jeo-code 0.1.0

package/src/tui/components/select-list.ts

@@ -0,0 +1,199 @@
+/**
+ * Generic keyboard-navigable selection list for the TUI (model/provider pickers).
+ *
+ * Split into a pure state machine (`SelectList`) and a pure renderer
+ * (`renderSelectList`) so the picker logic is fully unit-testable without a real
+ * TTY. The renderer is viewport-aware: it shows a scrolling window of `rows`
+ * around the cursor and fits each line to `cols`, so long lists never overflow
+ * the terminal height/width.
+ */
+import chalk from "chalk";
+import { padLineTo } from "./layout";
+import { visibleWidth } from "./color";
+
+export interface SelectItem<T> {
+  value: T;
+  label: string;
+  /** Optional group header shown above the first item of each group. */
+  group?: string;
+  /** Disabled items are shown dimmed and skipped by cursor navigation. */
+  disabled?: boolean;
+  /** Optional right-aligned hint/badge (e.g. "✓ ready · 200k"). */
+  hint?: string;
+}
+
+export class SelectList<T> {
+  private readonly items: SelectItem<T>[];
+  private query = "";
+  private cursor = 0; // index into the *visible* list
+
+  constructor(items: SelectItem<T>[]) {
+    this.items = items;
+    this.cursor = this.firstEnabled(this.computeVisible());
+  }
+
+  /** Items matching the current filter (case-insensitive substring on label). */
+  visible(): SelectItem<T>[] {
+    return this.computeVisible();
+  }
+
+  private computeVisible(): SelectItem<T>[] {
+    const q = this.query.trim().toLowerCase();
+    if (!q) return this.items;
+    return this.items.filter(i => i.label.toLowerCase().includes(q) || (i.group ?? "").toLowerCase().includes(q));
+  }
+
+  private firstEnabled(list: SelectItem<T>[]): number {
+    const i = list.findIndex(it => !it.disabled);
+    return i < 0 ? 0 : i;
+  }
+
+  /** Current cursor index within the visible list (clamped). */
+  cursorIndex(): number {
+    const n = this.computeVisible().length;
+    if (n === 0) return 0;
+    return Math.max(0, Math.min(this.cursor, n - 1));
+  }
+
+  isEmpty(): boolean {
+    return this.computeVisible().length === 0;
+  }
+
+  /** The currently selected item (skips when empty / all disabled). */
+  selected(): SelectItem<T> | undefined {
+    const list = this.computeVisible();
+    const item = list[this.cursorIndex()];
+    return item && !item.disabled ? item : undefined;
+  }
+
+  /** Set the filter query; cursor jumps to the first enabled match. */
+  setFilter(query: string): void {
+    this.query = query;
+    this.cursor = this.firstEnabled(this.computeVisible());
+  }
+
+  filter(): string {
+    return this.query;
+  }
+
+  /** Append a character to the filter (typing). */
+  typeChar(ch: string): void {
+    this.setFilter(this.query + ch);
+  }
+
+  /** Remove the last filter character (backspace). */
+  backspace(): void {
+    this.setFilter(this.query.slice(0, -1));
+  }
+
+  private step(dir: 1 | -1): void {
+    const list = this.computeVisible();
+    const n = list.length;
+    if (n === 0) return;
+    let i = this.cursorIndex();
+    for (let tries = 0; tries < n; tries++) {
+      i = (i + dir + n) % n;
+      if (!list[i]!.disabled) break;
+    }
+    this.cursor = i;
+  }
+
+  up(): void {
+    this.step(-1);
+  }
+  down(): void {
+    this.step(1);
+  }
+
+  /** Move by a page (clamped, no wrap), landing on an enabled item. */
+  page(dir: 1 | -1, size = 5): void {
+    const list = this.computeVisible();
+    const n = list.length;
+    if (n === 0) return;
+    let i = Math.max(0, Math.min(n - 1, this.cursorIndex() + dir * Math.max(1, size)));
+    // settle onto the nearest enabled item in the travel direction
+    while (i >= 0 && i < n && list[i]!.disabled) i += dir;
+    if (i < 0 || i >= n) i = this.firstEnabled(list);
+    this.cursor = i;
+  }
+}
+
+export interface RenderSelectOptions {
+  /** Title line shown above the list. */
+  title?: string;
+  /** Max body rows for the scrolling window (default 10). */
+  rows?: number;
+  /** Total width to fit each line to (default: natural). */
+  cols?: number;
+  /** Use unicode glyphs for the cursor/markers (default true). */
+  unicode?: boolean;
+  /** Apply chalk color (default true). */
+  color?: boolean;
+}
+
+/**
+ * Render a `SelectList` to lines: optional title, a scrolling window of items
+ * with the cursor highlighted, group headers, right-aligned hints, and a footer
+ * with the active filter + key hints. Pure — no I/O.
+ */
+export function renderSelectList<T>(list: SelectList<T>, opts: RenderSelectOptions = {}): string[] {
+  const unicode = opts.unicode !== false;
+  const color = opts.color !== false;
+  const rows = Math.max(1, opts.rows ?? 10);
+  const cols = opts.cols;
+  const pointer = unicode ? "\u276f" : ">"; // ❯ / >
+  const tint = (s: string, fn: (x: string) => string) => (color ? fn(s) : s);
+
+  const out: string[] = [];
+  if (opts.title) out.push(tint(opts.title, chalk.bold));
+
+  const items = list.visible();
+  if (items.length === 0) {
+    out.push(tint("  (no matches)", chalk.gray));
+  } else {
+    const cur = list.cursorIndex();
+    // Scrolling window centered-ish on the cursor.
+    let start = Math.max(0, cur - Math.floor(rows / 2));
+    start = Math.min(start, Math.max(0, items.length - rows));
+    const end = Math.min(items.length, start + rows);
+
+    if (start > 0) out.push(tint(`  \u2191 ${start} more`, chalk.gray));
+    let lastGroup: string | undefined;
+    for (let i = start; i < end; i++) {
+      const it = items[i]!;
+      if (it.group && it.group !== lastGroup) {
+        out.push(tint(`  ${it.group}`, chalk.gray));
+        lastGroup = it.group;
+      }
+      const isCur = i === cur;
+      const marker = isCur ? tint(pointer, chalk.cyan) : " ";
+      let label = it.disabled ? tint(it.label, chalk.gray) : isCur ? tint(it.label, chalk.cyan.bold) : it.label;
+      let line = `${marker} ${label}`;
+      if (it.hint) {
+        const hint = tint(it.hint, chalk.gray);
+        if (cols) {
+          // right-align the hint within cols
+          const used = visibleWidth(line) + visibleWidth(hint) + 1;
+          const gap = Math.max(1, cols - used);
+          line = `${line}${" ".repeat(gap)}${hint}`;
+        } else {
+          line = `${line}  ${hint}`;
+        }
+      }
+      out.push(cols ? clampToCols(line, cols) : line);
+    }
+    if (end < items.length) out.push(tint(`  \u2193 ${items.length - end} more`, chalk.gray));
+  }
+
+  const q = list.filter();
+  const filterPart = q ? `filter: ${q}` : "type to filter";
+  const keys = unicode ? "\u2191/\u2193 move \u00b7 enter select \u00b7 esc cancel" : "up/down move . enter select . esc cancel";
+  out.push(tint(`  ${filterPart}  \u2014  ${keys}`, chalk.gray));
+  return out;
+}
+
+/** Fit a (possibly colored) line to cols by visible width, preserving the right hint. */
+function clampToCols(line: string, cols: number): string {
+  if (visibleWidth(line) <= cols) return padLineTo(line, cols, "left");
+  return line; // caller-built hint lines are already gap-fitted; leave longer plain lines to the renderer truncate
+}

package/src/tui/components/slash.ts

@@ -0,0 +1,34 @@
+/** Slash-command palette/autocomplete for the interactive REPL (TUI M3). */
+
+export const SLASH_COMMANDS = [
+  "/help",
+  "/clear",
+  "/compact",
+  "/model",
+  "/models",
+  "/provider",
+  "/agents",
+  "/config",
+  "/roles",
+  "/thinking",
+  "/view",
+  "/diff",
+  "/find",
+  "/search",
+  "/sessions",
+  "/evolve",
+  "/exit",
+  "/quit",
+];
+
+/** Return the slash commands that prefix-match `input` (case-insensitive). Empty for non-slash input. */
+export function matchSlash(input: string, commands: string[] = SLASH_COMMANDS): string[] {
+  if (!input.startsWith("/")) return [];
+  const q = input.toLowerCase();
+  return commands.filter(c => c.startsWith(q));
+}
+
+/** True when `input` looks like a slash command (starts with "/" and has no space). */
+export function isSlashAttempt(input: string): boolean {
+  return input.startsWith("/") && !input.slice(1).includes(" ");
+}

package/src/tui/components/spinner.ts

@@ -0,0 +1,49 @@
+import { spinnerFramesFor, stageIndexForStep, clampStageIndex } from "./evolution";
+
+/**
+ * Stage-aware spinner. Frames evolve with the agent's step against its budget,
+ * sourced from the canonical evolution model so the spinner stays in lockstep
+ * with the ASCII art, meter, and footer track.
+ */
+export class Spinner {
+  private defaultFrames: string[];
+  private frames: string[];
+  private index: number = 0;
+  private unicode: boolean;
+
+  constructor(frames?: string[], opts: { unicode?: boolean } = {}) {
+    this.unicode = opts.unicode !== false;
+    // Default to the "AI Coding Agent" stage frames when none are supplied.
+    this.defaultFrames = frames || spinnerFramesFor(3, this.unicode);
+    this.frames = this.defaultFrames;
+  }
+
+  /** Switch frame set to the stage matching `step`/`maxSteps`. */
+  updateStep(step: number, maxSteps: number = 25): void {
+    const idx = stageIndexForStep(step, maxSteps);
+    this.setStage(idx);
+  }
+
+  /** Switch frame set to an explicit stage index (clamped). */
+  setStage(stageIndex: number): void {
+    this.frames = spinnerFramesFor(clampStageIndex(stageIndex), this.unicode);
+    // Keep the animation phase valid when the frame count shrinks.
+    this.index = this.frames.length ? this.index % this.frames.length : 0;
+  }
+
+  /** Reset to the default frame set and phase. */
+  reset(): void {
+    this.frames = this.defaultFrames;
+    this.index = 0;
+  }
+
+  next(): string {
+    const frame = this.frames[this.index]!;
+    this.index = (this.index + 1) % this.frames.length;
+    return frame;
+  }
+
+  current(): string {
+    return this.frames[this.index]!;
+  }
+}

package/src/tui/components/status.ts

@@ -0,0 +1,45 @@
+import chalk from "chalk";
+import { meter } from "./meter";
+
+export interface JocStatusData {
+  step?: number;
+  maxSteps?: number;
+  elapsedMs?: number;
+  message?: string;
+  currentTool?: string;
+  okCount?: number;
+  failCount?: number;
+  runningCount?: number;
+  totalCount?: number;
+  mutationGuarded?: boolean;
+  unicode?: boolean;
+}
+
+export function progressPercent(step: number | undefined, maxSteps: number | undefined): number {
+  if (!Number.isFinite(step) || !Number.isFinite(maxSteps) || (maxSteps ?? 0) <= 0) return 0;
+  return Math.max(0, Math.min(100, Math.round(((step ?? 0) / (maxSteps ?? 1)) * 100)));
+}
+
+function seconds(ms: number | undefined): number {
+  return Number.isFinite(ms) && (ms ?? 0) > 0 ? Math.round((ms ?? 0) / 1000) : 0;
+}
+
+export function renderJocStatus(data: JocStatusData): string[] {
+  const step = Number.isFinite(data.step) ? Math.max(0, Math.trunc(data.step ?? 0)) : 0;
+  const max = Number.isFinite(data.maxSteps) && (data.maxSteps ?? 0) > 0 ? Math.trunc(data.maxSteps ?? 0) : 0;
+  const pct = progressPercent(step, max);
+  const bar = meter(step, max || 1, 10, { unicode: data.unicode !== false });
+  const elapsed = `${seconds(data.elapsedMs)}s`;
+  const msg = data.message ?? "thinking through the next tool call";
+  const current = data.currentTool ? `forging ${data.currentTool}` : "forge idle";
+  const ok = data.okCount ?? 0;
+  const fail = data.failCount ?? 0;
+  const running = data.runningCount ?? 0;
+  const total = data.totalCount ?? ok + fail + running;
+  const guard = data.mutationGuarded ? ` · ${chalk.red.bold("mutation locked")}` : "";
+
+  return [
+    `  ${chalk.cyan.bold("joc thinking")} · ${msg} · step ${step}/${max} · ${pct}% ${bar} · ${elapsed}`,
+    `  ${chalk.magenta.bold("joc forge")} · ${current} · tools ${total} (${ok} ok / ${fail} fail / ${running} running)${guard}`,
+  ];
+}

package/src/tui/components/stream.ts

@@ -0,0 +1,36 @@
+export class StreamRegion {
+  private buffer: string = "";
+
+  append(text: string): void {
+    this.buffer += text;
+  }
+
+  render(width: number, maxLines?: number): string[] {
+    if (this.buffer === "") {
+      return [];
+    }
+
+    const cols = Math.max(1, width);
+    const segments = this.buffer.split("\n");
+    const result: string[] = [];
+
+    for (const segment of segments) {
+      if (segment === "") {
+        result.push("");
+      } else {
+        for (let i = 0; i < segment.length; i += cols) {
+          result.push(segment.slice(i, i + cols));
+        }
+      }
+    }
+
+    if (maxLines !== undefined && maxLines > 0 && result.length > maxLines) {
+      return result.slice(result.length - maxLines);
+    }
+    return result;
+  }
+
+  clear(): void {
+    this.buffer = "";
+  }
+}

package/src/tui/components/themes.ts

@@ -0,0 +1,86 @@
+/**
+ * Evolution TUI themes — selectable palettes for the five-stage identity.
+ *
+ * A theme only re-skins the *colors* (per-stage gradient palettes) and whether
+ * color is emitted at all. The stage model, art, spinner, meter glyphs, and
+ * track structure are theme-independent, so switching a theme never changes
+ * layout — only the look. `cosmic` is the default; `mono` is the colorless
+ * fallback for plain terminals.
+ */
+import { EVOLUTION_STAGE_GRADIENTS, EVOLUTION_STAGE_COUNT, type StageGradient } from "./evolution";
+import { clampStageIndex } from "./evolution";
+import type { EnvLike } from "./color";
+
+export interface EvolutionTheme {
+  name: string;
+  description: string;
+  /** Per-stage gradient palettes (index-aligned, length EVOLUTION_STAGE_COUNT). */
+  gradients: readonly StageGradient[];
+  /** Whether the theme emits color at all (`mono` = false → plain output). */
+  color: boolean;
+}
+
+const COSMIC: EvolutionTheme = {
+  name: "cosmic",
+  description: "Default — deep-space arc from cyan tide to white-hot singularity.",
+  gradients: EVOLUTION_STAGE_GRADIENTS,
+  color: true,
+};
+
+const MATRIX: EvolutionTheme = {
+  name: "matrix",
+  description: "Terminal green — every stage glows in shades of phosphor green.",
+  gradients: [
+    { from: "#003b00", to: "#00ff41" },
+    { from: "#005f00", to: "#39ff14" },
+    { from: "#008f11", to: "#7fff00" },
+    { from: "#00b300", to: "#aaff00" },
+    { from: "#00ff41", to: "#ccffcc" },
+  ],
+  color: true,
+};
+
+const SOLAR: EvolutionTheme = {
+  name: "solar",
+  description: "Warm star — embers to corona, red through gold to white.",
+  gradients: [
+    { from: "#7a1f00", to: "#ff6b00" },
+    { from: "#a83200", to: "#ff8c00" },
+    { from: "#d35400", to: "#ffb700" },
+    { from: "#e67e22", to: "#ffd24a" },
+    { from: "#ff8c00", to: "#fff5cc" },
+  ],
+  color: true,
+};
+
+const MONO: EvolutionTheme = {
+  name: "mono",
+  description: "Colorless — plain text for NO_COLOR / minimal terminals.",
+  gradients: EVOLUTION_STAGE_GRADIENTS,
+  color: false,
+};
+
+export const THEMES: readonly EvolutionTheme[] = [COSMIC, MATRIX, SOLAR, MONO];
+
+/** Look up a theme by name (case-insensitive); unknown names fall back to cosmic. */
+export function getTheme(name: string | undefined): EvolutionTheme {
+  if (!name) return COSMIC;
+  const lc = name.trim().toLowerCase();
+  return THEMES.find(t => t.name === lc) ?? COSMIC;
+}
+
+/** Theme names + descriptions for `joc evolve --list-themes`. */
+export function listThemes(): { name: string; description: string }[] {
+  return THEMES.map(t => ({ name: t.name, description: t.description }));
+}
+
+/** Resolve the active theme from the environment (`JOC_TUI_THEME`), default cosmic. */
+export function resolveTheme(env: EnvLike = process.env): EvolutionTheme {
+  return getTheme(env.JOC_TUI_THEME);
+}
+
+/** The gradient palette for a stage index under a theme (clamped). */
+export function themeGradient(theme: EvolutionTheme, index: number): StageGradient {
+  const i = clampStageIndex(index);
+  return theme.gradients[i] ?? theme.gradients[EVOLUTION_STAGE_COUNT - 1]!;
+}

package/src/tui/components/tool-list.ts

@@ -0,0 +1,67 @@
+import chalk from "chalk";
+
+export type ToolStatus = "running" | "ok" | "fail";
+
+interface ToolRow {
+  tool: string;
+  status: ToolStatus;
+}
+export interface ToolStats {
+  running: number;
+  ok: number;
+  fail: number;
+  total: number;
+}
+
+
+export class ToolList {
+  private rows: ToolRow[] = [];
+
+  start(tool: string): number {
+    this.rows.push({ tool, status: "running" });
+    return this.rows.length - 1;
+  }
+
+  finish(index: number, ok: boolean): void {
+    if (this.rows[index]) {
+      this.rows[index].status = ok ? "ok" : "fail";
+    }
+  }
+
+  render(maxRows?: number): string[] {
+    const rows =
+      maxRows !== undefined && maxRows > 0 && this.rows.length > maxRows
+        ? this.rows.slice(this.rows.length - (maxRows - 1)) // keep the most recent rows
+        : this.rows;
+    const hidden = this.rows.length - rows.length;
+    const lines = rows.map(row => {
+      if (row.status === "running") {
+        return `  ${chalk.yellow("·")} ${row.tool} ${chalk.yellow.bold("running...")}`;
+      } else if (row.status === "ok") {
+        // Faded decay for completed successful tools
+        return chalk.gray(`  · ${row.tool} ok`);
+      } else {
+        // Bright red for failures
+        return `  ${chalk.red("·")} ${row.tool} ${chalk.red.bold("FAILED")}`;
+      }
+    });
+    if (hidden > 0) {
+      lines.unshift(chalk.gray(`  · (+${hidden} earlier)`));
+    }
+    return lines;
+  }
+
+  currentTool(): string | undefined {
+    return [...this.rows].reverse().find(row => row.status === "running")?.tool;
+  }
+
+  stats(): ToolStats {
+    const stats: ToolStats = { running: 0, ok: 0, fail: 0, total: this.rows.length };
+    for (const row of this.rows) stats[row.status]++;
+    return stats;
+  }
+
+  reset(): void {
+    this.rows = [];
+  }
+}

package/src/tui/index.ts

@@ -0,0 +1,2 @@
+export * from "./terminal";
+export * from "./renderer";

package/src/tui/renderer.ts

@@ -0,0 +1,70 @@
+import { cursorDown, cursorUp, toColumn, clearLine, clearToEnd, size, truncate } from "./terminal";
+
+export type Writer = (s: string) => void;
+
+export class Renderer {
+  private write: Writer;
+  private cols: () => number;
+  private prev: string[] = [];
+  private prevCols?: number;
+
+  constructor(write?: Writer, cols?: () => number) {
+    this.write = write || ((s: string) => process.stdout.write(s));
+    this.cols = cols || (() => size().cols);
+  }
+
+  render(lines: string[]): void {
+    const currentCols = this.cols();
+    if (this.prevCols !== undefined && this.prevCols !== currentCols) {
+      this.clear();
+    }
+    this.prevCols = currentCols;
+
+    const next = lines.map(line => truncate(line, currentCols));
+    const maxLen = Math.max(this.prev.length, next.length);
+    let cursorRow = 0;
+    let out = "";
+
+    for (let i = 0; i < maxLen; i++) {
+      if (i < next.length) {
+        if (next[i] !== this.prev[i]) {
+          if (i > cursorRow) {
+            out += cursorDown(i - cursorRow);
+          } else if (i < cursorRow) {
+            out += cursorUp(cursorRow - i);
+          }
+          cursorRow = i;
+          out += toColumn(1) + clearLine() + next[i];
+        }
+      } else {
+        if (i > cursorRow) {
+          out += cursorDown(i - cursorRow);
+        } else if (i < cursorRow) {
+          out += cursorUp(cursorRow - i);
+        }
+        cursorRow = i;
+        out += toColumn(1) + clearLine();
+      }
+    }
+
+    if (cursorRow > 0) {
+      out += cursorUp(cursorRow);
+    }
+    out += toColumn(1);
+
+    if (out.length > 0) {
+      this.write(out);
+    }
+
+    this.prev = next;
+  }
+
+  clear(): void {
+    this.write(toColumn(1) + clearToEnd());
+    this.prev = [];
+  }
+
+  reset(): void {
+    this.prev = [];
+  }
+}

package/src/tui/terminal.ts

@@ -0,0 +1,78 @@
+export const ESC = "\x1b[";
+
+export function cursorUp(n: number): string {
+  return n > 0 ? `${ESC}${n}A` : "";
+}
+
+export function cursorDown(n: number): string {
+  return n > 0 ? `${ESC}${n}B` : "";
+}
+
+export function toColumn(col: number): string {
+  return `${ESC}${col}G`;
+}
+
+export function clearLine(): string {
+  return `${ESC}2K`;
+}
+
+export function clearToEnd(): string {
+  return `${ESC}0J`;
+}
+
+export function hideCursor(): string {
+  return `${ESC}?25l`;
+}
+
+export function showCursor(): string {
+  return `${ESC}?25h`;
+}
+
+export function size(): { cols: number; rows: number } {
+  return {
+    cols: process.stdout.columns || 80,
+    rows: process.stdout.rows || 24,
+  };
+}
+
+export function isTTY(): boolean {
+  return !!process.stdout.isTTY;
+}
+
+/**
+ * Truncate a line to `cols` *visible* columns. SGR color escapes are copied
+ * verbatim and do NOT count toward the width, so a colored line is never cut
+ * mid-escape (which would spill raw `\x1b[…` bytes onto the screen). If the line
+ * is cut while a color is active, a reset (`\x1b[0m`) is appended so trailing
+ * frame content is not tinted by a dangling color.
+ */
+export function truncate(line: string, cols: number): string {
+  const limit = Math.max(0, cols);
+  // Fast path: no escapes → plain slice by length.
+  if (!line.includes("\x1b")) {
+    return line.length <= limit ? line : line.slice(0, limit);
+  }
+  let out = "";
+  let visible = 0;
+  let sawEscape = false;
+  let i = 0;
+  while (i < line.length) {
+    if (line[i] === "\x1b") {
+      const m = /^\x1b\[[0-9;]*m/.exec(line.slice(i));
+      if (m) {
+        out += m[0];
+        sawEscape = true;
+        i += m[0].length;
+        continue;
+      }
+    }
+    if (visible >= limit) break;
+    out += line[i];
+    visible++;
+    i++;
+  }
+  if (i < line.length && sawEscape && !out.endsWith("\x1b[0m")) {
+    out += "\x1b[0m";
+  }
+  return out;
+}