@ebowwa/terminal 0.2.1 → 0.3.1

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 {};

package/dist/tmux-manager.d.ts

@@ -0,0 +1,327 @@
+/**
+ * Multi-Node Tmux Session Manager
+ * Provides unified management of tmux sessions across multiple VPS nodes
+ * Supports batch operations, session tracking, and parallel execution
+ */
+/**
+ * Represents a single node (server) in the cluster
+ */
+export interface Node {
+    /** Unique identifier (server ID from Hetzner) */
+    id: string;
+    /** Server name */
+    name: string;
+    /** IPv4 address */
+    ip: string;
+    /** IPv6 address (optional) */
+    ipv6?: string | null;
+    /** SSH user */
+    user: string;
+    /** SSH port */
+    port: number;
+    /** SSH key path (optional) */
+    keyPath?: string;
+    /** Node status */
+    status: "running" | "stopped" | "unreachable";
+    /** Metadata tags */
+    tags?: string[];
+    /** Datacenter location */
+    location?: string;
+}
+/**
+ * Represents a tmux session on a node
+ */
+export interface TmuxSession {
+    /** Session name */
+    name: string;
+    /** Node ID */
+    nodeId: string;
+    /** Number of windows */
+    windows?: number;
+    /** Number of panes */
+    panes?: number;
+    /** Session exists */
+    exists: boolean;
+}
+/**
+ * Detailed session information with windows and panes
+ */
+export interface DetailedTmuxSession extends TmuxSession {
+    windows: Array<{
+        index: string;
+        name: string;
+        active: boolean;
+        panes: Array<{
+            index: string;
+            currentPath: string;
+            pid: string;
+            active: boolean;
+        }>;
+    }>;
+}
+/**
+ * Batch operation result across multiple nodes
+ */
+export interface BatchOperationResult<T = any> {
+    /** Total nodes in batch */
+    total: number;
+    /** Successful operations */
+    successful: number;
+    /** Failed operations */
+    failed: number;
+    /** Results per node */
+    results: Array<{
+        nodeId: string;
+        nodeName: string;
+        success: boolean;
+        data?: T;
+        error?: string;
+    }>;
+}
+/**
+ * Options for creating a new tmux session
+ */
+export interface CreateSessionOptions {
+    /** Session name (auto-generated if not provided) */
+    sessionName?: string;
+    /** Initial working directory */
+    cwd?: string;
+    /** Initial command to run */
+    initialCommand?: string;
+    /** Window layout */
+    layout?: "even-horizontal" | "even-vertical" | "main-horizontal" | "main-vertical" | "tiled";
+}
+/**
+ * Options for batch command execution
+ */
+export interface BatchCommandOptions {
+    /** Command to execute */
+    command: string;
+    /** Target pane index (default: "0") */
+    paneIndex?: string;
+    /** Execute in parallel (default: true) */
+    parallel?: boolean;
+    /** Continue on error (default: true) */
+    continueOnError?: boolean;
+    /** Timeout per node (seconds) */
+    timeout?: number;
+}
+/**
+ * Options for multi-node session queries
+ */
+export interface SessionQueryOptions {
+    /** Filter by node IDs */
+    nodeIds?: string[];
+    /** Filter by tags */
+    tags?: string[];
+    /** Include detailed session info */
+    detailed?: boolean;
+    /** Include inactive sessions */
+    includeInactive?: boolean;
+}
+/**
+ * Multi-Node Tmux Session Manager
+ * Manages tmux sessions across multiple VPS nodes
+ */
+export declare class TmuxSessionManager {
+    private nodes;
+    private sessionCache;
+    private cacheTimeout;
+    private lastCacheUpdate;
+    /**
+     * Add or update a node in the manager
+     */
+    addNode(node: Node): void;
+    /**
+     * Remove a node from the manager
+     */
+    removeNode(nodeId: string): void;
+    /**
+     * Get a node by ID
+     */
+    getNode(nodeId: string): Node | undefined;
+    /**
+     * Get all nodes
+     */
+    getAllNodes(): Node[];
+    /**
+     * Get nodes by tag
+     */
+    getNodesByTag(tag: string): Node[];
+    /**
+     * Get active nodes (running and reachable)
+     */
+    getActiveNodes(): Node[];
+    /**
+     * Get SSH options for a node
+     */
+    private getSSHOptions;
+    /**
+     * Invalidate session cache for a node or all nodes
+     */
+    invalidateCache(nodeId?: string): void;
+    /**
+     * Check if cache is valid for a node
+     */
+    private isCacheValid;
+    /**
+     * Create a new tmux session on a node
+     */
+    createSession(nodeId: string, options?: CreateSessionOptions): Promise<{
+        success: boolean;
+        sessionName?: string;
+        error?: string;
+    }>;
+    /**
+     * Attach to a tmux session on a node (returns SSH command args)
+     */
+    attachSession(nodeId: string, sessionName?: string): Promise<{
+        success: true;
+        sshArgs: string[];
+        sessionName: string;
+    } | {
+        success: false;
+        error: string;
+    }>;
+    /**
+     * List all sessions across nodes
+     */
+    listSessions(options?: SessionQueryOptions): Promise<TmuxSession[]>;
+    /**
+     * Get detailed session information
+     */
+    getDetailedSession(nodeId: string, sessionName: string): Promise<DetailedTmuxSession | null>;
+    /**
+     * Kill a session on a node
+     */
+    killSession(nodeId: string, sessionName: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Send a command to a specific session on a node
+     */
+    sendCommand(nodeId: string, sessionName: string, command: string, paneIndex?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Send command to multiple nodes (batch operation)
+     */
+    sendCommandToNodes(nodeIds: string[], sessionName: string, command: string, options?: BatchCommandOptions): Promise<BatchOperationResult>;
+    /**
+     * Split a pane in a session
+     */
+    splitPaneOnNode(nodeId: string, sessionName: string, direction?: "h" | "v", command?: string | null, windowIndex?: string): Promise<{
+        success: boolean;
+        newPaneIndex?: string;
+        error?: string;
+    }>;
+    /**
+     * Capture pane output from a session
+     */
+    capturePaneOutput(nodeId: string, sessionName: string, paneIndex?: string): Promise<{
+        success: boolean;
+        output?: string;
+        error?: string;
+    }>;
+    /**
+     * Get pane history (scrollback buffer)
+     */
+    getPaneHistory(nodeId: string, sessionName: string, paneIndex?: string, lines?: number): Promise<{
+        success: boolean;
+        history?: string;
+        error?: string;
+    }>;
+    /**
+     * List windows in a session
+     */
+    listWindows(nodeId: string, sessionName: string): Promise<{
+        success: boolean;
+        windows?: Array<{
+            index: string;
+            name: string;
+            active: boolean;
+        }>;
+        error?: string;
+    }>;
+    /**
+     * List panes in a window
+     */
+    listPanes(nodeId: string, sessionName: string, windowIndex?: string): Promise<{
+        success: boolean;
+        panes?: Array<{
+            index: string;
+            currentPath: string;
+            pid: string;
+            active: boolean;
+        }>;
+        error?: string;
+    }>;
+    /**
+     * Switch to a different window in a session
+     */
+    switchToWindow(nodeId: string, sessionName: string, windowIndex: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Switch to a different pane in a session
+     */
+    switchToPane(nodeId: string, sessionName: string, paneIndex: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Rename a window in a session
+     */
+    renameWindowInSession(nodeId: string, sessionName: string, windowIndex: string, newName: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Kill a pane in a session
+     */
+    killPaneInSession(nodeId: string, sessionName: string, paneIndex: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Cleanup old sessions on a node
+     */
+    cleanupOldSessions(nodeId: string, ageLimitMs?: number): Promise<{
+        success: boolean;
+        cleaned?: number;
+        errors?: string[];
+    }>;
+    /**
+     * Get resource usage for sessions on a node
+     */
+    getResourceUsage(nodeId: string): Promise<{
+        success: boolean;
+        usage?: {
+            totalSessions: number;
+            codespacesSessions: number;
+            estimatedMemoryMB: number;
+        };
+        error?: string;
+    }>;
+    /**
+     * Get summary statistics across all nodes
+     */
+    getSummary(): Promise<{
+        totalNodes: number;
+        activeNodes: number;
+        totalSessions: number;
+        totalMemoryUsageMB: number;
+        nodesWithSessions: number;
+    }>;
+}
+/**
+ * Get the global tmux session manager instance
+ */
+export declare function getTmuxManager(): TmuxSessionManager;
+/**
+ * Reset the global manager (for testing)
+ */
+export declare function resetTmuxManager(): void;