vigiles 5.2.0 → 7.0.0

package/dist/core/hook-providers.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_PROVIDERS = exports.provider = exports.defineProvider = exports.dangerously = exports.provide = void 0;
+exports.unknownProviders = unknownProviders;
+exports.unsafeInlineProviders = unsafeInlineProviders;
+exports.unsafeProvider = unsafeProvider;
+exports.gatherContext = gatherContext;
+/**
+ * Hook CONTEXT PROVIDERS — let a compiled gate decide on EXTERNAL STATE (git
+ * branch, working-tree dirtiness, cwd, OS) WITHOUT breaking `capability = API
+ * surface`. The design (research/hook-context-providers.md, grounded in
+ * Cedar/OPA/Gatekeeper): the pure `decide` never fetches; the TRUSTED runtime
+ * gathers a DECLARED set of read-only facts and hands them in as `e.ctx`. A hook
+ * declares `needs: [...]`, so the dependency is explicit + auditable, and the
+ * fact-gathering I/O lives here (the trusted host), never inside the hook.
+ *
+ * Two tiers of `needs` entry, both DECLARED (the opt-out ladder):
+ *  - a built-in provider NAME (`"git.branch"`) — the curated, famous-80% set;
+ *  - an INLINE one-off — `provide(name, cmd)` (read-only, compile-rejected if not)
+ *    or `dangerously(name, cmd)` (the loud, greppable escape for a command that
+ *    isn't provably read-only) — for the long tail, no registration ceremony.
+ *
+ * Every built-in command is provably read-only (asserted in the test via
+ * bash-effects); a `provide()` command is checked the same way at compile. The
+ * gathering is parameterized over an injected `ProviderIO`, so the registry is
+ * testable with a fake exec and core depends on no child_process.
+ */
+const bash_effects_js_1 = require("./bash-effects.js");
+/**
+ * Declare an INLINE read-only fact: `provide("k8sCtx", "kubectl config current-context")`.
+ * The command MUST be provably read-only (compile rejects it otherwise — use
+ * {@link dangerously} to acknowledge a side-effecting/undecidable one). Its stdout
+ * is `e.ctx[name]`.
+ */
+const provide = (name, run) => ({ kind: "inline", name, run, dangerous: false });
+exports.provide = provide;
+/**
+ * Declare an INLINE fact whose command ISN'T provably read-only — the loud,
+ * greppable escape hatch (the `dangerouslySetInnerHTML` / `unsafe` / `http.send`
+ * convention; sibling of `purity:'dangerously-unrestricted'`). A security review
+ * searches for this one word.
+ */
+const dangerously = (name, run) => ({ kind: "inline", name, run, dangerous: true });
+exports.dangerously = dangerously;
+/** Author a registered provider: `export default defineProvider({ name, run })`. */
+const defineProvider = (p) => ({
+    kind: "provider-def",
+    name: p.name,
+    run: p.run,
+    dangerous: p.dangerous ?? false,
+});
+exports.defineProvider = defineProvider;
+/** Reference a registered provider (from `.vigiles/providers/`) by name in `needs`. */
+const provider = (name) => ({ kind: "provider-ref", name });
+exports.provider = provider;
+/** Run a command and trim, returning "" on any failure (total). */
+function tryExec(io, command) {
+    try {
+        return io.exec(command).trim();
+    }
+    catch {
+        return "";
+    }
+}
+/** The closed built-in registry. Each `run` is provably read-only (see the test). */
+exports.BUILTIN_PROVIDERS = {
+    "git.branch": {
+        run: "git branch --show-current",
+        gather: (io) => tryExec(io, "git branch --show-current"),
+    },
+    "git.isDirty": {
+        run: "git status --porcelain",
+        gather: (io) => tryExec(io, "git status --porcelain").length > 0,
+    },
+    "git.root": {
+        run: "git rev-parse --show-toplevel",
+        gather: (io) => tryExec(io, "git rev-parse --show-toplevel"),
+    },
+    cwd: {
+        gather: (io) => io.cwd,
+    },
+    "os.platform": {
+        gather: (io) => io.platform,
+    },
+    "env.isCI": {
+        gather: (io) => io.isCI,
+    },
+};
+/** True iff a `needs` entry is an inline `provide`/`dangerously`. */
+function isInline(need) {
+    return typeof need !== "string" && need.kind === "inline";
+}
+/** True iff a `needs` entry is a `provider()` reference to a registered provider. */
+function isRef(need) {
+    return typeof need !== "string" && need.kind === "provider-ref";
+}
+/**
+ * `needs` entries that don't resolve: a built-in NAME that isn't a built-in (a
+ * typo), or a `provider()` ref whose name isn't in `registeredNames` (a dangling
+ * ref). Inline `provide`/`dangerously` are always self-defined, so never flagged.
+ */
+function unknownProviders(needs, registeredNames = []) {
+    const registered = new Set(registeredNames);
+    const out = [];
+    for (const n of needs) {
+        if (isInline(n))
+            continue;
+        if (isRef(n)) {
+            if (!registered.has(n.name))
+                out.push(n.name);
+        }
+        else if (!(n in exports.BUILTIN_PROVIDERS))
+            out.push(n);
+    }
+    return out;
+}
+/**
+ * Inline `provide()` entries whose command ISN'T provably read-only — these must
+ * switch to `dangerously()` (the acknowledged escape) or compile is rejected. A
+ * `dangerously()` entry is never flagged (it already acknowledged the risk).
+ */
+function unsafeInlineProviders(needs) {
+    return needs
+        .filter(isInline)
+        .filter((n) => !n.dangerous && !(0, bash_effects_js_1.isReadOnlyBash)(n.run));
+}
+/**
+ * Is a REGISTERED provider's command unsafe (not read-only and not acknowledged
+ * `dangerous`)? Reused when compiling a `.vigiles/providers/` file.
+ */
+function unsafeProvider(def) {
+    return !def.dangerous && !(0, bash_effects_js_1.isReadOnlyBash)(def.run);
+}
+/**
+ * Gather the DECLARED facts into a context object (the trusted-host step). Only
+ * the names in `needs` are gathered, each at most once; a built-in, inline, or
+ * registered provider that can't resolve yields its default ("" / false), never
+ * throws. Pure over the injected `io` (CLI passes a real execSync; tests a fake)
+ * and the `registry` (the loaded `.vigiles/providers/`, for `provider()` refs).
+ */
+function gatherContext(needs, io, registry = {}) {
+    const ctx = {};
+    for (const need of needs) {
+        if (isInline(need))
+            ctx[need.name] = tryExec(io, need.run);
+        else if (isRef(need)) {
+            const def = registry[need.name];
+            ctx[need.name] = def ? tryExec(io, def.run) : "";
+        }
+        else
+            ctx[need] = exports.BUILTIN_PROVIDERS[need].gather(io);
+    }
+    return ctx;
+}
+//# sourceMappingURL=hook-providers.js.map

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

@@ -0,0 +1,74 @@
+/** A hook's declared side-effect posture. */
+export type HookEffect = "observe" | "mutate";
+/** A declared hook (the typed source the compiler reads). */
+export interface HookSpec {
+    /** The harness event, e.g. "PreToolUse" | "PostToolUse". */
+    readonly event: string;
+    /** The tool name(s) the hook matches, e.g. ["Bash"] or ["Edit", "Write"]. */
+    readonly match: readonly string[];
+    /** The `tool_input` fields the hook extracts (must exist on the matched tools). */
+    readonly reads: readonly string[];
+    /** Observe-only (a gate/checker) or allowed to mutate (an action runner). */
+    readonly effect: HookEffect;
+    /** Optional command the hook runs — classified against {@link effect}. */
+    readonly run?: string;
+}
+/** Build a hook spec (the untyped on-ramp; see `hookFor` for the typed one). */
+export declare const hook: (spec: HookSpec) => HookSpec;
+/** tool name → the `tool_input` fields it carries (injected; harness-specific). */
+export type ToolFieldCatalog = Record<string, readonly string[]>;
+export interface HookIssue {
+    readonly severity: "error" | "warning";
+    readonly message: string;
+}
+export interface ValidateHookOptions {
+    /** The per-tool `tool_input` field catalog for the active harness. */
+    readonly toolFields: ToolFieldCatalog;
+    /** The harness's known event names (optional — skips the event check if absent). */
+    readonly events?: readonly string[];
+}
+/**
+ * Validate a hook spec — the compiler half. Flags wrong-field extraction (Check 1)
+ * and effect misdeclaration (Check 2), plus an unknown event when `events` is given.
+ * Pure; the same checks `compileHook` enforces before emitting.
+ */
+export declare function validateHook(spec: HookSpec, opts: ValidateHookOptions): HookIssue[];
+/** A settings `hooks` block keyed by the spec's event (the generated artifact). */
+export interface CompiledHook {
+    readonly hooks: Record<string, readonly {
+        readonly matcher: string;
+        readonly hooks: readonly {
+            readonly type: "command";
+            readonly command: string;
+        }[];
+    }[]>;
+    /** field → the extraction expression a generated hook would use (the typed read). */
+    readonly extractions: Record<string, string>;
+}
+export declare class HookCompileError extends Error {
+}
+/**
+ * Compile a validated hook to its settings block. Refuses (throws) on any error-level
+ * issue — "an unsafe hook doesn't compile" — so a wrong-field read or a mutating
+ * observe-hook never ships. The `extractions` map shows the correctly-typed field
+ * reads the generated hook uses (here as jq paths) — never a hand-typed `jq` string.
+ */
+export declare function compileHook(spec: HookSpec, opts: ValidateHookOptions & {
+    gateCommand?: string;
+}): CompiledHook;
+/**
+ * The typed source for a hook over a field map `M` (tool → field-union) and the
+ * matched tool(s) `T`. `reads` is constrained to the fields of `T` — a field absent
+ * from the matched tool is a tsc error. `M` stays unconstrained so a plain interface
+ * (no index signature) works as the field map.
+ */
+export interface TypedHookSpec<M, T extends keyof M & string> {
+    readonly event: string;
+    readonly match: readonly T[];
+    readonly reads: readonly Extract<M[T], string>[];
+    readonly effect: HookEffect;
+    readonly run?: string;
+}
+/** Build a typed hook; `reads` outside the matched tool's field-union won't compile. */
+export declare function hookFor<M, T extends keyof M & string>(spec: TypedHookSpec<M, T>): HookSpec;
+//# sourceMappingURL=hook-spec.d.ts.map

package/dist/core/hook-spec.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HookCompileError = exports.hook = void 0;
+exports.validateHook = validateHook;
+exports.compileHook = compileHook;
+exports.hookFor = hookFor;
+/**
+ * SPIKE — typed, effect-classified HOOKS (the "type-safe bash" angle).
+ *
+ * A Claude Code / Codex hook today is hand-written shell in settings.json. Two
+ * silent footguns dominate, and both are exactly what a COMPILER catches:
+ *
+ *  1. WRONG-FIELD EXTRACTION (silent no-op). A PreToolUse event's `tool_input`
+ *     shape depends on the matched tool — `Bash` carries `command`, `Edit`/`Write`
+ *     carry `file_path`. A hook that matches `Bash` but does
+ *     `jq '.tool_input.file_path'` extracts EMPTY forever and never fires; nothing
+ *     tells you. `validateHook` makes "read a field the matched tool never provides"
+ *     an error, and the typed `hookFor` builder makes it a tsc error at edit time.
+ *
+ *  2. EFFECT MISDECLARATION ("type-safe bash"). A hook declared observe-only (a
+ *     read-only gate/checker) that actually RUNS a mutating command — `eslint --fix`,
+ *     `git push` — is a side effect masquerading as an observation. We already own a
+ *     deterministic Bash-effect classifier (`bash-effects.ts`), so the command's
+ *     effect class becomes a TYPE: an `effect: "observe"` hook whose `run` command
+ *     classifies as side-effecting/undecidable does NOT compile. No other plugin
+ *     tool has the classifier to make that judgment.
+ *
+ * Pure core, harness-agnostic: the per-tool field catalog is INJECTED (a Codex hook
+ * has different fields), and the Bash classifier is the harness-neutral one. The CC
+ * field catalog + the typed edit-time builder live in the test (no CC literal in core).
+ *
+ * NOT wired to the CLI/public API — a spike to see whether the compile step earns its
+ * keep on the hook surface. See research/harness-protocol-flow-moat.md.
+ */
+const bash_effects_js_1 = require("./bash-effects.js");
+/** Build a hook spec (the untyped on-ramp; see `hookFor` for the typed one). */
+const hook = (spec) => spec;
+exports.hook = hook;
+/** Which matched tools actually carry `field`. */
+function toolsProviding(field, match, toolFields) {
+    return match.filter((t) => (toolFields[t] ?? []).includes(field));
+}
+/** Check 1 — every read field exists on the matched tool(s). */
+function fieldIssues(spec, toolFields) {
+    const out = [];
+    for (const field of spec.reads) {
+        const providers = toolsProviding(field, spec.match, toolFields);
+        if (providers.length === 0) {
+            out.push({
+                severity: "error",
+                message: `reads "${field}" but no matched tool (${spec.match.join("|")}) provides it — the extraction is always empty (silent no-op)`,
+            });
+        }
+        else if (providers.length < spec.match.length) {
+            const missing = spec.match.filter((t) => !providers.includes(t));
+            out.push({
+                severity: "warning",
+                message: `reads "${field}", which ${missing.join("/")} does not carry — empty on those events`,
+            });
+        }
+    }
+    return out;
+}
+/** Check 2 — an observe-only hook's command must be provably read-only. */
+function effectIssues(spec) {
+    if (spec.effect !== "observe" || spec.run === undefined)
+        return [];
+    const cls = (0, bash_effects_js_1.classifyBashCommand)(spec.run);
+    if (cls === "read-only")
+        return [];
+    return [
+        {
+            severity: "error",
+            message: `declared observe-only but its command is ${cls}: "${spec.run}" — an observe hook must not mutate (use effect:"mutate" or a read-only command)`,
+        },
+    ];
+}
+/**
+ * Validate a hook spec — the compiler half. Flags wrong-field extraction (Check 1)
+ * and effect misdeclaration (Check 2), plus an unknown event when `events` is given.
+ * Pure; the same checks `compileHook` enforces before emitting.
+ */
+function validateHook(spec, opts) {
+    const out = [];
+    if (opts.events && !opts.events.includes(spec.event)) {
+        out.push({
+            severity: "error",
+            message: `unknown event "${spec.event}" — it will never fire`,
+        });
+    }
+    out.push(...fieldIssues(spec, opts.toolFields));
+    out.push(...effectIssues(spec));
+    return out;
+}
+class HookCompileError extends Error {
+}
+exports.HookCompileError = HookCompileError;
+/**
+ * Compile a validated hook to its settings block. Refuses (throws) on any error-level
+ * issue — "an unsafe hook doesn't compile" — so a wrong-field read or a mutating
+ * observe-hook never ships. The `extractions` map shows the correctly-typed field
+ * reads the generated hook uses (here as jq paths) — never a hand-typed `jq` string.
+ */
+function compileHook(spec, opts) {
+    const issues = validateHook(spec, opts);
+    const errors = issues.filter((i) => i.severity === "error");
+    if (errors.length > 0) {
+        throw new HookCompileError(`hook does not compile:\n  ${errors.map((e) => e.message).join("\n  ")}`);
+    }
+    const command = opts.gateCommand ?? "npx vigiles hook-runtime guard";
+    const extractions = {};
+    for (const field of spec.reads)
+        extractions[field] = `.tool_input.${field}`;
+    return {
+        hooks: {
+            [spec.event]: [
+                {
+                    matcher: spec.match.join("|"),
+                    hooks: [{ type: "command", command }],
+                },
+            ],
+        },
+        extractions,
+    };
+}
+/** Build a typed hook; `reads` outside the matched tool's field-union won't compile. */
+function hookFor(spec) {
+    return spec;
+}
+//# sourceMappingURL=hook-spec.js.map

package/dist/core/inline.js

@@ -53,7 +53,7 @@ const KNOWN_NON_RULE_MARKERS = new Set([
     "disable",
     "ignore",
     "ignore-file",
-    "gate", // skill step gate (src/skill-runtime.ts)
+    "gate", // skill step gate (src/adapters/claude-code/skill-runtime.ts)
     "result", // skill result gate
     "symbol", // symbol reference mark (src/refs.ts)
 ]);

package/dist/core/mcp-tool.d.ts

@@ -40,6 +40,18 @@ export interface McpToolIssue {
  * A `Tool(restriction)` suffix is stripped first.
  */
 export declare function mcpToolServer(raw: string, dialect: HarnessDialect): string | null;
+/**
+ * Split a direct `mcp__<server>__<tool>` reference into its `{ server, tool }`
+ * parts, or null when {@link mcpToolServer} declines it (non-MCP, plugin-namespaced,
+ * malformed). The tool segment is everything after `mcp__<server>__` (MCP tool
+ * names may themselves contain `__`). A `Tool(restriction)` suffix is stripped.
+ * Used by the LIVE contract-tool resolution (`verifyMcpContractTools` in mcp.ts) to
+ * check the tool actually exists on the server, not just that the server resolves.
+ */
+export declare function mcpToolParts(raw: string, dialect: HarnessDialect): {
+    server: string;
+    tool: string;
+} | null;
 /**
  * Verify the MCP tool references in a contract against the plugin's declared MCP
  * servers. Returns one {@link McpToolIssue} per direct `mcp__<server>__<tool>`

package/dist/core/mcp-tool.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mcpToolServer = mcpToolServer;
+exports.mcpToolParts = mcpToolParts;
 exports.verifyMcpToolServers = verifyMcpToolServers;
 /**
  * The server segment of a direct `mcp__<server>__<tool>` reference, or null when
@@ -23,6 +24,25 @@ function mcpToolServer(raw, dialect) {
         return null;
     return server;
 }
+/**
+ * Split a direct `mcp__<server>__<tool>` reference into its `{ server, tool }`
+ * parts, or null when {@link mcpToolServer} declines it (non-MCP, plugin-namespaced,
+ * malformed). The tool segment is everything after `mcp__<server>__` (MCP tool
+ * names may themselves contain `__`). A `Tool(restriction)` suffix is stripped.
+ * Used by the LIVE contract-tool resolution (`verifyMcpContractTools` in mcp.ts) to
+ * check the tool actually exists on the server, not just that the server resolves.
+ */
+function mcpToolParts(raw, dialect) {
+    const clean = raw.split("(")[0].trim();
+    const server = mcpToolServer(clean, dialect);
+    if (server === null)
+        return null;
+    const prefix = `mcp__${server}__`;
+    if (!clean.startsWith(prefix))
+        return null;
+    const tool = clean.slice(prefix.length);
+    return tool ? { server, tool } : null;
+}
 /**
  * Verify the MCP tool references in a contract against the plugin's declared MCP
  * servers. Returns one {@link McpToolIssue} per direct `mcp__<server>__<tool>`

package/dist/core/mcp.d.ts

@@ -43,6 +43,19 @@ export declare function loadMcpServers(cwd: string): Record<string, McpServerCon
  * to an undeclared server, an unreachable server, or a missing tool is an error.
  */
 export declare function verifyMcpRefs(markdown: string, mcpServers: Record<string, McpServerConfig>, timeoutMs?: number): Promise<McpRefError[]>;
+export type McpContractToolReason = "server-unreachable" | "tool-missing";
+export interface McpContractToolError {
+    /** The full `mcp__server__tool` reference (restriction suffix stripped). */
+    readonly tool: string;
+    readonly server: string;
+    /** The tool segment (what's looked up on the server). */
+    readonly toolName: string;
+    readonly reason: McpContractToolReason;
+    readonly suggestions: string[];
+}
+export declare function verifyMcpContractTools(tools: readonly string[], servers: Record<string, McpServerConfig>, dialect: import("./dialect.js").HarnessDialect, timeoutMs?: number): Promise<McpContractToolError[]>;
+/** Human-readable message for a contract-tool error (with "did you mean"). */
+export declare function mcpContractToolMessage(e: McpContractToolError): string;
 /** Human-readable message for an MCP reference error (with "did you mean"). */
 export declare function mcpRefMessage(e: McpRefError): string;
 //# sourceMappingURL=mcp.d.ts.map

package/dist/core/mcp.js

@@ -5,6 +5,8 @@ exports.verifyMcpTool = verifyMcpTool;
 exports.parseMcpRefs = parseMcpRefs;
 exports.loadMcpServers = loadMcpServers;
 exports.verifyMcpRefs = verifyMcpRefs;
+exports.verifyMcpContractTools = verifyMcpContractTools;
+exports.mcpContractToolMessage = mcpContractToolMessage;
 exports.mcpRefMessage = mcpRefMessage;
 /**
  * Minimal MCP client over stdio — start a server, do the JSON-RPC handshake, and
@@ -21,6 +23,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const refs_js_1 = require("./refs.js");
 const hash_js_1 = require("./hash.js");
+const mcp_tool_js_1 = require("./mcp-tool.js");
 function dispatch(line, pending) {
     let msg;
     try {
@@ -229,6 +232,70 @@ async function verifyMcpRefs(markdown, mcpServers, timeoutMs = 10000) {
     }
     return all;
 }
+/** Group the direct, declared-server `mcp__server__tool` refs by server (de-duped). */
+function groupContractTools(tools, servers, dialect) {
+    const byServer = new Map();
+    const seen = new Set();
+    for (const raw of tools) {
+        const parts = (0, mcp_tool_js_1.mcpToolParts)(raw, dialect);
+        if (!parts || !(parts.server in servers))
+            continue; // skip non-MCP/undeclared
+        const full = raw.split("(")[0].trim();
+        if (seen.has(full))
+            continue;
+        seen.add(full);
+        const arr = byServer.get(parts.server) ?? [];
+        arr.push({ full, toolName: parts.tool });
+        byServer.set(parts.server, arr);
+    }
+    return byServer;
+}
+/** Start one server and check its group of referenced tools against the live list. */
+async function checkServerGroup(server, group, cfg, timeoutMs) {
+    let available;
+    try {
+        available = (await listMcpTools(cfg, timeoutMs)).map((t) => t.name);
+    }
+    catch {
+        return group.map((g) => ({
+            tool: g.full,
+            server,
+            toolName: g.toolName,
+            reason: "server-unreachable",
+            suggestions: [],
+        }));
+    }
+    return group
+        .filter((g) => !available.includes(g.toolName))
+        .map((g) => ({
+        tool: g.full,
+        server,
+        toolName: g.toolName,
+        reason: "tool-missing",
+        suggestions: closest(g.toolName, available),
+    }));
+}
+async function verifyMcpContractTools(tools, servers, dialect, timeoutMs = 10000) {
+    const byServer = groupContractTools(tools, servers, dialect);
+    const errors = [];
+    for (const [server, group] of byServer) {
+        errors.push(...(await checkServerGroup(server, group, servers[server], timeoutMs)));
+    }
+    return errors;
+}
+/** Human-readable message for a contract-tool error (with "did you mean"). */
+function mcpContractToolMessage(e) {
+    switch (e.reason) {
+        case "server-unreachable":
+            return `MCP tool "${e.tool}" — server "${e.server}" failed to start`;
+        case "tool-missing":
+            return `MCP tool "${e.tool}" not found on server "${e.server}"${e.suggestions.length > 0
+                ? ` — did you mean ${e.suggestions.map((s) => `"${s}"`).join(", ")}?`
+                : ""}`;
+        default:
+            return (0, hash_js_1.assertNever)(e.reason);
+    }
+}
 /** Human-readable message for an MCP reference error (with "did you mean"). */
 function mcpRefMessage(e) {
     switch (e.reason) {