simt-dev 0.3.1 → 0.5.0

package/src/federation/client.mjs

@@ -0,0 +1,188 @@
+// The federation client: one stdio MCP conversation, spoken directly (plan 0003 R26).
+//
+// simt-dev carries no runtime dependency, and an external code-graph server speaks MCP over
+// stdio, which is newline-delimited JSON-RPC. That is a shape small enough to speak without
+// a client library, so this file is the whole client: start the server, initialize, ask one
+// tool for one text answer, and return that answer or the reason there is none.
+//
+// Two rules make it safe to put inside a brief:
+//
+//   * It never throws. A command that is not installed, a server that exits, one that
+//     answers with a protocol error, one that never answers at all — every one of them
+//     comes back as `{ error }` for the caller to render as a sentence. A brief that died
+//     because an optional server misbehaved would be a brief nobody keeps installed.
+//   * It always cleans up, and it always ends. The child is killed on the first answer, on
+//     an error and on the timeout, and the timeout is a real bound on a server that has
+//     forgotten how to read. Federation adds a wait with a ceiling, never an open one.
+//
+// The conversation is exactly three messages deep, which is the minimum MCP allows:
+// `initialize`, the `notifications/initialized` acknowledgement, then one `tools/call`.
+
+import { spawn } from 'node:child_process';
+
+/**
+ * The protocol revision this client opens with.
+ *
+ * Not this tool's newest — an external server predates it far more often than not — but the
+ * oldest revision every MCP server of the current generation is required to accept. A
+ * server that answers with a revision of its own is answering, and the reply is not
+ * second-guessed: this is a client for asking, not for negotiating.
+ */
+const PROTOCOL_VERSION = '2025-06-18';
+
+/** The longest a single server may take before the client stops waiting, in milliseconds. */
+export const DEFAULT_TIMEOUT_MS = 5000;
+
+const CLIENT_INFO = { name: 'simt-dev', version: '1' };
+
+/** The first non-blank text part of a result, or null when the result carries none. */
+function textOf(result) {
+  if (result === null || typeof result !== 'object') return null;
+  const content = Array.isArray(result.content) ? result.content : [];
+  for (const part of content) {
+    if (part !== null && typeof part === 'object' && part.type === 'text' && typeof part.text === 'string') {
+      if (part.text.trim().length > 0) return part.text;
+    }
+  }
+  return null;
+}
+
+/** One sentence for a JSON-RPC error object. */
+function reasonOf(error) {
+  if (error === null || typeof error !== 'object') return 'the server returned an error';
+  if (typeof error.message === 'string' && error.message.length > 0) return error.message;
+  if (error.code !== undefined) return `the server answered with error code ${error.code}`;
+  return 'the server returned an error';
+}
+
+/**
+ * Ask one server, over stdio, for one text answer to one question.
+ *
+ * @param {object} request
+ * @param {string} request.command the executable to start
+ * @param {string[]} [request.args] its arguments
+ * @param {string} [request.cwd] the directory to start it in
+ * @param {string} request.tool the MCP tool to call
+ * @param {string} [request.argument] the argument the question is placed in
+ * @param {string} request.query the question
+ * @param {number} [request.timeoutMs] how long to wait, in milliseconds
+ * @returns `{ text }` on an answer, `{ error }` on anything else — never a rejection
+ */
+export async function callTool({
+  command,
+  args = [],
+  cwd = undefined,
+  tool,
+  argument = 'query',
+  query,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'], cwd });
+    } catch (error) {
+      resolve({ error: `could not start \`${command}\` (${error.message})` });
+      return;
+    }
+
+    let settled = false;
+    let buffer = '';
+    let nextId = 1;
+    const pending = new Map();
+
+    const finish = (payload) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        child.stdin.end();
+      } catch {
+        // The pipe may already be gone; nothing to close in that case.
+      }
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // A process that has already exited cannot be killed again.
+      }
+      resolve(payload);
+    };
+
+    const timer = setTimeout(() => finish({ error: `no answer within ${timeoutMs} ms` }), timeoutMs);
+
+    child.on('error', (error) => finish({ error: `could not start \`${command}\` (${error.message})` }));
+    child.on('exit', (code) => {
+      if (!settled) finish({ error: `the server exited with code ${code} before answering` });
+    });
+    // stderr is not this client's to interpret, but it has to be read: an unread pipe fills
+    // and a server blocked on its own diagnostics never reaches the answer.
+    child.stderr.on('data', () => {});
+    child.stdin.on('error', () => {});
+
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk.toString('utf8');
+      let index = buffer.indexOf('\n');
+      while (index !== -1) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (line.length > 0) {
+          let message;
+          try {
+            message = JSON.parse(line);
+          } catch {
+            message = null;
+          }
+          const id = message !== null && typeof message === 'object' ? message.id : undefined;
+          const waiter = id !== undefined ? pending.get(id) : undefined;
+          if (waiter !== undefined) {
+            pending.delete(id);
+            waiter(message);
+          }
+        }
+        index = buffer.indexOf('\n');
+      }
+    });
+
+    const request = (method, params) =>
+      new Promise((done) => {
+        const id = nextId;
+        nextId += 1;
+        pending.set(id, done);
+        try {
+          child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+        } catch (error) {
+          pending.delete(id);
+          finish({ error: `could not talk to \`${command}\` (${error.message})` });
+        }
+      });
+
+    const notify = (method, params) => {
+      try {
+        child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method, params })}\n`);
+      } catch {
+        // A notification that cannot be written is a server that is already gone, and the
+        // exit handler reports that with a better sentence than this one could.
+      }
+    };
+
+    (async () => {
+      await request('initialize', {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: CLIENT_INFO,
+      });
+      notify('notifications/initialized', {});
+      const answer = await request('tools/call', { name: tool, arguments: { [argument]: query } });
+      if (answer.error !== undefined) {
+        finish({ error: reasonOf(answer.error) });
+        return;
+      }
+      const text = textOf(answer.result);
+      if (text === null) {
+        finish({ error: `\`${tool}\` returned no text` });
+        return;
+      }
+      finish({ text });
+    })().catch((error) => finish({ error: error.message }));
+  });
+}

package/src/federation/config.mjs

@@ -0,0 +1,134 @@
+// Federation configuration: the servers a repository names, and nothing else (plan 0003 R26).
+//
+// A brief is deterministic by default. Federation is the one opt-in exception, and the
+// opt-in is a `federation` block in the repository's own manifest. Nothing here probes a
+// harness config, scans for a server that might exist, or opens a socket the manifest did
+// not ask for — a repository that declared nothing pays nothing and reads nothing. Where
+// a harness would keep the same names is R42's several slices away, and it is a different
+// question: this one is "what did the repository commit", not "what did the editor
+// configure".
+//
+// The trust model is the one `gates.commands` already has. Those are commands a repository
+// declares and this tool runs; a federation server is the same declaration one layer up.
+// The manifest is the file a person reviews before they commit the change, so a command in
+// it is a command the repository meant to run.
+//
+// The block is deliberately small, because every field in it is a promise the packet has
+// to keep:
+//
+//   "federation": {
+//     "servers": [
+//       {
+//         "name": "serena",                  // required, unique; the name the packet cites
+//         "command": "uvx",                  // required; started with stdio pipes
+//         "args": ["serena", "start-mcp-server"],
+//         "tool": "find_symbol",             // optional; the MCP tool to call, default "query"
+//         "argument": "query",               // optional; where the question goes, default "query"
+//         "languages": ["python"],           // optional; the coverage the packet records
+//         "timeoutMs": 4000                  // optional; the wait, default 5000
+//       }
+//     ]
+//   }
+//
+// An entry that breaks the shape is not a crash and not a silent skip. It becomes a finding
+// with a sentence in it, the brief turns that into a caution, and every other entry still
+// runs. A malformed block costs the reader one line, which is exactly what they need to fix
+// it — and a silent skip is the failure that line exists to prevent.
+
+import { readManifest } from '../projection/manifest.mjs';
+import { DEFAULT_TIMEOUT_MS } from './client.mjs';
+
+/** The tool a server is asked for when it does not name one. */
+const DEFAULT_TOOL = 'query';
+
+/** The argument the question is placed in when a server does not name one. */
+const DEFAULT_ARGUMENT = 'query';
+
+/** A list of strings, or null when the value is anything else. */
+function strings(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string') ? [...value] : null;
+}
+
+/** A non-empty trimmed string, or the empty string. */
+function word(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/** One declared server, or the sentence explaining why it is not one. */
+function serverOf(entry, seen) {
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+    return { finding: 'a federation server must be an object' };
+  }
+  const name = word(entry.name);
+  if (name.length === 0) return { finding: 'a federation server needs a `name`' };
+  // The name is claimed before the rest is checked, so a rejected entry still reserves it:
+  // two entries called `serena` are a mistake whether or not the first one is also
+  // malformed, and a duplicate that only surfaced once both were valid would be the harder
+  // mistake to see.
+  if (seen.has(name)) return { finding: `two federation servers are named \`${name}\`` };
+  seen.add(name);
+
+  const command = word(entry.command);
+  if (command.length === 0) return { finding: `the \`${name}\` server needs a \`command\`` };
+
+  const args = entry.args === undefined ? [] : strings(entry.args);
+  if (args === null) return { finding: `the \`${name}\` server's \`args\` must be a list of strings` };
+  const languages = entry.languages === undefined ? [] : strings(entry.languages);
+  if (languages === null) return { finding: `the \`${name}\` server's \`languages\` must be a list of strings` };
+
+  const tool = entry.tool === undefined ? DEFAULT_TOOL : word(entry.tool);
+  if (tool.length === 0) return { finding: `the \`${name}\` server's \`tool\` must be a tool name` };
+  const argument = entry.argument === undefined ? DEFAULT_ARGUMENT : word(entry.argument);
+  if (argument.length === 0) return { finding: `the \`${name}\` server's \`argument\` must be an argument name` };
+
+  const timeoutMs = entry.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : entry.timeoutMs;
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    return { finding: `the \`${name}\` server's \`timeoutMs\` must be a positive whole number` };
+  }
+
+  return { server: { name, command, args, tool, argument, languages, timeoutMs } };
+}
+
+/**
+ * The servers a manifest declares, and the reason each rejected one was rejected.
+ *
+ * Pure: the manifest comes in, the decision comes out, and the same manifest always gives
+ * the same two lists. The order is the manifest's, because a packet's items are ordered and
+ * a federation answer is a packet item.
+ */
+export function federationServers(manifest) {
+  const block = manifest?.federation;
+  if (block === undefined || block === null) return { servers: [], findings: [] };
+  if (typeof block !== 'object' || Array.isArray(block)) {
+    return { servers: [], findings: ['`federation` must be an object'] };
+  }
+  const declared = block.servers;
+  if (declared === undefined || declared === null) return { servers: [], findings: [] };
+  if (!Array.isArray(declared)) return { servers: [], findings: ['`federation.servers` must be a list'] };
+
+  const servers = [];
+  const findings = [];
+  const seen = new Set();
+  for (const entry of declared) {
+    const parsed = serverOf(entry, seen);
+    if (parsed.finding !== undefined) {
+      findings.push(parsed.finding);
+      continue;
+    }
+    servers.push(parsed.server);
+  }
+  return { servers, findings };
+}
+
+/**
+ * The same two lists, read from the repository's manifest.
+ *
+ * A repository with no manifest, an unreadable one or none at all declares no servers and
+ * reports no finding: federation is silent unless it was asked for, and "you did not
+ * configure this" is not a fault a reader needs told.
+ */
+export async function readFederation(root) {
+  const { manifest, exists, error } = await readManifest(root);
+  if (!exists || error !== null || manifest === null) return { servers: [], findings: [] };
+  return federationServers(manifest);
+}

package/src/federation/query.mjs

@@ -0,0 +1,48 @@
+// The federation query: one structural question per task, one answer per server (0003 R26).
+//
+// The slice is narrow on purpose. When a repository names external code-graph servers, the
+// brief delegates a single structural question to each and cites where the answer came from,
+// and the `federation_query` tool asks one on demand. Neither is a general proxy: a question
+// goes to the tool and argument the manifest declared, so a server exposes no tool here that
+// the repository did not name. It is not a second index, so there is no coverage bookkeeping
+// to keep in sync. And it is not a gate, so a server that is down produces a sentence and
+// never a failure.
+//
+// The servers are asked in the order the manifest declares them, one at a time. Parallel
+// would be faster and would make the packet's item order a race, and a packet whose order
+// depends on which server answered first is the one property this whole module exists
+// beside.
+
+import { callTool } from './client.mjs';
+
+/**
+ * Ask each declared server the same question.
+ *
+ * @param {object} request
+ * @param {string} request.root the repository the servers are started in
+ * @param {string} request.query the structural question, already non-empty
+ * @param {object[]} request.servers the servers `readFederation` returned
+ * @returns `{ answers, findings }` — one `{ server, tool, query, text }` per server that
+ *   answered, one sentence per server that did not
+ */
+export async function consult({ root, query, servers }) {
+  const answers = [];
+  const findings = [];
+  for (const server of servers) {
+    const result = await callTool({
+      command: server.command,
+      args: server.args,
+      cwd: root,
+      tool: server.tool,
+      argument: server.argument,
+      query,
+      timeoutMs: server.timeoutMs,
+    });
+    if (result.error !== undefined) {
+      findings.push(`the \`${server.name}\` server did not answer (${result.error})`);
+      continue;
+    }
+    answers.push({ server: server.name, tool: server.tool, query, text: result.text });
+  }
+  return { answers, findings };
+}