@bakit-org/ai-sdlc-cli 0.0.0-stage → 0.1.1

package/lib/tui/keys.js

@@ -0,0 +1,182 @@
+'use strict';
+// Turns raw terminal input into key events:
+//   { name, text, ctrl, shift, meta }
+// name is 'char' (text holds the character), 'paste' (text holds the pasted
+// string), a control letter with ctrl:true ('c', 'u', ...), or one of
+// up down left right home end pageup pagedown insert delete enter tab
+// backspace escape unknown.
+
+const PASTE_START = '\x1b[200~';
+const PASTE_END = '\x1b[201~';
+const ARROWS = { A: 'up', B: 'down', C: 'right', D: 'left', H: 'home', F: 'end' };
+const TILDE = { 1: 'home', 2: 'insert', 3: 'delete', 4: 'end', 5: 'pageup', 6: 'pagedown', 7: 'home', 8: 'end' };
+const MAX_PASTE = 1024 * 1024;
+
+const key = (name, extra = {}) => ({ name, text: '', ctrl: false, shift: false, meta: false, ...extra });
+
+function csiKey(params, final) {
+  const parts = params.split(';');
+  const mod = parts.length > 1 ? Number(parts[1]) - 1 || 0 : 0;
+  const mods = { shift: Boolean(mod & 1), meta: Boolean(mod & 2), ctrl: Boolean(mod & 4) };
+  if (final === 'Z') return key('tab', { shift: true });
+  if (final === '~') return key(TILDE[parts[0]] || 'unknown', mods);
+  return key(ARROWS[final] || 'unknown', mods);
+}
+
+// feed() accepts chunks as the terminal delivers them: several keys in one
+// chunk, a bracketed paste split across chunks, CRLF Enter, an escape
+// sequence split across reads.
+//   escapeMs  how long a trailing lone ESC (or a bare ESC [ / ESC O) waits for
+//             the rest of its sequence before it is reported as the Escape key.
+//             0 reports it at once.
+//   pasteMs   a bracketed paste that never ends is abandoned after this long.
+// An unterminated paste can never swallow Ctrl-C (ETX), and is capped at 1 MB.
+function createKeyParser(emit, { escapeMs = 50, pasteMs = 2000 } = {}) {
+  let pending = '';
+  let paste = null;
+  let discarding = false;
+  let afterCR = false;
+  let escTimer = null;
+  let pasteTimer = null;
+
+  const later = (fn, ms) => {
+    const t = setTimeout(fn, ms);
+    if (t.unref) t.unref();
+    return t;
+  };
+  const stopEscTimer = () => {
+    if (escTimer) clearTimeout(escTimer);
+    escTimer = null;
+  };
+  const endPaste = (text) => {
+    if (pasteTimer) clearTimeout(pasteTimer);
+    pasteTimer = null;
+    if (text !== null) emit(key('paste', { text }));
+    paste = null;
+    discarding = false;
+  };
+
+  function holdEscape(rest) {
+    pending = rest;
+    if (escapeMs <= 0) return rest === '\x1b' ? flushEscape() : undefined;
+    stopEscTimer();
+    escTimer = later(flushEscape, escapeMs);
+    return undefined;
+  }
+
+  // The held ESC was not the start of a sequence: it is the Escape key, and
+  // whatever followed it is ordinary input.
+  function flushEscape() {
+    stopEscTimer();
+    const rest = pending;
+    pending = '';
+    if (!rest) return;
+    emit(key('escape'));
+    if (rest.length > 1) feed(rest.slice(1));
+  }
+
+  function collectPaste(data, i) {
+    if (!pasteTimer) pasteTimer = later(() => endPaste(discarding ? null : paste), pasteMs);
+    const chunk = data.slice(i);
+    const end = (paste + chunk).indexOf(PASTE_END);
+    if (end === -1) {
+      // No terminator yet: Ctrl-C must still work.
+      if (chunk.includes('\x03')) {
+        endPaste(null);
+        emit(key('c', { ctrl: true }));
+        return;
+      }
+      if (!discarding) paste += chunk;
+      if (paste.length > MAX_PASTE) {
+        emit(key('paste', { text: paste.slice(0, MAX_PASTE) }));
+        paste = '';
+        discarding = true;
+      }
+      return;
+    }
+    const full = paste + chunk;
+    const rest = full.slice(end + PASTE_END.length);
+    const text = discarding ? null : full.slice(0, Math.min(end, MAX_PASTE));
+    endPaste(text);
+    if (rest) feed(rest);
+  }
+
+  function feed(chunk) {
+    stopEscTimer();
+    const data = pending + chunk;
+    pending = '';
+    let i = 0;
+    while (i < data.length) {
+      const wasCR = afterCR;
+      afterCR = false;
+
+      if (paste !== null) {
+        collectPaste(data, i);
+        return;
+      }
+
+      const c = data[i];
+      if (c === '\x1b') {
+        const rest = data.slice(i);
+        if (rest === '\x1b' || rest === '\x1b[' || rest === '\x1bO') return holdEscape(rest);
+        if (rest[1] === '\x1b') {
+          emit(key('escape'));
+          i += 1;
+          continue;
+        }
+        if (rest.startsWith(PASTE_START)) {
+          paste = '';
+          i += PASTE_START.length;
+          continue;
+        }
+        const csi = /^\x1b\[([0-9;?]*)([@-~])/.exec(rest);
+        if (csi) {
+          emit(csiKey(csi[1], csi[2]));
+          i += csi[0].length;
+          continue;
+        }
+        const ss3 = /^\x1bO([A-Za-z])/.exec(rest);
+        if (ss3) {
+          emit(key(ARROWS[ss3[1]] || 'unknown'));
+          i += 3;
+          continue;
+        }
+        if (/^\x1b\[[0-9;?]*$/.test(rest) || PASTE_START.startsWith(rest)) {
+          return holdEscape(rest); // a longer sequence cut off by the read; wait for the rest
+        }
+        // ESC + character: an Alt chord. Reported as meta so widgets can ignore it.
+        const cp = String.fromCodePoint(rest.codePointAt(1));
+        emit(key('char', { text: cp, meta: true }));
+        i += 1 + cp.length;
+        continue;
+      }
+
+      const cp = data.codePointAt(i);
+      const ch = String.fromCodePoint(cp);
+      i += ch.length;
+      if (ch === '\r') {
+        emit(key('enter'));
+        afterCR = true;
+      } else if (ch === '\n') {
+        if (!wasCR) emit(key('enter'));
+      } else if (ch === '\t') emit(key('tab'));
+      else if (ch === '\x7f' || ch === '\b') emit(key('backspace'));
+      else if (cp < 32) emit(key(String.fromCharCode(cp + 96), { ctrl: true }));
+      else emit(key('char', { text: ch }));
+    }
+    return undefined;
+  }
+
+  // Drops timers and half-read input (the session is closing).
+  function dispose() {
+    stopEscTimer();
+    if (pasteTimer) clearTimeout(pasteTimer);
+    pasteTimer = null;
+    pending = '';
+    paste = null;
+  }
+
+  return { feed, dispose };
+}
+
+module.exports = { createKeyParser, key, PASTE_START, PASTE_END, MAX_PASTE };

package/lib/tui/launch.js

@@ -0,0 +1,19 @@
+'use strict';
+// Decides whether a run may use interactive/coloured screens. Anything that
+// asks for scripted behaviour (--json, --yes, --no-tui, TERM=dumb) or lacks a
+// terminal on both ends keeps the plain output.
+
+// `io.tui` lets a caller (tests, embedding) force the answer where the streams
+// are not real terminals; the flags above still win.
+function shouldUseTui(flags, io) {
+  if (flags.json || flags.noTui || flags.yes) return false;
+  if (io.env.TERM === 'dumb') return false;
+  if (io.tui !== undefined) return Boolean(io.tui);
+  // Raw key input is required; a stream that cannot switch to raw mode keeps the plain prompts.
+  return Boolean(io.stdin.isTTY && io.stdout.isTTY && typeof io.stdin.setRawMode === 'function');
+}
+
+// The guided install additionally steps aside for --dry-run (it prints the plan and exits).
+const shouldRunWizard = (flags, io) => shouldUseTui(flags, io) && !flags.dryRun;
+
+module.exports = { shouldUseTui, shouldRunWizard };

package/lib/tui/logo-fonts.js

@@ -0,0 +1,29 @@
+'use strict';
+// Bitmap fonts for the banner. '#' is a lit pixel. Every glyph in a font has
+// the same number of rows.
+
+// 7 rows, 1-pixel strokes.
+const SLIM = {
+  '>': ['#...', '.#..', '..#.', '...#', '..#.', '.#..', '#...'],
+  A: ['.###.', '#...#', '#...#', '#####', '#...#', '#...#', '#...#'],
+  I: ['###', '.#.', '.#.', '.#.', '.#.', '.#.', '###'],
+  '-': ['....', '....', '....', '####', '....', '....', '....'],
+  S: ['.####', '#....', '#....', '.###.', '....#', '....#', '####.'],
+  D: ['####.', '#...#', '#...#', '#...#', '#...#', '#...#', '####.'],
+  L: ['#....', '#....', '#....', '#....', '#....', '#....', '#####'],
+  C: ['.####', '#....', '#....', '#....', '#....', '#....', '.####'],
+};
+
+// 9 rows, 2-pixel strokes.
+const THICK = {
+  '>': ['##...', '###..', '.###.', '..###', '...##', '..###', '.###.', '###..', '##...'],
+  A: ['..###..', '.#####.', '##...##', '##...##', '#######', '#######', '##...##', '##...##', '##...##'],
+  I: ['######', '######', '..##..', '..##..', '..##..', '..##..', '..##..', '######', '######'],
+  '-': ['....', '....', '....', '####', '####', '....', '....', '....', '....'],
+  S: ['.#####.', '##...##', '##.....', '.####..', '..####.', '.....##', '.....##', '##...##', '.#####.'],
+  D: ['#####..', '##..##.', '##...##', '##...##', '##...##', '##...##', '##...##', '##..##.', '#####..'],
+  L: ['##....', '##....', '##....', '##....', '##....', '##....', '##....', '######', '######'],
+  C: ['.#####.', '##...##', '##.....', '##.....', '##.....', '##.....', '##.....', '##...##', '.#####.'],
+};
+
+module.exports = { SLIM, THICK };

package/lib/tui/logo.js

@@ -0,0 +1,98 @@
+'use strict';
+// Pixel-block banner: bitmap letters, drop shadow, horizontal gradient.
+// bannerFor(columns, level) picks the largest variant that fits:
+//   >= 120 columns  thick 2-pixel-stroke letters
+//   >= 100 columns  1-pixel letters, two cells per pixel
+//   >=  50 columns  1-pixel letters in half-blocks (compact)
+//   otherwise, or without colour support: one line of text
+const { colorLevel, gradientAt, shade, fg, bg, RESET } = require('./colors');
+const { SLIM, THICK } = require('./logo-fonts');
+
+const TEXT = '>AI-SDLC';
+const BLUE_PURPLE_PINK = [[71, 150, 228], [132, 122, 206], [195, 103, 127]];
+const BASIC = ['\x1b[94m', '\x1b[95m', '\x1b[91m'];
+
+// Pixel grid with 0 = empty, 1 = letter, 2 = shadow. One extra row below
+// the letters holds the shadow of the bottom stroke.
+function pixels(text, font = SLIM) {
+  const height = Object.values(font)[0].length;
+  const rows = Array.from({ length: height }, () => []);
+  [...text].forEach((ch, n) => {
+    const glyph = font[ch];
+    if (!glyph) throw new Error(`no glyph for ${ch}`);
+    for (let r = 0; r < height; r++) rows[r].push(...[...glyph[r]].map((c) => (c === '#' ? 1 : 0)), ...(n < text.length - 1 ? [0] : []));
+  });
+  const w = rows[0].length;
+  const out = [...rows, new Array(w).fill(0)].map((row) => [...row, 0]);
+  // shadow: one pixel down-right of every letter pixel, where no letter pixel already is
+  for (let r = 0; r < height; r++) for (let c = 0; c < w; c++) if (rows[r][c] && !(rows[r + 1] || [])[c + 1]) out[r + 1][c + 1] = 2;
+  return out;
+}
+
+// scale 2 -> two cells per pixel (wide); scale 1 -> half-block rows (compact).
+function renderLogo({ text = TEXT, scale = 2, level = colorLevel(), font = SLIM } = {}) {
+  const grid = pixels(text, font);
+  const w = grid[0].length;
+  const paint = (cls, x) => {
+    if (!cls) return null;
+    const base = gradientAt(BLUE_PURPLE_PINK, x / (w - 1));
+    return cls === 1 ? base : shade(base);
+  };
+  const third = (x) => BASIC[Math.min(2, Math.floor((x / w) * 3))];
+  const lines = [];
+  if (scale === 2) {
+    for (const row of grid) {
+      let s = '';
+      row.forEach((cls, x) => {
+        if (!cls) s += '  ';
+        else if (level === 3) s += `${fg(paint(cls, x))}██${RESET}`;
+        else if (level === 1) s += cls === 1 ? `${third(x)}██${RESET}` : '\x1b[2m░░\x1b[0m';
+        else s += cls === 1 ? '██' : '░░';
+      });
+      lines.push(s.replace(/\s+$/, ''));
+    }
+    return lines;
+  }
+  for (let r = 0; r < grid.length; r += 2) {
+    let s = '';
+    for (let x = 0; x < w; x++) {
+      const t = grid[r][x];
+      const b = r + 1 < grid.length ? grid[r + 1][x] : 0;
+      if (level === 3) {
+        const tc = paint(t, x);
+        const bc = paint(b, x);
+        if (!tc && !bc) s += ' ';
+        else if (tc && bc && t === b) s += `${fg(tc)}█${RESET}`;
+        else if (tc && !bc) s += `${fg(tc)}▀${RESET}`;
+        else if (!tc && bc) s += `${fg(bc)}▄${RESET}`;
+        else s += `${fg(tc)}${bg(bc)}▀${RESET}`;
+      } else {
+        const ch = t === 1 && b === 1 ? '█' : t === 1 ? '▀' : b === 1 ? '▄' : t || b ? '░' : ' ';
+        s += level === 1 && ch !== ' ' ? `${third(x)}${ch}${RESET}` : ch;
+      }
+    }
+    lines.push(s.replace(/\s+$/, ''));
+  }
+  return lines;
+}
+
+// The one-line fallback: gradient text on truecolor, bold on 16 colours, plain otherwise.
+function textBanner(level) {
+  const label = '> AI-SDLC';
+  if (level === 3) return [...label].map((ch, i) => `\x1b[1m${fg(gradientAt(BLUE_PURPLE_PINK, i / (label.length - 1)))}${ch}${RESET}`).join('');
+  return level === 1 ? `\x1b[1;94m${label}${RESET}` : label;
+}
+
+function bannerFor(columns = 80, level = colorLevel(), { unicode = true } = {}) {
+  if (!level || !unicode || columns < 50) return [textBanner(level)];
+  if (columns >= 120) return renderLogo({ font: THICK, scale: 2, level });
+  if (columns >= 100) return renderLogo({ scale: 2, level });
+  return renderLogo({ scale: 1, level });
+}
+
+module.exports = { renderLogo, bannerFor, pixels, textBanner };
+
+if (require.main === module) {
+  const cols = process.stdout.columns || 80;
+  console.log(`\n${bannerFor(process.argv.includes('--compact') ? 60 : cols, colorLevel()).join('\n')}\n`);
+}

package/lib/tui/sanitize.js

@@ -0,0 +1,27 @@
+'use strict';
+// Data from disk, from manifests or from the user must never reach the
+// terminal as control sequences. sanitize() turns control characters into
+// visible escapes; it is applied to data strings only, never to the colour
+// codes the theme adds around them.
+// Controls: C0, DEL, C1, line/paragraph separators and bidirectional overrides.
+const CONTROL = /[\x00-\x1f\x7f-\x9f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
+// Whole escape sequences (CSI, OSC, two-character) in text that was typed or pasted.
+const ESCAPE_SEQUENCE = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g;
+
+function visible(ch) {
+  const code = ch.charCodeAt(0);
+  if (ch === '\x1b') return '^[';
+  if (ch === '\n') return '\\n';
+  if (ch === '\r') return '\\r';
+  if (ch === '\t') return '\\t';
+  if (code < 0x20) return `^${String.fromCharCode(code + 64)}`;
+  if (code === 0x7f) return '^?';
+  return `\\u${code.toString(16).padStart(4, '0')}`;
+}
+
+const sanitize = (value) => String(value).replace(CONTROL, visible);
+
+// For text typed or pasted into a field: escape sequences and control characters are dropped.
+const stripControl = (value) => String(value).replace(ESCAPE_SEQUENCE, '').replace(CONTROL, '');
+
+module.exports = { sanitize, stripControl };

package/lib/tui/terminal-guards.js

@@ -0,0 +1,58 @@
+'use strict';
+// Process-level safety nets for a terminal session: whichever way the process
+// ends (exit, SIGINT, SIGTERM, an uncaught error, a dead stdout), the session's
+// restore() runs first.
+
+function createGuards({ stdout, stderr, proc, restore, isActive }) {
+  const report = (text) => {
+    try {
+      stderr.write(text);
+    } catch (_) {
+      /* nowhere left to report to */
+    }
+  };
+  const onExit = () => restore();
+  const onSigint = () => {
+    restore();
+    proc.exit(130);
+  };
+  const onSigterm = () => {
+    restore();
+    proc.exit(143);
+  };
+  const onFatal = (err) => {
+    restore();
+    report(`ai-sdlc: unexpected error: ${err && err.stack ? err.stack : err}\n`);
+    proc.exit(1);
+  };
+  // A closed pipe or a vanished terminal: restore what can be restored and leave quietly.
+  function onStdoutError(err) {
+    if (!isActive()) return;
+    restore();
+    if (!err || (err.code !== 'EPIPE' && err.code !== 'EIO')) report(`ai-sdlc: terminal error: ${err.message}\n`);
+    proc.exit(1);
+  }
+
+  return {
+    install() {
+      if (typeof stdout.on === 'function') stdout.on('error', onStdoutError);
+      proc.on('exit', onExit);
+      proc.on('SIGINT', onSigint);
+      proc.on('SIGTERM', onSigterm);
+      proc.on('uncaughtException', onFatal);
+    },
+    remove() {
+      proc.removeListener('exit', onExit);
+      proc.removeListener('SIGINT', onSigint);
+      proc.removeListener('SIGTERM', onSigterm);
+      proc.removeListener('uncaughtException', onFatal);
+      if (typeof stdout.removeListener === 'function') {
+        // A write to a dead terminal can still report its error later; keep absorbing it briefly.
+        const t = setTimeout(() => stdout.removeListener('error', onStdoutError), 250);
+        if (t.unref) t.unref();
+      }
+    },
+  };
+}
+
+module.exports = { createGuards };

package/lib/tui/terminal.js

@@ -0,0 +1,196 @@
+'use strict';
+// Terminal session: raw keyboard input, a redrawable live frame, resize
+// handling, and one cleanup path that always puts the terminal back.
+const { StringDecoder } = require('string_decoder');
+const { createKeyParser } = require('./keys');
+const { truncate, visibleWidth } = require('./text-width');
+const { createGuards } = require('./terminal-guards');
+const { BACK, Cancelled, isCancelKey } = require('./cancelled');
+
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const PASTE_ON = '\x1b[?2004h';
+const PASTE_OFF = '\x1b[?2004l';
+const CLEAR_DOWN = '\x1b[J';
+const MIN_COLUMNS = 20;
+const MIN_ROWS = 8;
+
+// A screen is { init, view(state, ctx) -> string[], onKey(state, key, ctx) -> { state } | { done } }.
+// ctx.elapsed is the time since the screen was first shown (screens use it to
+// ignore keys that were typed before the user could see them).
+function createSession({ stdin, stdout, stderr = process.stderr, theme, proc = process, escapeMs }) {
+  const decoder = new StringDecoder('utf8');
+  const queue = [];
+  let started = false;
+  let ended = false;
+  let handler = null;
+  let screenStart = Date.now();
+  let live = null; // array of lines or (ctx) => lines, redrawn on resize
+  let widths = []; // visible widths of the lines on screen
+  let drawn = { cols: 0, rows: 0 };
+
+  const columns = () => (stdout.columns > 0 ? stdout.columns : 80);
+  const rows = () => (stdout.rows > 0 ? stdout.rows : 24);
+  const tooSmall = () => columns() < MIN_COLUMNS || rows() < MIN_ROWS;
+  const ctx = () => ({ theme, width: Math.max(1, columns() - 1), rows: rows(), columns: columns(), elapsed: Date.now() - screenStart });
+
+  // Rows the current frame occupies if the terminal now has `cols` columns (lines may have re-wrapped).
+  const occupied = (cols) => widths.reduce((n, w) => n + Math.max(1, Math.ceil(w / cols)), 0);
+
+  function erase() {
+    if (!widths.length) return '';
+    const up = occupied(columns()) - 1;
+    return `${up > 0 ? `\x1b[${up}A` : ''}\r${CLEAR_DOWN}`;
+  }
+
+  const fit = (lines) => lines.map((l) => truncate(l, Math.max(1, columns() - 1), theme.sym.ellipsis));
+
+  function draw(source) {
+    if (!started) return;
+    live = source;
+    let shown;
+    if (tooSmall()) shown = fit([`Window too small: enlarge to ${MIN_COLUMNS}x${MIN_ROWS} (Esc cancels)`]);
+    else shown = fit((typeof source === 'function' ? source(ctx()) : source).slice(0, Math.max(3, rows() - 1)));
+    stdout.write(`${erase()}${shown.join('\n')}`);
+    widths = shown.map(visibleWidth);
+    drawn = { cols: columns(), rows: rows() };
+  }
+
+  // Replaces the live frame with permanent output (it stays in the scrollback).
+  function commit(lines) {
+    if (!started) return;
+    const out = fit(lines);
+    stdout.write(`${erase()}${out.join('\n')}${out.length ? '\n' : ''}`);
+    widths = [];
+    live = null;
+  }
+
+  const clear = () => commit([]);
+
+  function pump() {
+    while (handler && queue.length) handler(queue.shift());
+  }
+  const parser = createKeyParser((k) => {
+    queue.push(k);
+    pump();
+  }, escapeMs === undefined ? {} : { escapeMs });
+  const onData = (chunk) => parser.feed(typeof chunk === 'string' ? chunk : decoder.write(chunk));
+  const onEnd = () => {
+    ended = true;
+    if (handler) handler({ name: 'eof' });
+  };
+  const onResize = () => {
+    if (live && (drawn.cols !== columns() || drawn.rows !== rows())) draw(live);
+  };
+
+  // The single restore path: exit, signals, fatal errors and close() all land here.
+  const guards = createGuards({ stdout, stderr, proc, restore: () => restore(), isActive: () => started });
+  function restore() {
+    if (!started) return;
+    started = false;
+    parser.dispose();
+    try {
+      stdout.write(`${PASTE_OFF}${SHOW_CURSOR}${widths.length ? '\r\n' : ''}`);
+    } catch (_) {
+      /* output already gone */
+    }
+    try {
+      if (typeof stdin.setRawMode === 'function') stdin.setRawMode(false);
+    } catch (_) {
+      /* not a terminal any more */
+    }
+    stdin.removeListener('data', onData);
+    stdin.removeListener('end', onEnd);
+    stdin.removeListener('close', onEnd);
+    if (typeof stdout.removeListener === 'function') stdout.removeListener('resize', onResize);
+    guards.remove();
+    if (typeof stdin.pause === 'function') stdin.pause();
+    widths = [];
+    live = null;
+  }
+  function start() {
+    if (started) return;
+    started = true;
+    if (typeof stdin.setRawMode === 'function') stdin.setRawMode(true);
+    stdin.on('data', onData);
+    stdin.on('end', onEnd);
+    stdin.on('close', onEnd);
+    if (typeof stdout.on === 'function') {
+      stdout.on('resize', onResize);
+    }
+    guards.install();
+    stdin.resume();
+    stdout.write(`${HIDE_CURSOR}${PASTE_ON}`);
+  }
+
+  // Shows the screen and resolves with whatever its onKey returns as `done`.
+  // Ctrl-C and closed input reject with Cancelled. Keys typed before the screen
+  // existed (Enter pressed during a spinner, say) are dropped, except Ctrl-C.
+  function run(screen) {
+    return new Promise((resolve, reject) => {
+      const stale = queue.splice(0).filter(isCancelKey);
+      queue.push(...stale);
+      if (ended) return reject(new Cancelled('eof'));
+      let state = screen.init;
+      screenStart = Date.now();
+      const finish = (fn, value) => {
+        handler = null;
+        fn(value);
+      };
+      handler = (k) => {
+        if (k.name === 'eof') return finish(reject, new Cancelled('eof'));
+        if (isCancelKey(k)) return finish(reject, new Cancelled('interrupt'));
+        let out;
+        try {
+          out = screen.onKey(state, k, ctx());
+        } catch (err) {
+          return finish(reject, err);
+        }
+        if (out && out.done !== undefined) return finish(resolve, out.done);
+        if (out && out.state) state = out.state;
+        draw((c) => screen.view(state, c));
+        return undefined;
+      };
+      draw((c) => screen.view(state, c));
+      pump();
+      return undefined;
+    });
+  }
+
+  // While background work runs and no screen is active, Ctrl-C, Esc or closed input cancel it
+  // (onCancel(reason)); other keys are dropped. Returns a function that stops watching.
+  function watchCancel(onCancel) {
+    const typedAhead = queue.splice(0);
+    let fired = false;
+    const fire = (reason) => {
+      if (!fired) onCancel(reason);
+      fired = true;
+    };
+    const mine = (k) => {
+      if (k.name === 'eof') fire('eof');
+      else if (isCancelKey(k)) fire('interrupt');
+      else if (k.name === 'escape') fire('escape');
+    };
+    handler = mine;
+    if (ended) fire('eof');
+    else if (typedAhead.some(isCancelKey)) fire('interrupt');
+    return () => {
+      if (handler === mine) handler = null;
+    };
+  }
+
+  return { start, close: restore, draw, commit, clear, run, watchCancel, ctx, theme, get columns() { return columns(); }, get rows() { return rows(); } };
+}
+
+// Opens a session, runs fn(session) and always restores the terminal.
+async function withSession(opts, fn) {
+  const session = createSession(opts);
+  session.start();
+  try {
+    return await fn(session);
+  } finally {
+    session.close();
+  }
+}
+
+module.exports = { createSession, withSession, Cancelled, BACK, HIDE_CURSOR, SHOW_CURSOR, PASTE_ON, PASTE_OFF, MIN_COLUMNS, MIN_ROWS };