@dereekb/dbx-cli 13.37.0 → 13.39.0

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__
  */

package/src/lib/doctor/firestore-session.check.d.ts

@@ -0,0 +1,113 @@
+import { type CliFirestoreBinding } from '../firestore/firestore.models';
+import { type CliReadSourceReason } from '../firestore/firestore.read';
+import { type CliFirestoreSessionContext } from '../firestore/firestore.session';
+import { type CliFirestoreQueryManifest, type CliModelManifest } from '../manifest/types';
+import { type DoctorCheck } from './doctor.command.factory';
+/**
+ * Name reported by the check {@link createFirestoreSessionDoctorCheck} builds.
+ */
+export declare const FIRESTORE_SESSION_DOCTOR_CHECK_NAME = "firestore-session";
+/**
+ * An app-supplied read that proves the direct Firestore connection works end to end.
+ *
+ * The framework cannot know which collection is rules-protected in a given app, so the last hop —
+ * "App Check accepted and a rules-protected read succeeded" — is delegated. Point it at a collection
+ * an admin may list and a non-admin may not (e.g. `getDocs(query(collection(firestore, 'wk'), limit(1)))`).
+ *
+ * Return anything JSON-serializable; it is surfaced on the check's `detail.probe`.
+ */
+export type FirestoreSessionDoctorProbe = (context: CliFirestoreSessionContext) => Promise<unknown>;
+export interface CreateFirestoreSessionDoctorCheckInput {
+    /**
+     * The rules-protected read that proves the session is genuinely usable. Strongly recommended —
+     * without it the check stops after sign-in and cannot tell whether App Check was accepted.
+     */
+    readonly probe?: FirestoreSessionDoctorProbe;
+    /**
+     * Human-readable label for what the probe reads, surfaced in the check detail (e.g. `list /wk`).
+     */
+    readonly probeName?: string;
+    /**
+     * The same `firestore` binding passed to `runCli`. Doctor checks run PRE-AUTH with no `CliContext`,
+     * so the binding cannot be discovered — pass it here and the check reports whether
+     * `CliContext.getFirestoreModels` would exist, and therefore whether `--via auto` can ever go direct.
+     */
+    readonly firestore?: CliFirestoreBinding;
+    /**
+     * The same `modelManifest` passed to `runCli`, for the server-only model count.
+     */
+    readonly modelManifest?: CliModelManifest;
+    /**
+     * The same `firestoreQueryManifest` passed to `runCli`, for the invocable query-entry count.
+     */
+    readonly firestoreQueryManifest?: CliFirestoreQueryManifest;
+}
+/**
+ * The read-routing summary the check reports alongside the session handshake — the `--via auto`
+ * decision an operator would otherwise have to infer from three separate facts.
+ */
+export interface FirestoreSessionDoctorReadRouting {
+    /**
+     * Whether `CliContext.getFirestoreModels` exists — i.e. `runCli` was given a `firestore` binding.
+     */
+    readonly getFirestoreModels: boolean;
+    /**
+     * What `--via auto` would choose given the state this check just observed.
+     */
+    readonly readPreference: 'firestore' | 'api';
+    readonly reason: CliReadSourceReason;
+    /**
+     * Query-catalog entries whose factory bound to a real runtime export, and are therefore runnable
+     * by `firestore-query`. A non-invocable entry is listed by `firestore-queries` with `INVOCABLE = no`.
+     */
+    readonly invocableQueryEntries: number;
+    readonly totalQueryEntries: number;
+    /**
+     * Models the manifest marks `@dbxModelServerOnly` — refused on every `--via` value.
+     */
+    readonly serverOnlyModels: number;
+}
+/**
+ * Summarizes the `--via auto` routing decision from what doctor can observe.
+ *
+ * @param input - The wired bindings/manifests plus whether the session actually opened.
+ * @param input.firestore - The `firestore` binding, when supplied.
+ * @param input.modelManifest - The model manifest, when supplied.
+ * @param input.firestoreQueryManifest - The query manifest, when supplied.
+ * @param input.firebaseConfigComplete - Whether the env carries a complete Firebase client config.
+ * @param input.sessionOpened - Whether the session handshake succeeded in this run.
+ * @returns The routing summary.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function buildFirestoreSessionDoctorReadRouting(input: {
+    readonly firestore?: CliFirestoreBinding;
+    readonly modelManifest?: CliModelManifest;
+    readonly firestoreQueryManifest?: CliFirestoreQueryManifest;
+    readonly firebaseConfigComplete: boolean;
+    readonly sessionOpened: boolean;
+}): FirestoreSessionDoctorReadRouting;
+/**
+ * Builds the doctor check for the direct-Firestore session path.
+ *
+ * This is the **fail-loudly surface** for the feature: `CliContext.getFirestoreContext()` throws
+ * rather than falling back to the HTTP model API, so `doctor` is where an operator finds out which
+ * hop broke. It walks the whole chain in order:
+ *
+ * 1. the env carries a complete Firebase client config;
+ * 2. a usable access token is available (cached, env-supplied, or refreshed);
+ * 3. `GET /session/firestore` is reachable and mints a custom token (+ an App Check token when the
+ *    API is configured with a web `appId`);
+ * 4. `signInWithCustomToken` succeeds against the configured project;
+ * 5. the app-supplied {@link FirestoreSessionDoctorProbe} performs one rules-protected read.
+ *
+ * Doctor checks run PRE-AUTH — `DoctorCheckInput` is only `{ cliName, envName, env, config }`, with no
+ * token and no `CliContext` — so this loads credentials itself via `buildCliPaths` +
+ * `createCliTokenCacheStore`, matching the built-in `token-cache-fresh` / `token-refresh-round-trip`
+ * checks.
+ *
+ * @param input - Optional probe configuration.
+ * @returns A {@link DoctorCheck} to append to a CLI's `doctor` check list.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createFirestoreSessionDoctorCheck(input?: CreateFirestoreSessionDoctorCheckInput): DoctorCheck;

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

@@ -1 +1,2 @@
 export * from './doctor.command.factory';
+export * from './firestore-session.check';

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

@@ -0,0 +1,28 @@
+import type { CommandModule } from 'yargs';
+/**
+ * Default command name for the direct-Firestore single-document read.
+ */
+export declare const DEFAULT_FIRESTORE_GET_COMMAND_NAME = "firestore-get";
+/**
+ * Options accepted by {@link buildFirestoreGetCommand}.
+ */
+export interface BuildFirestoreGetCommandOptions {
+    readonly commandName?: string;
+}
+/**
+ * Builds the top-level `firestore-get <modelOrKey> [key]` command.
+ *
+ * Reads one document over the direct Firestore connection, through security rules. Positional
+ * parsing goes through the same {@link parseGetArgs} the API-backed `get` uses, so inferred-model
+ * resolution behaves identically, and the emitted `{ key, data }` is byte-identical to
+ * `GetModelOverHttpResult`.
+ *
+ * There is no `--via` here — the command name IS the transport selection. `get --via firestore` is
+ * the routed equivalent for callers that want a fallback.
+ *
+ * @param options - Optional command-name override.
+ * @returns A yargs `CommandModule` for `runCli({ apiCommands })`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function buildFirestoreGetCommand(options?: BuildFirestoreGetCommandOptions): CommandModule;

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

@@ -0,0 +1,26 @@
+import type { CommandModule } from 'yargs';
+import { type CliFirestoreQueryManifest } from '../manifest/types';
+/**
+ * Default command name for the Firestore query catalog command.
+ */
+export declare const DEFAULT_FIRESTORE_QUERIES_COMMAND_NAME = "firestore-queries";
+/**
+ * Options accepted by {@link buildFirestoreQueriesCommand}.
+ */
+export interface BuildFirestoreQueriesCommandOptions {
+    readonly commandName?: string;
+}
+/**
+ * Builds the top-level `firestore-queries [query]` catalog command.
+ *
+ * Registered as a CONFIG command, not an API command — browsing the catalog is a documentation
+ * read, and demanding a login to see what queries exist would be the wrong trade. This mirrors the
+ * existing `model-info` (config, auth-bypassed) vs `model <m> get` (api, post-auth) split.
+ *
+ * @param manifest - The generated Firestore query manifest.
+ * @param options - Optional command-name override.
+ * @returns A yargs `CommandModule` for `runCli({ configCommands })`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function buildFirestoreQueriesCommand(manifest: CliFirestoreQueryManifest, options?: BuildFirestoreQueriesCommandOptions): CommandModule;