terminal-pilot 0.0.1

package/README.md

@@ -0,0 +1,416 @@
+# @poe-code/terminal-pilot
+
+`terminal-pilot` is a Playwright-like SDK and MCP server for automating interactive CLI apps through a real pseudoterminal (PTY).
+
+Use it when plain stdio is not enough: menus, prompts, arrow-key navigation, confirmations, and terminal redraws such as `poe-code configure`.
+
+For design rationale and scope, see `docs/plans/terminal-pilot.md`.
+
+## What it includes
+
+- **SDK:** `TerminalPilot` → `TerminalSession` → `TerminalScreen`
+- **MCP server:** 10 tools for AI-driven CLI automation
+- **Real PTY execution:** works with interactive CLIs that expect a terminal
+- **Headless by default:** optional `observe: true` mirrors PTY output for debugging
+
+## Entry points
+
+```ts
+import { TerminalPilot } from "@poe-code/terminal-pilot";
+```
+
+```ts
+import { createTerminalPilotMcpServer, main } from "@poe-code/terminal-pilot/mcp";
+```
+
+CLI bin:
+
+```sh
+terminal-pilot-mcp
+```
+
+Development entry point in this repo:
+
+```sh
+npx tsx packages/terminal-pilot/src/mcp-server.ts
+```
+
+## SDK API
+
+### `TerminalPilot`
+
+Creates and tracks active terminal sessions.
+
+```ts
+import { TerminalPilot } from "@poe-code/terminal-pilot";
+
+const pilot = await TerminalPilot.launch();
+
+const session = await pilot.newSession({
+  command: "poe-code",
+  args: ["configure"],
+  cwd: process.cwd(),
+  env: process.env,
+  cols: 120,
+  rows: 40,
+  observe: false
+});
+
+console.log(session.id, session.pid);
+console.log(pilot.sessions().map(({ id, pid }) => ({ id, pid })));
+
+await pilot.close();
+```
+
+```ts
+type NewSessionOptions = {
+  command: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  cols?: number; // default: 120
+  rows?: number; // default: 40
+  observe?: boolean; // default: false
+};
+
+class TerminalPilot {
+  static launch(): Promise<TerminalPilot>;
+  newSession(options: NewSessionOptions): Promise<TerminalSession>;
+  getSession(id: string): TerminalSession; // throws if missing
+  sessions(): TerminalSession[]; // active sessions only
+  close(): Promise<void>;
+}
+```
+
+### `TerminalSession`
+
+Represents one PTY-backed CLI process.
+
+```ts
+await session.waitFor(/Pick an agent to configure:/);
+await session.press("ArrowDown");
+await session.press("Enter");
+
+await session.waitFor(/Waiting for authorization|default model|configured/i);
+
+const screen = await session.screen();
+const history = await session.history({ last: 20 });
+
+console.log(screen.text);
+console.log(history.join("\n"));
+
+await session.resize(100, 30);
+await session.signal("SIGINT");
+await session.close();
+```
+
+```ts
+type WaitForOptions = {
+  timeout?: number; // default: 10000
+};
+
+type HistoryOptions = {
+  last?: number;
+};
+
+type TerminalKey =
+  | "Enter"
+  | "Tab"
+  | "Escape"
+  | "Backspace"
+  | "Delete"
+  | "ArrowUp"
+  | "ArrowDown"
+  | "ArrowLeft"
+  | "ArrowRight"
+  | "Home"
+  | "End"
+  | "PageUp"
+  | "PageDown"
+  | "Space"
+  | `Control+${string}`
+  | `Alt+${string}`;
+
+class TerminalSession {
+  readonly id: string;
+  readonly command: string;
+  readonly pid: number;
+  exitCode: number | null;
+
+  type(text: string): Promise<void>; // character-by-character
+  fill(text: string): Promise<void>; // bulk write
+  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>;
+  waitForQuiet(ms: number): Promise<void>;
+  screen(): Promise<TerminalScreen>;
+  history(options?: HistoryOptions): Promise<string[]>;
+  resize(cols: number, rows: number): Promise<void>;
+  close(): Promise<number>;
+  on(event: "exit", cb: (code: number) => void): void;
+}
+```
+
+Common key names:
+
+- Navigation: `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, `Home`, `End`
+- Editing: `Enter`, `Tab`, `Backspace`, `Delete`, `Space`
+- Control/meta: `Control+c`, `Control+d`, `Alt+x`
+
+### `TerminalScreen`
+
+Normalized visible terminal state.
+
+```ts
+const screen = await session.screen();
+
+screen.lines; // ANSI-stripped visible lines
+screen.rawLines; // raw visible lines
+screen.cursor; // { row, col }
+screen.size; // { rows, cols }
+screen.text; // lines joined with \n
+screen.contains("Configured");
+screen.line(0);
+screen.line(-1);
+```
+
+```ts
+class TerminalScreen {
+  readonly lines: readonly string[];
+  readonly rawLines: readonly string[];
+  readonly cursor: { row: number; col: number };
+  readonly size: { rows: number; cols: number };
+
+  get text(): string;
+  contains(substring: string): boolean;
+  line(index: number): string; // negative indexes supported
+}
+```
+
+## MCP server
+
+The MCP server holds one in-memory `TerminalPilot` instance and exposes terminal automation over stdio.
+
+### Run it
+
+Development:
+
+```sh
+npx tsx packages/terminal-pilot/src/mcp-server.ts
+```
+
+Built / installed package:
+
+```sh
+terminal-pilot-mcp
+```
+
+Programmatic:
+
+```ts
+import { main } from "@poe-code/terminal-pilot/mcp";
+
+await main();
+```
+
+### Connect to an MCP client
+
+Install the package globally from a local build:
+
+```sh
+cd packages/terminal-pilot
+npm pack --pack-destination /tmp && npm install -g /tmp/poe-code-terminal-pilot-*.tgz && rm /tmp/poe-code-terminal-pilot-*.tgz
+```
+
+This makes the `terminal-pilot-mcp` bin available globally.
+
+**Claude Code** (`~/.claude.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "terminal-pilot": {
+      "command": "terminal-pilot-mcp"
+    }
+  }
+}
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "terminal-pilot": {
+      "command": "terminal-pilot-mcp"
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "terminal-pilot": {
+      "command": "terminal-pilot-mcp"
+    }
+  }
+}
+```
+
+### Tools
+
+`void` means the tool returns no payload.
+
+| Tool | Input | Output |
+| --- | --- | --- |
+| `terminal_create_session` | `{ command: string, args?: string[], cwd?: string, cols?: number, rows?: number, observe?: boolean }` | `{ sessionId: string, pid: number }` |
+| `terminal_type` | `{ sessionId: string, text: string }` | `void` |
+| `terminal_press_key` | `{ sessionId: string, key: TerminalKey }` | `void` |
+| `terminal_send_signal` | `{ sessionId: string, signal: string }` | `void` |
+| `terminal_wait_for` | `{ sessionId: string, pattern: string, timeout?: number }` | `{ matched: true, output: string }` |
+| `terminal_read_screen` | `{ sessionId: string }` | `{ lines: string[], cursor: { row: number, col: number }, size: { rows: number, cols: number } }` |
+| `terminal_read_history` | `{ sessionId: string, last?: number }` | `{ lines: string[] }` |
+| `terminal_resize` | `{ sessionId: string, cols: number, rows: number }` | `void` |
+| `terminal_close_session` | `{ sessionId: string }` | `{ exitCode: number }` |
+| `terminal_list_sessions` | `{}` | `{ sessions: Array<{ id: string, command: string, pid: number }> }` |
+
+Practical notes:
+
+- `terminal_wait_for.pattern` is compiled as a JavaScript `RegExp` on the server.
+- `terminal_type` maps to `session.fill(...)` for bulk text entry.
+- `terminal_read_screen` returns the **current visible screen**, not scrollback.
+- `terminal_read_history` returns ANSI-stripped output since session start.
+- `terminal_list_sessions` returns **active** sessions only.
+- `observe: true` mirrors PTY output to `stderr`, which is useful when debugging MCP-driven runs.
+
+Minimal MCP flow:
+
+```json
+{"tool":"terminal_create_session","arguments":{"command":"poe-code","args":["configure"]}}
+{"tool":"terminal_wait_for","arguments":{"sessionId":"<id>","pattern":"Pick an agent to configure:"}}
+{"tool":"terminal_press_key","arguments":{"sessionId":"<id>","key":"Enter"}}
+{"tool":"terminal_read_screen","arguments":{"sessionId":"<id>"}}
+{"tool":"terminal_close_session","arguments":{"sessionId":"<id>"}}
+```
+
+## Environment variables
+
+There are **no terminal-pilot-specific environment variables**.
+
+Runtime environment is controlled per session:
+
+- SDK: `newSession({ env })`
+- MCP server: spawned commands inherit the MCP server process environment unless you override it in your command wrapper
+
+There are also **no package-level config files or config options** beyond the per-session options above.
+
+## Testing
+
+Interactive fixtures live under `packages/terminal-pilot/src/testing/`:
+
+- `test-cli.ts` - prompt + text entry fixture
+- `menu-cli.ts` - arrow-key menu fixture
+- `fixtures.test.ts` - examples of driving both fixtures
+
+Run just the fixture tests:
+
+```sh
+npx vitest run packages/terminal-pilot/src/testing/fixtures.test.ts
+```
+
+Run the whole package test suite:
+
+```sh
+npx vitest run packages/terminal-pilot/src
+```
+
+Typical fixture workflow:
+
+1. Spawn the fixture in a `TerminalSession`
+2. `waitFor(...)` the prompt
+3. `type(...)`, `fill(...)`, `press(...)`, or `signal(...)`
+4. Assert with `screen()` or `history()`
+5. `close()` the session
+
+Example fixture-based test:
+
+```ts
+import path from "node:path";
+import { TerminalPilot } from "@poe-code/terminal-pilot";
+
+const pilot = await TerminalPilot.launch();
+const tsxPath = path.join(process.cwd(), "node_modules", ".bin", "tsx");
+const fixturePath = path.join(process.cwd(), "packages/terminal-pilot/src/testing/menu-cli.ts");
+
+try {
+  const session = await pilot.newSession({
+    command: tsxPath,
+    args: [fixturePath]
+  });
+
+  await session.waitFor("Select an option:");
+  await session.press("ArrowDown");
+  await session.press("ArrowDown");
+  await session.press("Enter");
+
+  await session.waitFor("You selected: Option 3");
+} finally {
+  await pilot.close();
+}
+```
+
+## Example: test `poe-code configure`
+
+Use a temporary home directory so you do not touch your real config while testing the interactive flow.
+
+```ts
+import { mkdtempSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { TerminalPilot } from "@poe-code/terminal-pilot";
+
+const tmpHome = mkdtempSync(path.join(os.tmpdir(), "poe-configure-test-"));
+const pilot = await TerminalPilot.launch();
+
+try {
+  const session = await pilot.newSession({
+    command: "npm",
+    args: ["run", "dev", "--silent", "--", "configure"],
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      HOME: tmpHome,
+      XDG_CONFIG_HOME: path.join(tmpHome, ".config"),
+      XDG_DATA_HOME: path.join(tmpHome, ".local", "share")
+    },
+    cols: 120,
+    rows: 40
+  });
+
+  await session.waitFor(/Pick an agent to configure:/);
+  await session.press("ArrowDown"); // choose Codex, Kimi, etc.
+  await session.press("Enter");
+
+  await session.waitFor(/Waiting for authorization|default model|configured/i, {
+    timeout: 15000
+  });
+
+  const screen = await session.screen();
+  const history = await session.history({ last: 40 });
+
+  console.log(screen.text);
+  console.log(history.join("\n"));
+
+  await session.signal("SIGINT");
+  await session.close();
+} finally {
+  await pilot.close();
+  rmSync(tmpHome, { recursive: true, force: true });
+}
+```
+
+That gives you a real end-to-end test of the interactive `configure` handoff. If the selected provider requires OAuth or API-key input, keep the temp environment and continue the flow with additional `type(...)`, `press(...)`, and `waitFor(...)` calls.

package/dist/ansi.d.ts

@@ -0,0 +1 @@
+export declare function stripAnsi(input: string): string;

package/dist/ansi.js

@@ -0,0 +1,71 @@
+const ESC = 0x1b;
+const BEL = 0x07;
+const ST = 0x9c;
+const CSI = 0x9b;
+const OSC = 0x9d;
+const DCS = 0x90;
+const SOS = 0x98;
+const PM = 0x9e;
+const APC = 0x9f;
+export function stripAnsi(input) {
+    let output = "";
+    for (let index = 0; index < input.length; index += 1) {
+        const code = input.charCodeAt(index);
+        if (code === ESC) {
+            const nextCode = input.charCodeAt(index + 1);
+            if (nextCode === 0x5b) {
+                index = consumeCsi(input, index + 2);
+                continue;
+            }
+            if (nextCode === 0x5d) {
+                index = consumeTerminatedString(input, index + 2, true);
+                continue;
+            }
+            if (nextCode === 0x50 || nextCode === 0x58 || nextCode === 0x5e || nextCode === 0x5f) {
+                index = consumeTerminatedString(input, index + 2, false);
+                continue;
+            }
+            if (!Number.isNaN(nextCode)) {
+                index += 1;
+            }
+            continue;
+        }
+        if (code === CSI) {
+            index = consumeCsi(input, index + 1);
+            continue;
+        }
+        if (code === OSC) {
+            index = consumeTerminatedString(input, index + 1, true);
+            continue;
+        }
+        if (code === DCS || code === SOS || code === PM || code === APC) {
+            index = consumeTerminatedString(input, index + 1, false);
+            continue;
+        }
+        output += input[index];
+    }
+    return output;
+}
+function consumeCsi(input, index) {
+    while (index < input.length) {
+        const code = input.charCodeAt(index);
+        if (code >= 0x40 && code <= 0x7e) {
+            return index;
+        }
+        index += 1;
+    }
+    return input.length;
+}
+function consumeTerminatedString(input, index, allowBellTerminator) {
+    while (index < input.length) {
+        const code = input.charCodeAt(index);
+        if (code === ST || (allowBellTerminator && code === BEL)) {
+            return index;
+        }
+        if (code === ESC && input.charCodeAt(index + 1) === 0x5c) {
+            return index + 1;
+        }
+        index += 1;
+    }
+    return input.length;
+}

package/dist/exports.compile-check.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/exports.compile-check.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { stripAnsi } from "./ansi.js";
+export { keyToSequence, type TerminalKey } from "./keys.js";
+export { TerminalScreen } from "./terminal-screen.js";
+export { TerminalSession, type HistoryOptions, type WaitForOptions } from "./terminal-session.js";
+export { TerminalPilot, type NewSessionOptions } from "./terminal-pilot.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { stripAnsi } from "./ansi.js";
+export { keyToSequence } from "./keys.js";
+export { TerminalScreen } from "./terminal-screen.js";
+export { TerminalSession } from "./terminal-session.js";
+export { TerminalPilot } from "./terminal-pilot.js";

package/dist/keys.d.ts

@@ -0,0 +1,2 @@
+export type TerminalKey = "Enter" | "Tab" | "Escape" | "Backspace" | "Delete" | "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" | "Home" | "End" | "PageUp" | "PageDown" | "Space" | `Control+${string}` | `Alt+${string}`;
+export declare function keyToSequence(key: TerminalKey): string;

package/dist/keys.js

@@ -0,0 +1,53 @@
+const NAMED_KEY_SEQUENCES = {
+    Enter: "\r",
+    Tab: "\t",
+    Escape: "\x1b",
+    Backspace: "\x7f",
+    Delete: "\x1b[3~",
+    ArrowUp: "\x1b[A",
+    ArrowDown: "\x1b[B",
+    ArrowRight: "\x1b[C",
+    ArrowLeft: "\x1b[D",
+    Home: "\x1b[H",
+    End: "\x1b[F",
+    PageUp: "\x1b[5~",
+    PageDown: "\x1b[6~",
+    Space: " "
+};
+export function keyToSequence(key) {
+    const namedSequence = NAMED_KEY_SEQUENCES[key];
+    if (namedSequence !== undefined) {
+        return namedSequence;
+    }
+    if (key.startsWith("Control+")) {
+        return controlKeyToSequence(key);
+    }
+    if (key.startsWith("Alt+")) {
+        const nestedKey = key.slice("Alt+".length);
+        if (nestedKey.length === 0) {
+            throw new Error(`Unknown terminal key: ${key}`);
+        }
+        if (nestedKey.length === 1) {
+            return "\x1b" + nestedKey;
+        }
+        try {
+            return "\x1b" + keyToSequence(nestedKey);
+        }
+        catch {
+            throw new Error(`Unknown terminal key: ${key}`);
+        }
+    }
+    throw new Error(`Unknown terminal key: ${key}`);
+}
+function controlKeyToSequence(key) {
+    const controlKey = key.slice("Control+".length);
+    if (controlKey.length !== 1) {
+        throw new Error(`Unknown terminal key: ${key}`);
+    }
+    const uppercaseLetter = controlKey.toUpperCase();
+    const charCode = uppercaseLetter.charCodeAt(0);
+    if (charCode < 65 || charCode > 90) {
+        throw new Error(`Unknown terminal key: ${key}`);
+    }
+    return String.fromCharCode(charCode - 64);
+}

package/dist/mcp-server.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { type Server } from "tiny-stdio-mcp-server";
+import { TerminalPilot } from "./terminal-pilot.js";
+type RuntimeProcess = Pick<typeof process, "on" | "off">;
+export declare function createTerminalPilotMcpServer(agent: TerminalPilot): Server;
+export declare function main({ launchAgent, createMcpServer, runtimeProcess }?: {
+    launchAgent?: typeof TerminalPilot.launch;
+    createMcpServer?: (agent: TerminalPilot) => Server;
+    runtimeProcess?: RuntimeProcess;
+}): Promise<void>;
+export {};

package/dist/mcp-server.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import packageJson from "../package.json" with { type: "json" };
+import { createServer } from "tiny-stdio-mcp-server";
+import { terminalPilotMcpTools } from "./mcp-tools.js";
+import { TerminalPilot } from "./terminal-pilot.js";
+export function createTerminalPilotMcpServer(agent) {
+    const server = createServer({
+        name: "terminal-pilot",
+        version: packageJson.version
+    });
+    for (const tool of terminalPilotMcpTools(agent)) {
+        server.tool(tool.name, tool.description, tool.inputSchema, tool.handler);
+    }
+    return server;
+}
+export async function main({ launchAgent = TerminalPilot.launch, createMcpServer = createTerminalPilotMcpServer, runtimeProcess = process } = {}) {
+    const agent = await launchAgent();
+    let closed = false;
+    const closeAgent = async () => {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        await agent.close();
+    };
+    const handleExit = () => {
+        void closeAgent();
+    };
+    runtimeProcess.on("exit", handleExit);
+    try {
+        await createMcpServer(agent).listen();
+    }
+    finally {
+        runtimeProcess.off("exit", handleExit);
+        await closeAgent();
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    void main();
+}

package/dist/mcp-tools.d.ts

@@ -0,0 +1,46 @@
+import { type ToolDefinition } from "tiny-stdio-mcp-server";
+import type { TerminalKey } from "./keys.js";
+import type { TerminalPilot } from "./terminal-pilot.js";
+export type TerminalPilotMcpTool<T = Record<string, unknown>> = ToolDefinition<T>;
+export declare function terminalCreateSessionTool(agent: TerminalPilot): TerminalPilotMcpTool<{
+    command: string;
+    args?: string[];
+    cwd?: string;
+    cols?: number;
+    rows?: number;
+    observe?: boolean;
+}>;
+export declare function terminalTypeTool(agent: TerminalPilot): TerminalPilotMcpTool<{
+    sessionId: string;
+    text: string;
+}>;
+export declare function terminalPressKeyTool(agent: TerminalPilot): TerminalPilotMcpTool<{
+    sessionId: string;
+    key: TerminalKey;
+}>;
+export declare function terminalSendSignalTool(agent: TerminalPilot): TerminalPilotMcpTool<{
+    sessionId: string;
+    signal: string;
+}>;
+export declare function terminalWaitForTool(agent: TerminalPilot): TerminalPilotMcpTool<{
+    sessionId: string;
+    pattern: string;
+    timeout?: number;
+}>;
+export declare function terminalReadScreenTool(agent: TerminalPilot): TerminalPilotMcpTool<{
+    sessionId: string;
+}>;
+export declare function terminalReadHistoryTool(agent: TerminalPilot): TerminalPilotMcpTool<{
+    sessionId: string;
+    last?: number;
+}>;
+export declare function terminalResizeTool(agent: TerminalPilot): TerminalPilotMcpTool<{
+    sessionId: string;
+    cols: number;
+    rows: number;
+}>;
+export declare function terminalCloseSessionTool(agent: TerminalPilot): TerminalPilotMcpTool<{
+    sessionId: string;
+}>;
+export declare function terminalPilotMcpTools(agent: TerminalPilot): Array<TerminalPilotMcpTool<any>>;
+export declare function terminalListSessionsTool(agent: TerminalPilot): TerminalPilotMcpTool<Record<string, never>>;