@vibe-agent-toolkit/cli 0.2.0-rc.2 → 0.2.0-rc.4

package/dist/commands/build.js

@@ -7,8 +7,8 @@
  */
 import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
-import { calculateValidationStatus, countBySeverity, } from '@vibe-agent-toolkit/agent-schema';
 import { checkBrokenPackagedLinks } from '@vibe-agent-toolkit/agent-skills';
+import { calculateValidationStatus, countBySeverity, } from '@vibe-agent-toolkit/schema';
 import { safePath } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
 import { handleCommandError } from '../utils/command-error.js';
@@ -16,8 +16,10 @@ import { loadConfig } from '../utils/config-loader.js';
 import { sumSeverityCounts } from '../utils/issue-rendering.js';
 import { writeYamlOutput } from '../utils/output.js';
 import { requireProjectRoot } from '../utils/project-root-policy.js';
+import { runClaudePluginBuildPhase } from './claude/plugin/build.js';
 import { aggregatePhaseIssueCounts, aggregatePhaseStatus, applyPhaseSelection, createPhaseContext, decidePhaseSelection, exitCodeForPhases, runPhase, SYSTEM_ERROR, worseOf, } from './phase-utils.js';
 import { rejectPositionalArguments } from './positional-args.js';
+import { runSkillsBuildPhase } from './skills/build.js';
 export function createBuildTopLevelCommand() {
     const command = new Command('build');
     command
@@ -65,9 +67,8 @@ Exit Codes:
   0 - All phases completed successfully (warnings do not fail a build)
   1 - Build error, or '--only' named a phase that is unrecognized or unconfigured
   2 - System error (this command's own, a usage error such as a positional
-      argument, or propagated from a phase that could not run: exited 2, was
-      killed by a signal, was never spawned, or wrote output that could not be
-      parsed)
+      argument, or propagated from a phase that could not run: it exited 2, or
+      reported 'system-error' for itself)
 
 Requirements:
   projectRoot: required (errors if no vibe-agent-toolkit.config.yaml or .git/ ancestor)
@@ -188,15 +189,14 @@ const BUILD_VOCABULARY = {
  */
 export function selectBuildPhases(only, hasClaudeMarketplaces, verbose = false) {
     const phases = [];
-    // Each phase is a separate spawned process, so a flag not forwarded here is a
-    // flag the composite command silently cannot express: `vat build` would always
-    // get the collapsed report with no way to ask for the full one.
-    const verboseArgs = verbose ? ['--verbose'] : [];
+    // A flag not forwarded here is a flag the composite command silently cannot
+    // express: `vat build` would always get the collapsed report with no way to
+    // ask for the full one.
     if (!only || only === 'skills') {
-        phases.push({ name: 'skills', args: ['skills', 'build', ...verboseArgs] });
+        phases.push({ name: 'skills', run: () => runSkillsBuildPhase(undefined, { verbose }) });
     }
     if ((!only || only === 'claude') && hasClaudeMarketplaces) {
-        phases.push({ name: 'claude', args: ['claude', 'plugin', 'build', ...verboseArgs] });
+        phases.push({ name: 'claude', run: () => runClaudePluginBuildPhase({ verbose }) });
     }
     return decidePhaseSelection(only, phases, BUILD_VOCABULARY);
 }
@@ -209,7 +209,7 @@ async function buildTopLevelCommand(options, command) {
     const cwd = process.cwd();
     // Spec §7: `vat build` requires a projectRoot.
     requireProjectRoot(cwd, 'vat build');
-    const { logger, startTime, binPath } = createPhaseContext(options.debug);
+    const { logger, startTime } = createPhaseContext(options.debug);
     try {
         // Inside the try, deliberately: this used to throw from outside it, so an
         // unroutable `--only` produced a raw stack trace and zero bytes of stdout.
@@ -223,7 +223,10 @@ async function buildTopLevelCommand(options, command) {
         let shippedLinkIssues = [];
         for (const phase of phases) {
             logger.info(`\n▶ Phase: ${phase.name}`);
-            const result = runPhase(binPath, phase);
+            // Awaited in the loop, deliberately, and here it is a DEPENDENCY rather
+            // than a presentation choice: `claude` packages what `skills` just wrote
+            // into dist/, so overlapping the two would read a half-built tree.
+            const result = await runPhase(phase);
             phaseResults.push(result);
             // Only a real failure stops the build. A `warning` phase must NOT abort:
             // warnings are non-blocking everywhere else in VAT, and phase status only

package/dist/commands/build.js.map

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

package/dist/commands/cache/cache-control.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The root-level `--no-cache` control surface, kept apart from the `cache`
+ * command itself.
+ *
+ * `bin.ts` must call {@link registerCacheControl} on every single invocation,
+ * before parsing. Co-locating it with `createCacheCommand` in `index.ts` meant
+ * that unavoidable call dragged in `./clear.js` and, behind it, the whole
+ * resources package — measured at ~1.2s of module load on Windows, paid even by
+ * `vat --version`. This module imports nothing but commander, so the always-on
+ * path stays cheap — keep it that way: any import added here is paid by every
+ * `vat` invocation, and `index.ts` deliberately does not re-export it, so
+ * reaching these functions through the command group cannot happen by accident.
+ */
+import type { Command } from 'commander';
+/**
+ * Root options this module reads. Commander represents `--no-cache` as the
+ * POSITIVE key `cache` — `true` by default, `false` only when the negated flag
+ * is passed. It NEVER produces `noCache`; reading that key is the exact bug that
+ * made three flags in this package silent no-ops (see
+ * `test/commands/commander-option-keys.test.ts`).
+ */
+export interface CacheControlOptions {
+    cache?: boolean;
+}
+/**
+ * Register the root-level `--no-cache` flag and the hook that gives it effect.
+ *
+ * ## Why this sets an environment variable instead of plumbing a flag
+ *
+ * ⚠️ The ORIGINAL reason has expired, and saying so is the point of this note.
+ * It was that `vat validate` / `vat verify` / `vat build` enumerated nothing in
+ * their own process — each `spawnSync`ed the vat binary once per phase, so a
+ * flag parsed in the parent never reached the process doing the parsing, while
+ * `process.env` crossed the boundary for free. Phases run in this process now,
+ * so that argument no longer holds.
+ *
+ * What still holds is narrower but sufficient: the flag has to reach code that
+ * no CLI option is threaded through. `ParseCache` is constructed deep inside
+ * `@vibe-agent-toolkit/resources`, by callers several layers below any command,
+ * and `bin.ts` leans on the same mechanism for `VAT_CONTEXT` /
+ * `VAT_CONTEXT_PATH`. Plumbing a `noCache` parameter down every one of those
+ * call chains is the alternative, and it is a real one — this is now a choice
+ * rather than a necessity, so treat it as revisitable rather than as settled.
+ *
+ * `VAT_CACHE=0` is read by `ParseCache` (packages/resources/src/parse-cache.ts)
+ * per construction, never at module load, so setting it from a `preAction` hook
+ * — after Commander has parsed, before any command body runs — is observed by
+ * every phase, all of which now start after that hook has run.
+ *
+ * ## The collision with `vat resources validate --no-cache`
+ *
+ * This root program does NOT use `enablePositionalOptions()`, so Commander scans
+ * the WHOLE argv for root options, including everything after the subcommand
+ * name. That is the same mechanism that let a root `-v` shadow the subcommands'
+ * own `-v, --verbose` (see the incident recorded in `bin.ts`). Measured against
+ * commander 12: `vat resources validate docs --no-cache` leaves the ROOT with
+ * `cache: false` and the SUBCOMMAND with `cache: true` — the subcommand's
+ * identically-named flag is swallowed before it ever sees it, which would have
+ * silently re-enabled the external-URL cache the flag exists to bypass.
+ *
+ * Rather than break a shipped flag, the hook hands the value back down to
+ * whichever action command declares a `cache` option of its own. `--no-cache` is
+ * a superset — every cache off — so the handoff is a strengthening, never a
+ * reversal.
+ *
+ * @param program - The root program to register the flag and hook on
+ */
+export declare function registerCacheControl(program: Command): void;
+/**
+ * Apply the root `--no-cache` decision: export it to child processes, and hand
+ * it down to an action command that declares its own `cache` option.
+ *
+ * Exported so a test can drive it from real parsed options rather than from a
+ * hand-built bag. Deliberately does nothing when the flag was not passed — a
+ * toggle that writes `VAT_CACHE=1` by default would be indistinguishable from
+ * one that is always on.
+ *
+ * @param rootOptions - Options bag from the ROOT program
+ * @param actionCommand - The command whose action is about to run
+ */
+export declare function applyCacheControl(rootOptions: CacheControlOptions, actionCommand: Command): void;
+//# sourceMappingURL=cache-control.d.ts.map

package/dist/commands/cache/cache-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-control.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/cache-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAM3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,OAAO,GAAG,IAAI,CAWhG"}

package/dist/commands/cache/cache-control.js

@@ -0,0 +1,86 @@
+/**
+ * The root-level `--no-cache` control surface, kept apart from the `cache`
+ * command itself.
+ *
+ * `bin.ts` must call {@link registerCacheControl} on every single invocation,
+ * before parsing. Co-locating it with `createCacheCommand` in `index.ts` meant
+ * that unavoidable call dragged in `./clear.js` and, behind it, the whole
+ * resources package — measured at ~1.2s of module load on Windows, paid even by
+ * `vat --version`. This module imports nothing but commander, so the always-on
+ * path stays cheap — keep it that way: any import added here is paid by every
+ * `vat` invocation, and `index.ts` deliberately does not re-export it, so
+ * reaching these functions through the command group cannot happen by accident.
+ */
+/**
+ * Register the root-level `--no-cache` flag and the hook that gives it effect.
+ *
+ * ## Why this sets an environment variable instead of plumbing a flag
+ *
+ * ⚠️ The ORIGINAL reason has expired, and saying so is the point of this note.
+ * It was that `vat validate` / `vat verify` / `vat build` enumerated nothing in
+ * their own process — each `spawnSync`ed the vat binary once per phase, so a
+ * flag parsed in the parent never reached the process doing the parsing, while
+ * `process.env` crossed the boundary for free. Phases run in this process now,
+ * so that argument no longer holds.
+ *
+ * What still holds is narrower but sufficient: the flag has to reach code that
+ * no CLI option is threaded through. `ParseCache` is constructed deep inside
+ * `@vibe-agent-toolkit/resources`, by callers several layers below any command,
+ * and `bin.ts` leans on the same mechanism for `VAT_CONTEXT` /
+ * `VAT_CONTEXT_PATH`. Plumbing a `noCache` parameter down every one of those
+ * call chains is the alternative, and it is a real one — this is now a choice
+ * rather than a necessity, so treat it as revisitable rather than as settled.
+ *
+ * `VAT_CACHE=0` is read by `ParseCache` (packages/resources/src/parse-cache.ts)
+ * per construction, never at module load, so setting it from a `preAction` hook
+ * — after Commander has parsed, before any command body runs — is observed by
+ * every phase, all of which now start after that hook has run.
+ *
+ * ## The collision with `vat resources validate --no-cache`
+ *
+ * This root program does NOT use `enablePositionalOptions()`, so Commander scans
+ * the WHOLE argv for root options, including everything after the subcommand
+ * name. That is the same mechanism that let a root `-v` shadow the subcommands'
+ * own `-v, --verbose` (see the incident recorded in `bin.ts`). Measured against
+ * commander 12: `vat resources validate docs --no-cache` leaves the ROOT with
+ * `cache: false` and the SUBCOMMAND with `cache: true` — the subcommand's
+ * identically-named flag is swallowed before it ever sees it, which would have
+ * silently re-enabled the external-URL cache the flag exists to bypass.
+ *
+ * Rather than break a shipped flag, the hook hands the value back down to
+ * whichever action command declares a `cache` option of its own. `--no-cache` is
+ * a superset — every cache off — so the handoff is a strengthening, never a
+ * reversal.
+ *
+ * @param program - The root program to register the flag and hook on
+ */
+export function registerCacheControl(program) {
+    program.option('--no-cache', "Disable VAT's disk caches for this run (every phase included)");
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+        applyCacheControl(program.opts(), actionCommand);
+    });
+}
+/**
+ * Apply the root `--no-cache` decision: export it to child processes, and hand
+ * it down to an action command that declares its own `cache` option.
+ *
+ * Exported so a test can drive it from real parsed options rather than from a
+ * hand-built bag. Deliberately does nothing when the flag was not passed — a
+ * toggle that writes `VAT_CACHE=1` by default would be indistinguishable from
+ * one that is always on.
+ *
+ * @param rootOptions - Options bag from the ROOT program
+ * @param actionCommand - The command whose action is about to run
+ */
+export function applyCacheControl(rootOptions, actionCommand) {
+    if (rootOptions.cache !== false)
+        return;
+    process.env['VAT_CACHE'] = '0';
+    // `attributeName()`, not `name()`: for `--no-cache` the latter returns
+    // 'no-cache', so a check written against it never matches and the handoff
+    // above becomes a no-op that looks like it works.
+    if (actionCommand.options.some((option) => option.attributeName() === 'cache')) {
+        actionCommand.setOptionValue('cache', false);
+    }
+}
+//# sourceMappingURL=cache-control.js.map

package/dist/commands/cache/cache-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-control.js","sourceRoot":"","sources":["../../../src/commands/cache/cache-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,+DAA+D,CAAC,CAAC;IAE9F,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,EAAE;QACxD,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAuB,EAAE,aAAa,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAgC,EAAE,aAAsB;IACxF,IAAI,WAAW,CAAC,KAAK,KAAK,KAAK;QAAE,OAAO;IAExC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC;IAE/B,uEAAuE;IACvE,0EAA0E;IAC1E,kDAAkD;IAClD,IAAI,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,OAAO,CAAC,EAAE,CAAC;QAC/E,aAAa,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC"}

package/dist/commands/cache/clear.d.ts

@@ -13,13 +13,27 @@
 export interface CacheClearOptions {
     debug?: boolean;
 }
-/** What a clear did, as published on stdout. */
+/**
+ * What a clear did, as published on stdout.
+ *
+ * `partial` is not a failure mode bolted on — it is the *common* outcome when
+ * something else on the machine is writing to the shared tree, and it has to be
+ * reportable. A recursive delete that gives up part-way has already removed most
+ * of the cache; surfacing that as a bare thrown error told the operator only
+ * that the command failed, while leaving them to guess how much of their cache
+ * still existed. An honest count of what went and what stayed is the whole
+ * point of a report.
+ */
 export interface CacheClearReport {
-    status: 'success';
+    status: 'success' | 'partial';
     cacheDir: string;
     existed: boolean;
-    /** Top-level entries that were deleted, sorted. Empty when nothing was there. */
+    /** Top-level entries that are gone, sorted. Empty when nothing was there. */
     removed: string[];
+    /** Top-level entries that survived a partial clear, sorted. Absent on success. */
+    remaining?: string[];
+    /** Why the delete stopped short. Absent on success. */
+    reason?: string;
     entriesRemoved: number;
     bytesRemoved: number;
 }

package/dist/commands/cache/clear.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clear.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/clear.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAeH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;CACtB;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAcrC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAkBrF;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYtF"}
+{"version":3,"file":"clear.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/clear.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAeH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;CACtB;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAcrC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwBrF;AA+CD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBtF"}

package/dist/commands/cache/clear.js

@@ -20,6 +20,24 @@ import { writeYamlOutput } from '../../utils/output.js';
 /** The one name the shared cache root is allowed to have. See {@link vatCacheRoot}. */
 const VAT_CACHE_DIR_NAME = '.vat-cache';
 const EMPTY_USAGE = { entries: 0, bytes: 0 };
+/**
+ * Retry budget for the recursive delete.
+ *
+ * Not defensive padding — observed. `<tmpdir>/.vat-cache` is shared by every VAT
+ * on the machine: other worktrees, other sessions, and any adopter running an
+ * *installed* vat all write into it under their own namespace. A `vat cache
+ * clear` issued while one of them is mid-run walks a tree that is growing
+ * underneath it and `rmdir` fails `ENOTEMPTY` on a shard that gained a file
+ * between the listing and the removal. Reproduced twice against a concurrent
+ * `vat verify`; the same command succeeded immediately once that run finished.
+ *
+ * Node retries exactly this error class (`EBUSY`, `EMFILE`, `ENFILE`,
+ * `ENOTEMPTY`, `EPERM`) with a linear backoff, which clears a short overlap.
+ * It cannot win against a writer that keeps going for the whole window — that
+ * case still surfaces as an error, which is correct: "some of your cache is
+ * gone and something is still writing" must not be reported as success.
+ */
+const RM_RETRY = { maxRetries: 5, retryDelay: 100 };
 /**
  * The shared cache root, `<tmpdir>/.vat-cache`.
  *
@@ -80,16 +98,59 @@ export async function clearCacheDirectory(cacheDir) {
         return { status: 'success', cacheDir, existed: false, removed: [], entriesRemoved: 0, bytesRemoved: 0 };
     }
     const usage = await measureEntries(cacheDir, entries);
-    await fs.rm(cacheDir, { recursive: true, force: true });
+    const names = entries.map((entry) => entry.name);
+    try {
+        await fs.rm(cacheDir, { recursive: true, force: true, ...RM_RETRY });
+    }
+    catch (error) {
+        return partialReport(cacheDir, names, usage, error);
+    }
     return {
         status: 'success',
         cacheDir,
         existed: true,
-        removed: entries.map((entry) => entry.name).sort((a, b) => a.localeCompare(b)),
+        removed: sorted(names),
         entriesRemoved: usage.entries,
         bytesRemoved: usage.bytes,
     };
 }
+/**
+ * Describe a delete that stopped part-way, by re-reading the tree.
+ *
+ * The survivors are read back off disk rather than inferred from the error,
+ * because the error names one path and says nothing about the other ninety-nine
+ * percent. Re-measuring what remains and subtracting is the only way the counts
+ * describe what actually happened rather than what was attempted.
+ *
+ * A concurrent writer can make the remainder *larger* than the original
+ * measurement, so the subtraction is floored at zero: reporting a negative
+ * number of removed bytes would be worse than reporting none.
+ *
+ * @param cacheDir - The tree that was being removed
+ * @param names - Top-level entry names as they were before the delete
+ * @param before - Usage measured before the delete
+ * @param error - Whatever `fs.rm` threw
+ * @returns A report naming what went, what stayed, and why
+ */
+async function partialReport(cacheDir, names, before, error) {
+    const survivors = (await readdirOrNull(cacheDir)) ?? [];
+    const remaining = new Set(survivors.map((entry) => entry.name));
+    const after = await measureEntries(cacheDir, survivors);
+    return {
+        status: 'partial',
+        cacheDir,
+        existed: true,
+        removed: sorted(names.filter((name) => !remaining.has(name))),
+        remaining: sorted([...remaining]),
+        reason: error instanceof Error ? error.message : String(error),
+        entriesRemoved: Math.max(0, before.entries - after.entries),
+        bytesRemoved: Math.max(0, before.bytes - after.bytes),
+    };
+}
+/** Stable ordering for the reported entry lists. */
+function sorted(names) {
+    return [...names].sort((left, right) => left.localeCompare(right));
+}
 /**
  * Command entry point: clear the real cache root and publish the report.
  *
@@ -102,7 +163,11 @@ export async function cacheClearCommand(options = {}) {
         const report = await clearCacheDirectory(vatCacheRoot());
         logger.debug(`Cleared ${String(report.entriesRemoved)} cache entries from ${report.cacheDir}`);
         writeYamlOutput(report);
-        process.exit(0);
+        // A partial clear publishes its report and *then* fails. Exiting through
+        // `handleCommandError` instead would suppress the report entirely, which is
+        // the defect this branch exists to fix: the operator most needs to know how
+        // much of the cache survived precisely when the command did not finish.
+        process.exit(report.status === 'partial' ? 1 : 0);
     }
     catch (error) {
         handleCommandError(error, logger, startTime, 'CacheClear');

package/dist/commands/cache/clear.js.map

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

package/dist/commands/cache/index.d.ts

@@ -1,68 +1,18 @@
 /**
- * Cache command group, plus the root-level `--no-cache` control surface.
- *
- * Both live here so the flag and the command that cleans up after it stay in one
- * place: `--no-cache` decides whether this run *writes* to the caches, `vat cache
- * clear` decides whether the caches *survive*.
+ * Cache command group.
+ *
+ * The paired `--no-cache` control surface lives in `./cache-control.js`:
+ * `--no-cache` decides whether this run *writes* to the caches, `vat cache
+ * clear` decides whether the caches *survive*. They are separate modules only
+ * because `bin.ts` registers the flag on every invocation and must not pay for
+ * this command's imports to do it.
+ *
+ * ⛔ Do NOT re-export `cache-control.js` from here for convenience. Importing it
+ * through this module pulls `./clear.js` and the whole resources package behind
+ * it — the exact ~1.2s that splitting the file removed — so a re-export leaves
+ * the expensive path one identical-looking import away, with nothing pinning
+ * the cheap one. Import from `./cache-control.js` directly.
  */
 import { Command } from 'commander';
-/**
- * Root options this module reads. Commander represents `--no-cache` as the
- * POSITIVE key `cache` — `true` by default, `false` only when the negated flag
- * is passed. It NEVER produces `noCache`; reading that key is the exact bug that
- * made three flags in this package silent no-ops (see
- * `test/commands/commander-option-keys.test.ts`).
- */
-export interface CacheControlOptions {
-    cache?: boolean;
-}
-/**
- * Register the root-level `--no-cache` flag and the hook that gives it effect.
- *
- * ## Why this sets an environment variable instead of plumbing a flag
- *
- * `vat validate`, `vat verify` and `vat build` enumerate nothing in their own
- * process: each `spawnSync`s the vat binary once per phase, and the child is
- * what parses the corpus. A flag parsed in the parent therefore never reaches
- * the process whose caching it is supposed to control, whereas `process.env` is
- * inherited by every child for free. `bin.ts` already leans on exactly that for
- * `VAT_CONTEXT` / `VAT_CONTEXT_PATH`.
- *
- * `VAT_CACHE=0` is read by `ParseCache` (packages/resources/src/parse-cache.ts)
- * per construction, never at module load, so setting it from a `preAction` hook
- * — after Commander has parsed, before any command body runs — is observed.
- *
- * ## The collision with `vat resources validate --no-cache`
- *
- * This root program does NOT use `enablePositionalOptions()`, so Commander scans
- * the WHOLE argv for root options, including everything after the subcommand
- * name. That is the same mechanism that let a root `-v` shadow the subcommands'
- * own `-v, --verbose` (see the incident recorded in `bin.ts`). Measured against
- * commander 12: `vat resources validate docs --no-cache` leaves the ROOT with
- * `cache: false` and the SUBCOMMAND with `cache: true` — the subcommand's
- * identically-named flag is swallowed before it ever sees it, which would have
- * silently re-enabled the external-URL cache the flag exists to bypass.
- *
- * Rather than break a shipped flag, the hook hands the value back down to
- * whichever action command declares a `cache` option of its own. `--no-cache` is
- * a superset — every cache off — so the handoff is a strengthening, never a
- * reversal.
- *
- * @param program - The root program to register the flag and hook on
- */
-export declare function registerCacheControl(program: Command): void;
-/**
- * Apply the root `--no-cache` decision: export it to child processes, and hand
- * it down to an action command that declares its own `cache` option.
- *
- * Exported so a test can drive it from real parsed options rather than from a
- * hand-built bag. Deliberately does nothing when the flag was not passed — a
- * toggle that writes `VAT_CACHE=1` by default would be indistinguishable from
- * one that is always on.
- *
- * @param rootOptions - Options bag from the ROOT program
- * @param actionCommand - The command whose action is about to run
- */
-export declare function applyCacheControl(rootOptions: CacheControlOptions, actionCommand: Command): void;
 export declare function createCacheCommand(): Command;
 //# sourceMappingURL=index.d.ts.map

package/dist/commands/cache/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAM3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,OAAO,GAAG,IAAI,CAWhG;AAED,wBAAgB,kBAAkB,IAAI,OAAO,CA6D5C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,kBAAkB,IAAI,OAAO,CA2E5C"}