@seflless/ghosttown 1.6.1 → 1.7.0

package/src/session/session-manager.ts

@@ -0,0 +1,587 @@
+/**
+ * Session Manager
+ *
+ * Core session management without tmux. Handles:
+ * - Direct PTY spawning via node-pty
+ * - Session persistence to disk
+ * - Session restoration on server restart
+ * - Multi-client connections
+ */
+
+import { randomUUID } from 'crypto';
+import { EventEmitter } from 'events';
+import { existsSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import path from 'path';
+import type { IPty } from '@lydell/node-pty';
+import fs from 'fs/promises';
+
+import { HistoryReplay } from './history-replay.js';
+import { type OutputChunk, OutputRecorder } from './output-recorder.js';
+import type {
+  CreateSessionOptions,
+  Session,
+  SessionId,
+  SessionInfo,
+  SessionManagerConfig,
+  SessionPaths,
+} from './types.js';
+
+// Dynamic import for node-pty (CommonJS module)
+let ptyModule: typeof import('@lydell/node-pty') | null = null;
+
+async function getPty(): Promise<typeof import('@lydell/node-pty')> {
+  if (!ptyModule) {
+    ptyModule = await import('@lydell/node-pty');
+  }
+  return ptyModule;
+}
+
+/**
+ * Default configuration values.
+ */
+const DEFAULTS = {
+  storageDir: path.join(homedir(), '.config', 'ghosttown', 'sessions'),
+  scrollbackLimit: 10_000,
+  defaultShell: process.env.SHELL || '/bin/sh',
+  defaultCols: 80,
+  defaultRows: 24,
+};
+
+/**
+ * Get the default shell for the current platform.
+ */
+function getDefaultShell(): string {
+  if (process.platform === 'win32') {
+    return process.env.COMSPEC || 'cmd.exe';
+  }
+  return process.env.SHELL || '/bin/sh';
+}
+
+/**
+ * Get default environment variables for terminal sessions.
+ */
+function getDefaultEnv(): Record<string, string> {
+  return {
+    TERM: 'xterm-256color',
+    COLORTERM: 'truecolor',
+    LANG: process.env.LANG || 'en_US.UTF-8',
+    LC_ALL: process.env.LC_ALL || 'en_US.UTF-8',
+    TERM_PROGRAM: 'ghosttown',
+  };
+}
+
+/**
+ * SessionManager handles all session lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const manager = new SessionManager();
+ * await manager.init();
+ *
+ * // Create a new session
+ * const session = await manager.createSession({ name: 'dev' });
+ *
+ * // Get the PTY for I/O
+ * const pty = manager.getPty(session.id);
+ * pty.onData((data) => console.log(data));
+ * pty.write('echo hello\n');
+ *
+ * // List all sessions
+ * const sessions = await manager.listSessions();
+ *
+ * // Delete a session
+ * await manager.deleteSession(session.id);
+ * ```
+ */
+export class SessionManager extends EventEmitter {
+  private config: Required<SessionManagerConfig>;
+  private paths: SessionPaths;
+  private sessions: Map<SessionId, Session> = new Map();
+  private ptyProcesses: Map<SessionId, IPty> = new Map();
+  private outputRecorders: Map<SessionId, OutputRecorder> = new Map(); // Disk-backed scrollback
+  private initialized = false;
+
+  constructor(config: SessionManagerConfig = {}) {
+    super();
+
+    this.config = {
+      storageDir: config.storageDir ?? DEFAULTS.storageDir,
+      scrollbackLimit: config.scrollbackLimit ?? DEFAULTS.scrollbackLimit,
+      defaultShell: config.defaultShell ?? getDefaultShell(),
+    };
+
+    this.paths = {
+      baseDir: this.config.storageDir,
+      sessionDir: (id: SessionId) => path.join(this.config.storageDir, id),
+      metadataFile: (id: SessionId) => path.join(this.config.storageDir, id, 'metadata.json'),
+      scrollbackFile: (id: SessionId) => path.join(this.config.storageDir, id, 'scrollback.jsonl'),
+    };
+  }
+
+  /**
+   * Initialize the session manager.
+   * Loads persisted sessions from disk.
+   */
+  async init(): Promise<void> {
+    if (this.initialized) return;
+
+    // Ensure storage directory exists
+    if (!existsSync(this.paths.baseDir)) {
+      mkdirSync(this.paths.baseDir, { recursive: true });
+    }
+
+    // Load persisted sessions
+    await this.loadPersistedSessions();
+
+    this.initialized = true;
+  }
+
+  /**
+   * Create a new session.
+   */
+  async createSession(options: CreateSessionOptions = {}): Promise<Session> {
+    if (!this.initialized) {
+      throw new Error('SessionManager not initialized. Call init() first.');
+    }
+
+    const id = randomUUID();
+    const displayName = options.name ?? this.generateDisplayName();
+    const now = Date.now();
+
+    const session: Session = {
+      id,
+      displayName,
+      createdAt: now,
+      lastActivity: now,
+      process: {
+        pid: null,
+        shell: options.shell ?? this.config.defaultShell,
+        args: options.args ?? [],
+        cwd: options.cwd ?? homedir(),
+        env: {
+          ...getDefaultEnv(),
+          ...options.env,
+        },
+      },
+      terminal: {
+        cols: options.cols ?? DEFAULTS.defaultCols,
+        rows: options.rows ?? DEFAULTS.defaultRows,
+        cursorX: 0,
+        cursorY: 0,
+        cursorStyle: 'block',
+        cursorVisible: true,
+      },
+      scrollbackFile: 'scrollback.jsonl',
+      scrollbackLength: 0,
+      sharing: null,
+    };
+
+    // Create session directory
+    const sessionDir = this.paths.sessionDir(id);
+    mkdirSync(sessionDir, { recursive: true });
+
+    // Spawn PTY process if requested (default: true)
+    // Web sessions use startProcess: false to wait for client connection
+    if (options.startProcess !== false) {
+      await this.spawnProcess(session);
+    }
+
+    // Save to memory and disk
+    this.sessions.set(id, session);
+    await this.persistSession(session);
+
+    this.emit('session:created', session);
+
+    return session;
+  }
+
+  /**
+   * Get a session by ID.
+   */
+  getSession(sessionId: SessionId): Session | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  /**
+   * Get the PTY process for a session.
+   * Returns undefined if the process is not running.
+   */
+  getPty(sessionId: SessionId): IPty | undefined {
+    return this.ptyProcesses.get(sessionId);
+  }
+
+  /**
+   * List all sessions with summary info.
+   */
+  async listSessions(): Promise<SessionInfo[]> {
+    const sessions: SessionInfo[] = [];
+
+    for (const session of this.sessions.values()) {
+      sessions.push({
+        id: session.id,
+        displayName: session.displayName,
+        lastActivity: session.lastActivity,
+        isRunning: session.process.pid !== null,
+        connectionCount: 0, // TODO: Track connections
+        isShared: session.sharing?.enabled ?? false,
+      });
+    }
+
+    // Sort by last activity (most recent first)
+    sessions.sort((a, b) => b.lastActivity - a.lastActivity);
+
+    return sessions;
+  }
+
+  /**
+   * Delete a session and all associated data.
+   */
+  async deleteSession(sessionId: SessionId): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    // Kill the PTY process if running
+    const pty = this.ptyProcesses.get(sessionId);
+    if (pty) {
+      pty.kill();
+      this.ptyProcesses.delete(sessionId);
+    }
+
+    // Close the output recorder
+    const recorder = this.outputRecorders.get(sessionId);
+    if (recorder) {
+      await recorder.close();
+      this.outputRecorders.delete(sessionId);
+    }
+
+    // Remove from memory
+    this.sessions.delete(sessionId);
+
+    // Remove from disk
+    const sessionDir = this.paths.sessionDir(sessionId);
+    if (existsSync(sessionDir)) {
+      await fs.rm(sessionDir, { recursive: true, force: true });
+    }
+
+    this.emit('session:deleted', sessionId);
+  }
+
+  /**
+   * Rename a session.
+   */
+  async renameSession(sessionId: SessionId, newName: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    session.displayName = newName;
+    session.lastActivity = Date.now();
+    await this.persistSession(session);
+  }
+
+  /**
+   * Resize a session's terminal.
+   */
+  async resizeSession(sessionId: SessionId, cols: number, rows: number): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    // Update session state first
+    session.terminal.cols = cols;
+    session.terminal.rows = rows;
+    session.lastActivity = Date.now();
+
+    // Persist before attempting PTY resize (so state is saved even if PTY fails)
+    await this.persistSession(session);
+
+    // Try to resize the PTY (may fail if process exited)
+    const pty = this.ptyProcesses.get(sessionId);
+    if (pty) {
+      try {
+        pty.resize(cols, rows);
+      } catch {
+        // PTY may have exited, that's ok - state is already updated
+      }
+    }
+  }
+
+  /**
+   * Connect to a session, respawning the process if needed.
+   * Returns the PTY for I/O.
+   */
+  async connectToSession(sessionId: SessionId): Promise<IPty> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    // Respawn process if it's not running
+    const hasPty = this.ptyProcesses.has(sessionId);
+
+    if (!hasPty) {
+      await this.spawnProcess(session);
+    }
+
+    const pty = this.ptyProcesses.get(sessionId);
+    if (!pty) {
+      throw new Error(`Failed to get PTY for session: ${sessionId}`);
+    }
+
+    session.lastActivity = Date.now();
+    await this.persistSession(session);
+
+    return pty;
+  }
+
+  /**
+   * Write data to a session's PTY.
+   */
+  write(sessionId: SessionId, data: string): void {
+    const pty = this.ptyProcesses.get(sessionId);
+    if (!pty) {
+      throw new Error(`No PTY for session: ${sessionId}`);
+    }
+
+    pty.write(data);
+
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.lastActivity = Date.now();
+    }
+  }
+
+  /**
+   * Get the storage paths for session data.
+   */
+  getPaths(): SessionPaths {
+    return this.paths;
+  }
+
+  /**
+   * Get the buffered output for a session (for replay on reconnect).
+   * Returns the concatenated output as a single string.
+   * Note: This loads all scrollback into memory. For large histories,
+   * use getScrollbackChunks() instead.
+   */
+  async getScrollback(sessionId: SessionId): Promise<string> {
+    const recorder = this.outputRecorders.get(sessionId);
+    if (!recorder) {
+      return '';
+    }
+
+    const chunks = await recorder.readAll();
+    return chunks.map((c) => c.d).join('');
+  }
+
+  /**
+   * Get scrollback chunks for a session with pagination.
+   * @param sessionId Session ID
+   * @param offset Number of chunks to skip from the start
+   * @param limit Maximum number of chunks to return
+   */
+  async getScrollbackChunks(
+    sessionId: SessionId,
+    offset = 0,
+    limit = 1000
+  ): Promise<OutputChunk[]> {
+    const recorder = this.outputRecorders.get(sessionId);
+    if (!recorder) {
+      return [];
+    }
+
+    return recorder.read(offset, limit);
+  }
+
+  /**
+   * Get the total number of scrollback chunks for a session.
+   */
+  getScrollbackLength(sessionId: SessionId): number {
+    const recorder = this.outputRecorders.get(sessionId);
+    return recorder ? recorder.getChunkCount() : 0;
+  }
+
+  /**
+   * Create a history replay for streaming scrollback to a client.
+   * The replay emits 'data', 'progress', and 'complete' events.
+   */
+  async createHistoryReplay(sessionId: SessionId): Promise<HistoryReplay | null> {
+    const recorder = this.outputRecorders.get(sessionId);
+    if (!recorder) {
+      return null;
+    }
+
+    const chunks = await recorder.readAll();
+    const replay = new HistoryReplay({
+      chunkSize: 100,
+      batchDelay: 10,
+    });
+
+    // Start replay in next tick to allow event handler setup
+    setImmediate(() => {
+      replay.start(chunks).catch((err) => replay.emit('error', err));
+    });
+
+    return replay;
+  }
+
+  /**
+   * Spawn a PTY process for a session.
+   */
+  private async spawnProcess(session: Session): Promise<void> {
+    const pty = await getPty();
+
+    const ptyProcess = pty.spawn(session.process.shell, session.process.args, {
+      name: 'xterm-256color',
+      cols: session.terminal.cols,
+      rows: session.terminal.rows,
+      cwd: session.process.cwd,
+      env: {
+        ...process.env,
+        ...session.process.env,
+      },
+    });
+
+    session.process.pid = ptyProcess.pid;
+    this.ptyProcesses.set(session.id, ptyProcess);
+
+    // Initialize output recorder for scrollback (disk-backed)
+    if (!this.outputRecorders.has(session.id)) {
+      const recorder = new OutputRecorder({
+        filePath: this.paths.scrollbackFile(session.id),
+        maxChunks: this.config.scrollbackLimit,
+      });
+      await recorder.init();
+      this.outputRecorders.set(session.id, recorder);
+    }
+
+    // Handle output
+    ptyProcess.onData((data) => {
+      // Record output to disk-backed scrollback
+      const recorder = this.outputRecorders.get(session.id);
+      if (recorder) {
+        recorder.record(data);
+      }
+
+      this.emit('session:output', session.id, data);
+      session.lastActivity = Date.now();
+    });
+
+    // Handle exit
+    ptyProcess.onExit(({ exitCode }) => {
+      session.process.pid = null;
+      this.ptyProcesses.delete(session.id);
+
+      // Flush scrollback before persisting session
+      const recorder = this.outputRecorders.get(session.id);
+      if (recorder) {
+        recorder.flush().catch(console.error);
+      }
+
+      this.persistSession(session).catch(console.error);
+      this.emit('session:exit', session.id, exitCode);
+    });
+  }
+
+  /**
+   * Persist a session's metadata to disk.
+   */
+  private async persistSession(session: Session): Promise<void> {
+    const metadataPath = this.paths.metadataFile(session.id);
+    const data = JSON.stringify(session, null, 2);
+    await fs.writeFile(metadataPath, data, 'utf-8');
+  }
+
+  /**
+   * Load persisted sessions from disk.
+   */
+  private async loadPersistedSessions(): Promise<void> {
+    const baseDir = this.paths.baseDir;
+
+    if (!existsSync(baseDir)) {
+      return;
+    }
+
+    const entries = await fs.readdir(baseDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const sessionId = entry.name;
+      const metadataPath = this.paths.metadataFile(sessionId);
+
+      if (!existsSync(metadataPath)) continue;
+
+      try {
+        const data = await fs.readFile(metadataPath, 'utf-8');
+        const session: Session = JSON.parse(data);
+
+        // Mark process as not running (it died when server stopped)
+        session.process.pid = null;
+
+        this.sessions.set(sessionId, session);
+      } catch (error) {
+        console.error(`Failed to load session ${sessionId}:`, error);
+      }
+    }
+  }
+
+  /**
+   * Generate a display name for a new session.
+   * Returns the next available number (1, 2, 3, ...).
+   */
+  private generateDisplayName(): string {
+    const existingNames = new Set(Array.from(this.sessions.values()).map((s) => s.displayName));
+
+    let num = 1;
+    while (existingNames.has(String(num))) {
+      num++;
+    }
+
+    return String(num);
+  }
+
+  /**
+   * Clean up all resources.
+   */
+  async destroy(): Promise<void> {
+    // Kill all PTY processes
+    for (const pty of this.ptyProcesses.values()) {
+      pty.kill();
+    }
+    this.ptyProcesses.clear();
+
+    // Close all output recorders (flushes pending data)
+    for (const recorder of this.outputRecorders.values()) {
+      await recorder.close();
+    }
+    this.outputRecorders.clear();
+
+    // Persist all sessions
+    for (const session of this.sessions.values()) {
+      await this.persistSession(session);
+    }
+
+    this.removeAllListeners();
+  }
+}
+
+/**
+ * Singleton instance for convenience.
+ * For most use cases, you can use this directly.
+ */
+let defaultManager: SessionManager | null = null;
+
+export function getSessionManager(config?: SessionManagerConfig): SessionManager {
+  if (!defaultManager) {
+    defaultManager = new SessionManager(config);
+  }
+  return defaultManager;
+}
+
+export { getDefaultShell, getDefaultEnv };