@seflless/ghosttown 1.7.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seflless/ghosttown",
-  "version": "1.7.0",
+  "version": "1.10.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

@@ -8,7 +8,7 @@
  *   ghosttown [options] [command]
  *
  * Options:
- *   -p, --port <port>    Port to listen on (default: 8080, or PORT env var)
+ *   -p, --port <port>    Port to listen on (default: auto-discover available port)
  *   -n, --name <name>    Give the session a custom name
  *   -k, --kill [session] Kill a session (current if inside one, or specify by name)
  *   -ka, --kill-all      Kill all ghosttown sessions
@@ -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;
@@ -91,6 +91,64 @@ const SESSION_EXPIRATION_MS = 3 * 24 * 60 * 60 * 1000;
 const SESSION_FILE_DIR = path.join(homedir(), '.config', 'ghosttown');
 const SESSION_FILE_PATH = path.join(SESSION_FILE_DIR, 'sessions.json');
 
+// Server config file for port discovery (allows CLI to find running server)
+const SERVER_CONFIG_PATH = path.join(SESSION_FILE_DIR, 'server.json');
+
+/**
+ * Write server config to disk for port discovery
+ */
+function writeServerConfig(port) {
+  try {
+    if (!fs.existsSync(SESSION_FILE_DIR)) {
+      fs.mkdirSync(SESSION_FILE_DIR, { recursive: true });
+    }
+    fs.writeFileSync(
+      SERVER_CONFIG_PATH,
+      JSON.stringify({ port, pid: process.pid, startedAt: Date.now() }, null, 2)
+    );
+  } catch (err) {
+    console.error('Warning: Failed to write server config:', err.message);
+  }
+}
+
+/**
+ * Remove server config file on shutdown
+ */
+function removeServerConfig() {
+  try {
+    if (fs.existsSync(SERVER_CONFIG_PATH)) {
+      fs.unlinkSync(SERVER_CONFIG_PATH);
+    }
+  } catch (err) {
+    // Ignore errors during cleanup
+  }
+}
+
+// Preferred ports to try in order before falling back to auto-discovery (port 0)
+// 64057 - strongest visual mapping to "GHOST"
+// 6057  - subtle and clean
+// 4040  - "ghost server not found" energy (404)
+// 1313  - haunted house number energy
+const PREFERRED_PORTS = [64057, 6057, 4040, 1313];
+
+/**
+ * Find an available port from the preferred list, or return 0 for auto-discovery
+ */
+function findPreferredPort() {
+  for (const port of PREFERRED_PORTS) {
+    try {
+      // Quick check if port is in use using lsof
+      execSync(`lsof -i:${port}`, { stdio: 'pipe' });
+      // If lsof succeeds, port is in use, try next
+    } catch (e) {
+      // lsof returns non-zero if port is free - use this port
+      return port;
+    }
+  }
+  // All preferred ports in use, fall back to auto-discovery
+  return 0;
+}
+
 // In-memory session store: Map<token, { username, createdAt, lastActivity }>
 const authSessions = new Map();
 
@@ -636,22 +694,41 @@ function getServerStatus() {
     const isRunning = output.split('\n').includes(SERVER_SESSION_NAME);
 
     if (!isRunning) {
+      // Also clean up stale server.json if tmux session doesn't exist
+      removeServerConfig();
       return { running: false, port: null, useHttp: false };
     }
 
-    // Get the port from tmux environment
-    let port = 8080;
+    // Get the port - prefer server.json (for auto port discovery), fall back to tmux env
+    let port = null;
     try {
-      const envOutput = execSync(`tmux show-environment -t ${SERVER_SESSION_NAME} GHOSTTOWN_PORT`, {
-        encoding: 'utf8',
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-      const parsedPort = Number.parseInt(envOutput.split('=')[1], 10);
-      if (!Number.isNaN(parsedPort)) {
-        port = parsedPort;
+      if (fs.existsSync(SERVER_CONFIG_PATH)) {
+        const config = JSON.parse(fs.readFileSync(SERVER_CONFIG_PATH, 'utf8'));
+        if (config.port) {
+          port = config.port;
+        }
       }
     } catch (e) {
-      // Use default port
+      // Failed to read server.json, try tmux env
+    }
+
+    // Fall back to tmux environment if server.json doesn't have the port
+    if (port === null) {
+      try {
+        const envOutput = execSync(
+          `tmux show-environment -t ${SERVER_SESSION_NAME} GHOSTTOWN_PORT`,
+          {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+          }
+        );
+        const parsedPort = Number.parseInt(envOutput.split('=')[1], 10);
+        if (!Number.isNaN(parsedPort) && parsedPort > 0) {
+          port = parsedPort;
+        }
+      } catch (e) {
+        // No port info available
+      }
     }
 
     // Get the protocol from tmux environment (default to HTTPS if not set)
@@ -1201,7 +1278,7 @@ function killAllSessions() {
  * @param {number} port - Port to listen on
  * @param {boolean} useHttp - Use HTTP instead of HTTPS (default: false, meaning HTTPS is used)
  */
-function startServerInBackground(port = 8080, useHttp = false) {
+async function startServerInBackground(port = 0, useHttp = false) {
   // Check if tmux is installed
   if (!checkTmuxInstalled()) {
     printTmuxInstallHelp();
@@ -1219,7 +1296,7 @@ function startServerInBackground(port = 8080, useHttp = false) {
     console.log('');
     console.log(`   ${RED}Error:${RESET} A server is already running (port ${status.port}).`);
     console.log('');
-    if (status.port !== port) {
+    if (port !== 0 && status.port !== port) {
       console.log(`   To switch to port ${port}:`);
       console.log(`     ${BEIGE}gt stop && gt start -p ${port}${RESET}`);
     } else {
@@ -1230,18 +1307,20 @@ function startServerInBackground(port = 8080, useHttp = false) {
     process.exit(1);
   }
 
-  // Check if port is already in use by another process
-  try {
-    execSync(`lsof -i:${port}`, { stdio: 'pipe' });
-    // If lsof succeeds, port is in use
-    console.log('');
-    console.log(`   ${RED}Error:${RESET} Port ${port} is already in use.`);
-    console.log('');
-    console.log(`   Try a different port: ${BEIGE}gt start -p <port>${RESET}`);
-    console.log('');
-    process.exit(1);
-  } catch (e) {
-    // lsof returns non-zero if port is free - this is what we want
+  // Check if specific port is already in use by another process (skip for port 0 auto-discovery)
+  if (port !== 0) {
+    try {
+      execSync(`lsof -i:${port}`, { stdio: 'pipe' });
+      // If lsof succeeds, port is in use
+      console.log('');
+      console.log(`   ${RED}Error:${RESET} Port ${port} is already in use.`);
+      console.log('');
+      console.log(`   Try a different port: ${BEIGE}gt start -p <port>${RESET}`);
+      console.log('');
+      process.exit(1);
+    } catch (e) {
+      // lsof returns non-zero if port is free - this is what we want
+    }
   }
 
   try {
@@ -1280,6 +1359,27 @@ function startServerInBackground(port = 8080, useHttp = false) {
       { stdio: 'pipe' }
     );
 
+    // Wait for server to start and get actual port from server.json
+    // The server writes to server.json once it starts listening
+    let actualPort = port;
+    let attempts = 0;
+    const maxAttempts = 30; // 3 seconds max wait
+    while (attempts < maxAttempts) {
+      try {
+        if (fs.existsSync(SERVER_CONFIG_PATH)) {
+          const config = JSON.parse(fs.readFileSync(SERVER_CONFIG_PATH, 'utf8'));
+          if (config.port) {
+            actualPort = config.port;
+            break;
+          }
+        }
+      } catch (e) {
+        // Ignore read errors, keep waiting
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      attempts++;
+    }
+
     // Get local IPs for display
     const localIPs = getLocalIPs();
     const protocol = useHttp ? 'http' : 'https';
@@ -1287,9 +1387,11 @@ function startServerInBackground(port = 8080, useHttp = false) {
     console.log('');
     console.log(`   ${BOLD_YELLOW}Ghosttown server started!${RESET}`);
     console.log('');
-    console.log(`     ${CYAN}Open:${RESET} ${BEIGE}${protocol}://localhost:${port}${RESET}`);
+    console.log(`     ${CYAN}Open:${RESET} ${BEIGE}${protocol}://localhost:${actualPort}${RESET}`);
     if (localIPs.length > 0) {
-      console.log(`  ${CYAN}Network:${RESET} ${BEIGE}${protocol}://${localIPs[0]}:${port}${RESET}`);
+      console.log(
+        `  ${CYAN}Network:${RESET} ${BEIGE}${protocol}://${localIPs[0]}:${actualPort}${RESET}`
+      );
     }
     console.log('');
     console.log(`   ${CYAN}To stop:${RESET}  ${BEIGE}gt stop${RESET}`);
@@ -1310,38 +1412,53 @@ function startServerInBackground(port = 8080, useHttp = false) {
  * Stop the background server
  */
 function stopServer() {
-  // Check if tmux is installed
-  if (!checkTmuxInstalled()) {
-    printTmuxInstallHelp();
-  }
-
   const RESET = '\x1b[0m';
   const RED = '\x1b[31m';
   const BOLD_YELLOW = '\x1b[1;93m';
   const BEIGE = '\x1b[38;2;255;220;150m';
 
-  const status = getServerStatus();
+  let stopped = false;
 
-  if (!status.running) {
-    console.log('');
-    console.log(`   ${BEIGE}No server is currently running.${RESET}`);
-    console.log('');
-    console.log('   To start: gt start');
-    console.log('');
-    process.exit(0);
+  // First, try to stop using PID from server.json (works for foreground servers)
+  try {
+    if (fs.existsSync(SERVER_CONFIG_PATH)) {
+      const config = JSON.parse(fs.readFileSync(SERVER_CONFIG_PATH, 'utf8'));
+      if (config.pid) {
+        try {
+          process.kill(config.pid, 'SIGTERM');
+          stopped = true;
+        } catch (e) {
+          // Process doesn't exist or can't be killed
+        }
+      }
+    }
+  } catch (e) {
+    // Ignore errors reading config
   }
 
-  try {
-    execSync(`tmux kill-session -t ${SERVER_SESSION_NAME}`, { stdio: 'pipe' });
+  // Also try to kill tmux session (for background servers started with `gt start`)
+  if (checkTmuxInstalled()) {
+    try {
+      execSync(`tmux kill-session -t ${SERVER_SESSION_NAME}`, { stdio: 'pipe' });
+      stopped = true;
+    } catch (err) {
+      // tmux session doesn't exist or can't be killed
+    }
+  }
 
+  // Clean up server.json
+  removeServerConfig();
+
+  if (stopped) {
     console.log('');
     console.log(`   ${BOLD_YELLOW}Server stopped.${RESET}`);
     console.log('');
-  } catch (err) {
+  } else {
     console.log('');
-    console.log(`   ${RED}Error:${RESET} Failed to stop server.`);
+    console.log(`   ${BEIGE}No server is currently running.${RESET}`);
+    console.log('');
+    console.log('   To start: gt start');
     console.log('');
-    process.exit(1);
   }
 
   process.exit(0);
@@ -1544,7 +1661,7 @@ function renameSession(renameArgs) {
 // Parse CLI arguments
 // ============================================================================
 
-function parseArgs(argv) {
+async function parseArgs(argv) {
   const args = argv.slice(2);
   let port = null;
   let command = null;
@@ -1562,7 +1679,7 @@ function parseArgs(argv) {
 Usage: ghosttown [options] [command]
 
 Options:
-  -p, --port <port>    Port to listen on (default: 8080, or PORT env var)
+  -p, --port <port>    Port to listen on (default: auto-discover available port)
   -n, --name <name>    Give the session a custom name (use with a command)
   --http               Use HTTP instead of HTTPS (default is HTTPS)
   --no-auth            Disable authentication (binds to localhost only)
@@ -1572,7 +1689,7 @@ Options:
   -h, --help           Show this help message
 
 Commands:
-  start [-p <port>]  Start the server in the background (default port: 8080)
+  start [-p <port>]  Start the server in the background (auto-discovers available port)
   stop               Stop the background server
   status             Show server status and URLs
   list               List all ghosttown tmux sessions
@@ -1680,7 +1797,7 @@ Aliases:
     // Handle start command
     else if (arg === 'start') {
       // Parse remaining args after 'start' for -p and --http flags
-      let startPort = 8080;
+      let startPort = findPreferredPort(); // Try preferred ports, fall back to auto-discovery
       let startUseHttp = false;
       const remainingArgs = args.slice(i + 1);
       for (let j = 0; j < remainingArgs.length; j++) {
@@ -1700,7 +1817,7 @@ Aliases:
         }
       }
       handled = true;
-      startServerInBackground(startPort, startUseHttp);
+      await startServerInBackground(startPort, startUseHttp);
       // startServerInBackground exits, so this won't be reached
     }
 
@@ -1772,7 +1889,41 @@ Aliases:
 // ============================================================================
 
 function startWebServer(cliArgs) {
-  const HTTP_PORT = cliArgs.port || process.env.PORT || 8080;
+  // ANSI color codes for formatted output
+  const RESET = '\x1b[0m';
+  const RED = '\x1b[31m';
+  const CYAN = '\x1b[36m';
+  const BEIGE = '\x1b[38;2;255;220;150m';
+
+  // Check if a server is already running (prevents multiple instances)
+  try {
+    if (fs.existsSync(SERVER_CONFIG_PATH)) {
+      const config = JSON.parse(fs.readFileSync(SERVER_CONFIG_PATH, 'utf8'));
+      // Check if the PID is still alive
+      if (config.pid) {
+        try {
+          process.kill(config.pid, 0); // Signal 0 = just check if process exists
+          // Process exists - server already running
+          console.log('');
+          console.log(`   ${RED}Error:${RESET} A gt server is already running.`);
+          console.log('');
+          console.log(`   ${CYAN}To stop:${RESET}  ${BEIGE}gt stop${RESET}`);
+          console.log(`   ${CYAN}To check:${RESET} ${BEIGE}gt status${RESET}`);
+          console.log('');
+          process.exit(1);
+        } catch (e) {
+          // Process doesn't exist - stale config, clean it up
+          removeServerConfig();
+        }
+      }
+    }
+  } catch (e) {
+    // Ignore errors reading config
+  }
+
+  // Try preferred ports (64057, 6057, 4040) in order, fall back to auto-discovery (port 0)
+  // if all are in use. User can still override with -p flag or PORT env var.
+  const HTTP_PORT = cliArgs.port || process.env.PORT || findPreferredPort();
   const USE_HTTPS = !cliArgs.useHttp;
   const NO_AUTH = cliArgs.noAuth || false;
   const backgroundMode = cliArgs.serverBackgroundMode || false;
@@ -3842,7 +3993,7 @@ function startWebServer(cliArgs) {
   // Startup
   // ============================================================================
 
-  function printBanner(url, backgroundMode = false) {
+  function printBanner(url, port, backgroundMode = false) {
     const localIPs = getLocalIPs();
     // ANSI color codes
     const RESET = '\x1b[0m';
@@ -3863,7 +4014,7 @@ function startWebServer(cliArgs) {
         networkCount++;
         const spaces = networkCount !== 1 ? '           ' : '';
         const protocol = USE_HTTPS ? 'https' : 'http';
-        network.push(`${spaces}${BEIGE}${protocol}://${ip}:${HTTP_PORT}${RESET}\n`);
+        network.push(`${spaces}${BEIGE}${protocol}://${ip}:${port}${RESET}\n`);
       }
     }
     console.log(`\n${network.join('')} `);
@@ -3886,6 +4037,8 @@ function startWebServer(cliArgs) {
 
   process.on('SIGINT', () => {
     console.log('\n\nShutting down...');
+    // Clean up server config file for port discovery
+    removeServerConfig();
     for (const [ws, conn] of wsConnections.entries()) {
       conn.pty.kill();
       ws.close();
@@ -3895,6 +4048,12 @@ function startWebServer(cliArgs) {
   });
 
   httpServer.listen(HTTP_PORT, BIND_ADDRESS, async () => {
+    // Get actual port (important when HTTP_PORT is 0 for auto-discovery)
+    const actualPort = httpServer.address().port;
+
+    // Write server config for port discovery by CLI commands
+    writeServerConfig(actualPort);
+
     // Display ASCII art banner
     try {
       const imagePath = path.join(__dirname, '..', 'bin', 'assets', 'ghosts.png');
@@ -3911,7 +4070,7 @@ function startWebServer(cliArgs) {
     }
 
     const protocol = USE_HTTPS ? 'https' : 'http';
-    printBanner(`${protocol}://localhost:${HTTP_PORT}`, backgroundMode);
+    printBanner(`${protocol}://localhost:${actualPort}`, actualPort, backgroundMode);
 
     // Show warning when auth is disabled
     if (NO_AUTH) {
@@ -3924,8 +4083,8 @@ function startWebServer(cliArgs) {
 // Main entry point
 // ============================================================================
 
-export function run(argv) {
-  const cliArgs = parseArgs(argv);
+export async function run(argv) {
+  const cliArgs = await parseArgs(argv);
 
   if (cliArgs.handled) {
     return;

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>;