crewly 1.0.0

package/dist/backend/backend/src/services/session/pty/pty-session-backend.d.ts

@@ -0,0 +1,258 @@
+/**
+ * PTY Session Backend Module
+ *
+ * Implements the ISessionBackend interface using node-pty and @xterm/headless.
+ * Provides a full terminal emulation backend with memory-bounded output buffers.
+ *
+ * @module pty-session-backend
+ */
+import type { ISessionBackend, ISession, SessionOptions } from '../session-backend.interface.js';
+import { PtyTerminalBuffer } from './pty-terminal-buffer.js';
+/**
+ * PTY Session Backend implementation.
+ *
+ * Manages terminal sessions using node-pty for process spawning and
+ * @xterm/headless for terminal emulation and output buffering.
+ *
+ * Features:
+ * - In-memory session management via Map
+ * - Terminal emulation with xterm.js headless
+ * - Memory-bounded output buffers (max 10MB)
+ * - Proper cleanup on session termination
+ *
+ * @example
+ * ```typescript
+ * const backend = new PtySessionBackend();
+ *
+ * // Create a session
+ * const session = await backend.createSession('dev', {
+ *   cwd: '/home/user/project',
+ *   command: '/bin/bash',
+ * });
+ *
+ * // Capture output
+ * const output = backend.captureOutput('dev', 50);
+ *
+ * // Cleanup
+ * await backend.destroy();
+ * ```
+ */
+export declare class PtySessionBackend implements ISessionBackend {
+    /**
+     * Map of session names to PtySession instances
+     */
+    private sessions;
+    /**
+     * Map of session names to PtyTerminalBuffer instances
+     */
+    private terminalBuffers;
+    /**
+     * Logger for this backend
+     */
+    private logger;
+    /**
+     * Create a new PTY session backend.
+     */
+    constructor();
+    /**
+     * Create a new terminal session.
+     *
+     * @param name - Unique name for the session
+     * @param options - Session configuration options
+     * @returns Promise resolving to the created session
+     * @throws Error if session name already exists
+     *
+     * @example
+     * ```typescript
+     * const session = await backend.createSession('my-session', {
+     *   cwd: '/home/user',
+     *   command: '/bin/bash',
+     *   args: ['--login'],
+     *   env: { NODE_ENV: 'development' },
+     *   cols: 120,
+     *   rows: 40,
+     * });
+     * ```
+     */
+    createSession(name: string, options: SessionOptions): Promise<ISession>;
+    /**
+     * Get an existing session by name.
+     *
+     * @param name - Name of the session to retrieve
+     * @returns The session if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const session = backend.getSession('my-session');
+     * if (session) {
+     *   session.write('echo hello\n');
+     * }
+     * ```
+     */
+    getSession(name: string): ISession | undefined;
+    /**
+     * Kill a session by name.
+     *
+     * @param name - Name of the session to kill
+     * @returns Promise that resolves when the session is killed
+     *
+     * @example
+     * ```typescript
+     * await backend.killSession('my-session');
+     * ```
+     */
+    killSession(name: string): Promise<void>;
+    /**
+     * List all active session names.
+     *
+     * @returns Array of session names
+     *
+     * @example
+     * ```typescript
+     * const sessions = backend.listSessions();
+     * console.log('Active sessions:', sessions);
+     * ```
+     */
+    listSessions(): string[];
+    /**
+     * Check if a session exists by name.
+     *
+     * @param name - Name of the session to check
+     * @returns true if the session exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (backend.sessionExists('my-session')) {
+     *   console.log('Session is running');
+     * }
+     * ```
+     */
+    sessionExists(name: string): boolean;
+    /**
+     * Capture recent output from a session.
+     *
+     * @param name - Name of the session
+     * @param lines - Number of lines to capture (default: 100)
+     * @returns Captured output as a string
+     *
+     * @example
+     * ```typescript
+     * const output = backend.captureOutput('my-session', 50);
+     * console.log('Recent output:', output);
+     * ```
+     */
+    captureOutput(name: string, lines?: number): string;
+    /**
+     * Get the full terminal buffer content for a session.
+     *
+     * @param name - Name of the session
+     * @returns Full buffer content as a string
+     *
+     * @example
+     * ```typescript
+     * const buffer = backend.getTerminalBuffer('my-session');
+     * console.log('Full buffer:', buffer);
+     * ```
+     */
+    getTerminalBuffer(name: string): string;
+    /**
+     * Get raw output history with ANSI escape codes preserved.
+     *
+     * @param name - Name of the session
+     * @returns Raw output history as a string with ANSI codes
+     *
+     * @example
+     * ```typescript
+     * const rawHistory = backend.getRawHistory('my-session');
+     * terminal.write(rawHistory);
+     * ```
+     */
+    getRawHistory(name: string): string;
+    /**
+     * Get the PIDs of all active sessions.
+     *
+     * @returns Array of process IDs for all active sessions
+     *
+     * @example
+     * ```typescript
+     * const pids = backend.getAllSessionPids();
+     * console.log('Active PIDs:', pids);
+     * ```
+     */
+    getAllSessionPids(): number[];
+    /**
+     * Destroy the backend and clean up all resources.
+     *
+     * @returns Promise that resolves when cleanup is complete
+     *
+     * @example
+     * ```typescript
+     * await backend.destroy();
+     * ```
+     */
+    destroy(): Promise<void>;
+    /**
+     * Forcefully destroy all sessions with SIGTERM → SIGKILL escalation.
+     *
+     * This method is designed for shutdown scenarios where child processes
+     * (Claude Code, Gemini CLI) may catch or ignore SIGHUP/SIGTERM.
+     * It collects all PIDs upfront, sends SIGTERM, waits, then SIGKILLs
+     * each process and its process group.
+     *
+     * @returns Promise that resolves after the force-kill sequence completes
+     *
+     * @example
+     * ```typescript
+     * await backend.forceDestroyAll();
+     * ```
+     */
+    forceDestroyAll(): Promise<void>;
+    /**
+     * Check if a child process is alive inside a session's PTY shell.
+     *
+     * Delegates to PtySession.isChildProcessAlive() to detect whether
+     * the runtime (e.g. Claude Code) is still running inside the shell.
+     *
+     * @param name - Name of the session to check
+     * @returns true if the session exists and has a living child process
+     */
+    isChildProcessAlive(name: string): boolean;
+    /**
+     * Get the number of active sessions.
+     *
+     * @returns Number of active sessions
+     */
+    getSessionCount(): number;
+    /**
+     * Resize a session's terminal.
+     *
+     * @param name - Name of the session
+     * @param cols - Number of columns
+     * @param rows - Number of rows
+     * @throws Error if session does not exist
+     */
+    resizeSession(name: string, cols: number, rows: number): void;
+    /**
+     * Get the raw output history for a session.
+     *
+     * This returns the raw bytes written to the terminal, including ANSI
+     * sequences. Useful for replaying the session.
+     *
+     * @param name - Name of the session
+     * @returns Raw output history as a string
+     *
+     * @example
+     * ```typescript
+     * const history = backend.getSessionHistory('my-session');
+     * ```
+     */
+    getSessionHistory(name: string): string;
+    /**
+     * Get the terminal buffer instance for a session.
+     *
+     * @param name - Name of the session
+     * @returns The PtyTerminalBuffer instance if found, undefined otherwise
+     */
+    getTerminalBufferInstance(name: string): PtyTerminalBuffer | undefined;
+}
+//# sourceMappingURL=pty-session-backend.d.ts.map

package/dist/backend/backend/src/services/session/pty/pty-session-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty-session-backend.d.ts","sourceRoot":"","sources":["../../../../../../../backend/src/services/session/pty/pty-session-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAMjG,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAI7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IACxD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAsC;IAEtD;;OAEG;IACH,OAAO,CAAC,eAAe,CAA6C;IAEpE;;OAEG;IACH,OAAO,CAAC,MAAM,CAAkB;IAEhC;;OAEG;;IAMH;;;;;;;;;;;;;;;;;;;OAmBG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IA4C7E;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAI9C;;;;;;;;;;OAUG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB9C;;;;;;;;;;OAUG;IACH,YAAY,IAAI,MAAM,EAAE;IAIxB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIpC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,MAAM;IAShD;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IASvC;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IASnC;;;;;;;;;;OAUG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAc7B;;;;;;;;;OASG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAc9B;;;;;;;;;;;;;;OAcG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAyDtC;;;;;;;;OAQG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAQ1C;;;;OAIG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;;OAOG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAgB7D;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IASvC;;;;;OAKG;IACH,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;CAGtE"}

package/dist/backend/backend/src/services/session/pty/pty-session-backend.js

@@ -0,0 +1,435 @@
+/**
+ * PTY Session Backend Module
+ *
+ * Implements the ISessionBackend interface using node-pty and @xterm/headless.
+ * Provides a full terminal emulation backend with memory-bounded output buffers.
+ *
+ * @module pty-session-backend
+ */
+import { DEFAULT_TERMINAL_COLS, DEFAULT_TERMINAL_ROWS, } from '../session-backend.interface.js';
+import { PtySession } from './pty-session.js';
+import { PtyTerminalBuffer } from './pty-terminal-buffer.js';
+import { LoggerService } from '../../core/logger.service.js';
+import { PTY_CONSTANTS } from '../../../constants.js';
+/**
+ * PTY Session Backend implementation.
+ *
+ * Manages terminal sessions using node-pty for process spawning and
+ * @xterm/headless for terminal emulation and output buffering.
+ *
+ * Features:
+ * - In-memory session management via Map
+ * - Terminal emulation with xterm.js headless
+ * - Memory-bounded output buffers (max 10MB)
+ * - Proper cleanup on session termination
+ *
+ * @example
+ * ```typescript
+ * const backend = new PtySessionBackend();
+ *
+ * // Create a session
+ * const session = await backend.createSession('dev', {
+ *   cwd: '/home/user/project',
+ *   command: '/bin/bash',
+ * });
+ *
+ * // Capture output
+ * const output = backend.captureOutput('dev', 50);
+ *
+ * // Cleanup
+ * await backend.destroy();
+ * ```
+ */
+export class PtySessionBackend {
+    /**
+     * Map of session names to PtySession instances
+     */
+    sessions = new Map();
+    /**
+     * Map of session names to PtyTerminalBuffer instances
+     */
+    terminalBuffers = new Map();
+    /**
+     * Logger for this backend
+     */
+    logger;
+    /**
+     * Create a new PTY session backend.
+     */
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('PtySessionBackend');
+        this.logger.info('PTY session backend initialized');
+    }
+    /**
+     * Create a new terminal session.
+     *
+     * @param name - Unique name for the session
+     * @param options - Session configuration options
+     * @returns Promise resolving to the created session
+     * @throws Error if session name already exists
+     *
+     * @example
+     * ```typescript
+     * const session = await backend.createSession('my-session', {
+     *   cwd: '/home/user',
+     *   command: '/bin/bash',
+     *   args: ['--login'],
+     *   env: { NODE_ENV: 'development' },
+     *   cols: 120,
+     *   rows: 40,
+     * });
+     * ```
+     */
+    async createSession(name, options) {
+        if (this.sessions.has(name)) {
+            throw new Error(`Session '${name}' already exists`);
+        }
+        this.logger.info('Creating PTY session', {
+            name,
+            command: options.command,
+            cwd: options.cwd,
+        });
+        // Create the PTY session
+        const session = new PtySession(name, options.cwd, options);
+        // Create terminal buffer for output buffering and history
+        const cols = options.cols ?? DEFAULT_TERMINAL_COLS;
+        const rows = options.rows ?? DEFAULT_TERMINAL_ROWS;
+        const terminalBuffer = new PtyTerminalBuffer(cols, rows);
+        // Pipe session output to terminal buffer
+        session.onData((data) => {
+            terminalBuffer.write(data);
+        });
+        // Clean up on session exit
+        session.onExit((code) => {
+            this.logger.info('Session exited', { name, exitCode: code });
+            // Don't delete here - let the session remain accessible until explicitly killed
+        });
+        // Store session and terminal buffer
+        this.sessions.set(name, session);
+        this.terminalBuffers.set(name, terminalBuffer);
+        this.logger.info('PTY session created', {
+            name,
+            pid: session.pid,
+            cols,
+            rows,
+        });
+        return session;
+    }
+    /**
+     * Get an existing session by name.
+     *
+     * @param name - Name of the session to retrieve
+     * @returns The session if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const session = backend.getSession('my-session');
+     * if (session) {
+     *   session.write('echo hello\n');
+     * }
+     * ```
+     */
+    getSession(name) {
+        return this.sessions.get(name);
+    }
+    /**
+     * Kill a session by name.
+     *
+     * @param name - Name of the session to kill
+     * @returns Promise that resolves when the session is killed
+     *
+     * @example
+     * ```typescript
+     * await backend.killSession('my-session');
+     * ```
+     */
+    async killSession(name) {
+        const session = this.sessions.get(name);
+        const terminalBuffer = this.terminalBuffers.get(name);
+        if (session) {
+            this.logger.info('Killing session', { name });
+            session.kill();
+            this.sessions.delete(name);
+        }
+        if (terminalBuffer) {
+            terminalBuffer.dispose();
+            this.terminalBuffers.delete(name);
+        }
+        this.logger.debug('Session resources cleaned up', { name });
+    }
+    /**
+     * List all active session names.
+     *
+     * @returns Array of session names
+     *
+     * @example
+     * ```typescript
+     * const sessions = backend.listSessions();
+     * console.log('Active sessions:', sessions);
+     * ```
+     */
+    listSessions() {
+        return Array.from(this.sessions.keys());
+    }
+    /**
+     * Check if a session exists by name.
+     *
+     * @param name - Name of the session to check
+     * @returns true if the session exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (backend.sessionExists('my-session')) {
+     *   console.log('Session is running');
+     * }
+     * ```
+     */
+    sessionExists(name) {
+        return this.sessions.has(name);
+    }
+    /**
+     * Capture recent output from a session.
+     *
+     * @param name - Name of the session
+     * @param lines - Number of lines to capture (default: 100)
+     * @returns Captured output as a string
+     *
+     * @example
+     * ```typescript
+     * const output = backend.captureOutput('my-session', 50);
+     * console.log('Recent output:', output);
+     * ```
+     */
+    captureOutput(name, lines = 100) {
+        const terminalBuffer = this.terminalBuffers.get(name);
+        if (!terminalBuffer) {
+            return '';
+        }
+        return terminalBuffer.getContent(lines);
+    }
+    /**
+     * Get the full terminal buffer content for a session.
+     *
+     * @param name - Name of the session
+     * @returns Full buffer content as a string
+     *
+     * @example
+     * ```typescript
+     * const buffer = backend.getTerminalBuffer('my-session');
+     * console.log('Full buffer:', buffer);
+     * ```
+     */
+    getTerminalBuffer(name) {
+        const terminalBuffer = this.terminalBuffers.get(name);
+        if (!terminalBuffer) {
+            return '';
+        }
+        return terminalBuffer.getAllContent();
+    }
+    /**
+     * Get raw output history with ANSI escape codes preserved.
+     *
+     * @param name - Name of the session
+     * @returns Raw output history as a string with ANSI codes
+     *
+     * @example
+     * ```typescript
+     * const rawHistory = backend.getRawHistory('my-session');
+     * terminal.write(rawHistory);
+     * ```
+     */
+    getRawHistory(name) {
+        const terminalBuffer = this.terminalBuffers.get(name);
+        if (!terminalBuffer) {
+            return '';
+        }
+        return terminalBuffer.getHistoryAsString();
+    }
+    /**
+     * Get the PIDs of all active sessions.
+     *
+     * @returns Array of process IDs for all active sessions
+     *
+     * @example
+     * ```typescript
+     * const pids = backend.getAllSessionPids();
+     * console.log('Active PIDs:', pids);
+     * ```
+     */
+    getAllSessionPids() {
+        const pids = [];
+        for (const session of this.sessions.values()) {
+            if (!session.isKilled()) {
+                try {
+                    pids.push(session.pid);
+                }
+                catch {
+                    // PID may not be accessible if process already exited
+                }
+            }
+        }
+        return pids;
+    }
+    /**
+     * Destroy the backend and clean up all resources.
+     *
+     * @returns Promise that resolves when cleanup is complete
+     *
+     * @example
+     * ```typescript
+     * await backend.destroy();
+     * ```
+     */
+    async destroy() {
+        this.logger.info('Destroying PTY session backend', {
+            sessionCount: this.sessions.size,
+        });
+        // Kill all sessions
+        const sessionNames = Array.from(this.sessions.keys());
+        for (const name of sessionNames) {
+            await this.killSession(name);
+        }
+        this.logger.info('PTY session backend destroyed');
+    }
+    /**
+     * Forcefully destroy all sessions with SIGTERM → SIGKILL escalation.
+     *
+     * This method is designed for shutdown scenarios where child processes
+     * (Claude Code, Gemini CLI) may catch or ignore SIGHUP/SIGTERM.
+     * It collects all PIDs upfront, sends SIGTERM, waits, then SIGKILLs
+     * each process and its process group.
+     *
+     * @returns Promise that resolves after the force-kill sequence completes
+     *
+     * @example
+     * ```typescript
+     * await backend.forceDestroyAll();
+     * ```
+     */
+    async forceDestroyAll() {
+        const sessionCount = this.sessions.size;
+        if (sessionCount === 0) {
+            this.logger.debug('No sessions to force-destroy');
+            return;
+        }
+        this.logger.info('Force-destroying all PTY sessions', { sessionCount });
+        // Step 1: Collect all PIDs before sending any signals
+        const pids = this.getAllSessionPids();
+        this.logger.info('Collected PIDs for force-kill', { pids });
+        // Step 2: Send SIGTERM to each session via node-pty
+        for (const session of this.sessions.values()) {
+            try {
+                if (!session.isKilled()) {
+                    session.kill('SIGTERM');
+                }
+            }
+            catch (err) {
+                this.logger.debug('Error sending SIGTERM to session', {
+                    name: session.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        // Step 3: Wait for processes to exit gracefully
+        await new Promise((resolve) => setTimeout(resolve, PTY_CONSTANTS.FORCE_DESTROY_ESCALATION_DELAY));
+        // Step 4: SIGKILL each PID and its process group
+        for (const pid of pids) {
+            try {
+                process.kill(pid, 'SIGKILL');
+                this.logger.debug('Sent SIGKILL to process', { pid });
+            }
+            catch {
+                // ESRCH = process already gone
+            }
+            try {
+                process.kill(-pid, 'SIGKILL');
+                this.logger.debug('Sent SIGKILL to process group', { pgid: -pid });
+            }
+            catch {
+                // ESRCH = process group already gone
+            }
+        }
+        // Step 5: Clean up internal maps
+        for (const terminalBuffer of this.terminalBuffers.values()) {
+            terminalBuffer.dispose();
+        }
+        this.sessions.clear();
+        this.terminalBuffers.clear();
+        this.logger.info('Force-destroyed all PTY sessions');
+    }
+    /**
+     * Check if a child process is alive inside a session's PTY shell.
+     *
+     * Delegates to PtySession.isChildProcessAlive() to detect whether
+     * the runtime (e.g. Claude Code) is still running inside the shell.
+     *
+     * @param name - Name of the session to check
+     * @returns true if the session exists and has a living child process
+     */
+    isChildProcessAlive(name) {
+        const session = this.sessions.get(name);
+        if (!session) {
+            return false;
+        }
+        return session.isChildProcessAlive();
+    }
+    /**
+     * Get the number of active sessions.
+     *
+     * @returns Number of active sessions
+     */
+    getSessionCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Resize a session's terminal.
+     *
+     * @param name - Name of the session
+     * @param cols - Number of columns
+     * @param rows - Number of rows
+     * @throws Error if session does not exist
+     */
+    resizeSession(name, cols, rows) {
+        const session = this.sessions.get(name);
+        const terminalBuffer = this.terminalBuffers.get(name);
+        if (!session) {
+            throw new Error(`Session '${name}' does not exist`);
+        }
+        session.resize(cols, rows);
+        if (terminalBuffer) {
+            terminalBuffer.resize(cols, rows);
+        }
+        this.logger.debug('Session resized', { name, cols, rows });
+    }
+    /**
+     * Get the raw output history for a session.
+     *
+     * This returns the raw bytes written to the terminal, including ANSI
+     * sequences. Useful for replaying the session.
+     *
+     * @param name - Name of the session
+     * @returns Raw output history as a string
+     *
+     * @example
+     * ```typescript
+     * const history = backend.getSessionHistory('my-session');
+     * ```
+     */
+    getSessionHistory(name) {
+        const terminalBuffer = this.terminalBuffers.get(name);
+        if (!terminalBuffer) {
+            return '';
+        }
+        return terminalBuffer.getHistoryAsString();
+    }
+    /**
+     * Get the terminal buffer instance for a session.
+     *
+     * @param name - Name of the session
+     * @returns The PtyTerminalBuffer instance if found, undefined otherwise
+     */
+    getTerminalBufferInstance(name) {
+        return this.terminalBuffers.get(name);
+    }
+}
+//# sourceMappingURL=pty-session-backend.js.map