comfyui-mcp 0.50.21 → 0.50.23

package/scripts/smoke-install.mjs

@@ -10,10 +10,50 @@
  * crashed on a missing file. Unit tests (`npm test`) never exercise the packed
  * tarball, so this is the gap. Run in CI and as a pre-publish gate.
  */
-import { execSync, spawnSync } from "node:child_process";
-import { mkdtempSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { execSync, spawn, spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, existsSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Ask the installed server for its tool list over MCP stdio. Resolves to the
+ * names, or null if it never answers within the budget — a silence this script
+ * reports rather than reading as "no tools".
+ */
+function listTools(entry) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [entry], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, COMFYUI_URL: "http://127.0.0.1:59999" },
+    });
+    const send = (o) => child.stdin.write(JSON.stringify(o) + "\n");
+    let buf = "";
+    const done = (v) => { try { child.kill(); } catch { /* already gone */ } resolve(v); };
+    const timer = setTimeout(() => done(null), 60_000);
+    child.stdout.on("data", (d) => {
+      buf += d.toString();
+      let i;
+      while ((i = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, i);
+        buf = buf.slice(i + 1);
+        if (!line.trim()) continue;
+        let msg;
+        try { msg = JSON.parse(line); } catch { continue; }
+        if (msg.id === 1) send({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
+        if (msg.id === 2) {
+          clearTimeout(timer);
+          done((msg.result?.tools ?? []).map((t) => t.name));
+        }
+      }
+    });
+    child.on("error", () => { clearTimeout(timer); done(null); });
+    send({
+      jsonrpc: "2.0", id: 1, method: "initialize",
+      params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "smoke", version: "1" } },
+    });
+  });
+}
 
 const run = (cmd, opts = {}) => {
   console.log(`$ ${cmd}${opts.cwd ? `  (cwd: ${opts.cwd})` : ""}`);
@@ -67,4 +107,95 @@ if (boot.signal === "SIGTERM" || boot.status === 0) {
   process.exit(1);
 }
 
-console.log("✅ pack/install smoke passed — tarball installs cleanly and boots");
+// 5. The published surface actually REGISTERS. Booting proves the process starts;
+//    it does not prove the tools are there. A packaging or registration
+//    regression that leaves the server up but short a tool would pass step 4 and
+//    ship — the user finds out when the tool they wanted is simply absent.
+//
+//    Driven over real MCP stdio against the INSTALLED tarball, so this is the
+//    surface a user gets, not the one the repo builds. COMFYUI_URL points at a
+//    dead port on purpose: registration must not depend on a reachable ComfyUI.
+// The ledger IS the list, not a ceiling: TOOL_NAMES holds every core tool, and
+// MAX_TOOLS beside it is a budget target that merely happens to match today.
+// Counting the list keeps this honest if the two ever diverge.
+const LEDGER = readFileSync(join(process.cwd(), "src/tools/vocabulary.ts"), "utf-8");
+const EXPECTED_CORE = (
+  LEDGER.match(/TOOL_NAMES\s*=\s*\[[\s\S]*?\n\]/)?.[0].match(/"[a-z][a-z0-9_]*"/g) ?? []
+).length;
+const surface = await listTools(join(pkg, "dist/index.js"));
+if (surface === null) {
+  console.error("❌ the installed server never answered tools/list");
+  process.exit(1);
+}
+// The three compact-mode meta tools (list_tools / describe_tool / call_tool) are
+// registered ALONGSIDE the core surface and are deliberately absent from the
+// ledger, so they are counted out rather than expected in it.
+const META = ["list_tools", "describe_tool", "call_tool"];
+const core = surface.filter((n) => !META.includes(n));
+const missingMeta = META.filter((n) => !surface.includes(n));
+if (EXPECTED_CORE > 0 && core.length !== EXPECTED_CORE) {
+  console.error(
+    `❌ installed surface has ${core.length} core tools, ledger declares ${EXPECTED_CORE}` +
+      `\n   registered: ${core.join(", ")}`,
+  );
+  process.exit(1);
+}
+if (missingMeta.length) {
+  console.error(`❌ compact-mode tools missing from the installed surface: ${missingMeta.join(", ")}`);
+  process.exit(1);
+}
+console.log(`✅ installed surface registers ${core.length} core tools + ${META.length} compact-mode tools`);
+
+// 6. The PANEL surface too. Those 91 tools are the whole reason the panel can
+//    drive a live canvas, they ship in the same tarball, and nothing else here
+//    checks that the published build still builds them. buildPanelToolDefs is
+//    pure — no server, no socket — so this is a direct call into the INSTALLED
+//    dist rather than another stdio round trip.
+//
+//    Compared against THIS REPO'S build, not against docs/design/panel-surface.txt.
+//    That baseline is frozen HISTORY, not the current surface: check-tool-vocabulary
+//    requires live ⊆ baseline, so the baseline only ever grows, and a retired panel
+//    tool keeps its line there forever. Counting against it passes today only
+//    because nothing has been retired yet — the first legitimate retirement would
+//    read as "installed build makes 90, ledger declares 92" and fail a RELEASE, the
+//    one gate a false alarm is most expensive in. The ledger relationship is already
+//    enforced on every PR by check:vocabulary, from both sides; what only this script
+//    can see is whether the TARBALL carries the same surface the repo builds, which
+//    is a packaging question and is what it now asks.
+//
+//    `prepare: tsc` runs during npm pack in step 1, so ./dist is a fresh build of
+//    this source. Two separate module instances, same process and env.
+async function panelNames(root, label) {
+  try {
+    const mod = await import(pathToFileURL(join(root, "dist/orchestrator/panel-tools.js")).href);
+    if (typeof mod.buildPanelToolDefs !== "function") {
+      console.error(`❌ the ${label} build exports no buildPanelToolDefs`);
+      process.exit(1);
+    }
+    return mod.buildPanelToolDefs().map((d) => d.name);
+  } catch (err) {
+    console.error(`❌ could not load the ${label} panel tools: ${err?.message ?? err}`);
+    process.exit(1);
+  }
+}
+const installedPanel = await panelNames(pkg, "installed");
+const repoPanel = await panelNames(process.cwd(), "repo");
+// A comparison of two empty lists is equal and proves nothing — the vacuous pass
+// that the sibling gate tests each carry a floor assertion against.
+if (repoPanel.length < 50) {
+  console.error(`❌ the repo build makes only ${repoPanel.length} panel tools — check is not looking at a real surface`);
+  process.exit(1);
+}
+const onlyInstalled = installedPanel.filter((n) => !repoPanel.includes(n));
+const onlyRepo = repoPanel.filter((n) => !installedPanel.includes(n));
+if (onlyInstalled.length || onlyRepo.length) {
+  console.error(
+    `❌ the tarball's panel surface differs from this repo's build` +
+      (onlyRepo.length ? `\n   in the repo but NOT in the tarball: ${onlyRepo.join(", ")}` : "") +
+      (onlyInstalled.length ? `\n   in the tarball but NOT in the repo: ${onlyInstalled.join(", ")}` : ""),
+  );
+  process.exit(1);
+}
+console.log(`✅ tarball's ${installedPanel.length} panel tools match this repo's build`);
+
+console.log("✅ pack/install smoke passed — tarball installs cleanly, boots, and registers its tools");

package/scripts/tools-dump.mts

@@ -9,9 +9,13 @@
  *   npx tsx scripts/tools-dump.mts                 # JSON: {count, tools:[…]}
  *   npx tsx scripts/tools-dump.mts --names         # one name per line, registration order
  *   npx tsx scripts/tools-dump.mts --max 30        # exit 1 if count > 30
- *   npx tsx scripts/tools-dump.mts --golden docs/design/tool-surface.txt
+ *   npx tsx scripts/tools-dump.mts --golden path/to/expected.txt
  *                                                  # diff names vs a committed golden
- *   npx tsx scripts/tools-dump.mts --write-golden docs/design/tool-surface.txt
+ *   npx tsx scripts/tools-dump.mts --write-golden path/to/expected.txt
+ *
+ * The golden is a snapshot of the LIVE surface. It is NOT docs/design/tool-surface.txt
+ * or docs/design/panel-surface.txt — those are hash-pinned retirement baselines and
+ * both invocations are refused against them; see RETIREMENT_BASELINES below.
  *
  * COMFYUI_URL is set so src/config.ts skips its network port-probe at import
  * time (same reason npm run docs:gen sets it).
@@ -116,6 +120,48 @@ if (max !== undefined) {
   }
 }
 
+/**
+ * The two hash-pinned RETIREMENT BASELINES. Neither is a live-surface golden, and
+ * pointing this script at either is a footgun in both directions.
+ *
+ * They are history, not state: docs/design/tool-surface.txt holds every core name
+ * that has EVER existed (195), against which check-tool-vocabulary enforces
+ * `BASELINE \ TOOL_NAMES ⊆ DEAD_NAMES`. The live surface is 37 after the 0.50.0
+ * consolidation and will never equal it again.
+ *
+ * So `--golden docs/design/tool-surface.txt` — an invocation this script's own
+ * usage text used to advertise — reports 158 removals and exits 1 on a perfectly
+ * healthy repo. That alone is only noise. The danger is the remedy printed
+ * underneath it: "re-run with --write-golden", which would overwrite the baseline
+ * with the 37 live names and DELETE the other 158. Deleting a line from a
+ * retirement baseline is exactly how the ratchet is disarmed for that name — every
+ * stale reference to it stops being an error. One typo-free, instruction-following
+ * run would have silently disarmed the repo's main vocabulary gate for 158 names,
+ * leaving only the SHA pin, whose own error text invites updating the hash.
+ *
+ * Refused rather than warned: there is no correct reading of either invocation.
+ * The baseline is maintained by APPENDING a newly shipped name and updating its
+ * SHA deliberately, which is a reviewed edit rather than a bulk rewrite.
+ */
+const RETIREMENT_BASELINES = ["tool-surface.txt", "panel-surface.txt"];
+const isRetirementBaseline = (p: string): boolean =>
+  RETIREMENT_BASELINES.some((b) => p.replace(/\\/g, "/").endsWith(`docs/design/${b}`));
+
+for (const opt of ["--golden", "--write-golden"] as const) {
+  const p = value(opt);
+  if (p !== undefined && isRetirementBaseline(p)) {
+    usage(
+      `${p} is a hash-pinned RETIREMENT BASELINE (every name that has ever existed), ` +
+        `not a golden of the live surface — ${opt} would ` +
+        (opt === "--write-golden"
+          ? `overwrite it with today's ${names.length} live names and delete the rest, disarming the dead-name ratchet for every name dropped.`
+          : `report every retired name as a removal and exit 1 on a healthy repo.`) +
+        `\n  What enforces it: npm run check:vocabulary (BASELINE \\ TOOL_NAMES ⊆ DEAD_NAMES).` +
+        `\n  To add a newly shipped tool: append the name, then update BASELINE_SHA256 in src/tools/vocabulary.ts.`,
+    );
+  }
+}
+
 const writeGolden = value("--write-golden");
 if (writeGolden) {
   writeFileSync(writeGolden, `${names.join("\n")}\n`, "utf8");