@seflless/ghosttown 1.7.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seflless/ghosttown",
-  "version": "1.7.0",
+  "version": "2.0.0",
   "description": "Web-based terminal emulator using Ghostty's VT100 parser via WebAssembly",
   "type": "module",
   "main": "./dist/ghostty-web.umd.cjs",
@@ -68,6 +68,7 @@
     "build": "bun run clean && bun run build:wasm && bun run build:lib && bun run build:wasm-copy",
     "build:wasm": "./scripts/build-wasm.sh",
     "build:lib": "vite build",
+    "build:cli": "tsc -p tsconfig.cli.json",
     "build:wasm-copy": "cp ghostty-vt.wasm dist/",
     "clean": "rm -rf dist",
     "preview": "vite preview",
@@ -80,7 +81,7 @@
     "test:e2e": "playwright test",
     "test:e2e:headed": "playwright test --headed",
     "test:e2e:ui": "playwright test --ui",
-    "prepublishOnly": "bun run build",
+    "prepublishOnly": "bun run build && bun run build:cli",
     "cli:publish": "node scripts/cli-publish.js",
     "kill:8080": "kill -9 $(lsof -ti :8080)"
   },

package/src/cli.js

@@ -53,7 +53,7 @@ import { asciiArt } from '../bin/ascii.js';
 // Session name utilities
 import { displayNameExists, findSession, validateSessionName } from './session-utils.js';
 // Session management - custom PTY session manager (replaces tmux)
-import { SessionManager } from './session/session-manager.ts';
+import { SessionManager } from './session/session-manager.js';
 
 // Global SessionManager instance (lazy-initialized)
 let sessionManager = null;

package/src/session/history-replay.d.ts

@@ -0,0 +1,118 @@
+/**
+ * History Replay
+ *
+ * Streams scrollback history to clients in chunks.
+ * Handles large histories (10,000+ lines) without blocking.
+ *
+ * Replay is throttled to prevent overwhelming the client with data
+ * and to show a progress indicator for long replays.
+ */
+import { EventEmitter } from 'events';
+import type { OutputChunk } from './output-recorder.js';
+/**
+ * Configuration for HistoryReplay.
+ */
+export interface HistoryReplayConfig {
+    /** Chunks to send per batch (default: 100) */
+    chunkSize?: number;
+    /** Delay between batches in milliseconds (default: 10) */
+    batchDelay?: number;
+    /** Maximum replay time in milliseconds (default: 30000 = 30s) */
+    maxReplayTime?: number;
+}
+/**
+ * Progress information during replay.
+ */
+export interface ReplayProgress {
+    /** Number of chunks sent */
+    sent: number;
+    /** Total number of chunks */
+    total: number;
+    /** Percentage complete (0-100) */
+    percent: number;
+    /** Whether replay is complete */
+    complete: boolean;
+}
+/**
+ * Events emitted by HistoryReplay.
+ */
+export interface HistoryReplayEvents {
+    /** Emitted for each batch of chunks */
+    data: (data: string) => void;
+    /** Emitted with progress updates */
+    progress: (progress: ReplayProgress) => void;
+    /** Emitted when replay completes */
+    complete: () => void;
+    /** Emitted on error */
+    error: (error: Error) => void;
+}
+/**
+ * Replays scrollback history to a client.
+ *
+ * @example
+ * ```typescript
+ * const replay = new HistoryReplay({
+ *   chunkSize: 100,
+ *   batchDelay: 10
+ * });
+ *
+ * replay.on('data', (data) => {
+ *   // Send data to client via WebSocket
+ *   ws.send(JSON.stringify({ type: 'scrollback', data }));
+ * });
+ *
+ * replay.on('progress', (progress) => {
+ *   // Update progress indicator
+ *   console.log(`Replay: ${progress.percent}% complete`);
+ * });
+ *
+ * replay.on('complete', () => {
+ *   console.log('Replay finished');
+ * });
+ *
+ * // Start replay
+ * await replay.start(chunks);
+ * ```
+ */
+export declare class HistoryReplay extends EventEmitter {
+    private config;
+    private aborted;
+    private startTime;
+    constructor(config?: HistoryReplayConfig);
+    /**
+     * Start replaying chunks.
+     * Emits 'data' events with concatenated output for each batch.
+     * Emits 'progress' events periodically.
+     * Emits 'complete' when done.
+     *
+     * @param chunks Array of output chunks to replay
+     * @returns Promise that resolves when replay completes or is aborted
+     */
+    start(chunks: OutputChunk[]): Promise<void>;
+    /**
+     * Start replay from an async generator.
+     * Useful for streaming from disk without loading all chunks into memory.
+     */
+    startFromGenerator(generator: AsyncGenerator<OutputChunk[], void, unknown>, total: number): Promise<void>;
+    /**
+     * Abort the replay.
+     */
+    abort(): void;
+    /**
+     * Check if replay was aborted.
+     */
+    isAborted(): boolean;
+    /**
+     * Emit progress event.
+     */
+    private emitProgress;
+    /**
+     * Delay for a specified time.
+     */
+    private delay;
+}
+/**
+ * Create an async generator that reads chunks in batches.
+ * Useful for memory-efficient replay of large scrollback files.
+ */
+export declare function createChunkGenerator(chunks: OutputChunk[], batchSize: number): AsyncGenerator<OutputChunk[], void, unknown>;

package/src/session/history-replay.js

@@ -0,0 +1,174 @@
+/**
+ * History Replay
+ *
+ * Streams scrollback history to clients in chunks.
+ * Handles large histories (10,000+ lines) without blocking.
+ *
+ * Replay is throttled to prevent overwhelming the client with data
+ * and to show a progress indicator for long replays.
+ */
+import { EventEmitter } from 'events';
+const DEFAULTS = {
+    chunkSize: 100,
+    batchDelay: 10,
+    maxReplayTime: 30000,
+};
+/**
+ * Replays scrollback history to a client.
+ *
+ * @example
+ * ```typescript
+ * const replay = new HistoryReplay({
+ *   chunkSize: 100,
+ *   batchDelay: 10
+ * });
+ *
+ * replay.on('data', (data) => {
+ *   // Send data to client via WebSocket
+ *   ws.send(JSON.stringify({ type: 'scrollback', data }));
+ * });
+ *
+ * replay.on('progress', (progress) => {
+ *   // Update progress indicator
+ *   console.log(`Replay: ${progress.percent}% complete`);
+ * });
+ *
+ * replay.on('complete', () => {
+ *   console.log('Replay finished');
+ * });
+ *
+ * // Start replay
+ * await replay.start(chunks);
+ * ```
+ */
+export class HistoryReplay extends EventEmitter {
+    constructor(config = {}) {
+        super();
+        this.aborted = false;
+        this.startTime = 0;
+        this.config = {
+            chunkSize: config.chunkSize ?? DEFAULTS.chunkSize,
+            batchDelay: config.batchDelay ?? DEFAULTS.batchDelay,
+            maxReplayTime: config.maxReplayTime ?? DEFAULTS.maxReplayTime,
+        };
+    }
+    /**
+     * Start replaying chunks.
+     * Emits 'data' events with concatenated output for each batch.
+     * Emits 'progress' events periodically.
+     * Emits 'complete' when done.
+     *
+     * @param chunks Array of output chunks to replay
+     * @returns Promise that resolves when replay completes or is aborted
+     */
+    async start(chunks) {
+        this.aborted = false;
+        this.startTime = Date.now();
+        const total = chunks.length;
+        if (total === 0) {
+            this.emitProgress(0, 0);
+            this.emit('complete');
+            return;
+        }
+        let sent = 0;
+        while (sent < total && !this.aborted) {
+            // Check timeout
+            if (Date.now() - this.startTime > this.config.maxReplayTime) {
+                this.emit('error', new Error('Replay timeout exceeded'));
+                return;
+            }
+            // Get next batch
+            const batch = chunks.slice(sent, sent + this.config.chunkSize);
+            // Concatenate output data
+            const data = batch.map((c) => c.d).join('');
+            // Emit data
+            if (data) {
+                this.emit('data', data);
+            }
+            sent += batch.length;
+            // Emit progress
+            this.emitProgress(sent, total);
+            // Delay between batches (unless this is the last batch)
+            if (sent < total && this.config.batchDelay > 0) {
+                await this.delay(this.config.batchDelay);
+            }
+        }
+        if (!this.aborted) {
+            this.emit('complete');
+        }
+    }
+    /**
+     * Start replay from an async generator.
+     * Useful for streaming from disk without loading all chunks into memory.
+     */
+    async startFromGenerator(generator, total) {
+        this.aborted = false;
+        this.startTime = Date.now();
+        let sent = 0;
+        for await (const batch of generator) {
+            if (this.aborted)
+                break;
+            // Check timeout
+            if (Date.now() - this.startTime > this.config.maxReplayTime) {
+                this.emit('error', new Error('Replay timeout exceeded'));
+                return;
+            }
+            // Concatenate output data
+            const data = batch.map((c) => c.d).join('');
+            // Emit data
+            if (data) {
+                this.emit('data', data);
+            }
+            sent += batch.length;
+            // Emit progress
+            this.emitProgress(sent, total);
+            // Delay between batches
+            if (this.config.batchDelay > 0) {
+                await this.delay(this.config.batchDelay);
+            }
+        }
+        if (!this.aborted) {
+            this.emit('complete');
+        }
+    }
+    /**
+     * Abort the replay.
+     */
+    abort() {
+        this.aborted = true;
+    }
+    /**
+     * Check if replay was aborted.
+     */
+    isAborted() {
+        return this.aborted;
+    }
+    /**
+     * Emit progress event.
+     */
+    emitProgress(sent, total) {
+        const progress = {
+            sent,
+            total,
+            percent: total === 0 ? 100 : Math.round((sent / total) * 100),
+            complete: sent >= total,
+        };
+        this.emit('progress', progress);
+    }
+    /**
+     * Delay for a specified time.
+     */
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+/**
+ * Create an async generator that reads chunks in batches.
+ * Useful for memory-efficient replay of large scrollback files.
+ */
+export async function* createChunkGenerator(chunks, batchSize) {
+    for (let i = 0; i < chunks.length; i += batchSize) {
+        yield chunks.slice(i, i + batchSize);
+    }
+}
+//# sourceMappingURL=history-replay.js.map

package/src/session/history-replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-replay.js","sourceRoot":"","sources":["history-replay.ts"],"names":[],"mappings":"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"}

package/src/session/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Session Management Module
+ *
+ * Custom PTY session management that replaces tmux.
+ * Provides session persistence, multi-client connections, and read-only sharing.
+ */
+export * from './types.js';
+export * from './session-manager.js';
+export * from './output-recorder.js';
+export * from './history-replay.js';

package/src/session/index.js

@@ -0,0 +1,11 @@
+/**
+ * Session Management Module
+ *
+ * Custom PTY session management that replaces tmux.
+ * Provides session persistence, multi-client connections, and read-only sharing.
+ */
+export * from './types.js';
+export * from './session-manager.js';
+export * from './output-recorder.js';
+export * from './history-replay.js';
+//# sourceMappingURL=index.js.map

package/src/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}

package/src/session/output-recorder.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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';
+/**
+ * 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;
+}
+/**
+ * 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 declare class OutputRecorder extends EventEmitter {
+    private config;
+    private buffer;
+    private bufferSize;
+    private flushTimer;
+    private isWriting;
+    private pendingFlush;
+    private closed;
+    private chunkCount;
+    constructor(config: OutputRecorderConfig);
+    /**
+     * Initialize the recorder.
+     * Creates the directory and counts existing chunks.
+     */
+    init(): Promise<void>;
+    /**
+     * Record a chunk of output.
+     * The data is buffered and flushed to disk periodically.
+     */
+    record(data: string): void;
+    /**
+     * Flush buffered chunks to disk.
+     * Returns immediately if already flushing (coalesces concurrent calls).
+     */
+    flush(): Promise<void>;
+    /**
+     * Internal flush implementation.
+     */
+    private doFlush;
+    /**
+     * Read all chunks from disk.
+     * Returns chunks in chronological order.
+     */
+    readAll(): Promise<OutputChunk[]>;
+    /**
+     * Read chunks with pagination.
+     * @param offset Number of chunks to skip from the start
+     * @param limit Maximum number of chunks to return
+     */
+    read(offset: number, limit: number): Promise<OutputChunk[]>;
+    /**
+     * Get the total number of chunks (on disk + in buffer).
+     */
+    getChunkCount(): number;
+    /**
+     * Clear all recorded data.
+     */
+    clear(): Promise<void>;
+    /**
+     * Close the recorder and flush remaining data.
+     */
+    close(): Promise<void>;
+    /**
+     * Count chunks in the file.
+     */
+    private countChunks;
+    /**
+     * Trim old chunks to stay under the limit.
+     * Removes the oldest chunks by rewriting the file.
+     */
+    private trimOldChunks;
+}