@dereekb/dbx-cli 13.37.0 → 13.38.0

package/lint-cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-lint-cache",
-  "version": "13.37.0",
+  "version": "13.38.0",
   "private": true,
   "type": "module",
   "devDependencies": {
@@ -8,7 +8,7 @@
     "eslint": "10.4.0"
   },
   "peerDependencies": {
-    "@dereekb/util": "13.37.0",
+    "@dereekb/util": "13.38.0",
     "yargs": "^18.0.0"
   }
 }

package/manifest-extract/index.cjs.js

@@ -828,6 +828,7 @@ function buildInterface(decl) {
     var jsDocs = decl.getJsDocs();
     var hasDbxModelTag = jsDocsHaveTag(jsDocs, 'dbxModel');
     var dbxModelRead = readDbxModelReadTag(jsDocs);
+    var dbxModelServerOnly = jsDocsHaveTag(jsDocs, 'dbxModelServerOnly');
     var mcpToolNameSegment = readMcpToolNameSegmentTag(jsDocs);
     var extendsNames = decl.getExtends().map(dbxCli.resolveExtendsName);
     var props = [];
@@ -873,7 +874,9 @@ function buildInterface(decl) {
         props: props
     }, dbxModelRead === undefined ? {} : {
         dbxModelRead: dbxModelRead
-    }, mcpToolNameSegment === undefined ? {} : {
+    }, dbxModelServerOnly ? {
+        dbxModelServerOnly: true
+    } : {}, mcpToolNameSegment === undefined ? {} : {
         mcpToolNameSegment: mcpToolNameSegment
     });
 }

package/manifest-extract/index.esm.js

@@ -826,6 +826,7 @@ function buildInterface(decl) {
     var jsDocs = decl.getJsDocs();
     var hasDbxModelTag = jsDocsHaveTag(jsDocs, 'dbxModel');
     var dbxModelRead = readDbxModelReadTag(jsDocs);
+    var dbxModelServerOnly = jsDocsHaveTag(jsDocs, 'dbxModelServerOnly');
     var mcpToolNameSegment = readMcpToolNameSegmentTag(jsDocs);
     var extendsNames = decl.getExtends().map(resolveExtendsName);
     var props = [];
@@ -871,7 +872,9 @@ function buildInterface(decl) {
         props: props
     }, dbxModelRead === undefined ? {} : {
         dbxModelRead: dbxModelRead
-    }, mcpToolNameSegment === undefined ? {} : {
+    }, dbxModelServerOnly ? {
+        dbxModelServerOnly: true
+    } : {}, mcpToolNameSegment === undefined ? {} : {
         mcpToolNameSegment: mcpToolNameSegment
     });
 }

package/manifest-extract/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "13.37.0",
+  "version": "13.38.0",
   "sideEffects": false,
   "peerDependencies": {
     "@dereekb/date": "13.15.0",
-    "@dereekb/dbx-cli": "13.37.0",
+    "@dereekb/dbx-cli": "13.38.0",
     "@dereekb/firebase": "13.15.0",
     "@dereekb/model": "13.15.0",
     "@dereekb/nestjs": "13.15.0",

package/manifest-extract/src/lib/types.d.ts

@@ -156,6 +156,12 @@ export interface ModelExtractionInterface {
      * / `permissions`). Absent when the interface omits the tag or declares an invalid value.
      */
     readonly dbxModelRead?: 'system' | 'owner' | 'admin-only' | 'permissions';
+    /**
+     * True when the interface carries `@dbxModelServerOnly` — the model has no client read grant in
+     * `firestore.rules` and must be refused on the model API too. See
+     * `FirebaseModelServiceConfig.serverOnly`, the runtime half of the same declaration.
+     */
+    readonly dbxModelServerOnly?: boolean;
     /**
      * Per-model MCP tool-name segment from `@dbxModelMcpToolNameSegment <segment>`. Replaces the model
      * type in generated tool names (e.g. the collection prefix). Absent when the tag is omitted or invalid.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "13.37.0",
+  "version": "13.38.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
     "dbx-cli-generate-firebase-api-manifest": "firebase-api-manifest/main.js",
     "dbx-cli-generate-firestore-indexes": "generate-firestore-indexes/main.js",
+    "dbx-cli-generate-firestore-query-manifest": "firestore-query-manifest/main.js",
     "dbx-cli-generate-mcp-manifest": "generate-mcp-manifest/main.js",
     "dbx-cli-generate-route-manifest": "generate-route-manifest/main.js",
     "dbx-cli-lint-cache": "lint-cache/main.js"
@@ -20,6 +21,9 @@
     "./firebase-api-manifest": {
       "default": "./firebase-api-manifest/main.js"
     },
+    "./firestore-query-manifest": {
+      "default": "./firestore-query-manifest/main.js"
+    },
     "./generate-firestore-indexes": {
       "default": "./generate-firestore-indexes/main.js"
     },
@@ -66,13 +70,14 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.37.0",
-    "@dereekb/firebase": "13.37.0",
-    "@dereekb/model": "13.37.0",
-    "@dereekb/nestjs": "13.37.0",
-    "@dereekb/util": "13.37.0",
+    "@dereekb/date": "13.38.0",
+    "@dereekb/firebase": "13.38.0",
+    "@dereekb/model": "13.38.0",
+    "@dereekb/nestjs": "13.38.0",
+    "@dereekb/util": "13.38.0",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
+    "firebase": "^12.12.1",
     "jiti": "2.6.1",
     "prettier": "3.8.3",
     "ts-morph": "^21.0.0",

package/route/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/dbx-cli/route",
-  "version": "13.37.0",
+  "version": "13.38.0",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "13.37.0",
-    "@dereekb/dbx-cli": "13.37.0",
-    "@dereekb/firebase": "13.37.0",
-    "@dereekb/model": "13.37.0",
-    "@dereekb/nestjs": "13.37.0",
-    "@dereekb/util": "13.37.0"
+    "@dereekb/date": "13.38.0",
+    "@dereekb/dbx-cli": "13.38.0",
+    "@dereekb/firebase": "13.38.0",
+    "@dereekb/model": "13.38.0",
+    "@dereekb/nestjs": "13.38.0",
+    "@dereekb/util": "13.38.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/src/lib/api/firestore-session.client.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Path (relative to the API base URL) of the direct-Firestore session endpoint served by
+ * `@dereekb/firebase-server`'s `SessionApiController`.
+ *
+ * Duplicated here rather than imported so `dbx-cli` keeps no dependency on the server package —
+ * the same arrangement `CALL_MODEL_API_PATH` uses.
+ */
+export declare const FIRESTORE_SESSION_API_PATH = "/session/firestore";
+/**
+ * The credential bundle `GET <apiBaseUrl>/session/firestore` returns.
+ */
+export interface CliFirestoreSession {
+    /**
+     * The uid the session was minted for.
+     */
+    readonly uid: string;
+    /**
+     * A Firebase Auth custom token to exchange via `signInWithCustomToken`.
+     */
+    readonly customToken: string;
+    /**
+     * An App Check attestation minted server-side for the project's registered web app. Absent when
+     * the API has no `appCheckAppId` configured (a project that does not enforce App Check).
+     */
+    readonly appCheckToken?: string;
+    /**
+     * ISO timestamp at which the session's shortest-lived credential expires.
+     */
+    readonly expiresAt: string;
+}
+export interface FetchFirestoreSessionInput {
+    /**
+     * The API base URL — typically `<host>/<project>/us-central1/api` or `https://<domain>/api`.
+     *
+     * The `/session/firestore` path is appended automatically.
+     */
+    readonly apiBaseUrl: string;
+    readonly accessToken: string;
+    /**
+     * Custom fetch implementation for tests.
+     */
+    readonly fetcher?: typeof fetch;
+}
+/**
+ * Fetches a direct-Firestore session from the API with the cached Bearer access token.
+ *
+ * The endpoint is admin-only and additionally gated on the `session.firestore` OIDC scope, so a 403
+ * here usually means the logged-in user is not an admin or logged in without that scope.
+ *
+ * @param input - The API target, access token, and optional fetch override.
+ * @returns The parsed {@link CliFirestoreSession}.
+ * @throws {CliError} When the endpoint answers non-2xx or returns an unusable body.
+ */
+export declare function fetchFirestoreSession(input: FetchFirestoreSessionInput): Promise<CliFirestoreSession>;

package/src/lib/api/get-args.helper.d.ts

@@ -49,7 +49,10 @@ export declare function parseGetArgs(input: {
  *    `modelType` or a {@link CliError} is thrown (the backend route is single-modelType per call).
  * 2. Otherwise `firstArg` is treated as the explicit `modelType` and `rest` are the keys.
  *
- * Always rejects empty key lists and lists exceeding 50 keys.
+ * Always rejects an empty key list. There is deliberately NO length cap: `get-many -` reads its keys
+ * from stdin and is unbounded, and both read paths batch for themselves —
+ * `getMultipleModelsOverHttpChunked` chunks at 50 per request, and `getMultipleModelsOverFirestore`
+ * holds a sliding window of 50 in-flight reads.
  *
  * @param input - Positionals captured by yargs plus the optional model manifest.
  * @param input.firstArg - The first positional from yargs.

package/src/lib/api/get-many.command.d.ts

@@ -4,12 +4,17 @@ import type { CommandModule } from 'yargs';
  *
  * Batch-reads Firestore documents by key. The first positional can either be an explicit
  * modelType (followed by ≥1 keys) or a full key (followed by additional keys whose prefixes
- * must resolve to the same modelType). Beyond 50 keys the request is automatically chunked
- * via `context.getMultipleModels`.
+ * must resolve to the same modelType). Beyond 50 keys the API request is automatically chunked
+ * via `context.getMultipleModels`; the direct path has no per-request cap and issues the reads
+ * concurrently.
  *
  * Stdin: pass `-` as the only positional to read whitespace-separated keys from stdin
  * (e.g. `cat keys.txt | <cli> get-many -`).
  *
- * Backend: `POST <apiBaseUrl>/model/<modelType>/get` with body `{ keys }` (ModelApiController.getMany).
+ * Transport is chosen by `--via` (see {@link CLI_READ_VIA_EPILOGUE}). Both paths emit the identical
+ * `{ results, errors }` envelope, so `--via` is observable only through `meta.source`.
+ *
+ * Backends: `POST <apiBaseUrl>/model/<modelType>/get` with body `{ keys }`
+ * (ModelApiController.getMany), or direct Firestore reads through the app's security rules.
  */
 export declare const GET_MANY_COMMAND: CommandModule;

package/src/lib/api/get.command.d.ts

@@ -1,12 +1,20 @@
 import type { CommandModule } from 'yargs';
+/**
+ * Epilogue shared by the routed read commands, documenting what `--via` does and does not do.
+ */
+export declare const CLI_READ_VIA_EPILOGUE: string;
 /**
  * Top-level `get <modelOrKey> [key]` command.
  *
- * Reads a single Firestore document via the typed model-access endpoint. The `model` arg is optional:
- * when only one positional is supplied, the CLI resolves the modelType from the key's leading
- * collection-name prefix via {@link decodeFirestoreModelKey}. The two-positional form passes the
- * explicit `modelType` straight through.
+ * Reads a single Firestore document. The `model` arg is optional: when only one positional is
+ * supplied, the CLI resolves the modelType from the key's leading collection-name prefix via
+ * {@link decodeFirestoreModelKey}. The two-positional form passes the explicit `modelType` straight
+ * through.
+ *
+ * Transport is chosen by `--via` (see {@link CLI_READ_VIA_EPILOGUE}). Both paths emit the identical
+ * `{ key, data }` envelope, so `--via` is observable only through `meta.source`.
  *
- * Backend: `GET <apiBaseUrl>/model/<modelType>/get?key=<key>` (ModelApiController.getOne).
+ * Backends: `GET <apiBaseUrl>/model/<modelType>/get?key=<key>` (ModelApiController.getOne), or a
+ * direct Firestore read through the app's security rules as the authenticated user.
  */
 export declare const GET_COMMAND: CommandModule;

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

@@ -2,6 +2,7 @@ export * from './call-model.client';
 export * from './call-model.command.factory';
 export * from './call.passthrough.command';
 export * from './expand-keys';
+export * from './firestore-session.client';
 export * from './get-args.helper';
 export * from './get.command';
 export * from './get-many.command';

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

@@ -102,6 +102,97 @@ export interface MergeCliEnvWithDefaultInput {
  * @returns The merged {@link CliEnvConfig}, or `undefined` when both inputs are empty.
  */
 export declare function mergeCliEnvWithDefault(input: MergeCliEnvWithDefaultInput): Maybe<CliEnvConfig>;
+/**
+ * Merges a stored Firebase client config on top of a default one, field by field, so an env can
+ * override just the `projectId` of a registered default without restating the whole block.
+ *
+ * @param env - The user's persisted Firebase config, if any.
+ * @param defaultEnv - The registered default's Firebase config, if any.
+ * @returns The merged config, or `undefined` when neither side supplies one.
+ */
+export declare function mergeCliFirebaseConfig(env: Maybe<CliFirebaseConfig>, defaultEnv: Maybe<CliFirebaseConfig>): CliFirebaseConfig | undefined;
+/**
+ * Local Firebase emulator targets for a CLI env.
+ *
+ * Mirrors the semantics of `DbxFirebaseEmulatorsConfig` in `@dereekb/dbx-firebase` (whose parse
+ * helper is Angular-bound and not reusable here): the presence of this object means "use emulators"
+ * unless {@link useEmulators} is explicitly `false`.
+ *
+ * App Check is auto-disabled whenever emulators are in use — the emulators do not verify
+ * attestations, and `initializeAppCheck` against a fake project only gets in the way.
+ */
+export interface CliFirebaseEmulatorsConfig {
+    /**
+     * Set `false` to keep the emulator targets configured but inactive. Defaults to `true`.
+     */
+    readonly useEmulators?: boolean;
+    /**
+     * Host the emulators are reachable at. Defaults to {@link DEFAULT_CLI_FIREBASE_EMULATOR_HOST}.
+     */
+    readonly host?: string;
+    /**
+     * Port of the Auth emulator. When unset, Auth is not redirected to an emulator.
+     */
+    readonly authPort?: number;
+    /**
+     * Port of the Firestore emulator. When unset, Firestore is not redirected to an emulator.
+     */
+    readonly firestorePort?: number;
+}
+/**
+ * Firebase client-SDK configuration for a CLI env, used only by the direct-Firestore session
+ * (`CliContext.getFirestoreContext`). Everything else the CLI does goes over the model HTTP API and
+ * needs none of this.
+ *
+ * These are the same public values the app's browser client initializes with — copy them from the
+ * target app's environment file. `appId` in particular must be the registered **web** app, since the
+ * server mints its App Check attestation for that app.
+ */
+export interface CliFirebaseConfig {
+    /**
+     * The Firebase web API key.
+     */
+    readonly apiKey?: string;
+    /**
+     * The project's auth domain (e.g. `my-project.firebaseapp.com`).
+     */
+    readonly authDomain?: string;
+    /**
+     * The Firebase project id.
+     */
+    readonly projectId?: string;
+    /**
+     * The registered **web** app id (e.g. `1:1234567890:web:abcdef`).
+     */
+    readonly appId?: string;
+    /**
+     * Optional emulator targets for local development.
+     */
+    readonly emulators?: CliFirebaseEmulatorsConfig;
+}
+/**
+ * Default host used for Firebase emulator connections when a {@link CliFirebaseEmulatorsConfig}
+ * omits one.
+ */
+export declare const DEFAULT_CLI_FIREBASE_EMULATOR_HOST = "localhost";
+/**
+ * Returns true when the env carries the minimum Firebase client config needed to open a direct
+ * Firestore session.
+ *
+ * Deliberately separate from {@link isCliEnvConfigComplete}: the Firebase config is optional, and
+ * folding it into the general completeness check would break every CLI that only uses the model API.
+ *
+ * @param firebase - The env's Firebase client config, if any.
+ * @returns `true` when `apiKey`, `projectId`, and `appId` are all present and non-empty.
+ */
+export declare function isCliFirebaseConfigComplete(firebase: Maybe<CliFirebaseConfig>): firebase is Required<Pick<CliFirebaseConfig, 'apiKey' | 'projectId' | 'appId'>> & CliFirebaseConfig;
+/**
+ * Returns true when the env's emulator config is present and active.
+ *
+ * @param firebase - The env's Firebase client config, if any.
+ * @returns `true` when emulators are configured and not explicitly disabled.
+ */
+export declare function cliFirebaseEmulatorsInUse(firebase: Maybe<CliFirebaseConfig>): boolean;
 /**
  * Environment-targeting config for a CLI invocation.
  *
@@ -154,6 +245,12 @@ export interface CliEnvConfig {
      * Space-separated OAuth scopes to request. Defaults to {@link DEFAULT_CLI_OIDC_SCOPES}.
      */
     readonly scopes?: string;
+    /**
+     * Optional Firebase client config enabling the direct-Firestore session
+     * (`CliContext.getFirestoreContext()`). Optional by design — a CLI that only calls the model API
+     * never needs it, and requiring it would break every existing consumer.
+     */
+    readonly firebase?: CliFirebaseConfig;
 }
 /**
  * Resolves the active env name from a flag, env-var, or the persisted config default.
@@ -189,6 +286,15 @@ export declare function resolveActiveEnvName(input: ResolveActiveEnvInput): Mayb
  *   - `DEMO_CLI_CLIENT_SECRET`
  *   - `DEMO_CLI_REDIRECT_URI`
  *   - `DEMO_CLI_SCOPES`
+ *
+ * Plus the optional direct-Firestore session config:
+ *   - `DEMO_CLI_FIREBASE_API_KEY`
+ *   - `DEMO_CLI_FIREBASE_AUTH_DOMAIN`
+ *   - `DEMO_CLI_FIREBASE_PROJECT_ID`
+ *   - `DEMO_CLI_FIREBASE_APP_ID`
+ *   - `DEMO_CLI_FIREBASE_EMULATOR_HOST`
+ *   - `DEMO_CLI_FIREBASE_AUTH_EMULATOR_PORT`
+ *   - `DEMO_CLI_FIREBASE_FIRESTORE_EMULATOR_PORT`
  */
 export interface EnvVarOverrideInput {
     readonly cliName: string;

package/src/lib/config/firestore-session.cache.d.ts

@@ -0,0 +1,86 @@
+import { type AsyncKeyedValueCache, type Maybe } from '@dereekb/util';
+import { type CliFirestoreSession } from '../api/firestore-session.client';
+/**
+ * Hard ceiling on how long a minted direct-Firestore session may be reused, regardless of what the
+ * API reported in `expiresAt`.
+ *
+ * One hour, because that is the Firebase ceiling the credentials themselves sit under: a custom
+ * token is exchangeable for one hour, and the ID token it mints lives one hour. Holding a session
+ * past that buys nothing — the sign-in would fail — and re-minting is one HTTP round-trip.
+ */
+export declare const CLI_FIRESTORE_SESSION_MAX_CACHE_MS: number;
+/**
+ * Default skew/latency buffer applied when deciding whether a cached session is still usable.
+ */
+export declare const CLI_FIRESTORE_SESSION_EXPIRY_BUFFER_MS = 60000;
+/**
+ * A cached direct-Firestore session for a single env.
+ *
+ * Stores the credential envelope the API minted, not the live Firebase objects — those are
+ * per-process and cannot be serialized. A cache hit still signs in; it just skips the
+ * `GET /session/firestore` round-trip.
+ */
+export interface CliFirestoreSessionEntry {
+    /**
+     * The credential bundle returned by `GET /session/firestore`.
+     */
+    readonly session: CliFirestoreSession;
+    /**
+     * Unix epoch milliseconds at which the entry was written.
+     */
+    readonly cachedAt: number;
+    /**
+     * The uid the entry was minted for, denormalized so a stale entry belonging to a different user
+     * can be detected without parsing the custom token.
+     */
+    readonly uid: string;
+}
+/**
+ * Firestore session cache shape on disk — keyed by env name.
+ */
+export type CliFirestoreSessionCache = Record<string, CliFirestoreSessionEntry>;
+/**
+ * Session cache store keyed by env name.
+ *
+ * Backed by a single JSON file with per-process in-memory memoization, exactly like the token
+ * cache — see {@link createMemoizedJsonFileAsyncKeyedValueCache}.
+ */
+export type CliFirestoreSessionCacheStore = AsyncKeyedValueCache<CliFirestoreSessionEntry>;
+export interface CreateCliFirestoreSessionCacheStoreInput {
+    readonly firestoreSessionCachePath: string;
+}
+/**
+ * Creates a per-env direct-Firestore session cache store backed by a single JSON file.
+ *
+ * Entries are written with mode 0o600 — they hold a Firebase custom token, which is a bearer
+ * credential for the user it was minted for.
+ *
+ * @param input - The cache store inputs.
+ * @param input.firestoreSessionCachePath - Absolute path to the JSON file backing the cache.
+ * @returns A {@link CliFirestoreSessionCacheStore} keyed by env name.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createCliFirestoreSessionCacheStore(input: CreateCliFirestoreSessionCacheStoreInput): CliFirestoreSessionCacheStore;
+/**
+ * Resolves the epoch-millis instant at which a cached session stops being usable.
+ *
+ * The effective expiry is the EARLIER of the API-reported `expiresAt` and
+ * {@link CLI_FIRESTORE_SESSION_MAX_CACHE_MS} past the write. Taking the earlier of the two means a
+ * server that reports an over-long (or unparsable) window still cannot push a session past the
+ * Firebase credential ceiling.
+ *
+ * @param entry - The cached entry.
+ * @returns The effective expiry in unix epoch milliseconds.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliFirestoreSessionEntryExpiresAt(entry: CliFirestoreSessionEntry): number;
+/**
+ * Returns true when the cached session is at or near its effective expiry.
+ *
+ * @param entry - The cached entry (`null`/`undefined` is treated as expired).
+ * @param nowMs - The current time in unix epoch milliseconds. Defaults to `Date.now()`.
+ * @param bufferMs - Skew/latency buffer; the entry is treated as expired this far ahead of its effective expiry.
+ * @returns `true` when the entry is unusable, otherwise `false`.
+ */
+export declare function isCliFirestoreSessionExpired(entry: Maybe<CliFirestoreSessionEntry>, nowMs?: number, bufferMs?: number): boolean;

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

@@ -1,5 +1,6 @@
 export * from './cli.config';
 export * from './env';
+export * from './firestore-session.cache';
 export * from './env.resolve';
 export * from './paths';
 export * from './token.cache';

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

@@ -5,6 +5,7 @@ export interface CliPaths {
     readonly configDir: string;
     readonly configFilePath: string;
     readonly tokenCachePath: string;
+    readonly firestoreSessionCachePath: string;
 }
 export interface CliPathsConfig {
     /**
@@ -24,11 +25,12 @@ export interface CliPathsConfig {
  * Layout:
  *   - `<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)
  *
  * @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, and the token cache file.
+ * @returns The {@link CliPaths} pointing at `configDir`, the config file, the token cache file, and the Firestore session cache file.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function buildCliPaths(config: CliPathsConfig): CliPaths;

package/src/lib/context/cli.context.d.ts

@@ -1,6 +1,10 @@
-import type { OnCallTypedModelParams } from '@dereekb/firebase';
+import type { FirestoreContext, OnCallTypedModelParams } from '@dereekb/firebase';
+import type { Maybe } from '@dereekb/util';
 import { type CliEnvConfig } from '../config/env';
+import { type CliFirestoreSessionCacheStore } from '../config/firestore-session.cache';
 import { type GetModelOverHttpResult, type GetMultipleModelsOverHttpResult } from '../api/call-model.client';
+import { type CliFirestoreBinding, type CliFirestoreModels } from '../firestore/firestore.models';
+import { type CliFirestoreSessionContext } from '../firestore/firestore.session';
 import { type CliModelManifest } from '../manifest/types';
 /**
  * The CLI context attached to argv by the auth middleware.
@@ -23,9 +27,76 @@ export interface CliContext {
     readonly getModel: <TResult = unknown>(modelType: string, key: string) => Promise<GetModelOverHttpResult<TResult>>;
     readonly getMultipleModels: <TResult = unknown>(modelType: string, keys: ReadonlyArray<string>) => Promise<GetMultipleModelsOverHttpResult<TResult>>;
     readonly modelManifest?: CliModelManifest;
+    /**
+     * Opens (once per invocation) a direct Firestore connection as the authenticated user and returns
+     * the `FirestoreContext` an app's `make<App>FirestoreCollections(context)` factory consumes — the
+     * same object the Angular app builds, so the same queries run through the same security rules.
+     *
+     * Lazy on purpose: the handshake costs an HTTP round-trip plus a sign-in, and the auth middleware
+     * builds a context on EVERY invocation, including ones that never touch Firestore. Memoized within
+     * the invocation, and — when the runner supplies a session cache — the minted credential envelope
+     * is reused ACROSS invocations for up to an hour, so only the sign-in is repaid.
+     *
+     * OPTIONAL so that a hand-built test context (see `createPassthroughAuthMiddleware`) stays valid.
+     * Calling it throws when the env carries no Firebase client config — there is no fallback to the
+     * HTTP model API by design.
+     */
+    readonly getFirestoreContext?: () => Promise<FirestoreContext>;
+    /**
+     * The full session behind {@link CliContext.getFirestoreContext} — the signed-in `Auth`, the raw
+     * `Firestore`, and the minted credential envelope. Memoized alongside it, so calling both opens one
+     * session.
+     */
+    readonly getFirestoreSession?: () => Promise<CliFirestoreSessionContext>;
+    /**
+     * The app's models bound to the direct-Firestore session — what `firestore-get` /
+     * `firestore-query` dispatch through. Layered on the {@link CliContext.getFirestoreSession} memo,
+     * so all three thunks share ONE session, and separately memoized itself, so the app's collections
+     * object is built ONCE per invocation rather than once per call.
+     *
+     * Present only when the CLI was configured with a `firestore` binding (`runCli({ firestore })`).
+     */
+    readonly getFirestoreModels?: () => Promise<CliFirestoreModels>;
+    /**
+     * Releases the direct-Firestore session opened during this invocation, if any.
+     *
+     * {@link runCli} calls this once the command has finished. Without it the CLI PRINTS ITS RESULT AND
+     * THEN HANGS: the signed-in `Auth` and live `Firestore` keep the Node event loop alive, so the
+     * process never exits and a caller piping the output waits forever.
+     *
+     * Never opens a session in order to close one — a command that never touched Firestore resolves
+     * immediately. Safe to call more than once.
+     */
+    readonly closeFirestoreSession?: () => Promise<void>;
 }
-export declare const setCliContext: (value: import("@dereekb/util").Maybe<CliContext>) => void;
-export declare const getCliContext: () => import("@dereekb/util").Maybe<CliContext>;
+/**
+ * Returns the context's {@link CliFirestoreSessionContext} thunk result, or throws a {@link CliError}
+ * when the context has none.
+ *
+ * {@link CliContext.getFirestoreSession} is optional so a hand-built test context stays valid, which
+ * would otherwise leave every consumer action writing the same guard. Every context built by
+ * {@link createCliContext} does provide it, so reaching this error in practice means the action ran
+ * against a context that was assembled by hand.
+ *
+ * @param context - The live CLI context.
+ * @returns The opened (and memoized) direct-Firestore session.
+ * @throws {CliError} When the context does not support direct-Firestore sessions.
+ */
+export declare function requireCliFirestoreSession(context: CliContext): Promise<CliFirestoreSessionContext>;
+/**
+ * Returns the client `FirestoreContext` for the current invocation, opening the direct-Firestore
+ * session on first use.
+ *
+ * The returned context is the exact analogue of the server's, so an app's
+ * `make<App>FirestoreCollections(context)` accepts it unchanged.
+ *
+ * @param context - The live CLI context.
+ * @returns The client `FirestoreContext` an app's collections factory consumes.
+ * @throws {CliError} When the context does not support direct-Firestore sessions.
+ */
+export declare function requireCliFirestoreContext(context: CliContext): Promise<FirestoreContext>;
+export declare const setCliContext: (value: Maybe<CliContext>) => void;
+export declare const getCliContext: () => Maybe<CliContext>;
 /**
  * Returns the current {@link CliContext} or throws — for use in command handlers that require auth.
  */
@@ -40,6 +111,17 @@ export interface CreateCliContextInput {
      * (e.g. `get <key>`) can resolve `prefix/id` keys to a `modelType` via `decodeFirestoreModelKey`.
      */
     readonly modelManifest?: CliModelManifest;
+    /**
+     * Optional on-disk direct-Firestore session cache. When supplied, the session opened by
+     * {@link CliContext.getFirestoreSession} is reused across invocations for up to an hour instead of
+     * costing a `GET /session/firestore` round-trip every time.
+     */
+    readonly firestoreSessionCache?: CliFirestoreSessionCacheStore;
+    /**
+     * The app-supplied Firestore binding (`cliFirestoreBinding({ collections, models })`). When
+     * present, the context exposes {@link CliContext.getFirestoreModels}.
+     */
+    readonly firestore?: CliFirestoreBinding;
 }
 /**
  * Builds a {@link CliContext} for the current invocation.
@@ -53,6 +135,8 @@ export interface CreateCliContextInput {
  * @param input.env - The resolved {@link CliEnvConfig} for the active env.
  * @param input.accessToken - The Bearer access token to include on outgoing API calls.
  * @param input.modelManifest - Optional generated {@link CliModelManifest} for key→modelType resolution.
+ * @param input.firestoreSessionCache - Optional on-disk direct-Firestore session cache shared across invocations.
+ * @param input.firestore - Optional app-supplied Firestore binding enabling the generic direct-read commands.
  * @returns The constructed {@link CliContext}.
  * @__NO_SIDE_EFFECTS__
  */