@dereekb/dbx-cli 14.3.0 → 14.5.0

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

@@ -1,12 +1,9 @@
 import { type FirestoreModelKey, type FirestoreModelType } from '@dereekb/firebase';
 import { type Maybe } from '@dereekb/util';
+import { type FirebaseClientFirestoreIdentityContext, type FirebaseClientFirestoreIdentityProblem, type FirebaseClientFirestoreIdentityReport, type FirebaseClientFirestoreSdkModuleIdentity } from '@dereekb/oauth-resource/firebase';
 /**
- * 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.
+ * The `drivers.firestoreDriverIdentifier` a client-SDK `FirestoreContext` reports. See
+ * {@link CLIENT_FIRESTORE_DRIVER_IDENTIFIER}.
  */
 export declare const CLI_CLIENT_FIRESTORE_DRIVER_IDENTIFIER = "@firebase/firestore";
 /**
@@ -22,94 +19,31 @@ export declare const FIRESTORE_SDK_IDENTITY_STAGE = "firestore-sdk-identity";
  */
 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.
+ * `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.
  */
- | 'duplicated-firestore-sdk'
+export declare const FIRESTORE_COLLECTION_UNRESOLVABLE_CODE = "FIRESTORE_COLLECTION_UNRESOLVABLE";
 /**
- * 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.
+ * The distinct ways a session's Firestore handle can be unusable. See
+ * {@link FirebaseClientFirestoreIdentityProblem}.
  */
- | 'foreign-firestore-instance';
+export type CliFirestoreSdkIdentityProblem = FirebaseClientFirestoreIdentityProblem;
 /**
- * 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.
+ * Where one consumer resolved `@firebase/firestore` to, and at which version. See
+ * {@link FirebaseClientFirestoreSdkModuleIdentity}.
  */
-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>;
-}
+export type CliFirestoreSdkModuleIdentity = FirebaseClientFirestoreSdkModuleIdentity;
 /**
- * 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.
+ * The provenance + brand-check report {@link inspectCliFirestoreSdkIdentity} produces. See
+ * {@link FirebaseClientFirestoreIdentityReport}.
  */
-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;
-}
+export type CliFirestoreSdkIdentityReport = FirebaseClientFirestoreIdentityReport;
 /**
- * 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.
+ * The slice of a session context {@link inspectCliFirestoreSdkIdentity} reads. See
+ * {@link FirebaseClientFirestoreIdentityContext}.
  */
-export interface CliFirestoreSdkIdentityContext {
-    readonly firestore?: unknown;
-    readonly drivers?: {
-        readonly firestoreDriverIdentifier?: unknown;
-    };
-}
+export type CliFirestoreSdkIdentityContext = FirebaseClientFirestoreIdentityContext;
 /**
  * Input for {@link inspectCliFirestoreSdkIdentity}.
  */
@@ -117,20 +51,12 @@ 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.
+ * Checks that a session's Firestore handle is one the loaded client SDK will accept, and reports
+ * where every consumer resolved the SDK from.
  *
- * 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.)
+ * The CLI wrapper over {@link inspectFirebaseClientFirestoreIdentity}: it supplies this package's own
+ * `require` as the resolution root and names the CLI in the report, so `doctor`'s output is unchanged
+ * by the move of the inspection core into `@dereekb/oauth-resource/firebase`.
  *
  * @param input - The session's `firestoreContext`, when one was built.
  * @returns The provenance + brand-check report.
@@ -149,12 +75,6 @@ export declare function inspectCliFirestoreSdkIdentity(input: InspectCliFirestor
  * @__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}.
  */

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

@@ -1,7 +1,4 @@
-import { type FirebaseApp } from 'firebase/app';
-import { type Auth } from 'firebase/auth';
-import { type Firestore } from 'firebase/firestore';
-import { type FirestoreContext } from '@dereekb/firebase';
+import { type FirebaseUserSession } from '@dereekb/oauth-resource/firebase';
 import { type CliFirestoreSession } from '../api/firestore-session.client';
 import { type CliEnvConfig } from '../config/env';
 import { type CliFirestoreSessionCacheStore } from '../config/firestore-session.cache';
@@ -9,25 +6,23 @@ import { type CliFirestoreSessionCacheStore } from '../config/firestore-session.
  * A live direct-Firestore session: the Firebase client objects the CLI signed in with, plus the
  * `FirestoreContext` an app's collections factory consumes.
  *
+ * The CLI's view of {@link FirebaseUserSession}, whose implementation lives in
+ * `@dereekb/oauth-resource/firebase` so any resource server that verified a bearer token carrying the
+ * `session.firestore` scope gets the same bridge.
+ *
  * The `firestoreContext` is built by `clientFirebaseFirestoreContextFactory`, the exact analogue of
  * the server's `googleCloudFirestoreContextFactory` — both satisfy `FirestoreContextFactory` — so an
  * app's `make<App>FirestoreCollections(context)` accepts it unchanged, and the CLI runs the SAME
  * queries the Angular app runs, through the SAME security rules.
  */
-export interface CliFirestoreSessionContext {
+export interface CliFirestoreSessionContext extends FirebaseUserSession {
     /**
      * The credential bundle the API minted for this session.
+     *
+     * The CLI's long-standing name for {@link FirebaseUserSession.credentials}; both name the same
+     * object.
      */
     readonly session: CliFirestoreSession;
-    /**
-     * True when {@link session} came from the on-disk session cache rather than a fresh
-     * `GET /session/firestore`. Surfaced for `doctor` and `--verbose`, not for control flow.
-     */
-    readonly fromCache: boolean;
-    readonly app: FirebaseApp;
-    readonly auth: Auth;
-    readonly firestore: Firestore;
-    readonly firestoreContext: FirestoreContext;
 }
 export interface CreateCliFirestoreSessionContextInput {
     readonly cliName: string;
@@ -49,39 +44,15 @@ export interface CreateCliFirestoreSessionContextInput {
      */
     readonly refreshSession?: boolean;
 }
-/**
- * The Firebase app name a direct-Firestore session registers for a CLI + env pair.
- *
- * Deriving the name rather than tracking apps in a side registry is what makes ONE app per CLI + env
- * per process a property of the code instead of a convention: {@link createCliFirestoreSessionContext}
- * looks this name up in `getApps()` before initializing, so repeated session opens in one process —
- * a doctor probe alongside a command's own session, an action that re-resolves the accessor — all
- * share a single app, and {@link closeAllCliFirebaseApps} finds it again from the name alone.
- *
- * @param input - The CLI name and env name the session targets.
- * @returns The Firebase app name for that pair.
- * @__NO_SIDE_EFFECTS__
- */
-export declare function cliFirebaseAppName(input: Pick<CreateCliFirestoreSessionContextInput, 'cliName' | 'envName'>): string;
 /**
  * Opens a direct Firestore connection as the authenticated CLI user.
  *
- * Steps, in a strict order:
+ * A thin wrapper over `openFirebaseUserSession`: it validates the env's Firebase client config with
+ * the CLI's own env-var-naming remediation, then delegates. The strict step ORDER (mint → fresh app →
+ * App Check FIRST → emulator wiring → sign-in) and its reasoning live with the implementation.
  *
- * 0. When a `sessionCache` is supplied, reuse the env's cached credential envelope if it is still
- *    live. Sessions are cached for up to an hour (see `CLI_FIRESTORE_SESSION_MAX_CACHE_MS`), which is
- *    the ceiling the Firebase credentials themselves sit under. A hit skips step 1 only — the
- *    Firebase app is per-process, so the sign-in in step 5 always runs.
- * 1. `GET <apiBaseUrl>/session/firestore` for a custom token + App Check attestation.
- * 2. `initializeApp` with the env's Firebase client config.
- * 3. `initializeAppCheck` with a `CustomProvider` handing back the server-minted token. **This must
- *    happen before any other Firebase call** — `dbx-firebase`'s provider documents the same
- *    constraint: "App Check must be initialized before any Firebase request goes out, otherwise
- *    requests are sent without an App Check token and are rejected in production." Skipped when the
- *    env targets emulators (which do not verify attestations) or when the API minted no token.
- * 4. `getAuth` / `getFirestore`, connecting each to its emulator when configured.
- * 5. `signInWithCustomToken`. The user's stored custom claims land at the top level of the exchanged
- *    ID token, so `request.auth.token.<claim>` reads in security rules behave exactly as in the app.
+ * The session's Firebase app is named `<cliName>::<envName>::<uid>`, so
+ * {@link closeAllCliFirebaseApps} finds every app this CLI opened from the name alone.
  *
  * There is deliberately NO fallback to the HTTP model API — a failure here throws so the operator
  * sees it. `createFirestoreSessionDoctorCheck` is the diagnostic surface for why.
@@ -96,15 +67,7 @@ export declare function createCliFirestoreSessionContext(input: CreateCliFiresto
  *
  * Required for the CLI to EXIT. A signed-in `Auth` and a live `Firestore` both hold open handles
  * that keep the Node event loop alive indefinitely, so without this a command prints its result and
- * then hangs forever — the process never returns to the shell. Nothing in the CLI is long-lived
- * enough to want that: a session is opened for one invocation and is dead weight afterwards.
- *
- * `deleteApp` is the single call that covers it — it disposes every registered component, which for
- * Firestore runs the same shutdown `terminate()` does, and for Auth stops the token-refresh timer.
- *
- * Deliberately tolerant: teardown runs in a `finally` after the command has already produced its
- * output, so a failure here must not change the exit code or mask the real result. A session that
- * was never opened is a no-op.
+ * then hangs forever — the process never returns to the shell.
  *
  * @param session - The session context to close.
  */
@@ -112,23 +75,15 @@ export declare function closeCliFirestoreSessionContext(session: CliFirestoreSes
 /**
  * Deletes every still-live Firebase app this CLI opened, whether or not a session was handed back.
  *
- * The CLI's last line of defence against a hang. `closeCliFirestoreSessionContext` covers the normal
- * path, but it needs a session to be handed to it, and three cases never produce one:
+ * The CLI's last line of defence against a hang. {@link closeCliFirestoreSessionContext} covers the
+ * normal path, but it needs a session to be handed to it, and three cases never produce one:
  *
- * - a handshake that fails AFTER `initializeApp` — a rejected custom token, a failed App Check
- *   registration — throws, so the caller that catches it has an initialized app and no session;
+ * - a handshake that fails AFTER `initializeApp` — a failed App Check registration, a broken emulator
+ *   connection — throws, so the caller that catches it has an initialized app and no session;
  * - a caller that opens its own session outside the context memo (the doctor probe) owns its own
  *   teardown, and forgetting it hangs the process;
  * - a {@link CliContext} orphaned mid-invocation carries the only reference to its session memo.
  *
- * Each leaves an app whose `Firestore` and signed-in `Auth` hold the Node event loop open forever.
- * `getApps()` already tracks every live app and `deleteApp` removes it from that list, so the app
- * names {@link cliFirebaseAppName} derives are enough to find them again — no side registry to keep
- * in sync, and idempotent by construction.
- *
- * Tolerant of failures for the same reason {@link closeCliFirestoreSessionContext} is: it runs after
- * the result is already on stdout.
- *
  * @param input - The function inputs.
  * @param input.cliName - The CLI whose apps should be closed. Apps belonging to other Firebase
  *   consumers in the same process are left alone.

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

@@ -9,6 +9,7 @@
 export * from './scan-config-schema.js';
 export * from './extract.js';
 export * from './build-manifest.js';
+export * from './sanitize-type-text.js';
 export * from './cli.js';
 export * from './filters-cli.js';
 export * from './filters-extract.js';

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

@@ -26,6 +26,12 @@ export type BuildModelSnapshotFieldsGlobber = ScanGlobber;
 export interface BuildModelSnapshotFieldsManifestInput {
     readonly projectRoot: string;
     readonly generator: string;
+    /**
+     * Absolute workspace root that absolute paths baked into type text are made
+     * relative to. Defaults to `process.cwd()`, which is the workspace root because
+     * the generate-* targets all run with `cwd: {workspaceRoot}`.
+     */
+    readonly workspaceRoot?: string;
     readonly now?: () => Date;
     readonly readFile?: BuildModelSnapshotFieldsReadFile;
     readonly globber?: BuildModelSnapshotFieldsGlobber;

package/src/lib/mcp-scan/scan/sanitize-type-text.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Makes ts-morph type text reproducible across checkouts.
+ *
+ * TypeScript emits `import("<absolute path>").Type` for any type it cannot name
+ * from the enclosing scope, and ts-morph surfaces that text verbatim. The path is
+ * machine-specific: it is the host checkout on a developer's machine and `/code`
+ * inside the build container's bind mount.
+ *
+ * That difference is not cosmetic. The generated manifests are tracked files under
+ * `packages/dbx-cli/generated`, which is inside `dbx-cli`'s project root, and the
+ * workspace's `default` named input is `{projectRoot}/**\/*`. So an absolute path
+ * baked into a manifest invalidates the Nx cache for `dbx-cli` — and everything
+ * downstream of it — on every alternation between a host build and a container
+ * build, and leaves the git tree permanently dirty.
+ *
+ * Rewriting the path to be workspace-relative makes the emitted bytes identical
+ * everywhere the workspace is checked out.
+ */
+/**
+ * Input to {@link sanitizeTypeText}.
+ */
+export interface SanitizeTypeTextInput {
+    /**
+     * Type text as reported by the type checker, possibly containing one or more
+     * `import("<absolute path>")` segments.
+     */
+    readonly typeText: string;
+    /**
+     * Absolute path to the workspace root that emitted paths are made relative to.
+     */
+    readonly workspaceRoot: string;
+}
+/**
+ * Rewrites every absolute `import("…")` path in `typeText` to a workspace-relative,
+ * forward-slashed path.
+ *
+ * Paths that are already relative, or that resolve outside `workspaceRoot`, are left
+ * untouched — there is no stable shorter form for them, and rewriting to a `../`
+ * chain would reintroduce the machine dependence this exists to remove.
+ *
+ * @param input - The type text and the workspace root to relativize against.
+ * @returns The type text with workspace-internal absolute paths relativized.
+ */
+export declare function sanitizeTypeText(input: SanitizeTypeTextInput): string;

package/src/lib/mcp-scan/scan/utils-build-manifest.d.ts

@@ -25,6 +25,12 @@ export type BuildUtilsGlobber = ScanGlobber;
 export interface BuildUtilsManifestInput {
     readonly projectRoot: string;
     readonly generator: string;
+    /**
+     * Absolute workspace root that absolute paths baked into type text are made
+     * relative to. Defaults to `process.cwd()`, which is the workspace root because
+     * the generate-* targets all run with `cwd: {workspaceRoot}`.
+     */
+    readonly workspaceRoot?: string;
     readonly now?: () => Date;
     readonly readFile?: BuildUtilsReadFile;
     readonly globber?: BuildUtilsGlobber;

package/test/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "14.3.0",
+  "version": "14.5.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.3.0",
-    "@dereekb/dbx-cli": "14.3.0",
-    "@dereekb/firebase": "14.3.0",
-    "@dereekb/firebase-server/test": "14.3.0",
-    "@dereekb/model": "14.3.0",
-    "@dereekb/nestjs": "14.3.0",
-    "@dereekb/rxjs": "14.3.0",
-    "@dereekb/util": "14.3.0",
+    "@dereekb/date": "14.5.0",
+    "@dereekb/dbx-cli": "14.5.0",
+    "@dereekb/firebase": "14.5.0",
+    "@dereekb/firebase-server/test": "14.4.0",
+    "@dereekb/model": "14.5.0",
+    "@dereekb/nestjs": "14.5.0",
+    "@dereekb/oauth-resource": "14.5.0",
+    "@dereekb/rxjs": "14.5.0",
+    "@dereekb/util": "14.5.0",
     "@nestjs/common": "^12.0.1",
     "arktype": "^2.2.0",
     "vitest": "4.1.11",

package/validate/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/dbx-cli/validate",
-  "version": "14.3.0",
+  "version": "14.5.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.3.0",
-    "@dereekb/util": "14.3.0",
+    "@dereekb/dbx-cli": "14.5.0",
+    "@dereekb/util": "14.5.0",
     "ts-morph": "^28.0.0"
   }
 }