caique 0.1.1 → 0.3.0

package/dist/inquirer.js

@@ -0,0 +1,207 @@
+import { AsyncResource } from 'node:async_hooks';
+import { resolve as resolvePath } from 'node:path';
+import { createInterface } from 'node:readline';
+import exitHook from 'closeout/exit-hook';
+import { AbortPromptError, CancelPromptError, ExitPromptError } from './inquirer-errors.js';
+import { effectScheduler, useEffect, useRef, useState, withHooks, withUpdates } from './inquirer-hooks.js';
+import { MuteStream, ScreenManager } from './inquirer-screen.js';
+import { LINE, makeTheme } from './inquirer-theme.js';
+import { processRuntime } from './runtime.js';
+const SEPARATOR_WIDTH = 15;
+const SPINNER_DELAY_MS = 300;
+export class Separator {
+    separator = Array.from({ length: SEPARATOR_WIDTH }).join(LINE);
+    type = 'separator';
+    constructor(separator) {
+        if (separator !== undefined && separator !== '')
+            this.separator = separator;
+    }
+    static isSeparator(choice) {
+        return Boolean(choice) && typeof choice === 'object' && choice !== null && 'type' in choice && choice.type === 'separator';
+    }
+}
+export function usePrefix({ status = 'idle', theme }) {
+    const [showLoader, setShowLoader] = useState(false);
+    const [tick, setTick] = useState(0);
+    const { prefix, spinner } = makeTheme(theme);
+    useEffect(() => {
+        if (status !== 'loading') {
+            setShowLoader(false);
+            return undefined;
+        }
+        let tickInterval;
+        let inc = -1;
+        const delayTimeout = setTimeout(() => {
+            setShowLoader(true);
+            tickInterval = setInterval(() => {
+                inc = inc + 1;
+                setTick(inc % spinner.frames.length);
+            }, spinner.interval);
+        }, SPINNER_DELAY_MS);
+        return () => {
+            clearTimeout(delayTimeout);
+            clearInterval(tickInterval);
+        };
+    }, [status]);
+    if (showLoader === true)
+        return spinner.frames[tick ?? 0] ?? '';
+    const iconName = status === 'loading' ? 'idle' : status;
+    if (typeof prefix === 'string')
+        return prefix;
+    return prefix[iconName] ?? prefix['idle'] ?? '';
+}
+export function useKeypress(userHandler) {
+    const signal = useRef(userHandler);
+    signal.current = userHandler;
+    useEffect((rl) => {
+        let ignore = false;
+        const handler = withUpdates((_input, event) => {
+            if (ignore)
+                return;
+            void signal.current(event, rl);
+        });
+        rl.input.on('keypress', handler);
+        return () => {
+            ignore = true;
+            rl.input.removeListener('keypress', handler);
+        };
+    }, []);
+}
+function callerFile() {
+    const saved = Error.prepareStackTrace;
+    let frames = [];
+    try {
+        Error.prepareStackTrace = (_error, callSites) => {
+            frames = [...callSites];
+            return frames;
+        };
+        void new Error('trace').stack;
+    }
+    catch {
+        return undefined;
+    }
+    Error.prepareStackTrace = saved;
+    const fileName = frames[2]?.getFileName() ?? undefined;
+    if (fileName === undefined || fileName.startsWith('file://'))
+        return fileName;
+    return resolvePath(fileName);
+}
+function listenTo(target, event, listener) {
+    const [add, remove] = 'on' in target
+        ? [target.on.bind(target), target.removeListener.bind(target)]
+        : [target.addEventListener.bind(target), target.removeEventListener.bind(target)];
+    add(event, listener);
+    return () => {
+        remove(event, listener);
+    };
+}
+const nativeSetImmediate = globalThis.setImmediate;
+function readlineOver(input, output) {
+    const stream = output;
+    return createInterface({ terminal: true, input, output: stream });
+}
+function runPrompt(view, origin, config, context) {
+    const runtime = processRuntime();
+    const { input = runtime.stdin, signal } = context;
+    const cleanups = new Set();
+    const output = new MuteStream();
+    output.pipe((context.output ?? runtime.stdout));
+    const rl = readlineOver(input, output);
+    output.mute();
+    const screen = new ScreenManager(rl);
+    const { promise, resolve, reject } = Promise.withResolvers();
+    return withHooks(rl, (cycle) => {
+        const clearEffects = AsyncResource.bind(() => {
+            effectScheduler.clearAll();
+        });
+        const settlePrompt = (settle) => {
+            try {
+                clearEffects();
+                settle();
+            }
+            catch (error) {
+                reject(error);
+            }
+        };
+        const settler = (finish) => (settled) => {
+            settlePrompt(() => {
+                finish(settled);
+            });
+        };
+        const resolvePrompt = settler(resolve);
+        const rejectPrompt = settler(reject);
+        const endsWith = (make) => () => {
+            rejectPrompt(make());
+        };
+        const promptPromise = Object.assign(promise
+            .finally(() => {
+            for (const cleanup of cleanups)
+                cleanup();
+            screen.done({ clearContent: Boolean(context.clearPromptOnDone) });
+            output.end();
+        })
+            .then(() => promise), { cancel: endsWith(() => new CancelPromptError()) });
+        if (signal) {
+            const abort = endsWith(() => new AbortPromptError({ cause: signal.reason }));
+            if (signal.aborted) {
+                abort();
+                return promptPromise;
+            }
+            cleanups.add(listenTo(signal, 'abort', abort));
+        }
+        const forceClosed = (how) => {
+            rejectPrompt(new ExitPromptError(`User force closed the prompt with ${how}`));
+        };
+        cleanups.add(exitHook((code) => {
+            forceClosed(String(code));
+        }));
+        cleanups.add(listenTo(rl, 'SIGINT', () => {
+            forceClosed('SIGINT');
+        }));
+        cleanups.add(listenTo(rl, 'close', clearEffects));
+        const startCycle = () => {
+            cleanups.add(listenTo(rl.input, 'keypress', () => {
+                screen.checkCursorPos();
+            }));
+            let pendingDone = null;
+            cycle(() => {
+                let effectsSettled = false;
+                try {
+                    const nextView = view(config, (value) => {
+                        if (effectsSettled)
+                            resolvePrompt(value);
+                        else
+                            pendingDone = { value };
+                    });
+                    if (nextView === undefined)
+                        throw new Error(`Prompt functions must return a string.\n    at ${origin ?? '<unknown>'}`);
+                    const [content, bottomContent] = typeof nextView === 'string' ? [nextView, undefined] : nextView;
+                    screen.render(content, bottomContent);
+                    effectScheduler.run();
+                }
+                catch (error) {
+                    rejectPrompt(error);
+                }
+                effectsSettled = true;
+                if (pendingDone !== null) {
+                    const { value } = pendingDone;
+                    pendingDone = null;
+                    resolvePrompt(value);
+                }
+            });
+        };
+        if ('readableFlowing' in input)
+            nativeSetImmediate(startCycle);
+        else
+            startCycle();
+        return promptPromise;
+    });
+}
+export function createPrompt(view) {
+    const origin = callerFile();
+    return (config, context = {}) => runPrompt(view, origin, config, context);
+}
+export { AbortPromptError, CancelPromptError, ExitPromptError, HookError, ValidationError } from './inquirer-errors.js';
+export { useEffect, useMemo, useRef, useState } from './inquirer-hooks.js';
+export { getDefaultKeybindings, isBackspaceKey, isDownKey, isEnterKey, isNumberKey, isShiftKey, isSpaceKey, isTabKey, isUpKey, } from './inquirer-keys.js';
+export { defaultTheme, getDefaultTheme, makeTheme } from './inquirer-theme.js';

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,99 @@
+import { projection } from './ask.js';
+import { BUILT_IN_KINDS } from './spec.js';
+export const CONTRACT = 1;
+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);
+const builtIns = () => [...BUILT_IN_KINDS].join(', ');
+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`');
+        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? }`');
+        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 = [];
+export function register(plugin) {
+    validate(plugin);
+    order.push(plugin);
+}
+export function reset() {
+    order.length = 0;
+}
+export function registered() {
+    return order;
+}
+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()];
+}
+export function widgetFor(kind) {
+    for (let i = order.length - 1; i >= 0; i -= 1) {
+        const widget = order[i].widgets?.[kind];
+        if (widget !== undefined)
+            return widget;
+    }
+    return undefined;
+}
+export function kinds() {
+    return [...BUILT_IN_KINDS, ...widgets().map((c) => c.kind)];
+}
+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();
+}

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

@@ -1,33 +1,8 @@
-/**
- * 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';
+import { hideCursor } from 'closeout/cursor';
+import exitHook from 'closeout/exit-hook';
 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';
@@ -37,26 +12,21 @@ export function keyOf(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 : ' ';
@@ -66,11 +36,6 @@ export function renderList(spec, choices, state, multi) {
     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);
@@ -88,30 +53,24 @@ function moved(key, state, length, multi) {
         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.
- */
+const asTerminal = (writer) => ({ write: (text) => writer.write(text), isTTY: true });
 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);
+        io.writer.write((painted === 0 ? '' : erase(painted)) + frame);
         painted = frame.split('\n').length;
     };
     io.keys.setRawMode?.(true);
     io.keys.resume?.();
+    const restore = hideCursor(asTerminal(io.writer), exitHook);
     paint();
     try {
         return await new Promise((resolve) => {
@@ -130,17 +89,15 @@ 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}`);
+                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?.();
     }
 }
-//# sourceMappingURL=raw.js.map

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,6 @@
+export const processRuntime = () => ({
+    env: process.env,
+    stdin: process.stdin,
+    stdout: process.stdout,
+    isTTY: { stdin: process.stdin.isTTY === true, stdout: process.stdout.isTTY === true },
+});

package/dist/schema.json

@@ -0,0 +1 @@
+{"$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;