jaitus 0.3.0

package/src/ui.js

@@ -0,0 +1,562 @@
+// ─── Terminal presentation ──────────────────────────────────────────────────────
+//
+// No dependencies. A CLI people run with `npx` should not pull a tree of packages to
+// print coloured text, and every one of those is a supply-chain surface on a tool that
+// holds an API key.
+//
+// Colour is decided per call rather than once at import, because `--no-color` is parsed
+// after this module loads and a flag that only works depending on import order is a bug
+// waiting to be reported. The cost is one env lookup per styled string.
+//
+// Suppressed when the output is not a TTY, when NO_COLOR is set (the documented
+// convention at no-color.org), when TERM says dumb, or on `--no-color` — so piping
+// output to a file or another program gives clean text rather than escape codes.
+
+import readline from 'node:readline';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { loadSettings, HOME } from './config.js';
+
+// Read without re-entering config's write paths; failures mean defaults.
+function loadSettingsFile() { return loadSettings(); }
+
+/**
+ * 0 none, 1 sixteen colours, 2 two-hundred-and-fifty-six, 3 truecolor.
+ * FORCE_COLOR is honoured because CI systems that do render colour have no TTY.
+ */
+export function colorLevel() {
+  if (process.env.JAITUS_NO_COLOR || process.env.NO_COLOR) return 0;
+  if (process.env.TERM === 'dumb' && !process.env.FORCE_COLOR) return 0;
+  if (!process.stdout.isTTY && !process.env.FORCE_COLOR) return 0;
+  // Forced sixteen (legacy consoles): JAITUS_16COLOR=1. Modern Windows
+  // consoles (Node enables VT processing) handle 256 colors fine.
+  if (process.env.JAITUS_16COLOR) return 1;
+  if (process.env.COLORTERM === 'truecolor' || process.env.COLORTERM === '24bit') return 3;
+  if (process.env.WT_SESSION || process.env.TERM_PROGRAM) return 3; // Windows Terminal, iTerm, VS Code
+  if (/-256(color)?$/.test(process.env.TERM || '')) return 2;
+  if (process.platform === 'win32') return 2;
+  return 1;
+}
+
+/**
+ * Whether box-drawing and block characters will actually render.
+ *
+ * The honest answer is unknowable, so this asks whether we are in one of the terminals
+ * that certainly can. Getting it wrong the safe way prints a plain-ASCII logo; getting
+ * it wrong the other way prints a screen of question marks over the first thing a new
+ * user ever sees.
+ */
+export function unicode() {
+  if (process.env.JAITUS_ASCII) return false;
+  if (process.platform !== 'win32') return !/^(ansi|dumb|vt100)/.test(process.env.TERM || '');
+  // Windows: conhost (cmd.exe) renders half blocks and box drawing fine with its
+  // default TrueType fonts, so the answer is yes everywhere except a font that cannot.
+  return true;
+}
+
+export const columns = () => process.stdout.columns || Number(process.env.COLUMNS) || 80;
+
+/**
+ * Glyph twin: the pretty character on terminals that render it, plain ASCII
+ * everywhere else (classic conhost raster fonts turn ›✓✗◆ into tofu boxes).
+ * Decided per call — JAITUS_ASCII can change between calls in tests.
+ */
+export const glyph = (uni, ascii) => (unicode() ? uni : ascii);
+
+// ─── Theme tokens (§5.1) ──────────────────────────────────────────────────────
+//
+// Every colour in the CLI renders through these named tokens, never raw codes:
+// swapping the active map reskins the app without touching call sites. Presets
+// ship for dark terminals (default), light terminals, a colorblind-safe
+// daltonized pair, and plain ANSI. `auto` picks light/dark from COLORFGBG.
+// A `~/.jaitus/theme.json` file may override individual tokens with raw ANSI
+// code strings, e.g. { "brand": "38;5;209" }.
+const BASE_TOKENS = {
+  bold: [1, 22], dim: [2, 22], italic: [3, 23], underline: [4, 24],
+  inverse: [7, 27], red: [31, 39], green: [32, 39], yellow: [33, 39],
+  blue: [34, 39], magenta: [35, 39], cyan: [36, 39], grey: [90, 39],
+};
+
+// Jaitus site palette: brand coral rgb(255 107 74), accent teal rgb(32 168 152).
+// The chrome is coral + teal everywhere; red/yellow stay purely semantic
+// (errors/warnings), so the product never reads as another orange CLI.
+export const THEMES = {
+  dark: {
+    // 208 is the deep-orange 256 step; red stays reserved for errors.
+    ...BASE_TOKENS, brand: '38;5;208', permission: '38;5;214', shimmer: '38;5;217', accent: '38;5;36',
+    // opencode parity: assistant prose sits on the bare background — only
+    // user panels wear a fill. toolBg was already null; memoryBg stays.
+    userBg: '48;5;236', assistantBg: null, toolBg: null, memoryBg: '48;5;235', errorBg: '48;5;52',
+  },
+  light: {
+    ...BASE_TOKENS, brand: '31', permission: '34', grey: [30, 39], dim: [2, 22], shimmer: '38;5;217', accent: '36',
+    userBg: '48;5;254', assistantBg: null, toolBg: null, memoryBg: '48;5;253', errorBg: '48;5;224',
+  },
+  daltonized: {
+    ...BASE_TOKENS, brand: '34', permission: '33', green: [36, 39], shimmer: '38;5;153', accent: '36',
+    userBg: '48;5;236', assistantBg: null, toolBg: null, memoryBg: '48;5;235', errorBg: '48;5;52',
+  },
+  // Teal-forward dark: the site accent leads, coral stays for the brand mark.
+  ocean: {
+    ...BASE_TOKENS, brand: '38;5;45', permission: '38;5;214', shimmer: '38;5;159', accent: '38;5;51',
+    userBg: '48;5;236', assistantBg: null, toolBg: null, memoryBg: '48;5;235', errorBg: '48;5;52',
+  },
+  plain: {},
+  auto: null, // resolved at load time
+};
+
+// Settings hit disk — cache the map briefly so per-row rendering stays cheap.
+// reloadTheme() (after /theme or config) drops it immediately.
+let themeCache = null;
+const THEME_TTL_MS = 2000;
+export function themeName() {
+  // `auto` is the default so light-background terminals get readable colors
+  // without anyone configuring anything; unknown backgrounds stay dark.
+  const raw = process.env.JAITUS_THEME || loadSettingsSafe().theme || 'auto';
+  if (raw === 'auto') {
+    const bg = String(process.env.COLORFGBG || '').split(/[;:]/).pop();
+    return ['7', '15', '11', '14'].includes(bg) ? 'light' : 'dark';
+  }
+  return THEMES[raw] ? raw : 'dark';
+}
+function loadSettingsSafe() {
+  // config.js imports only node builtins — importing it here is cycle-free.
+  try { return loadSettingsFile(); } catch { return {}; }
+}
+export function themeMap() {
+  const now = Date.now();
+  if (!themeCache || now - themeCache.at > THEME_TTL_MS) {
+    const name = themeName();
+    if (!themeCache || themeCache.name !== name) {
+      const map = { ...(THEMES[name] || THEMES.dark) };
+      // Custom overrides: { "brand": "38;5;209" } or { "brand": [38, 39] }.
+      try {
+        const custom = loadSettingsSafe().customTheme || readThemeFile();
+        for (const [token, codes] of Object.entries(custom || {})) {
+          if (typeof codes === 'string') map[token] = codes;
+          else if (Array.isArray(codes)) map[token] = codes;
+        }
+      } catch { /* built-ins stand */ }
+      themeCache = { name, map, at: now };
+    } else {
+      themeCache.at = now;
+    }
+  }
+  return themeCache.map;
+}
+function readThemeFile() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(HOME, 'theme.json'), 'utf8'));
+  } catch { return null; }
+}
+/** Drop the cached map after /theme or config changes it. */
+export function reloadTheme() { themeCache = null; }
+
+const paint = (token) => (s) => {
+  if (colorLevel() === 0) return String(s);
+  const codes = themeMap()[token];
+  if (codes == null) return String(s);
+  const open = Array.isArray(codes) ? codes[0] : codes;
+  const close = Array.isArray(codes) ? codes[1] : 39;
+  return `\x1b[${open}m${s}\x1b[${close}m`;
+};
+
+export const c = {
+  bold: paint('bold'),
+  dim: paint('dim'),
+  italic: paint('italic'),
+  underline: paint('underline'),
+  // Standing block used for the cursor and selected menu rows.
+  inverse: paint('inverse'),
+  red: paint('red'),
+  green: paint('green'),
+  yellow: paint('yellow'),
+  blue: paint('blue'),
+  magenta: paint('magenta'),
+  cyan: paint('cyan'),
+  grey: paint('grey'),
+  // Lighter twin of the brand token: the moving half of the shimmer sweep (§8).
+  shimmer: paint('shimmer'),
+  // Site accent teal: the go/confirm voice (ok checks, accept-edits chrome).
+  accent: paint('accent'),
+  // Jaitus coral, matching the site. Degrades to yellow on a sixteen-colour terminal
+  // rather than to nothing, so the accent still reads.
+  brand: (s) => {
+    const level = colorLevel();
+    if (level === 0) return String(s);
+    const codes = themeMap().brand;
+    if (codes == null) return String(s);
+    if (Array.isArray(codes)) return `\x1b[${codes[0]}m${s}\x1b[${codes[1]}m`;
+    if (level >= 2 && /;/.test(String(codes))) return `\x1b[${codes}m${s}\x1b[39m`;
+    // Sixteen colors have no orange: red is the closest readable brand stand-in
+    // on both dark and light grounds (daltonized keeps its blue).
+    if (themeName() === 'daltonized') return `\x1b[34m${s}\x1b[39m`;
+    return `\x1b[31m${s}\x1b[39m`;
+  },
+  // Permission dialogs draw their own border colour so they stand out from the
+  // input box. Amber, degrading to plain yellow on sixteen colours.
+  permission: (s) => {
+    const level = colorLevel();
+    if (level === 0) return String(s);
+    const codes = themeMap().permission;
+    if (codes == null) return String(s);
+    if (Array.isArray(codes)) return `\x1b[${codes[0]}m${s}\x1b[${codes[1]}m`;
+    if (level >= 2 && /;/.test(String(codes))) return `\x1b[${codes}m${s}\x1b[39m`;
+    return `\x1b[33m${s}\x1b[39m`;
+  },
+};
+
+export const err = (s = '') => {
+  // Inside the TUI, stderr is invisible (alt-screen owns stdout and stderr has
+  // no sink) — route failures through the same sink so errors are actually
+  // shown. In print mode, stderr keeps its meaning for pipelines.
+  if (tuiSink && !printingFromTui) {
+    printingFromTui = true;
+    try { tuiSink.print(s, 'error'); } finally { printingFromTui = false; }
+    return;
+  }
+  process.stderr.write(`${s}\n`);
+};
+export const write = (s) => process.stdout.write(s);
+
+// When the sticky-bottom TUI is active, everything the rest of the CLI prints with
+// out() belongs ABOVE the input box. The TUI registers itself here and print() does
+// the erase-and-redraw dance around it; without a TUI this is a plain write.
+//
+// printingFromTui is a hard stop against the out() → print() → out() loop that once
+// ate a whole session with "Maximum call stack size exceeded": if the TUI itself ever
+// calls out() by accident, it prints plainly instead of recursing.
+let tuiSink = null;
+let printingFromTui = false;
+export function setTuiSink(fn) { tuiSink = fn; }
+export const out = (s = '') => {
+  if (tuiSink && !printingFromTui) {
+    printingFromTui = true;
+    try { tuiSink.print(s); } finally { printingFromTui = false; }
+    return;
+  }
+  process.stdout.write(`${s}\n`);
+};
+
+export const info = (s) => out(`${c.blue(glyph('›', '>'))} ${s}`);
+export const ok = (s) => out(`${c.accent(glyph('✓', '+'))} ${s}`);
+export const warn = (s) => out(`${c.yellow('!')} ${s}`);
+export const fail = (s) => err(`${c.red(glyph('✗', 'x'))} ${s}`);
+
+/** A section heading, for output with more than one part to it. */
+export const heading = (s) => out(`\n${c.bold(s)}`);
+
+export const rule = (width = Math.min(columns(), 72)) =>
+  out(c.grey((unicode() ? '─' : '-').repeat(width)));
+
+/** Reduced motion (§8.3): static glyph instead of the frame cycle. */
+function animationsOff() {
+  if (process.env.JAITUS_NO_ANIMATION) return true;
+  try { return loadSettings().animations === false; } catch { return false; }
+}
+
+/** A spinner that degrades to a single static line when there is no TTY. */
+export function spinner(text) {
+  if (!process.stdout.isTTY || process.env.JAITUS_NO_SPINNER || animationsOff()) {
+    out(`${c.dim(glyph('…', '...'))} ${text}`);
+    return { stop: () => {}, update: () => {} };
+  }
+  const frames = unicode()
+    ? ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+    : ['|', '/', '-', '\\'];
+  let i = 0;
+  let label = text;
+  // stop() is called more than once per spinner: runAgent stops it when the first
+  // streamed text arrives and again when the turn ends. The second \r\x1b[2K must not
+  // fire, or it erases the line the answer was just printed on — the model appears to
+  // have said nothing.
+  let stopped = false;
+  // Shimmer sweep (§8.1): the coral frame and a lighter twin trade across ticks.
+  const sweep = (text, tick) => {
+    const chars = [...String(text)];
+    const half = Math.max(1, Math.ceil(chars.length / 2));
+    return chars.map((ch, idx) => ((idx + tick) % chars.length < half ? c.brand(ch) : c.shimmer(ch))).join('');
+  };
+  const tick = () => {
+    if (stopped) return;
+    const n = i++;
+    write(`\r\x1b[2K${c.brand(frames[n % frames.length])} ${sweep(label, n)}`);
+  };
+  tick();
+  const timer = setInterval(tick, 80);
+  return {
+    update(next) { label = next; },
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      write('\r\x1b[2K');
+    },
+  };
+}
+
+/** Ask a question on stdin. Returns the trimmed answer. */
+export function ask(question) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) return resolve('');
+    process.stdout.write(question);
+    process.stdin.setEncoding('utf8');
+    const onData = (data) => {
+      process.stdin.removeListener('data', onData);
+      process.stdin.pause();
+      resolve(String(data).trim());
+    };
+    process.stdin.resume();
+    process.stdin.on('data', onData);
+  });
+}
+
+// ─── The session prompt ─────────────────────────────────────────────────────────
+//
+// readline rather than a bare `data` listener, because without it there are no arrow
+// keys, no Ctrl-A, no word-delete and no history — you get one shot at typing a
+// paragraph-long instruction and a typo means starting again. That is the single most
+// noticeable difference between a script with a `>` on it and a CLI.
+//
+// The interface is created and closed per line. It has to be: the permission prompt puts
+// stdin into raw mode itself, and two things owning stdin at once produces a terminal
+// that echoes nothing. History is carried across in memory and written to disk so it
+// survives the session too.
+
+let historyLines = [];
+let historyFile = null;
+let historyLoaded = false;
+
+const HISTORY_MAX = 500;
+
+export function useHistoryFile(file) {
+  historyFile = file;
+}
+
+function loadHistory() {
+  if (historyLoaded) return;
+  historyLoaded = true;
+  if (!historyFile) return;
+  try {
+    // readline's array is newest-first; the file is stored oldest-first so it reads
+    // naturally if anyone ever opens it.
+    historyLines = fs.readFileSync(historyFile, 'utf8').split('\n').filter(Boolean).reverse();
+  } catch { /* no history yet */ }
+}
+
+function saveHistory() {
+  if (!historyFile) return;
+  try {
+    fs.writeFileSync(historyFile, historyLines.slice(0, HISTORY_MAX).reverse().join('\n') + '\n', { mode: 0o600 });
+  } catch { /* history is a convenience, never a reason to fail a command */ }
+}
+
+/**
+ * Read one line with full line editing.
+ *
+ * Options:
+ *   completions  slash-command completions, offered when the line starts with '/'
+ *   fileComplete offer file-path completions when the line contains '@'
+ *   onShiftTab   called when Shift+Tab is pressed; if it returns a string, that
+ *                string is drawn as a transient mode indicator above the prompt
+ *   multiline    '\\ + Enter' continues the line — the escape is stripped
+ *
+ * Resolves `null` on end of input. Ctrl-C never resolves: it clears the
+ * draft, and on an empty prompt it hints at /exit instead of leaving.
+ */
+export function promptLine(question, { completions = [], fileComplete = false, onShiftTab = null, multiline = true } = {}) {
+  loadHistory();
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) return resolve(null);
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      history: historyLines.slice(),
+      historySize: HISTORY_MAX,
+      removeHistoryDuplicates: true,
+      terminal: true,
+      completer(line) {
+        // '@' file mentions complete from the filesystem, anywhere in the line.
+        if (fileComplete) {
+          const at = line.lastIndexOf('@');
+          if (at !== -1 && !line.slice(at).includes(' ')) {
+            const frag = line.slice(at + 1);
+            const hits = completeFiles(frag);
+            if (hits.length) return [hits.map((h) => line.slice(0, at + 1) + h), frag];
+          }
+        }
+        if (!completions.length || !line.startsWith('/')) return [[], line];
+        const hits = completions.filter((s) => s.startsWith(line));
+        return [hits.length ? hits : completions, line];
+      },
+    });
+
+    let answered = false;
+    const done = (value) => {
+      if (answered) return;
+      answered = true;
+      // rl.history is readline's own copy; take it back so the next prompt continues
+      // the same history rather than starting over.
+      historyLines = Array.isArray(rl.history) ? rl.history.slice(0, HISTORY_MAX) : historyLines;
+      rl.close();
+      if (value) saveHistory();
+      resolve(value);
+    };
+
+    // Shift+Tab: readline reports the back-tab escape. Not every terminal sends it
+    // (some send nothing for the key), but every terminal that can will land here.
+    let shiftTabAt = 0;
+    const onKeypress = (str, key) => {
+      if (!key) return;
+      const isShiftTab = (key.shift && key.name === 'tab')
+        || key.sequence === '\x1b[Z' || key.sequence === '\x1b[OT';
+      if (isShiftTab && onShiftTab) {
+        const mode = onShiftTab();
+        if (mode) {
+          // Redraw the prompt line with the new mode tag; the caller rebuilds the
+          // question, so the cheapest honest indicator is a notice line above.
+          process.stdout.write(`\r\x1b[2K  ${c.yellow(glyph('◈', '*') + ' mode: ' + mode)}\n`);
+          rl.write('');
+          shiftTabAt = Date.now();
+        }
+      }
+    };
+    if (onShiftTab) {
+      readline.emitKeypressEvents(process.stdin, rl);
+      process.stdin.on('keypress', onKeypress);
+    }
+
+    rl.question(question, (line) => done(line));
+    rl.on('close', () => {
+      if (onShiftTab) process.stdin.removeListener('keypress', onKeypress);
+      done(null);
+    });
+    // Ctrl-C clears the line but never leaves: exiting happens only through
+    // /exit (Ctrl+D on an empty prompt also just hints). Muscle memory for
+    // clearing is preserved; accidental session loss is not.
+    rl.on('SIGINT', () => {
+      if (rl.line) {
+        rl.write(null, { ctrl: true, name: 'u' });
+        return;
+      }
+      process.stdout.write(`\n  ${c.dim('Type /exit to leave')}\n`);
+      rl.prompt(true);
+    });
+  });
+}
+
+/**
+ * Watch for Esc while `run` is in flight and abort its controller. The stdin stream
+ * is already in keypress mode from the prompt; during agent work we take raw mode
+ * briefly so Esc arrives as a keypress instead of buffered input. Ctrl-C keeps its
+ * usual job of killing the whole session.
+ */
+export function watchEsc(run) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) { resolve(run()); return; }
+    let wasRaw = false;
+    try { wasRaw = process.stdin.isRaw; process.stdin.setRawMode(true); } catch { /* not a real TTY */ }
+    readline.emitKeypressEvents(process.stdin);
+    const ctrl = new AbortController();
+    const onKeypress = (str, key) => {
+      if (!key) return;
+      if (key.name === 'escape' || key.sequence === '\x1b') {
+        ctrl.abort();
+      } else if (key.ctrl && key.name === 'c') {
+        process.kill(process.pid, 'SIGINT');
+      }
+    };
+    process.stdin.on('keypress', onKeypress);
+    Promise.resolve()
+      .then(() => run(ctrl.signal), run)
+      .then((v) => { cleanup(); resolve(v); })
+      .catch((e) => { cleanup(); resolve({ __error: e }); });
+    function cleanup() {
+      process.stdin.removeListener('keypress', onKeypress);
+      try { process.stdin.setRawMode(wasRaw); } catch { /* already gone */ }
+      ctrl.abort(); // release any pending fetch body readers
+    }
+  });
+}
+
+/** Files and directories matching an '@' fragment, shallow and cheap. */
+function completeFiles(frag) {
+  try {
+    const dir = frag.includes('/') ? frag.slice(0, frag.lastIndexOf('/') + 1) : '';
+    const base = frag.slice(dir.length);
+    const entries = fs.readdirSync(path.resolve(dir || '.'), { withFileTypes: true });
+    return entries
+      .filter((e) => e.name.startsWith(base) && !e.name.startsWith('.'))
+      .map((e) => dir + e.name + (e.isDirectory() ? '/' : ''))
+      .slice(0, 12);
+  } catch {
+    return [];
+  }
+}
+
+/** A single keypress, for permission prompts. Returns the lowercased character. */
+export function askKey(question, allowed) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) return resolve('');
+    process.stdout.write(question);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    const onData = (key) => {
+      const ch = String(key).toLowerCase();
+      // Ctrl-C must still kill the process while raw mode is on, or the prompt is a trap.
+      if (key === '') {
+        process.stdin.setRawMode(false);
+        process.stdout.write('\n');
+        process.exit(130);
+      }
+      if (allowed && !allowed.includes(ch)) return;
+      process.stdin.removeListener('data', onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write(`${ch}\n`);
+      resolve(ch);
+    };
+    process.stdin.on('data', onData);
+  });
+}
+
+export const bullet = (s) => out(`  ${c.grey(glyph('•', '-'))} ${s}`);
+
+// Escape sequences take no space on screen but plenty in a string, so padding has to be
+// measured on what is visible. Padding on raw length puts a coloured column several
+// characters further right than an uncoloured one and the table stops being a table.
+// eslint-disable-next-line no-control-regex
+const ANSI = /\x1b\[[0-9;]*m/g;
+export const visibleWidth = (s) => String(s ?? '').replace(ANSI, '').length;
+
+export function table(rows) {
+  if (!rows.length) return;
+  const columnCount = Math.max(...rows.map((r) => r.length));
+  const widths = Array.from({ length: columnCount }, (_, i) =>
+    Math.max(...rows.map((r) => visibleWidth(r[i]))));
+  for (const row of rows) {
+    const line = row
+      .map((cell, i) => {
+        const text = String(cell ?? '');
+        return text + ' '.repeat(Math.max(0, widths[i] - visibleWidth(text)));
+      })
+      .join('  ');
+    out(line.replace(/\s+$/, ''));
+  }
+}
+
+/**
+ * Print a result as JSON when `--json` was asked for, otherwise run the human renderer.
+ * Every command that reports something goes through here, so scripting the CLI never
+ * means parsing a layout that was designed to be read.
+ */
+export function present(json, data, render) {
+  if (json) {
+    out(JSON.stringify(data, null, 2));
+    return;
+  }
+  render();
+}