@dereekb/dbx-cli 13.40.0 → 13.42.0

package/src/lib/firestore/query-mode.d.ts

@@ -0,0 +1,120 @@
+import { type Maybe } from '@dereekb/util';
+import { type CliFirestoreQueryManifestEntry, type CliFirestoreQueryMode, type CliFirestoreQueryRules, type CliFirestoreQueryRulesAccess, type CliFirestoreQueryScope } from '../manifest/types';
+/**
+ * Input for {@link cliFirestoreQueryModeForRules}.
+ *
+ * Takes the rules facts as PLAIN values rather than a `FirestoreRulesCollectionEntry`, so the rule
+ * lives in the shipped package while the scanner stays in the in-repo source-only
+ * `@dereekb/dbx-cli/firestore-rules`. The generator is the one place that owns both.
+ */
+export interface CliFirestoreQueryModeForRulesInput {
+    readonly scope: CliFirestoreQueryScope;
+    readonly isNested: boolean;
+    /**
+     * `FirestoreRulesCollectionEntry.collectionGroup` — whether a `/{path=**}/<collection>/{id}` block exists.
+     */
+    readonly collectionGroup: boolean;
+    /**
+     * `FirestoreRulesCollectionEntry.list` — the merged `list` posture for the collection.
+     */
+    readonly list: CliFirestoreQueryRulesAccess;
+    /**
+     * Parent-document path templates read off the collection's non-recursive rules match paths.
+     */
+    readonly parentPaths?: readonly string[];
+}
+/**
+ * The mode an entry resolves to, paired with the rules evidence behind it.
+ */
+export interface CliFirestoreQueryModeResult {
+    readonly mode: CliFirestoreQueryMode;
+    readonly rules: CliFirestoreQueryRules;
+}
+/**
+ * Resolves how a catalog entry must be invoked, from the rules facts about its collection.
+ *
+ * The rule, in the order it is applied:
+ *
+ * 1. `list` is not `allowed` — no block anywhere grants a list, so the entry is dead at EVERY
+ *    scope. Checked first because no amount of `--parent` scoping rescues it.
+ * 2. `scope: 'COLLECTION_GROUP'` with no `/{path=**}/<collection>/{id}` block — the group shape is
+ *    dead. A NESTED model degrades to `parent-child` (the path-scoped grant that satisfied step 1
+ *    is what `--parent` runs against); a root collection has no parent to scope to, so
+ *    `cliFirestoreCollectionForQuery` rejects `--parent` outright and the mode is `unavailable`.
+ * 3. `scope: 'COLLECTION'` over a subcollection — `--parent` is required by construction, whatever
+ *    the rules say, so the mode is `parent-child` rather than `model`. This step is why the mode is
+ *    NOT a pure permission verdict: the rules permit the read, and it still cannot be run
+ *    unscoped.
+ * 4. Otherwise `model`.
+ *
+ * `unavailable` is a deliberate UNDER-approximation. `list` is merged across every match block that
+ * reaches the collection, so a recursive block that denies `list` while a nested block allows it
+ * reads as `allowed` and the entry is not marked dead. That direction is the safe one — the scanner
+ * can never make this CLI refuse a query that actually works, only miss one that does not.
+ *
+ * @param input - The entry's scope/nesting and the rules facts for its collection.
+ * @returns The mode plus the evidence, with a reason attached whenever the mode is not `model`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliFirestoreQueryModeForRules(input: CliFirestoreQueryModeForRulesInput): CliFirestoreQueryModeResult;
+/**
+ * The mode an entry carries, normalized so an absent field reads as `unknown` rather than
+ * `undefined` — a consumer switching over {@link CliFirestoreQueryMode} stays total.
+ *
+ * @param entry - The catalog entry.
+ * @returns The entry's mode, or `unknown` when the manifest was generated without `--rules`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliFirestoreQueryMode(entry: CliFirestoreQueryManifestEntry): CliFirestoreQueryMode;
+/**
+ * True when this CLI could actually run the entry — the factory bound AND the rules do not refuse
+ * it outright. Backs `firestore-queries --invocable-only`.
+ *
+ * A `parent-child` entry counts as invocable: `--parent` runs it. An `unknown` one counts too;
+ * nothing is known against it.
+ *
+ * @param entry - The catalog entry.
+ * @returns Whether the entry is worth offering.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isCliFirestoreQueryInvocable(entry: CliFirestoreQueryManifestEntry): boolean;
+/**
+ * Error code used when a query is refused because `firestore.rules` can never authorize it.
+ */
+export declare const FIRESTORE_QUERY_UNAVAILABLE_CODE = "FIRESTORE_QUERY_UNAVAILABLE";
+/**
+ * Error code used when a `parent-child` query was run without a `--parent`.
+ */
+export declare const FIRESTORE_QUERY_PARENT_REQUIRED_CODE = "FIRESTORE_QUERY_PARENT_REQUIRED";
+/**
+ * Refuses a catalog entry that cannot run as invoked, BEFORE a transport is chosen.
+ *
+ * Mirrors `assertCliModelIsNotServerOnly`, one level finer: that flag is per-MODEL and cannot say
+ * "readable under its parent, dead as a collection group", which is exactly the shape this catches.
+ * Answering locally makes the reason legible and free instead of surfacing as a bare
+ * `Missing or insufficient permissions.` from the rules engine.
+ *
+ * An `unknown` entry passes: the manifest was generated without a `--rules` file, so nothing is
+ * known and a guess would be worse than a round trip.
+ *
+ * @param input - The catalog entry and the `--parent` key, when one was supplied.
+ * @param input.entry - The catalog entry about to run.
+ * @param input.parent - The `--parent` key, when supplied.
+ * @throws {CliError} `FIRESTORE_QUERY_UNAVAILABLE` when no client can run it, or `FIRESTORE_QUERY_PARENT_REQUIRED` when it needs a `--parent` that was not given.
+ */
+export declare function assertCliFirestoreQueryCanRun(input: {
+    readonly entry: CliFirestoreQueryManifestEntry;
+    readonly parent?: Maybe<string>;
+}): void;
+/**
+ * Renders the `Mode:` line of the `firestore-queries <query>` detail view.
+ *
+ * @param entry - The catalog entry.
+ * @returns The rendered line body, without a trailing newline.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function describeCliFirestoreQueryMode(entry: CliFirestoreQueryManifestEntry): string;

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

@@ -46,8 +46,9 @@ export interface CliModelField {
     readonly description?: string;
     /**
      * Enum name referenced by either the interface property's TS type or the
-     * converter's `firestoreEnum<Enum>()` generic argument, when an enum is
-     * present in the same source file.
+     * converter's `firestoreEnum<Enum>()` generic argument, resolved against
+     * every enum in the scan — the declaring file does not have to be the
+     * converter's own.
      */
     readonly enumRef?: string;
     /**
@@ -107,6 +108,38 @@ export interface CliModelManifestEntry {
      * Parent identity const name when the model is a subcollection.
      */
     readonly parentIdentityConst?: string;
+    /**
+     * `true` when the model's collection holds exactly one document — built by
+     * `singleItemFirestoreCollection` (one per parent) or
+     * `rootSingleItemFirestoreCollection` (one, full stop). Absent for ordinary
+     * multi-document collections.
+     */
+    readonly singleton?: boolean;
+    /**
+     * Fixed document id of a {@link singleton} model's one document: the value passed as
+     * `singleItemIdentifier`, or `'0'`
+     * (`DEFAULT_SINGLE_ITEM_FIRESTORE_COLLECTION_DOCUMENT_IDENTIFIER`) when the collection
+     * factory omits it.
+     *
+     * This cannot be inferred from the rest of the entry — plenty of single-item collections
+     * override the default (`bgbs`, `bgsu`, …) — so a caller building a document key must read
+     * it here rather than assume `/0`. Absent when {@link singleton} is `true` but the id was
+     * declared as an expression the generator could not resolve (a build-time warning is
+     * printed for that case).
+     */
+    readonly singleItemIdentifier?: string;
+    /**
+     * A ready-to-use example document key for this model, with the parent chain resolved from
+     * the identity graph and `<…Id>` placeholders standing in for the ids a caller supplies
+     * (e.g. `p/<profileId>`, `bg/<billingGroupId>/bgi/<billingGroupInvoiceId>`). A
+     * {@link singleton} model's own segment is its literal {@link singleItemIdentifier}, so the
+     * key is exact past the last placeholder (e.g. `bg/<billingGroupId>/bgis/bgbs`).
+     *
+     * Key *shape* — parent chain plus fixed document id — is what consumers of the manifest
+     * actually get wrong, so it is published pre-assembled. Absent only when some ancestor
+     * identity could not be resolved.
+     */
+    readonly exampleKey?: string;
     /**
      * First paragraph of the source interface's JSDoc, when present.
      */
@@ -327,6 +360,23 @@ export interface McpManifestModelEntry {
     readonly identityConst: string;
     readonly collectionPrefix: string;
     readonly parentIdentityConst?: string;
+    /**
+     * `true` when the model's collection holds exactly one document, at the fixed
+     * {@link singleItemIdentifier} (mirror of {@link CliModelManifestEntry.singleton}).
+     */
+    readonly singleton?: boolean;
+    /**
+     * Fixed document id of a {@link singleton} model's one document — `'0'` by default but
+     * frequently overridden, so it cannot be inferred (mirror of
+     * {@link CliModelManifestEntry.singleItemIdentifier}).
+     */
+    readonly singleItemIdentifier?: string;
+    /**
+     * Example document key with the parent chain resolved and `<…Id>` placeholders for the ids a
+     * caller supplies (mirror of {@link CliModelManifestEntry.exampleKey}). Surfaced by
+     * `model-info` so a `model-get` caller can build a valid key without reading source.
+     */
+    readonly exampleKey?: string;
     readonly description?: string;
     readonly sourcePackage: string;
     readonly sourceFile: string;
@@ -562,6 +612,100 @@ export interface CliFirestoreQueryParam {
  * single scalar, single params object, two positionals, ...).
  */
 export type CliFirestoreQueryFactory = (...args: readonly any[]) => readonly FirestoreQueryConstraint[];
+/**
+ * How the rules resolve one read operation on a collection, mirroring
+ * `FirestoreRulesAccess` from `@dereekb/dbx-cli/firestore-rules`.
+ *
+ * Restated here rather than imported: `firestore-rules` is an in-repo
+ * source-only package that cannot resolve to a built `.d.ts` during this
+ * package's declaration build, and the manifest is a SERIALIZED artifact — its
+ * types have to stand alone.
+ *
+ * - `allowed` — some `allow` covering the op has a condition that is not constant-`false`.
+ * - `denied` — the op is covered only by `allow`s whose condition is literally `false`.
+ * - `unmatched` — no `allow` covers the op at all, so Firestore's default-deny applies.
+ */
+export type CliFirestoreQueryRulesAccess = 'allowed' | 'denied' | 'unmatched';
+/**
+ * How a catalog entry must be INVOKED, resolved from `firestore.rules` at generation time.
+ *
+ * This classifies on the axis a caller acts on — "how do I run this?" — rather than on the raw
+ * rules verdict. The two are not the same question: a `COLLECTION`-scope entry over a
+ * subcollection is fully permitted by the rules and still cannot be run without `--parent`, so a
+ * pure permission verdict would call it runnable-as-declared and be wrong about how to run it.
+ *
+ * - `model` — run it directly against the model's collection or collection group.
+ * - `parent-child` — it addresses ONE parent document's subcollection, so `--parent <parentKey>`
+ *   is required. Either the entry is `COLLECTION`-scope over a subcollection, or its
+ *   `COLLECTION_GROUP` shape has no `/{path=**}/<collection>/{id}` block behind it while the
+ *   path-scoped read IS granted.
+ * - `unavailable` — no client can run it, on any transport or scoping.
+ * - `unknown` — the query manifest was generated without a `--rules` file, so nothing was
+ *   resolved. Never stored; it is what {@link CliFirestoreQueryManifestEntry.queryMode} being
+ *   absent means, so a consumer's switch over this union stays total.
+ */
+export type CliFirestoreQueryMode = 'model' | 'parent-child' | 'unavailable' | 'unknown';
+/**
+ * Why an entry resolved to the {@link CliFirestoreQueryMode} it did.
+ *
+ * `denied` and `unmatched` are kept apart the way the rules scanner keeps them apart: a
+ * written-down `if false` is a deliberate no, an absence is an oversight, and a reviewer needs to
+ * know which one they are looking at.
+ */
+export type CliFirestoreQueryModeReason = 
+/**
+ * `scope: 'COLLECTION_GROUP'` with no `/{path=**}/<collection>/{id}` block in the rules. A
+ * collection-group query is evaluated against that block alone — a path-scoped block does not
+ * authorize it, no matter how permissive. `parent-child` when the model is nested (the
+ * path-scoped read is the way in), `unavailable` when it is a root collection with no parent to
+ * scope to.
+ */
+'no-collection-group-rule'
+/**
+ * `scope: 'COLLECTION'` over a subcollection: the entry addresses one parent's subcollection by
+ * construction, independent of what the rules say.
+ */
+ | 'nested-collection-scope'
+/**
+ * Every `list` grant on the collection is a constant-`false`.
+ */
+ | 'list-denied'
+/**
+ * No `list` grant covers the collection at all.
+ */
+ | 'list-unmatched';
+/**
+ * The `firestore.rules` evidence behind an entry's {@link CliFirestoreQueryMode} — the WHY, kept
+ * beside the answer rather than inside it.
+ *
+ * Split from the mode deliberately: a caller (or an agent) needs only the mode to decide what to
+ * do, while a reviewer auditing a surprising mode needs these facts to check the reasoning without
+ * re-reading the rules file.
+ *
+ * Absent, like the mode, when the generator was not given a `--rules` file.
+ */
+export interface CliFirestoreQueryRules {
+    /**
+     * The rules' `list` posture for {@link CliFirestoreQueryManifestEntry.collection}, merged across
+     * every match block that reaches it.
+     */
+    readonly list: CliFirestoreQueryRulesAccess;
+    /**
+     * True when the rules declare a `/{path=**}/<collection>/{id}` block — the only shape a
+     * collection-group query is authorized by.
+     */
+    readonly collectionGroup: boolean;
+    /**
+     * Present whenever the mode is not `model`.
+     */
+    readonly reason?: CliFirestoreQueryModeReason;
+    /**
+     * The parent-document path templates a `--parent` key must match, read off the non-recursive
+     * rules match paths that reach this collection (e.g. `jl/{jobLocation}/jlj/{job}`). Lets the CLI
+     * name the required `--parent` shape instead of saying only "pass --parent".
+     */
+    readonly parentPaths?: readonly string[];
+}
 /**
  * One entry in the generated per-model Firestore query catalog.
  *
@@ -619,6 +763,21 @@ export interface CliFirestoreQueryManifestEntry {
      * constraint sequence is empty by design. See {@link relatedSlugs}.
      */
     readonly dispatcher?: boolean;
+    /**
+     * How this entry must be invoked, per `firestore.rules` — unlike the flags
+     * above, this one DOES affect callability.
+     *
+     * Absent when the generator ran without a `--rules` file, which reads as
+     * `unknown` rather than `model`: a guess here would be worse than no field.
+     * Present, the CLI refuses an `unavailable` entry locally rather than paying
+     * a round trip for the `permission-denied` the rules guarantee, and requires
+     * `--parent` for a `parent-child` one.
+     */
+    readonly queryMode?: CliFirestoreQueryMode;
+    /**
+     * The rules evidence behind {@link queryMode}. Set and unset together with it.
+     */
+    readonly rules?: CliFirestoreQueryRules;
     /**
      * Absent when the identifier is not exported from {@link module}'s barrel
      * chain — the entry is listed but cannot be executed.

package/src/lib/mcp-scan/manifest/css-utilities-schema.d.ts

@@ -106,7 +106,7 @@ export declare const CssUtilityEntry: import("arktype/internal/variants/object.t
         property: string;
         value: string;
     }[];
-    role?: "text" | "state" | "size" | "layout" | "misc" | "flex" | "spacing" | "interaction" | "color" | "text-color" | "surface" | "radius" | undefined;
+    role?: "color" | "text" | "state" | "size" | "layout" | "misc" | "flex" | "spacing" | "interaction" | "text-color" | "surface" | "radius" | undefined;
     intent?: string | undefined;
     seeAlso?: string[] | undefined;
     antiUse?: string | undefined;
@@ -149,7 +149,7 @@ export declare const CssUtilityManifest: import("arktype/internal/variants/objec
             property: string;
             value: string;
         }[];
-        role?: "text" | "state" | "size" | "layout" | "misc" | "flex" | "spacing" | "interaction" | "color" | "text-color" | "surface" | "radius" | undefined;
+        role?: "color" | "text" | "state" | "size" | "layout" | "misc" | "flex" | "spacing" | "interaction" | "text-color" | "surface" | "radius" | undefined;
         intent?: string | undefined;
         seeAlso?: string[] | undefined;
         antiUse?: string | undefined;

package/src/lib/mcp-scan/manifest/tokens-schema.d.ts

@@ -58,7 +58,7 @@ export type TokenDefaults = typeof TokenDefaults.infer;
 export declare const TokenEntry: import("arktype/internal/variants/object.ts").ObjectType<{
     cssVariable: string;
     source: "app" | "dbx-web" | "dbx-form" | "mat-sys" | "mdc";
-    role: "breakpoint" | "size" | "misc" | "spacing" | "color" | "text-color" | "surface" | "radius" | "elevation" | "shadow" | "typography" | "motion" | "state-layer";
+    role: "color" | "breakpoint" | "size" | "misc" | "spacing" | "text-color" | "surface" | "radius" | "elevation" | "shadow" | "typography" | "motion" | "state-layer";
     intents: string[];
     description: string;
     defaults: {
@@ -96,7 +96,7 @@ export declare const TokenManifest: import("arktype/internal/variants/object.ts"
     entries: {
         cssVariable: string;
         source: "app" | "dbx-web" | "dbx-form" | "mat-sys" | "mdc";
-        role: "breakpoint" | "size" | "misc" | "spacing" | "color" | "text-color" | "surface" | "radius" | "elevation" | "shadow" | "typography" | "motion" | "state-layer";
+        role: "color" | "breakpoint" | "size" | "misc" | "spacing" | "text-color" | "surface" | "radius" | "elevation" | "shadow" | "typography" | "motion" | "state-layer";
         intents: string[];
         description: string;
         defaults: {

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "13.40.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.40.0",
-    "@dereekb/dbx-cli": "13.40.0",
-    "@dereekb/firebase": "13.40.0",
-    "@dereekb/firebase-server/test": "13.40.0",
-    "@dereekb/model": "13.40.0",
-    "@dereekb/nestjs": "13.40.0",
-    "@dereekb/rxjs": "13.40.0",
-    "@dereekb/util": "13.40.0",
+    "@dereekb/date": "13.42.0",
+    "@dereekb/dbx-cli": "13.42.0",
+    "@dereekb/firebase": "13.42.0",
+    "@dereekb/firebase-server/test": "13.42.0",
+    "@dereekb/model": "13.42.0",
+    "@dereekb/nestjs": "13.42.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "vitest": "4.1.5",

package/validate/index.js

@@ -6334,6 +6334,11 @@ var RESERVED_MODEL_FOLDERS = [
     name: "storagefile",
     reason: "StorageFile is a canonical group from `@dereekb/firebase` with a richer layout than the base 5 files (group, upload, file, etc.); downstream projects extend rather than redeclare it.",
     recommendedTool: "dbx_storagefile_m_validate_folder"
+  },
+  {
+    name: "calendar",
+    reason: "Calendar is a canonical group from `@dereekb/firebase` with a richer layout than the base 5 files (type, expand, ics, processing, etc.); downstream projects extend rather than redeclare it.",
+    recommendedTool: "dbx_model_validate_folder"
   }
 ];
 
@@ -7254,7 +7259,7 @@ function extractGroupModelNames(text) {
   while ((match = MODEL_NAME_RE.exec(text)) !== null) {
     seen.add(match[1]);
   }
-  return [...seen].sort((a, b) => a.localeCompare(b));
+  return Array.from(seen).sort((a, b) => a.localeCompare(b));
 }
 
 // packages/dbx-cli/src/lib/mcp-scan/scan/_jsdoc-tagged-export/extract-base.ts
@@ -8355,7 +8360,7 @@ function buildSummaries(entries, issues) {
     const summary = byModel.get(issue.model);
     if (summary) summary.errorCount += 1;
   }
-  return [...byModel.entries()].map(([model, s]) => ({ model, ...s })).sort((a, b) => a.model.localeCompare(b.model));
+  return Array.from(byModel.entries()).map(([model, s]) => ({ model, ...s })).sort((a, b) => a.model.localeCompare(b.model));
 }
 function compareEntries(a, b) {
   return a.model.localeCompare(b.model) || a.verb.localeCompare(b.verb) || (a.specifier ?? "").localeCompare(b.specifier ?? "");
@@ -8431,7 +8436,7 @@ async function readComponentDereekbDeps(componentAbs) {
       addScopedDependencyNames(json[field], out);
     }
   }
-  return [...out];
+  return Array.from(out);
 }
 function addScopedDependencyNames(field, out) {
   if (isRecord(field)) {
@@ -9864,7 +9869,7 @@ function tryReadTemplateInfoRecord(decl, rel, index) {
     symbolName: decl.getName(),
     directInfoIdentifiers: direct,
     spreadAggregateIdentifiers: spreads,
-    resolvedInfoIdentifiers: [...resolved],
+    resolvedInfoIdentifiers: Array.from(resolved),
     unresolvedSpreadIdentifiers: unresolved,
     sourceFile: rel
   };
@@ -11644,7 +11649,7 @@ function flagUploadServiceWiring(extracted, violations) {
   if (!anyWired) {
     pushViolation9(violations, {
       code: "STORAGEFILE_UPLOAD_SERVICE_NOT_WIRED",
-      message: `No NestJS provider with \`provide: StorageFileInitializeFromUploadService, useFactory: ${factoryNames.size > 0 ? [...factoryNames].join(" | ") : "<storage-file-upload-factory>"}\` found. Bind the factory function in a NestJS module.`,
+      message: `No NestJS provider with \`provide: StorageFileInitializeFromUploadService, useFactory: ${factoryNames.size > 0 ? Array.from(factoryNames).join(" | ") : "<storage-file-upload-factory>"}\` found. Bind the factory function in a NestJS module.`,
       side: "api",
       file: void 0
     });
@@ -13175,7 +13180,7 @@ function collectAllModels(fixtures, instances) {
   const all = /* @__PURE__ */ new Set();
   for (const k of fixtures.keys()) all.add(k);
   for (const k of instances.keys()) all.add(k);
-  const list = [...all];
+  const list = Array.from(all);
   list.sort((a, b) => {
     const aLine = (fixtures.get(a) ?? instances.get(a))?.getStartLineNumber() ?? 0;
     const bLine = (fixtures.get(b) ?? instances.get(b))?.getStartLineNumber() ?? 0;
@@ -13229,7 +13234,7 @@ function collectIdentityImports(sourceFile) {
       }
     }
   }
-  const list = [...out];
+  const list = Array.from(out);
   list.sort((a, b) => a.localeCompare(b));
   return list;
 }

package/validate/package.json

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