@sdxc/cli 0.0.0-stage → 2026.10.16

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/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;

package/dist/exec.js

@@ -0,0 +1,136 @@
+/**
+ * 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 { spawn } from "node:child_process";
+import { failure, success } from "@sdxc/result";
+import { CancelledError } from "./errors.js";
+/** A child that could not start or exited with a code other than 0. */
+export class ExecError extends Error {
+    name = "ExecError";
+    /** The command as given. */
+    command;
+    /** The exit code, or `null` when the child never started or ended on a signal. */
+    code;
+    stdout;
+    stderr;
+    output;
+    /**
+     * @param message - What went wrong
+     * @param details - The command and what it printed
+     */
+    constructor(message, details) {
+        super(message, { cause: details.cause });
+        this.command = details.command;
+        this.code = details.code;
+        this.stdout = details.stdout ?? "";
+        this.stderr = details.stderr ?? "";
+        this.output = details.output ?? "";
+    }
+}
+/** The command as a shell user would read it, for messages. */
+export function displayCommand(command) {
+    return command
+        .map((part) => (/^[\w./:=@-]+$/.test(part) ? part : JSON.stringify(part)))
+        .join(" ");
+}
+/**
+ * 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 const spawnExec = (command, request) => new Promise((resolve) => {
+    let settled = false;
+    let settle = (outcome) => {
+        if (settled)
+            return;
+        settled = true;
+        resolve(outcome);
+    };
+    let [program, ...args] = command;
+    if (program === undefined) {
+        settle(failure(new ExecError("exec needs a command", { command, code: null })));
+        return;
+    }
+    if (request.signal.aborted) {
+        settle(failure(new CancelledError()));
+        return;
+    }
+    let shown = displayCommand(command);
+    let direct = (target, stream) => target === stream;
+    let outTarget = request.stdio === "inherit"
+        ? request.stdout
+        : request.stdio === "stderr"
+            ? request.stderr
+            : null;
+    let errTarget = request.stdio === "inherit" || request.stdio === "stderr" ? request.stderr : null;
+    let stdout = request.stdio === "ignore"
+        ? "ignore"
+        : outTarget === null
+            ? "pipe"
+            : direct(outTarget, process.stdout)
+                ? "inherit"
+                : direct(outTarget, process.stderr)
+                    ? 2
+                    : "pipe";
+    let stderr = request.stdio === "ignore"
+        ? "ignore"
+        : errTarget !== null && direct(errTarget, process.stderr)
+            ? "inherit"
+            : "pipe";
+    let stdin = request.input !== undefined ? "pipe" : request.stdio === "inherit" ? "inherit" : "ignore";
+    let child = spawn(program, args, {
+        cwd: request.cwd,
+        env: { ...request.env },
+        shell: false,
+        stdio: [stdin, stdout, stderr],
+    });
+    let collected = { stdout: "", stderr: "", output: "" };
+    child.stdout?.on("data", (chunk) => {
+        let text = chunk.toString();
+        if (outTarget === null) {
+            collected.stdout += text;
+            collected.output += text;
+        }
+        else
+            outTarget.write(text);
+    });
+    child.stderr?.on("data", (chunk) => {
+        let text = chunk.toString();
+        if (errTarget === null) {
+            collected.stderr += text;
+            collected.output += text;
+        }
+        else
+            errTarget.write(text);
+    });
+    if (request.input !== undefined)
+        child.stdin?.end(request.input);
+    let abort = () => child.kill("SIGTERM");
+    request.signal.addEventListener("abort", abort, { once: true });
+    child.once("error", (error) => {
+        request.signal.removeEventListener("abort", abort);
+        settle(failure(new ExecError(`${shown} could not start: ${error.message}`, {
+            command,
+            code: null,
+            cause: error,
+            ...collected,
+        })));
+    });
+    child.once("close", (code, signal) => {
+        request.signal.removeEventListener("abort", abort);
+        if (request.signal.aborted) {
+            settle(failure(new CancelledError()));
+            return;
+        }
+        if (code === 0) {
+            settle(success({ code, ...collected }));
+            return;
+        }
+        let reason = code === null ? `was stopped by ${signal ?? "a signal"}` : `exited with ${code}`;
+        settle(failure(new ExecError(`${shown} ${reason}`, { command, code, ...collected })));
+    });
+});