@dereekb/dbx-cli 13.11.17 → 13.12.0

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

@@ -1,3 +1,4 @@
+import type { Maybe } from '@dereekb/util';
 import { type Type } from 'arktype';
 /**
  * One persisted field on a {@link CliModelManifestEntry}.
@@ -122,6 +123,20 @@ export interface CliModelManifestEntry {
      * Persisted-field metadata in source order.
      */
     readonly fields: readonly CliModelField[];
+    /**
+     * Read posture declared by `@dbxModelRead <level>` on the model interface. Closed enum:
+     * `system` / `owner` / `admin-only` / `permissions`. Absent when the model interface omits the tag.
+     */
+    readonly read?: 'system' | 'owner' | 'admin-only' | 'permissions';
+    /**
+     * Resolved `@dbxModelServiceFactory <modelType>`-tagged export that implements this model.
+     * Joined by `modelType` during model-manifest assembly. Absent when no factory was found
+     * (surfaced as an orphan by the cross-file ESLint rule).
+     */
+    readonly serviceFactory?: {
+        readonly exportName: string;
+        readonly sourceFile: string;
+    };
 }
 /**
  * Generated array of {@link CliModelManifestEntry} consumed by `model-info`
@@ -168,3 +183,143 @@ export interface CliApiManifestEntry {
     readonly resultFields?: readonly CliApiManifestField[];
 }
 export type CliApiManifest = readonly CliApiManifestEntry[];
+/**
+ * Version stamp embedded in the build-time MCP manifest JSON. Runtime loaders
+ * refuse manifests whose `version` does not match this constant.
+ */
+export declare const MCP_MANIFEST_VERSION: 1;
+/**
+ * One tool entry inside the build-time MCP manifest JSON.
+ *
+ * The renderer pre-merges descriptions, enriches the input schema with per-field
+ * `description` text, and synthesizes an `outputSchema` from `resultFields[]` so the
+ * runtime only has to do map lookups.
+ */
+export interface McpManifestToolEntry {
+    /**
+     * Merged tool description: `entry.description` joined with `entry.paramsTypeDescription`.
+     * Omitted when both source fields are absent.
+     */
+    readonly description?: string;
+    /**
+     * JSON Schema produced from the params validator and enriched with `paramsFields[]` descriptions.
+     * Omitted when neither validator nor fields produced a schema.
+     */
+    readonly inputSchema?: object;
+    /**
+     * JSON Schema synthesized from `resultFields[]` / `resultTypeDescription`. Omitted when both absent.
+     */
+    readonly outputSchema?: object;
+}
+/**
+ * One persisted field on a {@link McpManifestModelEntry}.
+ *
+ * Structural projection of {@link CliModelField} minus the converter expression
+ * text (CLI-only). Keeps the runtime payload narrow for downstream MCP tools.
+ */
+export interface McpManifestModelField {
+    readonly name: string;
+    readonly longName: string;
+    readonly tsType?: string;
+    readonly optional: boolean;
+    readonly description?: string;
+    readonly enumRef?: string;
+    readonly syncFlag?: string;
+    readonly nestedFields?: readonly McpManifestModelField[];
+    readonly nestedIsArray?: boolean;
+}
+/**
+ * One Firestore model entry in the build-time MCP manifest JSON.
+ *
+ * Structural projection of {@link CliModelManifestEntry} consumed at runtime by
+ * the firebase-server/mcp built-in `model-info` and `model-decode` tools.
+ */
+export interface McpManifestModelEntry {
+    readonly modelType: string;
+    readonly modelName: string;
+    readonly modelGroup?: string;
+    readonly identityConst: string;
+    readonly collectionPrefix: string;
+    readonly parentIdentityConst?: string;
+    readonly description?: string;
+    readonly sourcePackage: string;
+    readonly sourceFile: string;
+    readonly fields: readonly McpManifestModelField[];
+}
+/**
+ * One auth claim entry in the pre-rendered MCP manifest JSON. Powers the
+ * runtime `whoami` tool. Source paths and line numbers are stripped — only
+ * the catalog-facing fields survive.
+ */
+export interface McpManifestAuthClaim {
+    readonly key: string;
+    readonly description: string;
+    readonly type: string;
+    readonly app?: string;
+    readonly interfaceName?: string;
+    readonly source: 'system' | 'app';
+    readonly mapping: {
+        readonly roles: readonly string[];
+        readonly inverse: boolean;
+        readonly inverseMode?: 'any' | 'all';
+        readonly claimValue?: string | number | boolean;
+        readonly customEncodeDecode: boolean;
+    };
+    readonly tags: readonly string[];
+}
+/**
+ * One auth app entry in the pre-rendered MCP manifest JSON.
+ *
+ * `auth.app` denotes the manifest's primary app (the host that emitted the
+ * manifest). `auth.apps` carries the full list, which may include the primary
+ * plus inherited apps (e.g. `storageFile-upload-user`).
+ */
+export interface McpManifestAuthApp {
+    readonly app: string;
+    readonly claimsInterfaceName: string;
+    readonly serviceConstName: string;
+    readonly claimKeys: readonly string[];
+    readonly scopes: readonly string[];
+    readonly description?: string;
+}
+/**
+ * Auth section of the pre-rendered MCP manifest JSON. Optional — runtimes
+ * built before this section landed simply skip registering whoami.
+ */
+export interface McpManifestAuth {
+    readonly app?: McpManifestAuthApp;
+    readonly apps: readonly McpManifestAuthApp[];
+    readonly claims: readonly McpManifestAuthClaim[];
+}
+/**
+ * Build-time MCP manifest JSON shape consumed by the runtime MCP module's optional manifest loader.
+ *
+ * `tools` is keyed by {@link mcpManifestKey} so the runtime can do O(1) lookups per registered tool.
+ * `models` is optional — the runtime skips the catalog-introspection tools when missing.
+ * `auth` is optional — drives the runtime `whoami` tool.
+ */
+export interface McpManifest {
+    readonly version: typeof MCP_MANIFEST_VERSION;
+    /**
+     * ISO-8601 timestamp captured when the manifest was rendered. Useful for diagnostics.
+     */
+    readonly generatedAt: string;
+    readonly tools: {
+        readonly [key: string]: McpManifestToolEntry | undefined;
+    };
+    readonly models?: readonly McpManifestModelEntry[];
+    readonly auth?: McpManifestAuth;
+}
+/**
+ * Builds the canonical MCP manifest key for a (modelType, callType, specifier) triple.
+ *
+ * The default-specifier entry collapses to `_` so the runtime can compose the same
+ * key from its dispatch coordinates without first checking whether the handler is
+ * behind a specifier router.
+ *
+ * @param modelType - The Firestore model type (e.g., `guestbook`).
+ * @param call - The call type / verb (e.g., `query`).
+ * @param specifier - The specifier key, or `_` / undefined for the default entry.
+ * @returns The canonical `modelType.call.specifier` lookup key, with the default specifier normalized to `_`.
+ */
+export declare function mcpManifestKey(modelType: string, call: string, specifier?: Maybe<string>): string;

package/src/lib/mcp-scan/config/config-schema.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Arktype schema for `dbx-mcp.config.json`.
+ *
+ * The config file lives at the workspace root and carries three kinds of
+ * settings:
+ *
+ * 1. `<cluster>.sources` — repo-relative paths to *external* generated
+ *    manifests merged alongside the bundled `@dereekb/*` registries.
+ * 2. `<cluster>.scan` — per-package scan inputs that drive bundled-manifest
+ *    generation (replacing the per-package `dbx-mcp.scan.json` files this
+ *    repo previously shipped).
+ * 3. `modelValidate` — overrides for the firebase-model rule pipeline
+ *    (field-name length limit, ignored field names).
+ *
+ * The bundled registries are *always* loaded; `sources` adds extras. The
+ * `scan` array is consumed by `scripts/generate-manifests.mjs` at build
+ * time. `modelValidate` is read once at server bootstrap and threaded into
+ * `dbx_model_validate`'s rule options.
+ */
+/**
+ * One entry in `<cluster>.scan[]`. Mirrors the shape of the legacy
+ * per-package `dbx-mcp.scan.json` plus a `project` field that names the
+ * package directory the scan should target. Fields are intentionally a
+ * permissive superset across all six clusters — semantic-types entries
+ * carry `topicNamespace` / `declaredTopics`, cluster-with-section entries
+ * carry `module`, and per-cluster CLIs read only the fields they care
+ * about.
+ */
+declare const ScanEntry: import("arktype/internal/variants/object.ts").ObjectType<{
+    project: string;
+    source: string;
+    out: string;
+    include?: string[] | undefined;
+    exclude?: string[] | undefined;
+    topicNamespace?: string | undefined;
+    declaredTopics?: string[] | undefined;
+    module?: string | undefined;
+}, {}>;
+/**
+ * Top-level config schema. Missing-but-optional cluster keys mean the
+ * MCP runs with only its bundled `@dereekb/*` manifests, which is the
+ * intended default for fresh installs.
+ */
+export declare const DbxMcpConfig: import("arktype/internal/variants/object.ts").ObjectType<{
+    version: 1;
+    modelValidate?: {
+        maxFieldNameLength?: number | undefined;
+        ignoredFieldNames?: string[] | undefined;
+        ignoredExternalParents?: string[] | undefined;
+    } | undefined;
+    logs?: {
+        basePath?: string | undefined;
+        defaultProject?: string | undefined;
+    } | undefined;
+    semanticTypes?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    uiComponents?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    forgeFields?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    pipes?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    actions?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    filters?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    tokens?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    cssUtilities?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    utils?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    modelSnapshotFields?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    modelFirebaseIndex?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    dbxDocsUiExamples?: {
+        sources?: string[] | undefined;
+        scan?: {
+            project: string;
+            source: string;
+            out: string;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            topicNamespace?: string | undefined;
+            declaredTopics?: string[] | undefined;
+            module?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    uiSmellCheck?: {
+        projectConventions?: {
+            cardWrapperClasses?: string[] | undefined;
+        } | undefined;
+    } | undefined;
+}, {}>;
+/**
+ * Static type inferred from {@link DbxMcpConfig}.
+ */
+export type DbxMcpConfig = typeof DbxMcpConfig.infer;
+/**
+ * Static type inferred from `ScanEntry`. Exported so the build
+ * orchestrator and per-cluster CLIs can share one canonical entry type.
+ */
+export type DbxMcpScanEntry = typeof ScanEntry.infer;
+export {};

package/src/lib/mcp-scan/config/load-config.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Loader for `dbx-mcp.config.json`.
+ *
+ * Reads the config file from `${cwd}/dbx-mcp.config.json` (no upward walk —
+ * the MCP is always launched at the repo root, mirroring the cwd contract
+ * that the existing `validate-input.ts` security check relies on).
+ *
+ * Failure modes are surfaced as warnings rather than thrown errors. A
+ * missing file is *not* a warning — it is the expected default for fresh
+ * installs that haven't opted into downstream manifests yet. Parse and
+ * schema failures are warnings so the rest of the MCP can still come up;
+ * the caller decides whether to log or escalate.
+ */
+import type { Maybe } from '@dereekb/util';
+import { DbxMcpConfig } from './config-schema.js';
+/**
+ * Function shape used by the loader to read the config file. Defaults to
+ * `node:fs/promises.readFile(path, 'utf-8')`. Tests inject a Map-backed
+ * implementation so they can drive the loader without touching disk.
+ */
+export type ConfigReadFile = (absolutePath: string) => Promise<string>;
+/**
+ * Discriminated union of the non-fatal events the config loader emits.
+ * A missing file is *not* represented here — that case returns `null`
+ * config + empty warnings.
+ */
+export type ConfigWarning = {
+    readonly kind: 'config-parse-failed';
+    readonly path: string;
+    readonly error: string;
+} | {
+    readonly kind: 'config-schema-failed';
+    readonly path: string;
+    readonly error: string;
+};
+/**
+ * Result of {@link findAndLoadConfig}. `config` is `null` either when no
+ * file is present or when parsing/validation failed; `configPath` is set
+ * iff a file was actually found, regardless of whether parsing succeeded.
+ */
+export interface FindAndLoadConfigResult {
+    readonly config: Maybe<DbxMcpConfig>;
+    readonly configPath: Maybe<string>;
+    readonly warnings: readonly ConfigWarning[];
+}
+/**
+ * Input to {@link findAndLoadConfig}.
+ */
+export interface FindAndLoadConfigInput {
+    readonly cwd: string;
+    readonly readFile?: ConfigReadFile;
+}
+/**
+ * Reads `${cwd}/dbx-mcp.config.json` and returns its parsed contents.
+ * Missing files return `{ config: null, configPath: null, warnings: [] }`
+ * (not an error — the file is optional). Parse and schema failures
+ * return `{ config: null, configPath: <found path>, warnings: [...] }`
+ * so the caller can decide how loud to be about the failure.
+ *
+ * @param input - Cwd and an optional injected `readFile`
+ * @returns The parsed config, the path it came from, and any warnings.
+ */
+export declare function findAndLoadConfig(input: FindAndLoadConfigInput): Promise<FindAndLoadConfigResult>;

package/src/lib/mcp-scan/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Umbrella barrel for the dbx-components MCP scan infrastructure.
+ *
+ * Three subdirs:
+ *  - `registry/`  — typed metadata catalogs (`FIREBASE_MODELS`, archetypes,
+ *    auth, semantic types, etc.) used by runtime MCP tools and build-time CLIs.
+ *  - `scan/`      — ts-morph-backed source extractors and `generate-mcp-manifest`
+ *    cluster CLIs that walk workspace source to build the catalog JSON files.
+ *  - `manifest/`  — arktype-validated schemas + loader helpers that hydrate the
+ *    runtime registries from those JSON files.
+ */
+export * from './config/config-schema.js';
+export * from './config/load-config.js';
+export * from './registry/index.js';
+export * from './scan/index.js';
+export * from './manifest/index.js';

package/src/lib/mcp-scan/manifest/actions-loader.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Loader for actions manifests.
+ *
+ * Reads one or more manifest files, validates them against
+ * {@link ActionManifest}, and merges them into a single lookup-ready
+ * registry. Mirrors the pipes / forge-fields / ui-components loaders via
+ * the shared {@link loadManifestsBase} core.
+ */
+import { type ActionEntry } from './actions-schema.js';
+import { type ManifestLoaderWarning, type ManifestReadFile, type ManifestSource } from './manifest-loader-base.js';
+/**
+ * One manifest the loader is asked to ingest. `path` must be absolute.
+ */
+export type ActionManifestSource = ManifestSource;
+/**
+ * Function shape used by the loader to read manifest contents.
+ */
+export type ActionManifestReadFile = ManifestReadFile;
+/**
+ * Discriminated union of all non-fatal events the loader emits.
+ */
+export type ActionLoaderWarning = ManifestLoaderWarning;
+/**
+ * Input to {@link loadActionManifests}.
+ */
+export interface LoadActionManifestsInput {
+    readonly sources: readonly ActionManifestSource[];
+    readonly readFile?: ActionManifestReadFile;
+}
+/**
+ * Result of {@link loadActionManifests}. `entries` is the merged lookup map
+ * keyed by `${module}::${slug}`; `roleIndex` is the inverted index from role
+ * to entry keys. `warnings` is sorted deterministically.
+ */
+export interface LoadActionManifestsResult {
+    readonly entries: ReadonlyMap<string, ActionEntry>;
+    readonly roleIndex: ReadonlyMap<string, readonly string[]>;
+    readonly warnings: readonly ActionLoaderWarning[];
+    readonly loadedSources: readonly string[];
+}
+/**
+ * Loads, validates, and merges the supplied manifest sources into a single
+ * registry suitable for the `dbx_action_lookup` MCP tool.
+ *
+ * @param input - Manifest sources plus an optional injected `readFile`
+ * @returns Merged entries, role index, deterministic warnings, and the list of source labels that loaded.
+ * @throws {Error} When a strict source fails or when zero manifests load successfully.
+ */
+export declare function loadActionManifests(input: LoadActionManifestsInput): Promise<LoadActionManifestsResult>;