pty-manager 1.1.0 → 1.2.0

package/README.md

@@ -11,6 +11,7 @@ PTY session manager with lifecycle management, pluggable adapters, and blocking
 - **Terminal attachment** - Attach to sessions for raw I/O streaming
 - **Special key support** - Send Ctrl, Alt, Shift, and function key combinations via `sendKeys()`
 - **Bracketed paste** - Proper paste handling with bracketed paste mode support
+- **Bun compatible** - Worker-based adapter for non-Node runtimes like Bun
 - **Event-driven** - Rich event system for session lifecycle
 - **TypeScript-first** - Full type definitions included
 
@@ -310,6 +311,70 @@ console.log(SPECIAL_KEYS['up']);      // '\x1b[A'
 console.log(Object.keys(SPECIAL_KEYS).length);  // 130+
 ```
 
+## Bun Compatibility
+
+Since Bun doesn't fully support Node.js native addons like `node-pty`, this package includes a worker-based solution that spawns a Node.js child process to handle PTY operations.
+
+### BunCompatiblePTYManager
+
+```typescript
+import { BunCompatiblePTYManager, isBun } from 'pty-manager';
+
+// Create manager (works from Bun or Node.js)
+const manager = new BunCompatiblePTYManager({
+  nodePath: 'node',  // Path to Node.js executable
+});
+
+// Wait for worker to be ready
+await manager.waitForReady();
+
+// Spawn a session
+const session = await manager.spawn({
+  id: 'my-session',
+  name: 'shell',
+  type: 'shell',
+});
+
+// Listen for output
+manager.onSessionData('my-session', (data) => {
+  console.log('Output:', data);
+});
+
+// Send commands
+await manager.send('my-session', 'echo "Hello from Bun!"\n');
+
+// Send special keys
+await manager.sendKeys('my-session', 'ctrl+c');
+
+// Paste with bracketed paste mode
+await manager.paste('my-session', 'some text');
+
+// Shutdown
+await manager.shutdown();
+```
+
+### How it works
+
+1. `BunCompatiblePTYManager` spawns a Node.js child process running `pty-worker.js`
+2. Commands are sent as JSON over stdin
+3. Events (output, ready, exit) come back as JSON over stdout
+4. The worker uses the full `PTYManager` internally
+
+### Worker Protocol
+
+Commands (stdin → worker):
+- `{ "cmd": "spawn", "id": "...", "config": {...} }`
+- `{ "cmd": "send", "id": "...", "data": "..." }`
+- `{ "cmd": "sendKeys", "id": "...", "keys": ["ctrl+c"] }`
+- `{ "cmd": "kill", "id": "..." }`
+- `{ "cmd": "list" }`
+- `{ "cmd": "shutdown" }`
+
+Events (worker → stdout):
+- `{ "event": "output", "id": "...", "data": "..." }`
+- `{ "event": "ready", "id": "..." }`
+- `{ "event": "exit", "id": "...", "code": 0 }`
+
 ## Built-in Adapters
 
 ### ShellAdapter

package/dist/index.d.mts

@@ -669,4 +669,115 @@ declare class ShellAdapter implements CLIAdapter {
     private stripAnsi;
 }
 
-export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StopOptions, type TerminalAttachment, createAdapter };
+/**
+ * Bun-Compatible PTY Manager
+ *
+ * A wrapper that spawns a Node.js worker process to handle PTY operations,
+ * allowing pty-manager to work from Bun or other non-Node runtimes.
+ */
+
+interface WorkerSessionHandle {
+    id: string;
+    pid: number | undefined;
+    status: 'starting' | 'ready' | 'stopped' | 'error';
+    cols: number;
+    rows: number;
+}
+interface BunPTYManagerOptions {
+    /** Path to node executable (default: 'node') */
+    nodePath?: string;
+    /** Path to worker script (default: auto-detected) */
+    workerPath?: string;
+    /** Environment variables for worker process */
+    env?: Record<string, string>;
+}
+/**
+ * PTY Manager that works with Bun and other non-Node runtimes
+ * by spawning a Node.js worker process.
+ */
+declare class BunCompatiblePTYManager extends EventEmitter {
+    private worker;
+    private sessions;
+    private pending;
+    private ready;
+    private readyPromise;
+    private readyResolve;
+    private nodePath;
+    private workerPath;
+    private env;
+    constructor(options?: BunPTYManagerOptions);
+    private findWorkerPath;
+    private startWorker;
+    private handleWorkerMessage;
+    private sendCommand;
+    private createPending;
+    private resolvePending;
+    /**
+     * Wait for the worker to be ready
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * Check if worker is ready
+     */
+    isReady(): boolean;
+    /**
+     * Spawn a new PTY session
+     */
+    spawn(config: SpawnConfig & {
+        id: string;
+    }): Promise<WorkerSessionHandle>;
+    /**
+     * Send data to a session
+     */
+    send(id: string, data: string): Promise<void>;
+    /**
+     * Send special keys to a session
+     */
+    sendKeys(id: string, keys: string | string[]): Promise<void>;
+    /**
+     * Paste text to a session
+     */
+    paste(id: string, text: string, bracketed?: boolean): Promise<void>;
+    /**
+     * Resize a session
+     */
+    resize(id: string, cols: number, rows: number): Promise<void>;
+    /**
+     * Kill a session
+     */
+    kill(id: string, signal?: string): Promise<void>;
+    /**
+     * Get a session by ID
+     */
+    get(id: string): WorkerSessionHandle | undefined;
+    /**
+     * List all sessions
+     */
+    list(): Promise<WorkerSessionHandle[]>;
+    /**
+     * Check if a session exists
+     */
+    has(id: string): boolean;
+    /**
+     * Subscribe to output from a specific session
+     */
+    onSessionData(id: string, callback: (data: string) => void): () => void;
+    /**
+     * Shutdown the worker and all sessions
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Restart the worker process
+     */
+    restart(): Promise<void>;
+}
+/**
+ * Detect if running in Bun
+ */
+declare function isBun(): boolean;
+/**
+ * Create the appropriate PTY manager based on runtime
+ */
+declare function createPTYManager(options?: BunPTYManagerOptions): BunCompatiblePTYManager;
+
+export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StopOptions, type TerminalAttachment, type WorkerSessionHandle, createAdapter, createPTYManager, isBun };

package/dist/index.d.ts

@@ -669,4 +669,115 @@ declare class ShellAdapter implements CLIAdapter {
     private stripAnsi;
 }
 
-export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StopOptions, type TerminalAttachment, createAdapter };
+/**
+ * Bun-Compatible PTY Manager
+ *
+ * A wrapper that spawns a Node.js worker process to handle PTY operations,
+ * allowing pty-manager to work from Bun or other non-Node runtimes.
+ */
+
+interface WorkerSessionHandle {
+    id: string;
+    pid: number | undefined;
+    status: 'starting' | 'ready' | 'stopped' | 'error';
+    cols: number;
+    rows: number;
+}
+interface BunPTYManagerOptions {
+    /** Path to node executable (default: 'node') */
+    nodePath?: string;
+    /** Path to worker script (default: auto-detected) */
+    workerPath?: string;
+    /** Environment variables for worker process */
+    env?: Record<string, string>;
+}
+/**
+ * PTY Manager that works with Bun and other non-Node runtimes
+ * by spawning a Node.js worker process.
+ */
+declare class BunCompatiblePTYManager extends EventEmitter {
+    private worker;
+    private sessions;
+    private pending;
+    private ready;
+    private readyPromise;
+    private readyResolve;
+    private nodePath;
+    private workerPath;
+    private env;
+    constructor(options?: BunPTYManagerOptions);
+    private findWorkerPath;
+    private startWorker;
+    private handleWorkerMessage;
+    private sendCommand;
+    private createPending;
+    private resolvePending;
+    /**
+     * Wait for the worker to be ready
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * Check if worker is ready
+     */
+    isReady(): boolean;
+    /**
+     * Spawn a new PTY session
+     */
+    spawn(config: SpawnConfig & {
+        id: string;
+    }): Promise<WorkerSessionHandle>;
+    /**
+     * Send data to a session
+     */
+    send(id: string, data: string): Promise<void>;
+    /**
+     * Send special keys to a session
+     */
+    sendKeys(id: string, keys: string | string[]): Promise<void>;
+    /**
+     * Paste text to a session
+     */
+    paste(id: string, text: string, bracketed?: boolean): Promise<void>;
+    /**
+     * Resize a session
+     */
+    resize(id: string, cols: number, rows: number): Promise<void>;
+    /**
+     * Kill a session
+     */
+    kill(id: string, signal?: string): Promise<void>;
+    /**
+     * Get a session by ID
+     */
+    get(id: string): WorkerSessionHandle | undefined;
+    /**
+     * List all sessions
+     */
+    list(): Promise<WorkerSessionHandle[]>;
+    /**
+     * Check if a session exists
+     */
+    has(id: string): boolean;
+    /**
+     * Subscribe to output from a specific session
+     */
+    onSessionData(id: string, callback: (data: string) => void): () => void;
+    /**
+     * Shutdown the worker and all sessions
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Restart the worker process
+     */
+    restart(): Promise<void>;
+}
+/**
+ * Detect if running in Bun
+ */
+declare function isBun(): boolean;
+/**
+ * Create the appropriate PTY manager based on runtime
+ */
+declare function createPTYManager(options?: BunPTYManagerOptions): BunCompatiblePTYManager;
+
+export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StopOptions, type TerminalAttachment, type WorkerSessionHandle, createAdapter, createPTYManager, isBun };

package/dist/index.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -22,11 +32,14 @@ var index_exports = {};
 __export(index_exports, {
   AdapterRegistry: () => AdapterRegistry,
   BaseCLIAdapter: () => BaseCLIAdapter,
+  BunCompatiblePTYManager: () => BunCompatiblePTYManager,
   PTYManager: () => PTYManager,
   PTYSession: () => PTYSession,
   SPECIAL_KEYS: () => SPECIAL_KEYS,
   ShellAdapter: () => ShellAdapter,
-  createAdapter: () => createAdapter
+  createAdapter: () => createAdapter,
+  createPTYManager: () => createPTYManager,
+  isBun: () => isBun
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1309,14 +1322,314 @@ var ShellAdapter = class {
     return str.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "");
   }
 };
+
+// src/bun-compat.ts
+var import_child_process2 = require("child_process");
+var import_events3 = require("events");
+var path = __toESM(require("path"));
+var readline = __toESM(require("readline"));
+var BunCompatiblePTYManager = class extends import_events3.EventEmitter {
+  worker = null;
+  sessions = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  ready = false;
+  readyPromise;
+  readyResolve;
+  nodePath;
+  workerPath;
+  env;
+  constructor(options = {}) {
+    super();
+    this.nodePath = options.nodePath || "node";
+    this.workerPath = options.workerPath || this.findWorkerPath();
+    this.env = options.env || {};
+    this.readyPromise = new Promise((resolve) => {
+      this.readyResolve = resolve;
+    });
+    this.startWorker();
+  }
+  findWorkerPath() {
+    const possiblePaths = [
+      path.join(__dirname, "pty-worker.js"),
+      path.join(__dirname, "..", "dist", "pty-worker.js"),
+      path.join(__dirname, "..", "src", "pty-worker.js")
+    ];
+    return possiblePaths[0];
+  }
+  startWorker() {
+    this.worker = (0, import_child_process2.spawn)(this.nodePath, [this.workerPath], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, ...this.env }
+    });
+    if (!this.worker.stdout || !this.worker.stdin) {
+      throw new Error("Failed to create worker process pipes");
+    }
+    const rl = readline.createInterface({
+      input: this.worker.stdout,
+      terminal: false
+    });
+    rl.on("line", (line) => this.handleWorkerMessage(line));
+    this.worker.stderr?.on("data", (data) => {
+      this.emit("worker_error", data.toString());
+    });
+    this.worker.on("exit", (code, signal) => {
+      this.ready = false;
+      this.worker = null;
+      this.emit("worker_exit", { code, signal });
+      for (const [key, op] of this.pending) {
+        clearTimeout(op.timeout);
+        op.reject(new Error("Worker process exited"));
+        this.pending.delete(key);
+      }
+      for (const session of this.sessions.values()) {
+        session.status = "stopped";
+      }
+    });
+    this.worker.on("error", (err) => {
+      this.emit("worker_error", err);
+    });
+  }
+  handleWorkerMessage(line) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      this.emit("worker_error", `Invalid JSON from worker: ${line}`);
+      return;
+    }
+    const eventType = event.event;
+    const id = event.id;
+    switch (eventType) {
+      case "worker_ready":
+        this.ready = true;
+        this.readyResolve();
+        this.emit("ready");
+        break;
+      case "spawned": {
+        const session = {
+          id,
+          pid: event.pid,
+          status: "starting",
+          cols: 80,
+          rows: 24
+        };
+        this.sessions.set(id, session);
+        this.emit("session_started", session);
+        break;
+      }
+      case "output":
+        this.emit("data", { id, data: event.data });
+        this.emit(`data:${id}`, event.data);
+        break;
+      case "ready": {
+        const session = this.sessions.get(id);
+        if (session) {
+          session.status = "ready";
+          this.emit("session_ready", session);
+        }
+        break;
+      }
+      case "exit": {
+        const session = this.sessions.get(id);
+        if (session) {
+          session.status = "stopped";
+          this.emit("session_stopped", session, event.code, event.signal);
+          this.sessions.delete(id);
+        }
+        break;
+      }
+      case "error":
+        if (id) {
+          const session = this.sessions.get(id);
+          if (session) {
+            session.status = "error";
+          }
+          this.emit("session_error", { id, error: event.message });
+        } else {
+          this.emit("worker_error", event.message);
+        }
+        break;
+      case "list":
+        this.resolvePending("list", event.sessions);
+        break;
+      case "ack": {
+        const cmd = event.cmd;
+        const success = event.success;
+        const pendingKey = id ? `${cmd}:${id}` : cmd;
+        const pending = this.pending.get(pendingKey);
+        if (pending) {
+          clearTimeout(pending.timeout);
+          this.pending.delete(pendingKey);
+          if (success) {
+            pending.resolve(true);
+          } else {
+            pending.reject(new Error(event.error));
+          }
+        }
+        break;
+      }
+    }
+  }
+  sendCommand(cmd) {
+    if (!this.worker?.stdin) {
+      throw new Error("Worker not available");
+    }
+    this.worker.stdin.write(JSON.stringify(cmd) + "\n");
+  }
+  createPending(key, timeoutMs = 3e4) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(key);
+        reject(new Error(`Operation ${key} timed out`));
+      }, timeoutMs);
+      this.pending.set(key, { resolve, reject, timeout });
+    });
+  }
+  resolvePending(key, value) {
+    const pending = this.pending.get(key);
+    if (pending) {
+      clearTimeout(pending.timeout);
+      this.pending.delete(key);
+      pending.resolve(value);
+    }
+  }
+  /**
+   * Wait for the worker to be ready
+   */
+  async waitForReady() {
+    return this.readyPromise;
+  }
+  /**
+   * Check if worker is ready
+   */
+  isReady() {
+    return this.ready;
+  }
+  /**
+   * Spawn a new PTY session
+   */
+  async spawn(config) {
+    await this.waitForReady();
+    const { id } = config;
+    this.sendCommand({ cmd: "spawn", id, config });
+    await this.createPending(`spawn:${id}`);
+    return this.sessions.get(id);
+  }
+  /**
+   * Send data to a session
+   */
+  async send(id, data) {
+    await this.waitForReady();
+    this.sendCommand({ cmd: "send", id, data });
+    await this.createPending(`send:${id}`);
+  }
+  /**
+   * Send special keys to a session
+   */
+  async sendKeys(id, keys) {
+    await this.waitForReady();
+    this.sendCommand({ cmd: "sendKeys", id, keys });
+    await this.createPending(`sendKeys:${id}`);
+  }
+  /**
+   * Paste text to a session
+   */
+  async paste(id, text, bracketed = true) {
+    await this.waitForReady();
+    this.sendCommand({ cmd: "paste", id, text, bracketed });
+    await this.createPending(`paste:${id}`);
+  }
+  /**
+   * Resize a session
+   */
+  async resize(id, cols, rows) {
+    await this.waitForReady();
+    this.sendCommand({ cmd: "resize", id, cols, rows });
+    const session = this.sessions.get(id);
+    if (session) {
+      session.cols = cols;
+      session.rows = rows;
+    }
+    await this.createPending(`resize:${id}`);
+  }
+  /**
+   * Kill a session
+   */
+  async kill(id, signal) {
+    await this.waitForReady();
+    this.sendCommand({ cmd: "kill", id, signal });
+    await this.createPending(`kill:${id}`);
+  }
+  /**
+   * Get a session by ID
+   */
+  get(id) {
+    return this.sessions.get(id);
+  }
+  /**
+   * List all sessions
+   */
+  async list() {
+    await this.waitForReady();
+    this.sendCommand({ cmd: "list" });
+    const sessions = await this.createPending("list");
+    return sessions;
+  }
+  /**
+   * Check if a session exists
+   */
+  has(id) {
+    return this.sessions.has(id);
+  }
+  /**
+   * Subscribe to output from a specific session
+   */
+  onSessionData(id, callback) {
+    const handler = (data) => callback(data);
+    this.on(`data:${id}`, handler);
+    return () => this.off(`data:${id}`, handler);
+  }
+  /**
+   * Shutdown the worker and all sessions
+   */
+  async shutdown() {
+    if (!this.worker) return;
+    this.sendCommand({ cmd: "shutdown" });
+    await this.createPending("shutdown", 1e4).catch(() => {
+      this.worker?.kill("SIGKILL");
+    });
+  }
+  /**
+   * Restart the worker process
+   */
+  async restart() {
+    await this.shutdown();
+    this.sessions.clear();
+    this.ready = false;
+    this.readyPromise = new Promise((resolve) => {
+      this.readyResolve = resolve;
+    });
+    this.startWorker();
+    await this.waitForReady();
+  }
+};
+function isBun() {
+  return typeof process !== "undefined" && "Bun" in process.versions;
+}
+function createPTYManager(options) {
+  return new BunCompatiblePTYManager(options);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AdapterRegistry,
   BaseCLIAdapter,
+  BunCompatiblePTYManager,
   PTYManager,
   PTYSession,
   SPECIAL_KEYS,
   ShellAdapter,
-  createAdapter
+  createAdapter,
+  createPTYManager,
+  isBun
 });
 //# sourceMappingURL=index.js.map