@ebowwa/terminal 0.2.0

package/dist/scp.js

@@ -0,0 +1,74 @@
+/**
+ * SCP/SFTP file transfer operations
+ * Uses SSH connection pool and SFTP for efficient transfers
+ */
+import { SSHError } from "./error.js";
+import { SCPOptionsSchema } from '@ebowwa/codespaces-types/runtime/ssh';
+import { getSSHPool } from './pool.js';
+/**
+ * Upload a file to remote server via SFTP
+ * @param options - SCP options including source and destination
+ * @returns True if successful
+ */
+export async function scpUpload(options) {
+    // Validate inputs with Zod
+    const validated = SCPOptionsSchema.safeParse(options);
+    if (!validated.success) {
+        throw new Error(`Invalid SCP options: ${validated.error.issues.map(i => i.message).join(', ')}`);
+    }
+    const { host, user = "root", timeout = 30, port = 22, keyPath, source, destination, recursive = false, preserve = false, } = validated.data;
+    try {
+        const pool = getSSHPool();
+        const ssh = await pool.getConnection({ host, user, port, keyPath, timeout });
+        // Use SFTP for file transfer
+        await ssh.putFile(source, destination, null, {
+            mode: recursive ? 'recursive' : undefined,
+        });
+        return true;
+    }
+    catch (error) {
+        throw new SSHError(`SFTP upload failed: ${source} -> ${destination}`, error);
+    }
+}
+/**
+ * Download a file from remote server via SFTP
+ * @param options - SCP options including source (remote) and destination (local)
+ * @returns True if successful
+ */
+export async function scpDownload(options) {
+    // Validate inputs with Zod
+    const validated = SCPOptionsSchema.safeParse(options);
+    if (!validated.success) {
+        throw new Error(`Invalid SCP options: ${validated.error.issues.map(i => i.message).join(', ')}`);
+    }
+    const { host, user = "root", timeout = 30, port = 22, keyPath, source, destination, recursive = false, preserve = false, } = validated.data;
+    try {
+        const pool = getSSHPool();
+        const ssh = await pool.getConnection({ host, user, port, keyPath, timeout });
+        // Use SFTP for file transfer
+        await ssh.getFile(destination, source, null, {
+            mode: recursive ? 'recursive' : undefined,
+        });
+        return true;
+    }
+    catch (error) {
+        throw new SSHError(`SFTP download failed: ${source} -> ${destination}`, error);
+    }
+}
+/**
+ * Upload a directory to remote server via SFTP
+ * @param options - SCP options with source directory
+ * @returns True if successful
+ */
+export async function scpUploadDirectory(options) {
+    return scpUpload({ ...options, recursive: true });
+}
+/**
+ * Download a directory from remote server via SFTP
+ * @param options - SCP options with source directory
+ * @returns True if successful
+ */
+export async function scpDownloadDirectory(options) {
+    return scpDownload({ ...options, recursive: true });
+}
+//# sourceMappingURL=scp.js.map

package/dist/sessions.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Terminal Session Management
+ * Handles SSH PTY session lifecycle, persistence, and querying
+ * Uses tmux for persistent sessions that survive disconnections
+ */
+/**
+ * Terminal session interface
+ * Represents an active SSH PTY session
+ */
+export interface TerminalSession {
+    sessionId: string;
+    proc: Subprocess<"pipe", "pipe", "pipe">;
+    stdin: import("bun").SubprocessSink;
+    stdout: ReadableStream<Uint8Array>;
+    stderr: ReadableStream<Uint8Array>;
+    host: string;
+    user: string;
+    ws: ServerWebSocket | null;
+    createdAt: number;
+    lastUsed: number;
+    reader: ReadableStreamDefaultReader<Uint8Array> | null;
+    stderrReader: ReadableStreamDefaultReader<Uint8Array> | null;
+    writer: WritableStreamDefaultWriter<Uint8Array> | null;
+    closed: boolean;
+    tmuxSessionName?: string;
+    bootstrapLogStreamer?: Subprocess;
+}
+/**
+ * Session info for API responses (safe to expose)
+ */
+export interface SessionInfo {
+    sessionId: string;
+    host: string;
+    user: string;
+    createdAt: number;
+    lastUsed: number;
+    hasActiveWebSocket: boolean;
+    closed: boolean;
+}
+/**
+ * Clean up old sessions (older than specified milliseconds)
+ * Called automatically by interval timer
+ */
+export declare function cleanupStaleSessions(maxAge?: number): void;
+/**
+ * Close a specific session
+ */
+export declare function closeSession(sessionId: string): Promise<boolean>;
+/**
+ * Find or create a session for a host
+ * If sessionId is provided, try to reuse that specific session
+ * If sessionId is null/undefined, always create a new session (for multiple terminals)
+ * @param onProgress - Optional callback to send progress updates to WebSocket
+ * @param onBootstrapOutput - Optional callback to stream bootstrap log output to WebSocket
+ */
+export declare function getOrCreateSession(host: string, user?: string, sessionId?: string | null, keyPath?: string, onProgress?: (message: string, status: "info" | "success" | "error") => void, environmentId?: string, onBootstrapOutput?: (data: string) => void): Promise<TerminalSession>;
+/**
+ * Get a session by ID
+ */
+export declare function getSession(sessionId: string): TerminalSession | undefined;
+/**
+ * Get all active sessions
+ */
+export declare function getAllSessions(): TerminalSession[];
+/**
+ * Get session info for all sessions (safe for API responses)
+ */
+export declare function getAllSessionInfo(): SessionInfo[];
+/**
+ * Get session info for a specific session
+ */
+export declare function getSessionInfo(sessionId: string): SessionInfo | undefined;
+/**
+ * Get the total number of active sessions
+ */
+export declare function getSessionCount(): number;
+/**
+ * Find sessions by host
+ */
+export declare function getSessionsByHost(host: string): TerminalSession[];
+/**
+ * Attach a WebSocket to a session
+ * Sets up stdin/stdout/stderr streaming
+ */
+export declare function attachWebSocket(session: TerminalSession, ws: ServerWebSocket, wasReused?: boolean): void;
+/**
+ * Write data to a session's stdin
+ */
+export declare function writeToSession(sessionId: string, data: string): Promise<boolean>;
+/**
+ * Resize a session's PTY
+ */
+export declare function resizeSession(sessionId: string, rows: number, cols: number): Promise<boolean>;
+/**
+ * Detach WebSocket from session (without closing session)
+ */
+export declare function detachWebSocket(sessionId: string, ws: ServerWebSocket): boolean;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/tmux-exec.d.ts

@@ -0,0 +1,50 @@
+/**
+ * SSH command execution via tmux
+ * Executes commands through persistent tmux sessions instead of creating new SSH connections
+ */
+import type { SSHOptions } from "./types.js";
+/**
+ * Execute a command via tmux session (simplified approach)
+ *
+ * DESIGN RATIONALE:
+ * ================
+ *
+ * Current approach: Each API call creates multiple SSH connections
+ * - /api/environments/:id/resources: 4 connections (9 commands distributed)
+ * - /api/environments/:id/node-agent: 1 connection
+ * - Total: 5 SSH connections per page load
+ *
+ * New approach: Use existing tmux session for all commands
+ * - One persistent tmux session per server (already used for terminal WebSocket)
+ * - Execute commands via tmux send-keys, capture output
+ * - Total: 1 SSH connection per server (for tmux session management)
+ *
+ * Implementation:
+ * - Use existing tmux session's main window
+ * - Send command via send-keys
+ * - Wait for completion
+ * - Capture output with capture-pane
+ *
+ * Note: This is a simplified implementation that reuses the main tmux window.
+ * For production, we should create dedicated windows per command.
+ *
+ * @param command - Shell command to execute
+ * @param options - SSH connection options
+ * @param timeout - Command timeout in seconds (default: 10)
+ * @returns Command stdout output
+ */
+export declare function execViaTmux(command: string, options: SSHOptions, timeout?: number): Promise<string>;
+/**
+ * Execute multiple commands in parallel via tmux
+ *
+ * Note: This creates multiple temporary windows in parallel,
+ * each executing one command. This is more efficient than
+ * sequential execution but uses more tmux windows temporarily.
+ *
+ * @param commands - Object mapping names to shell commands
+ * @param options - SSH connection options
+ * @param timeout - Per-command timeout in seconds (default: 10)
+ * @returns Object mapping names to command outputs
+ */
+export declare function execViaTmuxParallel(commands: Record<string, string>, options: SSHOptions, timeout?: number): Promise<Record<string, string>>;
+//# sourceMappingURL=tmux-exec.d.ts.map

package/dist/tmux.d.ts

@@ -0,0 +1,213 @@
+/**
+ * tmux-based Terminal Sessions
+ * Provides persistent terminal sessions using tmux on remote servers
+ * Includes automatic tmux installation and session management
+ */
+import type { SSHOptions } from "./types.js";
+/**
+ * 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;
+}
+/**
+ * Generate a tmux session name for a host
+ */
+export declare function generateSessionName(host: string, user?: string): string;
+/**
+ * Check if tmux is installed on the remote server
+ */
+export declare function isTmuxInstalled(options: SSHOptions): Promise<boolean>;
+/**
+ * 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 declare function installTmux(options: SSHOptions): Promise<{
+    success: boolean;
+    message: string;
+}>;
+/**
+ * Ensure tmux is available, installing if necessary
+ */
+export declare function ensureTmux(options: SSHOptions): Promise<{
+    success: boolean;
+    message: string;
+}>;
+/**
+ * List existing tmux sessions on the remote server
+ */
+export declare function listTmuxSessions(options: SSHOptions): Promise<string[]>;
+/**
+ * Check if a specific tmux session exists
+ */
+export declare function hasTmuxSession(sessionName: string, options: SSHOptions): Promise<boolean>;
+/**
+ * Create or attach to a tmux session
+ * Returns the SSH command arguments to connect to the tmux session
+ */
+export declare function createOrAttachTmuxSession(host: string, user?: string, keyPath?: string, config?: Partial<TmuxConfig>): Promise<{
+    sshArgs: string[];
+    sessionName: string;
+    newlyCreated: boolean;
+}>;
+/**
+ * Kill a tmux session on the remote server
+ */
+export declare function killTmuxSession(sessionName: string, options: SSHOptions): Promise<boolean>;
+/**
+ * Get tmux session information
+ */
+export declare function getTmuxSessionInfo(sessionName: string, options: SSHOptions): Promise<{
+    exists: boolean;
+    windows?: number;
+    panes?: number;
+} | null>;
+/**
+ * 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 declare function cleanupOldTmuxSessions(options: SSHOptions, config?: Partial<TmuxConfig>): Promise<{
+    cleaned: number;
+    errors: string[];
+}>;
+/**
+ * Get resource usage information for tmux sessions on a remote server
+ * @param options SSH connection options
+ * @returns Resource usage summary
+ */
+export declare function getTmuxResourceUsage(options: SSHOptions): Promise<{
+    totalSessions: number;
+    codespacesSessions: number;
+    estimatedMemoryMB: number;
+} | 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 declare function sendCommandToPane(sessionName: string, command: string, paneIndex: string | undefined, options: SSHOptions): Promise<boolean>;
+/**
+ * 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 declare function splitPane(sessionName: string, direction: "h" | "v" | undefined, command: string | null | undefined, options: SSHOptions): Promise<string | null>;
+/**
+ * List all windows in a tmux session
+ * @param sessionName Target tmux session name
+ * @param options SSH connection options
+ */
+export declare function listSessionWindows(sessionName: string, options: SSHOptions): Promise<Array<{
+    index: string;
+    name: string;
+    active: boolean;
+}>>;
+/**
+ * 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 declare function listWindowPanes(sessionName: string, windowIndex: string | undefined, options: SSHOptions): Promise<Array<{
+    index: string;
+    currentPath: string;
+    pid: string;
+    active: boolean;
+}>>;
+/**
+ * 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 declare function capturePane(sessionName: string, paneIndex: string | undefined, options: SSHOptions): Promise<string | 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 declare function getPaneHistory(sessionName: string, paneIndex: string | undefined, lines: number | undefined, options: SSHOptions): Promise<string | 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 declare function switchWindow(sessionName: string, windowIndex: string, options: SSHOptions): Promise<boolean>;
+/**
+ * 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 declare function switchPane(sessionName: string, paneIndex: string, options: SSHOptions): Promise<boolean>;
+/**
+ * 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 declare function renameWindow(sessionName: string, windowIndex: string, newName: string, options: SSHOptions): Promise<boolean>;
+/**
+ * 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 declare function killPane(sessionName: string, paneIndex: string, options: SSHOptions): Promise<boolean>;
+/**
+ * Get detailed information about all panes in a session
+ * @param sessionName Target tmux session name
+ * @param options SSH connection options
+ */
+export declare 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>;
+export {};
+//# sourceMappingURL=tmux.d.ts.map