rovecode 0.4.0-beta.2 → 0.4.0

package/src/cli/export.ts

@@ -0,0 +1,278 @@
+/** 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, listSessions, type Entry } from "../core/session.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 (mirrors TUI /resume: app.ts cmdSessions) ----------
+
+/** Exact id wins outright; a prefix must match exactly ONE session; an ambiguous
+ *  prefix lists candidates instead of silently picking one (same rule as /resume). */
+export function resolveSessionId(sessionsRoot: string, idOrPrefix: string): string {
+  const all = listSessions(sessionsRoot);
+  const exact = all.find((s) => s.id === idOrPrefix);
+  const matches = exact ? [exact] : all.filter((s) => s.id.startsWith(idOrPrefix));
+  if (matches.length === 1) return matches[0]!.id;
+  if (matches.length > 1) {
+    throw new Error(
+      `"${idOrPrefix}" matches ${matches.length} sessions: ` +
+      `${matches.slice(0, 4).map((s) => s.id.slice(0, 8)).join(", ")}${matches.length > 4 ? ", …" : ""} — be more specific`,
+    );
+  }
+  throw new Error(`no session matching "${idOrPrefix}"`);
+}
+
+// ---------- 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);
+  }
+}

package/src/cli/help.ts

@@ -0,0 +1,240 @@
+/** `rovecode help [topic]` — short and grouped by default; `env`, `advanced` and `all` hold the full
+ *  reference. Pure text so it is unit-testable (main.ts dispatches on import). Wording follows
+ *  core/voice.ts: plain sentences, the two permission modes by their screen names. */
+
+import { MODE_ASK, MODE_AUTO } from "../core/voice.ts";
+
+export const HELP_TOPICS = ["", "env", "advanced", "all"] as const;
+export type HelpTopic = (typeof HELP_TOPICS)[number];
+
+const SHORT = `rovecode — your coding agent
+
+start here
+  1  rovecode connect              connect a model (about a minute)
+  2  rovecode                       open the cockpit and describe what you need
+  3  rovecode "fix the failing test" run one task, then exit
+
+  tip  Start with a sentence. Rovecode reads first and asks before changing anything.
+
+everyday
+  rovecode model                  choose a model
+  rovecode doctor                 diagnose setup problems
+  rovecode --resume <id>          continue a session
+  rovecode run "<prompt>" --yolo   run without approval prompts (${MODE_AUTO})
+  rovecode market search <q>      find skills, plugins and MCP servers
+
+safety
+  ${MODE_ASK} (default)            read freely; ask before writes, shell commands and subagents
+  accept edits (--accept-edits)   write in this folder; still ask for shell, network and outside writes
+  auto (--yolo, ROVECODE_YOLO=1)   never ask; deny rules still apply
+  plan mode (/plan in the TUI)    inspect and plan without changing files
+
+more
+  rovecode help advanced          every command and option
+  rovecode help env               every ROVECODE_* setting
+  rovecode help all               both reference pages`;
+
+const ADVANCED = `advanced — the full command reference
+  rovecode                      interactive TUI chat — the sextant surface (files · code · messages · plan · usage · pet)
+                            on a colour TTY of at least 100x30 (truecolor, or 256 colours through the
+                            quantizer), else the classic pi-tui chat;
+                            --classic forces the classic chat · --pet <name> names the pet · --plain = readline REPL
+                            --no-intro (or ROVECODE_INTRO=0) skips the ~0.9s opening animation
+  rovecode chat · rovecode repl  the same as bare rovecode (repl still needs --plain for the readline REPL)
+  rovecode --help | -h          this help (only with no command in front of it) · rovecode --version prints the
+                            version to stdout and the update check’s answer to stderr
+  rovecode --resume <id>        open the TUI resuming a session (full id or unique prefix)
+  rovecode --continue           reopen the newest session that holds something (also: --resume with no id);
+                                nothing to continue from → a fresh session
+  rovecode "prompt"             one-shot task (same as run; a lone path-shaped word — ./x, x.ts, an existing
+                                name — is confirmed on a TTY and refused with exit 2 off one: use "rovecode run" to send it)
+  rovecode setup                connect a model step by step (TTY only; piped stdin prints the recipe and exits 2)
+  rovecode connect              the same wizard when given no arguments
+  rovecode connect <id> [<baseUrl>] [--model <id>] [--key | --key-stdin | --key-env NAME | --no-key]
+                              [--protocol openai|anthropic] [--project] [--no-test]
+                              one line: register the endpoint, store the key, pick the model, one tiny real
+                              call, persist the default. A key is never a flag value (shell history, ps):
+                              --key prompts hidden, --key-stdin reads one piped line (CI), --key-env names
+                              an env var, --no-key marks a local server.
+                              exit 0 connected · 1 the test call failed (config still written) · 2 usage
+  rovecode smoke-tui            render check: full pipeline into an 80x24 terminal emulator (dev-only)
+  rovecode smoke-tui --sextant  render check: the sextant surface at 160x44 through the full pipeline (no emulator needed)
+  rovecode run "<prompt>"       run an agent task (--yolo = ${MODE_AUTO}; with no provider configured this is a
+                            startup error, exit 2 — ROVECODE_MOCK=1 asks for the scripted mock on purpose)
+                            "/name args" expands a custom command (.rovecode/commands/<name>.md, else ~/.rovecode/commands)
+                            the way the TUI does; an unknown /name is sent verbatim; model:/mode: frontmatter is
+                            TUI-only and not applied headlessly
+                            piped stdin is appended to the prompt as a fenced block — git diff | rovecode run "review this"
+                            (never read from a terminal; --no-stdin ignores it; an open pipe that sends nothing
+                            for 3 s is skipped with a note; capped at 1 MB)
+    --max-turns N · --max-seconds S|off   ceilings on one run; a hit ends it cleanly with status
+                            "budget" (exit 1) and the work so far, instead of an external kill. Headless runs
+                            default to a 20-minute wall clock; --max-seconds off removes it
+    --max-cost D|off        a spend ceiling in dollars for one run, priced from each turn's usage as it lands
+                            (the catalog's rates for the model that served it); the same clean "budget" end.
+                            A turn the catalog cannot price adds nothing and is counted in the summary
+    --output <text|json|ndjson>  text (default): progress + the final answer on stdout
+                            json: exactly ONE result object on stdout {status, summary, sessionId,
+                            model:{provider,model}, origin (served model|null), usage:{input,output,cacheRead,
+                            cacheWrite}, costUsd (null when unpriced), toolCalls:[{tool,ok,ms?}], durationMs, exitCode}
+                            ndjson: one JSON line per RunEvent, then a final {type:"result"} line
+                            json/ndjson: stdout carries only JSON, progress goes to stderr
+                            exit codes: 0 done · 1 error/budget · 2 usage/startup error · 130 aborted (Ctrl-C)
+                            exit 2 = usage/startup error (bad --output value, sandbox misconfig or unavailable rung):
+                            one stderr line, nothing on stdout; --output=<mode> is accepted as well
+  rovecode bench                run cross-harness micro-benchmarks (edits, sessions)
+  rovecode gauntlet             run the adversarial evaluation suite (offline, scripted model)
+  rovecode gauntlet --live      the gauntlet's tasks minus loop-guard (9) against the configured REAL model through
+                                the real prompt — --model <provider/model> and --effort pick; compare pass/calls/tokens
+  rovecode tools                list registered tools
+  rovecode plugin list          plugins in ~/.rovecode/plugins and .rovecode/plugins with status (active · disabled · untrusted · broken)
+  rovecode plugin add <folder|git-url> [--project] [--force]  install a plugin folder (tools, hooks, commands, skills, MCP in one manifest)
+  rovecode plugin trust <name>  approve a PROJECT plugin's current files on this machine (show <name> lists them first)
+  rovecode plugin remove|enable|disable|untrust|show <name>   (docs/plugins.md; restart to load — read once per process, like hooks)
+  rovecode mcp search [query]   MCP servers to install: the curated shelf, then the official registry (cached a day)
+  rovecode mcp info <name>      publisher, version, the exact command or URL, the keys it asks for
+  rovecode mcp add <name> [--project] [--pick N] [--as <name>] [--yes] [--force]  show the plan, ask for keys
+                            masked, write ~/.rovecode/mcp.json (or .rovecode/mcp.json); --as renames it, --force replaces an entry
+  rovecode mcp remove <name> [--project] · rovecode mcp list   (docs/mcp-market.md; /mcp does the same inside the TUI)
+  rovecode mcp show             this repo's .rovecode/mcp.json + .mcp.json: exact commands/URLs, env names, trusted or not
+  rovecode mcp trust [--yes] · rovecode mcp untrust   approve those files as they are now, or withdraw that
+                            approval — until trusted nothing in them loads; your own add --project is trusted as you approve it
+  rovecode market search [query] [--kind mcp|skill|plugin]  one shelf over MCP servers, skills and plugins
+  rovecode market info <id>     publisher, licence, version, exactly what an install would write
+  rovecode market docs <id>     the item's own documentation, as the catalog carries it — no network
+  rovecode market install <id|kind:id|git-url|npm-pkg> [--project] [--ref <branch|tag|commit>] [--yes]
+                            plan first, write only after you agree
+  rovecode market list|remove|update|sources   what is installed, what is behind, where each shelf came from
+  rovecode market verify [id]   re-hash what is installed and say what has changed since
+  rovecode market validate <path|url> [--kind skill|plugin]   check a catalog before anyone trusts it
+                            (docs/market.md; /market does the same inside the TUI; every subcommand takes --json)
+  rovecode doctor [--json] [--no-connect]  one pass over the setup: home (and a legacy ~/.cumulus), the default
+                            provider and where its key comes from (names, never values), the permission level and
+                            which rung set it, git/node/npm/npx/uvx on PATH with what each absence costs HERE,
+                            every configured MCP server (loads? skipped for a placeholder or an unset variable?
+                            untrusted file? connects?), the shadow checkpoints' size — and a list of what it did
+                            NOT check. exit 0 nothing broken · 1 something to fix · a missing provider is a note
+  rovecode context [session] [--json]  what fills the window, item by item, and how far our estimate is from
+                            the provider's own count of the same prompt (cache reads included — they are the prompt too)
+                            (--exact asks Anthropic to count it for real; --no-runtime skips the system prompt and tool schemas)
+  rovecode auth set <provider> [--key <name>]  store an API key (prompts on stdin; ~/.rovecode/credentials.json)
+  rovecode auth list            stored providers + key names (values redacted)
+  rovecode auth remove <provider>  delete a stored credential
+  rovecode login [--api <url>]   link this machine to a rovecode account: prints a code to approve at
+                              <url>/cli-auth, then stores the issued token in ~/.rovecode/account.json
+                              (--token rc_live_… links a hand-pasted key instead; --json for scripts)
+  rovecode account [--json]    the linked account, its API base and when it was linked
+  rovecode logout              unlink: remove ~/.rovecode/account.json
+  rovecode provider list [--all]  providers with a key + every providers.json entry, and the default provider/model
+  rovecode provider add <id> <baseUrl> [--protocol openai|anthropic] [--key-env NAME] [--model <id>] [--no-key]
+                              [--project | --user | --scope user|project] [--key]
+                              register any OpenAI-compatible or Anthropic endpoint in ~/.rovecode/providers.json
+                              (--project: ./.rovecode/providers.json); --key prompts for the secret (never echoed);
+                              running TUIs/servers pick the change up live — no restart
+  rovecode provider remove <id>  delete a providers.json entry (built-ins: rovecode auth remove <id> drops the key)
+  rovecode provider test <id> [model]  one tiny real call — proves url + key + model together
+  rovecode model list [provider]  model ids (providers.json "models" or the endpoint's /models); * = current default
+  rovecode models [provider]  alias for model list
+  rovecode model              no arguments on a terminal: every configured provider's models in one
+                            numbered menu, the current one first; a pipe gets the usage line instead
+  rovecode model use <provider/model> [--project]  persist the default (in the TUI: /model <provider/model> --save)
+  rovecode model show [provider/model]  the model, its protocol, and the exact thinking field each /effort
+                            level puts on the wire (docs/thinking.md)
+  rovecode trace <session-id>   the session's messages, one line each (role · first 120 chars · tool-call count)
+  rovecode export <session>     write a session as markdown (--json: raw JSONL copy; --out <path>; --force)
+  rovecode eval                 alias for gauntlet
+  rovecode acp                  Agent Client Protocol v1 endpoint over stdio (Zed/JetBrains)
+  rovecode serve                headless HTTP server (ROVECODE_PORT, default 4100; loopback-only)`;
+
+const ENV = `env — every ROVECODE_* setting
+  ROVECODE_BASE_URL   any OpenAI-compatible or Anthropic endpoint
+  ROVECODE_API_KEY    API key (falls back to OPENAI_API_KEY)
+  ROVECODE_MODEL      model id (e.g. zai-org/glm-5.3)
+  ROVECODE_MODEL_<ROLE>  role fallback chain, comma-separated provider/model list; on 429/5xx
+                  the next candidate serves. Roles: DEFAULT SMOL PLAN COMMIT TASK
+                  (e.g. ROVECODE_MODEL_DEFAULT=kaesra/zai-org/glm-5.3-flash,openai/gpt-4o-mini)
+  ROVECODE_STREAM     streaming is on by default (both protocols); off|json|0|false|none use the one-shot JSON
+                    adapters; sse forces the raw SSE adapter, without the tool-call middleware, for one-shot runs
+  ROVECODE_EFFORT     auto|off|low|medium|high thinking before the answer (default auto: the provider's
+                    own default stands). Anthropic gets output_config.effort or a thinking budget,
+                    whichever the model takes (learned from its own 400, then remembered); OpenAI gets
+                    reasoning_effort. Thinking is billed as output and delays the first word.
+  ROVECODE_PROFILE    model profile: off, or an id (glm-5.3 | glm-5.3-plain) whose PROMPT section is forced onto
+                    every model (request fields always follow the model id). Unset = by model id: GLM-5.3 / -Flash
+                    get the Claude Sonnet 5 persona + the working agreement appended to the system prompt
+                    (glm-5.3-plain = agreement only) plus, on OpenAI-compatible providers, Z.ai's
+                    request fields (thinking always on, reasoning_effort low|high|max — off leaves the endpoint's
+                    max, medium rounds up to high, high means max — and tool_stream when streaming). The text
+                    comes from .rovecode/profiles/<id>.md (project) or ~/.rovecode/profiles/<id>.md when present.
+  ROVECODE_DESIGN     off drops the interface-design section from the system prompt (for runs with no UI in
+                    them). Otherwise every run carries it: propose three distinct directions before the first
+                    UI in a project, let the human choose, record it with design_direction, then build to it.
+                    The section prescribes NO palette, typeface or layout -- there is no default look, on
+                    purpose -- and names the patterns to climb out of (amber accents, the reflex full-viewport
+                    hero, Inter/Roboto/Poppins, hairlines round everything, all-square corners, everything
+                    centred, violet gradients). The choice lives in .rovecode/design.json; design_audit counts
+                    those patterns in the files you touched and checks them against it.
+  ROVECODE_PERMISSION  ask|accept-edits|auto — the level this run starts at. Ladder, widest first:
+                    a CLI flag, then this, then <cwd>/.rovecode/settings.json, then ~/.rovecode/settings.json,
+                    then "ask". Write the files with /yolo --save or /accept-edits --save [--project].
+  ROVECODE_ACCEPT_EDITS=1  start in accept-edits (writes inside the workspace do not ask)
+  ROVECODE_YOLO=1     ${MODE_AUTO}: allow all tool actions
+  ROVECODE_TUI        sextant | classic — force the TUI surface (sextant still needs a TTY; --classic wins)
+  ROVECODE_THEME      sextant palette: night (default) | ember | contrast (/theme switches it live)
+  ROVECODE_PET=0      hide the sextant pet panel (rovecode); --pet <name> renames it
+  ROVECODE_SANDBOX    executor rung for bash: direct (default) | wsl | docker; beats .rovecode/sandbox.json {"rung","dockerImage"}
+  ROVECODE_SANDBOX_IMAGE  image for the docker rung (default debian:stable-slim; must contain bash)
+  ROVECODE_RETRY_MAX  same-model retries after a 429/5xx/transport failure (default 3 = 4 attempts; 0 = off)
+                    The wait is announced live, while it is happening, not in a summary after the run
+  ROVECODE_RETRY_BASE_MS  cap of the FIRST backoff, ms (default 1000; full jitter; a Retry-After hint is a floor)
+                    It doubles per attempt up to 20 s, and a server hint can raise the wait, never shorten it
+  ROVECODE_FIRST_BYTE_TIMEOUT_MS  how long a provider may go without ANY response before the request
+                    counts as failed and is retried (default 60000). Only the FIRST byte is on this clock:
+                    once the model is talking, the body may take as long as it takes
+  ROVECODE_WEBFETCH_TIMEOUT_MS  web_fetch request timeout in ms (default 30000)
+  ROVECODE_WEBFETCH_ALLOW_PRIVATE=1  let web_fetch reach loopback/private hosts (SSRF guard escape for local dev)
+  ROVECODE_COMPACTION  history compaction strategy: head-summarize (default) | keep-window | provider-native
+  ROVECODE_TASKS_MAX  concurrent background tasks (default 3; further task starts queue FIFO)
+  ROVECODE_OTEL_ENDPOINT  OTLP/HTTP collector, e.g. http://host:4318 — one trace per run (run ⊃ turn ⊃ tool); unset = off
+  ROVECODE_OTEL_HEADERS  extra OTLP headers as k=v,k2=v2 (e.g. authorization=Bearer …)
+  ROVECODE_REFLECTION=0  disable reflection nudges after failed edits; ROVECODE_REFLECTION_MAX caps them per run (default 2)
+  ROVECODE_PORT       port for rovecode serve (default 4100; loopback-only)
+  ROVECODE_IMAGE_MAX_BYTES  per-image cap in bytes for pasted and attached images (default 5 MB;
+                    at most 8 images per message). Over it, the image is refused by name, not silently dropped.
+  ROVECODE_REPOMAP_TOKENS  repo-map budget in tokens (default 1024); ROVECODE_NO_REPOMAP=1 drops the map entirely
+  ROVECODE_HOOK_TIMEOUT_MS  per-hook-call budget in ms (default 5000); ROVECODE_NO_HOOKS=1 skips hook files
+  ROVECODE_PLUGIN_TIMEOUT_MS  per-plugin import + tools() budget in ms (default 5000);
+                    ROVECODE_NO_PLUGINS=1 skips plugin discovery
+  ROVECODE_NO_CHECKPOINTS=1  turn off the shadow-git checkpoints taken after mutating tools
+  ROVECODE_TOOL_MIDDLEWARE=1  force the text tool-call protocol (a prompt block + a parser) even for a model
+                    the catalog says has native tool calling; ROVECODE_NO_TOOL_MIDDLEWARE=1 forces native only
+  ROVECODE_EVAL_CELL=1  register the persistent eval cell tool (a REPL that keeps state between calls)
+  ROVECODE_MAX_TURNS  turn ceiling for one run, every surface (TUI included); a hit ends it with status
+                    "budget" and exit 1
+  ROVECODE_MAX_SECONDS  the same as a wall clock, or "off". Every surface honours it, but only
+                    one-shot runs have a DEFAULT (1200 s) — the TUI has no clock unless this sets one
+  ROVECODE_MAX_COST   the same in dollars for one run (--max-cost on a one-shot run), or "off"; no default
+  ROVECODE_FINISH_CHECK=0  turn off the once-per-run finish check: when the model stops right after a failed tool
+                    call or an unanswered question, it is asked ONCE to finish or say what is left; the next
+                    reply ends the run either way. "done · …" on run_end still names what was left
+  ROVECODE_VERIFY=1   turn ON the verify gate (off by default): a run that wrote files runs the project's configured
+                    check before "done"; a failure goes back to the model once, then "done · check failed (…)" says
+                    so. No check configured → nothing runs, run_end says "not verified". ROVECODE_VERIFY_TIMEOUT=<s> (120)
+  ROVECODE_HOME       credentials + user-scope providers/commands dir (default ~/.rovecode)
+providers: built in — kaesra openai anthropic deepseek groq openrouter ollama lmstudio
+            together mistral cerebras fireworks perplexity xai moondream vllm
+            plus anything in ~/.rovecode/providers.json or ./.rovecode/providers.json (rovecode provider add)
+            key: rovecode auth set <id>, or set <ID>_API_KEY — stored creds beat env;
+            default: providers.json "default" ("provider/model"), ROVECODE_MODEL overrides the model,
+            ROVECODE_BASE_URL/ROVECODE_API_KEY always wins`;
+
+/** the text for a topic; an unknown topic gets the short page plus a one-line note */
+export function helpText(topic = ""): string {
+  switch (topic) {
+    case "": return SHORT;
+    case "env": return ENV;
+    case "advanced": return ADVANCED;
+    case "all": return `${SHORT}\n\n${ADVANCED}\n\n${ENV}`;
+    default: return `${SHORT}\n\nno help topic "${topic}" — topics: env · advanced · all`;
+  }
+}

package/src/cli/is-tui-invocation.ts

@@ -0,0 +1,8 @@
+/** Returns true when argv will start the interactive TUI (as opposed to a lightweight subcommand).
+ *  Used by bin/rovecode.ts to decide whether to route through the pre-bundled dist/cli/main.js. */
+import { parseCli } from "./dispatch.ts";
+
+export function isTuiInvocation(argv: string[]): boolean {
+  const { cmd, plain } = parseCli(argv);
+  return (cmd === "" || cmd === "chat" || cmd === "repl") && !plain;
+}