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

package/dist/utils/optional-backend.js

@@ -0,0 +1,115 @@
+/**
+ * Lazy loading for **optional heavy backends** — the seam that keeps a
+ * multi-hundred-megabyte dependency out of every other command's cost.
+ *
+ * ## Why this exists rather than four `await import()` calls
+ *
+ * `@vibe-agent-toolkit/rag-lancedb` pulls a platform-native LanceDB binary
+ * (119.6 MiB unpacked on `win32-x64`, 40.3 MiB compressed to download) plus
+ * `onnxruntime-web` (133 MB) and `gpt-tokenizer` (44 MB). Measured on the
+ * published `vibe-agent-toolkit@0.1.42`: **275 MB of a 351 MB install is the
+ * RAG lane**, and a static import chain from `bin.ts` meant
+ * `import('@lancedb/lancedb')` — **1,350 ms cold** — ran before `vat --version`
+ * could print a string. It is a named seam rather than a one-off fix because
+ * "optional backend" is a shape VAT keeps growing — a projection store is
+ * loaded through it too — not because any one dependency is special.
+ *
+ * ## What it does NOT do
+ *
+ * It does not fall back, retry, or degrade. An absent backend is a legible
+ * error naming the package to install, and nothing more — the point is that
+ * the failure is readable, not that it is survivable.
+ */
+// Deliberately NOT `commands/rag/command-helpers.js`, which is where the rest
+// of the rag lane's shared helpers live: that module statically imports
+// `@vibe-agent-toolkit/rag-lancedb`, so reaching for its `handleCommandError`
+// here would load the very backend this file exists to defer.
+import { writeYamlOutput } from './output.js';
+/**
+ * Node's code for "the module is genuinely not installed".
+ *
+ * Matched on `code`, never on the message: the message embeds the specifier and
+ * the importing file and is not a stable contract, while the code is. A miss
+ * here would be reported as a missing backend when the real cause was a syntax
+ * error *inside* the backend, which is the worst possible diagnosis.
+ */
+const MODULE_NOT_FOUND = 'ERR_MODULE_NOT_FOUND';
+/**
+ * Whether a thrown value is Node's "module not installed" error.
+ *
+ * Exported because every optional backend asks it, and a second copy would be
+ * free to drift onto the message.
+ *
+ * @param error - The thrown value
+ * @returns True when the module could not be resolved at all
+ */
+export function isModuleMissing(error) {
+    return (typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && error.code === MODULE_NOT_FOUND);
+}
+/**
+ * Report an uninstalled backend and exit, in the shape every other command
+ * failure takes.
+ *
+ * Exit code **2** — a system error, not a validation failure. An absent
+ * optional package is a fact about the installation rather than about the
+ * user's corpus, and a caller scripting `vat` must be able to tell those apart
+ * from the exit code alone.
+ *
+ * Exported for the backends that are not selected by a Commander action —
+ * {@link lazyAction} is the shape most take, but a store chosen by an
+ * environment variable is loaded from inside a command rather than in place of
+ * one, and it must fail the same way.
+ *
+ * @param backend - What to name and how to install it
+ * @returns Never; the process exits
+ */
+export function reportMissingBackend(backend) {
+    const install = `npm install ${backend.packageName}`;
+    process.stderr.write(`${backend.feature} is an optional feature and its backend is not installed.\n`
+        + `\nInstall it with:  ${install}\n`
+        + '\nIt ships separately because it carries a platform-native binary that every\n'
+        + 'other vat command would otherwise download and load.\n');
+    writeYamlOutput({
+        status: 'error',
+        error: `${backend.feature} backend not installed: ${backend.packageName}`,
+        fix: install,
+    });
+    process.exit(2);
+}
+/**
+ * Bind a Commander action that loads its implementation on first invocation.
+ *
+ * The returned function has the same shape Commander expects, so a command
+ * declaration keeps every option, description and help block it had — only the
+ * *implementation* moves behind the `await`. Help text is static data and must
+ * stay eagerly available, which is exactly why the split is at the action
+ * rather than at the command.
+ *
+ * @param backend - What to name in the error when the import fails to resolve
+ * @param load - Imports the module and returns the handler out of it
+ * @returns A Commander action that loads, then delegates
+ *
+ * @example
+ * ```typescript
+ * .action(lazyAction(RAG_BACKEND, async () => (await import('./index-command.js')).indexCommand))
+ * ```
+ */
+export function lazyAction(backend, load) {
+    return async (...args) => {
+        let handler;
+        try {
+            handler = await load();
+        }
+        catch (error) {
+            if (!isModuleMissing(error)) {
+                throw error;
+            }
+            reportMissingBackend(backend);
+        }
+        await handler(...args);
+    };
+}
+//# sourceMappingURL=optional-backend.js.map

package/dist/utils/optional-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-backend.js","sourceRoot":"","sources":["../../src/utils/optional-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAC9E,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;WACtB,KAAK,KAAK,IAAI;WACd,MAAM,IAAI,KAAK;WACd,KAA4B,CAAC,IAAI,KAAK,gBAAgB,CAC3D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAwB;IAC3D,MAAM,OAAO,GAAG,eAAe,OAAO,CAAC,WAAW,EAAE,CAAC;IACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,OAAO,CAAC,OAAO,6DAA6D;UAC7E,uBAAuB,OAAO,IAAI;UAClC,gFAAgF;UAChF,wDAAwD,CAC3D,CAAC;IACF,eAAe,CAAC;QACd,MAAM,EAAE,OAAO;QACf,KAAK,EAAE,GAAG,OAAO,CAAC,OAAO,2BAA2B,OAAO,CAAC,WAAW,EAAE;QACzE,GAAG,EAAE,OAAO;KACb,CAAC,CAAC;IACH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAUD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CACxB,OAAwB,EACxB,IAA+C;IAE/C,OAAO,KAAK,EAAE,GAAG,IAAU,EAAiB,EAAE;QAC5C,IAAI,OAA0C,CAAC;QAC/C,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,IAAI,EAAE,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,KAAK,CAAC;YACd,CAAC;YACD,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;QACD,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC;AACJ,CAAC"}

package/dist/utils/output.d.ts

@@ -76,6 +76,23 @@ export declare function writeAllSync(write: SyncWriter, buffer: Buffer, options?
  * @param data - Data to serialize as YAML
  */
 export declare function writeYamlOutput(data: unknown): void;
+/**
+ * Write a single JSON document to stdout.
+ *
+ * The sibling of {@link writeYamlOutput}, for the same payloads, and it exists
+ * because a consumer that has to parse YAML needs a YAML parser: JSON is the
+ * format every language reads without one. `vat resources validate` already
+ * offers `--format json` for exactly this reason; a scan document that could
+ * only be had as YAML made the population it reports the harder of the two to
+ * consume programmatically, which is backwards.
+ *
+ * Written the same way as its YAML sibling, and the comment there applies
+ * verbatim: the ordinary stream write keeps this summary behind any
+ * human-readable progress already buffered on the same channel.
+ *
+ * @param data - Data to serialize as JSON
+ */
+export declare function writeJsonOutput(data: unknown): void;
 /**
  * Write a test-format finding to stderr.
  *

package/dist/utils/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKrD;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;AAoCpF,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,CAAC,kBAAkB,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAChC,IAAI,CA+BN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAWnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,IAAI,CAEN"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKrD;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;AAoCpF,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,CAAC,kBAAkB,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAChC,IAAI,CA+BN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAWnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAEnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,IAAI,CAEN"}

package/dist/utils/output.js

@@ -138,6 +138,25 @@ export function writeYamlOutput(data) {
         aliasDuplicateObjects: false,
     })}`);
 }
+/**
+ * Write a single JSON document to stdout.
+ *
+ * The sibling of {@link writeYamlOutput}, for the same payloads, and it exists
+ * because a consumer that has to parse YAML needs a YAML parser: JSON is the
+ * format every language reads without one. `vat resources validate` already
+ * offers `--format json` for exactly this reason; a scan document that could
+ * only be had as YAML made the population it reports the harder of the two to
+ * consume programmatically, which is backwards.
+ *
+ * Written the same way as its YAML sibling, and the comment there applies
+ * verbatim: the ordinary stream write keeps this summary behind any
+ * human-readable progress already buffered on the same channel.
+ *
+ * @param data - Data to serialize as JSON
+ */
+export function writeJsonOutput(data) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+}
 /**
  * Write a test-format finding to stderr.
  *

package/dist/utils/output.js.map

@@ -1 +1 @@
-{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,YAAY,CACV,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAChE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAC7B,CAAC;AACJ,CAAC;AAUD;;;;;;;;;GASG;AACH,MAAM,8BAA8B,GAAG,MAAM,CAAC;AAE9C,uEAAuE;AACvE,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,SAAS,SAAS,CAAC,EAAU;IAC3B,OAAO,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,SAAS,yBAAyB,CAAC,kBAA0B;IAC3D,IAAI,kBAAkB,GAAG,mBAAmB;QAAE,SAAS,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAiB,EACjB,MAAc,EACd,UAA+B,EAAE;IAEjC,MAAM,UAAU,GAAG,OAAO,CAAC,qBAAqB,IAAI,8BAA8B,CAAC;IACnF,MAAM,IAAI,GAAG,OAAO,CAAC,kBAAkB,IAAI,yBAAyB,CAAC;IAErE,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,kBAAkB,GAAG,CAAC,CAAC;IAE3B,OAAO,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC;YAC1D,sEAAsE;YACtE,oCAAoC;YACpC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,aAAa,MAAM,CAAC,MAAM,GAAG,OAAO,YAAY,CAAC,CAAC;YAClH,CAAC;YACD,OAAO,IAAI,CAAC,CAAC;YACb,kBAAkB,GAAG,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,wEAAwE;YACxE,wEAAwE;YACxE,yBAAyB;YACzB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,KAAK,CAAC;YACpE,kBAAkB,EAAE,CAAC;YACrB,IAAI,kBAAkB,GAAG,UAAU,EAAE,CAAC;gBACpC,MAAM,IAAI,KAAK,CACb,kBAAkB,UAAU,sDAAsD,OAAO,OAAO,MAAM,CAAC,MAAM,8CAA8C,CAC5J,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,4EAA4E;IAC5E,wEAAwE;IACxE,4EAA4E;IAC5E,8EAA8E;IAC9E,2DAA2D;IAC3D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE;QAChD,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,GAAG;QACd,qBAAqB,EAAE,KAAK;KAC7B,CAAC,EAAE,CAAC,CAAC;AACR,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,IAAY,EACZ,MAAc,EACd,QAAgB,EAChB,OAAe;IAEf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,MAAM,KAAK,QAAQ,KAAK,OAAO,IAAI,CAAC,CAAC;AAC/E,CAAC"}
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"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"}

package/dist/utils/population-wiring.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The three arguments every CLI lane hands a projection population builder the
+ * same way: the blob-stage observer, the ignore oracle, and the run's store.
+ *
+ * ## Why this is CLI code and not `resources` code
+ *
+ * Nothing here decides anything about a projection. The observer's whole body is
+ * `describeBlobRefusals` — owned by `@vibe-agent-toolkit/resources` — routed to a
+ * {@link Logger}, which is a CLI type no other package has; the two spreads exist
+ * only because `exactOptionalPropertyTypes` makes "absent" and "present and
+ * undefined" different arguments. That is command plumbing, in the same family as
+ * `projection-store.ts` next door, so it stays inside the package the CLI-stays-
+ * dumb rule allows it in.
+ *
+ * ## The observer is the reason this is shared rather than retyped
+ *
+ * `buildInventoryPopulation` and `buildClaudeContextPopulation` both REQUIRE
+ * `onBlobPopulation` — a caller with nothing to do with the counts must name
+ * `DISCARD_BLOB_POPULATION` rather than leave it off — because a tree whose every
+ * document was declined as binary otherwise populates as empty and reports
+ * success. Two hand-written copies of the reporting half is two places for that
+ * report to quietly become a no-op.
+ */
+import { type BlobPopulationReport, type PopulationCache } from '@vibe-agent-toolkit/resources';
+import type { GitTracker } from '@vibe-agent-toolkit/utils';
+import type { Logger } from './logger.js';
+/**
+ * The population arguments {@link populationWiring} supplies.
+ *
+ * Spread into a builder's options object, so the two oracles are optional in the
+ * `exactOptionalPropertyTypes` sense — omitted entirely when they are absent,
+ * never present-and-undefined.
+ */
+export interface PopulationWiring {
+    onBlobPopulation: (report: BlobPopulationReport) => void;
+    gitTracker?: GitTracker | undefined;
+    cache?: PopulationCache | undefined;
+}
+/**
+ * Wire one population's blob-stage observer, ignore oracle and store.
+ *
+ * `describeBlobRefusals` returns undefined on a run that refused nothing, so a
+ * clean population stays exactly as quiet as it was — which is the only thing
+ * that keeps the line worth reading when it does appear.
+ *
+ * ⚠️ The refusals go to `logger.warn`, i.e. **stderr**. Both callers write a
+ * parseable document to stdout, and a diagnostic in the middle of it breaks every
+ * consumer.
+ *
+ * @param logger - Where blob-stage refusals are reported
+ * @param gitTracker - The ignore oracle, or undefined when there is none. Not
+ *   cosmetic: `resource_realizations.gitignored` is filled only when a tracker
+ *   was supplied, so its absence decides whether a consumer can TELL which
+ *   members were ignored
+ * @param cache - The run's projection store, or undefined to re-derive
+ * @returns The options to spread into the population builder's argument
+ */
+export declare function populationWiring(logger: Logger, gitTracker: GitTracker | undefined, cache: PopulationCache | undefined): PopulationWiring;
+//# sourceMappingURL=population-wiring.d.ts.map

package/dist/utils/population-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"population-wiring.d.ts","sourceRoot":"","sources":["../../src/utils/population-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAwB,KAAK,oBAAoB,EAAE,KAAK,eAAe,EAAE,MACzE,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACzD,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,KAAK,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,gBAAgB,CASlB"}

package/dist/utils/population-wiring.js

@@ -0,0 +1,55 @@
+/**
+ * The three arguments every CLI lane hands a projection population builder the
+ * same way: the blob-stage observer, the ignore oracle, and the run's store.
+ *
+ * ## Why this is CLI code and not `resources` code
+ *
+ * Nothing here decides anything about a projection. The observer's whole body is
+ * `describeBlobRefusals` — owned by `@vibe-agent-toolkit/resources` — routed to a
+ * {@link Logger}, which is a CLI type no other package has; the two spreads exist
+ * only because `exactOptionalPropertyTypes` makes "absent" and "present and
+ * undefined" different arguments. That is command plumbing, in the same family as
+ * `projection-store.ts` next door, so it stays inside the package the CLI-stays-
+ * dumb rule allows it in.
+ *
+ * ## The observer is the reason this is shared rather than retyped
+ *
+ * `buildInventoryPopulation` and `buildClaudeContextPopulation` both REQUIRE
+ * `onBlobPopulation` — a caller with nothing to do with the counts must name
+ * `DISCARD_BLOB_POPULATION` rather than leave it off — because a tree whose every
+ * document was declined as binary otherwise populates as empty and reports
+ * success. Two hand-written copies of the reporting half is two places for that
+ * report to quietly become a no-op.
+ */
+import { describeBlobRefusals } from '@vibe-agent-toolkit/resources';
+/**
+ * Wire one population's blob-stage observer, ignore oracle and store.
+ *
+ * `describeBlobRefusals` returns undefined on a run that refused nothing, so a
+ * clean population stays exactly as quiet as it was — which is the only thing
+ * that keeps the line worth reading when it does appear.
+ *
+ * ⚠️ The refusals go to `logger.warn`, i.e. **stderr**. Both callers write a
+ * parseable document to stdout, and a diagnostic in the middle of it breaks every
+ * consumer.
+ *
+ * @param logger - Where blob-stage refusals are reported
+ * @param gitTracker - The ignore oracle, or undefined when there is none. Not
+ *   cosmetic: `resource_realizations.gitignored` is filled only when a tracker
+ *   was supplied, so its absence decides whether a consumer can TELL which
+ *   members were ignored
+ * @param cache - The run's projection store, or undefined to re-derive
+ * @returns The options to spread into the population builder's argument
+ */
+export function populationWiring(logger, gitTracker, cache) {
+    return {
+        onBlobPopulation: (report) => {
+            const refusals = describeBlobRefusals(report);
+            if (refusals !== undefined)
+                logger.warn(refusals);
+        },
+        ...(gitTracker !== undefined && { gitTracker }),
+        ...(cache !== undefined && { cache }),
+    };
+}
+//# sourceMappingURL=population-wiring.js.map

package/dist/utils/population-wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"population-wiring.js","sourceRoot":"","sources":["../../src/utils/population-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oBAAoB,EAAmD,MACzE,+BAA+B,CAAC;AAkBvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,UAAkC,EAClC,KAAkC;IAElC,OAAO;QACL,gBAAgB,EAAE,CAAC,MAAM,EAAE,EAAE;YAC3B,MAAM,QAAQ,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;YAC9C,IAAI,QAAQ,KAAK,SAAS;gBAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACpD,CAAC;QACD,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC;QAC/C,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC"}

package/dist/utils/projection-store.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Selecting, opening and keying the **projection store** — the cross-process
+ * cache that makes a second population of an unchanged tree cheap.
+ *
+ * ## Why the CLI owns this and `resources` does not
+ *
+ * `@vibe-agent-toolkit/resources` states the {@link ProjectionStore} contract
+ * and never picks a backend, for the same reason it states the parse contract
+ * and never picks a parser: it is the toolkit's most widely installed package,
+ * and a storage engine is a *choice*. The choice is made here, at the edge that
+ * already owns every other optional backend — see `optional-backend.ts`, whose
+ * header names a projection store as one of the shapes it exists for.
+ *
+ * So `populate()` takes a {@link PopulationCache} it is handed, and this module
+ * is the only place in the toolkit that knows `@vibe-agent-toolkit/projection-
+ * sqlite` exists.
+ *
+ * ## The key, and why it is a whole-repository tree hash
+ *
+ * A stored extent is filed under `(rootId, treeHash)`. `populate()` derives the
+ * root id itself so a caller cannot file one root's contents under another's;
+ * this module supplies the other half.
+ *
+ * {@link gitTreeSnapshot} answers it with `git write-tree` against a throwaway
+ * index, which covers staged edits, unstaged edits and untracked files, and
+ * carries **no timestamp** — byte-identical content always produces the same
+ * hash. 🪤 Never `git stash create`: a stash is a *commit*, so two calls over
+ * identical content agree only within the same wall-clock second, and every
+ * read would miss.
+ *
+ * ⚠️ That hash covers the whole **repository**, not the subtree the root names.
+ * An edit anywhere in the repository therefore cools the cache for every root
+ * inside it. This is conservative in the safe direction and cheap to be
+ * conservative about — `git write-tree` against a throwaway index is the same
+ * call `vibe-validate` makes on every commit.
+ *
+ * ## An opted-in cache that quietly does nothing is worse than no cache
+ *
+ * Every failure here is loud, and that is deliberate rather than harsh. A
+ * selector nobody honours produces a measurement arm that believes it is
+ * testing a cache and is testing an ordinary cold run — the "subject that
+ * exercises nothing looks like a clean result" failure that has already cost
+ * this project one whole A/B. So an uninstalled backend exits with the seam's
+ * standard legible error, and a tree that cannot be keyed says so on stderr
+ * rather than silently declining.
+ */
+import type { PopulationCache } from '@vibe-agent-toolkit/resources';
+/**
+ * The env var that selects a projection store for this process.
+ *
+ * An environment switch rather than a config field, for the same reason
+ * `VAT_INVENTORY_CRAWL` and `VAT_RESOURCES_CRAWL` are: it selects which
+ * INSTRUMENT runs, not what the project means, and it has to be reachable from
+ * the lab, which spawns the binary and controls its environment. A config field
+ * would put the A and B arms inside the subject's own tree, where a measurement
+ * edits the thing it measures.
+ *
+ * 🔑 It is read from the environment and therefore **inherited by every phase
+ * child**. `runPhase` passes no `env` to `spawnSync`, so `vat validate`'s
+ * children see the same selection their parent did.
+ *
+ * 🔑 **That inheritance now has a within-verb instance.** `vat build`'s two
+ * phases — `skills build` and `claude plugin build` — both reach the lane
+ * through `withResourcePopulationSource` (see `resource-loader.ts`), and both
+ * root their population at the same directory, so phase 2 reads the extent
+ * phase 1 wrote. Measured on `packages/vat-development-agents` with
+ * `VAT_CRAWL_TIMING`: with a cold store phase 1 files `builtin:filesystem`
+ * 39.2 ms and `projection-store:write` 10.1 ms, phase 2 files neither and its
+ * `resource-registry:enumerate` reads 3.6 ms against phase 1's 66.6 ms.
+ *
+ * It did NOT need the closure to emit reasons, which is what an earlier reading
+ * of this expected: the packaging lanes consume `resource_realizations` and let
+ * `walkLinkGraph` keep running on top of the registry, so the base extent alone
+ * answers them — the same shape `buildResourcePopulation` already had.
+ *
+ * The cross-INVOCATION win is unchanged and independent: `vat validate` and
+ * `vat verify` spawn a byte-identical `resources validate` child, so the second
+ * hits the store.
+ *
+ * ⚠️ One packaging enumeration is still on the walk: `vat claude plugin build`'s
+ * per-skill post-build validation, which reaches `crawlAndResolveRegistry` in
+ * `packaging-validator.ts` without a source — its `withResourcePopulationSource`
+ * bracket closes around `createProjectRegistry` and does not span the
+ * marketplace loop. `vat skills build` no longer does: it holds one bracket over
+ * the whole run, and the registry memo is keyed on the population source, so
+ * both of its registries source from the projection.
+ */
+export declare const PROJECTION_STORE_ENV = "VAT_PROJECTION_STORE";
+/** {@link PROJECTION_STORE_ENV}'s value that selects the SQLite backend. */
+export declare const PROJECTION_STORE_SQLITE = "sqlite";
+/**
+ * The env var that turns VAT's disk caches off for a run.
+ *
+ * Not this module's invention — `ParseCache` has read it since the parse cache
+ * shipped, and `vat`'s root `--no-cache` exports it from a `preAction` hook so
+ * the decision reaches every spawned phase. Named here rather than spelled
+ * inline so the projection store is visibly the same tenant as the caches the
+ * flag was written for.
+ */
+export declare const CACHE_ENV = "VAT_CACHE";
+/** {@link CACHE_ENV}'s one off value. Exactly `'0'`, never truthiness — see {@link projectionStoreSelected}. */
+export declare const CACHE_DISABLED = "0";
+/**
+ * Whether this process should read and write a projection store.
+ *
+ * **Off unless asked for**, which is the opposite of `vat inventory`'s crawl
+ * selector and matches `vat resources scan`'s. A cache changes no answer, so
+ * the reason to hold it back is not correctness but evidence: the win is a
+ * claim about cost, and a default flipped before the cost is measured on real
+ * corpora is a claim nobody checked.
+ *
+ * Read from the environment at each call rather than memoized at module load:
+ * `vitest.setup.js` deletes every `VAT_*` variable before any test module
+ * loads, so a module-level binding would make the switch unobservable to every
+ * test that sets it.
+ *
+ * ## The two switches are AND-ed, and the second one is a veto
+ *
+ * {@link PROJECTION_STORE_ENV} says *which* backend; {@link CACHE_ENV} says
+ * whether this run caches at all. A store selected while `VAT_CACHE=0` was
+ * measured writing a 9.8 MB, 18,079-row store on this repository and hitting it
+ * on the next run — a user who asked for no cache silently got one, and
+ * `vat cache`'s own help text described three caches while a fourth was being
+ * written beside them.
+ *
+ * 🪤 Compared against `'0'` exactly, never for truthiness, matching
+ * `ParseCache`'s `env['VAT_CACHE'] !== '0'`. `VAT_CACHE=1` is the value an
+ * operator writes to turn caching ON, and a truthiness test would read it as a
+ * reason to decline.
+ *
+ * @returns `true` when a store is selected
+ */
+export declare function projectionStoreSelected(): boolean;
+/** An open store, the key half it is used with, and the way to let it go. */
+export interface OpenedPopulationCache {
+    /** Hand this to `populate()`. */
+    readonly cache: PopulationCache;
+    /**
+     * Close the underlying connection.
+     *
+     * Must be called. A `DatabaseSync` left open holds its file handle and, in
+     * WAL mode, its read transaction — see `projection-sqlite`'s note on why an
+     * unfinalized read statement pins a connection to a stale snapshot.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Open the projection store this process selected, keyed to one tree.
+ *
+ * Returns `undefined` when no store is selected, and when the tree cannot be
+ * keyed — the two "carry on without a cache" answers. It does **not** return
+ * `undefined` for an uninstalled backend: a user who set the selector asked for
+ * a store, and answering that request by silently not having one is how an
+ * opted-in cache becomes an unmeasured one.
+ *
+ * @param options - Where the corpus is
+ * @param options.root - The absolute corpus root. Used to find the repository;
+ *   the resulting hash covers that whole repository, not this subtree
+ * @returns The cache and its closer, or `undefined` to populate uncached
+ */
+export declare function openPopulationCache(options: {
+    root: string;
+}): Promise<OpenedPopulationCache | undefined>;
+/**
+ * Run one command's work with a projection store open for its whole duration,
+ * and closed however it ends.
+ *
+ * A scope rather than a bare open/close pair, because the store must outlive the
+ * call that builds a population source and not merely the call that uses it: the
+ * inventory extractor MEMOIZES its population provider and may reach it well
+ * after the frame that supplied it has returned. A store closed at the end of
+ * that frame would be closed under its own consumer.
+ *
+ * It is also the `withGitSnapshotCache` bracket for the work inside it, so the
+ * key and the extent filed under it come from ONE git snapshot — see the note
+ * on the call below.
+ *
+ * @param options - Where the corpus is
+ * @param options.root - The absolute corpus root
+ * @param work - Given the cache, or `undefined` when there is none to give
+ * @returns Whatever `work` returned
+ */
+export declare function withPopulationCache<T>(options: {
+    root: string;
+}, work: (cache: PopulationCache | undefined) => Promise<T>): Promise<T>;
+//# sourceMappingURL=projection-store.d.ts.map

package/dist/utils/projection-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection-store.d.ts","sourceRoot":"","sources":["../../src/utils/projection-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAKrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,gHAAgH;AAChH,eAAO,MAAM,cAAc,MAAM,CAAC;AAelC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAGjD;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IACjD,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAsB7C;AAuBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACzB,IAAI,EAAE,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GACvD,OAAO,CAAC,CAAC,CAAC,CA0BZ"}