@dereekb/dbx-cli 13.11.18 → 13.12.0

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

@@ -0,0 +1,366 @@
+/**
+ * Arktype schemas for the model-firebase-index manifest format.
+ *
+ * Manifests catalog the Firestore query-constraint factories opted in via
+ * the `@dbxModelFirebaseIndex` JSDoc marker — `*.query.ts` exports whose
+ * `where`/`orderBy` constraint sequences imply a required composite index
+ * or `fieldOverrides` entry in `firestore.indexes.json`. One manifest per
+ * source — bundled `@dereekb/firebase` plus any downstream-app manifests
+ * discovered via `dbx-mcp.config.json` — feeds the merged registry that
+ * powers the `dbx_model_firebase_index_lookup`,
+ * `dbx_model_firebase_index_search`, `dbx_model_firebase_index_list_app`,
+ * and `dbx_model_firebase_index_validate_app` MCP tools, and the
+ * `generate-firestore-indexes` CLI subcommand that emits a canonical
+ * `firestore.indexes.json` from the merged registry.
+ *
+ * Mirrors {@link ModelSnapshotFieldManifest} — both are tag-driven scanners
+ * over plain TS exports, so the schema shapes line up one-to-one. The
+ * model-firebase-index schema adds the Firestore-specific payload:
+ *   - `model` (the target TS type name)
+ *   - `collection` (the resolved short collection name, e.g. `'jlw'`)
+ *   - `isNested` (parent identity present, defaults scope to `COLLECTION_GROUP`)
+ *   - `scope` (`COLLECTION` | `COLLECTION_GROUP`)
+ *   - `manual` / `skip` flags from the JSDoc tags
+ *   - `constraintSequences` (raw extracted ordered constraints, one per
+ *     conditional-branch path)
+ *   - `derivedComposites` (required composite indexes after analysis)
+ *   - `derivedFieldOverrides` (required `fieldOverrides[]` contributions
+ *     after analysis — single-field `COLLECTION_GROUP` queries)
+ */
+/**
+ * Firestore query scopes. `COLLECTION` runs against one collection by path;
+ * `COLLECTION_GROUP` runs across every collection with the same id under any
+ * parent. Auto single-field indexes are `COLLECTION` scope only — anything
+ * `COLLECTION_GROUP` needs either a composite or a `fieldOverrides` entry.
+ */
+export declare const FIRESTORE_QUERY_SCOPES: readonly ["COLLECTION", "COLLECTION_GROUP"];
+/**
+ * Static type for {@link FIRESTORE_QUERY_SCOPES}.
+ */
+export type FirestoreQueryScope = (typeof FIRESTORE_QUERY_SCOPES)[number];
+/**
+ * Ascending vs descending for `orderBy`-bound index fields.
+ */
+export declare const FIRESTORE_INDEX_ORDERS: readonly ["ASCENDING", "DESCENDING"];
+/**
+ * Static type for {@link FIRESTORE_INDEX_ORDERS}.
+ */
+export type FirestoreIndexOrder = (typeof FIRESTORE_INDEX_ORDERS)[number];
+/**
+ * Array config for an index field — currently only `CONTAINS` (for
+ * `array-contains` / `array-contains-any`). Vector configs are out of scope.
+ */
+export declare const FIRESTORE_INDEX_ARRAY_CONFIGS: readonly ["CONTAINS"];
+/**
+ * Static type for {@link FIRESTORE_INDEX_ARRAY_CONFIGS}.
+ */
+export type FirestoreIndexArrayConfig = (typeof FIRESTORE_INDEX_ARRAY_CONFIGS)[number];
+/**
+ * Index density. Firestore's default for composites is `SPARSE_ALL` — skip
+ * documents missing any indexed field. Every composite in the live HelloSubs
+ * deploy carries this; the generator emits it on every entry so generated
+ * output round-trips cleanly against `firebase firestore:indexes`.
+ */
+export declare const FIRESTORE_INDEX_DENSITY_VALUES: readonly ["SPARSE_ALL", "SPARSE_ANY", "DENSE"];
+/**
+ * Static type for {@link FIRESTORE_INDEX_DENSITY_VALUES}.
+ */
+export type FirestoreIndexDensity = (typeof FIRESTORE_INDEX_DENSITY_VALUES)[number];
+/**
+ * Default density emitted by the generator. Matches the live HelloSubs deploy.
+ */
+export declare const DEFAULT_FIRESTORE_INDEX_DENSITY: FirestoreIndexDensity;
+/**
+ * Constraint kind inside a {@link ConstraintSequenceEntry}. `where` and
+ * `orderBy` are the base SDK calls; `helper` records an expanded helper
+ * (e.g. `whereDateIsBeforeWithSort`) so the source factory is faithful.
+ */
+export declare const FIRESTORE_CONSTRAINT_KINDS: readonly ["where", "orderBy"];
+/**
+ * Static type for {@link FIRESTORE_CONSTRAINT_KINDS}.
+ */
+export type FirestoreConstraintKind = (typeof FIRESTORE_CONSTRAINT_KINDS)[number];
+/**
+ * Closed vocabulary of Firestore `where` operators the extractor knows
+ * about. Drives the "is this equality / range / array-contains?" decision
+ * the analyzer uses to apply Firestore composite-field-order rules.
+ */
+export declare const FIRESTORE_WHERE_OPERATORS: readonly ["==", "!=", "<", "<=", ">", ">=", "in", "not-in", "array-contains", "array-contains-any"];
+/**
+ * Static type for {@link FIRESTORE_WHERE_OPERATORS}.
+ */
+export type FirestoreWhereOperator = (typeof FIRESTORE_WHERE_OPERATORS)[number];
+/**
+ * One constraint inside a {@link ConstraintSequence}. `kind` tells the
+ * analyzer which field-order bucket the entry falls into; `operator` is
+ * `where`-only; `direction` is `orderBy`-only; `fromHelper` records the
+ * source helper when the entry was expanded from one of the
+ * `firestoreQueryHelpers` registry entries (used for diagnostics).
+ */
+export declare const ConstraintSequenceEntry: import("arktype/internal/variants/object.ts").ObjectType<{
+    kind: "where" | "orderBy";
+    fieldPath: string;
+    operator?: ">" | ">=" | "<" | "<=" | "==" | "in" | "!=" | "not-in" | "array-contains" | "array-contains-any" | undefined;
+    direction?: "asc" | "desc" | undefined;
+    fromHelper?: string | undefined;
+}, {}>;
+/**
+ * Static type for {@link ConstraintSequenceEntry}.
+ */
+export type ConstraintSequenceEntry = typeof ConstraintSequenceEntry.infer;
+/**
+ * One linear path through a factory body. Conditional branches enumerate
+ * into multiple sequences. The generator dedupes equivalent index outputs;
+ * the sequence list itself is kept verbatim so diagnostics can point back
+ * to the source branch.
+ */
+export declare const ConstraintSequence: import("arktype/internal/variants/object.ts").ObjectType<{
+    entries: {
+        kind: "where" | "orderBy";
+        fieldPath: string;
+        operator?: ">" | ">=" | "<" | "<=" | "==" | "in" | "!=" | "not-in" | "array-contains" | "array-contains-any" | undefined;
+        direction?: "asc" | "desc" | undefined;
+        fromHelper?: string | undefined;
+    }[];
+    pathLabel?: string | undefined;
+}, {}>;
+/**
+ * Static type for {@link ConstraintSequence}.
+ */
+export type ConstraintSequence = typeof ConstraintSequence.infer;
+/**
+ * One field inside a derived composite index. Exactly one of `order` /
+ * `arrayConfig` is set.
+ */
+export declare const DerivedIndexField: import("arktype/internal/variants/object.ts").ObjectType<{
+    fieldPath: string;
+    order?: "ASCENDING" | "DESCENDING" | undefined;
+    arrayConfig?: "CONTAINS" | undefined;
+}, {}>;
+/**
+ * Static type for {@link DerivedIndexField}.
+ */
+export type DerivedIndexField = typeof DerivedIndexField.infer;
+/**
+ * One composite index a factory requires. Field order matches Firestore's
+ * required form (equality → range → array-contains → orderBy). The
+ * `__name__` tiebreaker is NOT stored here — the generator appends it at
+ * emission time, picking direction from the last orderBy.
+ */
+export declare const DerivedComposite: import("arktype/internal/variants/object.ts").ObjectType<{
+    collectionGroup: string;
+    queryScope: "COLLECTION" | "COLLECTION_GROUP";
+    fields: {
+        fieldPath: string;
+        order?: "ASCENDING" | "DESCENDING" | undefined;
+        arrayConfig?: "CONTAINS" | undefined;
+    }[];
+    density: "SPARSE_ALL" | "SPARSE_ANY" | "DENSE";
+}, {}>;
+/**
+ * Static type for {@link DerivedComposite}.
+ */
+export type DerivedComposite = typeof DerivedComposite.infer;
+/**
+ * One single-field `fieldOverrides[]` variant a factory contributes. Only
+ * emitted for `COLLECTION_GROUP`-scope single-field queries (auto indexes
+ * cover the `COLLECTION`-scope case). The generator combines multiple
+ * factory contributions on the same `(collectionGroup, fieldPath)` plus
+ * the standard `COLLECTION` quartet, mirroring the live HelloSubs deploy
+ * shape.
+ */
+export declare const DerivedFieldOverrideVariant: import("arktype/internal/variants/object.ts").ObjectType<{
+    queryScope: "COLLECTION" | "COLLECTION_GROUP";
+    order?: "ASCENDING" | "DESCENDING" | undefined;
+    arrayConfig?: "CONTAINS" | undefined;
+}, {}>;
+/**
+ * Static type for {@link DerivedFieldOverrideVariant}.
+ */
+export type DerivedFieldOverrideVariant = typeof DerivedFieldOverrideVariant.infer;
+/**
+ * One `fieldOverrides[]` contribution from a factory. `collectionGroup`
+ * is the resolved short collection name, `fieldPath` is the field name
+ * the factory queries by, and `variants[]` lists the (scope, order or
+ * arrayConfig) tuples implied by the factory's constraint sequences.
+ */
+export declare const DerivedFieldOverride: import("arktype/internal/variants/object.ts").ObjectType<{
+    collectionGroup: string;
+    fieldPath: string;
+    variants: {
+        queryScope: "COLLECTION" | "COLLECTION_GROUP";
+        order?: "ASCENDING" | "DESCENDING" | undefined;
+        arrayConfig?: "CONTAINS" | undefined;
+    }[];
+}, {}>;
+/**
+ * Static type for {@link DerivedFieldOverride}.
+ */
+export type DerivedFieldOverride = typeof DerivedFieldOverride.infer;
+/**
+ * One documented parameter of a query-factory function. Mirrors
+ * {@link ModelSnapshotFieldParamEntry} so the same JSDoc-`@param`
+ * extraction logic can be reused.
+ */
+export declare const ModelFirebaseIndexParamEntry: import("arktype/internal/variants/object.ts").ObjectType<{
+    name: string;
+    type: string;
+    description: string;
+    optional: boolean;
+}, {}>;
+/**
+ * Static type for {@link ModelFirebaseIndexParamEntry}.
+ */
+export type ModelFirebaseIndexParamEntry = typeof ModelFirebaseIndexParamEntry.infer;
+/**
+ * One model-firebase-index entry inside a manifest. Each entry describes a
+ * single `@dbxModelFirebaseIndex`-tagged query factory — its slug, target
+ * model, resolved collection name, scope, constraint sequences, and the
+ * indexes/field-overrides it requires.
+ *
+ * Required fields are the minimum needed for
+ * `dbx_model_firebase_index_lookup` to render a useful answer; every other
+ * field is optional so the extractor can populate them progressively.
+ */
+export declare const ModelFirebaseIndexEntry: import("arktype/internal/variants/object.ts").ObjectType<{
+    slug: string;
+    name: string;
+    module: string;
+    subpath: string;
+    signature: string;
+    description: string;
+    model: string;
+    collection: string;
+    isNested: boolean;
+    scope: "COLLECTION" | "COLLECTION_GROUP";
+    manual: boolean;
+    skip: boolean;
+    category: string;
+    params: {
+        name: string;
+        type: string;
+        description: string;
+        optional: boolean;
+    }[];
+    returns: string;
+    tags: string[];
+    constraintSequences: {
+        entries: {
+            kind: "where" | "orderBy";
+            fieldPath: string;
+            operator?: ">" | ">=" | "<" | "<=" | "==" | "in" | "!=" | "not-in" | "array-contains" | "array-contains-any" | undefined;
+            direction?: "asc" | "desc" | undefined;
+            fromHelper?: string | undefined;
+        }[];
+        pathLabel?: string | undefined;
+    }[];
+    derivedComposites: {
+        collectionGroup: string;
+        queryScope: "COLLECTION" | "COLLECTION_GROUP";
+        fields: {
+            fieldPath: string;
+            order?: "ASCENDING" | "DESCENDING" | undefined;
+            arrayConfig?: "CONTAINS" | undefined;
+        }[];
+        density: "SPARSE_ALL" | "SPARSE_ANY" | "DENSE";
+    }[];
+    derivedFieldOverrides: {
+        collectionGroup: string;
+        fieldPath: string;
+        variants: {
+            queryScope: "COLLECTION" | "COLLECTION_GROUP";
+            order?: "ASCENDING" | "DESCENDING" | undefined;
+            arrayConfig?: "CONTAINS" | undefined;
+        }[];
+    }[];
+    specOnly?: boolean | undefined;
+    excluded?: boolean | undefined;
+    example?: string | undefined;
+    relatedSlugs?: string[] | undefined;
+    skillRefs?: string[] | undefined;
+    deprecated?: string | boolean | undefined;
+    since?: string | undefined;
+}, {}>;
+/**
+ * Static type for {@link ModelFirebaseIndexEntry}.
+ */
+export type ModelFirebaseIndexEntry = typeof ModelFirebaseIndexEntry.infer;
+/**
+ * Top-level manifest envelope. One file per source. The `source` field is
+ * the workspace-unique label used to detect collisions; `module` carries
+ * the npm package the entries ship in.
+ *
+ * `version` is the schema version. The loader currently accepts only
+ * `version: 1`; manifests with any other value are rejected (strict
+ * sources) or warned-and-skipped (non-strict sources).
+ */
+export declare const ModelFirebaseIndexManifest: import("arktype/internal/variants/object.ts").ObjectType<{
+    version: 1;
+    source: string;
+    module: string;
+    generatedAt: string;
+    generator: string;
+    entries: {
+        slug: string;
+        name: string;
+        module: string;
+        subpath: string;
+        signature: string;
+        description: string;
+        model: string;
+        collection: string;
+        isNested: boolean;
+        scope: "COLLECTION" | "COLLECTION_GROUP";
+        manual: boolean;
+        skip: boolean;
+        category: string;
+        params: {
+            name: string;
+            type: string;
+            description: string;
+            optional: boolean;
+        }[];
+        returns: string;
+        tags: string[];
+        constraintSequences: {
+            entries: {
+                kind: "where" | "orderBy";
+                fieldPath: string;
+                operator?: ">" | ">=" | "<" | "<=" | "==" | "in" | "!=" | "not-in" | "array-contains" | "array-contains-any" | undefined;
+                direction?: "asc" | "desc" | undefined;
+                fromHelper?: string | undefined;
+            }[];
+            pathLabel?: string | undefined;
+        }[];
+        derivedComposites: {
+            collectionGroup: string;
+            queryScope: "COLLECTION" | "COLLECTION_GROUP";
+            fields: {
+                fieldPath: string;
+                order?: "ASCENDING" | "DESCENDING" | undefined;
+                arrayConfig?: "CONTAINS" | undefined;
+            }[];
+            density: "SPARSE_ALL" | "SPARSE_ANY" | "DENSE";
+        }[];
+        derivedFieldOverrides: {
+            collectionGroup: string;
+            fieldPath: string;
+            variants: {
+                queryScope: "COLLECTION" | "COLLECTION_GROUP";
+                order?: "ASCENDING" | "DESCENDING" | undefined;
+                arrayConfig?: "CONTAINS" | undefined;
+            }[];
+        }[];
+        specOnly?: boolean | undefined;
+        excluded?: boolean | undefined;
+        example?: string | undefined;
+        relatedSlugs?: string[] | undefined;
+        skillRefs?: string[] | undefined;
+        deprecated?: string | boolean | undefined;
+        since?: string | undefined;
+    }[];
+}, {}>;
+/**
+ * Static type for {@link ModelFirebaseIndexManifest}.
+ */
+export type ModelFirebaseIndexManifest = typeof ModelFirebaseIndexManifest.infer;

package/generate-firestore-indexes/main.js

@@ -5,7 +5,7 @@ const require = __createRequire(import.meta.url);
 // packages/dbx-cli/generate-firestore-indexes/package.json
 var package_default = {
   name: "@dereekb/dbx-cli-generate-firestore-indexes",
-  version: "13.11.18",
+  version: "13.12.0",
   private: true,
   type: "module",
   devDependencies: {

package/generate-firestore-indexes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-generate-firestore-indexes",
-  "version": "13.11.18",
+  "version": "13.12.0",
   "private": true,
   "type": "module",
   "devDependencies": {

package/generate-mcp-manifest/src/generate-mcp-manifest/main.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Generates a pre-rendered MCP manifest JSON file from a generated CliApiManifest.
+ *
+ * Pipeline (build-time, run via `nx run <demo-api>:generate-mcp-manifest`):
+ *
+ *   1. Load the TS module passed via `--input`, expecting either an `<X>_API_MANIFEST`
+ *      named export or a default export typed as `CliApiManifest`. The file is loaded
+ *      via dynamic `import()` so it must compile under ESM — same as the demo-cli
+ *      manifests written by `dbx-cli-generate-firebase-api-manifest`.
+ *   2. Run the pure {@link renderMcpManifest} renderer to pre-merge descriptions,
+ *      enrich the input JSON Schema with `paramsFields[]` descriptions, and
+ *      synthesize an `outputSchema` from `resultFields[]`.
+ *   3. Write the result to `<output>.tmp`, then `fs.renameSync` to `<output>` so
+ *      partial files never land on disk.
+ *
+ * Flags:
+ *   --input=<path>           (required) path to the *.api.manifest.generated.ts file.
+ *                             Absolute or workspace-relative.
+ *   --output=<path>          (required) destination JSON path (workspace-relative ok).
+ *   --regenerate-input       Reserved for a future revision that will invoke
+ *                             `dbx-cli-generate-firebase-api-manifest` first when the
+ *                             input file is missing. Today this flag is accepted but
+ *                             not honored; missing inputs still fail with a clear
+ *                             pointer to the right manifest target.
+ */
+export {};

package/generate-mcp-manifest/src/generate-mcp-manifest/render.d.ts

@@ -0,0 +1,38 @@
+import { type AuthRegistry, type CliApiManifest, type CliModelManifest, type McpManifest } from '@dereekb/dbx-cli';
+/**
+ * Inputs to {@link renderMcpManifest}.
+ */
+export interface RenderMcpManifestInput {
+    /**
+     * Generated API manifest used to render tool entries.
+     */
+    readonly apiManifest: CliApiManifest;
+    /**
+     * Optional generated model manifest. When present, projects each entry into
+     * the runtime {@link McpManifestModelEntry} shape and emits a `models` array
+     * on the output JSON for the runtime's built-in catalog tools.
+     */
+    readonly modelManifest?: CliModelManifest;
+    /**
+     * Optional auth registry + primary-app slug used to project the runtime
+     * `auth` section on the manifest. The renderer filters entries to the
+     * primary app's claim catalog (inherited claims like `fr` are included
+     * via the app's `claimKeys` list).
+     */
+    readonly auth?: {
+        readonly registry: AuthRegistry;
+        readonly app: string;
+    };
+}
+/**
+ * Pure renderer: turns a {@link CliApiManifest} (and optional {@link CliModelManifest})
+ * into the {@link McpManifest} JSON shape.
+ *
+ * No file I/O — the main entry handles writing. Skips `verb === 'standalone'` entries
+ * (they aren't dispatched through callModel and have no MCP tool counterpart).
+ *
+ * @param input - The render config carrying the API manifest and optional model manifest.
+ * @param now - Override for the `generatedAt` timestamp. Tests pass a fixed value.
+ * @returns The rendered MCP manifest with tools keyed by {@link mcpManifestKey} and an optional models array.
+ */
+export declare function renderMcpManifest(input: RenderMcpManifestInput, now?: Date): McpManifest;

package/generated/firebase-models.generated.d.ts

@@ -0,0 +1,3 @@
+import type { FirebaseModel, FirebaseModelGroup } from '../src/lib/mcp-scan/registry/firebase-models.js';
+export declare const FIREBASE_MODELS: readonly FirebaseModel[];
+export declare const FIREBASE_MODEL_GROUPS: readonly FirebaseModelGroup[];