@dereekb/dbx-cli 14.0.1 → 14.2.0

package/src/lib/cache/data-cache.fingerprint.d.ts

@@ -0,0 +1,109 @@
+import { type Maybe } from '@dereekb/util';
+/**
+ * Number of hex characters of the SHA-256 digest kept as a fingerprint.
+ *
+ * 16 hex chars is 64 bits of the digest. The namespace being distinguished is "the filters one
+ * developer ran against one env for one dataset", so 64 bits is far past the point where a collision
+ * is a practical concern, and a short fingerprint keeps a cache path readable.
+ */
+export declare const CLI_DATA_CACHE_FINGERPRINT_LENGTH = 16;
+/**
+ * Normalizes a filter into its canonical comparison form.
+ *
+ * The point is that two filters a human would call "the same" produce the SAME fingerprint:
+ *
+ * - `null`, `undefined`, `''`, and empty arrays are DROPPED, so `{}`, `{ agentId: undefined }`, and
+ *   `{ tg: [] }` all normalize to `{}`. That is what makes the very common unfiltered export share
+ *   one cache entry no matter which flags were left off.
+ * - Object keys are sorted, so key order in a literal never matters.
+ * - Arrays are sorted, because every filter array in practice names a SET (tags, regions, uids,
+ *   requirement keys). A filter whose array order is meaningful must not be normalized through here.
+ * - `Date`s become ISO strings, so a `Date` and the string it serializes to agree.
+ *
+ * @param filter - The filter value to normalize.
+ * @returns The canonical form, or `undefined` when the value drops out entirely.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function normalizeCliCacheFilter(filter: unknown): unknown;
+/**
+ * Renders a normalized value as deterministic JSON.
+ *
+ * Object keys are sorted here as well as in {@link normalizeCliCacheFilter} so the function is
+ * order-stable on its own — it is also used to sort array members, which happens before the
+ * enclosing object's keys have been walked.
+ *
+ * @param value - The value to render. Expected to already be normalized.
+ * @returns The canonical JSON rendering.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function canonicalCliCacheJson(value: unknown): string;
+/**
+ * Input for {@link cliCacheFingerprint}.
+ */
+export interface CliCacheFingerprintInput {
+    /**
+     * Identifier of the cached pipeline stage, e.g. `worker.lineDetails`.
+     */
+    readonly dataset: string;
+    /**
+     * The stage's shape/behavior version. Bumping it invalidates every entry for that dataset in one
+     * shot — required whenever the stage's output shape OR the code that builds it changes, because a
+     * stage rebuilt by newer code is a wrong-output bug rather than a slow one.
+     */
+    readonly datasetVersion: number;
+    /**
+     * The env the data was read from. Never omitted: the same filter against staging and prod are
+     * different data.
+     */
+    readonly env: string;
+    /**
+     * The inputs the stage's contents depend on. MUST exclude anything applied after the stage —
+     * output format, export flavour, destination file, and any row filter the pipeline applies in
+     * memory downstream.
+     */
+    readonly filter?: Maybe<unknown>;
+}
+/**
+ * Builds the fingerprint identifying one build of one dataset.
+ *
+ * @param input - The fingerprint inputs.
+ * @param input.dataset - Identifier of the cached pipeline stage.
+ * @param input.datasetVersion - The stage's shape/behavior version.
+ * @param input.env - The env the data was read from.
+ * @param input.filter - The inputs the stage's contents depend on.
+ * @returns The first {@link CLI_DATA_CACHE_FINGERPRINT_LENGTH} hex characters of the SHA-256 digest.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliCacheFingerprint(input: CliCacheFingerprintInput): string;
+/**
+ * Builds the index key one cache entry is stored under.
+ *
+ * @param input - The key parts.
+ * @param input.env - The env the data was read from.
+ * @param input.dataset - Identifier of the cached pipeline stage.
+ * @param input.fingerprint - The fingerprint from {@link cliCacheFingerprint}.
+ * @returns The `<env>/<dataset>/<fingerprint>` index key.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliDataCacheKey(input: {
+    readonly env: string;
+    readonly dataset: string;
+    readonly fingerprint: string;
+}): string;
+/**
+ * Sanitizes one path segment of a cache file path.
+ *
+ * A dataset id is developer-authored (`worker.lineDetails`, `firestore-query:workers-query`), so it
+ * can carry characters — a `:` most notably — that are illegal in a filename on some platforms.
+ * Mirrors what the lint cache does to a project name.
+ *
+ * @param segment - The raw segment.
+ * @returns The segment with every character outside `[A-Za-z0-9._-]` replaced by `_`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliDataCachePathSegment(segment: string): string;

package/src/lib/cache/data-cache.options.d.ts

@@ -0,0 +1,98 @@
+import { type Hours, type Maybe, type Milliseconds } from '@dereekb/util';
+/**
+ * Max age applied by a bare `--cache` with no explicit hour count.
+ *
+ * A day, because the exports this cache exists for are reporting reads whose underlying data moves
+ * on a human timescale — and because a default that is obviously conservative is easier to reason
+ * about than one tuned per dataset.
+ */
+export declare const DEFAULT_CLI_DATA_CACHE_MAX_AGE_HOURS: Hours;
+/**
+ * Names of the global cache options registered by `createCli`, so manifest commands can hide them
+ * from a focused `--help` alongside the other standard globals.
+ */
+export declare const CLI_DATA_CACHE_GLOBAL_OPTION_NAMES: readonly string[];
+/**
+ * The resolved cache policy for one CLI invocation.
+ *
+ * Reads and writes are separate on purpose: recording a build is what makes "when was this data last
+ * built" automatic and free, while READING a recorded build is opt-in, so no plain command ever
+ * silently returns data that is not live.
+ */
+export interface CliDataCacheOptions {
+    /**
+     * Whether a recorded build may satisfy this run.
+     */
+    readonly read: boolean;
+    /**
+     * Whether this run records what it builds.
+     */
+    readonly write: boolean;
+    /**
+     * How old a recorded build may be and still satisfy this run. `undefined` means no age limit —
+     * any recorded build is acceptable.
+     */
+    readonly maxAgeMs?: Maybe<Milliseconds>;
+}
+/**
+ * The default policy: record every build, read none of them back.
+ */
+export declare const DEFAULT_CLI_DATA_CACHE_OPTIONS: CliDataCacheOptions;
+/**
+ * The policy `--no-cache` selects: neither read nor record.
+ */
+export declare const DISABLED_CLI_DATA_CACHE_OPTIONS: CliDataCacheOptions;
+/**
+ * Publishes the resolved cache policy for the current invocation.
+ *
+ * Called from the output middleware, which runs for config and API commands alike.
+ *
+ * @param options - The resolved policy.
+ */
+export declare function configureCliDataCacheOptions(options: CliDataCacheOptions): void;
+/**
+ * Returns the cache policy for the current invocation.
+ *
+ * @returns The resolved policy, or {@link DEFAULT_CLI_DATA_CACHE_OPTIONS} when the middleware has
+ * not run (a programmatic caller, or a test driving a handler directly).
+ */
+export declare function cliDataCacheOptions(): CliDataCacheOptions;
+/**
+ * The shape the `--cache` / `--refresh` flags parse into.
+ *
+ * `cache` is declared to yargs as a string so `--cache` and `--cache=<hours>` are both accepted;
+ * yargs' boolean negation then turns `--no-cache` into `false` on the same key.
+ */
+export interface CliDataCacheArgv {
+    readonly cache?: Maybe<string | false>;
+    readonly refresh?: Maybe<boolean>;
+}
+/**
+ * Validates the `--cache` flag at parse time.
+ *
+ * Registered as a yargs `.check` rather than left to the middleware because a bare `--cache`
+ * immediately before a positional swallows it (`firestore-query --cache workers-query` parses as
+ * `cache: 'workers-query'` with no query). Failing loudly on a non-numeric value is what turns that
+ * into a clear message instead of a mysteriously empty result.
+ *
+ * @param argv - The parsed argv.
+ * @returns `true` when the flag is well-formed.
+ * @throws {Error} When `--cache` carries a value that is not a non-negative number.
+ */
+export declare function checkCliDataCacheArgv(argv: CliDataCacheArgv): boolean;
+/**
+ * Resolves the cache policy from parsed argv.
+ *
+ * Precedence, highest first:
+ * 1. `--refresh` — rebuild and overwrite. Beats `--cache`, so a wrapper script that always passes
+ *    `--cache` can still be forced fresh from the command line.
+ * 2. `--no-cache` — neither read nor record.
+ * 3. `--cache[=<hours>]` — read a build within the age limit. `--cache=0` accepts any age.
+ * 4. Nothing — record only.
+ *
+ * @param argv - The parsed argv.
+ * @returns The resolved policy.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function resolveCliDataCacheOptions(argv: CliDataCacheArgv): CliDataCacheOptions;

package/src/lib/cache/index.d.ts

@@ -0,0 +1,5 @@
+export * from './cache.command.factory';
+export * from './data-cache';
+export * from './data-cache.codec';
+export * from './data-cache.fingerprint';
+export * from './data-cache.options';

package/src/lib/config/paths.d.ts

@@ -6,6 +6,15 @@ export interface CliPaths {
     readonly configFilePath: string;
     readonly tokenCachePath: string;
     readonly firestoreSessionCachePath: string;
+    /**
+     * Directory holding the recorded query/export dataset cache — an index file plus one payload file
+     * per recorded build.
+     *
+     * A directory rather than a single file because a payload here is a whole dataset (a 20k-row
+     * export), not the handful of fields the token and session caches hold: one file per build is what
+     * keeps listing the cache from having to read all of it.
+     */
+    readonly dataCacheDir: string;
 }
 export interface CliPathsConfig {
     /**
@@ -26,11 +35,12 @@ export interface CliPathsConfig {
  *   - `<configDir>/config.json` — the persistent CLI config (envs, output settings)
  *   - `<configDir>/.tokens.json` — per-env access/refresh token cache (mode 0600)
  *   - `<configDir>/.firestore-sessions.json` — per-env direct-Firestore session cache (mode 0600)
+ *   - `<configDir>/cache/` — recorded query/export dataset cache (mode 0600 throughout)
  *
  * @param config - The path-building inputs.
  * @param config.cliName - The CLI's binary name; the default config dir is `~/.<cliName>`.
  * @param config.configDirOverride - Optional override that replaces the default config directory verbatim (used by tests).
- * @returns The {@link CliPaths} pointing at `configDir`, the config file, the token cache file, and the Firestore session cache file.
+ * @returns The {@link CliPaths} pointing at `configDir`, the config file, the token cache file, the Firestore session cache file, and the dataset cache directory.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function buildCliPaths(config: CliPathsConfig): CliPaths;

package/src/lib/firestore/firestore-query.command.d.ts

@@ -1,14 +1,38 @@
+import { type Maybe } from '@dereekb/util';
 import type { CommandModule } from 'yargs';
+import { type CliDataCache } from '../cache/data-cache';
 import { type CliFirestoreQueryManifest } from '../manifest/types';
 /**
  * Default command name for the Firestore query execution command.
  */
 export declare const DEFAULT_FIRESTORE_QUERY_COMMAND_NAME = "firestore-query";
+/**
+ * Dataset id prefix under which a `firestore-query` run records its result.
+ *
+ * One dataset per catalog slug, so `cache list` reads as a list of queries rather than one
+ * undifferentiated blob.
+ */
+export declare const CLI_FIRESTORE_QUERY_DATASET_PREFIX = "firestore-query";
+/**
+ * Version of the recorded `firestore-query` payload.
+ *
+ * Bump when the result envelope's shape changes, or when the row projection changes what it decodes
+ * — a recorded build from older code is a wrong-answer bug, not just a slow one.
+ */
+export declare const CLI_FIRESTORE_QUERY_DATASET_VERSION = 1;
 /**
  * Options accepted by {@link buildFirestoreQueryCommand}.
  */
 export interface BuildFirestoreQueryCommandOptions {
     readonly commandName?: string;
+    /**
+     * The dataset cache recorded runs are written to and `--cache` reads from.
+     *
+     * Supplied by `createCli` so the `cache` command group and this command share ONE instance (and
+     * so a test can point both at a temp directory). Omitted, it falls back to the CLI's own
+     * `<configDir>/cache`.
+     */
+    readonly dataCache?: Maybe<CliDataCache>;
 }
 /**
  * Builds the top-level `firestore-query <query>` command.
@@ -17,7 +41,7 @@ export interface BuildFirestoreQueryCommandOptions {
  * as the authenticated user.
  *
  * @param manifest - The generated Firestore query manifest.
- * @param options - Optional command-name override.
+ * @param options - Optional command-name override and the shared dataset cache.
  * @returns A yargs `CommandModule` for `runCli({ apiCommands })`.
  *
  * @__NO_SIDE_EFFECTS__

package/src/lib/index.d.ts

@@ -1,6 +1,7 @@
 export * from './action';
 export * from './api';
 export * from './auth';
+export * from './cache';
 export * from './config';
 export * from './context';
 export * from './doctor';

package/src/lib/runner/run.d.ts

@@ -1,5 +1,6 @@
 import { type Argv, type CommandModule } from 'yargs';
 import { type ActionCommandSpec } from '../action/action.command.factory';
+import { type CreateCacheCommandInput } from '../cache/cache.command.factory';
 import { type CliEnvDefault } from '../config/env';
 import { type CliContext } from '../context/cli.context';
 import { type DoctorCheck } from '../doctor/doctor.command.factory';
@@ -127,6 +128,15 @@ export interface CreateCliInput extends CliLifecycleHooks {
      * Disable the built-in `firestore-get` command even when {@link firestore} is provided.
      */
     readonly disableFirestoreGet?: boolean;
+    /**
+     * Enables the recorded query/export dataset cache: the auth-free `cache` command group, and the
+     * `--cache` / `--refresh` global flags that `firestore-query` and app actions honour.
+     *
+     * Pass `true` for the defaults (`<configDir>/cache`, the CLI's `version` as the recorded build
+     * stamp), or an object to override the cache instance (tests point it at a temp dir), the build
+     * stamp, or the command name.
+     */
+    readonly dataCache?: boolean | Omit<CreateCacheCommandInput, 'cliName'>;
     /**
      * Test-only override that bypasses the auth middleware entirely and attaches the supplied
      * {@link CliContext} on every command invocation.
@@ -199,6 +209,7 @@ export interface CreateCliInput extends CliLifecycleHooks {
  *   if {@link CreateCliInput.modelManifest} is provided.
  * @param input.firestore - The app-supplied direct-Firestore binding; enables `firestore-get` / `firestore-query`.
  * @param input.firestoreQueryManifest - The generated Firestore query catalog; enables `firestore-queries`.
+ * @param input.dataCache - Enables the recorded dataset cache: the `cache` command group plus the `--cache` / `--refresh` global flags.
  * @param input.manifestGeneratorVersion - The `@dereekb/dbx-cli` version that emitted the app's generated
  *   manifests, for the built-in `cli-build-not-stale` doctor check.
  * @param input.setup - App hook run once before the command's handler; a throw aborts the command.

package/test/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "14.0.1",
+  "version": "14.2.0",
+  "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.0.1",
-    "@dereekb/dbx-cli": "14.0.1",
-    "@dereekb/firebase": "14.0.1",
-    "@dereekb/firebase-server/test": "14.0.1",
-    "@dereekb/model": "14.0.1",
-    "@dereekb/nestjs": "14.0.1",
-    "@dereekb/rxjs": "14.0.1",
-    "@dereekb/util": "14.0.1",
+    "@dereekb/date": "14.2.0",
+    "@dereekb/dbx-cli": "14.2.0",
+    "@dereekb/firebase": "14.2.0",
+    "@dereekb/firebase-server/test": "14.2.0",
+    "@dereekb/model": "14.2.0",
+    "@dereekb/nestjs": "14.2.0",
+    "@dereekb/rxjs": "14.2.0",
+    "@dereekb/util": "14.2.0",
     "@nestjs/common": "^12.0.1",
     "arktype": "^2.2.0",
     "vitest": "4.1.11",

package/validate/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/dbx-cli/validate",
-  "version": "14.0.1",
+  "version": "14.2.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.0.1",
-    "@dereekb/util": "14.0.1",
+    "@dereekb/dbx-cli": "14.2.0",
+    "@dereekb/util": "14.2.0",
     "ts-morph": "^28.0.0"
   }
 }