@beremaran/godot-agent-loop 1.0.0

package/build/interaction-server-installer.js

@@ -0,0 +1,234 @@
+import { copyFileSync, cpSync, existsSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+const DEFAULT_AUTOLOAD_NAME = 'McpInteractionServer';
+const DESTINATION_SCRIPT_NAME = 'mcp_interaction_server.gd';
+/** Domain scripts the server preloads from res://; a missing copy fails the autoload at parse time. */
+const RUNTIME_DIR_NAME = 'mcp_runtime';
+/**
+ * The engine merges override.cfg over project.godot at startup, so the autoload
+ * is declared in a file MCP creates and deletes and never in a file the user
+ * tracks. Proven against Godot 4.7 in the Phase 6a spike (see TODO.md).
+ */
+const OVERRIDE_FILE_NAME = 'override.cfg';
+const BLOCK_BEGIN = '; godot-agent-loop: begin interaction server (generated; removed automatically)';
+const BLOCK_END = '; godot-agent-loop: end interaction server';
+const LEGACY_BLOCK_BEGIN = '; godot-mcp: begin interaction server (generated; removed automatically)';
+const LEGACY_BLOCK_END = '; godot-mcp: end interaction server';
+/** Owns the filesystem changes needed to expose the MCP interaction server to a project. */
+export class InteractionServerInstaller {
+    options;
+    autoloadName;
+    logDebug;
+    constructor(options) {
+        this.options = options;
+        this.autoloadName = options.autoloadName ?? DEFAULT_AUTOLOAD_NAME;
+        this.logDebug = options.logDebug ?? (() => undefined);
+    }
+    /** Installs the server and returns whether MCP owns the resulting autoload entry. */
+    install(projectPath) {
+        // A crashed or SIGKILLed earlier server had no chance to clean up; start
+        // from a truthful state before deciding who owns the installation.
+        this.reapStaleInstallation(projectPath);
+        const projectFile = join(projectPath, 'project.godot');
+        const destinationScript = join(projectPath, DESTINATION_SCRIPT_NAME);
+        const existingContent = readFileSync(projectFile, 'utf8');
+        if (existingContent.includes(this.autoloadName)) {
+            if (!existsSync(destinationScript)) {
+                copyFileSync(this.options.sourceScriptPath, destinationScript);
+                this.logDebug(`Autoload present but script missing; restored ${destinationScript}`);
+            }
+            else {
+                this.logDebug('Interaction server autoload and script already present; leaving project untouched');
+            }
+            // The script is only useful with its domain scripts, so keep them in sync even
+            // when an existing installation is left in place.
+            this.syncRuntimeDir(projectPath);
+            return false;
+        }
+        copyFileSync(this.options.sourceScriptPath, destinationScript);
+        this.syncRuntimeDir(projectPath);
+        this.logDebug(`Copied interaction server script to ${destinationScript}`);
+        this.appendOverrideBlock(projectPath);
+        this.logDebug(`Declared ${this.autoloadName} autoload in ${OVERRIDE_FILE_NAME}; project.godot is untouched`);
+        return true;
+    }
+    /** Removes an MCP-owned installation. User-managed installations are left untouched. */
+    remove(projectPath, ownedByMcp) {
+        if (!ownedByMcp) {
+            this.logDebug('Interaction server was user-managed; skipping cleanup');
+            return;
+        }
+        if (this.stripOverrideBlock(projectPath)) {
+            this.logDebug(`Removed interaction server autoload from ${OVERRIDE_FILE_NAME}`);
+        }
+        this.removeInstalledArtifacts(projectPath);
+    }
+    /**
+     * Stateless cleanup of artifacts an earlier crashed or SIGKILLed server left
+     * behind. Ownership is re-derived from the artifacts themselves: a sentinel
+     * block in override.cfg is proof MCP wrote the installation, and a server
+     * script byte-identical to the shipped source covers a crash that happened
+     * before the override block was written. A user-managed installation — the
+     * autoload declared in project.godot — never loses its scripts.
+     *
+     * Two live MCP servers pointed at the same project cannot be distinguished
+     * from a crash by looking at the filesystem; concurrent same-project servers
+     * are unsupported (they would collide on the runtime port anyway).
+     *
+     * Returns the artifacts that were removed.
+     */
+    reapStaleInstallation(projectPath) {
+        const reaped = [];
+        const projectFile = join(projectPath, 'project.godot');
+        const userManaged = existsSync(projectFile) && readFileSync(projectFile, 'utf8').includes(this.autoloadName);
+        const hadOverrideBlock = this.stripOverrideBlock(projectPath);
+        if (hadOverrideBlock)
+            reaped.push(join(projectPath, OVERRIDE_FILE_NAME));
+        if (!userManaged) {
+            const destinationScript = join(projectPath, DESTINATION_SCRIPT_NAME);
+            const scriptIsOurs = existsSync(destinationScript)
+                && (hadOverrideBlock || this.fileMatchesShippedSource(destinationScript));
+            if (scriptIsOurs) {
+                reaped.push(...this.removeInstalledArtifacts(projectPath));
+            }
+            else if (!existsSync(destinationScript) && this.runtimeDirLooksOwned(projectPath)) {
+                // A crash between deleting the script and deleting the domain scripts
+                // leaves an orphan mcp_runtime directory that is provably ours.
+                rmSync(join(projectPath, RUNTIME_DIR_NAME), { recursive: true, force: true });
+                reaped.push(join(projectPath, RUNTIME_DIR_NAME));
+            }
+        }
+        if (reaped.length > 0) {
+            this.logDebug(`Reaped stale interaction server artifacts: ${reaped.join(', ')}`);
+        }
+        return reaped;
+    }
+    /** Deletes the script, its .uid sidecar, and the domain scripts; returns what existed. */
+    removeInstalledArtifacts(projectPath) {
+        const removed = [];
+        const destinationScript = join(projectPath, DESTINATION_SCRIPT_NAME);
+        if (existsSync(destinationScript)) {
+            unlinkSync(destinationScript);
+            removed.push(destinationScript);
+            this.logDebug('Deleted interaction server script from project');
+        }
+        const uidFile = `${destinationScript}.uid`;
+        if (existsSync(uidFile)) {
+            unlinkSync(uidFile);
+            removed.push(uidFile);
+            this.logDebug('Deleted interaction server .uid file');
+        }
+        const runtimeDir = join(projectPath, RUNTIME_DIR_NAME);
+        if (existsSync(runtimeDir)) {
+            // Removes the domain scripts and any .uid files Godot generated beside them.
+            rmSync(runtimeDir, { recursive: true, force: true });
+            removed.push(runtimeDir);
+            this.logDebug('Deleted interaction server domain scripts from project');
+        }
+        return removed;
+    }
+    /** Appends the sentinel-delimited autoload block, preserving any user-owned override.cfg content. */
+    appendOverrideBlock(projectPath) {
+        const overrideFile = join(projectPath, OVERRIDE_FILE_NAME);
+        const block = [
+            BLOCK_BEGIN,
+            '[autoload]',
+            `${this.autoloadName}="*res://${DESTINATION_SCRIPT_NAME}"`,
+            BLOCK_END,
+            '',
+        ].join('\n');
+        if (!existsSync(overrideFile)) {
+            writeFileSync(overrideFile, block, 'utf8');
+            return;
+        }
+        const current = readFileSync(overrideFile, 'utf8');
+        // If the user file lacks a trailing newline one is added and survives
+        // removal; a benign normalization, and the only byte the strip cannot
+        // attribute. MCP-created files round-trip byte-identically.
+        writeFileSync(overrideFile, current.endsWith('\n') || current === '' ? current + block : `${current}\n${block}`, 'utf8');
+    }
+    /**
+     * Removes the sentinel block from override.cfg. Deletes the file when
+     * nothing else is in it, so a project that had no override.cfg gets none
+     * back. Returns whether a block was found.
+     */
+    stripOverrideBlock(projectPath) {
+        const overrideFile = join(projectPath, OVERRIDE_FILE_NAME);
+        if (!existsSync(overrideFile))
+            return false;
+        const content = readFileSync(overrideFile, 'utf8');
+        const currentBegin = content.indexOf(BLOCK_BEGIN);
+        const legacyBegin = content.indexOf(LEGACY_BLOCK_BEGIN);
+        const begin = currentBegin >= 0 ? currentBegin : legacyBegin;
+        if (begin < 0)
+            return false;
+        const endToken = currentBegin >= 0 ? BLOCK_END : LEGACY_BLOCK_END;
+        const endMarker = content.indexOf(endToken, begin);
+        const end = endMarker < 0 ? content.length : Math.min(endMarker + endToken.length + 1, content.length);
+        const stripped = content.slice(0, begin) + content.slice(end);
+        if (stripped.trim() === '') {
+            unlinkSync(overrideFile);
+        }
+        else {
+            writeFileSync(overrideFile, stripped, 'utf8');
+        }
+        return true;
+    }
+    /** Whether the installed server script is byte-identical to the shipped source. */
+    fileMatchesShippedSource(installedPath) {
+        try {
+            return readFileSync(installedPath).equals(readFileSync(this.options.sourceScriptPath));
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Whether every file in the project's mcp_runtime directory is either a
+     * Godot-generated .uid sidecar or byte-identical to the shipped domain
+     * script of the same name. Anything else means the directory is not ours.
+     */
+    runtimeDirLooksOwned(projectPath) {
+        const installedDir = join(projectPath, RUNTIME_DIR_NAME);
+        if (!existsSync(installedDir))
+            return false;
+        const sourceDir = join(dirname(this.options.sourceScriptPath), RUNTIME_DIR_NAME);
+        const entries = readdirSync(installedDir, { recursive: true, encoding: 'utf8' });
+        for (const entry of entries) {
+            if (entry.endsWith('.uid'))
+                continue;
+            const installed = join(installedDir, entry);
+            const shipped = join(sourceDir, entry);
+            try {
+                if (readFileSync(installed).equals(readFileSync(shipped)))
+                    continue;
+            }
+            catch {
+                // Directories throw EISDIR on both sides; a file missing from the
+                // shipped tree throws ENOENT and means the directory is not ours.
+                if (isDirectory(installed) && isDirectory(shipped))
+                    continue;
+            }
+            return false;
+        }
+        return true;
+    }
+    /** Copies the domain scripts the installed server preloads, overwriting stale copies. */
+    syncRuntimeDir(projectPath) {
+        const source = join(dirname(this.options.sourceScriptPath), RUNTIME_DIR_NAME);
+        if (!existsSync(source)) {
+            this.logDebug(`No ${RUNTIME_DIR_NAME} directory beside the source script; nothing to sync`);
+            return;
+        }
+        cpSync(source, join(projectPath, RUNTIME_DIR_NAME), { recursive: true });
+        this.logDebug(`Synced ${RUNTIME_DIR_NAME} domain scripts into ${projectPath}`);
+    }
+}
+function isDirectory(path) {
+    try {
+        return readdirSync(path) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}

package/build/opencode-setup.js

@@ -0,0 +1,199 @@
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { applyEdits, modify, parse } from 'jsonc-parser';
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const pluginRoot = join(packageRoot, 'agent-plugin');
+function loadAdapter() {
+    return JSON.parse(readFileSync(join(pluginRoot, 'adapter-manifest.json'), 'utf8'));
+}
+function stable(value) {
+    return JSON.stringify(value);
+}
+function directoryHash(path) {
+    const hash = createHash('sha256');
+    const visit = (dir) => {
+        for (const name of readdirSync(dir).sort()) {
+            const fullPath = join(dir, name);
+            const info = statSync(fullPath);
+            if (info.isDirectory())
+                visit(fullPath);
+            else {
+                hash.update(relative(path, fullPath));
+                hash.update(readFileSync(fullPath));
+            }
+        }
+    };
+    visit(path);
+    return hash.digest('hex');
+}
+function readOwnership(path) {
+    if (!existsSync(path))
+        return undefined;
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+function parseConfig(source, path) {
+    const errors = [];
+    const value = parse(source, errors, { allowTrailingComma: true, disallowComments: false });
+    if (errors.length > 0 || !value || Array.isArray(value)) {
+        throw new Error(`Cannot safely update ${path}: invalid JSON/JSONC configuration`);
+    }
+    return value;
+}
+function configSource(path) {
+    return existsSync(path) ? readFileSync(path, 'utf8') : '{\n  "$schema": "https://opencode.ai/config.json"\n}\n';
+}
+function editConfig(source, name, value) {
+    const edits = modify(source, ['mcp', name], value, {
+        formattingOptions: { insertSpaces: true, tabSize: 2, eol: '\n' },
+    });
+    return applyEdits(source, edits);
+}
+function defaultProjectConfig(cwd) {
+    const jsonc = join(cwd, 'opencode.jsonc');
+    const json = join(cwd, 'opencode.json');
+    return existsSync(jsonc) ? jsonc : json;
+}
+export function setupOpenCode(options = {}) {
+    const adapter = loadAdapter();
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const home = resolve(options.home ?? homedir());
+    const scope = options.scope ?? 'project';
+    const configPath = resolve(options.configPath ?? (scope === 'user' ? join(home, '.config', 'opencode', 'opencode.json') : defaultProjectConfig(cwd)));
+    const agentsRoot = scope === 'user' ? join(home, '.agents') : join(cwd, '.agents');
+    const skillsRoot = join(agentsRoot, 'skills');
+    const ownershipPath = join(agentsRoot, '.godot-agent-loop-setup.json');
+    const ownership = readOwnership(ownershipPath);
+    const expectedEntry = {
+        type: 'local',
+        command: adapter.mcp.command,
+        enabled: true,
+        environment: adapter.mcp.environment,
+    };
+    const source = configSource(configPath);
+    const config = parseConfig(source, configPath);
+    const currentEntry = config.mcp?.[adapter.name];
+    const changes = [];
+    const warnings = [];
+    const skillOperations = [];
+    let nextConfig = source;
+    if (options.uninstall) {
+        const ownedEntry = ownership?.configEntry ?? expectedEntry;
+        if (currentEntry !== undefined && stable(currentEntry) === stable(ownedEntry)) {
+            nextConfig = editConfig(source, adapter.name, undefined);
+            changes.push(`remove MCP entry ${adapter.name} from ${configPath}`);
+        }
+        else if (currentEntry !== undefined) {
+            warnings.push(`preserve modified MCP entry ${adapter.name} in ${configPath}`);
+        }
+    }
+    else if (currentEntry === undefined) {
+        nextConfig = editConfig(source, adapter.name, expectedEntry);
+        changes.push(`add MCP entry ${adapter.name} to ${configPath}`);
+    }
+    else if (stable(currentEntry) !== stable(expectedEntry)) {
+        const previouslyOwned = ownership && stable(currentEntry) === stable(ownership.configEntry);
+        if (!previouslyOwned)
+            throw new Error(`Refusing to overwrite existing OpenCode MCP entry: ${adapter.name}`);
+        nextConfig = editConfig(source, adapter.name, expectedEntry);
+        changes.push(`update MCP entry ${adapter.name} in ${configPath}`);
+    }
+    const nextSkills = {};
+    for (const declared of adapter.skills) {
+        const sourceSkill = join(pluginRoot, 'skills', declared.name);
+        const targetSkill = join(skillsRoot, declared.name);
+        const sourceHash = directoryHash(sourceSkill);
+        nextSkills[declared.name] = sourceHash;
+        if (options.uninstall) {
+            if (!existsSync(targetSkill))
+                continue;
+            const installedHash = directoryHash(targetSkill);
+            if (ownership?.skills[declared.name] === installedHash) {
+                changes.push(`remove owned skill ${targetSkill}`);
+                skillOperations.push({ action: 'remove', target: targetSkill });
+            }
+            else {
+                warnings.push(`preserve modified or unowned skill ${targetSkill}`);
+            }
+            continue;
+        }
+        if (!existsSync(targetSkill)) {
+            changes.push(`install skill ${targetSkill}`);
+            skillOperations.push({ action: 'install', source: sourceSkill, target: targetSkill });
+            continue;
+        }
+        const installedHash = directoryHash(targetSkill);
+        if (installedHash === sourceHash)
+            continue;
+        if (ownership?.skills[declared.name] !== installedHash) {
+            throw new Error(`Refusing to overwrite modified or unowned skill: ${targetSkill}`);
+        }
+        changes.push(`update owned skill ${targetSkill}`);
+        skillOperations.push({ action: 'update', source: sourceSkill, target: targetSkill });
+    }
+    if (options.write) {
+        for (const operation of skillOperations) {
+            if (operation.action === 'remove' || operation.action === 'update') {
+                rmSync(operation.target, { recursive: true });
+            }
+            if (operation.source) {
+                mkdirSync(dirname(operation.target), { recursive: true });
+                cpSync(operation.source, operation.target, { recursive: true });
+            }
+        }
+        if (nextConfig !== source) {
+            mkdirSync(dirname(configPath), { recursive: true });
+            writeFileSync(configPath, nextConfig);
+        }
+        if (options.uninstall) {
+            if (existsSync(ownershipPath))
+                rmSync(ownershipPath);
+        }
+        else {
+            mkdirSync(dirname(ownershipPath), { recursive: true });
+            const record = {
+                version: 1,
+                configPath,
+                configEntry: expectedEntry,
+                skills: nextSkills,
+            };
+            writeFileSync(ownershipPath, `${JSON.stringify(record, null, 2)}\n`);
+        }
+    }
+    return {
+        action: options.uninstall ? 'uninstall' : 'install',
+        applied: options.write === true,
+        configPath,
+        skillsRoot,
+        changes,
+        warnings,
+    };
+}
+export async function runOpenCodeSetup(args) {
+    const value = (flag) => {
+        const index = args.indexOf(flag);
+        return index >= 0 ? args[index + 1] : undefined;
+    };
+    const scope = value('--scope');
+    if (scope !== undefined && scope !== 'project' && scope !== 'user') {
+        throw new Error('--scope must be project or user');
+    }
+    const result = setupOpenCode({
+        scope,
+        configPath: value('--config'),
+        write: args.includes('--write') || args.includes('--yes'),
+        uninstall: args.includes('uninstall') || args.includes('--uninstall'),
+    });
+    const mode = result.applied ? 'Applied' : 'Preview';
+    console.log(`${mode}: OpenCode ${result.action}`);
+    console.log(`Config: ${result.configPath}`);
+    console.log(`Skills: ${result.skillsRoot}`);
+    for (const change of result.changes)
+        console.log(`  - ${change}`);
+    for (const warning of result.warnings)
+        console.log(`  ! ${warning}`);
+    if (!result.applied)
+        console.log('Run again with --write to apply this preview.');
+}

package/build/project-support.js

@@ -0,0 +1,219 @@
+import { execFile } from 'child_process';
+import { existsSync, readdirSync } from 'fs';
+import { basename, dirname, join, relative } from 'path';
+import { promisify } from 'util';
+import { fileURLToPath } from 'url';
+import { collectGdPaths, errorMessage, parseGodotScriptDiagnostics, } from './utils.js';
+import { GODOT_COMMAND_OPTIONS, GODOT_VERSION_OPTIONS } from './godot-subprocess.js';
+const execFileAsync = promisify(execFile);
+/**
+ * Filesystem and executable-backed support for project-oriented tools.
+ *
+ * Keeping this work outside GodotServer lets the server focus on lifecycle
+ * orchestration while project handlers share a single, testable service.
+ */
+export class ProjectSupport {
+    context;
+    validateScriptPath;
+    constructor(context, validateScriptPath = join(dirname(fileURLToPath(import.meta.url)), 'scripts', 'validate_script.gd')) {
+        this.context = context;
+        this.validateScriptPath = validateScriptPath;
+    }
+    findGodotProjects(directory, recursive) {
+        const projects = [];
+        try {
+            const projectFile = join(directory, 'project.godot');
+            if (existsSync(projectFile)) {
+                projects.push({
+                    path: directory,
+                    name: basename(directory),
+                });
+            }
+            const entries = readdirSync(directory, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory() || (recursive && entry.name.startsWith('.')))
+                    continue;
+                const subdirectory = join(directory, entry.name);
+                if (existsSync(join(subdirectory, 'project.godot'))) {
+                    projects.push({ path: subdirectory, name: entry.name });
+                }
+                else if (recursive) {
+                    projects.push(...this.findGodotProjects(subdirectory, true));
+                }
+            }
+        }
+        catch (error) {
+            this.context.logDebug(`Error searching directory ${directory}: ${error}`);
+        }
+        return projects;
+    }
+    async getProjectStructureAsync(projectPath) {
+        const structure = {
+            scenes: 0,
+            scripts: 0,
+            assets: 0,
+            other: 0,
+        };
+        try {
+            const scanDirectory = (currentPath) => {
+                const entries = readdirSync(currentPath, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.name.startsWith('.'))
+                        continue;
+                    const entryPath = join(currentPath, entry.name);
+                    if (entry.isDirectory()) {
+                        scanDirectory(entryPath);
+                    }
+                    else if (entry.isFile()) {
+                        const extension = entry.name.split('.').pop()?.toLowerCase();
+                        if (extension === 'tscn') {
+                            structure.scenes++;
+                        }
+                        else if (extension === 'gd' || extension === 'gdscript' || extension === 'cs') {
+                            structure.scripts++;
+                        }
+                        else if (['png', 'jpg', 'jpeg', 'webp', 'svg', 'ttf', 'wav', 'mp3', 'ogg'].includes(extension || '')) {
+                            structure.assets++;
+                        }
+                        else {
+                            structure.other++;
+                        }
+                    }
+                }
+            };
+            scanDirectory(projectPath);
+            return structure;
+        }
+        catch (error) {
+            this.context.logDebug(`Error getting project structure asynchronously: ${error}`);
+            return {
+                error: 'Failed to get project structure',
+                scenes: 0,
+                scripts: 0,
+                assets: 0,
+                other: 0,
+            };
+        }
+    }
+    isDotnetProject(projectPath) {
+        try {
+            return readdirSync(projectPath).some(entry => entry.toLowerCase().endsWith('.csproj'));
+        }
+        catch {
+            return false;
+        }
+    }
+    async detectGodotNetSdkVersion() {
+        try {
+            const godotPath = await this.requireGodotPath();
+            if (!godotPath)
+                return null;
+            const { stdout } = await execFileAsync(godotPath, ['--version'], GODOT_VERSION_OPTIONS);
+            const match = /^(\d+)\.(\d+)(?:\.\d+)?\.stable\b/.exec(stdout.trim());
+            return match ? `${match[1]}.${match[2]}.0` : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    keyNameToScancode(key) {
+        const map = {
+            'A': 65, 'B': 66, 'C': 67, 'D': 68, 'E': 69, 'F': 70, 'G': 71, 'H': 72,
+            'I': 73, 'J': 74, 'K': 75, 'L': 76, 'M': 77, 'N': 78, 'O': 79, 'P': 80,
+            'Q': 81, 'R': 82, 'S': 83, 'T': 84, 'U': 85, 'V': 86, 'W': 87, 'X': 88,
+            'Y': 89, 'Z': 90, 'SPACE': 32, 'ENTER': 16777221, 'ESCAPE': 16777217,
+            'TAB': 16777218, 'BACKSPACE': 16777220, 'UP': 16777232, 'DOWN': 16777234,
+            'LEFT': 16777231, 'RIGHT': 16777233, 'SHIFT': 16777237, 'CTRL': 16777238,
+            'ALT': 16777240, 'F1': 16777244, 'F2': 16777245, 'F3': 16777246,
+            'F4': 16777247, 'F5': 16777248, 'F6': 16777249, 'F7': 16777250,
+            'F8': 16777251, 'F9': 16777252, 'F10': 16777253, 'F11': 16777254,
+            'F12': 16777255,
+        };
+        const upper = key.toUpperCase();
+        return map[upper] || (key.length === 1 ? key.charCodeAt(0) : 0);
+    }
+    async runGdScriptCheck(projectPath, scriptFull) {
+        const godotPath = await this.requireGodotPath();
+        if (!godotPath) {
+            return { completed: false, errors: [], error: 'Could not find a valid Godot executable path' };
+        }
+        let output;
+        let failed = false;
+        const scriptResourcePath = `res://${relative(projectPath, scriptFull).replace(/\\/g, '/')}`;
+        try {
+            // `--check-only --script <target>` compiles too early for project autoload
+            // globals to be registered. The SceneTree validator loads the target from
+            // `_initialize()`, after autoload bootstrap, while CACHE_MODE_IGNORE keeps
+            // every check a fresh parse of the current file contents.
+            const { stdout, stderr } = await execFileAsync(godotPath, ['--headless', '--path', projectPath, '--script', this.validateScriptPath, scriptResourcePath], GODOT_COMMAND_OPTIONS);
+            output = `${stdout ?? ''}${stderr ?? ''}`;
+        }
+        catch (error) {
+            failed = true;
+            const execError = error;
+            output = `${execError.stdout ?? ''}${execError.stderr ?? ''}`;
+            const aborted = execError.killed === true || execError.signal != null ||
+                execError.code === 'ETIMEDOUT' || execError.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER';
+            if (aborted)
+                return { completed: false, errors: [], error: 'Godot timed out or produced too much output' };
+            if (!output)
+                return { completed: false, errors: [], error: errorMessage(error) };
+        }
+        const errors = parseGodotScriptDiagnostics(output);
+        if (errors.length === 0 && failed) {
+            const tail = output.trim().split(/\r?\n/).slice(-6).join(' ');
+            return { completed: false, errors: [], error: `Godot exited with an error: ${tail}` };
+        }
+        return { completed: true, errors };
+    }
+    async listChangedGdFiles(projectPath) {
+        const git = (gitArgs) => execFileAsync('git', ['-c', 'core.quotepath=false', '-C', projectPath, ...gitArgs], { timeout: 15000, maxBuffer: 16 * 1024 * 1024 });
+        try {
+            await git(['rev-parse', '--is-inside-work-tree']);
+        }
+        catch {
+            return { error: 'Not a git repository (or git is unavailable). Use scope: "all" or pass scriptPaths.' };
+        }
+        try {
+            const outputs = await Promise.all([
+                git(['diff', '--name-only', '--relative']),
+                git(['diff', '--name-only', '--relative', '--cached']),
+                git(['ls-files', '--others', '--exclude-standard']),
+            ]);
+            return { files: collectGdPaths(outputs.map(output => output.stdout ?? '')) };
+        }
+        catch (error) {
+            return { error: `Failed to list changed files: ${errorMessage(error)}` };
+        }
+    }
+    listAllGdFiles(projectPath) {
+        const results = [];
+        const skipDirectories = new Set(['.godot', '.git', 'node_modules', '.import']);
+        const walk = (directory) => {
+            let entries;
+            try {
+                entries = readdirSync(directory, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    if (skipDirectories.has(entry.name) || entry.name.startsWith('.'))
+                        continue;
+                    walk(join(directory, entry.name));
+                }
+                else if (entry.isFile() && /\.gd$/i.test(entry.name)) {
+                    results.push(relative(projectPath, join(directory, entry.name)).replace(/\\/g, '/'));
+                }
+            }
+        };
+        walk(projectPath);
+        return results;
+    }
+    async requireGodotPath() {
+        if (!this.context.getGodotPath())
+            await this.context.detectGodotPath();
+        return this.context.getGodotPath();
+    }
+}