@mmerterden/multi-agent-pipeline 20.8.1 → 20.8.2

package/install/_mcp-register.mjs

@@ -1,22 +1,12 @@
 /**
  * Register the companion MCP server with a host CLI.
  *
- * WHY THIS IS SHARED
- *
- * Codex got MCP registration when its installer was written; Copilot never did, and
- * neither did Claude Code. The result was a host that carried the full pipeline skill
- * set and could not call a single one of the 83 toolkit tools those skills depend
- * on - `design-check`, every `ios_*` / `android_*` simulator call, the archive audits.
- * Nothing failed at install time, and the skills only fail when a run actually reaches
- * for a tool.
- *
- * Claude Code was the longest-lived instance of that bug and the easiest to miss,
- * because a maintainer who registered the server by hand once sees a working tree
- * forever while every fresh install ships without it.
+ * Every host's skills call the toolkit's tools (`design-check`, every `ios_*` /
+ * `android_*` simulator call, the archive audits), and a missing server shows up
+ * only when a run reaches for one of them, so each installer registers it.
  *
  * All three CLIs take the same shape (`<cli> mcp add [scope] <name> -- <command>
- * [args...]`), so the difference was purely which installers called it. One
- * implementation, three callers.
+ * [args...]`), so one implementation serves all three installers.
  *
  * @module install/_mcp-register
  */
@@ -32,18 +22,14 @@ export const MCP_SERVER_NAME = "multi-agent-toolkit";
 export const MCP_SERVER_PACKAGE = "@mmerterden/multi-agent-toolkit-mcp";
 
 /**
- * The spec the host is registered with. `@latest` is deliberate and it is the
- * difference between "the toolkit was published" and "the toolkit is running".
- *
- * Measured before this was added: the registration was the bare package name,
- * npx found ANY cached version and reused it, and a machine that had cached
- * 3.0.0 kept starting 3.0.0 after 3.1.0 was published and tagged `latest`. The
- * new tool existed on the registry and in the docs, and in no running server.
+ * The spec the host is registered with. `@latest` makes each server start
+ * resolve the newest published toolkit: with a bare package name, npx reuses
+ * any cached version, so a machine keeps starting whatever it cached first
+ * after newer releases are published.
  *
  * The cost is a registry round-trip when the MCP server starts, and an offline
- * start now depends on what npx can resolve from its cache rather than on a
- * cached version being present at all. That trade was made explicitly: a stale
- * server is a silent wrong answer, a failed start is a loud one.
+ * start depends on what npx can resolve from its cache. A stale server is a
+ * silent wrong answer, a failed start is a loud one.
  */
 export const MCP_SERVER_SPEC = `${MCP_SERVER_PACKAGE}@latest`;
 
@@ -87,7 +73,8 @@ export function scopeRegistryFlag(pkg = MCP_SERVER_PACKAGE, registry = MCP_REGIS
 export const LEGACY_MCP_SERVER_NAME = "dev-toolkit";
 
 /**
- * Per-host CLI invocation details.
+ * Per-host CLI invocation details, built at call time so a caller that changes
+ * HOME (a test, a sandboxed install) gets candidates under that HOME.
  *
  * `candidates`: where the CLI might live. A bare name is resolved through PATH by
  * execFileSync. The explicit paths matter for Copilot: `copilot` is frequently a
@@ -97,26 +84,32 @@ export const LEGACY_MCP_SERVER_NAME = "dev-toolkit";
  * ~/.local/share/gh/copilot/.
  *
  * `scopeArgs`: options inserted before the server name. Only Claude Code needs
- * them, and it needs them badly: `claude mcp add` defaults to `--scope local`,
- * which binds the server to whichever directory the installer happened to run
- * in. Every other project would then see no multi-agent-toolkit server at all. Codex
- * writes `~/.codex/config.toml` and Copilot writes `~/.copilot/mcp-config.json`,
- * both already user-global, so both take no scope flag - passing one errors.
+ * them: `claude mcp add` defaults to `--scope local`, which binds the server to
+ * whichever directory the installer happened to run in. Codex writes
+ * `~/.codex/config.toml` and Copilot writes `~/.copilot/mcp-config.json`, both
+ * already user-global, so both take no scope flag - passing one errors.
+ *
+ * `getArgs`: extra options for `mcp get` that make it print JSON.
+ *
+ * @param {"claude"|"codex"|"copilot"} host
  */
-const HOSTS = Object.freeze({
-  claude: {
-    candidates: ["claude", join(homedir(), ".local", "bin", "claude")],
-    scopeArgs: ["--scope", "user"],
-  },
-  codex: {
-    candidates: ["codex"],
-    scopeArgs: [],
-  },
-  copilot: {
-    candidates: ["copilot", join(homedir(), ".local", "share", "gh", "copilot", "copilot")],
-    scopeArgs: [],
-  },
-});
+function hostConfig(host) {
+  const home = homedir();
+  const hosts = {
+    claude: {
+      candidates: ["claude", join(home, ".local", "bin", "claude")],
+      scopeArgs: ["--scope", "user"],
+      getArgs: [],
+    },
+    codex: { candidates: ["codex"], scopeArgs: [], getArgs: ["--json"] },
+    copilot: {
+      candidates: ["copilot", join(home, ".local", "share", "gh", "copilot", "copilot")],
+      scopeArgs: [],
+      getArgs: ["--json"],
+    },
+  };
+  return hosts[host] || { candidates: [host], scopeArgs: [], getArgs: [] };
+}
 
 /**
  * First candidate that exists as a file, or the first bare name to let PATH resolution
@@ -127,7 +120,7 @@ const HOSTS = Object.freeze({
  * @returns {string}
  */
 function resolveCli(host) {
-  const candidates = HOSTS[host]?.candidates || [host];
+  const { candidates } = hostConfig(host);
   for (const c of candidates) {
     if (c.includes("/") && existsSync(c)) return c;
   }
@@ -139,37 +132,76 @@ function saysAlreadyExists(text) {
   return /already exists/i.test(text);
 }
 
+const outputOf = (e) =>
+  `${e?.stderr?.toString() ?? ""}\n${e?.stdout?.toString() ?? ""}\n${e?.message ?? ""}`;
+
+/**
+ * The command line a registered server starts, as `[command, ...args]`, read
+ * from `<cli> mcp get`. Accepts the JSON form (Codex, Copilot: an object
+ * carrying `command` and `args`, possibly nested) and the text form (Claude
+ * Code: `Command:` and `Args:` lines; Copilot's text puts both on `Command:`).
+ *
+ * @param {string} text
+ * @returns {string[]|null}
+ */
+export function parseRegisteredSpec(text) {
+  const raw = String(text || "").trim();
+  if (!raw) return null;
+  try {
+    const find = (node) => {
+      if (!node || typeof node !== "object") return null;
+      if (typeof node.command === "string") {
+        return [node.command, ...(Array.isArray(node.args) ? node.args.map(String) : [])];
+      }
+      for (const v of Object.values(node)) {
+        const hit = find(v);
+        if (hit) return hit;
+      }
+      return null;
+    };
+    const hit = find(JSON.parse(raw));
+    if (hit) return hit;
+  } catch {
+    /* not JSON: read the text form */
+  }
+  const command = /^\s*Command:\s*(.+)$/m.exec(raw)?.[1]?.trim();
+  if (!command) return null;
+  const args = /^\s*Args:\s*(.*)$/m.exec(raw)?.[1]?.trim();
+  const words = (s) => s.split(/\s+/).filter(Boolean);
+  return args === undefined ? words(command) : [...words(command), ...words(args)];
+}
+
 /**
- * Register the MCP server. Idempotent from the caller's point of view, though the
- * three CLIs get there by three different routes:
+ * Register the MCP server, keeping whatever registration exists until a
+ * replacement is in place.
+ *
+ * The add runs first. The three CLIs answer a duplicate differently:
  *
  * - `codex mcp add` replaces an existing entry and exits 0.
  * - `copilot mcp add` refuses, printing `Server "<name>" already exists` and exiting 1.
  * - `claude mcp add` refuses, printing `MCP server <name> already exists in <scope>
  *   config` and exiting **0**.
  *
- * So neither the exit code nor the stream tells you on its own. A non-zero exit is not
- * automatically a failure, and a zero exit is not automatically a fresh write - which
- * is why the "already exists" test runs on both paths. Reporting an existing server as
- * "skipped MCP registration (Command failed)" would send the user to fix something that
- * is already correct.
- *
- * An existing entry under the same name is removed and re-added so its spec follows
- * the installed version (the entry is installer-owned; the reason is at the remove
- * below). A user who points the toolkit at a local checkout registers it under a
- * different name or re-applies the change after an update.
+ * so "already exists" is looked for on both the success and the failure path.
+ * On a duplicate, the registered spec is read back with `mcp get` and compared
+ * with the one this release wants. The same spec is left alone. A different
+ * spec is replaced (remove, then add); if that add fails, the previous spec is
+ * added back so the host never ends up with no server. A spec that cannot be
+ * read back is not replaced, because it could not be restored.
  *
  * Never fatal: a missing CLI or a failed write must not fail the install, because the
  * rest of the tree is still correct and useful. It prints the manual command instead.
  *
  * @param {"claude"|"codex"|"copilot"} host
  * @param {string} label - host label for log lines
- * @returns {{registered: boolean, alreadyPresent?: boolean, reason?: string}}
+ * @param {{cli?: string}} [opts] - `cli` overrides the CLI lookup (tests)
+ * @returns {{registered: boolean, alreadyPresent?: boolean, staleSpec?: boolean, replaced?: boolean, reason?: string}}
  */
-export function registerMcpServer(host, label) {
-  const cli = resolveCli(host);
-  const scopeArgs = HOSTS[host]?.scopeArgs || [];
+export function registerMcpServer(host, label, { cli: cliOverride } = {}) {
+  const cli = cliOverride || resolveCli(host);
+  const { scopeArgs, getArgs } = hostConfig(host);
   const npxArgs = ["-y", ...scopeRegistryFlag(), MCP_SERVER_SPEC];
+  const desired = ["npx", ...npxArgs];
   const manual = `${host} mcp add ${scopeArgs.join(" ")}${scopeArgs.length ? " " : ""}${MCP_SERVER_NAME} -- npx ${npxArgs.join(" ")}`;
 
   if (isDryRun()) {
@@ -186,75 +218,99 @@ export function registerMcpServer(host, label) {
     return { registered: false, reason: "opted out" };
   }
 
-  // Drop the pre-rename entry before adding the new one. Best-effort by design:
-  // "not registered" is the common case (a fresh install) and is not an error,
-  // and a host that cannot remove it is not a reason to skip the add.
+  // Bounded: an installer must never hang on a child process. These are local
+  // config reads and writes and return in milliseconds.
+  const run = (args) => execFileSync(cli, args, { stdio: "pipe", timeout: 20_000 });
+  const add = (spec) => {
+    try {
+      const stdout = run(["mcp", "add", ...scopeArgs, MCP_SERVER_NAME, "--", ...spec]);
+      // Claude Code refuses a duplicate on the success path (exit 0).
+      return saysAlreadyExists(stdout?.toString() ?? "") ? "exists" : "added";
+    } catch (e) {
+      const out = outputOf(e);
+      if (saysAlreadyExists(out)) return "exists";
+      const why =
+        e?.code === "ENOENT"
+          ? `${host} not on PATH`
+          : (out.split("\n").find((l) => l.trim()) || "unknown error").trim();
+      return { failed: why };
+    }
+  };
+
+  // The pre-rename entry (LEGACY_MCP_SERVER_NAME) would advertise the same tools
+  // under a second name. Best-effort: "not registered" is the common case.
   try {
-    execFileSync(cli, ["mcp", "remove", ...scopeArgs, LEGACY_MCP_SERVER_NAME], {
-      stdio: "pipe",
-      timeout: 20_000,
-    });
+    run(["mcp", "remove", ...scopeArgs, LEGACY_MCP_SERVER_NAME]);
     console.log(`    -> ${label}: removed the legacy ${LEGACY_MCP_SERVER_NAME} registration`);
   } catch {
     /* not present, or the host declines - either way the add below is what matters */
   }
 
-  // Drop the CURRENT entry too, so the add below rewrites its spec. Without this
-  // the host answers "already exists", the installer reported success, and the
-  // stored args stayed whatever an older version wrote - which is how a machine
-  // kept starting the toolkit from a bare package name (and therefore from
-  // whatever npx had cached) long after the spec gained `@latest`. The entry is
-  // installer-owned, so replacing it is not clobbering a user's work; a host
-  // that refuses the remove is reported below rather than counted as current.
-  let replacedExisting = false;
+  const first = add(desired);
+  if (first === "added") {
+    console.log(
+      `    -> ${label}: registered the ${MCP_SERVER_NAME} MCP server (${MCP_SERVER_SPEC})`,
+    );
+    return { registered: true };
+  }
+  if (first !== "exists") {
+    console.log(`    -> ${label}: skipped MCP registration (${first.failed})`);
+    console.log(`       run manually: ${manual}`);
+    return { registered: false, reason: first.failed };
+  }
+
+  let previous;
   try {
-    execFileSync(cli, ["mcp", "remove", ...scopeArgs, MCP_SERVER_NAME], {
-      stdio: "pipe",
-      timeout: 20_000,
-    });
-    replacedExisting = true;
+    previous = parseRegisteredSpec(run(["mcp", "get", MCP_SERVER_NAME, ...getArgs])?.toString());
   } catch {
-    /* not registered yet - the common case on a fresh install */
+    previous = null;
+  }
+  if (previous && previous.join("\u0000") === desired.join("\u0000")) {
+    console.log(
+      `    -> ${label}: ${MCP_SERVER_NAME} MCP server already registered (${MCP_SERVER_SPEC})`,
+    );
+    return { registered: true, alreadyPresent: true };
+  }
+  if (!previous) {
+    console.log(
+      `    -> ${label}: ${MCP_SERVER_NAME} already registered; its spec could not be read, so it was ` +
+        `left as-is. To make sure it runs ${MCP_SERVER_SPEC}, re-register with: ${manual}`,
+    );
+    return { registered: true, alreadyPresent: true, staleSpec: true };
   }
 
   try {
-    // Bounded: an installer must never hang on a child process. This is a local config
-    // write and returns in milliseconds.
-    const stdout = execFileSync(
-      cli,
-      ["mcp", "add", ...scopeArgs, MCP_SERVER_NAME, "--", "npx", ...npxArgs],
-      { stdio: "pipe", timeout: 20_000 },
+    run(["mcp", "remove", ...scopeArgs, MCP_SERVER_NAME]);
+  } catch (e) {
+    console.log(
+      `    -> ${label}: ${MCP_SERVER_NAME} is registered with an older spec and the host declined ` +
+        `to remove it (${(
+          outputOf(e)
+            .split("\n")
+            .find((l) => l.trim()) || "unknown error"
+        ).trim()}). ` +
+        `Re-register manually with: ${manual}`,
     );
-    // Claude Code refuses a duplicate on the SUCCESS path (exit 0), so the check
-    // cannot live in the catch alone.
-    if (saysAlreadyExists(stdout?.toString() ?? "")) {
-      // Reached only when the remove above did not take. The entry survives, but
-      // its spec is whatever was there before, so this is not a current
-      // registration - say that instead of reporting a clean pass.
-      console.log(
-        `    -> ${label}: ${MCP_SERVER_NAME} already registered and the host declined to replace it; ` +
-          `its spec may predate ${MCP_SERVER_SPEC}. Re-register manually with: ${manual}`,
-      );
-      return { registered: true, alreadyPresent: true, staleSpec: true };
-    }
+    return { registered: true, alreadyPresent: true, staleSpec: true };
+  }
+  const replaced = add(desired);
+  if (replaced === "added" || replaced === "exists") {
     console.log(
-      `    -> ${label}: ${replacedExisting ? "re-registered" : "registered"} the ${MCP_SERVER_NAME} MCP server (${MCP_SERVER_SPEC})`,
+      `    -> ${label}: re-registered the ${MCP_SERVER_NAME} MCP server (${MCP_SERVER_SPEC})`,
     );
-    return { registered: true };
-  } catch (e) {
-    // The CLI writes its diagnosis to stderr, which execFileSync parks on the error
-    // rather than in `message`. Read both, or "already exists" is invisible.
-    const out = `${e?.stderr?.toString() ?? ""}\n${e?.stdout?.toString() ?? ""}\n${e?.message ?? ""}`;
-    if (saysAlreadyExists(out)) {
-      console.log(`    -> ${label}: ${MCP_SERVER_NAME} MCP server already registered, left as-is`);
-      return { registered: true, alreadyPresent: true };
-    }
-    const why =
-      e?.code === "ENOENT"
-        ? `${host} not on PATH`
-        : (out.split("\n").find((l) => l.trim()) || "unknown error").trim();
-    console.log(`    -> ${label}: skipped MCP registration (${why})`);
-    console.log(`       run manually: ${manual}`);
-    return { registered: false, reason: why };
+    return { registered: true, replaced: true };
+  }
+  const restored = add(previous);
+  if (restored === "added" || restored === "exists") {
+    console.log(
+      `    -> ${label}: could not update ${MCP_SERVER_NAME} (${replaced.failed}); the previous ` +
+        `registration was restored. Re-register manually with: ${manual}`,
+    );
+    return { registered: true, alreadyPresent: true, staleSpec: true, reason: replaced.failed };
   }
+  console.log(
+    `    -> ${label}: could not update ${MCP_SERVER_NAME} (${replaced.failed}) or restore the previous ` +
+      `registration (${restored.failed}). Register it manually with: ${manual}`,
+  );
+  return { registered: false, reason: replaced.failed };
 }