@sdxc/cli 0.0.0-stage → 2026.10.20

package/dist/cli.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `createCLI()`: a command contract with handlers mapped onto it, run against an argument
+ * vector. A run parses, prints help or a usage error, asks for what is missing, runs the
+ * middleware chain and the handler, and answers the exit code its outcome maps to.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { ArgumentsOf, FlagsOf, Group, Node } from "./command.js";
+import type { CommandDescription } from "./describe.js";
+import type { CommandAction, CommandHandler } from "./handler.js";
+import type { Lazy } from "./lazy.js";
+import type { AnyCommandMiddleware, ChainProperties } from "./middleware.js";
+import type { RunIO, Script } from "./session.js";
+import { CommandContext } from "./context.js";
+import { UsageError } from "./errors.js";
+/** What a CLI is built from. */
+export interface CLIOptions<Commands extends Group, Chain extends readonly AnyCommandMiddleware[]> {
+    /** The program name, as the usage line prints it. */
+    name: string;
+    /** Printed by `--version`; without one the flag does not exist. */
+    version?: string;
+    /** Shown under the root usage line when the root group has no description. */
+    description?: string;
+    commands: Commands;
+    /** Runs before every command's own middleware, in order. */
+    middleware?: Chain;
+}
+/** What `map()` accepts for one command or group. */
+export type Binding<Target, Chain extends readonly AnyCommandMiddleware[]> = CommandHandler<CommandContext<ArgumentsOf<Target>, FlagsOf<Target>> & ChainProperties<Chain>> | CommandAction<Target, any> | Lazy<CommandAction<Target, any>>;
+/** A command line: its contract, the handlers mapped onto it, and a way to run it. */
+export interface CLI<Commands extends Group = Group, Chain extends readonly AnyCommandMiddleware[] = readonly AnyCommandMiddleware[]> {
+    readonly name: string;
+    readonly version: string | undefined;
+    readonly commands: Commands;
+    readonly middleware: Chain;
+    /**
+     * Binds a handler to a command. A group can be mapped too; it runs when the command line
+     * names the group and no member, which otherwise prints the group's help.
+     *
+     * @throws Error When the target is not in this CLI's contract, or is mapped twice.
+     */
+    map<Target extends Node>(target: Target, binding: Binding<Target, Chain>): void;
+    /**
+     * Runs the command `argv` names and answers its exit code: 0 success, 1 failure, 2 usage
+     * error, 130 cancelled, or the code an `exit()` failure carries.
+     *
+     * @param argv - The arguments after the program, as `process.argv.slice(2)` holds them
+     * @param io - Replaces any part of the process the run uses
+     * @example process.exitCode = await cli.run(process.argv.slice(2));
+     */
+    run(argv: readonly string[], io?: RunIO): Promise<number>;
+    /**
+     * The contract as data, the facts `--help --json` prints: the whole program, or the command
+     * `path` names, with every visible member below it.
+     *
+     * @returns The description, or `undefined` when `path` names no command
+     * @example let make = cli.describe(["make"]);
+     */
+    describe(path?: readonly string[]): CommandDescription | undefined;
+    /**
+     * Checks `argv` the way a run does before it asks or runs anything: the command it names, every
+     * flag, and every value against its schema. A missing value that a prompt would ask for passes,
+     * since a terminal run asks for it. Nothing is loaded and no handler runs.
+     *
+     * @returns The path of the command `argv` reaches, or a usage failure listing every problem
+     * @example let checked = await cli.check(["make", "controller", "posts", "--method", "form"]);
+     */
+    check(argv: readonly string[]): Promise<Result<CheckedCommand, UsageError>>;
+}
+/** A command line `check()` accepted. */
+export interface CheckedCommand {
+    /** The words that reached the command; empty for the root. */
+    path: string[];
+}
+/**
+ * Builds a CLI over a command contract.
+ *
+ * @throws Error When the contract repeats a command, gives a flag a reserved or duplicate name,
+ * or puts a variadic argument before another one.
+ * @example
+ * let cli = createCLI({ name: "sdxc", version, commands: sdxc, middleware: [project()] });
+ * cli.map(sdxc.init, lazy(() => import("./commands/init.js")));
+ * process.exitCode = await cli.run(process.argv.slice(2));
+ */
+export declare function createCLI<Commands extends Group, const Chain extends readonly AnyCommandMiddleware[] = []>(options: CLIOptions<Commands, Chain>): CLI<Commands, Chain>;
+/**
+ * Runs `argv` on `cli` with a test's script. Used by `@sdxc/cli/test`.
+ *
+ * @internal
+ */
+export declare function runScripted<Commands extends Group, Chain extends readonly AnyCommandMiddleware[]>(cli: CLI<Commands, Chain>, argv: readonly string[], io: RunIO, script: Script): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,229 @@
+/**
+ * `createCLI()`: a command contract with handlers mapped onto it, run against an argument
+ * vector. A run parses, prints help or a usage error, asks for what is missing, runs the
+ * middleware chain and the handler, and answers the exit code its outcome maps to.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success } from "@sdxc/result";
+import { CommandContext } from "./context.js";
+import { describeEntry } from "./describe.js";
+import { CancelledError, EXIT_CODES, exitCodeOf, UsageError } from "./errors.js";
+import { isAction } from "./handler.js";
+import { renderHelp } from "./help.js";
+import { isLazy } from "./lazy.js";
+import { parseArgv } from "./parse.js";
+import { createPrompter, resolveInputs } from "./resolve.js";
+import { openSession } from "./session.js";
+import { buildTree } from "./tree.js";
+/** Every CLI's internals, reachable by the test harness without being part of the API. */
+const INTERNALS = new WeakMap();
+/**
+ * Builds a CLI over a command contract.
+ *
+ * @throws Error When the contract repeats a command, gives a flag a reserved or duplicate name,
+ * or puts a variadic argument before another one.
+ * @example
+ * let cli = createCLI({ name: "sdxc", version, commands: sdxc, middleware: [project()] });
+ * cli.map(sdxc.init, lazy(() => import("./commands/init.js")));
+ * process.exitCode = await cli.run(process.argv.slice(2));
+ */
+export function createCLI(options) {
+    let tree = buildTree(options.name, options.commands);
+    let bindings = new Map();
+    let cli = {
+        name: options.name,
+        version: options.version,
+        commands: options.commands,
+        middleware: options.middleware ?? [],
+        map(target, binding) {
+            let entry = tree.entries.get(target);
+            if (entry === undefined)
+                throw new Error(`map() was given a command outside ${options.name}`);
+            if (bindings.has(target))
+                throw new Error(`${entry.title} is mapped twice`);
+            bindings.set(target, resolver(binding));
+        },
+        run: (argv, io = {}) => execute(cli, argv, io, undefined),
+        describe(path = []) {
+            let entry = tree.root;
+            for (let word of path)
+                entry = entry?.children.get(word);
+            if (entry === undefined)
+                return undefined;
+            return describeEntry(entry, { version: options.version, description: options.description });
+        },
+        check: (argv) => check(tree, options.version !== undefined, argv),
+    };
+    INTERNALS.set(cli, {
+        tree,
+        options: options,
+        bindings,
+    });
+    return cli;
+}
+/** A binding as a loader of its action, importing a lazy one at most once per CLI. */
+function resolver(binding) {
+    if (isLazy(binding)) {
+        let loading;
+        return () => {
+            loading ??= binding.load().then((module) => normalize(module.default), (error) => {
+                loading = undefined;
+                throw error;
+            });
+            return loading;
+        };
+    }
+    let action = normalize(binding);
+    return () => Promise.resolve(action);
+}
+/** An action, or a bare handler wrapped as one with no middleware of its own. */
+function normalize(binding) {
+    if (isAction(binding))
+        return binding;
+    return { middleware: [], handler: binding };
+}
+/**
+ * Runs `argv` on `cli` with a test's script. Used by `@sdxc/cli/test`.
+ *
+ * @internal
+ */
+export function runScripted(cli, argv, io, script) {
+    return execute(cli, argv, io, script);
+}
+/**
+ * Whether `--json` rides along with `--help`, before any `--`, so the help prints as data. A
+ * command with a `--json` flag of its own reads the pair the same way.
+ */
+function asksForJSON(argv) {
+    let end = argv.indexOf("--");
+    return (end === -1 ? argv : argv.slice(0, end)).includes("--json");
+}
+/**
+ * The prompts of a check: every one answers its initial value, so a value a terminal run would
+ * ask for counts as given.
+ */
+const CHECK_SESSION = {
+    interactive: true,
+    ask: (request) => Promise.resolve(success(request.initial)),
+};
+/** Parses and checks `argv` against `tree`, asking nothing and running nothing. */
+async function check(tree, withVersion, argv) {
+    let parsed = parseArgv(tree, argv, withVersion);
+    let path = [...parsed.entry.path];
+    if (parsed.help || parsed.version)
+        return success({ path });
+    let inputs = await resolveInputs(parsed, CHECK_SESSION);
+    if (isFailure(inputs)) {
+        let error = inputs.error;
+        return failure(error instanceof UsageError ? error : new UsageError(error.message));
+    }
+    return success({ path });
+}
+/** One run, from argument vector to exit code. */
+async function execute(cli, argv, io, script) {
+    let internals = INTERNALS.get(cli);
+    let { tree, options, bindings } = internals;
+    let program = { version: options.version, description: options.description };
+    let parsed = parseArgv(tree, argv, options.version !== undefined);
+    let session = openSession(io, parsed.noProgress, script);
+    try {
+        let entry = parsed.entry;
+        if (parsed.help && asksForJSON(argv)) {
+            session.stdout.write(`${JSON.stringify(describeEntry(entry, program), null, 2)}\n`);
+            return EXIT_CODES.success;
+        }
+        if (parsed.help) {
+            session.stdout.write(renderHelp(entry, program, session.style));
+            return EXIT_CODES.success;
+        }
+        if (parsed.version) {
+            session.stdout.write(`${options.version}\n`);
+            return EXIT_CODES.success;
+        }
+        if (parsed.issues.length > 0 && entry.children.size > 0) {
+            return report(new UsageError(parsed.issues.join("\n")), entry, session, program);
+        }
+        let load = bindings.get(entry.node);
+        if (load === undefined) {
+            if (entry.children.size > 0) {
+                session.stderr.write(renderHelp(entry, program, session.style.stderr));
+                return EXIT_CODES.usage;
+            }
+            return report(new Error(`${entry.title} has no handler`), entry, session, program);
+        }
+        let inputs = await resolveInputs(parsed, session);
+        if (isFailure(inputs))
+            return report(inputs.error, entry, session, program);
+        let action;
+        try {
+            action = await load();
+        }
+        catch (error) {
+            return report(asError(error), entry, session, program);
+        }
+        let context = new CommandContext({
+            argv: [...argv],
+            path: entry.path,
+            arguments: inputs.data.arguments,
+            flags: inputs.data.flags,
+            session,
+            prompt: createPrompter(session),
+        });
+        let chain = [...(options.middleware ?? []), ...action.middleware];
+        let outcome = await dispatch(chain, context, action.handler);
+        if (isFailure(outcome))
+            return report(outcome.error, entry, session, program);
+        return EXIT_CODES.success;
+    }
+    finally {
+        session.close();
+    }
+}
+/**
+ * Runs the middleware chain and the handler. A thrown error becomes a failure, so a bug in a
+ * handler still exits 1 with its message.
+ */
+async function dispatch(chain, context, handler) {
+    /** Runs the chain from `index`, answering the outcome the run exits with. */
+    let run = async (index) => {
+        let middleware = chain[index];
+        if (middleware === undefined)
+            return handler(context);
+        let downstream;
+        let returned = await middleware(context, async () => {
+            downstream = await run(index + 1);
+            return downstream;
+        });
+        if (returned !== undefined && (downstream === undefined || isFailure(returned))) {
+            return returned;
+        }
+        return downstream ?? success(undefined);
+    };
+    let outcome;
+    try {
+        outcome = await run(0);
+    }
+    catch (error) {
+        return failure(asError(error));
+    }
+    if (context.signal.aborted && isFailure(outcome))
+        return failure(new CancelledError());
+    return outcome;
+}
+/** A thrown value as an `Error`. */
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+/** Prints a failed run's message and answers its exit code. */
+function report(error, entry, session, program) {
+    if (error instanceof UsageError) {
+        let help = renderHelp(entry, program, session.style.stderr);
+        session.screen.write(session.stderr, `${error.message}\n\n${help}`);
+    }
+    else if (!(error instanceof CancelledError) && error.message !== "") {
+        session.screen.write(session.stderr, `${error.message}\n`);
+    }
+    return exitCodeOf(error);
+}

package/dist/command.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The command contract: `command()` declares what one command takes, and `commands()` groups
+ * commands under a name, nesting as deep as the command line does, so `sdxc ui add` is
+ * `contract.ui.add`. Declaration runs nothing; `createCLI` maps handlers onto it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Argument, ArgumentValue } from "./argument.js";
+import type { Carried, Flag, FlagValue } from "./flag.js";
+/** Brands a declared command. */
+declare const COMMAND: unique symbol;
+/** Brands a declared group. */
+declare const GROUP: unique symbol;
+/** Type-only slot carrying the inputs a group declares for its own handler. */
+declare const INPUTS: unique symbol;
+/** Keys of `commands()`' definition that describe the group instead of naming a member. */
+type GroupOwnKey = "description" | "hidden" | "arguments" | "flags" | "tasks";
+/** A command's positional arguments, filled in key order. */
+export type ArgumentsShape = Readonly<Record<string, Argument>>;
+/** A command's flags, keyed by the property its handler reads. */
+export type FlagsShape = Readonly<Record<string, Flag>>;
+/** What one command declares. */
+export interface CommandDefinition<Arguments extends ArgumentsShape = ArgumentsShape, Flags extends FlagsShape = FlagsShape> {
+    /** One line, shown in the help and in the parent group's command list. */
+    description?: string;
+    arguments?: Arguments;
+    flags?: Flags;
+    /** Command lines the help lists under "Examples", written without the program name. */
+    examples?: readonly string[];
+    /** Left out of the parent group's command list; it still runs. */
+    hidden?: boolean;
+    /** Its handler runs `ctx.task`, so the help lists `--no-progress`. */
+    tasks?: boolean;
+}
+/** A declared command. */
+export interface Command<Arguments extends ArgumentsShape = ArgumentsShape, Flags extends FlagsShape = FlagsShape> {
+    readonly [COMMAND]: true;
+    readonly description: string | undefined;
+    readonly arguments: Arguments;
+    readonly flags: Flags;
+    readonly examples: readonly string[];
+    readonly hidden: boolean;
+    readonly tasks: boolean;
+}
+/** What a group holds besides its members. */
+export interface GroupSpec {
+    description: string | undefined;
+    hidden: boolean;
+    tasks: boolean;
+    /** The members, keyed by the name typed on the command line. */
+    members: Readonly<Record<string, Command | Group>>;
+    /** What the group's own handler reads when the command line names no member. */
+    arguments: ArgumentsShape;
+    flags: FlagsShape;
+}
+/** What a group's own handler reads, carried for `ctx.arguments` and `ctx.flags`. */
+export interface GroupInputs<Arguments extends ArgumentsShape, Flags extends FlagsShape> {
+    arguments: Arguments;
+    flags: Flags;
+}
+/** A declared group: its members, reachable by name, plus the brand carrying its spec. */
+export type Group<Members = Readonly<Record<string, unknown>>, Arguments extends ArgumentsShape = ArgumentsShape, Flags extends FlagsShape = FlagsShape> = Members & {
+    readonly [GROUP]: GroupSpec;
+    readonly [INPUTS]?: Carried<GroupInputs<Arguments, Flags>>;
+};
+/**
+ * What `commands()` takes: members keyed by name, plus the group's own description and the
+ * inputs its handler reads when the command line names no member.
+ */
+export interface GroupDefinition {
+    /** One line, shown in the help and in the parent group's command list. */
+    readonly description?: string;
+    /** Left out of the parent group's command list; it still runs. */
+    readonly hidden?: boolean;
+    /**
+     * Read by the group's mapped handler. A word that names no member fills them, and one the
+     * first argument rejects is reported as an unknown command.
+     */
+    readonly arguments?: ArgumentsShape;
+    /** Read by the group's mapped handler; one written before a member's name moves to that member. */
+    readonly flags?: FlagsShape;
+    /** The group's handler runs `ctx.task`, so its help lists `--no-progress`. */
+    readonly tasks?: boolean;
+    readonly [name: string]: Command | Group | ArgumentsShape | FlagsShape | string | boolean | undefined;
+}
+/** A declared command or group, as the parser walks them. */
+export type Node = Command | Group;
+/**
+ * Declares one command.
+ *
+ * @example
+ * command({
+ * 	description: "Copy components into the project",
+ * 	arguments: { components: argument.variadic(s.string(), { min: 1 }) },
+ * 	flags: { dryRun: flag.boolean("dry-run") },
+ * })
+ */
+export declare function command<const Arguments extends ArgumentsShape = Record<never, never>, const Flags extends FlagsShape = Record<never, never>>(definition?: CommandDefinition<Arguments, Flags>): Command<Arguments, Flags>;
+/** The arguments a group definition declares for its own handler, or none. */
+type DeclaredArguments<Definition> = Definition extends {
+    readonly arguments: infer Shape extends ArgumentsShape;
+} ? Shape : Record<never, never>;
+/** The flags a group definition declares for its own handler, or none. */
+type DeclaredFlags<Definition> = Definition extends {
+    readonly flags: infer Shape extends FlagsShape;
+} ? Shape : Record<never, never>;
+/**
+ * Groups commands, and other groups, under the names typed on the command line.
+ * `description`, `hidden`, `arguments`, `flags` and `tasks` describe the group itself and are
+ * never members.
+ *
+ * @example export let sdxc = commands({ init: command({}), ui: commands({ description: "…", add }) });
+ * @example make: commands({ arguments: { kind: argument(s.enum_(KINDS), { prompt }) }, job, model })
+ */
+export declare function commands<const Definition extends GroupDefinition>(definition: Definition): Group<Omit<Definition, GroupOwnKey>, DeclaredArguments<Definition>, DeclaredFlags<Definition>>;
+/** Whether `value` is a declared command. */
+export declare function isCommand(value: unknown): value is Command;
+/** Whether `value` is a declared group. */
+export declare function isGroup(value: unknown): value is Group;
+/** The spec behind a group. */
+export declare function groupSpec(group: Group): GroupSpec;
+/** The inputs a group declared for its own handler. */
+type GroupInputsOf<Target> = Target extends {
+    readonly [INPUTS]?: Carried<infer Inputs> | undefined;
+} ? Inputs : never;
+/** What `ctx.arguments` holds for a command or a group: each argument's parsed value by key. */
+export type ArgumentsOf<Target> = Target extends Command<infer Arguments, FlagsShape> ? {
+    readonly [Key in keyof Arguments]: ArgumentValue<Arguments[Key]>;
+} : GroupInputsOf<Target> extends GroupInputs<infer Arguments, FlagsShape> ? {
+    readonly [Key in keyof Arguments]: ArgumentValue<Arguments[Key]>;
+} : Readonly<Record<never, never>>;
+/** What `ctx.flags` holds for a command or a group: each flag's parsed value by key. */
+export type FlagsOf<Target> = Target extends Command<ArgumentsShape, infer Flags> ? {
+    readonly [Key in keyof Flags]: FlagValue<Flags[Key]>;
+} : GroupInputsOf<Target> extends GroupInputs<ArgumentsShape, infer Flags> ? {
+    readonly [Key in keyof Flags]: FlagValue<Flags[Key]>;
+} : Readonly<Record<never, never>>;
+export {};

package/dist/command.js

@@ -0,0 +1,79 @@
+/**
+ * The command contract: `command()` declares what one command takes, and `commands()` groups
+ * commands under a name, nesting as deep as the command line does, so `sdxc ui add` is
+ * `contract.ui.add`. Declaration runs nothing; `createCLI` maps handlers onto it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Brands a declared command. */
+const COMMAND = Symbol.for("@sdxc/cli.command");
+/** Brands a declared group. */
+const GROUP = Symbol.for("@sdxc/cli.group");
+/**
+ * Declares one command.
+ *
+ * @example
+ * command({
+ * 	description: "Copy components into the project",
+ * 	arguments: { components: argument.variadic(s.string(), { min: 1 }) },
+ * 	flags: { dryRun: flag.boolean("dry-run") },
+ * })
+ */
+export function command(definition = {}) {
+    return {
+        [COMMAND]: true,
+        description: definition.description,
+        arguments: definition.arguments ?? {},
+        flags: definition.flags ?? {},
+        examples: definition.examples ?? [],
+        hidden: definition.hidden === true,
+        tasks: definition.tasks === true,
+    };
+}
+/**
+ * Groups commands, and other groups, under the names typed on the command line.
+ * `description`, `hidden`, `arguments`, `flags` and `tasks` describe the group itself and are
+ * never members.
+ *
+ * @example export let sdxc = commands({ init: command({}), ui: commands({ description: "…", add }) });
+ * @example make: commands({ arguments: { kind: argument(s.enum_(KINDS), { prompt }) }, job, model })
+ */
+export function commands(definition) {
+    let members = {};
+    for (let [name, member] of Object.entries(definition)) {
+        if (OWN_KEYS.has(name))
+            continue;
+        if (isCommand(member) || isGroup(member))
+            members[name] = member;
+    }
+    let spec = {
+        description: definition.description,
+        hidden: definition.hidden === true,
+        tasks: definition.tasks === true,
+        members,
+        arguments: definition.arguments ?? {},
+        flags: definition.flags ?? {},
+    };
+    return { ...members, [GROUP]: spec };
+}
+/** The definition keys `commands()` reads as the group's own. */
+const OWN_KEYS = new Set([
+    "description",
+    "hidden",
+    "arguments",
+    "flags",
+    "tasks",
+]);
+/** Whether `value` is a declared command. */
+export function isCommand(value) {
+    return typeof value === "object" && value !== null && COMMAND in value;
+}
+/** Whether `value` is a declared group. */
+export function isGroup(value) {
+    return typeof value === "object" && value !== null && GROUP in value;
+}
+/** The spec behind a group. */
+export function groupSpec(group) {
+    return group[GROUP];
+}

package/dist/context.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 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
+ */
+import type { Result } from "@sdxc/result";
+import type { ContextValue } from "remix/router";
+import type { CancelledError } from "./errors.js";
+import type { ExecError, ExecOptions, ExecOutput } from "./exec.js";
+import type { Prompter } from "./prompt.js";
+import type { Session } from "./session.js";
+import type { Env, Style } from "./style.js";
+import type { RunTask } from "./task.js";
+/** Everything a context is built from. */
+export interface CommandContextInit<Arguments, Flags> {
+    argv: readonly string[];
+    path: readonly string[];
+    arguments: Arguments;
+    flags: Flags;
+    session: Session;
+    prompt: Prompter;
+}
+/**
+ * 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 declare class CommandContext<Arguments = unknown, Flags = unknown> {
+    #private;
+    /**
+     * 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.
+     */
+    readonly argv: readonly string[];
+    /** The command's names after the program, `["ui", "add"]` for `sdxc ui add`. */
+    readonly path: readonly string[];
+    /** The positional arguments, parsed, prompted for, or defaulted. */
+    readonly arguments: Arguments;
+    /** The flags, parsed, prompted for, or defaulted. */
+    readonly flags: Flags;
+    readonly cwd: string;
+    readonly env: Env;
+    /** Styling for stdout; `style.stderr` styles stderr, each off for a stream that is not a terminal. */
+    readonly style: Style & {
+        readonly stderr: Style;
+    };
+    /** Aborts on Ctrl+C. */
+    readonly signal: AbortSignal;
+    /**
+     * Questions a handler asks itself. Each takes a `default`, which answers without a
+     * terminal, so the command stays runnable in CI.
+     */
+    readonly prompt: Prompter;
+    /**
+     * 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 }));
+     */
+    readonly task: RunTask;
+    /**
+     * 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());
+     */
+    readonly stdin: Stdin;
+    /** @param init - The parsed command and the run it belongs to */
+    constructor(init: CommandContextInit<Arguments, Flags>);
+    /** Writes to stdout, above any running task. */
+    readonly stdout: (text: string) => void;
+    /** Writes to stderr, above any running task. */
+    readonly stderr: (text: string) => void;
+    /**
+     * 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: readonly string[], options?: ExecOptions): Promise<Result<ExecOutput, ExecError | CancelledError>>;
+    /**
+     * 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: Env): void;
+    /**
+     * Reads a value some middleware published.
+     *
+     * @param key - The context key to read
+     * @returns Its value, the key's default, or `undefined`
+     */
+    get<Key extends object>(key: Key): ContextValue<Key> | undefined;
+    /**
+     * 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 extends object>(key: Key): NonNullable<ContextValue<Key>>;
+    /**
+     * Whether a value has been published for a key.
+     *
+     * @param key - The context key to check
+     */
+    has(key: object): boolean;
+    /**
+     * 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 extends object>(key: Key, value: ContextValue<Key>, options?: {
+        property: string;
+    }): void;
+}
+/** The run's standard input. */
+export interface Stdin {
+    /** Whether stdin is a terminal, as opposed to a pipe or a file. */
+    readonly isTTY: boolean;
+    /** Everything piped in, read once to its end; later calls answer the same text. */
+    text(): Promise<string>;
+}
+/** A context whatever it parsed, for middleware that runs before every command. */
+export type AnyCommandContext = CommandContext<any, any>;