@dereekb/dbx-cli 14.5.0 → 14.6.0

package/lint-cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-lint-cache",
-  "version": "14.5.0",
+  "version": "14.6.0",
   "sideEffects": false,
   "private": true,
   "type": "module",
@@ -9,7 +9,7 @@
     "eslint": "10.9.1"
   },
   "peerDependencies": {
-    "@dereekb/util": "14.5.0",
+    "@dereekb/util": "14.6.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.0",
+  "version": "14.6.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.5.0",
-    "@dereekb/dbx-cli": "14.5.0",
-    "@dereekb/firebase": "14.5.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",
+    "@dereekb/date": "14.6.0",
+    "@dereekb/dbx-cli": "14.6.0",
+    "@dereekb/firebase": "14.6.0",
+    "@dereekb/model": "14.6.0",
+    "@dereekb/nestjs": "14.6.0",
+    "@dereekb/oauth-resource": "14.6.0",
+    "@dereekb/rxjs": "14.6.0",
+    "@dereekb/util": "14.6.0",
     "ts-morph": "^28.0.0"
   },
   "devDependencies": {
-    "@dereekb/firebase": "14.5.0"
+    "@dereekb/firebase": "14.6.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.0",
+  "version": "14.6.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/util": "14.5.0",
+    "@dereekb/util": "14.6.0",
     "ts-morph": "^28.0.0"
   },
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "14.5.0",
+  "version": "14.6.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -66,12 +66,12 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "14.5.0",
-    "@dereekb/firebase": "14.5.0",
-    "@dereekb/model": "14.5.0",
-    "@dereekb/nestjs": "14.5.0",
-    "@dereekb/oauth-resource": "14.5.0",
-    "@dereekb/util": "14.5.0",
+    "@dereekb/date": "14.6.0",
+    "@dereekb/firebase": "14.6.0",
+    "@dereekb/model": "14.6.0",
+    "@dereekb/nestjs": "14.6.0",
+    "@dereekb/oauth-resource": "14.6.0",
+    "@dereekb/util": "14.6.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.0",
+  "version": "14.6.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.5.0",
-    "@dereekb/dbx-cli": "14.5.0",
-    "@dereekb/firebase": "14.5.0",
-    "@dereekb/model": "14.5.0",
-    "@dereekb/nestjs": "14.5.0",
-    "@dereekb/oauth-resource": "14.5.0",
-    "@dereekb/util": "14.5.0"
+    "@dereekb/date": "14.6.0",
+    "@dereekb/dbx-cli": "14.6.0",
+    "@dereekb/firebase": "14.6.0",
+    "@dereekb/model": "14.6.0",
+    "@dereekb/nestjs": "14.6.0",
+    "@dereekb/oauth-resource": "14.6.0",
+    "@dereekb/util": "14.6.0"
   },
   "exports": {
     "./package.json": "./package.json",

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/test/package.json

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