vigiles 2.5.0 → 2.6.0

package/dist/run-hook.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseHookOutput = parseHookOutput;
 exports.decideHook = decideHook;
+exports.runHookWith = runHookWith;
 exports.runHook = runHook;
 /**
  * vigiles — the *unit* tier for Claude Code hooks.
@@ -33,6 +34,10 @@ exports.runHook = runHook;
  * logic here, then assert it fires in the assembled machine there.
  */
 const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const sandbox_js_1 = require("./sandbox.js");
 /** Parse stdout as a hook JSON decision (pure, testable without a process). */
 function parseHookOutput(stdout) {
     const s = stdout.trim();
@@ -56,12 +61,50 @@ function decideHook(exitCode, json) {
     return { blocked, decision };
 }
 /**
- * Run a hook command, piping `input` as JSON to its stdin, and report the exit
- * code + parsed decision. Synchronous (so it can be used inside an eval's
- * `measure` too). `command` is run through a shell, so the same command string a
- * plugin ships (with args / env refs) works verbatim.
+ * The hook-run orchestration with injectable spawn seams: pick direct vs.
+ * confined via the safe-by-default policy (`decideSandbox`), then parse the exit
+ * code + stdout into a normalized decision. Exported so all three branches
+ * (direct / sandbox / refuse) are unit-tested with fake spawners — no real
+ * bwrap. `runHook` is this with the real seams.
  */
-function runHook(command, input, opts = {}) {
+function runHookWith(command, input, opts, deps) {
+    // Confinement follows provenance: a trusted hook (the default) runs directly;
+    // marking a hook untrusted defaults it to "auto" (confine-or-refuse), so
+    // foreign code is never run unconfined by accident. An explicit `sandbox`
+    // overrides the default either way. The trust fed to decideSandbox stays
+    // `false` at this tier — a raw command has no provenance, so an explicit
+    // "auto"/"strict" here is always a request to *confine*, not "trusted→direct".
+    // recordEgress needs the netns recorder, so it forces confinement too.
+    const mode = opts.sandbox ??
+        (opts.trusted === false || opts.recordEgress ? "auto" : false);
+    const decision = (0, sandbox_js_1.decideSandbox)({
+        trusted: false,
+        mode,
+        available: deps.available,
+    });
+    if (decision.action === "throw")
+        throw new Error(decision.reason);
+    const res = decision.action === "sandbox"
+        ? deps.sandboxed(command, input, opts)
+        : deps.direct(command, input, opts);
+    const exitCode = res.status ?? (res.signal ? 1 : 0);
+    const stdout = res.stdout ?? "";
+    const stderr = res.stderr ?? "";
+    const json = parseHookOutput(stdout);
+    const { blocked, decision: dec } = decideHook(exitCode, json);
+    return {
+        exitCode,
+        stdout,
+        stderr,
+        json,
+        blocked,
+        egress: res.egress ?? [],
+        filesWritten: res.filesWritten ?? [],
+        decision: dec,
+    };
+}
+/** Run the hook command directly through a shell (the default, unconfined). */
+function directSpawn(command, input, opts) {
     const res = (0, node_child_process_1.spawnSync)(command, {
         shell: true,
         cwd: opts.cwd,
@@ -70,11 +113,146 @@ function runHook(command, input, opts = {}) {
         encoding: "utf-8",
         timeout: opts.timeoutMs ?? 10000,
     });
-    const exitCode = res.status ?? (res.signal ? 1 : 0);
-    const stdout = res.stdout ?? "";
-    const stderr = res.stderr ?? "";
-    const json = parseHookOutput(stdout);
-    const { blocked, decision } = decideHook(exitCode, json);
-    return { exitCode, stdout, stderr, json, blocked, decision };
+    return {
+        status: res.status,
+        signal: res.signal,
+        stdout: res.stdout ?? "",
+        stderr: res.stderr ?? "",
+    };
+}
+/* v8 ignore start -- spawns real bwrap; exercised by the bwrap-gated integration
+   test (skipped without bwrap). The decision logic is runHookWith (unit-tested
+   with fakes); the confinement argv is bwrapArgs/setenvArgs and the egress log
+   parse is parseEgressLog (all unit-tested). */
+// When recordEgress is on: co-launch the recorder on loopback, point HTTP(S)_PROXY
+// at it, run the hook, then stop it. Paths come in via env (no shell escaping).
+const EGRESS_WRAPPER = [
+    'node "$VIG_EGRESS_ENTRY" "$VIG_EGRESS_LOG" "$VIG_EGRESS_PORT" &',
+    "EPID=$!",
+    "i=0",
+    'while [ ! -s "$VIG_EGRESS_PORT" ] && [ "$i" -lt 100 ]; do sleep 0.05; i=$((i+1)); done',
+    'export HTTP_PROXY="http://127.0.0.1:$(cat "$VIG_EGRESS_PORT")"',
+    'export HTTPS_PROXY="$HTTP_PROXY" http_proxy="$HTTP_PROXY" https_proxy="$HTTP_PROXY"',
+    // Node's fetch (undici) ignores the proxy env unless this is set — without it a
+    // hook that uses fetch() (e.g. an update check) would bypass the recorder.
+    "export NODE_USE_ENV_PROXY=1",
+    'sh -c "$VIG_HOOK_CMD"',
+    "code=$?",
+    'kill "$EPID" 2>/dev/null',
+    'exit "$code"',
+].join("\n");
+function egressProxyEntry() {
+    return ([
+        (0, node_path_1.join)(__dirname, "egress-proxy.js"),
+        (0, node_path_1.join)(__dirname, "..", "dist", "egress-proxy.js"),
+    ].find((p) => (0, node_fs_1.existsSync)(p)) ?? (0, node_path_1.join)(__dirname, "egress-proxy.js"));
+}
+/** Map every file under `dir` to a content signature (size:mtime), recursively. */
+function snapshotTree(dir) {
+    const out = {};
+    const walk = (d, rel) => {
+        for (const name of (0, node_fs_1.readdirSync)(d)) {
+            const full = (0, node_path_1.join)(d, name);
+            const r = rel ? `${rel}/${name}` : name;
+            const st = (0, node_fs_1.statSync)(full);
+            if (st.isDirectory())
+                walk(full, r);
+            else
+                out[r] = `${String(st.size)}:${String(st.mtimeMs)}`;
+        }
+    };
+    try {
+        walk(dir, "");
+    }
+    catch {
+        /* dir removed mid-walk — best effort */
+    }
+    return out;
+}
+function sandboxedSpawn(command, input, opts) {
+    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-hook-sbx-"));
+    const home = (0, node_path_1.join)(ioDir, "home");
+    (0, node_fs_1.mkdirSync)(home);
+    // The hook's confined writable work dir: the caller's cwd if given, else a
+    // dedicated `work/` under the IO dir (kept separate from the egress log/home so
+    // those don't pollute the filesWritten diff).
+    const work = opts.cwd ?? (0, node_path_1.join)(ioDir, "work");
+    (0, node_fs_1.mkdirSync)(work, { recursive: true });
+    try {
+        const baseArgs = [
+            ...(0, sandbox_js_1.bwrapArgs)({
+                cwd: work,
+                ioDir,
+                home,
+                path: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+            }),
+            ...(0, sandbox_js_1.setenvArgs)(opts.env ?? {}),
+        ];
+        const spawnOpts = {
+            cwd: work,
+            env: process.env,
+            input: JSON.stringify(input),
+            encoding: "utf-8",
+            timeout: opts.timeoutMs ?? 10000,
+        };
+        const before = snapshotTree(work);
+        let res;
+        let egress = [];
+        if (opts.recordEgress) {
+            const egressLog = (0, node_path_1.join)(ioDir, "egress.ndjson");
+            const portFile = (0, node_path_1.join)(ioDir, "egress.port");
+            (0, node_fs_1.writeFileSync)(egressLog, "");
+            res = (0, node_child_process_1.spawnSync)("bwrap", [
+                ...baseArgs,
+                "--setenv",
+                "VIG_EGRESS_ENTRY",
+                egressProxyEntry(),
+                "--setenv",
+                "VIG_EGRESS_LOG",
+                egressLog,
+                "--setenv",
+                "VIG_EGRESS_PORT",
+                portFile,
+                "--setenv",
+                "VIG_HOOK_CMD",
+                command,
+                "sh",
+                "-c",
+                EGRESS_WRAPPER,
+            ], spawnOpts);
+            egress = (0, sandbox_js_1.parseEgressLog)((0, node_fs_1.existsSync)(egressLog) ? (0, node_fs_1.readFileSync)(egressLog, "utf-8") : "");
+        }
+        else {
+            res = (0, node_child_process_1.spawnSync)("bwrap", [...baseArgs, "sh", "-c", command], spawnOpts);
+        }
+        return {
+            status: res.status,
+            signal: res.signal,
+            stdout: res.stdout ?? "",
+            stderr: res.stderr ?? "",
+            egress,
+            filesWritten: (0, sandbox_js_1.diffTrees)(before, snapshotTree(work)),
+        };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(ioDir, { recursive: true, force: true });
+    }
+}
+const REAL_DEPS = {
+    available: (0, sandbox_js_1.sandboxAvailable)(),
+    direct: directSpawn,
+    sandboxed: sandboxedSpawn,
+};
+/* v8 ignore stop */
+/**
+ * Run a hook command, piping `input` as JSON to its stdin, and report the exit
+ * code + parsed decision. Synchronous (so it can be used inside an eval's
+ * `measure` too). `command` is run through a shell, so the same command string a
+ * plugin ships (with args / env refs) works verbatim. Mark a hook you didn't
+ * write with `trusted: false` and it is confined by default (or pass `sandbox:
+ * "auto"` directly) — see {@link RunHookOptions.trusted}.
+ */
+function runHook(command, input, opts = {}) {
+    return runHookWith(command, input, opts, REAL_DEPS);
 }
 //# sourceMappingURL=run-hook.js.map

package/dist/sandbox.d.ts

@@ -8,10 +8,16 @@ import { type ModelTurn, type ModelRequest } from "./mock-model.js";
  */
 export type SandboxMode = "auto" | "strict" | false;
 /**
- * Whether bubblewrap is available to confine untrusted code. **Linux only** —
- * bubblewrap is a Linux tool, so this is always `false` on macOS / Windows,
- * where confined execution isn't supported and untrusted code must instead be
- * run via `sandbox: false` (trusting the outer container) or skipped.
+ * Whether this environment can ACTUALLY confine untrusted code under bubblewrap.
+ * **Linux only.** Critically, `bwrap --version` succeeding is NOT enough: many CI
+ * runners and hardened hosts ship bubblewrap but disable the **unprivileged user
+ * namespaces** it depends on, so a real confined exec fails even though the binary
+ * is present. We probe that real capability — a throwaway `bwrap --unshare-all …
+ * true` — and cache it, so we never *claim* confinement we can't deliver.
+ * `decideSandbox` then correctly refuses untrusted code in such an environment
+ * (rather than running it in a "sandbox" that doesn't actually sandbox), and the
+ * sandbox-gated tests skip instead of failing. The result is cached because the
+ * probe spawns a process and the answer can't change within a run.
  */
 export declare function sandboxAvailable(): boolean;
 /**
@@ -59,8 +65,33 @@ export declare function bwrapArgs(opts: {
     home: string;
     path: string;
 }): string[];
+/**
+ * `--setenv K V` pairs to add back specific variables after `--clearenv` — e.g.
+ * a hook's configured env (the `GUARD=path` a plugin's command relies on), which
+ * `bwrapArgs`' `--clearenv` would otherwise drop. Pure, so it's unit-tested.
+ */
+export declare function setenvArgs(env: Record<string, string>): string[];
 /** Parse the in-sandbox mock's ndjson request log into {@link ModelRequest}s. */
 export declare function parseRequestLog(ndjson: string): ModelRequest[];
+/** A network egress attempt a confined hook made — recorded, then blocked. */
+export interface EgressAttempt {
+    readonly host: string;
+    readonly port: number;
+    /** ms epoch when the attempt was recorded. */
+    readonly ts: number;
+}
+/**
+ * Parse the egress recorder's ndjson log into {@link EgressAttempt}s. Pure, so
+ * the record-shape and the malformed-line tolerance are unit-tested without a
+ * sandbox. A line missing host/port is skipped (a partially-flushed final line).
+ */
+export declare function parseEgressLog(ndjson: string): EgressAttempt[];
+/**
+ * The files in `after` that are new or changed vs `before` — i.e. what a confined
+ * run wrote to its work dir. Each tree maps a relative path to a content
+ * signature (size + mtime). Pure, so the diff is unit-tested without a sandbox.
+ */
+export declare function diffTrees(before: Readonly<Record<string, string>>, after: Readonly<Record<string, string>>): string[];
 /** The raw output of a sandboxed run: exit code, captured stdout, and requests. */
 export interface SandboxRunOut {
     readonly code: number;

package/dist/sandbox.js

@@ -4,7 +4,10 @@ exports.sandboxAvailable = sandboxAvailable;
 exports.specTrusted = specTrusted;
 exports.decideSandbox = decideSandbox;
 exports.bwrapArgs = bwrapArgs;
+exports.setenvArgs = setenvArgs;
 exports.parseRequestLog = parseRequestLog;
+exports.parseEgressLog = parseEgressLog;
+exports.diffTrees = diffTrees;
 exports.runSandboxed = runSandboxed;
 /**
  * vigiles — safe-by-default confinement for executing untrusted harness code.
@@ -32,18 +35,35 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+let cachedAvailable;
 /**
- * Whether bubblewrap is available to confine untrusted code. **Linux only** —
- * bubblewrap is a Linux tool, so this is always `false` on macOS / Windows,
- * where confined execution isn't supported and untrusted code must instead be
- * run via `sandbox: false` (trusting the outer container) or skipped.
+ * Whether this environment can ACTUALLY confine untrusted code under bubblewrap.
+ * **Linux only.** Critically, `bwrap --version` succeeding is NOT enough: many CI
+ * runners and hardened hosts ship bubblewrap but disable the **unprivileged user
+ * namespaces** it depends on, so a real confined exec fails even though the binary
+ * is present. We probe that real capability — a throwaway `bwrap --unshare-all …
+ * true` — and cache it, so we never *claim* confinement we can't deliver.
+ * `decideSandbox` then correctly refuses untrusted code in such an environment
+ * (rather than running it in a "sandbox" that doesn't actually sandbox), and the
+ * sandbox-gated tests skip instead of failing. The result is cached because the
+ * probe spawns a process and the answer can't change within a run.
  */
 function sandboxAvailable() {
+    if (cachedAvailable === undefined)
+        cachedAvailable = probeSandbox();
+    return cachedAvailable;
+}
+function probeSandbox() {
     /* v8 ignore next -- non-Linux has no bwrap; CI/coverage runs on Linux */
     if (process.platform !== "linux")
         return false;
     try {
-        return (0, node_child_process_1.spawnSync)("bwrap", ["--version"], { stdio: "ignore" }).status === 0;
+        // The capability that fails when user namespaces are disabled is the
+        // namespace creation itself (`--unshare-all`), so probe exactly that.
+        return ((0, node_child_process_1.spawnSync)("bwrap", ["--unshare-all", "--ro-bind", "/", "/", "true"], {
+            stdio: "ignore",
+            timeout: 10_000,
+        }).status === 0);
     }
     catch {
         /* v8 ignore next -- defensive: spawnSync only throws on a fork failure */
@@ -138,6 +158,17 @@ function bwrapArgs(opts) {
         "--new-session",
     ];
 }
+/**
+ * `--setenv K V` pairs to add back specific variables after `--clearenv` — e.g.
+ * a hook's configured env (the `GUARD=path` a plugin's command relies on), which
+ * `bwrapArgs`' `--clearenv` would otherwise drop. Pure, so it's unit-tested.
+ */
+function setenvArgs(env) {
+    const out = [];
+    for (const [k, v] of Object.entries(env))
+        out.push("--setenv", k, v);
+    return out;
+}
 /** Parse the in-sandbox mock's ndjson request log into {@link ModelRequest}s. */
 function parseRequestLog(ndjson) {
     const out = [];
@@ -153,6 +184,41 @@ function parseRequestLog(ndjson) {
     }
     return out;
 }
+/**
+ * Parse the egress recorder's ndjson log into {@link EgressAttempt}s. Pure, so
+ * the record-shape and the malformed-line tolerance are unit-tested without a
+ * sandbox. A line missing host/port is skipped (a partially-flushed final line).
+ */
+function parseEgressLog(ndjson) {
+    const out = [];
+    for (const line of ndjson.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const o = JSON.parse(line);
+            if (typeof o.host === "string" && typeof o.port === "number") {
+                out.push({ host: o.host, port: o.port, ts: Number(o.ts) || 0 });
+            }
+        }
+        catch {
+            /* a partially-written final line — skip */
+        }
+    }
+    return out;
+}
+/**
+ * The files in `after` that are new or changed vs `before` — i.e. what a confined
+ * run wrote to its work dir. Each tree maps a relative path to a content
+ * signature (size + mtime). Pure, so the diff is unit-tested without a sandbox.
+ */
+function diffTrees(before, after) {
+    const out = [];
+    for (const [path, sig] of Object.entries(after)) {
+        if (before[path] !== sig)
+            out.push(path);
+    }
+    return out.sort();
+}
 /**
  * Co-launch the scripted mock and `claude` inside ONE bubblewrap network
  * namespace: the mock serves on the sandbox's loopback (reachable), egress is

package/dist/testing.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `vigiles/testing` — Pillar 2 entry point: the **harness-testing** API. Re-exports
+ * the three tiers — `runHook` (unit), `runHarnessTest` (deterministic), `runEval`
+ * (eval) — plus the runner-agnostic predicates/assertions. Kept deliberately
+ * separate from `vigiles/claude-code` so this surface can stay harness-agnostic as
+ * more harnesses are added. Granular paths (`vigiles/run-hook`, etc.) still work.
+ */
+export * from "./run-hook.js";
+export * from "./harness-test.js";
+export * from "./eval.js";
+export * from "./harness-assert.js";
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `vigiles/testing` — Pillar 2 entry point: the **harness-testing** API. Re-exports
+ * the three tiers — `runHook` (unit), `runHarnessTest` (deterministic), `runEval`
+ * (eval) — plus the runner-agnostic predicates/assertions. Kept deliberately
+ * separate from `vigiles/claude-code` so this surface can stay harness-agnostic as
+ * more harnesses are added. Granular paths (`vigiles/run-hook`, etc.) still work.
+ */
+__exportStar(require("./run-hook.js"), exports);
+__exportStar(require("./harness-test.js"), exports);
+__exportStar(require("./eval.js"), exports);
+__exportStar(require("./harness-assert.js"), exports);
+//# sourceMappingURL=testing.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Compile .spec.ts files to instruction files (CLAUDE.md, AGENTS.md) with linter cross-referencing",
   "bin": {
     "vigiles": "dist/cli.js"
@@ -9,6 +9,9 @@
   "types": "./dist/spec.d.ts",
   "exports": {
     ".": "./dist/spec.js",
+    "./linting": "./dist/linting.js",
+    "./testing": "./dist/testing.js",
+    "./claude-code": "./dist/claude-code.js",
     "./spec": "./dist/spec.js",
     "./compile": "./dist/compile.js",
     "./linters": "./dist/linters.js",
@@ -51,7 +54,8 @@
     "test:eval": "npm run build && node dist/cli.js eval",
     "test:vitest": "npm run build && vitest run --project runners",
     "test:jest": "npm run build && jest",
-    "test:types": "npm run build && tsc --noEmit -p test/types/tsconfig.json"
+    "test:types": "npm run build && tsc --noEmit -p test/types/tsconfig.json",
+    "demo:plugin": "npm run build && node examples/plugin-test-demo.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",