vigiles 21.0.2 → 22.0.0

package/dist/cli.d.ts

@@ -9,5 +9,6 @@
  * `self-command-refs.test.ts` did not catch it because it guards against refs to
  * REMOVED commands, not against a list that merely stops growing.
  */
-export {};
+/** Reason the most recent `loadSpec()` returned null, or null if it succeeded. */
+export declare function specLoadFailureReason(): string | null;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -11,8 +11,10 @@
  * REMOVED commands, not against a list that merely stops growing.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.specLoadFailureReason = specLoadFailureReason;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
 const glob_1 = require("glob");
 const generate_types_js_1 = require("./core/generate-types.js");
 const generate_harness_js_1 = require("./core/generate-harness.js");
@@ -96,54 +98,168 @@ function findSpecs(pattern) {
         cwd: process.cwd(),
     });
 }
-async function loadSpec(specPath) {
-    const fullPath = (0, node_path_1.resolve)(process.cwd(), specPath);
-    // Try multiple dist/ path strategies
-    const candidates = [];
-    // src/ → dist/ mapping (e.g., src/CLAUDE.md.spec.ts → dist/CLAUDE.md.spec.js)
-    if (fullPath.includes("/src/")) {
-        candidates.push(fullPath.replace(/\/src\//, "/dist/").replace(/\.ts$/, ".js"));
-    }
-    // Root-level spec → dist/ (e.g., CLAUDE.md.spec.ts → dist/CLAUDE.md.spec.js)
-    const dir = fullPath.substring(0, fullPath.lastIndexOf("/"));
-    const base = fullPath.substring(fullPath.lastIndexOf("/") + 1);
-    candidates.push((0, node_path_1.resolve)(dir, "dist", base.replace(/\.ts$/, ".js")));
-    // examples/ → dist/examples/ mapping
-    candidates.push(fullPath
-        .replace(/\.ts$/, ".js")
-        .replace(process.cwd(), (0, node_path_1.resolve)(process.cwd(), "dist")));
-    for (const distPath of candidates) {
-        if ((0, node_fs_1.existsSync)(distPath)) {
+/**
+ * Why the last `loadSpec()` returned null.
+ *
+ * Kept as module state rather than a widened return type: `loadSpec` has six
+ * call sites and only one of them reports to a human.
+ */
+let lastSpecLoadFailure = null;
+/** Reason the most recent `loadSpec()` returned null, or null if it succeeded. */
+function specLoadFailureReason() {
+    return lastSpecLoadFailure;
+}
+/**
+ * How long one spec may take to evaluate before the host is killed.
+ *
+ * Overridable because 15s is a guess that fits the specs we have seen, not a
+ * law; a repo with genuinely slow specs should be able to raise it rather than
+ * discover the number by hitting it.
+ */
+const SPEC_DEADLINE_MS = Number(process.env.VIGILES_SPEC_TIMEOUT_MS) || 15_000;
+let host = null;
+/** The compiled host entry, beside this file in `dist/`. */
+function hostEntry() {
+    return (0, node_path_1.resolve)(__dirname, "spec-host.mjs");
+}
+function startHost() {
+    const child = (0, node_child_process_1.spawn)(process.execPath, [hostEntry()], {
+        cwd: process.cwd(),
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const h = { child, pending: new Map(), started: null, buffered: "" };
+    child.stdout.setEncoding("utf-8");
+    child.stdout.on("data", (chunk) => {
+        h.buffered += chunk;
+        let nl;
+        while ((nl = h.buffered.indexOf("\n")) >= 0) {
+            const line = h.buffered.slice(0, nl).trim();
+            h.buffered = h.buffered.slice(nl + 1);
+            if (!line)
+                continue;
+            let reply;
             try {
-                const mod = (await import(distPath));
-                // CJS double-default: `{ default: { default: spec } }`.
-                const raw = mod.default;
-                if (raw && typeof raw === "object" && "default" in raw) {
-                    return raw.default;
-                }
-                return raw;
+                reply = JSON.parse(line);
             }
             catch {
-                // Try next candidate
+                continue; // not ours; a spec writing to stdout cannot corrupt the stream
+            }
+            if ("phase" in reply) {
+                h.started = reply.path;
+                continue;
             }
+            const done = h.pending.get(reply.path);
+            h.pending.delete(reply.path);
+            done?.(reply);
         }
+    });
+    // Anything the child says on stderr is the spec's own noise; keep it out of
+    // our stdout so `--json` consumers are not corrupted, but do not lose it.
+    child.stderr.setEncoding("utf-8");
+    child.stderr.on("data", (chunk) => process.stderr.write(chunk));
+    // 🔴 Unreferenced, or the CLI never exits. A piped child and its three
+    // streams each hold the event loop open, so `compile` finished its work and
+    // then hung forever waiting on a host that had nothing left to say. The
+    // in-flight deadline timer keeps the loop alive while a request is pending,
+    // which is exactly as long as we need it.
+    // ONE exit listener per host, not one per request: with concurrent callers the
+    // per-request version added a listener each time and Node warned at eleven.
+    // It fails every outstanding request, because a dead host answers none of them.
+    child.once("exit", () => {
+        const waiting = [...h.pending.values()];
+        h.pending.clear();
+        for (const settle of waiting)
+            settle("died");
+    });
+    // The stdio types are Readable/Writable, which do not declare `unref` — the
+    // objects are pipes and do have it. Optional-called so this stays correct if
+    // a platform ever hands back a stream that genuinely lacks it.
+    const unref = (s) => s?.unref?.();
+    child.unref();
+    unref(child.stdin);
+    unref(child.stdout);
+    unref(child.stderr);
+    return h;
+}
+/**
+ * Kill the host and forget it; the next request starts a fresh one.
+ *
+ * Outstanding requests are failed rather than dropped: a killed host will never
+ * answer them, and a promise nobody settles is a hang wearing a different hat.
+ */
+function dropHost() {
+    if (!host)
+        return;
+    const dying = host;
+    host = null;
+    const waiting = [...dying.pending.values()];
+    dying.pending.clear();
+    dying.child.kill("SIGKILL");
+    for (const settle of waiting)
+        settle("died");
+}
+process.on("exit", dropHost);
+/**
+ * Load one spec in the spec host.
+ *
+ * 🔴 **Why a child process rather than `import()` here.** A module evaluation
+ * cannot be cancelled once started — `Promise.race` hands control back but the
+ * evaluation keeps running and holds the event loop — so an in-process loader
+ * gives a stalled spec an unbounded hang in `compile`, `test` and `audit`. It
+ * also cannot tell whether a failed spec already ran (Node reports
+ * `ERR_MODULE_NOT_FOUND` and `SyntaxError` both before and during evaluation),
+ * which is what made the previous two-loader arrangement unfixable rather than
+ * merely buggy: it had to guess whether re-running was safe.
+ *
+ * The host is spawned with `process.execPath` — never `npx` — so nothing is
+ * fetched and nothing needs installing.
+ */
+async function loadSpec(specPath) {
+    const fullPath = (0, node_path_1.resolve)(process.cwd(), specPath);
+    lastSpecLoadFailure = null;
+    if (!(0, node_fs_1.existsSync)(fullPath)) {
+        lastSpecLoadFailure = `no such file: ${specPath}`;
+        return null;
     }
-    // Try loading .ts directly via tsx
-    try {
-        const { execSync } = require("node:child_process");
-        // Handle ESM/CJS double-default: m.default may itself have a .default
-        const script = `import(${JSON.stringify(fullPath)}).then(m => { const d = m.default?.default ?? m.default; console.log(JSON.stringify(d)); })`;
-        const output = execSync(`npx tsx -e '${script.replace(/'/g, "'\\''")}'`, {
-            encoding: "utf-8",
-            cwd: process.cwd(),
-            stdio: ["pipe", "pipe", "pipe"],
-            timeout: 15000,
-        });
-        return JSON.parse(output.trim());
+    host ??= startHost();
+    const h = host;
+    const reply = await new Promise((done) => {
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            h.pending.delete(fullPath);
+            done(r);
+        };
+        const timer = setTimeout(() => {
+            finish("timeout");
+        }, SPEC_DEADLINE_MS);
+        h.pending.set(fullPath, finish);
+        h.child.stdin.write(JSON.stringify({ path: fullPath }) + "\n");
+    });
+    if (reply === "timeout") {
+        // The host's last `start` names the spec that stalled. Without it a hang
+        // produced N identical failures and no culprit.
+        const culprit = h.started ?? fullPath;
+        dropHost();
+        lastSpecLoadFailure =
+            `evaluating ${(0, node_path_1.relative)(process.cwd(), culprit)} exceeded ` +
+                `${SPEC_DEADLINE_MS}ms and was killed. Set VIGILES_SPEC_TIMEOUT_MS to ` +
+                `raise the limit, or look for a top-level await that never settles.`;
+        return null;
     }
-    catch {
+    if (reply === "died") {
+        dropHost();
+        lastSpecLoadFailure = "the spec host exited unexpectedly.";
+        return null;
+    }
+    if (!("ok" in reply) || !reply.ok) {
+        lastSpecLoadFailure = `the spec did not load. ${"error" in reply ? reply.error : "no reason given"}`;
         return null;
     }
+    return reply.value;
 }
 // ---------------------------------------------------------------------------
 // Output helpers
@@ -357,7 +473,7 @@ async function compile(specPaths, config, opts = {}) {
         const spec = await loadSpec(specPath);
         if (!spec) {
             console.log(`\n✗ ${specPath} — failed to load`);
-            console.log(`  Ensure the spec is compiled: run \`npm run build\` first.`);
+            console.log(`  ${specLoadFailureReason() ?? "reason unavailable"}`);
             allValid = false;
             continue;
         }

package/dist/spec-hooks.d.mts

@@ -0,0 +1,35 @@
+type ResolveContext = {
+    parentURL?: string;
+    conditions: string[];
+};
+type Resolved = {
+    url: string;
+    format?: string | null;
+    shortCircuit?: boolean;
+};
+type NextResolve = (specifier: string, context: ResolveContext) => Resolved | Promise<Resolved>;
+type LoadContext = {
+    format?: string | null;
+    conditions: string[];
+};
+type Loaded = {
+    format: string;
+    source?: string | ArrayBuffer;
+    shortCircuit?: boolean;
+};
+type NextLoad = (url: string, context: LoadContext) => Loaded | Promise<Loaded>;
+/**
+ * `./x.js` → `./x.ts` when the sibling exists.
+ *
+ * This is the TypeScript ESM convention (`tsc` under `nodenext` requires the
+ * `.js` extension in the source), which `tsx` implements and native Node does
+ * not. It is the ONE divergence that matters in practice: this repository's own
+ * dogfood specs import `src/core/spec.js`, a file that does not exist on disk.
+ * Attempted only AFTER normal resolution fails, so it can never shadow a real
+ * `.js` file.
+ */
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<Resolved>;
+/** Transpile `.ts`/`.mts` with the TypeScript this package already ships. */
+export declare function load(url: string, context: LoadContext, nextLoad: NextLoad): Promise<Loaded>;
+export {};
+//# sourceMappingURL=spec-hooks.d.mts.map

package/dist/spec-hooks.mjs

@@ -0,0 +1,68 @@
+/**
+ * Module customization hooks for the spec host — vigiles' OWN loader for `.ts`
+ * specs, replacing "whichever loader happens to be installed".
+ *
+ * Why vigiles owns this rather than shelling to `tsx`:
+ *
+ *   - **No install, no network.** `typescript` is already a runtime dependency
+ *     of this package (`dependencies`, and `core/compile-generator.ts` uses it),
+ *     so `ts.transpileModule` costs nothing extra. The bug that started this
+ *     work was a consuming repo without `tsx`, where `npx tsx` went to the
+ *     registry and every one of 50 specs blew a 15s budget.
+ *   - **One resolution contract.** Before this, a spec's module resolution
+ *     depended on the user's Node version and on which loader won — so a spec
+ *     could load locally and fail in CI under different rules. A tool that
+ *     audits other tools for that kind of quiet divergence should not have it.
+ *
+ * Scope is deliberately small and documented as such: `.ts`/`.mts` sources, the
+ * `./x.js` → `./x.ts` specifier rewrite, and bare specifiers. NOT tsconfig
+ * `paths`, JSX, or decorator configuration — specs are configuration modules,
+ * not applications.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+const TS_SOURCE = /\.m?ts$/;
+/**
+ * `./x.js` → `./x.ts` when the sibling exists.
+ *
+ * This is the TypeScript ESM convention (`tsc` under `nodenext` requires the
+ * `.js` extension in the source), which `tsx` implements and native Node does
+ * not. It is the ONE divergence that matters in practice: this repository's own
+ * dogfood specs import `src/core/spec.js`, a file that does not exist on disk.
+ * Attempted only AFTER normal resolution fails, so it can never shadow a real
+ * `.js` file.
+ */
+export async function resolve(specifier, context, nextResolve) {
+    try {
+        return await nextResolve(specifier, context);
+    }
+    catch (err) {
+        if (specifier.endsWith(".js") && context.parentURL) {
+            const candidate = new URL(specifier.slice(0, -3) + ".ts", context.parentURL);
+            if (existsSync(fileURLToPath(candidate))) {
+                return { url: candidate.href, format: "module", shortCircuit: true };
+            }
+        }
+        throw err;
+    }
+}
+/** Transpile `.ts`/`.mts` with the TypeScript this package already ships. */
+export async function load(url, context, nextLoad) {
+    if (!TS_SOURCE.test(new URL(url).pathname))
+        return nextLoad(url, context);
+    const fileName = fileURLToPath(url);
+    const { outputText } = ts.transpileModule(readFileSync(fileName, "utf-8"), {
+        fileName,
+        compilerOptions: {
+            module: ts.ModuleKind.ESNext,
+            target: ts.ScriptTarget.ES2022,
+            // Erasing types is the whole job; anything that changes SEMANTICS is not
+            // ours to decide for a spec.
+            verbatimModuleSyntax: false,
+            isolatedModules: true,
+        },
+    });
+    return { format: "module", source: outputText, shortCircuit: true };
+}
+//# sourceMappingURL=spec-hooks.mjs.map

package/dist/spec-host.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=spec-host.d.mts.map

package/dist/spec-host.mjs

@@ -0,0 +1,79 @@
+/**
+ * The spec host — a child process that loads specs and streams results as NDJSON.
+ *
+ * ONE host per CLI command, not one per spec: Node startup and the TypeScript
+ * load are paid once, then each spec costs a transpile.
+ *
+ * 🔴 **Why a child process at all, when `import()` works in-process.** Because a
+ * module evaluation cannot be cancelled once started. `Promise.race` returns
+ * control to the caller but the evaluation keeps running and holds the event
+ * loop, so a spec that stalls at top level hangs `compile`, `test` and `audit`
+ * with no bound. A child can be killed. That is the entire argument, and it is
+ * why the in-process loader this replaced could not be repaired: it also had to
+ * answer "did the module body already run?" to know whether re-running was
+ * safe, and Node does not expose that bit — `ERR_MODULE_NOT_FOUND` and
+ * `SyntaxError` each occur both before and during evaluation.
+ *
+ * Protocol, one JSON object per line each way:
+ *   in   {"path":"<abs path to spec>"}
+ *   out  {"path":"…","phase":"start"}          — emitted BEFORE evaluation
+ *   out  {"path":"…","ok":true,"value":{…}}
+ *   out  {"path":"…","ok":false,"error":"…"}
+ *
+ * The `start` line is what makes a hang diagnosable: when the parent's deadline
+ * fires, the last `start` without a result NAMES the spec that stalled. Before
+ * this, a stalled load produced N identical failures and no culprit.
+ *
+ * Values cross as JSON, which is not a new constraint — the previous `npx tsx`
+ * path already did `JSON.stringify` in the child and `JSON.parse` in the parent,
+ * so every spec that has ever loaded survived this round trip. Spec types carry
+ * no functions; TypeScript is the authoring layer, the value is data.
+ */
+import { register } from "node:module";
+import { pathToFileURL } from "node:url";
+register(new URL("./spec-hooks.mjs", import.meta.url));
+function say(line) {
+    process.stdout.write(JSON.stringify(line) + "\n");
+}
+async function loadOne(path) {
+    say({ path, phase: "start" });
+    try {
+        const mod = (await import(pathToFileURL(path).href));
+        // CJS interop can nest the default one level deeper.
+        const raw = mod.default;
+        const value = raw && typeof raw === "object" && "default" in raw ? raw.default : raw;
+        if (value === undefined) {
+            say({ path, ok: false, error: "the spec has no default export." });
+            return;
+        }
+        say({ path, ok: true, value });
+    }
+    catch (err) {
+        say({
+            path,
+            ok: false,
+            error: err instanceof Error ? (err.stack ?? err.message) : String(err),
+        });
+    }
+}
+// Requests are serialised: a spec may depend on module state a previous one set
+// up, and interleaving would make a hang impossible to attribute.
+let queue = Promise.resolve();
+let buffered = "";
+process.stdin.setEncoding("utf-8");
+process.stdin.on("data", (chunk) => {
+    buffered += chunk;
+    let nl;
+    while ((nl = buffered.indexOf("\n")) >= 0) {
+        const line = buffered.slice(0, nl).trim();
+        buffered = buffered.slice(nl + 1);
+        if (!line)
+            continue;
+        const { path } = JSON.parse(line);
+        queue = queue.then(() => loadOne(path));
+    }
+});
+process.stdin.on("end", () => {
+    queue.then(() => process.exit(0));
+});
+//# sourceMappingURL=spec-host.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "21.0.2",
+  "version": "22.0.0",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",