@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.45 → 0.1.2-dev.47

package/cli/src/devBack.mjs

@@ -10,15 +10,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, watch } from "node:fs";
 import { resolve } from "node:path";
-import {
-  detectPythonCmd,
-  ensureDocker,
-  findPluginRoot,
-  hasBin,
-  log,
-  promptRobotConnection,
-  venvPython,
-} from "./util.mjs";
+import { ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection } from "./util.mjs";
 import { assertManifestPorts, manifestRuntime, readManifest, validateManifest } from "./manifest.mjs";
 import {
   formatPortRanges,
@@ -43,33 +35,16 @@ import {
 } from "./cpp.mjs";
 
 // ── IDE tooling venv (best-effort, non-blocking) ────────────────────────────
-// Docker is the source of truth for actually RUNNING the backend — this just
-// gives editors/linters (pylint, pyright, mypy, ...) a real interpreter with
-// the plugin's deps installed, since they inspect the host filesystem, not the
-// container. Runs in the background so it never delays `dev:back` starting,
-// and any failure here (no local Python toolchain, offline, ...) is silent —
-// Docker works fine with zero local Python.
+// `muscat-pk new` already creates this up front (see new.mjs); this just
+// refreshes it on every `dev`/`dev:back` in case requirements.txt changed.
+// Docker remains the actual execution environment — this never affects it.
+// Runs in the background so it never delays `dev:back` starting, and any
+// failure here (no local Python toolchain, offline, ...) is silent.
 function syncIdeVenv(root) {
-  const venvDir = resolve(root, ".venv");
-  const py = venvPython(venvDir);
-
   setImmediate(() => {
     try {
-      if (!existsSync(py)) {
-        let created;
-        if (hasBin("uv")) {
-          created = spawnSync("uv", ["venv", venvDir, "--python", "3.12", "--seed"], { cwd: root, stdio: "ignore" });
-        } else {
-          const { cmd } = detectPythonCmd();
-          created = spawnSync(cmd[0], [...cmd.slice(1), "-m", "venv", venvDir], { cwd: root, stdio: "ignore" });
-        }
-        if (created.status !== 0 || !existsSync(py)) return;
-      }
-      const reqs = resolve(root, "requirements.txt");
-      const args = ["-m", "pip", "install", "-q"];
-      if (existsSync(reqs)) args.push("-r", reqs);
-      if (spawnSync(py, args, { cwd: root, stdio: "ignore" }).status === 0) {
-        log.info(`IDE venv ready → .venv (point your editor's Python interpreter there for pylint/pyright)`);
+      if (ensureIdeVenv(root)) {
+        log.info("IDE venv ready → .venv (point your editor's Python interpreter there for pylint/pyright)");
       }
     } catch {
       /* best-effort only */
@@ -82,9 +57,11 @@ function syncIdeVenv(root) {
 // Under `muscat-pk dev`, it shares the bridge container's netns, so the SDK
 // reaches the Socket.IO bridge at the default localhost:10000.
 async function runPython(root, portRanges) {
+  // Independent of Docker readiness — must still happen if Docker isn't
+  // installed/running, since that's exactly when local IDE tooling matters most.
+  syncIdeVenv(root);
   pyAssertDockerReady();
   await pyEnsureImage();
-  syncIdeVenv(root);
 
   const manifest = readManifest(root);
   const pluginId = manifest.id ?? "";
@@ -154,16 +131,19 @@ async function runPython(root, portRanges) {
 
 // ── ros2 ───────────────────────────────────────────────────────────────────────
 async function runRos2(root, portRanges) {
+  const manifest = readManifest(root);
+  const isRclcpp = manifest.runtime?.rosClient === "rclcpp";
+  // Independent of Docker readiness — must still happen if Docker isn't
+  // installed/running, since that's exactly when local IDE tooling matters most.
+  if (!isRclcpp) syncIdeVenv(root); // rclpy is plain Python — rclcpp is C++, no venv needed
+
   assertDockerReady();
   const pkg = ros2PackageName(root);
   if (!pkg) throw new Error("no ROS2 package found under ros2_ws/src.");
 
   await ensureImage();
 
-  const manifest = readManifest(root);
   const pluginId = manifest.id ?? "";
-  const isRclcpp = manifest.runtime?.rosClient === "rclcpp";
-  if (!isRclcpp) syncIdeVenv(root); // rclpy is plain Python — rclcpp is C++, no venv needed
   const container = `${ROS2_DEV_IMAGE}-run`;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";

package/cli/src/mcp.mjs

@@ -1,7 +1,6 @@
-// muscat-pk mcp — an MCP (Model Context Protocol) server that gives an AI
-// coding agent (Claude Code, Codex, ...) grounded knowledge of the Muscat
-// plugin UI surface, instead of it guessing prop names or grepping
-// node_modules for @rainbow-robotics/plugin-ui and @repo/rb-components:
+// muscat-pk mcp — an MCP (Model Context Protocol) server exposing the Muscat
+// plugin UI/SDK surface to an AI coding agent (Claude Code, Codex, ...) so it
+// looks things up instead of guessing. Tools:
 //
 //   Frontend UI (@rainbow-robotics/plugin-ui/react, via dist/react.d.ts):
 //   - list_components        every exported component/hook/type.
@@ -42,11 +41,9 @@ const DESIGN_TOKENS_CSS = existsSync(SHIPPED_DESIGN_TOKENS)
 
 let typesCache = null;
 
-// Resolves @rainbow-robotics/plugin-ui/react's bundled, self-contained
-// dist/react.d.ts (see plugin-ui/build-dist.mjs — rb-components' own types are
-// inlined into it, so this single file is enough; no need to resolve
-// @repo/rb-components separately, which wouldn't exist in an external install
-// anyway).
+// 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;
 
@@ -113,9 +110,7 @@ function findStorySource(name) {
 /* README search                                                              */
 /* -------------------------------------------------------------------------- */
 
-// Splits the plugin-author README on headings and keyword-scores each
-// section — good enough for short-query lookups ("save form data", "toast",
-// "manifest ui") without pulling in a real search dependency.
+// Split the README on headings and keyword-score each section.
 function searchReadme(query) {
   if (!existsSync(TEMPLATE_README)) return [];
   const text = readFileSync(TEMPLATE_README, "utf8");
@@ -200,9 +195,8 @@ function pythonCmd() {
   return null;
 }
 
-// Runs a short introspection script against the INSTALLED rainbow.rb_sdk. It's
-// the plugin's own backend dependency (requirements.txt / `muscat-pk sdk`), so
-// in a real plugin env it's importable; otherwise we return a clear hint.
+// Run an introspection script against the installed rainbow.rb_sdk (a plugin's
+// backend dependency). Returns a clear hint if it isn't importable.
 function introspectRbSdk(script) {
   const py = pythonCmd();
   if (!py) {
@@ -305,16 +299,27 @@ export async function runMcp() {
         "Get the real Storybook story source for a component (e.g. RBSlider) — actual working " +
         "props, imports, and layout, not a guessed shape. Prefer this over get_component_props when " +
         "you just need to know how to use a component, not its full type.",
-      inputSchema: { name: z.string().describe('Component name, e.g. "RBSlider"') },
+      // `component` accepted as an alias — agents often guess it over `name`.
+      inputSchema: {
+        name: z.string().optional().describe('Component name, e.g. "RBSlider"'),
+        component: z.string().optional().describe("Alias for `name`."),
+      },
     },
-    async ({ name }) => {
-      const source = findStorySource(name);
+    async ({ name, component }) => {
+      const target = name ?? component;
+      if (!target) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: 'Missing required argument: "name" (component name, e.g. "RBSlider").' }],
+        };
+      }
+      const source = findStorySource(target);
       if (!source) {
         return {
           content: [
             {
               type: "text",
-              text: `No Storybook example found for "${name}". Run "muscat-pk storybook" to browse all components live, or use get_component_props for its type.`,
+              text: `No Storybook example found for "${target}". Run "muscat-pk storybook" to browse all components live, or use get_component_props for its type.`,
             },
           ],
         };
@@ -467,20 +472,66 @@ print(json.dumps(out))
       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. Requires rainbow-rb-sdk to be pip-installed.",
-      inputSchema: { name: z.string().describe('e.g. "PluginProgramContext"') },
+        "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.",
+      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"'),
+      },
     },
-    async ({ name }) => {
+    async ({ name, method }) => {
+      // Tolerate a combined "ClassName method_name" in `name` (a common agent
+      // mistake) by splitting it ourselves instead of failing validation.
+      let className = name;
+      let methodName = method;
+      if (!methodName && /\s/.test(name.trim())) {
+        const parts = name.trim().split(/\s+/);
+        if (parts.length === 2) [className, methodName] = parts;
+      }
+
       const { data, error } = introspectRbSdk(`
 import inspect, json
 mod = importlib.import_module("rainbow.rb_sdk")
-name = ${JSON.stringify(name)}
+name = ${JSON.stringify(className)}
+method = ${JSON.stringify(methodName ?? null)}
 obj = getattr(mod, name, None)
 if obj is None:
     print(json.dumps({"__missing__": True})); raise SystemExit(0)
 def sig(o):
     try: return str(inspect.signature(o))
     except Exception: return "(...)"
+
+if method:
+    # Direct method on the class itself.
+    fn = getattr(obj, method, None) if inspect.isclass(obj) else None
+    # rb_sdk classes often group calls under a nested namespace set in
+    # __init__ (e.g. RBManipulateSDK().move.call_move_j) — that only exists on
+    # an INSTANCE, which we won't construct (side effects, needs a robot
+    # connection). Best-effort: search the class's own __init__ source text
+    # for self.<attr> = <NestedClass>(...) and check each nested class too.
+    owner = name
+    if fn is None and inspect.isclass(obj):
+        try:
+            src = inspect.getsource(obj.__init__)
+        except Exception:
+            src = ""
+        import re
+        for attr, nested_name in re.findall(r"self\\.(\\w+)\\s*=\\s*(\\w+)\\(", src):
+            nested = mod.__dict__.get(nested_name) or globals().get(nested_name)
+            cand = getattr(nested, method, None) if nested else None
+            if cand:
+                fn = cand
+                owner = f"{name}.{attr} ({nested_name})"
+                break
+    if fn is None:
+        print(json.dumps({"__missing__": True, "__method__": True})); raise SystemExit(0)
+    print(json.dumps({
+        "name": name, "kind": "method", "owner": owner,
+        "signature": method + sig(fn), "doc": inspect.getdoc(fn) or "",
+    }))
+    raise SystemExit(0)
+
 res = {"name": name, "doc": inspect.getdoc(obj) or ""}
 if inspect.isclass(obj):
     res["kind"] = "class"
@@ -497,12 +548,17 @@ print(json.dumps(res))
 `);
       if (error) return { isError: true, content: [{ type: "text", text: error }] };
       if (data.__missing__) {
-        return {
-          isError: true,
-          content: [
-            { type: "text", text: `No "${name}" in rainbow.rb_sdk. Call list_rb_sdk for valid names.` },
-          ],
-        };
+        const text = data.__method__
+          ? `No method "${methodName}" found directly on "${className}" (nor in an obvious nested ` +
+            `namespace set in __init__). Call get_rb_sdk_api with just \`name: "${className}"\` to see ` +
+            `its full method list and constructor first.`
+          : `No "${className}" in rainbow.rb_sdk. Call list_rb_sdk for valid names.`;
+        return { isError: true, content: [{ type: "text", text }] };
+      }
+      if (data.kind === "method") {
+        const lines = [`# ${data.owner}.${data.signature.split("(")[0]}`, data.signature];
+        if (data.doc) lines.push("", data.doc);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
       }
       const lines = [`# ${data.name} (${data.kind})`];
       if (data.doc) lines.push(data.doc, "");

package/cli/src/new.mjs

@@ -12,7 +12,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
-import { hasBin, kitVersion, parseArgs, prompt, templatesDir, log } from "./util.mjs";
+import { ensureIdeVenv, hasBin, kitVersion, parseArgs, prompt, templatesDir, log } from "./util.mjs";
 
 // Like cpSync(src, dst, {recursive:true}) but reads from the embedded snapshot
 // when the templates dir doesn't exist on disk (compiled binary mode).
@@ -227,6 +227,21 @@ export async function runNew(args) {
     } catch {
       log.warn(`'${pm} install' failed; run it manually in ${targetName}`);
     }
+
+    // Local .venv is for your editor/linter (pylint, pyright, ...) only — the
+    // backend actually RUNS in Docker (see README), this never affects that.
+    // rclcpp is C++, so no venv applies there.
+    const needsIdeVenv =
+      runtimeChoice.type === "python" ||
+      (runtimeChoice.type === "ros2" && runtimeChoice.rosClient === "rclpy");
+    if (needsIdeVenv) {
+      log.step("creating .venv for your editor (pylint/pyright)…");
+      if (ensureIdeVenv(target)) {
+        log.ok(".venv ready — point your editor's Python interpreter there.");
+      } else {
+        log.warn("Could not create .venv (no local Python/uv?) — skipping, Docker dev still works.");
+      }
+    }
   }
 
   // The back end (python / cpp / ros2) runs in a Docker container that matches

package/cli/src/pluginDevServer.mjs

@@ -46,12 +46,11 @@ import { setHostServices } from "@rainbow-robotics/plugin-ui/host-ui";
 import { RbWs, createLazyRbSdk } from "@rainbow-robotics/plugin-ui/ws";
 import App from ${entry};
 
-// HMR only hands the new module to the accept callback — it does NOT rebind the
-// static \`App\` import above. So we track the latest component at MODULE scope.
-// Without this, navigating away and back (a fresh mount() call on this cached
-// bootstrap module) would render the STALE component captured at first import;
-// only a hard refresh fixed it. \`activeRender\` points at the currently-mounted
-// root so live edits re-render it in place.
+// HMR passes the new module to the accept callback but doesn't rebind the
+// static \`App\` import, so we track the latest at module scope. Without this,
+// navigating away and back (a fresh mount() on this cached module) renders the
+// stale App from first import. \`activeRender\` points at the mounted root so
+// live edits re-render in place.
 let latestApp = App;
 let activeRender = null;
 if (import.meta.hot) {

package/cli/src/util.mjs

@@ -39,6 +39,32 @@ export function venvPython(venvDir) {
     : resolve(venvDir, "bin", "python");
 }
 
+/**
+ * Create/refresh a local `.venv` with requirements.txt installed, for the
+ * editor/linter only (the backend actually runs in Docker). Uses `uv` if
+ * present, else the system Python. Returns true if the venv is ready.
+ */
+export function ensureIdeVenv(root) {
+  const venvDir = resolve(root, ".venv");
+  const py = venvPython(venvDir);
+
+  if (!existsSync(py)) {
+    let created;
+    if (hasBin("uv")) {
+      created = spawnSync("uv", ["venv", venvDir, "--python", "3.12", "--seed"], { cwd: root, stdio: "ignore" });
+    } else {
+      const { cmd } = detectPythonCmd();
+      created = spawnSync(cmd[0], [...cmd.slice(1), "-m", "venv", venvDir], { cwd: root, stdio: "ignore" });
+    }
+    if (created.status !== 0 || !existsSync(py)) return false;
+  }
+
+  const reqs = resolve(root, "requirements.txt");
+  const args = ["-m", "pip", "install", "-q"];
+  if (existsSync(reqs)) args.push("-r", reqs);
+  return spawnSync(py, args, { cwd: root, stdio: "ignore" }).status === 0;
+}
+
 /** Published install/CLI package name. Author imports use @rainbow-robotics/plugin-ui separately. */
 export const KIT_PUBLISHED_NAME = "@rainbow-robotics/muscat-plugin-kit";
 

package/cli/storybook-dist/project.json

@@ -1 +1 @@
-{"generatedAt":1783605738795,"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":1783624567446,"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/package.json

@@ -10,6 +10,8 @@
     "@tailwindcss/vite": "^4.1.0",
     "@rainbow-robotics/muscat-plugin-kit": "__RB_VERSION__",
     "@rainbow-robotics/preview-host": "__RB_VERSION__",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
     "@vitejs/plugin-react": "^4.0.0",
     "tailwindcss": "^4.1.0",
     "typescript": "^5.8.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-robotics/muscat-plugin-kit",
-  "version": "0.1.2-dev.45",
+  "version": "0.1.2-dev.47",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -53,8 +53,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@rainbow-robotics/plugin-ui": "0.1.2-dev.45",
-    "@rainbow-robotics/preview-host": "0.1.2-dev.45",
+    "@rainbow-robotics/plugin-ui": "0.1.2-dev.47",
+    "@rainbow-robotics/preview-host": "0.1.2-dev.47",
     "postcss": "^8.5.8",
     "socket.io": "^4.8.1",
     "typescript": "^5.8.0",