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

package/cli/src/ai-rules.mjs

@@ -69,7 +69,8 @@ ${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.`;
+Backend, manifest and SDK questions: search_rb_sdk, list_rb_sdk, get_rb_sdk_api.
+Program commands and building/running programs (rb.program, /common/program REST): list_program_commands, get_program_api.`;
 
 // AGENTS.md (Codex, Cursor, Gemini CLI, Copilot …). CLAUDE.md imports it with `@AGENTS.md`.
 // The backend type is not named: `muscat-pk type change` would leave it stale.

package/cli/src/devUi.mjs

@@ -196,6 +196,17 @@ export async function runDevUi(args = []) {
   const readyFile = resolve(outDir, "plugin-dev-port.json");
   rmSync(readyFile, { force: true });
   const sharedRuntimeBase = `http://localhost:${port}/plugin-shared`;
+  // Registered before the first spawn: a Ctrl+C that arrived during `dev`'s synchronous backend build
+  // is handled only now, and a process started after it never got the signal itself.
+  const procs = [];
+  const stopProcs = () => {
+    for (const p of procs) if (p.exitCode === null) p.kill();
+  };
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
+    process.once(signal, () => {
+      stopProcs();
+      process.exit(130);
+    });
   const viteProc = spawnPluginDevServer(
     pluginRoot,
     node,
@@ -203,6 +214,7 @@ export async function runDevUi(args = []) {
     readyFile,
     sharedRuntimeBase,
   );
+  if (viteProc) procs.push(viteProc);
   let devPort = DEV_PLUGIN_PORT;
 
   if (!viteProc) {
@@ -227,6 +239,7 @@ export async function runDevUi(args = []) {
         stdio: "inherit",
         env: { ...process.env, VITE_PLUGIN_PREVIEW: "true" },
       });
+      procs.push(p);
       p.on("exit", (c) => (c === 0 ? res() : rej(new Error("preview-host build failed"))));
     });
   }
@@ -247,6 +260,7 @@ export async function runDevUi(args = []) {
     // preview-host only prints its address and paths; the "UI →" line below says what matters.
     { stdio: ["inherit", "ignore", "inherit"] },
   );
+  procs.push(child);
 
   for (let i = 0; i < 50 && !(await fetch(`http://localhost:${port}/`).then(() => true, () => false)); i++)
     await new Promise((r) => setTimeout(r, 200));
@@ -254,18 +268,8 @@ export async function runDevUi(args = []) {
   // Only for a person at a terminal — not CI, scripts or `--no-open`.
   if (process.stdout.isTTY && !process.env.CI && !parsed["no-open"]) openBrowser(`http://localhost:${port}`);
 
-  let cleaned = false;
-  const cleanup = () => {
-    if (cleaned) return;
-    cleaned = true;
-    if (viteProc && !viteProc.killed && viteProc.exitCode === null) viteProc.kill();
-    if (!child.killed && child.exitCode === null) child.kill();
-  };
-  process.once("SIGINT", cleanup);
-  process.once("SIGTERM", cleanup);
-  process.once("SIGHUP", cleanup);
   child.on("exit", (code) => {
-    cleanup();
+    stopProcs();
     process.exit(code ?? 0);
   });
 }

package/cli/src/mcp.mjs

@@ -18,6 +18,10 @@
 //                            rainbow-rb-sdk-dev apt package out of the cpp dev image).
 //   - get_rb_sdk_api         signature + docstring for an rb_sdk class/function.
 //
+//   Program page (nexus program.c.tsx + common OpenAPI):
+//   - list_program_commands  built-in commands, default args, nesting rules.
+//   - get_program_api        rb.program / REST guide + live endpoint schemas.
+//
 // Add to an MCP client config, e.g. Claude Code's .mcp.json:
 //   { "mcpServers": { "muscat": { "command": "muscat-pk", "args": ["mcp"] } } }
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -45,6 +49,7 @@ 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";
+import { describeProgramApi, loadProgramCommands, PROGRAM_API_GUIDE } from "./programCommands.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.
@@ -791,6 +796,80 @@ export async function runMcp() {
     },
   );
 
+  /* --- program commands / program API --- */
+
+  server.registerTool(
+    "list_program_commands",
+    {
+      title: "List built-in Muscat program commands",
+      description:
+        "List the built-in commands of the Muscat Program page (from nexus program.c.tsx): Wait, Repeat, " +
+        "Condition, Switch/Case, Thread, Script, MoveJ/MoveL + Point, Gripper, AMR Goal, ... with their " +
+        "category (common | manipulate | amr | rby1), funcName, default args and nesting rules " +
+        "(allowChildren/allowParents/notAllowChildren/requireChildren/requireParent). Pass `command` for one " +
+        "command's full defaults. Use it to build steps for rb.program.setSteps or POST /common/program/steps/upsert " +
+        "(see get_program_api), or to fill a program.panel commandInfo's allowParents/allowChildren with real names. " +
+        "Values in <angle brackets> are computed when the step is added (live robot state, ids).",
+      inputSchema: {
+        command: z.string().optional().describe('Command name, e.g. "Point" or "Repeat"'),
+        category: z.enum(["common", "manipulate", "amr", "rby1"]).optional().describe("Filter by robot category"),
+      },
+    },
+    async ({ command, category }) => {
+      const all = loadProgramCommands();
+      if (command) {
+        const found = all.find((c) => c.command.toLowerCase() === command.toLowerCase());
+        if (!found) {
+          const hints = suggestExports(command, all.map((c) => c.command));
+          const text = `No program command "${command}".${hints.length ? ` Did you mean: ${hints.join(", ")}?` : ""} Call list_program_commands without command for the list.`;
+          return { isError: true, content: [{ type: "text", text }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(found, null, 2) }] };
+      }
+      const lines = all
+        .filter((c) => !category || c.category === category)
+        .map((c) => {
+          const r = c.rules;
+          const notes = [
+            c.funcName && `func ${c.funcName}${c.postFuncName ? ` → ${c.postFuncName}` : ""}`,
+            r.allowChildren && `children: ${r.allowChildren.join(",")}`,
+            r.allowParents && `parents: ${r.allowParents.join(",")}`,
+            r.requireChildren && "needs children",
+            r.requireParent && "needs parent",
+            r.notAllowChildren && `no children: ${r.notAllowChildren.join(",")}`,
+            r.disabled === true && "disabled",
+            c.computedDefaults && "computed defaults",
+            c.asksOnInsert && "asks on insert",
+            c.defaultArgs && `args: ${Object.keys(c.defaultArgs).join(",")}`,
+          ].filter(Boolean);
+          return `${c.command} [${c.category}] ${c.label}${notes.length ? ` — ${notes.join("; ")}` : ""}`;
+        });
+      return { content: [{ type: "text", text: `${lines.join("\n")}\n\nCall again with command for full default args.` }] };
+    },
+  );
+
+  server.registerTool(
+    "get_program_api",
+    {
+      title: "How to build and run a Muscat program from a plugin",
+      description:
+        "How a plugin creates, edits, saves and runs Muscat programs: rb.program.getCatalog/getSteps/setSteps/" +
+        "getCommandDefaults from plugin UI, and the common REST API (/common/program/create, /program/steps/upsert " +
+        "step fields and ordering, load/start/stop, export/import). Without `path` returns the guide plus the live " +
+        "/program endpoint list; with `path` (e.g. \"/program/steps/upsert\") returns that endpoint's request/response " +
+        "schema from the running Muscat's OpenAPI (default http://localhost:3000; pass `url` for a robot).",
+      inputSchema: {
+        path: z.string().optional().describe('Endpoint path, e.g. "/program/steps/upsert"'),
+        url: z.string().optional().describe('Muscat base URL, default "http://localhost:3000"'),
+      },
+    },
+    async ({ path, url }) => {
+      const live = await describeProgramApi(path, url);
+      const text = path ? live : `${PROGRAM_API_GUIDE}\n## Live /program endpoints\n\n${live}`;
+      return { content: [{ type: "text", text }] };
+    },
+  );
+
   /* --- design tokens --- */
 
   server.registerTool(

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/storybook-dist/project.json

@@ -1 +1 @@
-{"generatedAt":1793249338174,"userSince":1750932757926,"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":1793262550568,"userSince":1750932757926,"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/requirements.txt

@@ -1,4 +1,4 @@
-rainbow-rb-sdk==0.10.3
-rainbow-rb-flat-buffers==0.10.3
-rainbow-rb-zenoh==0.10.3
+rainbow-rb-sdk==0.10.4
+rainbow-rb-flat-buffers==0.10.4
+rainbow-rb-zenoh==0.10.4
 requests==2.34.2

package/cli/templates/cpp/cpp/CMakeLists.txt

@@ -7,7 +7,7 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 # Rainbow Robotics C++ SDK — provided by the apt package rainbow-rb-sdk-dev
 # (pre-installed in the muscat-pk dev container). The version here is the one the
 # dev container installs; change it with `muscat-pk sdk update <version>`.
-find_package(rb_sdk 0.10.3 EXACT REQUIRED)
+find_package(rb_sdk 0.10.4 EXACT REQUIRED)
 
 # The executable name must match runtime.entry in manifest.json.
 add_executable(__PLUGIN_SLUG__ main.cpp)

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

@@ -244,7 +244,7 @@ don't install anything locally.
 
 ```cmake
 # cpp/CMakeLists.txt — the version is the SDK the dev container installs (muscat-pk sdk update <version>)
-find_package(rb_sdk 0.10.3 EXACT REQUIRED)
+find_package(rb_sdk 0.10.4 EXACT REQUIRED)
 add_executable(__PLUGIN_SLUG__ main.cpp)           # name must equal runtime.entry
 target_link_libraries(__PLUGIN_SLUG__ PRIVATE rb_sdk::rb_sdk)
 ```

package/cli/templates/ros2-cpp/ros2_ws/src/__PLUGIN_SLUG__/CMakeLists.txt

@@ -10,7 +10,7 @@ find_package(rclcpp REQUIRED)
 # Rainbow Robotics C++ SDK (apt: rainbow-rb-sdk-dev, pre-installed in the dev
 # container). The version here is the one the dev container installs; change it
 # with `muscat-pk sdk update <version>`.
-find_package(rb_sdk 0.10.3 EXACT REQUIRED)
+find_package(rb_sdk 0.10.4 EXACT REQUIRED)
 
 add_executable(__PLUGIN_SLUG___node src/node.cpp)
 ament_target_dependencies(__PLUGIN_SLUG___node rclcpp)

package/package.json

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