@rainbow-robotics/muscat-plugin-kit 0.1.1

package/README.md

@@ -0,0 +1,27 @@
+# @rainbow-robotics/muscat-plugin-kit
+
+Muscat plugin developer kit: `muscat-pk`, `create-muscat-plugin`, build/pack,
+and preview-host.
+
+This package does **not** own the UI contract. Plugin source imports
+`@rainbow-robotics/plugin-ui/*`, and `muscat-pk build` leaves that package external so the
+robot/preview-host can provide its own runtime.
+
+```bash
+npm i -g @rainbow-robotics/muscat-plugin-kit
+muscat-pk new my-plugin --type sdk
+cd my-plugin
+muscat-pk build
+muscat-pk dev:ui
+muscat-pk pack
+```
+
+Published package responsibilities:
+
+| Package | Role |
+|---|---|
+| `@rainbow-robotics/plugin-ui` | Contract/runtime: rb-* elements, author React bindings, sandbox connect, host renderer |
+| `@rainbow-robotics/muscat-plugin-kit` | CLI, scaffold templates, build/pack, preview-host |
+
+The plugin ZIP contains plugin code and assets only. It relies on the host's
+import map for `@rainbow-robotics/plugin-ui`, `react`, and `react-dom`.

package/cli/README.md

@@ -0,0 +1,44 @@
+# @rainbow-robotics/muscat-plugin-kit (`muscat-pk`)
+
+CLI to scaffold, build, preview and pack Muscat plugins.
+
+Install/use it the same way an external plugin author will:
+
+```bash
+npm i -g @rainbow-robotics/muscat-plugin-kit
+muscat-pk new my-plugin
+```
+
+```bash
+muscat-pk new my-plugin [--type sdk|ros2|ui] [--pm npm|yarn|pnpm|bun] [--yes]
+muscat-pk build       # src/content.tsx -> dist/content.js (+ manifest, sandbox, assets)
+muscat-pk pack        # build (minified) + distributable ZIP with a size report
+muscat-pk dev:ui      # preview the plugin in a mini-Muscat (preview-host)
+muscat-pk dev:back    # run the back end (.venv + python main.py)
+muscat-pk dev         # dev:ui + dev:back
+muscat-pk update      # update @rainbow-robotics/muscat-plugin-kit and @rainbow-robotics/plugin-ui
+muscat-pk sdk list | sdk update [version]   # manage rainbow-rb-sdk (python)
+```
+
+## How it fits together
+
+- **Install/CLI package** is `@rainbow-robotics/muscat-plugin-kit`.
+- **Author API** comes from `@rainbow-robotics/plugin-ui`. `build` keeps that package
+  external so robot/preview-host can provide the runtime.
+- **`build`** bundles plugin code into ESM while externalizing
+  `@rainbow-robotics/plugin-ui`, React, and ReactDOM.
+- **`dev:ui`** builds the plugin then serves it inside the bundled preview host
+  at `/plugin-dev` — a real mini-Muscat shell with no robot/back end.
+
+`create-muscat-plugin <dir>` is the bin alias for `muscat-pk new`.
+
+## Update check
+
+On `dev` / `dev:ui` the kit checks the registry for a newer published version and,
+if found, suggests `muscat-pk update`. It is non-blocking (≤2s) and silent when
+offline.
+
+- `RB_REGISTRY` — registry base URL (default `https://registry.npmjs.org`).
+- `MUSCAT_PK_NO_UPDATE_CHECK=1` — skip the check.
+
+Full spec: [`docs/plugin-system/CREATE-CLI.md`](../../docs/plugin-system/CREATE-CLI.md).

package/cli/bin/create-muscat-plugin.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Thin alias: `npm create @rainbow/muscat-plugin <dir>` → `muscat-pk new <dir>`.
+import { runNew } from "../src/new.mjs";
+
+runNew(process.argv.slice(2)).catch((err) => {
+  console.error(`\n✖ ${err?.message || err}`);
+  process.exit(1);
+});

package/cli/bin/muscat-pk.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// muscat-pk — Muscat plugin developer CLI.
+// Subcommands: new, build, pack, dev, dev:ui, dev:back, update, sdk.
+import { runNew } from "../src/new.mjs";
+import { runBuild } from "../src/build.mjs";
+import { runPack } from "../src/pack.mjs";
+import { runDevUi } from "../src/devUi.mjs";
+import { runDevBack } from "../src/devBack.mjs";
+import { runDev } from "../src/dev.mjs";
+import { runUpdate } from "../src/update.mjs";
+import { runSdk } from "../src/sdk.mjs";
+
+const [, , cmd, ...args] = process.argv;
+
+const HELP = `muscat-pk — Muscat plugin kit
+
+Usage: muscat-pk <command> [options]
+
+Commands:
+  new [dir]        Scaffold a new plugin project
+  build            Build src/content.tsx -> dist/content.js (+ manifest, assets)
+  pack             Build then create a distributable ZIP (with size report)
+  dev              Run dev:ui and dev:back together
+  dev:ui           Preview the plugin in a mini-Muscat (preview-host)
+  dev:back         Run the plugin back end (python main.py)
+  update           Update @rainbow-robotics/muscat-plugin-kit and @rainbow-robotics/plugin-ui
+  sdk <list|update [version]>   Manage the python rainbow-rb-sdk version
+
+Run "muscat-pk <command> --help" for details.`;
+
+async function main() {
+  try {
+    switch (cmd) {
+      case "new":
+        return await runNew(args);
+      case "build":
+        return await runBuild(args);
+      case "pack":
+        return await runPack(args);
+      case "dev":
+        return await runDev(args);
+      case "dev:ui":
+        return await runDevUi(args);
+      case "dev:back":
+        return await runDevBack(args);
+      case "update":
+        return await runUpdate(args);
+      case "sdk":
+        return await runSdk(args);
+      case undefined:
+      case "-h":
+      case "--help":
+      case "help":
+        console.log(HELP);
+        return;
+      default:
+        console.error(`Unknown command: ${cmd}\n`);
+        console.log(HELP);
+        process.exitCode = 1;
+    }
+  } catch (err) {
+    console.error(`\n✖ ${err?.message || err}`);
+    process.exitCode = 1;
+  }
+}
+
+main();

package/cli/m5-e2e.mjs

@@ -0,0 +1,69 @@
+// M5 e2e: full developer loop. Verifies a plugin scaffolded by `muscat-pk new`,
+// built by `muscat-pk build`, and served by `muscat-pk dev:ui` renders inside the
+// preview-host mini-Muscat. Requires `muscat-pk dev:ui` running on :4180 for a
+// plugin whose name is "Mpk Test".
+// Run from repo root: node packages/rb-plugin-kit/cli/m5-e2e.mjs
+import { chromium } from "playwright-core";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const EXEC = join(
+  homedir(),
+  "Library/Caches/ms-playwright/chromium-1223/chrome-mac-arm64",
+  "Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing",
+);
+const BASE = "http://localhost:4180";
+const PLUGIN_NAME = "Mpk Test";
+
+const R = [];
+const ok = (n, c, e = "") => R.push({ n, c: !!c, e });
+
+const b = await chromium.launch({ executablePath: EXEC });
+const p = await b.newPage({ viewport: { width: 1280, height: 800 } });
+const errs = [];
+p.on("pageerror", (e) => errs.push(e.message));
+const logs = [];
+p.on("console", (m) => logs.push(m.text()));
+const wait = (t, to = 40000) =>
+  p.waitForFunction(
+    (x) => document.body && document.body.innerText.includes(x),
+    t,
+    { timeout: to },
+  );
+
+try {
+  await p.goto(`${BASE}/muscat/plugin`, { waitUntil: "commit" });
+  await wait("D.Board");
+  ok("mini-Muscat shell renders", true);
+  await wait(PLUGIN_NAME, 20000);
+  ok("scaffolded plugin loaded (LNB/content)", true);
+  await wait(`${PLUGIN_NAME} width`, 30000);
+  ok("scaffolded plugin content renders via rb-components", true);
+
+  // Grip action round-trips to the preview SDK
+  logs.length = 0;
+  await p.locator("button", { hasText: "Grip" }).first().click();
+  await p.waitForTimeout(1500);
+  ok(
+    "Grip action round-trips to host SDK",
+    logs.some((l) => l.includes("action") && l.includes("grip")),
+    logs.join(" | "),
+  );
+
+  const body = await p.evaluate(() => document.body.innerText);
+  ok("no API-failure toast", !body.includes("API Request Failed"));
+  ok("no page errors", errs.length === 0, errs.slice(0, 2).join(" | "));
+  await p.screenshot({ path: "/tmp/m5-built.png" });
+} catch (e) {
+  ok("e2e completed", false, String(e));
+} finally {
+  await b.close();
+}
+
+let pass = true;
+for (const r of R) {
+  console.log(`${r.c ? "PASS" : "FAIL"}  ${r.n}${!r.c && r.e ? "  :: " + r.e : ""}`);
+  if (!r.c) pass = false;
+}
+console.log(pass ? "\nALL CHECKS PASSED" : "\nSOME CHECKS FAILED");
+process.exit(pass ? 0 : 1);

package/cli/src/build.mjs

@@ -0,0 +1,95 @@
+// muscat-pk build — bundle src/content.tsx into dist/content.js and stage
+// manifest.json and assets/ for distribution.
+//
+// sandbox.html is generated by the CLI — plugin authors never manage it.
+// The import map always reflects the current plugin-ui entry set, so users
+// don't have to update it when the runtime adds new entries.
+//
+// The plugin author's `@rainbow-robotics/plugin-ui` and React imports are left external.
+// Muscat/robot and preview-host provide those modules through a sandbox import
+// map, so plugin ZIPs do not carry the UI runtime.
+import { cpSync, copyFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { buildWithFallback } from "./esbuild.mjs";
+import { findPluginRoot, log } from "./util.mjs";
+
+const SANDBOX_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>plugin sandbox</title>
+    <script type="importmap">
+      {
+        "imports": {
+          "@rainbow-robotics/plugin-ui/connect":  "/plugin-runtime/@rainbow-robotics/plugin-ui/connect.js",
+          "@rainbow-robotics/plugin-ui/react":    "/plugin-runtime/@rainbow-robotics/plugin-ui/react.js",
+          "@rainbow-robotics/plugin-ui/sdk":      "/plugin-runtime/@rainbow-robotics/plugin-ui/sdk.js",
+          "@rainbow-robotics/plugin-ui/elements": "/plugin-runtime/@rainbow-robotics/plugin-ui/elements.js",
+          "react":                       "/plugin-runtime/vendor/react.js",
+          "react/jsx-runtime":           "/plugin-runtime/vendor/react-jsx-runtime.js",
+          "react/jsx-dev-runtime":       "/plugin-runtime/vendor/react-jsx-dev-runtime.js",
+          "react-dom/client":            "/plugin-runtime/vendor/react-dom-client.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <script type="module" src="./content.js"></script>
+  </body>
+</html>
+`;
+
+const HOST_PROVIDED_EXTERNALS = [
+  "@rainbow-robotics/plugin-ui",
+  "@rainbow-robotics/plugin-ui/*",
+  "react",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-dom",
+  "react-dom/*",
+];
+
+export async function buildPlugin({ root, minify = false } = {}) {
+  const pluginRoot = root ?? findPluginRoot();
+  const entry = resolve(pluginRoot, "src/content.tsx");
+  if (!existsSync(entry)) {
+    throw new Error(`missing entry: ${entry}`);
+  }
+  const distDir = resolve(pluginRoot, "dist");
+  rmSync(distDir, { recursive: true, force: true });
+  mkdirSync(distDir, { recursive: true });
+
+  log.step("bundling src/content.tsx → dist/content.js");
+  await buildWithFallback({
+    entryPoints: [entry],
+    outfile: resolve(distDir, "content.js"),
+    bundle: true,
+    format: "esm",
+    jsx: "automatic",
+    minify,
+    loader: { ".tsx": "tsx", ".ts": "ts", ".svg": "dataurl" },
+    define: { "process.env.NODE_ENV": JSON.stringify(minify ? "production" : "development") },
+    external: HOST_PROVIDED_EXTERNALS,
+    logLevel: "warning",
+  });
+
+  // Stage distribution files.
+  const manifestSrc = resolve(pluginRoot, "manifest.json");
+  if (existsSync(manifestSrc)) copyFileSync(manifestSrc, resolve(distDir, "manifest.json"));
+
+  // Generate sandbox.html — plugin authors don't manage this file.
+  writeFileSync(resolve(distDir, "sandbox.html"), SANDBOX_HTML, "utf8");
+  log.step("generated dist/sandbox.html");
+  const assetsSrc = resolve(pluginRoot, "assets");
+  if (existsSync(assetsSrc)) {
+    cpSync(assetsSrc, resolve(distDir, "assets"), { recursive: true });
+  }
+
+  log.ok(`built → ${distDir}`);
+  return { pluginRoot, distDir };
+}
+
+export async function runBuild(args) {
+  const minify = args.includes("--minify");
+  await buildPlugin({ minify });
+}

package/cli/src/check-package.mjs

@@ -0,0 +1,28 @@
+import { execFileSync } from "node:child_process";
+import { readdirSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const roots = [resolve(root, "cli"), resolve(root, "preview-host")];
+
+function* mjsFiles(dir) {
+  for (const entry of readdirSync(dir)) {
+    const full = resolve(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      if (entry === "dist" || entry === "runtime" || entry === "templates") {
+        continue;
+      }
+      yield* mjsFiles(full);
+    } else if (entry.endsWith(".mjs")) {
+      yield full;
+    }
+  }
+}
+
+for (const dir of roots) {
+  for (const file of mjsFiles(dir)) {
+    execFileSync(process.execPath, ["--check", file], { stdio: "inherit" });
+  }
+}

package/cli/src/dev.mjs

@@ -0,0 +1,11 @@
+// muscat-pk dev — run dev:ui and dev:back together.
+import { runDevUi } from "./devUi.mjs";
+import { runDevBack } from "./devBack.mjs";
+import { log } from "./util.mjs";
+
+export async function runDev(args = []) {
+  log.step("starting dev:ui + dev:back");
+  // dev:back runs to completion / detaches on its own; dev:ui owns the process.
+  runDevBack().catch((e) => log.warn(`dev:back: ${e.message}`));
+  await runDevUi(args);
+}

package/cli/src/devBack.mjs

@@ -0,0 +1,65 @@
+// muscat-pk dev:back — run the plugin back end.
+//   sdk  : create/refresh .venv then `python main.py`
+//   ros2 : requires Docker (Jazzy container) — guidance only here
+//   none : nothing to run
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { findPluginRoot, log } from "./util.mjs";
+
+function manifestRuntime(root) {
+  try {
+    const m = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
+    return m.runtime?.type ?? "none";
+  } catch {
+    return "none";
+  }
+}
+
+export async function runDevBack() {
+  const root = findPluginRoot();
+  const type = manifestRuntime(root);
+
+  if (type === "none") {
+    log.info("runtime: none — no back end to run.");
+    return;
+  }
+
+  if (type === "ros2") {
+    log.warn(
+      "ROS2 back end runs in a Jazzy + Python 3.12 Docker container.\n" +
+        "  Ensure Docker is running, then: muscat-pk dev:back (container support TBD).",
+    );
+    return;
+  }
+
+  // python / rb_sdk
+  const venv = resolve(root, ".venv");
+  const py = process.platform === "win32"
+    ? resolve(venv, "Scripts", "python.exe")
+    : resolve(venv, "bin", "python");
+
+  if (!existsSync(py)) {
+    log.step("creating .venv (python3.12 preferred)…");
+    const python = spawnSync("python3.12", ["--version"]).status === 0
+      ? "python3.12"
+      : "python3";
+    if (python !== "python3.12") {
+      log.warn("python3.12 not found; using python3 (robot targets 3.12).");
+    }
+    spawnSync(python, ["-m", "venv", venv], { cwd: root, stdio: "inherit" });
+  }
+
+  const reqs = resolve(root, "requirements.txt");
+  if (existsSync(reqs)) {
+    log.step("pip install -r requirements.txt…");
+    spawnSync(py, ["-m", "pip", "install", "-q", "-r", reqs], {
+      cwd: root,
+      stdio: "inherit",
+    });
+  }
+
+  log.step("python main.py");
+  const child = spawn(py, ["main.py"], { cwd: root, stdio: "inherit" });
+  child.on("exit", (code) => process.exit(code ?? 0));
+}

package/cli/src/devUi.mjs

@@ -0,0 +1,50 @@
+// muscat-pk dev:ui — preview the plugin inside a mini-Muscat (preview-host).
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { buildPlugin } from "./build.mjs";
+import { checkKitUpdate, findPluginRoot, kitRoot, log } from "./util.mjs";
+
+/** Resolve @rainbow-robotics/preview-host package root.
+ *  Works in monorepo (yarn workspace hoisting) and when both packages are
+ *  installed as deps of the plugin project. */
+function findPreviewHostRoot() {
+  try {
+    const req = createRequire(import.meta.url);
+    return dirname(req.resolve("@rainbow-robotics/preview-host/package.json"));
+  } catch {
+    // fallback: sibling package in muscat-plugin-kit/ workspace
+    return resolve(kitRoot, "../preview-host");
+  }
+}
+
+export async function runDevUi(args = []) {
+  const portIdx = args.indexOf("--port");
+  const port = portIdx !== -1 ? args[portIdx + 1] : "4180";
+
+  await checkKitUpdate();
+  const { distDir } = await buildPlugin();
+
+  const previewRoot = findPreviewHostRoot();
+  const serveEntry = resolve(previewRoot, "serve.mjs");
+  if (!existsSync(resolve(previewRoot, "dist", "index.html"))) {
+    log.step("building preview-host bundle (first run)…");
+    await new Promise((res, rej) => {
+      const p = spawn("node", [resolve(previewRoot, "build.mjs")], {
+        stdio: "inherit",
+      });
+      p.on("exit", (c) => (c === 0 ? res() : rej(new Error("preview-host build failed"))));
+    });
+  }
+
+  log.step(`starting preview-host on :${port}`);
+  const child = spawn(
+    "node",
+    [serveEntry, "--plugin", distDir, "--port", String(port)],
+    { stdio: "inherit" },
+  );
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+export { findPluginRoot };

package/cli/src/esbuild.mjs

@@ -0,0 +1,15 @@
+export async function buildWithFallback(options) {
+  const native = await import("esbuild");
+  try {
+    return await native.build(options);
+  } catch (error) {
+    const message = String(error?.message || error);
+    if (!message.includes("another platform")) {
+      throw error;
+    }
+
+    const wasm = await import("esbuild-wasm");
+    console.warn("[muscat-pk] native esbuild binary mismatch; falling back to esbuild-wasm");
+    return wasm.build(options);
+  }
+}

package/cli/src/new.mjs

@@ -0,0 +1,125 @@
+// muscat-pk new — scaffold a new plugin project from templates.
+import { execSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { basename, resolve } from "node:path";
+import { parseArgs, templatesDir, log } from "./util.mjs";
+
+const TYPES = ["sdk", "ros2", "ui"];
+const PMS = ["npm", "yarn", "pnpm", "bun"];
+const DEFAULT_SDK_VERSION = "2.4.1";
+
+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 applyTokens(dir, tokens) {
+  for (const entry of readdirSync(dir)) {
+    const full = resolve(dir, entry);
+    if (statSync(full).isDirectory()) {
+      applyTokens(full, tokens);
+      continue;
+    }
+    if (/\.(png|jpg|jpeg|gif|woff2?|glb|mp3)$/.test(entry)) continue;
+    let content = readFileSync(full, "utf8");
+    let changed = false;
+    for (const [k, v] of Object.entries(tokens)) {
+      if (content.includes(k)) {
+        content = content.split(k).join(v);
+        changed = true;
+      }
+    }
+    if (changed) writeFileSync(full, content);
+  }
+}
+
+export async function runNew(args) {
+  const opts = parseArgs(args, { booleans: ["yes", "no-install", "help"] });
+  if (opts.help) {
+    console.log(
+      "muscat-pk new [dir] [--type sdk|ros2|ui] [--pm npm|yarn|pnpm|bun]\n" +
+        "                 [--sdk-version <v>] [--yes] [--no-install]",
+    );
+    return;
+  }
+
+  const dirArg = opts._[0];
+  const targetName =
+    dirArg || (await prompt("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 type = opts.type;
+  if (!type && !opts.yes) {
+    type = await prompt(`Plugin type (${TYPES.join("/")}) [sdk]: `, "sdk");
+  }
+  type = TYPES.includes(type) ? type : "sdk";
+
+  let pm = opts.pm;
+  if (!pm && !opts.yes) {
+    pm = await prompt(`Package manager (${PMS.join("/")}) [npm]: `, "npm");
+  }
+  pm = PMS.includes(pm) ? pm : "npm";
+
+  const sdkVersion = opts["sdk-version"] || DEFAULT_SDK_VERSION;
+  const pluginName = basename(target)
+    .replace(/[-_]/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+  const pluginId = `com.example.${basename(target).toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+
+  mkdirSync(target, { recursive: true });
+
+  log.step(`scaffolding ${type} plugin → ${target}`);
+  cpSync(resolve(templatesDir, "common"), target, { recursive: true });
+  if (type === "sdk") {
+    cpSync(resolve(templatesDir, "sdk"), target, { recursive: true });
+  } else if (type === "ros2") {
+    if (existsSync(resolve(templatesDir, "ros2-rclpy"))) {
+      cpSync(resolve(templatesDir, "ros2-rclpy"), target, { recursive: true });
+    } else {
+      log.warn("ros2 template not bundled; scaffolding UI-only base");
+    }
+  }
+
+  applyTokens(target, {
+    __PLUGIN_ID__: pluginId,
+    __PLUGIN_NAME__: pluginName,
+    __SDK_VERSION__: sdkVersion,
+    __PM__: pm,
+    __RUNTIME_TYPE__: type === "ui" ? "none" : type === "ros2" ? "ros2" : "python",
+  });
+
+  // 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"),
+  );
+
+  if (!opts["no-install"]) {
+    try {
+      log.step(`installing JS deps with ${pm}…`);
+      execSync(`${pm} install`, { cwd: target, stdio: "inherit" });
+    } catch {
+      log.warn(`'${pm} install' failed; run it manually in ${targetName}`);
+    }
+  }
+
+  log.ok(`created ${targetName} (type: ${type}, pm: ${pm})`);
+  log.info(`\n  cd ${targetName}`);
+  log.info(`  ${pm} run dev      # preview in mini-Muscat + back end`);
+  log.info(`  ${pm} run pack     # build a distributable ZIP\n`);
+}

package/cli/src/pack.mjs

@@ -0,0 +1,58 @@
+// muscat-pk pack — build, then create a distributable ZIP with a size report.
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { buildPlugin } from "./build.mjs";
+import { findPluginRoot, humanSize, log } from "./util.mjs";
+
+function dirSize(dir) {
+  let total = 0;
+  for (const entry of readdirSync(dir)) {
+    const full = resolve(dir, entry);
+    const st = statSync(full);
+    total += st.isDirectory() ? dirSize(full) : st.size;
+  }
+  return total;
+}
+
+export async function runPack() {
+  const pluginRoot = findPluginRoot();
+  await buildPlugin({ root: pluginRoot, minify: true });
+
+  const manifest = JSON.parse(
+    readFileSync(resolve(pluginRoot, "manifest.json"), "utf8"),
+  );
+  const zipName = `${basename(pluginRoot)}-${manifest.version || "0.0.0"}.zip`;
+  const zipPath = resolve(pluginRoot, zipName);
+  rmSync(zipPath, { force: true });
+
+  // Contents: dist/ + back-end files if present.
+  const entries = ["dist"];
+  for (const f of ["main.py", "requirements.txt"]) {
+    if (existsSync(resolve(pluginRoot, f))) entries.push(f);
+  }
+  if (existsSync(resolve(pluginRoot, "ros2_ws/install"))) {
+    entries.push("ros2_ws/install");
+  }
+
+  log.step(`packing ${entries.join(", ")} → ${zipName}`);
+  try {
+    execSync(`zip -r -q "${zipPath}" ${entries.map((e) => `"${e}"`).join(" ")}`, {
+      cwd: pluginRoot,
+      stdio: "inherit",
+    });
+  } catch {
+    throw new Error("`zip` not found. Install zip or pack manually.");
+  }
+
+  const zipBytes = statSync(zipPath).size;
+  log.ok(`${zipName}   ${humanSize(zipBytes)}`);
+  for (const e of entries) {
+    const full = resolve(pluginRoot, e);
+    const size = statSync(full).isDirectory() ? dirSize(full) : statSync(full).size;
+    log.info(`  ├─ ${e}   ${humanSize(size)}`);
+  }
+  log.warn(
+    "robot install checks free space via GET /plugin/capacity (507 if low).",
+  );
+}

package/cli/src/sdk.mjs

@@ -0,0 +1,67 @@
+// muscat-pk sdk <list|update [version]> — manage the python rainbow-rb-sdk.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { findPluginRoot, log } from "./util.mjs";
+
+const PKG = "rainbow-rb-sdk";
+
+async function fetchVersions() {
+  try {
+    const res = await fetch(`https://pypi.org/pypi/${PKG}/json`);
+    if (!res.ok) return [];
+    const data = await res.json();
+    return Object.keys(data.releases || {}).sort((a, b) =>
+      b.localeCompare(a, undefined, { numeric: true }),
+    );
+  } catch {
+    return [];
+  }
+}
+
+export async function runSdk(args = []) {
+  const sub = args[0];
+  const root = findPluginRoot();
+  const reqs = resolve(root, "requirements.txt");
+
+  if (sub === "list") {
+    const versions = await fetchVersions();
+    if (!versions.length) {
+      log.warn("could not fetch versions (offline?).");
+      return;
+    }
+    log.info(`${PKG} versions:\n  ${versions.slice(0, 12).join("\n  ")}`);
+    return;
+  }
+
+  if (sub === "update") {
+    let version = args[1];
+    if (!version) {
+      const versions = await fetchVersions();
+      version = versions[0] || "latest";
+    }
+    let content = existsSync(reqs) ? readFileSync(reqs, "utf8") : "";
+    const line = `${PKG}==${version}`;
+    if (new RegExp(`^${PKG}==`, "m").test(content)) {
+      content = content.replace(new RegExp(`^${PKG}==.*$`, "m"), line);
+    } else {
+      content = (content ? content.trimEnd() + "\n" : "") + line + "\n";
+    }
+    writeFileSync(reqs, content);
+    log.ok(`requirements.txt → ${line}`);
+
+    const py = resolve(root, ".venv", "bin", "python");
+    if (existsSync(py)) {
+      log.step("pip install -r requirements.txt…");
+      spawnSync(py, ["-m", "pip", "install", "-q", "-r", reqs], {
+        cwd: root,
+        stdio: "inherit",
+      });
+    } else {
+      log.warn(".venv not found; run `muscat-pk dev:back` to install.");
+    }
+    return;
+  }
+
+  log.info("Usage: muscat-pk sdk <list|update [version]>");
+}

package/cli/src/update.mjs

@@ -0,0 +1,52 @@
+// muscat-pk update — update the JS plugin kit and host-provided UI contract.
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { findPluginRoot, KIT_PUBLISHED_NAME, log, parseArgs } from "./util.mjs";
+
+const PLUGIN_UI_PACKAGE = "@rainbow-robotics/plugin-ui";
+
+function detectPm(root) {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
+    if (pkg.packageManager) return pkg.packageManager.split("@")[0];
+  } catch {
+    /* ignore */
+  }
+  if (existsSync(resolve(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(resolve(root, "yarn.lock"))) return "yarn";
+  if (existsSync(resolve(root, "bun.lockb"))) return "bun";
+  return "npm";
+}
+
+export async function runUpdate(args = []) {
+  const root = findPluginRoot();
+  const pm = detectPm(root);
+  const opts = parseArgs(args);
+
+  const range =
+    opts._[0] ||
+    opts.version ||
+    opts["muscat-plugin-kit"] ||
+    opts["plugin-ui"] ||
+    "latest";
+  const list = [
+    `${KIT_PUBLISHED_NAME}@${range}`,
+    `${PLUGIN_UI_PACKAGE}@${range}`,
+  ];
+
+  const cmd =
+    pm === "npm"
+      ? `npm install ${list.join(" ")}`
+      : pm === "yarn"
+        ? `yarn add ${list.join(" ")}`
+        : `${pm} add ${list.join(" ")}`;
+
+  log.step(`${pm}: ${list.join(", ")}`);
+  try {
+    execSync(cmd, { cwd: root, stdio: "inherit" });
+    log.ok("kit packages updated");
+  } catch {
+    log.warn("update failed (offline?). Run manually:\n  " + cmd);
+  }
+}

package/cli/src/util.mjs

@@ -0,0 +1,120 @@
+// Shared helpers for muscat-pk.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Published install/CLI package name. Author imports use @rainbow-robotics/plugin-ui separately. */
+export const KIT_PUBLISHED_NAME = "@rainbow-robotics/muscat-plugin-kit";
+
+// This file lives at <pkg>/cli/src/util.mjs → package root is two levels up.
+export const kitRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+export const templatesDir = resolve(kitRoot, "cli/templates");
+
+/** Parse `--flag value` and `--bool` from argv into an object. */
+export function parseArgs(args, { booleans = [] } = {}) {
+  const out = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      if (booleans.includes(key)) {
+        out[key] = true;
+      } else if (args[i + 1] && !args[i + 1].startsWith("--")) {
+        out[key] = args[++i];
+      } else {
+        out[key] = true;
+      }
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+/** Walk up from cwd to find the plugin project root (has manifest.json). */
+export function findPluginRoot(start = process.cwd()) {
+  let dir = resolve(start);
+  for (;;) {
+    if (existsSync(resolve(dir, "manifest.json"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "Not a muscat plugin project (no manifest.json found). Run from your plugin directory.",
+  );
+}
+
+export const log = {
+  info: (...m) => console.log(...m),
+  step: (...m) => console.log("›", ...m),
+  ok: (...m) => console.log("✓", ...m),
+  warn: (...m) => console.warn("⚠", ...m),
+};
+
+export function humanSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+/** This kit's installed version (from its package.json). */
+export function kitVersion() {
+  try {
+    return JSON.parse(readFileSync(resolve(kitRoot, "package.json"), "utf8"))
+      .version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/** Compare semver-ish "x.y.z[-pre]". Returns true if `a` > `b` (release parts). */
+export function isNewer(a, b) {
+  const parse = (v) =>
+    String(v)
+      .split("-")[0]
+      .split(".")
+      .map((n) => parseInt(n, 10) || 0);
+  const [a1, a2, a3] = parse(a);
+  const [b1, b2, b3] = parse(b);
+  if (a1 !== b1) return a1 > b1;
+  if (a2 !== b2) return a2 > b2;
+  return a3 > b3;
+}
+
+/**
+ * Non-blocking check for a newer published kit. Prints an update suggestion if
+ * one exists. Fails silently when offline. Honors `RB_REGISTRY` and is skipped
+ * by `MUSCAT_PK_NO_UPDATE_CHECK=1`.
+ */
+export async function checkKitUpdate({ timeoutMs = 2000 } = {}) {
+  if (process.env.MUSCAT_PK_NO_UPDATE_CHECK === "1") return;
+  const current = kitVersion();
+  const registry = (process.env.RB_REGISTRY || "https://registry.npmjs.org").replace(/\/$/, "");
+  try {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    const res = await fetch(
+      `${registry}/${encodeURIComponent(KIT_PUBLISHED_NAME)}/latest`,
+      { signal: ac.signal },
+    );
+    clearTimeout(timer);
+    if (!res.ok) return;
+    const { version: latest } = await res.json();
+    if (latest && isNewer(latest, current)) {
+      const line = "─".repeat(58);
+      console.log(
+        [
+          "",
+          line,
+          `  muscat-plugin-kit 새 버전이 있습니다: ${current} → ${latest}`,
+          `  업데이트:  muscat-pk update`,
+          line,
+          "",
+        ].join("\n"),
+      );
+    }
+  } catch {
+    /* offline or registry unreachable — ignore */
+  }
+}

package/cli/templates/common/README.md

@@ -0,0 +1,16 @@
+# __PLUGIN_NAME__
+
+A Muscat plugin scaffolded with `muscat-pk`.
+
+```bash
+__PM__ run dev        # preview in a mini-Muscat (preview-host) + back end
+__PM__ run dev:ui     # UI preview only
+__PM__ run pack       # build a distributable ZIP
+```
+
+- `src/content.tsx` — your plugin UI. Import components from `@rainbow-robotics/plugin-ui/react`.
+- `manifest.json` — id, contributions, actions, runtime.
+- `assets/` — static assets (icons referenced from the manifest).
+- `main.py` — (sdk runtime) back-end handler using `rainbow-rb-sdk`.
+
+The plugin only emits `rb-*` name tags; Muscat renders the real components.

package/cli/templates/common/assets/icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="1em" height="1em" fill="none">
+  <path fill="currentColor" d="M16 3a13 13 0 1 0 0 26 13 13 0 0 0 0-26Zm0 4a3 3 0 0 1 3 3v2.18a3 3 0 0 1 0 5.64V20a3 3 0 1 1-6 0v-2.18a3 3 0 0 1 0-5.64V10a3 3 0 0 1 3-3Z"/>
+</svg>

package/cli/templates/common/manifest.json

@@ -0,0 +1,25 @@
+{
+  "id": "__PLUGIN_ID__",
+  "name": "__PLUGIN_NAME__",
+  "version": "1.0.0",
+  "minAppVersion": "2.0.0",
+  "icon": "assets/icon.svg",
+  "contributes": [
+    { "point": "program.panel", "label": "__PLUGIN_NAME__", "icon": "assets/icon.svg" },
+    { "point": "lnb", "label": "__PLUGIN_NAME__", "icon": "assets/icon.svg" },
+    {
+      "point": "header.toolbar",
+      "label": "__PLUGIN_NAME__",
+      "icon": "assets/icon.svg",
+      "opens": "popover"
+    }
+  ],
+  "actions": [
+    {
+      "id": "grip",
+      "topic": "rby2/plugin/__PLUGIN_ID__/grip",
+      "schema": { "width": "number" }
+    }
+  ],
+  "runtime": { "type": "__RUNTIME_TYPE__", "entry": "main.py" }
+}

package/cli/templates/common/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "__PLUGIN_ID__",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "muscat-pk dev",
+    "dev:ui": "muscat-pk dev:ui",
+    "dev:back": "muscat-pk dev:back",
+    "build": "muscat-pk build",
+    "pack": "muscat-pk pack"
+  },
+  "dependencies": {
+    "@rainbow-robotics/plugin-ui": "^0.1.0"
+  },
+  "devDependencies": {
+    "@rainbow-robotics/muscat-plugin-kit": "^0.1.0",
+    "@rainbow-robotics/preview-host": "^0.1.0",
+    "typescript": "^5.8.0",
+    "vite": "^6.4.1"
+  }
+}

package/cli/templates/common/src/content.tsx

@@ -0,0 +1,32 @@
+import { useState } from "react";
+import { connect } from "@rainbow-robotics/plugin-ui/connect";
+import { Slider, Button, Text, Switch, useRb } from "@rainbow-robotics/plugin-ui/react";
+
+function App() {
+  const rb = useRb();
+  const [width, setWidth] = useState(20);
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Text>__PLUGIN_NAME__ width: {width}</Text>
+      <Slider
+        value={width}
+        min={0}
+        max={100}
+        onChange={(event: { detail?: number }) => setWidth(event.detail ?? 0)}
+      />
+      <Button label="Grip" onPress={() => rb.action("grip", { width })} />
+      <Switch
+        checked={open}
+        onChange={(event: { detail?: boolean }) => {
+          const next = event.detail ?? false;
+          setOpen(next);
+          rb.notify(next ? "opened" : "closed", "info");
+        }}
+      />
+    </>
+  );
+}
+
+connect(App);

package/cli/templates/common/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "lib": ["DOM", "DOM.Iterable", "ESNext"]
+  },
+  "include": ["src"]
+}

package/cli/templates/common/vite.config.ts

@@ -0,0 +1,29 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+// Plugin UI and React are provided by Muscat/preview-host via import map.
+// They must NOT be bundled into the plugin ZIP.
+const HOST_PROVIDED_EXTERNALS = [
+  "@rainbow-robotics/plugin-ui",
+  /^@rainbow\/plugin-ui\//,
+  "react",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-dom",
+  /^react-dom\//,
+];
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    lib: {
+      entry: "src/content.tsx",
+      formats: ["es"],
+      fileName: "content",
+    },
+    outDir: "dist",
+    rollupOptions: {
+      external: HOST_PROVIDED_EXTERNALS,
+    },
+  },
+});

package/cli/templates/sdk/main.py

@@ -0,0 +1,21 @@
+import asyncio
+
+from rb_sdk import RBManipulateSDK  # PyPI: rainbow-rb-sdk
+
+sdk = RBManipulateSDK()
+
+
+async def on_action(payload: dict):
+    # Matches manifest.actions[].topic — handle the "grip" action here.
+    width = payload.get("width")
+    print(f"[__PLUGIN_NAME__] grip width={width}")
+    # TODO: drive the robot via the SDK.
+
+
+async def main():
+    await sdk.subscribe("rby2/plugin/__PLUGIN_ID__/grip", on_action)
+    await sdk.spin()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/cli/templates/sdk/requirements.txt

@@ -0,0 +1 @@
+rainbow-rb-sdk==__SDK_VERSION__

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@rainbow-robotics/muscat-plugin-kit",
+  "version": "0.1.1",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "description": "Muscat plugin kit: muscat-pk CLI, plugin scaffold, build/pack/dev tools",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "create-muscat-plugin": "./cli/bin/create-muscat-plugin.mjs",
+    "muscat-pk": "./cli/bin/muscat-pk.mjs"
+  },
+  "files": [
+    "cli",
+    "package.json"
+  ],
+  "scripts": {
+    "lint": "node cli/src/check-package.mjs",
+    "check": "node cli/src/check-package.mjs",
+    "check-types": "node cli/src/check-package.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.22.0",
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^22.13.9",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4"
+  },
+  "dependencies": {
+    "@rainbow-robotics/preview-host": "*",
+    "esbuild": "^0.25.0",
+    "esbuild-wasm": "^0.25.0"
+  }
+}