@sdxc/cli 0.0.0-stage → 2026.10.20

package/dist/context.js

@@ -0,0 +1,175 @@
+/**
+ * The context a command's middleware and handler receive: its parsed arguments and flags, the
+ * process it runs in (working directory, environment, output, prompts, tasks, child processes)
+ * and the values middleware published, readable by key or as installed properties.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * One command's run. A test builds one through `invoke()` from `@sdxc/cli/test`; a middleware
+ * publishes services with `set()`, which a handler reads as `ctx.<property>`.
+ *
+ * @example ctx.set(Database, connect(ctx.env.DATABASE_URL), { property: "db" });
+ */
+export class CommandContext {
+    /**
+     * The arguments the run was given, exactly as `cli.run` received them: the command's names,
+     * flags and values before parsing, for logging a run or starting it again.
+     */
+    argv;
+    /** The command's names after the program, `["ui", "add"]` for `sdxc ui add`. */
+    path;
+    /** The positional arguments, parsed, prompted for, or defaulted. */
+    arguments;
+    /** The flags, parsed, prompted for, or defaulted. */
+    flags;
+    cwd;
+    env;
+    /** Styling for stdout; `style.stderr` styles stderr, each off for a stream that is not a terminal. */
+    style;
+    /** Aborts on Ctrl+C. */
+    signal;
+    /**
+     * Questions a handler asks itself. Each takes a `default`, which answers without a
+     * terminal, so the command stays runnable in CI.
+     */
+    prompt;
+    /**
+     * Runs async work under a spinner, answering a `Result`; the label is optional.
+     *
+     * @example let posts = await ctx.task("Fetching posts", (task) => fetch(url, { signal: task.signal }));
+     */
+    task;
+    /**
+     * What the command was piped. `stdin.isTTY` is true at a terminal, where `text()` would wait
+     * for the user to end input, so a handler reads it only when `isTTY` is false.
+     *
+     * @example let sql = ctx.flags.execute ?? (ctx.stdin.isTTY ? undefined : await ctx.stdin.text());
+     */
+    stdin;
+    #session;
+    #values = new Map();
+    #execEnv = {};
+    /** @param init - The parsed command and the run it belongs to */
+    constructor(init) {
+        this.argv = init.argv;
+        this.path = init.path;
+        this.arguments = init.arguments;
+        this.flags = init.flags;
+        this.cwd = init.session.cwd;
+        this.env = init.session.env;
+        this.style = init.session.style;
+        this.signal = init.session.signal;
+        this.prompt = init.prompt;
+        this.task = init.session.tasks.task;
+        this.stdin = createStdin(init.session.stdin);
+        this.#session = init.session;
+    }
+    /** Writes to stdout, above any running task. */
+    stdout = (text) => {
+        this.#session.screen.write(this.#session.stdout, text);
+    };
+    /** Writes to stderr, above any running task. */
+    stderr = (text) => {
+        this.#session.screen.write(this.#session.stderr, text);
+    };
+    /**
+     * Runs a program with no shell, answering its exit code and output, or an `ExecError` when
+     * it fails to start or exits non-zero. `"inherit"` and `"stderr"` output pauses any spinner
+     * until the child exits.
+     *
+     * @param command - The program and its arguments, passed through exactly
+     * @example let status = await ctx.exec(["git", "status", "--short"], { stdio: "collect" });
+     */
+    exec(command, options) {
+        return this.#session.exec(command, {
+            ...options,
+            env: { ...this.#execEnv, ...options?.env },
+        });
+    }
+    /**
+     * Adds variables every child `exec` starts with, over the run's `env` and under a call's own
+     * `options.env`, so a middleware hands children what it knows (a trace parent) and a caller
+     * still overrides it. An `undefined` value removes the variable from children.
+     *
+     * @param variables - Merged over what earlier calls added
+     * @example ctx.setExecEnv({ TRACEPARENT: toTraceParent(trace) });
+     */
+    setExecEnv(variables) {
+        this.#execEnv = { ...this.#execEnv, ...variables };
+    }
+    /**
+     * Reads a value some middleware published.
+     *
+     * @param key - The context key to read
+     * @returns Its value, the key's default, or `undefined`
+     */
+    get(key) {
+        if (this.#values.has(key))
+            return this.#values.get(key);
+        return key.defaultValue;
+    }
+    /**
+     * Reads a value an earlier middleware must have published. A middleware sees the bare
+     * context, without the properties earlier ones installed, so this is how it reads them
+     * without an `undefined` it has no answer for; a missing value fails the run with exit 1.
+     *
+     * @param key - The context key to read
+     * @throws Error When nothing published a value for the key
+     * @example let db = ctx.require(Database);
+     */
+    require(key) {
+        let value = this.get(key);
+        if (value === undefined || value === null) {
+            throw new Error(`${this.path.join(" ")} read a context key that no middleware published`);
+        }
+        return value;
+    }
+    /**
+     * Whether a value has been published for a key.
+     *
+     * @param key - The context key to check
+     */
+    has(key) {
+        return this.#values.has(key);
+    }
+    /**
+     * Publishes a value for a key, optionally installing it as a read-only property so handlers
+     * read `ctx.db` rather than `ctx.get(Database)`.
+     *
+     * @param key - The context key to write
+     * @param value - The value to publish
+     * @param options - The property name to install it under
+     */
+    set(key, value, options) {
+        this.#values.set(key, value);
+        if (options === undefined)
+            return;
+        Object.defineProperty(this, options.property, {
+            value,
+            configurable: true,
+            enumerable: true,
+            writable: false,
+        });
+    }
+}
+/** A reader over `input` that reads it to the end at most once. */
+function createStdin(input) {
+    let reading;
+    return {
+        isTTY: input.isTTY === true,
+        text() {
+            reading ??= new Promise((resolve, reject) => {
+                let chunks = [];
+                input.on("data", (chunk) => {
+                    chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+                });
+                input.once("end", () => resolve(chunks.join("")));
+                input.once("error", reject);
+                input.resume();
+            });
+            return reading;
+        },
+    };
+}

package/dist/describe.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The contract as plain data: every command with its arguments, flags and examples, the same
+ * facts the help prints. `--help --json` prints it, and a tool reads it to check what a script,
+ * a guide or an agent passes against what the program accepts.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { FlagKind } from "./flag.js";
+import type { Entry } from "./tree.js";
+/** One argument of a command, in the order the command line takes them. */
+export interface ArgumentDescription {
+    name: string;
+    description: string | null;
+    /** A value is needed; a missing one is asked for on a terminal when the argument prompts. */
+    required: boolean;
+    /** Takes every remaining positional. */
+    variadic: boolean;
+    /** Takes every token after the command's name unparsed, flags included. */
+    rest: boolean;
+    /** The default, when one is declared. */
+    default?: unknown;
+}
+/** One flag of a command, or one every command answers to (`builtin`). */
+export interface FlagDescription {
+    /** The long name, written `--<name>`. */
+    name: string;
+    aliases: string[];
+    /** The one-character alias, written `-<short>`. */
+    short: string | null;
+    kind: FlagKind;
+    /** A boolean's `--no-<name>` spelling is accepted. */
+    negatable: boolean;
+    /** What the help shows in `<…>` after the flag; `null` for a boolean. */
+    value: string | null;
+    /** The flag may appear bare or with `=value`. */
+    optionalValue: boolean;
+    /** One value holds several, separated by commas. */
+    list: boolean;
+    /** Repeating the flag collects every value. */
+    repeatable: boolean;
+    required: boolean;
+    description: string | null;
+    /** Answered by every command the program runs: `--help`, `--version`, `--no-progress`. */
+    builtin: boolean;
+    /** The default, when one is declared. */
+    default?: unknown;
+}
+/** One command or group, with every visible member below it. */
+export interface CommandDescription {
+    /** The words typed after the program to reach it; empty for the root. */
+    path: string[];
+    /** The program name and the path, as the help prints it. */
+    title: string;
+    description: string | null;
+    arguments: ArgumentDescription[];
+    flags: FlagDescription[];
+    /** Example command lines, each starting with the program name. */
+    examples: string[];
+    /** Members of a group by name; empty for a command. */
+    commands: CommandDescription[];
+}
+/** The program's own facts the description includes beside the contract. */
+export interface DescribeProgram {
+    version: string | undefined;
+    description: string | undefined;
+}
+/**
+ * Describes `entry` and every visible member under it. Hidden commands and flags stay out, as
+ * they do from the help.
+ */
+export declare function describeEntry(entry: Entry, program: DescribeProgram): CommandDescription;

package/dist/describe.js

@@ -0,0 +1,88 @@
+/**
+ * The contract as plain data: every command with its arguments, flags and examples, the same
+ * facts the help prints. `--help --json` prints it, and a tool reads it to check what a script,
+ * a guide or an agent passes against what the program accepts.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { groupSpec, isGroup } from "./command.js";
+/**
+ * Describes `entry` and every visible member under it. Hidden commands and flags stay out, as
+ * they do from the help.
+ */
+export function describeEntry(entry, program) {
+    let node = entry.node;
+    let spec = isGroup(node) ? groupSpec(node) : node;
+    let description = spec.description ?? (entry.parent === undefined ? program.description : undefined);
+    let flags = entry.flags.filter(({ spec }) => !spec.hidden).map(({ spec }) => describeFlag(spec));
+    if (entry.tasks)
+        flags.push(builtin("progress", "Print tasks without animation", true));
+    if (program.version !== undefined && entry.parent === undefined) {
+        flags.push(builtin("version", "Print the version", false));
+    }
+    flags.push({ ...builtin("help", "Show this help", false), short: "h" });
+    let programName = entry.title.split(" ")[0];
+    let commands = [];
+    for (let child of entry.children.values()) {
+        let childSpec = isGroup(child.node) ? groupSpec(child.node) : child.node;
+        if (childSpec.hidden)
+            continue;
+        commands.push(describeEntry(child, program));
+    }
+    return {
+        path: [...entry.path],
+        title: entry.title,
+        description: description ?? null,
+        arguments: entry.arguments.map(({ key, spec }) => ({
+            name: spec.valueName ?? key,
+            description: spec.description ?? null,
+            required: !spec.optional && !spec.hasDefault && (spec.variadic ? spec.min > 0 : true),
+            variadic: spec.variadic,
+            rest: spec.rest,
+            ...(spec.hasDefault ? { default: spec.default } : {}),
+        })),
+        flags,
+        examples: isGroup(node) ? [] : node.examples.map((example) => `${programName} ${example}`),
+        commands,
+    };
+}
+/** A declared flag as data. */
+function describeFlag(spec) {
+    let boolean = spec.kind === "boolean";
+    return {
+        name: spec.name,
+        aliases: [...spec.aliases],
+        short: spec.short ?? null,
+        kind: spec.kind,
+        negatable: boolean,
+        value: boolean ? null : (spec.valueName ?? (spec.kind === "number" ? "number" : "value")),
+        optionalValue: spec.optionalValue,
+        list: spec.list,
+        repeatable: spec.multiple,
+        required: spec.required && spec.prompt === undefined,
+        description: spec.description ?? null,
+        builtin: false,
+        ...(spec.hasDefault && spec.default !== undefined ? { default: spec.default } : {}),
+    };
+}
+/**
+ * A flag the runtime answers for every command. `--no-progress` is the one spelled negated, so
+ * its name is `progress` and it is negatable.
+ */
+function builtin(name, description, negatable) {
+    return {
+        name,
+        aliases: [],
+        short: null,
+        kind: "boolean",
+        negatable,
+        value: null,
+        optionalValue: false,
+        list: false,
+        repeatable: false,
+        required: false,
+        description,
+        builtin: true,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The failures a command answers and the exit codes they map to: a usage failure prints the
+ * command's help and exits 2, a cancelled one exits 130 in silence, an exit failure picks its
+ * own code, and any other failure prints its message and exits 1.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Failure, Success } from "@sdxc/result";
+/** The exit code each outcome of a run maps to, shared by every command line built here. */
+export declare const EXIT_CODES: {
+    readonly success: 0;
+    readonly failure: 1;
+    readonly usage: 2;
+    readonly cancelled: 130;
+};
+/** A command line the user wrote wrong; the run prints the message and the command's help. */
+export declare class UsageError extends Error {
+    name: string;
+}
+/**
+ * The user stopped the run, with Ctrl+C or Escape at a prompt or Ctrl+C during a task. The run
+ * exits 130 and writes nothing more, since the user already knows why it stopped.
+ */
+export declare class CancelledError extends Error {
+    name: string;
+    /** @param message - Read only by code that logs the failure; the run itself prints nothing */
+    constructor(message?: string);
+}
+/**
+ * A failure that picks its own exit code. An empty message prints nothing, for a command that
+ * already reported what went wrong, such as a test runner that printed its failed tests.
+ */
+export declare class ExitError extends Error {
+    name: string;
+    /** The process exit code the run answers. */
+    code: number;
+    /**
+     * @param code - The exit code
+     * @param message - What the run prints on stderr, nothing when empty
+     */
+    constructor(code: number, message?: string);
+}
+/**
+ * A successful outcome; a command that has nothing to hand back calls it with no argument.
+ *
+ * @example return success();
+ */
+export declare function success(): Success<undefined>;
+export declare function success<T>(data: T): Success<T>;
+/**
+ * A usage failure: the run prints `message`, then the help of the command that answered it, and
+ * exits 2.
+ *
+ * @example if (ctx.flags.prompt && !ctx.flags.from) return usage("--prompt needs --from");
+ */
+export declare function usage(message: string): Failure<UsageError>;
+/** A cancelled failure, which exits 130 without printing anything. */
+export declare function cancelled(): Failure<CancelledError>;
+/**
+ * A failure that exits with `code`, printing `message` when one is given.
+ *
+ * @example return run.failed > 0 ? exit(1) : success();
+ */
+export declare function exit(code: number, message?: string): Failure<ExitError>;
+/** The exit code a run's failure maps to. */
+export declare function exitCodeOf(error: Error): number;

package/dist/errors.js

@@ -0,0 +1,82 @@
+/**
+ * The failures a command answers and the exit codes they map to: a usage failure prints the
+ * command's help and exits 2, a cancelled one exits 130 in silence, an exit failure picks its
+ * own code, and any other failure prints its message and exits 1.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success as succeed } from "@sdxc/result";
+/** The exit code each outcome of a run maps to, shared by every command line built here. */
+export const EXIT_CODES = {
+    success: 0,
+    failure: 1,
+    usage: 2,
+    cancelled: 130,
+};
+/** A command line the user wrote wrong; the run prints the message and the command's help. */
+export class UsageError extends Error {
+    name = "UsageError";
+}
+/**
+ * The user stopped the run, with Ctrl+C or Escape at a prompt or Ctrl+C during a task. The run
+ * exits 130 and writes nothing more, since the user already knows why it stopped.
+ */
+export class CancelledError extends Error {
+    name = "CancelledError";
+    /** @param message - Read only by code that logs the failure; the run itself prints nothing */
+    constructor(message = "Cancelled") {
+        super(message);
+    }
+}
+/**
+ * A failure that picks its own exit code. An empty message prints nothing, for a command that
+ * already reported what went wrong, such as a test runner that printed its failed tests.
+ */
+export class ExitError extends Error {
+    name = "ExitError";
+    /** The process exit code the run answers. */
+    code;
+    /**
+     * @param code - The exit code
+     * @param message - What the run prints on stderr, nothing when empty
+     */
+    constructor(code, message = "") {
+        super(message);
+        this.code = code;
+    }
+}
+export function success(data) {
+    return succeed(data);
+}
+/**
+ * A usage failure: the run prints `message`, then the help of the command that answered it, and
+ * exits 2.
+ *
+ * @example if (ctx.flags.prompt && !ctx.flags.from) return usage("--prompt needs --from");
+ */
+export function usage(message) {
+    return failure(new UsageError(message));
+}
+/** A cancelled failure, which exits 130 without printing anything. */
+export function cancelled() {
+    return failure(new CancelledError());
+}
+/**
+ * A failure that exits with `code`, printing `message` when one is given.
+ *
+ * @example return run.failed > 0 ? exit(1) : success();
+ */
+export function exit(code, message) {
+    return failure(new ExitError(code, message));
+}
+/** The exit code a run's failure maps to. */
+export function exitCodeOf(error) {
+    if (error instanceof UsageError)
+        return EXIT_CODES.usage;
+    if (error instanceof CancelledError)
+        return EXIT_CODES.cancelled;
+    if (error instanceof ExitError)
+        return error.code;
+    return EXIT_CODES.failure;
+}

package/dist/exec.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Child processes without a shell: arguments reach the program exactly as given, so nothing in
+ * them is expanded or split. The answer is a `Result` carrying the exit code and what the child
+ * printed, and an aborted signal stops the child and answers a cancelled failure.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { Output } from "./screen.js";
+import type { Env } from "./style.js";
+import { CancelledError } from "./errors.js";
+/**
+ * Where a child's output goes: `"inherit"` to the CLI's own streams, `"ignore"` nowhere,
+ * `"collect"` into the answer only, and `"stderr"` sends the child's stdout to the CLI's stderr,
+ * so a command whose stdout is piped keeps it clean while an install prints.
+ */
+export type Stdio = "inherit" | "ignore" | "collect" | "stderr";
+/** How `ctx.exec` runs one command. */
+export interface ExecOptions {
+    /** @default the command's working directory */
+    cwd?: string;
+    /** Variables set on top of the command's environment. */
+    env?: Env;
+    /** @default "inherit" */
+    stdio?: Stdio;
+    /** Stops the child. @default the run's signal, which aborts on Ctrl+C */
+    signal?: AbortSignal;
+    /** Text written to the child's stdin, which is otherwise closed (or the terminal for "inherit"). */
+    input?: string;
+}
+/** Everything an {@link Exec} receives, with every default filled in. */
+export interface ExecRequest {
+    cwd: string;
+    env: Env;
+    stdio: Stdio;
+    signal: AbortSignal;
+    input: string | undefined;
+    /** The CLI's streams, for `"inherit"` and `"stderr"` output. */
+    stdout: Output;
+    stderr: Output;
+}
+/** A child that exited 0. */
+export interface ExecOutput {
+    code: number;
+    /** What the child printed on stdout, empty unless it was collected. */
+    stdout: string;
+    stderr: string;
+    /** Both streams in the order they arrived. */
+    output: string;
+}
+/** A child that could not start or exited with a code other than 0. */
+export declare class ExecError extends Error {
+    name: string;
+    /** The command as given. */
+    command: readonly string[];
+    /** The exit code, or `null` when the child never started or ended on a signal. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    output: string;
+    /**
+     * @param message - What went wrong
+     * @param details - The command and what it printed
+     */
+    constructor(message: string, details: {
+        command: readonly string[];
+        code: number | null;
+        stdout?: string;
+        stderr?: string;
+        output?: string;
+        cause?: unknown;
+    });
+}
+/** Runs one command; `cli.run`'s `exec` option replaces it, as the test harness does. */
+export type Exec = (command: readonly string[], request: ExecRequest) => Promise<Result<ExecOutput, ExecError | CancelledError>>;
+/** The command as a shell user would read it, for messages. */
+export declare function displayCommand(command: readonly string[]): string;
+/**
+ * Spawns `command` with `node:child_process`. Output bound for the process's own streams is
+ * inherited directly; output bound for any other stream is piped and forwarded to it.
+ */
+export declare const spawnExec: Exec;