@devmarketplacenpm/devmp 0.1.1-beta.5

package/lib/tty/composer.js

@@ -0,0 +1,680 @@
+"use strict";
+
+const readline = require("readline");
+const { color } = require("../ui");
+const { displayWidth, wrap } = require("./ansi");
+
+// The composer owns stdin in raw mode for the whole interactive session. That
+// is what lets the user keep typing while a turn is streaming: keystrokes are
+// ours to interpret, so a running turn no longer has to block the prompt.
+//
+// It also owns the live region, because the caret has to be placed inside the
+// input box and only one component can do that coherently. The shell supplies
+// the rows above the box through `statusLines()`.
+
+const HISTORY_LIMIT = 100;
+
+// Ask the terminal to wrap pasted text in \e[200~ … \e[201~. Without it a
+// pasted stack trace arrives as ordinary keystrokes, every embedded newline
+// reads as Enter, and one paste fires one agent turn per line — nonsense
+// questions, billed individually. Node's readline already decodes the markers
+// into `paste-start` / `paste-end` keypresses.
+const PASTE_ON = "\u001b[?2004h";
+const PASTE_OFF = "\u001b[?2004l";
+
+// A pasted file should not push the whole conversation off screen. Past this
+// many rows the box scrolls around the caret instead of growing.
+const MAX_INPUT_ROWS = 12;
+
+/**
+ * Undo everything we did to the terminal, whatever killed us.
+ *
+ * The shell hides the cursor and turns on bracketed paste. A clean exit undoes
+ * both; a crash or a SIGTERM does not, and the user is left with an invisible
+ * cursor and `200~` glued to the front of every paste in whatever they run
+ * next — until they think to type `reset`. Cheap to guarantee, so guarantee it.
+ */
+function armTerminalRestore(output) {
+  let done = false;
+  const restore = () => {
+    if (done) return;
+    done = true;
+    try {
+      output.write?.(PASTE_OFF);
+      output.write?.("\u001b[?25h");
+    } catch {
+      /* the stream is already gone; nothing left to restore */
+    }
+  };
+
+  const onSignal = (signal) => {
+    restore();
+    process.off("exit", restore);
+    // Re-raise so the exit code still says what killed us.
+    process.kill(process.pid, signal);
+  };
+  const onSigterm = () => onSignal("SIGTERM");
+  const onSighup = () => onSignal("SIGHUP");
+
+  process.on("exit", restore);
+  process.once("SIGTERM", onSigterm);
+  process.once("SIGHUP", onSighup);
+
+  return () => {
+    restore();
+    process.off("exit", restore);
+    process.off("SIGTERM", onSigterm);
+    process.off("SIGHUP", onSighup);
+  };
+}
+
+function boxRow(inner, width) {
+  const pad = Math.max(0, width - 4 - displayWidth(inner));
+  return `${color.dim("│")} ${inner}${" ".repeat(pad)} ${color.dim("│")}`;
+}
+
+/**
+ * Show at most `cap` rows, keeping the caret in view. Returns how many rows
+ * fell off each end so the caller can say so rather than silently hiding them.
+ */
+function windowRows(rows, caretRow, cap) {
+  if (rows.length <= cap) {
+    return { rows, offset: 0, hiddenAbove: 0, hiddenBelow: 0 };
+  }
+  const half = Math.floor(cap / 2);
+  const offset = Math.max(0, Math.min(caretRow - half, rows.length - cap));
+  return {
+    rows: rows.slice(offset, offset + cap),
+    offset,
+    hiddenAbove: offset,
+    hiddenBelow: rows.length - (offset + cap),
+  };
+}
+
+/**
+ * Greedy word-wrap that also reports where `caretIndex` lands. Wrapping and
+ * caret placement have to come from one pass — computing them separately lets
+ * them disagree whenever a word straddles a wrap point, which shows up as a
+ * cursor sitting one row away from the character it is actually editing.
+ */
+function layoutInput(value, caretIndex, width) {
+  const limit = Math.max(1, width);
+  const glyphs = Array.from(value);
+  const rows = [];
+  let row = "";
+  let rowWidth = 0;
+  let caretRow = 0;
+  let caretCol = 0;
+  let placed = false;
+
+  const flush = () => {
+    rows.push(row);
+    row = "";
+    rowWidth = 0;
+  };
+
+  for (let i = 0; i < glyphs.length; i += 1) {
+    if (i === caretIndex) {
+      caretRow = rows.length;
+      caretCol = rowWidth;
+      placed = true;
+    }
+    const glyph = glyphs[i];
+    if (glyph === "\n") {
+      flush();
+      continue;
+    }
+    const glyphWidth = displayWidth(glyph);
+    if (rowWidth + glyphWidth > limit) flush();
+    row += glyph;
+    rowWidth += glyphWidth;
+  }
+
+  if (!placed) {
+    caretRow = rows.length;
+    caretCol = rowWidth;
+  }
+  rows.push(row);
+  return { rows, caretRow, caretCol };
+}
+
+function createComposer({
+  screen,
+  statusLines = () => [],
+  hintLines = () => [],
+  placeholder = "Describe a task, ask a question, or /help",
+  promptLabel = () => "›",
+  onSubmit,
+  onCancel,
+  onExit,
+  onPaste,
+  // (value, caretIndex) -> { from, to, insert, options } | null. Async, because
+  // completing a path means hitting the filesystem.
+  completer,
+  // Seeded from disk so up-arrow reaches yesterday's prompts, not just this
+  // session's. The shell owns persistence; the composer just reports changes.
+  initialHistory = [],
+  onHistoryChange,
+  // Injectable so the key handling can be driven in tests without putting a
+  // real terminal into raw mode.
+  input = process.stdin,
+  output = process.stdout,
+}) {
+
+  let chars = [];
+  let caret = 0;
+  let history = Array.isArray(initialHistory)
+    ? initialHistory.slice(-HISTORY_LIMIT)
+    : [];
+  let historyIndex = -1;
+  let draft = "";
+  let queue = [];
+  let busy = false;
+  let mode = "input";
+  let ask = null;
+  let interruptArmed = false;
+  let started = false;
+  // Set between paste-start and paste-end. While it holds, newlines are text
+  // rather than Enter, and redraws are suppressed — a 2,000-character paste is
+  // 2,000 keypresses, and repainting on each one takes seconds.
+  let pasting = false;
+  let pastedLines = 0;
+  let completionOptions = [];
+  let completing = false;
+  let disarmRestore = null;
+
+  const text = () => chars.join("");
+
+  /** Rows of the input box, already wrapped to the terminal so each returned
+   *  line is exactly one terminal row and the caret maps 1:1 onto it. */
+  function inputLines() {
+    const width = screen.columns;
+    const contentWidth = Math.max(8, width - 6);
+    const label = promptLabel();
+    const value = text();
+
+    const rows = [];
+    let caretRow = 0;
+    let caretCol = 0;
+
+    if (mode === "ask") {
+      const question = ask.question;
+      for (const row of wrap(question, contentWidth)) rows.push(row);
+      const answer = ask.freeText ? value : "";
+      const line = `${color.dim(ask.hint)}${answer ? ` ${answer}` : ""}`;
+      rows.push(line);
+      caretRow = rows.length - 1;
+      caretCol =
+        displayWidth(ask.hint) + (answer ? 1 + displayWidth(answer) : 0);
+    } else if (!value) {
+      rows.push(`${color.cyan(label)} ${color.dim(placeholder)}`);
+      caretRow = 0;
+      caretCol = displayWidth(label) + 1;
+    } else {
+      const indent = displayWidth(label) + 1;
+      const layout = layoutInput(value, caret, contentWidth - indent);
+      const cap = Math.max(3, Math.min(MAX_INPUT_ROWS, screen.rows - 8));
+      const view = windowRows(layout.rows, layout.caretRow, cap);
+
+      if (view.hiddenAbove) {
+        rows.push(color.dim(`  ⋯ ${view.hiddenAbove} line(s) above`));
+      }
+      caretRow = rows.length + (layout.caretRow - view.offset);
+      caretCol = indent + layout.caretCol;
+      view.rows.forEach((row, index) => {
+        const absolute = view.offset + index;
+        const prefix =
+          absolute === 0 ? color.cyan(label) : " ".repeat(displayWidth(label));
+        rows.push(`${prefix} ${row}`);
+      });
+      if (view.hiddenBelow) {
+        rows.push(color.dim(`  ⋯ ${view.hiddenBelow} line(s) below`));
+      }
+    }
+
+    const top = color.dim(`╭${"─".repeat(Math.max(2, screen.columns - 2))}╮`);
+    const bottom = color.dim(`╰${"─".repeat(Math.max(2, screen.columns - 2))}╯`);
+    const boxed = rows.map((row) => boxRow(row, screen.columns));
+
+    return {
+      lines: [top, ...boxed, bottom],
+      caret: { line: 1 + caretRow, column: 2 + caretCol },
+    };
+  }
+
+  /** The choices from an ambiguous Tab, laid out across the terminal width. */
+  function completionLines() {
+    if (!completionOptions.length) return [];
+    const width = Math.max(20, screen.columns - 4);
+    const cellWidth =
+      Math.max(...completionOptions.map((item) => displayWidth(item))) + 2;
+    const perRow = Math.max(1, Math.floor(width / cellWidth));
+    const lines = [];
+    for (let i = 0; i < completionOptions.length; i += perRow) {
+      const cells = completionOptions
+        .slice(i, i + perRow)
+        .map((item) => item + " ".repeat(cellWidth - displayWidth(item)));
+      lines.push(`  ${color.dim(cells.join("").trimEnd())}`);
+    }
+    return lines;
+  }
+
+  async function complete() {
+    if (!completer || completing) return;
+    completing = true;
+    try {
+      const result = await completer(text(), caret);
+      if (!result) {
+        completionOptions = [];
+        return;
+      }
+      const insert = Array.from(result.insert ?? "");
+      chars = [
+        ...chars.slice(0, result.from),
+        ...insert,
+        ...chars.slice(result.to),
+      ];
+      caret = result.from + insert.length;
+      completionOptions = result.options ?? [];
+      if (result.truncated) {
+        completionOptions = [
+          ...completionOptions,
+          `… +${result.truncated} more`,
+        ];
+      }
+    } catch {
+      // A completion that fails is a non-event: never let it take the shell
+      // down mid-keystroke.
+      completionOptions = [];
+    } finally {
+      completing = false;
+      refresh();
+    }
+  }
+
+  function queueLines() {
+    if (queue.length === 0) return [];
+    return queue.map(
+      (item, index) =>
+        `  ${color.dim(`${index + 1}.`)} ${color.dim(
+          item.length > screen.columns - 12
+            ? `${item.slice(0, screen.columns - 15)}…`
+            : item
+        )}`
+    );
+  }
+
+  function refresh() {
+    if (!screen.isTty || !started || pasting) return;
+    const box = inputLines();
+    const status = statusLines();
+    const queued = queueLines();
+    const head = queued.length
+      ? [...status, color.dim(`  queued (${queued.length}) — esc to clear`), ...queued]
+      : status;
+    const lines = [...head, ...box.lines, ...completionLines(), ...hintLines()];
+    screen.setLive(lines, {
+      line: head.length + box.caret.line,
+      column: box.caret.column,
+    });
+  }
+
+  function setText(value) {
+    chars = Array.from(value);
+    caret = chars.length;
+  }
+
+  function clearInput() {
+    chars = [];
+    caret = 0;
+    historyIndex = -1;
+  }
+
+  function pushHistory(value) {
+    if (!value.trim()) return;
+    if (history[history.length - 1] === value) return;
+    history.push(value);
+    if (history.length > HISTORY_LIMIT) history.shift();
+    onHistoryChange?.(history.slice());
+  }
+
+  function submit() {
+    const value = text().trim();
+    if (!value) return;
+    pushHistory(value);
+    clearInput();
+    if (busy) {
+      queue.push(value);
+      refresh();
+      return;
+    }
+    refresh();
+    onSubmit?.(value);
+  }
+
+  function deleteWord() {
+    let i = caret;
+    while (i > 0 && /\s/.test(chars[i - 1])) i -= 1;
+    while (i > 0 && !/\s/.test(chars[i - 1])) i -= 1;
+    chars.splice(i, caret - i);
+    caret = i;
+  }
+
+  function handleAskKey(str, key) {
+    if (key.ctrl && key.name === "c") {
+      const { resolve, defaultValue } = ask;
+      ask = null;
+      mode = "input";
+      clearInput();
+      resolve(defaultValue);
+      refresh();
+      return;
+    }
+    if (ask.freeText) {
+      if (key.name === "return" || key.name === "enter") {
+        const answer = text().trim();
+        const resolve = ask.resolve;
+        clearInput();
+        ask = null;
+        mode = "input";
+        resolve(answer);
+        refresh();
+        return;
+      }
+      handleEditing(str, key);
+      refresh();
+      return;
+    }
+
+    const pressed = (str || "").toLowerCase();
+    const choice =
+      ask.choices[pressed] ??
+      (key.name === "return" || key.name === "enter"
+        ? ask.defaultValue
+        : undefined);
+    if (choice === undefined) return;
+    const resolve = ask.resolve;
+    ask = null;
+    mode = "input";
+    resolve(choice);
+    refresh();
+  }
+
+  function handleEditing(str, key) {
+    if (key.name === "backspace") {
+      if (caret > 0) {
+        chars.splice(caret - 1, 1);
+        caret -= 1;
+      }
+      return;
+    }
+    if (key.name === "delete") {
+      if (caret < chars.length) chars.splice(caret, 1);
+      return;
+    }
+    if (key.name === "left") {
+      caret = Math.max(0, caret - 1);
+      return;
+    }
+    if (key.name === "right") {
+      caret = Math.min(chars.length, caret + 1);
+      return;
+    }
+    if (key.ctrl && key.name === "a") {
+      caret = 0;
+      return;
+    }
+    if (key.ctrl && key.name === "e") {
+      caret = chars.length;
+      return;
+    }
+    if (key.ctrl && key.name === "u") {
+      chars.splice(0, caret);
+      caret = 0;
+      return;
+    }
+    if (key.ctrl && key.name === "k") {
+      chars.splice(caret);
+      return;
+    }
+    if (key.ctrl && key.name === "w") {
+      deleteWord();
+      return;
+    }
+    // Ctrl-J inserts a literal newline so a prompt can span lines; Enter alone
+    // always submits, which is what people expect from a chat composer.
+    if (key.ctrl && key.name === "j") {
+      chars.splice(caret, 0, "\n");
+      caret += 1;
+      return;
+    }
+    insertText(str, key);
+  }
+
+  function insertText(str, key) {
+    if (!str || key.ctrl || key.meta) return;
+    for (const char of str) {
+      if (char === "\r" || char === "\n") continue;
+      chars.splice(caret, 0, char);
+      caret += 1;
+    }
+  }
+
+  function onKeypress(str, key) {
+    if (!key) return;
+
+    if (key.name === "paste-start") {
+      pasting = true;
+      pastedLines = 0;
+      return;
+    }
+    if (key.name === "paste-end") {
+      pasting = false;
+      // Enter right after a paste should send it, not append a blank line, so
+      // the newline count is what the user is told about — not a submit.
+      if (pastedLines > 0) onPaste?.(pastedLines + 1);
+      refresh();
+      return;
+    }
+
+    // Inside a paste every key is literal text; none of the editing bindings
+    // below should fire, or a stack trace containing "^C" would cancel a turn.
+    if (pasting) {
+      if (key.name === "return" || key.name === "enter") {
+        chars.splice(caret, 0, "\n");
+        caret += 1;
+        pastedLines += 1;
+        return;
+      }
+      insertText(str, key);
+      return;
+    }
+
+    if (mode === "ask") {
+      handleAskKey(str, key);
+      return;
+    }
+
+    if (key.ctrl && key.name === "c") {
+      if (busy) {
+        onCancel?.();
+        return;
+      }
+      if (chars.length > 0) {
+        clearInput();
+        interruptArmed = false;
+        refresh();
+        return;
+      }
+      if (interruptArmed) {
+        onExit?.();
+        return;
+      }
+      interruptArmed = true;
+      refresh();
+      setTimeout(() => {
+        interruptArmed = false;
+        refresh();
+      }, 2000).unref?.();
+      return;
+    }
+
+    interruptArmed = false;
+
+    if (key.name === "tab") {
+      void complete();
+      return;
+    }
+    // Any other key means the choices on screen are stale.
+    completionOptions = [];
+
+    if (key.ctrl && key.name === "d" && chars.length === 0) {
+      onExit?.();
+      return;
+    }
+
+    if (key.name === "escape") {
+      if (queue.length) {
+        queue = [];
+      } else {
+        clearInput();
+      }
+      refresh();
+      return;
+    }
+
+    if (key.name === "return" || key.name === "enter") {
+      submit();
+      return;
+    }
+
+    if (key.name === "up" || key.name === "down") {
+      if (history.length === 0) return;
+      if (key.name === "up") {
+        if (historyIndex === -1) {
+          draft = text();
+          historyIndex = history.length - 1;
+        } else if (historyIndex > 0) {
+          historyIndex -= 1;
+        }
+        setText(history[historyIndex]);
+      } else if (historyIndex !== -1) {
+        if (historyIndex < history.length - 1) {
+          historyIndex += 1;
+          setText(history[historyIndex]);
+        } else {
+          historyIndex = -1;
+          setText(draft);
+        }
+      }
+      refresh();
+      return;
+    }
+
+    handleEditing(str, key);
+    refresh();
+  }
+
+  const onResize = () => {
+    screen.resize();
+    refresh();
+  };
+
+  const api = {
+    start() {
+      if (started) return;
+      started = true;
+      readline.emitKeypressEvents(input);
+      if (input.isTTY) input.setRawMode(true);
+      if (screen.isTty) {
+        output.write?.(PASTE_ON);
+        disarmRestore = armTerminalRestore(output);
+      }
+      input.on("keypress", onKeypress);
+      output.on?.("resize", onResize);
+      input.resume?.();
+      refresh();
+    },
+
+    stop() {
+      if (!started) return;
+      started = false;
+      input.off("keypress", onKeypress);
+      output.off?.("resize", onResize);
+      // Left enabled, the next program to own this terminal receives paste
+      // markers it does not understand and prints them as literal text.
+      if (screen.isTty) output.write?.(PASTE_OFF);
+      disarmRestore?.();
+      disarmRestore = null;
+      if (input.isTTY) input.setRawMode(false);
+      input.pause?.();
+    },
+
+    refresh,
+
+    setBusy(value) {
+      busy = Boolean(value);
+      refresh();
+    },
+
+    get busy() {
+      return busy;
+    },
+
+    get history() {
+      return history.slice();
+    },
+
+    get interruptArmed() {
+      return interruptArmed;
+    },
+
+    /** Pull the next queued prompt, if the user typed ahead during a turn. */
+    shiftQueued() {
+      const next = queue.shift();
+      refresh();
+      return next;
+    },
+
+    get queued() {
+      return queue.slice();
+    },
+
+    clearQueue() {
+      queue = [];
+      refresh();
+    },
+
+    /**
+     * Take over the composer for an approval. `choices` maps a single key to a
+     * return value; omit it for a free-text answer.
+     */
+    question({ question, hint, choices, defaultValue = "no", freeText = false }) {
+      return new Promise((resolve) => {
+        // An approval can interrupt someone mid-sentence. Their draft is put
+        // back the moment the question is answered.
+        const heldDraft = text();
+        const heldCaret = caret;
+        clearInput();
+        mode = "ask";
+        ask = {
+          question,
+          hint: hint || (freeText ? "›" : "[y/n]"),
+          choices: choices || {},
+          defaultValue,
+          freeText,
+          resolve: (value) => {
+            chars = Array.from(heldDraft);
+            caret = Math.min(heldCaret, chars.length);
+            resolve(value);
+          },
+        };
+        refresh();
+      });
+    },
+  };
+
+  return api;
+}
+
+module.exports = { createComposer };