@vibe-agent-toolkit/cli 0.2.0-rc.1 → 0.2.0-rc.11

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

@@ -6,20 +6,48 @@
  * described in prose. This is that path, named once.
  *
  * Scope is the WHOLE `<tmpdir>/.vat-cache/` tree, not just the parse tenant.
- * That directory is shared — `external-links.json`, `auth-<user>/` and `parse/`
- * all live under it — and "clear the cache" cannot honestly mean "clear one of
- * the three". All of them are disposable by construction.
+ * That directory is shared — `external-links.json`, `auth-<user>/`, `parse/` and
+ * `<namespace>/projection-<shapeDigest>/projection.db` all live under it — and
+ * "clear the cache" cannot honestly mean "clear one of the four". All of them
+ * are disposable by construction.
+ *
+ * 🔑 **The projection store is the one that makes this command matter, and it is
+ * covered by SCOPE rather than by a clause about it.** `defaultStoreDirectory()`
+ * resolves through `vatCacheNamespaceRoot()`, so it is already inside the tree
+ * this removes; the tenant list above is the only thing that has to keep up. It
+ * is also by far the largest tenant (71 MB for one 12,602-file tree) and is on
+ * by DEFAULT, which is why reclaiming it had to be invocable before the flip.
+ *
+ * ⚠️ A store relocated with `VAT_PROJECTION_STORE_DIR` is outside this tree and
+ * is NOT removed — the variable names a directory this command was never told
+ * about, and a clear that hunted for stores by shape would delete directories
+ * the operator chose. Stated so nobody reads a clean `bytesRemoved` as "every
+ * store is gone".
  */
 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;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAgBH,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,CAiBtF"}

package/dist/commands/cache/clear.js

@@ -6,20 +6,53 @@
  * described in prose. This is that path, named once.
  *
  * Scope is the WHOLE `<tmpdir>/.vat-cache/` tree, not just the parse tenant.
- * That directory is shared — `external-links.json`, `auth-<user>/` and `parse/`
- * all live under it — and "clear the cache" cannot honestly mean "clear one of
- * the three". All of them are disposable by construction.
+ * That directory is shared — `external-links.json`, `auth-<user>/`, `parse/` and
+ * `<namespace>/projection-<shapeDigest>/projection.db` all live under it — and
+ * "clear the cache" cannot honestly mean "clear one of the four". All of them
+ * are disposable by construction.
+ *
+ * 🔑 **The projection store is the one that makes this command matter, and it is
+ * covered by SCOPE rather than by a clause about it.** `defaultStoreDirectory()`
+ * resolves through `vatCacheNamespaceRoot()`, so it is already inside the tree
+ * this removes; the tenant list above is the only thing that has to keep up. It
+ * is also by far the largest tenant (71 MB for one 12,602-file tree) and is on
+ * by DEFAULT, which is why reclaiming it had to be invocable before the flip.
+ *
+ * ⚠️ A store relocated with `VAT_PROJECTION_STORE_DIR` is outside this tree and
+ * is NOT removed — the variable names a directory this command was never told
+ * about, and a clear that hunted for stores by shape would delete directories
+ * the operator chose. Stated so nobody reads a clean `bytesRemoved` as "every
+ * store is gone".
  */
 import { promises as fs } from 'node:fs';
 import { basename, dirname } from 'node:path';
 import { parseCacheDirectory } from '@vibe-agent-toolkit/resources';
-import { safePath } from '@vibe-agent-toolkit/utils';
+import { ExitCode } from '@vibe-agent-toolkit/schema';
+import { direntKind, isPathAbsentError, safePath } from '@vibe-agent-toolkit/utils';
 import { handleCommandError } from '../../utils/command-error.js';
 import { createLogger } from '../../utils/logger.js';
 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 +113,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 +178,12 @@ 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.
+        // A partial clear is a run that did not finish, not a finding about the tree.
+        process.exit(report.status === 'partial' ? ExitCode.ERROR : ExitCode.OK);
     }
     catch (error) {
         handleCommandError(error, logger, startTime, 'CacheClear');
@@ -117,7 +198,6 @@ export async function cacheClearCommand(options = {}) {
  */
 async function readdirOrNull(dir) {
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is the derived cache root or a caller-injected test directory
         return await fs.readdir(dir, { withFileTypes: true });
     }
     catch (error) {
@@ -130,9 +210,11 @@ async function readdirOrNull(dir) {
 async function measureEntries(dir, entries) {
     const usages = await Promise.all(entries.map(async (entry) => {
         const child = safePath.join(dir, entry.name);
-        // Not `isFile()`: a symlink or socket is still an entry that is about to
-        // be removed, and counting only regular files would under-report it.
-        return entry.isDirectory() ? measureTree(child) : { entries: 1, bytes: await sizeOf(child) };
+        // Not `isFile()`, and NOT followed: a symlink or socket is still an entry
+        // that is about to be removed, and counting only regular files would
+        // under-report it — while walking INTO a linked directory would count a
+        // tree `rm -rf` leaves untouched.
+        return direntKind(entry) === 'directory' ? measureTree(child) : { entries: 1, bytes: await sizeOf(child) };
     }));
     return usages.reduce((total, usage) => ({ entries: total.entries + usage.entries, bytes: total.bytes + usage.bytes }), EMPTY_USAGE);
 }
@@ -147,16 +229,20 @@ async function measureTree(dir) {
  * A file that disappears between the listing and the stat contributes 0 rather
  * than failing the clear — the whole tree is about to be deleted anyway, and a
  * concurrent vat run pruning its own temp file must not turn cleanup into an
- * error.
+ * error. Only a DISAPPEARANCE is 0: an entry the OS refuses to stat is still
+ * there, still about to be counted as reclaimed, and the `rm` that follows is
+ * about to meet the same refusal — so it is raised here, where it names the
+ * entry, rather than read as an empty file.
  */
 async function sizeOf(target) {
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is inside the cache root being measured
         const stats = await fs.lstat(target);
         return stats.size;
     }
-    catch {
-        return 0;
+    catch (error) {
+        if (isPathAbsentError(error))
+            return 0;
+        throw error;
     }
 }
 //# sourceMappingURL=clear.js.map

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,CAoF5C"}

package/dist/commands/cache/index.js

@@ -1,75 +1,20 @@
 /**
- * Cache command group, plus the root-level `--no-cache` control surface.
+ * Cache command group.
  *
- * 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*.
+ * 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';
 import { cacheClearCommand } from './clear.js';
-/**
- * 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 function registerCacheControl(program) {
-    program.option('--no-cache', "Disable VAT's disk caches for this run (also applies to spawned phases)");
-    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);
-    }
-}
 export function createCacheCommand() {
     const cache = new Command('cache');
     cache
@@ -77,13 +22,25 @@ export function createCacheCommand() {
         .helpCommand(false)
         .addHelpText('after', `
 Description:
-  VAT keeps three disposable caches under <tmpdir>/.vat-cache: parse facts
-  keyed by file content, external-URL validation results, and per-OS-user
-  authenticated-link content. None of them is durable — recovery is always
-  "rescan", and the OS temp purge is the eviction policy.
+  VAT keeps four disposable caches under <tmpdir>/.vat-cache: parse facts
+  keyed by file content, external-URL validation results, per-OS-user
+  authenticated-link content, and the projection store — a SQLite database
+  holding one whole scanned tree per entry, on by default, and by far the
+  largest of the four. None of them is durable — recovery is always "rescan".
+
+  How large: one 12,602-file repository measured 71 MB of projection store,
+  and the file holds several trees per repository plus a shared blob tier, so
+  a machine that has scanned a few projects reaches the hundreds of MB. The
+  other three tenants are a few MB between them.
+
+  Only the projection store evicts anything on its own: it keeps the three
+  most recently written trees per root and the 50,000 most recently written
+  content keys, dropping the rest as it writes. The other three rely on the OS
+  temp purge, and every one of them is reclaimed in full by vat cache clear.
 
   To run WITHOUT the caches rather than remove them, use --no-cache on any
-  command (or VAT_CACHE=0), which also applies to spawned phases.
+  command (or VAT_CACHE=0), which also applies to spawned phases and to the
+  projection store. VAT_PROJECTION_STORE=off turns off just the store.
 
 Example:
   $ vat cache clear                    # Reclaim the temp-directory cache tree
@@ -97,9 +54,15 @@ Example:
         .addHelpText('after', `
 Description:
   Removes <tmpdir>/.vat-cache in its entirety — the parse cache, the
-  external-URL validation cache, and the per-OS-user authenticated-link cache.
-  Every one of them is disposable by design: the next run repopulates what it
-  needs, so the only cost of clearing is one cold pass.
+  external-URL validation cache, the per-OS-user authenticated-link cache, and
+  the projection store (<namespace>/projection-<shape>/projection.db), which is
+  usually most of the bytes this reclaims: 71 MB for a single 12,602-file
+  repository, and the hundreds of MB once a machine has scanned several. Every
+  one of them is disposable by design: the next run repopulates what it needs,
+  so the only cost of clearing is one cold pass.
+
+  A projection store relocated with VAT_PROJECTION_STORE_DIR lives outside
+  this tree and is not removed — delete that directory yourself.
 
   Runs regardless of --no-cache / VAT_CACHE=0. Turning caching off must not
   disarm the one command that reclaims the space.
@@ -107,16 +70,21 @@ Description:
   A cache directory that does not exist is not an error — nothing to remove is
   a successful clear.
 
+  The tree is shared by every VAT on the machine, so another run writing into
+  it can make the delete stop part-way. That is reported as status: partial,
+  naming what went and what stayed, rather than failing with no account of it.
+
 Output:
   - cacheDir: absolute path that was targeted
   - existed: whether the directory was there at all
-  - removed: top-level entries that were deleted
-  - entriesRemoved / bytesRemoved: file count and total size, measured before
-    deletion
+  - removed: top-level entries that are now gone
+  - remaining / reason: what survived a partial clear, and why (partial only)
+  - entriesRemoved / bytesRemoved: file count and total size actually removed
 
 Exit Codes:
   0 - Cache cleared (or already absent)
-  2 - Could not remove the cache (permissions, busy file)
+  1 - Cleared only in part, because something else is using the tree
+  2 - Could not read or target the cache at all (permissions, unexpected layout)
 
 Example:
   $ vat cache clear                    # Reclaim the temp-directory cache tree

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAA0B,MAAM,YAAY,CAAC;AAavE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,yEAAyE,CAAC,CAAC;IAExG,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;AAED,MAAM,UAAU,kBAAkB;IAChC,MAAM,KAAK,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC,KAAK;SACF,WAAW,CAAC,iEAAiE,CAAC;SAC9E,WAAW,CAAC,KAAK,CAAC;SAClB,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;CAYL,CACI,CAAC;IAEJ,KAAK;SACF,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,gEAAgE,CAAC;SAC7E,MAAM,CAAC,KAAK;QACX,MAAM,iBAAiB,CAAC,IAAI,CAAC,eAAe,EAAuB,CAAC,CAAC;IACvE,CAAC,CAAC;SACD,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BL,CACI,CAAC;IAEJ,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAA0B,MAAM,YAAY,CAAC;AAGvE,MAAM,UAAU,kBAAkB;IAChC,MAAM,KAAK,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC,KAAK;SACF,WAAW,CAAC,iEAAiE,CAAC;SAC9E,WAAW,CAAC,KAAK,CAAC;SAClB,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;CAwBL,CACI,CAAC;IAEJ,KAAK;SACF,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,gEAAgE,CAAC;SAC7E,MAAM,CAAC,KAAK;QACX,MAAM,iBAAiB,CAAC,IAAI,CAAC,eAAe,EAAuB,CAAC,CAAC;IACvE,CAAC,CAAC;SACD,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCL,CACI,CAAC;IAEJ,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/commands/claude/claude-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-config.d.ts","sourceRoot":"","sources":["../../../src/commands/claude/claude-config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAGnF,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC;CACxC,CAAC,CAWD"}
+{"version":3,"file":"claude-config.d.ts","sourceRoot":"","sources":["../../../src/commands/claude/claude-config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAGnF,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC;CACxC,CAAC,CAiBD"}

package/dist/commands/claude/claude-config.js

@@ -15,6 +15,12 @@ export async function loadClaudeProjectConfig() {
     if (!configPath) {
         throw new Error('No vibe-agent-toolkit.config.yaml found. Run from a project directory.');
     }
+    // No `onUnknownKeys` argument: `parseConfigFile` already DEFAULTS to writing
+    // the warning to stderr, which is exactly what this lane needs — unknown keys
+    // are a warning rather than a refusal, and stderr keeps the YAML document on
+    // stdout machine-readable. Passing a callback byte-identical to the default
+    // said "this command has an opinion here" while changing nothing, so a later
+    // reader would have to diff it against the default to learn it was dead.
     const config = await parseConfigFile(configPath);
     const configDir = dirname(configPath);
     return { configPath, configDir, claudeConfig: config.claude };