@dereekb/dbx-cli 13.37.0 → 13.39.0

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[];

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

@@ -0,0 +1,79 @@
+import { type FirestoreModelKey, type FirestoreQueryConstraint } from '@dereekb/firebase';
+import { type CliFirestoreQueryManifestEntry } from '../manifest/types';
+import { type CliFirestoreModels } from './firestore.models';
+/**
+ * One row returned by {@link runCliFirestoreQuery}.
+ */
+export interface CliFirestoreQueryRow {
+    readonly key: FirestoreModelKey;
+    readonly id: string;
+    readonly data: unknown;
+}
+/**
+ * The result envelope of a `firestore-query` run.
+ */
+export interface CliFirestoreQueryResult {
+    readonly slug: string;
+    readonly model: string;
+    readonly collection: string;
+    readonly scope: string;
+    readonly parent?: FirestoreModelKey;
+    /**
+     * Present unless `--count` was passed.
+     */
+    readonly rows?: readonly CliFirestoreQueryRow[];
+    /**
+     * Row count — the length of {@link rows}, or the `countDocs()` result under `--count`.
+     */
+    readonly count: number;
+    readonly source: 'firestore';
+}
+/**
+ * Input for {@link runCliFirestoreQuery}.
+ */
+export interface RunCliFirestoreQueryInput {
+    readonly models: CliFirestoreModels;
+    readonly entry: CliFirestoreQueryManifestEntry;
+    readonly params?: string;
+    readonly rawParams?: boolean;
+    readonly parent?: FirestoreModelKey;
+    readonly limit?: number;
+    /**
+     * Return only the count, with no rows.
+     */
+    readonly count?: boolean;
+}
+/**
+ * Resolves the constraint list a catalog entry produces for the supplied `--params`.
+ *
+ * Split out from {@link runCliFirestoreQuery} so the constraints can be inspected (or executed
+ * against a different sink, e.g. a future `--watch`) without running the query.
+ *
+ * @param input - The constraint inputs.
+ * @param input.entry - The catalog entry whose factory is called.
+ * @param input.params - The raw `--params` string, if supplied.
+ * @param input.rawParams - When true, disables date coercion on the params.
+ * @param input.limit - Replaces the factory's own `limit()` when supplied.
+ * @returns The resolved constraints.
+ * @throws {CliError} When the entry is not invocable, or the params do not fit its signature.
+ */
+export declare function cliFirestoreQueryConstraints(input: {
+    readonly entry: CliFirestoreQueryManifestEntry;
+    readonly params?: string;
+    readonly rawParams?: boolean;
+    readonly limit?: number;
+}): FirestoreQueryConstraint[];
+/**
+ * Executes a catalog entry against Firestore over the direct session.
+ *
+ * Rows come from `getDocSnapshotDataPairs()` + the per-document converter, which costs ONE read per
+ * row. `getDocs()` would cost two: `queryLike` is converter-less on both root collections and
+ * groups, so it re-loads every matched document from its ref purely to apply the converter. Going
+ * through `pair.document.converter` (rather than `collection.queryLike.withConverter(...)`) also
+ * honours per-ref converters, such as a stored-data map keyed by document id.
+ *
+ * @param input - The models view, the entry, and the run options.
+ * @returns The query result envelope.
+ * @throws {CliError} On an argument, scoping, or invocability failure. Firestore's own errors (rules, missing index) surface via `cliFirestoreErrorMapper`.
+ */
+export declare function runCliFirestoreQuery(input: RunCliFirestoreQueryInput): Promise<CliFirestoreQueryResult>;