@dereekb/dbx-cli 13.11.11 → 13.11.13

package/manifest-extract/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "13.11.11",
+  "version": "13.11.13",
   "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.11",
-    "@dereekb/firebase": "13.11.11",
-    "@dereekb/nestjs": "13.11.11",
-    "@dereekb/util": "13.11.11",
+    "@dereekb/date": "13.11.13",
+    "@dereekb/firebase": "13.11.13",
+    "@dereekb/nestjs": "13.11.13",
+    "@dereekb/util": "13.11.13",
     "arktype": "^2.2.0",
     "yargs": "^18.0.0"
   },

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/runner/run.d.ts

@@ -112,6 +112,22 @@ export interface CreateCliInput {
      * @internal Intended for use from `@dereekb/dbx-cli/test`. Not for production wiring.
      */
     readonly testCliContext?: CliContext;
+    /**
+     * Optional version string. When set, yargs registers `--version` / `-V` on the root parser
+     * returning this value. Defaults to omitted (no `--version` flag).
+     *
+     * Consumers typically pass their `package.json` version (read at build time, e.g. via a
+     * bundler `define` or a generated module).
+     */
+    readonly version?: string;
+    /**
+     * Optional shell-completion command name. When set, yargs registers
+     * `<cli> <completionCommandName>` (defaults to `completion`) that emits a bash/zsh script.
+     * Pass `false` to disable.
+     *
+     * @default 'completion'
+     */
+    readonly completionCommandName?: string | false;
 }
 /**
  * Top-level CLI builder.

package/src/lib/util/handler.d.ts

@@ -2,12 +2,28 @@ import type { Arguments } from 'yargs';
 /**
  * Wraps a yargs command handler with the standard structured-error boilerplate:
  * any thrown error is converted to a `{ ok: false, ... }` envelope via {@link outputError}
- * and the process exits with code 1.
+ * and the process exits with the supplied code (default {@link CLI_EXIT_CODE_HANDLER} = 1).
  *
  * Lets command files drop the per-handler `try { ... } catch (e) { outputError(e); process.exit(1); }`
  * block while keeping the same observable behavior.
  *
  * @param handler - The inner command handler to invoke. May be sync or async.
+ * @param exitCode - Optional override for the exit code on failure (defaults to {@link CLI_EXIT_CODE_HANDLER}).
  * @returns An async handler that delegates to `handler` and converts thrown errors into the standard envelope.
  */
-export declare function wrapCommandHandler<T>(handler: (argv: Arguments<T>) => Promise<void> | void): (argv: Arguments<T>) => Promise<void>;
+export declare function wrapCommandHandler<T>(handler: (argv: Arguments<T>) => Promise<void> | void, exitCode?: number): (argv: Arguments<T>) => Promise<void>;
+/**
+ * Sync variant of {@link wrapCommandHandler} for handlers that never return a Promise.
+ *
+ * Yargs invokes the wrapped function synchronously when registered, so errors thrown by the
+ * inner handler (and by `process.exit` itself when stubbed in tests) propagate synchronously —
+ * which is what `parseSync()`-based tests assert against via `expect(() => ...).toThrow(...)`.
+ *
+ * Use this when the inner handler does not perform any I/O. For async handlers (HTTP calls,
+ * disk reads, prompts) keep using {@link wrapCommandHandler}.
+ *
+ * @param handler - The inner sync command handler.
+ * @param exitCode - Optional override for the exit code on failure.
+ * @returns A sync handler that converts thrown errors into the standard envelope.
+ */
+export declare function wrapSyncCommandHandler<T>(handler: (argv: Arguments<T>) => void, exitCode?: number): (argv: Arguments<T>) => void;

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

@@ -4,3 +4,4 @@ export * from './handler';
 export * from './interactive';
 export * from './output';
 export * from './pagination';
+export * from './stdin';

package/src/lib/util/output.d.ts

@@ -20,7 +20,23 @@ export interface CliOutputOptions {
     readonly dumpDir?: string;
     readonly pick?: string;
     readonly commandPath?: string[];
+    /**
+     * When true, the stdout JSON envelope is rendered with 2-space indent instead of compact.
+     * Driven by the global `--pretty` flag.
+     */
+    readonly pretty?: boolean;
 }
+/**
+ * Standard exit code used when a CLI command handler throws.
+ *
+ * Used by {@link wrapCommandHandler} when no override is supplied.
+ */
+export declare const CLI_EXIT_CODE_HANDLER = 1;
+/**
+ * Exit code used when the auth middleware itself fails (no env, no token, expired refresh,
+ * etc.) — distinct from a handler error so scripts can disambiguate auth from logic failures.
+ */
+export declare const CLI_EXIT_CODE_AUTH = 4;
 /**
  * Patterns that indicate a string may contain a secret token or credential.
  */
@@ -54,6 +70,51 @@ export declare function configureOutputOptions(options: CliOutputOptions): void;
  * @returns The active output options (empty object when never configured).
  */
 export declare function getOutputOptions(): CliOutputOptions;
+/**
+ * Toggles the process-wide verbose flag. The HTTP layer (`call-model.client.ts`,
+ * `oidc.client.ts`) checks {@link isCliVerbose} before each request and emits a
+ * `[<method> <url>]` trace line to stderr when enabled.
+ *
+ * @param value - Whether verbose tracing is on.
+ */
+export declare function setCliVerbose(value: boolean): void;
+/**
+ * @returns Whether the verbose flag is currently enabled.
+ */
+export declare function isCliVerbose(): boolean;
+/**
+ * Writes a one-line stderr trace prefixed with `[verbose]` when the verbose
+ * flag is on. No-op otherwise. Kept off stdout so the JSON envelope on stdout
+ * stays parseable.
+ *
+ * @param message - The trace message.
+ */
+export declare function verboseLog(message: string): void;
+/**
+ * Drop-in `fetch` replacement that wraps the request with the configured verbose-trace
+ * and `--timeout` behavior. Aborts via `AbortController` after the configured timeout.
+ *
+ * Translates an aborted request into a {@link CliError} with code `TIMEOUT`.
+ *
+ * @param fetcher - The underlying fetch impl (defaults to global `fetch`). Allows tests to inject.
+ * @param input - The first arg to fetch (URL or Request).
+ * @param init - The RequestInit. Any existing `signal` is preserved; we only attach our own when no signal was supplied.
+ * @returns The fetch Response.
+ */
+export declare function tracedFetch(fetcher: typeof fetch | undefined, input: string | URL | Request, init?: RequestInit): Promise<Response>;
+/**
+ * Sets the process-wide HTTP timeout (in milliseconds) honored by the HTTP layer.
+ *
+ * Pass `undefined` to clear. The HTTP helpers thread this into an `AbortController`
+ * so individual `fetch` calls cancel after the configured duration.
+ *
+ * @param ms - Timeout in ms, or `undefined` to clear.
+ */
+export declare function setCliTimeoutMs(ms: Maybe<number>): void;
+/**
+ * @returns The current process-wide HTTP timeout in ms, or `undefined` when unset.
+ */
+export declare function getCliTimeoutMs(): Maybe<number>;
 /**
  * Replaces the active secret-redaction pattern list with the given patterns.
  *
@@ -110,7 +171,8 @@ export declare function pickFields<T>(data: T, pick: string): T;
  * Prints a successful command result as a `{ ok: true, data, meta? }` JSON envelope on stdout.
  *
  * Also writes a full unfiltered dump to disk when `dumpDir` is configured, then applies any
- * configured `pick` filter to the stdout payload.
+ * configured `pick` filter to the stdout payload. Honors the global `--pretty` flag for the
+ * stdout payload only (the dump-to-disk path is always pretty-printed).
  *
  * @param data - The command result to emit.
  * @param meta - Optional additional metadata to attach to the envelope.
@@ -119,6 +181,8 @@ export declare function outputResult<T>(data: T, meta?: Record<string, unknown>)
 /**
  * Prints a failed command result as a `{ ok: false, error, code, suggestion? }` JSON envelope on stdout.
  *
+ * Honors the global `--pretty` flag.
+ *
  * @param error - The thrown value to convert. Mapped via {@link buildErrorOutput} (which consults any registered {@link CliErrorMapper}).
  */
 export declare function outputError(error: unknown): void;

package/src/lib/util/stdin.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Returns `true` when the user passed `-` (the conventional "read from stdin" sentinel) as a
+ * positional or flag value. Centralizes the convention so command handlers can pattern-match
+ * consistently.
+ *
+ * @param value - The raw argv value to inspect.
+ * @returns `true` when the value is exactly `'-'`.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isStdinSentinel(value: unknown): boolean;
+/**
+ * Reads the entire contents of `process.stdin` as a UTF-8 string.
+ *
+ * Used by command handlers that accept `-` to mean "read from stdin" (e.g. `--data -`,
+ * `get-many -`). Resolves once the stream emits `end`; no timeout is applied — callers that
+ * need one should wrap with `Promise.race`.
+ *
+ * @returns The UTF-8 decoded stdin contents.
+ */
+export declare function readAllStdin(): Promise<string>;
+/**
+ * Reads stdin as a list of whitespace-separated tokens (newlines, spaces, tabs).
+ *
+ * Empty tokens are dropped so a trailing newline doesn't introduce a phantom entry.
+ *
+ * @returns The tokens parsed from stdin.
+ */
+export declare function readStdinTokens(): Promise<string[]>;

package/test/index.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./index.cjs.js').default;