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

package/src/core/attestation.mjs

@@ -0,0 +1,213 @@
+// The attestation a commit carries: an in-toto Statement v1 about the commit and its tree, in a
+// DSSE envelope signed with the developer's ed25519 key, stored as a git note under
+// refs/notes/trellis. It says which rules applied, what the checkpoint concluded, and which
+// checks were seen: file paths, blob ids, tool names and the test command line in clear, what a
+// check was about and each finding's message as SHA-256, never a prompt or a file's content.
+//
+// Trust: a developer's signature proves the attestation was not altered after Trellis wrote it.
+// It cannot prove an agent running as that developer did not write it: CI re-runs the
+// deterministic checks itself, and is the authority (docs/design/0001-evidence-v2.md).
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { keyFile } from "../agents/state.mjs";
+import { VERSION } from "./config.mjs";
+
+export const STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+export const PAYLOAD_TYPE = "application/vnd.in-toto+json";
+export const PREDICATE_TYPE = "https://github.com/Synovitec/trellis/blob/main/docs/attestation/v0.1.md";
+export const NOTES_REF = "refs/notes/trellis";
+
+/** @param {string} text */
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+
+/**
+ * @param {object} p
+ * @param {string} p.commit
+ * @param {string} p.tree
+ * @param {"agent" | "person"} p.actor
+ * @param {string | null} p.agent
+ * @param {string} p.preset
+ * @param {"pass" | "fail" | "unverified"} p.verdict     unverified: the commit skipped the checkpoint
+ * @param {Array<{ rule: string, mode: string, message: string }>} p.findings
+ * @param {import("./evidence.mjs").Event[]} p.events
+ */
+export function buildStatement(p) {
+  return {
+    _type: STATEMENT_TYPE,
+    subject: [{ name: "git commit", digest: { gitCommit: p.commit, gitTree: p.tree } }],
+    predicateType: PREDICATE_TYPE,
+    predicate: {
+      verifier: { name: "trellis", version: VERSION },
+      actor: p.actor,
+      agent: p.agent,
+      preset: p.preset,
+      verdict: p.verdict,
+      findings: p.findings.map((f) => ({ rule: f.rule, mode: f.mode, messageSha256: sha256(f.message) })),
+      events: p.events.map((e) => ({
+        kind: e.kind,
+        tool: e.tool,
+        agent: e.agent,
+        at: e.at,
+        ...(e.result !== undefined ? { result: e.result } : {}),
+        ...(e.blobs ? { blobs: e.blobs } : {}),
+        ...(e.tree ? { tree: e.tree } : {}),
+        ...(e.subject ? { subjectSha256: sha256(String(e.subject)) } : {}),
+      })),
+    },
+  };
+}
+
+/** The developer's ed25519 key, beside the evidence key, created once, readable by its owner only. @param {NodeJS.ProcessEnv} env */
+function privateKey(env) {
+  const file = join(dirname(keyFile(env)), "ed25519.pem");
+  if (!existsSync(file)) {
+    mkdirSync(dirname(file), { recursive: true });
+    const { privateKey: key } = generateKeyPairSync("ed25519");
+    writeFileSync(file, key.export({ type: "pkcs8", format: "pem" }), { mode: 0o600 });
+    try {
+      chmodSync(file, 0o600);
+    } catch {
+      /* Windows keeps its own ACLs */
+    }
+  }
+  return createPrivateKey(readFileSync(file, "utf8"));
+}
+
+/** The public half, as PEM: what a developer commits under .trellis/keys/. @param {NodeJS.ProcessEnv} [env] */
+export const publicKeyPem = (env = process.env) => String(createPublicKey(privateKey(env)).export({ type: "spki", format: "pem" }));
+
+/** A key's id: the SHA-256 of its public key, as DSSE's keyid hint. @param {string} pem */
+export const keyIdOf = (pem) => sha256(createPublicKey(pem).export({ type: "spki", format: "der" }).toString("base64")).slice(0, 32);
+
+/** DSSE's pre-authentication encoding. @param {string} type @param {Buffer} body */
+const pae = (type, body) => Buffer.concat([Buffer.from(`DSSEv1 ${Buffer.byteLength(type)} ${type} ${body.length} `), body]);
+
+/**
+ * @param {object} statement
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ payloadType: string, payload: string, signatures: Array<{ keyid: string, sig: string }> }}
+ */
+export function signEnvelope(statement, env = process.env) {
+  const body = Buffer.from(JSON.stringify(statement));
+  const key = privateKey(env);
+  const sig = sign(null, pae(PAYLOAD_TYPE, body), key).toString("base64");
+  return { payloadType: PAYLOAD_TYPE, payload: body.toString("base64"), signatures: [{ keyid: keyIdOf(publicKeyPem(env)), sig }] };
+}
+
+/**
+ * Checks an envelope against the trusted public keys, by keyid.
+ * @param {any} envelope
+ * @param {Map<string, string>} keys   keyid -> PEM
+ * @returns {{ ok: true, keyid: string, statement: any } | { ok: false, reason: string }}
+ */
+export function verifyEnvelope(envelope, keys) {
+  if (envelope?.payloadType !== PAYLOAD_TYPE || typeof envelope?.payload !== "string") return { ok: false, reason: "not an in-toto envelope" };
+  const body = Buffer.from(envelope.payload, "base64");
+  for (const s of envelope.signatures ?? []) {
+    const pem = keys.get(String(s?.keyid));
+    if (!pem) continue;
+    let good = false;
+    try {
+      good = verify(null, pae(PAYLOAD_TYPE, body), createPublicKey(pem), Buffer.from(String(s.sig), "base64"));
+    } catch {
+      good = false;
+    }
+    if (!good) return { ok: false, reason: `the signature by key ${s.keyid} does not match the content` };
+    let statement;
+    try {
+      statement = JSON.parse(body.toString("utf8"));
+    } catch {
+      return { ok: false, reason: "the signed payload is not JSON" };
+    }
+    if (statement?._type !== STATEMENT_TYPE || statement?.predicateType !== PREDICATE_TYPE) return { ok: false, reason: "not a Trellis statement" };
+    return { ok: true, keyid: s.keyid, statement };
+  }
+  return { ok: false, reason: `signed by an unknown key (${(envelope.signatures ?? []).map((/** @type {any} */ s) => s.keyid).join(", ") || "none"}): add the developer's public key under .trellis/keys/` };
+}
+
+/**
+ * The public keys a repository trusts: every PEM file under .trellis/keys/, in the work tree, or
+ * as it stands at commit `rev`. CI reads them at the base: a key a pull request adds is not
+ * trusted by that same pull request.
+ * @param {string} root
+ * @param {string} [rev]
+ */
+export function trustedKeys(root, rev) {
+  /** @type {Map<string, string>} */
+  const keys = new Map();
+  const add = (/** @type {string} */ pem) => {
+    try {
+      keys.set(keyIdOf(pem), pem);
+    } catch {
+      /* not a key: ignored */
+    }
+  };
+  if (rev) {
+    const ls = spawnSync("git", ["ls-tree", "-r", "-z", "--name-only", rev, "--", ".trellis/keys"], { cwd: root, encoding: "utf8", windowsHide: true });
+    if (ls.status !== 0) throw new Error(`the trusted keys at ${rev} could not be read: ${(ls.stderr || "").trim()}`);
+    for (const path of ls.stdout.split("\0").filter(Boolean)) {
+      const show = spawnSync("git", ["show", `${rev}:${path}`], { cwd: root, encoding: "utf8", windowsHide: true });
+      if (show.status === 0) add(show.stdout);
+    }
+    return keys;
+  }
+  const dir = join(root, ".trellis", "keys");
+  if (!existsSync(dir)) return keys;
+  for (const f of readdirSync(dir)) {
+    try {
+      add(readFileSync(join(dir, f), "utf8"));
+    } catch {
+      /* unreadable: ignored */
+    }
+  }
+  return keys;
+}
+
+/**
+ * Adds an envelope to a commit's note, one envelope per line. A note is never rewritten: two
+ * developers' notes on the same commit merge line by line (`git notes merge -s cat_sort_uniq`),
+ * and each line stands or falls on its own signature.
+ * @param {string} root @param {string} commit @param {object} envelope
+ */
+export function writeNote(root, commit, envelope) {
+  const line = JSON.stringify(envelope);
+  const kept = noteText(root, commit).split(/\r?\n/).filter((l) => l.trim() && l !== line);
+  const r = spawnSync("git", ["notes", "--ref", NOTES_REF, "add", "-f", "-F", "-", commit], { cwd: root, input: `${[...kept, line].join("\n")}\n`, encoding: "utf8", windowsHide: true });
+  if (r.status !== 0) throw new Error(`git notes could not record the attestation: ${(r.stderr || "").trim()}`);
+}
+
+/** @param {string} root @param {string} commit */
+function noteText(root, commit) {
+  const r = spawnSync("git", ["notes", "--ref", NOTES_REF, "show", commit], { cwd: root, encoding: "utf8", windowsHide: true });
+  return r.status === 0 ? r.stdout : "";
+}
+
+/** Every envelope a commit's note holds; a line that is not JSON is skipped. @param {string} root @param {string} commit */
+export function readNotes(root, commit) {
+  return noteText(root, commit)
+    .split(/\r?\n/)
+    .filter((l) => l.trim())
+    .flatMap((l) => {
+      try {
+        return [JSON.parse(l)];
+      } catch {
+        return [];
+      }
+    });
+}
+
+/** The first envelope a commit carries, or null. @param {string} root @param {string} commit */
+export const readNote = (root, commit) => readNotes(root, commit)[0] ?? null;
+
+/** This developer's public key if one exists already, without creating one (for doctor). @param {NodeJS.ProcessEnv} [env] */
+export function existingPublicKeyPem(env = process.env) {
+  const file = join(dirname(keyFile(env)), "ed25519.pem");
+  if (!existsSync(file)) return null;
+  try {
+    return String(createPublicKey(createPrivateKey(readFileSync(file, "utf8"))).export({ type: "spki", format: "pem" }));
+  } catch {
+    return null;
+  }
+}

package/src/core/config.mjs

@@ -0,0 +1,135 @@
+// trellis.config.json: which tools this repository uses, and their options. A tool set to `false`
+// is a decision on record (it does not apply here), not a gap the doctor reports.
+import { TOOLS, toolById } from "../tools/registry.mjs";
+import { PRESETS } from "../verify/rules.mjs";
+import { RULES } from "../agents/rules.mjs";
+import { parseJson } from "./context.mjs";
+import { readFileSync } from "node:fs";
+
+export const CONFIG_FILE = "trellis.config.json";
+export const VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+/** Pinned to the version that wrote the file, so an old install validates against its own schema. */
+export const SCHEMA_URL = `https://unpkg.com/@synovitec/trellis@${VERSION}/schema/trellis.config.schema.json`;
+
+/** @typedef {import("./context.mjs").Context} Context */
+/** @typedef {{ $schema?: string, tools: Record<string, boolean | Record<string, any>>, agents?: import("../agents/rules.mjs").AgentConfig }} Config */
+
+/** @type {Record<string, Record<string, any>>} */
+const DEFAULT_OPTIONS = {
+  "playwright-mcp": { origin: "http://localhost:3000" },
+  "postgres-mcp": { uriEnv: "MCP_PG_URI" },
+};
+
+/** @param {Context} ctx @returns {Config | null} */
+export function loadConfig(ctx) {
+  return parseJson(ctx.read(CONFIG_FILE));
+}
+
+/** Tools init leaves off even when present: what the commit checkpoint already covers. */
+const OFF_BY_DEFAULT = new Set(["osv-scanner"]);
+
+/**
+ * A config for this repository. By default, every tool that applies to its stack (what `doctor`
+ * checks without a config). With `detected`, only the tools that apply and are present here, so
+ * `init` leaves a repository green and proposes the rest instead of enabling what it cannot run.
+ * @param {Context} ctx
+ * @param {{ detected?: boolean }} [opts]
+ * @returns {Config}
+ */
+export function defaultConfig(ctx, opts = {}) {
+  /** @type {Config["tools"]} */
+  const tools = {};
+  for (const t of TOOLS) {
+    // init does not turn on what trellis verify already does: OSV-Scanner scans the whole lockfile,
+    // while the commit checkpoint checks each added dependency against OSV. It stays one setting away.
+    const on = t.applies(ctx) && (!opts.detected || (t.check(ctx, DEFAULT_OPTIONS[t.id] ?? {}).installed !== false && !OFF_BY_DEFAULT.has(t.id)));
+    tools[t.id] = on ? (DEFAULT_OPTIONS[t.id] ?? true) : false;
+  }
+  return { $schema: SCHEMA_URL, tools };
+}
+
+/**
+ * Tools that apply here but are not present: what init proposes, with how to get each.
+ * @param {Context} ctx
+ */
+export function proposals(ctx) {
+  return TOOLS.filter((t) => t.applies(ctx) && t.check(ctx, DEFAULT_OPTIONS[t.id] ?? {}).installed === false);
+}
+
+/**
+ * The tools a config turns on, with their options. Without a config, every tool that applies.
+ * @param {Context} ctx
+ * @param {Config | null} config
+ */
+export function enabledTools(ctx, config) {
+  const cfg = config ?? defaultConfig(ctx);
+  return TOOLS.flatMap((tool) => {
+    const v = cfg.tools?.[tool.id];
+    if (!v) return [];
+    return [{ tool, opts: typeof v === "object" ? v : (DEFAULT_OPTIONS[tool.id] ?? {}) }];
+  });
+}
+
+/**
+ * Problems with a config, as sentences. An unknown tool id is an error, not ignored: a typo
+ * would otherwise switch a tool off silently.
+ * @param {any} cfg
+ * @returns {string[]}
+ */
+export function validateConfig(cfg) {
+  if (cfg == null || typeof cfg !== "object" || Array.isArray(cfg)) return [`${CONFIG_FILE} is not a JSON object`];
+  // No "tools" is no tool switched on: `{}` is a valid config, the checkpoint alone.
+  if (cfg.tools !== undefined && (cfg.tools === null || typeof cfg.tools !== "object" || Array.isArray(cfg.tools))) return [`${CONFIG_FILE}: "tools" must be an object`];
+  const errors = [];
+  for (const [id, v] of Object.entries(cfg.tools ?? {})) {
+    if (!toolById(id)) errors.push(`unknown tool "${id}" (known: ${TOOLS.map((t) => t.id).join(", ")})`);
+    else if (typeof v !== "boolean" && (v === null || typeof v !== "object" || Array.isArray(v))) errors.push(`tool "${id}" must be true, false or an options object`);
+  }
+  if (cfg.agents !== undefined) errors.push(...validateAgents(cfg.agents));
+  if (cfg.verify !== undefined) errors.push(...validateVerify(cfg.verify));
+  return errors;
+}
+
+const MODES = ["block", "warn", "off"];
+
+/**
+ * The commit checkpoint's settings: a preset, and per-rule modes. An unknown rule is an error, so
+ * a typo cannot switch a rule off silently.
+ * @param {any} verify
+ */
+function validateVerify(verify) {
+  if (verify === null || typeof verify !== "object" || Array.isArray(verify)) return [`"verify" must be an object`];
+  const errors = [];
+  if (verify.preset !== undefined && !(verify.preset in PRESETS)) errors.push(`verify.preset must be one of ${Object.keys(PRESETS).join(", ")}`);
+  const known = Object.keys(PRESETS.recommended);
+  for (const [id, mode] of Object.entries(verify.rules ?? {})) {
+    if (!known.includes(id)) errors.push(`unknown verify rule "${id}" (known: ${known.join(", ")})`);
+    else if (!MODES.includes(/** @type {string} */ (mode))) errors.push(`verify.rules.${id} must be one of ${MODES.join(", ")}`);
+  }
+  if (verify.tests !== undefined && (!Array.isArray(verify.tests) || !verify.tests.length || verify.tests.some((t) => typeof t !== "string" || !t.trim()))) errors.push("verify.tests must be a list of test commands");
+  if (verify.unattested !== undefined && !["refuse", "judge"].includes(verify.unattested)) errors.push('verify.unattested must be "refuse" or "judge"');
+  for (const key of Object.keys(verify)) if (!["preset", "rules", "tests", "unattested"].includes(key)) errors.push(`unknown verify option "${key}"`);
+  return errors;
+}
+
+/** @param {any} agents */
+function validateAgents(agents) {
+  if (agents === null || typeof agents !== "object" || Array.isArray(agents)) return [`"agents" must be an object`];
+  const errors = [];
+  if (agents.mode !== undefined && !MODES.includes(agents.mode)) errors.push(`agents.mode must be one of ${MODES.join(", ")}`);
+  for (const [id, mode] of Object.entries(agents.rules ?? {})) {
+    if (!RULES.some((r) => r.id === id)) errors.push(`unknown agent rule "${id}" (known: ${RULES.map((r) => r.id).join(", ")})`);
+    else if (!MODES.includes(/** @type {string} */ (mode))) errors.push(`agents.rules.${id} must be one of ${MODES.join(", ")}`);
+  }
+  for (const key of ["uiPaths", "uiIgnore", "agentSetupPaths", "codePaths", "codeIgnore", "schemaPaths"]) {
+    const v = agents[key];
+    if (v !== undefined && (!Array.isArray(v) || v.some((g) => typeof g !== "string"))) errors.push(`agents.${key} must be a list of globs`);
+  }
+  for (const key of ["graphAfterSearches", "maxBlocks"]) {
+    const v = agents[key];
+    if (v !== undefined && !(Number.isInteger(v) && v > 0)) errors.push(`agents.${key} must be a positive integer`);
+  }
+  const known = ["mode", "rules", "uiPaths", "uiIgnore", "agentSetupPaths", "codePaths", "codeIgnore", "schemaPaths", "graphAfterSearches", "maxBlocks"];
+  for (const key of Object.keys(agents)) if (!known.includes(key)) errors.push(`unknown agents option "${key}"`);
+  return errors;
+}

package/src/core/context.mjs

@@ -0,0 +1,280 @@
+// The repository and the machine as every check sees them. One object, so a test can point it
+// at a temporary directory and a fake PATH and get the same answers a real run would.
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, delimiter, resolve } from "node:path";
+import { MANIFESTS, dependenciesOf } from "../agents/manifests.mjs";
+import { commandsIn, selfDescribing } from "../agents/shell.mjs";
+
+/** Files above this size are not read for call sites: a call lives in a script, not a bundle. */
+const MAX_SCAN_BYTES = 256 * 1024;
+
+/**
+ * @typedef {object} Context
+ * @property {string} root            the repository root
+ * @property {string} home            the user's home directory
+ * @property {NodeJS.Platform} platform
+ * @property {(name: string) => string | null} which   absolute path of a binary on PATH, or null
+ * @property {(rel: string) => string | null} read     a repository file's text, or null
+ * @property {(rel: string) => string | null} readHome a home file's text, or null
+ * @property {NodeJS.ProcessEnv} env                  the environment the tools would run in
+ * @property {(rel: string) => boolean} exists
+ * @property {(rel: string) => boolean} existsHome
+ * @property {(rel: string) => string[]} list          entry names of a repository directory
+ * @property {() => any} pkg                           package.json, or {}
+ * @property {(runs: (c: import("../agents/shell.mjs").Command) => boolean) => string[]} callers  files that run a command `runs` accepts
+ */
+
+/**
+ * Builds a context. Every field can be overridden, which is how the tests fake a machine.
+ * @param {Partial<Context> & { root: string, env?: NodeJS.ProcessEnv }} opts
+ * @returns {Context}
+ */
+export function createContext(opts) {
+  const root = opts.root;
+  const home = opts.home ?? homedir();
+  const platform = opts.platform ?? process.platform;
+  const env = opts.env ?? process.env;
+  const readAt = (/** @type {string} */ base, /** @type {string} */ rel) => {
+    try {
+      return readFileSync(resolve(base, rel), "utf8");
+    } catch {
+      return null;
+    }
+  };
+  const read = (/** @type {string} */ rel) => readAt(root, rel);
+  const list = (/** @type {string} */ rel) => {
+    try {
+      return readdirSync(resolve(root, rel)).sort();
+    } catch {
+      return [];
+    }
+  };
+  /** @type {any} */
+  let pkgCache;
+  const pkg = () => {
+    if (pkgCache === undefined) pkgCache = parseJson(read("package.json")) ?? {};
+    return pkgCache;
+  };
+  /** @type {Map<string, import("../agents/shell.mjs").Command[]> | undefined} */
+  let sites;
+  const callers = (/** @type {(c: import("../agents/shell.mjs").Command) => boolean} */ runs) => {
+    sites ??= callSites(root, pkg(), list);
+    return [...sites].filter(([, cmds]) => cmds.some(runs)).map(([file]) => file);
+  };
+  return {
+    root,
+    home,
+    platform,
+    env,
+    which: opts.which ?? ((name) => whichOnPath(name, env, platform)),
+    read,
+    readHome: (rel) => readAt(home, rel),
+    exists: (rel) => existsSync(resolve(root, rel)),
+    existsHome: (rel) => existsSync(join(home, rel)),
+    list,
+    pkg,
+    callers,
+    ...stripUndefined(opts, ["which"]),
+  };
+}
+
+/**
+ * The commands a repository actually runs, per file: package scripts, git hooks, shell scripts,
+ * CI steps, Makefile and justfile recipes, Jenkins `sh` steps. A tool that is installed and
+ * configured but run by none of these is configuration that never runs, so "wired" is decided
+ * here, by a parsed command, never by a mention: a string in a JavaScript file, a step's name, an
+ * `echo` or a comment runs nothing.
+ * @param {string} root
+ * @param {any} pkg
+ * @param {(rel: string) => string[]} list
+ * @returns {Map<string, import("../agents/shell.mjs").Command[]>}
+ */
+function callSites(root, pkg, list) {
+  /** @type {Map<string, import("../agents/shell.mjs").Command[]>} */
+  const out = new Map();
+  const ran = (/** @type {string[]} */ lines) => lines.flatMap((l) => commandsIn(l)).filter((c) => !selfDescribing(c));
+  const scripts = pkg?.scripts ?? {};
+  for (const [name, cmd] of Object.entries(scripts)) out.set(`package.json#scripts.${name}`, ran([String(cmd)]));
+  const add = (/** @type {string} */ rel) => {
+    try {
+      const full = join(root, rel);
+      const st = statSync(full);
+      if (!st.isFile() || st.size > MAX_SCAN_BYTES) return;
+      out.set(rel, ran(commandLines(rel, readFileSync(full, "utf8"))));
+    } catch {
+      /* unreadable files call nothing */
+    }
+  };
+  for (const dir of [".githooks", ".husky"]) for (const f of list(dir)) add(`${dir}/${f}`);
+  // The default hooks folder runs too; its `.sample` files are git's examples and run nothing.
+  for (const f of list(".git/hooks")) if (!f.endsWith(".sample")) add(`.git/hooks/${f}`);
+  const ROOT_FILES = [".woodpecker.yml", ".gitlab-ci.yml", ".pre-commit-config.yaml", "lefthook.yml", "Makefile", "makefile", "justfile", "Justfile", "Taskfile.yml", "Jenkinsfile", "azure-pipelines.yml", "bitbucket-pipelines.yml", ".drone.yml"];
+  for (const f of ROOT_FILES) add(f);
+  for (const dir of [".woodpecker", ".github/workflows", ".circleci", ".buildkite"]) for (const f of list(dir)) add(`${dir}/${f}`);
+  walk(root, "scripts", 3, add);
+  // `.claude/settings.json` is left out on purpose: a permission that allows a command is not a
+  // call to it, and counting it would report a scanner nobody runs as wired.
+  return out;
+}
+
+/**
+ * The command lines in a file, by what kind of file it is. YAML: the value of each step, run
+ * line or list item (a block scalar's lines included). Makefile and justfile: the recipe lines.
+ * Jenkinsfile: the strings given to `sh`. Anything else (a hook, a shell script): the file.
+ * @param {string} rel
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function commandLines(rel, text) {
+  const name = rel.slice(rel.lastIndexOf("/") + 1);
+  const lines = text.split(/\r?\n/);
+  if (/\.ya?ml$/i.test(name)) return yamlCommands(lines);
+  if (/^(GNU)?[Mm]akefile$|\.mk$|^[Jj]ustfile$/.test(name)) return lines.filter((l) => /^(\t| {2,})\S/.test(l)).map((l) => l.trim().replace(/^[@-]+/, ""));
+  if (name === "Jenkinsfile") return [...text.matchAll(/\b(?:sh|bat|powershell)\s*\(?\s*(?:script:\s*)?(['"]{1,3})([\s\S]*?)\1/g)].map((m) => m[2]);
+  return [text];
+}
+
+/** Keys whose value is a command in the CI and hook formats Trellis reads. */
+const CMD_KEYS = new Set(["run", "script", "scripts", "before_script", "after_script", "command", "commands", "cmd", "cmds", "entry", "bash", "sh", "pwsh", "powershell"]);
+
+/**
+ * The commands of a YAML step file: the value of a command key (`run: x`), the items of a
+ * command list (`commands:` then `- x`), and the lines of a block scalar under either (`run: |`).
+ * A step's `name:` or any other key is not a command, whatever words it holds.
+ * @param {string[]} lines
+ * @returns {string[]}
+ */
+function yamlCommands(lines) {
+  const out = [];
+  /** The indentation under which lines are commands, and how: a block's lines, or a list's items. */
+  let scope = /** @type {{ indent: number, block: boolean } | null} */ (null);
+  for (const raw of lines) {
+    if (!raw.trim() || /^\s*#/.test(raw)) continue;
+    const indent = raw.length - raw.trimStart().length;
+    if (scope && indent <= scope.indent) scope = null;
+    const text = raw.trim();
+    if (scope?.block) {
+      out.push(text);
+      continue;
+    }
+    const item = text.startsWith("- ") || text === "-";
+    const body = item ? text.slice(1).trim() : text;
+    const kv = body.match(/^["']?([\w.-]+)["']?\s*:(?:\s+(.*))?$/);
+    if (kv) {
+      const value = (kv[2] ?? "").trim();
+      if (!CMD_KEYS.has(kv[1])) continue;
+      const at = item ? indent + 2 : indent;
+      if (!value) scope = { indent: at, block: false };
+      else if (/^[|>][+-]?\d*$/.test(value)) scope = { indent: at, block: true };
+      else out.push(value.replace(/^["']|["']$/g, ""));
+    } else if (scope && item) {
+      // An item of a command list: itself a command, or the start of a block scalar.
+      if (/^[|>][+-]?\d*$/.test(body)) scope = { indent, block: true };
+      else out.push(body.replace(/^["']|["']$/g, ""));
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {string} root
+ * @param {string} rel
+ * @param {number} depth
+ * @param {(rel: string) => void} add
+ */
+function walk(root, rel, depth, add) {
+  if (depth < 0) return;
+  let entries;
+  try {
+    entries = readdirSync(join(root, rel), { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const child = `${rel}/${e.name}`;
+    if (e.isDirectory() && e.name !== "node_modules") walk(root, child, depth - 1, add);
+    // Shell scripts and step files; a JavaScript file's strings are not commands it runs.
+    else if (/\.(sh|bash|ps1|cmd|bat|ya?ml)$/.test(e.name)) add(child);
+  }
+}
+
+/**
+ * @param {string} name
+ * @param {NodeJS.ProcessEnv} env
+ * @param {NodeJS.Platform} platform
+ */
+function whichOnPath(name, env, platform) {
+  const dirs = (env.PATH ?? env.Path ?? "").split(delimiter).filter(Boolean);
+  const exts = platform === "win32" ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").map((e) => e.toLowerCase())] : [""];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const full = join(dir, name + ext);
+      try {
+        if (statSync(full).isFile()) return full;
+      } catch {
+        /* not here */
+      }
+    }
+  }
+  return null;
+}
+
+/** @param {string | null} text */
+export function parseJson(text) {
+  if (text == null) return null;
+  try {
+    // A leading byte-order mark is no part of the JSON: npm and editors read past it.
+    return JSON.parse(String(text).replace(/^\uFEFF/, ""));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {Record<string, any>} obj
+ * @param {string[]} skip
+ */
+function stripUndefined(obj, skip) {
+  /** @type {Record<string, any>} */
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) if (v !== undefined && !skip.includes(k) && k !== "env") out[k] = v;
+  return out;
+}
+
+/**
+ * Every dependency the repository declares, in any ecosystem Trellis reads (npm, Python, Go, Rust,
+ * PHP, Ruby), at its root and in its workspaces: a monorepo's front end lives in `apps/web`, not
+ * in the root package.json.
+ * @param {Context} ctx
+ */
+export function dependencyNames(ctx) {
+  const names = new Set();
+  for (const dir of ["", ...workspaces(ctx)]) {
+    for (const file of MANIFESTS) {
+      const rel = dir ? `${dir}/${file}` : file;
+      const text = ctx.read(rel);
+      if (text != null) for (const d of dependenciesOf(rel, text) ?? []) names.add(d);
+    }
+  }
+  return names;
+}
+
+/**
+ * Workspace folders, from package.json `workspaces` and pnpm-workspace.yaml. Patterns of the form
+ * `dir/*` and exact folders are read; deeper globs are left out rather than guessed.
+ * @param {Context} ctx
+ */
+function workspaces(ctx) {
+  const p = ctx.pkg();
+  const patterns = [...(Array.isArray(p.workspaces) ? p.workspaces : (p.workspaces?.packages ?? []))];
+  for (const m of (ctx.read("pnpm-workspace.yaml") ?? "").matchAll(/^\s*-\s*['"]?([^'"\n#]+?)['"]?\s*$/gm)) patterns.push(m[1]);
+  const dirs = [];
+  for (const pat of patterns) {
+    const clean = String(pat).replace(/\/$/, "");
+    if (clean.startsWith("!")) continue;
+    if (clean.endsWith("/*")) for (const d of ctx.list(clean.slice(0, -2))) dirs.push(`${clean.slice(0, -2)}/${d}`);
+    else if (!clean.includes("*")) dirs.push(clean);
+  }
+  return dirs.slice(0, 200);
+}