@dereekb/dbx-cli 13.18.0 → 13.20.0

package/eslint/index.cjs.js

@@ -669,6 +669,13 @@ var LINE_PREFIX_REGEX = /^(\s*\*?\s?)(.*)$/;
  *   promoted to `<collectionName>/<id>` at runtime via the model identity).
  * - `gb/:id/gbe/{authUid}` — alternating literal / placeholder segments (even
  *   count) → `kind: 'key'` (a full FirestoreModelKey for a subcollection model).
+ *   An odd (id) segment may also be a `{const:<id>}` token for a fixed/singleton
+ *   id (e.g. `wk/:uid/wkn/{const:0}`); it is normalized to the bare literal in
+ *   the parsed `keyTemplate` so the runtime emits it verbatim, while a forgotten
+ *   `:` (a bare `note`) still fails as malformed.
+ * - `{flatKey:<param>}` — single token → `kind: 'flatKey'`: the `<param>` URL
+ *   value IS a whole two-way-flat FirestoreModelKey (`r_<id>_cs_<id>_d_<id>`),
+ *   un-flattened at runtime. For pages that pack a full key into one URL segment.
  * - (absent, list tag) → `kind: 'list'`.
  *
  * This module is deliberately runtime-dependency-free (no ts-morph): the same
@@ -677,8 +684,8 @@ var LINE_PREFIX_REGEX = /^(\s*\*?\s?)(.*)$/;
  * valid tag is. The ts-morph consumer (`extractComponentRouteModelTags`) lives in
  * `./route-models-extract.ts` and re-exports these symbols for existing importers.
  */ /**
- * Whether a route-model entry resolves to a promoted id, a full key, or a
- * keyless list.
+ * Whether a route-model entry resolves to a promoted id, a full key, a
+ * single-param flattened key, or a keyless list.
  */ function _array_like_to_array(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
@@ -728,6 +735,14 @@ function _unsupported_iterable_to_array(o, minLen) {
 var MODEL_TYPE_RE = RegExp("^[a-zA-Z][a-zA-Z0-9]*$", "u");
 var LITERAL_SEGMENT_RE = RegExp("^[a-zA-Z0-9][a-zA-Z0-9_-]*$", "u");
 var AUTH_UID_PLACEHOLDER = '{authUid}';
+/**
+ * Matches a `{const:<id>}` fixed-id token (e.g. `{const:0}`), capturing the
+ * literal id. The id obeys the same shape as a literal collection segment.
+ */ var CONST_TOKEN_RE = RegExp("^\\{const:([a-zA-Z0-9][a-zA-Z0-9_-]*)\\}$", "u");
+/**
+ * Matches a `{flatKey:<param>}` token (e.g. `{flatKey:region}`), capturing the
+ * route param name whose URL value holds a whole two-way-flat FirestoreModelKey.
+ */ var FLAT_KEY_TOKEN_RE = RegExp("^\\{flatKey:([a-zA-Z_][a-zA-Z0-9_]*)\\}$", "u");
 /**
  * The bare `@dbxRouteModel` tag name (without the leading `@`).
  */ var ROUTE_MODEL_TAG = 'dbxRouteModel';
@@ -807,7 +822,7 @@ function parseModelTag(tokens, description) {
                 model: {
                     modelType: tokens[0],
                     kind: parsedKey.kind,
-                    keyTemplate: tokens[1],
+                    keyTemplate: parsedKey.keyTemplate,
                     description: description,
                     routeParams: parsedKey.routeParams
                 }
@@ -842,17 +857,29 @@ function parseKeyTemplate(keyTemplate) {
     return result;
 }
 function parseSingleSegmentKey(segment, keyTemplate) {
+    var flatKeyParam = flatKeyTokenParam(segment);
     var placeholder = placeholderParam(segment);
     var result;
-    if (placeholder === undefined) {
+    if (flatKeyParam !== undefined) {
+        // The whole key lives in one URL param; the runtime un-flattens it.
+        result = {
+            ok: true,
+            kind: 'flatKey',
+            keyTemplate: keyTemplate,
+            routeParams: [
+                flatKeyParam
+            ]
+        };
+    } else if (placeholder === undefined) {
         result = {
             ok: false,
-            message: "Single-segment key template `".concat(keyTemplate, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`).")
+            message: "Single-segment key template `".concat(keyTemplate, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`) or a flattened-key token (`{flatKey:<param>}`).")
         };
     } else {
         result = {
             ok: true,
             kind: 'id',
+            keyTemplate: keyTemplate,
             routeParams: placeholder.routeParam === undefined ? [] : [
                 placeholder.routeParam
             ]
@@ -862,6 +889,10 @@ function parseSingleSegmentKey(segment, keyTemplate) {
 }
 function parseAlternatingKey(segments, keyTemplate) {
     var routeParams = [];
+    // The normalized template substitutes any `{const:<id>}` token back to its
+    // bare literal so the runtime `resolveFullKey` (which emits non-placeholder
+    // segments verbatim) round-trips without needing to understand the token.
+    var normalizedSegments = [];
     var message;
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
@@ -872,14 +903,20 @@ function parseAlternatingKey(segments, keyTemplate) {
                     message = "Key template `".concat(keyTemplate, "` segment `").concat(segment, "` must be a literal collection name.");
                     break;
                 }
+                normalizedSegments.push(segment);
             } else {
                 var placeholder = placeholderParam(segment);
-                if (placeholder === undefined) {
-                    message = "Key template `".concat(keyTemplate, "` segment `").concat(segment, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`).");
+                var constId = constTokenId(segment);
+                if (placeholder !== undefined) {
+                    if (placeholder.routeParam !== undefined) {
+                        routeParams.push(placeholder.routeParam);
+                    }
+                    normalizedSegments.push(segment);
+                } else if (constId === undefined) {
+                    message = "Key template `".concat(keyTemplate, "` segment `").concat(segment, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`) or a fixed id (`{const:<id>}`).");
                     break;
-                }
-                if (placeholder.routeParam !== undefined) {
-                    routeParams.push(placeholder.routeParam);
+                } else {
+                    normalizedSegments.push(constId);
                 }
             }
         }
@@ -900,6 +937,7 @@ function parseAlternatingKey(segments, keyTemplate) {
     return message === undefined ? {
         ok: true,
         kind: 'key',
+        keyTemplate: normalizedSegments.join('/'),
         routeParams: routeParams
     } : {
         ok: false,
@@ -929,6 +967,28 @@ function parseAlternatingKey(segments, keyTemplate) {
     }
     return result;
 }
+/**
+ * Extracts the literal id from a `{const:<id>}` fixed-id token, used for a
+ * fixed/singleton subcollection id at an odd key-template position. Returns
+ * `undefined` for any non-`{const:…}` segment.
+ *
+ * @param segment - The single key-template segment to classify.
+ * @returns The captured literal id, or `undefined` when not a const token.
+ */ function constTokenId(segment) {
+    var match = CONST_TOKEN_RE.exec(segment);
+    return match === null ? undefined : match[1];
+}
+/**
+ * Extracts the route param name from a `{flatKey:<param>}` token, whose URL
+ * value is a whole two-way-flat FirestoreModelKey un-flattened at runtime.
+ * Returns `undefined` for any non-`{flatKey:…}` segment.
+ *
+ * @param segment - The single key-template segment to classify.
+ * @returns The captured route param name, or `undefined` when not a flatKey token.
+ */ function flatKeyTokenParam(segment) {
+    var match = FLAT_KEY_TOKEN_RE.exec(segment);
+    return match === null ? undefined : match[1];
+}
 
 /**
  * ESLint rule enforcing that `@dbxRouteModel` / `@dbxRouteModelList` tags parse

package/eslint/index.esm.js

@@ -667,6 +667,13 @@ var LINE_PREFIX_REGEX = /^(\s*\*?\s?)(.*)$/;
  *   promoted to `<collectionName>/<id>` at runtime via the model identity).
  * - `gb/:id/gbe/{authUid}` — alternating literal / placeholder segments (even
  *   count) → `kind: 'key'` (a full FirestoreModelKey for a subcollection model).
+ *   An odd (id) segment may also be a `{const:<id>}` token for a fixed/singleton
+ *   id (e.g. `wk/:uid/wkn/{const:0}`); it is normalized to the bare literal in
+ *   the parsed `keyTemplate` so the runtime emits it verbatim, while a forgotten
+ *   `:` (a bare `note`) still fails as malformed.
+ * - `{flatKey:<param>}` — single token → `kind: 'flatKey'`: the `<param>` URL
+ *   value IS a whole two-way-flat FirestoreModelKey (`r_<id>_cs_<id>_d_<id>`),
+ *   un-flattened at runtime. For pages that pack a full key into one URL segment.
  * - (absent, list tag) → `kind: 'list'`.
  *
  * This module is deliberately runtime-dependency-free (no ts-morph): the same
@@ -675,8 +682,8 @@ var LINE_PREFIX_REGEX = /^(\s*\*?\s?)(.*)$/;
  * valid tag is. The ts-morph consumer (`extractComponentRouteModelTags`) lives in
  * `./route-models-extract.ts` and re-exports these symbols for existing importers.
  */ /**
- * Whether a route-model entry resolves to a promoted id, a full key, or a
- * keyless list.
+ * Whether a route-model entry resolves to a promoted id, a full key, a
+ * single-param flattened key, or a keyless list.
  */ function _array_like_to_array(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
@@ -726,6 +733,14 @@ function _unsupported_iterable_to_array(o, minLen) {
 var MODEL_TYPE_RE = RegExp("^[a-zA-Z][a-zA-Z0-9]*$", "u");
 var LITERAL_SEGMENT_RE = RegExp("^[a-zA-Z0-9][a-zA-Z0-9_-]*$", "u");
 var AUTH_UID_PLACEHOLDER = '{authUid}';
+/**
+ * Matches a `{const:<id>}` fixed-id token (e.g. `{const:0}`), capturing the
+ * literal id. The id obeys the same shape as a literal collection segment.
+ */ var CONST_TOKEN_RE = RegExp("^\\{const:([a-zA-Z0-9][a-zA-Z0-9_-]*)\\}$", "u");
+/**
+ * Matches a `{flatKey:<param>}` token (e.g. `{flatKey:region}`), capturing the
+ * route param name whose URL value holds a whole two-way-flat FirestoreModelKey.
+ */ var FLAT_KEY_TOKEN_RE = RegExp("^\\{flatKey:([a-zA-Z_][a-zA-Z0-9_]*)\\}$", "u");
 /**
  * The bare `@dbxRouteModel` tag name (without the leading `@`).
  */ var ROUTE_MODEL_TAG = 'dbxRouteModel';
@@ -805,7 +820,7 @@ function parseModelTag(tokens, description) {
                 model: {
                     modelType: tokens[0],
                     kind: parsedKey.kind,
-                    keyTemplate: tokens[1],
+                    keyTemplate: parsedKey.keyTemplate,
                     description: description,
                     routeParams: parsedKey.routeParams
                 }
@@ -840,17 +855,29 @@ function parseKeyTemplate(keyTemplate) {
     return result;
 }
 function parseSingleSegmentKey(segment, keyTemplate) {
+    var flatKeyParam = flatKeyTokenParam(segment);
     var placeholder = placeholderParam(segment);
     var result;
-    if (placeholder === undefined) {
+    if (flatKeyParam !== undefined) {
+        // The whole key lives in one URL param; the runtime un-flattens it.
+        result = {
+            ok: true,
+            kind: 'flatKey',
+            keyTemplate: keyTemplate,
+            routeParams: [
+                flatKeyParam
+            ]
+        };
+    } else if (placeholder === undefined) {
         result = {
             ok: false,
-            message: "Single-segment key template `".concat(keyTemplate, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`).")
+            message: "Single-segment key template `".concat(keyTemplate, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`) or a flattened-key token (`{flatKey:<param>}`).")
         };
     } else {
         result = {
             ok: true,
             kind: 'id',
+            keyTemplate: keyTemplate,
             routeParams: placeholder.routeParam === undefined ? [] : [
                 placeholder.routeParam
             ]
@@ -860,6 +887,10 @@ function parseSingleSegmentKey(segment, keyTemplate) {
 }
 function parseAlternatingKey(segments, keyTemplate) {
     var routeParams = [];
+    // The normalized template substitutes any `{const:<id>}` token back to its
+    // bare literal so the runtime `resolveFullKey` (which emits non-placeholder
+    // segments verbatim) round-trips without needing to understand the token.
+    var normalizedSegments = [];
     var message;
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
@@ -870,14 +901,20 @@ function parseAlternatingKey(segments, keyTemplate) {
                     message = "Key template `".concat(keyTemplate, "` segment `").concat(segment, "` must be a literal collection name.");
                     break;
                 }
+                normalizedSegments.push(segment);
             } else {
                 var placeholder = placeholderParam(segment);
-                if (placeholder === undefined) {
-                    message = "Key template `".concat(keyTemplate, "` segment `").concat(segment, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`).");
+                var constId = constTokenId(segment);
+                if (placeholder !== undefined) {
+                    if (placeholder.routeParam !== undefined) {
+                        routeParams.push(placeholder.routeParam);
+                    }
+                    normalizedSegments.push(segment);
+                } else if (constId === undefined) {
+                    message = "Key template `".concat(keyTemplate, "` segment `").concat(segment, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`) or a fixed id (`{const:<id>}`).");
                     break;
-                }
-                if (placeholder.routeParam !== undefined) {
-                    routeParams.push(placeholder.routeParam);
+                } else {
+                    normalizedSegments.push(constId);
                 }
             }
         }
@@ -898,6 +935,7 @@ function parseAlternatingKey(segments, keyTemplate) {
     return message === undefined ? {
         ok: true,
         kind: 'key',
+        keyTemplate: normalizedSegments.join('/'),
         routeParams: routeParams
     } : {
         ok: false,
@@ -927,6 +965,28 @@ function parseAlternatingKey(segments, keyTemplate) {
     }
     return result;
 }
+/**
+ * Extracts the literal id from a `{const:<id>}` fixed-id token, used for a
+ * fixed/singleton subcollection id at an odd key-template position. Returns
+ * `undefined` for any non-`{const:…}` segment.
+ *
+ * @param segment - The single key-template segment to classify.
+ * @returns The captured literal id, or `undefined` when not a const token.
+ */ function constTokenId(segment) {
+    var match = CONST_TOKEN_RE.exec(segment);
+    return match === null ? undefined : match[1];
+}
+/**
+ * Extracts the route param name from a `{flatKey:<param>}` token, whose URL
+ * value is a whole two-way-flat FirestoreModelKey un-flattened at runtime.
+ * Returns `undefined` for any non-`{flatKey:…}` segment.
+ *
+ * @param segment - The single key-template segment to classify.
+ * @returns The captured route param name, or `undefined` when not a flatKey token.
+ */ function flatKeyTokenParam(segment) {
+    var match = FLAT_KEY_TOKEN_RE.exec(segment);
+    return match === null ? undefined : match[1];
+}
 
 /**
  * ESLint rule enforcing that `@dbxRouteModel` / `@dbxRouteModelList` tags parse

package/eslint/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@dereekb/dbx-cli/eslint",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.18.0",
-    "@dereekb/util": "13.18.0",
+    "@dereekb/dbx-cli": "13.20.0",
+    "@dereekb/util": "13.20.0",
     "@typescript-eslint/utils": "8.59.3"
   },
   "devDependencies": {

package/firebase-api-manifest/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/dbx-cli-firebase-api-manifest",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "private": true,
   "type": "module",
   "devDependencies": {
     "ts-morph": "^21.0.0"
   },
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.18.0",
-    "@dereekb/util": "13.18.0",
+    "@dereekb/dbx-cli": "13.20.0",
+    "@dereekb/util": "13.20.0",
     "prettier": "3.8.3"
   }
 }

package/generate-firestore-indexes/main.js

@@ -5,14 +5,14 @@ const require = __createRequire(import.meta.url);
 // packages/dbx-cli/generate-firestore-indexes/package.json
 var package_default = {
   name: "@dereekb/dbx-cli-generate-firestore-indexes",
-  version: "13.18.0",
+  version: "13.20.0",
   private: true,
   type: "module",
   devDependencies: {
     eslint: "10.4.0"
   },
   peerDependencies: {
-    "@dereekb/dbx-cli": "13.18.0"
+    "@dereekb/dbx-cli": "13.20.0"
   }
 };
 

package/generate-firestore-indexes/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/dbx-cli-generate-firestore-indexes",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "private": true,
   "type": "module",
   "devDependencies": {
     "eslint": "10.4.0"
   },
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.18.0"
+    "@dereekb/dbx-cli": "13.20.0"
   }
 }

package/generate-mcp-manifest/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/dbx-cli-generate-mcp-manifest",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "private": true,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.18.0",
-    "@dereekb/model": "13.18.0",
+    "@dereekb/dbx-cli": "13.20.0",
+    "@dereekb/model": "13.20.0",
     "arktype": "^2.2.0",
     "jiti": "2.6.1"
   }

package/generate-route-manifest/main.js

@@ -334,6 +334,42 @@ function collectRelativeImports(sourceFile, fileName) {
   return out;
 }
 
+// packages/dbx-cli/src/lib/route/url-match.ts
+function stripUrlQueryAndHash(url) {
+  const hashStripped = url.split("#", 1)[0];
+  return hashStripped.split("?", 1)[0];
+}
+function extractUrlParamKeys(fullUrl) {
+  if (fullUrl === void 0 || fullUrl.length === 0) {
+    return [];
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const keys = [];
+  for (const segment of fullUrl.split("/")) {
+    const key = extractParamKeyFromSegment(segment);
+    if (key !== void 0 && !seen.has(key)) {
+      seen.add(key);
+      keys.push(key);
+    }
+  }
+  return keys;
+}
+function extractParamKeyFromSegment(rawSegment) {
+  const segment = stripUrlQueryAndHash(rawSegment);
+  if (segment.startsWith(":")) {
+    const key = segment.slice(1);
+    return key.length > 0 ? key : void 0;
+  }
+  if (segment.startsWith("{") && segment.endsWith("}")) {
+    const inner = segment.slice(1, -1);
+    const colonIdx = inner.indexOf(":");
+    const rawKey = colonIdx >= 0 ? inner.slice(0, colonIdx) : inner;
+    const key = rawKey.trim();
+    return key.length > 0 ? key : void 0;
+  }
+  return void 0;
+}
+
 // packages/dbx-cli/src/lib/route/route-build-tree.ts
 // @__NO_SIDE_EFFECTS__
 function buildRouteTree(nodes, extractIssues) {
@@ -493,7 +529,7 @@ function composeFullUrl(node) {
     return void 0;
   }
   const joined = segments.join("");
-  const collapsed = joined.replaceAll(/\/{2,}/g, "/");
+  const collapsed = stripUrlQueryAndHash(joined).replaceAll(/\/{2,}/g, "/");
   return collapsed.length === 0 ? "/" : collapsed;
 }
 function compareByName(a, b) {
@@ -541,37 +577,6 @@ function loadRouteTree(args) {
   return result;
 }
 
-// packages/dbx-cli/src/lib/route/url-match.ts
-function extractUrlParamKeys(fullUrl) {
-  if (fullUrl === void 0 || fullUrl.length === 0) {
-    return [];
-  }
-  const seen = /* @__PURE__ */ new Set();
-  const keys = [];
-  for (const segment of fullUrl.split("/")) {
-    const key = extractParamKeyFromSegment(segment);
-    if (key !== void 0 && !seen.has(key)) {
-      seen.add(key);
-      keys.push(key);
-    }
-  }
-  return keys;
-}
-function extractParamKeyFromSegment(segment) {
-  if (segment.startsWith(":")) {
-    const key = segment.slice(1);
-    return key.length > 0 ? key : void 0;
-  }
-  if (segment.startsWith("{") && segment.endsWith("}")) {
-    const inner = segment.slice(1, -1);
-    const colonIdx = inner.indexOf(":");
-    const rawKey = colonIdx >= 0 ? inner.slice(0, colonIdx) : inner;
-    const key = rawKey.trim();
-    return key.length > 0 ? key : void 0;
-  }
-  return void 0;
-}
-
 // packages/dbx-cli/src/lib/route/component-resolve.ts
 import { dirname, join, normalize } from "node:path/posix";
 var TRY_EXTENSIONS = [".ts", ".tsx", "/index.ts", "/index.tsx"];
@@ -646,6 +651,8 @@ function containsImportedSymbol(importStatement, symbol) {
 var MODEL_TYPE_RE = /^[a-zA-Z][a-zA-Z0-9]*$/u;
 var LITERAL_SEGMENT_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/u;
 var AUTH_UID_PLACEHOLDER = "{authUid}";
+var CONST_TOKEN_RE = /^\{const:([a-zA-Z0-9][a-zA-Z0-9_-]*)\}$/u;
+var FLAT_KEY_TOKEN_RE = /^\{flatKey:([a-zA-Z_][a-zA-Z0-9_]*)\}$/u;
 var ROUTE_MODEL_TAG = "dbxRouteModel";
 var ROUTE_MODEL_LIST_TAG = "dbxRouteModelList";
 function parseRouteModelTag(tag) {
@@ -681,7 +688,7 @@ function parseModelTag(tokens, description) {
   } else if (MODEL_TYPE_RE.test(tokens[0])) {
     const parsedKey = parseKeyTemplate(tokens[1]);
     if (parsedKey.ok) {
-      result = { ok: true, model: { modelType: tokens[0], kind: parsedKey.kind, keyTemplate: tokens[1], description, routeParams: parsedKey.routeParams } };
+      result = { ok: true, model: { modelType: tokens[0], kind: parsedKey.kind, keyTemplate: parsedKey.keyTemplate, description, routeParams: parsedKey.routeParams } };
     } else {
       result = { ok: false, message: parsedKey.message };
     }
@@ -703,17 +710,21 @@ function parseKeyTemplate(keyTemplate) {
   return result;
 }
 function parseSingleSegmentKey(segment, keyTemplate) {
+  const flatKeyParam = flatKeyTokenParam(segment);
   const placeholder = placeholderParam(segment);
   let result;
-  if (placeholder === void 0) {
-    result = { ok: false, message: `Single-segment key template \`${keyTemplate}\` must be a placeholder (\`:param\` or \`${AUTH_UID_PLACEHOLDER}\`).` };
+  if (flatKeyParam !== void 0) {
+    result = { ok: true, kind: "flatKey", keyTemplate, routeParams: [flatKeyParam] };
+  } else if (placeholder === void 0) {
+    result = { ok: false, message: `Single-segment key template \`${keyTemplate}\` must be a placeholder (\`:param\` or \`${AUTH_UID_PLACEHOLDER}\`) or a flattened-key token (\`{flatKey:<param>}\`).` };
   } else {
-    result = { ok: true, kind: "id", routeParams: placeholder.routeParam === void 0 ? [] : [placeholder.routeParam] };
+    result = { ok: true, kind: "id", keyTemplate, routeParams: placeholder.routeParam === void 0 ? [] : [placeholder.routeParam] };
   }
   return result;
 }
 function parseAlternatingKey(segments, keyTemplate) {
   const routeParams = [];
+  const normalizedSegments = [];
   let message;
   for (const [i, segment] of segments.entries()) {
     if (i % 2 === 0) {
@@ -721,18 +732,24 @@ function parseAlternatingKey(segments, keyTemplate) {
         message = `Key template \`${keyTemplate}\` segment \`${segment}\` must be a literal collection name.`;
         break;
       }
+      normalizedSegments.push(segment);
     } else {
       const placeholder = placeholderParam(segment);
-      if (placeholder === void 0) {
-        message = `Key template \`${keyTemplate}\` segment \`${segment}\` must be a placeholder (\`:param\` or \`${AUTH_UID_PLACEHOLDER}\`).`;
+      const constId = constTokenId(segment);
+      if (placeholder !== void 0) {
+        if (placeholder.routeParam !== void 0) {
+          routeParams.push(placeholder.routeParam);
+        }
+        normalizedSegments.push(segment);
+      } else if (constId === void 0) {
+        message = `Key template \`${keyTemplate}\` segment \`${segment}\` must be a placeholder (\`:param\` or \`${AUTH_UID_PLACEHOLDER}\`) or a fixed id (\`{const:<id>}\`).`;
         break;
-      }
-      if (placeholder.routeParam !== void 0) {
-        routeParams.push(placeholder.routeParam);
+      } else {
+        normalizedSegments.push(constId);
       }
     }
   }
-  return message === void 0 ? { ok: true, kind: "key", routeParams } : { ok: false, message };
+  return message === void 0 ? { ok: true, kind: "key", keyTemplate: normalizedSegments.join("/"), routeParams } : { ok: false, message };
 }
 function placeholderParam(segment) {
   let result;
@@ -745,6 +762,14 @@ function placeholderParam(segment) {
   }
   return result;
 }
+function constTokenId(segment) {
+  const match = CONST_TOKEN_RE.exec(segment);
+  return match === null ? void 0 : match[1];
+}
+function flatKeyTokenParam(segment) {
+  const match = FLAT_KEY_TOKEN_RE.exec(segment);
+  return match === null ? void 0 : match[1];
+}
 
 // packages/dbx-cli/src/lib/route/route-models-extract.ts
 function extractComponentRouteModelTags(sourceFile, component) {
@@ -766,7 +791,7 @@ function collectRouteModelTags2(jsDocs) {
 
 // packages/dbx-cli/src/lib/route/route-manifest.ts
 import { Project as Project2 } from "ts-morph";
-var ROUTE_MANIFEST_VERSION = 1;
+var ROUTE_MANIFEST_VERSION = 2;
 function buildRouteManifest(input, now = /* @__PURE__ */ new Date()) {
   const warnings = [];
   const tree = loadRouteTree({ sources: input.sources });
@@ -990,7 +1015,12 @@ function formatRouteManifestWarning(warning) {
   return `[generate-route-manifest] ${warning.severity}: ${warning.kind}: ${warning.message}`;
 }
 function countRouteManifestGenerationErrors(input) {
-  return input.warnings.filter((warning) => warning.severity === "error" || input.strict && warning.severity === "warning").length;
+  const allow = new Set(input.allowWarning ?? []);
+  const errorCount = input.warnings.filter((warning) => warning.severity === "error").length;
+  const blockableWarnings = input.warnings.filter((warning) => warning.severity === "warning" && !allow.has(warning.kind));
+  const exceedsMax = input.maxWarnings !== void 0 && blockableWarnings.length > input.maxWarnings;
+  const blockingWarningCount = input.strict || exceedsMax ? blockableWarnings.length : 0;
+  return errorCount + blockingWarningCount;
 }
 function extractModelTypesFromModelsInput(parsed) {
   const models = parsed?.models;
@@ -1030,9 +1060,10 @@ async function main() {
     console.error(`generate-route-manifest: 0 states extracted from ${describePatterns(flags.src)}; not writing ${relative(WORKSPACE_ROOT, outputPath)}.`);
     process.exit(1);
   }
-  const errorCount = countRouteManifestGenerationErrors({ warnings, strict: flags.strict });
+  const errorCount = countRouteManifestGenerationErrors({ warnings, strict: flags.strict, allowWarning: flags.allowWarning, ...flags.maxWarnings == null ? {} : { maxWarnings: flags.maxWarnings } });
   if (errorCount > 0) {
-    console.error(`generate-route-manifest: ${errorCount} error-severity issue(s)${flags.strict ? " (--strict)" : ""}; not writing ${relative(WORKSPACE_ROOT, outputPath)}.`);
+    const gate = flags.strict ? " (--strict)" : flags.maxWarnings == null ? "" : ` (--max-warnings=${flags.maxWarnings})`;
+    console.error(`generate-route-manifest: ${errorCount} blocking issue(s)${gate}; not writing ${relative(WORKSPACE_ROOT, outputPath)}.`);
     process.exit(1);
   }
   const serialized = `${JSON.stringify(manifest, null, 2)}
@@ -1085,11 +1116,13 @@ function resolveWorkspacePath(value) {
 }
 function parseFlags(argv) {
   const src = [];
+  const allowWarning = [];
   let app;
   let baseUrl;
   let output;
   let modelsInput;
   let strict = false;
+  let maxWarnings;
   for (const arg of argv) {
     if (arg.startsWith("--src=")) {
       src.push(arg.slice("--src=".length));
@@ -1101,11 +1134,19 @@ function parseFlags(argv) {
       output = arg.slice("--output=".length);
     } else if (arg.startsWith("--models-input=")) {
       modelsInput = arg.slice("--models-input=".length);
+    } else if (arg.startsWith("--allow-warning=")) {
+      const kind = arg.slice("--allow-warning=".length).trim();
+      if (kind.length > 0) {
+        allowWarning.push(kind);
+      }
+    } else if (arg.startsWith("--max-warnings=")) {
+      const parsed = Number.parseInt(arg.slice("--max-warnings=".length), 10);
+      maxWarnings = Number.isNaN(parsed) ? void 0 : Math.max(0, parsed);
     } else if (arg === "--strict") {
       strict = true;
     }
   }
-  return { src, app, baseUrl, output, modelsInput, strict };
+  return { src, app, baseUrl, output, modelsInput, strict, allowWarning, maxWarnings };
 }
 function printUsageAndExit() {
   console.error(String.raw`generate-route-manifest
@@ -1126,7 +1167,12 @@ Optional:
   --models-input=<path>      MCP manifest JSON whose models[].modelType seed the
                              unknown-model-type validation.
   --strict                   Promote all warnings to errors for the exit decision
-                             (any finding then fails generation).`);
+                             (any finding then fails generation).
+  --allow-warning=<kind>     Tolerate a warning kind (repeatable); it never fails generation,
+                             even under --strict / --max-warnings. Kinds: unknown-route-param,
+                             unknown-model-type, duplicate-route-model, dropped-future-state,
+                             missing-route-model. (malformed-tag is an error and cannot be allowed.)
+  --max-warnings=<N>         Fail when non-allowlisted warnings exceed N (0 = fail on any new warning).`);
   process.exit(1);
 }
 try {

package/generate-route-manifest/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/dbx-cli-generate-route-manifest",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "private": true,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.18.0",
+    "@dereekb/dbx-cli": "13.20.0",
     "ts-morph": "^21.0.0"
   }
 }