@ebowwa/terminal 0.3.1 → 0.3.2

package/dist/pool.d.ts

@@ -1,142 +0,0 @@
-/**
- * SSH Connection Pool Manager
- * Maintains persistent SSH connections for reuse across commands
- */
-import { NodeSSH } from 'node-ssh';
-import type { SSHOptions } from './types.js';
-/**
- * Connection pool configuration
- */
-interface PoolConfig {
-    /** Maximum number of connections to keep alive across all hosts */
-    maxConnections: number;
-    /** Maximum number of connections per host (for parallel execution) */
-    maxConnectionsPerHost: number;
-    /** Idle timeout in milliseconds (default: 5 minutes) */
-    idleTimeout: number;
-    /** Connection timeout in milliseconds (default: 10 seconds) */
-    connectionTimeout: number;
-    /** Keep alive interval in milliseconds (default: 30 seconds) */
-    keepAliveInterval: number;
-}
-/**
- * SSH Connection Pool Class
- */
-export declare class SSHConnectionPool {
-    private connections;
-    private config;
-    private cleanupInterval;
-    private nextId;
-    constructor(config?: Partial<PoolConfig>);
-    /**
-     * Generate a unique key for the connection (host-based)
-     */
-    private getKey;
-    /**
-     * Get all connections for a given host
-     */
-    private getConnectionsList;
-    /**
-     * Get or create a connection (returns least recently used connection)
-     */
-    getConnection(options: SSHOptions): Promise<NodeSSH>;
-    /**
-     * Get or create a connection using password authentication
-     */
-    getConnectionWithPassword(host: string, user: string, password: string, port?: number): Promise<NodeSSH>;
-    /**
-     * Get or create multiple connections for parallel execution
-     * @param options - SSH connection options
-     * @param count - Number of connections to retrieve
-     * @returns Array of SSH connections
-     */
-    getConnections(options: SSHOptions, count: number): Promise<NodeSSH[]>;
-    /**
-     * Create a new SSH connection
-     * Tries key-based auth first, then password auth, then SSH agent
-     */
-    private createConnection;
-    /**
-     * Get total number of connections across all hosts
-     */
-    private getTotalConnectionCount;
-    /**
-     * Execute a command using a pooled connection
-     *
-     * ERROR HANDLING BEHAVIOR:
-     * =========================
-     * If result.stderr exists AND result.stdout is empty, we throw an error.
-     * This is intentional - commands that fail should return fallback values
-     * via shell redirection (e.g., `|| echo "0"` or `2>/dev/null`).
-     *
-     * Example of proper fallback handling:
-     *   `type nvidia-smi 2>/dev/null && nvidia-smi ... || echo NOGPU`
-     *
-     * This ensures commands don't silently fail - they must handle their own
-     * error cases and return sensible defaults.
-     */
-    exec(command: string, options: SSHOptions): Promise<string>;
-    /**
-     * Check if a connection exists and is alive for a given host
-     */
-    hasConnection(options: SSHOptions): Promise<boolean>;
-    /**
-     * Close a specific connection by SSH instance
-     */
-    private closeConnectionInstance;
-    /**
-     * Close all connections for a specific host
-     */
-    closeConnection(options: SSHOptions): Promise<void>;
-    /**
-     * Evict the oldest connection from the pool
-     */
-    private evictOldest;
-    /**
-     * Clean up idle connections
-     */
-    private cleanupIdle;
-    /**
-     * Start periodic cleanup
-     */
-    private startCleanup;
-    /**
-     * Stop cleanup interval
-     */
-    private stopCleanup;
-    /**
-     * Close all connections and stop cleanup
-     */
-    closeAll(): Promise<void>;
-    /**
-     * Get pool statistics
-     */
-    getStats(): {
-        totalConnections: number;
-        connections: Array<{
-            host: string;
-            port: number;
-            user: string;
-            lastUsed: Date;
-            idleMs: number;
-            id: string;
-        }>;
-    };
-    /**
-     * Check if a host has an active connection
-     */
-    isConnected(host: string, user?: string, port?: number): boolean;
-}
-/**
- * Get the global connection pool instance
- */
-export declare function getSSHPool(config?: Partial<PoolConfig>): SSHConnectionPool;
-/**
- * Close the global pool (for cleanup/shutdown)
- */
-export declare function closeGlobalSSHPool(): Promise<void>;
-/**
- * Get active SSH connections (for monitoring)
- */
-export declare function getActiveSSHConnections(): ReturnType<SSHConnectionPool['getStats']>;
-export {};

package/dist/pty.d.ts

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

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

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

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

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