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

package/dist/utils/optional-backend.js

@@ -0,0 +1,117 @@
+/**
+ * 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
+ * (97.8 MB unpacked on `darwin-arm64`, and larger still on `win32-x64`, where
+ * it measured 119.6 MiB) plus `onnxruntime-web` (137.5 MB) and `gpt-tokenizer`
+ * (42.2 MB). Summed over the RAG lane's third-party closure against this
+ * release's pins, on `darwin-arm64`: **~287 MB unpacked**, 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 { ExitCode } from '@vibe-agent-toolkit/schema';
+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(ExitCode.ERROR);
+}
+/**
+ * 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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAC9E,8DAA8D;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAEtD,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,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/B,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,32 @@ 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 one structured document in the format a `--format` option selected:
+ * `json` → {@link writeJsonOutput}; anything else (including an absent option)
+ * → {@link writeYamlOutput}, the CLI's default document format.
+ *
+ * @param data - The document
+ * @param format - The selected format (`json`, or anything else for YAML)
+ */
+export declare function writeStructuredOutput(data: unknown, format: string | undefined): 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;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAMrF;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,41 @@ 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 one structured document in the format a `--format` option selected:
+ * `json` → {@link writeJsonOutput}; anything else (including an absent option)
+ * → {@link writeYamlOutput}, the CLI's default document format.
+ *
+ * @param data - The document
+ * @param format - The selected format (`json`, or anything else for YAML)
+ */
+export function writeStructuredOutput(data, format) {
+    if (format === 'json') {
+        writeJsonOutput(data);
+    }
+    else {
+        writeYamlOutput(data);
+    }
+}
 /**
  * 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":"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"}
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"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"}

package/dist/utils/package-json.d.ts

@@ -0,0 +1,24 @@
+/**
+ * One reading of a project's `package.json` for the lanes that want an
+ * OPTIONAL field out of it — a `version` to stamp, a `vat.skills` list, a
+ * `files` allowlist.
+ *
+ * Every one of those lanes used to spell the read as `existsSync` →
+ * `readFileSync` → `JSON.parse` inside one `try { … } catch { return <absent> }`,
+ * which made "there is no package.json" indistinguishable from "there is one
+ * and it is not JSON" and from "there is one and the OS refused it". The first
+ * is the sentinel's meaning; the other two were reported as it — a build
+ * stamped no version, a consistency check verified nothing, and neither said
+ * why. npm itself refuses a manifest it cannot parse, so a tree with one is
+ * already broken; the reader's job is to say so, not to proceed around it.
+ */
+/**
+ * The parsed manifest, or `undefined` when there is none at `pkgPath`.
+ *
+ * @throws {Error} naming the file when it exists but is not a JSON object;
+ *   the parse error is the `cause`.
+ * @throws whatever the filesystem threw for anything that is not an absence
+ *   (a refusal stays a refusal).
+ */
+export declare function readPackageJsonOrAbsent(pkgPath: string): Record<string, unknown> | undefined;
+//# sourceMappingURL=package-json.d.ts.map

package/dist/utils/package-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-json.d.ts","sourceRoot":"","sources":["../../src/utils/package-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAoB5F"}

package/dist/utils/package-json.js

@@ -0,0 +1,49 @@
+/**
+ * One reading of a project's `package.json` for the lanes that want an
+ * OPTIONAL field out of it — a `version` to stamp, a `vat.skills` list, a
+ * `files` allowlist.
+ *
+ * Every one of those lanes used to spell the read as `existsSync` →
+ * `readFileSync` → `JSON.parse` inside one `try { … } catch { return <absent> }`,
+ * which made "there is no package.json" indistinguishable from "there is one
+ * and it is not JSON" and from "there is one and the OS refused it". The first
+ * is the sentinel's meaning; the other two were reported as it — a build
+ * stamped no version, a consistency check verified nothing, and neither said
+ * why. npm itself refuses a manifest it cannot parse, so a tree with one is
+ * already broken; the reader's job is to say so, not to proceed around it.
+ */
+import { readFileSync } from 'node:fs';
+import { isPathAbsentError } from '@vibe-agent-toolkit/utils';
+/**
+ * The parsed manifest, or `undefined` when there is none at `pkgPath`.
+ *
+ * @throws {Error} naming the file when it exists but is not a JSON object;
+ *   the parse error is the `cause`.
+ * @throws whatever the filesystem threw for anything that is not an absence
+ *   (a refusal stays a refusal).
+ */
+export function readPackageJsonOrAbsent(pkgPath) {
+    let raw;
+    try {
+        raw = readFileSync(pkgPath, 'utf-8');
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return undefined;
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        throw new Error(`${pkgPath} is not valid JSON: ${error.message}`, { cause: error });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${pkgPath} is not a JSON object, so it is not a package manifest`);
+    }
+    return parsed;
+}
+//# sourceMappingURL=package-json.js.map

package/dist/utils/package-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-json.js","sourceRoot":"","sources":["../../src/utils/package-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC/C,MAAM,KAAK,CAAC;IACd,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,WAAW,CAAC;YAAE,MAAM,KAAK,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,uBAAuB,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,wDAAwD,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,MAAiC,CAAC;AAC3C,CAAC"}

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

@@ -0,0 +1,100 @@
+/**
+ * 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 CollectionConfig, type PopulationCache } from '@vibe-agent-toolkit/resources';
+import type { GitTracker } from '@vibe-agent-toolkit/utils/git';
+import type { Logger } from './logger.js';
+/**
+ * The population arguments {@link populationWiring} supplies.
+ *
+ * Spread into a builder's options object, so the three optional inputs 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;
+    collections?: Readonly<Record<string, CollectionConfig>> | 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
+ * @param root - The project root, from which the run's declared `mimeType`
+ *   routing is READ rather than passed. See {@link collectionsOption}
+ * @returns The options to spread into the population builder's argument
+ */
+export declare function populationWiring(logger: Logger, gitTracker: GitTracker | undefined, cache: PopulationCache | undefined, root: string): PopulationWiring;
+/**
+ * The project's collection declarations at `root`, or undefined for a project
+ * that declares none.
+ *
+ * ## Why this is READ here and not passed in
+ *
+ * A declared `mimeType` changes which parser runs, which changes the content
+ * key, which is folded into the projection store's key through the routing's
+ * fingerprint. So two lanes of ONE command that disagree about whether to supply
+ * the declarations do not merely disagree about parsing — they **evict each
+ * other's stored extents over an unchanged tree, run after run.**
+ *
+ * Taking a `root` and reading the config here rather than accepting a
+ * `collections` argument is what makes that disagreement unrepresentable: there
+ * is one answer per root and every lane that goes through this helper gets it.
+ * An optional argument would have been a thing three call sites could each
+ * forget, and forgetting is silent — a cache that never hits looks exactly like
+ * a cache that is merely cold.
+ *
+ * `loadConfigCached` is keyed on the root, so the repeat calls across a
+ * command's lanes cost one parse between them. A broken config throws here, as
+ * it does everywhere else — a population silently typed by the built-in tables
+ * because the config would not parse is the conflation
+ * {@link loadConfigCached} exists to refuse.
+ *
+ * Returned as a SPREADABLE rather than a value: `exactOptionalPropertyTypes`
+ * makes an absent key and one holding `undefined` different arguments, and the
+ * population builders declare `collections` optional. Every caller spreads this,
+ * so no call site writes its own `!== undefined &&` and none can get the two
+ * states the wrong way round.
+ *
+ * @param root - The project root whose config declares the collections
+ * @returns `{ collections }`, or `{}` when there is no config or no
+ *   `resources.collections` in it
+ */
+export declare function collectionsOption(root: string): {
+    collections?: Readonly<Record<string, CollectionConfig>>;
+};
+//# 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,EAEL,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAGhE,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;IACpC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,GAAG,SAAS,CAAC;CACtE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,KAAK,EAAE,eAAe,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,GACX,gBAAgB,CAUlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GACX;IAAE,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAA;CAAE,CAG9D"}

package/dist/utils/population-wiring.js

@@ -0,0 +1,98 @@
+/**
+ * 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';
+import { loadConfigCached } from './config-loader.js';
+/**
+ * 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
+ * @param root - The project root, from which the run's declared `mimeType`
+ *   routing is READ rather than passed. See {@link collectionsOption}
+ * @returns The options to spread into the population builder's argument
+ */
+export function populationWiring(logger, gitTracker, cache, root) {
+    return {
+        onBlobPopulation: (report) => {
+            const refusals = describeBlobRefusals(report);
+            if (refusals !== undefined)
+                logger.warn(refusals);
+        },
+        ...(gitTracker !== undefined && { gitTracker }),
+        ...(cache !== undefined && { cache }),
+        ...collectionsOption(root),
+    };
+}
+/**
+ * The project's collection declarations at `root`, or undefined for a project
+ * that declares none.
+ *
+ * ## Why this is READ here and not passed in
+ *
+ * A declared `mimeType` changes which parser runs, which changes the content
+ * key, which is folded into the projection store's key through the routing's
+ * fingerprint. So two lanes of ONE command that disagree about whether to supply
+ * the declarations do not merely disagree about parsing — they **evict each
+ * other's stored extents over an unchanged tree, run after run.**
+ *
+ * Taking a `root` and reading the config here rather than accepting a
+ * `collections` argument is what makes that disagreement unrepresentable: there
+ * is one answer per root and every lane that goes through this helper gets it.
+ * An optional argument would have been a thing three call sites could each
+ * forget, and forgetting is silent — a cache that never hits looks exactly like
+ * a cache that is merely cold.
+ *
+ * `loadConfigCached` is keyed on the root, so the repeat calls across a
+ * command's lanes cost one parse between them. A broken config throws here, as
+ * it does everywhere else — a population silently typed by the built-in tables
+ * because the config would not parse is the conflation
+ * {@link loadConfigCached} exists to refuse.
+ *
+ * Returned as a SPREADABLE rather than a value: `exactOptionalPropertyTypes`
+ * makes an absent key and one holding `undefined` different arguments, and the
+ * population builders declare `collections` optional. Every caller spreads this,
+ * so no call site writes its own `!== undefined &&` and none can get the two
+ * states the wrong way round.
+ *
+ * @param root - The project root whose config declares the collections
+ * @returns `{ collections }`, or `{}` when there is no config or no
+ *   `resources.collections` in it
+ */
+export function collectionsOption(root) {
+    const collections = loadConfigCached(root)?.resources?.collections;
+    return collections === undefined ? {} : { collections };
+}
+//# 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,EACL,oBAAoB,GAIrB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAiBtD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,UAAkC,EAClC,KAAkC,EAClC,IAAY;IAEZ,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;QACrC,GAAG,iBAAiB,CAAC,IAAI,CAAC;KAC3B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY;IAEZ,MAAM,WAAW,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC;IACnE,OAAO,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;AAC1D,CAAC"}

package/dist/utils/project-root-policy.d.ts

@@ -30,4 +30,24 @@ export declare function projectRootOrLoudCwd(startDir: string, logger: Logger):
  * `tolerate null` policy — return `string | null`; caller handles either case.
  */
 export declare function projectRootOrNull(startDir: string): string | null;
+/**
+ * Fail loudly on a `[path]` argument that names no directory.
+ *
+ * Every `resources` verb takes an optional `[path]`, and two things can be
+ * meant by it: a SCOPE (`scan`, `validate` — crawl this subtree) or a LOCATOR
+ * (`query`, `check` — find the project from here; the projection is always the
+ * whole tree). Both start by resolving the argument, and both must refuse one
+ * that resolves to nothing — the scoping verbs would otherwise degrade into a
+ * glob matching nothing (`filesScanned: 0`, green), and the locating verbs
+ * walked UP from the missing path to whatever project the cwd is in and
+ * answered about THAT tree at exit 0, byte-identical to a correct run.
+ *
+ * One function so the two families refuse with one message; a reader who saw
+ * `validate` say "Path does not exist" should get the same words from `query`.
+ *
+ * @param pathArg - The argument as typed, relative to cwd or absolute
+ * @returns The resolved absolute path
+ * @throws When it does not exist or is not a directory
+ */
+export declare function assertDirectoryArgument(pathArg: string): string;
 //# sourceMappingURL=project-root-policy.d.ts.map

package/dist/utils/project-root-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-root-policy.d.ts","sourceRoot":"","sources":["../../src/utils/project-root-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAShF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ7E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjE"}
+{"version":3,"file":"project-root-policy.d.ts","sourceRoot":"","sources":["../../src/utils/project-root-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAShF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ7E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAS/D"}

package/dist/utils/project-root-policy.js

@@ -12,6 +12,7 @@
  * `.action(...)` callbacks). Inner library functions should take the resolved
  * root as a parameter — never call `findProjectRoot` themselves.
  */
+import { existsSync, statSync } from 'node:fs';
 import { findProjectRoot, safePath } from '@vibe-agent-toolkit/utils';
 /**
  * `required` policy — refuse to run if no projectRoot can be discovered.
@@ -46,4 +47,33 @@ export function projectRootOrLoudCwd(startDir, logger) {
 export function projectRootOrNull(startDir) {
     return findProjectRoot(startDir);
 }
+/**
+ * Fail loudly on a `[path]` argument that names no directory.
+ *
+ * Every `resources` verb takes an optional `[path]`, and two things can be
+ * meant by it: a SCOPE (`scan`, `validate` — crawl this subtree) or a LOCATOR
+ * (`query`, `check` — find the project from here; the projection is always the
+ * whole tree). Both start by resolving the argument, and both must refuse one
+ * that resolves to nothing — the scoping verbs would otherwise degrade into a
+ * glob matching nothing (`filesScanned: 0`, green), and the locating verbs
+ * walked UP from the missing path to whatever project the cwd is in and
+ * answered about THAT tree at exit 0, byte-identical to a correct run.
+ *
+ * One function so the two families refuse with one message; a reader who saw
+ * `validate` say "Path does not exist" should get the same words from `query`.
+ *
+ * @param pathArg - The argument as typed, relative to cwd or absolute
+ * @returns The resolved absolute path
+ * @throws When it does not exist or is not a directory
+ */
+export function assertDirectoryArgument(pathArg) {
+    const resolved = safePath.resolve(pathArg);
+    if (!existsSync(resolved)) {
+        throw new Error(`Path does not exist: ${resolved}`);
+    }
+    if (!statSync(resolved).isDirectory()) {
+        throw new Error(`Path is not a directory: ${resolved}`);
+    }
+    return resolved;
+}
 //# sourceMappingURL=project-root-policy.js.map

package/dist/utils/project-root-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"project-root-policy.js","sourceRoot":"","sources":["../../src/utils/project-root-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAItE;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,WAAmB;IACtE,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,GAAG,WAAW,gEAAgE;YAC5E,kDAAkD,CACrD,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB,EAAE,MAAc;IACnE,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,CAAC,IAAI,CACT,oEAAoE,GAAG,iBAAiB,CACzF,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"project-root-policy.js","sourceRoot":"","sources":["../../src/utils/project-root-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAItE;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,WAAmB;IACtE,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,GAAG,WAAW,gEAAgE;YAC5E,kDAAkD,CACrD,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB,EAAE,MAAc;IACnE,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,CAAC,IAAI,CACT,oEAAoE,GAAG,iBAAiB,CACzF,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,wBAAwB,QAAQ,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}