@axplusb/kepler 1.0.10 → 2.0.2

package/src/ui/palette.mjs

@@ -0,0 +1,189 @@
+/**
+ * Kepler palette — semantic color tokens for the CLI.
+ *
+ * Every feature module imports from here, never from raw ANSI. Tokens resolve
+ * at call time so changing terminal capabilities (resize, `refresh()`) is
+ * picked up without restarting the process.
+ *
+ *   import { paint } from './palette.mjs';
+ *   process.stdout.write(paint.brand.primary('KEPLER'));
+ *
+ * Composition (multiple styles on one string):
+ *
+ *   paint.bold(paint.brand.primary('KEPLER'))
+ *
+ * Tier behavior:
+ *   truecolor → 24-bit RGB
+ *   ansi256   → nearest 256-color index
+ *   ansi16    → nearest basic color
+ *   none      → identity (input returned unchanged)
+ *
+ * Brand identity (Mission Control PRD-055):
+ *   primary  Deep Space Purple  #7c3aed
+ *   accent   Stellar Magenta    #ec4899
+ *   data     Neon Cyan          #22d3ee
+ *   success  Aligned green      #22c55e
+ *   warn     Soft amber         #eab308
+ *   danger   Failure red        #ef4444
+ *   dim      Sub-agent / hint   #6b7280
+ *   text     Primary text       #c9d1d9
+ */
+
+import { term } from './term.mjs';
+
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+
+// ── Brand tokens ─────────────────────────────────────────────────────────
+// Each token is { rgb: [r,g,b], ansi256: n, ansi16: 'fgName' }.
+// `ansi16` maps to a key in BASIC_FG below.
+
+export const TOKENS = Object.freeze({
+  // Brand
+  'brand.primary': { rgb: [124, 58, 237],  ansi256: 99,  ansi16: 'magenta' }, // #7c3aed
+  'brand.accent':  { rgb: [236, 72, 153],  ansi256: 198, ansi16: 'magenta' }, // #ec4899
+  'brand.data':    { rgb: [34, 211, 238],  ansi256: 87,  ansi16: 'cyan'    }, // #22d3ee
+
+  // State
+  'state.success': { rgb: [34, 197, 94],   ansi256: 41,  ansi16: 'green'   }, // #22c55e
+  'state.warn':    { rgb: [234, 179, 8],   ansi256: 220, ansi16: 'yellow'  }, // #eab308
+  'state.danger':  { rgb: [239, 68, 68],   ansi256: 196, ansi16: 'red'     }, // #ef4444
+
+  // Text
+  'text.primary':  { rgb: [201, 209, 217], ansi256: 250, ansi16: 'white'   }, // #c9d1d9
+  'text.dim':      { rgb: [107, 114, 128], ansi256: 245, ansi16: 'gray'    }, // #6b7280
+  'text.muted':    { rgb: [156, 163, 175], ansi256: 247, ansi16: 'gray'    }, // #9ca3af
+});
+
+// ── ANSI 16-color foreground codes ───────────────────────────────────────
+
+const BASIC_FG = {
+  black:   30,
+  red:     31,
+  green:   32,
+  yellow:  33,
+  blue:    34,
+  magenta: 35,
+  cyan:    36,
+  white:   37,
+  gray:    90,
+};
+
+// ── Style codes (work at every tier) ─────────────────────────────────────
+
+const STYLE_CODES = {
+  bold:      [1, 22],
+  dim:       [2, 22],
+  italic:    [3, 23],
+  underline: [4, 24],
+  inverse:   [7, 27],
+  strike:    [9, 29],
+};
+
+// ── Open / close sequence builders ───────────────────────────────────────
+
+function openForToken(token, capability) {
+  const def = TOKENS[token];
+  if (!def) return '';
+
+  if (capability === 'truecolor') {
+    const [r, g, b] = def.rgb;
+    return `${ESC}38;2;${r};${g};${b}m`;
+  }
+  if (capability === 'ansi256') {
+    return `${ESC}38;5;${def.ansi256}m`;
+  }
+  if (capability === 'ansi16') {
+    return `${ESC}${BASIC_FG[def.ansi16] || BASIC_FG.white}m`;
+  }
+  return '';
+}
+
+function wrap(open) {
+  if (!open) return (input) => String(input ?? '');
+  // Re-open after every embedded reset so nested styles compose.
+  // Cheap and predictable; most tool output is short enough that the cost
+  // is negligible compared to writing to the TTY.
+  return (input) => {
+    const text = String(input ?? '');
+    if (!text) return '';
+    if (!text.includes(RESET)) return `${open}${text}${RESET}`;
+    return `${open}${text.split(RESET).join(`${RESET}${open}`)}${RESET}`;
+  };
+}
+
+function styleWrap(openCode, closeCode) {
+  return (input) => {
+    const text = String(input ?? '');
+    if (!text) return '';
+    // No color tier check here — styles like bold/dim work even in ansi16.
+    if (!term().color) return text;
+    const open = `${ESC}${openCode}m`;
+    const close = `${ESC}${closeCode}m`;
+    if (!text.includes(close)) return `${open}${text}${close}`;
+    return `${open}${text.split(close).join(`${close}${open}`)}${close}`;
+  };
+}
+
+// ── Build a structured `paint` object once per token ─────────────────────
+
+function buildPaint() {
+  const paint = {};
+
+  // Brand / state / text colorizers, nested by namespace.
+  for (const token of Object.keys(TOKENS)) {
+    const [ns, name] = token.split('.');
+    if (!paint[ns]) paint[ns] = {};
+    paint[ns][name] = (input) => {
+      const t = term();
+      if (!t.color) return String(input ?? '');
+      return wrap(openForToken(token, t.colorLevel))(input);
+    };
+  }
+
+  // Style colorizers (callable directly).
+  for (const [style, [open, close]] of Object.entries(STYLE_CODES)) {
+    paint[style] = styleWrap(open, close);
+  }
+
+  // Compose helper — apply multiple styles left-to-right.
+  paint.compose = (...fns) => (input) =>
+    fns.reduce((acc, fn) => (typeof fn === 'function' ? fn(acc) : acc), input);
+
+  // Raw token accessor for callers that need to inject codes around their
+  // own text (e.g. status bar repaint loops that re-style a buffer).
+  paint.token = (key) => {
+    const t = term();
+    if (!t.color) return { open: '', close: '' };
+    return { open: openForToken(key, t.colorLevel), close: RESET };
+  };
+
+  return paint;
+}
+
+export const paint = buildPaint();
+
+// ── Plain-text helper (always strips colors) ─────────────────────────────
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+export function strip(input) {
+  return String(input ?? '').replace(ANSI_RE, '');
+}
+
+/**
+ * Visible length of a string (ignoring ANSI codes).
+ * Surrogate pairs (emoji) count as 1 visual cell for layout purposes — this
+ * is consistent with most terminals' rendering of single-codepoint emoji.
+ */
+export function width(input) {
+  const plain = strip(input);
+  // Strip variation selectors so "🛰️" measures as one cell.
+  return [...plain.replace(/︎|️/g, '')].length;
+}
+
+// ── Backwards compatibility re-exports ───────────────────────────────────
+// `ansi.mjs` and other legacy modules import these names. New code should
+// prefer `paint.brand.primary(...)` etc.
+
+export const RESET_CODE = RESET;

package/src/ui/spinner.mjs

@@ -0,0 +1,116 @@
+/**
+ * Single shared spinner — Mission Control (PRD-055 §4.4).
+ *
+ * One spinner instance per process. The repl and status bar consume frames
+ * from the same source so the eye never sees two animations out of phase.
+ *
+ * Usage:
+ *
+ *   const stop = startSpinner('Reading auth.py');
+ *   await doWork();
+ *   stop();                          // clears the line and stops the timer
+ *
+ * Or, for a managed line that already exists (e.g. the status bar):
+ *
+ *   const tick = spinnerFrame();     // current frame, advances on next call
+ *
+ * Behavior:
+ *   - 120ms per frame.
+ *   - Suppressed entirely when stdout is not a TTY or when KEPLER_PLAIN=1.
+ *     The `start`/`stop` API is still safe to call (no-op).
+ *   - Color follows the current orbit (orchestrated by the caller via the
+ *     palette token). Default: brand.primary.
+ *   - ASCII fallback (when no Unicode): 'plain dot rotation'.
+ */
+
+import { paint } from './palette.mjs';
+import { term } from './term.mjs';
+
+// 8-step rotation. The PRD spec calls for ◯ → ◔ → ◑ → ◕ → ● → ◕ → ◑ → ◔
+// which yields a perceptual "breathing" cycle rather than a left-right spin.
+const FRAMES_UTF = ['◯', '◔', '◑', '◕', '●', '◕', '◑', '◔'];
+const FRAMES_ASCII = ['.', 'o', 'O', '@', 'O', 'o', '.', ' '];
+
+const INTERVAL_MS = 120;
+
+let _frame = 0;
+
+/**
+ * Current spinner glyph. Advances the cursor each call.
+ * Honors capability detection automatically.
+ */
+export function spinnerFrame(painter = paint.brand.primary) {
+  const frames = term().unicode ? FRAMES_UTF : FRAMES_ASCII;
+  const ch = frames[_frame % frames.length];
+  _frame = (_frame + 1) % frames.length;
+  return painter ? painter(ch) : ch;
+}
+
+/**
+ * Reset to frame 0 — useful at the start of a new turn so consecutive
+ * tool calls do not inherit each other's phase.
+ */
+export function resetSpinner() {
+  _frame = 0;
+}
+
+/**
+ * Start an inline spinner attached to `text`. Returns a stop function.
+ *
+ * The line is re-rendered in place using carriage return + erase, so the
+ * caller does not need to manage cursor state. If the terminal cannot
+ * render in place (non-TTY, dumb terminal, plain mode), the spinner becomes
+ * a single static line `"… text"` written once.
+ */
+export function startSpinner(text, { stream = process.stderr, painter, color = 'brand.primary' } = {}) {
+  const t = term();
+  if (!t.isTTY || t.plain || !t.color) {
+    try { stream.write(`… ${text}\n`); } catch {}
+    return () => {};
+  }
+
+  const paintFn = painter || tokenPainter(color);
+  let stopped = false;
+
+  const render = () => {
+    if (stopped) return;
+    const glyph = spinnerFrame(paintFn);
+    try {
+      stream.write(`\r\x1b[2K${glyph} ${paint.text.dim(text)}`);
+    } catch {
+      // Stream closed mid-spin — stop quietly.
+      stop();
+    }
+  };
+
+  render();
+  const handle = setInterval(render, INTERVAL_MS);
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(handle);
+    try {
+      stream.write('\r\x1b[2K');
+    } catch {}
+  }
+
+  return stop;
+}
+
+/**
+ * Look up a painter function from a dotted token name (e.g. 'brand.accent').
+ * Falls back to the identity painter when the token does not exist.
+ */
+function tokenPainter(tokenPath) {
+  const [ns, name] = String(tokenPath || '').split('.');
+  const group = paint[ns];
+  if (group && typeof group[name] === 'function') return group[name];
+  return (s) => String(s ?? '');
+}
+
+/**
+ * Interval used by the shared spinner. Exposed for the status bar to
+ * synchronize its own re-paints with the spinner phase.
+ */
+export const SPINNER_INTERVAL_MS = INTERVAL_MS;

package/src/ui/status-bar.mjs

@@ -0,0 +1,275 @@
+/**
+ * Persistent two-line status bar — Mission Control (PRD-055 §5).
+ *
+ * Anchors itself to the bottom two rows of the terminal using a DECSTBM
+ * scroll region:
+ *
+ *   ┌────────────────────────────────────────────────┐
+ *   │  scroll region (rows 1..rows-2)                │
+ *   │  scroll region (rows 1..rows-2)                │
+ *   │  scroll region (rows 1..rows-2)                │
+ *   ├────────────────────────────────────────────────┤
+ *   │  status line 1 — ORBIT | TASK | TURN | COST    │
+ *   │  status line 2 — keyboard dock                  │
+ *   └────────────────────────────────────────────────┘
+ *
+ * The scroll region is set once at mount; afterwards normal stdout/stderr
+ * writes scroll within the upper region without ever touching the bar.
+ *
+ * Behavior:
+ *   - No-op when stdout is not a TTY, or when KEPLER_PLAIN=1.
+ *     The `mount/unmount/setOrbit` API is still safe to call.
+ *   - Re-renders on state change (event-driven), not on a timer (except
+ *     while in a state with a live spinner — see `_tickIfNeeded`).
+ *   - SIGWINCH handler re-pads and re-sets the scroll region.
+ *   - `unmount()` MUST be called before exit so the scroll region is
+ *     restored and the cursor is shown.
+ *
+ * Implementation notes:
+ *   - All output goes to stderr to keep stdout pipe-clean for `--print`/
+ *     headless modes; if stdout is the only thing piped, the headless
+ *     branch already short-circuits this module before any escape codes
+ *     are emitted.
+ *   - The PRD's "tput sc/rc" hint is shorthand. We use the actual VT100
+ *     scroll region (`CSI top;bot r`) plus save/restore cursor.
+ */
+
+import { paint, width as visibleWidth } from './palette.mjs';
+import { icons } from './icons.mjs';
+import { spinnerFrame, SPINNER_INTERVAL_MS } from './spinner.mjs';
+import { term, onResize } from './term.mjs';
+import { ORBITS } from '../state/orbit.mjs';
+import { dockForOrbit, renderDock } from './dock.mjs';
+
+const ESC = '\x1b[';
+const OUT = process.stderr;
+
+// ── Orbit metadata: visual style + label ─────────────────────────────────
+
+const ORBIT_META = {
+  [ORBITS.IDLE]:      { label: 'IDLE',      paint: (s) => paint.text.dim(s),    spinning: false },
+  [ORBITS.DISCOVERY]: { label: 'DISCOVERY', paint: (s) => paint.text.dim(s),    spinning: true  },
+  [ORBITS.PLANNING]:  { label: 'PLANNING',  paint: (s) => paint.state.warn(s),  spinning: true  },
+  [ORBITS.EXECUTION]: { label: 'EXECUTION', paint: (s) => paint.brand.primary(s), spinning: true },
+  [ORBITS.ALIGNMENT]: { label: 'ALIGNMENT', paint: (s) => paint.brand.data(s),  spinning: true  },
+  [ORBITS.AWAITING]:  { label: 'AWAITING',  paint: (s) => paint.brand.accent(s), spinning: false, border: true },
+  [ORBITS.PAUSED]:    { label: 'PAUSED',    paint: (s) => paint.state.warn(s),  spinning: false },
+};
+
+// ── State held by the singleton ──────────────────────────────────────────
+
+let mounted = false;
+let unsubResize = null;
+let tickInterval = null;
+let lastSnapshot = null;
+let resetting = false;
+
+// ── Low-level cursor / region helpers ────────────────────────────────────
+
+function write(s) { try { OUT.write(s); } catch {} }
+
+function setScrollRegion(top, bottom) { write(`${ESC}${top};${bottom}r`); }
+function clearScrollRegion()           { write(`${ESC}r`); }
+function saveCursor()                  { write(`${ESC}s`); }
+function restoreCursor()               { write(`${ESC}u`); }
+function moveTo(row, col)              { write(`${ESC}${row};${col}H`); }
+function clearLine()                   { write(`${ESC}2K`); }
+function hideCursor()                  { write(`${ESC}?25l`); }
+function showCursor()                  { write(`${ESC}?25h`); }
+
+// ── Layout: assemble the two lines ───────────────────────────────────────
+
+function formatCost(usd) {
+  if (typeof usd !== 'number' || !Number.isFinite(usd)) return '$0.00';
+  if (usd < 0.01) return `$${usd.toFixed(4)}`;
+  return `$${usd.toFixed(2)}`;
+}
+
+function buildLineOne(snap, cols) {
+  const meta = ORBIT_META[snap.orbit] || ORBIT_META[ORBITS.IDLE];
+  const sep  = paint.text.dim(' │ ');
+
+  const glyph = meta.spinning ? spinnerFrame(meta.paint) : meta.paint(icons.orbit);
+  const orbitLabel = `${glyph} ${meta.paint('ORBIT: ' + meta.label)}`;
+
+  const segments = [orbitLabel];
+
+  if (snap.task) {
+    segments.push(paint.text.dim('TASK: ') + paint.text.primary(snap.task));
+  }
+  if (snap.subAgents > 0) {
+    const noun = snap.subAgents === 1 ? 'sub-agent' : 'sub-agents';
+    segments.push(paint.brand.data(`${icons.subAgent} ${snap.subAgents} ${noun}`) + ' ' + paint.text.dim('active'));
+  }
+  if (snap.turn > 0) {
+    const turnText = snap.maxTurn > 0 ? `TURN ${snap.turn}/${snap.maxTurn}` : `TURN ${snap.turn}`;
+    segments.push(paint.text.dim(turnText));
+  }
+  segments.push(paint.text.dim('COST ') + paint.brand.data(formatCost(snap.cost)));
+
+  return assembleLine(segments, sep, cols);
+}
+
+function buildLineTwo(snap, cols) {
+  if (snap.orbit === ORBITS.AWAITING && snap.awaitingTool) {
+    const prefix = paint.brand.accent(`${icons.warn} APPROVAL  `) + paint.text.primary(snap.awaitingTool);
+    const tail = renderDock(dockForOrbit(snap.orbit), Math.max(0, cols - visibleWidth(prefix) - 2));
+    return ` ${prefix}  ${tail}`;
+  }
+  const hints = dockForOrbit(snap.orbit);
+  return ' ' + renderDock(hints, cols - 1);
+}
+
+/**
+ * Concatenate segments with separators, dropping trailing segments when
+ * they exceed `cols` of visible width. Always keeps the first segment.
+ */
+function assembleLine(segments, sep, cols) {
+  if (segments.length === 0) return '';
+  let out = ' ' + segments[0];
+  let used = 1 + visibleWidth(segments[0]);
+  for (let i = 1; i < segments.length; i++) {
+    const piece = sep + segments[i];
+    const cost = visibleWidth(piece);
+    if (used + cost > cols) break;
+    out += piece;
+    used += cost;
+  }
+  return out;
+}
+
+// ── Render ───────────────────────────────────────────────────────────────
+
+function paintLine(text, cols) {
+  const pad = Math.max(0, cols - visibleWidth(text));
+  return text + ' '.repeat(pad);
+}
+
+function render(snap) {
+  if (!mounted || !snap) return;
+  const t = term();
+  if (!t.isTTY || t.plain) return;
+
+  const cols = Math.max(20, t.columns);
+  const rows = Math.max(4,  t.rows);
+
+  const line1 = paintLine(buildLineOne(snap, cols), cols);
+  const line2 = paintLine(buildLineTwo(snap, cols), cols);
+
+  saveCursor();
+  moveTo(rows - 1, 1);
+  clearLine();
+  write(line1);
+  moveTo(rows, 1);
+  clearLine();
+  write(line2);
+  restoreCursor();
+}
+
+// ── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Mount the status bar. Sets up the scroll region, hides the cursor, and
+ * registers SIGWINCH. Returns `false` when the environment is not TTY
+ * (caller can short-circuit).
+ *
+ * Safe to call multiple times — re-entrant calls are no-ops.
+ */
+export function mount() {
+  if (mounted) return true;
+  const t = term();
+  if (!t.isTTY || t.plain) return false;
+
+  // Reserve the bottom 2 rows.
+  const rows = Math.max(4, t.rows);
+  setScrollRegion(1, rows - 2);
+  moveTo(rows - 1, 1); clearLine();
+  moveTo(rows, 1);     clearLine();
+  // Restore cursor into the scroll region so subsequent writes go there.
+  moveTo(rows - 2, 1);
+
+  unsubResize = onResize(() => {
+    if (!mounted) return;
+    const r = Math.max(4, term().rows);
+    setScrollRegion(1, r - 2);
+    if (lastSnapshot) render(lastSnapshot);
+  });
+
+  // Cleanup hooks — exits, signals, uncaught crash all restore the terminal.
+  process.once('exit',    safeUnmount);
+  process.once('SIGINT',  () => { safeUnmount(); process.exit(130); });
+  process.once('SIGTERM', () => { safeUnmount(); process.exit(143); });
+
+  mounted = true;
+  return true;
+}
+
+/**
+ * Tear down: restore scroll region, show cursor. Must be called before
+ * process exit. Safe to call when not mounted.
+ */
+export function unmount() {
+  if (!mounted || resetting) return;
+  resetting = true;
+  try {
+    clearScrollRegion();
+    showCursor();
+    if (unsubResize) { unsubResize(); unsubResize = null; }
+    if (tickInterval) { clearInterval(tickInterval); tickInterval = null; }
+  } finally {
+    mounted = false;
+    resetting = false;
+  }
+}
+
+function safeUnmount() { try { unmount(); } catch {} }
+
+/**
+ * Push a new orbit snapshot. Triggers a render and starts/stops the
+ * spinner tick as needed.
+ */
+export function setOrbit(snap) {
+  lastSnapshot = snap;
+  if (!mounted) return;
+  const meta = ORBIT_META[snap.orbit] || ORBIT_META[ORBITS.IDLE];
+  if (meta.spinning) startTick();
+  else stopTick();
+  render(snap);
+}
+
+/** Force an immediate redraw using the last known snapshot. */
+export function redraw() {
+  if (lastSnapshot) render(lastSnapshot);
+}
+
+function startTick() {
+  if (tickInterval || !mounted) return;
+  tickInterval = setInterval(() => {
+    if (!mounted || !lastSnapshot) return;
+    render(lastSnapshot);
+  }, SPINNER_INTERVAL_MS);
+  if (typeof tickInterval.unref === 'function') tickInterval.unref();
+}
+
+function stopTick() {
+  if (!tickInterval) return;
+  clearInterval(tickInterval);
+  tickInterval = null;
+}
+
+/**
+ * Connect an `orbit` state machine instance to this status bar. Returns an
+ * unsubscribe function. The bar is mounted automatically; tear it down with
+ * `unmount()` or by calling the returned function (which also unmounts).
+ */
+export function attachOrbit(orbit) {
+  if (!orbit || typeof orbit.on !== 'function') return () => {};
+  if (!mount()) return () => {}; // non-TTY: silently ignore
+  const unsub = orbit.on('change', setOrbit);
+  // Initial paint
+  setOrbit(orbit.state());
+  return () => {
+    try { unsub(); } catch {}
+    unmount();
+  };
+}