feat(commands): /export and /doctor

/export renders the conversation as markdown to clipboard or file
(tool calls summarized, reminders stripped). /doctor one-screens the
install health: node version, auth + expiry, config/mcp JSON validity,
live MCP status, search keys, storage writability — so support requests
can start with a paste.

Author: halfaipg

src/commands/builtins/doctor.ts

@@ -0,0 +1,119 @@
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CredentialsStore } from "../../auth/credentials.js";
+import { VERSION } from "../../version.js";
+import type { Command } from "../types.js";
+
+/**
+ * /doctor — diagnose the install: runtime, credentials, config files,
+ * MCP servers, search keys, storage. Each check is one ✓/✗/– line so a
+ * support request can start with a paste of this output.
+ */
+export const doctor: Command = {
+	name: "doctor",
+	description: "Diagnose the installation: runtime, auth, config, MCP, storage.",
+	handler: (_args, ctx) => {
+		const lines: string[] = [`codebase ${VERSION} · doctor`];
+		const home = join(homedir(), ".codebase");
+
+		// Runtime
+		const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+		lines.push(check(major >= 20, `node ${process.versions.node}`, "node ≥ 20 required"));
+
+		// Credentials
+		const credStore = new CredentialsStore();
+		const creds = credStore.load();
+		if (!creds) {
+			lines.push(
+				info(
+					credStore.exists()
+						? "credentials file present but unreadable/invalid"
+						: "not signed in (env-key or BYOK mode)",
+				),
+			);
+		} else if (credStore.isExpired(creds)) {
+			lines.push(
+				check(
+					false,
+					"",
+					`credentials expired${creds.refreshToken ? " (will auto-refresh on next call)" : " — run codebase auth login"}`,
+				),
+			);
+		} else {
+			const until = creds.expiresAt ? ` until ${new Date(creds.expiresAt).toLocaleString()}` : "";
+			lines.push(check(true, `signed in (${creds.source})${until}`, ""));
+		}
+
+		// Model resolution for this session
+		lines.push(
+			check(
+				true,
+				`model: ${ctx.state.model.name} (${ctx.state.model.provider}/${ctx.state.model.id}) via ${ctx.bundle.source}`,
+				"",
+			),
+		);
+
+		// Config files parse
+		for (const path of [join(home, "config.json"), join(ctx.bundle.toolContext.cwd, ".codebase", "config.json")]) {
+			if (!existsSync(path)) continue;
+			lines.push(check(parses(path), `config ${path}`, `config ${path} is not valid JSON`));
+		}
+		for (const path of [join(home, "mcp.json"), join(ctx.bundle.toolContext.cwd, ".codebase", "mcp.json")]) {
+			if (!existsSync(path)) continue;
+			lines.push(check(parses(path), `mcp config ${path}`, `mcp config ${path} is not valid JSON`));
+		}
+
+		// MCP server status (live)
+		for (const s of ctx.bundle.mcp.status()) {
+			lines.push(check(s.connected, `mcp ${s.name}: ${s.toolCount} tools`, `mcp ${s.name}: ${s.error ?? "failed"}`));
+		}
+
+		// Web search keys
+		const hasSearch = Boolean(process.env.TAVILY_API_KEY || process.env.BRAVE_API_KEY || process.env.SEARXNG_URL);
+		lines.push(
+			hasSearch
+				? check(true, "web_search configured", "")
+				: info("web_search unconfigured — set TAVILY_API_KEY, BRAVE_API_KEY, or SEARXNG_URL to enable"),
+		);
+
+		// Storage writable
+		lines.push(
+			check(writable(home), `${home} writable`, `${home} is not writable — sessions/credentials can't persist`),
+		);
+
+		// Sessions + skills + agents on disk
+		lines.push(info(`sessions for this directory: ${ctx.bundle.sessions.list().length}`));
+		const subagents = ctx.bundle.toolContext.subagentTypes ?? [];
+		lines.push(info(`subagent types: ${subagents.map((t) => t.name).join(", ") || "none"}`));
+
+		ctx.emit(lines.join("\n"));
+		return { handled: true };
+	},
+};
+
+function check(ok: boolean, okText: string, failText: string): string {
+	return ok ? `  ✓ ${okText}` : `  ✗ ${failText}`;
+}
+
+function info(text: string): string {
+	return `  – ${text}`;
+}
+
+function parses(path: string): boolean {
+	try {
+		JSON.parse(readFileSync(path, "utf8"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function writable(dir: string): boolean {
+	try {
+		accessSync(dir, constants.W_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}

src/commands/builtins/export.ts

@@ -0,0 +1,105 @@
+import { writeFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { copyToClipboard } from "../../clipboard/copy.js";
+import type { Command } from "../types.js";
+
+/**
+ * /export — render the conversation as markdown. No args copies it to
+ * the clipboard; with a path it writes a file. Tool calls are summarized
+ * as one-liners; tool results are omitted (they're huge and rarely what
+ * a shared transcript needs).
+ */
+export const exportCmd: Command = {
+	name: "export",
+	description: "Export the conversation as markdown. /export = clipboard; /export <path> = file.",
+	handler: async (args, ctx) => {
+		if (ctx.state.messages.length === 0) {
+			ctx.emit("nothing to export — no messages yet.");
+			return { handled: true };
+		}
+		const markdown = renderTranscript(ctx.state.messages, ctx.state.model.name);
+
+		const target = args.trim();
+		if (target) {
+			const path = isAbsolute(target) ? target : resolve(ctx.bundle.toolContext.cwd, target);
+			try {
+				writeFileSync(path, markdown, "utf8");
+				ctx.emit(`exported ${ctx.state.messages.length} messages to ${path}`);
+			} catch (err) {
+				ctx.emit(`export failed: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			return { handled: true };
+		}
+
+		try {
+			const result = await copyToClipboard(markdown);
+			const note = result.truncated
+				? ` (truncated to ${result.bytes} bytes — use /export <path> for the full transcript)`
+				: "";
+			ctx.emit(`exported ${ctx.state.messages.length} messages to the clipboard via ${result.method}${note}.`);
+		} catch (err) {
+			ctx.emit(
+				`clipboard unavailable (${err instanceof Error ? err.message : String(err)}) — use /export <path> instead.`,
+			);
+		}
+		return { handled: true };
+	},
+};
+
+function renderTranscript(messages: readonly AgentMessage[], modelName: string): string {
+	const lines: string[] = [
+		`# codebase session`,
+		"",
+		`Model: ${modelName} · Exported: ${new Date().toISOString()}`,
+		"",
+	];
+	for (const m of messages) {
+		if (m.role === "user") {
+			const text = extractText(m.content);
+			if (!text) continue; // tool results / reminders aren't part of the dialogue
+			lines.push("## User", "", text, "");
+		} else if (m.role === "assistant") {
+			const text = extractText(m.content);
+			const calls = extractToolCalls(m.content);
+			if (!text && calls.length === 0) continue;
+			lines.push("## Assistant", "");
+			if (text) lines.push(text, "");
+			for (const c of calls) lines.push(`> 🔧 ${c}`);
+			if (calls.length > 0) lines.push("");
+		}
+	}
+	return lines.join("\n");
+}
+
+function extractText(content: AgentMessage["content"]): string {
+	if (typeof content === "string") {
+		return stripReminders(content);
+	}
+	if (!Array.isArray(content)) return "";
+	return stripReminders(
+		content
+			.filter(
+				(b): b is { type: "text"; text: string } =>
+					b.type === "text" && typeof (b as { text?: unknown }).text === "string",
+			)
+			.map((b) => b.text)
+			.join("\n"),
+	);
+}
+
+function extractToolCalls(content: AgentMessage["content"]): string[] {
+	if (!Array.isArray(content)) return [];
+	const out: string[] = [];
+	for (const block of content) {
+		if (block.type !== "toolCall") continue;
+		const call = block as { name?: string; arguments?: Record<string, unknown> };
+		const arg = call.arguments?.path ?? call.arguments?.command ?? call.arguments?.task ?? "";
+		out.push(`${call.name ?? "tool"}${arg ? ` — ${String(arg).slice(0, 80)}` : ""}`);
+	}
+	return out;
+}
+
+function stripReminders(text: string): string {
+	return text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, "").trim();
+}

src/commands/builtins/index.ts

@@ -3,6 +3,8 @@ import { agents } from "./agents.js";
 import { login, logout } from "./auth.js";
 import { copy } from "./copy.js";
 import { cost } from "./cost.js";
+import { doctor } from "./doctor.js";
+import { exportCmd } from "./export.js";
 import { context, debug, help, pwd, whoami } from "./info.js";
 import { init } from "./init.js";
 import { mcp } from "./mcp.js";
@@ -27,6 +29,8 @@ export const BUILTIN_COMMANDS: readonly Command[] = [
 	outputStyleCmd,
 	whoami,
 	copy,
+	exportCmd,
+	doctor,
 	diff,
 	commit,
 	review,