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

package/src/agents/install-adapters.mjs

@@ -0,0 +1,172 @@
+// Writes the hooks of Cursor, Codex and Copilot, each in its own file and format (each agent's hook
+// reference, read 2026-10-30), merged into what the team already has. Every command fails closed:
+// with Trellis gone it blocks, never passes.
+import { parseJson } from "../core/context.mjs";
+import { installKind, SCRIPT } from "./install.mjs";
+
+/** Where each agent reads its project hooks. */
+export const ADAPTER_FILES = Object.freeze({ cursor: ".cursor/hooks.json", codex: ".codex/hooks.json", copilot: ".github/hooks/trellis.json" });
+
+/**
+ * The agents this repository or machine shows signs of: the agent's folder or file in the
+ * repository, or its command on the PATH.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @returns {string[]}
+ */
+export function detectAgents(ctx) {
+  const found = [];
+  if (ctx.exists(".cursor") || ctx.which("cursor") || ctx.which("cursor-agent")) found.push("cursor");
+  if (ctx.exists(".codex") || ctx.which("codex")) found.push("codex");
+  if (ctx.exists(".github/copilot-instructions.md") || ctx.exists(".github/hooks") || ctx.which("copilot")) found.push("copilot");
+  return found;
+}
+
+const GONE = "Trellis is not installed here any more, so this agent cannot be checked. Reinstall it (npm i -D @synovitec/trellis).";
+
+/** @param {"local" | "global"} how @param {string} event @param {string} agent */
+const shellCommand = (how, event, agent, root = "") => {
+  const run = how === "global" ? `trellis hook ${event} --agent ${agent}` : `node "${root}${SCRIPT}" hook ${event} --agent ${agent}`;
+  const present = how === "global" ? "command -v trellis >/dev/null 2>&1" : `[ -f "${root}${SCRIPT}" ]`;
+  // Before a tool call, a check that could not run (node missing: 127; a crash: 1) refuses it.
+  const guarded = event === "pre-tool" ? `${run}; c=$?; if [ $c -ne 0 ] && [ $c -ne 2 ]; then echo "[trellis] the check could not run (exit $c), so this call is refused." >&2; exit 2; fi; exit $c` : run;
+  return `if ${present}; then ${guarded}; else echo '[trellis] ${GONE}' >&2; exit 2; fi`;
+};
+
+/** @param {"local" | "global"} how @param {string} event @param {string} agent */
+const powershellCommand = (how, event, agent) => {
+  const run = how === "global" ? `trellis hook ${event} --agent ${agent}` : `node '${SCRIPT}' hook ${event} --agent ${agent}`;
+  const present = how === "global" ? "Get-Command trellis -ErrorAction SilentlyContinue" : `Test-Path '${SCRIPT}'`;
+  // A missing node leaves no exit code, a crash another than 0 or 2: before a tool call, both refuse.
+  const after = event === "pre-tool" ? `$c = if ($?) { $LASTEXITCODE } else { 1 }; if ($c -ne 0 -and $c -ne 2) { [Console]::Error.WriteLine("[trellis] the check could not run (exit $c), so this call is refused."); exit 2 }; exit $c` : "exit $LASTEXITCODE";
+  return `if (${present}) { ${run}; ${after} } else { [Console]::Error.WriteLine('[trellis] ${GONE}'); exit 2 }`;
+};
+
+/**
+ * The same hook as one `node -e` line, for Codex on Windows (`commandWindows`), whose shell the
+ * docs do not name: the script holds no `"`, `$`, `%` or backtick, so cmd.exe and PowerShell
+ * pass it alike. It finds the repository through git, fails closed when Trellis is missing (a
+ * JSON block on stdout: Windows PowerShell turns an exit 2 into 1), and hands the hook its stdin.
+ * @param {"local" | "global"} how @param {string} event @param {string} agent
+ */
+const nodeCommand = (how, event, agent) => {
+  const fail = `console.log(JSON.stringify({decision:'block',reason:'[trellis] ${GONE}'}));console.error('[trellis] ${GONE}');process.exit(0)`;
+  const args = `['hook','${event}','--agent','${agent}']`;
+  const js =
+    how === "global"
+      ? `const c=require('child_process');try{c.execFileSync('where',['trellis'],{stdio:'ignore'})}catch(e){${fail}}const x=c.spawnSync('trellis',${args},{stdio:'inherit',shell:true});if(x.status!==0){${fail}}process.exit(0)`
+      : `const c=require('child_process'),f=require('fs'),p=require('path');let r='';try{r=c.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8'}).trim()}catch(e){}const s=p.join(r,'${SCRIPT}');if(!r||!f.existsSync(s)){${fail}}const x=c.spawnSync(process.execPath,[s,...${args}],{stdio:'inherit'});if(x.status!==0){${fail}}process.exit(0)`;
+  return `node -e "${js}"`;
+};
+
+/** An entry is Trellis's when it runs `hook <event> --agent`, in any version's spelling. @param {any} entry */
+const isTrellis = (entry) => /trellis(\.mjs)?["']?\s+hook\s+(pre|post)-tool\s+--agent\b/.test(JSON.stringify(entry ?? {}));
+
+/**
+ * Trellis's entries for one agent, by event key.
+ * @param {string} agent
+ * @param {"local" | "global"} how
+ * @returns {Record<string, any>}
+ */
+function entriesFor(agent, how) {
+  if (agent === "cursor") {
+    // Cursor runs project hooks from the project root.
+    const run = (/** @type {string} */ event) => (how === "global" ? `trellis hook ${event} --agent cursor` : `node ${SCRIPT} hook ${event} --agent cursor`);
+    return { preToolUse: { command: run("pre-tool"), timeout: 30, failClosed: true }, postToolUse: { command: run("post-tool"), timeout: 30 } };
+  }
+  if (agent === "codex") {
+    // Codex runs a hook in the session's folder: reach the repository root through git. On
+    // Windows it runs `commandWindows` instead, which needs no POSIX shell.
+    const cmd = (/** @type {string} */ event) => `R="$(git rev-parse --show-toplevel)/"; ${shellCommand(how, event, "codex", "$R")}`;
+    const hook = (/** @type {string} */ event) => ({ type: "command", command: cmd(event), commandWindows: nodeCommand(how, event, "codex"), timeout: 30 });
+    return { PreToolUse: { hooks: [hook("pre-tool")] }, PostToolUse: { hooks: [hook("post-tool")] } };
+  }
+  // Copilot: PascalCase events get the Claude-shaped payload; one command per shell.
+  const entry = (/** @type {string} */ event) => ({ type: "command", bash: shellCommand(how, event, "copilot"), powershell: powershellCommand(how, event, "copilot"), timeoutSec: 30 });
+  return { PreToolUse: entry("pre-tool"), PostToolUse: entry("post-tool") };
+}
+
+/**
+ * The hook files to write for `agents`: Trellis's entries added or brought up to date, the rest of
+ * each file kept as the team wrote it. An invalid file is left alone, with a note.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {string[]} agents
+ * @returns {{ writes: Array<{ path: string, text: string, why: string }>, notes: string[] }}
+ */
+export function planAdapterHooks(ctx, agents) {
+  const how = installKind(ctx) === "global" ? "global" : "local";
+  const writes = [];
+  const notes = [];
+  for (const agent of agents) {
+    const path = ADAPTER_FILES[/** @type {keyof typeof ADAPTER_FILES} */ (agent)];
+    if (!path) continue;
+    const raw = ctx.read(path);
+    const existing = raw == null ? {} : parseJson(raw);
+    if (existing == null || typeof existing !== "object" || Array.isArray(existing)) {
+      notes.push(`${path} is not valid JSON: left as it is, and no ${agent} hook written. Fix it and run init again.`);
+      continue;
+    }
+    const next = structuredClone(existing);
+    if (agent !== "codex") next.version ??= 1;
+    next.hooks ??= {};
+    for (const [event, entry] of Object.entries(entriesFor(agent, how))) {
+      const list = Array.isArray(next.hooks[event]) ? next.hooks[event].filter((e) => !isTrellis(e)) : [];
+      next.hooks[event] = [...list, entry];
+    }
+    // Compared as content: a file that already says this is left as it is, formatting included.
+    if (raw != null && JSON.stringify(next) === JSON.stringify(existing)) continue;
+    writes.push({ path, text: `${JSON.stringify(next, null, 2)}\n`, why: `${agent}: Trellis's guard and evidence on every tool call` });
+  }
+  return { writes, notes };
+}
+
+/**
+ * The gateway's entry for a shared, committed config: found through npm from wherever the agent
+ * launches it (npm walks up to the project's node_modules), and never downloaded: `--no-install`
+ * fails rather than fetch something else, and the name is always the scoped one.
+ * @param {import("../core/context.mjs").Context} ctx
+ */
+const gatewayCommand = (ctx) => (installKind(ctx) === "global" ? { command: "trellis", args: ["mcp"] } : { command: "npx", args: ["--no-install", "@synovitec/trellis", "mcp"] });
+
+/** Whether a server entry already runs Trellis's gateway. @param {any} s */
+const runsGateway = (s) => /trellis(\.mjs)?["']?,?\s*"?mcp\b/.test(JSON.stringify([s?.command, ...(s?.args ?? [])]));
+
+/**
+ * The gateway declared in each agent's own MCP config: Cursor's .cursor/mcp.json, Codex's
+ * .codex/config.toml (read in trusted projects), and VS Code's .vscode/mcp.json for Copilot (still
+ * read, though VS Code's guided setup labels it deprecated). Merged into what is there.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {string[]} agents
+ * @returns {{ writes: Array<{ path: string, text: string, why: string }>, notes: string[] }}
+ */
+export function planAgentMcp(ctx, agents) {
+  const { command, args } = gatewayCommand(ctx);
+  const writes = [];
+  const notes = [];
+  const why = "the Trellis gateway: the repository's checks as tools, recorded as evidence";
+  for (const [agent, path, key] of /** @type {const} */ ([["cursor", ".cursor/mcp.json", "mcpServers"], ["copilot", ".vscode/mcp.json", "servers"]])) {
+    if (!agents.includes(agent)) continue;
+    const raw = ctx.read(path);
+    const doc = raw == null ? {} : parseJson(raw);
+    if (doc == null || typeof doc !== "object" || Array.isArray(doc)) {
+      notes.push(`${path} is not valid JSON: left as it is, and the gateway not declared for ${agent}.`);
+      continue;
+    }
+    const servers = doc[key] && typeof doc[key] === "object" ? doc[key] : {};
+    if (Object.values(servers).some(runsGateway)) continue;
+    doc[key] = { ...servers, [servers.trellis ? "trellis-gateway" : "trellis"]: { type: "stdio", command, args } };
+    writes.push({ path, text: `${JSON.stringify(doc, null, 2)}\n`, why });
+  }
+  if (agents.includes("codex")) {
+    const path = ".codex/config.toml";
+    const raw = ctx.read(path) ?? "";
+    // Appended as its own table: the rest of the file is the team's, and is not rewritten.
+    // Declared already: our table, or any server whose args run the gateway (scoped name or script).
+    const declared = /^\s*\[mcp_servers\.trellis\]\s*$/m.test(raw) || /"@synovitec\/trellis",\s*"mcp"|trellis\.mjs",\s*"mcp"/.test(raw);
+    if (!declared) {
+      const sep = raw === "" || raw.endsWith("\n") ? "" : "\n";
+      const table = `[mcp_servers.trellis]\ncommand = ${JSON.stringify(command)}\nargs = [${args.map((a) => JSON.stringify(a)).join(", ")}]\n`;
+      writes.push({ path, text: `${raw}${sep}${raw ? "\n" : ""}${table}`, why });
+    }
+  }
+  return { writes, notes };
+}

package/src/agents/install.mjs

@@ -0,0 +1,302 @@
+// Putting the agent hooks in place, upgrading them, and taking them out: four entries and a few
+// deny rules in .claude/settings.json, and, when there is none, a pre-commit hook running the
+// secret scan. Only Trellis's own entries are ever rewritten; a settings file that cannot be
+// parsed is refused, not replaced.
+//
+// The hooks call the installed script with node, or a global `trellis` in a repository with no
+// node_modules, never through npx: `npx trellis` resolves to an unrelated package on the registry
+// when this one is not installed, and a hook must not download anything.
+import { commandsIn, flagValue } from "./shell.mjs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { git, hooksDir } from "./git.mjs";
+import { parseJson } from "../core/context.mjs";
+
+/** @typedef {import("../core/context.mjs").Context} Context */
+
+export const SETTINGS = ".claude/settings.json";
+export const SCRIPT = "node_modules/@synovitec/trellis/bin/trellis.mjs";
+export const PRE_COMMIT_MARK = "Written by `trellis init --agents`";
+
+/** @type {Record<string, { event: string, matcher?: string, timeout: number }>} */
+export const HOOKS = Object.freeze({
+  SessionStart: { event: "session-start", timeout: 60 },
+  PreToolUse: { event: "pre-tool", matcher: "Edit|Write|MultiEdit|NotebookEdit|Bash|PowerShell|mcp__.*", timeout: 30 },
+  PostToolUse: { event: "post-tool", matcher: "Bash|PowerShell|Grep|Glob|mcp__.*", timeout: 30 },
+  // Stop runs git, gitleaks (40 s at most) and AgentShield (60 s at most); its own budget is
+  // larger than both together, so a slow scan is reported, not cut off into a silent pass.
+  Stop: { event: "stop", timeout: 180 },
+});
+
+/**
+ * The evidence the agent must not write, and the key it must not read. Deny rules make tampering
+ * a deliberate act through the shell, which the PreToolUse guard then refuses too.
+ */
+export const DENY = Object.freeze([
+  "Edit(./.git/trellis/**)",
+  "Edit(./.git/info/exclude)",
+  "Read(~/.trellis/**)",
+  "Edit(~/.trellis/**)",
+  "Edit(~/.claude/projects/**/*.jsonl)",
+  "Edit(./node_modules/@synovitec/trellis/**)",
+  "Edit(./.git/logs/**)",
+]);
+
+const GONE = "echo '[trellis] Trellis is not installed here any more, so this session cannot be checked. Ask the person to reinstall it (npm i -D @synovitec/trellis).' >&2; exit 2";
+
+/**
+ * The command a hook runs: the project's installed script, from the project root whatever the
+ * session's working folder; or a global install for a repository without node_modules. When
+ * Trellis is gone (`git clean -fdx`, `npm ci --omit=dev`), the command exits 2, which Claude
+ * Code treats as blocking: node's own "module not found" exits 1, which it ignores, and the
+ * session would end unchecked.
+ * @param {string} event
+ * @param {"local" | "global"} [how]
+ */
+export const hookCommand = (event, how = "local") => {
+  const run = how === "global" ? `trellis hook ${event}` : `node "$CLAUDE_PROJECT_DIR/${SCRIPT}" hook ${event}`;
+  // Before a tool call, a check that could not run (node missing: 127; a crash: 1) refuses the
+  // call rather than let it through. Only there: a 2 from Stop would keep the session open.
+  const guarded = event === "pre-tool" ? `${run}; c=$?; if [ $c -ne 0 ] && [ $c -ne 2 ]; then echo "[trellis] the check could not run (exit $c), so this call is refused." >&2; exit 2; fi; exit $c` : run;
+  return how === "global"
+    ? `if command -v trellis >/dev/null 2>&1; then ${guarded}; else ${GONE}; fi`
+    : `if [ -f "$CLAUDE_PROJECT_DIR/${SCRIPT}" ]; then ${guarded}; else ${GONE}; fi`;
+};
+
+/** How this repository reaches Trellis. @param {Context} ctx @returns {"local" | "global" | null} */
+export function installKind(ctx) {
+  if (ctx.exists(SCRIPT)) return "local";
+  if (ctx.which("trellis")) return "global";
+  return null;
+}
+
+/** A settings hook entry that is Trellis's, for one event, in any version's spelling. @param {any} h @param {string} event */
+const isTrellisHook = (h, event) => new RegExp(`trellis(\\.mjs)?"?\\s+hook\\s+${event}\\b`).test(`${h?.command ?? ""} ${(h?.args ?? []).join(" ")}`);
+
+/**
+ * The state of each hook: current, outdated (an older Trellis spelling, matcher or timeout),
+ * broken (current, but what it runs is not installed, so it fails on every event), or missing.
+ * @param {Context} ctx
+ */
+export function hookState(ctx) {
+  const settings = parseJson(ctx.read(SETTINGS)) ?? {};
+  /** @type {{ present: string[], outdated: string[], broken: string[], missing: string[] }} */
+  const out = { present: [], outdated: [], broken: [], missing: [] };
+  const kind = installKind(ctx);
+  for (const [name, spec] of Object.entries(HOOKS)) {
+    const groups = settings?.hooks?.[name] ?? [];
+    const ours = groups.flatMap((/** @type {any} */ g) => (g?.hooks ?? []).filter((/** @type {any} */ h) => isTrellisHook(h, spec.event)).map((/** @type {any} */ h) => ({ g, h })));
+    const current = ours.find(({ g, h }) => [hookCommand(spec.event, "local"), hookCommand(spec.event, "global")].includes(h.command) && (g.matcher ?? undefined) === spec.matcher && h.timeout === spec.timeout);
+    if (!ours.length) out.missing.push(name);
+    else if (!current) out.outdated.push(name);
+    else if (current.h.command === hookCommand(spec.event, "local") ? kind !== "local" : !kind) out.broken.push(name);
+    else out.present.push(name);
+  }
+  return out;
+}
+
+/** Deny rules Trellis wants that the settings do not have. @param {any} settings */
+const missingDenies = (settings) => DENY.filter((d) => !(settings?.permissions?.deny ?? []).includes(d));
+
+/**
+ * @param {any} settings
+ * @param {(name: string) => boolean} keep  whether Trellis's entry for a hook stays
+ */
+function withoutTrellis(settings, keep) {
+  for (const [name, spec] of Object.entries(HOOKS)) {
+    if (keep(name) || !Array.isArray(settings?.hooks?.[name])) continue;
+    settings.hooks[name] = settings.hooks[name]
+      .map((/** @type {any} */ g) => ({ ...g, hooks: (g?.hooks ?? []).filter((/** @type {any} */ h) => !isTrellisHook(h, spec.event)) }))
+      .filter((/** @type {any} */ g) => g.hooks.length);
+    if (!settings.hooks[name].length) delete settings.hooks[name];
+  }
+  if (settings.hooks && !Object.keys(settings.hooks).length) delete settings.hooks;
+}
+
+/** Keep the file's own indentation, so the diff is the hooks and nothing else. @param {string | null} raw @param {any} value */
+const serialise = (raw, value) => `${JSON.stringify(value, null, raw && /\n\t/.test(raw) ? "\t" : 2)}\n`;
+
+/**
+ * The settings with Trellis's hooks and deny rules current: missing ones added, outdated replaced.
+ * @param {Context} ctx
+ * @returns {{ text: string | null, added: string[], upgraded: string[], denies: string[] }}
+ */
+export function planSettings(ctx) {
+  const raw = ctx.read(SETTINGS);
+  const settings = raw == null ? {} : parseJson(raw);
+  if (settings == null) throw new Error(`${SETTINGS} is not valid JSON; fix it before trellis adds its hooks`);
+  const state = hookState(ctx);
+  const todo = [...state.missing, ...state.outdated];
+  const denies = missingDenies(settings);
+  if (!todo.length && !denies.length) return { text: null, added: [], upgraded: [], denies: [] };
+  const how = installKind(ctx) === "global" ? "global" : "local";
+  withoutTrellis(settings, (name) => !state.outdated.includes(name));
+  settings.hooks ??= {};
+  for (const name of todo) {
+    const spec = HOOKS[name];
+    (settings.hooks[name] ??= []).push({ ...(spec.matcher ? { matcher: spec.matcher } : {}), hooks: [{ type: "command", command: hookCommand(spec.event, how), timeout: spec.timeout }] });
+  }
+  if (denies.length) {
+    settings.permissions ??= {};
+    settings.permissions.deny = [...(settings.permissions.deny ?? []), ...denies];
+  }
+  return { text: serialise(raw, settings), added: state.missing, upgraded: state.outdated, denies };
+}
+
+/** The pre-commit path git actually runs, relative to the root when inside it. @param {Context} ctx */
+export function preCommitPath(ctx) {
+  const dir = hooksDir(ctx.root);
+  return dir && !hooksOutside(ctx, dir) ? `${dir}/pre-commit` : null;
+}
+
+/**
+ * Whether git's hooks folder lies outside both the work tree and the git folder: a machine-wide
+ * `core.hooksPath` that every repository on the machine runs. A hook written there would run a
+ * path that only exists here, and fail every commit elsewhere.
+ * @param {Context} ctx
+ * @param {string} dir  as `git rev-parse --git-path hooks` gives it
+ */
+function hooksOutside(ctx, dir) {
+  const abs = resolve(ctx.root, dir);
+  const common = git(ctx.root, ["rev-parse", "--path-format=absolute", "--git-common-dir"])?.trim();
+  return ![ctx.root, common].filter(Boolean).some((base) => {
+    const rel = relative(resolve(/** @type {string} */ (base)), abs);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+  });
+}
+
+/** Whether a hook script runs the secret scan, read as commands (a comment does not count). @param {string} text */
+export function runsSecretScan(text) {
+  return commandsIn(text).some((c) => {
+    if (c.prog === "gitleaks") return ["git", "dir", "detect", "protect", "stdin"].includes(c.args[0] ?? "");
+    if (c.prog === "trellis" && c.args[0] === "verify") return true;
+    if (c.prog !== "trellis" || c.args[0] !== "scan") return false;
+    const only = flagValue(c.args, "--only");
+    return only == null || only.split(",").includes("gitleaks");
+  });
+}
+
+/** How a git hook reaches Trellis, and what it says when Trellis is missing. @param {"local" | "global"} how */
+const hookPrelude = (how) =>
+  how === "global"
+    ? `if ! command -v trellis >/dev/null 2>&1; then\n  echo "trellis is not installed. Install it, or remove this hook." >&2\n  exit 1\nfi`
+    : `if [ ! -f ${SCRIPT} ]; then\n  echo "trellis: ${SCRIPT} is missing. Run npm install, or remove this hook with npx @synovitec/trellis uninstall." >&2\n  exit 1\nfi`;
+/** @param {"local" | "global"} how @param {string} command */
+const trellisRun = (how, command) => (how === "global" ? `trellis ${command}` : `node ${SCRIPT} ${command}`);
+
+/**
+ * The pre-commit hook Trellis writes: the commit checkpoint, `trellis verify`, which also runs the
+ * secret scan. The script is named literally so the hook reads as what it runs.
+ * @param {"local" | "global"} how
+ */
+export function preCommitText(how) {
+  return `#!/bin/sh\n# ${PRE_COMMIT_MARK}: the commit checkpoint on every commit, whoever writes it.\n# Remove with \`npx @synovitec/trellis uninstall\`.\n${hookPrelude(how)}\nexec ${trellisRun(how, "verify")}\n`;
+}
+
+/**
+ * A hook that runs one Trellis command, with what it is for. post-rewrite passes its stdin (the
+ * old and new commit ids) through, since `exec` keeps it.
+ * @param {string} why @param {string} command @param {"local" | "global"} how
+ */
+const hookText = (why, command, how) => `#!/bin/sh\n# ${PRE_COMMIT_MARK}: ${why}.\n# Remove with \`npx @synovitec/trellis uninstall\`.\n${hookPrelude(how)}\nexec ${trellisRun(how, command)}\n`;
+
+/**
+ * The post-commit hook: attests the commit, and the next change starts a new evidence window. It
+ * cannot fail the commit (git ignores a post-commit's exit), so a missing Trellis only says so.
+ * @param {"local" | "global"} how
+ */
+export const postCommitText = (how) => hookText("start the next change's evidence window", "checkpoint", how);
+
+/**
+ * The pre-push hook: pushes the attestations (refs/notes/trellis) to the same remote, since git
+ * does not push notes by default. When a colleague pushed theirs first, it merges them in line by
+ * line (each line is one signed envelope, so nobody's is lost) and pushes again. Its own pushes
+ * skip hooks (no loop); a failure says so and lets the push go on: CI reports a commit whose
+ * attestation did not arrive.
+ */
+export function prePushText() {
+  return `#!/bin/sh
+# ${PRE_COMMIT_MARK}: the commits' attestations travel with the push.
+# Remove with \`npx @synovitec/trellis uninstall\`.
+if git rev-parse -q --verify refs/notes/trellis >/dev/null; then
+  if ! git push --no-verify --quiet "$1" refs/notes/trellis 2>/dev/null; then
+    { git fetch --quiet "$1" "+refs/notes/trellis:refs/notes/trellis-incoming" &&
+      git notes --ref trellis merge --quiet -s cat_sort_uniq refs/notes/trellis-incoming &&
+      git push --no-verify --quiet "$1" refs/notes/trellis; } 2>/dev/null ||
+      echo "trellis: the attestations (refs/notes/trellis) could not be pushed to $1; CI will report those commits." >&2
+  fi
+fi
+exit 0
+`;
+}
+
+/**
+ * Every git hook of the commit checkpoint. A merge runs pre-merge-commit and post-merge, never
+ * pre-commit or post-commit; a rebase runs post-commit per commit and then post-rewrite.
+ * @type {Array<{ name: string, command: string, run?: string, why: string, text: (how: "local" | "global") => string }>}
+ */
+const GIT_HOOKS = [
+  { name: "pre-commit", command: "verify", why: "the commit checkpoint on every commit", text: preCommitText },
+  { name: "pre-merge-commit", command: "verify", why: "the commit checkpoint on every merge commit", text: (how) => hookText("the commit checkpoint on every merge commit, whoever writes it", "verify", how) },
+  { name: "post-commit", command: "checkpoint", why: "attests the commit and starts the next change's evidence window", text: postCommitText },
+  { name: "post-merge", command: "checkpoint", run: "checkpoint --merge", why: "attests a merge commit (never a fast-forward)", text: (how) => hookText("attest the merge commit just made", "checkpoint --merge", how) },
+  { name: "post-rewrite", command: "checkpoint", run: 'checkpoint --rewritten "$1"', why: "a rebased or amended commit keeps its attestation when its change is the same", text: (how) => hookText("carry attestations to rebased and amended commits", 'checkpoint --rewritten "$1"', how) },
+  { name: "pre-push", command: "push", why: "sends the commits' attestations with the push", text: prePushText },
+];
+
+/**
+ * The git hooks of the commit checkpoint: pre-commit runs `trellis verify`, post-commit
+ * `trellis checkpoint`. A hook Trellis wrote is brought up to date; a team's own hook is left to
+ * the team, and the note says the line to add to it.
+ * @param {Context} ctx
+ * @returns {{ writes: Array<{ path: string, text: string, why: string }>, notes: string[] }}
+ */
+export function planGitHooks(ctx) {
+  const pre = preCommitPath(ctx);
+  if (!pre) {
+    const dir = hooksDir(ctx.root);
+    if (dir) return { writes: [], notes: [`git runs hooks from ${dir}, outside this repository (core.hooksPath): no hook written there, since every repository on the machine would run it. Add \`trellis verify\` to this repository's own pre-commit and pre-merge-commit, \`trellis checkpoint\` to its post-commit, \`trellis checkpoint --merge\` to its post-merge and \`trellis checkpoint --rewritten "$1"\` to its post-rewrite.`] };
+    return { writes: [], notes: ["not a git repository: no git hook written"] };
+  }
+  const how = installKind(ctx) === "global" ? "global" : "local";
+  const writes = [];
+  const notes = [];
+  for (const { name, text: textOf, command, run, why } of GIT_HOOKS) {
+    const path = pre.replace(/pre-commit$/, name);
+    const text = textOf(how);
+    const existing = ctx.read(path);
+    if (existing === text) continue;
+    if (existing == null || existing.includes(PRE_COMMIT_MARK)) writes.push({ path, text, why });
+    else if (command === "push") {
+      if (!/refs\/notes\/trellis/.test(existing)) notes.push(`${path} is the team's own: add \`git push --no-verify --quiet "$1" refs/notes/trellis\` to it, so the attestations reach CI`);
+    } else if (!commandsIn(existing).some((c) => c.prog === "trellis" && c.args[0] === command)) notes.push(`${path} is the team's own: add \`${trellisRun(how, run ?? command)}\` to it`);
+  }
+  return { writes, notes };
+}
+
+/**
+ * Everything `trellis uninstall` changes: Trellis's hook entries and deny rules out of the
+ * settings, its pre-commit hook deleted (only when it is the one Trellis wrote).
+ * @param {Context} ctx
+ * @returns {{ writes: Array<{ path: string, text: string }>, deletes: string[] }}
+ */
+export function planUninstallHooks(ctx) {
+  const writes = [];
+  const deletes = [];
+  const raw = ctx.read(SETTINGS);
+  const settings = parseJson(raw);
+  if (settings) {
+    const before = JSON.stringify(settings);
+    withoutTrellis(settings, () => false);
+    if (Array.isArray(settings.permissions?.deny)) {
+      settings.permissions.deny = settings.permissions.deny.filter((/** @type {string} */ d) => !DENY.includes(d));
+      if (!settings.permissions.deny.length) delete settings.permissions.deny;
+      if (!Object.keys(settings.permissions).length) delete settings.permissions;
+    }
+    if (JSON.stringify(settings) !== before) writes.push({ path: SETTINGS, text: serialise(raw, settings) });
+  }
+  const pre = preCommitPath(ctx);
+  for (const path of pre ? GIT_HOOKS.map((h) => pre.replace(/pre-commit$/, h.name)) : []) {
+    if ((ctx.read(path) ?? "").includes(PRE_COMMIT_MARK)) deletes.push(path);
+  }
+  return { writes, deletes };
+}

package/src/agents/manifests.mjs

@@ -0,0 +1,127 @@
+// Dependencies a manifest gained between two versions of it, for the ecosystems a repository is
+// likely to use. A dependency written into a manifest by hand is added all the same as one added
+// by a command, so both go through the same check.
+
+/**
+ * @param {string} path
+ * @param {string | null} before
+ * @param {string | null} after
+ * @returns {string[]}
+ */
+export function addedDependencies(path, before, after) {
+  const read = readerFor(path);
+  if (!read || after == null) return [];
+  const had = new Set(read(before ?? ""));
+  return [...new Set(read(after))].filter((d) => !had.has(d));
+}
+
+/**
+ * Every dependency a manifest declares, or null when the file is not a manifest Trellis reads.
+ * @param {string} path
+ * @param {string} text
+ */
+export function dependenciesOf(path, text) {
+  const read = readerFor(path);
+  return read ? read(text) : null;
+}
+
+/** Manifest files Trellis reads, at a repository's root or a workspace's. */
+export const MANIFESTS = Object.freeze(["package.json", "requirements.txt", "requirements-dev.txt", "pyproject.toml", "Cargo.toml", "go.mod", "composer.json", "Gemfile"]);
+
+/** @param {string} path @returns {((text: string) => string[]) | null} */
+function readerFor(path) {
+  const file = path.slice(path.lastIndexOf("/") + 1);
+  if (file === "package.json" || file === "composer.json") return jsonDeps;
+  if (/^requirements.*\.txt$/.test(file)) return requirements;
+  if (file === "pyproject.toml") return pyproject;
+  if (file === "Cargo.toml") return (t) => tomlTable(t, /^\[(.*\.)?(dev-|build-)?dependencies\]$/);
+  if (file === "go.mod") return goMod;
+  if (file === "Gemfile") return (t) => [...t.matchAll(/^\s*gem\s+['"]([^'"]+)['"]/gm)].map((m) => m[1]);
+  return null;
+}
+
+/** @param {string} text */
+function jsonDeps(text) {
+  let p;
+  try {
+    p = JSON.parse(text || "{}");
+  } catch {
+    return [];
+  }
+  return ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies", "require", "require-dev"].flatMap((k) => Object.keys(p?.[k] ?? {}));
+}
+
+/** `name==1.0`, `name[extra]>=2`, comments and options skipped. @param {string} text */
+function requirements(text) {
+  return text
+    .split(/\r?\n/)
+    .map((l) => l.replace(/#.*/, "").trim())
+    .filter((l) => l && !l.startsWith("-"))
+    .map((l) => l.split(/[\s\[<>=!~;@]/)[0].toLowerCase())
+    .filter(Boolean);
+}
+
+/**
+ * The dependency arrays of a pyproject.toml, and nothing else: `[project] dependencies`, every
+ * array of `[project.optional-dependencies]` and `[dependency-groups]`, and Poetry's tables.
+ * `classifiers`, `keywords` or a linter's `select = [...]` are lists, not dependencies.
+ * @param {string} text
+ */
+function pyproject(text) {
+  const names = [];
+  let table = "";
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].replace(/#.*$/, "").trim();
+    const header = line.match(/^\[([^\]]+)\]$/);
+    if (header) {
+      table = header[1].trim();
+      continue;
+    }
+    const m = line.match(/^([\w.\-"']+)\s*=\s*\[(.*)$/);
+    if (!m) continue;
+    const key = m[1].replace(/["']/g, "");
+    const wanted = (table === "project" && key === "dependencies") || table === "project.optional-dependencies" || table === "dependency-groups";
+    if (!wanted) continue;
+    // The array may span lines: read up to its closing bracket.
+    let body = m[2];
+    while (!body.includes("]") && i + 1 < lines.length) body += `\n${lines[++i].replace(/#.*$/, "")}`;
+    for (const s of body.matchAll(/["']\s*([A-Za-z0-9][A-Za-z0-9_.\-]*)/g)) names.push(s[1].toLowerCase());
+  }
+  names.push(...tomlTable(text, /^\[tool\.poetry\.(group\.[\w-]+\.)?(dev-)?dependencies\]$/).filter((n) => n !== "python"));
+  return names;
+}
+
+/** Keys of the TOML tables whose header matches. @param {string} text @param {RegExp} header */
+function tomlTable(text, header) {
+  const names = [];
+  let inside = false;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith("[")) inside = header.test(line);
+    else if (inside) {
+      const m = line.match(/^([A-Za-z0-9_.\-]+)\s*=/);
+      if (m) names.push(m[1].toLowerCase());
+    }
+  }
+  return names;
+}
+
+/** @param {string} text */
+function goMod(text) {
+  const names = [];
+  let block = false;
+  for (const raw of text.split(/\r?\n/)) {
+    // An `// indirect` requirement came with another one; it was not added by hand.
+    if (/\/\/\s*indirect\b/.test(raw)) continue;
+    const line = raw.replace(/\/\/.*/, "").trim();
+    if (/^require\s*\($/.test(line)) block = true;
+    else if (block && line === ")") block = false;
+    else if (block && line) names.push(line.split(/\s+/)[0]);
+    else {
+      const m = line.match(/^require\s+(\S+)/);
+      if (m) names.push(m[1]);
+    }
+  }
+  return names;
+}