rovecode 0.4.0-beta.2 → 0.4.0

package/src/sextant/local-commands.ts

@@ -0,0 +1,156 @@
+/** Sextant renderer-local commands (port #43): the slash lines and palette actions the renderer
+ *  answers itself — /help /theme /open /diff /focus /agents — the /undo /permissions /mode notes
+ *  (ALIAS_NOTE) and the state-then-hook effect helpers keys.ts shares with them. Ported from the
+ *  user's own sextant v0.4.0 prototype app.js:1024-1029 (runSlash) and :944 (openFile); split out
+ *  of keys.ts for the line budget — also the home for #44's further renderer-local commands.
+ *  Pure over (state, ctx): no clock, no timers, no process access. A state field is written BEFORE
+ *  the matching KeyCtx.local hook fires, so the renderer only loads content / rebuilds the palette.
+ *  Everything that is not renderer-local (built-ins, custom commands, `!cmd`, free text, unknown
+ *  `/x`) reaches ctx.hooks.onSubmit unchanged — app.ts handleSlash owns the rest. */
+
+import type { KeyCtx } from "./keys.ts";
+import { parseInput, resolveFile } from "./overlays.ts";
+import { expandMentions } from "./mentions.ts";
+import { THEME_ORDER, type CodeMode, type Focus, type SextantState, type ThemeName } from "./types.ts";
+import { openHelp, openNotices } from "./overlays.ts";
+
+/** prototype commands with an rovecode equivalent: a toast instead of a submission — unless
+ *  setCommands lists a custom command of that name, which then runs like any other */
+export const ALIAS_NOTE: Record<string, string> = {
+  undo: "/undo → use /checkpoints + /restore",
+  permissions: "/permissions → use /yolo",
+  mode: "/mode → use /plan or /act",
+};
+
+const isTheme = (v: string): v is ThemeName => (THEME_ORDER as readonly string[]).includes(v);
+
+// ------------------------------------------------------------------ effects (state first, then the hook)
+
+export function setTheme(s: SextantState, ctx: KeyCtx, name: ThemeName): void {
+  s.theme = name;
+  ctx.local.setTheme(name);
+}
+
+export function setMode(s: SextantState, ctx: KeyCtx, mode: CodeMode): void {
+  s.code.mode = mode;
+  s.code.scroll = 0;
+  ctx.local.setMode(mode);
+}
+
+/** the crew board in the code panel (⌃a, /agents): lane closed, focus follows */
+export function showAgents(s: SextantState, ctx: KeyCtx): void {
+  setMode(s, ctx, "agents");
+  s.code.laneOpen = false;
+  s.focus = "code";
+}
+
+/** app.js:944 — parent dirs expand, the code panel shows the file; focus is the caller's call */
+export function openFile(s: SextantState, ctx: KeyCtx, path: string): void {
+  const parts = path.split("/");
+  for (let i = 1; i < parts.length; i++) s.files.expanded.add(parts.slice(0, i).join("/"));
+  s.code.file = path;
+  s.code.mode = "code";
+  s.code.scroll = 0;
+  ctx.local.openFile(path);
+}
+
+/** the files panel only takes focus while the layout shows it (≥ 140 columns) */
+export function setFocus(s: SextantState, ctx: KeyCtx, f: Focus): void {
+  // a narrow terminal has no files column: page files into the main slot (draw-tabs.ts) instead of
+  // refusing — "the files panel needs ≥ 140 columns" was the old answer, and it left files unreachable
+  if (f === "files" && !ctx.layout.files) s.page = "files";
+  s.focus = f;
+}
+
+// ------------------------------------------------------------------ dispatch
+
+/** renderer-local slash commands run here; everything else (built-ins, custom, `!cmd`, free
+ *  text, unknown `/x`) reaches onSubmit unchanged — app.ts handleSlash owns the rest */
+export function dispatch(s: SextantState, text: string, ctx: KeyCtx): void {
+  const p = parseInput(text);
+  // `@file` in free text: the file goes with the message as a `read` result (mentions.ts) — this is the one
+  // consumer of parseInput's `mentions`, and what the footer's "@ mentions attach files" has meant since
+  if (p.kind === "text" && p.mentions.length > 0) {
+    const r = expandMentions(text, { cwd: s.cwd, mentions: p.mentions, resolve: (m) => resolveFile(m, s.files.paths) });
+    for (const n of r.notes) ctx.local.toast(n);
+    ctx.hooks.onSubmit(r.text);
+    return;
+  }
+  if (p.kind !== "slash" || !runLocal(s, p.cmd ?? "", p.arg ?? "", ctx)) ctx.hooks.onSubmit(text);
+}
+
+/** true when the line was answered here and must not reach onSubmit */
+export function runLocal(s: SextantState, cmd: string, arg: string, ctx: KeyCtx): boolean {
+  switch (cmd) {
+    case "help":
+      openHelp(s);
+      return false; // the card opens AND /help reaches the transcript
+    case "notices":
+      openNotices(s);
+      return true;
+    case "market":
+      // the overlay opens empty with a "loading" status; the renderer fills it when the catalog answers
+      ctx.local.openMarket();
+      return true;
+    case "context":
+      // counting is synchronous but not free on a long transcript, so the renderer does it off the frame
+      ctx.local.openContext();
+      return true;
+    case "theme":
+      if (isTheme(arg)) setTheme(s, ctx, arg);
+      else ctx.local.toast(`unknown theme "${arg}" · night, ember or contrast`);
+      return true;
+    case "open": {
+      const p = resolveFile(arg, s.files.paths, ctx.fuzzy);
+      if (!p) { ctx.local.toast(arg ? `no file matches "${arg}"` : "usage: /open <file>"); return true; }
+      openFile(s, ctx, p);
+      s.focus = "code";
+      return true;
+    }
+    case "diff": {
+      if (arg) {
+        const p = resolveFile(arg, s.files.paths, ctx.fuzzy);
+        if (!p) { ctx.local.toast(`no file matches "${arg}"`); return true; }
+        s.code.file = p;
+      }
+      setMode(s, ctx, "diff");
+      return true;
+    }
+    case "focus":
+      if (arg === "messages" || arg === "code" || arg === "files") setFocus(s, ctx, arg);
+      else ctx.local.toast("focus is messages, code or files");
+      return true;
+    case "agents":
+      showAgents(s, ctx);
+      return true;
+    default: {
+      const note = ALIAS_NOTE[cmd];
+      // a custom command of that name (listed by setCommands) wins over the note
+      if (note && !s.commands.some((c) => c.name === cmd)) { ctx.local.toast(note); return true; }
+      return false;
+    }
+  }
+}
+
+/** palette actions (overlays.ts paletteItems): a slash line, or theme: / mode: / focus: / open: */
+export function runAction(s: SextantState, action: string, ctx: KeyCtx): void {
+  if (action.startsWith("/")) {
+    const p = parseInput(action), needsArg = ["theme", "open", "focus"].includes(p.cmd ?? "");
+    if (needsArg && !p.arg) { // the argument is still missing: park the line in the prompt, options open
+      s.input.text = action + " ";
+      s.input.cur = s.input.text.length;
+      s.input.sgSel = 0;
+      s.focus = "messages";
+      return;
+    }
+    dispatch(s, action, ctx);
+    return;
+  }
+  const i = action.indexOf(":"), kind = action.slice(0, i), rest = action.slice(i + 1);
+  if (kind === "theme" && isTheme(rest)) setTheme(s, ctx, rest);
+  else if (kind === "mode") {
+    setMode(s, ctx, rest as CodeMode);
+    if (rest === "agents") s.code.laneOpen = false;
+  } else if (kind === "focus") setFocus(s, ctx, rest as Focus);
+  else if (kind === "open") { openFile(s, ctx, rest); s.focus = "code"; }
+}

package/src/sextant/market-source.ts

@@ -0,0 +1,287 @@
+/** The seam between the market overlay and the market module.
+ *
+ *  draw-market.ts is pure over (state, screen): it takes rows and a status and never fetches. This file is
+ *  the only place that knows src/market/ exists — it lazily imports the module (the boot rule: nothing in
+ *  the market's dependency tree is loaded until someone opens /market), maps src/market/types.ts onto the
+ *  overlay's flattened view rows, and turns every failure into a status the overlay can draw.
+ *
+ *  Nothing here throws for a data problem, because the module it wraps does not either: a source that fails
+ *  comes back as `SourceStatus {ok:false, reason}` and is shown as the error state, a source answered from
+ *  the cache is shown as the offline state with its age, and an install that fails is a `{ok:false, error}`
+ *  outcome printed on the plan card. The one thing this file DOES guard is the module not being there yet:
+ *  while src/market/ is being written (types.ts landed first), an absent registry.ts must read as "the
+ *  market module is not wired yet", not as a crash in the middle of a frame. */
+
+import type { MarketDocLine, MarketPlan, MarketStatus, MarketViewRow } from "./draw-market.ts";
+import { npxPackage } from "../mcp/local-package.ts";
+import type { MarketInstall } from "../mcp/market.ts";
+
+/** what the overlay needs to open: the rows, why they are what they are, and anything worth saying once */
+export interface MarketLoad {
+  rows: MarketViewRow[];
+  status: MarketStatus;
+  notes: string[];
+}
+
+/** src/market/types.ts, structurally — declared here so this file compiles before the module lands and so
+ *  the overlay never imports the market's types directly */
+interface Env { name: string; description?: string; required: boolean; secret: boolean; default?: string }
+interface Item {
+  id: string; kind: "mcp" | "skill" | "plugin"; title: string; publisher: string; description: string;
+  version?: string; repository?: string; homepage?: string; tags: string[]; status?: string;
+  env: Env[]; install: unknown; planNote?: string[];
+  /** the item's own documentation, as the catalog carries it (nimbus-24's writer): third-party markdown */
+  docs?: { source: string; format: string; bytes: number; truncated: boolean; body: string };
+}
+interface Row extends Item {
+  installed?: { path: string; scope: "user" | "project"; version?: string; updateAvailable?: boolean; trusted?: boolean };
+}
+type Status =
+  | { ok: true; from: "live" }
+  | { ok: true; from: "cache"; ageMs: number }
+  | { ok: true; from: "curated" }
+  /** the source was not consulted at all (an empty query never asks the registry, --offline skips it) */
+  | { ok: true; from: "skipped"; why: string }
+  | { ok: false; reason: string };
+interface Result { items: Item[]; sources: Record<string, Status>; notes: string[] }
+interface PlanView {
+  item: Item; target: string; scope: "user" | "project"; preview: string[];
+  asks: Env[]; pending: string[]; replaces?: string;
+}
+type Outcome =
+  | { ok: true; item: Item; target: string; scope: "user" | "project"; envNames: string[]; trusted?: boolean; next?: string;
+      /** install-once: what npm put on disk (src/market/types.ts InstallOutcome.package) */
+      package?: { name: string; version: string; prefix: string; integrity?: string; missing?: string[] } }
+  | { ok: false; error: string };
+/** the plan/install options the overlay passes through; `local` is the chooser's answer (mcp/local-package.ts) */
+interface Ctx { scope: "user" | "project"; cwd: string; home: string; local?: boolean }
+
+/** the module's public surface, as much of it as the overlay uses (src/market/registry.ts + install.ts;
+ *  there is no barrel file, so the two are imported separately) */
+interface RegistryModule {
+  searchMarket(query: string, deps?: { offline?: boolean; withDocs?: boolean }): Promise<Result>;
+  /** one item WITH its documentation body: search and list deliberately leave the bodies out (they are
+   *  hundreds of kilobytes the list never reads), so the docs pane asks for the row it is about to show */
+  findItem(kind: "mcp" | "skill" | "plugin", id: string, deps?: { offline?: boolean }): Promise<{ item?: Item; notes: string[] }>;
+}
+interface InstallModule {
+  planInstall(item: Item, opts: Ctx): PlanView | { error: string };
+  runInstall(plan: PlanView, answers: Record<string, string>, opts: Ctx, deps?: unknown): Promise<Outcome>;
+  withInstalled(items: readonly Item[], cwd: string, home: string): Row[];
+}
+
+/** "the market module is not wired yet" rather than an exception mid-frame */
+const NOT_WIRED = "the market module is not available in this build (src/market/ is still landing)";
+
+async function load(): Promise<{ registry: RegistryModule; install: InstallModule } | null> {
+  try {
+    // two lazy imports, resolved at call time so a missing file is a null, not a boot failure
+    const [registry, install] = await Promise.all([
+      import("../market/registry.ts") as Promise<Partial<RegistryModule>>,
+      import("../market/install.ts") as Promise<Partial<InstallModule>>,
+    ]);
+    if (typeof registry.searchMarket !== "function" || typeof install.planInstall !== "function") return null;
+    return { registry: registry as RegistryModule, install: install as InstallModule };
+  } catch {
+    return null;
+  }
+}
+
+/** what an item runs once installed, in one line — the install spec's own words, per arm */
+function runsLine(item: Item): string {
+  const spec = item.install as { kind?: string; entry?: { installs?: { kind?: string; url?: string; command?: string; args?: string[]; runtime?: string }[] }; source?: unknown; git?: boolean; files?: { path: string }[] } | undefined;
+  if (!spec) return "";
+  if (spec.kind === "mcp") {
+    const first = spec.entry?.installs?.[0];
+    if (!first) return "";
+    return first.kind === "http" ? `remote ${first.url ?? ""}` : [first.command, ...(first.args ?? [])].join(" ");
+  }
+  if (spec.kind === "plugin") return `${spec.git ? "clone" : "copy"} ${String(spec.source ?? "")}`;
+  if (spec.kind === "skill") {
+    if (spec.files?.length) return `${spec.files.length} file(s), written verbatim — runs nothing`;
+    const src = spec.source as { git?: string; subfolder?: string } | undefined;
+    return src?.git ? `clone ${src.git}${src.subfolder ? ` (${src.subfolder})` : ""}` : "a SKILL.md the model reads when it matches";
+  }
+  return "";
+}
+
+/** the other ways in an MCP entry offers (a remote endpoint beside a local runtime) */
+function alternatives(item: Item): string[] {
+  const spec = item.install as { kind?: string; entry?: { installs?: { kind?: string; url?: string; command?: string; args?: string[]; runtime?: string }[] } } | undefined;
+  if (spec?.kind !== "mcp") return [];
+  return (spec.entry?.installs ?? []).slice(1).map((i) => (i.kind === "http" ? `remote ${i.url ?? ""}` : `${i.runtime ?? "stdio"}: ${[i.command, ...(i.args ?? [])].join(" ")}`));
+}
+
+/** the npm package an mcp row's first form would run through npx — the install-once offer's subject */
+function localOfferOf(item: Item): string | undefined {
+  const spec = item.install as { kind?: string; entry?: { installs?: unknown[] } } | undefined;
+  if (spec?.kind !== "mcp") return undefined;
+  const first = spec.entry?.installs?.[0];
+  if (first === undefined || typeof first !== "object" || first === null) return undefined;
+  return npxPackage(first as MarketInstall)?.spec;
+}
+
+export function toViewRow(row: Row): MarketViewRow {
+  const localOffer = localOfferOf(row);
+  return {
+    ...(localOffer !== undefined ? { localOffer } : {}),
+    id: row.id,
+    kind: row.kind,
+    title: row.title,
+    publisher: row.publisher,
+    description: row.description,
+    ...(row.version !== undefined ? { version: row.version } : {}),
+    runs: runsLine(row),
+    env: row.env.map((v) => ({ name: v.name, required: v.required, secret: v.secret, ...(v.description !== undefined ? { description: v.description } : {}) })),
+    alternatives: alternatives(row),
+    pending: row.planNote ?? [],
+    ...(row.installed ? { installed: row.installed } : {}),
+    // search carries the metadata, not the body: the pane fills `lines` from docsFor() when it opens
+    ...(row.docs ? { docs: { source: row.docs.source, truncated: row.docs.truncated === true, lines: typeof row.docs.body === "string" && row.docs.body !== "" ? docLines(row.docs.body) : [] } } : {}),
+  };
+}
+
+/** ESC and the rest of C0 (tab and newline excepted), DEL, and the C1 range some terminals still read
+ *  as CSI — a document must not be able to move the cursor, change a colour or clear the screen */
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g;
+
+/** A document, flattened to lines a cockpit can draw and stripped of everything a terminal would obey.
+ *  The body is third-party text, so escape sequences and control characters go before anything else; then
+ *  markdown is flattened rather than rendered — headings and fenced code keep their shape, and the rest is
+ *  prose wrapped to a column. A README must not be able to move the cursor or repaint the screen. */
+export function docLines(body: string, width = 96): MarketDocLine[] {
+  const safe = body
+    .replace(/\r\n?/g, "\n")
+    .replace(/<(script|style|iframe|object|embed|template|noscript)\b[\s\S]*?<\/\1\s*>/gi, "")
+    .replace(/<\/?[a-zA-Z][^>]*>/g, "")
+    .replace(CONTROL, "")
+    .replace(/\t/g, "  ")
+    .replace(/^---\n[\s\S]*?\n---\n/, "");
+  const out: MarketDocLine[] = [];
+  let fence = false;
+  for (const raw of safe.split("\n")) {
+    if (/^\s*```/.test(raw)) { fence = !fence; out.push({ kind: "rule", text: "" }); continue; }
+    if (fence) { out.push({ kind: "code", text: raw.slice(0, width) }); continue; }
+    const h = /^(#{1,6})\s+(.*)$/.exec(raw);
+    if (h) { out.push({ kind: "head", text: h[2]!.replace(/[`*]/g, "").slice(0, width) }); continue; }
+    const text = raw.replace(/\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/[`*]/g, "");
+    if (text.trim() === "") { out.push({ kind: "blank", text: "" }); continue; }
+    let line = "";
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+      const piece = word.length > width ? word.slice(0, width) : word;
+      if (!line) { line = piece; continue; }
+      if (line.length + 1 + piece.length <= width) line += ` ${piece}`;
+      else { out.push({ kind: "text", text: line }); line = piece; }
+    }
+    if (line) out.push({ kind: "text", text: line });
+  }
+  return out;
+}
+
+/** the three drawn states, decided from the sources the module consulted — never from an empty list */
+export function statusFrom(sources: Record<string, Status>): MarketStatus {
+  const failed = Object.entries(sources).filter(([, v]) => !v.ok) as [string, { ok: false; reason: string }][];
+  if (failed.length) {
+    const [name, s] = failed[0]!;
+    return { kind: "error", reason: failed.length === 1 ? `${name}: ${s.reason}` : `${name}: ${s.reason} (+${failed.length - 1} more)` };
+  }
+  const cached = Object.values(sources).find((v) => v.ok && v.from === "cache") as { ok: true; from: "cache"; ageMs: number } | undefined;
+  if (cached) {
+    const mins = Math.round(cached.ageMs / 60000);
+    return { kind: "offline", note: `showing cached results${mins > 0 ? `, ${mins}m old` : ""}` };
+  }
+  // "skipped" is not a failure and not staleness: the source was left out on purpose, and `why` says so.
+  // It is worth one line because a reader who does not see a registry row deserves to know it was not asked.
+  const skipped = Object.values(sources).find((v) => v.ok && v.from === "skipped") as { ok: true; from: "skipped"; why: string } | undefined;
+  if (skipped) return { kind: "offline", note: skipped.why };
+  return { kind: "ready" };
+}
+
+/** Everything the overlay opens with. `offline` forces the no-network path (the curated shelf and the
+ *  repository catalogs), which is also what a failed network falls back to. */
+export async function loadMarket(cwd: string, home: string, opts: { offline?: boolean } = {}): Promise<MarketLoad> {
+  const mod = await load();
+  if (!mod) return { rows: [], status: { kind: "error", reason: NOT_WIRED }, notes: [] };
+  const result = await mod.registry.searchMarket("", opts.offline === true ? { offline: true } : {});
+  // installed state is disk truth, joined onto the catalog by withInstalled (never read from a catalog)
+  let rows: Row[] = result.items as Row[];
+  try { rows = mod.install.withInstalled(result.items, cwd, home); } catch { /* disk unreadable: the rows still list */ }
+  return { rows: rows.map(toViewRow), status: statusFrom(result.sources), notes: result.notes };
+}
+
+/** The documentation for one row, fetched when the reader asks for it.
+ *
+ *  `searchMarket` carries docs METADATA but not the bodies — they are ~400 KB nobody reads while browsing —
+ *  so the list cannot fill this in advance. `findItem` reads the one row with its body, and the body is
+ *  flattened to terminal-safe lines here, once, at the moment the pane opens. */
+export async function docsFor(row: MarketViewRow): Promise<{ source: string; truncated: boolean; lines: MarketDocLine[] } | null> {
+  const mod = await load();
+  if (!mod || typeof mod.registry.findItem !== "function") return null;
+  const { item } = await mod.registry.findItem(row.kind, row.id, { offline: true });
+  const docs = item?.docs;
+  if (!docs || typeof docs.body !== "string" || docs.body.trim() === "") return null;
+  return { source: docs.source, truncated: docs.truncated === true, lines: docLines(docs.body) };
+}
+
+/** the plan for one row, or the reason there is none. Writes nothing. `local` is the chooser's answer for an npx
+ *  row: true draws the install-once plan (`node <bin>`, the `installs`/`records` rows), false or absent the npx
+ *  line as today — and the plan remembers it, so the install runs the plan that was approved. */
+export async function planFor(row: MarketViewRow, ctx: Ctx, local?: boolean): Promise<MarketPlan | { error: string }> {
+  const mod = await load();
+  if (!mod) return { error: NOT_WIRED };
+  const result = await mod.registry.searchMarket(row.id, { offline: true });
+  const item = result.items.find((i) => i.kind === row.kind && i.id === row.id);
+  if (!item) return { error: `${row.kind}:${row.id} is not in the catalog any more` };
+  const plan = mod.install.planInstall(item, { ...ctx, ...(local === true ? { local: true } : {}) });
+  if ("error" in plan) return { error: plan.error };
+  return {
+    row,
+    title: `${plan.item.kind}:${plan.item.id} — ${plan.item.title}`,
+    target: plan.target,
+    scope: plan.scope,
+    preview: plan.preview,
+    asks: plan.asks.map((a) => ({ name: a.name, required: a.required, secret: a.secret })),
+    pending: plan.pending,
+    ...(plan.replaces !== undefined ? { replaces: plan.replaces } : {}),
+    ...(local === true ? { local: true } : {}),
+  };
+}
+
+/** Run a plan the human has just confirmed. The overlay only ever sees the outcome sentence. `opts.local` must be
+ *  the approved plan's own `local` — npm runs here, and only here, after the card said yes. `opts.deps` is the
+ *  installer's seam (a fake `npm` in tests). */
+export async function install(row: MarketViewRow, ctx: Ctx, opts: { local?: boolean; deps?: unknown } = {}): Promise<{ ok: boolean; text: string }> {
+  const mod = await load();
+  if (!mod) return { ok: false, text: NOT_WIRED };
+  const result = await mod.registry.searchMarket(row.id, { offline: true });
+  const item = result.items.find((i) => i.kind === row.kind && i.id === row.id);
+  if (!item) return { ok: false, text: `${row.kind}:${row.id} is not in the catalog any more` };
+  const withLocal: Ctx = { ...ctx, ...(opts.local === true ? { local: true } : {}) };
+  const plan = mod.install.planInstall(item, withLocal);
+  if ("error" in plan) return { ok: false, text: plan.error };
+  // A SECRET cannot be finished inside the overlay: it has to be typed on a shell, masked, not into a
+  // query line that echoes. The overlay says so and hands the exact command over.
+  //
+  // `pending` is not that, and treating it as if it were made six of the sixteen curated MCP servers
+  // uninstallable from the cockpit — including `filesystem`, which is the first one anybody tries.
+  // Nothing is asked for a pending value: it is a placeholder the installer writes into the config
+  // (`<directory the server may touch>`) for the human to replace afterwards, and the CLI installs it
+  // exactly that way. Refusing here was the overlay inventing a requirement the installer does not have.
+  if (plan.asks.length > 0) {
+    const what = plan.asks.map((a) => a.name).join(", ");
+    return { ok: false, text: `${what} must be typed where it can be masked — run: rovecode market install ${item.kind}:${item.id}` };
+  }
+  const outcome = await mod.install.runInstall(plan, {}, withLocal, opts.deps);
+  if (!outcome.ok) return { ok: false, text: outcome.error };
+  const bits = [`installed into ${outcome.target}`];
+  if (outcome.package) {
+    bits.push(`${outcome.package.name} ${outcome.package.version} installed once → ${outcome.package.prefix}${outcome.package.integrity !== undefined ? " (integrity recorded)" : ""}`);
+    if (outcome.package.missing?.length) bits.push(`record incomplete: ${outcome.package.missing.join("; ")}`);
+  }
+  if (outcome.envNames.length) bits.push(`export ${outcome.envNames.join(", ")}`);
+  // the placeholder is the one thing between this install and a working server, so it leads
+  for (const p of plan.pending) bits.push(`fill in ${p}`);
+  if (outcome.next) bits.push(outcome.next);
+  return { ok: true, text: bits.join(" · ") };
+}

package/src/sextant/mentions.ts

@@ -0,0 +1,141 @@
+/** `@file` mentions, made true. overlays.ts has parsed `@path` into `mentions[]` (with a fuzzy resolveFile) since
+ *  the port, and the input footer promised "@ mentions attach files" — but nothing ever read `.mentions`, so the
+ *  promise did nothing. This module is the consumer: on submit, each mention that resolves to a workspace file is
+ *  appended to the message exactly as the `read` tool would return it (hashline `path#TAG` header, `N#hash|text`
+ *  lines), so the model has the contents — and valid edit anchors — without spending a tool round-trip.
+ *
+ *  Why here and not in tui/commands.ts: that file's note ("no `!shell` / `@file` injection … the template reaches
+ *  the model as plain text") is about CUSTOM COMMAND TEMPLATES — files a repo or a plugin ships, where injecting
+ *  files or shell output from a template is a way for a project to read the user's disk. That reason stands and
+ *  is untouched. A `@file` the human types into their own prompt is the human choosing to show a file; the only
+ *  risk is cost, so the caps below exist and every cap is SAID, in the message and as a toast.
+ *
+ *  What is refused, and said: a mention no workspace file matches; a directory; a file outside the workspace
+ *  (resolveFile only knows the scanned list, and the absolute path is checked against cwd again); a binary; a
+ *  file past MAX_BYTES. What is capped, and said: lines per file (MAX_LINES — the footer names the offset that
+ *  continues), files per message (MAX_FILES), characters per message (MAX_CHARS). Never silent: `@` must not be a
+ *  way to spend a context window without knowing. */
+
+import { readFileSync, statSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { fileTag, lineHash, readAnchored, renderAnchored, type AnchoredFile } from "../coding/hashline.ts";
+
+/** `@path` tokens in free text: at the start or after whitespace, so `me@example.com` is not one. The one
+ *  regex both surfaces and overlays.ts parseInput read — this module imports nothing from the sextant, so the
+ *  classic renderer can use it without loading the cockpit's module graph. */
+export const MENTION_RE = /(?:^|\s)@([\w./-]+)/g;
+/** the mentions of a typed line — none for a `/command` or a `!shell` line, which are never expanded */
+export function mentionsIn(text: string): string[] {
+  const t = text.trim();
+  if (t[0] === "/" || t[0] === "!") return [];
+  return [...t.matchAll(MENTION_RE)].map((m) => m[1]!);
+}
+
+/** the most lines one mention contributes — the rest is one `read` with an offset away */
+export const MENTION_MAX_LINES = 400;
+/** mentions expanded per message; the rest are named and left for the model to read */
+export const MENTION_MAX_FILES = 8;
+/** characters all expansions together may add to one message (~15k tokens) */
+export const MENTION_MAX_CHARS = 60_000;
+/** a file larger than this is not read at all — name it, let the model ask for a window */
+export const MENTION_MAX_BYTES = 2 * 1024 * 1024;
+/** with less than this left of the character budget, a further file is named rather than squeezed to a
+ *  line or two — a three-line fragment of a file is worse context than "read it yourself" */
+export const MENTION_MIN_BLOCK = 500;
+
+/** the line that opens the attached section — what userRow cuts the transcript at */
+export const MENTION_FRAME = "(files attached by @mention — each block is what `read` returns for the file; its edit anchors are valid)";
+/** one per attached file, right above its read block: `[@src/x.ts — attached: 120 lines]` */
+export const MENTION_HEAD = /^\[@(\S+) — attached: (\d+)(?: of (\d+))? lines(, capped[^\]]*)?\]$/;
+
+export interface AttachedFile { path: string; shown: number; total: number; capped: boolean }
+export interface MentionExpansion {
+  /** the message as submitted: the typed text, then the attached section (unchanged when nothing attached) */
+  text: string;
+  attached: AttachedFile[];
+  /** what was refused or capped, one sentence each — the renderer toasts them */
+  notes: string[];
+}
+
+export interface ExpandOptions {
+  cwd: string;
+  /** a mention → the cwd-relative posix path it names, or null. The sextant ranks over its scanned file list
+   *  (overlays.ts resolveFile: exact, unique basename, fuzzy); the classic renderer, which has no list, takes
+   *  the exact path only — what its own `@` autocomplete inserts. */
+  resolve: (mention: string) => string | null;
+  /** already parsed mentions (default: mentionsIn(text)) */
+  mentions?: readonly string[];
+  /** seams for tests */
+  stat?: (abs: string) => { isFile(): boolean; size: number };
+  read?: (abs: string) => string;
+}
+
+const BINARY_PROBE = 8 * 1024;
+
+/** Expand every `@mention` in a typed line. Pure apart from the reads; never throws — a file that cannot be
+ *  read becomes a note and the message goes out without it. */
+export function expandMentions(text: string, opts: ExpandOptions): MentionExpansion {
+  const mentions = [...new Set(opts.mentions ?? mentionsIn(text))];
+  const notes: string[] = [];
+  const attached: AttachedFile[] = [];
+  const blocks: string[] = [];
+  if (mentions.length === 0) return { text, attached, notes };
+  const root = resolve(opts.cwd);
+  const stat = opts.stat ?? ((p: string) => statSync(p));
+  let budget = MENTION_MAX_CHARS;
+  for (const m of mentions) {
+    if (attached.length >= MENTION_MAX_FILES) { notes.push(`@${m}: not attached — ${MENTION_MAX_FILES} files per message is the cap; ask me to read it`); continue; }
+    const rel = opts.resolve(m);
+    if (rel === null) { notes.push(`@${m}: no file in the workspace matches`); continue; }
+    const abs = resolve(root, rel);
+    if (abs !== root && !abs.startsWith(root + sep)) { notes.push(`@${rel}: outside the workspace — not attached`); continue; }
+    let st: { isFile(): boolean; size: number };
+    try { st = stat(abs); } catch { notes.push(`@${rel}: cannot be read — not attached`); continue; }
+    if (!st.isFile()) { notes.push(`@${rel}: a directory — name a file in it`); continue; }
+    if (st.size > MENTION_MAX_BYTES) { notes.push(`@${rel}: ${(st.size / 1048576).toFixed(1)} MB is too large to attach — ask me to read a window of it`); continue; }
+    let content: string;
+    try { content = opts.read ? opts.read(abs) : readFileSync(abs, "utf8"); }
+    catch { notes.push(`@${rel}: cannot be read — not attached`); continue; }
+    if (content.slice(0, BINARY_PROBE).includes("\0")) { notes.push(`@${rel}: a binary file — not attached`); continue; }
+    if (budget < MENTION_MIN_BLOCK) { notes.push(`@${rel}: not attached — this message already carries ${MENTION_MAX_CHARS.toLocaleString()} characters of files; ask me to read it`); continue; }
+    const file = opts.read ? anchoredFrom(abs, content) : readAnchored(abs);
+    const total = file.lines.length;
+    // the line cap first, then the character budget: whichever is hit, the footer says where to continue
+    let shown = Math.min(total, MENTION_MAX_LINES);
+    let body = renderAnchored({ ...file, lines: file.lines.slice(0, shown) }).replace(/\n$/, "");
+    while (body.length > budget && shown > 1) {
+      shown = Math.max(1, Math.floor(shown * budget / body.length));
+      body = renderAnchored({ ...file, lines: file.lines.slice(0, shown) }).replace(/\n$/, "");
+    }
+    const capped = shown < total;
+    budget -= body.length;
+    const head = capped
+      ? `[@${rel} — attached: ${shown} of ${total} lines, capped: read it with offset ${shown + 1} for the rest]`
+      : `[@${rel} — attached: ${total} lines]`;
+    blocks.push(`${head}\n${body}\n(showing lines ${total === 0 ? 0 : 1}-${shown} of ${total})`);
+    attached.push({ path: rel, shown, total, capped });
+    if (capped) notes.push(`@${rel}: ${total} lines — attached the first ${shown}; the rest is a read away`);
+  }
+  if (blocks.length === 0) return { text, attached, notes };
+  return { text: `${text.trimEnd()}\n\n${MENTION_FRAME}\n\n${blocks.join("\n\n")}`, attached, notes };
+}
+
+/** an AnchoredFile from content already in hand (the `read` seam), split and hashed exactly as readAnchored does —
+ *  including the empty last line a trailing newline yields, so the counts match what the read tool reports */
+function anchoredFrom(abs: string, content: string): AnchoredFile {
+  return { path: abs, tag: fileTag(content), lines: content.split("\n").map((t, i) => ({ n: i + 1, hash: lineHash(t), text: t })) };
+}
+
+/** The transcript's view of a submitted line: the typed text, and one chip per attached file — never the file
+ *  bodies, which would flood the messages panel (they are in the session, where the model reads them). */
+export function splitAttached(text: string): { text: string; files: string[] } {
+  const lines = text.split("\n");
+  const at = lines.indexOf(MENTION_FRAME);
+  if (at < 0) return { text, files: [] };
+  const files: string[] = [];
+  for (const l of lines.slice(at + 1)) {
+    const m = MENTION_HEAD.exec(l);
+    if (m) files.push(m[3] !== undefined ? `${m[1]} · ${m[2]}/${m[3]} lines, capped` : `${m[1]} · ${m[2]} lines`);
+  }
+  return { text: lines.slice(0, at).join("\n").trimEnd(), files };
+}

package/src/sextant/message-hits.ts

@@ -0,0 +1,26 @@
+/** Click zones on the transcript: a tool row that names a file (`~ edit src/a.ts`, `◆ read …`) opens
+ *  that file in the code panel — what `/open <path>` does. The rows come from the same cached build the
+ *  painter used (draw-messages.ts cachedBuildRows), at the same scroll offset, so a zone is exactly the
+ *  painted row. Rows under a card, or off the visible window, get no zone. */
+import { areas, cachedBuildRows, messagesScroll } from "./draw-messages.ts";
+import { inner } from "./draw-util.ts";
+import type { Rect, SextantState, Theme } from "./types.ts";
+
+export interface MessageHit { rect: Rect; path: string }
+
+export function messageRowHits(rect: Rect, s: SextantState, theme: Theme, now: number): MessageHit[] {
+  const B = inner(rect);
+  if (B.w < 3 || B.h < 1) return [];
+  const { msgH } = areas(B, s);
+  if (msgH <= 0) return [];
+  const rows = cachedBuildRows(s, B.w, theme, now);
+  const { offset } = messagesScroll(rect, s, theme, now);
+  const out: MessageHit[] = [];
+  for (let i = 0; i < msgH; i++) {
+    const r = rows[offset + i];
+    if (!r?.path) continue;
+    const x = B.x + (r.indent ?? 0);
+    out.push({ rect: { x, y: B.y + i, w: Math.max(1, B.w - (r.indent ?? 0) - 1), h: 1 }, path: r.path }); // -1: the scrollbar column
+  }
+  return out;
+}