@dereekb/dbx-cli 13.11.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@dereekb/dbx-cli",
+  "version": "13.11.0",
+  "sideEffects": false,
+  "peerDependencies": {
+    "@dereekb/firebase": "13.11.0",
+    "@dereekb/nestjs": "13.11.0",
+    "@dereekb/util": "13.11.0",
+    "arktype": "^2.2.0",
+    "yargs": "^18.0.0"
+  },
+  "devDependencies": {
+    "@types/yargs": "^17.0.35"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/src/index.d.ts

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

package/src/lib/api/call-model.client.d.ts

@@ -0,0 +1,37 @@
+import type { OnCallTypedModelParams } from '@dereekb/firebase';
+export declare const CALL_MODEL_API_PATH = "/model/call";
+export interface CallModelOverHttpInput<T = unknown> {
+    /**
+     * The API base URL — typically `<host>/<project>/us-central1/api` or `https://<domain>/api`.
+     *
+     * The `/model/call` path is appended automatically.
+     */
+    readonly apiBaseUrl: string;
+    readonly accessToken: string;
+    readonly params: OnCallTypedModelParams<T>;
+    /**
+     * Custom fetch implementation for tests.
+     */
+    readonly fetcher?: typeof fetch;
+}
+export interface CallModelOverHttpResponse<R = unknown> {
+    readonly status: number;
+    readonly body: R;
+}
+/**
+ * Posts a typed model call to `<apiBaseUrl>/model/call` with a Bearer access token and parses the JSON response.
+ *
+ * Maps non-2xx responses to a {@link CliError} with a stable code derived from the status — this lets the
+ * error envelope downstream emit a sensible suggestion.
+ *
+ * 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>;
+export { CALL_MODEL_APP_FUNCTION_KEY } from '@dereekb/firebase';

package/src/lib/api/call-model.command.factory.d.ts

@@ -0,0 +1,42 @@
+import type { Argv, CommandModule } from 'yargs';
+export interface CallModelCommandSpec<TParams = unknown, TResult = unknown> {
+    /**
+     * The yargs command string (e.g. `'profile read username <value>'`).
+     */
+    readonly command: string;
+    readonly describe: string;
+    /**
+     * The Firestore model type (e.g. `'profile'`).
+     */
+    readonly model: string;
+    /**
+     * The CRUD verb (`'create' | 'read' | 'update' | 'delete' | 'query'`) or a custom action type.
+     */
+    readonly verb: string;
+    /**
+     * Optional sub-function specifier (e.g. `'username'`).
+     */
+    readonly specifier?: string;
+    /**
+     * Optional yargs option/positional builder for the command.
+     */
+    readonly builder?: (yargs: Argv) => Argv;
+    /**
+     * Maps the parsed argv to the typed call payload.
+     */
+    readonly buildParams: (argv: any) => TParams;
+    /**
+     * Optional transform applied before printing the result envelope.
+     */
+    readonly mapResult?: (result: TResult) => unknown;
+}
+/**
+ * Builder primitive: turns a {@link CallModelCommandSpec} into a yargs `CommandModule`.
+ *
+ * The handler reads the {@link CliContext} (built by the auth middleware), constructs the
+ * {@link OnCallTypedModelParams} envelope, and executes via `context.callModel(...)`.
+ *
+ * @param spec - The command spec describing the yargs command surface plus how to map argv into the typed call params and the result.
+ * @returns A yargs `CommandModule` whose handler runs the spec against the active CLI context.
+ */
+export declare function createCallModelCommand<TParams = unknown, TResult = unknown>(spec: CallModelCommandSpec<TParams, TResult>): CommandModule;

package/src/lib/api/call.passthrough.command.d.ts

@@ -0,0 +1,8 @@
+import type { CommandModule } from 'yargs';
+/**
+ * Generic `call <model> <verb> [specifier] --data <json>` passthrough.
+ *
+ * Provides direct access to the demo-api's typed model dispatch without typed wrappers — useful
+ * for ad-hoc admin tasks, scripting, and the MVP demo CLI before model-specific commands ship.
+ */
+export declare const callPassthroughCommand: CommandModule;

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

@@ -0,0 +1,3 @@
+export * from './call-model.client';
+export * from './call-model.command.factory';
+export * from './call.passthrough.command';

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

@@ -0,0 +1,29 @@
+import type { CommandModule } from 'yargs';
+import { type CliEnvDefault } from '../config/env';
+export interface CreateAuthCommandInput {
+    readonly cliName: string;
+    /**
+     * The env var name used to resolve the active env when no flag is provided.
+     *
+     * Conventionally `<CLINAME>_ENV` (e.g. `DEMO_CLI_ENV`).
+     */
+    readonly envVarName?: string;
+    /**
+     * Built-in env presets. Merged underneath the user's stored env when the env name matches.
+     */
+    readonly defaultEnvs?: readonly CliEnvDefault[];
+}
+/**
+ * Factory for the built-in `auth` command tree.
+ *
+ * Wires `setup`, `login`, `logout`, `status`, `show`, and `check` subcommands that drive the OIDC
+ * PKCE flow against the active env, persist tokens via the per-CLI token cache, and print a
+ * structured envelope.
+ *
+ * @param input - Factory configuration.
+ * @param input.cliName - The CLI's binary name. Used for the per-user config dir, env-var prefix, and error messages.
+ * @param input.envVarName - Override for the env-name env var. Defaults to `<CLINAME>_ENV` (e.g. `DEMO_CLI_ENV`).
+ * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
+ * @returns A yargs `CommandModule` exposing the full `auth` subcommand surface.
+ */
+export declare function createAuthCommand(input: CreateAuthCommandInput): CommandModule;

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

@@ -0,0 +1,3 @@
+export * from './auth.command.factory';
+export * from './oidc.client';
+export * from './oidc.flow';

package/src/lib/auth/oidc.client.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The subset of fields we read from an OIDC discovery document.
+ *
+ * The CLI only uses the authorization, token, userinfo, and revocation endpoints to drive
+ * the authorization-code-with-PKCE flow.
+ */
+export interface OidcDiscoveryMetadata {
+    readonly issuer: string;
+    readonly authorization_endpoint: string;
+    readonly token_endpoint: string;
+    readonly userinfo_endpoint?: string;
+    readonly revocation_endpoint?: string;
+    readonly end_session_endpoint?: string;
+    readonly jwks_uri?: string;
+    readonly scopes_supported?: string[];
+}
+/**
+ * Token response from a successful `authorization_code` or `refresh_token` exchange.
+ */
+export interface OidcTokenResponse {
+    readonly access_token: string;
+    readonly token_type?: string;
+    readonly expires_in?: number;
+    readonly refresh_token?: string;
+    readonly id_token?: string;
+    readonly scope?: string;
+}
+export interface DiscoverOidcMetadataInput {
+    readonly issuer: string;
+    /**
+     * Optional sibling base URL to try after the issuer-prefixed and origin-rooted paths.
+     *
+     * Useful when the discovery doc is served at `<api-base-url>/.well-known/openid-configuration`
+     * — e.g. when the issuer is reached via a different host than the API and the origin-rooted
+     * candidate would target the wrong host.
+     */
+    readonly fallbackBaseUrl?: string;
+}
+/**
+ * Fetches the OIDC discovery document for the given issuer, trying these candidates in order:
+ *
+ *   1. `<issuer>/.well-known/openid-configuration` (OpenID Connect Discovery 1.0).
+ *   2. `<issuer-origin>/.well-known/openid-configuration` (host-rooted; matches projects that
+ *      mount the discovery controller at the API/dev-server root rather than under the issuer
+ *      sub-path — e.g. demo's `OidcWellKnownController`).
+ *   3. `<fallbackBaseUrl>/.well-known/openid-configuration` when supplied and not already covered.
+ *
+ * @param input - The discovery request.
+ * @param input.issuer - The OIDC issuer URL whose `.well-known/openid-configuration` is fetched first.
+ * @param input.fallbackBaseUrl - Optional sibling base URL tried after the issuer-prefixed and origin-rooted candidates.
+ * @returns The parsed {@link OidcDiscoveryMetadata}. Throws a {@link CliError} (`OIDC_DISCOVERY_FAILED`) when every candidate fails.
+ */
+export declare function discoverOidcMetadata(input: DiscoverOidcMetadataInput): Promise<OidcDiscoveryMetadata>;
+export interface ExchangeAuthorizationCodeInput {
+    readonly tokenEndpoint: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly redirectUri: string;
+    readonly code: string;
+    readonly codeVerifier: string;
+}
+/**
+ * Exchanges an authorization code (from the redirect) for an access token + refresh token.
+ *
+ * Uses `client_secret_post` auth — the demo's oidc-provider config registers clients with that method.
+ *
+ * @param input - The token exchange parameters.
+ * @param input.tokenEndpoint - The OIDC token endpoint URL discovered from the issuer.
+ * @param input.clientId - The OAuth client ID.
+ * @param input.clientSecret - The OAuth client secret used for `client_secret_post` auth.
+ * @param input.redirectUri - The redirect URI registered with the OAuth client (must match the value used when requesting the code).
+ * @param input.code - The authorization code returned to the redirect URI.
+ * @param input.codeVerifier - The PKCE code verifier originally paired with the code challenge in the authorization request.
+ * @returns The parsed {@link OidcTokenResponse} with access/refresh tokens.
+ */
+export declare function exchangeAuthorizationCode(input: ExchangeAuthorizationCodeInput): Promise<OidcTokenResponse>;
+export interface RefreshAccessTokenInput {
+    readonly tokenEndpoint: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly refreshToken: string;
+}
+/**
+ * Exchanges a refresh token for a new access token (and possibly a rotated refresh token).
+ *
+ * @param input - The refresh request.
+ * @param input.tokenEndpoint - The OIDC token endpoint URL discovered from the issuer.
+ * @param input.clientId - The OAuth client ID.
+ * @param input.clientSecret - The OAuth client secret used for `client_secret_post` auth.
+ * @param input.refreshToken - The cached refresh token to redeem.
+ * @returns The parsed {@link OidcTokenResponse} with the refreshed access token.
+ */
+export declare function refreshAccessToken(input: RefreshAccessTokenInput): Promise<OidcTokenResponse>;
+export interface RevokeTokenInput {
+    readonly revocationEndpoint: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly token: string;
+    readonly tokenTypeHint?: 'access_token' | 'refresh_token';
+}
+/**
+ * Revokes an access or refresh token at the OIDC revocation endpoint.
+ *
+ * @param input - The revocation request.
+ * @param input.revocationEndpoint - The OIDC revocation endpoint URL.
+ * @param input.clientId - The OAuth client ID used for `client_secret_post` auth.
+ * @param input.clientSecret - The OAuth client secret used for `client_secret_post` auth.
+ * @param input.token - The access or refresh token to revoke.
+ * @param input.tokenTypeHint - Optional hint passed as `token_type_hint` (`access_token` or `refresh_token`).
+ * @returns Resolves when the server returns a non-error status. Throws a {@link CliError} (`TOKEN_REVOCATION_FAILED`) on error.
+ */
+export declare function revokeToken(input: RevokeTokenInput): Promise<void>;
+export interface FetchUserInfoInput {
+    readonly userinfoEndpoint: string;
+    readonly accessToken: string;
+}
+/**
+ * Fetches the OIDC `userinfo` endpoint and returns the parsed claims object.
+ *
+ * @param input - The userinfo request.
+ * @param input.userinfoEndpoint - The OIDC userinfo endpoint URL discovered from the issuer.
+ * @param input.accessToken - The Bearer access token sent in the `Authorization` header.
+ * @returns The parsed userinfo claims. Throws a {@link CliError} (`USERINFO_FAILED`) on a non-OK response.
+ */
+export declare function fetchUserInfo(input: FetchUserInfoInput): Promise<Record<string, unknown>>;

package/src/lib/auth/oidc.flow.d.ts

@@ -0,0 +1,79 @@
+import { type Maybe } from '@dereekb/util';
+export interface BuildAuthorizationUrlInput {
+    readonly authorizationEndpoint: string;
+    /**
+     * Optional API base URL. When set and `appClientUrl` is not provided, the CLI sends the user
+     * to `<apiBaseUrl>/oidc/login/client?<params>` instead of the raw authorization endpoint. The
+     * API redirects to the configured app login URL with the OAuth query string preserved, so the
+     * CLI does not need to know the client origin directly.
+     */
+    readonly apiBaseUrl?: Maybe<string>;
+    /**
+     * Optional client (frontend) origin to rebase the authorization endpoint onto.
+     *
+     * When set, the path + search of `authorizationEndpoint` are kept and the origin is replaced
+     * with this URL. Useful when the frontend dev server proxies `/oidc/**` to the API and the
+     * user-facing URL should target the app, not the API directly. Takes precedence over
+     * `apiBaseUrl` when both are provided.
+     */
+    readonly appClientUrl?: Maybe<string>;
+    readonly clientId: string;
+    readonly redirectUri: string;
+    readonly scopes?: string;
+    readonly state: string;
+    readonly codeChallenge: string;
+}
+/**
+ * Builds the authorization URL the user opens in a browser to start the PKCE flow.
+ *
+ * Resolves the user-facing endpoint by preferring `appClientUrl` (rebases the discovered
+ * authorization endpoint onto that origin) over `apiBaseUrl` (`/oidc/login/client` shortcut),
+ * and finally falls back to the discovered `authorizationEndpoint` itself.
+ *
+ * @param input - The authorization URL inputs.
+ * @param input.authorizationEndpoint - The authorization endpoint discovered from OIDC metadata.
+ * @param input.apiBaseUrl - Optional API base URL; when set without `appClientUrl`, the URL is built against `<apiBaseUrl>/oidc/login/client`.
+ * @param input.appClientUrl - Optional frontend origin to rebase the authorization endpoint onto. Takes precedence over `apiBaseUrl`.
+ * @param input.clientId - The OAuth client ID.
+ * @param input.redirectUri - The redirect URI registered with the OAuth client.
+ * @param input.scopes - Space-separated scope list. Defaults to {@link DEFAULT_CLI_OIDC_SCOPES}.
+ * @param input.state - The opaque OAuth state token used for CSRF protection.
+ * @param input.codeChallenge - The PKCE code challenge derived from the verifier.
+ * @returns The full authorization URL with all OAuth params merged in.
+ */
+export declare function buildAuthorizationUrl(input: BuildAuthorizationUrlInput): string;
+export interface PkceMaterial {
+    readonly codeVerifier: string;
+    readonly codeChallenge: string;
+}
+/**
+ * Generates a fresh PKCE code verifier and the matching SHA-256 code challenge.
+ *
+ * @returns A {@link PkceMaterial} pair consisting of the random `codeVerifier` and its derived `codeChallenge`.
+ */
+export declare function generatePkceMaterial(): Promise<PkceMaterial>;
+/**
+ * Generates a random URL-safe state value for the OAuth state parameter.
+ *
+ * @returns A 32-character hex string derived from 16 random bytes.
+ */
+export declare function generateOAuthState(): string;
+export interface ParsePastedRedirectInput {
+    readonly pasted: string;
+    readonly expectedState?: string;
+}
+export interface ParsedRedirect {
+    readonly code: string;
+    readonly state?: string;
+}
+/**
+ * Parses an authorization code out of a pasted redirect URL or a bare code string.
+ *
+ * Validates the `state` parameter when an expected value is provided.
+ *
+ * @param input - The parse inputs.
+ * @param input.pasted - The redirect URL or bare authorization code pasted by the user.
+ * @param input.expectedState - Optional state value to assert against `state` when present in the URL.
+ * @returns The {@link ParsedRedirect} containing `code` and (when present) `state`.
+ */
+export declare function parsePastedRedirect(input: ParsePastedRedirectInput): ParsedRedirect;

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

@@ -0,0 +1,112 @@
+import { type Maybe } from '@dereekb/util';
+import { type CliEnvConfig } from './env';
+/**
+ * Output settings that can be applied per-command.
+ */
+export interface CliCommandOutputConfig {
+    readonly dumpDir?: string;
+    readonly pick?: string;
+}
+/**
+ * Output configuration with global defaults and optional per-command overrides.
+ *
+ * Command keys use dot-separated paths matching the yargs command hierarchy
+ * (e.g. `call.profile.read`).
+ */
+export interface CliOutputConfig extends CliCommandOutputConfig {
+    readonly commands?: Record<string, CliCommandOutputConfig>;
+}
+/**
+ * The persisted shape of `<configDir>/config.json`.
+ */
+export interface CliConfig {
+    readonly activeEnv?: string;
+    readonly envs?: Record<string, CliEnvConfig>;
+    readonly output?: CliOutputConfig;
+}
+export interface LoadCliConfigInput {
+    readonly configFilePath: string;
+}
+/**
+ * Loads the persisted CLI config from disk. Returns `undefined` when the file is missing.
+ *
+ * @param input - The load inputs.
+ * @param input.configFilePath - Absolute path to the JSON config file.
+ * @returns The parsed {@link CliConfig}, or `undefined` when the file does not exist.
+ */
+export declare function loadCliConfig(input: LoadCliConfigInput): Promise<Maybe<CliConfig>>;
+export interface SaveCliConfigInput extends LoadCliConfigInput {
+    readonly configDir: string;
+    readonly config: CliConfig;
+}
+/**
+ * Writes the full {@link CliConfig} to disk, creating the parent directory if needed.
+ *
+ * @param input - The save inputs.
+ * @param input.configFilePath - Absolute path to the JSON config file.
+ * @param input.configDir - Absolute path to the config directory (created if missing).
+ * @param input.config - The full config object to persist.
+ * @returns Resolves once the file has been written.
+ */
+export declare function saveCliConfig(input: SaveCliConfigInput): Promise<void>;
+export interface MergeCliConfigInput extends Omit<SaveCliConfigInput, 'config'> {
+    readonly updates: Partial<CliConfig>;
+}
+/**
+ * Merges updates into the existing config and saves to disk.
+ *
+ * `envs` is shallow-merged so a partial env update preserves existing keys for other envs.
+ * `output` is merged via {@link mergeOutputConfig}.
+ *
+ * @param input - The merge inputs.
+ * @param input.configFilePath - Absolute path to the JSON config file.
+ * @param input.configDir - Absolute path to the config directory (created if missing).
+ * @param input.updates - The partial {@link CliConfig} to merge on top of the existing on-disk config.
+ * @returns The merged {@link CliConfig} that was just written.
+ */
+export declare function mergeCliConfig(input: MergeCliConfigInput): Promise<CliConfig>;
+/**
+ * Merges a partial {@link CliOutputConfig} update on top of an existing config slice.
+ *
+ * Exported so downstream CLIs that nest the output config under a different config tree (e.g.
+ * zoho-cli's `shared/recruit/crm/desk/output` shape) can reuse the same merge semantics for the
+ * output sub-tree without forking the implementation.
+ *
+ * @param existing - The existing output config slice (or `null`/`undefined` if none was stored).
+ * @param updates - The partial output config to merge on top.
+ * @returns The merged {@link CliOutputConfig}.
+ */
+export declare function mergeOutputConfig(existing: Maybe<CliOutputConfig>, updates: CliOutputConfig): CliOutputConfig;
+export interface ResolveOutputConfigInput {
+    readonly outputConfig: Maybe<CliOutputConfig>;
+    readonly commandPath: string[];
+    readonly cliFlags: {
+        dumpDir?: string;
+        pick?: string;
+    };
+}
+/**
+ * Resolves output settings for a given command path.
+ *
+ * Resolution order (highest priority first):
+ *   1. CLI flags (dumpDir, pick from argv)
+ *   2. Per-command config (output.commands["call.profile.read"])
+ *   3. Global output config (output.dumpDir, output.pick)
+ *
+ * @param input - The resolution inputs.
+ * @param input.outputConfig - The persisted {@link CliOutputConfig} (or `null`/`undefined`).
+ * @param input.commandPath - The yargs command-path segments (joined with `.` to look up per-command overrides).
+ * @param input.cliFlags - Per-invocation overrides parsed from argv.
+ * @returns The resolved `dumpDir` / `pick` pair to apply for this command.
+ */
+export declare function resolveOutputConfig(input: ResolveOutputConfigInput): {
+    dumpDir?: string;
+    pick?: string;
+};
+/**
+ * Masks a secret string by keeping the first 4 chars and replacing the rest with `***`.
+ *
+ * @param value - The string to mask. `null`/`undefined` are returned unchanged.
+ * @returns The masked string (`***` when the input is 4 chars or shorter), or the input unchanged when nullish.
+ */
+export declare function maskSecret(value: Maybe<string>): Maybe<string>;

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

@@ -0,0 +1,183 @@
+import { type Maybe } from '@dereekb/util';
+/**
+ * The default OAuth/OIDC scopes requested by the CLI when none are configured.
+ */
+export declare const DEFAULT_CLI_OIDC_SCOPES = "openid profile email";
+/**
+ * The `model.*` write scopes filtered out by {@link filterReadOnlyModelScopes}.
+ *
+ * Mirrors the write half of the dbx-components callModel CRUD scope set
+ * (`CALL_MODEL_OIDC_SCOPES` in `@dereekb/firebase-server/oidc`) — duplicated here so the
+ * CLI doesn't take a server-side dependency just to know the names.
+ */
+export declare const MODEL_WRITE_OIDC_SCOPES: readonly ["model.create", "model.update", "model.delete"];
+/**
+ * Returns the input scope string with the `model.create`, `model.update`, and `model.delete`
+ * scopes removed, preserving every other scope (including `model.read` and `model.query`).
+ *
+ * Drives the `auth login --read-only-scopes` flag: when a CLI's env defaults request the
+ * full callModel CRUD scope set, this trims the request down to read/query only.
+ *
+ * @param scopes - Space-separated scope list, or `undefined` to filter the default scopes.
+ * @returns The filtered space-separated scope list.
+ */
+export declare function filterReadOnlyModelScopes(scopes: Maybe<string>): string;
+/**
+ * A built-in env config preset shipped with a CLI app.
+ *
+ * Each preset is addressable by one or more {@link names} (so e.g. `dev` and `local` can resolve
+ * to the same default). Values from the user's persisted env shadow these defaults; missing fields
+ * fall back to the default.
+ */
+export interface CliEnvDefault {
+    /**
+     * Names this default config is addressable by. Each name must be unique across the registered
+     * defaults — an env name resolves to at most one default.
+     */
+    readonly names: readonly string[];
+    /**
+     * The default config values. Any field can be omitted; the user's stored env (and env-var
+     * overrides) shadow these values at resolution time.
+     */
+    readonly env: Partial<CliEnvConfig>;
+}
+/**
+ * Returns the {@link CliEnvDefault} whose `names` includes the given env name, or `undefined`.
+ */
+export interface FindCliEnvDefaultInput {
+    readonly name: string;
+    readonly defaults?: readonly CliEnvDefault[];
+}
+/**
+ * Returns the {@link CliEnvDefault} whose `names` includes the given env name, or `undefined`.
+ *
+ * @param input - The lookup inputs.
+ * @param input.name - The env name to look up.
+ * @param input.defaults - The list of registered defaults to search.
+ * @returns The matching {@link CliEnvDefault}, or `undefined` when no default registers `name`.
+ */
+export declare function findCliEnvDefault(input: FindCliEnvDefaultInput): Maybe<CliEnvDefault>;
+/**
+ * Merges a stored env on top of a default env. User-set fields take precedence; empty strings are
+ * treated as "not set" so that an `env add <name>` call that didn't pass `--api-base-url` still
+ * picks up the default.
+ */
+export interface MergeCliEnvWithDefaultInput {
+    readonly env?: Maybe<CliEnvConfig>;
+    readonly defaultEnv?: Maybe<Partial<CliEnvConfig>>;
+}
+/**
+ * Merges a stored env on top of a default env, treating empty strings on either side as "not set".
+ *
+ * @param input - The merge inputs.
+ * @param input.env - The user's persisted env config (or `null`/`undefined`).
+ * @param input.defaultEnv - The matching {@link CliEnvDefault}'s partial env values, if any.
+ * @returns The merged {@link CliEnvConfig}, or `undefined` when both inputs are empty.
+ */
+export declare function mergeCliEnvWithDefault(input: MergeCliEnvWithDefaultInput): Maybe<CliEnvConfig>;
+/**
+ * Environment-targeting config for a CLI invocation.
+ *
+ * Each env (e.g. `local`, `staging`, `prod`) holds the API base URL plus the OIDC client
+ * registration the user copied from the target app's web UI. Tokens are cached separately
+ * (see {@link CliTokenEntry}).
+ *
+ * The term "env" is used instead of "profile" to avoid colliding with the demo's
+ * `Profile` Firestore model — so user-facing flags read `--env local`, not `--profile local`.
+ */
+export interface CliEnvConfig {
+    /**
+     * The base URL for the API. The CLI POSTs `<apiBaseUrl>/model/call` for the callModel passthrough.
+     */
+    readonly apiBaseUrl: string;
+    /**
+     * The OIDC issuer URL — typically the OIDC controller mount under the API.
+     *
+     * The CLI fetches `<oidcIssuer>/.well-known/openid-configuration` first (per RFC 8414) and
+     * falls back to `<apiBaseUrl>/.well-known/openid-configuration` if the issuer-prefixed path
+     * is not served.
+     */
+    readonly oidcIssuer: string;
+    /**
+     * Optional base URL for the app's client (frontend). When set, the CLI rebases the discovered
+     * `authorization_endpoint` onto this origin so the user is sent to the frontend (which proxies
+     * `/oidc/**` to the backend) instead of being sent directly to the API.
+     *
+     * Useful in local development where the API runs on a separate port from the frontend
+     * dev server. In production, leave this unset when the API and frontend share an origin.
+     */
+    readonly appClientUrl?: string;
+    /**
+     * The OAuth client ID registered with the target app.
+     */
+    readonly clientId?: string;
+    /**
+     * The OAuth client secret registered with the target app.
+     */
+    readonly clientSecret?: string;
+    /**
+     * The redirect URI registered with the OAuth client. The CLI does not bind a server — it parses
+     * the URL the user pastes back, so this can be any value the OIDC provider accepts as a
+     * registered redirect URI (e.g. `http://127.0.0.1:0/callback` or another loopback/placeholder URL).
+     */
+    readonly redirectUri?: string;
+    /**
+     * Space-separated OAuth scopes to request. Defaults to {@link DEFAULT_CLI_OIDC_SCOPES}.
+     */
+    readonly scopes?: string;
+}
+/**
+ * Resolves the active env name from a flag, env-var, or the persisted config default.
+ *
+ * Resolution order:
+ *   1. CLI `--env` flag
+ *   2. `<CLINAME>_ENV` environment variable
+ *   3. The `activeEnv` field in the persisted config
+ */
+export interface ResolveActiveEnvInput {
+    readonly flagEnv?: string;
+    readonly envVarName: string;
+    readonly defaultEnv?: string;
+}
+/**
+ * Resolves the active env name from a flag, env var, or persisted default.
+ *
+ * @param input - The resolution inputs.
+ * @param input.flagEnv - The value passed via `--env` (highest priority).
+ * @param input.envVarName - The name of the `<CLINAME>_ENV` env var to consult.
+ * @param input.defaultEnv - The persisted `activeEnv` from the config (lowest priority).
+ * @returns The first non-empty value among the inputs, or `undefined` when none is set.
+ */
+export declare function resolveActiveEnvName(input: ResolveActiveEnvInput): Maybe<string>;
+/**
+ * Applies env-var overrides on top of a stored {@link CliEnvConfig}.
+ *
+ * The conventional env vars for a CLI named `demo-cli` are:
+ *   - `DEMO_CLI_API_BASE_URL`
+ *   - `DEMO_CLI_OIDC_ISSUER`
+ *   - `DEMO_CLI_APP_CLIENT_URL`
+ *   - `DEMO_CLI_CLIENT_ID`
+ *   - `DEMO_CLI_CLIENT_SECRET`
+ *   - `DEMO_CLI_REDIRECT_URI`
+ *   - `DEMO_CLI_SCOPES`
+ */
+export interface EnvVarOverrideInput {
+    readonly cliName: string;
+    readonly env: Maybe<CliEnvConfig>;
+}
+/**
+ * Reads `<CLINAME_PREFIX>_*` env vars and overlays them on top of the stored env.
+ *
+ * @param input - The override inputs.
+ * @param input.cliName - The CLI name (used to derive the env-var prefix; e.g. `demo-cli` → `DEMO_CLI`).
+ * @param input.env - The base {@link CliEnvConfig} to overlay env-var values on top of.
+ * @returns The merged {@link CliEnvConfig}, or `undefined` when both the stored env and every override are empty.
+ */
+export declare function applyEnvVarOverrides(input: EnvVarOverrideInput): Maybe<CliEnvConfig>;
+/**
+ * Returns true when the env has the minimum fields needed to attempt an OAuth login or token refresh.
+ *
+ * @param env - The env config to check.
+ * @returns `true` when `apiBaseUrl`, `oidcIssuer`, `clientId`, `clientSecret`, and `redirectUri` are all present and non-empty.
+ */
+export declare function isCliEnvConfigComplete(env: Maybe<CliEnvConfig>): env is Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'clientSecret' | 'redirectUri'>> & CliEnvConfig;

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

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