@ebowwa/terminal 0.2.0

package/src/tmux.ts

@@ -0,0 +1,711 @@
+/**
+ * tmux-based Terminal Sessions
+ * Provides persistent terminal sessions using tmux on remote servers
+ * Includes automatic tmux installation and session management
+ */
+
+import { getSSHPool } from "./pool.js";
+import type { SSHOptions } from "./types.js";
+import { SSHFlags, SSHPresets, buildSSHArgs, sshConfig, type PTYOptions, type SSHConfigFlag } from "@codespaces/ssh";
+
+/**
+ * tmux session configuration
+ */
+interface TmuxConfig {
+  /** Session name prefix for codespaces sessions */
+  sessionPrefix: string;
+  /** Default shell to use in tmux */
+  defaultShell: string;
+  /** Terminal type */
+  term: string;
+  /** Timeout for SSH commands (seconds) */
+  timeout: number;
+  /** Scrollback limit (lines) */
+  historyLimit: number;
+  /** Session age limit for cleanup (milliseconds) */
+  sessionAgeLimit: number;
+}
+
+const DEFAULT_CONFIG: TmuxConfig = {
+  sessionPrefix: "codespaces",
+  defaultShell: "/bin/bash",
+  term: "xterm-256color",
+  timeout: 30,
+  historyLimit: 10000, // 10k lines ~ 1-2MB per session
+  sessionAgeLimit: 30 * 24 * 60 * 60 * 1000, // 30 days
+};
+
+/**
+ * Generate a tmux session name for a host
+ */
+export function generateSessionName(host: string, user: string = "root"): string {
+  const sanitizedHost = host.replace(/[.]/g, "-");
+  return `${DEFAULT_CONFIG.sessionPrefix}-${sanitizedHost}`;
+}
+
+/**
+ * Check if tmux is installed on the remote server
+ */
+export async function isTmuxInstalled(options: SSHOptions): Promise<boolean> {
+  const pool = getSSHPool();
+  try {
+    const result = await pool.exec("type tmux", {
+      ...options,
+      timeout: 5,
+    });
+    return result !== "0";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install tmux on the remote server
+ *
+ * FALLBACK MECHANISM: This should NOT be the primary installation method.
+ * tmux should be installed via cloud-init during initial node provisioning.
+ *
+ * This function exists for:
+ * - Legacy nodes provisioned before cloud-init included tmux
+ * - Manual node provisioning outside cheapspaces
+ * - Recovery scenarios where cloud-init failed
+ *
+ * @see workspace/docs/design/node-agent/TMUX-INSTALLATION.md
+ * @see workspace/src/lib/bootstrap/cloud-init.ts - where tmux should be added to packages
+ *
+ * Supports Debian/Ubuntu (apt) and CentOS/RHEL (yum/dnf)
+ */
+export async function installTmux(options: SSHOptions): Promise<{ success: boolean; message: string }> {
+  const pool = getSSHPool();
+
+  try {
+    // Detect package manager and install tmux
+    const installCmd = `
+      if command -v apt-get >/dev/null 2>&1; then
+        # Debian/Ubuntu
+        export DEBIAN_FRONTEND=noninteractive
+        apt-get update -qq && apt-get install -y -qq tmux
+      elif command -v yum >/dev/null 2>&1; then
+        # CentOS/RHEL (older)
+        yum install -y -q tmux
+      elif command -v dnf >/dev/null 2>&1; then
+        # Fedora/RHEL (newer)
+        dnf install -y -q tmux
+      elif command -v apk >/dev/null 2>&1; then
+        # Alpine
+        apk add --no-cache tmux
+      else
+        echo "ERROR: No supported package manager found"
+        exit 1
+      fi
+    `;
+
+    await pool.exec(installCmd, {
+      ...options,
+      timeout: 120, // Installation can take time
+    });
+
+    // Verify installation
+    const installed = await isTmuxInstalled(options);
+    if (installed) {
+      return { success: true, message: "tmux installed successfully" };
+    } else {
+      return { success: false, message: "tmux installation failed" };
+    }
+  } catch (error) {
+    return {
+      success: false,
+      message: `tmux installation error: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+/**
+ * Ensure tmux is available, installing if necessary
+ */
+export async function ensureTmux(options: SSHOptions): Promise<{ success: boolean; message: string }> {
+  const installed = await isTmuxInstalled(options);
+  if (installed) {
+    return { success: true, message: "tmux already installed" };
+  }
+
+  console.log("[Tmux] Not installed, attempting installation...");
+  return await installTmux(options);
+}
+
+/**
+ * List existing tmux sessions on the remote server
+ */
+export async function listTmuxSessions(options: SSHOptions): Promise<string[]> {
+  const pool = getSSHPool();
+
+  try {
+    const result = await pool.exec(
+      "tmux list-sessions -F '#{session_name}' 2>/dev/null || echo ''",
+      { ...options, timeout: 5 }
+    );
+
+    if (!result || result === "0" || result.trim() === "") {
+      return [];
+    }
+
+    return result.trim().split("\n");
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Check if a specific tmux session exists
+ */
+export async function hasTmuxSession(sessionName: string, options: SSHOptions): Promise<boolean> {
+  const sessions = await listTmuxSessions(options);
+  return sessions.includes(sessionName);
+}
+
+/**
+ * Create or attach to a tmux session
+ * Returns the SSH command arguments to connect to the tmux session
+ */
+export async function createOrAttachTmuxSession(
+  host: string,
+  user: string = "root",
+  keyPath?: string,
+  config: Partial<TmuxConfig> = {},
+): Promise<{ sshArgs: string[]; sessionName: string; newlyCreated: boolean }> {
+  const fullConfig = { ...DEFAULT_CONFIG, ...config };
+  const sessionName = generateSessionName(host, user);
+  const pool = getSSHPool();
+
+  const sshOptions: SSHOptions = {
+    host,
+    user,
+    port: 22,
+    keyPath,
+    timeout: fullConfig.timeout,
+  };
+
+  // Ensure tmux is installed
+  const tmuxCheck = await ensureTmux(sshOptions);
+  if (!tmuxCheck.success) {
+    throw new Error(`Failed to setup tmux: ${tmuxCheck.message}`);
+  }
+
+  // Check if session already exists
+  const sessionExists = await hasTmuxSession(sessionName, sshOptions);
+
+  // Build SSH command with typed flags
+  const flags = [
+    ...SSHPresets.default,
+    SSHFlags.port(22),
+    SSHFlags.forceTTY(2), // -tt for forced PTY
+  ];
+
+  if (keyPath) {
+    flags.push(SSHFlags.identity(String(keyPath)) as any);
+  }
+
+  const sshArgs = buildSSHArgs(flags, host, user);
+
+  // Tmux commands to create or attach session
+  // -A: Attach to existing session or create new
+  // -s: Session name
+  // new-window: Ensure we have a window (for new sessions)
+  const tmuxCmd = [
+    "tmux",
+    "new-session",
+    "-A",
+    "-s", sessionName,
+    "-n", "codespaces",
+  ];
+
+  sshArgs.push(...tmuxCmd);
+
+  // If creating a new session, also configure it via separate command
+  if (!sessionExists) {
+    try {
+      await pool.exec(`tmux set-option -t "${sessionName}" history-limit ${fullConfig.historyLimit} 2>/dev/null`, {
+        ...sshOptions,
+        timeout: 5,
+      });
+    } catch {
+      // Ignore config errors
+    }
+  }
+
+  return {
+    sshArgs,
+    sessionName,
+    newlyCreated: !sessionExists,
+  };
+}
+
+/**
+ * Kill a tmux session on the remote server
+ */
+export async function killTmuxSession(sessionName: string, options: SSHOptions): Promise<boolean> {
+  const pool = getSSHPool();
+
+  try {
+    await pool.exec(`tmux kill-session -t "${sessionName}" 2>/dev/null`, {
+      ...options,
+      timeout: 5,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get tmux session information
+ */
+export async function getTmuxSessionInfo(sessionName: string, options: SSHOptions): Promise<{
+  exists: boolean;
+  windows?: number;
+  panes?: number;
+} | null> {
+  const pool = getSSHPool();
+
+  try {
+    const result = await pool.exec(
+      `tmux display-message -t "${sessionName}" -p '#{session_windows} #{window_panes}' 2>/dev/null || echo ""`,
+      { ...options, timeout: 5 }
+    );
+
+    if (!result || result.trim() === "" || result === "0") {
+      return { exists: false };
+    }
+
+    const [windows, panes] = result.trim().split(" ").map(Number);
+    return { exists: true, windows, panes };
+  } catch {
+    return { exists: false };
+  }
+}
+
+/**
+ * Cleanup old tmux sessions on a remote server
+ * Kills sessions with matching prefix that are older than specified age limit
+ * @param options SSH connection options
+ * @param config Optional configuration (uses default age limit if not provided)
+ * @returns Object with cleaned count and errors
+ */
+export async function cleanupOldTmuxSessions(
+  options: SSHOptions,
+  config: Partial<TmuxConfig> = {},
+): Promise<{ cleaned: number; errors: string[] }> {
+  const fullConfig = { ...DEFAULT_CONFIG, ...config };
+  const pool = getSSHPool();
+  const errors: string[] = [];
+  let cleaned = 0;
+
+  try {
+    // Get all tmux sessions
+    const sessions = await listTmuxSessions(options);
+
+    // Filter for codespaces sessions
+    const codespacesSessions = sessions.filter(s => s.startsWith(fullConfig.sessionPrefix));
+
+    // Check age of each session by looking at socket file modification time
+    for (const sessionName of codespacesSessions) {
+      try {
+        // Check session age by examining tmux socket file
+        // Tmux sockets are in /tmp/tmux-*/default or /tmp/tmux-*
+        const ageCheckCmd = `
+          find /tmp -type s -name "*${sessionName}*" 2>/dev/null | head -1 | while read socket; do
+            if [ -n "$socket" ]; then
+              # Get file modification time in seconds since epoch
+              mtime=$(stat -c %Y "$socket" 2>/dev/null || stat -f %m "$socket" 2>/dev/null)
+              if [ -n "$mtime" ]; then
+                now=$(date +%s)
+                age=$((now - mtime))
+                age_ms=$((age * 1000))
+                echo "$age_ms"
+              fi
+            fi
+          done
+        `;
+
+        const ageResult = await pool.exec(ageCheckCmd, { ...options, timeout: 10 });
+        const ageMs = parseInt(ageResult.trim());
+
+        if (!isNaN(ageMs) && ageMs > fullConfig.sessionAgeLimit) {
+          console.log(`[Tmux] Cleaning up old session "${sessionName}" (age: ${Math.round(ageMs / 86400000)} days)`);
+          await killTmuxSession(sessionName, options);
+          cleaned++;
+        }
+      } catch (err) {
+        errors.push(`${sessionName}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    return { cleaned, errors };
+  } catch (err) {
+    errors.push(`Cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+    return { cleaned, errors };
+  }
+}
+
+/**
+ * Get resource usage information for tmux sessions on a remote server
+ * @param options SSH connection options
+ * @returns Resource usage summary
+ */
+export async function getTmuxResourceUsage(options: SSHOptions): Promise<{
+  totalSessions: number;
+  codespacesSessions: number;
+  estimatedMemoryMB: number;
+} | null> {
+  const pool = getSSHPool();
+
+  try {
+    // Get count of tmux sessions
+    const sessions = await listTmuxSessions(options);
+    const codespacesSessions = sessions.filter(s => s.startsWith(DEFAULT_CONFIG.sessionPrefix));
+
+    // Estimate memory: each session ~10MB base + scrollback buffer
+    // Scrollback: 10000 lines × ~100 bytes/line = ~1MB per session
+    const estimatedMemoryMB = codespacesSessions.length * 11;
+
+    return {
+      totalSessions: sessions.length,
+      codespacesSessions: codespacesSessions.length,
+      estimatedMemoryMB,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Send a command to a specific pane in a tmux session
+ * @param sessionName Target tmux session name
+ * @param paneIndex Pane index (default: 0 for first pane)
+ * @param command Command to execute (sent as keystrokes)
+ * @param options SSH connection options
+ */
+export async function sendCommandToPane(
+  sessionName: string,
+  command: string,
+  paneIndex: string = "0",
+  options: SSHOptions
+): Promise<boolean> {
+  const pool = getSSHPool();
+
+  try {
+    // Use send-keys to send command as keystrokes, then Enter
+    const escapedCmd = command.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    await pool.exec(
+      `tmux send-keys -t "${sessionName}:${paneIndex}" "${escapedCmd}" Enter`,
+      { ...options, timeout: 5 }
+    );
+    return true;
+  } catch (error) {
+    console.error(`[Tmux] Failed to send command to ${sessionName}:${paneIndex}:`, error);
+    return false;
+  }
+}
+
+/**
+ * Split a pane horizontally or vertically in a tmux session
+ * @param sessionName Target tmux session name
+ * @param windowIndex Window index (default: 0)
+ * @param direction Split direction: "h" (horizontal) or "v" (vertical)
+ * @param command Optional command to run in the new pane
+ * @param options SSH connection options
+ * @returns The new pane index
+ */
+export async function splitPane(
+  sessionName: string,
+  direction: "h" | "v" = "v",
+  command: string | null = null,
+  options: SSHOptions
+): Promise<string | null> {
+  const pool = getSSHPool();
+
+  try {
+    // Split the pane and capture the new pane ID
+    const splitCmd = command
+      ? `tmux split-window -${direction} -t "${sessionName}" -c "#{pane_current_path}" "${command}"`
+      : `tmux split-window -${direction} -t "${sessionName}"`;
+
+    const result = await pool.exec(splitCmd, { ...options, timeout: 10 });
+
+    // Return the result which contains the new pane ID
+    return result?.trim() || null;
+  } catch (error) {
+    console.error(`[Tmux] Failed to split pane in ${sessionName}:`, error);
+    return null;
+  }
+}
+
+/**
+ * List all windows in a tmux session
+ * @param sessionName Target tmux session name
+ * @param options SSH connection options
+ */
+export async function listSessionWindows(
+  sessionName: string,
+  options: SSHOptions
+): Promise<Array<{ index: string; name: string; active: boolean }>> {
+  const pool = getSSHPool();
+
+  try {
+    const result = await pool.exec(
+      `tmux list-windows -t "${sessionName}" -F '#{window_index} #{window_name} #{window_active}' 2>/dev/null || echo ''`,
+      { ...options, timeout: 5 }
+    );
+
+    if (!result || result.trim() === "" || result === "0") {
+      return [];
+    }
+
+    return result.trim().split("\n").map(line => {
+      const [index, name, active] = line.split(" ");
+      return { index, name, active: active === "1" };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * List all panes in a tmux session window
+ * @param sessionName Target tmux session name
+ * @param windowIndex Window index (default: 0)
+ * @param options SSH connection options
+ */
+export async function listWindowPanes(
+  sessionName: string,
+  windowIndex: string = "0",
+  options: SSHOptions
+): Promise<Array<{ index: string; currentPath: string; pid: string; active: boolean }>> {
+  const pool = getSSHPool();
+
+  try {
+    const result = await pool.exec(
+      `tmux list-panes -t "${sessionName}:${windowIndex}" -F '#{pane_index} #{pane_current_path} #{pane_pid} #{pane_active}' 2>/dev/null || echo ''`,
+      { ...options, timeout: 5 }
+    );
+
+    if (!result || result.trim() === "" || result === "0") {
+      return [];
+    }
+
+    return result.trim().split("\n").map(line => {
+      const [index, currentPath, pid, active] = line.split(" ");
+      return { index, currentPath, pid, active: active === "1" };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Capture the current output of a pane
+ * @param sessionName Target tmux session name
+ * @param paneIndex Pane index (default: 0)
+ * @param options SSH connection options
+ */
+export async function capturePane(
+  sessionName: string,
+  paneIndex: string = "0",
+  options: SSHOptions
+): Promise<string | null> {
+  const pool = getSSHPool();
+
+  try {
+    const result = await pool.exec(
+      `tmux capture-pane -t "${sessionName}:${paneIndex}" -p`,
+      { ...options, timeout: 5 }
+    );
+
+    return result || null;
+  } catch (error) {
+    console.error(`[Tmux] Failed to capture pane ${sessionName}:${paneIndex}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Get scrollback/history from a pane
+ * @param sessionName Target tmux session name
+ * @param paneIndex Pane index (default: 0)
+ * @param lines Number of lines to retrieve (default: all)
+ * @param options SSH connection options
+ */
+export async function getPaneHistory(
+  sessionName: string,
+  paneIndex: string = "0",
+  lines: number = -1,
+  options: SSHOptions
+): Promise<string | null> {
+  const pool = getSSHPool();
+
+  try {
+    const linesArg = lines > 0 ? `-S -${lines}` : "-S -";
+    const result = await pool.exec(
+      `tmux capture-pane ${linesArg} -t "${sessionName}:${paneIndex}" -p`,
+      { ...options, timeout: 10 }
+    );
+
+    return result || null;
+  } catch (error) {
+    console.error(`[Tmux] Failed to get history for ${sessionName}:${paneIndex}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Switch to a specific window in a tmux session
+ * @param sessionName Target tmux session name
+ * @param windowIndex Target window index
+ * @param options SSH connection options
+ */
+export async function switchWindow(
+  sessionName: string,
+  windowIndex: string,
+  options: SSHOptions
+): Promise<boolean> {
+  const pool = getSSHPool();
+
+  try {
+    await pool.exec(
+      `tmux select-window -t "${sessionName}:${windowIndex}"`,
+      { ...options, timeout: 5 }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Switch to a specific pane in a tmux session window
+ * @param sessionName Target tmux session name
+ * @param paneIndex Target pane index (e.g., "0", "1", "0.1" for window.pane)
+ * @param options SSH connection options
+ */
+export async function switchPane(
+  sessionName: string,
+  paneIndex: string,
+  options: SSHOptions
+): Promise<boolean> {
+  const pool = getSSHPool();
+
+  try {
+    await pool.exec(
+      `tmux select-pane -t "${sessionName}:${paneIndex}"`,
+      { ...options, timeout: 5 }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rename a window in a tmux session
+ * @param sessionName Target tmux session name
+ * @param windowIndex Window index (default: 0)
+ * @param newName New window name
+ * @param options SSH connection options
+ */
+export async function renameWindow(
+  sessionName: string,
+  windowIndex: string,
+  newName: string,
+  options: SSHOptions
+): Promise<boolean> {
+  const pool = getSSHPool();
+
+  try {
+    await pool.exec(
+      `tmux rename-window -t "${sessionName}:${windowIndex}" "${newName}"`,
+      { ...options, timeout: 5 }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Kill a specific pane in a tmux session
+ * @param sessionName Target tmux session name
+ * @param paneIndex Pane index to kill
+ * @param options SSH connection options
+ */
+export async function killPane(
+  sessionName: string,
+  paneIndex: string,
+  options: SSHOptions
+): Promise<boolean> {
+  const pool = getSSHPool();
+
+  try {
+    await pool.exec(
+      `tmux kill-pane -t "${sessionName}:${paneIndex}"`,
+      { ...options, timeout: 5 }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get detailed information about all panes in a session
+ * @param sessionName Target tmux session name
+ * @param options SSH connection options
+ */
+export async function getDetailedSessionInfo(
+  sessionName: string,
+  options: SSHOptions
+): Promise<{
+  exists: boolean;
+  windows: Array<{
+    index: string;
+    name: string;
+    active: boolean;
+    panes: Array<{
+      index: string;
+      currentPath: string;
+      pid: string;
+      active: boolean;
+    }>;
+  }>;
+} | null> {
+  const pool = getSSHPool();
+
+  try {
+    // First check if session exists
+    const exists = await hasTmuxSession(sessionName, options);
+    if (!exists) {
+      return { exists: false, windows: [] };
+    }
+
+    // Get all windows
+    const windows = await listSessionWindows(sessionName, options);
+
+    // Get panes for each window
+    const windowsWithPanes = await Promise.all(
+      windows.map(async (window) => {
+        const panes = await listWindowPanes(sessionName, window.index, options);
+        return {
+          ...window,
+          panes,
+        };
+      })
+    );
+
+    return {
+      exists: true,
+      windows: windowsWithPanes,
+    };
+  } catch (error) {
+    console.error(`[Tmux] Failed to get detailed info for ${sessionName}:`, error);
+    return null;
+  }
+}