@mrclrchtr/supi-lsp 1.16.0 → 2.0.0

package/src/client/client.ts

@@ -5,6 +5,8 @@
 import { type ChildProcess, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import * as path from "node:path";
+import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
+import type { ProgressToken } from "vscode-languageserver-protocol";
 import { CLIENT_CAPABILITIES } from "../config/capabilities.ts";
 import type {
   CodeAction,
@@ -68,6 +70,15 @@ export class LspClient {
   /** Listeners waiting for diagnostics on a specific uri */
   private diagnosticWaiters = new Map<string, Array<() => void>>();
 
+  // ── Readiness (work-done-progress) ──────────────────────────────────
+  private trackedTokens = new Map<ProgressToken, "begin-seen" | "ended">();
+  private _readyPromise: Promise<void> | null = null;
+  private _readyResolve: (() => void) | undefined;
+  private _readyReject: ((err: Error) => void) | undefined;
+  private _isReady = false;
+  private noProgressTimer: ReturnType<typeof setTimeout> | null = null;
+  private tokenTimeouts = new Map<ProgressToken, ReturnType<typeof setTimeout>>();
+
   constructor(
     name: string,
     private readonly config: ServerConfig,
@@ -89,6 +100,11 @@ export class LspClient {
     return this.capabilities;
   }
 
+  /** Whether the server is currently not indexing and ready to serve queries. */
+  get ready(): boolean {
+    return this._isReady;
+  }
+
   // ── Lifecycle ───────────────────────────────────────────────────────
   /** Spawn the server process and perform the initialize handshake. */
   async start(): Promise<void> {
@@ -118,6 +134,8 @@ export class LspClient {
     this.rpc.onNotification((method, params) => {
       if (method === "textDocument/publishDiagnostics") {
         this.handlePublishDiagnostics(params as PublishDiagnosticsParams);
+      } else if (method === "$/progress") {
+        this.handleProgress(params as { token: ProgressToken; value: { kind: string } });
       }
     });
     this.rpc.onRequest((method, params) => this.handleServerRequest(method, params));
@@ -126,6 +144,8 @@ export class LspClient {
     this.process.on("exit", (_code) => {
       if (this._status !== "shutdown") {
         this._status = "error";
+        this.cancelNoProgressTimer();
+        this.rejectReady(new Error("Client crashed"));
       }
       this.rpc?.dispose();
     });
@@ -133,6 +153,7 @@ export class LspClient {
     this.process.on("error", (_err) => {
       if (this._status !== "shutdown") {
         this._status = "error";
+        this.rejectReady(new Error("Client process error"));
       }
     });
 
@@ -151,6 +172,8 @@ export class LspClient {
       this.capabilities = result.capabilities;
       this.rpc.sendNotification("initialized", {});
       this._status = "running";
+
+      this.armNoProgressTimer();
     } catch (err) {
       this._status = "error";
       this.process.kill();
@@ -203,6 +226,15 @@ export class LspClient {
     this.openDocs.clear();
     this.diagnosticStore.clear();
     this.releaseAllDiagnosticWaiters();
+
+    // Clear readiness state
+    if (this.noProgressTimer) {
+      clearTimeout(this.noProgressTimer);
+      this.noProgressTimer = null;
+    }
+    for (const timer of this.tokenTimeouts.values()) clearTimeout(timer);
+    this.tokenTimeouts.clear();
+    this.rejectReady(new Error("Client shutdown"));
   }
 
   // ── Document Synchronization ────────────────────────────────────────
@@ -468,6 +500,7 @@ export class LspClient {
   private async request<T>(method: string, params: unknown): Promise<T | null> {
     if (!this.rpc || this._status !== "running") return null;
     try {
+      await this.getReady();
       return (await this.rpc.sendRequest(method, params)) as T;
     } catch {
       return null;
@@ -482,8 +515,24 @@ export class LspClient {
         return [{ uri: fileToUri(this.root), name: path.basename(this.root) || this.root }];
       case "client/registerCapability":
       case "client/unregisterCapability":
-      case "window/workDoneProgress/create":
         return null;
+      case "window/workDoneProgress/create": {
+        const token = (params as { token: ProgressToken }).token;
+        this.trackedTokens.set(token, "begin-seen");
+        this.cancelNoProgressTimer();
+        this._isReady = false;
+        if (!this._readyPromise) {
+          this._readyPromise = new Promise<void>((resolve, reject) => {
+            this._readyResolve = resolve;
+            this._readyReject = reject;
+          });
+          // Prevent unhandled rejection when rejectReady fires before any
+          // consumer is actively awaiting this promise (e.g. during shutdown).
+          this._readyPromise.catch(() => {});
+        }
+        this.startTokenTimeout(token);
+        return null;
+      }
       default:
         throw new JsonRpcRequestError(-32601, `Method not found: ${method}`);
     }
@@ -569,4 +618,200 @@ export class LspClient {
     this.diagnosticWaiters.delete(uri);
     for (const waiter of waiters) waiter();
   }
+
+  // ── Readiness (work-done-progress) ──────────────────────────────────
+
+  /**
+   * Wait for the server to be ready to serve queries.
+   * Returns immediately if already ready; returns the ongoing promise
+   * if one is pending; creates and returns a new one otherwise.
+   */
+  async getReady(): Promise<void> {
+    if (this._isReady) return;
+    if (this._readyPromise !== null) return this._readyPromise;
+    // If no progress timer was ever armed and no tokens are tracked,
+    // the server was either never started with a real process (test scenario)
+    // or completed before any progress tracking began. Resolve immediately
+    // only when the client is still running — a crash or shutdown clears
+    // both fields but must not report the client as ready.
+    if (this.noProgressTimer === null && this.trackedTokens.size === 0) {
+      if (this._status === "running") this._isReady = true;
+      return;
+    }
+    this._readyPromise = new Promise<void>((resolve, reject) => {
+      this._readyResolve = resolve;
+      this._readyReject = reject;
+    });
+    // Prevent unhandled rejection when rejectReady fires before any
+    // consumer is actively awaiting this promise (e.g. during shutdown).
+    this._readyPromise.catch(() => {});
+    return this._readyPromise;
+  }
+
+  /** Handle the $/progress notification from the server. */
+  private handleProgress(params: { token: ProgressToken; value: { kind: string } }): void {
+    const { token, value } = params;
+    // Defensive: guard against malformed notifications without a value.
+    if (!value || typeof value.kind !== "string") return;
+
+    if (value.kind === "begin") {
+      recordDebugEvent({
+        source: "lsp",
+        level: "debug",
+        category: "readiness.progress-begin",
+        message: `Readiness progress begin for token ${token}`,
+        data: { token },
+      });
+      // Cancel the 2s no-progress grace timer — a server that sends
+      // begin without a prior create is spec-deviant but valid.
+      this.cancelNoProgressTimer();
+      this.trackedTokens.set(token, "begin-seen");
+      this._isReady = false;
+      // Re-arm readiness promise if not already pending
+      if (!this._readyPromise) {
+        this._readyPromise = new Promise<void>((resolve, reject) => {
+          this._readyResolve = resolve;
+          this._readyReject = reject;
+        });
+        // Prevent unhandled rejection when rejectReady fires before any
+        // consumer is actively awaiting this promise (e.g. during shutdown).
+        this._readyPromise.catch(() => {});
+      }
+      this.startTokenTimeout(token);
+    } else if (value.kind === "end") {
+      recordDebugEvent({
+        source: "lsp",
+        level: "debug",
+        category: "readiness.progress-end",
+        message: `Readiness progress end for token ${token}`,
+        data: { token },
+      });
+      this.trackedTokens.set(token, "ended");
+      this.clearTokenTimeout(token);
+      this.checkAllTokensEnded();
+    }
+    // kind: "report" — intentionally no-op
+  }
+
+  /** Check whether all tracked tokens have ended and resolve readiness. */
+  private checkAllTokensEnded(): void {
+    if (this.trackedTokens.size === 0) return;
+    for (const state of this.trackedTokens.values()) {
+      if (state !== "ended") return;
+    }
+    this.trackedTokens.clear();
+    this.resolveReady();
+  }
+
+  /** Resolve the current readiness promise (if any) and mark the client ready. */
+  private resolveReady(): void {
+    if (this._readyResolve) {
+      this._readyResolve();
+      this._readyPromise = null;
+      this._readyResolve = undefined;
+      this._readyReject = undefined;
+    }
+    this._isReady = true;
+    recordDebugEvent({
+      source: "lsp",
+      level: "info",
+      category: "readiness.resolved",
+      message: `LSP client ${this.name} is ready (cwd: ${this.root})`,
+    });
+  }
+
+  /**
+   * Reject the current readiness promise (if any) and mark the client
+   * not ready. Called on shutdown, crash, or restart.
+   */
+  private rejectReady(reason: Error): void {
+    if (this._readyReject) {
+      this._readyReject(reason);
+      this._readyPromise = null;
+      this._readyResolve = undefined;
+      this._readyReject = undefined;
+    }
+    this._isReady = false;
+    this.trackedTokens.clear();
+    for (const timer of this.tokenTimeouts.values()) clearTimeout(timer);
+    this.tokenTimeouts.clear();
+    recordDebugEvent({
+      source: "lsp",
+      level: this._status === "shutdown" ? "debug" : "warning",
+      category: "readiness.rejected",
+      message: `LSP client ${this.name} readiness rejected: ${reason.message}`,
+      data: { status: this._status },
+    });
+  }
+
+  /**
+   * Start a per-token timeout. If the token never receives an "end",
+   * force-end it after `readinessTimeoutMs` (default 10s).
+   */
+  private startTokenTimeout(token: ProgressToken): void {
+    // Clear any existing timeout for this token (e.g., if both
+    // window/workDoneProgress/create and $/progress begin fire).
+    this.clearTokenTimeout(token);
+    const timeoutMs = this.config.readinessTimeoutMs ?? 10_000;
+    const timer = setTimeout(() => {
+      this.trackedTokens.set(token, "ended");
+      this.tokenTimeouts.delete(token);
+      recordDebugEvent({
+        source: "lsp",
+        level: "debug",
+        category: "readiness.token-timeout",
+        message: `Readiness per-token timeout fired for token ${token} after ${timeoutMs}ms`,
+        data: { token, timeoutMs },
+      });
+      this.checkAllTokensEnded();
+    }, timeoutMs);
+    this.tokenTimeouts.set(token, timer);
+  }
+
+  /** Clear the per-token timeout for a completed token. */
+  private clearTokenTimeout(token: ProgressToken): void {
+    const timer = this.tokenTimeouts.get(token);
+    if (timer) {
+      clearTimeout(timer);
+      this.tokenTimeouts.delete(token);
+    }
+  }
+
+  /** Cancel the 2s no-progress grace timer. */
+  private cancelNoProgressTimer(): void {
+    if (this.noProgressTimer) {
+      clearTimeout(this.noProgressTimer);
+      this.noProgressTimer = null;
+      recordDebugEvent({
+        source: "lsp",
+        level: "debug",
+        category: "readiness.no-progress-cancelled",
+        message: `No-progress grace timer cancelled for ${this.name}`,
+      });
+    }
+  }
+
+  /**
+   * Arm the 2s no-progress grace timer. If no server-initiated
+   * progress token arrives within this window, the server is treated
+   * as immediately ready (small project or non-progress-supporting server).
+   *
+   * A server that sends its first $/progress begin after 2s causes
+   * a brief false-ready window — the steady-state re-entrancy in
+   * handleProgress() flips isReady back to false when the begin arrives.
+   */
+  private armNoProgressTimer(): void {
+    this.noProgressTimer = setTimeout(() => {
+      if (this.trackedTokens.size === 0 && this._status === "running") {
+        recordDebugEvent({
+          source: "lsp",
+          level: "debug",
+          category: "readiness.no-progress-resolved",
+          message: `No-progress grace timer resolved for ${this.name}`,
+        });
+        this.resolveReady();
+      }
+      this.noProgressTimer = null;
+    }, 2_000);
+  }
 }

package/src/client/transport.ts

@@ -93,6 +93,10 @@ export class JsonRpcClient {
     const timer = setTimeout(() => tokenSource.cancel(), timeoutMs);
 
     const request = this.connection.sendRequest(method, params, tokenSource.token);
+    // Catch the raw request promise to prevent unhandled rejections when
+    // dispose() cancels the token without a preceding timeout (the raced
+    // promise below covers the timeout-then-dispose path separately).
+    request.catch(() => {});
 
     // Race the request against a timeout so callers don't hang forever.
     // The CancellationToken is also passed to sendRequest so the connection

package/src/config/capabilities.ts

@@ -53,6 +53,9 @@ export const CLIENT_CAPABILITIES: ClientCapabilities = {
       relatedDocumentSupport: true,
     },
   },
+  window: {
+    workDoneProgress: true,
+  },
   workspace: {
     workspaceFolders: false,
     diagnostics: {

package/src/config/config.ts

@@ -2,13 +2,15 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { loadSupiConfigForScope } from "@mrclrchtr/supi-core/config";
 import type { LspConfig, ServerConfig } from "./types.ts";
 
+const CONFIG_DIR = path.dirname(fileURLToPath(import.meta.url));
+
 // Load defaults at module level — resolve relative to this file.
-// pi loads extensions via jiti, which always provides __dirname.
 const DEFAULTS: LspConfig = JSON.parse(
-  fs.readFileSync(path.join(__dirname, "defaults.json"), "utf-8"),
+  fs.readFileSync(path.join(CONFIG_DIR, "defaults.json"), "utf-8"),
 ) as LspConfig;
 
 // ── Public API ────────────────────────────────────────────────────────

package/src/config/lsp-settings.ts

@@ -0,0 +1,102 @@
+// LSP settings helpers — config loading for LSP session lifecycle.
+//
+// These are the non-UI config helpers extracted from settings-registration.ts
+// so they can be consumed by the library-only runtime controller without
+// importing pi-specific UI modules.
+
+import { loadSupiConfig, loadSupiConfigForScope } from "@mrclrchtr/supi-core/config";
+
+// ── Types ────────────────────────────────────────────────────
+
+export interface LspSettings {
+  enabled: boolean;
+  severity: number;
+  active: string[];
+  exclude: string[];
+}
+
+export const LSP_DEFAULTS: LspSettings = {
+  enabled: true,
+  severity: 1,
+  active: [],
+  exclude: [],
+};
+
+// ── Config helpers ───────────────────────────────────────────
+
+/**
+ * Load LSP settings from supi config for the given cwd.
+ *
+ * Merges project and global scopes with defaults, returning the
+ * effective LspSettings for session startup.
+ */
+export function loadLspSettings(cwd: string, homeDir?: string): LspSettings {
+  return loadSupiConfig("lsp", cwd, LSP_DEFAULTS, { homeDir });
+}
+
+/**
+ * Return a user-facing message explaining why LSP may appear disabled.
+ *
+ * **Since the always-on policy:** `lsp.enabled: false` is deprecated and
+ * ignored. This function is kept for backward compatibility with the
+ * settings UI and reports that LSP is always attempted.
+ */
+export function getLspDisabledMessage(cwd: string, homeDir?: string): string {
+  const global = loadSupiConfigForScope("lsp", cwd, LSP_DEFAULTS, { scope: "global", homeDir });
+  const project = loadSupiConfigForScope("lsp", cwd, LSP_DEFAULTS, { scope: "project", homeDir });
+
+  if (project.enabled === false) {
+    return "LSP is always attempted; `lsp.enabled: false` in project settings (.pi/supi/config.json) is deprecated and ignored";
+  }
+  if (global.enabled === false) {
+    return "LSP is always attempted; `lsp.enabled: false` in global settings (~/.pi/agent/supi/config.json) is deprecated and ignored";
+  }
+  return "LSP is always attempted";
+}
+
+// ── Deprecated-key detection (always-on policy) ────────────────
+
+/**
+ * Result of checking for deprecated LSP configuration keys.
+ */
+export interface DeprecatedLspKeys {
+  /** `lsp.enabled` presence in project config. */
+  projectEnabled: boolean;
+  /** `lsp.enabled` presence in global config. */
+  globalEnabled: boolean;
+  /** `lsp.active` presence in project config. */
+  projectActive: boolean;
+  /** `lsp.active` presence in global config. */
+  globalActive: boolean;
+}
+
+/**
+ * Check whether deprecated `lsp.enabled` or `lsp.active` keys exist
+ * in project or global config. These keys are ignored by the always-on
+ * LSP policy but may be present in user config.
+ */
+export function getDeprecatedLspKeys(cwd: string, homeDir?: string): DeprecatedLspKeys {
+  const global = loadSupiConfigForScope("lsp", cwd, LSP_DEFAULTS, { scope: "global", homeDir });
+  const project = loadSupiConfigForScope("lsp", cwd, LSP_DEFAULTS, { scope: "project", homeDir });
+
+  return {
+    projectEnabled: hasExplicitEnabledKey(project),
+    globalEnabled: hasExplicitEnabledKey(global),
+    projectActive: hasExplicitActiveKey(project),
+    globalActive: hasExplicitActiveKey(global),
+  };
+}
+
+/** Whether the loaded settings had an explicit `enabled` key (different from default). */
+function hasExplicitEnabledKey(settings: Partial<{ enabled: boolean }>): boolean {
+  return settings.enabled === false;
+}
+
+/** Whether the loaded settings had an explicit `active` key. */
+function hasExplicitActiveKey(settings: Partial<{ active: string[] }>): boolean {
+  return Array.isArray(settings.active) && settings.active.length > 0;
+}
+
+// Alias for backwards compatibility with the RED test name
+/** @deprecated Use {@link getDeprecatedLspKeys} instead. */
+export const hasDeprecatedLspKeys: typeof getDeprecatedLspKeys = getDeprecatedLspKeys;

package/src/config/server-actions.ts

@@ -0,0 +1,59 @@
+// Server capability action label helpers — maps LSP capabilities to readable action labels.
+
+import type { ServerCapabilities } from "../config/types.ts";
+
+interface LspServerSupportedActionSpec {
+  label: string;
+  isSupported: (capabilities: ServerCapabilities | null | undefined) => boolean;
+}
+
+const LSP_SERVER_SUPPORTED_ACTION_SPECS: readonly LspServerSupportedActionSpec[] = [
+  {
+    label: "diagnostics [optional file]",
+    isSupported: () => true,
+  },
+  {
+    label: "hover(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.hoverProvider),
+  },
+  {
+    label: "definition(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.definitionProvider),
+  },
+  {
+    label: "references(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.referencesProvider),
+  },
+  {
+    label: "implementation(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.implementationProvider),
+  },
+  {
+    label: "symbols(file)",
+    isSupported: (capabilities) => Boolean(capabilities?.documentSymbolProvider),
+  },
+  {
+    label: "workspace_symbols(query)",
+    isSupported: (capabilities) => Boolean(capabilities?.workspaceSymbolProvider),
+  },
+  {
+    label: "rename(file,line,char,newName)",
+    isSupported: (capabilities) => Boolean(capabilities?.renameProvider),
+  },
+  {
+    label: "code_actions(file,line,char)",
+    isSupported: (capabilities) => Boolean(capabilities?.codeActionProvider),
+  },
+] as const;
+
+/**
+ * Get the list of supported LSP server actions based on capabilities.
+ */
+export function getSupportedLspServerActions(
+  capabilities: ServerCapabilities | null | undefined,
+): string[] {
+  if (!capabilities) return [];
+  return LSP_SERVER_SUPPORTED_ACTION_SPECS.filter((spec) => spec.isSupported(capabilities)).map(
+    (spec) => spec.label,
+  );
+}

package/src/config/server-config.ts

@@ -8,6 +8,8 @@ export interface ServerConfig {
   rootMarkers: string[];
   enabled?: boolean;
   initializationOptions?: unknown;
+  /** Maximum time to wait for a single $/progress cycle, in ms. Default: 10_000. */
+  readinessTimeoutMs?: number;
 }
 
 /** LSP configuration keyed by language name (e.g. `typescript`, `python`). */
@@ -25,6 +27,8 @@ export interface ProjectServerInfo extends DetectedProjectServer {
   status: "running" | "error" | "unavailable";
   supportedActions: string[];
   openFiles: string[];
+  /** Whether the LSP server is currently not indexing and ready to serve queries. */
+  ready: boolean;
 }
 
 /** A language whose source files are present but the server binary is missing. */

package/src/index.ts

@@ -2,6 +2,11 @@
 // Consumers should import the published API surface from
 // `@mrclrchtr/supi-lsp/api`, not the package root.
 
+export type { LspSettings } from "./config/lsp-settings.ts";
+export {
+  getLspDisabledMessage,
+  loadLspSettings,
+} from "./config/lsp-settings.ts";
 export type {
   CodeAction,
   Diagnostic,
@@ -17,9 +22,15 @@ export type {
   WorkspaceSymbol,
 } from "./config/types.ts";
 export { toLspPosition, toOneBasedPosition } from "./coordinates.ts";
+export type {
+  LspControllerState,
+  LspStartResult,
+} from "./session/runtime-controller.ts";
+export { LspRuntimeController } from "./session/runtime-controller.ts";
 export type {
   OutstandingDiagnosticSummaryEntry,
   RecoverDiagnosticsResult,
+  SemanticReadinessResult,
   SessionLspServiceState,
   WorkspaceDiagnosticSummaryEntry,
 } from "./session/service-registry.ts";

package/src/manager/capability-index.ts

@@ -1,7 +1,7 @@
 // Capability index — indexes and queries server capabilities.
 
+import { getSupportedLspServerActions } from "../config/server-actions.ts";
 import type { ServerCapabilities } from "../config/types.ts";
-import { getSupportedLspServerActions } from "../tool/tool-specs.ts";
 import type { LspManager } from "./manager.ts";
 
 /**

package/src/manager/manager-project-info.ts

@@ -1,7 +1,7 @@
 import type { LspClient } from "../client/client.ts";
+import { getSupportedLspServerActions } from "../config/server-actions.ts";
 import type { ProjectServerInfo } from "../config/server-config.ts";
 import { displayRelativeFilePath } from "../summary.ts";
-import { getSupportedLspServerActions } from "../tool/tool-specs.ts";
 
 interface ProjectServerInfoInput {
   serverName: string;
@@ -31,5 +31,6 @@ export function buildProjectServerInfo(
     status,
     supportedActions: getSupportedLspServerActions(input.client?.serverCapabilities),
     openFiles: input.client?.openFiles.map((file) => displayRelativeFilePath(file, cwd)) ?? [],
+    ready: input.client?.ready ?? false,
   };
 }