caique/decide

import { decide } from 'caique/decide';

function decide({ value, spec, option, flag, runtime, flags, required }: DecideInput): Decision;

interface DecideInput {
    /** Whatever the option resolved to before prompting, from any source. */
    value: unknown;
    spec: PromptSpec;
    /** The option's long name, for the flag a refusal names. */
    option: string;
    /**
     * How a refusal names it, when `--<option>` is not how it is passed: `<name>` for a
     * positional (R1, `promptFor`), or a host's kebab-case flag for a camelCase key.
     */
    flag?: string;
    runtime: Runtime;
    /** Absent, or `undefined`, is a run that asked for none of them. */
    flags?: Flags | undefined;
    /** Whether the option must have a value for the command to run. */
    required?: boolean;
}

interface Decision {
    action: 'skip' | 'prompt' | 'answer' | 'error';
    /** For `answer`: what to use without asking. Today only `--yes` produces one. */
    value?: boolean;
    /** For `error`: an E1 code the caller maps to its own error type. */
    code?: 'USAGE';
    message?: string;
    /** For `error`: the one sentence that turns a refusal into a next step. */
    fix?: string;
}

interface Flags {
    /** `--json`: a machine is reading stdout, so no one is here to type (R6). */
    json?: boolean;
    /** `--yes`: every `confirm` is already answered true (R3). */
    yes?: boolean;
    /** `--interactive`: prompt for what is missing even where we would not have (R3). */
    interactive?: boolean;
    /** `--interactive=all`: prompt for every promptable option, not only the required ones. */
    interactiveAll?: boolean;
}

interface Runtime {
    env: Record<string, string | undefined>;
    isTTY: {
        stdin: boolean;
    };
    /**
     * The language a person is spoken to in, resolved by the host (`localised-human-surfaces` R6),
     * or a program's own: what `sayFor` from `caique/locale` is given. caique never reads `LANG`.
     */
    locale?: string | undefined;
}