burgee

import { defineError, ExitCode, isExitCode, … } from 'burgee';

function camel(flag: string): string;

function checkCommand(name: string, declared: Declared): void;

function checkDefinition(name: string, options: Record<string, OptionSpec>): void;

function defineCommand<const S extends OptionSpecs = OptionSpecs>(command: Command<S>): Command<S>;

function defineError(definition: ErrorDefinition): DefinedErrorClass;

function defineProgram(program: Program): Manifest;

function detectAgent(env: Record<string, string | undefined>, tty: boolean, probes?: readonly AgentProbe[]): Detection;

function execute(manifest: Manifest, opts?: RunOptions & {
    root?: string[];
    from?: 'node' | 'user';
}): Promise<void>;

function kebab(name: string): string;

function resolveCommand(manifest: Manifest, argv: readonly string[]): CommandNode | null;

function run<S extends OptionSpecs>(target: Command<S> | Manifest, opts?: RunOptions): Promise<void>;

function runCommand(manifest: Manifest, argv: readonly string[], opts?: Pick<RunOptions, 'env' | 'cwd' | 'entry' | 'stdin'>): Promise<RunResult>;

function sharedOptions<const T extends OptionSpecs>(name: string, specs: T): T;

class AuthError extends Error {
    readonly hint?: string | undefined;
    readonly fix?: string | undefined;
    constructor(message: string, hint?: string | undefined, fix?: string | undefined);
}

class UsageError extends Error {
    readonly hint?: string | undefined;
    constructor(message: string, hint?: string | undefined);
}

const AGENT_PROBES: readonly AgentProbe[];

interface ActionRequiredSpec {
    /** A short machine-readable reason: `login`, `confirm`, `missing-config` … */
    reason: string;
    message: string;
    /** Runnable commands, each with when to run it; the engine prefixes the program and carries the caller's flags. */
    next?: readonly {
        command: string;
        when: string;
    }[];
    hint?: string;
}

interface AgentProbe {
    /** Environment variable whose presence names the agent. */
    variable: string;
    agent: string;
}

interface ArgumentSpec {
    name: string;
    description?: string;
    required?: boolean;
    variadic?: boolean;
    default?: string;
    /** `'file'`: a path, where `-` means standard input — handed to the handler as `ctx.stdin` (S4). */
    type?: 'file';
}

interface Command<S extends OptionSpecs = OptionSpecs> {
    name: string;
    description?: string;
    /** Shown in command lists instead of the description. */
    summary?: string;
    /** Declared once (S1); the handler's `options` type is derived from it. */
    options?: S;
    arguments?: ArgumentSpec[];
    examples?: Example[];
    /** Heading this command is listed under in its parent's help. */
    group?: string;
    epilogue?: string;
    hidden?: boolean;
    /** What replaces this command, e.g. `'deploy'`: shown in help, `--schema` and the warning. `true` alone is refused (D1). */
    deprecated?: boolean | string;
    /**
     * What running it does to the world (N6). Declaring one of the three is what exposes the
     * command as an MCP tool (N2); `'withheld'` declares that it is not offered to agents.
     *
     * Optional on the type and **required at definition time** on a command that runs:
     * `defineCommand` refuses one that omits it. It stays optional here because a group that
     * only holds subcommands declares none, and TypeScript cannot make a field's presence
     * depend on a sibling's without splitting `Command` into a union that would cost the
     * option-spec inference every caller of this type relies on.
     */
    effects?: DeclaredEffects;
    /** Relationships between options, validated before choices and the handler (S2, S6). */
    relations?: readonly Relation[];
    /**
     * The top-level fields of this command's result (N14). With them, `--json=` lists them
     * without running the handler and `--json=a,b` refuses an unknown field before it runs.
     * Without them `--json=a,b` still selects, checked against the result's own keys.
     */
    fields?: readonly string[];
    /** Absent on a group that only holds subcommands. `NoInfer`: the spec fixes S, the handler only reads it. */
    run?: (ctx: CommandContext<InferOptions<NoInfer<S>>>) => unknown;
    /** The handler's module, imported on dispatch only (M2); everything else about the command is declared here. */
    load?: () => Promise<LazyModule>;
    commands?: AnyCommand[];
}

interface CommandContext<O> extends Omit<RunContext, 'options'> {
    options: O;
}

interface CommandNode {
    path: string[];
    description?: string;
    /** Shown in command lists instead of the description (yargs #1265). */
    summary?: string;
    options: Record<string, OptionSpec>;
    relations?: readonly Relation[];
    arguments?: ArgumentSpec[];
    examples?: Example[];
    /** Heading this command is listed under in its parent's help (yargs #684). */
    group?: string;
    epilogue?: string;
    hidden?: boolean;
    deprecated?: boolean | string;
    /**
     * What running it does to the world, or `'withheld'` (N2, N6). Required on a node that
     * runs — `checkCommand` refuses one that omits it — and optional on the type, because a
     * group carries no `effects` and the host front-ends build nodes that never reach that
     * door: commander and yargs have no notion of effects and their graded suites declare
     * none, so a façade's command is withheld in fact and cannot be made to say so.
     */
    effects?: DeclaredEffects;
    /** The result's top-level fields, as declared (N14); what `--json=` lists. */
    fields?: readonly string[];
    run?: (ctx: RunContext) => unknown;
    /**
     * The handler's module, imported on dispatch only (M2): the manifest — help, schema,
     * completions, MCP tool list — is complete from this node without loading it. A node
     * with `load` and no `run` gets a `run` that imports on first call.
     */
    load?: () => Promise<LazyModule>;
    /** Which plugin contributed this, if any. Declared, never diffed (M3). */
    plugin?: string;
}

interface DefinedErrorClass {
    new (message: string, options?: DefinedErrorOptions): Error & DefinedErrorOptions;
    readonly exitCode: number;
}

interface DefinedErrorOptions {
    hint?: string;
    fix?: string;
}

interface Detection {
    /** The agent named by the environment, if any; `AI_AGENT`'s own value when it names one. */
    agent?: string;
    /**
     * stdout is a terminal and no agent is named, or `FORCE_TTY=1`: the output side, which help's
     * colour reads. Whether to *ask* is `ctx.interactive`, roundel's rule over stdin and `CI`.
     */
    interactive: boolean;
}

interface ErrorDefinition {
    /** The class name, shown as the error's `name`. */
    name: string;
    /** The exit code, 7–125, owned by this class alone. */
    code: number;
}

interface Example {
    command: string;
    description?: string;
}

interface Hook {
    filter?: HookFilter;
    /** `parse` may return the argv to use instead; every other stage's return is ignored. */
    handler: (ctx: HookContext) => unknown;
}

interface LazyModule {
    default?: (ctx: RunContext) => unknown;
    run?: (ctx: RunContext) => unknown;
}

interface OptionSpec {
    /** `boolean` never consumes a value (S7); `number` rejects NaN and Infinity (S3). */
    type: 'string' | 'boolean' | 'number';
    /**
     * D3 / D-119 — values computed when a person presses TAB: the generated script calls the
     * program back (`<program> __complete <command> --<option> <partial>`) for this option and
     * no other. Declaring it is the opt-in; an option without one completes from `choices`, or
     * not at all, and never runs the program.
     */
    complete?: (partial: string) => Iterable<string> | Promise<Iterable<string>>;
    description?: string;
    required?: boolean;
    short?: string;
    default?: string | boolean | number | readonly string[] | readonly number[];
    /** Environment variable consulted when the flag is absent (V2). Read from the injected env, never process.env directly. */
    env?: string;
    /** Allowed values, enforced and shown as `(one of: a, b)` (yargs #1408, #1186). */
    choices?: readonly string[];
    /** Repeatable, and split on `separator` (`,` unless declared): `--tag a --tag b,c` → `['a', 'b', 'c']` (S8). */
    multiple?: boolean;
    separator?: string;
    /**
     * The other options this one requires: `--out --dependsOn force` is a usage error without
     * `--force` (S2). Sugar for a `{ implies: [this, other] }` relation per name, and nothing
     * else — one engine, one order, one error vocabulary.
     *
     * It exists as a second spelling because the first states the constraint away from the
     * option it constrains: a reader looking at `out` learns nothing from a `relations` entry
     * three keys down, and neither does the help line for `--out`. Both incumbents spell it on
     * the option (commander `.implies()`, yargs `.implies()`), and so does Fig, whose `Option`
     * declares this exact key.
     */
    dependsOn?: readonly string[];
    /**
     * The other options this one may not be given with (S2): `{ conflicts: [this, other] }` per
     * name. Commander's `.conflicts()`, yargs' `.conflicts()`, Fig's `exclusiveOn`.
     *
     * One-sided is enough — the relation it compiles to holds whichever of the two argv names
     * first — so declare it once, on whichever option the constraint belongs to.
     */
    exclusive?: readonly string[];
    /** `number` only. */
    minimum?: number;
    maximum?: number;
    integer?: boolean;
    /** Any Standard Schema, run on the parsed value; its issues become a usage error (S1). */
    schema?: StandardSchemaV1;
    /** The value's name in help: `--id <dataset-id>` (yargs #833). */
    placeholder?: string;
    /** `true` renders `(deprecated)`; a string names the replacement: `(deprecated: use --force)` (yargs #2248). */
    deprecated?: boolean | string;
    hidden?: boolean;
    /**
     * `boolean` only: whether `--no-<name>` is accepted. Every boolean is negatable unless this
     * says `false`. burgee's own parser negates every boolean (see `toParseConfig`); the
     * commander façade sets `false` where commander would refuse the negation, so completions
     * and `--mcp` never offer or send a flag the parser behind them rejects.
     */
    negatable?: boolean;
    /** The shared set this option was copied from (M4); `--schema` carries it, help lists the option like any other. */
    sharedFrom?: string;
}

interface Program {
    name: string;
    version?: string;
    description?: string;
    /** Options read `PREFIX_OPTION_NAME` from the environment unless they name their own variable (V2). */
    envPrefix?: string;
    /** Characters of `--schema` output above which it is summarised (N13); 48,000 by default. */
    schemaBudget?: number;
    /**
     * Opt into config discovery (V6): `--config <path>` > `NAME_CONFIG` > `./name.config.{json,mjs,js,cjs}`
     * > `package.json#name` > the user config directory; `true` uses the program's name.
     */
    config?: boolean | {
        name: string;
    };
    commands: AnyCommand[];
}

interface RunContext {
    options: Record<string, unknown>;
    positionals: string[];
    passthrough: string[];
    /**
     * Standard input, present only when a `type: 'file'` argument was given `-` (S4). The
     * positional still reads `-`, so a handler checks it the same way it checks a path.
     */
    stdin?: NodeJS.ReadableStream;
    env: Record<string, string | undefined>;
    /** Exit with an E1 code. Unwinds cleanly: the code is honoured and nothing is printed. */
    exit: (code: number) => never;
    /**
     * A person may be asked and be expected to answer (N12): roundel's `interactive()`, the
     * family's one rule — a terminal on stdin, no `CI`, no detected agent — or `FORCE_TTY=1`.
     */
    interactive: boolean;
    /** The agent the environment names, if any (N12). */
    agent?: string;
    /** Stop and tell the caller what to do instead of blocking on a prompt (N11). */
    actionRequired: (spec: ActionRequiredSpec) => never;
    /**
     * Cleanup that runs on **every** path out of the run (E5): a normal return, `ctx.exit`,
     * Ctrl-C, SIGTERM, a terminal closing, an uncaught throw. Returns the function that
     * unregisters it, for a command that cleaned up on its own.
     *
     * The handler runs after stdout has been drained (O5) and before the terminal is handed
     * back, and it runs exactly once however many of those arrive together. `label` is what a
     * breached shutdown deadline calls it; without one an arrow is reported as `(anonymous)`,
     * and the anonymous arrow is the shape that hangs.
     *
     * Typed here rather than re-exported from `closeout`, so a command's signature does not
     * change when that package's does.
     */
    onExit: (handler: () => void | Promise<void>, label?: string) => () => void;
}

interface RunOptions {
    argv?: string[];
    /** Read by `--mcp`, which serves JSON-RPC over it; its `isTTY` is whether a person may be asked (N12). */
    stdin?: NodeJS.ReadableStream;
    /** The environment env-bound options read from. Injected by the harness; the process's own otherwise. */
    env?: Record<string, string | undefined>;
    /** `columns` is read when present, so help wraps to the terminal (H3); `isTTY` decides whether help is coloured (O2). */
    stdout?: {
        write: (s: string) => unknown;
        columns?: number;
        isTTY?: boolean;
    };
    stderr?: {
        write: (s: string) => unknown;
    };
    /** Receives the E1 code. The default calls process.exit; an injected one may simply record it. */
    exit?: (code: number) => void;
    /** Where config discovery starts; the process's own otherwise. */
    cwd?: string;
    /** The entry file, whose nearest package.json owns the program's version (V4); `process.argv[1]` otherwise. */
    entry?: string;
}

interface RunResult {
    code: number;
    stdout: string;
    stderr: string;
}

interface StandardSchemaV1<Output = unknown> {
    readonly '~standard': {
        readonly version: 1;
        readonly vendor: string;
        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
    };
}

interface Usage {
    /** The command line from the program name: `demo greet [options] <name>`. */
    command: string;
    /** A runnable command's options, as typed. */
    options?: UsageRow[];
    /** A group's commands, for a word it does not know. */
    commands?: UsageRow[];
    /** The command that lists every row, present only when some were left out. */
    more?: string;
}

interface UsageRow {
    /** `--code <value>`, `-n, --name <value>`, or a command word. */
    name: string;
    description: string;
}

type AnyCommand = Command<any>;

type Effects = 'read_only' | 'idempotent' | 'non_idempotent';

type InferOptions<S extends Record<string, OptionSpec>> = {
    [K in keyof S]: Present<S[K]> extends true ? Many<S[K], Scalar<S[K]>> : Many<S[K], Scalar<S[K]>> | undefined;
};

type OptionSpecs = Record<string, OptionSpec>;

type Relation = {
    exactlyOneOf: readonly string[];
} | {
    atLeastOneOf: readonly string[];
} | {
    atMostOneOf: readonly string[];
} | {
    conflicts: readonly string[];
} | {
    implies: readonly [string, string | ((values: Record<string, unknown>) => boolean)];
};

type StandardResult<Output> = {
    readonly value: Output;
    readonly issues?: undefined;
} | {
    readonly issues: readonly {
        readonly message: string;
    }[];
};