@dereekb/dbx-cli 14.5.1 → 14.7.0

package/lint-cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-lint-cache",
-  "version": "14.5.1",
+  "version": "14.7.0",
   "sideEffects": false,
   "private": true,
   "type": "module",
@@ -9,7 +9,7 @@
     "eslint": "10.9.1"
   },
   "peerDependencies": {
-    "@dereekb/util": "14.5.1",
+    "@dereekb/util": "14.7.0",
     "yargs": "^18.0.0"
   }
 }

package/manifest-extract/index.esm.js

@@ -695,6 +695,7 @@ var SERVICE_FACTORY_TAG = 'dbxModelServiceFactory';
 var MCP_TOOL_NAME_SEGMENT_TAG = 'dbxModelMcpToolNameSegment';
 var MODEL_TYPE_VALUE_PATTERN = /^[a-z][A-Za-z0-9_$]*$/;
 var TOOL_NAME_SEGMENT_PATTERN = /^[A-Za-z][A-Za-z0-9_$]*$/;
+var COMPOSITE_KEY_MODEL_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_$]*$/;
 var IDENTITY_FN = 'firestoreModelIdentity';
 // the declared-type counterparts of IDENTITY_FN, which is all a .d.ts retains of the call
 var IDENTITY_TYPE = 'FirestoreModelIdentity';
@@ -940,6 +941,7 @@ function buildInterface(decl) {
     var dbxModelRead = readDbxModelReadTag(jsDocs);
     var dbxModelServerOnly = jsDocsHaveTag(jsDocs, 'dbxModelServerOnly');
     var mcpToolNameSegment = readMcpToolNameSegmentTag(jsDocs);
+    var compositeKey = readDbxModelCompositeKeyTag(jsDocs);
     var extendsNames = decl.getExtends().map(resolveExtendsName);
     var props = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
@@ -988,6 +990,8 @@ function buildInterface(decl) {
         dbxModelServerOnly: true
     } : {}, mcpToolNameSegment === undefined ? {} : {
         mcpToolNameSegment: mcpToolNameSegment
+    }, compositeKey === undefined ? {} : {
+        compositeKey: compositeKey
     });
 }
 function readMcpToolNameSegmentTag(jsDocs) {
@@ -1092,6 +1096,115 @@ function readDbxModelReadTag(jsDocs) {
     }
     return result;
 }
+/**
+ * Reads the first well-formed `@dbxModelCompositeKey from=<...> encoding=<...>` tag. Both parts are
+ * required — a tag missing `from=` or carrying an unknown encoding is dropped so the manifest never
+ * publishes a composite-key declaration a consumer could not act on.
+ *
+ * @param jsDocs - JSDoc blocks attached to the interface declaration.
+ * @returns The parsed tag, or `undefined` when absent or malformed.
+ */ function readDbxModelCompositeKeyTag(jsDocs) {
+    var result;
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = jsDocs[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var doc = _step.value;
+            var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
+            try {
+                for(var _iterator1 = doc.getTags()[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
+                    var tag = _step1.value;
+                    var _tag_getCommentText;
+                    if (tag.getTagName() !== 'dbxModelCompositeKey') continue;
+                    if (result !== undefined) continue;
+                    result = parseCompositeKeyTagValue((_tag_getCommentText = tag.getCommentText()) !== null && _tag_getCommentText !== void 0 ? _tag_getCommentText : '');
+                }
+            } catch (err) {
+                _didIteratorError1 = true;
+                _iteratorError1 = err;
+            } finally{
+                try {
+                    if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
+                        _iterator1.return();
+                    }
+                } finally{
+                    if (_didIteratorError1) {
+                        throw _iteratorError1;
+                    }
+                }
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Parses the `from=<...> encoding=<...>` tokens of a `@dbxModelCompositeKey` tag.
+ *
+ * @param raw - The tag text after the tag name.
+ * @returns The declaration, or `undefined` when `from=` is missing/empty or the encoding is not
+ *   `one-way` / `two-way`.
+ */ function parseCompositeKeyTagValue(raw) {
+    var from;
+    var encoding;
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = raw.trim().split(/\s+/)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var token = _step.value;
+            var eq = token.indexOf('=');
+            if (eq <= 0) continue;
+            var key = token.slice(0, eq);
+            var value = token.slice(eq + 1);
+            if (key === 'from') {
+                from = parseCompositeKeyFromValue(value);
+            } else if (key === 'encoding' && (value === 'one-way' || value === 'two-way')) {
+                encoding = value;
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return from !== undefined && encoding !== undefined ? {
+        from: from,
+        encoding: encoding
+    } : undefined;
+}
+function parseCompositeKeyFromValue(value) {
+    var result;
+    if (value === '*') {
+        result = '*';
+    } else {
+        var names = value.split(',').map(function(x) {
+            return x.trim();
+        }).filter(function(x) {
+            return COMPOSITE_KEY_MODEL_NAME_PATTERN.test(x);
+        });
+        result = names.length > 0 ? names : undefined;
+    }
+    return result;
+}
 function readServiceFactories(sourceFile) {
     var out = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;

package/manifest-extract/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "14.5.1",
+  "version": "14.7.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.5.1",
-    "@dereekb/dbx-cli": "14.5.1",
-    "@dereekb/firebase": "14.5.1",
-    "@dereekb/model": "14.5.1",
-    "@dereekb/nestjs": "14.5.1",
-    "@dereekb/oauth-resource": "14.5.1",
-    "@dereekb/rxjs": "14.5.1",
-    "@dereekb/util": "14.5.1",
+    "@dereekb/date": "14.7.0",
+    "@dereekb/dbx-cli": "14.7.0",
+    "@dereekb/firebase": "14.7.0",
+    "@dereekb/model": "14.7.0",
+    "@dereekb/nestjs": "14.7.0",
+    "@dereekb/oauth-resource": "14.7.0",
+    "@dereekb/rxjs": "14.7.0",
+    "@dereekb/util": "14.7.0",
     "ts-morph": "^28.0.0"
   },
   "devDependencies": {
-    "@dereekb/firebase": "14.5.1"
+    "@dereekb/firebase": "14.7.0"
   },
   "exports": {
     "./package.json": "./package.json",

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

@@ -177,6 +177,27 @@ export interface ModelExtractionInterface {
      * type in generated tool names (e.g. the collection prefix). Absent when the tag is omitted or invalid.
      */
     readonly mcpToolNameSegment?: string;
+    /**
+     * Parsed `@dbxModelCompositeKey from=<ModelA>[,<ModelB>...] encoding=<two-way|one-way>` tag. Absent
+     * when the tag is omitted or malformed (no `from=`, or an encoding other than `two-way` / `one-way`).
+     */
+    readonly compositeKey?: ModelExtractionCompositeKey;
+}
+/**
+ * Parsed `@dbxModelCompositeKey` tag on a `@dbxModel`-tagged interface whose document id is a
+ * flattened encoding of another model's key.
+ */
+export interface ModelExtractionCompositeKey {
+    /**
+     * `'*'` for the wildcard form (any model may be the source), or the ordered list of source
+     * model names exactly as written (interface name, identity const, or modelType).
+     */
+    readonly from: readonly string[] | '*';
+    /**
+     * `'one-way'` for `flatFirestoreModelKey` (slashes removed), `'two-way'` for
+     * `twoWayFlatFirestoreModelKey` (slashes replaced with underscores, recoverable).
+     */
+    readonly encoding: 'one-way' | 'two-way';
 }
 /**
  * One field inside a converter's `fields` map.

package/model-test/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "14.5.1",
+  "version": "14.7.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -66,12 +66,12 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "14.5.1",
-    "@dereekb/firebase": "14.5.1",
-    "@dereekb/model": "14.5.1",
-    "@dereekb/nestjs": "14.5.1",
-    "@dereekb/oauth-resource": "14.5.1",
-    "@dereekb/util": "14.5.1",
+    "@dereekb/date": "14.7.0",
+    "@dereekb/firebase": "14.7.0",
+    "@dereekb/model": "14.7.0",
+    "@dereekb/nestjs": "14.7.0",
+    "@dereekb/oauth-resource": "14.7.0",
+    "@dereekb/util": "14.7.0",
     "@nestjs/common": "^12.0.1",
     "arktype": "^2.2.0",
     "firebase": "^12.18.0",

package/route/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/dbx-cli/route",
-  "version": "14.5.1",
+  "version": "14.7.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.5.1",
-    "@dereekb/dbx-cli": "14.5.1",
-    "@dereekb/firebase": "14.5.1",
-    "@dereekb/model": "14.5.1",
-    "@dereekb/nestjs": "14.5.1",
-    "@dereekb/oauth-resource": "14.5.1",
-    "@dereekb/util": "14.5.1"
+    "@dereekb/date": "14.7.0",
+    "@dereekb/dbx-cli": "14.7.0",
+    "@dereekb/firebase": "14.7.0",
+    "@dereekb/model": "14.7.0",
+    "@dereekb/nestjs": "14.7.0",
+    "@dereekb/oauth-resource": "14.7.0",
+    "@dereekb/util": "14.7.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/src/lib/config/token.cache.d.ts

@@ -1,4 +1,4 @@
-import { type AsyncKeyedValueCache, type Maybe } from '@dereekb/util';
+import { type AsyncKeyedValueCache, type Maybe, type OidcTokenResponse } from '@dereekb/util';
 /**
  * A cached token entry for a single env.
  */
@@ -67,3 +67,34 @@ export declare function createCliTokenCacheStore(input: CreateCliTokenCacheStore
  * @returns `true` when the token is at or within `bufferMs` of expiry, otherwise `false`.
  */
 export declare function isTokenExpired(entry: Maybe<CliTokenEntry>, nowMs?: number, bufferMs?: number): boolean;
+/**
+ * Input for {@link mergeRefreshedTokenEntry}.
+ */
+export interface MergeRefreshedTokenEntryInput {
+    readonly entry: CliTokenEntry;
+    readonly refreshed: OidcTokenResponse;
+    /**
+     * The current time in unix epoch milliseconds, used to derive `expiresAt`. Defaults to `Date.now()`.
+     */
+    readonly nowMs?: number;
+}
+/**
+ * Folds an OIDC refresh response into the cached entry it was obtained with.
+ *
+ * EVERY refresh must persist the result of this merge. A refresh CONSUMES the supplied refresh
+ * token whenever the grant rotates, so keeping the old entry leaves the cache holding a spent
+ * credential and strands the session on the next refresh — with replay detection on the provider
+ * side, reusing the spent token can revoke the whole grant. Centralized so the refresh call sites
+ * (auth middleware, `auth check`, `doctor`) cannot drift apart on this.
+ *
+ * @param input - The entry that was refreshed and the token response it produced.
+ * @returns The updated entry to persist. Fields the provider omits fall back to the previous entry.
+ */
+export declare function mergeRefreshedTokenEntry(input: MergeRefreshedTokenEntryInput): CliTokenEntry;
+/**
+ * Whether a refresh response rotated the refresh token it was obtained with.
+ *
+ * @param input - The entry that was refreshed and the token response it produced.
+ * @returns `true` when the provider issued a DIFFERENT refresh token, meaning the old one is spent.
+ */
+export declare function didRotateRefreshToken(input: Pick<MergeRefreshedTokenEntryInput, 'entry' | 'refreshed'>): boolean;

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

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

package/src/lib/doctor/token-refresh.check.d.ts

@@ -0,0 +1,32 @@
+import { discoverOidcMetadata, refreshAccessToken } from '../auth/oidc.client';
+import { type CliTokenCacheStore } from '../config/token.cache';
+import { type DoctorCheck } from './doctor.command.factory';
+/**
+ * Name reported by the check {@link createTokenRefreshDoctorCheck} builds.
+ */
+export declare const TOKEN_REFRESH_DOCTOR_CHECK_NAME = "token-refresh-round-trip";
+/**
+ * Seams for {@link createTokenRefreshDoctorCheck}. Production omits all of them and gets the real
+ * OIDC client plus the on-disk token cache; tests substitute fakes so the check's PERSIST step can
+ * be asserted without a network or a home directory.
+ */
+export interface TokenRefreshDoctorCheckOverrides {
+    readonly tokenStoreForCli?: (cliName: string) => CliTokenCacheStore;
+    readonly discoverOidcMetadata?: typeof discoverOidcMetadata;
+    readonly refreshAccessToken?: typeof refreshAccessToken;
+}
+/**
+ * Builds the doctor check that proves the cached refresh token still works.
+ *
+ * The round-trip is a REAL refresh, so on a rotating grant it consumes the cached refresh token and
+ * the response must be written back — see `mergeRefreshedTokenEntry`. Discarding it (as this check
+ * once did) leaves the cache holding a spent credential: the very next refresh fails
+ * `invalid_grant`, and a provider doing replay detection revokes the whole grant. The symptom is
+ * maximally confusing because the session dies only AFTER the cached access token lapses, so the
+ * damage surfaces well away from the `doctor` run that caused it.
+ *
+ * @param overrides - Optional test seams; production passes none.
+ * @returns The {@link DoctorCheck}.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createTokenRefreshDoctorCheck(overrides?: TokenRefreshDoctorCheckOverrides): DoctorCheck;

package/src/lib/manifest/build-model-decode-command.d.ts

@@ -1,5 +1,5 @@
 import type { CommandModule } from 'yargs';
-import type { CliModelManifest } from './types';
+import type { CliModelCompositeKeyEncoding, CliModelManifest, CliModelManifestEntry } from './types';
 /**
  * Default command name for the model-decode command. Top-level so it stays
  * out of the API-call namespace owned by `model <model> <action>`.
@@ -31,14 +31,45 @@ export interface DecodedKeySegment {
     readonly sourceFile?: string;
 }
 /**
- * Result of decoding a Firestore model key into its model + id components.
+ * Segments of a decoded Firestore key — the leaf, its ancestor chain, and any prefixes the manifest
+ * could not resolve.
  */
-export interface DecodedKey {
+export interface DecodedKeySegments {
     readonly key: string;
     readonly leaf: DecodedKeySegment;
     readonly ancestors: readonly DecodedKeySegment[];
     readonly unresolvedPrefixes: readonly string[];
 }
+/**
+ * A composite-key model whose document id is derived from the decoded key, with that document's
+ * ready-to-use key (e.g. decoding a `District` key also yields the `jobDistrict` key
+ * `jd/<flattened district key>`).
+ */
+export interface DerivedCompositeKey {
+    /**
+     * The derived document's full key (`<collectionPrefix>/<flattened source key>`).
+     */
+    readonly key: string;
+    readonly modelType: string;
+    readonly modelName: string;
+    readonly collectionPrefix: string;
+    readonly encoding: CliModelCompositeKeyEncoding;
+}
+/**
+ * Result of decoding a Firestore model key into its model + id components.
+ */
+export interface DecodedKey extends DecodedKeySegments {
+    /**
+     * Composite-key models derived from this key. Empty when the leaf prefix is unresolved or no
+     * model declares this leaf as a composite-key source.
+     */
+    readonly derivedKeys: readonly DerivedCompositeKey[];
+    /**
+     * When the leaf is itself a `two-way` composite-key model, the source key recovered from its id,
+     * decoded. Absent for `one-way` models and when the id does not parse as a flattened key.
+     */
+    readonly compositeSource?: DecodedKeySegments;
+}
 /**
  * Builds the top-level `model-decode <key>` command.
  *
@@ -58,17 +89,49 @@ export interface DecodedKey {
 export declare function buildModelDecodeCommand(manifest: CliModelManifest, options?: BuildModelDecodeCommandOptions): CommandModule;
 /**
  * Splits `rawKey` on `/`, resolves each `[prefix, id]` pair against the
- * manifest, and returns the leaf segment + ancestor chain. Throws
+ * manifest, and returns the leaf segment + ancestor chain, plus the
+ * composite-key relationships declared on the manifest: the keys of models
+ * derived from this key (`derivedKeys`) and, for a two-way composite-key
+ * leaf, the recovered source key (`compositeSource`). Throws
  * {@link CliError} for malformed inputs.
  *
+ * Mirrors the `@dereekb/firebase-server/mcp` `model-decode` tool; both
+ * implementations must stay in lockstep on segment count, resolution order,
+ * and composite-key output.
+ *
  * @param rawKey - The Firestore key string.
  * @param manifest - The generated model manifest.
- * @returns The decoded key with leaf, ancestors, and any unresolved prefixes.
+ * @returns The decoded key with leaf, ancestors, unresolved prefixes, and composite-key relationships.
  * @throws {CliError} When `rawKey` is empty or does not parse into an even number of `prefix/id` segments.
  *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function decodeFirestoreModelKey(rawKey: string, manifest: CliModelManifest): DecodedKey;
+/**
+ * Resolves the manifest entries whose `compositeKey.from` names `source` — the models whose document
+ * id is derived from a `source` document's key. A wildcard `from=*` matches every model except
+ * `source` itself.
+ *
+ * @param source - The manifest entry of the decoded key's leaf model.
+ * @param manifest - The generated model manifest.
+ * @returns The composite-key entries derived from `source`, in manifest order.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function findCompositeKeyModelsDerivedFrom(source: CliModelManifestEntry, manifest: CliModelManifest): CliModelManifestEntry[];
+/**
+ * Splits `rawKey` on `/` and resolves each `[prefix, id]` pair against the
+ * manifest — the segment walk shared by {@link decodeFirestoreModelKey} and
+ * the two-way composite-source decode.
+ *
+ * @param rawKey - The Firestore key string.
+ * @param manifest - The generated model manifest.
+ * @returns The decoded key with leaf, ancestors, and any unresolved prefixes.
+ * @throws {CliError} When `rawKey` is empty or does not parse into an even number of `prefix/id` segments.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function decodeFirestoreModelKeySegments(rawKey: string, manifest: CliModelManifest): DecodedKeySegments;
 /**
  * Renders a {@link DecodedKey} as a human-readable text block. Mirrors the
  * MCP `dbx_model_decode` key-mode output for consistency between agent and

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

@@ -185,6 +185,37 @@ export interface CliModelManifestEntry {
         readonly exportName: string;
         readonly sourceFile: string;
     };
+    /**
+     * Declared `@dbxModelCompositeKey from=<ModelA>[,<ModelB>...] encoding=<two-way|one-way>` on the
+     * model interface — this model's document id is a flattened encoding of a source model's key.
+     * Absent when the model omits the tag.
+     *
+     * Consumed by `model-decode` (to publish the derived key when a source key is decoded, and to
+     * recover the source key from a two-way id) and by `model-get` (to accept a source key in place
+     * of the flattened id).
+     */
+    readonly compositeKey?: CliModelCompositeKey;
+}
+/**
+ * Flat-key encoding declared by a `@dbxModelCompositeKey` tag.
+ *
+ * - `one-way` — `flatFirestoreModelKey()`: slashes removed; the source key cannot be recovered
+ *   from the id.
+ * - `two-way` — `twoWayFlatFirestoreModelKey()`: slashes replaced with underscores; recover the
+ *   source key with `inferKeyFromTwoWayFlatFirestoreModelKey()`.
+ */
+export type CliModelCompositeKeyEncoding = 'one-way' | 'two-way';
+/**
+ * Composite-key declaration carried on a {@link CliModelManifestEntry}.
+ */
+export interface CliModelCompositeKey {
+    /**
+     * `'*'` when any model's key may be the source (framework models such as `NotificationBox`), or
+     * the source model names as written in the tag — each an interface name, identity const, or
+     * modelType, resolved against the manifest at decode time.
+     */
+    readonly from: readonly string[] | '*';
+    readonly encoding: CliModelCompositeKeyEncoding;
 }
 /**
  * Generated array of {@link CliModelManifestEntry} consumed by `model-info`
@@ -394,6 +425,11 @@ export interface McpManifestModelEntry {
      * client read grant in `firestore.rules` either) rather than a missing role it could be granted.
      */
     readonly serverOnly?: boolean;
+    /**
+     * Composite-key declaration (mirror of {@link CliModelManifestEntry.compositeKey}). Lets the
+     * runtime `model-decode` publish derived keys and `model-get` accept a source key.
+     */
+    readonly compositeKey?: CliModelCompositeKey;
 }
 /**
  * One auth claim entry in the pre-rendered MCP manifest JSON. Powers the

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

@@ -44,6 +44,15 @@ export interface LoadUtilRegistryResult {
     readonly loaderWarnings: readonly UtilLoaderWarning[];
     readonly externalSourceCount: number;
 }
+/**
+ * The bundled `@dereekb/*` utils manifests to load at startup. Must stay in step with the `utils.scan` entries in
+ * `dbx-mcp.config.json` — a generated manifest that is missing from this list is silently invisible to
+ * `dbx_util_lookup`/`dbx_util_search` no matter how well its exports are tagged.
+ *
+ * Loading is non-strict, so naming a file that a given workspace has not generated warns and skips rather than
+ * failing server startup.
+ */
+export declare const DEFAULT_BUNDLED_FILENAMES: readonly ["dereekb-util.utils.mcp.generated.json", "dereekb-util-fetch.utils.mcp.generated.json", "dereekb-date.utils.mcp.generated.json", "dereekb-rxjs.utils.mcp.generated.json", "dereekb-model.utils.mcp.generated.json", "dereekb-firebase.utils.mcp.generated.json", "dereekb-firebase-server.utils.mcp.generated.json"];
 /**
  * Loads the merged utils registry for the current MCP server.
  *

package/src/lib/util/output.d.ts

@@ -185,6 +185,32 @@ export declare function buildDumpFilePath(extension: 'json' | 'ndjson', suffix?:
  * @returns The filtered value (typed as the input).
  */
 export declare function pickFields<T>(data: T, pick: string): T;
+/**
+ * Applies the configured `--pick` filter to the document payload(s) carried by a command result.
+ *
+ * Returns `unknown` rather than `T` because picking REDUCES each payload — the reduced value is a
+ * partial view of the document and does not satisfy the result's own type.
+ *
+ * @param data - The full command result.
+ * @param pick - Reduces a document to the configured fields. Apply it to each payload, not the wrapper.
+ * @returns The result with its payload(s) reduced, wrapper fields intact.
+ */
+export type CliOutputPickApplier<T> = (data: T, pick: (value: unknown) => unknown) => unknown;
+/**
+ * Per-command output overrides for {@link outputResult}.
+ */
+export interface CliOutputResultOptions<T> {
+    /**
+     * Redirects the `--pick` filter into the result's document payload(s).
+     *
+     * Read commands wrap documents in an envelope (`{ key, data }`, `{ results, errors }`), so the
+     * default top-level pick can only ever match the wrapper's own keys — a pick naming real document
+     * fields silently yields `{}`, which is indistinguishable from an empty document. Supplied by the
+     * command because only it knows its envelope shape. Commands whose result *is* the payload
+     * (the common case) omit this and keep the top-level behavior.
+     */
+    readonly applyPick?: CliOutputPickApplier<T>;
+}
 /**
  * Prints a successful command result as a `{ ok: true, data, meta? }` JSON envelope on stdout.
  *
@@ -194,8 +220,9 @@ export declare function pickFields<T>(data: T, pick: string): T;
  *
  * @param data - The command result to emit.
  * @param meta - Optional additional metadata to attach to the envelope.
+ * @param options - Optional per-command overrides — see {@link CliOutputResultOptions}.
  */
-export declare function outputResult<T>(data: T, meta?: Record<string, unknown>): void;
+export declare function outputResult<T>(data: T, meta?: Record<string, unknown>, options?: CliOutputResultOptions<T>): void;
 /**
  * Prints a failed command result as a `{ ok: false, error, code, suggestion? }` JSON envelope on stdout.
  *

package/test/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "14.5.1",
+  "version": "14.7.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.5.1",
-    "@dereekb/dbx-cli": "14.5.1",
-    "@dereekb/firebase": "14.5.1",
-    "@dereekb/firebase-server/test": "14.5.0",
-    "@dereekb/model": "14.5.1",
-    "@dereekb/nestjs": "14.5.1",
-    "@dereekb/oauth-resource": "14.5.1",
-    "@dereekb/rxjs": "14.5.1",
-    "@dereekb/util": "14.5.1",
+    "@dereekb/date": "14.7.0",
+    "@dereekb/dbx-cli": "14.7.0",
+    "@dereekb/firebase": "14.7.0",
+    "@dereekb/firebase-server/test": "14.6.0",
+    "@dereekb/model": "14.7.0",
+    "@dereekb/nestjs": "14.7.0",
+    "@dereekb/oauth-resource": "14.7.0",
+    "@dereekb/rxjs": "14.7.0",
+    "@dereekb/util": "14.7.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.5.1",
+  "version": "14.7.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.5.1",
-    "@dereekb/util": "14.5.1",
+    "@dereekb/dbx-cli": "14.7.0",
+    "@dereekb/util": "14.7.0",
     "ts-morph": "^28.0.0"
   }
 }