@spexcode/spec-cli 0.6.5

package/dist/sh.d.ts

@@ -0,0 +1 @@
+export declare function shQuote(s: string): string;

package/dist/sh.js

@@ -0,0 +1,3 @@
+export function shQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}

package/dist/shim-runtime.d.ts

@@ -0,0 +1 @@
+export declare function shimRuntimeSource(harnessId: string, dispatch: string, spex: string): string;

package/dist/shim-runtime.js

@@ -0,0 +1,161 @@
+// @@@ shim-runtime - the ONE shared runtime every GENERATIVE per-session shim embeds ([[shim-runtime]]).
+// pi's extension and opencode's plugin (and any future in-process harness shim) are thin hosts: they declare
+// an event-name mapping and bind their host's API; the machinery they share — claude-shaped payload synthesis
+// into dispatch.sh, the block-verdict parse, the rendezvous socket server, tool-input normalization — is THIS
+// module's generated chunk, embedded verbatim by each generator. One source of truth: the deliver-confirm and
+// stop-gate-rejection bugs were each fixed in only one of the two hand-written copies this replaces; a fix
+// here reaches every generative shim at the next materialize.
+//
+// The chunk is PLAIN JavaScript (no type annotations, no non-builtin imports): pi loads its shim as a native
+// .ts extension, opencode as a project plugin, and tests import the generated file directly under node — the
+// lowest common denominator is untyped ESM against node builtins. Identifiers are __spex-prefixed so a host
+// section can never collide with them.
+// the embedded runtime chunk. `harnessId` is baked as dispatch.sh's argv[1] (the deterministic shell-side
+// harness detector); `dispatch`/`spex` are the absolute paths materialize bakes into every shim — the
+// 'dispatch.sh' substring doubles as the identity stamp cleanHarness gates removal on.
+export function shimRuntimeSource(harnessId, dispatch, spex) {
+    return `// ---- spexcode shared shim runtime (embedded from spec-cli/src/shim-runtime.ts — edit THERE) ----
+import { spawn as __spexSpawn } from "node:child_process"
+import { createServer as __spexCreateServer } from "node:net"
+import { unlinkSync as __spexUnlink } from "node:fs"
+
+const DISPATCH = ${JSON.stringify(dispatch)}
+const SPEX = ${JSON.stringify(spex)}
+const HARNESS = ${JSON.stringify(harnessId)}
+
+// cfg: { sessionId: () => string, cwd?: () => string } — the two identity accessors a host binds; everything
+// else is shared machinery.
+const spexShimRuntime = (cfg) => {
+  const cwd = cfg.cwd || (() => process.cwd())
+
+  // feed ONE claude-shaped payload ({ session_id, cwd, hook_event_name, ...extra }) to dispatch.sh, the
+  // harness id baked as argv[1]. Payload key order matters for tool events: a host must put agent_id (when
+  // present) BEFORE tool_input because harness.sh's hp_is_subagent checks keys only before tool_input. Resolves with the exit
+  // code + both streams for the verdict helpers below; never rejects.
+  const dispatchEvent = (event, extra) => new Promise((resolve) => {
+    let out = "", err = ""
+    let child
+    try {
+      child = __spexSpawn("bash", [DISPATCH, HARNESS, event], {
+        cwd: cwd(), env: { ...process.env, SPEX }, stdio: ["pipe", "pipe", "pipe"], timeout: 600_000,
+      })
+    } catch (e) { resolve({ code: 1, out, err: String(e) }); return }
+    child.stdout.on("data", (d) => { out += d })
+    child.stderr.on("data", (d) => { err += d })
+    child.on("error", (e) => resolve({ code: 1, out, err: err || String(e) }))
+    child.on("close", (code) => resolve({ code: code == null ? 1 : code, out, err }))
+    // a handler may exit without draining stdin (fast-fail scripts, a missing dispatch file) — the write then
+    // EPIPEs; that must never throw into the host's event handler, the child's exit code still answers.
+    child.stdin.on("error", () => { /* child exited before consuming stdin — fine */ })
+    try { child.stdin.end(JSON.stringify({ session_id: cfg.sessionId(), cwd: cwd(), hook_event_name: event, ...(extra || {}) })) } catch { /* same */ }
+  })
+
+  // the ONE block contract: dispatch.sh signals a block by EXIT 2 (a handler's stdout
+  // {"decision":"block","reason":…} JSON is mapped to exit 2 by dispatch itself, stderr staying empty; a
+  // bare exit-2 handler writes its reason on stderr instead). codex's stderr bridge is codex's own native
+  // protocol and lives in dispatch.sh — not here.
+  const blocked = (r) => r.code === 2
+
+  // the human-readable rejection, extracted in contract order — never the raw wire JSON (an escaped-\\n payload
+  // turned the stop-gate's teaching menu into one unreadable line on one harness before this was shared):
+  //   1. a decision:block JSON line on stdout, strictly parsed (the designed channel);
+  //   2. several handlers' stdout objects can arrive GLUED without separators — regex the reason string out
+  //      (JSON.parse of the string literal unescapes it);
+  //   3. stderr — the channel a bare exit-2 handler writes;
+  //   4. the caller's fallback.
+  const blockReason = (r, fallback) => {
+    for (const line of (r.out || "").split("\\n")) {
+      const s = line.trim()
+      if (!s.startsWith("{")) continue
+      try {
+        const o = JSON.parse(s)
+        if (o && o.decision === "block" && typeof o.reason === "string" && o.reason) return o.reason
+      } catch { /* not a lone JSON line — the glued fallback below */ }
+    }
+    if (/"decision"\\s*:\\s*"block"/.test(r.out || "")) {
+      const m = (r.out || "").match(/"reason"\\s*:\\s*"((?:[^"\\\\]|\\\\.)*)"/)
+      if (m) { try { return JSON.parse('"' + m[1] + '"') } catch { /* malformed escape — fall through */ } }
+    }
+    return (r.err || "").trim() || fallback
+  }
+
+  // the Stop dispatch with the gate's LOOP-TERMINATION bit. Claude's native Stop payload carries
+  // stop_hook_active=true when the stop happens inside a continuation a Stop-hook block itself forced, and
+  // the stop-gate's escape paths key on exactly that bit to guarantee the loop ends (auto-declare /
+  // downgrade-to-ask instead of a fresh block). A generative host has no native bit, so the runtime supplies
+  // it: false on a natural stop, true on the settle that follows a blocked one, reset by the first allowed
+  // stop. Without it every settle reads as a FIRST stop and a gate that can never pass (e.g. the commit gate
+  // on a 0-commit worktree) blocks forever. On block, the host's inject re-enters the gate's reason as the
+  // continuation; an inject that cannot land is caught LOUD on stderr — never thrown into the host, never
+  // silent. stopPending exposes whether the
+  // last Stop verdict was a block still awaiting its continuation's allow — the state a host's backstop
+  // binding (pi's agent_settled) keys on to consume exactly one pending blocked stop, never duplicating a
+  // naturally-allowed dispatch.
+  let stopBlocked = false
+  const stopPending = () => stopBlocked
+  const dispatchStop = async (inject, fallback) => {
+    const r = await dispatchEvent("Stop", { stop_hook_active: stopBlocked })
+    if (blocked(r)) {
+      stopBlocked = true
+      try { await inject(blockReason(r, fallback)) } catch (e) {
+        console.error("spexcode: a blocked stop's continuation could not be re-injected: " + String(e))
+      }
+    } else stopBlocked = false
+    return r
+  }
+
+  // normalize a host tool-input onto the claude accessor shape: mirror the host's file-path spelling onto
+  // file_path (the key harness.sh and every claude-family handler read), dropping the host spelling.
+  const toolInput = (input, fileAlias) => {
+    const args = { ...(input && typeof input === "object" ? input : {}) }
+    if (fileAlias && args[fileAlias] !== undefined && args.file_path === undefined) {
+      args.file_path = args[fileAlias]
+      delete args[fileAlias]
+    }
+    return args
+  }
+
+  // The per-session rendezvous control socket is a best-effort same-turn poke. The timeline remains the
+  // message's durable copy, so this listener only receives reply lines and never confirms or rejects them.
+  const serveRendezvous = (inject, opts) => {
+    const sock = (process.env.CLAUDE_BG_RENDEZVOUS_SOCK || "").trim()
+    if (!sock) return null
+    try { __spexUnlink(sock) } catch { /* no stale socket — fine */ }
+    const injected = new Set()
+    const server = __spexCreateServer((c) => {
+      let buf = ""
+      c.on("error", () => { /* probes disconnect abruptly — expected */ })
+      c.on("data", (d) => {
+        buf += d.toString("utf8")
+        let nl
+        while ((nl = buf.indexOf("\\n")) >= 0) {
+          const line = buf.slice(0, nl)
+          buf = buf.slice(nl + 1)
+          let msg
+          try { msg = JSON.parse(line) } catch { continue }
+          if (msg && msg.type === "reply" && typeof msg.text === "string") {
+            if (opts && opts.canInject && !opts.canInject()) continue
+            const mid = typeof msg.mid === "string" ? msg.mid : ""
+            if (mid && injected.has(mid)) continue
+            if (mid) injected.add(mid)
+            try {
+              const p = inject(msg.text)
+              if (p && typeof p.catch === "function") p.catch(() => { if (mid) injected.delete(mid) })
+            } catch { if (mid) injected.delete(mid) }
+          }
+        }
+      })
+    })
+    server.on("error", (e) => console.error("spexcode: rendezvous socket failed to bind at " + sock + ": " + String(e)))
+    server.listen(sock)
+    server.unref()   // never hold the host process open for our socket; the harness's own loop keeps it alive
+    return { close: () => {
+      try { server.close() } catch { /* already closed */ }
+      try { __spexUnlink(sock) } catch { /* already gone */ }
+    } }
+  }
+
+  return { dispatchEvent, dispatchStop, stopPending, blocked, blockReason, toolInput, serveRendezvous }
+}
+// ---- end spexcode shared shim runtime ----`;
+}

package/dist/slash-commands.d.ts

@@ -0,0 +1,9 @@
+export type SlashCommand = {
+    name: string;
+    description: string;
+    source: 'built-in' | 'user' | 'project' | 'skill';
+};
+export declare function claudeSlashCommands(): SlashCommand[];
+export declare function piSlashCommands(): SlashCommand[];
+export declare function codexSlashCommands(): SlashCommand[];
+export declare function opencodeSlashCommands(): SlashCommand[];

package/dist/slash-commands.js

@@ -0,0 +1,307 @@
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { homedir } from 'node:os';
+import { repoRoot } from '@spexcode/spec-core';
+// captured live from `claude --dangerously-skip-permissions` v2.1.x by typing `/` and paging the dropdown;
+// version-specific — re-capture this block to refresh for a new CC version (the disk-discovered sources don't).
+const BUILT_IN = [
+    ['add-dir', 'Add a new working directory'],
+    ['advisor', 'Let Claude consult a stronger model at key moments'],
+    ['agents', 'Manage agent configurations'],
+    ['autofix-pr', 'Monitor and autofix any issues with the current PR'],
+    ['background', 'Send this session to the background and free the terminal'],
+    ['branch', 'Create a branch of the current conversation at this point'],
+    ['btw', 'Ask a quick side question without interrupting the main conversation'],
+    ['chrome', 'Open Claude in Chrome (beta) settings'],
+    ['clear', 'Start a new session with empty context; previous session stays on disk (resumable with /resume)'],
+    ['color', 'Set the prompt bar color for this session'],
+    ['compact', 'Free up context by summarizing the conversation so far'],
+    ['config', 'Open settings'],
+    ['context', 'Visualize current context usage as a colored grid'],
+    ['copy', "Copy Claude's last response to clipboard (or /copy N for the Nth-latest)"],
+    ['desktop', 'Continue the current session in Claude Desktop'],
+    ['diff', 'View uncommitted changes and per-turn diffs'],
+    ['doctor', 'Diagnose and verify your Claude Code installation and settings'],
+    ['effort', 'Set effort level for model usage'],
+    ['exit', 'Exit the CLI'],
+    ['export', 'Export the current conversation to a file or clipboard'],
+    ['fast', 'Toggle fast mode (Opus 4.8)'],
+    ['feedback', 'Submit feedback, report a bug, or share your conversation'],
+    ['focus', 'Toggle focus view: just your prompt, summary, and response'],
+    ['fork', 'Spawn a background agent that inherits the full conversation'],
+    ['goal', 'Set a goal Claude checks before stopping'],
+    ['help', 'Show help and available commands'],
+    ['hooks', 'View hook configurations for tool events'],
+    ['ide', 'Manage IDE integrations and show status'],
+    ['install-github-app', 'Set up Claude GitHub Actions for a repository'],
+    ['install-slack-app', 'Install the Claude Slack app'],
+    ['keybindings', 'Open your keyboard shortcuts file'],
+    ['login', 'Sign in with your Anthropic account'],
+    ['logout', 'Sign out from your Anthropic account'],
+    ['mcp', 'Manage MCP servers'],
+    ['memory', 'Open a memory file in your editor'],
+    ['mobile', 'Show QR code to download the Claude mobile app'],
+    ['model', 'Set the AI model for Claude Code'],
+    ['permissions', 'Manage allow and deny tool permission rules'],
+    ['plan', 'Enable plan mode or view the current session plan'],
+    ['plugin', 'Manage Claude Code plugins'],
+    ['powerup', 'Discover Claude Code features through quick interactive lessons'],
+    ['privacy-settings', 'View and update your privacy settings'],
+    ['radio', 'Listen to Claude FM lo-fi radio'],
+    ['recap', 'Generate a one-line session recap now'],
+    ['release-notes', 'View release notes'],
+    ['reload-plugins', 'Activate pending plugin changes in the current session'],
+    ['reload-skills', 'Pick up skills added or changed on disk during this session'],
+    ['remote-control', 'Control this session from your phone or claude.ai/code'],
+    ['remote-env', 'Choose the default environment for cloud agents'],
+    ['rename', 'Rename the current conversation'],
+    ['resume', 'Resume a previous conversation'],
+    ['rewind', 'Restore the code and/or conversation to a previous point'],
+    ['sandbox', 'Configure sandbox settings'],
+    ['skills', 'List available skills'],
+    ['status', 'Show Claude Code status including version, model, account, API connectivity, and tool statuses'],
+    ['stickers', 'Order Claude Code stickers'],
+    ['tasks', 'View and manage everything running in the background'],
+    ['teleport', 'Resume a Claude Code session from claude.ai'],
+    ['terminal-setup', 'Install Shift+Enter key binding for newlines'],
+    ['theme', 'Change the theme'],
+    ['tui', 'Set the terminal UI renderer (default | fullscreen)'],
+    ['ultraplan', 'Draft an editable plan in Claude Code on the web'],
+    ['ultrareview', 'Start a cloud agent that finds and verifies bugs in your branch'],
+    ['upgrade', 'Upgrade to Max for higher rate limits and more Opus'],
+    ['usage', 'Show session cost, plan usage, and activity stats'],
+    ['usage-credits', 'Configure usage credits to keep working when you hit a limit'],
+    ['voice', 'Toggle voice mode'],
+    ['web-setup', 'Set up Claude Code on the web with your GitHub account'],
+    ['workflows', 'Browse running and completed workflows'],
+];
+// describe precedence (mirrors CC): a `description:` frontmatter line wins, else the first non-empty body
+// line (leading `#` stripped). Frontmatter parsing is intentionally one `key: value` line.
+function describe(src) {
+    const m = src.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    const fm = m ? m[1] : '';
+    const body = m ? m[2] : src;
+    for (const line of fm.split('\n')) {
+        const d = line.match(/^\s*description\s*:\s*(.+?)\s*$/);
+        if (d)
+            return d[1].replace(/^["']|["']$/g, '');
+    }
+    for (const line of body.split('\n')) {
+        const t = line.replace(/^#+\s*/, '').trim();
+        if (t)
+            return t;
+    }
+    return '';
+}
+// walk a commands/ dir; name = path under it minus `.md`, subdirs joined `a:b` (CC's namespace syntax).
+function scanCommands(root, source, out) {
+    if (!existsSync(root))
+        return;
+    const walk = (dir) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            const p = join(dir, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else if (e.isFile() && e.name.endsWith('.md')) {
+                const name = relative(root, p).replace(/\.md$/, '').split('/').join(':');
+                out.push({ name, description: describe(readFileSync(p, 'utf8')), source });
+            }
+        }
+    };
+    walk(root);
+}
+// best-effort skills: each skill is a dir with a SKILL.md whose `name:` (or dir name) is the command.
+function scanSkills(root, out) {
+    if (!existsSync(root))
+        return;
+    for (const e of readdirSync(root, { withFileTypes: true })) {
+        const skillFile = join(root, e.name, 'SKILL.md');
+        if (e.isDirectory() && existsSync(skillFile)) {
+            const src = readFileSync(skillFile, 'utf8');
+            const nm = src.match(/^---\n[\s\S]*?\nname\s*:\s*(.+?)\s*\n[\s\S]*?\n---/m);
+            out.push({ name: (nm ? nm[1] : e.name).trim(), description: describe(src), source: 'skill' });
+        }
+    }
+}
+// ordering mirrors CC: custom (user, then project), then built-in, then skills; alphabetical within each
+// group. A same-named custom command shadows a built-in — dedupe keeps the higher-priority source.
+const RANK = { user: 0, project: 1, 'built-in': 2, skill: 3 };
+// dedupe by name keeping the higher-priority source, then sort by source rank then name.
+function dedupeSort(all) {
+    const byName = new Map();
+    for (const c of all) {
+        const prev = byName.get(c.name);
+        if (!prev || RANK[c.source] < RANK[prev.source])
+            byName.set(c.name, c);
+    }
+    return [...byName.values()].sort((a, b) => RANK[a.source] - RANK[b.source] || a.name.localeCompare(b.name));
+}
+export function claudeSlashCommands() {
+    const home = homedir();
+    const repo = repoRoot();
+    const all = [];
+    scanCommands(join(home, '.claude', 'commands'), 'user', all);
+    scanCommands(join(repo, '.claude', 'commands'), 'project', all);
+    for (const [name, description] of BUILT_IN)
+        all.push({ name, description, source: 'built-in' });
+    scanSkills(join(home, '.claude', 'skills'), all);
+    scanSkills(join(repo, '.claude', 'skills'), all);
+    return dedupeSort(all);
+}
+// @@@ CODEX_BUILT_IN seed - Codex's `/` menu, taken from the codex-rs source of the pinned version
+// (tui/src/slash_command.rs, codex-cli 0.142.3): the `SlashCommand` enum in PRESENTATION order with each
+// `description()`. Discovered, not guessed — the same discipline as the Claude capture; to refresh for a new
+// codex, re-read that enum. We drop the ones codex itself hides from a normal session: the debug-only
+// (`rollout`, `test-approval`), the explicit DO-NOT-USE (`debug-m-drop`/`debug-m-update`), and the
+// windows-only `sandbox-add-read-dir`. Feature-gated commands are kept (best-effort: the menu is informational).
+const CODEX_BUILT_IN = [
+    ['model', 'choose what model and reasoning effort to use'],
+    ['ide', 'include current selection, open files, and other context from your IDE'],
+    ['permissions', 'choose what Codex is allowed to do'],
+    ['keymap', 'remap TUI shortcuts'],
+    ['vim', 'toggle Vim mode for the composer'],
+    ['setup-default-sandbox', 'set up elevated agent sandbox'],
+    ['experimental', 'toggle experimental features'],
+    ['approve', 'approve one retry of a recent auto-review denial'],
+    ['memories', 'configure memory use and generation'],
+    ['skills', 'use skills to improve how Codex performs specific tasks'],
+    ['import', 'import setup, this project, and recent chats from Claude Code'],
+    ['hooks', 'view and manage lifecycle hooks'],
+    ['review', 'review my current changes and find issues'],
+    ['rename', 'rename the current thread'],
+    ['new', 'start a new chat during a conversation'],
+    ['archive', 'archive this session and exit'],
+    ['delete', 'permanently delete this session and exit'],
+    ['resume', 'resume a saved chat'],
+    ['fork', 'fork the current chat'],
+    ['app', 'continue this session in Codex Desktop'],
+    ['init', 'create an AGENTS.md file with instructions for Codex'],
+    ['compact', 'summarize conversation to prevent hitting the context limit'],
+    ['plan', 'switch to Plan mode'],
+    ['goal', 'set or view the goal for a long-running task'],
+    ['agent', 'switch the active agent thread'],
+    ['side', 'start a side conversation in an ephemeral fork'],
+    ['btw', 'start a side conversation in an ephemeral fork'],
+    ['copy', 'copy last response as markdown'],
+    ['raw', 'toggle raw scrollback mode for copy-friendly terminal selection'],
+    ['diff', 'show git diff (including untracked files)'],
+    ['mention', 'mention a file'],
+    ['status', 'show current session configuration and token usage'],
+    ['usage', 'view account usage or use a usage limit reset'],
+    ['debug-config', 'show config layers and requirement sources for debugging'],
+    ['title', 'configure which items appear in the terminal title'],
+    ['statusline', 'configure which items appear in the status line'],
+    ['theme', 'choose a syntax highlighting theme'],
+    ['pets', 'choose or hide the terminal pet'],
+    ['mcp', 'list configured MCP tools; use /mcp verbose for details'],
+    ['apps', 'manage apps'],
+    ['plugins', 'browse plugins'],
+    ['logout', 'log out of Codex'],
+    ['quit', 'exit Codex'],
+    ['exit', 'exit Codex'],
+    ['feedback', 'send logs to maintainers'],
+    ['ps', 'list background terminals'],
+    ['stop', 'stop all background terminals'],
+    ['clear', 'clear the terminal and start a new chat'],
+    ['personality', 'choose a communication style for Codex'],
+    ['subagents', 'switch the active agent thread'],
+];
+// @@@ codexSlashCommands - Codex's `/` menu, computed the way Codex computes its own: its built-ins (above) +
+// the user's saved prompts in `$CODEX_HOME/prompts/*.md` (each filename becomes `/<name>`, codex's custom-
+// prompt convention). Like the Claude builder it NEVER guesses — plugin commands that aren't readable as
+// simple files contribute nothing. Presentation order: built-ins first (codex's enum order), then prompts.
+// @@@ PI_BUILT_IN seed - pi's `/` menu, extracted from the INSTALLED pi's own command table
+// (dist/core/slash-commands.js, @earendil-works/pi-coding-agent 0.80.10) — discovered, not guessed, same
+// discipline as the claude/codex captures; to refresh for a new pi, re-read that module.
+const PI_BUILT_IN = [
+    ['settings', 'Open settings menu'],
+    ['model', 'Select model (opens selector UI)'],
+    ['scoped-models', 'Enable/disable models for Ctrl+P cycling'],
+    ['export', 'Export session (HTML default, or specify path: .html/.jsonl)'],
+    ['import', 'Import and resume a session from a JSONL file'],
+    ['share', 'Share session as a secret GitHub gist'],
+    ['copy', 'Copy last agent message to clipboard'],
+    ['name', 'Set session display name'],
+    ['session', 'Show session info and stats'],
+    ['changelog', 'Show changelog entries'],
+    ['hotkeys', 'Show all keyboard shortcuts'],
+    ['fork', 'Create a new fork from a previous user message'],
+    ['clone', 'Duplicate the current session at the current position'],
+    ['tree', 'Navigate session tree (switch branches)'],
+    ['trust', 'Save project trust decision for future sessions'],
+    ['login', 'Configure provider authentication'],
+    ['logout', 'Remove provider authentication'],
+    ['new', 'Start a new session'],
+    ['compact', 'Manually compact the session context'],
+    ['resume', 'Resume a different session'],
+    ['reload', 'Reload keybindings, extensions, skills, prompts, themes, and context files'],
+];
+// @@@ piSlashCommands - pi's `/` menu, computed the way pi computes its own: built-ins (above) + prompt
+// templates (`~/.pi/agent/prompts/*.md` global, `.pi/prompts/*.md` project — each filename becomes `/<name>`)
+// + skills (`/skill:<name>` is pi's spelling, but the bare name is what our dropdown wants). Best-effort like
+// the codex builder: what isn't readable as simple files contributes nothing.
+export function piSlashCommands() {
+    const repo = repoRoot();
+    const all = [];
+    for (const [name, description] of PI_BUILT_IN)
+        all.push({ name, description, source: 'built-in' });
+    scanCommands(join(homedir(), '.pi', 'agent', 'prompts'), 'user', all);
+    scanCommands(join(repo, '.pi', 'prompts'), 'project', all);
+    scanSkills(join(homedir(), '.pi', 'agent', 'skills'), all);
+    scanSkills(join(repo, '.pi', 'skills'), all);
+    return dedupeSort(all);
+}
+export function codexSlashCommands() {
+    const all = [];
+    for (const [name, description] of CODEX_BUILT_IN)
+        all.push({ name, description, source: 'built-in' });
+    const codexHome = process.env.CODEX_HOME || join(homedir(), '.codex');
+    scanCommands(join(codexHome, 'prompts'), 'user', all); // saved prompts → /<basename>
+    // codex built-ins keep their enum (presentation) order; user prompts sort after, alphabetical.
+    const seen = new Map();
+    const order = [];
+    for (const c of all) {
+        if (!seen.has(c.name))
+            order.push(c.name);
+        if (!seen.has(c.name) || RANK[c.source] < RANK[seen.get(c.name).source])
+            seen.set(c.name, c);
+    }
+    const builtins = order.filter((n) => seen.get(n).source === 'built-in').map((n) => seen.get(n));
+    const prompts = [...seen.values()].filter((c) => c.source !== 'built-in').sort((a, b) => a.name.localeCompare(b.name));
+    return [...builtins, ...prompts];
+}
+// opencode built-ins — a conservative pinned set (opencode 1.18.x TUI commands; its TUI registry is compiled,
+// not file-discoverable, so like the other two capture blocks this is version-specific and re-pinned by hand).
+const OPENCODE_BUILT_IN = [
+    ['compact', 'Summarize and compact the current session'],
+    ['editor', 'Open the external editor for the message'],
+    ['exit', 'Exit opencode'],
+    ['export', 'Export the session'],
+    ['help', 'Show help'],
+    ['init', 'Create or update AGENTS.md'],
+    ['models', 'List and switch models'],
+    ['new', 'Start a new session'],
+    ['redo', 'Redo a previously undone message'],
+    ['sessions', 'List and switch sessions'],
+    ['share', 'Share the current session'],
+    ['themes', 'List and switch themes'],
+    ['undo', 'Undo the last message'],
+    ['unshare', 'Unshare the current session'],
+];
+// @@@ opencodeSlashCommands - opencode's `/` menu: the pinned built-ins + custom commands discovered the way
+// opencode discovers its own — `.opencode/command(s)/**/*.md` in the project and `~/.config/opencode/command(s)`
+// globally (both spellings are native). Like the other builders it never guesses: what isn't readable as a
+// file contributes nothing.
+export function opencodeSlashCommands() {
+    const all = [];
+    const cfgHome = process.env.OPENCODE_CONFIG_DIR || join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'opencode');
+    for (const d of ['command', 'commands'])
+        scanCommands(join(cfgHome, d), 'user', all);
+    const repo = repoRoot();
+    for (const d of ['command', 'commands'])
+        scanCommands(join(repo, '.opencode', d), 'project', all);
+    for (const [name, description] of OPENCODE_BUILT_IN)
+        all.push({ name, description, source: 'built-in' });
+    scanSkills(join(repo, '.opencode', 'skills'), all);
+    return dedupeSort(all);
+}

package/dist/source-files.d.ts

@@ -0,0 +1,9 @@
+export type SourcePolicy = {
+    sourceIncludeGlobs: string[] | null;
+    sourceExcludeGlobs: string[];
+    testGlobs: string[];
+};
+export declare const DEFAULT_TEST_GLOBS: string[];
+export declare function isSourceFile(root: string, path: string, policy: SourcePolicy): boolean;
+export declare function trackedSourceFiles(root: string, roots: string[], policy: SourcePolicy, tip?: string): string[];
+export declare function sourcePolicyDescription(policy: SourcePolicy): string;

package/dist/source-files.js

@@ -0,0 +1,113 @@
+import { closeSync, lstatSync, openSync, readSync } from 'node:fs';
+import { join } from 'node:path';
+import { git } from '@spexcode/spec-core';
+export const DEFAULT_TEST_GLOBS = [
+    '**/*.test.*',
+    '**/*.spec.*',
+    '**/test_*.*',
+    '**/*_test.*',
+    '**/test/**',
+    '**/tests/**',
+    '**/__tests__/**',
+];
+function globToRe(glob) {
+    const body = glob.split(/(\*\*\/|\*\*|\*|\?)/).map((seg) => {
+        if (seg === '**/')
+            return '(?:.*/)?';
+        if (seg === '**')
+            return '.*';
+        if (seg === '*')
+            return '[^/]*';
+        if (seg === '?')
+            return '[^/]';
+        return seg.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }).join('');
+    return new RegExp(`^${body}$`);
+}
+function isSpexCodeData(path) {
+    return path === 'spexcode.json' || path === 'spexcode.local.json'
+        || path === '.spec' || path.startsWith('.spec/')
+        || path === '.plugins' || path.startsWith('.plugins/');
+}
+function isTextWorktreeFile(root, path) {
+    const full = join(root, path);
+    let fd = null;
+    try {
+        if (!lstatSync(full).isFile())
+            return false;
+        fd = openSync(full, 'r');
+        const sample = Buffer.allocUnsafe(8000);
+        const bytes = readSync(fd, sample, 0, sample.length, 0);
+        return !sample.subarray(0, bytes).includes(0);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+// Source discovery classifies tracked paths and bytes only. Language structure belongs to anchors.ts's
+// adapter registry; adding a language must never add a branch here.
+export function isSourceFile(root, path, policy) {
+    if (!isSourcePath(path, policy))
+        return false;
+    return isTextWorktreeFile(root, path);
+}
+function isSourcePath(path, policy) {
+    if (isSpexCodeData(path))
+        return false;
+    if (policy.sourceIncludeGlobs !== null && !policy.sourceIncludeGlobs.some((glob) => globToRe(glob).test(path)))
+        return false;
+    if (policy.sourceExcludeGlobs.some((glob) => globToRe(glob).test(path)))
+        return false;
+    if (policy.testGlobs.some((glob) => globToRe(glob).test(path)))
+        return false;
+    return true;
+}
+export function trackedSourceFiles(root, roots, policy, tip = 'HEAD') {
+    if (tip !== 'HEAD') {
+        let listed = '', textOut = '';
+        try {
+            listed = git(['-C', root, '-c', 'core.quotePath=false', 'ls-tree', '-r', '-z', '-l', tip, '--', ...roots]);
+            textOut = git(['-C', root, '-c', 'core.quotePath=false', 'grep', '-I', '-l', '-z', '-e', '', tip, '--', ...roots]);
+        }
+        catch { /* git grep exits 1 when the tree slice has no non-empty text */ }
+        const text = new Set(textOut.split('\0').map((entry) => {
+            const prefix = `${tip}:`;
+            return entry.startsWith(prefix) ? entry.slice(prefix.length) : entry;
+        }).filter(Boolean));
+        const out = new Set();
+        for (const record of listed.split('\0')) {
+            if (!record)
+                continue;
+            const m = record.match(/^100\d+ blob [0-9a-f]+\s+(\d+)\t([\s\S]+)$/);
+            if (!m)
+                continue;
+            const path = m[2];
+            if (isSourcePath(path, policy) && (+m[1] === 0 || text.has(path)))
+                out.add(path);
+        }
+        return [...out];
+    }
+    const out = new Set();
+    for (const governedRoot of roots) {
+        let listed = '';
+        try {
+            listed = git(['-C', root, 'ls-files', '-z', '--', governedRoot]);
+        }
+        catch {
+            continue;
+        }
+        for (const path of listed.split('\0')) {
+            if (path && isSourceFile(root, path, policy))
+                out.add(path);
+        }
+    }
+    return [...out];
+}
+export function sourcePolicyDescription(policy) {
+    const includes = policy.sourceIncludeGlobs === null ? 'ALL tracked regular text' : `[${policy.sourceIncludeGlobs.join(', ')}]`;
+    return `includes ${includes}; sourceExcludeGlobs [${policy.sourceExcludeGlobs.join(', ')}]; testGlobs [${policy.testGlobs.join(', ')}] (SpexCode-owned data always excluded)`;
+}

package/dist/supervise.d.ts

@@ -0,0 +1 @@
+export {};