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

package/src/agents/rules.mjs

@@ -0,0 +1,330 @@
+// The session rules: what an agent must have done before it may say a task is done, and what it
+// must have looked at before it may write. Each rule is active only when the tool it asks for is
+// enabled, and each judges evidence: which files changed, by content, comes from git; what was
+// checked, and against which content, comes from the ledger the hooks write as each tool call
+// succeeds. A rule's mode is "block" (the agent is sent back, or the edit refused), "warn" (the
+// person is told) or "off".
+import { commandsIn, flagValue, gitSubcommand, selfDescribing } from "./shell.mjs";
+import { commandOf } from "./transcript.mjs";
+import { matchesAny } from "./glob.mjs";
+
+/** @typedef {import("./transcript.mjs").ToolUse} ToolUse */
+/** @typedef {import("./shell.mjs").Command} Command */
+/** @typedef {import("./state.mjs").Ledger} Ledger */
+/** @typedef {"block" | "warn" | "off"} Mode */
+/**
+ * @typedef {object} AgentConfig
+ * @property {Mode} [mode]                   the default for every rule
+ * @property {Record<string, Mode>} [rules]  per-rule overrides
+ * @property {string[]} [uiPaths]
+ * @property {string[]} [uiIgnore]
+ * @property {string[]} [agentSetupPaths]
+ * @property {string[]} [codePaths]
+ * @property {string[]} [codeIgnore]
+ * @property {string[]} [schemaPaths]
+ * @property {number} [graphAfterSearches]
+ * @property {number} [maxBlocks]            times the agent is sent back before the person decides
+ */
+/**
+ * @typedef {object} Session
+ * @property {Array<{ path: string, hash: string }>} changes
+ * @property {string[]} addedPackages
+ * @property {Set<string>} enabled          the enabled tool ids
+ * @property {Ledger} ledger
+ * @property {{ status: "none" | "clean" | "leaks" | "unavailable", detail?: string }} secrets
+ * @property {boolean} configChanged
+ * @property {{ status: "none" | "clean" | "findings" | "unavailable", detail?: string }} [setupScan]  the Stop hook's own AgentShield run
+ * @property {string[]} integrity          reasons the evidence itself cannot be trusted
+ */
+
+const GENERATED = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/coverage/**", "**/vendor/**", "**/.next/**", "**/target/**"];
+
+export const DEFAULTS = Object.freeze({
+  mode: /** @type {Mode} */ ("warn"),
+  uiPaths: ["**/*.{jsx,tsx,vue,svelte,astro,html,css,scss,sass,less}"],
+  uiIgnore: ["**/*.{test,spec,stories}.*", "**/__tests__/**", "**/tests/**", "**/test/**", "**/e2e/**", "docs/**", ...GENERATED],
+  agentSetupPaths: [".claude/**", ".mcp.json", "CLAUDE.md", "**/CLAUDE.md", "AGENTS.md", ".agents/**", "**/SKILL.md", "trellis.config.json"],
+  codePaths: ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts,py,go,rs,java,kt,kts,rb,php,cs,swift,vue,svelte,astro,dart,scala,c,cc,cpp,h,hpp,ex,exs}"],
+  codeIgnore: GENERATED,
+  schemaPaths: ["**/migrations/**", "**/migrate/**", "**/*.sql", "**/schema.prisma", "**/db/schema.rb", "**/alembic/versions/**", "**/models/**", "**/entities/**"],
+  graphAfterSearches: 6,
+  maxBlocks: 2,
+});
+
+/** Rules that may only warn at Stop: sending an agent back after the work is done cannot fix them. */
+const WARN_ONLY_AT_STOP = new Set(["graph-first", "graph-before-edit"]);
+
+// --- what a tool call is -------------------------------------------------------------------
+
+/** `mcp__<server>__<tool>` as its two parts; servers may contain underscores. @param {string} name */
+export function mcpParts(name) {
+  if (!name.startsWith("mcp__")) return null;
+  const rest = name.slice(5);
+  const cut = rest.indexOf("__");
+  return cut === -1 ? null : { server: rest.slice(0, cut), tool: rest.slice(cut + 2) };
+}
+
+/** The commands a call ran, without those that only describe a tool. @param {ToolUse | { name: string, input: any }} u */
+const ran = (u) => commandsIn(commandOf(/** @type {ToolUse} */ (u))).filter((c) => !selfDescribing(c));
+
+/** `trellis scan` that covers `tool` (no --only, or --only naming it). @param {Command} c @param {string} tool */
+const trellisScan = (c, tool) => {
+  if (c.prog !== "trellis" || c.args[0] !== "scan") return false;
+  const only = flagValue(c.args, "--only");
+  return only == null || only.split(",").includes(tool);
+};
+
+const SEARCH_PROGS = new Set(["grep", "rg", "ag", "ack", "find", "fd", "findstr", "select-string"]);
+/** A search of files. A grep reading another command's output (`npm test | grep x`) is not. @param {{ name: string, input: any }} u */
+export const isSearch = (u) =>
+  u.name === "Grep" || u.name === "Glob" || ran(u).some((c) => !c.piped && (SEARCH_PROGS.has(c.prog) || gitSubcommand(c)?.sub === "grep"));
+/** @param {{ name: string, input: any }} u */
+export const isGraphify = (u) =>
+  ran(u).some((c) => c.prog === "graphify" && ["query", "path", "explain"].includes(c.args[0])) || /graphify/i.test(mcpParts(u.name)?.server ?? "");
+/** @param {{ name: string, input: any }} u */
+export const isAgentShield = (u) => ran(u).some((c) => (c.prog === "ecc-agentshield" && c.args.includes("scan")) || trellisScan(c, "agentshield"));
+/** @param {{ name: string, input: any }} u */
+export const isSecretScan = (u) => ran(u).some((c) => (c.prog === "gitleaks" && ["git", "dir", "detect", "protect", "stdin"].includes(c.args[0])) || trellisScan(c, "gitleaks"));
+/** A commit that skipped the git hooks. @param {{ name: string, input: any }} u */
+export const isUnhookedCommit = (u) =>
+  ran(u).some((c) => {
+    const g = gitSubcommand(c);
+    return g?.sub === "commit" && g.rest.some((a) => a === "--no-verify" || /^-[a-zA-Z]*n[a-zA-Z]*$/.test(a));
+  });
+
+/** @param {Set<string>} keys @param {RegExp} name @param {{ name: string }} u */
+const onServer = (keys, name, u) => {
+  const p = mcpParts(u.name);
+  return !!p && (keys.has(p.server) || name.test(p.server));
+};
+/** @param {Set<string>} keys @param {{ name: string }} u */
+export const isBrowser = (keys, u) => onServer(keys, /playwright/i, u);
+/** @param {Set<string>} keys @param {{ name: string }} u */
+export const isContext7 = (keys, u) => onServer(keys, /context7/i, u);
+/** @param {Set<string>} keys @param {{ name: string }} u */
+export const isSchemaLookup = (keys, u) => onServer(keys, /postgres|^pg$|database|^db$/i, u);
+
+/** Whether `url` is on `origin`: same scheme, host and port; 127.0.0.1 and localhost are one. @param {string} url @param {string | null} origin */
+export function onOrigin(url, origin) {
+  const norm = (/** @type {string} */ u) => {
+    try {
+      const x = new URL(u);
+      return `${x.protocol}//${x.hostname === "127.0.0.1" ? "localhost" : x.hostname}:${x.port || (x.protocol === "https:" ? "443" : "80")}`;
+    } catch {
+      return null;
+    }
+  };
+  const got = norm(url);
+  if (!got) return false;
+  return origin ? got === norm(origin) : /^https?:\/\/localhost:/.test(got);
+}
+
+/** @param {string[]} items */
+const list = (items) => items.slice(0, 5).join(", ") + (items.length > 5 ? ` and ${items.length - 5} more` : "");
+
+/**
+ * What clears an evidence rule, said plainly: an explanation does not.
+ * @param {Required<AgentConfig>} cfg
+ * @param {string} what
+ */
+const evidenceOnly = (cfg, what) =>
+  `Only ${what} clears this; an explanation does not. If it is not possible here, say why in one line: after ${cfg.maxBlocks} attempt(s) the decision passes to the person.`;
+
+/** @param {string} pkg @param {string[]} lookups */
+function lookedUp(pkg, lookups) {
+  const name = pkg.toLowerCase();
+  const base = name.slice(name.lastIndexOf("/") + 1);
+  const esc = (/** @type {string} */ s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // A whole word: a lookup about "react" is not one about "re", nor about "react-dom".
+  const word = (/** @type {string} */ s) => new RegExp(`(^|[^a-z0-9_.-])${esc(s)}($|[^a-z0-9_-])`);
+  return lookups.some((q) => word(name).test(q) || (base.length > 2 && word(base).test(q)));
+}
+
+// --- the rules ------------------------------------------------------------------------------
+
+/**
+ * @typedef {object} Rule
+ * @property {string} id
+ * @property {string | null} needs  the tool id that must be enabled; null for always
+ * @property {string} title
+ * @property {(s: Session, cfg: Required<AgentConfig>) => string | null} check  the reason, or null
+ */
+
+/** @param {Session} s @param {string[]} globs @param {string[]} [ignore] */
+const changedUnder = (s, globs, ignore = []) => s.changes.filter((c) => matchesAny(c.path, globs) && !matchesAny(c.path, ignore));
+
+/** @type {ReadonlyArray<Rule>} */
+export const RULES = Object.freeze([
+  {
+    id: "evidence-intact",
+    needs: null,
+    title: "The session's evidence is intact",
+    check: (s) => (s.integrity.length ? `${s.integrity.join(" ")} The checks cannot be trusted this session: tell the person.` : null),
+  },
+  {
+    id: "config-unchanged",
+    needs: null,
+    title: "The Trellis rules stay as they were at the start of the session",
+    check: (s) =>
+      s.configChanged
+        ? "trellis.config.json changed during this session, perhaps by the person. Do not revert it; tell the person. This session is still judged against the rules as they were when it started."
+        : null,
+  },
+  {
+    id: "ui-verified",
+    needs: "playwright-mcp",
+    title: "A UI change is seen in the browser",
+    check: (s, cfg) => {
+      const pending = changedUnder(s, cfg.uiPaths, cfg.uiIgnore).filter((c) => s.ledger.browser[c.path] !== c.hash).map((c) => c.path);
+      return pending.length
+        ? `UI files changed since they were last seen in the browser: ${list(pending)}. Open the page with the Playwright MCP (navigate to the configured origin, then snapshot or screenshot). ${evidenceOnly(cfg, "a browser check of the current content")}`
+        : null;
+    },
+  },
+  {
+    id: "agent-setup-scanned",
+    needs: "agentshield",
+    title: "A change to the agent setup passes AgentShield",
+    // The Stop hook runs the scan itself (an exit code the agent produced proves nothing): this
+    // rule reads its result.
+    check: (s, cfg) => {
+      const pending = changedUnder(s, cfg.agentSetupPaths).filter((c) => s.ledger.setup[c.path] !== c.hash).map((c) => c.path);
+      if (!pending.length) return null;
+      const scan = s.setupScan ?? { status: "none" };
+      if (scan.status === "findings") return `The agent setup changed (${list(pending)}) and AgentShield reports ${scan.detail}. Fix them.`;
+      if (scan.status === "unavailable") return `The agent setup changed (${list(pending)}) and could not be scanned: ${scan.detail}.`;
+      return `The agent setup changed (${list(pending)}) and was not scanned.`;
+    },
+  },
+  {
+    id: "schema-before-change",
+    needs: "postgres-mcp",
+    title: "The database schema is looked at before a migration or a model changes",
+    check: (s, cfg) => {
+      const files = changedUnder(s, cfg.schemaPaths, cfg.codeIgnore).map((c) => c.path);
+      return files.length && !s.ledger.schema
+        ? `Schema files changed (${list(files)}) and the database schema was never looked at this session. Inspect the tables involved with the Postgres MCP and check the change against them.`
+        : null;
+    },
+  },
+  {
+    id: "graph-before-edit",
+    needs: "graphify",
+    title: "The code graph is asked before code changes",
+    check: (s, cfg) => {
+      const files = changedUnder(s, cfg.codePaths, cfg.codeIgnore).map((c) => c.path);
+      return files.length && !s.ledger.graph
+        ? `Code changed (${list(files)}) without a single \`graphify query\` this session. Ask the graph what depends on what you change, before you change it.`
+        : null;
+    },
+  },
+  {
+    id: "docs-looked-up",
+    needs: "context7",
+    title: "A new dependency is checked against its current docs",
+    check: (s) => {
+      const missing = s.addedPackages.filter((p) => !lookedUp(p, s.ledger.lookups));
+      return missing.length
+        ? `Dependencies added without a Context7 lookup naming them: ${list(missing)}. Look each one up (its current API, for the version you added) before relying on what you remember of it.`
+        : null;
+    },
+  },
+  {
+    id: "graph-first",
+    needs: "graphify",
+    title: "The code graph is asked before a long search",
+    check: (s, cfg) =>
+      s.ledger.searches >= cfg.graphAfterSearches && !s.ledger.graph
+        ? `${s.ledger.searches} file searches and no \`graphify query\` this session. Ask the graph first next time: it answers where something lives and what depends on it in one call.`
+        : null,
+  },
+  {
+    id: "secrets-scanned",
+    needs: "gitleaks",
+    title: "Every commit of the session is scanned for secrets",
+    check: (s) => {
+      if (s.secrets.status === "leaks") return `Gitleaks found secrets in commits made this session (${s.secrets.detail ?? "see `gitleaks git --redact`"}). Remove them from the history before anything is pushed, and treat the secret as exposed.`;
+      if (s.secrets.status === "unavailable") return `Commits were made this session and could not be scanned: ${s.secrets.detail ?? "gitleaks is not installed"}.`;
+      return null;
+    },
+  },
+]);
+
+/** The rules that can refuse an edit before it happens, by the path it writes. */
+export const GATES = Object.freeze(["schema-before-change", "graph-before-edit"]);
+
+/**
+ * @param {AgentConfig | undefined} agents
+ * @returns {Required<AgentConfig>}
+ */
+export function agentConfig(agents) {
+  return {
+    mode: agents?.mode ?? DEFAULTS.mode,
+    rules: agents?.rules ?? {},
+    uiPaths: agents?.uiPaths ?? DEFAULTS.uiPaths,
+    uiIgnore: agents?.uiIgnore ?? DEFAULTS.uiIgnore,
+    agentSetupPaths: agents?.agentSetupPaths ?? DEFAULTS.agentSetupPaths,
+    codePaths: agents?.codePaths ?? DEFAULTS.codePaths,
+    codeIgnore: agents?.codeIgnore ?? DEFAULTS.codeIgnore,
+    schemaPaths: agents?.schemaPaths ?? DEFAULTS.schemaPaths,
+    graphAfterSearches: agents?.graphAfterSearches ?? DEFAULTS.graphAfterSearches,
+    maxBlocks: agents?.maxBlocks ?? DEFAULTS.maxBlocks,
+  };
+}
+
+/**
+ * The mode a rule runs in. Evidence integrity blocks unless set otherwise: a check whose evidence
+ * was altered is no check. The config guard warns: the session is judged by the start's rules
+ * anyway, so an edit gains the agent nothing, and the person may be the one who made it.
+ * @param {Rule} rule
+ * @param {Required<AgentConfig>} cfg
+ * @param {{ atStop?: boolean }} [when]
+ * @returns {Mode}
+ */
+export function modeOf(rule, cfg, when = { atStop: true }) {
+  const fallback = rule.id === "evidence-intact" ? "block" : rule.id === "config-unchanged" ? "warn" : cfg.mode;
+  const mode = cfg.rules[rule.id] ?? fallback;
+  return when.atStop && WARN_ONLY_AT_STOP.has(rule.id) && mode === "block" ? "warn" : mode;
+}
+
+/**
+ * Every rule that is not satisfied, with its mode.
+ * @param {Session} session
+ * @param {AgentConfig | undefined} agents
+ * @returns {Array<{ id: string, mode: Mode, reason: string }>}
+ */
+export function evaluate(session, agents) {
+  const cfg = agentConfig(agents);
+  return RULES.flatMap((rule) => {
+    const mode = modeOf(rule, cfg);
+    if (mode === "off" || (rule.needs && !session.enabled.has(rule.needs))) return [];
+    const reason = rule.check(session, cfg);
+    return reason ? [{ id: rule.id, mode, reason }] : [];
+  });
+}
+
+/**
+ * Whether an edit to `path` may happen now. Returns the reason to refuse it, or null.
+ * @param {string} path  repository-relative
+ * @param {Ledger} ledger
+ * @param {Set<string>} enabled
+ * @param {AgentConfig | undefined} agents
+ * @param {{ graphReady: boolean }} env
+ * @returns {{ id: string, mode: Mode, reason: string } | null}
+ */
+export function gate(path, ledger, enabled, agents, env) {
+  const cfg = agentConfig(agents);
+  const rule = (/** @type {string} */ id) => /** @type {Rule} */ (RULES.find((r) => r.id === id));
+  const schema = rule("schema-before-change");
+  const schemaMode = modeOf(schema, cfg, { atStop: false });
+  if (schemaMode !== "off" && enabled.has("postgres-mcp") && matchesAny(path, cfg.schemaPaths) && !matchesAny(path, cfg.codeIgnore) && !ledger.schema) {
+    return { id: schema.id, mode: schemaMode, reason: `${path} is a schema file and the database schema has not been looked at this session. Inspect the tables it touches with the Postgres MCP (list_objects, get_object_details) first.` };
+  }
+  const graph = rule("graph-before-edit");
+  const graphMode = modeOf(graph, cfg, { atStop: false });
+  // A graph that cannot be queried here is not asked for: doctor reports it, the edit goes on.
+  if (graphMode !== "off" && enabled.has("graphify") && env.graphReady && matchesAny(path, cfg.codePaths) && !matchesAny(path, cfg.codeIgnore) && !ledger.graph) {
+    return { id: graph.id, mode: graphMode, reason: `Ask the code graph before changing code: \`graphify query "<what you are about to change, and what depends on it>"\`. One query this session unlocks every edit.` };
+  }
+  return null;
+}

package/src/agents/shell.mjs

@@ -0,0 +1,253 @@
+// A shell line as the commands it runs, each as a program and its arguments. The rules ask
+// "was gitleaks run", not "does the text contain gitleaks": `echo gitleaks`, a comment and
+// `gitleaks version` all contain the word and none of them scans anything.
+
+/** @typedef {{ prog: string, args: string[], piped: boolean }} Command */
+
+/**
+ * Programs that run another program: the command is what they run. `command` is not one: its
+ * common use, `command -v x`, asks whether x exists and runs nothing.
+ */
+const WRAPPERS = new Set(["exec", "env", "sudo", "time", "nohup", "npx", "bunx", "pnpx"]);
+/** A wrapper's own options that take a value. */
+const WRAPPER_VALUE_FLAGS = new Set(["-p", "--package", "-c", "--call"]);
+/** Arguments that make a tool describe itself instead of doing its work. */
+const SELF_DESCRIBING = new Set(["-h", "--help", "--version", "-V", "help", "version"]);
+
+/**
+ * @param {string} line
+ * @returns {Command[]}
+ */
+export function commandsIn(line) {
+  const text = String(line ?? "");
+  // A function or alias named like a tool shadows it: `gitleaks(){ true; }; gitleaks git` runs nothing.
+  const shadowed = new Set([...text.matchAll(/(?:^|[\s;&|{(])(?:function\s+)?([A-Za-z_][\w.-]*)\s*\(\s*\)\s*\{|\bfunction\s+([A-Za-z_][\w.-]*)|\balias\s+([\w.-]+)=/g)].map((m) => (m[1] ?? m[2] ?? m[3]).toLowerCase()));
+  /** @type {Command[]} */
+  const out = [];
+  let prev = "";
+  let prevDead = false;
+  for (const { words, piped, sep } of segments(text)) {
+    const c = normalise(words, piped);
+    const joined = sep === "&&" || sep === "||";
+    // `false && x` and `true || x` never run x, nor anything chained after it.
+    const dead = joined && (prevDead || (prev === "false" && sep === "&&") || (prev === "true" && sep === "||"));
+    prev = c?.prog ?? "";
+    prevDead = dead;
+    if (!c || dead || c.prog === "false" || c.prog === "true") continue;
+    // `bash -c "..."` and `sh -c '...'` run their string: look inside it.
+    if (["bash", "sh", "zsh", "pwsh", "powershell"].includes(c.prog)) {
+      const i = c.args.findIndex((a) => a === "-c" || a === "-Command" || a === "-command");
+      if (i !== -1 && c.args[i + 1]) {
+        out.push(...commandsIn(c.args[i + 1]));
+        continue;
+      }
+    }
+    if (!shadowed.has(c.prog)) out.push(c);
+  }
+  return out;
+}
+
+/** Whether a command only describes the tool (help, version) rather than running it. @param {Command} c */
+export const selfDescribing = (c) => c.args.some((a) => SELF_DESCRIBING.has(a)) && c.args.length <= 3;
+
+/**
+ * Words per command, split on ; && || | & and newlines, quotes respected, comments dropped, and
+ * heredoc bodies skipped: `cat <<EOF` followed by `gitleaks git` writes text, it runs nothing.
+ * @param {string} line
+ */
+function segments(line) {
+  /** @type {Array<{ words: string[], piped: boolean, sep: string }>} */
+  const out = [];
+  /** @type {string[]} */
+  let words = [];
+  let word = "";
+  let inWord = false;
+  let piped = false;
+  let sep = ";";
+  /** @type {Array<{ tag: string, strip: boolean }>} */
+  const heredocs = [];
+  const endWord = () => {
+    if (inWord) {
+      const m = word.match(/^<<(-?)(['"]?)([A-Za-z_][\w]*)\2$/);
+      if (m) heredocs.push({ tag: m[3], strip: m[1] === "-" });
+      words.push(word);
+    }
+    word = "";
+    inWord = false;
+  };
+  const endSegment = (/** @type {boolean} */ nextPiped, /** @type {string} */ op) => {
+    endWord();
+    if (words.length) out.push({ words, piped, sep });
+    words = [];
+    piped = nextPiped;
+    sep = op;
+  };
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === "\n" && heredocs.length) {
+      endSegment(false, ";");
+      // Skip every pending heredoc body, each up to its closing tag.
+      let pos = i + 1;
+      for (const h of heredocs) {
+        for (;;) {
+          const nl = line.indexOf("\n", pos);
+          const row = line.slice(pos, nl === -1 ? line.length : nl);
+          pos = nl === -1 ? line.length : nl + 1;
+          if ((h.strip ? row.replace(/^\t+/, "") : row) === h.tag || nl === -1) break;
+        }
+      }
+      heredocs.length = 0;
+      i = pos - 1;
+      continue;
+    }
+    if (ch === "<" && line[i + 1] === "<" && !inWord) {
+      // `<<EOF`, `<< 'EOF'`, `<<-EOF`: read the tag as one word.
+      const m = line.slice(i).match(/^<<(-?)\s*(['"]?)([A-Za-z_]\w*)\2/);
+      if (m) {
+        heredocs.push({ tag: m[3], strip: m[1] === "-" });
+        words.push(m[0]);
+        i += m[0].length - 1;
+        continue;
+      }
+    }
+    if (ch === "'" || ch === '"') {
+      const end = line.indexOf(ch, i + 1);
+      word += end === -1 ? line.slice(i + 1) : line.slice(i + 1, end);
+      inWord = true;
+      i = end === -1 ? line.length : end;
+    } else if (ch === "\\" && i + 1 < line.length) {
+      word += line[++i];
+      inWord = true;
+    } else if (ch === "#" && !inWord) {
+      const nl = line.indexOf("\n", i);
+      i = nl === -1 ? line.length : nl - 1;
+    } else if (ch === "|" && line[i + 1] === "|") {
+      endSegment(false, "||");
+      i++;
+    } else if (ch === "&" && (line[i - 1] === ">" || line[i + 1] === ">")) {
+      // A redirection (2>&1, &>file), not a separator.
+      word += ch;
+      inWord = true;
+    } else if (ch === "|") endSegment(true, "|");
+    else if (ch === "&" && line[i + 1] === "&") {
+      endSegment(false, "&&");
+      i++;
+    } else if (ch === ";" || ch === "\n" || ch === "&") endSegment(false, ";");
+    else if (/\s/.test(ch)) endWord();
+    else {
+      word += ch;
+      inWord = true;
+    }
+  }
+  endSegment(false, ";");
+  return out;
+}
+
+/**
+ * @param {string[]} words
+ * @param {boolean} piped
+ * @returns {Command | null}
+ */
+function normalise(words, piped) {
+  let i = 0;
+  // Leading assignments (FOO=1 cmd) set the environment of the command, they are not it.
+  while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i])) i++;
+  while (i < words.length) {
+    const p = program(words[i]);
+    if (WRAPPERS.has(p)) {
+      i++;
+      while (i < words.length && words[i].startsWith("-")) i += WRAPPER_VALUE_FLAGS.has(words[i]) ? 2 : 1;
+    } else if ((p === "pnpm" || p === "yarn") && words[i + 1] === "dlx") i += 2;
+    else if (p === "node" || p === "bun" || p === "deno") {
+      // `node path/to/tool.mjs args`: the tool is the script.
+      let j = i + 1;
+      while (j < words.length && words[j].startsWith("-")) j++;
+      if (j >= words.length) break;
+      i = j;
+      return { prog: program(words[i]), args: words.slice(i + 1), piped };
+    } else if (p === "python" || p === "python3" || p === "py") {
+      if (words[i + 1] === "-m" && words[i + 2]) return { prog: program(words[i + 2]), args: words.slice(i + 3), piped };
+      break;
+    } else break;
+  }
+  if (i >= words.length) return null;
+  return { prog: program(words[i]), args: words.slice(i + 1), piped };
+}
+
+/**
+ * A word as the program it names: no directory, no extension, no version, no scope.
+ * `./node_modules/.bin/trellis`, `@synovitec/trellis@0.3.0` and `gitleaks.exe` are trellis,
+ * trellis and gitleaks.
+ * @param {string} word
+ */
+export function program(word) {
+  let w = word.replace(/\\/g, "/");
+  w = w.replace(/^@[^/]+\//, "");
+  w = w.slice(w.lastIndexOf("/") + 1);
+  w = w.replace(/@[^@]*$/, "");
+  w = w.replace(/\.(exe|cmd|bat|ps1|mjs|cjs|js|sh)$/i, "");
+  return w.toLowerCase();
+}
+
+/** The value after a flag, or a `--flag=value`. @param {string[]} args @param {string} flag */
+export function flagValue(args, flag) {
+  const i = args.indexOf(flag);
+  if (i !== -1) return args[i + 1] ?? "";
+  const eq = args.find((a) => a.startsWith(`${flag}=`));
+  return eq ? eq.slice(flag.length + 1) : null;
+}
+
+/**
+ * The git subcommand, past git's own options (`git -C dir -c k=v commit`).
+ * @param {Command} c
+ */
+export function gitSubcommand(c) {
+  if (c.prog !== "git") return null;
+  for (let i = 0; i < c.args.length; i++) {
+    const a = c.args[i];
+    if (a === "-C" || a === "-c" || a === "--git-dir" || a === "--work-tree" || a === "--namespace") i++;
+    else if (!a.startsWith("-")) return { sub: a, rest: c.args.slice(i + 1) };
+  }
+  return null;
+}
+
+/**
+ * The packages a command adds to a project, without versions. Global installs and bare
+ * `npm install` (restoring the lockfile) add nothing.
+ * @param {Command} c
+ * @returns {string[]}
+ */
+export function packagesAdded(c) {
+  const positional = (/** @type {string[]} */ args, /** @type {string[]} */ valueFlags = []) => {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+      if (valueFlags.includes(args[i])) i++;
+      else if (!args[i].startsWith("-")) out.push(args[i]);
+    }
+    return out;
+  };
+  const [sub, ...rest] = c.args;
+  const global = rest.includes("-g") || rest.includes("--global") || rest.includes("--location=global");
+  let names = [];
+  if (c.prog === "npm" && ["i", "install", "add", "in", "isntall"].includes(sub) && !global) names = positional(rest, ["--prefix", "-w", "--workspace"]);
+  else if ((c.prog === "pnpm" || c.prog === "yarn" || c.prog === "bun") && sub === "add" && !global) names = positional(rest, ["--filter", "-F", "--cwd"]);
+  else if ((c.prog === "pip" || c.prog === "pip3") && sub === "install") names = positional(rest, ["-r", "--requirement", "-c", "--constraint", "-e", "--editable", "-t", "--target", "-i", "--index-url"]);
+  else if (c.prog === "uv" && sub === "add") names = positional(rest);
+  else if (c.prog === "uv" && sub === "pip" && rest[0] === "install") names = positional(rest.slice(1), ["-r"]);
+  else if ((c.prog === "poetry" || c.prog === "cargo") && sub === "add") names = positional(rest);
+  else if (c.prog === "go" && sub === "get") names = positional(rest);
+  const upgrade = rest.includes("-U") || rest.includes("--upgrade");
+  return names
+    // A local path, a URL or a git source is the team's own code, not a library to look up.
+    .filter((n) => !/^[.~/\\]|^[a-zA-Z]:[\\/]|:/.test(n))
+    .map(packageName)
+    // Upgrading the installer itself adds nothing to the project.
+    .filter((n) => n && !(upgrade && ["pip", "setuptools", "wheel"].includes(n)));
+}
+
+/** `zod@4` → zod, `@scope/x@1.2` → @scope/x, `requests==2.1` → requests, `mod/x@v1` → mod/x. @param {string} spec */
+export function packageName(spec) {
+  const s = spec.replace(/\[.*\]$/, "");
+  if (s.startsWith("@")) return s.replace(/^(@[^/]+\/[^@]+).*$/, "$1");
+  return s.replace(/(==|>=|<=|~=|!=|>|<|@).*$/, "");
+}