@sdxc/cli 0.0.0-stage → 2026.10.20

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Command lines declared as a contract and mapped to handlers: `commands`, `command`,
+ * `argument`, `flag` and `prompt` declare what a program takes, `createCLI` maps handlers onto
+ * it and runs it, and every handler answers a `Result` that decides the exit code.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { Argument, ArgumentOptions, ArgumentValue, RestArgumentOptions, SingleArgumentOptions, VariadicArgumentOptions, } from "./argument.js";
+export type { Binding, CheckedCommand, CLI, CLIOptions } from "./cli.js";
+export type { ArgumentsOf, ArgumentsShape, Command, CommandDefinition, FlagsOf, FlagsShape, Group, GroupDefinition, GroupInputs, Node, } from "./command.js";
+export type { AnyCommandContext, CommandContextInit, Stdin } from "./context.js";
+export type { ArgumentDescription, CommandDescription, FlagDescription } from "./describe.js";
+export type { Exec, ExecOptions, ExecOutput, ExecRequest, Stdio } from "./exec.js";
+export type { BooleanFlagOptions, Flag, FlagKind, FlagOptions, FlagValue, ValueFlag, ValueFlagOptions, } from "./flag.js";
+export type { ChainContext, CLITypes, CommandAction, CommandHandler, HandlerContext, } from "./handler.js";
+export type { Input } from "./keys.js";
+export type { Lazy } from "./lazy.js";
+export type { AnyCommandMiddleware, ChainProperties, CommandMiddleware, CommandResult, ContextEffect, EmptyContextEffect, NextFunction, } from "./middleware.js";
+export type { Ask, AskOptions, Choice, Choices, ConfirmOptions, MultiselectOptions, NumberOptions, PasswordOptions, PromptDeclaration, PromptError, PromptKind, Prompter, SearchOptions, SelectOptions, TextOptions, } from "./prompt.js";
+export type { Output } from "./screen.js";
+export type { RunIO } from "./session.js";
+export type { Env, Paint, Style } from "./style.js";
+export type { RunTask, Task, TaskResult } from "./task.js";
+export { argument } from "./argument.js";
+export { createCLI } from "./cli.js";
+export { command, commands } from "./command.js";
+export { CommandContext } from "./context.js";
+export { CancelledError, EXIT_CODES, ExitError, UsageError, cancelled, exit, exitCodeOf, success, usage, } from "./errors.js";
+export { ExecError, spawnExec } from "./exec.js";
+export { flag } from "./flag.js";
+export { createCommand } from "./handler.js";
+export { lazy } from "./lazy.js";
+export { prompt } from "./prompt.js";
+export { createStyle } from "./style.js";
+export { failure } from "@sdxc/result";

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * Command lines declared as a contract and mapped to handlers: `commands`, `command`,
+ * `argument`, `flag` and `prompt` declare what a program takes, `createCLI` maps handlers onto
+ * it and runs it, and every handler answers a `Result` that decides the exit code.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { argument } from "./argument.js";
+export { createCLI } from "./cli.js";
+export { command, commands } from "./command.js";
+export { CommandContext } from "./context.js";
+export { CancelledError, EXIT_CODES, ExitError, UsageError, cancelled, exit, exitCodeOf, success, usage, } from "./errors.js";
+export { ExecError, spawnExec } from "./exec.js";
+export { flag } from "./flag.js";
+export { createCommand } from "./handler.js";
+export { lazy } from "./lazy.js";
+export { prompt } from "./prompt.js";
+export { createStyle } from "./style.js";
+export { failure } from "@sdxc/result";

package/dist/interactions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * How each prompt kind draws and reacts to keys on a terminal: a line editor for text, password
+ * and number, a toggle for confirm, and a scrolling list for select, multiselect and search.
+ * Each is pure state over keys; `ask.ts` owns the terminal and the loop around them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Key } from "./keys.js";
+import type { PromptKind, PromptKinds } from "./prompt.js";
+import type { Style } from "./style.js";
+/** What a key did: answered the prompt, or found the answer wrong, or neither. */
+export type Step = {
+    submit: unknown;
+} | {
+    error: string;
+} | undefined;
+/** One prompt kind's state on a terminal. */
+export interface Interaction {
+    /** The lines under the question, the question line itself included. */
+    render(style: Style, header: string): string[];
+    key(key: Key): Step;
+    /** The answer as the summary line prints it. */
+    summary(value: unknown): string;
+}
+/** The interaction for `kind`, starting from `initial` (the default, or a preselection). */
+export declare function interaction<Kind extends PromptKind>(kind: Kind, options: PromptKinds[Kind], initial: unknown): Interaction;

package/dist/interactions.js

@@ -0,0 +1,373 @@
+/**
+ * How each prompt kind draws and reacts to keys on a terminal: a line editor for text, password
+ * and number, a toggle for confirm, and a scrolling list for select, multiselect and search.
+ * Each is pure state over keys; `ask.ts` owns the terminal and the loop around them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { typed } from "./keys.js";
+import { normalizeChoices } from "./prompt.js";
+import { graphemes } from "./style.js";
+/** How many list options show at once; the rest scroll. */
+const LIST_LIMIT = 10;
+/** How long typed characters keep adding to a select's jump-to text. */
+const JUMP_RESET_MS = 1000;
+/** The interaction for `kind`, starting from `initial` (the default, or a preselection). */
+export function interaction(kind, options, initial) {
+    switch (kind) {
+        case "text":
+            return line(initial, { placeholder: options.placeholder });
+        case "password":
+            return line(initial, { mask: options.mask ?? true });
+        case "number":
+            return numberLine(options, initial);
+        case "confirm":
+            return confirm(initial === true, options);
+        case "select":
+            return list(options.options, initial, { mode: "one" });
+        case "multiselect": {
+            let multiselect = options;
+            return list(multiselect.options, initial, {
+                mode: "many",
+                min: multiselect.min,
+                max: multiselect.max,
+            });
+        }
+        default: {
+            let search = options;
+            return list(search.options, initial, {
+                mode: search.multiple === true ? "many" : "one",
+                search: true,
+                placeholder: search.placeholder,
+                min: search.min,
+                max: search.max,
+            });
+        }
+    }
+}
+/** A line of text being edited, with a cursor inside it. */
+class Editor {
+    chars;
+    cursor;
+    /** @param text - What the line starts with */
+    constructor(text = "") {
+        this.chars = graphemes(text);
+        this.cursor = this.chars.length;
+    }
+    get text() {
+        return this.chars.join("");
+    }
+    /** Applies an editing key, answering whether it was one. */
+    edit(key, accept = () => true) {
+        let character = typed(key);
+        if (character !== undefined) {
+            if (!accept(character))
+                return false;
+            this.chars.splice(this.cursor, 0, character);
+            this.cursor += 1;
+            return true;
+        }
+        if (key.name === "backspace") {
+            if (this.cursor > 0)
+                this.chars.splice(this.cursor - 1, 1);
+            this.cursor = Math.max(0, this.cursor - 1);
+        }
+        else if (key.name === "delete")
+            this.chars.splice(this.cursor, 1);
+        else if (key.name === "left")
+            this.cursor = Math.max(0, this.cursor - 1);
+        else if (key.name === "right")
+            this.cursor = Math.min(this.chars.length, this.cursor + 1);
+        else if (key.name === "home" || (key.ctrl && key.name === "a"))
+            this.cursor = 0;
+        else if (key.name === "end" || (key.ctrl && key.name === "e"))
+            this.cursor = this.chars.length;
+        else if (key.ctrl && key.name === "u") {
+            this.chars.splice(0, this.cursor);
+            this.cursor = 0;
+        }
+        else
+            return false;
+        return true;
+    }
+    /** The line with the cursor drawn as an inverse cell, each character shown through `show`. */
+    render(style, show = (character) => character) {
+        let shown = this.chars.map(show);
+        let at = shown[this.cursor] ?? " ";
+        return `${shown.slice(0, this.cursor).join("")}${style.inverse(at)}${shown.slice(this.cursor + 1).join("")}`;
+    }
+}
+/** Text and password: a line editor whose empty answer takes `initial`. */
+function line(initial, options) {
+    let editor = new Editor();
+    let fallback = typeof initial === "string" ? initial : undefined;
+    let secret = options.mask !== undefined;
+    return {
+        render(style, header) {
+            if (editor.chars.length === 0) {
+                let hint = secret ? undefined : (fallback ?? options.placeholder);
+                let shown = hint === undefined ? style.inverse(" ") : style.dim(hint);
+                return [`${header} › ${shown}`];
+            }
+            if (secret && options.mask === false)
+                return [`${header} › `];
+            let value = secret ? editor.render(style, () => "•") : editor.render(style);
+            return [`${header} › ${value}`];
+        },
+        key(key) {
+            if (key.name === "return") {
+                return {
+                    submit: editor.chars.length === 0 && fallback !== undefined ? fallback : editor.text,
+                };
+            }
+            editor.edit(key);
+            return undefined;
+        },
+        summary(value) {
+            if (!secret)
+                return String(value);
+            return options.mask === false ? "" : "•".repeat(graphemes(String(value)).length);
+        },
+    };
+}
+/** Number: digits, `-` and `.`, with the arrows stepping by `step` within `min` and `max`. */
+function numberLine(options, initial) {
+    let editor = new Editor();
+    let fallback = typeof initial === "number" ? initial : undefined;
+    let step = options.step ?? 1;
+    let clamp = (value) => Math.min(options.max ?? Infinity, Math.max(options.min ?? -Infinity, value));
+    return {
+        render(style, header) {
+            if (editor.chars.length === 0) {
+                let shown = fallback === undefined ? style.inverse(" ") : style.dim(String(fallback));
+                return [`${header} › ${shown}`];
+            }
+            return [`${header} › ${editor.render(style)}`];
+        },
+        key(key) {
+            if (key.name === "up" || key.name === "down") {
+                let current = editor.text === "" ? (fallback ?? options.min ?? 0) : Number(editor.text);
+                if (Number.isNaN(current))
+                    current = fallback ?? 0;
+                let next = editor.text === "" && fallback === undefined
+                    ? current
+                    : current + (key.name === "up" ? step : -step);
+                editor = new Editor(String(clamp(next)));
+                return undefined;
+            }
+            if (key.name === "return") {
+                if (editor.text === "") {
+                    return fallback === undefined ? { error: "Enter a number" } : { submit: fallback };
+                }
+                let value = Number(editor.text);
+                if (Number.isNaN(value))
+                    return { error: "Enter a number" };
+                if (options.min !== undefined && value < options.min) {
+                    return { error: `Enter a number of at least ${options.min}` };
+                }
+                if (options.max !== undefined && value > options.max) {
+                    return { error: `Enter a number of at most ${options.max}` };
+                }
+                return { submit: value };
+            }
+            editor.edit(key, (character) => /^[\d.-]$/.test(character));
+            return undefined;
+        },
+        summary: (value) => String(value),
+    };
+}
+/** Yes or no: `y` and `n` answer at once, the arrows switch, and Enter takes the current one. */
+function confirm(initial, options) {
+    let value = initial;
+    let active = options.active ?? "Yes";
+    let inactive = options.inactive ?? "No";
+    return {
+        render(style, header) {
+            let yes = value ? style.cyan(style.underline(active)) : style.dim(active);
+            let no = value ? style.dim(inactive) : style.cyan(style.underline(inactive));
+            let marker = value ? "(Y/n)" : "(y/N)";
+            return [
+                `${header} ${style.dim(marker)} › ${value ? "●" : "○"} ${yes} / ${value ? "○" : "●"} ${no}`,
+            ];
+        },
+        key(key) {
+            if (key.name === "y")
+                return { submit: true };
+            if (key.name === "n")
+                return { submit: false };
+            if (key.name === "return")
+                return { submit: value };
+            if (["left", "right", "up", "down", "tab"].includes(key.name))
+                value = !value;
+            return undefined;
+        },
+        summary: (answer) => (answer === true ? active : inactive),
+    };
+}
+/**
+ * Select, multiselect and search: a cursor over the options (only the ones matching the typed
+ * query, for search), skipping disabled ones, with Space toggling when the answer is a list.
+ */
+function list(choices, initial, mode) {
+    let options = normalizeChoices(choices);
+    let selected = new Set();
+    if (mode.mode === "many" && Array.isArray(initial)) {
+        options.forEach((option, index) => {
+            if (initial.some((value) => Object.is(value, option.value)))
+                selected.add(index);
+        });
+    }
+    let query = new Editor();
+    let jump = "";
+    let jumpedAt = 0;
+    /** The options the query matches, as indices into `options`. */
+    let visible = () => {
+        let needle = query.text.toLowerCase();
+        return options
+            .map((_, index) => index)
+            .filter((index) => {
+            if (mode.search !== true || needle === "")
+                return true;
+            let option = options[index];
+            return (option.label.toLowerCase().includes(needle) ||
+                String(option.value).toLowerCase().includes(needle));
+        });
+    };
+    let initialIndex = options.findIndex((option) => !option.disabled && mode.mode === "one" && Object.is(option.value, initial));
+    let cursor = initialIndex === -1 ? options.findIndex((option) => !option.disabled) : initialIndex;
+    /** Moves the cursor `by` positions through the matching enabled options, wrapping around. */
+    let move = (by) => {
+        let shown = visible().filter((index) => !options[index].disabled);
+        if (shown.length === 0)
+            return;
+        let at = shown.indexOf(cursor);
+        let next = at === -1 ? 0 : (at + by + shown.length) % shown.length;
+        cursor = shown[next];
+    };
+    /** Puts the cursor on the first match after the query changed. */
+    let settle = () => {
+        let shown = visible().filter((index) => !options[index].disabled);
+        if (!shown.includes(cursor))
+            cursor = shown[0] ?? -1;
+    };
+    let labels = (value) => {
+        let values = Array.isArray(value) ? value : [value];
+        return values
+            .map((each) => options.find((option) => Object.is(option.value, each))?.label ?? String(each))
+            .join(", ");
+    };
+    return {
+        render(style, header) {
+            let lines = [];
+            if (mode.search === true) {
+                let shownQuery = query.chars.length === 0
+                    ? mode.placeholder === undefined
+                        ? style.inverse(" ")
+                        : style.dim(mode.placeholder)
+                    : query.render(style);
+                lines.push(`${header} › ${shownQuery}`);
+            }
+            else
+                lines.push(header);
+            let shown = visible();
+            if (shown.length === 0) {
+                lines.push(style.dim("  No option matches"));
+                return lines;
+            }
+            let at = Math.max(0, shown.indexOf(cursor));
+            let start = Math.min(Math.max(0, at - Math.floor(LIST_LIMIT / 2)), Math.max(0, shown.length - LIST_LIMIT));
+            let window = shown.slice(start, start + LIST_LIMIT);
+            if (start > 0)
+                lines.push(style.dim(`  ↑ ${start} more`));
+            for (let index of window) {
+                let option = options[index];
+                let pointer = index === cursor ? style.cyan("❯") : " ";
+                let box = mode.mode === "many" ? `${selected.has(index) ? style.green("◉") : "◯"} ` : "";
+                let label = option.disabled
+                    ? style.dim(`${option.label} (disabled)`)
+                    : index === cursor
+                        ? style.cyan(option.label)
+                        : option.label;
+                let hint = option.hint === "" ? "" : ` ${style.dim(option.hint)}`;
+                lines.push(`${pointer} ${box}${label}${hint}`);
+            }
+            let below = shown.length - start - window.length;
+            if (below > 0)
+                lines.push(style.dim(`  ↓ ${below} more`));
+            return lines;
+        },
+        key(key) {
+            if (key.name === "up")
+                move(-1);
+            else if (key.name === "down" || key.name === "tab")
+                move(1);
+            else if (key.name === "home" && mode.search !== true) {
+                cursor = -1;
+                move(1);
+            }
+            else if (key.name === "end" && mode.search !== true) {
+                cursor = -1;
+                move(-1);
+            }
+            else if (key.name === "space" && mode.mode === "many") {
+                let option = options[cursor];
+                if (option !== undefined && !option.disabled) {
+                    if (selected.has(cursor))
+                        selected.delete(cursor);
+                    else
+                        selected.add(cursor);
+                }
+            }
+            else if (key.name === "a" && !key.ctrl && mode.mode === "many" && mode.search !== true) {
+                let enabled = options
+                    .map((_, index) => index)
+                    .filter((index) => !options[index].disabled);
+                let all = enabled.every((index) => selected.has(index));
+                for (let index of enabled) {
+                    if (all)
+                        selected.delete(index);
+                    else
+                        selected.add(index);
+                }
+            }
+            else if (key.name === "return") {
+                if (mode.mode === "one") {
+                    let option = options[cursor];
+                    if (option === undefined || option.disabled || !visible().includes(cursor)) {
+                        return { error: "No option matches" };
+                    }
+                    return { submit: option.value };
+                }
+                let values = options
+                    .filter((_, index) => selected.has(index))
+                    .map((option) => option.value);
+                if (mode.min !== undefined && values.length < mode.min) {
+                    return { error: `Select at least ${mode.min}` };
+                }
+                if (mode.max !== undefined && values.length > mode.max) {
+                    return { error: `Select at most ${mode.max}` };
+                }
+                return { submit: values };
+            }
+            else if (mode.search === true) {
+                if (query.edit(key))
+                    settle();
+            }
+            else {
+                let character = typed(key);
+                if (character !== undefined) {
+                    let now = Date.now();
+                    jump = now - jumpedAt > JUMP_RESET_MS ? character : jump + character;
+                    jumpedAt = now;
+                    let needle = jump.toLowerCase();
+                    let match = options.findIndex((option) => !option.disabled && option.label.toLowerCase().startsWith(needle));
+                    if (match !== -1)
+                        cursor = match;
+                }
+            }
+            return undefined;
+        },
+        summary: labels,
+    };
+}

package/dist/keys.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Keyboard input for prompts: `node:readline`'s keypress events on a stdin in raw mode, which
+ * run the same on Node and Bun, behind a queue a prompt reads one key at a time. Closing the
+ * reader leaves raw mode and pauses stdin, so the process can exit once a prompt is answered.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** One key press, shaped as `node:readline` reports it. */
+export interface Key {
+    /** `"return"`, `"up"`, `"a"`, `"space"`…; empty for a character readline does not name. */
+    name: string;
+    /** The characters the key produced. */
+    sequence: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+}
+/** Reads keys one at a time. */
+export interface Keyboard {
+    /** The next key, or `null` once no more will arrive (`signal` aborted, input ended). */
+    read(signal: AbortSignal): Promise<Key | null>;
+    /** Stops reading and gives the input back. */
+    close(): void;
+}
+/** A readable stream a CLI reads keys from; `process.stdin` is one. */
+export interface Input extends NodeJS.EventEmitter {
+    isTTY?: boolean;
+    setRawMode?(mode: boolean): unknown;
+    resume(): unknown;
+    pause(): unknown;
+}
+/**
+ * Starts reading keys from `input` in raw mode.
+ *
+ * @param onRaw - Told when raw mode turns on and off, so an exit handler can leave it
+ */
+export declare function openKeyboard(input: Input, onRaw: (raw: boolean) => void): Keyboard;
+/**
+ * The key a script names: `"enter"`, `"down"`, `"ctrl+c"`, or a single character. Longer text is
+ * not a key; {@link keysFromScript} types it one character at a time.
+ */
+export declare function keyFromName(name: string): Key;
+/** A test's key script as key presses: named keys as one press, other text one per character. */
+export declare function keysFromScript(script: readonly string[]): Key[];
+/** Whether `key` cancels a prompt: Ctrl+C or Escape. */
+export declare function isCancel(key: Key): boolean;
+/** The printable character `key` types, or `undefined` for a control key. */
+export declare function typed(key: Key): string | undefined;

package/dist/keys.js

@@ -0,0 +1,146 @@
+/**
+ * Keyboard input for prompts: `node:readline`'s keypress events on a stdin in raw mode, which
+ * run the same on Node and Bun, behind a queue a prompt reads one key at a time. Closing the
+ * reader leaves raw mode and pauses stdin, so the process can exit once a prompt is answered.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { emitKeypressEvents } from "node:readline";
+import { graphemes } from "./style.js";
+/**
+ * Starts reading keys from `input` in raw mode.
+ *
+ * @param onRaw - Told when raw mode turns on and off, so an exit handler can leave it
+ */
+export function openKeyboard(input, onRaw) {
+    emitKeypressEvents(input);
+    input.setRawMode?.(true);
+    onRaw(true);
+    input.resume();
+    let queue = [];
+    let waiting;
+    let ended = false;
+    /** Queues one key, or hands it to the read waiting for it. */
+    function onKeypress(sequence, key) {
+        let pressed = {
+            name: key?.name ?? "",
+            sequence: key?.sequence ?? sequence ?? "",
+            ctrl: key?.ctrl === true,
+            meta: key?.meta === true,
+            shift: key?.shift === true,
+        };
+        if (waiting === undefined)
+            queue.push(pressed);
+        else {
+            let resolve = waiting;
+            waiting = undefined;
+            resolve(pressed);
+        }
+    }
+    /** Ends every pending read once the input closes. */
+    function onEnd() {
+        ended = true;
+        waiting?.(null);
+        waiting = undefined;
+    }
+    input.on("keypress", onKeypress);
+    input.on("end", onEnd);
+    return {
+        read(signal) {
+            let next = queue.shift();
+            if (next !== undefined)
+                return Promise.resolve(next);
+            if (ended || signal.aborted)
+                return Promise.resolve(null);
+            return new Promise((resolve) => {
+                let abort = () => {
+                    waiting = undefined;
+                    resolve(null);
+                };
+                signal.addEventListener("abort", abort, { once: true });
+                waiting = (key) => {
+                    signal.removeEventListener("abort", abort);
+                    resolve(key);
+                };
+            });
+        },
+        close() {
+            input.off("keypress", onKeypress);
+            input.off("end", onEnd);
+            input.setRawMode?.(false);
+            onRaw(false);
+            input.pause();
+        },
+    };
+}
+/** Keys a script names by something other than the character they type. */
+const NAMED_KEYS = {
+    enter: "return",
+    return: "return",
+    space: "space",
+    up: "up",
+    down: "down",
+    left: "left",
+    right: "right",
+    home: "home",
+    end: "end",
+    tab: "tab",
+    backspace: "backspace",
+    delete: "delete",
+    escape: "escape",
+    pageup: "pageup",
+    pagedown: "pagedown",
+};
+/**
+ * The key a script names: `"enter"`, `"down"`, `"ctrl+c"`, or a single character. Longer text is
+ * not a key; {@link keysFromScript} types it one character at a time.
+ */
+export function keyFromName(name) {
+    let ctrl = name.startsWith("ctrl+");
+    let bare = ctrl ? name.slice(5) : name;
+    let named = NAMED_KEYS[bare];
+    if (named !== undefined) {
+        let sequence = named === "space" ? " " : named === "return" ? "\r" : "";
+        return { name: named, sequence, ctrl, meta: false, shift: false };
+    }
+    let shift = bare !== bare.toLowerCase();
+    return {
+        name: /^[a-z0-9]$/i.test(bare) ? bare.toLowerCase() : "",
+        sequence: ctrl ? String.fromCharCode(bare.charCodeAt(0) & 31) : bare,
+        ctrl,
+        meta: false,
+        shift,
+    };
+}
+/** A test's key script as key presses: named keys as one press, other text one per character. */
+export function keysFromScript(script) {
+    let keys = [];
+    for (let entry of script) {
+        if (entry.length === 1 || NAMED_KEYS[entry] !== undefined || entry.startsWith("ctrl+")) {
+            keys.push(keyFromName(entry));
+        }
+        else {
+            for (let character of entry)
+                keys.push(keyFromName(character));
+        }
+    }
+    return keys;
+}
+/** Whether `key` cancels a prompt: Ctrl+C or Escape. */
+export function isCancel(key) {
+    return (key.ctrl && key.name === "c") || key.name === "escape";
+}
+/** The printable character `key` types, or `undefined` for a control key. */
+export function typed(key) {
+    if (key.ctrl || key.meta)
+        return undefined;
+    if (key.name === "space")
+        return " ";
+    let sequence = key.sequence;
+    if (sequence.length === 0 || sequence.startsWith("\u001B"))
+        return undefined;
+    if (graphemes(sequence).length !== 1)
+        return undefined;
+    return sequence.codePointAt(0) >= 32 && sequence !== "\u007F" ? sequence : undefined;
+}

package/dist/lazy.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Marks a command's implementation as a module imported on first use, so a run imports only
+ * the handler it reaches and `--help` imports none.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Brands a loader so `map()` can tell it from a handler, both being plain functions. */
+declare const LAZY: unique symbol;
+/** An implementation that arrives as the default export of a module imported on demand. */
+export interface Lazy<Target> {
+    readonly [LAZY]: true;
+    readonly load: () => Promise<{
+        default: Target;
+    }>;
+}
+/**
+ * Wraps a dynamic import so `map()` defers it to the run that needs the module, which
+ * default-exports what `createCommand` returns.
+ *
+ * @param load - A function returning the module's `import()`
+ * @example cli.map(sdxc.ui.add, lazy(() => import("./commands/ui/add.js")));
+ */
+export declare function lazy<Target>(load: () => Promise<{
+    default: Target;
+}>): Lazy<Target>;
+/** Whether a `map()` argument was wrapped by {@link lazy}. */
+export declare function isLazy(value: unknown): value is Lazy<unknown>;
+export {};