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

package/lib/tui/text-width.js

@@ -0,0 +1,122 @@
+'use strict';
+// Width helpers for strings that may carry ANSI sequences: display width,
+// truncation that never cuts inside an escape sequence or a character cluster.
+
+// CSI (colours, cursor), OSC (titles, links; BEL or ST terminated), and two-character escapes.
+const ESC_SEQ = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g;
+const RESET = '\x1b[0m';
+
+// East Asian wide / fullwidth and emoji blocks: two terminal cells each.
+const WIDE = [
+  [0x1100, 0x115f], [0x2e80, 0x303e], [0x3041, 0x33ff], [0x3400, 0x4dbf], [0x4e00, 0x9fff],
+  [0xa000, 0xa4cf], [0xac00, 0xd7a3], [0xf900, 0xfaff], [0xfe30, 0xfe6f], [0xff00, 0xff60],
+  [0xffe0, 0xffe6], [0x1f300, 0x1f64f], [0x1f680, 0x1f6ff], [0x1f900, 0x1f9ff], [0x1fa70, 0x1faff], [0x20000, 0x3fffd],
+  // Emoji_Presentation characters among the symbol blocks (the check mark, warning and
+  // pointer glyphs used by the UI are text-presentation and stay one cell wide).
+  [0x231a, 0x231b], [0x23e9, 0x23ec], [0x23f0, 0x23f0], [0x23f3, 0x23f3], [0x25fd, 0x25fe], [0x2614, 0x2615],
+  [0x2648, 0x2653], [0x267f, 0x267f], [0x2693, 0x2693], [0x26a1, 0x26a1], [0x26aa, 0x26ab], [0x26bd, 0x26be],
+  [0x26c4, 0x26c5], [0x26ce, 0x26ce], [0x26d4, 0x26d4], [0x26ea, 0x26ea], [0x26f2, 0x26f3], [0x26f5, 0x26f5],
+  [0x26fa, 0x26fa], [0x26fd, 0x26fd], [0x2705, 0x2705], [0x270a, 0x270b], [0x2728, 0x2728], [0x274c, 0x274c],
+  [0x274e, 0x274e], [0x2753, 0x2755], [0x2757, 0x2757], [0x2795, 0x2797], [0x27b0, 0x27b0], [0x27bf, 0x27bf],
+  [0x2b1b, 0x2b1c], [0x2b50, 0x2b50], [0x2b55, 0x2b55],
+];
+
+const stripAnsi = (s) => String(s).replace(ESC_SEQ, '');
+
+function charWidth(cp) {
+  if (cp < 32 || (cp >= 0x7f && cp < 0xa0)) return 0;
+  // combining marks, zero-width space/joiners, variation selectors
+  if ((cp >= 0x300 && cp <= 0x36f) || (cp >= 0x200b && cp <= 0x200f) || (cp >= 0xfe00 && cp <= 0xfe0f) || cp === 0x20e3) return 0;
+  for (const [lo, hi] of WIDE) if (cp >= lo && cp <= hi) return 2;
+  return 1;
+}
+
+const segmenter = typeof Intl !== 'undefined' && Intl.Segmenter ? new Intl.Segmenter(undefined, { granularity: 'grapheme' }) : null;
+const SIMPLE = /^[\x20-\x7e]*$/;
+
+// Characters a user sees as one: letter plus combining marks, emoji with skin tone or joiners, flags.
+function graphemes(text) {
+  const str = String(text);
+  if (SIMPLE.test(str)) return str.split('');
+  return segmenter ? Array.from(segmenter.segment(str), (s) => s.segment) : Array.from(str);
+}
+
+// Cells a cluster occupies: the widest member, and emoji sequences / flags are always two.
+function clusterWidth(cluster) {
+  const cps = Array.from(cluster, (c) => c.codePointAt(0));
+  if (cps.length === 1) return charWidth(cps[0]);
+  if (cps.includes(0xfe0f) || cps.includes(0x200d)) return 2;
+  if (cps.length === 2 && cps.every((c) => c >= 0x1f1e6 && c <= 0x1f1ff)) return 2;
+  return Math.max(...cps.map(charWidth));
+}
+
+// Splits into { esc: true, s } sequences and { s, w } clusters.
+function* parts(str) {
+  let last = 0;
+  const text = (chunk) => graphemes(chunk).map((g) => ({ s: g, w: clusterWidth(g) }));
+  for (const m of str.matchAll(ESC_SEQ)) {
+    if (m.index > last) yield* text(str.slice(last, m.index));
+    yield { esc: true, s: m[0], w: 0 };
+    last = m.index + m[0].length;
+  }
+  if (last < str.length) yield* text(str.slice(last));
+}
+
+function visibleWidth(s) {
+  const str = String(s);
+  if (SIMPLE.test(str)) return str.length;
+  let w = 0;
+  for (const p of parts(str)) w += p.w;
+  return w;
+}
+
+// Cuts to `max` cells (ellipsis included), keeping escape sequences whole and
+// closing any open styling.
+function truncate(s, max, ellipsis = '…') {
+  const str = String(s);
+  if (visibleWidth(str) <= max) return str;
+  const ew = visibleWidth(ellipsis);
+  if (max <= ew) return max > 0 ? ellipsis.slice(0, max) : '';
+  const budget = max - ew;
+  let out = '';
+  let used = 0;
+  let styled = false;
+  for (const p of parts(str)) {
+    if (p.esc) {
+      out += p.s;
+      styled = true;
+    } else if (used + p.w > budget) break;
+    else {
+      out += p.s;
+      used += p.w;
+    }
+  }
+  return `${out}${styled ? RESET : ''}${ellipsis}`;
+}
+
+// For plain strings such as paths: keeps the start and the end, drops the middle.
+function truncateMiddle(s, max, ellipsis = '…') {
+  const str = String(s);
+  if (visibleWidth(str) <= max) return str;
+  const ew = visibleWidth(ellipsis);
+  if (max <= ew) return max > 0 ? ellipsis.slice(0, max) : '';
+  const budget = max - ew;
+  const take = (list, room) => {
+    const out = [];
+    let used = 0;
+    for (const g of list) {
+      const w = clusterWidth(g);
+      if (used + w > room) break;
+      out.push(g);
+      used += w;
+    }
+    return out;
+  };
+  const all = graphemes(str);
+  const tailRoom = Math.ceil(budget * 0.65);
+  return `${take(all, budget - tailRoom).join('')}${ellipsis}${take([...all].reverse(), tailRoom).reverse().join('')}`;
+}
+
+const padEnd = (s, width) => `${s}${' '.repeat(Math.max(0, width - visibleWidth(s)))}`;
+
+module.exports = { stripAnsi, visibleWidth, truncate, truncateMiddle, padEnd, charWidth, clusterWidth, graphemes, ESC_SEQ, RESET };

package/lib/tui/theme.js

@@ -0,0 +1,84 @@
+'use strict';
+// Palette and symbols. One object answers every "how do I draw this" question:
+// colour level (0 none, 1 sixteen colours, 3 truecolor), whether text attributes
+// (dim, bold, inverse) are safe, and unicode versus ASCII symbols.
+const { colorLevel, gradientAt, fg, RESET } = require('./colors');
+
+const STOPS = [[71, 150, 228], [132, 122, 206], [195, 103, 127]];
+// role -> [truecolor rgb | null, sixteen-colour code | null, attribute code | null]
+const ROLES = {
+  accent: [[71, 150, 228], '94'],
+  purple: [[132, 122, 206], '95'],
+  pink: [[195, 103, 127], '91'],
+  ok: [[90, 200, 130], '32'],
+  warn: [[230, 180, 80], '33'],
+  err: [[230, 95, 95], '31'],
+  dim: [null, null, '2'],
+  bold: [null, null, '1'],
+};
+
+const UNICODE = {
+  ok: '✔', warn: '⚠', err: '✖', info: '•', dot: '·', pointer: '❯', bullet: '•', ellipsis: '…', arrow: '→',
+  up: '↑', down: '↓', bar: ['█', '░'], spinner: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+  box: { tl: '╭', tr: '╮', bl: '╰', br: '╯', h: '─', v: '│' },
+};
+const ASCII = {
+  ok: '+', warn: '!', err: 'x', info: '-', dot: '|', pointer: '>', bullet: '*', ellipsis: '...', arrow: '->',
+  up: '^', down: 'v', bar: ['#', '-'], spinner: ['|', '/', '-', '\\'],
+  box: { tl: '+', tr: '+', bl: '+', br: '+', h: '-', v: '|' },
+};
+
+// Box-drawing and block glyphs need a UTF-8 locale; TERM=linux/dumb never get them.
+function detectUnicode(env, platform = process.platform) {
+  if (env.TERM === 'linux' || env.TERM === 'dumb') return false;
+  const locale = env.LC_ALL || env.LC_CTYPE || env.LANG;
+  if (locale) return /utf-?8/i.test(locale);
+  if (platform === 'win32') return Boolean(env.WT_SESSION || env.TERM_PROGRAM || env.ConEmuANSI);
+  return true;
+}
+
+function createTheme({ env = process.env, stream = process.stdout, level, unicode, attrs, platform } = {}) {
+  const lvl = level !== undefined ? level : colorLevel(env, stream);
+  const uni = unicode !== undefined ? unicode : detectUnicode(env, platform);
+  const hasAttrs = attrs !== undefined ? attrs : lvl > 0 || (Boolean(stream && stream.isTTY) && env.TERM !== 'dumb');
+
+  const open = (role) => {
+    const def = ROLES[role];
+    if (!def) return '';
+    if (def[2]) return hasAttrs ? `\x1b[${def[2]}m` : '';
+    if (lvl === 3) return fg(def[0]);
+    return lvl === 1 ? `\x1b[${def[1]}m` : '';
+  };
+
+  // paint('ok bold', 'text'): roles joined, closed with a full reset.
+  const paint = (roles, text) => {
+    const prefix = String(roles).split(' ').map(open).join('');
+    return prefix ? `${prefix}${text}${RESET}` : String(text);
+  };
+
+  // Blue to purple to pink across the visible characters of `text`.
+  const gradient = (text, from = 0, to = 1) => {
+    if (lvl === 0) return String(text);
+    const chars = [...String(text)];
+    return chars.map((ch, i) => {
+      if (ch === ' ') return ch;
+      const t = chars.length < 2 ? from : from + ((to - from) * i) / (chars.length - 1);
+      return lvl === 3 ? `${fg(gradientAt(STOPS, t))}${ch}${RESET}` : paint(t < 0.34 ? 'accent' : t < 0.67 ? 'purple' : 'pink', ch);
+    }).join('');
+  };
+
+  return {
+    level: lvl,
+    unicode: uni,
+    attrs: hasAttrs,
+    sym: uni ? UNICODE : ASCII,
+    box: (uni ? UNICODE : ASCII).box,
+    paint,
+    gradient,
+    // Text caret: inverse video where attributes work, nothing extra otherwise.
+    caret: (ch) => (hasAttrs ? `\x1b[7m${ch || ' '}\x1b[27m` : ch || ' '),
+    tone: (status) => ({ ok: 'ok', warn: 'warn', fail: 'err', err: 'err', info: 'dim' }[status] || ''),
+  };
+}
+
+module.exports = { createTheme, detectUnicode };

package/lib/tui/widgets/confirm.js

@@ -0,0 +1,56 @@
+'use strict';
+// Confirmation screen: a titled body that can scroll, Enter/y to proceed,
+// Esc/n to step back. Optional `d` toggles a detailed body.
+const { BACK } = require('../terminal');
+const { renderBox } = require('./panel');
+
+// body(state, ctx) returns the lines to show; state.expanded tells whether details are on.
+// guardMs: Enter / y arriving sooner than this after the screen first appeared are
+// ignored, so keys typed before the user could read it cannot confirm.
+function createConfirm({ title, body, confirmLabel = 'Install', detailsToggle = false, guardMs = 150 }) {
+  const windowSize = (ctx) => Math.max(5, ctx.rows - 7);
+
+  function view(state, ctx) {
+    const { theme, width } = ctx;
+    const all = body(state, ctx);
+    const size = windowSize(ctx);
+    const top = Math.max(0, Math.min(state.scroll, Math.max(0, all.length - size)));
+    const rows = all.slice(top, top + size);
+    if (top > 0) rows[0] = theme.paint('dim', `${theme.sym.up} ${top} more above`);
+    const below = all.length - (top + size);
+    if (below > 0) rows[rows.length - 1] = theme.paint('dim', `${theme.sym.down} ${below} more below`);
+    const keys = [`Enter ${confirmLabel.toLowerCase()}`];
+    if (detailsToggle) keys.push(`d ${state.expanded ? 'hide' : 'show'} full list`);
+    if (all.length > size) keys.push(`${theme.sym.up}${theme.sym.down} scroll`);
+    keys.push('Esc back');
+    return [...renderBox({ theme, width, title, rows }), theme.paint('dim', `  ${keys.join(` ${theme.sym.dot} `)}`)];
+  }
+
+  function onKey(state, key, ctx) {
+    const total = body(state, ctx).length;
+    const size = windowSize(ctx);
+    const scroll = (n) => ({ state: { ...state, scroll: Math.max(0, Math.min(n, Math.max(0, total - size))) } });
+    const tooSoon = ctx.elapsed !== undefined && ctx.elapsed < guardMs;
+    switch (key.name) {
+      case 'enter': return tooSoon ? { state } : { done: true };
+      case 'escape': return { done: BACK };
+      case 'up': return scroll(state.scroll - 1);
+      case 'down': return scroll(state.scroll + 1);
+      case 'pageup': return scroll(state.scroll - size);
+      case 'pagedown': return scroll(state.scroll + size);
+      case 'home': return scroll(0);
+      case 'end': return scroll(total);
+      default: break;
+    }
+    if (key.name === 'char' && !key.meta) {
+      if (key.text === 'y' || key.text === 'Y') return tooSoon ? { state } : { done: true };
+      if (key.text === 'n' || key.text === 'N') return { done: BACK };
+      if (detailsToggle && (key.text === 'd' || key.text === 'D')) return { state: { ...state, expanded: !state.expanded, scroll: 0 } };
+    }
+    return { state };
+  }
+
+  return { init: { expanded: false, scroll: 0 }, view, onKey };
+}
+
+module.exports = { createConfirm };

package/lib/tui/widgets/input-box.js

@@ -0,0 +1,88 @@
+'use strict';
+// Single-line text editing (pure) and the rounded input box that shows it.
+const { clusterWidth, graphemes } = require('../text-width');
+const { sanitize, stripControl } = require('../sanitize');
+const { renderBox } = require('./panel');
+
+const MAX_LENGTH = 4096; // characters (grapheme clusters) a field accepts
+
+const cleanPaste = (text) => stripControl(text);
+const endOf = (value) => graphemes(value).length;
+
+// state: { value, cursor } with cursor counted in characters (clusters: an emoji
+// with a skin tone or a letter with accents is one character for the caret and Backspace).
+// Returns the new state, or null when the key is not a text-editing key.
+function editText(state, key) {
+  const chars = graphemes(state.value);
+  const at = Math.min(state.cursor, chars.length);
+  const make = (arr, cursor) => ({ ...state, value: arr.join(''), cursor });
+  const insert = (text) => {
+    const add = graphemes(text).slice(0, Math.max(0, MAX_LENGTH - chars.length));
+    const before = [...chars.slice(0, at), ...add];
+    return { ...state, value: [...before, ...chars.slice(at)].join(''), cursor: endOf(before.join('')) };
+  };
+
+  if (key.name === 'char' && !key.ctrl && !key.meta) return stripControl(key.text) === key.text ? insert(key.text) : make(chars, at);
+  if (key.name === 'paste') return insert(cleanPaste(key.text));
+  if (key.ctrl) {
+    if (key.name === 'a') return make(chars, 0);
+    if (key.name === 'e') return make(chars, chars.length);
+    if (key.name === 'u') return make(chars.slice(at), 0);
+    if (key.name === 'w') {
+      let start = at;
+      while (start > 0 && chars[start - 1] === ' ') start -= 1;
+      while (start > 0 && chars[start - 1] !== ' ') start -= 1;
+      return make([...chars.slice(0, start), ...chars.slice(at)], start);
+    }
+    return null;
+  }
+  switch (key.name) {
+    case 'backspace': return at > 0 ? make([...chars.slice(0, at - 1), ...chars.slice(at)], at - 1) : make(chars, at);
+    case 'delete': return make([...chars.slice(0, at), ...chars.slice(at + 1)], at);
+    case 'left': return make(chars, Math.max(0, at - 1));
+    case 'right': return make(chars, Math.min(chars.length, at + 1));
+    case 'home': return make(chars, 0);
+    case 'end': return make(chars, chars.length);
+    default: return null;
+  }
+}
+
+// The slice of `chars` that fits `room` cells and keeps the caret visible.
+// Walks outward from the caret, so the cost depends on the window, not the text length.
+function windowAround(chars, cursor, room) {
+  let start = cursor;
+  let used = 0;
+  while (start > 0) {
+    const w = clusterWidth(chars[start - 1]);
+    if (used + w > room - 1) break;
+    used += w;
+    start -= 1;
+  }
+  let end = cursor;
+  while (end < chars.length) {
+    const w = clusterWidth(chars[end]);
+    if (used + w > room) break;
+    used += w;
+    end += 1;
+  }
+  return { start, end };
+}
+
+// Returns the box as lines.
+function renderInputBox({ theme, width, state, placeholder = '', title = '' }) {
+  const prompt = `${theme.paint('accent bold', theme.sym.pointer)} `;
+  const inner = Math.max(12, Math.min(width, 100)) - 4;
+  const room = inner - 2;
+  const chars = graphemes(state.value);
+  const cursor = Math.min(state.cursor, chars.length);
+  let body;
+  if (!chars.length) body = `${theme.caret(' ')}${theme.paint('dim', sanitize(placeholder))}`;
+  else {
+    const { start, end } = windowAround(chars, cursor, room);
+    const under = cursor < end ? sanitize(chars[cursor]) : ' ';
+    body = `${sanitize(chars.slice(start, cursor).join(''))}${theme.caret(under)}${sanitize(chars.slice(Math.min(cursor + 1, end), end).join(''))}`;
+  }
+  return renderBox({ theme, width, title, rows: [`${prompt}${body}`] });
+}
+
+module.exports = { editText, renderInputBox, cleanPaste, endOf, MAX_LENGTH };

package/lib/tui/widgets/panel.js

@@ -0,0 +1,31 @@
+'use strict';
+// Bordered box with an optional title in the top edge. Used by the input box,
+// the review screen and the result panels.
+const { truncate, padEnd, visibleWidth } = require('../text-width');
+
+const MAX_BOX = 100;
+
+// tone: '' = gradient border, otherwise a theme role such as 'ok' or 'warn'.
+function renderBox({ theme, width, rows, title = '', tone = '' }) {
+  const w = Math.max(12, Math.min(width, MAX_BOX));
+  const inner = w - 4;
+  const b = theme.box;
+  const fill = w - 2;
+  const edge = (text, from, to) => (tone ? theme.paint(tone, text) : theme.gradient(text, from, to));
+  let top;
+  if (title) {
+    const label = ` ${truncate(title, fill - 4)} `;
+    top = `${b.tl}${b.h}${label}${b.h.repeat(Math.max(0, fill - 1 - visibleWidth(label)))}${b.tr}`;
+  } else top = `${b.tl}${b.h.repeat(fill)}${b.tr}`;
+  const left = edge(b.v, 0, 0);
+  const right = edge(b.v, 1, 1);
+  return [
+    edge(top, 0, 1),
+    ...rows.map((row) => `${left} ${padEnd(truncate(row, inner, theme.sym.ellipsis), inner)} ${right}`),
+    edge(`${b.bl}${b.h.repeat(fill)}${b.br}`, 0, 1),
+  ];
+}
+
+const renderPanel = ({ theme, width, title, lines, tone }) => renderBox({ theme, width, rows: lines, title, tone });
+
+module.exports = { renderBox, renderPanel, MAX_BOX };

package/lib/tui/widgets/path-input.js

@@ -0,0 +1,110 @@
+'use strict';
+// Path entry with Tab completion over directories. `validate(text)` returns the
+// accepted value or throws an Error whose message is shown under the box.
+const fs = require('fs');
+const path = require('path');
+const { BACK } = require('../terminal');
+const { editText, renderInputBox, endOf } = require('./input-box');
+const { sanitize, stripControl } = require('../sanitize');
+const { expandHome } = require('../../project-picker');
+
+const SEP = path.sep === '\\' ? '\\' : '/';
+const MAX_SHOWN = 6;
+
+function commonPrefix(list) {
+  return list.reduce((acc, s) => {
+    let n = 0;
+    while (n < acc.length && n < s.length && acc[n] === s[n]) n += 1;
+    return acc.slice(0, n);
+  });
+}
+
+// Directories that complete `value`, as full replacement texts ending in a separator.
+function completions(value, { cwd, home }) {
+  if (value === '~') return [`~${SEP}`];
+  const cut = Math.max(value.lastIndexOf('/'), path.sep === '\\' ? value.lastIndexOf('\\') : -1);
+  const dirPart = value.slice(0, cut + 1);
+  const prefix = value.slice(cut + 1);
+  const base = path.resolve(cwd, expandHome(dirPart || '.', home));
+  let entries;
+  try {
+    entries = fs.readdirSync(base, { withFileTypes: true });
+  } catch (_) {
+    return [];
+  }
+  const isDir = (e) => {
+    if (e.isDirectory()) return true;
+    if (!e.isSymbolicLink()) return false;
+    try {
+      return fs.statSync(path.join(base, e.name)).isDirectory();
+    } catch (_) {
+      return false;
+    }
+  };
+  return entries
+    .filter((e) => stripControl(e.name) === e.name && isDir(e) && e.name.startsWith(prefix) && (prefix.startsWith('.') || !e.name.startsWith('.')))
+    .map((e) => `${dirPart}${e.name}${SEP}`)
+    .sort();
+}
+
+function applyTab(state, direction, opts) {
+  const comp = state.comp && state.comp.value === state.value ? state.comp : null;
+  let matches;
+  let index;
+  if (comp) {
+    matches = comp.matches;
+    index = comp.index < 0 ? (direction > 0 ? 0 : matches.length - 1) : (comp.index + direction + matches.length) % matches.length;
+  } else {
+    matches = completions(state.value, opts);
+    if (!matches.length) return { ...state, comp: null, error: '', note: 'no matching folders' };
+    if (matches.length === 1) return { ...state, value: matches[0], cursor: endOf(matches[0]), comp: null, error: '', note: '' };
+    const common = commonPrefix(matches);
+    if (common.length > state.value.length) {
+      return { ...state, value: common, cursor: endOf(common), comp: { matches, index: -1, value: common }, error: '', note: '' };
+    }
+    index = direction > 0 ? 0 : matches.length - 1;
+  }
+  const value = matches[index];
+  return { ...state, value, cursor: endOf(value), comp: { matches, index, value }, error: '', note: '' };
+}
+
+function createPathInput({ title = 'Project path', cwd, home, validate, initial = '' }) {
+  const opts = { cwd, home };
+
+  function view(state, ctx) {
+    const { theme, width } = ctx;
+    const lines = [theme.paint('bold', `  ${title}`), ...renderInputBox({ theme, width, state, placeholder: '~/projects/my-app' })];
+    if (state.error) lines.push(`  ${theme.paint('err', `${theme.sym.err} ${sanitize(state.error)}`)}`);
+    else if (state.note) lines.push(`  ${theme.paint('dim', state.note)}`);
+    if (state.comp) {
+      const { matches, index } = state.comp;
+      const from = Math.max(0, Math.min(index, matches.length - MAX_SHOWN));
+      matches.slice(from, from + MAX_SHOWN).forEach((m, n) => {
+        const on = from + n === index;
+        lines.push(`  ${on ? theme.paint('accent bold', theme.sym.pointer) : ' '} ${on ? theme.paint('accent', sanitize(m)) : theme.paint('dim', sanitize(m))}`);
+      });
+      if (matches.length > MAX_SHOWN) lines.push(theme.paint('dim', `    ${matches.length} matches`));
+    }
+    lines.push(theme.paint('dim', `  ${['Enter confirm', 'Tab complete', 'Shift-Tab previous', 'Esc back'].join(` ${theme.sym.dot} `)}`));
+    return lines;
+  }
+
+  function onKey(state, key) {
+    if (key.name === 'tab') return { state: applyTab(state, key.shift ? -1 : 1, opts) };
+    if (key.name === 'enter') {
+      if (!state.value.trim()) return { state: { ...state, error: 'type or paste a folder path' } };
+      try {
+        return { done: validate(state.value) };
+      } catch (err) {
+        return { state: { ...state, error: err.message, comp: null } };
+      }
+    }
+    if (key.name === 'escape') return state.comp ? { state: { ...state, comp: null } } : { done: BACK };
+    const next = editText(state, key);
+    return { state: next ? { ...next, error: '', note: '', comp: null } : state };
+  }
+
+  return { init: { value: stripControl(initial), cursor: endOf(stripControl(initial)), error: '', note: '', comp: null }, view, onKey };
+}
+
+module.exports = { createPathInput, completions };

package/lib/tui/widgets/progress-bar.js

@@ -0,0 +1,17 @@
+'use strict';
+// One-line progress bar: [#####-----]  45%  current step
+const { truncate } = require('../text-width');
+
+function renderProgress({ theme, width, done, total, label = '' }) {
+  const ratio = total > 0 ? Math.min(1, Math.max(0, done / total)) : 1;
+  const barWidth = Math.max(10, Math.min(40, width - 24));
+  const filled = Math.round(barWidth * ratio);
+  const [full, empty] = theme.sym.bar;
+  const bar = theme.paint('accent', full.repeat(filled)) + theme.paint('dim', empty.repeat(barWidth - filled));
+  const pct = `${String(Math.round(ratio * 100)).padStart(3)}%`;
+  const head = `  ${bar} ${pct}  `;
+  const room = Math.max(0, width - barWidth - 9);
+  return `${head}${truncate(label, room, theme.sym.ellipsis)}`;
+}
+
+module.exports = { renderProgress };

package/lib/tui/widgets/select-list.js

@@ -0,0 +1,89 @@
+'use strict';
+// Filterable list under an input box. Items: { label, hint, badge, tone, value, sticky, hotkey }.
+// Sticky items stay visible whatever the filter says (e.g. "Enter a path...").
+const { BACK } = require('../terminal');
+const { editText, renderInputBox, endOf } = require('./input-box');
+const { sanitize } = require('../sanitize');
+const { truncate, truncateMiddle, padEnd, visibleWidth } = require('../text-width');
+
+function filterItems(items, query) {
+  const terms = String(query).toLowerCase().split(/\s+/).filter(Boolean);
+  if (!terms.length) return items;
+  return items.filter((it) => it.sticky || terms.every((t) => `${it.label} ${it.hint || ''}`.toLowerCase().includes(t)));
+}
+
+const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));
+
+function createSelectList({ title, items, placeholder = 'Type to filter', maxVisible = 8, filterable = true, notice = '', footer = '' }) {
+  const visibleFor = (state) => filterItems(items, state.value);
+
+  // Keeps the cursor inside the window and the window inside the list.
+  const settle = (state, count) => {
+    const index = clamp(state.index, 0, Math.max(0, count - 1));
+    let top = clamp(state.top, 0, Math.max(0, count - maxVisible));
+    if (index < top) top = index;
+    if (index >= top + maxVisible) top = index - maxVisible + 1;
+    return { ...state, index, top };
+  };
+
+  function view(state, ctx) {
+    const { theme, width } = ctx;
+    const list = visibleFor(state);
+    const s = settle(state, list.length);
+    const lines = [theme.paint('bold', `  ${sanitize(title)}`)];
+    if (notice) lines.push(`  ${theme.paint('warn', `${theme.sym.warn} ${sanitize(notice)}`)}`);
+    if (filterable) lines.push(...renderInputBox({ theme, width, state, placeholder }));
+    else lines.push('');
+    const shown = list.slice(s.top, s.top + maxVisible).map((it) => ({ ...it, label: sanitize(it.label), hint: sanitize(it.hint || ''), badge: sanitize(it.badge || '') }));
+    const labelW = Math.min(30, Math.max(0, ...shown.map((it) => visibleWidth(it.label))));
+    const badgeW = Math.max(0, ...shown.map((it) => visibleWidth(it.badge || '')));
+    if (!list.some((it) => !it.sticky)) lines.push(`    ${theme.paint('dim', 'No matches')}`);
+    if (s.top > 0) lines.push(`    ${theme.paint('dim', `${theme.sym.up} ${s.top} more`)}`);
+    shown.forEach((it, n) => {
+      const selected = s.top + n === s.index;
+      const label = padEnd(truncate(it.label, labelW, theme.sym.ellipsis), labelW);
+      const hintRoom = width - 4 - labelW - (badgeW ? badgeW + 2 : 0) - 2;
+      const hint = it.hint && hintRoom >= 8 ? `  ${theme.paint('dim', padEnd(truncateMiddle(it.hint, hintRoom, theme.sym.ellipsis), hintRoom))}` : '';
+      const badge = it.badge ? `  ${theme.paint(it.tone || 'dim', padEnd(it.badge, badgeW))}` : '';
+      const ptr = selected ? theme.paint('accent bold', theme.sym.pointer) : ' ';
+      lines.push(`  ${ptr} ${selected ? theme.paint('accent bold', label) : label}${hint}${badge}`);
+    });
+    const below = list.length - (s.top + shown.length);
+    if (below > 0) lines.push(`    ${theme.paint('dim', `${theme.sym.down} ${below} more`)}`);
+    const dot = theme.sym.dot;
+    const hotkeys = filterable ? '' : ` ${dot} 1-9 jump`;
+    lines.push(theme.paint('dim', `  Enter select ${dot} ${theme.sym.up}${theme.sym.down} move${hotkeys} ${dot} Esc ${state.value ? 'clear filter' : 'back'}${footer ? ` ${dot} ${footer}` : ''}`));
+    return lines;
+  }
+
+  function onKey(state, key) {
+    const list = visibleFor(state);
+    const move = (index) => ({ state: settle({ ...state, index }, list.length) });
+    switch (key.name) {
+      case 'up': return move(state.index <= 0 ? list.length - 1 : state.index - 1);
+      case 'down': return move(state.index >= list.length - 1 ? 0 : state.index + 1);
+      case 'home': return move(0);
+      case 'end': return move(list.length - 1);
+      case 'pageup': return move(state.index - maxVisible);
+      case 'pagedown': return move(state.index + maxVisible);
+      case 'enter': {
+        const item = list[clamp(state.index, 0, list.length - 1)];
+        return item ? { done: { item } } : { state };
+      }
+      case 'escape': return state.value ? { state: { ...state, value: '', cursor: 0, index: 0, top: 0 } } : { done: BACK };
+      case 'tab': case 'left': case 'right': return { state };
+      default: break;
+    }
+    if (!filterable) {
+      const hit = list.find((it) => it.hotkey && key.name === 'char' && key.text === it.hotkey);
+      return hit ? { done: { item: hit } } : { state };
+    }
+    const next = editText({ ...state, cursor: endOf(state.value) }, key);
+    if (!next) return { state };
+    return { state: settle({ ...next, cursor: endOf(next.value), index: 0, top: 0 }, filterItems(items, next.value).length) };
+  }
+
+  return { init: { value: '', cursor: 0, index: 0, top: 0 }, view, onKey };
+}
+
+module.exports = { createSelectList, filterItems };

package/lib/tui/widgets/spinner.js

@@ -0,0 +1,41 @@
+'use strict';
+// A spinner line for work that awaits something (child processes, I/O).
+const { Cancelled } = require('../cancelled');
+
+const frame = (theme, tick) => theme.sym.spinner[tick % theme.sym.spinner.length];
+
+const spinnerLine = ({ theme, tick, text }) => `  ${theme.paint('accent', frame(theme, tick))} ${text}`;
+
+// After a cancel the work gets this long to wind down (it is told through the signal) before we stop waiting.
+const SETTLE_MS = 1000;
+
+// Animates while `fn(signal)` runs, then clears the line. Resolves with fn's result.
+// Ctrl-C, Esc and closed input abort the signal and reject with Cancelled once fn has
+// stopped (or SETTLE_MS passed), so work that honours the signal can clean up first.
+async function withSpinner(session, text, fn, { intervalMs = 80 } = {}) {
+  let tick = 0;
+  const controller = new AbortController();
+  const show = () => session.draw((ctx) => [spinnerLine({ theme: ctx.theme, tick, text })]);
+  show();
+  const timer = setInterval(() => {
+    tick += 1;
+    show();
+  }, intervalMs);
+  if (timer.unref) timer.unref();
+  const unwatch = typeof session.watchCancel === 'function' ? session.watchCancel((reason) => controller.abort(new Cancelled(reason))) : () => {};
+  try {
+    const work = Promise.resolve().then(() => fn(controller.signal));
+    work.catch(() => {});
+    const cancelled = new Promise((resolve) => controller.signal.addEventListener('abort', resolve, { once: true }));
+    const winner = await Promise.race([work.then((value) => ({ value })), cancelled]);
+    if (winner && 'value' in winner) return winner.value;
+    await Promise.race([work.catch(() => {}), new Promise((resolve) => setTimeout(resolve, SETTLE_MS).unref())]);
+    throw controller.signal.reason;
+  } finally {
+    unwatch();
+    clearInterval(timer);
+    session.clear();
+  }
+}
+
+module.exports = { spinnerLine, withSpinner };