@dereekb/dbx-cli 13.38.0 → 13.40.0

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/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__
  */

package/test/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "13.38.0",
+  "version": "13.40.0",
+  "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.38.0",
-    "@dereekb/dbx-cli": "13.38.0",
-    "@dereekb/firebase": "13.38.0",
-    "@dereekb/firebase-server/test": "13.38.0",
-    "@dereekb/model": "13.38.0",
-    "@dereekb/nestjs": "13.38.0",
-    "@dereekb/rxjs": "13.38.0",
-    "@dereekb/util": "13.38.0",
+    "@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",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "vitest": "4.1.5",
@@ -18,13 +19,12 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "module": "./index.esm.js",
       "types": "./index.d.ts",
-      "import": "./index.cjs.mjs",
-      "default": "./index.cjs.js"
+      "import": "./index.esm.js",
+      "default": "./index.esm.js"
     }
   },
   "module": "./index.esm.js",
-  "main": "./index.cjs.js",
+  "main": "./index.esm.js",
   "types": "./index.d.ts"
-}
+}

package/validate/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hapier Creative LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.