@ebowwa/terminal 0.3.4 → 0.3.6

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;

package/dist/tmux.d.ts

@@ -0,0 +1,212 @@
+/**
+ * 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, 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", command: string | null, 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, 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, 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, lines: number, 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 {};

package/dist/types.d.ts

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

package/package.json

@@ -1,57 +1,29 @@
 {
   "name": "@ebowwa/terminal",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Terminal session management with tmux integration, SSH client, WebSocket support, and MCP interface",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js",
-    "./mcp": "./dist/mcp/index.js",
-    "./client": "./dist/index.js"
+    ".": {
+    "types": "./dist/index.d.ts",
+    "default": "./dist/index.js"
   },
-  "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target bun --external 'node-ssh' --external 'hono' --external 'zod' --external 'node:*' && bun build src/mcp/index.ts --outdir dist/mcp --target bun --external 'node-ssh' --external 'hono' --external 'zod' --external 'node:*' --external '@modelcontextprotocol/*'",
-    "prepublishOnly": "bun run build"
-  },
-  "files": [
-    "dist"
-  ],
-  "keywords": [
-    "terminal",
-    "tmux",
-    "ssh",
-    "session",
-    "websocket",
-    "mcp",
-    "pty",
-    "cli",
-    "remote"
-  ],
-  "author": "Ebowwa Labs <labs@ebowwa.com>",
-  "license": "MIT",
-  "homepage": "https://github.com/ebowwa/terminal#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ebowwa/terminal.git",
-    "directory": "/"
-  },
-  "bugs": {
-    "url": "https://github.com/ebowwa/terminal/issues"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@ebowwa/codespaces-types": "^1.4.0",
-    "@ebowwa/ssh": "^0.2.1",
-    "node-ssh": "^13.2.1",
-    "hono": "^4.11.3",
-    "zod": "^3.24.1"
-  },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "@types/node-ssh": "^11.0.0",
-    "typescript": "^5.9.3"
-  }
+  "./mcp": {
+  "types": "./dist/mcp/index.d.ts",
+  "default": "./dist/mcp/index.js"
+},
+"./types": {
+"types": "./dist/types.d.ts",
+"default": "./dist/types.d.ts"
+}
+},
+"files": ["dist"],
+"keywords": ["terminal", "tmux", "ssh", "mcp"],
+"author": "Ebowwa Labs <labs@ebowwa.com>",
+"license": "MIT",
+"dependencies": {
+"zod": "^3.24.1"
+}
 }