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

package/dist/resolve.js

@@ -1,294 +0,0 @@
-/**
- * Turns what the command line gave into the values a handler reads: each flag and argument
- * converted, checked by its schema, asked for when missing on a terminal, or defaulted. Every
- * value typed wrong is reported in one usage error before any question is asked.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import { failure, isFailure, success } from "@sdxc/result";
-import { isGroup } from "./command.js";
-import { CancelledError, UsageError } from "./errors.js";
-import { validate } from "./schema.js";
-import { closest } from "./suggest.js";
-/** A value that failed, as one line of the usage error. */
-class Issues {
-    lines = [];
-    add(label, messages) {
-        for (let message of messages)
-            this.lines.push(`${label}: ${message}`);
-    }
-}
-/**
- * The issue for a word a group's first argument rejects: the word was tried as a member's name
- * first, so it reads as a mistyped command, with the closest member suggested.
- */
-function unknownMember(entry, word) {
-    let suggestion = closest(word, entry.children.keys());
-    let hint = suggestion === undefined ? "" : `; did you mean "${suggestion}"?`;
-    return `Unknown command "${word}" for ${entry.title}${hint}`;
-}
-/** Text read as a number, or `undefined` when it is not one. */
-function toNumber(text) {
-    if (text.trim() === "")
-        return undefined;
-    let value = Number(text);
-    return Number.isNaN(value) ? undefined : value;
-}
-/**
- * Converts and checks each item of one input: numbers read from text for a number flag, then
- * the schema. Answers the outputs, or the messages of every item that failed.
- */
-async function checkItems(items, kind, schema) {
-    let outputs = [];
-    let messages = [];
-    for (let item of items) {
-        let value = item;
-        if (kind === "number" && typeof item === "string") {
-            let number = toNumber(item);
-            if (number === undefined) {
-                messages.push(`expects a number, got ${JSON.stringify(item)}`);
-                continue;
-            }
-            value = number;
-        }
-        let checked = await validate(schema, value);
-        if (isFailure(checked))
-            messages.push(...checked.error.messages);
-        else
-            outputs.push(checked.data);
-    }
-    if (messages.length > 0) {
-        return failure(Object.assign(new Error(messages.join("; ")), { messages }));
-    }
-    return success(outputs);
-}
-/** Splits a comma list, dropping blanks. */
-function splitList(text) {
-    return text
-        .split(",")
-        .map((part) => part.trim())
-        .filter((part) => part !== "");
-}
-/** An answer as items: a list as it is, text split when the flag is a comma list. */
-function answerItems(answer, list) {
-    if (Array.isArray(answer))
-        return answer;
-    if (list && typeof answer === "string")
-        return splitList(answer);
-    return [answer];
-}
-/**
- * Resolves `parsed`'s command into the values its handler reads. The parser's own issues lead
- * the usage error, followed by every value that failed its conversion or schema.
- *
- * @returns The inputs, a usage failure listing every problem, a cancelled failure, or the
- * failure of a scripted answer that was missing or rejected
- */
-export async function resolveInputs(parsed, session) {
-    let entry = parsed.entry;
-    let inputs = { arguments: {}, flags: {} };
-    let issues = new Issues();
-    issues.lines.push(...parsed.issues);
-    let missing = [];
-    let positionals = [...parsed.positionals];
-    for (let { key, spec } of entry.arguments) {
-        let label = `<${spec.valueName ?? key}>`;
-        let given = spec.variadic ? positionals.splice(0) : positionals.splice(0, 1);
-        let check = async (answer) => {
-            let items = answerItems(answer, false);
-            if (spec.variadic && items.length < spec.min) {
-                return failure(new Error(`needs at least ${spec.min} value${spec.min === 1 ? "" : "s"}`));
-            }
-            if (spec.variadic && items.length > spec.max) {
-                return failure(new Error(`takes at most ${spec.max} value${spec.max === 1 ? "" : "s"}`));
-            }
-            let checked = await checkItems(items, "string", spec.schema);
-            if (isFailure(checked))
-                return checked;
-            return success(spec.variadic ? checked.data : checked.data[0]);
-        };
-        if (given.length === 0) {
-            let fallback = spec.hasDefault
-                ? { value: spec.default }
-                : spec.optional
-                    ? { value: undefined }
-                    : spec.variadic && spec.min === 0
-                        ? { value: [] }
-                        : undefined;
-            missing.push({
-                label,
-                names: [key],
-                spec,
-                assign: (value) => {
-                    inputs.arguments[key] = value;
-                },
-                check,
-                fallback,
-            });
-            continue;
-        }
-        let checked = await check(spec.variadic ? given : given[0]);
-        if (isFailure(checked) && isGroup(entry.node) && key === entry.arguments[0]?.key) {
-            issues.lines.push(unknownMember(entry, given[0]));
-        }
-        else if (isFailure(checked))
-            issues.add(label, [checked.error.message]);
-        else
-            inputs.arguments[key] = checked.data;
-    }
-    for (let extra of positionals)
-        issues.lines.push(`Unexpected argument ${JSON.stringify(extra)}`);
-    for (let { key, spec } of entry.flags) {
-        let label = `--${spec.name}`;
-        let occurrences = parsed.occurrences.get(key) ?? [];
-        let many = spec.multiple || spec.list;
-        let check = async (answer) => {
-            if (spec.kind === "boolean")
-                return success(answer === true);
-            if (spec.optionalValue && answer === true)
-                return success(true);
-            let checked = await checkItems(answerItems(answer, spec.list), spec.kind, spec.schema);
-            if (isFailure(checked))
-                return checked;
-            return success(many ? checked.data : checked.data[0]);
-        };
-        if (occurrences.length === 0) {
-            let fallback = spec.hasDefault
-                ? { value: spec.default }
-                : spec.kind === "boolean"
-                    ? { value: false }
-                    : spec.required
-                        ? undefined
-                        : { value: many ? [] : undefined };
-            missing.push({
-                label,
-                names: [key, spec.name],
-                spec,
-                assign: (value) => {
-                    inputs.flags[key] = value;
-                },
-                check,
-                fallback,
-            });
-            continue;
-        }
-        if (spec.kind === "boolean") {
-            let plain = occurrences.find((occurrence) => !occurrence.negated);
-            let negated = occurrences.find((occurrence) => occurrence.negated);
-            if (plain !== undefined && negated !== undefined) {
-                issues.lines.push(`${plain.spelled} and ${negated.spelled} cannot be passed together`);
-                continue;
-            }
-            inputs.flags[key] = !occurrences.at(-1).negated;
-            continue;
-        }
-        let values = [];
-        let bare = false;
-        let broken = false;
-        for (let occurrence of occurrences) {
-            if (occurrence.value === true) {
-                bare = true;
-                continue;
-            }
-            if (!spec.list) {
-                values.push(occurrence);
-                continue;
-            }
-            let parts = splitList(occurrence.value);
-            if (parts.length === 0) {
-                issues.lines.push(`${occurrence.spelled} needs a value`);
-                broken = true;
-            }
-            for (let part of parts)
-                values.push({ ...occurrence, value: part });
-        }
-        if (broken)
-            continue;
-        if (bare) {
-            inputs.flags[key] = true;
-            continue;
-        }
-        if (!many)
-            values = values.slice(-1);
-        let outputs = [];
-        for (let value of values) {
-            let checked = await checkItems([value.value], spec.kind, spec.schema);
-            if (isFailure(checked))
-                issues.add(value.spelled, checked.error.messages);
-            else
-                outputs.push(checked.data[0]);
-        }
-        if (outputs.length === values.length)
-            inputs.flags[key] = many ? outputs : outputs[0];
-    }
-    if (issues.lines.length > 0)
-        return failure(new UsageError(issues.lines.join("\n")));
-    for (let input of missing) {
-        let declared = input.spec.prompt;
-        let asks = declared !== undefined &&
-            session.interactive &&
-            (!input.spec.hasDefault ||
-                input.spec.default === undefined ||
-                declared.options.ask === "always");
-        if (!asks || declared === undefined) {
-            if (input.fallback !== undefined)
-                input.assign(input.fallback.value);
-            else if (declared !== undefined) {
-                issues.lines.push(`${input.label} is required when stdin is not a terminal`);
-            }
-            else if (input.label.startsWith("<"))
-                issues.lines.push(`Missing argument ${input.label}`);
-            else
-                issues.lines.push(`${input.label} is required`);
-            continue;
-        }
-        if (issues.lines.length > 0)
-            continue;
-        let answered = await session.ask({
-            kind: declared.kind,
-            options: declared.options,
-            names: input.names,
-            label: input.label,
-            initial: input.spec.hasDefault ? input.spec.default : undefined,
-            check: input.check,
-        });
-        if (isFailure(answered))
-            return answered;
-        input.assign(answered.data);
-    }
-    if (issues.lines.length > 0)
-        return failure(new UsageError(issues.lines.join("\n")));
-    return success(inputs);
-}
-/** The `ctx.prompt` of one run: asks on a terminal or from a script, else answers the default. */
-export function createPrompter(session) {
-    /** Asks one handler-called prompt. */
-    let ask = async (kind, options) => {
-        if (!session.interactive)
-            return success(options.default);
-        if (session.signal.aborted)
-            return failure(new CancelledError());
-        let request = {
-            kind,
-            options,
-            names: options.name === undefined ? [] : [options.name],
-            label: options.name ?? JSON.stringify(options.message),
-            initial: "initial" in options ? options.initial : options.default,
-            async check(answer) {
-                let checked = await validate(options.schema, answer);
-                return isFailure(checked) ? failure(new Error(checked.error.message)) : success(answer);
-            },
-        };
-        return (await session.ask(request));
-    };
-    return {
-        text: (options) => ask("text", options),
-        password: (options) => ask("password", options),
-        number: (options) => ask("number", options),
-        confirm: (options) => ask("confirm", options),
-        select: (options) => ask("select", options),
-        multiselect: (options) => ask("multiselect", options),
-        search: ((options) => ask("search", options)),
-    };
-}

package/dist/schema.d.ts

@@ -1,27 +0,0 @@
-/**
- * Runs a Standard Schema over one command-line value, synchronous or asynchronous alike, and
- * answers its output or the issue messages, so every argument, flag and prompt answer is checked
- * by the schema it was declared with.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import type { Result } from "@sdxc/result";
-import type { StandardSchemaV1 } from "@standard-schema/spec";
-/** A value's issues, each as the message the user reads after the input's name. */
-export declare class SchemaIssues extends Error {
-    name: string;
-    /** One message per issue, in the order the schema reported them. */
-    messages: readonly string[];
-    /** @param messages - The schema's issue messages */
-    constructor(messages: readonly string[]);
-}
-/**
- * `value` checked by `schema`, or its issues. A missing schema accepts the value unchanged.
- *
- * @param schema - Any Standard Schema
- * @param value - What the command line, a prompt or a default supplied
- */
-export declare function validate(schema: StandardSchemaV1 | undefined, value: unknown): Promise<Result<unknown, SchemaIssues>>;
-/** The output type of a Standard Schema. */
-export type SchemaOutput<Schema> = Schema extends StandardSchemaV1<infer _Input, infer Output> ? Output : never;

package/dist/schema.js

@@ -1,34 +0,0 @@
-/**
- * Runs a Standard Schema over one command-line value, synchronous or asynchronous alike, and
- * answers its output or the issue messages, so every argument, flag and prompt answer is checked
- * by the schema it was declared with.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import { failure, success } from "@sdxc/result";
-/** A value's issues, each as the message the user reads after the input's name. */
-export class SchemaIssues extends Error {
-    name = "SchemaIssues";
-    /** One message per issue, in the order the schema reported them. */
-    messages;
-    /** @param messages - The schema's issue messages */
-    constructor(messages) {
-        super(messages.join("; "));
-        this.messages = messages;
-    }
-}
-/**
- * `value` checked by `schema`, or its issues. A missing schema accepts the value unchanged.
- *
- * @param schema - Any Standard Schema
- * @param value - What the command line, a prompt or a default supplied
- */
-export async function validate(schema, value) {
-    if (schema === undefined)
-        return success(value);
-    let outcome = await schema["~standard"].validate(value);
-    if (outcome.issues === undefined)
-        return success(outcome.value);
-    return failure(new SchemaIssues(outcome.issues.map((issue) => issue.message)));
-}

package/dist/screen.d.ts

@@ -1,42 +0,0 @@
-/**
- * The one owner of the terminal during a run: a live region at the bottom of stderr that tasks
- * and prompts redraw in place, with every other write going above it. A write clears the region,
- * writes, and redraws it, so command output and spinner frames never interleave.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-/** A writable stream a CLI prints to; `process.stdout` and `process.stderr` are ones. */
-export interface Output {
-    write(text: string): unknown;
-    isTTY?: boolean;
-    /** The terminal's width in columns. */
-    columns?: number;
-}
-/** The live region on stderr and every write that goes around it. */
-export declare class Screen {
-    #private;
-    /** The stream the region is drawn on. */
-    readonly stderr: Output;
-    /** @param stderr - The stream the region is drawn on */
-    constructor(stderr: Output);
-    /** The terminal's width. */
-    get columns(): number;
-    /** Whether a prompt or a child process holds the region. */
-    get held(): boolean;
-    /** Sets what the region shows when nobody holds it: the running tasks. */
-    onRefresh(refresh: () => void): void;
-    /** Replaces the region with `lines`; an empty list clears it and shows the cursor. */
-    paint(lines: readonly string[]): void;
-    /**
-     * Writes `text` to `target` above the region: the region is cleared first and redrawn
-     * after, when `target` shares the terminal with it.
-     */
-    write(target: Output, text: string): void;
-    /** Takes the region for a prompt or a child process, clearing what the tasks drew. */
-    hold(): void;
-    /** Gives the region back, and the tasks redraw it. */
-    release(): void;
-    /** Clears the region and shows the cursor, as any exit must leave the terminal. */
-    restore(): void;
-}

package/dist/screen.js

@@ -1,114 +0,0 @@
-/**
- * The one owner of the terminal during a run: a live region at the bottom of stderr that tasks
- * and prompts redraw in place, with every other write going above it. A write clears the region,
- * writes, and redraws it, so command output and spinner frames never interleave.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import { visibleWidth } from "./style.js";
-/** Hides the cursor while the region is drawn. */
-const HIDE_CURSOR = "\u001B[?25l";
-/** Shows it again. */
-const SHOW_CURSOR = "\u001B[?25h";
-/** Erases from the cursor to the end of the screen. */
-const ERASE_DOWN = "\u001B[J";
-/** The width assumed for a stream that does not report one. */
-const DEFAULT_COLUMNS = 80;
-/** The live region on stderr and every write that goes around it. */
-export class Screen {
-    /** The stream the region is drawn on. */
-    stderr;
-    /** The lines the region shows now. */
-    #lines = [];
-    /** How many terminal rows those lines take, wrapping included. */
-    #rows = 0;
-    #cursorHidden = false;
-    /** How many callers hold the region for themselves (a prompt, a child process). */
-    #holds = 0;
-    /** Redraws the region's usual content when nobody holds it. */
-    #refresh = () => undefined;
-    /** @param stderr - The stream the region is drawn on */
-    constructor(stderr) {
-        this.stderr = stderr;
-    }
-    /** The terminal's width. */
-    get columns() {
-        let columns = this.stderr.columns ?? 0;
-        return columns > 0 ? columns : DEFAULT_COLUMNS;
-    }
-    /** Whether a prompt or a child process holds the region. */
-    get held() {
-        return this.#holds > 0;
-    }
-    /** Sets what the region shows when nobody holds it: the running tasks. */
-    onRefresh(refresh) {
-        this.#refresh = refresh;
-    }
-    /** Replaces the region with `lines`; an empty list clears it and shows the cursor. */
-    paint(lines) {
-        let text = this.#erase();
-        if (lines.length === 0) {
-            if (this.#cursorHidden)
-                text += SHOW_CURSOR;
-            this.#cursorHidden = false;
-            this.#lines = [];
-            if (text !== "")
-                this.stderr.write(text);
-            return;
-        }
-        if (!this.#cursorHidden)
-            text += HIDE_CURSOR;
-        this.#cursorHidden = true;
-        text += lines.join("\n");
-        this.#lines = lines;
-        this.#rows = lines.reduce((rows, line) => rows + this.#rowsOf(line), 0);
-        this.stderr.write(text);
-    }
-    /**
-     * Writes `text` to `target` above the region: the region is cleared first and redrawn
-     * after, when `target` shares the terminal with it.
-     */
-    write(target, text) {
-        let shared = target === this.stderr || target.isTTY === true;
-        if (this.#rows === 0 || !shared) {
-            target.write(text);
-            return;
-        }
-        let lines = this.#lines;
-        this.paint([]);
-        target.write(text);
-        this.paint(lines);
-    }
-    /** Takes the region for a prompt or a child process, clearing what the tasks drew. */
-    hold() {
-        this.#holds += 1;
-        if (this.#holds === 1)
-            this.paint([]);
-    }
-    /** Gives the region back, and the tasks redraw it. */
-    release() {
-        this.#holds = Math.max(0, this.#holds - 1);
-        if (this.#holds === 0)
-            this.#refresh();
-    }
-    /** Clears the region and shows the cursor, as any exit must leave the terminal. */
-    restore() {
-        this.paint([]);
-        if (this.#cursorHidden)
-            this.stderr.write(SHOW_CURSOR);
-        this.#cursorHidden = false;
-    }
-    /** The sequence that erases the region, leaving the cursor where it began. */
-    #erase() {
-        if (this.#rows === 0)
-            return "";
-        let up = this.#rows > 1 ? `\u001B[${this.#rows - 1}A` : "";
-        this.#rows = 0;
-        return `\r${up}${ERASE_DOWN}`;
-    }
-    /** How many rows `line` takes once the terminal wraps it. */
-    #rowsOf(line) {
-        return Math.max(1, Math.ceil(visibleWidth(line) / this.columns));
-    }
-}

package/dist/session.d.ts

@@ -1,84 +0,0 @@
-/**
- * One run's process context: its working directory, environment and streams, whether it may
- * ask questions, the terminal owner tasks and prompts draw through, and the signal Ctrl+C
- * aborts. Built from `cli.run`'s options, each defaulting to the process's own.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import type { Result } from "@sdxc/result";
-import type { Exec, ExecOptions, ExecOutput, ExecError } from "./exec.js";
-import type { Input, Keyboard } from "./keys.js";
-import type { PromptKind, PromptKinds } from "./prompt.js";
-import type { Output } from "./screen.js";
-import type { Env, Style } from "./style.js";
-import { CancelledError } from "./errors.js";
-import { Screen } from "./screen.js";
-import { Tasks } from "./task.js";
-/** What `cli.run` replaces of the process: any option left out is the process's own. */
-export interface RunIO {
-    cwd?: string;
-    env?: Env;
-    stdin?: Input;
-    stdout?: Output;
-    stderr?: Output;
-    /** Runs `ctx.exec`'s commands. */
-    exec?: Exec;
-    /**
-     * Aborting it stops the run the way Ctrl+C does. Without one, the run listens for SIGINT and
-     * SIGTERM itself while it lasts.
-     */
-    signal?: AbortSignal;
-}
-/** How a test harness answers prompts in place of a person. */
-export interface Script {
-    /** By the name a prompt answers to, or in the order prompts are asked. */
-    answers: Readonly<Record<string, unknown>> | readonly unknown[] | undefined;
-    /** Reads keys from a virtual terminal; without one, prompts take scripted answers. */
-    keyboard: (() => Keyboard) | undefined;
-    /** Whether stdin counts as a terminal, which decides whether prompts are asked at all. */
-    interactive: boolean;
-}
-/** One question to ask, in the shape both bound and handler-called prompts reduce to. */
-export interface PromptRequest {
-    kind: PromptKind;
-    options: PromptKinds[PromptKind];
-    /** Names a scripted `answers` object may answer it by. */
-    names: readonly string[];
-    /** How errors about it name it: `--template`, `<directory>`, or its message. */
-    label: string;
-    /** The default, shown dimmed or preselected. */
-    initial: unknown;
-    /** Converts and checks an answer; the issue keeps the prompt open. */
-    check(answer: unknown): Promise<Result<unknown, Error>>;
-}
-/** The process context of one run. */
-export interface Session {
-    cwd: string;
-    env: Env;
-    stdin: Input;
-    stdout: Output;
-    stderr: Output;
-    /** Styling for stdout, with stderr's under `stderr`. */
-    style: Style & {
-        readonly stderr: Style;
-    };
-    screen: Screen;
-    tasks: Tasks;
-    signal: AbortSignal;
-    /** Whether prompts are asked; otherwise defaults apply. */
-    interactive: boolean;
-    /** Whether tasks animate, false once `--no-progress` is passed. */
-    animate: boolean;
-    ask(request: PromptRequest): Promise<Result<unknown, Error>>;
-    exec(command: readonly string[], options?: ExecOptions): Promise<Result<ExecOutput, ExecError | CancelledError>>;
-    /** Stops tasks, clears the frame, shows the cursor and stops listening for signals. */
-    close(): void;
-}
-/**
- * Opens the session for one run.
- *
- * @param noProgress - Whether `--no-progress` was passed
- * @param script - How a test answers prompts; `undefined` for a person at a terminal
- */
-export declare function openSession(io: RunIO, noProgress: boolean, script: Script | undefined): Session;