acuvo-code 0.3.6 → 0.4.1

package/ENTERPRISE.md

@@ -188,8 +188,8 @@ copy, but it *is* a place a process starts, and this is a list of those. Six and
 are the numbers to quote. Counting is the first thing a reviewer does.
 
 ⚠️ **This said "18 shipped files", then "41", then "90", then "101", then "108", and every
-one went stale in turn.** The package ships **119 files — 117 in `lib/`, 2 in
-`bin/` — about 77604 lines**, with **235 test files** beside them (counted 2026-08-22).
+one went stale in turn.** The package ships **120 files — 118 in `lib/`, 2 in
+`bin/` — about 77954 lines**, with **236 test files** beside them (counted 2026-08-22).
 
 ⭐ **AND THE 108 WENT STALE IN THE MOST INSTRUCTIVE WAY POSSIBLE: THREE OF THE FILES IT
 MISSED WERE REACHABLE FROM NOTHING.** `wiring-reach.test.mjs` was naming

package/lib/chat.mjs

@@ -22,6 +22,7 @@
  */
 
 import { createInterface } from 'node:readline';
+import { readBoxedLine } from './input-box.mjs';
 import { EXIT_INTERRUPTED } from './interrupt.mjs';
 import { parseSlash, runSlashCommand } from './slash.mjs';
 import { estimateMessagesTokens } from './compact.mjs';
@@ -319,7 +320,23 @@ export async function runChat({
   const queued = interactive ? null : await readAllLines(input);
   let queueIndex = 0;
 
-  const rl = interactive ? createInterface({ input, output, terminal: true }) : null;
+  /**
+   * ── ⚠️⚠️ READLINE IS GONE FROM THE INTERACTIVE PATH, AND IT HAD TO GO ──────
+   *
+   * `input-box.mjs` now owns the keyboard. Leaving the readline interface
+   * attached to the SAME stream was not merely redundant — both it and the box
+   * saw every Ctrl-C, so `onInterrupt` fired TWICE for one keypress. Measured,
+   * not theorised: a single `\x03` produced `['interrupt', 'interrupt']`.
+   *
+   * ⭐ A DOUBLE INTERRUPT IS NOT A COSMETIC BUG. The second Ctrl-C is the one
+   * that QUITS — so one press would have armed and fired the escape hatch in the
+   * same instant, ending a session the user meant only to nudge.
+   *
+   * The Node-internals note below about `question()` swallowing Ctrl-C is kept
+   * because it is why the box reads raw keys itself rather than asking readline
+   * for a line. It is history now, not a live constraint.
+   */
+  const rl = null;
   const state = { closed: false };
   /**
    * ⚠️ ATTACHED ONCE, NOT PER QUESTION — and the per-question version is why the
@@ -350,6 +367,8 @@ export async function runChat({
    * to the model; this is the variable that makes the verb real.
    */
   let pendingInject = null;
+  /** Lines the user has submitted this session — the box's Up/Down history. */
+  const typed = [];
 
   try {
     for (;;) {
@@ -374,12 +393,19 @@ export async function runChat({
        * because `columns` is `undefined` when stdout is not a TTY and enormous
        * when someone maximises on an ultrawide.
        */
-      const width = Math.max(40, Math.min(100, (output.columns ?? process.stdout.columns ?? 80) - 1));
-      if (interactive) output.write(`\n╭${'─'.repeat(width - 1)}\n`);
-      const line = interactive
-        ? await ask(rl, '│ › ', state)
-        : (queueIndex < queued.length ? queued[queueIndex++] : null);
-      if (interactive && line !== null) output.write(`╰${'─'.repeat(width - 1)}\n`);
+      let line;
+      if (interactive) {
+        output.write('\n');
+        const got = await readBoxedLine({
+          input,
+          output,
+          history: typed,
+          onInterrupt,
+        });
+        line = got.value;
+      } else {
+        line = queueIndex < queued.length ? queued[queueIndex++] : null;
+      }
       // Echo a piped prompt so a scripted transcript reads like a session.
       if (!interactive && line !== null && line.trim()) output.write(`› ${line.trim()}
 `);
@@ -389,6 +415,9 @@ export async function runChat({
       if (line === null) break;
       const task = line.trim();
       if (!task) continue;
+      // ⚠️ Deduped against the PREVIOUS entry only: pressing Up should walk
+      // distinct instructions, not scroll through five copies of `npm test`.
+      if (typed[typed.length - 1] !== task) typed.push(task);
       if (QUIT.has(task.toLowerCase())) break;
 
       /**

package/lib/input-box.mjs

@@ -0,0 +1,326 @@
+/**
+ * ── ⭐⭐⭐ A PERSISTENT INPUT BOX, BECAUSE READLINE CANNOT DRAW ONE ──────────
+ *
+ * Roman, repeatedly: *"the box that I am typing in right now needs to be real."*
+ *
+ * ── ⚠️⚠️ WHY READLINE WAS NEVER GOING TO WORK, MEASURED ─────────────────────
+ *
+ * Pre-drawing a four-sided box and asking `readline.question()` to type inside
+ * it produces this on the very first keystroke:
+ *
+ *     \x1b[1G\x1b[0J
+ *
+ * Column 1, then **clear to end of screen**. Readline owns everything from the
+ * cursor down and erases it to redraw the line — so the bottom border and the
+ * right edge are gone before the user has typed a second character. No amount of
+ * re-drawing wins that fight; it repaints on every key.
+ *
+ * ⭐ SO THE ANSWER IS TO OWN THE RENDER. This is a small raw-mode line editor:
+ * it reads keys, keeps the buffer, and paints three lines itself. That is what
+ * every terminal app with a real input box does, and it is why they can have one.
+ *
+ * ── ⚠️ WHAT IT MUST NOT LOSE ────────────────────────────────────────────────
+ *
+ * A half-built line editor is WORSE than a plain prompt: backspace that does
+ * nothing, or an arrow key that prints `^[[D`, makes the tool feel broken in a
+ * way `› ` never did. So the keys people actually use are all handled —
+ * backspace, delete, left/right, home/end, word-left/right, history up/down,
+ * Ctrl-C, Ctrl-D, Ctrl-U/K/W — and each is tested.
+ */
+
+const ESC = '\x1b';
+const CSI = `${ESC}[`;
+
+/** Keys that are not text. Kept as one table so the handler stays readable. */
+const KEY = Object.freeze({
+  ENTER: '\r',
+  NEWLINE: '\n',
+  BACKSPACE: '\x7f',
+  BACKSPACE_ALT: '\b',
+  CTRL_C: '\x03',
+  CTRL_D: '\x04',
+  CTRL_U: '\x15',
+  CTRL_K: '\x0b',
+  CTRL_W: '\x17',
+  CTRL_A: '\x01',
+  CTRL_E: '\x05',
+});
+
+/**
+ * Visible width of a string, ignoring ANSI. Deliberately simple: this package
+ * has no dependencies and a full grapheme/east-asian-width implementation is a
+ * library. It is correct for the ASCII and box characters we draw, and errs by
+ * over-counting a wide glyph rather than under — which wraps early rather than
+ * overflowing the border.
+ */
+export function visibleWidth(s) {
+  return String(s ?? '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '').length;
+}
+
+/**
+ * Render the three lines of the box for a given buffer.
+ *
+ * Exported so the layout can be asserted without a terminal — the render and
+ * the key handling are separately testable, which is the only way a thing like
+ * this stays correct.
+ *
+ * @returns {{lines: string[], cursorColumn: number}} 1-based cursor column
+ */
+export function renderBox({ value = '', cursor = 0, columns = 80, prompt = '› ' } = {}) {
+  const width = Math.max(20, Math.min(100, columns - 1));
+  const inner = width - 2;
+  const promptWidth = visibleWidth(prompt);
+
+  /**
+   * ⚠️ THE VIEW SCROLLS, THE BUFFER DOES NOT. A long line must not wrap — a
+   * wrapped line pushes the bottom border down and the box stops being a box.
+   * So the buffer is windowed around the cursor and the border stays put, which
+   * is what every real input does.
+   */
+  const room = inner - promptWidth - 1;
+  let start = 0;
+  if (cursor > room) start = cursor - room;
+  const shown = value.slice(start, start + room);
+
+  const body = `${prompt}${shown}`;
+  const pad = ' '.repeat(Math.max(0, inner - visibleWidth(body)));
+
+  return {
+    lines: [
+      `╭${'─'.repeat(width - 2)}╮`,
+      `│${body}${pad}│`,
+      `╰${'─'.repeat(width - 2)}╯`,
+    ],
+    // 1-based: the │, then the prompt, then however far into the shown text.
+    cursorColumn: 1 + 1 + promptWidth + (cursor - start),
+  };
+}
+
+/**
+ * Apply one keypress to the editor state.
+ *
+ * ⚠️ PURE, AND THAT IS THE WHOLE POINT. Every key can be tested without a TTY,
+ * without timing, and without a terminal to inspect afterwards. The half of this
+ * module that touches the terminal does nothing but paint what this returns.
+ *
+ * @returns {{value, cursor, historyIndex, done?: 'submit'|'cancel'|'eof'}}
+ */
+export function applyKey(state, key) {
+  const { value, cursor, history = [], historyIndex = history.length } = state;
+  /**
+   * ⚠️ `history` IS CARRIED THROUGH, AND ITS ABSENCE WAS A REAL BUG. The first
+   * version returned only `{value, cursor, historyIndex}` — so the history array
+   * was dropped by the FIRST keystroke, and pressing Up afterwards silently did
+   * nothing. It looked like the history feature was unimplemented rather than
+   * like state was being lost, which is exactly the kind of bug a pure function
+   * makes visible and a stateful one hides.
+   */
+  const keep = (over = {}) => ({ value, cursor, history, historyIndex, draft: state.draft, ...over });
+
+  if (key === KEY.ENTER || key === KEY.NEWLINE) return keep({ done: 'submit' });
+  if (key === KEY.CTRL_C) return keep({ done: 'cancel' });
+  /**
+   * ⚠️ Ctrl-D IS EOF ONLY ON AN EMPTY LINE. On a line with text it is
+   * forward-delete — collapsing the two would exit the session when someone
+   * meant to delete a character, which is a data-loss-shaped surprise.
+   */
+  if (key === KEY.CTRL_D) {
+    if (value.length === 0) return keep({ done: 'eof' });
+    return keep({ value: value.slice(0, cursor) + value.slice(cursor + 1) });
+  }
+
+  if (key === KEY.BACKSPACE || key === KEY.BACKSPACE_ALT) {
+    if (cursor === 0) return keep();
+    return keep({ value: value.slice(0, cursor - 1) + value.slice(cursor), cursor: cursor - 1 });
+  }
+
+  if (key === KEY.CTRL_U) return keep({ value: value.slice(cursor), cursor: 0 });
+  if (key === KEY.CTRL_K) return keep({ value: value.slice(0, cursor) });
+  if (key === KEY.CTRL_A) return keep({ cursor: 0 });
+  if (key === KEY.CTRL_E) return keep({ cursor: value.length });
+
+  if (key === KEY.CTRL_W) {
+    const upto = value.slice(0, cursor);
+    const cut = upto.replace(/\s*\S+$/, '');
+    return keep({ value: cut + value.slice(cursor), cursor: cut.length });
+  }
+
+  // Arrows and Home/End arrive as escape sequences.
+  if (key === `${CSI}D`) return keep({ cursor: Math.max(0, cursor - 1) });
+  if (key === `${CSI}C`) return keep({ cursor: Math.min(value.length, cursor + 1) });
+  if (key === `${CSI}H` || key === `${CSI}1~`) return keep({ cursor: 0 });
+  if (key === `${CSI}F` || key === `${CSI}4~`) return keep({ cursor: value.length });
+  if (key === `${CSI}3~`) return keep({ value: value.slice(0, cursor) + value.slice(cursor + 1) });
+
+  /**
+   * History. ⚠️ The index may sit one PAST the end — that position is "the line
+   * I was typing", so walking up and back down returns what you had rather than
+   * silently eating it.
+   */
+  if (key === `${CSI}A`) {
+    if (historyIndex === 0 || history.length === 0) return keep();
+    const i = historyIndex - 1;
+    /**
+     * ⚠️ THE DRAFT IS SAVED ON THE WAY UP. Leaving it behind means a half-typed
+     * line is destroyed by a single Up press — the user glances at what they ran
+     * before, comes back, and their sentence is gone. Losing typed input to a
+     * navigation key is the least forgivable bug a line editor can have.
+     */
+    const draft = historyIndex === history.length ? value : state.draft;
+    return keep({ value: history[i], cursor: history[i].length, historyIndex: i, draft });
+  }
+  if (key === `${CSI}B`) {
+    if (historyIndex >= history.length) return keep({ draft: state.draft });
+    const i = historyIndex + 1;
+    const next = i === history.length ? (state.draft ?? '') : history[i];
+    return keep({ value: next, cursor: next.length, historyIndex: i, draft: state.draft });
+  }
+
+  /**
+   * ⚠️ EVERYTHING ELSE CONTROL-SHAPED IS DROPPED, NOT INSERTED. An unhandled
+   * escape sequence typed into the buffer shows the user `^[[5~` and looks like
+   * the tool is broken — the one impression a new line editor cannot afford.
+   */
+  if (key.startsWith(ESC)) return keep();
+  if (key.length === 1 && key < ' ') return keep();
+
+  return keep({ value: value.slice(0, cursor) + key + value.slice(cursor), cursor: cursor + key.length });
+}
+
+/**
+ * Split a raw chunk into keys. A paste arrives as one chunk and an arrow key as
+ * three bytes, so neither "one byte per key" nor "one chunk per key" is right.
+ */
+export function splitKeys(chunk) {
+  const s = String(chunk);
+  const keys = [];
+  for (let i = 0; i < s.length; i += 1) {
+    if (s[i] === ESC) {
+      const m = /^\x1b\[[0-9;]*[A-Za-z~]/.exec(s.slice(i));
+      if (m) { keys.push(m[0]); i += m[0].length - 1; continue; }
+    }
+    keys.push(s[i]);
+  }
+  return keys;
+}
+
+/**
+ * Draw the box and park the cursor inside it.
+ *
+ * ⚠️ THE CURSOR IS HIDDEN WHILE PAINTING. Without it, the cursor visibly darts
+ * to the end of each border as it is written — which reads as a flicker and is
+ * the difference between a rendered box and a drawn one.
+ */
+export function paint(output, state, { first = false } = {}) {
+  const { lines, cursorColumn } = renderBox(state);
+
+  /**
+   * ── ⚠️⚠️ THE CURSOR MATH, AND MY FIRST VERSION ATE THE SCREEN ──────────────
+   *
+   * Roman: *"it moves upwards every time you type a character then deletes the
+   * design you did."* Exactly right, and the arithmetic says why.
+   *
+   * After a paint the cursor rests on the INPUT line — line 2 of 3, not below
+   * the box. The first version began each repaint with `ESC[3A`, which is where
+   * it would be if the cursor were below. From line 2, moving up 3 lands ONE
+   * LINE ABOVE the top border — and the `ESC[0J` that follows clears from there
+   * to the bottom of the screen. So every keystroke crept upward and erased
+   * another line of the banner.
+   *
+   * ⭐ THE INVARIANT, WRITTEN DOWN BECAUSE IT IS THE WHOLE FUNCTION: this
+   * routine ENTERS with the cursor on the input line and LEAVES it there. So a
+   * repaint moves up exactly ONE line to reach the top border, and the final
+   * reposition moves up exactly one from the last line written.
+   *
+   *   ╭────────╮   <- line 1   ESC[1A from the input line reaches here
+   *   │› …      │   <- line 2   cursor lives here, in and out
+   *   ╰────────╯   <- line 3   cursor is here after writing; ESC[1A returns
+   *
+   * ⚠️ NO TRAILING NEWLINE. Writing one after the last border scrolls the
+   * viewport when the box is at the bottom of the screen, and every subsequent
+   * `up` is then off by a row for the rest of the session.
+   */
+  const home = first ? '' : `\r${CSI}1A`;
+  output.write(
+    `${CSI}?25l${home}${CSI}0J${lines.join('\n')}` +
+    `${CSI}1A\r${CSI}${cursorColumn}G${CSI}?25h`,
+  );
+}
+
+/**
+ * ── ⭐⭐⭐ THE ONLY PART THAT TOUCHES A TERMINAL ─────────────────────────────
+ *
+ * Reads one line inside the box. Everything decision-shaped lives in `applyKey`
+ * and `renderBox`, which are pure and fully tested; this function does nothing
+ * but move bytes and paint what they return.
+ *
+ * @returns {Promise<{value: string|null, reason: 'submit'|'cancel'|'eof'}>}
+ */
+export function readBoxedLine({ input, output, history = [], onInterrupt = null, prompt = '› ' }) {
+  return new Promise((resolve) => {
+    let state = { value: '', cursor: 0, history, historyIndex: history.length, draft: '' };
+    const columns = () => output.columns ?? process.stdout.columns ?? 80;
+
+    /**
+     * ⚠️ RAW MODE IS RESTORED ON EVERY EXIT PATH, INCLUDING THE UNHAPPY ONES.
+     * A process that leaves the terminal in raw mode hands the user a shell with
+     * no echo and no line editing — they have to type `reset` blind. That is the
+     * single worst thing a CLI can do to somebody's session.
+     */
+    let finished = false;
+    const finish = (value, reason) => {
+      if (finished) return;
+      finished = true;
+      input.off('data', onData);
+      input.off('end', onEnd);
+      try { input.setRawMode?.(false); } catch { /* not a TTY any more */ }
+      output.write('\n');
+      resolve({ value, reason });
+    };
+
+    const onEnd = () => finish(null, 'eof');
+
+    const onData = (chunk) => {
+      for (const key of splitKeys(chunk)) {
+        const next = applyKey(state, key);
+        if (next.done === 'submit') {
+          state = next;
+          // Repaint once so the committed line is what stays on screen.
+          paint(output, { ...state, columns: columns() });
+          return finish(state.value, 'submit');
+        }
+        if (next.done === 'cancel') {
+          /**
+           * ⚠️ Ctrl-C ON A NON-EMPTY LINE CLEARS IT; on an empty one it means
+           * "stop". Anything else makes the first Ctrl-C — the one people press
+           * to abandon a sentence — quit the whole session.
+           */
+          /**
+           * ⚠️⚠️ Ctrl-C NEVER ENDS THE READ — it clears the line and hands the
+           * event on. The first version finished with `cancel` on an empty line,
+           * which ended the session on the FIRST press: there was then no prompt
+           * for a second Ctrl-C to arrive at, so the "press again to quit"
+           * escape hatch could never fire. `onInterrupt` owns that decision (see
+           * `interrupt.mjs`), and it can only own it if it keeps being called.
+           *
+           * ⭐ It is also what every shell does: Ctrl-C gives you a fresh line.
+           * Quitting is `exit`, or Ctrl-D on an empty one.
+           */
+          state = { ...state, value: '', cursor: 0, historyIndex: history.length, draft: '' };
+          onInterrupt?.();
+          paint(output, { ...state, columns: columns() });
+          continue;
+        }
+        if (next.done === 'eof') return finish(null, 'eof');
+        state = next;
+        paint(output, { ...state, columns: columns() });
+      }
+    };
+
+    try { input.setRawMode?.(true); } catch { /* not a TTY */ }
+    input.resume?.();
+    paint(output, { ...state, columns: columns() }, { first: true });
+    input.on('data', onData);
+    input.once('end', onEnd);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acuvo-code",
-  "version": "0.3.6",
+  "version": "0.4.1",
   "description": "Acuvo Code — the terminal client for the Acuvo capability registry. Zero dependencies, by design.",
   "type": "module",
   "bin": {