@dereekb/dbx-cli 13.40.0 → 13.41.0

package/lint-cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-lint-cache",
-  "version": "13.40.0",
+  "version": "13.41.0",
   "private": true,
   "type": "module",
   "devDependencies": {
@@ -8,7 +8,7 @@
     "eslint": "10.4.0"
   },
   "peerDependencies": {
-    "@dereekb/util": "13.40.0",
+    "@dereekb/util": "13.41.0",
     "yargs": "^18.0.0"
   }
 }

package/manifest-extract/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "13.40.0",
+  "version": "13.41.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
     "@dereekb/date": "13.15.0",
-    "@dereekb/dbx-cli": "13.40.0",
+    "@dereekb/dbx-cli": "13.41.0",
     "@dereekb/firebase": "13.15.0",
     "@dereekb/model": "13.15.0",
     "@dereekb/nestjs": "13.15.0",

package/model-test/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "13.40.0",
+  "version": "13.41.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -66,11 +66,11 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.40.0",
-    "@dereekb/firebase": "13.40.0",
-    "@dereekb/model": "13.40.0",
-    "@dereekb/nestjs": "13.40.0",
-    "@dereekb/util": "13.40.0",
+    "@dereekb/date": "13.41.0",
+    "@dereekb/firebase": "13.41.0",
+    "@dereekb/model": "13.41.0",
+    "@dereekb/nestjs": "13.41.0",
+    "@dereekb/util": "13.41.0",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "firebase": "^12.12.1",

package/route/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/dbx-cli/route",
-  "version": "13.40.0",
+  "version": "13.41.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "13.40.0",
-    "@dereekb/dbx-cli": "13.40.0",
-    "@dereekb/firebase": "13.40.0",
-    "@dereekb/model": "13.40.0",
-    "@dereekb/nestjs": "13.40.0",
-    "@dereekb/util": "13.40.0"
+    "@dereekb/date": "13.41.0",
+    "@dereekb/dbx-cli": "13.41.0",
+    "@dereekb/firebase": "13.41.0",
+    "@dereekb/model": "13.41.0",
+    "@dereekb/nestjs": "13.41.0",
+    "@dereekb/util": "13.41.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/src/lib/doctor/firestore-session.check.d.ts

@@ -57,11 +57,32 @@ export interface FirestoreSessionDoctorReadRouting {
     readonly readPreference: 'firestore' | 'api';
     readonly reason: CliReadSourceReason;
     /**
-     * Query-catalog entries whose factory bound to a real runtime export, and are therefore runnable
-     * by `firestore-query`. A non-invocable entry is listed by `firestore-queries` with `INVOCABLE = no`.
+     * Query-catalog entries `firestore-query` can actually run: the factory bound to a real runtime
+     * export AND `firestore.rules` does not refuse the query at every scope.
+     *
+     * `unavailable` entries are deliberately EXCLUDED. Counting them was the bug this number had:
+     * an entry with a bound factory over a collection with no `/{path=**}/` rule reported as invocable
+     * and then failed with `permission-denied` on every call, so `invocableQueryEntries: 128/128` was
+     * a claim the CLI could not honour for about a third of the catalog.
      */
     readonly invocableQueryEntries: number;
     readonly totalQueryEntries: number;
+    /**
+     * Entries `firestore.rules` refuses at every scope (`queryMode: 'unavailable'`) — the query-level
+     * analogue of {@link serverOnlyModels}, surfaced the same way because it has the same consequence.
+     */
+    readonly unavailableQueryEntries: number;
+    /**
+     * Entries that address ONE parent document's subcollection (`queryMode: 'parent-child'`), so they
+     * run only when scoped with `--parent`.
+     */
+    readonly parentChildQueryEntries: number;
+    /**
+     * Whether the query manifest carries invocation modes at all — false when its generator ran
+     * without `--rules`, in which case the two counts above are structurally `0` rather than
+     * genuinely clean.
+     */
+    readonly queryModesScanned: boolean;
     /**
      * Models the manifest marks `@dbxModelServerOnly` — refused on every `--via` value.
      */

package/src/lib/firestore/firestore.collection.d.ts

@@ -20,6 +20,12 @@ export interface CliFirestoreCollectionForQueryInput {
      * The parent document key to narrow to, from `--parent`.
      */
     readonly parentKey?: FirestoreModelKey;
+    /**
+     * The parent-document path templates the rules declare for this collection, from
+     * `CliFirestoreQueryReachability.parentPaths` (e.g. `jl/{jobLocation}/jlj/{job}`). When supplied,
+     * a `--parent` whose collection chain does not match one of them is rejected locally.
+     */
+    readonly parentPaths?: readonly string[];
 }
 /**
  * Resolves the collection a catalog entry should execute against, applying `--parent` scoping.
@@ -42,3 +48,26 @@ export interface CliFirestoreCollectionForQueryInput {
  * @throws {CliError} When `--parent` is missing where required, supplied where rejected, or the registered collection cannot be scoped.
  */
 export declare function cliFirestoreCollectionForQuery(input: CliFirestoreCollectionForQueryInput): FirestoreCollectionLike<unknown>;
+/**
+ * Validates a `--parent` value before it is turned into a document reference.
+ *
+ * Both checks exist because the failure they prevent is otherwise unreadable. An odd-segment
+ * `--parent` (a COLLECTION path, e.g. `jl/abc/jlj`) reaches `docAtPath` and comes back as a raw
+ * Firestore path assertion; a well-formed key for the WRONG ancestor chain (e.g. `gb/abc` for a
+ * collection that lives under `jl/{loc}/jlj/{job}`) silently produces an empty result set, which is
+ * indistinguishable from "no matching documents".
+ *
+ * The chain comparison is on COLLECTION NAMES only — document ids are the caller's data, and the
+ * rules templates carry `{wildcard}` placeholders there.
+ *
+ * @param input - The model type, the supplied parent key, and the rules-declared parent templates.
+ * @param input.modelType - The model being queried, for the message.
+ * @param input.parentKey - The raw `--parent` value.
+ * @param input.parentPaths - The rules-declared parent path templates, when known.
+ * @throws {CliError} `INVALID_ARGUMENT` when the key is not a document path, or names a chain the rules do not declare.
+ */
+export declare function assertCliFirestoreQueryParentKey(input: {
+    readonly modelType: FirestoreModelType;
+    readonly parentKey: FirestoreModelKey;
+    readonly parentPaths?: readonly string[];
+}): void;

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

@@ -74,6 +74,6 @@ export declare function cliFirestoreQueryConstraints(input: {
  *
  * @param input - The models view, the entry, and the run options.
  * @returns The query result envelope.
- * @throws {CliError} On an argument, scoping, or invocability failure. Firestore's own errors (rules, missing index) surface via `cliFirestoreErrorMapper`.
+ * @throws {CliError} On an argument, scoping, mode, or invocability failure. Firestore's own errors (rules, missing index) surface via `cliFirestoreErrorMapper`.
  */
 export declare function runCliFirestoreQuery(input: RunCliFirestoreQueryInput): Promise<CliFirestoreQueryResult>;

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

@@ -10,4 +10,5 @@ export * from './firestore.query-params';
 export * from './firestore.read';
 export * from './firestore.session';
 export * from './query-info-utils';
+export * from './query-mode';
 export * from './query-registry';

package/src/lib/firestore/query-info-utils.d.ts

@@ -17,9 +17,14 @@ export interface CliFirestoreQueryListFilter {
     readonly model?: string;
     readonly category?: string;
     readonly tag?: string;
+    /**
+     * Drop the entries this CLI cannot run — an unbound factory, or a query `firestore.rules` refuses
+     * at every scope. A `parent-child` entry is KEPT: `--parent` runs it.
+     */
+    readonly invocableOnly?: boolean;
 }
 /**
- * Applies the `--model` / `--category` / `--tag` filters to the catalog.
+ * Applies the `--model` / `--category` / `--tag` / `--invocable-only` filters to the catalog.
  *
  * @param registry - The query catalog.
  * @param filter - The active filters.

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

@@ -562,6 +562,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 +713,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/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "13.40.0",
+  "version": "13.41.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.41.0",
+    "@dereekb/dbx-cli": "13.41.0",
+    "@dereekb/firebase": "13.41.0",
+    "@dereekb/firebase-server/test": "13.41.0",
+    "@dereekb/model": "13.41.0",
+    "@dereekb/nestjs": "13.41.0",
+    "@dereekb/rxjs": "13.41.0",
+    "@dereekb/util": "13.41.0",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "vitest": "4.1.5",

package/validate/package.json

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