vigiles 26.0.1 → 26.2.0

package/dist/cli.js

@@ -66,7 +66,11 @@ const merge_conflict_js_1 = require("./core/merge-conflict.js");
 const hook_install_js_1 = require("./hook-install.js");
 const hook_providers_js_1 = require("./core/hook-providers.js");
 const toml_1 = require("@iarna/toml");
-const hash_js_1 = require("./core/hash.js");
+// The named-state STORE. Lifted out of this file so a TEST can seed a fact
+// through the SAME writer the runtime uses (`experimental_hookState`) — the
+// private path a stateful hook's test used to hard-code is what kept the hook
+// vocabulary experimental. Same move as `loadHook`, for the same reason.
+const hook_state_store_js_1 = require("./hook-state-store.js");
 const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
 const observe_js_1 = require("./observe.js");
 const effect_region_js_1 = require("./adapters/claude-code/effect-region.js");
@@ -137,10 +141,21 @@ let host = null;
 function hostEntry() {
     return (0, node_path_1.resolve)(__dirname, "spec-host.mjs");
 }
+/**
+ * This package's own root — `dist/`'s parent, since this file compiles to
+ * `dist/cli.js`. Handed to the host so its resolve hook can serve the spec's
+ * `vigiles/spec` import from OUR install (see `src/self-resolve.mts`), which is
+ * what lets a repo with no `node_modules/vigiles` — a Python or Rust repo has
+ * no `package.json` to install into at all — compile a spec.
+ */
+function selfRoot() {
+    return (0, node_path_1.resolve)(__dirname, "..");
+}
 function startHost() {
     const child = (0, node_child_process_1.spawn)(process.execPath, [hostEntry()], {
         cwd: process.cwd(),
         stdio: ["pipe", "pipe", "pipe"],
+        env: { ...process.env, VIGILES_SELF_ROOT: selfRoot() },
     });
     const h = { child, pending: new Map(), started: null, buffered: "" };
     child.stdout.setEncoding("utf-8");
@@ -2973,56 +2988,24 @@ async function setupPillar1(detected, targetValue, harnesses) {
     // user reviews the generated spec and runs `vigiles compile` themselves to
     // switch it to spec-managed (non-destructive by default; the compile is
     // byte-faithful, but it's the user's call to make, with a diff to review).
-    // And we only compile when `vigiles` actually resolves — a fresh repo hasn't
-    // run `npm install` yet, so compiling would just error; defer it with a clear
-    // next step instead of a scary stack-traceless "failed to load".
-    const canCompile = canResolveVigiles(cwd);
+    //
+    // There is no longer an "only if vigiles resolves" gate here. The spec host
+    // serves a spec's `vigiles/spec` import from the CLI's OWN install (the
+    // resolve hook in src/self-resolve.mts), so compiling needs no
+    // `node_modules/vigiles` in the user's repo — and a repo with no
+    // `package.json` at all (Python, Rust, Go) has no install to run.
     const initConfig = (0, validate_js_1.loadConfig)();
     const excludes = (0, exclude_js_1.excludeSet)(cwd, initConfig.exclude);
-    const specs = canCompile
-        ? findSpecs(excludes).filter((s) => {
-            const tf = (0, node_path_1.resolve)(cwd, s.replace(/\.spec\.ts$/, ""));
-            return !(0, node_fs_1.existsSync)(tf) || targetHasHash(tf);
-        })
-        : [];
+    const specs = findSpecs(excludes).filter((s) => {
+        const tf = (0, node_path_1.resolve)(cwd, s.replace(/\.spec\.ts$/, ""));
+        return !(0, node_fs_1.existsSync)(tf) || targetHasHash(tf);
+    });
     if (specs.length > 0) {
         console.log("\nCompiling specs...");
         await compile(specs, initConfig, excludes);
     }
-    else if (!canCompile) {
-        // Honest, project-type-aware guidance. A JS repo just needs `npm install`
-        // (init already added the devDep). A repo with NO package.json (Python, Rust,
-        // …) can't resolve the npm package at all, so point at the no-install paths
-        // instead of a misleading `npm install`.
-        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "package.json"))) {
-            console.log("\n  Skipping compile — run `npm install` (to fetch the vigiles dep just added), then `npx vigiles compile`.");
-        }
-        else {
-            console.log("\n  No package.json here, so the typed-spec compile isn't available yet.\n" +
-                "  • `npx vigiles lint` verifies your instruction files right now — no install needed.\n" +
-                "  • To spec-manage them, add a package.json first: `npm init -y && npm i -D vigiles`, then `npx vigiles compile`.");
-        }
-    }
     return { specTargets: targets, written, adopted };
 }
-/**
- * Whether `vigiles/spec` will resolve for a spec compiled from `cwd` — true when
- * vigiles is installed locally (`node_modules/vigiles`) or `cwd` IS the vigiles
- * package itself (the in-repo dogfood / a monorepo workspace). A fresh user repo
- * that hasn't run `npm install` yet returns false, so `init` defers the compile
- * instead of emitting a resolution error.
- */
-function canResolveVigiles(cwd) {
-    if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "node_modules", "vigiles")))
-        return true;
-    try {
-        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, "package.json"), "utf-8"));
-        return pkg.name === "vigiles";
-    }
-    catch {
-        return false;
-    }
-}
 /** Whether a harness binary (`claude`, `codex`) is on PATH. */
 function harnessBinaryPresent(bin) {
     try {
@@ -3278,22 +3261,16 @@ function printDetection(detected, harnesses) {
 function printSetupSummary(opts) {
     const { plan, strict, targets, adopted, written } = opts;
     const specPathsList = targets.map((t) => `${t}.spec.ts`);
-    // A repo with no package.json (Python/Rust/…) can't resolve the npm package,
-    // so the typed-spec compile path needs an install first — give honest steps.
-    const hasPkg = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), "package.json"));
     console.log("\n---\nSetup complete.\n");
-    // Next steps in DEPENDENCY order: install the dep first, then compile (which
-    // needs it), then the optional hardening / test / CI steps.
+    // Next steps in the order a reader should do them. `npm install` is NOT a
+    // prerequisite of `compile` any more (the spec host resolves `vigiles/spec`
+    // from the CLI's own install) — it is listed because we just declared the
+    // devDep, so installing it is what gives the editor the spec's types.
     const nextSteps = [];
     if (written.includes("package.json")) {
         nextSteps.push("Run `npm install` to fetch the vigiles dev dependency");
     }
-    if (adopted.length > 0 && !hasPkg) {
-        // Non-JS repo: compile needs a local install. Point at the no-install verify
-        // path + how to enable specs, instead of a compile that would fail.
-        nextSteps.push(`Verify now with \`npx vigiles lint\` (no install). To spec-manage ${adopted.join(", ")}, add a package.json first (\`npm init -y && npm i -D vigiles\`), then \`npx vigiles compile\` and review the diff`);
-    }
-    else if (adopted.length > 0) {
+    if (adopted.length > 0) {
         // Adoption is NON-DESTRUCTIVE: the file is untouched until you compile, so
         // the diff to review is what compile WOULD produce (byte-faithful).
         nextSteps.push(`Run \`npx vigiles compile\` to put ${adopted.join(", ")} under spec management — it reproduces the file + adds an integrity header, so review the diff (\`vigiles eject\` reverses it)`);
@@ -5726,64 +5703,6 @@ async function compileProviders() {
 function hookStampPath(file) {
     return (0, node_path_1.resolve)(process.cwd(), ".vigiles/hooks", (0, node_path_1.basename)(file) + ".json");
 }
-/**
- * The directory a hook's recorded facts live in — the SCOPE of `state()`/`record()`.
- *
- * Derived from the hook's own location and never from anything the hook said, so
- * a key cannot address another owner's store: hooks shipped in the same directory
- * share their facts (the requirement — one hook records, another reads), a
- * vendored plugin's hooks get their own. The layout MIRRORS the hook's directory
- * rather than slugging it, which keeps it injective and lets a human debugging a
- * hook find the fact by walking the path they already know:
- *
- *   .claude/hooks/calendar-sync-record.hook.ts
- *     → .vigiles/state/.claude/hooks/calendar.synced.json
- *
- * A hook outside the project (an absolute path elsewhere) falls back to a hash of
- * its directory: still stable and still isolated, just not readable — which is the
- * right trade for a case that should not happen in a project's own harness.
- */
-function hookStateDir(file) {
-    const dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(process.cwd(), file));
-    const rel = (0, node_path_1.relative)(process.cwd(), dir);
-    const inside = rel !== "" && !rel.startsWith("..") && !(0, node_path_1.isAbsolute)(rel);
-    return (0, node_path_1.resolve)(process.cwd(), ".vigiles/state", inside ? rel : `external-${(0, hash_js_1.sha256short)(dir)}`);
-}
-/** Read one recorded fact for a hook, or `null` if it was never recorded. */
-function readHookState(file, key) {
-    try {
-        const raw = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(hookStateDir(file), key + ".json"), "utf-8");
-        const parsed = JSON.parse(raw);
-        return typeof parsed.value === "string" && typeof parsed.at === "string"
-            ? parsed
-            : null;
-    }
-    catch {
-        // Never recorded, unreadable, or corrupt — all "no fact", which `stateFact`
-        // turns into an infinite age, so the reading hook SPEAKS. Failing toward
-        // noise is the whole point; a store problem must never look like freshness.
-        return null;
-    }
-}
-/**
- * Record one fact. Atomic: written to a temp file in the same directory and
- * `rename()`d over, so a concurrent reader sees the whole old entry or the whole
- * new one — never one write's value with another's timestamp. Distinct keys are
- * distinct files and never interact at all.
- */
-function writeHookState(file, w) {
-    const dir = hookStateDir(file);
-    const target = (0, node_path_1.resolve)(dir, w.name + ".json");
-    const entry = {
-        value: w.value,
-        at: new Date().toISOString(),
-        by: (0, hook_install_js_1.normalizeHookRef)(file),
-    };
-    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
-    const tmp = `${target}.${String(process.pid)}.tmp`;
-    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(entry, null, 2) + "\n");
-    (0, node_fs_1.renameSync)(tmp, target);
-}
 /**
  * Perform the state writes a hook declared, after its output has been emitted.
  * A refused write (a hand-built record object with a key `record()` would have
@@ -5797,7 +5716,7 @@ function applyHookWrites(file, outcome) {
     }
     for (const w of ok) {
         try {
-            writeHookState(file, w);
+            (0, hook_state_store_js_1.writeHookState)(file, w);
         }
         catch (e) {
             console.error(`vigiles: could not record ${w.name} from ${file}: ${String(e)}`);
@@ -5856,7 +5775,19 @@ async function installHookFile(file, adapter, registeredProviders = []) {
     const injectable = adapter.hookProtocol?.injectableEvents ?? [];
     const matcher = (0, hook_program_js_1.hookRouting)(program).matcher;
     let warning;
-    if (adapter.name !== "claude-code") {
+    // A react on an event this harness does NOT inject can still call `notice()`,
+    // and that text would reach NOBODY (stderr at exit 0 is the debug log only).
+    // Say so at INSTALL time: a runtime warning would go to the same stderr the
+    // notice is stuck in, which is the defect one level up.
+    if (role === "react" && !injectable.includes(event)) {
+        warning =
+            `a react on "${event}" may emit notice(...), but ${adapter.name} does not ` +
+                `honor additionalContext for that event — the text would reach NOBODY ` +
+                `(stderr at exit 0 goes to the debug log, not the transcript, and the model ` +
+                `never sees it). Injectable here: ${injectable.join(", ") || "(none)"}. ` +
+                `Move the hook to one of those events, or use run() if you meant an action.`;
+    }
+    else if (adapter.name !== "claude-code") {
         if (role === "inject" && !injectable.includes(event)) {
             warning =
                 `this inject hook targets "${event}", which ${adapter.name} does not ` +
@@ -5975,7 +5906,7 @@ async function gatherHookContext(program, file) {
         isCI,
         // The namespace is bound HERE, from the hook's own path — core never sees
         // it, so no key a hook can spell reaches another owner's store.
-        readState: (key) => readHookState(file, key),
+        readState: (key) => (0, hook_state_store_js_1.readHookState)(file, key),
         now: Date.now(),
     }, registry);
 }
@@ -6311,6 +6242,27 @@ async function runHookProgramCommand(file) {
             const ctx = await gatherHookContext(program, file);
             warnIfPathUndecidable(event, projectRoot);
             const reaction = (0, hook_program_js_1.runReact)(program, event, ctx, projectRoot);
+            // A notice has to REACH someone. stderr at exit 0 goes to the debug log
+            // and nothing else (the host's docs are explicit: "Claude never sees it"),
+            // and a react always exits 0 because its type has no `deny` — so stderr
+            // alone delivered nowhere. Emit the same `additionalContext` shape the
+            // shipped refs/eval-lock nudges use, gated on the ACTIVE adapter's
+            // `injectableEvents` so this is per-harness fact, not a CC literal.
+            const injectable = (0, adapter_registry_js_1.resolveAdapter)(projectRoot ?? process.cwd()).hookProtocol
+                ?.injectableEvents ?? [];
+            const delivery = (0, hook_program_js_1.noticeDelivery)(reaction, program.on, injectable);
+            if (delivery.kind === "inject") {
+                process.stdout.write(JSON.stringify({
+                    hookSpecificOutput: {
+                        hookEventName: program.on,
+                        additionalContext: delivery.context,
+                    },
+                }) + "\n");
+            }
+            // The stderr copy STAYS, deliberately. It is what the debug log and every
+            // `runHook`-based probe already read, it costs nothing, and on an event
+            // this harness does not inject it is the only trace that exists at all.
+            // Removing it would break existing consumers to gain nothing.
             if (reaction.kind === "notice")
                 console.error(reaction.message);
             applyHookWrites(file, { kind: "reaction", reaction });

package/dist/core/bash-effects.d.ts

@@ -144,6 +144,28 @@ export declare const SHORT_TO_LONG: Readonly<Record<string, string>>;
 export declare const LONG_TO_SHORT: Readonly<Record<string, string>>;
 /** @internal — read by `bash-equivalents.ts` to generate shell-equivalent variants. */
 export declare const WRAPPER_HEADS: Set<string>;
+/**
+ * Resolve a wrapped command through one or more wrapper layers. Given a leaf's
+ * full normalized argv (`[head, ...args]`), returns the effective argv of the
+ * REAL command plus any `NAME=value` words an `env` wrapper consumed (so the
+ * caller can fold them into the leaf's assignment map). If the head is not a
+ * wrapper, or the wrapper has no following command, the argv is returned
+ * unchanged with an empty assignment set.
+ *
+ * @internal — the SINGLE answer to "which word is the real command head". Read
+ * by `bash-equivalents.ts` (to generate wrapper-prefixed spellings) and by
+ * `core/command-files.ts` (to find the interpreter behind a wrapper, so
+ * `env python3 guard` names its script). That second reader had its own idea of
+ * what a wrapper was — namely none — so it reported no script at all for the
+ * wrapped form, and a missing script that is never named is a hook that runs,
+ * exits 2, and is scored as a block. One list, or the next wrapper is missed in
+ * whichever copy nobody remembered.
+ */
+export declare function stripWrappers(argv: readonly string[]): {
+    argv: readonly string[];
+    envAssigns: Map<string, string | null>;
+    chdir: string | null;
+};
 /**
  * Extract every simple command as a {@link NormalizedLeaf} — the operation-level
  * twin of {@link leafCommands}. Same AST-backed structural coverage (a leaf nested

package/dist/core/bash-effects.js

@@ -28,6 +28,7 @@ exports.WRAPPER_HEADS = exports.LONG_TO_SHORT = exports.SHORT_TO_LONG = void 0;
 exports.classifyBashCommand = classifyBashCommand;
 exports.isReadOnlyBash = isReadOnlyBash;
 exports.leafCommands = leafCommands;
+exports.stripWrappers = stripWrappers;
 exports.leafCommandsNormalized = leafCommandsNormalized;
 exports.leafArgvSource = leafArgvSource;
 exports.commandWords = commandWords;
@@ -698,6 +699,15 @@ function splitAssignmentWord(word) {
  * caller can fold them into the leaf's assignment map). If the head is not a
  * wrapper, or the wrapper has no following command, the argv is returned
  * unchanged with an empty assignment set.
+ *
+ * @internal — the SINGLE answer to "which word is the real command head". Read
+ * by `bash-equivalents.ts` (to generate wrapper-prefixed spellings) and by
+ * `core/command-files.ts` (to find the interpreter behind a wrapper, so
+ * `env python3 guard` names its script). That second reader had its own idea of
+ * what a wrapper was — namely none — so it reported no script at all for the
+ * wrapped form, and a missing script that is never named is a hook that runs,
+ * exits 2, and is scored as a block. One list, or the next wrapper is missed in
+ * whichever copy nobody remembered.
  */
 function stripWrappers(argv) {
     const envAssigns = new Map();

package/dist/core/command-files.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Which FILES a shell command hands to a program to execute — the parser-backed
+ * answer to "is the guard this hook names even on disk?".
+ *
+ * 🔴 WHY THIS EXISTS, and it is the loudest lie the sweep could tell. A hook
+ * registered as `python3 .claude/hooks/guard.py` whose script is not there does
+ * not fail in a way anyone can see: `python3` exits **2** on a file it cannot
+ * open, and 2 is Claude Code's DENY code. So `decideHook` reads a block, and
+ * `experimental_verifyPluginGuards` reports the hook as blocking every disaster
+ * in the battery — a perfect score for a guard that does not exist. Measured on
+ * this repo's own build:
+ *
+ * ```
+ * hook `python3 .claude/hooks/guard.py`, script absent
+ *   → MEASURED blocks=7/7 exits=2,2,2,2,2,2,2
+ * ```
+ *
+ * No malformed config is needed to reach it — a relative script path is the
+ * commonest shape in the wild — which makes it strictly worse than the
+ * uncompilable-matcher lie fixed alongside it, and it is the same false
+ * confidence the product sells against, produced by the product.
+ *
+ * THE EXIT CODE CANNOT DECIDE IT, and that is not a guess: `run-script.ts`
+ * already writes down the same fact for its own coverage attribution — "`sh
+ * <missing>` exits **2** under dash, which is Claude Code's BLOCK code —
+ * indistinguishable from a gate legitimately denying, so it cannot be encoded".
+ * The shell's own 126/127 catch a program that never launched; nothing catches a
+ * program that launched and could not find its script. That is what this module
+ * is for, and why the two halves are both needed rather than either alone.
+ *
+ * ## What counts as a file reference (MEASURED, not assumed)
+ *
+ * A word is only reported when it is UNAMBIGUOUSLY a script the command runs:
+ * fully resolved (no unexpanded `$`, no substitution, no glob, no whitespace),
+ * not a flag, not a `NAME=value`, not a URL, not the inline program text of a
+ * `-c`/`-e`, and either the head is a known interpreter or the word carries a
+ * script extension UNDER A HEAD THAT COULD EXECUTE IT. The OR is what keeps
+ * either list from being load-bearing on its own: an interpreter missing from
+ * the table is still caught by the extension, and an extensionless script is
+ * still caught by the interpreter.
+ *
+ * The `UNDER A HEAD` clause is the correction: an extension is evidence about
+ * the FILE, not about the command, so on its own it read `rm -f /tmp/stale.sh`
+ * — an ordinary cleanup hook whose file is meant to be absent — as a missing
+ * script. {@link DATA_ONLY_HEADS} is the set of heads that never execute an
+ * operand, and it silences the extension branch for them.
+ *
+ * The narrowing is measured, not taste. Over the 107 hook registrations in
+ * `davila7/claude-code-templates` (the corpus the defect was found in):
+ *
+ * | rule                                        | hits | wrong |
+ * | ------------------------------------------- | ---: | ----: |
+ * | any path-shaped operand                     |   31 |     8 |
+ * | interpreter head OR script extension        |   23 |     0 |
+ *
+ * The eight the wide rule got wrong are files a hook WRITES or later reads
+ * (`rm ~/.claude/session_start.tmp`, `mv ~/.claude/performance.csv`) and one
+ * outright absurdity (`echo N/A`, which contains a slash). Reporting those would
+ * be crying wolf on hooks that are perfectly fine, and a check read once and
+ * distrusted is a check that is off.
+ *
+ * ⚠️ THE `wrong: 0` ROW IS WHAT THE `DATA_ONLY_HEADS` CLAUSE CORRECTS, and the
+ * two measurements are of different corpora — say so rather than quoting one
+ * number. `rm -f /tmp/stale.sh` is exactly the eighth shape above wearing a
+ * script extension, and it was not in the pinned 107. Re-measured 2026-09-08
+ * against today's `davila7/claude-code-templates` (134 registrations, 120
+ * distinct commands — the repo has moved since the pin, so this is a second
+ * sample, not a reproduction of the first):
+ *
+ * | rule                                        | hits | lost to the clause |
+ * | ------------------------------------------- | ---: | -----------------: |
+ * | interpreter head OR script extension        |    5 |                  0 |
+ * | …with the `DATA_ONLY_HEADS` clause          |    5 |                  0 |
+ *
+ * All five are true positives reached by an INTERPRETER head or a head that is
+ * itself a path, so the extension-under-an-unknown-head branch contributes zero
+ * hits on this sample and narrowing it costs nothing measurable. That is the
+ * evidence the clause does not trade a real detection for a false-positive fix;
+ * it is not evidence the branch is dead, which is why it is kept.
+ *
+ * CONSERVATIVE IN THE OTHER DIRECTION THAN {@link shellVarReads}, on purpose.
+ * Over-reporting a missing FILE costs a real guard its measurement AND accuses
+ * its author of shipping a broken hook, so here silence is the safe error: a
+ * word this module cannot fully resolve is skipped, never guessed at. The
+ * missing-program half of the same question is answered after the fact by the
+ * shell's 126/127, so a false negative here is not the last line of defence.
+ */
+/** What a command would execute, as far as this module can resolve it. */
+export interface CommandFileRefs {
+    /**
+     * Files the command hands to a program to run, in first-seen order, exactly
+     * as the shell would spell them (relative stays relative — the caller resolves
+     * against the cwd the hook will run in).
+     */
+    readonly refs: readonly string[];
+    /** Whether the shell parser accepted the command. `false` ⇒ `refs` is empty. */
+    readonly parsed: boolean;
+}
+/**
+ * The files `command` would hand to a program to execute.
+ *
+ * @param command - the shell command, exactly as the hook registers it.
+ * @param values - variables whose value is known at run time, for expansion. A
+ *   word naming anything absent from this map is skipped, not guessed.
+ */
+export declare function commandFileRefs(command: string, values?: Readonly<Record<string, string>>): CommandFileRefs;
+//# sourceMappingURL=command-files.d.ts.map