@seflless/ghosttown 1.6.2 → 1.10.0

package/src/session/output-recorder.ts

@@ -0,0 +1,322 @@
+/**
+ * Output Recorder
+ *
+ * Records PTY output to disk for scrollback persistence.
+ * Uses JSONL format for append-only, corruption-isolated storage.
+ *
+ * Each line in the JSONL file is a chunk of PTY output with timestamp:
+ * {"t": 1234567890123, "d": "raw output data"}
+ *
+ * The recorder batches writes to disk for performance (flushes every 100ms
+ * or when buffer exceeds 64KB).
+ */
+
+import { EventEmitter } from 'events';
+import { existsSync, mkdirSync } from 'fs';
+import path from 'path';
+import fs from 'fs/promises';
+
+/**
+ * A single output chunk stored in the scrollback file.
+ */
+export interface OutputChunk {
+  /** Unix timestamp in milliseconds */
+  t: number;
+  /** Raw output data */
+  d: string;
+}
+
+/**
+ * Configuration for OutputRecorder.
+ */
+export interface OutputRecorderConfig {
+  /** Path to the scrollback file */
+  filePath: string;
+  /** Maximum number of chunks to keep (default: 50000) */
+  maxChunks?: number;
+  /** Flush interval in milliseconds (default: 100) */
+  flushInterval?: number;
+  /** Maximum buffer size in bytes before flush (default: 65536 = 64KB) */
+  maxBufferSize?: number;
+}
+
+/**
+ * Events emitted by OutputRecorder.
+ */
+export interface OutputRecorderEvents {
+  /** Emitted when data is flushed to disk */
+  flush: (chunkCount: number) => void;
+  /** Emitted on error */
+  error: (error: Error) => void;
+}
+
+const DEFAULTS = {
+  maxChunks: 50_000, // ~50K chunks (each chunk is a PTY output event)
+  flushInterval: 100, // 100ms
+  maxBufferSize: 65_536, // 64KB
+};
+
+/**
+ * Records PTY output to disk with batched writes.
+ *
+ * @example
+ * ```typescript
+ * const recorder = new OutputRecorder({
+ *   filePath: '/path/to/scrollback.jsonl'
+ * });
+ *
+ * await recorder.init();
+ *
+ * // Record output as it comes from PTY
+ * recorder.record('Hello, world!\r\n');
+ * recorder.record('\x1b[32mGreen text\x1b[0m\r\n');
+ *
+ * // Flush pending writes
+ * await recorder.flush();
+ *
+ * // Read all chunks
+ * const chunks = await recorder.readAll();
+ *
+ * // Clean up
+ * await recorder.close();
+ * ```
+ */
+export class OutputRecorder extends EventEmitter {
+  private config: Required<OutputRecorderConfig>;
+  private buffer: OutputChunk[] = [];
+  private bufferSize = 0;
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+  private isWriting = false;
+  private pendingFlush: Promise<void> | null = null;
+  private closed = false;
+  private chunkCount = 0; // Track total chunks on disk
+
+  constructor(config: OutputRecorderConfig) {
+    super();
+
+    this.config = {
+      filePath: config.filePath,
+      maxChunks: config.maxChunks ?? DEFAULTS.maxChunks,
+      flushInterval: config.flushInterval ?? DEFAULTS.flushInterval,
+      maxBufferSize: config.maxBufferSize ?? DEFAULTS.maxBufferSize,
+    };
+  }
+
+  /**
+   * Initialize the recorder.
+   * Creates the directory and counts existing chunks.
+   */
+  async init(): Promise<void> {
+    // Ensure directory exists
+    const dir = path.dirname(this.config.filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    // Count existing chunks
+    if (existsSync(this.config.filePath)) {
+      this.chunkCount = await this.countChunks();
+    }
+
+    // Start flush timer
+    this.flushTimer = setInterval(() => {
+      if (this.buffer.length > 0 && !this.isWriting) {
+        this.flush().catch((err) => this.emit('error', err));
+      }
+    }, this.config.flushInterval);
+  }
+
+  /**
+   * Record a chunk of output.
+   * The data is buffered and flushed to disk periodically.
+   */
+  record(data: string): void {
+    if (this.closed) {
+      throw new Error('OutputRecorder is closed');
+    }
+
+    const chunk: OutputChunk = {
+      t: Date.now(),
+      d: data,
+    };
+
+    this.buffer.push(chunk);
+    this.bufferSize += data.length;
+
+    // Flush if buffer exceeds size limit
+    if (this.bufferSize >= this.config.maxBufferSize) {
+      this.flush().catch((err) => this.emit('error', err));
+    }
+  }
+
+  /**
+   * Flush buffered chunks to disk.
+   * Returns immediately if already flushing (coalesces concurrent calls).
+   */
+  async flush(): Promise<void> {
+    if (this.closed || this.buffer.length === 0) {
+      return;
+    }
+
+    // Coalesce concurrent flush calls
+    if (this.pendingFlush) {
+      return this.pendingFlush;
+    }
+
+    this.pendingFlush = this.doFlush();
+
+    try {
+      await this.pendingFlush;
+    } finally {
+      this.pendingFlush = null;
+    }
+  }
+
+  /**
+   * Internal flush implementation.
+   */
+  private async doFlush(): Promise<void> {
+    if (this.buffer.length === 0) {
+      return;
+    }
+
+    this.isWriting = true;
+
+    try {
+      // Grab current buffer and reset
+      const chunks = this.buffer;
+      this.buffer = [];
+      this.bufferSize = 0;
+
+      // Convert to JSONL
+      const lines = chunks.map((c) => JSON.stringify(c)).join('\n') + '\n';
+
+      // Append to file
+      await fs.appendFile(this.config.filePath, lines, 'utf-8');
+
+      this.chunkCount += chunks.length;
+      this.emit('flush', chunks.length);
+
+      // Trim if over limit
+      if (this.chunkCount > this.config.maxChunks) {
+        await this.trimOldChunks();
+      }
+    } finally {
+      this.isWriting = false;
+    }
+  }
+
+  /**
+   * Read all chunks from disk.
+   * Returns chunks in chronological order.
+   */
+  async readAll(): Promise<OutputChunk[]> {
+    // Flush pending writes first
+    await this.flush();
+
+    if (!existsSync(this.config.filePath)) {
+      return [];
+    }
+
+    const content = await fs.readFile(this.config.filePath, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+
+    const chunks: OutputChunk[] = [];
+    for (const line of lines) {
+      try {
+        chunks.push(JSON.parse(line));
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    return chunks;
+  }
+
+  /**
+   * Read chunks with pagination.
+   * @param offset Number of chunks to skip from the start
+   * @param limit Maximum number of chunks to return
+   */
+  async read(offset: number, limit: number): Promise<OutputChunk[]> {
+    const all = await this.readAll();
+    return all.slice(offset, offset + limit);
+  }
+
+  /**
+   * Get the total number of chunks (on disk + in buffer).
+   */
+  getChunkCount(): number {
+    return this.chunkCount + this.buffer.length;
+  }
+
+  /**
+   * Clear all recorded data.
+   */
+  async clear(): Promise<void> {
+    this.buffer = [];
+    this.bufferSize = 0;
+    this.chunkCount = 0;
+
+    if (existsSync(this.config.filePath)) {
+      await fs.unlink(this.config.filePath);
+    }
+  }
+
+  /**
+   * Close the recorder and flush remaining data.
+   */
+  async close(): Promise<void> {
+    if (this.closed) return;
+
+    this.closed = true;
+
+    // Stop flush timer
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    // Final flush
+    await this.flush();
+
+    this.removeAllListeners();
+  }
+
+  /**
+   * Count chunks in the file.
+   */
+  private async countChunks(): Promise<number> {
+    if (!existsSync(this.config.filePath)) {
+      return 0;
+    }
+
+    const content = await fs.readFile(this.config.filePath, 'utf-8');
+    return content.trim().split('\n').filter(Boolean).length;
+  }
+
+  /**
+   * Trim old chunks to stay under the limit.
+   * Removes the oldest chunks by rewriting the file.
+   */
+  private async trimOldChunks(): Promise<void> {
+    if (!existsSync(this.config.filePath)) {
+      return;
+    }
+
+    const content = await fs.readFile(this.config.filePath, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+
+    if (lines.length <= this.config.maxChunks) {
+      return;
+    }
+
+    // Keep only the most recent chunks
+    const keepCount = Math.floor(this.config.maxChunks * 0.9); // Keep 90% of max
+    const trimmedLines = lines.slice(-keepCount);
+
+    await fs.writeFile(this.config.filePath, trimmedLines.join('\n') + '\n', 'utf-8');
+
+    this.chunkCount = trimmedLines.length;
+  }
+}

package/src/session/session-manager.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 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 { EventEmitter } from 'events';
+import type { IPty } from '@lydell/node-pty';
+import { HistoryReplay } from './history-replay.js';
+import { type OutputChunk } from './output-recorder.js';
+import type { CreateSessionOptions, Session, SessionId, SessionInfo, SessionManagerConfig, SessionPaths } from './types.js';
+/**
+ * Get the default shell for the current platform.
+ */
+declare function getDefaultShell(): string;
+/**
+ * Get default environment variables for terminal sessions.
+ */
+declare function getDefaultEnv(): Record<string, string>;
+/**
+ * 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 declare class SessionManager extends EventEmitter {
+    private config;
+    private paths;
+    private sessions;
+    private ptyProcesses;
+    private outputRecorders;
+    private initialized;
+    constructor(config?: SessionManagerConfig);
+    /**
+     * Initialize the session manager.
+     * Loads persisted sessions from disk.
+     */
+    init(): Promise<void>;
+    /**
+     * Create a new session.
+     */
+    createSession(options?: CreateSessionOptions): Promise<Session>;
+    /**
+     * Get a session by ID.
+     */
+    getSession(sessionId: SessionId): Session | undefined;
+    /**
+     * Get the PTY process for a session.
+     * Returns undefined if the process is not running.
+     */
+    getPty(sessionId: SessionId): IPty | undefined;
+    /**
+     * List all sessions with summary info.
+     */
+    listSessions(): Promise<SessionInfo[]>;
+    /**
+     * Delete a session and all associated data.
+     */
+    deleteSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Rename a session.
+     */
+    renameSession(sessionId: SessionId, newName: string): Promise<void>;
+    /**
+     * Resize a session's terminal.
+     */
+    resizeSession(sessionId: SessionId, cols: number, rows: number): Promise<void>;
+    /**
+     * Connect to a session, respawning the process if needed.
+     * Returns the PTY for I/O.
+     */
+    connectToSession(sessionId: SessionId): Promise<IPty>;
+    /**
+     * Write data to a session's PTY.
+     */
+    write(sessionId: SessionId, data: string): void;
+    /**
+     * Get the storage paths for session data.
+     */
+    getPaths(): SessionPaths;
+    /**
+     * 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.
+     */
+    getScrollback(sessionId: SessionId): Promise<string>;
+    /**
+     * 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
+     */
+    getScrollbackChunks(sessionId: SessionId, offset?: number, limit?: number): Promise<OutputChunk[]>;
+    /**
+     * Get the total number of scrollback chunks for a session.
+     */
+    getScrollbackLength(sessionId: SessionId): number;
+    /**
+     * Create a history replay for streaming scrollback to a client.
+     * The replay emits 'data', 'progress', and 'complete' events.
+     */
+    createHistoryReplay(sessionId: SessionId): Promise<HistoryReplay | null>;
+    /**
+     * Spawn a PTY process for a session.
+     */
+    private spawnProcess;
+    /**
+     * Persist a session's metadata to disk.
+     */
+    private persistSession;
+    /**
+     * Load persisted sessions from disk.
+     */
+    private loadPersistedSessions;
+    /**
+     * Generate a display name for a new session.
+     * Returns the next available number (1, 2, 3, ...).
+     */
+    private generateDisplayName;
+    /**
+     * Clean up all resources.
+     */
+    destroy(): Promise<void>;
+}
+export declare function getSessionManager(config?: SessionManagerConfig): SessionManager;
+export { getDefaultShell, getDefaultEnv };