vigiles 5.1.0 → 6.0.0

package/dist/core/effects.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyToolEffect = classifyToolEffect;
+exports.effectSurface = effectSurface;
+exports.purityViolations = purityViolations;
+exports.pureContractViolations = pureContractViolations;
+exports.decidePurityGate = decidePurityGate;
+const hash_js_1 = require("./hash.js");
+const bash_effects_js_1 = require("./bash-effects.js");
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Strips a `Tool(restriction)` suffix and returns the base tool name. */
+function baseTool(raw) {
+    return raw.split("(")[0].trim();
+}
+/** Returns true for the wildcard sentinels that mean "inherits-all". */
+function isWildcard(tool) {
+    return tool === "" || tool === "*";
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Classify the effect of ONE tool name against a dialect's known catalogs.
+ *
+ * A `Tool(restriction)` suffix (e.g. `Bash(git:*)`) is stripped first — the
+ * restriction narrows what the tool can DO but doesn't change its effect class
+ * (Bash with any restriction is still conservatively side-effecting).
+ *
+ * Classification rules (in priority order):
+ *  1. In `dialect.sideEffectingTools`  → `"side-effecting"`
+ *  2. In `dialect.builtinAgentTools` (and NOT side-effecting) → `"read-only"`
+ *  3. Matches `dialect.mcpToolPattern` → `"unknown"` (MCP tools are not
+ *     classifiable from the name alone — treated as unknown-effect)
+ *  4. Otherwise → `"unknown"` (unrecognized tool; may be a plugin tool or a typo)
+ */
+function classifyToolEffect(tool, dialect) {
+    const base = baseTool(tool);
+    const sideEffecting = dialect.sideEffectingTools ?? [];
+    if (sideEffecting.includes(base))
+        return "side-effecting";
+    if (dialect.builtinAgentTools.includes(base))
+        return "read-only";
+    if (dialect.mcpToolPattern.test(base))
+        return "unknown";
+    return "unknown";
+}
+/**
+ * Compute the static effect surface of a declared `tools:` contract.
+ *
+ * `"*"` / `""` (inherits-all) entries make purity `"unrestricted"` because the
+ * contract grants access to all tools including every side-effecting one — the
+ * full surface is unknowable statically. They are NOT listed in any bucket
+ * (they represent a wildcard, not a named tool).
+ *
+ * De-duplication: a tool name that appears more than once in `tools` is counted
+ * once in its bucket (base tool after restriction stripping).
+ */
+function effectSurface(tools, dialect) {
+    const readOnly = new Set();
+    const sideEffecting = new Set();
+    const unknown = new Set();
+    let hasWildcard = false;
+    let hasBash = false;
+    for (const raw of tools) {
+        const base = baseTool(raw);
+        if (isWildcard(base)) {
+            hasWildcard = true;
+            continue; // wildcards don't go into any named bucket
+        }
+        const effect = classifyToolEffect(raw, dialect);
+        switch (effect) {
+            case "read-only":
+                readOnly.add(base);
+                break;
+            case "side-effecting":
+                sideEffecting.add(base);
+                if (base === "Bash")
+                    hasBash = true;
+                break;
+            case "unknown":
+                unknown.add(base);
+                break;
+            default:
+                (0, hash_js_1.assertNever)(effect);
+        }
+    }
+    const purity = hasWildcard || hasBash || unknown.size > 0
+        ? "unrestricted"
+        : sideEffecting.size > 0
+            ? "bounded"
+            : "pure";
+    return {
+        readOnly: [...readOnly],
+        sideEffecting: [...sideEffecting],
+        unknown: [...unknown],
+        purity,
+    };
+}
+/**
+ * Returns the violations of a DECLARED purity floor — the tools that make the
+ * actual effect surface LOOSER than the declared level. Empty ⇒ the contract
+ * honours the declared level. The `message` on each is actionable (names the
+ * tool, the effect class, and what to do).
+ *
+ * What counts as a violation depends on `declared`:
+ * - `"pure"`:         every side-effecting tool (incl. `Bash`), every
+ *                     unknown-effect tool, and any wildcard (a pure unit may
+ *                     only observe — no `Bash`, no effects, fully static).
+ * - `"bounded"`:      only the truly UNBOUNDED tools — unknown-effect (MCP /
+ *                     unrecognized) and wildcards. Every decidable side-effecting
+ *                     tool is ALLOWED: Write/Edit confine to the boundary, and
+ *                     `Bash` is admitted because the RUNTIME gate
+ *                     (`decidePurityGate`) refines it by command (read-only Bash
+ *                     is an observation; a mutating command is denied).
+ * - `"unrestricted"`: never a violation (the rung carries no constraint).
+ *
+ * A wildcard (`"*"` / `""`) contract is a violation at every constrained level:
+ * "inherits-all" grants every tool, so neither `pure` nor `bounded` can hold.
+ */
+function purityViolations(tools, dialect, declared) {
+    if (declared === "unrestricted")
+        return []; // no constraint to violate
+    const violations = [];
+    const seen = new Set();
+    for (const raw of tools) {
+        const base = baseTool(raw);
+        if (isWildcard(base)) {
+            const key = base === "" ? '""' : '"*"';
+            if (!seen.has(key)) {
+                seen.add(key);
+                violations.push({
+                    tool: base,
+                    effect: "side-effecting",
+                    message: `${key} (inherits-all) is not allowed in a ${declared} contract — it grants access to every tool, including side-effecting ones. Declare explicit tools instead.`,
+                });
+            }
+            continue;
+        }
+        if (seen.has(base))
+            continue;
+        const effect = classifyToolEffect(raw, dialect);
+        switch (effect) {
+            case "read-only":
+                break; // allowed at every level
+            case "unknown":
+                seen.add(base);
+                violations.push({
+                    tool: base,
+                    effect,
+                    message: `"${base}" has unknown effect class (MCP or unrecognized tool); a ${declared} contract cannot declare it — its effects are unbounded from static analysis. Remove it or declare the unit dangerously-unrestricted.`,
+                });
+                break;
+            case "side-effecting":
+                // In a BOUNDED unit every decidable side-effecting tool is allowed:
+                // Write/Edit confine to the boundary, and `Bash` is admitted because the
+                // RUNTIME gate (`decidePurityGate`) refines it by command — a read-only
+                // Bash is an observation, a mutating command is denied. Only `pure` bars
+                // them (a pure unit may only observe; no `Bash`, no effects).
+                if (declared === "bounded")
+                    break;
+                seen.add(base);
+                violations.push({
+                    tool: base,
+                    effect,
+                    message: base === "Bash"
+                        ? `"Bash" is undecidable at the tool-name level; a pure unit cannot declare it. A read-only Bash belongs in a bounded unit (the runtime gate confines it by command) — declare the unit bounded or dangerously-unrestricted.`
+                        : `"${base}" is side-effecting; a pure unit cannot declare it. Remove it or declare the unit bounded.`,
+                });
+                break;
+            default:
+                (0, hash_js_1.assertNever)(effect);
+        }
+    }
+    return violations;
+}
+/**
+ * The violations of a `purity: "pure"` contract — every side-effecting,
+ * unknown-effect, or wildcard tool. A thin alias for `purityViolations(…,
+ * "pure")` kept for the common pure case.
+ */
+function pureContractViolations(tools, dialect) {
+    return purityViolations(tools, dialect, "pure");
+}
+/**
+ * The RUNTIME half of the purity contract: decide whether a single LIVE tool
+ * call is allowed under the active unit's declared purity floor.
+ *
+ * Unlike `purityViolations` (which checks the DECLARED tools contract
+ * statically), this sees the ACTUAL call — including the `Bash` command string —
+ * so it refines `Bash` by effect via `isReadOnlyBash`. That command is the whole
+ * reason the gate's home is the runtime hook: only here is the concrete command
+ * visible (the static surface sees a tool name + a `Bash(git:*)` pattern, never
+ * the command).
+ *
+ * Rules (the ladder, command-refined):
+ * - `unrestricted` → always allow (no constraint).
+ * - read-only tool → allow at every level.
+ * - `Bash` → allow iff the command is provably read-only (an observation);
+ *   otherwise deny — a mutating/undecidable command's effect must move to a
+ *   marked boundary. Same at `pure` and `bounded`.
+ * - other side-effecting tool (Write, Edit, …) → allow under `bounded`
+ *   (a decidable, boundary-confined effect), deny under `pure` (observe-only).
+ * - unknown-effect (MCP / unrecognized) → deny under `pure`/`bounded`
+ *   (unbounded from static analysis).
+ *
+ * Dialect injected (core ⊄ adapter). Reuses `classifyToolEffect` +
+ * `isReadOnlyBash` — one-detector-no-drift with compile + scan.
+ */
+function decidePurityGate(declared, tool, command, dialect) {
+    if (declared === "unrestricted")
+        return { allow: true, message: "" };
+    const base = baseTool(tool);
+    const effect = classifyToolEffect(tool, dialect);
+    if (effect === "read-only")
+        return { allow: true, message: "" };
+    if (base === "Bash") {
+        if (command !== undefined && (0, bash_effects_js_1.isReadOnlyBash)(command)) {
+            return { allow: true, message: "" };
+        }
+        const shown = command ? `"${command}" ` : "";
+        return {
+            allow: false,
+            message: `Bash command ${shown}is not provably read-only; a ${declared} unit may run only read-only Bash ` +
+                `(observation). Move the side effect into a marked boundary, or declare the unit dangerously-unrestricted.`,
+        };
+    }
+    if (effect === "side-effecting") {
+        if (declared === "bounded")
+            return { allow: true, message: "" };
+        return {
+            allow: false,
+            message: `"${base}" is side-effecting; a pure unit may only observe. ` +
+                `Declare the unit bounded (or dangerously-unrestricted) to use it.`,
+        };
+    }
+    // unknown — MCP / unrecognized tool
+    return {
+        allow: false,
+        message: `"${base}" has unknown effect class; a ${declared} unit cannot use it — its effects are unbounded. ` +
+            `Declare the unit dangerously-unrestricted to allow it.`,
+    };
+}
+//# sourceMappingURL=effects.js.map

package/dist/core/generate-harness.d.ts

@@ -0,0 +1,187 @@
+/**
+ * vigiles generate-harness — emit ONE typed registry over the whole harness.
+ *
+ * The third generated artifact beside `generate-types` (`.d.ts`) and
+ * `generate-schema` (JSON Schema): a `harness.gen.ts` that imports every
+ * `*.spec.ts` in a directory, folds the agents into a `registry`, and asserts
+ * the cross-spec invariants at the TYPE level — so a single `tsc --noEmit`
+ * checks the WHOLE harness as one program (think TanStack's `routeTree.gen.ts`).
+ * See research/whole-harness-codegen.md for the design + the measured perf.
+ *
+ * The shipped scope (the first increment):
+ *  1. DANGLING `delegate` → a `tsc` error. Each `railway()` delegate target is a
+ *     name the generator reads at codegen time; the gen file emits one shallow
+ *     per-edge assertion (`KnownAgentName<"target", AgentName>` — O(N), no
+ *     recursion) that the target resolves to a real agent, else a `tsc` error
+ *     naming the dangling target + its railway.
+ *  2. DUPLICATE agent/skill NAMES → a generator error (this module returns a
+ *     `duplicate` diagnostic; the CLI exits non-zero). This is the O(N) JS check
+ *     the encoding rule mandates — a set-uniqueness MAPPED TYPE is the TS2589
+ *     wall (measured ≈ N=1000), so duplicates are NEVER a type.
+ *  3. The whole-harness CAPABILITY LATTICE: the UNION of every agent's
+ *     `effectSurface(tools, dialect)` — a generator-computed value + type, the
+ *     substrate the future repo-scale capability-diff reads.
+ *  4. CROSS-FILE TYPED COMPOSITION: when a `railway()` success-track step declares
+ *     what it `needs()`, the gen file emits one shallow per-pair assertion
+ *     (`Handoff<OkOf<typeof registry[producer]>, needs>` — O(N), no recursion)
+ *     that the PRIOR step's `result().ok` SUPPLIES it, so a cross-file handoff
+ *     mismatch (a missing field / wrong type) is a `tsc` error naming the field.
+ *     The repo-scale generalization of the per-file `pipe`/`Supplies` composition.
+ *     Scoped to the linear success track; recover/onError (which consume an `err`,
+ *     not the prior `ok`) are a noted follow-up.
+ *
+ * Harness-agnostic: the `dialect` (for the capability lattice) is INJECTED by
+ * the composition root (the CLI), never hard-coded — mirroring `compileAgent` /
+ * `scanPlugin`. The core stays free of any Claude-Code literal.
+ */
+import type { HarnessDialect } from "./dialect.js";
+import { type PurityLevel } from "./effects.js";
+/** One agent the harness defines (its registry-relevant facts). */
+export interface HarnessAgentEntry {
+    /** The agent's dispatch name — also a registry key + the dangling-check union. */
+    readonly name: string;
+    /** The agent's declared tool contract (used to compute its effect surface). */
+    readonly tools?: readonly string[];
+    /** The spec file this agent came from (for import + duplicate diagnostics). */
+    readonly file: string;
+}
+/** One delegate edge: a railway dispatches `target` (resolved against agents). */
+export interface HarnessDelegateEdge {
+    /** The railway / orchestrator the edge originates from (for the diagnostic). */
+    readonly from: string;
+    /** The delegate target name — must resolve to a known agent, else dangling. */
+    readonly target: string;
+}
+/**
+ * One CROSS-FILE handoff edge: a consecutive success-track pair where the
+ * CONSUMER (`to`) declares the input it `needs`, asserted against the PRODUCER
+ * (`from`, the prior step's agent) `result().ok` at the type level. The
+ * registry already imports each agent's `TypedAgentSpec`, so the generator reads
+ * the producer's `ok` shape off the registry (`OkOf<typeof registry[from]>`) and
+ * emits one shallow `Handoff<>` assertion per such pair (O(N), no recursion).
+ */
+export interface HarnessHandoffEdge {
+    /** The railway the edge originates from (for the diagnostic). */
+    readonly railway: string;
+    /** The PRODUCER agent name (the prior success-track step) — registry key. */
+    readonly from: string;
+    /** The CONSUMER agent name (this step) — names the failing edge. */
+    readonly to: string;
+    /** The consumer's declared input shape (`needs(...)`) — the literal emitted. */
+    readonly needs: Readonly<Record<string, string>>;
+}
+/** Everything the generator needs, already loaded (the pure-core input). */
+export interface HarnessModel {
+    readonly agents: readonly HarnessAgentEntry[];
+    readonly edges: readonly HarnessDelegateEdge[];
+    /**
+     * Cross-file handoff edges (consecutive success-track step pairs whose
+     * consumer declares `needs`). Optional + defaults to none, so an existing
+     * model with no handoffs generates exactly as before — backwards-compatible.
+     */
+    readonly handoffs?: readonly HarnessHandoffEdge[];
+}
+export interface GenerateHarnessOptions {
+    /** The dialect the capability lattice is computed against (injected). */
+    readonly dialect: HarnessDialect;
+    /**
+     * The module specifier the generated file imports `KnownAgentName` from.
+     * Defaults to the public package (`"vigiles/spec"`); the in-repo dogfood
+     * passes a relative path so the generated file resolves without the package.
+     */
+    readonly specImport?: string;
+    /** The directory the gen file will be written to (to relativize spec imports). */
+    readonly outDir: string;
+}
+/** A duplicate-name collision found at codegen time (the O(N) JS check). */
+export interface DuplicateNameDiagnostic {
+    readonly name: string;
+    readonly first: string;
+    readonly second: string;
+    /** A ready-to-print message. */
+    readonly message: string;
+}
+/** The whole-harness capability lattice — the union of every agent's surface. */
+export interface HarnessCapabilities {
+    /** Every read-only tool reachable anywhere in the harness (de-duped, sorted). */
+    readonly readOnly: readonly string[];
+    /** Every side-effecting tool reachable anywhere (de-duped, sorted). */
+    readonly sideEffecting: readonly string[];
+    /** Every unknown-effect tool (MCP / unrecognized) reachable anywhere. */
+    readonly unknown: readonly string[];
+    /** The harness-wide purity: the LOOSEST purity of any single agent. */
+    readonly purity: PurityLevel;
+}
+export interface GenerateHarnessResult {
+    /** The generated `harness.gen.ts` source (always produced — even on a dup, so
+     *  the caller can decide; the CLI gates the WRITE on `duplicate` being absent). */
+    readonly gen: string;
+    /** The computed capability lattice (also embedded in `gen`). */
+    readonly capabilities: HarnessCapabilities;
+    /** Set iff two agents declare the same name — the caller exits non-zero. */
+    readonly duplicate?: DuplicateNameDiagnostic;
+    /** The number of agents + edges folded in (for the CLI summary). */
+    readonly agentCount: number;
+    readonly edgeCount: number;
+    /** The number of cross-file handoff assertions emitted (for the CLI summary). */
+    readonly handoffCount: number;
+}
+/**
+ * Fold every agent's `effectSurface` into one harness-wide lattice: the union of
+ * each bucket and the loosest purity. An agent with no `tools` inherits all (a
+ * wildcard), so its surface is `unrestricted` — handled by `effectSurface` when
+ * we pass `["*"]`. O(N) over the agents; the per-agent legs are fixed-arity.
+ */
+export declare function computeHarnessCapabilities(agents: readonly HarnessAgentEntry[], dialect: HarnessDialect): HarnessCapabilities;
+/**
+ * Find the FIRST pair of agents that declare the same `name`. O(N) over the
+ * agents — the set-cardinality check the encoding rule says must live in the JS
+ * generator, never as an N×N mapped type (the measured TS2589 wall). Returns
+ * `undefined` when names are unique.
+ */
+export declare function findDuplicateName(agents: readonly HarnessAgentEntry[]): DuplicateNameDiagnostic | undefined;
+/**
+ * Generate the `harness.gen.ts` source over an already-loaded `HarnessModel`.
+ *
+ * Pure: no filesystem read, no spec loading — just string emission + the two
+ * O(N) computations (capability lattice + duplicate check). The fs/scan wrapper
+ * (`loadHarnessModel`) feeds this.
+ */
+export declare function generateHarness(model: HarnessModel, options: GenerateHarnessOptions): GenerateHarnessResult;
+/** A minimal shape of a loaded spec value (the fields the model reads). */
+interface LoadedSpecLike {
+    readonly _specType?: string;
+    readonly name?: string;
+    readonly tools?: readonly string[];
+    readonly steps?: readonly {
+        readonly agent?: string;
+        readonly needs?: Readonly<Record<string, string>>;
+    }[];
+    readonly onError?: {
+        readonly agent?: string;
+    };
+    readonly recover?: {
+        readonly step?: {
+            readonly agent?: string;
+        };
+    };
+}
+/** Discover every `*.spec.ts` directly under `dir` (non-recursive, sorted). */
+export declare function findHarnessSpecFiles(dir: string): string[];
+/**
+ * Build a `HarnessModel` from `dir`'s spec files using a caller-supplied
+ * `load(file) → value` (the CLI injects its `loadSpec`, so this stays
+ * fs/runtime-agnostic and unit-testable with fakes). Agents become registry
+ * entries; railways contribute delegate edges (steps + recover + onError).
+ */
+export declare function loadHarnessModel(dir: string, load: (absFile: string) => Promise<LoadedSpecLike | null>): Promise<HarnessModel>;
+/** Convenience: the gen file's basename, used by the CLI default out path. */
+export declare const HARNESS_GEN_FILENAME = "harness.gen.ts";
+/** Relative label for a path under cwd (CLI-only nicety; pure). */
+export declare function labelFor(cwd: string, abs: string): string;
+/** Read a spec file's raw text (helper exposed for callers that need the source). */
+export declare function readSpecSource(absFile: string): string;
+/** The directory a gen file at `outFile` lives in (helper for the CLI). */
+export declare function genOutDir(outFile: string): string;
+export {};
+//# sourceMappingURL=generate-harness.d.ts.map