signoff-cli 0.0.0-stage → 4.0.0

package/lib/guard.js

@@ -0,0 +1,1229 @@
+"use strict";
+// SignOff auto-guard: install once, then the gates run themselves.
+//
+// `guard init` wires the five gates into git hooks and CI so that a normal
+// `git commit` / `git push` / pull request cannot get past a red gate without
+// leaving a trace. `guard hook <stage>` is what the hooks call.
+//
+// Port of gates/guard.py with one intended change: a gate is spawned as
+// `process.execPath bin/signoff.js <gate> ...` (the pure-Node dispatcher)
+// instead of `python <gate>.py`. Nothing here requires Python: the pytest
+// fallback is only considered when a python interpreter happens to exist.
+//
+// Design rules (kept from the Python reference):
+//   * stdlib only, no network;
+//   * quiet on success (one line), full gate output only when something fails;
+//   * a pass is cached per staged tree, so re-running the same commit is ~0 ms;
+//   * fail closed: a missing CLI or a red gate blocks, and the only way past is
+//     an explicit, recorded skip (SIGNOFF_SKIP=1) or `git commit --no-verify`.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const core = require("./core");
+const detector = require("./detect");
+
+const ROOT = path.join(__dirname, "..");
+const DISPATCHER = path.join(ROOT, "bin", "signoff.js");
+const HOOK_MARK = "# generated by signoff-cli";
+const LEGACY_HOOK_MARK = "# generated by dsh-signoff";
+function markedByUs(text) {
+  const t = String(text || "");
+  return t.includes(HOOK_MARK) || t.includes(LEGACY_HOOK_MARK);
+}
+const STATE = ".signoff";
+const DEFAULT_CONFIG = {
+  checkpoint: false,
+  version: 2,
+  docs: ["README.md", "docs"],
+  test_cmd: null,
+  budget: 180,
+  tasks: "tasks",
+  pre_push: true,
+  ci: true,
+  // Explicit defaults: a reader should not have to infer these from a `!== false`.
+  secrets: true,
+  cache: true,
+  docsFast: true,
+  coverage: null,
+  sign: false,
+};
+// pre-commit: run the gates and record what they saw
+// commit-msg: turn that record into a trailer on the message (never fails a commit)
+// pre-push:   the full set, since a push is the last cheap moment to stop
+const STAGES = ["pre-commit", "commit-msg", "pre-push"];
+const PREPARE_SCRIPT = "signoff init --quiet";
+
+class GuardExit extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code === undefined ? 1 : code;
+  }
+}
+
+// A bad flag value, raised before anything is written (argparse does the same).
+class ArgparseError extends Error {}
+
+// ---------------------------------------------------------------- helpers
+
+function now() {
+  return core.nowISO();
+}
+
+function sh(args, cwd, timeout) {
+  const r = spawnSync(args[0], args.slice(1), {
+    cwd: cwd === undefined || cwd === null ? process.cwd() : String(cwd),
+    encoding: "utf8",
+    timeout: timeout === undefined || timeout === null ? undefined : timeout,
+    windowsHide: true,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return {
+    code: r.status === null ? 127 : r.status,
+    out: r.stdout || "",
+    err: r.stderr || "",
+    error: r.error,
+  };
+}
+
+function readText(p) {
+  return fs.readFileSync(p, "utf8");
+}
+
+function isFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch (e) {
+    return false;
+  }
+}
+
+function isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch (e) {
+    return false;
+  }
+}
+
+function exists(p) {
+  try {
+    fs.statSync(p);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function repoRoot(cwd) {
+  const r = sh(["git", "rev-parse", "--show-toplevel"], cwd);
+  if (r.code !== 0) throw new GuardExit("signoff: not a git repository (run inside a repo)", 1);
+  // git prints forward slashes; the Python reference prints the platform form.
+  return path.resolve(r.out.trim());
+}
+
+function stateDir(root) {
+  const d = path.join(root, STATE);
+  fs.mkdirSync(d, { recursive: true });
+  return d;
+}
+
+function loadConfig(root) {
+  const p = path.join(root, STATE, "config.json");
+  const cfg = Object.assign({}, DEFAULT_CONFIG);
+  if (exists(p)) {
+    try {
+      Object.assign(cfg, JSON.parse(fs.readFileSync(p, "utf8")));
+    } catch (e) {
+      /* keep the defaults */
+    }
+  }
+  return cfg;
+}
+
+function saveConfig(root, cfg) {
+  fs.mkdirSync(path.join(root, STATE), { recursive: true });
+  fs.writeFileSync(path.join(root, STATE, "config.json"), JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+
+function packageVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
+    return String(pkg.version === undefined ? "0" : pkg.version);
+  } catch (e) {
+    return "0";
+  }
+}
+
+// ---------------------------------------------------------------- install
+
+function hookBody(stage, chain) {
+  // commit-msg receives the message file as $1; it must never block a commit, so
+  // a missing CLI warns and gets out of the way instead of exiting 1.
+  const extra = stage === "commit-msg" ? ' "$1"' : "";
+  // A chained install keeps the hook that was already there as `<stage>.local` and runs
+  // it first: its verdict is the repo owner's, so a failure stops the commit before any
+  // signoff gate spends time on it.
+  // A chained hook can be a shell script, a python file, a node script or a PowerShell
+  // script. The suffix picks the launcher: on Windows a git hook has no exec bit, so
+  // `sh file.py` would fail even though `python file.py` works. `.local` stays first so
+  // repos installed before 3.9.0 keep working.
+  const chained = chain
+    ? `CHAIN_DIR="$(git rev-parse --git-dir)/hooks"
+for LOCAL in "$CHAIN_DIR/${stage}.local" "$CHAIN_DIR/${stage}.local.sh" "$CHAIN_DIR/${stage}.local.py" "$CHAIN_DIR/${stage}.local.js" "$CHAIN_DIR/${stage}.local.ps1" "$CHAIN_DIR/${stage}.local.cmd"; do
+  [ -f "$LOCAL" ] || continue
+  if [ -x "$LOCAL" ]; then
+    "$LOCAL" "$@" || exit $?
+  else
+    case "$LOCAL" in
+      *.py) PY=$(command -v python3 || command -v python || command -v py) || { echo "[signoff] chained hook needs python: $LOCAL" >&2; exit 1; }; "$PY" "$LOCAL" "$@" || exit $? ;;
+      *.js) node "$LOCAL" "$@" || exit $? ;;
+      *.ps1) powershell -NoProfile -ExecutionPolicy Bypass -File "$LOCAL" "$@" || exit $? ;;
+      *.cmd) cmd //c "$LOCAL" "$@" || exit $? ;;
+      *) sh "$LOCAL" "$@" || exit $? ;;
+    esac
+  fi
+  break
+done
+`
+    : "";
+  const tail =
+    stage === "commit-msg"
+      ? `echo "[signoff] CLI not found: the commit continues, but it gets no Signoff trailer" >&2
+exit 0
+`
+      : `echo "[signoff] CLI not found: npm i -g signoff-cli (or add it as a devDependency)" >&2
+echo "[signoff] this repo is guarded; install the CLI, or bypass this once with --no-verify" >&2
+exit 1
+`;
+  return `#!/bin/sh
+${HOOK_MARK} ${packageVersion()} -- remove with: signoff uninstall
+ROOT=$(git rev-parse --show-toplevel) || exit 1
+${chained}if command -v signoff >/dev/null 2>&1; then
+  exec signoff hook ${stage}${extra}
+fi
+if [ -f "$ROOT/node_modules/signoff-cli/bin/signoff.js" ]; then
+  exec node "$ROOT/node_modules/signoff-cli/bin/signoff.js" hook ${stage}${extra}
+fi
+if [ -f "$ROOT/node_modules/dsh-signoff/bin/signoff.js" ]; then
+  exec node "$ROOT/node_modules/dsh-signoff/bin/signoff.js" hook ${stage}${extra}
+fi
+${tail}`;
+}
+
+const CI_BODY = `# generated by signoff-cli -- remove with: signoff uninstall
+name: signoff
+on: [push, pull_request]
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - run: npx --yes signoff-cli@latest guard --ci
+      - name: audit trailers
+        env:
+          GITHUB_EVENT_BEFORE: \${{ github.event.before }}
+        run: |
+          # A shallow clone has no history, and \`git rev-parse HEAD~1\` echoes the missing
+          # name instead of failing, so ask for a verified commit hash or nothing at all.
+          BASE="\${GITHUB_EVENT_BEFORE}"
+          if [ -z "$BASE" ] || ! git cat-file -e "$BASE^{commit}" 2>/dev/null; then
+            git fetch --unshallow --quiet 2>/dev/null || git fetch --deepen=50 --quiet 2>/dev/null || true
+            BASE=$(git rev-parse --verify --quiet "HEAD~1^{commit}" || true)
+          fi
+          if [ -n "$BASE" ]; then
+            npx --yes signoff-cli@latest audit --range "$BASE..HEAD"
+          else
+            echo "no base commit in this clone; skipping the trailer audit"
+          fi
+`;
+
+function writeExec(p, text) {
+  fs.writeFileSync(p, text, "utf8");
+  try {
+    fs.chmodSync(p, 0o755);
+  } catch (e) {
+    /* windows has no execute bit */
+  }
+}
+
+// ---------------------------------------------------------------- marker
+//
+// `.signoff/passed` is the hand-off from pre-commit to commit-msg: the tree the
+// gate run saw, and whether it passed or was explicitly skipped. It is deleted
+// by commit-msg as soon as it is used, so a marker never outlives its commit.
+
+// Consume the hand-off marker. It is single-use: a stale marker (tree no longer
+// matches, or a commit that never happened) must never survive to a later commit,
+// or the same trailer could be appended twice.
+function dropMarker(root) {
+  try {
+    fs.rmSync(markerPath(root), { force: true });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function markerPath(root) {
+  return path.join(root, STATE, "passed");
+}
+
+function currentTree(root) {
+  const r = sh(["git", "write-tree"], root);
+  const tree = r.code === 0 ? r.out.trim() : "";
+  return /^[0-9a-f]{40,64}$/.test(tree) ? tree : null;
+}
+
+function writeMarker(root, mode) {
+  const tree = currentTree(root);
+  if (!tree) return null;
+  fs.mkdirSync(path.join(root, STATE), { recursive: true });
+  dropMarker(root);
+  fs.writeFileSync(markerPath(root), JSON.stringify({ tree, mode, ts: now() }) + "\n", "utf8");
+  if (mode === "pass") maybeCheckpoint(root);
+  return tree;
+}
+
+// A repo that has ever written a checkpoint keeps writing them: the ledger is then
+// tamper-evident from the outside, not only from inside the file.
+function maybeCheckpoint(root) {
+  try {
+    const cfg = loadConfig(root);
+    const cp = require("./checkpoint");
+    if (cfg.checkpoint !== true && !exists(cp.checkpointPath())) return { ok: true, skipped: "no checkpoint in this repo" };
+    const now = cp.summarize();
+    const prev = cp.readCheckpoint();
+    // Same ledger, same statement: re-signing would only churn the file.
+    if (prev && Number(prev.seq) === now.seq && prev.head === now.head) {
+      return { ok: true, seq: now.seq, unchanged: true };
+    }
+    const made = cp.create({ sign: true });
+    return { ok: true, seq: made.checkpoint.seq, anchor: made.checkpoint.anchor };
+  } catch (e) {
+    // A hook must never fail a commit over bookkeeping; callers that care can see why.
+    return { ok: false, error: String((e && e.message) || e) };
+  }
+}
+
+// commit-msg <msgfile>: append the trailer only when the message belongs to the
+// tree the gates saw. Anything else (no marker, stale marker, unreadable file)
+// leaves the message alone and exits 0 — this hook never fails a commit.
+function cmdCommitMsg(msgfile) {
+  try {
+    if (typeof msgfile !== "string" || !msgfile) return 0;
+    const root = repoRoot();
+    const p = path.isAbsolute(msgfile) ? msgfile : path.join(root, msgfile);
+    if (!exists(p) || !exists(markerPath(root))) return 0;
+    let marker;
+    try {
+      marker = JSON.parse(readText(markerPath(root)));
+    } catch (e) {
+      return 0;
+    }
+    const tree = currentTree(root);
+    if (!tree || !marker) return 0;
+    if (marker.tree !== tree) {
+      dropMarker(root); // stale: the staged tree changed after the gate run
+      return 0;
+    }
+    const skip = marker.mode === "skip";
+    const line = `Signoff-${skip ? "Skip" : "Pass"}: ${tree.slice(0, 12)}`;
+    // Sign the full tree (not the 12-char prefix) so an auditor can verify against
+    // the commit's own tree without trusting anything local. Signing never blocks a
+    // commit: a missing key just leaves the trailer unsigned.
+    let extra = "";
+    if (!skip && process.env.SIGNOFF_NO_SIGN !== "1") {
+      try {
+        const signed = require("./sign").sign(tree);
+        if (signed) extra = `\nSignoff-Key: ${signed.key}\nSignoff-Sig: ${signed.sig}`;
+      } catch (e) {
+        extra = "";
+      }
+    }
+    let text = readText(p);
+    if (text.length && !text.endsWith("\n")) text += "\n";
+    fs.writeFileSync(p, text + line + extra + "\n", "utf8");
+    dropMarker(root);
+    console.log(`signoff: ${line}`);
+    return 0;
+  } catch (e) {
+    // fail open on purpose: a broken trailer is better than a lost commit
+    return 0;
+  }
+}
+
+// `init --prepare`: make the guard self-installing for anyone who clones the repo.
+function addPrepareScript(root, say, dryRun) {
+  const pkgPath = path.join(root, "package.json");
+  if (!isFile(pkgPath)) {
+    say("  prepare   skipped (no package.json)");
+    return;
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(readText(pkgPath));
+  } catch (e) {
+    say("  prepare   skipped (package.json is not valid JSON)");
+    return;
+  }
+  if (!pkg || typeof pkg !== "object") {
+    say("  prepare   skipped (package.json is not an object)");
+    return;
+  }
+  // A prepare script that cannot find the CLI breaks every npm install of the repo.
+  // Only write it when the package is a devDependency (then node_modules/.bin/signoff
+  // exists before lifecycle scripts run) or a local install is already present.
+  const deps = Object.assign({}, pkg.devDependencies || {}, pkg.dependencies || {});
+  const selfDep =
+    Object.prototype.hasOwnProperty.call(deps, "signoff-cli") ||
+    Object.prototype.hasOwnProperty.call(deps, "dsh-signoff");
+  const binName = process.platform === "win32" ? "signoff.cmd" : "signoff";
+  const localBin = isFile(path.join(root, "node_modules", ".bin", binName));
+  if (!selfDep && !localBin) {
+    say("  prepare   skipped: signoff-cli is not a devDependency, so the CLI is absent during install");
+    say("            run: npm i -D signoff-cli  then  signoff init --prepare");
+    return;
+  }
+  const scripts = pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+  const old = typeof scripts.prepare === "string" ? scripts.prepare.trim() : "";
+  if (old.includes(PREPARE_SCRIPT)) {
+    say(`  prepare   already set (${old})`);
+    return;
+  }
+  const next = old ? `${old} && ${PREPARE_SCRIPT}` : PREPARE_SCRIPT;
+  if (dryRun) {
+    say(`would set scripts.prepare = "${next}" in package.json`);
+    return;
+  }
+  pkg.scripts = Object.assign({}, scripts, { prepare: next });
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+  say(`  prepare   package.json scripts.prepare = "${next}"`);
+}
+
+// The extension of a chained hook decides how it is launched, so keep the one that
+// says what it is. A shell script (or anything unrecognised) keeps the plain `.local`.
+function chainSuffix(file) {
+  const text = readText(file);
+  if (/^#!.*\bpython/i.test(text)) return ".py";
+  if (/^#!.*\bnode\b/i.test(text)) return ".js";
+  if (/^#!.*\bpwsh\b|^#!.*\bpowershell\b/i.test(text)) return ".ps1";
+  return "";
+}
+
+const CHAIN_SUFFIXES = ["", ".sh", ".py", ".js", ".ps1", ".cmd"];
+
+function findChainFile(hooks, name) {
+  for (const suffix of CHAIN_SUFFIXES) {
+    const p = path.join(hooks, `${name}.local${suffix}`);
+    if (exists(p)) return p;
+  }
+  return null;
+}
+
+function cmdInit(args) {
+  const root = repoRoot();
+  const cfg = loadConfig(root);
+  let lockedNote = "";
+  if (args.testCmd) cfg.test_cmd = args.testCmd;
+  // Pinning what detection found keeps the runner from drifting on another machine
+  // (a laptop with pytest installed used to silently switch p1 to pytest).
+  if (args.lockTest) {
+    // `say` is defined further down (it honours --quiet), so report through it lazily.
+    const d = detector.detect(root, cfg);
+    if (d.cmd) {
+      cfg.test_cmd = d.cmd;
+      lockedNote = `  locked    ${d.cmd}  (${d.source})`;
+    } else {
+      lockedNote = "  locked    nothing to lock: no test runner was detected";
+    }
+  }
+  if (args.budget) cfg.budget = args.budget;
+  if (args.docs) cfg.docs = args.docs;
+  cfg.pre_push = !args.noPush;
+  cfg.ci = !args.noCi;
+  cfg.version = 2;
+
+  const say = args.quiet ? () => {} : (line) => console.log(line);
+
+  const hooks = path.join(root, ".git", "hooks");
+  const targets = [
+    ["pre-commit", "pre-commit"],
+    ["commit-msg", "commit-msg"],
+  ];
+  if (cfg.pre_push) targets.push(["pre-push", "pre-push"]);
+
+  if (args.dryRun) {
+    for (const [name] of targets) {
+      const target = path.join(hooks, name);
+      const local = path.join(hooks, `${name}.local${chainSuffix(target)}`);
+      if (exists(target) && !markedByUs(readText(target))) {
+        say(
+          args.chain
+            ? `would chain ${path.join(hooks, name)} -> ${path.basename(local)}`
+            : `would back up ${path.join(hooks, name)}`
+        );
+      }
+      say(`would write ${target}`);
+    }
+    if (cfg.ci) say(`would write ${path.join(root, ".github", "workflows", "signoff.yml")}`);
+    say(`would write ${path.join(root, STATE, "config.json")}`);
+    if (args.prepare) addPrepareScript(root, say, true);
+    return 0;
+  }
+
+  fs.mkdirSync(hooks, { recursive: true });
+  const notes = [];
+  for (const [name, stage] of targets) {
+    const target = path.join(hooks, name);
+    const existingChain = findChainFile(hooks, name);
+    let chain = !!existingChain;
+    if (exists(target) && !markedByUs(readText(target))) {
+      if (args.chain) {
+        if (!existingChain) {
+          const local = path.join(hooks, `${name}.local${chainSuffix(target)}`);
+          fs.renameSync(target, local);
+          notes.push(`  chained   .git/hooks/${path.basename(local)} runs first`);
+        } else {
+          notes.push(`  chained   .git/hooks/${path.basename(existingChain)} runs first`);
+        }
+        chain = true;
+      } else {
+        const backup = path.join(hooks, `${name}.signoff-backup`);
+        if (!exists(backup)) {
+          fs.writeFileSync(backup, readText(target), "utf8");
+          notes.push(`  saved old hook -> .git/hooks/${path.basename(backup)}`);
+        }
+      }
+    }
+    writeExec(target, hookBody(stage, chain));
+  }
+
+  if (cfg.ci) {
+    const ci = path.join(root, ".github", "workflows");
+    fs.mkdirSync(ci, { recursive: true });
+    writeExec(path.join(ci, "signoff.yml"), CI_BODY);
+  }
+
+  const gi = path.join(root, ".gitignore");
+  const line = `${STATE}/`;
+  if (exists(gi)) {
+    const txt = readText(gi);
+    if (!txt.split(/\r?\n/).includes(line)) {
+      fs.writeFileSync(gi, txt.replace(/\n+$/, "") + "\n" + line + "\n", "utf8");
+    }
+  } else {
+    fs.writeFileSync(gi, line + "\n", "utf8");
+  }
+
+  if (args.preset) {
+    const pre = require("./preset").apply(cfg, args.preset, cfg);
+    if (!pre.ok) {
+      console.error(`signoff init: ${pre.error}`);
+      return 2;
+    }
+    for (const n of pre.notes) say(n);
+  }
+
+  if (args.editor) {
+    if (String(args.editor) !== "vscode") {
+      console.error(`signoff init: unknown editor '${args.editor}' (supported: vscode)`);
+      return 2;
+    }
+    const ed = require("./editor").vscode(root, { command: "signoff" });
+    say(ed.ok ? `  editor    .vscode/tasks.json (${ed.added} task(s) added)` : `  editor    ${ed.reason}`);
+  }
+
+  saveConfig(root, cfg);
+
+  // The install point is what `audit --since-install` measures from, and what lets the
+  // plain audit explain a `missing` commit that simply predates the guard. Re-running
+  // init keeps the first one: history before the guard is history, not a failure.
+  const installPath = path.join(root, STATE, "installed.json");
+  if (args.resetInstall) {
+    const head = core.git(["rev-parse", "HEAD"], root);
+    const record = { sha: head.code === 0 ? head.out.trim() : "", ts: now(), version: packageVersion() };
+    fs.writeFileSync(installPath, JSON.stringify(record) + "\n", "utf8");
+    notes.push(`  install   reset to ${record.sha ? record.sha.slice(0, 12) : "(no commits yet)"}`);
+  } else if (!exists(installPath)) {
+    const head = core.git(["rev-parse", "HEAD"], root);
+    const record = { sha: head.code === 0 ? head.out.trim() : "", ts: now(), version: packageVersion() };
+    fs.writeFileSync(installPath, JSON.stringify(record) + "\n", "utf8");
+    notes.push(`  install   ${record.sha ? record.sha.slice(0, 12) : "(no commits yet)"}`);
+  } else {
+    // Re-init rewrites the hooks, so the recorded version has to follow them; the install
+    // point itself (sha + ts) stays put - that is the boundary of "before the guard".
+    let prev = null;
+    try {
+      prev = JSON.parse(fs.readFileSync(installPath, "utf8"));
+    } catch (e) {
+      prev = null;
+    }
+    if (prev) {
+      const next = Object.assign({}, prev);
+      let reason = null;
+      // A bootstrap can run during the very first commit, where HEAD does not exist yet, so
+      // the install point arrives without a sha. Re-init after that commit is the moment to
+      // fill it in - otherwise `audit --since-install` stays unusable for the repo's life.
+      if (!prev.sha) {
+        const head = core.git(["rev-parse", "HEAD"], root);
+        const headSha = head.code === 0 ? head.out.trim() : "";
+        if (headSha) {
+          next.sha = headSha;
+          next.ts = now();
+          reason = `${headSha.slice(0, 12)} (filled in: the first bootstrap ran before this commit)`;
+        }
+      }
+      // Re-init rewrites the hooks, so the recorded version has to follow them; the install
+      // point itself (sha + ts) stays put - that is the boundary of "before the guard".
+      if (prev.version !== packageVersion()) {
+        next.version = packageVersion();
+        if (!reason) reason = `${String(prev.version || "?")} -> ${packageVersion()} (same sha)`;
+      }
+      if (reason) {
+        fs.writeFileSync(installPath, JSON.stringify(next) + "\n", "utf8");
+        notes.push(`  install   ${reason}`);
+      }
+    }
+  }
+
+  if (args.sign) {
+    // A repo-local key is optional; without one the trailer is simply unsigned.
+    const keyPath = require("./sign").generateKey(path.join(root, STATE));
+    if (keyPath) {
+      cfg.sign_key = path.relative(root, keyPath).split(path.sep).join("/");
+      saveConfig(root, cfg);
+      notes.push("  sign      commits carry Signoff-Sig (local key: .signoff/signing_key)");
+    } else {
+      notes.push("  sign      skipped (ssh-keygen not available)");
+    }
+  }
+
+  if (args.share) {
+    // Only the portable fields: a pinned test command would break on a clone without that
+    // runner, which is the opposite of "clone and it works".
+    const decl = { $schema: "https://raw.githubusercontent.com/ayuanxx-max/dsh-signoff/master/docs/signoff.schema.json" };
+    decl.gates = ["p1", "p2", "p3", "p4", "p5"];
+    if (args.lockTest && cfg.test_cmd) decl.test_cmd = cfg.test_cmd;
+    fs.writeFileSync(path.join(root, "signoff.json"), JSON.stringify(decl, null, 2) + "\n", "utf8");
+    notes.push("  share     signoff.json (commit it: clones build the five gates themselves)");
+  }
+
+  if (args.prepare) addPrepareScript(root, say, false);
+
+  say(`signoff ${packageVersion()} installed in ${path.basename(root)}`);
+  for (const n of notes) say(n);
+  for (const [name] of targets) say(`  hook      .git/hooks/${name}`);
+  if (cfg.ci) say("  ci        .github/workflows/signoff.yml");
+  say(`  config    ${STATE}/config.json`);
+  if (lockedNote) say(lockedNote);
+  say(`  install   ${STATE}/installed.json`);
+  say(`  test      ${cfg.test_cmd || detector.describe(root, cfg)}`);
+  say("  next      git commit as usual; a red gate stops the commit");
+  return 0;
+}
+
+// ---------------------------------------------------------------- run
+
+function pythonExe() {
+  const override = process.env.SIGNOFF_PYTHON;
+  if (override) return override;
+  return process.platform === "win32" ? "python" : "python3";
+}
+
+// Python is optional: it is probed only to keep the pytest shortcut working in
+// repos that really use it. A machine without python just detects nothing.
+function pythonInterpreter() {
+  const candidates = [pythonExe()];
+  if (!process.env.SIGNOFF_PYTHON && process.platform !== "win32") candidates.push("python");
+  for (const exe of candidates) {
+    const r = sh([exe, "-c", "import sys;print(sys.executable)"]);
+    if (r.code === 0 && r.out.trim()) return r.out.trim();
+  }
+  return null;
+}
+
+function findTestFiles(root) {
+  const found = [];
+  const skip = new Set([".git", "node_modules", ".signoff", "__pycache__", ".venv", "venv"]);
+  const walk = (dir, depth) => {
+    if (depth > 8 || found.length) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (e) {
+      return;
+    }
+    for (const e of entries) {
+      if (found.length) return;
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (skip.has(e.name)) continue;
+        walk(p, depth + 1);
+      } else if (/^test_.*\.py$/.test(e.name)) {
+        found.push(p);
+        return;
+      }
+    }
+  };
+  walk(root, 0);
+  return found;
+}
+
+function detectTest(root, cfg) {
+  const d = detector.detect(root, cfg);
+  return d.cmd || null;
+}
+
+function stagedFiles(root) {
+  const r = sh(["git", "diff", "--cached", "--name-only", "--diff-filter=ACMR"], root);
+  return r.out
+    .split(/\r?\n/)
+    .map((ln) => ln.trim())
+    .filter((ln) => ln.length > 0);
+}
+
+function treeKey(root) {
+  const r = sh(["git", "write-tree"], root);
+  const base = r.code === 0 ? r.out.trim() : "";
+  const r2 = sh(["git", "diff", "--cached", "--name-only"], root);
+  return base + "|" + r2.out.split(/\s+/).filter(Boolean).sort().join(",");
+}
+
+function stagedDocs(files, cfg) {
+  const docs = cfg.docs || [];
+  const out = [];
+  for (const f of files) {
+    if (!/\.(md|mdx|txt)$/.test(f)) continue;
+    for (const raw of docs) {
+      const d = String(raw).replace(/\/+$/, "");
+      if (f === d || f.startsWith(d + "/")) {
+        out.push(f);
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+function ledgerPath() {
+  const home = process.env.SIGNOFF_HOME;
+  return home ? path.join(home, "audit.log") : path.join(os.homedir(), ".signoff", "audit.log");
+}
+
+function docsFiles(root, cfg) {
+  const out = [];
+  for (const raw of cfg.docs || []) {
+    const base = String(raw).replace(/\/+$/, "");
+    const target = path.join(root, base);
+    if (isFile(target)) {
+      out.push(base);
+    } else if (isDir(target)) {
+      const md = [];
+      const walk = (dir) => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+          const p = path.join(dir, e.name);
+          if (e.isDirectory()) walk(p);
+          else if (e.name.endsWith(".md")) md.push(p);
+        }
+      };
+      walk(target);
+      md.sort();
+      for (const p of md) out.push(path.relative(root, p).split(path.sep).join("/"));
+    }
+  }
+  return out;
+}
+
+function plan(root, cfg, files, full) {
+  const steps = [];
+  // Secrets first: a leaked key is not a style issue and must not wait for the suite.
+  if (cfg.secrets !== false) steps.push(["secrets", ["--json"]]);
+  const docs = stagedDocs(files, cfg);
+  if (docs.length) steps.push(["p5", docs]);
+  const cmd = detectTest(root, cfg);
+  if (cmd) steps.push(["p1", ["--run", cmd, "--budget", String(cfg.budget === undefined ? 180 : cfg.budget)]]);
+  // P2 only joins when the repo actually has scenario fixtures; a repo without
+  // them is not "low coverage", it is simply not using this gate.
+  if (isDir(path.join(root, "verify", "scenarios")) || cfg.apps) steps.push(["p2", ["--strict"]]);
+  if (exists(ledgerPath())) steps.push(["p4", ["verify"]]);
+  // Line coverage of the change is only meaningful when the project already produces
+  // a coverage file; a missing file is reported by the gate itself, not by the guard.
+  if (cfg.coverage) {
+    const min = typeof cfg.coverage === "object" && cfg.coverage.min !== undefined ? cfg.coverage.min : 80;
+    steps.push(["cov", ["--diff", "--min", String(min), "--allow-missing"]]);
+  }
+  return steps;
+}
+
+// The one intended change from the Python guard: the gate is this CLI itself,
+// run on the current node, so a global `npm i -g signoff-cli` needs no python.
+function runGate(name, gargs, root, timeoutSeconds) {
+  const t0 = Date.now();
+  const r = sh([process.execPath, DISPATCHER, name, ...gargs], root, timeoutSeconds * 1000);
+  const secs = (Date.now() - t0) / 1000;
+  if (r.error && (r.error.code === "ETIMEDOUT" || r.error.signal)) {
+    return { rc: 1, secs, out: `${name}: timed out after ${Math.round(timeoutSeconds)}s` };
+  }
+  if (r.error) {
+    return { rc: 127, secs, out: `${name}: cannot start ${process.execPath} (${r.error.message})` };
+  }
+  return { rc: r.code, secs, out: r.out + r.err };
+}
+
+// A PR reviewer should not have to open the log to learn which gate failed.
+function writeSummary(steps, seconds, ok, failed) {
+  const ci = require("./ci");
+  if (!ci.isCI()) return;
+  const bad = new Set((failed || []).map(([n]) => n));
+  const rows = steps.map(([name]) => [name, bad.has(name) ? "FAIL" : "ok"]);
+  ci.summary(
+    `### SignOff ${ok ? "PASS" : "FAIL"} (${Number(seconds).toFixed(2)}s)\n\n` +
+      ci.table(rows, ["gate", "result"]) +
+      (bad.size ? `\n\nFull output: \`.signoff/hook.log\`` : "")
+  );
+}
+
+function cmdGuard(args) {
+  const root = repoRoot();
+  const cfg = loadConfig(root);
+  const files = stagedFiles(root);
+  const full = !!(args.full || args.ci);
+  // Only pre-commit writes the hand-off marker: it is what commit-msg turns into a
+  // trailer. A pre-push run must not leave one behind for a commit that never came.
+  const mark = args.mark !== false;
+
+  if (!files.length && !full) {
+    console.log("signoff guard: nothing staged");
+    return 0;
+  }
+
+  const key = treeKey(root);
+  const cache = path.join(root, STATE, "cache.json");
+  if (!full && exists(cache)) {
+    try {
+      const c = JSON.parse(fs.readFileSync(cache, "utf8"));
+      if (c.key === key && c.ok) {
+        if (mark) writeMarker(root, "pass");
+        console.log(`signoff guard: cached pass (${Number(c.seconds || 0).toFixed(2)}s)`);
+        return 0;
+      }
+    } catch (e) {
+      /* a corrupt cache is a cache miss */
+    }
+  }
+
+  if (process.env.SIGNOFF_SKIP === "1") {
+    const sd = stateDir(root);
+    if (mark) writeMarker(root, "skip");
+    fs.appendFileSync(path.join(sd, "skips.log"), `${now()} skipped ${files.length} file(s) via SIGNOFF_SKIP=1\n`, "utf8");
+    console.log("signoff guard: SKIPPED (SIGNOFF_SKIP=1, recorded in .signoff/skips.log)");
+    return 0;
+  }
+
+  let steps = plan(root, cfg, files, full);
+  if (args.ci) {
+    // CI has no index: check every configured doc, not just the staged ones.
+    const allDocs = docsFiles(root, cfg);
+    if (allDocs.length) steps = [["p5", allDocs]].concat(steps.filter((s) => s[0] !== "p5"));
+  }
+  if (!steps.length) {
+    if (mark) writeMarker(root, "pass");
+    console.log("signoff guard: no gate applies to this change");
+    return 0;
+  }
+
+  const budget = Number(cfg.budget === undefined ? 180 : cfg.budget);
+  console.log(`signoff guard: ${files.length} file(s) staged, ${steps.length} gate(s)`);
+  const t0 = Date.now();
+  const failed = [];
+  for (const [name, gargs] of steps) {
+    const res = runGate(name, gargs, root, Math.max(budget, 60));
+    console.log(`  ${name.padEnd(4)} ${res.rc === 0 ? "ok  " : "FAIL"} ${res.secs.toFixed(2).padStart(6, " ")}s`);
+    if (res.rc !== 0) failed.push([name, res.out]);
+  }
+  const total = (Date.now() - t0) / 1000;
+
+  if (failed.length) {
+    const sd = stateDir(root);
+    fs.writeFileSync(path.join(sd, "hook.log"), failed.map(([n, o]) => `== ${n} ==\n${o}`).join("\n\n"), "utf8");
+    console.log(`signoff guard: FAIL (${total.toFixed(2)}s)`);
+    for (const [n, out] of failed) {
+      const tail = out
+        .trim()
+        .split(/\r?\n/)
+        .filter((ln) => ln.trim())
+        .slice(-8);
+      console.log(`-- ${n} --`);
+      for (const ln of tail) console.log(`  ${ln}`);
+    }
+    console.log(`  full output: ${STATE}/hook.log`);
+    writeSummary(steps, total, false, failed);
+    console.log("  bypass once: SIGNOFF_SKIP=1 git commit ... (recorded) or git commit --no-verify");
+    return 1;
+  }
+
+  fs.writeFileSync(
+    path.join(root, STATE, "cache.json"),
+    JSON.stringify({ key, ok: true, ts: now(), seconds: Number(total.toFixed(3)) }) + "\n",
+    "utf8"
+  );
+  if (mark) writeMarker(root, "pass");
+  console.log(`signoff guard: PASS (${total.toFixed(2)}s)`);
+  writeSummary(steps, total, true, []);
+  return 0;
+}
+
+// ---------------------------------------------------------------- status
+
+function installed(root) {
+  const hooks = path.join(root, ".git", "hooks");
+  const out = {};
+  for (const name of STAGES) {
+    const p = path.join(hooks, name);
+    out[name] = !!(exists(p) && markedByUs(readText(p)));
+  }
+  const ci = path.join(root, ".github", "workflows", "signoff.yml");
+  out.ci = !!(exists(ci) && markedByUs(readText(ci)));
+  out.config = exists(path.join(root, STATE, "config.json"));
+  // A commit can carry a trailer only when both halves of the hand-off exist:
+  // pre-commit records the tree, commit-msg writes the line from that record.
+  out.trailer = !!(out["pre-commit"] && out["commit-msg"]);
+  const c = path.join(root, STATE, "cache.json");
+  if (exists(c)) {
+    try {
+      const d = JSON.parse(fs.readFileSync(c, "utf8"));
+      out.last_run = { ok: d.ok, ts: d.ts, seconds: d.seconds };
+    } catch (e) {
+      /* unreadable cache: no last run */
+    }
+  }
+  return out;
+}
+
+function cmdStatus(args) {
+  const root = repoRoot();
+  const cfg = loadConfig(root);
+  const st = installed(root);
+  if (args.json) {
+    console.log(JSON.stringify({ root, version: packageVersion(), trailer: st.trailer, installed: st, config: cfg }));
+    return 0;
+  }
+  console.log(`repo        ${root}`);
+  console.log(`version     ${packageVersion()}`);
+  for (const k of ["pre-commit", "commit-msg", "pre-push", "ci"]) {
+    console.log(`${k.padEnd(12)}${st[k] ? "installed" : "missing"}`);
+  }
+  console.log(`${"trailer".padEnd(12)}${st.trailer ? "enforced" : "off"}`);
+  console.log(`${"config".padEnd(12)}${st.config ? "present" : "missing"}`);
+  console.log(`${"test".padEnd(12)}${detector.describe(root, cfg)}`);
+  const lr = st.last_run;
+  console.log(`${"last run".padEnd(12)}${lr ? lr.ts + (lr.ok ? " PASS" : " FAIL") : "never"}`);
+  return 0;
+}
+
+function cmdUninstall(args) {
+  const root = repoRoot();
+  const removedState = [];
+  const runtime = [`${STATE}/passed`, `${STATE}/cache.json`];
+  const removed = [];
+  for (const name of STAGES) {
+    const p = path.join(root, ".git", "hooks", name);
+    if (!exists(p) || !markedByUs(readText(p))) continue;
+    const local = findChainFile(path.join(root, ".git", "hooks"), name);
+    if (local) {
+      fs.rmSync(p, { force: true });
+      fs.renameSync(local, p);
+      removed.push(`.git/hooks/${name} (restored from ${path.basename(local)})`);
+    } else {
+      fs.unlinkSync(p);
+      removed.push(`.git/hooks/${name}`);
+    }
+  }
+  const ci = path.join(root, ".github", "workflows", "signoff.yml");
+  if (exists(ci) && markedByUs(readText(ci))) {
+    fs.unlinkSync(ci);
+    removed.push(".github/workflows/signoff.yml");
+  }
+  // The marker and the last-run cache describe a hook that no longer exists; leaving
+  // them behind makes the next `status` look installed. config/installed/ledger stay
+  // unless asked for: they are the repo's record, not runtime state.
+  for (const rel of runtime) {
+    const p = path.join(root, rel);
+    if (exists(p)) {
+      fs.rmSync(p, { force: true });
+      removedState.push(rel);
+    }
+  }
+  if (args.all || args.keepConfig) {
+    const ip = path.join(root, STATE, "installed.json");
+    if (exists(ip)) {
+      fs.rmSync(ip, { force: true });
+      removedState.push(`${STATE}/installed.json`);
+    }
+  }
+  if (args.all) {
+    const p = path.join(root, STATE, "config.json");
+    if (exists(p)) {
+      fs.unlinkSync(p);
+      removed.push(`${STATE}/config.json`);
+    }
+  }
+  console.log(`removed: ${removed.length ? removed.join(", ") : "nothing"}`);
+  if (removedState.length) console.log(`state:   ${removedState.join(", ")}`);
+  if (!args.all) {
+    const kept = [`${STATE}/config.json`, `${STATE}/ledger.jsonl`, `${STATE}/skips.log`].filter((rel) =>
+      exists(path.join(root, rel))
+    );
+    if (kept.length) console.log(`kept:    ${kept.join(", ")}  (use --all to drop the config)`);
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------- lock
+// Two commits in one repo at the same moment (IDE plus terminal) would race on
+// .signoff/passed: the first commit-msg consumes the marker the second run just wrote.
+// One hook run at a time; a lock left by a dead pid or older than 10 minutes is broken.
+function lockPath(root) {
+  return path.join(stateDir(root), "lock");
+}
+
+function pidAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// The owner record is a file inside the lock directory; 3.9.0 wrote a plain file at the
+// same path, so both shapes are read (and both can be broken).
+function readLockOwner(p) {
+  try {
+    const file = fs.statSync(p).isDirectory() ? path.join(p, "owner.json") : p;
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    return null;
+  }
+}
+
+function withLock(root, stage, fn) {
+  const p = lockPath(root);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const raw = process.env.SIGNOFF_LOCK_WAIT_MS;
+  const wait = raw === undefined ? 8000 : Number(raw) || 0;
+  const deadline = Date.now() + wait;
+  for (;;) {
+    try {
+      // mkdir is atomic and, unlike O_EXCL create, it is also honoured on SMB/NFS shares,
+      // where two `open(..., "wx")` calls can both succeed.
+      fs.mkdirSync(p);
+      fs.writeFileSync(
+        path.join(p, "owner.json"),
+        JSON.stringify({ pid: process.pid, stage: stage, ts: new Date().toISOString() }),
+        "utf8"
+      );
+      break;
+    } catch (e) {
+      const held = e.code === "EEXIST" ? readLockOwner(p) : null;
+      if (e.code !== "EEXIST") {
+        // EACCES or a plain file where the directory should be: treat as held only if
+        // something is visibly there, otherwise let the run continue.
+        if (!fs.existsSync(p)) return fn();
+      }
+      const old = !held || !pidAlive(held.pid) || Date.now() - Date.parse(held.ts || 0) > 10 * 60 * 1000;
+      if (old) {
+        fs.rmSync(p, { force: true, recursive: true });
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        console.error(`signoff: another signoff run holds the lock (pid ${held.pid}, ${held.stage}, ${held.ts})`);
+        console.error("signoff: retry when it finishes; if it is gone, delete .signoff/lock");
+        return 1;
+      }
+      sleepMs(200);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    fs.rmSync(p, { force: true, recursive: true });
+  }
+}
+
+function optedIn(root) {
+  return exists(path.join(root, STATE, "config.json"));
+}
+
+// The machine-wide dispatcher (core.hooksPath) reaches repos that never ran `signoff init`.
+// Five gates there would fail for reasons the repo never agreed to (no cards, no scenario
+// files, prose rules), so an unopted repo gets the one gate that is always meaningful -
+// do the tests pass - and leaves no state behind.
+function lightGuard(root, cfg, files) {
+  if (!files.length) return 0;
+  // A leaked key is the one accident that cannot be undone by a revert, so it is
+  // checked even where the repo never opted in. --no-state keeps that promise.
+  if (cfg.secrets !== false) {
+    const sec = runGate("secrets", ["--json", "--no-state"], root, 60);
+    if (sec.rc !== 0 && sec.rc !== 2) {
+      console.log("signoff guard: FAIL (staged secret, machine-wide guard)");
+      for (const ln of String(sec.out || "").trim().split(/\r?\n/).filter(Boolean).slice(-8)) {
+        console.log(`  ${ln}`);
+      }
+      console.log("  remove the value, or allow this rule in .signoff/config.json");
+      return 1;
+    }
+  }
+  const res = runGate("p1", [], root, 300);
+  if (res.rc === 0) return 0;
+  if (res.rc === 2) {
+    console.log("signoff: no test runner detected; run `signoff init` for the full five gates");
+    return 0;
+  }
+  console.log("signoff guard: FAIL (P1 tests, machine-wide guard)");
+  for (const ln of String(res.out || "").trim().split(/\r?\n/).filter(Boolean).slice(-8)) {
+    console.log(`  ${ln}`);
+  }
+  console.log("  opt in with `signoff init` (or `npm i -D signoff-cli`) to get all five gates");
+  return 1;
+}
+
+function cmdHook(args) {
+  const stage = args._[0];
+  if (stage === undefined)
+    return argparseError(HOOK_USAGE, "signoff guard hook", "the following arguments are required: stage");
+  if (STAGES.indexOf(stage) === -1)
+    return argparseError(
+      HOOK_USAGE,
+      "signoff guard hook",
+      `argument stage: invalid choice: '${stage}' (choose from 'pre-commit', 'commit-msg', 'pre-push')`
+    );
+  const root = repoRoot();
+  if (!optedIn(root)) {
+    // Nothing to hand off and nothing to audit: an unopted repo has no marker protocol.
+    if (stage === "commit-msg") return 0;
+    // Test suites and scripted runs own their fixture repos; they ask for the machine
+    // layer to stay out of the way explicitly rather than by unsetting core.hooksPath.
+    if (process.env.SIGNOFF_NO_MACHINE === "1") return 0;
+    // A committed signoff.json is the repository opting in for everyone who clones it:
+    // finish the local install, then run the same five gates as a local `signoff init`.
+    const boot = require("./bootstrap");
+    if (!boot.declaration(root)) return lightGuard(root, loadConfig(root), stagedFiles(root));
+    boot.ensureRepo({ cwd: root, quiet: true });
+    if (!optedIn(root)) return lightGuard(root, loadConfig(root), stagedFiles(root));
+  }
+  if (stage === "commit-msg") return cmdCommitMsg(args._[1]);
+  // commit-msg is deliberately not locked: it must never block a commit that git already
+  // accepted, and it only reads the marker pre-commit wrote.
+  return withLock(root, stage, () =>
+    cmdGuard({ full: stage === "pre-push", ci: false, mark: stage === "pre-commit" })
+  );
+}
+
+// ---------------------------------------------------------------- main
+
+// argparse-shaped errors, so a failed command reads the same as the Python
+// reference (message on stderr, exit 2, nothing on stdout).
+const USAGE = "usage: signoff guard [-h] {init,guard,hook,status,uninstall} ...";
+const HOOK_USAGE = "usage: signoff guard hook [-h] {pre-commit,commit-msg,pre-push}";
+const INIT_USAGE =
+  "usage: signoff guard init [-h] [--test-cmd TEST_CMD] [--budget BUDGET]\n" +
+  "                          [--docs [DOCS ...]] [--no-ci] [--no-push]\n" +
+  "                          [--prepare] [--lock-test] [--reset-install] [--share]\n" +
+  "                          [--quiet] [--dry-run]";
+
+function argparseError(usage, prog, body) {
+  process.stderr.write(`${usage}\n`);
+  process.stderr.write(`${prog}: error: ${body}\n`);
+  return 2;
+}
+
+function usageError(body) {
+  return argparseError(USAGE, "signoff guard", body);
+}
+
+function isInitPositionalError(args) {
+  return args.docs === undefined && args._.length > 0;
+}
+
+function main(argv) {
+  const args = core.parseArgs(argv || [], {});
+  const cmd = args._.shift();
+  try {
+    if (cmd === "init") {
+      // argparse raises "unrecognized arguments" from the top-level parser,
+      // so the usage line is the parent's, not the subparser's.
+      if (isInitPositionalError(args)) return usageError(`unrecognized arguments: ${args._.join(" ")}`);
+      return cmdInit(normalizeInit(args));
+    }
+    if (cmd === "guard") return cmdGuard(args);
+    if (cmd === "hook") return cmdHook(args);
+    if (cmd === "status") return cmdStatus(args);
+    if (cmd === "uninstall") {
+      if (args._.length) return usageError(`unrecognized arguments: ${args._.join(" ")}`);
+      return cmdUninstall(args);
+    }
+    if (!cmd) return usageError("the following arguments are required: cmd");
+    return usageError(
+      `argument cmd: invalid choice: '${cmd}' (choose from 'init', 'guard', 'hook', 'status', 'uninstall')`
+    );
+  } catch (e) {
+    if (e instanceof GuardExit) {
+      // repoRoot() fails closed: same one-line message and exit 1 as the Python guard.
+      process.stderr.write(`${e.message}\n`);
+      return e.code;
+    }
+    if (e instanceof ArgparseError) return argparseError(INIT_USAGE, "signoff guard init", e.message);
+    throw e;
+  }
+}
+
+// `--docs` takes zero or more values in the Python reference (argparse nargs="*").
+// init has no positionals of its own, so any left-over words belong to --docs.
+function normalizeInit(args) {
+  const rawBudget = args.budget;
+  let budget = null;
+  if (rawBudget === true) throw new ArgparseError("argument --budget: expected one argument");
+  if (rawBudget !== undefined) {
+    budget = Number(rawBudget);
+    if (!Number.isFinite(budget)) throw new ArgparseError(`argument --budget: invalid float value: '${rawBudget}'`);
+  }
+  if (args.testCmd === true) throw new ArgparseError("argument --test-cmd: expected one argument");
+  const out = {
+    testCmd: typeof args.testCmd === "string" ? args.testCmd : null,
+    lockTest: !!args.lockTest,
+    resetInstall: !!args.resetInstall,
+    budget,
+    docs: null,
+    noCi: !!args.noCi,
+    noPush: !!args.noPush,
+    chain: !!args.chain,
+    prepare: !!args.prepare,
+    quiet: !!args.quiet,
+    dryRun: !!args.dryRun,
+    share: !!args.share,
+    sign: !!args.sign,
+    preset: args.preset ? String(args.preset) : null,
+    editor: args.editor ? String(args.editor) : null,
+  };
+  if (args.docs !== undefined) {
+    const list = Array.isArray(args.docs) ? args.docs.slice() : args.docs === true ? [] : [String(args.docs)];
+    out.docs = list.concat(args._.map(String));
+    if (out.docs.length === 0) out.docs = null; // `--docs` alone: argparse -> []
+  }
+  return out;
+}
+
+module.exports = { main, hookBody, CI_BODY, DEFAULT_CONFIG, maybeCheckpoint };