@remnic/coding-graph 9.3.759

package/src/lsp/client.ts

@@ -0,0 +1,484 @@
+/**
+ * Minimal JSON-RPC-over-stdio LSP client.
+ *
+ * Implements exactly the protocol subset the resolution pass needs
+ * (LSP 3.17): initialize → initialized → didOpen → definition →
+ * shutdown → exit. No npm LSP framework — the protocol subset is small
+ * and a dependency here would bloat the optional package (issue #1555).
+ *
+ * Failure discipline (rule 13): every operation degrades to a tagged
+ * `LspDegradation` — the client NEVER throws to a caller. Server crashes
+ * mid-run, protocol errors, and timeouts all surface as distinct codes.
+ *
+ * Lifecycle: the client owns the child process. `dispose()` sends
+ * shutdown + exit, then hard-kills (SIGKILL) any lingering process —
+ * no zombie children survive (tested).
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+
+import {
+  encodeLspFrame,
+  LspFrameDecoder,
+} from "./framing.js";
+import {
+  type JsonRpcRequest,
+  type LspInitializeParams,
+  type LspInitializeResult,
+  type LspLocation,
+  type LspTextDocumentItem,
+  type LspTextDocumentPositionParams,
+} from "./types.js";
+import {
+  lspDegradation,
+  type LspDegradation,
+  type LspDegradationCode,
+  type LspResult,
+} from "./degradation.js";
+import type { LspServerLaunchSpec } from "./config.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Pending-request entry — stores the resolver pair + timeout handle.
+// ──────────────────────────────────────────────────────────────────────────
+
+interface PendingRequest {
+  readonly resolve: (value: unknown) => void;
+  readonly reject: (degradation: LspDegradation) => void;
+  readonly timer: ReturnType<typeof setTimeout>;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Connection options
+// ──────────────────────────────────────────────────────────────────────────
+
+export interface LspClientOptions {
+  readonly launchSpec: LspServerLaunchSpec;
+  readonly rootUri: string | null;
+  readonly timeoutMs: number;
+  /**
+   * Optional spawn override — test seam. When provided, the client calls
+   * this instead of `child_process.spawn`. Must return a ChildProcess-
+   * compatible object with stdin/stdout streams.
+   */
+  readonly spawnFn?: typeof spawn;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// LspClient — the connection. One instance per server process.
+// ──────────────────────────────────────────────────────────────────────────
+
+export class LspClient {
+  private readonly child: ChildProcess;
+  private readonly decoder = new LspFrameDecoder();
+  private readonly rootUri: string | null;
+  private readonly timeoutMs: number;
+  private nextId = 1;
+  private readonly pending = new Map<number, PendingRequest>();
+  private disposed = false;
+  private crashed = false;
+  private crashCode: LspDegradationCode | null = null;
+  private serverCapabilities: LspInitializeResult["capabilities"] | null = null;
+
+  private constructor(child: ChildProcess, rootUri: string | null, timeoutMs: number) {
+    this.child = child;
+    this.rootUri = rootUri;
+    this.timeoutMs = timeoutMs;
+
+    // Wire stdout → decoder → message dispatcher.
+    this.child.stdout?.setEncoding("utf8");
+    this.child.stdout?.on("data", (chunk: Buffer | string) => this.onStdoutData(chunk));
+
+    // Drain stderr so the OS pipe buffer doesn't fill and block the server.
+    this.child.stderr?.on("data", () => {});
+
+    // Unexpected exit → mark crashed, reject all pending.
+    this.child.on("exit", (code, signal) => this.onChildExit(code, signal));
+    this.child.on("error", (err) => this.onChildError(err));
+  }
+
+  /**
+   * Spawn the server and perform the initialize handshake. Returns a
+   * tagged result — `{ ok: true, client }` on success, or a degradation
+   * on failure (server_missing, handshake_timeout, handshake_error).
+   */
+  static async connect(options: LspClientOptions): Promise<
+    | { ok: true; client: LspClient }
+    | { ok: false; degradation: LspDegradation }
+  > {
+    let child: ChildProcess;
+    const spawnFn = options.spawnFn ?? spawn;
+    try {
+      child = spawnFn(options.launchSpec.command, [...options.launchSpec.args], {
+        stdio: ["pipe", "pipe", "pipe"],
+        shell: false,
+        // The server inherits our cwd so relative rootUri paths resolve.
+        cwd: process.cwd(),
+      });
+    } catch {
+      return {
+        ok: false,
+        degradation: lspDegradation(
+          "server_missing",
+          `failed to spawn ${options.launchSpec.command}`,
+        ),
+      };
+    }
+
+    // If spawn emitted 'error' synchronously (ENOENT), treat as missing.
+    // We detect this by checking if the child has already exited.
+    if (child.exitCode !== null && child.exitCode !== undefined) {
+      return {
+        ok: false,
+        degradation: lspDegradation("server_missing"),
+      };
+    }
+
+    const client = new LspClient(child, options.rootUri, options.timeoutMs);
+
+    // If the spawn errored asynchronously (ENOENT fires as 'error' event),
+    // the client.crashed flag is set by onChildError. Check after wiring.
+    if (client.crashed) {
+      return {
+        ok: false,
+        degradation: lspDegradation(client.crashCode ?? "server_crashed"),
+      };
+    }
+
+    // ── initialize handshake ──
+    const initParams: LspInitializeParams = {
+      processId: process.pid,
+      rootUri: options.rootUri,
+      capabilities: {},
+    };
+    const initResult = await client.request("initialize", initParams);
+    if (!initResult.ok) {
+      // Remap request_timeout → handshake_timeout (the timeout happened
+      // during the initialize handshake). protocol_error, server_crashed,
+      // and server_missing pass through with their original codes — they
+      // describe the specific failure precisely enough.
+      await client.dispose();
+      const code =
+        initResult.degradation.code === "request_timeout"
+          ? "handshake_timeout"
+          : initResult.degradation.code;
+      return {
+        ok: false,
+        degradation: lspDegradation(code, initResult.degradation.detail),
+      };
+    }
+
+    if (initResult.value === null || typeof initResult.value !== "object") {
+      await client.dispose();
+      return {
+        ok: false,
+        degradation: lspDegradation("protocol_error", "initialize response missing or invalid"),
+      };
+    }
+    const initResponse = initResult.value as LspInitializeResult;
+    client.serverCapabilities = initResponse.capabilities;
+
+    // initialized notification (no response expected).
+    client.notify("initialized", {});
+
+    return { ok: true, client };
+  }
+
+  /**
+   * Send `textDocument/didOpen` — notifies the server about an open
+   * document with its full content. No response expected.
+   */
+  didOpen(item: LspTextDocumentItem): void {
+    this.notify("textDocument/didOpen", { textDocument: item });
+  }
+
+  /**
+   * Send `textDocument/definition` for a position in a document. Returns
+   * the definition locations (may be empty, a single location, or an
+   * array). Degrades on timeout/error/crash — never throws.
+   */
+  async definition(
+    params: LspTextDocumentPositionParams,
+  ): Promise<LspResult<{ locations: LspLocation[] }>> {
+    if (this.disposed || this.crashed) {
+      return {
+        ok: false,
+        degradation: lspDegradation("server_crashed"),
+      };
+    }
+    const result = await this.request("textDocument/definition", params);
+    if (!result.ok) {
+      return result;
+    }
+    // LSP allows Location | Location[] | null for definition.
+    const value = result.value;
+    let locations: LspLocation[];
+    if (value === null || value === undefined) {
+      locations = [];
+    } else if (Array.isArray(value)) {
+      locations = value as LspLocation[];
+    } else {
+      locations = [value as LspLocation];
+    }
+    return { ok: true, locations };
+  }
+
+  /**
+   * Send `shutdown`, then `exit`, then SIGKILL if the process lingers.
+   * Idempotent — safe to call multiple times. After dispose, no child
+   * process remains (tested — zombie cleanup).
+   */
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+
+    // Reject all pending requests immediately.
+    for (const [id, entry] of this.pending) {
+      clearTimeout(entry.timer);
+      entry.reject(lspDegradation("server_crashed"));
+      this.pending.delete(id);
+    }
+
+    // Try graceful shutdown: send shutdown request, then exit notification.
+    if (!this.crashed && this.child.stdin && !this.child.stdin.destroyed) {
+      try {
+        const promise = new Promise<void>((resolve) => {
+          // Send shutdown — don't wait for a response longer than the timeout.
+          this.child.stdin?.write(encodeLspFrame({ jsonrpc: "2.0", id: 0, method: "shutdown" }));
+          this.child.stdin?.write(encodeLspFrame({ jsonrpc: "2.0", method: "exit" }));
+          // Give the server a brief window to exit cleanly.
+          const timer = setTimeout(resolve, 500);
+          this.child.on("exit", () => {
+            clearTimeout(timer);
+            resolve();
+          });
+        });
+        await promise;
+      } catch {
+        // Best-effort — if writing fails, hard-kill below.
+      }
+    }
+
+    // Hard kill — ensures no zombie survives even if graceful exit failed.
+    this.hardKill();
+  }
+
+  /** Returns the pid of the child process (for zombie-cleanup tests). */
+  get pid(): number | undefined {
+    return this.child.pid;
+  }
+
+  /** True if the server reported definitionProvider capability. */
+  get supportsDefinition(): boolean {
+    const caps = this.serverCapabilities;
+    return caps !== null && Boolean(caps.definitionProvider);
+  }
+
+  // ──────────────────────────────────────────────────────────────────────
+  // Internal — JSON-RPC request/notification machinery
+  // ──────────────────────────────────────────────────────────────────────
+
+  /**
+   * Send a request and await its response. Returns the `result` field
+   * on success, or a degradation on timeout/error/crash/protocol-error.
+   */
+  private request(method: string, params: unknown): Promise<
+    | { ok: true; value: unknown }
+    | { ok: false; degradation: LspDegradation }
+  > {
+    if (this.disposed || this.crashed) {
+      return Promise.resolve({
+        ok: false,
+        degradation: lspDegradation("server_crashed"),
+      });
+    }
+    const id = this.nextId++;
+    const message: JsonRpcRequest = { jsonrpc: "2.0", id, method, params };
+    const promise = new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const entry = this.pending.get(id);
+        if (entry) {
+          this.pending.delete(id);
+          entry.reject(lspDegradation("request_timeout", `method=${method}`));
+        }
+      }, this.timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      try {
+        const frame = encodeLspFrame(message);
+        if (!this.child.stdin || this.child.stdin.destroyed) {
+          clearTimeout(timer);
+          this.pending.delete(id);
+          reject(lspDegradation("server_crashed"));
+          return;
+        }
+        this.child.stdin.write(frame);
+      } catch {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(lspDegradation("server_crashed"));
+      }
+    });
+
+    return promise.then(
+      (value: unknown) => ({ ok: true as const, value }),
+      (degradation: LspDegradation) => ({ ok: false as const, degradation }),
+    );
+  }
+
+  /**
+   * Send a notification (no response expected). Best-effort — if the
+   * write fails, the next request will surface the crash.
+   */
+  private notify(method: string, params: unknown): void {
+    if (this.disposed || this.crashed) return;
+    try {
+      const message: JsonRpcRequest = { jsonrpc: "2.0", method, params };
+      this.child.stdin?.write(encodeLspFrame(message));
+    } catch {
+      // Best-effort — notifications have no response path.
+    }
+  }
+
+  /**
+   * Dispatch a decoded JSON-RPC message. Correlates responses to pending
+   * requests by id; ignores server-initiated notifications (we don't
+   * need them for the resolution pass).
+   */
+  /**
+   * Dispatch a decoded JSON-RPC message. Correlates responses to pending
+   * requests by id; ignores server-initiated notifications.
+   */
+  private dispatchMessage(msg: unknown): void {
+    if (typeof msg !== "object" || msg === null) return;
+    const rpc = msg as Record<string, unknown>;
+    if (rpc.id === undefined || (rpc.result === undefined && rpc.error === undefined)) {
+      return;
+    }
+    const id = typeof rpc.id === "number" ? rpc.id : Number(rpc.id);
+    const entry = this.pending.get(id);
+    if (!entry) return;
+    clearTimeout(entry.timer);
+    this.pending.delete(id);
+    if (rpc.error !== undefined) {
+      // Don't echo raw server error text — it may contain absolute paths.
+      entry.reject(lspDegradation("request_error", "server returned an error response"));
+    } else {
+      entry.resolve(rpc.result);
+    }
+  }
+
+  /**
+   * stdout data handler — feed the decoder, dispatch complete messages,
+   * detect protocol errors.
+   */
+  private onStdoutData(chunk: Buffer | string): void {
+    const result = this.decoder.feed(chunk);
+    if (!result.ok) {
+      this.handleProtocolError(result.error.detail);
+      return;
+    }
+    for (const msg of result.messages) {
+      this.dispatchMessage(msg);
+    }
+  }
+
+  /**
+   * Handle an unexpected child exit. All pending requests are rejected
+   * with server_crashed.
+   */
+  private onChildExit(code: number | null, signal: NodeJS.Signals | null): void {
+    // Normal exit during dispose — don't mark as crashed.
+    if (this.disposed) return;
+    this.crashed = true;
+    this.crashCode = "server_crashed";
+    const detail =
+      code !== null ? `server exited with code ${code}` : `server killed by ${signal}`;
+    for (const [id, entry] of this.pending) {
+      clearTimeout(entry.timer);
+      entry.reject(lspDegradation("server_crashed", detail));
+      this.pending.delete(id);
+    }
+  }
+
+  /**
+   * Handle a spawn error (ENOENT etc). Marks the server as missing.
+   */
+  private onChildError(err: Error): void {
+    // ENOENT = binary not found; other spawn errors = server present but failing.
+    this.crashed = true;
+    const isENOENT = err.message.includes("ENOENT");
+    this.crashCode = isENOENT ? "server_missing" : "server_crashed";
+    const detail = isENOENT ? undefined : "spawn error";
+    for (const [id, entry] of this.pending) {
+      clearTimeout(entry.timer);
+      entry.reject(lspDegradation(this.crashCode, detail));
+      this.pending.delete(id);
+    }
+  }
+
+  /**
+   * Protocol error — the stream produced a malformed frame. Reject all
+   * pending and mark disposed so no further requests can be sent.
+   */
+  private handleProtocolError(detail: string): void {
+    this.crashed = true;
+    for (const [id, entry] of this.pending) {
+      clearTimeout(entry.timer);
+      entry.reject(lspDegradation("protocol_error", detail));
+      this.pending.delete(id);
+    }
+  }
+
+  /**
+   * Hard-kill the child process: SIGKILL. Called by dispose() as a
+   * final cleanup guarantee. Also called if the graceful shutdown path
+   * fails. Uses `kill` which is a no-op if the process already exited.
+   */
+  private hardKill(): void {
+    try {
+      if (this.child.pid !== undefined && !this.child.killed) {
+        this.child.kill("SIGKILL");
+      }
+    } catch {
+      // Best-effort — the process may have already exited.
+    }
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// URI helpers — convert between file paths and LSP URIs.
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Convert a repo-relative or absolute file path to a `file://` URI.
+ * Handles Windows drive letters (C:\ → file:///C:/).
+ */
+export function pathToUri(filePath: string): string {
+  const abs = path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
+  const normalized = abs.replace(/\\/g, "/");
+  // Windows drive paths need a leading slash: C:/foo → /C:/foo → file:///C:/foo
+  const withSlash = /^[A-Za-z]:/.test(normalized) ? `/${normalized}` : normalized;
+  return `file://${withSlash}`;
+}
+
+/**
+ * Convert a `file://` URI back to an absolute file path.
+ */
+export function uriToPath(uri: string): string {
+  if (uri.startsWith("file://")) {
+    let rest = uri.slice("file://".length);
+    // Decode percent-encoded characters (e.g. %20 → space) per RFC 8089.
+    try {
+      rest = decodeURIComponent(rest);
+    } catch {
+      // Malformed escape sequence — keep raw path (best-effort).
+    }
+    // Windows: file:///C:/foo → C:/foo
+    if (/^\/[A-Za-z]:/.test(rest)) {
+      return rest.slice(1).replace(/\//g, path.sep);
+    }
+    // Unix: file:///foo → /foo
+    return rest.replace(/\//g, path.sep);
+  }
+  return uri;
+}

package/src/lsp/config.ts

@@ -0,0 +1,219 @@
+/**
+ * LSP configuration types and defaults (issue #1555 — rule 30/48).
+ *
+ * `codingGraph.lsp.enabled` defaults `false`. Enabling LSP with zero
+ * servers installed must produce a working index identical to Phase A
+ * plus visible degradations — the characterization test proves this.
+ *
+ * Env overrides follow gotcha 9: `REMNIC_CODING_GRAPH_LSP_ENABLED` with
+ * `ENGRAM_` fallback.
+ */
+import process from "node:process";
+
+import type { CodingGraphLanguage } from "@remnic/core";
+
+import type { LspDegradation } from "./degradation.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Server launch spec — argv array end-to-end (rule 10).
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * How to launch a language server: command + argv. Always an array of
+ * strings — never a shell string — so injection via config is impossible
+ * (rule 10: argv arrays end-to-end).
+ */
+export interface LspServerLaunchSpec {
+  readonly command: string;
+  readonly args: readonly string[];
+}
+
+/**
+ * Per-language server overrides. Keys are language identifiers (matching
+ * {@link CodingGraphLanguage}); values are launch specs that REPLACE the
+ * default. An unknown language key is an error (rule 51 — list supported
+ * languages).
+ */
+export type LspServerOverrides = Partial<Record<CodingGraphLanguage, LspServerLaunchSpec>>;
+
+// ──────────────────────────────────────────────────────────────────────────
+// Configuration shape
+// ──────────────────────────────────────────────────────────────────────────
+
+export interface LspConfig {
+  /** Master switch — default false (rule 30/48). */
+  readonly enabled: boolean;
+  /** Per-language server overrides (default: empty — use registry defaults). */
+  readonly servers: LspServerOverrides;
+  /** Handshake + per-request timeout in ms (default 3000). */
+  readonly timeoutMs: number;
+  /** Max definition requests per index run (default 500). */
+  readonly maxRequestsPerRun: number;
+}
+
+export const DEFAULT_LSP_TIMEOUT_MS = 3_000;
+export const DEFAULT_LSP_MAX_REQUESTS_PER_RUN = 500;
+
+export const DEFAULT_LSP_CONFIG: LspConfig = {
+  enabled: false,
+  servers: {},
+  timeoutMs: DEFAULT_LSP_TIMEOUT_MS,
+  maxRequestsPerRun: DEFAULT_LSP_MAX_REQUESTS_PER_RUN,
+};
+
+/**
+ * Parse and validate user-supplied LSP config. Unknown keys in `servers`
+ * are rejected with a degradation listing supported languages (rule 51).
+ * Non-executable absolute paths are rejected (rule 24 analog).
+ *
+ * Returns `{ ok: true, config }` or `{ ok: false, degradation }` — never
+ * throws (rule 13).
+ */
+export type LspConfigParseResult =
+  | { readonly ok: true; readonly config: LspConfig }
+  | { readonly ok: false; readonly degradation: LspDegradation };
+
+/**
+ * Parse the `enabled` flag strictly. Boolean values pass through; strings
+ * like `"false"`, `"0"`, `"no"`, and `""` are false (so env/CLI overrides
+ * work as operators expect). Any other truthy value enables.
+ */
+function parseEnabledFlag(v: unknown): boolean {
+  if (typeof v === "boolean") return v;
+  if (typeof v === "string") {
+    const lower = v.trim().toLowerCase();
+    return lower !== "false" && lower !== "0" && lower !== "no" && lower !== "";
+  }
+  return Boolean(v);
+}
+
+/**
+ * Parse and validate user-supplied LSP config. Unknown keys in `servers`
+ * are rejected with a degradation listing supported languages (rule 51).
+ * Non-executable absolute paths are rejected (rule 24 analog).
+ *
+ * Returns `{ ok: true, config }` or `{ ok: false, degradation }` — never
+ * throws (rule 13).
+ */
+export function parseLspConfig(
+  raw: unknown,
+  knownLanguages: readonly CodingGraphLanguage[],
+): LspConfigParseResult {
+  if (raw === null || raw === undefined) {
+    return { ok: true, config: DEFAULT_LSP_CONFIG };
+  }
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return {
+      ok: false,
+      degradation: {
+        backend: "lsp",
+        code: "protocol_error",
+        detail: "codingGraph.lsp must be an object",
+      },
+    };
+  }
+  const obj = raw as Record<string, unknown>;
+  const knownSet = new Set(knownLanguages);
+
+  const enabled = obj.enabled === undefined ? false : parseEnabledFlag(obj.enabled);
+  const timeoutMs = obj.timeoutMs === undefined ? DEFAULT_LSP_TIMEOUT_MS : Number(obj.timeoutMs);
+  const maxRequestsPerRun =
+    obj.maxRequestsPerRun === undefined ? DEFAULT_LSP_MAX_REQUESTS_PER_RUN : Number(obj.maxRequestsPerRun);
+
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+    return {
+      ok: false,
+      degradation: {
+        backend: "lsp",
+        code: "protocol_error",
+        detail: `lsp.timeoutMs must be a non-negative number, got ${JSON.stringify(obj.timeoutMs)}`,
+      },
+    };
+  }
+  if (!Number.isFinite(maxRequestsPerRun) || maxRequestsPerRun < 0) {
+    return {
+      ok: false,
+      degradation: {
+        backend: "lsp",
+        code: "protocol_error",
+        detail: `lsp.maxRequestsPerRun must be a non-negative number, got ${JSON.stringify(obj.maxRequestsPerRun)}`,
+      },
+    };
+  }
+
+  const servers: Partial<Record<CodingGraphLanguage, LspServerLaunchSpec>> = {};
+  if (obj.servers !== undefined && obj.servers !== null) {
+    if (typeof obj.servers !== "object" || Array.isArray(obj.servers)) {
+      return {
+        ok: false,
+        degradation: {
+          backend: "lsp",
+          code: "protocol_error",
+          detail: "lsp.servers must be an object",
+        },
+      };
+    }
+    for (const [lang, spec] of Object.entries(obj.servers as Record<string, unknown>)) {
+      if (!knownSet.has(lang as CodingGraphLanguage)) {
+        return {
+          ok: false,
+          degradation: {
+            backend: "lsp",
+            code: "unknown_language",
+            detail: `unknown language "${lang}" in lsp.servers; supported: ${knownLanguages.join(", ")}`,
+          },
+        };
+      }
+      if (typeof spec !== "object" || spec === null || Array.isArray(spec)) {
+        return {
+          ok: false,
+          degradation: {
+            backend: "lsp",
+            code: "protocol_error",
+            detail: `lsp.servers.${lang} must be an object`,
+          },
+        };
+      }
+      const s = spec as Record<string, unknown>;
+      if (typeof s.command !== "string" || s.command.length === 0) {
+        return {
+          ok: false,
+          degradation: {
+            backend: "lsp",
+            code: "protocol_error",
+            detail: `lsp.servers.${lang}.command must be a non-empty string`,
+          },
+        };
+      }
+      if (!Array.isArray(s.args) || s.args.some((a) => typeof a !== "string")) {
+        return {
+          ok: false,
+          degradation: {
+            backend: "lsp",
+            code: "protocol_error",
+            detail: `lsp.servers.${lang}.args must be an array of strings`,
+          },
+        };
+      }
+      servers[lang as CodingGraphLanguage] = {
+        command: s.command,
+        args: [...(s.args as string[])],
+      };
+    }
+  }
+
+  return { ok: true, config: { enabled, servers, timeoutMs, maxRequestsPerRun } };
+}
+
+/**
+ * Read the env-var override for `lsp.enabled`. Returns the raw string
+ * value or null. The caller decides how to interpret it (gotcha 9:
+ * `REMNIC_` primary, `ENGRAM_` fallback).
+ */
+export function readLspEnabledEnv(): string | null {
+  return (
+    process.env.REMNIC_CODING_GRAPH_LSP_ENABLED ??
+    process.env.ENGRAM_CODING_GRAPH_LSP_ENABLED ??
+    null
+  );
+}