rovecode 0.3.2

package/src/cli/doctor.ts

@@ -0,0 +1,362 @@
+/** `rovecode doctor` — "what is wrong with my setup", answered once, in one pass.
+ *
+ *  Every check here already existed and already spoke — each at its own moment: the LSP note at boot, the
+ *  provider hint when a run fails, the prerequisite row inside an install plan, the MCP loader's skipped-server
+ *  warnings, the trust gate's line. A person whose setup is half-wrong met them one at a time, in the order
+ *  the day happened to raise them. This runs the same code and lays the answers side by side.
+ *
+ *  Rules it keeps:
+ *  - It invents nothing. Every row is produced by the module that owns that decision (providers/registry.ts,
+ *    mcp/config.ts, mcp/market-install.ts, coding/lsp.ts, market/prereq.ts, core/settings.ts). A check that
+ *    would need code this repository does not have is listed under `notChecked`, by name.
+ *  - It never prints a secret. Provider rows carry ids, scopes and key NAMES; the registry's own redaction is
+ *    not even consulted, because nothing here needs the value.
+ *  - It makes no provider request: reachability would be a billed call, so it is a listed non-check. MCP
+ *    servers ARE connected (that is a local process, and "does it connect" is the question); `--no-connect`
+ *    skips it and says so.
+ *  - Exit 0 = nothing is broken; 1 = something the person must fix before a run can work as configured. A
+ *    fresh install with no provider is a FINDING (exit 0, status "note"), not a failure — nothing is broken,
+ *    something is not done yet. `--json` is one document, on every exit. */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { rovecodeHome } from "../providers/auth.ts";
+import { ProviderRegistry } from "../providers/registry.ts";
+import { isConfigured } from "../providers/provider-config.ts";
+import { resolvePermission, settingsPath } from "../core/settings.ts";
+import type { PermissionLevel } from "../core/types.ts";
+import { checkPrereq, type PrereqEnv } from "../market/prereq.ts";
+import { lspAvailabilityNote } from "../coding/lsp.ts";
+import { WorkspaceRoots, resolveRoots } from "../core/workspace.ts";
+import { parseAddDirs } from "./run-flags.ts";
+import { configuredServers } from "../mcp/market-install.ts";
+import { loadMcpConfig, placeholderHoles, type McpServerConfig } from "../mcp/config.ts";
+import { mcpTrustStatus, trustedPredicate } from "../mcp/trust.ts";
+import { projectTrustRows, trustShowLines, untrustedRows } from "../core/project-trust.ts";
+import { loadState as loadPluginState } from "../plugins/state.ts";
+import { launchesViaNpx, npxOfferLine } from "../mcp/local-package.ts";
+import { resolveVerify, VERIFY_BLIND_SPOT, verifyLabelWithCost } from "../core/verify.ts";
+
+export type DoctorStatus = "ok" | "note" | "warn" | "fail";
+
+export interface DoctorCheck {
+  id: "home" | "provider" | "permission" | "trust" | "tools" | "verify" | "mcp" | "workspace" | "checkpoints";
+  status: DoctorStatus;
+  summary: string;
+  detail?: string[];
+}
+
+export interface DoctorReport {
+  ok: boolean;
+  exitCode: 0 | 1;
+  cwd: string;
+  home: string;
+  checks: DoctorCheck[];
+  /** what this command did NOT look at, by name — so a clean report is never read as "everything is fine" */
+  notChecked: string[];
+}
+
+export interface DoctorDeps {
+  cwd?: string;
+  /** the rovecode home; default rovecodeHome() (ROVECODE_HOME or ~/.rovecode) */
+  home?: string;
+  env?: Record<string, string | undefined>;
+  /** PATH lookup for the tools row — tests inject a fixed environment */
+  prereqEnv?: PrereqEnv;
+  /** the LSP probe — tests inject; default Bun.which */
+  which?: (name: string) => string | null;
+  /** try to connect every loadable MCP server (default true; `--no-connect` turns it off) */
+  connect?: boolean;
+  connectTimeoutMs?: number;
+  out?: (line: string) => void;
+  err?: (line: string) => void;
+  /** `--add-dir <dir>` values (absolute; cli/run-flags.ts parseAddDirs) — doctor is its own process, so it can only
+   *  describe roots it is told about; the row then names what a session with those roots would and would not cover */
+  addDirs?: readonly string[];
+}
+
+const DOCTOR_USAGE = [
+  "usage: rovecode doctor [--json] [--no-connect] [--add-dir <dir>]…",
+  "  one pass over the setup: home · provider · permission level · tools on PATH · the verify check · MCP servers · workspace roots (with --add-dir) · checkpoints",
+  "  --no-connect   do not start the MCP servers to see whether they answer (they are otherwise connected and closed)",
+  "  --json         one document on stdout; exit 0 = nothing broken, 1 = something to fix (a missing provider is a note, not a failure)",
+];
+
+const PERMISSIONS: readonly string[] = ["ask", "accept-edits", "auto"];
+/** the size at which a shadow repository becomes worth mentioning: 14e9118 measured 232 MB as the bad case */
+const CHECKPOINTS_WARN_BYTES = 200 * 1024 * 1024;
+
+function userHome(env: Record<string, string | undefined>): string {
+  return (process.platform === "win32" ? env.USERPROFILE : env.HOME) || homedir();
+}
+
+function dirSize(root: string): { bytes: number; files: number } {
+  let bytes = 0, files = 0;
+  const walk = (d: string): void => {
+    let names: string[];
+    try { names = readdirSync(d); } catch { return; }
+    for (const n of names) {
+      const p = join(d, n);
+      try {
+        const st = statSync(p);
+        if (st.isDirectory()) walk(p); else { bytes += st.size; files++; }
+      } catch { /* vanished mid-walk: the number is a snapshot, not a ledger */ }
+    }
+  };
+  walk(root);
+  return { bytes, files };
+}
+
+const mb = (bytes: number): string => `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+
+/** the permission level in effect and WHERE it came from — the same ladder core/settings.ts resolvePermission
+ *  walks, re-read here only to name the rung; the level itself is resolvePermission's answer */
+function permissionCheck(cwd: string, env: Record<string, string | undefined>): DoctorCheck {
+  const level = resolvePermission(cwd, undefined, { ROVECODE_PERMISSION: env.ROVECODE_PERMISSION, ROVECODE_YOLO: env.ROVECODE_YOLO, ROVECODE_ACCEPT_EDITS: env.ROVECODE_ACCEPT_EDITS });
+  const fileLevel = (scope: "user" | "project"): PermissionLevel | undefined => {
+    try {
+      const raw = JSON.parse(readFileSync(settingsPath(scope, cwd), "utf8")) as { permission?: unknown };
+      return typeof raw.permission === "string" && PERMISSIONS.includes(raw.permission) ? raw.permission as PermissionLevel : undefined;
+    } catch { return undefined; }
+  };
+  const named = (env.ROVECODE_PERMISSION ?? "").trim().toLowerCase();
+  const source = PERMISSIONS.includes(named) ? "ROVECODE_PERMISSION"
+    : env.ROVECODE_YOLO === "1" ? "ROVECODE_YOLO=1"
+    : env.ROVECODE_ACCEPT_EDITS === "1" ? "ROVECODE_ACCEPT_EDITS=1"
+    : fileLevel("project") !== undefined ? settingsPath("project", cwd)
+    : fileLevel("user") !== undefined ? settingsPath("user", cwd)
+    : "the default";
+  const words = level === "auto" ? "auto — never asks (deny rules and plan mode still hold)"
+    : level === "accept-edits" ? "accept edits — writes inside this folder do not ask; shell, subagents, network and writes outside it do"
+    : "ask first — every write, shell command and subagent asks";
+  return { id: "permission", status: level === "auto" ? "note" : "ok", summary: `${words} · from ${source}`,
+    ...(level === "auto" ? { detail: ["a one-shot run adds --yolo per run; the TUI's /yolo --save is what made it stick if this surprises you"] } : {}) };
+}
+
+export async function runDoctor(deps: DoctorDeps = {}): Promise<DoctorReport> {
+  const cwd = deps.cwd ?? process.cwd();
+  const env = deps.env ?? process.env;
+  const home = deps.home ?? rovecodeHome();
+  const which = deps.which ?? ((n: string) => Bun.which(n));
+  const checks: DoctorCheck[] = [];
+  const notChecked: string[] = [
+    "whether the provider answers — a request would be billed; `rovecode provider test <id>` makes one small call on purpose",
+    "plugins — `rovecode plugin list` shows each one's state",
+    "the bash sandbox rung (wsl/docker) — probed at session start, not here",
+    "hooks — loaded at session start; a broken one is reported there",
+  ];
+
+  // ---- home
+  {
+    const explicit = env.ROVECODE_HOME !== undefined;
+    const legacy = join(userHome(env), ".cumulus");
+    const legacyThere = existsSync(legacy);
+    const detail: string[] = [];
+    if (legacyThere) detail.push(explicit
+      ? `a legacy ${legacy} is still on this machine; an explicit ROVECODE_HOME is never filled from it (only the default home inherits, once, and says so)`
+      : `a legacy ${legacy} is still on this machine; the default home was copied from it once and both are kept — delete the old one when you are sure`);
+    checks.push({ id: "home", status: existsSync(home) ? "ok" : "note",
+      summary: `${home}${explicit ? " (ROVECODE_HOME)" : ""}${existsSync(home) ? "" : " — does not exist yet; the first thing you store creates it"}`,
+      ...(detail.length ? { detail } : {}) });
+  }
+
+  // ---- provider (ids, scopes and key NAMES only — never a value)
+  {
+    const reg = new ProviderRegistry(cwd, { env });
+    const def = reg.defaultRef();
+    const configured = reg.list().filter(isConfigured);
+    const warnings = reg.warnings();
+    const detail = configured.map((p) => `${p.id} (${p.scope}${p.noKey ? ", no key needed" : `, key from ${p.keySource === "env" ? `env ${p.keyEnv}` : p.keySource}`})`);
+    for (const w of warnings) detail.push(`providers.json: ${w}`);
+    if (def === null) {
+      checks.push({ id: "provider", status: warnings.length ? "warn" : "note",
+        summary: "no provider configured yet — nothing is broken, nothing is connected: `rovecode connect` (or provider add + auth set)", ...(detail.length ? { detail } : {}) });
+    } else {
+      checks.push({ id: "provider", status: warnings.length ? "warn" : "ok",
+        summary: `default ${def.provider}/${def.model || "(no model — rovecode model use <provider/model>)"} · ${configured.length} provider${configured.length === 1 ? "" : "s"} configured`, ...(detail.length ? { detail } : {}) });
+    }
+  }
+
+  // ---- permission
+  checks.push(permissionCheck(cwd, env));
+
+  // ---- trust: the project files that could make rovecode run or import something (core/trust.ts), each with what it
+  // carries — an untrusted one contributes nothing until `rovecode trust`. A repo with none is a repo with none.
+  {
+    const rows = projectTrustRows(cwd, home);
+    const off = untrustedRows(rows);
+    const detail = trustShowLines(rows);
+    const summary = rows.length === 0 ? "no gated project files here"
+      : off.length === 0 ? `${rows.length} gated project file${rows.length === 1 ? "" : "s"}, all trusted on this machine`
+      : `${off.length} of ${rows.length} gated project file${rows.length === 1 ? "" : "s"} NOT trusted — contributing nothing until \`rovecode trust\` (read \`rovecode trust show\` first)`;
+    checks.push({ id: "trust", status: off.length ? "note" : "ok", summary, ...(rows.length ? { detail } : {}) });
+  }
+
+  // ---- MCP: what the files say, what the loader takes, what actually answers
+  const parseWarnings: string[] = [];
+  const rows = configuredServers(cwd, home, parseWarnings);
+  const loadWarnings: string[] = [];
+  const loaded = loadMcpConfig(cwd, loadWarnings, { home, env, trusted: trustedPredicate(loadPluginState(home)) });
+  const needsNpx = rows.some((r) => r.server.transport === "stdio" && /^npx(\.cmd)?$/i.test(r.server.command ?? ""));
+  const needsUvx = rows.some((r) => r.server.transport === "stdio" && /^uvx(\.exe)?$/i.test(r.server.command ?? ""));
+  {
+    const detail: string[] = [];
+    let status: DoctorStatus = "ok";
+    const raise = (s: DoctorStatus): void => { const rank = { ok: 0, note: 1, warn: 2, fail: 3 }; if (rank[s] > rank[status]) status = s; };
+    for (const w of parseWarnings) { detail.push(`✗ ${w}`); raise("fail"); }
+    const loadedNames = new Set(loaded.map((c) => c.name));
+    let connected = new Set<string>(); const failed = new Map<string, string>();
+    if (deps.connect !== false && loaded.length > 0) {
+      const { McpManager } = await import("../mcp/client.ts");
+      const mgr = new McpManager(loaded, deps.connectTimeoutMs !== undefined ? { connectTimeoutMs: deps.connectTimeoutMs } : {});
+      const r = await mgr.connect();
+      connected = new Set(r.connected);
+      for (const f of r.failed) failed.set(f.name, f.error);
+      await mgr.close().catch(() => {});
+    } else if (deps.connect === false && loaded.length > 0) {
+      notChecked.push("whether the MCP servers answer (--no-connect)");
+    }
+    for (const row of rows) {
+      const s: McpServerConfig = row.server;
+      const where = `${row.scope}${row.scope === "user" ? "" : ` ${row.file}`}`;
+      const trust = row.scope === "user" ? "trusted" : mcpTrustStatus(home, row.file);
+      const holes = placeholderHoles(s);
+      const skipped = loadWarnings.find((w) => w.includes(`server "${s.name}"`));
+      if (s.enabled === false) { detail.push(`· ${s.name} — disabled in ${where}`); continue; }
+      if (trust !== "trusted") { detail.push(`· ${s.name} — off: its file is not trusted on this machine (${row.file}) — rovecode mcp show, then rovecode mcp trust`); raise("note"); continue; }
+      if (holes.length) { detail.push(`! ${s.name} — skipped: still has ${holes.join(", ")} to fill in — edit the args in ${row.file}`); raise("warn"); continue; }
+      if (skipped !== undefined && !loadedNames.has(s.name)) { detail.push(`! ${s.name} — skipped: ${skipped.replace(/^.*?server "[^"]+" /, "")}`); raise("warn"); continue; }
+      if (!loadedNames.has(s.name)) { detail.push(`! ${s.name} — not loaded (${where})`); raise("warn"); continue; }
+      if (failed.has(s.name)) { detail.push(`✗ ${s.name} — did not connect: ${failed.get(s.name)}`); raise("fail"); continue; }
+      if (connected.has(s.name)) { detail.push(`✓ ${s.name} — connected (${where})`); continue; }
+      detail.push(`· ${s.name} — loads (${where}); not connected in this pass`);
+    }
+    const npx = rows.filter((r) => launchesViaNpx(r.server) && loadedNames.has(r.server.name)).map((r) => r.server.name);
+    const offer = npxOfferLine(npx);
+    if (offer !== undefined) detail.push(offer);
+    // "load" = would start: a disabled entry is kept by the loader (so `mcp list` can show it) but never launched
+    const starting = loaded.filter((c) => c.enabled !== false).length;
+    const summary = rows.length === 0 ? "no MCP servers configured — rovecode mcp search <query>"
+      : `${rows.length} configured · ${starting} load${deps.connect === false ? "" : ` · ${connected.size} connected · ${failed.size} failed`}`;
+    checks.push({ id: "mcp", status, summary, ...(detail.length ? { detail } : {}) });
+  }
+
+  // ---- tools on PATH: what an install plan would say, all at once — and what each absence costs HERE
+  {
+    const detail: string[] = [];
+    let status: DoctorStatus = "ok";
+    const raise = (s: DoctorStatus): void => { const rank = { ok: 0, note: 1, warn: 2, fail: 3 }; if (rank[s] > rank[status]) status = s; };
+    const want: { program: string; needed: boolean; why?: string }[] = [
+      { program: "git", needed: true, why: "checkpoints (undo without touching your repo) and plugin/skill installs need it" },
+      { program: "node", needed: needsNpx, why: "an MCP server here starts through npx" },
+      { program: "npm", needed: needsNpx, why: "an MCP server here starts through npx (install-once uses npm)" },
+      { program: "npx", needed: needsNpx, why: "an MCP server here starts through npx" },
+      { program: "uvx", needed: needsUvx, why: "an MCP server here starts through uvx" },
+    ];
+    for (const w of want) {
+      const p = checkPrereq(w.program, deps.prereqEnv ?? {});
+      if (p.found) { detail.push(`✓ ${w.program}`); continue; }
+      const cost = w.needed ? ` — ${w.why}` : ` — nothing configured here needs it${w.program === "git" ? "" : " yet"}`;
+      detail.push(`${w.needed ? "✗" : "·"} ${w.program} not on PATH${cost}${p.hint ? ` (${p.hint})` : ""}`);
+      raise(w.needed ? (w.program === "git" ? "warn" : "fail") : "note");
+    }
+    const lsp = lspAvailabilityNote(cwd, which);
+    if (lsp !== null) { detail.push(`! ${lsp.replace(/^lsp: /, "")}`); raise("warn"); }
+    else if (existsSync(join(cwd, "tsconfig.json"))) detail.push("✓ typescript-language-server — edits and writes come back with diagnostics");
+    else detail.push("· typescript-language-server — not a TypeScript project here (no tsconfig.json), so the gate does not apply");
+    checks.push({ id: "tools", status, summary: detail.filter((l) => l.startsWith("✓")).length + " of " + detail.length + " present", detail });
+  }
+
+  // ---- verify: the check the loop runs before "done" (core/verify.ts) — the same kind of fact as `tools` and
+  // `permission`: what this project WOULD run, or that nothing is configured and why nothing was inferred. Never a
+  // failure: a project with no gate is a project with no gate. The refusals are the row's detail on purpose — that
+  // list is how a person decides, once, whether to turn the gate on with the `verify` key.
+  {
+    const plan = resolveVerify(cwd);
+    const summary = plan.source === "settings" ? `${verifyLabelWithCost(cwd, plan)} · from ${plan.reason}`
+      : plan.source === "inferred" ? `${verifyLabelWithCost(cwd, plan)} · ${plan.reason} — set \`verify\` in .rovecode/settings.json to pin or replace it`
+      : `none · ${plan.reason}`;
+    const detail = plan.refused.map((r) => `not inferred: ${r}`);
+    if (plan.commands.length > 0) detail.push(VERIFY_BLIND_SPOT);
+    checks.push({ id: "verify", status: plan.source === "settings" ? "ok" : "note", summary, ...(detail.length ? { detail } : {}) });
+  }
+
+  // ---- workspace: the roots a session started with `--add-dir` would have, and the limit that comes with them
+  if (deps.addDirs !== undefined && deps.addDirs.length > 0) {
+    try {
+      const roots = new WorkspaceRoots(cwd, resolveRoots(cwd, deps.addDirs));
+      const detail = [...roots.notes, ...(roots.dirs.length > 0 ? [roots.checkpointNote(), "the boundary covers the file tools (read, edit, write, glob, grep, ls); bash is judged as a command, not a path"] : [])];
+      checks.push({ id: "workspace", status: roots.dirs.length > 0 ? "note" : "ok",
+        summary: roots.dirs.length > 0 ? `${cwd} ${roots.describe()} — ${roots.dirs.length} extra root${roots.dirs.length === 1 ? "" : "s"}` : `${cwd} — every --add-dir value was already inside it`,
+        ...(detail.length ? { detail } : {}) });
+    } catch (e) {
+      checks.push({ id: "workspace", status: "fail", summary: e instanceof Error ? e.message : String(e) });
+    }
+  }
+
+  // ---- checkpoints: the shadow repositories under this workspace
+  {
+    const root = join(cwd, ".rovecode", "checkpoints");
+    if (!existsSync(root)) checks.push({ id: "checkpoints", status: "ok", summary: "no shadow repository here yet (the first change of a session creates one)" });
+    else {
+      let sessions = 0; try { sessions = readdirSync(root).length; } catch { /* unreadable: size says 0 */ }
+      const { bytes, files } = dirSize(root);
+      const big = bytes >= CHECKPOINTS_WARN_BYTES;
+      checks.push({ id: "checkpoints", status: big ? "warn" : "ok",
+        summary: `${sessions} session${sessions === 1 ? "" : "s"} · ${mb(bytes)} in ${files} files under .rovecode/checkpoints`,
+        ...(big ? { detail: [
+          "that is large: something big under this folder is being snapshotted before every change (untracked files are included; media, archives and binaries are excluded by pattern, other large files are not)",
+          "delete .rovecode/checkpoints to reclaim it — nothing of yours lives there — or ROVECODE_NO_CHECKPOINTS=1 turns snapshots off",
+        ] } : {}) });
+      notChecked.push("which files the NEXT snapshot would hash — there is no dry run for that");
+    }
+  }
+
+  const exitCode = checks.some((c) => c.status === "fail") ? 1 : 0;
+  return { ok: exitCode === 0, exitCode, cwd, home, checks, notChecked };
+}
+
+const MARK: Record<DoctorStatus, string> = { ok: "✓", note: "·", warn: "!", fail: "✗" };
+
+export function renderDoctor(r: DoctorReport): string[] {
+  const lines: string[] = [];
+  for (const c of r.checks) {
+    lines.push(`${MARK[c.status]} ${c.id.padEnd(12)} ${c.summary}`);
+    for (const d of c.detail ?? []) lines.push(`               ${d}`);
+  }
+  lines.push("");
+  lines.push("not checked:");
+  for (const n of r.notChecked) lines.push(`  - ${n}`);
+  lines.push("");
+  lines.push(r.exitCode === 0
+    ? (r.checks.some((c) => c.status === "warn" || c.status === "note") ? "nothing is broken; the lines marked ! and · are things to know or finish" : "everything checked is in order")
+    : "something is broken — the lines marked ✗ say what");
+  return lines;
+}
+
+/** `rovecode doctor [--json] [--no-connect]` — exit 0 nothing broken · 1 something to fix · 2 usage */
+export async function cmdDoctor(args: string[], deps: DoctorDeps = {}): Promise<number> {
+  const out = deps.out ?? ((l: string) => console.log(l));
+  const err = deps.err ?? ((l: string) => console.error(l));
+  const json = args.includes("--json");
+  // --add-dir: validated exactly as a session would (a bad value is the same one-line usage error, exit 2)
+  let addDirs: string[] | undefined;
+  try { addDirs = parseAddDirs(["", "", ...args], (msg) => { throw new Error(msg); }); }
+  catch (e) { const msg = e instanceof Error ? e.message : String(e); err(msg); if (json) out(JSON.stringify({ ok: false, error: msg, usage: DOCTOR_USAGE }, null, 2)); return 2; }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--add-dir") { i++; continue; }
+    if (a.startsWith("--add-dir=")) continue;
+    if (!a.startsWith("-")) continue;
+    if (a === "--json" || a === "--no-connect") continue;
+    const msg = `unknown flag ${a}`;
+    err(msg); err(DOCTOR_USAGE.join("\n"));
+    if (json) out(JSON.stringify({ ok: false, error: msg, usage: DOCTOR_USAGE }, null, 2));
+    return 2;
+  }
+  const report = await runDoctor({ ...deps, ...(args.includes("--no-connect") ? { connect: false } : {}), ...(addDirs.length > 0 ? { addDirs } : {}) });
+  if (json) out(JSON.stringify(report, null, 2));
+  else for (const l of renderDoctor(report)) out(l);
+  return report.exitCode;
+}

package/src/cli/export.ts

@@ -0,0 +1,276 @@
+/** Port #38: session export — markdown transcript or raw JSONL copy, LOCAL only.
+ *  Pattern: opencode cli/cmd/export.ts @ ebece6e (MIT) — session resolution → serialize;
+ *  their export emits the raw session data verbatim to stdout, which maps to --json here
+ *  (verbatim byte copy of entries.jsonl, the whole tree incl. abandoned branches). The
+ *  cloud-share half of opencode's feature (share/session.ts) is explicitly deferred
+ *  (PORTS.md wave-3 ledger: "export stays local"), and the markdown layout is rovecode-native:
+ *  the snapshot has no session→markdown renderer at ebece6e.
+ *
+ *  Markdown walks the ACTIVE path only (store.path()), mirroring TUI replayHistory:
+ *  user/assistant text, tool cards (args one-liner, bounded output, ok/ERROR badge),
+ *  mode switches as "mode → plan" lines (wave-2 replay convention, never raw
+ *  <mode_notice> XML), compaction markers, and a costs section over per-origin usage
+ *  totals + buildCostNote. Output is deterministic: every timestamp comes from the
+ *  entries themselves (ISO UTC), there is no "generated at" wall-clock line, and the
+ *  catalog is the offline snapshot (lookup() never fetches). */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import { SessionStore, type Entry } from "../core/session.ts";
+import { describeBadSessionId } from "../core/session-id.ts";
+import { resolveSession } from "../core/session-ops.ts";
+import { modeSwitchOf } from "../core/modes.ts";
+import { ModelCatalog } from "../providers/catalog.ts";
+import { buildCostNote } from "../tui/cost.ts";
+import { describeImage } from "../core/images.ts";
+import type { ImagePart, Message, ToolCallPart, ToolResultPart } from "../core/types.ts";
+
+/** Tool output cap (chars) per card. Clipped output gets an explicit marker line. */
+export const TOOL_OUTPUT_CAP = 2000;
+/** One-line args summary cap — same 120-char clip the TUI uses for tool cards. */
+const ARGS_CAP = 120;
+/** CLI usage line — thrown on a missing id or a dangling --out; cmdExport turns it into exit 2, the
+ *  usage/startup class README documents, while a real export failure stays exit 1. */
+const USAGE = "usage: rovecode export <session-id|prefix> [--json] [--out <path>] [--force]";
+
+export interface ExportOptions {
+  /** raw JSONL copy (verbatim bytes) instead of markdown */
+  json?: boolean;
+  /** target path; default ./<sessionId-short>.(md|jsonl) under cwd */
+  out?: string;
+  /** overwrite an existing target file */
+  force?: boolean;
+  /** base dir for relative/default output paths; default process.cwd() */
+  cwd?: string;
+}
+
+export interface ExportResult { path: string; format: "markdown" | "jsonl" }
+
+// ---------- session-prefix resolution: the ONE rule (core/session-ops.ts resolveSession — shared with /resume,
+// `--resume`, `trace` and the `sessions` verbs; this file used to carry its own copy) ----------
+
+/** Exact id wins outright; a prefix must match exactly ONE session; an ambiguous prefix lists candidates instead
+ *  of silently picking one. An id that is not a plain directory name is refused on export's own usage path
+ *  before any listing (`../x` never reaches a path join). */
+export function resolveSessionId(sessionsRoot: string, idOrPrefix: string): string {
+  const bad = describeBadSessionId(idOrPrefix);
+  if (bad !== undefined) throw new Error(`${bad} — ${USAGE}`);
+  const r = resolveSession(sessionsRoot, idOrPrefix);
+  if (!r.ok) throw new Error(r.error);
+  return r.id;
+}
+
+// ---------- markdown rendering ----------
+
+function isMessage(e: Entry): e is Message { return "role" in e; }
+
+/** Longest backtick run in s (0 when none) — a CommonMark span/fence must be longer. */
+function tickRun(s: string): number {
+  let run = 0;
+  for (const m of s.matchAll(/`+/g)) run = Math.max(run, m[0].length);
+  return run;
+}
+
+/** Inline-code span that survives backticks in the content (args may contain them):
+ *  delimiter = longest run + 1 (a fixed `` closes at the first inner double tick),
+ *  space-padded so a leading/trailing tick stays inside the span. */
+function inlineCode(s: string): string {
+  const run = tickRun(s);
+  if (run === 0) return `\`${s}\``;
+  const tick = "`".repeat(run + 1);
+  return `${tick} ${s} ${tick}`;
+}
+
+/** Fenced block whose fence is longer than any backtick run in the content. */
+function fenced(content: string): string {
+  const fence = "`".repeat(Math.max(3, tickRun(content) + 1));
+  return `${fence}\n${content}\n${fence}`;
+}
+
+/** One tool card: name + badge header, one-line args, bounded output block. */
+function toolCard(tool: string, args: unknown, res: ToolResultPart | undefined): string {
+  const badge = res === undefined ? "no result recorded" : res.ok ? "ok" : "ERROR";
+  const argsLine = JSON.stringify(args) ?? "undefined";
+  const argsShown = argsLine.length > ARGS_CAP ? argsLine.slice(0, ARGS_CAP) + "…" : argsLine;
+  const parts = [`### tool: ${tool} — ${badge}`, `args: ${inlineCode(argsShown)}`];
+  if (res !== undefined) {
+    if (res.output.length === 0) parts.push("*(no output)*");
+    else {
+      const clipped = res.output.length > TOOL_OUTPUT_CAP;
+      parts.push(fenced(clipped ? res.output.slice(0, TOOL_OUTPUT_CAP) : res.output));
+      if (clipped) parts.push(`*+${res.output.length - TOOL_OUTPUT_CAP} chars clipped (cap ${TOOL_OUTPUT_CAP})*`);
+    }
+  }
+  return parts.join("\n\n");
+}
+
+function textOf(m: Message): string {
+  return m.parts.filter((p) => p.kind === "text").map((p) => (p as { text: string }).text).join("");
+}
+
+/** Render the active path as markdown. Exported for tests; pure over the entries. */
+export function renderSessionMarkdown(entries: readonly Entry[], sessionId: string, catalog: ModelCatalog): string {
+  const messages = entries.filter(isMessage);
+  // pair tool_call parts with their results up front so a card renders where the
+  // assistant issued the call; results without a visible call render as orphan cards
+  const results = new Map<string, ToolResultPart>();
+  for (const m of messages) {
+    if (m.role !== "tool") continue;
+    for (const p of m.parts) if (p.kind === "tool_result" && !results.has(p.callId)) results.set(p.callId, p);
+  }
+  const consumed = new Set<string>();
+
+  // title block: id, date range, model origins (first-appearance order)
+  const stamps = entries.map((e) => e.createdAt).filter((t) => typeof t === "number");
+  const range = stamps.length > 0
+    ? `${new Date(Math.min(...stamps)).toISOString()} → ${new Date(Math.max(...stamps)).toISOString()}`
+    : "(empty)";
+  const origins: string[] = [];
+  for (const m of messages) {
+    if (!m.origin) continue;
+    const key = `${m.origin.provider}/${m.origin.model}`;
+    if (!origins.includes(key)) origins.push(key);
+  }
+  const blocks: string[] = [
+    `# rovecode session ${sessionId.slice(0, 8)}`,
+    [`- id: ${inlineCode(sessionId)}`, `- range: ${range}`, `- models: ${origins.length > 0 ? origins.join(", ") : "(none)"}`].join("\n"),
+  ];
+
+  for (const e of entries) {
+    if (!isMessage(e)) {
+      // event entries: compaction becomes a marker (TUI wording, app.ts); others skipped
+      if (e.event.type === "compaction") {
+        blocks.push(`> compacted (${e.event.strategy}): ${e.event.tokensBefore} → ${e.event.tokensAfter} tokens`);
+      }
+      continue;
+    }
+    const sw = modeSwitchOf(e);
+    if (sw) { blocks.push(`> mode → ${sw.to}`); continue; } // replay convention, never the raw XML
+    const text = textOf(e);
+    if (e.role === "user") {
+      // port #34: image parts render as one chip line each under the text (name, WxH, size), the
+      // same describeImage text the TUI notes use; the bytes stay in the session's attachments
+      // dir (header) so no image link that would dangle next to the export is emitted
+      const chips = e.parts.filter((p): p is ImagePart => p.kind === "image").map((p) => `[image: ${describeImage(p)}]`);
+      if (text || chips.length > 0) blocks.push("## User", ...(text ? [text] : []), ...chips);
+    } else if (e.role === "assistant") {
+      blocks.push("## Assistant");
+      if (text) blocks.push(text);
+      for (const p of e.parts) {
+        if (p.kind !== "tool_call") continue;
+        const call = p as ToolCallPart;
+        blocks.push(toolCard(call.tool, call.args, results.get(call.id)));
+        consumed.add(call.id);
+      }
+    } else if (e.role === "tool") {
+      for (const p of e.parts) {
+        if (p.kind === "tool_result" && !consumed.has(p.callId)) {
+          blocks.push(toolCard("(unknown)", undefined, p));
+          consumed.add(p.callId);
+        }
+      }
+    } else if (text) {
+      // plain system note (e.g. a compaction summary message)
+      blocks.push(text.split("\n").map((l) => `> ${l}`).join("\n"));
+    }
+  }
+  if (messages.length === 0) blocks.push("*(no entries)*");
+
+  // costs: per-origin usage totals, then the /cost note (existing helpers, deterministic
+  // against the offline catalog; "current" = the last message origin on the path)
+  const byOrigin = new Map<string, { input: number; output: number; cacheRead: number; cacheWrite: number; msgs: number }>();
+  for (const m of messages) {
+    if (!m.usage) continue;
+    const key = m.origin ? `${m.origin.provider}/${m.origin.model}` : "(no origin)";
+    const row = byOrigin.get(key) ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, msgs: 0 };
+    row.input += m.usage.input; row.output += m.usage.output;
+    row.cacheRead += m.usage.cacheRead ?? 0; row.cacheWrite += m.usage.cacheWrite ?? 0;
+    row.msgs += 1;
+    byOrigin.set(key, row);
+  }
+  blocks.push("## Costs");
+  if (byOrigin.size > 0) {
+    blocks.push([
+      "| model | input | output | cache read | cache write | messages |",
+      "| --- | ---: | ---: | ---: | ---: | ---: |",
+      ...[...byOrigin.entries()].map(([k, r]) => `| ${k} | ${r.input} | ${r.output} | ${r.cacheRead} | ${r.cacheWrite} | ${r.msgs} |`),
+    ].join("\n"));
+  }
+  const current = [...messages].reverse().find((m) => m.origin)?.origin ?? { provider: "unknown", model: "unknown" };
+  blocks.push(buildCostNote(messages, catalog, current).split("\n").map((l) => `- ${l}`).join("\n"));
+
+  return blocks.join("\n\n") + "\n";
+}
+
+// ---------- export entrypoint ----------
+
+function targetPath(out: string | undefined, id: string, format: "markdown" | "jsonl", cwd: string): string {
+  const fallback = `${id.slice(0, 8)}.${format === "jsonl" ? "jsonl" : "md"}`;
+  const p = out ?? fallback;
+  return isAbsolute(p) ? p : join(cwd, p);
+}
+
+/** Export a session (full id or unique prefix) to markdown or a raw JSONL copy.
+ *  --json copies entries.jsonl BYTE-VERBATIM (whole tree, every branch); markdown
+ *  renders the active path only. Never overwrites an existing file without force. */
+export function exportSession(sessionsRoot: string, idOrPrefix: string, opts: ExportOptions = {}): ExportResult {
+  if (!idOrPrefix) throw new Error(USAGE);
+  const id = resolveSessionId(sessionsRoot, idOrPrefix);
+  const format: ExportResult["format"] = opts.json ? "jsonl" : "markdown";
+  const target = targetPath(opts.out, id, format, opts.cwd ?? process.cwd());
+  if (existsSync(target) && !opts.force) throw new Error(`refusing to overwrite ${target} — pass --force`);
+  if (opts.json) {
+    const src = join(sessionsRoot, id, "entries.jsonl");
+    if (!existsSync(src)) throw new Error(`session ${id.slice(0, 8)} has no entries.jsonl to copy`);
+    writeFileSync(target, readFileSync(src)); // Buffer in → Buffer out: verbatim bytes
+  } else {
+    const store = new SessionStore(sessionsRoot, id);
+    writeFileSync(target, renderSessionMarkdown(store.path(), id, new ModelCatalog()));
+  }
+  return { path: target, format };
+}
+
+// ---------- CLI glue (rovecode export …) ----------
+
+export interface ExportCliArgs { idOrPrefix?: string; json: boolean; out?: string; force: boolean }
+
+/** Parse `rovecode export` argv. Flags may sit anywhere — parseCli accepts `rovecode --json
+ *  export <id>` for every subcommand — so the whole argv after the script path is
+ *  scanned and the single `export` command token skipped. parseCli strips flags but
+ *  leaves flag VALUES in rest, so --out is consumed here (same reason main.ts hand-
+ *  parses --resume: dispatch flags are boolean-only); a missing or flag-shaped --out
+ *  value is a usage error, never a silent default. First remaining non-flag = the id. */
+export function parseExportArgs(argv: readonly string[]): ExportCliArgs {
+  const args = argv.slice(2);
+  const parsed: ExportCliArgs = { json: false, force: false };
+  let cmdSeen = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--json") parsed.json = true;
+    else if (a === "--force") parsed.force = true;
+    else if (a === "--out") {
+      const v = args[++i];
+      if (v === undefined || v.startsWith("-")) throw new Error(`--out needs a path — ${USAGE}`);
+      parsed.out = v;
+    } else if (!a.startsWith("-")) { // other flags (--yolo, --plain, …) belong to dispatch
+      if (!cmdSeen && a === "export") cmdSeen = true; // the command token itself
+      else if (parsed.idOrPrefix === undefined) parsed.idOrPrefix = a;
+    }
+  }
+  return parsed;
+}
+
+/** `rovecode export <session> [--json] [--out <path>] [--force]` — errors exit 1. */
+export function cmdExport(argv: readonly string[]): void {
+  try {
+    const a = parseExportArgs(argv); // inside: a dangling --out is a usage error too
+    const res = exportSession(join(process.cwd(), ".rovecode", "sessions"), a.idOrPrefix ?? "", a);
+    console.log(`exported ${res.format} → ${res.path}`);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`error: ${msg}`);
+    // "you typed it wrong" and "it did not work" are different answers to a script: 2 is the usage class
+    // (README: 0 done · 1 error/budget · 2 usage/startup), and every other command already answers that way
+    process.exit(msg.startsWith("usage:") ? 2 : 1);
+  }
+}