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

package/src/mcp/relay.mjs

@@ -0,0 +1,111 @@
+// The servers the gateway relays: every stdio server declared in .mcp.json except Trellis itself,
+// once a person has trusted it (./trust.mjs). Their tools are offered as `<server>__<tool>`; a call goes to the server as it was asked, its
+// answer comes back unchanged, and when it succeeded Trellis records what kind of check it was
+// (docs, schema, browser), because Trellis saw it answer.
+import { appendEvent } from "../core/evidence.mjs";
+import { uiBlobs } from "../agents/adapters.mjs";
+import { Upstream } from "./client.mjs";
+import { fingerprint, relayable, SEP, trustedServers } from "./trust.mjs";
+
+/**
+ * What a successful call to a server's `tool` is evidence of, if anything. Read from what the
+ * entry runs (its command and arguments), never from the name it is given in .mcp.json: any
+ * server can be called "context7".
+ * @param {any} entry
+ * @param {string} tool
+ * @returns {"docs" | "schema" | "browser" | null}
+ */
+function kindOf(entry, tool) {
+  const runs = [entry?.command, ...(entry?.args ?? [])].join(" ");
+  if (/context7/i.test(runs)) return "docs";
+  if (/postgres/i.test(runs)) return "schema";
+  if (/playwright/i.test(runs) && /^browser_(snapshot|take_screenshot)$/.test(tool)) return "browser";
+  return null;
+}
+
+export class Relay {
+  /**
+   * @param {import("../core/context.mjs").Context} ctx
+   * @param {NodeJS.ProcessEnv} env
+   */
+  constructor(ctx, env) {
+    this.ctx = ctx;
+    this.env = env;
+    /** @type {Map<string, Upstream>} */
+    this.servers = new Map();
+    /** @type {string[]} */
+    this.notRelayed = [];
+    /** @type {Map<string, any>} */
+    this.entries = new Map();
+    const { servers, skipped } = relayable(ctx);
+    this.notRelayed.push(...skipped);
+    const trusted = trustedServers(ctx.root, env);
+    for (const [name, entry] of servers) {
+      // Started only as a person trusted it: .mcp.json is a file a pull request can change.
+      if (trusted[name] !== fingerprint(entry, ctx.root)) {
+        this.notRelayed.push(`${name}: ${trusted[name] ? "changed since it was trusted" : "not trusted yet"}; a person runs \`npx --no-install @synovitec/trellis mcp trust\` in a terminal`);
+        continue;
+      }
+      this.servers.set(name, new Upstream(name, entry, { cwd: ctx.root, env }));
+      this.entries.set(name, entry);
+    }
+    /** @type {Map<string, any[]>} */
+    this.toolsBy = new Map();
+  }
+
+  /**
+   * Every relayed tool, prefixed with its server's name. A server that does not start is said in
+   * `notRelayed`, never waited on forever.
+   * @returns {Promise<any[]>}
+   */
+  async tools() {
+    const lists = await Promise.all(
+      [...this.servers].map(async ([name, up]) => {
+        try {
+          const { tools = [] } = await up.request("tools/list", {}, 60_000);
+          this.toolsBy.set(name, tools);
+          return tools.map((/** @type {any} */ t) => ({ ...t, name: `${name}${SEP}${t.name}`, description: `[${name}, relayed by Trellis] ${t.description ?? ""}`.trim() }));
+        } catch (e) {
+          this.notRelayed.push(`${name}: did not start (${e instanceof Error ? e.message : String(e)})`);
+          this.servers.delete(name);
+          up.close();
+          return [];
+        }
+      }),
+    );
+    return lists.flat();
+  }
+
+  /**
+   * Relays one call, or returns null when `name` is not a relayed tool.
+   * @param {string} name
+   * @param {Record<string, any>} args
+   * @param {string} agent
+   */
+  async call(name, args, agent) {
+    const i = name.indexOf(SEP);
+    if (i === -1) return null;
+    const server = name.slice(0, i);
+    const tool = name.slice(i + SEP.length);
+    const up = this.servers.get(server);
+    if (!up) return null;
+    if (!this.toolsBy.has(server)) await this.tools();
+    if (!(this.toolsBy.get(server) ?? []).some((t) => t.name === tool)) return null;
+    const result = await up.request("tools/call", { name: tool, arguments: args });
+    const { resultType: _, ...plain } = result ?? {};
+    const kind = kindOf(this.entries.get(server), tool);
+    if (kind && !plain.isError) {
+      if (kind === "browser") {
+        const blobs = uiBlobs(this.ctx);
+        if (blobs) appendEvent(this.ctx.root, { kind, tool: name, agent, blobs }, this.env);
+      } else {
+        appendEvent(this.ctx.root, { kind, tool: name, agent, subject: JSON.stringify(args).toLowerCase().slice(0, 500) }, this.env);
+      }
+    }
+    return plain;
+  }
+
+  close() {
+    for (const up of this.servers.values()) up.close();
+  }
+}

package/src/mcp/server.mjs

@@ -0,0 +1,210 @@
+// `trellis mcp`: Trellis as an MCP server, so any agent that speaks MCP gets the repository's checks
+// as tools, and Trellis records the evidence itself: it ran the call and saw the answer. The
+// strongest evidence there is, and it does not depend on an agent's hooks or transcript.
+//
+// Dual-era, as the specification allows (2026-07-28, "Versioning and Compatibility"): a modern
+// client sends its version and capabilities in each request's `_meta`; a legacy client opens with
+// `initialize` and gets the legacy semantics for this process. stdio framing: one JSON-RPC message
+// per line on stdout, nothing else there; logs go to stderr.
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { appendEvent } from "../core/evidence.mjs";
+import { VERSION } from "../core/config.mjs";
+import { testOverride } from "../agents/state.mjs";
+import { checkTests, escalate, verify } from "../commands/verify.mjs";
+import { Relay } from "./relay.mjs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { normalise, testEnv } from "../verify/test-commands.mjs";
+
+const MODERN = ["2026-07-28"];
+const LEGACY = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+const KEY = { version: "io.modelcontextprotocol/protocolVersion", client: "io.modelcontextprotocol/clientInfo", caps: "io.modelcontextprotocol/clientCapabilities", server: "io.modelcontextprotocol/serverInfo" };
+const SERVER_INFO = { name: "trellis", version: VERSION };
+const INSTRUCTIONS =
+  "The repository's checks, run by Trellis and recorded as evidence for the commit checkpoint. Ask graph_query before changing code; run the tests with run_tests; if a test or the task is wrong, call escalate and stop; check_change says what the next commit would be refused for.";
+
+const TOOLS = [
+  {
+    name: "graph_query",
+    description: "Ask the repository's code graph where something lives and what depends on it (graphify). Use it before changing code.",
+    inputSchema: { type: "object", properties: { question: { type: "string", description: "What you are about to change, and what you need to know about it" } }, required: ["question"] },
+  },
+  {
+    name: "run_tests",
+    description: "Run the test command; Trellis records which changed files it ran on and its exit code. A test run you only describe counts for nothing.",
+    inputSchema: { type: "object", properties: { command: { type: "string", description: "The test command, e.g. npm test" } }, required: ["command"] },
+  },
+  {
+    name: "escalate",
+    description: "Stop and hand the change to a person: a test that contradicts the task, a requirement you cannot meet. The change is held until a person approves it.",
+    inputSchema: { type: "object", properties: { reason: { type: "string" } }, required: ["reason"] },
+  },
+  {
+    name: "check_change",
+    description: "What the commit checkpoint would say about the staged change now, without committing.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+/** @typedef {{ jsonrpc: "2.0", id?: string | number, method?: string, params?: any }} Message */
+
+/** A client's name as the evidence names an agent; self-reported, so for labels only. @param {any} info */
+const agentOf = (info) => (typeof info?.name === "string" && info.name.trim() ? info.name.trim().slice(0, 60) : "mcp-client");
+
+/** @param {string} text @param {boolean} isError */
+const toolResult = (text, isError) => ({ content: [{ type: "text", text: text.slice(0, 50_000) }], isError });
+
+/**
+ * One tool call. Returns the tool result, or null for an unknown tool.
+ * @param {string} name
+ * @param {Record<string, any>} args
+ * @param {{ ctx: import("../core/context.mjs").Context, env: NodeJS.ProcessEnv, agent: string }} c
+ */
+async function callTool(name, args, c) {
+  const env = { ...c.env, TRELLIS_AGENT: c.agent };
+  /** @type {string[]} */
+  const lines = [];
+  const out = (/** @type {string[]} */ ...l) => void lines.push(...l);
+  if (name === "graph_query") {
+    const question = String(args.question ?? "").trim();
+    if (!question) return toolResult("graph_query needs a question.", true);
+    const custom = testOverride(c.env, "TRELLIS_GRAPHIFY");
+    const bin = custom ? process.execPath : c.ctx.which("graphify");
+    if (!bin) return toolResult("graphify is not installed here: there is no code graph to ask.", true);
+    const r = spawnSync(bin, custom ? [custom, "query", question] : ["query", question], { cwd: c.ctx.root, encoding: "utf8", timeout: 120_000, windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+    const text = `${r.stdout ?? ""}${r.stderr ? `\n${r.stderr}` : ""}`.trim();
+    // Answered: graphify's own output, from graphify itself, which Trellis ran.
+    const answered = r.status === 0 && /^Graph: .*\bnodes?\b|^NODE /m.test(r.stdout ?? "");
+    if (answered) appendEvent(c.ctx.root, { kind: "graph", tool: "graphify", agent: c.agent, subject: question.slice(0, 300) }, c.env);
+    return toolResult(text || "graphify gave no answer.", !answered);
+  }
+  if (name === "run_tests") {
+    const command = String(args.command ?? "").trim();
+    if (!command) return toolResult("run_tests needs the test command.", true);
+    let output = "";
+    const run = () => {
+      // The same environment as `trellis check tests`: nothing that steers the runner.
+      const dir = mkdtempSync(join(tmpdir(), "trellis-empty-"));
+      writeFileSync(join(dir, "npmrc"), "");
+      writeFileSync(join(dir, "npmrc.global"), "");
+      // What runs is the command as it was accepted, never the raw text that matched it.
+      const r = spawnSync(normalise(command), { cwd: c.ctx.root, encoding: "utf8", shell: true, timeout: 30 * 60_000, windowsHide: true, maxBuffer: 64 * 1024 * 1024, env: testEnv(process.env, join(dir, "npmrc")) });
+      rmSync(dir, { recursive: true, force: true });
+      output = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+      return r.status;
+    };
+    const code = checkTests(c.ctx, [command], out, { env, run });
+    // The end of a test run says what failed; keep that part when the output is long.
+    return toolResult(`${output.length > 40_000 ? `...\n${output.slice(-40_000)}` : output}\n${lines.join("\n")}`.trim(), code !== 0);
+  }
+  if (name === "escalate") {
+    const code = escalate(c.ctx, String(args.reason ?? ""), out, { env });
+    return toolResult(lines.join("\n"), code !== 0);
+  }
+  if (name === "check_change") {
+    const code = await verify(c.ctx, out, { env });
+    return toolResult(lines.join("\n"), code !== 0);
+  }
+  return null;
+}
+
+/**
+ * Answers one message: a response, or null for a notification.
+ * @param {Message} msg
+ * @param {{ ctx: import("../core/context.mjs").Context, env: NodeJS.ProcessEnv, legacy: { version: string, client: any } | null, relay?: Relay }} state
+ * @returns {Promise<object | null>}
+ */
+export async function answer(msg, state) {
+  const id = msg.id;
+  if (id === undefined || id === null) return null;
+  const reply = (/** @type {object} */ result) => ({ jsonrpc: "2.0", id, result });
+  const fail = (/** @type {number} */ code, /** @type {string} */ message, /** @type {any} */ data) => ({ jsonrpc: "2.0", id, error: data === undefined ? { code, message } : { code, message, data } });
+  const params = msg.params ?? {};
+
+  if (msg.method === "initialize") {
+    const asked = String(params.protocolVersion ?? "");
+    const version = LEGACY.includes(asked) ? asked : LEGACY[0];
+    state.legacy = { version, client: params.clientInfo };
+    return reply({ protocolVersion: version, capabilities: { tools: {} }, serverInfo: SERVER_INFO, instructions: INSTRUCTIONS });
+  }
+
+  // A modern request carries its own version; a legacy one relies on the initialize before it.
+  const m = params._meta ?? {};
+  let agent;
+  let modern = false;
+  if (m[KEY.version] !== undefined) {
+    if (!MODERN.includes(m[KEY.version])) return fail(-32022, "Unsupported protocol version", { supported: [...MODERN, ...LEGACY], requested: m[KEY.version] });
+    if (m[KEY.caps] === undefined) return fail(-32602, `Invalid params: _meta must carry ${KEY.caps}`);
+    modern = true;
+    agent = agentOf(m[KEY.client]);
+  } else if (state.legacy) {
+    agent = agentOf(state.legacy.client);
+  } else if (msg.method === "ping") {
+    return reply({});
+  } else {
+    return fail(-32602, `Invalid params: a request must carry ${KEY.version} and ${KEY.caps} in _meta, or come after initialize`);
+  }
+  const done = (/** @type {Record<string, any>} */ result) => reply(modern ? { resultType: "complete", ...result, _meta: { ...(result._meta ?? {}), [KEY.server]: SERVER_INFO } } : result);
+
+  switch (msg.method) {
+    case "server/discover":
+      return done({ supportedVersions: [...MODERN, ...LEGACY], capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    case "ping":
+      return done({});
+    case "tools/list": {
+      const relayed = state.relay ? await state.relay.tools() : [];
+      // What could not be relayed is said, in the listing's own metadata, never hidden.
+      const notRelayed = state.relay?.notRelayed ?? [];
+      return done({ tools: [...TOOLS, ...relayed], ...(notRelayed.length ? { _meta: { "dev.trellis/notRelayed": notRelayed } } : {}) });
+    }
+    case "tools/call": {
+      const name = String(params.name ?? "");
+      const args = params.arguments ?? {};
+      const result = (await callTool(name, args, { ctx: state.ctx, env: state.env, agent })) ?? (state.relay ? await state.relay.call(name, args, agent) : null);
+      if (!result) return fail(-32602, `Unknown tool "${name}"`);
+      return done(result);
+    }
+    default:
+      return fail(-32601, `Method not found: ${msg.method}`);
+  }
+}
+
+/**
+ * Serves MCP over stdio until stdin closes.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {Promise<number>}
+ */
+export function serveMcp(ctx, env) {
+  /** @type {{ ctx: import("../core/context.mjs").Context, env: NodeJS.ProcessEnv, legacy: { version: string, client: any } | null, relay: Relay }} */
+  const state = { ctx, env, legacy: null, relay: new Relay(ctx, env) };
+  const write = (/** @type {object} */ m) => process.stdout.write(`${JSON.stringify(m)}\n`);
+  const pending = [];
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  rl.on("line", (line) => {
+    if (!line.trim()) return;
+    /** @type {Message} */
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      write({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+      return;
+    }
+    // initialize is answered before anything after it is read, so a legacy session is set first.
+    const p = answer(msg, state)
+      .then((r) => r && write(r))
+      .catch((e) => msg.id != null && write({ jsonrpc: "2.0", id: msg.id, error: { code: -32603, message: `Internal error: ${e instanceof Error ? e.message : String(e)}` } }));
+    pending.push(p);
+  });
+  return new Promise((resolve) =>
+    rl.on("close", () =>
+      void Promise.allSettled(pending).then(() => {
+        state.relay.close();
+        resolve(0);
+      }),
+    ),
+  );
+}

package/src/mcp/trust.mjs

@@ -0,0 +1,142 @@
+// Which servers of .mcp.json the gateway may start. A server is a command run on this machine,
+// and .mcp.json is a file a pull request can change: the gateway starts a server only once a
+// person has trusted that exact entry (command, arguments, environment, folder), as Claude Code
+// asks before it starts a project's servers. An entry that changes after it was trusted is held
+// again. The trust is this clone's, kept beside the evidence log, never in the repository.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { parseJson } from "../core/context.mjs";
+import { evidenceFile } from "../core/evidence.mjs";
+
+/** The relay's separator between a server's name and its tool's. */
+export const SEP = "__";
+
+/** An entry that runs Trellis's own server: never relayed, or the gateway would call itself. @param {any} s */
+export const isTrellis = (s) => /trellis(\.mjs)?["']?,?\s*"?mcp\b/.test(JSON.stringify([s?.command, ...(s?.args ?? [])]));
+
+/**
+ * The entries of .mcp.json the relay would start, and why the others are not.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @returns {{ servers: Array<[string, any]>, skipped: string[] }}
+ */
+export function relayable(ctx) {
+  const doc = parseJson(ctx.read(".mcp.json"));
+  /** @type {Array<[string, any]>} */
+  const servers = [];
+  const skipped = [];
+  for (const [name, entry] of Object.entries(doc?.mcpServers ?? {})) {
+    if (isTrellis(entry)) continue;
+    const type = entry?.type ?? (entry?.url ? "http" : "stdio");
+    if (name.includes(SEP)) skipped.push(`${name}: its name holds "${SEP}", which the relay uses to route`);
+    else if (type !== "stdio" || typeof entry?.command !== "string") skipped.push(`${name}: a ${type} server is not relayed yet; the agent reaches it directly`);
+    else servers.push([name, entry]);
+  }
+  return { servers, skipped };
+}
+
+/** What is trusted of an entry: everything that decides what runs. @param {any} entry @param {string} root */
+export const fingerprint = (entry, root) =>
+  createHash("sha256")
+    .update(JSON.stringify({ command: entry?.command, args: entry?.args ?? [], env: Object.entries(entry?.env ?? {}).sort(), cwd: entry?.cwd ?? null, files: filesRun(entry, root) }))
+    .digest("hex");
+
+/**
+ * The content of each repository file the entry names (`node scripts/mcp.js`): a pull request
+ * that changes the script changes what the trusted entry runs, so the trust does not hold.
+ * @param {any} entry @param {string} root
+ */
+function filesRun(entry, root) {
+  const base = resolve(root, entry?.cwd ?? ".");
+  /** @type {Record<string, string>} */
+  const files = {};
+  for (const token of [entry?.command, ...(entry?.args ?? [])]) {
+    if (typeof token !== "string" || !token || token.startsWith("-")) continue;
+    const path = resolve(base, token);
+    const inside = relative(root, path);
+    if (inside.startsWith("..") || isAbsolute(inside)) continue;
+    try {
+      if (statSync(path).isFile()) files[inside.replace(/\\/g, "/")] = createHash("sha256").update(readFileSync(path)).digest("hex");
+    } catch {
+      /* not a file: an argument */
+    }
+  }
+  return files;
+}
+
+/**
+ * Beside the evidence log in the git folder, wherever an environment variable points the log: a
+ * gateway entry's `env` must not move what the gateway trusts to a file a pull request commits.
+ * @param {string} root @param {NodeJS.ProcessEnv} _env
+ */
+const trustFile = (root, _env) => join(dirname(evidenceFile(root, {})), "mcp-trusted.json");
+
+/**
+ * The trusted entries, by server name. A missing or unreadable file trusts nothing.
+ * @param {string} root @param {NodeJS.ProcessEnv} env
+ * @returns {Record<string, string>}
+ */
+export function trustedServers(root, env) {
+  const file = trustFile(root, env);
+  const doc = existsSync(file) ? parseJson(readFileSync(file, "utf8")) : null;
+  return doc && typeof doc === "object" ? doc : {};
+}
+
+/**
+ * Records `entries` as trusted, beside those trusted already.
+ * @param {string} root @param {NodeJS.ProcessEnv} env @param {Array<[string, any]>} entries
+ */
+export function trustEntries(root, env, entries) {
+  const trusted = trustedServers(root, env);
+  for (const [name, entry] of entries) trusted[name] = fingerprint(entry, root);
+  mkdirSync(dirname(trustFile(root, env)), { recursive: true });
+  writeFileSync(trustFile(root, env), `${JSON.stringify(trusted, null, 2)}\n`);
+}
+
+/** One line from the terminal. */
+function askLine() {
+  const buf = Buffer.alloc(1);
+  let line = "";
+  try {
+    while (readSync(0, buf, 0, 1, null) === 1 && buf[0] !== 10) line += String.fromCharCode(buf[0]);
+  } catch {
+    /* no terminal: no answer */
+  }
+  return line.trim();
+}
+
+/**
+ * `trellis mcp trust`: shows what each untrusted server would run and, on a person's yes, trusts
+ * those exact entries. Refused without a terminal, like approve: an agent's commands run without one.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {(...lines: string[]) => void} out
+ * @param {{ env?: NodeJS.ProcessEnv, interactive?: boolean, confirm?: () => boolean }} [opts]
+ */
+export function trustCommand(ctx, out, opts = {}) {
+  const env = opts.env ?? process.env;
+  const interactive = opts.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!interactive) {
+    out("trellis mcp trust is a person's step: run it yourself, in a terminal.");
+    return 1;
+  }
+  const trusted = trustedServers(ctx.root, env);
+  const pending = relayable(ctx).servers.filter(([name, entry]) => trusted[name] !== fingerprint(entry, ctx.root));
+  if (!pending.length) {
+    out("trellis mcp trust: every server in .mcp.json is trusted already.");
+    return 0;
+  }
+  out("The gateway would start these servers of .mcp.json, as commands on this machine:");
+  for (const [name, entry] of pending) {
+    out(`  ${name}${trusted[name] ? " (changed since it was trusted)" : ""}: ${[entry.command, ...(entry.args ?? [])].join(" ")}`);
+    if (entry.env && Object.keys(entry.env).length) out(`      environment: ${Object.keys(entry.env).join(", ")}`);
+    if (entry.cwd) out(`      in: ${entry.cwd}`);
+  }
+  out("Trust them? [y/N]");
+  if (!(opts.confirm ?? (() => /^y(es)?$/i.test(askLine())))()) {
+    out("trellis mcp trust: nothing trusted.");
+    return 1;
+  }
+  trustEntries(ctx.root, env, pending);
+  out(`trellis mcp trust: ${pending.length} server(s) trusted; the gateway starts them from its next launch.`);
+  return 0;
+}