# caique/ask

> Every export of caique/ask, with its signature and doc comment: ask, projection, plus 6 types.

Source: https://caique.interlace.tools/docs/api/ask

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

The six widgets, in line mode (R5) — and line mode is not a fallback, it is the floor.

```ts
import { ask, projection } from 'caique/ask';
```

## Functions

### ask

Ask one prompt and return its answer.

```ts
function ask(prompt: BoundPrompt | PromptSpec, io: Io): Promise<Asked>;
```

| Parameter | Type |
| :-- | :-- |
| `prompt` | `BoundPrompt \| PromptSpec` |
| `io` | `Io` |

**Returns** `Promise<Asked>`

### projection

What a widget would have written, without reading anything — the static projection (U3).
The docs gallery, `--help` and a transcript in an issue all want the question without
the conversation, and every other package in this family can answer that; so does this.

```ts
function projection(spec: PromptSpec): string;
```

| Parameter | Type |
| :-- | :-- |
| `spec` | `PromptSpec` |

**Returns** `string`

## Interfaces

### Io

```ts
interface Io {
    reader: Reader;
    writer: Writer;
    /**
     * The run's language for what caique draws itself — the instruction under a list, a problem
     * with an answer, the giving-up line — never the author's question (`localised-human-surfaces`
     * R6). `sayFor(runtime.locale)` from `caique/locale` builds it; absent, it is English.
     */
    say?: (english: string) => string;
}
```

### Reader

A line of input, or `undefined` when the stream ended — which is a cancellation.

```ts
interface Reader {
    line(options?: ReadOptions): Promise<string | undefined>;
}
```

### ReadOptions

```ts
interface ReadOptions {
    /**
     * Do not echo what is typed. Set for `password`, and honoured by whatever is reading —
     * this module never sees a terminal, so it cannot hide anything itself, and a widget
     * that never writes back what it read cannot leak it either.
     */
    hidden?: boolean;
}
```

### Writer

```ts
interface Writer {
    write(text: string): void;
    /**
     * How many columns the terminal behind this writer is, when it knows. Line mode never
     * reads it; the raw renderer does, because a row wider than the terminal occupies more
     * than one row of screen and the repaint has to climb all of them.
     */
    readonly columns?: number | undefined;
    /**
     * How many rows the terminal is, when it knows. The raw renderer windows a list to it, so a
     * list longer than the screen never climbs above the top row on a repaint.
     */
    readonly rows?: number | undefined;
}
```

## Types

### Answer

```ts
type Answer = string | boolean | string[];
```

### Asked

Answered, or cancelled — cancellation is a value here and a `CANCELLED` error above (R4).

```ts
type Asked = {
    ok: true;
    value: Answer;
} | {
    ok: false;
    reason: 'cancelled';
};
```

---

# caique/binding

> Every export of caique/binding, with its signature and doc comment: resolvePrompts, localise, plus 4 types.

Source: https://caique.interlace.tools/docs/api/binding

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

Resolving a whole command's prompts in one pass (R2, R3) — the piece a framework calls
from its `preAction` hook, after the environment and config layers have had their turn.

```ts
import { resolvePrompts, localise } from 'caique/binding';
```

## Functions

### resolvePrompts

```ts
function resolvePrompts<O extends PromptableOption>({ options, values, runtime, flags, io }: ResolveInput<O>): Promise<Resolved>;
```

| Parameter | Type |
| :-- | :-- |
| `{ options, values, runtime, flags, io }` | `ResolveInput<O>` |

**Returns** `Promise<Resolved>`

## Constants

### localise

A failure with its translation beside it (R6). `say` is the identity unless a pack speaks the
run's locale (`sayFor` returns `String` itself then). A failure without a `fix` gets none.

```ts
const localise: (failure: ResolveFailure, say: (english: string) => string) => ResolveFailure;
```

## Interfaces

### PromptableOption

What a host tells us about one option. Structural: any framework's spec satisfies it.

```ts
interface PromptableOption {
    required?: boolean;
    prompt?: PromptSpec;
    /**
     * How a refusal names it when `--<option>` is not how it is passed: `<name>` for a
     * positional, `--dry-run` for a host's camelCase `dryRun` key (R1, `promptFor`).
     */
    flag?: string;
}
```

### Resolved

```ts
interface Resolved {
    /** The values with every answered prompt written in. The input is not mutated. */
    values: Record<string, unknown>;
    /**
     * The first refusal, or nothing. First rather than all: the caller is about to exit, and
     * a person told about six missing flags one of which they will answer interactively has
     * been given a worse message than one told about the first.
     */
    failure?: ResolveFailure;
}
```

### ResolveFailure

```ts
interface ResolveFailure {
    option: string;
    code: 'USAGE' | 'CANCELLED';
    message: string;
    fix?: string;
    /**
     * `message` and `fix` in `runtime.locale`, when a registered pack speaks it
     * (`localised-human-surfaces` R6). Beside them and not in place of them: a refusal is a value a
     * host may write into a machine envelope, and those stay in English whatever the locale.
     */
    localised?: {
        message: string;
        fix?: string;
    };
}
```

### ResolveInput

```ts
interface ResolveInput<O extends PromptableOption = PromptableOption> {
    /** The command's options by name, in declaration order — a record preserves it. */
    options: Record<string, O>;
    /** What the values are after every other source has been consulted. */
    values: Record<string, unknown>;
    runtime: Runtime;
    flags?: Flags;
    io: Io;
}
```

---

# caique/clack

> Every export of caique/clack, with its signature and doc comment: CANCEL_SYMBOL, formatInstructionFooter, isCancel, isCI, isTTY, MULTISELECT_INSTRUCTIONS and 54 more, plus 26 types.

Source: https://caique.interlace.tools/docs/api/clack

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`caique/clack` — `@clack/prompts`' API on caique's own engine: its twelve prompts, its
writers, its symbols and its settings, under the names clack gives them.

```ts
import { CANCEL_SYMBOL, formatInstructionFooter, isCancel, … } from 'caique/clack';
```

## Functions

### formatInstructionFooter

The key hints under a list: one line, and the closing guide under it when there is one.

```ts
function formatInstructionFooter(instructions: string[], hasGuide: boolean): string[];
```

| Parameter | Type |
| :-- | :-- |
| `instructions` | `string[]` |
| `hasGuide` | `boolean` |

**Returns** `string[]`

### limitOptions

The window of options a list should draw, as lines, with `...` where it was cut.

```ts
function limitOptions<TOption>({ cursor, options, style, output, maxItems, columnPadding, rowPadding, }: LimitOptionsParams<TOption>): string[];
```

| Parameter | Type |
| :-- | :-- |
| `{ cursor, options, style, output, maxItems, columnPadding, rowPadding, }` | `LimitOptionsParams<TOption>` |

**Returns** `string[]`

### updateSettings

Change the settings every later prompt reads.

```ts
function updateSettings(updates: ClackSettings): void;
```

| Parameter | Type |
| :-- | :-- |
| `updates` | `ClackSettings` |

**Returns** `void`

## Constants

### autocomplete

`autocomplete` — `select` with a search box over the list.

```ts
const autocomplete: <Value>(opts: AutocompleteOptions<Value>) => Answer<Value>;
```

### autocompleteMultiselect

`autocompleteMultiselect` — `multiselect` with a search box over the list.

```ts
const autocompleteMultiselect: <Value>(opts: AutocompleteMultiSelectOptions<Value>) => Answer<Value[]>;
```

### cancel

Closes a session that was cancelled: the end of the guide, and the message in red. Not decoration, so never quiet.

```ts
const cancel: (message?: string, opts?: CommonOptions) => void;
```

### CANCEL_SYMBOL

What every prompt resolves to when it is cancelled. Test it with `isCancel`.

```ts
const CANCEL_SYMBOL: unique symbol;
```

### confirm

`confirm` — yes or no: arrows toggle, `y` and `n` answer at once.

```ts
const confirm: (opts: ConfirmOptions) => Answer<boolean>;
```

### date

`date` — a date typed field by field, or stepped with the arrows inside `minDate`…`maxDate`.

```ts
const date: (opts: DateOptions) => Answer<Date>;
```

### group

Ask a set of prompts in order; a cancelled one is recorded as `'canceled'` when `onCancel` is given.

```ts
const group: <T>(prompts: PromptGroup<T>, opts?: PromptGroupOptions<T>) => Promise<Prettify<PromptGroupAwaitedReturn<T>>>;
```

### groupMultiselect

`groupMultiselect` — a multi-selection in named groups; a group toggles all of its options.

```ts
const groupMultiselect: <Value>(opts: GroupMultiSelectOptions<Value>) => Answer<Value[]>;
```

### intro

Opens a session: the top of the guide, and a title beside it.

```ts
const intro: (title?: string, opts?: CommonOptions) => void;
```

### isCancel

Whether a prompt's answer is a cancellation rather than an answer.

```ts
const isCancel: (value: unknown) => value is symbol;
```

### isCI

Whether `CI` is the string `true`, which is the test clack makes. This and the glyph table
above stay clack's rules rather than roundel's: `interactive()` asks whether a person can
answer, which clack never asks, and clack's table counts `CI` where roundel's `unicode()` does not.
A caller's runtime is read when one is passed (`caique-quiet-seam` R1), the process's otherwise.

```ts
const isCI: (runtime?: {
    env: PolicyRuntime["env"];
}) => boolean;
```

### isTTY

Whether a stream is a terminal.

```ts
const isTTY: (output: {
    isTTY?: boolean;
}) => boolean;
```

### log

clack's `log`: a message on the guide, with a symbol for its kind. Every kind but `error` is decoration.

```ts
const log: {
    message: (text?: string | string[], opts?: LogMessageOptions) => void;
    info: (text: string, opts?: LogMessageOptions) => void;
    success: (text: string, opts?: LogMessageOptions) => void;
    step: (text: string, opts?: LogMessageOptions) => void;
    warn: (text: string, opts?: LogMessageOptions) => void;
    /** An alias for `log.warn()`. */
    warning: (text: string, opts?: LogMessageOptions) => void;
    /** A failure: written under a quiet runtime too, because `--quiet` never hides one. */
    error: (text: string, opts?: LogMessageOptions) => void;
};
```

### multiline

`multiline` — typing across lines; a second enter at the end submits, or tab reaches `[ submit ]`.

```ts
const multiline: (opts: MultiLineOptions) => Answer<string>;
```

### multiselect

`multiselect` — any number of options: space toggles, `a` toggles all, `i` inverts.

```ts
const multiselect: <Value>(opts: MultiSelectOptions<Value>) => Answer<Value[]>;
```

### MULTISELECT_INSTRUCTIONS

```ts
const MULTISELECT_INSTRUCTIONS: string[];
```

### note

A message in a box on the guide, with a title in its top edge.

```ts
const note: (text?: string, title?: string, opts?: NoteOptions) => void;
```

### outro

Closes a session: the end of the guide, and a last message beside it.

```ts
const outro: (message?: string, opts?: CommonOptions) => void;
```

### password

`password` — typing that is drawn as a mask and never echoed.

```ts
const password: (opts: PasswordOptions) => Answer<string>;
```

### path

`path` — an autocomplete over the filesystem, starting at `root` or the working directory.

```ts
const path: (opts: PathOptions) => Answer<string>;
```

### S_BAR

```ts
const S_BAR: string;
```

### S_BAR_END

```ts
const S_BAR_END: string;
```

### S_BAR_END_RIGHT

```ts
const S_BAR_END_RIGHT: string;
```

### S_BAR_H

```ts
const S_BAR_H: string;
```

### S_BAR_START

```ts
const S_BAR_START: string;
```

### S_BAR_START_RIGHT

```ts
const S_BAR_START_RIGHT: string;
```

### S_CHECKBOX_ACTIVE

```ts
const S_CHECKBOX_ACTIVE: string;
```

### S_CHECKBOX_INACTIVE

```ts
const S_CHECKBOX_INACTIVE: string;
```

### S_CHECKBOX_SELECTED

```ts
const S_CHECKBOX_SELECTED: string;
```

### S_CONNECT_LEFT

```ts
const S_CONNECT_LEFT: string;
```

### S_CORNER_BOTTOM_LEFT

```ts
const S_CORNER_BOTTOM_LEFT: string;
```

### S_CORNER_BOTTOM_RIGHT

```ts
const S_CORNER_BOTTOM_RIGHT: string;
```

### S_CORNER_TOP_LEFT

```ts
const S_CORNER_TOP_LEFT: string;
```

### S_CORNER_TOP_RIGHT

```ts
const S_CORNER_TOP_RIGHT: string;
```

### S_ERROR

```ts
const S_ERROR: string;
```

### S_INFO

```ts
const S_INFO: string;
```

### S_PASSWORD_MASK

```ts
const S_PASSWORD_MASK: string;
```

### S_RADIO_ACTIVE

```ts
const S_RADIO_ACTIVE: string;
```

### S_RADIO_INACTIVE

```ts
const S_RADIO_INACTIVE: string;
```

### S_STEP_ACTIVE

```ts
const S_STEP_ACTIVE: string;
```

### S_STEP_CANCEL

```ts
const S_STEP_CANCEL: string;
```

### S_STEP_ERROR

```ts
const S_STEP_ERROR: string;
```

### S_STEP_SUBMIT

```ts
const S_STEP_SUBMIT: string;
```

### S_SUCCESS

```ts
const S_SUCCESS: string;
```

### S_WARN

```ts
const S_WARN: string;
```

### select

`select` — one option from a list, drawn through `limitOptions`.

```ts
const select: <Value>(opts: SelectOptions<Value>) => Answer<Value>;
```

### SELECT_INSTRUCTIONS

```ts
const SELECT_INSTRUCTIONS: string[];
```

### selectKey

`selectKey` — one option, chosen by pressing the first letter of its value.

```ts
const selectKey: <Value extends string>(opts: SelectKeyOptions<Value>) => Answer<Value>;
```

### settings

The process-wide settings every prompt here reads, and `updateSettings` writes.

```ts
const settings: {
    actions: Set<Action>;
    aliases: Map<string, Action>;
    messages: {
        cancel: string;
        error: string;
    };
    withGuide: boolean;
};
```

### spinner

A spinner on the guide: animated on a terminal outside CI, printed once per message anywhere else.

```ts
const spinner: (opts?: SpinnerOptions) => SpinnerResult;
```

### stream

clack's `stream`: `log`, for text that arrives in pieces.

```ts
const stream: {
    message: typeof streamed;
    info: (chunks: Chunks) => Promise<void>;
    success: (chunks: Chunks) => Promise<void>;
    step: (chunks: Chunks) => Promise<void>;
    warn: (chunks: Chunks) => Promise<void>;
    warning: (chunks: Chunks) => Promise<void>;
    error: (chunks: Chunks) => Promise<void>;
};
```

### symbol

The glyph that opens a prompt's title line, coloured for its state.

```ts
const symbol: (state: State) => string;
```

### symbolBar

The guide bar beside a prompt's body, coloured for its state; none while it validates.

```ts
const symbolBar: (state: State) => string | undefined;
```

### tasks

Run tasks one after another, each under its own spinner, each ending on what it returned.

```ts
const tasks: (list: Task[], opts?: CommonOptions) => Promise<void>;
```

### text

`text` — one line of typing, with a placeholder, a default and a validator.

```ts
const text: (opts: TextOptions) => Answer<string>;
```

### unicode

Whether the terminal can draw clack's box characters; read once, as the incumbent reads it.

```ts
const unicode: boolean;
```

### unicodeOr

The first glyph where the terminal draws unicode, the second where it does not.

```ts
const unicodeOr: (glyph: string, fallback: string) => string;
```

## Interfaces

### AutocompleteMultiSelectOptions

```ts
interface AutocompleteMultiSelectOptions<Value> extends AutocompleteSharedOptions<Value> {
    initialValues?: Value[];
    required?: boolean;
}
```

### AutocompleteOptions

```ts
interface AutocompleteOptions<Value> extends AutocompleteSharedOptions<Value> {
    initialValue?: Value;
    initialUserInput?: string;
    completeOnTab?: boolean;
}
```

### ClackSettings

What `updateSettings` takes.

```ts
interface ClackSettings {
    /** Extra keys for an action — `{ w: 'up' }` — which never replace an existing alias. */
    aliases?: Record<string, Action>;
    messages?: {
        cancel?: string;
        error?: string;
    };
    /** `false` draws every prompt without its left-hand guide. */
    withGuide?: boolean;
}
```

### CommonOptions

The streams and settings every clack call accepts.

```ts
interface CommonOptions {
    input?: NodeJS.ReadableStream;
    output?: NodeJS.WritableStream & SizedOutput;
    signal?: AbortSignal;
    withGuide?: boolean;
    /**
     * The caller's runtime — burgee's `ctx.runtime` — and the one way `--quiet` reaches this port
     * (`caique-quiet-seam` R1). With `quiet`, the writers that decorate draw nothing; prompts
     * ignore it. Its `env` is the one `CI` is read from. It carries no streams, so `input` and
     * `output` still default to the process's. Never read from the environment: a caller passes it.
     */
    runtime?: PolicyRuntime;
}
```

### ConfirmOptions

```ts
interface ConfirmOptions extends CommonOptions {
    message: string;
    active?: string;
    inactive?: string;
    initialValue?: boolean;
    vertical?: boolean;
}
```

### DateOptions

```ts
interface DateOptions extends CommonOptions {
    message: string;
    format?: DateFormat;
    locale?: string;
    defaultValue?: Date;
    initialValue?: Date;
    minDate?: Date;
    maxDate?: Date;
    validate?: Validate<Date>;
}
```

### GroupMultiSelectOptions

```ts
interface GroupMultiSelectOptions<Value> extends CommonOptions {
    message: string;
    options: Record<string, Option<Value>[]>;
    initialValues?: Value[];
    maxItems?: number;
    required?: boolean;
    cursorAt?: Value;
    selectableGroups?: boolean;
    groupSpacing?: number;
    showInstructions?: boolean;
}
```

### LimitOptionsParams

What `limitOptions` takes. Named as the incumbent names it, because callers import it.

```ts
interface LimitOptionsParams<TOption> extends CommonOptions {
    /** The list to display. */
    options: TOption[];
    /** The index of the active option. */
    cursor: number;
    /** Renders one option, told whether it is the active one. */
    style: (option: TOption, active: boolean) => string;
    /** The most options to show, before the terminal's own height is taken into account. */
    maxItems?: number | undefined;
    /** Columns taken by something else on the line — a bar, an indent. */
    columnPadding?: number | undefined;
    /** Rows taken by something else on the screen — a message, a footer. */
    rowPadding?: number | undefined;
}
```

### LogMessageOptions

```ts
interface LogMessageOptions extends CommonOptions {
    symbol?: string;
    spacing?: number;
    secondarySymbol?: string;
}
```

### MultiLineOptions

```ts
interface MultiLineOptions extends TextOptions {
    /** Draw a `[ submit ]` button, reached with tab, instead of submitting on a second enter. */
    showSubmit?: boolean;
}
```

### MultiSelectOptions

```ts
interface MultiSelectOptions<Value> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValues?: Value[];
    maxItems?: number;
    required?: boolean;
    cursorAt?: Value;
    showInstructions?: boolean;
}
```

### NoteOptions

```ts
interface NoteOptions extends CommonOptions {
    /** Applied to every line of the message. */
    format?: (line: string) => string;
}
```

### PasswordOptions

```ts
interface PasswordOptions extends CommonOptions {
    message: string;
    mask?: string;
    validate?: Validate<string>;
    clearOnError?: boolean;
}
```

### PathOptions

```ts
interface PathOptions extends CommonOptions {
    message: string;
    root?: string;
    directory?: boolean;
    initialValue?: string;
    validate?: Validate<string>;
}
```

### PromptGroupOptions

```ts
interface PromptGroupOptions<T> {
    /** Called when a prompt in the group is cancelled, with the answers so far. */
    onCancel?: (opts: {
        results: Prettify<Partial<PromptGroupAwaitedReturn<T>>>;
    }) => void;
}
```

### SelectKeyOptions

```ts
interface SelectKeyOptions<Value extends string> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValue?: Value;
    caseSensitive?: boolean;
}
```

### SelectOptions

```ts
interface SelectOptions<Value> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValue?: Value;
    maxItems?: number;
    showInstructions?: boolean;
}
```

### SizedOutput

A stream a list can measure itself against. Anything with a size, including a test double.

```ts
interface SizedOutput {
    columns?: number;
    rows?: number;
    isTTY?: boolean;
}
```

### SpinnerOptions

```ts
interface SpinnerOptions extends CommonOptions {
    indicator?: 'dots' | 'timer';
    onCancel?: () => void;
    cancelMessage?: string;
    errorMessage?: string;
    frames?: string[];
    delay?: number;
    styleFrame?: (frame: string) => string;
    /**
     * A spinner style as data — flagstaff's `lookupSpinner(name)`, or a plugin's `spinners` entry —
     * in place of `frames` and `delay`: on a terminal its frames turn at its interval, and anywhere
     * else its `static` is printed where the first frame would be (U3). caique imports no registry:
     * the program that has both hands one to the other (D-20261027-prompt-spinner-composed).
     */
    style?: {
        readonly frames: readonly string[];
        readonly interval: number;
        readonly static: string;
    };
}
```

### SpinnerResult

```ts
interface SpinnerResult {
    start(msg?: string): void;
    stop(msg?: string): void;
    cancel(msg?: string): void;
    error(msg?: string): void;
    message(msg?: string): void;
    clear(): void;
    readonly isCancelled: boolean;
}
```

### Task

```ts
interface Task {
    title: string;
    task: (message: (string: string) => void) => string | Promise<string> | void | Promise<void>;
    enabled?: boolean;
}
```

### TextOptions

```ts
interface TextOptions extends CommonOptions {
    message: string;
    placeholder?: string;
    defaultValue?: string;
    initialValue?: string;
    validate?: Validate<string>;
}
```

## Types

### DateFormat

The date field order, as clack names it.

```ts
type DateFormat = 'YMD' | 'MDY' | 'DMY';
```

### Option

One choice in a list: a primitive value may go without a label, anything else may not.

```ts
type Option<Value> = Value extends Primitive ? {
    value: Value;
    label?: string;
    hint?: string;
    disabled?: boolean;
} : {
    value: Value;
    label: string;
    hint?: string;
    disabled?: boolean;
};
```

### PromptGroup

A named set of prompts, each told the answers before it.

```ts
type PromptGroup<T> = {
    [P in keyof T]: (opts: {
        results: Prettify<Partial<PromptGroupAwaitedReturn<Omit<T, P>>>>;
    }) => undefined | Promise<T[P] | undefined>;
};
```

### PromptGroupAwaitedReturn

What a group resolves to: every prompt's answer, with the cancel symbol taken out of the type.

```ts
type PromptGroupAwaitedReturn<T> = {
    [P in keyof T]: Exclude<Awaited<T[P]>, symbol>;
};
```

---

# caique/decide

> Every export of caique/decide, with its signature and doc comment: decide, plus 4 types.

Source: https://caique.interlace.tools/docs/api/decide

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { decide } from 'caique/decide';
```

## Functions

### decide

The rule, in order, and the order is the argument:

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

| Parameter | Type |
| :-- | :-- |
| `{ value, spec, option, flag, runtime, flags, required }` | `DecideInput` |

**Returns** `Decision`

## Interfaces

### DecideInput

```ts
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;
}
```

### Decision

```ts
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;
}
```

### Flags

What the run was asked for, as the engine knows it — never sniffed from the process.

```ts
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;
}
```

### Runtime

The slice of a runtime this needs. burgee's satisfies it; so does a literal in a test.

```ts
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;
}
```

---

# caique/editor

> Every export of caique/editor, with its signature and doc comment: editor, submissions, EDITOR_KEYS, plus 8 types.

Source: https://caique.interlace.tools/docs/api/editor

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { editor, submissions, EDITOR_KEYS } from 'caique/editor';
```

## Functions

### editor

Build an editor.

```ts
function editor(options?: EditorOptions): Editor;
```

| Parameter | Type |
| :-- | :-- |
| `options` (optional) | `EditorOptions` |

**Returns** `Editor`

### submissions

The editor's entries when there is no terminal to edit on: one per line of input, ending
when the input does. A pipe, a file and `/dev/null` all end — so this never waits for a key
that cannot come (controlroom R7).

```ts
function submissions(input: NodeJS.ReadableStream): AsyncGenerator<string, void, undefined>;
```

| Parameter | Type |
| :-- | :-- |
| `input` | `NodeJS.ReadableStream` |

**Returns** `AsyncGenerator<string, void, undefined>`

## Constants

### EDITOR_KEYS

The editor's commands, as data. A host passes its own `keymap` to change them.

```ts
const EDITOR_KEYS: {
    readonly enter: "submit";
    readonly 'meta+enter': "newline";
    readonly 'ctrl+j': "newline";
    readonly up: "previous";
    readonly down: "next";
    readonly tab: "complete";
    readonly escape: "dismiss";
    readonly 'ctrl+c': "cancel";
};
```

## Interfaces

### Editor

An editor: its first state, its reducer, and its drawing. All three are pure.

```ts
interface Editor {
    initial: EditorState;
    onKey: (state: EditorState, key: KeyPress) => Step;
    render: (state: EditorState) => Frame;
}
```

### EditorOptions

```ts
interface EditorOptions {
    /** The entry the editor opens with. */
    text?: string;
    /** Earlier entries, oldest first: what Up recalls. */
    history?: readonly string[];
    /**
     * Candidates for the word before the cursor (`/com`, `@fi`); an empty list shows no menu.
     * The program decides what a word means — the editor only asks.
     */
    complete?: (word: string) => readonly string[];
    /** Replaces `EDITOR_KEYS`. Any key it does not bind is typed, if it is text. */
    keymap?: Keymap<EditorAction>;
    /** Drawn before the first row; the rows under it are indented to match. */
    prompt?: string;
}
```

### EditorState

Everything the editor is. Plain data: no functions, nothing a host cannot copy or log.

```ts
interface EditorState {
    /** The entry being written; `\n` separates its rows. */
    readonly text: string;
    /** Where the cursor is in `text`, in UTF-16 units. */
    readonly cursor: number;
    /** Earlier entries, oldest first. */
    readonly history: readonly string[];
    /** Which history entry is shown; `history.length` is the entry being written. */
    readonly at: number;
    /** The entry being written, kept while the history is browsed. */
    readonly draft: string;
    /** A bracketed paste being collected, or `undefined` outside one. */
    readonly paste: string | undefined;
    readonly menu: Menu | undefined;
    /** The word whose menu Escape closed: it stays closed until the word changes. */
    readonly dismissed: string | undefined;
}
```

### Frame

Where the editor sits on screen once rendered: its rows, and the cursor among them.

```ts
interface Frame {
    lines: string[];
    /** Row and display column of the cursor within `lines`, before any wrapping by the host. */
    cursor: {
        row: number;
        column: number;
    };
}
```

### Menu

The completion menu: what the program offered for the word before the cursor.

```ts
interface Menu {
    word: string;
    items: readonly string[];
    selected: number;
}
```

### Step

One key's result: the next state, and an event when the key ended the entry.

```ts
interface Step {
    state: EditorState;
    event?: EditorEvent;
}
```

## Types

### EditorAction

What a key can ask the editor to do, beyond typing.

```ts
type EditorAction = 'submit' | 'newline' | 'previous' | 'next' | 'complete' | 'dismiss' | 'cancel';
```

### EditorEvent

What a key did that the host has to act on.

```ts
type EditorEvent = {
    type: 'submit';
    text: string;
} | {
    type: 'cancel';
};
```

---

# caique

> Every export of caique, with its signature and doc comment: processRuntime, ask, projection, resolvePrompts, localise, decide and 17 more, plus 27 types.

Source: https://caique.interlace.tools/docs/api

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

caique — prompts that are flags first. The first working slice is `decide()`: the pure
rule that decides whether a person can be asked at all, which is what keeps a CLI built
on this from hanging when an agent runs it. Widgets and the two façades follow; see
`.sdlc/intents/caique/`.

```ts
import { processRuntime, ask, projection, … } from 'caique';
```

## Constants

### processRuntime

What a real process looks like. Callers that have not got one pass their own.

```ts
const processRuntime: () => Runtime;
```

## Re-exported

Documented on the page of the entry point that declares them.

| Export | Kind | Documented in |
| :-- | :-- | :-- |
| `ask` | function | [`caique/ask`](/docs/api/ask#ask) |
| `askList` | function | [`caique/raw`](/docs/api/raw#asklist) |
| `bindings` | function | [`caique/keys`](/docs/api/keys#bindings) |
| `canonical` | function | [`caique/keys`](/docs/api/keys#canonical) |
| `canReadKeys` | function | [`caique/keys`](/docs/api/keys#canreadkeys) |
| `canRender` | function | [`caique/raw`](/docs/api/raw#canrender) |
| `createIo` | function | [`caique/terminal`](/docs/api/terminal#createio) |
| `decide` | function | [`caique/decide`](/docs/api/decide#decide) |
| `decode` | function | [`caique/keys`](/docs/api/keys#decode) |
| `flagOf` | function | [`caique/spec`](/docs/api/spec#flagof) |
| `keyOf` | function | [`caique/raw`](/docs/api/raw#keyof) |
| `match` | function | [`caique/keys`](/docs/api/keys#match) |
| `problemWith` | function | [`caique/spec`](/docs/api/spec#problemwith) |
| `projection` | function | [`caique/ask`](/docs/api/ask#projection) |
| `readKeys` | function | [`caique/keys`](/docs/api/keys#readkeys) |
| `renderList` | function | [`caique/raw`](/docs/api/raw#renderlist) |
| `resolvePrompts` | function | [`caique/binding`](/docs/api/binding#resolveprompts) |
| `specOf` | function | [`caique/keys`](/docs/api/keys#specof) |
| `KeysError` | class | [`caique/keys`](/docs/api/keys#keyserror) |
| `BUILT_IN_KINDS` | const | [`caique/spec`](/docs/api/spec#built_in_kinds) |
| `localise` | const | [`caique/binding`](/docs/api/binding#localise) |
| `streamsOf` | const | [`caique/terminal`](/docs/api/terminal#streamsof) |
| `Binding` | interface | [`caique/keys`](/docs/api/keys#binding) |
| `BoundPrompt` | interface | [`caique/spec`](/docs/api/spec#boundprompt) |
| `Choice` | interface | [`caique/spec`](/docs/api/spec#choice) |
| `DecideInput` | interface | [`caique/decide`](/docs/api/decide#decideinput) |
| `Decision` | interface | [`caique/decide`](/docs/api/decide#decision) |
| `Flags` | interface | [`caique/decide`](/docs/api/decide#flags) |
| `Io` | interface | [`caique/ask`](/docs/api/ask#io) |
| `KeyPress` | interface | [`caique/keys`](/docs/api/keys#keypress) |
| `KeyStream` | interface | [`caique/raw`](/docs/api/raw#keystream) |
| `PromptableOption` | interface | [`caique/binding`](/docs/api/binding#promptableoption) |
| `PromptSpec` | interface | [`caique/spec`](/docs/api/spec#promptspec) |
| `RawIo` | interface | [`caique/raw`](/docs/api/raw#rawio) |
| `Reader` | interface | [`caique/ask`](/docs/api/ask#reader) |
| `ReadOptions` | interface | [`caique/ask`](/docs/api/ask#readoptions) |
| `Resolved` | interface | [`caique/binding`](/docs/api/binding#resolved) |
| `ResolveFailure` | interface | [`caique/binding`](/docs/api/binding#resolvefailure) |
| `ResolveInput` | interface | [`caique/binding`](/docs/api/binding#resolveinput) |
| `Runtime` | interface | [`caique/decide`](/docs/api/decide#runtime) |
| `Streams` | interface | [`caique/terminal`](/docs/api/terminal#streams) |
| `Writer` | interface | [`caique/ask`](/docs/api/ask#writer) |
| `Answer` | type | [`caique/ask`](/docs/api/ask#answer) |
| `Asked` | type | [`caique/ask`](/docs/api/ask#asked) |
| `Key` | type | [`caique/raw`](/docs/api/raw#key) |
| `KeyInput` | type | [`caique/keys`](/docs/api/keys#keyinput) |
| `Keymap` | type | [`caique/keys`](/docs/api/keys#keymap) |
| `KeysErrorCode` | type | [`caique/keys`](/docs/api/keys#keyserrorcode) |
| `PromptKind` | type | [`caique/spec`](/docs/api/spec#promptkind) |

---

# caique/inquirer

> Every export of caique/inquirer, with its signature and doc comment: usePrefix, useKeypress, createPrompt, Separator, AbortPromptError, CancelPromptError and 19 more, plus 10 types.

Source: https://caique.interlace.tools/docs/api/inquirer

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { usePrefix, useKeypress, createPrompt, … } from 'caique/inquirer';
```

## Functions

### createPrompt

Turn a render function into a prompt.

```ts
function createPrompt<Value, Config>(view: ViewFunction<Value, Config>): Prompt<Value, Config>;
```

| Parameter | Type |
| :-- | :-- |
| `view` | `ViewFunction<Value, Config>` |

**Returns** `Prompt<Value, Config>`

### getDefaultKeybindings

`INQUIRER_KEYBINDINGS` split on whitespace or commas, lowercased, unknown names dropped
and duplicates collapsed — so `'vim emacs unknown vim'` is `['vim', 'emacs']`.

```ts
function getDefaultKeybindings(): Keybinding[];
```

**Returns** `Keybinding[]`

### getDefaultTheme

The defaults with the environment's keybindings folded in, read fresh on every call.

```ts
function getDefaultTheme(): Theme;
```

**Returns** `Theme`

### makeTheme

Merge any number of partial themes over the defaults, last one winning per leaf.

```ts
function makeTheme<Extension = object>(...themes: readonly (PartialTheme<Extension> | PartialDeep<Theme & Extension> | undefined)[]): Theme & Extension;
```

| Parameter | Type |
| :-- | :-- |
| `themes` | `readonly (PartialTheme<Extension> \| PartialDeep<Theme & Extension> \| undefined)[]` |

**Returns** `Theme & Extension`

### useEffect

A side effect, queued when its dependency array changes and cleaned up before it re-runs.

```ts
function useEffect(cb: (rl: PromptReadline) => Cleanup, depArray: readonly unknown[]): void;
```

| Parameter | Type |
| :-- | :-- |
| `cb` | `(rl: PromptReadline) => Cleanup` |
| `depArray` | `readonly unknown[]` |

**Returns** `void`

### useKeypress

Register a keypress handler for as long as the prompt is rendering.

```ts
function useKeypress(userHandler: (event: KeypressEvent, rl: PromptReadline) => void | Promise<void>): void;
```

| Parameter | Type |
| :-- | :-- |
| `userHandler` | `(event: KeypressEvent, rl: PromptReadline) => void \| Promise<void>` |

**Returns** `void`

### useMemo

A memoised value.

```ts
function useMemo<Value>(fn: () => Value, dependencies: readonly unknown[]): Value;
```

| Parameter | Type |
| :-- | :-- |
| `fn` | `() => Value` |
| `dependencies` | `readonly unknown[]` |

**Returns** `Value`

### usePrefix

The prefix a prompt draws, and the spinner that replaces it while the prompt is loading.

```ts
function usePrefix({ status, theme }: {
    status?: Status;
    theme?: PartialTheme;
}): string;
```

| Parameter | Type |
| :-- | :-- |
| `{ status, theme }` | `{ status?: Status; theme?: PartialTheme; }` |

**Returns** `string`

### useRef

A box that survives re-renders. One `useState` slot holding an object that never changes.
The no-argument form, for a box a later render fills — `useRef<Timeout | undefined>()`.

```ts
function useRef<Value>(value: Value): {
    current: Value;
};

function useRef<Value>(value?: Value): {
    current: Value | undefined;
};
```

| Parameter | Type |
| :-- | :-- |
| `value` | `Value` |

**Returns** `{ current: Value; }`

### useState

State that survives a re-render, addressed by call order.
The no-argument form, for state a later keypress fills.

```ts
function useState<Value>(defaultValue: NotFunction<Value> | (() => Value)): [Value, SetState<Value>];

function useState<Value>(defaultValue?: NotFunction<Value> | (() => Value)): [Value | undefined, SetState<Value | undefined>];
```

| Parameter | Type |
| :-- | :-- |
| `defaultValue` | `NotFunction<Value> \| (() => Value)` |

**Returns** `[Value, SetState<Value>]`

## Classes

### AbortPromptError

Thrown when the `AbortSignal` handed to a prompt aborts.

```ts
class AbortPromptError extends Error {
    name: string;
    message: string;
    constructor(options?: {
        cause?: unknown;
    });
}
```

### CancelPromptError

Thrown when a caller calls `.cancel()` on the returned promise.

```ts
class CancelPromptError extends Error {
    name: string;
    message: string;
}
```

### ExitPromptError

Thrown when the process is going away under the prompt — Ctrl-C, or a signalled exit.

```ts
class ExitPromptError extends Error {
    name: string;
}
```

### HookError

Thrown when a hook is called outside a prompt render, where there is no store to read.

```ts
class HookError extends Error {
    name: string;
}
```

### Separator

A non-choice in a list of choices.

```ts
class Separator {
    readonly separator: string;
    readonly type = "separator";
    constructor(separator?: string);
    /** Whether `choice` is a separator — by shape, never by class. */
    static isSeparator(choice: unknown): choice is Separator;
}
```

### ValidationError

Thrown when a hook is called correctly but handed something it cannot use.

```ts
class ValidationError extends Error {
    name: string;
}
```

## Constants

### defaultTheme

The incumbent's defaults, byte for byte where a byte is observable.

```ts
const defaultTheme: Theme;
```

### isBackspaceKey

Backspace.

```ts
const isBackspaceKey: (key: KeypressEvent) => boolean;
```

### isDownKey

The down arrow always; `j` under vim; `Ctrl-N` under emacs.

```ts
const isDownKey: (key: KeypressEvent, keybindings?: readonly Keybinding[]) => boolean;
```

### isEnterKey

Enter, under either name readline gives it.

```ts
const isEnterKey: (key: KeypressEvent) => boolean;
```

### isNumberKey

A digit. `name` is a single character for these, so a substring test is the whole test.

```ts
const isNumberKey: (key: KeypressEvent) => boolean;
```

### isShiftKey

Whether shift was held. Returns the flag itself, so an absent flag reads as `false`.

```ts
const isShiftKey: (key: KeypressEvent) => boolean;
```

### isSpaceKey

The space bar.

```ts
const isSpaceKey: (key: KeypressEvent) => boolean;
```

### isTabKey

Tab.

```ts
const isTabKey: (key: KeypressEvent) => boolean;
```

### isUpKey

The up arrow always; `k` under vim; `Ctrl-P` under emacs. Nothing else, ever.

```ts
const isUpKey: (key: KeypressEvent, keybindings?: readonly Keybinding[]) => boolean;
```

## Interfaces

### Context

The streams and lifetime a caller may hand a prompt.

```ts
interface Context {
    input?: NodeJS.ReadableStream;
    output?: NodeJS.WritableStream;
    clearPromptOnDone?: boolean;
    signal?: AbortSignal;
}
```

### KeypressEvent

What `node:readline` hands a keypress listener. Widened to what the predicates read.

```ts
interface KeypressEvent {
    name: string;
    ctrl?: boolean;
    shift?: boolean;
    meta?: boolean;
    sequence?: string;
}
```

### Theme

The whole theme, as a prompt sees it after `makeTheme` has merged the defaults in.

```ts
interface Theme {
    prefix: ThemePrefix;
    spinner: ThemeSpinner;
    keybindings: Keybinding[];
    style: ThemeStyle;
}
```

## Types

### CancelablePromise

The promise a prompt returns: cancellable, so a caller can take the question back.

```ts
type CancelablePromise<Value> = Promise<Value> & {
    cancel: () => void;
};
```

### Keybinding

The two named keybinding sets the incumbent understands. Anything else is ignored.

```ts
type Keybinding = 'emacs' | 'vim';
```

### PartialTheme

What a caller may hand `makeTheme`: any subset, nested.

```ts
type PartialTheme<Extension = object> = Partial<Omit<Theme, 'style' | 'spinner'>> & {
    spinner?: Partial<ThemeSpinner>;
    style?: Partial<ThemeStyle>;
} & Partial<Extension>;
```

### Prompt

A prompt, ready to be called with its config.

```ts
type Prompt<Value, Config> = (config: Config, context?: Context) => CancelablePromise<Value>;
```

### SetState

The setter `useState` returns: a new value, or a reducer over the current one.

```ts
type SetState<Value> = (newValue: NotFunction<Value> | ((current: Value) => Value)) => void;
```

### Status

The lifecycle a prompt reports through `theme.prefix`. Open, so a caller may add states.

```ts
type Status = 'loading' | 'idle' | 'done' | (string & {});
```

### ViewFunction

What a render function returns: one string, or a body and a line below the cursor.

```ts
type ViewFunction<Value, Config> = (config: Config, done: (value: Value) => void) => string | [string, string | undefined];
```

---

# caique/inquirer/prompts

> Every export of caique/inquirer/prompts, with its signature and doc comment: Separator, checkbox, editor, confirm, input, number and 5 more, plus 25 types.

Source: https://caique.interlace.tools/docs/api/inquirer/prompts

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`caique/inquirer/prompts` — `@inquirer/prompts`' prompts, over `caique/inquirer`'s loop.

```ts
import { Separator, checkbox, editor, … } from 'caique/inquirer/prompts';
```

## Constants

### checkbox

Ask for any of `choices`.

```ts
const checkbox: <Value>(config: CheckboxConfig<Value>, context?: import("./inquirer.js").Context) => import("./inquirer.js").CancelablePromise<Value[]>;
```

### confirm

```ts
const confirm: import("./inquirer.js").Prompt<boolean, ConfirmConfig>;
```

### editor

```ts
const editor: import("./inquirer.js").Prompt<string, EditorConfig>;
```

### expand

```ts
const expand: <Value>(config: ExpandConfig<Value>, context?: import("./inquirer.js").Context) => import("./inquirer.js").CancelablePromise<Value>;
```

### input

```ts
const input: import("./inquirer.js").Prompt<string, InputConfig>;
```

### number

```ts
const number: <Required extends boolean>(config: NumberConfig<Required>, context?: import("./inquirer.js").Context) => import("./inquirer.js").CancelablePromise<Required extends true ? number : number | undefined>;
```

### password

```ts
const password: import("./inquirer.js").Prompt<string, PasswordConfig>;
```

### rawlist

```ts
const rawlist: <Value>(config: RawlistConfig<Value>, context?: import("./inquirer.js").Context) => import("./inquirer.js").CancelablePromise<Value>;
```

### search

```ts
const search: <Value>(config: SearchConfig<Value>, context?: import("./inquirer.js").Context) => import("./inquirer.js").CancelablePromise<Value>;
```

### select

Ask for one of `choices`.

```ts
const select: <Value>(config: SelectConfig<Value>, context?: import("./inquirer.js").Context) => import("./inquirer.js").CancelablePromise<Value>;
```

## Interfaces

### CheckboxConfig

`checkbox`'s configuration, as `@inquirer/checkbox` declares it.

```ts
interface CheckboxConfig<Value> {
    message: string;
    prefix?: string;
    pageSize?: number;
    choices: readonly (Value | Choice<Value> | Separator)[];
    loop?: boolean;
    required?: boolean;
    validate?: (choices: readonly NormalizedChoice<Value>[]) => boolean | string | Promise<string | boolean>;
    theme?: PartialTheme<CheckboxTheme>;
    shortcuts?: {
        all?: string | null;
        invert?: string | null;
    };
}
```

### CheckboxTheme

What `checkbox` adds to the core theme.

```ts
interface CheckboxTheme {
    icon: {
        checked: string;
        unchecked: string;
        cursor: string;
        disabledChecked: string;
        disabledUnchecked: string;
    };
    style: {
        disabled: (text: string) => string;
        renderSelectedChoices: <T>(selectedChoices: readonly NormalizedChoice<T>[], allChoices: readonly Item<T>[]) => string;
        description: (text: string) => string;
        keysHelpTip: (keys: [key: string, action: string][]) => string | undefined;
    };
    i18n: {
        disabledError: string;
    };
}
```

### Choice

A choice as a caller may write it.

```ts
interface Choice<Value> {
    value: Value;
    name?: string;
    checkedName?: string;
    description?: string;
    short?: string;
    disabled?: boolean | string;
    checked?: boolean;
    type?: never;
}
```

### ConfirmConfig

`confirm`'s config, as the incumbent declares it.

```ts
interface ConfirmConfig {
    message: string;
    default?: boolean | undefined;
    transformer?: (value: boolean) => string;
    theme?: PartialDeep<Theme & ConfirmTheme>;
}
```

### ConfirmTheme

What `confirm` adds to the shared theme.

```ts
interface ConfirmTheme {
    /** The words that answer yes and no, matched by prefix; `y`, `n`, `yes` and `no` always work too. */
    keywords: {
        yes: string;
        no: string;
        error: (keywords: {
            yes: string;
            no: string;
        }) => string;
    };
    /** How the default's letter is drawn in the `Y/n` hint. */
    style: {
        confirmDefault: (text: string) => string;
    };
}
```

### EditorConfig

`editor`'s config, as the incumbent declares it.

```ts
interface EditorConfig {
    message: string;
    default?: string | undefined;
    postfix?: string;
    waitForUserInput?: boolean;
    validate?: (value: string) => boolean | string | Promise<string | boolean>;
    file?: EditorFileOptions;
    theme?: PartialDeep<Theme & EditorTheme>;
}
```

### EditorFileOptions

Where the temporary file goes and what it is called, as `@inquirer/external-editor` takes it.

```ts
interface EditorFileOptions {
    prefix?: string;
    postfix?: string;
    mode?: number;
    dir?: string;
}
```

### EditorTheme

What `editor` adds to the shared theme.

```ts
interface EditorTheme {
    validationFailureMode: 'keep' | 'clear';
    style: {
        loadingMessage: () => string;
        waitingMessage: (enterKey: string) => string;
    };
}
```

### ExpandConfig

`expand`'s config, as the incumbent declares it.

```ts
interface ExpandConfig<Value> {
    message: string;
    choices: readonly (Separator | {
        key: ExpandKey;
        name: Value & string;
        value?: never;
    } | ExpandChoice<Value>)[];
    default?: ExpandKey | 'h';
    expanded?: boolean;
    theme?: PartialDeep<Theme>;
}
```

### InputConfig

`input`'s config, as the incumbent declares it.

```ts
interface InputConfig {
    message: string;
    default?: string | undefined;
    prefill?: 'tab' | 'editable';
    required?: boolean;
    transformer?: (value: string, flags: {
        isFinal: boolean;
    }) => string;
    validate?: (value: string) => Verdict;
    theme?: PartialDeep<Theme & InputTheme>;
    pattern?: RegExp;
    patternError?: string;
}
```

### InputTheme

What `input` adds to the shared theme.

```ts
interface InputTheme {
    validationFailureMode: 'keep' | 'clear';
}
```

### NormalizedChoice

A choice once the prompt has filled in every field.

```ts
interface NormalizedChoice<Value> {
    value: Value;
    name: string;
    checkedName: string;
    description?: string;
    short: string;
    disabled: boolean | string;
    checked: boolean;
}
```

### NumberConfig

`number`'s config, as the incumbent declares it.

```ts
interface NumberConfig<Required extends boolean = boolean> {
    message: string;
    default?: number | undefined;
    min?: number;
    max?: number;
    step?: number | 'any';
    required?: Required;
    validate?: (value: Required extends true ? number : number | undefined) => Verdict;
    theme?: PartialDeep<Theme>;
}
```

### PasswordConfig

`password`'s config, as the incumbent declares it.

```ts
interface PasswordConfig {
    message: string;
    mask?: boolean | string;
    toggleMask?: boolean;
    validate?: (value: string) => Verdict;
    theme?: PartialDeep<Theme & PasswordTheme>;
}
```

### PasswordTheme

What `password` adds to the shared theme.

```ts
interface PasswordTheme {
    style: {
        maskedText: string;
        keysHelpTip: (keys: [key: string, action: string][]) => string | undefined;
    };
}
```

### RawlistChoice

A `rawlist` choice as a caller writes it.

```ts
interface RawlistChoice<Value> {
    value: Value;
    name?: string;
    short?: string;
    key?: string;
    description?: string;
}
```

### RawlistConfig

`rawlist`'s config, as the incumbent declares it.

```ts
interface RawlistConfig<Value> {
    message: string;
    choices: readonly (Value | RawlistChoice<Value> | Separator)[];
    loop?: boolean;
    theme?: PartialDeep<Theme & RawlistTheme>;
    default?: NoInfer<Value>;
}
```

### RawlistTheme

What `rawlist` adds to the shared theme.

```ts
interface RawlistTheme {
    style: {
        description: (text: string) => string;
    };
}
```

### SearchConfig

`search`'s config, as the incumbent declares it.

```ts
interface SearchConfig<Value> {
    message: string;
    source: (term: string | undefined, opt: {
        signal: AbortSignal;
    }) => readonly (Value | SearchChoice<Value> | Separator)[] | Promise<readonly (Value | SearchChoice<Value> | Separator)[]>;
    validate?: (value: Value) => boolean | string | Promise<string | boolean>;
    pageSize?: number;
    default?: NoInfer<Value>;
    initialValue?: string;
    theme?: PartialDeep<Theme & SearchTheme>;
}
```

### SearchTheme

What `search` adds to the shared theme.

```ts
interface SearchTheme {
    icon: {
        cursor: string;
    };
    style: {
        disabled: (text: string) => string;
        searchTerm: (text: string) => string;
        description: (text: string) => string;
        keysHelpTip: (keys: [key: string, action: string][]) => string | undefined;
    };
}
```

### SelectConfig

`select`'s configuration, as `@inquirer/select` declares it.

```ts
interface SelectConfig<Value> {
    message: string;
    choices: readonly (Value | Omit<Choice<Value>, 'checked' | 'checkedName'> | Separator)[];
    pageSize?: number;
    loop?: boolean;
    default?: NoInfer<Value>;
    theme?: PartialTheme<SelectTheme>;
}
```

### SelectTheme

What `select` adds to the core theme.

```ts
interface SelectTheme {
    icon: {
        cursor: string;
    };
    style: {
        disabled: (text: string) => string;
        description: (text: string) => string;
        keysHelpTip: (keys: [key: string, action: string][]) => string | undefined;
    };
    i18n: {
        disabledError: string;
    };
    indexMode: 'hidden' | 'number';
}
```

## Types

### ExpandChoice

An `expand` choice: a key, and a value, a name, or both.

```ts
type ExpandChoice<Value> = {
    key: ExpandKey;
    value: Value;
} | {
    key: ExpandKey;
    name: string;
    value: Value;
};
```

### ExpandKey

The keys `expand` accepts: a letter or a digit, `h` aside, because `h` is help.

```ts
type ExpandKey = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
```

### SearchChoice

A `search` choice as a caller writes it: `select`'s, without `checkbox`'s fields.

```ts
type SearchChoice<Value> = Omit<Choice<Value>, 'checked' | 'checkedName'>;
```

## Re-exported

Documented on the page of the entry point that declares them.

| Export | Kind | Documented in |
| :-- | :-- | :-- |
| `Separator` | class | [`caique/inquirer`](/docs/api/inquirer#separator) |

---

# caique/keys

> Every export of caique/keys, with its signature and doc comment: decode, canonical, specOf, bindings, match, canReadKeys and 2 more, plus 5 types.

Source: https://caique.interlace.tools/docs/api/keys

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { decode, canonical, specOf, … } from 'caique/keys';
```

## Functions

### bindings

Every binding in a keymap, in the order it was written, with each key in canonical form.

```ts
function bindings<Action extends string>(keymap: Keymap<Action>): Binding<Action>[];
```

| Parameter | Type |
| :-- | :-- |
| `keymap` | `Keymap<Action>` |

**Returns** `Binding<Action>[]`

### canonical

The one spelling of a key spec, or a `KeysError` naming what is wrong with it.

```ts
function canonical(spec: string): string;
```

| Parameter | Type |
| :-- | :-- |
| `spec` | `string` |

**Returns** `string`

### canReadKeys

Whether keys can be read from this input at all: a terminal that can be put into raw mode.
A pipe, a file and `/dev/null` cannot, and no amount of waiting changes that.

```ts
function canReadKeys(input: InputStream): boolean;
```

| Parameter | Type |
| :-- | :-- |
| `input` | `InputStream` |

**Returns** `boolean`

### decode

Every key in one chunk of input, in order — what one `data` event from a raw terminal means.

```ts
function decode(chunk: string): KeyPress[];
```

| Parameter | Type |
| :-- | :-- |
| `chunk` | `string` |

**Returns** `KeyPress[]`

### match

The action a key press is bound to in this keymap, or `undefined`.

```ts
function match<Action extends string>(keymap: Keymap<Action>, key: KeyPress): Action | undefined;
```

| Parameter | Type |
| :-- | :-- |
| `keymap` | `Keymap<Action>` |
| `key` | `KeyPress` |

**Returns** `Action \| undefined`

### readKeys

Read key presses from a terminal until the returned function is called.

```ts
function readKeys(input: KeyInput, onKey: (key: KeyPress) => void, onExit?: Registrar): () => void;
```

| Parameter | Type |
| :-- | :-- |
| `input` | `KeyInput` |
| `onKey` | `(key: KeyPress) => void` |
| `onExit` (optional) | `Registrar` |

**Returns** `() => void`

### specOf

A key press in a keymap's spelling, or `undefined` for a sequence nothing can bind.

```ts
function specOf(key: KeyPress): string | undefined;
```

| Parameter | Type |
| :-- | :-- |
| `key` | `KeyPress` |

**Returns** `string \| undefined`

## Classes

### KeysError

A refusal in the family's shape: what is wrong, and what to do about it.

```ts
class KeysError extends Error {
    readonly code: KeysErrorCode;
    readonly fix: string;
    constructor(code: KeysErrorCode, message: string, fix: string);
}
```

## Interfaces

### Binding

One entry of a keymap, with its key in the one spelling `match()` compares.

```ts
interface Binding<Action extends string = string> {
    key: string;
    action: Action;
}
```

### KeyPress

One key press, as every consumer of this module sees it.

```ts
interface KeyPress {
    /**
     * `up`, `down`, `left`, `right`, `tab`, `enter`, `escape`, `backspace`, `delete`, `home`,
     * `end`, `pageup`, `pagedown`, `space`, a lowercase letter, any other printable character
     * as itself (`/`, `?`, `é`), or one of node's own names (`f1`, `insert`, `paste-start`).
     * Empty for a sequence nothing names, which no keymap can bind.
     */
    name: string;
    ctrl: boolean;
    meta: boolean;
    shift: boolean;
    /** The characters the terminal sent for it. */
    sequence: string;
}
```

## Types

### KeyInput

A readable terminal stream: `process.stdin`, or a test's double of one.

```ts
type KeyInput = NodeJS.ReadableStream & InputStream;
```

### Keymap

Key spec → action name. Plain data: it can be written in JSON and diffed.

```ts
type Keymap<Action extends string = string> = Readonly<Record<string, Action>>;
```

### KeysErrorCode

```ts
type KeysErrorCode = 'E_KEY_SPEC' | 'E_NOT_A_TERMINAL';
```

---

# caique/locale

> Every export of caique/locale, with its signature and doc comment: checkLocales, render, sayFor, plus 2 types.

Source: https://caique.interlace.tools/docs/api/locale

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { checkLocales, render, sayFor } from 'caique/locale';
```

## Functions

### checkLocales

R6 — refuse a pack whose caique messages cannot be rendered: an id caique does not have, a
placeholder the English lacks, a plural message missing a form its locale selects. Ids that
do not begin `caique.` are another package's and are left to it. A tag is burgee's to check,
which reads it the same way; here it only has to name an object.

```ts
function checkLocales(plugin: {
    name: string;
    locales?: unknown;
}): void;
```

| Parameter | Type |
| :-- | :-- |
| `plugin` | `{ name: string; locales?: unknown; }` |

**Returns** `void`

### render

A checked message in `locale`, with the values put back: the plural form by `count`, then each `{name}`.

```ts
function render(message: Message, values: Readonly<Record<string, string>>, locale: string): string;
```

| Parameter | Type |
| :-- | :-- |
| `message` | `Message` |
| `values` | `Readonly<Record<string, string>>` |
| `locale` | `string` |

**Returns** `string`

### sayFor

```ts
function sayFor(locale: string | undefined): (english: string) => string;
```

| Parameter | Type |
| :-- | :-- |
| `locale` | `string \| undefined` |

**Returns** `(english: string) => string`

## Types

### Locales

A pack's `locales`: language tag → message id → translation. Ids outside `caique.` are another package's.

```ts
type Locales = Readonly<Record<string, Readonly<Record<string, Message>>>>;
```

### Message

A translation: one string, or — for a message that carries `{count}` — one per plural form.

```ts
type Message = string | Readonly<Partial<Record<Intl.LDMLPluralRule, string>>>;
```

---

# caique/plugin

> Every export of caique/plugin, with its signature and doc comment: validate, register, reset, registered, widgets, widgetFor and 4 more, plus 5 types.

Source: https://caique.interlace.tools/docs/api/plugin

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { validate, register, reset, … } from 'caique/plugin';
```

## Functions

### kinds

Every kind that can be drawn right now: the six, plus whatever is registered.

```ts
function kinds(): string[];
```

**Returns** `string[]`

### projectionOf

The static projection for *any* kind — the one surface a caller needs.

```ts
function projectionOf(spec: PromptSpec): string;
```

| Parameter | Type |
| :-- | :-- |
| `spec` | `PromptSpec` |

**Returns** `string`

### register

Register a plugin. Later wins, like ESLint flat config: the array is ordered, a caller
reads it top to bottom, and the last word on a kind is the one nearest the program.

```ts
function register(plugin: unknown): void;
```

| Parameter | Type |
| :-- | :-- |
| `plugin` | `unknown` |

**Returns** `void`

### registered

The plugins registered, in registration order.

```ts
function registered(): readonly Plugin[];
```

**Returns** `readonly Plugin[]`

### reset

Forget every registered plugin. For tests, and for a program that re-registers at runtime.

```ts
function reset(): void;
```

**Returns** `void`

### validate

Refuse a plugin that cannot contribute a widget, at the door.

```ts
function validate(plugin: unknown): asserts plugin is Plugin;
```

| Parameter | Type |
| :-- | :-- |
| `plugin` | `unknown` |

**Returns** `asserts plugin is Plugin`

### widgetFor

The widget that draws `kind`, or nothing when no plugin registered one.

```ts
function widgetFor(kind: string): Widget | undefined;
```

| Parameter | Type |
| :-- | :-- |
| `kind` | `string` |

**Returns** `Widget \| undefined`

### widgets

Every kind a plugin contributed, with who won it and who it shadowed.

```ts
function widgets(): Contribution[];
```

**Returns** `Contribution[]`

## Classes

### PluginError

A refused plugin says what is wrong and what to do about it — the family's one vocabulary.

```ts
class PluginError extends Error {
    readonly code: PluginErrorCode;
    readonly fix: string;
    constructor(code: PluginErrorCode, message: string, fix: string);
}
```

## Constants

### CONTRACT

The plugin contract version. One number for the family — the same `1` flagstaff and
roundel declare, written out rather than imported for the reason in the file comment.

```ts
const CONTRACT = 1;
```

## Interfaces

### Contribution

Which plugin last contributed each kind — the shadowing a `plugin check` prints.

```ts
interface Contribution {
    kind: string;
    from: string;
    /** Plugins that contributed this kind earlier and were overridden, in order. */
    shadowed: string[];
}
```

### Plugin

The keys caique reads. Declared structurally: any object with these fields is a plugin
here, whatever else it carries.

```ts
interface Plugin {
    name: string;
    contract?: number;
    widgets?: Record<string, Widget>;
    /**
     * A locale pack (`localised-human-surfaces` R6): language tag → message id → translation. caique
     * reads the ids that begin `caique.` and leaves the rest to the package that owns them, so the
     * one object burgee registers for its own messages carries these too. Checked where it is
     * first used — the run whose locale it speaks — and by `caique check`, not here: this door is
     * on every entry's startup path, and the check is the catalog's weight.
     */
    locales?: Locales;
}
```

### Widget

How a plugin draws one kind of prompt.

```ts
interface Widget {
    static: (spec: PromptSpec) => string;
    frame?: (t: number, spec: PromptSpec) => string;
    sample?: WidgetSample;
}
```

### WidgetSample

Two named states of plain data, which a grader renders a widget with (R7).

```ts
interface WidgetSample {
    running: unknown;
    done: unknown;
}
```

## Types

### PluginErrorCode

```ts
type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT' | 'E_NO_STATIC_PROJECTION' | 'E_UNKNOWN_KIND' | 'E_NO_CONTRIBUTION';
```

---

# caique/prompt-for

> Every export of caique/prompt-for, with its signature and doc comment: promptFor, PromptRefusal, plus 5 types.

Source: https://caique.interlace.tools/docs/api/prompt-for

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { promptFor, PromptRefusal } from 'caique/prompt-for';
```

## Functions

### promptFor

Wrap a command so that its declared prompts are resolved before its handler runs (R1, R2, R6).

```ts
function promptFor<T extends PromptableCommand>(command: T & CarriesContext<T>, name?: string, spec?: PromptSpec, opts?: PromptForOptions): T;
```

| Parameter | Type |
| :-- | :-- |
| `command` | `T & CarriesContext<T>` |
| `name` (optional) | `string` |
| `spec` (optional) | `PromptSpec` |
| `opts` (optional) | `PromptForOptions` |

**Returns** `T`

## Classes

### PromptRefusal

A refusal a handler throws: burgee reads `code` by name, prints `message` and `fix` (P2, P3).

```ts
class PromptRefusal extends Error {
    readonly code: ResolveFailure['code'];
    readonly fix: string | undefined;
    /** The option or positional it stopped at, by its declared name. */
    readonly option: string;
    constructor(failure: ResolveFailure);
}
```

## Interfaces

### PromptableArgument

A positional as `promptFor` reads it. burgee's `ArgumentSpec` satisfies it.

```ts
interface PromptableArgument extends PromptableSpec {
    name: string;
}
```

### PromptableCommand

A command as `promptFor` reads it. burgee's `Command` satisfies it. `run` takes the host's own
context, whatever it is called; {@link promptFor} checks that it carries a {@link PromptContext}.

```ts
interface PromptableCommand {
    options?: Record<string, PromptableSpec>;
    arguments?: readonly PromptableArgument[];
    run?: (ctx: never) => unknown;
}
```

### PromptableSpec

An option as `promptFor` reads it. burgee's `OptionSpec` satisfies it; the rest of a host's spec is carried as it is.

```ts
interface PromptableSpec {
    required?: boolean;
    prompt?: PromptSpec;
    [field: string]: unknown;
}
```

### PromptContext

What `promptFor` reads of a host's run context. burgee's `RunContext` satisfies it.

```ts
interface PromptContext {
    options: Record<string, unknown>;
    /** The declared positionals by name. */
    args: Record<string, unknown>;
    /** The positionals as typed; an answered one is written in at its declared place. */
    positionals: string[];
    env: Record<string, string | undefined>;
    /** Whether a person may be asked: a terminal on stdin, no `CI`, no agent (N12) — the host's answer. */
    interactive: boolean;
    /** The run was asked for `--json`, which an `--mcp` tool call always is (R6): nobody is there to type. */
    json?: boolean;
    /** The host's exit path (E5): what closes the terminal if the run is ended mid-question. */
    onExit?: (handler: () => void, label?: string) => () => void;
}
```

### PromptForOptions

```ts
interface PromptForOptions {
    /** Where to ask; the process's stdin and stderr when omitted, opened only if a question is asked. */
    io?: Io;
}
```

---

# caique/raw

> Every export of caique/raw, with its signature and doc comment: keyOf, canRender, renderList, askList, plus 3 types.

Source: https://caique.interlace.tools/docs/api/raw

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { keyOf, canRender, renderList, … } from 'caique/raw';
```

## Functions

### askList

Drive a list prompt with the arrow keys, repainting in place.

```ts
function askList(spec: PromptSpec, io: RawIo, multi?: boolean): Promise<Asked>;
```

| Parameter | Type |
| :-- | :-- |
| `spec` | `PromptSpec` |
| `io` | `RawIo` |
| `multi` (optional) | `boolean` |

**Returns** `Promise<Asked>`

### canRender

Whether this runtime can drive the raw renderer at all.

```ts
function canRender(keys: KeyStream): boolean;
```

| Parameter | Type |
| :-- | :-- |
| `keys` | `KeyStream` |

**Returns** `boolean`

### keyOf

What a keypress means. Only the six that drive a list — everything else is `other`, and
a widget that does not know what to do with a key does nothing, which is what a person
expects from a key they pressed by accident.

```ts
function keyOf(data: string): Key;
```

| Parameter | Type |
| :-- | :-- |
| `data` | `string` |

**Returns** `Key`

### renderList

One frame of the list. Exported so a test asserts the drawing rather than a screenshot.

```ts
function renderList(spec: PromptSpec, choices: Choice[], state: ListState, multi: boolean): string;
```

| Parameter | Type |
| :-- | :-- |
| `spec` | `PromptSpec` |
| `choices` | `Choice[]` |
| `state` | `ListState` |
| `multi` | `boolean` |

**Returns** `string`

## Interfaces

### KeyStream

A stream that can be put into raw mode and read a key at a time.

```ts
interface KeyStream {
    isTTY?: boolean;
    /**
     * Node's record of the mode. Read so that a stream somebody else already put into raw
     * mode — a prompt library, the program itself — is left raw when this prompt ends.
     */
    isRaw?: boolean;
    setRawMode?(raw: boolean): unknown;
    on(event: 'data', listener: (chunk: Buffer | string) => void): unknown;
    off(event: 'data', listener: (chunk: Buffer | string) => void): unknown;
    resume?(): unknown;
    pause?(): unknown;
}
```

### RawIo

```ts
interface RawIo extends Io {
    keys: KeyStream;
}
```

## Types

### Key

```ts
type Key = 'up' | 'down' | 'space' | 'enter' | 'cancel' | 'other';
```

---

# caique/spec

> Every export of caique/spec, with its signature and doc comment: flagOf, problemWith, BUILT_IN_KINDS, plus 4 types.

Source: https://caique.interlace.tools/docs/api/spec

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

What a prompt *is*, before anything draws one (R1).

```ts
import { flagOf, problemWith, BUILT_IN_KINDS } from 'caique/spec';
```

## Functions

### flagOf

`--output-dir`, which is what a refusal has to say to be actionable.

```ts
function flagOf(option: string): string;
```

| Parameter | Type |
| :-- | :-- |
| `option` | `string` |

**Returns** `string`

### problemWith

A `select` without choices, or a `confirm` with them, is a spec that cannot be drawn.
Caught here rather than in the widget, so a program with a malformed prompt fails on the
first run instead of the first time someone reaches that option.

```ts
function problemWith(spec: PromptSpec): string | undefined;
```

| Parameter | Type |
| :-- | :-- |
| `spec` | `PromptSpec` |

**Returns** `string \| undefined`

## Constants

### BUILT_IN_KINDS

The six caique draws itself, as data rather than as a `switch` nobody can read back.

```ts
const BUILT_IN_KINDS: ReadonlySet<string>;
```

## Interfaces

### BoundPrompt

A prompt spec bound to the option it answers.

```ts
interface BoundPrompt extends PromptSpec {
    /** The option's long name, without dashes — `output-dir`, not `--output-dir`. */
    option: string;
}
```

### Choice

One choice in a `select` or `multiselect`. `value` is what the option receives.

```ts
interface Choice {
    value: string;
    label?: string;
    hint?: string;
}
```

### PromptSpec

```ts
interface PromptSpec {
    kind: PromptKind;
    /** What a person is asked. Also what an agent reads in the refusal when it cannot be asked. */
    message: string;
    /** Offered as the answer if the person just presses return. */
    initial?: string | boolean | string[];
    /** Required for `select` and `multiselect`; meaningless for the rest. */
    choices?: Choice[];
    /** Returns a message when the answer is unacceptable, or nothing when it is fine. */
    validate?: (value: string) => string | undefined;
    /**
     * The most choices a raw `select` or `multiselect` shows at once, clack's name for it. The
     * screen caps it too: never more than the terminal's rows less three.
     */
    maxItems?: number;
}
```

## Types

### PromptKind

The six kinds a prompt can be — plus whatever a plugin adds.

```ts
type PromptKind = 'text' | 'confirm' | 'select' | 'multiselect' | 'password' | 'path' | (string & {});
```

---

# caique/terminal

> Every export of caique/terminal, with its signature and doc comment: createIo, streamsOf, plus 1 type.

Source: https://caique.interlace.tools/docs/api/terminal

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { createIo, streamsOf } from 'caique/terminal';
```

## Functions

### createIo

A reader and writer over a real stream pair.

```ts
function createIo(streams?: Streams): Io & {
    close: () => void;
};
```

| Parameter | Type |
| :-- | :-- |
| `streams` (optional) | `Streams` |

**Returns** `Io & { close: () => void; }`

## Constants

### streamsOf

A runtime's two streams as the pair `createIo` takes — the mapping, written down once.

```ts
const streamsOf: (runtime: Runtime) => Streams;
```

## Interfaces

### Streams

The stream pair a terminal Io is built over: a `Runtime`'s `stdin` and its `stdout`.

```ts
interface Streams {
    input: NodeJS.ReadableStream & {
        isTTY?: boolean;
    };
    output: NodeJS.WritableStream & {
        isTTY?: boolean;
        columns?: number;
        rows?: number;
    };
}
```

---

# Changelog

> Every release of caique, newest first, from its CHANGELOG.md — what changed and the pull request it came from.

Source: https://caique.interlace.tools/docs/changelog

## 1.6.3

### Patch Changes

- [#1483](https://github.com/ofri-peretz/burgee/pull/1483) [`3e69fb2`](https://github.com/ofri-peretz/burgee/commit/3e69fb2d8d068210347ac71d2886d6a4309859d1) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The package manifest names its author and publishes with `publishConfig` `{ "access": "public", "provenance": true }`. burgee's `homepage` is its landing page, https://burgee.interlace.tools. oxmutate gains `keywords`, so npm search finds it, and a `sideEffects` list (its CLI, its worker and its Vitest runner run on load), so a bundler can drop the rest. No code changes.
- Updated dependencies [[`3e69fb2`](https://github.com/ofri-peretz/burgee/commit/3e69fb2d8d068210347ac71d2886d6a4309859d1)]:
  - bellpull@1.0.11
  - closeout@1.1.10
  - linegauge@1.2.1
  - paratext@1.0.13
  - roundel@1.3.2

## 1.6.2

### Patch Changes

- [#1469](https://github.com/ofri-peretz/burgee/pull/1469) [`80fa4fb`](https://github.com/ofri-peretz/burgee/commit/80fa4fbdce8448adb1ad26bd0be95e5189284ba5) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Two fixes.

  - **An autocomplete search whose first match is disabled no longer overflows the stack.** The cursor search stepped by `Math.sign(0)` from a disabled option, which is the same option again; it now searches forward, as upstream does, and lands on the next enabled match.
  - **Line-mode `select` and `multiselect` read only an all-digits answer as a number.** `parseInt` read `1 2` as choice 1, `2x` as choice 2, and a label typed out, such as `3 apples`, as choice 3. Those are now refused, and a label that starts with a digit is matched as that label.

- Updated dependencies [[`80fa4fb`](https://github.com/ofri-peretz/burgee/commit/80fa4fbdce8448adb1ad26bd0be95e5189284ba5)]:
  - closeout@1.1.9

## 1.6.1

### Patch Changes

- [#1337](https://github.com/ofri-peretz/burgee/pull/1337) [`9bf2624`](https://github.com/ofri-peretz/burgee/commit/9bf2624f4ed6007fd8d745de4305cd6b3c6f6a95) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/inquirer` follows `@inquirer/core` 12.0.6 and `caique/inquirer/prompts` follows `@inquirer/prompts` 8.7.5. The first render waits a tick only when the input is a terminal, so an answer already piped into a non-TTY stdin before the prompt starts is read instead of dropped. `password` keeps the space after its message while the mask has nothing to draw, so the cursor sits past it. Their own suites grade them 46 / 46 and 222 / 222, level with the incumbents.

## 1.6.0

### Minor Changes

- [#1316](https://github.com/ofri-peretz/burgee/pull/1316) [`d565864`](https://github.com/ofri-peretz/burgee/commit/d56586433d64b9485a266d3085ea5ef8527e86d5) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `promptFor` asks for a command's missing option or positional, and refuses when nobody can
  answer (R1).

  - `import { promptFor } from 'caique/prompt-for'`. `promptFor(command, 'name', { kind: 'text',
message: 'Who?' })` wraps a command so its handler never sees a missing value. A person at a
    terminal is asked, on stderr, so the question never lands in the command's data. With no
    terminal, under `CI`, under a detected agent, under `--json` or in an `--mcp` tool call, it
    refuses with `USAGE`, naming how to pass the value: `<name>` for a positional, `--dry-run` for
    a `dryRun` option. A cancelled question is `CANCELLED`. burgee leaves with exit 2 or 4.
  - `promptFor(command)` resolves the `prompt:` a command already declares on its options or
    arguments. The command's shape is read structurally, and nothing in caique imports burgee.
  - The terminal is opened only to ask, handed to the host's exit path while it is open, and closed
    before the handler runs. Ctrl+C at the question gives the terminal back out of raw mode, on
    Linux, macOS and Windows.
  - A declared prompt is left out of the command's JSON, so `--schema` does not grow.
  - `caique/clack`'s `spinner({ style })` takes a spinner style as data, such as flagstaff's
    `lookupSpinner(name)` or a plugin's `spinners` entry. On a terminal its frames turn at its
    interval. Anywhere else its `static` line is printed in place of the first frame.
  - `decide()` and `resolvePrompts()` take a `flag`, which is how a refusal names an option when
    `--<option>` is not how it is passed.

## 1.5.2

### Patch Changes

- [#1285](https://github.com/ofri-peretz/burgee/pull/1285) [`6570ff2`](https://github.com/ofri-peretz/burgee/commit/6570ff28a3aa8959548ee338dfb114cb9b7deab5) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/inquirer` follows `@inquirer/core` 12.0.5 and `caique/inquirer/prompts` follows `@inquirer/prompts` 8.7.4. A prompt cancelled or aborted before its first render never draws it and leaves no listener on the input. `checkbox` shows its loading state while an async `validate` runs and ignores every key until it answers. `number` reads a line of only whitespace as empty: the default, or a refusal under `required`. Their own suites grade them 45 / 45 and 221 / 221, level with the incumbents.

## 1.5.1

### Patch Changes

- [#1258](https://github.com/ofri-peretz/burgee/pull/1258) [`e3b3a41`](https://github.com/ofri-peretz/burgee/commit/e3b3a41745ecdc853d741c457306c566541271b6) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `check` reads a `.json` plugin file as data. It handed every file to `import()`, and Node refuses a `.json` module without an import attribute (ERR_IMPORT_ATTRIBUTE_MISSING), so a plugin written as JSON got Node's message and no verdict, from the host's own `check` and through `burgee check`, which runs it.

- [#1266](https://github.com/ofri-peretz/burgee/pull/1266) [`02e6f9f`](https://github.com/ofri-peretz/burgee/commit/02e6f9fcd779d892e7097659a6bd4c2f0e5b5a04) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The family plugin schema (`schema.json`, identical in every plugin host) now describes `formats`, burgee's output-format key. This package reads nothing new, and a plugin carrying `formats` registers here as before.

- [#1252](https://github.com/ofri-peretz/burgee/pull/1252) [`efc994e`](https://github.com/ofri-peretz/burgee/commit/efc994ea20dae1f31990a7afef9dfa3c34fee596) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every benchmark figure in the README, a ratio, a byte count or a cold-start time, now links to
  the benchmarks page where it is measured.
- Updated dependencies [[`e3b3a41`](https://github.com/ofri-peretz/burgee/commit/e3b3a41745ecdc853d741c457306c566541271b6), [`02e6f9f`](https://github.com/ofri-peretz/burgee/commit/02e6f9fcd779d892e7097659a6bd4c2f0e5b5a04), [`efc994e`](https://github.com/ofri-peretz/burgee/commit/efc994ea20dae1f31990a7afef9dfa3c34fee596), [`efc994e`](https://github.com/ofri-peretz/burgee/commit/efc994ea20dae1f31990a7afef9dfa3c34fee596)]:
  - bellpull@1.0.10
  - closeout@1.1.8
  - linegauge@1.1.5
  - paratext@1.0.11
  - roundel@1.2.1

## 1.5.0

### Minor Changes

- [#1201](https://github.com/ofri-peretz/burgee/pull/1201) [`70a86aa`](https://github.com/ofri-peretz/burgee/commit/70a86aa6959b1ab6a27dc03bbfc3ff6c0ad9c37b) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/inquirer/prompts` now carries all ten of `@inquirer/prompts`' prompts: `input`, `confirm`, `password`, `number`, `expand`, `rawlist`, `search` and `editor` join `select` and `checkbox`, with their config and theme types. `@inquirer/prompts` 8.7.3's own suites pass 213 / 213, level with `@inquirer/prompts` itself (the eleven `editor` cases that answer through a mock of `@inquirer/external-editor` are excluded for both sides, D-20261011-inquirer-prompts-editor-mock). The subpath bundles to 44,683 B against the incumbent's 582,754 B. `editor` starts the user's editor through `bellpull/cross-spawn`, so caique now depends on `bellpull`.

## 1.4.5

### Patch Changes

- [#1186](https://github.com/ofri-peretz/burgee/pull/1186) [`af24328`](https://github.com/ofri-peretz/burgee/commit/af243288e27cbffbcffac18af7112172e46a003b) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Published declarations now keep each doc comment's first paragraph, its code examples and its `@param`, `@returns`, `@throws`, `@example`, `@deprecated`, `@default` and `@see` tags, and drop the longer design notes below them, so the tarballs are smaller (burgee by 5.7% gzipped, bellpull and closeout by about a fifth). Types are unchanged, and hover text in an editor keeps its summary. `burgee`'s README also names `burgee/program-schema.json`, the JSON Schema every `--schema` document validates against.
- Updated dependencies [[`af24328`](https://github.com/ofri-peretz/burgee/commit/af243288e27cbffbcffac18af7112172e46a003b), [`122635d`](https://github.com/ofri-peretz/burgee/commit/122635dce20998d1cba0eaa3c9df9c38bfd47c8b)]:
  - closeout@1.1.6
  - linegauge@1.1.4
  - paratext@1.0.10
  - roundel@1.2.0

## 1.4.4

### Patch Changes

- [#1160](https://github.com/ofri-peretz/burgee/pull/1160) [`0b381a0`](https://github.com/ofri-peretz/burgee/commit/0b381a0d394092edf2ea21a9143a10111aa72fe4) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Export `./package.json`. `require('<package>/package.json')` threw `ERR_PACKAGE_PATH_NOT_EXPORTED`, which broke tools that read a dependency's manifest that way: bundlers, license scanners and version checks.
- Updated dependencies [[`0b381a0`](https://github.com/ofri-peretz/burgee/commit/0b381a0d394092edf2ea21a9143a10111aa72fe4)]:
  - closeout@1.1.5
  - linegauge@1.1.3
  - paratext@1.0.9
  - roundel@1.1.3

## 1.4.3

### Patch Changes

- [#1141](https://github.com/ofri-peretz/burgee/pull/1141) [`711ba15`](https://github.com/ofri-peretz/burgee/commit/711ba151de96dcb18af8e7c9b293beaf0c1ab21d) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/clack`: a throw from the prompt's own code — a `render`, `onKey` or `finalize` that throws, on a key, on an abort, or on the first frame — now rejects the prompt's promise with that error, after turning raw mode off, removing the keypress listener and showing the cursor again. From a key it used to escape the keypress listener as an unhandledRejection, which kills a Node process by default, and left the prompt unsettled with raw mode on; from an abort it was an uncaught exception; from the first frame the promise rejected but left raw mode on and the keypress listener attached. A validator that throws is still a failed check, as before.

## 1.4.2

### Patch Changes

- [#1130](https://github.com/ofri-peretz/burgee/pull/1130) [`c05c86e`](https://github.com/ofri-peretz/burgee/commit/c05c86e2caa0fc3a89f97f7fe9c37bd7b876bfaf) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every drop-in subpath now type-checks under `moduleResolution: node10`, and under `module: commonjs`
  with no resolution set, which is TypeScript's default there. `import … from 'burgee/commander'`
  used to fail with TS2307 in such a project, although `require()` of the same specifier worked.
  Each package now declares `types` and a `typesVersions` map, derived from `exports`, with one key per
  typed subpath pointing at the file `exports` already names. `exports` is unchanged, so `node16`,
  `nodenext` and `bundler` read exactly what they read before. `controlroom/ink`'s declarations no
  longer name the untyped `react-reconciler`, which was TS7016 for consumers with `skipLibCheck: false`.
- Updated dependencies [[`c05c86e`](https://github.com/ofri-peretz/burgee/commit/c05c86e2caa0fc3a89f97f7fe9c37bd7b876bfaf)]:
  - closeout@1.1.4
  - linegauge@1.1.2
  - paratext@1.0.8
  - roundel@1.1.2

## 1.4.1

### Patch Changes

- [#1097](https://github.com/ofri-peretz/burgee/pull/1097) [`3f96896`](https://github.com/ofri-peretz/burgee/commit/3f96896fe01484cf597590d4bcd896b15d58a05e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/clack`: a validator that throws, or returns a promise that rejects — a network check that fails, say — is now a failed check: the prompt shows the error's message (or the `messages.error` setting when it has none) and stays open, so the person can retry or cancel. It used to escape the keypress listener as an unhandledRejection, which kills a Node process by default; after an abort it escaped from a prompt that had already answered. `@clack/core` 1.5.1 lets it escape the same way.

## 1.4.0

### Minor Changes

- [#1095](https://github.com/ofri-peretz/burgee/pull/1095) [`98a0004`](https://github.com/ofri-peretz/burgee/commit/98a00049a453aac7a5b4b69451ab51e0abc4618f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A list prompt never outgrows the terminal. The raw `select` and `multiselect` draw a list longer
  than the screen as a window that follows the cursor, with `↑ N more` and `↓ N more` rows for
  what is outside it, so a repaint never climbs above the top row. The window is the new
  `maxItems` on a prompt spec, clack's name for it, and never more than the terminal's rows less
  three. `renderList` takes `maxItems`, and the terminal `Writer` reports `rows`, read live.

## 1.3.0

### Minor Changes

- [#1037](https://github.com/ofri-peretz/burgee/pull/1037) [`50cc502`](https://github.com/ofri-peretz/burgee/commit/50cc5024df7a99ecd2dff33570eea21730b87b99) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - New entry point `caique/inquirer/prompts`: `@inquirer/prompts`' `select` and `checkbox`, with `Separator` and their config, theme and choice types, over `caique/inquirer`'s prompt loop. Both are graded by their own suites in `@inquirer/prompts` 8.7.3, `select`'s pagination suite included: 100 of those 100 cases pass, level with the real packages. Paging follows `@inquirer/core`'s `usePagination`, multi-line choices and `loop: false` included. The other eight prompts are not built yet, so `burgee migrate` does not rewrite `@inquirer/prompts` imports. `caique/inquirer` is unchanged, and a program that imports it loads none of this.

## 1.2.1

### Patch Changes

- [#1068](https://github.com/ofri-peretz/burgee/pull/1068) [`566b7d7`](https://github.com/ofri-peretz/burgee/commit/566b7d7a35431f384518e9705620441c5ab4b9b9) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/clack`: Ctrl-C or escape while an async validator is still out now cancels the prompt (it answers `CANCEL_SYMBOL`), where it used to be dropped. In raw mode Ctrl-C reaches the prompt as a byte, not a signal, so a validator that never answered left no way out. `@clack/core` drops the key too, but its readline interface then leaves raw mode, so a second Ctrl-C kills the process. Other keys still wait for the verdict.
- Updated dependencies [[`4a62884`](https://github.com/ofri-peretz/burgee/commit/4a6288481a77dce34c496af5a5ffbaed900483c6)]:
  - paratext@1.0.7

## 1.2.0

### Minor Changes

- [#1060](https://github.com/ofri-peretz/burgee/pull/1060) [`52f6c71`](https://github.com/ofri-peretz/burgee/commit/52f6c71d2db4bc3fd9cbfd9e83fedb5f3ea359dc) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--quiet` reaches `caique/clack`'s decoration. Every clack call's options take an optional `runtime` (roundel's policy `Runtime`, which is burgee's `ctx.runtime`). When it says `quiet`, `spinner`, `tasks`, `intro`, `outro`, `note` and `log.message`, `info`, `step`, `success` and `warn` write nothing, and the spinner arms no interval; their lifecycle methods still run. `log.error` and `cancel` still write, and prompts ignore `quiet`. A call without a `runtime` behaves exactly as before, and quiet is never read from argv or the environment. `isCI()` takes an optional runtime to read `CI` from.

  burgee's README shows the call under For agents: `spinner({ runtime: ctx.runtime })`.

### Patch Changes

- Updated dependencies [[`1797388`](https://github.com/ofri-peretz/burgee/commit/1797388f27a294803b12839ff4d074226bd40917)]:
  - closeout@1.1.3

## 1.1.0

### Minor Changes

- [#1045](https://github.com/ofri-peretz/burgee/pull/1045) [`c4fd9a3`](https://github.com/ofri-peretz/burgee/commit/c4fd9a3cb10bc36bef8c468365addfc6deb572cf) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - caique's own chrome can speak the user's language. That covers the instruction under a list, a problem with an answer, the giving-up line, and the no-terminal and cancel refusals. A locale pack registered with `register()` carries translations under ids that begin `caique.`, so one object can serve burgee's catalog too. The new `caique/locale` entry turns the runtime's `locale` into the translator: `io.say = sayFor(runtime.locale)`. `ask` and `resolvePrompts` apply it. Neither reads the catalog itself, and caique never reads `LANG`. A refusal keeps its English `message` and `fix`, which a host may put in a machine envelope, and adds `localised` beside them. `caique check` renders a pack's messages, or refuses an unknown id, a stray placeholder or a missing plural form with `E_PLUGIN_SCHEMA`. With no `say` handed in, every byte is unchanged, and `caique/clack` and `caique/inquirer` keep their incumbents' English.

  burgee: the family plugin schema it publishes describes the `locales` key.

### Patch Changes

- [#1045](https://github.com/ofri-peretz/burgee/pull/1045) [`c4fd9a3`](https://github.com/ofri-peretz/burgee/commit/c4fd9a3cb10bc36bef8c468365addfc6deb572cf) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The family plugin schema (`schema.json`, identical in every plugin host) now describes `locales`, burgee's locale-pack key. A plugin carrying `locales` validates against the shared schema as it does against `burgee/locale-pack-schema.json`, which lists every message id. This package reads nothing new, and a plugin carrying `locales` registers here as before.
- Updated dependencies [[`c4fd9a3`](https://github.com/ofri-peretz/burgee/commit/c4fd9a3cb10bc36bef8c468365addfc6deb572cf)]:
  - closeout@1.1.2
  - linegauge@1.1.1
  - paratext@1.0.6
  - roundel@1.1.1

## 1.0.5

### Patch Changes

- [#1012](https://github.com/ofri-peretz/burgee/pull/1012) [`49d8e94`](https://github.com/ofri-peretz/burgee/commit/49d8e943ceaf8dcef14d43c0a70c2edec1a67816) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `@inquirer/prompts` is now graded: its ten prompts' own suites (8.7.3) are vendored and run against `caique/inquirer`, with a control of 213 of 213 against the real packages. `caique/inquirer` passes 0 of them today, because it exports `@inquirer/core`'s surface and none of the prompts yet, and `burgee migrate` reports `@inquirer/prompts` as a graded path that is not level, never rewriting it. The eleven `@inquirer/editor` cases are excluded by title: each answers the prompt through a mock of `@inquirer/external-editor`, which caique does not import.

  The oracle gains two host fields for it. `suiteFiles` lists a monorepo suite's files across several packages and vendors only those; `defaultExport` grades a suite that imports its prompt as a default against the named export a program migrates.

- [#1022](https://github.com/ofri-peretz/burgee/pull/1022) [`ecb0a00`](https://github.com/ofri-peretz/burgee/commit/ecb0a00ca68e9a3b3584aefabb9dcf97e3ff967a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The tarball no longer carries declaration files that no `exports` entry reaches. TypeScript could never open them, because a deep import is refused by `exports`. Every entry's types are unchanged. The ten packages drop 71 files and 118,312 bytes between them, burgee 35 files and 76,504 bytes, which takes its tarball from 251,814 to 225,278 bytes gzipped.
- Updated dependencies [[`bfe4ab8`](https://github.com/ofri-peretz/burgee/commit/bfe4ab8b13ff04293345a69007cad9e0cb81c678), [`1968eb4`](https://github.com/ofri-peretz/burgee/commit/1968eb46feec57bb047a9c4a4288e0cf4442f4b2), [`65afee5`](https://github.com/ofri-peretz/burgee/commit/65afee5c96e4cae62dbb9b0ba28fab98fffdbf01), [`bcc438a`](https://github.com/ofri-peretz/burgee/commit/bcc438ac3936ee1cd530931ea090c6a8bdd016b2), [`ecb0a00`](https://github.com/ofri-peretz/burgee/commit/ecb0a00ca68e9a3b3584aefabb9dcf97e3ff967a)]:
  - linegauge@1.1.0
  - paratext@1.0.5
  - roundel@1.1.0
  - closeout@1.1.1

## 1.0.4

### Patch Changes

- [#938](https://github.com/ofri-peretz/burgee/pull/938) [`9babb6d`](https://github.com/ofri-peretz/burgee/commit/9babb6da1ae7783c7e8367f89e3da9dffc85ffdb) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - npm description and README: the description says what the package does, then its dependency fact in one of two wordings ("Zero dependencies." or "No dependency outside the burgee family."), then its drop-in paths. The README's family section states how the family is built — the leaves, one-way dependencies, nothing from outside the family, trusted publishing with provenance — and its table column is "Migrates from". No API, compatibility grade or benchmark changes.
- Updated dependencies [[`9babb6d`](https://github.com/ofri-peretz/burgee/commit/9babb6da1ae7783c7e8367f89e3da9dffc85ffdb)]:
  - closeout@1.0.4
  - linegauge@1.0.8
  - paratext@1.0.4
  - roundel@1.0.4

## 1.0.3

### Patch Changes

- [#917](https://github.com/ofri-peretz/burgee/pull/917) [`735f0f6`](https://github.com/ofri-peretz/burgee/commit/735f0f68048f2d0f5e4effad151ed5132b480bb8) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - README: the opening paragraph says what the package does first. The drop-in path follows it as one line, naming the incumbent and `npx burgee migrate`, and every compatibility row and benchmark is unchanged.
- Updated dependencies [[`735f0f6`](https://github.com/ofri-peretz/burgee/commit/735f0f68048f2d0f5e4effad151ed5132b480bb8)]:
  - closeout@1.0.3
  - linegauge@1.0.7
  - paratext@1.0.3
  - roundel@1.0.3

## 1.0.2

### Patch Changes

- [#897](https://github.com/ofri-peretz/burgee/pull/897) [`f29f159`](https://github.com/ofri-peretz/burgee/commit/f29f159ca0c9746f58d8ba84eec9be72b1140093) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - controlroom has its own docs site at https://controlroom.interlace.tools: its README's Docs line, its `homepage`, and every family table now link there.
- Updated dependencies [[`f29f159`](https://github.com/ofri-peretz/burgee/commit/f29f159ca0c9746f58d8ba84eec9be72b1140093)]:
  - closeout@1.0.2
  - linegauge@1.0.6
  - paratext@1.0.2
  - roundel@1.0.2

## 1.0.1

### Patch Changes

- [#886](https://github.com/ofri-peretz/burgee/pull/886) [`d33ae03`](https://github.com/ofri-peretz/burgee/commit/d33ae0342583cebfa54be1a043d0c085efd9eaaf) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The README and docs index say caique is 1.0, not "Released, pre-1.0.": it shipped 1.0.0 on 2026-10-08.

## 1.0.0

### Major Changes

- [#851](https://github.com/ofri-peretz/burgee/pull/851) [`446a691`](https://github.com/ofri-peretz/burgee/commit/446a691ae1b1ff05e06699fd44034f61e91906c2) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - caique 1.0.0. The spec is fully built, `caique/clack` (16 / 16) and `caique/inquirer` (41 / 41) pass their incumbents' own suites at the latest release, level with the incumbents, and coverage is 100% on all four measures (D-20261007-caique-controlroom-1-0-evidence). The published entries, the plugin `schema.json` and the `caique` bin become a semver contract. No API changed in this release.

### Patch Changes

- [#857](https://github.com/ofri-peretz/burgee/pull/857) [`d80b2d0`](https://github.com/ofri-peretz/burgee/commit/d80b2d0f4a535400c6825b42ac2d8e1be2827f4e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique check` refuses a widget whose `static` throws on its own `sample`. It used to print the throw as a row, then `<name>: ok`, and exit 0. Now each throwing widget is an `E_NO_STATIC_PROJECTION` refusal that names the widget and what it threw, with a `fix`, and the command exits 1 without printing `ok`.

- [#848](https://github.com/ofri-peretz/burgee/pull/848) [`6ae533e`](https://github.com/ofri-peretz/burgee/commit/6ae533e4610c32bad557f5d74a24d0c9a0f07f7e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The family `schema.json` describes what five values look like. `contract` is `1`, and burgee refuses a plugin that declares none. A caique widget's `static(spec)` gets `{ kind, message, ...sample.done }`. A seniority `rank` sits between the built-in layers at flag 0, environment 10, config file 20, `package.json` 30 and default 40. A burgee hook's `filter` is `{ command: RegExp }`, now with `command` required, so the schema and the host refuse the same filters.

- [#857](https://github.com/ofri-peretz/burgee/pull/857) [`d80b2d0`](https://github.com/ofri-peretz/burgee/commit/d80b2d0f4a535400c6825b42ac2d8e1be2827f4e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The family `schema.json` closes a bellpull resolver's `when` with `additionalProperties: false`, so the schema and bellpull's own validation refuse the same unknown keys.

- [#848](https://github.com/ofri-peretz/burgee/pull/848) [`6ae533e`](https://github.com/ofri-peretz/burgee/commit/6ae533e4610c32bad557f5d74a24d0c9a0f07f7e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Each README now shows a whole plugin as a default export, the command that checks it (from an install, and from a clone where `dist/` has to be built first), and the report `check` prints when the plugin passes. caique says what a widget's `static(spec)` receives. seniority gives the `rank` for each slot between the built-in layers. bellpull says that `{VAR}` is the only substitution a path gets.
- Updated dependencies [[`6ae533e`](https://github.com/ofri-peretz/burgee/commit/6ae533e4610c32bad557f5d74a24d0c9a0f07f7e), [`d80b2d0`](https://github.com/ofri-peretz/burgee/commit/d80b2d0f4a535400c6825b42ac2d8e1be2827f4e)]:
  - closeout@1.0.1
  - linegauge@1.0.5
  - paratext@1.0.1
  - roundel@1.0.1

## 0.7.2

### Patch Changes

- Updated dependencies [[`1945d65`](https://github.com/ofri-peretz/burgee/commit/1945d65f22aafabd380d67f1e40341d6ef3aa6fa), [`1945d65`](https://github.com/ofri-peretz/burgee/commit/1945d65f22aafabd380d67f1e40341d6ef3aa6fa), [`9ebef65`](https://github.com/ofri-peretz/burgee/commit/9ebef654930ac4565f1ee04ec5f8b6f735c6a1d9), [`1945d65`](https://github.com/ofri-peretz/burgee/commit/1945d65f22aafabd380d67f1e40341d6ef3aa6fa)]:
  - closeout@1.0.0
  - paratext@1.0.0
  - roundel@1.0.0

## 0.7.1

### Patch Changes

- [#810](https://github.com/ofri-peretz/burgee/pull/810) [`a47209b`](https://github.com/ofri-peretz/burgee/commit/a47209b3a7774e4ecdd1def3043d19afed5a1266) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/terminal`: `createIo()`'s reader no longer drops lines that arrive before a question is asked. It listened for one `line` event per `line()` call, so `printf 'x\ny\n' | cli` lost both answers and `ask()` read the missing line as a cancellation. Lines are now queued from a single listener and handed out in order, before the end of the stream is.

- [#816](https://github.com/ofri-peretz/burgee/pull/816) [`5230016`](https://github.com/ofri-peretz/burgee/commit/52300169a98ece41b3544e5316833464e63a7c83) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - controlroom hosts plugins (R10): `keymaps` and `panes` register through `controlroom/plugin`'s `register()` against the family schema, a screen takes either by name, and `controlroom check <plugin-file>` reports what a plugin contributes. The family schema every host ships gains the `keymaps` and `panes` definitions.
- Updated dependencies [[`5230016`](https://github.com/ofri-peretz/burgee/commit/52300169a98ece41b3544e5316833464e63a7c83), [`5230016`](https://github.com/ofri-peretz/burgee/commit/52300169a98ece41b3544e5316833464e63a7c83), [`5230016`](https://github.com/ofri-peretz/burgee/commit/52300169a98ece41b3544e5316833464e63a7c83)]:
  - closeout@0.7.0
  - paratext@0.9.0
  - linegauge@1.0.4
  - roundel@0.6.3

## 0.7.0

### Minor Changes

- [#801](https://github.com/ofri-peretz/burgee/pull/801) [`81fc994`](https://github.com/ofri-peretz/burgee/commit/81fc994c27ae7731495c810c4f642ba63d7eb073) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/editor`: the line editor as a component a host drives (`editor()` returns `initial`, an `onKey` reducer and `render`), with multi-line entry, history, bracketed paste treated as text, and a completion menu the program feeds. Its commands are a `caique/keys` keymap (`EDITOR_KEYS`). Off a terminal, `submissions(stdin)` yields one entry per line and ends when the input does. The editing itself moved into a module `caique/clack`'s prompts share, so there is one line editor in the package.

- [#801](https://github.com/ofri-peretz/burgee/pull/801) [`81fc994`](https://github.com/ofri-peretz/burgee/commit/81fc994c27ae7731495c810c4f642ba63d7eb073) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/keys`: key presses decoded through `node:readline`'s keypress events into one `KeyPress` shape, keymaps as plain data (`match()`, `bindings()`), and `readKeys()`, which takes raw mode once through `closeout/cursor` and throws `E_NOT_A_TERMINAL` with a `fix` instead of waiting when stdin is not a terminal. `caique/raw`'s `keyOf` is rebuilt on the same decoder, and now reads the application-mode arrows (`ESC O A`) a terminal can send.

## 0.6.4

### Patch Changes

- Updated dependencies [[`b44f426`](https://github.com/ofri-peretz/burgee/commit/b44f426621ed799700cceda8c979de8f759f56b7), [`6195b99`](https://github.com/ofri-peretz/burgee/commit/6195b99344a21b4a05ab100fc38358deab229ce8)]:
  - paratext@0.8.0
  - roundel@0.6.1

## 0.6.3

### Patch Changes

- [#764](https://github.com/ofri-peretz/burgee/pull/764) [`1817b62`](https://github.com/ofri-peretz/burgee/commit/1817b6286fae3943e79686a42dc635cca0f0cdda) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/clack` now grades 16 / 16 against `@clack/prompts` 1.8.1's own suite, level with clack itself at 16 / 16. It was 16 / 17. The pass count did not change. The denominator did: one case, `guide.test.ts`'s `no prompt renders a guide when withGuide is globally false`, is now excluded by its exact title. It imports `updateSettings` from `@clack/core` and asserts that the prompts read that package's module state, so it grades `@clack/core` and not `@clack/prompts` (D-20260930-caique-clack-core-exclusion). The exclusion and its reason are on the compatibility page.

  Because the row is level, `burgee migrate` now rewrites `@clack/prompts` to `caique/clack`. It refuses a file that imports `box`, `progress` or `taskLog`, which `caique/clack` does not build, and leaves that file on clack. It does not rewrite `@clack/core`. So a migrated program that imports `updateSettings` from `@clack/core` is still changing clack's settings, and caique's prompts never read them. Import `updateSettings` from `caique/clack` instead.

- Updated dependencies [[`6c2e9c5`](https://github.com/ofri-peretz/burgee/commit/6c2e9c5cee5d9962c0d75d84a766c76b76760f7f), [`6c2e9c5`](https://github.com/ofri-peretz/burgee/commit/6c2e9c5cee5d9962c0d75d84a766c76b76760f7f)]:
  - linegauge@1.0.1
  - paratext@0.7.5

## 0.6.2

### Patch Changes

- Updated dependencies [[`a115799`](https://github.com/ofri-peretz/burgee/commit/a1157991a5defddadfbea49ba8ea3bf161d4a832)]:
  - roundel@0.6.0

## 0.6.1

### Patch Changes

- [#752](https://github.com/ofri-peretz/burgee/pull/752) [`22e6dae`](https://github.com/ofri-peretz/burgee/commit/22e6dae1b71bfa478265829a1b98d20a6f9de4f7) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A plugin that declares `contract: 0` or a negative contract is now refused with `E_PLUGIN_CONTRACT`, as `schema.json`'s minimum of 1 always said. These hosts checked only that a contract was not newer than the one they know, so 0 and below registered.
- Updated dependencies [[`12bac9c`](https://github.com/ofri-peretz/burgee/commit/12bac9c99cb87ec2b67a56b4afc38de2c21687c7), [`22e6dae`](https://github.com/ofri-peretz/burgee/commit/22e6dae1b71bfa478265829a1b98d20a6f9de4f7)]:
  - paratext@0.7.4
  - closeout@0.6.1
  - roundel@0.5.6

## 0.6.0

### Minor Changes

- [#638](https://github.com/ofri-peretz/burgee/pull/638) [`e4c1f69`](https://github.com/ofri-peretz/burgee/commit/e4c1f6951dcbc73d581ce1edce4cf3f9ae183058) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/clack` now carries `@clack/prompts`' prompts, not only `limitOptions`: `text`, `password`, `confirm`, `multiline`, `date`, `path`, `select`, `selectKey`, `multiselect`, `groupMultiselect`, `autocomplete` and `autocompleteMultiselect`, with `intro`, `outro`, `cancel`, `note`, `log`, `stream`, `spinner`, `tasks`, `group`, the `S_*` glyphs, `settings`/`updateSettings` and `isCancel`, under clack's names and options. They run on caique's own keypress loop and reach nothing outside this repository. Graded by clack's own suite at 16 / 17 (was 14 / 17; the control is 17 / 17): the one case left imports `updateSettings` from `@clack/core`, which caique does not depend on (D-152). The spinner animates only on a terminal outside CI and prints each message once anywhere else. `box`, `progress` and `taskLog` are not built. `burgee migrate` reports the new grade and, since it is not level with the control, still does not rewrite `@clack/prompts`.

### Patch Changes

- [#708](https://github.com/ofri-peretz/burgee/pull/708) [`b52659f`](https://github.com/ofri-peretz/burgee/commit/b52659fbb7da12fa5fe372962af3bcdac0d022e6) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/clack`: a prompt's raw mode goes through `closeout/cursor`'s `rawMode`, as `caique/raw` already does. A prompt on a stream that was already raw no longer switches raw mode off when it ends, and raw mode it did turn on is also turned off on `SIGINT` and `SIGTERM`. `caique/clack` still grades 16 / 17 against clack's suite.

- [#726](https://github.com/ofri-peretz/burgee/pull/726) [`2c631cb`](https://github.com/ofri-peretz/burgee/commit/2c631cb820ec181dd7615864cc6ce7412ee7cafe) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Two fixes in `caique/clack`, and paths no input could reach are removed. A prompt aborted while its validator was still running drew one more frame after it had closed and given the cursor back, so the frame landed under whatever the program wrote next; it now writes nothing once closed. `date` took a locale's field separator from its first literal, which in Pashto is the space after the era, so the fields read `yyyy mm dd` rather than `yyyy-mm-dd`; it now takes the literal after the first field, which is also right where the last literal is a suffix, as in Bulgarian's `г.`. `caique/raw`'s `askList`, called directly with no choices, answered a multiselect with `['']` after a space; it now answers `[]`. The fallbacks removed from `clack-core`, `clack-date`, `clack-prompts`, `clack-search`, `raw`, `binding` and `terminal` are for values that are always there; behaviour is otherwise unchanged.

- [#727](https://github.com/ofri-peretz/burgee/pull/727) [`b9de3f3`](https://github.com/ofri-peretz/burgee/commit/b9de3f341bb59b9a2139bb094809176af5a65bee) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Four checks that could never change a result are removed from `caique/inquirer`; behaviour is unchanged. The screen's last line no longer falls back to an empty string (splitting a string always yields one), the loader no longer defaults a tick that `useState(0)` always sets, `INQUIRER_KEYBINDINGS=''` no longer has its own early return (it already parses to no bindings), and `useMemo` no longer asks whether a slot that holds a value was initialised.

- [#728](https://github.com/ofri-peretz/burgee/pull/728) [`9a65722`](https://github.com/ofri-peretz/burgee/commit/9a657220fe9c877ca475e7be1f3a575a0e88a76a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/clack`'s `spinner` now ends on its `errorMessage` when the process exits with a failing code the program chose (2–127), as clack's does; before this every exit while spinning ended as a cancel, and `errorMessage` was never shown. A signal, and exit codes 0 and 1, still end as a cancel. Unreachable code is removed from the spinner and from `caique check`, whose never-called "replaces" helper is gone; behaviour is otherwise unchanged.

- [#680](https://github.com/ofri-peretz/burgee/pull/680) [`7f59bc2`](https://github.com/ofri-peretz/burgee/commit/7f59bc2a612aa71925d5eca1db96d44d9f488c9a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Raw mode is paired with its undo through `closeout/cursor`'s `rawMode`, the way the cursor already was.

  - `caique/raw`: a list prompt on a stream that was already in raw mode — a prompt library's, or the program's own — no longer switches raw mode off when it ends; it used to call `setRawMode(false)` unconditionally and take the keyboard from its owner. Raw mode the prompt did turn on is now turned off on `SIGINT` and `SIGTERM` too, not only in the prompt's own `finally`. `KeyStream` gains an optional `isRaw`.
  - `flagstaff/ora`: stdin-discarder's raw mode goes through the same pairing. Behaviour is unchanged except that an already-raw stdin is no longer written to at all.

- [#677](https://github.com/ofri-peretz/burgee/pull/677) [`8bc14e6`](https://github.com/ofri-peretz/burgee/commit/8bc14e644f02a28ce54333d683742f2fca027917) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Measuring text against a terminal is linegauge's job, and four places did it by hand.

  - `caique/raw`: the repaint counted a frame's rows with `split('\n')` and ignored wrapping, so a choice whose hint was wider than the terminal left a stale copy of the question on screen after every keypress. It counts rows with linegauge's `lineCount` against the terminal's width, which `Writer` now carries as an optional `columns` (read through to the output stream by `createIo`). A writer without one is treated as never wrapping, as before.
  - `burgee/testing`: `stripAnsi` is linegauge's `strip`. The regex it used left private modes (`ESC[?25l`), the colon form of a truecolor SGR (`ESC[38:2::255:0:0m`) and OSC 8 hyperlinks in the text.
  - `burgee` help: descriptions and epilogues are folded by `linegauge/wrap` rather than a loop of help's own. A styled description now opens and closes its styles on each row instead of running its colour into the next row's indent, and a run of spaces at a break no longer leaves trailing whitespace. Lines the author indented are still kept verbatim, and a word wider than the row still overflows rather than breaking.
  - `burgee` `config explain`: the option column is padded in terminal columns, so a CJK option name no longer pushes its value two columns right of the others.

- [#674](https://github.com/ofri-peretz/burgee/pull/674) [`e9f45d8`](https://github.com/ofri-peretz/burgee/commit/e9f45d85d9db5b2e3dcaa1e43f292a1281a6952a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - README: family header, badges, install, migrating, the family table.

  Every package README now opens the same way — lockup, tagline, one badge row in one order (npm version, downloads, Quality Gate, the package's own coverage, OpenSSF Scorecard, unpacked size, dependencies, types, Node, licence, npm provenance), a row of compatibility badges read from the graded baseline — and carries the same sections in the same order: Install for npm, pnpm, yarn and bun, Quick start, Migrating as a before/after diff, Compatibility, Benchmarks, For agents, API, and a generated table of the nine packages. Links are absolute, so they work on npm as well as GitHub.

- [#684](https://github.com/ofri-peretz/burgee/pull/684) [`6c7b55a`](https://github.com/ofri-peretz/burgee/commit/6c7b55a01ea2e3aa1993419f78fbf6858ade5f8b) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `paratext/csi`: the CSI half of `ansi-escapes` as a subpath of its own — cursor moves, erases, scrolling, the alternate screen and synchronized output, byte-exact with `ansi-escapes` 7.3.0. It is 2,700 bytes and, unlike the package root, registers no built-ins when imported.

  `flagstaff/log-update`, `flagstaff/ora`, `caique/raw` and `caique/inquirer` take their cursor sequences from it instead of carrying their own copies; caique now depends on paratext. Output is unchanged, with one spelling difference: `caique/raw`'s repaint clears with `ESC[J` rather than the equivalent `ESC[0J`. `caique/inquirer` keeps `@inquirer/ansi`'s answer of nothing for a zero-row move, where `ansi-escapes`' `cursorUp(0)` is `ESC[0A`.

- [#678](https://github.com/ofri-peretz/burgee/pull/678) [`088cecc`](https://github.com/ofri-peretz/burgee/commit/088ceccb7dda1cbe878950c631f49f48980dd2e2) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Whether anybody is there, whether to colour, and whether a tick can be drawn are roundel's questions, and three packages answered them by hand.

  - `roundel/terminal` (new subpath, 878 B, reaching nothing): `interactive(rt)` — a terminal on stdin, no `CI`, and no agent variable (`CLAUDECODE`, `AI_AGENT`, `CURSOR_AGENT`, `CODEX_THREAD_ID`, `GEMINI_CLI`, exported as `AGENTS`), with `FORCE_TTY=1` as the override — and `unicode(rt)`, is-unicode-supported 2.1.0's table over `{ env, platform }`.
  - `caique/decide` now depends on `roundel` and asks `interactive()`. **Behaviour change:** under an agent that has a terminal — `CLAUDECODE=1` and a TTY on stdin — a missing required value is refused with a usage error naming the flag (`--x is required when nobody is there to answer`) instead of prompting and hanging the agent. `FORCE_TTY=1` now prompts even without a terminal on stdin, as it does for burgee.
  - `caique/inquirer`'s tick and `flagstaff/ora`'s log symbols and spinner fallback use roundel's `unicode()`. caique's copy was a four-condition subset: the Linux console (`TERM=linux`) now gets `√` rather than `✔`, and ConEmu/Cmder, Terminus, Alacritty, rxvt-unicode and JetBrains' terminal on Windows now get `✔`, as `figures` draws them.
  - `burgee` help colour is roundel's `colorLevel(rt) > 0`. **Behaviour changes:** `NO_COLOR` now beats `FORCE_COLOR`; `--no-color` and `--color=…` on the command line are honoured; `CLI_ACCESSIBLE` turns help colour off; and a terminal that sets no `TERM` (Windows' conhost) gets plain help unless `FORCE_COLOR`, `--color` or `COLORTERM` asks for colour.
  - `burgee/contrast` rounds with roundel's `round2`; no output changes.
  - `paratext`: the supports-color fork behind `paratext/terminal-link` is unchanged, and now held to roundel's policy by a parity test everywhere their two incumbents agree.

- Updated dependencies [[`6d8aadf`](https://github.com/ofri-peretz/burgee/commit/6d8aadff01a4c65ef3be16fe2082b0abd0c00b90), [`ff4159d`](https://github.com/ofri-peretz/burgee/commit/ff4159d25544fd45257f145e40ff0c5f8dfc4b3a), [`5e635b0`](https://github.com/ofri-peretz/burgee/commit/5e635b0a79c16ff2b459a4d00c80d334d5d945d1), [`ff4159d`](https://github.com/ofri-peretz/burgee/commit/ff4159d25544fd45257f145e40ff0c5f8dfc4b3a), [`6ef8227`](https://github.com/ofri-peretz/burgee/commit/6ef822762f5ad19564215945d7e76aa329614585), [`7c77cd2`](https://github.com/ofri-peretz/burgee/commit/7c77cd25c8fbeea4199c38c135e3a8937907f849), [`6ef8227`](https://github.com/ofri-peretz/burgee/commit/6ef822762f5ad19564215945d7e76aa329614585), [`6ef8227`](https://github.com/ofri-peretz/burgee/commit/6ef822762f5ad19564215945d7e76aa329614585), [`e9f45d8`](https://github.com/ofri-peretz/burgee/commit/e9f45d85d9db5b2e3dcaa1e43f292a1281a6952a), [`8a338ba`](https://github.com/ofri-peretz/burgee/commit/8a338baa50bb754051b18c00dbd0972976cccba1), [`6c7b55a`](https://github.com/ofri-peretz/burgee/commit/6c7b55a01ea2e3aa1993419f78fbf6858ade5f8b), [`620fc74`](https://github.com/ofri-peretz/burgee/commit/620fc74af013834ca6b15faa2772aeb94c5013b1), [`088cecc`](https://github.com/ofri-peretz/burgee/commit/088ceccb7dda1cbe878950c631f49f48980dd2e2), [`4319563`](https://github.com/ofri-peretz/burgee/commit/4319563b902c9d968786196f495cf47e7d4d9d39)]:
  - closeout@0.6.0
  - linegauge@1.0.0
  - paratext@0.7.3
  - roundel@0.5.5

## 0.5.4

### Patch Changes

- [#627](https://github.com/ofri-peretz/burgee/pull/627) [`4a629a9`](https://github.com/ofri-peretz/burgee/commit/4a629a9ff1129f2ce6f0c34e7cfc1d159304d18a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Lint with every published Interlace ESLint plugin, and fix what the upgrade surfaced.

  - caique: the inquirer theme merge skips `__proto__`, `constructor` and `prototype` keys, so a theme object cannot swap the merged object's prototype.
  - burgee: last-element reads use `.at(-1)`.
  - burgee, closeout, flagstaff, roundel: helpers that capture nothing from their enclosing function move to module scope.
  - seniority: suppression comments name the `no-dynamic-require` rule that now reports the config loader's dynamic `require`.

  No public API or output changes.

- Updated dependencies [[`4a629a9`](https://github.com/ofri-peretz/burgee/commit/4a629a9ff1129f2ce6f0c34e7cfc1d159304d18a)]:
  - closeout@0.5.4

## 0.5.3

### Patch Changes

- [#604](https://github.com/ofri-peretz/burgee/pull/604) [`0e7b1e8`](https://github.com/ofri-peretz/burgee/commit/0e7b1e88a7021350cf689f109c7728f799be1589) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Each README links to its migration guides under the docs link: "Migrating from: chalk", "ora · log-update · boxen · cli-table3", and so on. That puts a path from the npm page to the guide for the library you are replacing. No code changes.
- Updated dependencies [[`0e7b1e8`](https://github.com/ofri-peretz/burgee/commit/0e7b1e88a7021350cf689f109c7728f799be1589)]:
  - linegauge@0.5.4
  - closeout@0.5.3

## 0.5.2

### Patch Changes

- [#518](https://github.com/ofri-peretz/burgee/pull/518) [`866b972`](https://github.com/ofri-peretz/burgee/commit/866b9724652bebea867a730b8f2ea5e0ca63f5ab) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - README weight lines now count every incumbent with a graded drop-in: terminal-link and term-img (paratext), exit-hook (closeout), @inquirer/core (caique).

- [#474](https://github.com/ofri-peretz/burgee/pull/474) [`1955419`](https://github.com/ofri-peretz/burgee/commit/19554194342b55f8893161f894a8c2a4df1b0f21) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - burgee plugins can hook two more stages. `parse` runs before the command is resolved: it receives argv and may return a replacement, which is how an alias plugin maps `d` to `deploy`. `shutdown` runs once as the program exits, whether the command succeeded or failed. The family `schema.json` shipped in every package now describes both stages.
- Updated dependencies [[`866b972`](https://github.com/ofri-peretz/burgee/commit/866b9724652bebea867a730b8f2ea5e0ca63f5ab), [`1955419`](https://github.com/ofri-peretz/burgee/commit/19554194342b55f8893161f894a8c2a4df1b0f21), [`1b002e0`](https://github.com/ofri-peretz/burgee/commit/1b002e0b72f8dc1aa61020fb40c26e50949f16e7), [`77ff1cb`](https://github.com/ofri-peretz/burgee/commit/77ff1cb8e595d32bb8bddf441ae21fc61e6f247d)]:
  - closeout@0.5.2
  - linegauge@0.5.2

## 0.5.1

### Patch Changes

- [#508](https://github.com/ofri-peretz/burgee/pull/508) [`1aae1e2`](https://github.com/ofri-peretz/burgee/commit/1aae1e2186ce88421067df5317795773419e53d0) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `<package> --help` and `--version` answer instead of crashing. The bin took its first argument as the plugin file to import, so `roundel --help` failed with `Cannot find module '…/--help'` and exit 1. `-h`/`--help` now print usage and exit 0, `-V`/`--version` print the version and exit 0, and any other flag where the plugin file belongs is a usage error, exit 2.
- Updated dependencies [[`1aae1e2`](https://github.com/ofri-peretz/burgee/commit/1aae1e2186ce88421067df5317795773419e53d0)]:
  - closeout@0.5.1
  - linegauge@0.5.1

## 0.5.0

### Minor Changes

- [#507](https://github.com/ofri-peretz/burgee/pull/507) [`b8e97dc`](https://github.com/ofri-peretz/burgee/commit/b8e97dcb64772e413f0b6f9e17e063c73314d242) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Runs on Node 20 and 22, not just 24+: `engines.node` is now `^20.19.0 || >=22.13.0`. Those are the first releases where `require(esm)` loads without a warning, so the CommonJS `require()` path keeps working. Every package's test suite runs on exactly 20.19.0 and 22.13.0, on Linux, macOS and Windows. caique's prompts no longer call `Promise.withResolvers`, which Node 20 doesn't have.

### Patch Changes

- [#505](https://github.com/ofri-peretz/burgee/pull/505) [`9800b43`](https://github.com/ofri-peretz/burgee/commit/9800b43d9c74a49dfb66d04a40fd0d1c48892e20) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Docs: the Benchmarks section's weight ceiling is re-measured against a fresh install of each incumbent's latest release (cosmiconfig 10.0.1, slice-ansi 9.0.1, which 7.0.0, dotenv 18.0.3, …) instead of the copies hoisted in this workspace, and names incumbents that were measured but left out of the ceiling as exactly that.
- Updated dependencies [[`9800b43`](https://github.com/ofri-peretz/burgee/commit/9800b43d9c74a49dfb66d04a40fd0d1c48892e20), [`b8e97dc`](https://github.com/ofri-peretz/burgee/commit/b8e97dcb64772e413f0b6f9e17e063c73314d242)]:
  - closeout@0.5.0
  - linegauge@0.5.0

## 0.4.3

### Patch Changes

- [#494](https://github.com/ofri-peretz/burgee/pull/494) [`f7f6d4b`](https://github.com/ofri-peretz/burgee/commit/f7f6d4b8e8f9d9c7010bd4c81fda4b4d106fc9f0) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Each package's `homepage` and README docs link now point at its own documentation site, `https://<package>.interlace.tools`, instead of a page on burgee's site. The old `burgee.interlace.tools/docs/packages/<package>` URLs answer with a 301 to the new host, so nothing already linked breaks. closeout's README override example also resolves to the current release again (`npm:closeout@^0.4`; the 0.4.0 release left it at `^0.3`).
- Updated dependencies [[`f7f6d4b`](https://github.com/ofri-peretz/burgee/commit/f7f6d4b8e8f9d9c7010bd4c81fda4b4d106fc9f0)]:
  - linegauge@0.4.4
  - closeout@0.4.1

## 0.4.2

### Patch Changes

- Updated dependencies [[`69563d1`](https://github.com/ofri-peretz/burgee/commit/69563d1fb14d9a4b29364446bae2fc48d86f6103), [`2dc573f`](https://github.com/ofri-peretz/burgee/commit/2dc573f884e7a4cc46829cd8f2c949a17f07710c)]:
  - closeout@0.4.0
  - linegauge@0.4.3

## 0.4.1

### Patch Changes

- [#454](https://github.com/ofri-peretz/burgee/pull/454) [`b4584e7`](https://github.com/ofri-peretz/burgee/commit/b4584e719bc0064b294aab5ea6da1c11f698f0e9) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every package's npm `homepage` now points at its page on the docs site, `https://burgee.interlace.tools/docs/packages/<name>`, and each README links it under the header. The keywords add what people and models search for: `burgee` gains `cli-framework`, `argument-parser`, `subcommands`, `json-schema`, `mcp-server`, `model-context-protocol`, `ai-agent`, `llm`, `shell-completion`, `typescript`, `zero-dependency`, `commander-alternative` and `yargs-alternative`; the other eight gain `agent`, `ai-agent`, `non-tty`, `json` and `zero-dependency` where the package does that — `zero-dependency` only on the six that install nothing at all.

  `burgee`'s README gains a short FAQ (commander alternative, agent use, MCP, dependencies) and states the compatibility counts the oracle holds — 1,360 / 1,360 of commander's tests and 804 / 804 of yargs' — where it had said 1,215 and 1,185. `caique`'s README no longer calls a released package pre-release.

- [#442](https://github.com/ofri-peretz/burgee/pull/442) [`bdaf364`](https://github.com/ofri-peretz/burgee/commit/bdaf364f81564c1700cf1adec18f927afe6c60c9) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every package now lists `plugin`, `plugins` and `extensible` in its npm keywords, because every package takes plugins through one shared contract.

  A plugin is a plain object, validated against the `schema.json` that ships in every package, and checked with the package's own `check` command. Each package reads its own key and ignores the rest, so one object can extend any subset of the family. The [plugins page](https://github.com/ofri-peretz/burgee/blob/main/apps/docs/content/docs/plugins.mdx) has a nine-layer example that every package's `check` accepts in CI.

- [#435](https://github.com/ofri-peretz/burgee/pull/435) [`7888524`](https://github.com/ofri-peretz/burgee/commit/78885245eb292cd4a40541fe09382a198c9c45cf) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `schema.json` now describes every plugin host in the family.

  The one schema each package ships as its plugin contract used to cover only four hosts: roundel's `tokens`, flagstaff's `glyphs`, `spinners`, `borders` and `components`, paratext's `capabilities`, and linegauge's `widths`. Five hosts validated their keys in their own code, but the file an author (or a model) writes against said nothing about them. It now describes all of them:

  - bellpull `resolvers`, including the absolute-path rule on `paths`
  - caique `widgets`
  - closeout `handlers`, including the phases a plugin may use
  - seniority `sources`, including the rank bounds
  - burgee `commands`, `hooks` and `enforce`

  Where the schema can express a rule, it gives the same verdict as the host's own validator, and a test holds the two together. Function-valued fields (`static`, `run`, `read`, `handler`) are described and required, but not typed, because JSON Schema can't say "function".

  **flagstaff** now validates a plugin against only its own keys, not the whole family schema. It no longer refuses a plugin over another host's key, which lets one plugin object contribute to several hosts. Its entry points are also 4.7–5.9 KB lighter for it.

- [#445](https://github.com/ofri-peretz/burgee/pull/445) [`dac303e`](https://github.com/ofri-peretz/burgee/commit/dac303e944e889ac4175ac38c94e4ca0f0ca5358) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every package now declares `sideEffects` truthfully, so bundlers can drop what you don't import.

  Six packages declared nothing, so no bundler could drop any of their modules. A named import from the root now bundles to the same bytes as the same import from its subpath:

  | import                                |  before |   after |
  | :------------------------------------ | ------: | ------: |
  | `import { explain } from 'seniority'` | 2,939 B | 1,067 B |
  | `import { decide } from 'caique'`     | 1,235 B |   734 B |
  | `import { strip } from 'linegauge'`   | 1,102 B |   940 B |
  | `import { once } from 'closeout'`     |   353 B |   235 B |

  flagstaff and roundel used to declare `false`, but each ships a `check` command whose file runs when loaded. Each now lists that file, which is the true statement. paratext also lists the two modules that register its built-in capabilities when they load.

- [#457](https://github.com/ofri-peretz/burgee/pull/457) [`44edb2f`](https://github.com/ofri-peretz/burgee/commit/44edb2f6f03a36f1b6773105867f41c899ffb6cd) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - flagstaff's npm description no longer says "Zero dependencies" (it takes four, all in-family); caique's README badge names both of its dependencies.
- Updated dependencies [[`b4584e7`](https://github.com/ofri-peretz/burgee/commit/b4584e719bc0064b294aab5ea6da1c11f698f0e9), [`bdaf364`](https://github.com/ofri-peretz/burgee/commit/bdaf364f81564c1700cf1adec18f927afe6c60c9), [`7888524`](https://github.com/ofri-peretz/burgee/commit/78885245eb292cd4a40541fe09382a198c9c45cf), [`dac303e`](https://github.com/ofri-peretz/burgee/commit/dac303e944e889ac4175ac38c94e4ca0f0ca5358)]:
  - closeout@0.3.1
  - linegauge@0.4.1

## 0.4.0

### Minor Changes

- [#421](https://github.com/ofri-peretz/burgee/pull/421) [`db3c59e`](https://github.com/ofri-peretz/burgee/commit/db3c59e3dcd373c7e6e4a057715adb173766523f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every plugin host has a `check` command.

  ```bash
  npx linegauge check ./my-widths.mjs
  npx burgee check ./my-plugin.mjs --json
  ```

  PRINCIPLES 7 asks three things of an extension surface: the plugin is data validated against one
  published schema, there is a **`check` command that shows it every way it can be seen**, and the
  bar is measured. The first was built in all nine hosts; the second existed in `flagstaff` alone.
  So an author writing a plugin for any other host found out what it did by shipping it into a
  program — and a surface nobody can check is a surface nobody outside this repository can write
  against.

  Each command validates, registers, and shows what the host does with the plugin, in the host's own
  terms: linegauge measures each code point **before and after** the override, paratext shows a
  capability's `encode` **and** its `fallback`, roundel each token and what it replaced, caique each
  widget's static projection rendered with its own sample. burgee's returns a **document** rather
  than printing one, so `burgee check --json` is the form an agent that just wrote a plugin reads.

  They share one contract with the author, held identically across all nine:

  - a readable report, contribution by contribution, with **`ok` as the last line**;
  - a refusal with a code from the family's vocabulary and a `fix`, exit 1;
  - **`E_NO_CONTRIBUTION`** for a plugin that contributes nothing to this host — the schema allows
    unknown keys so one object registers everywhere, which makes a misspelled key silent, and this
    is how that typo tells on itself;
  - exit 2 with no file.

  Each host also gains an eval case measuring the one-turn claim, proved to discriminate before it
  was committed: green against a correct plugin, red against the same plugin with one field broken.

### Patch Changes

- [#430](https://github.com/ofri-peretz/burgee/pull/430) [`4d1b2b3`](https://github.com/ofri-peretz/burgee/commit/4d1b2b399cff354864d1e2e843a19fde80ef1f30) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `check` now reports every refusal with its code and its fix, wherever it was raised.

  Some plugin files register themselves on import: they call `register()` at the top of the module and export the result. Until now, when such a file was refused, the error was thrown inside `check`'s `import()`, before the only `try` that turns a `PluginError` into `E_PLUGIN_SCHEMA: …` plus a `fix:` line. The author got the bare message on stderr, with no code and no fix. Now the whole of `check` runs inside that one handler, so every refusal comes out the same way on every host.

- Updated dependencies [[`4d1b2b3`](https://github.com/ofri-peretz/burgee/commit/4d1b2b399cff354864d1e2e843a19fde80ef1f30), [`db3c59e`](https://github.com/ofri-peretz/burgee/commit/db3c59e3dcd373c7e6e4a057715adb173766523f), [`db3c59e`](https://github.com/ofri-peretz/burgee/commit/db3c59e3dcd373c7e6e4a057715adb173766523f)]:
  - closeout@0.3.0
  - linegauge@0.4.0

## 0.3.1

### Patch Changes

- [#398](https://github.com/ofri-peretz/burgee/pull/398) [`ee35904`](https://github.com/ofri-peretz/burgee/commit/ee35904e987a0133f2c0b51371227f840e0fd677) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A `__proto__` key in a caller's corpus stays a style.

  `fromCliSpinners` and `fromCliBoxes` built their maps by assigning `map[key] = value` over
  the caller's JSON. JSON can carry the key `__proto__`, and that assignment hands it to the
  prototype setter rather than defining a property: the entry vanished from the plugin _and_
  whatever it held became the fallback that every other `lookupSpinner` and `lookupBorder`
  inherited. Both now build with `Object.fromEntries`, which defines an own property for
  every key, and the returned map keeps `Object.prototype`.

  The registry's `deepFrozen` copy and caique's prompt binding write the same shape from a
  loop they cannot turn into an expression, and use `Object.defineProperty` instead.

  `flagstaff/import` is 80 bytes lighter for it — 838 B to 758 B — because two loops became
  two expressions.

## 0.3.0

### Minor Changes

- [#381](https://github.com/ofri-peretz/burgee/pull/381) [`8104eb9`](https://github.com/ofri-peretz/burgee/commit/8104eb9fa9bfdcb58ad9df4e9e9b1e42f7b86907) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/inquirer` and `caique/clack` — two drop-in subpaths, and the first measured numbers
  either incumbent has given caique.

  `caique/inquirer` is `@inquirer/core`'s surface over `node:readline` and `node:async_hooks`:
  `createPrompt`, `useState`, `useEffect`, `useMemo`, `useRef`, `useKeypress`, `usePrefix`,
  `makeTheme`, `Separator`, the eight key predicates and the five error classes. Graded
  **41 / 41, 100.0%** against `@inquirer/core` 12.0.3's own suite, up from 0 / 41 — a suite
  that renders through a headless xterm and asserts the screen, so what passed is the prompt
  loop rather than a drawing. `usePagination` is not implemented and is named as a gap in
  `.sdlc/intents/caique/design.md` rather than shipped ungraded.

  `caique/clack` is `limitOptions`, which is the part of `@clack/prompts` that is a rule
  rather than a drawing. Graded **14 / 17, 82.4%**, up from 0 / 606 — and the denominator
  moved for a reason published in full on the compatibility page: 289 of that suite's 444
  assertions are `toMatchSnapshot()` across 17 of its 19 files, and those seventeen are
  subtracted as a declared subset, one named entry each. The three that remain unpassed are
  all of `guide.test.ts` and are a ceiling, not a shortfall: two want clack's twelve prompts
  drawn frame for frame, and the third asserts we read `updateSettings` out of `@clack/core`'s
  own module state, which a package with no external dependencies cannot see.

  Both subpaths reach `linegauge/wrap`, and `caique/inquirer` also reaches
  `closeout/exit-hook` — both published from this repository, both declared, both budgeted in
  `weight.test.ts`. The package root is unchanged: nothing in either façade is reachable from
  `caique` itself.

### Patch Changes

- [#373](https://github.com/ofri-peretz/burgee/pull/373) [`a1f1d40`](https://github.com/ofri-peretz/burgee/commit/a1f1d40b7d1e7244f3a180943b641bb3b491d256) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Stage 2's artifact is now `spec.md`, the name Anthropic's AI-Native SDLC playbook gives it, so the source comments and README sections that cite a package's own design document point at `spec.md` rather than `design.md`.

  No behaviour changes. The published tarballs do move, by two bytes per surviving reference — `design.md` is nine characters and `spec.md` is seven — so the four packages carrying a weight band were re-measured against it: linegauge 83,538 to 83,536; paratext 66,343 to 66,341; closeout 84,455 to 84,453; bellpull 86,113 to 86,107.

- Updated dependencies [[`a1f1d40`](https://github.com/ofri-peretz/burgee/commit/a1f1d40b7d1e7244f3a180943b641bb3b491d256)]:
  - closeout@0.2.1
  - linegauge@0.3.1

## 0.2.0

### Minor Changes

- [#294](https://github.com/ofri-peretz/burgee/pull/294) [`3f92a60`](https://github.com/ofri-peretz/burgee/commit/3f92a6099b1b8d5d476c64405ca963d40bf9af45) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/plugin` — a plugin may now ship a prompt kind caique does not have. `register({ widgets })` keeps the `widgets` key and ignores every other layer's, so the same plugin object works on any subset of the family that is installed (`plugin-contract` R1, R5). A widget is the same shape a flagstaff component is — `{ static, frame?, sample? }` — and one without `static` is refused with `E_NO_STATIC_PROJECTION`, the same code and the same fix shape.

  `PromptKind` is an open union (`… | (string & {})`). It was closed, which made a plugin's seventh kind a type error and would have turned hosting `widgets` into a breaking change written as an additive one; the six literals stay in an editor's completion list, which a bare `string` would have thrown away.

  Because the union is open, a kind nobody registered no longer falls through to a text prompt — `projectionOf()` refuses it with `E_UNKNOWN_KIND`, and the message names the kinds that _are_ registered so the reader sees the typo rather than a text prompt where their widget should have been. The six built-ins are still drawn by caique and a plugin may not replace them: `password` guarantees that nothing writes back what it read, and a third party able to override it could defeat that from a config file.

  Also ships `caique/schema.json`, byte-identical to flagstaff's and roundel's (R2) — the specifier caique's own `E_PLUGIN_SCHEMA` fix names, so following the advice resolves.

### Patch Changes

- [#326](https://github.com/ofri-peretz/burgee/pull/326) [`88f7ba6`](https://github.com/ofri-peretz/burgee/commit/88f7ba65e3a79ed20bf7c5bc4feae8b87684122b) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A `Runtime` seam on caique (PLAN 4.3, Y9).

  `src/runtime.ts` declares the slice of the world caique reads — `env`, `stdin`, `stdout` and
  the two `isTTY` flags — and `processRuntime()`, the one function in the package that names
  `process`. It is a function and not a constant, for the reason paratext's is: a runtime built
  at import freezes the environment as it was when the module graph loaded, which is before a
  test can say what it wants the world to look like.

  `createIo()` now takes no argument and builds over the real process, so a program gets the
  terminal it was started in without naming `process` itself; `streamsOf(runtime)` is the
  mapping for callers that already hold one. `decide()` is unchanged and still takes the
  narrower pair it reads, which is what the root export's `Runtime` continues to name.

  `runtime.test.ts` asserts the seam rather than documenting it: `runtime.ts` is the only
  non-test source in the package that reads the process, and `processRuntime()` returns two
  different answers across a change to the environment made after the import.

- [#332](https://github.com/ofri-peretz/burgee/pull/332) [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Restore the cursor when a prompt is killed, by taking the job from `closeout`.

  `raw.ts` hid the cursor and put it back on one path: the keypress loop, which sees Ctrl-C
  because raw mode delivers it as a byte rather than a signal. A `SIGINT` from a parent
  process, a `SIGTERM`, a crash or a `process.exit()` elsewhere in the program never reached
  that loop, and left the cursor invisible in the user's shell until they typed `reset`.
  Measured against the built `dist/raw.js`: hide 1, show 0, for `SIGINT`, `SIGTERM` and
  `SIGHUP` alike.

  `askList()` now hides through `closeout.hideCursor()`, which registers the restore in the
  same call, with `closeout/exit-hook` running it on the paths a keypress loop cannot see.
  The two escape sequences come from `closeout/cursor` as well, so caique no longer carries
  the family's third copy of them. The bytes on the wire are unchanged for a prompt that
  ends normally, and a prompt that ended unregisters, so exit writes nothing twice.

  caique therefore installs one package, `closeout`, which this repository publishes and
  which sits in the foundation tier below it. Nothing outside this repository is installed.

- [#339](https://github.com/ofri-peretz/burgee/pull/339) [`f295630`](https://github.com/ofri-peretz/burgee/commit/f2956301d5f9dcbcac0b001b00ebaf0315891fac) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `schema.json` constrains token names, because it was promising something no host honours.

  `tokens` was described as any name to a `#rrggbb` colour. `roundel`'s `validate()` accepts
  ten semantic names — `error`, `warn`, `ok`, `hint`, `muted`, `command`, `flag`, `value`,
  `heading`, `ground` — and throws on everything else. So a plugin author doing exactly what
  their own `E_PLUGIN_SCHEMA` error tells them, comparing their object against
  `roundel/schema.json`, got a green from the schema and `"accent" is not a token` from
  `register()`. Measured 2026-09-16 with `{ accent: '#336699' }`.

  The schema now carries `propertyNames.enum`, and `scripts/plugin-contract-lock.test.ts`
  pins the enum and the runtime set to each other from both sides, so neither can grow a
  name the other does not know.

  Every host ships a byte-identical copy of this file (`plugin-schema-lock.test.ts` asserts
  it), which is why nine packages are listed. Only the key `roundel` owns is constrained:
  describing `widgets`, `handlers`, `sources`, `resolvers` or `commands` in a file all eight
  hosts share is what made _flagstaff_ start validating caique's key last time
  (`PluginError: plugin.widgets.later: expected object, got boolean`), and those stay in
  `plugin-schema-lock`'s `UNDESCRIBED` list with that reason.

  `linegauge` is in the list for a different change: `ceilings.json`'s R9 block now records
  the bar as D1's tree-inclusive ceiling — 83,538 against 170,342, a ratio of 0.4904 — and
  keeps the superseded `get-east-asian-width` bar beside it with the count of entries that
  cleared it.

- Updated dependencies [[`c8acb28`](https://github.com/ofri-peretz/burgee/commit/c8acb2848714a1cbe3e26a2f9895d7498fb4f096), [`fc640dd`](https://github.com/ofri-peretz/burgee/commit/fc640ddec11255c12d1e0948c5b8e99cc3f3263b), [`3f92a60`](https://github.com/ofri-peretz/burgee/commit/3f92a6099b1b8d5d476c64405ca963d40bf9af45), [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328), [`f295630`](https://github.com/ofri-peretz/burgee/commit/f2956301d5f9dcbcac0b001b00ebaf0315891fac)]:
  - closeout@0.2.0

## 0.1.1

### Patch Changes

- [#92](https://github.com/ofri-peretz/burgee/pull/92) [`24e025d`](https://github.com/ofri-peretz/burgee/commit/24e025d267ee078bf02af9706faa7574b0679942) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Lock caique's weight, per subpath, against clack.

  caique was the last published package in the family without a `weight.test.ts` — so the one
  package that talks to a person, and to an agent, was the one making an unmeasured claim.

  **The whole package is 25,627 B and reaches no package at all, against `@clack/prompts`
  1.8.0's 101,684 B across six.** Deciding _not_ to ask — the case an agent hits — costs
  4,986 B and never loads the machinery of asking.

  Every entry now declares what it may import (nothing), what it may weigh, and what it must
  never reach; and an entry cannot be added without a budget.

## 0.1.0

### Minor Changes

- [#71](https://github.com/ofri-peretz/burgee/pull/71) [`e204772`](https://github.com/ofri-peretz/burgee/commit/e204772ce0647b3158994e57dc48828163f47488) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Add `caique/raw`: arrow-key `select` and `multiselect` on a terminal that can take raw mode.

  `askList()` draws a moving highlight and repaints in place, and answers the same question
  `ask()` does with the same value — line mode stays the floor, this is decoration on top,
  and the suite proves the two agree by running one spec through both. `keyOf()` reads a
  keypress, `canRender()` says whether a runtime can take raw mode, and `renderList()` is one
  frame so the drawing is asserted rather than screenshotted.

  `Ctrl-C` cancels — in raw mode it arrives as a byte, not a signal — and the terminal is
  restored (raw mode off, cursor shown) whatever the answer.

  No dependency on flagstaff: a prompt has no spinner, and the repaint it needs is three
  escape sequences.

### Patch Changes

- [#66](https://github.com/ofri-peretz/burgee/pull/66) [`b43e1d3`](https://github.com/ofri-peretz/burgee/commit/b43e1d3ccd62aad40b295cf4151aaff526d24acb) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `ask()` — the six prompt kinds in line mode, which is also the accessible rendering rather than a second implementation of it. A stream that ends is a cancellation, not an empty answer; invalid input is re-asked a bounded five times, never forever; `projection(spec)` gives the question without the conversation.

- [#66](https://github.com/ofri-peretz/burgee/pull/66) [`b43e1d3`](https://github.com/ofri-peretz/burgee/commit/b43e1d3ccd62aad40b295cf4151aaff526d24acb) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `resolvePrompts()` — the pass a framework calls from its `preAction` hook: walks a command's options in declaration order, asks only what has to be asked, and stops at the first refusal. One host-agnostic binding rather than one per host, so nothing in caique imports burgee.

- [#66](https://github.com/ofri-peretz/burgee/pull/66) [`b43e1d3`](https://github.com/ofri-peretz/burgee/commit/b43e1d3ccd62aad40b295cf4151aaff526d24acb) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `decide()` — the pure rule that decides whether a person can be asked at all: a value from any source wins, `--json` never prompts, `--yes` answers a confirm and only a confirm, and no terminal means an error naming the flag rather than a wait. All 256 combinations the design names are enumerated in the suite, not sampled.

- [#69](https://github.com/ofri-peretz/burgee/pull/69) [`2da5883`](https://github.com/ofri-peretz/burgee/commit/2da5883d512705c370c2da1eb07efdfcfc869c29) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `createIo()` — a reader and writer over real streams, so `ask()` can be used by a program and not only by a test. A `password` prompt is not echoed, and the muting lives in the one layer that knows what echo is.

---

# Coming from clack

> A clack (@clack/prompts) alternative with two ways across: caique/clack, clack's prompts under clack's names on caique's own engine, graded by clack's own suite; or caique's flag-first prompts, where a non-TTY caller gets an error naming the flag instead of a hang.

Source: https://caique.interlace.tools/docs/coming-from/clack

**caique** is a **clack alternative** built on one rule: a prompt is a flag first. There are
two ways across, and you can use both in one program:

1. **Change the import.** `caique/clack` exports `@clack/prompts`' prompts, writers, glyphs
   and settings under clack's own names and call signatures, built on caique's keypress loop
   with no dependency outside the burgee family. Your prompts keep working.
2. **Move a prompt to a flag.** caique's own API takes a prompt as a spec attached to a flag,
   so an agent answers it on the command line and a non-TTY run fails naming the flag instead
   of waiting. That is a rewrite, one prompt at a time, and it is what the rest of caique is for.

## Change the import

```js
// before
import { cancel, confirm, group, intro, isCancel, outro, select, spinner, text } from '@clack/prompts';
// after
import { cancel, confirm, group, intro, isCancel, outro, select, spinner, text } from 'caique/clack';
```

| clack (`@clack/prompts`) | `caique/clack` |
| :-- | :-- |
| `text`, `password`, `confirm`, `multiline`, `date`, `path` | the same, same options and answers |
| `select`, `selectKey`, `multiselect`, `groupMultiselect` | the same |
| `autocomplete`, `autocompleteMultiselect` | the same |
| `intro`, `outro`, `cancel`, `note`, `log`, `stream` | the same |
| `spinner`, `tasks`, `group` | the same — the spinner animates only on a terminal outside CI, and prints each message once anywhere else |
| `isCancel`, `CANCEL_SYMBOL`, `limitOptions` | the same |
| `settings`, `updateSettings` | caique's own: they govern `caique/clack`'s prompts, not `@clack/core`'s |
| `S_*`, `symbol`, `symbolBar`, `unicode`, `unicodeOr`, `isTTY`, `isCI`, `formatInstructionFooter`, `SELECT_INSTRUCTIONS`, `MULTISELECT_INSTRUCTIONS` | the same |
| `box`, `progress`, `taskLog` | not built — no graded case reaches them |

**Two things differ, on purpose.** The frames are clack's layout — the guide, the state
glyph, the dimmed answer — and not its exact bytes, so a test of yours that snapshots
clack's output will see different escape sequences. And `updateSettings` must be imported
from `caique/clack`: one imported from `@clack/core` changes a package caique does not
depend on, and our prompts cannot see it.

## Is caique compatible with clack?

`caique/clack` is graded against `@clack/prompts`' own suite, vendored at 1.8.1 and unmodified
apart from the import specifier. 17 of its 19 files — 289 of its 444 assertions — are
snapshots of clack's exact frames and are subtracted by name; what is left grades behaviour:

| | passing | rate |
| :-- | --: | --: |
| `caique/clack` | 16 / 16 | 100.0% |
| `@clack/prompts` itself (control) | 16 / 16 | 100.0% |

From [Compatibility](https://burgee.interlace.tools/docs/compatibility), which `npm run compat:page` generates from the
oracle's last run; that page is the authority. The 16 are all of `limit-options.test.ts` and
two of `guide.test.ts`, which render all twelve prompts and check the guide with and without
`withGuide`. A third `guide.test.ts` case is subtracted by its exact title. It sets
`updateSettings({ withGuide: false })` from `@clack/core` and asserts our prompts obey it.
That is the case above, and it grades `@clack/core`'s state, not `@clack/prompts`. The
row is level, so `burgee migrate` rewrites `@clack/prompts` to `caique/clack`. It leaves on
clack a file that imports `box`, `progress` or `taskLog`. It never rewrites `@clack/core`, and
it refuses a clack file that also imports `@clack/core` (reason `sibling-state`) rather than
move its prompts away from the settings that file sets. The refusal's fix reads:
`import { updateSettings } from 'caique/clack' instead of '@clack/core', then re-run burgee migrate`.

## Move a prompt to a flag

| clack (`@clack/prompts`) | caique |
| :-- | :-- |
| `text`, `password`, `path` | `ask({ kind: 'text' \| 'password' \| 'path', message, initial, validate }, io)` from `caique/ask`. `password` is read without echo by `createIo()` from `caique/terminal` |
| `confirm` | `ask({ kind: 'confirm', message, initial }, io)`. With `--yes` passed to `decide()`, it is answered `true` without asking |
| `select`, `multiselect` | `ask({ kind: 'select' \| 'multiselect', message, choices: [{ value, label, hint }] }, io)` asks by number. `askList(spec, io, multi)` from `caique/raw` adds arrow keys where there is a terminal |
| `group` | `resolvePrompts({ options, values, runtime, flags, io })` from `caique/binding`, which asks in declaration order and stops at the first refusal |
| `isCancel` | check the result: `ask()` returns `{ ok: false, reason: 'cancelled' }`, and `resolvePrompts()` returns a `failure` with code `CANCELLED` |

### A `text` and a `confirm`, before and after

```js
// clack
import { cancel, confirm, isCancel, text } from '@clack/prompts';

const name = await text({ message: 'Project name?' });
if (isCancel(name)) { cancel('Cancelled.'); process.exit(0); }
const git = await confirm({ message: 'Initialise git?' });
if (isCancel(git)) { cancel('Cancelled.'); process.exit(0); }
```

```js
// caique
import { processRuntime } from 'caique';
import { resolvePrompts } from 'caique/binding';
import { createIo } from 'caique/terminal';

const io = createIo();
const { values, failure } = await resolvePrompts({
  options: {
    name: { required: true, prompt: { kind: 'text', message: 'Project name?' } },
    git: { required: true, prompt: { kind: 'confirm', message: 'Initialise git?', initial: true } },
  },
  values: supplied,              // what --name, --git, env and config already answered
  runtime: processRuntime(),
  flags: { json, yes },          // the run's --json and --yes
  io,
});
io.close();
if (failure) {
  console.error(`${failure.message}\n${failure.fix ?? ''}`);
  process.exit(failure.code === 'CANCELLED' ? 0 : 2);
}
```

The two questions are the same, but the second program can also be answered without a
person. An option `supplied` already answers is never asked. `--yes` answers the `confirm`.
With no terminal, or under `CI`, the first unanswered option comes back as a failure,
`--name is required when there is no terminal`, rather than a wait. One difference to carry
over deliberately: caique asks only for options marked `required`, unless the run passed
`--interactive`.

## What you gain over clack

A prompt that waits for a human who is not there is a hang, and a hung agent is a failed
task. caique's `decide()` rules on every prompt before anything is drawn:

- **An agent answers before it is asked.** A value from any source — flag, env, config —
  means the prompt is skipped.
- **`--json` never prompts.** A missing value is an error, `--name is required under
  --json`, with a fix naming the flag.
- **No terminal is never a prompt.** Without a terminal on stdin, or with `CI` set, the
  verdict is an error naming the flag and the fix, never a wait on stdin. `--interactive`
  cannot override that; it can only ask for more where a terminal exists.
- **Checked exhaustively.** All 256 combinations of value, kind, TTY, CI, `--json`, `--yes`,
  `--interactive` and required are generated and checked in `decide.test.ts`.
- **Line mode is the floor.** No raw mode, no cursor movement, no redraw, so the accessible
  rendering and the terminal rendering are the same bytes. A closed stdin is a
  cancellation, not an empty answer, and invalid input is re-asked five times, then given
  up.

`caique/clack` is 62,238 B against `@clack/prompts`' 101,684 B across six packages, and a
program that uses caique's own API never loads a byte of it; caique reaches no package
outside the burgee family.

## When to switch from clack

- Your CLI runs in CI, in a container or under an agent, and a prompt there must fail fast
  with the flag that fixes it — move those prompts to flags.
- You want off clack's dependency tree today without touching your prompts — change the
  import to `caique/clack`.
- Stay on clack if you snapshot its exact frames, or need `box`, `progress` or `taskLog`.

The rule, the widgets and the inquirer path are on [caique](/docs).

---

# Coming from inquirer

> An inquirer alternative for prompts that never hang: caique/inquirer carries @inquirer/core's surface, graded 46 / 46 by its own suite — and caique's prompts are flags first, so a non-TTY caller gets an error naming the flag instead of a hang.

Source: https://caique.interlace.tools/docs/coming-from/inquirer

**caique** is an **inquirer alternative** built on one rule: a prompt is a flag first. Its
drop-in path, `caique/inquirer`, carries `@inquirer/core`'s surface — the layer every
`@inquirer/prompts` prompt is built on — for CLIs that write their prompts against it.

## Migrate from inquirer in one import

```diff
- import { createPrompt, useState, useKeypress, isEnterKey } from '@inquirer/core';
+ import { createPrompt, useState, useKeypress, isEnterKey } from 'caique/inquirer';
```

The same render functions, hooks (`useState`, `useEffect`, `useRef`, `useMemo`,
`useKeypress`, `usePrefix`), `Separator`, theme helpers and error classes keep working.

**What is not covered.** The legacy `inquirer.prompt([...])` object API — the `inquirer`
package itself — is out of scope: its own maintainer moved off it, and its npm tarball ships
no tests to grade against. `@inquirer/core`'s `usePagination` is not implemented yet and is
named as a gap in caique's spec.

## Is caique compatible with inquirer?

Graded against `@inquirer/core`, where the prompt loop — the keypress state machine both
inquirer façades sit on — is actually tested. Its suite, vendored at 12.0.6 and unmodified
apart from the import specifier, runs against `caique/inquirer` beside a control that runs it
against the real package:

| | passing | rate |
| :-- | --: | --: |
| `caique/inquirer` | 46 / 46 | 100.0% |
| `@inquirer/core` itself (control) | 46 / 46 | 100.0% |

From [Compatibility](https://burgee.interlace.tools/docs/compatibility), which `npm run compat:page` generates from the
oracle's last run; that page is the authority. There is **no graded row for the legacy
`inquirer` package**, for the reason above. The 46 grade the loop, not the drawing.

## What you gain over inquirer

A prompt that waits for a human who is not there is a hang, and a hung agent is a failed
task. caique's own API — `caique/decide`, `caique/ask`, `caique/binding` — declares each
prompt as an option first:

- **An agent answers before it is asked.** A caller who passes the flag is never prompted.
- **No terminal is never a prompt.** With nobody to ask, `decide()` returns an error naming
  the flag and the fix — `--output-dir is required when there is no terminal` — rather than
  waiting on stdin.
- **Checked exhaustively.** All 256 combinations of value, kind, TTY, CI, `--json`, `--yes`,
  `--interactive` and required are generated and checked in `decide.test.ts`.
- **Line mode is the floor.** No raw mode, no cursor movement, no redraw — so the accessible
  rendering and the terminal rendering are the same bytes. A closed stdin is a cancellation,
  not an empty answer.

`caique/inquirer` is the door; the flags-first API is where those properties live.

## When to switch from inquirer

- Your CLI runs in CI, in a container or under an agent, and a prompt there must fail fast.
- You want every prompt answerable from the command line.

The rule, the widgets and the clack path are on [caique](/docs).

---

# Compatibility

> How caique's drop-ins are graded — @inquirer/core's own suite at 46 / 46, @inquirer/prompts' at 222 / 222, and @clack/prompts' behavioural cases at 16 / 16 — and the differences that remain.

Source: https://caique.interlace.tools/docs/drop-ins

`caique/inquirer` and `caique/clack` are graded, not described as compatible. Each is run
against its incumbent's **own test suite**, by
[compat-oracle](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/README.md),
in CI.

✓ yes · ◐ partial (what is missing is said) · ✗ no · — does not apply. Every cell links to its evidence: our test or grade, or the incumbent’s source at the version compat-oracle grades.

### Compatibility

| Capability | **caique** | inquirer-core | clack |
| :-- | :-- | :-- | :-- |
| **Passes @inquirer/core's own test suite** — `caique/inquirer` — `createPrompt`, the hooks and the keypress helpers — is graded by @inquirer/core 12.0.3's own tests, unedited, rendered through a headless terminal. | [✓ 46 / 46 of its own tests](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/baseline/inquirer-core.json) | [✓ its own suite, the control run](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/vendor/inquirer-core/packages/core/core.vitest.ts) | [— a different API](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/vendor/clack/packages/prompts/test/limit-options.test.ts) |
| **Passes clack's own test suite** — `caique/clack` is graded by the behavioural cases of @clack/prompts 1.8.1's own suite, with the snapshots of clack's exact frames subtracted by name, and one case that grades @clack/core's module state rather than @clack/prompts (D-20260930-caique-clack-core-exclusion). | [✓ 16 / 16 of its own tests](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/baseline/clack.json) | [— a different API](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/vendor/inquirer-core/packages/core/core.vitest.ts) | [✓ its own suite, the control run](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/vendor/clack/packages/prompts/test/limit-options.test.ts) |

The counts are compat-oracle's baselines, the pass count each drop-in is held to. The family's
[compatibility page](https://burgee.interlace.tools/docs/compatibility) is generated from the
oracle's last run and is the authority for the current figures.

| incumbent | graded version | drop-in | cases |
| :-- | :-- | :-- | --: |
| `@inquirer/core` | 12.0.6 | `caique/inquirer` | 46 / 46 |
| `@inquirer/prompts` | 8.7.5 | `caique/inquirer/prompts` | 222 / 222 |
| `@clack/prompts` | 1.8.1 | `caique/clack` | 16 / 16 |

## How a suite is graded

1. The incumbent's repository is cloned at the release tag and its test directory copied into
   `packages/compat-oracle/vendor/`. `PROVENANCE` names the tag, the commit and the command that
   reproduces it.
2. The only edit is the import that reaches the library, rewritten to a shim generated per run.
   Assertions and fixtures are upstream's, byte for byte.
3. A **control run** points the shim at the real incumbent first, which proves the harness and
   sets the total every rate is measured against.
4. The **target run** points the same shim at caique's path.

## `@inquirer/core`: the loop, not the drawing

`@inquirer/testing` renders through a headless terminal and asserts the screen, so the 41 grade
hooks keeping their place across re-renders, keypresses that stop the instant a prompt settles,
an effect cleanup that throws superseding the answer, and an aborted signal still restoring the
cursor — behaviour a second implementation can share. `usePagination` is not implemented, and
no case in the suite reaches it.

## `@clack/prompts`: 16 behavioural cases

289 of clack's 444 assertions are snapshots of clack's exact frames, in 17 of its 19 files.
Matching them frame for frame would make `caique/clack` clack, so they are subtracted by name,
as a declared subset. `caique/clack` passes all of `limit-options.test.ts` and the two
`guide.test.ts` cases that render all twelve prompts with and without the guide.

**One more case is subtracted, by its exact title.** It calls
`updateSettings({ withGuide: false })` **imported from `@clack/core`** and asserts the prompts
obey it. That is module-level state inside `@clack/core`, a package caique does not depend on
and cannot read, so the case grades `@clack/core` and not `@clack/prompts`. `caique/clack`
exports its own `updateSettings`, as `@clack/prompts` does, and its prompts obey that one. The
subtraction is published on the compatibility page. The row reads 16 / 16, level with clack's
own 16 / 16, so `burgee migrate` rewrites `@clack/prompts` to `caique/clack`. It leaves a file
that imports `box`, `progress` or `taskLog` on clack.

## Known differences

- **`caique/clack`'s frames are clack's layout, not its bytes.** A test of yours that snapshots
  clack's output will see different escape sequences.
- **`updateSettings` must come from `caique/clack`**, as above. `burgee migrate` does not
  rewrite `@clack/core`. It refuses a file that imports both `@clack/prompts` and `@clack/core`
  (reason `sibling-state`), with the fix: import `updateSettings` from `caique/clack`, then run it
  again. It reads one file at a time, so an `updateSettings` from `@clack/core` in a file with no
  clack prompts is not caught. Move that import yourself.
- **`caique/clack` does not build `box`, `progress` or `taskLog`**; no graded case reaches them.
- **`caique/inquirer` has no `usePagination`.**
- **The legacy `inquirer` package is not a drop-in**: its object API is out of scope, and
  `caique/inquirer` is `@inquirer/core`'s surface.

---

# FAQ

> Short answers about caique — why it refused, --yes, --interactive, CI, closed stdin, passwords, raw mode, the drop-ins and CommonJS — each with where to read more.

Source: https://caique.interlace.tools/docs/faq

## Why did it refuse instead of asking?

Because nobody was there to ask: stdin is not a terminal, `CI` is set, an agent is driving the
process, or the run passed
`--json`. The error names the flag to pass and quotes the question it would have asked
([Never hangs](/docs/guides/never-hangs)).

## How do I make it ask anyway?

Run it on a terminal. `--interactive` asks for optional values it would otherwise skip, but it
cannot conjure a person: with no terminal it still refuses, and says that `--interactive` needs
one.

## What does `--yes` answer?

Every `confirm`, with `true`, terminal or not. Nothing else: a `text` or a `select` has no
"yes" ([Confirmations in CI](/docs/recipes/confirm-in-ci)).

## My CI job has a terminal attached. Does it prompt?

No. `CI` set means nobody is there to type, whatever stdin is.

## An agent runs my CLI in a terminal. Does it prompt?

No. Under `CLAUDECODE`, `CURSOR_AGENT`, `CODEX_THREAD_ID`, `GEMINI_CLI` or `AI_AGENT` the
prompt is refused, naming the flag, even with a terminal on stdin: the agent has the terminal
but not a person. `FORCE_TTY=1` overrides it, for a caller that pipes answers on purpose.

## What happens when stdin closes mid-question?

The question is cancelled — `{ ok: false, reason: 'cancelled' }`, or a `CANCELLED` failure from
`resolvePrompts()` — and never read as an empty answer.

## Is a password ever echoed?

No. `createIo()` suppresses the echo for the one question by intercepting readline's output,
not by turning the terminal's echo off, so a process that dies mid-prompt does not leave the
terminal silent ([The terminal](/docs/guides/terminal)).

## I put the terminal in raw mode myself. Will a prompt take it away?

Not caique's own: `askList()` turns raw mode off only if it turned it on. clack and inquirer
turn it off when a prompt closes whatever it was before ([Why caique](/docs/why-caique)).

## Can I keep my clack or inquirer code?

Yes: `caique/clack` and `caique/inquirer` carry their APIs, graded by their own suites
([Compatibility](/docs/drop-ins)). Moving a prompt to a flag is what makes it answerable
without a person.

## Can I use it from CommonJS?

Yes, on Node 22.13+: every entry is ESM with a `default` condition, so
`require('caique')` loads it through `require(esm)`.

---

# Getting started

> Install caique, bind two prompts to flags, and see the same program ask a person on a terminal and refuse — naming the flag — when nobody is there.

Source: https://caique.interlace.tools/docs/getting-started

caique asks questions a CLI needs answered, with one rule first: **a prompt is a flag**. A
value that arrived any other way — a flag, an environment variable, a config file — is never
asked for, and when there is nobody at the terminal to ask, a missing value is an error that
names the flag to pass, never a prompt waiting for a person who is not there.

## Install

```bash
npm install caique
```

It is ESM with a `default` condition, so `require('caique')` also works from CommonJS on Node
22.13+. It depends on closeout, linegauge and paratext, all from this repository,
and on nothing else.

## A first program

`resolvePrompts()` takes the command's options — each may carry a prompt — and the values every
other source already resolved, and asks only what is still missing:

```js title="deploy.mjs"
import process from 'node:process';

import { processRuntime } from 'caique';
import { resolvePrompts } from 'caique/binding';
import { createIo } from 'caique/terminal';

const argv = process.argv.slice(2);
const supplied = {};
for (const arg of argv) {
  const [, name, value] = /^--([a-z-]+)=(.*)$/u.exec(arg) ?? [];
  if (name !== undefined) supplied[name] = value;
}

const io = createIo();
const { values, failure } = await resolvePrompts({
  options: {
    env: { required: true, prompt: { kind: 'select', message: 'Deploy to?', choices: [{ value: 'staging' }, { value: 'production' }] } },
    tag: { required: true, prompt: { kind: 'text', message: 'Which tag?' } },
  },
  values: supplied,
  runtime: processRuntime(),
  flags: { json: argv.includes('--json'), yes: argv.includes('--yes') },
  io,
});
io.close();

if (failure) {
  console.error(`${failure.message}\n  fix: ${failure.fix}`);
  process.exitCode = 2;
} else {
  console.log(`deploying ${values.tag} to ${values.env}`);
}
```

(A real CLI gets `supplied` from its argument parser; a CLI on
[burgee](https://burgee.interlace.tools/docs) gets this whole pass from its `preAction` hook.)

In a terminal, it asks both questions. With no terminal on stdin — an agent, a CI job, a
pipe — it asks nothing, and the first missing value is an error naming the flag:

```text title="node deploy.mjs" exit="2"
--env is required when there is no terminal
  fix: pass --env; it would have been asked as "Deploy to?"
```

```text title="node deploy.mjs --env=staging" exit="2"
--tag is required when there is no terminal
  fix: pass --tag; it would have been asked as "Which tag?"
```

```text title="node deploy.mjs --env=staging --tag=v1.2.0"
deploying v1.2.0 to staging
```

Every output block on this site is checked: `tests/examples.test.ts` writes each titled file,
runs the command in the block's title with nothing on stdin, and compares.

## The rule

`decide()` rules on every prompt before anything is drawn. First match wins:

| situation | verdict |
| :-- | :-- |
| a value came from any source | not asked |
| `--json` | an error naming the flag: a machine is reading |
| `--yes`, and the prompt is a `confirm` | answered `true`, even with no terminal |
| no terminal on stdin, `CI` set, or an agent (`CLAUDECODE` and the like) | an error naming the flag |
| `required`, or the run passed `--interactive` | asked |
| anything else | not asked |

[Never hangs](/docs/guides/never-hangs) has the rule in full, and why each row is where it is.

## Where next

- [Guides](/docs/guides/never-hangs): the rule, the six kinds of question, binding prompts to
  a CLI, the terminal, and widget plugins.
- [Why caique](/docs/why-caique): what it does that inquirer and clack do not, cell by cell,
  with the evidence.
- [Coming from inquirer](/docs/coming-from/inquirer) and
  [Coming from clack](/docs/coming-from/clack).
- [API reference](/docs/api): every export of every entry point.

---

# Asking

> ask() is the six kinds — text, confirm, select, multiselect, password and path — each a question written and a line read back, with no raw mode and no escape sequence: the accessible rendering is the only one.

Source: https://caique.interlace.tools/docs/guides/asking

`ask(spec, io)` from `caique/ask` asks one question and returns `{ ok: true, value }` or
`{ ok: false, reason: 'cancelled' }`. `io` is a reader of lines and a writer of text; on a real
terminal it is [`createIo()`](/docs/guides/terminal), and in the examples on this site it is a
scripted person:

```js title="scripted.mjs"
import process from 'node:process';

/**
 * A person, scripted: each answer is "typed" and echoed the way a terminal shows it — unless
 * the prompt asked for it hidden — and running out of answers is Ctrl-D.
 */
export function scripted(answers) {
  const lines = [...answers];
  return {
    reader: {
      async line({ hidden = false } = {}) {
        const line = lines.shift();
        process.stdout.write(line === undefined ? '^D\n' : `${hidden ? '' : line}\n`);
        return line;
      },
    },
    writer: { write: (text) => void process.stdout.write(text) },
  };
}
```

## A conversation

```js title="conversation.mjs"
import { ask } from 'caique/ask';

import { scripted } from './scripted.mjs';

const io = scripted(['', 'nope', '2', 'y']);

const name = await ask({ kind: 'text', message: 'Project name?', initial: 'my-cli' }, io);
const host = await ask({ kind: 'select', message: 'Which host?', choices: [{ value: 'ora' }, { value: 'log-update', hint: 'repaints in place' }] }, io);
const git = await ask({ kind: 'confirm', message: 'Initialise git?' }, io);
const more = await ask({ kind: 'text', message: 'Anything else?' }, io);

console.log(JSON.stringify([name, host, git, more]));
```

```text title="node conversation.mjs"
Project name? (my-cli) 
Which host?
  1) ora
  2) log-update — repaints in place
  enter a number (1-2): nope
  enter a number from 1 to 2
Which host?
  1) ora
  2) log-update — repaints in place
  enter a number (1-2): 2
Initialise git? (y/N) y
Anything else? ^D
[{"ok":true,"value":"my-cli"},{"ok":true,"value":"log-update"},{"ok":true,"value":true},{"ok":false,"reason":"cancelled"}]
```

- A blank line takes the `initial`.
- An answer that is not one is re-asked, saying why — five times, then it gives up, because a
  loop against a stream that keeps answering wrongly is the same hang wearing a hat.
- **A stream that ends is a cancellation, not an empty answer.** `Ctrl-D` and a closed pipe both
  mean nobody is going to type, and reading that as `''` is how a program writes to a path
  nobody chose.

## The six kinds

| kind | asks | answer |
| :-- | :-- | :-- |
| `text` | the message, with `initial` in parentheses | the line, or `initial` for a blank one |
| `confirm` | the message, `(y/N)` or `(Y/n)` | `true` or `false` |
| `select` | a numbered list, with hints | the chosen `value`; the number, the value or the label typed out all count |
| `multiselect` | a numbered list | the chosen values in list order; a blank line is none |
| `password` | the message | the line, read without echo by `createIo()` |
| `path` | the message | the line |

`validate(answer)` on a spec returns a string to reject an answer with that reason.

## Line mode is the floor

Every question is written and a line is read back: no raw mode, no cursor movement, no escape
sequence and no redraw (`ask.test.ts` asserts a `select` writes no escape and no carriage
return). That is not a fallback for poor terminals — it is the accessible rendering, and the
only one `ask()` has, so a screen reader gets the same bytes a terminal does. Arrow-key
selection sits on top of it where there is a terminal to take keys
([The terminal](/docs/guides/terminal#arrow-keys)).

## The question without the conversation

`projection(spec)` returns what `ask()` would write, without reading anything — for `--help`, a
docs gallery or a transcript in an issue.

```js title="projection.mjs"
import { projection } from 'caique/ask';

console.log(projection({ kind: 'multiselect', message: 'Which checks?', choices: [{ value: 'lint' }, { value: 'test', hint: 'slow' }] }));
```

```text title="node projection.mjs"
Which checks?
  1) lint
  2) test — slow
  enter numbers separated by commas, or blank for none:
```

---

# Binding prompts to a CLI

> resolvePrompts() is the pass a framework runs once flags, environment and config have had their turn: it asks in declaration order, only what is missing, and stops at the first refusal.

Source: https://caique.interlace.tools/docs/guides/binding

`resolvePrompts()` from `caique/binding` is the pass a CLI framework calls after every other
source of a value — flags, environment, config, defaults — has had its turn. A CLI on
[burgee](https://burgee.interlace.tools/docs) runs it from its `preAction` hook; any other
framework calls it with the same four things.

```js title="binding.mjs"
import { resolvePrompts } from 'caique/binding';

import { scripted } from './scripted.mjs';

const options = {
  name: { required: true, prompt: { kind: 'text', message: 'Project name?' } },
  force: { required: true, prompt: { kind: 'confirm', message: 'Overwrite?' } },
  template: { required: true, prompt: { kind: 'select', message: 'Template?', choices: [{ value: 'cli' }, { value: 'lib' }] } },
  description: { prompt: { kind: 'text', message: 'Description?' } },
};
const terminal = { env: {}, isTTY: { stdin: true, stdout: true } };

const asked = await resolvePrompts({ options, values: { name: 'demo' }, runtime: terminal, flags: { yes: true }, io: scripted(['2']) });
console.log(JSON.stringify(asked));

const agent = { env: {}, isTTY: { stdin: false, stdout: false } };
const refused = await resolvePrompts({ options, values: { name: 'demo' }, runtime: agent, flags: { yes: true }, io: scripted([]) });
console.log(JSON.stringify(refused));
```

```text title="node binding.mjs"
Template?
  1) cli
  2) lib
  enter a number (1-2): 2
{"values":{"name":"demo","force":true,"template":"lib"}}
{"values":{"name":"demo","force":true},"failure":{"option":"template","code":"USAGE","message":"--template is required when there is no terminal","fix":"pass --template; it would have been asked as \"Template?\""}}
```

On the terminal, `name` was supplied so it was not asked, `--yes` answered the `confirm`, the
`select` was asked, and the optional `description` was left alone. (`--yes` answers every
`confirm`, optional ones included.) For the agent, the same pass
refused at `template` — the first option it would have had to ask about.

## What it guarantees

- **Declaration order.** Options are asked in the order they were declared, which is the order
  the help lists them.
- **Only what has to be asked.** Every option goes through [`decide()`](/docs/guides/never-hangs)
  first.
- **The first refusal stops it.** A caller about to exit is better served by one actionable
  message than by six; `failure` is that one, with a `code` of `USAGE` or `CANCELLED`, a
  `message` and a `fix`.
- **A spec that cannot be drawn is a usage error** — a `select` with no choices is refused
  before anything is asked, rather than drawn as an empty list and waited on.
- **The input is not mutated.** `values` comes back as a new object with the answers written in.

## One binding, not one per framework

What the pass needs is a record of options, the values so far, a runtime and an `io`. None of
it is any framework's types, so `caique` imports none, and the same pass serves commander,
yargs, burgee or a hand-rolled parser.

## Wrapping a command: `promptFor`

`caique/prompt-for` puts that pass where it belongs, in front of a command's handler.
`promptFor(command, 'name', spec)` declares the prompt on the option or positional called `name`
and wraps the handler: before it runs, every declared prompt with no value is asked for, or
refused, and the handler never sees a missing value. `promptFor(command)` does the same for the
`prompt:` a command already declares.

```js title="greet.mjs"
import { promptFor } from 'caique/prompt-for';

const greet = promptFor(
  { arguments: [{ name: 'name' }], run: ({ args }) => `Hello, ${args.name}!` },
  'name',
  { kind: 'text', message: 'Who should I greet?' },
);

// What a framework hands its handler. burgee builds this context; any other framework can too.
const ctx = (over) => ({ options: {}, args: {}, positionals: [], env: process.env, interactive: false, json: false, ...over });

console.log(await greet.run(ctx({ args: { name: 'ada' }, positionals: ['ada'] })));
try {
  await greet.run(ctx());
} catch (refusal) {
  console.log(`${refusal.code}: ${refusal.message}`);
  console.log(`fix: ${refusal.fix}`);
}
```

```text title="node greet.mjs"
Hello, ada!
USAGE: <name> is required when there is no terminal
fix: pass <name>; it would have been asked as "Who should I greet?"
```

The refusal names the value the way it is passed: `<name>` for a positional, `--dry-run` for an
option keyed `dryRun`. On burgee it leaves with exit 2, and a cancelled question with exit 4.

- **Who is asked.** `ctx.interactive` is the host's answer — a terminal on stdin, no `CI`, no
  agent — and `ctx.json` is `true` under `--json` and in every `--mcp` tool call, where nobody is
  there to type.
- **Where.** On stdin, with the question on stderr, so it never lands in the data on stdout.
- **For how long.** The terminal is opened only to ask, handed to the host's exit path while it
  is open, and closed before the handler runs. Ctrl+C at the question cancels it and gives the
  terminal back out of raw mode.
- **What a program reading `--schema` sees.** Not the prompt: it is left out of the command's
  JSON, because a program is never asked. Declare prompts through `promptFor`, so this holds.

---

# Never hangs

> decide() is the rule: a supplied value is never asked for, --json, CI and agents never prompt, --yes answers a confirm, and with nobody on stdin a missing value is an error naming the flag.

Source: https://caique.interlace.tools/docs/guides/never-hangs

A prompt that waits for a person who is not there is a hang, and a hung agent is a failed
task. `decide()` from `caique/decide` rules on each prompt **before** anything is drawn, as a
pure function: a value, a prompt spec, the option's name, a runtime and the run's flags in, a
verdict out.

```js title="decisions.mjs"
import { decide } from 'caique/decide';

const spec = { kind: 'confirm', message: 'Overwrite the existing config?' };
const terminal = { env: {}, isTTY: { stdin: true } };
const pipe = { env: {}, isTTY: { stdin: false } };
const ci = { env: { CI: 'true' }, isTTY: { stdin: true } };
const agent = { env: { CLAUDECODE: '1' }, isTTY: { stdin: true } };

const cases = [
  ['a value was passed', { value: false, runtime: pipe }],
  ['a terminal, required', { value: undefined, runtime: terminal, required: true }],
  ['a terminal, optional', { value: undefined, runtime: terminal }],
  ['a terminal, optional, --interactive', { value: undefined, runtime: terminal, flags: { interactive: true } }],
  ['no terminal, required', { value: undefined, runtime: pipe, required: true }],
  ['CI on a terminal, required', { value: undefined, runtime: ci, required: true }],
  ['an agent on a terminal, required', { value: undefined, runtime: agent, required: true }],
  ['--json on a terminal', { value: undefined, runtime: terminal, required: true, flags: { json: true } }],
  ['--yes, no terminal', { value: undefined, runtime: pipe, required: true, flags: { yes: true } }],
];

for (const [name, input] of cases) {
  const { action, value, message } = decide({ spec, option: 'force', ...input });
  console.log(`${name.padEnd(36)} ${action}${value === undefined ? '' : ` ${value}`}${message === undefined ? '' : ` — ${message}`}`);
}
```

```text title="node decisions.mjs"
a value was passed                   skip
a terminal, required                 prompt
a terminal, optional                 skip
a terminal, optional, --interactive  prompt
no terminal, required                error — --force is required when there is no terminal
CI on a terminal, required           error — --force is required when nobody is there to answer
an agent on a terminal, required     error — --force is required when nobody is there to answer
--json on a terminal                 error — --force is required under --json
--yes, no terminal                   answer true
```

## Why each row is where it is

- **A value from any source is never asked for** — `false`, `0` and `''` included. Only
  "nothing was supplied" is not an answer.
- **`--json` comes before everything else**, `--yes` and `--interactive` included: they cannot
  make a machine type.
- **`--yes` answers a `confirm`, and only a `confirm`.** Nothing has to be typed, so it works
  with no terminal too. It never answers a `text` or a `select`, because there is no "yes" to
  a question with more than two answers.
- **No terminal on stdin, `CI` set, or an agent driving the process is nobody there.** An
  agent — `CLAUDECODE`, `CURSOR_AGENT`, `CODEX_THREAD_ID`, `GEMINI_CLI`, `AI_AGENT` — may well
  have a terminal; what it does not have is a person. This is roundel's
  [`interactive()`](https://roundel.interlace.tools/docs), and `FORCE_TTY=1`
  is its one override. Then a missing value is an error
  whose `fix` names the flag and quotes the question it would have asked. `--interactive`
  cannot conjure a person, and the error says so when it was passed, rather than looking as if
  the flag was ignored.
- **Otherwise, only what is required is asked**, unless the run passed `--interactive`, which
  asks for optional values too.

`decide.test.ts` enumerates every one of the 256 combinations of value, kind, terminal, `CI`,
`--json`, `--yes`, `--interactive` and required, against the rule written a second time,
independently. The case that would be a bug report if it broke is named on its own: no
terminal and no value is never a prompt.

## The runtime

`decide()` reads `env` — `CI`, the agent variables, `FORCE_TTY` — and `isTTY.stdin` from the runtime it is handed, and never `process`.
`processRuntime()` from `caique` builds one from the real process; a test passes a literal.

---

# Widget plugins

> A plugin adds a prompt kind beyond the six as a widget with a required static projection; register() validates it, projectionOf() draws any kind, and npx caique check validates a plugin before it ships.

Source: https://caique.interlace.tools/docs/guides/plugins

caique hosts one plugin key, **`widgets`**: how to draw a prompt kind that is not one of the
six built-ins. A plugin is the family's one plain object, so the same file can carry roundel's
tokens or flagstaff's spinners, and caique keeps the key it reads and ignores the rest.

## Writing one

```js title="rating.mjs"
export default {
  name: 'rating',
  widgets: {
    rating: {
      static: (spec) => `${spec.message} (1-5)`,
      sample: { running: {}, done: {} },
    },
  },
};
```

A widget's **`static(spec)`** is required: it is what a pipe, an agent and a screen reader get,
the same surface `projection()` gives the six built-ins. `frame(t, spec)` is optional and
drives raw mode; `sample` is what `check` renders it with.

## Registering it

```js title="rating-app.mjs"
import { kinds, projectionOf, register } from 'caique/plugin';

import rating from './rating.mjs';

register(rating);
console.log(kinds().join(', '));
console.log(projectionOf({ kind: 'rating', message: 'How was the install?' }));
console.log(projectionOf({ kind: 'select', message: 'Which host?', choices: [{ value: 'ora' }, { value: 'boxen' }] }));
try {
  projectionOf({ kind: 'ratng', message: 'typo' });
} catch (error) {
  console.log(`${error.code}: ${error.message}`);
}
```

```text title="node rating-app.mjs"
text, confirm, select, multiselect, password, path, rating
How was the install? (1-5)
Which host?
  1) ora
  2) boxen
  enter a number (1-2):
E_UNKNOWN_KIND: no widget draws prompt kind "ratng" — registered kinds: rating
```

`projectionOf(spec)` draws any kind: the six are still caique's, anything else is a registered
widget's `static`. A kind nobody registered is a refusal naming what is registered, so a typo
shows as a typo rather than as a text prompt where a rating should have been.

- **Later wins**, like flat config, and `widgets()` reports who shadowed whom.
- **The six built-ins cannot be replaced**: a widget named `password` is refused, so a third
  party cannot swap the one prompt that must not echo.
- **A refused plugin is not registered** — validation is at the door.

## Refusals

A widget without `static` is refused with `E_NO_STATIC_PROJECTION`, the code flagstaff and
paratext use for the same rule, and with the fix. `npx caique check` shows it before the plugin
ships:

```text title="npx caique check rating.mjs"
rating — 1 widgets
  rating  static "preview (1-5)"
rating: ok
```

```js title="stars.mjs"
export default { name: 'stars', widgets: { stars: { frame: () => '*' } } };
```

```text title="npx caique check stars.mjs" exit="1"
E_NO_STATIC_PROJECTION: plugin "stars": widget "stars" has no static projection
  fix: add `static: (spec) => "…"` — it is what a pipe, an agent and a screen reader get
```

`npx caique check` loads the file without registering it and exits 0, 1 with the code and the
fix, or 2 on a usage error.

---

# The terminal

> createIo() reads lines from a real terminal and hides a password without turning echo off; askList() adds arrow keys where there is a terminal, and puts raw mode back exactly as it found it.

Source: https://caique.interlace.tools/docs/guides/terminal

Everything above this page is strings in and strings out. `caique/terminal` and `caique/raw`
are the two files that touch a real terminal.

## `createIo()`

```js
import { ask } from 'caique/ask';
import { createIo } from 'caique/terminal';

const io = createIo(); // the terminal the program was started in
const token = await ask({ kind: 'password', message: 'Token?' }, io);
io.close();
```

It reads lines through `node:readline`, so line editing, backspace and `Ctrl-D` behave as a
person expects, and it resolves `undefined` when the stream ends, which `ask()` reads as a
cancellation.

**A password is never echoed**, and the way it is hidden matters: the echo is suppressed by
intercepting the interface's own output for the duration of the one question, not by turning
the terminal's echo off — which would leave it off if the process died mid-prompt. Hiding is
per question: the next question echoes again. `terminal.test.ts` asserts that a plain read on
the same streams does echo, so the assertion that the password did not can fail.

## Arrow keys

`askList(spec, io)` from `caique/raw` draws a `select` or `multiselect` with a moving highlight
and repaints in place. It answers the same question `ask()` does and returns the same value,
so it is a swap, not a second implementation — the suite runs the same spec through both and
compares the answers.

```js
import { processRuntime } from 'caique';
import { ask } from 'caique/ask';
import { askList, canRender } from 'caique/raw';
import { createIo, streamsOf } from 'caique/terminal';

const rt = processRuntime();
const io = { ...createIo(streamsOf(rt)), keys: rt.stdin };
const spec = { kind: 'select', message: 'Which host?', choices: [{ value: 'ora' }, { value: 'chalk' }] };
const answer = canRender(io.keys) ? await askList(spec, io) : await ask(spec, io);
```

## The terminal as it was found

Raw mode and a hidden cursor are borrowed, and `caique/raw` gives both back:

- **Raw mode is turned off only if the prompt turned it on.** A program that already had its
  terminal in raw mode keeps it when the prompt ends (`raw.test.ts`, "leaves raw mode on for a
  caller that already had it").
- **The cursor is hidden once and shown again**, whatever the answer.
- **`Ctrl-C` cancels** — in raw mode it arrives as a byte, not a signal — and still restores the
  terminal.
- **`SIGINT` and `SIGTERM` mid-prompt** turn raw mode off and put the cursor back, and the
  process still ends: the undo is registered with [closeout](https://closeout.interlace.tools/docs),
  which runs it on the way out.
- **A frame wider than the terminal** is repainted in place: the repaint climbs every row the
  wrapped frame occupies, so there is one copy of the question on screen after every keypress.

---

# caique

> Prompts that are flags first: an agent passes the answer up front, and a non-TTY caller gets an error naming the flag, never a prompt that waits. No dependency outside the burgee family. Drop-in path for @inquirer/core.

Source: https://caique.interlace.tools/docs

**caique** asks a question only when someone can answer it. Every prompt is a flag first, so
an agent passes the answer before it is asked, and a non-TTY caller gets an error naming the
flag instead of a prompt that waits. **It never hangs.**

Drop-in for **@inquirer/core** and **@clack/prompts**: `npx burgee migrate` moves the imports
to `caique/inquirer` and `caique/clack`, each graded by its incumbent's own suite.

**1.0.** `decide()`, `ask()` and the `caique/inquirer` and `caique/clack` drop-in paths are a
semver contract, each path graded by its incumbent's own suite on the
[compatibility page](https://burgee.interlace.tools/docs/compatibility), level with the incumbent
at its latest release (D-20261007-caique-controlroom-1-0-evidence).

A **caique** (kah-EEK) is a small, loud, never-silent parrot — and this one always answers
back. It is also the light wooden boat of the Bosphorus and the Greek islands, the one that
runs between the ship and the shore carrying people and messages across the gap. Both are
true of this package: it is the go-between that carries a question from a program to whoever
is calling, human or agent, and brings the answer back. **It never hangs.**

## Install

```bash
npm install caique
pnpm add caique
yarn add caique
bun add caique
```

## Quick start

`decide()` — the rule that decides whether a person can be asked at all, and the reason
this package can promise it never hangs. It is pure: a value, a runtime slice and the run's
flags in, a verdict out.

```js
import { decide } from 'caique/decide';
import { processRuntime } from 'caique';

decide({
  value: undefined,                                  // nothing was passed
  spec: { kind: 'text', message: 'Where should it go?' },
  option: 'output-dir',
  runtime: processRuntime(),                         // or your own { env, isTTY: { stdin } }
  required: true,
});
// no terminal -> { action: 'error', code: 'USAGE',
//                  message: '--output-dir is required when there is no terminal',
//                  fix: 'pass --output-dir; it would have been asked as "Where should it go?"' }
// a terminal   -> { action: 'prompt' }
```

The order of the rule is the argument, and it is enumerated rather than described: every
one of the 256 combinations of value x kind x TTY x CI x `--json` x `--yes` x
`--interactive` x required is generated and checked in `decide.test.ts`, against the rule
written a second time, independently. The case that would be a bug report if it broke is
called out by name: **no terminal and no value is never a prompt.**

`--interactive` reaches past "we would not have asked", never past "there is nobody to
ask" — and when there is nobody, the refusal says so, rather than looking like the flag was
ignored.

## What it does

### Asking, once it is allowed

`ask()` is the six kinds — `text`, `confirm`, `select`, `multiselect`, `password`, `path` —
each written as a question and a line read back:

```js
import { ask } from 'caique/ask';

await ask(
  { kind: 'select', message: 'Which host?', choices: [{ value: 'ora' }, { value: 'log-update' }] },
  { reader, writer },
);
// Which host?
//   1) ora
//   2) log-update
//   enter a number (1-2):
```

**Line mode is not the fallback, it is the floor.** No raw mode, no cursor movement, no
escape sequence, no redraw — so this *is* the accessible rendering rather than a second
implementation of it, and a screen reader gets the same bytes a terminal does. The raw-mode
renderer, with arrow keys and a highlight, sits on top of it and answers the same questions
([below](#arrow-keys-where-there-is-a-terminal-to-take-them)).

A stream that ends is a **cancellation**, not an empty answer: `Ctrl-D` and a closed pipe
both mean nobody is going to type, and reading that as `''` is how a program writes to a
path nobody chose. Invalid input is re-asked five times and then gives up, because a loop
against a stream that keeps answering wrongly is the same hang wearing a hat.

`projection(spec)` gives the question without the conversation, for a gallery, a `--help`
or a transcript in an issue.

### Wiring it to a CLI

`resolvePrompts()` is the pass a framework calls from its `preAction` hook, once the flags,
environment and config have had their turn:

```js
import { resolvePrompts } from 'caique/binding';

const { values, failure } = await resolvePrompts({
  options,            // { name: { required: true, prompt: { kind: 'text', message: 'Project name?' } } }
  values,             // what every other source resolved
  runtime: processRuntime(),
  flags: { json, yes, interactive },
  io: { reader, writer },
});
if (failure) throw new CliError(failure.code, failure.message, { fix: failure.fix });
```

It walks the options in **declaration order** — the order the help listed — asks only what
has to be asked, and **stops at the first refusal**, because a caller about to exit is
better served by one actionable message than six.

There is one binding, not one per host. What a framework supplies is a record of options,
the values so far and a runtime; none of that needs any particular framework's types, so
`caique` imports none of them.

### On a real terminal

`createIo()` is the reader and writer over actual streams — the only file in the package
that touches a terminal:

```js
import { createIo } from 'caique/terminal';
import { ask } from 'caique/ask';

const io = createIo();   // the terminal the program was started in
await ask({ kind: 'password', message: 'Token?' }, io);
io.close();
```

A `password` prompt is not echoed, and that lives here rather than in the widgets: this is
the only layer that knows what echo *is*, and no widget can leak a secret by writing it
back, because no widget writes what it read. The echo is suppressed for the duration of the
question rather than by turning the terminal's echo off — which would leave it off if the
process died mid-prompt.

### Arrow keys, where there is a terminal to take them

`askList()` draws `select` and `multiselect` with a moving highlight and repaints in place.
It answers the same question `ask()` does and returns the same value, so it is a swap and
not a second implementation:

```js
import { askList, canRender } from 'caique/raw';
import { createIo, streamsOf } from 'caique/terminal';
import { processRuntime } from 'caique';

const rt = processRuntime();
const io = { ...createIo(streamsOf(rt)), keys: rt.stdin };
const spec = { kind: 'select', message: 'Which host?', choices: [{ value: 'ora' }, { value: 'chalk' }] };
const answer = canRender(io.keys) ? await askList(spec, io) : await ask(spec, io);
```

Line mode is the floor, not the fallback: this is decoration on top of it, and the suite
proves the two agree by running the same spec through both and comparing the answers.
`Ctrl-C` cancels — in raw mode it arrives as a byte rather than a signal — and the terminal
is put back the way it was found either way.

### A prompt kind of your own

A plugin adds a kind under `widgets`; the six built-ins cannot be replaced. It is one module
whose default export is a plain object — in full:

```js
// acme-plugin.mjs
export default {
  name: 'acme',
  contract: 1,
  widgets: {
    'acme-rating': {
      // Required. `spec` is the prompt — `{ kind, message, ... }` plus any field your kind reads —
      // and the string is what a pipe, an agent and a screen reader get.
      static: (spec) => `${spec.message} ${'★'.repeat(spec.value ?? 0)}${'☆'.repeat(5 - (spec.value ?? 0))}`,
      // Optional: `(t, spec) => string`, the animated form. Leave it out for line mode only.
      // frame: (t, spec) => '…',
      // Two states of plain data to preview it with; `check` renders `static({ kind, message: 'preview', ...done })`.
      sample: { running: { value: 0 }, done: { value: 4 } },
    },
  },
};
```

Check it before it ships — in a clone of this repository, where `dist/` is not committed, build
caique and the four packages it imports first:

```bash
npx caique check ./acme-plugin.mjs
# in a clone: npx turbo run build --filter=caique && node packages/caique/dist/cli.js check ./acme-plugin.mjs
```

```text
acme — 1 widgets
  acme-rating  static "preview ★★★★☆"
acme: ok
```

The census comes first and `ok` last. A refusal exits 1 with a code and the edit to make —
`E_NO_STATIC_PROJECTION` for a widget with no `static`, or one whose `static` throws on its own
`sample`, `E_PLUGIN_SCHEMA` for a built-in kind or
a `sample` that is not `{ running, done }`.

### In the user's language

caique's own chrome (the instruction under a list, a problem with an answer, the giving-up line)
can speak the user's language. The translations come from a locale pack registered with
`register()`, under ids that begin `caique.`, so the same object can carry burgee's messages
too. The locale is your runtime's `locale`, which burgee resolves. caique never reads `LANG`
itself:

```js
import { register } from 'caique/plugin';
import { sayFor } from 'caique/locale';

register({ name: 'de', contract: 1, locales: { de: { 'caique.answerYesNo': 'antworten Sie j oder n' } } });
await resolvePrompts({ options, values, runtime, io: { ...io, say: sayFor(runtime.locale) } });
```

A refusal keeps its `message` and `fix` in English, because a host may write them into a
machine envelope. The translation rides beside them as `localised`. Your question and choices
are yours and are never translated. `caique/clack` and `caique/inquirer` keep their incumbents'
English. `npx caique check ./pack.mjs` renders every message, or refuses an unknown id, a stray
placeholder or a missing plural form.

## Migrating

From **`@inquirer/core`**, one import — `createPrompt`, the hooks and the keypress helpers:

```diff
- import { createPrompt, useState, useKeypress, isEnterKey } from '@inquirer/core';
+ import { createPrompt, useState, useKeypress, isEnterKey } from 'caique/inquirer';
```

`npx burgee migrate --dry-run` lists the imports the codemod would rewrite — only drop-ins graded
level with their incumbent — and `npx burgee migrate` makes the change
([Migrate](https://burgee.interlace.tools/docs/migrate)).

From **`@inquirer/prompts`**, `select` and `checkbox` are at `caique/inquirer/prompts`, each level
with its own suite; the other prompts are not built yet, so `burgee migrate` leaves that import alone.

From **`@clack/prompts`** there is no one-import swap: caique takes a prompt as a spec rather
than clack's call signature and does not draw clack's frames, so a CLI moves one prompt at a
time. [Coming from clack](https://caique.interlace.tools/docs/coming-from/clack) maps each clack
export to its caique counterpart, or says there is none.

## Compatibility

Measured against **`@inquirer/prompts`** (28.8 M/wk) and **`@clack/prompts`** — those two, and
not the package whose download count is larger:

- **`inquirer` (34.3 M/wk) is out of scope, deliberately.** Its 34 million are the *legacy*
  `inquirer.prompt([...])` façade, an API its own maintainer moved off; a new CLI written
  today writes `@inquirer/prompts`. Reproducing the legacy object API would be work spent
  on a shape nobody new adopts, and it is not on this package's roadmap.
- **`@inquirer/core`** is what the compatibility oracle grades, because it is where the
  prompt *loop* — the keypress state machine both façades sit on — is actually tested.
  `inquirer`'s own npm tarball ships **no tests at all**, so there is nothing there to grade.

Each is graded by its own unedited suite through `compat-oracle`, run twice: once against the
incumbent (the control — the column that proves the gate works) and once against caique.
`caique/inquirer` is a drop-in for `@inquirer/core`. `caique/clack` is narrower on purpose: it
carries `limitOptions`, the one clack function that is not a drawing, and its row grades the
behavioural remainder of clack's suite as a declared subset. The current grades are generated
under *Benchmarks* below and published on the
[compatibility page](https://burgee.interlace.tools/docs/compatibility).

## Weight

Every subpath is a lock, not a convention: `weight.test.ts` walks each entry's import graph in
`dist/` and asserts its budget and what it may reach, and the figures below are what it
measured. **The ceiling is clack**: `@clack/prompts`
1.8.0 is **101,684 B across six packages** — itself, `@clack/core`, `fast-string-width`,
`fast-string-truncated-width`, `fast-wrap-ansi` and `sisteransi` ([measured](https://burgee.interlace.tools/docs/benchmarks)).

| Subpath | Bytes | Reaches |
| :-- | --: | :-- |
| `caique` (everything but the façades) | 19,549 | `closeout/cursor` and `closeout/exit-hook` — never a façade |
| `caique/spec` | 739 | a leaf — declare prompts without loading a widget |
| `caique/decide` | 2,133 | the spec only |
| `caique/ask` | 4,234 | the six widgets, no terminal, no raw mode |
| `caique/raw` | 8,896 | line mode, which it sits on top of, the key decoder, and `closeout` for the cursor |
| `caique/keys` | 4,991 | `closeout` for raw mode, and nothing else in caique |
| `caique/editor` | 12,389 | the key decoder and the line editing `caique/clack` shares; no I/O |
| `caique/binding` | 8,123 | the decision and the widgets |
| `caique/terminal` | 1,947 | the one file that touches a stream |
| `caique/plugin` | 9,788 | the widgets, and the family schema |
| `caique/clack` | 62,097 | `closeout/cursor`, `closeout/exit-hook` and `linegauge/wrap` |
| `caique/inquirer` | 20,623 | `closeout/cursor`, `closeout/exit-hook` and `linegauge/wrap` |

The root entry is **under a fifth of the lightest incumbent**, and nothing reaches outside this
repository: every `allow` list in `weight.test.ts` names only `closeout` and `linegauge`
subpaths, asserted rather than claimed. Deciding *not* to ask costs 2,133 B and never loads
the machinery of asking — which is the case an agent hits. The two façades are leaves away
from the rest: a program on caique's own API never loads a byte of either ([measured](https://burgee.interlace.tools/docs/benchmarks)).

Measured 2026-09-20 (the root, `caique/raw`, `caique/keys`, `caique/editor` and `caique/clack` on 2026-10-05), the same way every bill in this family is: shipped code and data
(`.js`/`.mjs`/`.cjs` plus imported `.json`, `package.json` never counted), each competitor
counted whole across its own resolved tree.

caique depends on two packages, both from this repository: `closeout`, because a prompt
hides the cursor and owes it back however the process dies, and there is exactly one correct
implementation of that; and `linegauge/wrap`, because the two façades' lists wrap and re-draw, and need the
incumbent's own line-breaking — which this repository publishes as a graded port. Nothing
outside this repository is installed.

The two drop-in subpaths are priced on their own, because a program that imports caique
never loads either. **`caique/clack`** — clack's twelve prompts, its writers, glyphs and
settings — is **62,238 B** against clack's 101,684 B (measured 2026-09-27, budget 64,000 in
`weight.test.ts`); `caique/inquirer` is priced beside it ([measured](https://burgee.interlace.tools/docs/benchmarks)).

## Benchmarks

Every number here is produced by `npm run bench` and published at [burgee.interlace.tools/docs/benchmarks](https://burgee.interlace.tools/docs/benchmarks).

Graded by the incumbent's own test suite:

| suite | passing |
| :-- | --: |
| `clack` | 16 / 16 |
| `inquirer-core` | 46 / 46 |
| `inquirer-prompts` | 222 / 222 |

Weight, installed and tree-inclusive: **300,221 bytes** against **389,049** for the incumbents it replaces — a ratio of **0.7717** ([measured](https://burgee.interlace.tools/docs/benchmarks)).

## For agents

- **No terminal and no value is never a prompt.** `decide()` returns
  `{ action: 'error', code: 'USAGE', message, fix }` naming the flag that would have answered the
  question, so an agent passes it and retries — exit 2, never a hang.
- **Every prompt is a flag first.** A caller who passes the flag is never asked; `--yes` accepts
  every confirmation; `--interactive` asks for every missing required option in one pass.
- **The question without the conversation.** `projection(spec)` renders a prompt for a gallery,
  a `--help` or a transcript.
- **A widget plugin can be checked before it ships.** `npx caique check ./widget.mjs` validates
  it against the family schema and exits 0, 1 with a code and a fix, or 2 on a usage error. The
  whole plugin and the report are under [A prompt kind of your own](#a-prompt-kind-of-your-own).
- **The docs are machine-readable** at
  [caique.interlace.tools/llms.txt](https://caique.interlace.tools/llms.txt) and
  [llms-full.txt](https://caique.interlace.tools/llms-full.txt).

## Guarantees

- **Every prompt is a flag first.** A caller who passes the flag is never asked, so an agent
  answers on the command line, in one pass.
- **Off a terminal, nothing waits.** With nobody to answer, a missing value is a `USAGE`
  error, exit 2, that names the flag and carries a `fix` a program can apply and retry.
- **`--interactive`** asks for every missing required option in one pass, and
  `--interactive=all` for every promptable one; **`--yes`** answers every confirmation; a
  cancelled prompt exits `CANCELLED` with the terminal restored.
- **Line mode is the accessible mode:** numbered choices and line input, with no live redraw.
- **Drop-in paths for `@inquirer/core` and `@clack/prompts`**, each graded by its own suite.
  The current grades are under *Compatibility* and *Benchmarks*, above.

## Design documents

The intent and the design are committed beside the code, with the status of every
requirement: [`.sdlc/intents/caique/`](https://github.com/ofri-peretz/burgee/tree/main/.sdlc/intents/caique).
If a prompt in your CLI cannot be expressed as a flag,
[open an issue](https://github.com/ofri-peretz/burgee/issues): that case shapes the design.

## API

`decide`, `ask`, `askList`, `resolvePrompts`, `createIo` and `projection` are shown above, each
on its own subpath (see [Weight](#weight)); every export, with its types, is on
[caique.interlace.tools](https://caique.interlace.tools/docs).

## Where it sits

Plugins register under the `widgets` and `locales` keys, against the one schema the whole family shares.

`controlroom` builds on it, and it builds on `bellpull`, `closeout`, `linegauge`, `paratext`, `roundel`.

## The family

Eleven packages, one repository, one release pipeline. Each installs and works on its own, and each
owns one job. Six of them — `bellpull`, `closeout`, `linegauge`, `paratext`, `roundel`, `seniority`
— depend on nothing; the others depend only on packages in this table, and every dependency points
one way, down the [layers](https://burgee.interlace.tools/docs/concepts/family).

No package declares a dependency from outside the family; `react` and `react-reconciler` are
optional peers of `controlroom`, which npm does not install; `vitest` is an optional peer of
`oxmutate`, which npm does not install.
[`package-shape-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/package-shape-lock.test.ts)
holds that for every manifest, and
[`independence-install-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/independence-install-lock.test.ts)
installs each package alone and finds nothing but the family packages it declares.

Releases are published by one workflow through npm trusted publishing: no npm token is used, and
each release carries SLSA provenance, which `npm view <package> dist.attestations` shows.
[`trusted-publishing-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/trusted-publishing-lock.test.ts)
keeps both true.

| Package | What it is | Migrates from |
| :-- | :-- | :-- |
| [burgee](https://burgee.interlace.tools/docs/packages/burgee) | The CLI framework: one declaration, every surface | commander, yargs and meow |
| [roundel](https://roundel.interlace.tools/docs) | Colour: one output policy, semantic tokens, a theme | chalk, colorette, kleur, picocolors, supports-color and yoctocolors |
| [flagstaff](https://flagstaff.interlace.tools/docs) | The frame loop: spinners, progress, boxes and tables | ora, log-update, boxen and cli-table3 |
| **caique** (this package) | Prompts that are flags first, and never hang | @inquirer/core |
| [linegauge](https://linegauge.interlace.tools/docs) | Measuring, wrapping, truncating and slicing styled text | string-width, wrap-ansi, strip-ansi, slice-ansi, cli-truncate and widest-line |
| [paratext](https://paratext.interlace.tools/docs) | Hyperlinks, images, title, clipboard and notifications | ansi-escapes, terminal-link and term-img |
| [seniority](https://seniority.interlace.tools/docs) | Configuration precedence and discovery, with provenance | cosmiconfig, lilconfig, dotenv and rc |
| [closeout](https://closeout.interlace.tools/docs) | Exit handlers, terminal restore and a bounded shutdown | signal-exit, exit-hook, restore-cursor, cli-cursor and onetime |
| [bellpull](https://bellpull.interlace.tools/docs) | Subprocesses, and which executable actually ran | cross-spawn and which |
| [controlroom](https://controlroom.interlace.tools/docs) | Keyboard-driven terminal screens, inline or full-screen | ink |
| [oxmutate](https://oxmutate.interlace.tools/docs) | Mutation testing on the oxc engine, inside your own Vitest | Stryker |

Every migration guide, and the family-wide [compatibility](https://burgee.interlace.tools/docs/compatibility)
and [benchmarks](https://burgee.interlace.tools/docs/benchmarks) pages, are on
[burgee.interlace.tools](https://burgee.interlace.tools/docs/packages).

## Contributing

Issues and pull requests are welcome at [ofri-peretz/burgee](https://github.com/ofri-peretz/burgee/issues); read
[CONTRIBUTING.md](https://github.com/ofri-peretz/burgee/blob/main/CONTRIBUTING.md) first. Report a vulnerability privately, as
[SECURITY.md](https://github.com/ofri-peretz/burgee/blob/main/SECURITY.md) describes — never in a public issue.

## Licence

MIT © Ofri Peretz — see [LICENSE](https://github.com/ofri-peretz/burgee/blob/main/packages/caique/LICENSE).

---

# Prompts an agent can answer

> Declare each prompt on the option it fills, so an agent answers on the command line, --json refuses instead of asking, and the refusal tells the agent exactly what to pass.

Source: https://caique.interlace.tools/docs/recipes/answers-for-agents

An agent driving your CLI cannot type into a prompt. It can pass a flag, and it can act on an
error that names one. Declaring the prompt on the option it fills gives it both:

```js title="init.mjs"
import process from 'node:process';

import { processRuntime } from 'caique';
import { resolvePrompts } from 'caique/binding';
import { createIo } from 'caique/terminal';

const argv = process.argv.slice(2);
const json = argv.includes('--json');
const name = argv.find((a) => a.startsWith('--name='))?.slice('--name='.length);

const io = createIo();
const { values, failure } = await resolvePrompts({
  options: { name: { required: true, prompt: { kind: 'text', message: 'Project name?' } } },
  values: { name },
  runtime: processRuntime(),
  flags: { json },
  io,
});
io.close();

if (failure) {
  if (json) console.log(JSON.stringify({ ok: false, error: { code: failure.code, message: failure.message, fix: failure.fix } }));
  else console.error(`${failure.message}\n  fix: ${failure.fix}`);
  process.exitCode = 2;
} else {
  console.log(json ? JSON.stringify({ ok: true, name: values.name }) : `created ${values.name}`);
}
```

```text title="node init.mjs --json" exit="2"
{"ok":false,"error":{"code":"USAGE","message":"--name is required under --json","fix":"pass --name; --json means no one is here to answer \"Project name?\""}}
```

```text title="node init.mjs --json --name=demo"
{"ok":true,"name":"demo"}
```

The refusal is structured, carries the flag and quotes the question, and the second call is the
one an agent makes after reading it. The same program asks a person on a terminal, and under
`--json` never does, terminal or not.

A CLI on [burgee](https://burgee.interlace.tools/docs) gets this without the wiring: its
`--json` envelope already carries `code`, `message` and `fix`.

---

# Confirmations in CI

> Let --yes answer a destructive confirm in CI and scripts, while a required text or select with no value still refuses — --yes never invents an answer to a question with more than two.

Source: https://caique.interlace.tools/docs/recipes/confirm-in-ci

A destructive command asks "are you sure?". In CI there is nobody to say yes, and a command
that waits is a hung job. `--yes` answers every `confirm` with `true`, with or without a
terminal — and nothing else:

```js title="reset.mjs"
import { resolvePrompts } from 'caique/binding';

const options = {
  force: { required: true, prompt: { kind: 'confirm', message: 'Delete every cached build?' } },
  scope: { required: true, prompt: { kind: 'select', message: 'Which scope?', choices: [{ value: 'local' }, { value: 'remote' }] } },
};
const ci = { env: { CI: 'true' }, isTTY: { stdin: false, stdout: false } };
const io = { reader: { line: async () => undefined }, writer: { write: () => {} } };

for (const [label, values] of [['--yes', {}], ['--yes --scope=local', { scope: 'local' }]]) {
  const { values: out, failure } = await resolvePrompts({ options, values, runtime: ci, flags: { yes: true }, io });
  console.log(`${label}: ${failure ? failure.message : JSON.stringify(out)}`);
}
```

```text title="node reset.mjs"
--yes: --scope is required when there is no terminal
--yes --scope=local: {"scope":"local","force":true}
```

`--yes` answered the confirmation both times. It did not answer `scope`, because there is no
"yes" to a question with two options that are not yes and no; the run has to say which.

---

# Incremental migration

> Move from @inquirer/core with one import, from @clack/prompts with one import or a prompt at a time, and then to flag-first prompts where an agent or CI runs the command.

Source: https://caique.interlace.tools/docs/recipes/incremental-migration

## From `@inquirer/core`: one import

```diff
- import { createPrompt, useState, useKeypress, isEnterKey } from '@inquirer/core';
+ import { createPrompt, useState, useKeypress, isEnterKey } from 'caique/inquirer';
```

Graded 46 of 46 by `@inquirer/core`'s own suite, so `npx burgee migrate` rewrites it for you
(`--dry-run` lists it first).

## From `@clack/prompts`: one import

```diff
- import { confirm, isCancel, select, text } from '@clack/prompts';
+ import { confirm, isCancel, select, text } from 'caique/clack';
```

`caique/clack` grades 16 of 16, level with clack, so `burgee migrate` makes this change for you.
It refuses a file that also imports `@clack/core`, because caique's prompts never read
`@clack/core`'s settings: import `updateSettings` from `caique/clack` there and run it again
([Compatibility](/docs/drop-ins#known-differences)).

## Then: a prompt at a time, to a flag

The drop-ins keep your prompts working. The reason to move is what they cannot do: refuse,
naming a flag, when nobody is there. Move the prompts an agent or CI will meet first — the ones
on commands that run unattended — to options with a prompt spec, and pass them through
`resolvePrompts()` ([Binding prompts to a CLI](/docs/guides/binding)). The rest can stay on the
drop-in as long as you like; both read their input from the same process.

## Checking each step

```bash
npm uninstall @inquirer/core @clack/prompts
npm ls @clack/core
```

---

# Testing prompts

> Drive ask() and resolvePrompts() with a scripted reader and writer — no PTY, no fake stdin — and assert both the answers and exactly what was written.

Source: https://caique.interlace.tools/docs/recipes/testing-prompts

Nothing above `caique/terminal` touches a stream: `ask()` takes a reader of lines and a writer
of text. A test hands it both and asserts the conversation.

```js title="prompt-check.mjs"
import assert from 'node:assert/strict';

import { ask } from 'caique/ask';

function conversation(answers) {
  const lines = [...answers];
  let written = '';
  return {
    io: { reader: { line: async () => lines.shift() }, writer: { write: (text) => void (written += text) } },
    written: () => written,
  };
}

const port = conversation(['eighty', '80']);
const answer = await ask({ kind: 'text', message: 'Port?', validate: (v) => (/^\d+$/u.test(v) ? undefined : 'a port is a number') }, port.io);
assert.deepEqual(answer, { ok: true, value: '80' });
assert.equal(port.written(), 'Port?   a port is a number\nPort? ');

const closed = conversation([]);
assert.deepEqual(await ask({ kind: 'confirm', message: 'Continue?' }, closed.io), { ok: false, reason: 'cancelled' });

console.log('ok');
```

```text title="node prompt-check.mjs"
ok
```

The second case is the one that matters most: a stream that ends — `Ctrl-D`, a closed pipe, an
empty script — is a cancellation, never an empty answer. `decide()` needs no stream at all; it
is a pure function of a literal runtime ([Never hangs](/docs/guides/never-hangs)).

---

# Why caique

> caique against inquirer and clack, one capability per row, every cell linked to the test, grade or source that proves it.

Source: https://caique.interlace.tools/docs/why-caique

inquirer and clack draw good prompts for a person at a terminal. Neither asks whether a person
is there. A CLI run by an agent, in CI or with its input piped either waits on a stream nobody
will write to, or fails without saying what to pass instead. caique decides that first: a
prompt is a flag, a value from anywhere is never asked for, and with nobody to ask, a missing
value is an error that names the flag. Its two drop-in paths, `caique/inquirer` and
`caique/clack`, are graded by each incumbent's own suite.

The table below is the whole comparison. Every mark links to its evidence: a test in this
repository for ours, and for theirs the source of the exact version compat-oracle grades, or
that package's own test suite. `scripts/capabilities-lock.test.ts` fails the build when a cited
test no longer contains the title it is cited for.

✓ yes · ◐ partial (what is missing is said) · ✗ no · — does not apply. Every cell links to its evidence: our test or grade, or the incumbent’s source at the version compat-oracle grades.

### Never hangs

| Capability | **caique** | inquirer-core | clack |
| :-- | :-- | :-- | :-- |
| **No terminal and no value is a refusal, not a wait** — `decide()` rules on every prompt before anything is drawn, and with nobody on stdin a missing value is a usage error rather than a prompt waiting for a person who is not there. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/caique/src/decide.test.ts) | [✗ reads whatever input stream it is given; nothing checks whether a person is on it](https://cdn.jsdelivr.net/npm/@inquirer/core@12.0.3/dist/lib/create-prompt.js) | [✗ a prompt reads its input stream whether or not it is a terminal; only raw mode is conditional](https://cdn.jsdelivr.net/npm/@clack/core@1.5.1/dist/index.mjs) |
| **The refusal names the flag to pass** — A prompt is bound to a flag, so the error says `--name is required when there is no terminal` and how to answer it, which an agent can act on. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/caique/src/shape.test.ts) | [✗ a prompt has no flag behind it to name](https://cdn.jsdelivr.net/npm/@inquirer/core@12.0.3/dist/lib/create-prompt.js) | [✗ a prompt has no flag behind it to name](https://cdn.jsdelivr.net/npm/@clack/core@1.5.1/dist/index.mjs) |
| **An agent on a terminal is refused, not prompted** — Under `CLAUDECODE`, `CURSOR_AGENT`, `CODEX_THREAD_ID`, `GEMINI_CLI` or `AI_AGENT` there is a terminal and no person, so `decide()` asks roundel's `interactive()` and refuses, naming the flag, where asking only whether stdin is a terminal would wait forever. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/caique/src/decide.test.ts) | [✗ reads no agent variable; a prompt on a terminal waits for keys](https://cdn.jsdelivr.net/npm/@inquirer/core@12.0.3/dist/lib/create-prompt.js) | [✗ reads no agent variable; a prompt on a terminal waits for keys](https://cdn.jsdelivr.net/npm/@clack/core@1.5.1/dist/index.mjs) |
| **`--json` and `CI` never prompt** — Under `--json`, or with `CI` set, a missing value is refused even on a terminal, because a machine is reading and nobody is there to type. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/caique/src/decide.test.ts) | [✗ reads no CI variable and knows no --json](https://cdn.jsdelivr.net/npm/@inquirer/core@12.0.3/dist/lib/create-prompt.js) | [✗ reads CI to stop its spinner and progress animating, not to stop a prompt](https://cdn.jsdelivr.net/npm/@clack/prompts@1.8.1/dist/index.mjs) |

### The terminal as it was found

| Capability | **caique** | inquirer-core | clack |
| :-- | :-- | :-- | :-- |
| **Raw mode is turned off only if the prompt turned it on** — A program that already had its terminal in raw mode keeps it when a prompt ends, and a signal mid-prompt still turns off the raw mode the prompt did turn on, through closeout. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/caique/src/raw.test.ts) | [✗ runs on node:readline with terminal: true, whose close() turns raw mode off whatever it was before](https://github.com/nodejs/node/blob/v24.12.0/lib/internal/readline/interface.js) | [✗ close() calls setRawMode(input, false) unconditionally](https://cdn.jsdelivr.net/npm/@clack/core@1.5.1/dist/index.mjs) |

### Extending it

| Capability | **caique** | inquirer-core | clack |
| :-- | :-- | :-- | :-- |
| **Custom prompt kinds through a validated plugin registry** — A widget for a kind outside the six built-ins is registered by name, and one without a static projection is refused with the code flagstaff and paratext use. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/caique/src/plugin.test.ts) | [◐ a custom prompt is a function built with createPrompt; there is no registry, and nothing asks it for a text form](https://cdn.jsdelivr.net/npm/@inquirer/core@12.0.3/dist/lib/create-prompt.js) | [◐ a custom prompt subclasses Prompt; there is no registry, and nothing asks it for a text form](https://cdn.jsdelivr.net/npm/@clack/core@1.5.1/dist/index.mjs) |
| **A checker for widget plugins before they ship** — `npx caique check ./rating.mjs` validates a plugin against the family schema and exits 1 with a code and a fix when it is refused. | [✓](https://github.com/ofri-peretz/burgee/blob/main/scripts/plugin-check-lock.test.ts) | [— takes no plugins, so has nothing to check](https://cdn.jsdelivr.net/npm/@inquirer/core@12.0.3/package.json) | [— takes no plugins, so has nothing to check](https://cdn.jsdelivr.net/npm/@clack/prompts@1.8.1/package.json) |

### Weight

| Capability | **caique** | inquirer-core | clack |
| :-- | :-- | :-- | :-- |
| **Every runtime dependency from the same repository** — Installing it adds closeout, linegauge and paratext, released from this repository through one pipeline, and nothing else. | [✓](https://github.com/ofri-peretz/burgee/blob/main/scripts/package-shape-lock.test.ts) | [✗ seven dependencies, among them signal-exit, mute-stream and cli-width](https://cdn.jsdelivr.net/npm/@inquirer/core@12.0.3/package.json) | [✗ @clack/core, fast-string-width, fast-wrap-ansi and sisteransi](https://cdn.jsdelivr.net/npm/@clack/prompts@1.8.1/package.json) |

### Compatibility

| Capability | **caique** | inquirer-core | clack |
| :-- | :-- | :-- | :-- |
| **Passes @inquirer/core's own test suite** — `caique/inquirer` — `createPrompt`, the hooks and the keypress helpers — is graded by @inquirer/core 12.0.3's own tests, unedited, rendered through a headless terminal. | [✓ 46 / 46 of its own tests](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/baseline/inquirer-core.json) | [✓ its own suite, the control run](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/vendor/inquirer-core/packages/core/core.vitest.ts) | [— a different API](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/vendor/clack/packages/prompts/test/limit-options.test.ts) |
| **Passes clack's own test suite** — `caique/clack` is graded by the behavioural cases of @clack/prompts 1.8.1's own suite, with the snapshots of clack's exact frames subtracted by name, and one case that grades @clack/core's module state rather than @clack/prompts (D-20260930-caique-clack-core-exclusion). | [✓ 16 / 16 of its own tests](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/baseline/clack.json) | [— a different API](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/vendor/inquirer-core/packages/core/core.vitest.ts) | [✓ its own suite, the control run](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/vendor/clack/packages/prompts/test/limit-options.test.ts) |

## Reading it

- **The inquirer column is `inquirer-core`, `@inquirer/core` 12.0.3**: the loop every inquirer
  prompt runs on, and what compat-oracle grades for inquirer. The legacy `inquirer.prompt([...])` API
  is out of scope, and its tarball ships no tests to grade.
- **The clack column is `@clack/prompts` 1.8.1 and the `@clack/core` 1.5.1 it depends on.**
- **Neither is installed in this repository**, so their cells link to the graded version's
  source on jsDelivr (and, for inquirer's raw mode, to Node's `readline`, which it runs on). The
  lock does not re-read a URL cell; each was checked against that file by hand. The
  compatibility rows cite each one's vendored suite, which the lock reads every run.
- **clack's compatibility is partial on purpose.** One case sets `updateSettings({ withGuide:
  false })` imported from `@clack/core` and asserts caique's prompts obey it — module state in a
  package caique does not depend on ([Compatibility](/docs/drop-ins)).

## What is not in the table

A row goes in only when every cell of it can be proved. These were left out:

- **A cursor restored when the process is signalled mid-prompt.** caique's `raw.test.ts` proves
  it for `SIGINT` and `SIGTERM`. inquirer registers a signal-exit handler whose cleanup runs in a
  promise's `finally`; whether that runs before the process exits was not established, so there
  is no row rather than a guessed cell.
- **An accessible rendering.** caique's line mode is its accessible mode; clack 1.8 also has an
  `accessible` option and reads `ACCESSIBLE`. No test here compares them.
- **Weight in bytes.** The per-subpath figures are asserted by
  [`weight.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/caique/src/weight.test.ts)
  and published on [Benchmarks](https://burgee.interlace.tools/docs/benchmarks).