@seflless/ghosttown 1.3.0 → 1.3.1

package/src/cli.js

@@ -0,0 +1,944 @@
+/**
+ * ghosttown CLI - Web-based terminal emulator
+ *
+ * Starts a local HTTP server with WebSocket PTY support,
+ * or runs a command in a new tmux session.
+ *
+ * Usage:
+ *   ghosttown [options] [command]
+ *
+ * Options:
+ *   -p, --port <port>  Port to listen on (default: 8080, or PORT env var)
+ *   -h, --help         Show this help message
+ *
+ * Examples:
+ *   ghosttown                    Start the web terminal server
+ *   ghosttown -p 3000            Start the server on port 3000
+ *   ghosttown vim                Run vim in a new tmux session
+ *   ghosttown "npm run dev"      Run npm in a new tmux session
+ */
+
+import { execSync, spawn } from 'child_process';
+import fs from 'fs';
+import http from 'http';
+import { homedir, networkInterfaces } from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Node-pty for cross-platform PTY support
+import pty from '@lydell/node-pty';
+// WebSocket server
+import { WebSocketServer } from 'ws';
+// ASCII art generator
+import { asciiArt } from '../bin/ascii.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ============================================================================
+// Tmux Session Management
+// ============================================================================
+
+/**
+ * Check if tmux is installed
+ */
+function checkTmuxInstalled() {
+  try {
+    execSync('which tmux', { stdio: 'pipe' });
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * Print tmux installation instructions and exit
+ */
+function printTmuxInstallHelp() {
+  console.error('\x1b[31mError: tmux is not installed.\x1b[0m\n');
+  console.error('tmux is required to run commands in ghosttown sessions.\n');
+  console.error('To install tmux:\n');
+
+  if (process.platform === 'darwin') {
+    console.error('  \x1b[36mmacOS (Homebrew):\x1b[0m  brew install tmux');
+    console.error('  \x1b[36mmacOS (MacPorts):\x1b[0m  sudo port install tmux');
+  } else if (process.platform === 'linux') {
+    console.error('  \x1b[36mDebian/Ubuntu:\x1b[0m  sudo apt install tmux');
+    console.error('  \x1b[36mFedora:\x1b[0m         sudo dnf install tmux');
+    console.error('  \x1b[36mArch:\x1b[0m           sudo pacman -S tmux');
+  } else {
+    console.error('  Please install tmux using your system package manager.');
+  }
+
+  console.error('');
+  process.exit(1);
+}
+
+/**
+ * Get the next available ghosttown session ID
+ * Scans existing tmux sessions named ghosttown-<N> and returns max(N) + 1
+ */
+function getNextSessionId() {
+  try {
+    // List all tmux sessions
+    const output = execSync('tmux list-sessions -F "#{session_name}"', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    // Find all ghosttown-<N> sessions and extract IDs
+    const sessionIds = output
+      .split('\n')
+      .filter((name) => name.startsWith('ghosttown-'))
+      .map((name) => {
+        const id = Number.parseInt(name.replace('ghosttown-', ''), 10);
+        return Number.isNaN(id) ? 0 : id;
+      });
+
+    // Return max + 1, or 1 if no sessions exist
+    return sessionIds.length > 0 ? Math.max(...sessionIds) + 1 : 1;
+  } catch (err) {
+    // tmux not running or no sessions - start with 1
+    return 1;
+  }
+}
+
+/**
+ * List all ghosttown tmux sessions
+ */
+function listSessions() {
+  // Check if tmux is installed
+  if (!checkTmuxInstalled()) {
+    printTmuxInstallHelp();
+  }
+
+  try {
+    // Get detailed session information
+    const output = execSync(
+      'tmux list-sessions -F "#{session_name}|#{session_created}|#{session_attached}|#{session_windows}"',
+      {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }
+    );
+
+    const sessions = output
+      .split('\n')
+      .filter((line) => line.startsWith('ghosttown-'))
+      .map((line) => {
+        const [name, created, attached, windows] = line.split('|');
+        return {
+          name,
+          created: new Date(Number.parseInt(created, 10) * 1000),
+          attached: attached === '1',
+          windows: Number.parseInt(windows, 10),
+        };
+      });
+
+    if (sessions.length === 0) {
+      console.log('No ghosttown sessions running.');
+      console.log('\nTo create a session, run:');
+      console.log('  ghosttown <command>');
+      console.log('\nExample:');
+      console.log('  ghosttown vim');
+      process.exit(0);
+    }
+
+    // Print header
+    console.log('\n\x1b[1mGhosttown Sessions\x1b[0m\n');
+    console.log(
+      `\x1b[36m${'Name'.padEnd(15)}  ${'Created'.padEnd(22)}  ${'Status'.padEnd(10)}  Windows\x1b[0m`
+    );
+    console.log('-'.repeat(65));
+
+    // Print sessions
+    for (const session of sessions) {
+      const createdStr = session.created.toLocaleString();
+      // Status has ANSI codes so we need to pad the visible text differently
+      const statusPadded = session.attached
+        ? `\x1b[32m${'attached'.padEnd(10)}\x1b[0m`
+        : `\x1b[33m${'detached'.padEnd(10)}\x1b[0m`;
+      console.log(
+        `${session.name.padEnd(15)}  ${createdStr.padEnd(22)}  ${statusPadded}  ${session.windows}`
+      );
+    }
+
+    console.log('');
+    console.log(`Total: ${sessions.length} session(s)`);
+    console.log('');
+  } catch (err) {
+    // tmux not running or no sessions
+    console.log('No ghosttown sessions running.');
+    console.log('\nTo create a session, run:');
+    console.log('  ghosttown <command>');
+    console.log('\nExample:');
+    console.log('  ghosttown vim');
+  }
+
+  process.exit(0);
+}
+
+/**
+ * Create a new tmux session and run the command
+ */
+function createTmuxSession(command) {
+  // Check if tmux is installed
+  if (!checkTmuxInstalled()) {
+    printTmuxInstallHelp();
+  }
+
+  const sessionId = getNextSessionId();
+  const sessionName = `ghosttown-${sessionId}`;
+
+  try {
+    // Create tmux session and attach directly (not detached)
+    // Use -x and -y to set initial size, avoiding "terminal too small" issues
+    // The command runs in the session, and we attach immediately
+    const attach = spawn(
+      'tmux',
+      [
+        'new-session',
+        '-s',
+        sessionName,
+        '-x',
+        '200',
+        '-y',
+        '50',
+        // Set status off (no HUD), run the command, then start a shell
+        // so the session stays open and interactive after command completes
+        'tmux set-option status off; ' + command + '; exec $SHELL',
+      ],
+      {
+        stdio: 'inherit',
+      }
+    );
+
+    attach.on('exit', (code) => {
+      process.exit(code || 0);
+    });
+  } catch (err) {
+    console.error(`Error creating tmux session: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// ============================================================================
+// Parse CLI arguments
+// ============================================================================
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let port = null;
+  let command = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '-h' || arg === '--help') {
+      console.log(`
+Usage: ghosttown [options] [command]
+
+Options:
+  -p, --port <port>  Port to listen on (default: 8080, or PORT env var)
+  -h, --help         Show this help message
+
+Commands:
+  list               List all ghosttown tmux sessions
+  <command>          Run command in a new tmux session (ghosttown-<id>)
+
+Examples:
+  ghosttown                    Start the web terminal server
+  ghosttown -p 3000            Start the server on port 3000
+  ghosttown list               List all ghosttown sessions
+  ghosttown vim                Run vim in a new tmux session
+  ghosttown "npm run dev"      Run npm in a new tmux session
+
+Aliases:
+  This CLI can also be invoked as 'gt' or 'ght'.
+`);
+      process.exit(0);
+    }
+
+    // Handle list command
+    if (arg === 'list') {
+      listSessions();
+      // listSessions exits, so this won't be reached
+    }
+
+    if (arg === '-p' || arg === '--port') {
+      const nextArg = args[i + 1];
+      if (!nextArg || nextArg.startsWith('-')) {
+        console.error(`Error: ${arg} requires a port number`);
+        process.exit(1);
+      }
+      port = Number.parseInt(nextArg, 10);
+      if (Number.isNaN(port) || port < 1 || port > 65535) {
+        console.error(`Error: Invalid port number: ${nextArg}`);
+        process.exit(1);
+      }
+      i++; // Skip the next argument since we consumed it
+      continue;
+    }
+
+    // First non-flag argument starts the command
+    // Capture it and all remaining arguments as the command
+    if (!arg.startsWith('-')) {
+      command = args.slice(i).join(' ');
+      break;
+    }
+  }
+
+  return { port, command };
+}
+
+// ============================================================================
+// Web Server
+// ============================================================================
+
+function startWebServer(cliArgs) {
+  const HTTP_PORT = cliArgs.port || process.env.PORT || 8080;
+
+  // ============================================================================
+  // Locate ghosttown assets
+  // ============================================================================
+
+  function findAssets() {
+    // Assets are in the package root (one level up from src/)
+    const packageRoot = path.join(__dirname, '..');
+    const distPath = path.join(packageRoot, 'dist');
+    const wasmPath = path.join(packageRoot, 'ghostty-vt.wasm');
+
+    if (!fs.existsSync(path.join(distPath, 'ghostty-web.js'))) {
+      console.error('Error: dist/ghostty-web.js not found.');
+      console.error('The package may not have been built correctly.');
+      process.exit(1);
+    }
+
+    if (!fs.existsSync(wasmPath)) {
+      console.error('Error: ghostty-vt.wasm not found.');
+      console.error('The package may not have been built correctly.');
+      process.exit(1);
+    }
+
+    return { distPath, wasmPath };
+  }
+
+  const { distPath, wasmPath } = findAssets();
+
+  // ============================================================================
+  // HTML Template
+  // ============================================================================
+
+  const HTML_TEMPLATE = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
+    <title>ghosttown</title>
+    <style>
+      :root {
+        --vvh: 100vh;
+        --vv-offset-top: 0px;
+      }
+
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+
+      html, body {
+        margin: 0;
+        padding: 0;
+        height: var(--vvh);
+        overflow: hidden;
+        overscroll-behavior: none;
+        touch-action: none;
+        transition: none;
+      }
+
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        background: #292c34;
+        padding: 8px 8px 14px 8px;
+        box-sizing: border-box;
+        position: fixed;
+        inset: 0;
+        height: var(--vvh);
+      }
+
+      .terminal-window {
+        width: 100%;
+        height: 100%;
+        background: #ededed;
+        display: flex;
+        flex-direction: column;
+        overflow: hidden;
+        box-shadow:
+          0 0 0 0.5px #65686e,
+          0 0 0 1px #74777c,
+          0 0 0 1.5px #020203,
+          0px 4px 10px 0px rgba(0, 0, 0, 0.5);
+        border-radius: 8px;
+        box-sizing: border-box;
+        transform: translateY(calc(var(--vv-offset-top) * -1));
+        transition: none;
+      }
+
+      .title-bar {
+        background: #292c34;
+        padding: 8px 16px 6px 10px;
+        display: flex;
+        align-items: center;
+        gap: 12px;
+      }
+
+      .traffic-lights {
+        display: flex;
+        gap: 8px;
+      }
+
+      .light {
+        width: 12px;
+        height: 12px;
+        border-radius: 50%;
+      }
+
+      .light.red { background: #ff5f56; }
+      .light.yellow { background: #ffbd2e; }
+      .light.green { background: #27c93f; }
+
+      .title {
+        color: #e5e5e5;
+        font-size: 13px;
+        font-weight: 500;
+        letter-spacing: 0.3px;
+        display: flex;
+        align-items: center;
+        gap: 8px;
+      }
+
+      .title-separator { color: #666; }
+      .current-directory {
+        color: #888;
+        font-size: 12px;
+        font-weight: 400;
+        max-width: 400px;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+
+      .connection-status {
+        margin-left: auto;
+        font-size: 11px;
+        color: #888;
+        display: flex;
+        align-items: center;
+        gap: 6px;
+      }
+
+      .connection-dot {
+        width: 6px;
+        height: 6px;
+        border-radius: 50%;
+        background: #666;
+      }
+
+      .connection-dot.connected { background: #27c93f; }
+
+      #terminal-container {
+        flex: 1;
+        padding: 2px 0 2px 2px;
+        background: #292c34;
+        position: relative;
+        overflow: hidden;
+        min-height: 0;
+        touch-action: none;
+      }
+
+      #terminal-container canvas {
+        display: block;
+        touch-action: none;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="terminal-window">
+      <div class="title-bar">
+        <div class="traffic-lights">
+          <span class="light red"></span>
+          <span class="light yellow"></span>
+          <span class="light green"></span>
+        </div>
+        <div class="title">
+          <span>ghosttown</span>
+          <span class="title-separator" id="title-separator" style="display: none">•</span>
+          <span class="current-directory" id="current-directory"></span>
+        </div>
+        <div class="connection-status">
+          <span class="connection-dot" id="connection-dot"></span>
+          <span id="connection-text">Disconnected</span>
+        </div>
+      </div>
+      <div id="terminal-container"></div>
+    </div>
+
+    <script type="module">
+      import { init, Terminal, FitAddon } from '/dist/ghostty-web.js';
+
+      let term;
+      let ws;
+      let fitAddon;
+
+      async function initTerminal() {
+        await init();
+
+        term = new Terminal({
+          cursorBlink: true,
+          fontSize: 12,
+          fontFamily: 'Monaco, Menlo, "Courier New", monospace',
+          theme: {
+            background: '#292c34',
+            foreground: '#d4d4d4',
+          },
+          smoothScrollDuration: 0,
+          scrollback: 10000,
+          scrollbarVisible: false,
+        });
+
+        fitAddon = new FitAddon();
+        term.loadAddon(fitAddon);
+
+        term.open(document.getElementById('terminal-container'));
+        fitAddon.fit();
+        fitAddon.observeResize();
+
+        // Desktop: auto-focus. Mobile: focus only on tap.
+        const isCoarsePointer = window.matchMedia && window.matchMedia('(pointer: coarse)').matches;
+        if (!isCoarsePointer) {
+          term.focus();
+        }
+
+        // Prevent page scroll on iOS
+        document.addEventListener('touchmove', (e) => {
+          const container = document.getElementById('terminal-container');
+          if (container && !container.contains(e.target)) {
+            e.preventDefault();
+          }
+        }, { passive: false });
+
+        // Mobile keyboard handling via visualViewport
+        {
+          const root = document.documentElement;
+          let watchRafId = null;
+          let vvhCurrent = 0;
+          let vvhTarget = 0;
+          let offsetCurrent = 0;
+          let offsetTarget = 0;
+          let lastTick = 0;
+
+          const readViewport = () => ({
+            height: window.visualViewport?.height ?? window.innerHeight,
+            offsetTop: window.visualViewport?.offsetTop ?? 0,
+          });
+
+          const applyVars = () => {
+            root.style.setProperty('--vvh', vvhCurrent + 'px');
+            root.style.setProperty('--vv-offset-top', offsetCurrent + 'px');
+          };
+
+          const startKeyboardWatch = () => {
+            if (watchRafId !== null) return;
+            lastTick = performance.now();
+
+            const tick = () => {
+              const now = performance.now();
+              const dtMs = Math.max(1, now - lastTick);
+              lastTick = now;
+
+              const { height, offsetTop } = readViewport();
+              vvhTarget = height;
+              offsetTarget = offsetTop;
+
+              if (vvhCurrent === 0) vvhCurrent = vvhTarget;
+
+              const tauMs = 100;
+              const alpha = 1 - Math.exp(-dtMs / tauMs);
+              const deltaH = vvhTarget - vvhCurrent;
+              const deltaO = offsetTarget - offsetCurrent;
+
+              if (Math.abs(deltaH) > 1) vvhCurrent += deltaH * alpha;
+              else vvhCurrent = vvhTarget;
+
+              if (Math.abs(deltaO) > 0.5) offsetCurrent += deltaO * alpha;
+              else offsetCurrent = offsetTarget;
+
+              applyVars();
+              fitAddon.fit();
+
+              const stillAnimating = Math.abs(vvhTarget - vvhCurrent) > 0.5 || Math.abs(offsetTarget - offsetCurrent) > 0.5;
+              if (stillAnimating) {
+                watchRafId = requestAnimationFrame(tick);
+              } else {
+                watchRafId = null;
+              }
+            };
+
+            watchRafId = requestAnimationFrame(tick);
+          };
+
+          // Initial setup
+          const { height, offsetTop } = readViewport();
+          vvhCurrent = height;
+          vvhTarget = height;
+          offsetCurrent = offsetTop;
+          offsetTarget = offsetTop;
+          applyVars();
+
+          window.addEventListener('resize', startKeyboardWatch);
+          window.addEventListener('focusin', startKeyboardWatch);
+          window.addEventListener('focusout', startKeyboardWatch);
+          window.visualViewport?.addEventListener('resize', startKeyboardWatch);
+        }
+
+        // Handle terminal resize
+        term.onResize((size) => {
+          if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ type: 'resize', cols: size.cols, rows: size.rows }));
+          }
+        });
+
+        // Handle user input
+        term.onData((data) => {
+          if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(data);
+          }
+        });
+
+        // Handle directory changes
+        const directoryElement = document.getElementById('current-directory');
+        const separatorElement = document.getElementById('title-separator');
+        term.onDirectoryChange((directory) => {
+          if (directoryElement && separatorElement) {
+            if (directory) {
+              directoryElement.textContent = directory;
+              separatorElement.style.display = 'inline';
+            } else {
+              directoryElement.textContent = '';
+              separatorElement.style.display = 'none';
+            }
+          }
+        });
+
+        connectWebSocket();
+      }
+
+      function connectWebSocket() {
+        const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+        const wsUrl = protocol + '//' + window.location.host + '/ws?cols=' + term.cols + '&rows=' + term.rows;
+
+        ws = new WebSocket(wsUrl);
+
+        ws.onopen = () => {
+          updateConnectionStatus(true);
+        };
+
+        ws.onmessage = (event) => {
+          term.write(event.data);
+        };
+
+        ws.onerror = () => {
+          updateConnectionStatus(false);
+        };
+
+        ws.onclose = () => {
+          updateConnectionStatus(false);
+          setTimeout(() => {
+            if (!ws || ws.readyState === WebSocket.CLOSED) {
+              connectWebSocket();
+            }
+          }, 3000);
+        };
+      }
+
+      function updateConnectionStatus(connected) {
+        const dot = document.getElementById('connection-dot');
+        const text = document.getElementById('connection-text');
+        if (connected) {
+          dot.classList.add('connected');
+          text.textContent = 'Connected';
+        } else {
+          dot.classList.remove('connected');
+          text.textContent = 'Disconnected';
+        }
+      }
+
+      initTerminal();
+    </script>
+  </body>
+</html>`;
+
+  // ============================================================================
+  // MIME Types
+  // ============================================================================
+
+  const MIME_TYPES = {
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.wasm': 'application/wasm',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+  };
+
+  // ============================================================================
+  // HTTP Server
+  // ============================================================================
+
+  const httpServer = http.createServer((req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const pathname = url.pathname;
+
+    // Serve index page
+    if (pathname === '/' || pathname === '/index.html') {
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(HTML_TEMPLATE);
+      return;
+    }
+
+    // Serve dist files
+    if (pathname.startsWith('/dist/')) {
+      const filePath = path.join(distPath, pathname.slice(6));
+      serveFile(filePath, res);
+      return;
+    }
+
+    // Serve WASM file
+    if (pathname === '/ghostty-vt.wasm') {
+      serveFile(wasmPath, res);
+      return;
+    }
+
+    // 404
+    res.writeHead(404);
+    res.end('Not Found');
+  });
+
+  function serveFile(filePath, res) {
+    const ext = path.extname(filePath);
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+
+    fs.readFile(filePath, (err, data) => {
+      if (err) {
+        res.writeHead(404);
+        res.end('Not Found');
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': contentType });
+      res.end(data);
+    });
+  }
+
+  // ============================================================================
+  // WebSocket Server
+  // ============================================================================
+
+  const sessions = new Map();
+
+  function getShell() {
+    if (process.platform === 'win32') {
+      return process.env.COMSPEC || 'cmd.exe';
+    }
+    return process.env.SHELL || '/bin/bash';
+  }
+
+  function createPtySession(cols, rows) {
+    const shell = getShell();
+
+    const ptyProcess = pty.spawn(shell, [], {
+      name: 'xterm-256color',
+      cols: cols,
+      rows: rows,
+      cwd: homedir(),
+      env: {
+        ...process.env,
+        TERM: 'xterm-256color',
+        COLORTERM: 'truecolor',
+      },
+    });
+
+    return ptyProcess;
+  }
+
+  const wss = new WebSocketServer({ noServer: true });
+
+  httpServer.on('upgrade', (req, socket, head) => {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+
+    if (url.pathname === '/ws') {
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        wss.emit('connection', ws, req);
+      });
+    } else {
+      socket.destroy();
+    }
+  });
+
+  wss.on('connection', (ws, req) => {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const cols = Number.parseInt(url.searchParams.get('cols') || '80');
+    const rows = Number.parseInt(url.searchParams.get('rows') || '24');
+
+    const ptyProcess = createPtySession(cols, rows);
+    sessions.set(ws, { pty: ptyProcess });
+
+    ptyProcess.onData((data) => {
+      if (ws.readyState === ws.OPEN) {
+        ws.send(data);
+      }
+    });
+
+    ptyProcess.onExit(({ exitCode }) => {
+      if (ws.readyState === ws.OPEN) {
+        ws.send(`\r\n\x1b[33mShell exited (code: ${exitCode})\x1b[0m\r\n`);
+        ws.close();
+      }
+    });
+
+    ws.on('message', (data) => {
+      const message = data.toString('utf8');
+
+      if (message.startsWith('{')) {
+        try {
+          const msg = JSON.parse(message);
+          if (msg.type === 'resize') {
+            ptyProcess.resize(msg.cols, msg.rows);
+            return;
+          }
+        } catch (e) {
+          // Not JSON, treat as input
+        }
+      }
+
+      ptyProcess.write(message);
+    });
+
+    ws.on('close', () => {
+      const session = sessions.get(ws);
+      if (session) {
+        session.pty.kill();
+        sessions.delete(ws);
+      }
+    });
+
+    ws.on('error', () => {
+      // Ignore socket errors
+    });
+  });
+
+  // ============================================================================
+  // Startup
+  // ============================================================================
+
+  function getLocalIPs() {
+    const interfaces = networkInterfaces();
+    const ips = [];
+    for (const name of Object.keys(interfaces)) {
+      for (const iface of interfaces[name] || []) {
+        if (iface.family === 'IPv4' && !iface.internal) {
+          ips.push(iface.address);
+        }
+      }
+    }
+    return ips;
+  }
+
+  function printBanner(url) {
+    const localIPs = getLocalIPs();
+    // ANSI color codes
+    const RESET = '\x1b[0m';
+    const CYAN = '\x1b[36m'; // Labels
+    const BEIGE = '\x1b[38;2;255;220;150m'; // Warm yellow/beige for values (RGB: 255,220,150)
+    const DIM = '\x1b[2m'; // Dimmed text
+
+    // console.log('');
+
+    // Open: URL
+    console.log(`     ${CYAN}Open:${RESET} ${BEIGE}${url}${RESET}`);
+
+    // Network: URLs
+    const network = [`  ${CYAN}Network: ${RESET}`];
+    if (localIPs.length > 0) {
+      let networkCount = 0;
+      for (const ip of localIPs) {
+        networkCount++;
+        const spaces = networkCount !== 1 ? '           ' : '';
+        network.push(`${spaces}${BEIGE}http://${ip}:${HTTP_PORT}${RESET}\n`);
+      }
+    }
+    console.log(`\n${network.join('')} `);
+
+    // Shell: path
+    console.log(`    ${CYAN}Shell:${RESET} ${BEIGE}${getShell()}${RESET}`);
+
+    console.log('');
+
+    // Home: path
+    console.log(`     ${CYAN}Home:${RESET} ${BEIGE}${homedir()}${RESET}`);
+
+    console.log('');
+    console.log(`           ${DIM}Press Ctrl+C to stop.${RESET}\n`);
+  }
+
+  process.on('SIGINT', () => {
+    console.log('\n\nShutting down...');
+    for (const [ws, session] of sessions.entries()) {
+      session.pty.kill();
+      ws.close();
+    }
+    wss.close();
+    process.exit(0);
+  });
+
+  httpServer.listen(HTTP_PORT, '0.0.0.0', async () => {
+    // Display ASCII art banner
+    try {
+      const imagePath = path.join(__dirname, '..', 'bin', 'assets', 'ghosts.png');
+      if (fs.existsSync(imagePath)) {
+        // Welcome text with orange/yellow color (bright yellow, bold)
+        console.log('\n       \x1b[1;93mWelcome to Ghosttown!\x1b[0m\n');
+        const art = await asciiArt(imagePath, { maxWidth: 80, maxHeight: 20 });
+        console.log(art);
+        console.log('');
+      }
+    } catch (err) {
+      // Silently fail if ASCII art can't be displayed
+      // This allows the server to start even if the image is missing
+    }
+
+    printBanner(`http://localhost:${HTTP_PORT}`);
+  });
+}
+
+// ============================================================================
+// Main entry point
+// ============================================================================
+
+export function run(argv) {
+  const cliArgs = parseArgs(argv);
+
+  // If a command is provided, create a tmux session instead of starting server
+  if (cliArgs.command) {
+    createTmuxSession(cliArgs.command);
+    // createTmuxSession spawns tmux attach and waits for it to exit
+    // The script will exit when tmux attach exits (via the exit handler)
+    // We must not continue to server code, so we stop here
+  } else {
+    // Server mode (no command provided)
+    startWebServer(cliArgs);
+  }
+}