@ebowwa/terminal 0.2.0

package/dist/tmux.js

@@ -0,0 +1,528 @@
+/**
+ * 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 { SSHFlags, SSHPresets, buildSSHArgs } from "@codespaces/ssh";
+const DEFAULT_CONFIG = {
+    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, user = "root") {
+    const sanitizedHost = host.replace(/[.]/g, "-");
+    return `${DEFAULT_CONFIG.sessionPrefix}-${sanitizedHost}`;
+}
+/**
+ * Check if tmux is installed on the remote server
+ */
+export async function isTmuxInstalled(options) {
+    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) {
+    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) {
+    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) {
+    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, options) {
+    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, user = "root", keyPath, config = {}) {
+    const fullConfig = { ...DEFAULT_CONFIG, ...config };
+    const sessionName = generateSessionName(host, user);
+    const pool = getSSHPool();
+    const 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)));
+    }
+    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, options) {
+    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, options) {
+    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, config = {}) {
+    const fullConfig = { ...DEFAULT_CONFIG, ...config };
+    const pool = getSSHPool();
+    const errors = [];
+    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) {
+    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, command, paneIndex = "0", options) {
+    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, direction = "v", command = null, options) {
+    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, options) {
+    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, windowIndex = "0", options) {
+    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, paneIndex = "0", options) {
+    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, paneIndex = "0", lines = -1, options) {
+    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, windowIndex, options) {
+    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, paneIndex, options) {
+    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, windowIndex, newName, options) {
+    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, paneIndex, options) {
+    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, options) {
+    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;
+    }
+}
+//# sourceMappingURL=tmux.js.map

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SSH type definitions
+ */
+export interface SSHOptions {
+    host: string;
+    user?: string;
+    timeout?: number;
+    port?: number;
+    keyPath?: string;
+    password?: string;
+}
+export interface SCPOptions extends SSHOptions {
+    source: string;
+    destination: string;
+    recursive?: boolean;
+    preserve?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * SSH type definitions
+ */
+export {};
+//# sourceMappingURL=types.js.map