@dereekb/dbx-cli 13.11.17 → 13.12.0

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

@@ -0,0 +1,38 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadActionManifests}, and {@link createActionRegistry}.
+ *
+ * Resolves the bundled `@dereekb/*` actions manifests that ship inside this
+ * package's `generated/` directory and merges them with any external sources
+ * declared in `dbx-mcp.config.json` under `actions.sources`.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type ActionRegistry } from '../registry/actions-runtime.js';
+import { type ActionLoaderWarning, type ActionManifestReadFile } from './actions-loader.js';
+export type BundledActionManifestPathsFactory = () => readonly string[];
+export interface LoadActionRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledActionManifestPathsFactory;
+    readonly readFile?: ActionManifestReadFile;
+}
+export interface LoadActionRegistryResult {
+    readonly registry: ActionRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly ActionLoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged actions registry for the current MCP server.
+ *
+ * @param input - The load configuration: working directory, bundled manifest path factory, and file reader.
+ * @returns The combined registry, config path, and any warnings emitted while reading config or manifests.
+ */
+export declare function loadActionRegistry(input: LoadActionRegistryInput): Promise<LoadActionRegistryResult>;
+/**
+ * Returns the absolute paths of the action manifests bundled with this package.
+ *
+ * @returns The absolute paths to the bundled action manifest JSON files.
+ */
+export declare function getDefaultBundledActionManifestPaths(): readonly string[];

package/src/lib/mcp-scan/manifest/load-auth-registry.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Loader for the auth catalog.
+ *
+ * Walks the workspace looking for `claims.ts`-style downstream files
+ * (those tagged with `@dbxAuthClaimsApp`), parses them via the auth
+ * extractor, and merges the extracted entries with the bundled built-ins
+ * (`@dereekb/util` roles, the `fr` upload claim and the five `model.*` OIDC
+ * scopes from `@dereekb/firebase`).
+ *
+ * Discovery is intentionally cheap:
+ *   - Glob `components/*-{firebase,shared,web,core}/**/auth/*claims*.ts`
+ *   - Glob `apps/*/**/auth/*claims*.ts`
+ *   - Anything else is opt-in via `extraFiles` (used by tests).
+ *
+ * Files are read with the package's standard reader and pushed into an
+ * in-memory ts-morph project. Loader and extractor warnings are returned
+ * as structured objects so the server bootstrap can echo them on stderr.
+ */
+import { type AuthRegistry } from '../registry/auth-runtime.js';
+import { type AuthExtractWarning } from '../scan/auth-extract.js';
+import { type ScanReadFile } from '../../scan-helpers/scan-io.js';
+/**
+ * Discriminated union surfacing per-file failures the loader can't recover
+ * from. Forwarded to the server bootstrap so operators can spot mis-tagged
+ * downstream files at startup.
+ */
+export type AuthLoaderFileWarning = {
+    readonly kind: 'read-failed';
+    readonly relPath: string;
+    readonly error: string;
+} | {
+    readonly kind: 'parse-failed';
+    readonly relPath: string;
+    readonly error: string;
+};
+/**
+ * Result of {@link loadAuthRegistry}. The registry is always populated —
+ * it includes the bundled built-ins plus whatever extracted entries
+ * succeeded. Warnings are returned alongside so callers can decide
+ * whether to fail loudly or merely log.
+ */
+export interface LoadAuthRegistryResult {
+    readonly registry: AuthRegistry;
+    readonly extractWarnings: readonly AuthExtractWarning[];
+    readonly fileWarnings: readonly AuthLoaderFileWarning[];
+    readonly scannedFiles: readonly string[];
+    readonly extractedAppCount: number;
+    readonly extractedClaimCount: number;
+}
+/**
+ * Input to {@link loadAuthRegistry}. `extraFiles` is reserved for tests
+ * that want to inject in-memory claims modules instead of touching disk.
+ *
+ * `skipDiscovery: true` disables the workspace glob walk so only `extraFiles`
+ * are scanned. Used by build-time CLIs (e.g. `generate-mcp-manifest`) when
+ * the caller knows exactly which claims module(s) belong to their app.
+ */
+export interface LoadAuthRegistryInput {
+    readonly cwd: string;
+    readonly readFile?: ScanReadFile;
+    readonly extraFiles?: readonly string[];
+    readonly skipDiscovery?: boolean;
+}
+/**
+ * Discovers downstream `claims.ts` files, runs the auth extractor, and
+ * returns a fully composed {@link AuthRegistry} merged with the package's
+ * built-in roles/claims/scopes. Always returns a valid registry — when
+ * no downstream files are found, the registry contains only the
+ * built-ins.
+ *
+ * @param input - Workspace cwd plus optional injected reader / extra files.
+ * @returns The merged registry plus loader/extractor diagnostics.
+ */
+export declare function loadAuthRegistry(input: LoadAuthRegistryInput): Promise<LoadAuthRegistryResult>;
+/**
+ * Resolves the workspace-relative path of the demo claims module without
+ * leaking the constant into the public surface of {@link loadAuthRegistry}.
+ *
+ * @param workspaceRoot - Absolute workspace root.
+ * @returns The absolute path of `components/demo-firebase/src/lib/auth/claims.ts`
+ */
+export declare function resolveDemoClaimsPath(workspaceRoot: string): string;

package/src/lib/mcp-scan/manifest/load-css-utilities-registry.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadCssUtilityManifests}, and {@link createCssUtilityRegistry}.
+ *
+ * Resolves the bundled css-utility manifest that ships inside this
+ * package's `generated/` directory and merges it with any external
+ * sources declared in `dbx-mcp.config.json` under either
+ * `cssUtilities.sources` (full manifest paths) or `cssUtilities.scan[].out`
+ * (paths produced by a downstream app's own scan run).
+ *
+ * The resulting {@link CssUtilityRegistry} is the data the
+ * `dbx_css_class_lookup` tool and the css-utility resource read from. All
+ * I/O is injectable so unit tests can drive every branch without touching
+ * disk.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type CssUtilityRegistry } from '../registry/css-utilities-runtime.js';
+import { type CssUtilityLoaderWarning, type CssUtilityManifestReadFile } from './css-utilities-loader.js';
+/**
+ * Function shape used by {@link loadCssUtilityRegistry} to enumerate the
+ * bundled css-utility manifest paths shipped with this package.
+ */
+export type BundledCssUtilityManifestPathsFactory = () => readonly string[];
+/**
+ * Input to {@link loadCssUtilityRegistry}.
+ */
+export interface LoadCssUtilityRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledCssUtilityManifestPathsFactory;
+    readonly readFile?: CssUtilityManifestReadFile;
+}
+/**
+ * Outcome from {@link loadCssUtilityRegistry}. Surfaces both the registry
+ * and the loader warnings so callers (the server bootstrap) can log
+ * anything that fell through warn-and-skip.
+ */
+export interface LoadCssUtilityRegistryResult {
+    readonly registry: CssUtilityRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly CssUtilityLoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged css-utilities registry for the current MCP server.
+ *
+ * Bundled manifests load as strict sources — a malformed or missing
+ * bundled file is a build-time bug, not a configuration problem. External
+ * manifests declared in `dbx-mcp.config.json` (`cssUtilities.sources` plus
+ * `cssUtilities.scan[].out`) load as non-strict sources so a single bad
+ * downstream manifest does not take the registry down.
+ *
+ * Returns an {@link EMPTY_CSS_UTILITY_REGISTRY} with surfaced warnings
+ * when neither bundled nor external manifests yield any successful load.
+ *
+ * @param input - Cwd plus optional injected bundled-path factory and reader.
+ * @returns The registry, the resolved config path (if any), and any warnings.
+ */
+export declare function loadCssUtilityRegistry(input: LoadCssUtilityRegistryInput): Promise<LoadCssUtilityRegistryResult>;
+/**
+ * Re-exported so callers can build a deterministic test fixture pointing
+ * at the package's bundled manifests without touching `import.meta.url`.
+ *
+ * @returns The absolute paths of the bundled css-utility manifests.
+ */
+export declare function getDefaultBundledCssUtilityManifestPaths(): readonly string[];

package/src/lib/mcp-scan/manifest/load-dbx-docs-ui-examples-registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadDbxDocsUiExamplesManifests}, and
+ * {@link createDbxDocsUiExamplesRegistry}.
+ *
+ * Resolves the bundled `apps/demo` dbx-docs-ui-examples manifest plus any
+ * external sources declared in `dbx-mcp.config.json` under
+ * `dbxDocsUiExamples.sources`. Mirrors `load-ui-components-registry.ts`.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type DbxDocsUiExamplesRegistry } from '../registry/dbx-docs-ui-examples-runtime.js';
+import { type DbxDocsUiExamplesLoaderWarning, type DbxDocsUiExamplesManifestReadFile } from './dbx-docs-ui-examples-loader.js';
+export type BundledDbxDocsUiExamplesManifestPathsFactory = () => readonly string[];
+export interface LoadDbxDocsUiExamplesRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledDbxDocsUiExamplesManifestPathsFactory;
+    readonly readFile?: DbxDocsUiExamplesManifestReadFile;
+}
+export interface LoadDbxDocsUiExamplesRegistryResult {
+    readonly registry: DbxDocsUiExamplesRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly DbxDocsUiExamplesLoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged dbx-docs-ui-examples registry for the current MCP server.
+ *
+ * Bundled manifests load as strict sources; external manifests declared in
+ * `dbx-mcp.config.json` load as non-strict sources.
+ *
+ * @param input - Resolution context.
+ * @param input.cwd - Working directory used to locate `dbx-mcp.config.json`.
+ * @param input.bundledManifestPaths - Optional override for the bundled manifest path factory; defaults to the manifests shipped with this package.
+ * @param input.readFile - Optional file reader used during testing.
+ * @returns The composed registry, the resolved config path (if any), config and loader warnings, and the count of external sources.
+ */
+export declare function loadDbxDocsUiExamplesRegistry(input: LoadDbxDocsUiExamplesRegistryInput): Promise<LoadDbxDocsUiExamplesRegistryResult>;
+/**
+ * Resolves the absolute paths of the bundled dbx-docs-ui-examples manifests shipped with this package.
+ *
+ * @returns Absolute filesystem paths of the bundled manifests.
+ */
+export declare function getDefaultBundledDbxDocsUiExamplesManifestPaths(): readonly string[];

package/src/lib/mcp-scan/manifest/load-filters-registry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadFilterManifests}, and {@link createFilterRegistry}.
+ *
+ * Resolves the bundled `@dereekb/*` filter manifests that ship inside this
+ * package's `generated/` directory and merges them with any external sources
+ * declared in `dbx-mcp.config.json` under `filters.sources`. The resulting
+ * {@link FilterRegistry} is the data the `dbx_filter_lookup` tool reads from.
+ *
+ * All I/O is injectable so unit tests can drive every branch without
+ * touching disk. The default `bundledManifestPaths` factory uses
+ * `import.meta.url` to locate the package's `generated/` directory
+ * regardless of whether the caller imports the source or the bundled binary.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type FilterRegistry } from '../registry/filters-runtime.js';
+import { type FilterLoaderWarning, type FilterManifestReadFile } from './filters-loader.js';
+/**
+ * Function shape used by {@link loadFilterRegistry} to enumerate the bundled
+ * `@dereekb/*` manifest paths shipped with this package. Defaults to the
+ * JSON files inside the package's `generated/` directory.
+ */
+export type BundledFilterManifestPathsFactory = () => readonly string[];
+/**
+ * Input to {@link loadFilterRegistry}.
+ */
+export interface LoadFilterRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledFilterManifestPathsFactory;
+    readonly readFile?: FilterManifestReadFile;
+}
+/**
+ * Outcome from {@link loadFilterRegistry}. Surfaces both the registry and the
+ * loader warnings so callers (the server bootstrap) can log anything that
+ * fell through warn-and-skip.
+ */
+export interface LoadFilterRegistryResult {
+    readonly registry: FilterRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly FilterLoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged filter registry for the current MCP server.
+ *
+ * Bundled `@dereekb/*` manifests load as strict sources — a malformed or
+ * missing bundled file is a build-time bug, not a configuration problem.
+ * External manifests declared in `dbx-mcp.config.json` load as non-strict
+ * sources so a single bad downstream manifest does not take the registry
+ * down.
+ *
+ * Returns an {@link EMPTY_FILTER_REGISTRY} with surfaced warnings when neither
+ * bundled nor external manifests yield any successful load — the loader's
+ * "zero successful manifests" guard. The caller is responsible for deciding
+ * whether an empty registry is a fatal startup error.
+ *
+ * @param input - Cwd plus optional injected bundled-path factory and reader.
+ * @returns The registry, the resolved config path (if any), and any warnings.
+ */
+export declare function loadFilterRegistry(input: LoadFilterRegistryInput): Promise<LoadFilterRegistryResult>;
+/**
+ * Re-exported so callers can build a deterministic test fixture pointing at
+ * the package's bundled manifests without touching `import.meta.url`.
+ *
+ * @returns The absolute paths of the bundled `@dereekb/*` manifests.
+ */
+export declare function getDefaultBundledFilterManifestPaths(): readonly string[];

package/src/lib/mcp-scan/manifest/load-forge-fields-registry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadForgeFieldManifests}, and {@link createForgeFieldRegistry}.
+ *
+ * Resolves the bundled `@dereekb/*` forge-fields manifests that ship inside
+ * this package's `generated/` directory and merges them with any external
+ * sources declared in `dbx-mcp.config.json` under `forgeFields.sources`. The
+ * resulting {@link ForgeFieldRegistry} is the data the lookup-form /
+ * search-form tools and the registry resource read from.
+ *
+ * All I/O is injectable so unit tests can drive every branch without touching
+ * disk. The default `bundledManifestPaths` factory uses `import.meta.url` to
+ * locate the package's `generated/` directory regardless of whether the
+ * caller imports the source or the bundled binary.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type ForgeFieldRegistry } from '../registry/forge-fields.js';
+import { type ForgeFieldLoaderWarning, type ForgeFieldManifestReadFile } from './forge-fields-loader.js';
+/**
+ * Function shape used by {@link loadForgeFieldRegistry} to enumerate the
+ * bundled `@dereekb/*` manifest paths shipped with this package. Defaults to
+ * the JSON files inside the package's `generated/` directory.
+ */
+export type BundledForgeFieldManifestPathsFactory = () => readonly string[];
+/**
+ * Input to {@link loadForgeFieldRegistry}.
+ */
+export interface LoadForgeFieldRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledForgeFieldManifestPathsFactory;
+    readonly readFile?: ForgeFieldManifestReadFile;
+}
+/**
+ * Outcome from {@link loadForgeFieldRegistry}. Surfaces both the registry
+ * and the loader warnings so callers (the server bootstrap) can log anything
+ * that fell through warn-and-skip.
+ */
+export interface LoadForgeFieldRegistryResult {
+    readonly registry: ForgeFieldRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly ForgeFieldLoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged forge-fields registry for the current MCP server.
+ *
+ * Bundled `@dereekb/*` manifests load as strict sources — a malformed or
+ * missing bundled file is a build-time bug, not a configuration problem.
+ * External manifests declared in `dbx-mcp.config.json` load as non-strict
+ * sources so a single bad downstream manifest does not take the registry
+ * down.
+ *
+ * Returns an {@link EMPTY_FORGE_FIELD_REGISTRY} with surfaced warnings when
+ * neither bundled nor external manifests yield any successful load — the
+ * loader's "zero successful manifests" guard. The caller is responsible for
+ * deciding whether an empty registry is a fatal startup error.
+ *
+ * @param input - Cwd plus optional injected bundled-path factory and reader.
+ * @returns The registry, the resolved config path (if any), and any warnings.
+ */
+export declare function loadForgeFieldRegistry(input: LoadForgeFieldRegistryInput): Promise<LoadForgeFieldRegistryResult>;
+/**
+ * Re-exported so callers can build a deterministic test fixture pointing at
+ * the package's bundled manifests without touching `import.meta.url`.
+ *
+ * @returns The absolute paths of the bundled `@dereekb/*` manifests.
+ */
+export declare function getDefaultBundledForgeFieldManifestPaths(): readonly string[];

package/src/lib/mcp-scan/manifest/load-model-firebase-index-registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadModelFirebaseIndexManifests}, and
+ * {@link createModelFirebaseIndexRegistry}.
+ *
+ * Resolves the bundled `@dereekb/firebase` model-firebase-index manifest
+ * that ships inside this package's `generated/` directory and merges it
+ * with any external sources declared in `dbx-mcp.config.json` under
+ * `modelFirebaseIndex.sources`. The resulting
+ * {@link ModelFirebaseIndexRegistry} is the data the
+ * `dbx_model_firebase_index_*` tools read from.
+ *
+ * All I/O is injectable so unit tests can drive every branch without
+ * touching disk. The default `bundledManifestPaths` factory uses
+ * `import.meta.url` to locate the package's `generated/` directory
+ * regardless of whether the caller imports the source or the bundled
+ * binary.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type ModelFirebaseIndexRegistry } from '@dereekb/dbx-cli/firestore-indexes';
+import { type ModelFirebaseIndexLoaderWarning, type ModelFirebaseIndexManifestReadFile } from './model-firebase-index-loader.js';
+/**
+ * Function shape used by {@link loadModelFirebaseIndexRegistry} to
+ * enumerate the bundled `@dereekb/firebase` manifest path shipped with
+ * this package. Defaults to the JSON file inside the package's
+ * `generated/` directory.
+ */
+export type BundledModelFirebaseIndexManifestPathsFactory = () => readonly string[];
+/**
+ * Input to {@link loadModelFirebaseIndexRegistry}.
+ */
+export interface LoadModelFirebaseIndexRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledModelFirebaseIndexManifestPathsFactory;
+    readonly readFile?: ModelFirebaseIndexManifestReadFile;
+}
+/**
+ * Outcome from {@link loadModelFirebaseIndexRegistry}.
+ */
+export interface LoadModelFirebaseIndexRegistryResult {
+    readonly registry: ModelFirebaseIndexRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly ModelFirebaseIndexLoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged model-firebase-index registry for the current MCP server.
+ *
+ * @param input - Cwd plus optional injected bundled-path factory and reader.
+ * @returns The registry, the resolved config path (if any), and any warnings.
+ */
+export declare function loadModelFirebaseIndexRegistry(input: LoadModelFirebaseIndexRegistryInput): Promise<LoadModelFirebaseIndexRegistryResult>;
+/**
+ * Re-exported so callers can build a deterministic test fixture pointing
+ * at the package's bundled manifests without touching `import.meta.url`.
+ *
+ * @returns The absolute paths of the bundled `@dereekb/firebase` manifests.
+ */
+export declare function getDefaultBundledModelFirebaseIndexManifestPaths(): readonly string[];

package/src/lib/mcp-scan/manifest/load-model-snapshot-fields-registry.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadModelSnapshotFieldManifests}, and
+ * {@link createModelSnapshotFieldRegistry}.
+ *
+ * Resolves the bundled `@dereekb/firebase` model-snapshot-fields manifest that
+ * ships inside this package's `generated/` directory and merges it with any
+ * external sources declared in `dbx-mcp.config.json` under
+ * `modelSnapshotFields.sources`. The resulting
+ * {@link ModelSnapshotFieldRegistry} is the data the
+ * `dbx_model_snapshot_field_*` tools read from.
+ *
+ * All I/O is injectable so unit tests can drive every branch without
+ * touching disk. The default `bundledManifestPaths` factory uses
+ * `import.meta.url` to locate the package's `generated/` directory
+ * regardless of whether the caller imports the source or the bundled
+ * binary.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type ModelSnapshotFieldRegistry } from '../registry/model-snapshot-fields-runtime.js';
+import { type ModelSnapshotFieldLoaderWarning, type ModelSnapshotFieldManifestReadFile } from './model-snapshot-fields-loader.js';
+/**
+ * Function shape used by {@link loadModelSnapshotFieldRegistry} to enumerate
+ * the bundled `@dereekb/firebase` manifest path shipped with this package.
+ * Defaults to the JSON file inside the package's `generated/` directory.
+ */
+export type BundledModelSnapshotFieldManifestPathsFactory = () => readonly string[];
+/**
+ * Input to {@link loadModelSnapshotFieldRegistry}.
+ */
+export interface LoadModelSnapshotFieldRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledModelSnapshotFieldManifestPathsFactory;
+    readonly readFile?: ModelSnapshotFieldManifestReadFile;
+}
+/**
+ * Outcome from {@link loadModelSnapshotFieldRegistry}. Surfaces both the
+ * registry and the loader warnings so callers (the server bootstrap) can
+ * log anything that fell through warn-and-skip.
+ */
+export interface LoadModelSnapshotFieldRegistryResult {
+    readonly registry: ModelSnapshotFieldRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly ModelSnapshotFieldLoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged model-snapshot-fields registry for the current MCP server.
+ *
+ * Bundled manifests load as non-strict sources because the `@dereekb/firebase`
+ * scan may not have produced a manifest yet (e.g. before the first
+ * `generate-manifests` run). External manifests declared in
+ * `dbx-mcp.config.json` likewise load as non-strict sources so a single bad
+ * downstream manifest does not take the registry down.
+ *
+ * Returns an {@link EMPTY_MODEL_SNAPSHOT_FIELD_REGISTRY} with surfaced
+ * warnings when neither bundled nor external manifests yield any successful
+ * load — the loader's "zero successful manifests" guard is caught and
+ * translated into an empty registry so a workspace that hasn't run
+ * `generate-manifests` yet still boots.
+ *
+ * @param input - Cwd plus optional injected bundled-path factory and reader.
+ * @returns The registry, the resolved config path (if any), and any warnings.
+ */
+export declare function loadModelSnapshotFieldRegistry(input: LoadModelSnapshotFieldRegistryInput): Promise<LoadModelSnapshotFieldRegistryResult>;
+/**
+ * Re-exported so callers can build a deterministic test fixture pointing
+ * at the package's bundled manifests without touching `import.meta.url`.
+ *
+ * @returns The absolute paths of the bundled `@dereekb/firebase` manifests.
+ */
+export declare function getDefaultBundledModelSnapshotFieldManifestPaths(): readonly string[];

package/src/lib/mcp-scan/manifest/load-pipes-registry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadPipeManifests}, and {@link createPipeRegistry}.
+ *
+ * Resolves the bundled `@dereekb/*` pipes manifests that ship inside this
+ * package's `generated/` directory and merges them with any external sources
+ * declared in `dbx-mcp.config.json` under `pipes.sources`. The resulting
+ * {@link PipeRegistry} is the data the `dbx_pipe_lookup` tool reads from.
+ *
+ * All I/O is injectable so unit tests can drive every branch without
+ * touching disk. The default `bundledManifestPaths` factory uses
+ * `import.meta.url` to locate the package's `generated/` directory
+ * regardless of whether the caller imports the source or the bundled binary.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type PipeRegistry } from '../registry/pipes-runtime.js';
+import { type PipeLoaderWarning, type PipeManifestReadFile } from './pipes-loader.js';
+/**
+ * Function shape used by {@link loadPipeRegistry} to enumerate the bundled
+ * `@dereekb/*` manifest paths shipped with this package. Defaults to the
+ * JSON files inside the package's `generated/` directory.
+ */
+export type BundledPipeManifestPathsFactory = () => readonly string[];
+/**
+ * Input to {@link loadPipeRegistry}.
+ */
+export interface LoadPipeRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledPipeManifestPathsFactory;
+    readonly readFile?: PipeManifestReadFile;
+}
+/**
+ * Outcome from {@link loadPipeRegistry}. Surfaces both the registry and the
+ * loader warnings so callers (the server bootstrap) can log anything that
+ * fell through warn-and-skip.
+ */
+export interface LoadPipeRegistryResult {
+    readonly registry: PipeRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly PipeLoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged pipes registry for the current MCP server.
+ *
+ * Bundled `@dereekb/*` manifests load as strict sources — a malformed or
+ * missing bundled file is a build-time bug, not a configuration problem.
+ * External manifests declared in `dbx-mcp.config.json` load as non-strict
+ * sources so a single bad downstream manifest does not take the registry
+ * down.
+ *
+ * Returns an {@link EMPTY_PIPE_REGISTRY} with surfaced warnings when neither
+ * bundled nor external manifests yield any successful load — the loader's
+ * "zero successful manifests" guard. The caller is responsible for deciding
+ * whether an empty registry is a fatal startup error.
+ *
+ * @param input - Cwd plus optional injected bundled-path factory and reader.
+ * @returns The registry, the resolved config path (if any), and any warnings.
+ */
+export declare function loadPipeRegistry(input: LoadPipeRegistryInput): Promise<LoadPipeRegistryResult>;
+/**
+ * Re-exported so callers can build a deterministic test fixture pointing at
+ * the package's bundled manifests without touching `import.meta.url`.
+ *
+ * @returns The absolute paths of the bundled `@dereekb/*` manifests.
+ */
+export declare function getDefaultBundledPipeManifestPaths(): readonly string[];

package/src/lib/mcp-scan/manifest/load-registry.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadSemanticTypeManifests}, and {@link createSemanticTypeRegistry}.
+ *
+ * Resolves the bundled `@dereekb/*` manifests that ship inside this package's
+ * `generated/` directory and merges them with any external sources declared
+ * in `dbx-mcp.config.json`. The resulting {@link SemanticTypeRegistry} is the
+ * data the lookup / search tools and the registry resource read from.
+ *
+ * All I/O is injectable so unit tests can drive every branch without touching
+ * disk. The default `bundledManifestUrls` factory uses `import.meta.url` to
+ * locate the package's `generated/` directory regardless of whether the
+ * caller imports the source or the bundled binary.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type SemanticTypeRegistry } from '../registry/semantic-types.js';
+import { type LoaderWarning, type ManifestReadFile } from './loader.js';
+/**
+ * Function shape used by {@link loadSemanticTypeRegistry} to enumerate the
+ * bundled `@dereekb/*` manifest paths shipped with this package. Defaults to
+ * the JSON files inside the package's `generated/` directory.
+ */
+export type BundledManifestPathsFactory = () => readonly string[];
+/**
+ * Input to {@link loadSemanticTypeRegistry}.
+ */
+export interface LoadSemanticTypeRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledManifestPathsFactory;
+    readonly readFile?: ManifestReadFile;
+}
+/**
+ * Outcome from {@link loadSemanticTypeRegistry}. Surfaces both the registry
+ * and the loader warnings so callers (the server bootstrap) can log anything
+ * that fell through warn-and-skip.
+ */
+export interface LoadSemanticTypeRegistryResult {
+    readonly registry: SemanticTypeRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly LoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged semantic-types registry for the current MCP server.
+ *
+ * Bundled `@dereekb/*` manifests load as strict sources — a malformed or
+ * missing bundled file is a build-time bug, not a configuration problem.
+ * External manifests declared in `dbx-mcp.config.json` load as non-strict
+ * sources so a single bad downstream manifest does not take the registry
+ * down.
+ *
+ * Returns an {@link EMPTY_SEMANTIC_TYPE_REGISTRY} with surfaced warnings
+ * when neither bundled nor external manifests yield any successful load —
+ * the loader's "zero successful manifests" guard. The caller is responsible
+ * for deciding whether an empty registry is a fatal startup error.
+ *
+ * @param input - Cwd plus optional injected bundled-path factory and reader.
+ * @returns The registry, the resolved config path (if any), and any warnings.
+ */
+export declare function loadSemanticTypeRegistry(input: LoadSemanticTypeRegistryInput): Promise<LoadSemanticTypeRegistryResult>;
+/**
+ * Re-exported so callers can build a deterministic test fixture pointing at
+ * the package's bundled manifests without touching `import.meta.url`.
+ *
+ * @returns The absolute paths of the bundled `@dereekb/*` manifests.
+ */
+export declare function getDefaultBundledManifestPaths(): readonly string[];
+/**
+ * Returns the package's `generated/` directory. Useful for callers that want
+ * to derive sibling paths without re-deriving the package root themselves.
+ *
+ * @returns The absolute path of the bundled manifests directory.
+ */
+export declare function getBundledManifestsDirectory(): string;