terminal-pilot 0.0.3 → 0.0.5

package/README.md

@@ -61,8 +61,9 @@ type NewSessionOptions = {
 class TerminalPilot {
   static launch(): Promise<TerminalPilot>;
   newSession(options: NewSessionOptions): Promise<TerminalSession>;
-  getSession(id: string): TerminalSession; // throws if missing
-  sessions(): TerminalSession[]; // active sessions only
+  getSession(id: string): TerminalSession; // throws if not in map; works for exited sessions until deleteSession
+  deleteSession(id: string): void; // explicit removal from session map
+  sessions(): TerminalSession[]; // running sessions only (exitCode === null)
   close(): Promise<void>;
 }
 ```
@@ -122,12 +123,13 @@ class TerminalSession {
   readonly pid: number;
   exitCode: number | null;
 
-  type(text: string): Promise<void>; // character-by-character
-  fill(text: string): Promise<void>; // bulk write
+  type(text: string): Promise<void>; // character-by-character with delay
+  fill(text: string): Promise<void>; // bulk write (\n → \r)
   press(key: TerminalKey): Promise<void>;
   send(raw: string): Promise<void>; // raw bytes / escape sequences
   signal(signal: string): Promise<void>;
   waitFor(pattern: string | RegExp, options?: WaitForOptions): Promise<string>;
+  waitForExit(options?: { timeout?: number }): Promise<number>; // throws on timeout
   waitForQuiet(ms: number): Promise<void>;
   screen(): Promise<TerminalScreen>;
   history(options?: HistoryOptions): Promise<string[]>;

package/dist/terminal-buffer.d.ts

@@ -0,0 +1,38 @@
+type Cell = [number, string] | null;
+type Row = Cell[];
+export declare class TerminalBuffer {
+    private _cols;
+    private _rows;
+    private _screen;
+    private _cursorX;
+    private _cursorY;
+    private _savedCursor;
+    private _scrollTop;
+    private _scrollBottom;
+    private _state;
+    private _csiParams;
+    private _csiPrivate;
+    readonly displayBuffer: {
+        readonly cursorX: number;
+        readonly cursorY: number;
+        readonly data: Array<Row | undefined>;
+    };
+    constructor(cols: number, rows: number);
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    private _makeScreen;
+    private _makeRow;
+    private _clamp;
+    private _setChar;
+    private _eraseLine;
+    private _scrollUp;
+    private _scrollDown;
+    private _newline;
+    private _parseCsiParams;
+    private _execCsi;
+    private _feed;
+    private _feedNormal;
+    private _feedEscape;
+    private _feedCsi;
+}
+export {};

package/dist/terminal-buffer.js

@@ -0,0 +1,445 @@
+export class TerminalBuffer {
+    _cols;
+    _rows;
+    _screen;
+    _cursorX = 0;
+    _cursorY = 0;
+    _savedCursor = { x: 0, y: 0 };
+    _scrollTop = 0;
+    _scrollBottom;
+    _state = 0 /* State.Normal */;
+    _csiParams = "";
+    _csiPrivate = "";
+    displayBuffer;
+    constructor(cols, rows) {
+        this._cols = cols;
+        this._rows = rows;
+        this._scrollBottom = rows - 1;
+        this._screen = this._makeScreen(cols, rows);
+        this.displayBuffer = Object.defineProperties({}, {
+            cursorX: { get: () => this._cursorX, enumerable: true },
+            cursorY: { get: () => this._cursorY, enumerable: true },
+            data: { get: () => this._screen, enumerable: true },
+        });
+    }
+    write(data) {
+        for (const ch of data) {
+            this._feed(ch);
+        }
+    }
+    resize(cols, rows) {
+        // Adjust row count
+        while (this._screen.length < rows) {
+            this._screen.push(this._makeRow(cols));
+        }
+        this._screen.length = rows;
+        // Adjust col count for each row
+        for (let y = 0; y < rows; y++) {
+            const row = this._screen[y] ?? this._makeRow(cols);
+            while (row.length < cols)
+                row.push(null);
+            row.length = cols;
+            this._screen[y] = row;
+        }
+        this._cols = cols;
+        this._rows = rows;
+        this._scrollTop = 0;
+        this._scrollBottom = rows - 1;
+        this._cursorX = this._clamp(this._cursorX, 0, cols - 1);
+        this._cursorY = this._clamp(this._cursorY, 0, rows - 1);
+    }
+    _makeScreen(cols, rows) {
+        return Array.from({ length: rows }, () => this._makeRow(cols));
+    }
+    _makeRow(cols) {
+        return Array(cols).fill(null);
+    }
+    _clamp(value, min, max) {
+        return Math.max(min, Math.min(max, value));
+    }
+    _setChar(y, x, ch) {
+        const row = this._screen[y];
+        if (row && x >= 0 && x < this._cols) {
+            row[x] = [ch.charCodeAt(0), ch];
+        }
+    }
+    _eraseLine(y, fromX, toX) {
+        const row = this._screen[y];
+        if (!row)
+            return;
+        for (let x = fromX; x <= toX && x < this._cols; x++) {
+            row[x] = null;
+        }
+    }
+    _scrollUp(count) {
+        for (let i = 0; i < count; i++) {
+            this._screen.splice(this._scrollTop, 1);
+            this._screen.splice(this._scrollBottom, 0, this._makeRow(this._cols));
+        }
+    }
+    _scrollDown(count) {
+        for (let i = 0; i < count; i++) {
+            this._screen.splice(this._scrollBottom, 1);
+            this._screen.splice(this._scrollTop, 0, this._makeRow(this._cols));
+        }
+    }
+    _newline() {
+        if (this._cursorY === this._scrollBottom) {
+            this._scrollUp(1);
+        }
+        else {
+            this._cursorY = Math.min(this._cursorY + 1, this._rows - 1);
+        }
+    }
+    _parseCsiParams() {
+        if (!this._csiParams)
+            return [];
+        return this._csiParams.split(";").map((s) => (s === "" ? 0 : parseInt(s, 10)));
+    }
+    _execCsi(final) {
+        const params = this._parseCsiParams();
+        const p0 = params[0] ?? 0;
+        const p1 = params[1] ?? 0;
+        if (this._csiPrivate === "?") {
+            if (final === "h" || final === "l") {
+                // Only handle alt screen (1049) — ignore everything else
+                if (params.includes(1049)) {
+                    if (final === "h") {
+                        this._screen = this._makeScreen(this._cols, this._rows);
+                        this._cursorX = 0;
+                        this._cursorY = 0;
+                    }
+                    else {
+                        this._screen = this._makeScreen(this._cols, this._rows);
+                        this._cursorX = 0;
+                        this._cursorY = 0;
+                    }
+                }
+            }
+            return;
+        }
+        switch (final) {
+            case "A": // cursor up
+                this._cursorY = this._clamp(this._cursorY - Math.max(1, p0), 0, this._rows - 1);
+                break;
+            case "B": // cursor down
+                this._cursorY = this._clamp(this._cursorY + Math.max(1, p0), 0, this._rows - 1);
+                break;
+            case "C": // cursor forward
+            case "a":
+                this._cursorX = this._clamp(this._cursorX + Math.max(1, p0), 0, this._cols - 1);
+                break;
+            case "D": // cursor backward
+                this._cursorX = this._clamp(this._cursorX - Math.max(1, p0), 0, this._cols - 1);
+                break;
+            case "E": // cursor next line
+                this._cursorY = this._clamp(this._cursorY + Math.max(1, p0), 0, this._rows - 1);
+                this._cursorX = 0;
+                break;
+            case "F": // cursor preceding line
+                this._cursorY = this._clamp(this._cursorY - Math.max(1, p0), 0, this._rows - 1);
+                this._cursorX = 0;
+                break;
+            case "G": // cursor horizontal absolute
+            case "`":
+                this._cursorX = this._clamp(Math.max(1, p0) - 1, 0, this._cols - 1);
+                break;
+            case "H": // cursor position
+            case "f":
+                this._cursorY = this._clamp(Math.max(1, p0) - 1, 0, this._rows - 1);
+                this._cursorX = this._clamp(Math.max(1, p1) - 1, 0, this._cols - 1);
+                break;
+            case "I": // cursor forward tabulation
+                for (let i = 0; i < Math.max(1, p0); i++) {
+                    this._cursorX = Math.min(this._cols - 1, (Math.floor(this._cursorX / 8) + 1) * 8);
+                }
+                break;
+            case "J": // erase in display
+                if (p0 === 0) {
+                    this._eraseLine(this._cursorY, this._cursorX, this._cols - 1);
+                    for (let y = this._cursorY + 1; y < this._rows; y++)
+                        this._eraseLine(y, 0, this._cols - 1);
+                }
+                else if (p0 === 1) {
+                    for (let y = 0; y < this._cursorY; y++)
+                        this._eraseLine(y, 0, this._cols - 1);
+                    this._eraseLine(this._cursorY, 0, this._cursorX);
+                }
+                else if (p0 === 2 || p0 === 3) {
+                    for (let y = 0; y < this._rows; y++)
+                        this._eraseLine(y, 0, this._cols - 1);
+                }
+                break;
+            case "K": // erase in line
+                if (p0 === 0)
+                    this._eraseLine(this._cursorY, this._cursorX, this._cols - 1);
+                else if (p0 === 1)
+                    this._eraseLine(this._cursorY, 0, this._cursorX);
+                else if (p0 === 2)
+                    this._eraseLine(this._cursorY, 0, this._cols - 1);
+                break;
+            case "X": // erase characters (ECH)
+                this._eraseLine(this._cursorY, this._cursorX, this._cursorX + Math.max(1, p0) - 1);
+                break;
+            case "L": { // insert lines
+                const n = Math.max(1, p0);
+                for (let i = 0; i < n; i++) {
+                    this._screen.splice(this._scrollBottom, 1);
+                    this._screen.splice(this._cursorY, 0, this._makeRow(this._cols));
+                }
+                break;
+            }
+            case "M": { // delete lines
+                const n = Math.max(1, p0);
+                for (let i = 0; i < n; i++) {
+                    this._screen.splice(this._cursorY, 1);
+                    this._screen.splice(this._scrollBottom, 0, this._makeRow(this._cols));
+                }
+                break;
+            }
+            case "P": { // delete characters
+                const row = this._screen[this._cursorY];
+                if (row) {
+                    const n = Math.max(1, p0);
+                    row.splice(this._cursorX, n);
+                    while (row.length < this._cols)
+                        row.push(null);
+                }
+                break;
+            }
+            case "@": { // insert blank characters
+                const row = this._screen[this._cursorY];
+                if (row) {
+                    const n = Math.max(1, p0);
+                    for (let i = 0; i < n; i++)
+                        row.splice(this._cursorX, 0, null);
+                    row.splice(this._cols);
+                }
+                break;
+            }
+            case "S": // scroll up
+                this._scrollUp(Math.max(1, p0));
+                break;
+            case "T": // scroll down
+                if (params.length <= 1)
+                    this._scrollDown(Math.max(1, p0));
+                break;
+            case "Z": { // cursor backward tabulation
+                const n = Math.max(1, p0);
+                for (let i = 0; i < n; i++) {
+                    this._cursorX = Math.max(0, (Math.ceil(this._cursorX / 8) - 1) * 8);
+                }
+                break;
+            }
+            case "d": // line position absolute
+                this._cursorY = this._clamp(Math.max(1, p0) - 1, 0, this._rows - 1);
+                break;
+            case "e": // vertical position relative
+                this._cursorY = this._clamp(this._cursorY + Math.max(1, p0), 0, this._rows - 1);
+                break;
+            case "r": { // set scrolling region
+                const top = this._clamp(Math.max(1, p0) - 1, 0, this._rows - 1);
+                const bottom = this._clamp((p1 === 0 ? this._rows : p1) - 1, 0, this._rows - 1);
+                if (top < bottom) {
+                    this._scrollTop = top;
+                    this._scrollBottom = bottom;
+                }
+                this._cursorX = 0;
+                this._cursorY = 0;
+                break;
+            }
+            case "s": // save cursor
+                this._savedCursor = { x: this._cursorX, y: this._cursorY };
+                break;
+            case "u": // restore cursor
+                this._cursorX = this._clamp(this._savedCursor.x, 0, this._cols - 1);
+                this._cursorY = this._clamp(this._savedCursor.y, 0, this._rows - 1);
+                break;
+            case "m": // SGR — ignore (we don't track attributes)
+                break;
+            default:
+                break;
+        }
+    }
+    _feed(ch) {
+        const code = ch.charCodeAt(0);
+        switch (this._state) {
+            case 0 /* State.Normal */:
+                this._feedNormal(ch, code);
+                break;
+            case 1 /* State.Escape */:
+                this._feedEscape(ch, code);
+                break;
+            case 2 /* State.Csi */:
+                this._feedCsi(ch, code);
+                break;
+            case 3 /* State.Osc */:
+                // consume until BEL or ESC (ESC \ = ST)
+                if (code === 0x07 || code === 0x9c) {
+                    this._state = 0 /* State.Normal */;
+                }
+                else if (code === 0x1b) {
+                    // next char should be `\` — just return to normal, it will be consumed
+                    this._state = 0 /* State.Normal */;
+                }
+                break;
+            case 4 /* State.Str */:
+                // consume until ST (0x9c) or BEL
+                if (code === 0x9c || code === 0x07) {
+                    this._state = 0 /* State.Normal */;
+                }
+                else if (code === 0x1b) {
+                    this._state = 0 /* State.Normal */;
+                }
+                break;
+            case 5 /* State.EscCharset */:
+                // consume one character for charset designation
+                this._state = 0 /* State.Normal */;
+                break;
+            case 6 /* State.EscHash */:
+                // consume one character for line attributes
+                this._state = 0 /* State.Normal */;
+                break;
+        }
+    }
+    _feedNormal(ch, code) {
+        if (code === 0x1b) {
+            this._state = 1 /* State.Escape */;
+        }
+        else if (code === 0x9b) {
+            // C1 CSI
+            this._csiParams = "";
+            this._csiPrivate = "";
+            this._state = 2 /* State.Csi */;
+        }
+        else if (code === 0x9d) {
+            // C1 OSC
+            this._state = 3 /* State.Osc */;
+        }
+        else if (code === 0x90 || code === 0x98 || code === 0x9e || code === 0x9f) {
+            // DCS, SOS, PM, APC
+            this._state = 4 /* State.Str */;
+        }
+        else if (code === 0x07 || code === 0x05 || code === 0x06) {
+            // BEL, ENQ, ACK — ignore
+        }
+        else if (code === 0x08) {
+            // BS
+            if (this._cursorX > 0)
+                this._cursorX--;
+        }
+        else if (code === 0x7f) {
+            // DEL
+            if (this._cursorX > 0) {
+                this._cursorX--;
+                this._setChar(this._cursorY, this._cursorX, " ");
+            }
+        }
+        else if (code === 0x09) {
+            // HT
+            this._cursorX = Math.min(this._cols - 1, (Math.floor(this._cursorX / 8) + 1) * 8);
+        }
+        else if (code === 0x0a || code === 0x0b || code === 0x0c) {
+            // LF, VT, FF
+            this._newline();
+        }
+        else if (code === 0x0d) {
+            // CR
+            this._cursorX = 0;
+        }
+        else if (code === 0x0e || code === 0x0f) {
+            // SO, SI — charset switch, ignore
+        }
+        else if (code >= 0x20 && code !== 0x7f) {
+            // Printable character (including multi-byte Unicode via code points)
+            this._setChar(this._cursorY, this._cursorX, ch);
+            this._cursorX++;
+            if (this._cursorX >= this._cols) {
+                // Auto-wrap
+                this._cursorX = 0;
+                this._newline();
+            }
+        }
+    }
+    _feedEscape(ch, code) {
+        this._state = 0 /* State.Normal */;
+        if (code === 0x5b) {
+            // ESC [ = CSI
+            this._csiParams = "";
+            this._csiPrivate = "";
+            this._state = 2 /* State.Csi */;
+        }
+        else if (code === 0x5d) {
+            // ESC ] = OSC
+            this._state = 3 /* State.Osc */;
+        }
+        else if (code === 0x50 || code === 0x58 || code === 0x5e || code === 0x5f) {
+            // DCS, SOS, PM, APC
+            this._state = 4 /* State.Str */;
+        }
+        else if (code === 0x28 || code === 0x29 || code === 0x2a || code === 0x2b || code === 0x2d || code === 0x2e) {
+            // ESC ( ) * + - . = charset designation (consume next char)
+            this._state = 5 /* State.EscCharset */;
+        }
+        else if (code === 0x23) {
+            // ESC # = line attributes (consume next char)
+            this._state = 6 /* State.EscHash */;
+        }
+        else if (code === 0x37) {
+            // ESC 7 = save cursor
+            this._savedCursor = { x: this._cursorX, y: this._cursorY };
+        }
+        else if (code === 0x38) {
+            // ESC 8 = restore cursor
+            this._cursorX = this._clamp(this._savedCursor.x, 0, this._cols - 1);
+            this._cursorY = this._clamp(this._savedCursor.y, 0, this._rows - 1);
+        }
+        else if (code === 0x44) {
+            // ESC D = index (LF)
+            this._newline();
+        }
+        else if (code === 0x45) {
+            // ESC E = next line
+            this._cursorX = 0;
+            this._newline();
+        }
+        else if (code === 0x4d) {
+            // ESC M = reverse index
+            if (this._cursorY === this._scrollTop) {
+                this._scrollDown(1);
+            }
+            else {
+                this._cursorY = Math.max(0, this._cursorY - 1);
+            }
+        }
+        else if (code === 0x48) {
+            // ESC H = tab set (ignore)
+        }
+        else if (code === 0x63) {
+            // ESC c = full reset
+            this._screen = this._makeScreen(this._cols, this._rows);
+            this._cursorX = 0;
+            this._cursorY = 0;
+            this._savedCursor = { x: 0, y: 0 };
+            this._scrollTop = 0;
+            this._scrollBottom = this._rows - 1;
+        }
+        // All other ESC sequences: two-char, already consumed — ignore
+    }
+    _feedCsi(ch, code) {
+        if (code >= 0x40 && code <= 0x7e) {
+            // Final byte
+            this._execCsi(ch);
+            this._state = 0 /* State.Normal */;
+        }
+        else if (code === 0x3f || code === 0x21 || code === 0x3e || code === 0x20) {
+            // Private/intermediate marker (?, !, >, space)
+            this._csiPrivate = ch;
+        }
+        else if ((code >= 0x30 && code <= 0x39) || code === 0x3b) {
+            // Digit or semicolon — parameter byte
+            this._csiParams += ch;
+        }
+        // Other bytes ignored
+    }
+}

package/dist/terminal-pilot.d.ts

@@ -13,6 +13,7 @@ export declare class TerminalPilot {
     static launch(): Promise<TerminalPilot>;
     newSession(opts: NewSessionOptions): Promise<TerminalSession>;
     getSession(id: string): TerminalSession;
+    deleteSession(id: string): void;
     sessions(): TerminalSession[];
     close(): Promise<void>;
 }

package/dist/terminal-pilot.js

@@ -18,9 +18,6 @@ export class TerminalPilot {
             rows: opts.rows ?? DEFAULT_ROWS,
             observe: opts.observe ?? false
         });
-        session.on("exit", () => {
-            this.sessionMap.delete(session.id);
-        });
         this.sessionMap.set(session.id, session);
         return session;
     }
@@ -31,8 +28,11 @@ export class TerminalPilot {
         }
         return session;
     }
+    deleteSession(id) {
+        this.sessionMap.delete(id);
+    }
     sessions() {
-        return [...this.sessionMap.values()];
+        return [...this.sessionMap.values()].filter((s) => s.exitCode === null);
     }
     async close() {
         const sessions = [...this.sessionMap.values()];

package/dist/terminal-session.d.ts

@@ -42,6 +42,9 @@ export declare class TerminalSession {
     screen(): Promise<TerminalScreen>;
     history(opts?: HistoryOptions): Promise<string[]>;
     resize(cols: number, rows: number): Promise<void>;
+    waitForExit(opts?: {
+        timeout?: number;
+    }): Promise<number>;
     close(): Promise<number>;
     on(event: "exit", cb: (code: number) => void): void;
 }

package/dist/terminal-session.js

@@ -1,12 +1,10 @@
 import { spawn as spawnChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
-import { createRequire } from "node:module";
 import * as nodePty from "node-pty";
 import { stripAnsi } from "./ansi.js";
+import { TerminalBuffer } from "./terminal-buffer.js";
 import { keyToSequence } from "./keys.js";
 import { TerminalScreen } from "./terminal-screen.js";
-const require = createRequire(import.meta.url);
-const HeadlessTerminal = require("headless-terminal");
 const DEFAULT_COLS = 120;
 const DEFAULT_ROWS = 40;
 const DEFAULT_TIMEOUT_MS = 10_000;
@@ -33,7 +31,7 @@ export class TerminalSession {
         this.command = command;
         this.currentCols = cols;
         this.currentRows = rows;
-        this.terminal = new HeadlessTerminal(cols, rows);
+        this.terminal = new TerminalBuffer(cols, rows);
         this.pty = createPtyProcess({ command, args, cwd, env, cols, rows });
         this.pid = this.pty.pid;
         const dataSubscription = this.pty.onData((chunk) => {
@@ -145,6 +143,19 @@ export class TerminalSession {
         }
         this.terminal.resize(cols, rows);
     }
+    async waitForExit(opts) {
+        if (this.exitCode !== null) {
+            return this.exitCode;
+        }
+        if (opts?.timeout !== undefined) {
+            const result = await waitForExit(this.exitPromise, opts.timeout);
+            if (result === null) {
+                throw new Error(`Timed out waiting for process to exit after ${opts.timeout}ms`);
+            }
+            return result;
+        }
+        return this.exitPromise;
+    }
     async close() {
         if (this.exitCode !== null) {
             return this.exitCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminal-pilot",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Playwright-like SDK for automating interactive CLI apps through a real PTY",
   "type": "module",
   "main": "dist/index.js",
@@ -34,7 +34,6 @@
     "headless"
   ],
   "dependencies": {
-    "headless-terminal": "^0.4.0",
     "node-pty": "^1.1.0"
   },
   "devDependencies": {}