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

package/src/commands/attest.mjs

@@ -0,0 +1,208 @@
+// Attaching a commit's attestation, from the git hooks that run after a commit is made:
+//   trellis checkpoint            post-commit: attest HEAD, start the next evidence window
+//   trellis checkpoint --merge    post-merge: attest the merge commit just made (never a fast-forward)
+//   trellis checkpoint --rewritten <amend|rebase>
+//                                 post-rewrite: a rebased or amended commit keeps its attestation
+//                                 only when its change is exactly the one attested
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { commitDiff, parentsOf } from "../core/diff.mjs";
+import { checkpoint, evidenceFile, readWindow } from "../core/evidence.mjs";
+import { buildStatement, existingPublicKeyPem, keyIdOf, readNotes, signEnvelope, trustedKeys, verifyEnvelope, writeNote } from "../core/attestation.mjs";
+import { loadConfig, validateConfig } from "../core/config.mjs";
+import { scanCommit } from "../verify/secrets.mjs";
+import { checkDependencies, dependencyChanges } from "../verify/deps.mjs";
+import { evaluate, localModes } from "../verify/rules.mjs";
+import { testCommands, testScriptChanges } from "../verify/test-commands.mjs";
+
+/**
+ * @typedef {object} JudgeOptions
+ * @property {import("../verify/deps.mjs").Http} [http]
+ * @property {(root: string, commit: string) => import("../verify/secrets.mjs").SecretScan} [scanCommit]
+ */
+
+/**
+ * Which agent is at work, if any: one the evidence names (every agent's hooks record its first
+ * call of a window), or one whose own environment marks its shell. An agent running with neither
+ * Trellis's hooks nor its gateway, and no marker, reads as a person, locally and in CI: what
+ * holds for it are the rules that apply to everyone.
+ * @param {import("../core/evidence.mjs").Event[]} events
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string | null}
+ */
+export function agentAtWork(events, env) {
+  const named = [...events].reverse().find((e) => e.agent && e.agent !== "person");
+  if (named) return named.agent;
+  if (env.TRELLIS_AGENT) return env.TRELLIS_AGENT;
+  if (env.CLAUDECODE === "1") return "claude-code";
+  return null;
+}
+
+/** Where verify leaves its verdict for the post-commit. @param {string} root @param {NodeJS.ProcessEnv} env */
+export const lastVerifyFile = (root, env) => join(dirname(evidenceFile(root, env)), "last-verify.json");
+
+/** @param {string} root @param {string[]} args */
+const git = (root, args) => spawnSync("git", args, { cwd: root, encoding: "utf8", windowsHide: true }).stdout?.trim() ?? "";
+
+/** Whether a commit already carries an attestation that is not `unverified`. @param {string} root @param {string} commit */
+const attested = (root, commit) =>
+  readNotes(root, commit).some((env) => {
+    try {
+      return JSON.parse(Buffer.from(String(env?.payload), "base64").toString("utf8"))?.predicate?.verdict !== "unverified";
+    } catch {
+      return false;
+    }
+  });
+
+/**
+ * The checkpoint run after the fact, on a commit no pre-commit saw (a conflicted rebase, a
+ * cherry-pick, a revert, a commit made with --no-verify): the same rules, on the commit's own
+ * change, with this window's evidence. CI judges it again either way.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {string} commit
+ * @param {string} tree
+ * @param {import("../core/evidence.mjs").Event[]} events
+ * @param {NodeJS.ProcessEnv} env
+ * @param {JudgeOptions} opts
+ */
+async function judgeCommit(ctx, commit, tree, events, env, opts) {
+  const agent = agentAtWork(events, env);
+  const actor = agent ? "agent" : "person";
+  const raw = ctx.read("trellis.config.json");
+  const config = loadConfig(ctx);
+  const errors = raw?.trim() && config == null ? ["trellis.config.json is not valid JSON"] : config ? validateConfig(config) : [];
+  const preset = config?.verify?.preset ?? "recommended";
+  if (errors.length) return { actor, agent, preset, findings: [{ rule: "config-invalid", mode: "block", message: errors.join("; ") }], verdict: "fail" };
+  const changes = commitDiff(ctx.root, commit);
+  const deps = dependencyChanges(ctx.root, changes);
+  const secrets = (opts.scanCommit ?? scanCommit)(ctx.root, commit);
+  const findings = evaluate({
+    changes,
+    events,
+    actor,
+    preset,
+    modes: localModes(config, secrets),
+    secrets,
+    deps: deps.length ? await checkDependencies(deps, { http: opts.http }) : { status: "clean", findings: [], unpinned: [], unchecked: [] },
+    depNames: deps.map((d) => d.name),
+    testCommands: testCommands((p) => ctx.read(p)),
+    tree,
+    testScripts: testScriptChanges(ctx.root, changes),
+  });
+  return { actor, agent, preset, findings, verdict: findings.some((f) => f.mode === "block") ? "fail" : "pass" };
+}
+
+/**
+ * The statement for `commit`: the checkpoint's verdict when it ran on exactly this tree, else
+ * the checkpoint run now, on the commit itself; `unverified` only when the evidence log no
+ * longer verifies, so nothing can be judged from it.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {string} commit
+ * @param {NodeJS.ProcessEnv} env
+ * @param {Record<string, unknown>} [extra]  added to the predicate
+ * @param {JudgeOptions} [opts]
+ */
+async function statementFor(ctx, commit, env, extra = {}, opts = {}) {
+  const tree = git(ctx.root, ["rev-parse", `${commit}^{tree}`]);
+  if (!tree) throw new Error("no commit to attest");
+  const window = readWindow(ctx.root, env);
+  /** @type {any} */
+  let last = null;
+  try {
+    const file = lastVerifyFile(ctx.root, env);
+    last = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : null;
+  } catch {
+    last = null;
+  }
+  const verified = last?.tree === tree && window.status === "ok";
+  const judged = verified ? last : window.status === "ok" ? await judgeCommit(ctx, commit, tree, window.events, env, opts) : null;
+  const agent = judged ? judged.agent : agentAtWork([], env);
+  const statement = buildStatement({
+    commit,
+    tree,
+    actor: judged ? judged.actor : agent ? "agent" : "person",
+    agent,
+    preset: judged ? judged.preset : "unknown",
+    verdict: judged ? judged.verdict : "unverified",
+    findings: judged ? judged.findings : [],
+    events: window.status === "ok" ? window.events : [],
+  });
+  Object.assign(statement.predicate, extra);
+  return { statement, verified: Boolean(judged) };
+}
+
+/** Whether a rebase is under way: its commits are attested once, by post-rewrite. @param {string} root */
+const rebasing = (root) => ["rebase-merge", "rebase-apply"].some((d) => existsSync(join(root, git(root, ["rev-parse", "--git-path", d]))));
+
+/**
+ * The hooks after a commit. post-commit attests HEAD; post-merge attests the merge commit it made
+ * (a fast-forward makes none: HEAD is someone else's commit); post-rewrite carries attestations
+ * to rebased and amended commits. A commit that already carries an attestation keeps it.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {(...lines: string[]) => void} out
+ * @param {{ env?: NodeJS.ProcessEnv, merge?: boolean, rewritten?: string, input?: string } & JudgeOptions} [opts]
+ * @returns {Promise<number>}
+ */
+export async function commitCheckpoint(ctx, out, opts = {}) {
+  const env = opts.env ?? process.env;
+  try {
+    if (opts.rewritten) return await carry(ctx, opts.input ?? "", env, opts);
+    if (rebasing(ctx.root)) return 0;
+    const head = git(ctx.root, ["rev-parse", "HEAD"]);
+    if (opts.merge) {
+      const parents = head ? parentsOf(ctx.root, head) : [];
+      if (parents.length < 2 || parents[0] !== git(ctx.root, ["rev-parse", "-q", "--verify", "ORIG_HEAD"])) return 0;
+    }
+    if (!head || !readNotes(ctx.root, head).length) writeNote(ctx.root, head, signEnvelope((await statementFor(ctx, head, env, {}, opts)).statement, env));
+  } catch (e) {
+    // The commit is made; a missing attestation is what CI will report. Say it now too.
+    out(`trellis checkpoint: the commit's attestation could not be written (${e instanceof Error ? e.message : String(e)}).`);
+  }
+  checkpoint(ctx.root, env);
+  return 0;
+}
+
+/** The change a commit makes, as content, for comparing two commits. @param {string} root @param {string} commit */
+const changeKey = (root, commit) =>
+  commitDiff(root, commit)
+    .map((c) => `${c.path}\0${c.status}\0${c.newBlob}`)
+    .sort()
+    .join("\n");
+
+/**
+ * post-rewrite: `<old> <new>` per line. A rewritten commit whose change is exactly the old one's
+ * (same files, same content) carries the old attestation, re-signed for the new commit and tree
+ * and marked `rewrittenFrom`; the evidence still holds, since it is tied to the content. Any
+ * other rewritten commit is attested as verify last saw it, or `unverified`.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {string} input
+ * @param {NodeJS.ProcessEnv} env
+ * @param {JudgeOptions} opts
+ */
+async function carry(ctx, input, env, opts) {
+  const keys = trustedKeys(ctx.root);
+  const own = existingPublicKeyPem(env);
+  if (own) keys.set(keyIdOf(own), own);
+  let usedWindow = false;
+  for (const [from, to] of input.split(/\r?\n/).map((l) => l.trim().split(/\s+/))) {
+    if (!from || !to || attested(ctx.root, to)) continue;
+    const old = readNotes(ctx.root, from)
+      .map((e) => verifyEnvelope(e, keys))
+      .find((v) => v.ok && v.statement.subject?.[0]?.digest?.gitCommit === from && v.statement.predicate?.verdict === "pass");
+    let statement;
+    if (old?.ok && changeKey(ctx.root, from) === changeKey(ctx.root, to)) {
+      statement = old.statement;
+      statement.subject = [{ name: "git commit", digest: { gitCommit: to, gitTree: git(ctx.root, ["rev-parse", `${to}^{tree}`]) } }];
+      statement.predicate.rewrittenFrom = from;
+    } else {
+      const made = await statementFor(ctx, to, env, { rewrittenFrom: from }, opts);
+      statement = made.statement;
+      usedWindow ||= made.verified;
+    }
+    writeNote(ctx.root, to, signEnvelope(statement, env));
+  }
+  // A rebase that only moved commits leaves the work in progress its evidence.
+  if (usedWindow) checkpoint(ctx.root, env);
+  return 0;
+}

package/src/commands/checkpoint-state.mjs

@@ -0,0 +1,62 @@
+// What doctor shows first: whether the commit checkpoint is in place, from the pre-commit that
+// runs it to the CI step that is its authority. Read only: nothing here creates or changes a file.
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { commandsIn } from "../agents/shell.mjs";
+import { preCommitPath } from "../agents/install.mjs";
+import { parseJson } from "../core/context.mjs";
+import { existingPublicKeyPem, trustedKeys } from "../core/attestation.mjs";
+import { fingerprint, relayable, trustedServers } from "../mcp/trust.mjs";
+
+/** @typedef {{ name: string, status: "ok" | "warn" | "fail", detail: string, fix: string | null }} CheckpointItem */
+
+/** The CI files Trellis knows how to read. @param {string} root */
+function ciFiles(root) {
+  const files = [".gitlab-ci.yml", ".woodpecker.yml", "azure-pipelines.yml", "Jenkinsfile", "bitbucket-pipelines.yml"].filter((f) => existsSync(join(root, f)));
+  for (const dir of [".github/workflows", ".woodpecker"]) {
+    try {
+      files.push(...readdirSync(join(root, dir)).filter((f) => /\.ya?ml$/.test(f)).map((f) => `${dir}/${f}`));
+    } catch {
+      /* none */
+    }
+  }
+  return files;
+}
+
+/**
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {any} config
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {CheckpointItem[]}
+ */
+export function checkpointState(ctx, config, env) {
+  /** @type {CheckpointItem[]} */
+  const items = [];
+  // The hooks are what init --agents installs: once it has run, a missing one is a failure.
+  const expected = config?.agents ? "fail" : "warn";
+  const pre = preCommitPath(ctx);
+  const runs = (/** @type {string | null} */ path, /** @type {string} */ sub) => !!path && commandsIn(ctx.read(path) ?? "").some((c) => c.prog === "trellis" && c.args[0] === sub);
+  items.push(runs(pre, "verify") ? { name: "pre-commit", status: "ok", detail: "runs trellis verify on every commit", fix: null } : { name: "pre-commit", status: expected, detail: "does not run trellis verify: commits are not checked", fix: "npx @synovitec/trellis init --agents (or add `trellis verify` to your own pre-commit)" });
+  const post = pre ? pre.replace(/pre-commit$/, "post-commit") : null;
+  items.push(runs(post, "checkpoint") ? { name: "post-commit", status: "ok", detail: "attests every commit", fix: null } : { name: "post-commit", status: expected, detail: "does not run trellis checkpoint: commits carry no attestation", fix: "npx @synovitec/trellis init --agents (or add `trellis checkpoint` to your own post-commit)" });
+  const hook = (/** @type {string} */ name) => (pre ? pre.replace(/pre-commit$/, name) : null);
+  const merges = runs(hook("pre-merge-commit"), "verify") && runs(hook("post-merge"), "checkpoint") && runs(hook("post-rewrite"), "checkpoint");
+  items.push(merges ? { name: "merges and rebases", status: "ok", detail: "merge commits are checked and attested; rebased commits keep their attestation", fix: null } : { name: "merges and rebases", status: "warn", detail: "pre-merge-commit, post-merge or post-rewrite does not run Trellis: merge commits and rebased commits reach CI unattested", fix: "npx @synovitec/trellis init --agents" });
+  const push = hook("pre-push");
+  items.push(push && /refs\/notes\/trellis/.test(ctx.read(push) ?? "") ? { name: "pre-push", status: "ok", detail: "sends the attestations with each push", fix: null } : { name: "pre-push", status: "warn", detail: "the attestations (refs/notes/trellis) are not pushed: CI will not find them", fix: "npx @synovitec/trellis init --agents" });
+  const mcp = parseJson(ctx.read(".mcp.json"))?.mcpServers ?? {};
+  const gateway = Object.values(mcp).some((s) => /trellis(\.mjs)?["']?,?\s*"?mcp\b/.test(JSON.stringify([/** @type {any} */ (s)?.command, ...(/** @type {any} */ (s)?.args ?? [])])));
+  items.push(gateway ? { name: "MCP gateway", status: "ok", detail: "declared in .mcp.json", fix: null } : { name: "MCP gateway", status: "warn", detail: "not declared: agents do not get the checks as tools", fix: "npx @synovitec/trellis init --agents" });
+  const trustedMcp = trustedServers(ctx.root, env);
+  const untrusted = relayable(ctx).servers.filter(([name, entry]) => trustedMcp[name] !== fingerprint(entry, ctx.root)).map(([name]) => name);
+  if (gateway && untrusted.length) items.push({ name: "relayed servers", status: "warn", detail: `not trusted on this clone, so the gateway does not start them: ${untrusted.join(", ")}`, fix: "npx --no-install @synovitec/trellis mcp trust (in a terminal)" });
+  const mine = existingPublicKeyPem(env);
+  const trusted = mine != null && [...trustedKeys(ctx.root).values()].some((k) => k.trim() === mine.trim());
+  items.push(trusted ? { name: "signing key", status: "ok", detail: "this developer's key is trusted under .trellis/keys/", fix: null } : { name: "signing key", status: "warn", detail: "this developer's attestations are signed by a key CI does not trust", fix: "npx @synovitec/trellis key --add, then commit .trellis/keys/" });
+  const ci = ciFiles(ctx.root).find((f) => /Synovitec\/trellis@|trellis(\.mjs)?\s+verify\s+--ci/.test(ctx.read(f) ?? ""));
+  // On GitHub, `pull_request` runs the pull request's own copy of the workflow: it can drop the step.
+  const editable = ci?.startsWith(".github/workflows/") && !/pull_request_target/.test(ctx.read(ci) ?? "");
+  if (ci && editable) items.push({ name: "CI", status: "warn", detail: `${ci} runs the check, but on pull_request a pull request runs its own copy of it and can remove the step`, fix: "run it on pull_request_target, as the README's workflow does, and require the check in the branch's ruleset" });
+  else items.push(ci ? { name: "CI", status: "ok", detail: `${ci} runs the authority check`, fix: null } : { name: "CI", status: "warn", detail: "no CI step runs trellis verify --ci: nothing checks commits where it cannot be skipped", fix: "add `- uses: Synovitec/trellis@<commit>` after a checkout with fetch-depth: 0" });
+  return items;
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,98 @@
+// `trellis doctor`: every enabled tool, installed or not, wired or not. "Installed but not wired"
+// is reported as its own state, because it is the one that looks fine and protects nothing.
+import { enabledTools, loadConfig, validateConfig, CONFIG_FILE } from "../core/config.mjs";
+import { installHint } from "../tools/registry.mjs";
+import { ROLES } from "../tools/roles.mjs";
+import { hookState } from "../agents/install.mjs";
+import { checkpointState } from "./checkpoint-state.mjs";
+
+/** @typedef {import("../core/context.mjs").Context} Context */
+/** @typedef {"ok" | "warn" | "unwired" | "missing"} Status */
+
+/**
+ * @param {Context} ctx
+ * @returns {{ configured: boolean, errors: string[], results: Array<{ id: string, name: string, role: string, status: Status, detail: string, warnings: string[], fix: string | null }>, agents: ReturnType<typeof hookState> | null }}
+ */
+export function diagnose(ctx) {
+  const config = loadConfig(ctx);
+  const raw = ctx.read(CONFIG_FILE);
+  const errors = raw != null && config == null ? [`${CONFIG_FILE} is not valid JSON`] : config ? validateConfig(config) : [];
+  const results = enabledTools(ctx, errors.length ? null : config).map(({ tool, opts }) => {
+    const c = tool.check(ctx, opts);
+    /** @type {Status} */
+    // Installed with one known step left (a graph to build): a warning carrying that step.
+    const status = c.installed === false ? "missing" : !c.wired && c.todo ? "warn" : !c.wired ? "unwired" : c.warnings.length ? "warn" : "ok";
+    const fix = status === "missing" ? installHint(tool, ctx.platform) : status === "unwired" ? `wire it: ${tool.wire}` : c.todo && !c.wired ? c.todo : null;
+    return { id: tool.id, name: tool.name, role: tool.role, status, detail: c.detail, warnings: c.warnings, fix };
+  });
+  // The agent rules are a tool like the others: configured but with no hook to run them, they
+  // are exactly the inert setup this command exists to find.
+  const agents = config?.agents && !errors.length ? hookState(ctx) : null;
+  return { configured: config != null, errors, results, agents };
+}
+
+const MARK = { ok: "✓", warn: "!", unwired: "✗", missing: "✗" };
+
+/**
+ * @param {Context} ctx
+ * @param {{ json?: boolean, strict?: boolean, all?: boolean, env?: NodeJS.ProcessEnv }} flags
+ * @param {(line: string) => void} out
+ * @returns {number} exit code: 1 when a tool is missing or unwired (or warns, with --strict)
+ */
+export function doctor(ctx, flags, out) {
+  const report = diagnose(ctx);
+  const config = report.configured && !report.errors.length ? loadConfig(ctx) : null;
+  const checkpoint = config ? checkpointState(ctx, config, flags.env ?? process.env) : [];
+  const failing = report.results.filter((r) => r.status === "missing" || r.status === "unwired" || (flags.strict && r.status === "warn"));
+  const cpFailing = checkpoint.filter((i) => i.status === "fail" || (flags.strict && i.status === "warn"));
+  const a = report.agents;
+  const hooksBad = a ? a.missing.length + a.broken.length + a.outdated.length : 0;
+  const code = !report.configured || report.errors.length || failing.length || cpFailing.length || hooksBad ? 1 : 0;
+  if (flags.json) {
+    out(JSON.stringify({ ...report, checkpoint, exitCode: code }, null, 2));
+    return code;
+  }
+  for (const e of report.errors) out(`✗ ${e}`);
+  if (!report.configured && !flags.all) {
+    // A first run: one diagnosis and one command, not every tool that could apply.
+    out("Trellis is not set up in this repository.", "  → npx @synovitec/trellis init --agents   (add --dry-run to see what it writes first)", "  `trellis doctor --all` lists every tool that would apply here.");
+    return code;
+  }
+  if (!report.configured) out(`(no ${CONFIG_FILE}: checking every tool that applies to this stack; \`trellis init\` writes one)`);
+  if (checkpoint.length) {
+    out("", "Checkpoint");
+    const width = Math.max(16, ...checkpoint.map((i) => i.name.length));
+    for (const i of checkpoint) {
+      out(`  ${i.status === "ok" ? "✓" : i.status === "warn" ? "!" : "✗"} ${i.name.padEnd(width)} ${i.detail}`);
+      if (i.fix) out(`      → ${i.fix}`);
+    }
+  }
+  for (const role of ROLES) {
+    const rows = report.results.filter((r) => r.role === role.id);
+    if (!rows.length) continue;
+    out("", `${role.title}`);
+    for (const r of rows) {
+      out(`  ${MARK[r.status]} ${r.name.padEnd(16)} ${r.status.padEnd(8)} ${r.detail}`);
+      for (const w of r.warnings) out(`      ! ${w}`);
+      if (r.fix) out(`      → ${r.fix}`);
+    }
+  }
+  if (report.agents) {
+    out("", "Agents");
+    for (const e of report.agents.present) out(`  ✓ ${e.padEnd(16)} hooked   the hook runs the installed trellis`);
+    for (const e of report.agents.broken) out(`  ✗ ${e.padEnd(16)} broken   the hook is set, but trellis is not installed where it looks: it fails on every event`, "      → npm i -D @synovitec/trellis (or -g for a repository without node_modules)");
+    for (const e of report.agents.outdated) out(`  ✗ ${e.padEnd(16)} outdated the hook is an older trellis command`, "      → npx @synovitec/trellis init");
+    for (const e of report.agents.missing) out(`  ✗ ${e.padEnd(16)} unwired  the agent rules are configured, but no ${e} hook runs them`, "      → npx @synovitec/trellis init --agents");
+  }
+  // One count per section, so the summary says what the screen shows.
+  const n = (/** @type {Status} */ s) => report.results.filter((r) => r.status === s).length;
+  const parts = [];
+  if (checkpoint.length) parts.push(`checkpoint ${checkpoint.filter((i) => i.status === "ok").length} of ${checkpoint.length} in place`);
+  parts.push(`tools ${n("ok")} ok, ${n("warn")} with warnings, ${n("unwired")} not wired, ${n("missing")} missing`);
+  if (report.agents) {
+    const a = report.agents;
+    parts.push(`agent hooks ${a.present.length} of ${a.present.length + a.broken.length + a.outdated.length + a.missing.length} working`);
+  }
+  out("", `${parts.join("; ")}.`);
+  return code;
+}

package/src/commands/guide.mjs

@@ -0,0 +1,62 @@
+// `trellis guide [tool|role]`: which tool answers which question. Without an argument, the whole
+// routing for this repository; with one, that tool's use, rule, install line and current state.
+import { enabledTools, loadConfig } from "../core/config.mjs";
+import { installHint, toolById } from "../tools/registry.mjs";
+import { ROLES, roleById } from "../tools/roles.mjs";
+import { diagnose } from "./doctor.mjs";
+
+/** @typedef {import("../core/context.mjs").Context} Context */
+
+/**
+ * @param {Context} ctx
+ * @param {string | undefined} topic
+ * @param {(line: string) => void} out
+ * @returns {number}
+ */
+export function guide(ctx, topic, out) {
+  const enabled = enabledTools(ctx, loadConfig(ctx));
+  if (topic) {
+    const tool = toolById(topic);
+    if (tool) return guideTool(ctx, tool, out);
+    const role = roleById(topic);
+    if (!role) {
+      out(`Unknown topic "${topic}". Topics: ${ROLES.map((r) => r.id).join(", ")}, or a tool id from \`trellis tools\`.`);
+      return 2;
+    }
+    return printRoles([role], enabled, out);
+  }
+  return printRoles(ROLES, enabled, out);
+}
+
+/**
+ * @param {ReadonlyArray<{ id: string, title: string, question: string }>} roles
+ * @param {ReturnType<typeof enabledTools>} enabled
+ * @param {(line: string) => void} out
+ */
+function printRoles(roles, enabled, out) {
+  for (const role of roles) {
+    out(`${role.title}: ${role.question}`);
+    const tools = enabled.filter((e) => e.tool.role === role.id);
+    if (!tools.length) out("  (no tool enabled for this role)");
+    for (const { tool } of tools) out(`  ${tool.name.padEnd(16)} ${tool.use}`);
+    out("");
+  }
+  return 0;
+}
+
+/**
+ * @param {Context} ctx
+ * @param {import("../tools/registry.mjs").Tool} tool
+ * @param {(line: string) => void} out
+ */
+function guideTool(ctx, tool, out) {
+  const state = diagnose(ctx).results.find((r) => r.id === tool.id);
+  out(`${tool.name} (${roleById(tool.role)?.title}${tool.ai ? ", used by agents" : ""})`, "");
+  out(`Use it when: ${tool.use}`);
+  if (tool.rule) out(`Rule:        ${tool.rule}`);
+  out(`Install:     ${installHint(tool, ctx.platform)}`);
+  out(`Wired when:  ${tool.wire}`);
+  out(`Here:        ${state ? `${state.status}, ${state.detail}` : "disabled in trellis.config.json"}`);
+  for (const w of state?.warnings ?? []) out(`             ! ${w}`);
+  return 0;
+}

package/src/commands/init.mjs

@@ -0,0 +1,131 @@
+// `trellis init`: writes the config, the MCP entries and the AGENTS.md block, and adds the
+// git-ignore lines the tools need. With `--agents` (or once the config has an `agents` section)
+// it also puts the agent hooks in place. It installs no binary: it prints how, because installing
+// software on a machine is a person's decision. Run twice, it changes nothing the second time.
+import { CONFIG_FILE, defaultConfig, enabledTools, loadConfig, proposals, validateConfig } from "../core/config.mjs";
+import { installHint } from "../tools/registry.mjs";
+import { planMcp } from "../core/mcp.mjs";
+import { renderBlock, upsertBlock } from "../core/agents-block.mjs";
+import { installKind, planGitHooks, planSettings, SCRIPT, SETTINGS } from "../agents/install.mjs";
+import { detectAgents, planAdapterHooks, planAgentMcp } from "../agents/install-adapters.mjs";
+import { ADAPTED } from "../agents/adapters.mjs";
+import { trustEntries } from "../mcp/trust.mjs";
+
+/** @typedef {import("../core/context.mjs").Context} Context */
+/** @typedef {{ path: string, text: string, why: string, executable?: boolean }} Write */
+
+/** Paths a tool writes that can hold real data or are rebuilt on every run. */
+const IGNORES = /** @type {Record<string, string>} */ ({ "playwright-mcp": ".playwright-mcp/", graphify: "graphify-out/" });
+
+/**
+ * Every file init would write, with its new text. Nothing is written here.
+ * @param {Context} ctx
+ * @param {{ agents?: boolean, agentList?: string[] }} [flags]
+ * @returns {{ writes: Write[], notes: string[] }}
+ */
+export function planInit(ctx, flags = {}) {
+  const existing = loadConfig(ctx);
+  if (ctx.read(CONFIG_FILE) != null) {
+    const errors = existing == null ? [`${CONFIG_FILE} is not valid JSON`] : validateConfig(existing);
+    if (errors.length) throw new Error(errors.join("; "));
+  }
+  const config = existing ?? defaultConfig(ctx, { detected: true });
+  const turnOnAgents = flags.agents && !config.agents;
+  if (turnOnAgents) config.agents = { mode: "warn" };
+  const enabled = enabledTools(ctx, config);
+  /** @type {Write[]} */
+  const writes = [];
+  const notes = [];
+  if (!existing) {
+    for (const t of proposals(ctx)) notes.push(`${t.name} would fit this stack but is not here, so it is off. To add it: ${installHint(t, ctx.platform)}; then set "${t.id}": true in ${CONFIG_FILE}`);
+  }
+  if (!existing || turnOnAgents) {
+    writes.push({ path: CONFIG_FILE, text: `${JSON.stringify(config, null, 2)}\n`, why: turnOnAgents ? "agent rules on, in warn mode" : "which tools this repository uses" });
+  }
+
+  const kind = installKind(ctx);
+  const gateway = kind === "local" ? { type: "stdio", command: "node", args: [SCRIPT, "mcp"] } : kind === "global" ? { type: "stdio", command: "trellis", args: ["mcp"] } : null;
+  const mcp = planMcp(ctx, enabled, gateway);
+  if (mcp.text) writes.push({ path: ".mcp.json", text: mcp.text, why: `MCP servers added: ${mcp.added.join(", ")}` });
+  if (mcp.kept.length) notes.push(`kept the existing MCP entries for ${mcp.kept.join(", ")}`);
+
+  const agents = ctx.read("AGENTS.md");
+  const next = upsertBlock(agents, renderBlock(enabled));
+  if (next !== agents) writes.push({ path: "AGENTS.md", text: next, why: "the tool routing block" });
+
+  const gitignore = ctx.read(".gitignore") ?? "";
+  const missing = enabled.map((e) => IGNORES[e.tool.id]).filter((p) => p && !gitignore.split(/\r?\n/).includes(p));
+  if (missing.length) {
+    const sep = gitignore === "" || gitignore.endsWith("\n") ? "" : "\n";
+    writes.push({ path: ".gitignore", text: `${gitignore}${sep}# trellis: tool output\n${missing.join("\n")}\n`, why: `ignored: ${missing.join(", ")}` });
+  }
+
+  if (config.agents) planAgentHooks(ctx, enabled, writes, notes, flags.agentList);
+  // The servers Trellis itself adds (pinned, its own choice) are trusted as it writes them; a
+  // server already in .mcp.json is left for a person to trust.
+  const doc = mcp.text ? JSON.parse(mcp.text) : null;
+  /** @type {Array<[string, any]>} */
+  const trust = mcp.added.map((name) => /** @type {[string, any]} */ ([name, doc?.mcpServers?.[name]])).filter(([, entry]) => entry);
+  return { writes, notes, trust };
+}
+
+/**
+ * @param {Context} ctx
+ * @param {ReturnType<typeof enabledTools>} enabled
+ * @param {Write[]} writes
+ * @param {string[]} notes
+ * @param {string[] | undefined} agentList  agents other than Claude Code to hook; absent, those detected here
+ */
+function planAgentHooks(ctx, enabled, writes, notes, agentList) {
+  if (!installKind(ctx)) {
+    notes.push("trellis is neither in node_modules nor on PATH: install it (npm i -D @synovitec/trellis, or npm i -g @synovitec/trellis for a repository without node_modules) and run init again; until then the agent hooks would fail on every event, so none were written");
+    return;
+  }
+  const settings = planSettings(ctx);
+  if (settings.text) {
+    const what = [
+      settings.added.length ? `hooks added: ${settings.added.join(", ")}` : "",
+      settings.upgraded.length ? `hooks upgraded: ${settings.upgraded.join(", ")}` : "",
+      settings.denies.length ? `${settings.denies.length} deny rule(s) protecting the evidence` : "",
+    ].filter(Boolean);
+    writes.push({ path: SETTINGS, text: settings.text, why: what.join("; ") });
+  }
+  // The commit checkpoint holds with or without gitleaks: without it, commits are not scanned for
+  // secrets here (CI scans them), and the note says how to add it.
+  if (!enabled.some((e) => e.tool.id === "gitleaks")) notes.push('gitleaks is off, so commits are not scanned for secrets on this machine (CI scans them): install it from github.com/gitleaks/gitleaks, then set "gitleaks": true in trellis.config.json');
+  const git = planGitHooks(ctx);
+  for (const w of git.writes) writes.push({ ...w, executable: true });
+  notes.push(...git.notes);
+  const others = (agentList ?? detectAgents(ctx)).filter((a) => a !== "claude-code" && a !== "claude");
+  const unknown = others.filter((a) => !ADAPTED.includes(a));
+  if (unknown.length) notes.push(`no hooks for ${unknown.join(", ")}: Trellis adapts ${ADAPTED.join(", ")} (and Claude Code); the commit checkpoint still holds them`);
+  const adapted = others.filter((a) => ADAPTED.includes(a));
+  for (const plan of [planAdapterHooks(ctx, adapted), planAgentMcp(ctx, adapted)]) {
+    writes.push(...plan.writes);
+    notes.push(...plan.notes);
+  }
+}
+
+/**
+ * @param {Context} ctx
+ * @param {{ dryRun?: boolean, agents?: boolean, agentList?: string[] }} flags
+ * @param {(...lines: string[]) => void} out
+ * @param {(path: string, text: string, executable?: boolean) => void} write
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {number}
+ */
+export function init(ctx, flags, out, write, env = process.env) {
+  const { writes, notes, trust } = planInit(ctx, flags);
+  for (const n of notes) out(`· ${n}`);
+  if (!writes.length) {
+    out("Nothing to change: this repository is already framed. `npx @synovitec/trellis doctor` checks the tools themselves.");
+    return 0;
+  }
+  for (const w of writes) {
+    if (!flags.dryRun) write(w.path, w.text, w.executable);
+    out(`${flags.dryRun ? "would write" : "wrote"} ${w.path.padEnd(22)} ${w.why}`);
+  }
+  if (!flags.dryRun && trust.length) trustEntries(ctx.root, env, trust);
+  out("", flags.dryRun ? "Dry run: nothing written." : "Next: `npx @synovitec/trellis doctor` lists what is still to install or wire, with the command for each.");
+  return 0;
+}

package/src/commands/key.mjs

@@ -0,0 +1,31 @@
+// `trellis key`: this developer's public key, the one CI checks attestations against. With --add,
+// written under .trellis/keys/, to be committed: a key the repository does not hold is not trusted.
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { publicKeyPem, trustedKeys } from "../core/attestation.mjs";
+
+/**
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {{ add?: boolean }} flags
+ * @param {(...lines: string[]) => void} out
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {number}
+ */
+export function keyCommand(ctx, flags, out, env) {
+  const pem = publicKeyPem(env);
+  if (!flags.add) {
+    out(pem.trim());
+    return 0;
+  }
+  if ([...trustedKeys(ctx.root).values()].some((known) => known.trim() === pem.trim())) {
+    out("trellis key: this key is already trusted here.");
+    return 0;
+  }
+  // Named after the key itself: the same key always lands in the same file.
+  const rel = `.trellis/keys/${createHash("sha256").update(pem.trim()).digest("hex").slice(0, 16)}.pub`;
+  mkdirSync(join(ctx.root, ".trellis", "keys"), { recursive: true });
+  writeFileSync(join(ctx.root, rel), pem);
+  out(`trellis key: wrote ${rel}. Commit it: CI checks the commits' attestations against the keys under .trellis/keys/.`);
+  return 0;
+}

package/src/commands/scan.mjs

@@ -0,0 +1,51 @@
+// `trellis scan`: runs every enabled scanner and reports each one as passed, failed or not run.
+// A scanner that could not run is never counted as a pass: a skip that reads as green is how a
+// check ends up protecting nothing. It fails the scan unless --allow-missing says otherwise.
+import { spawnSync } from "node:child_process";
+import { enabledTools, loadConfig } from "../core/config.mjs";
+import { installHint } from "../tools/registry.mjs";
+
+/** @typedef {import("../core/context.mjs").Context} Context */
+/** @typedef {(cmd: string, args: string[], cwd: string) => { status: number | null, error?: Error }} Runner */
+
+/** @type {Runner} */
+export const spawnRunner = (cmd, args, cwd) => {
+  // npx is a .cmd on Windows, which spawn only finds through a shell.
+  const r = spawnSync(cmd, args, { cwd, stdio: "inherit", shell: process.platform === "win32" && cmd === "npx" });
+  return { status: r.status, error: r.error };
+};
+
+/**
+ * @param {Context} ctx
+ * @param {{ history?: boolean, allowMissing?: boolean, only?: string[] }} flags
+ * @param {(line: string) => void} out
+ * @param {Runner} [run]
+ * @returns {number}
+ */
+export function scan(ctx, flags, out, run = spawnRunner) {
+  const scanners = enabledTools(ctx, loadConfig(ctx)).filter(({ tool }) => tool.scan && (!flags.only?.length || flags.only.includes(tool.id)));
+  if (!scanners.length) {
+    out("No scanner is enabled: nothing was checked.");
+    return 1;
+  }
+  /** @type {Array<{ name: string, result: "passed" | "failed" | "not run" | "nothing to scan", why?: string }>} */
+  const results = [];
+  for (const { tool } of scanners) {
+    const { cmd, args, nothingToScan } = /** @type {NonNullable<typeof tool.scan>} */ (tool.scan)({ history: flags.history });
+    if (cmd !== "npx" && !ctx.which(cmd)) {
+      results.push({ name: tool.name, result: "not run", why: `not installed: ${installHint(tool, ctx.platform)}` });
+      continue;
+    }
+    out(`── ${tool.name}: ${cmd} ${args.join(" ")}`);
+    const r = run(cmd, args, ctx.root);
+    if (r.error || r.status == null) results.push({ name: tool.name, result: "not run", why: r.error?.message ?? "killed" });
+    else if (nothingToScan && r.status === nothingToScan.code) results.push({ name: tool.name, result: "nothing to scan", why: nothingToScan.why });
+    else results.push({ name: tool.name, result: r.status === 0 ? "passed" : "failed", why: r.status === 0 ? undefined : `exit ${r.status}` });
+  }
+  out("");
+  const mark = (/** @type {string} */ result) => (result === "passed" ? "✓" : result === "nothing to scan" ? "-" : "✗");
+  for (const r of results) out(`${mark(r.result)} ${r.name.padEnd(14)} ${r.result}${r.why ? ` (${r.why})` : ""}`);
+  const failed = results.some((r) => r.result === "failed");
+  const notRun = results.some((r) => r.result === "not run");
+  return failed || (notRun && !flags.allowMissing) ? 1 : 0;
+}