rovecode 0.3.3 → 0.4.0-beta.3

package/src/sextant/local-commands.ts

@@ -1,169 +0,0 @@
-/** 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.
- *  `undo` is GONE from here since port #65: /undo is a real built-in that reaches onSubmit
- *  (tui/git-cmds.ts restores the previous checkpoint), no longer an alias note. */
-export const ALIAS_NOTE: Record<string, string> = {
-  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 {
-  // the connect wizard IS this surface's /connect — THE connect command (Berkay, 2026-09-10: setup
-  // is gone from the table; /setup still opens the wizard as a soft alias for muscle memory). With
-  // an argument, /connect keeps its one-line contract: the answers are on the line
-  if (text === "/setup" || text === "/connect") { ctx.local.openWizard(); return; }
-  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) {
-    // port #54: an IMAGE mention takes the /attach seam (local.attachImage → the store's stage) instead of
-    // dying as "a binary file" — it reaches the model as an image part and spends none of the text budget
-    const r = expandMentions(text, { cwd: s.cwd, mentions: p.mentions, resolve: (m) => resolveFile(m, s.files.paths), attachImage: ctx.local.attachImage?.bind(ctx.local) });
-    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();
-    case "wizard":
-      // /connect and /setup on the sextant surface: the columned connect wizard (draw-wizard.ts),
-      // reached here so the classic surface keeps its own pickOne chain untouched
-      ctx.local.openWizard();
-      return true;
-      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":
-      if (arg) return false; // port #62: `/agents list` (any argument) reaches app.ts handleSlash — the definitions list; the BARE /agents is this board
-      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

@@ -1,287 +0,0 @@
-/** 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

@@ -1,200 +0,0 @@
-/** `@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.
- *
- *  Three widenings (2026-09-07), each because the promise was narrower than the words: `@~/notes.md` and an
- *  ABSOLUTE mention name a file outright and are attached wherever they point (the person typed the whole path —
- *  that IS the choice; a RELATIVE mention still has to land in the workspace); a relative mention that resolves
- *  nowhere under cwd is tried against the `--add-dir` roots, without which a file in an added root could not be
- *  mentioned at all; and an IMAGE mention takes the /attach seam so it reaches the model as an image part instead
- *  of being refused as "a binary file". The token class carries `~`, `:` and `\` for the first of those, which is
- *  what lets `@C:\Users\me\notes.md` tokenize on Windows — the cost is that a prose `@foo:bar` is read as a path
- *  and reported as not found, which is a note, not a loss. */
-
-import { existsSync, openSync, closeSync, readSync, readFileSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { isAbsolute, resolve, sep } from "node:path";
-import { sniffImageMime } from "../core/images.ts";
-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[];
-  /** `--add-dir` roots (core/workspace.ts): a RELATIVE mention that resolves nowhere under cwd is tried against
-   *  each of these in order, so a file in an added root can be mentioned at all. cwd always wins a tie. */
-  roots?: readonly string[];
-  /** an image mention takes the /attach seam instead of being refused as binary — it reaches the model as an
-   *  image part, and costs nothing against the text budget. Without this the old "binary file" refusal stands. */
-  attachImage?: (abs: string) => void;
-  /** seams for tests */
-  stat?: (abs: string) => { isFile(): boolean; size: number };
-  read?: (abs: string) => string;
-  exists?: (abs: string) => boolean;
-}
-
-/** Where a mention points, and by what right. `~`/`~/x` and an ABSOLUTE mention are the person naming a file
- *  outright — that is the choice, so they are allowed wherever they point; a RELATIVE mention must land inside the
- *  cwd or one of the `--add-dir` roots, which is the containment rule the workspace already enforces everywhere
- *  else. `label` is what the notes and the attached header show. */
-export function locateMention(m: string, opts: ExpandOptions): { abs: string; label: string; root?: string } | null {
-  const exists = opts.exists ?? existsSync;
-  if (m === "~" || m.startsWith("~/") || m.startsWith("~\\")) { const abs = resolve(homedir(), m.slice(2)); return { abs, label: m }; }
-  if (isAbsolute(m)) return { abs: resolve(m), label: m };
-  const rel = opts.resolve(m);
-  if (rel !== null) return { abs: resolve(opts.cwd, rel), label: rel };
-  for (const root of opts.roots ?? []) {
-    const abs = resolve(root, m);
-    if ((abs === resolve(root) || abs.startsWith(resolve(root) + sep)) && exists(abs)) return { abs, label: m, root };
-  }
-  return null;
-}
-
-const BINARY_PROBE = 8 * 1024;
-
-/** the file's image MIME by magic bytes (core/images.ts), reading only the first bytes — an image mention must not
- *  pull a 4 MB photo into memory just to learn it is a photo. null when it is not an image we accept. */
-function sniffImage(abs: string, opts: ExpandOptions): string | null {
-  try {
-    if (opts.read) { const head = Buffer.from(opts.read(abs).slice(0, 32), "binary"); return sniffImageMime(head) ?? null; }
-    const fd = openSync(abs, "r");
-    try { const buf = Buffer.alloc(32); const n = readSync(fd, buf, 0, 32, 0); return sniffImageMime(buf.subarray(0, n)) ?? null; }
-    finally { closeSync(fd); }
-  } catch { return null; }
-}
-
-/** 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 found = locateMention(m, opts);
-    if (found === null) { notes.push(`@${m}: no file in the workspace matches`); continue; }
-    const { abs } = found;
-    const rel = found.label;
-    // a relative mention resolved through the workspace list stays inside it; `~`/absolute and the added roots
-    // carry their own right (locateMention), so only the cwd-relative case is re-checked here
-    if (found.root === undefined && !isAbsolute(m) && !m.startsWith("~") && 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; }
-    // an IMAGE takes the /attach seam BEFORE the size and budget checks: it reaches the model as an image part
-    // and spends none of the text budget, so refusing it as "binary" was the wrong answer to the right question
-    if (opts.attachImage) {
-      const mime = sniffImage(abs, opts);
-      if (mime !== null) {
-        opts.attachImage(abs);
-        notes.push(`@${rel}: attached as an image (${mime})${found.root ? ` (from ${found.root})` : ""}`);
-        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 };
-}