pennyrouter 0.3.0 → 0.3.2

package/src/mcp-register.js

@@ -0,0 +1,212 @@
+/* Register the Threads MCP server with the harnesses that can run it.
+
+   Without this, `pennyrouter install` gives a user routing and nothing else: the MCP server
+   exists as a command they would have to discover and register by hand, which almost nobody
+   does. Registration is what makes thread_read/thread_resume simply be there.
+
+   Two harnesses, two config files, neither of them the one the installer already manages:
+
+     Claude Code  ~/.claude.json          -> mcpServers.pennyrouter   (JSON)
+     Codex        ~/.codex/config.toml    -> [mcp_servers.pennyrouter] (TOML)
+
+   NOTE the file for Claude Code. Its MCP registry is `~/.claude.json`, NOT the
+   `~/.claude/settings.json` that harnesses/claude-code.js writes — different file, different
+   shape. Writing the entry into settings.json looks right and does nothing.
+
+   The command is `npx -y pennyrouter mcp`, deliberately unpinned. An absolute path to the
+   current bin breaks the moment the user switches node versions or reinstalls, and the server
+   then silently stops appearing rather than failing loudly. A pinned version would freeze the
+   session writers, which is wrong for a feature whose whole risk is that Claude Code and Codex
+   change their undocumented formats — the writers need to be updatable. */
+
+import { atomicWrite, backupFile, exists, expandHome, readJsonFile } from "./state.js";
+import { readFile } from "node:fs/promises";
+
+export const SERVER_NAME = "pennyrouter";
+const CLAUDE_REGISTRY = "~/.claude.json";
+const CODEX_CONFIG = "~/.codex/config.toml";
+
+const MANAGED_START = "# --- PennyRouter managed MCP server ---";
+const MANAGED_END = "# --- end PennyRouter managed MCP server ---";
+
+/** What we register. Shared by both harnesses so the two configs cannot drift apart.
+
+    `gatewayBaseUrl` is pinned into the entry only when the install targeted a non-default
+    gateway. The MCP server is spawned later by the harness, in a process that shares nothing
+    with the install run, so a base URL chosen at install time reaches it only by being written
+    here. Omitted when unset, which keeps default installs byte-identical to earlier versions. */
+export function serverEntry(harness = "claude-code", gatewayBaseUrl = "") {
+  const url = String(gatewayBaseUrl || "").trim();
+  return {
+    command: "npx",
+    args: ["-y", "pennyrouter", "mcp"],
+    env: {
+      PENNYROUTER_MCP_HARNESS: harness,
+      ...(url ? { PENNYROUTER_GATEWAY_BASE_URL: url } : {}),
+    },
+  };
+}
+
+/** True when an entry is one of ours, so re-installing updates rather than duplicating and
+    uninstalling never removes a server the user registered themselves. */
+export function isManagedEntry(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  const args = Array.isArray(entry.args) ? entry.args.join(" ") : "";
+  return /\bpennyrouter\b/.test(`${entry.command || ""} ${args}`);
+}
+
+// -- Claude Code ----------------------------------------------------------
+
+export function applyClaudeRegistry(config, { remove = false, gatewayBaseUrl = "" } = {}) {
+  const next = { ...(config || {}) };
+  const servers = { ...(next.mcpServers || {}) };
+
+  if (remove) {
+    // Only remove what we wrote. A user who pointed the name at their own build keeps it.
+    if (isManagedEntry(servers[SERVER_NAME])) delete servers[SERVER_NAME];
+  } else {
+    const existing = servers[SERVER_NAME];
+    if (existing && !isManagedEntry(existing)) {
+      throw new Error(
+        `Claude Code already has an MCP server named "${SERVER_NAME}" that PennyRouter did not ` +
+          "write. Rename it before installing so your configuration is not overwritten.",
+      );
+    }
+    servers[SERVER_NAME] = serverEntry("claude-code", gatewayBaseUrl);
+  }
+
+  if (Object.keys(servers).length) next.mcpServers = servers;
+  else delete next.mcpServers;
+  return next;
+}
+
+async function writeClaude({ remove, gatewayBaseUrl }) {
+  if (!(await exists(CLAUDE_REGISTRY))) {
+    // Claude Code writes this on first run. Creating it ourselves risks clobbering a shape we
+    // do not own, so skip rather than guess.
+    return { changed: false, reason: "Claude Code config not found" };
+  }
+  const current = (await readJsonFile(CLAUDE_REGISTRY, null)) || {};
+  const next = applyClaudeRegistry(current, { remove, gatewayBaseUrl });
+  if (JSON.stringify(next) === JSON.stringify(current)) return { changed: false };
+
+  await backupFile(CLAUDE_REGISTRY, "mcp");
+  await atomicWrite(CLAUDE_REGISTRY, `${JSON.stringify(next, null, 2)}\n`);
+  return { changed: true, path: expandHome(CLAUDE_REGISTRY) };
+}
+
+// -- Codex ----------------------------------------------------------------
+
+export function renderCodexMcp(text, { remove = false, gatewayBaseUrl = "" } = {}) {
+  const clean = removeManagedCodexMcp(text).trimEnd();
+  if (remove) return clean ? `${clean}\n` : "";
+
+  const pattern = new RegExp(`^\\s*\\[mcp_servers\\.${SERVER_NAME}\\]\\s*$`, "m");
+  if (pattern.test(clean)) {
+    throw new Error(
+      `Codex already defines [mcp_servers.${SERVER_NAME}] outside PennyRouter's managed block. ` +
+        "Rename that server before installing so PennyRouter does not overwrite it.",
+    );
+  }
+
+  const entry = serverEntry("codex", gatewayBaseUrl);
+  // Rendered from entry.env rather than a fixed line, so a key added to serverEntry reaches both
+  // harnesses instead of silently appearing only in Claude Code's JSON.
+  const env = Object.entries(entry.env)
+    .map(([key, value]) => `${key} = "${value}"`)
+    .join(", ");
+  const block = [
+    MANAGED_START,
+    `[mcp_servers.${SERVER_NAME}]`,
+    `command = "${entry.command}"`,
+    `args = [${entry.args.map((a) => `"${a}"`).join(", ")}]`,
+    `env = { ${env} }`,
+    MANAGED_END,
+  ].join("\n");
+
+  // Appended rather than spliced at the first table: a TOML table header captures every key
+  // that follows it, so inserting this block above existing tables would silently reparent
+  // their keys into ours.
+  return `${clean ? `${clean}\n\n` : ""}${block}\n`;
+}
+
+export function removeManagedCodexMcp(text) {
+  return String(text || "").replace(
+    new RegExp(
+      `${escapeRegex(MANAGED_START)}[\\s\\S]*?${escapeRegex(MANAGED_END)}\\n?`,
+      "g",
+    ),
+    "",
+  );
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+async function writeCodex({ remove, gatewayBaseUrl }) {
+  if (!(await exists(CODEX_CONFIG))) return { changed: false, reason: "Codex config not found" };
+  const current = await readFile(expandHome(CODEX_CONFIG), "utf8").catch(() => "");
+  const next = renderCodexMcp(current, { remove, gatewayBaseUrl });
+  if (next === current) return { changed: false };
+
+  await backupFile(CODEX_CONFIG, "mcp");
+  await atomicWrite(CODEX_CONFIG, next);
+  return { changed: true, path: expandHome(CODEX_CONFIG) };
+}
+
+// -- entry points ---------------------------------------------------------
+
+const WRITERS = { "claude-code": writeClaude, codex: writeCodex };
+
+/** Whether each harness currently has our server registered, and whether it could. */
+export async function mcpStatus(harnessIds = Object.keys(WRITERS)) {
+  const out = [];
+  for (const id of harnessIds) {
+    if (id === "claude-code") {
+      const present = await exists(CLAUDE_REGISTRY);
+      const config = present ? (await readJsonFile(CLAUDE_REGISTRY, null)) || {} : {};
+      out.push({
+        harness: id,
+        configFound: present,
+        registered: isManagedEntry((config.mcpServers || {})[SERVER_NAME]),
+        conflict: Boolean(
+          (config.mcpServers || {})[SERVER_NAME] &&
+            !isManagedEntry((config.mcpServers || {})[SERVER_NAME]),
+        ),
+      });
+    } else if (id === "codex") {
+      const present = await exists(CODEX_CONFIG);
+      const text = present ? await readFile(expandHome(CODEX_CONFIG), "utf8").catch(() => "") : "";
+      const managed = text.includes(MANAGED_START);
+      out.push({
+        harness: id,
+        configFound: present,
+        registered: managed,
+        conflict:
+          !managed && new RegExp(`^\\s*\\[mcp_servers\\.${SERVER_NAME}\\]`, "m").test(text),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Register (or with `remove`, unregister) the MCP server for `harnessIds`.
+ * Returns one result per harness; a harness whose config is absent is skipped, not an error.
+ */
+export async function registerMcp(harnessIds, { remove = false, gatewayBaseUrl = "" } = {}) {
+  const results = [];
+  for (const id of harnessIds) {
+    const writer = WRITERS[id];
+    if (!writer) continue;
+    try {
+      results.push({ harness: id, ...(await writer({ remove, gatewayBaseUrl })) });
+    } catch (error) {
+      // A conflict must not fail the whole install: routing is the primary job and is already
+      // done by this point. Report it and let the user resolve the name.
+      results.push({ harness: id, changed: false, error: error?.message || String(error) });
+    }
+  }
+  return results;
+}

package/src/mcp-register.test.js

@@ -0,0 +1,200 @@
+import assert from "node:assert/strict";
+
+import {
+  SERVER_NAME,
+  applyClaudeRegistry,
+  isManagedEntry,
+  removeManagedCodexMcp,
+  renderCodexMcp,
+  serverEntry,
+} from "./mcp-register.js";
+
+// -- what gets written ----------------------------------------------------
+// Unpinned on purpose: an absolute path breaks on a node/nvm switch and the server then stops
+// appearing silently, and a pinned version would freeze the session writers — wrong for a
+// feature whose risk is that the harnesses change their undocumented formats.
+{
+  const entry = serverEntry();
+  assert.equal(entry.command, "npx");
+  assert.deepEqual(entry.args, ["-y", "pennyrouter", "mcp"]);
+  assert.equal(entry.env.PENNYROUTER_MCP_HARNESS, "claude-code");
+  assert.ok(!JSON.stringify(entry).includes("/"), "no absolute paths");
+  assert.ok(!/pennyrouter@/.test(JSON.stringify(entry)), "not version-pinned");
+  assert.ok(!("PENNYROUTER_GATEWAY_BASE_URL" in entry.env), "no URL pinned by default");
+}
+
+// A non-default gateway must be pinned into the entry. The MCP server is spawned later by the
+// harness, in a process that never sees the install run's flags, so `--local` reaches it only
+// through the written config. Regression: `--local` used to set the URL for the install process
+// alone, leaving the registered server pointed at production and every transfer failing there.
+{
+  const local = serverEntry("claude-code", "http://localhost:8400");
+  assert.equal(local.env.PENNYROUTER_GATEWAY_BASE_URL, "http://localhost:8400");
+  assert.equal(local.env.PENNYROUTER_MCP_HARNESS, "claude-code");
+
+  // Both harnesses carry it, or the two configs drift apart.
+  const toml = renderCodexMcp("", { gatewayBaseUrl: "http://localhost:8400" });
+  assert.match(toml, /PENNYROUTER_MCP_HARNESS = "codex"/);
+  assert.match(toml, /PENNYROUTER_GATEWAY_BASE_URL = "http:\/\/localhost:8400"/);
+
+  // Default installs stay byte-identical, so existing entries are not rewritten on update.
+  assert.equal(renderCodexMcp(""), renderCodexMcp("", { gatewayBaseUrl: "" }));
+  assert.ok(!renderCodexMcp("").includes("PENNYROUTER_GATEWAY_BASE_URL"));
+
+  const claude = applyClaudeRegistry({}, { gatewayBaseUrl: "http://localhost:8400" });
+  assert.equal(
+    claude.mcpServers[SERVER_NAME].env.PENNYROUTER_GATEWAY_BASE_URL,
+    "http://localhost:8400",
+  );
+  assert.ok(isManagedEntry(claude.mcpServers[SERVER_NAME]), "still ours after pinning a URL");
+}
+
+// -- Claude Code registry -------------------------------------------------
+{
+  // Registering into an empty config.
+  const fresh = applyClaudeRegistry({});
+  assert.deepEqual(fresh.mcpServers[SERVER_NAME], serverEntry());
+
+  // Existing unrelated servers are preserved.
+  const withOthers = applyClaudeRegistry({
+    mcpServers: { railway: { command: "railway" } },
+    projects: { "/x": {} },
+  });
+  assert.ok(withOthers.mcpServers.railway, "other servers survive");
+  assert.ok(withOthers.projects, "unrelated top-level keys survive");
+
+  // Re-installing updates in place rather than duplicating.
+  const twice = applyClaudeRegistry(applyClaudeRegistry({}));
+  assert.equal(Object.keys(twice.mcpServers).length, 1);
+
+  // A same-named server we did not write is a hard stop, not a silent overwrite.
+  assert.throws(
+    () => applyClaudeRegistry({ mcpServers: { [SERVER_NAME]: { command: "/my/own/build" } } }),
+    /did not write/,
+  );
+
+  // Removal takes ours and leaves everything else.
+  const removed = applyClaudeRegistry(
+    { mcpServers: { railway: { command: "railway" }, [SERVER_NAME]: serverEntry() } },
+    { remove: true },
+  );
+  assert.ok(!removed.mcpServers[SERVER_NAME]);
+  assert.ok(removed.mcpServers.railway);
+
+  // A user who re-pointed the name at their own build keeps it through an uninstall.
+  const custom = { mcpServers: { [SERVER_NAME]: { command: "/my/own/build" } } };
+  assert.deepEqual(applyClaudeRegistry(custom, { remove: true }), custom);
+
+  // Removing the last server drops the key entirely rather than leaving `{}`.
+  const emptied = applyClaudeRegistry(
+    { mcpServers: { [SERVER_NAME]: serverEntry() } },
+    { remove: true },
+  );
+  assert.ok(!("mcpServers" in emptied));
+}
+
+// -- managed-entry detection ----------------------------------------------
+assert.equal(isManagedEntry(serverEntry()), true);
+assert.equal(isManagedEntry({ command: "npx", args: ["-y", "pennyrouter@1.2.3", "mcp"] }), true);
+assert.equal(isManagedEntry({ command: "/my/own/build" }), false);
+assert.equal(isManagedEntry(null), false);
+assert.equal(isManagedEntry({}), false);
+
+// -- Codex TOML -----------------------------------------------------------
+{
+  const existing = [
+    'model_provider = "pennyrouter"',
+    "",
+    "[mcp_servers.node_repl]",
+    'command = "/Applications/Codex.app/node_repl"',
+  ].join("\n");
+
+  const written = renderCodexMcp(existing);
+  assert.ok(written.includes(`[mcp_servers.${SERVER_NAME}]`));
+  assert.ok(written.includes('command = "npx"'));
+  assert.ok(written.includes('args = ["-y", "pennyrouter", "mcp"]'));
+  assert.ok(written.includes('PENNYROUTER_MCP_HARNESS = "codex"'));
+  assert.ok(written.includes("[mcp_servers.node_repl]"), "existing servers survive");
+
+  // A TOML table header captures every key after it, so our block must be appended — splicing
+  // it above an existing table would reparent that table's keys into ours.
+  const ourIndex = written.indexOf(`[mcp_servers.${SERVER_NAME}]`);
+  assert.ok(ourIndex > written.indexOf("[mcp_servers.node_repl]"), "appended, not spliced");
+  assert.ok(
+    written.indexOf('model_provider = "pennyrouter"') < written.indexOf("[mcp_servers."),
+    "root keys stay above every table",
+  );
+
+  // Re-installing is idempotent: the managed block is replaced, not stacked.
+  const again = renderCodexMcp(written);
+  assert.equal(again.match(new RegExp(`\\[mcp_servers\\.${SERVER_NAME}\\]`, "g")).length, 1);
+
+  // Removal restores the original.
+  assert.equal(renderCodexMcp(written, { remove: true }).trim(), existing.trim());
+  assert.equal(removeManagedCodexMcp(written).trim(), existing.trim());
+
+  // An unmanaged server of the same name is a hard stop.
+  assert.throws(
+    () => renderCodexMcp(`[mcp_servers.${SERVER_NAME}]\ncommand = "mine"`),
+    /outside PennyRouter's managed block/,
+  );
+
+  // Empty config in, valid config out.
+  assert.ok(renderCodexMcp("").includes(`[mcp_servers.${SERVER_NAME}]`));
+  assert.equal(renderCodexMcp("", { remove: true }), "");
+}
+
+// -- status reporting -----------------------------------------------------
+// `mcp status` is how someone finds out they are in the state install cannot reach: opted out
+// with --no-mcp, or blocked by a name conflict. Both must be distinguishable from "not set up".
+{
+  const { mkdtempSync, writeFileSync, mkdirSync } = await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const { join } = await import("node:path");
+  const { mcpStatus } = await import("./mcp-register.js");
+
+  const home = mkdtempSync(join(tmpdir(), "pr-mcp-status-"));
+  const originalHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    // No configs at all: reported as absent, not as "not registered".
+    let rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.configFound), [false, false]);
+
+    // Present but not registered — the --no-mcp state.
+    writeFileSync(join(home, ".claude.json"), JSON.stringify({ mcpServers: {} }));
+    mkdirSync(join(home, ".codex"), { recursive: true });
+    writeFileSync(join(home, ".codex", "config.toml"), 'model = "gpt-5"\n');
+    rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.registered), [false, false]);
+    assert.deepEqual(rows.map((r) => r.conflict), [false, false]);
+    assert.deepEqual(rows.map((r) => r.configFound), [true, true]);
+
+    // Someone else's server under our name.
+    writeFileSync(
+      join(home, ".claude.json"),
+      JSON.stringify({ mcpServers: { [SERVER_NAME]: { command: "/my/own/build" } } }),
+    );
+    writeFileSync(
+      join(home, ".codex", "config.toml"),
+      `[mcp_servers.${SERVER_NAME}]\ncommand = "mine"\n`,
+    );
+    rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.conflict), [true, true]);
+    assert.deepEqual(rows.map((r) => r.registered), [false, false]);
+
+    // Ours.
+    writeFileSync(
+      join(home, ".claude.json"),
+      JSON.stringify(applyClaudeRegistry({})),
+    );
+    writeFileSync(join(home, ".codex", "config.toml"), renderCodexMcp(""));
+    rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.registered), [true, true]);
+    assert.deepEqual(rows.map((r) => r.conflict), [false, false]);
+  } finally {
+    process.env.HOME = originalHome;
+  }
+}
+
+console.log("mcp-register tests passed");