@dereekb/dbx-cli 13.39.0 → 13.41.0

package/lint-cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-lint-cache",
-  "version": "13.39.0",
+  "version": "13.41.0",
   "private": true,
   "type": "module",
   "devDependencies": {
@@ -8,7 +8,7 @@
     "eslint": "10.4.0"
   },
   "peerDependencies": {
-    "@dereekb/util": "13.39.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.39.0",
+  "version": "13.41.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
     "@dereekb/date": "13.15.0",
-    "@dereekb/dbx-cli": "13.39.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.39.0",
+  "version": "13.41.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/util": "13.39.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.39.0",
+  "version": "13.41.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -66,11 +66,11 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.39.0",
-    "@dereekb/firebase": "13.39.0",
-    "@dereekb/model": "13.39.0",
-    "@dereekb/nestjs": "13.39.0",
-    "@dereekb/util": "13.39.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.39.0",
+  "version": "13.41.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "13.39.0",
-    "@dereekb/dbx-cli": "13.39.0",
-    "@dereekb/firebase": "13.39.0",
-    "@dereekb/model": "13.39.0",
-    "@dereekb/nestjs": "13.39.0",
-    "@dereekb/util": "13.39.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/firestore.session.d.ts

@@ -49,6 +49,20 @@ export interface CreateCliFirestoreSessionContextInput {
      */
     readonly refreshSession?: boolean;
 }
+/**
+ * The Firebase app name a direct-Firestore session registers for a CLI + env pair.
+ *
+ * Deriving the name rather than tracking apps in a side registry is what makes ONE app per CLI + env
+ * per process a property of the code instead of a convention: {@link createCliFirestoreSessionContext}
+ * looks this name up in `getApps()` before initializing, so repeated session opens in one process —
+ * a doctor probe alongside a command's own session, an action that re-resolves the accessor — all
+ * share a single app, and {@link closeAllCliFirebaseApps} finds it again from the name alone.
+ *
+ * @param input - The CLI name and env name the session targets.
+ * @returns The Firebase app name for that pair.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliFirebaseAppName(input: Pick<CreateCliFirestoreSessionContextInput, 'cliName' | 'envName'>): string;
 /**
  * Opens a direct Firestore connection as the authenticated CLI user.
  *
@@ -95,3 +109,29 @@ export declare function createCliFirestoreSessionContext(input: CreateCliFiresto
  * @param session - The session context to close.
  */
 export declare function closeCliFirestoreSessionContext(session: CliFirestoreSessionContext): Promise<void>;
+/**
+ * Deletes every still-live Firebase app this CLI opened, whether or not a session was handed back.
+ *
+ * The CLI's last line of defence against a hang. `closeCliFirestoreSessionContext` covers the normal
+ * path, but it needs a session to be handed to it, and three cases never produce one:
+ *
+ * - a handshake that fails AFTER `initializeApp` — a rejected custom token, a failed App Check
+ *   registration — throws, so the caller that catches it has an initialized app and no session;
+ * - a caller that opens its own session outside the context memo (the doctor probe) owns its own
+ *   teardown, and forgetting it hangs the process;
+ * - a {@link CliContext} orphaned mid-invocation carries the only reference to its session memo.
+ *
+ * Each leaves an app whose `Firestore` and signed-in `Auth` hold the Node event loop open forever.
+ * `getApps()` already tracks every live app and `deleteApp` removes it from that list, so the app
+ * names {@link cliFirebaseAppName} derives are enough to find them again — no side registry to keep
+ * in sync, and idempotent by construction.
+ *
+ * Tolerant of failures for the same reason {@link closeCliFirestoreSessionContext} is: it runs after
+ * the result is already on stdout.
+ *
+ * @param input - The function inputs.
+ * @param input.cliName - The CLI whose apps should be closed. Apps belonging to other Firebase
+ *   consumers in the same process are left alone.
+ * @returns Resolves once every matching app has been deleted.
+ */
+export declare function closeAllCliFirebaseApps(input: Pick<CreateCliFirestoreSessionContextInput, 'cliName'>): Promise<void>;

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/src/lib/runner/index.d.ts

@@ -1 +1,2 @@
+export * from './lifecycle';
 export * from './run';

package/src/lib/runner/lifecycle.d.ts

@@ -0,0 +1,85 @@
+import { type Maybe, type PromiseOrValue } from '@dereekb/util';
+import { type CliContext } from '../context/cli.context';
+/**
+ * Input handed to a {@link CliSetupFunction} / {@link CliTeardownFunction}.
+ */
+export interface CliLifecycleHookInput {
+    readonly cliName: string;
+    /**
+     * The invocation's {@link CliContext}, when one was built.
+     *
+     * Absent for an auth-bypassed command (`auth login`, `env list`, `firestore-queries`), and for a
+     * teardown that runs after authentication itself failed. A hook that needs the context should say
+     * so by throwing from `setup`, which aborts the command with an error envelope — a `teardown` must
+     * tolerate its absence, since it runs on paths `setup` never reached.
+     */
+    readonly context: Maybe<CliContext>;
+}
+/**
+ * App-supplied hook run once per invocation, after the command's arguments validate and the auth
+ * middleware has attached the {@link CliContext}, and before the command's handler.
+ *
+ * Runs inside the parser, so throwing aborts the command: the error is emitted as the standard error
+ * envelope and the process exits non-zero, with {@link CliTeardownFunction} still run. That makes it
+ * the right place for a precondition an app's commands all depend on.
+ */
+export type CliSetupFunction = (input: CliLifecycleHookInput) => PromiseOrValue<void>;
+/**
+ * App-supplied hook run once per invocation after the parser has fully settled, on both the success
+ * and the failure path, and BEFORE the CLI closes its direct-Firestore session — so the hook can
+ * still read Firestore through `input.context`.
+ *
+ * Best-effort, exactly like the built-in session teardown it precedes: it runs after the command's
+ * result is already on stdout, so a throw is swallowed (surfaced under `--verbose`) rather than
+ * changing what the caller sees or the exit code they get.
+ *
+ * A teardown may run when {@link CliSetupFunction} did NOT — an invocation that failed validation or
+ * authentication never reaches setup — so it must not assume setup's side effects are in place.
+ */
+export type CliTeardownFunction = (input: CliLifecycleHookInput) => PromiseOrValue<void>;
+/**
+ * The app-supplied lifecycle hooks accepted by `createCli` / `runCli`.
+ */
+export interface CliLifecycleHooks {
+    /**
+     * Run once before the command's handler. See {@link CliSetupFunction}.
+     */
+    readonly setup?: Maybe<CliSetupFunction>;
+    /**
+     * Run once after the parser settles, before the direct-Firestore session is closed. See
+     * {@link CliTeardownFunction}.
+     */
+    readonly teardown?: Maybe<CliTeardownFunction>;
+}
+/**
+ * Input for {@link cliLifecycleRunner}.
+ */
+export interface CliLifecycleRunnerInput extends CliLifecycleHooks {
+    readonly cliName: string;
+}
+/**
+ * The once-per-invocation view of an app's {@link CliLifecycleHooks}.
+ */
+export interface CliLifecycleRunner {
+    /**
+     * Runs the app's `setup` hook, at most once, rethrowing whatever it throws.
+     */
+    readonly runSetup: (context: Maybe<CliContext>) => Promise<void>;
+    /**
+     * Runs the app's `teardown` hook, at most once, swallowing whatever it throws.
+     */
+    readonly runTeardown: (context: Maybe<CliContext>) => Promise<void>;
+}
+/**
+ * Wraps an app's lifecycle hooks so each runs at most once per process.
+ *
+ * The once-only guard is not a convenience: yargs re-runs a global middleware for every COMMAND
+ * LEVEL it parses, so a nested command (`action worker export`) enters the setup middleware three
+ * times. An app's `setup` is written as "prepare this invocation", not "prepare this command level",
+ * and a hook that opened a connection or wrote a file would do it three times over.
+ *
+ * @param input - The CLI name and the app's hooks.
+ * @returns The guarded runner.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliLifecycleRunner(input: CliLifecycleRunnerInput): CliLifecycleRunner;

package/src/lib/runner/run.d.ts

@@ -5,6 +5,7 @@ import { type CliContext } from '../context/cli.context';
 import { type DoctorCheck } from '../doctor/doctor.command.factory';
 import { type CliFirestoreQueryManifest, type CliModelManifest } from '../manifest/types';
 import { type CliFirestoreBinding } from '../firestore/firestore.models';
+import { type CliLifecycleHooks, type CliLifecycleRunner } from './lifecycle';
 /**
  * Names of the global options registered by {@link createCli} that are not
  * specific to a single manifest command's payload. Manifest commands hide
@@ -12,7 +13,7 @@ import { type CliFirestoreBinding } from '../firestore/firestore.models';
  * focuses on the schema sections.
  */
 export declare const STANDARD_GLOBAL_OPTION_NAMES: readonly string[];
-export interface CreateCliInput {
+export interface CreateCliInput extends CliLifecycleHooks {
     readonly cliName: string;
     /**
      * App-specific config/utility commands appended after the built-in `auth`, `env`, and `doctor` commands.
@@ -145,6 +146,16 @@ export interface CreateCliInput {
      * bundler `define` or a generated module).
      */
     readonly version?: string;
+    /**
+     * The lifecycle runner guarding this invocation's {@link CliLifecycleHooks}.
+     *
+     * Passed by {@link runCli} so the setup hook the parser runs and the teardown hook the exit path
+     * runs share ONE guard — two runners built from the same hooks would each track their own
+     * "already ran" flag, and the pairing between them is the whole contract.
+     *
+     * @internal Apps pass `setup` / `teardown`, not this.
+     */
+    readonly lifecycle?: CliLifecycleRunner;
     /**
      * Optional shell-completion command name. When set, yargs registers
      * `<cli> <completionCommandName>` (defaults to `completion`) that emits a bash/zsh script.
@@ -177,6 +188,9 @@ export interface CreateCliInput {
  *   if {@link CreateCliInput.modelManifest} is provided.
  * @param input.firestore - The app-supplied direct-Firestore binding; enables `firestore-get` / `firestore-query`.
  * @param input.firestoreQueryManifest - The generated Firestore query catalog; enables `firestore-queries`.
+ * @param input.setup - App hook run once before the command's handler; a throw aborts the command.
+ * @param input.teardown - App hook run once after the parser settles, before the Firestore session closes.
+ *   Only {@link runCli} runs it — a caller that drives `createCli().parse()` itself owns its own teardown.
  * @returns The configured yargs `Argv` ready to be `.parse()`-d.
  * @__NO_SIDE_EFFECTS__
  */