@beremaran/godot-agent-loop 1.0.0

package/build/tool-handlers/project-tool-handlers.js

@@ -0,0 +1,1506 @@
+import { join, dirname, basename } from 'path';
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { normalizeParameters, validatePath, createErrorResponse, errorMessage, isGodot44OrLater, generateGodotProjectFeatures, generateCsprojContent, generateCsharpScriptSource, toDotnetIdentifier, isValidCsharpIdentifier, PathSecurity, } from '../utils.js';
+import { GODOT_VERSION_OPTIONS } from '../godot-subprocess.js';
+import { ProjectConfigurationService, ProjectExportService, ProjectFileIOService, ImportPipelineService, ProjectIntegrityService, ExportReadinessService, DotnetWorkflowService, AddonManagementService, ProjectTestService, SceneOperationService, ScriptValidationService, } from './project-handler-services.js';
+const execFileAsync = promisify(execFile);
+const CI_EXPORT_PLATFORMS = new Set(['windows', 'linux', 'macos', 'web']);
+const DOCKER_BASE_IMAGES = new Set(['ubuntu:22.04', 'ubuntu:24.04']);
+const GODOT_EXPORT_VERSION = /^4\.\d+(?:\.\d+)?(?:-stable)?$/;
+const EXPORT_PRESET_NAME = /^[A-Za-z0-9][A-Za-z0-9 _./-]{0,127}$/;
+const INPUT_EVENT_KEY_PREFIX = 'Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0';
+const INPUT_EVENT_KEY_SUFFIX = ',"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)';
+/** Merge one physical key into an existing one-line project.godot input entry. */
+export function mergeInputMapAction(content, actionName, deadzone, physicalKeycode) {
+    const escapedName = actionName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const inputSection = /(^|\n)\[input\][^\n]*(?:\n|$)([\s\S]*?)(?=\n\[[^\n]+\](?:\n|$)|$)/.exec(content);
+    const newEvent = physicalKeycode === undefined
+        ? ''
+        : `${INPUT_EVENT_KEY_PREFIX},"physical_keycode":${physicalKeycode}${INPUT_EVENT_KEY_SUFFIX}`;
+    if (inputSection) {
+        const sectionBody = inputSection[2];
+        const actionPattern = new RegExp(`^${escapedName}\\s*=\\s*(\\{[^\\r\\n]*\\})[ \\t]*$`, 'm');
+        const existing = actionPattern.exec(sectionBody);
+        if (existing) {
+            const block = existing[1];
+            const existingDeadzone = /"deadzone"\s*:\s*([\d.eE+-]+)/.exec(block)?.[1] ?? String(deadzone);
+            const existingEvents = /"events"\s*:\s*\[([\s\S]*?)\]\s*(?:,|\})/.exec(block)?.[1] ?? '';
+            const duplicate = physicalKeycode !== undefined
+                && new RegExp(`"physical_keycode"\\s*:\\s*${physicalKeycode}\\b`).test(existingEvents);
+            if (!newEvent || duplicate) {
+                return { content, existed: true, eventAdded: false };
+            }
+            const mergedEvents = newEvent && !duplicate
+                ? (existingEvents.trim() ? `${existingEvents}, ${newEvent}` : newEvent)
+                : existingEvents;
+            const replacement = mergedEvents.trim()
+                ? `${actionName}={"deadzone": ${existingDeadzone}, "events": [${mergedEvents}]}`
+                : `${actionName}={"deadzone": ${existingDeadzone}}`;
+            const updatedBody = sectionBody.replace(actionPattern, replacement);
+            const bodyStart = inputSection.index + inputSection[0].indexOf(sectionBody);
+            return {
+                content: `${content.slice(0, bodyStart)}${updatedBody}${content.slice(bodyStart + sectionBody.length)}`,
+                existed: true,
+                eventAdded: Boolean(newEvent) && !duplicate,
+            };
+        }
+    }
+    const events = newEvent ? `, "events": [${newEvent}]` : '';
+    const inputLine = `${actionName}={"deadzone": ${deadzone}${events}}`;
+    const updated = content.includes('[input]')
+        ? content.replace('[input]', `[input]\n\n${inputLine}`)
+        : `${content}\n[input]\n\n${inputLine}\n`;
+    return { content: updated, existed: false, eventAdded: Boolean(newEvent) };
+}
+function validateGodotExportVersion(version) {
+    if (typeof version !== 'string' || !GODOT_EXPORT_VERSION.test(version)) {
+        return 'godotVersion must be a supported Godot 4 version such as "4.3-stable".';
+    }
+    return null;
+}
+/** Implements project, scene, file, script, and export tools. */
+export class ProjectToolHandlers {
+    context;
+    fileIO;
+    configuration;
+    scriptValidation;
+    exportService;
+    sceneOperations;
+    projectTests;
+    importPipeline;
+    projectIntegrity;
+    exportReadiness;
+    dotnetWorkflow;
+    addonManagement;
+    constructor(context) {
+        const pathSecurity = context.pathSecurity ?? new PathSecurity();
+        this.context = {
+            ...context,
+            pathSecurity,
+            getGodotPath: () => context.executable.path,
+            detectGodotPath: async () => { await context.executable.detect(); },
+            executeOperation: (operation, params, projectPath) => context.operations.execute(operation, params, projectPath),
+            headlessOp: (operation, args, argsFn) => {
+                const { projectPath, params } = argsFn(args);
+                return context.operations.run(operation, projectPath, params);
+            },
+        };
+        const serviceContext = {
+            executable: context.executable,
+            operations: context.operations,
+            pathSecurity,
+            projectSupport: context.projectSupport,
+        };
+        this.fileIO = new ProjectFileIOService(serviceContext);
+        this.configuration = new ProjectConfigurationService(serviceContext);
+        this.scriptValidation = new ScriptValidationService(serviceContext);
+        this.exportService = new ProjectExportService(serviceContext);
+        this.sceneOperations = new SceneOperationService(serviceContext);
+        this.projectTests = new ProjectTestService(serviceContext);
+        this.importPipeline = new ImportPipelineService(serviceContext);
+        this.projectIntegrity = new ProjectIntegrityService(serviceContext);
+        this.exportReadiness = new ExportReadinessService(serviceContext);
+        this.dotnetWorkflow = new DotnetWorkflowService(serviceContext);
+        this.addonManagement = new AddonManagementService(serviceContext);
+    }
+    projectRelativePath(projectPath, relativePath) {
+        const resolved = this.context.pathSecurity.resolveProjectPath(projectPath, relativePath);
+        if (!resolved)
+            throw new Error(`Path is outside the project: ${relativePath}`);
+        return resolved;
+    }
+    /** Converts the runner's structured process status into a tool error. */
+    headlessFailure(action, result) {
+        if (result.exitCode === 0 && result.signal === null)
+            return null;
+        const status = result.signal
+            ? `terminated by signal ${result.signal}`
+            : `exited with code ${result.exitCode}`;
+        const output = result.stderr || result.stdout;
+        return createErrorResponse(`${action} (${status})${output ? `: ${output}` : '.'}`);
+    }
+    async handleListProjects(args) {
+        // Normalize parameters to camelCase
+        args = normalizeParameters(args);
+        if (!args.directory) {
+            return createErrorResponse('Directory is required');
+        }
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.directory)) {
+            return createErrorResponse('Invalid directory path');
+        }
+        try {
+            this.context.logDebug(`Listing Godot projects in directory: ${args.directory}`);
+            if (!existsSync(args.directory)) {
+                return createErrorResponse(`Directory does not exist: ${args.directory}`);
+            }
+            const recursive = args.recursive === true;
+            const projects = this.context.projectSupport.findGodotProjects(args.directory, recursive);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(projects, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to list projects: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * Get the structure of a Godot project asynchronously by counting files recursively
+     * @param projectPath Path to the Godot project
+     * @returns Promise resolving to an object with counts of scenes, scripts, assets, and other files
+     */
+    async handleGetProjectInfo(args) {
+        // Normalize parameters to camelCase
+        args = normalizeParameters(args);
+        if (!args.projectPath) {
+            return createErrorResponse('Project path is required');
+        }
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath)) {
+            return createErrorResponse('Invalid project path');
+        }
+        try {
+            // Ensure godotPath is set
+            if (!this.context.getGodotPath()) {
+                await this.context.detectGodotPath();
+                if (!this.context.getGodotPath()) {
+                    return createErrorResponse('Could not find a valid Godot executable path');
+                }
+            }
+            // Check if the project directory exists and contains a project.godot file
+            const projectFile = join(args.projectPath, 'project.godot');
+            if (!existsSync(projectFile)) {
+                return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+            }
+            this.context.logDebug(`Getting project info for: ${args.projectPath}`);
+            // Get Godot version
+            const { stdout } = await execFileAsync(this.context.getGodotPath(), ['--version'], GODOT_VERSION_OPTIONS);
+            // Get project structure using the recursive method
+            const projectStructure = await this.context.projectSupport.getProjectStructureAsync(args.projectPath);
+            // Extract project name from project.godot file
+            let projectName = basename(args.projectPath);
+            try {
+                const projectFileContent = readFileSync(projectFile, 'utf8');
+                const configNameMatch = /config\/name="([^"]+)"/.exec(projectFileContent);
+                if (configNameMatch && configNameMatch[1]) {
+                    projectName = configNameMatch[1];
+                    this.context.logDebug(`Found project name in config: ${projectName}`);
+                }
+            }
+            catch (error) {
+                this.context.logDebug(`Error reading project file: ${error}`);
+                // Continue with default project name if extraction fails
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            name: projectName,
+                            path: args.projectPath,
+                            godotVersion: stdout.trim(),
+                            isDotnet: this.context.projectSupport.isDotnetProject(args.projectPath),
+                            structure: projectStructure,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to get project info: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * Handle the create_scene tool
+     */
+    async handleCreateScene(args) {
+        // Normalize parameters to camelCase
+        args = normalizeParameters(args);
+        if (!args.projectPath || !args.scenePath) {
+            return createErrorResponse('Project path and scene path are required');
+        }
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath) || !validatePath(args.scenePath)) {
+            return createErrorResponse('Invalid path');
+        }
+        try {
+            // Check if the project directory exists and contains a project.godot file
+            const projectFile = join(args.projectPath, 'project.godot');
+            if (!existsSync(projectFile)) {
+                return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+            }
+            // Prepare parameters for the operation (already in camelCase)
+            const params = {
+                scenePath: args.scenePath,
+                rootNodeType: args.rootNodeType || 'Node2D',
+            };
+            // Execute the operation
+            const result = await this.context.executeOperation('create_scene', params, args.projectPath);
+            const failure = this.headlessFailure('Failed to create scene', result);
+            if (failure)
+                return failure;
+            const { stdout } = result;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Scene created successfully at: ${args.scenePath}\n\nOutput: ${stdout}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to create scene: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * Handle the add_node tool
+     */
+    async handleAddNode(args) {
+        // Normalize parameters to camelCase
+        args = normalizeParameters(args);
+        if (!args.projectPath || !args.scenePath || !args.nodeType || !args.nodeName) {
+            return createErrorResponse('Missing required parameters');
+        }
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath) || !validatePath(args.scenePath)) {
+            return createErrorResponse('Invalid path');
+        }
+        try {
+            // Check if the project directory exists and contains a project.godot file
+            const projectFile = join(args.projectPath, 'project.godot');
+            if (!existsSync(projectFile)) {
+                return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+            }
+            // Check if the scene file exists
+            const scenePath = this.projectRelativePath(args.projectPath, args.scenePath);
+            if (!existsSync(scenePath)) {
+                return createErrorResponse(`Scene file does not exist: ${args.scenePath}`);
+            }
+            // Prepare parameters for the operation (already in camelCase)
+            const params = {
+                scenePath: args.scenePath,
+                nodeType: args.nodeType,
+                nodeName: args.nodeName,
+            };
+            // Add optional parameters
+            if (args.parentNodePath) {
+                params.parentNodePath = args.parentNodePath;
+            }
+            if (args.properties) {
+                params.properties = args.properties;
+            }
+            // Execute the operation
+            const result = await this.context.executeOperation('add_node', params, args.projectPath);
+            const failure = this.headlessFailure('Failed to add node', result);
+            if (failure)
+                return failure;
+            const { stdout } = result;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Node '${args.nodeName}' of type '${args.nodeType}' added successfully to '${args.scenePath}'.\n\nOutput: ${stdout}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to add node: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * Handle the load_sprite tool
+     */
+    async handleLoadSprite(args) {
+        // Normalize parameters to camelCase
+        args = normalizeParameters(args);
+        if (!args.projectPath || !args.scenePath || !args.nodePath || !args.texturePath) {
+            return createErrorResponse('Missing required parameters');
+        }
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath) ||
+            !validatePath(args.scenePath) ||
+            !validatePath(args.nodePath) ||
+            !validatePath(args.texturePath)) {
+            return createErrorResponse('Invalid path');
+        }
+        try {
+            // Check if the project directory exists and contains a project.godot file
+            const projectFile = join(args.projectPath, 'project.godot');
+            if (!existsSync(projectFile)) {
+                return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+            }
+            // Check if the scene file exists
+            const scenePath = this.projectRelativePath(args.projectPath, args.scenePath);
+            if (!existsSync(scenePath)) {
+                return createErrorResponse(`Scene file does not exist: ${args.scenePath}`);
+            }
+            // Check if the texture file exists
+            const texturePath = this.projectRelativePath(args.projectPath, args.texturePath);
+            if (!existsSync(texturePath)) {
+                return createErrorResponse(`Texture file does not exist: ${args.texturePath}`);
+            }
+            // Prepare parameters for the operation (already in camelCase)
+            const params = {
+                scenePath: args.scenePath,
+                nodePath: args.nodePath,
+                texturePath: args.texturePath,
+            };
+            // Execute the operation
+            const result = await this.context.executeOperation('load_sprite', params, args.projectPath);
+            const failure = this.headlessFailure('Failed to load sprite', result);
+            if (failure)
+                return failure;
+            const { stdout } = result;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Sprite loaded successfully with texture: ${args.texturePath}\n\nOutput: ${stdout}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to load sprite: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * Handle the export_mesh_library tool
+     */
+    async handleExportMeshLibrary(args) {
+        // Normalize parameters to camelCase
+        args = normalizeParameters(args);
+        if (!args.projectPath || !args.scenePath || !args.outputPath) {
+            return createErrorResponse('Missing required parameters');
+        }
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath) ||
+            !validatePath(args.scenePath) ||
+            !validatePath(args.outputPath)) {
+            return createErrorResponse('Invalid path');
+        }
+        try {
+            // Check if the project directory exists and contains a project.godot file
+            const projectFile = join(args.projectPath, 'project.godot');
+            if (!existsSync(projectFile)) {
+                return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+            }
+            // Check if the scene file exists
+            const scenePath = this.projectRelativePath(args.projectPath, args.scenePath);
+            if (!existsSync(scenePath)) {
+                return createErrorResponse(`Scene file does not exist: ${args.scenePath}`);
+            }
+            // Prepare parameters for the operation (already in camelCase)
+            const params = {
+                scenePath: args.scenePath,
+                outputPath: args.outputPath,
+            };
+            // Add optional parameters
+            if (args.meshItemNames && Array.isArray(args.meshItemNames)) {
+                params.meshItemNames = args.meshItemNames;
+            }
+            // Execute the operation
+            const result = await this.context.executeOperation('export_mesh_library', params, args.projectPath);
+            const failure = this.headlessFailure('Failed to export mesh library', result);
+            if (failure)
+                return failure;
+            const { stdout } = result;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `MeshLibrary exported successfully to: ${args.outputPath}\n\nOutput: ${stdout}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to export mesh library: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * Handle the save_scene tool
+     */
+    async handleSaveScene(args) {
+        // Normalize parameters to camelCase
+        args = normalizeParameters(args);
+        if (!args.projectPath || !args.scenePath) {
+            return createErrorResponse('Missing required parameters');
+        }
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath) || !validatePath(args.scenePath)) {
+            return createErrorResponse('Invalid path');
+        }
+        // If newPath is provided, validate it
+        if (args.newPath && !validatePath(args.newPath)) {
+            return createErrorResponse('Invalid new path');
+        }
+        try {
+            // Check if the project directory exists and contains a project.godot file
+            const projectFile = join(args.projectPath, 'project.godot');
+            if (!existsSync(projectFile)) {
+                return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+            }
+            // Check if the scene file exists
+            const scenePath = this.projectRelativePath(args.projectPath, args.scenePath);
+            if (!existsSync(scenePath)) {
+                return createErrorResponse(`Scene file does not exist: ${args.scenePath}`);
+            }
+            // Prepare parameters for the operation (already in camelCase)
+            const params = {
+                scenePath: args.scenePath,
+            };
+            // Add optional parameters
+            if (args.newPath) {
+                params.newPath = args.newPath;
+            }
+            // Execute the operation
+            const result = await this.context.executeOperation('save_scene', params, args.projectPath);
+            const failure = this.headlessFailure('Failed to save scene', result);
+            if (failure)
+                return failure;
+            const { stdout } = result;
+            const savePath = args.newPath || args.scenePath;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Scene saved successfully to: ${savePath}\n\nOutput: ${stdout}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to save scene: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * Handle the get_uid tool
+     */
+    async handleGetUid(args) {
+        // Normalize parameters to camelCase
+        args = normalizeParameters(args);
+        if (!args.projectPath || !args.filePath) {
+            return createErrorResponse('Missing required parameters');
+        }
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath) || !validatePath(args.filePath)) {
+            return createErrorResponse('Invalid path');
+        }
+        try {
+            // Ensure godotPath is set
+            if (!this.context.getGodotPath()) {
+                await this.context.detectGodotPath();
+                if (!this.context.getGodotPath()) {
+                    return createErrorResponse('Could not find a valid Godot executable path');
+                }
+            }
+            // Check if the project directory exists and contains a project.godot file
+            const projectFile = join(args.projectPath, 'project.godot');
+            if (!existsSync(projectFile)) {
+                return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+            }
+            // Check if the file exists
+            const filePath = this.projectRelativePath(args.projectPath, args.filePath);
+            if (!existsSync(filePath)) {
+                return createErrorResponse(`File does not exist: ${args.filePath}`);
+            }
+            // Get Godot version to check if UIDs are supported
+            const { stdout: versionOutput } = await execFileAsync(this.context.getGodotPath(), ['--version'], GODOT_VERSION_OPTIONS);
+            const version = versionOutput.trim();
+            if (!isGodot44OrLater(version)) {
+                return createErrorResponse(`UIDs are only supported in Godot 4.4 or later. Current version: ${version}`);
+            }
+            // Prepare parameters for the operation (already in camelCase)
+            const params = {
+                filePath: args.filePath,
+            };
+            // Execute the operation
+            const result = await this.context.executeOperation('get_uid', params, args.projectPath);
+            const failure = this.headlessFailure('Failed to get UID', result);
+            if (failure)
+                return failure;
+            const { stdout } = result;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `UID for ${args.filePath}: ${stdout.trim()}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to get UID: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * Handle the game_screenshot tool
+     */
+    async handleReadScene(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.scenePath) {
+            return createErrorResponse('projectPath and scenePath are required.');
+        }
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath) || !validatePath(args.scenePath)) {
+            return createErrorResponse('Invalid path.');
+        }
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile)) {
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        }
+        const scenePath = this.projectRelativePath(args.projectPath, args.scenePath);
+        if (!existsSync(scenePath)) {
+            return createErrorResponse(`Scene file does not exist: ${args.scenePath}`);
+        }
+        try {
+            const result = await this.context.executeOperation('read_scene', {
+                scenePath: args.scenePath,
+            }, args.projectPath);
+            const failure = this.headlessFailure('Failed to read scene', result);
+            if (failure)
+                return failure;
+            const { stdout, stderr } = result;
+            // Extract JSON from the SCENE_JSON_START/END markers
+            const startMarker = 'SCENE_JSON_START';
+            const endMarker = 'SCENE_JSON_END';
+            const startIdx = stdout.indexOf(startMarker);
+            const endIdx = stdout.indexOf(endMarker);
+            if (startIdx !== -1 && endIdx !== -1) {
+                const jsonStr = stdout.substring(startIdx + startMarker.length, endIdx).trim();
+                try {
+                    const parsed = JSON.parse(jsonStr);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }],
+                    };
+                }
+                catch {
+                    return {
+                        content: [{ type: 'text', text: `Raw scene data:\n${jsonStr}` }],
+                    };
+                }
+            }
+            return {
+                content: [{ type: 'text', text: `Scene read output:\n${stdout}\n${stderr ? 'Errors:\n' + stderr : ''}` }],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to read scene: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * Handle the modify_scene_node tool
+     */
+    async handleModifySceneNode(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.scenePath || !args.nodePath || !args.properties)
+            return createErrorResponse('projectPath, scenePath, nodePath, and properties are required.');
+        return this.sceneOperations.run('modify_node', args, { scenePath: args.scenePath, nodePath: args.nodePath, properties: args.properties });
+    }
+    async handleRemoveSceneNode(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.scenePath || !args.nodePath)
+            return createErrorResponse('projectPath, scenePath, and nodePath are required.');
+        return this.sceneOperations.run('remove_node', args, { scenePath: args.scenePath, nodePath: args.nodePath });
+    }
+    /**
+     * Handle the read_project_settings tool - Parse project.godot as JSON
+     */
+    async handleReadProjectSettings(args) {
+        return this.configuration.read(args);
+    }
+    /**
+     * Handle the modify_project_settings tool - Change a project.godot setting
+     */
+    async handleModifyProjectSettings(args) {
+        return this.configuration.modify(args);
+    }
+    /**
+     * Handle the list_project_files tool - List files with extension filtering
+     */
+    async handleListProjectFiles(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath) {
+            return createErrorResponse('projectPath is required.');
+        }
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath)) {
+            return createErrorResponse('Invalid path.');
+        }
+        if (!existsSync(args.projectPath)) {
+            return createErrorResponse(`Directory does not exist: ${args.projectPath}`);
+        }
+        try {
+            const baseDir = args.subdirectory
+                ? this.projectRelativePath(args.projectPath, args.subdirectory)
+                : args.projectPath;
+            if (!existsSync(baseDir)) {
+                return createErrorResponse(`Subdirectory does not exist: ${args.subdirectory}`);
+            }
+            const files = [];
+            const extensions = args.extensions;
+            const scanDir = (dir, relativeTo) => {
+                const entries = readdirSync(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.name.startsWith('.'))
+                        continue;
+                    const fullPath = join(dir, entry.name);
+                    const relativePath = fullPath.substring(relativeTo.length + 1).replace(/\\/g, '/');
+                    if (entry.isDirectory()) {
+                        scanDir(fullPath, relativeTo);
+                    }
+                    else if (entry.isFile()) {
+                        if (extensions && extensions.length > 0) {
+                            const ext = '.' + entry.name.split('.').pop();
+                            if (extensions.includes(ext)) {
+                                files.push(relativePath);
+                            }
+                        }
+                        else {
+                            files.push(relativePath);
+                        }
+                    }
+                }
+            };
+            scanDir(baseDir, args.projectPath);
+            files.sort((left, right) => left.localeCompare(right, 'en'));
+            const cursor = args.cursor ?? 0;
+            const limit = args.limit ?? 1000;
+            const page = files.slice(cursor, cursor + limit);
+            const nextCursor = cursor + page.length < files.length ? cursor + page.length : null;
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ count: page.length, total: files.length, files: page, nextCursor }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to list project files: ${errorMessage(error)}`);
+        }
+    }
+    async handleAttachScript(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.scenePath || !args.nodePath || !args.scriptPath)
+            return createErrorResponse('projectPath, scenePath, nodePath, and scriptPath are required.');
+        return this.context.headlessOp('attach_script', args, a => ({
+            projectPath: a.projectPath,
+            params: { scenePath: a.scenePath, nodePath: a.nodePath, scriptPath: a.scriptPath },
+        }));
+    }
+    async handleCreateResource(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.resourceType || !args.resourcePath)
+            return createErrorResponse('projectPath, resourceType, and resourcePath are required.');
+        return this.context.headlessOp('create_resource', args, a => ({
+            projectPath: a.projectPath,
+            params: { resourceType: a.resourceType, resourcePath: a.resourcePath, ...(a.properties ? { properties: a.properties } : {}) },
+        }));
+    }
+    // --- File I/O handlers ---
+    async handleReadFile(args) {
+        return this.fileIO.read(args);
+    }
+    async handleWriteFile(args) {
+        return this.fileIO.write(args);
+    }
+    async handleDeleteFile(args) {
+        return this.fileIO.delete(args);
+    }
+    async handleCreateDirectory(args) {
+        return this.fileIO.createDirectory(args);
+    }
+    // --- Error/Log capture handlers ---
+    async handleCreateProject(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.projectName)
+            return createErrorResponse('projectPath and projectName are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath, true))
+            return createErrorResponse('Invalid path.');
+        try {
+            if (!existsSync(args.projectPath)) {
+                mkdirSync(args.projectPath, { recursive: true });
+            }
+            const projectFile = join(args.projectPath, 'project.godot');
+            if (existsSync(projectFile))
+                return createErrorResponse('A project.godot already exists at this path.');
+            const isDotnet = args.dotnet === true;
+            const assemblyName = toDotnetIdentifier(args.projectName);
+            const features = generateGodotProjectFeatures(isDotnet);
+            let content = `; Engine configuration file.\n; Generated by Godot Agent Loop.\n\nconfig_version=5\n\n[application]\n\nconfig/name=${JSON.stringify(args.projectName)}\nconfig/features=${features}\n`;
+            if (isDotnet) {
+                content += `\n[dotnet]\n\nproject/assembly_name=${JSON.stringify(assemblyName)}\n`;
+            }
+            writeFileSync(projectFile, content, 'utf8');
+            if (isDotnet) {
+                const sdkVersion = (await this.context.projectSupport.detectGodotNetSdkVersion()) ?? undefined;
+                writeFileSync(this.projectRelativePath(args.projectPath, `${assemblyName}.csproj`), generateCsprojContent(args.projectName, sdkVersion), 'utf8');
+            }
+            return { content: [{ type: 'text', text: `Project "${args.projectName}" created at ${args.projectPath}${isDotnet ? ' (Godot .NET / C#)' : ''}` }] };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to create project: ${errorMessage(error)}`);
+        }
+    }
+    async handleCreateCsharpScript(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.scriptPath)
+            return createErrorResponse('projectPath and scriptPath are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath) || !validatePath(args.scriptPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        if (!this.context.projectSupport.isDotnetProject(args.projectPath))
+            return createErrorResponse('Not a Godot .NET project (no .csproj found). Use create_project with dotnet: true first.');
+        if (!/\.cs$/i.test(args.scriptPath))
+            return createErrorResponse('scriptPath must end with .cs');
+        const fileBase = basename(args.scriptPath).replace(/\.cs$/i, '');
+        if (!isValidCsharpIdentifier(fileBase))
+            return createErrorResponse(`Invalid C# script file name "${fileBase}.cs": the name must be a valid class name (letters, digits, underscore; not starting with a digit), because Godot requires the class name to match the file name.`);
+        if (args.className && args.className !== fileBase)
+            return createErrorResponse(`className "${args.className}" must match the script file name "${fileBase}" for Godot to attach the script.`);
+        try {
+            const fullPath = this.projectRelativePath(args.projectPath, args.scriptPath);
+            const dir = dirname(fullPath);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            let source = args.source;
+            if (!source) {
+                source = generateCsharpScriptSource({
+                    className: fileBase,
+                    baseClass: args.baseClass,
+                    namespaceName: args.namespaceName,
+                    methods: Array.isArray(args.methods) ? args.methods : undefined,
+                });
+            }
+            writeFileSync(fullPath, source, 'utf8');
+            return { content: [{ type: 'text', text: `C# script created at ${args.scriptPath}` }] };
+        }
+        catch (error) {
+            return createErrorResponse(`create_csharp_script failed: ${errorMessage(error)}`);
+        }
+    }
+    async handleManageAutoloads(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.action)
+            return createErrorResponse('projectPath and action are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        try {
+            let content = readFileSync(projectFile, 'utf8');
+            if (args.action === 'list') {
+                const autoloads = {};
+                const autoloadMatch = /\[autoload\]([\s\S]*?)(?=\n\[|$)/.exec(content);
+                if (autoloadMatch) {
+                    for (const line of autoloadMatch[1].split('\n')) {
+                        const kv = /^([^=]+)=(.*)$/.exec(line.trim());
+                        if (kv)
+                            autoloads[kv[1].trim()] = kv[2].trim();
+                    }
+                }
+                return { content: [{ type: 'text', text: JSON.stringify(autoloads, null, 2) }] };
+            }
+            else if (args.action === 'add') {
+                if (!args.name || !args.path)
+                    return createErrorResponse('name and path are required for add action.');
+                const autoloadLine = `${args.name}="*${args.path}"`;
+                if (content.includes('[autoload]')) {
+                    content = content.replace('[autoload]', `[autoload]\n\n${autoloadLine}`);
+                }
+                else {
+                    content += `\n[autoload]\n\n${autoloadLine}\n`;
+                }
+                writeFileSync(projectFile, content, 'utf8');
+                return { content: [{ type: 'text', text: `Autoload "${args.name}" added: ${args.path}` }] };
+            }
+            else if (args.action === 'remove') {
+                if (!args.name)
+                    return createErrorResponse('name is required for remove action.');
+                const pattern = new RegExp(`\\n?${args.name}\\s*=.*\\n?`, 'g');
+                content = content.replace(pattern, '\n');
+                writeFileSync(projectFile, content, 'utf8');
+                return { content: [{ type: 'text', text: `Autoload "${args.name}" removed.` }] };
+            }
+            return createErrorResponse('Invalid action. Use "list", "add", or "remove".');
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to manage autoloads: ${errorMessage(error)}`);
+        }
+    }
+    async handleManageInputMap(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.action)
+            return createErrorResponse('projectPath and action are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        try {
+            let content = readFileSync(projectFile, 'utf8');
+            if (args.action === 'list') {
+                const actions = {};
+                const inputMatch = /\[input\]([\s\S]*?)(?=\n\[|$)/.exec(content);
+                if (inputMatch) {
+                    for (const line of inputMatch[1].split('\n')) {
+                        const kv = /^([^=]+)=(.*)$/.exec(line.trim());
+                        if (kv)
+                            actions[kv[1].trim()] = kv[2].trim();
+                    }
+                }
+                return { content: [{ type: 'text', text: JSON.stringify(actions, null, 2) }] };
+            }
+            else if (args.action === 'add') {
+                if (!args.actionName)
+                    return createErrorResponse('actionName is required for add action.');
+                const deadzone = args.deadzone !== undefined ? args.deadzone : 0.5;
+                const keycode = args.key ? this.context.projectSupport.keyNameToScancode(args.key) : undefined;
+                const merged = mergeInputMapAction(content, args.actionName, deadzone, keycode);
+                content = merged.content;
+                writeFileSync(projectFile, content, 'utf8');
+                const outcome = merged.existed ? (merged.eventAdded ? 'updated with key binding' : 'already configured') : 'added';
+                return { content: [{ type: 'text', text: `Input action "${args.actionName}" ${outcome}.` }] };
+            }
+            else if (args.action === 'remove') {
+                if (!args.actionName)
+                    return createErrorResponse('actionName is required for remove action.');
+                const pattern = new RegExp(`\\n?${args.actionName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*=.*\\n?`, 'g');
+                content = content.replace(pattern, '\n');
+                writeFileSync(projectFile, content, 'utf8');
+                return { content: [{ type: 'text', text: `Input action "${args.actionName}" removed.` }] };
+            }
+            return createErrorResponse('Invalid action. Use "list", "add", or "remove".');
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to manage input map: ${errorMessage(error)}`);
+        }
+    }
+    async handleManageExportPresets(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.action)
+            return createErrorResponse('projectPath and action are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        const presetsFile = join(args.projectPath, 'export_presets.cfg');
+        try {
+            if (args.action === 'list') {
+                if (!existsSync(presetsFile))
+                    return { content: [{ type: 'text', text: JSON.stringify({ presets: [] }, null, 2) }] };
+                const content = readFileSync(presetsFile, 'utf8');
+                const presets = [];
+                const nameMatches = content.matchAll(/name="([^"]+)"/g);
+                const platformMatches = content.matchAll(/platform="([^"]+)"/g);
+                const names = [...nameMatches].map(m => m[1]);
+                const platforms = [...platformMatches].map(m => m[1]);
+                for (let i = 0; i < names.length; i++) {
+                    presets.push({ name: names[i], platform: platforms[i] || 'unknown' });
+                }
+                return { content: [{ type: 'text', text: JSON.stringify({ presets }, null, 2) }] };
+            }
+            else if (args.action === 'add') {
+                if (!args.name || !args.platform)
+                    return createErrorResponse('name and platform are required for add action.');
+                const runnable = args.runnable ? 'true' : 'false';
+                const presetBlock = `\n[preset.${Date.now()}]\n\nname="${args.name}"\nplatform="${args.platform}"\nrunnable=${runnable}\n`;
+                let content = existsSync(presetsFile) ? readFileSync(presetsFile, 'utf8') : '';
+                content += presetBlock;
+                writeFileSync(presetsFile, content, 'utf8');
+                return { content: [{ type: 'text', text: `Export preset "${args.name}" added for platform "${args.platform}".` }] };
+            }
+            else if (args.action === 'remove') {
+                if (!args.name)
+                    return createErrorResponse('name is required for remove action.');
+                if (!existsSync(presetsFile))
+                    return createErrorResponse('No export_presets.cfg file found.');
+                let content = readFileSync(presetsFile, 'utf8');
+                // Remove the preset section containing the given name
+                const pattern = new RegExp(`\\[preset\\.[^\\]]+\\]\\s*\\n[\\s\\S]*?name="${args.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"[\\s\\S]*?(?=\\[preset\\.|$)`, 'g');
+                content = content.replace(pattern, '');
+                writeFileSync(presetsFile, content, 'utf8');
+                return { content: [{ type: 'text', text: `Export preset "${args.name}" removed.` }] };
+            }
+            return createErrorResponse('Invalid action. Use "list", "add", or "remove".');
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to manage export presets: ${errorMessage(error)}`);
+        }
+    }
+    // --- Advanced runtime handlers ---
+    async handleExportProject(args) {
+        return this.exportService.export(args);
+    }
+    async handleRunProjectTests(args) {
+        if (args.action !== 'discover' && args.action !== 'run') {
+            return createErrorResponse('action must be discover or run.');
+        }
+        return this.projectTests.execute(args);
+    }
+    async handleManageImportPipeline(args) {
+        if (!['inspect', 'change', 'reimport', 'dependencies'].includes(String(args.action))) {
+            return createErrorResponse('action must be inspect, change, reimport, or dependencies.');
+        }
+        return this.importPipeline.execute(args);
+    }
+    async handleAnalyzeProjectIntegrity(args) {
+        if (!['analyze', 'preview_rename', 'assets', 'localization', 'accessibility', 'extensions', 'leaks'].includes(args.action)) {
+            return createErrorResponse('action must be analyze, preview_rename, assets, localization, accessibility, extensions, or leaks.');
+        }
+        return this.projectIntegrity.execute(args);
+    }
+    async handleVerifyExportReadiness(args) {
+        if (args.action !== 'inspect' && args.action !== 'export_smoke') {
+            return createErrorResponse('action must be inspect or export_smoke.');
+        }
+        return this.exportReadiness.execute(args);
+    }
+    async handleVerifyDotnetProject(args) {
+        if (!['inspect', 'restore', 'build', 'run'].includes(String(args.action))) {
+            return createErrorResponse('action must be inspect, restore, build, or run.');
+        }
+        return this.dotnetWorkflow.execute(args);
+    }
+    async handleManageAddon(args) {
+        if (!['inspect', 'install', 'update', 'remove', 'enable', 'disable'].includes(String(args.action))) {
+            return createErrorResponse('action must be inspect, install, update, remove, enable, or disable.');
+        }
+        return this.addonManagement.execute(args);
+    }
+    async handleRenameFile(args) {
+        return this.fileIO.rename(args);
+    }
+    async handleManageResource(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.resourcePath || !args.action)
+            return createErrorResponse('projectPath, resourcePath, and action are required.');
+        return this.context.headlessOp('manage_resource', args, a => ({
+            projectPath: a.projectPath,
+            params: { resourcePath: a.resourcePath, action: a.action, ...(a.properties ? { properties: a.properties } : {}) },
+        }));
+    }
+    async handleValidateScript(args) {
+        return this.scriptValidation.validate(args);
+    }
+    async handleValidateScripts(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath)
+            return createErrorResponse('projectPath is required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        if (!this.context.getGodotPath()) {
+            await this.context.detectGodotPath();
+            if (!this.context.getGodotPath())
+                return createErrorResponse('Could not find a valid Godot executable path');
+        }
+        let scope;
+        let candidates;
+        const explicit = Array.isArray(args.scriptPaths) && args.scriptPaths.length > 0;
+        if (explicit) {
+            scope = 'explicit';
+            candidates = args.scriptPaths.map((p) => String(p));
+        }
+        else if (args.scope === undefined || args.scope === 'changed') {
+            scope = 'changed';
+            const changed = await this.context.projectSupport.listChangedGdFiles(args.projectPath);
+            if (changed.error)
+                return createErrorResponse(changed.error);
+            candidates = changed.files;
+        }
+        else if (args.scope === 'all') {
+            scope = 'all';
+            candidates = this.context.projectSupport.listAllGdFiles(args.projectPath);
+        }
+        else {
+            return createErrorResponse(`Invalid scope "${args.scope}". Use "changed" or "all", or pass scriptPaths.`);
+        }
+        const results = [];
+        let filesWithErrors = 0;
+        const toCheck = [];
+        for (const rel of candidates) {
+            if (!/\.gd$/i.test(rel) || !validatePath(rel)) {
+                if (explicit)
+                    results.push({ scriptPath: rel, checked: false, error: 'Not a valid .gd path' });
+                continue;
+            }
+            if (!existsSync(join(args.projectPath, rel))) {
+                if (explicit)
+                    results.push({ scriptPath: rel, checked: false, error: 'Script does not exist' });
+                continue;
+            }
+            toCheck.push(rel);
+        }
+        const MAX_BATCH = 60;
+        if (toCheck.length > MAX_BATCH)
+            return createErrorResponse(`Too many scripts to validate (${toCheck.length} > ${MAX_BATCH}). Narrow the scope or pass an explicit scriptPaths list.`);
+        for (const rel of toCheck) {
+            const check = await this.context.projectSupport.runGdScriptCheck(args.projectPath, join(args.projectPath, rel));
+            if (!check.completed) {
+                results.push({ scriptPath: rel, checked: false, error: check.error });
+            }
+            else {
+                if (check.errors.length > 0)
+                    filesWithErrors++;
+                results.push({ scriptPath: rel, checked: true, valid: check.errors.length === 0, errorCount: check.errors.length, errors: check.errors });
+            }
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        scope,
+                        fileCount: results.length,
+                        filesWithErrors,
+                        allValid: filesWithErrors === 0 && results.every(r => r.checked),
+                        results,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    async handleCreateScript(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.scriptPath)
+            return createErrorResponse('projectPath and scriptPath are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath) || !validatePath(args.scriptPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        try {
+            const fullPath = this.projectRelativePath(args.projectPath, args.scriptPath);
+            const dir = dirname(fullPath);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            let source = args.source;
+            if (!source) {
+                const ext = args.extends || 'Node';
+                const lines = [`extends ${ext}`, ''];
+                if (args.className)
+                    lines.splice(1, 0, `class_name ${args.className}`);
+                if (args.methods && Array.isArray(args.methods)) {
+                    for (const m of args.methods) {
+                        lines.push('', `func ${m}():`);
+                        lines.push('\tpass');
+                    }
+                }
+                source = lines.join('\n') + '\n';
+            }
+            writeFileSync(fullPath, source, 'utf8');
+            return { content: [{ type: 'text', text: `Script created at ${args.scriptPath}` }] };
+        }
+        catch (error) {
+            return createErrorResponse(`create_script failed: ${errorMessage(error)}`);
+        }
+    }
+    async handleManageSceneSignals(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.scenePath || !args.action)
+            return createErrorResponse('projectPath, scenePath, and action are required.');
+        return this.sceneOperations.run('manage_scene_signals', args, {
+            scenePath: args.scenePath, action: args.action,
+            ...(args.signalName ? { signalName: args.signalName } : {}),
+            ...(args.sourcePath ? { sourcePath: args.sourcePath } : {}),
+            ...(args.targetPath ? { targetPath: args.targetPath } : {}),
+            ...(args.method ? { method: args.method } : {}),
+        });
+    }
+    async handleManageLayers(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.action)
+            return createErrorResponse('projectPath and action are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        try {
+            let content = readFileSync(projectFile, 'utf8');
+            // Keys live inside [layer_names] as `<type>/layer_<n>`, so the section
+            // header supplies the `layer_names/` prefix of the engine setting path.
+            // Older versions wrote the prefix into the key as well, producing
+            // `layer_names/layer_names/...`, which the engine never resolved; those
+            // stale keys are still listed and are repaired by the next `set`.
+            const sectionLayers = () => {
+                const section = /\[layer_names\]([\s\S]*?)(?=\n\[|$)/.exec(content);
+                if (!section)
+                    return [];
+                const layers = [];
+                const entry = /^(?:layer_names\/)?([\w_]+)\/layer_(\d+)\s*=\s*"([^"]*)"$/;
+                for (const line of section[1].split('\n')) {
+                    const match = entry.exec(line.trim());
+                    if (match)
+                        layers.push({ type: match[1], layer: parseInt(match[2]), name: match[3] });
+                }
+                return layers;
+            };
+            if (args.action === 'list') {
+                return { content: [{ type: 'text', text: JSON.stringify({ layers: sectionLayers() }, null, 2) }] };
+            }
+            else if (args.action === 'set') {
+                if (!args.layerType || !args.layer || !args.name)
+                    return createErrorResponse('layerType, layer, and name are required for set.');
+                const key = `${args.layerType}/layer_${args.layer}`;
+                const settingLine = `${key}="${args.name}"`;
+                const existingRegex = new RegExp(`^(?:layer_names\\/)?${key.replace(/\//g, '\\/')}\\s*=\\s*"[^"]*"$`, 'm');
+                if (existingRegex.test(content)) {
+                    content = content.replace(existingRegex, settingLine);
+                }
+                else {
+                    if (!content.includes('[layer_names]'))
+                        content += '\n[layer_names]\n';
+                    content = content.replace('[layer_names]', `[layer_names]\n${settingLine}`);
+                }
+                writeFileSync(projectFile, content, 'utf8');
+                return { content: [{ type: 'text', text: `Layer set: layer_names/${settingLine}` }] };
+            }
+            return createErrorResponse(`Unknown action: ${args.action}`);
+        }
+        catch (error) {
+            return createErrorResponse(`manage_layers failed: ${errorMessage(error)}`);
+        }
+    }
+    async handleManagePlugins(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.action)
+            return createErrorResponse('projectPath and action are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        try {
+            let content = readFileSync(projectFile, 'utf8');
+            if (args.action === 'list') {
+                const enabledSetting = /\[editor_plugins\][\s\S]*?^enabled=PackedStringArray\(([^\n]*)\)/m.exec(content)?.[1] ?? '';
+                const plugins = [...enabledSetting.matchAll(/"res:\/\/addons\/([^/]+)\/plugin\.cfg"/g)]
+                    .map(match => match[1]);
+                const addonsDir = join(args.projectPath, 'addons');
+                const available = [];
+                if (existsSync(addonsDir)) {
+                    const entries = readdirSync(addonsDir, { withFileTypes: true });
+                    for (const e of entries) {
+                        if (e.isDirectory())
+                            available.push(e.name);
+                    }
+                }
+                return { content: [{ type: 'text', text: JSON.stringify({ enabled: plugins, available }, null, 2) }] };
+            }
+            else if (args.action === 'enable' || args.action === 'disable') {
+                if (!args.pluginName)
+                    return createErrorResponse('pluginName is required.');
+                const pluginPath = `res://addons/${args.pluginName}/plugin.cfg`;
+                const sectionPattern = /\[editor_plugins\][\s\S]*?(?=\n\[|$)/;
+                const section = sectionPattern.exec(content);
+                const current = section
+                    ? [...section[0].matchAll(/"(res:\/\/addons\/[^"]+\/plugin\.cfg)"/g)].map(match => match[1])
+                    : [];
+                const enabled = current.filter(value => value !== pluginPath);
+                if (args.action === 'enable')
+                    enabled.push(pluginPath);
+                const setting = `enabled=PackedStringArray(${[...new Set(enabled)].sort().map(value => JSON.stringify(value)).join(', ')})`;
+                if (!section)
+                    content += `\n[editor_plugins]\n\n${setting}\n`;
+                else {
+                    const replacement = /^enabled=.*$/m.test(section[0])
+                        ? section[0].replace(/^enabled=.*$/m, setting)
+                        : `${section[0].trimEnd()}\n${setting}\n`;
+                    content = content.slice(0, section.index) + replacement + content.slice(section.index + section[0].length);
+                }
+                writeFileSync(projectFile, content, 'utf8');
+                return { content: [{ type: 'text', text: `Plugin ${args.pluginName} ${args.action}d.` }] };
+            }
+            return createErrorResponse(`Unknown action: ${args.action}`);
+        }
+        catch (error) {
+            return createErrorResponse(`manage_plugins failed: ${errorMessage(error)}`);
+        }
+    }
+    async handleManageShader(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.shaderPath || !args.action)
+            return createErrorResponse('projectPath, shaderPath, and action are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath) || !validatePath(args.shaderPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        const fullPath = this.projectRelativePath(args.projectPath, args.shaderPath);
+        try {
+            if (args.action === 'read') {
+                if (!existsSync(fullPath))
+                    return createErrorResponse(`Shader not found: ${args.shaderPath}`);
+                const source = readFileSync(fullPath, 'utf8');
+                return { content: [{ type: 'text', text: source }] };
+            }
+            else if (args.action === 'create') {
+                const dir = dirname(fullPath);
+                if (!existsSync(dir))
+                    mkdirSync(dir, { recursive: true });
+                let source = args.source;
+                if (!source) {
+                    const type = args.shaderType || 'spatial';
+                    source = `shader_type ${type};\n\nvoid fragment() {\n\t// Called for every pixel the material is visible on.\n}\n`;
+                }
+                writeFileSync(fullPath, source, 'utf8');
+                return { content: [{ type: 'text', text: `Shader created at ${args.shaderPath}` }] };
+            }
+            return createErrorResponse(`Unknown action: ${args.action}`);
+        }
+        catch (error) {
+            return createErrorResponse(`manage_shader failed: ${errorMessage(error)}`);
+        }
+    }
+    async handleManageThemeResource(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.resourcePath || !args.action)
+            return createErrorResponse('projectPath, resourcePath, and action are required.');
+        return this.context.headlessOp('manage_theme_resource', args, a => ({
+            projectPath: a.projectPath,
+            params: { resourcePath: a.resourcePath, action: a.action, ...(a.properties ? { properties: a.properties } : {}) },
+        }));
+    }
+    async handleSetMainScene(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.scenePath)
+            return createErrorResponse('projectPath and scenePath are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        try {
+            let content = readFileSync(projectFile, 'utf8');
+            const resPath = args.scenePath.startsWith('res://') ? args.scenePath : `res://${args.scenePath}`;
+            const settingLine = `run/main_scene="${resPath}"`;
+            const existingRegex = /run\/main_scene="[^"]*"/;
+            if (existingRegex.test(content)) {
+                content = content.replace(existingRegex, settingLine);
+            }
+            else {
+                if (content.includes('[application]')) {
+                    content = content.replace('[application]', `[application]\n\n${settingLine}`);
+                }
+                else {
+                    content += `\n[application]\n\n${settingLine}\n`;
+                }
+            }
+            writeFileSync(projectFile, content, 'utf8');
+            return { content: [{ type: 'text', text: `Main scene set to ${resPath}` }] };
+        }
+        catch (error) {
+            return createErrorResponse(`set_main_scene failed: ${errorMessage(error)}`);
+        }
+    }
+    async handleManageSceneStructure(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.scenePath || !args.action || !args.nodePath)
+            return createErrorResponse('projectPath, scenePath, action, and nodePath are required.');
+        return this.sceneOperations.run('manage_scene_structure', args, {
+            scenePath: args.scenePath, action: args.action, nodePath: args.nodePath,
+            ...(args.newName ? { newName: args.newName } : {}),
+            ...(args.newParentPath ? { newParentPath: args.newParentPath } : {}),
+        });
+    }
+    async handleManageTranslations(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.action)
+            return createErrorResponse('projectPath and action are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        try {
+            let content = readFileSync(projectFile, 'utf8');
+            // The engine setting is `internationalization/locale/translations`, so the
+            // key inside [internationalization] must be `locale/translations`. A bare
+            // `translations=` key is never read by the engine; it is still matched here
+            // so projects written by older versions list correctly and are repaired on
+            // the next add.
+            const listRegex = /^(?:locale\/)?translations=PackedStringArray\(([^)]*)\)$/m;
+            if (args.action === 'list') {
+                const match = listRegex.exec(content);
+                const translations = match ? match[1].split(',').map(s => s.trim().replace(/"/g, '')).filter(Boolean) : [];
+                return { content: [{ type: 'text', text: JSON.stringify({ translations }, null, 2) }] };
+            }
+            else if (args.action === 'add') {
+                if (!args.translationPath)
+                    return createErrorResponse('translationPath is required.');
+                const resPath = args.translationPath.startsWith('res://') ? args.translationPath : `res://${args.translationPath}`;
+                const match = listRegex.exec(content);
+                if (match) {
+                    const existing = match[1];
+                    const newVal = existing ? `${existing}, "${resPath}"` : `"${resPath}"`;
+                    content = content.replace(listRegex, `locale/translations=PackedStringArray(${newVal})`);
+                }
+                else {
+                    if (!content.includes('[internationalization]'))
+                        content += '\n[internationalization]\n';
+                    content = content.replace('[internationalization]', `[internationalization]\n\nlocale/translations=PackedStringArray("${resPath}")`);
+                }
+                writeFileSync(projectFile, content, 'utf8');
+                return { content: [{ type: 'text', text: `Translation added: ${resPath}` }] };
+            }
+            else if (args.action === 'remove') {
+                if (!args.translationPath)
+                    return createErrorResponse('translationPath is required.');
+                const resPath = args.translationPath.startsWith('res://') ? args.translationPath : `res://${args.translationPath}`;
+                content = content.replace(new RegExp(`,?\\s*"${resPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"`), '');
+                writeFileSync(projectFile, content, 'utf8');
+                return { content: [{ type: 'text', text: `Translation removed: ${resPath}` }] };
+            }
+            return createErrorResponse(`Unknown action: ${args.action}`);
+        }
+        catch (error) {
+            return createErrorResponse(`manage_translations failed: ${errorMessage(error)}`);
+        }
+    }
+    async handleManageCiPipeline(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.action)
+            return createErrorResponse('projectPath and action are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        const workflowDir = join(args.projectPath, '.github', 'workflows');
+        const workflowPath = join(workflowDir, 'godot-export.yml');
+        try {
+            if (args.action === 'read') {
+                if (!existsSync(workflowPath))
+                    return createErrorResponse('No workflow file found at .github/workflows/godot-export.yml');
+                const content = readFileSync(workflowPath, 'utf8');
+                return { content: [{ type: 'text', text: content }] };
+            }
+            else if (args.action === 'create') {
+                const godotVersion = args.godotVersion || '4.3-stable';
+                const versionError = validateGodotExportVersion(godotVersion);
+                if (versionError)
+                    return createErrorResponse(versionError);
+                const platforms = args.platforms || ['linux'];
+                if (!Array.isArray(platforms) || platforms.length === 0 || !platforms.every(platform => typeof platform === 'string' && CI_EXPORT_PLATFORMS.has(platform))) {
+                    return createErrorResponse('platforms must be a non-empty array containing only: windows, linux, macos, web.');
+                }
+                if (new Set(platforms).size !== platforms.length) {
+                    return createErrorResponse('platforms must not contain duplicates.');
+                }
+                if (!existsSync(workflowDir))
+                    mkdirSync(workflowDir, { recursive: true });
+                const exportSteps = platforms.map((p) => `      - name: Export ${p}\n        run: godot --headless --export-release "${p}" build/${p}/game`).join('\n');
+                const workflow = `name: Godot Export\non:\n  push:\n    branches: [main]\n  pull_request:\n    branches: [main]\njobs:\n  export:\n    runs-on: ubuntu-latest\n    container:\n      image: barichello/godot-ci:${godotVersion}\n    steps:\n      - uses: actions/checkout@v4\n      - name: Setup export templates\n        run: |\n          mkdir -p ~/.local/share/godot/export_templates/${godotVersion}\n          mv /root/.local/share/godot/export_templates/${godotVersion}/* ~/.local/share/godot/export_templates/${godotVersion}/ || true\n${exportSteps}\n      - uses: actions/upload-artifact@v4\n        with:\n          name: game-builds\n          path: build/\n`;
+                writeFileSync(workflowPath, workflow, 'utf8');
+                return { content: [{ type: 'text', text: `CI pipeline created at .github/workflows/godot-export.yml for platforms: ${platforms.join(', ')}` }] };
+            }
+            return createErrorResponse(`Unknown action: ${args.action}`);
+        }
+        catch (error) {
+            return createErrorResponse(`manage_ci_pipeline failed: ${errorMessage(error)}`);
+        }
+    }
+    async handleManageDockerExport(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.action)
+            return createErrorResponse('projectPath and action are required.');
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath))
+            return createErrorResponse('Invalid path.');
+        const projectFile = join(args.projectPath, 'project.godot');
+        if (!existsSync(projectFile))
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        const dockerfilePath = join(args.projectPath, 'Dockerfile');
+        try {
+            if (args.action === 'read') {
+                if (!existsSync(dockerfilePath))
+                    return createErrorResponse('No Dockerfile found in project root.');
+                const content = readFileSync(dockerfilePath, 'utf8');
+                return { content: [{ type: 'text', text: content }] };
+            }
+            else if (args.action === 'create') {
+                const godotVersion = args.godotVersion || '4.3-stable';
+                const baseImage = args.baseImage || 'ubuntu:22.04';
+                let exportPreset = args.exportPreset || 'Linux/X11';
+                const versionError = validateGodotExportVersion(godotVersion);
+                if (versionError)
+                    return createErrorResponse(versionError);
+                if (typeof baseImage !== 'string' || !DOCKER_BASE_IMAGES.has(baseImage)) {
+                    return createErrorResponse('baseImage must be one of: ubuntu:22.04, ubuntu:24.04.');
+                }
+                if (typeof exportPreset !== 'string' || !EXPORT_PRESET_NAME.test(exportPreset)) {
+                    return createErrorResponse('exportPreset may contain only letters, digits, spaces, _, ., /, and - (up to 128 characters).');
+                }
+                const exportPresetName = exportPreset;
+                exportPreset = JSON.stringify(exportPreset).slice(1, -1);
+                const dockerfile = `FROM ${baseImage}\n\nARG GODOT_VERSION=${godotVersion}\n\nRUN apt-get update && apt-get install -y \\\n    wget unzip ca-certificates \\\n    && rm -rf /var/lib/apt/lists/*\n\nRUN wget -q https://github.com/godotengine/godot/releases/download/\${GODOT_VERSION}/Godot_v\${GODOT_VERSION}_linux.x86_64.zip \\\n    && unzip Godot_v\${GODOT_VERSION}_linux.x86_64.zip \\\n    && mv Godot_v\${GODOT_VERSION}_linux.x86_64 /usr/local/bin/godot \\\n    && rm Godot_v\${GODOT_VERSION}_linux.x86_64.zip\n\nRUN wget -q https://github.com/godotengine/godot/releases/download/\${GODOT_VERSION}/Godot_v\${GODOT_VERSION}_export_templates.tpz \\\n    && mkdir -p /root/.local/share/godot/export_templates/\${GODOT_VERSION} \\\n    && unzip Godot_v\${GODOT_VERSION}_export_templates.tpz \\\n    && mv templates/* /root/.local/share/godot/export_templates/\${GODOT_VERSION}/ \\\n    && rm -rf templates Godot_v\${GODOT_VERSION}_export_templates.tpz\n\nWORKDIR /game\nCOPY . .\n\nRUN mkdir -p build\nCMD ["godot", "--headless", "--export-release", "${exportPreset}", "build/game"]\n`;
+                writeFileSync(dockerfilePath, dockerfile, 'utf8');
+                return { content: [{ type: 'text', text: `Dockerfile created for headless Godot export (preset: ${exportPresetName})` }] };
+            }
+            return createErrorResponse(`Unknown action: ${args.action}`);
+        }
+        catch (error) {
+            return createErrorResponse(`manage_docker_export failed: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * Handle the update_project_uids tool
+     */
+    async handleUpdateProjectUids(args) {
+        // Normalize parameters to camelCase
+        args = normalizeParameters(args);
+        if (!args.projectPath) {
+            return createErrorResponse('Project path is required');
+        }
+        if (!this.context.pathSecurity.isProjectPathAllowed(args.projectPath)) {
+            return createErrorResponse('Invalid project path');
+        }
+        try {
+            // Ensure godotPath is set
+            if (!this.context.getGodotPath()) {
+                await this.context.detectGodotPath();
+                if (!this.context.getGodotPath()) {
+                    return createErrorResponse('Could not find a valid Godot executable path');
+                }
+            }
+            // Check if the project directory exists and contains a project.godot file
+            const projectFile = join(args.projectPath, 'project.godot');
+            if (!existsSync(projectFile)) {
+                return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+            }
+            // Get Godot version to check if UIDs are supported
+            const { stdout: versionOutput } = await execFileAsync(this.context.getGodotPath(), ['--version'], GODOT_VERSION_OPTIONS);
+            const version = versionOutput.trim();
+            if (!isGodot44OrLater(version)) {
+                return createErrorResponse(`UIDs are only supported in Godot 4.4 or later. Current version: ${version}`);
+            }
+            // The operation runs with --path at the project root, so res:// already
+            // covers it. Passing the absolute OS path as project_path used to make
+            // the operation scan res://<absolute-path> — nothing — and report
+            // success while generating no UIDs.
+            const result = await this.context.executeOperation('resave_resources', {}, args.projectPath);
+            const failure = this.headlessFailure('Failed to update project UIDs', result);
+            if (failure)
+                return failure;
+            const { stdout } = result;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Project UIDs updated successfully.\n\nOutput: ${stdout}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(`Failed to update project UIDs: ${errorMessage(error)}`);
+        }
+    }
+}