staysfixed 0.3.0 → 0.4.0

package/src/v2/mcp/server.js

@@ -0,0 +1,374 @@
+/**
+ * Stays Fixed v2 over the Model Context Protocol, hand-rolled.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ *  STDOUT IS THE PROTOCOL. Nothing but JSON-RPC messages may EVER be written
+ *  to it — one compact JSON object per line, newline-terminated. A single
+ *  stray `console.log` anywhere in the process, in this tool or in a project's
+ *  own code that we imported, corrupts the stream and the client's parser dies
+ *  with an error that points nowhere near the real cause. Every human-readable
+ *  word goes to stderr. `serveMcp` enforces this by swapping
+ *  `process.stdout.write` for a diverter and keeping the real one to itself;
+ *  do not undo that.
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ * What changed from v1's server: almost nothing, on purpose. The transport was
+ * the one part of v1 that was already right — a hundred lines, no dependency,
+ * and it has never been the thing that broke. What changed is what it says on
+ * connect, and that it hands every tool the protocol revision it negotiated so
+ * a tool can decide whether the client will understand structured output.
+ *
+ * The server also starts, lists its tools and answers `staysfixed_capabilities`
+ * when the difference engine is half-built or the project is not set up at all.
+ * That is deliberate: capabilities is the call an agent makes to find out what
+ * is wrong, so it is the one call that must never be the thing that is wrong.
+ */
+
+import { StringDecoder } from 'node:string_decoder';
+import path from 'node:path';
+
+import { isExpected, messageOf } from '../../core/errors.js';
+import { toolDefinitions, callTool, findRoot } from './tools.js';
+
+/** Protocol revisions this server understands. Newest first. */
+const SUPPORTED_PROTOCOLS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const LATEST_PROTOCOL = SUPPORTED_PROTOCOLS[0];
+
+/** JSON-RPC 2.0 error codes, plus the ones MCP leans on. */
+const RPC = {
+  parseError: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internalError: -32603,
+};
+
+/**
+ * A line this long without a newline is a stream that has gone wrong, not a
+ * message. Incoming requests are small; only our replies ever carry evidence.
+ */
+const MAX_LINE_BYTES = 64 * 1024 * 1024;
+
+/** How long we wait for a check that is mid-flight when the client hangs up. */
+const SHUTDOWN_GRACE_MS = 10_000;
+
+/**
+ * What the server tells the agent the moment it connects. This is the shortest
+ * useful description of the loop, and it names the first call, because an agent
+ * that starts with `staysfixed_check` on an unconfigured project learns nothing
+ * and spends a minute finding that out.
+ */
+const INSTRUCTIONS = [
+  'Stays Fixed proves that nothing which already worked has changed.',
+  '',
+  'The loop: seal what you MEANT to change with staysfixed_intent, do the work, then call',
+  'staysfixed_check. You get back only the differences you did not intend — everything unchanged is',
+  'skipped and never reaches you, and the count of what was skipped is in the reply so the silence is',
+  'legible. Read the findings, fix the ones you caused, and check again.',
+  '',
+  'Call staysfixed_capabilities FIRST, once per session. It tells you what can be checked on this',
+  'machine right now, what cannot and why, what is missing that would unlock more, and the exact shape',
+  'of every reply. You should not need to read any documentation after that call.',
+  '',
+  'You cannot decide that a difference is acceptable. You can only record that one was intended, with',
+  'staysfixed_waive, and five classes are sealed off from you entirely: money, signing in, losing data,',
+  'a crash, and anything a named guard covers. Those go to a person.',
+].join('\n');
+
+/**
+ * Serve Stays Fixed v2 on stdin/stdout until the client goes away.
+ *
+ * @param {{cwd?: string, root?: string, version?: string}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function serveMcp(opts = {}) {
+  const cwd = path.resolve(opts.cwd ?? process.cwd());
+  // An editor usually starts an MCP server in the folder it was opened in, which
+  // is often a subfolder of the project. Walking up to the real root here means
+  // an agent never has to know or say where the project starts.
+  const root = opts.root ? path.resolve(opts.root) : findRoot(cwd);
+  const version = opts.version ?? '0.0.0';
+
+  const writeToClient = process.stdout.write.bind(process.stdout);
+  const realStdoutWrite = process.stdout.write;
+  /** @type {any} */ (process.stdout).write = divertToStderr;
+
+  /** The revision we settled on with this client. Tools ask before shaping output. */
+  let protocolVersion = LATEST_PROTOCOL;
+
+  /**
+   * One JSON-RPC message out. The ONLY function allowed to touch real stdout.
+   * @param {Record<string, any>} message
+   */
+  function send(message) {
+    try {
+      writeToClient(JSON.stringify(message) + '\n');
+    } catch (e) {
+      // The client hung up mid-answer. There is nowhere left to report it but here.
+      log(`could not write a reply: ${messageOf(e)}`);
+    }
+  }
+
+  /**
+   * @param {string|number} id
+   * @param {any} result
+   */
+  function reply(id, result) {
+    send({ jsonrpc: '2.0', id, result });
+  }
+
+  /**
+   * @param {string|number|null} id
+   * @param {number} code
+   * @param {string} message
+   */
+  function replyError(id, code, message) {
+    send({ jsonrpc: '2.0', id, error: { code, message } });
+  }
+
+  /** @param {string} line */
+  function log(line) {
+    process.stderr.write(`[staysfixed] ${line}\n`);
+  }
+
+  // Tool calls run one at a time. Two at once would mean two copies of the app
+  // fighting over ports, locks and data dirs — which is the exact failure this
+  // whole design rejects in its third principle. The queue is not optional.
+  /** @type {Promise<void>} */
+  let queue = Promise.resolve();
+  /** @type {Set<Promise<void>>} */
+  const inFlight = new Set();
+
+  /**
+   * @param {() => Promise<void>} job
+   * @returns {Promise<void>}
+   */
+  function enqueue(job) {
+    const run = queue.then(job);
+    const settled = run.then(
+      () => {},
+      () => {}
+    );
+    queue = settled;
+    inFlight.add(settled);
+    settled.then(() => inFlight.delete(settled));
+    return run;
+  }
+
+  /** @param {any} msg */
+  async function handle(msg) {
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) {
+      replyError(null, RPC.invalidRequest, 'Each line must be one JSON-RPC request object. Batched arrays are not supported.');
+      return;
+    }
+
+    const method = typeof msg.method === 'string' ? msg.method : null;
+    // No `id` member means a notification, and a notification never gets an
+    // answer — replying to one is the classic way to wedge a strict client.
+    const isNotification = !('id' in msg);
+    const id = /** @type {string|number} */ (msg.id);
+
+    if (!method) {
+      if (!isNotification) replyError(id, RPC.invalidRequest, 'That message has no method name.');
+      return;
+    }
+
+    if (isNotification) {
+      if (method === 'notifications/cancelled') log('client cancelled a request');
+      return;
+    }
+
+    switch (method) {
+      case 'initialize': {
+        const asked = msg.params?.protocolVersion;
+        const client = msg.params?.clientInfo?.name;
+        // Speak the client's revision when we know it; otherwise answer with ours
+        // and let it decide whether it can live with that.
+        protocolVersion = typeof asked === 'string' && SUPPORTED_PROTOCOLS.includes(asked) ? asked : LATEST_PROTOCOL;
+        reply(id, {
+          protocolVersion,
+          capabilities: { tools: {} },
+          serverInfo: { name: 'staysfixed', version },
+          instructions: INSTRUCTIONS,
+        });
+        log(`connected${client ? ` to ${client}` : ''} — speaking ${protocolVersion}`);
+        return;
+      }
+
+      case 'ping':
+        reply(id, {});
+        return;
+
+      case 'tools/list':
+        // Static, and it never touches disk. An agent listing tools on a project
+        // that is not set up yet must still see `staysfixed_capabilities`, which
+        // is the tool that explains why nothing else will work.
+        reply(id, { tools: toolDefinitions() });
+        return;
+
+      case 'tools/call': {
+        const name = msg.params?.name;
+        if (typeof name !== 'string' || name === '') {
+          replyError(id, RPC.invalidParams, 'A tools/call needs the name of the tool to run.');
+          return;
+        }
+        const args = msg.params?.arguments ?? {};
+        if (Array.isArray(args)) {
+          replyError(id, RPC.invalidParams, 'Tool arguments must be an object, not a list.');
+          return;
+        }
+        await enqueue(async () => {
+          try {
+            const result = await callTool(name, args, { root, cwd, version, protocolVersion });
+            reply(id, result);
+          } catch (e) {
+            // A tool that blows up is still a RESULT, not a protocol error: the
+            // agent is meant to read what went wrong and act on it, and a
+            // protocol error is swallowed by its client before it sees the words.
+            reply(id, {
+              content: [{ type: 'text', text: isExpected(e) ? messageOf(e) : `Stays Fixed could not finish that: ${messageOf(e)}` }],
+              isError: true,
+            });
+          }
+        });
+        return;
+      }
+
+      default:
+        replyError(id, RPC.methodNotFound, `This server does not handle "${method}".`);
+    }
+  }
+
+  // ── the stdio loop ────────────────────────────────────────────────────────
+
+  const decoder = new StringDecoder('utf8');
+  let buffer = '';
+  let overlong = false;
+
+  /** @type {() => void} */
+  let finish = () => {};
+  /** @type {Promise<void>} */
+  const done = new Promise((resolve) => {
+    finish = resolve;
+  });
+
+  let closing = false;
+
+  /** @param {string} why */
+  async function shutdown(why) {
+    if (closing) return;
+    closing = true;
+    log(`shutting down (${why})`);
+    // Wait for whatever is mid-flight so anything it opened gets closed properly.
+    // Past the grace period we stop waiting; a hung app must not hold the editor.
+    if (inFlight.size > 0) {
+      /** @type {NodeJS.Timeout|undefined} */
+      let timer;
+      const grace = new Promise((resolve) => {
+        timer = setTimeout(resolve, SHUTDOWN_GRACE_MS);
+      });
+      await Promise.race([Promise.all([...inFlight]), grace]);
+      if (timer) clearTimeout(timer);
+    }
+    /** @type {any} */ (process.stdout).write = realStdoutWrite;
+    finish();
+  }
+
+  /** @param {string} line */
+  function onLine(line) {
+    const trimmed = line.endsWith('\r') ? line.slice(0, -1) : line;
+    if (trimmed.trim() === '') return;
+    /** @type {any} */
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      replyError(null, RPC.parseError, 'That line was not valid JSON. Each message must be one JSON object on one line.');
+      return;
+    }
+    // Handling is async; a throw escaping it would take the server down, so it is
+    // caught here and reported as an internal error against that one message.
+    Promise.resolve()
+      .then(() => handle(msg))
+      .catch((e) => {
+        const id = msg && typeof msg === 'object' && 'id' in msg ? msg.id : null;
+        log(`internal error: ${messageOf(e)}`);
+        if (id !== null && id !== undefined) replyError(id, RPC.internalError, `Something went wrong inside Stays Fixed: ${messageOf(e)}`);
+      });
+  }
+
+  process.stdin.on('data', (chunk) => {
+    buffer += decoder.write(/** @type {Buffer} */ (chunk));
+
+    for (;;) {
+      const nl = buffer.indexOf('\n');
+      if (nl === -1) break;
+      const line = buffer.slice(0, nl);
+      buffer = buffer.slice(nl + 1);
+      if (overlong) {
+        // We already gave up on this message; the newline ends it.
+        overlong = false;
+        continue;
+      }
+      onLine(line);
+    }
+
+    // A line that never ends is a broken stream, not a big request. Drop what we
+    // are holding rather than growing until the process runs out of memory.
+    if (!overlong && buffer.length > MAX_LINE_BYTES) {
+      overlong = true;
+      buffer = '';
+      replyError(null, RPC.parseError, 'That message was too long to read. Each message must be one JSON object on one line.');
+    }
+  });
+
+  process.stdin.on('error', (e) => {
+    log(`stdin error: ${messageOf(e)}`);
+    void shutdown('stdin error');
+  });
+  process.stdin.on('end', () => void shutdown('the client closed the connection'));
+  process.stdin.on('close', () => void shutdown('the client closed the connection'));
+
+  /** @type {(() => void)[]} */
+  const signalHandlers = [];
+  for (const signal of /** @type {NodeJS.Signals[]} */ (['SIGINT', 'SIGTERM'])) {
+    const onSignal = () => void shutdown(signal);
+    process.on(signal, onSignal);
+    signalHandlers.push(() => process.removeListener(signal, onSignal));
+  }
+
+  process.stdin.resume();
+  log(`Stays Fixed ${version} ready — talking MCP on stdin and stdout, saying everything else here.`);
+
+  await done;
+  for (const off of signalHandlers) off();
+  process.stdin.pause();
+}
+
+/**
+ * Anything that tries to print to stdout gets pushed to stderr instead.
+ * @param {any} chunk
+ * @param {any} [encoding]
+ * @param {any} [callback]
+ * @returns {boolean}
+ */
+function divertToStderr(chunk, encoding, callback) {
+  return process.stderr.write(chunk, encoding, callback);
+}
+
+/**
+ * The block a person pastes into their editor's MCP settings.
+ *
+ * Written once, here, so `init`, the README and the capabilities reply cannot
+ * drift apart — and quoted verbatim by `staysfixed_capabilities`, which is the
+ * point: the agent installing this reads the exact block, not a description of it.
+ *
+ * @param {{command: string, args?: string[], cwd?: string}} opts
+ * @returns {string}
+ */
+export function mcpConfigSnippet({ command, args = [], cwd }) {
+  /** @type {Record<string, any>} */
+  const server = { command, args };
+  if (cwd) server.cwd = cwd;
+  return JSON.stringify({ mcpServers: { staysfixed: server } }, null, 2);
+}