@skillcap/gdh 0.25.4 → 0.26.0

package/node_modules/@gdh/authoring/dist/lsp.js

@@ -5,7 +5,7 @@ import fs from "node:fs/promises";
 import net from "node:net";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { GDH_MANAGED_LSP_SURFACE_VERSION, resolveConfiguredGodotEditorBin } from "@gdh/core";
+import { GDH_MANAGED_LSP_MIN_GODOT_VERSION, GDH_MANAGED_LSP_SURFACE_VERSION, resolveConfiguredGodotEditorBin, } from "@gdh/core";
 import { connectGodotLspClient, GdhLspClientError, } from "./lsp-client.js";
 import { summarizeBlockingDiagnostics } from "./diagnostics-summary.js";
 import { classifyDiagnosticsFreshness, DIAGNOSTICS_BROKER_DEFAULT_FRESHNESS_STALE_AFTER_MS, resolveDiagnosticsBrokerPaths, } from "./diagnostics-broker-contract.js";
@@ -24,6 +24,7 @@ const MANAGED_LSP_HEALTH_RETRY_DELAY_MS = 100;
 const MANAGED_LSP_DIAGNOSTIC_CONNECT_TIMEOUT_MS = 1_000;
 const MANAGED_LSP_DIAGNOSTIC_REQUEST_TIMEOUT_MS = 1_000;
 const MANAGED_LSP_DIAGNOSTIC_WAIT_TIMEOUT_MS = 10_000;
+const MANAGED_LSP_POST_EDIT_DIAGNOSTIC_WAIT_TIMEOUT_MS = 1_500;
 class GdhManagedLspStateLockError extends Error {
     reason;
     reasons;
@@ -60,7 +61,7 @@ async function readBrokerSnapshot(targetPath) {
  *
  * Returns null otherwise (fall through to direct LSP check).
  */
-function extractBrokerDiagnosticsIfFresh(snapshot, currentInstanceId, requestedUris) {
+function extractBrokerDiagnosticsIfFresh(snapshot, currentInstanceId, requestedUris, currentContentHashesByUri) {
     if (snapshot.lspInstanceId !== currentInstanceId) {
         return null;
     }
@@ -73,6 +74,12 @@ function extractBrokerDiagnosticsIfFresh(snapshot, currentInstanceId, requestedU
         if (file === undefined) {
             return null; // Requested URI not in broker — fall through.
         }
+        if (typeof file.contentHash !== "string" || file.contentHash.length === 0) {
+            return null; // Pre-content-hash snapshots cannot prove current file content.
+        }
+        if (currentContentHashesByUri.get(uri) !== file.contentHash) {
+            return null; // Snapshot was captured for different file content.
+        }
         const freshness = classifyDiagnosticsFreshness({
             fileSnapshot: {
                 uri: file.uri,
@@ -115,122 +122,190 @@ export async function getManagedLspStatus(input) {
         return unavailable;
     }
     try {
-        return await withManagedLspStateLock(worktree, input.owner ?? "gdh lsp status", async (stateLock) => await withLease(worktree, input.owner ?? "gdh lsp status", async (lease, activeLeaseCount) => {
-            let cleanedStaleInstance = false;
-            let cleanupReasons = [];
+        return await withManagedLspStateLock(worktree, input.owner ?? "gdh lsp status", async (stateLock) => {
             const projectPath = path.resolve(input.targetPath, input.status.primaryProjectPath ?? ".");
             const expectedIdentity = await resolveCurrentManagedLspIdentity(worktree, projectPath);
-            const existing = await readPersistedInstance(worktree);
-            if (existing !== null) {
-                const validation = await validatePersistedInstance(existing.instance, expectedIdentity);
-                if (validation.reusable) {
-                    const reusedInstance = {
-                        ...existing.instance,
-                        lastValidatedAt: new Date().toISOString(),
-                        trust: validation.trust,
-                    };
-                    await persistInstance(worktree, {
-                        ...existing,
-                        instance: reusedInstance,
-                        rawPayload: validation.rawPayload ?? existing.rawPayload,
+            // Phase 81 / LSP-08 / D-17: refuse-to-launch when the configured
+            // Godot version is below the managed-LSP floor. Short-circuits
+            // BEFORE lsp-leases.json acquisition (withLease) and BEFORE
+            // persisted-instance reads — but executes inside the lsp.lock
+            // (stateLock) so identity resolution is serialized with other
+            // lifecycle mutations. Misconfigured 4.5.0/4.5.1 setups never
+            // acquire a lease or block other waiters.
+            if (expectedIdentity.editorVersionReason === "godot_editor_version_unsupported_for_lsp") {
+                return createUnavailableStatus({
+                    targetPath: input.targetPath,
+                    readiness: input.status.readiness,
+                    worktree,
+                    inventoryObservedAt: input.status.inventoryObservedAt,
+                    projectConfigPresent: input.projectConfig !== null,
+                    availability: "unavailable",
+                    reasons: dedupe([
+                        ...stateLock.recoveredReasons,
+                        "godot_editor_version_unsupported_for_lsp",
+                    ]),
+                    summary: "The configured Godot editor version does not meet the minimum version required for the managed authoring.lsp. Upgrade to Godot 4.5.2 or later.",
+                    versionFloorAdvisory: {
+                        detectedVersion: expectedIdentity.editorVersion,
+                        minimumVersion: GDH_MANAGED_LSP_MIN_GODOT_VERSION,
+                        recommendedVersions: ["4.5.2", "4.6.x"],
+                    },
+                });
+            }
+            return await withLease(worktree, input.owner ?? "gdh lsp status", async (lease, activeLeaseCount) => {
+                let cleanedStaleInstance = false;
+                let cleanupReasons = [];
+                const existing = await readPersistedInstance(worktree);
+                if (existing !== null) {
+                    const validation = await validatePersistedInstance(existing.instance, expectedIdentity);
+                    if (validation.reusable) {
+                        const reusedInstance = {
+                            ...existing.instance,
+                            lastValidatedAt: new Date().toISOString(),
+                            trust: validation.trust,
+                        };
+                        await persistInstance(worktree, {
+                            ...existing,
+                            instance: reusedInstance,
+                            rawPayload: validation.rawPayload ?? existing.rawPayload,
+                        });
+                        return createStatusResult({
+                            targetPath: input.targetPath,
+                            readiness: input.status.readiness,
+                            availability: "available",
+                            status: validation.trust === "trusted" ? "ready" : "degraded",
+                            validationMode: existing.validationMode,
+                            summary: validation.trust === "trusted"
+                                ? "Reused the managed authoring.lsp instance for this worktree."
+                                : "Reused the managed authoring.lsp instance, but trust is degraded and the instance should be treated cautiously.",
+                            reasons: dedupe([
+                                ...stateLock.recoveredReasons,
+                                ...(validation.trust === "trusted" ? [] : ["lsp_instance_degraded"]),
+                            ]),
+                            worktree,
+                            lease,
+                            activeLeaseCount,
+                            reusedInstance: true,
+                            cleanedStaleInstance,
+                            instance: reusedInstance,
+                            inventoryObservedAt: input.status.inventoryObservedAt,
+                            projectConfigPresent: input.projectConfig !== null,
+                            rawPayload: validation.rawPayload ?? existing.rawPayload,
+                        });
+                    }
+                    cleanedStaleInstance = true;
+                    cleanupReasons = validation.reasons;
+                    await cleanupPersistedInstance(worktree, existing.instance, validation.reason, {
+                        expectedIdentity,
                     });
-                    return createStatusResult({
+                    // Phase 81 / LSP-04 / D-11 / Pitfall 7: when the LSP instance
+                    // identity has changed, the broker snapshot referenced the
+                    // now-defunct instance. Prune so the next read returns
+                    // broker_metadata_missing instead of lsp_instance_identity_mismatch.
+                    {
+                        const { pruneAuthoringDiagnostics } = await import("./diagnostics-broker.js");
+                        await pruneAuthoringDiagnostics({
+                            targetPath: input.targetPath,
+                            status: input.status,
+                            projectConfig: input.projectConfig,
+                        });
+                    }
+                }
+                if (input.launchPolicy === "reuse_existing") {
+                    return createUnavailableStatus({
                         targetPath: input.targetPath,
                         readiness: input.status.readiness,
-                        availability: "available",
-                        status: validation.trust === "trusted" ? "ready" : "degraded",
-                        validationMode: existing.validationMode,
-                        summary: validation.trust === "trusted"
-                            ? "Reused the managed authoring.lsp instance for this worktree."
-                            : "Reused the managed authoring.lsp instance, but trust is degraded and the instance should be treated cautiously.",
+                        worktree,
+                        inventoryObservedAt: input.status.inventoryObservedAt,
+                        projectConfigPresent: input.projectConfig !== null,
+                        availability: lspCapability?.availability ?? "available",
                         reasons: dedupe([
                             ...stateLock.recoveredReasons,
-                            ...(validation.trust === "trusted" ? [] : ["lsp_instance_degraded"]),
+                            ...(cleanedStaleInstance ? ["stale_lsp_instance_cleaned"] : []),
+                            ...cleanupReasons,
+                            "lsp_instance_not_running",
+                            "post_edit_fast_path_did_not_launch_lsp",
                         ]),
-                        worktree,
+                        summary: "No reusable managed authoring.lsp instance is currently running; post-edit fast check did not launch Godot.",
                         lease,
                         activeLeaseCount,
-                        reusedInstance: true,
                         cleanedStaleInstance,
-                        instance: reusedInstance,
+                        rawPayload: {
+                            launchPolicy: "reuse_existing",
+                            projectPath,
+                            cleanedStaleInstance,
+                            cleanupReasons,
+                        },
+                    });
+                }
+                const launchResult = await launchManagedInstance(worktree, projectPath);
+                if ("unavailable" in launchResult) {
+                    return createUnavailableStatus({
+                        targetPath: input.targetPath,
+                        readiness: input.status.readiness,
+                        worktree,
                         inventoryObservedAt: input.status.inventoryObservedAt,
                         projectConfigPresent: input.projectConfig !== null,
-                        rawPayload: validation.rawPayload ?? existing.rawPayload,
+                        availability: "unavailable",
+                        reasons: [
+                            ...stateLock.recoveredReasons,
+                            ...(cleanedStaleInstance ? ["stale_lsp_instance_cleaned"] : []),
+                            ...cleanupReasons,
+                            ...launchResult.unavailable.reasons,
+                        ],
+                        summary: launchResult.unavailable.summary,
+                        lease,
+                        activeLeaseCount,
+                        cleanedStaleInstance,
+                        rawPayload: launchResult.unavailable.rawPayload,
                     });
                 }
-                cleanedStaleInstance = true;
-                cleanupReasons = validation.reasons;
-                await cleanupPersistedInstance(worktree, existing.instance, validation.reason, {
-                    expectedIdentity,
+                const launchedInstance = {
+                    instanceId: launchResult.instanceId,
+                    launcher: launchResult.launcher,
+                    port: launchResult.port,
+                    pid: launchResult.pid,
+                    projectPath,
+                    command: launchResult.command,
+                    trust: launchResult.trust,
+                    launchedAt: new Date().toISOString(),
+                    lastValidatedAt: new Date().toISOString(),
+                    identity: launchResult.identity,
+                };
+                await persistInstance(worktree, {
+                    schemaVersion: LSP_INSTANCE_SCHEMA_VERSION,
+                    instance: launchedInstance,
+                    validationMode: launchResult.validationMode,
+                    diagnostics: launchResult.diagnostics,
+                    rawPayload: launchResult.rawPayload,
                 });
-            }
-            const launchResult = await launchManagedInstance(worktree, projectPath);
-            if ("unavailable" in launchResult) {
-                return createUnavailableStatus({
+                return createStatusResult({
                     targetPath: input.targetPath,
                     readiness: input.status.readiness,
-                    worktree,
-                    inventoryObservedAt: input.status.inventoryObservedAt,
-                    projectConfigPresent: input.projectConfig !== null,
-                    availability: "unavailable",
-                    reasons: [
+                    availability: "available",
+                    status: launchResult.trust === "trusted" ? "ready" : "degraded",
+                    validationMode: launchResult.validationMode,
+                    summary: launchResult.trust === "trusted"
+                        ? "Started a managed authoring.lsp instance for this worktree."
+                        : "Started a managed authoring.lsp instance, but trust is degraded and validation should be treated cautiously.",
+                    reasons: dedupe([
                         ...stateLock.recoveredReasons,
                         ...(cleanedStaleInstance ? ["stale_lsp_instance_cleaned"] : []),
                         ...cleanupReasons,
-                        ...launchResult.unavailable.reasons,
-                    ],
-                    summary: launchResult.unavailable.summary,
+                        ...(launchResult.trust === "trusted" ? [] : ["lsp_instance_degraded"]),
+                    ]),
+                    worktree,
                     lease,
                     activeLeaseCount,
+                    reusedInstance: false,
                     cleanedStaleInstance,
-                    rawPayload: launchResult.unavailable.rawPayload,
+                    instance: launchedInstance,
+                    inventoryObservedAt: input.status.inventoryObservedAt,
+                    projectConfigPresent: input.projectConfig !== null,
+                    rawPayload: launchResult.rawPayload,
                 });
-            }
-            const launchedInstance = {
-                instanceId: launchResult.instanceId,
-                launcher: launchResult.launcher,
-                port: launchResult.port,
-                pid: launchResult.pid,
-                projectPath,
-                command: launchResult.command,
-                trust: launchResult.trust,
-                launchedAt: new Date().toISOString(),
-                lastValidatedAt: new Date().toISOString(),
-                identity: launchResult.identity,
-            };
-            await persistInstance(worktree, {
-                schemaVersion: LSP_INSTANCE_SCHEMA_VERSION,
-                instance: launchedInstance,
-                validationMode: launchResult.validationMode,
-                diagnostics: launchResult.diagnostics,
-                rawPayload: launchResult.rawPayload,
-            });
-            return createStatusResult({
-                targetPath: input.targetPath,
-                readiness: input.status.readiness,
-                availability: "available",
-                status: launchResult.trust === "trusted" ? "ready" : "degraded",
-                validationMode: launchResult.validationMode,
-                summary: launchResult.trust === "trusted"
-                    ? "Started a managed authoring.lsp instance for this worktree."
-                    : "Started a managed authoring.lsp instance, but trust is degraded and validation should be treated cautiously.",
-                reasons: dedupe([
-                    ...stateLock.recoveredReasons,
-                    ...(cleanedStaleInstance ? ["stale_lsp_instance_cleaned"] : []),
-                    ...cleanupReasons,
-                    ...(launchResult.trust === "trusted" ? [] : ["lsp_instance_degraded"]),
-                ]),
-                worktree,
-                lease,
-                activeLeaseCount,
-                reusedInstance: false,
-                cleanedStaleInstance,
-                instance: launchedInstance,
-                inventoryObservedAt: input.status.inventoryObservedAt,
-                projectConfigPresent: input.projectConfig !== null,
-                rawPayload: launchResult.rawPayload,
             });
-        }));
+        });
     }
     catch (error) {
         if (error instanceof GdhManagedLspStateLockError) {
@@ -248,6 +323,36 @@ export async function getManagedLspStatus(input) {
         throw error;
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 82 / LSP-02 / LSP-07 — managed-LSP warmup surface.
+//
+// `warmupManagedLsp` is the in-process entry point that the post-edit hook
+// detach-spawns (via `gdh lsp warmup`) and the MCP `authoring.warmup` tool
+// invokes. It is idempotent: concurrent callers fan in via a single-attempt
+// `<targetPath>/.gdh-state/lsp.lock` acquire so the underlying Godot launch
+// happens at most once.
+//
+// The implementation lives in `./lsp-warmup.js`. That sibling module imports
+// `getManagedLspStatus` from `./lsp.js`, which is the documented vitest
+// workaround for the "vi.mock cannot intercept same-module internal calls"
+// pitfall (https://vitest.dev/guide/mocking/modules — Internal Method Calls).
+//
+// IMPORTANT: this is a thin wrapper that DEFERS to the impl via dynamic
+// `await import("./lsp-warmup.js")`. The deferral guarantees `lsp-warmup.ts`
+// is NOT a static dependency of `lsp.ts`. Were it static (a re-export), it
+// would be evaluated as part of `./lsp.js`'s module graph, with its
+// `import { getManagedLspStatus } from "./lsp.js"` resolving against the
+// partially-evaluated original module record — so the unit-test mock
+// (`vi.mock("./lsp.js", ...)`) would never reach the warmup impl. By
+// keeping it deferred, the test's `await import("./lsp-warmup.js")` is
+// the FIRST point at which lsp-warmup.ts loads, and at that time the mock
+// is already registered, so the `./lsp.js` import resolves to the mocked
+// module. See `./lsp-warmup.ts` and `./lsp-warmup.test.ts` for context.
+// ─────────────────────────────────────────────────────────────────────────────
+export async function warmupManagedLsp(input) {
+    const { warmupManagedLsp: impl } = await import("./lsp-warmup.js");
+    return impl(input);
+}
 export async function checkManagedLsp(input) {
     const worktree = resolveWorktreeIdentity(input.targetPath, input.status, input.projectConfig);
     return await withManagedLspLifecycleLock(worktree, "check", "gdh lsp check", async (stateLock) => {
@@ -370,6 +475,19 @@ export async function stopManagedLsp(input) {
             killProcess: true,
             expectedIdentity,
         });
+        // Phase 81 / LSP-04 / D-11: prune the broker snapshot inside the lifecycle
+        // lock so concurrent readers cannot observe a stale snapshot pointing at
+        // the just-stopped LSP instance. The .primed marker is intentionally
+        // preserved (D-10) — broker absence remains "broker_metadata_missing"
+        // until the next refresh, distinct from "broker_not_yet_primed".
+        {
+            const { pruneAuthoringDiagnostics } = await import("./diagnostics-broker.js");
+            await pruneAuthoringDiagnostics({
+                targetPath: input.targetPath,
+                status: input.status,
+                projectConfig: input.projectConfig,
+            });
+        }
         return createLifecycleCommandResult({
             targetPath: input.targetPath,
             command: "stop",
@@ -820,7 +938,8 @@ async function tryBrokerDiagnosticsForPostEdit(input) {
         return null;
     }
     const requestedUris = resolvedFiles.map((f) => pathToFileURL(f).href);
-    const brokerResult = extractBrokerDiagnosticsIfFresh(snapshot, input.instance.instanceId, requestedUris);
+    const currentContentHashesByUri = await hashFilesByUri(resolvedFiles);
+    const brokerResult = extractBrokerDiagnosticsIfFresh(snapshot, input.instance.instanceId, requestedUris, currentContentHashesByUri);
     if (brokerResult === null) {
         return null;
     }
@@ -880,7 +999,7 @@ async function collectManagedGdscriptDiagnostics(input) {
                 const uri = pathToFileURL(filePath).href;
                 const diagnosticsPromise = client.waitForDiagnostics({
                     uri,
-                    timeoutMs: resolveManagedLspDiagnosticWaitTimeoutMs(),
+                    timeoutMs: resolveManagedLspDiagnosticWaitTimeoutMs(input.mode),
                 });
                 await client.didOpen({
                     uri,
@@ -1071,14 +1190,29 @@ function canonicalExistingPath(filePath) {
         return path.resolve(filePath);
     }
 }
-function resolveManagedLspDiagnosticWaitTimeoutMs() {
+async function hashFilesByUri(filePaths) {
+    const hashes = new Map();
+    for (const filePath of filePaths) {
+        const text = await fs.readFile(filePath, "utf8").catch(() => "");
+        hashes.set(pathToFileURL(filePath).href, hashText(text));
+    }
+    return hashes;
+}
+function hashText(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+function resolveManagedLspDiagnosticWaitTimeoutMs(mode) {
     const configured = process.env["GDH_TEST_LSP_DIAGNOSTIC_WAIT_TIMEOUT_MS"];
     if (configured === undefined) {
-        return MANAGED_LSP_DIAGNOSTIC_WAIT_TIMEOUT_MS;
+        return mode === "post_edit"
+            ? MANAGED_LSP_POST_EDIT_DIAGNOSTIC_WAIT_TIMEOUT_MS
+            : MANAGED_LSP_DIAGNOSTIC_WAIT_TIMEOUT_MS;
     }
     const parsed = Number(configured);
     if (!Number.isFinite(parsed) || parsed <= 0) {
-        return MANAGED_LSP_DIAGNOSTIC_WAIT_TIMEOUT_MS;
+        return mode === "post_edit"
+            ? MANAGED_LSP_POST_EDIT_DIAGNOSTIC_WAIT_TIMEOUT_MS
+            : MANAGED_LSP_DIAGNOSTIC_WAIT_TIMEOUT_MS;
     }
     return parsed;
 }
@@ -1102,13 +1236,20 @@ function resolveWorktreeIdentity(targetPath, status, projectConfig) {
 async function resolveCurrentManagedLspIdentity(worktree, projectPath) {
     const testMode = process.env["GDH_TEST_LSP_MODE"];
     if (testMode) {
+        const syntheticVersion = normalizeTestMode(testMode);
+        // Phase 81 / LSP-08 / D-15: honor the version floor for synthetic test versions
+        // so unit tests can exercise the floor-blocked path via GDH_TEST_LSP_MODE.
+        const syntheticFloorViolation = typeof syntheticVersion === "string" &&
+            (syntheticVersion.startsWith("4.5.0") || syntheticVersion.startsWith("4.5.1"));
         return await createManagedLspInstanceIdentity({
             worktree,
             projectPath,
             launcher: "test_fake",
-            editorBinPath: `test_fake:${normalizeTestMode(testMode)}`,
-            editorVersion: normalizeTestMode(testMode),
-            editorVersionReason: null,
+            editorBinPath: `test_fake:${syntheticVersion}`,
+            editorVersion: syntheticVersion,
+            editorVersionReason: syntheticFloorViolation
+                ? "godot_editor_version_unsupported_for_lsp"
+                : null,
         });
     }
     const godotBin = await resolveConfiguredGodotEditorBin({
@@ -1116,15 +1257,25 @@ async function resolveCurrentManagedLspIdentity(worktree, projectPath) {
         environment: process.env,
     });
     const version = godotBin === null ? null : await probeGodotEditorVersion(godotBin);
+    const versionStr = version?.version ?? null;
+    // Phase 81 / LSP-08 / D-15 / Pitfall 4: Godot reports versions like
+    // "4.5.0.stable" or "4.5.1.stable.official"; use a startsWith prefix match
+    // on the 3-part version prefix to handle every suffix form. No semver
+    // dependency is added — the floor check is intentionally narrow.
+    const isFloorViolation = versionStr !== null &&
+        (versionStr.startsWith("4.5.0") || versionStr.startsWith("4.5.1"));
+    const editorVersionReason = godotBin === null
+        ? "godot_editor_not_configured"
+        : isFloorViolation
+            ? "godot_editor_version_unsupported_for_lsp"
+            : (version?.reason ?? null);
     return await createManagedLspInstanceIdentity({
         worktree,
         projectPath,
         launcher: "godot_editor",
         editorBinPath: godotBin,
-        editorVersion: version?.version ?? null,
-        editorVersionReason: godotBin === null
-            ? "godot_editor_not_configured"
-            : (version?.reason ?? "godot_editor_version_unavailable"),
+        editorVersion: versionStr,
+        editorVersionReason,
     });
 }
 async function createManagedLspInstanceIdentity(input) {
@@ -1976,6 +2127,7 @@ function createUnavailableStatus(input) {
             stateRootPath: input.worktree.stateRootPath,
             rawPayload: input.rawPayload ?? null,
         },
+        versionFloorAdvisory: input.versionFloorAdvisory ?? null,
     };
 }
 function isPidAlive(pid) {