@rainbow-robotics/muscat-plugin-kit 1.10.2-dev.1 → 1.10.2-dev.3

package/cli/bin/muscat-pk.mjs

@@ -5,13 +5,13 @@ import { readFileSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
-import { color, kitVersion, log, resolveLocalCliBin } from "../src/util.mjs";
+import { color, compareKitVersions, kitVersion, log, resolveLocalCliBin } from "../src/util.mjs";
 import { runNew } from "../src/new.mjs";
 import { runBuild } from "../src/build.mjs";
 import { runDevUi } from "../src/devUi.mjs";
 import { runDevBack } from "../src/devBack.mjs";
 import { runDev } from "../src/dev.mjs";
-import { runUpdate } from "../src/update.mjs";
+import { runUpdate, runUpdateCheck } from "../src/update.mjs";
 import { runUninstall } from "../src/uninstall.mjs";
 import { runSdk } from "../src/sdk.mjs";
 import { runType } from "../src/type.mjs";
@@ -50,6 +50,13 @@ if (isBinaryMode && !process.env.MUSCAT_PK_VERSION) {
     // Say so — otherwise an outdated local copy silently answers instead, and
     // its missing/renamed subcommands look like the CLI is broken.
     const localVersion = readVersion(localBin);
+    // An older local copy can't update a project correctly — it doesn't know what changed since
+    // it was published. Run this CLI's update instead, still touching this project only.
+    if (process.argv[2] === "update" && localVersion && compareKitVersions(localVersion, kitVersion()) < 0) {
+      console.error(color.dim(`[muscat-pk] project's local install (v${localVersion}) is older — updating it with this CLI (v${kitVersion()})`));
+      process.env.MUSCAT_PK_UPDATE_PROJECT_ONLY = "1";
+      return;
+    }
     console.error(
       color.dim(`[muscat-pk] using this project's local install${localVersion ? ` (v${localVersion})` : ""}: ${localBin}`),
     );
@@ -121,6 +128,8 @@ async function main() {
       }
       case "update":
         return await runUpdate(args);
+      case "update:check": // internal: update runs it with the freshly installed local kit
+        return await runUpdateCheck(args);
       case "uninstall":
         return await runUninstall(args);
       case "sdk":

package/cli/src/ai-rules.mjs

@@ -29,6 +29,33 @@ const UI_RULES = [
   "Colors and type come from tokens (bg-bg-*, text-fg-*, typo-*), not hex values or arbitrary Tailwind colors.",
 ];
 
+// plugin-ui 1.x replaced the remote-dom components and the connect() bootstrap. The project check
+// (update, MCP check_project) flags these; the migration rules below tell an agent how to fix them.
+export const LEGACY_SUBPATHS = {
+  connect: "removed — drop `connect(App)` and `export default App` instead (the host renders the entry's default export)",
+  elements: "removed — use the RB* components from @rainbow-robotics/plugin-ui/react",
+  "dist-browser": "removed — import from @rainbow-robotics/plugin-ui/react",
+};
+export const LEGACY_COMPONENTS = {
+  Slider: "RBSlider",
+  Button: "RBLabelButton",
+  IconButton: "RBIconButton",
+  Text: "a plain element or RBTextLabel",
+  TextInput: "RBTextInput / RBTextField",
+  Switch: "RBSwitch",
+  Select: "RBSelectBox",
+};
+const MIGRATION_RULES = [
+  "After `muscat-pk update`, or when the UI fails to build or the preview says \"no default export\", call check_project and fix every item it lists. Call it again until it reports no issues.",
+  "Each top-level ui/*.tsx is an entry and ends in `export default App`. The old `connect(App)` bootstrap and @rainbow-robotics/plugin-ui/connect are gone.",
+  "vite.config.ts uses the muscat() preset (`plugins: [muscat()]` from @rainbow-robotics/muscat-plugin-kit/vite); keep any other plugins the project adds. A hand-written config drops the entry's default export from the build.",
+  "rb.toast takes one object: rb.toast({ message, type }).",
+  `Old components → new: ${Object.entries(LEGACY_COMPONENTS).map(([o, n]) => `${o} → ${n}`).join(", ")}. Their props differ (no event.detail) — call get_component_example for the new component before rewriting.`,
+];
+
+// Claude Code reads this to start the MCP server; `muscat-pk` hands off to the project's local kit.
+export const MCP_JSON = `${JSON.stringify({ mcpServers: { muscat: { command: "muscat-pk", args: ["mcp"] } } }, null, 2)}\n`;
+
 const nativeTable = () => NATIVE_TO_RB.map(([el, rb]) => `- ${el}: ${rb}`).join("\n");
 
 export const SERVER_INSTRUCTIONS = `Muscat plugin UI (ui/*.tsx) is built only from @rainbow-robotics/plugin-ui/react, styled with the design-token Tailwind classes (list_design_tokens).
@@ -39,6 +66,9 @@ ${UI_RULES.map((r) => `- ${r}`).join("\n")}
 Native element -> plugin-ui component:
 ${nativeTable()}
 
+Upgrading a project made with an older kit:
+${MIGRATION_RULES.map((r) => `- ${r}`).join("\n")}
+
 Backend, manifest and SDK questions: search_rb_sdk, list_rb_sdk, get_rb_sdk_api.`;
 
 // AGENTS.md (Codex, Cursor, Gemini CLI, Copilot …). CLAUDE.md imports it with `@AGENTS.md`.
@@ -64,6 +94,13 @@ ${UI_RULES.map((r) => `- ${r}`).join("\n")}
 Native element → plugin-ui component:
 
 ${nativeTable()}
+
+## Upgrading from an older kit
+
+\`muscat-pk update\` bumps the kit, plugin-ui and preview-host and lists what the project must change.
+The MCP tool \`check_project\` runs the same check (known old APIs + \`tsc --noEmit\`).
+
+${MIGRATION_RULES.map((r) => `- ${r}`).join("\n")}
 `;
 }
 

package/cli/src/mcp.mjs

@@ -43,6 +43,7 @@ import { PYTHON_DEV_IMAGE } from "./python.mjs";
 import { SHIPPED_STORIES_SRC, SHIPPED_DESIGN_TOKENS } from "./storybook.mjs";
 import { CPP_DEV_IMAGE } from "./cpp.mjs";
 import { NATIVE_TO_RB, SERVER_INSTRUCTIONS } from "./ai-rules.mjs";
+import { checkProject, formatProjectCheck } from "./projectCheck.mjs";
 
 const TEMPLATE_READMES = { python: "common/README.md", cpp: "readme-cpp/README.md" };
 // Design tokens: prefer the shipped copy, fall back to the monorepo source.
@@ -1090,6 +1091,35 @@ print(json.dumps(res))
     },
   );
 
+  server.registerTool(
+    "check_project",
+    {
+      title: "Check the plugin project for changes the installed plugin-ui needs",
+      description:
+        "List what the plugin project must change to work with the plugin-ui it has installed: old APIs " +
+        "(connect(App), Slider/Text/Switch…, rb.toast(message, type), a vite.config without the muscat() " +
+        "preset, entries without a default export) and `tsc --noEmit` errors, each as file:line. Same check " +
+        "as `muscat-pk update`. Call it after an update or when the UI fails to build, fix each item " +
+        "(get_component_example for replacement components), and call it again until it reports no issues.",
+      inputSchema: {
+        path: z.string().optional().describe("Plugin project directory (default: the server's working directory)"),
+      },
+    },
+    async ({ path }) => {
+      let root;
+      try {
+        root = findPluginRoot(path ? resolve(path) : process.cwd());
+      } catch (err) {
+        return { isError: true, content: [{ type: "text", text: err.message }] };
+      }
+      const lines = formatProjectCheck(checkProject(root));
+      const text = lines.length
+        ? `${root}: ${lines.filter((l) => /:\d+ {2}/.test(l)).length} item(s) to fix\n${lines.join("\n")}`
+        : `${root}: no issues — the project matches the installed plugin-ui.`;
+      return { content: [{ type: "text", text }] };
+    },
+  );
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/cli/src/new.mjs

@@ -13,7 +13,7 @@ import {
 } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { color, ensureIdeVenv, hasBin, kitVersion, parseArgs, prompt, templatesDir, log } from "./util.mjs";
-import { agentsMd, CLAUDE_MD } from "./ai-rules.mjs";
+import { agentsMd, CLAUDE_MD, MCP_JSON } from "./ai-rules.mjs";
 
 // Like cpSync(src, dst, {recursive:true}) but reads from the embedded snapshot
 // when the templates dir doesn't exist on disk (compiled binary mode).
@@ -281,6 +281,7 @@ export async function runNew(args) {
   // Rules for AI agents, generated from the same source as the MCP server's instructions.
   writeFileSync(resolve(target, "AGENTS.md"), agentsMd({ pluginName }));
   writeFileSync(resolve(target, "CLAUDE.md"), CLAUDE_MD);
+  writeFileSync(resolve(target, ".mcp.json"), MCP_JSON);
 
   if (!opts["no-install"]) {
     try {

package/cli/src/projectCheck.mjs

@@ -0,0 +1,102 @@
+// What a project must change for the plugin-ui it has installed: known old APIs (ai-rules.mjs) plus
+// `tsc --noEmit`. Shared by `muscat-pk update` and the MCP tool check_project, so a user and an
+// agent see the same list.
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { LEGACY_COMPONENTS, LEGACY_SUBPATHS } from "./ai-rules.mjs";
+
+const isBinaryMode = typeof Bun !== "undefined";
+
+// The clause can't hold quotes or `;`, so a match can't start at an earlier import statement.
+const PLUGIN_UI_IMPORT = /import\s+([^;'"]*?)\s+from\s+["']@rainbow-robotics\/plugin-ui\/([\w-]+)["']/g;
+
+function listUiFiles(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+    e.isDirectory() ? listUiFiles(join(dir, e.name)) : /\.[jt]sx?$/.test(e.name) ? [join(dir, e.name)] : [],
+  );
+}
+
+// rb.toast takes one { message, type } object now; flag a string or multi-argument call.
+const TOAST_CALL = /\.toast\(([^()]*)\)/g;
+
+/** Uses of the pre-1.x plugin-ui API in the project (ui/ and vite.config), as { file, line, text }. */
+function findLegacyUiUsage(root) {
+  const uiDir = resolve(root, "ui");
+  if (!existsSync(uiDir)) return [];
+  const found = [];
+  // The old hand-written config builds entries without their exports (connect() rendered as a side
+  // effect), so `export default App` is dropped from dist. The muscat() preset keeps it.
+  const viteConfig = ["vite.config.ts", "vite.config.mts", "vite.config.js", "vite.config.mjs"].find((f) => existsSync(resolve(root, f)));
+  if (viteConfig && !readFileSync(resolve(root, viteConfig), "utf8").includes("@rainbow-robotics/muscat-plugin-kit/vite")) {
+    found.push({
+      file: viteConfig,
+      line: 1,
+      text: 'not using the muscat() preset — the build drops the entry\'s default export. Use: import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite"; defineConfig({ plugins: [muscat()] })',
+    });
+  }
+  for (const file of listUiFiles(uiDir)) {
+    const src = readFileSync(file, "utf8");
+    const rel = relative(root, file);
+    const lineOf = (index) => src.slice(0, index).split("\n").length;
+    for (const m of src.matchAll(PLUGIN_UI_IMPORT)) {
+      const [, clause, subpath] = m;
+      if (LEGACY_SUBPATHS[subpath]) {
+        found.push({ file: rel, line: lineOf(m.index), text: `@rainbow-robotics/plugin-ui/${subpath} ${LEGACY_SUBPATHS[subpath]}` });
+      } else if (subpath === "react") {
+        const named = clause.match(/\{([\s\S]*)\}/)?.[1] ?? "";
+        for (const spec of named.split(",")) {
+          const name = spec.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0];
+          if (LEGACY_COMPONENTS[name]) {
+            found.push({ file: rel, line: lineOf(m.index), text: `${name} → ${LEGACY_COMPONENTS[name]}` });
+          }
+        }
+      }
+    }
+    for (const m of src.matchAll(TOAST_CALL)) {
+      const arg = m[1].trim();
+      if (!arg.startsWith("{") && (/^["'`]/.test(arg) || arg.includes(","))) {
+        found.push({ file: rel, line: lineOf(m.index), text: "rb.toast(message, type) → rb.toast({ message, type })" });
+      }
+    }
+    // Top-level ui/ files are the entries; the host mounts their default export.
+    if (relative(uiDir, file).split(/[\\/]/).length === 1 && !/export\s+default\b/.test(src)) {
+      found.push({ file: rel, line: 1, text: "no default export — the host renders the entry's default export" });
+    }
+  }
+  return found;
+}
+
+// The known-API list above only knows past changes. Type-checking against the plugin-ui that was
+// just installed catches whatever a later release removes or reshapes, with no list to keep up.
+function typeScriptErrors(root) {
+  const tsc = resolve(root, "node_modules/typescript/bin/tsc");
+  if (!existsSync(tsc) || !existsSync(resolve(root, "tsconfig.json"))) return [];
+  const runtime = isBinaryMode ? "node" : process.execPath;
+  const r = spawnSync(runtime, [tsc, "--noEmit", "-p", root, "--pretty", "false"], { cwd: root, encoding: "utf8" });
+  return `${r.stdout ?? ""}`
+    .split("\n")
+    .map((l) => /^(.+?)\((\d+),\d+\): error (TS\d+): (.*)$/.exec(l))
+    .filter(Boolean)
+    .map(([, file, line, code, text]) => ({ file: relative(root, resolve(root, file)), line: Number(line), text: `${code} ${text}` }));
+}
+
+/** Everything the project must change, as { file, line, text, source: "known" | "tsc" }. */
+export function checkProject(root) {
+  return [
+    ...findLegacyUiUsage(root).map((f) => ({ ...f, source: "known" })),
+    ...typeScriptErrors(root).map((e) => ({ ...e, source: "tsc" })),
+  ];
+}
+
+/** Plain-text lines for a checkProject() result (empty when there is nothing to fix). */
+export function formatProjectCheck(items) {
+  if (!items.length) return [];
+  const line = (i) => `  ${i.file}:${i.line}  ${i.text}`;
+  const tsc = items.filter((i) => i.source === "tsc");
+  return [
+    ...items.filter((i) => i.source !== "tsc").map(line),
+    ...(tsc.length ? ["  TypeScript (tsc --noEmit):", ...tsc.map(line)] : []),
+    "  For working examples, generate a fresh project and read its ui/content.tsx:  muscat-pk new <dir>",
+  ];
+}

package/cli/src/update.mjs

@@ -11,9 +11,14 @@
 // After updating the CLI itself, also bumps the plugin project's local deps
 // and migrates the project structure if it's outdated (src/ → ui/, root main.py → py/).
 import { execSync, spawn, spawnSync } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
-import { findPluginRoot, isLocalKitInstall, KIT_PUBLISHED_NAME, kitVersion, log, parseArgs, prompt } from "./util.mjs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { agentsMd, CLAUDE_MD, MCP_JSON } from "./ai-rules.mjs";
+import { checkProject, formatProjectCheck } from "./projectCheck.mjs";
+import {
+  compareKitVersions, findPluginRoot, isLocalKitInstall, KIT_PUBLISHED_NAME, kitVersion, log, parseArgs, prompt,
+  resolveLocalCliBin,
+} from "./util.mjs";
 
 const PLUGIN_UI_PACKAGE = "@rainbow-robotics/plugin-ui";
 const PREVIEW_HOST_PACKAGE = "@rainbow-robotics/preview-host";
@@ -224,90 +229,59 @@ function updateLocalDeps(root, tag) {
   }
 }
 
-// ── legacy plugin-ui API ──────────────────────────────────────────────────────
-// plugin-ui 1.x replaced the remote-dom components and connect() bootstrap. update can't rewrite
-// UI code, so after bumping it lists what the user has to change.
-
-const LEGACY_SUBPATHS = {
-  connect: "removed — drop `connect(App)` and `export default App` instead (the host renders the entry's default export)",
-  elements: "removed — use the RB* components from @rainbow-robotics/plugin-ui/react",
-  "dist-browser": "removed — import from @rainbow-robotics/plugin-ui/react",
-};
-const LEGACY_COMPONENTS = {
-  Slider: "RBSlider",
-  Button: "RBLabelButton",
-  IconButton: "RBIconButton",
-  Text: "a plain element or RBTextLabel",
-  TextInput: "RBTextInput / RBTextField",
-  Switch: "RBSwitch",
-  Select: "RBSelectBox",
-};
-// The clause can't hold quotes or `;`, so a match can't start at an earlier import statement.
-const PLUGIN_UI_IMPORT = /import\s+([^;'"]*?)\s+from\s+["']@rainbow-robotics\/plugin-ui\/([\w-]+)["']/g;
-
-function listUiFiles(dir) {
-  return readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
-    e.isDirectory() ? listUiFiles(join(dir, e.name)) : /\.[jt]sx?$/.test(e.name) ? [join(dir, e.name)] : [],
-  );
+const PROJECT_CHECK_HEADER = "This project needs changes for the updated plugin-ui. Fix these before `muscat-pk dev` / `build`:";
+
+function reportProject(root) {
+  const lines = formatProjectCheck(checkProject(root));
+  if (!lines.length) return;
+  log.warn(PROJECT_CHECK_HEADER);
+  for (const l of lines) log.info(l);
 }
 
-// rb.toast takes one { message, type } object now; flag a string or multi-argument call.
-const TOAST_CALL = /\.toast\(([^()]*)\)/g;
-
-/** Uses of the pre-1.x plugin-ui API in the project (ui/ and vite.config), as { file, line, text }. */
-export function findLegacyUiUsage(root) {
-  const uiDir = resolve(root, "ui");
-  if (!existsSync(uiDir)) return [];
-  const found = [];
-  // The old hand-written config builds entries without their exports (connect() rendered as a side
-  // effect), so `export default App` is dropped from dist. The muscat() preset keeps it.
-  const viteConfig = ["vite.config.ts", "vite.config.mts", "vite.config.js", "vite.config.mjs"].find((f) => existsSync(resolve(root, f)));
-  if (viteConfig && !readFileSync(resolve(root, viteConfig), "utf8").includes("@rainbow-robotics/muscat-plugin-kit/vite")) {
-    found.push({
-      file: viteConfig,
-      line: 1,
-      text: 'not using the muscat() preset — the build drops the entry\'s default export. Use: import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite"; defineConfig({ plugins: [muscat()] })',
-    });
-  }
-  for (const file of listUiFiles(uiDir)) {
-    const src = readFileSync(file, "utf8");
-    const rel = relative(root, file);
-    const lineOf = (index) => src.slice(0, index).split("\n").length;
-    for (const m of src.matchAll(PLUGIN_UI_IMPORT)) {
-      const [, clause, subpath] = m;
-      if (LEGACY_SUBPATHS[subpath]) {
-        found.push({ file: rel, line: lineOf(m.index), text: `@rainbow-robotics/plugin-ui/${subpath} ${LEGACY_SUBPATHS[subpath]}` });
-      } else if (subpath === "react") {
-        const named = clause.match(/\{([\s\S]*)\}/)?.[1] ?? "";
-        for (const spec of named.split(",")) {
-          const name = spec.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0];
-          if (LEGACY_COMPONENTS[name]) {
-            found.push({ file: rel, line: lineOf(m.index), text: `${name} → ${LEGACY_COMPONENTS[name]}` });
-          }
-        }
-      }
-    }
-    for (const m of src.matchAll(TOAST_CALL)) {
-      const arg = m[1].trim();
-      if (!arg.startsWith("{") && (/^["'`]/.test(arg) || arg.includes(","))) {
-        found.push({ file: rel, line: lineOf(m.index), text: "rb.toast(message, type) → rb.toast({ message, type })" });
-      }
-    }
-    // Top-level ui/ files are the entries; the host mounts their default export.
-    if (relative(uiDir, file).split(/[\\/]/).length === 1 && !/export\s+default\b/.test(src)) {
-      found.push({ file: rel, line: 1, text: "no default export — the host renders the entry's default export" });
-    }
+/** `muscat-pk update:check` — the post-update project check, run by the freshly installed kit. */
+export async function runUpdateCheck() {
+  reportProject(findPluginRoot());
+}
+
+// Prefer the kit update just installed: it knows the plugin-ui it shipped with, this process may not.
+function checkProjectAfterUpdate(root) {
+  const localBin = resolveLocalCliBin(root);
+  let localVersion = "";
+  try {
+    localVersion = JSON.parse(readFileSync(resolve(localBin, "../../../package.json"), "utf8")).version;
+  } catch { /* no local kit */ }
+  if (localBin && localVersion && compareKitVersions(localVersion, kitVersion()) >= 0) {
+    const runtime = isBinaryMode ? "node" : process.execPath;
+    const r = spawnSync(runtime, [localBin, "update:check"], { cwd: root, stdio: "inherit" });
+    if (!r.error && r.status === 0) return;
   }
-  return found;
+  reportProject(root);
 }
 
-function reportLegacyUi(root) {
-  const found = findLegacyUiUsage(root);
-  if (!found.length) return;
-  log.warn("This project still uses the old plugin-ui API (removed in plugin-ui 1.x). Fix these before `muscat-pk dev` / `build`:");
-  for (const f of found) log.info(`  ${f.file}:${f.line}  ${f.text}`);
-  log.info("  Props changed too (e.g. RBSlider onValueChange(values[]), RBSwitch onCheckedChange(bool) instead of event.detail).");
-  log.info("  For working examples, generate a fresh project and read its ui/content.tsx:  muscat-pk new <dir>");
+// ── AI agent files ────────────────────────────────────────────────────────────
+// Projects made before `new` scaffolded these have no MCP server or agent rules, so an agent asked
+// to fix the update can't call check_project. Only missing files are written; edited ones stay.
+
+function pluginNameOf(root) {
+  try {
+    const { name } = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
+    if (typeof name === "string") return name;
+    if (name && typeof name === "object") return name.en ?? Object.values(name)[0] ?? "";
+  } catch { /* fall through */ }
+  return "";
+}
+
+function ensureAiFiles(root) {
+  const files = {
+    ".mcp.json": () => MCP_JSON,
+    "AGENTS.md": () => agentsMd({ pluginName: pluginNameOf(root) || "Plugin" }),
+    "CLAUDE.md": () => CLAUDE_MD,
+  };
+  for (const [file, content] of Object.entries(files)) {
+    if (existsSync(resolve(root, file))) continue;
+    writeFileSync(resolve(root, file), content());
+    log.ok(`${file} added (MCP server / AI agent rules)`);
+  }
 }
 
 // ── main ─────────────────────────────────────────────────────────────────────
@@ -336,7 +310,7 @@ export async function runUpdate(args = []) {
 
   // 지금 도는 게 프로젝트의 로컬 설치면 그 프로젝트만 건드린다. 이 머신의 다른
   // 프로젝트들이 쓰는 글로벌 CLI까지 같이 올리려면 --global을 명시해야 한다.
-  const runningLocal = isLocalKitInstall();
+  const runningLocal = isLocalKitInstall() || process.env.MUSCAT_PK_UPDATE_PROJECT_ONLY === "1";
 
   // 1. Update the CLI itself
   if (!runningLocal || opts.global) {
@@ -391,11 +365,17 @@ export async function runUpdate(args = []) {
     log.warn(`Structure check failed: ${err.message}`);
   }
 
+  try {
+    ensureAiFiles(root);
+  } catch (err) {
+    log.warn(`AI agent files: ${err.message}`);
+  }
+
   updateLocalDeps(root, tag);
 
   try {
-    reportLegacyUi(root);
+    checkProjectAfterUpdate(root);
   } catch (err) {
-    log.warn(`Legacy UI check failed: ${err.message}`);
+    log.warn(`Project check failed: ${err.message}`);
   }
 }

package/cli/src/util.mjs

@@ -403,6 +403,18 @@ export function isNewer(a, b) {
   return a3 > b3;
 }
 
+/** Compare "x.y.z[-dev.N]" including the dev number (a release sorts after its dev builds). <0, 0, >0. */
+export function compareKitVersions(a, b) {
+  const parse = (v) => {
+    const [rel, pre] = String(v).split("-");
+    const nums = rel.split(".").map((n) => parseInt(n, 10) || 0);
+    return [...nums, pre === undefined ? Infinity : parseInt(pre.split(".").pop(), 10) || 0];
+  };
+  const pa = parse(a), pb = parse(b);
+  for (let i = 0; i < 4; i++) if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
+  return 0;
+}
+
 /**
  * Non-blocking check for a newer published kit. Prints an update suggestion if
  * one exists. Fails silently when offline. Honors `RB_REGISTRY` and is skipped

package/cli/storybook-dist/project.json

@@ -1 +1 @@
-{"generatedAt":1792689204059,"userSince":1750997484097,"hasCustomBabel":false,"hasCustomWebpack":false,"hasStaticDirs":false,"hasStorybookEslint":true,"refCount":0,"testPackages":{"@vitest/browser":"3.2.4","@vitest/coverage-v8":"3.2.4","playwright":"1.59.1","vitest":"3.2.4"},"hasRouterPackage":false,"monorepo":"Turborepo","packageManager":{"type":"yarn","version":"berry","agent":"yarn@berry"},"preview":{"usesGlobals":false},"framework":{"name":"@storybook/react-vite","options":{}},"builder":"@storybook/builder-vite","renderer":"@storybook/react","portableStoriesFileCount":0,"applicationFileCount":0,"storybookVersion":"8.6.18","storybookVersionSpecifier":"^8.6.4","language":"typescript","storybookPackages":{"@chromatic-com/storybook":{"version":"3.2.7"},"@storybook/addon-essentials":{"version":"8.6.18"},"@storybook/addon-links":{"version":"8.6.18"},"@storybook/addon-onboarding":{"version":"8.6.18"},"@storybook/addon-themes":{"version":"8.6.18"},"@storybook/blocks":{"version":"8.6.18"},"@storybook/experimental-addon-test":{"version":"8.6.18"},"@storybook/react":{"version":"8.6.18"},"@storybook/react-vite":{"version":"8.6.18"},"@storybook/test":{"version":"8.6.18"},"@storybook/theming":{"version":"8.6.18"},"eslint-plugin-storybook":{"version":"0.11.6"},"storybook":{"version":"8.6.18"},"storybook-addon-react-docgen":{"version":"1.2.44"}},"addons":{"$SNIP/node_modules/@storybook/addon-links":{"version":null},"$SNIP/node_modules/@storybook/addon-essentials":{"version":null},"$SNIP/node_modules/@chromatic-com/storybook":{"version":null},"$SNIP/node_modules/@storybook/addon-themes":{"version":null},"$SNIP/node_modules/@storybook/experimental-addon-test":{"version":null}}}
+{"generatedAt":1792691105012,"userSince":1750997484097,"hasCustomBabel":false,"hasCustomWebpack":false,"hasStaticDirs":false,"hasStorybookEslint":true,"refCount":0,"testPackages":{"@vitest/browser":"3.2.4","@vitest/coverage-v8":"3.2.4","playwright":"1.59.1","vitest":"3.2.4"},"hasRouterPackage":false,"monorepo":"Turborepo","packageManager":{"type":"yarn","version":"berry","agent":"yarn@berry"},"preview":{"usesGlobals":false},"framework":{"name":"@storybook/react-vite","options":{}},"builder":"@storybook/builder-vite","renderer":"@storybook/react","portableStoriesFileCount":0,"applicationFileCount":0,"storybookVersion":"8.6.18","storybookVersionSpecifier":"^8.6.4","language":"typescript","storybookPackages":{"@chromatic-com/storybook":{"version":"3.2.7"},"@storybook/addon-essentials":{"version":"8.6.18"},"@storybook/addon-links":{"version":"8.6.18"},"@storybook/addon-onboarding":{"version":"8.6.18"},"@storybook/addon-themes":{"version":"8.6.18"},"@storybook/blocks":{"version":"8.6.18"},"@storybook/experimental-addon-test":{"version":"8.6.18"},"@storybook/react":{"version":"8.6.18"},"@storybook/react-vite":{"version":"8.6.18"},"@storybook/test":{"version":"8.6.18"},"@storybook/theming":{"version":"8.6.18"},"eslint-plugin-storybook":{"version":"0.11.6"},"storybook":{"version":"8.6.18"},"storybook-addon-react-docgen":{"version":"1.2.44"}},"addons":{"$SNIP/node_modules/@storybook/addon-links":{"version":null},"$SNIP/node_modules/@storybook/addon-essentials":{"version":null},"$SNIP/node_modules/@chromatic-com/storybook":{"version":null},"$SNIP/node_modules/@storybook/addon-themes":{"version":null},"$SNIP/node_modules/@storybook/experimental-addon-test":{"version":null}}}

package/cli/templates/common/README.md

@@ -1132,6 +1132,10 @@ letting it guess. `muscat-pk mcp` is an MCP server exposing:
   backend) classes and signatures; with `lang: "cpp"`, the C++ SDK headers
   (`rainbow-rb-sdk-dev`, read out of the `muscat-pk` cpp dev image — build it
   once with `muscat-pk dev:back`).
+- `check_project` — what this project must change for the plugin-ui it has
+  installed (old APIs such as `connect(App)` or `Slider`, a `vite.config` without
+  the `muscat()` preset, `tsc` errors), the same list `muscat-pk update` prints.
+  Ask the assistant to fix the project after an update; it re-checks until clean.
 
 **Browse the components live** with `muscat-pk storybook`.
 

package/cli/templates/readme-cpp/README.md

@@ -898,6 +898,10 @@ letting it guess. `muscat-pk mcp` is an MCP server exposing:
   backend) classes and signatures; with `lang: "cpp"`, the C++ SDK headers
   (`rainbow-rb-sdk-dev`, read out of the `muscat-pk` cpp dev image — build it
   once with `muscat-pk dev:back`).
+- `check_project` — what this project must change for the plugin-ui it has
+  installed (old APIs such as `connect(App)` or `Slider`, a `vite.config` without
+  the `muscat()` preset, `tsc` errors), the same list `muscat-pk update` prints.
+  Ask the assistant to fix the project after an update; it re-checks until clean.
 
 **Browse the components live** with `muscat-pk storybook`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-robotics/muscat-plugin-kit",
-  "version": "1.10.2-dev.1",
+  "version": "1.10.2-dev.3",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -52,8 +52,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@rainbow-robotics/plugin-ui": "1.10.2-dev.1",
-    "@rainbow-robotics/preview-host": "1.10.2-dev.1",
+    "@rainbow-robotics/plugin-ui": "1.10.2-dev.3",
+    "@rainbow-robotics/preview-host": "1.10.2-dev.3",
     "@types/react": "^19.0.10",
     "postcss": "^8.5.8",
     "typescript": "^5.8.0",

package/cli/templates/common/.mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "muscat": {
-      "command": "muscat-pk",
-      "args": ["mcp"]
-    }
-  }
-}