@dougharness/cli 1.0.2 → 1.1.0

package/node_modules/@dougharness/gates/lib/verified-tree.mjs

@@ -0,0 +1,225 @@
+// Verified-tree record (card verified-tree-record): "these commands exited 0 on exactly this tree".
+//
+// computeTree hashes the WORKING tree (tracked, modified and untracked-but-not-ignored files) into a git tree
+// sha through a private temp index, so the real index and the staged diff are never touched. A writer records
+// the sha after a green run; a reader credits the record when the current tree is the recorded one, or differs
+// only on preCommit.noTestPaths (the pre-commit rule), under the same Node and the same command set.
+//
+// Standing: a record is an honest-path record, not proof. A forged record credits Stop, SubagentStop, land and
+// verify.mjs (accepted, same standing as the proposal ledger, decision 0006 amendment). The commit cannot be
+// forged past: the pre-commit hook never reads it.
+//
+// Every export except resolveCommands never throws (hook readers fail open): failure returns null / false / no-op.
+// resolveCommands is moved unchanged from stop-gate.mjs and expects a loaded config.
+
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { pathToFileURL } from "node:url";
+
+export const RECORD_RELPATH = ".doug/.state/verified-tree.json";
+export const EXCLUDED = [".doug/.state", ".claude/worktrees", ".doug/anchor.md"];
+
+const SHA_RE = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+const GIT_FLAGS = ["-c", "core.fsmonitor=false", "-c", "core.untrackedCache=false"];
+
+function cleanGitEnv(extra = {}) {
+  const env = {};
+  for (const [k, v] of Object.entries(process.env)) if (!k.startsWith("GIT_")) env[k] = v;
+  return { ...env, ...extra };
+}
+
+function git(dir, args, env) {
+  return spawnSync("git", [...GIT_FLAGS, ...args], { cwd: dir, encoding: "utf8", env, timeout: 10000, maxBuffer: 64 * 1024 * 1024 });
+}
+
+function unlinkQuiet(p) {
+  try {
+    unlinkSync(p);
+  } catch {
+    // already gone
+  }
+}
+
+export function computeTree(dir, opts) {
+  let tmpIndex = null;
+  try {
+    const tmpDir = (opts && opts.tmpDir) || join(dir, ".doug/.state");
+    const baseEnv = cleanGitEnv();
+    const where = git(dir, ["rev-parse", "--git-path", "index"], baseEnv);
+    if (where.status !== 0) return null;
+    const realIndex = resolve(dir, String(where.stdout).trim());
+    mkdirSync(tmpDir, { recursive: true });
+    tmpIndex = join(tmpDir, `verified-tree.index.${process.pid}.${randomBytes(4).toString("hex")}`);
+    if (existsSync(realIndex)) {
+      // Stat BEFORE copying: a git replacing the index between copy and stat would pair new times with old bytes.
+      const st = statSync(realIndex);
+      copyFileSync(realIndex, tmpIndex);
+      // git's racy-clean check compares entry mtimes with the index FILE's mtime; a fresh copy would look newer
+      // than the real index and let a same-size edit made in the same instant as the last index write read as
+      // unchanged (a stale blob in the tree). Keep the real index's times, floored to whole seconds (an older
+      // time is always the safe side, and it needs no nanosecond support).
+      utimesSync(tmpIndex, Math.floor(st.atimeMs / 1000), Math.floor(st.mtimeMs / 1000));
+    }
+    const env = cleanGitEnv({ GIT_INDEX_FILE: tmpIndex });
+    // No pathspec and no exclude pathspecs: an exclude of a gitignored dir makes `git add` exit 1.
+    if (git(dir, ["add", "-A"], env).status !== 0) return null;
+    // The seed may carry tracked entries for excluded paths (anchor.md is tracked in this repo).
+    if (git(dir, ["rm", "-r", "-q", "-f", "--cached", "--ignore-unmatch", "--", ...EXCLUDED], env).status !== 0) return null;
+    const staged = git(dir, ["ls-files", "-s"], env);
+    if (staged.status !== 0) return null;
+    if (String(staged.stdout).split("\n").some((l) => l.startsWith("160000 "))) return null;
+    const tags = git(dir, ["ls-files", "-v"], env);
+    if (tags.status !== 0) return null;
+    if (String(tags.stdout).split("\n").some((l) => /^[a-zS] /.test(l))) return null;
+    const w = git(dir, ["write-tree"], env);
+    if (w.status !== 0) return null;
+    const sha = String(w.stdout).trim();
+    return SHA_RE.test(sha) ? sha : null;
+  } catch {
+    return null;
+  } finally {
+    if (tmpIndex) {
+      unlinkQuiet(tmpIndex);
+      unlinkQuiet(`${tmpIndex}.lock`);
+    }
+  }
+}
+
+const isObj = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+
+export function validRecord(r) {
+  try {
+    return (
+      isObj(r) &&
+      r.version === 1 &&
+      typeof r.tree === "string" &&
+      SHA_RE.test(r.tree) &&
+      Array.isArray(r.commands) &&
+      r.commands.length > 0 &&
+      r.commands.every((c) => isObj(c) && typeof c.name === "string" && typeof c.command === "string" && c.command !== "" && Number.isInteger(c.exit) && typeof c.durationMs === "number") &&
+      isObj(r.totals) &&
+      typeof r.node === "string" &&
+      typeof r.at === "string"
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function readRecord(dir) {
+  try {
+    const r = JSON.parse(readFileSync(join(dir, RECORD_RELPATH), "utf8"));
+    return validRecord(r) ? r : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeRecord(dir, record) {
+  let tmp = null;
+  try {
+    mkdirSync(join(dir, ".doug/.state"), { recursive: true });
+    tmp = join(dir, `${RECORD_RELPATH}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`);
+    writeFileSync(tmp, JSON.stringify(record));
+    renameSync(tmp, join(dir, RECORD_RELPATH));
+    return true;
+  } catch {
+    if (tmp) unlinkQuiet(tmp);
+    return false;
+  }
+}
+
+export function removeRecord(dir) {
+  try {
+    unlinkSync(join(dir, RECORD_RELPATH));
+  } catch {
+    // ENOENT or unremovable: nothing to do
+  }
+}
+
+// The pre-commit rule (.githooks/pre-commit, lib/baseline.mjs): equal to the entry, or under an entry ending in `/`.
+export function noTestPathHit(list, p) {
+  try {
+    return list.some((e) => (e.endsWith("/") ? p.startsWith(e) : p === e));
+  } catch {
+    return false;
+  }
+}
+
+export function resolveCommands(cfg) {
+  const out = [];
+  for (const entry of cfg.stopGate.commands || []) {
+    if (typeof entry !== "string") continue;
+    const named = cfg.commands && cfg.commands[entry];
+    out.push({ name: entry, command: typeof named === "string" ? named : entry });
+  }
+  return out;
+}
+
+// -> { ok: true, diff } or { ok: false, why }.
+export function creditable(dir, cfg, record, currentTree, commands) {
+  try {
+    if (!validRecord(record)) return { ok: false, why: "no valid record" };
+    if (!record.commands.every((c) => c.exit === 0)) return { ok: false, why: "record has a failing command" };
+    if (record.node !== process.version) return { ok: false, why: "record is from another Node version" };
+    if (typeof currentTree !== "string" || !SHA_RE.test(currentTree)) return { ok: false, why: "current tree unknown" };
+    const rec = new Set(record.commands.map((c) => c.command));
+    const now = new Set(commands);
+    if (rec.size !== now.size || ![...rec].every((c) => now.has(c))) return { ok: false, why: "command set differs" };
+    if (record.tree === currentTree) return { ok: true, diff: [] };
+    const list = cfg && cfg.preCommit && cfg.preCommit.noTestPaths;
+    if (!Array.isArray(list) || list.length === 0 || !list.every((e) => typeof e === "string" && e !== "")) return { ok: false, why: "tree differs and no noTestPaths list" };
+    const d = git(dir, ["diff-tree", "-r", "-z", "--name-only", "--no-renames", record.tree, currentTree], cleanGitEnv());
+    if (d.status !== 0) return { ok: false, why: "recorded tree unknown to git" };
+    const diff = String(d.stdout).split("\0").filter((p) => p !== "");
+    if (diff.length === 0) return { ok: false, why: "empty diff between differing trees" };
+    if (diff.includes(".doug/config.json")) return { ok: false, why: ".doug/config.json changed" };
+    const bad = diff.find((p) => !noTestPathHit(list, p));
+    if (bad !== undefined) return { ok: false, why: `${bad} changed and is not a no-test path` };
+    return { ok: true, diff };
+  } catch {
+    return { ok: false, why: "error" };
+  }
+}
+
+// CLI for the pre-commit hook: `node verified-tree.mjs tree [dir]` prints the tree sha (empty on failure);
+// `node verified-tree.mjs record <treeBefore> <commandsJson> [dir]` writes a by-pre-commit record when the
+// working tree is still treeBefore. Always exits 0.
+function isMain() {
+  try {
+    return !!process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+if (isMain()) {
+  try {
+    const [cmd, a, b, c] = process.argv.slice(2);
+    if (cmd === "tree") {
+      process.stdout.write(computeTree(a || process.cwd()) || "");
+    } else if (cmd === "record") {
+      const dir = c || process.cwd();
+      const after = computeTree(dir);
+      if (after && after === a) {
+        const commands = JSON.parse(b);
+        const totals = {};
+        for (const cm of commands) {
+          if (cm.totals && cm.totals.status === "ok") totals[cm.command] = cm.totals;
+        }
+        writeRecord(dir, {
+          version: 1,
+          tree: after,
+          node: process.version,
+          at: new Date().toISOString(),
+          by: "pre-commit",
+          commands: commands.map((cm) => ({ name: cm.name, command: cm.command, exit: cm.exit, durationMs: cm.durationMs })),
+          totals,
+        });
+      }
+    }
+  } catch {
+    // never fail the hook
+  }
+}

package/node_modules/@dougharness/gates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougharness/gates",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "private": true,
   "description": "Deterministic Claude Code hooks: protected paths, bash guard, secret scan on edits and commands, format on edit, edit-loop detection, stop gate, re-anchor after compaction.",
   "type": "module",

package/node_modules/@dougharness/gates/scripts/research-cap.mjs

@@ -19,10 +19,33 @@
 //
 // Known limits (round 2, major 2 - measured, not guessed): the cap is a budget nudge for researchers, not a
 // security boundary. Not counted at all: xargs curl; a for/while loop body (do curl ...); timeout 10 curl ...;
-// and any other wrapper resolveVerb does not skip (docker run ... curl, ssh host curl); other fetchers (gh api,
-// a node -e "fetch(...)" one-liner, python, etc.). Counted although no network call happens: curl --version,
-// curl --help. A shell -c script with several curls in it (bash -c 'curl a; curl b') counts once, since
-// commandForms reads the whole -c script as one form.
+// eval curl ...; and any other wrapper resolveVerb does not skip (docker run ... curl, ssh host curl); other
+// fetchers (gh api, a node -e "fetch(...)" one-liner, python, etc.). Counted although no network call happens:
+// curl --version, curl --help. A shell -c script with several curls in it (bash -c 'curl a; curl b') counts
+// once, since commandForms reads the whole -c script as one form.
+//
+// Loopback exemption (card research-cap-localhost, whole-command grammar, fix pass 5): a local model probe is not
+// web research, so it is neither counted nor denied. The exemption applies only when the entire raw command
+// string, before any splitting, is ONE simple fetch (isLoopbackFetch):
+//   1. Trimmed, it tokenizes into words. Single quotes are literal; double quotes may not hold $, a backtick, a
+//      backslash or !; an unterminated quote is not exempt. Outside quotes only space, tab, [A-Za-z0-9._:/=@%+,-]
+//      and a redirect's > are allowed, so & | ; ( ) { } [ ] * ? ~ # $ ` \ ! < and a newline are never exempt.
+//   2. The first word is exactly curl or wget: no path, wrapper, assignment or other case.
+//   3. Every other word is an allowlisted option (value-less -s -S -f -L -i -v -g or --silent and similar,
+//      combinable in one short token; value-taking -o -H -d -X -w -m for curl, -O -T and --header for wget,
+//      whose value is any word and is never URL-checked), a redirect, or a loopback URL: host exactly localhost,
+//      127.0.0.1 or [::1] with an optional scheme and port, matched whole (localhost.evil.com, localhost@evil.com
+//      and 127.0.0.1.nip.io are remote). [::1] is a glob unquoted, so it is exempt only inside quotes. At least
+//      one loopback URL is required; there is no other positional word.
+//   4. A redirect is only >, >> or 2>, attached to or followed by one unquoted, charset-clean target that is
+//      exactly /dev/null or does not start with /dev/ (bash opens /dev/tcp and /dev/udp as sockets).
+// A command outside the grammar is not an error: it is counted by bashFetchVerbs exactly as at HEAD, one count
+// per split command whose first resolved fetch form is curl or wget. Only Bash curl/wget is affected; WebFetch
+// and WebSearch always count. Anything doubtful counts: a compound line, a pipe, a wrapper, a mixed local and
+// remote command, no URL such as curl --version, other 127.x addresses, 0.0.0.0, host.docker.internal.
+// Accepted limits of the exemption: an env proxy (https_proxy=http://evil.com in the environment, not on the
+// command) routes the request out; -L, and wget by default, follow a redirect a local server can point at a
+// remote host; a ~/.curlrc or ~/.wgetrc can add a URL or a proxy.
 //
 // Known limit: several calls issued in one message can each read the same count before any of them appends, so
 // a single burst can push an agent's count past the cap by the number of calls it issues at once.
@@ -242,11 +265,116 @@ function splitTopLevel(command) {
   return results;
 }
 
+const LOOPBACK_TOKEN = /^(?:[a-z][a-z0-9+.-]*:\/\/)?(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?(?:[/?#].*)?$/i;
+const UNQUOTED_SAFE = /[A-Za-z0-9._:/=@%+,-]/;
+const REDIRECT = /^2?>>?(.*)$/;
+const REDIRECT_TARGET = /^[A-Za-z0-9._:/=@%+,-]+$/;
+
+// Option allowlist. A loopback fetch may carry only these options; every other option (-K/--config, -x/--proxy,
+// wget -i/--input-file, --url, --, curl -T, anything unknown) can hide a remote target or proxy. Value-less flags
+// may be combined in one short token; a value-taking letter may come last with its value attached (-qO-,
+// -sSo/tmp/x). A value is never URL-checked.
+const FETCH_OPTIONS = {
+  curl: {
+    flags: new Set("sSfLivg"),
+    longFlags: new Set(["silent", "show-error", "fail", "location", "include", "verbose", "compressed", "no-progress-meter"]),
+    valueShort: new Set("oHdXwm"),
+    valueLong: new Set(["output", "header", "data", "data-raw", "data-binary", "json", "request", "write-out", "max-time", "connect-timeout"]),
+  },
+  wget: {
+    flags: new Set("q"),
+    longFlags: new Set(["quiet"]),
+    valueShort: new Set("OT"),
+    valueLong: new Set(["output-document", "header", "post-data", "timeout"]),
+  },
+};
+
+// Words of one simple command, or null when the text leaves the grammar's character set (rule 1). Each word keeps
+// its raw source text (quotes included), its unquoted value, and whether it holds an unquoted redirect ">".
+function tokenize(text) {
+  const words = [];
+  let raw = "";
+  let val = "";
+  let gt = false;
+  let open = false;
+  let quote = "";
+  const end = () => {
+    if (open) words.push({ raw, val, gt });
+    raw = "";
+    val = "";
+    gt = false;
+    open = false;
+  };
+  for (const ch of text) {
+    if (quote) {
+      raw += ch;
+      if (ch === quote) quote = "";
+      else if (quote === '"' && "$`\\!".includes(ch)) return null;
+      else val += ch;
+    } else if (ch === " " || ch === "\t") end();
+    else {
+      open = true;
+      raw += ch;
+      if (ch === "'" || ch === '"') quote = ch;
+      else if (ch === ">") {
+        gt = true;
+        val += ch;
+      } else if (UNQUOTED_SAFE.test(ch)) val += ch;
+      else return null;
+    }
+  }
+  if (quote) return null;
+  end();
+  return words;
+}
+
+// True only when the whole raw command is one simple loopback fetch (see the header). Never throws: string tests
+// only; anything outside the grammar returns false and is counted as at HEAD.
+function isLoopbackFetch(command) {
+  const words = tokenize(String(command).trim());
+  if (!words || words.length < 2 || !Object.hasOwn(FETCH_OPTIONS, words[0].raw)) return false;
+  const opts = FETCH_OPTIONS[words[0].raw];
+  let urls = 0;
+  let wantValue = false;
+  for (let k = 1; k < words.length; k += 1) {
+    const { raw, val, gt } = words[k];
+    if (gt) {
+      const m = REDIRECT.exec(raw);
+      if (!m) return false;
+      let target = m[1];
+      if (target === "") {
+        k += 1;
+        if (k >= words.length) return false;
+        target = words[k].raw;
+      }
+      if (!REDIRECT_TARGET.test(target) || (target.startsWith("/dev/") && target !== "/dev/null")) return false;
+    } else if (wantValue) wantValue = false;
+    else if (raw.startsWith("--")) {
+      const eq = val.indexOf("=");
+      const name = val.slice(2, eq === -1 ? undefined : eq);
+      if (opts.valueLong.has(name)) wantValue = eq === -1;
+      else if (eq !== -1 || !opts.longFlags.has(name)) return false;
+    } else if (raw.startsWith("-")) {
+      if (raw.length === 1) return false;
+      for (let c = 1; c < raw.length; c += 1) {
+        if (opts.flags.has(raw[c])) continue;
+        if (!opts.valueShort.has(raw[c])) return false;
+        wantValue = c === raw.length - 1;
+        break;
+      }
+    } else if (LOOPBACK_TOKEN.test(val) && !/\s/.test(val)) urls += 1;
+    else return false;
+  }
+  return urls > 0;
+}
+
 // Returns one verb ("curl" or "wget") per split command of a Bash command line that resolves to a fetch;
 // non-fetch split commands contribute nothing. A non-string command (missing, or e.g. a number) is zero
 // fetches. commandForms runs on each split command's original text with its quotes intact (it does its own
-// quote parsing for a shell -c script), never on stripped or reconstructed text.
+// quote parsing for a shell -c script), never on stripped or reconstructed text. A command that is one simple
+// loopback fetch (isLoopbackFetch) is not a fetch to count.
 function bashFetchVerbs(command) {
+  if (isLoopbackFetch(command)) return [];
   const verbs = [];
   for (const cmd of splitTopLevel(command)) {
     for (const form of commandForms(cmd)) {