@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.9 → 0.10.1-dev.1

package/cli/src/ports.mjs

@@ -0,0 +1,193 @@
+// Port contract helpers for plugin back ends.
+import { spawnSync } from "node:child_process";
+import { usesHostNetwork } from "./zenohDev.mjs";
+
+export const PLUGIN_PORT_MIN = 28600;
+export const PLUGIN_PORT_MAX = 28999;
+export const MEDIA_PORTS = [8554, 8889, 8189]; // MediaMTX: RTSP publish, WebRTC, WebRTC media
+export const INTERNAL_DEV_PORTS = new Set([10000, ...MEDIA_PORTS]);
+
+export function mediaPortFlags() {
+  return [
+    "-p", "127.0.0.1:8554:8554", "-p", "127.0.0.1:8889:8889",
+    "-p", "127.0.0.1:8189:8189/udp", "-p", "127.0.0.1:8189:8189/tcp",
+  ];
+}
+export const RESERVED_BACKEND_PORTS = new Map([
+  [502, "Modbus TCP"],
+  [4840, "OPC-UA"],
+  [10000, "Muscat plugin gateway"],
+  [2222, "EtherNet/IP Implicit"],
+  [30004, "RTDE"],
+  [34964, "ProfiNET"],
+  [44818, "EtherNet/IP Explicit"],
+  [50051, "gRPC"],
+]);
+export const RESERVED_BACKEND_PORT_RANGES = [
+  { from: 5170, to: 5179, name: "UI 517x servers" },
+  { from: 8000, to: 8999, name: "Muscat/internal 8000 range" },
+  { from: 50000, to: 50005, name: "robot TCP/UDP ASCII and REST interfaces" },
+];
+
+function reservedPortReason(port) {
+  if (RESERVED_BACKEND_PORTS.has(port)) return RESERVED_BACKEND_PORTS.get(port);
+  const range = RESERVED_BACKEND_PORT_RANGES.find((item) => port >= item.from && port <= item.to);
+  if (!range) return null;
+  return `${range.name} (${range.from}-${range.to})`;
+}
+
+// function isPluginManagedPort(port) {
+//   return reservedPortReason(port) || (port >= PLUGIN_PORT_MIN && port <= PLUGIN_PORT_MAX);
+// }
+
+function isInt(value) {
+  return Number.isInteger(value);
+}
+
+function validatePort(port, field, errors) {
+  if (!isInt(port)) {
+    errors.push(`${field}: must be a port number`);
+    return;
+  }
+  if (port < 1 || port > 65535) {
+    errors.push(`${field}: port must be between 1 and 65535`);
+    return;
+  }
+  const reserved = reservedPortReason(port);
+  if (reserved) {
+    errors.push(`${field}: ${port} is reserved for ${reserved}`);
+    return;
+  }
+  if (port < PLUGIN_PORT_MIN || port > PLUGIN_PORT_MAX) {
+    errors.push(
+      `${field}: external plugin backend ports must be within ${PLUGIN_PORT_MIN}-${PLUGIN_PORT_MAX}`,
+    );
+  }
+}
+
+export function normalizePorts(ports, errors = []) {
+  if (ports === undefined || ports === null) return [];
+  if (!Array.isArray(ports)) {
+    errors.push(`"ports" must be an array`);
+    return [];
+  }
+  if (ports.length === 0) {
+    errors.push(`"ports" must not be empty when provided`);
+    return [];
+  }
+
+  const normalized = [];
+  const seen = new Set();
+  ports.forEach((port, i) => {
+    validatePort(port, `ports[${i}]`, errors);
+    if (!isInt(port)) return;
+    if (seen.has(port)) {
+      errors.push(`"ports" entries must be unique (duplicate: ${port})`);
+      return;
+    }
+    seen.add(port);
+    normalized.push(port);
+  });
+
+  return normalized;
+}
+
+export function validatePorts(ports, errors) {
+  normalizePorts(ports, errors);
+}
+
+export function manifestPortRanges(manifest) {
+  return normalizePorts(manifest?.ports, []);
+}
+
+export function formatPortRange(range) {
+  return String(range);
+}
+
+export function formatPortRanges(ranges) {
+  return ranges.map(formatPortRange).join(", ");
+}
+
+export function portInRanges(port, ranges) {
+  return ranges.includes(port);
+}
+
+export function portEnvFlags(ranges) {
+  if (ranges.length === 0) return [];
+  return ["-e", `RB_PLUGIN_PORTS=${ranges.map(formatPortRange).join(",")}`];
+}
+
+/**
+ * `docker run -p` flags for the plugin's declared ports, TCP and UDP on every host interface like
+ * on the robot, so LAN devices (e.g. a Meta Quest streaming UDP) reach the backend. Native Linux
+ * without a local Muscat uses --network host instead. Only valid on the container that owns the netns.
+ */
+export function publishPortFlags(ranges = []) {
+  return ranges.flatMap((port) => ["-p", `${port}:${port}`, "-p", `${port}:${port}/udp`]);
+}
+
+// Skips OS-assigned loopback listeners (127.0.0.1:0, e.g. the SDK's Zenoh session).
+function listeningTcpPorts(container) {
+  const script = `
+read -r eph_lo eph_hi < /proc/sys/net/ipv4/ip_local_port_range 2>/dev/null || { eph_lo=32768; eph_hi=60999; }
+for f in /proc/net/tcp /proc/net/tcp6; do
+  [ -r "$f" ] || continue
+  tail -n +2 "$f" | while read -r sl local_address rem_address st rest; do
+    [ "$st" = "0A" ] || continue
+    hex_ip="\${local_address%%:*}"
+    port=$((0x\${local_address##*:}))
+    case "$hex_ip" in
+      0100007F|00000000000000000000000001000000)
+        [ "$port" -ge "$eph_lo" ] && [ "$port" -le "$eph_hi" ] && continue ;;
+    esac
+    echo "$port"
+  done
+done | sort -n -u
+`;
+  const r = spawnSync("docker", ["exec", container, "bash", "-lc", script], {
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return [];
+  return String(r.stdout || "")
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((v) => Number(v))
+    .filter((v) => Number.isInteger(v));
+}
+
+export function startPortContractMonitor({ container, ranges, log, intervalMs = 1000, allow = [] }) {
+  // Under --network host (or a local Muscat container's netns) /proc/net/tcp shows every
+  // host/robot service port, not just the plugin's — the contract can't be enforced.
+  if (usesHostNetwork() || process.env.MUSCAT_PK_MUSCAT_CONTAINER) return () => false;
+  const declared = ranges ?? [];
+  // muscat-pk's own dev plumbing shares this netns — not the plugin's doing.
+  const ignored = new Set([...INTERNAL_DEV_PORTS, ...allow.map(Number).filter(Number.isInteger)]);
+  let reported = false;
+  const timer = setInterval(() => {
+    // Every listening port that isn't declared is a violation — a port outside
+    // 28600-28999 can't be declared at all, so it must not be opened either.
+    // Otherwise it silently escapes both this check and rby2's install-time
+    // conflict check, and only collides once it's on a robot.
+    const unexpected = listeningTcpPorts(container)
+      .filter((port) => !ignored.has(port))
+      .filter((port) => !portInRanges(port, declared));
+    if (unexpected.length === 0) return;
+
+    clearInterval(timer);
+    reported = true;
+    const declaredText = declared.length > 0 ? formatPortRanges(declared) : "(none)";
+    log.error(
+      `backend opened undeclared TCP port(s): ${unexpected.join(", ")}. ` +
+      `Every listening port must be in manifest.json "ports" within ${PLUGIN_PORT_MIN}-${PLUGIN_PORT_MAX}. ` +
+      `Declared: ${declaredText}`,
+    );
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    process.exit(1);
+  }, intervalMs);
+  timer.unref?.();
+
+  return () => {
+    clearInterval(timer);
+    return reported;
+  };
+}

package/cli/src/programCommands.mjs

@@ -0,0 +1,327 @@
+// Built-in Program page commands for the `mcp` command's list_program_commands
+// tool. The source of truth is nexus's program.c.tsx; it imports React/host
+// code, so instead of running it we read its object literals with the
+// TypeScript AST. prepack stages the result as JSON so an external install
+// (no monorepo) gets the same list.
+import ts from "typescript";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { kitRoot } from "./util.mjs";
+
+const REPO_PROGRAM_SRC = resolve(kitRoot, "../..", "apps/web/nexus/src/constants/program.c.tsx");
+export const SHIPPED_PROGRAM_COMMANDS = resolve(kitRoot, "cli/program-commands.json");
+
+// Exported list name → robot category the Program page shows it for.
+const LISTS = {
+  COMMON_PROGRAM_COMMAND_LIST: "common",
+  MANIPULATE_PROGRAM_COMMAND_LIST: "manipulate",
+  AMR_PROGRAM_COMMAND_LIST: "amr",
+  RBY1_PROGRAM_COMMAND_LIST: "rby1",
+};
+// Reached through the Thread modal, not the palette list (nexus CALL_EVENT_PLUGIN_COMMAND).
+const EXTRA = { CALL_EVENT_THREAD_PROGRAM_COMMAND: "common" };
+const RULE_KEYS = [
+  "allowChildren", "allowParents", "notAllowChildren", "childrenCommand", "requireChildren",
+  "requireParent", "fixChildren", "syncGroupId", "groupFirstItem", "groupLastItem", "isStrict",
+  "disableCopy", "disableDelete", "disabled",
+];
+
+const UNRESOLVED = Symbol("unresolved");
+
+function propName(name, sf) {
+  return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : name.getText(sf);
+}
+
+// Best-effort literal evaluation. Anything that needs the live robot or host
+// (fetch*, uniqueId(), imported option tables) comes back as its source text
+// in angle brackets, so the agent sees what the value depends on.
+function makeEvaluator(sf, fileScope) {
+  const raw = (node) => `<${node.getText(sf).replace(/\s+/g, " ")}>`;
+
+  function evalFn(fn, scope) {
+    if (!ts.isBlock(fn.body)) return evalNode(fn.body, scope);
+    const local = new Map(scope);
+    let result = UNRESOLVED;
+    for (const st of fn.body.statements) {
+      if (ts.isVariableStatement(st)) {
+        for (const d of st.declarationList.declarations) {
+          if (ts.isIdentifier(d.name) && d.initializer) local.set(d.name.text, evalNode(d.initializer, local));
+        }
+      } else if (ts.isReturnStatement(st) && st.expression) {
+        result = evalNode(st.expression, local);
+      }
+    }
+    return result === UNRESOLVED ? raw(fn) : result;
+  }
+
+  function evalNode(node, scope) {
+    if (!node) return null;
+    if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isAwaitExpression(node)) {
+      return evalNode(node.expression, scope);
+    }
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+    if (ts.isNumericLiteral(node)) return Number(node.text);
+    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(node.operand)) {
+      return -Number(node.operand.text);
+    }
+    if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+    if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+    if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+    if (ts.isIdentifier(node)) {
+      if (node.text === "undefined") return null;
+      if (scope.has(node.text)) return scope.get(node.text);
+      const decl = fileScope.get(node.text);
+      return decl ? evalNode(decl, scope) : raw(node);
+    }
+    if (ts.isArrayLiteralExpression(node)) {
+      return node.elements.flatMap((el) => {
+        if (!ts.isSpreadElement(el)) return [evalNode(el, scope)];
+        const v = evalNode(el.expression, scope);
+        return Array.isArray(v) ? v : [raw(el)];
+      });
+    }
+    if (ts.isObjectLiteralExpression(node)) {
+      const out = {};
+      for (const p of node.properties) {
+        if (ts.isSpreadAssignment(p)) {
+          const v = evalNode(p.expression, scope);
+          if (v && typeof v === "object" && !Array.isArray(v)) Object.assign(out, v);
+        } else if (ts.isPropertyAssignment(p)) {
+          out[propName(p.name, sf)] = evalNode(p.initializer, scope);
+        } else if (ts.isShorthandPropertyAssignment(p)) {
+          out[p.name.text] = evalNode(p.name, scope);
+        }
+      }
+      return out;
+    }
+    if (ts.isPropertyAccessExpression(node)) {
+      const obj = evalNode(node.expression, scope);
+      return obj && typeof obj === "object" && Object.hasOwn(obj, node.name.text) ? obj[node.name.text] : raw(node);
+    }
+    if (ts.isTemplateExpression(node)) {
+      let s = node.head.text;
+      for (const span of node.templateSpans) {
+        const v = evalNode(span.expression, scope);
+        if (typeof v === "string" && v.startsWith("<")) return raw(node);
+        s += String(v) + span.literal.text;
+      }
+      return s;
+    }
+    // (() => ({...}))() — an IIFE building the default data.
+    if (ts.isCallExpression(node) && node.arguments.length === 0) {
+      const callee = ts.isParenthesizedExpression(node.expression) ? node.expression.expression : node.expression;
+      if (ts.isArrowFunction(callee) || ts.isFunctionExpression(callee)) return evalFn(callee, scope);
+    }
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) return evalFn(node, scope);
+    return raw(node);
+  }
+
+  return evalNode;
+}
+
+export function extractProgramCommands(srcPath = REPO_PROGRAM_SRC) {
+  const sf = ts.createSourceFile(srcPath, readFileSync(srcPath, "utf8"), ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const fileScope = new Map();
+  for (const st of sf.statements) {
+    if (!ts.isVariableStatement(st)) continue;
+    for (const d of st.declarationList.declarations) {
+      if (ts.isIdentifier(d.name) && d.initializer) fileScope.set(d.name.text, d.initializer);
+    }
+  }
+  const evalNode = makeEvaluator(sf, fileScope);
+
+  const toCommand = (node, category) => {
+    // A list element is an object literal, a const name, or { ...CONST, data: {...} }.
+    const props = new Map();
+    const collect = (n) => {
+      if (ts.isIdentifier(n) && fileScope.has(n.text)) return collect(fileScope.get(n.text));
+      if (!ts.isObjectLiteralExpression(n)) return;
+      for (const p of n.properties) {
+        if (ts.isSpreadAssignment(p)) collect(p.expression);
+        else if (ts.isPropertyAssignment(p)) props.set(propName(p.name, sf), p.initializer);
+      }
+    };
+    collect(node);
+    if (!props.has("command")) return null;
+
+    const value = (key) => (props.has(key) ? evalNode(props.get(key), new Map()) : undefined);
+    const factory = props.get("factoryDataFn");
+    const data = value("data") ?? (factory ? evalNode(factory, new Map()) : undefined);
+    const rules = Object.fromEntries(RULE_KEYS.map((k) => [k, value(k)]).filter(([, v]) => v !== undefined));
+    return {
+      command: value("command"),
+      category,
+      label: value("label"),
+      method: data?.method ?? value("command"),
+      funcName: data?.funcName ?? null,
+      postFuncName: data?.postFuncName ?? null,
+      defaultArgs: data?.args ?? null,
+      defaultData: data ?? null,
+      rules,
+      // factoryDataFn: defaults are computed when the step is added (group/task ids, live robot pose, tool list, ...).
+      computedDefaults: !!factory,
+      // confirmModal: the Program page asks the user something (type, count, program) before adding it.
+      asksOnInsert: props.has("confirmModal"),
+    };
+  };
+
+  const out = [];
+  const seen = new Set();
+  for (const [name, category] of Object.entries({ ...LISTS, ...EXTRA })) {
+    const init = fileScope.get(name);
+    if (!init) continue;
+    const nodes = ts.isArrayLiteralExpression(init) ? init.elements : [init];
+    for (const n of nodes) {
+      const cmd = toCommand(n, category);
+      if (cmd && !seen.has(cmd.command)) {
+        seen.add(cmd.command);
+        out.push(cmd);
+      }
+    }
+  }
+  return out;
+}
+
+export function loadProgramCommands() {
+  if (existsSync(REPO_PROGRAM_SRC)) return extractProgramCommands();
+  if (existsSync(SHIPPED_PROGRAM_COMMANDS)) return JSON.parse(readFileSync(SHIPPED_PROGRAM_COMMANDS, "utf8"));
+  throw new Error(`Program command list not found (${SHIPPED_PROGRAM_COMMANDS}) — reinstall muscat-plugin-kit.`);
+}
+
+// prepack: stage the list so it ships with the kit. Outside the monorepo the
+// already-staged file is kept.
+export function stageProgramCommands() {
+  if (!existsSync(REPO_PROGRAM_SRC)) return;
+  writeFileSync(SHIPPED_PROGRAM_COMMANDS, JSON.stringify(extractProgramCommands(), null, 2) + "\n");
+}
+
+export const DEFAULT_COMMON_URL = "http://localhost:3000";
+
+export const PROGRAM_API_GUIDE = `# Building a Muscat program from a plugin
+
+Commands: list_program_commands gives every built-in command (name, default args, funcName,
+nesting rules). A step is one command instance; nesting goes through children / parentStepId.
+
+## A. From plugin UI: rb.program (edits the program open on the Program page)
+
+\`\`\`ts
+const rb = useRb();
+const catalog = await rb.program.getCatalog(scope);    // commands of the loaded robot, incl. other plugins' commands
+const steps = await rb.program.getSteps(scope);        // current main step tree
+await rb.program.setSteps([                            // replaces the main tree (unsaved — the user presses Save)
+  { command: "MoveJ", children: [{ command: "Point", args: { tar_values: [0, 0, 90, 0, 90, 0, 0] } }] },
+  { command: "Wait", args: { second: 1 } },
+  { command: "Repeat", args: { count: 3 }, children: [{ command: "Wait", args: { second: 0.5 } }] },
+  { command: "SubTask", fields: { subTaskType: "INSERT", subTaskScriptPath: "..." } },
+], scope);
+const pointDefaults = await rb.program.getCommandDefaults?.("Point", scope); // computedDefaults commands (ids, live robot state)
+\`\`\`
+
+- Step shape: { command, args?, summary?, fields?, children? }. The host fills the rest from the command
+  defaults: args = default args merged with yours, robot_model filled with the loaded robot, name = the
+  command label, funcName/postFuncName, nesting rules, fresh stepIds.
+- fields only accepts subTaskType, subTaskScriptPath, name, memo, funcName, postFuncName.
+- scope = { taskId, robotModel }: a program.monitor plugin gets it as rb.data; without it the first main task is used.
+- Unknown command names throw ("unknown command: X").
+
+## B. From a backend or external tool: common REST API
+
+Base: http://<robot>:3000/common (robot backend: http://127.0.0.1:3000, muscat-pk dev backend container on
+macOS/Windows: http://host.docker.internal:3000). The same API is reachable over TCP/MQTT/Socket.IO/WebRTC
+with topic common/<path> (e.g. common/program/steps/upsert) and the request body as data.
+
+1. Create: POST /program/create { name, repeatCnt } → { program, mainTasks[] } — take program.programId and the
+   main task's taskId (one main task per robot component, see mainTasks[].robotModel).
+2. Steps: POST /program/steps/upsert { steps: [...] } with a FLAT list. Each step needs
+   stepId (unique string), taskId, programId, name, method, order. Also send what the command defines:
+   funcName / postFuncName / args, and its rules (allowChildren, requireChildren, groupId, ...).
+   - name is required (422 without it). The Program page stores the command label, e.g. "program.button.wait"
+     (label in list_program_commands), not the display text.
+   - method = the command name ("MoveJ", "Point", "Wait", ...).
+   - Nesting: a child's parentStepId = parent's stepId. order = pre-order (DFS) index over the whole tree,
+     starting at 0 — the parent before its children.
+   - Args like "$parent.move_type" are resolved from the parent step at run time; keep them as given.
+   - If/ElseIf/Else: sibling Condition steps sharing one groupId, args.condition_type "If" | "ElseIf" | "Else",
+     names "program.button.condition" | "program.button.elif" | "program.button.else". Switch and its Case
+     children share one groupId too.
+   - robot_model "" in default args → set it to the task's robotModel.
+3. Read back: GET /program/main-tasks/{programId}, GET /program/steps/{taskId}, GET /program/step/{stepId}.
+4. Delete steps: DELETE /program/steps/delete. Edit / clone / delete program: PUT /program/edit,
+   POST /program/clone, DELETE /program/delete/{programId}. List: GET /programs.
+5. Run (moves the robot): POST /program/load { programId } then POST /program/start { programId };
+   /program/pause | resume | stop with the same body. State: GET /program/current/state,
+   GET /program/task/{taskId}/step-state, GET /program/executor/state, variables: GET /program/{robot_model}/variables.
+6. Export / import as a script: GET /program/export/{programId or name} (.zip, or .py with taskId),
+   POST /program/import/preview, POST /program/import.
+
+Exact request/response fields come from the live OpenAPI: call get_program_api with path, e.g. "/program/steps/upsert".
+
+## Manipulator Point notes
+
+- tar_values always has 7 values. input_method 0 = absolute target. Joint targets (tar_frame -1) go under MoveJ/MoveJB,
+  Cartesian (tar_frame 0) under MoveL/MoveLB. PinPoint (Cartesian pin) under MoveL, PinJoint under MoveJ.
+- Relative move: input_method 1 + a reference point (pin name or RB_POINT_REF) + 7 offsets.
+`;
+
+function compactSchema(schema, spec, depth = 0) {
+  if (!schema) return "any";
+  if (schema.$ref) {
+    const name = schema.$ref.split("/").pop();
+    if (depth > 3) return name;
+    return compactSchema(spec.components?.schemas?.[name], spec, depth + 1);
+  }
+  const alt = schema.anyOf ?? schema.oneOf;
+  if (alt) return alt.map((s) => compactSchema(s, spec, depth)).map((s) => (typeof s === "string" ? s : JSON.stringify(s))).join(" | ");
+  if (schema.enum) return schema.enum.map((v) => JSON.stringify(v)).join(" | ");
+  if (schema.type === "array") return [compactSchema(schema.items, spec, depth)];
+  if (schema.type === "object" || schema.properties) {
+    if (!schema.properties) return "object";
+    const req = new Set(schema.required ?? []);
+    return Object.fromEntries(
+      Object.entries(schema.properties).map(([k, v]) => [req.has(k) ? k : `${k}?`, compactSchema(v, spec, depth)]),
+    );
+  }
+  return schema.type ?? "any";
+}
+
+// Live endpoint list / schema from the common service's OpenAPI.
+export async function describeProgramApi(path, baseUrl = DEFAULT_COMMON_URL) {
+  const url = `${baseUrl.replace(/\/$/, "")}/common/openapi.json`;
+  let spec;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    spec = await res.json();
+  } catch (e) {
+    return `Could not read ${url} (${e.message}). Start Muscat (muscat-pk dev) or pass url with the robot's address, e.g. "http://192.168.0.10:3000".`;
+  }
+  const paths = spec.paths ?? {};
+  if (!path) {
+    return Object.entries(paths)
+      .filter(([p]) => p.startsWith("/program"))
+      .flatMap(([p, ops]) => Object.entries(ops).map(([m, op]) => `${m.toUpperCase()} /common${p} — ${(op.summary ?? "").trim()}`))
+      .join("\n");
+  }
+  const key = path.replace(/^\/common/, "");
+  const ops = paths[key];
+  if (!ops) {
+    const near = Object.keys(paths).filter((p) => p.includes(key.split("/").filter(Boolean).pop() ?? ""));
+    return `No endpoint "${path}".${near.length ? ` Similar: ${near.slice(0, 10).join(", ")}` : ""}`;
+  }
+  return Object.entries(ops)
+    .map(([m, op]) => {
+      const body = op.requestBody?.content?.["application/json"]?.schema;
+      const params = (op.parameters ?? []).map((p) => `${p.name} (${p.in}${p.required ? ", required" : ""}): ${JSON.stringify(compactSchema(p.schema, spec))}`);
+      const ok = op.responses?.["200"]?.content?.["application/json"]?.schema;
+      return [
+        `${m.toUpperCase()} /common${key} — ${(op.summary ?? "").trim()}`,
+        op.description ? op.description.trim() : null,
+        params.length ? `Parameters:\n  ${params.join("\n  ")}` : null,
+        body ? `Request body (? = optional):\n${JSON.stringify(compactSchema(body, spec), null, 2)}` : null,
+        ok ? `Response 200:\n${JSON.stringify(compactSchema(ok, spec), null, 2)}` : null,
+      ]
+        .filter(Boolean)
+        .join("\n\n");
+    })
+    .join("\n\n---\n\n");
+}

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>",
+  ];
+}