@dereekb/dbx-cli 13.11.10 → 13.11.12

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.12",
   "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.12",
   "sideEffects": false,
   "bin": {
     "dbx-cli-generate-firebase-api-manifest": "firebase-api-manifest/main.js"
@@ -15,6 +15,12 @@
       "import": "./manifest-extract/index.cjs.mjs",
       "default": "./manifest-extract/index.cjs.js"
     },
+    "./test": {
+      "module": "./test/index.esm.js",
+      "types": "./test/index.d.ts",
+      "import": "./test/index.cjs.mjs",
+      "default": "./test/index.cjs.js"
+    },
     "./package.json": "./package.json",
     ".": {
       "module": "./index.esm.js",
@@ -24,10 +30,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.12",
+    "@dereekb/firebase": "13.11.12",
+    "@dereekb/nestjs": "13.11.12",
+    "@dereekb/util": "13.11.12",
     "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/api/call-model.client.d.ts

@@ -28,10 +28,6 @@ export interface CallModelOverHttpResponse<R = unknown> {
  * The function name is referenced via {@link CALL_MODEL_APP_FUNCTION_KEY} for consistency with the demo's wiring.
  *
  * @param input - The call envelope describing the API target, access token, model params, and optional fetch override.
- * @param input.apiBaseUrl - The API base URL (the `/model/call` path is appended automatically).
- * @param input.accessToken - The Bearer access token sent in the `Authorization` header.
- * @param input.params - The {@link OnCallTypedModelParams} payload posted as JSON.
- * @param input.fetcher - Optional fetch implementation override (used by tests).
  * @returns The parsed JSON response body cast to `R`.
  */
 export declare function callModelOverHttp<T = unknown, R = unknown>(input: CallModelOverHttpInput<T>): Promise<R>;
@@ -105,8 +101,20 @@ export interface GetMultipleModelsOverHttpResult<T = unknown> {
  *
  * Backend route: `ModelApiController.getMany` (packages/firebase-server). Same `'read'` role enforcement.
  *
+ * For >50 keys, use {@link getMultipleModelsOverHttpChunked} to auto-batch and merge.
+ *
  * @param input - The request envelope describing the API target, access token, model, keys, and optional fetch override.
  * @returns The parsed `{ results, errors }` envelope.
  */
 export declare function getMultipleModelsOverHttp<T = unknown>(input: GetMultipleModelsOverHttpInput): Promise<GetMultipleModelsOverHttpResult<T>>;
+/**
+ * Batch-reads any number of keys by chunking into requests of {@link MAX_MODEL_ACCESS_MULTI_READ_KEYS}
+ * keys each and merging the `{ results, errors }` envelopes across batches.
+ *
+ * Chunks are sent sequentially so a single env doesn't see a burst of concurrent connections.
+ *
+ * @param input - Same shape as {@link GetMultipleModelsOverHttpInput} but without the 50-key cap.
+ * @returns The merged `{ results, errors }` envelope across all chunks.
+ */
+export declare function getMultipleModelsOverHttpChunked<T = unknown>(input: GetMultipleModelsOverHttpInput): Promise<GetMultipleModelsOverHttpResult<T>>;
 export { CALL_MODEL_APP_FUNCTION_KEY } from '@dereekb/firebase';

package/src/lib/api/get-many.command.d.ts

@@ -2,9 +2,13 @@ import type { CommandModule } from 'yargs';
 /**
  * Top-level `get-many <firstArg> [rest..]` command.
  *
- * Batch-reads up to 50 Firestore documents in a single request. The first positional can either
- * be an explicit modelType (followed by ≥1 keys) or a full key (followed by additional keys whose
- * prefixes must resolve to the same modelType).
+ * Batch-reads Firestore documents by key. The first positional can either be an explicit
+ * modelType (followed by ≥1 keys) or a full key (followed by additional keys whose prefixes
+ * must resolve to the same modelType). Beyond 50 keys the request is automatically chunked
+ * via `context.getMultipleModels`.
+ *
+ * Stdin: pass `-` as the only positional to read whitespace-separated keys from stdin
+ * (e.g. `cat keys.txt | <cli> get-many -`).
  *
  * Backend: `POST <apiBaseUrl>/model/<modelType>/get` with body `{ keys }` (ModelApiController.getMany).
  */

package/src/lib/config/cli.config.d.ts

@@ -1,5 +1,17 @@
 import { type Maybe } from '@dereekb/util';
 import { type CliEnvConfig } from './env';
+/**
+ * Returns a copy of the env config with the OAuth client id and secret masked via
+ * {@link maskSecret}. The remaining URLs/scopes pass through untouched.
+ *
+ * Used by every command that surfaces an env to the user (`auth status`, `auth show`,
+ * `env list`, `env show`, …) so secrets never end up in the JSON envelope.
+ *
+ * @param env - The env config to mask.
+ * @returns A plain object suitable for the structured stdout envelope.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function maskEnv(env: CliEnvConfig): Record<string, unknown>;
 /**
  * Output settings that can be applied per-command.
  */

package/src/lib/config/env.resolve.d.ts

@@ -0,0 +1,98 @@
+import { type Maybe } from '@dereekb/util';
+import { type CliConfig } from './cli.config';
+import { type CliEnvConfig, type CliEnvDefault } from './env';
+import { type CliPaths } from './paths';
+/**
+ * The narrowed env shape returned by {@link resolveCliEnvOrThrow} when `requireComplete: true`.
+ *
+ * Guarantees that the OIDC client fields are present so callers can pass them through to the
+ * OIDC client/token helpers without a non-null assertion or extra runtime check.
+ */
+export type CliEnvConfigComplete = Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'clientSecret' | 'redirectUri'>> & CliEnvConfig;
+/**
+ * Builds the conventional `<CLINAME>_ENV` env var name from the CLI binary name.
+ *
+ * Example: `demo-cli` → `DEMO_CLI_ENV`.
+ *
+ * @param cliName - The CLI's binary name (typically a kebab-case slug).
+ * @returns The uppercased, underscored env var name used to override the active env.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function getCliEnvVarName(cliName: string): string;
+export interface ResolveCliEnvInput {
+    readonly cliName: string;
+    readonly paths: CliPaths;
+    /**
+     * Value passed via `--env <name>` (highest priority).
+     */
+    readonly flagEnv?: Maybe<string>;
+    /**
+     * Optional override for the env-name env var. Defaults to {@link getCliEnvVarName}(cliName).
+     */
+    readonly envVarName?: string;
+    /**
+     * Optional built-in env presets merged underneath the user's stored env when names match.
+     */
+    readonly defaultEnvs?: readonly CliEnvDefault[];
+}
+export interface ResolveCliEnvResult {
+    /**
+     * The loaded persisted CLI config (possibly empty when no config has been saved yet).
+     */
+    readonly config: CliConfig;
+    /**
+     * The resolved active env name from flag/env-var/active default, or `undefined` when none.
+     */
+    readonly envName: Maybe<string>;
+    /**
+     * The merged env config (stored env + default + env-var overrides), or `undefined` when
+     * neither the stored env nor any defaults/overrides cover this name.
+     */
+    readonly env: Maybe<CliEnvConfig>;
+}
+/**
+ * Resolves the active env for a CLI invocation in one call.
+ *
+ * Performs the env-resolution dance that every per-env command needs:
+ *   1. Load `<configDir>/config.json` (may be missing — returns `{}` in that case).
+ *   2. Resolve env name: `flagEnv` → `process.env[<CLINAME>_ENV]` → `config.activeEnv`.
+ *   3. Look up the stored env block (may be missing).
+ *   4. Merge with the matching {@link CliEnvDefault} (when one is registered).
+ *   5. Overlay `<CLINAME>_*` env var overrides.
+ *
+ * Non-throwing: returns `{ env: undefined, envName: undefined }` when the user has not
+ * configured anything. Use {@link resolveCliEnvOrThrow} for the "command requires an env"
+ * variant.
+ *
+ * @param input - Resolution inputs.
+ * @returns The resolved env triple.
+ */
+export declare function resolveCliEnv(input: ResolveCliEnvInput): Promise<ResolveCliEnvResult>;
+export interface ResolveCliEnvOrThrowInput extends ResolveCliEnvInput {
+    /**
+     * When `true`, throws `AUTH_ENV_INCOMPLETE` if the resolved env is missing OIDC fields
+     * (apiBaseUrl, oidcIssuer, clientId, clientSecret, redirectUri). The returned env is narrowed
+     * to {@link CliEnvConfigComplete}. Defaults to `false`.
+     */
+    readonly requireComplete?: boolean;
+}
+export interface ResolveCliEnvOrThrowResult<E extends CliEnvConfig = CliEnvConfig> {
+    readonly config: CliConfig;
+    readonly envName: string;
+    readonly env: E;
+}
+/**
+ * Throwing variant of {@link resolveCliEnv}.
+ *
+ *  - Throws `NO_ACTIVE_ENV` when neither `--env`, the env var, nor `activeEnv` resolves.
+ *  - Throws `ENV_NOT_FOUND` when the resolved name has no stored config and no matching default.
+ *  - Throws `AUTH_ENV_INCOMPLETE` when `requireComplete` is set and OIDC fields are missing.
+ *
+ * @param input - Resolution inputs (with optional `requireComplete`).
+ * @returns The resolved env triple with `envName` and `env` guaranteed present. When
+ *   `requireComplete` is `true`, `env` is narrowed to {@link CliEnvConfigComplete}.
+ */
+export declare function resolveCliEnvOrThrow(input: ResolveCliEnvOrThrowInput & {
+    readonly requireComplete: true;
+}): Promise<ResolveCliEnvOrThrowResult<CliEnvConfigComplete>>;
+export declare function resolveCliEnvOrThrow(input: ResolveCliEnvOrThrowInput): Promise<ResolveCliEnvOrThrowResult>;

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

@@ -1,4 +1,5 @@
 export * from './cli.config';
 export * from './env';
+export * from './env.resolve';
 export * from './paths';
 export * from './token.cache';

package/src/lib/context/cli.context.d.ts

@@ -9,7 +9,7 @@ import { type CliModelManifest } from '../manifest/types';
  * `<env.apiBaseUrl>/model/*`:
  *  - {@link CliContext.callModel} → `POST /model/call` (typed model dispatch)
  *  - {@link CliContext.getModel} → `GET /model/<modelType>/get?key=<key>`
- *  - {@link CliContext.getMultipleModels} → `POST /model/<modelType>/get` with `{ keys }`
+ *  - {@link CliContext.getMultipleModels} → `POST /model/<modelType>/get` with `{ keys }`, automatically chunked into batches of 50
  *
  * When provided by the runner, {@link CliContext.modelManifest} carries the generated
  * `CliModelManifest` so commands can resolve `prefix/id` keys to a `modelType`.

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;