@sdxc/cli 0.0.0-pre.1 → 0.0.0-stage

package/dist/terminal.d.ts

@@ -1,21 +0,0 @@
-/**
- * A virtual terminal: an output stream that applies the cursor movement, erasing and wrapping a
- * real terminal does, so a test reads the screen a person would see instead of the escape
- * sequences that drew it.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import type { Output } from "./screen.js";
-/** A screen that keeps every row written to it, scrolling never discarding one. */
-export declare class VirtualTerminal implements Output {
-    #private;
-    readonly isTTY = true;
-    readonly columns: number;
-    /** @param columns - The width text wraps at */
-    constructor(columns: number);
-    /** Applies `text` as a terminal would. */
-    write(text: string): boolean;
-    /** The screen as text: each row without trailing spaces, trailing empty rows dropped. */
-    screen(): string;
-}

package/dist/terminal.js

@@ -1,101 +0,0 @@
-/**
- * A virtual terminal: an output stream that applies the cursor movement, erasing and wrapping a
- * real terminal does, so a test reads the screen a person would see instead of the escape
- * sequences that drew it.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-/** A CSI escape sequence: parameters and the final letter. */
-// oxlint-disable-next-line eslint/no-control-regex -- CSI sequences start with the ESC control character
-const CSI = /^\u001B\[([0-9;?]*)([A-Za-z])/;
-/** A screen that keeps every row written to it, scrolling never discarding one. */
-export class VirtualTerminal {
-    isTTY = true;
-    columns;
-    #rows = [[]];
-    #row = 0;
-    #column = 0;
-    /** @param columns - The width text wraps at */
-    constructor(columns) {
-        this.columns = columns;
-    }
-    /** Applies `text` as a terminal would. */
-    write(text) {
-        let index = 0;
-        while (index < text.length) {
-            let rest = text.slice(index);
-            let sequence = CSI.exec(rest);
-            if (sequence !== null) {
-                this.#control(sequence[1], sequence[2]);
-                index += sequence[0].length;
-                continue;
-            }
-            let character = String.fromCodePoint(rest.codePointAt(0));
-            index += character.length;
-            if (character === "\r")
-                this.#column = 0;
-            else if (character === "\n")
-                this.#moveTo(this.#row + 1, 0);
-            else if (character === "\u001B")
-                continue;
-            else
-                this.#print(character);
-        }
-        return true;
-    }
-    /** The screen as text: each row without trailing spaces, trailing empty rows dropped. */
-    screen() {
-        let lines = this.#rows.map((row) => row.join("").replace(/\s+$/, ""));
-        while (lines.length > 0 && lines.at(-1) === "")
-            lines.pop();
-        return lines.join("\n");
-    }
-    /** Prints one character, wrapping first when the previous one filled the row. */
-    #print(character) {
-        if (this.#column >= this.columns)
-            this.#moveTo(this.#row + 1, 0);
-        let row = this.#rows[this.#row];
-        while (row.length < this.#column)
-            row.push(" ");
-        row[this.#column] = character;
-        this.#column += 1;
-    }
-    #moveTo(row, column) {
-        this.#row = Math.max(0, row);
-        this.#column = Math.max(0, column);
-        while (this.#rows.length <= this.#row)
-            this.#rows.push([]);
-    }
-    /** Applies one CSI sequence; styling and cursor visibility change nothing on the text. */
-    #control(parameters, command) {
-        let count = parameters === "" ? 1 : Number.parseInt(parameters, 10) || 1;
-        let row = this.#rows[this.#row];
-        switch (command) {
-            case "A":
-                this.#moveTo(this.#row - count, this.#column);
-                break;
-            case "B":
-                this.#moveTo(this.#row + count, this.#column);
-                break;
-            case "C":
-                this.#column = Math.min(this.columns, this.#column + count);
-                break;
-            case "D":
-                this.#column = Math.max(0, this.#column - count);
-                break;
-            case "G":
-                this.#column = count - 1;
-                break;
-            case "K":
-                row.length = Math.min(row.length, this.#column);
-                break;
-            case "J":
-                row.length = Math.min(row.length, this.#column);
-                this.#rows.length = this.#row + 1;
-                break;
-            default:
-                break;
-        }
-    }
-}

package/dist/test.d.ts

@@ -1,89 +0,0 @@
-/**
- * `@sdxc/cli/test`: runs a CLI in a test the way a terminal does, collecting both streams,
- * answering prompts from a script, recording every child process against a table of replies,
- * and optionally drawing prompts on a virtual terminal driven by key presses.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import type { CLI } from "./cli.js";
-import type { Group } from "./command.js";
-import type { Exec, Stdio } from "./exec.js";
-import type { AnyCommandMiddleware } from "./middleware.js";
-import type { Env } from "./style.js";
-/** What a recorded command answers: exit 0 and no output unless given. */
-export interface ExecReply {
-    /** @default 0 */
-    code?: number;
-    stdout?: string;
-    stderr?: string;
-}
-/** One command the run executed. */
-export interface ExecCall {
-    command: string[];
-    cwd: string;
-    stdio: Stdio;
-}
-/** How `invoke` runs the CLI. */
-export interface InvokeOptions {
-    /** @default process.cwd() */
-    cwd?: string;
-    /** The whole environment the run sees. @default {} */
-    env?: Env;
-    /**
-     * Replies by command, keyed as a shell user writes it (`"git init"`), or an `Exec` that runs
-     * them. A command with no reply fails, naming itself, so nothing runs by accident.
-     * @default {}
-     */
-    exec?: Readonly<Record<string, ExecReply>> | Exec;
-    /**
-     * Prompt answers: an object answers by the flag or argument a prompt fills (its key or flag
-     * name) or a handler prompt's `name`; an array answers prompts in the order they are asked.
-     * A prompt with no answer fails the run, naming it.
-     */
-    answers?: Readonly<Record<string, unknown>> | readonly unknown[];
-    /**
-     * Whether stdin is a terminal. With `false`, nothing is asked: defaults apply, and a
-     * required input with a prompt is a usage error.
-     * @default true
-     */
-    interactive?: boolean;
-    /** Draws prompts and tasks on a virtual terminal this wide; prompts then read `keys`. */
-    tty?: {
-        columns?: number;
-    };
-    /**
-     * Key presses for `tty`: `"enter"`, `"down"`, `"space"`, `"ctrl+c"`, a character, or longer
-     * text typed one character at a time.
-     */
-    keys?: readonly string[];
-    /** Aborting it stops the run the way Ctrl+C does. */
-    signal?: AbortSignal;
-    /**
-     * Text piped into the run, which `ctx.stdin.text()` reads. Piped stdin is no terminal, so
-     * `interactive` then defaults to `false`.
-     */
-    stdin?: string;
-}
-/** What a run printed and how it ended. */
-export interface Invocation {
-    code: number;
-    stdout: string;
-    /** What stderr shows: plain text, or the virtual terminal's final screen with `tty`. */
-    stderr: string;
-    /** Every command `ctx.exec` ran, in order. */
-    exec: ExecCall[];
-    /** With `tty`, the screen after each key press. */
-    screens: string[];
-}
-/**
- * Runs `cli` with `argv` and answers what it printed.
- *
- * @example
- * let run = await invoke(cli, ["create", "app"], { answers: { template: "app", git: false } });
- * expect(run.code).toBe(0);
- * @example
- * let run = await invoke(cli, ["create"], { tty: { columns: 60 }, keys: ["my-app", "enter", "down", "enter"] });
- * run.screens[0]; // the prompt after "my-app" was typed
- */
-export declare function invoke<Commands extends Group, Chain extends readonly AnyCommandMiddleware[]>(cli: CLI<Commands, Chain>, argv: readonly string[], options?: InvokeOptions): Promise<Invocation>;

package/dist/test.js

@@ -1,140 +0,0 @@
-/**
- * `@sdxc/cli/test`: runs a CLI in a test the way a terminal does, collecting both streams,
- * answering prompts from a script, recording every child process against a table of replies,
- * and optionally drawing prompts on a virtual terminal driven by key presses.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import { EventEmitter } from "node:events";
-import { failure, success } from "@sdxc/result";
-import { runScripted } from "./cli.js";
-import { displayCommand, ExecError } from "./exec.js";
-import { keysFromScript } from "./keys.js";
-import { VirtualTerminal } from "./terminal.js";
-/** A stream that keeps what is written to it. */
-class Capture {
-    text = "";
-    isTTY = false;
-    write(text) {
-        this.text += text;
-        return true;
-    }
-}
-/** An exec answering from `replies` and recording each call. */
-function tableExec(replies, calls) {
-    return async (command, request) => {
-        calls.push({ command: [...command], cwd: request.cwd, stdio: request.stdio });
-        let shown = displayCommand(command);
-        let reply = replies[shown];
-        if (reply === undefined) {
-            return failure(new ExecError(`invoke() has no reply for ${shown}`, { command, code: null }));
-        }
-        let stdout = reply.stdout ?? "";
-        let stderr = reply.stderr ?? "";
-        if (request.stdio === "inherit") {
-            if (stdout !== "")
-                request.stdout.write(stdout);
-            if (stderr !== "")
-                request.stderr.write(stderr);
-        }
-        else if (request.stdio === "stderr") {
-            if (stdout !== "")
-                request.stderr.write(stdout);
-            if (stderr !== "")
-                request.stderr.write(stderr);
-        }
-        let collected = request.stdio === "collect"
-            ? { stdout, stderr, output: stdout + stderr }
-            : { stdout: "", stderr: "", output: "" };
-        let code = reply.code ?? 0;
-        if (code !== 0) {
-            return failure(new ExecError(`${shown} exited with ${code}`, { command, code, ...collected }));
-        }
-        return success({ code, ...collected });
-    };
-}
-/**
- * A stdin that reports being a terminal or not. Read, a pipe produces `text` and ends, empty
- * when there is none; a terminal produces nothing.
- */
-function scriptedInput(isTTY, text) {
-    let emitter = new EventEmitter();
-    let sent = false;
-    return Object.assign(emitter, {
-        isTTY,
-        resume: () => {
-            if (isTTY || sent)
-                return;
-            sent = true;
-            queueMicrotask(() => {
-                if (text !== undefined && text !== "")
-                    emitter.emit("data", text);
-                emitter.emit("end");
-            });
-        },
-        pause: () => undefined,
-    });
-}
-/**
- * Runs `cli` with `argv` and answers what it printed.
- *
- * @example
- * let run = await invoke(cli, ["create", "app"], { answers: { template: "app", git: false } });
- * expect(run.code).toBe(0);
- * @example
- * let run = await invoke(cli, ["create"], { tty: { columns: 60 }, keys: ["my-app", "enter", "down", "enter"] });
- * run.screens[0]; // the prompt after "my-app" was typed
- */
-export async function invoke(cli, argv, options = {}) {
-    let stdout = new Capture();
-    let terminal = options.tty === undefined ? undefined : new VirtualTerminal(options.tty.columns ?? 80);
-    let capture = new Capture();
-    let stderr = terminal ?? capture;
-    let calls = [];
-    let exec = typeof options.exec === "function"
-        ? recording(options.exec, calls)
-        : tableExec(options.exec ?? {}, calls);
-    let screens = [];
-    let keyboard;
-    let pending = false;
-    if (terminal !== undefined) {
-        let keys = keysFromScript(options.keys ?? []);
-        keyboard = () => ({
-            read() {
-                if (pending)
-                    screens.push(terminal.screen());
-                let key = keys.shift();
-                pending = key !== undefined;
-                return Promise.resolve(key ?? null);
-            },
-            close: () => undefined,
-        });
-    }
-    let interactive = options.interactive ?? options.stdin === undefined;
-    let code = await runScripted(cli, argv, {
-        cwd: options.cwd ?? process.cwd(),
-        env: options.env ?? {},
-        stdin: scriptedInput(interactive, options.stdin),
-        stdout,
-        stderr,
-        exec,
-        signal: options.signal ?? new AbortController().signal,
-    }, { answers: options.answers, keyboard, interactive });
-    if (pending && terminal !== undefined)
-        screens.push(terminal.screen());
-    return {
-        code,
-        stdout: stdout.text,
-        stderr: terminal === undefined ? capture.text : terminal.screen(),
-        exec: calls,
-        screens,
-    };
-}
-/** Records each call before handing it to `exec`. */
-function recording(exec, calls) {
-    return (command, request) => {
-        calls.push({ command: [...command], cwd: request.cwd, stdio: request.stdio });
-        return exec(command, request);
-    };
-}

package/dist/tree.d.ts

@@ -1,58 +0,0 @@
-/**
- * The indexed contract a CLI parses against: every command and group with its path, flag
- * lookup by long name, alias and short alias, and which commands own each flag name. Built once
- * by `createCLI`, so a contract mistake fails at startup instead of on the run that reaches it.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import type { ArgumentSpec } from "./argument.js";
-import type { Group, Node } from "./command.js";
-import type { FlagSpec } from "./flag.js";
-/** One declared flag with the property its handler reads it as. */
-export interface FlagEntry {
-    key: string;
-    spec: FlagSpec;
-}
-/** One declared argument with the property its handler reads it as. */
-export interface ArgumentEntry {
-    key: string;
-    spec: ArgumentSpec;
-}
-/** One command or group in the indexed contract. */
-export interface Entry {
-    node: Node;
-    /** The names typed after the program to reach it; empty for the root. */
-    path: readonly string[];
-    /** The program name and the path, as the help and every error print it. */
-    title: string;
-    parent: Entry | undefined;
-    /** Members by name; empty for a command. */
-    children: ReadonlyMap<string, Entry>;
-    arguments: readonly ArgumentEntry[];
-    flags: readonly FlagEntry[];
-    /** Flags by long name and by alias. */
-    longs: ReadonlyMap<string, FlagEntry>;
-    shorts: ReadonlyMap<string, FlagEntry>;
-    /** Its handler runs tasks, so the help lists `--no-progress`. */
-    tasks: boolean;
-    /** It declares `argument.rest()`, so every token after its name reaches it unparsed. */
-    rest: boolean;
-}
-/** The whole indexed contract. */
-export interface Tree {
-    root: Entry;
-    entries: ReadonlyMap<Node, Entry>;
-    /** The commands declaring each long name or alias, for naming them in a usage error. */
-    owners: ReadonlyMap<string, readonly Entry[]>;
-}
-/**
- * Indexes `root` under the program `name`.
- *
- * @throws Error When a command or group appears twice in the tree, a flag takes a reserved name
- * (`help`, `version`, `progress`, `-h`) or a name starting with `no-`, two flags of one command
- * share a name, a variadic argument is not the last one, or a command with `argument.rest()`
- * declares flags or another argument. Each is a contract mistake that would make a command
- * unreachable or ambiguous.
- */
-export declare function buildTree(name: string, root: Group): Tree;

package/dist/tree.js

@@ -1,97 +0,0 @@
-/**
- * The indexed contract a CLI parses against: every command and group with its path, flag
- * lookup by long name, alias and short alias, and which commands own each flag name. Built once
- * by `createCLI`, so a contract mistake fails at startup instead of on the run that reaches it.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import { argumentSpec } from "./argument.js";
-import { groupSpec, isGroup } from "./command.js";
-import { flagSpec } from "./flag.js";
-/** Long names every command answers to, so no flag may take them. */
-const RESERVED_NAMES = new Set(["help", "version", "progress"]);
-/** Short names every command answers to. */
-const RESERVED_SHORTS = new Set(["h"]);
-/**
- * Indexes `root` under the program `name`.
- *
- * @throws Error When a command or group appears twice in the tree, a flag takes a reserved name
- * (`help`, `version`, `progress`, `-h`) or a name starting with `no-`, two flags of one command
- * share a name, a variadic argument is not the last one, or a command with `argument.rest()`
- * declares flags or another argument. Each is a contract mistake that would make a command
- * unreachable or ambiguous.
- */
-export function buildTree(name, root) {
-    let entries = new Map();
-    let owners = new Map();
-    /** Indexes one node and everything under it. */
-    function visit(node, path, parent) {
-        if (entries.has(node)) {
-            throw new Error(`${[name, ...path].join(" ")} reuses a command already in the tree`);
-        }
-        let title = [name, ...path].join(" ");
-        let children = new Map();
-        let flags = [];
-        let longs = new Map();
-        let shorts = new Map();
-        let args = [];
-        let declaration = isGroup(node) ? groupSpec(node) : node;
-        for (let [key, declared] of Object.entries(declaration.flags)) {
-            let flag = { key, spec: flagSpec(declared) };
-            for (let long of [flag.spec.name, ...flag.spec.aliases]) {
-                if (RESERVED_NAMES.has(long) || long.startsWith("no-")) {
-                    throw new Error(`${title}: --${long} is reserved for every command`);
-                }
-                if (longs.has(long))
-                    throw new Error(`${title}: two flags are named --${long}`);
-                longs.set(long, flag);
-            }
-            let short = flag.spec.short;
-            if (short !== undefined) {
-                if (short.length !== 1 || RESERVED_SHORTS.has(short)) {
-                    throw new Error(`${title}: -${short} must be one character other than h`);
-                }
-                if (shorts.has(short))
-                    throw new Error(`${title}: two flags are named -${short}`);
-                shorts.set(short, flag);
-            }
-            flags.push(flag);
-        }
-        let entriesOfArguments = Object.entries(declaration.arguments);
-        entriesOfArguments.forEach(([key, declared], index) => {
-            let spec = argumentSpec(declared);
-            if (spec.variadic && index < entriesOfArguments.length - 1) {
-                throw new Error(`${title}: the variadic argument <${key}> must be the last one`);
-            }
-            args.push({ key, spec });
-        });
-        let rest = args.some((arg) => arg.spec.rest);
-        if (rest && (isGroup(node) || flags.length > 0 || args.length !== 1)) {
-            throw new Error(`${title}: argument.rest() is a command's only argument, with no flags`);
-        }
-        let entry = {
-            node,
-            path,
-            title,
-            parent,
-            children,
-            arguments: args,
-            flags,
-            longs,
-            shorts,
-            tasks: declaration.tasks,
-            rest,
-        };
-        entries.set(node, entry);
-        for (let long of longs.keys())
-            owners.set(long, [...(owners.get(long) ?? []), entry]);
-        if (isGroup(node)) {
-            for (let [member, child] of Object.entries(groupSpec(node).members)) {
-                children.set(member, visit(child, [...path, member], entry));
-            }
-        }
-        return entry;
-    }
-    return { root: visit(root, [], undefined), entries, owners };
-}