@vibe-agent-toolkit/cli 0.1.42 → 0.2.0-rc.10

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

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

@@ -0,0 +1,98 @@
+/**
+ * Which lenses a run evaluates, and when it does NOT — the selection that keeps
+ * the derived relations affordable.
+ *
+ * 🚨 **The selector over-selects on purpose: a FALSE NEGATIVE fails a run that
+ * had an answer.** A lens skipped when its relation is named leaves that
+ * relation ABSENT from the run's database, so the statement is refused with
+ * `no such table` — loud rather than wrong, because the refusal is SQLite's and
+ * does not depend on this scan. The cost that forced the selection, the rules
+ * that keep it fail-safe, and why the registry lives in the CLI rather than in a
+ * population are in
+ * `docs/architecture/zones.md` §2, "A lens is evaluated only when a statement
+ * names one of its relations".
+ */
+import { type DerivedTableName, type PopulationCache, type Projection } from '@vibe-agent-toolkit/resources';
+import type { Logger } from './logger.js';
+/**
+ * The rows one lens evaluation produced, keyed by `DERIVED_TABLES`' own keys.
+ *
+ * Structurally `projection-sqlite`'s `DerivedRows`, spelled here so every lens
+ * states its output in terms of the RELATION REGISTRY rather than of a storage
+ * backend. `writeDerived` accepts it unchanged.
+ */
+export type LensRows = {
+    readonly [Name in DerivedTableName]?: readonly Record<string, unknown>[];
+};
+/** Everything a lens may read while evaluating. */
+export interface LensEvaluationInput {
+    /** The resources-lane projection the run already populated. */
+    readonly projection: Projection;
+    /** Absolute corpus root, for a lens that must populate a lane of its own. */
+    readonly root: string;
+    /** Where a lens's own blob-stage refusals go — stderr. */
+    readonly logger: Logger;
+    /** The run's projection store, so a lens's own population can hit it. */
+    readonly cache: PopulationCache | undefined;
+}
+/** One lens: the relations it owns, and how to produce their rows. */
+export interface ProjectionLens {
+    /** How the lens names itself in `lensesEvaluated` and in a refusal. */
+    readonly name: string;
+    /**
+     * Every relation this lens produces, by registry key.
+     *
+     * ⛔ Disjoint from every other lens's. Two lenses claiming one relation would
+     * make "was it evaluated" unanswerable, and the second `writeDerived` would
+     * CLEAR the first's rows — `writeDerived` replaces a relation's contents.
+     */
+    readonly relations: readonly DerivedTableName[];
+    /**
+     * Produce the rows.
+     *
+     * @param input - The projection, the root, and the run's oracles
+     * @returns Every relation this lens owns — all of them, every time, because
+     *   omitting one leaves its previous contents in place
+     */
+    readonly evaluate: (input: LensEvaluationInput) => Promise<LensRows> | LensRows;
+}
+/** The authored-link lens: `lens_contexts`, `edges`, `edge_resolutions`. */
+export declare const AUTHORED_LINK_LENS: ProjectionLens;
+/** The always-loaded context lens: `claude_context_chains`, `claude_context_loads`. */
+export declare const CLAUDE_CONTEXT_LENS: ProjectionLens;
+/** Every lens the query lane can evaluate, in evaluation order. */
+export declare const PROJECTION_LENSES: readonly ProjectionLens[];
+/**
+ * The SQL names of a lens's relations. Read off `DERIVED_TABLES` rather than
+ * restated: the SQL name and the registry key are deliberately different
+ * vocabularies (`edgeResolutions` is spelled `edge_resolutions`), so a second
+ * copy here would be a rename waiting to be missed.
+ *
+ * @param lens - The lens
+ * @returns Its relations as SQL spells them
+ */
+export declare function lensRelationNames(lens: ProjectionLens): readonly string[];
+/**
+ * The lenses a run has to evaluate, given the statements it declared.
+ *
+ * @param statements - Every statement the run may ask, or `undefined` when the
+ *   caller cannot enumerate them. ⛔ `undefined` selects EVERY lens — see the
+ *   header on why the fail-safe direction is not negotiable
+ * @returns The lenses to evaluate, in {@link PROJECTION_LENSES} order
+ */
+export declare function lensesNamedBy(statements: readonly string[] | undefined): readonly ProjectionLens[];
+/**
+ * Evaluate one lens and hand back its rows, refusing any that are not exactly
+ * the relations it declares.
+ *
+ * `LensRows` makes every relation optional, so a lens that forgot one compiles —
+ * and `writeDerived` would leave that relation empty, a table that reads as a
+ * healthy tree. Checked here because this is the one place every lens passes.
+ *
+ * @param lens - The lens
+ * @param input - What it may read
+ * @returns Its rows
+ * @throws Error When the rows omit a declared relation or carry an undeclared one
+ */
+export declare function evaluateLens(lens: ProjectionLens, input: LensEvaluationInput): Promise<LensRows>;
+//# sourceMappingURL=projection-lenses.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projection-lenses.d.ts","sourceRoot":"","sources":["../../src/utils/projection-lenses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAkB,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAI7H,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAE,IAAI,IAAI,gBAAgB,CAAC,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;CACzE,CAAC;AAEF,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,CAAC;CAC7C;AAED,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC;CACjF;AAED,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,EAAE,cAIhC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,EAAE,cAIjC,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAGtD,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,MAAM,EAAE,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,SAAS,cAAc,EAAE,CAMlG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,QAAQ,CAAC,CAYnB"}