@dereekb/dbx-cli 13.11.0

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

@@ -0,0 +1,33 @@
+/**
+ * Path configuration for a CLI's on-disk config and token cache files.
+ */
+export interface CliPaths {
+    readonly configDir: string;
+    readonly configFilePath: string;
+    readonly tokenCachePath: string;
+}
+export interface CliPathsConfig {
+    /**
+     * The CLI name. Used as the directory suffix (e.g. `demo-cli` → `~/.demo-cli`).
+     */
+    readonly cliName: string;
+    /**
+     * Optional override for the config directory. When set, this is used verbatim instead of `~/.<cliName>`.
+     *
+     * Useful for tests that want to point at a temp dir.
+     */
+    readonly configDirOverride?: string;
+}
+/**
+ * Builds the on-disk path layout for a CLI's config directory.
+ *
+ * Layout:
+ *   - `<configDir>/config.json` — the persistent CLI config (envs, output settings)
+ *   - `<configDir>/.tokens.json` — per-env access/refresh token cache (mode 0600)
+ *
+ * @param config - The path-building inputs.
+ * @param config.cliName - The CLI's binary name; the default config dir is `~/.<cliName>`.
+ * @param config.configDirOverride - Optional override that replaces the default config directory verbatim (used by tests).
+ * @returns The {@link CliPaths} pointing at `configDir`, the config file, and the token cache file.
+ */
+export declare function buildCliPaths(config: CliPathsConfig): CliPaths;

package/src/lib/config/token.cache.d.ts

@@ -0,0 +1,51 @@
+import { type AsyncKeyedValueCache, type Maybe } from '@dereekb/util';
+/**
+ * A cached token entry for a single env.
+ */
+export interface CliTokenEntry {
+    readonly accessToken: string;
+    readonly refreshToken?: string;
+    /**
+     * Unix epoch milliseconds at which the access token expires.
+     */
+    readonly expiresAt: number;
+    readonly tokenType?: string;
+    readonly scope?: string;
+    readonly idToken?: string;
+}
+/**
+ * Token cache shape on disk — keyed by env name.
+ */
+export type CliTokenCache = Record<string, CliTokenEntry>;
+/**
+ * Token cache store keyed by env name.
+ *
+ * Backed by a single JSON file with per-process in-memory memoization. See
+ * {@link createMemoizedJsonFileAsyncKeyedValueCache} for the underlying file/memo behavior.
+ */
+export type CliTokenCacheStore = AsyncKeyedValueCache<CliTokenEntry>;
+export interface CreateCliTokenCacheStoreInput {
+    readonly tokenCachePath: string;
+}
+/**
+ * Creates a per-env token cache store backed by a single JSON file.
+ *
+ * Entries are written with mode 0o600. Reads are memoized per-process to avoid hitting disk
+ * on every access.
+ *
+ * @param input - The cache store inputs.
+ * @param input.tokenCachePath - Absolute path to the JSON file backing the cache.
+ * @returns A {@link CliTokenCacheStore} keyed by env name.
+ */
+export declare function createCliTokenCacheStore(input: CreateCliTokenCacheStoreInput): CliTokenCacheStore;
+/**
+ * Returns true when the token entry's access token is at or near expiry.
+ *
+ * Defaults to a 60-second buffer to allow for clock skew and request latency.
+ *
+ * @param entry - The token cache entry to check (`null`/`undefined` is treated as expired).
+ * @param nowMs - The current time in unix epoch milliseconds. Defaults to `Date.now()`.
+ * @param bufferMs - Skew/latency buffer in milliseconds; the token is treated as expired this far ahead of `expiresAt`.
+ * @returns `true` when the token is at or within `bufferMs` of expiry, otherwise `false`.
+ */
+export declare function isTokenExpired(entry: Maybe<CliTokenEntry>, nowMs?: number, bufferMs?: number): boolean;

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

@@ -0,0 +1,41 @@
+import type { OnCallTypedModelParams } from '@dereekb/firebase';
+import { type CliEnvConfig } from '../config/env';
+/**
+ * The CLI context attached to argv by the auth middleware.
+ *
+ * Holds the active env, the current access token, and a `callModel` helper that performs
+ * the HTTP call against `<env.apiBaseUrl>/model/call`.
+ */
+export interface CliContext {
+    readonly cliName: string;
+    readonly envName: string;
+    readonly env: CliEnvConfig;
+    readonly accessToken: string;
+    readonly callModel: <TParams = unknown, TResult = unknown>(params: OnCallTypedModelParams<TParams>) => Promise<TResult>;
+}
+export declare const setCliContext: (value: import("@dereekb/util").Maybe<CliContext>) => void;
+export declare const getCliContext: () => import("@dereekb/util").Maybe<CliContext>;
+/**
+ * Returns the current {@link CliContext} or throws — for use in command handlers that require auth.
+ */
+export declare const requireCliContext: () => CliContext;
+export interface CreateCliContextInput {
+    readonly cliName: string;
+    readonly envName: string;
+    readonly env: CliEnvConfig;
+    readonly accessToken: string;
+}
+/**
+ * Builds a {@link CliContext} for the current invocation.
+ *
+ * Bundles the env config and access token alongside a `callModel` helper that POSTs to
+ * `<env.apiBaseUrl>/model/call` with the cached Bearer token.
+ *
+ * @param input - The context inputs.
+ * @param input.cliName - The CLI's binary name.
+ * @param input.envName - The active env name.
+ * @param input.env - The resolved {@link CliEnvConfig} for the active env.
+ * @param input.accessToken - The Bearer access token to include on outgoing API calls.
+ * @returns The constructed {@link CliContext}.
+ */
+export declare function createCliContext(input: CreateCliContextInput): CliContext;

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

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

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

@@ -0,0 +1,48 @@
+import type { CommandModule } from 'yargs';
+import { type Maybe } from '@dereekb/util';
+import { type CliConfig } from '../config/cli.config';
+import { type CliEnvConfig, type CliEnvDefault } from '../config/env';
+export interface DoctorCheckInput {
+    readonly cliName: string;
+    readonly envName: Maybe<string>;
+    readonly env: Maybe<CliEnvConfig>;
+    readonly config: Maybe<CliConfig>;
+}
+export interface DoctorCheckResult {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly detail?: unknown;
+    readonly suggestion?: string;
+}
+export type DoctorCheck = (input: DoctorCheckInput) => Promise<DoctorCheckResult>;
+/**
+ * Built-in checks: config file present, active env resolved, OIDC discovery, token refresh, API reachability.
+ *
+ * @returns The default {@link DoctorCheck} list, in execution order.
+ */
+export declare function defaultDoctorChecks(): DoctorCheck[];
+export interface CreateDoctorCommandInput {
+    readonly cliName: string;
+    /**
+     * Additional checks to append after the default check list.
+     */
+    readonly checks?: DoctorCheck[];
+    /**
+     * Built-in env presets. Resolved by env name and merged underneath the user's stored config so
+     * doctor can run against an env that only stores overrides on top of a registered default.
+     */
+    readonly defaultEnvs?: readonly CliEnvDefault[];
+}
+/**
+ * Composable doctor command.
+ *
+ * Runs all checks, prints a JSON summary, and exits 0 even when checks fail (the `ok` flag in the
+ * envelope is what callers script against).
+ *
+ * @param input - Factory configuration.
+ * @param input.cliName - The CLI's binary name.
+ * @param input.checks - Additional checks to append after the default check list.
+ * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
+ * @returns A yargs `CommandModule` exposing the `doctor` command.
+ */
+export declare function createDoctorCommand(input: CreateDoctorCommandInput): CommandModule;

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

@@ -0,0 +1 @@
+export * from './doctor.command.factory';

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

@@ -0,0 +1,22 @@
+import type { CommandModule } from 'yargs';
+import { type CliEnvDefault } from '../config/env';
+export interface CreateEnvCommandInput {
+    readonly cliName: string;
+    /**
+     * Built-in env presets. Resolved by env name and merged underneath the user's stored config so
+     * `env list` / `env show` / `env add` reflect the effective config.
+     */
+    readonly defaultEnvs?: readonly CliEnvDefault[];
+}
+/**
+ * Factory for the built-in `env` command tree.
+ *
+ * Wires `list`, `use`, `add`, `show`, and `remove` subcommands that operate on the persisted env
+ * registry. Token-cache entries are removed when an env is deleted.
+ *
+ * @param input - Factory configuration.
+ * @param input.cliName - The CLI's binary name.
+ * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
+ * @returns A yargs `CommandModule` exposing the full `env` subcommand surface.
+ */
+export declare function createEnvCommand(input: CreateEnvCommandInput): CommandModule;

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

@@ -0,0 +1 @@
+export * from './env.command.factory';

package/src/lib/index.d.ts

@@ -0,0 +1,11 @@
+export * from './api';
+export * from './auth';
+export * from './config';
+export * from './context';
+export * from './doctor';
+export * from './env';
+export * from './manifest';
+export * from './middleware';
+export * from './output';
+export * from './runner';
+export * from './util';

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

@@ -0,0 +1,77 @@
+import { type CommandModule } from 'yargs';
+import { type CliApiManifest } from './types';
+/**
+ * Format used for the `Params Schema` section of a manifest command's `--help`
+ * epilogue.
+ *
+ *  - `jsonschema` (default): emits a draft-2020-12 JSON Schema, the canonical
+ *    shape `--data <json>` must match.
+ *  - `arktype`: emits the arktype `expression` string — a compact, copy-pastable
+ *    declaration that round-trips through `type(...)` to an equivalent validator.
+ *  - `both`: emits the JSON Schema followed by the arktype expression.
+ */
+export type ManifestHelpDataFormat = 'jsonschema' | 'arktype' | 'both';
+/**
+ * Default schema format when no override is supplied.
+ */
+export declare const DEFAULT_MANIFEST_HELP_DATA_FORMAT: ManifestHelpDataFormat;
+/**
+ * Options accepted by {@link buildManifestCommands}.
+ */
+export interface BuildManifestCommandsOptions {
+    /**
+     * argv used to detect `--data-help`, `--all-help`, and similar flags.
+     * Defaults to `process.argv`. Tests pass an explicit value so detection
+     * does not leak from the surrounding process.
+     */
+    readonly argv?: readonly string[];
+    /**
+     * Format used for the `Params Schema` section of `--help`.
+     *
+     * When omitted, the configured argv is scanned for `--data-help=<format>`
+     * (or `--data-help <format>`). Falls back to
+     * {@link DEFAULT_MANIFEST_HELP_DATA_FORMAT}.
+     */
+    readonly dataHelpFormat?: ManifestHelpDataFormat;
+    /**
+     * Whether to hide unrelated global options (like `--verbose`, `--dump-dir`,
+     * `--pick`, …) from `--help` when the user passed `--data-help`. Defaults
+     * to `true` so the help output stays focused on the schema sections.
+     *
+     * Even when this is `true`, the user can pass `--all-help` to opt back in
+     * to the full options table.
+     */
+    readonly focusHelpOnDataHelp?: boolean;
+    /**
+     * Names of global options to hide when focus mode is in effect. Defaults
+     * to {@link STANDARD_GLOBAL_OPTION_NAMES} (the options registered by
+     * {@link createCli}).
+     */
+    readonly hiddenWhenFocused?: readonly string[];
+}
+/**
+ * Builds yargs `CommandModule[]` from a generated {@link CliApiManifest}.
+ *
+ * Groups entries by `model`, emitting one parent command per model and one child action per entry
+ * (named `<verb>` or `<verb>-<specifier>`). Each child accepts `--data <json>`, validates the
+ * payload against the entry's bound arktype validator (when present), and dispatches via the
+ * authenticated CLI context's `callModel` helper. Standalone entries are skipped because they
+ * are not dispatched through the `/model/call` endpoint.
+ *
+ * @param manifest - The generated manifest array.
+ * @param options - Optional overrides; see {@link BuildManifestCommandsOptions}.
+ * @returns The yargs `CommandModule[]` ready to be passed to `runCli({ apiCommands })`.
+ */
+export declare function buildManifestCommands(manifest: CliApiManifest, options?: BuildManifestCommandsOptions): CommandModule[];
+/**
+ * Inspects an argv array for `--data-help=<format>` or `--data-help <format>`
+ * and returns the requested {@link ManifestHelpDataFormat}.
+ *
+ * Implemented as a raw argv scan (rather than going through yargs) because the
+ * value is needed when each command's builder runs — which is before yargs
+ * parses argv. Unrecognized values fall back to the default.
+ *
+ * @param argv - argv to inspect (defaults to `process.argv`).
+ * @returns The detected format, or {@link DEFAULT_MANIFEST_HELP_DATA_FORMAT}.
+ */
+export declare function detectDataHelpFormat(argv?: readonly string[]): ManifestHelpDataFormat;

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

@@ -0,0 +1,2 @@
+export * from './build-manifest-commands';
+export * from './types';

package/src/lib/manifest/types.d.ts

@@ -0,0 +1,20 @@
+import { type Type } from 'arktype';
+export type CliApiVerb = 'create' | 'read' | 'update' | 'delete' | 'query' | 'standalone';
+export interface CliApiManifestField {
+    readonly name: string;
+    readonly typeText: string;
+    readonly description?: string;
+}
+export interface CliApiManifestEntry {
+    readonly model: string;
+    readonly verb: CliApiVerb;
+    readonly specifier?: string;
+    readonly paramsTypeName?: string;
+    readonly paramsValidator?: Type<unknown>;
+    readonly resultTypeName?: string;
+    readonly groupName: string;
+    readonly sourceFile: string;
+    readonly description?: string;
+    readonly paramsFields?: readonly CliApiManifestField[];
+}
+export type CliApiManifest = readonly CliApiManifestEntry[];

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

@@ -0,0 +1,29 @@
+import type { MiddlewareFunction } from 'yargs';
+import { type CliEnvDefault } from '../config/env';
+export interface CreateAuthMiddlewareInput {
+    readonly cliName: string;
+    /**
+     * Top-level command names that bypass authentication entirely.
+     *
+     * Conventionally: `auth`, `env`, `doctor`, plus any other config/utility commands.
+     */
+    readonly skipCommands: ReadonlySet<string>;
+    /**
+     * Built-in env presets. Merged underneath the user's stored env when the env name matches.
+     */
+    readonly defaultEnvs?: readonly CliEnvDefault[];
+}
+/**
+ * Yargs middleware that resolves the active env, loads/refreshes its access token, and attaches
+ * a {@link CliContext} via the module-level slot.
+ *
+ * Skips auth for the configured top-level commands so `auth login`, `env list`, etc. don't require
+ * a valid token.
+ *
+ * @param input - Middleware configuration.
+ * @param input.cliName - The CLI's binary name (used to derive the env-var prefix and config dir).
+ * @param input.skipCommands - Top-level command names that bypass authentication entirely.
+ * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
+ * @returns A yargs middleware function suitable for `.middleware([..., true])`.
+ */
+export declare function createAuthMiddleware(input: CreateAuthMiddlewareInput): MiddlewareFunction;

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

@@ -0,0 +1,2 @@
+export * from './auth.middleware';
+export * from './output.middleware';

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

@@ -0,0 +1,54 @@
+import { type Maybe } from '@dereekb/util';
+import type { MiddlewareFunction } from 'yargs';
+import { type CliCommandOutputConfig, type CliOutputConfig } from '../config/cli.config';
+/**
+ * Returns the output config slice from wherever the consumer stores it.
+ *
+ * Default implementation reads from `<configDir>/config.json` at the dbx-cli location, but
+ * apps with their own on-disk config shape (e.g. zoho-cli) plug in their own loader.
+ */
+export type LoadOutputConfigFn = () => Promise<Maybe<CliOutputConfig>>;
+/**
+ * Persists a per-command output override (called only when `--set-pick` / `--set-dump-dir` is used).
+ *
+ * Apps with their own config-file shape pass an implementation that merges into their store.
+ */
+export type SaveCommandOutputConfigFn = (commandKey: string, config: CliCommandOutputConfig) => Promise<void>;
+export interface CreateOutputMiddlewareInput {
+    readonly cliName: string;
+    /**
+     * Top-level command names whose output should never be filtered by saved pick/dump-dir
+     * (typically the same set passed to {@link createAuthMiddleware}).
+     */
+    readonly skipCommands: ReadonlySet<string>;
+    /**
+     * Optional override for how the output config is read.
+     *
+     * When omitted, defaults to reading from `~/.config/<cliName>/config.json` via
+     * {@link loadCliConfig} + {@link buildCliPaths}.
+     */
+    readonly loadOutputConfig?: LoadOutputConfigFn;
+    /**
+     * Optional override for how a per-command output config is persisted.
+     *
+     * When omitted, defaults to {@link mergeCliConfig} writing into `~/.config/<cliName>/config.json`.
+     */
+    readonly saveCommandOutputConfig?: SaveCommandOutputConfigFn;
+}
+/**
+ * Yargs middleware that resolves output options (`--pick`, `--dump-dir`) by combining CLI flags,
+ * `--set-pick` / `--set-dump-dir` saves, per-command config, and global config — then writes them
+ * into the module-level output options slot.
+ *
+ * Consumers with a non-default config-file shape (e.g. zoho-cli's per-product layout) inject
+ * {@link CreateOutputMiddlewareInput.loadOutputConfig} and {@link CreateOutputMiddlewareInput.saveCommandOutputConfig}
+ * so the middleware orchestrates resolve/save without owning the storage format.
+ *
+ * @param input - Middleware configuration.
+ * @param input.cliName - The CLI's binary name (used to derive the default config path).
+ * @param input.skipCommands - Top-level command names whose output is never filtered by saved pick/dump-dir.
+ * @param input.loadOutputConfig - Optional override for how the output config is read.
+ * @param input.saveCommandOutputConfig - Optional override for how a per-command output config is persisted.
+ * @returns A yargs middleware function suitable for `.middleware([..., true])`.
+ */
+export declare function createOutputMiddleware(input: CreateOutputMiddlewareInput): MiddlewareFunction;

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

@@ -0,0 +1 @@
+export * from './output.command.factory';

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

@@ -0,0 +1,55 @@
+import type { CommandModule } from 'yargs';
+import { type CliOutputConfig } from '../config/cli.config';
+import { type LoadOutputConfigFn } from '../middleware/output.middleware';
+/**
+ * Persists a partial output config update (global + per-command overrides). Implementations are
+ * expected to merge with existing state — the same semantics used by {@link mergeCliConfig}.
+ */
+export type MergeOutputConfigFn = (update: CliOutputConfig) => Promise<unknown>;
+/**
+ * Wipes the persisted output config entirely (global defaults + every per-command override).
+ */
+export type ClearOutputConfigFn = () => Promise<unknown>;
+export interface CreateOutputCommandInput {
+    readonly cliName: string;
+    /**
+     * Reads the persisted output config. When omitted, defaults to dbx-cli's own
+     * `<configDir>/config.json` via {@link loadCliConfig}.
+     */
+    readonly loadOutputConfig?: LoadOutputConfigFn;
+    /**
+     * Merges partial updates into the persisted output config. When omitted, defaults to
+     * {@link mergeCliConfig} writing to `<configDir>/config.json`.
+     */
+    readonly mergeOutputConfig?: MergeOutputConfigFn;
+    /**
+     * Clears the persisted output config. When omitted, defaults to merging an empty/`undefined`
+     * output slice via {@link mergeCliConfig}.
+     */
+    readonly clearOutputConfig?: ClearOutputConfigFn;
+}
+/**
+ * Factory for the `output` config command.
+ *
+ * Subcommands:
+ * - `output set [--command <key>] [--set-dump-dir <path>] [--set-pick <fields>]`
+ * - `output show`
+ * - `output clear [--command <key>]`
+ *
+ * The factory accepts callbacks for reading/writing the persisted output config so each CLI can
+ * plug in its own on-disk shape (e.g. dbx-cli's flat `<config>.output`, zoho-cli's
+ * shared/recruit/crm/desk wrapper). When omitted, the dbx-cli defaults persist to
+ * `<configDir>/config.json`.
+ *
+ * The `--set-dump-dir` / `--set-pick` flags on `output set` reuse the global flags registered by
+ * {@link createCli}, so the same syntax `<cli> output set --command foo.bar --set-pick a,b` works
+ * across CLIs.
+ *
+ * @param input - Factory configuration.
+ * @param input.cliName - The CLI's binary name (used to derive the default config path).
+ * @param input.loadOutputConfig - Optional override for reading the persisted output config.
+ * @param input.mergeOutputConfig - Optional override for persisting partial output-config updates.
+ * @param input.clearOutputConfig - Optional override for clearing the persisted output config entirely.
+ * @returns A yargs `CommandModule` exposing the full `output` subcommand surface.
+ */
+export declare function createOutputCommand(input: CreateOutputCommandInput): CommandModule;

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

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

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

@@ -0,0 +1,71 @@
+import { type Argv, type CommandModule } from 'yargs';
+import { type CliEnvDefault } from '../config/env';
+import { type DoctorCheck } from '../doctor/doctor.command.factory';
+/**
+ * Names of the global options registered by {@link createCli} that are not
+ * specific to a single manifest command's payload. Manifest commands hide
+ * these from `--help` when the user passes `--data-help` so the help output
+ * focuses on the schema sections.
+ */
+export declare const STANDARD_GLOBAL_OPTION_NAMES: readonly string[];
+export interface CreateCliInput {
+    readonly cliName: string;
+    /**
+     * App-specific config/utility commands appended after the built-in `auth`, `env`, and `doctor` commands.
+     *
+     * Commands listed here bypass authentication.
+     */
+    readonly configCommands?: CommandModule[];
+    /**
+     * App-specific API commands appended after the built-in `call` passthrough.
+     *
+     * Commands listed here run after the auth middleware, so they have access to the {@link CliContext}.
+     */
+    readonly apiCommands?: CommandModule[];
+    /**
+     * Extra checks appended to the doctor's default check list.
+     */
+    readonly doctorChecks?: DoctorCheck[];
+    /**
+     * Built-in env presets shipped with the CLI. When the user runs commands against an env name
+     * that matches one of {@link CliEnvDefault.names}, the default values are merged underneath the
+     * stored config so users don't need to supply `apiBaseUrl`/`oidcIssuer` themselves.
+     */
+    readonly defaultEnvs?: readonly CliEnvDefault[];
+    /**
+     * Argv to parse. Defaults to `hideBin(process.argv)`.
+     */
+    readonly argv?: string[];
+    /**
+     * Disable the built-in `call` passthrough — useful when an app prefers to expose only typed wrappers.
+     */
+    readonly disableCallPassthrough?: boolean;
+}
+/**
+ * Top-level CLI builder.
+ *
+ * Wires the standard yargs setup (global flags, auth/output middleware, the built-in `auth`, `env`,
+ * `doctor`, and `call` commands), and returns a yargs parser ready to be `.parse()`-d.
+ *
+ * App CLIs become a thin `index.ts` that imports `createCli`, registers any app-specific commands,
+ * and calls `.parse()`.
+ *
+ * @param input - Builder configuration.
+ * @param input.cliName - The CLI's binary name (used as `scriptName`, env-var prefix, and config dir).
+ * @param input.configCommands - App-specific config/utility commands appended after the built-ins; bypass auth.
+ * @param input.apiCommands - App-specific API commands appended after the built-in `call` passthrough; run after auth middleware.
+ * @param input.doctorChecks - Extra checks appended to the doctor's default check list.
+ * @param input.defaultEnvs - Built-in env presets shipped with the CLI.
+ * @param input.argv - Argv to parse. Defaults to `hideBin(process.argv)`.
+ * @param input.disableCallPassthrough - When `true`, omits the built-in `call` passthrough.
+ * @returns The configured yargs `Argv` ready to be `.parse()`-d.
+ */
+export declare function createCli(input: CreateCliInput): Argv;
+/**
+ * Convenience helper for app `index.ts` entrypoints — wraps `createCli().parse()` in a try/catch
+ * that emits a structured error envelope and exits 1 on uncaught failures.
+ *
+ * @param input - The same builder configuration accepted by {@link createCli}.
+ * @returns Resolves once the parser has finished. Rejects only when `process.exit` is stubbed (e.g. in tests).
+ */
+export declare function runCli(input: CreateCliInput): Promise<void>;

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

@@ -0,0 +1,78 @@
+import type { Argv } from 'yargs';
+export interface EnvOptions {
+    readonly env?: string;
+}
+/**
+ * Adds the standard `--env <name>` option used by every per-env command.
+ *
+ * @param yargs - The yargs builder to extend.
+ * @returns The same yargs builder with the `--env` option chained on.
+ */
+export declare function withEnv<T>(yargs: Argv<T>): Argv<T & EnvOptions>;
+export interface OutputOptions {
+    readonly dumpDir?: string;
+    readonly pick?: string;
+    readonly pickAll?: boolean;
+}
+/**
+ * Adds the per-command output flag set: `--dump-dir`, `--pick`, and `--pick-all`.
+ *
+ * @param yargs - The yargs builder to extend.
+ * @returns The same yargs builder with the output options chained on.
+ */
+export declare function withOutput<T>(yargs: Argv<T>): Argv<T & OutputOptions>;
+/**
+ * Dump file format for {@link runPaginatedList} when `--dump-dir` is set.
+ *
+ * - `raw`: one full JSON page response (concatenated JSON when `--dump-merge=concat`, not standard JSON).
+ * - `page_by_line`: NDJSON with one page response per line.
+ * - `data_by_line`: NDJSON with one record per line.
+ */
+export declare const DUMP_OUTPUT_MODES: readonly ["raw", "page_by_line", "data_by_line"];
+export type DumpOutputMode = (typeof DUMP_OUTPUT_MODES)[number];
+/**
+ * Across-pages dump merge mode for {@link runPaginatedList}.
+ *
+ * - `replace`: truncate the file each iteration; only the last page survives.
+ * - `concat`: append each page to the file.
+ */
+export declare const DUMP_MERGE_MODES: readonly ["replace", "concat"];
+export type DumpMergeMode = (typeof DUMP_MERGE_MODES)[number];
+/**
+ * Stdout shape when `--multiple-pages > 1`.
+ *
+ * - `meta`: summary only (low memory).
+ * - `pages`: array of page responses (holds all pages in memory).
+ * - `merged_page`: concat all records into one array (holds all records in memory).
+ */
+export declare const MULTIPLE_PAGES_OUTPUT_MODES: readonly ["meta", "pages", "merged_page"];
+export type MultiplePagesOutputMode = (typeof MULTIPLE_PAGES_OUTPUT_MODES)[number];
+export interface MultiplePagesOptions {
+    readonly multiplePages: number;
+    readonly multiplePagesOutput: MultiplePagesOutputMode;
+    readonly dumpOutput: DumpOutputMode;
+    readonly dumpMerge: DumpMergeMode;
+}
+/**
+ * Adds the multi-page pagination flag set shared by every paginated list command.
+ *
+ * Compose from a CLI-specific page/offset builder (e.g. Zoho's `withPagination` adds
+ * `--page` / `--per-page`, then chains this for the multi-page controls).
+ *
+ * @param yargs - The yargs builder to extend.
+ * @returns The same yargs builder with the multi-page options chained on.
+ */
+export declare function withMultiplePages<T>(yargs: Argv<T>): Argv<T & MultiplePagesOptions>;
+export interface CallModelArgs {
+    readonly model: string;
+    readonly verb: string;
+    readonly specifier?: string;
+    readonly data?: string;
+}
+/**
+ * Adds the standard generic-call positional + flag set: `<model> <verb> [specifier]` plus `--data <json>`.
+ *
+ * @param yargs - The yargs builder to extend.
+ * @returns The same yargs builder with the model-call positionals and `--data` option chained on.
+ */
+export declare function withCallModelArgs<T>(yargs: Argv<T>): Argv<T & CallModelArgs>;