@dereekb/dbx-cli 13.11.4 → 13.11.5

package/manifest-extract/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "13.11.4",
+  "version": "13.11.5",
   "sideEffects": false,
   "peerDependencies": {
     "ts-morph": "^21.0.0"

package/manifest-extract/src/index.d.ts

@@ -1,2 +1,3 @@
 export * from './lib/extract-crud';
+export * from './lib/extract-models';
 export * from './lib/types';

package/manifest-extract/src/lib/extract-models.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-source-file walker that pulls Firestore-model metadata out of a `.ts`
+ * file: identities, `@dbxModel`-tagged interfaces with their property JSDocs,
+ * snapshot converters (top-level `snapshotConverterFunctions`,
+ * `firestoreSubObject`, and `firestoreObjectArray` consts), enums, and
+ * `@dbxModelGroup`-tagged collection containers.
+ *
+ * Mirrors the per-file outputs of `dbx-components-mcp`'s `extractModels()`
+ * but lives inside `@dereekb/dbx-cli/manifest-extract` so the `dbx-cli`
+ * build pipeline can reuse it without taking on a runtime dependency on the
+ * MCP package. The orchestrator that stitches per-file outputs into a
+ * downstream-shape `CliModelManifest` lives in
+ * `packages/dbx-cli/firebase-api-manifest/src/generate-api-manifest/`.
+ */
+import type { ModelExtraction } from './types';
+/**
+ * Inputs for {@link extractModelsFromSource}.
+ */
+export interface ExtractModelsFromSourceInput {
+    readonly name: string;
+    readonly text: string;
+}
+/**
+ * Walks a single source file and reports raw model-extraction artifacts.
+ * Best-effort: a malformed call shape leaves the corresponding entry out
+ * rather than throwing.
+ *
+ * @param input - in-memory `{ name, text }` source pair.
+ * @returns the per-file extraction. Aggregation across files happens in the
+ *   firebase-api-manifest orchestrator so cross-file converter consts can be
+ *   resolved against a global registry.
+ */
+export declare function extractModelsFromSource(input: ExtractModelsFromSourceInput): ModelExtraction;

package/manifest-extract/src/lib/types.d.ts

@@ -84,3 +84,151 @@ export interface CrudExtraction {
      */
     readonly functionsClassName?: string;
 }
+/**
+ * One `firestoreModelIdentity(...)` declaration found by
+ * {@link ../lib/extract-models#extractModelsFromSource}.
+ */
+export interface ModelExtractionIdentity {
+    readonly identityConst: string;
+    readonly modelType: string;
+    readonly collectionPrefix: string | undefined;
+    readonly parentIdentityConst: string | undefined;
+}
+/**
+ * One property on a `@dbxModel`-tagged interface.
+ */
+export interface ModelExtractionInterfaceProp {
+    readonly name: string;
+    readonly tsType: string;
+    readonly optional: boolean;
+    readonly description: string | undefined;
+    /**
+     * Long form parsed from the property's `@dbxModelVariable <name>` JSDoc tag,
+     * when present.
+     */
+    readonly longName: string | undefined;
+    /**
+     * Description parsed from the property's `@dbxModelVariableSyncFlag …` JSDoc
+     * tag, when present.
+     */
+    readonly syncFlag: string | undefined;
+}
+/**
+ * One exported `interface` declaration. The walker captures every exported
+ * interface so cross-interface lookups (e.g. nested interface refs from a
+ * sub-object converter) work; the orchestrator filters by
+ * `hasDbxModelTag` to find the canonical model interfaces.
+ */
+export interface ModelExtractionInterface {
+    readonly name: string;
+    readonly description: string | undefined;
+    readonly hasDbxModelTag: boolean;
+    readonly extendsNames: readonly string[];
+    readonly props: readonly ModelExtractionInterfaceProp[];
+}
+/**
+ * One field inside a converter's `fields` map.
+ */
+export interface ModelExtractionConverterField {
+    readonly key: string;
+    /**
+     * Verbatim expression text of the field's value (whitespace collapsed).
+     */
+    readonly converter: string;
+    /**
+     * Name of a referenced converter const when the field's expression is
+     * `firestoreObjectArray({ objectField: <const> })` or
+     * `firestoreSubObject({ objectField: <const> })`. Resolved by the
+     * orchestrator against the cross-file converter registry.
+     */
+    readonly nestedConverterRef?: string;
+    /**
+     * Inline nested converter when the field's expression is
+     * `firestoreObjectArray({ objectField: { fields: { … } } })` or
+     * `firestoreSubObject({ objectField: { fields: { … } } })`.
+     */
+    readonly nestedConverterInline?: ModelExtractionConverter;
+    /**
+     * `true` when the wrapping factory is `firestoreObjectArray` (array element
+     * shape); `false` for `firestoreSubObject`. Only meaningful when one of
+     * `nestedConverterRef` or `nestedConverterInline` is set.
+     */
+    readonly nestedIsArray?: boolean;
+}
+/**
+ * One snapshot-converter call. Captures both top-level
+ * `export const <X>Converter = snapshotConverterFunctions<…>(…)` declarations
+ * and inline `firestoreSubObject(…)` / `firestoreObjectArray(…)` calls
+ * embedded in another converter's field map.
+ */
+export interface ModelExtractionConverter {
+    /**
+     * Name of the variable this converter is assigned to. `undefined` when the
+     * converter is an inline literal inside another converter's field map.
+     */
+    readonly converterConst: string | undefined;
+    /**
+     * Factory function that produced the converter
+     * (`snapshotConverterFunctions` / `firestoreSubObject` / `firestoreObjectArray`).
+     */
+    readonly factory: string;
+    /**
+     * Generic interface-name argument (e.g. `NotificationBox`), with any nested
+     * generic arguments stripped. `undefined` when the call had no type
+     * arguments.
+     */
+    readonly interfaceName: string | undefined;
+    /**
+     * Source-line number of the converter declaration (1-based) for diagnostics.
+     */
+    readonly line: number;
+    readonly fields: readonly ModelExtractionConverterField[];
+}
+/**
+ * One enum value with its JSDoc paragraph and persisted literal value.
+ */
+export interface ModelExtractionEnumValue {
+    readonly name: string;
+    readonly value: number | string;
+    readonly description: string | undefined;
+}
+/**
+ * One `export enum` declaration found in the source.
+ */
+export interface ModelExtractionEnum {
+    readonly name: string;
+    readonly values: readonly ModelExtractionEnumValue[];
+    readonly description: string | undefined;
+}
+/**
+ * One `<X>FirestoreCollections` container tagged with `@dbxModelGroup`.
+ */
+export interface ModelExtractionGroup {
+    /**
+     * Group name parsed from the `@dbxModelGroup <name>` JSDoc tag.
+     */
+    readonly name: string;
+    /**
+     * Container interface name (e.g. `NotificationFirestoreCollections`).
+     */
+    readonly containerName: string;
+    readonly description: string | undefined;
+    /**
+     * Model names referenced by the container's `<X>FirestoreCollection` /
+     * `<X>FirestoreCollectionFactory` properties, in source order.
+     */
+    readonly modelNames: readonly string[];
+}
+/**
+ * Per-source-file output of {@link ../lib/extract-models#extractModelsFromSource}.
+ *
+ * Aggregation across files happens in the firebase-api-manifest orchestrator
+ * so cross-file converter consts can be resolved against a global registry.
+ */
+export interface ModelExtraction {
+    readonly identities: readonly ModelExtractionIdentity[];
+    readonly interfaces: readonly ModelExtractionInterface[];
+    readonly converters: readonly ModelExtractionConverter[];
+    readonly enums: readonly ModelExtractionEnum[];
+    readonly modelGroups: readonly ModelExtractionGroup[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "13.11.4",
+  "version": "13.11.5",
   "sideEffects": false,
   "bin": {
     "dbx-cli-generate-firebase-api-manifest": "firebase-api-manifest/main.js"
@@ -24,10 +24,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.11.4",
-    "@dereekb/firebase": "13.11.4",
-    "@dereekb/nestjs": "13.11.4",
-    "@dereekb/util": "13.11.4",
+    "@dereekb/date": "13.11.5",
+    "@dereekb/firebase": "13.11.5",
+    "@dereekb/nestjs": "13.11.5",
+    "@dereekb/util": "13.11.5",
     "arktype": "^2.2.0",
     "yargs": "^18.0.0"
   },

package/src/lib/api/expand-keys.d.ts

@@ -0,0 +1,31 @@
+import type { CliModelManifest, CliModelManifestEntry } from '../manifest/types';
+/**
+ * Resolves the manifest entry for `modelType`. Lookup tries
+ * `modelType` first, then falls back to `identityConst` and `collectionPrefix`
+ * so callers can pass any of the three forms a user might type at the CLI.
+ *
+ * @param modelType - identifier to look up.
+ * @param manifest - generated model manifest.
+ * @returns the matching entry, or `undefined` when none exists.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function findCliModelManifestEntry(modelType: string, manifest: CliModelManifest): CliModelManifestEntry | undefined;
+/**
+ * Rewrites the persisted (short) keys in `data` to the long-name form
+ * declared in the model's manifest entry. Recurses into nested object-array
+ * and sub-object fields when the manifest captured a nested field map.
+ *
+ * Returns the input untouched when `modelType` is not in the manifest, when
+ * the model has no fields, or when the input is not a plain object/array.
+ * Unknown keys, primitives, `Date`, `null`, and `undefined` pass through
+ * unchanged.
+ *
+ * @param modelType - the model identifier (`modelType`, `identityConst`,
+ *   or `collectionPrefix`) used to look up the rewrite map.
+ * @param data - the value to rewrite (typically a `read`/`query` response
+ *   payload).
+ * @param manifest - generated model manifest.
+ * @returns the rewritten value, or `data` unchanged when no rewrite applies.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function expandModelKeys(modelType: string, data: unknown, manifest: CliModelManifest): unknown;

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

@@ -1,3 +1,4 @@
 export * from './call-model.client';
 export * from './call-model.command.factory';
 export * from './call.passthrough.command';
+export * from './expand-keys';

package/src/lib/manifest/build-manifest-commands.d.ts

@@ -1,5 +1,5 @@
 import { type CommandModule } from 'yargs';
-import { type CliApiManifest } from './types';
+import { type CliApiManifest, type CliModelManifest } from './types';
 /**
  * Controls which sections of an action's `--help` epilogue are rendered.
  *
@@ -79,6 +79,17 @@ export interface BuildManifestCommandsOptions {
      * full invocation reads `<cli> model <model> <action>`.
      */
     readonly modelCommandName?: string;
+    /**
+     * Generated model manifest used to power the per-action `--expand-keys`
+     * flag. When supplied, a payload returned from the `/model/call` endpoint
+     * is rewritten to use the long-name form of each persisted field (recursing
+     * into nested object-array and sub-object converters captured in the
+     * manifest).
+     *
+     * Optional. When omitted the flag is not registered and result payloads are
+     * emitted with their original short keys.
+     */
+    readonly modelManifest?: CliModelManifest;
 }
 /**
  * Default name of the parent command that groups all per-model manifest commands.

package/src/lib/manifest/build-model-info-command.d.ts

@@ -0,0 +1,37 @@
+import type { CommandModule } from 'yargs';
+import type { CliModelManifest } from './types';
+/**
+ * Default command name for the model-info command. Top-level so it stays out
+ * of the API-call namespace owned by `model <model> <action>`.
+ */
+export declare const DEFAULT_MODEL_INFO_COMMAND_NAME = "model-info";
+/**
+ * Options accepted by {@link buildModelInfoCommand}.
+ */
+export interface BuildModelInfoCommandOptions {
+    /**
+     * Override the parent command name. Defaults to
+     * {@link DEFAULT_MODEL_INFO_COMMAND_NAME}.
+     */
+    readonly commandName?: string;
+}
+/**
+ * Builds the top-level `model-info [model]` command.
+ *
+ * Without an argument: prints a column-aligned table summarising every model
+ * in the manifest. With an argument: looks the model up by `modelType`,
+ * `identityConst`, or `collectionPrefix` and prints its full per-field
+ * documentation, recursing into nested converters when the manifest captured
+ * them.
+ *
+ * Flags:
+ *   - `--json` emits a structured `{ ok, data }` envelope instead of the
+ *     human-readable table (useful for scripting or LLM agents).
+ *   - `--fields` prints only the field table for the resolved model.
+ *
+ * @param manifest - The generated model manifest (e.g. `DEMO_CLI_MODEL_MANIFEST`).
+ * @param options - Optional overrides; see {@link BuildModelInfoCommandOptions}.
+ * @returns A yargs `CommandModule` ready to be passed to `runCli({ configCommands })`.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function buildModelInfoCommand(manifest: CliModelManifest, options?: BuildModelInfoCommandOptions): CommandModule;

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

@@ -1,2 +1,4 @@
 export * from './build-manifest-commands';
+export * from './build-model-info-command';
+export * from './model-info-utils';
 export * from './types';

package/src/lib/manifest/model-info-utils.d.ts

@@ -0,0 +1,40 @@
+import type { CliModelManifest, CliModelManifestEntry } from './types';
+/**
+ * Resolves the manifest entry for `query` against `modelType`, `identityConst`,
+ * and `collectionPrefix` in that order.
+ *
+ * Re-exports {@link findCliModelManifestEntry} under a more descriptive name
+ * for the model-info command.
+ *
+ * @param manifest - the generated model manifest.
+ * @param query - identifier to look up.
+ * @returns the matching entry or `undefined`.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function resolveCliModel(manifest: CliModelManifest, query: string): CliModelManifestEntry | undefined;
+/**
+ * Produces a column-aligned summary table of every model in the manifest.
+ *
+ * @param manifest - the generated model manifest.
+ * @returns the formatted table as a single string with a trailing newline.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function renderModelManifestList(manifest: CliModelManifest): string;
+/**
+ * Produces a human-readable summary of one model entry: header, description,
+ * and an indented field tree (recursing into `nestedFields`).
+ *
+ * @param entry - the manifest entry to render.
+ * @returns the formatted summary as a single string with a trailing newline.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function renderModelManifestEntry(entry: CliModelManifestEntry): string;
+/**
+ * Produces the field-table portion of {@link renderModelManifestEntry} on its
+ * own, used by the `--fields` flag of the `model-info` command.
+ *
+ * @param entry - the manifest entry whose fields should be rendered.
+ * @returns the formatted field tree as a single string with a trailing newline.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function renderModelManifestFields(entry: CliModelManifestEntry): string;

package/src/lib/manifest/types.d.ts

@@ -1,4 +1,130 @@
 import { type Type } from 'arktype';
+/**
+ * One persisted field on a {@link CliModelManifestEntry}.
+ *
+ * Captures both the persisted (Firestore) short key and the human-readable
+ * long name from the model's `@dbxModelVariable` JSDoc tag, plus the verbatim
+ * converter expression text and any nested converter shape (for
+ * `firestoreObjectArray` / `firestoreSubObject` fields) so downstream tooling
+ * can recursively rewrite payload keys.
+ */
+export interface CliModelField {
+    /**
+     * Persisted Firestore short key (e.g. `fn`, `cat`, `gc`).
+     */
+    readonly name: string;
+    /**
+     * Human-readable long name resolved from the interface property's
+     * `@dbxModelVariable` JSDoc tag. Falls back to `name` when no tag is
+     * declared and the persisted key is already long-form.
+     */
+    readonly longName: string;
+    /**
+     * Verbatim converter expression text from the converter's `fields` literal
+     * (e.g. `firestoreDate()`, `firestoreObjectArray({ objectField: foo })`).
+     */
+    readonly converter: string;
+    /**
+     * TypeScript type text from the interface property declaration, when the
+     * field's interface property could be located (e.g. `Date`, `Maybe<NotificationUserState>`).
+     */
+    readonly tsType?: string;
+    /**
+     * `true` when the interface property is optional (`?`) or typed as `Maybe<>`,
+     * or when the converter is an `optionalFirestore...()` factory.
+     */
+    readonly optional: boolean;
+    /**
+     * First paragraph of the interface property's JSDoc, when present.
+     */
+    readonly description?: string;
+    /**
+     * Enum name referenced by either the interface property's TS type or the
+     * converter's `firestoreEnum<Enum>()` generic argument, when an enum is
+     * present in the same source file.
+     */
+    readonly enumRef?: string;
+    /**
+     * Free-text description from the interface property's
+     * `@dbxModelVariableSyncFlag` JSDoc tag, when present.
+     */
+    readonly syncFlag?: string;
+    /**
+     * Recursively-resolved nested fields when this field's converter is a
+     * `firestoreObjectArray({ objectField: ... })` or
+     * `firestoreSubObject({ objectField: ... })` call whose inner converter
+     * could be resolved (either inline or via cross-file converter const).
+     *
+     * Absent when the converter is opaque (custom helper, dynamic expression,
+     * `firestoreEnum`, primitive factory, etc.).
+     */
+    readonly nestedFields?: readonly CliModelField[];
+    /**
+     * `true` when the nested fields describe an array element shape
+     * (`firestoreObjectArray`); `false` for sub-object fields. Only meaningful
+     * when {@link nestedFields} is set.
+     */
+    readonly nestedIsArray?: boolean;
+}
+/**
+ * One Firestore model entry in a downstream CLI's `<NAMESPACE>_MODEL_MANIFEST`.
+ *
+ * Generated at build time by `dbx-cli-generate-firebase-api-manifest` from the
+ * same source packages it walks for the API manifest. Drives both the
+ * `model-info` command's catalog/per-model help and the `--expand-keys` flag's
+ * payload-rewrite behaviour.
+ */
+export interface CliModelManifestEntry {
+    /**
+     * Persisted model type id (e.g. `notificationBox`, `profile`).
+     */
+    readonly modelType: string;
+    /**
+     * Pascal-case model name as declared by the source interface (e.g.
+     * `NotificationBox`).
+     */
+    readonly modelName: string;
+    /**
+     * Group name from the source `@dbxModelGroup` tag on the
+     * `<X>FirestoreCollections` container (e.g. `Notification`, `Profile`).
+     */
+    readonly modelGroup?: string;
+    /**
+     * Identity const name from the source file (e.g. `notificationBoxIdentity`).
+     */
+    readonly identityConst: string;
+    /**
+     * Collection-name prefix used by the identity (e.g. `nb`, `p`).
+     */
+    readonly collectionPrefix: string;
+    /**
+     * Parent identity const name when the model is a subcollection.
+     */
+    readonly parentIdentityConst?: string;
+    /**
+     * First paragraph of the source interface's JSDoc, when present.
+     */
+    readonly description?: string;
+    /**
+     * Source package providing the model (e.g. `@dereekb/firebase`,
+     * `demo-firebase`).
+     */
+    readonly sourcePackage: string;
+    /**
+     * Workspace-relative path of the source `.ts` file that declares the model.
+     */
+    readonly sourceFile: string;
+    /**
+     * Persisted-field metadata in source order.
+     */
+    readonly fields: readonly CliModelField[];
+}
+/**
+ * Generated array of {@link CliModelManifestEntry} consumed by `model-info`
+ * and the `--expand-keys` rewrite. Each downstream CLI app exports its own
+ * `<NAMESPACE>_MODEL_MANIFEST` of this type.
+ */
+export type CliModelManifest = readonly CliModelManifestEntry[];
 export type CliApiVerb = 'create' | 'read' | 'update' | 'delete' | 'query' | 'standalone';
 export interface CliApiManifestField {
     readonly name: string;

package/src/lib/runner/run.d.ts

@@ -1,6 +1,7 @@
 import { type Argv, type CommandModule } from 'yargs';
 import { type CliEnvDefault } from '../config/env';
 import { type DoctorCheck } from '../doctor/doctor.command.factory';
+import { type CliModelManifest } from '../manifest/types';
 /**
  * Names of the global options registered by {@link createCli} that are not
  * specific to a single manifest command's payload. Manifest commands hide
@@ -43,6 +44,30 @@ export interface CreateCliInput {
      * Disable the built-in `call` passthrough — useful when an app prefers to expose only typed wrappers.
      */
     readonly disableCallPassthrough?: boolean;
+    /**
+     * Generated Firestore model manifest used to drive the built-in `model-info` command.
+     *
+     * Opt-in: when provided, a top-level `model-info [model]` command is auto-wired into the built-in
+     * config commands so users can browse the model catalog and per-model field documentation. When
+     * omitted, no `model-info` command is registered. Apps that pass the manifest but want to suppress
+     * the command can additionally set {@link disableModelInfo} to `true`.
+     *
+     * The manifest itself is also opt-in at build time. The `dbx-cli-firebase-api-manifest` generator
+     * only emits `<NAMESPACE>_MODEL_MANIFEST` when invoked with `--emit-models`, so apps that never
+     * enable this option won't bundle model metadata into their final binary.
+     *
+     * Note: this option only controls the `model-info` command. Manifest-driven typed model commands
+     * are still wired explicitly via {@link apiCommands} (see `buildManifestCommands`), and the
+     * `--expand-keys` flag still requires passing the manifest to `buildManifestCommands`.
+     */
+    readonly modelManifest?: CliModelManifest;
+    /**
+     * Disable the built-in `model-info` command even when {@link modelManifest} is provided.
+     *
+     * Useful when an app wants the manifest available for `--expand-keys` (via `buildManifestCommands`)
+     * but does not want to surface the `model-info` command itself.
+     */
+    readonly disableModelInfo?: boolean;
 }
 /**
  * Top-level CLI builder.
@@ -61,6 +86,10 @@ export interface CreateCliInput {
  * @param input.defaultEnvs - Built-in env presets shipped with the CLI.
  * @param input.argv - Argv to parse. Defaults to `hideBin(process.argv)`.
  * @param input.disableCallPassthrough - When `true`, omits the built-in `call` passthrough.
+ * @param input.modelManifest - Optional Firestore model manifest. When provided, auto-wires the
+ *   built-in `model-info` command. Opt-in per app.
+ * @param input.disableModelInfo - When `true`, suppresses the auto-wired `model-info` command even
+ *   if {@link CreateCliInput.modelManifest} is provided.
  * @returns The configured yargs `Argv` ready to be `.parse()`-d.
  * @__NO_SIDE_EFFECTS__
  */