vigiles 2.2.0 → 2.4.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/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Compile .spec.ts files to instruction files (CLAUDE.md, AGENTS.md) with linter cross-referencing",
   "bin": {
     "vigiles": "dist/cli.js"
@@ -14,11 +14,23 @@
     "./linters": "./dist/linters.js",
     "./eval": "./dist/eval.js",
     "./harness-test": "./dist/harness-test.js",
-    "./mock-model": "./dist/mock-model.js"
+    "./harness-assert": "./dist/harness-assert.js",
+    "./run-hook": "./dist/run-hook.js",
+    "./plugin-loader": "./dist/plugin-loader.js",
+    "./mcp": "./dist/mcp.js",
+    "./judge": "./dist/judge.js",
+    "./mock-model": "./dist/mock-model.js",
+    "./vitest": {
+      "types": "./dist/vitest.d.mts",
+      "default": "./dist/vitest.mjs"
+    },
+    "./jest": "./dist/jest.js"
   },
   "files": [
     "dist/**/*.js",
+    "dist/**/*.mjs",
     "dist/**/*.d.ts",
+    "dist/**/*.d.mts",
     "!dist/**/*.test.js",
     "!dist/**/*.test.d.ts",
     "action.yml",
@@ -28,11 +40,17 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test dist/spec.test.js dist/validate.test.js dist/cli.test.js dist/proofs.test.js dist/inline.test.js dist/sidecar.test.js dist/coverage.test.js dist/session.test.js dist/orphans.test.js dist/cedar.test.js dist/doc-refs.test.js dist/frontmatter.test.js dist/skill-pipeline.test.js dist/skill-runtime.test.js dist/skill-driver.test.js dist/skill-test.test.js dist/compile-generator.test.js dist/community-skills.test.js dist/action-gate.test.js dist/symbols.test.js dist/refs.test.js dist/harness-test.test.js dist/eval.test.js",
+    "test": "npm run build && node --test dist/spec.test.js dist/validate.test.js dist/cli.test.js dist/proofs.test.js dist/inline.test.js dist/sidecar.test.js dist/coverage.test.js dist/session.test.js dist/orphans.test.js dist/cedar.test.js dist/doc-refs.test.js dist/frontmatter.test.js dist/skill-pipeline.test.js dist/skill-runtime.test.js dist/skill-driver.test.js dist/skill-test.test.js dist/compile-generator.test.js dist/community-skills.test.js dist/action-gate.test.js dist/symbols.test.js dist/refs.test.js dist/harness-test.test.js dist/eval.test.js dist/run-scripts.test.js dist/plugin-loader.test.js dist/harness-assert.test.js dist/judge.test.js dist/run-hook.test.js dist/mcp.test.js",
     "lint": "eslint src/",
     "fmt": "prettier --write .",
     "fmt:check": "prettier --check .",
-    "test:e2e": "bash test/e2e/run.sh"
+    "demo": "npm run build && bash examples/demo/run.sh",
+    "test:e2e": "bash test/e2e/run.sh",
+    "test:harness": "npm run build && node dist/cli.js test",
+    "test:eval": "npm run build && node dist/cli.js eval",
+    "test:vitest": "npm run build && vitest run",
+    "test:jest": "npm run build && jest",
+    "test:types": "npm run build && tsc --noEmit -p test/types/tsconfig.json"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -44,9 +62,23 @@
     "eslint": "^10.1.0",
     "eslint-plugin-sonarjs": "^4.0.2",
     "globals": "^17.4.0",
+    "jest": "^30.4.2",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "jest": ">=28",
+    "vitest": ">=1"
+  },
+  "peerDependenciesMeta": {
+    "jest": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@ast-grep/lang-python": "^0.0.6",