@mmerterden/multi-agent-toolkit-mcp 3.7.1 → 3.11.0

package/tools/code-intel/kotlin.js

@@ -0,0 +1,159 @@
+/**
+ * kotlin.js  -  JetBrains kotlin-lsp, behind a probe, and labelled as Alpha.
+ *
+ * WHAT IS VERIFIED AND WHAT IS NOT, stated here because a green test suite would
+ * otherwise imply something false. The probe below is verified: on a machine
+ * without kotlin-lsp it reports the absence and installs nothing. The SERVER
+ * path is not verified by any gate in this repository - kotlin-lsp is not
+ * installed here and CI has no JVM - so every Kotlin answer carries
+ * `confidence: "alpha"` and the README says the same thing.
+ *
+ * Upstream state at the time of writing: Alpha, partially closed source, Android
+ * Gradle Plugin support experimental. A 4,294-file, 85-module Gradle project is
+ * the realistic target here, and importing one of those is the expensive step -
+ * hence an initialize budget measured in minutes, not the 20 seconds a Swift
+ * request gets.
+ *
+ * @module tools/code-intel/kotlin
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+
+const INSTALL = [
+  "brew tap JetBrains/utils",
+  "brew install kotlin-lsp",
+  "requires a JVM, Java 17 or newer",
+];
+
+const CANDIDATES = [
+  "/opt/homebrew/bin/kotlin-lsp",
+  "/usr/local/bin/kotlin-lsp",
+];
+
+let cached;
+
+/**
+ * Is there a Kotlin language server on this machine?
+ *
+ * Absence is a RESULT, not an error: `code_index_status` exists to be run when
+ * something is missing, so it must answer rather than fail. Nothing here spawns
+ * the server.
+ */
+export function probeKotlin() {
+  if (cached) return cached;
+  const bin = findBin();
+  if (!bin) {
+    return (cached = {
+      available: false,
+      reason: "kotlin-lsp is not on PATH",
+      install: INSTALL,
+    });
+  }
+  const java = javaMajor();
+  if (java === null) {
+    return (cached = {
+      available: false,
+      bin,
+      reason: "kotlin-lsp is installed but no JVM was found",
+      install: INSTALL,
+    });
+  }
+  if (java < 17) {
+    return (cached = {
+      available: false,
+      bin,
+      javaVersion: java,
+      reason: `kotlin-lsp needs Java 17 or newer, found ${java}`,
+      install: INSTALL,
+    });
+  }
+  return (cached = { available: true, bin, javaVersion: java, confidence: "alpha" });
+}
+
+export function resetKotlinProbeCache() {
+  cached = undefined;
+}
+
+function findBin() {
+  const explicit = process.env.KOTLIN_LSP_PATH;
+  if (explicit && existsSync(explicit)) return explicit;
+  try {
+    const p = execFileSync("/usr/bin/which", ["kotlin-lsp"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim();
+    if (p && existsSync(p)) return p;
+  } catch {
+    /* not on PATH */
+  }
+  return CANDIDATES.find(existsSync) || null;
+}
+
+/**
+ * The JVM's major version, or null.
+ *
+ * `java -version` writes to STDERR and exits 0. execFileSync returns stdout, so
+ * reading it there captured an empty string, matched nothing, and reported "no
+ * JVM was found" on a machine running Java 17 - and the catch that reads
+ * e.stderr never ran, because there was no error. spawnSync is used to get both
+ * streams; `--version` (stdout, JDK 9+) is deliberately not used instead,
+ * because on a JDK 8 it fails and the answer needed there is "8", not nothing.
+ */
+function javaMajor() {
+  const r = spawnSync("java", ["-version"], { encoding: "utf8", timeout: 10000 });
+  const out = `${r.stderr || ""}${r.stdout || ""}`;
+  const m = /version "(\d+)(?:\.(\d+))?/.exec(out);
+  if (!m) return null;
+  const major = Number(m[1]);
+  // 1.8 style for anything before 9.
+  return major === 1 ? Number(m[2] || 0) : major;
+}
+
+/** The Gradle root at or above a file. */
+export function resolveKotlinRoot(file, explicitRoot) {
+  if (explicitRoot) return { root: explicitRoot, source: "explicit" };
+  let dir = dirname(file);
+  for (let i = 0; i < 40 && dir && dir !== "/"; i++) {
+    if (existsSync(join(dir, "settings.gradle.kts")) || existsSync(join(dir, "settings.gradle"))) {
+      return { root: dir, source: "gradle" };
+    }
+    dir = dirname(dir);
+  }
+  dir = dirname(file);
+  for (let i = 0; i < 40 && dir && dir !== "/"; i++) {
+    if (existsSync(join(dir, "build.gradle.kts")) || existsSync(join(dir, "build.gradle"))) {
+      return { root: dir, source: "gradle-module" };
+    }
+    dir = dirname(dir);
+  }
+  return { root: dirname(file), source: "fallback" };
+}
+
+/** Kotlin's half of `code_index_status`, whether or not anything is installed. */
+export function kotlinReport(root) {
+  const probe = probeKotlin();
+  if (!probe.available) {
+    return {
+      available: false,
+      root,
+      reason: probe.reason,
+      install: probe.install,
+      note: "Kotlin support here is written against JetBrains kotlin-lsp (Alpha) and is not exercised by any gate in this repository.",
+    };
+  }
+  return {
+    available: true,
+    root,
+    bin: probe.bin,
+    javaVersion: probe.javaVersion,
+    confidence: "alpha",
+    note: "kotlin-lsp is Alpha and its Android Gradle Plugin support is experimental. The first request against a multi-module Gradle build triggers an import that can take minutes.",
+  };
+}
+
+export const KOTLIN_INIT_TIMEOUT_MS = 300000;
+export const KOTLIN_ARGV = ["--stdio"];
+export { INSTALL as KOTLIN_INSTALL };

package/tools/code-intel/lsp-client.js

@@ -0,0 +1,422 @@
+/**
+ * lsp-client.js  -  a JSON-RPC client for one language server, over its stdio.
+ *
+ * STDOUT DISCIPLINE, first because it is the one mistake that breaks everything
+ * else. This process speaks JSON-RPC to its own MCP host on fd 1. A language
+ * server speaks JSON-RPC too, and getting the two streams confused corrupts the
+ * host's channel and takes every tool in the server down with it, not just this
+ * family. Three independent rules, all applied:
+ *
+ *   1. The child is spawned with `stdio: ["pipe","pipe","pipe"]`. Never
+ *      "inherit" for fd 1 or 2. Nothing in this file touches process.stdout.
+ *   2. The child's stderr is drained into a small ring buffer and never
+ *      forwarded. sourcekit-lsp logs there when SOURCEKIT_LSP_LOG_LEVEL is set,
+ *      so the spawn env deletes that rather than inheriting a developer's shell.
+ *   3. Bytes off the child's stdout are parsed as LSP frames and never
+ *      re-emitted. Anything unparseable goes into the same ring buffer.
+ *
+ * FRAMING is done over a Buffer, not a string. `Content-Length` counts bytes,
+ * and a UTF-8 identifier - a Turkish `ö`, an emoji in a string literal - will
+ * straddle a chunk boundary and be miscounted the moment the accumulator is a
+ * string.
+ *
+ * INDEXING is tracked, because it is the difference between two answers that
+ * look identical. Measured against sourcekit-lsp 6.3.1: a `references` request
+ * answers `[]` while the background index is still building, and `[3]` sixteen
+ * seconds later with no other change. Returning the first as "no references"
+ * reads as "this symbol is unused". The server announces the work - a
+ * `window/workDoneProgress/create` for a token named `indexing.<uuid>`, then
+ * `$/progress` begin ("Indexing", "Determining files"), report ("0 / 2"), end -
+ * so `indexing()` reports whether any such token is currently open, and
+ * `waitForIndex()` lets a caller hold until it closes.
+ *
+ * @module tools/code-intel/lsp-client
+ */
+
+import { spawn } from "node:child_process";
+
+const STDERR_RING = 8 * 1024;
+const DEFAULT_REQUEST_TIMEOUT_MS = 20000;
+
+/** Env a language server should not inherit from whoever started the host. */
+const SCRUBBED_ENV = [
+  "SOURCEKIT_LSP_LOG_LEVEL",
+  "SOURCEKIT_LSP_LOG_PRIVACY_LEVEL",
+  "SOURCEKIT_TOOLCHAIN_PATH",
+];
+
+/**
+ * Start a language server and talk to it.
+ *
+ * Never throws for anything the server does; a failure is a rejected request
+ * with a readable reason, and a dead server is reported through `onCrash`.
+ *
+ * @param {object} opts
+ * @param {string} opts.bin                 executable
+ * @param {string[]} [opts.argv]            arguments, as an array - no shell
+ * @param {string} opts.cwd                 workspace root
+ * @param {object} [opts.env]               extra env
+ * @param {object} opts.initializeParams    LSP initialize params
+ * @param {number} [opts.requestTimeoutMs]
+ * @param {(m: object) => void} [opts.onNotification]
+ * @param {(info: object) => void} [opts.onCrash]
+ * @returns {object} the client
+ */
+export function createLspClient(opts) {
+  const {
+    bin,
+    argv = [],
+    cwd,
+    env = {},
+    initializeParams,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+    onNotification,
+    onCrash,
+  } = opts;
+
+  const childEnv = { ...process.env, ...env };
+  for (const k of SCRUBBED_ENV) delete childEnv[k];
+
+  const child = spawn(bin, argv, { cwd, env: childEnv, stdio: ["pipe", "pipe", "pipe"] });
+
+  let buf = Buffer.alloc(0);
+  let stderrTail = "";
+  let nextId = 1;
+  let disposing = false;
+  let exited = null;
+  let serverCapabilities = null;
+  const pending = new Map();
+  /** Extra notification subscribers, added and removed per request. */
+  const subscribers = new Set();
+  /** Open work-done tokens, by token -> {title, message, percentage}. */
+  const progress = new Map();
+  const indexWaiters = [];
+
+  const note = (s) => {
+    stderrTail = (stderrTail + s).slice(-STDERR_RING);
+  };
+
+  child.stderr.on("data", (d) => note(String(d)));
+  child.on("error", (e) => finish(127, e.message));
+  child.on("exit", (code, signal) => finish(code ?? -1, signal ? `signal ${signal}` : ""));
+
+  function finish(code, detail) {
+    if (exited) return;
+    exited = { code, detail };
+    const reason =
+      `ERROR: ${bin} exited (${code})` + (detail ? ` ${detail}` : "") + tail();
+    for (const [, p] of pending) {
+      clearTimeout(p.timer);
+      p.resolve({ error: { message: reason } });
+    }
+    pending.clear();
+    releaseIndexWaiters();
+    if (!disposing && typeof onCrash === "function") {
+      onCrash({ code, detail, stderr: stderrTail });
+    }
+  }
+
+  function tail() {
+    const t = stderrTail.trim();
+    return t ? `: ${t.slice(-400)}` : "";
+  }
+
+  function write(obj) {
+    if (exited || !child.stdin.writable) return false;
+    const s = JSON.stringify(obj);
+    child.stdin.write(`Content-Length: ${Buffer.byteLength(s, "utf8")}\r\n\r\n${s}`);
+    return true;
+  }
+
+  child.stdout.on("data", (chunk) => {
+    buf = Buffer.concat([buf, chunk]);
+    for (;;) {
+      const sep = buf.indexOf("\r\n\r\n");
+      if (sep === -1) {
+        // A header this long is not a header. Drop it rather than growing
+        // without bound on a server that prints a banner and nothing else.
+        if (buf.length > 64 * 1024) {
+          note(buf.toString("utf8"));
+          buf = Buffer.alloc(0);
+        }
+        return;
+      }
+      const header = buf.slice(0, sep).toString("ascii");
+      const m = /content-length:\s*(\d+)/i.exec(header);
+      if (!m) {
+        note(header);
+        buf = buf.slice(sep + 4);
+        continue;
+      }
+      const len = Number(m[1]);
+      if (buf.length < sep + 4 + len) return;
+      const body = buf.slice(sep + 4, sep + 4 + len).toString("utf8");
+      buf = buf.slice(sep + 4 + len);
+      let msg;
+      try {
+        msg = JSON.parse(body);
+      } catch {
+        note(body);
+        continue;
+      }
+      dispatch(msg);
+    }
+  });
+
+  function dispatch(msg) {
+    // A server-to-client REQUEST has both an id and a method. Ignoring these
+    // hangs the server: sourcekit-lsp waits on workDoneProgress/create before
+    // it starts indexing.
+    if (msg.id !== undefined && msg.method) {
+      if (msg.method === "window/workDoneProgress/create") {
+        const token = msg.params?.token;
+        if (token !== undefined) progress.set(tokenKey(token), { title: null });
+      }
+      write({ jsonrpc: "2.0", id: msg.id, result: null });
+      return;
+    }
+    if (msg.id !== undefined && pending.has(msg.id)) {
+      const p = pending.get(msg.id);
+      pending.delete(msg.id);
+      clearTimeout(p.timer);
+      p.resolve(msg);
+      return;
+    }
+    if (msg.method === "$/progress") {
+      onProgress(msg.params);
+      fanout(msg);
+      return;
+    }
+    if (msg.method) {
+      fanout(msg);
+      return;
+    }
+    note(JSON.stringify(msg).slice(0, 500));
+  }
+
+  function fanout(msg) {
+    if (typeof onNotification === "function") onNotification(msg);
+    for (const s of subscribers) {
+      try {
+        s(msg);
+      } catch {
+        // A subscriber that throws must not take the read loop with it.
+      }
+    }
+  }
+
+  /**
+   * Listen to notifications for the length of one request.
+   *
+   * Diagnostics are the reason this exists: sourcekit-lsp publishes them
+   * unsolicited after didOpen rather than answering a request, so a caller has
+   * to be listening before it asks.
+   *
+   * @returns {() => void} unsubscribe
+   */
+  function subscribe(handler) {
+    subscribers.add(handler);
+    return () => subscribers.delete(handler);
+  }
+
+  function tokenKey(t) {
+    return typeof t === "string" ? t : JSON.stringify(t);
+  }
+
+  function onProgress(params) {
+    if (!params) return;
+    const key = tokenKey(params.token);
+    const v = params.value || {};
+    if (v.kind === "end") {
+      progress.delete(key);
+      releaseIndexWaiters();
+      return;
+    }
+    const prev = progress.get(key) || {};
+    progress.set(key, {
+      title: v.title ?? prev.title ?? null,
+      message: v.message ?? prev.message ?? null,
+      percentage: v.percentage ?? prev.percentage ?? null,
+    });
+  }
+
+  /** An open token that is the index build, by either of the two signals. */
+  function indexingEntry() {
+    for (const [key, v] of progress) {
+      if (key.startsWith("indexing.")) return { key, ...v };
+      if (typeof v.title === "string" && /index/i.test(v.title)) return { key, ...v };
+    }
+    return null;
+  }
+
+  function releaseIndexWaiters() {
+    if (indexingEntry()) return;
+    while (indexWaiters.length) {
+      const w = indexWaiters.shift();
+      clearTimeout(w.timer);
+      w.resolve(true);
+    }
+  }
+
+  /**
+   * Send a request. Resolves with the raw JSON-RPC message, or a synthetic
+   * `{error}` - it never rejects, so no caller needs a try/catch to stay alive.
+   */
+  function request(method, params, { timeoutMs = requestTimeoutMs, signal } = {}) {
+    if (exited) {
+      return Promise.resolve({
+        error: { message: `ERROR: ${bin} is not running (${exited.code})${tail()}` },
+      });
+    }
+    const id = nextId++;
+    return new Promise((resolve) => {
+      let onAbort;
+      const settle = (v) => {
+        if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+        resolve(v);
+      };
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        write({ jsonrpc: "2.0", method: "$/cancelRequest", params: { id } });
+        // The server is NOT killed. One slow query is not a reason to throw
+        // away a warm index that took minutes to build.
+        settle({ error: { message: `ERROR: ${method} timed out after ${timeoutMs}ms` } });
+      }, timeoutMs);
+      pending.set(id, { resolve: settle, timer, method });
+      if (signal) {
+        onAbort = () => {
+          const p = pending.get(id);
+          if (!p) return;
+          pending.delete(id);
+          clearTimeout(p.timer);
+          write({ jsonrpc: "2.0", method: "$/cancelRequest", params: { id } });
+          settle({ error: { message: `ERROR: ${method} aborted` } });
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      if (!write({ jsonrpc: "2.0", id, method, params })) {
+        pending.delete(id);
+        clearTimeout(timer);
+        settle({ error: { message: `ERROR: cannot write to ${bin}` } });
+      }
+    });
+  }
+
+  function notify(method, params) {
+    write({ jsonrpc: "2.0", method, params });
+  }
+
+  async function initialize({ timeoutMs } = {}) {
+    const res = await request("initialize", initializeParams, { timeoutMs });
+    if (res.error) return res;
+    serverCapabilities = res.result?.capabilities || {};
+    notify("initialized", {});
+    return res;
+  }
+
+  /**
+   * Hold until the index build closes, or the budget runs out.
+   *
+   * `settleMs` is not a nicety. Measured: `initialize` answers at ~680ms and the
+   * `indexing.<uuid>` token does not open until ~1750ms, so a wait that only
+   * asked "is a token open right now" returned true 900ms too early and the
+   * caller went on to read an empty `references` as "no references". The wait
+   * therefore has to survive a quiet gap: no open token has to STAY true for
+   * `settleMs` before it counts as done.
+   *
+   * @returns {Promise<boolean>} true when idle, false when the budget ran out
+   */
+  async function waitForIndex(timeoutMs, { settleMs = 2500 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      if (indexingEntry()) {
+        const left = deadline - Date.now();
+        if (left <= 0) return false;
+        const closed = await awaitIndexClose(left);
+        if (!closed) return false;
+        continue;
+      }
+      const quiet = Math.min(settleMs, Math.max(0, deadline - Date.now()));
+      if (quiet === 0) return !indexingEntry();
+      await delay(quiet, { keepAlive: true });
+      if (!indexingEntry()) return true;
+    }
+  }
+
+  function awaitIndexClose(timeoutMs) {
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        const i = indexWaiters.findIndex((w) => w.timer === timer);
+        if (i >= 0) indexWaiters.splice(i, 1);
+        resolve(false);
+      }, timeoutMs);
+      indexWaiters.push({ resolve, timer });
+    });
+  }
+
+  async function dispose() {
+    disposing = true;
+    if (!exited) {
+      await Promise.race([
+        request("shutdown", null, { timeoutMs: 2000 }),
+        delay(2000, { keepAlive: true }),
+      ]);
+      notify("exit");
+      await delay(150, { keepAlive: true });
+      if (!exited) child.kill("SIGTERM");
+      const hard = setTimeout(() => {
+        if (!exited) child.kill("SIGKILL");
+      }, 1000);
+      hard.unref?.();
+    }
+    // SETTLE, not just clear. Clearing a pending entry drops its `resolve`
+    // with nobody left to call it: the exit event that would have run finish()
+    // arrives to an empty map, and whoever was awaiting that request waits for
+    // the rest of the process's life. Measured against a server that ignores
+    // shutdown - the request never settled and the probe had to be timed out.
+    for (const [, p] of pending) {
+      clearTimeout(p.timer);
+      p.resolve({ error: { message: `ERROR: ${bin} was shut down while ${p.method} was in flight` } });
+    }
+    pending.clear();
+    while (indexWaiters.length) {
+      const w = indexWaiters.shift();
+      clearTimeout(w.timer);
+      w.resolve(false);
+    }
+  }
+
+  return {
+    request,
+    notify,
+    subscribe,
+    initialize,
+    dispose,
+    waitForIndex,
+    get pid() {
+      return child.pid;
+    },
+    get alive() {
+      return !exited;
+    },
+    get capabilities() {
+      return serverCapabilities;
+    },
+    /** `{title, message, percentage}` while the index is building, else null. */
+    indexing: () => indexingEntry(),
+    stderrTail: () => stderrTail,
+  };
+}
+
+/**
+ * `keepAlive` exists because an unref'd timer that is the only thing left in the
+ * loop never fires, and an `await` on it hangs the process instead of ending it.
+ * Measured on the first dispose(): "Detected unsettled top-level await". Waits
+ * that something is awaiting must hold the loop; fire-and-forget ones must not.
+ */
+function delay(ms, { keepAlive = false } = {}) {
+  return new Promise((r) => {
+    const t = setTimeout(r, ms);
+    if (!keepAlive) t.unref?.();
+  });
+}