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

package/dist/middleware.d.ts

@@ -1,78 +0,0 @@
-/**
- * The middleware chain a CLI runs every command inside, and the types that carry what each
- * middleware publishes into the context. The effect a middleware declares rides along as
- * type-only metadata, so an inline `middleware: [...]` array is enough for a handler to read
- * `ctx.db` with its real type; the shape matches `@sdxc/jobs`, so one package ships both.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import type { Result } from "@sdxc/result";
-import type { AnyCommandContext } from "./context.js";
-/** What a command answers: success exits 0, a failure exits by its kind. */
-export type CommandResult = Result<unknown, Error>;
-/**
- * Runs the rest of the chain, ending in the command's handler, and resolves to what it answered,
- * so a middleware can log or wrap the outcome; a throw in the rest of the chain rejects it.
- */
-export type NextFunction = () => Promise<CommandResult>;
-/** What one middleware puts into the context, and the property it installs it as. */
-export interface ContextEffect {
-    key: object;
-    value: unknown;
-    property?: string;
-}
-/** A middleware that publishes nothing a handler can read off the context. */
-export interface EmptyContextEffect {
-    key: never;
-    value: never;
-}
-/** Type-only slot carrying a middleware's declared effect. */
-declare const contextEffect: unique symbol;
-/**
- * Runs before the command's handler, in the order declared. `Effect` names what it publishes; a
- * middleware publishing several values declares a union of effects, one per property. It calls `next()` to continue; one
- * that returns a failure instead ends the run with it, the way a handler's failure does, and one
- * that returns without calling `next()` ends the run successfully without the handler.
- *
- * @example
- * function project(): CommandMiddleware<{ key: typeof Project; value: Root; property: "project" }> {
- * 	return async (ctx, next) => {
- * 		let root = await findProjectRoot(ctx.cwd);
- * 		if (isFailure(root)) return root;
- * 		ctx.set(Project, root.data, { property: "project" });
- * 		await next();
- * 	};
- * }
- * @example CommandMiddleware<{ key: typeof Locale; value: string; property: "locale" } | { key: typeof Intl; value: I18n; property: "intl" }>
- */
-export type CommandMiddleware<Effect extends ContextEffect = EmptyContextEffect> = ((context: AnyCommandContext, next: NextFunction) => void | CommandResult | Promise<void | CommandResult>) & {
-    /** Type-only metadata naming what this middleware publishes. */
-    readonly [contextEffect]?: Effect | undefined;
-};
-/** A middleware whatever it publishes, for the places that hold a whole chain. */
-export type AnyCommandMiddleware = CommandMiddleware<any>;
-/** The effect one middleware declared, or nothing when it declared none. */
-type EffectOf<Middleware> = Middleware extends {
-    readonly [contextEffect]?: (infer Effect) | undefined;
-} ? Effect extends ContextEffect ? Effect : never : never;
-/** Installs nothing a handler can read: an intersection with this changes no type. */
-type NoProperties = Record<never, never>;
-/** The property one effect installs, ignoring an effect that installs none. */
-type EachProperty<Effect> = Effect extends {
-    property: infer Property extends string;
-    value: infer Value;
-} ? string extends Property ? NoProperties : {
-    readonly [Key in Property]: Value;
-} : NoProperties;
-/** Folds a union of property objects into one object holding all of them. */
-type Merge<Union> = (Union extends unknown ? (each: Union) => void : never) extends (all: infer All) => void ? All : never;
-/** Every property an effect installs: one, or each member of a union of effects. */
-type PropertyOf<Effect> = [Effect] extends [never] ? NoProperties : Merge<EachProperty<Effect>>;
-/**
- * Every property a chain installs, folded left to right so a later middleware overriding a name
- * wins. A chain that is a plain array rather than a tuple carries no order, so it contributes
- * nothing.
- */
-export type ChainProperties<Chain extends readonly AnyCommandMiddleware[]> = number extends Chain["length"] ? NoProperties : Chain extends readonly [infer First, ...infer Rest extends readonly AnyCommandMiddleware[]] ? Omit<PropertyOf<EffectOf<First>>, keyof ChainProperties<Rest>> & ChainProperties<Rest> : NoProperties;
-export {};

package/dist/middleware.js

@@ -1,9 +0,0 @@
-/**
- * The middleware chain a CLI runs every command inside, and the types that carry what each
- * middleware publishes into the context. The effect a middleware declares rides along as
- * type-only metadata, so an inline `middleware: [...]` array is enough for a handler to read
- * `ctx.db` with its real type; the shape matches `@sdxc/jobs`, so one package ships both.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */

package/dist/parse.d.ts

@@ -1,38 +0,0 @@
-/**
- * Splits an argument vector into the command it names, its positionals and every flag
- * occurrence, against the indexed contract. Every problem is collected rather than stopping at
- * the first, so one usage error lists all of them.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import type { Entry, Tree } from "./tree.js";
-/** One appearance of a flag on the command line. */
-export interface Occurrence {
-    /** The text after `=` or the next token; `true` for a boolean or a bare optional value. */
-    value: string | true;
-    /** Written as `--no-<name>`. */
-    negated: boolean;
-    /** The flag as typed, `--allow-net` or `-f`, for error messages. */
-    spelled: string;
-}
-/** What one argument vector asks for. */
-export interface Parsed {
-    /** The command or group it reaches. */
-    entry: Entry;
-    help: boolean;
-    version: boolean;
-    /** `--no-progress`: tasks print without animation. */
-    noProgress: boolean;
-    positionals: string[];
-    /** Occurrences by the flag's key, in command-line order. */
-    occurrences: Map<string, Occurrence[]>;
-    issues: string[];
-}
-/**
- * Parses `argv` against `tree`. Combined short flags (`-xvf`) are read as one unknown name.
- *
- * @param withVersion - Whether `--version` is answered, which it is only at the root of a CLI
- * that declares a version
- */
-export declare function parseArgv(tree: Tree, argv: readonly string[], withVersion: boolean): Parsed;

package/dist/parse.js

@@ -1,218 +0,0 @@
-/**
- * Splits an argument vector into the command it names, its positionals and every flag
- * occurrence, against the indexed contract. Every problem is collected rather than stopping at
- * the first, so one usage error lists all of them.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import { isGroup } from "./command.js";
-import { closest } from "./suggest.js";
-/** A token that starts a flag: a dash and something after it, other than a negative number. */
-function isFlagToken(token) {
-    return token.startsWith("-") && token !== "-" && !/^-\d/.test(token);
-}
-/**
- * Parses `argv` against `tree`. Combined short flags (`-xvf`) are read as one unknown name.
- *
- * @param withVersion - Whether `--version` is answered, which it is only at the root of a CLI
- * that declares a version
- */
-export function parseArgv(tree, argv, withVersion) {
-    let parsed = {
-        entry: tree.root,
-        help: false,
-        version: false,
-        noProgress: false,
-        positionals: [],
-        occurrences: new Map(),
-        issues: [],
-    };
-    let index = 0;
-    let rest = false;
-    /** Flag tokens read at a group, replayed against the member the command line goes on to name. */
-    let atGroup = [];
-    /** How many issues stood before the current group's flags were read. */
-    let groupIssues = 0;
-    /** Records a global flag, answering whether `token` was one. */
-    function global(token) {
-        if (token === "--help" || token === "-h")
-            parsed.help = true;
-        else if (token === "--no-progress")
-            parsed.noProgress = true;
-        else if (token === "--version" && withVersion && parsed.entry === tree.root) {
-            parsed.version = true;
-        }
-        else
-            return false;
-        return true;
-    }
-    while (index < argv.length) {
-        let token = argv[index];
-        index += 1;
-        if (rest) {
-            parsed.positionals.push(token);
-            continue;
-        }
-        if (token === "--") {
-            rest = true;
-            continue;
-        }
-        if (isFlagToken(token)) {
-            if (global(token))
-                continue;
-            let start = index - 1;
-            index = readFlag(tree, parsed, argv, index, token);
-            if (isGroup(parsed.entry.node))
-                atGroup.push(...argv.slice(start, index));
-            continue;
-        }
-        if (isGroup(parsed.entry.node) && parsed.positionals.length === 0) {
-            let child = parsed.entry.children.get(token);
-            if (child === undefined && parsed.entry.arguments.length > 0) {
-                parsed.positionals.push(token);
-                continue;
-            }
-            if (child === undefined) {
-                let suggestion = closest(token, parsed.entry.children.keys());
-                let hint = suggestion === undefined ? "" : `; did you mean "${suggestion}"?`;
-                parsed.issues.push(`Unknown command "${token}" for ${parsed.entry.title}${hint}`);
-                for (let remaining of argv.slice(index)) {
-                    if (remaining === "--help" || remaining === "-h")
-                        parsed.help = true;
-                }
-                return parsed;
-            }
-            parsed.entry = child;
-            parsed.issues.length = groupIssues;
-            replay(tree, parsed, atGroup);
-            groupIssues = parsed.issues.length;
-            if (child.rest)
-                rest = true;
-            continue;
-        }
-        parsed.positionals.push(token);
-    }
-    if (rest &&
-        isGroup(parsed.entry.node) &&
-        parsed.entry.arguments.length === 0 &&
-        parsed.positionals.length > 0) {
-        parsed.issues.push(`Unknown command "${parsed.positionals[0]}" for ${parsed.entry.title}`);
-    }
-    return parsed;
-}
-/**
- * Re-reads the flag tokens written before a member's name against that member, so
- * `prog make --dry-run job` reaches `job`'s `--dry-run` and a group's flag the member lacks is
- * reported as unknown to it. The caller drops what the group's own reading recorded.
- */
-function replay(tree, parsed, tokens) {
-    let replayed = tokens.splice(0);
-    parsed.occurrences = new Map();
-    let index = 0;
-    while (index < replayed.length) {
-        let token = replayed[index];
-        index = readFlag(tree, parsed, replayed, index + 1, token);
-    }
-}
-/** Reads one flag token of a command, answering the index after any value it consumed. */
-function readFlag(tree, parsed, argv, index, token) {
-    let long = token.startsWith("--");
-    let body = token.slice(long ? 2 : 1);
-    let separator = body.indexOf("=");
-    let name = separator === -1 ? body : body.slice(0, separator);
-    let inline = separator === -1 ? undefined : body.slice(separator + 1);
-    let spelled = `${long ? "--" : "-"}${name}`;
-    let entry = parsed.entry;
-    let negated = false;
-    let flag = long ? entry.longs.get(name) : entry.shorts.get(name);
-    if (flag === undefined && long && name.startsWith("no-")) {
-        let positive = entry.longs.get(name.slice(3));
-        if (positive?.spec.kind === "boolean") {
-            flag = positive;
-            negated = true;
-        }
-    }
-    if (flag === undefined) {
-        parsed.issues.push(unknownFlag(tree, entry, token));
-        return inline === undefined && ownersTakeValue(tree, long ? name : "")
-            ? skipValue(argv, index)
-            : index;
-    }
-    let list = parsed.occurrences.get(flag.key) ?? [];
-    parsed.occurrences.set(flag.key, list);
-    if (flag.spec.kind === "boolean") {
-        if (inline !== undefined)
-            parsed.issues.push(`${spelled} takes no value`);
-        else
-            list.push({ value: true, negated, spelled });
-        return index;
-    }
-    if (inline === "") {
-        parsed.issues.push(`${spelled} needs a value`);
-        return index;
-    }
-    if (inline !== undefined) {
-        list.push({ value: inline, negated: false, spelled });
-        return index;
-    }
-    if (flag.spec.optionalValue) {
-        list.push({ value: true, negated: false, spelled });
-        return index;
-    }
-    let next = argv[index];
-    if (next === undefined || isFlagToken(next) || next === "--") {
-        parsed.issues.push(`${spelled} needs a value`);
-        return index;
-    }
-    list.push({ value: next, negated: false, spelled });
-    return index + 1;
-}
-/**
- * Whether every command declaring `--<name>` reads a value after it, so the word following a
- * misplaced `--cron "0 8 * * *"` is its value rather than a second, unexpected argument.
- */
-function ownersTakeValue(tree, name) {
-    let owners = tree.owners.get(name) ?? [];
-    return (owners.length > 0 &&
-        owners.every((owner) => {
-            let spec = owner.longs.get(name)?.spec;
-            return spec !== undefined && spec.kind !== "boolean" && !spec.optionalValue;
-        }));
-}
-/** The index after the value at `index`, or `index` when the next token is no value. */
-function skipValue(argv, index) {
-    let next = argv[index];
-    return next === undefined || isFlagToken(next) || next === "--" ? index : index + 1;
-}
-/**
- * The message for a flag `entry` does not declare: the commands that do declare it, or the
- * closest name it does declare.
- */
-function unknownFlag(tree, entry, token) {
-    let long = token.startsWith("--");
-    let body = token.slice(long ? 2 : 1);
-    let name = body.split("=")[0];
-    let spelled = `${long ? "--" : "-"}${name}`;
-    let positive = name.startsWith("no-") ? name.slice(3) : name;
-    let owners = long ? (tree.owners.get(name) ?? tree.owners.get(positive) ?? []) : [];
-    if (owners.length > 0) {
-        let titles = owners.map((owner) => owner.title);
-        let listed = titles.length === 1
-            ? titles[0]
-            : `${titles.slice(0, -1).join(", ")} and ${titles.at(-1)}`;
-        return `${spelled} is not a flag of ${entry.title}; ${listed} ${titles.length === 1 ? "takes" : "take"} it`;
-    }
-    let candidates = [];
-    if (long) {
-        for (let flag of entry.flags) {
-            candidates.push(flag.spec.name, ...flag.spec.aliases);
-            if (flag.spec.kind === "boolean")
-                candidates.push(`no-${flag.spec.name}`);
-        }
-        candidates.push("help");
-    }
-    let suggestion = long ? closest(name, candidates) : undefined;
-    let hint = suggestion === undefined ? "" : `; did you mean --${suggestion}?`;
-    return `Unknown flag ${spelled}${hint}`;
-}

package/dist/prompt.d.ts

@@ -1,153 +0,0 @@
-/**
- * The seven prompt kinds as declarations: what a flag or argument asks when the command line
- * leaves it out, and the option shapes `ctx.prompt` takes when a handler asks on its own. A
- * declaration runs nothing; the run decides whether to ask, answer from a default or fail.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-import type { Result } from "@sdxc/result";
-import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { CancelledError } from "./errors.js";
-/** Brands a prompt declaration so a flag can tell it from a plain options object. */
-declare const PROMPT: unique symbol;
-/**
- * When a bound prompt asks: `"missing"` only when the command line left its input out and no
- * default applies, `"always"` also when a default exists, preselecting it, for a choice the user
- * should see. A value on the command line skips the prompt either way.
- */
-export type Ask = "missing" | "always";
-/** One option of a list prompt. */
-export interface Choice<T> {
-    value: T;
-    /** What the list shows. @default String(value) */
-    label?: string;
-    /** Dimmed text after the label. */
-    hint?: string;
-    /** Shown dimmed and skipped by the cursor. */
-    disabled?: boolean;
-}
-/** A list prompt's options: plain values, shown as written, or choices. */
-export type Choices<T> = readonly (Choice<T> | (T & (string | number)))[];
-/** Options every prompt kind takes. */
-export interface PromptBase {
-    /** The question, also printed in the summary line once answered. */
-    message: string;
-    /** @default "missing" */
-    ask?: Ask;
-}
-/** A line of text. */
-export interface TextOptions extends PromptBase {
-    /** Dimmed text shown while the answer is empty. */
-    placeholder?: string;
-}
-/** A secret line of text. */
-export interface PasswordOptions extends PromptBase {
-    /** `false` echoes nothing as the user types. @default true, one `•` per character */
-    mask?: boolean;
-}
-/** A number, typed or stepped with the arrow keys. */
-export interface NumberOptions extends PromptBase {
-    min?: number;
-    max?: number;
-    /** How far one arrow press moves. @default 1 */
-    step?: number;
-}
-/** A yes-or-no question. */
-export interface ConfirmOptions extends PromptBase {
-    /** What the toggle and the summary line call a yes. @default "Yes" */
-    active?: string;
-    /** What the toggle and the summary line call a no. @default "No" */
-    inactive?: string;
-}
-/** One value from a list. */
-export interface SelectOptions<T = unknown> extends PromptBase {
-    options: Choices<T>;
-}
-/** Any number of values from a list. */
-export interface MultiselectOptions<T = unknown> extends PromptBase {
-    options: Choices<T>;
-    /** Fewest values Enter accepts. */
-    min?: number;
-    /** Most values Enter accepts. */
-    max?: number;
-}
-/** One value, or several with `multiple`, from a list filtered by what the user types. */
-export interface SearchOptions<T = unknown> extends PromptBase {
-    options: Choices<T>;
-    placeholder?: string;
-    /** Space toggles options and Enter answers every toggled one. */
-    multiple?: boolean;
-    min?: number;
-    max?: number;
-}
-/** Every prompt kind with the options it takes. */
-export interface PromptKinds {
-    text: TextOptions;
-    password: PasswordOptions;
-    number: NumberOptions;
-    confirm: ConfirmOptions;
-    select: SelectOptions;
-    multiselect: MultiselectOptions;
-    search: SearchOptions;
-}
-/** A prompt kind's name. */
-export type PromptKind = keyof PromptKinds;
-/** A prompt bound to the flag or argument it fills. */
-export interface PromptDeclaration<Kind extends PromptKind = PromptKind> {
-    readonly [PROMPT]: true;
-    readonly kind: Kind;
-    readonly options: PromptKinds[Kind];
-}
-/** Whether `value` is a prompt declaration. */
-export declare function isPromptDeclaration(value: unknown): value is PromptDeclaration;
-/**
- * Prompt declarations for flags and arguments. The answer goes through the same schema as a
- * value typed on the command line, and a failed check keeps the prompt open with the issue
- * under it.
- *
- * @example flag.string("template", { default: "app", prompt: prompt.select({ message: "Which template?", options: TEMPLATES }) })
- * @example argument(s.string(), { prompt: prompt.text({ message: "Where should the project go?" }) })
- */
-export declare const prompt: {
-    text: (options: TextOptions) => PromptDeclaration<"text">;
-    password: (options: PasswordOptions) => PromptDeclaration<"password">;
-    number: (options: NumberOptions) => PromptDeclaration<"number">;
-    confirm: (options: ConfirmOptions) => PromptDeclaration<"confirm">;
-    select: (options: SelectOptions<unknown>) => PromptDeclaration<"select">;
-    multiselect: (options: MultiselectOptions<unknown>) => PromptDeclaration<"multiselect">;
-    search: (options: SearchOptions<unknown>) => PromptDeclaration<"search">;
-};
-/** What a handler-called prompt adds to a declaration's options. */
-export interface AskOptions<T> {
-    /** The answer without a terminal, so the command still runs in CI or under an agent. */
-    default: T;
-    /**
-     * What a terminal starts from, preselected or filled in, when it differs from `default`: a
-     * question can answer no in CI and still take yes on Enter.
-     * @default the `default`
-     */
-    initial?: T;
-    /** The name a test's scripted `answers` object answers this prompt by. */
-    name?: string;
-    /** Checks the answer; a failed check keeps the prompt open with the issue under it. */
-    schema?: StandardSchemaV1<T, unknown>;
-}
-/** Why a handler-called prompt has no answer: the user cancelled, or a test left it unscripted. */
-export type PromptError = CancelledError | Error;
-/** Prompts a handler asks itself, for questions that depend on earlier work. */
-export interface Prompter {
-    text(options: TextOptions & AskOptions<string>): Promise<Result<string, PromptError>>;
-    password(options: PasswordOptions & AskOptions<string>): Promise<Result<string, PromptError>>;
-    number(options: NumberOptions & AskOptions<number>): Promise<Result<number, PromptError>>;
-    confirm(options: ConfirmOptions & AskOptions<boolean>): Promise<Result<boolean, PromptError>>;
-    select<T>(options: SelectOptions<T> & AskOptions<NoInfer<T>>): Promise<Result<T, PromptError>>;
-    multiselect<T>(options: MultiselectOptions<T> & AskOptions<readonly NoInfer<T>[]>): Promise<Result<T[], PromptError>>;
-    search<T>(options: SearchOptions<T> & {
-        multiple: true;
-    } & AskOptions<readonly NoInfer<T>[]>): Promise<Result<T[], PromptError>>;
-    search<T>(options: SearchOptions<T> & AskOptions<NoInfer<T>>): Promise<Result<T, PromptError>>;
-}
-/** The choices of a list prompt with every label and flag filled in. */
-export declare function normalizeChoices<T>(choices: Choices<T>): Required<Choice<T>>[];
-export {};

package/dist/prompt.js

@@ -1,53 +0,0 @@
-/**
- * The seven prompt kinds as declarations: what a flag or argument asks when the command line
- * leaves it out, and the option shapes `ctx.prompt` takes when a handler asks on its own. A
- * declaration runs nothing; the run decides whether to ask, answer from a default or fail.
- *
- * @author [Sergio Xalambrí](https://sergiodxa.com)
- * @copyright Sergio Xalambrí 2026
- */
-/** Brands a prompt declaration so a flag can tell it from a plain options object. */
-const PROMPT = Symbol.for("@sdxc/cli.prompt");
-/** Whether `value` is a prompt declaration. */
-export function isPromptDeclaration(value) {
-    return typeof value === "object" && value !== null && PROMPT in value;
-}
-/** Builds one prompt declaration. */
-function declare(kind) {
-    return (options) => ({
-        [PROMPT]: true,
-        kind,
-        options,
-    });
-}
-/**
- * Prompt declarations for flags and arguments. The answer goes through the same schema as a
- * value typed on the command line, and a failed check keeps the prompt open with the issue
- * under it.
- *
- * @example flag.string("template", { default: "app", prompt: prompt.select({ message: "Which template?", options: TEMPLATES }) })
- * @example argument(s.string(), { prompt: prompt.text({ message: "Where should the project go?" }) })
- */
-export const prompt = {
-    text: declare("text"),
-    password: declare("password"),
-    number: declare("number"),
-    confirm: declare("confirm"),
-    select: declare("select"),
-    multiselect: declare("multiselect"),
-    search: declare("search"),
-};
-/** The choices of a list prompt with every label and flag filled in. */
-export function normalizeChoices(choices) {
-    return choices.map((choice) => {
-        if (typeof choice === "object" && choice !== null && "value" in choice) {
-            return {
-                value: choice.value,
-                label: choice.label ?? String(choice.value),
-                hint: choice.hint ?? "",
-                disabled: choice.disabled ?? false,
-            };
-        }
-        return { value: choice, label: String(choice), hint: "", disabled: false };
-    });
-}

package/dist/resolve.d.ts

@@ -1,27 +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 type { Result } from "@sdxc/result";
-import type { Parsed } from "./parse.js";
-import type { Prompter } from "./prompt.js";
-import type { Session } from "./session.js";
-/** The values a handler reads. */
-export interface Inputs {
-    arguments: Record<string, unknown>;
-    flags: Record<string, unknown>;
-}
-/**
- * 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 declare function resolveInputs(parsed: Parsed, session: Session): Promise<Result<Inputs, Error>>;
-/** The `ctx.prompt` of one run: asks on a terminal or from a script, else answers the default. */
-export declare function createPrompter(session: Session): Prompter;