@synovitec/trellis 0.0.0-stage → 0.6.0-rc.2

package/src/agents/state.mjs

@@ -0,0 +1,233 @@
+// What a session looked like when it started, and the evidence collected since, inside the
+// repository's git folder (never committed), signed with a key kept outside the repository.
+//
+// Two files per session. The snapshot (`<id>.json`) is written once at session start; only the
+// Stop hook rewrites it, to count its blocks. The evidence (`<id>.events.jsonl`) is append-only,
+// one signed line per event, so hooks running in parallel add to it without losing each other's
+// lines. The agent runs as the same user, so nothing here is out of its reach: the signature
+// makes an edit detectable, the deny rules and the shell guard make it a deliberate act, and a
+// missing or altered file is itself a finding. Evidence is only ever positive (a check that
+// happened), so removing a line can only hurt the agent that removes it.
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { git } from "./git.mjs";
+
+/**
+ * @typedef {object} Ledger  evidence, folded from the event log
+ * @property {Record<string, string>} browser  file → its content hash at the last browser check
+ * @property {Record<string, string>} setup    file → its content hash at the last clean AgentShield run
+ * @property {boolean} graph                   a code graph query returned an answer
+ * @property {boolean} schema                  a database schema lookup succeeded
+ * @property {string[]} lookups                Context7 calls, as lowercased input
+ * @property {number} searches                 file searches
+ * @property {boolean} onPage                  the browser's last navigation was to the origin
+ * @property {boolean} nudged                  the graph reminder was given
+ */
+
+/**
+ * @typedef {object} SessionState
+ * @property {number} v
+ * @property {number} startedAt
+ * @property {string | null} head
+ * @property {string[]} [tips]        where local branches, HEAD and the stash pointed at the start
+ * @property {string[]} [remotes]     where the remote-tracking refs pointed at the start
+ * @property {number} [reflog]        HEAD's reflog length at the start
+ * @property {Record<string, string>} dirty
+ * @property {string[]} flagged       files git was told to ignore (assume-unchanged, skip-worktree)
+ * @property {string | null} exclude  .git/info/exclude as it was
+ * @property {string[]} [ignored]     what git ignored and did not track at the start
+ * @property {string | null} [ignoreRules] a fingerprint of the ignore rules at the start
+ * @property {number} stashes
+ * @property {string | null} configText
+ * @property {string | null} [self]   a hash of Trellis's own code, as installed at the start
+ * @property {number} blocks
+ * @property {Ledger} ledger
+ */
+
+/** Session files older than this are removed when a new session starts. */
+const KEEP_MS = 30 * 24 * 3600 * 1000;
+
+/** @returns {Ledger} */
+export const emptyLedger = () => ({ browser: {}, setup: {}, graph: false, schema: false, lookups: [], searches: 0, onPage: false, nudged: false });
+
+/**
+ * A test override (`TRELLIS_STATE_DIR`, `TRELLIS_KEY_FILE`, `TRELLIS_AGENTSHIELD`), honoured only
+ * under Node's test runner and outside Claude Code's project (`CLAUDE_PROJECT_DIR`), where a
+ * settings file's `env` could set it. An agent's own command could set it too: the shell guard
+ * refuses a command that does (hooks.mjs).
+ * @param {NodeJS.ProcessEnv} env
+ * @param {"TRELLIS_STATE_DIR" | "TRELLIS_KEY_FILE" | "TRELLIS_AGENTSHIELD" | "TRELLIS_GRAPHIFY"} name
+ * @returns {string | undefined}
+ */
+export const testOverride = (env, name) => (env.CLAUDE_PROJECT_DIR || !underTest(env) ? undefined : env[name] || undefined);
+
+/** Whether Node's test runner started this process (or its parent, whose environment it inherits). @param {NodeJS.ProcessEnv} env */
+const underTest = (env) => Boolean(process.env.NODE_TEST_CONTEXT || env.NODE_TEST_CONTEXT);
+
+/**
+ * Where a repository's session files live: its git folder, else the temp folder.
+ * @param {string} root
+ * @param {NodeJS.ProcessEnv} env
+ */
+export function stateDir(root, env = process.env) {
+  const override = testOverride(env, "TRELLIS_STATE_DIR");
+  if (override) return override;
+  const common = git(root, ["rev-parse", "--git-common-dir"])?.trim();
+  return common ? join(resolve(root, common), "trellis", "sessions") : join(tmpdir(), "trellis-sessions");
+}
+
+/** @param {NodeJS.ProcessEnv} env */
+export const keyFile = (env = process.env) => {
+  const override = testOverride(env, "TRELLIS_KEY_FILE");
+  if (override) return override;
+  // A test that forgot its key would sign with the developer's own: fail it instead.
+  if (underTest(env) && !env.CLAUDE_PROJECT_DIR) throw new Error("a test reached the real signing key (~/.trellis): set TRELLIS_KEY_FILE");
+  return join(homedir(), ".trellis", "key");
+};
+
+/** The signing key, created once per user, readable by the user only. @param {NodeJS.ProcessEnv} env */
+function key(env) {
+  const file = keyFile(env);
+  if (!existsSync(file)) {
+    mkdirSync(join(file, ".."), { recursive: true });
+    writeFileSync(file, randomBytes(32).toString("hex"), { mode: 0o600 });
+    try {
+      chmodSync(file, 0o600);
+    } catch {
+      /* Windows keeps its own ACLs */
+    }
+  }
+  return readFileSync(file, "utf8").trim();
+}
+
+/** @param {string} body @param {NodeJS.ProcessEnv} env */
+export const sign = (body, env) => createHmac("sha256", key(env)).update(body).digest("hex");
+
+/** @param {unknown} sig @param {string} body @param {NodeJS.ProcessEnv} env */
+export function valid(sig, body, env) {
+  const expected = Buffer.from(sign(body, env), "hex");
+  const got = Buffer.from(String(sig ?? ""), "hex");
+  return got.length === expected.length && timingSafeEqual(got, expected);
+}
+
+/** @param {string} sessionId */
+const baseName = (sessionId) => sessionId.replace(/[^A-Za-z0-9_.-]/g, "_");
+
+/**
+ * The evidence, folded in the order it was recorded.
+ * @param {Array<Record<string, any>>} events
+ * @returns {Ledger}
+ */
+export function fold(events) {
+  const l = emptyLedger();
+  for (const e of events) {
+    if (e.k === "graph") l.graph = true;
+    else if (e.k === "schema") l.schema = true;
+    else if (e.k === "search") l.searches++;
+    else if (e.k === "lookup") l.lookups.push(String(e.q ?? ""));
+    else if (e.k === "nav") l.onPage = !!e.on;
+    else if (e.k === "browser") Object.assign(l.browser, e.files ?? {});
+    else if (e.k === "setup") Object.assign(l.setup, e.files ?? {});
+    else if (e.k === "nudged") l.nudged = true;
+  }
+  return l;
+}
+
+/**
+ * @param {string} root
+ * @param {string | undefined} sessionId
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ state: SessionState | null, status: "ok" | "missing" | "tampered" | "no-session" }}
+ */
+export function loadState(root, sessionId, env = process.env) {
+  if (!sessionId) return { state: null, status: "no-session" };
+  const dir = stateDir(root, env);
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(join(dir, `${baseName(sessionId)}.json`), "utf8"));
+  } catch {
+    return { state: null, status: "missing" };
+  }
+  if (!valid(raw?.sig, JSON.stringify(raw?.state ?? null), env)) return { state: null, status: "tampered" };
+  /** @type {Array<Record<string, any>>} */
+  const events = [];
+  let text = "";
+  try {
+    text = readFileSync(join(dir, `${baseName(sessionId)}.events.jsonl`), "utf8");
+  } catch {
+    /* no evidence yet */
+  }
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      // A line a parallel hook is still appending can be read half-written; the next read has it whole.
+      continue;
+    }
+    if (!valid(rec?.sig, JSON.stringify(rec?.e ?? null), env)) return { state: null, status: "tampered" };
+    events.push(rec.e);
+  }
+  return { state: { ...raw.state, ledger: fold(events) }, status: "ok" };
+}
+
+/**
+ * Writes the snapshot (once at session start, and when Stop counts a block). The ledger is not
+ * part of it: evidence goes through `record`.
+ * @param {string} root
+ * @param {string | undefined} sessionId
+ * @param {SessionState} state
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function saveState(root, sessionId, state, env = process.env) {
+  if (!sessionId) return;
+  const dir = stateDir(root, env);
+  mkdirSync(dir, { recursive: true });
+  const { ledger, ...snapshot } = state;
+  void ledger;
+  const file = join(dir, `${baseName(sessionId)}.json`);
+  // Written beside, then renamed over: a reader never sees half a snapshot.
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ state: snapshot, sig: sign(JSON.stringify(snapshot), env) }));
+  renameSync(tmp, file);
+}
+
+/**
+ * Appends one signed event to the session's evidence.
+ * @param {string} root
+ * @param {string | undefined} sessionId
+ * @param {Record<string, any>} event
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function record(root, sessionId, event, env = process.env) {
+  if (!sessionId) return;
+  const dir = stateDir(root, env);
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, `${baseName(sessionId)}.events.jsonl`), `${JSON.stringify({ e: event, sig: sign(JSON.stringify(event), env) })}\n`);
+}
+
+/**
+ * Removes session files older than 30 days.
+ * @param {string} root
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {number} [now]
+ */
+export function prune(root, env = process.env, now = Date.now()) {
+  const dir = stateDir(root, env);
+  let names = [];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const n of names) {
+    try {
+      if (now - statSync(join(dir, n)).mtimeMs > KEEP_MS) unlinkSync(join(dir, n));
+    } catch {
+      /* in use or gone */
+    }
+  }
+}

package/src/agents/transcript.mjs

@@ -0,0 +1,120 @@
+// What a coding agent actually did in a session, read from its transcript: every tool call, with
+// its time. Which files changed is read from git (git.mjs); the transcript's own edit calls are
+// the fallback outside a git repository.
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+/**
+ * @typedef {{ i: number, t: number, id?: string, name: string, input: Record<string, any> }} ToolUse
+ * `t` is the call's time (ms since epoch), 0 when the transcript has none.
+ */
+
+/** Tools whose call writes a file, and the input field that names it. */
+const EDIT_TOOLS = /** @type {Record<string, string>} */ ({ Edit: "file_path", Write: "file_path", MultiEdit: "file_path", NotebookEdit: "notebook_path" });
+/** Symbol-level editors over MCP that take a repository-relative path. */
+const MCP_EDIT = /^mcp__[^_]+(?:_[^_]+)*__(replace|insert|create|rename|safe_delete|write|edit)/;
+
+/**
+ * Every tool call of a session, its subagents' included, in time order. A subagent writes its
+ * own transcript (`<session>/subagents/agent-*.jsonl` beside the main one): the work it does is
+ * the session's work, so a browser check or a scan it ran counts, and so does an edit.
+ * Unreadable lines are skipped: a transcript is appended while the session runs.
+ * @param {string | null | undefined} path
+ * @returns {{ uses: ToolUse[], readable: boolean }}
+ */
+export function readSession(path) {
+  if (!path) return { uses: [], readable: false };
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return { uses: [], readable: false };
+  }
+  const all = parseToolUses(text);
+  const subDir = join(dirname(path), basename(path).replace(/\.jsonl$/, ""), "subagents");
+  let files = [];
+  try {
+    files = readdirSync(subDir).filter((f) => f.endsWith(".jsonl"));
+  } catch {
+    /* no subagent ran */
+  }
+  for (const f of files) {
+    try {
+      all.push(...parseToolUses(readFileSync(join(subDir, f), "utf8")));
+    } catch {
+      /* a subagent file being written */
+    }
+  }
+  // Stable: calls without a time keep their order relative to each other.
+  const sorted = all.map((u, k) => ({ u, k })).sort((a, b) => a.u.t - b.u.t || a.k - b.k);
+  return { uses: sorted.map(({ u }, i) => ({ ...u, i })), readable: true };
+}
+
+/** @param {string | null | undefined} path */
+export function readToolUses(path) {
+  return readSession(path).uses;
+}
+
+/** @param {string} text @returns {ToolUse[]} */
+export function parseToolUses(text) {
+  /** @type {ToolUse[]} */
+  const out = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.includes('"tool_use"')) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const content = entry?.message?.role === "assistant" ? entry.message.content : null;
+    if (!Array.isArray(content)) continue;
+    const t = Date.parse(entry.timestamp ?? "") || 0;
+    for (const c of content) {
+      if (c?.type === "tool_use" && typeof c.name === "string") out.push({ i: out.length, t, id: typeof c.id === "string" ? c.id : undefined, name: c.name, input: c.input ?? {} });
+    }
+  }
+  return out;
+}
+
+/**
+ * The repository-relative path a tool call wrote, or null when it wrote nothing (or outside the
+ * repository). Edits made through a shell command are not seen: that is a stated limit.
+ * @param {ToolUse} use
+ * @param {string} root
+ * @param {NodeJS.Platform} platform
+ */
+export function editedPath(use, root, platform) {
+  const field = EDIT_TOOLS[use.name];
+  if (field) return relativeTo(use.input[field], root, platform);
+  if (!MCP_EDIT.test(use.name)) return null;
+  const p = use.input.relative_path ?? use.input.path ?? use.input.file_path;
+  return typeof p === "string" ? relativeTo(p, root, platform) : null;
+}
+
+/**
+ * @param {unknown} file
+ * @param {string} root
+ * @param {NodeJS.Platform} platform
+ */
+export function relativeTo(file, root, platform) {
+  if (typeof file !== "string" || !file) return null;
+  const norm = (/** @type {string} */ p) => {
+    let s = p.replace(/\\/g, "/").replace(/\/+$/, "");
+    // Git Bash spells C:\x as /c/x.
+    if (platform === "win32") s = s.replace(/^\/([a-zA-Z])\//, "$1:/");
+    return s;
+  };
+  const f = norm(file);
+  const r = norm(root);
+  // Windows and macOS file systems are case-insensitive by default.
+  const same = platform === "win32" || platform === "darwin" ?(/** @type {string} */ a, /** @type {string} */ b) => a.toLowerCase() === b.toLowerCase() : (/** @type {string} */ a, /** @type {string} */ b) => a === b;
+  if (!/^([a-zA-Z]:)?\//.test(f)) return f.replace(/^\.\//, "");
+  if (f.length > r.length && same(f.slice(0, r.length), r) && f[r.length] === "/") return f.slice(r.length + 1);
+  return null;
+}
+
+/** The shell command of a call, or "". @param {ToolUse} use */
+export function commandOf(use) {
+  return use.name === "Bash" || use.name === "PowerShell" ? String(use.input.command ?? "") : "";
+}

package/src/cli/main.mjs

@@ -0,0 +1,191 @@
+// Argument parsing and dispatch; no tool logic lives here.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createContext } from "../core/context.mjs";
+import { PASSTHROUGH, runAbatty } from "../core/abatty.mjs";
+import { doctor } from "../commands/doctor.mjs";
+import { init } from "../commands/init.mjs";
+import { guide } from "../commands/guide.mjs";
+import { scan } from "../commands/scan.mjs";
+import { TOOLS } from "../tools/registry.mjs";
+import { ROLES } from "../tools/roles.mjs";
+import { handleHook, hookFailure, hookRoot, EVENTS } from "../agents/hooks.mjs";
+import { uninstall } from "../commands/uninstall.mjs";
+import { parseJson } from "../core/context.mjs";
+import { approve, checkTests, commitCheckpoint, escalate, evidenceReset, verify, verifyCi } from "../commands/verify.mjs";
+import { keyCommand } from "../commands/key.mjs";
+import { agentHook } from "../agents/adapters.mjs";
+import { serveMcp } from "../mcp/server.mjs";
+import { trustCommand } from "../mcp/trust.mjs";
+
+/** A hook's JSON input. Nothing to read from a terminal: an interactive run has no event. */
+function readStdin() {
+  if (process.stdin.isTTY) return "";
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+const HELP = `trellis - the frame a repository grows on
+
+  trellis init [--dry-run] [--agents[=cursor,codex,copilot]]
+                                write trellis.config.json, the MCP servers and the AGENTS.md block;
+                                --agents also the Claude Code hooks and a pre-commit secret scan
+  trellis hook <${EVENTS.join("|")}>
+                                what the agent hooks run (reads the hook's JSON on stdin)
+  trellis uninstall [--dry-run]  take out the agent hooks, the pre-commit hook and the AGENTS.md block
+  trellis doctor [--json] [--strict] [--all]
+                                every enabled tool: installed? actually wired? what to do next
+  trellis guide [tool|role]     which tool answers which question, and how to use it here
+  trellis tools                 every tool Trellis knows, by role
+  trellis scan [--history] [--only a,b] [--allow-missing]
+                                run the enabled scanners (Gitleaks, OSV-Scanner, AgentShield)
+  trellis verify                the staged change against the rules (the pre-commit checkpoint)
+  trellis verify --ci [--base <rev>] [--head <rev>] [--summary <file>] [--checksums <file>]
+                                every commit after base: its attestation checked, the checks re-run here
+  trellis evidence reset        a person sets an unusable evidence log aside and starts a new one
+  trellis key [--add]           this developer's public key; --add commits it under .trellis/keys/
+  trellis check tests -- <cmd>  run the tests and record what they ran on
+  trellis escalate "<why>"      an agent stops and hands the change to a person
+  trellis approve               a person approves the change as it is now (in a terminal)
+  trellis checkpoint [--merge | --rewritten <how>]
+                                after a commit, merge or rewrite: attest it (the git hooks run it)
+  trellis mcp                   the MCP server: the checks as tools for any agent, recorded as evidence
+  trellis mcp trust             a person trusts the .mcp.json servers the gateway may start (in a terminal)
+  trellis ${PASSTHROUGH.join("|")} [...]
+                                the guard engine: abatty's command, run as it is
+
+Roles: ${ROLES.map((r) => r.id).join(", ")}.  Exit codes: 0 ok, 1 something to fix, 2 bad usage.`;
+
+/**
+ * @typedef {object} IO
+ * @property {string} [cwd]
+ * @property {(...lines: string[]) => void} [out]
+ * @property {string} [stdin]                      a hook's input; read from the process when absent
+ * @property {(text: string) => void} [stdout]     raw output, for hooks
+ * @property {(text: string) => void} [stderr]
+ * @property {NodeJS.ProcessEnv} [env]
+ */
+
+/**
+ * @param {string[]} argv
+ * @param {IO} [io]
+ * @returns {number | Promise<number>} exit code (a promise for the commands that use the network)
+ */
+export function main(argv, io = {}) {
+  const root = io.cwd ?? process.cwd();
+  const out = io.out ?? ((/** @type {string[]} */ ...lines) => lines.forEach((l) => console.log(l)));
+  const [cmd, ...rest] = argv;
+  const flag = (/** @type {string} */ name) => rest.includes(`--${name}`);
+  const opt = (/** @type {string} */ name) => {
+    const i = rest.indexOf(`--${name}`);
+    return i === -1 ? undefined : rest[i + 1];
+  };
+  const ctx = createContext({ root });
+  const write = (/** @type {string} */ rel, /** @type {string} */ text, /** @type {boolean | undefined} */ executable) => {
+    // Absolute when git keeps its hooks outside the work tree (worktrees, a global hooksPath).
+    const full = resolve(root, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, text, executable ? { mode: 0o755 } : undefined);
+  };
+  try {
+    switch (cmd) {
+      case "init":
+      {
+        const list = rest.find((x) => x.startsWith("--agents="));
+        const agentList = list ? list.slice("--agents=".length).split(",").map((x) => x.trim()).filter(Boolean) : undefined;
+        return init(ctx, { dryRun: flag("dry-run"), agents: flag("agents") || Boolean(list), agentList }, out, write, io.env);
+      }
+      case "hook": {
+        const input = parseJson(io.stdin ?? readStdin()) ?? {};
+        const env = io.env ?? process.env;
+        const a = rest.indexOf("--agent");
+        const agent = a === -1 ? null : String(rest[a + 1] ?? "");
+        let r;
+        try {
+          const hctx = createContext({ root: hookRoot(input, env, root) });
+          r = agent ? agentHook(agent, rest[0] ?? "", input, hctx, env) : handleHook(rest[0] ?? "", input, hctx, { env });
+        } catch (err) {
+          // A crash in a hook must not read as a pass. Claude Code treats any exit but 2 as one; for
+          // the other agents a crashed pre-tool hook exits 2, a deny for Codex and Copilot, and
+          // Cursor's entry is written with failClosed.
+          r = agent
+            ? { code: rest[0] === "pre-tool" ? 2 : 0, stderr: `[trellis] hook ${rest[0]} failed: ${err instanceof Error ? err.message : String(err)}\n` }
+            : hookFailure(rest[0] ?? "", input, err);
+        }
+        if (r.stdout) (io.stdout ?? ((/** @type {string} */ t) => process.stdout.write(t)))(r.stdout);
+        if (r.stderr) (io.stderr ?? ((/** @type {string} */ t) => process.stderr.write(t)))(r.stderr);
+        return r.code;
+      }
+      case "uninstall":
+        return uninstall(ctx, { dryRun: flag("dry-run") }, out, write);
+      case "doctor":
+        return doctor(ctx, { json: flag("json"), strict: flag("strict"), all: flag("all"), env: io.env }, out);
+      case "guide":
+        return guide(ctx, rest.find((a) => !a.startsWith("--")), out);
+      case "tools":
+        for (const role of ROLES) {
+          out(role.title);
+          for (const t of TOOLS.filter((x) => x.role === role.id)) out(`  ${t.id.padEnd(16)} ${t.name}${t.ai ? " (agent)" : ""}`);
+        }
+        return 0;
+      case "scan": {
+        const i = rest.indexOf("--only");
+        const only = i === -1 ? [] : String(rest[i + 1] ?? "").split(",").filter(Boolean);
+        return scan(ctx, { history: flag("history"), allowMissing: flag("allow-missing"), only }, out);
+      }
+      case "verify": {
+        if (!flag("ci")) return verify(ctx, out, { env: io.env });
+        return verifyCi(ctx, out, { env: io.env, base: opt("base"), head: opt("head"), summary: opt("summary"), checksums: opt("checksums") });
+      }
+      case "evidence":
+        if (rest[0] !== "reset") {
+          out("Usage: trellis evidence reset   (a person sets an unusable evidence log aside)");
+          return 2;
+        }
+        return evidenceReset(ctx, out, { env: io.env });
+      case "key":
+        return keyCommand(ctx, { add: flag("add") }, out, io.env ?? process.env);
+      case "check": {
+        if (rest[0] !== "tests") {
+          out('Usage: trellis check tests -- <test command>');
+          return 2;
+        }
+        const dash = rest.indexOf("--");
+        return checkTests(ctx, dash === -1 ? [] : rest.slice(dash + 1), out, { env: io.env });
+      }
+      case "escalate":
+        return escalate(ctx, rest.join(" "), out, { env: io.env });
+      case "approve":
+        return approve(ctx, out, { env: io.env });
+      case "checkpoint":
+        return commitCheckpoint(ctx, out, { env: io.env, merge: flag("merge"), rewritten: opt("rewritten"), input: opt("rewritten") ? (io.stdin ?? readStdin()) : undefined });
+      case "mcp": {
+        // Launched by an agent from wherever it stands: the repository is the project it names,
+        // else the nearest folder above holding the config.
+        const env = io.env ?? process.env;
+        if (rest[0] === "trust") return trustCommand(ctx, out, { env });
+        return serveMcp(createContext({ root: hookRoot({ cwd: root }, env, root) }), env);
+      }
+      case "--version":
+      case "-v":
+        out(JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version);
+        return 0;
+      case undefined:
+      case "help":
+      case "--help":
+      case "-h":
+        out(HELP);
+        return 0;
+      default:
+        if (PASSTHROUGH.includes(cmd)) return runAbatty(root, [cmd, ...rest], out);
+        out(`Unknown command "${cmd}".`, "", HELP);
+        return 2;
+    }
+  } catch (err) {
+    out(`trellis ${cmd}: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}