@orkestrel/terminal 0.0.14 → 0.0.16

package/dist/src/server/index.js

@@ -1,14 +1,15 @@
 import { CSI, createStyler } from "@orkestrel/console";
 import { NEWLINE, RETURN, TerminalError, createCheckboxState, createConfirmState, createEditorState, createInputState, createPasswordState, createPromptTheme, createSelectState, parseKey, reduceCheckbox, reduceConfirm, reduceEditor, reduceInput, reducePassword, reduceSelect, renderErrorLine, renderHintedHeader, renderPromptHeader, sanitizeDisplayText } from "../core/index.js";
+import { isBoolean, isFunction, isNumber, isObject, isString } from "@orkestrel/contract";
 import { matchesAnswer, parseValue } from "@orkestrel/form";
 import { isStreamTarget } from "@orkestrel/console/server";
 import { createInterface } from "node:readline";
 import { stdin, stdout } from "node:process";
 //#region src/server/constants.ts
 /**
-* Holds the cursor-UP sequence TEMPLATE (`ESC[{count}A`) — {@link import('./helpers.js').renderCursorUp}
-* interpolates the `{count}` placeholder with the number of lines to climb. Kept as a template so
-* the count stays out of the constant.
+* Holds the cursor-up sequence template (`ESC[{count}A`) —
+* {@link import('./helpers.js').renderCursorUp} interpolates the `{count}` placeholder with the
+* number of lines to climb. Kept as a template so the count stays out of the constant.
 */
 var CSI_UP = `${CSI}{count}A`;
 /**
@@ -19,9 +20,9 @@ var CURSOR_HIDE = `${CSI}?25l`;
 /** Shows the cursor (`ESC[?25h`) — restores the cursor after a prompt resolves / cancels (the {@link CURSOR_HIDE} pair). */
 var CURSOR_SHOW = `${CSI}?25h`;
 /**
-* Erases from the cursor down to the end of the screen (`ESC[J`) — wipes the WHOLE previous (possibly
-* multi-line `select` / `checkbox`) view in one write before the new view is rendered, so a redraw
-* never leaves orphaned rows below.
+* Erases from the cursor down to the end of the screen (`ESC[J`) — wipes the whole previous view,
+* which a `select` or `checkbox` can spread over several lines, in one write before the new view is
+* rendered, so a redraw never leaves orphaned rows behind.
 */
 var CLEAR_DOWN = `${CSI}J`;
 /**
@@ -53,9 +54,15 @@ var CONTROL_HINTS = Object.freeze({
 });
 /** Holds the instruction a `file` field with `multiple` shows before its entries — one path per line, and a blank line ends the list. */
 var FILE_HINT = "One path per line, blank to finish";
-/** Holds the lead on the line listing an open `select`'s offered values, which a typed answer may ignore. */
+/**
+* Holds the lead on the line listing an open `select`'s offered values, which a typed answer can
+* ignore.
+*/
 var SUGGESTION_LEAD = "Suggestions";
-/** Holds the lead on the line listing the choices a `select` or `checkbox` shows but refuses, so a reader sees why one is missing from the list below. */
+/**
+* Holds the lead on the line listing the choices a `select` or `checkbox` shows but refuses, so a
+* reader sees why one is missing from the list it heads.
+*/
 var UNAVAILABLE_LEAD = "Unavailable";
 /** Holds the mark on a locked field's line — the walk renders its value and moves on, because the form refuses an edit there. */
 var LOCKED_MARK = "(locked)";
@@ -69,55 +76,55 @@ var REFUSAL_MESSAGE = "Enter a value this field accepts";
 //#endregion
 //#region src/server/helpers.ts
 /**
-* Checks whether `value` is a usable {@link InputStreamInterface} — a record with callable `on` / `off`
-* `'data'` subscription methods. A total type guard: it NEVER throws and returns `false`
-* for anything off-shape, so it narrows the one unavoidable input boundary (the real `process.stdin`,
-* or a fake TTY a test injects) to the exact slice the driver reads — no `as`.
+* Checks whether `value` is a usable {@link InputStreamInterface} — a record with callable `on` /
+* `off` `'data'` subscription methods. A total type guard: it never throws and returns `false` for
+* anything off-shape, so it narrows the one unavoidable input boundary (the real `process.stdin`,
+* or a fake TTY a test injects) to the exact slice the driver reads, never an assertion.
 *
 * @remarks
 * Only `on` / `off` are required (the irreducible event seam); `setRawMode` / `resume` / `pause` /
 * `isTTY` are optional on {@link InputStreamInterface}, so their absence does not disqualify a stream
-* — a piped, non-TTY stream is still a valid input, just one the driver reads through the readline
+* — a piped, non-TTY stream is still a valid input, one the driver reads through the readline
 * fallback rather than raw mode.
 *
 * @param value - Any value crossing the boundary (a process stream, an injected fake, `unknown`)
 * @returns True if `value` has callable `on` and `off`; false otherwise
 */
 function isInputStream(value) {
-	return typeof value === "object" && value !== null && "on" in value && typeof value.on === "function" && "off" in value && typeof value.off === "function";
+	return isObject(value) && "on" in value && isFunction(value.on) && "off" in value && isFunction(value.off);
 }
 /**
 * Checks whether `value` is a Node {@link NodeJS.ReadableStream} — a total structural guard
-* checking for the callable `read` / `pipe` / `on` that `node:readline`'s `createInterface` requires
-* as its `input`. The non-TTY fallback narrows the resolved input stream through this before handing
-* it to readline (never an `as`), so a real piped `process.stdin` (or a `PassThrough` a test injects)
-* crosses into the readline boundary honestly. Never throws; returns `false` for a minimal fake that
-* isn't a full readable.
+* checking for the callable `read` / `pipe` / `on` that `node:readline`'s `createInterface`
+* requires as its `input`. The non-TTY fallback narrows the resolved input stream through this
+* before handing it to readline, never through an assertion, so a real piped `process.stdin` (or a
+* `PassThrough` a test injects) crosses into the readline boundary honestly. Never throws; returns
+* `false` for a minimal fake that isn't a full readable.
 *
 * @param value - The resolved input stream (or any value crossing the boundary)
 * @returns True if `value` has the readable methods readline needs; false otherwise
 */
 function isReadable(value) {
-	return typeof value === "object" && value !== null && "read" in value && typeof value.read === "function" && "pipe" in value && typeof value.pipe === "function";
+	return isObject(value) && "read" in value && isFunction(value.read) && "pipe" in value && isFunction(value.pipe);
 }
 /**
-* Checks whether an input stream can be driven in RAW mode — it both reports `isTTY === true` AND
-* exposes a callable `setRawMode`. The {@link import('./Terminal.js').Terminal} probes this to choose its path:
-* `true` ⇒ the interactive raw-mode prompts (arrow-key navigation, live re-render); `false` ⇒ the
-* `node:readline` line-input fallback (a piped / non-terminal stream cannot enter raw mode). Total —
-* never throws.
+* Checks whether an input stream can be driven in raw mode — it reports `isTTY === true` and
+* exposes a callable `setRawMode`. The {@link import('./Terminal.js').Terminal} probes this to
+* choose its path: true selects the interactive raw-mode fields, with arrow-key navigation and a
+* live re-render; false selects the `node:readline` line-input fallback, because a piped or
+* non-terminal stream cannot enter raw mode. Total — never throws.
 *
 * @param input - The resolved {@link InputStreamInterface}
 * @returns True if the stream is a TTY with `setRawMode`; false otherwise
 */
 function supportsRawMode(input) {
-	return input.isTTY === true && typeof input.setRawMode === "function";
+	return input.isTTY === true && isFunction(input.setRawMode);
 }
 /**
-* Counts the terminal LINES a rendered prompt `view` occupies — one more than its newline count
-* (a view with no newline is a single line; N newlines span N+1 lines). The basis of the in-place
-* re-render: the driver records the line count of the view it just wrote so the next redraw knows how
-* far up to move the cursor before overwriting. Total; an empty string is one (empty) line.
+* Counts the terminal lines a rendered prompt `view` occupies — one more than its newline count, so
+* a view with no newline is a single line and a view with N newlines spans N+1 lines. The basis of
+* the in-place re-render: the driver records the line count of the view it wrote so the next redraw
+* knows how far up to move the cursor before overwriting. Total; an empty string is one empty line.
 *
 * @param view - The rendered (possibly multi-line, possibly ANSI-styled) view string
 * @returns The number of lines the view spans (always at least 1)
@@ -128,10 +135,10 @@ function lineCount(view) {
 	return lines;
 }
 /**
-* Returns the cursor-UP control sequence that moves the cursor up `count` lines (`ESC[{count}A`) — or the
-* empty string when `count` is zero or negative (no movement needed, and `ESC[0A` is a wasted write).
-* The pure step the in-place re-render uses to climb back over the previous view before clearing it.
-* Total.
+* Returns the cursor-up control sequence that moves the cursor up `count` lines (`ESC[{count}A`),
+* or the empty string when `count` is zero or negative, because no movement is needed and `ESC[0A`
+* is a wasted write. The pure step the in-place re-render uses to climb back over the previous view
+* before clearing it. Total.
 *
 * @param count - How many lines to move the cursor up
 * @returns The `ESC[{count}A` sequence, or `''` when `count <= 0`
@@ -141,31 +148,31 @@ function renderCursorUp(count) {
 	return `${CSI_UP.replace("{count}", String(count))}`;
 }
 /**
-* Returns the full reposition-and-clear prefix to write BEFORE re-rendering a prompt view in place — given
-* the line count of the PREVIOUS view, it moves the cursor up over those lines, returns it to column
-* 0, and erases everything from there to the end of the screen, so the next view is drawn on a clean
-* region (no orphaned rows from a taller previous view). Pure; the driver writes this immediately
-* followed by the new view.
+* Returns the full reposition-and-clear prefix to write before re-rendering a prompt view in place
+* — given the line count of the previous view, it moves the cursor up over those lines, returns it
+* to column 0, and erases everything from there to the end of the screen, so the next view is drawn
+* on a clean region and a taller previous view leaves no orphaned rows. Pure; the driver writes
+* this immediately followed by the new view.
 *
 * @remarks
-* For the FIRST render `previousLines` is `1` (the cursor sits on the line the prompt opened on) so
-* the prefix is just a carriage return + clear-down — the prompt draws from the current line. For a
-* subsequent render it climbs `previousLines - 1` lines (the cursor is on the LAST line of the prior
+* For the first render `previousLines` is `1` (the cursor sits on the line the prompt opened on) so
+* the prefix is a carriage return + clear-down — the prompt draws from the current line. For a
+* subsequent render it climbs `previousLines - 1` lines (the cursor is on the last line of the prior
 * view) before clearing. Keeping the math here (not in the driver) makes the re-render unit-testable
 * without a real terminal.
 *
-* @param previousLines - The line count of the view currently on screen (from {@link lineCount})
+* @param previousLines - The line count of the view on screen (from {@link lineCount})
 * @returns The control-sequence prefix to write before the new view
 */
 function redrawPrefix(previousLines) {
 	return `${renderCursorUp(previousLines - 1)}${RETURN}${CLEAR_DOWN}`;
 }
 /**
-* Projects any field the walk reads as a LINE OF TEXT into the {@link TextField} the text reducer
-* takes — `text` itself, and the controls a terminal has no widget for: `number`, `date`,
-* `time`, `datetime`, `color`, and one `file` entry. The label carries that control's format cue
-* from {@link CONTROL_HINTS}, and a declared `default` becomes the line a bare return submits. The
-* projection carries no rule, because the AUTHORITATIVE form still evaluates the answer this line
+* Projects any field the walk reads as a line of text into the {@link TextField} the text reducer
+* takes — `text` itself, and the controls a terminal has no widget for: `number`, `date`, `time`,
+* `datetime`, `color`, and one `file` entry. The label carries that control's format cue from
+* {@link CONTROL_HINTS}, and a declared `default` becomes the line a bare return submits. The
+* projection carries no rule, because the authoritative form still evaluates the answer this line
 * binds; it exists only so one reducer covers every one of them.
 *
 * @param field - The field being read
@@ -181,12 +188,12 @@ function fieldToText(field) {
 	const label = field.label ?? field.name;
 	const hint = CONTROL_HINTS[field.control];
 	const seed = "default" in field ? field.default : void 0;
-	const text = typeof seed === "number" ? String(seed) : seed;
+	const text = isNumber(seed) ? String(seed) : seed;
 	return {
 		control: "text",
 		name: field.name,
 		label: hint === void 0 ? label : `${label} ${hint}`,
-		...typeof text === "string" ? { default: text } : {}
+		...isString(text) ? { default: text } : {}
 	};
 }
 /**
@@ -199,13 +206,13 @@ function fieldToText(field) {
 */
 function valueToText(value) {
 	if (value === void 0) return "";
-	if (typeof value === "string") return value;
-	if (typeof value === "number") return String(value);
-	if (typeof value === "boolean") return value ? "yes" : "no";
+	if (isString(value)) return value;
+	if (isNumber(value)) return String(value);
+	if (isBoolean(value)) return value ? "yes" : "no";
 	return value.join(", ");
 }
 /**
-* Returns the choices a `select` or `checkbox` field actually OFFERS — the form refuses a disabled
+* Returns the choices a `select` or `checkbox` field actually offers — the form refuses a disabled
 * choice's value at every door, including a fill, so the walk never puts one in front of the
 * cursor. Pair with {@link filterDisabled} to tell the reader what was withheld.
 *
@@ -216,7 +223,7 @@ function filterEnabled(choices) {
 	return choices.filter((choice) => choice.disabled !== true);
 }
 /**
-* Returns the choices a `select` or `checkbox` field SHOWS but refuses — the complement of
+* Returns the choices a `select` or `checkbox` field shows but refuses — the complement of
 * {@link filterEnabled}, rendered by {@link renderUnavailableLine} above the list so a reader sees
 * why a declared choice is missing from it.
 *
@@ -239,9 +246,9 @@ function renderGroupHeader(styler, theme, label) {
 	return styler.render(theme.roles.message, label);
 }
 /**
-* Renders the read-only line a LOCKED field shows — its label, the {@link LOCKED_MARK}, and the
-* answer the form already holds. The walk writes this instead of a prompt, because the field is still
-* validated and still submitted but must not be edited here.
+* Renders the read-only line a locked field shows — its label, the {@link LOCKED_MARK}, and the
+* answer the form already holds. The walk writes this instead of a prompt, because the field is
+* still validated and still submitted but must not be edited here.
 *
 * @param styler - The console styler that renders each role
 * @param theme - The resolved prompt theme
@@ -254,7 +261,7 @@ function renderLockedLine(styler, theme, label, value) {
 	return value.length === 0 ? head : `${head} ${styler.render(theme.roles.content, value)}`;
 }
 /**
-* Renders the line listing an OPEN select's offered values above its text prompt — a suggestion
+* Renders the line listing an open select's offered values above its text prompt — a suggestion
 * list, because an open select admits an answer the list does not offer.
 *
 * @param styler - The console styler that renders each role
@@ -295,12 +302,13 @@ function renderNumberedList(styler, theme, choices) {
 //#endregion
 //#region src/server/Terminal.ts
 /**
-* Implements {@link TerminalInterface} for a human at this machine's keyboard — the interactive form
-* DRIVER, and the only impure part of the terminal stack. {@link ask} walks one
-* form's fields in schema order, feeds raw-mode stdin bytes through `parseKey` into the matching
-* pure reducer, renders each returned view in place, and binds every answer through the form's own
-* `fill`. It owns no form logic: the schema, the rules, the values, and the settlement all belong to
-* the form it is given, and this class owns only raw mode, the cursor, and the re-render.
+* Implements {@link TerminalInterface} for a human at this machine's keyboard — the interactive
+* form driver, and the only impure part of the terminal stack. {@link ask} walks one form's fields
+* in schema order, feeds raw-mode stdin bytes through `parseKey` into the matching pure reducer,
+* renders each returned view in place, binds every answer through the form's own `fill`, and
+* re-asks what the form refused. It owns no form logic: the schema, the rules, the values, and the
+* settlement all belong to the form it is given, and this class owns only raw mode, the cursor, and
+* the re-render.
 *
 * @remarks
 * See {@link TerminalInterface} for the driving contract. The walk itself:
@@ -312,12 +320,11 @@ function renderNumberedList(styler, theme, choices) {
 *   `open` means the answer need not come from the list.
 * - **The binding projects through `matchesAnswer`.** Every answer is filled as
 *   `fill(name, matchesAnswer(value) ? value : undefined)` after `parseValue` has coerced it to the
-*   control's own shape, so a bare return on a field with no default binds as ABSENCE and the
+*   control's own shape, so a bare return on a field with no default binds as absence and the
 *   form's `required` rule refuses it. A typed answer the control cannot hold binds as absence and
 *   invalidates the field, so the walk asks again with the reason on screen.
-* - **Visibility is honored.** A `hidden` field and a field currently in `form.disabled` are
-*   skipped; a `locked` field renders read-only; entering a new group writes its label as a section
-*   header.
+* - **Visibility is honored.** A `hidden` field and a field in `form.disabled` are skipped; a
+*   `locked` field renders read-only; entering a new group writes its label as a section header.
 * - **Refusal re-asks.** After the walk the form is submitted. A refusal re-walks only the erroring
 *   fields the walk can edit and submits again. When every erroring field is one the walk cannot
 *   edit — hidden, locked, or disabled — the form is abandoned instead, because asking again could
@@ -745,12 +752,12 @@ var Terminal = class {
 //#endregion
 //#region src/server/factories.ts
 /**
-* Creates the interactive terminal form driver — the local-keyboard arm of the terminal trio, beside
-* the core headless `createPrompt` broker and the SSE `createPromptClient` bridge. Where the broker
-* PARKS a live form until somebody elsewhere answers it, a `Terminal` answers one HERE: it walks the
-* form's fields in schema order, drives each control's pure reducer over raw-mode stdin, binds every
-* answer through the form's own `fill`, and submits. It is the only impure part of the terminal
-* stack.
+* Creates the interactive terminal form driver — the local-keyboard arm of the terminal trio,
+* beside the core headless `createPrompt` broker and the SSE `createPromptClient` bridge. Where the
+* broker parks a live form until somebody elsewhere answers it, a `Terminal` answers one here: it
+* walks the form's fields in schema order, drives each control's pure reducer over raw-mode stdin,
+* binds every answer through the form's own `fill`, and submits. It is the only impure part of the
+* terminal stack.
 *
 * @param options - See {@link TerminalOptions}
 * @returns A {@link TerminalInterface} whose `ask` drives one whole form over the resolved streams
@@ -770,21 +777,39 @@ var Terminal = class {
 * - **Non-TTY fallback.** A piped stream cannot enter raw mode, so the same walk runs over
 *   `node:readline` line input.
 *
-* @example
+* @example Ask one form at this keyboard
 * ```ts
 * import { createForm } from '@orkestrel/form'
+* import { isTerminalError } from '@orkestrel/terminal'
 * import { createTerminal } from '@orkestrel/terminal/server'
 *
-* const terminal = createTerminal()
-* const values = await terminal.ask(
-* 	createForm({
-* 		label: 'Sign up',
-* 		fields: [
-* 			{ control: 'text', name: 'email', label: 'Email', rule: { required: true, email: true } },
-* 			{ control: 'confirm', name: 'terms', label: 'I accept the terms' },
-* 		],
-* 	}),
-* )
+* const terminal = createTerminal() // process.stdin / process.stdout by default
+* const form = createForm({
+* 	label: 'Sign up',
+* 	fields: [
+* 		{ control: 'text', name: 'name', label: 'Your name', rule: { required: true, minimum: 2 } },
+* 		{ control: 'text', name: 'email', label: 'Email', rule: { required: true, email: true } },
+* 		{ control: 'password', name: 'token', label: 'Token' },
+* 		{ control: 'confirm', name: 'terms', label: 'Accept the terms', rule: { required: true } },
+* 		{
+* 			control: 'select',
+* 			name: 'role',
+* 			label: 'Role',
+* 			choices: [
+* 				{ value: 'admin', label: 'Admin' },
+* 				{ value: 'viewer', label: 'Viewer', help: 'read-only' },
+* 			],
+* 		},
+* 	],
+* })
+*
+* try {
+* 	const values = await terminal.ask(form)
+* 	deploy(values)
+* } catch (error) {
+* 	// Ctrl-c: the walk ended, and the form is still `editing` for whoever owns it.
+* 	if (isTerminalError(error) && error.code === 'CANCEL') form.destroy()
+* }
 * ```
 */
 function createTerminal(options) {