@dereekb/dbx-cli 13.11.10 → 13.11.11

package/manifest-extract/index.cjs.js

@@ -2,7 +2,6 @@
 
 var tsMorph = require('ts-morph');
 
-// 'query' is accepted today even though `<Group>ModelCrudFunctionsConfig` in @dereekb/firebase does not yet permit `query:` keys (deferred follow-up). Once query support lands upstream, every query entry flows through here with no change.
 var SUPPORTED_VERBS = new Set([
     'create',
     'read',

package/manifest-extract/index.esm.js

@@ -1,6 +1,5 @@
 import { Project, Node } from 'ts-morph';
 
-// 'query' is accepted today even though `<Group>ModelCrudFunctionsConfig` in @dereekb/firebase does not yet permit `query:` keys (deferred follow-up). Once query support lands upstream, every query entry flows through here with no change.
 var SUPPORTED_VERBS = new Set([
     'create',
     'read',

package/manifest-extract/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "13.11.10",
+  "version": "13.11.11",
   "sideEffects": false,
   "peerDependencies": {
     "ts-morph": "^21.0.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "13.11.10",
+  "version": "13.11.11",
   "sideEffects": false,
   "bin": {
     "dbx-cli-generate-firebase-api-manifest": "firebase-api-manifest/main.js"
@@ -24,10 +24,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.11.10",
-    "@dereekb/firebase": "13.11.10",
-    "@dereekb/nestjs": "13.11.10",
-    "@dereekb/util": "13.11.10",
+    "@dereekb/date": "13.11.11",
+    "@dereekb/firebase": "13.11.11",
+    "@dereekb/nestjs": "13.11.11",
+    "@dereekb/util": "13.11.11",
     "arktype": "^2.2.0",
     "yargs": "^18.0.0"
   },

package/src/lib/action/action.command.factory.d.ts

@@ -0,0 +1,80 @@
+import type { Argv, CommandModule } from 'yargs';
+import { type CliContext } from '../context/cli.context';
+/**
+ * Specification for a composite action command surfaced under `<cli> action ...`.
+ *
+ * Actions are user-defined async lambdas that chain multiple {@link CliContext.callModel} /
+ * {@link CliContext.getModel} / {@link CliContext.getMultipleModels} calls in-process,
+ * letting consumers expose high-leverage workflows (paginate-and-aggregate, fan-out,
+ * derived projections) without spending a CLI round-trip per call.
+ *
+ * Each action runs after the standard auth middleware, so the {@link CliContext} is
+ * already populated by the time {@link ActionCommandSpec.handler} fires.
+ *
+ * @example
+ * ```ts
+ * const districtsForRegion: ActionCommandSpec = {
+ *   command: 'districts <region>',
+ *   describe: 'List every District in a Region.',
+ *   model: 'region',
+ *   builder: (y) => y.positional('region', { type: 'string' }),
+ *   handler: async ({ context, argv }) => {
+ *     const region = String(argv.region);
+ *     return context.callModel({ modelType: 'district', call: 'query', data: { region } });
+ *   }
+ * };
+ * ```
+ */
+export interface ActionCommandSpec<TArgv = any, TResult = unknown> {
+    /**
+     * Yargs command string for the action's leaf — positionals come after the action name.
+     * Example: `'open-jobs-for-region <region>'` resolves to `<cli> action open-jobs-for-region <region>`
+     * (or `<cli> action <model> open-jobs-for-region <region>` when {@link model} is set).
+     */
+    readonly command: string;
+    /**
+     * Short one-line description shown in `<cli> action --help`.
+     */
+    readonly describe: string;
+    /**
+     * When provided, the action is grouped under `<cli> action <model> <action>` instead of
+     * the root `<cli> action <action>`. Use the model's persisted type (e.g. `'region'`,
+     * `'district'`) so the grouping mirrors `model <model>` from {@link buildManifestCommands}.
+     */
+    readonly model?: string;
+    /**
+     * Optional yargs builder. Use to declare positionals and options that the action consumes.
+     */
+    readonly builder?: (yargs: Argv) => Argv;
+    /**
+     * Optional epilogue rendered after `--help` for this action.
+     */
+    readonly helpEpilogue?: string;
+    /**
+     * The action body. Receives the live {@link CliContext} (auth already resolved) and the
+     * parsed argv. Throwing a {@link CliError} surfaces a structured failure envelope.
+     */
+    readonly handler: (input: {
+        readonly context: CliContext;
+        readonly argv: TArgv;
+    }) => Promise<TResult> | TResult;
+    /**
+     * Optional result transform applied before {@link outputResult} serialises the value.
+     * Use to strip noise (e.g. paging cursors) or shape the response for downstream callers.
+     */
+    readonly mapResult?: (result: TResult) => unknown;
+}
+/**
+ * Wraps an {@link ActionCommandSpec} as a yargs `CommandModule`.
+ *
+ * The returned command:
+ *  - Calls {@link requireCliContext} so it fails loudly when auth middleware did not run.
+ *  - Invokes `spec.handler({ context, argv })`.
+ *  - Pipes the result through `spec.mapResult` when provided.
+ *  - Emits the value via {@link outputResult}; emits {@link outputError} + `process.exit(1)` on failure.
+ *
+ * @param spec - The action specification.
+ * @returns The yargs command module ready to be registered under the `action` parent.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createActionCommand<TArgv = any, TResult = unknown>(spec: ActionCommandSpec<TArgv, TResult>): CommandModule;

package/src/lib/action/build-action-commands.d.ts

@@ -0,0 +1,30 @@
+import type { CommandModule } from 'yargs';
+import { type ActionCommandSpec } from './action.command.factory';
+/**
+ * Default name of the parent command that groups all registered action specs.
+ * Surfaces as `<cli> action <action>` (root) and `<cli> action <model> <action>` (model-scoped).
+ */
+export declare const DEFAULT_ACTION_COMMAND_NAME = "action";
+/**
+ * Options accepted by {@link buildActionCommands}.
+ */
+export interface BuildActionCommandsOptions {
+    /**
+     * Name of the parent command that groups all action specs. Defaults to
+     * {@link DEFAULT_ACTION_COMMAND_NAME} (`action`).
+     */
+    readonly actionCommandName?: string;
+}
+/**
+ * Assembles the parent `action` command tree from a list of {@link ActionCommandSpec}s.
+ *
+ * Specs without a `model` are appended as direct subcommands of `action`. Specs with a
+ * `model` are grouped under `action <model> <action>` (mirroring `buildManifestCommands`'
+ * `model <model> <action>` shape) so the model-scoped surface stays browseable.
+ *
+ * @param specs - The action specs registered by the app.
+ * @param options - Optional overrides (e.g. parent command name).
+ * @returns An array containing a single parent `action` command, or empty when no specs were provided.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function buildActionCommands(specs: readonly ActionCommandSpec[], options?: BuildActionCommandsOptions): CommandModule[];

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

@@ -0,0 +1,3 @@
+export * from './action.command.factory';
+export * from './build-action-commands';
+export * from './iterate';

package/src/lib/action/iterate.d.ts

@@ -0,0 +1,231 @@
+import type { OnCallFunctionType, OnCallQueryModelResult } from '@dereekb/firebase';
+import { type Maybe, type PerformAsyncTasksConfig } from '@dereekb/util';
+import { type CliContext } from '../context/cli.context';
+/**
+ * State passed into {@link IterateDbxCliCallModelConfig.buildRequestData} when assembling
+ * the next page's request payload.
+ */
+export interface IterateDbxCliCallModelPageState {
+    /**
+     * Zero-based index of the page about to be fetched.
+     */
+    readonly pageIndex: number;
+    /**
+     * Cursor key returned by the previous page, or undefined for the first page.
+     */
+    readonly cursorDocumentKey: Maybe<string>;
+    /**
+     * Total items visited prior to this page.
+     */
+    readonly visitedItems: number;
+}
+/**
+ * Per-item callback signature for {@link iterateDbxCliCallModel}.
+ *
+ * @typeParam TItem - The item type yielded by the page response.
+ * @typeParam TItemResult - The value produced by processing one item.
+ */
+export type IterateDbxCliCallModelItemFn<TItem, TItemResult> = (input: {
+    readonly context: CliContext;
+    readonly item: TItem;
+    readonly key: string;
+    readonly pageIndex: number;
+    readonly itemIndex: number;
+}) => Promise<TItemResult>;
+/**
+ * Per-page callback signature for {@link iterateDbxCliCallModel}. Invoked after
+ * {@link IterateDbxCliCallModelItemFn} (when both are configured).
+ */
+export type IterateDbxCliCallModelPageFn<TItem, TRaw, TItemResult, TPageResult> = (input: {
+    readonly context: CliContext;
+    readonly page: TRaw;
+    readonly items: ReadonlyArray<TItem>;
+    readonly keys: ReadonlyArray<string>;
+    readonly pageIndex: number;
+    readonly pageItemResults?: ReadonlyArray<TItemResult>;
+}) => Promise<TPageResult>;
+/**
+ * Adapter that maps an arbitrary `callModel` response shape into the pieces
+ * {@link iterateDbxCliCallModel} needs (items, cursor, has-more).
+ *
+ * Defaults to the {@link OnCallQueryModelResult} shape — supply a custom adapter
+ * when iterating responses from other call types (e.g. `getMultiple`-style calls
+ * or custom standalone calls that return an array of records).
+ */
+export interface IterateDbxCliCallModelResponseAdapter<TRaw, TItem> {
+    /**
+     * Pulls the page's items out of the raw response.
+     */
+    readonly items: (raw: TRaw) => ReadonlyArray<TItem>;
+    /**
+     * Returns the keys aligned with {@link items}. Defaults to an empty array when omitted.
+     */
+    readonly keys?: (raw: TRaw) => ReadonlyArray<string>;
+    /**
+     * Returns the cursor key for the next page, or undefined to stop.
+     */
+    readonly cursorDocumentKey?: (raw: TRaw) => Maybe<string>;
+    /**
+     * Overrides the "keep going" check. Defaults to `!!cursorDocumentKey(raw)`.
+     */
+    readonly hasMore?: (raw: TRaw) => boolean;
+}
+/**
+ * Config for {@link iterateDbxCliCallModel}.
+ *
+ * Cursor-paginated iterator over a `callModel` endpoint that returns an array of
+ * items. The default {@link responseAdapter} reads {@link OnCallQueryModelResult}
+ * fields (`results`, `keys`, `cursorDocumentKey`, `hasMore`), so a typical
+ * `call: 'query'` flow only needs to specify `modelType` and `params`. Custom
+ * call shapes can override both {@link buildRequestData} and {@link responseAdapter}.
+ *
+ * @typeParam TParams - The request data shape passed to `callModel`.
+ * @typeParam TItem - The item type yielded by the page response.
+ * @typeParam TRaw - The full raw response shape. Defaults to {@link OnCallQueryModelResult}<TItem>.
+ * @typeParam TItemResult - Per-item processing result type.
+ * @typeParam TPageResult - Per-page processing result type.
+ */
+export interface IterateDbxCliCallModelConfig<TParams, TItem, TRaw = OnCallQueryModelResult<TItem>, TItemResult = void, TPageResult = void> {
+    /**
+     * Active CLI context (provides callModel + auth).
+     */
+    readonly context: CliContext;
+    /**
+     * Target model type, e.g. `'guestbook'`.
+     */
+    readonly modelType: string;
+    /**
+     * Call type.
+     */
+    readonly call: OnCallFunctionType;
+    /**
+     * Optional specifier passed through to `OnCallTypedModelParams`.
+     */
+    readonly specifier?: string;
+    /**
+     * Base request data merged into each page request. The iterator owns the
+     * `cursorDocumentKey` field — anything else on the object (filters, parent
+     * keys, etc.) is forwarded verbatim.
+     */
+    readonly params: TParams;
+    /**
+     * Override how the per-page request data is assembled. Defaults to spreading
+     * `params` with `cursorDocumentKey` and (when {@link limitPerPage} or the
+     * remaining {@link totalItemsLimit} budget is set) `limit` injected.
+     */
+    readonly buildRequestData?: (params: TParams, state: IterateDbxCliCallModelPageState, limit: Maybe<number>) => TParams;
+    /**
+     * Adapter for non-{@link OnCallQueryModelResult} responses.
+     */
+    readonly responseAdapter?: IterateDbxCliCallModelResponseAdapter<TRaw, TItem>;
+    /**
+     * Per-page request limit. Forwarded into the default {@link buildRequestData}.
+     */
+    readonly limitPerPage?: number;
+    /**
+     * Stop once this many items have been visited across all pages.
+     */
+    readonly totalItemsLimit?: number;
+    /**
+     * Stop after this many pages.
+     */
+    readonly maxPages?: number;
+    /**
+     * Per-item processing callback. Parallelism controlled by {@link maxParallelPerPage}.
+     */
+    readonly iterateItem?: IterateDbxCliCallModelItemFn<TItem, TItemResult>;
+    /**
+     * Per-page processing callback. Runs after {@link iterateItem} when both are set.
+     */
+    readonly iteratePage?: IterateDbxCliCallModelPageFn<TItem, TRaw, TItemResult, TPageResult>;
+    /**
+     * Concurrency knobs forwarded to `performAsyncTasks` for {@link iterateItem}.
+     */
+    readonly itemPerformTasksConfig?: Partial<PerformAsyncTasksConfig<TItem>>;
+    /**
+     * Shorthand for `itemPerformTasksConfig.maxParallelTasks`.
+     */
+    readonly maxParallelPerPage?: number;
+    /**
+     * Collect items into the result array. Defaults to true.
+     */
+    readonly collectItems?: boolean;
+    /**
+     * Collect per-item results into the result array. Defaults to true when {@link iterateItem} is set.
+     */
+    readonly collectItemResults?: boolean;
+    /**
+     * Collect per-page results into the result array. Defaults to true when {@link iteratePage} is set.
+     */
+    readonly collectPageResults?: boolean;
+}
+/**
+ * Aggregate result returned by {@link iterateDbxCliCallModel}.
+ */
+export interface IterateDbxCliCallModelResult<TItem, TItemResult, TPageResult> {
+    /**
+     * Number of pages fetched.
+     */
+    readonly totalPages: number;
+    /**
+     * Number of items visited across all pages.
+     */
+    readonly totalItems: number;
+    /**
+     * True when iteration stopped because of `totalItemsLimit` / `maxPages`.
+     */
+    readonly hitLimit: boolean;
+    /**
+     * Last cursor seen. Useful for callers that want to resume later.
+     */
+    readonly lastCursorDocumentKey: Maybe<string>;
+    /**
+     * Flat list of items across all pages. Present when `collectItems !== false`.
+     */
+    readonly items?: ReadonlyArray<TItem>;
+    /**
+     * Flat list of per-item processing results. Present when {@link iterateItem} ran and `collectItemResults !== false`.
+     */
+    readonly itemResults?: ReadonlyArray<TItemResult>;
+    /**
+     * Per-page processing results. Present when {@link iteratePage} ran and `collectPageResults !== false`.
+     */
+    readonly pageResults?: ReadonlyArray<TPageResult>;
+}
+/**
+ * Iterates a paginated `callModel` endpoint, exhausting (or stopping at the configured limit) all pages.
+ *
+ * Cursor-paginated analog of {@link iterateFirestoreDocumentSnapshots}, but speaking HTTP/`callModel`
+ * rather than direct Firestore. The default response adapter reads the canonical
+ * {@link OnCallQueryModelResult} shape — supply a custom adapter to iterate other array-returning
+ * call types (e.g. a `getMultiple`-style standalone call).
+ *
+ * Concurrency: pages are fetched serially (cursor dependency); items within a page can run
+ * in parallel via `maxParallelPerPage` (forwarded to `performAsyncTasks`).
+ *
+ * @example
+ * ```ts
+ * // Exhaust every published Guestbook entry for a single Guestbook.
+ * const { totalItems, items } = await iterateDbxCliCallModel<QueryGuestbookEntriesParams, GuestbookEntry>({
+ *   context,
+ *   modelType: 'guestbookEntry',
+ *   params: { guestbook: 'gb/abc', published: true }
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Fan out to a child action per Guestbook, with 4-way parallelism per page.
+ * const { itemResults } = await iterateDbxCliCallModel<QueryGuestbooksParams, Guestbook, OnCallQueryModelResult<Guestbook>, EntriesForGuestbook>({
+ *   context,
+ *   modelType: 'guestbook',
+ *   params: { published: true },
+ *   maxParallelPerPage: 4,
+ *   iterateItem: ({ context, key }) => queryGuestbookEntriesForGuestbook({ context, guestbook: key, published: true })
+ * });
+ * ```
+ *
+ * @param config - Iterator configuration.
+ * @returns The aggregate result.
+ */
+export declare function iterateDbxCliCallModel<TParams, TItem, TRaw = OnCallQueryModelResult<TItem>, TItemResult = void, TPageResult = void>(config: IterateDbxCliCallModelConfig<TParams, TItem, TRaw, TItemResult, TPageResult>): Promise<IterateDbxCliCallModelResult<TItem, TItemResult, TPageResult>>;

package/src/lib/index.d.ts

@@ -1,3 +1,4 @@
+export * from './action';
 export * from './api';
 export * from './auth';
 export * from './config';

package/src/lib/middleware/auth.middleware.d.ts

@@ -1,5 +1,6 @@
 import type { MiddlewareFunction } from 'yargs';
 import { type CliEnvDefault } from '../config/env';
+import { type CliContext } from '../context/cli.context';
 import { type CliModelManifest } from '../manifest/types';
 export interface CreateAuthMiddlewareInput {
     readonly cliName: string;
@@ -34,3 +35,17 @@ export interface CreateAuthMiddlewareInput {
  * @__NO_SIDE_EFFECTS__
  */
 export declare function createAuthMiddleware(input: CreateAuthMiddlewareInput): MiddlewareFunction;
+/**
+ * Test-only middleware that skips OIDC discovery, disk token loading, and token refresh, attaching
+ * a pre-built {@link CliContext} directly via {@link setCliContext}.
+ *
+ * @internal Intended for use by `@dereekb/dbx-cli/test`. Not for production wiring.
+ *
+ * @param input - The pre-built context to attach on every invocation.
+ * @param input.cliContext - The {@link CliContext} that will be attached via {@link setCliContext}.
+ * @returns A yargs middleware function that always sets the provided context.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createPassthroughAuthMiddleware(input: {
+    readonly cliContext: CliContext;
+}): MiddlewareFunction;

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

@@ -1,5 +1,7 @@
 import { type Argv, type CommandModule } from 'yargs';
+import { type ActionCommandSpec } from '../action/action.command.factory';
 import { type CliEnvDefault } from '../config/env';
+import { type CliContext } from '../context/cli.context';
 import { type DoctorCheck } from '../doctor/doctor.command.factory';
 import { type CliModelManifest } from '../manifest/types';
 /**
@@ -26,6 +28,18 @@ export interface CreateCliInput {
      * it returns a single parent `model <model>` command so the top-level `--help` stays focused.
      */
     readonly apiCommands?: CommandModule[];
+    /**
+     * App-defined composite actions surfaced under `<cli> action <action>` (root) or
+     * `<cli> action <model> <action>` (model-scoped).
+     *
+     * Each action runs after the auth middleware so the handler receives the live
+     * {@link CliContext}. Use for high-leverage workflows that chain multiple
+     * `callModel` / `getModel` / `getMultipleModels` calls in-process so the caller
+     * does not pay one CLI round-trip per call.
+     *
+     * When omitted or empty, no `action` parent command is registered.
+     */
+    readonly actionCommands?: readonly ActionCommandSpec[];
     /**
      * Extra checks appended to the doctor's default check list.
      */
@@ -87,6 +101,17 @@ export interface CreateCliInput {
      * not want to surface the key-decode command itself.
      */
     readonly disableModelDecode?: boolean;
+    /**
+     * Test-only override that bypasses the auth middleware entirely and attaches the supplied
+     * {@link CliContext} on every command invocation.
+     *
+     * When set, the default auth middleware (OIDC discovery, disk token load, refresh, `process.exit`
+     * on failure) is replaced with a passthrough that just calls `setCliContext(testCliContext)`. The
+     * output middleware still runs.
+     *
+     * @internal Intended for use from `@dereekb/dbx-cli/test`. Not for production wiring.
+     */
+    readonly testCliContext?: CliContext;
 }
 /**
  * Top-level CLI builder.

package/test/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/test/src/lib/cli-test.d.ts

@@ -0,0 +1,101 @@
+import { type INestApplication } from '@nestjs/common';
+import { type CliContext, type CliEnvConfig, type CliModelManifest, type CreateCliInput } from '@dereekb/dbx-cli';
+/**
+ * Input for {@link buildTestCliContext}.
+ */
+export interface BuildTestCliContextInput {
+    readonly cliName: string;
+    readonly envName: string;
+    readonly env: CliEnvConfig;
+    readonly accessToken: string;
+    readonly modelManifest?: CliModelManifest;
+}
+/**
+ * Builds a {@link CliContext} for use as `testCliContext` on {@link createCli}.
+ *
+ * Thin wrapper around {@link createCliContext} that exists so test code can import from a single
+ * test-only entry without pulling in production-only types.
+ *
+ * @param input - The context inputs (cliName, envName, env, accessToken, optional modelManifest).
+ * @returns The constructed {@link CliContext} that drives `callModel` / `getModel` / `getMultipleModels`
+ *   against `input.env.apiBaseUrl` with `input.accessToken` as the Bearer token.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function buildTestCliContext(input: BuildTestCliContextInput): CliContext;
+/**
+ * Result envelope returned by {@link runCliCommand}.
+ *
+ * Captures everything tests typically want to assert on: stdout/stderr chunks, the parsed argv,
+ * yargs's help output (if any), any handler error, and the exit code if the handler called
+ * `process.exit` (which is intercepted so it does not actually terminate vitest).
+ *
+ * {@link runCliCommand} always resolves — errors come back in {@link RunCliCommandResult.error}
+ * and exit attempts in {@link RunCliCommandResult.exitCode} so tests can assert on error envelopes
+ * without try/catch boilerplate.
+ */
+export interface RunCliCommandResult {
+    readonly stdout: readonly string[];
+    readonly stderr: readonly string[];
+    readonly stdoutText: string;
+    readonly stderrText: string;
+    readonly argv: unknown;
+    readonly helpOutput: string;
+    readonly error?: Error;
+    /**
+     * Set when the CLI's handler called `process.exit(code)`. Captured (so the test process is not
+     * killed) and surfaced here so tests can assert on the intended exit status.
+     *
+     * Production CLI handlers exit with `1` on CliError (via `wrapCommandHandler`) and `4` on auth
+     * middleware failures. With the `testCliContext` override the auth middleware never exits, but
+     * handler errors still go through `wrapCommandHandler`.
+     */
+    readonly exitCode?: number;
+}
+/**
+ * Drives a CLI invocation in-process and captures all output.
+ *
+ * Creates a fresh yargs `Argv` per call (so middleware/option defaults can't leak across tests),
+ * parses `args`, and collects `process.stdout.write` / `process.stderr.write` / `console.log` /
+ * `console.error` output via `vi.spyOn`. The spies are always restored on completion.
+ *
+ * Always resolves — handler errors and yargs failures are surfaced in {@link RunCliCommandResult.error}
+ * instead of being thrown.
+ *
+ * @param input - The {@link CreateCliInput} used to build the CLI for this invocation. Pass a fresh
+ *   object each call (or rely on the caller-side factory) — yargs `Argv` state is not reused across
+ *   invocations.
+ * @param args - The argv vector to parse (e.g. `['get', 'p/abc']`).
+ * @returns The captured output envelope.
+ */
+export declare function runCliCommand(input: CreateCliInput, args: readonly string[]): Promise<RunCliCommandResult>;
+/**
+ * Idempotently binds the fixture's NestJS application to `127.0.0.1:0` (or the supplied host) and
+ * returns the live `apiBaseUrl` so the CLI's `fetch` calls have a real socket to hit.
+ *
+ * Safe to call multiple times against the same app — when `app.getHttpServer().listening` is true,
+ * skips re-binding and just resolves the current address.
+ *
+ * The caller does NOT need to `.close()` explicitly: the demoApi/firebase-admin-nest fixture closes
+ * the underlying NestJS app at the end of its describe block, which closes the HTTP listener.
+ *
+ * @param input - The fixture app + optional global route prefix (defaults to `'api'` to match
+ *   demo-api's production prefix) and host (defaults to `127.0.0.1`).
+ * @returns The bound `apiBaseUrl` (e.g. `http://127.0.0.1:54321/api`) and the resolved port.
+ */
+export declare function listenOnNestAppForTest(input: ListenOnNestAppForTestInput): Promise<ListenOnNestAppForTestResult>;
+export interface ListenOnNestAppForTestInput {
+    readonly app: INestApplication;
+    /**
+     * Global route prefix the NestJS app is mounted under. Defaults to `'api'` to match the demo-api
+     * production configuration. Pass an empty string to skip the prefix.
+     */
+    readonly apiPrefix?: string;
+    /**
+     * Host to bind to. Defaults to `127.0.0.1`.
+     */
+    readonly host?: string;
+}
+export interface ListenOnNestAppForTestResult {
+    readonly apiBaseUrl: string;
+    readonly port: number;
+}

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

@@ -0,0 +1 @@
+export * from './cli-test';