godot-mcp-runtime 3.0.0 → 3.1.1

package/dist/utils/godot-runner.js

@@ -1,12 +1,12 @@
 import { fileURLToPath } from 'url';
-import { join, dirname, normalize } from 'path';
+import { join, dirname, normalize, resolve, sep } from 'path';
 import { existsSync } from 'fs';
 import { spawn } from 'child_process';
 import * as net from 'net';
 import { randomBytes } from 'crypto';
 import { BridgeManager } from './bridge-manager.js';
-import { encodeFrame, getBridgePort, parseFrames } from './bridge-protocol.js';
-import { logDebug, logError } from './logger.js';
+import { DEFAULT_BRIDGE_PORT, encodeFrame, findFreePort, parseFrames, FRAME_HEADER_BYTES, MAX_FRAME_BYTES, } from './bridge-protocol.js';
+import { logDebug, logError, DEBUG_MODE } from './logger.js';
 /**
  * Thrown when the bridge socket closes (Godot exited, port closed, or peer
  * dropped the connection mid-flight). Lets callers distinguish
@@ -21,7 +21,6 @@ export class BridgeDisconnectedError extends Error {
 // Derive __filename and __dirname in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const DEBUG_MODE = process.env.DEBUG === 'true';
 // Bridge readiness polling
 export const BRIDGE_WAIT_SPAWNED_TIMEOUT_MS = 8000;
 const BRIDGE_WAIT_SPAWNED_INTERVAL_MS = 300;
@@ -31,6 +30,7 @@ const BRIDGE_PING_TIMEOUT_MS = 1000;
 const BRIDGE_SHUTDOWN_SPAWNED_TIMEOUT_MS = 500;
 const BRIDGE_SHUTDOWN_ATTACHED_TIMEOUT_MS = 1500;
 const BRIDGE_PROCESS_EXIT_TIMEOUT_MS = 2000;
+const BRIDGE_RECONNECT_DELAY_MS = 1000;
 /**
  * Normalize a path for cross-platform comparison.
  * Folds Windows backslashes to forward slashes and strips trailing slashes,
@@ -117,15 +117,22 @@ export function cleanStdout(stdout) {
     return cleanOutput(stdout);
 }
 // Parameter mappings between snake_case and camelCase
+// Add new entries whenever a tool surfaces a new compound parameter — the
+// strict converter throws in test env on unmapped keys to catch oversights.
 const parameterMappings = {
     project_path: 'projectPath',
     scene_path: 'scenePath',
     root_node_type: 'rootNodeType',
     parent_node_path: 'parentNodePath',
+    parent_path: 'parentPath',
     node_type: 'nodeType',
     node_name: 'nodeName',
     texture_path: 'texturePath',
     node_path: 'nodePath',
+    node_paths: 'nodePaths',
+    target_node_path: 'targetNodePath',
+    target_parent_path: 'targetParentPath',
+    new_name: 'newName',
     output_path: 'outputPath',
     mesh_item_names: 'meshItemNames',
     new_path: 'newPath',
@@ -134,6 +141,13 @@ const parameterMappings = {
     response_mode: 'responseMode',
     preview_max_width: 'previewMaxWidth',
     preview_max_height: 'previewMaxHeight',
+    bridge_port: 'bridgePort',
+    abort_on_error: 'abortOnError',
+    max_depth: 'maxDepth',
+    changed_only: 'changedOnly',
+    case_sensitive: 'caseSensitive',
+    file_types: 'fileTypes',
+    max_results: 'maxResults',
 };
 // Reverse mapping from camelCase to snake_case
 const reverseParameterMappings = {};
@@ -162,29 +176,101 @@ export function normalizeParameters(params) {
     }
     return result;
 }
+function convertCamelToSnakeValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => convertCamelToSnakeValue(entry));
+    }
+    if (typeof value === 'object' && value !== null) {
+        return convertCamelToSnakeCase(value);
+    }
+    return value;
+}
 export function convertCamelToSnakeCase(params) {
     const result = {};
+    const isTestEnv = process.env.NODE_ENV === 'test' || process.env.VITEST === 'true';
     for (const key in params) {
         if (Object.prototype.hasOwnProperty.call(params, key)) {
-            const snakeKey = reverseParameterMappings[key] ||
-                key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
-            const value = params[key];
-            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                result[snakeKey] = convertCamelToSnakeCase(value);
+            const mapped = reverseParameterMappings[key];
+            let snakeKey;
+            if (mapped) {
+                snakeKey = mapped;
+            }
+            else if (/[A-Z]/.test(key)) {
+                // Unmapped camelCase key — tolerated in production via regex fallback,
+                // but in tests we throw to catch missing entries in parameterMappings.
+                if (isTestEnv) {
+                    throw new Error(`convertCamelToSnakeCase: unmapped camelCase key '${key}'. ` +
+                        `Add it to parameterMappings in src/utils/godot-runner.ts so snake/camel conversion stays explicit.`);
+                }
+                snakeKey = key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
             }
             else {
-                result[snakeKey] = value;
+                snakeKey = key;
             }
+            result[snakeKey] = convertCamelToSnakeValue(params[key]);
         }
     }
     return result;
 }
+/**
+ * Check whether a display server (X11 / Wayland) is available on the current
+ * platform.  On macOS and Windows the display subsystem is always present;
+ * on Linux we probe the standard environment variables.
+ */
+export function checkDisplayAvailable() {
+    if (process.platform !== 'linux')
+        return true;
+    return !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+}
 export function validatePath(path) {
     if (!path || path.includes('..')) {
         return false;
     }
     return true;
 }
+/**
+ * Stricter check for paths that must stay inside `projectPath`. Rejects `..`
+ * (via `validatePath`) and absolute paths that escape the project root.
+ * `path.join('/project', '/etc/passwd')` resolves to `/etc/passwd`, so the
+ * basic `..`-substring check alone permits absolute-path traversal.
+ *
+ * Tolerates a leading `res://` (Godot's project-root URI) by stripping it
+ * before resolving — autoload entries and resource paths use this prefix.
+ */
+export function validateSubPath(projectPath, userPath) {
+    if (!validatePath(userPath))
+        return false;
+    const stripped = userPath.startsWith('res://') ? userPath.slice('res://'.length) : userPath;
+    if (!stripped)
+        return false;
+    const projectRoot = resolve(projectPath);
+    const resolved = resolve(projectRoot, stripped);
+    const tail = projectRoot === sep ? sep : projectRoot + sep;
+    return resolved === projectRoot || resolved.startsWith(tail);
+}
+/**
+ * Validate a Godot scene-tree path (NodePath). Scene-tree paths are a
+ * separate namespace from filesystem paths — they address nodes inside
+ * a scene, not files on disk, so the project-root containment check
+ * in `validateSubPath` does not apply.
+ *
+ * Rejects empty strings and `..` segments. Accepts both relative
+ * (`root/Player`) and absolute (`/root/Player`) Godot forms; the
+ * codebase convention is the relative form.
+ */
+export function validateNodePath(path) {
+    return typeof path === 'string' && path.length > 0 && !path.includes('..');
+}
+/**
+ * True when `child` resolves to `parent` or a path beneath it. Used by
+ * defense-in-depth checks on bridge-returned paths (e.g. screenshot files
+ * that must live under `.mcp/screenshots/`).
+ */
+export function isUnderDir(parent, child) {
+    const parentResolved = resolve(parent);
+    const childResolved = resolve(child);
+    return childResolved === parentResolved || childResolved.startsWith(parentResolved + sep);
+}
 /**
  * Return `error.message` when `error` is an `Error`, otherwise `'Unknown error'`.
  * Centralizes the catch-block boilerplate so handlers can build error responses
@@ -259,9 +345,9 @@ export function validateSceneArgs(args, opts) {
         }
         return { projectPath: projectResult.projectPath, scenePath: '' };
     }
-    if (!validatePath(args.scenePath)) {
+    if (!validateSubPath(projectResult.projectPath, args.scenePath)) {
         return createErrorResponse('Invalid scene path', [
-            'Provide a valid path without ".." or other potentially unsafe characters',
+            'Provide a valid relative path without ".." that stays inside the project directory',
         ]);
     }
     if (sceneRequired) {
@@ -275,6 +361,26 @@ export function validateSceneArgs(args, opts) {
     }
     return { projectPath: projectResult.projectPath, scenePath: args.scenePath };
 }
+/**
+ * Read the first `n` bytes from a chunk array without concatenating the
+ * entire array. If the first chunk already has enough bytes, returns a
+ * zero-copy subarray; otherwise copies just `n` bytes into a fresh buffer.
+ * Caller must ensure total length across chunks is >= n.
+ */
+function readBytesFromChunks(chunks, n) {
+    if (chunks[0].length >= n)
+        return chunks[0].subarray(0, n);
+    const result = Buffer.allocUnsafe(n);
+    let copied = 0;
+    for (const c of chunks) {
+        const take = Math.min(c.length, n - copied);
+        c.copy(result, copied, 0, take);
+        copied += take;
+        if (copied >= n)
+            break;
+    }
+    return result;
+}
 export class GodotRunner {
     godotPath = null;
     operationsScriptPath;
@@ -284,8 +390,14 @@ export class GodotRunner {
     activeProcess = null;
     activeProjectPath = null;
     activeSessionMode = null;
+    activeBridgePort = null;
     socket = null;
-    rxBuffer = Buffer.alloc(0);
+    // Receive buffer kept as an array of chunks until at least one complete frame
+    // is available. Avoids re-copying accumulated bytes on every TCP data event
+    // (the old `Buffer.concat([rxBuffer, chunk])` pattern was O(n²) on large
+    // frames split across many chunks).
+    rxChunks = [];
+    rxTotal = 0;
     inFlight = null;
     constructor(config) {
         this.operationsScriptPath = join(__dirname, '..', 'scripts', 'godot_operations.gd');
@@ -370,8 +482,17 @@ export class GodotRunner {
         }
     }
     async detectGodotPath() {
-        if (this.godotPath && (await this.isValidGodotPath(this.godotPath))) {
-            logDebug(`Using existing Godot path: ${this.godotPath}`);
+        // Explicit paths (constructor config or GODOT_PATH) are authoritative — leave
+        // godotPath null on failure rather than fabricating a platform default, so
+        // callers can produce actionable errors.
+        if (this.godotPath) {
+            if (await this.isValidGodotPath(this.godotPath)) {
+                logDebug(`Using existing Godot path: ${this.godotPath}`);
+                return;
+            }
+            logError(`Configured Godot path "${this.godotPath}" is not a working Godot executable. ` +
+                `Pass a valid Godot 4.x binary via the godotPath config option.`);
+            this.godotPath = null;
             return;
         }
         if (process.env.GODOT_PATH) {
@@ -382,6 +503,9 @@ export class GodotRunner {
                 logDebug(`Using Godot path from environment: ${this.godotPath}`);
                 return;
             }
+            logError(`GODOT_PATH is set to "${normalizedPath}" but no working Godot executable was found there. ` +
+                `Update GODOT_PATH to your Godot 4.x binary or unset it to auto-detect.`);
+            return;
         }
         const osPlatform = process.platform;
         logDebug(`Auto-detecting Godot path for platform: ${osPlatform}`);
@@ -403,22 +527,20 @@ export class GodotRunner {
             logDebug(`Found Godot at: ${winner.path}`);
             return;
         }
-        logDebug(`Warning: Could not find Godot in common locations for ${osPlatform}`);
-        logError(`Could not find Godot in common locations for ${osPlatform}`);
-        if (osPlatform === 'win32') {
-            this.godotPath = normalize('C:\\Program Files\\Godot\\Godot.exe');
-        }
-        else if (osPlatform === 'darwin') {
-            this.godotPath = normalize('/Applications/Godot.app/Contents/MacOS/Godot');
-        }
-        else {
-            this.godotPath = normalize('/usr/bin/godot');
-        }
-        logDebug(`Using default path: ${this.godotPath}, but this may not work.`);
+        logError(`Could not find Godot in common locations for ${osPlatform}. ` +
+            `Set GODOT_PATH to your Godot 4.x executable.`);
     }
     getGodotPath() {
         return this.godotPath;
     }
+    /**
+     * Read the port currently baked into the project's bridge script. Returns
+     * null if the file is missing or malformed. Thin pass-through to
+     * BridgeManager — used by bridge-wait-timeout race detection.
+     */
+    readBakedBridgePort(projectPath) {
+        return this.bridge.readBakedPort(projectPath);
+    }
     async getVersion() {
         if (this.cachedVersion !== null) {
             return this.cachedVersion;
@@ -484,13 +606,13 @@ export class GodotRunner {
     }
     launchEditor(projectPath) {
         if (!this.godotPath) {
-            throw new Error('Godot path not set. Call detectGodotPath first.');
+            throw new Error('No Godot executable resolved. Set GODOT_PATH to a Godot 4.x binary, or pass godotPath via config.');
         }
         return spawn(this.godotPath, ['-e', '--path', projectPath], { stdio: 'pipe' });
     }
-    runProject(projectPath, scene, background = false) {
+    async runProject(projectPath, scene, background = false, bridgePort) {
         if (!this.godotPath) {
-            throw new Error('Godot path not set. Call detectGodotPath first.');
+            throw new Error('No Godot executable resolved. Set GODOT_PATH to a Godot 4.x binary, or pass godotPath via config.');
         }
         if (this.activeSessionMode === 'spawned' && this.activeProcess) {
             logDebug('Killing existing Godot process before starting a new one');
@@ -506,8 +628,14 @@ export class GodotRunner {
             this.closeConnection();
             this.bridge.cleanup(this.activeProjectPath);
         }
+        if (!checkDisplayAvailable()) {
+            throw new Error('No display server available (DISPLAY and WAYLAND_DISPLAY are both unset). ' +
+                'Godot requires a display to run a project window.');
+        }
+        const port = bridgePort ?? (await findFreePort());
+        this.activeBridgePort = port;
         try {
-            this.bridge.inject(projectPath);
+            this.bridge.inject(projectPath, port);
         }
         catch (err) {
             logDebug(`Non-fatal: Failed to inject bridge autoload: ${err}`);
@@ -515,15 +643,19 @@ export class GodotRunner {
         this.activeProjectPath = projectPath;
         this.activeSessionMode = 'spawned';
         const cmdArgs = ['--path', projectPath];
-        if (scene && validatePath(scene)) {
+        if (scene && validateSubPath(projectPath, scene)) {
             logDebug(`Adding scene parameter: ${scene}`);
             cmdArgs.push(scene);
         }
-        logDebug(`Running Godot project: ${projectPath}`);
+        const portSource = bridgePort !== undefined ? 'explicit' : 'auto';
+        logDebug(`Running Godot project: ${projectPath} (bridge port ${port}, ${portSource})`);
         const sessionToken = randomBytes(16).toString('hex');
         const spawnOptions = {
             stdio: 'pipe',
-            env: { ...process.env, MCP_SESSION_TOKEN: sessionToken },
+            env: {
+                ...process.env,
+                MCP_SESSION_TOKEN: sessionToken,
+            },
         };
         if (background) {
             spawnOptions.env = { ...spawnOptions.env, MCP_BACKGROUND: '1' };
@@ -545,12 +677,10 @@ export class GodotRunner {
             output.push(...lines);
             if (output.length > 500)
                 output.splice(0, output.length - 500);
-            if (DEBUG_MODE) {
-                lines.forEach((line) => {
-                    if (line.trim())
-                        logDebug(`[Godot stdout] ${line}`);
-                });
-            }
+            lines.forEach((line) => {
+                if (line.trim())
+                    logDebug(`[Godot stdout] ${line}`);
+            });
         });
         proc.stderr?.on('data', (data) => {
             const lines = data.toString().split('\n');
@@ -558,12 +688,10 @@ export class GodotRunner {
             errors.push(...lines);
             if (errors.length > 500)
                 errors.splice(0, errors.length - 500);
-            if (DEBUG_MODE) {
-                lines.forEach((line) => {
-                    if (line.trim())
-                        logDebug(`[Godot stderr] ${line}`);
-                });
-            }
+            lines.forEach((line) => {
+                if (line.trim())
+                    logDebug(`[Godot stderr] ${line}`);
+            });
         });
         proc.on('exit', (code) => {
             logDebug(`Godot process exited with code ${code}`);
@@ -579,7 +707,7 @@ export class GodotRunner {
         this.activeProcess = godotProcess;
         return this.activeProcess;
     }
-    async attachProject(projectPath) {
+    async attachProject(projectPath, bridgePort) {
         if (this.activeSessionMode === 'spawned' && this.activeProcess) {
             await this.stopProject();
         }
@@ -599,7 +727,11 @@ export class GodotRunner {
             this.activeProjectPath = null;
             this.activeSessionMode = null;
         }
-        this.bridge.inject(projectPath);
+        const port = bridgePort ?? (await findFreePort());
+        this.activeBridgePort = port;
+        this.bridge.inject(projectPath, port);
+        const portSource = bridgePort !== undefined ? 'explicit' : 'auto';
+        logDebug(`Attaching to Godot project: ${projectPath} (bridge port ${port}, ${portSource})`);
         this.activeProjectPath = projectPath;
         this.activeSessionMode = 'attached';
         this.activeProcess = null;
@@ -625,6 +757,7 @@ export class GodotRunner {
             }
             this.activeProjectPath = null;
             this.activeSessionMode = null;
+            this.activeBridgePort = null;
             this.activeProcess = null;
             return {
                 mode: 'attached',
@@ -677,6 +810,7 @@ export class GodotRunner {
             this.activeProjectPath = null;
         }
         this.activeSessionMode = null;
+        this.activeBridgePort = null;
         return result;
     }
     hasActiveRuntimeSession() {
@@ -727,7 +861,7 @@ export class GodotRunner {
                     sock.removeAllListeners();
                     sock.destroy();
                 }
-                this.rxBuffer = Buffer.alloc(0);
+                this.resetRxBuffer();
                 settle(new Error(`Command '${command}' timed out after ${timeoutMs}ms. Is the game running?`));
             }, timeoutMs);
             this.inFlight = { command, resolve, reject, timer };
@@ -736,18 +870,47 @@ export class GodotRunner {
                     cb();
                     return;
                 }
-                const port = getBridgePort();
+                // Fallback to DEFAULT_BRIDGE_PORT is defensive — every entry point
+                // (runProject, attachProject) sets activeBridgePort before sendCommand
+                // can be reached, so this branch is not expected in practice.
+                const port = this.activeBridgePort ?? DEFAULT_BRIDGE_PORT;
                 const sock = net.connect(port, '127.0.0.1');
                 const onConnect = () => {
                     sock.setNoDelay(true);
                     sock.removeListener('error', onConnectError);
                     this.socket = sock;
-                    this.rxBuffer = Buffer.alloc(0);
+                    this.resetRxBuffer();
                     sock.on('data', (chunk) => {
-                        this.rxBuffer = Buffer.concat([this.rxBuffer, chunk]);
+                        this.rxChunks.push(chunk);
+                        this.rxTotal += chunk.length;
+                        // Defer the (potentially expensive) concat until we know at least
+                        // one complete frame is ready. Peek the 4-byte header without
+                        // copying all accumulated chunks first.
+                        if (this.rxTotal < FRAME_HEADER_BYTES)
+                            return;
+                        const header = readBytesFromChunks(this.rxChunks, FRAME_HEADER_BYTES);
+                        const firstLen = header.readUInt32BE(0);
+                        if (firstLen > MAX_FRAME_BYTES) {
+                            this.socket = null;
+                            sock.destroy();
+                            settle(new BridgeDisconnectedError(`Bridge frame header advertises ${firstLen} bytes, exceeds limit ${MAX_FRAME_BYTES}`));
+                            return;
+                        }
+                        if (this.rxTotal < FRAME_HEADER_BYTES + firstLen)
+                            return;
                         try {
-                            const { frames, remainder } = parseFrames(this.rxBuffer);
-                            this.rxBuffer = remainder;
+                            const buffer = this.rxChunks.length === 1
+                                ? this.rxChunks[0]
+                                : Buffer.concat(this.rxChunks, this.rxTotal);
+                            const { frames, remainder } = parseFrames(buffer);
+                            if (remainder.length === 0) {
+                                this.rxChunks = [];
+                                this.rxTotal = 0;
+                            }
+                            else {
+                                this.rxChunks = [remainder];
+                                this.rxTotal = remainder.length;
+                            }
                             for (const frame of frames) {
                                 settle(null, frame.toString('utf8'));
                             }
@@ -814,7 +977,11 @@ export class GodotRunner {
             sock.removeAllListeners();
             sock.destroy();
         }
-        this.rxBuffer = Buffer.alloc(0);
+        this.resetRxBuffer();
+    }
+    resetRxBuffer() {
+        this.rxChunks = [];
+        this.rxTotal = 0;
     }
     getErrorCount() {
         return this.activeProcess?.totalErrorsWritten ?? 0;
@@ -832,12 +999,28 @@ export class GodotRunner {
     // Only the explicit `SCRIPT ERROR:` / `USER SCRIPT ERROR:` markers belong here — the looser
     // `GDScript error` substring also matches user printerr output and produces false positives.
     static SCRIPT_ERROR_PATTERNS = ['SCRIPT ERROR:', 'USER SCRIPT ERROR:'];
+    static RETRYABLE_BRIDGE_COMMANDS = new Set(['get_ui_elements', 'screenshot']);
     extractRuntimeErrors(lines) {
         return lines.filter((line) => GodotRunner.SCRIPT_ERROR_PATTERNS.some((p) => line.includes(p)));
     }
+    async sendCommandWithReconnect(command, params = {}, timeoutMs = 10000) {
+        try {
+            return await this.sendCommand(command, params, timeoutMs);
+        }
+        catch (err) {
+            if (err instanceof BridgeDisconnectedError &&
+                this.activeSessionMode &&
+                GodotRunner.RETRYABLE_BRIDGE_COMMANDS.has(command)) {
+                this.closeConnection();
+                await new Promise((r) => setTimeout(r, BRIDGE_RECONNECT_DELAY_MS));
+                return this.sendCommand(command, params, timeoutMs);
+            }
+            throw err;
+        }
+    }
     async sendCommandWithErrors(command, params = {}, timeoutMs = 10000) {
         const marker = this.getErrorCount();
-        const response = await this.sendCommand(command, params, timeoutMs);
+        const response = await this.sendCommandWithReconnect(command, params, timeoutMs);
         const newErrors = this.getErrorsSince(marker);
         const runtimeErrors = this.activeSessionMode === 'spawned' ? this.extractRuntimeErrors(newErrors) : [];
         return { response, runtimeErrors };