@synovitec/trellis 0.0.0-stage → 0.6.0-rc.2

package/src/core/diff.mjs

@@ -0,0 +1,189 @@
+// A change as content: the files that differ between two trees, with the blob each one has on
+// either side. This is what every rule reads, whoever made the change and however it arrived
+// (commit, rebase, fetch, side clone): two trees are compared, never a history walked.
+//
+// Every git call here either answers or throws. An empty list means "nothing changed", never
+// "git could not tell": a check that cannot run is a finding, not a pass.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+/** A git command that failed. The caller reports it; it never reads as "no change". */
+export class GitError extends Error {
+  /** @param {string[]} args @param {string} detail */
+  constructor(args, detail) {
+    super(`git ${args.slice(0, 3).join(" ")} failed: ${detail}`);
+    this.name = "GitError";
+  }
+}
+
+/**
+ * @typedef {object} Change
+ * @property {string} path
+ * @property {"A" | "M" | "D" | "T"} status   added, modified, deleted, type changed
+ * @property {string | null} oldBlob           the blob before, null when added
+ * @property {string | null} newBlob           the blob after, null when deleted
+ */
+
+/**
+ * @param {string} root
+ * @param {string[]} args
+ * @param {string} [input]  fed on stdin, so a long list never becomes a long command line
+ * @returns {string}
+ */
+function git(root, args, input) {
+  const r = spawnSync("git", args, { cwd: root, encoding: "utf8", input, maxBuffer: 256 * 1024 * 1024, windowsHide: true });
+  if (r.error) throw new GitError(args, r.error.message);
+  if (r.status !== 0) throw new GitError(args, (r.stderr || `exit ${r.status}`).trim());
+  return r.stdout;
+}
+
+/** The empty tree, in this repository's object format (SHA-1 or SHA-256). @param {string} root */
+const emptyTree = (root) => git(root, ["hash-object", "-t", "tree", "--stdin"], "").trim();
+
+/** @param {string} sha */
+const zero = (sha) => /^0+$/.test(sha);
+
+/**
+ * Parses `--raw -z` output: `:<mode> <mode> <old> <new> <status>\0<path>\0`, per file.
+ * @param {string} out
+ * @returns {Change[]}
+ */
+function parseRaw(out) {
+  const parts = out.split("\0");
+  /** @type {Change[]} */
+  const changes = [];
+  for (let i = 0; i + 1 < parts.length; i += 2) {
+    const head = parts[i].replace(/^\n/, "");
+    if (!head.startsWith(":")) continue;
+    const [, , oldSha, newSha, status] = head.slice(1).split(" ");
+    const s = /** @type {Change["status"]} */ (status[0]);
+    changes.push({
+      path: parts[i + 1],
+      status: s,
+      oldBlob: s === "A" || zero(oldSha) ? null : oldSha,
+      newBlob: s === "D" ? null : newSha,
+    });
+  }
+  return changes;
+}
+
+const RAW = ["--raw", "-z", "--no-renames", "--no-abbrev", "--no-ext-diff", "--no-textconv"];
+
+/**
+ * A tree id for a revision or tree. Throws when it names nothing.
+ * @param {string} root
+ * @param {string} rev
+ */
+export const treeOf = (root, rev) => git(root, ["rev-parse", "--verify", "--quiet", `${rev}^{tree}`]).trim();
+
+/**
+ * What the next commit would contain: the index against HEAD (against nothing before the first
+ * commit).
+ * @param {string} root
+ * @returns {Change[]}
+ */
+export function stagedDiff(root) {
+  let base;
+  try {
+    base = treeOf(root, "HEAD");
+  } catch (e) {
+    // No HEAD yet is the only failure that is not an error: a repository before its first commit.
+    if (git(root, ["rev-parse", "--is-inside-work-tree"]).trim() !== "true") throw e;
+    base = emptyTree(root);
+  }
+  const changes = parseRaw(git(root, ["diff-index", "--cached", ...RAW, base, "--"]));
+  // A merge being concluded: only what it adds beyond both sides, as commitDiff judges it.
+  const other = spawnSync("git", ["rev-parse", "-q", "--verify", "MERGE_HEAD^{commit}"], { cwd: root, encoding: "utf8", windowsHide: true });
+  if (other.status !== 0) return changes;
+  return ownChanges(changes, [parseRaw(git(root, ["diff-index", "--cached", ...RAW, other.stdout.trim(), "--"]))]);
+}
+
+/**
+ * The part of a merge that is the merge's own: the files that differ from every parent (a
+ * resolved conflict, an edit made in the merge). What each side brought is judged on its own
+ * commits, which CI checks one by one.
+ * @param {Change[]} first   the change against the first parent
+ * @param {Change[][]} others the change against each other parent
+ */
+const ownChanges = (first, others) => first.filter((c) => others.every((o) => o.some((x) => x.path === c.path)));
+
+/**
+ * The change one commit makes: against its first parent, or against nothing for a root commit.
+ * A merge is judged by its own part only (`ownChanges`).
+ * @param {string} root
+ * @param {string} commit
+ * @returns {Change[]}
+ */
+export function commitDiff(root, commit) {
+  const sha = git(root, ["rev-parse", "--verify", "--quiet", `${commit}^{commit}`]).trim();
+  const [, firstParent, ...others] = git(root, ["rev-list", "--parents", "-n", "1", sha]).trim().split(" ");
+  const against = (/** @type {string} */ base) => parseRaw(git(root, ["diff-tree", "-r", ...RAW, base, sha, "--"]));
+  const changes = against(firstParent ?? emptyTree(root));
+  return others.length ? ownChanges(changes, others.map(against)) : changes;
+}
+
+/**
+ * The change from one tree to another, whatever lies between them.
+ * @param {string} root @param {string} from @param {string} to
+ * @returns {Change[]}
+ */
+export const treeDiff = (root, from, to) => parseRaw(git(root, ["diff-tree", "-r", ...RAW, from, to, "--"]));
+
+/**
+ * The tree the work tree holds now, as `git add -A` and a commit would make it (ignored files
+ * left out), written through a copy of the index so the real one is untouched and files git has
+ * already hashed are not hashed again.
+ * @param {string} root
+ * @returns {string}
+ */
+export function worktreeTree(root) {
+  const dir = mkdtempSync(join(tmpdir(), "trellis-tree-"));
+  try {
+    const index = join(dir, "index");
+    const real = resolve(root, git(root, ["rev-parse", "--git-path", "index"]).trim());
+    if (existsSync(real)) copyFileSync(real, index);
+    const env = { ...process.env, GIT_INDEX_FILE: index };
+    const run = (/** @type {string[]} */ args) => {
+      const r = spawnSync("git", args, { cwd: root, encoding: "utf8", env, maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+      if (r.status !== 0) throw new GitError(args, (r.stderr || `exit ${r.status}`).trim());
+      return r.stdout.trim();
+    };
+    if (!existsSync(real)) run(["read-tree", "--empty"]);
+    run(["add", "-A", "--", "."]);
+    return run(["write-tree"]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** A commit's parents. @param {string} root @param {string} commit */
+export const parentsOf = (root, commit) => git(root, ["rev-list", "--parents", "-n", "1", commit]).trim().split(" ").slice(1);
+
+/**
+ * The work tree against a recorded tree: tracked files as they are on disk, and untracked files
+ * git does not ignore. A file an ignore rule hides is not part of the change: it is not
+ * committed, so the commit checkpoint and CI never ship it either.
+ * @param {string} root
+ * @param {string} base  a tree id (as `treeOf` gives it)
+ * @returns {Change[]}
+ */
+export function worktreeDiff(root, base) {
+  if (git(root, ["cat-file", "-t", base]).trim() !== "tree") throw new GitError(["cat-file", "-t", base], "not a tree");
+  const tracked = parseRaw(git(root, ["diff-index", ...RAW, base, "--"]));
+  const known = new Set(tracked.map((c) => c.path));
+  const untracked = git(root, ["ls-files", "--others", "--exclude-standard", "-z"])
+    .split("\0")
+    .filter((p) => p && !known.has(p))
+    .map((path) => /** @type {Change} */ ({ path, status: "A", oldBlob: null, newBlob: null }));
+  const changes = [...tracked, ...untracked];
+  // git leaves a work-tree file it has not hashed as 000...; hash those as `git add` would.
+  const unhashed = changes.filter((c) => c.status !== "D" && (c.newBlob == null || zero(c.newBlob)));
+  if (unhashed.length) {
+    const ids = git(root, ["hash-object", "--stdin-paths"], `${unhashed.map((c) => c.path).join("\n")}\n`).trim().split(/\r?\n/);
+    if (ids.length !== unhashed.length) throw new GitError(["hash-object", "--stdin-paths"], "fewer ids than files");
+    unhashed.forEach((c, i) => (c.newBlob = ids[i]));
+  }
+  return changes;
+}

package/src/core/evidence.mjs

@@ -0,0 +1,167 @@
+// The evidence log: one append-only file per repository, written by whatever ran a check (the
+// Trellis gateway, the `trellis` CLI, an agent hook) and read at the commit checkpoint. Each line
+// is signed and chained to the one before it by its hash, so an edited, removed or reordered line
+// reads as tampering, never as fewer events. A signed checkpoint marks the line the last commit
+// stopped at; a verification reads the events after it.
+//
+// Same-user limit: the key is the user's, so an agent running as that user can forge a line with
+// enough effort. Locally this is integrity, not proof; CI re-runs the deterministic checks.
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { sign, stateDir, testOverride, valid } from "../agents/state.mjs";
+
+/**
+ * @typedef {object} Event
+ * @property {string} kind      graph, docs, schema, browser, tests, review, plan, approval, escalation, agent (an agent at work)
+ * @property {string} tool      what ran it (graphify, context7, npm test...)
+ * @property {string} agent     who asked for it: an agent's id, or "person"
+ * @property {string} [subject] what it was about (a query, package names, a URL), as a digest when private
+ * @property {Record<string, string>} [blobs]  path -> blob id of each file it checked, as it was then
+ * @property {string} [tree]    the whole tree a test run ran on, when the run left it unchanged
+ * @property {number} [result]  an exit code, for checks that have one
+ * @property {number} [at]      when it was recorded (ms), set by appendEvent
+ */
+
+/** The evidence folder: the test override, else the git folder's `trellis`. @param {string} root @param {NodeJS.ProcessEnv} env */
+const dir = (root, env) => testOverride(env, "TRELLIS_STATE_DIR") ?? join(stateDir(root, env), "..");
+
+/** @param {string} root @param {NodeJS.ProcessEnv} [env] */
+export const evidenceFile = (root, env = process.env) => join(dir(root, env), "evidence.jsonl");
+/** @param {string} root @param {NodeJS.ProcessEnv} env */
+const checkpointFile = (root, env) => join(dir(root, env), "checkpoint.json");
+
+/** @param {string} line */
+const hashOf = (line) => createHash("sha256").update(line).digest("hex");
+
+/** @param {string} file */
+const linesOf = (file) => (existsSync(file) ? readFileSync(file, "utf8").split("\n").filter(Boolean) : []);
+
+/**
+ * Appends one event, signed and chained to the last line.
+ * @param {string} root
+ * @param {Event} event
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function appendEvent(root, event, env = process.env) {
+  const file = evidenceFile(root, env);
+  mkdirSync(join(file, ".."), { recursive: true });
+  // The gateway, the hooks and parallel tool calls write at once: reading the last line and
+  // appending after it must be one step, or two writers chain to the same line and the log reads
+  // as tampered for good.
+  withLock(`${file}.lock`, () => {
+    const lines = linesOf(file);
+    const prev = lines.length ? hashOf(lines[lines.length - 1]) : "";
+    const e = { ...event, at: Date.now() };
+    const body = JSON.stringify({ e, prev });
+    appendFileSync(file, `${JSON.stringify({ e, prev, sig: sign(body, env) })}\n`);
+  });
+}
+
+/** A lock older than this was left by a writer that died holding it. */
+const STALE_LOCK_MS = 10_000;
+const LOCK_WAIT_MS = 15_000;
+const HELD = new Set(["EEXIST", "EPERM", "EBUSY", "EACCES"]);
+
+/**
+ * Runs `fn` holding an exclusive lock file. Creating a file with `wx` is atomic on every platform.
+ * Waits for a writer holding it, takes over a lock left by a writer that died, and throws rather
+ * than write unlocked.
+ * @param {string} lock
+ * @param {() => void} fn
+ */
+function withLock(lock, fn) {
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  const sleeper = new Int32Array(new SharedArrayBuffer(4));
+  for (;;) {
+    try {
+      closeSync(openSync(lock, "wx"));
+      break;
+    } catch (e) {
+      // Windows answers EPERM or EBUSY, not EEXIST, while another writer's lock is being removed.
+      if (!HELD.has(String(/** @type {NodeJS.ErrnoException} */ (e).code))) throw e;
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > STALE_LOCK_MS) rmSync(lock, { force: true });
+      } catch {
+        /* released meanwhile */
+      }
+      if (Date.now() > deadline) throw new Error(`the evidence log stayed locked (${lock}); remove the file if no Trellis is running`);
+      Atomics.wait(sleeper, 0, 0, 5 + Math.floor(Math.random() * 20));
+    }
+  }
+  try {
+    fn();
+  } finally {
+    rmSync(lock, { force: true });
+  }
+}
+
+/**
+ * The events since the last checkpoint, or "tampered" when any line, the chain or the checkpoint
+ * does not verify. A log that does not exist is no evidence, which every rule that needs some
+ * reads as missing.
+ * @param {string} root
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ status: "ok" | "tampered", events: Event[] }}
+ */
+export function readWindow(root, env = process.env) {
+  const lines = linesOf(evidenceFile(root, env));
+  /** @type {Event[]} */
+  const events = [];
+  let prev = "";
+  for (const line of lines) {
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      return { status: "tampered", events: [] };
+    }
+    if (rec?.prev !== prev || !valid(rec?.sig, JSON.stringify({ e: rec?.e, prev: rec?.prev }), env)) return { status: "tampered", events: [] };
+    events.push(rec.e);
+    prev = hashOf(line);
+  }
+  let from = 0;
+  const cp = checkpointFile(root, env);
+  if (existsSync(cp)) {
+    let c;
+    try {
+      c = JSON.parse(readFileSync(cp, "utf8"));
+    } catch {
+      return { status: "tampered", events: [] };
+    }
+    if (!Number.isInteger(c?.line) || c.line > lines.length || !valid(c?.sig, `checkpoint:${c?.line}`, env)) return { status: "tampered", events: [] };
+    from = c.line;
+  }
+  return { status: "ok", events: events.slice(from) };
+}
+
+/**
+ * Marks the end of the log as the start of the next window, after a commit.
+ * @param {string} root
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function checkpoint(root, env = process.env) {
+  const line = linesOf(evidenceFile(root, env)).length;
+  mkdirSync(dir(root, env), { recursive: true });
+  writeFileSync(checkpointFile(root, env), JSON.stringify({ line, sig: sign(`checkpoint:${line}`, env) }));
+}
+
+/**
+ * Sets the log and its checkpoint aside, kept under a dated name, and starts a new one: the way
+ * out of a log that no longer verifies. A person's step; what was set aside is never deleted.
+ * @param {string} root
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string | null} the name the old log was kept under, or null when there was none
+ */
+export function resetEvidence(root, env = process.env) {
+  const file = evidenceFile(root, env);
+  let kept = null;
+  withLock(`${file}.lock`, () => {
+    if (existsSync(file)) {
+      kept = file.replace(/\.jsonl$/, `.${new Date().toISOString().replace(/[:.]/g, "-")}.set-aside.jsonl`);
+      renameSync(file, kept);
+    }
+    rmSync(checkpointFile(root, env), { force: true });
+  });
+  return kept;
+}

package/src/core/mcp.mjs

@@ -0,0 +1,51 @@
+// Merging MCP servers into .mcp.json. Additive only: an entry the repository already has for the
+// same tool is left exactly as it is, because a person may have tuned it on purpose.
+import { mcpServers } from "../tools/registry.mjs";
+import { parseJson } from "./context.mjs";
+
+/** @typedef {import("./context.mjs").Context} Context */
+/** @typedef {import("../tools/registry.mjs").Tool} Tool */
+
+/** How each tool's entry is recognised in an existing file, whatever its key is called. */
+const MATCHERS = /** @type {Record<string, RegExp>} */ ({
+  context7: /context7-mcp/,
+  "postgres-mcp": /postgres-mcp/,
+  "playwright-mcp": /@playwright\/mcp/,
+});
+
+/** The key a new entry is written under. */
+const KEYS = /** @type {Record<string, string>} */ ({ context7: "context7", "postgres-mcp": "postgres", "playwright-mcp": "playwright" });
+
+/**
+ * The new .mcp.json text, and which entries it adds. `text` is null when nothing changes.
+ * @param {Context} ctx
+ * @param {Array<{ tool: Tool, opts: Record<string, any> }>} enabled
+ * @param {{ type: string, command: string, args: string[] } | null} [gateway]  the Trellis server's entry, when Trellis is installed
+ * @returns {{ text: string | null, added: string[], kept: string[] }}
+ */
+export function planMcp(ctx, enabled, gateway = null) {
+  const raw = ctx.read(".mcp.json");
+  const current = parseJson(raw);
+  if (raw != null && current == null) throw new Error(".mcp.json is not valid JSON; fix it before trellis writes to it");
+  const doc = current ?? {};
+  doc.mcpServers ??= {};
+  const added = [];
+  const kept = [];
+  for (const { tool, opts } of enabled) {
+    if (!tool.mcp) continue;
+    if (mcpServers(ctx, MATCHERS[tool.id]).length) {
+      kept.push(tool.id);
+      continue;
+    }
+    let key = KEYS[tool.id] ?? tool.id;
+    if (doc.mcpServers[key]) key = `${key}-trellis`;
+    doc.mcpServers[key] = tool.mcp(opts);
+    added.push(tool.id);
+  }
+  // Trellis's own server: the checks as tools for any agent. Kept as it is if already declared.
+  if (gateway && !Object.values(doc.mcpServers).some((s) => /trellis(\.mjs)?["']?,?\s*"?mcp\b/.test(JSON.stringify([s?.command, ...(s?.args ?? [])])))) {
+    doc.mcpServers[doc.mcpServers.trellis ? "trellis-gateway" : "trellis"] = gateway;
+    added.push("trellis");
+  }
+  return { text: added.length ? `${JSON.stringify(doc, null, 2)}\n` : null, added, kept };
+}

package/src/index.mjs

@@ -0,0 +1,11 @@
+export { createContext } from "./core/context.mjs";
+export { CONFIG_FILE, defaultConfig, enabledTools, loadConfig, validateConfig } from "./core/config.mjs";
+export { planMcp } from "./core/mcp.mjs";
+export { renderBlock, upsertBlock } from "./core/agents-block.mjs";
+export { TOOLS, toolById, installHint, mcpServers } from "./tools/registry.mjs";
+export { ROLES, roleById } from "./tools/roles.mjs";
+export { diagnose, doctor } from "./commands/doctor.mjs";
+export { planInit, init } from "./commands/init.mjs";
+export { guide } from "./commands/guide.mjs";
+export { scan } from "./commands/scan.mjs";
+export { main } from "./cli/main.mjs";

package/src/mcp/client.mjs

@@ -0,0 +1,164 @@
+// Trellis as an MCP client of the servers it relays, over stdio, either era (specification
+// 2026-07-28, stdio "Backward Compatibility"): probe with server/discover; a discover result or a
+// recognised modern error means a modern server, anything else (or no answer) a legacy one, which
+// gets the initialize handshake.
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { VERSION } from "../core/config.mjs";
+import { launchSpec } from "./launch.mjs";
+
+const MODERN = "2026-07-28";
+const LEGACY = "2025-11-25";
+/** Errors only a modern server sends: UnsupportedProtocolVersion, HeaderMismatch, MissingRequiredClientCapability. */
+const MODERN_ERRORS = new Set([-32022, -32020, -32021]);
+const CLIENT = { name: "trellis", version: VERSION };
+
+/** An error a server answered with. */
+export class RpcError extends Error {
+  /** @param {{ code: number, message: string, data?: any }} e */
+  constructor(e) {
+    super(e.message);
+    this.code = e.code;
+    this.data = e.data;
+  }
+}
+
+/** `${VAR}` in a server entry, from the environment, as Claude Code expands it. @param {any} v @param {NodeJS.ProcessEnv} env */
+const expand = (v, env) => (typeof v === "string" ? v.replace(/\$\{(\w+)\}/g, (_, name) => env[name] ?? "") : v);
+
+/**
+ * One relayed server: launched on first use, its era detected once.
+ */
+export class Upstream {
+  /**
+   * @param {string} name
+   * @param {{ command: string, args?: string[], env?: Record<string, string>, cwd?: string }} entry
+   * @param {{ cwd: string, env: NodeJS.ProcessEnv }} where
+   */
+  constructor(name, entry, where) {
+    this.name = name;
+    this.entry = entry;
+    this.where = where;
+    /** @type {"modern" | "legacy" | null} */
+    this.era = null;
+    this.version = MODERN;
+    /** @type {Map<number, { resolve: (v: any) => void, reject: (e: Error) => void, timer: NodeJS.Timeout }>} */
+    this.pending = new Map();
+    this.next = 1;
+    /** @type {Promise<void> | null} */
+    this.ready = null;
+    /** @type {import("node:child_process").ChildProcess | null} */
+    this.child = null;
+    /** @type {Error | null} why the server is gone, once it is: every later request fails at once */
+    this.gone = null;
+  }
+
+  /** Launches the server and settles its era; once. */
+  start() {
+    this.ready ??= this.#launch();
+    return this.ready;
+  }
+
+  async #launch() {
+    const env = { ...this.where.env, ...Object.fromEntries(Object.entries(this.entry.env ?? {}).map(([k, v]) => [k, expand(v, this.where.env)])) };
+    const command = expand(this.entry.command, this.where.env);
+    const args = (this.entry.args ?? []).map((a) => expand(a, this.where.env));
+    // `npx` and the like are .cmd shims on Windows: ./launch.mjs gets their arguments through cmd.exe intact.
+    const spec = launchSpec(command, args, env);
+    const child = spawn(spec.file, spec.args, { cwd: this.entry.cwd ?? this.where.cwd, env, stdio: ["pipe", "pipe", "pipe"], shell: spec.shell, windowsVerbatimArguments: spec.windowsVerbatimArguments, windowsHide: true });
+    this.child = child;
+    const end = (/** @type {Error} */ e) => {
+      this.gone ??= e;
+      this.#failAll(e);
+    };
+    child.on("error", end);
+    child.on("exit", (code) => end(new Error(`${this.name} exited (code ${code})`)));
+    child.stderr?.on("data", () => {});
+    createInterface({ input: /** @type {NodeJS.ReadableStream} */ (child.stdout) }).on("line", (line) => this.#receive(line));
+    try {
+      const discover = await this.#send("server/discover", { _meta: this.#meta() }, 5_000);
+      const supported = discover?.supportedVersions ?? [];
+      this.era = "modern";
+      if (supported.length && !supported.includes(MODERN)) throw new Error(`${this.name} supports ${supported.join(", ")}, not ${MODERN}`);
+    } catch (e) {
+      if (e instanceof RpcError && MODERN_ERRORS.has(/** @type {number} */ (e.code))) {
+        this.era = "modern";
+        const supported = e.data?.supported ?? [];
+        if (!supported.includes(MODERN)) throw new Error(`${this.name} supports ${supported.join(", ")}, not ${MODERN}`);
+        return;
+      }
+      if (this.era === "modern") throw e;
+      // Anything else, an unknown-method error or silence, is a legacy server.
+      this.era = "legacy";
+      const init = await this.#send("initialize", { protocolVersion: LEGACY, capabilities: {}, clientInfo: CLIENT }, 60_000);
+      this.version = String(init?.protocolVersion ?? LEGACY);
+      this.#notify("notifications/initialized");
+    }
+  }
+
+  #meta() {
+    return { "io.modelcontextprotocol/protocolVersion": MODERN, "io.modelcontextprotocol/clientInfo": CLIENT, "io.modelcontextprotocol/clientCapabilities": {} };
+  }
+
+  /** @param {string} line */
+  #receive(line) {
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return;
+    }
+    const p = this.pending.get(msg?.id);
+    if (!p) return;
+    this.pending.delete(msg.id);
+    clearTimeout(p.timer);
+    if (msg.error) p.reject(new RpcError(msg.error));
+    else p.resolve(msg.result);
+  }
+
+  /** @param {Error} e */
+  #failAll(e) {
+    for (const p of this.pending.values()) {
+      clearTimeout(p.timer);
+      p.reject(e);
+    }
+    this.pending.clear();
+  }
+
+  /** @param {string} method @param {any} params @param {number} timeoutMs */
+  #send(method, params, timeoutMs) {
+    if (this.gone) return Promise.reject(this.gone);
+    const id = this.next++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${this.name}: no answer to ${method} within ${timeoutMs / 1000} s`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      this.child?.stdin?.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+    });
+  }
+
+  /** @param {string} method */
+  #notify(method) {
+    this.child?.stdin?.write(`${JSON.stringify({ jsonrpc: "2.0", method })}\n`);
+  }
+
+  /**
+   * A request in the server's era: modern ones carry their `_meta`.
+   * @param {string} method
+   * @param {Record<string, any>} [params]
+   * @param {number} [timeoutMs]
+   */
+  async request(method, params = {}, timeoutMs = 120_000) {
+    await this.start();
+    const p = this.era === "modern" ? { ...params, _meta: { ...(params._meta ?? {}), ...this.#meta() } } : params;
+    return this.#send(method, p, timeoutMs);
+  }
+
+  close() {
+    this.#failAll(new Error(`${this.name} closed`));
+    this.child?.stdin?.end();
+    this.child?.kill();
+  }
+}

package/src/mcp/launch.mjs

@@ -0,0 +1,57 @@
+// How a relayed server's command line reaches the operating system unchanged. On Windows, a
+// command named without a path (`npx`, `uvx`) is looked up on PATH as Windows does: an `.exe` is
+// started directly, its arguments quoted by Node; a `.cmd` or `.bat` shim can only run through
+// cmd.exe, which reads `"`, `%`, `&`, `^` and the like itself, so each argument is escaped for it,
+// twice for a shim (cmd reads the line once, the shim passes it on once more), the way cross-spawn
+// does. Elsewhere the command and its arguments go to the system as they are.
+import { existsSync } from "node:fs";
+import { delimiter, extname, join } from "node:path";
+
+const META = /([()\][%!^"`<>&|;, *?])/g;
+
+/**
+ * One argument for cmd.exe: backslashes before a quote doubled, quoted, cmd's characters escaped.
+ * @param {string} arg @param {boolean} shim
+ */
+function cmdArg(arg, shim) {
+  let a = String(arg)
+    .replace(/(\\*)"/g, '$1$1\\"')
+    .replace(/(\\*)$/, "$1$1");
+  a = `"${a}"`.replace(META, "^$1");
+  return shim ? a.replace(META, "^$1") : a;
+}
+
+/**
+ * Where Windows finds `command`, by PATH and PATHEXT, or null.
+ * @param {string} command @param {NodeJS.ProcessEnv} env
+ */
+function onPath(command, env) {
+  const exts = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+  const dirs = (env.PATH ?? env.Path ?? "").split(delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    for (const ext of extname(command) ? [""] : exts) {
+      const file = join(dir, command + ext);
+      if (existsSync(file)) return file;
+    }
+  }
+  return null;
+}
+
+/**
+ * What to hand to spawn for `command` with `args`.
+ * @param {string} command
+ * @param {string[]} args
+ * @param {NodeJS.ProcessEnv} env
+ * @param {NodeJS.Platform} [platform]
+ * @returns {{ file: string, args: string[], shell: boolean, windowsVerbatimArguments: boolean }}
+ */
+export function launchSpec(command, args, env, platform = process.platform) {
+  if (platform !== "win32") return { file: command, args, shell: false, windowsVerbatimArguments: false };
+  const found = /[\\/]/.test(command) ? command : (onPath(command, env) ?? command);
+  if (!/\.(cmd|bat)$/i.test(found)) return { file: found, args, shell: false, windowsVerbatimArguments: false };
+  // cmd.exe ends a command at a line break, whatever the quoting: such an argument would arrive cut.
+  if (args.some((a) => /[\r\n]/.test(a))) throw new Error(`an argument holds a line break, which cmd.exe cannot pass to ${command}; start it through node or an .exe instead`);
+  // cmd.exe /d /s /c "<line>": the line is passed as it is, each part escaped above.
+  const line = [found.replace(META, "^$1"), ...args.map((a) => cmdArg(a, true))].join(" ");
+  return { file: env.ComSpec ?? env.COMSPEC ?? "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], shell: false, windowsVerbatimArguments: true };
+}