@npgamedev/godot-mcp-server 0.0.1 → 1.0.0

package/dist/index.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Composition root + CLI entry (the npm `bin`). Constructs and wires the whole
+ * server in dependency order — bridge, MCP server, hook pipeline, the built-in
+ * tool surface, groups, prompts/resources/roots, the extension manager, and the
+ * config/version reconciler — then connects the stdio transport LAST so nothing is
+ * advertised before its guards are in place.
+ *
+ * @remarks
+ * Owns sequencing and wiring only — no domain logic (that lives in the modules it
+ * composes). The ordering is load-bearing: preflight may `process.exit` (Node
+ * version check, `--help` / a CLI parse error / `--tools-count` / `--list-eager`); the transport
+ * connects only after the full tool surface and the notification router are ready.
+ *
+ * @module
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createBridge } from "./transport/bridge.js";
+import { isReadOnly } from "./security/profiles.js";
+import { toolRefCount } from "./registration/toolRefs.js";
+import { createHookPipeline } from "./startup/hooks.js";
+import { getServerVersion } from "./shared/version.js";
+import { registerPrompts } from "./mcp/prompts.js";
+import { registerResources } from "./mcp/resources.js";
+import { init as initRoots, registerRoots } from "./mcp/roots.js";
+import { setGlobalHookPipeline } from "./registration/toolRegistry.js";
+import * as startupEnv from "./startup/startupEnv.js";
+import { parseCliArgs } from "./startup/cliArgs.js";
+import { resolvePortConfigOrExit, logResolvedPortConfig } from "./startup/portConfig.js";
+import { setLspOverride } from "./lsp/lspClient.js";
+import { MODULE_ALLOWED } from "./startup/serverMode.js";
+import * as registrars from "./startup/registrars.js";
+import { createExtensionManager } from "./extensions/extensions.js";
+import { createReconciler } from "./startup/reconcile.js";
+import { createLspStatusReporter } from "./lsp/lspStatusReporter.js";
+import { installProcessHandlers } from "./startup/lifecycle.js";
+// ── Preflight (may exit) ─────────────────────────────────────────────
+startupEnv.enforceNodeVersion();
+const cli = parseCliArgs(process.argv.slice(2));
+startupEnv.applyCliMetaGates(cli); // --help / parse error / --tools-count / --list-eager
+// ── Bridge setup ─────────────────────────────────────────────────────
+const projectPath = process.env.GODOT_MCP_PROJECT_PATH ?? process.cwd();
+const ports = resolvePortConfigOrExit(cli, projectPath); // invalid pin → exit 1
+logResolvedPortConfig(ports);
+const caps = startupEnv.resolveResponseCaps();
+// Feed the CLI LSP override into the lazy per-connect LSP resolution (CLI wins
+// over env there; env stays live so a config reload can still change it).
+setLspOverride({ port: cli.lspPort, host: cli.lspHost });
+const bridge = createBridge(`ws://127.0.0.1:${ports.editorPort}`, {
+    projectPath,
+    explicitRuntimePort: ports.runtimePort,
+    explicitEditorPort: ports.editorPinned,
+    scriptReadLimitBytes: caps.scriptReadLimitBytes,
+    wsBufferLimitBytes: caps.wsBufferLimitBytes,
+});
+startupEnv.warnConfigVersion();
+// ── Server + hook pipeline ───────────────────────────────────────────
+const server = new McpServer({ name: "godot-mcp-toolkit", version: getServerVersion() }, {
+    capabilities: { tools: { listChanged: true } },
+});
+const hookPipeline = createHookPipeline();
+setGlobalHookPipeline(hookPipeline);
+// ── Subsystem construction ───────────────────────────────────────────
+// The extension subsystem owns extension discovery (single-flight), live
+// reconciliation on extensions.changed, and the always-on extensions_refresh
+// tool. getReadOnly is injected (a live read of profiles.isReadOnly) so extensions.ts
+// imports no other composition module.
+const extensions = createExtensionManager({ server, bridge, getReadOnly: isReadOnly });
+// The reconciler keeps the advertised surface consistent with config + version:
+// the debounced config_reloaded reload and the one-shot startup reconcile.
+// discover is injected (extensions.discoverExtensions, a closure method — no
+// `this`) so reconcile.ts imports no other composition module (acyclic graph).
+const reconciler = createReconciler({ server, bridge, projectPath, discover: extensions.discoverExtensions });
+function logStartup(extTimedOut = false) {
+    const suffix = extTimedOut ? " (ext discovery timed out — extensions_refresh available)" : "";
+    process.stderr.write(`[godot-mcp] readOnly=${isReadOnly()} tools=${toolRefCount()} hooks=${hookPipeline.length} caps=${caps.scriptReadLimitBytes / 1024}KB/${caps.wsBufferLimitBytes / 1024}KB${suffix}\n`);
+}
+// ── Initial registration ────────────────────────────────────────────
+// Snapshot whether the Godot version is unknown at eager registration. When it
+// is, the registration-time version gate filters out version-gated tools
+// (scene_close) — leaving the startup surface incomplete. The startup reconcile
+// (below) completes it once the version resolves. Pre-populated from the
+// registry in the common dogfood flow → false → no reconcile needed.
+const versionNullAtEagerRegistration = bridge.getGodotVersion() == null;
+registrars.registerBuiltinModules(server, bridge, MODULE_ALLOWED);
+registrars.registerGroups(server, bridge, isReadOnly());
+extensions.registerRefreshTool(); // always in initial tools/list
+// ── Prompts, resources, roots ────────────────────────────────────────
+registerPrompts(server);
+registerResources(server, bridge);
+initRoots(projectPath);
+registerRoots(server);
+// ── Eager extension discovery ──────────────────────────────────────
+// Discover extensions BEFORE transport connects so they're in the
+// initial tools/list. Deadline prevents blocking if editor is slow.
+// Note: the editor's FIRST connect delivers no notification (config_reloaded
+// is reconnect-only — see bridge.ts performAuth). The version becomes known
+// via bridge.onGodotVersionKnown; if discovery timed out here or the version
+// was unknown at eager registration, the startup reconcile (armStartupReconcile,
+// below) completes the tool surface once the editor is reachable.
+const { timedOut } = await extensions.discoverEagerly();
+logStartup(timedOut);
+// ── Live config reload + notification routing ────────────────────────
+// LSP status reporter — pushes the GDScript-LSP verdict to the editor dock,
+// de-duped (the server computes the verdict; the editor has no engine API to
+// read its own LSP bind status). Constructed here so its setLspStatusReporter +
+// setGodotVersionGetter wiring fires before transport connect; the notification
+// router below calls reportRegistryVerdict() on reconnect.
+const lspReporter = createLspStatusReporter({ bridge, projectPath });
+bridge.onNotification((type, params) => {
+    if (type === "config_reloaded") {
+        // Push the authoritative LSP verdict to the editor dock.
+        lspReporter.reportRegistryVerdict();
+        // config_reloaded is only ever emitted on a RECONNECT ({reconnect:true},
+        // bridge.ts performAuth) — the editor's FIRST connect sends no notification.
+        // An incomplete first-connect surface is completed by the startup reconcile
+        // (reconciler.armStartupReconcile), not here. So this is the live reconnect
+        // handler: re-read config + re-register tools, debounced (300 ms).
+        reconciler.scheduleConfigReload();
+    }
+    else if (type === "extensions.changed") {
+        extensions.handleExtensionsChanged(params);
+    }
+    else if (type === "game_stopped") {
+        // Proactive runtime teardown: editor detected game-stop/crash and
+        // notified us. Clear the runtime channel immediately so the next
+        // callRuntime() fails with GAME_NOT_RUNNING in 0ms (no TCP probe).
+        bridge.clearRuntime?.();
+    }
+});
+// ── Startup reconcile ────────────────────────────────────────────────
+// Arm the one-shot startup reconcile: the eagerly-registered surface is
+// INCOMPLETE when the Godot version was unknown at eager registration
+// (version-gated tools like scene_close were filtered) or extension discovery
+// timed out (extension tools never registered) — the server-before-editor cold
+// start. The reconciler completes it EXACTLY ONCE (immediately if the version is
+// already known, else via onGodotVersionKnown) and is a strict no-op when the
+// eager surface was already complete. See reconcile.ts for the latch + triggers.
+reconciler.armStartupReconcile({ versionNullAtEagerRegistration, extDiscoveryTimedOut: timedOut });
+// ── Lifecycle + transport (last) ─────────────────────────────────────
+installProcessHandlers(bridge);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/lsp/lspClient.js

@@ -0,0 +1,509 @@
+/**
+ * Lightweight LSP client for Godot's built-in GDScript language server.
+ * The endpoint is discovered PER PROJECT from the registry at connect time
+ * (GODOT_MCP_LSP_PORT/_HOST override it); a collision fails visibly rather than
+ * silently reaching the wrong editor. Lazy connection — the first request
+ * triggers connect + the initialize handshake.
+ *
+ * @module
+ */
+import { createConnection } from "node:net";
+import { discoverLspEndpoint, liveLspClaimants } from "../registry.js";
+import { getServerVersion, isVersionCompatible } from "../shared/version.js";
+import { isValidPort } from "../startup/portConfig.js";
+import { normalizeUri } from "./lspUri.js";
+// ── Constants ────────────────────────────────────────────────────────
+const DEFAULT_LSP_PORT = 6005;
+const CONNECT_TIMEOUT_MS = 5_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+const HEADER_SEPARATOR = "\r\n\r\n";
+// Substring of the GDScript LSP's workspace-root-mismatch warning (window/
+// showMessage), shipped in Godot 4.5+ (PR #104401). Engine-verified against
+// gdscript_language_protocol.cpp on 4.5/4.6; absent 4.2-4.4. We send our real
+// rootUri in initialize, so this fires only when we reached the WRONG editor.
+const ROOT_MISMATCH_SUBSTRING = "might not work correctly with other projects";
+// Conflict hint, tailored to the connected Godot version (getter injected at
+// startup). The recovery differs by version, and the auto-rebind window is closed
+// at BOTH ends: only 4.5 retries the LSP bind, so only there does closing the other
+// editor recover the port. Every other supported version needs distinct ports or an
+// editor restart. Giving the LLM only the applicable path keeps the hint actionable.
+let godotVersionGetter = undefined;
+/** Inject the connected-version getter that tailors the conflict hint (startup wiring). @internal */
+export function setGodotVersionGetter(cb) {
+    godotVersionGetter = cb;
+}
+// CLI-sourced LSP override, injected once at startup. The composition root
+// resolves CLI > env and injects only the CLI part, so an env value stays
+// live-re-readable across a config reload. undefined until injected; when its
+// port is set it outranks both env and the registry in resolveLspEndpoint.
+let lspCliOverride = undefined;
+/** Inject the CLI `--lsp-port` / `--lsp-host` override (startup wiring). @internal */
+export function setLspOverride(override) {
+    lspCliOverride = override;
+}
+function lspConflictHint() {
+    const v = godotVersionGetter?.();
+    // A closed window, not an open-ended floor: 4.5 re-runs start() every
+    // internal-process frame while the bind has not succeeded, so it takes the port
+    // as soon as the other editor frees it. 4.6 latched that behind a
+    // start_attempted flag set before the call, making the bind one-shot again.
+    // Bounds are inclusive and compared on major.minor, so every 4.5 patch qualifies.
+    if (v != null && isVersionCompatible(v, "4.5", "4.5")) {
+        return ("Another editor holds this project's GDScript LSP port. Close the other editor — " +
+            "this editor's LSP then rebinds the port automatically — or give each editor a " +
+            "distinct --lsp-port + GODOT_MCP_LSP_PORT (see the toolkit addon's addons/godot_mcp_toolkit/docs/multi-instance.md).");
+    }
+    if (v != null) {
+        // No bind retry on this version — 4.2-4.4 never had one, and 4.6 onward latched
+        // it to a single attempt — so closing the other editor won't recover this one.
+        // The text is deliberately version-agnostic, which is why both ranges share it.
+        return ("Another editor holds this project's GDScript LSP port. On this Godot version, give " +
+            "each editor a distinct --lsp-port + GODOT_MCP_LSP_PORT (see the toolkit addon's addons/godot_mcp_toolkit/docs/multi-instance.md) — " +
+            "closing the other editor won't recover this LSP without restarting this editor.");
+    }
+    // Version unknown — lead with the lever that works everywhere, and make the one
+    // positive version claim narrow enough to stay true.
+    return ("Another editor holds this project's GDScript LSP port. Either give each editor a " +
+        "distinct --lsp-port + GODOT_MCP_LSP_PORT (see the toolkit addon's addons/godot_mcp_toolkit/docs/multi-instance.md), or close the other " +
+        "editor (only Godot 4.5 rebinds automatically; on every other version, restart this editor afterwards).");
+}
+const LSP_UNAVAILABLE_HINT = "GDScript LSP not reachable. Ensure the Godot editor is running with the toolkit " +
+    "plugin enabled. With multiple editors open, give each a distinct --lsp-port + " +
+    "GODOT_MCP_LSP_PORT (see the toolkit addon's addons/godot_mcp_toolkit/docs/multi-instance.md).";
+/** Resolution failure carrying a specific tool error code + actionable hint. */
+export class LspResolutionError extends Error {
+    code;
+    hint;
+    port;
+    constructor(code, message, hint, port) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.port = port;
+        this.name = "LspResolutionError";
+    }
+}
+/**
+ * Resolve a project's LSP endpoint at connect time. Priority:
+ *   1. --lsp-port / GODOT_MCP_LSP_PORT (+ --lsp-host / GODOT_MCP_LSP_HOST) —
+ *      explicit override (CLI wins over env), top priority, bypasses the registry
+ *      (the documented multi-instance lever).
+ *   2. discoverLspEndpoint(projectPath) — registry hit (with conflict guard).
+ *   3. miss → 6005 ONLY if no live editor holds it; else unavailable.
+ * Throws LspResolutionError on a conflict or an ambiguous miss — never a blind
+ * 6005 fallback (that is what kept comparable tools returning the wrong project).
+ * An invalid override value is skipped LOUDLY (stderr warning, fall through to
+ * discovery): the env var is re-read live on every connect, so a config reload
+ * can rewrite it mid-session after the startup validation gate has passed.
+ */
+export async function resolveLspEndpoint(projectPath) {
+    const overridePort = lspCliOverride?.port ?? process.env.GODOT_MCP_LSP_PORT;
+    if (overridePort) {
+        if (isValidPort(overridePort)) {
+            const host = lspCliOverride?.host ?? process.env.GODOT_MCP_LSP_HOST;
+            return { host: host || "127.0.0.1", port: parseInt(overridePort, 10) };
+        }
+        process.stderr.write(`[godot-mcp] ignoring invalid LSP port override "${overridePort}" ` +
+            `(expected an integer 1–65535); falling through to registry discovery\n`);
+    }
+    const disc = await discoverLspEndpoint(projectPath);
+    if (disc) {
+        if ("conflict" in disc) {
+            throw new LspResolutionError("LSP_PORT_CONFLICT", `Another live editor owns GDScript LSP port ${disc.port}; refusing to return its results.`, lspConflictHint(), disc.port);
+        }
+        return disc;
+    }
+    // Registry miss — fall back to 6005 only when no live editor holds it.
+    if ((await liveLspClaimants(DEFAULT_LSP_PORT)).length === 0) {
+        return { host: "127.0.0.1", port: DEFAULT_LSP_PORT };
+    }
+    throw new LspResolutionError("LSP_UNAVAILABLE", `No registry LSP endpoint for this project and port ${DEFAULT_LSP_PORT} is held by another editor.`, LSP_UNAVAILABLE_HINT, DEFAULT_LSP_PORT);
+}
+/**
+ * The authoritative LSP verdict for a project, computed without opening an LSP
+ * connection (resolution + registry ownership only — cross-platform PID liveness
+ * corroborated by a peer's own WS command port). The toolkit can't determine this
+ * itself (no engine API for its own LSP bind status), so the server reports it to
+ * the editor dock via editor.set_lsp_status. "active" = this editor owns the port
+ * (per registry / env override); a later editor or a non-registry holder →
+ * conflict / unavailable.
+ */
+export async function getLspStatus(projectPath) {
+    try {
+        const ep = await resolveLspEndpoint(projectPath);
+        return { state: "active", host: ep.host, port: ep.port, detail: "Owns the GDScript LSP port." };
+    }
+    catch (err) {
+        if (err instanceof LspResolutionError) {
+            return {
+                state: err.code === "LSP_PORT_CONFLICT" ? "conflict" : "unavailable",
+                host: "127.0.0.1",
+                port: err.port,
+                detail: err.message,
+            };
+        }
+        return { state: "unavailable", host: "127.0.0.1", port: DEFAULT_LSP_PORT, detail: String(err) };
+    }
+}
+// ── LspClient ────────────────────────────────────────────────────────
+export class LspClient {
+    socket = undefined;
+    nextId = 1;
+    pending = new Map();
+    buffer = "";
+    initialized = false;
+    connecting = undefined;
+    host = "127.0.0.1";
+    port = DEFAULT_LSP_PORT;
+    projectPath;
+    // Set when the LSP emits the 4.5+ root-mismatch warning during initialize —
+    // means we reached an editor open on a different project. Reset each connect.
+    rootMismatch = false;
+    // Document tracking — which files have been opened via didOpen.
+    openDocuments = new Set();
+    // Notification storage — keyed by URI, stores latest diagnostics.
+    diagnosticsByUri = new Map();
+    diagnosticWaiters = new Map();
+    /** Optional per-instance override for the `initialize` request timeout only
+     *  (all other requests keep {@link REQUEST_TIMEOUT_MS}). Undefined = default.
+     *  Consumed by the smoke harness: Godot 4.2 answers the FIRST initialize only
+     *  after a synchronous main-thread workspace scan that can take far longer
+     *  than the default budget on slow runners (measured ~5.3s warm-hardware /
+     *  100s+ mute on 2-core windows-latest); a patient first handshake absorbs
+     *  that one-time cost. Product callers pass nothing and are unaffected. */
+    initializeTimeoutMs;
+    constructor(projectPath, opts) {
+        this.projectPath = projectPath;
+        this.initializeTimeoutMs = opts?.initializeTimeoutMs;
+    }
+    /** file:// URI for the project root — sent as rootUri so the 4.5+ LSP can
+     *  warn (window/showMessage) when we reached an editor open on a different
+     *  project, i.e. a port collision reached the wrong editor. */
+    projectRootUri() {
+        const norm = this.projectPath.replace(/\\/g, "/").replace(/\/+$/, "");
+        return /^[A-Za-z]:/.test(norm) ? `file:///${norm}` : `file://${norm}`;
+    }
+    /** Ensure connection is established. Lazy — connects on first call. */
+    async ensureConnected() {
+        if (this.initialized && this.socket && !this.socket.destroyed)
+            return;
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = this.doConnect();
+        try {
+            await this.connecting;
+        }
+        finally {
+            this.connecting = undefined;
+        }
+    }
+    async doConnect() {
+        // Reset state from any previous connection.
+        this.cleanup();
+        this.rootMismatch = false;
+        // Resolve fresh each connect so a reconnect picks up a changed port/host.
+        // Throws LspResolutionError on a conflict / ambiguous miss (no blind 6005).
+        const endpoint = await resolveLspEndpoint(this.projectPath);
+        this.host = endpoint.host;
+        this.port = endpoint.port;
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                socket.destroy();
+                reject(new Error(`LSP connect timeout (${this.host}:${this.port})`));
+            }, CONNECT_TIMEOUT_MS);
+            const socket = createConnection({ host: this.host, port: this.port }, () => {
+                clearTimeout(timer);
+                this.socket = socket;
+                resolve();
+            });
+            socket.on("error", (err) => {
+                clearTimeout(timer);
+                reject(new Error(`LSP connect failed (${this.host}:${this.port}): ${err.message}`));
+            });
+            socket.on("data", (chunk) => this.onData(chunk.toString("utf-8")));
+            socket.on("close", () => this.onClose());
+        });
+        // LSP initialize handshake. Send our REAL rootUri (not null): on Godot 4.5+
+        // the server emits a window/showMessage root-mismatch warning when the URI
+        // resolves to a different open project — i.e. we reached the wrong editor.
+        // The engine sends that warning BEFORE the initialize response
+        // (gdscript_language_protocol.cpp), so rootMismatch is already set when this
+        // await resolves.
+        const initResult = await this.sendRequest("initialize", {
+            processId: process.pid,
+            capabilities: {},
+            rootUri: this.projectRootUri(),
+            clientInfo: { name: "godot-mcp-server", version: getServerVersion() },
+        }, this.initializeTimeoutMs);
+        if (!initResult || typeof initResult !== "object") {
+            throw new Error("LSP initialize failed: no capabilities returned");
+        }
+        if (this.rootMismatch) {
+            this.cleanup();
+            throw new LspResolutionError("LSP_PORT_CONFLICT", `Reached an editor open on a different project on LSP port ${this.port} (root mismatch).`, lspConflictHint(), this.port);
+        }
+        // Send initialized notification.
+        this.sendNotification("initialized", {});
+        this.initialized = true;
+    }
+    /** Send a JSON-RPC request and await the response.
+     *  `timeoutMs` overrides {@link REQUEST_TIMEOUT_MS} for this request only
+     *  (used for the patient first `initialize`); omitted = default. */
+    async sendRequest(method, params, timeoutMs) {
+        if (!this.socket || this.socket.destroyed) {
+            throw new Error("LSP not connected");
+        }
+        const id = this.nextId++;
+        const request = { jsonrpc: "2.0", id, method, params };
+        const body = JSON.stringify(request);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`LSP request timeout: ${method}`));
+            }, timeoutMs ?? REQUEST_TIMEOUT_MS);
+            this.pending.set(id, { resolve, reject, timer });
+            this.writeMessage(body);
+        });
+    }
+    /** Send a JSON-RPC notification (no response expected). */
+    sendNotification(method, params) {
+        if (!this.socket || this.socket.destroyed)
+            return;
+        const notification = { jsonrpc: "2.0", method, params };
+        this.writeMessage(JSON.stringify(notification));
+    }
+    /** Open a document in the LSP (or update if already open). */
+    async openDocument(uri, content) {
+        // Drop any diagnostics stored for this URI before (re)sending content: an
+        // entry present now predates the new text, and a late publish of it could
+        // otherwise poison the next waitForDiagnostics for this file (the batch
+        // scan multiplies that hazard). The map is keyed by normalizeUri (see
+        // handleNotification), so normalize here too.
+        this.diagnosticsByUri.delete(normalizeUri(uri));
+        if (this.openDocuments.has(uri)) {
+            // Already open — send didChange with full content.
+            this.sendNotification("textDocument/didChange", {
+                textDocument: { uri, version: this.nextId++ },
+                contentChanges: [{ text: content }],
+            });
+        }
+        else {
+            // Open shaders as "gdshader", not "gdscript": Godot's LSP has no shader
+            // documentSymbol/diagnostics provider, so a "gdscript" languageId makes the
+            // engine parse valid shader source as GDScript and emit bogus parse-error
+            // diagnostics. A non-GDScript languageId makes it skip parsing — clean empty
+            // symbols + no false diagnostics, uniform across 4.2-4.7.
+            const languageId = uri.endsWith(".gdshader") || uri.endsWith(".gdshaderinc") ? "gdshader" : "gdscript";
+            this.sendNotification("textDocument/didOpen", {
+                textDocument: { uri, languageId, version: 1, text: content },
+            });
+            this.openDocuments.add(uri);
+        }
+    }
+    /** Close a document in the LSP, clearing its open + diagnostics state.
+     *
+     *  Keeps client and server open-state in lockstep — the 4.7 GDScript LSP
+     *  erases per-peer parser state on didClose and ERR_FAILs a re-didOpen of a
+     *  file it still thinks is open, so a batch that reopens files must close
+     *  each first. Call only AFTER collecting a URI's diagnostics — never while a
+     *  waitForDiagnostics for it is still pending. */
+    async closeDocument(uri) {
+        if (this.openDocuments.has(uri)) {
+            this.sendNotification("textDocument/didClose", { textDocument: { uri } });
+        }
+        this.openDocuments.delete(uri);
+        this.diagnosticsByUri.delete(normalizeUri(uri));
+    }
+    /** Wait for a diagnostics notification for a URI (with timeout).
+     *
+     *  Tri-state: a received notification returns its {@link DiagnosticEntry}
+     *  array — which may be `[]` for a clean file (a clean file DOES publish an
+     *  empty-diagnostics notification on every supported Godot version). A
+     *  timeout with no notification returns `undefined` — status unknown, which
+     *  the caller must NOT conflate with clean. The distinction is load-bearing
+     *  for the project scan: a timed-out file is never counted clean. */
+    async waitForDiagnostics(uri, timeoutMs = 5000) {
+        const normUri = normalizeUri(uri);
+        // Check if we already have diagnostics from the notification. `!== undefined`
+        // distinguishes a stored empty array (clean) from nothing stored (unknown).
+        const existing = this.diagnosticsByUri.get(normUri);
+        if (existing !== undefined) {
+            this.diagnosticsByUri.delete(normUri);
+            return existing;
+        }
+        // Wait for the notification to arrive.
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.diagnosticWaiters.delete(normUri);
+                // Final check — a late publish may have stored diagnostics under
+                // normUri between the wait starting and the timer firing. Present =
+                // received (return it, possibly `[]`); absent = no notification arrived
+                // (return undefined — timed out, NOT clean).
+                const late = this.diagnosticsByUri.get(normUri);
+                this.diagnosticsByUri.delete(normUri);
+                resolve(late);
+            }, timeoutMs);
+            this.diagnosticWaiters.set(normUri, {
+                resolve: () => {
+                    clearTimeout(timer);
+                    const diags = this.diagnosticsByUri.get(normUri);
+                    this.diagnosticsByUri.delete(normUri);
+                    resolve(diags);
+                },
+                timer,
+            });
+        });
+    }
+    /** Check if the client is currently connected. */
+    isConnected() {
+        return this.initialized && !!this.socket && !this.socket.destroyed;
+    }
+    /** Whether `uri` is currently tracked as open (post-didOpen, pre-didClose).
+     *  Exposes the open-document bookkeeping for the close-lifecycle tests. @internal */
+    hasOpenDocument(uri) {
+        return this.openDocuments.has(uri);
+    }
+    /** The host:port resolved for the most recent connect attempt (valid after
+     *  doConnect set it — i.e. when a connect was attempted, success or failure). */
+    getEndpoint() {
+        return { host: this.host, port: this.port };
+    }
+    /** Graceful shutdown. */
+    async close() {
+        if (!this.socket || this.socket.destroyed)
+            return;
+        try {
+            await this.sendRequest("shutdown", null);
+            this.sendNotification("exit");
+        }
+        catch {
+            // Best-effort shutdown.
+        }
+        this.cleanup();
+    }
+    // ── Private ────────────────────────────────────────────────────────
+    writeMessage(body) {
+        const header = `Content-Length: ${Buffer.byteLength(body, "utf-8")}${HEADER_SEPARATOR}`;
+        this.socket.write(header + body, "utf-8");
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        this.processBuffer();
+    }
+    processBuffer() {
+        while (true) {
+            const headerEnd = this.buffer.indexOf(HEADER_SEPARATOR);
+            if (headerEnd === -1)
+                break;
+            // Parse Content-Length from headers.
+            const headerBlock = this.buffer.slice(0, headerEnd);
+            const match = headerBlock.match(/Content-Length:\s*(\d+)/i);
+            if (!match) {
+                // Malformed — skip this header block.
+                this.buffer = this.buffer.slice(headerEnd + HEADER_SEPARATOR.length);
+                continue;
+            }
+            const contentLength = parseInt(match[1], 10);
+            const bodyStart = headerEnd + HEADER_SEPARATOR.length;
+            // Check if we have the full body.
+            if (Buffer.byteLength(this.buffer.slice(bodyStart), "utf-8") < contentLength)
+                break;
+            // Extract body by byte length.
+            const bodyBytes = Buffer.from(this.buffer.slice(bodyStart), "utf-8");
+            const body = bodyBytes.slice(0, contentLength).toString("utf-8");
+            const remainderBytes = bodyBytes.slice(contentLength);
+            this.buffer = remainderBytes.toString("utf-8");
+            this.handleMessage(body);
+        }
+    }
+    handleMessage(body) {
+        let msg;
+        try {
+            msg = JSON.parse(body);
+        }
+        catch {
+            return;
+        }
+        // Response to a request we sent.
+        if ("id" in msg && msg.id != null) {
+            const resp = msg;
+            const pending = this.pending.get(resp.id);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pending.delete(resp.id);
+                if (resp.error) {
+                    pending.reject(new Error(`LSP error [${resp.error.code}]: ${resp.error.message}`));
+                }
+                else {
+                    pending.resolve(resp.result);
+                }
+            }
+            return;
+        }
+        // Server notification (no id).
+        if ("method" in msg) {
+            this.handleNotification(msg);
+        }
+    }
+    handleNotification(notification) {
+        if (notification.method === "window/showMessage") {
+            // Godot 4.5+ root-mismatch warning → we reached an editor open on a
+            // different project (port collision). doConnect checks this after init.
+            const params = notification.params;
+            if (params?.message && params.message.includes(ROOT_MISMATCH_SUBSTRING)) {
+                this.rootMismatch = true;
+            }
+            return;
+        }
+        if (notification.method === "textDocument/publishDiagnostics") {
+            const params = notification.params;
+            if (!params?.uri)
+                return;
+            const uri = normalizeUri(params.uri);
+            const diagnostics = (params.diagnostics ?? []).map((d) => {
+                const diag = d;
+                return {
+                    line: diag.range?.start?.line ?? 0,
+                    character: diag.range?.start?.character ?? 0,
+                    severity: diag.severity ?? 1,
+                    message: diag.message ?? "",
+                    code: diag.code,
+                };
+            });
+            this.diagnosticsByUri.set(uri, diagnostics);
+            // Wake any waiter for this URI.
+            const waiter = this.diagnosticWaiters.get(uri);
+            if (waiter) {
+                this.diagnosticWaiters.delete(uri);
+                waiter.resolve();
+            }
+        }
+    }
+    onClose() {
+        this.initialized = false;
+        this.openDocuments.clear();
+        // Reject all pending requests.
+        for (const [, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error("LSP connection closed"));
+        }
+        this.pending.clear();
+    }
+    cleanup() {
+        if (this.socket) {
+            this.socket.destroy();
+            this.socket = undefined;
+        }
+        this.initialized = false;
+        this.openDocuments.clear();
+        this.diagnosticsByUri.clear();
+        for (const [, waiter] of this.diagnosticWaiters) {
+            clearTimeout(waiter.timer);
+        }
+        this.diagnosticWaiters.clear();
+        for (const [, pending] of this.pending) {
+            clearTimeout(pending.timer);
+        }
+        this.pending.clear();
+    }
+}