@dereekb/dbx-cli 14.4.0 → 14.5.1

package/eslint/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/dbx-cli/eslint",
-  "version": "14.4.0",
+  "version": "14.5.1",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.4.0",
-    "@dereekb/util": "14.4.0",
+    "@dereekb/dbx-cli": "14.5.1",
+    "@dereekb/util": "14.5.1",
     "@typescript-eslint/utils": "8.69.0",
     "typescript": "6.0.3"
   },

package/firebase-api-manifest/main.js

@@ -1860,17 +1860,15 @@ function renderModelField(field, emitConverters) {
 // packages/dbx-cli/firebase-api-manifest/package.json
 var package_default = {
   name: "@dereekb/dbx-cli-firebase-api-manifest",
-  version: "14.4.0",
+  version: "14.5.1",
   sideEffects: false,
   private: true,
   type: "module",
-  devDependencies: {
-    "ts-morph": "^28.0.0"
-  },
   peerDependencies: {
-    "@dereekb/dbx-cli": "14.4.0",
-    "@dereekb/util": "14.4.0",
-    oxfmt: "^0.66.0"
+    "@dereekb/dbx-cli": "14.5.1",
+    "@dereekb/util": "14.5.1",
+    oxfmt: "^0.66.0",
+    "ts-morph": "^28.0.0"
   }
 };
 

package/firebase-api-manifest/package.json

@@ -1,15 +1,13 @@
 {
   "name": "@dereekb/dbx-cli-firebase-api-manifest",
-  "version": "14.4.0",
+  "version": "14.5.1",
   "sideEffects": false,
   "private": true,
   "type": "module",
-  "devDependencies": {
-    "ts-morph": "^28.0.0"
-  },
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.4.0",
-    "@dereekb/util": "14.4.0",
-    "oxfmt": "^0.66.0"
+    "@dereekb/dbx-cli": "14.5.1",
+    "@dereekb/util": "14.5.1",
+    "oxfmt": "^0.66.0",
+    "ts-morph": "^28.0.0"
   }
 }

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

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

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

@@ -0,0 +1,135 @@
+/**
+ * Loader for PRE-BUILT model-firebase-index manifests.
+ *
+ * `buildModelFirebaseIndexManifest` derives a manifest by parsing query-factory
+ * bodies with ts-morph, which only works against a scannable source tree. A
+ * published `@dereekb/*` tarball ships `.d.ts` only, so a downstream app cannot
+ * derive the framework models' indexes that way and is forced to hand-carry them
+ * in its own `firestore.indexes.json` — the gap that nearly dropped the `nbn`
+ * notification send-sweep composite in a production workspace.
+ *
+ * This module closes that gap from the other side: it reads the manifests the
+ * framework already generates at release time (`generate-manifests.mjs` writes
+ * them into `@dereekb/dbx-components-mcp`'s `generated/` directory) so
+ * `generate-firestore-indexes` can merge framework entries without any source to
+ * scan.
+ *
+ * Merge policy is intentionally ADDITIVE and unfiltered: every entry a package
+ * declares is emitted, whether or not the consuming app wires that collection.
+ * The two failure directions are not symmetric — an index for a collection the
+ * app never writes to holds no index entries, so it costs nothing, while a
+ * MISSING index breaks the query outright. Filtering to "collections this app
+ * wires" is also not the cheap text match it looks like: collection ids are
+ * framework constants that never appear literally in consumer source, and the
+ * wiring is split across the client model service and the separate server-only
+ * `firebaseModelServiceFactory` path. Any escape hatch added later should be an
+ * opt-OUT list, which fails safe, rather than an opt-in one, which does not.
+ *
+ * I/O is fully injectable so tests drive every branch without touching disk.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ScanReadFile } from '../../src/lib/scan-helpers/scan-io.js';
+import { ModelFirebaseIndexManifest } from './model-firebase-index-schema.js';
+/**
+ * Filename suffix every generated model-firebase-index manifest carries. The
+ * leading segment is the source package's slug (`dereekb-firebase`), so
+ * discovery matches on the suffix alone and picks up any package that starts
+ * publishing one without a code change here.
+ */
+export declare const MODEL_FIREBASE_INDEX_MANIFEST_FILENAME_SUFFIX = ".model-firebase-index.mcp.generated.json";
+/**
+ * Package that bundles the generated `@dereekb/*` manifests. The manifests do
+ * not ship inside each model-owning package (`@dereekb/firebase` and friends
+ * publish no JSON assets); `generate-manifests.mjs` collects them all into this
+ * one package's `generated/` directory, which is what actually gets published.
+ */
+export declare const BUNDLED_MODEL_FIREBASE_INDEX_MANIFEST_PACKAGE = "@dereekb/dbx-components-mcp";
+/**
+ * Function shape used to list a directory's entry names. Defaults to
+ * `node:fs/promises.readdir`.
+ */
+export type ModelFirebaseIndexManifestReadDir = (absolutePath: string) => Promise<readonly string[]>;
+/**
+ * Function shape used to locate the bundled manifest directory from the
+ * consuming workspace's cwd. Returns `null` when the bundling package is not
+ * installed.
+ */
+export type ModelFirebaseIndexManifestDirectoryResolver = (cwd: string) => Maybe<string>;
+/**
+ * One successfully loaded manifest plus the absolute path it came from. The
+ * path is retained so the CLI can name the offending file in diagnostics.
+ */
+export interface LoadedModelFirebaseIndexManifest {
+    readonly path: string;
+    readonly manifest: ModelFirebaseIndexManifest;
+}
+/**
+ * Outcome of one {@link loadModelFirebaseIndexPackageManifests} call.
+ */
+export type LoadModelFirebaseIndexPackageManifestsOutcome = {
+    readonly kind: 'success';
+    readonly loaded: readonly LoadedModelFirebaseIndexManifest[];
+} | {
+    readonly kind: 'unreadable-manifest';
+    readonly path: string;
+    readonly error: string;
+} | {
+    readonly kind: 'invalid-manifest';
+    readonly path: string;
+    readonly error: string;
+} | {
+    readonly kind: 'no-bundled-package';
+    readonly packageName: string;
+};
+/**
+ * Input to {@link loadModelFirebaseIndexPackageManifests}.
+ */
+export interface LoadModelFirebaseIndexPackageManifestsInput {
+    /**
+     * Working directory explicit `manifestPaths` resolve against, and the origin
+     * bundled-package resolution starts from.
+     */
+    readonly cwd: string;
+    /**
+     * Explicit manifest paths (cwd-relative or absolute). Loaded in the order
+     * given, ahead of any discovered bundled manifests.
+     */
+    readonly manifestPaths?: readonly string[];
+    /**
+     * When true, also discover every manifest bundled in the installed
+     * {@link BUNDLED_MODEL_FIREBASE_INDEX_MANIFEST_PACKAGE}.
+     */
+    readonly discoverBundled?: boolean;
+    readonly readFile?: ScanReadFile;
+    readonly readDir?: ModelFirebaseIndexManifestReadDir;
+    readonly resolveBundledDirectory?: ModelFirebaseIndexManifestDirectoryResolver;
+}
+/**
+ * Resolves the bundled manifest directory by asking Node to resolve the
+ * bundling package's `package.json` from the consuming workspace. Going through
+ * module resolution (rather than joining `node_modules` by hand) keeps this
+ * correct under hoisting and workspace layouts.
+ *
+ * @param cwd - Working directory the resolution originates from.
+ * @returns The absolute `generated/` directory, or null when the package is not installed.
+ */
+export declare const defaultBundledManifestDirectoryResolver: ModelFirebaseIndexManifestDirectoryResolver;
+/**
+ * Loads and validates pre-built model-firebase-index manifests from explicit
+ * paths and/or the installed bundling package. Never throws — every failure
+ * path returns a discriminated outcome the CLI renders as a diagnostic.
+ *
+ * @param input - Cwd, the manifest sources to load, and injectable I/O hooks.
+ * @returns The loaded manifests, or the first failure encountered.
+ */
+export declare function loadModelFirebaseIndexPackageManifests(input: LoadModelFirebaseIndexPackageManifestsInput): Promise<LoadModelFirebaseIndexPackageManifestsOutcome>;
+/**
+ * Renders a non-success outcome as a single actionable line, naming both the
+ * cause and the fix.
+ *
+ * @param outcome - The non-success load outcome.
+ * @returns A one-line description suitable for stderr.
+ */
+export declare function formatModelFirebaseIndexPackageManifestFailure(outcome: Exclude<LoadModelFirebaseIndexPackageManifestsOutcome, {
+    kind: 'success';
+}>): string;

package/firestore-query-manifest/main.js

@@ -9,7 +9,7 @@ import { isAbsolute as isAbsolute2, relative as relative2, resolve as resolve3 }
 // packages/dbx-cli/firestore-query-manifest/package.json
 var package_default = {
   name: "@dereekb/dbx-cli-firestore-query-manifest",
-  version: "14.4.0",
+  version: "14.5.1",
   sideEffects: false,
   private: true,
   type: "module",
@@ -17,8 +17,8 @@ var package_default = {
     eslint: "10.9.1"
   },
   peerDependencies: {
-    "@dereekb/dbx-cli": "14.4.0",
-    "@dereekb/util": "14.4.0"
+    "@dereekb/dbx-cli": "14.5.1",
+    "@dereekb/util": "14.5.1"
   }
 };
 

package/firestore-query-manifest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-firestore-query-manifest",
-  "version": "14.4.0",
+  "version": "14.5.1",
   "sideEffects": false,
   "private": true,
   "type": "module",
@@ -8,7 +8,7 @@
     "eslint": "10.9.1"
   },
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.4.0",
-    "@dereekb/util": "14.4.0"
+    "@dereekb/dbx-cli": "14.5.1",
+    "@dereekb/util": "14.5.1"
   }
 }

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: "14.4.0",
+  version: "14.5.1",
   sideEffects: false,
   private: true,
   type: "module",
@@ -13,7 +13,7 @@ var package_default = {
     eslint: "10.9.1"
   },
   peerDependencies: {
-    "@dereekb/dbx-cli": "14.4.0"
+    "@dereekb/dbx-cli": "14.5.1"
   }
 };
 
@@ -324,7 +324,7 @@ function computeDiff(input) {
 
 // packages/dbx-cli/firestore-indexes/src/generate-firestore-indexes-cli.ts
 import { readFile as nodeReadFile2, writeFile as nodeWriteFile } from "node:fs/promises";
-import { resolve as resolve2 } from "node:path";
+import { resolve as resolve3 } from "node:path";
 
 // packages/dbx-cli/firestore-indexes/src/model-firebase-index-build-manifest.ts
 import { relative, resolve } from "node:path";
@@ -1063,10 +1063,10 @@ function collectParams(decl, descriptions) {
   for (const param of params) {
     const name = param.getName();
     const typeNode = param.getTypeNode()?.getText();
-    const type4 = typeNode ?? param.getType().getText() ?? "unknown";
+    const type5 = typeNode ?? param.getType().getText() ?? "unknown";
     const description = descriptions.get(name) ?? "";
     const optional = param.isOptional() || param.hasInitializer();
-    out.push({ name, type: type4, description, optional });
+    out.push({ name, type: type5, description, optional });
   }
   return out;
 }
@@ -2077,17 +2077,128 @@ function pushInto(map, key, entry) {
   }
 }
 
+// packages/dbx-cli/firestore-indexes/src/model-firebase-index-package-manifests.ts
+import { type as type4 } from "arktype";
+import { readdir as nodeReadDir } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, resolve as resolve2 } from "node:path";
+var MODEL_FIREBASE_INDEX_MANIFEST_FILENAME_SUFFIX = ".model-firebase-index.mcp.generated.json";
+var BUNDLED_MODEL_FIREBASE_INDEX_MANIFEST_PACKAGE = "@dereekb/dbx-components-mcp";
+var BUNDLED_MANIFEST_DIRECTORY_NAME = "generated";
+var defaultBundledManifestDirectoryResolver = (cwd) => {
+  let result2;
+  try {
+    const requireFromCwd = createRequire(resolve2(cwd, "noop.js"));
+    const packageJsonPath = requireFromCwd.resolve(`${BUNDLED_MODEL_FIREBASE_INDEX_MANIFEST_PACKAGE}/package.json`);
+    result2 = resolve2(dirname(packageJsonPath), BUNDLED_MANIFEST_DIRECTORY_NAME);
+  } catch {
+    result2 = null;
+  }
+  return result2;
+};
+var defaultReadDir = (path) => nodeReadDir(path);
+async function loadModelFirebaseIndexPackageManifests(input) {
+  const { cwd, manifestPaths = [], discoverBundled = false, readFile = defaultReadFile, readDir = defaultReadDir, resolveBundledDirectory = defaultBundledManifestDirectoryResolver } = input;
+  const paths = manifestPaths.map((path) => resolve2(cwd, path));
+  let failure = null;
+  if (discoverBundled) {
+    const bundledDirectory = resolveBundledDirectory(cwd);
+    if (bundledDirectory == null) {
+      failure = { kind: "no-bundled-package", packageName: BUNDLED_MODEL_FIREBASE_INDEX_MANIFEST_PACKAGE };
+    } else {
+      paths.push(...await readBundledManifestPaths(bundledDirectory, readDir));
+    }
+  }
+  const loaded = [];
+  for (const path of paths) {
+    if (failure != null) {
+      break;
+    }
+    const readResult = await readManifestFile(path, readFile);
+    if (readResult.kind === "ok") {
+      loaded.push({ path, manifest: readResult.manifest });
+    } else {
+      failure = readResult.outcome;
+    }
+  }
+  return failure ?? { kind: "success", loaded };
+}
+function formatModelFirebaseIndexPackageManifestFailure(outcome) {
+  let result2;
+  switch (outcome.kind) {
+    case "unreadable-manifest":
+      result2 = `could not read manifest at ${outcome.path} \u2014 ${outcome.error}`;
+      break;
+    case "invalid-manifest":
+      result2 = `manifest at ${outcome.path} failed validation \u2014 ${outcome.error}`;
+      break;
+    default:
+      result2 = `${outcome.packageName} is not installed, so no bundled index manifests could be discovered. Install it, or pass --manifest <path> explicitly.`;
+      break;
+  }
+  return result2;
+}
+async function readBundledManifestPaths(directory, readDir) {
+  let result2;
+  try {
+    const names = await readDir(directory);
+    result2 = names.filter((name) => name.endsWith(MODEL_FIREBASE_INDEX_MANIFEST_FILENAME_SUFFIX)).toSorted().map((name) => resolve2(directory, name));
+  } catch {
+    result2 = [];
+  }
+  return result2;
+}
+async function readManifestFile(path, readFile) {
+  let raw = null;
+  let readError = null;
+  try {
+    raw = await readFile(path);
+  } catch (err) {
+    readError = err instanceof Error ? err.message : String(err);
+  }
+  let result2;
+  if (raw == null) {
+    result2 = { kind: "fail", outcome: { kind: "unreadable-manifest", path, error: readError ?? "unknown error" } };
+  } else {
+    let parsed;
+    let parseError = null;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      parseError = err instanceof Error ? err.message : String(err);
+    }
+    if (parseError == null) {
+      const validated = ModelFirebaseIndexManifest(parsed);
+      if (validated instanceof type4.errors) {
+        result2 = { kind: "fail", outcome: { kind: "invalid-manifest", path, error: validated.summary } };
+      } else {
+        result2 = { kind: "ok", manifest: validated };
+      }
+    } else {
+      result2 = { kind: "fail", outcome: { kind: "invalid-manifest", path, error: parseError } };
+    }
+  }
+  return result2;
+}
+
 // packages/dbx-cli/firestore-indexes/src/generate-firestore-indexes-cli.ts
 var DEFAULT_BIN_NAME = "dbx-cli-generate-firestore-indexes";
 function buildUsage(binName) {
   return [
-    `Usage: ${binName} --component <dir> [--component <dir> ...] [--output <path>] [--check] [--json] [--help]`,
+    `Usage: ${binName} [--component <dir> ...] [--packages] [--manifest <path> ...] [--output <path>] [--check] [--json] [--help]`,
     "",
     "Generates `firestore.indexes.json` from `@dbxModelFirebaseIndex`-tagged factories.",
     "",
     "Options:",
-    "  --component <dir>  Required, repeatable. Relative path to a `-firebase` component or package.",
-    "                     Repeat to derive one indexes file from several packages at once.",
+    "  --component <dir>  Repeatable. Relative path to a `-firebase` component or package whose",
+    "                     source is scanned for tagged factories. Repeat to derive one indexes",
+    "                     file from several packages at once.",
+    "  --packages         Also merge the pre-built index manifests bundled in the installed",
+    "                     @dereekb/dbx-components-mcp. Lets an app derive the framework models\u2019",
+    "                     indexes without a scannable copy of their source.",
+    "  --manifest <path>  Repeatable. Merge a specific pre-built manifest JSON file.",
+    "",
+    "  At least one of --component / --packages / --manifest is required.",
     "  --output <path>    Output path. Defaults to `firestore.indexes.json` at the cwd.",
     "  --check            Compare against the on-disk file; exit 1 on drift, do not write.",
     "  --json             Print the diff summary as JSON instead of human-readable text.",
@@ -2107,18 +2218,18 @@ async function runGenerateFirestoreIndexesCli(input) {
     stderr(usage);
     return { exitCode: 2 };
   }
-  if (parsed.components.length === 0) {
-    stderr("generate-firestore-indexes: --component is required");
+  if (parsed.components.length === 0 && parsed.manifests.length === 0 && !parsed.packages) {
+    stderr("generate-firestore-indexes: at least one of --component / --packages / --manifest is required");
     stderr(usage);
     return { exitCode: 2 };
   }
-  const outputAbs = resolve2(cwd, parsed.output);
+  const outputAbs = resolve3(cwd, parsed.output);
   const entries = [];
   const loadedSources = [];
   let sawUnresolvedModel = false;
   for (const component of parsed.components) {
     const buildOutcome = await buildModelFirebaseIndexManifest({
-      projectRoot: resolve2(cwd, component),
+      projectRoot: resolve3(cwd, component),
       generator
     });
     if (buildOutcome.kind !== "success") {
@@ -2136,6 +2247,15 @@ async function runGenerateFirestoreIndexesCli(input) {
     }
     loadedSources.push(buildOutcome.manifest.source);
   }
+  if (parsed.packages || parsed.manifests.length > 0) {
+    const merged = await collectPackageManifestEntries({ cwd, manifestPaths: parsed.manifests, discoverBundled: parsed.packages, readFile });
+    if (merged.kind === "fail") {
+      stderr(merged.message);
+      return { exitCode: 1 };
+    }
+    entries.push(...merged.entries);
+    loadedSources.push(...merged.sources);
+  }
   if (sawUnresolvedModel) {
     stderr("generate-firestore-indexes: one or more @dbxModelFirebaseIndexModel tags could not be resolved, so their indexes were dropped. Add the missing identity file to the component\u2019s `dbx-mcp.scan.json` include globs.");
     return { exitCode: 1 };
@@ -2162,8 +2282,29 @@ async function runGenerateFirestoreIndexesCli(input) {
   }
   return { exitCode: 0 };
 }
+async function collectPackageManifestEntries(input) {
+  const { cwd, manifestPaths, discoverBundled, readFile } = input;
+  const outcome = await loadModelFirebaseIndexPackageManifests({ cwd, manifestPaths, discoverBundled, readFile });
+  let result2;
+  if (outcome.kind === "success") {
+    const entries = [];
+    const sources = [];
+    for (const { manifest } of outcome.loaded) {
+      for (const entry of manifest.entries) {
+        entries.push(toModelFirebaseIndexEntryInfo(entry));
+      }
+      sources.push(manifest.source);
+    }
+    result2 = { kind: "ok", entries, sources };
+  } else {
+    result2 = { kind: "fail", message: `generate-firestore-indexes: ${formatModelFirebaseIndexPackageManifestFailure(outcome)}` };
+  }
+  return result2;
+}
 function parseArgv(argv) {
   const components = [];
+  const manifests = [];
+  let packages = false;
   let output = "firestore.indexes.json";
   let check = false;
   let json = false;
@@ -2181,6 +2322,17 @@ function parseArgv(argv) {
           components.push(argv[i]);
         }
         break;
+      case "--manifest":
+        i += 1;
+        if (i >= argv.length) {
+          error = "generate-firestore-indexes: --manifest requires a value";
+        } else {
+          manifests.push(argv[i]);
+        }
+        break;
+      case "--packages":
+        packages = true;
+        break;
       case "--output":
         i += 1;
         if (i >= argv.length) {
@@ -2205,7 +2357,7 @@ function parseArgv(argv) {
     }
     i += 1;
   }
-  return { components, output, check, json, help, error };
+  return { components, manifests, packages, output, check, json, help, error };
 }
 async function readExistingIndexes(input) {
   const text = await readExistingIndexesText(input);

package/generate-firestore-indexes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-generate-firestore-indexes",
-  "version": "14.4.0",
+  "version": "14.5.1",
   "sideEffects": false,
   "private": true,
   "type": "module",
@@ -8,6 +8,6 @@
     "eslint": "10.9.1"
   },
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.4.0"
+    "@dereekb/dbx-cli": "14.5.1"
   }
 }

package/generate-mcp-manifest/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/dbx-cli-generate-mcp-manifest",
-  "version": "14.4.0",
+  "version": "14.5.1",
   "sideEffects": false,
   "private": true,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.4.0",
-    "@dereekb/model": "14.4.0",
+    "@dereekb/dbx-cli": "14.5.1",
+    "@dereekb/model": "14.5.1",
     "arktype": "^2.2.0",
     "jiti": "2.7.0"
   }

package/generate-route-manifest/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/dbx-cli-generate-route-manifest",
-  "version": "14.4.0",
+  "version": "14.5.1",
   "sideEffects": false,
   "private": true,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.4.0",
+    "@dereekb/dbx-cli": "14.5.1",
     "ts-morph": "^28.0.0"
   }
 }