vigiles 8.0.0 → 9.0.0

package/dist/scan.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * `vigiles scan <dir>` — point vigiles at any plugin/repo and see what it ships
+ * `vigiles audit <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
@@ -168,6 +168,7 @@ function scanSkills(files, cls) {
             name: fm.name ?? skillName(path),
             path,
             hasDescription: Boolean(effectiveDesc && effectiveDesc.length >= 20),
+            description: effectiveDesc?.trim(),
             userInvoked: /^\s*disable-model-invocation:\s*true\s*$/m.test(md),
             descriptionScript: effectiveDesc ? unexpectedScript(effectiveDesc) : null,
         });
@@ -244,7 +245,7 @@ function scanAgents(files, dialect, declaredServers, cls) {
  * quotes. A token that still carries any `$VAR` after that is genuinely
  * uncheckable.
  */
-function resolveScript(token, root, pluginRootToken) {
+function resolveScript(token, root, pluginRootToken, fullCommand) {
     // "${CLAUDE_PLUGIN_ROOT}" → unbraced "$CLAUDE_PLUGIN_ROOT".
     const unbraced = pluginRootToken.replace(/^\$\{(.+)\}$/, "$$$1");
     const cleaned = token
@@ -252,14 +253,23 @@ function resolveScript(token, root, pluginRootToken) {
         .replaceAll(pluginRootToken, root)
         .replaceAll(unbraced, root);
     if (cleaned.includes("$"))
-        return { script: token, status: "unresolved" };
+        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);
-    return { script: cleaned, status: (0, node_fs_1.existsSync)(abs) ? "ok" : "missing" };
+    // 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
@@ -284,9 +294,42 @@ function preferCompiledHooksMessage(count) {
         `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(hooks) {
+    const map = new Map();
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+        return map;
+    for (const [event, arr] of Object.entries(hooks)) {
+        if (!Array.isArray(arr))
+            continue;
+        for (const entry of arr) {
+            const hookList = entry.hooks;
+            if (!Array.isArray(hookList))
+                continue;
+            for (const h of hookList) {
+                const cmd = h.command;
+                if (typeof cmd !== "string")
+                    continue;
+                for (const tok of cmd.match(SCRIPT_RE) ?? []) {
+                    if (!map.has(tok))
+                        map.set(tok, event);
+                }
+            }
+        }
+    }
+    return map;
+}
 function scanHooks(settings, root, pluginRootToken) {
     const text = JSON.stringify(settings.hooks ?? {});
     const commands = [...text.matchAll(/"command":\s*"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1]);
+    const evMap = eventsByScript(settings.hooks);
     // 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) => {
@@ -309,8 +352,9 @@ function scanHooks(settings, root, pluginRootToken) {
             continue;
         }
         for (const tok of found) {
-            const hook = resolveScript(tok, root, pluginRootToken);
-            byScript.set(hook.script, hook);
+            const hook = resolveScript(tok, root, pluginRootToken, unescaped);
+            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));
@@ -564,14 +608,16 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
     };
 }
 /**
- * LIVE MCP tool resolution for a scanned plugin — the opt-in (`scan --verify-mcp`)
- * dynamic check no static linter can do: it STARTS each declared MCP server and
- * checks every `mcp__server__tool` the plugin's agents reference actually exists on
- * it (catching rename/removal rot, e.g. `create_issue`→`issue_write`). Reuses the
+ * LIVE MCP tool resolution for a scanned plugin — the dynamic check no static
+ * linter can do: it STARTS each declared MCP server and checks every
+ * `mcp__server__tool` the plugin's agents reference actually exists on it
+ * (catching rename/removal rot, e.g. `create_issue`→`issue_write`). Reuses the
  * already-computed `report` (its agents' tool lists) + the declared server configs;
  * returns `[]` when the plugin declares no MCP servers (nothing to start). Async +
- * side-effecting (spawns servers) — which is exactly why it's opt-in, not a default
- * lint rule. See `verifyMcpContractTools` (core/mcp.ts).
+ * side-effecting (spawns servers) — so `audit` runs it by default only for the
+ * user's OWN repo (own-repo, like running your own tools); a FOREIGN plugin's
+ * servers are never spawned, and `--fast` opts out. See `verifyMcpContractTools`
+ * (core/mcp.ts).
  */
 async function verifyLiveMcpTools(report, layout, dialect, timeoutMs = 10000) {
     // collectMcpServers yields the raw JSON server entries; a malformed one (no
@@ -596,7 +642,7 @@ function formatMcpContractReport(errors) {
  * Read a `marketplace.json` beside the layout's plugin manifest and classify its
  * members into on-disk vs external. Returns `null` when `dir` is not a
  * marketplace. The source of truth behind {@link expandMarketplace} and the
- * curated-marketplace report in `vigiles scan`.
+ * curated-marketplace report in `vigiles audit`.
  */
 function inspectMarketplace(dir, layout = layout_js_1.claudeCodeLayout) {
     const mpPath = (0, node_path_1.join)(dir, (0, node_path_1.dirname)(layout.manifestPath), "marketplace.json");
@@ -648,7 +694,7 @@ function inspectMarketplace(dir, layout = layout_js_1.claudeCodeLayout) {
  * plugin manifest, e.g. `.claude-plugin/marketplace.json`), expand it into the
  * absolute dirs of its member plugins. Returns `null` when there's no
  * marketplace, `[]` when it's a marketplace whose members are all external (not
- * on disk). Used by `vigiles scan` to rank a whole marketplace — wshobson/agents
+ * on disk). Used by `vigiles audit` to rank a whole marketplace — wshobson/agents
  * alone ships 80+ plugins under one `marketplace.json`. See {@link inspectMarketplace}.
  */
 function expandMarketplace(dir, layout = layout_js_1.claudeCodeLayout) {

package/dist/score-explainer.d.ts

@@ -35,7 +35,7 @@ export type BehavioralSymptom = "wrong-skill-fires" | "skill-never-fires" | "age
  *   never-available tool can't be called); the cause is near-certain.
  * - `"possible"` — a high-precision PROXY for a behavioral risk (a description
  *   overlap / a foreign-script description); deterministic to detect, but whether
- *   it actually moved behaviour is confirmed by `scan --trigger`.
+ *   it actually moved behaviour is confirmed by the `audit` trigger tier.
  */
 export type ExplanationConfidence = "likely" | "possible";
 export interface ScoreExplanation {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "8.0.0",
+  "version": "9.0.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",
@@ -55,6 +55,7 @@
     "dist/**/*.mjs",
     "dist/**/*.d.ts",
     "dist/**/*.d.mts",
+    "dist/audit-report.template.html",
     "!dist/**/*.test.js",
     "!dist/**/*.test.d.ts",
     "action.yml",
@@ -66,7 +67,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node scripts/build-report.mjs",
+    "build:core": "tsc",
     "test": "npm run build && vitest run",
     "coverage": "npm run build && vitest run --coverage",
     "lint": "eslint src/",

package/skills/test-harness/SKILL.md

@@ -39,7 +39,7 @@ surface sorts into one of three buckets:
 
 - **A — Free & deterministic** (no model, runs in CI on every commit): a hook's
   block/allow decision (`runHook`), a tool-contract / "did NOT call the forbidden
-  tool" check, structural facts (`vigiles scan`), and **record-replay** of any tool
+  tool" check, structural facts (`vigiles audit`), and **record-replay** of any tool
   a skill shells out to (record the real result once, replay it via a PATH stub).
 - **B — Model-gated, on your subscription** (real model, **no metered API**): does a
   skill's description **fire** (`measureTriggerRate`, recall + precision) **and**