@dereekb/dbx-cli 13.11.18 → 13.12.0

package/firebase-api-manifest/main.js

@@ -161,7 +161,7 @@ import { join as join2 } from "node:path";
 
 // packages/dbx-cli/manifest-extract/src/lib/extract-crud.ts
 import { Node as Node2, Project as Project2 } from "ts-morph";
-var SUPPORTED_VERBS = /* @__PURE__ */ new Set(["create", "read", "update", "delete", "query"]);
+var SUPPORTED_VERBS = /* @__PURE__ */ new Set(["create", "read", "update", "delete", "query", "invoke"]);
 function extractCrudEntries(source) {
   const project = new Project2({ useInMemoryFileSystem: true, skipAddingFilesFromTsConfig: true });
   const sourceFile = project.createSourceFile(source.name, source.text, { overwrite: true });
@@ -426,6 +426,9 @@ function readJsDocSummary(node) {
 
 // packages/dbx-cli/manifest-extract/src/lib/extract-models.ts
 import { Node as Node3, Project as Project3 } from "ts-morph";
+var READ_LEVEL_VALUES = /* @__PURE__ */ new Set(["system", "owner", "admin-only", "permissions"]);
+var SERVICE_FACTORY_TAG = "dbxModelServiceFactory";
+var MODEL_TYPE_VALUE_PATTERN = /^[a-z][A-Za-z0-9_$]*$/;
 var PASSTHROUGH_TYPE_WRAPPERS = /* @__PURE__ */ new Set(["Partial", "Required", "Readonly", "NonNullable", "MaybeMap", "Pick", "Omit"]);
 var IDENTITY_FN = "firestoreModelIdentity";
 var CONVERTER_FN_NAMES = ["snapshotConverterFunctions", "firestoreSubObject", "firestoreObjectArray"];
@@ -442,7 +445,8 @@ function extractModelsFromSource(input) {
   const converters = readConverters(sourceFile);
   const enums = readEnums(sourceFile);
   const modelGroups = readModelGroups(sourceFile);
-  return { identities, interfaces, converters, enums, modelGroups };
+  const serviceFactories = readServiceFactories(sourceFile);
+  return { identities, interfaces, converters, enums, modelGroups, serviceFactories };
 }
 function readIdentities(sourceFile) {
   const out = [];
@@ -497,6 +501,7 @@ function readInterfaces(sourceFile) {
 function buildInterface(decl) {
   const jsDocs = decl.getJsDocs();
   const hasDbxModelTag = jsDocsHaveTag(jsDocs, "dbxModel");
+  const dbxModelRead = readDbxModelReadTag(jsDocs);
   const extendsNames = decl.getExtends().map(resolveExtendsName);
   const props = [];
   for (const prop of decl.getProperties()) {
@@ -519,9 +524,54 @@ function buildInterface(decl) {
     description: readJsDocDescription(jsDocs),
     hasDbxModelTag,
     extendsNames,
-    props
+    props,
+    ...dbxModelRead === void 0 ? {} : { dbxModelRead }
   };
 }
+function readDbxModelReadTag(jsDocs) {
+  let result;
+  for (const doc of jsDocs) {
+    for (const tag of doc.getTags()) {
+      if (tag.getTagName() !== "dbxModelRead") continue;
+      if (result !== void 0) continue;
+      const raw = tag.getCommentText()?.trim();
+      if (raw === void 0 || raw.length === 0) continue;
+      const firstToken = raw.split(/\s+/)[0];
+      if (READ_LEVEL_VALUES.has(firstToken)) {
+        result = firstToken;
+      }
+    }
+  }
+  return result;
+}
+function readServiceFactories(sourceFile) {
+  const out = [];
+  for (const statement of sourceFile.getVariableStatements()) {
+    if (!statement.isExported()) continue;
+    const modelType = readServiceFactoryModelType(statement.getJsDocs());
+    if (modelType === void 0) continue;
+    for (const decl of statement.getDeclarations()) {
+      out.push({ modelType, exportName: decl.getName() });
+    }
+  }
+  return out;
+}
+function readServiceFactoryModelType(jsDocs) {
+  let result;
+  for (const doc of jsDocs) {
+    for (const tag of doc.getTags()) {
+      if (tag.getTagName() !== SERVICE_FACTORY_TAG) continue;
+      if (result !== void 0) continue;
+      const raw = tag.getCommentText()?.trim();
+      if (raw === void 0 || raw.length === 0) continue;
+      const firstToken = raw.split(/\s+/)[0];
+      if (MODEL_TYPE_VALUE_PATTERN.test(firstToken)) {
+        result = firstToken;
+      }
+    }
+  }
+  return result;
+}
 function resolveExtendsName(expr) {
   const head = expr.getExpression().getText();
   let result = head;
@@ -850,14 +900,14 @@ function findModelFiles(packageRoot) {
       const text = readFileSync4(filePath, "utf8");
       if (!textHasModelMarker(text)) continue;
       const extraction = extractModelsFromSource({ name: filePath, text });
-      if (extraction.identities.length === 0 && extraction.modelGroups.length === 0 && extraction.converters.length === 0) continue;
+      if (extraction.identities.length === 0 && extraction.modelGroups.length === 0 && extraction.converters.length === 0 && extraction.serviceFactories.length === 0) continue;
       out.push({ filePath, extraction });
     }
   }
   return out;
 }
 function textHasModelMarker(text) {
-  return text.includes("firestoreModelIdentity(") || text.includes("@dbxModelGroup") || text.includes("snapshotConverterFunctions") || text.includes("firestoreSubObject") || text.includes("firestoreObjectArray");
+  return text.includes("firestoreModelIdentity(") || text.includes("@dbxModelGroup") || text.includes("snapshotConverterFunctions") || text.includes("firestoreSubObject") || text.includes("firestoreObjectArray") || text.includes("@dbxModelServiceFactory");
 }
 function* walkSourceFiles(dir) {
   for (const entry of readdirSync2(dir).sort()) {
@@ -901,12 +951,18 @@ function buildGlobalRegistries(extractions) {
   const converterRegistry = /* @__PURE__ */ new Map();
   const interfaceRegistry = /* @__PURE__ */ new Map();
   const groupByModelName = /* @__PURE__ */ new Map();
-  for (const { extraction } of extractions) {
+  const serviceFactoryByModelType = /* @__PURE__ */ new Map();
+  for (const { extraction, sourceFile } of extractions) {
     registerConverters(extraction.converters, converterRegistry);
     registerInterfaces(extraction.interfaces, interfaceRegistry);
     registerModelGroups(extraction.modelGroups, groupByModelName);
+    for (const factory of extraction.serviceFactories) {
+      if (!serviceFactoryByModelType.has(factory.modelType)) {
+        serviceFactoryByModelType.set(factory.modelType, { exportName: factory.exportName, sourceFile });
+      }
+    }
   }
-  return { converterRegistry, interfaceRegistry, groupByModelName };
+  return { converterRegistry, interfaceRegistry, groupByModelName, serviceFactoryByModelType };
 }
 function registerConverters(converters, registry) {
   for (const converter of converters) {
@@ -957,6 +1013,7 @@ function buildEntryForIdentity(input) {
           visitedConverters: /* @__PURE__ */ new Set()
         });
         const modelGroup = registries.groupByModelName.get(modelName);
+        const serviceFactory = registries.serviceFactoryByModelType.get(identity.modelType);
         result = {
           modelType: identity.modelType,
           modelName,
@@ -967,7 +1024,9 @@ function buildEntryForIdentity(input) {
           ...iface.description ? { description: iface.description } : {},
           sourcePackage: source.sourcePackage,
           sourceFile: source.sourceFile,
-          fields
+          fields,
+          ...iface.dbxModelRead ? { read: iface.dbxModelRead } : {},
+          ...serviceFactory ? { serviceFactory } : {}
         };
       }
     }
@@ -1290,7 +1349,9 @@ function renderModelEntry(entry, emitConverters) {
     entry.description ? `description: ${JSON.stringify(entry.description)}` : void 0,
     `sourcePackage: ${JSON.stringify(entry.sourcePackage)}`,
     `sourceFile: ${JSON.stringify(entry.sourceFile)}`,
-    `fields: ${renderModelFields(entry.fields, emitConverters)}`
+    `fields: ${renderModelFields(entry.fields, emitConverters)}`,
+    entry.read ? `read: ${JSON.stringify(entry.read)}` : void 0,
+    entry.serviceFactory ? `serviceFactory: { exportName: ${JSON.stringify(entry.serviceFactory.exportName)}, sourceFile: ${JSON.stringify(entry.serviceFactory.sourceFile)} }` : void 0
   ];
   return `  { ${fields.filter((v) => Boolean(v)).join(", ")} }`;
 }

package/firebase-api-manifest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-firebase-api-manifest",
-  "version": "13.11.18",
+  "version": "13.12.0",
   "private": true,
   "type": "module",
   "devDependencies": {

package/firestore-indexes/src/firestore-indexes-generate.d.ts

@@ -0,0 +1,125 @@
+/**
+ * `firestore.indexes.json` generator.
+ *
+ * Consumes the {@link ModelFirebaseIndexRegistry} and produces the
+ * canonical `firestore.indexes.json` payload (composites + fieldOverrides)
+ * Firebase deploys against. Encodes the live-deploy shape observed in
+ * HelloSubs:
+ *
+ *   - Every composite ends with a `__name__` tiebreaker whose direction
+ *     matches the last orderBy in the entry.
+ *   - Every composite carries `density: "SPARSE_ALL"`.
+ *   - Every COLLECTION_GROUP single-field variant in a `fieldOverrides`
+ *     entry is emitted alongside the standard COLLECTION quartet
+ *     (ASCENDING/DESCENDING/CONTAINS) so the auto-indexes Firebase would
+ *     have created at COLLECTION scope are explicitly preserved.
+ *
+ * Preserves user-authored content that the analyzer can't produce:
+ *
+ *   - `fieldOverrides[]` entries whose `(collection, fieldPath)` no
+ *     analyzed factory touches (TTL flags, hand-trimmed overrides like
+ *     `sjs.adat`, vector indexes, etc.).
+ *   - `indexes[]` entries tied to slugs that carry the
+ *     `@dbxModelFirebaseIndexManual` JSDoc tag — round-tripped untouched.
+ *
+ * Returns the new JSON + a structured diff (`added`, `removed`,
+ * `unchanged`) so the CLI / MCP tool can render a clear CI report.
+ */
+import type { ModelFirebaseIndexEntryInfo } from './model-firebase-index-runtime.js';
+/**
+ * `firestore.indexes.json` top-level shape.
+ */
+export interface FirestoreIndexesJson {
+    readonly indexes: readonly FirestoreIndexJsonEntry[];
+    readonly fieldOverrides: readonly FirestoreFieldOverrideJsonEntry[];
+}
+/**
+ * One `indexes[]` entry. Mirrors the Firestore Admin API schema with the
+ * `density` field included (Firebase CLI emits this on every export).
+ */
+export interface FirestoreIndexJsonEntry {
+    readonly collectionGroup: string;
+    readonly queryScope: 'COLLECTION' | 'COLLECTION_GROUP';
+    readonly fields: readonly FirestoreIndexJsonField[];
+    readonly density?: 'SPARSE_ALL' | 'SPARSE_ANY' | 'DENSE';
+}
+/**
+ * One `fields[]` member of an `indexes[]` entry. Includes the `__name__`
+ * tiebreaker the generator appends at emission time.
+ */
+export interface FirestoreIndexJsonField {
+    readonly fieldPath: string;
+    readonly order?: 'ASCENDING' | 'DESCENDING';
+    readonly arrayConfig?: 'CONTAINS';
+}
+/**
+ * One `fieldOverrides[]` entry.
+ */
+export interface FirestoreFieldOverrideJsonEntry {
+    readonly collectionGroup: string;
+    readonly fieldPath: string;
+    readonly ttl?: boolean;
+    readonly indexes: readonly FirestoreFieldOverrideJsonVariant[];
+}
+/**
+ * One variant inside a `fieldOverrides[].indexes` array.
+ */
+export interface FirestoreFieldOverrideJsonVariant {
+    readonly queryScope: 'COLLECTION' | 'COLLECTION_GROUP';
+    readonly order?: 'ASCENDING' | 'DESCENDING';
+    readonly arrayConfig?: 'CONTAINS';
+}
+/**
+ * Input to {@link generateFirestoreIndexesJson}.
+ */
+export interface GenerateFirestoreIndexesJsonInput {
+    /**
+     * Every entry the registry knows about. Entries with `skip = true` or
+     * `manual = true` are filtered out by the generator — manual entries
+     * are preserved via {@link existingJson}.
+     */
+    readonly entries: readonly ModelFirebaseIndexEntryInfo[];
+    /**
+     * The current on-disk `firestore.indexes.json` if any, used to preserve
+     * user-authored content the generator can't reproduce.
+     */
+    readonly existingJson?: FirestoreIndexesJson;
+}
+/**
+ * Diff shape returned alongside the new JSON. Each list carries the
+ * canonical-key form of the index (or override) for inclusion in CI
+ * reports.
+ */
+export interface FirestoreIndexesDiff {
+    readonly added: readonly string[];
+    readonly removed: readonly string[];
+    readonly unchanged: readonly string[];
+    readonly fieldOverridesAdded: readonly string[];
+    readonly fieldOverridesRemoved: readonly string[];
+    readonly fieldOverridesUnchanged: readonly string[];
+}
+/**
+ * Output of {@link generateFirestoreIndexesJson}.
+ */
+export interface GenerateFirestoreIndexesJsonResult {
+    readonly json: FirestoreIndexesJson;
+    readonly diff: FirestoreIndexesDiff;
+}
+/**
+ * Generates a canonical `firestore.indexes.json` payload from the
+ * registry, preserving user-authored content from any prior on-disk
+ * version.
+ *
+ * @param input - The entries and (optionally) the existing JSON to merge against.
+ * @returns The new JSON payload plus a diff against the existing version.
+ */
+export declare function generateFirestoreIndexesJson(input: GenerateFirestoreIndexesJsonInput): GenerateFirestoreIndexesJsonResult;
+/**
+ * Serializes `firestore.indexes.json` with stable key ordering and a
+ * trailing newline so `--check` mode can byte-compare against the
+ * committed file without false-positive whitespace diffs.
+ *
+ * @param json - The indexes payload to serialise.
+ * @returns The canonical string form.
+ */
+export declare function serializeFirestoreIndexesJson(json: FirestoreIndexesJson): string;

package/firestore-indexes/src/firestore-model-identity-resolver.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Build-time resolver from a TS type name (`JobLocationWeek`) to the
+ * model's Firestore short collection name (`'jlw'`) and nested flag.
+ *
+ * The model-firebase-index extractor needs to map the
+ * `@dbxModelFirebaseIndexModel <TypeName>` tag value onto the
+ * `collectionPrefix` Firestore uses for the model — that's what becomes
+ * the `collectionGroup` field in `firestore.indexes.json`. The resolver
+ * builds a per-project map by walking the supplied ts-morph project for
+ * `firestoreModelIdentity(...)` calls, then exposes lookup-by-type-name
+ * (preferred), lookup-by-modelType (the first-string-arg), and
+ * lookup-by-identity-const (e.g. `jobLocationWeekIdentity`).
+ *
+ * For runtime use (the `dbx_model_firebase_index_*` MCP tools) the
+ * upstream `FIREBASE_MODELS` registry + downstream catalog provides the
+ * same data — see {@link buildIdentityResolverFromRegistries} below.
+ */
+import { type Project } from 'ts-morph';
+/**
+ * Resolution result for one model. `collection` is the short collection
+ * prefix used by Firestore (and the `collectionGroup` field in
+ * `firestore.indexes.json`). `isNested` is `true` when the identity
+ * declares a parent — these models default to `COLLECTION_GROUP` scope.
+ */
+export interface ResolvedFirestoreModelIdentity {
+    readonly modelType: string;
+    readonly collection: string;
+    readonly isNested: boolean;
+    readonly identityConstName: string;
+}
+/**
+ * Build-time identity resolver. Methods accept either the TS type name
+ * (`'JobLocationWeek'`), the modelType string (`'jobLocationWeek'`), or
+ * the identity-const name (`'jobLocationWeekIdentity'`) — extractors
+ * commonly have access to whichever surface lines up with how the tagged
+ * factory was written.
+ */
+export interface FirestoreModelIdentityResolver {
+    /**
+     * Lookup by the TS type / interface name (e.g. `JobLocationWeek`). The
+     * resolver tries the literal name, then the camelCase form, then the
+     * derived `<lowerCamelCase>Identity` const name.
+     */
+    readonly lookupByTypeName: (typeName: string) => ResolvedFirestoreModelIdentity | undefined;
+    /**
+     * Lookup by the first-arg `modelType` string passed to
+     * `firestoreModelIdentity(...)` — exact match.
+     */
+    readonly lookupByModelType: (modelType: string) => ResolvedFirestoreModelIdentity | undefined;
+    /**
+     * Lookup by the identity const name (e.g. `jobLocationWeekIdentity`) —
+     * exact match.
+     */
+    readonly lookupByIdentityConst: (identityConstName: string) => ResolvedFirestoreModelIdentity | undefined;
+    /**
+     * Every resolved record, useful for diagnostics.
+     */
+    readonly all: () => readonly ResolvedFirestoreModelIdentity[];
+}
+/**
+ * Walks the supplied ts-morph project looking for
+ * `<name>Identity = firestoreModelIdentity(...)` declarations and assembles
+ * a {@link FirestoreModelIdentityResolver}.
+ *
+ * Identifies three call shapes:
+ *   1. `firestoreModelIdentity('modelType', 'prefix')` — root identity.
+ *   2. `firestoreModelIdentity(parentIdentity, 'modelType', 'prefix')` — nested identity.
+ *   3. `firestoreModelIdentity('modelType')` — root identity with prefix-defaulted-to-modelType (rare; collection equals modelType).
+ *
+ * Calls that don't match any of these shapes are skipped silently — the
+ * extractor only consumes successful matches.
+ *
+ * @param project - The ts-morph project whose source files to scan.
+ * @returns The resolver.
+ */
+export declare function buildIdentityResolverFromProject(project: Project): FirestoreModelIdentityResolver;
+/**
+ * Builds a resolver from a pre-resolved list of records — used when the
+ * MCP tool runtime has access to {@link FIREBASE_MODELS} + the downstream
+ * catalog and doesn't need to rescan source files.
+ *
+ * @param records - The resolved identity records.
+ * @returns The resolver.
+ */
+export declare function buildIdentityResolverFromRecords(records: readonly ResolvedFirestoreModelIdentity[]): FirestoreModelIdentityResolver;
+/**
+ * Converts `JobLocationWeek` → `jobLocationWeek`. Pass-through when the
+ * input is already camelCase.
+ *
+ * @param typeName - The TypeScript type name.
+ * @returns The lowerCamelCase identifier.
+ */
+export declare function toCamelCase(typeName: string): string;

package/firestore-indexes/src/firestore-query-helpers.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Constraint-helper expansion registry used by the model-firebase-index
+ * extractor.
+ *
+ * The query factories under scan compose `@dereekb/firebase` helpers
+ * (`whereDateIsBeforeWithSort`, `whereDateIsBetween`,
+ * `allChildDocumentsUnderRelativePath`, …) that internally fan out to one
+ * or more base `where` / `orderBy` constraints. Static AST walking only
+ * sees the helper call — to derive the actual Firestore index requirements
+ * the extractor needs to know which base constraints the helper produces.
+ * This file is the source of truth for that mapping.
+ *
+ * Each entry declares:
+ *   - which positional argument carries the field path
+ *   - which positional argument carries the `OrderByDirection` (if any)
+ *   - the ordered base constraints the helper emits, with operators or
+ *     orderBy directions resolved from the call site when possible
+ *
+ * The extractor reads the call site, plugs the resolved field path and
+ * direction into the descriptor, and emits {@link ConstraintSequenceEntry}
+ * rows tagged with `fromHelper: <helperName>` so diagnostics remain
+ * faithful to the source factory.
+ */
+import type { ConstraintSequenceEntry, FirestoreWhereOperator } from './model-firebase-index-schema.js';
+/**
+ * Description of one base constraint a helper expands into. `direction`
+ * resolves at call-site time from the helper's direction argument when
+ * `useCallSiteDirection` is set; otherwise it falls back to the literal
+ * `direction` here. `operator` is required when `kind === 'where'`.
+ */
+export interface FirestoreQueryHelperExpansionPart {
+    readonly kind: 'where' | 'orderBy';
+    readonly operator?: FirestoreWhereOperator;
+    readonly direction?: 'asc' | 'desc';
+    /**
+     * When `true` and the helper resolves a direction from its call-site
+     * argument, override the literal `direction` above.
+     */
+    readonly useCallSiteDirection?: boolean;
+}
+/**
+ * One entry in the helper expansion registry.
+ */
+export interface FirestoreQueryHelperDescriptor {
+    /**
+     * Helper function name as it appears in source (e.g. `whereDateIsBetween`).
+     */
+    readonly name: string;
+    /**
+     * Index of the call argument carrying the field path. The extractor reads
+     * the string literal at this position (or the identifier when the call
+     * passes a `FieldPath` constant — currently treated as opaque, dropping
+     * the entry with a warning).
+     */
+    readonly fieldArgIndex: number;
+    /**
+     * Index of the call argument carrying the `OrderByDirection`. Undefined
+     * when the helper does not accept one (e.g. `whereDateIsBefore`).
+     */
+    readonly directionArgIndex?: number;
+    /**
+     * Default direction when the call-site direction argument is absent.
+     */
+    readonly defaultDirection?: 'asc' | 'desc';
+    /**
+     * Ordered list of the base constraints the helper expands into. Field
+     * path is the same for every part (helpers always operate on one field).
+     */
+    readonly parts: readonly FirestoreQueryHelperExpansionPart[];
+}
+/**
+ * Built-in helper expansions. Mirrors the upstream
+ * `@dereekb/firebase/constraint.template.ts` implementations as of writing.
+ * Helpers not listed here are extracted as a single opaque `where` call so
+ * the entry still surfaces during validation — the extractor emits a
+ * warning so a missing helper can be added here.
+ *
+ * Order within `parts` is significant: it mirrors the source helper's
+ * emitted constraint array order, which the analyzer treats as the user's
+ * intended Firestore index field order.
+ */
+export declare const FIRESTORE_QUERY_HELPERS: readonly FirestoreQueryHelperDescriptor[];
+/**
+ * Lookup helper by name. Returns `undefined` when the helper isn't in the
+ * registry — the extractor treats that as an opaque call (no constraints
+ * emitted) and surfaces a warning so the registry can be extended.
+ *
+ * @param name - The helper's source-level identifier.
+ * @returns The descriptor or undefined.
+ */
+export declare function getFirestoreQueryHelperDescriptor(name: string): FirestoreQueryHelperDescriptor | undefined;
+/**
+ * Resolves the constraint entries a helper call produces given the
+ * resolved field path and (optional) call-site direction. The extractor
+ * supplies the parsed values; this function applies the descriptor's
+ * `parts` template.
+ *
+ * @param input - The resolved descriptor + call-site values.
+ * @param input.descriptor - The looked-up helper descriptor.
+ * @param input.fieldPath - The resolved field path for the constraints.
+ * @param input.direction - Optional call-site direction override for orderBy parts.
+ * @returns The ordered constraint entries the helper emits.
+ */
+export declare function expandFirestoreQueryHelper(input: {
+    readonly descriptor: FirestoreQueryHelperDescriptor;
+    readonly fieldPath: string;
+    readonly direction?: 'asc' | 'desc';
+}): readonly ConstraintSequenceEntry[];

package/firestore-indexes/src/generate-firestore-indexes-cli.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `generate-firestore-indexes` subcommand entry point.
+ *
+ * Walks a downstream `-firebase` component for `@dbxModelFirebaseIndex`-
+ * tagged factories (the same pipeline `scan-model-firebase-indexes` uses),
+ * runs the analyzer, and emits a canonical `firestore.indexes.json`
+ * payload via {@link generateFirestoreIndexesJson}.
+ *
+ * Two modes:
+ *
+ *   - **write** (default) — write the generated JSON to `--output` (defaults to
+ *     `firestore.indexes.json` at the workspace root).
+ *   - **`--check`** — compare the generated JSON to the file on disk and exit
+ *     1 on drift. Used in CI to fail PRs that change query factories without
+ *     regenerating the indexes file.
+ *
+ * Preserves user-authored content that the analyzer can't reproduce: TTL
+ * fieldOverrides, vector indexes, hand-tuned single-field overrides like
+ * `sjs.adat`, and any composite tied to a `@dbxModelFirebaseIndexManual`
+ * factory (round-tripped verbatim from the existing file).
+ */
+/**
+ * Function shape used by the CLI to read existing files (the on-disk
+ * `firestore.indexes.json`). Defaults to `node:fs/promises.readFile`.
+ */
+export type GenerateFirestoreIndexesCliReadFile = (absolutePath: string) => Promise<string>;
+/**
+ * Function shape used by the CLI to write the produced file. Defaults to
+ * `node:fs/promises.writeFile`.
+ */
+export type GenerateFirestoreIndexesCliWriteFile = (absolutePath: string, data: string) => Promise<void>;
+/**
+ * Console sink for stdout and stderr lines.
+ */
+export type GenerateFirestoreIndexesCliLogger = (message: string) => void;
+/**
+ * Result of one CLI invocation.
+ */
+export interface RunGenerateFirestoreIndexesCliResult {
+    readonly exitCode: number;
+}
+/**
+ * Input to {@link runGenerateFirestoreIndexesCli}.
+ */
+export interface RunGenerateFirestoreIndexesCliInput {
+    /**
+     * Subcommand argv slice — everything after `generate-firestore-indexes`.
+     */
+    readonly argv: readonly string[];
+    /**
+     * Working directory the CLI resolves relative paths against.
+     */
+    readonly cwd: string;
+    /**
+     * Generator string written into the manifest source field (used for
+     * diagnostics only — the indexes file does not record this).
+     */
+    readonly generator: string;
+    /**
+     * Optional binary name printed in the `--help` usage banner so embedders
+     * (e.g. the `dbx-components-mcp generate-firestore-indexes` subcommand)
+     * can advertise the right invocation to their users. Defaults to
+     * `dbx-cli-generate-firestore-indexes`.
+     */
+    readonly binName?: string;
+    /**
+     * Optional now() override. Unused at present; reserved so callers can
+     * inject a stable clock when adding wall-time metadata in the future.
+     */
+    readonly now?: () => Date;
+    /**
+     * Optional file-reader override (e.g. tests that inject an in-memory FS).
+     */
+    readonly readFile?: GenerateFirestoreIndexesCliReadFile;
+    /**
+     * Optional file-writer override (e.g. tests that capture output without
+     * touching disk).
+     */
+    readonly writeFile?: GenerateFirestoreIndexesCliWriteFile;
+    /**
+     * Optional logger override. Defaults to console.log / console.error.
+     */
+    readonly stdout?: GenerateFirestoreIndexesCliLogger;
+    readonly stderr?: GenerateFirestoreIndexesCliLogger;
+}
+/**
+ * Runs one invocation of `generate-firestore-indexes`. Never throws on
+ * user errors — every failure path returns a structured exit code so
+ * callers can wire this into `process.exit` without try/catch.
+ *
+ * @param input - Argv plus injectable I/O hooks.
+ * @returns The CLI's exit code (0 on success / no drift, 1 on drift / failure, 2 on usage error)
+ */
+export declare function runGenerateFirestoreIndexesCli(input: RunGenerateFirestoreIndexesCliInput): Promise<RunGenerateFirestoreIndexesCliResult>;

package/firestore-indexes/src/index.d.ts

@@ -0,0 +1,7 @@
+export * from './firestore-indexes-generate';
+export * from './generate-firestore-indexes-cli';
+export * from './model-firebase-index-build-manifest';
+export * from './model-firebase-index-extract';
+export * from './model-firebase-index-runtime';
+export * from './model-firebase-index-scan-config-schema';
+export * from './model-firebase-index-schema';

package/firestore-indexes/src/model-firebase-index-analyze.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Index analyzer.
+ *
+ * Consumes the {@link ExtractedModelFirebaseIndexEntry}s produced by the
+ * extractor and decides, per `(collection, scope, constraintSequence)`,
+ * whether the query requires a composite index, a `fieldOverrides[]`
+ * variant, or neither (because Firestore's automatic single-field
+ * `COLLECTION`-scope index already covers the query). Encodes Firestore's
+ * field-order rule for composites:
+ *
+ *   1. Equality (`==`, `in`) fields first, in source order.
+ *   2. A single range/inequality field next (direction taken from any
+ *      explicit `orderBy` on the same field, else ASCENDING).
+ *   3. An optional `array-contains` field.
+ *   4. Remaining `orderBy` fields in source order, with their declared
+ *      direction.
+ *
+ * The `__name__` tiebreaker is NOT appended here — the generator does that
+ * at emission time, picking the direction to match the last orderBy.
+ *
+ * Returns one `derivedComposites` + one `derivedFieldOverrides` set per
+ * entry. The generator merges these across entries when building
+ * `firestore.indexes.json` (dedupe, canonical sort, COLLECTION-quartet
+ * companion fieldOverrides).
+ */
+import { type DerivedComposite, type DerivedFieldOverride } from './model-firebase-index-schema.js';
+import type { ExtractedModelFirebaseIndexEntry } from './model-firebase-index-extract.js';
+/**
+ * Per-factory analyzer output. The entry order matches the extractor's
+ * input order so warnings + diagnostics can point back to the factory.
+ */
+export interface AnalyzedEntry {
+    readonly extractedEntry: ExtractedModelFirebaseIndexEntry;
+    readonly derivedComposites: readonly DerivedComposite[];
+    readonly derivedFieldOverrides: readonly DerivedFieldOverride[];
+    readonly warnings: readonly AnalyzerWarning[];
+}
+/**
+ * Discriminated union of non-fatal events emitted during analysis.
+ */
+export type AnalyzerWarning = {
+    readonly kind: 'multiple-range-fields';
+    readonly factoryName: string;
+    readonly fields: readonly string[];
+} | {
+    readonly kind: 'orderby-conflict';
+    readonly factoryName: string;
+    readonly field: string;
+    readonly directions: readonly string[];
+} | {
+    readonly kind: 'unsupported-array-contains-any';
+    readonly factoryName: string;
+    readonly field: string;
+};
+/**
+ * Runs the analyzer over every extracted entry.
+ *
+ * @param entries - The extracted entries to analyze.
+ * @returns One analyzed result per input entry.
+ */
+export declare function analyzeModelFirebaseIndexEntries(entries: readonly ExtractedModelFirebaseIndexEntry[]): readonly AnalyzedEntry[];
+/**
+ * Runs the analyzer over a single extracted entry.
+ *
+ * @param entry - The extracted entry to analyze.
+ * @returns The analyzed result.
+ */
+export declare function analyzeEntry(entry: ExtractedModelFirebaseIndexEntry): AnalyzedEntry;