@ebowwa/terminal 0.2.1 → 0.3.1

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/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ebowwa/terminal-mcp",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Terminal session management MCP server with SSH, tmux, and file operations",
   "type": "module",
   "main": "stdio.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ebowwa/terminal",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Terminal session management with tmux integration, SSH client, WebSocket support, and MCP interface",
   "type": "module",
   "main": "./dist/index.js",
@@ -76,10 +76,8 @@
     }
   },
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target node && bun build src/mcp/index.ts --outdir dist/mcp --target node",
-    "mcp": "bun run src/mcp/index.ts",
-    "mcp-dev": "MCP_PORT=8913 bun run src/mcp/index.ts",
-    "mcp-stdio": "bun run src/mcp/stdio.ts"
+    "build": "bun build src/index.ts --outdir dist --target bun --external '@ebowwa/*' --external 'node-ssh' --external 'hono' --external 'zod' && bun build src/mcp/index.ts --outdir dist/mcp --target bun --external '@ebowwa/*' --external 'node-ssh' --external 'hono' --external 'zod' --external '@modelcontextprotocol/*'",
+    "prepublishOnly": "bun run build"
   },
   "keywords": [
     "terminal",
@@ -107,13 +105,15 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@ebowwa/codespaces-types": "^1.1.0",
+    "@ebowwa/codespaces-types": "^1.3.0",
+    "@ebowwa/ssh": "^0.1.0",
     "node-ssh": "^13.2.1",
     "hono": "^4.11.3",
     "zod": "^3.24.1"
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@types/node-ssh": "^11.0.0"
+    "@types/node-ssh": "^11.0.0",
+    "typescript": "^5.9.3"
   }
 }

package/src/mcp/stdio.js

@@ -51,7 +51,7 @@ var __asyncValues = (this && this.__asyncValues) || function (o) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 // Re-export terminal functions
-var index_js_1 = require("../index.js");
+var terminal_1 = require("@ebowwa/terminal");
 // ==============
 // Tool Implementations
 //=============
@@ -59,7 +59,7 @@ function listSessionsTool() {
     return __awaiter(this, void 0, void 0, function () {
         var sessions, lines, _i, sessions_1, session, active;
         return __generator(this, function (_a) {
-            sessions = (0, index_js_1.getAllSessionInfo)();
+            sessions = (0, terminal_1.getAllSessionInfo)();
             lines = [
                 "🖥️  Active Terminal Sessions",
                 "=".repeat(50),
@@ -90,7 +90,7 @@ function getSessionInfoTool(sessionId) {
             switch (_a.label) {
                 case 0:
                     _a.trys.push([0, 2, , 3]);
-                    return [4 /*yield*/, (0, index_js_1.getSessionInfo)(sessionId)];
+                    return [4 /*yield*/, (0, terminal_1.getSessionInfo)(sessionId)];
                 case 1:
                     info = _a.sent();
                     lines = [
@@ -105,7 +105,7 @@ function getSessionInfoTool(sessionId) {
                     if (info.lastActivity) {
                         lines.push("Last activity: ".concat(new Date(info.lastActivity).toLocaleString()));
                     }
-                    session = (0, index_js_1.getSession)(sessionId);
+                    session = (0, terminal_1.getSession)(sessionId);
                     if (session) {
                         lines.push("");
                         lines.push("PTY session: ".concat(session.ptyId || "N/A"));
@@ -128,7 +128,7 @@ function createSessionTool(host_1) {
             switch (_a.label) {
                 case 0:
                     _a.trys.push([0, 2, , 3]);
-                    return [4 /*yield*/, (0, index_js_1.getOrCreateSession)(host, {
+                    return [4 /*yield*/, (0, terminal_1.getOrCreateSession)(host, {
                             type: type,
                             command: command,
                         })];
@@ -150,11 +150,11 @@ function writeCommandTool(sessionId, command) {
             switch (_a.label) {
                 case 0:
                     _a.trys.push([0, 2, , 3]);
-                    session = (0, index_js_1.getSession)(sessionId);
+                    session = (0, terminal_1.getSession)(sessionId);
                     if (!session) {
                         throw new Error("Session ".concat(sessionId, " not found"));
                     }
-                    return [4 /*yield*/, (0, index_js_1.writeToSession)(sessionId, command)];
+                    return [4 /*yield*/, (0, terminal_1.writeToSession)(sessionId, command)];
                 case 1:
                     _a.sent();
                     return [2 /*return*/, "\u2713 Command sent to session ".concat(sessionId)];
@@ -173,7 +173,7 @@ function resizeSessionTool(sessionId, rows, cols) {
             switch (_a.label) {
                 case 0:
                     _a.trys.push([0, 2, , 3]);
-                    return [4 /*yield*/, (0, index_js_1.resizeSession)(sessionId, rows, cols)];
+                    return [4 /*yield*/, (0, terminal_1.resizeSession)(sessionId, rows, cols)];
                 case 1:
                     _a.sent();
                     return [2 /*return*/, "\u2713 Resized session ".concat(sessionId, " to ").concat(rows, "x").concat(cols)];
@@ -192,7 +192,7 @@ function closeSessionTool(sessionId) {
             switch (_a.label) {
                 case 0:
                     _a.trys.push([0, 2, , 3]);
-                    return [4 /*yield*/, (0, index_js_1.closeSession)(sessionId)];
+                    return [4 /*yield*/, (0, terminal_1.closeSession)(sessionId)];
                 case 1:
                     _a.sent();
                     return [2 /*return*/, "\u2713 Closed session ".concat(sessionId)];
@@ -211,7 +211,7 @@ function execSSHTool(host, command, options) {
             switch (_a.label) {
                 case 0:
                     _a.trys.push([0, 2, , 3]);
-                    return [4 /*yield*/, (0, index_js_1.execSSH)(host, command, options)];
+                    return [4 /*yield*/, (0, terminal_1.execSSH)(host, command, options)];
                 case 1:
                     result = _a.sent();
                     return [2 /*return*/, result.stdout || result.stderr || "Command executed"];
@@ -230,7 +230,7 @@ function testConnectionTool(host) {
             switch (_a.label) {
                 case 0:
                     _a.trys.push([0, 2, , 3]);
-                    return [4 /*yield*/, (0, index_js_1.testSSHConnection)(host)];
+                    return [4 /*yield*/, (0, terminal_1.testSSHConnection)(host)];
                 case 1:
                     result = _a.sent();
                     if (result.success) {
@@ -255,10 +255,10 @@ function listTmuxSessionsTool() {
             switch (_a.label) {
                 case 0:
                     _a.trys.push([0, 3, , 4]);
-                    return [4 /*yield*/, (0, index_js_1.ensureTmux)()];
+                    return [4 /*yield*/, (0, terminal_1.ensureTmux)()];
                 case 1:
                     _a.sent();
-                    return [4 /*yield*/, (0, index_js_1.listTmuxSessions)()];
+                    return [4 /*yield*/, (0, terminal_1.listTmuxSessions)()];
                 case 2:
                     sessions = _a.sent();
                     lines = [
@@ -295,7 +295,7 @@ function listFilesTool(host_1) {
             switch (_a.label) {
                 case 0:
                     _a.trys.push([0, 2, , 3]);
-                    return [4 /*yield*/, (0, index_js_1.listFiles)(host, path)];
+                    return [4 /*yield*/, (0, terminal_1.listFiles)(host, path)];
                 case 1:
                     files = _a.sent();
                     lines = [
@@ -325,7 +325,7 @@ function uploadFileTool(host, localPath, remotePath) {
             switch (_a.label) {
                 case 0:
                     _a.trys.push([0, 2, , 3]);
-                    return [4 /*yield*/, (0, index_js_1.scpUpload)(host, { localPath: localPath, remotePath: remotePath })];
+                    return [4 /*yield*/, (0, terminal_1.scpUpload)(host, { localPath: localPath, remotePath: remotePath })];
                 case 1:
                     _a.sent();
                     return [2 /*return*/, "\u2713 Uploaded ".concat(localPath, " to ").concat(host, ":").concat(remotePath)];
@@ -344,7 +344,7 @@ function downloadFileTool(host, remotePath, localPath) {
             switch (_a.label) {
                 case 0:
                     _a.trys.push([0, 2, , 3]);
-                    return [4 /*yield*/, (0, index_js_1.scpDownload)(host, { remotePath: remotePath, localPath: localPath })];
+                    return [4 /*yield*/, (0, terminal_1.scpDownload)(host, { remotePath: remotePath, localPath: localPath })];
                 case 1:
                     _a.sent();
                     return [2 /*return*/, "\u2713 Downloaded ".concat(host, ":").concat(remotePath, " to ").concat(localPath)];
@@ -361,7 +361,7 @@ function getActiveConnectionsTool() {
         var connections, lines, _i, connections_1, conn;
         return __generator(this, function (_a) {
             try {
-                connections = (0, index_js_1.getActiveSSHConnections)();
+                connections = (0, terminal_1.getActiveSSHConnections)();
                 lines = [
                     "🔗 Active SSH Connections",
                     "=".repeat(50),
@@ -642,7 +642,7 @@ function handleToolCall(name, args) {
                 case 12: return [2 /*return*/, _b.sent()];
                 case 13: return [4 /*yield*/, execSSHTool(args.host, args.command, args.options)];
                 case 14: return [2 /*return*/, _b.sent()];
-                case 15: return [4 /*yield*/, testConnection(args.host)];
+                case 15: return [4 /*yield*/, testConnectionTool(args.host)];
                 case 16: return [2 /*return*/, _b.sent()];
                 case 17: return [4 /*yield*/, listTmuxSessionsTool()];
                 case 18: return [2 /*return*/, _b.sent()];

package/src/tmux.js

@@ -84,7 +84,7 @@ exports.renameWindow = renameWindow;
 exports.killPane = killPane;
 exports.getDetailedSessionInfo = getDetailedSessionInfo;
 var pool_js_1 = require("./pool.js");
-var ssh_1 = require("@codespaces/ssh");
+var flags_1 = require("@ebowwa/ssh/flags");
 var DEFAULT_CONFIG = {
     sessionPrefix: "codespaces",
     defaultShell: "/bin/bash",
@@ -273,14 +273,14 @@ function createOrAttachTmuxSession(host_1) {
                     return [4 /*yield*/, hasTmuxSession(sessionName, sshOptions)];
                 case 2:
                     sessionExists = _b.sent();
-                    flags = __spreadArray(__spreadArray([], ssh_1.SSHPresets.default, true), [
-                        ssh_1.SSHFlags.port(22),
-                        ssh_1.SSHFlags.forceTTY(2), // -tt for forced PTY
+                    flags = __spreadArray(__spreadArray([], flags_1.SSHPresets.default, true), [
+                        flags_1.SSHFlags.port(22),
+                        flags_1.SSHFlags.forceTTY(2), // -tt for forced PTY
                     ], false);
                     if (keyPath) {
-                        flags.push(ssh_1.SSHFlags.identity(String(keyPath)));
+                        flags.push(flags_1.SSHFlags.identity(String(keyPath)));
                     }
-                    sshArgs = (0, ssh_1.buildSSHArgs)(flags, host, user);
+                    sshArgs = (0, flags_1.buildSSHArgs)(flags, host, user);
                     tmuxCmd = [
                         "tmux",
                         "new-session",

package/src/tmux.ts

@@ -6,7 +6,7 @@
 
 import { getSSHPool } from "./pool.js";
 import type { SSHOptions } from "./types.js";
-import { SSHFlags, SSHPresets, buildSSHArgs, sshConfig, type PTYOptions, type SSHConfigFlag } from "@codespaces/ssh";
+import { SSHFlags, SSHPresets, buildSSHArgs, sshConfig, type PTYOptions, type SSHConfigFlag } from "@ebowwa/ssh/flags";
 
 /**
  * tmux session configuration

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "declaration": true,
+    "declarationDir": "./dist",
+    "emitDeclarationOnly": true,
+    "strict": false,
+    "skipLibCheck": true,
+    "noImplicitAny": false,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": false
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "src/**/*.js",
+    "src/mcp"
+  ]
+}