godot-cli 0.1.0

package/dist/utils/godot-editor.js

@@ -0,0 +1,184 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { homedir, platform } from 'os';
+/**
+ * Environment variables that, when set, point directly at a Godot editor
+ * binary. Checked before PATH and common install dirs. `GODOT_BIN` is the
+ * conventional name; `GODOT4_BIN` is honored for setups that pin a Godot 4
+ * binary alongside a legacy Godot 3 one.
+ */
+export const GODOT_BIN_ENV_VARS = ['GODOT_BIN', 'GODOT4_BIN'];
+/**
+ * Candidate executable base-names searched on `PATH`. The Windows mono build
+ * uses a `_console.exe` companion that surfaces stdout; the mono editor binary
+ * itself ships under several historical names, so we probe a small set.
+ */
+function pathCandidateNames(os) {
+    if (os === 'win32') {
+        // Prefer the mono build; the `_console` variant surfaces GD.Print/stdout.
+        return [
+            'godot_mono.exe',
+            'godot.exe',
+            'Godot_mono.exe',
+            'Godot.exe',
+        ];
+    }
+    if (os === 'darwin') {
+        return ['godot', 'godot_mono', 'Godot'];
+    }
+    return ['godot', 'godot_mono', 'Godot'];
+}
+/**
+ * Per-OS common install directories to scan for a Godot editor binary when
+ * neither an env override nor a PATH hit resolves one.
+ *   - Windows: prefer the mono build under Program Files / common download dirs.
+ *   - macOS: the `.app` bundle's inner `Contents/MacOS/Godot` binary.
+ *   - Linux: extracted binaries under common app dirs.
+ */
+function commonInstallCandidates(os) {
+    const home = homedir();
+    const candidates = [];
+    if (os === 'win32') {
+        const programFiles = process.env['PROGRAMFILES'] ?? 'C:\\Program Files';
+        const localAppData = process.env['LOCALAPPDATA'] ?? path.join(home, 'AppData', 'Local');
+        for (const root of [
+            path.join(programFiles, 'Godot'),
+            path.join(localAppData, 'Programs', 'Godot'),
+            path.join(home, 'Downloads'),
+        ]) {
+            // Prefer the mono console build (surfaces stdout), then the plain mono build.
+            candidates.push(path.join(root, 'Godot_mono.exe'));
+            candidates.push(path.join(root, 'Godot.exe'));
+        }
+        return candidates;
+    }
+    if (os === 'darwin') {
+        for (const app of [
+            '/Applications/Godot_mono.app',
+            '/Applications/Godot.app',
+            path.join(home, 'Applications', 'Godot_mono.app'),
+            path.join(home, 'Applications', 'Godot.app'),
+        ]) {
+            candidates.push(path.join(app, 'Contents', 'MacOS', 'Godot'));
+        }
+        return candidates;
+    }
+    // linux + others
+    for (const dir of [
+        '/usr/local/bin',
+        '/usr/bin',
+        path.join(home, '.local', 'bin'),
+        path.join(home, 'Applications'),
+        path.join(home, 'bin'),
+    ]) {
+        candidates.push(path.join(dir, 'godot'));
+        candidates.push(path.join(dir, 'godot_mono'));
+        candidates.push(path.join(dir, 'Godot'));
+    }
+    return candidates;
+}
+/**
+ * Search the directories on `PATH` for the first matching Godot binary name.
+ * Pure filesystem lookup — never spawns anything.
+ */
+function findOnPath(os) {
+    const pathEnv = process.env['PATH'] ?? '';
+    if (!pathEnv)
+        return null;
+    const sep = os === 'win32' ? ';' : ':';
+    const dirs = pathEnv.split(sep).filter((d) => d.length > 0);
+    const names = pathCandidateNames(os);
+    for (const dir of dirs) {
+        for (const name of names) {
+            const candidate = path.join(dir, name);
+            if (existsAsFile(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    return null;
+}
+function existsAsFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the Godot editor binary path.
+ *
+ * Resolution order (first hit wins):
+ *   1. An explicit `editorPath` argument (validated to be an existing file).
+ *   2. `GODOT_BIN` / `GODOT4_BIN` environment variables.
+ *   3. The first matching Godot binary on `PATH`.
+ *   4. Per-OS common install directories (Windows prefers the mono build;
+ *      macOS resolves the `.app/Contents/MacOS` binary; Linux scans common
+ *      extracted-binary locations).
+ *
+ * Returns the absolute path, or `null` when no Godot binary can be located.
+ * Pure / no spawn — exported for unit tests (the `os`/env are injectable via
+ * the running process; tests stub `fs` + env).
+ */
+export function findGodotBinary(editorPath, os = platform()) {
+    // 1. Explicit path
+    if (editorPath !== undefined) {
+        const trimmed = editorPath.trim();
+        if (trimmed.length === 0)
+            return null;
+        const resolved = path.resolve(trimmed);
+        return existsAsFile(resolved) ? resolved : null;
+    }
+    // 2. Env overrides
+    for (const envVar of GODOT_BIN_ENV_VARS) {
+        const raw = process.env[envVar];
+        if (raw && raw.trim().length > 0) {
+            const resolved = path.resolve(raw.trim());
+            if (existsAsFile(resolved)) {
+                return resolved;
+            }
+        }
+    }
+    // 3. PATH
+    const onPath = findOnPath(os);
+    if (onPath)
+        return onPath;
+    // 4. Common install dirs
+    for (const candidate of commonInstallCandidates(os)) {
+        if (existsAsFile(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Spawn the Godot editor binary opening the given project, optionally with
+ * `GODOT_MCP_*` connection environment variables. Mirrors the Unity CLI's
+ * `launchEditor`: spawns detached, with `stdio: 'ignore'`, and `unref()`s so
+ * the parent process can exit without waiting on the editor.
+ *
+ * Godot's editor-open invocation is `--editor --path <project>` (the
+ * `--editor` flag forces the project to open in the editor rather than run).
+ *
+ * Library-safe (no process.exit, no stdout/stderr writes — observability is
+ * the caller's responsibility via the optional callbacks).
+ */
+export function launchEditor(editorPath, projectPath, env, callbacks) {
+    const args = ['--editor', '--path', path.resolve(projectPath)];
+    const child = spawn(editorPath, args, {
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env, ...env },
+    });
+    child.on('spawn', () => {
+        callbacks?.onSpawn?.(child.pid);
+    });
+    child.on('error', (err) => {
+        callbacks?.onError?.(err);
+    });
+    child.unref();
+    return child;
+}
+//# sourceMappingURL=godot-editor.js.map

package/dist/utils/godot-editor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"godot-editor.js","sourceRoot":"","sources":["../../src/utils/godot-editor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,WAAW,EAAE,YAAY,CAAU,CAAC;AAEvE;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,EAAmB;IAC7C,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;QACnB,0EAA0E;QAC1E,OAAO;YACL,gBAAgB;YAChB,WAAW;YACX,gBAAgB;YAChB,WAAW;SACZ,CAAC;IACJ,CAAC;IACD,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;QACpB,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,SAAS,uBAAuB,CAAC,EAAmB;IAClD,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;QACnB,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,mBAAmB,CAAC;QACxE,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QACxF,KAAK,MAAM,IAAI,IAAI;YACjB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC;YAChC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,EAAE,OAAO,CAAC;YAC5C,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC;SAC7B,EAAE,CAAC;YACF,8EAA8E;YAC9E,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC;YACnD,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;QACpB,KAAK,MAAM,GAAG,IAAI;YAChB,8BAA8B;YAC9B,yBAAyB;YACzB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,gBAAgB,CAAC;YACjD,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,WAAW,CAAC;SAC7C,EAAE,CAAC;YACF,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,iBAAiB;IACjB,KAAK,MAAM,GAAG,IAAI;QAChB,gBAAgB;QAChB,UAAU;QACV,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC;KACvB,EAAE,CAAC;QACF,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;QACzC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC;QAC9C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAAC,EAAmB;IACrC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC1C,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,GAAG,GAAG,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IACvC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACvC,IAAI,YAAY,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC5B,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,YAAY,CAAC,CAAS;IAC7B,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAC7B,UAAmB,EACnB,KAAsB,QAAQ,EAAE;IAEhC,mBAAmB;IACnB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;QAClC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,CAAC;IAED,mBAAmB;IACnB,KAAK,MAAM,MAAM,IAAI,kBAAkB,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;YAC1C,IAAI,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC3B,OAAO,QAAQ,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IAED,UAAU;IACV,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;IAC9B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,yBAAyB;IACzB,KAAK,MAAM,SAAS,IAAI,uBAAuB,CAAC,EAAE,CAAC,EAAE,CAAC;QACpD,IAAI,YAAY,CAAC,SAAS,CAAC,EAAE,CAAC;YAC5B,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AASD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,UAAkB,EAClB,WAAmB,EACnB,GAA4B,EAC5B,SAAiC;IAEjC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IAE/D,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,EAAE,IAAI,EAAE;QACpC,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,QAAQ;QACf,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE;KAChC,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACrB,SAAS,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;QACxB,SAAS,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/godot-process.d.ts

@@ -0,0 +1,10 @@
+export interface GodotProcess {
+    pid: number;
+    projectPath: string;
+    commandLine: string;
+}
+/**
+ * Check if a Godot editor process is running with the given project path.
+ * Returns process info if found, null otherwise.
+ */
+export declare function findGodotProcess(projectPath: string): GodotProcess | null;

package/dist/utils/godot-process.js

@@ -0,0 +1,93 @@
+import { execFileSync, execSync } from 'child_process';
+import { platform } from 'os';
+import * as path from 'path';
+import { verbose } from './ui.js';
+/**
+ * Extract the `--path <project>` value from a Godot editor command line.
+ * Quote-aware: a double-quoted path (Windows CIM `CommandLine` shape for paths
+ * with spaces) is consumed whole, otherwise the first whitespace-delimited
+ * token is used. Returns the resolved absolute path, or null when absent.
+ */
+function extractProjectPath(commandLine) {
+    const quoted = commandLine.match(/--path\s+"([^"]+)"/i);
+    if (quoted)
+        return path.resolve(quoted[1].trim());
+    const unquoted = commandLine.match(/--path\s+(\S+)/i);
+    if (unquoted)
+        return path.resolve(unquoted[1].trim());
+    return null;
+}
+/**
+ * Check if a Godot editor process is running with the given project path.
+ * Returns process info if found, null otherwise.
+ */
+export function findGodotProcess(projectPath) {
+    const isWindows = platform() === 'win32';
+    const resolvedTarget = path.resolve(projectPath);
+    const normalizedTarget = isWindows ? resolvedTarget.toLowerCase() : resolvedTarget;
+    const processes = listGodotProcesses();
+    for (const proc of processes) {
+        const normalizedProc = isWindows ? proc.projectPath.toLowerCase() : proc.projectPath;
+        if (normalizedProc === normalizedTarget) {
+            verbose(`Found Godot process PID ${proc.pid} with project: ${proc.projectPath}`);
+            return proc;
+        }
+    }
+    verbose(`No Godot process found for project: ${projectPath}`);
+    return null;
+}
+/**
+ * List all running Godot editor processes with their project paths. Matches
+ * any process whose name contains "godot" (covers `Godot.exe`, `Godot_mono.exe`,
+ * `godot_mono_console.exe`, the macOS `Godot` binary, and Linux extracted
+ * binaries) and that carries a `--path` argument.
+ */
+function listGodotProcesses() {
+    const os = platform();
+    const results = [];
+    try {
+        if (os === 'win32') {
+            const psCommand = "Get-CimInstance Win32_Process -Filter \"Name LIKE '%godot%'\" | Select-Object ProcessId,CommandLine | ForEach-Object { $_.ProcessId.ToString() + '|||' + $_.CommandLine }";
+            const output = execFileSync('powershell.exe', ['-NoProfile', '-Command', psCommand], { encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] });
+            const lines = output.split('\n').filter((l) => l.trim().length > 0);
+            for (const line of lines) {
+                const sepIdx = line.indexOf('|||');
+                if (sepIdx === -1)
+                    continue;
+                const pid = parseInt(line.substring(0, sepIdx).trim(), 10);
+                const commandLine = line.substring(sepIdx + 3).trim();
+                if (!Number.isFinite(pid) || pid === 0)
+                    continue;
+                if (!/--path/i.test(commandLine))
+                    continue;
+                const projectPath = extractProjectPath(commandLine);
+                if (projectPath) {
+                    results.push({ pid, projectPath, commandLine });
+                }
+            }
+        }
+        else {
+            const output = execSync("ps -eo pid,args | grep -i '[g]odot' || true", { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] });
+            const lines = output.split('\n').filter((l) => l.trim().length > 0);
+            for (const line of lines) {
+                const match = line.trim().match(/^(\d+)\s+(.*)$/);
+                if (!match)
+                    continue;
+                const pid = parseInt(match[1], 10);
+                const commandLine = match[2];
+                if (!/--path/i.test(commandLine))
+                    continue;
+                const projectPath = extractProjectPath(commandLine);
+                if (projectPath) {
+                    results.push({ pid, projectPath, commandLine });
+                }
+            }
+        }
+    }
+    catch (err) {
+        verbose(`Failed to list Godot processes: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    verbose(`Found ${results.length} Godot process(es)`);
+    return results;
+}
+//# sourceMappingURL=godot-process.js.map

package/dist/utils/godot-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"godot-process.js","sourceRoot":"","sources":["../../src/utils/godot-process.ts"],"names":[],"mappings":"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"}

package/dist/utils/godot-shutdown.d.ts

@@ -0,0 +1,16 @@
+export type SupportedPlatform = 'win32' | 'darwin' | 'linux';
+/** True when the process with the given PID is currently alive. */
+export declare function isProcessAlive(pid: number, os?: SupportedPlatform): boolean;
+/**
+ * Send a graceful-shutdown request. On POSIX this is SIGTERM; on Windows we use
+ * `taskkill` WITHOUT `/F` (a polite close request the OS routes to the process).
+ * Returns true when the signal was delivered without error.
+ */
+export declare function sendGracefulShutdown(pid: number, os?: SupportedPlatform): boolean;
+/** Hard-kill the process. SIGKILL on POSIX; `taskkill /F` on Windows. */
+export declare function sendForceKill(pid: number, os?: SupportedPlatform): boolean;
+/**
+ * Poll for the process to exit, up to `timeoutMs`. Resolves true when the
+ * process is gone, false on timeout.
+ */
+export declare function waitForExit(pid: number, timeoutMs: number, os?: SupportedPlatform): Promise<boolean>;

package/dist/utils/godot-shutdown.js

@@ -0,0 +1,67 @@
+import { execFileSync } from 'child_process';
+import { platform } from 'os';
+/** True when the process with the given PID is currently alive. */
+export function isProcessAlive(pid, os = platform()) {
+    try {
+        if (os === 'win32') {
+            const out = execFileSync('tasklist', ['/FI', `PID eq ${pid}`, '/NH'], {
+                encoding: 'utf-8',
+                timeout: 5000,
+            });
+            return out.includes(String(pid));
+        }
+        // POSIX: signal 0 probes existence without delivering a signal.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Send a graceful-shutdown request. On POSIX this is SIGTERM; on Windows we use
+ * `taskkill` WITHOUT `/F` (a polite close request the OS routes to the process).
+ * Returns true when the signal was delivered without error.
+ */
+export function sendGracefulShutdown(pid, os = platform()) {
+    try {
+        if (os === 'win32') {
+            execFileSync('taskkill', ['/PID', String(pid)], { encoding: 'utf-8', timeout: 5000, stdio: 'pipe' });
+            return true;
+        }
+        process.kill(pid, 'SIGTERM');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Hard-kill the process. SIGKILL on POSIX; `taskkill /F` on Windows. */
+export function sendForceKill(pid, os = platform()) {
+    try {
+        if (os === 'win32') {
+            execFileSync('taskkill', ['/PID', String(pid), '/F'], { encoding: 'utf-8', timeout: 5000, stdio: 'pipe' });
+            return true;
+        }
+        process.kill(pid, 'SIGKILL');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Poll for the process to exit, up to `timeoutMs`. Resolves true when the
+ * process is gone, false on timeout.
+ */
+export async function waitForExit(pid, timeoutMs, os = platform()) {
+    const start = Date.now();
+    const interval = 250;
+    while (Date.now() - start < timeoutMs) {
+        if (!isProcessAlive(pid, os))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    return !isProcessAlive(pid, os);
+}
+//# sourceMappingURL=godot-shutdown.js.map

package/dist/utils/godot-shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"godot-shutdown.js","sourceRoot":"","sources":["../../src/utils/godot-shutdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAI9B,mEAAmE;AACnE,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,KAAwB,QAAQ,EAAuB;IACjG,IAAI,CAAC;QACH,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;YACnB,MAAM,GAAG,GAAG,YAAY,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,GAAG,EAAE,EAAE,KAAK,CAAC,EAAE;gBACpE,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,IAAI;aACd,CAAC,CAAC;YACH,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACnC,CAAC;QACD,gEAAgE;QAChE,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAW,EACX,KAAwB,QAAQ,EAAuB;IAEvD,IAAI,CAAC;QACH,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;YACnB,YAAY,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;YACrG,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAC3B,GAAW,EACX,KAAwB,QAAQ,EAAuB;IAEvD,IAAI,CAAC;QACH,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;YACnB,YAAY,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;YAC3G,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAAW,EACX,SAAiB,EACjB,KAAwB,QAAQ,EAAuB;IAEvD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,QAAQ,GAAG,GAAG,CAAC;IACrB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,SAAS,EAAE,CAAC;QACtC,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAClC,CAAC"}

package/dist/utils/input.d.ts

@@ -0,0 +1,13 @@
+export interface InputOptions {
+    input?: string;
+    inputFile?: string;
+}
+/**
+ * Parse tool input from --input, --input-file, or stdin.
+ *
+ * - `--input-file -` or `--input-file /dev/stdin` reads from stdin (cross-platform).
+ * - `--input-file <path>` reads from a file.
+ * - `--input <json>` parses inline JSON.
+ * - Falls back to `{}` if nothing provided.
+ */
+export declare function parseInput(options: InputOptions): string;

package/dist/utils/input.js

@@ -0,0 +1,72 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as ui from './ui.js';
+import { verbose } from './ui.js';
+import { parseJsonStrict, JsonParseError } from './json-parse.js';
+/**
+ * Parse tool input from --input, --input-file, or stdin.
+ *
+ * - `--input-file -` or `--input-file /dev/stdin` reads from stdin (cross-platform).
+ * - `--input-file <path>` reads from a file.
+ * - `--input <json>` parses inline JSON.
+ * - Falls back to `{}` if nothing provided.
+ */
+export function parseInput(options) {
+    if (options.inputFile) {
+        const isStdin = options.inputFile === '-' || options.inputFile === '/dev/stdin';
+        let content;
+        if (isStdin) {
+            verbose('Reading input from stdin...');
+            try {
+                content = fs.readFileSync(0, 'utf-8');
+            }
+            catch {
+                ui.error('Failed to read from stdin.');
+                process.exit(1);
+            }
+            if (!content.trim()) {
+                ui.error('No input received from stdin.');
+                process.exit(1);
+            }
+        }
+        else {
+            const filePath = path.resolve(options.inputFile);
+            if (!fs.existsSync(filePath)) {
+                ui.error(`Input file does not exist: ${filePath}`);
+                process.exit(1);
+            }
+            content = fs.readFileSync(filePath, 'utf-8');
+        }
+        try {
+            parseJsonStrict(content);
+        }
+        catch (err) {
+            const source = isStdin ? 'stdin' : options.inputFile;
+            if (err instanceof JsonParseError) {
+                ui.error(`--input-file content from '${source}' must be valid JSON\n${err.message}`);
+            }
+            else {
+                ui.error(`--input-file content from '${source}' must be valid JSON`);
+            }
+            process.exit(1);
+        }
+        return content;
+    }
+    if (options.input) {
+        try {
+            const result = parseJsonStrict(options.input);
+            return result.raw;
+        }
+        catch (err) {
+            if (err instanceof JsonParseError) {
+                ui.error(`--input must be valid JSON\n${err.message}`);
+            }
+            else {
+                ui.error('--input must be valid JSON');
+            }
+            process.exit(1);
+        }
+    }
+    return '{}';
+}
+//# sourceMappingURL=input.js.map

package/dist/utils/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../../src/utils/input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAOlE;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,OAAqB;IAC9C,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,KAAK,GAAG,IAAI,OAAO,CAAC,SAAS,KAAK,YAAY,CAAC;QAChF,IAAI,OAAe,CAAC;QAEpB,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,6BAA6B,CAAC,CAAC;YACvC,IAAI,CAAC;gBACH,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YACxC,CAAC;YAAC,MAAM,CAAC;gBACP,EAAE,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;gBACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;gBACpB,EAAE,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;gBAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YACjD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC7B,EAAE,CAAC,KAAK,CAAC,8BAA8B,QAAQ,EAAE,CAAC,CAAC;gBACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;QAED,IAAI,CAAC;YACH,eAAe,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;YACrD,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;gBAClC,EAAE,CAAC,KAAK,CAAC,8BAA8B,MAAM,yBAAyB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACvF,CAAC;iBAAM,CAAC;gBACN,EAAE,CAAC,KAAK,CAAC,8BAA8B,MAAM,sBAAsB,CAAC,CAAC;YACvE,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC9C,OAAO,MAAM,CAAC,GAAG,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;gBAClC,EAAE,CAAC,KAAK,CAAC,+BAA+B,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACzD,CAAC;iBAAM,CAAC;gBACN,EAAE,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;YACzC,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/utils/json-parse.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Robust JSON parsing with detailed error reporting.
+ *
+ * 1. Try to parse the raw string as JSON.
+ * 2. If invalid, report the exact position where parsing fails.
+ */
+export interface JsonParseResult {
+    readonly value: unknown;
+    readonly raw: string;
+    readonly wasStringified: boolean;
+}
+export declare class JsonParseError extends Error {
+    readonly position: number;
+    readonly snippet: string;
+    constructor(message: string, position: number, snippet: string);
+}
+/**
+ * Parse a string as strict JSON. Throws {@link JsonParseError} with
+ * position and snippet on failure.
+ *
+ * @param input  The raw string to parse as JSON.
+ * @returns      A result containing the parsed value.
+ * @throws       {@link JsonParseError} with position and snippet on failure.
+ */
+export declare function parseJsonStrict(input: string): JsonParseResult;

package/dist/utils/json-parse.js

@@ -0,0 +1,83 @@
+export class JsonParseError extends Error {
+    constructor(message, position, snippet) {
+        super(message);
+        this.name = 'JsonParseError';
+        this.position = position;
+        this.snippet = snippet;
+    }
+}
+/**
+ * Extract the error position from a JSON.parse SyntaxError message.
+ * Common formats:
+ *   - "... at position 42"           (V8 / Node)
+ *   - "... at line 3 column 5"       (some engines)
+ *   - "Unexpected token X in JSON at position 42"
+ */
+function extractErrorPosition(error, input) {
+    const msg = error.message;
+    const posMatch = msg.match(/position\s+(\d+)/i);
+    if (posMatch) {
+        return parseInt(posMatch[1], 10);
+    }
+    const lineColMatch = msg.match(/line\s+(\d+)\s+column\s+(\d+)/i);
+    if (lineColMatch) {
+        const targetLine = parseInt(lineColMatch[1], 10);
+        const targetCol = parseInt(lineColMatch[2], 10);
+        const lines = input.split('\n');
+        let offset = 0;
+        for (let i = 0; i < targetLine - 1 && i < lines.length; i++) {
+            offset += lines[i].length + 1; // +1 for newline
+        }
+        return offset + targetCol - 1;
+    }
+    return -1;
+}
+/**
+ * Build a human-readable snippet around the error position.
+ */
+function buildSnippet(input, position) {
+    if (position < 0 || position > input.length) {
+        return input.length <= 80 ? input : input.slice(0, 80) + '...';
+    }
+    const contextBefore = 20;
+    const contextAfter = 20;
+    const start = Math.max(0, position - contextBefore);
+    const end = Math.min(input.length, position + contextAfter);
+    const before = (start > 0 ? '...' : '') + input.slice(start, position);
+    const errorChar = position < input.length ? input[position] : '<end>';
+    const after = input.slice(position + 1, end) + (end < input.length ? '...' : '');
+    const pointer = ' '.repeat(before.length) + '^';
+    return `${before}${errorChar}${after}\n${pointer}`;
+}
+/**
+ * Build a detailed error message for a JSON parse failure.
+ */
+function buildDetailedError(input, error) {
+    const position = extractErrorPosition(error, input);
+    const snippet = buildSnippet(input, position);
+    const posInfo = position >= 0 ? ` at position ${position}` : '';
+    const message = `Invalid JSON${posInfo}: ${error.message}\n\n` +
+        `  ${snippet.split('\n').join('\n  ')}\n`;
+    return new JsonParseError(message, position, snippet);
+}
+/**
+ * Parse a string as strict JSON. Throws {@link JsonParseError} with
+ * position and snippet on failure.
+ *
+ * @param input  The raw string to parse as JSON.
+ * @returns      A result containing the parsed value.
+ * @throws       {@link JsonParseError} with position and snippet on failure.
+ */
+export function parseJsonStrict(input) {
+    try {
+        const value = JSON.parse(input);
+        return { value, raw: input, wasStringified: false };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw buildDetailedError(input, error);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=json-parse.js.map

package/dist/utils/json-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-parse.js","sourceRoot":"","sources":["../../src/utils/json-parse.ts"],"names":[],"mappings":"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"}

package/dist/utils/probe.d.ts

@@ -0,0 +1,18 @@
+export declare const PING_ENDPOINT = "/api/tools/ping";
+export interface ProbeSuccess {
+    ok: true;
+    baseUrl: string;
+    data: unknown;
+}
+export interface ProbeFailure {
+    ok: false;
+    reason: string;
+}
+export type ProbeResult = ProbeSuccess | ProbeFailure;
+/**
+ * Probe a Godot-MCP server's ping endpoint (`<base>/api/tools/ping`).
+ * Returns a structured result. The `ping` tool is registered by the
+ * `Tool_Ping` family (pure-managed, no editor required), so a connected
+ * plugin responds `{ "structured": { "result": "pong" } }`.
+ */
+export declare function probe(baseUrl: string, headers: Record<string, string>, timeoutMs: number): Promise<ProbeResult>;