@vibe-agent-toolkit/cli 0.2.0-rc.5 → 0.2.0-rc.7

package/dist/utils/run-integrity.js

@@ -0,0 +1,102 @@
+/**
+ * The run-integrity refusal: ONE mechanism for every gate that must never
+ * answer `success` after checking nothing.
+ *
+ * ## The class this closes
+ *
+ * A gate that checked nothing produces the same document as a gate that was
+ * removed. `vat resources check` shipped it (no `checks:` block → `status:
+ * success`, exit 0), then `vat claude budget` (a path matching no working
+ * location), then the repo's own audit quality gate (a green path over zero
+ * parsed findings), then `vat resources validate` (a `--collection` matching
+ * nothing → `filesScanned: 0`, exit 0), `vat claude marketplace validate` (no
+ * `plugins/` to walk, no count published), `vat corpus scan` (an empty tree
+ * "audits cleanly"), `vat verify`'s `packaged-content` phase (a typo'd glob
+ * discovers no bundle and the phase reports `success`), then `vat skills
+ * validate` (the same typo'd glob: one info line, no document, exit 0 — and
+ * `vat validate` folded that into `success`) and `vat audit` (an existing tree
+ * with nothing auditable: `status: success` over `filesScanned: 0`). Nine
+ * instances of one shape, and each was first fixed by hand at its own site.
+ * This module is where that hand-fixing stops: every site derives its refusal
+ * through the same three functions, so the invariants below are properties of
+ * the mechanism rather than of each author's memory.
+ *
+ * ## The invariants
+ *
+ * 1. **Code {@link RUN_INTEGRITY_CODE} — `RESOURCE_CHECK_BROKEN` — and never a
+ *    sibling per site.** It is the registry's one run-integrity claim — *these
+ *    assertions did not execute meaningfully, so the green means nothing* — and
+ *    `ValidationConfigSchema` refuses it as a `severity` key, which is what makes
+ *    it non-overridable by construction. A code per site would buy a consumer
+ *    nothing the message does not already say while adding one more thing an
+ *    adopter's CI has to know to look for.
+ * 2. **Severity `error`, and not a parameter.** The one thing that must never be
+ *    configurable about "the gate did not do its job" is whether it gates.
+ * 3. **Derived inside the DOCUMENT builder, never asserted in a handler.** The
+ *    builder is the one function every lane's document passes through, so
+ *    deriving the refusal there lands it after `resolveIssueSeverity` and
+ *    `applyAllowFilter` and makes "denominator zero, status clean"
+ *    unrepresentable rather than merely unwritten. A pure function, unit-testable
+ *    without I/O.
+ * 4. **ONE finding per run**, however many things went unmatched. The claim is
+ *    about the RUN; one per argument is per-finding duplication.
+ * 5. **The message says what did not run and what the operator can do.** It
+ *    must not claim the corpus is broken — it claims the run is not a verdict.
+ * 6. **stderr may still carry a human warning; the document and the exit code
+ *    must agree with it.** The human channel and the machine channel were what
+ *    disagreed in every shipped instance, and only the machine channel gates.
+ */
+/**
+ * The code every run-integrity refusal carries.
+ *
+ * 🔑 **One code for every refusal, on purpose.** A statement that would not
+ * compile, a corpus with no members, a run with no rules, a run that was killed,
+ * a scan that matched no file, a walk that missed a declared plugin, a phase that
+ * found no bundle — all are the same claim to a consumer, and they need the
+ * identical non-overridability, which
+ * `ValidationConfigSchema` grants by refusing this code as a `severity` key.
+ */
+export const RUN_INTEGRITY_CODE = 'RESOURCE_CHECK_BROKEN';
+/**
+ * A run-integrity refusal: the non-overridable code, at `error`, always.
+ *
+ * The severity is not a parameter and must not become one. Every caller is
+ * reporting that the gate did not do its job, and the one thing that must never
+ * be configurable about that report is whether it gates.
+ *
+ * @param message - What did not run, and what the operator can do about it
+ * @returns The finding
+ */
+export function runIntegrityFinding(message) {
+    return { code: RUN_INTEGRITY_CODE, severity: 'error', message };
+}
+/**
+ * The refusal for a run whose denominator is zero — nothing was checked.
+ *
+ * 🪤 **It asks the DENOMINATOR, never the config.** A builder cannot see why
+ * nothing ran and deliberately does not ask. An absent config block, a filter
+ * that matched nothing, a glob with a typo, a directory that was never built —
+ * all arrive as the same document, and all of them are a gate that asserted
+ * nothing. The message is where a site names the likely causes and the remedy.
+ *
+ * 🪤 **One report per situation.** A run that already carries a run-integrity
+ * finding (an interrupted run, say) has the more specific of the two claims on
+ * the document, so this stands down rather than handing the operator two reports
+ * about one situation. Nothing weaker is needed: every such finding is `error`,
+ * so the status is already refused.
+ *
+ * @param denominator - How many things the run actually checked
+ * @param issues - What the run already found, so an existing run-integrity
+ *   report is not duplicated
+ * @param message - The site's own account of what did not run and what to do;
+ *   evaluated lazily so a populated run pays nothing for it
+ * @returns The one finding, or nothing when at least one thing was checked
+ */
+export function nothingCheckedFinding(denominator, issues, message) {
+    if (denominator > 0)
+        return [];
+    if (issues.some((issue) => issue.code === RUN_INTEGRITY_CODE))
+        return [];
+    return [runIntegrityFinding(message())];
+}
+//# sourceMappingURL=run-integrity.js.map

package/dist/utils/run-integrity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-integrity.js","sourceRoot":"","sources":["../../src/utils/run-integrity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAIH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAAmB,EACnB,MAAkC,EAClC,OAAqB;IAErB,IAAI,WAAW,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAC/B,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,kBAAkB,CAAC;QAAE,OAAO,EAAE,CAAC;IACzE,OAAO,CAAC,mBAAmB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AAC1C,CAAC"}

package/dist/utils/sqlite-experimental-warning.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Filter for the one `ExperimentalWarning` `node:sqlite` emits at load.
+ *
+ * ## Whose obligation this is, and why it lands here
+ *
+ * `@vibe-agent-toolkit/projection-sqlite` imports `node:sqlite`, which loads
+ * without a flag from Node 22.13.0 — but **unflagged is not silent**: Node
+ * still emits one `ExperimentalWarning` per process. That package deliberately
+ * does not suppress it, and says why in its own header: a blanket
+ * `NODE_NO_WARNINGS` would hide real ones. It assigns the work instead —
+ * *"any caller that turns this backend on by default has to filter that one
+ * warning by name at its own boundary."*
+ *
+ * The CLI is that caller. `openEphemeralQueryStore()` is the query lane's
+ * fallback when no store is selected, which is the default, so a user running
+ * `vat resources query` gets the warning on a perfectly ordinary run with no
+ * way to silence it short of silencing everything.
+ *
+ * Measured on Node v24.13.1 against the built CLI, before this filter existed:
+ *
+ * | Command | `ExperimentalWarning`s printed |
+ * |---|---|
+ * | `vat resources query "SELECT …"` | **1** |
+ * | `vat resources check`, no checks declared | **0** |
+ *
+ * ⚠️ That second row corrects a claim in `projection-store.ts`, which says
+ * `node:sqlite` is required "on every default run of those two commands".
+ * True of `query`; too strong for `check`, which never opens a store when the
+ * project declares no checks for it to evaluate. The obligation is real either
+ * way — it just fires on one command rather than two.
+ *
+ * ## Why the predicate is deliberately narrow
+ *
+ * The failure being avoided is not "a warning printed"; it is "a warning
+ * suppressed that someone needed to see". So the match requires BOTH the
+ * `ExperimentalWarning` type and SQLite's own message, and every near miss —
+ * another experimental builtin, a `DeprecationWarning` that mentions SQLite, an
+ * untyped string — is passed straight through. The test suite spends most of
+ * its assertions on what this does *not* swallow, because that is the property
+ * worth defending.
+ *
+ * ⛔ Do not widen this to "any ExperimentalWarning". The next experimental
+ * builtin VAT starts loading is one a maintainer should be told about.
+ */
+/**
+ * Does this warning look like the `node:sqlite` load warning, and nothing else?
+ *
+ * @param warning - The warning value `process.emitWarning` was called with
+ * @param type - The `type` argument, when the caller passed a bare string
+ * @returns `true` only for SQLite's experimental-load warning
+ */
+export declare function isSqliteExperimentalWarning(warning: unknown, type?: unknown): boolean;
+/** Restores the emitter this filter replaced. */
+export type RestoreWarningEmitter = () => void;
+/**
+ * Wrap `process.emitWarning` so SQLite's load warning is dropped and every
+ * other warning is emitted unchanged.
+ *
+ * Patching the emitter is what makes this filter *by name*. The alternatives
+ * are both worse: `NODE_NO_WARNINGS` is global and hides real warnings, and
+ * replacing the `'warning'` listener means re-implementing Node's default
+ * formatting, which then drifts from it silently.
+ *
+ * @param host - The process-like object to patch; injected so the behaviour is
+ *   testable without mutating the real process
+ * @returns A function restoring the previous emitter
+ */
+export declare function installSqliteWarningFilter(host?: Pick<NodeJS.Process, 'emitWarning'>): RestoreWarningEmitter;
+//# sourceMappingURL=sqlite-experimental-warning.d.ts.map

package/dist/utils/sqlite-experimental-warning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-experimental-warning.d.ts","sourceRoot":"","sources":["../../src/utils/sqlite-experimental-warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAQH;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAOrF;AAED,iDAAiD;AACjD,MAAM,MAAM,qBAAqB,GAAG,MAAM,IAAI,CAAC;AAwC/C;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,GAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAW,GAClD,qBAAqB,CAwBvB"}

package/dist/utils/sqlite-experimental-warning.js

@@ -0,0 +1,144 @@
+/**
+ * Filter for the one `ExperimentalWarning` `node:sqlite` emits at load.
+ *
+ * ## Whose obligation this is, and why it lands here
+ *
+ * `@vibe-agent-toolkit/projection-sqlite` imports `node:sqlite`, which loads
+ * without a flag from Node 22.13.0 — but **unflagged is not silent**: Node
+ * still emits one `ExperimentalWarning` per process. That package deliberately
+ * does not suppress it, and says why in its own header: a blanket
+ * `NODE_NO_WARNINGS` would hide real ones. It assigns the work instead —
+ * *"any caller that turns this backend on by default has to filter that one
+ * warning by name at its own boundary."*
+ *
+ * The CLI is that caller. `openEphemeralQueryStore()` is the query lane's
+ * fallback when no store is selected, which is the default, so a user running
+ * `vat resources query` gets the warning on a perfectly ordinary run with no
+ * way to silence it short of silencing everything.
+ *
+ * Measured on Node v24.13.1 against the built CLI, before this filter existed:
+ *
+ * | Command | `ExperimentalWarning`s printed |
+ * |---|---|
+ * | `vat resources query "SELECT …"` | **1** |
+ * | `vat resources check`, no checks declared | **0** |
+ *
+ * ⚠️ That second row corrects a claim in `projection-store.ts`, which says
+ * `node:sqlite` is required "on every default run of those two commands".
+ * True of `query`; too strong for `check`, which never opens a store when the
+ * project declares no checks for it to evaluate. The obligation is real either
+ * way — it just fires on one command rather than two.
+ *
+ * ## Why the predicate is deliberately narrow
+ *
+ * The failure being avoided is not "a warning printed"; it is "a warning
+ * suppressed that someone needed to see". So the match requires BOTH the
+ * `ExperimentalWarning` type and SQLite's own message, and every near miss —
+ * another experimental builtin, a `DeprecationWarning` that mentions SQLite, an
+ * untyped string — is passed straight through. The test suite spends most of
+ * its assertions on what this does *not* swallow, because that is the property
+ * worth defending.
+ *
+ * ⛔ Do not widen this to "any ExperimentalWarning". The next experimental
+ * builtin VAT starts loading is one a maintainer should be told about.
+ */
+/** Node's own text for the SQLite warning, matched as a substring. */
+const SQLITE_WARNING_FRAGMENT = 'SQLite is an experimental feature';
+/** The warning type Node tags it with. */
+const EXPERIMENTAL_WARNING_NAME = 'ExperimentalWarning';
+/**
+ * Does this warning look like the `node:sqlite` load warning, and nothing else?
+ *
+ * @param warning - The warning value `process.emitWarning` was called with
+ * @param type - The `type` argument, when the caller passed a bare string
+ * @returns `true` only for SQLite's experimental-load warning
+ */
+export function isSqliteExperimentalWarning(warning, type) {
+    const isError = warning instanceof Error;
+    const name = isError ? warning.name : type;
+    if (name !== EXPERIMENTAL_WARNING_NAME)
+        return false;
+    const message = isError ? warning.message : warning;
+    return typeof message === 'string' && message.includes(SQLITE_WARNING_FRAGMENT);
+}
+/** Marks a function as one of this module's filters, so a chain can be walked. */
+const FILTER_BRAND = Symbol('sqliteWarningFilter');
+/** Is this one of our filters, rather than the host's own emitter? */
+function isFilterEmitter(value) {
+    return typeof value === 'function' && FILTER_BRAND in value;
+}
+/**
+ * Wrap `process.emitWarning` so SQLite's load warning is dropped and every
+ * other warning is emitted unchanged.
+ *
+ * Patching the emitter is what makes this filter *by name*. The alternatives
+ * are both worse: `NODE_NO_WARNINGS` is global and hides real warnings, and
+ * replacing the `'warning'` listener means re-implementing Node's default
+ * formatting, which then drifts from it silently.
+ *
+ * @param host - The process-like object to patch; injected so the behaviour is
+ *   testable without mutating the real process
+ * @returns A function restoring the previous emitter
+ */
+export function installSqliteWarningFilter(host = process) {
+    const filtered = ((...args) => {
+        if (!filtered.retired && isSqliteExperimentalWarning(args[0], args[1]))
+            return;
+        // Read through the node, not through a captured local: `previous` is
+        // rewritten when a filter below this one is spliced out.
+        Reflect.apply(filtered.previous, host, args);
+    });
+    // Stored UNBOUND so chain identity survives — a `.bind()` here would make each
+    // filter delegate to a fresh wrapper, and no restore could then recognise the
+    // node it needs to splice out.
+    filtered.previous = host.emitWarning;
+    filtered.retired = false;
+    Object.defineProperty(filtered, FILTER_BRAND, { value: true });
+    host.emitWarning = filtered;
+    return () => {
+        // Retire FIRST, and unconditionally. Splicing is the tidy outcome; ceasing
+        // to filter is the one the caller actually asked for, and it is the only one
+        // that can always be delivered.
+        filtered.retired = true;
+        removeFromChain(host, filtered);
+    };
+}
+/**
+ * Take one filter out of the emitter chain, wherever it currently sits.
+ *
+ * Doing nothing when the filter is already gone is the correct answer, not a
+ * swallowed failure: a second `restore()` call, or a host whose emitter was
+ * replaced wholesale by something else, both mean this filter is no longer
+ * reached at all — which is exactly what the caller asked for.
+ *
+ * ⚠️ **There is a third case, and it is NOT covered here.** The walk can only
+ * step through nodes carrying {@link FILTER_BRAND}, so any *delegating* wrapper
+ * installed above us — an APM shim, another library's warning filter, an
+ * unrestored spy — ends the walk with our node still in the chain. That is not
+ * an oversight that can be fixed: the foreign wrapper holds its link to the
+ * emitter beneath it in a closure, and nothing outside it can rewrite that link.
+ * Splicing through it is genuinely impossible, not merely unimplemented.
+ *
+ * So the leak is closed at the other end: `restore()` sets `retired` before
+ * calling this, and a retired node forwards everything. The chain may keep a
+ * dead link in it — harmless — but no unreachable filter goes on eating the
+ * warning it was installed to hide, which was the real defect (a
+ * `vat resources query` run under an APM agent would have lost SQLite's
+ * experimental warning permanently, with no way to get it back short of
+ * restarting the process).
+ */
+function removeFromChain(host, filter) {
+    if (host.emitWarning === filter) {
+        host.emitWarning = filter.previous;
+        return;
+    }
+    let node = host.emitWarning;
+    while (isFilterEmitter(node)) {
+        if (node.previous === filter) {
+            node.previous = filter.previous;
+            return;
+        }
+        node = node.previous;
+    }
+}
+//# sourceMappingURL=sqlite-experimental-warning.js.map

package/dist/utils/sqlite-experimental-warning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-experimental-warning.js","sourceRoot":"","sources":["../../src/utils/sqlite-experimental-warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,sEAAsE;AACtE,MAAM,uBAAuB,GAAG,mCAAmC,CAAC;AAEpE,0CAA0C;AAC1C,MAAM,yBAAyB,GAAG,qBAAqB,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAgB,EAAE,IAAc;IAC1E,MAAM,OAAO,GAAG,OAAO,YAAY,KAAK,CAAC;IACzC,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3C,IAAI,IAAI,KAAK,yBAAyB;QAAE,OAAO,KAAK,CAAC;IAErD,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACpD,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAAC;AAClF,CAAC;AAQD,kFAAkF;AAClF,MAAM,YAAY,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AA6BnD,sEAAsE;AACtE,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,UAAU,IAAI,YAAY,IAAI,KAAK,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAA4C,OAAO;IAEnD,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,IAAe,EAAQ,EAAE;QAC7C,IAAI,CAAC,QAAQ,CAAC,OAAO,IAAI,2BAA2B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO;QAC/E,qEAAqE;QACrE,yDAAyD;QACzD,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/C,CAAC,CAAkB,CAAC;IAEpB,+EAA+E;IAC/E,8EAA8E;IAC9E,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC,WAA0B,CAAC;IACpD,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC;IACzB,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/D,IAAI,CAAC,WAAW,GAAG,QAAoD,CAAC;IAExE,OAAO,GAAG,EAAE;QACV,2EAA2E;QAC3E,6EAA6E;QAC7E,gCAAgC;QAChC,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;QACxB,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAS,eAAe,CAAC,IAAyC,EAAE,MAAqB;IACvF,IAAK,IAAI,CAAC,WAAuB,KAAK,MAAM,EAAE,CAAC;QAC7C,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,QAAyC,CAAC;QACpE,OAAO;IACT,CAAC;IAED,IAAI,IAAI,GAAY,IAAI,CAAC,WAAW,CAAC;IACrC,OAAO,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,QAAQ,KAAM,MAAiC,EAAE,CAAC;YACzD,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;YAChC,OAAO;QACT,CAAC;QACD,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/utils/user-context-scanner.d.ts

@@ -4,6 +4,7 @@
  * Scan user-level Claude directories for plugins, skills, and marketplaces.
  */
 import { type ScanResult } from '@vibe-agent-toolkit/discovery';
+import type { DirectoryRefusal } from '@vibe-agent-toolkit/utils/crawl';
 /**
  * Scan user-level Claude directories for skills and plugins
  *
@@ -27,5 +28,12 @@ export declare function scanUserContext(): Promise<{
     plugins: ScanResult[];
     skills: ScanResult[];
     marketplaces: ScanResult[];
+    /**
+     * Directories under either tree that could not be listed — carried through
+     * from `ScanSummary.unreadable`, because a `~/.claude/plugins` with one
+     * root-owned directory is ordinary and every caller must say what it could
+     * not see rather than list fewer skills.
+     */
+    unreadable: DirectoryRefusal[];
 }>;
 //# sourceMappingURL=user-context-scanner.d.ts.map

package/dist/utils/user-context-scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user-context-scanner.d.ts","sourceRoot":"","sources":["../../src/utils/user-context-scanner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAGtE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC;IAC/C,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,YAAY,EAAE,UAAU,EAAE,CAAC;CAC5B,CAAC,CAmCD"}
+{"version":3,"file":"user-context-scanner.d.ts","sourceRoot":"","sources":["../../src/utils/user-context-scanner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAGxE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC;IAC/C,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAChC,CAAC,CAuCD"}

package/dist/utils/user-context-scanner.js

@@ -27,6 +27,7 @@ import { scan } from '@vibe-agent-toolkit/discovery';
  */
 export async function scanUserContext() {
     const { pluginsDir, skillsDir } = getClaudeUserPaths();
+    const unreadable = [];
     // Scan plugins directory (SKILL.md and .claude-plugin directories)
     let plugins = [];
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- User's home directory is safe
@@ -37,6 +38,7 @@ export async function scanUserContext() {
             include: ['**/SKILL.md', '**/.claude-plugin/**'],
         });
         plugins = pluginsScan.results;
+        unreadable.push(...pluginsScan.unreadable);
     }
     // Scan skills directory (SKILL.md files)
     let skills = [];
@@ -48,6 +50,7 @@ export async function scanUserContext() {
             include: ['**/SKILL.md'],
         });
         skills = skillsScan.results;
+        unreadable.push(...skillsScan.unreadable);
     }
     // Marketplaces reserved for future use
     const marketplaces = [];
@@ -55,6 +58,7 @@ export async function scanUserContext() {
         plugins,
         skills,
         marketplaces,
+        unreadable,
     };
 }
 //# sourceMappingURL=user-context-scanner.js.map

package/dist/utils/user-context-scanner.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-context-scanner.js","sourceRoot":"","sources":["../../src/utils/user-context-scanner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,IAAI,EAAmB,MAAM,+BAA+B,CAAC;AAGtE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IAKnC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,kBAAkB,EAAE,CAAC;IAEvD,mEAAmE;IACnE,IAAI,OAAO,GAAiB,EAAE,CAAC;IAC/B,oGAAoG;IACpG,IAAI,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3B,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;YAC7B,IAAI,EAAE,UAAU;YAChB,SAAS,EAAE,IAAI;YACf,OAAO,EAAE,CAAC,aAAa,EAAE,sBAAsB,CAAC;SACjD,CAAC,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC;IAChC,CAAC;IAED,yCAAyC;IACzC,IAAI,MAAM,GAAiB,EAAE,CAAC;IAC9B,oGAAoG;IACpG,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC;YAC5B,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,IAAI;YACf,OAAO,EAAE,CAAC,aAAa,CAAC;SACzB,CAAC,CAAC;QACH,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC;IAC9B,CAAC;IAED,uCAAuC;IACvC,MAAM,YAAY,GAAiB,EAAE,CAAC;IAEtC,OAAO;QACL,OAAO;QACP,MAAM;QACN,YAAY;KACb,CAAC;AACJ,CAAC"}
+{"version":3,"file":"user-context-scanner.js","sourceRoot":"","sources":["../../src/utils/user-context-scanner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,IAAI,EAAmB,MAAM,+BAA+B,CAAC;AAItE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IAYnC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,kBAAkB,EAAE,CAAC;IACvD,MAAM,UAAU,GAAuB,EAAE,CAAC;IAE1C,mEAAmE;IACnE,IAAI,OAAO,GAAiB,EAAE,CAAC;IAC/B,oGAAoG;IACpG,IAAI,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3B,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;YAC7B,IAAI,EAAE,UAAU;YAChB,SAAS,EAAE,IAAI;YACf,OAAO,EAAE,CAAC,aAAa,EAAE,sBAAsB,CAAC;SACjD,CAAC,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC;QAC9B,UAAU,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IAC7C,CAAC;IAED,yCAAyC;IACzC,IAAI,MAAM,GAAiB,EAAE,CAAC;IAC9B,oGAAoG;IACpG,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC;YAC5B,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,IAAI;YACf,OAAO,EAAE,CAAC,aAAa,CAAC;SACzB,CAAC,CAAC;QACH,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC;QAC5B,UAAU,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IAC5C,CAAC;IAED,uCAAuC;IACvC,MAAM,YAAY,GAAiB,EAAE,CAAC;IAEtC,OAAO;QACL,OAAO;QACP,MAAM;QACN,YAAY;QACZ,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/utils/validate-help-files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-help-files.d.ts","sourceRoot":"","sources":["../../src/utils/validate-help-files.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA0CH;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAkDxC"}
+{"version":3,"file":"validate-help-files.d.ts","sourceRoot":"","sources":["../../src/utils/validate-help-files.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2CH;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAkDxC"}

package/dist/utils/validate-help-files.js

@@ -7,8 +7,9 @@
  */
 import { existsSync, readdirSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { safePath } from '@vibe-agent-toolkit/utils';
+import { isEntrypoint } from '@vibe-agent-toolkit/utils/process';
 /**
  * Files `loadVerboseHelp()` is actually asked for by a command.
  *
@@ -89,8 +90,14 @@ export function validateHelpFiles() {
 /**
  * Run validation if this file is executed directly
  * (via tsx or node during build process)
+ *
+ * ⛔ NOT `import.meta.url === pathToFileURL(process.argv[1]).href`, which is what
+ * this used to be. That compare has no realpath pass, so it is false whenever
+ * the build reaches this script through a symlink — and a build-time validator
+ * whose guard is false does not fail the build, it exits 0 having validated
+ * nothing, which is the exact opposite of the "fail fast" this file exists for.
  */
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isEntrypoint(import.meta.url)) {
     try {
         validateHelpFiles();
         console.log('✓ All required help documentation files exist');

package/dist/utils/validate-help-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-help-files.js","sourceRoot":"","sources":["../../src/utils/validate-help-files.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validate-help-files.js","sourceRoot":"","sources":["../../src/utils/validate-help-files.ts"],"names":[],"mappings":"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"}

package/docs/audit.md

@@ -29,6 +29,8 @@ vat audit [git-url-or-path] [options]
 
 - `--user` - Audit user-level Claude plugins installation (`~/.claude/plugins`)
 - `-r, --recursive` - Scan directories recursively for all resource types
+- `--compat` - Run compatibility analysis for each plugin; adds a `compatibility:` block to its entry (see [Compatibility and settings blocks](#compatibility-and-settings-blocks))
+- `--settings [file]` - Check each plugin against Claude settings (auto-discovered, or the given file); adds a `settings:` block. Requires `--compat`
 - `--debug` - Enable debug logging (outputs to stderr)
 
 ### Gitignore-aware scanning
@@ -205,25 +207,68 @@ hierarchical:
                   message: Skill exceeds recommended length
 ```
 
+## Two verdicts: `status` and the exit code
+
+`vat audit` publishes two verdicts, and they answer different questions.
+
+| Verdict | Answers | Where to read it |
+|---|---|---|
+| `status` in the YAML report | **What was found** — the worst actionable severity across the findings | stdout |
+| The process exit code | **Whether the run completed** | `$?` |
+
+So a tree with errors produces `status: error` beside **exit 0**, and both are
+correct. That pair surprises people because `status` means something wider
+everywhere else in this CLI, where it moves with the exit code. Here it does not,
+because this command is a report rather than a gate.
+
+A run that audited **zero files** is refused, not passed. An existing directory
+with nothing auditable in it — plugins that moved, a wrong subdirectory, an
+excluded tree, files no lane recognises — used to publish `status: success`
+beside `filesScanned: 0`, which is the same document a clean tree produces. It
+now publishes `status: error` with one non-overridable `RESOURCE_CHECK_BROKEN`
+finding under a top-level `issues:` key (the claim is about the run, so it is
+not a `files[]` row and does not count toward `filesScanned`). The exit code is
+still `0`: the run completed; it just is not a verdict.
+
+**Gate CI on the report, never on this command's exit code** — read `status` and
+`issueCounts` out of the YAML (see [CI/CD Integration](#cicd-integration) for a
+worked example), or reach for a command whose exit code *is* the verdict:
+`vat skills validate` and `vat skills build` exit `1` on validation errors, and
+`vat skills validate` also exits `1` when its `skills.include` globs discover no
+skill — so a typo'd glob fails the gate there instead of passing it.
+
 ## Exit Codes
 
 `vat audit` is **advisory by design** — it reports every issue it detects but does not block on validation severity. Use `vat skills validate` or `vat skills build` for gated checks (those commands exit `1` on validation errors).
 
-- **0** - Always, when the audit completes. The report may still contain errors and warnings; check `status` and `summary` in the YAML output to decide whether action is needed.
-- **2** - System error: Config invalid, path not found, permission denied, etc. The audit could not run.
+- **0** - Always, when the audit completes — including when the report says `status: error`. The findings are in the report; check `status` and `summary` in the YAML output to decide whether action is needed. That includes the environment refusing part of the subject: a path that does not exist or is not a recognisable resource is reported as `UNKNOWN_FORMAT` (error), and a directory or file the scan could not read — permission denied, a vanished mount — as `SCAN_PATH_UNREADABLE` (warning), with every readable sibling still validated. A governing `vibe-agent-toolkit.config.yaml` that cannot be loaded, or whose `skills.include` reaches a directory the crawl cannot list, is warned about once on stderr and filed as `SCAN_PATH_UNREADABLE` on the config file or the directory; the skills it governs are validated config-free rather than dropped. Degrading beats destroying, and the report says where it degraded.
+- **2** - The audit could not run at all, so there is no report to read: `--user` with no Claude config directory installed, a git URL that could not be cloned, or an internal failure (a validator defect). Invalid config, missing paths and permission problems are **not** exit 2 — they are findings, above.
 
 ## Validation Configuration
 
-Audit honors `validation.severity` from `vibe-agent-toolkit.config.yaml` for **display grouping only** — setting a code to `ignore` hides it from output, raising to `error` promotes it in the report's error count. Audit does **not** apply `validation.allow` (per-path allow entries); for that, use `vat skills validate` or `vat skills build`.
+Audit honors `validation.severity` from `vibe-agent-toolkit.config.yaml`: setting a code to `ignore` hides it from the report, and every other level is applied as written — a code raised to `error` is reported as an error, a code lowered to `warning` as a warning. It changes **which findings are reported and at what severity**, never whether the command fails (see [Two verdicts](#two-verdicts-status-and-the-exit-code)). Audit does **not** apply `validation.allow` (per-path allow entries); for that, use `vat skills validate` or `vat skills build`.
+
+Three scopes are read, least specific first — a more specific one naming the same code wins:
 
 ```yaml
 # In vibe-agent-toolkit.config.yaml
+resources:
+  validation:
+    severity:
+      LINK_MISSING_TARGET: ignore       # project-wide; the same dial
+                                        # `vat resources validate` reads
 skills:
   defaults:
     validation:
       severity:
-        LINK_TO_NAVIGATION_FILE: ignore   # hidden from audit output
-        LINK_DROPPED_BY_DEPTH: error      # elevated in the report
+        LINK_TO_NAVIGATION_FILE: ignore # project-wide: skills, plugins and
+                                        # marketplaces alike
+        LINK_DROPPED_BY_DEPTH: error    # elevated in the report
+  config:
+    my-skill:
+      validation:
+        severity:
+          LINK_DROPPED_BY_DEPTH: info   # just this skill
 ```
 
 See `docs/validation-codes.md` for the full code reference.
@@ -321,9 +366,13 @@ summary:
   filesWithWarnings: number   # Files whose worst actionable severity is warning
   filesWithErrors: number     # Files carrying at least one error
 issueCounts:                  # FINDINGS, not files — same field name and meaning
-  errors: number              #   as the `issueCounts` on each entry below
-  warnings: number
+  errors: number              #   as the `issueCounts` on each entry below,
+  warnings: number            #   plus the run-level `issues` when present
   info: number
+issues:                       # Only when the RUN itself is refused — a run over
+  - code: RESOURCE_CHECK_BROKEN   # zero files. Not a file, so not in `files[]`.
+    severity: error
+    message: ...
 duration: "123ms"
 files:
   - path: plugins/my-plugin            # relative to `root`
@@ -357,6 +406,70 @@ say in how a path is spelled.
 lives in a random tempdir that nothing downstream can resolve, so the provenance
 header states the base instead and paths are relative to the cloned repo.
 
+#### Compatibility and settings blocks
+
+Under `--compat`, every `claude-plugin` entry carries a `compatibility:` block;
+under `--compat --settings`, a `settings:` block beside it. **Both blocks are
+always present for every plugin the run was asked about** — a lane that could
+not run says so in its block rather than leaving it out, because a plugin the
+check could not answer for must never look like one the operator never asked
+about.
+
+```yaml
+files:
+  - path: plugins/my-plugin
+    type: claude-plugin
+    compatibility:               # the analyzer's verdicts…
+      plugin: my-plugin
+      declaredTargets: [claude-code]
+      observations: [...]
+      verdicts: [...]
+      unchecked: []              # files the analysis could not read; verdicts were computed without them
+    settings:
+      compatible: false          # true ONLY when conflicts and unchecked are both empty
+      conflicts:
+        - type: tool-blocked
+          detail: Tool "Bash" in skills/deploy/SKILL.md blocked by org policy (permissions.deny)
+          blockedBy: permissions.deny
+          value: Bash
+          settingsFile: /etc/claude-code/managed-settings.json
+          settingsLevel: managed
+      unchecked:                 # present only when non-empty
+        - path: skills/locked/SKILL.md           # relative to `root`
+          reason: "EACCES: permission denied, open 'skills/locked/SKILL.md'"
+  - path: plugins/other-plugin
+    type: claude-plugin
+    compatibility:               # …or the reason there are none
+      analyzed: false
+      reason: "EACCES: permission denied, scandir 'plugins/other-plugin/skills/locked'"
+    settings:
+      compatible: false
+      conflicts: []
+      unchecked:
+        - path: plugins/other-plugin/skills/locked
+          reason: "EACCES: permission denied, scandir 'plugins/other-plugin/skills/locked'"
+```
+
+`settings.unchecked` lists every path the settings check enumerated but could
+not compare: a `SKILL.md` it could not read or whose frontmatter is not a YAML
+mapping (the same file the validator reports as `SKILL_MISSING_FRONTMATTER`), or
+a directory it could not list — in which case any skill beneath it is unseen
+and unnamed. The check follows symlinks the way the validator lane does, so a
+plugin whose `skills/` points at a shared tree is checked, not skipped.
+`compatible` is `false` whenever anything is listed here: zero conflicts over a
+skill that was never read is not compatibility. The two compat lanes are
+independent — a plugin-wide analyzer failure (no valid `plugin.json`, or a root
+that cannot be listed) does not stop the settings check. A single file the
+analyzer cannot read, list or parse is listed under `compatibility.unchecked`
+(root-relative, with the OS or parser reason) and every other file is still
+analyzed; the verdicts are computed WITHOUT the unchecked files, so an empty
+`verdicts` beside a non-empty `unchecked` is a verdict over fewer files than
+the plugin ships.
+
+Both outcomes are also said on stderr without `--debug`: a
+`Compatibility analysis could not run for <plugin>: <reason>` line, and totals
+for conflicts found and paths the settings check could not compare.
+
 ### Standard Error (stderr)
 
 Human-readable error messages and logs. Paths are root-relative here too: