@love-moon/tui-driver 0.2.0

package/src/driver/TuiProfile.ts

@@ -0,0 +1,72 @@
+export type TuiProfileName = "claude-code" | "codex";
+
+export interface TuiAnchors {
+  ready: RegExp[];
+  busy?: RegExp[];
+  error?: RegExp[];
+  trust?: RegExp[];
+}
+
+export interface TuiKeys {
+  submit: string[];
+  newChat?: string[];
+  cancel?: string[];
+  trustConfirm?: string[];
+}
+
+export interface TuiExtraction {
+  mode: "diff-viewport" | "diff-scrollback";
+  stripPatterns: RegExp[];
+  stripEcho?: boolean;
+  bottomUiLines?: number;
+  includeLinePatterns?: RegExp[];
+  stopLinePatterns?: RegExp[];
+}
+
+export interface TuiSignals {
+  prompt?: RegExp[];
+  promptHint?: RegExp[];
+  replyStart?: RegExp[];
+  replyStop?: RegExp[];
+  status?: RegExp[];
+  statusDone?: RegExp[];
+}
+
+export interface TuiProfile {
+  name: TuiProfileName;
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+  anchors: TuiAnchors;
+  keys: TuiKeys;
+  preflightKeys?: string[];
+  signals?: TuiSignals;
+  requireReplyStart?: boolean;
+  extraction: TuiExtraction;
+  cols?: number;
+  rows?: number;
+  scrollback?: number;
+  timeouts?: {
+    boot?: number;
+    ready?: number;
+    streamStart?: number;
+    streamEnd?: number;
+    idle?: number;
+  };
+}
+
+export function createProfile(partial: Partial<TuiProfile> & {
+  name: TuiProfileName;
+  command: string;
+  anchors: TuiAnchors;
+  keys: TuiKeys;
+  extraction: TuiExtraction;
+}): TuiProfile {
+  return {
+    args: [],
+    cols: 120,
+    rows: 40,
+    scrollback: 5000,
+    ...partial,
+  };
+}

package/src/driver/index.ts

@@ -0,0 +1,4 @@
+export { TuiDriver, TuiDriverOptions, AskResult, TuiScreenSignals } from "./TuiDriver.js";
+export { TuiProfile, TuiProfileName, TuiAnchors, TuiKeys, TuiExtraction, TuiSignals, createProfile } from "./TuiProfile.js";
+export { StateMachine, TuiState, StateTransition } from "./StateMachine.js";
+export { claudeCodeProfile, codexProfile } from "./profiles/index.js";

package/src/driver/profiles/claudeCode.profile.ts

@@ -0,0 +1,96 @@
+import { TuiProfile, createProfile } from "../TuiProfile.js";
+
+export const claudeCodeProfile: TuiProfile = createProfile({
+  name: "claude-code",
+  command: "claude",
+  args: [],
+  env: {
+    TERM: "xterm-256color",
+    LANG: "en_US.UTF-8",
+    LC_ALL: "en_US.UTF-8",
+  },
+
+  anchors: {
+    ready: [
+      /❯\s*$/m,                    // Empty prompt (ready for input)
+      /❯\s*(?!\d+\.)/m,            // Prompt line (avoid trust menu options)
+    ],
+    trust: [
+      /Accessing workspace:/i,
+      /Quick safety check/i,
+      /Yes, I trust this folder/i,
+    ],
+    busy: [
+      /⏺/,                         // Claude's streaming indicator
+      /Thinking/i,
+      /Working/i,
+    ],
+    error: [
+      /Error:/i,
+      /Failed to/i,
+      /Connection refused/i,
+      /Authentication failed/i,
+      /Rate limit/i,
+      /API.*error/i,
+    ],
+  },
+
+  keys: {
+    submit: ["ENTER"],
+    newChat: ["CTRL_L"],
+    cancel: ["CTRL_C"],
+  },
+
+  extraction: {
+    mode: "diff-scrollback",
+    includeLinePatterns: [
+      /^⏺\s(?!.*(tool|mcp|running|calling|call))/i,
+    ],
+    stopLinePatterns: [
+      /^❯\s*/m,
+    ],
+    stripPatterns: [
+      /^❯\s*/gm,                   // Prompt indicator
+      /^⏺\s*/gm,                   // Claude reply/tool indicator
+      /^\s*\d+\s*│/gm,             // Line numbers
+      /Press .* to/gi,
+      /\? for shortcuts/gi,        // Help hint
+      /────+/g,                    // Horizontal lines
+      /╭.*╮/g,                     // Box top
+      /╰.*╯/g,                     // Box bottom
+      /│.*│/g,                     // Box sides (be careful with this)
+    ],
+    stripEcho: true,
+    bottomUiLines: 4,
+  },
+
+  signals: {
+    prompt: [/^❯\s*/m],
+    promptHint: [/^❯\s+(?!\d+\.)\S+/m],
+    replyStart: [/^⏺\s(?!.*(tool|mcp|running|calling|call))/i],
+    replyStop: [/^❯\s*/m],
+    status: [
+      /^⏺\s.*(tool|mcp|running|calling|call)/i,
+      /^✻\s.*\(\d+s\s*•/i,  // Working status with updating time: "✻ ... (5s • esc to interrupt)"
+    ],
+    statusDone: [
+      /^✻\s.*for\s+\d+(\.\d+)?s/i,  // Final status with fixed time: "✻ Cooked for 33s"
+    ],
+  },
+
+  requireReplyStart: true,
+
+  cols: 120,
+  rows: 40,
+  scrollback: 5000,
+
+  timeouts: {
+    boot: 0,
+    ready: 0,
+    streamStart: 0,
+    streamEnd: 0,
+    idle: 1000,
+  },
+});
+
+export default claudeCodeProfile;

package/src/driver/profiles/codex.profile.ts

@@ -0,0 +1,87 @@
+import { TuiProfile, createProfile } from "../TuiProfile.js";
+
+export const codexProfile: TuiProfile = createProfile({
+  name: "codex",
+  command: "codex",
+  args: [],
+  env: {
+    TERM: "xterm-256color",
+    LANG: "en_US.UTF-8",
+    LC_ALL: "en_US.UTF-8",
+  },
+
+  anchors: {
+    ready: [
+      /[\s\S]*model:(?!\s*loading)[\s\S]*^›\s*/mi,
+      /^(?![\s\S]*model:\s*loading)(?![\s\S]*Press enter to continue)(?=[\s\S]*(?:^|\n)›\s*(?!\d+\.)[^\n]*)[\s\S]*$/i,
+    ],
+    trust: [
+      /You are running Codex in /i,
+      /Since this folder is not version controlled/i,
+      /Allow Codex to work in this folder without asking for approval/i,
+      /Require approval of edits and commands/i,
+      /Press enter to continue/i,
+    ],
+    busy: [
+      /^\s*•\s*(Working|Thinking)\b.*$/m,
+      /\b(Working|Thinking)\s*\(\d+s\s*•\s*esc to interrupt\)/i,
+    ],
+    error: [
+      /Error:/i,
+      /Failed/i,
+      /API.*error/i,
+    ],
+  },
+
+  keys: {
+    submit: ["ENTER"],
+    newChat: [],
+    cancel: ["CTRL_C"],
+    trustConfirm: ["UP", "ENTER"],
+  },
+
+  extraction: {
+    mode: "diff-scrollback",
+    includeLinePatterns: [
+      /^\s*•\s*(?!Working|Thinking).+/m,
+    ],
+    stopLinePatterns: [
+      /^\s*›\s*/m,
+    ],
+    stripPatterns: [
+      /^>\s*/gm,
+      /^\s*›\s*/gm,
+      /^\s*•\s*/gm,
+      /codex>\s*/gi,
+    ],
+    stripEcho: true,
+    bottomUiLines: 2,
+  },
+
+  signals: {
+    prompt: [/^\s*›\s*/m],
+    replyStart: [/^\s*•\s*(?!Working|Thinking).+/m],
+    replyStop: [/^\s*›\s*/m],
+    status: [
+      /^\s*•\s*(Working|Thinking)\b.*$/m,
+      /\b(Working|Thinking)\s*\(\d+s\s*•\s*esc to interrupt\)/i,
+    ],
+    statusDone: [/^\s*─\s*Worked for .*─+/m, /\bWorked for\b.*$/i],
+  },
+
+  requireReplyStart: true,
+
+  cols: 120,
+  rows: 40,
+  scrollback: 5000,
+
+  timeouts: {
+    boot: 0,
+    ready: 0,
+    streamStart: 0,
+    streamEnd: 0,
+    idle: 1200,
+  },
+});
+
+export default codexProfile;

package/src/driver/profiles/index.ts

@@ -0,0 +1,2 @@
+export { claudeCodeProfile } from "./claudeCode.profile.js";
+export { codexProfile } from "./codex.profile.js";

package/src/example.ts

@@ -0,0 +1,45 @@
+import { createDriver, TuiDriver, claudeCodeProfile } from "./index.js";
+
+async function main() {
+  // Method 1: Using the convenience factory
+  const driver1 = createDriver("claude-code", { debug: true });
+
+  // Method 2: Using TuiDriver directly with a profile
+  const driver2 = new TuiDriver({
+    profile: claudeCodeProfile,
+    debug: true,
+    onSnapshot: (snapshot, state) => {
+      console.log(`[${state}] Screen hash: ${snapshot.hash}`);
+    },
+  });
+
+  try {
+    // Boot the TUI
+    await driver2.boot();
+    console.log("TUI booted successfully");
+
+    // Ask a question
+    const result = await driver2.ask("What is 2 + 2?");
+
+    if (result.success) {
+      console.log("Answer:", result.answer);
+      console.log("Elapsed:", result.elapsedMs, "ms");
+    } else {
+      console.error("Failed:", result.error?.message);
+    }
+
+    // Ask another question
+    const result2 = await driver2.ask("Explain briefly what TypeScript is.");
+
+    if (result2.success) {
+      console.log("Answer:", result2.answer);
+    }
+  } catch (error) {
+    console.error("Error:", error);
+  } finally {
+    // Clean up
+    driver2.kill();
+  }
+}
+
+main().catch(console.error);

package/src/expect/ExpectEngine.ts

@@ -0,0 +1,171 @@
+import { HeadlessScreen } from "../term/HeadlessScreen.js";
+import { ScreenSnapshot } from "../term/ScreenSnapshot.js";
+import { MatcherFn } from "./Matchers.js";
+
+export interface UntilOptions {
+  name: string;
+  match: MatcherFn;
+  stableMs?: number;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  onTimeout?: () => void | Promise<void>;
+}
+
+export interface IdleOptions {
+  name: string;
+  idleMs: number;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  onTimeout?: () => void | Promise<void>;
+}
+
+export interface ExpectResult {
+  success: boolean;
+  snapshot: ScreenSnapshot;
+  elapsedMs: number;
+  timedOut: boolean;
+}
+
+const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+const DEFAULT_STABLE_MS = 300;
+
+export class ExpectEngine {
+  constructor(private screen: HeadlessScreen) {}
+
+  async until(options: UntilOptions): Promise<ExpectResult> {
+    const {
+      match,
+      stableMs = DEFAULT_STABLE_MS,
+      timeoutMs = DEFAULT_TIMEOUT_MS,
+      pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+      onTimeout,
+    } = options;
+
+    const startTime = Date.now();
+    let matchStartTime: number | null = null;
+    let lastSnapshot: ScreenSnapshot = this.screen.snapshot();
+
+    while (true) {
+      const elapsed = Date.now() - startTime;
+
+      if (elapsed >= timeoutMs) {
+        if (onTimeout) {
+          await onTimeout();
+        }
+        return {
+          success: false,
+          snapshot: lastSnapshot,
+          elapsedMs: elapsed,
+          timedOut: true,
+        };
+      }
+
+      lastSnapshot = this.screen.snapshot();
+      const matched = match(lastSnapshot);
+
+      if (matched) {
+        if (matchStartTime === null) {
+          matchStartTime = Date.now();
+        } else if (Date.now() - matchStartTime >= stableMs) {
+          return {
+            success: true,
+            snapshot: lastSnapshot,
+            elapsedMs: Date.now() - startTime,
+            timedOut: false,
+          };
+        }
+      } else {
+        matchStartTime = null;
+      }
+
+      await this.sleep(pollIntervalMs);
+    }
+  }
+
+  async untilIdle(options: IdleOptions): Promise<ExpectResult> {
+    const {
+      idleMs,
+      timeoutMs = DEFAULT_TIMEOUT_MS,
+      pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+      onTimeout,
+    } = options;
+
+    const startTime = Date.now();
+    let lastHash = this.screen.snapshot().hash;
+    let lastChangeTime = Date.now();
+    let lastSnapshot: ScreenSnapshot = this.screen.snapshot();
+
+    while (true) {
+      const elapsed = Date.now() - startTime;
+
+      if (elapsed >= timeoutMs) {
+        if (onTimeout) {
+          await onTimeout();
+        }
+        return {
+          success: false,
+          snapshot: lastSnapshot,
+          elapsedMs: elapsed,
+          timedOut: true,
+        };
+      }
+
+      lastSnapshot = this.screen.snapshot();
+      const currentHash = lastSnapshot.hash;
+
+      if (currentHash !== lastHash) {
+        lastHash = currentHash;
+        lastChangeTime = Date.now();
+      } else if (Date.now() - lastChangeTime >= idleMs) {
+        return {
+          success: true,
+          snapshot: lastSnapshot,
+          elapsedMs: Date.now() - startTime,
+          timedOut: false,
+        };
+      }
+
+      await this.sleep(pollIntervalMs);
+    }
+  }
+
+  async waitForChange(timeoutMs: number = DEFAULT_TIMEOUT_MS): Promise<ExpectResult> {
+    const startTime = Date.now();
+    const initialHash = this.screen.snapshot().hash;
+    let lastSnapshot: ScreenSnapshot = this.screen.snapshot();
+
+    while (true) {
+      const elapsed = Date.now() - startTime;
+
+      if (elapsed >= timeoutMs) {
+        return {
+          success: false,
+          snapshot: lastSnapshot,
+          elapsedMs: elapsed,
+          timedOut: true,
+        };
+      }
+
+      lastSnapshot = this.screen.snapshot();
+      if (lastSnapshot.hash !== initialHash) {
+        return {
+          success: true,
+          snapshot: lastSnapshot,
+          elapsedMs: Date.now() - startTime,
+          timedOut: false,
+        };
+      }
+
+      await this.sleep(DEFAULT_POLL_INTERVAL_MS);
+    }
+  }
+
+  snapshot(): ScreenSnapshot {
+    return this.screen.snapshot();
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/expect/Matchers.ts

@@ -0,0 +1,92 @@
+import { ScreenSnapshot } from "../term/ScreenSnapshot.js";
+
+export type MatcherFn = (snapshot: ScreenSnapshot) => boolean;
+
+export interface MatcherResult {
+  matched: boolean;
+  matchedPattern?: RegExp;
+  matchedText?: string;
+}
+
+export class Matchers {
+  static regex(pattern: RegExp, region: "viewport" | "scrollback" = "viewport"): MatcherFn {
+    return (snapshot: ScreenSnapshot) => snapshot.matchesPattern(pattern, region);
+  }
+
+  static anyOf(patterns: RegExp[], region: "viewport" | "scrollback" = "viewport"): MatcherFn {
+    return (snapshot: ScreenSnapshot) => {
+      const text = region === "viewport" ? snapshot.viewportText : snapshot.scrollbackText;
+      return patterns.some(p => p.test(text));
+    };
+  }
+
+  static allOf(patterns: RegExp[], region: "viewport" | "scrollback" = "viewport"): MatcherFn {
+    return (snapshot: ScreenSnapshot) => {
+      const text = region === "viewport" ? snapshot.viewportText : snapshot.scrollbackText;
+      return patterns.every(p => p.test(text));
+    };
+  }
+
+  static noneOf(patterns: RegExp[], region: "viewport" | "scrollback" = "viewport"): MatcherFn {
+    return (snapshot: ScreenSnapshot) => {
+      const text = region === "viewport" ? snapshot.viewportText : snapshot.scrollbackText;
+      return !patterns.some(p => p.test(text));
+    };
+  }
+
+  static cursorAt(x: number, y: number): MatcherFn {
+    return (snapshot: ScreenSnapshot) => {
+      return snapshot.cursor.x === x && snapshot.cursor.y === y;
+    };
+  }
+
+  static cursorInRegion(
+    minX: number, maxX: number,
+    minY: number, maxY: number
+  ): MatcherFn {
+    return (snapshot: ScreenSnapshot) => {
+      const { x, y } = snapshot.cursor;
+      return x >= minX && x <= maxX && y >= minY && y <= maxY;
+    };
+  }
+
+  static bottomRegion(pattern: RegExp, bottomLines: number = 5): MatcherFn {
+    return (snapshot: ScreenSnapshot) => {
+      const lines = snapshot.getViewportLines();
+      const bottom = lines.slice(-bottomLines).join("\n");
+      return pattern.test(bottom);
+    };
+  }
+
+  static topRegion(pattern: RegExp, topLines: number = 5): MatcherFn {
+    return (snapshot: ScreenSnapshot) => {
+      const lines = snapshot.getViewportLines();
+      const top = lines.slice(0, topLines).join("\n");
+      return pattern.test(top);
+    };
+  }
+
+  static hashChanged(previousHash: string): MatcherFn {
+    return (snapshot: ScreenSnapshot) => snapshot.hash !== previousHash;
+  }
+
+  static hashUnchanged(previousHash: string): MatcherFn {
+    return (snapshot: ScreenSnapshot) => snapshot.hash === previousHash;
+  }
+
+  static and(...matchers: MatcherFn[]): MatcherFn {
+    return (snapshot: ScreenSnapshot) => matchers.every(m => m(snapshot));
+  }
+
+  static or(...matchers: MatcherFn[]): MatcherFn {
+    return (snapshot: ScreenSnapshot) => matchers.some(m => m(snapshot));
+  }
+
+  static not(matcher: MatcherFn): MatcherFn {
+    return (snapshot: ScreenSnapshot) => !matcher(snapshot);
+  }
+
+  static custom(fn: (snapshot: ScreenSnapshot) => boolean): MatcherFn {
+    return fn;
+  }
+}

package/src/expect/index.ts

@@ -0,0 +1,2 @@
+export { ExpectEngine, UntilOptions, IdleOptions, ExpectResult } from "./ExpectEngine.js";
+export { Matchers, MatcherFn, MatcherResult } from "./Matchers.js";

package/src/extract/Diff.ts

@@ -0,0 +1,51 @@
+import diff from "fast-diff";
+
+export interface DiffResult {
+  added: string[];
+  removed: string[];
+  unchanged: string[];
+}
+
+export function computeLineDiff(before: string, after: string): DiffResult {
+  const beforeLines = before.split("\n");
+  const afterLines = after.split("\n");
+
+  const beforeSet = new Set(beforeLines);
+  const afterSet = new Set(afterLines);
+
+  const added = afterLines.filter(line => !beforeSet.has(line));
+  const removed = beforeLines.filter(line => !afterSet.has(line));
+  const unchanged = afterLines.filter(line => beforeSet.has(line));
+
+  return { added, removed, unchanged };
+}
+
+export function computeCharDiff(before: string, after: string): Array<[number, string]> {
+  return diff(before, after);
+}
+
+export function getAddedText(before: string, after: string): string {
+  const result = diff(before, after);
+  const added: string[] = [];
+
+  for (const [type, text] of result) {
+    if (type === 1) {
+      added.push(text);
+    }
+  }
+
+  return added.join("");
+}
+
+export function getRemovedText(before: string, after: string): string {
+  const result = diff(before, after);
+  const removed: string[] = [];
+
+  for (const [type, text] of result) {
+    if (type === -1) {
+      removed.push(text);
+    }
+  }
+
+  return removed.join("");
+}