caique 0.2.0 → 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.js

@@ -1,37 +1,6 @@
-/**
- * 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;
@@ -43,14 +12,7 @@ export class PluginError extends Error {
     }
 }
 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');
@@ -71,19 +33,11 @@ function validateWidgets(widgetMap, name) {
     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');
         }
@@ -101,23 +55,16 @@ function validateSample(sample, name, kind) {
     }
 }
 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) {
@@ -128,9 +75,7 @@ export function widgets() {
     }
     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)
@@ -138,17 +83,9 @@ export function widgetFor(kind) {
     }
     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);
@@ -160,4 +97,3 @@ export function projectionOf(spec) {
     }
     return widget.static(spec).trimEnd();
 }
-//# sourceMappingURL=plugin.js.map

package/dist/raw.js

@@ -1,36 +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 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}[`;
-/** 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';
@@ -40,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 : ' ';
@@ -69,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);
@@ -91,29 +53,12 @@ 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 ?? '');
 }
-/**
- * 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 ?? [];
     const state = { cursor: 0, selected: new Set() };
@@ -125,8 +70,6 @@ export async function askList(spec, io, multi = false) {
     };
     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 {
@@ -146,8 +89,6 @@ export async function askList(spec, io, multi = false) {
             };
             const done = (answer) => {
                 io.keys.off('data', onData);
-                // 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);
             };
@@ -160,4 +101,3 @@ export async function askList(spec, io, multi = false) {
         io.keys.pause?.();
     }
 }
-//# sourceMappingURL=raw.js.map

package/dist/runtime.js

@@ -1,18 +1,6 @@
-/**
- * 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