mstro-app 0.4.2 → 0.4.4

package/server/services/terminal/pty-manager.ts

@@ -2,241 +2,56 @@
 // Licensed under the MIT License. See LICENSE file for details.
 
 /**
- * PTY Manager - Manages pseudo-terminal sessions for shell access
+ * PTY Manager - Manages pseudo-terminal sessions for shell access.
  *
- * Provides terminal emulation for running shell commands on the local machine.
- * Each terminal session is managed independently with its own PTY process.
- *
- * Supports session persistence:
- * - Sessions survive WebSocket disconnections
- * - Scrollback buffer is maintained for replay on reconnect
- * - Sessions can be reattached without losing running processes
- *
- * NOTE: node-pty is an optional dependency requiring native compilation.
- * Terminal features gracefully degrade when node-pty is not available.
+ * Utilities (node-pty loading, shell detection, ScrollbackBuffer, types)
+ * live in pty-utils.ts. This file owns session lifecycle orchestration.
  */
 
 import { EventEmitter } from 'node:events';
-import { createRequire } from 'node:module';
 import { homedir, platform } from 'node:os';
 import { sanitizeEnvForSandbox } from '../sandbox-utils.js';
-
-// Try to load node-pty (optional native dependency)
-let pty: typeof import('node-pty') | null = null;
-let _ptyLoadError: string | null = null;
-
-try {
-  pty = await import('node-pty');
-} catch (error: unknown) {
-  _ptyLoadError = error instanceof Error ? error.message : 'Failed to load node-pty';
-  console.warn('[PTYManager] node-pty not available - terminal features disabled');
-  console.warn('[PTYManager] To enable terminals, run: mstro setup-terminal');
-}
-
-/**
- * Check if node-pty is available
- */
-export function isPtyAvailable(): boolean {
-  return pty !== null;
-}
-
-/**
- * Re-attempt loading node-pty at runtime.
- * Called after `mstro setup-terminal` compiles the native module
- * so the running server can pick it up without a restart.
- *
- * Uses createRequire (CJS) to bypass ESM's module cache — a failed
- * ESM import is permanently cached, but CJS require cache entries
- * can be deleted and re-required.
- */
-export async function reloadPty(): Promise<boolean> {
-  if (pty) return true;
-  try {
-    const require = createRequire(import.meta.url);
-    // Clear any cached failure so require() retries the native load
-    const resolved = require.resolve('node-pty');
-    delete require.cache[resolved];
-    pty = require('node-pty');
-    _ptyLoadError = null;
-    console.log('[PTYManager] node-pty loaded successfully after reload');
-    return true;
-  } catch (error: unknown) {
-    _ptyLoadError = error instanceof Error ? error.message : 'Failed to load node-pty';
-    return false;
-  }
-}
-
-/**
- * Get installation instructions for node-pty based on platform
- */
-export function getPtyInstallInstructions(): string {
-  const os = platform();
-
-  let instructions = `Terminal feature requires native compilation of node-pty.\n\n`;
-  instructions += `To enable this feature:\n\n`;
-
-  if (os === 'darwin') {
-    instructions += `1. Install Xcode Command Line Tools:\n`;
-    instructions += `   xcode-select --install\n\n`;
-  } else if (os === 'win32') {
-    instructions += `1. Install Windows Build Tools:\n`;
-    instructions += `   npm install -g windows-build-tools\n\n`;
-  } else {
-    // Linux
-    instructions += `1. Install build tools:\n`;
-    instructions += `   # Debian/Ubuntu:\n`;
-    instructions += `   sudo apt install build-essential python3\n\n`;
-    instructions += `   # Fedora/RHEL:\n`;
-    instructions += `   sudo dnf install gcc-c++ make python3\n\n`;
-    instructions += `   # Arch:\n`;
-    instructions += `   sudo pacman -S base-devel python\n\n`;
-  }
-
-  instructions += `2. Rebuild native modules:\n`;
-  instructions += `   npm rebuild node-pty\n\n`;
-  instructions += `3. Restart mstro\n`;
-
-  return instructions;
-}
-
-// Import type separately for type-checking (doesn't require the module to load)
-type IPty = import('node-pty').IPty;
-
-/**
- * Fixed-size buffer that retains the most recent PTY output for replay on reconnect.
- * Stores raw string chunks and evicts oldest data when the total exceeds maxBytes.
- */
-class ScrollbackBuffer {
-  private chunks: string[] = [];
-  private totalLength = 0;
-  private maxBytes: number;
-
-  constructor(maxBytes: number) {
-    this.maxBytes = maxBytes;
-  }
-
-  append(data: string): void {
-    this.chunks.push(data);
-    this.totalLength += data.length;
-    // Evict oldest chunks until under budget
-    while (this.totalLength > this.maxBytes && this.chunks.length > 1) {
-      const removed = this.chunks.shift()!;
-      this.totalLength -= removed.length;
-    }
-    // If a single chunk exceeds max, truncate from the front
-    if (this.totalLength > this.maxBytes && this.chunks.length === 1) {
-      const excess = this.totalLength - this.maxBytes;
-      this.chunks[0] = this.chunks[0].slice(excess);
-      this.totalLength = this.chunks[0].length;
-    }
-  }
-
-  getContents(): string {
-    return this.chunks.join('');
-  }
-
-  clear(): void {
-    this.chunks = [];
-    this.totalLength = 0;
-  }
-}
-
-const SCROLLBACK_MAX_BYTES = 256 * 1024; // 256KB
-
-export interface PTYSession {
-  id: string;
-  pty: IPty;
-  shell: string;
-  cwd: string;
-  // Timestamp when session was created
-  createdAt: number;
-  // Last activity timestamp
-  lastActivityAt: number;
-  // Current dimensions
-  cols: number;
-  rows: number;
-  // Output coalescing: buffer small chunks into fewer WS messages
-  _outputBuffer: string;
-  _outputTimer: ReturnType<typeof setTimeout> | null;
-  // Scrollback ring buffer for replay on reconnect
-  scrollback: ScrollbackBuffer;
-}
-
-/**
- * Detect the user's default shell
- */
-function detectShell(): string {
-  const shell = process.env.SHELL;
-
-  if (shell) {
-    return shell;
-  }
-
-  // Platform-specific defaults
-  if (platform() === 'win32') {
-    return process.env.COMSPEC || 'powershell.exe';
-  }
-
-  return '/bin/bash';
-}
-
-/**
- * Get shell name from path
- */
-function getShellName(shellPath: string): string {
-  const parts = shellPath.split(/[/\\]/);
-  return parts[parts.length - 1] || 'shell';
-}
+import type { PTYSession } from './pty-utils.js';
+import {
+  detectShell,
+  getPty,
+  getPtyInstallInstructions,
+  getShellName,
+  isPtyAvailable,
+  SCROLLBACK_MAX_BYTES,
+  ScrollbackBuffer,
+} from './pty-utils.js';
+
+export type { PTYSession } from './pty-utils.js';
+// Re-export public API for backward compatibility
+export { isPtyAvailable, reloadPty } from './pty-utils.js';
 
 export class PTYManager extends EventEmitter {
   private terminals: Map<string, PTYSession> = new Map();
 
   constructor() {
     super();
-    // Each terminal adds 3 listeners (output, exit, error) to this singleton.
-    // With multiple terminals, the default limit of 10 is easily exceeded.
     this.setMaxListeners(50);
   }
 
-  /**
-   * Check if a terminal session exists and is still running
-   */
   exists(terminalId: string): boolean {
     return this.terminals.has(terminalId);
   }
 
-  /**
-   * Get session info for reconnection
-   * Returns null if session doesn't exist
-   */
   getSessionInfo(terminalId: string): { shell: string; cwd: string; cols: number; rows: number } | null {
     const session = this.terminals.get(terminalId);
     if (!session) return null;
-    return {
-      shell: session.shell,
-      cwd: session.cwd,
-      cols: session.cols,
-      rows: session.rows,
-    };
+    return { shell: session.shell, cwd: session.cwd, cols: session.cols, rows: session.rows };
   }
 
-  /**
-   * Check if PTY functionality is available
-   */
   isPtyAvailable(): boolean {
     return isPtyAvailable();
   }
 
-  /**
-   * Get installation instructions if PTY is not available
-   */
   getPtyInstallInstructions(): string {
     return getPtyInstallInstructions();
   }
 
-  /**
-   * Create a new terminal session
-   */
   create(
     terminalId: string,
     workingDir: string,
@@ -245,52 +60,30 @@ export class PTYManager extends EventEmitter {
     requestedShell?: string,
     options?: { sandboxed?: boolean }
   ): { shell: string; cwd: string; isReconnect: boolean; platform: string } {
-    // Check if node-pty is available
+    const pty = getPty();
     if (!pty) {
       throw new Error(`PTY_NOT_AVAILABLE:${getPtyInstallInstructions()}`);
     }
 
-    // Check if session already exists - if so, this is a reconnection
+    // Reconnect to existing session
     if (this.terminals.has(terminalId)) {
       const existingSession = this.terminals.get(terminalId)!;
-
-      // Always resize on reconnect to trigger SIGWINCH, which causes the
-      // shell to redraw its prompt line for the reconnected client
       existingSession.pty.resize(cols, rows);
       existingSession.cols = cols;
       existingSession.rows = rows;
-
-      return {
-        shell: existingSession.shell,
-        cwd: existingSession.cwd,
-        isReconnect: true,
-        platform: platform(),
-      };
+      return { shell: existingSession.shell, cwd: existingSession.cwd, isReconnect: true, platform: platform() };
     }
 
     const shell = requestedShell || detectShell();
     const cwd = workingDir || homedir();
 
-
     try {
-      // Build env: sandboxed sessions get stripped secrets and HOME=projectDir
       const baseEnv = options?.sandboxed
         ? sanitizeEnvForSandbox(process.env, cwd)
         : { ...process.env, HOME: homedir() };
-      const env = {
-        ...baseEnv,
-        TERM: 'xterm-256color',
-        COLORTERM: 'truecolor',
-      };
+      const env = { ...baseEnv, TERM: 'xterm-256color', COLORTERM: 'truecolor' };
 
-      // Spawn the PTY process
-      const ptyProcess = pty.spawn(shell, [], {
-        name: 'xterm-256color',
-        cols,
-        rows,
-        cwd,
-        env,
-      });
+      const ptyProcess = pty.spawn(shell, [], { name: 'xterm-256color', cols, rows, cwd, env });
 
       const session: PTYSession = {
         id: terminalId,
@@ -307,56 +100,7 @@ export class PTYManager extends EventEmitter {
       };
       this.terminals.set(terminalId, session);
 
-      // Handle data output — coalesce small chunks to reduce WebSocket message count.
-      // On macOS, node-pty emits many tiny chunks (sometimes single bytes) and zsh
-      // wraps echoed chars in multi-part ANSI sequences (RPROMPT, syntax highlighting).
-      // A longer window on macOS ensures these multi-part sequences arrive as one chunk,
-      // which the browser's predictive echo can match correctly.
-      // 32ms on macOS captures full zsh redraw cycles (RPROMPT + syntax highlighting)
-      // that 24ms often split across coalesce boundaries.
-      const OUTPUT_COALESCE_MS = platform() === 'darwin' ? 32 : 8;
-      // High-water mark: flush immediately when buffer exceeds this size
-      // to prevent unbounded memory growth during high-output commands (e.g. `yes`)
-      const OUTPUT_HIGH_WATER = 64 * 1024; // 64KB
-      // Maximum chunk size per WebSocket message to prevent browser overload
-      const OUTPUT_CHUNK_SIZE = 64 * 1024;
-
-      const flushOutputBuffer = () => {
-        if (session._outputTimer) {
-          clearTimeout(session._outputTimer);
-          session._outputTimer = null;
-        }
-        const buffered = session._outputBuffer;
-        session._outputBuffer = '';
-        // Chunk large output to prevent single massive WebSocket frames
-        for (let i = 0; i < buffered.length; i += OUTPUT_CHUNK_SIZE) {
-          this.emit('output', terminalId, buffered.slice(i, i + OUTPUT_CHUNK_SIZE));
-        }
-      };
-
-      ptyProcess.onData((data: string) => {
-        session.scrollback.append(data);
-        session.lastActivityAt = Date.now();
-        session._outputBuffer += data;
-        // Flush immediately if buffer exceeds high-water mark
-        if (session._outputBuffer.length >= OUTPUT_HIGH_WATER) {
-          flushOutputBuffer();
-        } else if (!session._outputTimer) {
-          session._outputTimer = setTimeout(flushOutputBuffer, OUTPUT_COALESCE_MS);
-        }
-      });
-
-      // Handle exit — flush any buffered output first
-      ptyProcess.onExit(({ exitCode }) => {
-        if (session._outputBuffer) {
-          flushOutputBuffer();
-        } else if (session._outputTimer) {
-          clearTimeout(session._outputTimer);
-          session._outputTimer = null;
-        }
-        this.emit('exit', terminalId, exitCode);
-        this.terminals.delete(terminalId);
-      });
+      this.attachOutputHandlers(session, terminalId);
 
       return { shell: session.shell, cwd, isReconnect: false, platform: platform() };
     } catch (error: unknown) {
@@ -366,16 +110,53 @@ export class PTYManager extends EventEmitter {
     }
   }
 
-  /**
-   * Write input data to terminal
-   */
+  private attachOutputHandlers(session: PTYSession, terminalId: string): void {
+    // Output coalescing constants
+    const OUTPUT_COALESCE_MS = platform() === 'darwin' ? 32 : 8;
+    const OUTPUT_HIGH_WATER = 64 * 1024;
+    const OUTPUT_CHUNK_SIZE = 64 * 1024;
+
+    const flushOutputBuffer = () => {
+      if (session._outputTimer) {
+        clearTimeout(session._outputTimer);
+        session._outputTimer = null;
+      }
+      const buffered = session._outputBuffer;
+      session._outputBuffer = '';
+      for (let i = 0; i < buffered.length; i += OUTPUT_CHUNK_SIZE) {
+        this.emit('output', terminalId, buffered.slice(i, i + OUTPUT_CHUNK_SIZE));
+      }
+    };
+
+    session.pty.onData((data: string) => {
+      session.scrollback.append(data);
+      session.lastActivityAt = Date.now();
+      session._outputBuffer += data;
+      if (session._outputBuffer.length >= OUTPUT_HIGH_WATER) {
+        flushOutputBuffer();
+      } else if (!session._outputTimer) {
+        session._outputTimer = setTimeout(flushOutputBuffer, OUTPUT_COALESCE_MS);
+      }
+    });
+
+    session.pty.onExit(({ exitCode }) => {
+      if (session._outputBuffer) {
+        flushOutputBuffer();
+      } else if (session._outputTimer) {
+        clearTimeout(session._outputTimer);
+        session._outputTimer = null;
+      }
+      this.emit('exit', terminalId, exitCode);
+      this.terminals.delete(terminalId);
+    });
+  }
+
   write(terminalId: string, data: string): boolean {
     const session = this.terminals.get(terminalId);
     if (!session) {
       console.warn(`[PTYManager] Terminal ${terminalId} not found for write`);
       return false;
     }
-
     try {
       session.pty.write(data);
       return true;
@@ -386,16 +167,12 @@ export class PTYManager extends EventEmitter {
     }
   }
 
-  /**
-   * Resize terminal
-   */
   resize(terminalId: string, cols: number, rows: number): boolean {
     const session = this.terminals.get(terminalId);
     if (!session) {
       console.warn(`[PTYManager] Terminal ${terminalId} not found for resize`);
       return false;
     }
-
     try {
       session.pty.resize(cols, rows);
       return true;
@@ -405,18 +182,10 @@ export class PTYManager extends EventEmitter {
     }
   }
 
-  /**
-   * Close terminal session
-   */
   close(terminalId: string): boolean {
     const session = this.terminals.get(terminalId);
-    if (!session) {
-      return false;
-    }
-
-
+    if (!session) return false;
     try {
-      // Flush any coalesced output before closing
       if (session._outputTimer) {
         clearTimeout(session._outputTimer);
         if (session._outputBuffer) {
@@ -435,45 +204,29 @@ export class PTYManager extends EventEmitter {
     }
   }
 
-  /**
-   * Get scrollback buffer contents for replay on reconnect
-   */
   getScrollback(terminalId: string): string | null {
     const session = this.terminals.get(terminalId);
     if (!session) return null;
     return session.scrollback.getContents();
   }
 
-  /**
-   * Get terminal session info
-   */
   getSession(terminalId: string): PTYSession | undefined {
     return this.terminals.get(terminalId);
   }
 
-  /**
-   * Check if terminal exists
-   */
   has(terminalId: string): boolean {
     return this.terminals.has(terminalId);
   }
 
-  /**
-   * Get all active terminal IDs
-   */
   getActiveTerminals(): string[] {
     return Array.from(this.terminals.keys());
   }
 
-  /**
-   * Close all terminals
-   */
   closeAll(): void {
     for (const terminalId of this.terminals.keys()) {
       this.close(terminalId);
     }
   }
-
 }
 
 // Singleton instance

package/server/services/terminal/pty-utils.ts

@@ -0,0 +1,176 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * PTY Utilities — node-pty loading, shell detection, scrollback buffer, and types.
+ *
+ * Separated from pty-manager.ts so the PTYManager class stays focused
+ * on session lifecycle orchestration.
+ */
+
+import { createRequire } from 'node:module';
+import { platform } from 'node:os';
+
+// ── node-pty loading ──────────────────────────────────────────
+
+// Try to load node-pty (optional native dependency)
+let pty: typeof import('node-pty') | null = null;
+let _ptyLoadError: string | null = null;
+
+try {
+  pty = await import('node-pty');
+} catch (error: unknown) {
+  _ptyLoadError = error instanceof Error ? error.message : 'Failed to load node-pty';
+  console.warn('[PTYManager] node-pty not available - terminal features disabled');
+  console.warn('[PTYManager] To enable terminals, run: mstro setup-terminal');
+}
+
+export function getPty(): typeof import('node-pty') | null {
+  return pty;
+}
+
+/**
+ * Check if node-pty is available
+ */
+export function isPtyAvailable(): boolean {
+  return pty !== null;
+}
+
+/**
+ * Re-attempt loading node-pty at runtime.
+ * Called after `mstro setup-terminal` compiles the native module
+ * so the running server can pick it up without a restart.
+ *
+ * Uses createRequire (CJS) to bypass ESM's module cache — a failed
+ * ESM import is permanently cached, but CJS require cache entries
+ * can be deleted and re-required.
+ */
+export async function reloadPty(): Promise<boolean> {
+  if (pty) return true;
+  try {
+    const require = createRequire(import.meta.url);
+    const resolved = require.resolve('node-pty');
+    delete require.cache[resolved];
+    pty = require('node-pty');
+    _ptyLoadError = null;
+    console.log('[PTYManager] node-pty loaded successfully after reload');
+    return true;
+  } catch (error: unknown) {
+    _ptyLoadError = error instanceof Error ? error.message : 'Failed to load node-pty';
+    return false;
+  }
+}
+
+/**
+ * Get installation instructions for node-pty based on platform
+ */
+export function getPtyInstallInstructions(): string {
+  const os = platform();
+
+  let instructions = `Terminal feature requires native compilation of node-pty.\n\n`;
+  instructions += `To enable this feature:\n\n`;
+
+  if (os === 'darwin') {
+    instructions += `1. Install Xcode Command Line Tools:\n`;
+    instructions += `   xcode-select --install\n\n`;
+  } else if (os === 'win32') {
+    instructions += `1. Install Windows Build Tools:\n`;
+    instructions += `   npm install -g windows-build-tools\n\n`;
+  } else {
+    instructions += `1. Install build tools:\n`;
+    instructions += `   # Debian/Ubuntu:\n`;
+    instructions += `   sudo apt install build-essential python3\n\n`;
+    instructions += `   # Fedora/RHEL:\n`;
+    instructions += `   sudo dnf install gcc-c++ make python3\n\n`;
+    instructions += `   # Arch:\n`;
+    instructions += `   sudo pacman -S base-devel python\n\n`;
+  }
+
+  instructions += `2. Rebuild native modules:\n`;
+  instructions += `   npm rebuild node-pty\n\n`;
+  instructions += `3. Restart mstro\n`;
+
+  return instructions;
+}
+
+// ── Shell detection ───────────────────────────────────────────
+
+/**
+ * Detect the user's default shell
+ */
+export function detectShell(): string {
+  const shell = process.env.SHELL;
+  if (shell) return shell;
+  if (platform() === 'win32') {
+    return process.env.COMSPEC || 'powershell.exe';
+  }
+  return '/bin/bash';
+}
+
+/**
+ * Get shell name from path
+ */
+export function getShellName(shellPath: string): string {
+  const parts = shellPath.split(/[/\\]/);
+  return parts[parts.length - 1] || 'shell';
+}
+
+// ── Scrollback buffer ─────────────────────────────────────────
+
+export const SCROLLBACK_MAX_BYTES = 256 * 1024; // 256KB
+
+/**
+ * Fixed-size buffer that retains the most recent PTY output for replay on reconnect.
+ * Stores raw string chunks and evicts oldest data when the total exceeds maxBytes.
+ */
+export class ScrollbackBuffer {
+  private chunks: string[] = [];
+  private totalLength = 0;
+  private maxBytes: number;
+
+  constructor(maxBytes: number) {
+    this.maxBytes = maxBytes;
+  }
+
+  append(data: string): void {
+    this.chunks.push(data);
+    this.totalLength += data.length;
+    while (this.totalLength > this.maxBytes && this.chunks.length > 1) {
+      const removed = this.chunks.shift()!;
+      this.totalLength -= removed.length;
+    }
+    if (this.totalLength > this.maxBytes && this.chunks.length === 1) {
+      const excess = this.totalLength - this.maxBytes;
+      this.chunks[0] = this.chunks[0].slice(excess);
+      this.totalLength = this.chunks[0].length;
+    }
+  }
+
+  getContents(): string {
+    return this.chunks.join('');
+  }
+
+  clear(): void {
+    this.chunks = [];
+    this.totalLength = 0;
+  }
+}
+
+// ── Types ─────────────────────────────────────────────────────
+
+// Import type separately for type-checking (doesn't require the module to load)
+type IPty = import('node-pty').IPty;
+
+export interface PTYSession {
+  id: string;
+  pty: IPty;
+  shell: string;
+  cwd: string;
+  createdAt: number;
+  lastActivityAt: number;
+  cols: number;
+  rows: number;
+  _outputBuffer: string;
+  _outputTimer: ReturnType<typeof setTimeout> | null;
+  scrollback: ScrollbackBuffer;
+}