@dereekb/dbx-components-mcp 14.5.1 → 14.7.0

package/dbx-components-mcp.js

@@ -10,7 +10,7 @@ var __export = (target, all) => {
 // packages/dbx-components-mcp/package.json
 var package_default = {
   name: "@dereekb/dbx-components-mcp",
-  version: "14.5.1",
+  version: "14.7.0",
   sideEffects: false,
   type: "module",
   bin: {
@@ -22,8 +22,8 @@ var package_default = {
     "ts-morph": "^21.0.0"
   },
   peerDependencies: {
-    "@dereekb/dbx-cli": "14.5.1",
-    "@dereekb/util": "14.5.1"
+    "@dereekb/dbx-cli": "14.7.0",
+    "@dereekb/util": "14.7.0"
   }
 };
 
@@ -2337,6 +2337,10 @@ var FIREBASE_MODELS = [
     description: "Root notification container for a model. The document ID is the two-way flat key of the model it represents (see {@link notificationBoxIdForModel} in `notification.id.ts`).",
     modelGroup: "Notification",
     collectionKind: "root",
+    compositeKey: {
+      from: "*",
+      encoding: "two-way"
+    },
     archetypes: ["composite-key-root"]
   },
   {
@@ -2417,6 +2421,10 @@ var FIREBASE_MODELS = [
     description: "Aggregated notification feed for a specific model. Holds embedded {@link NotificationItem} entries that summarize recent notifications, similar to an activity feed.",
     modelGroup: "Notification",
     collectionKind: "root",
+    compositeKey: {
+      from: "*",
+      encoding: "two-way"
+    },
     archetypes: ["root-singleton-aggregate", "composite-key-root"]
   },
   {
@@ -15996,7 +16004,15 @@ async function loadUtilManifests(input) {
 }
 
 // packages/dbx-cli/src/lib/mcp-scan/manifest/load-utils-registry.ts
-var DEFAULT_BUNDLED_FILENAMES12 = ["dereekb-util.utils.mcp.generated.json", "dereekb-date.utils.mcp.generated.json", "dereekb-rxjs.utils.mcp.generated.json", "dereekb-model.utils.mcp.generated.json"];
+var DEFAULT_BUNDLED_FILENAMES12 = [
+  "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"
+];
 var DEFAULT_BUNDLED_PATHS12 = () => {
   const packageRoot = findPackageRoot(import.meta.url);
   return DEFAULT_BUNDLED_FILENAMES12.map((name) => resolve33(packageRoot, "generated", name));
@@ -29467,6 +29483,7 @@ var SERVICE_FACTORY_TAG = "dbxModelServiceFactory";
 var MCP_TOOL_NAME_SEGMENT_TAG = "dbxModelMcpToolNameSegment";
 var MODEL_TYPE_VALUE_PATTERN2 = /^[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";
 var IDENTITY_TYPE = "FirestoreModelIdentity";
 var ROOT_IDENTITY_TYPE = "RootFirestoreModelIdentity";
@@ -29583,6 +29600,7 @@ function buildInterface2(decl) {
   const dbxModelRead = readDbxModelReadTag(jsDocs);
   const dbxModelServerOnly = jsDocsHaveTag(jsDocs, "dbxModelServerOnly");
   const mcpToolNameSegment = readMcpToolNameSegmentTag(jsDocs);
+  const compositeKey2 = readDbxModelCompositeKeyTag2(jsDocs);
   const extendsNames = decl.getExtends().map(resolveExtendsName);
   const props = [];
   for (const prop of decl.getProperties()) {
@@ -29608,7 +29626,8 @@ function buildInterface2(decl) {
     props,
     ...dbxModelRead === void 0 ? {} : { dbxModelRead },
     ...dbxModelServerOnly ? { dbxModelServerOnly: true } : {},
-    ...mcpToolNameSegment === void 0 ? {} : { mcpToolNameSegment }
+    ...mcpToolNameSegment === void 0 ? {} : { mcpToolNameSegment },
+    ...compositeKey2 === void 0 ? {} : { compositeKey: compositeKey2 }
   };
 }
 function readMcpToolNameSegmentTag(jsDocs) {
@@ -29643,6 +29662,43 @@ function readDbxModelReadTag(jsDocs) {
   }
   return result;
 }
+function readDbxModelCompositeKeyTag2(jsDocs) {
+  let result;
+  for (const doc of jsDocs) {
+    for (const tag of doc.getTags()) {
+      if (tag.getTagName() !== "dbxModelCompositeKey") continue;
+      if (result !== void 0) continue;
+      result = parseCompositeKeyTagValue2(tag.getCommentText() ?? "");
+    }
+  }
+  return result;
+}
+function parseCompositeKeyTagValue2(raw) {
+  let from;
+  let encoding;
+  for (const token of raw.trim().split(/\s+/)) {
+    const eq = token.indexOf("=");
+    if (eq <= 0) continue;
+    const key = token.slice(0, eq);
+    const value = token.slice(eq + 1);
+    if (key === "from") {
+      from = parseCompositeKeyFromValue3(value);
+    } else if (key === "encoding" && (value === "one-way" || value === "two-way")) {
+      encoding = value;
+    }
+  }
+  return from !== void 0 && encoding !== void 0 ? { from, encoding } : void 0;
+}
+function parseCompositeKeyFromValue3(value) {
+  let result;
+  if (value === "*") {
+    result = "*";
+  } else {
+    const names = value.split(",").map((x) => x.trim()).filter((x) => COMPOSITE_KEY_MODEL_NAME_PATTERN.test(x));
+    result = names.length > 0 ? names : void 0;
+  }
+  return result;
+}
 function readServiceFactories(sourceFile) {
   const out = [];
   for (const statement of sourceFile.getVariableStatements()) {
@@ -40781,7 +40837,7 @@ var DBX_MODEL_DECODE_TOOL = {
     "",
     'Document mode \u2014 pass `data` as a JSON string (copied straight from the Firestore console) or an already-parsed object to identify the model, expand abbreviated field names, decode enum integer values, and surface foreign-key relationships. Optionally pass `model` to skip detection and target a specific model by interface name (`"StorageFile"`), identity constant (`"storageFileIdentity"`), `modelType` (`"storageFile"`), or collection prefix (`"sf"`).',
     "",
-    'Key mode \u2014 pass just `key` (e.g. `"jwr/hkzQa9W6MpaP99RTlQJcImbWdZm2"`) to resolve the model identity and id from the collection prefix alone, no document required. Subcollection paths like `"nb/abc/nbn/def"` are walked end-to-end so the leaf model is reported alongside its parent chain.',
+    'Key mode \u2014 pass just `key` (e.g. `"jwr/hkzQa9W6MpaP99RTlQJcImbWdZm2"`) to resolve the model identity and id from the collection prefix alone, no document required. Subcollection paths like `"nb/abc/nbn/def"` are walked end-to-end so the leaf model is reported alongside its parent chain. Composite-key models derived from the key (`@dbxModelCompositeKey from=\u2026`) are listed with their ready-to-use flattened keys, and a two-way composite-key leaf reports the source key recovered from its id.',
     "",
     "At least one of `data` or `key` is required."
   ].join("\n"),
@@ -40905,6 +40961,29 @@ function buildPrefixMap() {
   }
   return out;
 }
+function findDerivedCompositeKeys(rawKey, leafModel) {
+  const out = [];
+  for (const model of FIREBASE_MODELS) {
+    const compositeKey2 = model.compositeKey;
+    if (!compositeKey2 || model.modelType === leafModel.modelType) continue;
+    const matches = compositeKey2.from === "*" || compositeKey2.from.some((name) => name === leafModel.name || name === leafModel.identityConst || name === leafModel.modelType);
+    if (!matches) continue;
+    const flatId = compositeKey2.encoding === "two-way" ? rawKey.replaceAll("/", "_") : rawKey.replaceAll("/", "");
+    out.push({ key: `${model.collectionPrefix}/${flatId}`, model, encoding: compositeKey2.encoding });
+  }
+  return out;
+}
+function decodeCompositeSource(leaf) {
+  let result;
+  if (leaf.model?.compositeKey?.encoding === "two-way" && leaf.id.includes("_")) {
+    const sourceKey = leaf.id.replaceAll("_", "/");
+    const decoded = decodeKeyPath(sourceKey, void 0);
+    if (!("error" in decoded)) {
+      result = { key: sourceKey, path: decoded };
+    }
+  }
+  return result;
+}
 function decodeKeyPath(key, hint) {
   const trimmed = key.trim();
   if (trimmed.length === 0) {
@@ -40971,8 +41050,24 @@ function formatUnresolved(unresolvedPrefixes) {
   const list = unresolvedPrefixes.map((p) => `\`${p}\``).join(", ");
   return ["", `_Unresolved ${label}: ${list}. Run \`dbx_model_lookup\` to browse known models._`];
 }
+function formatCompositeSource(source) {
+  if (!source) return [];
+  const sourceModel = source.path.leaf.model ? source.path.leaf.model.name : `_unknown_ (prefix \`${source.path.leaf.prefix}\`)`;
+  return ["", `**Composite source (two-way):** \`${source.key}\` \u2192 ${sourceModel}`];
+}
+function formatDerivedKeys(derived) {
+  if (derived.length === 0) return [];
+  const out = ["", "**Derived keys:**"];
+  for (const entry of derived) {
+    out.push(`- ${entry.model.name} (${entry.encoding}) \u2014 \`${entry.key}\``);
+  }
+  return out;
+}
 function formatKeyDecode(input, rawKey) {
-  const lines = ["_Model decoded from key prefix._", "", ...formatLeaf(input.leaf), ...formatAncestors(input.ancestors), ...formatUnresolved(input.unresolvedPrefixes), "", `_Key:_ \`${rawKey}\``];
+  const trimmedKey = rawKey.trim();
+  const derived = input.leaf.model ? findDerivedCompositeKeys(trimmedKey, input.leaf.model) : [];
+  const compositeSource = decodeCompositeSource(input.leaf);
+  const lines = ["_Model decoded from key prefix._", "", ...formatLeaf(input.leaf), ...formatAncestors(input.ancestors), ...formatUnresolved(input.unresolvedPrefixes), ...formatCompositeSource(compositeSource), ...formatDerivedKeys(derived), "", `_Key:_ \`${rawKey}\``];
   return lines.join("\n");
 }
 function runModelDecode(rawArgs) {

package/generated/dereekb-util-fetch.utils.mcp.generated.json

@@ -0,0 +1,221 @@
+{
+  "version": 1,
+  "source": "@dereekb/util/fetch",
+  "module": "@dereekb/util/fetch",
+  "generatedAt": "1970-01-01T00:00:00.000Z",
+  "generator": "@dereekb/dbx-components-mcp/scripts/generate-manifests.mjs",
+  "entries": [
+    {
+      "slug": "to-bracket-notation-search-param-tuples",
+      "name": "toBracketNotationSearchParamTuples",
+      "kind": "function",
+      "category": "url",
+      "module": "@dereekb/util/fetch",
+      "subpath": "fetch.url",
+      "signature": "toBracketNotationSearchParamTuples(input: Maybe<object>): UrlSearchParamsKeyValueTuple[]",
+      "description": "Expands a potentially nested object into bracket-notation query key/value tuples.\n\nArrays are addressed by index and object properties by key, recursively, so every leaf\ngets its own fully-qualified parameter. Nullish leaves are omitted rather than emitted\nas the strings `\"null\"`/`\"undefined\"`; all other leaves are stringified.",
+      "params": [
+        {
+          "name": "input",
+          "type": "Maybe<object>",
+          "description": "- The object to expand.",
+          "optional": false
+        }
+      ],
+      "returns": "The bracket-notation key/value tuples.",
+      "tags": [
+        "url",
+        "query",
+        "search",
+        "params",
+        "bracket",
+        "notation",
+        "nested",
+        "expand",
+        "tuples",
+        "encode",
+        "to",
+        "param",
+        "tobracketnotationsearchparamtuples"
+      ],
+      "example": "toBracketNotationSearchParamTuples({ calendarsToLoad: [{ credentialId: 1, externalId: 'a@b.com' }] });\n// => [['calendarsToLoad[0][credentialId]', '1'], ['calendarsToLoad[0][externalId]', 'a@b.com']]",
+      "relatedSlugs": [
+        "make-url-search-params",
+        "make-url-search-params-string"
+      ]
+    },
+    {
+      "slug": "make-url-search-params",
+      "name": "makeUrlSearchParams",
+      "kind": "function",
+      "category": "url",
+      "module": "@dereekb/util/fetch",
+      "subpath": "fetch.url",
+      "signature": "makeUrlSearchParams(input: Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>, options?: Maybe<MakeUrlSearchParamsOptions>): URLSearchParams",
+      "description": "Creates URLSearchParams from the input objects. The input objects are merged together.",
+      "params": [
+        {
+          "name": "input",
+          "type": "Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>",
+          "description": "- One or more objects (or nullish values) whose key-value pairs become search parameters.",
+          "optional": false
+        },
+        {
+          "name": "options",
+          "type": "Maybe<MakeUrlSearchParamsOptions>",
+          "description": "- Optional configuration for filtering, omitting keys, and space encoding.",
+          "optional": true
+        }
+      ],
+      "returns": "A URLSearchParams instance built from the merged and filtered input.",
+      "tags": [
+        "url",
+        "query",
+        "search",
+        "params",
+        "urlsearchparams",
+        "encode",
+        "merge",
+        "filter",
+        "omit",
+        "querystring",
+        "make",
+        "makeurlsearchparams"
+      ],
+      "relatedSlugs": [
+        "make-url-search-params-string",
+        "update-url-search-params",
+        "to-bracket-notation-search-param-tuples",
+        "merge-make-url-search-params-options"
+      ]
+    },
+    {
+      "slug": "make-url-search-params-string",
+      "name": "makeUrlSearchParamsString",
+      "kind": "function",
+      "category": "url",
+      "module": "@dereekb/util/fetch",
+      "subpath": "fetch.url",
+      "signature": "makeUrlSearchParamsString(input: Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>, options?: Maybe<MakeUrlSearchParamsOptions>): string",
+      "description": "Creates a URL query string from the input objects.\n\nEquivalent to `makeUrlSearchParams(...).toString()`, but respects the\n{@link MakeUrlSearchParamsOptions.useUrlSearchSpaceHandling} option to produce\nRFC 3986 percent-encoded output (`%20` for spaces) instead of the\n`application/x-www-form-urlencoded` default (`+` for spaces).",
+      "params": [
+        {
+          "name": "input",
+          "type": "Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>",
+          "description": "- Objects to encode as query parameters.",
+          "optional": false
+        },
+        {
+          "name": "options",
+          "type": "Maybe<MakeUrlSearchParamsOptions>",
+          "description": "- Encoding options.",
+          "optional": true
+        }
+      ],
+      "returns": "The encoded query string (without a leading `?`)",
+      "tags": [
+        "url",
+        "query",
+        "search",
+        "params",
+        "string",
+        "querystring",
+        "encode",
+        "percent",
+        "space",
+        "stringify",
+        "make",
+        "makeurlsearchparamsstring"
+      ],
+      "relatedSlugs": [
+        "make-url-search-params",
+        "update-url-search-params"
+      ]
+    },
+    {
+      "slug": "update-url-search-params",
+      "name": "updateUrlSearchParams",
+      "kind": "function",
+      "category": "url",
+      "module": "@dereekb/util/fetch",
+      "subpath": "fetch.url",
+      "signature": "updateUrlSearchParams(url: string, params: Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>, options?: Maybe<MakeUrlSearchParamsOptions>): string",
+      "description": "Updates or adds query parameters on an existing URL string.\n\nParses the URL's existing query string, merges in the new parameters (new values\noverride existing keys), and returns the rebuilt URL. Respects all\n{@link MakeUrlSearchParamsOptions} such as `omitKeys`, `filterEmptyValues`, and\n`useUrlSearchSpaceHandling`.",
+      "params": [
+        {
+          "name": "url",
+          "type": "string",
+          "description": "- The URL string to update.",
+          "optional": false
+        },
+        {
+          "name": "params",
+          "type": "Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>",
+          "description": "- New search parameters to merge into the URL.",
+          "optional": false
+        },
+        {
+          "name": "options",
+          "type": "Maybe<MakeUrlSearchParamsOptions>",
+          "description": "- Optional configuration for filtering, omitting keys, and space encoding.",
+          "optional": true
+        }
+      ],
+      "returns": "The URL string with updated query parameters.",
+      "tags": [
+        "url",
+        "query",
+        "search",
+        "params",
+        "update",
+        "merge",
+        "append",
+        "override",
+        "querystring",
+        "encode",
+        "updateurlsearchparams"
+      ],
+      "example": "// Add params to a URL with no query string\nupdateUrlSearchParams('https://example.com/form', { name: 'Alice', age: 30 });\n// => 'https://example.com/form?name=Alice&age=30'\n\n// Override an existing param\nupdateUrlSearchParams('https://example.com?page=1&sort=asc', { page: 2 });\n// => 'https://example.com?page=2&sort=asc'\n\n// Use percent-encoded spaces for redirect URLs\nupdateUrlSearchParams('https://example.com', { scope: 'openid profile' }, { useUrlSearchSpaceHandling: true });\n// => 'https://example.com?scope=openid%20profile'",
+      "relatedSlugs": [
+        "make-url-search-params",
+        "make-url-search-params-string",
+        "merge-slash-paths"
+      ]
+    },
+    {
+      "slug": "merge-make-url-search-params-options",
+      "name": "mergeMakeUrlSearchParamsOptions",
+      "kind": "function",
+      "category": "url",
+      "module": "@dereekb/util/fetch",
+      "subpath": "fetch.url",
+      "signature": "mergeMakeUrlSearchParamsOptions(options: ArrayOrValue<Maybe<MakeUrlSearchParamsOptions>>): MakeUrlSearchParamsOptions",
+      "description": "Merges an array of MakeUrlSearchParamsOptions into a single MakeUrlSearchParamsOptions value.",
+      "params": [
+        {
+          "name": "options",
+          "type": "ArrayOrValue<Maybe<MakeUrlSearchParamsOptions>>",
+          "description": "- One or more options objects whose omitKeys sets are combined.",
+          "optional": false
+        }
+      ],
+      "returns": "A single MakeUrlSearchParamsOptions with the union of all omitKeys.",
+      "tags": [
+        "url",
+        "query",
+        "search",
+        "params",
+        "options",
+        "merge",
+        "omit",
+        "keys",
+        "config",
+        "make",
+        "mergemakeurlsearchparamsoptions"
+      ],
+      "relatedSlugs": [
+        "make-url-search-params"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-components-mcp",
-  "version": "14.5.1",
+  "version": "14.7.0",
   "sideEffects": false,
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
     "ts-morph": "^21.0.0"
   },
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.5.1",
-    "@dereekb/util": "14.5.1"
+    "@dereekb/dbx-cli": "14.7.0",
+    "@dereekb/util": "14.7.0"
   }
 }