chainlesschain 0.162.148 → 0.162.149

package/src/lib/lsp/lsp-client.js

@@ -0,0 +1,318 @@
+/**
+ * LSPClient — one connection to a single language server over stdio.
+ *
+ * Speaks JSON-RPC 2.0 framed by `jsonrpc-stream.js`. Responsibilities:
+ *   - spawn the server process (stdio pipes, UTF-8)
+ *   - the `initialize` / `initialized` handshake
+ *   - correlate `request` id → Promise, dispatch `notification`s to listeners
+ *   - request timeouts, graceful `shutdown`/`exit`, and process-level
+ *     `error`/`exit` propagation
+ *
+ * Testability: all process spawning goes through `_deps.spawn` so tests inject a
+ * fake stdio pair (see cli-dev.md `_deps` pattern — `vi.mock("child_process")`
+ * does not intercept this file). Nothing here is language-specific.
+ */
+
+import { spawn as nodeSpawn } from "child_process";
+import { EventEmitter } from "events";
+import { encodeMessage, MessageBuffer } from "./jsonrpc-stream.js";
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+const DEFAULT_INIT_TIMEOUT_MS = 30_000;
+
+// Injectable so unit tests can supply a fake child process.
+export const _deps = { spawn: nodeSpawn };
+
+export class LSPClient extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.command      server executable
+   * @param {string[]} [opts.args]     server args (e.g. ["--stdio"])
+   * @param {string} opts.rootPath     absolute project root
+   * @param {object} [opts.env]        extra env vars
+   * @param {number} [opts.requestTimeoutMs]
+   * @param {object} [opts.capabilities] client capabilities override
+   */
+  constructor(opts = {}) {
+    super();
+    this.command = opts.command;
+    this.args = Array.isArray(opts.args) ? opts.args : [];
+    this.rootPath = opts.rootPath;
+    this.env = opts.env || {};
+    this.requestTimeoutMs = opts.requestTimeoutMs || DEFAULT_REQUEST_TIMEOUT_MS;
+    this.capabilitiesOverride = opts.capabilities || null;
+
+    this._child = null;
+    this._buffer = new MessageBuffer();
+    this._nextId = 1;
+    /** @type {Map<number, {resolve,reject,timer}>} */
+    this._pending = new Map();
+    this._initialized = false;
+    this._closed = false;
+    /** server-reported capabilities from `initialize` */
+    this.serverCapabilities = null;
+  }
+
+  get running() {
+    return Boolean(this._child) && !this._closed;
+  }
+
+  /** Spawn the process and run the initialize handshake. Resolves when ready. */
+  async start({ initTimeoutMs = DEFAULT_INIT_TIMEOUT_MS } = {}) {
+    if (this._child) throw new Error("LSPClient already started");
+
+    // shell:false — never route the server command through a shell (prevents
+    // command injection and GBK codepage surprises on Windows). Callers pass a
+    // resolved executable path; see lsp-server-registry.js. `.cmd`/`.bat` shims
+    // can't be spawned directly with shell:false since Node's CVE-2024-27980
+    // fix, so buildSpawnCommand rewrites them to an explicit `cmd.exe /d /s /c`
+    // invocation with verbatim args — still no shell, still injection-safe.
+    const spawnSpec = buildSpawnCommand(this.command, this.args);
+    this._child = _deps.spawn(spawnSpec.file, spawnSpec.args, {
+      cwd: this.rootPath,
+      env: { ...process.env, ...this.env },
+      stdio: ["pipe", "pipe", "pipe"],
+      shell: false,
+      windowsHide: true,
+      windowsVerbatimArguments: spawnSpec.windowsVerbatimArguments,
+    });
+
+    this._child.on("error", (err) => {
+      this._failAll(err);
+      this.emit("error", err);
+    });
+    this._child.on("exit", (code, signal) => {
+      const wasClosed = this._closed;
+      this._closed = true;
+      this._failAll(
+        new Error(`language server exited (code=${code}, signal=${signal})`),
+      );
+      if (!wasClosed) this.emit("exit", { code, signal });
+    });
+
+    // UTF-8 decode explicitly (encoding.md) — never rely on system default.
+    this._child.stdout.on("data", (chunk) => {
+      this._buffer.append(chunk);
+      for (const msg of this._buffer.readAll()) this._dispatch(msg);
+    });
+    // Surface server diagnostics/logs without corrupting the message channel.
+    this._child.stderr.on("data", (chunk) => {
+      this.emit("stderr", chunk.toString("utf8"));
+    });
+
+    const initResult = await this.request(
+      "initialize",
+      this._initializeParams(),
+      { timeoutMs: initTimeoutMs },
+    );
+    this.serverCapabilities = initResult?.capabilities || {};
+    this.notify("initialized", {});
+    this._initialized = true;
+    return this.serverCapabilities;
+  }
+
+  _initializeParams() {
+    const rootUri = pathToFileUri(this.rootPath);
+    return {
+      processId: process.pid,
+      clientInfo: { name: "chainlesschain-cc", version: "1" },
+      rootUri,
+      rootPath: this.rootPath,
+      workspaceFolders: [{ uri: rootUri, name: "workspace" }],
+      capabilities: this.capabilitiesOverride || defaultClientCapabilities(),
+    };
+  }
+
+  /** Send a JSON-RPC request and await its result. */
+  request(method, params, { timeoutMs } = {}) {
+    if (this._closed) {
+      return Promise.reject(new Error("LSPClient is closed"));
+    }
+    const id = this._nextId++;
+    const payload = { jsonrpc: "2.0", id, method, params };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(id);
+        reject(
+          new Error(
+            `LSP request "${method}" timed out after ${timeoutMs || this.requestTimeoutMs}ms`,
+          ),
+        );
+      }, timeoutMs || this.requestTimeoutMs);
+      // Don't keep the event loop alive purely for a pending LSP request.
+      if (typeof timer.unref === "function") timer.unref();
+      this._pending.set(id, { resolve, reject, timer });
+      this._write(payload);
+    });
+  }
+
+  /** Send a JSON-RPC notification (no response expected). */
+  notify(method, params) {
+    if (this._closed) return;
+    this._write({ jsonrpc: "2.0", method, params });
+  }
+
+  _write(payload) {
+    if (!this._child || !this._child.stdin.writable) return;
+    try {
+      this._child.stdin.write(encodeMessage(payload));
+    } catch (err) {
+      this.emit("error", err);
+    }
+  }
+
+  _dispatch(msg) {
+    if (msg == null) return;
+    // Response to one of our requests.
+    if (Object.prototype.hasOwnProperty.call(msg, "id") && msg.method == null) {
+      const entry = this._pending.get(msg.id);
+      if (!entry) return; // late/duplicate response — ignore
+      this._pending.delete(msg.id);
+      clearTimeout(entry.timer);
+      if (msg.error) {
+        const e = new Error(msg.error.message || "LSP error");
+        e.code = msg.error.code;
+        e.data = msg.error.data;
+        entry.reject(e);
+      } else {
+        entry.resolve(msg.result);
+      }
+      return;
+    }
+    // Server → client request (e.g. workspace/configuration). We don't act on
+    // these yet, but must reply so the server doesn't block; reply null.
+    if (msg.method != null && Object.prototype.hasOwnProperty.call(msg, "id")) {
+      this._write({ jsonrpc: "2.0", id: msg.id, result: null });
+      this.emit("serverRequest", msg);
+      return;
+    }
+    // Notification from the server (diagnostics, logs, progress…).
+    if (msg.method != null) {
+      this.emit("notification", msg.method, msg.params);
+      this.emit(`notify:${msg.method}`, msg.params);
+    }
+  }
+
+  _failAll(err) {
+    for (const [, entry] of this._pending) {
+      clearTimeout(entry.timer);
+      entry.reject(err);
+    }
+    this._pending.clear();
+  }
+
+  /** Graceful LSP shutdown → exit → kill fallback. Idempotent. */
+  async stop({ graceTimeoutMs = 2000 } = {}) {
+    if (!this._child || this._closed) {
+      this._closed = true;
+      return;
+    }
+    try {
+      if (this._initialized) {
+        await this.request("shutdown", null, { timeoutMs: graceTimeoutMs });
+        this.notify("exit", null);
+      }
+    } catch {
+      // Server unresponsive — fall through to hard kill.
+    } finally {
+      this._closed = true;
+      this._failAll(new Error("LSPClient stopped"));
+      try {
+        this._child.kill();
+      } catch {
+        /* already dead */
+      }
+    }
+  }
+}
+
+/**
+ * Compute the actual (file, args) to spawn without a shell. On Windows a
+ * `.cmd`/`.bat` batch shim cannot be spawned with shell:false (EINVAL since
+ * Node's CVE-2024-27980 fix), so route it through `cmd.exe /d /s /c "<cmd>" …`
+ * with windowsVerbatimArguments so cmd.exe — not Node — parses the line. The
+ * command path is double-quoted (handles spaces) and our args are constant, so
+ * there is no injection surface. Everything else spawns verbatim.
+ */
+export function buildSpawnCommand(command, args = []) {
+  if (process.platform === "win32" && /\.(cmd|bat)$/i.test(command)) {
+    const comspec = process.env.ComSpec || "cmd.exe";
+    // Always quote the command path (a batch path can contain spaces/&); quote
+    // args only when they carry shell-significant characters. Verbatim args mean
+    // cmd.exe — not Node — parses this line, so our own quoting is authoritative.
+    const quotedCmd = `"${String(command).replace(/"/g, '""')}"`;
+    const quotedArgs = args.map((a) =>
+      /[\s"&|<>^]/.test(a) ? `"${String(a).replace(/"/g, '""')}"` : a,
+    );
+    return {
+      file: comspec,
+      args: ["/d", "/s", "/c", [quotedCmd, ...quotedArgs].join(" ")],
+      windowsVerbatimArguments: true,
+    };
+  }
+  return { file: command, args, windowsVerbatimArguments: false };
+}
+
+/** LSP wants a `file://` URI; build one that round-trips on Windows and POSIX. */
+export function pathToFileUri(p) {
+  if (!p) return "";
+  let normalized = String(p).replace(/\\/g, "/");
+  // Windows drive path → file:///C:/...
+  if (/^[a-zA-Z]:\//.test(normalized)) {
+    normalized = "/" + normalized;
+  }
+  const encoded = normalized
+    .split("/")
+    .map((seg) => encodeURIComponent(seg))
+    .join("/");
+  return "file://" + encoded;
+}
+
+/**
+ * Canonicalize a `file://` URI so keys match regardless of who produced them.
+ * Windows language servers echo back a lowercase drive letter
+ * (`file:///c%3A/…`) while `path.resolve` yields uppercase (`C%3A`), so a Map
+ * keyed on the raw URI misses. Lowercasing the drive letter reconciles both.
+ */
+export function normalizeUri(uri) {
+  if (!uri) return uri;
+  return String(uri).replace(
+    /^(file:\/\/\/)([A-Za-z])(%3[Aa]|:)/,
+    (_m, p, drive, colon) => p + drive.toLowerCase() + colon,
+  );
+}
+
+/** Convert a `file://` URI back to a native filesystem path. */
+export function fileUriToPath(uri) {
+  if (!uri) return "";
+  let p = String(uri).replace(/^file:\/\//, "");
+  p = decodeURIComponent(p);
+  // /C:/... → C:/... on Windows
+  if (/^\/[a-zA-Z]:\//.test(p)) p = p.slice(1);
+  return process.platform === "win32" ? p.replace(/\//g, "\\") : p;
+}
+
+function defaultClientCapabilities() {
+  return {
+    textDocument: {
+      synchronization: { dynamicRegistration: false, didSave: true },
+      definition: { dynamicRegistration: false, linkSupport: false },
+      references: { dynamicRegistration: false },
+      hover: {
+        dynamicRegistration: false,
+        contentFormat: ["markdown", "plaintext"],
+      },
+      documentSymbol: {
+        dynamicRegistration: false,
+        hierarchicalDocumentSymbolSupport: true,
+      },
+      publishDiagnostics: { relatedInformation: true },
+      rename: { dynamicRegistration: false, prepareSupport: true },
+    },
+    workspace: {
+      workspaceFolders: true,
+      symbol: { dynamicRegistration: false },
+      configuration: true,
+    },
+  };
+}

package/src/lib/lsp/lsp-manager.js

@@ -0,0 +1,323 @@
+/**
+ * LSPManager — pools language servers by (projectRoot, languageId), syncs open
+ * documents, translates positions, and recovers from server crashes.
+ *
+ * One `LSPClient` is expensive (spawns a process + indexes the project), so we
+ * lazily start and reuse one per (root, language) family. The manager owns:
+ *   - server lifecycle (start / reuse / bounded crash-loop restart / disposeAll)
+ *   - textDocument/didOpen + didChange (servers only answer about open docs)
+ *   - diagnostics collection (servers push them via publishDiagnostics)
+ *   - 1-based (user) ⇄ 0-based (LSP) position conversion, done HERE only
+ *
+ * The high-level `code-intelligence.js` calls into this; nothing above the
+ * manager should touch raw LSP positions/URIs.
+ */
+
+import fs from "fs";
+import path from "path";
+import { LSPClient, pathToFileUri, normalizeUri } from "./lsp-client.js";
+import { languageIdForFile, resolveServer } from "./lsp-server-registry.js";
+
+export const _deps = {
+  readFileSync: fs.readFileSync,
+  existsSync: fs.existsSync,
+  createClient: (opts) => new LSPClient(opts),
+};
+
+export class LSPManager {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.projectRoot] default root; per-file root inferred otherwise
+   * @param {number} [opts.maxRestarts] crashes within the window before a server
+   *   is quarantined (degrade to text search) instead of re-spawned. Default 3.
+   * @param {number} [opts.restartWindowMs] sliding window for the crash count.
+   *   A server that stays healthy for this long has its crash history pruned and
+   *   can restart fresh. Default 30000.
+   * @param {() => number} [opts.now] injected clock (deterministic crash-loop tests)
+   */
+  constructor(opts = {}) {
+    this.projectRoot = opts.projectRoot || process.cwd();
+    /** key `${root}::${serverId}` → { client, languageId, root, restarts } */
+    this._servers = new Map();
+    /** open document uri → { version, languageId } */
+    this._openDocs = new Map();
+    /** uri → latest diagnostics array */
+    this._diagnostics = new Map();
+    /** uri → { count, at } publish bookkeeping (for settle/readiness) */
+    this._diagMeta = new Map();
+    // Crash-loop guard: a language server that dies is lazily re-spawned on the
+    // next request (ensureFor), but a server that crashes on startup would then
+    // thrash — re-spawned on EVERY request forever. Bound it: at most
+    // `maxRestarts` crashes inside a sliding `restartWindowMs`, after which the
+    // server is quarantined (callers degrade to text search) until the window
+    // clears. `restarts` was previously a dead field; this makes it real.
+    this.maxRestarts = Number.isFinite(opts.maxRestarts) ? opts.maxRestarts : 3;
+    this.restartWindowMs = Number.isFinite(opts.restartWindowMs)
+      ? opts.restartWindowMs
+      : 30000;
+    this._now = typeof opts.now === "function" ? opts.now : () => Date.now();
+    /** key → array of recent crash timestamps (survives entry re-spawn) */
+    this._crashLog = new Map();
+    this._disposed = false;
+  }
+
+  /** Recent crash timestamps for `key`, pruned to the sliding window. */
+  _recentCrashes(key) {
+    const cutoff = this._now() - this.restartWindowMs;
+    const pruned = (this._crashLog.get(key) || []).filter((t) => t >= cutoff);
+    if (pruned.length) this._crashLog.set(key, pruned);
+    else this._crashLog.delete(key);
+    return pruned;
+  }
+
+  /**
+   * Ensure a server is running for `filePath` and the file is open. Returns
+   * `{ client, uri, languageId }`, or `{ unavailable: true, reason }` when no
+   * server is installed (caller degrades to text search).
+   */
+  async ensureFor(
+    filePath,
+    { root, waitReady = false, readyTimeoutMs = 8000 } = {},
+  ) {
+    if (this._disposed) throw new Error("LSPManager disposed");
+    const abs = path.resolve(filePath);
+    const languageId = languageIdForFile(abs);
+    if (!languageId) {
+      return {
+        unavailable: true,
+        reason: `no language mapping for ${path.extname(abs) || "file"}`,
+      };
+    }
+    const projectRoot = root || this._inferRoot(abs);
+    const resolved = resolveServer(languageId, projectRoot);
+    if (!resolved) {
+      return {
+        unavailable: true,
+        reason: `no language server installed for ${languageId} (install one, e.g. typescript-language-server)`,
+      };
+    }
+
+    const key = `${projectRoot}::${resolved.id}`;
+    let entry = this._servers.get(key);
+    if (!entry || !entry.client.running) {
+      // A dead/absent server is (re)started — but if it has crash-looped past
+      // the cap inside the window, quarantine it so we don't re-spawn on every
+      // request. The caller degrades to text search until the window clears.
+      const crashes = this._recentCrashes(key);
+      if (crashes.length >= this.maxRestarts) {
+        const retryInMs = this.restartWindowMs - (this._now() - crashes[0]);
+        return {
+          unavailable: true,
+          reason:
+            `${resolved.id} crash-looped (${crashes.length} crashes in ` +
+            `${Math.round(this.restartWindowMs / 1000)}s) — quarantined, ` +
+            `retrying in ~${Math.max(0, Math.round(retryInMs / 1000))}s`,
+          quarantined: true,
+        };
+      }
+      entry = await this._startServer(key, resolved, projectRoot);
+    }
+
+    const uri = pathToFileUri(abs);
+    this._ensureOpen(entry.client, uri, abs, languageId);
+
+    // One-shot callers (the `cc code-intel` CLI) spawn a cold server per run;
+    // the server publishes an empty diagnostics set BEFORE it finishes loading
+    // the tsconfig project, so an immediate definition/references/diagnostics
+    // query sees a partial project. Waiting for the first publish for THIS doc
+    // is a reliable "project loaded far enough" signal. Long-lived callers (the
+    // agent session) keep the server warm and pass waitReady:false.
+    if (waitReady) {
+      await this._waitForFirstPublish(uri, readyTimeoutMs);
+    }
+    return { client: entry.client, uri, languageId, root: projectRoot };
+  }
+
+  /** Resolve once the server has published diagnostics for `uri` at least once, or timeout. */
+  _waitForFirstPublish(rawUri, timeoutMs) {
+    const uri = normalizeUri(rawUri);
+    if ((this._diagMeta.get(uri)?.count || 0) > 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      const started = Date.now();
+      const timer = setInterval(() => {
+        if (
+          (this._diagMeta.get(uri)?.count || 0) > 0 ||
+          Date.now() - started >= timeoutMs
+        ) {
+          clearInterval(timer);
+          resolve();
+        }
+      }, 40);
+      if (typeof timer.unref === "function") timer.unref();
+    });
+  }
+
+  async _startServer(key, resolved, projectRoot) {
+    const client = _deps.createClient({
+      command: resolved.command,
+      args: resolved.args,
+      rootPath: projectRoot,
+    });
+    // Collect pushed diagnostics keyed by document, tracking publish count/time
+    // so callers can wait for the project to load (first publish) and settle
+    // (last publish) rather than racing the initial empty set tsserver emits.
+    client.on("notify:textDocument/publishDiagnostics", (params) => {
+      if (params && params.uri) {
+        const key = normalizeUri(params.uri);
+        this._diagnostics.set(key, params.diagnostics || []);
+        const prev = this._diagMeta.get(key) || { count: 0 };
+        this._diagMeta.set(key, { count: prev.count + 1, at: Date.now() });
+      }
+    });
+    const entry = {
+      client,
+      serverId: resolved.id,
+      root: projectRoot,
+      // How many times THIS key has already been (re)started — crash history
+      // survives entry replacement via _crashLog, so this reflects it.
+      restarts: (this._crashLog.get(key) || []).length,
+    };
+    // On crash: record the crash timestamp (bounds the re-spawn loop via the
+    // crash-loop guard in ensureFor) and drop this project's open docs so they
+    // re-sync against the fresh server on the next ensureFor.
+    client.on("exit", () => {
+      const log = this._crashLog.get(key) || [];
+      log.push(this._now());
+      this._crashLog.set(key, log);
+      for (const [uri, meta] of this._openDocs) {
+        if (meta.root === projectRoot) this._openDocs.delete(uri);
+      }
+    });
+    await client.start();
+    this._servers.set(key, entry);
+    return entry;
+  }
+
+  _ensureOpen(client, uri, abs, languageId) {
+    const existing = this._openDocs.get(uri);
+    let text = "";
+    try {
+      text = _deps.readFileSync(abs, "utf8");
+    } catch {
+      text = "";
+    }
+    if (!existing) {
+      client.notify("textDocument/didOpen", {
+        textDocument: { uri, languageId, version: 1, text },
+      });
+      this._openDocs.set(uri, {
+        version: 1,
+        languageId,
+        root: client.rootPath,
+      });
+    } else {
+      // File may have changed on disk since first open — push the latest text so
+      // definitions/diagnostics reflect current state (edit-freshness).
+      const version = existing.version + 1;
+      client.notify("textDocument/didChange", {
+        textDocument: { uri, version },
+        contentChanges: [{ text }],
+      });
+      this._openDocs.set(uri, { ...existing, version });
+    }
+  }
+
+  /** Notify the server that a document changed on disk (after an edit). */
+  async didChangeFile(filePath, { root } = {}) {
+    const abs = path.resolve(filePath);
+    const uri = pathToFileUri(abs);
+    if (!this._openDocs.has(uri)) {
+      // Not open yet — opening it (via ensureFor) will read fresh text anyway.
+      return this.ensureFor(abs, { root });
+    }
+    const ready = await this.ensureFor(abs, { root });
+    return ready;
+  }
+
+  /** Latest diagnostics for a file (may be empty). Server pushes asynchronously. */
+  getDiagnostics(filePath) {
+    const uri = normalizeUri(pathToFileUri(path.resolve(filePath)));
+    return this._diagnostics.get(uri) || [];
+  }
+
+  /**
+   * Wait for diagnostics for `filePath` to publish AND settle, then return the
+   * latest set. tsserver publishes an initial (often empty) set the moment a doc
+   * opens, then republishes once the project is loaded — resolving on the first
+   * publish would return stale/empty results. So we wait for at least one
+   * publish, then a `settleMs` quiet window with no further publishes (bounded
+   * by `timeoutMs`), and return whatever was published last.
+   */
+  async waitForDiagnostics(
+    filePath,
+    { timeoutMs = 3000, settleMs = 600 } = {},
+  ) {
+    const uri = normalizeUri(pathToFileUri(path.resolve(filePath)));
+    return new Promise((resolve) => {
+      const started = Date.now();
+      const timer = setInterval(() => {
+        const meta = this._diagMeta.get(uri);
+        const elapsed = Date.now() - started;
+        const settled =
+          meta && meta.count > 0 && Date.now() - meta.at >= settleMs;
+        if (settled || elapsed >= timeoutMs) {
+          clearInterval(timer);
+          resolve(this._diagnostics.get(uri) || []);
+        }
+      }, 50);
+      if (typeof timer.unref === "function") timer.unref();
+    });
+  }
+
+  /** Infer the project root for a file: nearest ancestor with package.json / .git / go.mod / Cargo.toml. */
+  _inferRoot(abs) {
+    let dir = path.dirname(abs);
+    const markers = [
+      "package.json",
+      ".git",
+      "go.mod",
+      "Cargo.toml",
+      "tsconfig.json",
+      "pyproject.toml",
+    ];
+    for (let i = 0; i < 12; i++) {
+      for (const m of markers) {
+        if (_deps.existsSync(path.join(dir, m))) return dir;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    return this.projectRoot;
+  }
+
+  /** Shut down every server and clear state. Idempotent. */
+  async disposeAll() {
+    this._disposed = true;
+    const clients = [...this._servers.values()].map((e) => e.client);
+    this._servers.clear();
+    this._openDocs.clear();
+    this._diagnostics.clear();
+    this._diagMeta.clear();
+    await Promise.all(clients.map((c) => c.stop().catch(() => {})));
+  }
+
+  get activeServerCount() {
+    return this._servers.size;
+  }
+}
+
+// ---- position helpers (the ONLY place that converts between coordinate spaces) ----
+
+/** 1-based user position → 0-based LSP position. */
+export function toLspPosition({ line, col }) {
+  return {
+    line: Math.max(0, (line || 1) - 1),
+    character: Math.max(0, (col || 1) - 1),
+  };
+}
+
+/** 0-based LSP position → 1-based user position. */
+export function fromLspPosition(pos) {
+  return { line: (pos?.line || 0) + 1, col: (pos?.character || 0) + 1 };
+}