@rainbow-robotics/muscat-plugin-kit 1.2.1 → 1.3.0

package/cli/README.md

@@ -60,10 +60,10 @@ and `50051` are reserved and must not be used by external plugins.
 | runtime | source | notes |
 |---|---|---|
 | `{ "type": "none" }` | — | UI-only plugin; no backend container |
-| `{ "type": "python", "entry": "main.py" }` | `py/` | Uses `rainbow.rb_sdk.RBPluginCall` for UI/backend messaging |
-| `{ "type": "cpp", "entry": "<executable name>" }` | `cpp/` | Built with CMake in Docker; current template is a run skeleton |
+| `{ "type": "python", "entry": "main.py" }` | `py/` | Uses `rainbow.rb_sdk.RBPluginCall` for UI/backend messaging; `plugin.router` exposes external endpoints (`common/plugin/{id}/{path}`, needs sdk ≥ 0.0.9.dev5 on the robot; the dev bridge only registers routes — external calls need a running `common`) |
+| `{ "type": "cpp", "entry": "<executable name>" }` | `cpp/` | Built with CMake in Docker against the C++ SDK (apt `rainbow-rb-sdk-dev`, `find_package(rb_sdk)`, dynamic link) |
 | `{ "type": "ros2", "rosClient": "rclpy", ... }` | `ros2_ws/` | ROS2 Python node; may use Python SDK alongside ROS2 APIs |
-| `{ "type": "ros2", "rosClient": "rclcpp", ... }` | `ros2_ws/` | ROS2 C++ node built with colcon/CMake |
+| `{ "type": "ros2", "rosClient": "rclcpp", ... }` | `ros2_ws/` | ROS2 C++ node built with colcon/CMake, links the C++ SDK like `cpp` |
 
 All non-`none` runtimes run in Docker during `muscat-pk dev:back`, `muscat-pk
 dev`, and build/export flows so development matches the robot environment.
@@ -257,6 +257,11 @@ would break `dev` offline. Pre-seed an air-gapped machine with
 `docker save … | gzip` + `docker load`, or force a rebuild with
 `MUSCAT_PK_REBUILD_IMAGE=1`.
 
+The C++ images (`Dockerfile.cpp`, `Dockerfile.dev`) install `rainbow-rb-sdk-dev`
+from `https://rainbowrobotics.github.io/rb-sdk` (suite `dev`), pinned by the
+`RB_SDK_VERSION` build arg. Set `MUSCAT_PK_RB_SDK_VERSION=<version>` (with
+`MUSCAT_PK_REBUILD_IMAGE=1`) to match a robot running a different SDK version.
+
 On Linux the dev containers run as the invoking user (`--user`), so build output
 under `dist/` and `cpp/build-*` is not left root-owned.
 

package/cli/docker/Dockerfile.cpp

@@ -10,12 +10,17 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       cmake \
     && rm -rf /var/lib/apt/lists/*
 
-# TODO(cpp-sdk): install the rainbow cpp SDK (dev package) here, pinned to the
-# robot's version, so plugins build/link against the same SDK as production.
-# Plan: apt package + dynamic link (the robot provides the .so at runtime;
-# we do NOT bundle it into the plugin binary). e.g.:
-#   RUN apt-get update && apt-get install -y rainbow-cpp-sdk-dev=<robot-version> \
-#       && rm -rf /var/lib/apt/lists/*
+# Rainbow Robotics C++ SDK (rainbow-rb-sdk-dev): headers + CMake config for
+# find_package(rb_sdk). Pinned to the robot's SDK version — the binary links
+# librb_sdk.so.<ver> by SONAME and the robot provides that exact .so at runtime.
+# Override with MUSCAT_PK_RB_SDK_VERSION=<ver> (+ MUSCAT_PK_REBUILD_IMAGE=1).
+ARG RB_SDK_VERSION=0.1.2~dev1
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
+    && install -d /etc/apt/keyrings \
+    && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
+    && echo 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk dev main' > /etc/apt/sources.list.d/rb-sdk.list \
+    && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
+    && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /plugin
 

package/cli/docker/Dockerfile.dev

@@ -9,6 +9,18 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       python3-colcon-common-extensions \
     && rm -rf /var/lib/apt/lists/*
 
+# Rainbow Robotics C++ SDK (rainbow-rb-sdk-dev): headers + CMake config for
+# find_package(rb_sdk). Pinned to the robot's SDK version — the binary links
+# librb_sdk.so.<ver> by SONAME and the robot provides that exact .so at runtime.
+# Override with MUSCAT_PK_RB_SDK_VERSION=<ver> (+ MUSCAT_PK_REBUILD_IMAGE=1).
+ARG RB_SDK_VERSION=0.1.2~dev1
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
+    && install -d /etc/apt/keyrings \
+    && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
+    && echo 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk dev main' > /etc/apt/sources.list.d/rb-sdk.list \
+    && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
+    && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /plugin
 
 CMD ["bash"]

package/cli/src/build.mjs

@@ -65,11 +65,11 @@ function runViteBuild(pluginRoot, { mode = "production" } = {}) {
   if (r.status !== 0) throw new Error("vite build failed");
 }
 
-function isMainBranch() {
-  const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
-  const branch = r.stdout?.trim();
-  return branch === "main" || branch === "master";
-}
+// function isMainBranch() {
+//   const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+//   const branch = r.stdout?.trim();
+//   return branch === "main" || branch === "master";
+// }
 
 // For ros2 plugins, compile the colcon workspace inside the Jazzy + Python 3.12 container.
 // rclpy: arch-agnostic (pure Python) → dist/ros2_ws/install/ (built once)
@@ -169,7 +169,7 @@ function isPrerelease(version) {
 // stableOnly=true → skips pre-release (dev/a/b/rc) versions.
 async function latestPypiVersion(pkg, { stableOnly = false } = {}) {
   const res = await fetch(`https://pypi.org/pypi/${pkg}/json`, {
-    signal: AbortSignal.timeout(5000),
+    signal: new AbortController().signal.timeout(5000),
   });
   if (!res.ok) throw new Error(`pypi ${pkg}: ${res.status}`);
   const data = await res.json();

package/cli/src/cpp.mjs

@@ -22,9 +22,11 @@ export async function ensureImage(image = CPP_DEV_IMAGE, { platform = null } = {
   const dockerfile = await resolveDockerfile("Dockerfile.cpp");
   log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
   const platformFlags = platform ? ["--platform", platform] : [];
+  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
+  const buildArgs = sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : [];
   const r = spawnSync(
     "docker",
-    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    ["build", ...platformFlags, ...buildArgs, "-t", image, "-f", dockerfile, dirname(dockerfile)],
     { stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error("docker build failed.");

package/cli/src/manifest.mjs

@@ -15,7 +15,7 @@ const RUNTIME_TYPES = ["none", "python", "cpp", "ros2"];
 const ROS_CLIENTS = ["rclpy", "rclcpp"];
 const I18N_LANGS = ["ko", "en", "ja", "zh", "vi", "th", "es"];
 const TARGET_CATEGORIES = ["manipulate", "amr", "rby1", "vision"];
-const VARIABLE_TYPES = ["number", "string", "array"];
+const VARIABLE_TYPES = ["number", "string", "boolean", "array"];
 const VARIABLE_NAME_PREFIX = "RBP_";
 const VARIABLE_NAME_RE = /^RBP_[A-Za-z0-9_]+$/;
 
@@ -144,6 +144,8 @@ function validateVariables(variables, errors) {
       errors.push(`variables[${i}].init must be a number when type is "number"`);
     else if (v.type === "string" && typeof v.init !== "string")
       errors.push(`variables[${i}].init must be a string when type is "string"`);
+    else if (v.type === "boolean" && typeof v.init !== "boolean")
+      errors.push(`variables[${i}].init must be a boolean when type is "boolean"`);
     else if (v.type === "array" && !Array.isArray(v.init))
       errors.push(`variables[${i}].init must be an array when type is "array"`);
     if (v.description !== undefined && v.description !== null)

package/cli/src/mcp.mjs

@@ -13,7 +13,9 @@
 //
 //   Plugin SDK docs + Python backend:
 //   - search_rb_sdk          search the plugin-author README (useRb(), rb.*, manifest, runtimes).
-//   - list_rb_sdk            classes/functions of the installed rainbow.rb_sdk.
+//   - list_rb_sdk            classes/functions of the installed rainbow.rb_sdk
+//                            (lang: "python" | "cpp" — cpp reads the headers of the
+//                            rainbow-rb-sdk-dev apt package out of the cpp dev image).
 //   - get_rb_sdk_api         signature + docstring for an rb_sdk class/function.
 //
 // Add to an MCP client config, e.g. Claude Code's .mcp.json:
@@ -22,13 +24,23 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import ts from "typescript";
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { kitRoot, kitVersion, findPluginRoot, venvPython } from "./util.mjs";
 import { SHIPPED_STORIES_SRC, SHIPPED_DESIGN_TOKENS } from "./storybook.mjs";
+import { CPP_DEV_IMAGE } from "./cpp.mjs";
 
 const TEMPLATE_README = join(kitRoot, "cli/templates/common/README.md");
 // Design tokens: prefer the shipped copy, fall back to the monorepo source.
@@ -40,14 +52,10 @@ const DESIGN_TOKENS_CSS = existsSync(SHIPPED_DESIGN_TOKENS)
 /* react.d.ts introspection — component/hook list + prop types                */
 /* -------------------------------------------------------------------------- */
 
-let typesCache = null;
-
-// Parse plugin-ui/react's dist/react.d.ts. It's self-contained (rb-components
-// types are inlined at build — see plugin-ui/build-dist.mjs), so this one file
-// is enough even in an external install.
-async function loadReactTypes() {
-  if (typesCache) return typesCache;
-
+// plugin-ui/react's dist/react.d.ts. It's self-contained (rb-components types
+// are inlined at build — see plugin-ui/build-dist.mjs), so this one file is
+// enough even in an external install.
+async function reactDtsPath() {
   const entryUrl = await import.meta.resolve("@rainbow-robotics/plugin-ui/react");
   const dtsPath = fileURLToPath(entryUrl).replace(/\.js$/, ".d.ts");
   if (!existsSync(dtsPath)) {
@@ -55,19 +63,23 @@ async function loadReactTypes() {
       `plugin-ui type declarations not found at ${dtsPath} — reinstall or rebuild @rainbow-robotics/plugin-ui.`,
     );
   }
+  return dtsPath;
+}
 
+function loadReactTypes(dtsPath) {
+  // Without moduleResolution the `import ... from "react"` inside react.d.ts
+  // never resolves and every React-derived type collapses to `any`.
   const program = ts.createProgram([dtsPath], {
     target: ts.ScriptTarget.ES2022,
     module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
     skipLibCheck: true,
   });
   const sourceFile = program.getSourceFile(dtsPath);
   const checker = program.getTypeChecker();
   const moduleSymbol = sourceFile && checker.getSymbolAtLocation(sourceFile);
   const exports = moduleSymbol ? checker.getExportsOfModule(moduleSymbol) : [];
-
-  typesCache = { checker, sourceFile, exports };
-  return typesCache;
+  return { checker, sourceFile, exports };
 }
 
 // The barrel's trailing `export { A, B, ... }` produces Alias symbols whose
@@ -83,6 +95,124 @@ function exportKind(checker, symbol) {
   return resolved.flags & ts.SymbolFlags.Value ? "value" : "type";
 }
 
+// typeToString alone often prints an opaque alias (`ForwardRefExoticComponent<PropsType$s>`).
+// The first call signature works for plain components and forwardRef alike; its
+// first parameter is the props object.
+function ownProps(checker, type) {
+  const [signature] = type.getCallSignatures?.() ?? [];
+  const param = signature?.getParameters?.()[0];
+  if (!param) return [];
+  const declaration = param.valueDeclaration ?? param.declarations?.[0];
+  if (!declaration) return [];
+  const propsType = checker.getTypeOfSymbolAtLocation(param, declaration);
+
+  return checker
+    .getPropertiesOfType(propsType)
+    // Without this, ~220 inherited React DOM attributes bury the component's own API.
+    .filter((prop) =>
+      (prop.declarations ?? []).some(
+        (d) => !d.getSourceFile().fileName.includes("node_modules"),
+      ),
+    )
+    .map((prop) => {
+      const d = prop.valueDeclaration ?? prop.declarations[0];
+      const optional = prop.flags & ts.SymbolFlags.Optional ? "?" : "";
+      return `${prop.getName()}${optional}: ${checker.typeToString(
+        checker.getTypeOfSymbolAtLocation(prop, d),
+      )}`;
+    });
+}
+
+// Kept out of the tool handler so every export can be precomputed and cached.
+function propsText(checker, sourceFile, name, symbol) {
+  const resolved = resolveExport(checker, symbol);
+  const declaration = resolved.valueDeclaration ?? resolved.declarations?.[0] ?? sourceFile;
+  const type = checker.getTypeOfSymbolAtLocation(resolved, declaration);
+  const signature = checker.typeToString(
+    type,
+    undefined,
+    ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.MultilineObjectLiterals,
+  );
+
+  const props = ownProps(checker, type);
+  if (props.length) {
+    // Keep the signature line: RBSlider's value/min/max come from Radix and the
+    // own-props filter drops them.
+    return `# ${name} — own props\n${props.sort().join("\n")}\n\nfull type: ${signature}`;
+  }
+  // No own props means either a Radix wrapper or unresolved React types. The two
+  // look identical, so name the second case explicitly.
+  if (/<any>/.test(signature)) {
+    return (
+      `# ${name} — prop types could not be resolved\n${signature}\n\n` +
+      "React's types didn't resolve, so this collapsed to `any`. Install `@types/react` " +
+      "in this project (`npm i -D @types/react`) and retry for the real props."
+    );
+  }
+  return (
+    `# ${name} — full type (no plugin-ui-specific props; it forwards a third-party ` +
+    `component's props)\n${signature}`
+  );
+}
+
+// Rendering every export up front is what makes the result cacheable: once the
+// text exists no TypeChecker is needed.
+function buildUiIndex(dtsPath) {
+  const { checker, sourceFile, exports } = loadReactTypes(dtsPath);
+  const props = {};
+  for (const symbol of exports) {
+    props[symbol.getName()] = propsText(checker, sourceFile, symbol.getName(), symbol);
+  }
+  return {
+    components: exports
+      .map((sym) => `${sym.getName()} (${exportKind(checker, sym)})`)
+      .sort()
+      .join("\n"),
+    props,
+  };
+}
+
+// ts.createProgram pulls in ~1100 source files (~1.5s) and an MCP server is a fresh
+// process per session. The key covers the .d.ts identity and the kit version.
+const UI_INDEX_CACHE_DIR = join(homedir(), ".cache", "muscat-pk");
+const UI_INDEX_CACHE = join(UI_INDEX_CACHE_DIR, "ui-index.json");
+
+let uiIndexCache = null;
+
+async function loadUiIndex() {
+  if (uiIndexCache) return uiIndexCache;
+  const dtsPath = await reactDtsPath();
+  const { mtimeMs, size } = statSync(dtsPath);
+  const key = `${dtsPath}|${mtimeMs}|${size}|${kitVersion()}`;
+
+  try {
+    const cached = JSON.parse(readFileSync(UI_INDEX_CACHE, "utf8"));
+    // A half-written file still parses as JSON, so check the shape too.
+    if (
+      cached.key === key &&
+      typeof cached.components === "string" &&
+      cached.props &&
+      typeof cached.props === "object"
+    ) {
+      return (uiIndexCache = cached);
+    }
+  } catch {
+    /* absent, unreadable or corrupt — rebuild below */
+  }
+
+  uiIndexCache = { key, ...buildUiIndex(dtsPath) };
+  try {
+    mkdirSync(UI_INDEX_CACHE_DIR, { recursive: true });
+    // rename is atomic, so a concurrent server never reads a half-written file.
+    const tmp = `${UI_INDEX_CACHE}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(uiIndexCache));
+    renameSync(tmp, UI_INDEX_CACHE);
+  } catch {
+    /* read-only fs / sandbox: the cache is an optimisation, never a requirement */
+  }
+  return uiIndexCache;
+}
+
 /* -------------------------------------------------------------------------- */
 /* Storybook story source lookup                                              */
 /* -------------------------------------------------------------------------- */
@@ -262,6 +392,114 @@ ${script}
   return { data };
 }
 
+/* -------------------------------------------------------------------------- */
+/* rainbow-rb-sdk-dev (C++) headers — copied out of the cpp dev image           */
+/* -------------------------------------------------------------------------- */
+
+const CPP_INCLUDE_CACHE = join(UI_INDEX_CACHE_DIR, "rb-sdk-include");
+// Headers we don't want to surface: third-party vendored code, pybind glue,
+// flatbuffers-generated schemas, and the industrial comm stacks.
+const CPP_SKIP = /^(vendor|binding|rb_comm_source)\/|_generated\.h$/;
+
+// The apt package is only installed inside the muscat-pk-cpp-dev image, so
+// copy /usr/include/rainbow/rb_sdk out once per image build (cache key =
+// image id) with `docker cp` — no host tar needed.
+function cppIncludeDir() {
+  const insp = spawnSync("docker", ["image", "inspect", "-f", "{{.Id}}", CPP_DEV_IMAGE], { encoding: "utf8" });
+  if (insp.error) return { error: "Docker not found — the C++ SDK headers live in the muscat-pk cpp dev image." };
+  if (insp.status !== 0) {
+    return {
+      error:
+        `Docker image ${CPP_DEV_IMAGE} not built yet. Run \`muscat-pk dev:back\` (or \`muscat-pk build\`) once ` +
+        "in a cpp / rclcpp plugin to build it, then retry.",
+    };
+  }
+  const dir = join(CPP_INCLUDE_CACHE, insp.stdout.trim().replace(/^sha256:/, "").slice(0, 12));
+  const out = join(dir, "rb_sdk");
+  if (existsSync(out)) return { dir: out };
+  mkdirSync(dir, { recursive: true });
+  const ctr = spawnSync("docker", ["create", CPP_DEV_IMAGE], { encoding: "utf8" });
+  if (ctr.status !== 0) return { error: `docker create failed: ${(ctr.stderr || "").trim().slice(0, 300)}` };
+  const id = ctr.stdout.trim();
+  const cp = spawnSync("docker", ["cp", `${id}:/usr/include/rainbow/rb_sdk`, dir], { encoding: "utf8" });
+  spawnSync("docker", ["rm", "-f", id], { encoding: "utf8" });
+  if (cp.status !== 0 || !existsSync(out)) {
+    return { error: `docker cp failed: ${(cp.stderr || "").trim().slice(0, 300)}` };
+  }
+  return { dir: out };
+}
+
+function cppHeaders(root) {
+  const files = [];
+  const walk = (d, rel) => {
+    for (const name of readdirSync(d)) {
+      const r = rel ? `${rel}/${name}` : name;
+      if (CPP_SKIP.test(r)) continue;
+      const full = join(d, name);
+      if (statSync(full).isDirectory()) walk(full, r);
+      else if (/\.hpp$/.test(name)) files.push(r);
+    }
+  };
+  walk(root, "");
+  return files.sort();
+}
+
+// "class Foo {" / "class Foo : public Bar {" — not forward declarations.
+const CLASS_RE = /^\s*(?:class|struct)\s+(\w+)\b(?![^\n]*;\s*$)/;
+
+function cppClassesIn(text) {
+  return [...new Set(text.split("\n").map((l) => l.match(CLASS_RE)?.[1]).filter(Boolean))];
+}
+
+// Return the class body (brace-matched) plus the file's leading comment block,
+// which in these headers usually carries a full usage example.
+function cppExtract(text, className, method) {
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => CLASS_RE.test(l) && l.match(CLASS_RE)[1] === className);
+  if (start < 0) return null;
+  let depth = 0, end = start, seen = false;
+  for (let i = start; i < lines.length; i++) {
+    for (const ch of lines[i]) {
+      if (ch === "{") { depth++; seen = true; }
+      else if (ch === "}") depth--;
+    }
+    if (seen && depth === 0) { end = i; break; }
+  }
+  const body = lines.slice(start, end + 1);
+  if (method) {
+    // Declarations sit at class-member indent (<= 2 spaces) and the name is
+    // not preceded by `.`/`->`/`::` — that skips call sites inside bodies.
+    const re = new RegExp(`^ {0,2}[^(]*(?<![\\w.>:])${method.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\(`);
+    const hits = [];
+    for (let i = 0; i < body.length; i++) {
+      if (!re.test(body[i]) || /^\s*\/\//.test(body[i])) continue;
+      let a = i;
+      while (a > 0 && /^\s*\/\//.test(body[a - 1])) a--;
+      let b = i;
+      while (b < body.length - 1 && !/[{;]/.test(body[b])) b++;
+      hits.push(body.slice(a, b + 1).join("\n"));
+    }
+    return hits.length ? hits.join("\n\n") : null;
+  }
+  const head = [];
+  for (const l of lines) {
+    if (/^\s*\/\//.test(l)) head.push(l);
+    else if (l.trim() === "" || /^#pragma/.test(l)) continue;
+    else break;
+  }
+  return (head.length > 3 ? head.join("\n") + "\n\n" : "") + body.join("\n");
+}
+
+function cppFind(className) {
+  const { dir, error } = cppIncludeDir();
+  if (error) return { error };
+  for (const rel of cppHeaders(dir)) {
+    const text = readFileSync(join(dir, rel), "utf8");
+    if (cppClassesIn(text).includes(className)) return { rel, text };
+  }
+  return { error: `No class "${className}" in the C++ SDK headers. Call list_rb_sdk with lang "cpp" for valid names.` };
+}
+
 /* -------------------------------------------------------------------------- */
 /* client registration — `muscat-pk mcp --install <client>`                    */
 /* -------------------------------------------------------------------------- */
@@ -313,11 +551,8 @@ export async function runMcp() {
       inputSchema: {},
     },
     async () => {
-      const { checker, exports } = await loadReactTypes();
-      const lines = exports
-        .map((sym) => `${sym.getName()} (${exportKind(checker, sym)})`)
-        .sort();
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+      const { components } = await loadUiIndex();
+      return { content: [{ type: "text", text: components }] };
     },
   );
 
@@ -331,9 +566,8 @@ export async function runMcp() {
       inputSchema: { name: z.string().describe('Exported name, e.g. "RBSlider"') },
     },
     async ({ name }) => {
-      const { checker, sourceFile, exports } = await loadReactTypes();
-      const symbol = exports.find((sym) => sym.getName() === name);
-      if (!symbol) {
+      const { props } = await loadUiIndex();
+      if (!Object.hasOwn(props, name)) {
         return {
           isError: true,
           content: [
@@ -344,15 +578,7 @@ export async function runMcp() {
           ],
         };
       }
-      const resolved = resolveExport(checker, symbol);
-      const declaration = resolved.valueDeclaration ?? resolved.declarations?.[0] ?? sourceFile;
-      const type = checker.getTypeOfSymbolAtLocation(resolved, declaration);
-      const text = checker.typeToString(
-        type,
-        undefined,
-        ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.MultilineObjectLiterals,
-      );
-      return { content: [{ type: "text", text }] };
+      return { content: [{ type: "text", text: props[name] }] };
     },
   );
 
@@ -399,6 +625,8 @@ export async function runMcp() {
       title: "Search the Muscat plugin-author docs",
       description:
         "Search the Muscat plugin-author README for how to use useRb(), rb.pub/sub/action/serve, " +
+        "plugin.router (external endpoints: router.on/subscribe/emit exposed over REST/Socket.IO/TCP/" +
+        "MQTT/WebRTC at common/plugin/{plugin_id}/{path}, PluginRouteError, meta.transport/principal), " +
         "rb.toast/alert/confirm/prompt, useRbFormData/useRbSave (save/restore form data through the " +
         "host), manifest.json (including the \"variables\" declaration for the pyfm variable picker — " +
         "names require the RBP_ prefix), program variables & executor state (ctx.get_variable/" +
@@ -446,7 +674,10 @@ export async function runMcp() {
       const other = { shadow: [], radius: [], spacing: [] };
       for (const t of vars) {
         const m = t.group?.match(/^color-(bg|fg|border|fill)$/);
-        if (m && t.class) colorGroups[m[1]].push(`${t.class}   (${t.value})`);
+        // Class name only: the value is just an indirection to another CSS var
+        // (var(--color-scale-zinc-200)), and each class is declared twice (light/dark)
+        // with different values — dropping the value lets the Set dedup collapse them.
+        if (m && t.class) colorGroups[m[1]].push(t.class);
         else if (t.name.startsWith("shadow-")) other.shadow.push(`shadow-${t.name.slice(7)}`);
         else if (t.name.startsWith("radius-")) other.radius.push(`rounded-${t.name.slice(7)}`);
         else if (t.name.startsWith("spacing-")) other.spacing.push(t.name);
@@ -509,14 +740,28 @@ export async function runMcp() {
   server.registerTool(
     "list_rb_sdk",
     {
-      title: "List rainbow-rb-sdk (Python) classes and functions",
+      title: "List rainbow-rb-sdk classes and functions (Python or C++)",
       description:
-        "List the public classes and functions of the installed rainbow.rb_sdk Python package — the " +
-        "plugin BACKEND SDK (RBPluginCall, RBManipulateSDK, RBAmrSDK, PluginProgramContext, ...). Call " +
-        "before writing py/main.py. Requires rainbow-rb-sdk to be pip-installed.",
-      inputSchema: {},
+        "List the public classes and functions of the plugin BACKEND SDK. lang \"python\" (default): the " +
+        "installed rainbow.rb_sdk package (RBPluginCall, RBManipulateSDK, RBAmrSDK, PluginProgramContext, " +
+        "...) — call before writing py/main.py; requires rainbow-rb-sdk to be pip-installed. lang \"cpp\": " +
+        "the C++ SDK headers (apt rainbow-rb-sdk-dev: RBManipulateSDK, rb_plugin::PluginProgramContext, " +
+        "...) grouped by header path — call before writing cpp/main.cpp or an rclcpp node; requires the " +
+        "muscat-pk-cpp-dev Docker image (built by `muscat-pk dev:back`). Note: RBPluginCall (UI pub/sub/" +
+        "serve) exists in Python only.",
+      inputSchema: { lang: z.enum(["python", "cpp"]).optional().describe('Default "python"') },
     },
-    async () => {
+    async ({ lang }) => {
+      if (lang === "cpp") {
+        const { dir, error } = cppIncludeDir();
+        if (error) return { isError: true, content: [{ type: "text", text: error }] };
+        const out = [];
+        for (const rel of cppHeaders(dir)) {
+          const classes = cppClassesIn(readFileSync(join(dir, rel), "utf8"));
+          if (classes.length) out.push(`${rel}: ${classes.join(", ")}`);
+        }
+        return { content: [{ type: "text", text: `#include <rainbow/rb_sdk/...>\n\n${out.join("\n")}` }] };
+      }
       const { data, error } = introspectRbSdk(`
 import inspect, json
 mod = importlib.import_module("rainbow.rb_sdk")
@@ -536,19 +781,22 @@ print(json.dumps(out))
   server.registerTool(
     "get_rb_sdk_api",
     {
-      title: "Get a rainbow-rb-sdk class/function signature + docs",
+      title: "Get a rainbow-rb-sdk class/function signature + docs (Python or C++)",
       description:
         "Get the signature(s) and docstring for a rainbow.rb_sdk class or function (e.g. " +
         "'PluginProgramContext', 'RBManipulateSDK'). For a class, lists its public methods with " +
         "signatures. To drill into ONE method of a class (e.g. RBManipulateSDK.call_move_j), pass " +
-        "`method` alongside `name` — do not put both in `name`. Requires rainbow-rb-sdk to be " +
-        "pip-installed.",
+        "`method` alongside `name` — do not put both in `name`. lang \"python\" (default) introspects the " +
+        "pip-installed package. lang \"cpp\" returns the class declaration from the C++ SDK header " +
+        "(rainbow-rb-sdk-dev) with its header comment — usually a full usage example — and the " +
+        "#include path; with `method`, just that method's declaration and comment.",
       inputSchema: {
         name: z.string().describe('Class or function name, e.g. "RBManipulateSDK"'),
         method: z.string().optional().describe('Optional: a specific method on that class, e.g. "call_move_j"'),
+        lang: z.enum(["python", "cpp"]).optional().describe('Default "python"'),
       },
     },
-    async ({ name, method }) => {
+    async ({ name, method, lang }) => {
       // Tolerate a combined "ClassName method_name" in `name` (a common agent
       // mistake) by splitting it ourselves instead of failing validation.
       let className = name;
@@ -558,6 +806,42 @@ print(json.dumps(out))
         if (parts.length === 2) [className, methodName] = parts;
       }
 
+      if (lang === "cpp") {
+        const cls = className.replace(/^.*::/, "");
+        let { rel, text, error } = cppFind(cls);
+        if (error) return { isError: true, content: [{ type: "text", text: error }] };
+        let body = cppExtract(text, cls, methodName);
+        let owner = cls;
+        if (!body && methodName) {
+          // Like the Python path: most calls live on sub-SDK members
+          // (RBManipulateMoveSDK move; -> sdk.move.call_move_j) or on the base
+          // class — look there before giving up.
+          const decl = cppExtract(text, cls);
+          const cands = [
+            ...[...decl.matchAll(/^\s*(\w+SDK)\s+(\w+);/gm)].map((m) => [m[1], `${cls}.${m[2]}`]),
+            ...[...decl.matchAll(/:\s*public\s+(\w+)/g)].map((m) => [m[1], `${cls} (base ${m[1]})`]),
+          ];
+          for (const [c, label] of cands) {
+            const f = cppFind(c);
+            if (f.error) continue;
+            const b = cppExtract(f.text, c, methodName);
+            if (b) { ({ rel, text } = f); body = b; owner = label; break; }
+          }
+        }
+        if (!body) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `No method "${methodName}" declared in class "${cls}" (${rel}) or its sub-SDK members / base class. Call get_rb_sdk_api with just \`name\` to see the class.` }],
+          };
+        }
+        const ns = text.match(/^namespace\s+(\w+)\s*\{/m)?.[1];
+        const header =
+          `// #include <rainbow/rb_sdk/${rel}>${ns ? `   (namespace ${ns})` : ""}\n` +
+          `// link: find_package(rb_sdk) + rb_sdk::rb_sdk\n` +
+          (methodName ? `// ${owner}.${methodName}\n` : "") + "\n";
+        return { content: [{ type: "text", text: header + body.slice(0, 60_000) }] };
+      }
+
       const { data, error } = introspectRbSdk(`
 import inspect, json
 mod = importlib.import_module("rainbow.rb_sdk")

package/cli/src/ros2.mjs

@@ -37,9 +37,11 @@ export async function ensureImage(image = ROS2_DEV_IMAGE, { platform = null } =
   const dockerfile = await resolveDockerfile("Dockerfile.dev");
   log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
   const platformFlags = platform ? ["--platform", platform] : [];
+  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
+  const buildArgs = sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : [];
   const r = spawnSync(
     "docker",
-    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    ["build", ...platformFlags, ...buildArgs, "-t", image, "-f", dockerfile, dirname(dockerfile)],
     { stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error("docker build failed.");

package/cli/storybook-dist/_stories-src/RBDatePicker/RBRangeDateInput.stories.tsx

@@ -16,13 +16,25 @@ export default {
     },
     showPresets: { control: "boolean" },
     showFooter: { control: "boolean" },
+    min: { control: "date" },
+    max: { control: "date" },
+    maxDays: {
+      control: { type: "number", min: 0, step: 1 },
+      description: "선택 가능한 최대 일수. 0은 제한 없음.",
+    },
   },
+  args: { maxDays: 0 },
 } as Meta<typeof RBRangeDateInput>;
 
 const Template: StoryTemplate = (args) => {
   return (
     <div style={{ height: 700 }}>
-      <RBRangeDateInput {...args} />
+      <RBRangeDateInput
+        {...args}
+        min={args.min != null ? new Date(args.min) : undefined}
+        max={args.max != null ? new Date(args.max) : undefined}
+        maxDays={(args.maxDays ?? 0) > 0 ? args.maxDays : undefined}
+      />
     </div>
   );
 };