vigiles 2.1.1 → 2.3.0

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/refs.d.ts

@@ -0,0 +1,44 @@
+/** An inline code span with its 1-based source line. */
+export interface Span {
+    readonly text: string;
+    readonly line: number;
+}
+/**
+ * Extract inline code spans, skipping fenced code blocks (R1). Returns each
+ * span's trimmed text and 1-based line.
+ */
+export declare function inlineSpans(markdown: string): Span[];
+/** A parsed file-qualified reference. */
+export interface SymbolRef {
+    readonly file: string;
+    readonly symbol: string;
+    readonly line: number;
+}
+/** A reference that failed verification. */
+export interface SymbolRefError extends SymbolRef {
+    readonly reason: string;
+}
+/** Extract the `vigiles:symbol` references from a markdown file. */
+export declare function symbolRefs(markdown: string): SymbolRef[];
+/**
+ * Verify the file-qualified symbol references in a markdown file: the named
+ * file must exist and define the named symbol. `basePath` is the directory the
+ * paths resolve against (the instruction file's own directory).
+ */
+export declare function verifySymbolRefs(markdown: string, basePath: string): SymbolRefError[];
+/**
+ * Whether a span looks like a *code reference* that ought to carry a
+ * file-qualified mark — a scoped name, or an identifier that isn't a bare
+ * lowercase prose word. A function-call form `` `foo(args)` `` is treated as a
+ * reference to its callee `foo`. Paths/filenames are excluded (they are `file`
+ * refs).
+ */
+export declare function isCodeShaped(text: string): boolean;
+/**
+ * Code-shaped inline references that are NOT yet marked — the spans the
+ * enforcement hook makes the agent mark as `` `vigiles:symbol path.ext#symbol` ``
+ * or opt out of with `<!-- vigiles:ignore -->` (or `<!-- vigiles:ignore-file -->`
+ * for the whole file).
+ */
+export declare function unmarkedCodeRefs(markdown: string): Span[];
+//# sourceMappingURL=refs.d.ts.map

package/dist/refs.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inlineSpans = inlineSpans;
+exports.symbolRefs = symbolRefs;
+exports.verifySymbolRefs = verifySymbolRefs;
+exports.isCodeShaped = isCodeShaped;
+exports.unmarkedCodeRefs = unmarkedCodeRefs;
+/**
+ * vigiles — file-qualified symbol reference verification (variant A).
+ *
+ * A reference names both the file and the symbol, as an inline code span:
+ *
+ *     See `src/config.ts#parseConfig` for the loader.
+ *     Render with `app/models/user.rb#full_name`.
+ *
+ * We parse *that one named file* and check it defines the symbol. No
+ * project-wide index, no cross-file resolution, no autoloader chasing, no
+ * ambiguity (the file disambiguates). Because the `path.ext#symbol` shape is
+ * unmistakable and deliberately written, it is a *declared* reference — like
+ * `vigiles:file` / `vigiles:cmd` — so a broken one is an **error**, not an
+ * inferred-prose warning. The author names the file; vigiles proves the symbol.
+ *
+ * R1 (cross-compat): only inline code spans are read. Fenced code blocks are
+ * never touched, so rustdoc doctests / typescript-docs-verifier keep working.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const symbols_js_1 = require("./symbols.js");
+const FENCE = /^\s*```/;
+const SPAN = /`([^`\n]+)`/g;
+/**
+ * Extract inline code spans, skipping fenced code blocks (R1). Returns each
+ * span's trimmed text and 1-based line.
+ */
+function inlineSpans(markdown) {
+    const spans = [];
+    let inFence = false;
+    const lines = markdown.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        if (FENCE.test(lines[i])) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        for (const m of lines[i].matchAll(SPAN)) {
+            spans.push({ text: m[1].trim(), line: i + 1 });
+        }
+    }
+    return spans;
+}
+// A file-qualified symbol reference: `<path>.<ext>` then `#`/`::` then a symbol.
+// Requires a real file extension before the separator, so a bare scoped symbol
+// An explicit `vigiles:symbol <path>.<ext>#<symbol>` directive inside a code
+// span. The literal `vigiles:symbol` prefix means zero detection heuristic — a
+// span either carries it or it does not — consistent with the rest of vigiles'
+// markers. The mark is self-contained (file + symbol in one inline token), so
+// it binds unambiguously even in a long line with several references.
+const SYMBOL_MARK = /^vigiles:symbol\s+([\w@./-]+\.[A-Za-z0-9]+)(?:#|::)([A-Za-z_]\w*[?!]?)$/;
+/** Extract the `vigiles:symbol` references from a markdown file. */
+function symbolRefs(markdown) {
+    const refs = [];
+    for (const span of inlineSpans(markdown)) {
+        const m = SYMBOL_MARK.exec(span.text);
+        if (m)
+            refs.push({ file: m[1], symbol: m[2], line: span.line });
+    }
+    return refs;
+}
+/**
+ * Verify the file-qualified symbol references in a markdown file: the named
+ * file must exist and define the named symbol. `basePath` is the directory the
+ * paths resolve against (the instruction file's own directory).
+ */
+function verifySymbolRefs(markdown, basePath) {
+    const errors = [];
+    for (const ref of symbolRefs(markdown)) {
+        const full = (0, node_path_1.resolve)(basePath, ref.file);
+        if (!(0, node_fs_1.existsSync)(full)) {
+            errors.push({ ...ref, reason: `File not found: "${ref.file}"` });
+        }
+        else if ((0, symbols_js_1.langForFile)(ref.file) === null) {
+            errors.push({
+                ...ref,
+                reason: `Unsupported language for symbol check: "${ref.file}"`,
+            });
+        }
+        else if (!(0, symbols_js_1.fileDefinesSymbol)(full, ref.symbol)) {
+            errors.push({
+                ...ref,
+                reason: `"${ref.symbol}" is not defined in ${ref.file}`,
+            });
+        }
+    }
+    return errors;
+}
+// ---------------------------------------------------------------------------
+// Enforcement: force code references to carry the file-qualified mark
+// ---------------------------------------------------------------------------
+const PATH_LIKE = /[/\\]|\.[A-Za-z0-9]+$/; // a path or a bare filename
+const PLAIN_ID = /^[A-Za-z_]\w*$/;
+const SCOPED = /^[A-Za-z_]\w*(?:#|::)[\w?!]+$/;
+const IGNORE_FILE = /<!--\s*vigiles:ignore-file\s*-->/;
+const IGNORE_LINE = /<!--\s*vigiles:ignore\s*-->/;
+/**
+ * Whether a span looks like a *code reference* that ought to carry a
+ * file-qualified mark — a scoped name, or an identifier that isn't a bare
+ * lowercase prose word. A function-call form `` `foo(args)` `` is treated as a
+ * reference to its callee `foo`. Paths/filenames are excluded (they are `file`
+ * refs).
+ */
+function isCodeShaped(text) {
+    const callee = text.replace(/\s*\([^)]*\)\s*$/, ""); // `foo(args)` → `foo`
+    if (SCOPED.test(callee))
+        return true;
+    if (!PLAIN_ID.test(callee))
+        return false;
+    const hasUnderscore = callee.includes("_");
+    const hasCamel = /[a-z][A-Z]/.test(callee);
+    const isPascal = /^[A-Z][a-z]/.test(callee);
+    const isScreaming = /^[A-Z][A-Z0-9_]+$/.test(callee);
+    return hasUnderscore || hasCamel || isPascal || isScreaming;
+}
+/**
+ * Code-shaped inline references that are NOT yet marked — the spans the
+ * enforcement hook makes the agent mark as `` `vigiles:symbol path.ext#symbol` ``
+ * or opt out of with `<!-- vigiles:ignore -->` (or `<!-- vigiles:ignore-file -->`
+ * for the whole file).
+ */
+function unmarkedCodeRefs(markdown) {
+    if (IGNORE_FILE.test(markdown))
+        return [];
+    const lines = markdown.split("\n");
+    return inlineSpans(markdown).filter((span) => {
+        if (IGNORE_LINE.test(lines[span.line - 1] ?? ""))
+            return false;
+        if (SYMBOL_MARK.test(span.text))
+            return false; // already a vigiles:symbol mark
+        if (PATH_LIKE.test(span.text))
+            return false; // a path/filename → file ref
+        return isCodeShaped(span.text);
+    });
+}
+//# sourceMappingURL=refs.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