@dereekb/dbx-cli 13.42.0 → 13.43.0

package/lint-cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-lint-cache",
-  "version": "13.42.0",
+  "version": "13.43.0",
   "private": true,
   "type": "module",
   "devDependencies": {
@@ -8,7 +8,7 @@
     "eslint": "10.4.0"
   },
   "peerDependencies": {
-    "@dereekb/util": "13.42.0",
+    "@dereekb/util": "13.43.0",
     "yargs": "^18.0.0"
   }
 }

package/manifest-extract/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "13.42.0",
+  "version": "13.43.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
     "@dereekb/date": "13.15.0",
-    "@dereekb/dbx-cli": "13.42.0",
+    "@dereekb/dbx-cli": "13.43.0",
     "@dereekb/firebase": "13.15.0",
     "@dereekb/model": "13.15.0",
     "@dereekb/nestjs": "13.15.0",

package/model-test/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/dbx-cli/model-test",
-  "version": "13.42.0",
+  "version": "13.43.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/util": "13.42.0",
+    "@dereekb/util": "13.43.0",
     "ts-morph": "^21.0.0"
   },
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "13.42.0",
+  "version": "13.43.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -66,11 +66,11 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.42.0",
-    "@dereekb/firebase": "13.42.0",
-    "@dereekb/model": "13.42.0",
-    "@dereekb/nestjs": "13.42.0",
-    "@dereekb/util": "13.42.0",
+    "@dereekb/date": "13.43.0",
+    "@dereekb/firebase": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/nestjs": "13.43.0",
+    "@dereekb/util": "13.43.0",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "firebase": "^12.12.1",

package/route/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/dbx-cli/route",
-  "version": "13.42.0",
+  "version": "13.43.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "13.42.0",
-    "@dereekb/dbx-cli": "13.42.0",
-    "@dereekb/firebase": "13.42.0",
-    "@dereekb/model": "13.42.0",
-    "@dereekb/nestjs": "13.42.0",
-    "@dereekb/util": "13.42.0"
+    "@dereekb/date": "13.43.0",
+    "@dereekb/dbx-cli": "13.43.0",
+    "@dereekb/firebase": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/nestjs": "13.43.0",
+    "@dereekb/util": "13.43.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/src/lib/doctor/build-drift.check.d.ts

@@ -0,0 +1,21 @@
+import { type InspectCliBuildDriftInput } from '../runner/build-stamp';
+import { type DoctorCheck } from './doctor.command.factory';
+/**
+ * Name reported by the check {@link createCliBuildDriftDoctorCheck} builds.
+ */
+export declare const BUILD_DRIFT_DOCTOR_CHECK_NAME = "cli-build-not-stale";
+/**
+ * Builds the doctor check that compares the running artifact against the `@dereekb/*` tree resolved
+ * at run time.
+ *
+ * Runs FIRST in the default check list, ahead of every network hop, because a stale artifact
+ * invalidates the answers those hops give: they exercise the framework that is loaded now, not the
+ * one the bundle was compiled against, so a green `token-refresh-round-trip` next to a red read is
+ * exactly the misleading report this check exists to pre-empt.
+ *
+ * @param input - Optional overrides forwarded to {@link inspectCliBuildDrift}; apps normally pass only
+ *   `manifestGeneratorVersion`.
+ * @returns The {@link DoctorCheck}.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createCliBuildDriftDoctorCheck(input?: InspectCliBuildDriftInput): DoctorCheck;

package/src/lib/doctor/doctor.command.factory.d.ts

@@ -16,11 +16,24 @@ export interface DoctorCheckResult {
 }
 export type DoctorCheck = (input: DoctorCheckInput) => Promise<DoctorCheckResult>;
 /**
- * Built-in checks: config file present, active env resolved, OIDC discovery, token refresh, API reachability.
+ * Input for {@link defaultDoctorChecks}.
+ */
+export interface DefaultDoctorChecksInput {
+    /**
+     * The `@dereekb/dbx-cli` version that emitted the app's generated manifests
+     * (`<NAMESPACE>_STAMP.generatorVersion`). Forwarded to the build-drift check so a manifest produced
+     * by a different generator than the one running it is flagged.
+     */
+    readonly manifestGeneratorVersion?: Maybe<string>;
+}
+/**
+ * Built-in checks: build not stale, config file present, active env resolved, OIDC discovery, token
+ * refresh, API reachability.
  *
+ * @param input - Optional configuration for the built-in checks.
  * @returns The default {@link DoctorCheck} list, in execution order.
  */
-export declare function defaultDoctorChecks(): DoctorCheck[];
+export declare function defaultDoctorChecks(input?: DefaultDoctorChecksInput): DoctorCheck[];
 export interface CreateDoctorCommandInput {
     readonly cliName: string;
     /**
@@ -32,6 +45,11 @@ export interface CreateDoctorCommandInput {
      * doctor can run against an env that only stores overrides on top of a registered default.
      */
     readonly defaultEnvs?: readonly CliEnvDefault[];
+    /**
+     * The generator version stamped into the app's generated manifests, forwarded to the built-in
+     * build-drift check.
+     */
+    readonly manifestGeneratorVersion?: Maybe<string>;
 }
 /**
  * Composable doctor command.
@@ -43,6 +61,7 @@ export interface CreateDoctorCommandInput {
  * @param input.cliName - The CLI's binary name.
  * @param input.checks - Additional checks to append after the default check list.
  * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
+ * @param input.manifestGeneratorVersion - The generator version stamped into the app's generated manifests.
  * @returns A yargs `CommandModule` exposing the `doctor` command.
  * @__NO_SIDE_EFFECTS__
  */

package/src/lib/doctor/firestore-session.check.d.ts

@@ -120,7 +120,13 @@ export declare function buildFirestoreSessionDoctorReadRouting(input: {
  * 3. `GET /session/firestore` is reachable and mints a custom token (+ an App Check token when the
  *    API is configured with a web `appId`);
  * 4. `signInWithCustomToken` succeeds against the configured project;
- * 5. the app-supplied {@link FirestoreSessionDoctorProbe} performs one rules-protected read.
+ * 5. the session's Firestore handle is one the loaded client SDK accepts (`inspectCliFirestoreSdkIdentity`),
+ *    reported as `stage: 'firestore-sdk-identity'`. Sits between the sign-in and the read because it
+ *    is the hop whose failure otherwise MASQUERADES as the read's: the handshake returns a uid, and
+ *    the read then dies on the SDK's `Expected first argument to collection() to be …` — a message
+ *    that names neither the model nor the handle, and sends the operator to rules and App Check
+ *    instead of to a duplicated SDK or a stale artifact;
+ * 6. the app-supplied {@link FirestoreSessionDoctorProbe} performs one rules-protected read.
  *
  * Doctor checks run PRE-AUTH — `DoctorCheckInput` is only `{ cliName, envName, env, config }`, with no
  * token and no `CliContext` — so this loads credentials itself via `buildCliPaths` +

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

@@ -1,2 +1,3 @@
+export * from './build-drift.check';
 export * from './doctor.command.factory';
 export * from './firestore-session.check';

package/src/lib/firestore/firestore.sdk-identity.d.ts

@@ -0,0 +1,193 @@
+import { type FirestoreModelKey, type FirestoreModelType } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+/**
+ * The `drivers.firestoreDriverIdentifier` a client-SDK `FirestoreContext` reports.
+ *
+ * `clientFirebaseFirestoreContextFactory` stamps this; the server's
+ * `googleCloudFirestoreContextFactory` stamps `@google-cloud/firestore` instead. Comparing against
+ * it is how {@link inspectCliFirestoreSdkIdentity} tells an admin-SDK context handed to the CLI apart
+ * from a genuinely broken client one.
+ */
+export declare const CLI_CLIENT_FIRESTORE_DRIVER_IDENTIFIER = "@firebase/firestore";
+/**
+ * The doctor `detail.stage` reported when the session's Firestore handle is not a usable client-SDK
+ * `Firestore`.
+ *
+ * A distinct stage from `rules-protected-read` on purpose: the read never ran, so reporting it under
+ * the read's stage is what made this failure look like a rules/App Check problem.
+ */
+export declare const FIRESTORE_SDK_IDENTITY_STAGE = "firestore-sdk-identity";
+/**
+ * `CliError` code for a Firestore handle the client SDK does not recognize as its own.
+ */
+export declare const FIRESTORE_SDK_INSTANCE_MISMATCH_CODE = "FIRESTORE_SDK_INSTANCE_MISMATCH";
+/**
+ * The distinct ways a session's Firestore handle can be unusable, in the order
+ * {@link inspectCliFirestoreSdkIdentity} tests them — most specific diagnosis first.
+ */
+export type CliFirestoreSdkIdentityProblem = 
+/**
+ * `firestoreContext` is absent, or its `firestore` is null/undefined. Every `collection()` call
+ * built off it throws `Expected first argument to collection() to be a CollectionReference, a
+ * DocumentReference or FirebaseFirestore` — the SDK's message for ANY non-Firestore first
+ * argument, which is why it never named this.
+ */
+'no-firestore-handle'
+/**
+ * The context reports a driver other than {@link CLI_CLIENT_FIRESTORE_DRIVER_IDENTIFIER} — an
+ * admin/`@google-cloud/firestore` context reached the client-SDK read path.
+ */
+ | 'unexpected-driver'
+/**
+ * Two copies of `@firebase/firestore` are loaded, so the handle minted by one fails the other's
+ * brand check.
+ */
+ | 'duplicated-firestore-sdk'
+/**
+ * The handle is present and the driver looks right, but it is not an instance of THIS copy of the
+ * SDK's `Firestore` class and no duplicate install explains it.
+ */
+ | 'foreign-firestore-instance';
+/**
+ * Where one consumer resolved `@firebase/firestore` to, and at which version.
+ *
+ * Reported for both `@dereekb/dbx-cli` and `@dereekb/firebase` because the whole point of the
+ * duplicated-SDK hypothesis is that those two answers can differ.
+ */
+export interface CliFirestoreSdkModuleIdentity {
+    /**
+     * The resolved package directory, or `undefined` when resolution failed.
+     */
+    readonly packageDir?: Maybe<string>;
+    readonly version?: Maybe<string>;
+    /**
+     * Why resolution failed, when it did.
+     */
+    readonly error?: Maybe<string>;
+}
+/**
+ * The provenance + brand-check report {@link inspectCliFirestoreSdkIdentity} produces.
+ *
+ * Everything here is reported whether or not the check passed: a `sdkDuplicated: true` alongside
+ * `ok: true` is a latent hazard worth seeing before it becomes an outage.
+ */
+export interface CliFirestoreSdkIdentityReport {
+    readonly ok: boolean;
+    readonly problem?: CliFirestoreSdkIdentityProblem;
+    readonly firestorePresent: boolean;
+    /**
+     * Whether the handle passes `instanceof Firestore` against the copy of `@firebase/firestore` THIS
+     * package loaded.
+     */
+    readonly firestoreIsSdkInstance: boolean;
+    /**
+     * The handle's constructor name, which distinguishes a duplicate `Firestore` (same name, different
+     * class) from a genuinely foreign object.
+     */
+    readonly firestoreConstructor?: Maybe<string>;
+    readonly firestoreDriverIdentifier?: Maybe<string>;
+    /**
+     * The version of the `firebase` umbrella package resolved at runtime.
+     */
+    readonly firebaseVersion?: Maybe<string>;
+    readonly sdkFromDbxCli: CliFirestoreSdkModuleIdentity;
+    readonly sdkFromDbxFirebase: CliFirestoreSdkModuleIdentity;
+    /**
+     * True when the two resolutions above name DIFFERENT package directories.
+     */
+    readonly sdkDuplicated: boolean;
+}
+/**
+ * The slice of a session context {@link inspectCliFirestoreSdkIdentity} reads.
+ *
+ * Deliberately looser than `FirestoreContext`: this check exists precisely for the case where the
+ * object is not the shape its declared type claims, so narrowing it here would assume away the
+ * failure. A real `CliFirestoreSessionContext['firestoreContext']` is structurally assignable.
+ */
+export interface CliFirestoreSdkIdentityContext {
+    readonly firestore?: unknown;
+    readonly drivers?: {
+        readonly firestoreDriverIdentifier?: unknown;
+    };
+}
+/**
+ * Input for {@link inspectCliFirestoreSdkIdentity}.
+ */
+export interface InspectCliFirestoreSdkIdentityInput {
+    readonly firestoreContext?: Maybe<CliFirestoreSdkIdentityContext>;
+}
+/**
+ * Checks that a session's Firestore handle is one THIS copy of the client SDK will accept, and
+ * reports where every consumer resolved the SDK from.
+ *
+ * Exists because `collection()` refuses any non-`Firestore` first argument with one message —
+ * `Expected first argument to collection() to be a CollectionReference, a DocumentReference or
+ * FirebaseFirestore` — that names neither the model, nor the collection, nor which of the three
+ * distinct causes ({@link CliFirestoreSdkIdentityProblem}) produced it. Every downstream CLI built on
+ * `@dereekb/dbx-cli` shares that hazard, so the diagnosis belongs here rather than in an app.
+ *
+ * The `instanceof` test is the load-bearing one and it is deliberately NOT structural: an identity
+ * check across the package boundary is the only thing that can detect a duplicated
+ * `@firebase/firestore`, which is exactly what a structural check would hide. (Contrast
+ * `firestore.error.ts`, which narrows a thrown `FirebaseError` structurally — there the goal is to
+ * classify an error even when copies differ, so the tradeoff runs the other way.)
+ *
+ * @param input - The session's `firestoreContext`, when one was built.
+ * @returns The provenance + brand-check report.
+ */
+export declare function inspectCliFirestoreSdkIdentity(input: InspectCliFirestoreSdkIdentityInput): CliFirestoreSdkIdentityReport;
+/**
+ * The actionable next step for a failed {@link inspectCliFirestoreSdkIdentity}, keyed on which
+ * problem was found.
+ *
+ * Each branch names the fix rather than the symptom — a raw SDK sentence sends an operator looking at
+ * security rules and App Check, neither of which is ever the cause here.
+ *
+ * @param report - The report to describe.
+ * @returns The suggestion, or `undefined` when the report passed.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliFirestoreSdkIdentitySuggestion(report: CliFirestoreSdkIdentityReport): Maybe<string>;
+/**
+ * `CliError` code for a collection/document reference the SDK refused to build for a reason the
+ * wiring identity check cannot explain — a bad `--parent`, or an app collection whose own
+ * construction is broken.
+ */
+export declare const FIRESTORE_COLLECTION_UNRESOLVABLE_CODE = "FIRESTORE_COLLECTION_UNRESOLVABLE";
+/**
+ * Input for {@link cliFirestoreWiringError}.
+ */
+export interface CliFirestoreWiringErrorInput {
+    /**
+     * The value the SDK threw.
+     */
+    readonly error: unknown;
+    /**
+     * What the CLI was doing, phrased to complete `Could not <operation>` — e.g.
+     * `build the app's Firestore collections`.
+     */
+    readonly operation: string;
+    readonly modelType?: FirestoreModelType;
+    readonly collectionName?: string;
+    /**
+     * The `--parent` in play, when one was supplied. Reported either way: "no `--parent`" rules out the
+     * subcollection route, which is otherwise the first thing an operator has to go and check.
+     */
+    readonly parentKey?: FirestoreModelKey;
+    readonly firestoreContext?: Maybe<CliFirestoreSdkIdentityContext>;
+}
+/**
+ * Re-raises a reference-construction failure as a `CliError` that names WHAT was being built and, when
+ * the SDK handle is at fault, WHY.
+ *
+ * The failure this replaces is the least readable in the direct-Firestore path: `collection()` and
+ * `doc()` reject a bad first argument with a message that names neither the model, the collection, the
+ * `--parent`, nor the handle — and every one of those is known at the call site. A `CliError` already
+ * raised upstream (an unknown model type, a malformed `--parent`) is passed through untouched, so this
+ * can be applied unconditionally in a `catch`.
+ *
+ * @param input - The thrown value plus everything the call site knows about the reference it was building.
+ * @returns The `CliError` to throw, or the original `CliError` when the failure was already named.
+ */
+export declare function cliFirestoreWiringError(input: CliFirestoreWiringErrorInput): Error;

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

@@ -8,6 +8,7 @@ export * from './firestore.models';
 export * from './firestore.query';
 export * from './firestore.query-params';
 export * from './firestore.read';
+export * from './firestore.sdk-identity';
 export * from './firestore.session';
 export * from './query-info-utils';
 export * from './query-mode';

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

@@ -788,3 +788,24 @@ export interface CliFirestoreQueryManifestEntry {
  * The generated per-model Firestore query catalog.
  */
 export type CliFirestoreQueryManifest = readonly CliFirestoreQueryManifestEntry[];
+/**
+ * The generator provenance a generated manifest module carries alongside its catalog.
+ *
+ * Emitted as `<NAMESPACE>_STAMP` by the manifest generators and wired into `runCli` as
+ * `manifestGeneratorVersion`. Exists because a generated manifest is the one build output that can go
+ * stale WITHOUT breaking the build: it is committed TypeScript, so a manifest emitted by an older
+ * generator still compiles and still type-checks against a newer runtime — it just quietly lacks the
+ * fields that runtime reads. `queryMode` / `rules` were exactly that, and the resulting
+ * `queryModesScanned: false` sat in `doctor` output unread while the direct-Firestore path was being
+ * debugged from the wrong end.
+ *
+ * Version only, deliberately no timestamp: the generators skip a write when the bytes are unchanged
+ * so incremental builds preserve mtimes, and a timestamp would rewrite the file — and its git
+ * history — on every build.
+ */
+export interface CliGeneratedManifestStamp {
+    /**
+     * The `@dereekb/dbx-cli` version of the generator that emitted the module.
+     */
+    readonly generatorVersion: string;
+}

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

@@ -106,7 +106,7 @@ export declare const CssUtilityEntry: import("arktype/internal/variants/object.t
         property: string;
         value: string;
     }[];
-    role?: "color" | "text" | "state" | "size" | "layout" | "misc" | "flex" | "spacing" | "interaction" | "text-color" | "surface" | "radius" | undefined;
+    role?: "color" | "state" | "text" | "size" | "layout" | "misc" | "flex" | "spacing" | "interaction" | "text-color" | "surface" | "radius" | undefined;
     intent?: string | undefined;
     seeAlso?: string[] | undefined;
     antiUse?: string | undefined;
@@ -149,7 +149,7 @@ export declare const CssUtilityManifest: import("arktype/internal/variants/objec
             property: string;
             value: string;
         }[];
-        role?: "color" | "text" | "state" | "size" | "layout" | "misc" | "flex" | "spacing" | "interaction" | "text-color" | "surface" | "radius" | undefined;
+        role?: "color" | "state" | "text" | "size" | "layout" | "misc" | "flex" | "spacing" | "interaction" | "text-color" | "surface" | "radius" | undefined;
         intent?: string | undefined;
         seeAlso?: string[] | undefined;
         antiUse?: string | undefined;

package/src/lib/runner/build-stamp.d.ts

@@ -0,0 +1,138 @@
+import { type Maybe } from '@dereekb/util';
+/**
+ * The `@dereekb/*` package prefix the drift check compares. Only framework packages are checked —
+ * a third-party range like `firebase: ^12.12.1` is deliberately out of scope.
+ */
+export declare const CLI_FRAMEWORK_PACKAGE_PREFIX = "@dereekb/";
+/**
+ * The artifact `package.json` a built CLI ships beside its entry file.
+ *
+ * `@nx/esbuild` copies the project's `package.json` verbatim into the output directory, so its
+ * exact-pinned `@dereekb/*` peer versions ARE the build stamp — the dependency tree the bundle was
+ * compiled against — with no extra build-time codegen to keep in sync.
+ */
+export interface CliArtifactPackage {
+    /**
+     * Absolute path the stamp was read from, reported so an operator can see WHICH artifact is running.
+     */
+    readonly path: string;
+    readonly name?: Maybe<string>;
+    readonly version?: Maybe<string>;
+    /**
+     * Every exact-pinned `@dereekb/*` version the artifact declares, from `peerDependencies` and
+     * `dependencies` combined.
+     */
+    readonly frameworkVersions: Readonly<Record<string, string>>;
+}
+/**
+ * One framework package whose built-against version differs from the version resolved at run time.
+ */
+export interface CliFrameworkVersionDrift {
+    readonly packageName: string;
+    readonly builtAgainst: string;
+    /**
+     * The version resolved from `node_modules` now, or `undefined` when the package is not installed.
+     */
+    readonly resolved?: Maybe<string>;
+}
+/**
+ * Why {@link inspectCliBuildDrift} could not compare anything. A report with a `reason` is `ok`: an
+ * undetectable stamp is not evidence of drift.
+ */
+export type CliBuildDriftUndeterminedReason = 'no-entry-path' | 'no-artifact-package' | 'no-framework-versions-declared'
+/**
+ * The artifact declares framework versions but NOT ONE of them resolves from `node_modules` — the
+ * signature of running from SOURCE through a workspace's tsconfig paths (a monorepo dev run), where
+ * there is no installed framework to drift from. Reporting every package as "not installed" here
+ * would make the check red on every dev run, and a check that is red by default gets ignored.
+ */
+ | 'framework-not-resolvable';
+/**
+ * The verdict on whether the running artifact matches the dependency tree it was built against.
+ */
+export interface CliBuildDriftReport {
+    readonly ok: boolean;
+    readonly reason?: Maybe<CliBuildDriftUndeterminedReason>;
+    readonly artifactPackagePath?: Maybe<string>;
+    readonly artifactVersion?: Maybe<string>;
+    /**
+     * How many framework packages were actually comparable.
+     */
+    readonly checked: number;
+    readonly drift: readonly CliFrameworkVersionDrift[];
+    /**
+     * The `@dereekb/dbx-cli` version that emitted the CLI's generated manifests, when the app passed
+     * one through.
+     */
+    readonly manifestGeneratorVersion?: Maybe<string>;
+    /**
+     * The `@dereekb/dbx-cli` version resolved at run time.
+     */
+    readonly resolvedDbxCliVersion?: Maybe<string>;
+    /**
+     * True when the manifests were generated by a DIFFERENT `@dereekb/dbx-cli` than the one now
+     * running them. This is the half the peer-version comparison cannot see: bumping the app's declared
+     * peers without re-running the generators leaves the committed manifests behind, which is how a
+     * manifest silently lost fields the runtime reads (`queryModesScanned: false` was this, unread).
+     */
+    readonly manifestGeneratorDrift: boolean;
+}
+/**
+ * Input for {@link inspectCliBuildDrift}.
+ */
+export interface InspectCliBuildDriftInput {
+    /**
+     * The executed entry file. Defaults to `process.argv[1]`.
+     */
+    readonly entryPath?: Maybe<string>;
+    /**
+     * The generator version stamped into the app's generated manifests
+     * (`<NAMESPACE>_STAMP.generatorVersion`), when the app wires one.
+     */
+    readonly manifestGeneratorVersion?: Maybe<string>;
+    /**
+     * Test seam: use this artifact stamp instead of discovering one from {@link entryPath}.
+     */
+    readonly artifactPackage?: Maybe<CliArtifactPackage>;
+    /**
+     * Test seam: resolves a package's installed version. Defaults to resolving each package's
+     * `package.json` through `createRequire`.
+     */
+    readonly resolveVersion?: (packageName: string) => Maybe<string>;
+}
+/**
+ * Compares the `@dereekb/*` versions the running artifact was BUILT against with the versions
+ * resolved from `node_modules` now.
+ *
+ * This is the check whose absence turns a routine `@dereekb/*` bump into an unreadable runtime
+ * failure. A CLI built with `thirdParty: false` inlines its app code and resolves the framework at
+ * RUN time, so the artifact is only valid against the tree it was compiled against — and nothing
+ * else in the toolchain notices when that stops being true. The symptom is arbitrary: an SDK
+ * assertion, a missing manifest field, a silently-empty result.
+ *
+ * Deliberately conservative. Only exact-pinned `@dereekb/*` versions are compared, and every way the
+ * comparison can fail to apply produces `ok: true` with a {@link CliBuildDriftUndeterminedReason} —
+ * a check that cried wolf on every source-run CLI would be turned off, and then it would be useless
+ * on the day it mattered.
+ *
+ * @param input - The entry path, the manifest generator stamp, and the test seams.
+ * @returns The drift verdict.
+ */
+export declare function inspectCliBuildDrift(input?: InspectCliBuildDriftInput): CliBuildDriftReport;
+/**
+ * Renders a {@link CliBuildDriftReport} as one operator-facing line, for `--version` and for a
+ * doctor suggestion.
+ *
+ * @param report - The report to describe.
+ * @returns The description, or `undefined` when there is nothing to say.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliBuildDriftDescription(report: CliBuildDriftReport): Maybe<string>;
+/**
+ * Finds and parses the artifact `package.json` nearest the executed entry file.
+ *
+ * @param entryPath - The executed entry file (`process.argv[1]`).
+ * @returns The parsed stamp, or `undefined` when none could be read.
+ */
+export declare function readCliArtifactPackage(entryPath: string): Maybe<CliArtifactPackage>;

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

@@ -1,2 +1,3 @@
+export * from './build-stamp';
 export * from './lifecycle';
 export * from './run';

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

@@ -146,6 +146,17 @@ export interface CreateCliInput extends CliLifecycleHooks {
      * bundler `define` or a generated module).
      */
     readonly version?: string;
+    /**
+     * The `@dereekb/dbx-cli` version that emitted this CLI's generated manifests — pass
+     * `<NAMESPACE>_STAMP.generatorVersion` from a generated manifest module.
+     *
+     * Wiring it turns the built-in `cli-build-not-stale` doctor check from "the artifact's declared
+     * peers match `node_modules`" into "…and the committed manifests were generated by that same
+     * version", which is the half the peer comparison cannot see: bumping `@dereekb/*` and rebuilding
+     * without re-running the generators leaves the manifests behind, and a manifest missing a field the
+     * runtime reads degrades silently rather than failing.
+     */
+    readonly manifestGeneratorVersion?: string;
     /**
      * The lifecycle runner guarding this invocation's {@link CliLifecycleHooks}.
      *
@@ -188,6 +199,8 @@ export interface CreateCliInput extends CliLifecycleHooks {
  *   if {@link CreateCliInput.modelManifest} is provided.
  * @param input.firestore - The app-supplied direct-Firestore binding; enables `firestore-get` / `firestore-query`.
  * @param input.firestoreQueryManifest - The generated Firestore query catalog; enables `firestore-queries`.
+ * @param input.manifestGeneratorVersion - The `@dereekb/dbx-cli` version that emitted the app's generated
+ *   manifests, for the built-in `cli-build-not-stale` doctor check.
  * @param input.setup - App hook run once before the command's handler; a throw aborts the command.
  * @param input.teardown - App hook run once after the parser settles, before the Firestore session closes.
  *   Only {@link runCli} runs it — a caller that drives `createCli().parse()` itself owns its own teardown.

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "13.42.0",
+  "version": "13.43.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.42.0",
-    "@dereekb/dbx-cli": "13.42.0",
-    "@dereekb/firebase": "13.42.0",
-    "@dereekb/firebase-server/test": "13.42.0",
-    "@dereekb/model": "13.42.0",
-    "@dereekb/nestjs": "13.42.0",
-    "@dereekb/rxjs": "13.42.0",
-    "@dereekb/util": "13.42.0",
+    "@dereekb/date": "13.43.0",
+    "@dereekb/dbx-cli": "13.43.0",
+    "@dereekb/firebase": "13.43.0",
+    "@dereekb/firebase-server/test": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/nestjs": "13.43.0",
+    "@dereekb/rxjs": "13.43.0",
+    "@dereekb/util": "13.43.0",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "vitest": "4.1.5",

package/validate/index.js

@@ -6335,6 +6335,11 @@ var RESERVED_MODEL_FOLDERS = [
     reason: "StorageFile is a canonical group from `@dereekb/firebase` with a richer layout than the base 5 files (group, upload, file, etc.); downstream projects extend rather than redeclare it.",
     recommendedTool: "dbx_storagefile_m_validate_folder"
   },
+  {
+    name: "formspace",
+    reason: "FormSpace is a canonical group from `@dereekb/firebase` with a richer layout than the base 5 files (type, upload, task, util, etc.); a downstream project only registers its own types and does not redeclare the model.",
+    recommendedTool: "dbx_model_validate_folder"
+  },
   {
     name: "calendar",
     reason: "Calendar is a canonical group from `@dereekb/firebase` with a richer layout than the base 5 files (type, expand, ics, processing, etc.); downstream projects extend rather than redeclare it.",