@lovrabet/cli-framework 0.1.1-beta.0

package/lib/framework/output.js

@@ -0,0 +1,354 @@
+/**
+ * @fileoverview Output formatting pipeline.
+ *
+ * Renders a {@link CommandResult} to stdout in one of three modes:
+ * - `json`    — Full indented JSON envelope.
+ * - `compress` — Single-line JSON envelope (default).
+ * - `pretty`  — Human-readable plain-text layout.
+ *
+ * Supports `--jq` post-filtering in `json` / `compress` modes via the
+ * bundled `node-jq` executable (or a `jq` binary on PATH).
+ */
+import chalk from "chalk";
+import { createJqFilter } from "../utils/apply-jq-filter.js";
+import { createCliErrors } from "../errors.js";
+const applyJqFilter = createJqFilter(createCliErrors({
+    cliBinName: "cli",
+    authRequiredHint: "",
+    configMissingHint: "",
+    notInProjectHint: "",
+}));
+/**
+ * Central formatting entry point used by the runner adapter.
+ *
+ * Dispatches to the appropriate internal printer based on `options.format`:
+ * - `"json"`     → {@link printJson}
+ * - `"compress"` → {@link printCompress}
+ * - `"pretty"`   → {@link printPretty}
+ *
+ * All output is written to stdout. Errors are written to stderr.
+ *
+ * @param result  - The command result to render.
+ * @param options - Formatting options including format, command label, risk, and jq filter.
+ *
+ * @example
+ * ```ts
+ * formatOutput({ ok: true, data: { id: 1 } }, { command: "app list", risk: "read", format: "compress" });
+ * ```
+ */
+export function formatOutput(result, options) {
+    switch (options.format) {
+        case "json":
+            printJson(result, options);
+            break;
+        case "compress":
+            printCompress(result, options);
+            break;
+        case "pretty":
+        default:
+            printPretty(result, options);
+            break;
+    }
+}
+/**
+ * Wraps the command result in an {@link OutputEnvelope} by merging the
+ * command metadata from `options` and the result data / error.
+ *
+ * @template T - Type of the result data payload.
+ * @param result  - The command result to wrap.
+ * @param options - Output options providing command, risk, and dry-run flag.
+ * @returns A fully populated output envelope ready for JSON serialization.
+ */
+function buildEnvelope(result, options) {
+    const envelope = {
+        ok: result.ok,
+        command: options.command,
+        risk: options.risk,
+    };
+    if (options.dryRun)
+        envelope.dryRun = true;
+    if (result.data !== undefined)
+        envelope.data = result.data;
+    if (!result.ok && result.message) {
+        envelope.error = { code: "command_error", message: result.message };
+    }
+    return envelope;
+}
+/**
+ * Formats and prints the result as pretty-printed (2-space indent) JSON.
+ * Applies the `--jq` filter if `options.jqFilter` is set.
+ *
+ * @param result  - The command result to serialize.
+ * @param options - Output options including jq filter.
+ */
+function printJson(result, options) {
+    writeJsonWithOptionalJq(`${JSON.stringify(buildEnvelope(result, options), null, 2)}\n`, options);
+}
+/**
+ * Formats and prints the result as single-line (compact) JSON.
+ * Applies the `--jq` filter if `options.jqFilter` is set.
+ *
+ * @param result  - The command result to serialize.
+ * @param options - Output options including jq filter.
+ */
+function printCompress(result, options) {
+    writeJsonWithOptionalJq(`${JSON.stringify(buildEnvelope(result, options))}\n`, options);
+}
+/**
+ * Writes a JSON string to stdout, optionally piping it through `jq`.
+ *
+ * @param jsonLine - Complete JSON line (must end with `\n`).
+ * @param options  - Output options carrying the jq expression.
+ */
+function writeJsonWithOptionalJq(jsonLine, options) {
+    const expr = options.jqFilter?.trim();
+    if (!expr) {
+        process.stdout.write(jsonLine);
+        return;
+    }
+    const out = applyJqFilter(jsonLine, expr);
+    process.stdout.write(out.endsWith("\n") ? out : `${out}\n`);
+}
+/**
+ * Formats and prints the result as human-readable plain text.
+ * Handles special data shapes (`ListWithMetaData`, `ListEnvelope`, arrays,
+ * objects, scalars) with appropriate visual treatments.
+ *
+ * @param result  - The command result to render.
+ * @param options - Output options.
+ */
+function printPretty(result, options) {
+    if (options.dryRun) {
+        console.log("[dry-run] Would execute:");
+        console.log(JSON.stringify(result.data, null, 2));
+        return;
+    }
+    if (!result.ok) {
+        console.error(`Error: ${result.message ?? "Unknown error"}`);
+        return;
+    }
+    const data = result.data;
+    if (data === undefined || data === null) {
+        if (result.message)
+            console.log(result.message);
+        return;
+    }
+    if (isListWithMetaData(data)) {
+        printAppListMeta(data.meta);
+        printArrayPretty(data.items, { appListHighlight: true });
+        return;
+    }
+    if (isListEnvelope(data)) {
+        printListEnvelopePretty(data);
+        return;
+    }
+    if (Array.isArray(data)) {
+        printArrayPretty(data);
+        return;
+    }
+    if (typeof data === "object") {
+        printObjectPretty(data);
+        return;
+    }
+    console.log(String(data));
+}
+/**
+ * Type guard for the `{ items: unknown[]; meta: Record<string, unknown> }` shape
+ * used by app-list commands.
+ *
+ * @param data - Value to test.
+ */
+function isListWithMetaData(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        "items" in data &&
+        Array.isArray(data.items) &&
+        "meta" in data &&
+        typeof data.meta === "object" &&
+        data.meta !== null);
+}
+/**
+ * Type guard for the `{ items: unknown[]; [key: string]: unknown }` shape
+ * used by list commands that include extra summary fields.
+ *
+ * @param data - Value to test.
+ */
+function isListEnvelope(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        "items" in data &&
+        Array.isArray(data.items));
+}
+/**
+ * Prints the metadata block for app-list output in pretty mode.
+ * Switches between "scope" mode (single config path) and "dual" mode
+ * (separate global/project paths with default-app annotation).
+ *
+ * @param meta - Metadata object with config paths and default-app info.
+ */
+function printAppListMeta(meta) {
+    if (meta.scope) {
+        const cp = meta.configPath != null ? String(meta.configPath) : "(none)";
+        console.log(`  Scope:    ${String(meta.scope)}`);
+        console.log(`  Config:   ${cp}`);
+        console.log();
+        return;
+    }
+    const gp = meta.globalPath != null ? String(meta.globalPath) : "(none)";
+    const pp = meta.projectPath != null ? String(meta.projectPath) : "(none)";
+    const def = meta.defaultApp != null ? String(meta.defaultApp) : "(none)";
+    const src = meta.defaultAppSource;
+    const defSuffix = src === "project"
+        ? " (default from project file)"
+        : src === "global"
+            ? " (default from global file)"
+            : "";
+    console.log(`  Global config:   ${gp}`);
+    console.log(`  Project config:  ${pp}`);
+    console.log(`  Default app:     ${def}${defSuffix}`);
+    console.log();
+}
+/**
+ * Prints a list envelope (items + summary fields) in pretty mode.
+ * Summary fields are rendered as `key  value` rows first, then the item list.
+ *
+ * @param data - List envelope object.
+ */
+function printListEnvelopePretty(data) {
+    const { items, ...rest } = data;
+    const summaryEntries = Object.entries(rest).filter(([, val]) => val !== undefined && val !== null && val !== "");
+    if (summaryEntries.length > 0) {
+        const maxKeyLen = Math.max(...summaryEntries.map(([key]) => key.length), 0);
+        for (const [key, val] of summaryEntries) {
+            const label = key.padEnd(maxKeyLen);
+            console.log(`${label}  ${formatPrettyScalarValue(val)}`);
+        }
+        console.log("");
+    }
+    printArrayPretty(items);
+}
+/**
+ * Prints a plain object as key-value rows with default indentation.
+ * Delegates to {@link printObjectPrettyWithIndent}.
+ *
+ * @param obj - Object to print.
+ */
+function printObjectPretty(obj) {
+    printObjectPrettyWithIndent(obj);
+}
+/**
+ * Converts any non-object scalar to a display string.
+ * Objects and arrays are JSON-stringified; all other values are cast to string.
+ *
+ * @param raw - Raw value to format.
+ * @returns Display string.
+ */
+function formatPrettyScalarValue(raw) {
+    return typeof raw === "object" && raw !== null ? JSON.stringify(raw) : String(raw);
+}
+/** Keys excluded from app-list item display in pretty mode. */
+const APP_LIST_PRETTY_HIDE_KEYS = new Set(["isDefault", "isCurrent"]);
+/**
+ * Formats a single cell value for an app-list item in pretty mode.
+ * Applies special annotations for `isDefault` (gray "(default)") and
+ * `isCurrent` (green "← current").
+ *
+ * @param key  - Field name.
+ * @param raw  - Raw field value.
+ * @param item - The full item object (used for cross-field context).
+ * @returns Formatted display string for the cell.
+ */
+function formatAppListPrettyCell(key, raw, item) {
+    const val = formatPrettyScalarValue(raw);
+    const hasName = item.name != null && item.name !== "";
+    if (key === "name" && hasName) {
+        let out = formatPrettyScalarValue(raw);
+        if (item.isDefault === true)
+            out = `${out}${chalk.gray(" (default)")}`;
+        if (item.isCurrent === true)
+            out = `${out}${chalk.green(" ← current")}`;
+        return out;
+    }
+    if (key === "appcode" && !hasName) {
+        if (item.isDefault !== true && item.isCurrent !== true)
+            return val;
+        let out = formatPrettyScalarValue(raw);
+        if (item.isDefault === true)
+            out = `${out}${chalk.gray(" (default)")}`;
+        if (item.isCurrent === true)
+            out = `${out}${chalk.green(" ← current")}`;
+        return out;
+    }
+    return val;
+}
+/**
+ * Prints an array of items in pretty mode.
+ * Each item is either a primitive (printed as `- value`) or an object
+ * (printed as key-value rows under the item). Nested structures are handled
+ * recursively.
+ *
+ * @param arr  - Array to print.
+ * @param opts - Rendering options.
+ */
+function printArrayPretty(arr, opts) {
+    const indent = opts?.indent ?? "";
+    if (arr.length === 0) {
+        console.log(`${indent}(empty)`);
+        return;
+    }
+    if (opts?.showCount !== false) {
+        console.log(`${indent}Found ${arr.length} items:\n`);
+    }
+    const highlight = opts?.appListHighlight === true;
+    for (const item of arr) {
+        if (typeof item === "object" && item !== null) {
+            const entries = Object.entries(item)
+                .filter(([, v]) => v != null && v !== "")
+                .filter(([k]) => !highlight || !APP_LIST_PRETTY_HIDE_KEYS.has(k));
+            for (const [key, val] of entries) {
+                if (!highlight && Array.isArray(val)) {
+                    console.log(`${indent}- ${key}:`);
+                    printArrayPretty(val, { indent: `${indent}  `, showCount: false });
+                    continue;
+                }
+                if (!highlight && typeof val === "object" && val !== null) {
+                    console.log(`${indent}- ${key}:`);
+                    printObjectPrettyWithIndent(val, `${indent}  `);
+                    continue;
+                }
+                const rendered = highlight
+                    ? formatAppListPrettyCell(key, val, item)
+                    : formatPrettyScalarValue(val);
+                console.log(`${indent}- ${key}: ${rendered}`);
+            }
+            console.log(`${indent}`);
+            continue;
+        }
+        console.log(`${indent}- ${formatPrettyScalarValue(item)}`);
+    }
+}
+/**
+ * Recursively prints key-value rows for a plain object with configurable indent.
+ * Arrays are delegated to {@link printArrayPretty}; nested objects recurse.
+ *
+ * @param obj    - Object to print.
+ * @param indent - Current indentation prefix.
+ */
+function printObjectPrettyWithIndent(obj, indent = "") {
+    const entries = Object.entries(obj).filter(([, val]) => val !== undefined && val !== null);
+    const maxKeyLen = Math.max(...entries.map(([key]) => key.length), 0);
+    for (const [key, val] of entries) {
+        const label = `${indent}${key.padEnd(maxKeyLen)}`;
+        if (Array.isArray(val)) {
+            console.log(`${label}`);
+            printArrayPretty(val, { indent: `${indent}  `, showCount: false });
+            continue;
+        }
+        if (typeof val === "object" && val !== null) {
+            console.log(`${label}`);
+            printObjectPrettyWithIndent(val, `${indent}  `);
+            continue;
+        }
+        console.log(`${label}  ${formatPrettyScalarValue(val)}`);
+    }
+}

package/lib/framework/response.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Utilities for extracting structured data from API responses.
+ *
+ * Normalizes responses from heterogeneous API shapes into a consistent
+ * list + paging model used by the output formatter and list commands.
+ */
+/**
+ * Pagination metadata embedded in list responses.
+ */
+export interface Paging {
+    /** 1-based current page number. */
+    currentPage: number;
+    /** Total number of records across all pages. */
+    totalCount: number;
+    /** Number of records per page. */
+    pageSize: number;
+}
+/**
+ * A list response wrapper returned by many API endpoints.
+ * `tableData` holds the records; `paging` and `tableColumns` are optional.
+ *
+ * @template T - Type of each record in `tableData`.
+ */
+export interface ListResponse<T = any> {
+    /** Array of record objects. */
+    tableData: T[];
+    /** Present when the response includes pagination metadata. */
+    paging?: Paging;
+    /** Optional column schema for tabular rendering. */
+    tableColumns?: unknown[];
+}
+/**
+ * Extracts the array of records from a response that may be either:
+ * - A plain array `T[]`.
+ * - An object with a `tableData` property.
+ *
+ * @template T - Inferred record type.
+ * @param data - Raw API response body.
+ * @returns The extracted array, or `[]` if the shape is unrecognized.
+ *
+ * @example
+ * ```ts
+ * const items = extractList<User>(apiResponse);
+ * ```
+ */
+export declare function extractList<T = any>(data: unknown): T[];
+/**
+ * Extracts the {@link Paging} metadata from a response object.
+ * Returns `undefined` for plain arrays or empty responses.
+ *
+ * @param data - Raw API response body.
+ * @returns The paging object if present, otherwise `undefined`.
+ *
+ * @example
+ * ```ts
+ * const paging = extractPaging(response);
+ * if (paging) console.log(`Page ${paging.currentPage} of ${Math.ceil(paging.totalCount / paging.pageSize)}`);
+ * ```
+ */
+export declare function extractPaging(data: unknown): Paging | undefined;

package/lib/framework/response.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Utilities for extracting structured data from API responses.
+ *
+ * Normalizes responses from heterogeneous API shapes into a consistent
+ * list + paging model used by the output formatter and list commands.
+ */
+/**
+ * Extracts the array of records from a response that may be either:
+ * - A plain array `T[]`.
+ * - An object with a `tableData` property.
+ *
+ * @template T - Inferred record type.
+ * @param data - Raw API response body.
+ * @returns The extracted array, or `[]` if the shape is unrecognized.
+ *
+ * @example
+ * ```ts
+ * const items = extractList<User>(apiResponse);
+ * ```
+ */
+export function extractList(data) {
+    if (Array.isArray(data))
+        return data;
+    if (data && typeof data === "object") {
+        return data.tableData ?? [];
+    }
+    return [];
+}
+/**
+ * Extracts the {@link Paging} metadata from a response object.
+ * Returns `undefined` for plain arrays or empty responses.
+ *
+ * @param data - Raw API response body.
+ * @returns The paging object if present, otherwise `undefined`.
+ *
+ * @example
+ * ```ts
+ * const paging = extractPaging(response);
+ * if (paging) console.log(`Page ${paging.currentPage} of ${Math.ceil(paging.totalCount / paging.pageSize)}`);
+ * ```
+ */
+export function extractPaging(data) {
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+        return data.paging;
+    }
+    return undefined;
+}

package/lib/framework/runner-shared.d.ts

@@ -0,0 +1,244 @@
+/**
+ * @fileoverview Shared utilities used by the framework runner.
+ *
+ * Provides pure functions for:
+ * - Resolving the effective output format and jq filter from flags/config.
+ * - Building the runtime context object passed to command implementations.
+ * - Enforcing risk-level policy.
+ * - Running dry-run previews and confirmation prompts.
+ *
+ * These functions are called from both the runner adapter and help/schema
+ * generators, so they carry no side-effects beyond argument validation.
+ */
+import type { CommandDefinition, CommandResult, OutputFormat, Risk, RuntimeContext } from "./types.js";
+import type { ParsedFlags } from "./flags.js";
+/** Options for {@link resolveOutputConfig}. */
+export interface ResolveOutputOptions {
+    /** Parsed flags from the CLI. */
+    flags: ParsedFlags;
+    /** Command definition supplying format defaults. */
+    def: CommandDefinition;
+    /**
+     * Global config default format. Falls through to:
+     * `flags.format` → `configDefault` → `def.defaultOutputFormat` → `"compress"`.
+     */
+    configDefault?: OutputFormat;
+}
+/** Output configuration resolved by {@link resolveOutputConfig}. */
+export interface ResolvedOutputConfig {
+    /** Effective output format. */
+    format: OutputFormat;
+    /**
+     * jq expression from `--jq`, or `undefined` if not provided.
+     */
+    jqFilter?: string;
+}
+/**
+ * Extracts the `--jq` flag value from parsed flags.
+ *
+ * @param flags - Parsed flag map.
+ * @returns Trimmed jq expression, or `undefined` if absent / blank.
+ *
+ * @example
+ * ```ts
+ * const jq = resolveJqFilter(flags); // ".[].name" | undefined
+ * ```
+ */
+export declare function resolveJqFilter(flags: ParsedFlags): string | undefined;
+/**
+ * Resolves the effective output format from the cascade:
+ * CLI flag → global config default → command default → `"compress"`.
+ *
+ * @param options - Resolution options.
+ * @returns The effective output format.
+ */
+export declare function resolveFormat({ flags, def, configDefault, }: ResolveOutputOptions): OutputFormat;
+/**
+ * Resolves both the output format and jq filter, and validates that `--jq`
+ * is only used with `json` or `compress` formats.
+ *
+ * @param options - Resolution options.
+ * @returns Resolved format and jq filter.
+ * @throws Error with code `"validation_error"` if `--jq` is used with an incompatible format.
+ */
+export declare function resolveOutputConfig(options: ResolveOutputOptions): ResolvedOutputConfig;
+/** Options for {@link assertRiskWithinLevel}. */
+export interface AssertRiskWithinLevelOptions {
+    /** Human-readable command label for error messages. */
+    commandLabel: string;
+    /** Risk level declared by the command. */
+    commandRisk: Risk;
+    /**
+     * User-configured risk ceiling from the config file. Commands with a
+     * higher risk than this will be blocked.
+     */
+    configuredRiskLevel?: Risk;
+    /** Whether the current session is non-interactive. */
+    nonInteractive: boolean;
+    /** `true` when `--dry-run` was supplied. */
+    dryRun?: boolean;
+    /** Skip the assertion entirely when `dryRun` is active. */
+    skipWhenDryRun?: boolean;
+    /**
+     * Optional side-effect callback invoked with the violation message
+     * before the error is thrown (e.g. for logging).
+     */
+    onViolation?: (message: string) => void;
+    /**
+     * Factory for creating the error to throw. Allows the caller to use
+     * its own error type (e.g. a framework {@link CliError}).
+     */
+    createError: (message: string) => unknown;
+}
+/**
+ * Asserts that the command's risk level does not exceed the configured ceiling.
+ *
+ * The comparison uses {@link riskLevelOrder}: `high-risk-write (2) > write (1) > read (0)`.
+ *
+ * @param options - Assertion options.
+ * @throws The error returned by `options.createError` when the ceiling is exceeded.
+ *
+ * @example
+ * ```ts
+ * assertRiskWithinLevel({
+ *   commandLabel: "app delete",
+ *   commandRisk: "high-risk-write",
+ *   configuredRiskLevel: "write",
+ *   nonInteractive: true,
+ *   createError: (msg) => cliErrors.validation(msg),
+ * });
+ * ```
+ */
+export declare function assertRiskWithinLevel(options: AssertRiskWithinLevelOptions): void;
+/** Options for {@link buildRuntimeContext}. */
+export interface BuildRuntimeContextOptions<Extras extends object = {}> {
+    /** Full command label (e.g. `"dataset list"`). */
+    commandLabel: string;
+    /** Resolved output format. */
+    format: OutputFormat;
+    /** Resolved jq expression. */
+    jqFilter?: string;
+    /** Parsed flags map. */
+    flags: ParsedFlags;
+    /** Command definition for metadata (args, risk, etc.). */
+    def: CommandDefinition;
+    /** `true` when running non-interactively. */
+    nonInteractive: boolean;
+    /** Positional arguments. */
+    args: string[];
+    /**
+     * Static default values for boolean and number flags that take effect
+     * when the flag is absent. Allows commands to distinguish "not set"
+     * from "set to false/0".
+     */
+    defaults?: {
+        booleans?: Record<string, boolean | undefined>;
+        numbers?: Record<string, number | undefined>;
+    };
+    /**
+     * Additional context properties injected by the adapter's `prepare` hook.
+     * Examples: `appCode`, `cookie`, `session`, `config`.
+     */
+    extras?: Extras;
+    /**
+     * The `formatOutput` function from the adapter, bound to the correct
+     * command label and risk so the context can render results correctly.
+     */
+    formatOutput: <T>(result: CommandResult<T>, options: {
+        command: string;
+        risk: CommandDefinition["risk"];
+        format: OutputFormat;
+        jqFilter?: string;
+    }) => void;
+}
+/**
+ * Constructs the {@link RuntimeContext} object passed to every command's
+ * `validate`, `dryRun`, and `execute` function.
+ *
+ * The context provides:
+ * - Typed accessors for flags (`str`, `bool`, `num`, `flag`).
+ * - Positional argument accessors (`arg`).
+ * - The `output()` method for rendering results through the formatter.
+ *
+ * @template Extras - Shape of the adapter-supplied extras object.
+ * @param opts     - Construction options.
+ * @returns A fully populated runtime context object.
+ */
+export declare function buildRuntimeContext<Extras extends object = {}>(opts: BuildRuntimeContextOptions<Extras>): RuntimeContext<Extras>;
+/** Options for {@link runDryRunIfNeeded}. */
+export interface RunDryRunOptions {
+    /** Parsed flags map (checked for `--dry-run`). */
+    flags: ParsedFlags;
+    /** Command definition whose `dryRun` hook will be called. */
+    def: CommandDefinition;
+    /** Fully constructed runtime context. */
+    ctx: RuntimeContext;
+    /** Human-readable command label for error messages. */
+    commandLabel: string;
+    /** Resolved output format. */
+    format: OutputFormat;
+    /** Resolved jq expression. */
+    jqFilter?: string;
+    /** Adapter's `formatOutput` function. */
+    formatOutput: <T>(result: CommandResult<T>, options: {
+        command: string;
+        risk: CommandDefinition["risk"];
+        format: OutputFormat;
+        dryRun?: boolean;
+        jqFilter?: string;
+    }) => void;
+    /**
+     * Optional error mapper applied to errors thrown by `def.dryRun`.
+     * Allows the adapter to normalize framework-internal errors to its own type.
+     */
+    mapError?: (error: unknown) => unknown;
+    /**
+     * Factory for the error thrown when `--dry-run` is used on a command
+     * that does not define a `dryRun` hook.
+     */
+    createUnsupportedError: (message: string) => unknown;
+}
+/**
+ * Checks whether `--dry-run` was supplied and, if so, calls the command's
+ * `dryRun` hook and outputs the preview.
+ *
+ * @param options - Dry-run options.
+ * @returns `true` if dry-run was handled (caller should return early);
+ *          `false` if `--dry-run` was not present.
+ * @throws The error from `createUnsupportedError` when `--dry-run` is used
+ *         on a command without a `dryRun` hook.
+ */
+export declare function runDryRunIfNeeded(options: RunDryRunOptions): Promise<boolean>;
+/** Options for {@link requireConfirmationPrompt}. */
+export interface ConfirmationPromptOptions {
+    /**
+     * Lines displayed as the prompt (written to stderr).
+     * The last line typically ends with `(y/N)`.
+     */
+    lines: string[];
+    /**
+     * Factory for the error thrown when the user declines or presses Ctrl+C.
+     * The error code should be `"cancelled"` so the top-level handler exits 0.
+     */
+    createCancelledError: (message: string) => unknown;
+}
+/**
+ * Displays an interactive confirmation prompt on stderr and resolves
+ * when the user types `y` or `yes` (case-insensitive).
+ *
+ * - Any other answer throws a `"cancelled"` error.
+ * - Ctrl+C (SIGINT) also throws a `"cancelled"` error without a stack trace.
+ *
+ * @param options - Prompt options.
+ * @returns Resolves normally on confirmation.
+ * @throws The error from `createCancelledError` on decline or Ctrl+C.
+ *
+ * @example
+ * ```ts
+ * await requireConfirmationPrompt({
+ *   lines: ["This will permanently delete the dataset.", "Are you sure? (y/N)"],
+ *   createCancelledError: (msg) => cliErrors.cancelled(msg),
+ * });
+ * ```
+ */
+export declare function requireConfirmationPrompt(options: ConfirmationPromptOptions): Promise<void>;