vigiles 32.1.1 → 33.1.0

package/dist/adapters/claude-code/run-scripts.d.ts

@@ -1,3 +1,16 @@
+/**
+ * vigiles — run harness-test / eval script files via the CLI.
+ *
+ * `vigiles test` and `vigiles eval` discover `*.harness.*` / `*.eval.*`
+ * scripts and run each as a child `node` process, so the two-tier
+ * harness-testing API (`src/harness-test.ts`, `src/eval.ts`) works as a CI
+ * command, not just `node x.mjs`. Scripts may be authored in **JavaScript**
+ * (`.mjs` / `.cjs` / `.js`) **or TypeScript** (`.ts` / `.mts` / `.cts`) — a TS
+ * script is run through `tsx` when installed, else Node's built-in type
+ * stripping (Node >= 22.6). The scripts import from the built `dist/`, so they
+ * also run standalone — the CLI just discovers, runs, and aggregates exit codes.
+ */
+import { type TestTier } from "../../source-kinds.js";
 import { type SurfaceProbe } from "../../check-count.js";
 /**
  * The outcome of running one script.
@@ -102,10 +115,13 @@ export declare function statusFor(code: number, checks: number | undefined, load
  * retracting silently with no type error.
  */
 export declare function loadFailed(r: ScriptRunResult): boolean;
-/** Filename extensions accepted for harness/eval scripts (JS and TS). */
+/**
+ * Filename extensions accepted for harness/eval scripts (JS and TS). The table
+ * lives in `source-kinds.ts`; this re-export keeps the runner's name for it.
+ */
 export declare const SCRIPT_EXTS: readonly ["mjs", "cjs", "js", "mts", "cts", "ts"];
-/** Glob suffix matching every accepted script extension, e.g. `harness`. */
-export declare function scriptGlob(kind: "harness" | "eval"): string;
+/** The glob that discovers one tier's scripts, derived from the same table as everything else that names a test. */
+export declare function scriptGlob(kind: TestTier): string;
 export { detectNodeCaps, canRunTypeScript, type NodeCaps, } from "../../ts-runner-caps.js";
 import type { NodeCaps } from "../../ts-runner-caps.js";
 import { type GlobIgnore } from "../../core/glob-ignore.js";

package/dist/adapters/claude-code/run-scripts.js

@@ -22,6 +22,7 @@ exports.formatScriptSummary = formatScriptSummary;
  * stripping (Node >= 22.6). The scripts import from the built `dist/`, so they
  * also run standalone — the CLI just discovers, runs, and aggregates exit codes.
  */
+const source_kinds_js_1 = require("../../source-kinds.js");
 const node_child_process_1 = require("node:child_process");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -103,11 +104,14 @@ function statusFor(code, checks, load) {
 function loadFailed(r) {
     return r.status === "skip" && r.code !== exports.SKIP_EXIT_CODE;
 }
-/** Filename extensions accepted for harness/eval scripts (JS and TS). */
-exports.SCRIPT_EXTS = ["mjs", "cjs", "js", "mts", "cts", "ts"];
-/** Glob suffix matching every accepted script extension, e.g. `harness`. */
+/**
+ * Filename extensions accepted for harness/eval scripts (JS and TS). The table
+ * lives in `source-kinds.ts`; this re-export keeps the runner's name for it.
+ */
+exports.SCRIPT_EXTS = source_kinds_js_1.RUNNABLE_EXTS;
+/** The glob that discovers one tier's scripts, derived from the same table as everything else that names a test. */
 function scriptGlob(kind) {
-    return `**/*.${kind}.{${exports.SCRIPT_EXTS.join(",")}}`;
+    return (0, source_kinds_js_1.testGlob)(kind);
 }
 const TS_EXT = /\.(?:m|c)?ts$/;
 // The capability probe lives in `src/ts-runner-caps.ts` so the SUGGESTER
@@ -194,6 +198,10 @@ function discoverScripts(patterns, defaultGlob, cwd, ignore) {
             ignore: (0, glob_ignore_js_1.withIgnored)([], ignore),
             dot: true,
             nodir: true,
+            // `glob` defaults this to TRUE on macOS and Windows, which made
+            // `a.hook.HARNESS.mjs` a test there and nothing on Linux. The kind of a
+            // name is decided case-sensitively (`source-kinds.ts`); the glob agrees.
+            nocase: false,
         })) {
             found.add(m);
         }

package/dist/cli-main.js

@@ -5981,7 +5981,16 @@ async function refsHookCommand() {
  */
 async function compileProviders() {
     const names = [];
-    for (const file of (0, hook_install_js_1.discoverProviderFiles)(process.cwd())) {
+    const { claimed, unclaimed } = (0, hook_install_js_1.discoverProviderFiles)(process.cwd());
+    // A provider that lost (or never had) its marker is not silently skipped: a
+    // hook's `provider()` ref to it would then fail to resolve with a message
+    // about the REF, far from the cause.
+    if (unclaimed.length > 0) {
+        // Every one gets the ✗ (the catch adds the first): the others used to read
+        // as a continuation of the first message.
+        throw new hook_program_js_1.HookCompileError(unclaimed.map((f) => (0, hook_install_js_1.unclaimedReport)(f, "provider")).join("\n✗ "));
+    }
+    for (const file of claimed) {
         const def = await (0, hook_runtime_js_1.loadProvider)(file);
         if ((0, hook_providers_js_1.unsafeProvider)(def)) {
             throw new hook_program_js_1.HookCompileError(`provider ${file} ("${def.run}") is not provably read-only — ` +
@@ -6117,8 +6126,8 @@ async function installHookFile(file, adapter, registeredProviders = []) {
  * resolved from the `--harness=` flag, else `.vigilesrc.json#harnesses`, else auto-detect.
  * Returns false if any hook failed to compile for any harness.
  */
-async function installHooks(hookFiles, harnessFlag, configHarness) {
-    if (hookFiles.length === 0)
+async function installHooks(hookFiles, harnessFlag, configHarness, validateProvidersAnyway = false) {
+    if (hookFiles.length === 0 && !validateProvidersAnyway)
         return true;
     const adapters = (0, adapter_registry_js_1.resolveHarnessAdapters)({
         root: process.cwd(),
@@ -6138,6 +6147,8 @@ async function installHooks(hookFiles, harnessFlag, configHarness) {
         }
         throw e;
     }
+    if (hookFiles.length === 0)
+        return true; // providers validated; nothing to wire
     let ok = true;
     for (const file of hookFiles) {
         try {
@@ -6645,15 +6656,40 @@ async function main() {
                     .filter((f) => f.endsWith(".spec.ts"))
                     .map((f) => noteExplicitOverride(excludes, f, "compiling"))
                 : findSpecs(excludes);
-            const hooks = restArgs.length > 0
-                ? restArgs.filter((f) => !f.endsWith(".spec.ts"))
-                : (0, hook_install_js_1.discoverHookFiles)(process.cwd());
-            if (specs.length === 0 && hooks.length === 0) {
+            // WHAT A HOOK IS is decided once, in `source-kinds.ts`: a bare `compile`
+            // and `compile <file>` ask the same classifier, so they cannot disagree.
+            // Only `.hook.` files are compiled; a runnable file that carries no marker
+            // is refused below, out loud, with the command that fixes it.
+            const found = restArgs.length > 0
+                ? (0, hook_install_js_1.partitionHookArgs)(restArgs.filter((f) => !f.endsWith(".spec.ts")))
+                : (0, hook_install_js_1.discoveredHookArgs)(process.cwd());
+            const hooks = [...found.hooks];
+            const unclaimed = found.unclaimed;
+            if (specs.length === 0 &&
+                hooks.length === 0 &&
+                unclaimed.length === 0 &&
+                found.skipped.length === 0 &&
+                found.invalid.length === 0) {
                 console.log("No .spec.ts or .vigiles/hooks/ hook files found.");
                 console.log("Run `vigiles init` to create one.");
                 process.exit(0);
             }
             let valid = true;
+            // Refused files FIRST and on stderr: they are the news in this run, and a
+            // line that scrolled past under forty `✓` lines is a silent skip with
+            // extra steps. Compiling the rest still proceeds — one stray file must
+            // not stop the hooks that are fine.
+            for (const f of unclaimed) {
+                console.error(`✗ ${(0, hook_install_js_1.unclaimedReport)(f, "hook")}`);
+                valid = false;
+            }
+            for (const bad of found.invalid) {
+                console.error(`✗ ${(0, hook_install_js_1.invalidArgMessage)(bad.path, bad.reason)}`);
+                valid = false;
+            }
+            for (const s of found.skipped) {
+                console.log(`- ${s.path} skipped: a ${s.kind}, not a hook.`);
+            }
             if (specs.length > 0)
                 valid =
                     (await compile(specs, config, excludes, { harnessFlag })) && valid;
@@ -6670,13 +6706,21 @@ async function main() {
                     console.log(`\n${weightLine}`);
             }
             valid =
-                (await installHooks(hooks, harnessFlag, (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses))) && valid;
+                (await installHooks(hooks, harnessFlag, (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses), 
+                // A hook-side compile is under way even when every hook was refused:
+                // validate the providers too, so ONE run shows every problem.
+                unclaimed.length > 0)) && valid;
             // Keep an existing whole-harness registry in sync (cheap, opt-in) so the
             // user never hand-runs `generate-harness`. Skipped when no harness.gen.ts.
             if (specs.length > 0)
                 valid = (await refreshHarnessGenIfPresent(harnessFlag)) && valid;
             console.log("");
-            if (valid) {
+            if (valid && specs.length === 0 && hooks.length === 0) {
+                // Skipped paths are not errors, but a run that compiled nothing must not
+                // read like one that did.
+                console.log("Nothing was compiled: every path given was skipped.");
+            }
+            else if (valid) {
                 console.log("Compilation complete.");
             }
             else {

package/dist/core/frame.d.ts

@@ -28,7 +28,7 @@
  * 🔴 THE ONE CONVERSION POINT. A `RepoPath` is minted here and nowhere else:
  * {@link Frame.repo} from an absolute path, {@link Bundle.path} from a
  * `BundlePath`. A cast to `RepoPath` outside this file is refused by ESLint
- * (`no-restricted-syntax` in `eslint.config.mjs`), so "where did this path get its
+ * (`local/frame-mint` in `eslint.config.mjs`), so "where did this path get its
  * frame" always has the answer "in frame.ts".
  *
  * WHAT IS UNREPRESENTABLE AND WHAT IS ONLY DETECTABLE. The CLI's output boundary

package/dist/core/hook-program.js

@@ -515,7 +515,7 @@ function commandView(raw, root) {
             // uses, and for the same reason. This matcher read only `leaves` (raw), so
             // three ordinary rewrites walked past a guard that blocks the plain form.
             // MEASURED 2026-09-02 on the shipped dogfood artifact behind the public
-            // 7/7 claim (`examples/harness/safe-bash-guard.mjs`):
+            // 7/7 claim (`examples/harness/safe-bash-guard.hook.mjs`):
             //   git push --force origin main            exit 2  blocked
             //   git push "--force" origin main          exit 0  ALLOWED
             //   sudo git push --force origin main       exit 0  ALLOWED

package/dist/core/hook-providers.d.ts

@@ -54,7 +54,7 @@ export declare const provide: <const Name extends string>(name: Name, run: strin
 export declare const dangerously: <const Name extends string>(name: Name, run: string) => InlineProvider<Name>;
 /**
  * A REGISTERED provider — a reusable, named fact authored once in
- * `.vigiles/providers/<name>.{mjs,ts}` (default-exported via {@link defineProvider})
+ * `.vigiles/providers/<name>.provider.{mjs,ts}` (default-exported via {@link defineProvider})
  * and referenced from many hooks by {@link provider} name. The reusable sibling of
  * the one-off inline {@link provide}; same read-only-by-default rule.
  */

package/dist/coverage-evidence.d.ts

@@ -64,9 +64,7 @@ export interface PreparedTest {
 export declare function isColocatedTest(surface: Pick<CoverableSurface, "name" | "path">, testPath: string): boolean;
 /** Wrap a discovered path. Kept as a function so both twins share one shape. */
 export declare function prepareTest(path: string): PreparedTest;
-/** @param filename a BASENAME — callers strip the directory with their own path
- * helper (`node:path` on disk, `posix-path` in the browser twin). */
-export declare function isEvalScript(filename: string): boolean;
+export { isEvalScript } from "./source-kinds.js";
 /**
  * The root variables a hook command may be written against — the structural
  * slice of `PluginLayout` this needs, taken by SHAPE so the browser twin does

package/dist/coverage-evidence.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SURFACE_TOKEN = void 0;
+exports.SURFACE_TOKEN = exports.isEvalScript = void 0;
 exports.strongerEvidence = strongerEvidence;
 exports.isColocatedTest = isColocatedTest;
 exports.prepareTest = prepareTest;
-exports.isEvalScript = isEvalScript;
 exports.hookScriptRefs = hookScriptRefs;
 exports.evidenceFor = evidenceFor;
 exports.hasSurfaceToken = hasSurfaceToken;
@@ -185,39 +184,12 @@ function prepareTest(path) {
  * mode here is under-counting, not accusation.
  */
 const SCRIPT_RE = (0, source_refs_js_1.scriptRefPattern)();
-/**
- * Is this filename one the PAID real-model runner would actually run?
- *
- * The tier split decides which of two runners owns a test file, and it is the
- * only thing standing between a scheduled paid run and a per-push one. It has
- * now been wrong in both directions:
- *
- * - As the full suffix `.eval.mjs` it was a MONEY HAZARD — `foo.eval.ts` fell
- *   into the free branch and would have spent real model calls on every push.
- * - As the bare INFIX `.eval.` it made a FALSE GRANT — `parser.eval.test.ts`,
- *   an ordinary deterministic test discovered by an `include` of
- *   `**\/*.test.ts`, was credited to the paid tier and dropped from the free
- *   one. `vigiles eval` globs `**\/*.eval.{mjs,cjs,js,mts,cts,ts}`, so that name
- *   is not discoverable by the eval runner at all: the surface was reported
- *   covered by the tier that cannot run it, and uncovered by the tier that does.
- *
- * The rule that is wrong in neither direction is the one the runner itself uses:
- * `.eval.` followed by a runnable extension AT THE END of the name. Anything
- * else — including a name that merely contains `.eval.` — is deterministic, or
- * is not a script at all.
- *
- * ⚠️ The extension list is RE-DECLARED, not imported: the authority is
- * `SCRIPT_EXTS` in adapters/claude-code/run-scripts.ts, which pulls in
- * `node:child_process` and `glob` and so cannot be imported by this
- * browser-safe module. A test in test-coverage.test.ts asserts the two agree,
- * so an extension added to the runner cannot silently fail to be billed here.
- */
-const EVAL_SCRIPT_RE = /\.eval\.(?:mjs|cjs|js|mts|cts|ts)$/;
-/** @param filename a BASENAME — callers strip the directory with their own path
- * helper (`node:path` on disk, `posix-path` in the browser twin). */
-function isEvalScript(filename) {
-    return EVAL_SCRIPT_RE.test(filename);
-}
+// Which runner owns a test file — the paid real-model one or the free one — is
+// answered by the shared source-kind table (`source-kinds.ts`), which this
+// browser-safe module can import because it imports nothing. See `isEvalScript`
+// there for the two ways this question has been answered wrongly before.
+var source_kinds_js_1 = require("./source-kinds.js");
+Object.defineProperty(exports, "isEvalScript", { enumerable: true, get: function () { return source_kinds_js_1.isEvalScript; } });
 /**
  * The hook-script paths a manifest's `hooks` block names, repo-relative.
  *

package/dist/eval-define.js

@@ -60,6 +60,7 @@ exports.defineEval = defineEval;
  * never executes, so it is untouched.
  */
 const node_path_1 = require("node:path");
+const source_kinds_js_1 = require("./source-kinds.js");
 /**
  * Brand marking a value as built by {@link defineEval}. A registered symbol, so
  * a descriptor still reads as one across two copies of the package on disk —
@@ -128,8 +129,6 @@ function moduleDefault(mod) {
     const inner = outer?.default;
     return isEvalDefinition(inner) ? inner : outer;
 }
-/** Filenames vigiles runs as evals — the runner's own glob, as a pattern. */
-const EVAL_FILE = /\.eval\.(?:m|c)?[jt]s$/;
 /**
  * Was node pointed STRAIGHT at an eval file? `argv1` is `process.argv[1]`: the
  * path node was started with, which no stray configuration can forge.
@@ -142,7 +141,8 @@ const EVAL_FILE = /\.eval\.(?:m|c)?[jt]s$/;
  * Pure: a fact in, a boolean out.
  */
 function ranAsEntry(argv1) {
-    return argv1 !== undefined && EVAL_FILE.test(argv1.replaceAll("\\", "/"));
+    return (argv1 !== undefined &&
+        (0, source_kinds_js_1.isEvalScript)(argv1.replaceAll("\\", "/").split("/").pop() ?? ""));
 }
 /** The words shown when someone runs an eval file directly. Asserted by a test:
  *  a refusal that stops a run without saying what to do instead is a ticket. */

package/dist/eval-lock.js

@@ -58,6 +58,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const hash_js_1 = require("./core/hash.js");
 const eval_cache_js_1 = require("./eval-cache.js");
+const source_kinds_js_1 = require("./source-kinds.js");
 /**
  * On-disk lock-format version, salted into nothing (the lock is keyed by name,
  * not by hash) but VALIDATED on read so an incompatible shape fails loud rather
@@ -162,7 +163,7 @@ function isEvalInputFile(path) {
     const p = path.replace(/\\/g, "/");
     if (/(^|\/)SKILL\.md$/.test(p))
         return true;
-    return /\.eval\.(mjs|cjs|js|mts|cts|ts)$/.test(p);
+    return (0, source_kinds_js_1.isEvalScript)(p.split("/").pop() ?? "");
 }
 /**
  * The NON-BLOCKING nudge to emit after an eval-input edit when committed locks

package/dist/hook-install.d.ts

@@ -1,11 +1,100 @@
+import { type CompilableMarker, type SourceKind } from "./source-kinds.js";
 /** The agnostic, committed home for hook SOURCE — one dir, cross-adapter. */
 export declare const HOOKS_DIR = ".vigiles/hooks";
 /** The committed home for registered context-provider SOURCE (v2). */
 export declare const PROVIDERS_DIR = ".vigiles/providers";
-/** Discover hook source files under {@link HOOKS_DIR} (stamps excluded). */
-export declare function discoverHookFiles(cwd: string): string[];
-/** Discover registered-provider source files under {@link PROVIDERS_DIR}. */
-export declare function discoverProviderFiles(cwd: string): string[];
+/** What discovery found in one source directory, split by what `compile` owes each part. */
+export interface Discovered {
+    /** Files this directory's role compiles: `.hook.` files in `.vigiles/hooks/`, `.provider.` files in `.vigiles/providers/`. */
+    readonly claimed: readonly string[];
+    /**
+     * Runnable files nothing claims here. `compile` REFUSES these out loud
+     * ({@link unclaimedMessage}); dropping them would make a hook that lost its
+     * marker vanish from the build without a word.
+     */
+    readonly unclaimed: readonly string[];
+}
+/** Discover hook sources under {@link HOOKS_DIR}: `.hook.` files, and the runnable files that are nobody's. */
+export declare function discoverHookFiles(cwd: string): Discovered;
+/** Discover registered-provider sources under {@link PROVIDERS_DIR}. */
+export declare function discoverProviderFiles(cwd: string): Discovered;
+/** Why an explicit `compile` argument is an error rather than a hook, a refusal or a skip. */
+export type InvalidArgReason = "missing" | "directory" | "not-a-source";
+/** What `vigiles compile <files…>` makes of the paths it was handed. */
+export interface HookArgs {
+    readonly hooks: readonly string[];
+    /** Runnable files nothing claims (or a marked file in the wrong directory): refused, with the fix. */
+    readonly unclaimed: readonly string[];
+    /** Named on purpose, not compilable (a test, a stamp…): said out loud, not an error. */
+    readonly skipped: readonly {
+        readonly path: string;
+        readonly kind: SourceKind["kind"];
+    }[];
+    /** Not a file at all, or not a source: an error, the way it always was. */
+    readonly invalid: readonly {
+        readonly path: string;
+        readonly reason: InvalidArgReason;
+    }[];
+}
+/** What the file system says a path is. Injected so the rules below stay pure. */
+export type PathProbe = (path: string) => "file" | "directory" | "missing" | "other";
+/**
+ * Sort explicit `compile` arguments by the same classifier discovery uses, so
+ * `compile guard.mjs` and a bare `compile` give the same answer about it — for a
+ * path ANYWHERE, not just under `.vigiles/hooks/`: `compile .claude/hooks/x.mjs`
+ * or a plugin's `hooks/guard.mjs` is refused unless it carries `.hook.`.
+ *
+ * A path that is missing, a directory or not a regular file is an error (it used
+ * to fail, and the first version of the marker rule turned it into a green run).
+ * The one lenient case exists for a shell glob (`compile .vigiles/hooks/*`): a
+ * test, declaration or stamp is reported as skipped, and so is a README or
+ * `.gitkeep` — but only inside the two vigiles source directories, where a glob
+ * would sweep one up. A `/etc/passwd` is not a README.
+ */
+export declare function partitionHookArgs(args: readonly string[], probe?: PathProbe): HookArgs;
+/** The line `compile` prints for an argument it cannot treat as a hook source at all. */
+export declare function invalidArgMessage(path: string, reason: InvalidArgReason): string;
+/**
+ * Discovery, shaped like {@link partitionHookArgs}'s answer, so `compile` handles
+ * "no arguments" and "these paths" through one code path afterwards.
+ */
+export declare function discoveredHookArgs(cwd: string): HookArgs;
+/**
+ * The ONE shell command that renames an unclaimed file to its marked name and
+ * (for a hook) recompiles it. Every path is single-quoted: this is printed by a
+ * tool and pasted by a person, and a repository can plant a file name that is a
+ * command.
+ *
+ * 🔴 THE HOOK COMMAND COPIES FIRST AND DELETES LAST, and that order is the
+ * point. Already-wired hooks keep running after an upgrade: the runtime loads
+ * whatever path `settings.json` names, and never asks what a file is called. So
+ * the break is the NEXT compile, and a plain `mv` + `compile` has one bad
+ * moment — the old path is gone and the wiring still names it. For a gate
+ * wired `|| exit 2` that is a hook that cannot load, which blocks every Bash
+ * call (the repair is a file write, not a command). Compiling the renamed copy
+ * while the old file still exists, and deleting the old one only after that
+ * compile succeeded, has no such moment: if anything fails the old hook is
+ * still on disk and still wired. `compile` replaces the old wiring itself
+ * ({@link ownedRefs}), so nothing is left naming the deleted path.
+ *
+ * 🔴 `cp -n`, because the marked name may already exist: a plain `cp` replaced
+ * an edited `guard.hook.mjs` with the stale `guard.mjs`, and the weaker hook
+ * became the wired gate. {@link unclaimedMessage} checks first and prints no
+ * command at all in that case; `-n` is for the file that appears in between.
+ */
+export declare function renameCommand(path: string, role: CompilableMarker): string;
+/**
+ * {@link unclaimedMessage} with the one fact it cannot know, read off the disk:
+ * whether the marked name is already there.
+ */
+export declare function unclaimedReport(path: string, role: CompilableMarker, cwd?: string): string;
+/**
+ * The text `compile` prints for one file it will not compile, with the exact
+ * command to fix it. `targetExists` is whether the marked name is already on
+ * disk: then there is nothing safe to copy, and the message says to merge by
+ * hand instead.
+ */
+export declare function unclaimedMessage(path: string, role: CompilableMarker, targetExists?: boolean): string;
 interface CommandHook {
     readonly type: "command";
     readonly command: string;