@dereekb/dbx-cli 13.36.0 → 13.38.0

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;

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

@@ -0,0 +1,25 @@
+import type { CommandModule } from 'yargs';
+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";
+/**
+ * Options accepted by {@link buildFirestoreQueryCommand}.
+ */
+export interface BuildFirestoreQueryCommandOptions {
+    readonly commandName?: string;
+}
+/**
+ * Builds the top-level `firestore-query <query>` command.
+ *
+ * Executes a catalog entry over the direct Firestore connection, through the app's security rules
+ * as the authenticated user.
+ *
+ * @param manifest - The generated Firestore query manifest.
+ * @param options - Optional command-name override.
+ * @returns A yargs `CommandModule` for `runCli({ apiCommands })`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function buildFirestoreQueryCommand(manifest: CliFirestoreQueryManifest, options?: BuildFirestoreQueryCommandOptions): CommandModule;

package/src/lib/firestore/firestore.accessor.d.ts

@@ -0,0 +1,85 @@
+import { type FirebaseAppModelContext, type FirebaseModelsService } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+import { type GetModelOverHttpResult, type GetMultipleModelsOverHttpResult } from '../api/call-model.client';
+import { type CliContext } from '../context/cli.context';
+import { type CliFirestoreBinding, type CliFirestoreBindingInput, type CliFirestoreModels } from './firestore.models';
+/**
+ * A callable that resolves the app's TYPED direct-Firestore view for the current invocation, plus the
+ * binding to wire the CLI with.
+ *
+ * The one place an app names its `<X>FirestoreCollections`: `cliFirestoreAccessorFactory` captures
+ * both `C` and `Y` at the app site, and hands them back on every call — so an action reads through
+ * `collections.guestbookCollection` and `serviceFor('guestbook')` at the app's real types instead of
+ * rebuilding the collections itself to recover them.
+ *
+ * @template C - The app's collections type, e.g. `DemoFirestoreCollections`.
+ * @template Y - The app's `<app>FirebaseModelServices` type.
+ */
+export type CliFirestoreAccessorFactory<C extends object, Y extends FirebaseModelsService<any, any>> = ((context: CliContext) => Promise<CliFirestoreAccessor<C, Y>>) & {
+    /**
+     * The binding to hand `runCli({ firestore })`, `buildTestCliContext({ firestore })`, and
+     * `createFirestoreSessionDoctorCheck({ firestore })`.
+     *
+     * Sharing THIS object — rather than calling `cliFirestoreBinding` again with the same arguments —
+     * is what lets the accessor reuse the context's memoized collections instead of building a second
+     * copy: the reuse branch is an identity check, and two separate `cliFirestoreBinding` calls produce
+     * two non-identical bindings.
+     */
+    readonly binding: CliFirestoreBinding<C>;
+};
+/**
+ * The typed direct-Firestore view an app's actions read through.
+ *
+ * A {@link CliFirestoreModels} carrying the app's real `C` / `Y`, plus the two read helpers, so an
+ * action never has to import `getModelOverFirestore` alongside it.
+ *
+ * @template C - The app's collections type.
+ * @template Y - The app's `<app>FirebaseModelServices` type.
+ */
+export type CliFirestoreAccessor<C extends object, Y extends FirebaseModelsService<any, any>> = CliFirestoreModels<C, Y> & {
+    /**
+     * Reads one document by model key, returning the same `{ key, data }` envelope
+     * `GET /model/<type>/get` returns.
+     */
+    readonly readModel: <T = unknown>(modelType: string, key: string) => Promise<GetModelOverHttpResult<Maybe<T>>>;
+    /**
+     * Batch-reads documents by model key, returning the same `{ results, errors }` envelope the model
+     * API's `getMany` returns.
+     */
+    readonly readMultipleModels: <T = unknown>(modelType: string, keys: ReadonlyArray<string>) => Promise<GetMultipleModelsOverHttpResult<Maybe<T>>>;
+};
+/**
+ * Registers an app's collections factory + model services once, and returns the accessor its actions
+ * read through.
+ *
+ * Resolution order on each call, three cases:
+ *
+ * 1. the context was wired with THIS binding (`models.binding === binding`) → reuse its memoized
+ *    view. The identity check is what makes the `object` → `C` narrowing sound: `collections`
+ *    provably came from `binding.collections`, which returns `C`.
+ * 2. the context has NO binding → build a view from `requireCliFirestoreSession(context)`, so an app
+ *    can use the accessor in its actions without also passing `runCli({ firestore })`.
+ * 3. the context was wired with a DIFFERENT binding → build a second view and `verboseLog` about it,
+ *    rather than silently asserting that someone else's `collections` is a `C`.
+ *
+ * @param input - The app's collections factory, model services, and optional per-model override.
+ * @returns The callable accessor, carrying {@link CliFirestoreAccessorFactory.binding}.
+ *
+ * @example
+ * ```ts
+ * export const demoCliFirestore = cliFirestoreAccessorFactory({
+ *   collections: makeDemoFirestoreCollections,
+ *   models: demoFirebaseModelServices
+ * });
+ *
+ * // wiring
+ * runCli({ firestore: demoCliFirestore.binding });
+ *
+ * // in an action
+ * const { collections, session } = await demoCliFirestore(input.context);
+ * const entries = await collections.guestbookCollection.queryDocument(...).getDocs();
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliFirestoreAccessorFactory<C extends object, Y extends FirebaseModelsService<any, FirebaseAppModelContext<C>>>(input: CliFirestoreBindingInput<C, Y>): CliFirestoreAccessorFactory<C, Y>;

package/src/lib/firestore/firestore.collection.d.ts

@@ -0,0 +1,44 @@
+import { type FirestoreCollectionLike, type FirestoreModelKey, type FirestoreModelType } from '@dereekb/firebase';
+import { type CliFirestoreQueryScope } from '../manifest/types';
+import { type CliFirestoreModels } from './firestore.models';
+/**
+ * Input for {@link cliFirestoreCollectionForQuery}.
+ */
+export interface CliFirestoreCollectionForQueryInput {
+    readonly models: CliFirestoreModels;
+    readonly modelType: FirestoreModelType;
+    /**
+     * The entry's declared scope. Together with {@link isNested} it decides whether `--parent` is
+     * optional, required, or rejected.
+     */
+    readonly scope: CliFirestoreQueryScope;
+    /**
+     * Whether the model is a subcollection of some parent.
+     */
+    readonly isNested: boolean;
+    /**
+     * The parent document key to narrow to, from `--parent`.
+     */
+    readonly parentKey?: FirestoreModelKey;
+}
+/**
+ * Resolves the collection a catalog entry should execute against, applying `--parent` scoping.
+ *
+ * The `--parent` rules, and why:
+ *
+ * | entry | `--parent` |
+ * | --- | --- |
+ * | `COLLECTION_GROUP` + nested | optional — narrows the group to one parent |
+ * | `COLLECTION` + nested | **required** — the COLLECTION-scope composite index may not exist at group scope, so silently widening would turn a working query into a `FAILED_PRECONDITION` |
+ * | not nested | rejected — a root collection has no parent to scope to |
+ *
+ * Narrowing is derived generically rather than per-model: `FirestoreCollectionGroup.config` is
+ * public and `makeFirestoreCollectionGroup` accepts any `queryLike`, so re-pointing the group's
+ * `queryLike` at `firestoreContext.subcollection(parentRef, collectionName)` scopes it to one
+ * parent. `docAtPath` needs no parent modelType — the parent key IS the path.
+ *
+ * @param input - The models view, the entry's model/scope/nesting, and the optional parent key.
+ * @returns The collection to query.
+ * @throws {CliError} When `--parent` is missing where required, supplied where rejected, or the registered collection cannot be scoped.
+ */
+export declare function cliFirestoreCollectionForQuery(input: CliFirestoreCollectionForQueryInput): FirestoreCollectionLike<unknown>;

package/src/lib/firestore/firestore.error.d.ts

@@ -0,0 +1,14 @@
+import { type CliErrorMapper } from '../util/output';
+/**
+ * Maps a client-SDK `FirebaseError` onto the CLI's error envelope.
+ *
+ * Without this a rules rejection falls through `buildErrorOutput` to a bare
+ * `{ ok: false, code: 'ERROR' }` — indistinguishable from any other failure, which is exactly the
+ * wrong answer for the one error the direct path exists to surface honestly.
+ *
+ * @param error - The thrown value.
+ * @returns The mapped envelope, or `undefined` to defer to the built-in branches.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare const cliFirestoreErrorMapper: CliErrorMapper;

package/src/lib/firestore/firestore.models.d.ts

@@ -0,0 +1,223 @@
+import { type FirebaseAppModelContext, type FirebaseModelServiceGetter, type FirebaseModelsService, type FirebaseModelsServiceTypes, type FirestoreCollectionLike, type FirestoreContext, type FirestoreDocument, type FirestoreModelKey, type FirestoreModelType, type InContextFirebaseModelCollectionLoader, type InContextFirebaseModelLoader } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+import { type CliContext } from '../context/cli.context';
+import { type CliFirestoreSessionContext } from './firestore.session';
+/**
+ * The slice of a `FirebaseModelService` the CLI's generic direct-Firestore reads need.
+ *
+ * Only the two members that never touch `roleMapForModel`: `dbx-cli` reads through Firestore
+ * security rules, not through the app's role map, so the permission half of the service is
+ * deliberately unused here.
+ */
+export interface CliFirestoreModelService {
+    readonly loadModelForKey: (key: FirestoreModelKey) => FirestoreDocument<unknown>;
+    readonly getFirestoreCollection: () => FirestoreCollectionLike<unknown>;
+}
+/**
+ * The callable shape of an app's `<app>FirebaseModelServices`, erased to what the CLI needs.
+ */
+export type CliFirestoreModelsService = ((modelType: FirestoreModelType, context: {
+    readonly app: unknown;
+}) => CliFirestoreModelService) & {
+    allTypes(): FirestoreModelType[];
+};
+/**
+ * Input for a {@link CliFirestoreBinding.collectionForModel} override.
+ */
+export interface CliFirestoreCollectionForModelInput {
+    readonly collections: object;
+    readonly modelType: FirestoreModelType;
+    readonly parentKey?: FirestoreModelKey;
+}
+/**
+ * The one app-supplied hook that makes generic direct-Firestore commands possible.
+ *
+ * `dbx-cli` cannot import an app's collections factory — that is the whole reason there is no
+ * generic direct command without this. Supplying it wires `firestore-get` / `firestore-query`
+ * for EVERY registered model at once; there is no per-model codegen.
+ *
+ * `C` appears in exactly one position — the RETURN of {@link collections} — and that is deliberate.
+ * Because the use is purely covariant, `CliFirestoreBinding<DemoFirestoreCollections>` is assignable
+ * to `CliFirestoreBinding<object>`, which is what lets `CreateCliInput.firestore` keep accepting a
+ * typed binding with no cast and keeps generics out of `CliContext` / `runCli` entirely.
+ *
+ * Adding `C` (or the models generic `Y`) to {@link models} or to
+ * {@link CliFirestoreCollectionForModelInput} would put it in a PARAMETER position, and under
+ * `strictFunctionTypes` that destroys the assignability above — cascading generics through
+ * `CreateCliInput` → `createAuthMiddleware` → `createCliContext` → `CliContext`. Don't.
+ *
+ * @template C - The app's collections type, e.g. `DemoFirestoreCollections`.
+ */
+export interface CliFirestoreBinding<C extends object = object> {
+    /**
+     * The app's `make<App>FirestoreCollections`.
+     */
+    readonly collections: (firestoreContext: FirestoreContext) => C;
+    /**
+     * The app's `<app>FirebaseModelServices`.
+     */
+    readonly models: CliFirestoreModelsService;
+    /**
+     * Escape hatch for models whose registered collection cannot be parent-scoped generically
+     * (e.g. a paged-items collection). Return `undefined` to fall through to the derived scoping.
+     */
+    readonly collectionForModel?: (input: CliFirestoreCollectionForModelInput) => Maybe<FirestoreCollectionLike<unknown>>;
+}
+/**
+ * Input for {@link cliFirestoreBinding} and {@link cliFirestoreAccessorFactory}.
+ *
+ * `Y` sits in a PROPERTY position here, which is safe precisely because this is the INPUT type and
+ * never the binding: nothing assigns a `CliFirestoreBindingInput` to `CreateCliInput.firestore`, so
+ * the variance rule on {@link CliFirestoreBinding} does not apply. Capturing it is what lets
+ * `cliFirestoreAccessorFactory` hand back the app's real model types.
+ *
+ * @template C - The app's collections type, e.g. `DemoFirestoreCollections`.
+ * @template Y - The app's `<app>FirebaseModelServices` type.
+ */
+export interface CliFirestoreBindingInput<C extends object, Y extends FirebaseModelsService<any, FirebaseAppModelContext<C>> = FirebaseModelsService<any, FirebaseAppModelContext<C>>> {
+    readonly collections: (firestoreContext: FirestoreContext) => C;
+    readonly models: Y;
+    readonly collectionForModel?: (input: CliFirestoreCollectionForModelInput) => Maybe<FirestoreCollectionLike<unknown>>;
+}
+/**
+ * Builds a {@link CliFirestoreBinding} from an app's collections factory and model services.
+ *
+ * Typed so the app site needs no cast — `C` is carried through on {@link CliFirestoreBinding.collections},
+ * and the one erasure the CLI requires (the app's model-service union → {@link CliFirestoreModelService})
+ * is absorbed here rather than at every call site.
+ *
+ * The `{ app: collections }` context handed to the model service is COMPLETE for the two members
+ * the CLI uses: `FirebasePermissionContext`, `FirebasePermissionErrorContext` and
+ * `FirebaseAuthContext` are all-optional, `firebaseModelsService` self-injects `service`, and
+ * neither `loadModelForKey` nor `getFirestoreCollection` reads `auth`.
+ *
+ * Most apps should reach for {@link cliFirestoreAccessorFactory} instead, which calls this and ALSO
+ * hands back a typed accessor for the app's own actions. Use this directly only when the binding is
+ * all you need.
+ *
+ * @param input - The app's collections factory, model services, and optional per-model override.
+ * @returns The binding `runCli` accepts, still carrying `C`.
+ *
+ * @example
+ * ```ts
+ * runCli({
+ *   firestore: cliFirestoreBinding({ collections: makeDemoFirestoreCollections, models: demoFirebaseModelServices })
+ * });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliFirestoreBinding<C extends object>(input: CliFirestoreBindingInput<C>): CliFirestoreBinding<C>;
+/**
+ * The default `Y` for {@link CliFirestoreModels}: a registry admitting ANY `FirestoreModelType`, with
+ * every model erased to `unknown`.
+ *
+ * Chosen so the defaulted generic form reproduces the pre-`Y` interface member-for-member — which is
+ * why `CliContext.getFirestoreModels?: () => Promise<CliFirestoreModels>` needs no change, and why
+ * every string-dispatched caller inside `dbx-cli` still compiles.
+ */
+export type CliErasedFirebaseModelsService = FirebaseModelsService<Record<FirestoreModelType, FirebaseModelServiceGetter<any, unknown>>, any>;
+/**
+ * Resolves the app's REAL `T` / `D` for one registered model type out of its `<app>FirebaseModelServices`.
+ *
+ * Deliberately only the loader half — {@link CliFirestoreModelService} explains why the permission
+ * half (`roleMapForModel`, `requireRole`, `use`) is excluded: `dbx-cli` authorizes through
+ * `firestore.rules`, not the app's role map, and the `{ app: collections }` context it hands the
+ * service carries no `auth` for a role map to read.
+ *
+ * @template Y - The app's `<app>FirebaseModelServices` type.
+ * @template K - The registered model type to resolve.
+ */
+export type CliFirestoreModelServiceForType<Y extends FirebaseModelsService<any, any>, K extends FirebaseModelsServiceTypes<Y>> = Y extends FirebaseModelsService<infer X, infer C> ? (K extends keyof X ? (X[K] extends FirebaseModelServiceGetter<C, infer T, infer D, any> ? InContextFirebaseModelLoader<T, D> & InContextFirebaseModelCollectionLoader<T, D> : never) : never) : never;
+/**
+ * The per-invocation, session-bound view of an app's models over a direct Firestore connection.
+ *
+ * @template C - The app's collections type, e.g. `DemoFirestoreCollections`.
+ * @template Y - The app's `<app>FirebaseModelServices` type. Defaults to
+ *   {@link CliErasedFirebaseModelsService}, which reproduces the erased pre-`Y` interface exactly.
+ */
+export interface CliFirestoreModels<C extends object = object, Y extends FirebaseModelsService<any, any> = CliErasedFirebaseModelsService> {
+    readonly session: CliFirestoreSessionContext;
+    /**
+     * The app's collections object, built against the session's `FirestoreContext`.
+     */
+    readonly collections: C;
+    /**
+     * The binding the app supplied, for consumers that need `collectionForModel`.
+     *
+     * Typed `CliFirestoreBinding<C>`, NOT `CliFirestoreBinding<C, Y>` — `Y` must never reach the
+     * binding, or the binding stops being assignable to `CliFirestoreBinding<object>`. See the
+     * variance note on {@link CliFirestoreBinding}.
+     */
+    readonly binding: CliFirestoreBinding<C>;
+    /**
+     * The app's `<app>FirebaseModelServices`, at its real type.
+     *
+     * Runtime-identical to `binding.models` — the same object — but honestly typed, so callers that
+     * hold a typed `CliFirestoreModels` can reach the full service (permissions included) when they
+     * genuinely want it, rather than the CLI-erased slice {@link serviceFor} hands back.
+     */
+    readonly models: Y;
+    readonly allTypes: () => FirebaseModelsServiceTypes<Y>[];
+    /**
+     * Resolves the model service for `modelType`, validating against {@link allTypes} FIRST.
+     *
+     * The validation is load-bearing, not defensive: `firebaseModelsService` indexes its factory map
+     * and calls the result immediately, so an unregistered type surfaces as a bare `TypeError`
+     * instead of a `CliError` the CLI can render.
+     *
+     * An OVERLOAD PAIR, specific-first, and the order is what keeps this non-breaking. A literal
+     * (`serviceFor('guestbook')`) satisfies `K extends FirebaseModelsServiceTypes<Y>` and gets the app's
+     * real `GuestbookDocument`; a runtime `string` off argv does not, and falls through to the erased
+     * signature — which is why every string-dispatched caller in `dbx-cli` compiles untouched. Under
+     * the default erased `Y`, `FirebaseModelsServiceTypes<Y>` widens to `FirestoreModelType` and
+     * signature 1 collapses into signature 2.
+     */
+    readonly serviceFor: {
+        <K extends FirebaseModelsServiceTypes<Y>>(modelType: K): CliFirestoreModelServiceForType<Y, K>;
+        (modelType: FirestoreModelType): CliFirestoreModelService;
+    };
+    /**
+     * Resolves a SHORT COLLECTION NAME (`gb`, `gbe`) to the `modelType` the app registered its service
+     * under (`guestbook`, `guestbookEntry`).
+     *
+     * The query catalog records the collection name, not the model type — that is what
+     * `firestore.indexes.json` keys on and what `CliModelManifestEntry.collectionPrefix` joins to — but
+     * `<app>FirebaseModelServices` is keyed by model type. The join is derived from the registered
+     * collections' own `modelIdentity` rather than from a manifest, so it works for every app with no
+     * extra wiring.
+     *
+     * Memoized: resolving walks `allTypes()` building each service's collection until it matches.
+     */
+    readonly modelTypeForCollection: (collectionName: string) => FirebaseModelsServiceTypes<Y>;
+}
+/**
+ * Resolves the direct-Firestore model view for the current invocation, opening the session on
+ * first use.
+ *
+ * @param context - The live CLI context.
+ * @returns The session-bound {@link CliFirestoreModels}.
+ * @throws {CliError} When the CLI was not configured with a `firestore` binding, or the session cannot be opened.
+ */
+export declare function requireCliFirestoreModels(context: CliContext): Promise<CliFirestoreModels>;
+/**
+ * Input for {@link createCliFirestoreModels}.
+ */
+export interface CreateCliFirestoreModelsInput<C extends object = object> {
+    readonly binding: CliFirestoreBinding<C>;
+    readonly session: CliFirestoreSessionContext;
+}
+/**
+ * Binds an app's {@link CliFirestoreBinding} to an open session.
+ *
+ * `Y` is inferred from the caller's annotation rather than from `input` — the binding erased its
+ * models to {@link CliFirestoreModelsService} on the way in (it must, for variance), so there is
+ * nothing left here to infer it from. {@link cliFirestoreAccessorFactory} is what re-attaches the
+ * app's real `Y`, having captured it at the app site.
+ *
+ * @param input - The binding and the open session.
+ * @returns The {@link CliFirestoreModels} view.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createCliFirestoreModels<C extends object = object, Y extends FirebaseModelsService<any, any> = CliErasedFirebaseModelsService>(input: CreateCliFirestoreModelsInput<C>): CliFirestoreModels<C, Y>;

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

@@ -0,0 +1,34 @@
+import { type CliFirestoreQueryManifestEntry } from '../manifest/types';
+/**
+ * Input for {@link resolveCliFirestoreQueryArgs}.
+ */
+export interface ResolveCliFirestoreQueryArgsInput {
+    readonly entry: CliFirestoreQueryManifestEntry;
+    /**
+     * The raw `--params` string, if supplied.
+     */
+    readonly params?: string;
+    /**
+     * When true, no date coercion is applied at any level.
+     */
+    readonly rawParams?: boolean;
+}
+/**
+ * Resolves the positional argument list to call a catalog entry's factory with.
+ *
+ * The contract is POSITIONAL-first, because the single-params-object convention is not universal:
+ * the workspace's `*.query.ts` files include zero-arg, single-scalar, two-positional,
+ * defaulted-positional, `Maybe<Date>` and `ArrayOrValue<T>` shapes.
+ *
+ * 1. **omitted** → call with no args; valid only when every param is optional.
+ * 2. **JSON array** → spread positionally. Works for every shape.
+ * 3. **JSON object** → when the factory takes exactly one param and the key set is not exactly that
+ *    param's name, the whole object is passed as arg 0 (the single-params-object ergonomic path).
+ *    Otherwise keys are mapped by param name into positional order.
+ * 4. **unparseable** → a `CliError` quoting the parse error and the received string.
+ *
+ * @param input - The catalog entry and the raw `--params` string.
+ * @returns The positional arguments to spread into the factory.
+ * @throws {CliError} On any arity, naming, JSON, or date-coercion failure.
+ */
+export declare function resolveCliFirestoreQueryArgs(input: ResolveCliFirestoreQueryArgsInput): unknown[];