@love-moon/tui-driver 0.2.0

package/src/extract/OutputExtractor.ts

@@ -0,0 +1,88 @@
+import { ScreenSnapshot } from "../term/ScreenSnapshot.js";
+import { TuiExtraction } from "../driver/TuiProfile.js";
+import { computeLineDiff, getAddedText } from "./Diff.js";
+
+export interface ExtractionResult {
+  text: string;
+  rawText: string;
+  linesAdded: number;
+}
+
+export class OutputExtractor {
+  constructor(private extraction: TuiExtraction) {}
+
+  extract(before: ScreenSnapshot, after: ScreenSnapshot): ExtractionResult {
+    let rawText: string;
+
+    if (this.extraction.mode === "diff-viewport") {
+      rawText = this.extractFromViewport(before, after);
+    } else {
+      rawText = this.extractFromScrollback(before, after);
+    }
+
+    const text = this.cleanText(rawText);
+
+    return {
+      text,
+      rawText,
+      linesAdded: text.split("\n").length,
+    };
+  }
+
+  private extractFromViewport(before: ScreenSnapshot, after: ScreenSnapshot): string {
+    const bottomLines = this.extraction.bottomUiLines ?? 3;
+    const afterText = after.getViewportWithoutBottom(bottomLines);
+    const beforeText = before.getViewportWithoutBottom(bottomLines);
+
+    return getAddedText(beforeText, afterText);
+  }
+
+  private extractFromScrollback(before: ScreenSnapshot, after: ScreenSnapshot): string {
+    const { added } = computeLineDiff(before.scrollbackText, after.scrollbackText);
+    return added.join("\n");
+  }
+
+  private cleanText(text: string): string {
+    let result = text;
+    const includeLinePatterns = this.extraction.includeLinePatterns;
+    const stopLinePatterns = this.extraction.stopLinePatterns ?? [];
+
+    if (includeLinePatterns && includeLinePatterns.length > 0) {
+      const lines = result.split("\n");
+      const kept: string[] = [];
+      let including = false;
+
+      for (const line of lines) {
+        if (includeLinePatterns.some(pattern => pattern.test(line))) {
+          including = true;
+          kept.push(line);
+          continue;
+        }
+
+        if (including && stopLinePatterns.some(pattern => pattern.test(line))) {
+          including = false;
+          continue;
+        }
+
+        if (including) {
+          kept.push(line);
+        }
+      }
+
+      result = kept.join("\n");
+    }
+
+    for (const pattern of this.extraction.stripPatterns) {
+      result = result.replace(pattern, "");
+    }
+
+    result = result
+      .split("\n")
+      .map(line => line.trimEnd())
+      .join("\n");
+
+    result = result.replace(/\n{3,}/g, "\n\n");
+
+    return result.trim();
+  }
+}

package/src/extract/index.ts

@@ -0,0 +1,2 @@
+export { OutputExtractor, ExtractionResult } from "./OutputExtractor.js";
+export { computeLineDiff, computeCharDiff, getAddedText, getRemovedText, DiffResult } from "./Diff.js";

package/src/index.ts

@@ -0,0 +1,67 @@
+// PTY Session
+export { PtySession, PtySessionOptions } from "./pty/index.js";
+
+// Terminal / Screen
+export { HeadlessScreen, HeadlessScreenOptions } from "./term/index.js";
+export { ScreenSnapshot, ScreenSnapshotData } from "./term/index.js";
+
+// Expect Engine
+export { ExpectEngine, UntilOptions, IdleOptions, ExpectResult } from "./expect/index.js";
+export { Matchers, MatcherFn } from "./expect/index.js";
+
+// Driver
+export {
+  TuiDriver,
+  TuiDriverOptions,
+  AskResult,
+  TuiProfile,
+  TuiProfileName,
+  TuiAnchors,
+  TuiKeys,
+  TuiExtraction,
+  createProfile,
+  StateMachine,
+  TuiState,
+  StateTransition,
+  claudeCodeProfile,
+  codexProfile,
+  TuiSignals,
+  TuiScreenSignals,
+} from "./driver/index.js";
+
+// Extract
+export {
+  OutputExtractor,
+  ExtractionResult,
+  computeLineDiff,
+  computeCharDiff,
+  getAddedText,
+  getRemovedText,
+  DiffResult,
+} from "./extract/index.js";
+
+// Convenience factory function
+import { TuiDriver, TuiDriverOptions } from "./driver/index.js";
+import { claudeCodeProfile, codexProfile } from "./driver/index.js";
+import { TuiProfileName, TuiProfile } from "./driver/index.js";
+
+export function createDriver(
+  profileName: TuiProfileName,
+  options?: Partial<Omit<TuiDriverOptions, "profile">>
+): TuiDriver {
+  const baseProfile = profileName === "claude-code" ? claudeCodeProfile : codexProfile;
+
+  // Merge current process.env with profile env
+  const profile: TuiProfile = {
+    ...baseProfile,
+    env: {
+      ...process.env as Record<string, string>,
+      ...baseProfile.env,
+    },
+  };
+
+  return new TuiDriver({
+    profile,
+    ...options,
+  });
+}

package/src/pty/PtySession.ts

@@ -0,0 +1,234 @@
+import * as pty from "node-pty";
+import { EventEmitter } from "events";
+import fs from "node:fs";
+import path from "node:path";
+
+export interface PtySessionOptions {
+  cols?: number;
+  rows?: number;
+  env?: Record<string, string>;
+  cwd?: string;
+}
+
+export interface PtySessionEvents {
+  data: (chunk: string) => void;
+  exit: (code: number, signal?: number) => void;
+  error: (err: Error) => void;
+}
+
+const DEFAULT_COLS = 120;
+const DEFAULT_ROWS = 40;
+
+let helperPermissionChecked = false;
+
+function locateSpawnHelperPath(): string | null {
+  if (process.platform === "win32") {
+    return null;
+  }
+
+  try {
+    const unixTerminalPath = require.resolve("node-pty/lib/unixTerminal.js");
+    const libDir = path.dirname(unixTerminalPath);
+    const platformDir = `${process.platform}-${process.arch}`;
+    const candidates = [
+      path.resolve(libDir, "../build/Release/spawn-helper"),
+      path.resolve(libDir, "../build/Debug/spawn-helper"),
+      path.resolve(libDir, `../prebuilds/${platformDir}/spawn-helper`),
+      path.resolve(libDir, "./build/Release/spawn-helper"),
+      path.resolve(libDir, "./build/Debug/spawn-helper"),
+      path.resolve(libDir, `./prebuilds/${platformDir}/spawn-helper`),
+    ];
+
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+  } catch {
+    // best effort
+  }
+
+  return null;
+}
+
+function ensureSpawnHelperExecutable(): void {
+  if (helperPermissionChecked) {
+    return;
+  }
+  helperPermissionChecked = true;
+
+  const helperPath = locateSpawnHelperPath();
+  if (!helperPath) {
+    return;
+  }
+
+  try {
+    fs.accessSync(helperPath, fs.constants.X_OK);
+  } catch {
+    try {
+      const stat = fs.statSync(helperPath);
+      fs.chmodSync(helperPath, stat.mode | 0o111);
+    } catch {
+      // best effort
+    }
+  }
+}
+
+export class PtySession extends EventEmitter {
+  private ptyProcess: pty.IPty | null = null;
+  private _cols: number;
+  private _rows: number;
+  private _isRunning = false;
+
+  constructor(
+    private command: string,
+    private args: string[] = [],
+    private options: PtySessionOptions = {}
+  ) {
+    super();
+    this._cols = options.cols ?? DEFAULT_COLS;
+    this._rows = options.rows ?? DEFAULT_ROWS;
+  }
+
+  get cols(): number {
+    return this._cols;
+  }
+
+  get rows(): number {
+    return this._rows;
+  }
+
+  get isRunning(): boolean {
+    return this._isRunning;
+  }
+
+  get pid(): number | undefined {
+    return this.ptyProcess?.pid;
+  }
+
+  spawn(): void {
+    if (this.ptyProcess) {
+      throw new Error("PTY session already spawned");
+    }
+
+    ensureSpawnHelperExecutable();
+
+    const env: Record<string, string> = {
+      ...process.env as Record<string, string>,
+      TERM: "xterm-256color",
+      LANG: "en_US.UTF-8",
+      LC_ALL: "en_US.UTF-8",
+      ...this.options.env,
+    };
+
+    this.ptyProcess = pty.spawn(this.command, this.args, {
+      name: "xterm-256color",
+      cols: this._cols,
+      rows: this._rows,
+      cwd: this.options.cwd ?? process.cwd(),
+      env,
+    });
+
+    this._isRunning = true;
+
+    this.ptyProcess.onData((data: string) => {
+      this.emit("data", data);
+    });
+
+    this.ptyProcess.onExit(({ exitCode, signal }) => {
+      this._isRunning = false;
+      this.emit("exit", exitCode, signal);
+    });
+  }
+
+  write(data: string): void {
+    if (!this.ptyProcess) {
+      throw new Error("PTY session not spawned");
+    }
+    this.ptyProcess.write(data);
+  }
+
+  writeResponse(data: string): void {
+    this.write(data);
+  }
+
+  async writeChunked(
+    data: string,
+    chunkSize = 300,
+    delayMs = 20
+  ): Promise<void> {
+    for (let i = 0; i < data.length; i += chunkSize) {
+      const chunk = data.slice(i, i + chunkSize);
+      this.write(chunk);
+      if (i + chunkSize < data.length) {
+        await this.sleep(delayMs);
+      }
+    }
+  }
+
+  resize(cols: number, rows: number): void {
+    if (!this.ptyProcess) {
+      throw new Error("PTY session not spawned");
+    }
+    this._cols = cols;
+    this._rows = rows;
+    this.ptyProcess.resize(cols, rows);
+  }
+
+  kill(signal: string = "SIGTERM"): void {
+    if (this.ptyProcess) {
+      this.ptyProcess.kill(signal);
+      this.ptyProcess = null;
+      this._isRunning = false;
+    }
+  }
+
+  sendKey(key: string): void {
+    const keyMap: Record<string, string> = {
+      ENTER: "\r",
+      CTRL_C: "\x03",
+      CTRL_D: "\x04",
+      CTRL_J: "\n",
+      CTRL_L: "\x0c",
+      CTRL_Z: "\x1a",
+      ESC: "\x1b",
+      TAB: "\t",
+      BACKSPACE: "\x7f",
+      UP: "\x1b[A",
+      DOWN: "\x1b[B",
+      RIGHT: "\x1b[C",
+      LEFT: "\x1b[D",
+    };
+
+    const mapped = keyMap[key.toUpperCase()];
+    if (mapped) {
+      this.write(mapped);
+    } else {
+      this.write(key);
+    }
+  }
+
+  sendKeys(keys: string[], delayMs = 50): Promise<void> {
+    return new Promise(async (resolve) => {
+      for (let i = 0; i < keys.length; i++) {
+        this.sendKey(keys[i]);
+        if (i < keys.length - 1) {
+          await this.sleep(delayMs);
+        }
+      }
+      resolve();
+    });
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  onData(callback: (chunk: string) => void): void {
+    this.on("data", callback);
+  }
+
+  onExit(callback: (code: number, signal?: number) => void): void {
+    this.on("exit", callback);
+  }
+}

package/src/pty/index.ts

@@ -0,0 +1 @@
+export { PtySession, PtySessionOptions, PtySessionEvents } from "./PtySession.js";

package/src/term/HeadlessScreen.ts

@@ -0,0 +1,151 @@
+import { Terminal } from "@xterm/headless";
+import { SerializeAddon } from "@xterm/addon-serialize";
+import { ScreenSnapshot } from "./ScreenSnapshot.js";
+
+export interface HeadlessScreenOptions {
+  cols?: number;
+  rows?: number;
+  scrollback?: number;
+  onTerminalReply?: (data: string) => void;
+}
+
+const DEFAULT_COLS = 120;
+const DEFAULT_ROWS = 40;
+const DEFAULT_SCROLLBACK = 5000;
+
+export class HeadlessScreen {
+  private terminal: Terminal;
+  private serializeAddon: SerializeAddon;
+  private _cols: number;
+  private _rows: number;
+  private onTerminalReply?: (data: string) => void;
+
+  constructor(options: HeadlessScreenOptions = {}) {
+    this._cols = options.cols ?? DEFAULT_COLS;
+    this._rows = options.rows ?? DEFAULT_ROWS;
+    this.onTerminalReply = options.onTerminalReply;
+
+    this.terminal = new Terminal({
+      cols: this._cols,
+      rows: this._rows,
+      scrollback: options.scrollback ?? DEFAULT_SCROLLBACK,
+      allowProposedApi: true,
+    });
+
+    this.serializeAddon = new SerializeAddon();
+    this.terminal.loadAddon(this.serializeAddon);
+  }
+
+  get cols(): number {
+    return this._cols;
+  }
+
+  get rows(): number {
+    return this._rows;
+  }
+
+  write(data: string): void {
+    const replies = this.getDsrReplies(data);
+    this.terminal.write(data);
+    if (this.onTerminalReply && replies.length > 0) {
+      for (const reply of replies) {
+        this.onTerminalReply(reply);
+      }
+    }
+  }
+
+  resize(cols: number, rows: number): void {
+    this._cols = cols;
+    this._rows = rows;
+    this.terminal.resize(cols, rows);
+  }
+
+  clear(): void {
+    this.terminal.clear();
+  }
+
+  reset(): void {
+    this.terminal.reset();
+  }
+
+  snapshot(): ScreenSnapshot {
+    const viewportText = this.getViewportText();
+    const scrollbackText = this.getScrollbackText();
+    const cursor = this.getCursor();
+    const hash = ScreenSnapshot.computeHash(viewportText);
+
+    return new ScreenSnapshot({
+      viewportText,
+      scrollbackText,
+      cursor,
+      hash,
+      timestamp: Date.now(),
+      cols: this._cols,
+      rows: this._rows,
+    });
+  }
+
+  private getViewportText(): string {
+    const buffer = this.terminal.buffer.active;
+    const lines: string[] = [];
+
+    for (let i = 0; i < this._rows; i++) {
+      const line = buffer.getLine(buffer.baseY + i);
+      if (line) {
+        lines.push(line.translateToString(true));
+      } else {
+        lines.push("");
+      }
+    }
+
+    return lines.join("\n");
+  }
+
+  private getScrollbackText(): string {
+    const buffer = this.terminal.buffer.active;
+    const lines: string[] = [];
+    const totalLines = buffer.baseY + this._rows;
+
+    for (let i = 0; i < totalLines; i++) {
+      const line = buffer.getLine(i);
+      if (line) {
+        lines.push(line.translateToString(true));
+      } else {
+        lines.push("");
+      }
+    }
+
+    return lines.join("\n");
+  }
+
+  private getCursor(): { x: number; y: number } {
+    const buffer = this.terminal.buffer.active;
+    return {
+      x: buffer.cursorX,
+      y: buffer.cursorY,
+    };
+  }
+
+  private getDsrReplies(data: string): string[] {
+    const dsrRegex = /\x1b\[(\?)?6n/g;
+    const matches = data.match(dsrRegex);
+    if (!matches || matches.length === 0) {
+      return [];
+    }
+
+    const cursor = this.getCursor();
+    const row = cursor.y + 1;
+    const col = cursor.x + 1;
+    const reply = `\x1b[${row};${col}R`;
+
+    return Array.from({ length: matches.length }, () => reply);
+  }
+
+  serialize(): string {
+    return this.serializeAddon.serialize();
+  }
+
+  dispose(): void {
+    this.terminal.dispose();
+  }
+}

package/src/term/ScreenSnapshot.ts

@@ -0,0 +1,89 @@
+import { createHash } from "crypto";
+
+export interface ScreenSnapshotData {
+  viewportText: string;
+  scrollbackText: string;
+  cursor: { x: number; y: number };
+  hash: string;
+  timestamp: number;
+  cols: number;
+  rows: number;
+}
+
+export class ScreenSnapshot implements ScreenSnapshotData {
+  readonly viewportText: string;
+  readonly scrollbackText: string;
+  readonly cursor: { x: number; y: number };
+  readonly hash: string;
+  readonly timestamp: number;
+  readonly cols: number;
+  readonly rows: number;
+
+  constructor(data: ScreenSnapshotData) {
+    this.viewportText = data.viewportText;
+    this.scrollbackText = data.scrollbackText;
+    this.cursor = data.cursor;
+    this.hash = data.hash;
+    this.timestamp = data.timestamp;
+    this.cols = data.cols;
+    this.rows = data.rows;
+  }
+
+  static computeHash(text: string): string {
+    return createHash("md5").update(text).digest("hex").slice(0, 16);
+  }
+
+  getViewportLines(): string[] {
+    return this.viewportText.split("\n");
+  }
+
+  getScrollbackLines(): string[] {
+    return this.scrollbackText.split("\n");
+  }
+
+  getViewportWithoutBottom(bottomLines: number): string {
+    const lines = this.getViewportLines();
+    if (bottomLines >= lines.length) {
+      return "";
+    }
+    return lines.slice(0, lines.length - bottomLines).join("\n");
+  }
+
+  matchesPattern(pattern: RegExp, region: "viewport" | "scrollback" = "viewport"): boolean {
+    const text = region === "viewport" ? this.viewportText : this.scrollbackText;
+    return pattern.test(text);
+  }
+
+  findPattern(pattern: RegExp, region: "viewport" | "scrollback" = "viewport"): RegExpMatchArray | null {
+    const text = region === "viewport" ? this.viewportText : this.scrollbackText;
+    return text.match(pattern);
+  }
+
+  diff(other: ScreenSnapshot): {
+    added: string[];
+    removed: string[];
+  } {
+    const thisLines = this.scrollbackText.split("\n");
+    const otherLines = other.scrollbackText.split("\n");
+
+    const thisSet = new Set(thisLines);
+    const otherSet = new Set(otherLines);
+
+    const added = otherLines.filter(line => !thisSet.has(line));
+    const removed = thisLines.filter(line => !otherSet.has(line));
+
+    return { added, removed };
+  }
+
+  toJSON(): ScreenSnapshotData {
+    return {
+      viewportText: this.viewportText,
+      scrollbackText: this.scrollbackText,
+      cursor: this.cursor,
+      hash: this.hash,
+      timestamp: this.timestamp,
+      cols: this.cols,
+      rows: this.rows,
+    };
+  }
+}

package/src/term/index.ts

@@ -0,0 +1,2 @@
+export { HeadlessScreen, HeadlessScreenOptions } from "./HeadlessScreen.js";
+export { ScreenSnapshot, ScreenSnapshotData } from "./ScreenSnapshot.js";

package/test/claude-profile.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { claudeCodeProfile } from "../src/driver/profiles/claudeCode.profile.js";
+
+describe("claude profile timeout policy", () => {
+  it("disables hard timeouts for long-running turns", () => {
+    expect(claudeCodeProfile.timeouts?.boot).toBe(0);
+    expect(claudeCodeProfile.timeouts?.ready).toBe(0);
+    expect(claudeCodeProfile.timeouts?.streamStart).toBe(0);
+    expect(claudeCodeProfile.timeouts?.streamEnd).toBe(0);
+  });
+});