@mrclrchtr/supi-lsp 0.1.0 → 1.0.0

package/{client.ts → src/client/client.ts}

@@ -1,15 +1,17 @@
 // LSP Client — wraps a server process + JsonRpcClient.
 // Handles initialize handshake, document sync, shutdown, and crash recovery.
 
+// biome-ignore lint/nursery/noExcessiveLinesPerFile: LspClient remains a cohesive stateful wrapper; refresh logic is already split out.
 import { type ChildProcess, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { CLIENT_CAPABILITIES } from "./capabilities.ts";
-import { JsonRpcClient } from "./transport.ts";
+import { CLIENT_CAPABILITIES } from "../capabilities.ts";
 import type {
   CodeAction,
   CodeActionContext,
   Diagnostic,
+  DidChangeWatchedFilesParams,
   DocumentSymbol,
+  FileEvent,
   Hover,
   InitializeResult,
   Location,
@@ -24,14 +26,15 @@ import type {
   TextDocumentItem,
   VersionedTextDocumentIdentifier,
   WorkspaceEdit,
-} from "./types.ts";
-import { detectLanguageId, fileToUri, uriToFile } from "./utils.ts";
+  WorkspaceSymbol,
+} from "../types.ts";
+import { detectLanguageId, fileToUri, uriToFile } from "../utils.ts";
+import { JsonRpcClient } from "./transport.ts";
 
 const SHUTDOWN_TIMEOUT_MS = 5_000;
 const DIAGNOSTIC_WAIT_MS = 3_000;
 
 // ── Types ─────────────────────────────────────────────────────────────
-
 export type ClientStatus = "initializing" | "running" | "error" | "shutdown";
 
 export interface DiagnosticEntry {
@@ -39,8 +42,15 @@ export interface DiagnosticEntry {
   diagnostics: Diagnostic[];
 }
 
-// ── LspClient ─────────────────────────────────────────────────────────
+/** Internal metadata tracked alongside cached diagnostics. */
+export interface DiagnosticCacheEntry {
+  diagnostics: Diagnostic[];
+  receivedAt: number;
+  version?: number;
+  resultId?: string;
+}
 
+// ── LspClient ─────────────────────────────────────────────────────────
 export class LspClient {
   readonly name: string;
   readonly root: string;
@@ -52,8 +62,8 @@ export class LspClient {
 
   /** Open documents: uri → { version, languageId } */
   private openDocs = new Map<string, { version: number; languageId: string }>();
-  /** Per-file diagnostics from the server */
-  private diagnosticStore = new Map<string, Diagnostic[]>();
+  /** Per-file diagnostics with freshness metadata */
+  private diagnosticStore = new Map<string, DiagnosticCacheEntry>();
   /** Listeners waiting for diagnostics on a specific uri */
   private diagnosticWaiters = new Map<string, Array<() => void>>();
 
@@ -74,8 +84,11 @@ export class LspClient {
     return Array.from(this.openDocs.keys()).map(uriToFile);
   }
 
-  // ── Lifecycle ───────────────────────────────────────────────────────
+  get serverCapabilities(): ServerCapabilities | null {
+    return this.capabilities;
+  }
 
+  // ── Lifecycle ───────────────────────────────────────────────────────
   /** Spawn the server process and perform the initialize handshake. */
   async start(): Promise<void> {
     const cmd = this.config.command;
@@ -181,10 +194,10 @@ export class LspClient {
 
     this.openDocs.clear();
     this.diagnosticStore.clear();
+    this.releaseAllDiagnosticWaiters();
   }
 
   // ── Document Synchronization ────────────────────────────────────────
-
   /** Open a document (or re-sync if already open). */
   didOpen(filePath: string, content: string): void {
     if (!this.rpc || this._status !== "running") return;
@@ -267,49 +280,114 @@ export class LspClient {
   }
 
   // ── Diagnostics ─────────────────────────────────────────────────────
-
   /** Get stored diagnostics for a file. */
   getDiagnostics(filePath: string): Diagnostic[] {
-    return this.diagnosticStore.get(fileToUri(filePath)) ?? [];
+    return this.diagnosticStore.get(fileToUri(filePath))?.diagnostics ?? [];
   }
 
-  /** Get all stored diagnostics across all files. */
+  /**
+   * Get all stored diagnostics across all files.
+   *
+   * Filters out empty entries and — defensively — files that no longer exist
+   * on disk. The latter guards against a race where a `publishDiagnostics`
+   * notification (already in-flight) arrives *after* `pruneMissingFiles()`
+   * has removed the file from `openDocs`, recreating a stale cache entry.
+   */
   getAllDiagnostics(): DiagnosticEntry[] {
     const result: DiagnosticEntry[] = [];
-    for (const [uri, diagnostics] of this.diagnosticStore) {
-      if (diagnostics.length > 0) {
-        result.push({ uri, diagnostics });
-      }
+    for (const [uri, entry] of this.diagnosticStore) {
+      if (entry.diagnostics.length === 0) continue;
+      // Defensive: drop diagnostics for files deleted after prune. Late
+      // in-flight publishDiagnostics notifications can recreate stale entries.
+      if (!existsSync(uriToFile(uri))) continue;
+      result.push({ uri, diagnostics: entry.diagnostics });
     }
     return result;
   }
 
+  /** Get the internal cache entry for a file (exposed for testing / version checks). */
+  getDiagnosticCacheEntry(uri: string): DiagnosticCacheEntry | undefined {
+    return this.diagnosticStore.get(uri);
+  }
+
+  /**
+   * Clear all pull-diagnostic result IDs, forcing full (not `unchanged`)
+   * pull diagnostic responses on the next refresh cycle.
+   *
+   * Use this after file creation/write operations so that cross-file
+   * diagnostics (e.g., `Cannot find module` errors in importing files)
+   * are fully re-computed instead of returned as `unchanged`.
+   */
+  clearPullResultIds(): void {
+    for (const entry of this.diagnosticStore.values()) {
+      delete entry.resultId;
+    }
+  }
+
+  /** Get all currently open document URIs. */
+  get openUris(): string[] {
+    return Array.from(this.openDocs.keys());
+  }
+
+  /** Check if server supports pull diagnostics. */
+  get hasDiagnosticProvider(): boolean {
+    return (
+      this.capabilities?.diagnosticProvider !== undefined &&
+      this.capabilities.diagnosticProvider !== false
+    );
+  }
+
+  /** Notify the server that watched workspace files changed. */
+  notifyWorkspaceFileChanges(changes: FileEvent[]): void {
+    if (!this.rpc || this._status !== "running" || changes.length === 0) return;
+    this.rpc.sendNotification("workspace/didChangeWatchedFiles", {
+      changes,
+    } satisfies DidChangeWatchedFilesParams);
+  }
+
+  /**
+   * Re-read and re-sync all currently open, existing documents.
+   * Delegates to client-refresh module.
+   */
+  async refreshOpenDiagnostics(
+    options: { maxWaitMs?: number; quietMs?: number } = {},
+  ): Promise<void> {
+    const { refreshClientOpenDiagnostics } = await import("./client-refresh.ts");
+    return refreshClientOpenDiagnostics(this, options);
+  }
+
   /**
    * Sync a file and wait for diagnostics (up to timeout).
    * Returns diagnostics for the file.
    */
   async syncAndWaitForDiagnostics(filePath: string, content: string): Promise<Diagnostic[]> {
     const uri = fileToUri(filePath);
+    const syncStart = Date.now();
 
     // Sync the content
     this.didChange(filePath, content);
 
-    // Wait for publishDiagnostics or timeout
-    await new Promise<void>((resolve) => {
-      const timer = setTimeout(resolve, DIAGNOSTIC_WAIT_MS);
-      const waiters = this.diagnosticWaiters.get(uri) ?? [];
-      waiters.push(() => {
-        clearTimeout(timer);
-        resolve();
-      });
-      this.diagnosticWaiters.set(uri, waiters);
-    });
+    // Prefer pull diagnostics when available, but fall back to push notifications.
+    if (this.hasDiagnosticProvider) {
+      const remaining = DIAGNOSTIC_WAIT_MS - (Date.now() - syncStart);
+      if (remaining > 0) {
+        try {
+          const { pullDiagnosticsForUri } = await import("./client-refresh.ts");
+          const pulled = await pullDiagnosticsForUri(this, uri, remaining);
+          if (pulled) {
+            return this.getDiagnostics(filePath);
+          }
+        } catch {
+          // Pull diagnostics failed — fall back to push wait
+        }
+      }
+    }
 
+    await this.waitForDiagnostics(uri, Math.max(0, DIAGNOSTIC_WAIT_MS - (Date.now() - syncStart)));
     return this.getDiagnostics(filePath);
   }
 
   // ── LSP Requests ───────────────────────────────────────────────────
-
   async hover(filePath: string, position: Position): Promise<Hover | null> {
     return this.request("textDocument/hover", {
       textDocument: { uri: fileToUri(filePath) },
@@ -341,6 +419,11 @@ export class LspClient {
     });
   }
 
+  async workspaceSymbol(query: string): Promise<SymbolInformation[] | WorkspaceSymbol[] | null> {
+    if (!this.capabilities?.workspaceSymbolProvider) return null;
+    return this.request("workspace/symbol", { query });
+  }
+
   async rename(
     filePath: string,
     position: Position,
@@ -365,8 +448,18 @@ export class LspClient {
     });
   }
 
-  // ── Private ─────────────────────────────────────────────────────────
+  async implementation(
+    filePath: string,
+    position: Position,
+  ): Promise<Location | Location[] | LocationLink[] | null> {
+    if (!this.capabilities?.implementationProvider) return null;
+    return this.request("textDocument/implementation", {
+      textDocument: { uri: fileToUri(filePath) },
+      position,
+    });
+  }
 
+  // ── Private ─────────────────────────────────────────────────────────
   private async request<T>(method: string, params: unknown): Promise<T | null> {
     if (!this.rpc || this._status !== "running") return null;
     try {
@@ -377,16 +470,71 @@ export class LspClient {
   }
 
   private handlePublishDiagnostics(params: PublishDiagnosticsParams): void {
-    this.diagnosticStore.set(params.uri, params.diagnostics);
+    // If the publication includes a version and we have a newer synced
+    // version for this open document, ignore the stale publication.
+    if (params.version !== undefined && params.version !== null) {
+      const openDoc = this.openDocs.get(params.uri);
+      if (openDoc && params.version < openDoc.version) {
+        return;
+      }
+    }
+
+    this.diagnosticStore.set(params.uri, {
+      diagnostics: params.diagnostics,
+      receivedAt: Date.now(),
+      version: params.version ?? undefined,
+    });
     this.releaseDiagnosticWaiters(params.uri);
   }
 
+  /** Wait for diagnostics on a URI, resolving on publication or timeout. */
+  private waitForDiagnostics(uri: string, timeoutMs: number): Promise<void> {
+    if (timeoutMs <= 0) return Promise.resolve();
+
+    return new Promise<void>((resolve) => {
+      const waiter = () => {
+        clearTimeout(timer);
+        this.removeDiagnosticWaiter(uri, waiter);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        this.removeDiagnosticWaiter(uri, waiter);
+        resolve();
+      }, timeoutMs);
+      const waiters = this.diagnosticWaiters.get(uri) ?? [];
+      waiters.push(waiter);
+      this.diagnosticWaiters.set(uri, waiters);
+    });
+  }
+
+  /** Clear all per-file state and wake any diagnostics callers waiting on this URI. */
   private clearFileState(uri: string): void {
     this.openDocs.delete(uri);
     this.diagnosticStore.delete(uri);
     this.releaseDiagnosticWaiters(uri);
   }
 
+  /** Remove a single pending diagnostics waiter, usually after its timeout fires. */
+  private removeDiagnosticWaiter(uri: string, waiter: () => void): void {
+    const waiters = this.diagnosticWaiters.get(uri);
+    if (!waiters) return;
+
+    const next = waiters.filter((entry) => entry !== waiter);
+    if (next.length > 0) {
+      this.diagnosticWaiters.set(uri, next);
+    } else {
+      this.diagnosticWaiters.delete(uri);
+    }
+  }
+
+  /** Wake every pending diagnostics waiter during shutdown or bulk cleanup. */
+  private releaseAllDiagnosticWaiters(): void {
+    for (const uri of Array.from(this.diagnosticWaiters.keys())) {
+      this.releaseDiagnosticWaiters(uri);
+    }
+  }
+
+  /** Wake all diagnostics waiters for a URI and remove them from the waiter map. */
   private releaseDiagnosticWaiters(uri: string): void {
     const waiters = this.diagnosticWaiters.get(uri);
     if (!waiters) return;

package/{transport.ts → src/client/transport.ts}

@@ -6,7 +6,7 @@ import type {
   JsonRpcNotification,
   JsonRpcRequest,
   JsonRpcResponse,
-} from "./types.ts";
+} from "../types.ts";
 
 const CONTENT_LENGTH = "Content-Length: ";
 const HEADER_DELIMITER = "\r\n\r\n";
@@ -48,18 +48,23 @@ export class JsonRpcClient {
     this.notificationHandler = handler;
   }
 
-  /** Send a request and wait for the correlated response. */
-  sendRequest(method: string, params?: unknown): Promise<unknown> {
+  /** Send a request and wait for the correlated response, optionally overriding the timeout. */
+  sendRequest(
+    method: string,
+    params?: unknown,
+    options?: { timeoutMs?: number },
+  ): Promise<unknown> {
     if (this.closed) {
       return Promise.reject(new Error("JSON-RPC client is closed"));
     }
 
     const id = this.nextId++;
+    const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
     const promise = new Promise<unknown>((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(id);
-        reject(new Error(`Request ${method} (id=${id}) timed out after ${this.timeoutMs}ms`));
-      }, this.timeoutMs);
+        reject(new Error(`Request ${method} (id=${id}) timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
 
       this.pending.set(id, { resolve, reject, timer });
     });
@@ -104,7 +109,6 @@ export class JsonRpcClient {
   }
 
   private processBuffer(): void {
-    // eslint-disable-next-line no-constant-condition
     while (true) {
       // Look for header delimiter
       const headerEnd = this.buffer.indexOf(HEADER_DELIMITER);

package/src/config.ts

@@ -0,0 +1,143 @@
+// LSP server configuration — load defaults, merge with supi config per language key.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { loadSupiConfigForScope } from "@mrclrchtr/supi-core";
+import type { LspConfig, ServerConfig } from "./types.ts";
+
+// 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"),
+) as LspConfig;
+
+// ── Public API ────────────────────────────────────────────────────────
+
+export interface LoadConfigOptions {
+  homeDir?: string;
+}
+
+/** Map from language alias → canonical config key. */
+export const LANGUAGE_ALIASES: Record<string, string> = {
+  cpp: "c",
+};
+
+/** Resolve a language name through aliases. */
+export function resolveLanguageAlias(name: string): string {
+  return LANGUAGE_ALIASES[name] ?? name;
+}
+
+function resolveAliasesInOverrides(servers: Record<string, Partial<ServerConfig>>): void {
+  for (const [alias, target] of Object.entries(LANGUAGE_ALIASES)) {
+    if (servers[alias]) {
+      servers[target] = { ...(servers[target] ?? {}), ...servers[alias] };
+      delete servers[alias];
+    }
+  }
+}
+
+/**
+ * Load LSP config: built-in defaults merged with per-language-key overrides
+ * from supi config (`~/.pi/agent/supi/config.json` and `.pi/supi/config.json`).
+ * Each language key merges individually; omitted fields fall back to defaults.
+ */
+export function loadConfig(cwd: string, options?: LoadConfigOptions): LspConfig {
+  const defaults = DEFAULTS;
+
+  const globalLsp = loadSupiConfigForScope(
+    "lsp",
+    cwd,
+    { enabled: true, severity: 1, active: [], servers: {} as Record<string, ServerConfig> },
+    { scope: "global", homeDir: options?.homeDir },
+  );
+  const projectLsp = loadSupiConfigForScope(
+    "lsp",
+    cwd,
+    { enabled: true, severity: 1, active: [], servers: {} as Record<string, ServerConfig> },
+    { scope: "project" },
+  );
+
+  const merged = mergeServerConfigs(defaults.servers, globalLsp.servers, projectLsp.servers);
+
+  return { servers: merged };
+}
+
+/**
+ * Find which server config handles a given file extension.
+ * Returns [languageName, config] or null.
+ */
+export function getServerForFile(
+  config: LspConfig,
+  filePath: string,
+): [string, ServerConfig] | null {
+  const ext = path.extname(filePath).slice(1).toLowerCase();
+  if (!ext) return null;
+
+  for (const [name, server] of Object.entries(config.servers)) {
+    if (server.fileTypes.includes(ext)) {
+      return [name, server];
+    }
+  }
+  return null;
+}
+
+// ── Private ───────────────────────────────────────────────────────────
+
+function mergeServerConfigs(
+  defaults: Record<string, ServerConfig>,
+  globalOverrides: unknown,
+  projectOverrides: unknown,
+): Record<string, ServerConfig> {
+  const merged: Record<string, ServerConfig> = { ...defaults };
+
+  const globalServers = isServerRecord(globalOverrides) ? globalOverrides : {};
+  const projectServers = isServerRecord(projectOverrides) ? projectOverrides : {};
+
+  resolveAliasesInOverrides(globalServers);
+  resolveAliasesInOverrides(projectServers);
+
+  // Apply global per-key overrides against defaults
+  for (const [lang, override] of Object.entries(globalServers)) {
+    const result = mergeSingleServer(defaults[lang], override);
+    if (result) merged[lang] = result;
+  }
+
+  // Apply project per-key overrides against the result so far
+  for (const [lang, override] of Object.entries(projectServers)) {
+    const result = mergeSingleServer(merged[lang] ?? defaults[lang], override);
+    if (result) merged[lang] = result;
+  }
+
+  // Remove servers whose final merged config has enabled === false
+  for (const [lang, config] of Object.entries(merged)) {
+    if (config.enabled === false) {
+      delete merged[lang];
+    }
+  }
+
+  return merged;
+}
+
+function mergeSingleServer(
+  base: ServerConfig | undefined,
+  override: Partial<ServerConfig>,
+): ServerConfig | null {
+  if (!base) {
+    // New custom language — must have all required fields
+    if (
+      override.command &&
+      Array.isArray(override.fileTypes) &&
+      override.fileTypes.length > 0 &&
+      Array.isArray(override.rootMarkers) &&
+      override.rootMarkers.length > 0
+    ) {
+      return override as ServerConfig;
+    }
+    return null;
+  }
+  return { ...base, ...override };
+}
+
+function isServerRecord(value: unknown): value is Record<string, Partial<ServerConfig>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/defaults.json

@@ -0,0 +1,82 @@
+{
+  "servers": {
+    "typescript": {
+      "command": "typescript-language-server",
+      "args": ["--stdio"],
+      "fileTypes": ["ts", "tsx", "js", "jsx", "mts", "cts", "mjs", "cjs"],
+      "rootMarkers": ["tsconfig.json", "jsconfig.json", "package.json"]
+    },
+    "python": {
+      "command": "pyright-langserver",
+      "args": ["--stdio"],
+      "fileTypes": ["py", "pyi"],
+      "rootMarkers": [
+        "pyproject.toml",
+        "setup.py",
+        "setup.cfg",
+        "requirements.txt",
+        "pyrightconfig.json"
+      ]
+    },
+    "rust": {
+      "command": "rust-analyzer",
+      "args": [],
+      "fileTypes": ["rs"],
+      "rootMarkers": ["Cargo.toml"]
+    },
+    "go": {
+      "command": "gopls",
+      "args": ["serve"],
+      "fileTypes": ["go", "mod"],
+      "rootMarkers": ["go.mod", "go.sum"]
+    },
+    "c": {
+      "command": "clangd",
+      "args": ["--background-index"],
+      "fileTypes": ["c", "h", "cpp", "hpp", "cc", "cxx", "hxx", "c++", "h++"],
+      "rootMarkers": ["compile_commands.json", "CMakeLists.txt", ".clangd", "Makefile"]
+    },
+    "ruby": {
+      "command": "ruby-lsp",
+      "args": [],
+      "fileTypes": ["rb", "erb", "gemspec"],
+      "rootMarkers": ["Gemfile", ".ruby-version"]
+    },
+    "java": {
+      "command": "jdtls",
+      "args": [],
+      "fileTypes": ["java"],
+      "rootMarkers": ["pom.xml", "build.gradle"]
+    },
+    "kotlin": {
+      "command": "kotlin-lsp",
+      "args": [],
+      "fileTypes": ["kt", "kts"],
+      "rootMarkers": ["build.gradle.kts", "pom.xml"]
+    },
+    "bash": {
+      "command": "bash-language-server",
+      "args": ["start"],
+      "fileTypes": ["sh", "bash", "zsh", "ksh"],
+      "rootMarkers": []
+    },
+    "html": {
+      "command": "vscode-html-language-server",
+      "args": ["--stdio"],
+      "fileTypes": ["html", "htm", "xhtml"],
+      "rootMarkers": ["package.json"]
+    },
+    "sql": {
+      "command": "sql-language-server",
+      "args": ["up", "--method", "stdio"],
+      "fileTypes": ["sql"],
+      "rootMarkers": []
+    },
+    "r": {
+      "command": "R",
+      "args": ["--slave", "-e", "languageserver::run()"],
+      "fileTypes": ["r"],
+      "rootMarkers": ["DESCRIPTION", "renv.lock", ".Rprofile"]
+    }
+  }
+}

package/src/diagnostics/diagnostic-augmentation.ts

@@ -0,0 +1,82 @@
+import * as path from "node:path";
+import type { LspManager } from "../manager/manager.ts";
+import type { Diagnostic, Hover, MarkedString, MarkupContent } from "../types.ts";
+
+const AUGMENT_TIMEOUT_MS = 500;
+
+/**
+ * Augment diagnostics with LSP hover and code_actions at the first severity-1 error.
+ * Silently returns null if LSP is unavailable, times out, or there are no errors.
+ */
+export async function augmentDiagnostics(
+  filePath: string,
+  diags: Diagnostic[],
+  manager: LspManager,
+  _cwd: string,
+): Promise<string | null> {
+  const firstError = diags.find((d) => d.severity === 1);
+  if (!firstError) return null;
+
+  const resolvedPath = path.resolve(filePath);
+  const client = await manager.getClientForFile(filePath);
+  if (!client) return null;
+
+  const pos = firstError.range.start;
+
+  const [hoverResult, codeActionsResult] = await Promise.all([
+    withTimeout(client.hover(resolvedPath, pos), AUGMENT_TIMEOUT_MS),
+    withTimeout(
+      client.codeActions(resolvedPath, { start: pos, end: pos }, { diagnostics: [firstError] }),
+      AUGMENT_TIMEOUT_MS,
+    ),
+  ]);
+
+  const parts: string[] = [];
+
+  if (hoverResult) {
+    const hoverText = formatHoverForDiagnostics(hoverResult);
+    if (hoverText) parts.push(`💡 Hover info:\n${hoverText}`);
+  }
+
+  if (codeActionsResult && codeActionsResult.length > 0) {
+    const titles = codeActionsResult.map((a) => a.title).join(", ");
+    parts.push(`💡 Available fix: ${titles}`);
+  }
+
+  return parts.length > 0 ? parts.join("\n") : null;
+}
+
+/**
+ * Extract raw hover text for inline diagnostic augmentation.
+ * Intentionally strips markdown code-block framing (unlike formatHover)
+ * to keep augmentation concise and readable inside diagnostic output.
+ */
+function formatHoverForDiagnostics(hover: Hover): string {
+  const contents = hover.contents;
+  let text = "";
+
+  if (typeof contents === "string") {
+    text = contents;
+  } else if ("value" in contents) {
+    const mc = contents as MarkupContent | { language: string; value: string };
+    if ("kind" in mc) text = mc.value;
+    else text = mc.value;
+  } else if (Array.isArray(contents)) {
+    text = (contents as MarkedString[])
+      .map((c) => (typeof c === "string" ? c : c.value))
+      .join("\n");
+  }
+
+  const lines = text.split("\n").slice(0, 3);
+  return lines.join("\n");
+}
+
+async function withTimeout<T>(promise: Promise<T | null>, ms: number): Promise<T | null> {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const timeoutPromise = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), ms);
+  });
+  const result = await Promise.race([promise, timeoutPromise]);
+  if (timer) clearTimeout(timer);
+  return result;
+}