rovecode 0.4.0-beta.3 → 0.4.0

package/src/tui/attach.ts

@@ -0,0 +1,127 @@
+/** Port #34 TUI wiring for image input: `/attach` stages image parts for the next user message,
+ *  user turns echo (and replay) with image chips, and the stage survives a session switch.
+ *
+ *  The stage is the SessionStore's own (stageAttachments / stagedAttachments): the store folds it
+ *  into the NEXT role:"user" entry that lands in append() — the run's goal message when idle
+ *  (loop.ts userMsg), the queued steer when the loop drains it mid-run (loop.ts steering drain) —
+ *  so the ONE agentLoop (ADR-003) needs no attach change and the TUI keeps no second copy of the
+ *  list. Consequences, documented rather than hidden:
+ *  - a steer queued BEFORE /attach is the next user entry and takes the images instead; if the
+ *    run ends before any steer is drained, the images ride on the next run's goal message and the
+ *    steer text follows it in the same request — nothing is ever dropped;
+ *  - /sessions, /resume and a root /rewind replace the store INSTANCE: switchSession carries the
+ *    stage across with a visible note (carryOverAttachments); same-store /new and /rewind move
+ *    only the leaf, so the stage stays put;
+ *  - no image-only messages: the editor drops empty input (pi-renderer.ts onSubmit), so text is
+ *    required and every attach note says so — no "(see attached image)" text is invented on the
+ *    user's behalf.
+ *  Vision check at attach time (catalog.supportsImages on the current mode's model): false → warn
+ *  (wire-messages.ts will send a text placeholder), undefined → info (unknown model: sent as-is,
+ *  the provider may reject). Paths resolve against the runtime cwd; the loader sniffs magic bytes
+ *  (core/images.ts), never the extension. */
+
+import { resolve } from "node:path";
+import { checkImageCount, describeImage, imageChip, imageFromBytes, loadImageAttachment, MAX_IMAGES_PER_MESSAGE } from "../core/images.ts";
+import { clipboardImageName, readClipboardImage } from "./clipboard-image.ts";
+import type { SessionStore } from "../core/session.ts";
+import type { ImagePart, MessagePart } from "../core/types.ts";
+import { supportsImages } from "../providers/catalog.ts";
+import type { Renderer, SlashCommand } from "./renderer.ts";
+
+/** The TUI_COMMANDS entry (/help, palette, custom-command reserved names). */
+export const ATTACH_COMMAND: SlashCommand = {
+  name: "attach",
+  description: "Attach an image to your next message (text required): /attach <path> · /attach = list · /attach clear · or drag an image file onto the terminal",
+};
+
+export interface AttachCtx {
+  renderer: Renderer;
+  /** runtime cwd — relative paths resolve against it */
+  cwd: string;
+  /** the ACTIVE store, read live (/sessions and a root /rewind swap it) */
+  store(): SessionStore;
+  /** the current mode's model — the vision check */
+  modelRef(): { provider: string; model: string };
+}
+
+const plural = (n: number): string => `${n} image${n === 1 ? "" : "s"}`;
+
+/** `/attach <path>` stages one image · `/attach` lists the stage · `/attach clear` empties it.
+ *  Never throws: a bad file, an oversize image or the 9th image is a note, nothing staged. */
+export function cmdAttach(ctx: AttachCtx, arg: string): void {
+  const { renderer } = ctx;
+  const store = ctx.store();
+  const staged = store.stagedAttachments;
+  if (arg === "") {
+    renderer.addSystemNote(staged.length === 0
+      ? "no images attached — /attach <path>"
+      : `attached (${staged.length}/${MAX_IMAGES_PER_MESSAGE}):\n${staged.map((p, i) => `${i + 1}. ${describeImage(p)}`).join("\n")}`);
+    return;
+  }
+  if (arg === "clear") {
+    store.stageAttachments([]);
+    renderer.addSystemNote(staged.length === 0 ? "no images attached" : `attachments cleared (${plural(staged.length)} removed)`);
+    return;
+  }
+  const path = arg.replace(/^(["'])(.*)\1$/, "$2"); // a quoted path keeps its spaces
+  const loaded = loadImageAttachment(resolve(ctx.cwd, path));
+  if ("error" in loaded) { renderer.addSystemNote(loaded.error, "error"); return; }
+  const over = checkImageCount(staged.length + 1);
+  if (over !== undefined) { renderer.addSystemNote(over, "error"); return; }
+  store.stageAttachments([...staged, loaded]); // replaces the stage; folds into the next user entry
+  renderer.addSystemNote(`attached ${describeImage(loaded)} (${staged.length + 1}/${MAX_IMAGES_PER_MESSAGE}) — type your message and press Enter to send it`);
+  const ref = ctx.modelRef();
+  const vision = supportsImages(ref);
+  if (vision === false) renderer.addSystemNote(`model ${ref.provider}/${ref.model} has no image input — it will be sent as a text placeholder`, "warn");
+  else if (vision === undefined) renderer.addSystemNote(`unknown model ${ref.provider}/${ref.model}; image sent as-is (provider may reject)`);
+}
+
+/** `/paste` — the clipboard image as an attachment (⌃v in the sextant surface lands here). */
+export const PASTE_COMMAND: SlashCommand = {
+  name: "paste",
+  description: "attach the image on the clipboard (⌃v)",
+};
+
+/** Stage the image currently on the system clipboard. Berkay: "gorsel gonderebilme olayini yapalim" —
+ *  /attach <path> existed, but the thing everyone tries first is copying a screenshot and pressing ⌃v,
+ *  and a terminal delivers only TEXT pastes, so that did nothing. tui/clipboard-image.ts asks the OS.
+ *  Same rules as /attach: magic-byte sniff, size cap, the 8-image cap, the vision note; never throws.
+ *  `read` is injectable (tests never touch a real clipboard). */
+export function cmdPasteImage(ctx: AttachCtx, read: () => Uint8Array | null = () => readClipboardImage(), name = clipboardImageName()): void {
+  const { renderer } = ctx;
+  const bytes = read();
+  if (bytes === null) { renderer.addSystemNote("no image on the clipboard — copy a screenshot or picture first, or /attach <path>"); return; }
+  const loaded = imageFromBytes(bytes, { name });
+  if ("error" in loaded) { renderer.addSystemNote(loaded.error, "error"); return; }
+  const store = ctx.store();
+  const staged = store.stagedAttachments;
+  const over = checkImageCount(staged.length + 1);
+  if (over !== undefined) { renderer.addSystemNote(over, "error"); return; }
+  store.stageAttachments([...staged, loaded]);
+  renderer.addSystemNote(`attached ${describeImage(loaded)} from the clipboard (${staged.length + 1}/${MAX_IMAGES_PER_MESSAGE}) — type your message and press Enter to send it`);
+  const ref = ctx.modelRef();
+  const vision = supportsImages(ref);
+  if (vision === false) renderer.addSystemNote(`model ${ref.provider}/${ref.model} has no image input — it will be sent as a text placeholder`, "warn");
+}
+
+/** Transcript line for a user turn: the text, then one chip per image on a second line; an
+ *  image-only turn is just its chips; "" when there is nothing to show. Used by the submit echo
+ *  (with the stage about to fold) and by replay (with the persisted parts). */
+export function userTurnLine(text: string, parts: readonly MessagePart[]): string {
+  const chips = parts.filter((p): p is ImagePart => p.kind === "image").map(imageChip).join(" ");
+  return text && chips ? `${text}\n${chips}` : text || chips;
+}
+
+/** Suffix for the busy-submit note: what the queued steer will carry when the loop drains it. */
+export function queuedAttachNote(store: SessionStore): string {
+  const n = store.stagedAttachments.length;
+  return n === 0 ? "" : ` — ${plural(n)} attached to your queued message`;
+}
+
+/** After a store swap (/sessions, /resume, root /rewind): re-stage the images the OLD instance held
+ *  on the new one and say so — the switch must never lose them silently. */
+export function carryOverAttachments(ctx: AttachCtx, pending: readonly ImagePart[]): void {
+  if (pending.length === 0) return;
+  ctx.store().stageAttachments(pending);
+  ctx.renderer.addSystemNote(`${plural(pending.length)} still attached — carried over to this session, rides on your next message`);
+}

package/src/tui/checkpoints-cmd.ts

@@ -0,0 +1,70 @@
+/** TUI surface for shadow-git checkpoints (port #11, cline): /checkpoints lists the
+ *  session's snapshots in a pickOne overlay; /restore <ref> [files|conversation|both]
+ *  replays cline's three restore modes. Conversation/both restores branch the session
+ *  tree to the checkpoint's recorded entryId (port #2 leaf machinery) — the CALLER
+ *  owns the store, so branching + replay run through the injected ctx. */
+
+import type { RestoreMode } from "../coding/checkpoints.ts";
+import type { Checkpoints } from "../coding/checkpoints.ts";
+import type { Renderer } from "./renderer.ts";
+
+export interface CheckpointCmdCtx {
+  renderer: Renderer;
+  busy(): boolean;
+  /** active session id (checkpoints are per-session) */
+  sessionId(): string;
+  checkpointsFor(sessionId: string): Promise<Checkpoints | null>;
+  /** branch the ACTIVE session store to entryId; false when the entry is unknown */
+  branchTo(entryId: string): boolean;
+  /** re-render transcript + usage after a conversation restore */
+  replayAndRefresh(): void;
+}
+
+const MODES: readonly RestoreMode[] = ["files", "conversation", "both"];
+
+/** /checkpoints — list snapshots newest-first in the overlay; picking one prefills nothing
+ *  and just prints the /restore hint (restore is deliberately an explicit second step). */
+export async function cmdCheckpoints(ctx: CheckpointCmdCtx): Promise<void> {
+  if (ctx.busy()) { ctx.renderer.addSystemNote("finish or interrupt the run first (Esc)", "warn"); return; }
+  const cp = await ctx.checkpointsFor(ctx.sessionId());
+  if (!cp) { ctx.renderer.addSystemNote("checkpoints unavailable (git missing or ROVECODE_NO_CHECKPOINTS=1)", "warn"); return; }
+  const log = cp.list();
+  if (log.length === 0) { ctx.renderer.addSystemNote("no checkpoints yet — snapshots land after each mutating tool call"); return; }
+  const items = [...log].reverse().slice(0, 20).map((c, i) => ({
+    value: c.hash,
+    label: `#${log.length - i} ${c.label} · ${c.hash.slice(0, 8)}`,
+    description: `${new Date(c.createdAt).toLocaleString()}${c.entryId ? " · conversation anchor" : ""}`,
+  }));
+  const picked = await ctx.renderer.pickOne(items, "checkpoints (Enter = show restore hint, Esc = close)");
+  ctx.replayAndRefresh(); // clear the overlay title note
+  if (picked) ctx.renderer.addSystemNote(`restore with: /restore ${picked.slice(0, 8)} [files|conversation|both]`);
+}
+
+/** /restore <hash-prefix> [mode] — files (workspace only), conversation (session branch
+ *  only), or both. Cline's three modes, checkpoint-restore semantics. */
+export async function cmdRestore(ctx: CheckpointCmdCtx, arg: string): Promise<void> {
+  if (ctx.busy()) { ctx.renderer.addSystemNote("finish or interrupt the run first (Esc)", "warn"); return; }
+  const [ref, modeArg] = arg.split(/\s+/);
+  if (!ref) { ctx.renderer.addSystemNote("usage: /restore <checkpoint> [files|conversation|both] — list with /checkpoints", "warn"); return; }
+  const mode = (modeArg || "files") as RestoreMode;
+  if (!MODES.includes(mode)) { ctx.renderer.addSystemNote(`unknown restore mode "${modeArg}" (files|conversation|both)`, "warn"); return; }
+  const cp = await ctx.checkpointsFor(ctx.sessionId());
+  if (!cp) { ctx.renderer.addSystemNote("checkpoints unavailable (git missing or ROVECODE_NO_CHECKPOINTS=1)", "warn"); return; }
+  // dedupe candidates BY HASH (identical content re-snapshotted shares one): counting
+  // entries made even the full 40-char hash "match 2 checkpoints" forever. Latest entry
+  // per hash wins, mirroring the module's own pick.
+  const match = [...new Map(cp.list().filter((c) => c.hash.startsWith(ref)).map((c) => [c.hash, c])).values()];
+  if (match.length !== 1) {
+    ctx.renderer.addSystemNote(match.length === 0 ? `no checkpoint matching "${ref}"` : `"${ref}" matches ${match.length} checkpoints — be more specific`, "warn");
+    return;
+  }
+  const res = await cp.restore(match[0]!.hash, mode);
+  if (!res.ok) { ctx.renderer.addSystemNote(`restore failed: ${res.error}`, "error"); return; }
+  let convNote = "";
+  if (mode === "conversation" || mode === "both") {
+    if (res.entryId && ctx.branchTo(res.entryId)) { ctx.replayAndRefresh(); convNote = " · conversation branched to the checkpoint's turn"; }
+    else convNote = " · conversation anchor unavailable in this session tree (files unaffected by that)";
+  }
+  const fileNote = mode === "conversation" ? "" : "workspace rolled back";
+  ctx.renderer.addSystemNote(`restored ${res.checkpoint.hash.slice(0, 8)} (${mode}) — ${fileNote}${convNote}; snapshots keep history`);
+}

package/src/tui/clipboard-image.ts

@@ -0,0 +1,81 @@
+/** Read an IMAGE from the system clipboard (⌃v / `/paste`).
+ *
+ *  A terminal only ever hands a program TEXT from the clipboard (bracketed paste). When the clipboard
+ *  holds an image — a screenshot, a copied picture — the terminal sends nothing useful, and users who
+ *  press ⌃v expecting the image to land (every chat app taught them that) get silence. So the surface
+ *  asks the OS itself, through the one tool each platform has for it, and converts to PNG:
+ *    win32  PowerShell + System.Windows.Forms.Clipboard.GetImage()  → PNG → base64 on stdout
+ *    darwin osascript `the clipboard as «class PNGf»`                → hex («data PNGf…»)
+ *    linux  wl-paste -t image/png, else xclip -selection clipboard -t image/png -o
+ *
+ *  The command runner is injected so tests never touch a real clipboard; every failure (no image on
+ *  the clipboard, tool missing, odd output) is `null`, never a throw — the caller says "no image on the
+ *  clipboard" and moves on. Nothing here writes a file: the bytes go straight to core/images.ts
+ *  imageFromBytes, which sniffs the magic bytes and enforces the size cap like any other attachment. */
+
+import { spawnSync } from "node:child_process";
+
+export interface ClipboardRunner {
+  /** run a command, return stdout decoded as `encoding` (utf8 for text tools, latin1 when the tool
+   *  prints raw image bytes — utf8 decoding would corrupt them), or null when it failed / is missing */
+  (cmd: string, args: readonly string[], encoding?: "utf8" | "latin1"): string | null;
+}
+
+const TIMEOUT_MS = 5_000;
+const MAX_OUT = 64 * 1024 * 1024; // a 5 MiB image is ~7 MiB of base64; leave room, never unbounded
+
+/** child_process.spawnSync under the contract above: non-zero exit, signal, timeout or ENOENT → null */
+export const spawnRunner: ClipboardRunner = (cmd, args, encoding = "utf8") => {
+  try {
+    const r = spawnSync(cmd, args, { encoding, timeout: TIMEOUT_MS, maxBuffer: MAX_OUT, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+    if (r.error || r.status !== 0 || r.signal) return null;
+    return r.stdout;
+  } catch { return null; }
+};
+
+/** PowerShell: the image as PNG base64, or nothing when the clipboard holds no image */
+const PS_SCRIPT = [
+  "Add-Type -AssemblyName System.Windows.Forms,System.Drawing",
+  "$i = [System.Windows.Forms.Clipboard]::GetImage()",
+  "if ($i -eq $null) { exit 3 }",
+  "$ms = New-Object System.IO.MemoryStream",
+  "$i.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png)",
+  "[Console]::Out.Write([Convert]::ToBase64String($ms.ToArray()))",
+].join("; ");
+
+function fromBase64(s: string | null): Uint8Array | null {
+  const t = s?.trim() ?? "";
+  if (t.length < 16 || !/^[A-Za-z0-9+/=\r\n]+$/.test(t)) return null;
+  try { return new Uint8Array(Buffer.from(t.replace(/\s+/g, ""), "base64")); } catch { return null; }
+}
+
+/** osascript prints `«data PNGf89504E47…»`; take the hex between the marker and the closing » */
+function fromAppleScriptHex(s: string | null): Uint8Array | null {
+  const m = /«data PNGf([0-9A-Fa-f]+)»/.exec(s ?? "");
+  if (!m || m[1]!.length < 32 || m[1]!.length % 2 !== 0) return null;
+  return new Uint8Array(Buffer.from(m[1]!, "hex"));
+}
+
+/** The clipboard image as raw bytes (PNG on win32/darwin, whatever the tool yields on linux — the
+ *  magic-byte sniff downstream decides), or null when there is none. `platform` defaults to the process's. */
+export function readClipboardImage(run: ClipboardRunner = spawnRunner, platform: NodeJS.Platform = process.platform): Uint8Array | null {
+  if (platform === "win32") {
+    return fromBase64(run("powershell", ["-NoProfile", "-NonInteractive", "-STA", "-Command", PS_SCRIPT]));
+  }
+  if (platform === "darwin") {
+    return fromAppleScriptHex(run("osascript", ["-e", "the clipboard as «class PNGf»"]));
+  }
+  // linux and the rest: wayland first, then X11; both print the raw PNG, which the runner returns as a
+  // utf8 string — decode it back to bytes with latin1 so no byte is altered
+  for (const [cmd, args] of [["wl-paste", ["-t", "image/png"]], ["xclip", ["-selection", "clipboard", "-t", "image/png", "-o"]]] as const) {
+    const out = run(cmd, args, "latin1");
+    if (out !== null && out.length > 8) return new Uint8Array(Buffer.from(out, "latin1"));
+  }
+  return null;
+}
+
+/** what a pasted image is called in the transcript chip and the sidecar name: clipboard-HHMMSS.png */
+export function clipboardImageName(now: Date = new Date()): string {
+  const p = (n: number): string => String(n).padStart(2, "0");
+  return `clipboard-${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}.png`;
+}

package/src/tui/commands.ts

@@ -0,0 +1,277 @@
+/** Custom slash commands (port #30): `.rovecode/commands/*.md` (project) and `~/.rovecode/commands/*.md`
+ *  (user scope, ROVECODE_HOME-aware) become `/name` commands in the TUI — autocomplete, /help,
+ *  and dispatch through the same user-turn path a typed prompt takes.
+ *
+ *  Ported from opencode @ ebece6e (MIT), packages/opencode/src unless noted:
+ *  - discovery: markdown files under a `command(s)/` dir, name = path sans extension
+ *    (config/command.ts:13-39 load, config/entry-name.ts:15-19 configEntryNameFromPath);
+ *    the frontmatter is the command's metadata and the markdown body its template
+ *    (config/command.ts:26-30 `{ name, ...md.data, template: md.content.trim() }`); fields
+ *    description/model (packages/core/src/v1/config/command.ts:5-12 — agent/variant/subtask
+ *    have no rovecode counterpart; rovecode adds `mode` for plan/act, port #20).
+ *  - precedence: the global config dir is loaded before the project's and later entries
+ *    replace earlier ones (config/config.ts:473 mergeDeep) → project shadows user here.
+ *  - templating (session/prompt.ts:1372-1395): quote-aware argument split (argsRegex :1594,
+ *    quoteTrimRegex :1596), `$N` positional (placeholderRegex :1595), `$ARGUMENTS` = the whole
+ *    argument string (:1391), and a template with no placeholder gets the arguments appended
+ *    after a blank line (:1393-1395); `hints` (command/index.ts:36-44) lists the placeholders.
+ *  - a per-command `model` overrides the session model for THAT prompt only (:1411-1412).
+ *  Pattern reference only, no code ported: gemini-cli @ 0bd1d43 packages/cli/src/services/
+ *  FileCommandLoader.ts — user dir first, project dir second, "last wins" (:85-90, :204-228),
+ *  invalid files skipped with a report, never fatal (:277-298).
+ *
+ *  Deviations: flat directory (no subdirectory namespaces); names are lowercased and must
+ *  match [a-z0-9_-]+; YAML-lite frontmatter (`key: value` lines — skills/index.ts
+ *  parseFrontmatter, reused) instead of gray-matter, so an unterminated block, a `mode`
+ *  outside plan|act, or an empty body skips the file with a boot warning (never a throw);
+ *  substitution is ONE pass, so substituted text is never re-scanned, `$$` is a literal `$`,
+ *  and a positional `$N` is exactly one token (upstream's "last placeholder absorbs the rest",
+ *  prompt.ts:1387, is not ported); no `!\`shell\`` / `@file` injection (prompt.ts:1397-1408) —
+ *  the template reaches the model as plain text; a built-in TUI command always beats a custom
+ *  one of the same name (warned at boot); a symlinked *.md counts when it points at a file (a
+ *  dangling link is reported unreadable); boot-warning echoes and descriptions are bounded.
+ *
+ *  TUI semantics (runCustomCommand): `mode` switches through the /plan-/act path and STAYS
+ *  switched after the run — the switch is a durable session entry (port #20), and silently
+ *  flipping back would desynchronize the status line from the session record; `model` is set
+ *  the way /model does and restored after the run unless the user re-pointed it mid-run
+ *  (/model is not busy-gated). With planActSeparateModels off, /model mirrors writes into
+ *  both slots, so the restore does too — same as typing /model <prev> by hand. */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { AgentMode, ModeManager } from "../core/modes.ts";
+import { rovecodeHome } from "../providers/auth.ts";
+import { parseFrontmatter } from "../skills/index.ts";
+import { togglePlanAct, type ModeStateSlice } from "./modes-cmd.ts";
+import type { Renderer, SlashCommand } from "./renderer.ts";
+
+export type CommandScope = "project" | "user";
+
+export interface CustomCommand {
+  /** `/name`: the filename sans `.md`, lowercased; must match [a-z0-9_-]+ */
+  name: string;
+  description: string;
+  /** frontmatter `model:` — per-run override, applied the way /model does */
+  model?: string;
+  /** frontmatter `mode:` — the run happens in this plan/act mode */
+  mode?: AgentMode;
+  /** the markdown body: the prompt template */
+  body: string;
+  /** placeholders the template uses, for /help — opencode hints(): "$1 $2 $ARGUMENTS" */
+  hints: string[];
+  path: string;
+  scope: CommandScope;
+}
+
+export interface ParsedCommandFile { description?: string; model?: string; mode?: AgentMode; body: string }
+
+const NAME_RE = /^[a-z0-9_-]+$/;
+/** opencode prompt.ts:1594 minus its `[Image N]` alternative (no image parts reach this path). */
+const ARGS_RE = /(?:"[^"]*"|'[^']*'|[^\s"']+)/g;
+const QUOTE_TRIM_RE = /^["']|["']$/g;
+/** one pass: `$$` (literal), `$ARGUMENTS`, `$1`..`$9` */
+const PLACEHOLDER_RE = /\$(\$|ARGUMENTS|[1-9])/g;
+/** /help + palette rows stay one line; a 20k-char frontmatter field must not become one */
+const MAX_DESCRIPTION_CHARS = 200;
+
+/** Bounded echo (todo.ts `show` idiom): file content quoted back in a warning is clipped. */
+function clip(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + "…" : s;
+}
+
+// ---------- file format ----------
+
+/** Optional `---` frontmatter + body → command fields. `{ error }` names why a file must be
+ *  skipped (unterminated block, `mode` outside plan|act, empty body). Never throws. */
+export function parseCommandFile(text: string): ParsedCommandFile | { error: string } {
+  let src = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text; // drop a UTF-8 BOM
+  let fm: Record<string, string> = {};
+  let body = src;
+  if (src.startsWith("---")) {
+    if (!src.endsWith("\n")) src += "\n"; // parseFrontmatter finds the closing fence by its line end
+    const parsed = parseFrontmatter(src);
+    if (!parsed) return { error: "unterminated frontmatter (no closing ---)" };
+    fm = parsed.fm; body = parsed.body;
+  }
+  body = body.trim();
+  if (body === "") return { error: "empty command body (nothing to send)" };
+  const field = (k: string): string | undefined => { const v = fm[k]?.trim(); return v ? v : undefined; };
+  const mode = field("mode");
+  if (mode !== undefined && mode !== "plan" && mode !== "act") return { error: `mode must be "plan" or "act" (got "${clip(mode, 40)}")` }; // LOW-2: bounded echo
+  return { description: field("description"), model: field("model"), mode, body };
+}
+
+/** Placeholders a template uses: `$1..$9` sorted, then `$ARGUMENTS` (command/index.ts:36-44).
+ *  `$$` escapes are dropped first so `$$1` does not count. */
+export function hints(body: string): string[] {
+  const src = body.replace(/\$\$/g, "");
+  const out = [...new Set(src.match(/\$[1-9]/g) ?? [])].sort();
+  if (src.includes("$ARGUMENTS")) out.push("$ARGUMENTS");
+  return out;
+}
+
+// ---------- discovery ----------
+
+export interface DiscoverOptions {
+  /** user-scope rovecode dir; default rovecodeHome() (ROVECODE_HOME → ~/.rovecode). Commands: `<home>/commands` */
+  home?: string;
+  /** built-in command names — a custom command with one of these names is dropped, with a warning */
+  reserved?: readonly string[];
+  /** more command folders — a plugin's (src/plugins) — scanned AFTER the folder of the same scope, so
+   *  your own `~/.rovecode/commands/x.md` or `.rovecode/commands/x.md` keeps `/x` over a plugin's */
+  extraDirs?: readonly { dir: string; scope: CommandScope }[];
+}
+
+export interface DiscoveredCommands { commands: CustomCommand[]; warnings: string[] }
+
+/** Scan `<home>/commands` then `<cwd>/.rovecode/commands`; a later (project) entry replaces an
+ *  earlier (user) one of the same name. Missing dirs are silent (the common case); every
+ *  other problem is a warning for the boot transcript, never a throw. Sorted by name. */
+export function discoverCommands(cwd: string, opts: DiscoverOptions = {}): DiscoveredCommands {
+  const warnings: string[] = [];
+  const reserved = new Set(opts.reserved ?? []);
+  const userDir = join(opts.home ?? rovecodeHome(), "commands");
+  const projectDir = join(cwd, ".rovecode", "commands");
+  const extra = (scope: CommandScope): [CommandScope, string][] => (opts.extraDirs ?? []).filter((e) => e.scope === scope).map((e) => [scope, e.dir]);
+  // cwd IS the rovecode home: one directory, scanned once (gemini-cli FileCommandLoader.ts:221-228)
+  const dirs: [CommandScope, string][] = resolve(userDir) === resolve(projectDir)
+    ? [["project", projectDir], ...extra("user"), ...extra("project")]
+    : [["user", userDir], ...extra("user"), ["project", projectDir], ...extra("project")];
+  const byName = new Map<string, CustomCommand>();
+  for (const [scope, dir] of dirs) {
+    for (const cmd of scanCommandDir(dir, scope, warnings)) {
+      // the verdict first, the path last: an 80-column terminal wraps a long path mid-line and the
+      // sentence must survive at the line start
+      if (reserved.has(cmd.name)) { warnings.push(`/${cmd.name} is a built-in command — built-in kept (${cmd.path})`); continue; }
+      const prev = byName.get(cmd.name);
+      if (prev?.scope === scope) { warnings.push(`${cmd.path}: /${cmd.name} already defined by ${prev.path} — first kept`); continue; }
+      byName.set(cmd.name, cmd); // project (scanned second) shadows user
+    }
+  }
+  return { commands: [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)), warnings };
+}
+
+/** LOW-3: a symlinked `*.md` counts when its target is a file (a link to a directory is skipped
+ *  like any directory); a DANGLING link stays in the list so the read below reports it unreadable. */
+function linksToFile(path: string): boolean {
+  try { return statSync(path).isFile(); } catch { return true; }
+}
+
+/** One directory's `*.md` files (top level only, sorted), each parsed or warned about. */
+function scanCommandDir(dir: string, scope: CommandScope, warnings: string[]): CustomCommand[] {
+  let files: string[];
+  try {
+    files = readdirSync(dir, { withFileTypes: true })
+      .filter((e) => /\.md$/i.test(e.name) && (e.isFile() || (e.isSymbolicLink() && linksToFile(join(dir, e.name)))))
+      .map((e) => e.name).sort();
+  } catch {
+    return []; // no such directory — silent, like the skills store
+  }
+  const out: CustomCommand[] = [];
+  for (const file of files) {
+    const path = join(dir, file);
+    const name = file.slice(0, -3).toLowerCase();
+    if (!NAME_RE.test(name)) { warnings.push(`${path}: skipped — command name "${name}" must match [a-z0-9_-]+`); continue; }
+    let text: string;
+    try {
+      text = readFileSync(path, "utf8");
+    } catch (e) {
+      warnings.push(`${path}: skipped — unreadable (${e instanceof Error ? e.message : String(e)})`);
+      continue;
+    }
+    const parsed = parseCommandFile(text);
+    if ("error" in parsed) { warnings.push(`${path}: skipped — ${parsed.error}`); continue; }
+    out.push({
+      name, description: clip(parsed.description ?? `custom command (${file})`, MAX_DESCRIPTION_CHARS), model: parsed.model, mode: parsed.mode,
+      body: parsed.body, hints: hints(parsed.body), path, scope,
+    });
+  }
+  return out;
+}
+
+// ---------- templating ----------
+
+/** Template → prompt. `$ARGUMENTS` = the whole argument string, `$1..$9` = one quote-aware token
+ *  each ("" when missing), `$$` = a literal `$`. One pass, so substituted text is never
+ *  re-scanned. A template without placeholders gets the arguments appended after a blank line
+ *  (prompt.ts:1393-1395) so nothing the user typed is silently dropped. */
+export function renderCommand(cmd: Pick<CustomCommand, "body">, argString: string): string {
+  const raw = argString.trim();
+  const args = (raw.match(ARGS_RE) ?? []).map((a) => a.replace(QUOTE_TRIM_RE, ""));
+  let placeholder = false;
+  const out = cmd.body.replace(PLACEHOLDER_RE, (_m, tok: string) => {
+    if (tok === "$") return "$";
+    placeholder = true;
+    return tok === "ARGUMENTS" ? raw : (args[Number(tok) - 1] ?? "");
+  });
+  return placeholder || raw === "" ? out : `${out}\n\n${raw}`;
+}
+
+/** `rovecode run "/name args"` hook (main.ts call sites — see the port notes): a leading `/name`
+ *  that names a discovered command renders to its prompt; anything else passes through
+ *  verbatim. `model`/`mode` are TUI semantics and are not applied here. */
+export function expandSlashPrompt(prompt: string, cwd: string, opts: DiscoverOptions = {}): string {
+  const m = /^\/(\S+)(?:\s+([\s\S]*))?$/.exec(prompt.trim());
+  if (!m) return prompt;
+  const cmd = discoverCommands(cwd, opts).commands.find((c) => c.name === m[1]!.toLowerCase());
+  return cmd ? renderCommand(cmd, m[2] ?? "") : prompt;
+}
+
+// ---------- TUI surface ----------
+
+/** Entries for Renderer.setCommands (editor autocomplete) — appended after the built-ins. */
+export function commandsForPalette(list: readonly CustomCommand[]): SlashCommand[] {
+  return list.map((c) => ({ name: c.name, description: c.description }));
+}
+
+/** `/help` tail: "" when there are none, else a "custom:" section (name, hints, description, scope). */
+export function helpForCommands(list: readonly CustomCommand[]): string {
+  if (list.length === 0) return "";
+  return "\ncustom:\n" + list
+    .map((c) => `/${c.name}${c.hints.length > 0 ? " " + c.hints.join(" ") : ""} — ${c.description} (${c.scope})`)
+    .join("\n");
+}
+
+/** What the TUI hands the dispatcher (app.ts builds it once; state is read live). */
+export interface CustomCommandCtx {
+  renderer: Renderer;
+  modes: ModeManager;
+  state: ModeStateSlice;
+  pushStatus: () => void;
+  /** the plain user-turn path (app.ts `submit`): echo, flush a pending mode switch, start the run */
+  submit: (text: string) => Promise<void>;
+}
+
+/** handleSlash `default:` hook: false when `name` is not a custom command (the caller reports
+ *  "unknown command"); true after kicking off the run — fire-and-forget, the same shape as the
+ *  other async slash commands. */
+export function dispatchCustomCommand(ctx: CustomCommandCtx, list: readonly CustomCommand[], name: string, arg: string): boolean {
+  const cmd = list.find((c) => c.name === name);
+  if (!cmd) return false;
+  void runCustomCommand(ctx, cmd, arg);
+  return true;
+}
+
+/** Busy-gated like /plan and /checkpoints — a rendered prompt with a model/mode attached cannot
+ *  be queued as steering. `mode` → togglePlanAct (stays); `model` → setModel like /model,
+ *  restored after the run unless the user re-pointed it meanwhile (header: TUI semantics). */
+export async function runCustomCommand(ctx: CustomCommandCtx, cmd: CustomCommand, arg: string): Promise<void> {
+  if (ctx.state.busy) { ctx.renderer.addSystemNote("finish or interrupt the run first (Esc)", "warn"); return; }
+  if (cmd.mode !== undefined && cmd.mode !== ctx.modes.mode) togglePlanAct(ctx.modes, cmd.mode, ctx.state, ctx.renderer, ctx.pushStatus);
+  const prev = ctx.modes.modelFor().model;
+  const override = cmd.model !== undefined && cmd.model !== prev;
+  if (override) {
+    ctx.modes.setModel({ model: cmd.model });
+    ctx.state.model = ctx.modes.modelFor().model;
+    ctx.renderer.addSystemNote(`model → ${cmd.model} for /${cmd.name} (restored after the run)`);
+    ctx.pushStatus();
+  }
+  try {
+    await ctx.submit(renderCommand(cmd, arg));
+  } finally {
+    if (override && ctx.modes.modelFor().model === cmd.model) {
+      ctx.modes.setModel({ model: prev }); ctx.state.model = prev; ctx.pushStatus();
+    }
+  }
+}