@bahulam/code 0.1.1

package/src/ui/term.mjs

@@ -0,0 +1,174 @@
+/**
+ * Terminal capability detection.
+ *
+ * Resolves once at import. Re-evaluation requires `refresh()` (used by tests
+ * and the rare command that toggles a relevant env var mid-process).
+ *
+ * Capability tiers (highest first):
+ *   truecolor - 24-bit RGB (e.g. iTerm2, modern xterm, Windows Terminal)
+ *   ansi256  - 256-color palette
+ *   ansi16   - basic 16 colors
+ *   none     - no color (NO_COLOR=1, dumb terminal, non-TTY without override)
+ */
+
+const TRUECOLOR_TERMS = new Set([
+  'truecolor',
+  '24bit',
+  '24-bit',
+]);
+
+const ANSI256_TERMS = [
+  /-256(color)?$/i,
+  /^xterm/i,
+  /^screen/i,
+  /^tmux/i,
+  /^rxvt-unicode/i,
+  /^alacritty/i,
+];
+
+const DUMB_TERMS = new Set(['', 'dumb', 'unknown']);
+
+function readEnv() {
+  const env = process.env || {};
+  return {
+    NO_COLOR: env.NO_COLOR,
+    FORCE_COLOR: env.FORCE_COLOR,
+    BAHULAM_PLAIN: env.BAHULAM_PLAIN,
+    KEPLER_PLAIN: env.KEPLER_PLAIN,
+    BAHULAM_TTY_MODE: env.BAHULAM_TTY_MODE,
+    KEPLER_TTY_MODE: env.KEPLER_TTY_MODE,
+    COLORTERM: (env.COLORTERM || '').toLowerCase(),
+    TERM: (env.TERM || '').toLowerCase(),
+    TERM_PROGRAM: env.TERM_PROGRAM || '',
+    CI: env.CI,
+  };
+}
+
+function detectColorLevel(env, isTTY) {
+  // Hard opt-out (https://no-color.org). Honored even on TTYs.
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return 'none';
+  if (env.BAHULAM_PLAIN === '1') return 'none';
+  if (env.KEPLER_PLAIN === '1') return 'none';
+
+  // Hard opt-in. FORCE_COLOR=1|2|3 maps to ansi16|ansi256|truecolor.
+  // FORCE_COLOR with no value or =true falls through to detection.
+  if (env.FORCE_COLOR !== undefined) {
+    const v = String(env.FORCE_COLOR).trim();
+    if (v === '0' || v === 'false') return 'none';
+    if (v === '1') return 'ansi16';
+    if (v === '2') return 'ansi256';
+    if (v === '3') return 'truecolor';
+    // Any other truthy value: continue detection but allow non-TTY.
+    isTTY = true;
+  }
+
+  // No TTY and not forced: no color.
+  if (!isTTY) return 'none';
+
+  if (DUMB_TERMS.has(env.TERM)) return 'none';
+
+  if (TRUECOLOR_TERMS.has(env.COLORTERM)) return 'truecolor';
+
+  // Some terminal emulators advertise truecolor through TERM_PROGRAM.
+  if (env.TERM_PROGRAM === 'iTerm.app' || env.TERM_PROGRAM === 'WezTerm') {
+    return 'truecolor';
+  }
+  if (env.TERM_PROGRAM === 'vscode' || env.TERM_PROGRAM === 'Apple_Terminal') {
+    return 'ansi256';
+  }
+
+  if (ANSI256_TERMS.some(re => re.test(env.TERM))) return 'ansi256';
+
+  return 'ansi16';
+}
+
+function detectUnicode(env) {
+  if (env.BAHULAM_PLAIN === '1') return false;
+  if (env.KEPLER_PLAIN === '1') return false;
+  // Most modern terminals on macOS/Linux handle UTF-8.
+  // Windows ConEmu / older terminals are the main holdouts; conservative
+  // fallback when LANG and LC_* are missing or explicitly POSIX.
+  const lang = (process.env.LANG || process.env.LC_ALL || process.env.LC_CTYPE || '').toLowerCase();
+  if (!lang) return process.platform !== 'win32';
+  if (lang.includes('utf')) return true;
+  return false;
+}
+
+function detectTtyMode(env) {
+  const raw = String(env.BAHULAM_TTY_MODE || env.KEPLER_TTY_MODE || '').trim().toLowerCase();
+  if (env.BAHULAM_PLAIN === '1' || env.KEPLER_PLAIN === '1') return 'plain';
+  if (raw === 'stable' || raw === 'simple' || raw === 'static' || raw === 'transcript') return 'stable';
+  return 'rich';
+}
+
+function compute() {
+  const env = readEnv();
+  const isTTY = !!(process.stdout && process.stdout.isTTY);
+  const level = detectColorLevel(env, isTTY);
+  const ttyMode = detectTtyMode(env);
+  return {
+    isTTY,
+    colorLevel: level,                       // 'none' | 'ansi16' | 'ansi256' | 'truecolor'
+    color: level !== 'none',
+    truecolor: level === 'truecolor',
+    ansi256: level === 'ansi256' || level === 'truecolor',
+    unicode: detectUnicode(env),
+    ttyMode,                                 // 'rich' | 'stable' | 'plain'
+    plain: ttyMode === 'plain',
+    fixedInput: ttyMode === 'rich',
+    columns: (process.stdout && process.stdout.columns) || 80,
+    rows: (process.stdout && process.stdout.rows) || 24,
+    ci: !!env.CI,
+  };
+}
+
+let _capabilities = compute();
+
+/**
+ * Current terminal capabilities. Stable until `refresh()` is called.
+ */
+export function term() {
+  return _capabilities;
+}
+
+/**
+ * Re-run capability detection. Tests, `/config` reloads, or runtime env changes.
+ */
+export function refresh() {
+  _capabilities = compute();
+  return _capabilities;
+}
+
+/**
+ * Listen for terminal resizes. Returns an unsubscribe function.
+ * Callers receive the latest capabilities object (with updated columns/rows).
+ */
+export function onResize(handler) {
+  if (typeof handler !== 'function') return () => {};
+  const stream = process.stdout;
+  if (!stream || typeof stream.on !== 'function') return () => {};
+
+  const onChange = () => {
+    _capabilities = {
+      ..._capabilities,
+      columns: stream.columns || _capabilities.columns,
+      rows: stream.rows || _capabilities.rows,
+    };
+    handler(_capabilities);
+  };
+  stream.on('resize', onChange);
+  return () => stream.off('resize', onChange);
+}
+
+/**
+ * Force a capability level. Test-only escape hatch.
+ * Pass `null` to clear and re-detect.
+ */
+export function _setForTesting(overrides) {
+  if (overrides === null) {
+    _capabilities = compute();
+    return _capabilities;
+  }
+  _capabilities = { ..._capabilities, ...overrides };
+  return _capabilities;
+}

package/src/ui/text-layout.mjs

@@ -0,0 +1,127 @@
+/**
+ * Pure text layout helpers.
+ *
+ * Extracted so the input dock's line-wrapping and clipping logic can be
+ * unit-tested without a live terminal. Everything here is a pure function
+ * of its inputs.
+ */
+
+import { strip as stripAnsi, width as visibleWidth } from './palette.mjs';
+
+/**
+ * Wrap `text` into lines of at most `maxWidth` visible columns.
+ *
+ * - Preserves existing '\n' as hard breaks.
+ * - Wraps long lines at whitespace when possible.
+ * - Breaks mid-word only when a single word exceeds maxWidth.
+ * - Empty input returns [''].
+ * - ANSI escapes are preserved; wrap decisions use visible width.
+ *
+ * @param {string} text
+ * @param {number} maxWidth
+ * @returns {string[]}
+ */
+export function wrapToLines(text, maxWidth) {
+  const width = Math.max(1, Math.floor(maxWidth));
+  const source = String(text ?? '');
+  if (!source) return [''];
+
+  const out = [];
+  for (const rawLine of source.split('\n')) {
+    if (rawLine === '') { out.push(''); continue; }
+    if (visibleWidth(rawLine) <= width) { out.push(rawLine); continue; }
+
+    // Long line — wrap at whitespace where possible.
+    let current = '';
+    const tokens = tokenizeForWrap(rawLine);
+    for (const token of tokens) {
+      const isSpace = /^\s+$/.test(stripAnsi(token));
+      const candidate = current + token;
+      if (visibleWidth(candidate) <= width) { current = candidate; continue; }
+      if (current) { out.push(current.replace(/\s+$/, '')); current = ''; }
+      if (isSpace) continue; // don't start a new line with pure whitespace
+      // Token alone still too wide — chunk it.
+      if (visibleWidth(token) > width) {
+        for (const chunk of chunkByVisibleWidth(token, width)) out.push(chunk);
+      } else {
+        current = token;
+      }
+    }
+    if (current) out.push(current.replace(/\s+$/, ''));
+  }
+  return out.length ? out : [''];
+}
+
+/**
+ * Take the last `maxRows` of `lines`. If more lines were dropped, prefix
+ * the first surviving line with a dim '…' marker so the truncation is
+ * explicit (per PRD §5.1).
+ *
+ * Returns { visible, truncated: boolean, dropped: number }.
+ */
+export function tailWithEllipsis(lines, maxRows, ellipsis = '… ') {
+  const rows = Math.max(1, Math.floor(maxRows));
+  const arr = Array.isArray(lines) ? lines : [];
+  if (arr.length <= rows) return { visible: arr.slice(), truncated: false, dropped: 0 };
+  const dropped = arr.length - rows;
+  const visible = arr.slice(dropped);
+  visible[0] = `${ellipsis}${visible[0] || ''}`;
+  return { visible, truncated: true, dropped };
+}
+
+/**
+ * Given the wrapped visible lines and a cursor position (as a linear
+ * character offset into the *joined* wrapped output), return the
+ * { row, col } inside the visible block (0-indexed).
+ *
+ * Used to place the terminal cursor after rendering the input buffer.
+ */
+export function cursorPositionInLines(visibleLines, offset) {
+  const arr = Array.isArray(visibleLines) ? visibleLines : [];
+  let remaining = Math.max(0, Math.floor(offset));
+  for (let row = 0; row < arr.length; row++) {
+    const line = arr[row] || '';
+    const w = visibleWidth(line);
+    if (remaining <= w) return { row, col: remaining };
+    remaining -= w;
+    // Newline between wrapped lines doesn't count as a visible column,
+    // but consumes zero of the remaining offset either.
+  }
+  const lastRow = Math.max(0, arr.length - 1);
+  return { row: lastRow, col: visibleWidth(arr[lastRow] || '') };
+}
+
+// ── internals ────────────────────────────────────────────────────────────
+
+// Tokenize into runs of non-whitespace and whitespace so wrapWords can
+// decide break points without merging spaces into words. ANSI escapes stay
+// attached to the visible token they precede.
+function tokenizeForWrap(line) {
+  const tokens = [];
+  const re = /(\s+|\S+)/g;
+  let m;
+  while ((m = re.exec(line)) !== null) tokens.push(m[0]);
+  return tokens;
+}
+
+// Split a single overly-long token into chunks of at most `maxWidth`
+// visible cells, preserving ANSI escape sequences (they don't count).
+function chunkByVisibleWidth(token, maxWidth) {
+  const chunks = [];
+  let buf = '';
+  let bufWidth = 0;
+  const chars = Array.from(String(token));
+  for (const ch of chars) {
+    // Naive: treat each codepoint as 1 cell. Good enough for path-like
+    // tokens; wide-char inputs would need a fuller width table.
+    if (bufWidth + 1 > maxWidth) {
+      chunks.push(buf);
+      buf = '';
+      bufWidth = 0;
+    }
+    buf += ch;
+    bufWidth += 1;
+  }
+  if (buf) chunks.push(buf);
+  return chunks;
+}