caique 0.1.0 → 0.2.0

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,4 +1,22 @@
-# 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>
+
+<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/dependencies-closeout-0a6b47?style=flat-square" alt="One dependency: closeout" />
+  <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).
@@ -17,12 +35,13 @@ 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: { env: process.env, isTTY: { stdin: process.stdin.isTTY } },
+  runtime: processRuntime(),                         // or your own { env, isTTY: { stdin } }
   required: true,
 });
 // no terminal -> { action: 'error', code: 'USAGE',
@@ -83,7 +102,7 @@ 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 } },
+  runtime: processRuntime(),
   flags: { json, yes, interactive },
   io: { reader, writer },
 });
@@ -107,7 +126,7 @@ that touches a terminal:
 import { createIo } from 'caique/terminal';
 import { ask } from 'caique/ask';
 
-const io = createIo({ input: process.stdin, output: process.stdout });
+const io = createIo();   // the terminal the program was started in
 await ask({ kind: 'password', message: 'Token?' }, io);
 io.close();
 ```
@@ -126,9 +145,11 @@ not a second implementation:
 
 ```js
 import { askList, canRender } from 'caique/raw';
-import { createIo } from 'caique/terminal';
+import { createIo, streamsOf } from 'caique/terminal';
+import { processRuntime } from 'caique';
 
-const io = { ...createIo({ input: process.stdin, output: process.stdout }), keys: process.stdin };
+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);
 ```
@@ -172,8 +193,76 @@ counted whole across its own resolved tree.
 - **`--interactive`** asks for every missing required option in one pass; **`--yes`** accepts
   every confirmation; cancellation exits `CANCELLED` and restores the terminal.
 - **Accessible mode** falls back to line input with no live redraw.
-- **Drop-in paths** for inquirer and clack, graded by their own suites.
+- **A migration path from `@inquirer/prompts` and `@clack/prompts`**, graded by their own
+  suites. See below for what that is graded at today, which is zero.
+
+## Which incumbents this is 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.
+
+| Incumbent's suite | Cases | Their own package | `caique` |
+| :-- | --: | --: | --: |
+| [`@inquirer/core` 12.0.3](https://github.com/SBoudrias/Inquirer.js) | 41 | 41 (100%) | **0 (0.0%)** |
+| [`@clack/prompts` 1.8.1](https://github.com/bombshell-dev/clack) | 606 | 576 (95.0%) | **0 (0.0%)** |
+
+Measured 2026-09-14 by `npm run compat`, which runs each incumbent's own unedited suite
+twice: once against the incumbent (the control — the column that proves the gate works)
+and once against caique. **Both caique columns are zero, and they are zero because no
+façade exists yet** — `caique` exports `ask`, `decide` and `spec`, not `createPrompt` or
+`text` in their spelling. The row is here because a claimed replacement with no number
+beside it is a claim; this is the number, and it can only go up from here.
+
+The 30 cases `@clack/prompts` fails against itself are `path.test.ts`, which mocks
+`node:fs` in a way this repository's vitest does not reproduce — a harness divergence,
+recorded with its reason in `packages/compat-oracle/src/hosts.ts` rather than rounded away.
+
+## 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.
+caique installs one of them: [closeout](https://www.npmjs.com/package/closeout), because a
+prompt hides the cursor and owes it back however the process dies, and there is exactly one
+correct implementation of that. Nothing outside this repository is installed.
+
+MIT © Ofri Peretz — see [LICENSE](./LICENSE).
+
+## Benchmarks
+
+Every number here is produced by `npm run bench` and published at [/docs/benchmarks](/docs/benchmarks).
+
+Graded by the incumbent's own test suite:
+
+| suite | passing |
+| :-- | --: |
+| `clack` | 0 / 606 |
+| `inquirer-core` | 0 / 41 |
+
+Weight, installed and tree-inclusive: **84,740 bytes** against **182,219** for the incumbents it replaces — a ratio of **0.4650** (@inquirer/core not installed here, so the ceiling is understated).
+
+That ratio is not yet a claim: nothing here passes an incumbent suite, so it is the weight of a package that does not do the job.
+## Where it sits
+
+Plugins register under the `widgets` key, against the one schema the whole family shares.
 
-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.
+Nothing in this family builds on it yet, and it builds on `closeout`.

package/dist/index.d.ts

@@ -10,3 +10,9 @@ export * from './decide.js';
 export * from './raw.js';
 export * from './spec.js';
 export * from './terminal.js';
+/**
+ * Named, not starred: `runtime.ts` and `decide.ts` both call their slice `Runtime`, and two
+ * star exports of one name is an ambiguity TypeScript resolves by dropping it. The root
+ * keeps `decide`'s — the one a caller of `decide()` constructs — and takes the function.
+ */
+export { processRuntime } from './runtime.js';

package/dist/index.js

@@ -10,4 +10,10 @@ export * from './decide.js';
 export * from './raw.js';
 export * from './spec.js';
 export * from './terminal.js';
+/**
+ * Named, not starred: `runtime.ts` and `decide.ts` both call their slice `Runtime`, and two
+ * star exports of one name is an ambiguity TypeScript resolves by dropping it. The root
+ * keeps `decide`'s — the one a caller of `decide()` constructs — and takes the function.
+ */
+export { processRuntime } from './runtime.js';
 //# sourceMappingURL=index.js.map

package/dist/plugin.d.ts

@@ -0,0 +1,81 @@
+import { type PromptSpec } from './spec.js';
+/**
+ * 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.
+ */
+export declare const CONTRACT = 1;
+/**
+ * Two named states of plain data, which a grader renders a widget with (R7).
+ *
+ * It carries no behaviour, so reading it does not mean running the author's code — that is
+ * why an optional `sample` does not turn a plugin into a program.
+ */
+export interface WidgetSample {
+    running: unknown;
+    done: unknown;
+}
+/**
+ * How a plugin draws one kind of prompt.
+ *
+ * `static(spec)` is what a pipe, an agent and a screen reader get; it is what `projection()`
+ * already returns for the six built-ins, so a plugin widget slots into the same surface
+ * rather than beside it. `frame` is optional and drives `caique/raw`.
+ */
+export interface Widget {
+    static: (spec: PromptSpec) => string;
+    frame?: (t: number, spec: PromptSpec) => string;
+    sample?: WidgetSample;
+}
+/**
+ * The keys caique reads. Declared structurally: any object with these fields is a plugin
+ * here, whatever else it carries.
+ */
+export interface Plugin {
+    name: string;
+    contract?: number;
+    widgets?: Record<string, Widget>;
+}
+export type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT' | 'E_NO_STATIC_PROJECTION' | 'E_UNKNOWN_KIND';
+/** A refused plugin says what is wrong and what to do about it — the family's one vocabulary. */
+export declare class PluginError extends Error {
+    readonly code: PluginErrorCode;
+    readonly fix: string;
+    constructor(code: PluginErrorCode, message: string, fix: string);
+}
+/**
+ * Refuse a plugin that cannot contribute a widget, at the door.
+ *
+ * Every refusal here is about the `widgets` key or the plugin's own identity. A key another
+ * layer owns is not inspected and not rejected (R1) — caique has no opinion about a spinner.
+ */
+export declare function validate(plugin: unknown): asserts plugin is Plugin;
+/** Which plugin last contributed each kind — the shadowing a `plugin check` prints. */
+export interface Contribution {
+    kind: string;
+    from: string;
+    /** Plugins that contributed this kind earlier and were overridden, in order. */
+    shadowed: string[];
+}
+/**
+ * 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.
+ */
+export declare function register(plugin: unknown): void;
+/** Forget every registered plugin. For tests, and for a program that re-registers at runtime. */
+export declare function reset(): void;
+/** The plugins registered, in registration order. */
+export declare function registered(): readonly Plugin[];
+/** Every kind a plugin contributed, with who won it and who it shadowed. */
+export declare function widgets(): Contribution[];
+/** The widget that draws `kind`, or nothing when no plugin registered one. */
+export declare function widgetFor(kind: string): Widget | undefined;
+/** Every kind that can be drawn right now: the six, plus whatever is registered. */
+export declare function kinds(): string[];
+/**
+ * The static projection for *any* kind — the one surface a caller needs.
+ *
+ * The six are still drawn by caique; anything else is a registered widget's `static`. A
+ * kind that is neither is a refusal naming what *is* registered, so the reader can see the
+ * typo rather than a text prompt where their rating widget should have been.
+ */
+export declare function projectionOf(spec: PromptSpec): string;

package/dist/plugin.js

@@ -0,0 +1,163 @@
+/**
+ * The plugin host for caique's half of the contract (`plugin-contract` R1, R5, R6, R7, R8).
+ *
+ * A plugin is one plain object shared by the whole family. This file keeps the key caique
+ * understands — `widgets`, a prompt kind and how to draw it — and **ignores every other key
+ * without complaining**, which is what makes the same object work on any subset of the
+ * family that is installed. A plugin written for flagstaff registers here and contributes
+ * its widgets; its `tokens`, `glyphs` and `components` are not caique's business and are
+ * not an error.
+ *
+ * **Nothing here imports another layer**, and the plugin shape is declared rather than
+ * imported (R3). Types erase, so an import would cost nothing at run time — and it would
+ * still put flagstaff in caique's dependency story, which is the one thing the family
+ * promises it does not do.
+ *
+ * **A widget is the same shape a flagstaff component is** — `{ static, frame?, sample? }` —
+ * and a widget without `static` is refused with `E_NO_STATIC_PROJECTION`, the same code and
+ * the same fix shape. That sameness is the whole content of R5: the moment the two shapes
+ * differ by a key, "the same shape" stops being a fact a lock can hold and becomes prose.
+ *
+ * **Why this file, and not `ask.ts`, raises `E_UNKNOWN_KIND`.** `PromptKind` is an open
+ * union now, so `{ kind: 'acme-rating' }` type-checks whether or not anyone can draw it.
+ * The refusal therefore has to happen where the registry is, and it has to be *loud*: a
+ * kind nobody registered rendered as a text prompt is the silent-wrong-answer failure this
+ * package exists to prevent, wearing a hat.
+ */
+import { projection } from './ask.js';
+import { BUILT_IN_KINDS } from './spec.js';
+/**
+ * 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.
+ */
+export const CONTRACT = 1;
+/** A refused plugin says what is wrong and what to do about it — the family's one vocabulary. */
+export class PluginError extends Error {
+    code;
+    fix;
+    constructor(code, message, fix) {
+        super(message);
+        this.code = code;
+        this.fix = fix;
+        this.name = 'PluginError';
+    }
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The six, in the order a person reads them — for the `fix` on an unknown kind. */
+const builtIns = () => [...BUILT_IN_KINDS].join(', ');
+/**
+ * Refuse a plugin that cannot contribute a widget, at the door.
+ *
+ * Every refusal here is about the `widgets` key or the plugin's own identity. A key another
+ * layer owns is not inspected and not rejected (R1) — caique has no opinion about a spinner.
+ */
+export function validate(plugin) {
+    if (!isRecord(plugin))
+        throw new PluginError('E_PLUGIN_SCHEMA', 'a plugin is a plain object', 'export an object, not a function or an array');
+    if (typeof plugin['name'] !== 'string' || plugin['name'] === '') {
+        throw new PluginError('E_PLUGIN_SCHEMA', 'a plugin needs a name', 'add `name: "…"` — it is how a shadowed widget is reported');
+    }
+    const contract = plugin['contract'];
+    if (contract !== undefined && (!Number.isInteger(contract) || contract > CONTRACT)) {
+        throw new PluginError('E_PLUGIN_CONTRACT', `plugin "${plugin['name']}" declares contract ${String(contract)}; this caique knows ${CONTRACT}`, 'upgrade caique, or lower the plugin’s contract');
+    }
+    validateWidgets(plugin['widgets'], plugin['name']);
+}
+function validateWidgets(widgetMap, name) {
+    if (widgetMap === undefined)
+        return;
+    if (!isRecord(widgetMap))
+        throw new PluginError('E_PLUGIN_SCHEMA', `plugin "${name}": widgets must be an object`, 'map a prompt kind to a widget: `{ static, frame?, sample? }`');
+    for (const [kind, widget] of Object.entries(widgetMap)) {
+        if (kind === '')
+            throw new PluginError('E_PLUGIN_SCHEMA', `plugin "${name}": a widget’s kind is empty`, 'name the kind — it is what a `PromptSpec` sets as `kind`');
+        /**
+         * A plugin may not replace one of the six. The built-ins are the accessible floor and
+         * the drop-in surface, and `password` in particular guarantees that nothing writes back
+         * what it read — a third party that could override it could defeat that from a config
+         * file. Extension is the space *outside* the six, which is exactly what widening
+         * `PromptKind` opened up.
+         */
+        if (BUILT_IN_KINDS.has(kind)) {
+            throw new PluginError('E_PLUGIN_SCHEMA', `plugin "${name}": "${kind}" is a built-in prompt kind`, `caique draws the six itself (${builtIns()}); name a kind of your own`);
+        }
+        if (!isRecord(widget))
+            throw new PluginError('E_PLUGIN_SCHEMA', `plugin "${name}": widget "${kind}" is not an object`, 'a widget is `{ static, frame?, sample? }`');
+        /** U3 everywhere else, and the reason a third-party prompt cannot break the non-TTY guarantee. */
+        if (typeof widget['static'] !== 'function') {
+            throw new PluginError('E_NO_STATIC_PROJECTION', `plugin "${name}": widget "${kind}" has no static projection`, 'add `static: (spec) => "…"` — it is what a pipe, an agent and a screen reader get');
+        }
+        if (widget['frame'] !== undefined && typeof widget['frame'] !== 'function') {
+            throw new PluginError('E_PLUGIN_SCHEMA', `plugin "${name}": widget "${kind}" has a \`frame\` that is not a function`, 'a frame is `(t, spec) => "…"`, or leave it out and the widget is line-mode only');
+        }
+        validateSample(widget['sample'], name, kind);
+    }
+}
+function validateSample(sample, name, kind) {
+    if (sample === undefined)
+        return;
+    if (!isRecord(sample) || !('running' in sample) || !('done' in sample)) {
+        throw new PluginError('E_PLUGIN_SCHEMA', `plugin "${name}": widget "${kind}" has a malformed \`sample\``, 'a sample is `{ running, done }` — two named states of plain data, which a grader renders the widget with');
+    }
+}
+const order = [];
+/**
+ * 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.
+ */
+export function register(plugin) {
+    validate(plugin);
+    order.push(plugin);
+}
+/** Forget every registered plugin. For tests, and for a program that re-registers at runtime. */
+export function reset() {
+    order.length = 0;
+}
+/** The plugins registered, in registration order. */
+export function registered() {
+    return order;
+}
+/** Every kind a plugin contributed, with who won it and who it shadowed. */
+export function widgets() {
+    const by = new Map();
+    for (const plugin of order) {
+        for (const kind of Object.keys(plugin.widgets ?? {})) {
+            const existing = by.get(kind);
+            by.set(kind, { kind, from: plugin.name, shadowed: existing === undefined ? [] : [...existing.shadowed, existing.from] });
+        }
+    }
+    return [...by.values()];
+}
+/** The widget that draws `kind`, or nothing when no plugin registered one. */
+export function widgetFor(kind) {
+    // Walked backwards because later wins, and the first hit from the end is the winner.
+    for (let i = order.length - 1; i >= 0; i -= 1) {
+        const widget = order[i].widgets?.[kind];
+        if (widget !== undefined)
+            return widget;
+    }
+    return undefined;
+}
+/** Every kind that can be drawn right now: the six, plus whatever is registered. */
+export function kinds() {
+    return [...BUILT_IN_KINDS, ...widgets().map((c) => c.kind)];
+}
+/**
+ * The static projection for *any* kind — the one surface a caller needs.
+ *
+ * The six are still drawn by caique; anything else is a registered widget's `static`. A
+ * kind that is neither is a refusal naming what *is* registered, so the reader can see the
+ * typo rather than a text prompt where their rating widget should have been.
+ */
+export function projectionOf(spec) {
+    if (BUILT_IN_KINDS.has(spec.kind))
+        return projection(spec);
+    const widget = widgetFor(spec.kind);
+    if (widget === undefined) {
+        const known = widgets().map((c) => c.kind);
+        const named = known.length === 0 ? 'no plugin has registered a widget' : `registered kinds: ${known.join(', ')}`;
+        throw new PluginError('E_UNKNOWN_KIND', `no widget draws prompt kind ${JSON.stringify(spec.kind)} — ${named}`, `register a plugin whose \`widgets\` defines ${JSON.stringify(spec.kind)}, or use a built-in kind: ${builtIns()}`);
+    }
+    return widget.static(spec).trimEnd();
+}
+//# sourceMappingURL=plugin.js.map

package/dist/raw.d.ts

@@ -1,20 +1,3 @@
-/**
- * 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. */
@@ -50,6 +33,9 @@ export declare function renderList(spec: PromptSpec, choices: Choice[], state: L
  * 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.
+ *
+ * The cursor is hidden through `closeout`: the byte path resolves and `restore()` runs in
+ * the `finally`; every path that never reaches the `finally` is the exit hook's.
  */
 export declare function askList(spec: PromptSpec, io: RawIo, multi?: boolean): Promise<Asked>;
 export {};

package/dist/raw.js

@@ -7,20 +7,23 @@
  * 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.
+ * **On its one dependency.** The design said "spinner from flagstaff"; this imports
+ * `closeout` instead, and the difference is the point. A repaint is one escape sequence
+ * and belongs here. Hiding the cursor is a global side effect on someone else's terminal,
+ * and the obligation it creates — put it back however the process dies — is not a repaint.
+ * This file used to own `HIDE_CURSOR`/`SHOW_CURSOR`, the family's third copy, and restore
+ * on one path only: the keypress loop, which sees Ctrl-C because raw mode delivers it as a
+ * byte. A `SIGINT` from a parent, a `SIGTERM`, a crash or a `process.exit()` elsewhere
+ * never reached it, and left the cursor invisible until the user typed `reset` (measured
+ * against `dist/raw.js`, 2026-09-15: hide 1, show 0). `hideCursor()` registers the restore
+ * in the call that hides, so the two cannot drift.
  */
+import { hideCursor } from 'closeout/cursor';
+import exitHook from 'closeout/exit-hook';
 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`;
 /**
@@ -94,12 +97,22 @@ function chosen(choices, state, multi) {
         return choices[state.cursor]?.value ?? '';
     return [...state.selected].sort((a, b) => a - b).map((index) => choices[index]?.value ?? '');
 }
+/**
+ * The writer, seen as a terminal, for `hideCursor()` — which refuses a non-TTY. caique's
+ * `Writer` is one method and has no `isTTY`: the terminal test this renderer makes is
+ * `canRender(io.keys)`, on the other half of the same terminal, and it has already been
+ * made. So it is answered here rather than re-asked of a stream that cannot answer.
+ */
+const asTerminal = (writer) => ({ write: (text) => writer.write(text), isTTY: true });
 /**
  * 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.
+ *
+ * The cursor is hidden through `closeout`: the byte path resolves and `restore()` runs in
+ * the `finally`; every path that never reaches the `finally` is the exit hook's.
  */
 export async function askList(spec, io, multi = false) {
     const choices = spec.choices ?? [];
@@ -107,11 +120,14 @@ export async function askList(spec, io, multi = false) {
     let painted = 0;
     const paint = () => {
         const frame = renderList(spec, choices, state, multi);
-        io.writer.write((painted === 0 ? HIDE_CURSOR : erase(painted)) + frame);
+        io.writer.write((painted === 0 ? '' : erase(painted)) + frame);
         painted = frame.split('\n').length;
     };
     io.keys.setRawMode?.(true);
     io.keys.resume?.();
+    // Hide and register the restore together. `restore()` shows the cursor and unregisters,
+    // so a prompt that ends normally leaves nothing behind for exit to do.
+    const restore = hideCursor(asTerminal(io.writer), exitHook);
     paint();
     try {
         return await new Promise((resolve) => {
@@ -130,15 +146,16 @@ export async function askList(spec, io, multi = false) {
             };
             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}`);
+                // Leave the answered question on screen; the `finally` puts the cursor and the
+                // terminal back, because a prompt that exits in raw mode leaves the shell unusable.
+                io.writer.write(`${erase(painted)}${renderList(spec, choices, state, multi)}\n`);
                 resolve(answer);
             };
             io.keys.on('data', onData);
         });
     }
     finally {
+        restore();
         io.keys.setRawMode?.(false);
         io.keys.pause?.();
     }

package/dist/runtime.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The slice of the world caique needs, and the one file here that names `process` (Y9) —
+ * the same seam `paratext/src/runtime.ts` declares. `decide()` already took the fields it
+ * reads and `createIo()` already took its streams; this is the other half, so a program can
+ * get a real one without writing `process.stdin` itself.
+ *
+ * A **function**, for paratext's reason: 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.
+ * `runtime.test.ts` asks twice across a change, so a captured constant cannot pass.
+ */
+/**
+ * Declared structurally, not imported: burgee's `Runtime` satisfies it, so does a literal in
+ * a test. `decide.ts` names the narrower pair it reads for the same reason; this satisfies it.
+ */
+export interface Runtime {
+    /** `decide()` reads `CI`: set means nobody is there to type (R6). */
+    env: Record<string, string | undefined>;
+    stdin: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    stdout: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+    /** `stdin` decides whether a person can be asked at all; `stdout`, whether anything is drawn. */
+    isTTY: {
+        stdin: boolean;
+        stdout: boolean;
+    };
+}
+/** What a real process looks like. Callers that have not got one pass their own. */
+export declare const processRuntime: () => Runtime;

package/dist/runtime.js

@@ -0,0 +1,18 @@
+/**
+ * The slice of the world caique needs, and the one file here that names `process` (Y9) —
+ * the same seam `paratext/src/runtime.ts` declares. `decide()` already took the fields it
+ * reads and `createIo()` already took its streams; this is the other half, so a program can
+ * get a real one without writing `process.stdin` itself.
+ *
+ * A **function**, for paratext's reason: 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.
+ * `runtime.test.ts` asks twice across a change, so a captured constant cannot pass.
+ */
+/** What a real process looks like. Callers that have not got one pass their own. */
+export const processRuntime = () => ({
+    env: process.env,
+    stdin: process.stdin,
+    stdout: process.stdout,
+    isTTY: { stdin: process.stdin.isTTY === true, stdout: process.stdout.isTTY === true },
+});
+//# sourceMappingURL=runtime.js.map

package/dist/schema.json

@@ -0,0 +1,300 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json",
+  "title": "flagstaff plugin",
+  "description": "A plugin is one plain object. Everything in it is data that can be read without running it; the only functions allowed are a component's `static` (required) and `frame` (optional). A spinner or component without a static projection is refused at register().",
+  "type": "object",
+  "required": [
+    "name"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The plugin's name; also the prefix a host may use when two plugins contribute the same key."
+    },
+    "contract": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The plugin contract this object follows. A host refuses a newer contract than it knows."
+    },
+    "tokens": {
+      "type": "object",
+      "description": "A roundel theme: semantic token name to a hex colour, contrast-checked when flown.",
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^#[0-9a-fA-F]{6}$"
+      },
+      "propertyNames": {
+        "enum": [
+          "error",
+          "warn",
+          "ok",
+          "hint",
+          "muted",
+          "command",
+          "flag",
+          "value",
+          "heading",
+          "ground"
+        ],
+        "description": "roundel's ten semantic tokens, and nothing else — `roundel`'s own validate() refuses any other name."
+      }
+    },
+    "glyphs": {
+      "type": "object",
+      "description": "Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one.",
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "spinners": {
+      "type": "object",
+      "description": "Spinner styles by name, in cli-spinners' shape plus the static projection.",
+      "additionalProperties": {
+        "$ref": "#/$defs/spinner"
+      }
+    },
+    "borders": {
+      "type": "object",
+      "description": "Border styles a box can be drawn with, by name.",
+      "additionalProperties": {
+        "$ref": "#/$defs/border"
+      }
+    },
+    "components": {
+      "type": "object",
+      "description": "Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form.",
+      "additionalProperties": {
+        "$ref": "#/$defs/component"
+      }
+    },
+    "capabilities": {
+      "$ref": "#/$defs/capabilities"
+    }
+  },
+  "$defs": {
+    "spinner": {
+      "type": "object",
+      "required": [
+        "frames",
+        "interval",
+        "static"
+      ],
+      "properties": {
+        "frames": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1
+        },
+        "interval": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Milliseconds between frames on a terminal."
+        },
+        "static": {
+          "type": "string",
+          "description": "What a pipe prints instead of the animation."
+        }
+      }
+    },
+    "component": {
+      "type": "object",
+      "required": [
+        "static"
+      ],
+      "properties": {
+        "static": {
+          "description": "(state) => string. Required: the projection every non-terminal mode prints."
+        },
+        "frame": {
+          "description": "(t, state) => string. Optional: the frame at t milliseconds since hoisting."
+        },
+        "sample": {
+          "type": "object",
+          "required": [
+            "running",
+            "done"
+          ],
+          "description": "Two states to *show* this component with: `flagstaff check` and the docs gallery render `running` then `done`. Omitted, they assume `{ phase: 'running' }` and `{ phase: 'done' }` and say so in the output. The loop never reads it — a running program's state comes from the program.",
+          "properties": {
+            "running": {
+              "description": "The state to open with."
+            },
+            "done": {
+              "description": "The state to close with."
+            }
+          }
+        },
+        "interval": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Milliseconds between repaints when `frame` is given; 80 when omitted."
+        }
+      }
+    },
+    "border": {
+      "type": "object",
+      "required": [
+        "topLeft",
+        "top",
+        "topRight",
+        "left",
+        "right",
+        "bottomLeft",
+        "bottom",
+        "bottomRight"
+      ],
+      "description": "cli-boxes' shape exactly, so that corpus imports unchanged.",
+      "properties": {
+        "topLeft": {
+          "type": "string"
+        },
+        "top": {
+          "type": "string"
+        },
+        "topRight": {
+          "type": "string"
+        },
+        "left": {
+          "type": "string"
+        },
+        "right": {
+          "type": "string"
+        },
+        "bottomLeft": {
+          "type": "string"
+        },
+        "bottom": {
+          "type": "string"
+        },
+        "bottomRight": {
+          "type": "string"
+        }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "required": [
+        "name",
+        "osc",
+        "when",
+        "encode",
+        "fallback"
+      ],
+      "additionalProperties": false,
+      "description": "One paratext capability: what it says to the terminal, when the terminal is believed to understand it, and what prints when it does not. No functions, so it travels through JSON. `encode` and `fallback` are templates: `{field}` is the field's value, `{field|base64}` is it base64-encoded, and `[ … ]` is emitted only when every field inside it has a value.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "How callers name it. Registering an existing name replaces it — how a caller corrects a guess we got wrong."
+        },
+        "osc": {
+          "description": "The OSC code this speaks, or 'BEL' for the bell and for protocols that are not OSC at all, such as Kitty's.",
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "const": "BEL"
+            }
+          ]
+        },
+        "when": {
+          "type": "object",
+          "description": "When the terminal is believed to understand it. Every clause must hold; `termProgram` and `envAny` are ORs within themselves. Guesses — no terminal answers 'do you do OSC 1337' — and therefore data a caller can replace.",
+          "additionalProperties": false,
+          "properties": {
+            "tty": {
+              "type": "boolean",
+              "description": "Refuse a pipe. Almost always true: a file that receives OSC gets control bytes in it."
+            },
+            "termProgram": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Any one of these TERM_PROGRAM values."
+            },
+            "envAny": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Any one of these environment variables merely being set, as VTE announces itself."
+            },
+            "term": {
+              "type": "string",
+              "description": "An exact TERM — Kitty is xterm-kitty."
+            }
+          }
+        },
+        "encode": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The bytes, as a template, for a terminal that does understand."
+        },
+        "fallback": {
+          "type": "string",
+          "description": "What to print when it does not — PRINCIPLES rule 6. '' is a legitimate answer, a window title having nothing to say in a log; absence is not, which is why this is required and may be ''."
+        }
+      },
+      "examples": [
+        {
+          "name": "kitty-image",
+          "osc": "BEL",
+          "when": {
+            "tty": true,
+            "term": "xterm-kitty"
+          },
+          "encode": "\u001b_Ga=T,f=100;{base64}\u001b\\",
+          "fallback": "{caption}"
+        }
+      ]
+    },
+    "capabilities": {
+      "type": "object",
+      "description": "paratext capabilities by name — the OSC section of a plugin, read the way flagstaff reads `spinners`.",
+      "additionalProperties": {
+        "$ref": "#/$defs/capability"
+      }
+    },
+    "capabilityDocument": {
+      "description": "What paratext's `check()` accepts. Two shapes, and only one of them survives 1.0.",
+      "oneOf": [
+        {
+          "description": "The family shape: a plugin carrying its capabilities under `capabilities`.",
+          "type": "object",
+          "required": [
+            "name",
+            "capabilities"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "minLength": 1
+            },
+            "contract": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "capabilities": {
+              "$ref": "#/$defs/capabilities"
+            }
+          }
+        },
+        {
+          "deprecated": true,
+          "description": "Deprecated: one capability as the whole document, the shape paratext's schema had before this one absorbed it. Accepted for one minor release, removed at 1.0 — `check()` validates it and says so.",
+          "$ref": "#/$defs/capability"
+        }
+      ]
+    }
+  }
+}

package/dist/spec.d.ts

@@ -9,8 +9,29 @@
  *
  * 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';
+/**
+ * The six kinds a prompt can be — plus whatever a plugin adds.
+ *
+ * **Why `(string & {})` rather than a closed union** (`plugin-contract` R5, D5). A closed
+ * union makes a plugin's seventh kind a type error, so hosting `widgets` at all would be a
+ * breaking change written as an additive one: every caller of `caique/plugin` would need
+ * this file edited before it could name its own kind. The intersection keeps all six
+ * literals in an editor's completion list — which a bare `string` would throw away — while
+ * admitting the kinds `caique/plugin` renders.
+ *
+ * Anything more than a *kind* is still a wizard, which is out of scope. Widening the type
+ * does not widen the model: a prompt is one question with one answer, whoever draws it.
+ */
+export type PromptKind = 'text' | 'confirm' | 'select' | 'multiselect' | 'password' | 'path' | (string & {});
+/**
+ * The six caique draws itself, as data rather than as a `switch` nobody can read back.
+ *
+ * `caique/plugin` needs this set to answer two questions a plugin makes askable for the
+ * first time: whether a kind is already spoken for, and which kinds a refusal should name.
+ * Deriving it from the widget dispatch in `ask.ts` would mean two lists that agree only by
+ * inspection, which is the drift the family's locks exist to prevent.
+ */
+export declare const BUILT_IN_KINDS: ReadonlySet<string>;
 /** One choice in a `select` or `multiselect`. `value` is what the option receives. */
 export interface Choice {
     value: string;

package/dist/spec.js

@@ -9,6 +9,15 @@
  *
  * Nothing here imports a runtime, a stream or a terminal. This file is data.
  */
+/**
+ * The six caique draws itself, as data rather than as a `switch` nobody can read back.
+ *
+ * `caique/plugin` needs this set to answer two questions a plugin makes askable for the
+ * first time: whether a kind is already spoken for, and which kinds a refusal should name.
+ * Deriving it from the widget dispatch in `ask.ts` would mean two lists that agree only by
+ * inspection, which is the drift the family's locks exist to prevent.
+ */
+export const BUILT_IN_KINDS = new Set(['text', 'confirm', 'select', 'multiselect', 'password', 'path']);
 /** `--output-dir`, which is what a refusal has to say to be actionable. */
 export function flagOf(option) {
     return `--${option}`;

package/dist/terminal.d.ts

@@ -1,5 +1,6 @@
 import { type Io } from './ask.js';
-/** The stream pair a terminal Io is built over: `process.stdin` and `process.stdout`. */
+import { type Runtime } from './runtime.js';
+/** The stream pair a terminal Io is built over: a `Runtime`'s `stdin` and its `stdout`. */
 export interface Streams {
     input: NodeJS.ReadableStream & {
         isTTY?: boolean;
@@ -8,13 +9,18 @@ export interface Streams {
         isTTY?: boolean;
     };
 }
+/** A runtime's two streams as the pair `createIo` takes — the mapping, written down once. */
+export declare const streamsOf: (runtime: Runtime) => Streams;
 /**
  * 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.
+ *
+ * With no argument it builds over the real process, read when it is called and not at
+ * import: a program that wants the terminal it was started in writes `createIo()`.
  */
-export declare function createIo(streams: Streams): Io & {
+export declare function createIo(streams?: Streams): Io & {
     close: () => void;
 };

package/dist/terminal.js

@@ -13,6 +13,9 @@
  */
 import { createInterface } from 'node:readline';
 import {} from './ask.js';
+import { processRuntime } from './runtime.js';
+/** A runtime's two streams as the pair `createIo` takes — the mapping, written down once. */
+export const streamsOf = (runtime) => ({ input: runtime.stdin, output: runtime.stdout });
 /** Accepts a chunk and writes nothing: what a muted stream's `write` does. */
 const swallow = () => true;
 /**
@@ -36,8 +39,11 @@ function mute(rl, streams) {
  * 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.
+ *
+ * With no argument it builds over the real process, read when it is called and not at
+ * import: a program that wants the terminal it was started in writes `createIo()`.
  */
-export function createIo(streams) {
+export function createIo(streams = streamsOf(processRuntime())) {
     const rl = createInterface({ input: streams.input, output: streams.output, terminal: streams.output.isTTY === true });
     let ended = false;
     rl.once('close', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caique",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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",
@@ -28,11 +28,17 @@
       "import": "./dist/decide.js",
       "default": "./dist/decide.js"
     },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    },
     "./raw": {
       "types": "./dist/raw.d.ts",
       "import": "./dist/raw.js",
       "default": "./dist/raw.js"
     },
+    "./schema.json": "./dist/schema.json",
     "./spec": {
       "types": "./dist/spec.d.ts",
       "import": "./dist/spec.js",
@@ -50,9 +56,10 @@
     "!dist/**/*.test.*"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/schema-to-dist.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run --passWithNoTests",
+    "coverage": "vitest run --coverage.enabled",
     "lint": "eslint src"
   },
   "repository": {
@@ -75,6 +82,9 @@
     "agent",
     "non-tty"
   ],
+  "dependencies": {
+    "closeout": "^0.2.0"
+  },
   "devDependencies": {
     "vitest": "^5.0.0"
   }