signoff-cli 0.0.0-stage → 4.0.0

package/lib/audit.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+"use strict";
+// signoff audit — did the commits that landed actually carry a Signoff trailer?
+//
+// The pre-commit hook records what it saw in `.signoff/passed` (staged tree + mode)
+// and the commit-msg hook turns that record into a `Signoff-Pass:` / `Signoff-Skip:`
+// line on the message. `git commit --no-verify` skips both hooks, so that commit
+// carries no trailer at all — this command is how that stops being invisible after
+// the fact: a trailer only counts when its tree prefix matches the commit's tree.
+
+const fs = require("fs");
+const path = require("path");
+const core = require("./core");
+
+const DEFAULT_RANGE = "HEAD~1..HEAD";
+const TRAILER = /^Signoff-(Pass|Skip): ([0-9a-f]{12})$/;
+const SIG_LINE = /^Signoff-(Key|Sig): (.+)$/;
+const USAGE = `usage: signoff audit [-h] [--range A..B] [--since-install] [--json] [--strict] [--verify] [--require-signed]
+
+Did the commits that landed carry a Signoff trailer?
+
+options:
+  -h, --help       show this help message and exit
+  --range A..B     commit range to audit (default: ${DEFAULT_RANGE})
+  --since-install  audit from the commit recorded by signoff init
+  --json           machine-readable result
+  --strict         also fail on Signoff-Skip commits
+  --verify         check each commit's Signoff-Sig against its Signoff-Key
+                   (slow: one ssh-keygen per commit)
+  --require-signed fail when a commit carries no signature at all
+`;
+
+function warn(msg) {
+  process.stderr.write(`signoff audit: ${msg}\n`);
+}
+
+// `.signoff/installed.json` is written by `signoff init`; older repos do not have it.
+function installPoint() {
+  const top = core.git(["rev-parse", "--show-toplevel"]);
+  if (top.code !== 0) return null;
+  const p = path.join(top.out.trim(), ".signoff", "installed.json");
+  try {
+    const d = JSON.parse(fs.readFileSync(p, "utf8"));
+    return d && typeof d.sha === "string" ? d : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function isAncestor(sha, of) {
+  return core.git(["merge-base", "--is-ancestor", sha, of]).code === 0;
+}
+
+function run(argv) {
+  const args = core.parseArgs(argv || [], { verify: false, requireSigned: false });
+  if (args.help || args._.indexOf("-h") !== -1) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const install = installPoint();
+  const sinceInstall = !!args.sinceInstall;
+  let range = DEFAULT_RANGE;
+  if (sinceInstall) {
+    if (!install || !install.sha) {
+      if (install && !install.sha) {
+        warn("install point has no commit yet (the first bootstrap ran mid-commit)");
+        warn("run `signoff init` once more after committing, or audit --range A..B");
+      } else {
+        warn("no install point recorded (run `signoff init`, or pass --range A..B)");
+      }
+      return 2;
+    }
+    // The install point is a commit id. If history was rewritten (rebase, force-push)
+    // or this is a different clone, that id is not an ancestor of HEAD and the range
+    // silently covers the wrong commits - a wrong audit is worse than a refused one.
+    const known = core.git(["cat-file", "-e", `${install.sha}^{commit}`]);
+    const anc = known.code === 0 ? core.git(["merge-base", "--is-ancestor", install.sha, "HEAD"]) : { code: 1 };
+    if (known.code !== 0 || anc.code !== 0) {
+      warn(`install point ${String(install.sha).slice(0, 12)} is not an ancestor of HEAD`);
+      warn("history was rewritten or this is another clone; run: signoff init --reset-install");
+      warn("(or audit an explicit window with --range A..B)");
+      return 2;
+    }
+    range = `${install.sha}..HEAD`;
+  }
+  if (args.range !== undefined) {
+    if (args.range === true) {
+      warn("--range needs a value, e.g. --range HEAD~1..HEAD");
+      return 2;
+    }
+    range = String(args.range);
+  }
+  const strict = !!args.strict;
+  const asJson = !!args.json;
+
+  if (core.git(["rev-parse", "--git-dir"]).code !== 0) {
+    warn("not a git repository (run inside a repo)");
+    return 2;
+  }
+  const listed = core.git(["rev-list", range]);
+  if (listed.code !== 0) {
+    warn(`cannot parse range '${range}' (try --range HEAD~1..HEAD)`);
+    return 2;
+  }
+
+  const shas = listed.out
+    .split(/\r?\n/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const counts = { pass: 0, skip: 0, missing: 0 };
+  const sigCounts = {};
+  const verify = !!args.verify;
+  const sigcheck = require("./sign");
+  const allowed = verify ? sigcheck.allowedKeys(core.git(["rev-parse", "--show-toplevel"]).out.trim() || process.cwd()) : [];
+  const commits = [];
+  let merges = 0;
+
+  for (const sha of shas) {
+    // A merge has no single staged tree, so it cannot be accountable this way.
+    const parents = core.git(["log", "-1", "--format=%P", sha])
+      .out.split(/\s+/)
+      .filter(Boolean);
+    if (parents.length > 1) {
+      merges++;
+      continue;
+    }
+    const tree = core.git(["rev-parse", `${sha}^{tree}`]).out.trim().slice(0, 12);
+    const body = core.git(["log", "-1", "--format=%B", sha]).out;
+    let pass = null;
+    let skip = null;
+    for (const line of body.split(/\r?\n/)) {
+      const m = TRAILER.exec(line.trim());
+      if (!m) continue;
+      if (m[1] === "Pass") pass = m[2];
+      else skip = m[2];
+    }
+    let state = "missing";
+    if (pass !== null && pass === tree) state = "pass";
+    else if (skip !== null && skip === tree) state = "skip";
+    counts[state]++;
+    const entry = { sha, state };
+    if (verify) {
+      let key = null;
+      let sig = null;
+      for (const line of body.split(/\r?\n/)) {
+        const m = SIG_LINE.exec(line.trim());
+        if (!m) continue;
+        if (m[1] === "Key") key = m[2].trim();
+        else sig = m[2].trim();
+      }
+      if (state !== "pass") {
+        entry.sig = "unsigned";
+      } else if (!key || !sig) {
+        entry.sig = "unsigned";
+      } else {
+        const full = core.git(["rev-parse", `${sha}^{tree}`]).out.trim();
+        const v = sigcheck.verify(full, key, sig, allowed);
+        entry.sig = v.state;
+        if (v.reason) entry.why = v.reason;
+      }
+      sigCounts[entry.sig] = (sigCounts[entry.sig] || 0) + 1;
+    }
+    commits.push(entry);
+  }
+
+  // A missing commit that predates the install point cannot carry a trailer: the guard
+  // did not exist yet. Say so instead of leaving the number unexplained.
+  let preInstall = 0;
+  if (counts.missing > 0 && install && install.sha && !sinceInstall) {
+    for (const c of commits) {
+      if (c.state !== "missing") continue;
+      if (isAncestor(c.sha, install.sha)) preInstall++;
+    }
+  }
+
+  let ok = counts.missing === 0 && !(strict && counts.skip > 0);
+  if (verify) {
+    if ((sigCounts["bad-signature"] || 0) > 0) ok = false;
+    if (args.requireSigned && (sigCounts.unsigned || 0) > 0) ok = false;
+  }
+
+  if (asJson) {
+    const payload = { ok, range, strict, counts, skipped_merges: merges, commits };
+    if (verify) payload.signatures = sigCounts;
+    if (install && install.sha) payload.install = { sha: install.sha, pre_install_missing: preInstall };
+    core.json(payload);
+  } else {
+    for (const c of commits) console.log(`${c.sha.slice(0, 7)} ${c.state}`);
+    console.log(
+      `audit: ${shas.length} commits, pass=${counts.pass} skip=${counts.skip} ` +
+        `missing=${counts.missing} skipped_merges=${merges}`
+    );
+    if (strict && counts.skip > 0) console.log("audit: strict, so Signoff-Skip commits are failures");
+    if (verify) {
+      const total = Object.values(sigCounts).reduce((n, v) => n + v, 0);
+      const parts = Object.entries(sigCounts).map(([k, v]) => `${k}=${v}`).join(" ");
+      console.log(`audit: signatures ${parts || "none"} (of ${total} audited)`);
+      if (!(sigCounts.verified || 0) && total) {
+        console.log("audit: no key matched .signoff/allowed_signers (self-signed is not an identity)");
+      }
+    }
+    if (preInstall > 0) {
+      console.log(
+        `audit: ${preInstall} of ${counts.missing} missing commit(s) predate the install point ` +
+          `(${install.sha.slice(0, 12)}); use --since-install`
+      );
+    }
+  }
+  return ok ? 0 : 1;
+}
+
+module.exports = { run, USAGE, DEFAULT_RANGE };

package/lib/bootstrap.js

@@ -0,0 +1,361 @@
+"use strict";
+// Zero-touch bootstrap: after one `npm i -g signoff-cli`, nothing else is typed.
+//
+// Two layers, both idempotent and silent unless they change something:
+//   1. repo layer  — the first gate run (or `npm i` inside a repo) writes .git/hooks,
+//                    .signoff/config.json, .signoff/installed.json and the CI workflow.
+//   2. machine layer — `core.hooksPath` points at ~/.signoff/hooks, so a fresh clone
+//                    of any repo is guarded on the next commit without per-repo install.
+// The machine layer delegates to the repo's own hook first, then to the gates, so an
+// existing hook keeps its verdict.
+//
+// Opt out per shell with SIGNOFF_NO_BOOTSTRAP=1, per machine with `signoff uninstall --global`.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+const core = require("./core");
+
+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 STAGES = ["pre-commit", "commit-msg", "pre-push"];
+const DECLARATION = "signoff.json";
+
+function gitRoot(cwd) {
+  const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
+  if (r.status !== 0) return null;
+  const out = (r.stdout || "").trim().split(/\r?\n/).pop();
+  return out ? out : null;
+}
+
+function gitDir(root) {
+  const r = spawnSync("git", ["rev-parse", "--git-dir"], { cwd: root, encoding: "utf8" });
+  if (r.status !== 0) return null;
+  const raw = (r.stdout || "").trim();
+  return path.isAbsolute(raw) ? raw : path.join(root, raw);
+}
+
+// A committed `signoff.json` at the repo root is the repository saying "run all five".
+// It has to be committed to be useful: `.signoff/` is gitignored, so a teammate's clone
+// arrives with the declaration and nothing else, and the first commit builds the rest.
+function declaration(p) {
+  const root = path.resolve(p || process.cwd());
+  const file = path.join(root, DECLARATION);
+  if (!isFile(file)) return null;
+  try {
+    const parsed = JSON.parse(readSafe(file));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch (e) {
+    return null;
+  }
+}
+
+// Declaration fields are a small, documented subset: anything else is ignored, because a
+// committed file must never be able to widen what the gates check on someone else's clone.
+function applyDeclaration(root, decl) {
+  const file = path.join(root, STATE, "config.json");
+  let cfg;
+  try {
+    cfg = JSON.parse(readSafe(file));
+  } catch (e) {
+    return;
+  }
+  if (!cfg || typeof cfg !== "object") return;
+  if (typeof decl.test_cmd === "string" && decl.test_cmd) cfg.test_cmd = decl.test_cmd;
+  if (typeof decl.budget === "number" && Number.isFinite(decl.budget)) cfg.budget = decl.budget;
+  if (Array.isArray(decl.docs) && decl.docs.length) cfg.docs = decl.docs.map(String);
+  if (typeof decl.pre_push === "boolean") cfg.pre_push = decl.pre_push;
+  fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+
+function readSafe(p) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+function isFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch (e) {
+    return false;
+  }
+}
+
+function hookState(root) {
+  const gd = gitDir(root);
+  const hooks = gd ? path.join(gd, "hooks") : null;
+  const out = {};
+  for (const stage of STAGES) {
+    const p = hooks ? path.join(hooks, stage) : "";
+    out[stage] = !!(p && isFile(p) && markedByUs(readSafe(p)));
+  }
+  return out;
+}
+
+// What a repo still needs. `guarded` means every piece the hooks depend on exists.
+function inspect(root) {
+  const hooks = hookState(root);
+  const st = path.join(root, STATE);
+  const config = isFile(path.join(st, "config.json"));
+  const installed = isFile(path.join(st, "installed.json"));
+  const ci = isFile(path.join(root, ".github", "workflows", "signoff.yml"));
+  const guarded = hooks["pre-commit"] && hooks["commit-msg"] && config;
+  return { root, hooks, config, installed, ci, guarded };
+}
+
+// Write the package's init in `root` without touching the caller's cwd for longer than
+// the call. guard.main reads process.cwd(), so the chdir is the seam.
+function initRepo(root, quiet) {
+  const guard = require("./guard");
+  const before = process.cwd();
+  let code = 1;
+  try {
+    process.chdir(root);
+    code = guard.main(["init", "--chain", ...(quiet ? ["--quiet"] : [])]) || 0;
+  } catch (e) {
+    code = 1;
+  } finally {
+    process.chdir(before);
+  }
+  return code;
+}
+
+// Returns {ok, root, installed, changed[], code}. Never throws: it runs inside npm
+// postinstall and inside git hooks, where a crash would be worse than a skipped install.
+function ensureRepo(opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const root = gitRoot(cwd);
+  if (!root) {
+    return { ok: false, root: null, installed: false, changed: [], reason: "not a git repository", code: 2 };
+  }
+  const before = inspect(root);
+  if (before.guarded && before.installed) {
+    return { ok: true, root, installed: false, changed: [], code: 0, state: before };
+  }
+  const code = initRepo(root, true);
+  if (!before.config) {
+    const decl = o.decl || declaration(root);
+    if (decl) applyDeclaration(root, decl);
+  }
+  const after = inspect(root);
+  const changed = [];
+  if (!before.hooks["pre-commit"] && after.hooks["pre-commit"]) changed.push("hooks");
+  if (!before.config && after.config) changed.push("config");
+  if (!before.installed && after.installed) changed.push("installed.json");
+  if (!before.ci && after.ci) changed.push("ci");
+  return { ok: code === 0 && after.guarded, root, installed: changed.length > 0, changed, code, state: after };
+}
+
+// ---------------------------------------------------------------- machine layer
+
+function globalHooksDir() {
+  return path.join(core.homeDir(), "hooks");
+}
+
+function dispatcherBody(stage) {
+  return `#!/bin/sh
+${HOOK_MARK} ${require("../package.json").version} -- remove with: signoff uninstall --global
+# Machine-wide dispatcher: hand the verdict to the repo's own hook first. If that hook is
+# ours it already ran the gates, so stop there; otherwise add the light guard on top.
+STAGE=${stage}
+GITDIR=$(git rev-parse --git-dir 2>/dev/null) || exit 0
+LOCAL="$GITDIR/hooks/$STAGE"
+if [ -f "$LOCAL" ]; then
+  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
+  if grep -q "${HOOK_MARK}" "$LOCAL" 2>/dev/null || grep -q "${LEGACY_HOOK_MARK}" "$LOCAL" 2>/dev/null; then
+    exit 0
+  fi
+fi
+if command -v signoff >/dev/null 2>&1; then
+  exec signoff hook $STAGE "$@"
+fi
+if [ -f "./node_modules/signoff-cli/bin/signoff.js" ]; then
+  exec node "./node_modules/signoff-cli/bin/signoff.js" hook $STAGE "$@"
+fi
+if [ -f "./node_modules/dsh-signoff/bin/signoff.js" ]; then
+  exec node "./node_modules/dsh-signoff/bin/signoff.js" hook $STAGE "$@"
+fi
+if [ "$STAGE" = "commit-msg" ]; then
+  echo "[signoff] CLI not found: the commit continues, but it gets no Signoff trailer" >&2
+  exit 0
+fi
+echo "[signoff] CLI not found: npm i -g signoff-cli (or add it as a devDependency)" >&2
+exit 1
+`;
+}
+
+function writeExec(p, text) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, text, "utf8");
+  try {
+    fs.chmodSync(p, 0o755);
+  } catch (e) {
+    /* Windows has no exec bit; git runs the hook through sh anyway. */
+  }
+}
+
+function globalHooksPathSetting() {
+  const r = spawnSync("git", ["config", "--global", "--get", "core.hooksPath"], { encoding: "utf8" });
+  if (r.status !== 0) return "";
+  return (r.stdout || "").trim();
+}
+
+function samePath(a, b) {
+  if (!a || !b) return false;
+  const norm = (p) => path.resolve(p).replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+  const na = norm(a);
+  const nb = norm(b);
+  if (na === nb) return true;
+  // git may store `~/...`; compare the expanded forms too.
+  if (a.startsWith("~/")) return norm(path.join(os.homedir(), a.slice(2))) === nb;
+  return false;
+}
+
+function setGlobalHooksPath(dir) {
+  const value = dir.replace(/\\/g, "/");
+  const r = spawnSync("git", ["config", "--global", "core.hooksPath", value], { encoding: "utf8" });
+  return r.status === 0;
+}
+
+function ensureGlobal(opts) {
+  const o = opts || {};
+  const dir = globalHooksDir();
+  const existing = globalHooksPathSetting();
+  if (existing && !samePath(existing, dir) && !o.force) {
+    return {
+      ok: false,
+      installed: false,
+      dir,
+      skipped: true,
+      reason: `core.hooksPath already points at ${existing} (use --force to replace it)`,
+      code: 0,
+    };
+  }
+  const changed = [];
+  for (const stage of STAGES) {
+    const p = path.join(dir, stage);
+    const body = dispatcherBody(stage);
+    if (readSafe(p) !== body) {
+      writeExec(p, body);
+      changed.push(stage);
+    }
+  }
+  const wrote = setGlobalHooksPath(dir);
+  if (wrote) changed.push("core.hooksPath");
+  return { ok: true, installed: changed.length > 0, dir, changed, code: 0 };
+}
+
+function uninstallGlobal() {
+  const dir = globalHooksDir();
+  const existing = globalHooksPathSetting();
+  const owned = existing && samePath(existing, dir);
+  if (owned) spawnSync("git", ["config", "--global", "--unset", "core.hooksPath"], { encoding: "utf8" });
+  for (const stage of STAGES) {
+    const p = path.join(dir, stage);
+    if (isFile(p) && markedByUs(readSafe(p))) fs.rmSync(p, { force: true });
+  }
+  return { ok: true, owned, dir, removed: owned };
+}
+
+function status() {
+  const root = gitRoot(process.cwd());
+  const cfg = globalHooksPathSetting();
+  const dir = globalHooksDir();
+  return {
+    repo: root,
+    repoState: root ? inspect(root) : null,
+    global: { configured: cfg, expected: dir.replace(/\\/g, "/"), active: !!cfg && samePath(cfg, dir) },
+  };
+}
+
+// ---------------------------------------------------------------- CLI
+
+const HELP = `signoff ensure — one-time (and then automatic) install
+
+  signoff ensure                 guard this repo now: hooks, config, CI, ledger
+  signoff ensure --global        guard every repo on this machine (core.hooksPath)
+  signoff ensure --json          machine-readable result
+  signoff ensure --quiet         say nothing unless something changed
+
+Every gate command (p1..p5, all, guard, hook) runs the repo layer by itself, so a clone
+that never saw \`signoff init\` is guarded on its first commit. Opt out with
+SIGNOFF_NO_BOOTSTRAP=1; undo the machine layer with \`signoff uninstall --global\`.
+`;
+
+function run(argv) {
+  const args = argv || [];
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log(HELP);
+    return 0;
+  }
+  const json = args.includes("--json");
+  const quiet = args.includes("--quiet");
+  const global = args.includes("--global");
+  const force = args.includes("--force");
+  const fromInstall = args.includes("--from-install");
+
+  let repo = null;
+  if (!global || fromInstall) {
+    const cwd = fromInstall && process.env.INIT_CWD ? process.env.INIT_CWD : process.cwd();
+    repo = ensureRepo({ cwd, quiet });
+  }
+  let machine = null;
+  if (global || fromInstall) machine = ensureGlobal({ force });
+
+  if (json) {
+    console.log(JSON.stringify({ repo, machine }, null, 2));
+  } else if (!quiet) {
+    if (repo && repo.root) {
+      console.log(repo.installed ? `signoff: guarded ${path.basename(repo.root)} (${repo.changed.join(", ")})` : `signoff: ${path.basename(repo.root)} already guarded`);
+    } else if (repo) {
+      console.log(`signoff: ${repo.reason}`);
+    }
+    if (machine) {
+      if (machine.skipped) console.log(`signoff: machine layer skipped — ${machine.reason}`);
+      else console.log(machine.installed ? `signoff: machine layer -> ${machine.dir}` : "signoff: machine layer already in place");
+    }
+  }
+
+  // postinstall must never fail an npm install.
+  if (fromInstall) return 0;
+  if (repo && !repo.ok && repo.code === 2 && !global) return 2;
+  if (repo && !repo.ok && repo.code) return 1;
+  return 0;
+}
+
+module.exports = {
+  HOOK_MARK,
+  LEGACY_HOOK_MARK,
+  markedByUs,
+  DECLARATION,
+  declaration,
+  gitRoot,
+  inspect,
+  ensureRepo,
+  ensureGlobal,
+  uninstallGlobal,
+  globalHooksDir,
+  globalHooksPathSetting,
+  status,
+  run,
+};