@hcu-lab.me/mcp-device 1.0.0

package/dist/terminal-manager.js

@@ -0,0 +1,635 @@
+import { spawn } from 'child_process';
+import path from 'path';
+import { DEFAULT_COMMAND_TIMEOUT } from './config.js';
+import { configManager } from './config-manager.js';
+import { capture } from "./utils/capture.js";
+import { analyzeProcessState } from './utils/process-detection.js';
+/**
+ * Standard Windows PATHEXT value, used to repair a corrupted PATHEXT before
+ * spawning child shells.
+ *
+ * On some Windows Claude Desktop / DXT launches the server process inherits a
+ * broken PATHEXT (observed as ".CPL" only). Because we build the child env from
+ * { ...process.env }, that broken value would propagate into every spawned
+ * shell, stripping ".EXE" and breaking resolution of git / node / python / rg /
+ * etc. (and even full-path .exe invocations under PowerShell). See issue #481.
+ */
+const STANDARD_PATHEXT = '.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC';
+/**
+ * Return a healthy PATHEXT for spawned Windows shells.
+ * - Unset           -> use the standard list.
+ * - Missing ".EXE"  -> corrupted; merge the standard list with whatever was
+ *                      present (preserves any extra extensions, order-stable).
+ * - Otherwise       -> leave the inherited value untouched.
+ */
+function getRepairedPathExt() {
+    const current = process.env.PATHEXT;
+    if (!current)
+        return STANDARD_PATHEXT;
+    const exts = current.split(';').map(e => e.trim().toUpperCase()).filter(Boolean);
+    if (!exts.includes('.EXE')) {
+        return [...new Set([...STANDARD_PATHEXT.split(';'), ...exts])].join(';');
+    }
+    return current;
+}
+/**
+ * Output buffering caps. Without a cap, a process emitting enough output makes
+ * string concatenation throw "RangeError: Invalid string length" at V8's max
+ * string size (~536M chars) inside a stdout 'data' handler — an uncaught
+ * exception that kills the whole server (index.ts exits on uncaughtException).
+ * The cap also bounds the join() cost in snapshot reads and the periodic
+ * process-state scan, both of which are O(total output).
+ */
+export const MAX_BUFFERED_OUTPUT_CHARS = 50 * 1024 * 1024; // per session; oldest lines evicted first
+const MAX_LINE_CHARS = 1024 * 1024; // force-split longer lines so eviction can work
+const MAX_WAIT_OUTPUT_CHARS = 2 * 1024 * 1024; // start_process wait buffer (prompt/state detection)
+/**
+ * Get the appropriate spawn configuration for a given shell
+ * This handles login shell flags for different shell types
+ */
+function getShellSpawnArgs(shellPath, command) {
+    const shellName = path.basename(shellPath).toLowerCase();
+    // Unix shells with login flag support
+    if (shellName.includes('bash') || shellName.includes('zsh')) {
+        return {
+            executable: shellPath,
+            args: ['-l', '-c', command],
+            useShellOption: false
+        };
+    }
+    // PowerShell Core (cross-platform, supports -Login)
+    if (shellName === 'pwsh' || shellName === 'pwsh.exe') {
+        return {
+            executable: shellPath,
+            args: ['-Login', '-Command', command],
+            useShellOption: false
+        };
+    }
+    // Windows PowerShell 5.1 (no login flag support)
+    if (shellName === 'powershell' || shellName === 'powershell.exe') {
+        return {
+            executable: shellPath,
+            args: ['-NoProfile', '-NonInteractive', '-Command', command],
+            useShellOption: false
+        };
+    }
+    // CMD
+    if (shellName === 'cmd' || shellName === 'cmd.exe') {
+        return {
+            executable: shellPath,
+            args: ['/c', command],
+            windowsVerbatim: true,
+            useShellOption: false
+        };
+    }
+    // Fish shell (uses -l for login, -c for command)
+    if (shellName.includes('fish')) {
+        return {
+            executable: shellPath,
+            args: ['-l', '-c', command],
+            useShellOption: false
+        };
+    }
+    // Unknown/other shells - use shell option for safety
+    // This provides a fallback for shells we don't explicitly handle
+    return {
+        executable: command,
+        args: [],
+        useShellOption: shellPath
+    };
+}
+export class TerminalManager {
+    constructor() {
+        this.sessions = new Map();
+        this.completedSessions = new Map();
+    }
+    /**
+     * Send input to a running process
+     * @param pid Process ID
+     * @param input Text to send to the process
+     * @returns Whether input was successfully sent
+     */
+    sendInputToProcess(pid, input) {
+        const session = this.sessions.get(pid);
+        if (!session) {
+            return false;
+        }
+        try {
+            if (session.process.stdin && !session.process.stdin.destroyed) {
+                // Ensure input ends with a newline for most REPLs
+                const inputWithNewline = input.endsWith('\n') ? input : input + '\n';
+                session.process.stdin.write(inputWithNewline);
+                return true;
+            }
+            return false;
+        }
+        catch (error) {
+            console.error(`Error sending input to process ${pid}:`, error);
+            return false;
+        }
+    }
+    async executeCommand(command, timeoutMs = DEFAULT_COMMAND_TIMEOUT, shell, collectTiming = false, workingDirectory) {
+        // Get the shell from config if not specified
+        let shellToUse = shell;
+        if (!shellToUse) {
+            try {
+                const config = await configManager.getConfig();
+                shellToUse = config.defaultShell || true;
+            }
+            catch (error) {
+                // If there's an error getting the config, fall back to default
+                shellToUse = true;
+            }
+        }
+        // For REPL interactions, we need to ensure stdin, stdout, and stderr are properly configured
+        // Note: No special stdio options needed here, Node.js handles pipes by default
+        // Enhance SSH commands automatically
+        let enhancedCommand = command;
+        if (command.trim().startsWith('ssh ') && !command.includes(' -t')) {
+            enhancedCommand = command.replace(/^ssh /, 'ssh -t ');
+            console.log(`Enhanced SSH command: ${enhancedCommand}`);
+        }
+        // Get the appropriate spawn configuration for the shell
+        let spawnConfig;
+        let spawnOptions;
+        if (typeof shellToUse === 'string') {
+            // Use shell-specific configuration with login flags where appropriate
+            spawnConfig = getShellSpawnArgs(shellToUse, enhancedCommand);
+            spawnOptions = {
+                env: {
+                    ...process.env,
+                    TERM: 'xterm-256color' // Better terminal compatibility
+                },
+                windowsHide: true, // Prevent visible console windows on Windows
+                ...(workingDirectory ? { cwd: workingDirectory } : {})
+            };
+            // Add shell option if needed (for unknown shells)
+            if (spawnConfig.useShellOption) {
+                spawnOptions.shell = spawnConfig.useShellOption;
+            }
+        }
+        else {
+            // Boolean or undefined shell - use default shell option behavior
+            spawnConfig = {
+                executable: enhancedCommand,
+                args: [],
+                useShellOption: shellToUse
+            };
+            spawnOptions = {
+                shell: shellToUse,
+                env: {
+                    ...process.env,
+                    TERM: 'xterm-256color'
+                },
+                windowsHide: true, // Prevent visible console windows on Windows
+                ...(workingDirectory ? { cwd: workingDirectory } : {})
+            };
+        }
+        // Repair PATHEXT on Windows before spawning. On some Windows DXT launches
+        // the server process inherits a corrupted PATHEXT (e.g. ".CPL"), which we
+        // would otherwise propagate via { ...process.env } and break command
+        // resolution (git, node, python, rg, ...) in the spawned shell. See #481.
+        if (process.platform === 'win32' && spawnOptions.env) {
+            spawnOptions.env.PATHEXT = getRepairedPathExt();
+        }
+        // On Windows, when we invoke cmd.exe directly and pass the user's command as a
+        // single argument, Node/libuv applies MSVCRT-style quoting that escapes embedded
+        // double quotes as \" . cmd.exe does not understand that escaping, so any command
+        // containing quotes (e.g. a quoted path with spaces like "C:\Program Files\app.exe")
+        // is corrupted before the shell ever parses it. Passing arguments verbatim lets
+        // cmd handle its own quoting. Scoped to shells that set windowsVerbatim (cmd only)
+        // because PowerShell/pwsh have different quote rules and must NOT use verbatim.
+        if (process.platform === 'win32' && spawnConfig.windowsVerbatim) {
+            spawnOptions.windowsVerbatimArguments = true;
+        }
+        // Spawn the process with appropriate arguments
+        const childProcess = spawn(spawnConfig.executable, spawnConfig.args, spawnOptions);
+        let output = '';
+        // Ensure childProcess.pid is defined before proceeding
+        if (!childProcess.pid) {
+            // Return a consistent error object instead of throwing
+            return {
+                pid: -1, // Use -1 to indicate an error state
+                output: 'Error: Failed to get process ID. The command could not be executed.',
+                isBlocked: false
+            };
+        }
+        const session = {
+            pid: childProcess.pid,
+            process: childProcess,
+            outputLines: [], // Line-based buffer
+            lastReadIndex: 0, // Track where "new" output starts
+            isBlocked: false,
+            startTime: new Date(),
+            bufferedChars: 0,
+            evictedLines: 0,
+            evictedChars: 0
+        };
+        this.sessions.set(childProcess.pid, session);
+        // Timing telemetry
+        const startTime = Date.now();
+        let firstOutputTime;
+        let lastOutputTime;
+        const outputEvents = [];
+        let exitReason = 'timeout';
+        return new Promise((resolve) => {
+            let resolved = false;
+            let periodicCheck = null;
+            // Quick prompt patterns for immediate detection
+            const quickPromptPatterns = />>>\s*$|>\s*$|\$\s*$|#\s*$/;
+            const resolveOnce = (result) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                if (periodicCheck)
+                    clearInterval(periodicCheck);
+                // Add timing info if requested
+                if (collectTiming) {
+                    const endTime = Date.now();
+                    result.timingInfo = {
+                        startTime,
+                        endTime,
+                        totalDurationMs: endTime - startTime,
+                        exitReason,
+                        firstOutputTime,
+                        lastOutputTime,
+                        timeToFirstOutputMs: firstOutputTime ? firstOutputTime - startTime : undefined,
+                        outputEvents: outputEvents.length > 0 ? outputEvents : undefined
+                    };
+                }
+                resolve(result);
+            };
+            childProcess.stdout.on('data', (data) => {
+                const text = data.toString();
+                const now = Date.now();
+                if (!firstOutputTime)
+                    firstOutputTime = now;
+                lastOutputTime = now;
+                // `output` only feeds the wait-phase result and prompt/state detection,
+                // so stop growing it once resolved and keep only a bounded tail.
+                if (!resolved) {
+                    output += text;
+                    if (output.length > MAX_WAIT_OUTPUT_CHARS) {
+                        output = output.slice(-Math.floor(MAX_WAIT_OUTPUT_CHARS / 2));
+                    }
+                }
+                // Append to line-based buffer
+                this.appendToLineBuffer(session, text);
+                // Record output event if collecting timing
+                if (collectTiming) {
+                    outputEvents.push({
+                        timestamp: now,
+                        deltaMs: now - startTime,
+                        source: 'stdout',
+                        length: text.length,
+                        snippet: text.slice(0, 50).replace(/\n/g, '\\n')
+                    });
+                }
+                // Immediate check for obvious prompts
+                if (quickPromptPatterns.test(text)) {
+                    session.isBlocked = true;
+                    exitReason = 'early_exit_quick_pattern';
+                    if (collectTiming && outputEvents.length > 0) {
+                        outputEvents[outputEvents.length - 1].matchedPattern = 'quick_pattern';
+                    }
+                    resolveOnce({
+                        pid: childProcess.pid,
+                        output,
+                        isBlocked: true
+                    });
+                }
+            });
+            childProcess.stderr.on('data', (data) => {
+                const text = data.toString();
+                const now = Date.now();
+                if (!firstOutputTime)
+                    firstOutputTime = now;
+                lastOutputTime = now;
+                if (!resolved) {
+                    output += text;
+                    if (output.length > MAX_WAIT_OUTPUT_CHARS) {
+                        output = output.slice(-Math.floor(MAX_WAIT_OUTPUT_CHARS / 2));
+                    }
+                }
+                // Append to line-based buffer
+                this.appendToLineBuffer(session, text);
+                // Record output event if collecting timing
+                if (collectTiming) {
+                    outputEvents.push({
+                        timestamp: now,
+                        deltaMs: now - startTime,
+                        source: 'stderr',
+                        length: text.length,
+                        snippet: text.slice(0, 50).replace(/\n/g, '\\n')
+                    });
+                }
+            });
+            // Periodic comprehensive check every 100ms
+            periodicCheck = setInterval(() => {
+                if (output.trim()) {
+                    const processState = analyzeProcessState(output, childProcess.pid);
+                    if (processState.isWaitingForInput) {
+                        session.isBlocked = true;
+                        exitReason = 'early_exit_periodic_check';
+                        resolveOnce({
+                            pid: childProcess.pid,
+                            output,
+                            isBlocked: true
+                        });
+                    }
+                }
+            }, 100);
+            // Timeout fallback
+            setTimeout(() => {
+                session.isBlocked = true;
+                exitReason = 'timeout';
+                resolveOnce({
+                    pid: childProcess.pid,
+                    output,
+                    isBlocked: true
+                });
+            }, timeoutMs);
+            childProcess.on('exit', (code) => {
+                if (childProcess.pid) {
+                    // Store completed session before removing active session
+                    this.completedSessions.set(childProcess.pid, {
+                        pid: childProcess.pid,
+                        outputLines: [...session.outputLines], // Copy line buffer
+                        exitCode: code,
+                        startTime: session.startTime,
+                        endTime: new Date(),
+                        evictedLines: session.evictedLines,
+                        evictedChars: session.evictedChars
+                    });
+                    // Keep only last 100 completed sessions
+                    if (this.completedSessions.size > 100) {
+                        const oldestKey = Array.from(this.completedSessions.keys())[0];
+                        this.completedSessions.delete(oldestKey);
+                    }
+                    this.sessions.delete(childProcess.pid);
+                }
+                exitReason = 'process_exit';
+                resolveOnce({
+                    pid: childProcess.pid,
+                    output,
+                    isBlocked: false
+                });
+            });
+        });
+    }
+    /**
+     * Append text to a session's line buffer
+     * Handles partial lines and newline splitting
+     */
+    appendToLineBuffer(session, text) {
+        if (!text)
+            return;
+        // Split text into lines, keeping track of whether text ends with newline
+        const lines = text.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const isLastFragment = i === lines.length - 1;
+            const endsWithNewline = text.endsWith('\n');
+            if (session.outputLines.length === 0) {
+                // First line ever
+                session.outputLines.push(line);
+            }
+            else if (i === 0) {
+                // First fragment - append to last line (might be partial)
+                session.outputLines[session.outputLines.length - 1] += line;
+            }
+            else {
+                // Subsequent lines - add as new lines
+                session.outputLines.push(line);
+            }
+        }
+        // Appended text contributes exactly its length to the joined buffer
+        // (its newlines become the join separators).
+        session.bufferedChars += text.length;
+        // A process printing without newlines grows a single line forever, which
+        // eviction can't bound — force-split so no line exceeds MAX_LINE_CHARS.
+        // Each inserted break adds one separator to the joined length.
+        let lastIndex = session.outputLines.length - 1;
+        while (session.outputLines[lastIndex].length > MAX_LINE_CHARS) {
+            const overlong = session.outputLines[lastIndex];
+            session.outputLines[lastIndex] = overlong.slice(0, MAX_LINE_CHARS);
+            session.outputLines.push(overlong.slice(MAX_LINE_CHARS));
+            session.bufferedChars += 1;
+            lastIndex++;
+        }
+        // Enforce the per-session cap by evicting the oldest lines. Keeps the
+        // buffer far below V8's max string length so concatenation and join()
+        // can never throw "Invalid string length" and kill the server.
+        while (session.bufferedChars > MAX_BUFFERED_OUTPUT_CHARS && session.outputLines.length > 1) {
+            const dropped = session.outputLines.shift();
+            const droppedJoinedChars = dropped.length + 1; // +1 for its join separator
+            session.bufferedChars -= droppedJoinedChars;
+            session.evictedChars += droppedJoinedChars;
+            session.evictedLines++;
+            if (session.lastReadIndex > 0)
+                session.lastReadIndex--;
+        }
+    }
+    /**
+     * Read process output with pagination (like file reading)
+     * @param pid Process ID
+     * @param offset Line offset: 0=from lastReadIndex, positive=absolute, negative=tail
+     * @param length Max lines to return
+     * @param updateReadIndex Whether to update lastReadIndex (default: true for offset=0)
+     */
+    readOutputPaginated(pid, offset = 0, length = 1000) {
+        // First check active sessions
+        const session = this.sessions.get(pid);
+        if (session) {
+            const result = this.readFromLineBuffer(session.outputLines, offset, length, session.lastReadIndex, (newIndex) => { session.lastReadIndex = newIndex; }, false, undefined);
+            result.evictedLines = session.evictedLines;
+            return result;
+        }
+        // Then check completed sessions
+        const completedSession = this.completedSessions.get(pid);
+        if (completedSession) {
+            const runtimeMs = completedSession.endTime.getTime() - completedSession.startTime.getTime();
+            const result = this.readFromLineBuffer(completedSession.outputLines, offset, length, 0, // Completed sessions don't track read position
+            () => { }, // No-op for completed sessions
+            true, completedSession.exitCode, runtimeMs);
+            result.evictedLines = completedSession.evictedLines;
+            return result;
+        }
+        return null;
+    }
+    /**
+     * Internal helper to read from a line buffer with offset/length
+     */
+    readFromLineBuffer(lines, offset, length, lastReadIndex, updateLastRead, isComplete, exitCode, runtimeMs) {
+        const totalLines = lines.length;
+        let startIndex;
+        let linesToRead;
+        if (offset < 0) {
+            // Negative offset = start position from end, then read 'length' lines forward
+            // e.g., offset=-50, length=10 means: start 50 lines from end, read 10 lines
+            const fromEnd = Math.abs(offset);
+            startIndex = Math.max(0, totalLines - fromEnd);
+            linesToRead = lines.slice(startIndex, startIndex + length);
+            // Don't update lastReadIndex for tail reads
+        }
+        else if (offset === 0) {
+            // offset=0 means "from where I last read" (like getNewOutput)
+            startIndex = lastReadIndex;
+            linesToRead = lines.slice(startIndex, startIndex + length);
+            // Update lastReadIndex for "new output" behavior
+            updateLastRead(Math.min(startIndex + linesToRead.length, totalLines));
+        }
+        else {
+            // Positive offset = absolute position
+            startIndex = offset;
+            linesToRead = lines.slice(startIndex, startIndex + length);
+            // Don't update lastReadIndex for absolute position reads
+        }
+        const readCount = linesToRead.length;
+        const endIndex = startIndex + readCount;
+        const remaining = Math.max(0, totalLines - endIndex);
+        return {
+            lines: linesToRead,
+            totalLines,
+            readFrom: startIndex,
+            readCount,
+            remaining,
+            isComplete,
+            exitCode,
+            runtimeMs
+        };
+    }
+    /**
+     * Get total line count for a process
+     */
+    getOutputLineCount(pid) {
+        const session = this.sessions.get(pid);
+        if (session) {
+            return session.outputLines.length;
+        }
+        const completedSession = this.completedSessions.get(pid);
+        if (completedSession) {
+            return completedSession.outputLines.length;
+        }
+        return null;
+    }
+    /**
+     * Legacy method for backward compatibility
+     * Returns all new output since last read
+     * @param maxLines Maximum lines to return (default: 1000 for context protection)
+     * @deprecated Use readOutputPaginated instead
+     */
+    getNewOutput(pid, maxLines = 1000) {
+        const result = this.readOutputPaginated(pid, 0, maxLines);
+        if (!result)
+            return null;
+        const output = result.lines.join('\n').trim();
+        // For completed sessions, append completion info with runtime
+        if (result.isComplete) {
+            const runtimeStr = result.runtimeMs !== undefined
+                ? `\nRuntime: ${(result.runtimeMs / 1000).toFixed(2)}s`
+                : '';
+            if (output) {
+                return `${output}\n\nProcess completed with exit code ${result.exitCode}${runtimeStr}`;
+            }
+            else {
+                return `Process completed with exit code ${result.exitCode}${runtimeStr}\n(No output produced)`;
+            }
+        }
+        // Add truncation warning if there's more output
+        if (result.remaining > 0) {
+            return `${output}\n\n[Output truncated: ${result.remaining} more lines available. Use read_process_output with offset/length for full output.]`;
+        }
+        return output || null;
+    }
+    /**
+     * Capture a snapshot of current output state for interaction tracking.
+     * Used by interactWithProcess to know what output existed before sending input.
+     */
+    captureOutputSnapshot(pid) {
+        const session = this.sessions.get(pid);
+        if (session) {
+            const fullOutput = session.outputLines.join('\n');
+            return {
+                // Absolute since process start (includes evicted output), so the
+                // offset stays valid even if the cap evicts lines between
+                // snapshot and read.
+                totalChars: session.evictedChars + fullOutput.length,
+                lineCount: session.evictedLines + session.outputLines.length
+            };
+        }
+        return null;
+    }
+    /**
+     * Get output that appeared since a snapshot was taken.
+     * This handles the case where output is appended to the last line (REPL prompts).
+     * Also checks completed sessions in case process finished between snapshot and poll.
+     */
+    getOutputSinceSnapshot(pid, snapshot) {
+        // Check active session first
+        const session = this.sessions.get(pid);
+        if (session) {
+            return TerminalManager.outputSinceSnapshot(session.outputLines, session.evictedChars, snapshot.totalChars);
+        }
+        // Fallback to completed sessions - process may have finished between snapshot and poll
+        const completedSession = this.completedSessions.get(pid);
+        if (completedSession) {
+            return TerminalManager.outputSinceSnapshot(completedSession.outputLines, completedSession.evictedChars, snapshot.totalChars);
+        }
+        return null;
+    }
+    /**
+     * New output since a snapshot, in absolute (since process start) offsets.
+     * If eviction dropped part of the unseen output, returns what the buffer
+     * still holds — the oldest unseen chars are lost to the cap.
+     */
+    static outputSinceSnapshot(outputLines, evictedChars, snapshotTotalChars) {
+        const fullOutput = outputLines.join('\n');
+        const newChars = evictedChars + fullOutput.length - snapshotTotalChars;
+        if (newChars <= 0) {
+            return ''; // No new output
+        }
+        return fullOutput.substring(Math.max(0, fullOutput.length - newChars));
+    }
+    /**
+   * Get a session by PID
+   * @param pid Process ID
+   * @returns The session or undefined if not found
+   */
+    getSession(pid) {
+        return this.sessions.get(pid);
+    }
+    forceTerminate(pid) {
+        const session = this.sessions.get(pid);
+        if (!session) {
+            return false;
+        }
+        try {
+            session.process.kill('SIGINT');
+            setTimeout(() => {
+                if (this.sessions.has(pid)) {
+                    session.process.kill('SIGKILL');
+                }
+            }, 1000);
+            return true;
+        }
+        catch (error) {
+            // Convert error to string, handling both Error objects and other types
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            capture('server_request_error', { error: errorMessage, message: `Failed to terminate process ${pid}:` });
+            return false;
+        }
+    }
+    listActiveSessions() {
+        const now = new Date();
+        return Array.from(this.sessions.values()).map(session => ({
+            pid: session.pid,
+            isBlocked: session.isBlocked,
+            runtime: now.getTime() - session.startTime.getTime()
+        }));
+    }
+    listCompletedSessions() {
+        return Array.from(this.completedSessions.values());
+    }
+}
+export const terminalManager = new TerminalManager();