@ebowwa/terminal 0.3.4 → 0.3.6

package/dist/pty.d.ts

@@ -0,0 +1,58 @@
+/**
+ * SSH PTY session manager for interactive terminal sessions
+ * Handles bidirectional communication with remote shells
+ */
+interface PTYSession {
+    id: string;
+    host: string;
+    user: string;
+    proc: any;
+    stdin: WritableStream<Uint8Array>;
+    stdout: ReadableStream<Uint8Array>;
+    stderr: ReadableStream<Uint8Array>;
+    rows: number;
+    cols: number;
+    createdAt: number;
+}
+/**
+ * Create a new SSH PTY session
+ * Uses script or expect to wrap SSH with PTY allocation
+ */
+export declare function createPTYSession(host: string, user?: string, options?: {
+    rows?: number;
+    cols?: number;
+    port?: number;
+    keyPath?: string;
+}): Promise<{
+    sessionId: string;
+    initialOutput: string;
+}>;
+/**
+ * Write data to PTY session stdin
+ */
+export declare function writeToPTY(sessionId: string, data: string): Promise<boolean>;
+/**
+ * Set PTY size (rows and columns)
+ */
+export declare function setPTYSize(sessionId: string, rows: number, cols: number): Promise<boolean>;
+/**
+ * Read from PTY session stdout (non-blocking)
+ */
+export declare function readFromPTY(sessionId: string, timeout?: number): Promise<string | null>;
+/**
+ * Close PTY session
+ */
+export declare function closePTYSession(sessionId: string): Promise<boolean>;
+/**
+ * Get session info
+ */
+export declare function getPTYSession(sessionId: string): PTYSession | undefined;
+/**
+ * Get all active sessions
+ */
+export declare function getActivePTYSessions(): PTYSession[];
+/**
+ * Clean up stale sessions (older than specified milliseconds)
+ */
+export declare function cleanupStaleSessions(maxAge?: number): void;
+export {};

package/dist/resources.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Resource monitoring commands for remote servers
+ *
+ * SSH commands for fetching system resources via execSSHParallel
+ * Returns: raw command string to execute via SSH
+ *
+ * Commands avoid complex quoting for reliable SSH execution
+ */
+/**
+ * SSH commands for fetching system resources
+ * Each command returns space-separated values for easy parsing
+ */
+export declare const RESOURCE_COMMANDS: {
+    /**
+     * CPU usage percentage
+     * Format: "12.5" (user+system as percentage of total)
+     */
+    readonly cpu: "cat /proc/stat | head -1 | awk '{print ($2+$4)*100/($2+$4+$5)}'";
+    /**
+     * Memory usage - reads from /proc/meminfo
+     * Format: "percent used_gb total_gb"
+     * Example: "17.5 0.7 3.7"
+     */
+    readonly memory: "cat /proc/meminfo | grep -E '^MemTotal|^MemAvailable' | awk '{if(NR==1)t=$2; else a=$2} END {print (t-a)*100/t, (t-a)/1024/1024, t/1024/1024}'";
+    /**
+     * Disk usage for root partition
+     * Format: "percent used_size total_size"
+     * Example: "4% 2.8G 75G"
+     */
+    readonly disk: "df -h / | grep -v '^Filesystem' | awk '{print $5, $3, $2}' | head -1";
+    /**
+     * GPU usage (if NVIDIA GPU present)
+     * Format: "utilization_percent memory_used_mb memory_total_mb" or "NOGPU"
+     */
+    readonly gpu: "type nvidia-smi 2>/dev/null && nvidia-smi --query-gpu=utilization.gpu,memory.used,memory.total --format=csv,noheader,nounits | head -1 || echo NOGPU";
+    /**
+     * Network I/O bytes (total rx/tx since boot)
+     * Format: "rx_bytes tx_bytes"
+     */
+    readonly network: "cat /proc/net/dev | grep -E ': ' | head -1 | awk '{print $2, $10}'";
+    /**
+     * Load average (1min, 5min, 15min)
+     * Format: "1min 5min 15min"
+     */
+    readonly loadavg: "cut -d' ' -f1-3 /proc/loadavg";
+    /**
+     * Active process count
+     * Format: "count"
+     */
+    readonly processes: "ls /proc 2>/dev/null | grep -cE '^[0-9]+$'";
+    /**
+     * Active network connections (established + listening)
+     * Format: "count"
+     */
+    readonly connections: "cat /proc/net/tcp /proc/net/tcp6 2>/dev/null | wc -l";
+    /**
+     * Active listening ports (hex format)
+     * Format: "port1;port2;..." or empty
+     */
+    readonly ports: "cat /proc/net/tcp /proc/net/tcp6 2>/dev/null | grep -v 'local_address' | awk '{print $2}' | cut -d: -f2 | sort -u | tr '\\n' ';' | sed 's/;$//'";
+};
+export type ResourceCommand = keyof typeof RESOURCE_COMMANDS;

package/dist/scp.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SCP/SFTP file transfer operations
+ * Uses SSH connection pool and SFTP for efficient transfers
+ */
+import type { SCPOptions } from "./types.js";
+/**
+ * Upload a file to remote server via SFTP
+ * @param options - SCP options including source and destination
+ * @returns True if successful
+ */
+export declare function scpUpload(options: SCPOptions): Promise<boolean>;
+/**
+ * Download a file from remote server via SFTP
+ * @param options - SCP options including source (remote) and destination (local)
+ * @returns True if successful
+ */
+export declare function scpDownload(options: SCPOptions): Promise<boolean>;
+/**
+ * Upload a directory to remote server via SFTP
+ * @param options - SCP options with source directory
+ * @returns True if successful
+ */
+export declare function scpUploadDirectory(options: SCPOptions): Promise<boolean>;
+/**
+ * Download a directory from remote server via SFTP
+ * @param options - SCP options with source directory
+ * @returns True if successful
+ */
+export declare function scpDownloadDirectory(options: SCPOptions): Promise<boolean>;

package/dist/sessions.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Terminal Session Management
+ * Handles SSH PTY session lifecycle, persistence, and querying
+ * Uses tmux for persistent sessions that survive disconnections
+ */
+import type { ServerWebSocket, Subprocess } from "bun";
+/**
+ * Terminal session interface
+ * Represents an active SSH PTY session
+ */
+export interface TerminalSession {
+    sessionId: string;
+    proc: Subprocess<"pipe", "pipe", "pipe">;
+    stdin: Subprocess<"pipe", "pipe", "pipe">["stdin"];
+    stdout: ReadableStream<Uint8Array>;
+    stderr: ReadableStream<Uint8Array>;
+    host: string;
+    user: string;
+    ws: ServerWebSocket<unknown> | 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;
+    uptime: number;
+    idleTime: number;
+}
+/**
+ * Clean up old sessions (older than specified milliseconds)
+ * Called automatically by interval timer
+ */
+export declare function cleanupStaleSessions(maxAge?: number): string[];
+/**
+ * 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<unknown>, 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;

package/dist/tmux-exec.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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>>;

package/dist/tmux-local.d.ts

@@ -0,0 +1,272 @@
+/**
+ * tmux-based Local Terminal Sessions
+ * Provides persistent terminal sessions using local tmux for SSH connections
+ * SSH connections stay active within tmux sessions on the local machine
+ */
+/**
+ * Local tmux session configuration
+ */
+interface LocalTmuxConfig {
+    /** Session name prefix for local MCP SSH sessions */
+    sessionPrefix: string;
+    /** Default shell to use in tmux */
+    defaultShell: string;
+    /** Terminal type */
+    term: string;
+    /** Timeout for local commands (seconds) */
+    timeout: number;
+    /** Scrollback limit (lines) */
+    historyLimit: number;
+    /** Session age limit for cleanup (milliseconds) */
+    sessionAgeLimit: number;
+}
+/**
+ * Options for creating a local tmux SSH session
+ */
+export interface LocalTmuxSessionOptions {
+    /** Initial command to run after SSH connection */
+    initialCommand?: string;
+    /** Custom session name (auto-generated if not provided) */
+    sessionName?: string;
+    /** Window name */
+    windowName?: string;
+}
+/**
+ * Result of creating a local tmux session
+ */
+export interface LocalTmuxSessionResult {
+    /** Session name */
+    sessionName: string;
+    /** Whether the session was newly created */
+    newlyCreated: boolean;
+    /** Full tmux command used to create the session */
+    command: string;
+}
+/**
+ * Check if tmux is installed locally
+ */
+export declare function isLocalTmuxInstalled(): Promise<boolean>;
+/**
+ * Generate a local tmux session name for a host
+ * @param host - Remote host IP or hostname
+ * @param user - SSH user (default: "root")
+ * @returns Session name (e.g., "mcp-ssh-192-168-1-1")
+ */
+export declare function generateLocalSessionName(host: string, user?: string): string;
+/**
+ * List all local tmux sessions
+ * @returns Array of session names
+ */
+export declare function listLocalSessions(): Promise<string[]>;
+/**
+ * Check if a specific local tmux session exists
+ * @param sessionName - Session name to check
+ * @returns True if session exists
+ */
+export declare function hasLocalSession(sessionName: string): Promise<boolean>;
+/**
+ * Create a local tmux session with an active SSH connection
+ *
+ * This function creates a tmux session on the local machine that maintains
+ * an active SSH connection to the remote host. The connection stays alive
+ * within the tmux session, allowing for persistent interactions.
+ *
+ * @param host - Remote host IP or hostname
+ * @param user - SSH user (default: "root")
+ * @param keyPath - Path to SSH private key (for key-based auth)
+ * @param password - SSH password (for password-based auth)
+ * @param options - Additional options for session creation
+ * @returns Session creation result
+ *
+ * @example
+ * ```ts
+ * // Key-based authentication
+ * const result = await createLocalTmuxSSHSession(
+ *   "192.168.1.100",
+ *   "root",
+ *   "/path/to/key"
+ * );
+ *
+ * // Password-based authentication (requires sshpass)
+ * const result = await createLocalTmuxSSHSession(
+ *   "192.168.1.100",
+ *   "root",
+ *   undefined,
+ *   "mypassword"
+ * );
+ * ```
+ */
+export declare function createLocalTmuxSSHSession(host: string, user?: string, keyPath?: string, password?: string, options?: LocalTmuxSessionOptions): Promise<LocalTmuxSessionResult>;
+/**
+ * Send a command to a local tmux pane (already SSH'd into the remote host)
+ *
+ * This function sends a command to the tmux pane, which will be executed
+ * on the remote host since the SSH connection is already active.
+ *
+ * @param sessionName - Local tmux session name
+ * @param command - Command to send to the remote host
+ * @param paneIndex - Pane index (default: "0")
+ * @param windowName - Window name (default: auto-detects first window)
+ * @returns True if command was sent successfully
+ */
+export declare function sendCommandToLocalSession(sessionName: string, command: string, paneIndex?: string, windowName?: string): Promise<boolean>;
+/**
+ * Capture output from a local tmux pane
+ *
+ * This captures the current visible content of the pane, including
+ * the scrollback history.
+ *
+ * @param sessionName - Local tmux session name
+ * @param paneIndex - Pane index (default: "0")
+ * @param windowName - Window name (default: auto-detects first window)
+ * @returns Captured output or null if failed
+ */
+export declare function captureLocalPane(sessionName: string, paneIndex?: string, windowName?: string): Promise<string | null>;
+/**
+ * Get scrollback/history from a local tmux pane
+ *
+ * @param sessionName - Local tmux session name
+ * @param paneIndex - Pane index (default: "0")
+ * @param lines - Number of lines to retrieve (default: -1 for all)
+ * @param windowName - Window name (default: auto-detects first window)
+ * @returns History content or null if failed
+ */
+export declare function getLocalPaneHistory(sessionName: string, paneIndex?: string, lines?: number, windowName?: string): Promise<string | null>;
+/**
+ * Kill a local tmux session
+ *
+ * @param sessionName - Session name to kill
+ * @returns True if session was killed successfully
+ */
+export declare function killLocalSession(sessionName: string): Promise<boolean>;
+/**
+ * Get information about a local tmux session
+ *
+ * @param sessionName - Session name to query
+ * @returns Session information or null if session doesn't exist
+ */
+export declare function getLocalSessionInfo(sessionName: string): Promise<{
+    exists: boolean;
+    windows?: number;
+    panes?: number;
+} | null>;
+/**
+ * List all windows in a local tmux session
+ *
+ * @param sessionName - Local tmux session name
+ * @returns Array of window information
+ */
+export declare function listLocalSessionWindows(sessionName: string): Promise<Array<{
+    index: string;
+    name: string;
+    active: boolean;
+}>>;
+/**
+ * List all panes in a local tmux session window
+ *
+ * @param sessionName - Local tmux session name
+ * @param windowIndex - Window index (default: "0")
+ * @returns Array of pane information
+ */
+export declare function listLocalWindowPanes(sessionName: string, windowIndex?: string): Promise<Array<{
+    index: string;
+    currentPath: string;
+    pid: string;
+    active: boolean;
+}>>;
+/**
+ * Split a pane horizontally or vertically in a local tmux session
+ *
+ * @param sessionName - Local tmux session name
+ * @param direction - Split direction: "h" (horizontal) or "v" (vertical)
+ * @param command - Optional command to run in the new pane
+ * @param windowName - Window name (default: auto-detects first window)
+ * @returns The new pane index or null if failed
+ */
+export declare function splitLocalPane(sessionName: string, direction?: "h" | "v", command?: string, windowName?: string): Promise<string | null>;
+/**
+ * Cleanup old local tmux sessions
+ *
+ * @param config - Optional configuration (uses default age limit if not provided)
+ * @returns Object with cleaned count and errors
+ */
+export declare function cleanupOldLocalSessions(config?: Partial<LocalTmuxConfig>): Promise<{
+    cleaned: number;
+    errors: string[];
+}>;
+/**
+ * Get resource usage information for local tmux sessions
+ *
+ * @returns Resource usage summary
+ */
+export declare function getLocalTmuxResourceUsage(): Promise<{
+    totalSessions: number;
+    mcpSessions: number;
+    estimatedMemoryMB: number;
+} | null>;
+/**
+ * Wait for a specific text to appear in the pane output
+ *
+ * @param sessionName - Local tmux session name
+ * @param text - Text to wait for
+ * @param timeoutMs - Maximum time to wait in milliseconds (default: 30000)
+ * @param paneIndex - Pane index (default: "0")
+ * @param windowName - Window name (default: auto-detects first window)
+ * @returns True if text appeared, false if timeout
+ */
+export declare function waitForTextInPane(sessionName: string, text: string, timeoutMs?: number, paneIndex?: string, windowName?: string): Promise<boolean>;
+/**
+ * Switch to a specific window in a local tmux session
+ *
+ * @param sessionName - Local tmux session name
+ * @param windowIndex - Target window index
+ * @returns True if successful
+ */
+export declare function switchLocalWindow(sessionName: string, windowIndex: string): Promise<boolean>;
+/**
+ * Switch to a specific pane in a local tmux session window
+ *
+ * @param sessionName - Local tmux session name
+ * @param paneIndex - Target pane index (e.g., "0", "1", "0.1" for window.pane)
+ * @returns True if successful
+ */
+export declare function switchLocalPane(sessionName: string, paneIndex: string): Promise<boolean>;
+/**
+ * Rename a window in a local tmux session
+ *
+ * @param sessionName - Local tmux session name
+ * @param windowIndex - Window index (default: "0")
+ * @param newName - New window name
+ * @returns True if successful
+ */
+export declare function renameLocalWindow(sessionName: string, windowIndex: string, newName: string): Promise<boolean>;
+/**
+ * Kill a specific pane in a local tmux session
+ *
+ * @param sessionName - Local tmux session name
+ * @param paneIndex - Pane index to kill
+ * @param windowName - Window name (default: auto-detects first window)
+ * @returns True if successful
+ */
+export declare function killLocalPane(sessionName: string, paneIndex: string, windowName?: string): Promise<boolean>;
+/**
+ * Get detailed information about all panes in a local session
+ *
+ * @param sessionName - Local tmux session name
+ * @returns Detailed session information or null
+ */
+export declare function getDetailedLocalSessionInfo(sessionName: string): Promise<{
+    exists: boolean;
+    windows: Array<{
+        index: string;
+        name: string;
+        active: boolean;
+        panes: Array<{
+            index: string;
+            currentPath: string;
+            pid: string;
+            active: boolean;
+        }>;
+    }>;
+} | null>;
+export {};