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

package/cli/src/new.mjs

@@ -1,5 +1,5 @@
 // muscat-pk new — scaffold a new plugin project from templates.
-import { execFileSync, execSync } from "node:child_process";
+import { execSync } from "node:child_process";
 import {
   cpSync,
   existsSync,
@@ -7,26 +7,102 @@ import {
   readFileSync,
   readdirSync,
   renameSync,
+  rmSync,
   statSync,
   writeFileSync,
 } from "node:fs";
-import { createInterface } from "node:readline/promises";
-import { basename, resolve } from "node:path";
-import { detectPythonCmd, hasBin, parseArgs, templatesDir, log, venvPython } from "./util.mjs";
+import { basename, dirname, resolve } from "node:path";
+import { color, ensureIdeVenv, hasBin, kitVersion, parseArgs, prompt, templatesDir, log } from "./util.mjs";
+import { agentsMd, CLAUDE_MD, MCP_JSON } from "./ai-rules.mjs";
 
-const TYPES = ["python", "ros2"];
+// Like cpSync(src, dst, {recursive:true}) but reads from the embedded snapshot
+// when the templates dir doesn't exist on disk (compiled binary mode).
+// ponytail: import() is module-cached by the runtime — no manual cache needed.
+export async function copyTemplate(srcDir, dst) {
+  if (existsSync(templatesDir)) { cpSync(srcDir, dst, { recursive: true }); return; }
+  const { TEMPLATES } = await import("./templates-embedded.mjs");
+  const prefix = srcDir.slice(templatesDir.length + 1).replace(/\\/g, "/") + "/";
+  for (const [key, b64] of Object.entries(TEMPLATES)) {
+    if (!key.startsWith(prefix)) continue;
+    const dest = resolve(dst, key.slice(prefix.length));
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, Buffer.from(b64, "base64"));
+  }
+}
+
+// `--type` values map to a runtime descriptor. ros2 has a python (rclpy) and a
+// C++ (rclcpp) flavor; we expose them as distinct type choices for clarity.
+export const TYPE_CHOICES = {
+  python:    { type: "python" },
+  cpp:       { type: "cpp" },
+  ros2:      { type: "ros2", rosClient: "rclpy" },
+  "ros2-cpp":{ type: "ros2", rosClient: "rclcpp" },
+};
+const TYPES = Object.keys(TYPE_CHOICES);
 const PMS = ["npm", "yarn", "pnpm", "bun"];
 
-async function prompt(question, fallback) {
-  if (!process.stdin.isTTY) return fallback;
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const answer = (await rl.question(question)).trim();
-  rl.close();
-  return answer || fallback;
+function printNewSuccess({ targetName, type, pm }) {
+  const mark = [
+    "             /\\",
+    "            /  \\_",
+    "       ____||__",
+    "      /  \\__/  \\",
+    "   __/\\__/  \\__/\\",
+    "  /  \\__/\\__/\\__/\\",
+    "  \\__/  \\__/  \\__/",
+    "     \\__/  \\__/",
+    "        \\__/",
+  ].map((line) => color.green(line)).join("\n");
+
+  log.info("");
+  log.info(mark);
+  log.info(color.bold(color.green("Welcome to Muscat Plugin Kit!")));
+  log.info(color.dim("A fresh plugin workspace is ready."));
+  log.info("");
+  log.ok(`created ${color.bold(targetName)} ${color.dim(`(type: ${type}, pm: ${pm})`)}`);
+  log.info("");
+  log.info(color.bold("Next steps"));
+  log.info(`  ${color.cyan("cd")} ${targetName}`);
+  log.info(`  ${color.cyan("muscat-pk dev")}      ${color.dim("# preview in mini-Muscat + back end")}`);
+  log.info(`  ${color.cyan("muscat-pk build")}    ${color.dim("# build + distributable ZIP")}`);
+  log.info("");
+  log.info(color.dim("AI assistant? Claude Code reads the scaffolded .mcp.json and CLAUDE.md (→ AGENTS.md);"));
+  log.info(color.dim(`Codex users run ${color.cyan("muscat-pk mcp --install codex")} once.`));
+  log.info("");
+}
+
+// C++ backends: the editor needs the SDK headers, which only exist in the dev image. Building the image
+// now (dev/build reuse it) lets VS Code resolve rb_sdk right away. Best-effort, like the .venv.
+export async function prepareCppIde(root, choice) {
+  const later = "they come with the first `muscat-pk dev` / `build`";
+  if (!hasBin("docker")) return log.warn(`Docker not found — SDK headers for the editor: ${later}.`);
+  try {
+    log.step("preparing the C++ dev image + SDK headers for your editor (first run is slow)…");
+    const { ensureImage } = await import(choice.type === "cpp" ? "./cpp.mjs" : "./ros2.mjs");
+    await ensureImage(undefined, { root });
+  } catch (err) {
+    log.warn(`Could not prepare SDK headers for the editor (${err.message}) — ${later}.`);
+  }
+}
+
+// Build the manifest runtime object for a given type choice + plugin slug.
+export function runtimeForChoice(choice, slug) {
+  switch (choice.type) {
+    case "cpp":
+      // entry = built executable name (matches add_executable in cpp/CMakeLists.txt)
+      return { type: "cpp", entry: slug };
+    case "ros2":
+      // package = colcon package name; launch = node executable run on the robot
+      return { type: "ros2", rosClient: choice.rosClient, package: slug, launch: `${slug}_node` };
+    case "python":
+    default:
+      return { type: "python", entry: "main.py" };
+  }
 }
 
 export function applyTokens(dir, tokens) {
   for (const entry of readdirSync(dir)) {
+    if (entry === "node_modules" || entry === ".git" || entry === ".venv") continue;
     const full = resolve(dir, entry);
     if (statSync(full).isDirectory()) {
       applyTokens(full, tokens);
@@ -46,6 +122,12 @@ export function applyTokens(dir, tokens) {
 }
 
 // Derive naming tokens from a plugin directory name.
+// One id part (see PLUGIN_ID_RE): lowercase, single "-", starts with a letter.
+function idPart(name) {
+  const part = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return /^[a-z]/.test(part) ? part : part ? `plugin-${part}` : "plugin";
+}
+
 export function deriveNames(target) {
   const base = basename(target);
   const slug = base.toLowerCase().replace(/[^a-z0-9]+/g, "_");
@@ -55,7 +137,7 @@ export function deriveNames(target) {
     slug,
     pluginName,
     pluginClass: pluginName.replace(/\s+/g, ""),
-    pluginId: `com.example.${base.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`,
+    pluginId: `com.example.${idPart(base)}`,
   };
 }
 
@@ -74,16 +156,25 @@ function renameSlugPaths(dir, slug) {
 // Copy the ros2_ws/ overlay into a plugin and substitute the package slug into
 // every path segment. The dev Dockerfile is NOT scaffolded here — it lives in
 // the kit (cli/docker/) so authors can't edit it. Caller runs applyTokens after.
-export function overlayRos2(target, slug) {
-  cpSync(resolve(templatesDir, "ros2"), target, { recursive: true });
+//   rclpy  → templates/ros2      (ament_python)
+//   rclcpp → templates/ros2-cpp  (ament_cmake)
+export async function overlayRos2(target, slug, rosClient = "rclpy") {
+  const tmpl = rosClient === "rclcpp" ? "ros2-cpp" : "ros2";
+  await copyTemplate(resolve(templatesDir, tmpl), target);
   renameSlugPaths(resolve(target, "ros2_ws"), slug);
 }
 
+// Copy the cpp/ overlay (CMake project) into a plugin. Caller runs applyTokens after.
+export async function overlayCpp(target) {
+  await copyTemplate(resolve(templatesDir, "cpp"), target);
+}
+
 export async function runNew(args) {
   const opts = parseArgs(args, { booleans: ["yes", "no-install", "help"] });
   if (opts.help) {
     console.log(
-      "muscat-pk new [dir] [--type python|ros2] [--pm npm|yarn|pnpm|bun]\n" +
+      "muscat-pk new [dir] [--type python|cpp|ros2|ros2-cpp] [--pm npm|yarn|pnpm|bun]\n" +
+        "                 [--author <name>] [--email <email>] [--description <text>]\n" +
         "                 [--yes] [--no-install]",
     );
     return;
@@ -91,25 +182,53 @@ export async function runNew(args) {
 
   const dirArg = opts._[0];
   const targetName =
-    dirArg || (await prompt("Plugin directory name: ", "my-plugin"));
+    dirArg || (await prompt(color.cyan("Plugin directory name: "), "my-plugin"));
   const target = resolve(process.cwd(), targetName);
   if (existsSync(target) && readdirSync(target).length > 0) {
     throw new Error(`directory not empty: ${target}`);
   }
 
+  let authorArg = opts.author;
+  let emailArg = opts.email;
+  let descriptionArg = opts.description;
+
+  if (!opts.yes) {
+    if (!authorArg) authorArg = await prompt(color.cyan("Author name: "), "");
+    if (!emailArg) emailArg = await prompt(`${color.cyan("Email")} ${color.yellow("(required)")}: `, "");
+    if (!descriptionArg) descriptionArg = await prompt(color.cyan("Description (English): "), "");
+  }
+
   let type = opts.type;
   if (!type && !opts.yes) {
-    console.log("\n플러그인 타입을 선택하세요:");
-    console.log("  1) Python");
-    console.log("  2) ROS2(rclpy)");
-    const choice = await prompt("\n선택 [1/2, default: 1]: ", "1");
-    type = choice === "2" ? "ros2" : "python";
+    console.log(`\n${color.bold(color.cyan("Select the plugin type:"))}`);
+    console.log(`  ${color.green("1)") } ${color.bold("Python")}`);
+    console.log(`  ${color.green("2)") } ${color.bold("C++")}`);
+    console.log(`  ${color.green("3)") } ${color.bold("ROS2")} ${color.dim("(rclpy / Python)")}`);
+    console.log(`  ${color.green("4)") } ${color.bold("ROS2")} ${color.dim("(rclcpp / C++)")}`);
+    const choice = await prompt(`\n${color.cyan("선택")} ${color.dim("[1/2/3/4, default: 1]")}: `, "1");
+    type = { "2": "cpp", "3": "ros2", "4": "ros2-cpp" }[choice] ?? "python";
   }
   type = TYPES.includes(type) ? type : "python";
+  const runtimeChoice = TYPE_CHOICES[type];
+
+  // Auto-detect yarn workspace: if .yarnrc.yml exists anywhere up the tree, default to yarn.
+  function isInsideYarnWorkspace(dir) {
+    let cur = dir;
+    while (true) {
+      if (existsSync(resolve(cur, ".yarnrc.yml"))) return true;
+      const parent = resolve(cur, "..");
+      if (parent === cur) return false;
+      cur = parent;
+    }
+  }
 
   let pm = opts.pm;
   if (!pm && !opts.yes) {
-    pm = await prompt(`Package manager (${PMS.join("/")}) [npm]: `, "npm");
+    const defaultPm = isInsideYarnWorkspace(process.cwd()) ? "yarn" : "npm";
+    pm = await prompt(
+      `${color.cyan("Front-end package manager")} ${color.dim(`(${PMS.join("/")})`)} ${color.dim(`[${defaultPm}]`)}: `,
+      defaultPm,
+    );
   }
   pm = PMS.includes(pm) ? pm : "npm";
 
@@ -117,11 +236,21 @@ export async function runNew(args) {
 
   mkdirSync(target, { recursive: true });
 
-  // common(UI + main.py + requirements.txt + manifest/config)은 항상 포함.
-  // ros2면 ros2_ws/ 오버레이만 추가로 얹는다. python은 ros2_ws/가 없을 뿐 구조는 동일.
+  // common(UI + manifest/config)은 항상 포함. 백엔드 오버레이는 타입별로 얹는다.
+  //   python   → common의 py/ 사용
+  //   cpp      → cpp/ 오버레이, py/·requirements.txt 제거
+  //   ros2(*)  → ros2_ws/ 오버레이 (rclpy=ament_python, rclcpp=ament_cmake)
   log.step(`scaffolding ${type} plugin → ${target}`);
-  cpSync(resolve(templatesDir, "common"), target, { recursive: true });
-  if (type === "ros2") overlayRos2(target, slug);
+  await copyTemplate(resolve(templatesDir, "common"), target);
+  if (runtimeChoice.type === "ros2") await overlayRos2(target, slug, runtimeChoice.rosClient);
+  if (runtimeChoice.type === "cpp") {
+    await overlayCpp(target);
+    rmSync(resolve(target, "py"), { recursive: true, force: true });
+    rmSync(resolve(target, "requirements.txt"), { force: true });
+  }
+  if (runtimeChoice.type === "cpp" || runtimeChoice.rosClient === "rclcpp") {
+    await copyTemplate(resolve(templatesDir, "readme-cpp"), target);
+  }
 
   applyTokens(target, {
     __PLUGIN_ID__: pluginId,
@@ -129,16 +258,31 @@ export async function runNew(args) {
     __PLUGIN_DIR__: dir,
     __PLUGIN_SLUG__: slug,
     __PLUGIN_CLASS__: pluginClass,
+    __PLUGIN_AUTHOR__: authorArg || "",
+    __PLUGIN_EMAIL__: emailArg || "",
     __PM__: pm,
-    __RUNTIME_TYPE__: type,
+    __RUNTIME_TYPE__: runtimeChoice.type,
+    __RB_VERSION__: kitVersion(),
   });
 
+  // Write the correct runtime block into manifest.json (per-type fields).
+  const manifestPath = resolve(target, "manifest.json");
+  const manifestJson = JSON.parse(readFileSync(manifestPath, "utf8"));
+  manifestJson.runtime = runtimeForChoice(runtimeChoice, slug);
+  if (descriptionArg) manifestJson.description = { en: descriptionArg };
+  writeFileSync(manifestPath, JSON.stringify(manifestJson, null, 2) + "\n");
+
   // gitignore (templates can't ship a literal .gitignore via npm reliably)
   writeFileSync(
     resolve(target, ".gitignore"),
-    ["node_modules", "dist", ".venv", "*.zip", "ros2_ws/install", ""].join("\n"),
+    ["node_modules", "dist", ".muscat-dev", ".venv", "*.zip", "ros2_ws/install", "ros2_ws/build*", "ros2_ws/log", "cpp/build*", ""].join("\n"),
   );
 
+  // Rules for AI agents, generated from the same source as the MCP server's instructions.
+  writeFileSync(resolve(target, "AGENTS.md"), agentsMd({ pluginName }));
+  writeFileSync(resolve(target, "CLAUDE.md"), CLAUDE_MD);
+  writeFileSync(resolve(target, ".mcp.json"), MCP_JSON);
+
   if (!opts["no-install"]) {
     try {
       log.step(`installing JS deps with ${pm}…`);
@@ -146,61 +290,54 @@ export async function runNew(args) {
     } catch {
       log.warn(`'${pm} install' failed; run it manually in ${targetName}`);
     }
-  }
-
-  let noPython = false;
-  let venvFailed = false;
 
-  if (!opts["no-install"]) {
-    // Python venv (robot targets 3.12) — cross-platform.
-    // uv is preferred: handles uv-managed Pythons that break standard ensurepip.
-    try {
-      const venv = resolve(target, ".venv");
-      log.step("creating .venv + installing requirements…");
-      if (hasBin("uv")) {
-        execFileSync("uv", ["venv", venv, "--python", "3.12", "--seed"], { cwd: target, stdio: "inherit" });
-      } else if (hasBin("conda")) {
-        execFileSync("conda", ["create", "-p", venv, "python=3.12", "-y", "--quiet"], { cwd: target, stdio: "inherit" });
-      } else if (hasBin("python3.12") || hasBin("python3") || hasBin("python")) {
-        const { cmd, is312 } = detectPythonCmd();
-        if (!is312) log.warn("python3.12 not found; venv uses fallback python (robot targets 3.12).");
-        execFileSync(cmd[0], [...cmd.slice(1), "-m", "venv", venv], { cwd: target, stdio: "inherit" });
+    // 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 {
-        noPython = true;
-      }
-      if (!noPython) {
-        const py = venvPython(venv);
-        if (existsSync(resolve(target, "requirements.txt"))) {
-          execFileSync(py, ["-m", "pip", "install", "-q", "-r", "requirements.txt"], { cwd: target, stdio: "inherit" });
-        }
+        log.warn("Could not create .venv (no local Python/uv?) — skipping, Docker dev still works.");
       }
+    }
+    if (runtimeChoice.type === "cpp" || runtimeChoice.rosClient === "rclcpp") await prepareCppIde(target, runtimeChoice);
+  }
+
+  // git init (best-effort). Always runs, even nested inside another repo —
+  // delete target/.git if you don't want it.
+  if (hasBin("git")) {
+    try {
+      execSync("git init", { cwd: target, stdio: "ignore" });
+      execSync("git add -A", { cwd: target, stdio: "ignore" });
+      execSync('git commit -m "Initial commit from muscat-pk new" --no-verify', { cwd: target, stdio: "ignore" });
     } catch {
-      venvFailed = true;
+      log.warn("git init failed — run it manually if you want version control here.");
     }
-  } else {
-    noPython = !hasBin("uv") && !hasBin("conda") && !hasBin("python3.12") && !hasBin("python3") && !hasBin("python");
   }
 
-  log.ok(`created ${targetName} (type: ${type}, pm: ${pm})`);
-  log.info(`\n  cd ${targetName}`);
-  log.info(`  muscat-pk dev      # preview in mini-Muscat + back end`);
-  log.info(`  muscat-pk pack     # build a distributable ZIP\n`);
+  // The back end (python / cpp / ros2) runs in a Docker container that matches
+  // the robot — no local Python/toolchain setup needed. Only `none` skips it.
+  const needsDocker = runtimeChoice.type !== "none";
+  const noDocker = needsDocker && !hasBin("docker");
+
+  printNewSuccess({ targetName, type, pm });
 
   // ── post-scaffold environment warnings ───────────────────────────────────
   const noNode = !hasBin("node");
-  if (noNode || noPython || venvFailed) {
+  if (noNode || noDocker) {
     log.info("");
     if (noNode) {
       log.warn("Node.js not found. Install Node.js 20+ to run JS deps and dev:ui.");
       log.warn("  https://nodejs.org");
     }
-    if (noPython) {
-      log.warn("Python not found. Install Python 3.12 to run the backend.");
-      log.warn("  https://www.python.org/downloads/  (or: brew install python@3.12 / uv / conda)");
-      log.warn(`  Then: cd ${targetName} && python3.12 -m venv .venv && pip install -r requirements.txt`);
-    } else if (venvFailed) {
-      log.warn("venv setup failed. Create it manually:");
-      log.warn(`  cd ${targetName} && python3.12 -m venv .venv && pip install -r requirements.txt`);
+    if (noDocker) {
+      log.warn("Docker not found. The plugin back end runs in a container (matches the robot env).");
+      log.warn("  https://docs.docker.com/get-docker/");
     }
     log.info("");
   }

package/cli/src/pluginDevServer.mjs

@@ -0,0 +1,111 @@
+
+import { createRequire } from "node:module";
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const pluginRoot = resolve(process.argv[2]);
+const port = Number(process.argv[3] || "4181");
+const readyFile = process.argv[4] ? resolve(process.argv[4]) : "";
+
+
+process.chdir(pluginRoot);
+
+const require = createRequire(resolve(pluginRoot, "package.json"));
+
+const viteMod = await import(pathToFileURL(require.resolve("vite")));
+const createServer = viteMod.createServer ?? viteMod.default?.createServer;
+
+const BOOTSTRAP_PREFIX = "\0rb-bootstrap:";
+const PREAMBLE_ID = "\0rb-preamble";
+const bootstrapPlugin = {
+  name: "rb-plugin-bootstrap",
+  resolveId(id) {
+    if (id.startsWith("rb-bootstrap:")) return "\0" + id;
+    if (id === "rb-preamble") return PREAMBLE_ID;
+  },
+  load(id) {
+    if (id === PREAMBLE_ID) {
+      return `
+import RefreshRuntime from "/@react-refresh";
+RefreshRuntime.injectIntoGlobalHook(window);
+window.$RefreshReg$ = () => {};
+window.$RefreshSig$ = () => (type) => type;
+window.__vite_plugin_react_preamble_installed__ = true;
+`;
+    }
+    if (!id.startsWith(BOOTSTRAP_PREFIX)) return;
+    const ui = id.slice(BOOTSTRAP_PREFIX.length) || "content";
+    const entry = JSON.stringify(`muscat-ui-entry:${ui}`);
+    return `
+import "rb-preamble";
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { RbContext } from "@rainbow-robotics/plugin-ui/sdk";
+import { setHostServices } from "@rainbow-robotics/plugin-ui/host-ui";
+import { RbWs, createLazyRbSdk } from "@rainbow-robotics/plugin-ui/ws";
+import App from ${entry};
+
+// 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) {
+  import.meta.hot.accept(${entry}, (m) => {
+    if (!m || !m.default) return;
+    latestApp = m.default;
+    activeRender?.(latestApp);
+  });
+}
+
+export function mount(container, { socketUrl, pluginId, hostServices, data, onSave }) {
+  container.setAttribute("data-muscat-plugin-root", "");
+  container.setAttribute("data-muscat-plugin-id", pluginId);
+  setHostServices(hostServices);
+  // Lazy connect: don't block the first render on the WebSocket handshake
+  // (there may be no backend at all in dev, e.g. no robot reachable) — each rb
+  // method awaits this promise internally instead.
+  const wsPromise = RbWs.connect(socketUrl, pluginId);
+  const rb = createLazyRbSdk(wsPromise, hostServices, { data, onSave, pluginId });
+  const root = createRoot(container);
+  let mounted = true;
+  const render = (Component) => {
+    if (!mounted) return;
+    root.render(createElement(RbContext.Provider, { value: rb }, createElement(Component)));
+  };
+  const boundRender = (Component) => queueMicrotask(() => render(Component));
+  activeRender = boundRender;
+  render(latestApp);
+  return () => {
+    mounted = false;
+    // Don't clobber a newer mount's render (host defers unmount a microtask).
+    if (activeRender === boundRender) activeRender = null;
+    root.unmount();
+  };
+}
+`;
+  },
+};
+
+const server = await createServer({
+  root: pluginRoot,
+  configFile: resolve(pluginRoot, "vite.config.ts"),
+  mode: "development",
+  plugins: [bootstrapPlugin],
+  server: {
+    port,
+    strictPort: false,
+    cors: true,
+    hmr: { host: "localhost", protocol: "ws" },
+  },
+});
+
+await server.listen();
+const address = server.httpServer?.address();
+const actualPort = typeof address === "object" && address ? address.port : port;
+if (readyFile) {
+  writeFileSync(readyFile, JSON.stringify({ port: actualPort }), "utf8");
+}