@ebowwa/terminal 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,45 @@
+/**
+ * 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 { SSHError } from "./error.js";
+import { SSHOptionsSchema, SSHCommandSchema } from '@ebowwa/codespaces-types/runtime/ssh';
+import { getSSHPool } from './pool.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 async function execSSH(command, options) {
+    // Validate inputs with Zod
+    const validatedCommand = SSHCommandSchema.safeParse(command);
+    if (!validatedCommand.success) {
+        throw new Error(`Invalid SSH command: ${validatedCommand.error.issues.map(i => i.message).join(', ')}`);
+    }
+    const validatedOptions = SSHOptionsSchema.safeParse(options);
+    if (!validatedOptions.success) {
+        throw new Error(`Invalid SSH options: ${validatedOptions.error.issues.map(i => i.message).join(', ')}`);
+    }
+    const { host, user = "root", timeout = 5, port = 22, keyPath, password } = validatedOptions.data;
+    try {
+        // Get connection pool
+        const pool = getSSHPool();
+        // Execute command directly via SSH - the pool handles proper escaping
+        const output = await pool.exec(validatedCommand.data, {
+            host,
+            user,
+            timeout,
+            port,
+            keyPath,
+            password,
+        });
+        return output || "0";
+    }
+    catch (error) {
+        throw new SSHError(`SSH command failed: ${validatedCommand.data}`, error);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SSH error class
+ */
+export declare class SSHError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/error.js

@@ -0,0 +1,12 @@
+/**
+ * SSH error class
+ */
+export class SSHError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "SSHError";
+    }
+}
+//# sourceMappingURL=error.js.map

package/dist/exec.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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>;
+//# sourceMappingURL=exec.d.ts.map

package/dist/exec.js

@@ -0,0 +1,107 @@
+/**
+ * SSH command execution functions
+ */
+import { execSSH } from "./client.js";
+import { getSSHPool } from "./pool.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 async function execSSHParallel(commands, options) {
+    const entries = Object.entries(commands);
+    const pool = getSSHPool();
+    // Determine optimal number of connections (3-4 connections is a good balance)
+    // This avoids SSH channel limits while maintaining parallelism
+    const numCommands = entries.length;
+    const numConnections = Math.min(numCommands, 4); // Max 4 connections
+    // Get multiple connections from the pool
+    const connections = await pool.getConnections(options, numConnections);
+    // Distribute commands across connections (round-robin)
+    const connectionPromises = connections.map((ssh, connIndex) => {
+        // Assign commands to this connection
+        const assignedCommands = entries.filter((_, i) => i % numConnections === connIndex);
+        // Execute all assigned commands on this connection
+        return Promise.allSettled(assignedCommands.map(async ([key, cmd]) => {
+            try {
+                const result = await ssh.execCommand(cmd, {
+                    execOptions: {
+                        timeout: (options.timeout || 5) * 1000,
+                    },
+                });
+                // If we have stderr but no stdout, the command failed
+                if (result.stderr && !result.stdout) {
+                    throw new Error(result.stderr);
+                }
+                return [key, result.stdout.trim()];
+            }
+            catch (error) {
+                // Log the error with full details including cause
+                console.error(`[execSSHParallel] Command "${key}" failed:`, error instanceof Error ? error.message : error);
+                // Log the underlying cause if available
+                if (error instanceof Error && error.cause) {
+                    console.error(`[execSSHParallel] Command "${key}" cause:`, error.cause);
+                }
+                return [key, "0"]; // Fallback value
+            }
+        }));
+    });
+    // Wait for all connections to complete their assigned commands
+    const allSettledResults = await Promise.all(connectionPromises);
+    // Flatten results from all connections
+    const results = [];
+    for (const connResults of allSettledResults) {
+        for (const result of connResults) {
+            if (result.status === "fulfilled") {
+                results.push([...result.value]);
+            }
+            // Rejected promises are already logged and return "0" above
+        }
+    }
+    return Object.fromEntries(results);
+}
+/**
+ * Test SSH connection to a remote server
+ * @param options - SSH connection options
+ * @returns True if connection successful
+ */
+export async function testSSHConnection(options) {
+    try {
+        await execSSH('echo "connection_test"', options);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=exec.js.map

package/dist/files.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 | undefined, 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 {};
+//# sourceMappingURL=files.d.ts.map