@ebowwa/terminal 0.3.1 → 0.3.2

package/package.json

@@ -1,84 +1,22 @@
 {
   "name": "@ebowwa/terminal",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./sessions": {
-      "types": "./dist/sessions.d.ts",
-      "default": "./dist/sessions.js"
-    },
-    "./tmux": {
-      "types": "./dist/tmux.d.ts",
-      "default": "./dist/tmux.js"
-    },
-    "./manager": {
-      "types": "./dist/manager.d.ts",
-      "default": "./dist/manager.js"
-    },
-    "./types": {
-      "types": "./dist/types.d.ts",
-      "default": "./dist/types.js"
-    },
-    "./api": {
-      "types": "./dist/api.d.ts",
-      "default": "./dist/api.js"
-    },
-    "./config": {
-      "types": "./dist/config.d.ts",
-      "default": "./dist/config.js"
-    },
-    "./pool": {
-      "types": "./dist/pool.d.ts",
-      "default": "./dist/pool.js"
-    },
-    "./exec": {
-      "types": "./dist/exec.d.ts",
-      "default": "./dist/exec.js"
-    },
-    "./pty": {
-      "types": "./dist/pty.d.ts",
-      "default": "./dist/pty.js"
-    },
-    "./files": {
-      "types": "./dist/files.d.ts",
-      "default": "./dist/files.js"
-    },
-    "./scp": {
-      "types": "./dist/scp.d.ts",
-      "default": "./dist/scp.js"
-    },
-    "./fingerprint": {
-      "types": "./dist/fingerprint.d.ts",
-      "default": "./dist/fingerprint.js"
-    },
-    "./tmux-exec": {
-      "types": "./dist/tmux-exec.d.ts",
-      "default": "./dist/tmux-exec.js"
-    },
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "default": "./dist/client.js"
-    },
-    "./network-error-detector": {
-      "types": "./dist/network-error-detector.d.ts",
-      "default": "./dist/network-error-detector.js"
-    },
-    "./mcp": {
-      "types": "./dist/mcp/index.d.ts",
-      "default": "./dist/mcp/index.js"
-    }
+    ".": "./dist/index.js",
+    "./mcp": "./dist/mcp/index.js",
+    "./client": "./dist/index.js"
   },
   "scripts": {
     "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"
   },
+  "files": [
+    "dist"
+  ],
   "keywords": [
     "terminal",
     "tmux",
@@ -105,7 +43,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@ebowwa/codespaces-types": "^1.3.0",
+    "@ebowwa/codespaces-types": "^1.4.0",
     "@ebowwa/ssh": "^0.1.0",
     "node-ssh": "^13.2.1",
     "hono": "^4.11.3",

package/dist/api.d.ts

@@ -1,7 +0,0 @@
-/**
- * API routes for Multi-Node Tmux Session Manager
- * Provides REST API for managing tmux sessions across multiple VPS nodes
- */
-import { Hono } from "hono";
-declare const tmuxApi: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
-export { tmuxApi };

package/dist/client.d.ts

@@ -1,14 +0,0 @@
-/**
- * Core SSH client for executing commands on remote servers
- * Uses persistent connection pool for efficient reuse
- * Uses base64 encoding to avoid shell escaping issues
- */
-import type { SSHOptions } from "./types.js";
-/**
- * Execute a command on a remote server via SSH
- * Uses persistent connection pool for better performance
- * @param command - Shell command to execute
- * @param options - SSH connection options
- * @returns Command output as string
- */
-export declare function execSSH(command: string, options: SSHOptions): Promise<string>;

package/dist/config.d.ts

@@ -1,85 +0,0 @@
-/**
- * SSH Config Manager
- *
- * Manages ~/.ssh/config entries for easy node access.
- * When a node is created, adds an alias so you can:
- *   ssh node-<id>    or    ssh <name>
- * Instead of:
- *   ssh -i ~/.../key -o StrictHostKeyChecking=no root@167.235.236.8
- */
-export interface SSHConfigEntry {
-    id: string;
-    name: string;
-    host: string;
-    user?: string;
-    keyPath: string;
-    port?: number;
-}
-/**
- * Add or update an SSH config entry for a node
- */
-export declare function addSSHConfigEntry(entry: SSHConfigEntry): void;
-/**
- * Remove an SSH config entry for a node
- */
-export declare function removeSSHConfigEntry(id: string): void;
-/**
- * Update IP address for an existing node (e.g., after rebuild)
- */
-export declare function updateSSHConfigHost(id: string, newHost: string): void;
-/**
- * List all managed SSH config entries
- */
-export declare function listSSHConfigEntries(): SSHConfigEntry[];
-/**
- * Validate SSH connection works with the configured key
- * Returns true if connection succeeds, throws on failure with diagnostic info
- */
-export declare function validateSSHConnection(host: string, keyPath: string, user?: string, timeoutSeconds?: number): Promise<{
-    success: boolean;
-    error?: string;
-    diagnostics?: string;
-}>;
-/**
- * Ensure SSH key is loaded correctly and agent doesn't interfere
- * Clears wrong keys from agent and adds the correct one
- */
-export declare function ensureCorrectSSHKey(keyPath: string): Promise<void>;
-/**
- * Wait for SSH to become ready on a new server
- * Polls until connection succeeds or timeout
- */
-export declare function waitForSSHReady(host: string, keyPath: string, options?: {
-    user?: string;
-    maxAttempts?: number;
-    intervalMs?: number;
-    onAttempt?: (attempt: number, maxAttempts: number) => void;
-}): Promise<{
-    success: boolean;
-    attempts: number;
-    error?: string;
-}>;
-/**
- * Sync result for a single node
- */
-export interface SyncResult {
-    id: string;
-    name: string;
-    ip: string;
-    status: "added" | "updated" | "skipped" | "error";
-    error?: string;
-    sshReady?: boolean;
-}
-/**
- * Sync all existing Hetzner nodes to SSH config
- * Call this to add aliases for nodes created before this feature
- */
-export declare function syncNodesToSSHConfig(nodes: Array<{
-    id: string;
-    name: string;
-    ip: string;
-    keyPath: string;
-}>, options?: {
-    validateSSH?: boolean;
-    onProgress?: (result: SyncResult) => void;
-}): Promise<SyncResult[]>;

package/dist/error.d.ts

@@ -1,7 +0,0 @@
-/**
- * SSH error class
- */
-export declare class SSHError extends Error {
-    readonly cause?: unknown;
-    constructor(message: string, cause?: unknown);
-}

package/dist/exec.d.ts

@@ -1,46 +0,0 @@
-/**
- * SSH command execution functions
- */
-import type { SSHOptions } from "./types.js";
-/**
- * Execute multiple SSH commands in parallel using multiple connections
- *
- * DESIGN DECISION: Multiple Connections vs Single Connection
- * ===========================================================
- *
- * We use MULTIPLE SSH connections to avoid channel saturation issues.
- * SSH servers typically limit concurrent channels per connection (~10).
- * When executing 9+ commands in parallel, we can exceed this limit.
- *
- * Solution: Distribute commands across multiple pooled connections.
- * Each connection handles a subset of commands, staying within channel limits.
- *
- * DESIGN DECISION: Promise.allSettled() vs Promise.all()
- * ======================================================
- *
- * We use Promise.allSettled() instead of Promise.all() for a critical reason:
- * Resource monitoring should be RESILIENT. If one command fails (e.g., GPU
- * query on a CPU-only server), we still want results from all other commands.
- *
- * Example scenario:
- * - CPU, memory, disk commands: succeed
- * - GPU command: fails (no NVIDIA GPU)
- * - Network command: succeeds
- *
- * With Promise.all(): entire batch fails, no metrics collected
- * With Promise.allSettled(): we get 6/7 metrics, GPU returns "0" fallback
- *
- * ERROR HANDLING:
- * ==============
- * 1. Individual command failures are logged to console
- * 2. Failed commands return "0" as fallback (matches execSSH default)
- * 3. The function always completes successfully (never throws)
- * 4. Calling code can check for "0" values to detect failures
- */
-export declare function execSSHParallel(commands: Record<string, string>, options: SSHOptions): Promise<Record<string, string>>;
-/**
- * Test SSH connection to a remote server
- * @param options - SSH connection options
- * @returns True if connection successful
- */
-export declare function testSSHConnection(options: SSHOptions): Promise<boolean>;

package/dist/files.d.ts

@@ -1,123 +0,0 @@
-/**
- * Remote file operations via SSH
- */
-import type { SSHOptions } from "./types.js";
-import { SSHError } from "./error.js";
-/**
- * Path sanitization options
- */
-export interface SanitizePathOptions {
-    /**
-     * Allowed base directories (absolute paths)
-     * Default: ["/root"] for root user
-     */
-    allowedBaseDirs?: string[];
-    /**
-     * User context for determining default base directory
-     */
-    user?: string;
-    /**
-     * Whether to allow absolute paths
-     * Default: false (security best practice)
-     */
-    allowAbsolutePaths?: boolean;
-    /**
-     * Maximum path depth to prevent deep traversal attempts
-     * Default: 20
-     */
-    maxDepth?: number;
-    /**
-     * Log suspicious path attempts
-     * Default: true
-     */
-    logSuspicious?: boolean;
-}
-/**
- * Path traversal security error
- */
-export declare class PathTraversalError extends SSHError {
-    readonly attemptedPath: string;
-    readonly reason: string;
-    constructor(message: string, attemptedPath: string, reason: string);
-}
-/**
- * Security event log for path traversal attempts
- */
-interface SecurityEvent {
-    timestamp: string;
-    attemptedPath: string;
-    reason: string;
-    severity: "blocked" | "suspicious" | "warning";
-}
-/**
- * Get recent security events for monitoring
- */
-export declare function getSecurityEvents(limit?: number): SecurityEvent[];
-/**
- * Clear old security events (for maintenance)
- */
-export declare function clearSecurityEvents(olderThanMs?: number): number;
-/**
- * Sanitize and validate a file path for security
- *
- * This function prevents path traversal attacks by:
- * 1. Rejecting paths with .. components
- * 2. Validating against allowed base directories
- * 3. Normalizing paths to remove . and redundant /
- * 4. Checking for null bytes and other escape sequences
- * 5. Limiting path depth to prevent deep traversal
- *
- * @param inputPath - The user-provided path to sanitize
- * @param options - Sanitization options
- * @returns Sanitized absolute path
- * @throws PathTraversalError if path is suspicious or invalid
- *
- * @example
- * ```ts
- * // Safe: within /root
- * sanitizePath("project/file.txt", { user: "root" })
- * // Returns: "/root/project/file.txt"
- *
- * // BLOCKED: attempts to escape
- * sanitizePath("../../../etc/passwd", { user: "root" })
- * // Throws: PathTraversalError
- *
- * // BLOCKED: null byte injection
- * sanitizePath("file.txt\0../../../etc/passwd", { user: "root" })
- * // Throws: PathTraversalError
- * ```
- */
-export declare function sanitizePath(inputPath: string, options?: SanitizePathOptions): string;
-export type FileType = "file" | "directory";
-export interface RemoteFile {
-    name: string;
-    path: string;
-    size: string;
-    modified: string;
-    type: FileType;
-}
-export type PreviewType = "text" | "image" | "binary" | "error";
-export interface FilePreview {
-    type: PreviewType;
-    content?: string;
-    error?: string;
-}
-/**
- * List files in a directory on remote server
- * @param path - Directory path to list (default: .)
- * @param options - SSH connection options
- * @returns List of files with metadata
- * @throws PathTraversalError if path attempts to escape allowed directories
- * @throws SSHError if SSH command fails
- */
-export declare function listFiles(path: string, options: SSHOptions): Promise<RemoteFile[]>;
-/**
- * Preview a file's content from remote server
- * @param filePath - Path to the file to preview
- * @param options - SSH connection options
- * @returns File content for preview
- * @throws PathTraversalError if path attempts to escape allowed directories
- * @throws SSHError if SSH command fails
- */
-export declare function previewFile(filePath: string, options: SSHOptions): Promise<FilePreview>;
-export {};

package/dist/fingerprint.d.ts

@@ -1,66 +0,0 @@
-/**
- * SSH fingerprint utilities with validation and recovery
- */
-import type { SSHOptions } from "./types.js";
-/**
- * Get SSH fingerprint from remote server
- * @param options - SSH connection options
- * @returns SSH fingerprint or null
- */
-export declare function getSSHFingerprint(options: SSHOptions): Promise<string | null>;
-/**
- * Get SSH fingerprint from a local private key file
- * @param keyPath - Path to the private key file
- * @returns SSH fingerprint (SHA256 format) or null
- */
-export declare function getLocalKeyFingerprint(keyPath: string): Promise<string | null>;
-/**
- * Convert MD5 fingerprint format to SHA256 format (for comparison)
- * Hetzner returns MD5 like "29:cd:c1:c3:84:eb:ca:31:a4:1f:94:69:0c:84:b3:56"
- * We need to handle both formats
- */
-export declare function normalizeFingerprint(fingerprint: string): string;
-/**
- * Validate that a local SSH key matches what's on a remote server
- * @param host - Server hostname or IP
- * @param keyPath - Path to local private key
- * @returns Validation result
- */
-export declare function validateSSHKeyMatch(host: string, keyPath: string): Promise<{
-    valid: boolean;
-    localFingerprint?: string;
-    remoteFingerprint?: string;
-    error?: string;
-}>;
-/**
- * Check if we can SSH to a server with a given key
- * @param host - Server hostname or IP
- * @param keyPath - Path to SSH private key
- * @returns true if SSH works
- */
-export declare function testSSHKeyConnection(host: string, keyPath: string): Promise<boolean>;
-/**
- * SSH Key Mismatch Error with recovery suggestions
- */
-export declare class SSHKeyMismatchError extends Error {
-    host: string;
-    localFingerprint: string;
-    hetznerFingerprint: string;
-    keyPath: string;
-    constructor(host: string, localFingerprint: string, hetznerFingerprint: string, keyPath: string);
-}
-/**
- * Comprehensive SSH key validation for server creation
- * @param host - Server hostname or IP
- * @param keyPath - Path to local SSH key
- * @param hetznerKeyId - SSH key ID on Hetzner (for comparison)
- * @returns Validation result with recovery suggestions
- */
-export declare function validateSSHKeyForServer(host: string, keyPath: string, hetznerKeyId?: string): Promise<{
-    canConnect: boolean;
-    fingerprintMatch: boolean;
-    localFingerprint?: string;
-    remoteFingerprint?: string;
-    error?: string;
-    recovery?: string[];
-}>;

package/dist/index.d.ts

@@ -1,20 +0,0 @@
-/**
- * SSH utility library - modular entry point
- */
-export { TmuxSessionManager, getTmuxManager, resetTmuxManager, type Node, type TmuxSession, type DetailedTmuxSession, type BatchOperationResult, type CreateSessionOptions, type BatchCommandOptions, type SessionQueryOptions, } from "./tmux-manager.js";
-export type { SSHOptions, SCPOptions } from "./types.js";
-export { SSHError } from "./error.js";
-export { execSSH } from "./client.js";
-export { execSSHParallel, testSSHConnection } from "./exec.js";
-export { execViaTmux, execViaTmuxParallel } from "./tmux-exec.js";
-export { scpUpload, scpDownload } from "./scp.js";
-export { listFiles, previewFile, sanitizePath, PathTraversalError, getSecurityEvents, clearSecurityEvents, type FileType, type RemoteFile, type PreviewType, type FilePreview, type SanitizePathOptions, } from "./files.js";
-export { getSSHFingerprint, getLocalKeyFingerprint, normalizeFingerprint, validateSSHKeyMatch, testSSHKeyConnection, validateSSHKeyForServer, SSHKeyMismatchError } from "./fingerprint.js";
-export { createPTYSession, writeToPTY, setPTYSize, readFromPTY, closePTYSession, getPTYSession, getActivePTYSessions, } from "./pty.js";
-export { getSSHPool, closeGlobalSSHPool, getActiveSSHConnections, SSHConnectionPool, } from "./pool.js";
-export { closeSession, cleanupStaleSessions, getOrCreateSession, getSession, getAllSessions, getAllSessionInfo, getSessionInfo, getSessionCount, getSessionsByHost, attachWebSocket, writeToSession, resizeSession, detachWebSocket, } from "./sessions.js";
-export type { TerminalSession, SessionInfo } from "./sessions.js";
-export { generateSessionName, isTmuxInstalled, installTmux, ensureTmux, listTmuxSessions, hasTmuxSession, createOrAttachTmuxSession, killTmuxSession, getTmuxSessionInfo, cleanupOldTmuxSessions, getTmuxResourceUsage, sendCommandToPane, splitPane, listSessionWindows, listWindowPanes, capturePane, getPaneHistory, switchWindow, switchPane, renameWindow, killPane, getDetailedSessionInfo, } from "./tmux.js";
-export { generateLocalSessionName, isLocalTmuxInstalled, listLocalSessions, hasLocalSession, createLocalTmuxSSHSession, sendCommandToLocalSession, captureLocalPane, getLocalPaneHistory, killLocalSession, getLocalSessionInfo, listLocalSessionWindows, listLocalWindowPanes, splitLocalPane, cleanupOldLocalSessions, getLocalTmuxResourceUsage, waitForTextInPane, switchLocalWindow, switchLocalPane, renameLocalWindow, killLocalPane, getDetailedLocalSessionInfo, type LocalTmuxSessionOptions, type LocalTmuxSessionResult, } from "./tmux-local.js";
-export { RESOURCE_COMMANDS } from "./resources.js";
-export type { ResourceCommand } from "./resources.js";

package/dist/manager.d.ts

@@ -1,102 +0,0 @@
-/**
- * SSH Key Manager - Single Source of Truth
- *
- * Consolidates SSH key creation, upload, and management for Hetzner.
- * Replaces duplicate ensureSSHKey() functions in api.ts and crud.ts.
- *
- * FEATURES:
- * - Create or reuse local SSH key pairs
- * - Upload public key to Hetzner if not exists
- * - Handle fingerprint format conversion (SHA256 <-> MD5)
- * - Provide consistent API for all SSH key operations
- * - OS-specific user data directory for portable key storage
- *
- * ENVIRONMENT VARIABLES:
- * - HETZNER_SSH_KEYS_DIR: Override default SSH keys directory
- */
-import type { HetznerClient } from "../lib/hetzner/client";
-declare module "bun" {
-    interface Env {
-        HETZNER_SSH_KEYS_DIR?: string;
-    }
-}
-/**
- * Get OS-specific user data directory for SSH keys
- * - macOS: ~/Library/Application Support/com.hetzner.codespaces/ssh-keys/
- * - Linux: ~/.config/com.hetzner.codespaces/ssh-keys/
- * - Windows: %APPDATA%\com.hetzner.codespaces\ssh-keys\
- *
- * Can be overridden via .env file:
- *   HETZNER_SSH_KEYS_DIR=/custom/path
- */
-export declare function getDefaultKeysDir(): string;
-/**
- * SSH Key information returned by the manager
- */
-export interface SSHKeyInfo {
-    keyId: number;
-    keyPath: string;
-    fingerprint: string;
-    name: string;
-}
-/**
- * Configuration for SSH key manager
- */
-export interface SSHKeyManagerConfig {
-    keyName?: string;
-    keysDir?: string;
-}
-/**
- * Fingerprint format types
- */
-export type FingerprintFormat = "md5" | "sha256";
-/**
- * Convert SSH key fingerprint between formats
- * Hetzner uses MD5 with colons, modern tools use SHA256
- */
-export declare function convertFingerprintFormat(publicKeyPath: string, format: FingerprintFormat): Promise<string>;
-/**
- * SSH Key Manager - Main class for managing SSH keys
- */
-export declare class SSHKeyManager {
-    private keyName;
-    private keysDir;
-    constructor(config?: SSHKeyManagerConfig);
-    /**
-     * Get the absolute path to the SSH keys directory
-     */
-    private getKeysDirPath;
-    /**
-     * Get the full path to the SSH key files (absolute path)
-     */
-    private getKeyPath;
-    /**
-     * Ensure SSH key exists locally and on Hetzner
-     * This is the main entry point - replaces duplicate ensureSSHKey() functions
-     *
-     * @param hetznerClient - Hetzner API client
-     * @returns SSH key information for server creation
-     */
-    ensureSSHKey(hetznerClient: HetznerClient): Promise<SSHKeyInfo>;
-    /**
-     * Get local key fingerprint in SHA256 format
-     */
-    getLocalFingerprint(): Promise<string | null>;
-    /**
-     * Get local key fingerprint in MD5 format (for Hetzner comparison)
-     */
-    getHetznerFingerprint(): Promise<string>;
-    /**
-     * Get the key path
-     */
-    getKeyPathValue(): string;
-}
-/**
- * Convenience function - creates default manager and ensures SSH key
- * This is a drop-in replacement for the old ensureSSHKey() functions
- *
- * @param hetznerClient - Hetzner API client
- * @param config - Optional configuration
- * @returns SSH key information
- */
-export declare function ensureSSHKey(hetznerClient: HetznerClient, config?: SSHKeyManagerConfig): Promise<SSHKeyInfo>;

package/dist/mcp/index.d.ts

@@ -1,8 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Terminal MCP Server
- *
- * Exposes terminal session management via Model Context Protocol
- * Integrates with tmux, SSH, PTY, and file operations
- */
-export {};

package/dist/mcp/stdio.d.ts

@@ -1,8 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Terminal MCP Server (stdio protocol)
- *
- * Model Context Protocol server for terminal session management
- * Uses stdio transport for Claude Code integration
- */
-export {};

package/dist/network-error-detector.d.ts

@@ -1,18 +0,0 @@
-/**
- * Network Error Detection
- * Detects and provides helpful messages for common network issues
- */
-export interface NetworkErrorDetails {
-    type: "SERVER_NOT_READY" | "NETWORK_BLOCKED" | "AUTH_FAILED" | "UNKNOWN";
-    message: string;
-    troubleshooting: string[];
-    isLikelyNetworkBlock: boolean;
-}
-/**
- * Analyzes SSH connection error and provides detailed diagnosis
- */
-export declare function detectNetworkError(error: Error | string, host: string, serverStatus?: string): NetworkErrorDetails;
-/**
- * Format network error for WebSocket/UI display
- */
-export declare function formatNetworkError(diagnosis: NetworkErrorDetails): string;