tamperward 2.13.0 → 2.13.2

package/README.md

@@ -336,9 +336,13 @@ from trusted CI, or after an externally isolated agent hands off the frozen cand
 
 ### CLI reference
 
-Every flag below is what the command's parser actually reads (`src/cli/index.ts`,
-`parseVerify`, `parseRun`). `check` reports an unknown flag on stderr; the other
-commands ignore what they do not know.
+Every flag below is what the command's parser actually reads (`src/cli/main.ts`,
+`parseVerify`, `parseRun`). Since **2.13.1**, user-supplied argv is validated before
+any command-specific parser or side effect runs: unknown options, missing values,
+invalid numeric budgets/timeouts, duplicate/conflicting `check` views, and unexpected
+positionals fail closed with exit 2 and one deterministic `tamperward: ...` diagnostic.
+`run` requires an explicit `--` before the wrapped command, so a typoed TamperWard
+option can never be reinterpreted as the agent command.
 
 | command | flags |
 | --- | --- |

package/dist/cli/index.js

@@ -308,8 +308,8 @@ function inspectOnce(abs2) {
   try {
     st = lstatSync(abs2);
   } catch (e) {
-    const code = errCode(e);
-    if (code === "ENOENT" || code === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
+    const code2 = errCode(e);
+    if (code2 === "ENOENT" || code2 === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
     return { kind: "unreadable", content: null, ...NO_META, detail: errText(e) };
   }
   if (st.isSymbolicLink() || !st.isFile()) return classify(abs2, st);
@@ -320,8 +320,8 @@ function inspectPath(abs2) {
   try {
     st = lstatSync(abs2);
   } catch (e) {
-    const code = errCode(e);
-    if (code === "ENOENT" || code === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
+    const code2 = errCode(e);
+    if (code2 === "ENOENT" || code2 === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
     return { kind: "unreadable", content: null, ...NO_META, detail: errText(e) };
   }
   return classify(abs2, st);
@@ -334,8 +334,8 @@ function inspectResolved(abs2) {
   try {
     real = realpathSync(abs2);
   } catch (e) {
-    const code = errCode(e);
-    if (code === "ENOENT" || code === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
+    const code2 = errCode(e);
+    if (code2 === "ENOENT" || code2 === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
     return { kind: "unreadable", content: null, ...NO_META, detail: errText(e) };
   }
   return inspectPath(real);
@@ -2669,8 +2669,8 @@ var CODE_PROBES = ["src/index.ts", "src/index.js", "lib/index.js", "index.ts", "
 function sourceProbes(ctx) {
   const files = trackedFiles(ctx);
   if (!files) return CODE_PROBES;
-  const code = files.filter((f) => langOf(f) !== null);
-  return code.length ? code : CODE_PROBES;
+  const code2 = files.filter((f) => langOf(f) !== null);
+  return code2.length ? code2 : CODE_PROBES;
 }
 function triggerNarrowings(before, after, opts) {
   const out2 = [];
@@ -6535,8 +6535,8 @@ function terminalWidth(stream = process.stdout) {
   if (!c || c < 40) return 80;
   return Math.min(c, 100);
 }
-function paint(s, code, on) {
-  return on ? code + s + RESET : s;
+function paint(s, code2, on) {
+  return on ? code2 + s + RESET : s;
 }
 function wrap(text, width) {
   const out2 = [];
@@ -7025,7 +7025,7 @@ function dropTurnTree(cwd, sessionId) {
 }
 
 // src/cli/watch.ts
-import { appendFileSync as appendFileSync3, mkdirSync as mkdirSync4, readdirSync as readdirSync2, statSync, watch } from "node:fs";
+import { appendFileSync as appendFileSync3, lstatSync as lstatSync3, mkdirSync as mkdirSync4, readdirSync as readdirSync2, watch } from "node:fs";
 import { join as join11 } from "node:path";
 import { createHash as createHash4 } from "node:crypto";
 var SKIP2 = /(^|\/)(\.git|node_modules)(\/|$)/;
@@ -7060,7 +7060,7 @@ function watchTree(dir, cb) {
         const child = rel ? `${rel}/${String(fname)}` : String(fname);
         cb(kind, child);
         try {
-          if (statSync(join11(dir, child)).isDirectory()) addDir(child);
+          if (lstatSync3(join11(dir, child)).isDirectory()) addDir(child);
         } catch {
         }
       });
@@ -7081,7 +7081,7 @@ function watchTree(dir, cb) {
       const child = rel ? `${rel}/${name}` : name;
       if (SKIP2.test(child + "/")) continue;
       try {
-        if (statSync(join11(dir, child)).isDirectory()) walk2(child);
+        if (lstatSync3(join11(dir, child)).isDirectory()) walk2(child);
       } catch {
       }
     }
@@ -7126,12 +7126,12 @@ function runWatch(args) {
 }
 
 // src/detectors/fs-events.ts
-import { readFileSync as readFileSync10, statSync as statSync2 } from "node:fs";
+import { readFileSync as readFileSync10, statSync } from "node:fs";
 var RULE11 = "transient-protected-mutation";
 function readEvents(log, offset) {
   let size = 0;
   try {
-    size = statSync2(log).size;
+    size = statSync(log).size;
   } catch {
     return { events: [], newOffset: offset };
   }
@@ -7598,7 +7598,7 @@ Honored at LOCAL pre-commit only. The agent-layer hook ignores this file; CI req
 // src/cli/init.ts
 import { execFileSync as execFileSync6 } from "node:child_process";
 import { createHash as createHash6 } from "node:crypto";
-import { existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync12, writeFileSync as writeFileSync5, chmodSync, statSync as statSync3 } from "node:fs";
+import { existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync12, writeFileSync as writeFileSync5, chmodSync, statSync as statSync2 } from "node:fs";
 import { basename as basename2, dirname as dirname4, isAbsolute as isAbsolute8, join as join12, relative as relative3, resolve as resolve3 } from "node:path";
 
 // src/verifier-limits.ts
@@ -7985,7 +7985,7 @@ function planPreCommit(cwd) {
     }
   }
   const rel = display(cwd, path);
-  if (existsSync9(path) && !statSync3(path).isFile()) {
+  if (existsSync9(path) && !statSync2(path).isFile()) {
     return { item: "pre-commit", path: rel, status: "error", detail: "exists but is not a regular file \u2014 refusing to write" };
   }
   const existing = existsSync9(path) ? readFileSync12(path, "utf8") : null;
@@ -8535,7 +8535,7 @@ function runDoctor(opts = {}) {
 // src/cli/verify.ts
 import { execFileSync as execFileSync9, spawnSync as spawnSync2 } from "node:child_process";
 import { createHash as createHash10 } from "node:crypto";
-import { chmodSync as chmodSync2, cpSync, lstatSync as lstatSync4, mkdirSync as mkdirSync6, mkdtempSync as mkdtempSync2, readFileSync as readFileSync16, readlinkSync as readlinkSync3, rmSync as rmSync3, symlinkSync, writeFileSync as writeFileSync6 } from "node:fs";
+import { chmodSync as chmodSync2, cpSync, lstatSync as lstatSync5, mkdirSync as mkdirSync6, mkdtempSync as mkdtempSync2, readFileSync as readFileSync16, readlinkSync as readlinkSync3, rmSync as rmSync3, symlinkSync, writeFileSync as writeFileSync6 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import { dirname as dirname7, isAbsolute as isAbsolute10, join as join16, relative as relative5, resolve as resolve7, sep as sep2 } from "node:path";
 
@@ -8569,12 +8569,12 @@ function treeFingerprint(cwd, keepIgnored) {
 import { createHash as createHash8 } from "node:crypto";
 import {
   existsSync as existsSync11,
-  lstatSync as lstatSync3,
+  lstatSync as lstatSync4,
   readdirSync as readdirSync4,
   readFileSync as readFileSync14,
   readlinkSync as readlinkSync2,
   realpathSync as realpathSync3,
-  statSync as statSync4
+  statSync as statSync3
 } from "node:fs";
 import {
   basename as basename3,
@@ -8593,7 +8593,7 @@ function inside(root, candidate) {
   return rel === "" || rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute9(rel);
 }
 function modeKind(path) {
-  const st = lstatSync3(path);
+  const st = lstatSync4(path);
   if (st.isFile()) return { kind: "file", mode: st.mode };
   if (st.isDirectory()) return { kind: "dir", mode: st.mode };
   if (st.isSymbolicLink()) return { kind: "symlink", mode: st.mode };
@@ -8603,7 +8603,7 @@ function fingerprintRoot(root, cwd, h) {
   let rootStat;
   let currentReal;
   try {
-    rootStat = lstatSync3(root.path);
+    rootStat = lstatSync4(root.path);
     currentReal = realpathSync3(root.path);
   } catch (e) {
     throw new Unattestable(
@@ -8615,7 +8615,7 @@ function fingerprintRoot(root, cwd, h) {
       root.kind + " root moved from " + JSON.stringify(root.realPath) + " to " + JSON.stringify(currentReal)
     );
   }
-  if (!statSync4(root.path).isDirectory()) {
+  if (!statSync3(root.path).isDirectory()) {
     throw new Unattestable(root.kind + " root " + JSON.stringify(root.path) + " is not a directory");
   }
   h.update("root\0" + root.kind + "\0" + root.path + "\0" + root.realPath + "\0" + String(rootStat.mode) + "\0");
@@ -8625,7 +8625,7 @@ function fingerprintRoot(root, cwd, h) {
   const hashFile = (path, label) => {
     let st;
     try {
-      st = statSync4(path);
+      st = statSync3(path);
       if (!st.isFile()) throw new Error("not a regular file");
       h.update(label + "\0external-file\0" + path + "\0" + String(st.mode) + "\0");
       h.update(readFileSync14(path));
@@ -8691,7 +8691,7 @@ function fingerprintRoot(root, cwd, h) {
         } catch {
           continue;
         }
-        const followed = statSync4(path);
+        const followed = statSync3(path);
         if (followed.isFile()) {
           hashFile(resolved, "@target:" + rel);
           continue;
@@ -8729,7 +8729,7 @@ function snapshot(roots, probes, cwd) {
 }
 function freezeRoot(kind, path) {
   try {
-    if (!statSync4(path).isDirectory()) {
+    if (!statSync3(path).isDirectory()) {
       throw new Error("not a directory");
     }
     return { kind, path: resolve5(path), realPath: realpathSync3(path) };
@@ -8778,7 +8778,7 @@ function resolveExecutable(token, cwd, env) {
   for (const entry of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
     const candidate = resolve5(entry, token);
     try {
-      if (existsSync11(candidate) && statSync4(candidate).isFile()) return realpathSync3(candidate);
+      if (existsSync11(candidate) && statSync3(candidate).isFile()) return realpathSync3(candidate);
     } catch {
     }
   }
@@ -8921,7 +8921,7 @@ function dependencyEnvironmentSummary(descriptor) {
 // src/verifier-backend.ts
 import { createHash as createHash9, randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { accessSync, constants as constants2, readFileSync as readFileSync15, realpathSync as realpathSync4, statSync as statSync5 } from "node:fs";
+import { accessSync, constants as constants2, readFileSync as readFileSync15, realpathSync as realpathSync4, statSync as statSync4 } from "node:fs";
 import { delimiter as delimiter2, dirname as dirname6, join as join15, resolve as resolve6 } from "node:path";
 var DEFAULT_CONTAINER_RESOURCE_LIMITS = Object.freeze({
   memoryBytes: 2 * 1024 * 1024 * 1024,
@@ -8939,7 +8939,7 @@ function identity() {
 }
 function writableByCaller(path) {
   try {
-    const st = statSync5(path);
+    const st = statSync4(path);
     const { uid, groups } = identity();
     if (uid === 0) return true;
     if ((st.mode & 2) !== 0) return true;
@@ -9317,8 +9317,8 @@ function runContainerStage(backend, dir, command, budgetSecs) {
     const secs = Math.round((Date.now() - t0) / 1e3);
     if (r.error) {
       cleanupContainer(backend, name);
-      const code = r.error.code;
-      return code === "ETIMEDOUT" ? { exit: null, secs, failure: "budget", reason: "verifier stage exceeded its budget" } : { exit: null, secs, failure: "backend", reason: `Docker client failed: ${r.error.message}` };
+      const code2 = r.error.code;
+      return code2 === "ETIMEDOUT" ? { exit: null, secs, failure: "budget", reason: "verifier stage exceeded its budget" } : { exit: null, secs, failure: "backend", reason: `Docker client failed: ${r.error.message}` };
     }
     if (r.status === null) {
       cleanupContainer(backend, name);
@@ -9512,7 +9512,7 @@ function validateSymlinkGraph(target, out2, root, dependencyRoot, label) {
     const current = join16(base, ...stack);
     let st;
     try {
-      st = lstatSync4(current);
+      st = lstatSync5(current);
     } catch {
       continue;
     }
@@ -9548,7 +9548,7 @@ function rejectLinkedParent(cwd, rel) {
     current = join16(current, part);
     let st;
     try {
-      st = lstatSync4(current);
+      st = lstatSync5(current);
     } catch {
       continue;
     }
@@ -9565,7 +9565,7 @@ function materialize(cwd, dest, dependencyRoot) {
     rejectLinkedParent(cwd, rel);
     let st;
     try {
-      st = lstatSync4(src);
+      st = lstatSync5(src);
     } catch {
       continue;
     }
@@ -9590,7 +9590,7 @@ function materialize(cwd, dest, dependencyRoot) {
 }
 function dropSymlink(p) {
   try {
-    if (lstatSync4(p).isSymbolicLink()) rmSync3(p, { force: true });
+    if (lstatSync5(p).isSymbolicLink()) rmSync3(p, { force: true });
   } catch {
   }
 }
@@ -9621,7 +9621,7 @@ function overlayDigest(dest, paths) {
     h.update("\0");
     const p = join16(dest, rel);
     try {
-      const st = lstatSync4(p);
+      const st = lstatSync5(p);
       h.update(String(st.mode));
       h.update(st.isSymbolicLink() ? readlinkSync3(p) : readFileSync16(p));
     } catch {
@@ -9942,22 +9942,22 @@ function runVerify(opts) {
     return 2;
   }
   let verdict2;
-  let code;
+  let code2;
   if (visible.exit === null || pristine.exit === null) {
     verdict2 = "BUDGET_EXCEEDED";
-    code = 2;
+    code2 = 2;
   } else if (visible.exit === 0 && pristine.exit === 0) {
     verdict2 = "VERIFIED";
-    code = 0;
+    code2 = 0;
   } else if (visible.exit === 0) {
     verdict2 = "MASKED_FAILURE";
-    code = 1;
+    code2 = 1;
   } else {
     verdict2 = "SUITE_RED";
-    code = 1;
+    code2 = 1;
   }
   const signedOff = verdict2 === "MASKED_FAILURE" ? oobToken("verify", oobFromEnv(), oobHeadFromEnv()) : null;
-  if (signedOff) code = 0;
+  if (signedOff) code2 = 0;
   if (opts.json) {
     out2(
       JSON.stringify({
@@ -10000,7 +10000,7 @@ function runVerify(opts) {
         `(${removedAdded} protected file(s) added since ${base.slice(0, 10)} were removed from the pristine run: the pristine tree carries exactly the base's protected surface.)`
       );
   }
-  return code;
+  return code2;
 }
 function parseVerify(args) {
   const o = {};
@@ -10567,17 +10567,148 @@ function parseCheck(args) {
     else if (a === "--format") {
       const v = args[++i];
       if (v !== void 0 && isFormat(v)) o.format = v;
-      else process.stderr.write(`tamperward: unknown --format "${v ?? ""}" (expected ${FORMATS.join(" | ")})
-`);
     } else if (a === "--diff") o.diff = args[++i];
     else if (a === "--cwd") o.cwd = args[++i];
-    else {
-      process.stderr.write(`tamperward: unknown flag "${a}"
-`);
-    }
   }
   return o;
 }
+function validateFlatArgs(args, grammar) {
+  const flags = new Set(grammar.flags ?? []);
+  const values = grammar.values ?? {};
+  const seen = /* @__PURE__ */ new Set();
+  const positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (flags.has(a) || Object.prototype.hasOwnProperty.call(values, a)) {
+      if (seen.has(a)) {
+        return { error: `option "${a}" specified more than once`, seen, positionals };
+      }
+      seen.add(a);
+      const rule = values[a];
+      if (!rule) continue;
+      const v = args[i + 1];
+      if (v === void 0 || v.startsWith("--")) {
+        return {
+          error: `${a} needs a value` + (v === void 0 ? "" : ` (got the flag "${v}")`),
+          seen,
+          positionals
+        };
+      }
+      i++;
+      if (rule === "positive") {
+        const n = Number(v);
+        if (!Number.isFinite(n) || n <= 0) {
+          return { error: `${a} needs a positive number (got "${v}")`, seen, positionals };
+        }
+      } else if (rule === "non-negative") {
+        const n = Number(v);
+        if (!Number.isFinite(n) || n < 0) {
+          return { error: `${a} needs a non-negative number (got "${v}")`, seen, positionals };
+        }
+      } else if (rule === "format" && !isFormat(v)) {
+        return {
+          error: `--format needs one of ${FORMATS.join(" | ")} (got "${v}")`,
+          seen,
+          positionals
+        };
+      }
+      continue;
+    }
+    if (a.startsWith("-")) {
+      return { error: `unknown option "${a}"`, seen, positionals };
+    }
+    if (grammar.positional === "one" && positionals.length === 0) {
+      positionals.push(a);
+      continue;
+    }
+    return { error: `unexpected argument "${a}"`, seen, positionals };
+  }
+  return { seen, positionals };
+}
+function validateCliArgs(cmd, args) {
+  if (cmd === "hook" || cmd === "sweep") {
+    if (args.length === 0) return `${cmd} requires an agent name`;
+    if (args.length > 1) return `unexpected argument "${args[1]}"`;
+    return void 0;
+  }
+  if (cmd === "run") {
+    const delimiter3 = args.indexOf("--");
+    if (delimiter3 < 0) return 'run requires an explicit "--" before the wrapped command';
+    const prefix = args.slice(0, delimiter3);
+    const command = args.slice(delimiter3 + 1);
+    const parsed = validateFlatArgs(prefix, {
+      flags: ["--allow-dirty", "--allow-dep-drift"],
+      values: {
+        "--base": "string",
+        "--cmd": "string",
+        "--budget": "positive",
+        "--agent-budget": "positive",
+        "--settle": "non-negative",
+        "--cwd": "string"
+      }
+    });
+    if (parsed.error) return parsed.error;
+    if (command.length === 0) return 'run requires a wrapped command after "--"';
+    return void 0;
+  }
+  if (cmd === "check") {
+    const parsed = validateFlatArgs(args, {
+      flags: ["--staged", "--worktree", "--json"],
+      values: { "--diff": "string", "--format": "format", "--cwd": "string" }
+    });
+    if (parsed.error) return parsed.error;
+    const views = ["--staged", "--worktree", "--diff"].filter((x) => parsed.seen.has(x));
+    if (views.length > 1) return "choose exactly one of --staged, --worktree, or --diff";
+    if (parsed.seen.has("--json") && parsed.seen.has("--format")) {
+      return "--json cannot be combined with --format";
+    }
+    return void 0;
+  }
+  if (cmd === "allow") {
+    const parsed = validateFlatArgs(args, {
+      values: { "--file": "string", "--reason": "string", "--cwd": "string" },
+      positional: "one"
+    });
+    if (parsed.error) return parsed.error;
+    if (parsed.positionals.length === 0) return "allow requires a rule";
+    return void 0;
+  }
+  if (cmd === "init") {
+    return validateFlatArgs(args, {
+      flags: ["--dry-run", "--force-workflow"],
+      values: { "--cwd": "string" }
+    }).error;
+  }
+  if (cmd === "doctor") {
+    return validateFlatArgs(args, {
+      flags: ["--github"],
+      values: {
+        "--cwd": "string",
+        "--base": "string",
+        "--workflow": "string",
+        "--repo": "string",
+        "--branch": "string"
+      }
+    }).error;
+  }
+  if (cmd === "verify") {
+    return validateFlatArgs(args, {
+      flags: ["--json", "--keep", "--require-ancestor"],
+      values: {
+        "--base": "string",
+        "--cmd": "string",
+        "--cwd": "string",
+        "--budget": "positive"
+      }
+    }).error;
+  }
+  if (cmd === "watch") {
+    return validateFlatArgs(args, {
+      values: { "--dir": "string", "--log": "string" }
+    }).error;
+  }
+  return void 0;
+}
 function printHelp() {
   process.stdout.write(`tamperward \u2014 the deterministic agent-integrity gate
 
@@ -10652,6 +10783,14 @@ Exit codes: 0 clean \xB7 1 a blocking finding (check), MASKED_FAILURE or SUITE_R
 }
 function main(argv2) {
   const [cmd, ...rest] = argv2;
+  if (cmd !== void 0 && cmd !== "-h" && cmd !== "--help") {
+    const invalid = validateCliArgs(cmd, rest);
+    if (invalid) {
+      process.stderr.write(`tamperward: ${invalid}
+`);
+      return 2;
+    }
+  }
   switch (cmd) {
     case "check":
       return runCheck(parseCheck(rest));
@@ -10665,6 +10804,8 @@ function main(argv2) {
       return runInit(parseInit(rest));
     case "doctor":
       return runDoctor(parseDoctor(rest));
+    case "watch":
+      return runWatch(rest);
     case "verify":
       return runVerify(parseVerify(rest));
     case "run":
@@ -10694,8 +10835,5 @@ function guardedMain(argv2, stderr = process.stderr) {
 
 // src/cli/index.ts
 var argv = process.argv.slice(2);
-if (argv[0] === "watch") {
-  runWatch(argv.slice(1));
-} else {
-  process.exit(guardedMain(argv));
-}
+var code = guardedMain(argv);
+if (code >= 0) process.exit(code);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamperward",
-  "version": "2.13.0",
+  "version": "2.13.2",
   "description": "The deterministic agent-integrity gate. One ruleset, evaluated on the actual diff/commands as a verdict, enforced everywhere a change can be made.",
   "license": "Apache-2.0",
   "author": "hexrift",