@dereekb/dbx-cli 14.1.0 → 14.3.0

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

@@ -0,0 +1,272 @@
+import { type ArrayOrValue, type Maybe, type Milliseconds } from '@dereekb/util';
+import { type CliDataCacheOptions } from './data-cache.options';
+/**
+ * Version of the on-disk index and payload envelopes.
+ *
+ * Bumped when the envelope shape itself changes. A payload written under a different schema version
+ * is a miss, not an error — see {@link CliDataCache.loadData}.
+ */
+export declare const CLI_DATA_CACHE_SCHEMA_VERSION = 1;
+/**
+ * Name of the index file inside the cache directory.
+ */
+export declare const CLI_DATA_CACHE_INDEX_FILE_NAME = "index.json";
+/**
+ * One recorded build of one dataset, as held in the index.
+ *
+ * The payload lives in its own file (see {@link file}) so listing the cache never has to read the
+ * data — mirroring the lint cache's per-project files plus an index roll-up.
+ */
+export interface CliDataCacheEntry {
+    /**
+     * Identifier of the cached pipeline stage, e.g. `worker.lineDetails`.
+     */
+    readonly dataset: string;
+    /**
+     * The stage version this build was produced by. An entry whose version no longer matches the
+     * caller's is a miss.
+     */
+    readonly datasetVersion: number;
+    /**
+     * The env the data was read from.
+     */
+    readonly env: string;
+    readonly fingerprint: string;
+    /**
+     * The NORMALIZED filter this build covers, stored verbatim so `cache list` can show what an entry
+     * is a build OF rather than just its digest.
+     */
+    readonly filter: unknown;
+    /**
+     * When the build was recorded, as an ISO string.
+     */
+    readonly builtAt: string;
+    /**
+     * Number of rows, when the cached value was an array. Absent for a non-array payload.
+     */
+    readonly itemCount?: Maybe<number>;
+    /**
+     * Size of the payload file in bytes.
+     */
+    readonly bytes: number;
+    /**
+     * Absolute path of the payload file.
+     */
+    readonly file: string;
+    /**
+     * The CLI build that produced the entry, when known.
+     *
+     * Recorded but deliberately NOT part of the fingerprint: fingerprinting on it would invalidate the
+     * whole cache on every rebuild of the CLI, which is exactly the workflow this feature is meant to
+     * speed up. `cache list` surfaces it so an entry from a different build is visible.
+     */
+    readonly cliBuildStamp?: Maybe<string>;
+}
+/**
+ * The persisted payload envelope.
+ */
+export interface CliDataCachePayloadFile {
+    readonly schemaVersion: number;
+    readonly dataset: string;
+    readonly datasetVersion: number;
+    readonly env: string;
+    readonly fingerprint: string;
+    readonly builtAt: string;
+    /**
+     * The cached value, encoded by the entry's codec.
+     */
+    readonly payload: unknown;
+}
+/**
+ * How a cached value is converted to and from the JSON written on disk.
+ *
+ * Defaults to the tagged structured codec, which needs no per-dataset work. A dataset whose value
+ * holds something the tagged codec cannot represent — a class instance whose identity matters —
+ * supplies its own.
+ */
+export interface CliDataCacheCodec<T> {
+    readonly toJson: (data: T) => unknown;
+    readonly fromJson: (raw: unknown) => T;
+}
+/**
+ * The default codec: the tagged structured JSON walk.
+ */
+export declare const DEFAULT_CLI_DATA_CACHE_CODEC: CliDataCacheCodec<any>;
+/**
+ * Narrowing filter accepted by {@link CliDataCache.listEntries} and {@link CliDataCache.removeEntries}.
+ */
+export interface CliDataCacheEntryFilter {
+    readonly env?: Maybe<string>;
+    readonly dataset?: Maybe<string>;
+    readonly fingerprint?: Maybe<string>;
+    /**
+     * Keep only entries built longer ago than this. Used by `cache prune`.
+     */
+    readonly olderThanMs?: Maybe<Milliseconds>;
+}
+/**
+ * Input for {@link CliDataCache.saveData}.
+ */
+export interface SaveCliDataCacheInput<T> {
+    readonly dataset: string;
+    readonly datasetVersion: number;
+    readonly env: string;
+    readonly filter?: Maybe<unknown>;
+    readonly data: T;
+    readonly codec?: Maybe<CliDataCacheCodec<T>>;
+}
+/**
+ * Input for {@link CliDataCache.loadData}.
+ */
+export interface LoadCliDataCacheInput<T> {
+    readonly dataset: string;
+    readonly datasetVersion: number;
+    readonly env: string;
+    readonly filter?: Maybe<unknown>;
+    readonly codec?: Maybe<CliDataCacheCodec<T>>;
+    /**
+     * Reject an entry built longer ago than this. Omit for no age limit.
+     */
+    readonly maxAgeMs?: Maybe<Milliseconds>;
+}
+/**
+ * A hit returned by {@link CliDataCache.loadData}.
+ */
+export interface CliDataCacheHit<T> {
+    readonly data: T;
+    readonly entry: CliDataCacheEntry;
+}
+/**
+ * On-disk store of recorded dataset builds.
+ */
+export interface CliDataCache {
+    /**
+     * The directory holding the index and every payload file.
+     */
+    readonly dataCacheDir: string;
+    /**
+     * Returns every recorded entry matching `filter`, newest build first.
+     */
+    listEntries(filter?: Maybe<CliDataCacheEntryFilter>): Promise<CliDataCacheEntry[]>;
+    /**
+     * Reads a recorded build, or `undefined` when there is no usable one.
+     *
+     * Any reason the entry cannot be used — absent, wrong `datasetVersion`, wrong schema version, past
+     * `maxAgeMs`, payload file missing, payload unparsable — is reported the same way: a miss, so the
+     * caller rebuilds. A cache is never allowed to turn into a failure.
+     */
+    loadData<T>(input: LoadCliDataCacheInput<T>): Promise<Maybe<CliDataCacheHit<T>>>;
+    /**
+     * Records a build, replacing any previous build of the same dataset + filter.
+     */
+    saveData<T>(input: SaveCliDataCacheInput<T>): Promise<CliDataCacheEntry>;
+    /**
+     * Removes every entry matching `filter` (and its payload file). Returns what was removed.
+     */
+    removeEntries(filter?: Maybe<CliDataCacheEntryFilter>): Promise<CliDataCacheEntry[]>;
+}
+export interface CreateCliDataCacheInput {
+    /**
+     * Directory holding the index and payload files, e.g. `~/.<cliName>/cache`.
+     */
+    readonly dataCacheDir: string;
+    /**
+     * Optional stamp identifying the CLI build, recorded on every entry it writes.
+     */
+    readonly cliBuildStamp?: Maybe<string>;
+}
+/**
+ * Creates the on-disk dataset cache.
+ *
+ * Layout, mirroring the lint cache's per-key files plus a versioned index roll-up:
+ *
+ * ```
+ * <dataCacheDir>/index.json                            the CliDataCacheEntry roll-up
+ * <dataCacheDir>/<env>/<dataset>/<fingerprint>.json    one CliDataCachePayloadFile per build
+ * ```
+ *
+ * Everything is written mode 0600. A cached export holds production rows — worker names, emails,
+ * billing lines — so the files are readable by the owning user only, the same posture as the token
+ * and Firestore-session caches next to them.
+ *
+ * @param input - The cache inputs.
+ * @param input.dataCacheDir - Directory holding the index and payload files.
+ * @param input.cliBuildStamp - Optional stamp identifying the CLI build, recorded on written entries.
+ * @returns The cache.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createCliDataCache(input: CreateCliDataCacheInput): CliDataCache;
+/**
+ * Whether a recorded build is too old to satisfy a read.
+ *
+ * @param entry - The entry to test.
+ * @param maxAgeMs - The age limit. `null`/`undefined` means no limit.
+ * @returns Whether the entry is past the limit.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isEntryExpired(entry: CliDataCacheEntry, maxAgeMs: Maybe<Milliseconds>): boolean;
+/**
+ * The outcome of {@link loadOrBuildCliCachedData}.
+ */
+export interface CliCachedDataResult<T> {
+    readonly data: T;
+    /**
+     * Whether `data` came off disk rather than from `build()`.
+     */
+    readonly fromCache: boolean;
+    readonly dataset: string;
+    readonly fingerprint: string;
+    readonly builtAt: Date;
+    /**
+     * How old the data is. Zero for a fresh build.
+     */
+    readonly ageMs: Milliseconds;
+    readonly itemCount?: Maybe<number>;
+}
+/**
+ * Input for {@link loadOrBuildCliCachedData}.
+ */
+export interface LoadOrBuildCliCachedDataInput<T> {
+    readonly cache: CliDataCache;
+    readonly dataset: string;
+    readonly datasetVersion: number;
+    readonly env: string;
+    /**
+     * The inputs this stage's contents depend on — and ONLY those. Anything applied after the stage
+     * (output format, export flavour, a row filter the pipeline applies downstream) must be left out,
+     * or changing it will needlessly miss.
+     */
+    readonly filter?: Maybe<unknown>;
+    /**
+     * The invocation's cache policy. Defaults to {@link DEFAULT_CLI_DATA_CACHE_OPTIONS} (record only).
+     */
+    readonly options?: Maybe<CliDataCacheOptions>;
+    readonly codec?: Maybe<CliDataCacheCodec<T>>;
+    /**
+     * Produces the data when no recorded build satisfies the run. Only called on a miss, which is what
+     * makes nesting these calls resolve a stage chain back-to-front: a hit on a late stage never runs
+     * the earlier stages at all.
+     */
+    readonly build: () => Promise<T>;
+}
+/**
+ * Reads a recorded build of a dataset, or produces and records one.
+ *
+ * @param input - The lookup + build inputs.
+ * @returns The data plus where it came from.
+ */
+export declare function loadOrBuildCliCachedData<T>(input: LoadOrBuildCliCachedDataInput<T>): Promise<CliCachedDataResult<T>>;
+/**
+ * Builds the `cache` provenance block for an output envelope's `meta`.
+ *
+ * Emitting it on every cached command is what lets a reader tell whether the bytes in front of them
+ * came off disk, and how old they are, without re-running anything.
+ *
+ * @param results - One result, or the per-stage results of a pipeline.
+ * @returns The meta block: one object for a single result, an array for several.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliDataCacheMeta(results: ArrayOrValue<CliCachedDataResult<unknown>>): Record<string, unknown>;

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/env.d.ts

@@ -1,4 +1,4 @@
-import { type Maybe } from '@dereekb/util';
+import { type Maybe, type OidcClientAuthMethod } from '@dereekb/util';
 import { type CliTokenEntry } from './token.cache';
 /**
  * The default OAuth/OIDC scopes requested by the CLI when none are configured.
@@ -15,7 +15,12 @@ export declare const MODEL_WRITE_OIDC_SCOPES: readonly ["model.create", "model.u
 /**
  * The default redirect URI used by the CLI.
  *
- * Opens up to nothing in the browser so the user can copy/paste the resulting token url back into the CLI.
+ * The `0` port is a placeholder, not a bindable port: the redirect resolves to nothing in the
+ * browser and the user copy/pastes the resulting URL back into the CLI.
+ *
+ * To have `auth login` capture the redirect automatically instead, configure a redirect URI with a
+ * concrete loopback port (e.g. `http://127.0.0.1:8976/callback`) and register that exact URI with
+ * the OAuth client — `auth login` binds it and reads the code straight out of the browser redirect.
  */
 export declare const DEFAULT_CLI_REDIRECT_URI = "http://127.0.0.1:0/callback";
 /**
@@ -193,6 +198,14 @@ export declare function isCliFirebaseConfigComplete(firebase: Maybe<CliFirebaseC
  * @returns `true` when emulators are configured and not explicitly disabled.
  */
 export declare function cliFirebaseEmulatorsInUse(firebase: Maybe<CliFirebaseConfig>): boolean;
+/**
+ * The OAuth client's registered `token_endpoint_auth_method`, as far as the CLI needs to model it.
+ *
+ * Wider than {@link OidcClientAuthMethod} by exactly one member: `'none'`, the public-client case.
+ * That value is meaningless to the protocol layer — a public client sends no credential, so there is
+ * no presentation to choose — but it is precisely what the CLI needs in order to stop asking for one.
+ */
+export type OidcCliTokenEndpointAuthMethod = OidcClientAuthMethod | 'none';
 /**
  * Environment-targeting config for a CLI invocation.
  *
@@ -231,12 +244,30 @@ export interface CliEnvConfig {
     readonly clientId?: string;
     /**
      * The OAuth client secret registered with the target app.
+     *
+     * Absent for a public client — see {@link tokenEndpointAuthMethod}.
      */
     readonly clientSecret?: string;
     /**
-     * The redirect URI registered with the OAuth client. The CLI does not bind a server — it parses
-     * the URL the user pastes back, so this can be any value the OIDC provider accepts as a
-     * registered redirect URI (e.g. `http://127.0.0.1:0/callback` or another loopback/placeholder URL).
+     * How the client authenticates at the token endpoint, mirroring the OAuth client's registered
+     * `token_endpoint_auth_method`.
+     *
+     * `'none'` marks a PUBLIC client: it holds no secret and proves itself with PKCE instead. Recording
+     * it lets `auth setup` skip the client-secret prompt outright rather than asking for a credential
+     * that must not exist — the prompt cannot infer this, since "no secret yet" and "never a secret"
+     * look identical from an empty config.
+     *
+     * Omit to leave it unknown, which keeps the existing prompt-and-accept-empty behaviour.
+     */
+    readonly tokenEndpointAuthMethod?: OidcCliTokenEndpointAuthMethod;
+    /**
+     * The redirect URI registered with the OAuth client.
+     *
+     * When this is an `http:` loopback URI with a concrete, non-zero port (e.g.
+     * `http://127.0.0.1:8976/callback`), `auth login` binds that port and reads the authorization code
+     * straight out of the browser redirect. Any other value — including the
+     * {@link DEFAULT_CLI_REDIRECT_URI} `:0` placeholder and out-of-band URNs — falls back to the user
+     * pasting the redirect URL back into the CLI.
      *
      * Defaults to {@link DEFAULT_CLI_REDIRECT_URI}.
      */
@@ -312,10 +343,15 @@ export declare function applyEnvVarOverrides(input: EnvVarOverrideInput): Maybe<
 /**
  * Returns true when the env has the minimum fields needed to attempt an OAuth login or token refresh.
  *
+ * `clientSecret` is NOT among them. A CLI is a public client in the usual case
+ * (`token_endpoint_auth_method: 'none'`), authenticating with PKCE rather than a secret, so requiring
+ * one here would report a correctly-configured public env as incomplete — and send the caller back to
+ * `auth setup` to supply a credential the provider would then reject.
+ *
  * @param env - The env config to check.
- * @returns `true` when `apiBaseUrl`, `oidcIssuer`, `clientId`, `clientSecret`, and `redirectUri` are all present and non-empty.
+ * @returns `true` when `apiBaseUrl`, `oidcIssuer`, `clientId`, and `redirectUri` are all present and non-empty.
  */
-export declare function isCliEnvConfigComplete(env: Maybe<CliEnvConfig>): env is Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'clientSecret' | 'redirectUri'>> & CliEnvConfig;
+export declare function isCliEnvConfigComplete(env: Maybe<CliEnvConfig>): env is Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'redirectUri'>> & CliEnvConfig;
 /**
  * Inputs to {@link readEnvTokenEntry}.
  */

package/src/lib/config/env.resolve.d.ts

@@ -8,7 +8,7 @@ import { type CliPaths } from './paths';
  * Guarantees that the OIDC client fields are present so callers can pass them through to the
  * OIDC client/token helpers without a non-null assertion or extra runtime check.
  */
-export type CliEnvConfigComplete = Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'clientSecret' | 'redirectUri'>> & CliEnvConfig;
+export type CliEnvConfigComplete = Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'redirectUri'>> & CliEnvConfig;
 /**
  * Builds the conventional `<CLINAME>_ENV` env var name from the CLI binary name.
  *
@@ -71,8 +71,9 @@ export declare function resolveCliEnv(input: ResolveCliEnvInput): Promise<Resolv
 export interface ResolveCliEnvOrThrowInput extends ResolveCliEnvInput {
     /**
      * When `true`, throws `AUTH_ENV_INCOMPLETE` if the resolved env is missing OIDC fields
-     * (apiBaseUrl, oidcIssuer, clientId, clientSecret, redirectUri). The returned env is narrowed
-     * to {@link CliEnvConfigComplete}. Defaults to `false`.
+     * (apiBaseUrl, oidcIssuer, clientId, redirectUri). `clientSecret` is not required — see
+     * {@link isCliEnvConfigComplete}. The returned env is narrowed to {@link CliEnvConfigComplete}.
+     * Defaults to `false`.
      */
     readonly requireComplete?: boolean;
 }

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__