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

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

@@ -305,16 +305,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.`,
             },
           ],
         };

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/util.mjs

@@ -39,6 +39,35 @@ export function venvPython(venvDir) {
     : resolve(venvDir, "bin", "python");
 }
 
+/**
+ * Create/refresh a LOCAL `.venv` with the plugin's requirements.txt installed —
+ * purely so an editor/linter (pylint, pyright, mypy, ...) can resolve imports.
+ * Docker remains the actual execution environment for `dev`/`dev:back`; this
+ * never affects it. Uses `uv` if available (fast, pins Python 3.12 — matches
+ * the robot), else falls back to the detected system Python.
+ * Returns true if the venv is ready with deps installed.
+ */
+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":1783623695483,"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.46",
   "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.46",
+    "@rainbow-robotics/preview-host": "0.1.2-dev.46",
     "postcss": "^8.5.8",
     "socket.io": "^4.8.1",
     "typescript": "^5.8.0",