caique 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ofri Peretz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,25 @@
-# caique
+<p align="center">
+  <a href="https://github.com/ofri-peretz/burgee/tree/main/packages/caique" target="blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ofri-peretz/burgee/main/brand-assets/caique-lockup.svg" />
+      <img src="https://raw.githubusercontent.com/ofri-peretz/burgee/main/brand-assets/caique-lockup-light.svg" alt="caique" width="360" />
+    </picture>
+  </a>
+</p>
 
-**Not yet released.** This version reserves the name; the first working release follows
-[`docs/intents/cli-prompts/`](https://github.com/ofri-peretz/burgee/tree/main/docs/intents/cli-prompts).
+<p align="center">
+  Prompts that are flags first — so an agent answers before it is asked, and nothing ever hangs.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/caique"><img src="https://img.shields.io/npm/v/caique?style=flat-square&color=0a6b47" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/status-pre--release-a84c17?style=flat-square" alt="Status: pre-release" />
+  <img src="https://img.shields.io/badge/runtime%20dependencies-0-0a6b47?style=flat-square" alt="Zero runtime dependencies" />
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT" />
+</p>
+
+**Pre-release.** The first working slice is here — `decide()`, below — and the rest follows
+[`.sdlc/intents/caique/`](https://github.com/ofri-peretz/burgee/tree/main/.sdlc/intents/caique).
 
 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
@@ -9,6 +27,160 @@ runs between the ship and the shore carrying people and messages across the gap.
 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.**
 
+## What ships today
+
+`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';
+
+decide({
+  value: undefined,                                  // nothing was passed
+  spec: { kind: 'text', message: 'Where should it go?' },
+  option: 'output-dir',
+  runtime: { env: process.env, isTTY: { stdin: process.stdin.isTTY } },
+  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.
+
+### 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 that arrows and highlights will sit on top and answer the same questions.
+
+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: { env: process.env, isTTY: { stdin: process.stdin.isTTY } },
+  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({ input: process.stdin, output: process.stdout });
+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 } from 'caique/terminal';
+
+const io = { ...createIo({ input: process.stdin, output: process.stdout }), keys: process.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.
+
+## Weight
+
+Every subpath is a lock, not a convention, and the numbers below are asserted by
+`weight.test.ts` against `dist/`, not estimated. **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`.
+
+| Subpath | Bytes | Reaches |
+| :-- | --: | :-- |
+| `caique` (everything) | 25,627 | no package at all |
+| `caique/spec` | 1,571 | a leaf — declare prompts without loading a widget |
+| `caique/decide` | 4,986 | the spec only |
+| `caique/ask` | 8,564 | the six widgets, no terminal, no raw mode |
+| `caique/raw` | 14,796 | line mode, which it sits on top of |
+| `caique/binding` | 15,475 | the decision and the widgets |
+| `caique/terminal` | 11,975 | the one file that touches a stream |
+
+The whole package is **a quarter of the lightest incumbent**, and it reaches nothing:
+`allow` is empty for every entry, asserted rather than claimed. Deciding *not* to ask costs
+4,986 B and never loads the machinery of asking — which is the case an agent hits.
+
+Measured 2026-09-09, 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.
+
 ## What it will be
 
 - **Every prompt is a flag first.** A caller who passes the flag is never asked. An agent
@@ -20,6 +192,22 @@ is calling, human or agent, and brings the answer back. **It never hangs.**
 - **Accessible mode** falls back to line input with no live redraw.
 - **Drop-in paths** for inquirer and clack, graded by their own suites.
 
-Part of the [burgee](https://github.com/ofri-peretz/burgee) family: a CLI on burgee declares
-what it is, roundel carries its colours, flagstaff flies it, caique answers back. Each is
-an independent package; none requires the others.
+## Following along
+
+The intent and design are committed before the code is, so you can read what it will be —
+and argue with it — before it exists:
+
+- [`.sdlc/intents/caique/`](https://github.com/ofri-peretz/burgee/tree/main/.sdlc/intents/caique)
+  — the intent and the design.
+- [Open an issue](https://github.com/ofri-peretz/burgee/issues) if a prompt in your CLI
+  cannot be expressed as a flag. That case is the interesting one.
+
+---
+
+Part of the [burgee](https://github.com/ofri-peretz/burgee) family: a CLI on
+[burgee](https://www.npmjs.com/package/burgee) declares what it is,
+[roundel](https://www.npmjs.com/package/roundel) carries its colours,
+[flagstaff](https://www.npmjs.com/package/flagstaff) flies it, and caique answers back. Each
+is an independent package; none requires the others.
+
+MIT © Ofri Peretz — see [LICENSE](./LICENSE).

package/dist/ask.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The six widgets, in line mode (R5) — and line mode is not a fallback, it is the floor.
+ *
+ * Every widget here works by writing a question and reading a line. No raw mode, no cursor
+ * movement, no escape sequence, no redraw. That makes it the accessible mode by
+ * construction rather than by a second implementation kept in step by hand: a screen
+ * reader gets the same bytes a terminal does, and `select` is a numbered list because a
+ * numbered list is what a person can answer without seeing a highlight move.
+ *
+ * It is also what makes the widgets testable without a PTY. A `Reader` is one method that
+ * returns the next line, so the whole suite is strings in and strings out; the raw-mode
+ * renderer that arrows and highlights will come later sits *on top* of this and answers
+ * the same questions, which is how it stays honest.
+ *
+ * Nothing here reads `process`, and nothing decides *whether* to ask — that is `decide()`,
+ * which runs first and refuses when there is no one to ask.
+ */
+import { type BoundPrompt, type PromptSpec } from './spec.js';
+export 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;
+}
+/** A line of input, or `undefined` when the stream ended — which is a cancellation. */
+export interface Reader {
+    line(options?: ReadOptions): Promise<string | undefined>;
+}
+export interface Writer {
+    write(text: string): void;
+}
+export interface Io {
+    reader: Reader;
+    writer: Writer;
+}
+export type Answer = string | boolean | string[];
+/** Answered, or cancelled — cancellation is a value here and a `CANCELLED` error above (R4). */
+export type Asked = {
+    ok: true;
+    value: Answer;
+} | {
+    ok: false;
+    reason: 'cancelled';
+};
+/**
+ * Ask one prompt and return its answer.
+ *
+ * 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 treating that as `''` is how a program ends up
+ * writing to a path the user never chose. Invalid input is re-asked, bounded — after
+ * `MAX_ATTEMPTS` it gives up rather than looping, because a loop against a stream that
+ * keeps answering wrongly is the hang this package exists to prevent, wearing a hat.
+ */
+export declare function ask(prompt: BoundPrompt | PromptSpec, io: Io): Promise<Asked>;
+/**
+ * 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.
+ */
+export declare function projection(spec: PromptSpec): string;

package/dist/ask.js

@@ -0,0 +1,148 @@
+/**
+ * The six widgets, in line mode (R5) — and line mode is not a fallback, it is the floor.
+ *
+ * Every widget here works by writing a question and reading a line. No raw mode, no cursor
+ * movement, no escape sequence, no redraw. That makes it the accessible mode by
+ * construction rather than by a second implementation kept in step by hand: a screen
+ * reader gets the same bytes a terminal does, and `select` is a numbered list because a
+ * numbered list is what a person can answer without seeing a highlight move.
+ *
+ * It is also what makes the widgets testable without a PTY. A `Reader` is one method that
+ * returns the next line, so the whole suite is strings in and strings out; the raw-mode
+ * renderer that arrows and highlights will come later sits *on top* of this and answers
+ * the same questions, which is how it stays honest.
+ *
+ * Nothing here reads `process`, and nothing decides *whether* to ask — that is `decide()`,
+ * which runs first and refuses when there is no one to ask.
+ */
+import {} from './spec.js';
+const CANCELLED = { ok: false, reason: 'cancelled' };
+/** Re-asking forever on invalid input is a hang with extra steps. */
+const MAX_ATTEMPTS = 5;
+const DECIMAL = 10;
+const YES = new Set(['y', 'yes', 'true', '1']);
+const NO = new Set(['n', 'no', 'false', '0']);
+/** `Overwrite it? (y/N)` — the default in capitals, the convention every CLI already uses. */
+function confirmSuffix(initial) {
+    return initial === true ? ' (Y/n) ' : ' (y/N) ';
+}
+function textSuffix(initial) {
+    return typeof initial === 'string' && initial !== '' ? ` (${initial}) ` : ' ';
+}
+/** The numbered list R5 asks for. One-based, because a person is reading it. */
+function listChoices(choices) {
+    return choices.map((choice, index) => `  ${index + 1}) ${choice.label ?? choice.value}${choice.hint === undefined ? '' : ` — ${choice.hint}`}`).join('\n');
+}
+/** A 1-based index into `choices`, or nothing when the answer names no choice. */
+function pick(answer, choices) {
+    const index = Number.parseInt(answer, DECIMAL);
+    if (Number.isInteger(index) && index >= 1 && index <= choices.length)
+        return choices[index - 1];
+    // A person who types the label rather than its number has answered the question.
+    return choices.find((choice) => choice.value === answer || choice.label === answer);
+}
+function confirmAttempt(spec, label) {
+    return {
+        question: label + confirmSuffix(spec.initial),
+        parse: (line) => {
+            const answer = line.trim().toLowerCase();
+            if (answer === '')
+                return { ok: true, value: spec.initial === true };
+            if (YES.has(answer))
+                return { ok: true, value: true };
+            if (NO.has(answer))
+                return { ok: true, value: false };
+            return { ok: false, problem: 'answer y or n' };
+        },
+    };
+}
+function selectAttempt(choices, label) {
+    return {
+        question: `${label}\n${listChoices(choices)}\n  enter a number (1-${choices.length}): `,
+        parse: (line) => {
+            const choice = pick(line.trim(), choices);
+            return choice === undefined ? { ok: false, problem: `enter a number from 1 to ${choices.length}` } : { ok: true, value: choice.value };
+        },
+    };
+}
+function multiselectAttempt(choices, label) {
+    return {
+        question: `${label}\n${listChoices(choices)}\n  enter numbers separated by commas, or blank for none: `,
+        parse: (line) => {
+            const parts = line
+                .split(',')
+                .map((part) => part.trim())
+                .filter((part) => part !== '');
+            if (parts.length === 0)
+                return { ok: true, value: [] };
+            const picked = parts.map((part) => pick(part, choices));
+            const missing = parts.filter((_, index) => picked[index] === undefined);
+            if (missing.length > 0)
+                return { ok: false, problem: `${missing.join(', ')} ${missing.length === 1 ? 'is not a choice' : 'are not choices'}; use numbers from 1 to ${choices.length}` };
+            return { ok: true, value: picked.map((choice) => choice.value) };
+        },
+    };
+}
+/**
+ * text, password and path all read a line. `password` differs only in that the caller must
+ * not echo it, which is the reader's business — this module never sees a terminal, so
+ * hiding the input cannot be got wrong here.
+ */
+function lineAttempt(spec, label) {
+    return {
+        question: label + textSuffix(spec.initial),
+        parse: (line) => {
+            const answer = line === '' && typeof spec.initial === 'string' ? spec.initial : line;
+            const problem = spec.validate?.(answer);
+            return problem === undefined ? { ok: true, value: answer } : { ok: false, problem };
+        },
+    };
+}
+function attemptFor(spec, label) {
+    const choices = spec.choices ?? [];
+    if (spec.kind === 'confirm')
+        return confirmAttempt(spec, label);
+    if (spec.kind === 'select')
+        return selectAttempt(choices, label);
+    if (spec.kind === 'multiselect')
+        return multiselectAttempt(choices, label);
+    return lineAttempt(spec, label);
+}
+/**
+ * Ask one prompt and return its answer.
+ *
+ * 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 treating that as `''` is how a program ends up
+ * writing to a path the user never chose. Invalid input is re-asked, bounded — after
+ * `MAX_ATTEMPTS` it gives up rather than looping, because a loop against a stream that
+ * keeps answering wrongly is the hang this package exists to prevent, wearing a hat.
+ */
+export async function ask(prompt, io) {
+    const label = prompt.message;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+        const { question, parse } = attemptFor(prompt, label);
+        io.writer.write(question);
+        // A prompt is a conversation: the next question depends on the last answer, which is
+        // what sequential means. Promise.all() would ask all five at once and read none.
+        // eslint-disable-next-line reliability/no-await-in-loop -- see above
+        const line = await io.reader.line({ hidden: prompt.kind === 'password' });
+        if (line === undefined)
+            return CANCELLED;
+        const result = parse(line);
+        if (result.ok)
+            return { ok: true, value: result.value };
+        io.writer.write(`  ${result.problem}\n`);
+    }
+    io.writer.write(`  giving up after ${MAX_ATTEMPTS} attempts\n`);
+    return CANCELLED;
+}
+/**
+ * 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.
+ */
+export function projection(spec) {
+    const { question } = attemptFor(spec, spec.message);
+    return question.trimEnd();
+}
+//# sourceMappingURL=ask.js.map

package/dist/binding.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ *
+ * The design sketched this as `caique/burgee`, one binding per host. It is one binding for
+ * all of them instead, and that is the better answer: what a host actually supplies is a
+ * record of options, the values parsed so far, and a runtime. None of that needs burgee's
+ * types, so nothing here imports them — which keeps the family's rule that no package
+ * requires another, and means `burgee`, `burgee/commander` and `burgee/yargs` share one
+ * implementation rather than three that drift.
+ *
+ * The order is the declaration order, because `--interactive` asks for several things at
+ * once and a person answering them needs the sequence to match the help they just read.
+ */
+import { type Io } from './ask.js';
+import { type Flags, type Runtime } from './decide.js';
+import { type PromptSpec } from './spec.js';
+/** What a host tells us about one option. Structural: any framework's spec satisfies it. */
+export interface PromptableOption {
+    required?: boolean;
+    prompt?: PromptSpec;
+}
+export 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;
+}
+export interface ResolveFailure {
+    option: string;
+    code: 'USAGE' | 'CANCELLED';
+    message: string;
+    fix?: string;
+}
+export 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;
+}
+/**
+ * Walk the command's options in order, asking only what has to be asked.
+ *
+ * Stops at the first refusal: the caller is about to exit, and a person told about six
+ * missing flags — one of which they would have answered interactively — has been given a
+ * worse message than one told about the first.
+ */
+export declare function resolvePrompts<O extends PromptableOption>({ options, values, runtime, flags, io }: ResolveInput<O>): Promise<Resolved>;

package/dist/binding.js

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ *
+ * The design sketched this as `caique/burgee`, one binding per host. It is one binding for
+ * all of them instead, and that is the better answer: what a host actually supplies is a
+ * record of options, the values parsed so far, and a runtime. None of that needs burgee's
+ * types, so nothing here imports them — which keeps the family's rule that no package
+ * requires another, and means `burgee`, `burgee/commander` and `burgee/yargs` share one
+ * implementation rather than three that drift.
+ *
+ * The order is the declaration order, because `--interactive` asks for several things at
+ * once and a person answering them needs the sequence to match the help they just read.
+ */
+import { ask } from './ask.js';
+import { decide } from './decide.js';
+import { problemWith } from './spec.js';
+/**
+ * One option's verdict, before any terminal is consulted. A spec that cannot be drawn is
+ * caught here rather than in the widget: better to say so than to draw an empty list and
+ * wait, which is the hang this package exists to prevent.
+ */
+function verdictFor({ option, prompt, required, value, runtime, flags }) {
+    const malformed = problemWith(prompt);
+    if (malformed !== undefined)
+        return { option, code: 'USAGE', message: `--${option} has a prompt that cannot be drawn: ${malformed}`, fix: 'fix the prompt spec where the option is declared' };
+    const verdict = decide({ value, spec: prompt, option, runtime, ...(flags === undefined ? {} : { flags }), required });
+    if (verdict.action === 'error')
+        return { option, code: 'USAGE', message: verdict.message ?? '', ...(verdict.fix === undefined ? {} : { fix: verdict.fix }) };
+    return verdict;
+}
+const isFailure = (v) => !('action' in v);
+/**
+ * Walk the command's options in order, asking only what has to be asked.
+ *
+ * Stops at the first refusal: the caller is about to exit, and a person told about six
+ * missing flags — one of which they would have answered interactively — has been given a
+ * worse message than one told about the first.
+ */
+export async function resolvePrompts({ options, values, runtime, flags, io }) {
+    const out = { ...values };
+    for (const [option, spec] of Object.entries(options)) {
+        const prompt = spec.prompt;
+        if (prompt === undefined)
+            continue;
+        const verdict = verdictFor({ option, prompt, required: spec.required === true, value: out[option], runtime, flags });
+        if (isFailure(verdict))
+            return { values: out, failure: verdict };
+        if (verdict.action === 'skip')
+            continue;
+        if (verdict.action === 'answer') {
+            out[option] = verdict.value;
+            continue;
+        }
+        // Asked one at a time on purpose: a person answers in sequence, and asking the second
+        // question before the first is answered would interleave two prompts on one terminal.
+        // eslint-disable-next-line reliability/no-await-in-loop -- see above
+        const answer = await ask(prompt, io);
+        if (!answer.ok) {
+            return { values: out, failure: { option, code: 'CANCELLED', message: `cancelled at --${option}`, fix: `pass --${option} to skip the question` } };
+        }
+        out[option] = answer.value;
+    }
+    return { values: out };
+}
+//# sourceMappingURL=binding.js.map

package/dist/decide.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Whether to prompt at all (R2, R3, R6) — the one decision this package exists to get
+ * right, and the only one that has to be correct before a single character is drawn.
+ *
+ * **An agent asked to type is an agent that hangs.** Every prompt library assumes a person
+ * is there; when one is not, the process waits on a stdin that will never produce a line,
+ * and the caller sees a timeout with no output and no clue. That is the failure this
+ * function refuses to allow: with no terminal, a missing value is an *error naming the
+ * flag*, immediately, in words the caller can act on.
+ *
+ * It is pure — a value, a runtime slice and the flags in, a verdict out — so the whole
+ * truth table is a unit test rather than a PTY. `decide.test.ts` walks all of it.
+ */
+import { type PromptSpec } from './spec.js';
+/** The slice of a runtime this needs. burgee's satisfies it; so does a literal in a test. */
+export interface Runtime {
+    env: Record<string, string | undefined>;
+    isTTY: {
+        stdin: boolean;
+    };
+}
+/** What the run was asked for, as the engine knows it — never sniffed from the process. */
+export 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;
+}
+export 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;
+}
+export 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;
+    runtime: Runtime;
+    flags?: Flags;
+    /** Whether the option must have a value for the command to run. */
+    required?: boolean;
+}
+/**
+ * The rule, in order, and the order is the argument:
+ *
+ *  1. A value from any source wins. Prompting for something already answered is how a
+ *     script that sets an env var still ends up waiting for input.
+ *  2. `--json` never prompts. It means "a machine is reading this", and there is no
+ *     answer a machine can type.
+ *  3. `--yes` answers a `confirm`, and only a `confirm` — it is not a licence to invent
+ *     a path or a password.
+ *  4. No terminal on stdin, or `CI` set, means nobody is there: refuse, naming the flag.
+ *  5. `--interactive` reaches past 4 only when there *is* a terminal; it is an override
+ *     for "you would not have asked", never for "there is no one to ask".
+ *  6. Otherwise, if it is required or `--interactive` was asked for, prompt.
+ */
+export declare function decide({ value, spec, option, runtime, flags, required }: DecideInput): Decision;

package/dist/decide.js

@@ -0,0 +1,69 @@
+/**
+ * Whether to prompt at all (R2, R3, R6) — the one decision this package exists to get
+ * right, and the only one that has to be correct before a single character is drawn.
+ *
+ * **An agent asked to type is an agent that hangs.** Every prompt library assumes a person
+ * is there; when one is not, the process waits on a stdin that will never produce a line,
+ * and the caller sees a timeout with no output and no clue. That is the failure this
+ * function refuses to allow: with no terminal, a missing value is an *error naming the
+ * flag*, immediately, in words the caller can act on.
+ *
+ * It is pure — a value, a runtime slice and the flags in, a verdict out — so the whole
+ * truth table is a unit test rather than a PTY. `decide.test.ts` walks all of it.
+ */
+import { flagOf } from './spec.js';
+const SKIP = { action: 'skip' };
+const PROMPT = { action: 'prompt' };
+/** Present and not empty — the same convention roundel's policy applies to every switch. */
+const set = (value) => value !== undefined && value !== '';
+/** A value from any source at all: a flag, an env var, a config file, a default. */
+function alreadyAnswered(value) {
+    // `false` and `0` and `''` are answers. Only "nothing was supplied" is not.
+    return value !== undefined && value !== null;
+}
+/**
+ * The rule, in order, and the order is the argument:
+ *
+ *  1. A value from any source wins. Prompting for something already answered is how a
+ *     script that sets an env var still ends up waiting for input.
+ *  2. `--json` never prompts. It means "a machine is reading this", and there is no
+ *     answer a machine can type.
+ *  3. `--yes` answers a `confirm`, and only a `confirm` — it is not a licence to invent
+ *     a path or a password.
+ *  4. No terminal on stdin, or `CI` set, means nobody is there: refuse, naming the flag.
+ *  5. `--interactive` reaches past 4 only when there *is* a terminal; it is an override
+ *     for "you would not have asked", never for "there is no one to ask".
+ *  6. Otherwise, if it is required or `--interactive` was asked for, prompt.
+ */
+export function decide({ value, spec, option, runtime, flags = {}, required = false }) {
+    if (alreadyAnswered(value))
+        return SKIP;
+    const flag = flagOf(option);
+    const interactive = flags.interactive === true || flags.interactiveAll === true;
+    if (flags.json === true) {
+        return {
+            action: 'error',
+            code: 'USAGE',
+            message: `${flag} is required under --json`,
+            fix: `pass ${flag}; --json means no one is here to answer "${spec.message}"`,
+        };
+    }
+    if (flags.yes === true && spec.kind === 'confirm')
+        return { action: 'answer', value: true };
+    const nobodyThere = !runtime.isTTY.stdin || set(runtime.env['CI']);
+    if (nobodyThere) {
+        // `--interactive` cannot conjure a person. Saying so is the difference between a
+        // useful refusal and a flag that looks like it did nothing.
+        const because = interactive ? ' (--interactive needs a terminal on stdin)' : '';
+        return {
+            action: 'error',
+            code: 'USAGE',
+            message: `${flag} is required when there is no terminal${because}`,
+            fix: `pass ${flag}; it would have been asked as "${spec.message}"`,
+        };
+    }
+    if (required || interactive)
+        return PROMPT;
+    return SKIP;
+}
+//# sourceMappingURL=decide.js.map

package/dist/index.d.ts

@@ -1,6 +1,12 @@
 /**
- * caique — reserved. The first working release follows
- * docs/intents/cli-prompts/ in the burgee repository. Until then this entry
- * exports only its own name, so that importing it costs nothing and promises nothing.
+ * 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/`.
  */
-export declare const name: "caique";
+export * from './ask.js';
+export * from './binding.js';
+export * from './decide.js';
+export * from './raw.js';
+export * from './spec.js';
+export * from './terminal.js';

package/dist/index.js

@@ -1,7 +1,13 @@
 /**
- * caique — reserved. The first working release follows
- * docs/intents/cli-prompts/ in the burgee repository. Until then this entry
- * exports only its own name, so that importing it costs nothing and promises nothing.
+ * 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/`.
  */
-export const name = 'caique';
+export * from './ask.js';
+export * from './binding.js';
+export * from './decide.js';
+export * from './raw.js';
+export * from './spec.js';
+export * from './terminal.js';
 //# sourceMappingURL=index.js.map

package/dist/raw.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The raw-mode renderer: arrow keys and a moving highlight for `select` and `multiselect`,
+ * on a terminal that can take them.
+ *
+ * **It answers the same questions `ask()` does, and returns the same answers.** That is the
+ * whole arrangement: line mode is the floor (R5), this sits on top, and a caller chooses
+ * between them by asking whether the terminal is one. Anything this can do that line mode
+ * cannot is decoration; anything line mode can do that this cannot would be a bug.
+ *
+ * **On the dependency the design named.** It said "spinner from flagstaff", and this does
+ * not import flagstaff. A prompt has no spinner — it is waiting for a person, not for work
+ * — and the repaint it needs is three escape sequences, written here. Importing flagstaff
+ * to get them would make the one package that talks to a human the only one in the family
+ * that requires a sibling, which is the rule `caique`'s own README states. If a prompt ever
+ * needs to show progress *while* it waits, that is a caller composing `hoist()` around
+ * `ask()`, not this file reaching for it.
+ */
+import { type Asked, type Io } from './ask.js';
+import { type Choice, type PromptSpec } from './spec.js';
+/** A stream that can be put into raw mode and read a key at a time. */
+export interface KeyStream {
+    isTTY?: 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;
+}
+export type Key = 'up' | 'down' | 'space' | 'enter' | 'cancel' | 'other';
+/**
+ * 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.
+ */
+export declare function keyOf(data: string): Key;
+export interface RawIo extends Io {
+    keys: KeyStream;
+}
+/** Whether this runtime can drive the raw renderer at all. */
+export declare function canRender(keys: KeyStream): boolean;
+interface ListState {
+    cursor: number;
+    selected: Set<number>;
+}
+/** One frame of the list. Exported so a test asserts the drawing rather than a screenshot. */
+export declare function renderList(spec: PromptSpec, choices: Choice[], state: ListState, multi: boolean): string;
+/**
+ * Drive a list prompt with the arrow keys, repainting in place.
+ *
+ * Returns the same `Asked` shape `ask()` does, so a caller can swap the two without
+ * knowing which ran — and cancels the same way, because `Ctrl-C` in raw mode is a byte and
+ * not a signal, and a person who presses it means to leave.
+ */
+export declare function askList(spec: PromptSpec, io: RawIo, multi?: boolean): Promise<Asked>;
+export {};

package/dist/raw.js

@@ -0,0 +1,146 @@
+/**
+ * The raw-mode renderer: arrow keys and a moving highlight for `select` and `multiselect`,
+ * on a terminal that can take them.
+ *
+ * **It answers the same questions `ask()` does, and returns the same answers.** That is the
+ * whole arrangement: line mode is the floor (R5), this sits on top, and a caller chooses
+ * between them by asking whether the terminal is one. Anything this can do that line mode
+ * cannot is decoration; anything line mode can do that this cannot would be a bug.
+ *
+ * **On the dependency the design named.** It said "spinner from flagstaff", and this does
+ * not import flagstaff. A prompt has no spinner — it is waiting for a person, not for work
+ * — and the repaint it needs is three escape sequences, written here. Importing flagstaff
+ * to get them would make the one package that talks to a human the only one in the family
+ * that requires a sibling, which is the rule `caique`'s own README states. If a prompt ever
+ * needs to show progress *while* it waits, that is a caller composing `hoist()` around
+ * `ask()`, not this file reaching for it.
+ */
+import {} from './ask.js';
+import {} from './spec.js';
+const ESC = '\u001B';
+const CSI = `${ESC}[`;
+const HIDE_CURSOR = `${CSI}?25l`;
+const SHOW_CURSOR = `${CSI}?25h`;
+/** Column 1, up `n` lines, clear to the end of the screen — the only repaint this needs. */
+const erase = (lines) => `${CSI}1G${lines > 1 ? `${CSI}${lines - 1}A` : ''}${CSI}0J`;
+/**
+ * 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.
+ */
+export function keyOf(data) {
+    if (data === `${CSI}A` || data === 'k')
+        return 'up';
+    if (data === `${CSI}B` || data === 'j')
+        return 'down';
+    if (data === ' ')
+        return 'space';
+    if (data === '\r' || data === '\n')
+        return 'enter';
+    // Ctrl-C and Ctrl-D. In raw mode the terminal delivers these as bytes rather than
+    // signals, so a widget that did not read them would leave a person unable to leave.
+    if (data === '\u0003' || data === '\u0004' || data === ESC)
+        return 'cancel';
+    return 'other';
+}
+/** Whether this runtime can drive the raw renderer at all. */
+export function canRender(keys) {
+    return keys.isTTY === true && typeof keys.setRawMode === 'function';
+}
+const MARK = { on: '◉', off: '◯' };
+const POINTER = '❯';
+const CANCELLED = { ok: false, reason: 'cancelled' };
+/** The `◉`/`◯` column, which only a multiselect has. Empty for a single select. */
+function markFor(state, index, multi) {
+    if (!multi)
+        return '';
+    return `${state.selected.has(index) ? MARK.on : MARK.off} `;
+}
+/** One frame of the list. Exported so a test asserts the drawing rather than a screenshot. */
+export function renderList(spec, choices, state, multi) {
+    const rows = choices.map((choice, index) => {
+        const pointer = index === state.cursor ? POINTER : ' ';
+        const hint = choice.hint === undefined ? '' : ` — ${choice.hint}`;
+        return `${pointer} ${markFor(state, index, multi)}${choice.label ?? choice.value}${hint}`;
+    });
+    return [spec.message, ...rows].join('\n');
+}
+const clamp = (index, length) => (index + length) % length;
+/**
+ * Apply a navigation key, and say whether anything changed — a key with no meaning here
+ * changes nothing and repaints nothing, which is what a person expects from a key they
+ * pressed by accident.
+ */
+function moved(key, state, length, multi) {
+    if (key === 'up') {
+        state.cursor = clamp(state.cursor - 1, length);
+        return true;
+    }
+    if (key === 'down') {
+        state.cursor = clamp(state.cursor + 1, length);
+        return true;
+    }
+    if (key !== 'space' || !multi)
+        return false;
+    if (state.selected.has(state.cursor))
+        state.selected.delete(state.cursor);
+    else
+        state.selected.add(state.cursor);
+    return true;
+}
+/** What enter answers with. List order, not press order: a set of choices has no sequence. */
+function chosen(choices, state, multi) {
+    if (!multi)
+        return choices[state.cursor]?.value ?? '';
+    return [...state.selected].sort((a, b) => a - b).map((index) => choices[index]?.value ?? '');
+}
+/**
+ * Drive a list prompt with the arrow keys, repainting in place.
+ *
+ * Returns the same `Asked` shape `ask()` does, so a caller can swap the two without
+ * knowing which ran — and cancels the same way, because `Ctrl-C` in raw mode is a byte and
+ * not a signal, and a person who presses it means to leave.
+ */
+export async function askList(spec, io, multi = false) {
+    const choices = spec.choices ?? [];
+    const state = { cursor: 0, selected: new Set() };
+    let painted = 0;
+    const paint = () => {
+        const frame = renderList(spec, choices, state, multi);
+        io.writer.write((painted === 0 ? HIDE_CURSOR : erase(painted)) + frame);
+        painted = frame.split('\n').length;
+    };
+    io.keys.setRawMode?.(true);
+    io.keys.resume?.();
+    paint();
+    try {
+        return await new Promise((resolve) => {
+            const onData = (chunk) => {
+                const key = keyOf(String(chunk));
+                if (key === 'cancel') {
+                    done(CANCELLED);
+                    return;
+                }
+                if (key === 'enter') {
+                    done({ ok: true, value: chosen(choices, state, multi) });
+                    return;
+                }
+                if (moved(key, state, choices.length, multi))
+                    paint();
+            };
+            const done = (answer) => {
+                io.keys.off('data', onData);
+                // Leave the answered question on screen, the cursor back, and the terminal as it
+                // was found: a prompt that exits in raw mode leaves the shell unusable.
+                io.writer.write(`${erase(painted)}${renderList(spec, choices, state, multi)}\n${SHOW_CURSOR}`);
+                resolve(answer);
+            };
+            io.keys.on('data', onData);
+        });
+    }
+    finally {
+        io.keys.setRawMode?.(false);
+        io.keys.pause?.();
+    }
+}
+//# sourceMappingURL=raw.js.map

package/dist/spec.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What a prompt *is*, before anything draws one (R1).
+ *
+ * A `PromptSpec` hangs off an option, not off a call site, and that is the whole
+ * inversion: the option is the thing that exists in the manifest, in `--help`, in the MCP
+ * tool schema and on the command line, and the prompt is one more projection of it. A
+ * program written this way can be answered by a flag, by an environment variable, by a
+ * config file or by a person, and nothing in it has to know which happened.
+ *
+ * Nothing here imports a runtime, a stream or a terminal. This file is data.
+ */
+/** The six kinds a prompt can be. Anything more is a wizard, which is out of scope. */
+export type PromptKind = 'text' | 'confirm' | 'select' | 'multiselect' | 'password' | 'path';
+/** One choice in a `select` or `multiselect`. `value` is what the option receives. */
+export interface Choice {
+    value: string;
+    label?: string;
+    hint?: string;
+}
+export 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;
+}
+/** A prompt spec bound to the option it answers. */
+export interface BoundPrompt extends PromptSpec {
+    /** The option's long name, without dashes — `output-dir`, not `--output-dir`. */
+    option: string;
+}
+/** `--output-dir`, which is what a refusal has to say to be actionable. */
+export declare function flagOf(option: string): string;
+/**
+ * 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.
+ */
+export declare function problemWith(spec: PromptSpec): string | undefined;

package/dist/spec.js

@@ -0,0 +1,31 @@
+/**
+ * What a prompt *is*, before anything draws one (R1).
+ *
+ * A `PromptSpec` hangs off an option, not off a call site, and that is the whole
+ * inversion: the option is the thing that exists in the manifest, in `--help`, in the MCP
+ * tool schema and on the command line, and the prompt is one more projection of it. A
+ * program written this way can be answered by a flag, by an environment variable, by a
+ * config file or by a person, and nothing in it has to know which happened.
+ *
+ * Nothing here imports a runtime, a stream or a terminal. This file is data.
+ */
+/** `--output-dir`, which is what a refusal has to say to be actionable. */
+export function flagOf(option) {
+    return `--${option}`;
+}
+/**
+ * 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.
+ */
+export function problemWith(spec) {
+    const needsChoices = spec.kind === 'select' || spec.kind === 'multiselect';
+    if (needsChoices && (spec.choices === undefined || spec.choices.length === 0))
+        return `a ${spec.kind} prompt needs a non-empty \`choices\` array`;
+    if (!needsChoices && spec.choices !== undefined)
+        return `a ${spec.kind} prompt has no use for \`choices\``;
+    if (spec.message.trim() === '')
+        return 'a prompt needs a message: it is what a person is asked, and what an agent is told when it cannot be';
+    return undefined;
+}
+//# sourceMappingURL=spec.js.map

package/dist/terminal.d.ts

@@ -0,0 +1,20 @@
+import { type Io } from './ask.js';
+/** The stream pair a terminal Io is built over: `process.stdin` and `process.stdout`. */
+export interface Streams {
+    input: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    output: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+}
+/**
+ * A reader and writer over a real stream pair.
+ *
+ * The reader resolves `undefined` when the stream ends, which `ask()` reads as a
+ * cancellation — `Ctrl-D` and a closed pipe both arrive that way, and both mean nobody is
+ * going to type.
+ */
+export declare function createIo(streams: Streams): Io & {
+    close: () => void;
+};

package/dist/terminal.js

@@ -0,0 +1,81 @@
+/**
+ * A `Reader` and `Writer` over real streams — the one file in this package that touches a
+ * terminal, and the reason `ask()` can be used by a program rather than only by a test.
+ *
+ * Everything above this is strings in and strings out. That is deliberate: the widgets, the
+ * decision and the binding are all testable without a PTY, and this is the thin layer that
+ * has to be got right once. It reads lines through `node:readline`, which handles the
+ * line editing, the backspace and the `Ctrl-D` a person expects.
+ *
+ * **Hiding a password happens here**, because this is the only layer that knows what echo
+ * is. `ask()` says which prompts are hidden; nothing above has to remember to mute anything,
+ * and a widget cannot leak a secret by writing it, since no widget writes what it read.
+ */
+import { createInterface } from 'node:readline';
+import {} from './ask.js';
+/** Accepts a chunk and writes nothing: what a muted stream's `write` does. */
+const swallow = () => true;
+/**
+ * `readline` echoes what it reads. For a hidden answer the echo is suppressed by
+ * intercepting the interface's own output for the duration of the question — not by
+ * turning the terminal's echo off, which would leave it off if the process died mid-prompt.
+ */
+function mute(rl, streams) {
+    const target = rl.output ?? streams.output;
+    const original = target.write.bind(target);
+    // `readline` writes the prompt through the same stream it echoes through, so the prompt
+    // has already been written by the time this is installed: everything after it is input.
+    target.write = swallow;
+    return () => {
+        target.write = original;
+    };
+}
+/**
+ * A reader and writer over a real stream pair.
+ *
+ * The reader resolves `undefined` when the stream ends, which `ask()` reads as a
+ * cancellation — `Ctrl-D` and a closed pipe both arrive that way, and both mean nobody is
+ * going to type.
+ */
+export function createIo(streams) {
+    const rl = createInterface({ input: streams.input, output: streams.output, terminal: streams.output.isTTY === true });
+    let ended = false;
+    rl.once('close', () => {
+        ended = true;
+    });
+    const reader = {
+        line: async ({ hidden = false } = {}) => {
+            if (ended)
+                return undefined;
+            const unmute = hidden ? mute(rl, streams) : undefined;
+            try {
+                return await new Promise((resolve) => {
+                    const onLine = (value) => {
+                        rl.off('close', onClose);
+                        resolve(value);
+                    };
+                    const onClose = () => {
+                        rl.off('line', onLine);
+                        resolve(undefined);
+                    };
+                    rl.once('line', onLine);
+                    rl.once('close', onClose);
+                });
+            }
+            finally {
+                unmute?.();
+                // The newline the person typed was swallowed with the echo; put it back so the
+                // next question does not start on the same line as the hidden answer.
+                if (hidden)
+                    streams.output.write('\n');
+            }
+        },
+    };
+    const writer = {
+        write: (text) => {
+            streams.output.write(text);
+        },
+    };
+    return { reader, writer, close: () => rl.close() };
+}
+//# sourceMappingURL=terminal.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caique",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "The parrot that always answers back, and the boat that goes between ship and shore. Prompts that are flags first, so agents answer before they are asked and non-TTY callers get an error naming the flag, never a hang. Drop-in path for inquirer and clack.",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,36 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./ask": {
+      "types": "./dist/ask.d.ts",
+      "import": "./dist/ask.js",
+      "default": "./dist/ask.js"
+    },
+    "./binding": {
+      "types": "./dist/binding.d.ts",
+      "import": "./dist/binding.js",
+      "default": "./dist/binding.js"
+    },
+    "./decide": {
+      "types": "./dist/decide.d.ts",
+      "import": "./dist/decide.js",
+      "default": "./dist/decide.js"
+    },
+    "./raw": {
+      "types": "./dist/raw.d.ts",
+      "import": "./dist/raw.js",
+      "default": "./dist/raw.js"
+    },
+    "./spec": {
+      "types": "./dist/spec.d.ts",
+      "import": "./dist/spec.js",
+      "default": "./dist/spec.js"
+    },
+    "./terminal": {
+      "types": "./dist/terminal.d.ts",
+      "import": "./dist/terminal.js",
+      "default": "./dist/terminal.js"
     }
   },
   "files": [
@@ -23,6 +53,7 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run --passWithNoTests",
+    "coverage": "vitest run --coverage.enabled",
     "lint": "eslint src"
   },
   "repository": {
@@ -46,6 +77,6 @@
     "non-tty"
   ],
   "devDependencies": {
-    "vitest": "^4.0.0"
+    "vitest": "^5.0.0"
   }
 }