refactor(commands): split 732-LOC builtins.ts into per-category modules

No behavior change; this is the audit's J item — the monolith was the
worst seam in the codebase, holding 22 commands as one object literal
with no way to unit-test command logic in isolation. Split by topic:

  info.ts      help, whoami, pwd, debug, context
  session.ts   clear, fresh, compact, session, resume, redo, exit
  cost.ts      cost (+ padNum)
  model.ts     model, models (+ MODEL_ALIASES, parseModelSpec)
  copy.ts      copy (+ resolveCopyTarget helpers)
  scm.ts       diff, commit, review
  memory.ts    memory
  auth.ts      login, logout
  init.ts      init
  projects.ts  projects
  index.ts     re-exports BUILTIN_COMMANDS in original order

Every file under 150 LOC. Helpers colocated with the command that
uses them; no shared module needed. App.tsx import updated.
741 tests still pass.

Author: halfaipg

src/commands/builtins.ts

@@ -0,0 +1,33 @@
+import { CredentialsStore } from "../../auth/credentials.js";
+import type { Command } from "../types.js";
+
+// ─── auth / session ───────────────────────────────────────────────────
+
+export const login: Command = {
+	name: "login",
+	description: "Sign in via codebase.design OAuth (run from a fresh terminal: `codebase auth login`).",
+	handler: (_args, ctx) => {
+		ctx.emit(
+			"to sign in, exit (Ctrl-C) and run:\n  codebase auth login\n\n" +
+				"that opens your browser to codebase.design and persists tokens to ~/.codebase/credentials.json. " +
+				"after sign-in, restart codebase to use the new credentials.",
+		);
+		return { handled: true };
+	},
+};
+
+export const logout: Command = {
+	name: "logout",
+	description: "Clear saved credentials. Restart to take effect.",
+	mutates: true,
+	handler: (_args, ctx) => {
+		const store = new CredentialsStore();
+		const cleared = store.clear();
+		if (cleared) {
+			ctx.emit("cleared ~/.codebase/credentials.json. Restart codebase to use a different provider/sign-in.");
+		} else {
+			ctx.emit("no saved credentials to clear.");
+		}
+		return { handled: true };
+	},
+};

src/commands/builtins/auth.ts

@@ -0,0 +1,76 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { copyToClipboard, extractLastCodeBlock } from "../../clipboard/copy.js";
+import type { Command } from "../types.js";
+
+export const copy: Command = {
+	name: "copy",
+	description:
+		"Copy text to the system clipboard. /copy = last assistant message; /copy code = last code block; /copy <N> = message N.",
+	handler: async (args, ctx) => {
+		const messages = ctx.state.messages;
+		const target = resolveCopyTarget(args, messages);
+		if (target === null) {
+			ctx.emit("no assistant messages yet to copy.");
+			return { handled: true };
+		}
+		if (!target.text) {
+			ctx.emit("could not find text to copy. Try /copy, /copy code, or /copy <N>.");
+			return { handled: true };
+		}
+		try {
+			const result = await copyToClipboard(target.text);
+			const truncatedNote = result.truncated ? `, truncated to ${result.bytes}` : ` (${result.bytes} bytes)`;
+			ctx.emit(`copied ${target.label} via ${result.method}${truncatedNote}`);
+		} catch (err) {
+			ctx.emit(`/copy failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		return { handled: true };
+	},
+};
+
+interface CopyTarget {
+	text: string;
+	label: string;
+}
+
+function resolveCopyTarget(args: string, messages: readonly AgentMessage[]): CopyTarget | null {
+	const trimmed = args.trim().toLowerCase();
+	if (trimmed === "code") {
+		const last = lastAssistantText(messages);
+		if (!last) return null;
+		const block = extractLastCodeBlock(last);
+		if (!block) return { text: "", label: "" };
+		return { text: block, label: "last code block" };
+	}
+	if (/^\d+$/.test(trimmed)) {
+		const idx = Number.parseInt(trimmed, 10) - 1;
+		if (idx < 0 || idx >= messages.length) return { text: "", label: "" };
+		const msg = messages[idx];
+		const text = extractText(msg);
+		if (!text) return { text: "", label: "" };
+		return { text, label: `message ${idx + 1}` };
+	}
+	const last = lastAssistantText(messages);
+	if (!last) return null;
+	return { text: last, label: "last assistant message" };
+}
+
+function lastAssistantText(messages: readonly AgentMessage[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i];
+		if (m.role !== "assistant") continue;
+		const text = extractText(m);
+		if (text) return text;
+	}
+	return "";
+}
+
+function extractText(message: AgentMessage): string {
+	if (typeof message.content === "string") return message.content;
+	if (!Array.isArray(message.content)) return "";
+	const parts: string[] = [];
+	for (const block of message.content as Array<{ type: string; text?: string }>) {
+		if (block.type === "text" && typeof block.text === "string") parts.push(block.text);
+	}
+	return parts.join("");
+}

src/commands/builtins/copy.ts

@@ -0,0 +1,35 @@
+import type { Command } from "../types.js";
+
+export const cost: Command = {
+	name: "cost",
+	description: "Detailed token + cost breakdown for the current session, including cache hit rate.",
+	handler: (_args, ctx) => {
+		const { state, bundle } = ctx;
+		const u = state.usage;
+		const turns = state.messages.filter((m) => m.role === "assistant").length;
+		const promptTokens = u.input + u.cacheRead;
+		const hitRate = promptTokens > 0 ? `${((u.cacheRead / promptTokens) * 100).toFixed(0)}%` : "—";
+		const turnAvg = turns > 0 ? u.cost.total / turns : 0;
+		const proxyNote = bundle.source === "proxy" ? " (proxied via codebase.foundation)" : "";
+
+		const lines = [
+			`Session cost: $${u.cost.total.toFixed(4)}${proxyNote}`,
+			"",
+			"Tokens:",
+			`  Input         ${padNum(u.input, 8)} ($${u.cost.input.toFixed(4)})`,
+			`  Output        ${padNum(u.output, 8)} ($${u.cost.output.toFixed(4)})`,
+			`  Cache read    ${padNum(u.cacheRead, 8)} ($${u.cost.cacheRead.toFixed(4)})  ${hitRate} hit rate`,
+			`  Cache write   ${padNum(u.cacheWrite, 8)} ($${u.cost.cacheWrite.toFixed(4)})`,
+			"",
+			turns > 0
+				? `Turn average: $${turnAvg.toFixed(4)} (${turns} turn${turns === 1 ? "" : "s"})`
+				: "No assistant turns yet.",
+		];
+		ctx.emit(lines.join("\n"));
+		return { handled: true };
+	},
+};
+
+function padNum(n: number, width: number): string {
+	return n.toLocaleString().padStart(width, " ");
+}

src/commands/builtins/cost.ts

@@ -0,0 +1,38 @@
+import type { Command } from "../types.js";
+import { login, logout } from "./auth.js";
+import { copy } from "./copy.js";
+import { cost } from "./cost.js";
+import { context, debug, help, pwd, whoami } from "./info.js";
+import { init } from "./init.js";
+import { memory } from "./memory.js";
+import { modelCmd, modelsCmd } from "./model.js";
+import { projects } from "./projects.js";
+import { commit, diff, review } from "./scm.js";
+import { clear, compact, exit, fresh, redo, resume, session } from "./session.js";
+
+export const BUILTIN_COMMANDS: readonly Command[] = [
+	help,
+	clear,
+	fresh,
+	compact,
+	session,
+	cost,
+	modelCmd,
+	modelsCmd,
+	whoami,
+	copy,
+	diff,
+	commit,
+	review,
+	memory,
+	context,
+	login,
+	logout,
+	resume,
+	init,
+	projects,
+	pwd,
+	redo,
+	debug,
+	exit,
+];

src/commands/builtins/index.ts

@@ -0,0 +1,134 @@
+import { copyToClipboard } from "../../clipboard/copy.js";
+import type { Command } from "../types.js";
+
+export const help: Command = {
+	name: "help",
+	description: "List available slash commands and keyboard shortcuts.",
+	handler: (_args, ctx) => {
+		const lines: string[] = [];
+		lines.push("Keyboard shortcuts:");
+		lines.push("  /          slash-command autocomplete (Tab to complete, ↑↓ to choose)");
+		lines.push("  !cmd       run a shell command directly (e.g. !git status)");
+		lines.push("  @path      inline a file's contents into the next prompt");
+		lines.push("  ↑/↓        recall prior prompts (at line start)");
+		lines.push("  \\<Enter>   insert a newline instead of submitting");
+		lines.push("  Ctrl-C     cancel turn (busy) · twice to exit (idle)");
+		lines.push("");
+		lines.push("Slash commands:");
+		for (const cmd of ctx.registry.list()) {
+			const aliasPart = cmd.aliases?.length ? ` (${cmd.aliases.map((a) => `/${a}`).join(", ")})` : "";
+			lines.push(`  /${cmd.name}${aliasPart} — ${cmd.description}`);
+		}
+		ctx.emit(lines.join("\n"));
+		return { handled: true };
+	},
+};
+
+export const whoami: Command = {
+	name: "whoami",
+	aliases: ["status"],
+	description: "Show current sign-in status.",
+	handler: (_args, ctx) => {
+		const source = ctx.bundle.source;
+		ctx.emit(
+			source === "proxy"
+				? "signed in via codebase.foundation (inference proxy)"
+				: source === "explicit"
+					? "using model selected via CODEBASE_PROVIDER + CODEBASE_MODEL"
+					: "using auto-detected provider from env",
+		);
+		return { handled: true };
+	},
+};
+
+export const pwd: Command = {
+	name: "pwd",
+	aliases: ["cwd"],
+	description: "Print the current working directory and copy it to the clipboard.",
+	handler: async (_args, ctx) => {
+		const cwd = ctx.bundle.toolContext.cwd;
+		const copied = await copyToClipboard(cwd).catch(() => false);
+		ctx.emit(copied ? `${cwd}\n(copied to clipboard)` : cwd);
+		return { handled: true };
+	},
+};
+
+/**
+ * Diagnostic for "the model isn't remembering what I told it earlier."
+ * Compares the UI's display state (what the user sees in the transcript)
+ * with the agent's internal _state.messages (what actually ships to the
+ * model on the next turn). If those diverge, that's the bug. If they
+ * match but the model still acts amnesiac, the issue is in the wire
+ * call — pi-ai's openai-completions builder, the proxy, or the upstream.
+ */
+export const debug: Command = {
+	name: "debug",
+	description: "Inspect internal agent state — message count, token estimate, last few roles.",
+	handler: (_args, ctx) => {
+		const display = ctx.state.messages;
+		const internal = ctx.bundle.agent.state.messages;
+		const rolesTail = (msgs: readonly { role: string }[], n: number) =>
+			msgs
+				.slice(-n)
+				.map((m) => m.role)
+				.join(" → ") || "(empty)";
+		const u = ctx.state.usage;
+		const used = u.input + u.cacheRead;
+		const compactAt = ctx.bundle.compaction.threshold();
+		const divergent = display.length !== internal.length;
+		const lines = [
+			"Internal state inspection:",
+			"",
+			`  Display messages (UI):     ${display.length}`,
+			`  Agent state messages:      ${internal.length}${divergent ? "  ← MISMATCH!" : ""}`,
+			"",
+			`  Last 5 display roles:      ${rolesTail(display, 5)}`,
+			`  Last 5 agent state roles:  ${rolesTail(internal, 5)}`,
+			"",
+			`  Estimated tokens used:     ${used.toLocaleString()}`,
+			`  Compaction triggers at:    ${compactAt.toLocaleString()}`,
+			`  Streaming in progress:     ${ctx.state.streaming ? "yes" : "no"}`,
+			"",
+			divergent
+				? "Mismatch means the agent and the UI disagree about what's been said. " +
+					"That's the source of 'the model forgot' — the next turn ships internal " +
+					"messages, not display messages. Report this with a `codebase --debug-input` " +
+					"transcript so we can see how it happened."
+				: "Display and agent state match. If the model is still acting amnesiac, the " +
+					"context is leaving the CLI correctly but something on the wire is dropping " +
+					"it — capture with OPENAI_LOG=debug codebase to see the raw HTTP request body.",
+		];
+		ctx.emit(lines.join("\n"));
+		return { handled: true };
+	},
+};
+
+export const context: Command = {
+	name: "context",
+	description: "Visualize how full the context window is right now.",
+	handler: (_args, ctx) => {
+		const u = ctx.state.usage;
+		const used = u.input + u.cacheRead;
+		// Anthropic Claude Sonnet 4.x is 200K input by default; Opus is 200K too.
+		// pi-ai's model.contextLength would be the source of truth; for now use
+		// 200K as the floor and clamp.
+		const window = (ctx.state.model as { contextLength?: number }).contextLength ?? 200_000;
+		const ratio = Math.min(1, used / window);
+		const compactAt = ctx.bundle.compaction.threshold();
+		const barWidth = 40;
+		const filled = Math.round(ratio * barWidth);
+		const compactMark = Math.round((compactAt / window) * barWidth);
+		let bar = "";
+		for (let i = 0; i < barWidth; i++) {
+			if (i < filled) bar += "█";
+			else if (i === compactMark) bar += "│";
+			else bar += "░";
+		}
+		const pct = `${(ratio * 100).toFixed(1)}%`;
+		const compactPct = `${((compactAt / window) * 100).toFixed(0)}%`;
+		ctx.emit(
+			`context window:\n  ${bar}\n  ${used.toLocaleString()} / ${window.toLocaleString()} tokens (${pct})\n  │ = compaction triggers at ${compactAt.toLocaleString()} (${compactPct})`,
+		);
+		return { handled: true };
+	},
+};

src/commands/builtins/info.ts

@@ -0,0 +1,48 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Command } from "../types.js";
+
+// ─── project + extensions ─────────────────────────────────────────────
+
+export const init: Command = {
+	name: "init",
+	description: "Drop a starter CLAUDE.md at the project root with instructions for the agent.",
+	mutates: true,
+	handler: (_args, ctx) => {
+		const cwd = ctx.bundle.toolContext.cwd;
+		const target = join(cwd, "CLAUDE.md");
+		if (existsSync(target)) {
+			ctx.emit(`CLAUDE.md already exists at ${target}. Edit it directly; it's auto-injected on session start.`);
+			return { handled: true };
+		}
+		const template = [
+			"# Project Instructions",
+			"",
+			"This file is auto-loaded by `codebase` on session start.",
+			"Use it to capture project-specific rules and context the agent should follow.",
+			"",
+			"## What this project is",
+			"",
+			"Replace this with a one-paragraph summary of what the codebase does, the",
+			"primary language(s), and the user-visible product.",
+			"",
+			"## Commands",
+			"",
+			"- Build:  `…`",
+			"- Test:   `…`",
+			"- Lint:   `…`",
+			"",
+			"## Coding conventions",
+			"",
+			"- …",
+			"",
+			"## Don'ts",
+			"",
+			"- …",
+			"",
+		].join("\n");
+		writeFileSync(target, template);
+		ctx.emit(`wrote ${target}. Edit it to capture project-specific guidance for the agent.`);
+		return { handled: true };
+	},
+};

src/commands/builtins/init.ts

@@ -0,0 +1,17 @@
+import type { Command } from "../types.js";
+
+// ─── memory + context ─────────────────────────────────────────────────
+
+export const memory: Command = {
+	name: "memory",
+	description: "Show the MEMORY.md index of saved cross-session memories for this project.",
+	handler: (_args, ctx) => {
+		const index = ctx.bundle.memory.index();
+		if (!index.trim()) {
+			ctx.emit("no memories saved yet. The agent can write them via the save_memory tool.");
+			return { handled: true };
+		}
+		ctx.emit(index);
+		return { handled: true };
+	},
+};