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

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

@@ -0,0 +1,335 @@
+/**
+ * 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 * as ProjectionSqlite from '@vibe-agent-toolkit/projection-sqlite';
+import type { PopulationCache } from '@vibe-agent-toolkit/resources';
+/**
+ * The env var that selects — or now, DESELECTS — a projection store for this
+ * process.
+ *
+ * 🔑 **The store is on by default, so this is the escape hatch rather than the
+ * selector.** Same shape and same reason as `VAT_RESOURCES_CRAWL`: any value the
+ * off-parser does not read as false leaves the store selected, including the
+ * historical `sqlite`, so every script and lab arm that names it explicitly
+ * keeps working and keeps MEANING the same thing. See
+ * {@link PROJECTION_STORE_OFF} for the one way out.
+ *
+ * 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 **every phase now runs in the process
+ * that read it**, so `vat validate`'s phases cannot fail to see the selection
+ * their orchestrator did. Which lanes share a store within one verb and across
+ * invocations, with the measurements, and the ⚠️ one packaging enumeration still
+ * on the walk: `docs/architecture/resource-scanning-and-caching.md` §3.7.
+ */
+export declare const PROJECTION_STORE_ENV = "VAT_PROJECTION_STORE";
+/**
+ * {@link PROJECTION_STORE_ENV}'s value that names the SQLite backend. Redundant
+ * with the default now, and kept — see
+ * `docs/architecture/resource-scanning-and-caching.md` §3.7.
+ */
+export declare const PROJECTION_STORE_SQLITE = "sqlite";
+/**
+ * The value that turns the store OFF while leaving VAT's other caches on.
+ *
+ * Read through the same {@link parseEnvBoolean} as every other VAT switch, so
+ * `0`, `false`, `no` and `n` work too. The empty string joins them: unlike
+ * {@link PROJECTION_STORE_DIR_ENV}, where empty falls back to a default
+ * directory that means something, there is nothing else for a cleared selector
+ * to mean.
+ */
+export declare const PROJECTION_STORE_OFF = "off";
+/**
+ * Where the projection store's database lives, overriding the default.
+ *
+ * The default is `tmpdir/.vat-cache/<version>/projection-<shapeDigest>` — one
+ * database per VAT release, shared by every root on the machine. This names a
+ * different one **explicitly**, which is what an adopter with a per-job cache
+ * directory, a shared build agent running two jobs at once, or a test arm that
+ * must not touch the developer's live cache actually needs.
+ *
+ * 🪤 **What it replaces is redirecting `TMPDIR`, which works and is the wrong
+ * instrument.** `defaultStoreDirectory()` resolves through
+ * `vatCacheNamespaceRoot()` → `normalizedTmpdir()`, so pointing the OS temp
+ * directory elsewhere does move the store — along with every other temp
+ * consumer in the process, on a variable whose name is not the same on both
+ * platforms (`TMPDIR` on POSIX; `TEMP`, then `TMP`, on Windows, so setting one
+ * is silently inert on the other). It relocates the store as a side effect of
+ * relocating something larger. This variable says the one thing meant.
+ *
+ * ⚠️ It does **not** consult `XDG_CACHE_HOME` or `HOME`. A caller that set
+ * those believed it had its own database and was writing into the shared one;
+ * the fix is to name the directory here, not to add more implicit roots.
+ *
+ * An environment variable rather than a config field, for the same reason
+ * {@link PROJECTION_STORE_ENV} is one: it says where an INSTRUMENT keeps its
+ * scratch space, not what the project means, and it has to be reachable from a
+ * harness that spawns the binary.
+ */
+export declare const PROJECTION_STORE_DIR_ENV = "VAT_PROJECTION_STORE_DIR";
+/**
+ * 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";
+/**
+ * Whether this process should read and write a projection store.
+ *
+ * **On unless turned off.** It used to be the opposite; the measurement that
+ * paid for the flip, and the blob-tier bound that had to land first, are in
+ * `docs/architecture/resource-scanning-and-caching.md` §3.7.
+ *
+ * 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} turns off THIS cache; {@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.
+ *
+ * 🪤 Read through `parseEnvBoolean`, never for truthiness — `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. It was previously a comparison against the
+ * literal `'0'`, which is the same shape `ParseCache` carried and the same
+ * defect: `VAT_CACHE=false` disabled nothing. The two now share one parser
+ * (`@vibe-agent-toolkit/utils`) so the variable cannot be read two ways again.
+ *
+ * Only an explicit `false` vetoes. `parseEnvBoolean` returns `undefined` for a
+ * value it cannot read, and an unreadable value is not something the operator
+ * said — the veto has to be a statement, not a shrug. That reading is why both
+ * variables can be read through ONE parser even though they now sit on
+ * opposite default sides: each asks only whether the operator SAID no.
+ *
+ * @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.
+ *
+ * ⚠️ **Deliberately NOT typed for SQL, and do not re-widen it.** This handle
+ * reaches the database at {@link PROJECTION_STORE_DIR_ENV}'s directory, which
+ * defaults to one file per VAT release shared by every root on the machine —
+ * holding other repositories' link text, heading text and frontmatter. A field
+ * typed `SqlQueryableStore` used to live here "for a caller that needs to ASK
+ * the store something", and that caller was removed precisely because arbitrary
+ * SQL over this store answers from trees the asker never named. `populate()`
+ * needs the engine-free {@link PopulationCache} and nothing more; a query lane
+ * builds its own store (see `projection-query.ts`).
+ */
+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: the store is on unless a user turned it
+ * off, and answering that by silently not having one is how a default-on 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>;
+/**
+ * Open a store that lives only in this process's memory.
+ *
+ * 🔑 **This is what keeps the query surface an ANSWER rather than a privilege.**
+ * A caller with no store selected — CI's first run, or a developer who never set
+ * the selector — still gets the same SQL over the same schema; the on-disk store
+ * only makes the second run cheap. Without it, "what does this tree contain"
+ * would be answerable only where a cache happened to exist, and two callers
+ * would hold differently-shaped views of one tree.
+ *
+ * It is a cache that cannot hit: nothing survives the close, so a caller must
+ * write the projection into it before asking anything.
+ *
+ * @returns An open, empty store; close it when done
+ */
+export declare function openEphemeralQueryStore(): Promise<ProjectionSqlite.SqlQueryableStore>;
+/**
+ * Open a compile-only probe over the full queryable schema, derived relations
+ * included — for checking statements BEFORE any population or lens has run.
+ *
+ * ⚠️ Not {@link openEphemeralQueryStore}: that store has no table for a derived
+ * relation until a lens fills it, which is how an unevaluated one is refused.
+ *
+ * @returns An open probe; close it when done
+ */
+export declare function openCompileProbe(): Promise<ProjectionSqlite.ProjectionCompileProbe>;
+/**
+ * The legible failure for "your Node is too old", or `undefined` when this is
+ * some other failure — including "the package is absent".
+ *
+ * Exported, and returning the error rather than throwing it, so the DIAGNOSIS
+ * is unit-testable without a mocked dynamic import. A test cannot make a mocked
+ * `import()` reject with a plain `{ code }` — the test runner wraps whatever a
+ * module factory throws in its own error, so the code never survives to be
+ * read — and the branch's whole value is the message it produces.
+ *
+ * 🪤 The two are **different error codes**, and only one of them reaches
+ * {@link isModuleMissing}. `@vibe-agent-toolkit/projection-sqlite` imports
+ * `node:sqlite`, which loads unflagged from Node 22.13.0 (it was added in 22.5.0
+ * behind `--experimental-sqlite`); on 22.0–22.12 an ordinary import fails
+ * with `ERR_UNKNOWN_BUILTIN_MODULE`, not `ERR_MODULE_NOT_FOUND`. Without this
+ * branch the user gets a bare `No such built-in module: node:sqlite` — which
+ * names neither the version floor nor the fix.
+ *
+ * ⚠️ It is reachable on an ordinary run and is not a corner: the query lane has
+ * always fallen back to {@link openEphemeralQueryStore} when no store is
+ * selected, which is the default, so `node:sqlite` is required on a default
+ * `vat resources query` whichever way the lane resolves its store.
+ *
+ * 🪤 This used to say "EVERY `vat resources query`/`check` run", and that was
+ * too strong for `check`. Measured against the built CLI on Node v24.13.1 by
+ * counting the `ExperimentalWarning` `node:sqlite` emits at load — the only
+ * externally visible tell that the module was reached at all:
+ *
+ * | Command | Warnings | Backend loaded? |
+ * |---|---|---|
+ * | `vat resources query "SELECT …"` | 1 | yes |
+ * | `vat resources check`, no checks declared | 0 | **no** |
+ *
+ * `check` reaches a store only when the project declares checks for it to
+ * evaluate, so a repo with none never loads the backend and never needed the
+ * floor for that command. The floor argument is unaffected — `query` alone
+ * establishes it — but "every default run of those two commands" was a claim
+ * nothing had counted.
+ *
+ * ✅ **VAT's declared floor is now `>=22.13.0`, so this no longer fires on a
+ * SUPPORTED Node.** It used to: the manifests said `>=22.0.0` while these two
+ * commands could not run below 22.13.0, which meant thirteen Node patch
+ * releases were advertised as supported and hard-failed here. The floor was
+ * raised to stop advertising what VAT cannot do. The branch stays load-bearing
+ * for the Node that is merely *installed* rather than supported — `engines` is
+ * a warning in npm and nothing at all under most runners, so a user on 22.4
+ * still reaches this and still deserves to be told which number is wrong.
+ *
+ * The repair stays distinct from the missing-package one on purpose:
+ * "install this package" is the wrong instruction for "upgrade Node", and
+ * sending someone round that loop cannot terminate.
+ *
+ * @param error - Whatever the dynamic import threw
+ * @returns The error to raise when Node itself lacks the builtin; `undefined`
+ *   when this failure is something else and the caller should keep diagnosing
+ */
+export declare function nodeSqliteFloorFailure(error: unknown): Error | 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
+ * in the body.
+ *
+ * `undefined` on a run with no store selected, which is the shape every
+ * population lane wants: no store means re-derive, not fail.
+ *
+ * ⚠️ A caller that wants to run SQL must NOT query this store. It is one
+ * database per VAT release, shared by every root on the machine, so arbitrary
+ * SQL over it answers from other repositories — see `projection-query.ts`.
+ * That is also why this is the ONLY scope over the opened store: there is no
+ * separate "opened handle" bracket for a caller wanting more than the cache,
+ * because there is nothing legitimate for such a caller to want.
+ *
+ * ## 🔑 It NESTS, and the outermost scope wins
+ *
+ * A scope opened inside another over the same repository **joins** it: same
+ * cache by identity, no second database, no second `git write-tree`, and the
+ * inner scope does not close what it did not open. That lets an orchestrator
+ * hold one bracket over a whole run (`vat validate` does) while each lane
+ * underneath keeps its own and stays correct run alone. Reuse is gated on the
+ * TREE HASH, never on "a scope is open" — see {@link joinableCache}.
+ *
+ * ⚠️ The whole nest shares ONE snapshot, so work that must see its own edits as
+ * they land must not run inside a single scope. That is why a hoist is a
+ * decision rather than a refactor.
+ *
+ * @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;AAIH,OAAO,KAAK,KAAK,gBAAgB,MAAM,uCAAuC,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,+BAA+B,CAAC;AAOtF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,QAAQ,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,cAAc,CAAC;AAmBrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CASjD;AAED;;;;;;;;;;;;GAYG;AACH,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,CA6B7C;AA2BD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAE3F;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC,sBAAsB,CAAC,CAEzF;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAmBxE;AAgFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;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,CA4BZ"}