create-pathfinder 1.6.0 → 1.7.0

package/src/prompt.mjs

@@ -10,10 +10,31 @@
  * nothing must also print nothing, and a guard bug that degrades silently would
  * show up as a script that hangs on someone's CI runner months later.
  *
- * The second is the decided interaction model: `node:readline` and printed
- * lines. No setRawMode, no keypress handler, no cursor control, no redraw. That
- * is what makes this work in a dumb terminal, over ssh, and inside an editor's
- * integrated console, and it is a decision rather than a default.
+ * The second is the decided interaction model. ~~`node:readline` and printed
+ * lines. No setRawMode, no keypress handler, no cursor control, no redraw.~~
+ * **Superseded in Feature 23**, in two different ways, and the sentence was
+ * partly wrong when it was written:
+ *
+ * - **"No setRawMode" was never true of the process**, only of this file.
+ *   `node:readline` turns raw mode on itself the moment its input is a TTY, and
+ *   turns it off again on `close()` — verified across five Node majors during
+ *   the spike. What is true, and is now the load-bearing statement, is that
+ *   **readline owns raw mode and Pathfinder never touches it.** The distinction
+ *   matters: the first is a claim about terminal state that a reader could check
+ *   and find false, and the second is the reason no interrupt can leave a
+ *   terminal broken.
+ * - **There is now a keypress handler and a redraw**, in `select.mjs`, borrowed
+ *   from readline and given back. Which is a change of interaction, not of
+ *   ownership.
+ *
+ * What has *not* changed is the reason the original sentence existed. The
+ * line-based path still works in a dumb terminal, over a pipe, and on a CI
+ * runner, and it is still here — every function below keeps its numbered/`y n`
+ * implementation intact and reaches for it whenever `theme.selection` is false.
+ * That is a supported way to use this tool, reachable deliberately with
+ * `PATHFINDER_PROMPT=classic`, and not a fallback anyone should feel they have
+ * been demoted to. `text()` never had anything to gain from a keypress loop and
+ * is untouched.
  *
  * Answers are bounded. Unparseable input is re-prompted a fixed number of times
  * and then gives up, so an input stream that will never produce a `y` cannot
@@ -24,14 +45,25 @@
 
 import { createInterface } from "node:readline";
 
+import { alignmentWidth, optionRow, select } from "./select.mjs";
+import { createTheme } from "./theme.mjs";
+
 const YES = new Set(["y", "yes"]);
 const NO = new Set(["n", "no"]);
 
 /**
  * A question-asker bound to one pair of streams.
  *
+ * `theme` decides *how* a question is asked and nothing else. Every function
+ * below returns the same values through either path, which is what lets the
+ * choice be made here instead of at four call sites — and what lets the whole
+ * existing test suite drive the classic path unchanged by simply not supplying
+ * one. The default theme knows about no terminal at all, so it answers no to
+ * `selection`, which is the conservative answer and the right one for a
+ * prompter built from streams nobody has described.
+ *
  * @param {{input: NodeJS.ReadableStream, output: NodeJS.WritableStream,
- *          interactive?: boolean, retries?: number}} options
+ *          interactive?: boolean, retries?: number, theme?: object}} options
  * @returns {{interactive: boolean,
  *            confirm: (question: string, options?: {defaultAnswer?: boolean}) => Promise<boolean|null>,
  *            chooseMany: (question: string, config?: object) => Promise<unknown[]|null>,
@@ -39,7 +71,13 @@ const NO = new Set(["n", "no"]);
  *            text: (question: string) => Promise<string|null>,
  *            close: () => void}}
  */
-export function createPrompter({ input, output, interactive = false, retries = 3 }) {
+export function createPrompter({
+  input,
+  output,
+  interactive = false,
+  retries = 3,
+  theme = createTheme(),
+}) {
   let reader = null;
 
   // Created on first use, not here. A run that never reaches a question — a
@@ -47,10 +85,23 @@ export function createPrompter({ input, output, interactive = false, retries = 3
   // reader to stdin, because attaching one resumes the stream and a process
   // holding an open stdin does not exit on its own.
   function ensureReader() {
-    if (reader === null) reader = createReader({ input, output });
+    if (reader === null) reader = createReader({ input, output, theme });
     return reader;
   }
 
+  /**
+   * Ask one question with the arrow keys.
+   *
+   * The Interface is handed over rather than a pair of streams, because the
+   * selector's whole contract is that it borrows from an open readline and
+   * gives it back. Nothing here consults `input.isTTY`: the decision was made
+   * once, in the theme, and a module that re-derived it could disagree with the
+   * one place that is allowed to have an opinion — and could not be tested over
+   * a pipe at all.
+   */
+  const ask = (question, config) =>
+    select({ readline: ensureReader().readline, theme, question, ...config });
+
   return {
     interactive,
 
@@ -59,6 +110,20 @@ export function createPrompter({ input, output, interactive = false, retries = 3
         throw new Error(`refusing to ask "${question}": this prompter is not interactive`);
       }
 
+      // Two rows rather than a typed letter. `y` and `n` still work and are
+      // deliberately not printed: the presented interaction is the one the hint
+      // line describes, and an accelerator that has to be advertised is a second
+      // thing to learn rather than a shortcut for people who already know it.
+      if (theme.selection) {
+        return ask(question, {
+          options: [
+            { label: "Yes", value: true, key: "y" },
+            { label: "No", value: false, key: "n" },
+          ],
+          initial: [defaultAnswer],
+        });
+      }
+
       const suffix = defaultAnswer ? "[Y/n]" : "[y/N]";
 
       for (let attempt = 0; attempt < retries; attempt += 1) {
@@ -103,12 +168,28 @@ export function createPrompter({ input, output, interactive = false, retries = 3
       }
       if (choices.length === 0) return [];
 
+      // A checkbox list, which is what this question always was. Note what does
+      // *not* move: the caller still supplies `{label, value}` and still reads
+      // back the chosen values in list order, so no decision about what the
+      // options mean has crossed into this file.
+      if (theme.selection) {
+        return ask(question, { options: choices, multi: true, initial: defaultSelection });
+      }
+
       const defaults = choices.filter((choice) => defaultSelection.includes(choice.value));
       const defaultNumbers = defaults.map((choice) => choices.indexOf(choice) + 1);
 
+      // The same option grammar the selector uses, inside a numbered list
+      // instead of a repainted block. An option that names the path it writes
+      // to is not a decoration the keyboard path earned — it is the answer to
+      // "what does checking this box do", and both paths owe it.
+      const labelWidth = alignmentWidth(choices, theme);
+
       const header = [
         `? ${question}`,
-        ...choices.map((choice, index) => `    ${index + 1}. ${choice.label}`),
+        ...choices.map(
+          (choice, index) => `    ${index + 1}. ${optionRow({ theme, option: choice, labelWidth })}`,
+        ),
         defaultNumbers.length > 0
           ? `  Numbers, comma-separated. Enter for the detected default [${defaultNumbers.join(",")}], or 0 for none.`
           : "  Numbers, comma-separated. Enter or 0 for none.",
@@ -158,12 +239,22 @@ export function createPrompter({ input, output, interactive = false, retries = 3
       if (choices.length === 0) return null;
 
       const fallback = choices.find((choice) => choice.value === defaultValue) ?? choices[0];
+
+      // The default becomes the highlighted row rather than a number in a
+      // sentence, so taking it still costs one keystroke.
+      if (theme.selection) {
+        return ask(question, { options: choices, initial: [fallback.value] });
+      }
+
       const defaultNumber = choices.indexOf(fallback) + 1;
+      const labelWidth = alignmentWidth(choices, theme);
 
       output.write(
         [
           `? ${question}`,
-          ...choices.map((choice, index) => `    ${index + 1}. ${choice.label}`),
+          ...choices.map(
+            (choice, index) => `    ${index + 1}. ${optionRow({ theme, option: choice, labelWidth })}`,
+          ),
           `  A number, or Enter for [${defaultNumber}].`,
           "",
         ].join("\n"),
@@ -266,8 +357,16 @@ export function nonInteractivePrompter() {
  * with a closed stdin must fall through to the caller's decision about an
  * unanswered question, not hang.
  */
-function createReader({ input, output }) {
-  const readline = createInterface({ input, output });
+function createReader({ input, output, theme }) {
+  // `terminal` is forced only where the selector will run, and only ever from
+  // false to true. On a real terminal readline works this out for itself and
+  // the flag changes nothing; over a pipe it is what makes the keypress decoder
+  // exist at all, which is the difference between a selector that can be tested
+  // and one that can only be tried. It is never forced *off*, so no classic run
+  // has its line editing altered by this.
+  const readline = createInterface(
+    theme?.selection ? { input, output, terminal: true } : { input, output },
+  );
   const delivered = [];
   const waiting = [];
   let closed = false;
@@ -284,6 +383,12 @@ function createReader({ input, output }) {
   });
 
   return {
+    // The Interface itself, for the one caller that needs the *owner* rather
+    // than a line: the selector borrows this object's listeners and hands them
+    // back. Exposed rather than re-created, because a second Interface over the
+    // same stdin would be a second thing turning raw mode on and off.
+    readline,
+
     /**
      * Print `text` and resolve with the next line, or null at end of input.
      *

package/src/select.mjs

@@ -0,0 +1,426 @@
+/**
+ * A vertical list you answer with the arrow keys, drawn on a terminal that
+ * belongs to somebody else.
+ *
+ * The whole design follows from one decision: **readline stays the owner of raw
+ * mode for the entire run.** `setRawMode` is never called here, or anywhere in
+ * this package. `createInterface` turns raw mode on because stdin is a TTY and
+ * `rl.close()` turns it off, and this module simply borrows the keyboard in
+ * between and gives it back. Owning raw mode would mean owning its restoration
+ * on every exit path including the ones nobody plans for, and the interrupt
+ * guarantee this package already has would become something to maintain rather
+ * than something that holds by construction.
+ *
+ * ## Two listeners are borrowed, not one
+ *
+ * An open Interface registers exactly one `keypress` listener on its input and
+ * exactly one `resize` listener on its output — verified identical on Node
+ * 18.12.1, 18.17.0, 20.20.2, 22.23.1 and 26.5.0.
+ *
+ * The first is obvious: removing it disengages readline's line editor
+ * completely — no echo, no history, no line buffer — while the Interface stays
+ * open and therefore still holds raw mode. The stream's keypress decoder keeps
+ * running because a listener of our own goes on immediately.
+ *
+ * The second was found by experiment and is **not optional**. On SIGWINCH an
+ * open Interface refreshes its own line, emitting `ESC[1G`, `ESC[0J` and
+ * `ESC[3G` — none of which are in this package's escape budget — and painting
+ * its default `"> "` prompt into the middle of the frame. Borrowing the
+ * keyboard without borrowing this leaves readline drawing on top of us the
+ * moment someone drags a window edge.
+ *
+ * ## The cursor is never hidden
+ *
+ * No `?25l`, ever. It parks visibly at column 0 below the block, which is why
+ * nothing needs restoring, why no signal handler exists, and why an interrupted
+ * run cannot leave a terminal with an invisible cursor. A repainting renderer
+ * is exactly the kind of code that reaches for cursor hiding, so the absence is
+ * stated here rather than left to be noticed.
+ *
+ * ## The question is printed once, above everything this module repaints
+ *
+ * The repainted block is the option rows, a blank line, and the hint — and
+ * nothing else. The question is written once before the block and never
+ * touched again.
+ *
+ * That is a width decision rather than an aesthetic one. The longest question
+ * the CLI asks is 70 cells, so a question inside the block would force a
+ * minimum terminal width of 71 and put keyboard selection out of reach of a
+ * split pane. Outside the block it is free to wrap across as many rows as it
+ * likes: the cursor-up count is computed over the block, the question is not in
+ * it, and a row count that is not part of the arithmetic cannot corrupt it.
+ *
+ * ## Every row is clipped, and `.length` is never a width
+ *
+ * The byte stream this renderer emits is width-independent — it always says
+ * `ESC[7A` for a seven-row block — so a row wider than the terminal takes two
+ * rows, the cursor moves up one row too few, and every repaint leaves a copy of
+ * the frame behind. Reproduced during the prototype at 24 columns: five copies
+ * of the question for four keypresses.
+ *
+ * Clipping every row to `columns - 1` makes the row count equal the line count
+ * by construction. It has to be `theme.clip` and `theme.width` rather than
+ * `String.prototype.slice` and `.length`: `theme.ok("✓ Git repository detected")`
+ * has a `.length` of 34 and occupies 25 cells, and a slice through an escape
+ * sequence prints its tail as literal text.
+ *
+ * ## What this module deliberately is not
+ *
+ * No filtering, no fuzzy search, no scrolling viewport, no mouse, no spinner,
+ * no animation, no colour of its own. The highlight is carried by a pointer
+ * glyph, which is the one presentation that survives every tier, both
+ * alphabets, and a terminal that renders no colour at all.
+ */
+
+/** Terminal width to assume when the stream will not say. */
+const FALLBACK_COLUMNS = 80;
+
+/**
+ * How wide the terminal is *right now*, not when the theme was built.
+ *
+ * Deliberately read from the stream on every paint. A window can be dragged
+ * while a question is on screen, and a renderer clipping against a remembered
+ * width would clip against a terminal that no longer exists.
+ */
+function liveColumns(output, theme) {
+  const columns = output?.columns;
+  if (Number.isInteger(columns) && columns > 0) return columns;
+  return theme.columns ?? FALLBACK_COLUMNS;
+}
+
+/**
+ * Pad `text` on the right to `cells` columns of *rendered* width.
+ *
+ * Not `padEnd`, which counts UTF-16 units: it pads `[x]` and `◉` to different
+ * places, and would pad a coloured string by the length of its escape sequence.
+ */
+function padTo(text, cells, theme) {
+  const short = cells - theme.width(text);
+  return short > 0 ? text + " ".repeat(short) : text;
+}
+
+/**
+ * How wide the label column has to be for the second column to line up.
+ *
+ * Zero when there is nothing to line up against. A list of editors has nothing
+ * to the right of its labels, and padding them would emit trailing whitespace
+ * that means nothing and clips first.
+ *
+ * @param {{label: string, hint?: string}[]} options
+ * @param {object} theme
+ * @returns {number}
+ */
+export function alignmentWidth(options, theme) {
+  if (!options.some((option) => Boolean(option.hint))) return 0;
+  return Math.max(...options.map((option) => theme.width(option.label)));
+}
+
+/**
+ * One option, as text: its label, the path it writes to, and whatever the
+ * detector had to say about it.
+ *
+ * Exported because **both** renderers need the same grammar. The classic
+ * numbered list and the keyboard selector draw completely different frames
+ * around an option, but the option itself reads the same in each — and it has
+ * to, because the classic path is a supported way to answer the question and
+ * not a reduced one. Two implementations of this sentence would drift, and the
+ * drift would be invisible until someone ran the same install twice under
+ * different terminals.
+ *
+ * What is *not* here: the pointer, the checkbox, and the clipping. Those belong
+ * to a frame, and only one of the two renderers draws them.
+ *
+ * @param {object} args
+ * @param {object} args.theme
+ * @param {{label: string, hint?: string, note?: string}} args.option
+ * @param {number} [args.labelWidth] - from `alignmentWidth`
+ * @param {boolean} [args.withNote] - false to compose the row without its
+ *   suffix, which is how a caller asks "how short can this row be".
+ * @returns {string}
+ */
+export function optionRow({ theme, option, labelWidth = 0, withNote = true }) {
+  const label = labelWidth > 0 ? padTo(option.label, labelWidth, theme) : option.label;
+  const row = label + (option.hint ? `  -> ${option.hint}` : "");
+  return withNote && option.note ? `${row}   ${option.note}` : row;
+}
+
+/**
+ * Build the block this renderer repaints: the option rows, a blank line, and
+ * the hint.
+ *
+ * Pure, and exported for that reason — the no-wrap guarantee is a property of
+ * these strings at a given width, and asserting it should not require
+ * synthesizing a terminal and pressing keys at it.
+ *
+ * Every returned line is already clipped to `columns - 1`, so the caller may
+ * count them as rows without checking anything.
+ *
+ * @param {object} args
+ * @param {object} args.theme
+ * @param {{label: string, value: unknown, hint?: string, note?: string}[]} args.options
+ * @param {number} args.cursor - index of the highlighted row
+ * @param {Set<number>} [args.selected] - checked indices, multi-select only
+ * @param {boolean} [args.multi]
+ * @param {number} args.columns
+ * @returns {string[]}
+ */
+export function renderBlock({ theme, options, cursor, selected = new Set(), multi = false, columns }) {
+  const budget = Math.max(0, columns - 1);
+  const glyph = theme.glyph;
+
+  // An unhighlighted row spends the same cells on nothing that a highlighted one
+  // spends on the pointer, so the labels never shift sideways as the cursor
+  // moves. Measured rather than assumed to be one: `❯` is one cell and `>` is
+  // one cell today, and a future pointer that is not would silently misalign
+  // every row.
+  const blank = " ".repeat(theme.width(glyph.pointer));
+
+  const labelWidth = alignmentWidth(options, theme);
+
+  const rows = options.map((option, index) => {
+    const pointer = index === cursor ? glyph.pointer : blank;
+    const box = multi ? `${selected.has(index) ? glyph.checked : glyph.unchecked} ` : "";
+    const frame = `${pointer} ${box}`;
+
+    // The suffix renders whole or not at all.
+    //
+    // `note` carries `(detected)`, which the ENVIRONMENT phase has already
+    // reported — so it duplicates information rather than carrying it, and a
+    // truncated `(detec` would be strictly worse than its absence. This is also
+    // why the minimum width is 49 rather than the wider terminal a guaranteed
+    // `note` would demand: a suffix that says nothing new does not get to decide
+    // whether the whole interaction is available.
+    const decorated = frame + optionRow({ theme, option, labelWidth });
+    const bare = frame + optionRow({ theme, option, labelWidth, withNote: false });
+
+    return theme.clip(theme.width(decorated) <= budget ? decorated : bare, budget);
+  });
+
+  const keys = multi
+    ? `${glyph.arrowUp}${glyph.arrowDown} move   space toggle   enter confirm`
+    : `${glyph.arrowUp}${glyph.arrowDown} move   enter confirm`;
+
+  return [...rows, "", theme.clip(`  ${keys}`, budget)];
+}
+
+/**
+ * Ask one question with the arrow keys, over a readline Interface somebody else
+ * opened.
+ *
+ * Returns the chosen `value`, or an array of them when `multi`, or `null` when
+ * nobody answered — Escape, or a stream that ended. `null` is the same refusal
+ * every existing call site already reads from the classic path, which is what
+ * lets this be swapped in behind an unchanged interface.
+ *
+ * @param {object} args
+ * @param {import("node:readline").Interface} args.readline - the raw-mode owner
+ * @param {object} args.theme
+ * @param {string} args.question
+ * @param {{label: string, value: unknown, hint?: string, note?: string, key?: string}[]} args.options
+ * @param {boolean} [args.multi]
+ * @param {unknown[]} [args.initial] - values checked at the start in `multi`,
+ *   and the value highlighted at the start otherwise. One shape for both, so a
+ *   caller never has to remember which mode takes which.
+ * @param {() => void} [args.raiseInterrupt] - how Ctrl-C re-raises. Injected so
+ *   that a test can observe the interrupt rather than be killed by it.
+ * @returns {Promise<unknown|unknown[]|null>}
+ */
+export function select({
+  readline,
+  theme,
+  question,
+  options,
+  multi = false,
+  initial = [],
+  raiseInterrupt = () => process.kill(process.pid, "SIGINT"),
+}) {
+  // Nothing to choose between is not a question. Returning before anything is
+  // printed keeps an empty list from leaving a hint line on screen that no key
+  // can dismiss.
+  if (!Array.isArray(options) || options.length === 0) return Promise.resolve(null);
+
+  const input = readline.input;
+  const output = readline.output;
+  const write = (text) => output.write(text);
+
+  const selected = new Set();
+  if (multi) {
+    options.forEach((option, index) => {
+      if (initial.includes(option.value)) selected.add(index);
+    });
+  }
+
+  // In `multi` the cursor starts at the top whatever is checked; in a
+  // single-select it starts on the answer the caller would have defaulted to,
+  // which is what keeps the common case one keystroke.
+  const highlighted = multi ? -1 : options.findIndex((option) => initial.includes(option.value));
+  let cursor = highlighted >= 0 ? highlighted : 0;
+
+  // How many rows the block on screen occupies. Zero means nothing has been
+  // drawn yet, which is also what a resize resets it to.
+  let painted = 0;
+
+  const paint = () => {
+    const lines = renderBlock({
+      theme,
+      options,
+      cursor,
+      selected,
+      multi,
+      columns: liveColumns(output, theme),
+    });
+
+    // Back to the top of the block drawn last time, then rewrite every row in
+    // place. Each row is cleared before it is written, so a shorter row can
+    // never leave the tail of a longer one behind it.
+    write(theme.line.up(painted));
+    for (const line of lines) write(theme.line.start() + theme.line.clear() + line + "\n");
+    painted = lines.length;
+
+    // The cursor is now parked at column 0 below the block, plainly visible.
+  };
+
+  return new Promise((resolve) => {
+    let settled = false;
+
+    /**
+     * Repaint from scratch, because the block on screen belongs to a width that
+     * no longer exists.
+     *
+     * `painted` counts rows at the *old* width, so moving up by it would be
+     * wrong however carefully it was counted. Forgetting it is the honest
+     * recovery: the stale frame stays in scrollback and a clean one is drawn
+     * below it. A resize costs one duplicated frame and never a corrupted
+     * terminal.
+     */
+    const onResize = () => {
+      painted = 0;
+      paint();
+    };
+
+    function onKey(_sequence, key = {}) {
+      // Ctrl-C. Borrowing readline's keypress listener took its Ctrl-C handling
+      // with it, so that handling is owed back: give the keyboard up, let
+      // readline drop raw mode on close, then re-raise the signal so the process
+      // dies exactly the way it would have anyway — exit 130, no handler,
+      // nothing swallowed.
+      if (key.ctrl && key.name === "c") {
+        if (settled) return;
+        settled = true;
+
+        // Restore first, so that closing readline finds the terminal exactly as
+        // readline left it — and so the `close` listener below, which would
+        // otherwise fire from this very `close()`, is already gone.
+        restore();
+        write("\n");
+        readline.close();
+        raiseInterrupt();
+
+        // Reached only if the interrupt did not end the process, which is the
+        // case under test and never in a real run. Settling is strictly safer
+        // than leaving a promise nobody can resolve.
+        resolve(null);
+        return;
+      }
+
+      if (key.name === "up" || key.name === "k") {
+        cursor = (cursor - 1 + options.length) % options.length;
+        paint();
+        return;
+      }
+
+      if (key.name === "down" || key.name === "j") {
+        cursor = (cursor + 1) % options.length;
+        paint();
+        return;
+      }
+
+      if (multi && key.name === "space") {
+        if (selected.has(cursor)) selected.delete(cursor);
+        else selected.add(cursor);
+        paint();
+        return;
+      }
+
+      if (key.name === "escape") {
+        paint();
+        finish(null);
+        return;
+      }
+
+      if (key.name === "return" || key.name === "enter") {
+        paint();
+        finish(answer());
+        return;
+      }
+
+      // Hidden accelerators, and hidden is the point.
+      //
+      // `confirm` is a two-row select, and `y`/`n` kept working there costs one
+      // lookup and saves anyone with the old habit a keystroke. They are not
+      // presented in the hint, because the presented interaction is the arrow
+      // keys — an accelerator advertised is a second interaction to learn.
+      // Single-select only: in a checkbox list every letter is a candidate for
+      // some future label and none of them should silently submit the form.
+      if (!multi) {
+        const accelerated = options.findIndex((option) => option.key !== undefined && option.key === key.name);
+        if (accelerated >= 0) {
+          cursor = accelerated;
+          paint();
+          finish(options[accelerated].value);
+          return;
+        }
+      }
+
+      // Everything else is ignored rather than echoed, which is what stops a
+      // stray escape byte from being printed as text into the middle of the
+      // block.
+    }
+
+    /** What the current state means as an answer. */
+    const answer = () =>
+      multi
+        ? [...selected].sort((a, b) => a - b).map((index) => options[index].value)
+        : options[cursor].value;
+
+    /**
+     * The stream ended while the question was on screen — Ctrl-D, or a pipe
+     * that closed under us.
+     *
+     * Resolving `null` rather than hanging: an unanswered question is a refusal
+     * every call site already knows how to read, and a prompt that waits
+     * forever on a closed stdin is how a CI job hangs at 3am.
+     */
+    const onClose = () => finish(null);
+
+    // Take the keyboard, and the resize handler, remembering exactly what was
+    // taken so exactly that can be given back.
+    const borrowedKeypress = input.listeners("keypress");
+    input.removeAllListeners("keypress");
+    const borrowedResize = output.listeners("resize");
+    output.removeAllListeners("resize");
+
+    function restore() {
+      input.removeListener("keypress", onKey);
+      for (const listener of borrowedKeypress) input.on("keypress", listener);
+      output.removeListener("resize", onResize);
+      for (const listener of borrowedResize) output.on("resize", listener);
+      readline.removeListener("close", onClose);
+    }
+
+    function finish(value) {
+      if (settled) return;
+      settled = true;
+      restore();
+      resolve(value);
+    }
+
+    input.on("keypress", onKey);
+    output.on("resize", onResize);
+    readline.on("close", onClose);
+
+    // Once, above the block, and never again. It may wrap; nothing counts it.
+    write(`? ${question}\n\n`);
+    paint();
+  });
+}