@dereekb/dbx-cli 13.11.0

package/src/lib/util/context.slot.d.ts

@@ -0,0 +1,50 @@
+import { type Maybe } from '@dereekb/util';
+/**
+ * Module-level slot for a single value of type `T`.
+ *
+ * Used to bridge yargs middleware (which assigns to argv) and command handlers (which read the
+ * value) without having to thread the context through `argv` (where yargs strict mode would flag
+ * unknown keys).
+ */
+export interface ContextSlot<T> {
+    /**
+     * Assigns the slot to `value` (or clears it if `null`/`undefined` is passed).
+     */
+    set(value: Maybe<T>): void;
+    /**
+     * Returns the current slot value, or `undefined` when unset.
+     */
+    get(): Maybe<T>;
+    /**
+     * Returns the current slot value, or throws when unset. Use this from command handlers that
+     * require the auth middleware to have run.
+     */
+    require(): T;
+}
+export interface CreateContextSlotInput {
+    /**
+     * Custom error message thrown by {@link ContextSlot.require} when the slot is unset. Defaults
+     * to a generic "context slot has not been initialized" message.
+     */
+    readonly notInitializedMessage?: string;
+}
+/**
+ * Creates a typed module-level slot.
+ *
+ * Each CLI exposes its current per-invocation context (auth tokens, API clients, env config, ...)
+ * via a slot so command handlers can read it without yargs strict-mode flagging unknown argv keys.
+ *
+ * Usage:
+ * ```ts
+ * const slot = createContextSlot<MyCliContext>({ notInitializedMessage: 'Auth middleware did not run.' });
+ * // in middleware:
+ * slot.set(buildContext(...));
+ * // in handler:
+ * const ctx = slot.require();
+ * ```
+ *
+ * @param input - Optional slot configuration.
+ * @param input.notInitializedMessage - Custom error message thrown by `require()` when the slot is unset.
+ * @returns A new {@link ContextSlot} for type `T`.
+ */
+export declare function createContextSlot<T>(input?: CreateContextSlotInput): ContextSlot<T>;

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

@@ -0,0 +1,13 @@
+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.
+ *
+ * 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.
+ * @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>;

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

@@ -0,0 +1,6 @@
+export * from './args';
+export * from './context.slot';
+export * from './handler';
+export * from './interactive';
+export * from './output';
+export * from './pagination';

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

@@ -0,0 +1,26 @@
+export interface PromptInput {
+    readonly question: string;
+    readonly mask?: boolean;
+}
+/**
+ * Error code thrown by {@link promptLine} when the user cancels a masked prompt with Ctrl-C.
+ *
+ * Callers that want to catch and handle cancellation should match on this code; otherwise the
+ * standard wrapCommandHandler / outputError envelope reports `code: 'PROMPT_CANCELLED'`.
+ */
+export declare const PROMPT_CANCELLED_ERROR_CODE = "PROMPT_CANCELLED";
+/**
+ * Reads a single line of input from stdin, optionally masking the typed characters.
+ *
+ * Used by `auth setup` to prompt for client secrets and by `auth login` to prompt for the
+ * pasted redirect URL.
+ *
+ * Rejects with a {@link CliError} (`code: 'PROMPT_CANCELLED'`) when the user presses Ctrl-C
+ * during a masked prompt, instead of forcibly terminating the process.
+ *
+ * @param input - The prompt inputs.
+ * @param input.question - The prompt text written to stdout (or stderr when masking).
+ * @param input.mask - When `true`, characters are echoed as `*` and Ctrl-C cancels the prompt.
+ * @returns The line entered by the user (without the trailing newline).
+ */
+export declare function promptLine(input: PromptInput): Promise<string>;

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

@@ -0,0 +1,152 @@
+import { type Maybe } from '@dereekb/util';
+export interface CliSuccessOutput<T = unknown> {
+    readonly ok: true;
+    readonly data: T;
+    readonly meta?: Record<string, unknown>;
+}
+export interface CliErrorOutput {
+    readonly ok: false;
+    readonly error: string;
+    readonly code: string;
+    readonly suggestion?: string;
+}
+export type CliOutput<T = unknown> = CliSuccessOutput<T> | CliErrorOutput;
+/**
+ * Configuration for response dumping and field filtering.
+ *
+ * Set via {@link configureOutputOptions} from global CLI flags.
+ */
+export interface CliOutputOptions {
+    readonly dumpDir?: string;
+    readonly pick?: string;
+    readonly commandPath?: string[];
+}
+/**
+ * Patterns that indicate a string may contain a secret token or credential.
+ */
+export type CliSecretPattern = RegExp;
+/**
+ * Default secret-redaction patterns. Covers OAuth bearer tokens, access/refresh tokens, and client secrets.
+ *
+ * Apps can extend this list via {@link configureCliSecretPatterns} to add provider-specific patterns
+ * (e.g. Zoho's `1000.<32-char>` token shape).
+ */
+export declare const DEFAULT_CLI_SECRET_PATTERNS: CliSecretPattern[];
+/**
+ * Optional mapper for converting consumer-specific exception types into a {@link CliErrorOutput} envelope.
+ *
+ * When set via {@link configureCliErrorMapper}, {@link buildErrorOutput} consults the mapper before falling
+ * back to the built-in `CliError` / `Error` / unknown branches. Returning `undefined` defers to the defaults.
+ */
+export type CliErrorMapper = (error: unknown) => Maybe<CliErrorOutput>;
+/**
+ * Configures output options from parsed CLI arguments.
+ *
+ * Call from middleware before any command handler runs.
+ *
+ * @param options - The resolved {@link CliOutputOptions} (dump dir, pick filter, command path).
+ */
+export declare function configureOutputOptions(options: CliOutputOptions): void;
+/**
+ * Returns the current process-wide {@link CliOutputOptions} previously set via
+ * {@link configureOutputOptions}.
+ *
+ * @returns The active output options (empty object when never configured).
+ */
+export declare function getOutputOptions(): CliOutputOptions;
+/**
+ * Replaces the active secret-redaction pattern list with the given patterns.
+ *
+ * Use to add provider-specific patterns. Pass `[...DEFAULT_CLI_SECRET_PATTERNS, ...extra]`
+ * to keep the defaults.
+ *
+ * @param patterns - The new pattern list applied by {@link sanitizeString}.
+ */
+export declare function configureCliSecretPatterns(patterns: CliSecretPattern[]): void;
+/**
+ * Registers a {@link CliErrorMapper} that {@link buildErrorOutput} consults before falling back
+ * to the built-in `CliError` / `Error` / unknown handling. Pass `undefined` to clear.
+ *
+ * Use to plug provider-specific exception types (e.g. Zoho's `ZohoInvalidTokenError`) into the
+ * standard error envelope without duplicating the rest of the formatting / secret-redaction pipeline.
+ *
+ * @param mapper - The mapper to install, or `undefined` to clear any previously registered mapper.
+ */
+export declare function configureCliErrorMapper(mapper?: CliErrorMapper): void;
+/**
+ * Applies the configured secret-redaction patterns to a string, replacing each match with `[REDACTED]`.
+ *
+ * @param value - The input string (typically an error message) to sanitize.
+ * @returns The sanitized string with secret-shaped substrings replaced.
+ */
+export declare function sanitizeString(value: string): string;
+/**
+ * Returns the current time as a filename-safe ISO-8601 stamp (`:` and `.` replaced with `-`).
+ *
+ * @returns The formatted timestamp string.
+ */
+export declare function dumpTimestamp(): string;
+/**
+ * Builds a dump-file absolute path inside the configured `dumpDir`.
+ *
+ * The filename combines the active command path (joined with `_`), the current
+ * {@link dumpTimestamp}, and the optional `suffix`. Returns `undefined` when no `dumpDir` is set.
+ *
+ * @param extension - File extension to append (`json` for full responses, `ndjson` for streaming dumps).
+ * @param suffix - Optional suffix appended to the filename before the extension.
+ * @returns The absolute file path, or `undefined` when `dumpDir` is not configured.
+ */
+export declare function buildDumpFilePath(extension: 'json' | 'ndjson', suffix?: string): Maybe<string>;
+/**
+ * Reduces an object (or array of objects) to the named top-level fields.
+ *
+ * @param data - The value to filter; arrays are mapped element-wise, objects are reduced to the picked keys, primitives pass through unchanged.
+ * @param pick - Comma-separated list of field names to keep.
+ * @returns The filtered value (typed as the input).
+ */
+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.
+ *
+ * @param data - The command result to emit.
+ * @param meta - Optional additional metadata to attach to the envelope.
+ */
+export declare function outputResult<T>(data: T, meta?: Record<string, unknown>): void;
+/**
+ * Prints a failed command result as a `{ ok: false, error, code, suggestion? }` JSON envelope on stdout.
+ *
+ * @param error - The thrown value to convert. Mapped via {@link buildErrorOutput} (which consults any registered {@link CliErrorMapper}).
+ */
+export declare function outputError(error: unknown): void;
+/**
+ * An error that carries a stable code and optional suggestion for the user.
+ *
+ * Throw from within commands to produce a structured `{ ok: false, code, suggestion }` envelope.
+ */
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly suggestion?: string;
+    constructor(input: {
+        readonly message: string;
+        readonly code: string;
+        readonly suggestion?: string;
+    });
+}
+/**
+ * Converts an arbitrary thrown value into a {@link CliErrorOutput} envelope.
+ *
+ * Order of resolution:
+ *   1. Any registered {@link CliErrorMapper} that returns a mapped envelope.
+ *   2. {@link CliError} instances (preserve `code` and optional `suggestion`).
+ *   3. Generic `Error` instances (`code: 'ERROR'`).
+ *   4. Unknown values (`code: 'UNKNOWN_ERROR'`, message stringified).
+ *
+ * Error messages are passed through {@link sanitizeString} so secret-shaped substrings are redacted.
+ *
+ * @param error - The thrown value to convert.
+ * @returns The structured {@link CliErrorOutput}.
+ */
+export declare function buildErrorOutput(error: unknown): CliErrorOutput;

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

@@ -0,0 +1,91 @@
+import { type Maybe } from '@dereekb/util';
+import { type DumpMergeMode, type DumpOutputMode, type MultiplePagesOutputMode } from './args';
+/**
+ * Minimal page response shape required by {@link runPaginatedList}.
+ *
+ * Engine consumers extend this with whatever provider-specific fields their adapter inspects
+ * (e.g. Zoho CRM/Recruit responses add `info.more_records`).
+ */
+export interface PaginatedResponse {
+    readonly data: readonly unknown[];
+}
+/**
+ * Adapter that hides the underlying API's pagination scheme (page-based, offset-based, cursor-based, etc.).
+ *
+ * Implementations build the next-page input, count records, and produce single-page meta.
+ */
+export interface PaginationAdapter<I, R extends PaginatedResponse> {
+    /**
+     * Returns the input for the next page, or `undefined` if no more pages exist.
+     */
+    nextInput(input: I, lastResult: R): Maybe<I>;
+    /**
+     * Number of records on this page.
+     */
+    countOf(result: R): number;
+    /**
+     * Meta object for single-page output (matches each command's prior meta shape).
+     */
+    metaOf(input: I, result: R): Record<string, unknown>;
+    /**
+     * Whether the response indicates more pages are available beyond this one.
+     */
+    hasMorePagesAvailable(input: I, result: R): boolean;
+}
+export interface StreamingDump {
+    readonly mainPath: Maybe<string>;
+    readonly pickPath: Maybe<string>;
+    writePage(result: PaginatedResponse): void;
+    close(): void;
+}
+export interface OpenStreamingDumpParams {
+    readonly dumpOutput: DumpOutputMode;
+    readonly dumpMerge: DumpMergeMode;
+}
+/**
+ * Opens a streaming dump writer that flushes each page to disk on `writePage(...)`.
+ *
+ * When `--pick` is configured, a parallel `_pick` file is also written with the pick filter
+ * applied to each record's `data` array. If no dump directory is configured, returns a no-op writer.
+ *
+ * @param params - Streaming dump configuration.
+ * @param params.dumpOutput - Per-page dump format (`raw`, `page_by_line`, or `data_by_line`).
+ * @param params.dumpMerge - Across-pages dump merge mode (`replace` truncates each iteration; `concat` appends).
+ * @returns The {@link StreamingDump} writer (a no-op when no `dumpDir` is configured).
+ */
+export declare function openStreamingDump(params: OpenStreamingDumpParams): StreamingDump;
+export interface RunPaginatedListParams<I, R extends PaginatedResponse> {
+    readonly initialInput: I;
+    readonly fetchPage: (input: I) => Promise<R>;
+    readonly adapter: PaginationAdapter<I, R>;
+    readonly multiplePages: number;
+    readonly multiplePagesOutput: MultiplePagesOutputMode;
+    readonly dumpOutput: DumpOutputMode;
+    readonly dumpMerge: DumpMergeMode;
+}
+export type RunPaginatedListOutcome<R extends PaginatedResponse> = {
+    readonly handled: false;
+    readonly result: R;
+} | {
+    readonly handled: true;
+};
+/**
+ * Runs a list command's fetch loop with multi-page streaming support.
+ *
+ * - When `multiplePages <= 1` returns `{ handled: false, result }`. The caller invokes its own
+ *   `outputResult(...)` to preserve the command's existing single-page meta shape exactly.
+ * - When `multiplePages > 1` loops up to `multiplePages` times (or until end-of-data), streams each
+ *   page to disk via {@link openStreamingDump}, prints a stdout response per `multiplePagesOutput`,
+ *   and returns `{ handled: true }`.
+ *
+ * @param params - The pagination loop inputs.
+ * @param params.initialInput - The first-page input passed to `fetchPage`.
+ * @param params.fetchPage - Callback that fetches a single page from the underlying API.
+ * @param params.adapter - Adapter that hides the API's pagination scheme (next-input, count, meta, has-more).
+ * @param params.multiplePages - Maximum number of pages to fetch in this invocation (1 = single-page passthrough).
+ * @param params.multiplePagesOutput - Stdout shape when looping (`meta`, `pages`, or `merged_page`).
+ * @param params.dumpOutput - Per-page dump format passed to {@link openStreamingDump}.
+ * @param params.dumpMerge - Across-pages dump merge mode passed to {@link openStreamingDump}.
+ * @returns `{ handled: false, result }` for single-page mode, otherwise `{ handled: true }` after the loop prints its own response.
+ */
+export declare function runPaginatedList<I, R extends PaginatedResponse>(params: RunPaginatedListParams<I, R>): Promise<RunPaginatedListOutcome<R>>;