vigiles 2.5.0 → 3.0.0

package/dist/leaderboard.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Plugin health leaderboard — rank many plugins by the deterministic structural
+ * signals `scan` already computes (research/divergent-bets.md #9, the engine).
+ *
+ * This is the no-model half: a defensible health score from concrete facts
+ * (missing hook scripts, skills that can't trigger, agents with no tool
+ * contract, untested surfaces). It deliberately does NOT score on the loader's
+ * free-text warnings — those include doc-mention false positives (see
+ * src/scan.ts), and a ranking that penalizes a prose mention would be unfair.
+ * The behavioural columns (real trigger-rate, observed egress, safety) need a
+ * model and stack on top later; this part runs anywhere in CI for free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scoreReport = scoreReport;
+exports.rankPlugins = rankPlugins;
+exports.formatLeaderboard = formatLeaderboard;
+const node_path_1 = require("node:path");
+const scan_js_1 = require("./scan.js");
+// Penalty weights — broken-at-runtime costs most, footguns less, nudges least.
+const W_MISSING_HOOK = 15; // a hook script that doesn't exist → never runs
+const W_NO_DESCRIPTION = 10; // a skill with no usable description → can't trigger
+const W_NO_CONTRACT = 5; // an agent with no `tools:` line → inherits everything
+const W_UNTESTED = 3; // a surface with no test/eval → warning-tier
+function gradeFor(score) {
+    if (score >= 90)
+        return "A";
+    if (score >= 80)
+        return "B";
+    if (score >= 70)
+        return "C";
+    if (score >= 60)
+        return "D";
+    return "F";
+}
+/** Deterministic structural-health score for one scanned plugin. */
+function scoreReport(r) {
+    // An empty/unloadable machine isn't healthy — it's a non-plugin or a broken load.
+    if (r.skills.length + r.agents.length + r.hooks.length === 0) {
+        return { score: 0, issues: ["no loadable plugin surface"] };
+    }
+    const missingHooks = r.hooks.filter((h) => h.status === "missing").length;
+    const noDesc = r.skills.filter((s) => !s.hasDescription).length;
+    const noContract = r.agents.filter((a) => a.tools === null).length;
+    const deductions = [
+        {
+            n: missingHooks,
+            weight: W_MISSING_HOOK,
+            label: "hook script(s) MISSING",
+        },
+        {
+            n: noDesc,
+            weight: W_NO_DESCRIPTION,
+            label: "skill(s) with no usable description",
+        },
+        {
+            n: noContract,
+            weight: W_NO_CONTRACT,
+            label: "agent(s) inherit all tools (no contract)",
+        },
+        { n: r.untested, weight: W_UNTESTED, label: "untested surface(s)" },
+    ];
+    let penalty = 0;
+    const issues = [];
+    for (const d of deductions) {
+        if (d.n === 0)
+            continue;
+        penalty += d.n * d.weight;
+        issues.push(`${String(d.n)} ${d.label}`);
+    }
+    // Sort issues by cost (worst first) so the report leads with what matters.
+    issues.sort((a, b) => Number(b.split(" ")[0]) - Number(a.split(" ")[0]));
+    return { score: Math.max(0, 100 - penalty), issues };
+}
+/** Scan + score each directory, ranked best-first (ties broken by name). */
+function rankPlugins(dirs) {
+    const scored = dirs.map((dir) => {
+        const report = (0, scan_js_1.scanPlugin)(dir);
+        const { score, issues } = scoreReport(report);
+        return {
+            dir,
+            name: (0, node_path_1.basename)(dir) || dir,
+            score,
+            grade: gradeFor(score),
+            issues,
+            report,
+        };
+    });
+    return scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+}
+/** Format a ranked leaderboard as human-readable text. */
+function formatLeaderboard(scores) {
+    const out = [
+        `Plugin health leaderboard (${String(scores.length)} scanned)`,
+        "",
+        "  #   score  grade  plugin",
+    ];
+    scores.forEach((s, i) => {
+        const rank = String(i + 1).padStart(2);
+        const score = String(s.score).padStart(3);
+        const issue = s.issues.length > 0 ? ` — ${s.issues.join("; ")}` : "";
+        out.push(`  ${rank}  ${score}    ${s.grade}      ${s.name}${issue}`);
+    });
+    out.push("", "Structural health only (no model). Weights: missing hook -15, no-description", "skill -10, agent-without-tool-contract -5, untested surface -3.");
+    return out.join("\n");
+}
+//# sourceMappingURL=leaderboard.js.map

package/dist/linting.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
+ * files. Re-exports the spec builders/types and the compiler under one
+ * concern-named import. The granular paths (`vigiles/spec`, `vigiles/compile`)
+ * keep working; this just groups them so the import name matches the pillar.
+ */
+export * from "./core/spec.js";
+export * from "./core/compile.js";
+//# sourceMappingURL=linting.d.ts.map

package/dist/linting.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
+ * files. Re-exports the spec builders/types and the compiler under one
+ * concern-named import. The granular paths (`vigiles/spec`, `vigiles/compile`)
+ * keep working; this just groups them so the import name matches the pillar.
+ */
+__exportStar(require("./core/spec.js"), exports);
+__exportStar(require("./core/compile.js"), exports);
+//# sourceMappingURL=linting.js.map

package/dist/plugin-loader.d.ts

@@ -1,3 +1,4 @@
+import type { PluginLayout } from "./core/layout.js";
 export interface LoadedPlugin {
     /** A `.claude/settings.json`-shaped object with hooks resolved. */
     readonly settings: {
@@ -20,17 +21,19 @@ export interface LoadedPlugin {
  * sandbox, and `warnings` for surfaces the deterministic tier can't drive. Merge
  * `settings` with any inline settings and spread `files` into the fixture.
  */
-export declare function loadPlugin(pluginPath: string): LoadedPlugin;
+export declare function loadPlugin(pluginPath: string, layout: PluginLayout): LoadedPlugin;
 /**
  * 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.
+ * `runEval` so both test the assembled machine the same way. `layout` is
+ * REQUIRED (no harness default at the composition root) — the Claude Code
+ * wrapper supplies `claudeCodeLayout` to preserve `resolveHarness(opts)`.
  */
 export declare function resolveHarness(opts: {
     plugin?: string;
     settings?: unknown;
     files?: Record<string, string>;
-}): {
+}, layout: PluginLayout): {
     settings: unknown;
     files: Record<string, string>;
 };

package/dist/plugin-loader.js

@@ -3,28 +3,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadPlugin = loadPlugin;
 exports.resolveHarness = resolveHarness;
 /**
- * vigiles — load a real plugin/repo harness for testing.
+ * vigiles — harness-agnostic plugin/repo harness loader (composition root).
  *
- * 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).
+ * Lives at the app/composition root, NOT in any harness adapter, so every
+ * adapter (Claude Code, Codex, OpenCode, …) loads its plugin through the SAME
+ * loader by injecting its own `PluginLayout` — no adapter imports a sibling
+ * adapter. The unit that matters is not a single hook but the *assembled
+ * machine*: the hooks, settings, instruction file, 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, instruction file 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.
+ * Resolution order for hooks: inline `hooks` in the layout's manifest, a `hooks`
+ * string path in the manifest, the layout's `hooks` convention path (e.g.
+ * obra/superpowers' `hooks/hooks.json`), then a plain repo's settings file.
+ * The layout's plugin-root token 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 instruction file and skills/ are materialized into the
+ * sandbox so the assembled context is present too.
+ *
+ * `layout` is REQUIRED here — there is no harness default at the composition
+ * root. Each adapter supplies its own (the Claude Code wrapper at
+ * `src/adapters/claude-code/plugin-loader.ts` defaults it to `claudeCodeLayout`
+ * to preserve `loadPlugin(dir)` ergonomics and the public `vigiles/*` exports).
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const toml_1 = require("@iarna/toml");
 const MAX_SKILL_FILE_BYTES = 256 * 1024;
 /** Parse a JSON file, or null on any error (missing / malformed). */
 function safeReadJson(path) {
@@ -39,6 +49,40 @@ function safeReadJson(path) {
 function readHooksFile(path) {
     return safeReadJson(path)?.hooks;
 }
+/**
+ * Parse the layout's manifest in its declared `settingsFormat` — JSON (Claude
+ * Code's plugin.json) or TOML (Codex's `config.toml`). A TOML harness's manifest
+ * (hooks, `[mcp_servers]`) would otherwise read as empty through the JSON path.
+ * Behaviour-identical to `safeReadJson` when the format is JSON.
+ */
+function safeReadManifest(root, layout) {
+    const path = (0, node_path_1.join)(root, layout.manifestPath);
+    if (layout.settingsFormat === "toml") {
+        try {
+            return (0, toml_1.parse)((0, node_fs_1.readFileSync)(path, "utf-8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    return safeReadJson(path);
+}
+/**
+ * Read the `.hooks` field of a settings file in the layout's format — JSON
+ * (Claude Code's settings.json) or TOML (Codex's `config.toml` `[hooks]`). A
+ * TOML harness's hooks would otherwise be read as zero by the JSON path.
+ */
+function readSettingsHooks(path, format) {
+    if (format === "json")
+        return readHooksFile(path);
+    try {
+        return (0, toml_1.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,
@@ -46,22 +90,23 @@ function readHooksFile(path) {
  *   3. the `hooks/hooks.json` convention (e.g. obra/superpowers) — auto-discovered,
  *   4. a plain repo's `.claude/settings.json`.
  */
-function readHooks(root) {
-    // A malformed plugin.json must not crash the loader — fall through to the
-    // other layouts (safeReadJson returns null on a parse error).
-    const m = safeReadJson((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"));
+function readHooks(root, layout) {
+    // A malformed manifest must not crash the loader — fall through to the
+    // other layouts (safeReadManifest returns null on a parse error). Format-aware
+    // so a Codex `config.toml` manifest's `[hooks]` is read, not skipped.
+    const m = safeReadManifest(root, layout);
     if (m) {
         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");
+    const conventionPath = (0, node_path_1.join)(root, layout.hooksConventionPath);
     if ((0, node_fs_1.existsSync)(conventionPath))
         return readHooksFile(conventionPath);
-    const settingsPath = (0, node_path_1.join)(root, ".claude", "settings.json");
+    const settingsPath = (0, node_path_1.join)(root, layout.settingsPath);
     if ((0, node_fs_1.existsSync)(settingsPath))
-        return readHooksFile(settingsPath);
+        return readSettingsHooks(settingsPath, layout.settingsFormat);
     return undefined;
 }
 /** Recursively collect text files under `dir` as `relativePath → contents`. */
@@ -85,39 +130,39 @@ function readTree(dir, base) {
  * 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) {
+function loadPlugin(pluginPath, layout) {
     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
+    const hooks = readHooks(root, layout);
+    // Expand the plugin-root token 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))
+        ? JSON.parse(JSON.stringify(hooks).replaceAll(layout.pluginRootToken, 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");
+    const instructions = (0, node_path_1.join)(root, layout.instructionFile);
+    if ((0, node_fs_1.existsSync)(instructions)) {
+        files[layout.instructionFile] = (0, node_fs_1.readFileSync)(instructions, "utf-8");
     }
-    // Materialize each project-level surface under .claude/<surface>/ so the
+    // Materialize each project-level surface under the materialize root 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"]) {
+    for (const surface of layout.surfaceDirs) {
         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;
+            files[(0, node_path_1.join)(layout.materializeRoot, rel)] = content;
         }
         counts[surface] = Object.keys(tree).length;
     }
     return {
         settings: resolvedHooks ? { hooks: resolvedHooks } : {},
         files,
-        warnings: pluginWarnings(root, counts, resolvedHooks, files),
+        warnings: pluginWarnings(root, counts, resolvedHooks, files, layout),
     };
 }
 /**
@@ -127,7 +172,7 @@ function loadPlugin(pluginPath) {
  * 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) {
+function pluginWarnings(root, counts, hooks, files, layout) {
     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.`);
@@ -135,10 +180,10 @@ function pluginWarnings(root, counts, hooks, files) {
     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 (hasMcp(root, layout)) {
+        warnings.push(`plugin declares MCP server(s) (${layout.mcpManifestKey} / ${layout.mcpConfigFile}) — the loader does not wire MCP; bring the server up yourself if your test needs it.`);
     }
-    const dangling = danglingRefs(root);
+    const dangling = danglingRefs(root, layout);
     if (dangling.length) {
         const shown = dangling.slice(0, 5).join(", ");
         const more = dangling.length > 5 ? `, … (+${String(dangling.length - 5)})` : "";
@@ -149,16 +194,20 @@ function pluginWarnings(root, counts, hooks, files) {
     }
     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")))
+/** Whether the plugin declares any MCP servers (manifest key or standalone file).
+ *  Format-aware: reads the layout's `mcpManifestKey` from a JSON OR TOML manifest,
+ *  so Codex's `[mcp_servers]` TOML table is detected, not silently missed. */
+function hasMcp(root, layout) {
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.mcpConfigFile)))
         return true;
-    return (safeReadJson((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"))?.mcpServers !==
-        undefined);
+    return safeReadManifest(root, layout)?.[layout.mcpManifestKey] !== undefined;
 }
 // A plugin-relative path reference to a file under a standard surface dir, with a
 // known extension — e.g. a hook script that `cat`s `skills/using-superpowers/SKILL.md`.
-const INTRA_REF_RE = /(?:skills|hooks|commands|agents)\/[A-Za-z0-9._/-]+\.(?:md|sh|cmd|mjs|cjs|js|ts|py|rb|txt|json)/g;
+const INTRA_REF_EXTS = "md|sh|cmd|mjs|cjs|js|ts|py|rb|txt|json";
+function intraRefRe(layout) {
+    return new RegExp(`(?:${layout.intraRefDirs.join("|")})/[A-Za-z0-9._/-]+\\.(?:${INTRA_REF_EXTS})`, "g");
+}
 /**
  * Intra-plugin file references that don't resolve — the partial-vendor / broken-
  * path class (e.g. obra/superpowers' `SessionStart` reads
@@ -168,15 +217,16 @@ const INTRA_REF_RE = /(?:skills|hooks|commands|agents)\/[A-Za-z0-9._/-]+\.(?:md|
  * and report the ones missing on disk. A static check that would have caught a
  * bug the dogfood hit twice. Best-effort: a warning, not an error.
  */
-function danglingRefs(root) {
+function danglingRefs(root, layout) {
     const missing = new Set();
     const seen = new Set();
-    for (const surface of ["hooks", "skills", "agents", "commands"]) {
+    const re = intraRefRe(layout);
+    for (const surface of layout.intraRefDirs) {
         const dir = (0, node_path_1.join)(root, surface);
         if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory())
             continue;
         for (const content of Object.values(readTree(dir, root))) {
-            for (const m of content.matchAll(INTRA_REF_RE)) {
+            for (const m of content.matchAll(re)) {
                 const ref = m[0];
                 if (seen.has(ref))
                     continue;
@@ -215,11 +265,13 @@ function mergeSettings(base, override) {
 /**
  * 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.
+ * `runEval` so both test the assembled machine the same way. `layout` is
+ * REQUIRED (no harness default at the composition root) — the Claude Code
+ * wrapper supplies `claudeCodeLayout` to preserve `resolveHarness(opts)`.
  */
-function resolveHarness(opts) {
+function resolveHarness(opts, layout) {
     const loaded = opts.plugin
-        ? loadPlugin(opts.plugin)
+        ? loadPlugin(opts.plugin, layout)
         : { settings: {}, files: {} };
     return {
         files: { ...loaded.files, ...opts.files },

package/dist/scan.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `vigiles scan <dir>` — point vigiles at any plugin/repo and see what it ships
+ * and what's broken, with **no model and no API key**.
+ *
+ * This is the deterministic substrate under the plugin/skill leaderboard
+ * (research/divergent-bets.md #9) and the harness-aware audit
+ * (research/agent-supply-chain-security.md #1): it re-aims the machinery that
+ * already exists — `loadPlugin` (surfaces + dangling-ref/MCP/empty-machine
+ * warnings), `parseAgentTools` (the declared tool contract), and
+ * `findUntestedSurfaces` — into one read-only report. Behavioral checks that
+ * need to RUN the plugin (observed egress under the sandbox, real trigger-rate)
+ * stack on top later; this core stays pure so it runs anywhere in CI for free.
+ */
+import type { PluginLayout } from "./core/layout.js";
+export interface ScanSkill {
+    readonly name: string;
+    readonly path: string;
+    readonly hasDescription: boolean;
+    readonly userInvoked: boolean;
+}
+export interface ScanAgent {
+    readonly name: string;
+    readonly path: string;
+    /** Declared tool contract, or null when the agent ships no `tools:` (inherits all). */
+    readonly tools: readonly string[] | null;
+}
+/** ok = file present; missing = referenced but absent; unresolved = path still has an unexpanded var, can't check. */
+export type HookStatus = "ok" | "missing" | "unresolved";
+export interface ScanHook {
+    readonly script: string;
+    readonly status: HookStatus;
+}
+export interface ScanReport {
+    readonly dir: string;
+    readonly skills: readonly ScanSkill[];
+    readonly agents: readonly ScanAgent[];
+    readonly hooks: readonly ScanHook[];
+    /** Hook entries with no script file (inline shell one-liners) — can't be path-checked. */
+    readonly inlineHooks: number;
+    readonly commands: number;
+    readonly mcp: boolean;
+    readonly warnings: readonly string[];
+    readonly untested: number;
+}
+/** Scan a plugin/repo directory and report its surfaces + structural issues. */
+export declare function scanPlugin(dir: string, layout?: PluginLayout): ScanReport;
+/** Format a scan report as human-readable text. */
+export declare function formatScanReport(r: ScanReport): string;
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * `vigiles scan <dir>` — point vigiles at any plugin/repo and see what it ships
+ * and what's broken, with **no model and no API key**.
+ *
+ * This is the deterministic substrate under the plugin/skill leaderboard
+ * (research/divergent-bets.md #9) and the harness-aware audit
+ * (research/agent-supply-chain-security.md #1): it re-aims the machinery that
+ * already exists — `loadPlugin` (surfaces + dangling-ref/MCP/empty-machine
+ * warnings), `parseAgentTools` (the declared tool contract), and
+ * `findUntestedSurfaces` — into one read-only report. Behavioral checks that
+ * need to RUN the plugin (observed egress under the sandbox, real trigger-rate)
+ * stack on top later; this core stays pure so it runs anywhere in CI for free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanPlugin = scanPlugin;
+exports.formatScanReport = formatScanReport;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
+const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
+const test_coverage_js_1 = require("./test-coverage.js");
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+const SCRIPT_RE = /\S+\.(?:sh|mjs|cjs|js|ts|py|rb)\b/g;
+function frontmatter(md) {
+    const m = /(?:^|\n)---\r?\n([\s\S]*?)\r?\n---/.exec(md);
+    if (!m)
+        return {};
+    const name = /^name:\s*(.+)$/m.exec(m[1])?.[1]?.trim();
+    const description = /^description:\s*(.+)$/m.exec(m[1])?.[1]?.trim();
+    return { name, description };
+}
+const isSkill = (f) => /skills\/[^/]+\/SKILL\.md$/.test(f);
+const isAgent = (f) => /agents\/[^/]+\.md$/.test(f) && !f.endsWith(".spec.ts");
+const isCommand = (f) => /commands\/.+\.md$/.test(f);
+function skillName(path) {
+    return (path
+        .replace(/\/SKILL\.md$/, "")
+        .split("/")
+        .pop() ?? path);
+}
+function scanSkills(files) {
+    const out = [];
+    for (const [path, md] of Object.entries(files)) {
+        if (!isSkill(path))
+            continue;
+        const fm = frontmatter(md);
+        out.push({
+            name: fm.name ?? skillName(path),
+            path,
+            hasDescription: Boolean(fm.description && fm.description.length >= 20),
+            userInvoked: /^\s*disable-model-invocation:\s*true\s*$/m.test(md),
+        });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+function scanAgents(files) {
+    const out = [];
+    for (const [path, md] of Object.entries(files)) {
+        if (!isAgent(path))
+            continue;
+        out.push({ name: (0, node_path_1.basename)(path, ".md"), path, tools: (0, agent_runtime_js_1.parseAgentTools)(md) });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Resolve a hook script token to a checkable path. `loadPlugin` expands the
+ * braced `${CLAUDE_PLUGIN_ROOT}`; the unbraced shell form `$CLAUDE_PLUGIN_ROOT`
+ * survives, so resolve it against the plugin root here and strip shell quotes.
+ * A token that still carries any `$VAR` after that is genuinely uncheckable.
+ */
+function resolveScript(token, root) {
+    const path = token
+        .replace(/["']/g, "")
+        .replaceAll("${CLAUDE_PLUGIN_ROOT}", root)
+        .replaceAll("$CLAUDE_PLUGIN_ROOT", root);
+    if (path.includes("$"))
+        return { script: token, status: "unresolved" };
+    return { script: path, status: (0, node_fs_1.existsSync)(path) ? "ok" : "missing" };
+}
+/** Pull script-file hook commands out of the resolved settings; count inline ones. */
+function scanHooks(settings, root) {
+    const text = JSON.stringify(settings.hooks ?? {});
+    const commands = [...text.matchAll(/"command":\s*"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1]);
+    const byScript = new Map();
+    let inline = 0;
+    for (const cmd of commands) {
+        const unescaped = cmd.replace(/\\(.)/g, "$1");
+        const found = unescaped.match(SCRIPT_RE);
+        if (!found || found.length === 0) {
+            inline++;
+            continue;
+        }
+        for (const tok of found) {
+            const hook = resolveScript(tok, root);
+            byScript.set(hook.script, hook);
+        }
+    }
+    const hooks = [...byScript.values()].sort((a, b) => a.script.localeCompare(b.script));
+    return { hooks, inline };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Scan a plugin/repo directory and report its surfaces + structural issues. */
+function scanPlugin(dir, layout) {
+    const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, layout);
+    const { hooks, inline } = scanHooks(loaded.settings, (0, node_path_1.resolve)(dir));
+    return {
+        dir,
+        skills: scanSkills(loaded.files),
+        agents: scanAgents(loaded.files),
+        hooks,
+        inlineHooks: inline,
+        commands: Object.keys(loaded.files).filter(isCommand).length,
+        mcp: loaded.warnings.some((w) => w.includes("MCP server")),
+        warnings: loaded.warnings,
+        untested: (0, test_coverage_js_1.findUntestedSurfaces)({ basePath: dir }).untested.length,
+    };
+}
+function section(title, lines) {
+    if (lines.length === 0)
+        return [];
+    return [`${title} (${String(lines.length)}):`, ...lines, ""];
+}
+/** Format a scan report as human-readable text. */
+function formatScanReport(r) {
+    const out = [`Scan: ${r.dir}`, ""];
+    out.push(...section("Skills", r.skills.map((s) => {
+        const mark = s.hasDescription ? "✓" : "⚠";
+        const note = s.hasDescription
+            ? s.userInvoked
+                ? "(user-invoked)"
+                : ""
+            : "(missing/short description — can't trigger)";
+        return `  ${mark} ${s.name} ${note}`.trimEnd();
+    })));
+    out.push(...section("Agents", r.agents.map((a) => {
+        const tools = a.tools === null
+            ? "tools: (inherits all — no contract)"
+            : `tools: ${a.tools.join(", ") || "(none)"}`;
+        return `  ${a.tools === null ? "⚠" : "✓"} ${a.name} — ${tools}`;
+    })));
+    const hookMark = {
+        ok: "✓",
+        missing: "✗",
+        unresolved: "?",
+    };
+    const hookNote = {
+        ok: "",
+        missing: " (referenced but MISSING)",
+        unresolved: " (unresolved var — can't check)",
+    };
+    const hookLines = r.hooks.map((h) => `  ${hookMark[h.status]} ${h.script}${hookNote[h.status]}`);
+    if (r.inlineHooks > 0) {
+        hookLines.push(`  · ${String(r.inlineHooks)} inline hook(s) (no script file)`);
+    }
+    out.push(...section("Hooks", hookLines));
+    const facts = [];
+    if (r.commands > 0)
+        facts.push(`Commands: ${String(r.commands)}`);
+    facts.push(`MCP servers: ${r.mcp ? "yes" : "no"}`);
+    facts.push(`Untested surfaces: ${String(r.untested)}`);
+    out.push(...facts, "");
+    if (r.warnings.length > 0) {
+        out.push("Warnings:", ...r.warnings.map((w) => `  - ${w}`), "");
+    }
+    const broken = r.hooks.filter((h) => h.status === "missing").length +
+        r.skills.filter((s) => !s.hasDescription).length;
+    out.push(broken === 0
+        ? "✓ no structural issues found"
+        : `⚠ ${String(broken)} structural issue(s) — see ✗/⚠ above`);
+    return out.join("\n");
+}
+//# sourceMappingURL=scan.js.map