rovecode 0.4.0-beta.2 → 0.4.0

package/src/sextant/sextant-bridge.ts

@@ -0,0 +1,174 @@
+/** Sextant bridge (port #44): pure helpers between rovecode's app/Renderer seam and the surface state —
+ *  a user line → row (image chips split off), a replayed tool card → row, how many duplicate app
+ *  notes a RunEvent triggers (the #41 reducer already produced the row), and the RunEvent / TaskInfo
+ *  → rovecode forwarding table (#45's report: start/read/edit/write/remove/run/glob/plan/spawn/
+ *  permission/fetch/crew/tinker on starts — every tool says its specific thing, a risky command gets
+ *  the risk line — + observe over written content and edit newLines; grep's count, tool_fail/pass/fail + a fail-line
+ *  reaction on tool ends; denied on a permission refusal; done/stopped/error at run_end; laneDone /
+ *  laneFail from the task manager). Pure: `now` is a parameter, no I/O, no timers. */
+
+import type { RunEvent } from "../core/types.ts";
+import type { TaskInfo } from "../core/tasks.ts";
+import type { Pet, PetEventData } from "./pet.ts";
+import { baseName, describeCall, relPath } from "./tool-rows.ts";
+import { splitAttached } from "./mentions.ts";
+import type { MessageRow, ToolRow } from "./types.ts";
+
+type UserRow = Extract<MessageRow, { kind: "user" }>;
+const CHIP_RE = /\[image: ([^\]]*)\]/g;
+const TEST_CMD = /\b(tests?|vitest|jest|pytest|mocha|spec)\b/i;
+/** commands worth a second look before they run: recursive deletes, force pushes, history rewrites,
+ *  world-writable modes, piping the network into a shell, dropping tables */
+const RISKY_CMD = /\brm\s+(-[a-z]*r[a-z]*f|-[a-z]*f[a-z]*r)\b|--force\b|\bpush\s+-f\b|\breset\s+--hard\b|\bchmod\s+777\b|\bcurl\b[^|]*\|\s*(ba|z)?sh\b|\bdrop\s+(table|database)\b/i;
+const RUN_TOOLS = new Set(["bash", "shell", "run"]);
+const REMOVE_TOOLS = new Set(["remove", "rm", "delete", "unlink"]);
+
+const rec = (v: unknown): Record<string, unknown> => (v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+const oneLine = (s: string, max = 40): string => s.replace(/\s+/g, " ").trim().slice(0, max);
+
+/** tui/attach.ts userTurnLine: the text, then ONE line of `[image: name]` chips (or chips alone) */
+export function userRow(line: string, now: number): UserRow {
+  const lines = line.split("\n");
+  const last = lines[lines.length - 1] ?? "";
+  const chips = [...last.matchAll(CHIP_RE)].map((m) => m[1]!);
+  const chipLine = chips.length > 0 && last.replace(CHIP_RE, "").trim() === "";
+  // `@file` read blocks (mentions.ts) stay out of the panel: the typed text and one chip per file
+  const { text, files } = splitAttached((chipLine ? lines.slice(0, -1) : lines).join("\n"));
+  const row: UserRow = { kind: "user", text, at: now };
+  if (chipLine) row.images = chips;
+  if (files.length > 0) row.files = files;
+  return row;
+}
+
+/** args for a replayed tool card: session-cmd replayTranscript hands the renderer a ≤120-char JSON
+ *  slice — the whole object when it still parses, else the path/command/pattern/url/question/label
+ *  fields recovered from the intact prefix (a truncated escape yields nothing for that key) */
+export function argsFromPreview(preview: string): Record<string, unknown> {
+  try {
+    const v: unknown = JSON.parse(preview);
+    if (v && typeof v === "object" && !Array.isArray(v)) return v as Record<string, unknown>;
+  } catch { /* truncated — fall through */ }
+  const out: Record<string, unknown> = {};
+  for (const k of ["path", "command", "pattern", "url", "question", "label"]) {
+    const m = new RegExp(`"${k}":"((?:[^"\\\\]|\\\\.)*)"`).exec(preview);
+    if (!m) continue;
+    try { out[k] = JSON.parse(`"${m[1]}"`); } catch { /* unterminated escape */ }
+  }
+  return out;
+}
+
+/** a replayed tool card (the renderer is NOT busy: session history) → a settled row; toolEnd fills ok/detail */
+export function replayToolRow(callId: string, tool: string, argsPreview: string, cwd: string): ToolRow {
+  const d = describeCall(tool, argsFromPreview(argsPreview), cwd);
+  const row: ToolRow = { kind: "tool", callId, tool, verb: d.verb, label: d.label, running: false };
+  if (d.path) row.path = d.path;
+  if (d.verb === "edit" || d.verb === "write") { row.add = d.add; row.del = d.del; }
+  return row;
+}
+
+/** how many addSystemNote calls app.ts makes for this event that duplicate a reducer row: the
+ *  compaction note, "↪ steering applied", and the run_end error/warn line (none for `done`) — the
+ *  renderer drops exactly that many, and only those */
+export function duplicateNotes(ev: RunEvent): number {
+  if (ev.type === "compaction" || ev.type === "steer") return 1;
+  if (ev.type === "run_end") return ev.status === "done" ? 0 : 1;
+  return 0;
+}
+
+/** what the renderer remembers per live call so the end event can find its tool/command */
+export interface LiveCall { tool: string; cmd: string }
+
+/** RunEvent → rovecode (see the header table) */
+export function petOnEvent(pet: Pet, ev: RunEvent, calls: Map<string, LiveCall>, cwd: string, now: number): void {
+  switch (ev.type) {
+    case "run_start": pet.event("start", undefined, now); break;
+    case "tool_execution_start": {
+      const a = rec(ev.args), f = baseName(relPath(cwd, str(a.path))) || "file";
+      calls.set(ev.callId, { tool: ev.tool, cmd: str(a.command) || str(a.cmd) });
+      petOnStart(pet, ev.tool, a, f, now);
+      break;
+    }
+    case "tool_execution_end": {
+      const c = calls.get(ev.callId);
+      calls.delete(ev.callId);
+      petOnEnd(pet, c, ev.ok, ev.output, now);
+      break;
+    }
+    case "tool_call_failed":
+      calls.delete(ev.callId);
+      pet.event(ev.reason === "permission_denied" ? "denied" : "tool_fail", undefined, now);
+      break;
+    case "run_end":
+      calls.clear();
+      pet.event(ev.status === "done" ? "done" : ev.status === "error" ? "error" : "stopped", undefined, now);
+      break;
+    default: break;
+  }
+}
+
+/** the host of a URL for the fetch quip; a bare or broken URL keeps its first 30 chars */
+const hostOf = (u: string): string => { try { return new URL(u).host || oneLine(u, 30); } catch { return oneLine(u, 30) || "the web"; } };
+
+/** Every tool the agent has says something SPECIFIC — the file, the pattern, the host, the child,
+ *  the thing being tinkered with — because a bubble that only says "working" is worse than silence.
+ *  Kinds are the existing ones where they fit (a directory listing is a read, an ask is a permission,
+ *  a search start is glob's line with the pattern); fetch / crew / tinker are the three acts that
+ *  had none. Unknown tools (an MCP server's own, a future one) fall to tinker with their name. */
+function petOnStart(pet: Pet, tool: string, a: Record<string, unknown>, f: string, now: number): void {
+  const data: PetEventData = { f };
+  if (tool === "read") pet.event("read", data, now);
+  else if (tool === "edit") {
+    pet.event("edit", data, now);
+    const lines = (Array.isArray(a.edits) ? a.edits : []).flatMap((e) => { const nl = rec(e).newLines; return Array.isArray(nl) ? nl.map(String) : []; });
+    if (lines.length) pet.observe(lines.join("\n"), "ins", now);
+  } else if (tool === "write") { pet.event("write", data, now); if (str(a.content)) pet.observe(str(a.content), "ins", now); }
+  else if (REMOVE_TOOLS.has(tool)) pet.event("remove", data, now);
+  else if (RUN_TOOLS.has(tool)) {
+    // a destructive-looking command gets the risk line instead of "thunder time" — keyed off the
+    // command text the agent asked for, never off an error message (the validator owns those)
+    const cmd = str(a.command) || str(a.cmd);
+    if (RISKY_CMD.test(cmd)) pet.react("risk", now); else pet.event("run", undefined, now);
+  }
+  else if (tool === "glob" || tool === "grep") pet.event("glob", { q: oneLine(str(a.pattern), 24) || "it" }, now);
+  else if (tool === "ls") pet.event("read", { f: (baseName(str(a.path)) || ".") + "/" }, now);
+  else if (tool === "web_fetch") pet.event("fetch", { f: hostOf(str(a.url)) }, now);
+  else if (tool === "todo_write") { const n = Array.isArray(a.todos) ? a.todos.length : 0; if (n) pet.event("plan", { n }, now); }
+  else if (tool === "todo_read") pet.event("read", { f: "the plan" }, now);
+  else if (tool === "ask_user") pet.event("permission", undefined, now);
+  else if (tool === "task") pet.event("spawn", { a: oneLine(str(a.label) || str(a.agent) || "a worker", 20) }, now);
+  else if (tool === "task_status") pet.event("crew", { a: str(a.action) === "list" ? "the crew" : oneLine(str(a.id), 20) || "the crew" }, now);
+  else pet.event("tinker", { f: tinkerTarget(tool, a) }, now);
+}
+
+/** what the housekeeping tools are about, by name: `providers`, `skills`, `memory`, `notes`, `search/issues` */
+function tinkerTarget(tool: string, a: Record<string, unknown>): string {
+  if (tool.startsWith("provider_")) return str(a.action) === "use" && str(a.selector) ? oneLine(str(a.selector), 24) : "providers";
+  if (tool === "skill_view") return oneLine(str(a.name) || str(a.skill), 24) || "a skill";
+  if (tool === "skills_list") return "the skills";
+  if (tool === "memory_edit") return "memory";
+  if (tool === "recall") return oneLine(str(a.query), 24) ? `notes on ${oneLine(str(a.query), 24)}` : "the notes";
+  if (tool === "eval_cell") return "a scratch cell";
+  if (tool === "mcp_call" || tool === "mcp_list") return [str(a.server), str(a.tool)].filter(Boolean).map((s) => oneLine(s, 16)).join(" ") || "mcp";
+  return oneLine(tool, 24);
+}
+
+function petOnEnd(pet: Pet, c: LiveCall | undefined, ok: boolean, output: string, now: number): void {
+  if (c && RUN_TOOLS.has(c.tool)) {
+    const lines = output.replace(/^exit=-?\d+\r?\n?/, "").split(/\r?\n/).filter((l) => l.trim());
+    const r = oneLine(lines[lines.length - 1] ?? "");
+    if (TEST_CMD.test(c.cmd)) pet.event(ok ? "pass" : "fail", { r }, now);
+    else if (!ok) pet.event("tool_fail", undefined, now);
+    if (lines.some((l) => /^\s*FAIL\b/.test(l))) pet.react("fail-line", now);
+    else if (ok && lines.some((l) => /^\s*PASS\b/.test(l))) pet.react("pass-line", now);
+    return;
+  }
+  if (!ok) { pet.event("tool_fail", undefined, now); return; }
+  if (c?.tool === "grep") pet.event("grep", { n: output.split(/\r?\n/).filter((l) => l.trim() && !l.startsWith("(")).length }, now);
+}
+
+/** TaskManager status transitions → laneDone / laneFail quips (queued/running/cancelled say nothing) */
+export function petOnTask(pet: Pet, t: TaskInfo, now: number): void {
+  if (t.status === "done") pet.event("laneDone", { a: oneLine(t.label, 20), r: oneLine(t.summary ?? "done") }, now);
+  else if (t.status === "failed") pet.event("laneFail", { a: oneLine(t.label, 20), r: oneLine(t.error ?? "failed") }, now);
+}

package/src/sextant/sextant-cards.ts

@@ -0,0 +1,142 @@
+/** Sextant cards (port #44): the modal seams of the Renderer — the approval card (once / always /
+ *  deny), the ask_user question card (options / free text / skip, dismissed by the run's abort signal)
+ *  and the pickOne picker (the #43 palette with `pick:<value>` rows: Enter resolves the fuzzy-selected
+ *  row, Esc / ⌃k / ⌃p / a click outside resolves null). ONE card at a time: a second approval waits
+ *  for the first to settle, a second concurrent question is rejected (renderer.ts contract), a new
+ *  picker cancels the previous one; settleAll() (renderer stop) resolves everything with deny / null so
+ *  no awaiting caller is ever pinned. keys.ts owns the key handling (onCardKey / onPaletteKey) and
+ *  nulls s.card before calling resolve — this class only owns the promises and the state hand-off. */
+
+import type { ApprovalAnswer, PickItem, QuestionAnswer, QuestionPrompt } from "../tui/renderer.ts";
+import { fuzzy } from "./engine.ts";
+import { closePalette, openPalette, paletteVisible } from "./overlays.ts";
+import type { CardState, InputEvent, SextantState } from "./types.ts";
+import { notify } from "./model.ts";
+
+/** palette action prefix of a picker row; the value follows verbatim (it may contain ":") */
+export const PICK = "pick:";
+
+export interface CardHostDeps {
+  state: SextantState;
+  /** request a repaint */
+  dirty(): void;
+  /** the renderer stopped: a card opened now resolves its fallback at once */
+  stopped(): boolean;
+  /** an approval card opened / was allowed (the pet's permission / allowed quips) */
+  onApprovalOpen?(): void;
+  onAllowed?(): void;
+  /** the surface clock, for the "needs you" notice a card raises (model.ts notify); Date.now() when absent */
+  clock?(): number;
+}
+
+/** tools whose approval card offers the accept-edits door */
+const EDIT_TOOLS = new Set(["edit", "write"]);
+
+export class CardHost {
+  /** cancel thunks of every open or queued card and the picker */
+  private readonly pending = new Set<() => void>();
+  private queue: Promise<void> = Promise.resolve();
+  private picker: ((v: string | null) => void) | null = null;
+
+  constructor(private readonly d: CardHostDeps) {}
+
+  /** settle everything with its fallback (deny / null) */
+  settleAll(): void { for (const cancel of [...this.pending]) cancel(); }
+  get pickerOpen(): boolean { return this.picker !== null; }
+
+  approval(tool: string, argsPreview: string, detail: string | undefined): Promise<ApprovalAnswer> {
+    return this.enqueue<ApprovalAnswer>("deny", (settle) => {
+      this.d.onApprovalOpen?.();
+      // the `all edits` door is offered only where it means something: a write/edit card. On a bash or
+      // a network card it would read as "allow everything", which is what auto mode is for.
+      const verdicts: readonly ApprovalAnswer[] = EDIT_TOOLS.has(tool)
+        ? ["once", "always", "all-edits", "deny"]
+        : ["once", "always", "deny"];
+      const card: CardState = { kind: "approval", tool, argsPreview, verdicts, selected: 0, resolve: (a) => { if (a !== "deny") this.d.onAllowed?.(); settle(a); } };
+      if (detail) card.detail = detail;
+      return card;
+    });
+  }
+
+  /** cards open ONE at a time: the next waits for the current to settle */
+  private enqueue<T>(fallback: T, make: (settle: (v: T) => void) => CardState): Promise<T> {
+    return new Promise<T>((resolve) => {
+      const open = (): Promise<void> => new Promise<void>((done) => {
+        if (this.d.stopped()) { resolve(fallback); done(); return; }
+        let card: CardState | null = null, settled = false;
+        const settle = (v: T): void => {
+          if (settled) return;
+          settled = true; this.pending.delete(cancel);
+          if (card && this.d.state.card === card) this.d.state.card = null;
+          this.d.dirty(); resolve(v); done();
+        };
+        const cancel = (): void => settle(fallback);
+        this.pending.add(cancel);
+        card = make(settle);
+        this.d.state.card = card; notify(this.d.state, "tool" in card ? `needs you: ${card.tool}` : "needs you: a question", this.d.clock?.() ?? Date.now(), "warn", "approval"); this.d.dirty();
+      });
+      this.queue = this.queue.then(open, open);
+    });
+  }
+
+  /** the question card; `signal` abort dismisses it (null); a SECOND concurrent ask is rejected */
+  question(q: QuestionPrompt, signal?: AbortSignal): Promise<QuestionAnswer | null> {
+    if (this.d.stopped() || signal?.aborted) return Promise.resolve(null);
+    if (this.d.state.card) return Promise.reject(new Error("a question or approval card is already open"));
+    return new Promise((resolve) => {
+      let settled = false;
+      const settle = (a: QuestionAnswer | null): void => {
+        if (settled) return;
+        settled = true; this.pending.delete(cancel); signal?.removeEventListener("abort", cancel);
+        if (this.d.state.card === card) this.d.state.card = null;
+        this.d.dirty(); resolve(a);
+      };
+      const cancel = (): void => settle(null);
+      const card: CardState = {
+        kind: "question", prompt: q, selected: 0, freeText: "",
+        resolve: (a) => settle(a === null ? null : a.kind === "option" ? { choice: a.index, label: q.options?.[a.index] } : { text: a.text }),
+      };
+      this.pending.add(cancel); signal?.addEventListener("abort", cancel, { once: true });
+      this.d.state.card = card; notify(this.d.state, "tool" in card ? `needs you: ${card.tool}` : "needs you: a question", this.d.clock?.() ?? Date.now(), "warn", "approval"); this.d.dirty();
+    });
+  }
+
+  /** the palette as a picker: items become `pick:<value>` rows under `title` */
+  pick(items: PickItem[], title?: string): Promise<string | null> {
+    if (this.d.stopped() || items.length === 0) return Promise.resolve(null);
+    this.picker?.(null);
+    return new Promise((resolve) => {
+      const s = this.d.state;
+      // the title is the BOX's, not a group row: as a group it was painted unclipped inside the list
+      // and ran past the border. Rows keep one short group so the list has no repeated header.
+      openPalette(s, items.map((i) => ({
+        label: i.description ? `${i.label} · ${i.description}` : i.label, group: "", action: PICK + i.value,
+        ...(i.description !== undefined ? { hint: i.description } : {}),
+      })), title ?? "pick one");
+      const settle = (v: string | null): void => {
+        if (this.picker !== settle) return;
+        this.picker = null; this.pending.delete(cancel);
+        if (s.palette?.items.some((it) => it.action.startsWith(PICK))) closePalette(s);
+        this.d.dirty(); resolve(v);
+      };
+      const cancel = (): void => settle(null);
+      this.picker = settle; this.pending.add(cancel); this.d.dirty();
+    });
+  }
+
+  /** Enter / Esc while the picker's palette is open — true = swallowed (keys.ts must not see them) */
+  interceptKey(ev: InputEvent): boolean {
+    const s = this.d.state;
+    if (!this.picker || !s.palette || ev.type !== "key" || ev.ctrl) return false;
+    if (ev.name === "enter") {
+      const it = paletteVisible(s.palette, fuzzy)[s.palette.sel];
+      this.picker(it && it.action.startsWith(PICK) ? it.action.slice(PICK.length) : null);
+      return true;
+    }
+    if (ev.name === "escape") { this.picker(null); return true; }
+    return false;
+  }
+
+  /** after keys.handleInput: ⌃k / ⌃p / a click outside closed the palette → the picker resolves null */
+  afterKey(): void { if (this.picker && !this.d.state.palette) this.picker(null); }
+}

package/src/sextant/sextant-diff-base.ts

@@ -0,0 +1,63 @@
+/** Sextant diff base (port #44 fix wave): the PRE-EDIT content of a file the agent edited without a
+ *  gate (yolo, `always`, an auto-allowed rule), rebuilt after the fact. Why after: the renderer sees
+ *  tool_execution_start only when the loop's event pump flushes (core/loop.ts pumps every 5 ms), and
+ *  rovecode's edit/write tools have already written synchronously by then (core/tools.ts: emit → await
+ *  execute, whose first statements are the fs calls) — a disk snapshot taken at the start event IS the
+ *  post-edit file. What the ops carry is enough to walk the edit back: each hashline op replaced ONE
+ *  anchored line (anchorLine in the original, verified by lineHash) with newLines, applied bottom-up
+ *  (coding/hashline.ts applyEditsToContent), so undoing them top-down puts every new block at
+ *  anchorLine − 1 of the partially restored file. The only unknown per op is the replaced line's text;
+ *  any line whose lineHash equals the anchor — in git HEAD, or elsewhere in the file — is a candidate,
+ *  and the file TAG the ops carry (fileTag of the content the model read) proves a rebuild right or
+ *  rejects it. Pure: no I/O, no clock. */
+
+import { fileTag, lineHash, type EditOp } from "../coding/hashline.ts";
+
+export type HashlineOp = Pick<EditOp, "tag" | "anchorLine" | "anchorHash" | "newLines">;
+
+/** candidate combinations tried before giving up (whitespace variants of one line share a hash) */
+const MAX_TRIES = 8;
+
+/** the hashline ops of an edit call's args (tool_execution_start.args); [] when any op is malformed */
+export function editOpsOf(args: unknown): HashlineOp[] {
+  const a = args && typeof args === "object" && !Array.isArray(args) ? (args as { edits?: unknown }) : {};
+  if (!Array.isArray(a.edits)) return [];
+  const out: HashlineOp[] = [];
+  for (const e of a.edits) {
+    const r = e && typeof e === "object" && !Array.isArray(e) ? (e as Record<string, unknown>) : {};
+    const lines = Array.isArray(r.newLines) && r.newLines.every((l) => typeof l === "string") ? (r.newLines as string[]) : null;
+    if (typeof r.tag !== "string" || typeof r.anchorLine !== "number" || !Number.isInteger(r.anchorLine) || typeof r.anchorHash !== "string" || !lines) return [];
+    out.push({ tag: r.tag, anchorLine: r.anchorLine, anchorHash: r.anchorHash, newLines: lines });
+  }
+  return out;
+}
+
+/** The content before `ops` were applied to it, given the file on disk NOW (`disk`) and the committed
+ *  content when git has one (`head`) — or null when it cannot be proven: no op, ops that disagree on the
+ *  TAG or share a line, a block on disk that is not its op's newLines, an anchor no known line hashes to,
+ *  or no candidate combination that reproduces the TAG. Null means "no pre-edit base" — never a guess. */
+export function reconstructBefore(disk: string, ops: readonly HashlineOp[], head: string | null): string | null {
+  if (!ops.length) return null;
+  const tag = ops[0]!.tag;
+  if (ops.some((o) => o.tag !== tag)) return null;
+  const sorted = [...ops].sort((a, b) => a.anchorLine - b.anchorLine);
+  if (sorted.some((o, i) => i > 0 && o.anchorLine === sorted[i - 1]!.anchorLine)) return null;
+  const post = disk.split("\n");
+  // HEAD lines first: the replaced line is most likely intact there; then the file itself (an unchanged twin)
+  const pool = [...(head ?? "").split("\n"), ...post];
+  const candidates = sorted.map((o) => [...new Set(pool.filter((l) => lineHash(l) === o.anchorHash))]);
+  if (candidates.some((c) => c.length === 0)) return null;
+  let tries = 0;
+  const attempt = (i: number, lines: string[]): string | null => {
+    if (i === sorted.length) { const text = lines.join("\n"); return fileTag(text) === tag ? text : null; }
+    const o = sorted[i]!, at = o.anchorLine - 1, n = o.newLines.length;
+    if (at < 0 || at > lines.length || o.newLines.some((l, k) => lines[at + k] !== l)) return null;
+    for (const text of candidates[i]!) {
+      if (++tries > MAX_TRIES) return null;
+      const r = attempt(i + 1, [...lines.slice(0, at), text, ...lines.slice(at + n)]);
+      if (r !== null) return r;
+    }
+    return null;
+  };
+  return attempt(0, post);
+}

package/src/sextant/sextant-files.ts

@@ -0,0 +1,154 @@
+/** Sextant repo I/O (port #44): the files-panel list, git statuses + branch, bounded file reads for
+ *  the code panel and the hunks the diff view shows. Together with git-status.ts this is the ONLY I/O
+ *  behind the surface, and the renderer runs it OFF the frame loop (sextant-repo.ts: a setTimeout(0)
+ *  scheduled from the tick, then the `…Async` forms here so git runs beside the loop — a spawnSync
+ *  must not stall a half-painted frame). The file list is `git ls-files -z --cached --others
+ *  --exclude-standard` (the coding/repomap-files.ts gitListFiles command, issued through the injectable
+ *  sextant GitRunner so tests never spawn) or a bounded deterministic walk when git cannot answer.
+ *  Nothing here throws: null/[] instead. The sync forms stay for synchronous callers and as the parity
+ *  oracle of the async ones. */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { buildHunks, diffOps, opStats, toDiffHunk } from "./engine.ts";
+import {
+  gitBranch, gitBranchAsync, gitHeadContent, gitHeadContentAsync, gitPorcelain, gitPorcelainAsync, spawnGit, spawnGitAsync,
+  type GitRunner, type GitRunnerAsync,
+} from "./git-status.ts";
+import { reconstructBefore, type HashlineOp } from "./sextant-diff-base.ts";
+import type { DiffHunk, FileStatus } from "./types.ts";
+
+/** walk bound (coding/repomap-files.ts MAX_SRC_FILES) */
+export const MAX_FILES = 2000;
+/** a file larger than this is not shown in the code panel (`cannot read`) */
+export const MAX_FILE_BYTES = 512 * 1024;
+/** git's binary heuristic: a NUL within the first 8000 bytes */
+const BINARY_SNIFF = 8000;
+const SKIP_DIRS = new Set(["node_modules", ".git", ".rovecode", "dist", "build", "out", "coverage", ".cache"]);
+const DIFF_CONTEXT = 3;
+
+export interface RepoSnapshot {
+  /** cwd-relative posix paths (tracked + untracked-unignored, or the walk) */
+  paths: string[];
+  /** porcelain M/A/D; null = no git */
+  statuses: Map<string, FileStatus> | null;
+  branch: string | null;
+  /** the list came from git (a non-repo walks and never polls statuses) */
+  git: boolean;
+}
+
+const LS_FILES: readonly string[] = ["ls-files", "-z", "--cached", "--others", "--exclude-standard"];
+const splitZ = (r: { status: number | null; stdout: string } | null): string[] | null => (!r || r.status !== 0 ? null : r.stdout.split("\0").filter((p) => p.length > 0));
+
+/** tracked + untracked-but-not-ignored paths; null when git cannot run, the cwd is not a repo or the call fails */
+export function gitFiles(cwd: string, run: GitRunner = spawnGit): string[] | null {
+  try { return splitZ(run(LS_FILES, cwd)); } catch { return null; }
+}
+/** gitFiles, awaited */
+export async function gitFilesAsync(cwd: string, run: GitRunnerAsync = spawnGitAsync): Promise<string[] | null> {
+  try { return splitZ(await run(LS_FILES, cwd)); } catch { return null; }
+}
+
+/** bounded deterministic walk for non-repos: per-dir sorted DFS, SKIP_DIRS and dot-dirs skipped, at most `max` files */
+export function walkFiles(cwd: string, max = MAX_FILES): string[] {
+  const out: string[] = [];
+  const walk = (dir: string, rel: string): void => {
+    let names: string[];
+    try { names = readdirSync(dir); } catch { return; }
+    for (const name of names.sort()) {
+      if (out.length >= max) return;
+      const full = join(dir, name), r = rel ? `${rel}/${name}` : name;
+      let st;
+      try { st = statSync(full); } catch { continue; }
+      if (st.isDirectory()) { if (!SKIP_DIRS.has(name) && !name.startsWith(".")) walk(full, r); }
+      else if (st.isFile()) out.push(r);
+    }
+  };
+  walk(cwd, "");
+  return out;
+}
+
+/** the full snapshot: list (git or walk) + statuses + branch — three spawns, so the renderer calls it
+ *  at start and after a write/edit/bash; the idle poll uses statusOnly() */
+export function scanRepo(cwd: string, run: GitRunner = spawnGit): RepoSnapshot {
+  const fromGit = gitFiles(cwd, run);
+  return { paths: fromGit ?? walkFiles(cwd), statuses: gitPorcelain(cwd, run), branch: gitBranch(cwd, run), git: fromGit !== null };
+}
+/** scanRepo, awaited — the three read-only git calls run concurrently */
+export async function scanRepoAsync(cwd: string, run: GitRunnerAsync = spawnGitAsync): Promise<RepoSnapshot> {
+  const [fromGit, statuses, branch] = await Promise.all([gitFilesAsync(cwd, run), gitPorcelainAsync(cwd, run), gitBranchAsync(cwd, run)]);
+  return { paths: fromGit ?? walkFiles(cwd), statuses, branch, git: fromGit !== null };
+}
+
+/** the cheap idle refresh: porcelain only (new untracked files show up as A through the statuses) */
+export function statusOnly(cwd: string, run: GitRunner = spawnGit): Map<string, FileStatus> | null {
+  return gitPorcelain(cwd, run);
+}
+/** statusOnly, awaited */
+export const statusOnlyAsync = (cwd: string, run: GitRunnerAsync = spawnGitAsync): Promise<Map<string, FileStatus> | null> => gitPorcelainAsync(cwd, run);
+
+/** utf8 content of a cwd-relative path; null when missing, not a file, binary or over `maxBytes` */
+export function readFileBounded(cwd: string, rel: string, maxBytes = MAX_FILE_BYTES): string | null {
+  try {
+    const full = join(cwd, rel);
+    const st = statSync(full);
+    if (!st.isFile() || st.size > maxBytes) return null;
+    const buf = readFileSync(full);
+    const n = Math.min(buf.length, BINARY_SNIFF);
+    for (let i = 0; i < n; i++) if (buf[i] === 0) return null;
+    return buf.toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+export interface HeadDiff {
+  hunks: DiffHunk[]; add: number; del: number;
+  /** present when the base is git HEAD (no pre-edit content captured or rebuilt): the hunks are
+   *  cumulative — every uncommitted change of the file, not just the edit that landed */
+  base?: "head";
+}
+
+/** The base an edit/write is diffed against, best first: the pre-edit content the renderer captured at
+ *  approval (`before`; null = the file did not exist → all adds); the pre-edit content REBUILT from the
+ *  hashline ops when the call was not gated (yolo / always — sextant-diff-base.ts, TAG-verified); the
+ *  HEAD content (cumulative, flagged); null when only the repo question is left (the caller answers it:
+ *  "" flagged head for a file HEAD never saw, no base at all outside git). */
+function chooseBase(before: string | null | undefined, ops: readonly HashlineOp[] | undefined, disk: string | null, head: string | null): { base: string; head: boolean } | null {
+  if (before !== undefined) return { base: before ?? "", head: false };
+  const rebuilt = ops?.length && disk !== null ? reconstructBefore(disk, ops, head) : null;
+  if (rebuilt !== null) return { base: rebuilt, head: false };
+  return head !== null ? { base: head, head: true } : null;
+}
+const NEW_IN_REPO = { base: "", head: true };
+
+/** hunks (3 context lines, jsdiff Myers through engine.ts) of `disk` over `base`; null when both are nothing */
+function diffAgainst(b: { base: string; head: boolean }, disk: string | null): HeadDiff | null {
+  if (b.base === "" && disk === null) return null;
+  const ops = diffOps(b.base, disk ?? "");
+  const { a, d } = opStats(ops);
+  const out: HeadDiff = { hunks: buildHunks(ops, DIFF_CONTEXT).map(toDiffHunk), add: a, del: d };
+  if (b.head) out.base = "head";
+  return out;
+}
+
+/** The diff view's hunks for a cwd-relative path that an edit/write just changed: the disk content
+ *  against chooseBase() — the captured or rebuilt pre-edit content (edit-only, so a dirty file shows
+ *  the ONE change that landed), else HEAD (`base: "head"`), else "" inside a repo whose HEAD never saw
+ *  the file (all adds, flagged). null outside git with nothing captured, or when nothing can be read.
+ *  A deleted file diffs as all deletes. `ops` = the edit call's hashline ops (editOpsOf). */
+export function fileDiff(cwd: string, rel: string, before: string | null | undefined, run: GitRunner = spawnGit, ops?: readonly HashlineOp[]): HeadDiff | null {
+  const disk = readFileBounded(cwd, rel);
+  const b = chooseBase(before, ops, disk, gitHeadContent(cwd, rel, run)) ?? (gitBranch(cwd, run) !== null ? NEW_IN_REPO : null);
+  return b ? diffAgainst(b, disk) : null;
+}
+/** fileDiff, awaited (the renderer's path — sextant-repo.ts) */
+export async function fileDiffAsync(cwd: string, rel: string, before: string | null | undefined, run: GitRunnerAsync = spawnGitAsync, ops?: readonly HashlineOp[]): Promise<HeadDiff | null> {
+  const disk = readFileBounded(cwd, rel);
+  const b = chooseBase(before, ops, disk, await gitHeadContentAsync(cwd, rel, run)) ?? ((await gitBranchAsync(cwd, run)) !== null ? NEW_IN_REPO : null);
+  return b ? diffAgainst(b, disk) : null;
+}
+
+/** the /diff view: HEAD-vs-disk (nothing captured to fall back on), so always `base: "head"` */
+export const headDiff = (cwd: string, rel: string, run: GitRunner = spawnGit): HeadDiff | null => fileDiff(cwd, rel, undefined, run);
+export const headDiffAsync = (cwd: string, rel: string, run: GitRunnerAsync = spawnGitAsync): Promise<HeadDiff | null> => fileDiffAsync(cwd, rel, undefined, run);