vigiles 14.7.0 → 14.9.0

package/dist/scan.js

@@ -12,9 +12,21 @@
  * 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.
  */
+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 });
-exports.isManagedHookCommand = isManagedHookCommand;
-exports.preferCompiledHooksMessage = preferCompiledHooksMessage;
 exports.scanPlugin = scanPlugin;
 exports.verifyLiveMcpTools = verifyLiveMcpTools;
 exports.formatMcpContractReport = formatMcpContractReport;
@@ -27,538 +39,25 @@ const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
 const layout_js_1 = require("./adapters/claude-code/layout.js");
 const dialect_js_1 = require("./adapters/claude-code/dialect.js");
 const plugin_loader_js_2 = require("./plugin-loader.js");
-const tool_contract_js_1 = require("./core/tool-contract.js");
 const hook_events_js_1 = require("./core/hook-events.js");
 const mcp_config_js_1 = require("./core/mcp-config.js");
 const hook_normalize_js_1 = require("./core/hook-normalize.js");
-const linters_js_1 = require("./core/linters.js");
-const frontmatter_read_js_1 = require("./core/frontmatter-read.js");
-const description_overlap_js_1 = require("./core/description-overlap.js");
-const skill_description_budget_js_1 = require("./core/skill-description-budget.js");
-const mcp_tool_js_1 = require("./core/mcp-tool.js");
 const mcp_js_1 = require("./core/mcp.js");
+const mcp_contract_message_js_1 = require("./core/mcp-contract-message.js");
 const mcp_hook_js_1 = require("./core/mcp-hook.js");
-const lethal_trifecta_js_1 = require("./core/lethal-trifecta.js");
-const skill_resources_js_1 = require("./core/skill-resources.js");
-const skill_missing_fence_js_1 = require("./core/skill-missing-fence.js");
 const plugin_dir_layout_js_1 = require("./core/plugin-dir-layout.js");
-const delegation_trifecta_js_1 = require("./core/delegation-trifecta.js");
 const hook_block_ineffective_js_1 = require("./core/hook-block-ineffective.js");
 const hook_matcher_js_1 = require("./core/hook-matcher.js");
-const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
 const test_coverage_js_1 = require("./test-coverage.js");
-const effects_js_1 = require("./core/effects.js");
+const scan_core_js_1 = require("./scan-core.js");
+// Re-export the pure detectors (and their public types: SurfaceClassifier,
+// SkillScanContext, isManagedHookCommand, preferCompiledHooksMessage, ...) that
+// moved to the node-free `./scan-core.js`, so every existing consumer of
+// `./scan.js` is unchanged — one detector, no drift.
+__exportStar(require("./scan-core.js"), exports);
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------
-const SCRIPT_RE = /\S+\.(?:sh|mjs|cjs|js|ts|py|rb)\b/g;
-// The scalar fields scan reads from a skill/agent `---` block, via the shared
-// lenient reader (core/frontmatter-read.ts) — a real YAML parse with a regex
-// salvage on malformed input, so block scalars / multi-line quoted values parse
-// for free and a bad block still yields what it can. One reader, no drift.
-function frontmatter(md) {
-    const fm = (0, frontmatter_read_js_1.readFrontmatter)(md);
-    return {
-        name: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "name"),
-        description: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "description"),
-        model: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "model"),
-        color: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "color"),
-    };
-}
-function escapeRe(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function makeClassifier(layout) {
-    // An empty dir means "this harness has no such surface" → never matches.
-    const at = (dir) => dir ? `(?:^|/)${escapeRe(dir)}/` : null;
-    const skill = at(layout.skillDir);
-    const agent = at(layout.agentDir);
-    const command = at(layout.commandDir);
-    const skillRe = skill ? new RegExp(`${skill}[^/]+/SKILL\\.md$`) : null;
-    const agentRe = agent ? new RegExp(`${agent}[^/]+\\.md$`) : null;
-    const commandRe = command ? new RegExp(`${command}.+\\.md$`) : null;
-    // A subagent lives at the plugin's TOP-LEVEL `agents/` dir (e.g. `agents/foo.md`
-    // or `.claude/agents/foo.md`), never recursively under ANOTHER surface dir. Two
-    // real-world nesting traps are excluded as false positives:
-    //   - `skills/<x>/agents/…` — skill-internal worker docs (Anthropic's skill-creator)
-    //   - `commands/agents/…`   — a COMMAND namespaced `/agents:…` (ruvnet/claude-flow),
-    //     incl. a `README.md`; these are commands, not dispatchable subagents.
-    // Flagging either as a subagent missing frontmatter is a false positive (it
-    // mis-graded a real plugin F). A genuine top-level `agents/foo.md` still
-    // matches. Both excluded dirs are read from the layout (adapter-agnostic). See
-    // scan.test.ts for the regressions.
-    const nestedUnder = [
-        layout.skillDir &&
-            `${escapeRe(layout.skillDir)}/.+/${escapeRe(layout.agentDir)}/`,
-        layout.commandDir &&
-            `${escapeRe(layout.commandDir)}/(?:.+/)?${escapeRe(layout.agentDir)}/`,
-    ].filter((x) => Boolean(x));
-    const nestedAgentRe = layout.agentDir && nestedUnder.length
-        ? new RegExp(`(?:^|/)(?:${nestedUnder.join("|")})`)
-        : null;
-    const isAgent = (f) => (agentRe?.test(f) ?? false) &&
-        !f.endsWith(".spec.ts") &&
-        !(nestedAgentRe?.test(f) ?? false);
-    return {
-        isSkill: (f) => skillRe?.test(f) ?? false,
-        isAgent,
-        isCommand: (f) => commandRe?.test(f) ?? false,
-    };
-}
-function skillName(path) {
-    return (path
-        .replace(/\/SKILL\.md$/, "")
-        .split("/")
-        .pop() ?? path);
-}
-/**
- * The first prose paragraph of a SKILL.md body (after the frontmatter and any
- * leading `#` headings) — Claude Code's FALLBACK skill description when the
- * frontmatter omits `description`. Used so the trigger-surface check doesn't
- * overclaim "can't trigger" for a skill that has a usable body paragraph.
- */
-function firstBodyParagraph(md) {
-    const body = md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
-    const para = [];
-    for (const line of body.split(/\r?\n/)) {
-        const t = line.trim();
-        if (t === "" || t.startsWith("#")) {
-            if (para.length > 0)
-                break; // end of the first paragraph
-            continue; // skip leading blanks / headings
-        }
-        para.push(t);
-    }
-    return para.join(" ").trim() || undefined;
-}
-/** The body of a SKILL.md with the leading `---` frontmatter block stripped. */
-function skillBody(md) {
-    return md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
-}
-/**
- * The on-disk path for a materialized file key. `loadPlugin` prefixes each
- * surface file with the layout's `materializeRoot` (e.g. `.claude/`), but the file
- * lives on disk WITHOUT that prefix (under the real surface dir), so a
- * bundled-resource existence check must strip it back off. Mirrors how
- * `resolveScript` resolves a hook path against the real plugin root.
- */
-function onDiskPath(materializedKey, materializeRoot) {
-    if (!materializeRoot)
-        return materializedKey;
-    const prefix = `${materializeRoot}/`;
-    return materializedKey.startsWith(prefix)
-        ? materializedKey.slice(prefix.length)
-        : materializedKey;
-}
-function scanSkills(files, cls, ctx) {
-    const { root, materializeRoot, dialect, sharedDirs } = ctx;
-    // `sharedDirs` are declared relative to the REPO root (config location), which
-    // is `root` for a whole-repo scan but a PARENT when the scan is scoped to a
-    // subdir. Resolve them against that, not the scoped subdir.
-    const sharedDirsRoot = ctx.sharedDirsRoot ?? root;
-    const out = [];
-    for (const [path, md] of Object.entries(files)) {
-        if (!cls.isSkill(path))
-            continue;
-        // Prefer the real on-disk dir (a `.claude/skills/…` skill materializes under
-        // the same canonical key as a repo-root one, but lives elsewhere on disk).
-        const onDiskDir = ctx.sources?.[path];
-        const fm = frontmatter(md);
-        // A skill's trigger surface is its frontmatter `description` OR — when that's
-        // absent — Claude Code's fallback to the first body paragraph. Only when
-        // NEITHER exists is the skill genuinely undescribed (can't be selected). The
-        // explicit-frontmatter best-practice is the separate `skill-frontmatter` rule.
-        const effectiveDesc = fm.description ?? firstBodyParagraph(md);
-        const userInvoked = /^\s*disable-model-invocation:\s*true\s*$/m.test(md);
-        // Bundled-resource refs resolve against the skill's OWN dir (resources ship
-        // beside the SKILL.md), built from the plugin root + the file's ON-DISK dir
-        // (the materialize-root prefix the loader added is stripped back off).
-        const skillDir = onDiskDir
-            ? (0, node_path_1.dirname)(onDiskDir)
-            : (0, node_path_1.resolve)(root, (0, node_path_1.dirname)(onDiskPath(path, materializeRoot)));
-        // Bundled refs resolve against the skill's OWN dir. A repo that shares a
-        // top-level tree across skills (`sharedDirs` in .vigilesrc.json) ALSO resolves
-        // a ref under one of those declared dirs against the repo root — OPT-IN, so a
-        // repo that doesn't set it is byte-identical to before (no masking of a real
-        // missing bundled resource). See feedback P1-4.
-        const resourceIssues = (0, skill_resources_js_1.skillResourceIssues)(skillBody(md), skillDir, {
-            repoRoot: sharedDirsRoot,
-            sharedDirs,
-        });
-        // The lethal trifecta is a property of what a unit CAN do, which for a skill is
-        // its declared `allowed-tools` (the CC skill tool contract). Only a model-
-        // invocable skill can be hijacked by attacker content, so a user-invoked one is
-        // excluded. A skill with no `allowed-tools` line inherits all → advisory.
-        const skillTools = (0, agent_runtime_js_1.parseAgentToolList)(md, "allowed-tools");
-        // No `allowed-tools:` line (null) → inherits all → wildcard sentinel; an
-        // EXPLICIT empty `[]` means zero tools → no trifecta (don't collapse them).
-        const trifecta = userInvoked
-            ? null
-            : (0, lethal_trifecta_js_1.lethalTrifectaIssues)(skillTools ?? ["*"], dialect);
-        out.push({
-            name: fm.name ?? skillName(path),
-            path,
-            hasDescription: Boolean(effectiveDesc && effectiveDesc.length >= 20),
-            description: effectiveDesc?.trim(),
-            userInvoked,
-            resourceIssues,
-            trifecta,
-            // A SKILL.md opening with `name:`/`description:` but no `---` fence loads
-            // as plain body → the skill is invisible. Inspect the RAW md (not the
-            // frontmatter-stripped body) so the unfenced keys are visible.
-            fenceIssue: (0, skill_missing_fence_js_1.skillMissingFence)(md),
-        });
-    }
-    return out.sort((a, b) => a.name.localeCompare(b.name));
-}
-/**
- * Near-duplicate description pairs among the MODEL-INVOCABLE skills — the ones
- * that actually compete for auto-selection (a user-invoked skill is picked by
- * explicit command, so it can't collide). Uses the same effective-description
- * logic as `scanSkills` (frontmatter `description` ← first body paragraph), then
- * the NCD precision-proxy. See description-overlap.ts.
- */
-function modelInvocableSkillSurfaces(files, cls) {
-    const surfaces = [];
-    for (const [path, md] of Object.entries(files)) {
-        if (!cls.isSkill(path))
-            continue;
-        if (/^\s*disable-model-invocation:\s*true\s*$/m.test(md))
-            continue;
-        const fm = frontmatter(md);
-        const description = fm.description ?? firstBodyParagraph(md);
-        if (!description || description.length < 20)
-            continue;
-        surfaces.push({ name: fm.name ?? skillName(path), description });
-    }
-    return surfaces;
-}
-function descriptionOverlapsFor(files, cls) {
-    return (0, description_overlap_js_1.findDescriptionOverlaps)(modelInvocableSkillSurfaces(files, cls));
-}
-/**
- * Model-invocable skills whose description is so long the trigger signal is
- * buried (heuristic proxy; degrades recall + precision). Same surfaces as the
- * overlap check. See skill-description-budget.ts.
- */
-function descriptionBudgetFor(files, cls) {
-    return (0, skill_description_budget_js_1.findDescriptionBudgetIssues)(modelInvocableSkillSurfaces(files, cls));
-}
-function scanAgents(files, dialect, declaredServers, cls) {
-    const out = [];
-    for (const [path, md] of Object.entries(files)) {
-        if (!cls.isAgent(path))
-            continue;
-        const tools = (0, agent_runtime_js_1.parseAgentTools)(md);
-        // An inherits-all agent (no `tools:` line) grants access to every tool
-        // including every side-effecting one — pass the wildcard sentinel so
-        // effectSurface correctly classifies it as `"unrestricted"`.
-        const surface = (0, effects_js_1.effectSurface)(tools ?? ["*"], dialect);
-        out.push({
-            name: (0, node_path_1.basename)(path, ".md"),
-            path,
-            tools,
-            // Cross-reference the declared rail against the dialect catalog — the moat.
-            // Auditing third-party plugins → only the HIGH-CONFIDENCE issues (never-
-            // available + close typos); a bare unrecognized tool is likely plugin/MCP-
-            // provided, not a defect (the TaskCreate/TaskGet lesson). See tool-contract.ts.
-            toolIssues: tools
-                ? (0, tool_contract_js_1.confidentToolIssues)((0, tool_contract_js_1.verifyToolContract)(tools, dialect))
-                : [],
-            // The MCP half of the moat: an `mcp__server__tool` whose server isn't in the
-            // plugin's declared set can't resolve. High-precision (gated on a declared
-            // set, built-ins allowlisted, plugin-namespaced form skipped). See mcp-tool.ts.
-            mcpToolIssues: tools
-                ? (0, mcp_tool_js_1.verifyMcpToolServers)(tools, declaredServers, dialect)
-                : [],
-            // The block-list mirror: a `disallowedTools:` entry that's a typo of a real
-            // tool blocks nothing (close-typo only — high-precision). See tool-contract.ts.
-            disallowedToolIssues: (0, tool_contract_js_1.disallowedToolIssues)((0, agent_runtime_js_1.parseAgentToolList)(md, "disallowedTools") ?? [], dialect),
-            purity: surface.purity,
-            effectBuckets: {
-                readOnly: surface.readOnly,
-                sideEffecting: surface.sideEffecting,
-                unknown: surface.unknown,
-            },
-            // The lethal trifecta: a subagent whose contract grants all three legs. An
-            // inherits-all agent (no `tools:` line → tools === null) is the advisory
-            // case — pass the wildcard sentinel so it's distinguished from an EXPLICIT
-            // empty `tools: []` (zero tools → no trifecta). One detector, no drift.
-            trifecta: (0, lethal_trifecta_js_1.lethalTrifectaIssues)(tools ?? ["*"], dialect),
-        });
-    }
-    return out.sort((a, b) => a.name.localeCompare(b.name));
-}
-/**
- * Resolve a hook script token to a checkable path. `loadPlugin` expands the
- * braced plugin-root token (`${CLAUDE_PLUGIN_ROOT}`, Codex `${PLUGIN_ROOT}`, …);
- * the unbraced shell form survives, so resolve BOTH forms of the HARNESS's token
- * (from the layout, not hard-coded) against the plugin root and strip shell
- * quotes. A token that still carries any `$VAR` after that is genuinely
- * uncheckable.
- */
-function resolveScript(token, root, pluginRootToken, fullCommand) {
-    // "${CLAUDE_PLUGIN_ROOT}" → unbraced "$CLAUDE_PLUGIN_ROOT".
-    const unbraced = pluginRootToken.replace(/^\$\{(.+)\}$/, "$$$1");
-    const cleaned = token
-        .replace(/["']/g, "")
-        .replaceAll(pluginRootToken, root)
-        .replaceAll(unbraced, root);
-    if (cleaned.includes("$"))
-        return { command: fullCommand, script: token, status: "unresolved" };
-    // A relative hook path (`./hooks/x.sh`, `scripts/x.py`) is the plugin's own —
-    // resolve it against the PLUGIN ROOT, not the scanner's cwd. Without this, a
-    // plugin that references `./hooks/x.sh` (the file IS present) was reported
-    // MISSING because existsSync() checked cwd-relative (a false positive caught on
-    // ananddtyagi/cc-marketplace). The displayed `script` stays as the author wrote it.
-    const abs = (0, node_path_1.isAbsolute)(cleaned) ? cleaned : (0, node_path_1.resolve)(root, cleaned);
-    // Resolve the full command the same way we resolve the script token (expand
-    // plugin-root, strip outer quotes) so the CLI can pass it to verifyGuardrail.
-    const resolvedCommand = fullCommand
-        .replaceAll(pluginRootToken, root)
-        .replaceAll(unbraced, root);
-    return {
-        command: resolvedCommand,
-        script: cleaned,
-        status: (0, node_fs_1.existsSync)(abs) ? "ok" : "missing",
-    };
-}
-// A shell existence guard around a command — `[ ! -f x ] || x`, `[ -f x ] && x`,
-// `test -f x && …`. Authors use it to make a hook OPTIONAL (run the script only
-// if present; a no-op otherwise — e.g. a runtime-generated guard), so a missing
-// target is INTENTIONAL, not a broken reference. Don't flag scripts in such a
-// command as MISSING (a false positive caught on gmickel/flow-next's ralph-guard).
-const EXISTENCE_GUARD = /(?:\[\[?\s*!?\s*-[efsx]\s)|(?:\btest\s+!?\s*-[efsx]\s)/;
-/**
- * A compiled `vigiles/hook` artifact runs through the `hook-runtime run-program`
- * runtime entrypoint; any other hook command is hand-written (a shell script or
- * an inline one-liner) the author maintains directly. The basis for the
- * `prefer-compiled-hooks` nudge.
- */
-function isManagedHookCommand(command) {
-    return /\bhook-runtime\b/.test(command);
-}
-/** The `prefer-compiled-hooks` recommendation message (shared by `lint` + `scan`). */
-function preferCompiledHooksMessage(count) {
-    return (`${String(count)} hand-written hook command(s) — if any gate the agent ` +
-        `(a block/deny decision), compiled hooks (\`vigiles/hook\`) make whole hook ` +
-        `bug classes unrepresentable at authoring time, and \`guardrail-check\` proves ` +
-        `an existing one blocks. See docs/compiled-hooks.md.`);
-}
-/** Pull script-file hook commands out of the resolved settings; count inline ones. */
-/**
- * Best-effort map of each script token → the hook EVENT it's registered under,
- * by walking the canonical object-keyed-by-event settings shape
- * (`{ PreToolUse: [{ hooks: [{ command }] }], … }`). Lets the safety battery
- * scope itself to `PreToolUse` (the only event that can block a tool call), so a
- * `SessionStart`/`PostToolUse`/`Stop` hook isn't tested against the disaster
- * catalog. Returns an empty map for a non-object/array config (event → unknown).
- */
-function eventsByScript(regs) {
-    const map = new Map();
-    for (const reg of regs) {
-        for (const tok of reg.command.match(SCRIPT_RE) ?? []) {
-            if (!map.has(tok))
-                map.set(tok, reg.event);
-        }
-    }
-    return map;
-}
-function scanHooks(regs, root, pluginRootToken) {
-    const commands = regs.map((r) => r.command);
-    const evMap = eventsByScript(regs);
-    // A hand-written hook is any non-empty command that isn't a vigiles-managed
-    // (compiled) hook-runtime invocation — the basis for the prefer-compiled-hooks nudge.
-    const manual = commands.filter((c) => {
-        const u = c.trim();
-        return u !== "" && !isManagedHookCommand(u);
-    }).length;
-    const byScript = new Map();
-    let inline = 0;
-    for (const cmd of commands) {
-        const found = cmd.match(SCRIPT_RE);
-        if (!found || found.length === 0) {
-            inline++;
-            continue;
-        }
-        // A guarded command runs its script only if it exists — an optional hook, not
-        // a broken one. Treat it as a conditional one-liner (inline), don't path-check.
-        if (EXISTENCE_GUARD.test(cmd)) {
-            inline++;
-            continue;
-        }
-        for (const tok of found) {
-            const hook = resolveScript(tok, root, pluginRootToken, cmd);
-            const event = evMap.get(tok);
-            byScript.set(hook.script, event ? { ...hook, event } : hook);
-        }
-    }
-    const hooks = [...byScript.values()].sort((a, b) => a.script.localeCompare(b.script));
-    return { hooks, inline, manual };
-}
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Frontmatter-schema check — **subagents only**. Per the Claude Code docs, a
- * subagent (`agents/*.md`) REQUIRES `name` + `description` (no fallback) or it
- * won't register. A SKILL.md requires NOTHING: `name` falls back to the directory
- * name and `description` to the first body paragraph, so a frontmatter-less skill
- * still loads — flagging it would be a false positive (skill description QUALITY
- * is a separate, behavioral concern). See https://code.claude.com/docs/en/skills
- * and …/sub-agents.
- */
-function frontmatterIssuesFor(files, cls) {
-    const out = [];
-    for (const [path, md] of Object.entries(files)) {
-        if (!cls.isAgent(path))
-            continue; // skills require no frontmatter (dir/body fallbacks)
-        const fm = frontmatter(md);
-        const missing = [];
-        if (!fm.name)
-            missing.push("name");
-        if (!fm.description)
-            missing.push("description");
-        if (missing.length === 0)
-            continue;
-        out.push({
-            path,
-            kind: "agent",
-            missing,
-            message: `agent ${path} is missing required frontmatter: ${missing.join(", ")} — it won't register.`,
-        });
-    }
-    return out.sort((a, b) => a.path.localeCompare(b.path));
-}
-// The canonical subagent `model:` aliases and `color:` enum (Claude Code). The
-// model check skips a full/dated id (`claude-sonnet-4-5`) — that's a valid
-// explicit form, not a typo — so only an alias misspelling is caught.
-const MODEL_ALIASES = ["inherit", "sonnet", "opus", "haiku"];
-const AGENT_COLORS = [
-    "red",
-    "blue",
-    "green",
-    "yellow",
-    "purple",
-    "orange",
-    "pink",
-    "cyan",
-];
-/**
- * Closest candidate by edit distance, ONLY when it's a high-confidence typo: the
- * value isn't already a candidate, and the nearest is within 2 edits. Returns
- * null otherwise — a far-off value is more likely an unknown-we-don't-know than a
- * typo (the high-precision discipline), so it's suppressed, not flagged.
- */
-function closeCandidate(value, candidates) {
-    const v = value.toLowerCase();
-    if (candidates.includes(v))
-        return null;
-    let best = null;
-    let bestDistance = Infinity;
-    for (const c of candidates) {
-        const dist = (0, linters_js_1.editDistance)(v, c);
-        if (dist < bestDistance) {
-            bestDistance = dist;
-            best = c;
-        }
-    }
-    return bestDistance > 0 && bestDistance <= 2 ? best : null;
-}
-/**
- * Agent frontmatter VALUE validity — a `model:` or `color:` that's a close typo
- * of a real one. A bad `model:` silently falls back; a bad `color:` is ignored.
- * High-precision (close-typo only); a full/dated model id is left alone. Folded
- * into the `subagent-frontmatter` rule. Agents only (skills have no model/color).
- */
-function frontmatterValueIssuesFor(files, cls) {
-    const out = [];
-    for (const [path, md] of Object.entries(files)) {
-        if (!cls.isAgent(path))
-            continue;
-        const fm = frontmatter(md);
-        // A model id with a digit/hyphen is an explicit form, not an alias typo.
-        if (fm.model && !/[0-9-]/.test(fm.model)) {
-            const near = closeCandidate(fm.model, MODEL_ALIASES);
-            if (near) {
-                out.push({
-                    path,
-                    field: "model",
-                    value: fm.model,
-                    suggestion: near,
-                    message: `agent ${path} has model "${fm.model}", not a known alias — it silently falls back. Did you mean "${near}"?`,
-                });
-            }
-        }
-        if (fm.color) {
-            const near = closeCandidate(fm.color, AGENT_COLORS);
-            if (near) {
-                out.push({
-                    path,
-                    field: "color",
-                    value: fm.color,
-                    suggestion: near,
-                    message: `agent ${path} has color "${fm.color}", not a valid color — it's ignored. Did you mean "${near}"?`,
-                });
-            }
-        }
-    }
-    return out.sort((a, b) => a.path.localeCompare(b.path));
-}
-/**
- * Frontmatter that EXISTS but isn't valid YAML — the `frontmatter-valid` signal.
- * Reported for skills + agents via the shared reader's `malformed` flag. Honest
- * caveat (see docs/rules/frontmatter-valid.md): js-yaml is stricter than some
- * loaders, so a one-line `description:` containing a `: ` colon or an `<example>`
- * block is flagged even though it may still load — which is why scan surfaces it
- * as an informational note (NOT a structural defect) and the lint rule is a
- * warn, not an error. The file's other fields are still salvaged.
- */
-function malformedFrontmatterFor(files, cls) {
-    const out = [];
-    for (const [path, md] of Object.entries(files)) {
-        if (!cls.isSkill(path) && !cls.isAgent(path))
-            continue;
-        if (!(0, frontmatter_read_js_1.readFrontmatter)(md).malformed)
-            continue;
-        out.push({
-            path,
-            message: `${path}: frontmatter is not valid YAML — fields may not parse as intended (a colon, quote, or bracket likely needs escaping/quoting).`,
-        });
-    }
-    return out.sort((a, b) => a.path.localeCompare(b.path));
-}
-/**
- * Skill-metadata RECOMMENDATION (not a correctness check): a `SKILL.md` loads
- * fine without frontmatter (`name` ← dir, `description` ← first body paragraph),
- * but relying on those fallbacks is fragile — the dir name may be unclear and the
- * first paragraph is often a heading or boilerplate, making a weak trigger
- * surface. Best practice is an EXPLICIT `name` + `description`. Flags skills
- * missing either; surfaced as a soft note in scan (NOT a structural defect, NOT
- * scored) and gated by the `skill-frontmatter` lint rule (warn by default).
- */
-function skillMetaIssuesFor(files, cls) {
-    const out = [];
-    for (const [path, md] of Object.entries(files)) {
-        if (!cls.isSkill(path))
-            continue;
-        const fm = frontmatter(md);
-        const missing = [];
-        if (!fm.name)
-            missing.push("name");
-        if (!fm.description)
-            missing.push("description");
-        if (missing.length === 0)
-            continue;
-        out.push({
-            path,
-            kind: "skill",
-            missing,
-            message: `skill ${path} has no explicit frontmatter ${missing.join(" / ")} — recommended for a reliable trigger surface (it still loads via the dir-name / first-paragraph fallback).`,
-        });
-    }
-    return out.sort((a, b) => a.path.localeCompare(b.path));
-}
 /**
  * Collect declared MCP servers from the JSON sources (`.mcp.json` + the plugin
  * manifest's `mcpServers`). Codex's TOML `[mcp_servers]` isn't parsed here (a
@@ -586,149 +85,35 @@ function collectMcpServers(root, layout) {
     collect(layout.manifestPath);
     return servers;
 }
-/**
- * Flatten the per-surface lethal-trifecta + skill-resource findings into the
- * path-tagged report lists the `audit` report AND the `lethal-trifecta` /
- * `skill-resource-resolves` lint rules both consume (one detector, no drift).
- */
-function collectSurfaceFindings(agents, skills) {
-    const trifectaFindings = [];
-    for (const a of agents) {
-        if (a.trifecta) {
-            trifectaFindings.push({
-                path: a.path,
-                kind: "subagent",
-                name: a.name,
-                finding: a.trifecta,
-            });
-        }
+// Disk-backed IO the moved detectors take by injection (they never import
+// `node:fs`, so the browser engine can inject a map-backed pair instead).
+const nodeReadFile = (p) => {
+    try {
+        return (0, node_fs_1.readFileSync)(p, "utf8");
     }
-    for (const s of skills) {
-        if (s.trifecta) {
-            trifectaFindings.push({
-                path: s.path,
-                kind: "skill",
-                name: s.name,
-                finding: s.trifecta,
-            });
-        }
+    catch {
+        return "";
     }
-    const skillResourceFindings = skills.flatMap((s) => s.resourceIssues.map((finding) => ({
-        path: s.path,
-        name: s.name,
-        finding,
-    })));
-    const skillFenceFindings = skills.flatMap((s) => s.fenceIssue ? [{ path: s.path, name: s.name, finding: s.fenceIssue }] : []);
-    return { trifectaFindings, skillResourceFindings, skillFenceFindings };
-}
-/**
- * Build the subagent delegation graph and flag a lethal trifecta that EMERGES
- * across an edge (own ∪ delegated-to capability) though no single unit trips it.
- *
- * Edge source (deterministic, audit-available): a subagent that lists the `Task`
- * tool can dispatch any sibling subagent, so it `delegatesTo` every OTHER agent.
- * An inherits-all agent (`tools === null`) carries the wildcard, which the
- * detector's FP-safe guard skips (that maximal-blast case is the per-unit
- * advisory's job). One detector, no drift. (Richer edge sources — a typed
- * railway's `delegate()` chain, a Flue subagent inheritance tree — plug in here.)
- */
-function collectDelegationTrifecta(agents, dialect) {
-    const allNames = agents.map((a) => a.name);
-    const nodes = agents.map((a) => {
-        const canDispatch = a.tools === null ||
-            a.tools.some((t) => t === "Task" || t.startsWith("Task("));
-        return {
-            name: a.name,
-            kind: "agent",
-            tools: a.tools ?? ["*"],
-            delegatesTo: canDispatch ? allNames.filter((n) => n !== a.name) : [],
-        };
-    });
-    const pathByName = new Map(agents.map((a) => [a.name, a.path]));
-    return (0, delegation_trifecta_js_1.delegationTrifectaIssues)(nodes, dialect).map((finding) => ({
-        path: pathByName.get(finding.name) ?? "",
-        finding,
-    }));
-}
-/**
- * Build `hookBlockIssues` entries by walking the canonical object-keyed-by-event
- * settings shape PER REGISTRATION — so a script registered under several events
- * is inspected under EACH (no de-dup by script path), inline one-liners are
- * included (script token → null, inspect the command), and a script token is
- * resolved to its ABSOLUTE on-disk path against the plugin root (not the caller's
- * cwd). Addresses the gaps a de-duplicated `ScanHook[]` would miss.
- */
-function collectHookBlockEntries(regs, root, pluginRootToken) {
-    const out = [];
-    for (const { event, command: cmd } of regs) {
-        // A wrapper command runs MORE than one script (`node run.cjs guard.mjs`),
-        // so resolve EVERY candidate and inspect each — reading only the first
-        // (the wrapper) would miss the guard's block logic. Candidates: extensioned
-        // script tokens (SCRIPT_RE) PLUS path-like words with NO extension
-        // (`bash hooks/guard`, `${ROOT}/hooks/session-start`) that resolve to a file.
-        const candidates = new Set(cmd.match(SCRIPT_RE) ?? []);
-        for (const word of cmd.split(/\s+/)) {
-            const w = word.replace(/^["']+|["']+$/g, "");
-            if (w.startsWith("-"))
-                continue; // a flag, not a path
-            if (w.includes("/") || w.includes(pluginRootToken))
-                candidates.add(w);
-        }
-        const resolvedPaths = [];
-        for (const tok of candidates) {
-            const r = resolveScript(tok, root, pluginRootToken, cmd);
-            if (r.status === "ok") {
-                const abs = (0, node_path_1.isAbsolute)(r.script) ? r.script : (0, node_path_1.resolve)(root, r.script);
-                if (!resolvedPaths.includes(abs))
-                    resolvedPaths.push(abs);
-            }
-        }
-        if (resolvedPaths.length > 0) {
-            // One entry per resolvable script (each is inspected on its own).
-            for (const sp of resolvedPaths) {
-                out.push({ event, command: cmd, scriptPath: sp });
-            }
-        }
-        else {
-            // No script file resolved → inline one-liner; inspect the command text.
-            out.push({ event, command: cmd, scriptPath: null });
-        }
+};
+const nodeIsDirectory = (p) => {
+    try {
+        return (0, node_fs_1.statSync)(p).isDirectory();
     }
-    return out;
-}
-/** Extract (event, matcher) pairs from the normalized hook registrations. */
-function collectHookMatchers(regs) {
-    const seen = new Set();
-    const out = [];
-    for (const { event, matcher } of regs) {
-        if (matcher === null)
-            continue;
-        const key = `${event}${matcher}`;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        out.push({ event, matcher });
+    catch {
+        return false;
     }
-    return out;
-}
-/** Tally how many scanned agents fall into each purity rung (effectSurface). */
-function summarizePurity(agents) {
-    return agents.reduce((acc, a) => {
-        acc[a.purity]++;
-        return acc;
-    }, { pure: 0, bounded: 0, unrestricted: 0 });
-}
+};
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
 function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts = {}) {
     const lay = layout ?? layout_js_1.claudeCodeLayout;
-    const cls = makeClassifier(lay);
+    const cls = (0, scan_core_js_1.makeClassifier)(lay);
     const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, lay);
     // Parse the raw `settings.hooks` ONCE at the boundary (parse-don't-validate):
     // tolerant of the Claude Code nested shape AND the Codex flat shape, so every
     // hook detector below consumes typed `HookRegistration[]` instead of re-walking
     // `unknown`. The single seam where the per-harness hook shape is absorbed.
     const hookRegs = (0, hook_normalize_js_1.normalizeHooks)(loaded.settings.hooks);
-    const { hooks, inline, manual } = scanHooks(hookRegs, (0, node_path_1.resolve)(dir), lay.pluginRootToken);
+    const { hooks, inline, manual } = (0, scan_core_js_1.scanHooks)(hookRegs, (0, node_path_1.resolve)(dir), lay.pluginRootToken, node_fs_1.existsSync);
     // Hook-event keys are a CLOSED platform set — an unrecognized one is a dead
     // registration (the hook never fires), so flag every unknown (not just typos).
     // ONLY for the canonical object-keyed-by-event shape: a plugin shipping a
@@ -746,17 +131,18 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
         : null;
     const mcpServers = collectMcpServers((0, node_path_1.resolve)(dir), lay);
     const declaredServers = Object.keys(mcpServers);
-    const agents = scanAgents(loaded.files, dialect, declaredServers, cls);
-    const skills = scanSkills(loaded.files, cls, {
+    const agents = (0, scan_core_js_1.scanAgents)(loaded.files, dialect, declaredServers, cls);
+    const skills = (0, scan_core_js_1.scanSkills)(loaded.files, cls, {
         root: (0, node_path_1.resolve)(dir),
         materializeRoot: lay.materializeRoot,
         dialect,
         sources: loaded.sources,
         sharedDirs: opts.sharedDirs,
         sharedDirsRoot: opts.sharedDirsRoot,
+        existsSync: node_fs_1.existsSync,
     });
-    const puritySummary = summarizePurity(agents);
-    const { trifectaFindings, skillResourceFindings, skillFenceFindings } = collectSurfaceFindings(agents, skills);
+    const puritySummary = (0, scan_core_js_1.summarizePurity)(agents);
+    const { trifectaFindings, skillResourceFindings, skillFenceFindings } = (0, scan_core_js_1.collectSurfaceFindings)(agents, skills);
     return {
         dir,
         instructions,
@@ -769,13 +155,13 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
         mcp: loaded.warnings.some((w) => w.includes("MCP server")),
         danglingRefs: (0, plugin_loader_js_2.danglingRefs)((0, node_path_1.resolve)(dir), lay),
         hookEventIssues,
-        frontmatterIssues: frontmatterIssuesFor(loaded.files, cls),
-        frontmatterValueIssues: frontmatterValueIssuesFor(loaded.files, cls),
-        skillMetaIssues: skillMetaIssuesFor(loaded.files, cls),
+        frontmatterIssues: (0, scan_core_js_1.frontmatterIssuesFor)(loaded.files, cls),
+        frontmatterValueIssues: (0, scan_core_js_1.frontmatterValueIssuesFor)(loaded.files, cls),
+        skillMetaIssues: (0, scan_core_js_1.skillMetaIssuesFor)(loaded.files, cls),
         mcpIssues: (0, mcp_config_js_1.verifyMcpServers)(mcpServers),
         mcpHookIssues: (0, mcp_hook_js_1.verifyMcpHookTargets)(loaded.settings.hooks, declaredServers, dialect),
-        descriptionOverlaps: descriptionOverlapsFor(loaded.files, cls),
-        descriptionBudgetIssues: descriptionBudgetFor(loaded.files, cls),
+        descriptionOverlaps: (0, scan_core_js_1.descriptionOverlapsFor)(loaded.files, cls),
+        descriptionBudgetIssues: (0, scan_core_js_1.descriptionBudgetFor)(loaded.files, cls),
         trifectaFindings,
         skillResourceIssues: skillResourceFindings,
         skillFenceIssues: skillFenceFindings,
@@ -783,16 +169,17 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
         // The hooks dir is a misplaceable functional surface too, but it lives in
         // the layout as a convention PATH (`hooks/hooks.json`), not in surfaceDirs
         // — derive its first segment and dedupe so the detector watches it as well.
-        [...new Set([...lay.surfaceDirs, lay.hooksConventionPath.split("/")[0]])]),
-        delegationTrifecta: collectDelegationTrifecta(agents, dialect),
+        [...new Set([...lay.surfaceDirs, lay.hooksConventionPath.split("/")[0]])], { existsSync: node_fs_1.existsSync, isDirectory: nodeIsDirectory }),
+        delegationTrifecta: (0, scan_core_js_1.collectDelegationTrifecta)(agents, dialect),
         hookBlockFindings: dialect.noEffectHookEvents
-            ? (0, hook_block_ineffective_js_1.hookBlockIssues)(collectHookBlockEntries(hookRegs, (0, node_path_1.resolve)(dir), lay.pluginRootToken), {
+            ? (0, hook_block_ineffective_js_1.hookBlockIssues)((0, scan_core_js_1.collectHookBlockEntries)(hookRegs, (0, node_path_1.resolve)(dir), lay.pluginRootToken, node_fs_1.existsSync), {
                 noEffectEvents: new Set(dialect.noEffectHookEvents),
                 permissionDecisionEvents: new Set(dialect.permissionDecisionHookEvents ?? []),
+                readFileSync: nodeReadFile,
             })
             : [],
-        hookMatcherFindings: (0, hook_matcher_js_1.hookMatcherIssues)(collectHookMatchers(hookRegs), declaredServers, dialect),
-        malformedFrontmatter: malformedFrontmatterFor(loaded.files, cls),
+        hookMatcherFindings: (0, hook_matcher_js_1.hookMatcherIssues)((0, scan_core_js_1.collectHookMatchers)(hookRegs), declaredServers, dialect),
+        malformedFrontmatter: (0, scan_core_js_1.malformedFrontmatterFor)(loaded.files, cls),
         warnings: loaded.warnings,
         untested: (0, test_coverage_js_1.findUntestedSurfaces)({ basePath: dir, layout: lay }).untested
             .length,
@@ -827,7 +214,7 @@ function formatMcpContractReport(errors) {
     }
     const lines = [`Live MCP tool check — ${String(errors.length)} issue(s):`];
     for (const e of errors)
-        lines.push("  ✗ " + (0, mcp_js_1.mcpContractToolMessage)(e));
+        lines.push("  ✗ " + (0, mcp_contract_message_js_1.mcpContractToolMessage)(e));
     return lines.join("\n");
 }
 /**
@@ -1023,7 +410,7 @@ function formatScanReport(r) {
     // One discovery nudge toward compiled hooks (never per-hook); the hand-written
     // shell lane stays first-class, so this is a recommendation, not a defect.
     if (r.manualHookCount > 0) {
-        out.push(`ℹ ${preferCompiledHooksMessage(r.manualHookCount)}`, "");
+        out.push(`ℹ ${(0, scan_core_js_1.preferCompiledHooksMessage)(r.manualHookCount)}`, "");
     }
     // Malformed-YAML frontmatter is INFORMATIONAL, not a structural defect: js-yaml
     // is stricter than some loaders (a colon/quote/<example> in a one-line