@love-moon/tui-driver 0.2.0

package/README.md

@@ -0,0 +1,142 @@
+# TUI Driver
+
+A headless TUI driver for interacting with interactive CLI tools like Claude Code and Codex.
+
+## Requirements
+
+- Node.js >= 18.0.0 (recommended: Node.js 20.x LTS)
+- node-pty requires native compilation (Python and build tools)
+
+**Note**: node-pty may have compatibility issues with Node.js 23+. Use Node.js 20.x LTS for best compatibility.
+
+## Features
+
+- **PTY Session Management**: Spawn and manage pseudo-terminal sessions
+- **Headless Terminal Emulation**: Parse ANSI sequences and maintain screen buffer using @xterm/headless
+- **Expect Engine**: Wait for screen conditions with stability checks and idle detection
+- **State Machine**: Track interaction states (BOOT, READY, TYPING, STREAMING, etc.)
+- **Output Extraction**: Extract model responses using diff-based algorithms
+- **Profile System**: Configurable profiles for different TUI tools
+
+## Installation
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createDriver } from "@love-moon/tui-driver";
+
+const driver = createDriver("claude-code", { debug: true });
+
+await driver.boot();
+const result = await driver.ask("What is 2 + 2?");
+
+if (result.success) {
+  console.log("Answer:", result.answer);
+}
+
+driver.kill();
+```
+
+### Advanced Usage
+
+```typescript
+import { TuiDriver, claudeCodeProfile } from "@love-moon/tui-driver";
+
+const driver = new TuiDriver({
+  profile: claudeCodeProfile,
+  debug: true,
+  onSnapshot: (snapshot, state) => {
+    console.log(`[${state}] Hash: ${snapshot.hash}`);
+  },
+});
+
+await driver.boot();
+
+// Multiple questions in sequence
+const q1 = await driver.ask("Hello!");
+const q2 = await driver.ask("What can you do?");
+
+driver.kill();
+```
+
+### Custom Profile
+
+```typescript
+import { TuiDriver, createProfile } from "@love-moon/tui-driver";
+
+const myProfile = createProfile({
+  name: "claude-code",
+  command: "my-cli",
+  args: ["--interactive"],
+  anchors: {
+    ready: [/>\s*$/m, /prompt:/i],
+    busy: [/thinking/i],
+  },
+  keys: {
+    submit: ["ENTER"],
+    cancel: ["CTRL_C"],
+  },
+  extraction: {
+    mode: "diff-scrollback",
+    stripPatterns: [/^>\s*/gm],
+    bottomUiLines: 2,
+  },
+});
+
+const driver = new TuiDriver({ profile: myProfile });
+```
+
+## Architecture
+
+```
+src/
+  pty/
+    PtySession.ts       # node-pty wrapper
+  term/
+    HeadlessScreen.ts   # @xterm/headless wrapper
+    ScreenSnapshot.ts   # Screen state snapshot
+  expect/
+    ExpectEngine.ts     # Wait/expect engine
+    Matchers.ts         # Pattern matchers
+  driver/
+    TuiProfile.ts       # Profile type definitions
+    TuiDriver.ts        # Main driver class
+    StateMachine.ts     # State management
+    profiles/
+      claudeCode.profile.ts
+      codex.profile.ts
+  extract/
+    OutputExtractor.ts  # Response extraction
+    Diff.ts             # Text diff utilities
+```
+
+## API Reference
+
+### TuiDriver
+
+- `boot()`: Initialize and wait for TUI to be ready
+- `ask(prompt)`: Send a prompt and wait for response
+- `ensureReady()`: Ensure TUI is in ready state
+- `snapshot()`: Get current screen snapshot
+- `sendKeys(keys)`: Send key sequences
+- `kill()`: Terminate the PTY session
+
+### ExpectEngine
+
+- `until(options)`: Wait for condition with stability
+- `untilIdle(options)`: Wait for screen to stop changing
+- `waitForChange(timeout)`: Wait for any screen change
+
+### ScreenSnapshot
+
+- `viewportText`: Current visible screen content
+- `scrollbackText`: Full scrollback buffer
+- `cursor`: Current cursor position
+- `hash`: Screen content hash for change detection

package/dist/driver/StateMachine.d.ts

@@ -0,0 +1,28 @@
+import { EventEmitter } from "events";
+export type TuiState = "IDLE" | "BOOT" | "WAIT_READY" | "PREPARE_TURN" | "TYPE_PROMPT" | "SUBMIT" | "WAIT_STREAM_START" | "WAIT_STREAM_END" | "CAPTURE" | "DONE" | "ERROR" | "RECOVERY";
+export interface StateTransition {
+    from: TuiState;
+    to: TuiState;
+    timestamp: number;
+}
+export interface StateMachineEvents {
+    stateChange: (transition: StateTransition) => void;
+    error: (error: Error, state: TuiState) => void;
+}
+export declare class StateMachine extends EventEmitter {
+    private _state;
+    private _history;
+    private _stateStartTime;
+    get state(): TuiState;
+    get history(): readonly StateTransition[];
+    get stateElapsedMs(): number;
+    transition(to: TuiState): void;
+    transitionTo(...states: TuiState[]): void;
+    isIn(...states: TuiState[]): boolean;
+    reset(): void;
+    error(err: Error): void;
+    recover(): void;
+    getLastTransition(): StateTransition | undefined;
+    getTransitionsSince(timestamp: number): StateTransition[];
+}
+//# sourceMappingURL=StateMachine.d.ts.map

package/dist/driver/StateMachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateMachine.d.ts","sourceRoot":"","sources":["../../src/driver/StateMachine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC,MAAM,MAAM,QAAQ,GAChB,MAAM,GACN,MAAM,GACN,YAAY,GACZ,cAAc,GACd,aAAa,GACb,QAAQ,GACR,mBAAmB,GACnB,iBAAiB,GACjB,SAAS,GACT,MAAM,GACN,OAAO,GACP,UAAU,CAAC;AAEf,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,QAAQ,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,CAAC,UAAU,EAAE,eAAe,KAAK,IAAI,CAAC;IACnD,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;CAChD;AAED,qBAAa,YAAa,SAAQ,YAAY;IAC5C,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,eAAe,CAAsB;IAE7C,IAAI,KAAK,IAAI,QAAQ,CAEpB;IAED,IAAI,OAAO,IAAI,SAAS,eAAe,EAAE,CAExC;IAED,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI;IAY9B,YAAY,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI;IAMzC,IAAI,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO;IAIpC,KAAK,IAAI,IAAI;IAMb,KAAK,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI;IAMvB,OAAO,IAAI,IAAI;IAIf,iBAAiB,IAAI,eAAe,GAAG,SAAS;IAIhD,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE;CAG1D"}

package/dist/driver/StateMachine.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateMachine = void 0;
+const events_1 = require("events");
+class StateMachine extends events_1.EventEmitter {
+    _state = "IDLE";
+    _history = [];
+    _stateStartTime = Date.now();
+    get state() {
+        return this._state;
+    }
+    get history() {
+        return this._history;
+    }
+    get stateElapsedMs() {
+        return Date.now() - this._stateStartTime;
+    }
+    transition(to) {
+        const from = this._state;
+        const timestamp = Date.now();
+        const transition = { from, to, timestamp };
+        this._history.push(transition);
+        this._state = to;
+        this._stateStartTime = timestamp;
+        this.emit("stateChange", transition);
+    }
+    transitionTo(...states) {
+        for (const state of states) {
+            this.transition(state);
+        }
+    }
+    isIn(...states) {
+        return states.includes(this._state);
+    }
+    reset() {
+        this._state = "IDLE";
+        this._history = [];
+        this._stateStartTime = Date.now();
+    }
+    error(err) {
+        const previousState = this._state;
+        this.transition("ERROR");
+        this.emit("error", err, previousState);
+    }
+    recover() {
+        this.transition("RECOVERY");
+    }
+    getLastTransition() {
+        return this._history[this._history.length - 1];
+    }
+    getTransitionsSince(timestamp) {
+        return this._history.filter(t => t.timestamp >= timestamp);
+    }
+}
+exports.StateMachine = StateMachine;
+//# sourceMappingURL=StateMachine.js.map

package/dist/driver/StateMachine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateMachine.js","sourceRoot":"","sources":["../../src/driver/StateMachine.ts"],"names":[],"mappings":";;;AAAA,mCAAsC;AA2BtC,MAAa,YAAa,SAAQ,qBAAY;IACpC,MAAM,GAAa,MAAM,CAAC;IAC1B,QAAQ,GAAsB,EAAE,CAAC;IACjC,eAAe,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7C,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC;IAC3C,CAAC;IAED,UAAU,CAAC,EAAY;QACrB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;QACzB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,MAAM,UAAU,GAAoB,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;QAC5D,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;QAEjC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;IACvC,CAAC;IAED,YAAY,CAAC,GAAG,MAAkB;QAChC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAG,MAAkB;QACxB,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;QACnB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,GAAU;QACd,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC;QAClC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC;IACzC,CAAC;IAED,OAAO;QACL,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAED,iBAAiB;QACf,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,mBAAmB,CAAC,SAAiB;QACnC,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,SAAS,CAAC,CAAC;IAC7D,CAAC;CACF;AA9DD,oCA8DC"}

package/dist/driver/TuiDriver.d.ts

@@ -0,0 +1,73 @@
+import { EventEmitter } from "events";
+import { ScreenSnapshot } from "../term/ScreenSnapshot.js";
+import { TuiProfile } from "./TuiProfile.js";
+import { TuiState } from "./StateMachine.js";
+export interface TuiDriverOptions {
+    profile: TuiProfile;
+    debug?: boolean;
+    onSnapshot?: (snapshot: ScreenSnapshot, state: TuiState) => void;
+    onSignals?: (signals: TuiScreenSignals, snapshot: ScreenSnapshot, state: TuiState) => void;
+}
+export interface AskResult {
+    success: boolean;
+    answer: string;
+    beforeSnapshot: ScreenSnapshot;
+    afterSnapshot: ScreenSnapshot;
+    elapsedMs: number;
+    error?: Error;
+    signals?: TuiScreenSignals;
+    promptLine?: string;
+    replyText?: string;
+    replyBlocks?: string[];
+    replyInProgress?: boolean;
+    statusLine?: string;
+    statusDoneLine?: string;
+}
+export interface TuiScreenSignals {
+    hasPrompt: boolean;
+    promptLine?: string;
+    replyText?: string;
+    replyBlocks?: string[];
+    replyInProgress: boolean;
+    statusLine?: string;
+    statusDoneLine?: string;
+}
+export declare class TuiDriver extends EventEmitter {
+    private pty;
+    private screen;
+    private expect;
+    private stateMachine;
+    private profile;
+    private debug;
+    private onSnapshot?;
+    private onSignals?;
+    private isBooted;
+    constructor(options: TuiDriverOptions);
+    private setupEventHandlers;
+    private log;
+    get state(): TuiState;
+    get running(): boolean;
+    boot(): Promise<void>;
+    ensureReady(): Promise<void>;
+    ask(prompt: string): Promise<AskResult>;
+    private prepareTurn;
+    private typePrompt;
+    private submit;
+    private waitStreamStart;
+    private waitStreamEnd;
+    private extractAnswer;
+    private recovery;
+    private restart;
+    private captureSnapshot;
+    snapshot(): ScreenSnapshot;
+    getSignals(snapshot?: ScreenSnapshot): TuiScreenSignals;
+    sendKeys(keys: string[]): Promise<void>;
+    write(data: string): Promise<void>;
+    kill(): void;
+    private sleep;
+    private resolveTimeout;
+    private waitForScrollbackIdle;
+    private findLastMatch;
+    private extractReplyBlocks;
+}
+//# sourceMappingURL=TuiDriver.d.ts.map

package/dist/driver/TuiDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TuiDriver.d.ts","sourceRoot":"","sources":["../../src/driver/TuiDriver.ts"],"names":[],"mappings":"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"}