vigiles 2.2.0 → 2.3.0

package/dist/judge.d.ts

@@ -0,0 +1,29 @@
+export interface JudgeResult {
+    /** Score in [0, 1] (clamped). 0 on any failure to obtain a verdict. */
+    readonly score: number;
+    /** score ≥ threshold (default 0.5). */
+    readonly pass: boolean;
+    /** The model's one-line rationale, or an error string. */
+    readonly reason: string;
+}
+export interface JudgeOptions {
+    /** The text to grade. */
+    readonly output: string;
+    /** The grading rubric — describe what earns a high vs low score. */
+    readonly rubric: string;
+    /** Model alias. Default "haiku" (cheap; judging is a simple call). */
+    readonly model?: string;
+    /** pass = score ≥ threshold. Default 0.5. */
+    readonly threshold?: number;
+    /** Per-call timeout ms. Default 60000. */
+    readonly timeoutMs?: number;
+}
+/** Grade `output` against `rubric` with a model. Synchronous (for `measure`). */
+export declare function judge(opts: JudgeOptions): JudgeResult;
+/**
+ * Parse a verdict out of the grader's stdout — pure, so the parsing is testable
+ * without a model. Handles `claude --output-format json` (text wrapped in a
+ * `result` field), bare/prose-wrapped JSON, clamping, and the pass threshold.
+ */
+export declare function parseJudgeOutput(stdout: string, threshold?: number): JudgeResult;
+//# sourceMappingURL=judge.d.ts.map

package/dist/judge.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.judge = judge;
+exports.parseJudgeOutput = parseJudgeOutput;
+/**
+ * vigiles — a thin LLM-as-judge for the eval tier.
+ *
+ * Some outcomes aren't a regex: "is this commit message clear?", "did the SKILL
+ * produce a sensible plan?". `judge` grades an output against a rubric with a
+ * model and returns a numeric score + pass/fail, for use *inside* an eval's
+ * `measure` (which is synchronous — so this shells out via the `claude` CLI
+ * synchronously, no extra deps):
+ *
+ *   measure: (ctx) => {
+ *     const v = judge({ output: ctx.file("PLAN.md") ?? "", rubric:
+ *       "1 if the plan lists concrete, ordered steps; else 0." });
+ *     return { quality: v.score, ok: v.pass };
+ *   }
+ *
+ * This is deliberately minimal — for datasets, tracing, and dashboards use a
+ * dedicated eval platform (Braintrust, DeepEval). vigiles owns the harness A/B,
+ * not the judging platform. Needs the `claude` CLI + model auth.
+ */
+const node_child_process_1 = require("node:child_process");
+const clamp01 = (n) => Math.max(0, Math.min(1, n));
+/** Extract the first JSON object from a string (models often wrap it in prose). */
+function firstJsonObject(s) {
+    const start = s.indexOf("{");
+    const end = s.lastIndexOf("}");
+    if (start === -1 || end <= start)
+        return null;
+    try {
+        return JSON.parse(s.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+}
+/** Grade `output` against `rubric` with a model. Synchronous (for `measure`). */
+function judge(opts) {
+    const threshold = opts.threshold ?? 0.5;
+    const prompt = "You are a strict grader. Score the OUTPUT against the RUBRIC. " +
+        'Respond with ONLY a JSON object: {"score": <number 0..1>, "reason": "<one line>"}.\n\n' +
+        `RUBRIC:\n${opts.rubric}\n\nOUTPUT:\n${opts.output}`;
+    let res;
+    try {
+        res = (0, node_child_process_1.spawnSync)("claude", [
+            "-p",
+            prompt,
+            "--model",
+            opts.model ?? "haiku",
+            "--output-format",
+            "json",
+        ], { encoding: "utf-8", timeout: opts.timeoutMs ?? 60000 });
+    }
+    catch (e) {
+        return {
+            score: 0,
+            pass: false,
+            reason: `judge spawn failed: ${String(e)}`,
+        };
+    }
+    if (res.status !== 0) {
+        return { score: 0, pass: false, reason: "judge: no model output" };
+    }
+    return parseJudgeOutput(res.stdout ?? "", threshold);
+}
+/**
+ * Parse a verdict out of the grader's stdout — pure, so the parsing is testable
+ * without a model. Handles `claude --output-format json` (text wrapped in a
+ * `result` field), bare/prose-wrapped JSON, clamping, and the pass threshold.
+ */
+function parseJudgeOutput(stdout, threshold = 0.5) {
+    if (!stdout)
+        return { score: 0, pass: false, reason: "judge: no model output" };
+    // claude --output-format json wraps the model text in a `result` field.
+    let text = stdout;
+    const wrapper = firstJsonObject(stdout);
+    if (wrapper && typeof wrapper.result === "string")
+        text = wrapper.result;
+    const verdict = firstJsonObject(text);
+    if (!verdict || typeof verdict.score !== "number") {
+        return { score: 0, pass: false, reason: "judge: unparseable verdict" };
+    }
+    const score = clamp01(verdict.score);
+    return { score, pass: score >= threshold, reason: verdict.reason ?? "" };
+}
+//# sourceMappingURL=judge.js.map

package/dist/plugin-loader.d.ts

@@ -0,0 +1,37 @@
+export interface LoadedPlugin {
+    /** A `.claude/settings.json`-shaped object with hooks resolved. */
+    readonly settings: {
+        hooks?: unknown;
+    };
+    /** Files to materialize in the sandbox (CLAUDE.md, skills, agents, commands). */
+    readonly files: Record<string, string>;
+    /**
+     * Surfaces that are present in the plugin but cannot be exercised at the
+     * deterministic tier (subagents and slash commands need a real model; MCP
+     * servers aren't wired by the loader). Empty when the plugin is fully
+     * covered. Surfaced so "load the whole plugin" never silently tests nothing —
+     * read it in a test, or just to know what the deterministic run won't reach.
+     */
+    readonly warnings: readonly string[];
+}
+/**
+ * Load the real harness at `pluginPath`. Returns the resolved settings (hooks),
+ * the files (CLAUDE.md + skills + agents + commands) to write into the test
+ * sandbox, and `warnings` for surfaces the deterministic tier can't drive. Merge
+ * `settings` with any inline settings and spread `files` into the fixture.
+ */
+export declare function loadPlugin(pluginPath: string): LoadedPlugin;
+/**
+ * Resolve the effective harness for a test/eval (arm): load the plugin if given,
+ * then layer inline settings + files on top. Shared by `runHarnessTest` and
+ * `runEval` so both test the assembled machine the same way.
+ */
+export declare function resolveHarness(opts: {
+    plugin?: string;
+    settings?: unknown;
+    files?: Record<string, string>;
+}): {
+    settings: unknown;
+    files: Record<string, string>;
+};
+//# sourceMappingURL=plugin-loader.d.ts.map

package/dist/plugin-loader.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPlugin = loadPlugin;
+exports.resolveHarness = resolveHarness;
+/**
+ * vigiles — load a real plugin/repo harness for testing.
+ *
+ * The unit that matters is not a single hook but the *assembled machine*: the
+ * hooks, settings, CLAUDE.md, skills, subagents, and commands a plugin/repo
+ * actually ships, working together. `loadPlugin` reads that real harness so a
+ * `runHarnessTest` / `runEval` runs against what ships — not a hand-retyped
+ * subset that can drift. Hooks, CLAUDE.md and skills are exercisable at the
+ * deterministic tier; subagents/commands/MCP are materialized but only run under
+ * a real model, so `LoadedPlugin.warnings` flags them (no silent empty machine).
+ *
+ *   runHarnessTest({ plugin: "./", model: scriptModel([...]) });
+ *
+ * Resolution order for hooks: inline `hooks` in `.claude-plugin/plugin.json`, a
+ * `hooks` string path in plugin.json, the `hooks/hooks.json` convention (e.g.
+ * obra/superpowers), then a plain repo's `.claude/settings.json`. `${CLAUDE_
+ * PLUGIN_ROOT}` in any hook command is expanded to the plugin's absolute path,
+ * so the real hook scripts run from where they live (no copying needed). The
+ * plugin's CLAUDE.md and skills/ are materialized into the sandbox so the
+ * assembled context is present too.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const MAX_SKILL_FILE_BYTES = 256 * 1024;
+/** Read and return the `.hooks` field of a JSON file, or undefined on any error. */
+function readHooksFile(path) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8"))
+            .hooks;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the hooks block, handling the real-world plugin layouts:
+ *   1. inline `hooks` object in .claude-plugin/plugin.json,
+ *   2. a `hooks` *string* in plugin.json pointing at a hooks JSON file,
+ *   3. the `hooks/hooks.json` convention (e.g. obra/superpowers) — auto-discovered,
+ *   4. a plain repo's `.claude/settings.json`.
+ */
+function readHooks(root) {
+    const manifestPath = (0, node_path_1.join)(root, ".claude-plugin", "plugin.json");
+    if ((0, node_fs_1.existsSync)(manifestPath)) {
+        const m = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf-8"));
+        if (typeof m.hooks === "string")
+            return readHooksFile((0, node_path_1.join)(root, m.hooks));
+        if (m.hooks !== undefined)
+            return m.hooks;
+    }
+    const conventionPath = (0, node_path_1.join)(root, "hooks", "hooks.json");
+    if ((0, node_fs_1.existsSync)(conventionPath))
+        return readHooksFile(conventionPath);
+    const settingsPath = (0, node_path_1.join)(root, ".claude", "settings.json");
+    if ((0, node_fs_1.existsSync)(settingsPath))
+        return readHooksFile(settingsPath);
+    return undefined;
+}
+/** Recursively collect text files under `dir` as `relativePath → contents`. */
+function readTree(dir, base) {
+    const out = {};
+    for (const entry of (0, node_fs_1.readdirSync)(dir)) {
+        const full = (0, node_path_1.join)(dir, entry);
+        const st = (0, node_fs_1.statSync)(full);
+        if (st.isDirectory()) {
+            Object.assign(out, readTree(full, base));
+        }
+        else if (st.isFile() && st.size <= MAX_SKILL_FILE_BYTES) {
+            out[(0, node_path_1.relative)(base, full)] = (0, node_fs_1.readFileSync)(full, "utf-8");
+        }
+    }
+    return out;
+}
+/**
+ * Load the real harness at `pluginPath`. Returns the resolved settings (hooks),
+ * the files (CLAUDE.md + skills + agents + commands) to write into the test
+ * sandbox, and `warnings` for surfaces the deterministic tier can't drive. Merge
+ * `settings` with any inline settings and spread `files` into the fixture.
+ */
+function loadPlugin(pluginPath) {
+    const root = (0, node_path_1.resolve)(pluginPath);
+    const hooks = readHooks(root);
+    // Expand ${CLAUDE_PLUGIN_ROOT} to the real absolute path so the actual hook
+    // scripts execute — we test the shipped wiring, not a reimplementation.
+    const resolvedHooks = hooks
+        ? JSON.parse(JSON.stringify(hooks).replaceAll("${CLAUDE_PLUGIN_ROOT}", root))
+        : undefined;
+    const files = {};
+    const claudeMd = (0, node_path_1.join)(root, "CLAUDE.md");
+    if ((0, node_fs_1.existsSync)(claudeMd)) {
+        files["CLAUDE.md"] = (0, node_fs_1.readFileSync)(claudeMd, "utf-8");
+    }
+    // Materialize each project-level surface under .claude/<surface>/ so the
+    // assembled context is present in the sandbox (best-effort — headless
+    // activation of plugin skills/subagents/commands is not guaranteed; the body
+    // is present for the agent to read either way). Counting what we materialize
+    // also lets us warn about surfaces the deterministic tier can't drive.
+    const counts = {};
+    for (const surface of ["skills", "agents", "commands"]) {
+        const dir = (0, node_path_1.join)(root, surface);
+        if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory())
+            continue;
+        const tree = readTree(dir, root);
+        for (const [rel, content] of Object.entries(tree)) {
+            files[(0, node_path_1.join)(".claude", rel)] = content;
+        }
+        counts[surface] = Object.keys(tree).length;
+    }
+    return {
+        settings: resolvedHooks ? { hooks: resolvedHooks } : {},
+        files,
+        warnings: pluginWarnings(root, counts, resolvedHooks, files),
+    };
+}
+/**
+ * Flag surfaces present-but-not-deterministically-exercisable. Subagents
+ * (`agents/`) and slash commands (`commands/`) are materialized into the sandbox
+ * but only run under a real model (Task / slash invocation), so they belong to
+ * the eval tier. MCP servers aren't wired by the loader at all. And a plugin
+ * that yields neither hooks nor files would otherwise be a silent empty machine.
+ */
+function pluginWarnings(root, counts, hooks, files) {
+    const warnings = [];
+    if (counts.agents) {
+        warnings.push(`plugin defines ${String(counts.agents)} subagent file(s) under agents/ — these run only under a real model; test them at the eval tier (runEval), not the deterministic mock.`);
+    }
+    if (counts.commands) {
+        warnings.push(`plugin defines ${String(counts.commands)} slash-command file(s) under commands/ — slash-command invocation needs a real model; test at the eval tier.`);
+    }
+    if (hasMcp(root)) {
+        warnings.push(`plugin declares MCP server(s) (mcpServers / .mcp.json) — the loader does not wire MCP; bring the server up yourself if your test needs it.`);
+    }
+    if (!hooks && Object.keys(files).length === 0) {
+        warnings.push(`nothing was loaded (no hooks, CLAUDE.md, skills, agents, or commands) — the deterministic harness would run an effectively empty machine.`);
+    }
+    return warnings;
+}
+/** Whether the plugin declares any MCP servers (manifest field or .mcp.json). */
+function hasMcp(root) {
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(root, ".mcp.json")))
+        return true;
+    const manifestPath = (0, node_path_1.join)(root, ".claude-plugin", "plugin.json");
+    if (!(0, node_fs_1.existsSync)(manifestPath))
+        return false;
+    try {
+        const m = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf-8"));
+        return m.mcpServers !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Merge a loaded plugin's settings with inline settings. Inline wins; when both
+ * declare hooks, the per-event arrays are concatenated (plugin hooks first), so
+ * a test can layer an extra hook on top of the real plugin. Returns `undefined`
+ * when neither side has hooks (so the caller skips `--settings`).
+ */
+function mergeSettings(base, override) {
+    const baseHasHooks = base.hooks !== undefined;
+    if (override === undefined)
+        return baseHasHooks ? base : undefined;
+    if (!baseHasHooks)
+        return override;
+    const b = base;
+    const o = override;
+    const events = new Set([
+        ...Object.keys(b.hooks ?? {}),
+        ...Object.keys(o.hooks ?? {}),
+    ]);
+    const hooks = {};
+    for (const e of events) {
+        hooks[e] = [...(b.hooks?.[e] ?? []), ...(o.hooks?.[e] ?? [])];
+    }
+    return { ...o, hooks };
+}
+/**
+ * Resolve the effective harness for a test/eval (arm): load the plugin if given,
+ * then layer inline settings + files on top. Shared by `runHarnessTest` and
+ * `runEval` so both test the assembled machine the same way.
+ */
+function resolveHarness(opts) {
+    const loaded = opts.plugin
+        ? loadPlugin(opts.plugin)
+        : { settings: {}, files: {} };
+    return {
+        files: { ...loaded.files, ...opts.files },
+        settings: mergeSettings(loaded.settings, opts.settings),
+    };
+}
+//# sourceMappingURL=plugin-loader.js.map

package/dist/run-hook.d.ts

@@ -0,0 +1,77 @@
+/** A hook event payload (the JSON Claude Code writes to the hook's stdin). */
+export interface HookInput {
+    /** e.g. "PreToolUse", "PostToolUse", "Stop", "SessionStart", "PreCompact". */
+    readonly hook_event_name?: string;
+    /** PreToolUse/PostToolUse. */
+    readonly tool_name?: string;
+    readonly tool_input?: unknown;
+    readonly tool_response?: unknown;
+    /** UserPromptSubmit. */
+    readonly prompt?: string;
+    /** SessionStart. */
+    readonly source?: string;
+    /** Stop / SubagentStop. */
+    readonly stop_hook_active?: boolean;
+    /** Any other event-specific fields. */
+    readonly [k: string]: unknown;
+}
+/** The JSON a hook may print on stdout (all fields optional). */
+export interface HookOutput {
+    readonly decision?: "approve" | "block";
+    readonly reason?: string;
+    readonly continue?: boolean;
+    readonly stopReason?: string;
+    readonly suppressOutput?: boolean;
+    readonly systemMessage?: string;
+    readonly hookSpecificOutput?: {
+        readonly hookEventName?: string;
+        readonly permissionDecision?: "allow" | "deny" | "ask";
+        readonly permissionDecisionReason?: string;
+        readonly additionalContext?: string;
+    };
+    readonly [k: string]: unknown;
+}
+export interface RunHookOptions {
+    /** Working directory for the hook process. Default: a value won't be set. */
+    readonly cwd?: string;
+    /** Extra env vars (merged over process.env). `{cwd}` in values is left as-is. */
+    readonly env?: Record<string, string>;
+    /** Per-run timeout ms. Default 10000. */
+    readonly timeoutMs?: number;
+}
+export interface HookRunResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** Parsed stdout JSON if the hook emitted a JSON decision, else null. */
+    readonly json: HookOutput | null;
+    /**
+     * Normalized decision: a deny/block via exit 2, `decision:"block"`, or
+     * `permissionDecision:"deny"` all set `blocked = true`.
+     */
+    readonly blocked: boolean;
+    /**
+     * The decision the hook expressed, preferring the structured
+     * `permissionDecision` ("allow"|"deny"|"ask") then legacy `decision`
+     * ("approve"|"block"), else undefined.
+     */
+    readonly decision: HookOutput["decision"] | "allow" | "deny" | "ask" | undefined;
+}
+/** Parse stdout as a hook JSON decision (pure, testable without a process). */
+export declare function parseHookOutput(stdout: string): HookOutput | null;
+/**
+ * Decide whether a hook result blocked, and the normalized decision. Pure, so
+ * the policy is unit-testable independent of spawning anything.
+ */
+export declare function decideHook(exitCode: number, json: HookOutput | null): {
+    blocked: boolean;
+    decision: HookRunResult["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.
+ */
+export declare function runHook(command: string, input: HookInput, opts?: RunHookOptions): HookRunResult;
+//# sourceMappingURL=run-hook.d.ts.map

package/dist/run-hook.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseHookOutput = parseHookOutput;
+exports.decideHook = decideHook;
+exports.runHook = runHook;
+/**
+ * vigiles — the *unit* tier for Claude Code hooks.
+ *
+ * A hook is just a process: Claude Code pipes a JSON event to its stdin and
+ * reads back an exit code (0 ok, 2 = block) and, optionally, a JSON decision on
+ * stdout. `runHook` exercises exactly that contract directly — no `claude`
+ * binary, no model, no sandbox — so a hook's logic can be unit-tested in
+ * milliseconds:
+ *
+ *   const r = runHook('"$GUARD" ', {
+ *     hook_event_name: "PreToolUse",
+ *     tool_name: "Bash",
+ *     tool_input: { command: "git commit --no-verify" },
+ *   }, { env: { GUARD: guardPath } });
+ *   assert.ok(r.blocked);            // exit 2 / decision:block / permission:deny
+ *
+ * Why this exists alongside `runHarnessTest`:
+ *   - It is the cheap base of the pyramid — no CLI dependency, runs anywhere.
+ *   - It reaches every event. The deterministic `runHarnessTest` mock can drive
+ *     SessionStart/Stop/UserPromptSubmit/Bash PreToolUse|PostToolUse, but NOT
+ *     Edit/Write tool events (headless-gated), PreCompact, Notification,
+ *     SessionEnd, or SubagentStop. At this tier you hand the hook the event
+ *     JSON yourself, so all of them are testable.
+ *
+ * It does NOT prove the hook is *wired* into the harness (that the settings
+ * point at it, that `${CLAUDE_PLUGIN_ROOT}` resolves) — that is what the
+ * `plugin:` loader + `runHarnessTest` cover. Use both: unit-test the hook's
+ * logic here, then assert it fires in the assembled machine there.
+ */
+const node_child_process_1 = require("node:child_process");
+/** Parse stdout as a hook JSON decision (pure, testable without a process). */
+function parseHookOutput(stdout) {
+    const s = stdout.trim();
+    if (!s.startsWith("{"))
+        return null;
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide whether a hook result blocked, and the normalized decision. Pure, so
+ * the policy is unit-testable independent of spawning anything.
+ */
+function decideHook(exitCode, json) {
+    const permission = json?.hookSpecificOutput?.permissionDecision;
+    const decision = permission ?? json?.decision;
+    const blocked = exitCode === 2 || decision === "block" || decision === "deny";
+    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.
+ */
+function runHook(command, input, opts = {}) {
+    const res = (0, node_child_process_1.spawnSync)(command, {
+        shell: true,
+        cwd: opts.cwd,
+        env: { ...process.env, ...opts.env },
+        input: JSON.stringify(input),
+        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 };
+}
+//# sourceMappingURL=run-hook.js.map

package/dist/run-scripts.d.ts

@@ -0,0 +1,20 @@
+export interface ScriptRunResult {
+    readonly file: string;
+    readonly code: number;
+}
+/**
+ * Expand the given path/glob patterns into concrete script files. A pattern
+ * that is an existing file passes through unchanged; anything else is treated
+ * as a glob. Falls back to `defaultGlob` when no patterns are given. Results
+ * are deduped and sorted; `node_modules` and `dist` are always ignored.
+ */
+export declare function discoverScripts(patterns: readonly string[], defaultGlob: string, cwd: string): string[];
+/**
+ * Run each script as `node <file>`, inheriting stdio so the script's own report
+ * streams to the console. `env` is merged over `process.env` for every child
+ * (e.g. `VIGILES_TRIALS`). Returns the per-file exit codes.
+ */
+export declare function runScripts(files: readonly string[], cwd: string, env?: NodeJS.ProcessEnv): ScriptRunResult[];
+/** Format a one-line-per-file run summary with a pass/fail tally. */
+export declare function formatScriptSummary(results: readonly ScriptRunResult[]): string;
+//# sourceMappingURL=run-scripts.d.ts.map

package/dist/run-scripts.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverScripts = discoverScripts;
+exports.runScripts = runScripts;
+exports.formatScriptSummary = formatScriptSummary;
+/**
+ * vigiles — run harness-test / eval script files via the CLI.
+ *
+ * `vigiles test` and `vigiles eval` discover `*.harness.mjs` / `*.eval.mjs`
+ * 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`. The scripts stay plain Node modules (they
+ * import from the built `dist/`), so they also run standalone — the CLI just
+ * discovers, runs, and aggregates exit codes.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const glob_1 = require("glob");
+/**
+ * Expand the given path/glob patterns into concrete script files. A pattern
+ * that is an existing file passes through unchanged; anything else is treated
+ * as a glob. Falls back to `defaultGlob` when no patterns are given. Results
+ * are deduped and sorted; `node_modules` and `dist` are always ignored.
+ */
+function discoverScripts(patterns, defaultGlob, cwd) {
+    const globs = patterns.length > 0 ? patterns : [defaultGlob];
+    const found = new Set();
+    for (const p of globs) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, p))) {
+            found.add(p);
+            continue;
+        }
+        for (const m of (0, glob_1.globSync)(p, {
+            cwd,
+            ignore: ["node_modules/**", "dist/**"],
+        })) {
+            found.add(m);
+        }
+    }
+    return [...found].sort();
+}
+/**
+ * Run each script as `node <file>`, inheriting stdio so the script's own report
+ * streams to the console. `env` is merged over `process.env` for every child
+ * (e.g. `VIGILES_TRIALS`). Returns the per-file exit codes.
+ */
+function runScripts(files, cwd, env = {}) {
+    const results = [];
+    for (const file of files) {
+        const res = (0, node_child_process_1.spawnSync)("node", [file], {
+            cwd,
+            stdio: "inherit",
+            env: { ...process.env, ...env },
+        });
+        results.push({ file, code: res.status ?? 1 });
+    }
+    return results;
+}
+/** Format a one-line-per-file run summary with a pass/fail tally. */
+function formatScriptSummary(results) {
+    const lines = results.map((r) => `  ${r.code === 0 ? "✓" : "✗"} ${r.file}` +
+        (r.code === 0 ? "" : ` (exit ${String(r.code)})`));
+    const failed = results.filter((r) => r.code !== 0).length;
+    lines.push(failed === 0
+        ? `\n${String(results.length)} passed.`
+        : `\n${String(failed)}/${String(results.length)} failed.`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=run-scripts.js.map

package/dist/vitest.d.mts

@@ -0,0 +1,9 @@
+declare module "@vitest/expect" {
+    interface Matchers<T = any> {
+        toHaveCreated(path: string): T;
+        toBlock(): T;
+        toBeatBaseline(baseline: string, arm: string, metric: string, by?: number): T;
+    }
+}
+export {};
+//# sourceMappingURL=vitest.d.mts.map

package/dist/vitest.mjs

@@ -0,0 +1,22 @@
+/* eslint-disable max-params, @typescript-eslint/no-explicit-any --
+   The matcher signatures mirror the runtime vigilesMatchers (positional args),
+   and `Matchers<T = any>` must match @vitest/expect's generic default to merge. */
+/**
+ * vigiles — vitest integration (opt-in). ESM, because vitest is ESM-only.
+ *
+ * Importing this entry registers the vigiles matchers AND augments vitest's
+ * types so `toHaveCreated` / `toBeatBaseline` type-check.
+ *
+ *   // vitest.config.ts →  test: { setupFiles: ["vigiles/vitest"] }
+ *   // …or at the top of a test file:
+ *   import "vigiles/vitest";
+ *
+ *   expect(result).toHaveCreated("DONE");
+ *   expect(report).toBeatBaseline("vanilla", "gated", "caught");
+ *
+ * vitest is an optional peer dependency — only vitest users load this entry.
+ */
+import { expect } from "vitest";
+import { vigilesMatchers } from "./harness-assert.js";
+expect.extend(vigilesMatchers);
+//# sourceMappingURL=vitest.mjs.map