vigiles 26.2.0 → 27.0.0

package/dist/cli.d.ts

@@ -1,136 +1,52 @@
 #!/usr/bin/env node
 /**
- * vigiles CLI — verify your agent harness is real, and prove it works.
+ * The `vigiles` bin — a DISPATCHER SHIM, and deliberately almost empty.
  *
- * The verbs and their one-liners live in ONE place, `COMMAND_HELP` + `HELP_GROUPS`
- * near the bottom of this file, and `--help` prints from that table. A second list
- * here would be a copy that rots — this docblock WAS that copy: it named four
- * commands and omitted `audit`, `test`, `eval` and `eject`, four of the eight, and
- * `self-command-refs.test.ts` did not catch it because it guards against refs to
- * REMOVED commands, not against a list that merely stops growing.
- */
-import { type ExcludeSet } from "./exclude.js";
-import type { RuleSeverity } from "./core/types.js";
-/** Reason the most recent `loadSpec()` returned null, or null if it succeeded. */
-export declare function specLoadFailureReason(): string | null;
-/**
- * Structured lint report used by --json, --summary, and exit-code logic.
- */
-interface LintReport {
-    hashErrors: number;
-    validationErrors: number;
-    inlineErrors: number;
-    inlineRules: number;
-    frontmatterErrors: number;
-    frontmatterRules: number;
-    specRefIssues: number;
-    specRefErrors: number;
-    duplicatePairs: number;
-    /** Severity of `duplicate-instructions` — carried so the exit code can tier it. */
-    duplicateSeverity: RuleSeverity;
-    coverageEnabled: number;
-    coverageDocumented: number;
-    strengthenSuggestions: number;
-    integrityErrors: number;
-    coverageErrors: number;
-    orphanCount: number;
-    /** Severity of `orphan-docs` — carried so the exit code can tier it (#181). */
-    orphanSeverity: RuleSeverity;
-    untestedSurfaces: number;
-    untestedErrors: number;
-    toolContractIssues: number;
-    toolContractErrors: number;
-    hookEventIssues: number;
-    hookEventErrors: number;
-    frontmatterSchemaIssues: number;
-    frontmatterSchemaErrors: number;
-    mcpConfigIssues: number;
-    mcpConfigErrors: number;
-    skillFrontmatterIssues: number;
-    skillFrontmatterErrors: number;
-    mcpToolIssues: number;
-    mcpToolErrors: number;
-    hookScriptIssues: number;
-    hookScriptErrors: number;
-    disallowedToolIssues: number;
-    disallowedToolErrors: number;
-    descriptionOverlapIssues: number;
-    descriptionOverlapErrors: number;
-    descriptionBudgetIssues: number;
-    descriptionBudgetErrors: number;
-    frontmatterValidIssues: number;
-    frontmatterValidErrors: number;
-    mcpHookIssues: number;
-    mcpHookErrors: number;
-    preferCompiledHookIssues: number;
-    preferCompiledHookErrors: number;
-    lethalTrifectaIssues: number;
-    lethalTrifectaErrors: number;
-    skillResourceIssues: number;
-    skillResourceErrors: number;
-    skillFenceIssues: number;
-    skillFenceErrors: number;
-    pluginLayoutIssues: number;
-    pluginLayoutErrors: number;
-    delegationTrifectaIssues: number;
-    delegationTrifectaErrors: number;
-    hookBlockIssues: number;
-    hookBlockErrors: number;
-    hookMatcherIssues: number;
-    hookMatcherErrors: number;
-    docRefErrors: number;
-    symbolRefErrors: number;
-    mcpRefErrors: number;
-    files: string[];
-    /**
-     * Findings / errors / warnings for the whole run — the same numbers the
-     * human-readable summary line prints, so a consumer never has to reconstruct
-     * them by counting output lines (#183, and the generic-consumer half of #181).
-     */
-    totals?: {
-        findings: number;
-        errors: number;
-        warnings: number;
-    };
-}
-/** Exit codes: 0 clean, 1 warnings only, 2 hard errors. */
-/**
- * The run's totals, derived from the report itself.
+ * ## Why this file has no imports
  *
- * 🔴 ONE SOURCE, because the two numbers disagreeing IS the bug (#183). The
- * human-readable log had no total, and counting its `⚠` lines gave a different
- * number from the JSON — 21 against 88 on a real repo — because some checks print
- * one line per finding and others one line carrying a count. Both numbers were
- * right and nothing said why they differed, so "vigiles reports 21 warnings" and
- * "88 warnings" were equally defensible readings of one run.
+ * `dist/cli.js` is the `bin`, so it is also what the harness spawns for
+ * `vigiles hook-runtime run-program <file>` — a compiled hook's decision, which
+ * runs on EVERY matching tool call. The output is CommonJS, where a top-level
+ * `import` becomes a top-level `require` that resolves BEFORE argv is read. The
+ * verb barrel (`./cli-main.js`) has ~85 of them: the report template loader, the
+ * linter catalogs, the adapter registry, `audit`, `eval`, `init`. A hook calls
+ * none of it.
  *
- * Counted GENERICALLY off the `*Issues` / `*Errors` / count keys rather than a
- * hand-maintained list, so a rule added later is included by existing, not by
- * somebody remembering. `orphanCount` and `duplicatePairs` are named explicitly
- * only because they predate the `*Issues` convention (#181).
- */
-export declare function lintTotals(report: LintReport): {
-    findings: number;
-    errors: number;
-    warnings: number;
-};
-/**
- * Nested plugin bundles under a lint root — a directory that is itself a harness
- * (its own `.claude-plugin/plugin.json`, or its own skills dir) and is NOT the
- * root being linted.
+ * MEASURED 2026-09-08, Node 22.22.2, median of 20 spawns
+ * (`node tools/measure-hook-startup.mjs` — run it, do not trust these):
+ *
+ * ```
+ *   bare `node -e ''`                                42 ms
+ *   require dist/core/hook-program.js               170 ms
+ *   require dist/cli.js  ← what a hook used to load 623 ms
+ *   a real run-program spawn                    610-661 ms
+ * ```
+ *
+ * A shell hook doing the same job costs ~12 ms and a python one ~35 ms, so the
+ * gap was the reason to keep the shell hook. Issue #216.
+ *
+ * ## The rule this file exists to hold
+ *
+ * 🔴 NO TOP-LEVEL IMPORT MAY BE ADDED HERE. Every `require` in this file is paid
+ * by every gated tool call before anything decides anything. Both branches below
+ * load their module lazily, inside the branch. `src/hook-runtime-graph.test.ts`
+ * fails the day a top-level import puts the CLI barrel back into a hook
+ * decision's module graph — it asserts the GRAPH, not a duration, because a
+ * timing threshold on a shared CI runner is flaky and would be quarantined first.
+ *
+ * ## What must not change
  *
- * 🔴 WHY THIS EXISTS. Every per-surface check reads ONE root, so in a monorepo
- * holding `skills/` plus `plugins/  * /skills/` the nested skills were never scored
- * and nothing said so. Measured on a fixture: 4 skills over the description
- * budget, `lint .` reported 2, exit 0 — a repo reads that as green-with-2 while
- * the other 2 carry the same defect (#185). The failure is silent, which is the
- * shape this repo treats as worse than a loud one.
+ * The emitted command `npx vigiles hook-runtime run-program <file>` is byte-for-byte
+ * what `vigiles compile` has already written into users' `.claude/settings.json`
+ * and `.codex/config.toml`, and it is covered by the SHA stamp beside each hook.
+ * Renaming it — or moving the bin off `dist/cli.js` — breaks a contract that
+ * lives in other people's repositories. It is a fast path THROUGH the same
+ * command, never a new one.
  *
- * Deliberately shallow (one level under a container dir): deep recursion would
- * sweep vendored corpora — this repo's own `test/dogfood/` holds real pinned
- * third-party plugins — and scoring someone else's vendored plugin as if it were
- * yours is the false-positive that gets a gate switched off.
+ * Harness-neutral: `run-program` dispatches on the hook's own role, and the gate
+ * protocol (deny → exit 2) is identical on Claude Code and Codex, so one path
+ * serves both. The single harness-specific fact (which events accept injected
+ * context) is read from the resolved adapter inside the runtime.
  */
-export declare function discoverNestedBundles(root: string, excludes: ExcludeSet): string[];
 export {};
 //# sourceMappingURL=cli.d.ts.map