@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.4 → 0.1.2-dev.6

package/cli/src/new.mjs

@@ -1,21 +1,21 @@
 // muscat-pk new — scaffold a new plugin project from templates.
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 import {
   cpSync,
   existsSync,
   mkdirSync,
   readFileSync,
   readdirSync,
+  renameSync,
   statSync,
   writeFileSync,
 } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { basename, resolve } from "node:path";
-import { parseArgs, templatesDir, log } from "./util.mjs";
+import { detectPythonCmd, hasBin, parseArgs, templatesDir, log, venvPython } from "./util.mjs";
 
-const TYPES = ["sdk", "ros2", "ui"];
+const TYPES = ["python", "ros2"];
 const PMS = ["npm", "yarn", "pnpm", "bun"];
-const DEFAULT_SDK_VERSION = "2.4.1";
 
 async function prompt(question, fallback) {
   if (!process.stdin.isTTY) return fallback;
@@ -25,7 +25,7 @@ async function prompt(question, fallback) {
   return answer || fallback;
 }
 
-function applyTokens(dir, tokens) {
+export function applyTokens(dir, tokens) {
   for (const entry of readdirSync(dir)) {
     const full = resolve(dir, entry);
     if (statSync(full).isDirectory()) {
@@ -45,12 +45,46 @@ function applyTokens(dir, tokens) {
   }
 }
 
+// Derive naming tokens from a plugin directory name.
+export function deriveNames(target) {
+  const base = basename(target);
+  const slug = base.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+  const pluginName = base.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return {
+    dir: base,
+    slug,
+    pluginName,
+    pluginClass: pluginName.replace(/\s+/g, ""),
+    pluginId: `com.example.${base.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`,
+  };
+}
+
+// Recursively rename any file/dir whose name contains __PLUGIN_SLUG__.
+function renameSlugPaths(dir, slug) {
+  for (const entry of readdirSync(dir)) {
+    let full = resolve(dir, entry);
+    if (entry.includes("__PLUGIN_SLUG__")) {
+      full = resolve(dir, entry.split("__PLUGIN_SLUG__").join(slug));
+      renameSync(resolve(dir, entry), full);
+    }
+    if (statSync(full).isDirectory()) renameSlugPaths(full, 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 });
+  renameSlugPaths(resolve(target, "ros2_ws"), slug);
+}
+
 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]",
+      "muscat-pk new [dir] [--type python|ros2] [--pm npm|yarn|pnpm|bun]\n" +
+        "                 [--yes] [--no-install]",
     );
     return;
   }
@@ -65,9 +99,13 @@ export async function runNew(args) {
 
   let type = opts.type;
   if (!type && !opts.yes) {
-    type = await prompt(`Plugin type (${TYPES.join("/")}) [sdk]: `, "sdk");
+    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";
   }
-  type = TYPES.includes(type) ? type : "sdk";
+  type = TYPES.includes(type) ? type : "python";
 
   let pm = opts.pm;
   if (!pm && !opts.yes) {
@@ -75,32 +113,24 @@ export async function runNew(args) {
   }
   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, "-")}`;
+  const { dir, slug, pluginName, pluginClass, pluginId } = deriveNames(target);
 
   mkdirSync(target, { recursive: true });
 
+  // common(UI + main.py + requirements.txt + manifest/config)은 항상 포함.
+  // ros2면 ros2_ws/ 오버레이만 추가로 얹는다. python은 ros2_ws/가 없을 뿐 구조는 동일.
   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");
-    }
-  }
+  if (type === "ros2") overlayRos2(target, slug);
 
   applyTokens(target, {
     __PLUGIN_ID__: pluginId,
     __PLUGIN_NAME__: pluginName,
-    __SDK_VERSION__: sdkVersion,
+    __PLUGIN_DIR__: dir,
+    __PLUGIN_SLUG__: slug,
+    __PLUGIN_CLASS__: pluginClass,
     __PM__: pm,
-    __RUNTIME_TYPE__: type === "ui" ? "none" : type === "ros2" ? "ros2" : "python",
+    __RUNTIME_TYPE__: type,
   });
 
   // gitignore (templates can't ship a literal .gitignore via npm reliably)
@@ -118,8 +148,60 @@ export async function runNew(args) {
     }
   }
 
+  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" });
+      } 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" });
+        }
+      }
+    } catch {
+      venvFailed = true;
+    }
+  } 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(`  ${pm} run dev      # preview in mini-Muscat + back end`);
-  log.info(`  ${pm} run pack     # build a distributable ZIP\n`);
+  log.info(`  muscat-pk dev      # preview in mini-Muscat + back end`);
+  log.info(`  muscat-pk pack     # build a distributable ZIP\n`);
+
+  // ── post-scaffold environment warnings ───────────────────────────────────
+  const noNode = !hasBin("node");
+  if (noNode || noPython || venvFailed) {
+    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`);
+    }
+    log.info("");
+  }
 }

package/cli/src/pack.mjs

@@ -2,7 +2,7 @@
 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 { buildPlugin, exportRos2Build, pinRequirements } from "./build.mjs";
 import { findPluginRoot, humanSize, log } from "./util.mjs";
 
 function dirSize(dir) {
@@ -17,7 +17,10 @@ function dirSize(dir) {
 
 export async function runPack() {
   const pluginRoot = findPluginRoot();
+  log.step("pinning requirements.txt to latest PyPI versions");
+  await pinRequirements(pluginRoot);
   await buildPlugin({ root: pluginRoot, minify: true });
+  await exportRos2Build(pluginRoot);
 
   const manifest = JSON.parse(
     readFileSync(resolve(pluginRoot, "manifest.json"), "utf8"),

package/cli/src/ros2.mjs

@@ -0,0 +1,65 @@
+// Shared ROS2 Docker helpers (Jazzy + Python 3.12 — matches the robot backend).
+// Used by dev:back (interactive dev loop) and build (export install/ into the ZIP).
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { hasBin, kitRoot, log } from "./util.mjs";
+
+export const ROS2_DEV_IMAGE = "muscat-pk-ros2-dev";
+
+// Dockerfile lives inside the kit — plugin authors never see or edit it.
+// It has no COPY/ADD, so the build context is irrelevant (its own dir is used).
+const DOCKERFILE = resolve(kitRoot, "cli/docker/Dockerfile.dev");
+
+/** First package directory under ros2_ws/src (the colcon package name). */
+export function ros2PackageName(root) {
+  const srcDir = resolve(root, "ros2_ws/src");
+  if (!existsSync(srcDir)) return null;
+  const dirs = readdirSync(srcDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+  return dirs[0] ?? null;
+}
+
+export function assertDockerReady() {
+  if (!hasBin("docker")) {
+    throw new Error("Docker not found. ROS2 needs Docker (Jazzy + Python 3.12 container).");
+  }
+  if (!existsSync(DOCKERFILE)) {
+    throw new Error(`kit Dockerfile missing at ${DOCKERFILE} (reinstall muscat-plugin-kit).`);
+  }
+}
+
+/** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
+export function ensureImage(image = ROS2_DEV_IMAGE) {
+  log.step(`docker build -t ${image} (first run is slow, then cached)…`);
+  const r = spawnSync(
+    "docker",
+    ["build", "-t", image, "-f", DOCKERFILE, dirname(DOCKERFILE)],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("docker build failed.");
+}
+
+/**
+ * Run `colcon build` inside the container, producing ros2_ws/install on the host
+ * (the workspace is mounted). symlink=true for dev (fast, edit-in-place);
+ * symlink=false for export builds that ship in the ZIP (real copies, relocatable).
+ */
+export function colconBuild(root, { image = ROS2_DEV_IMAGE, symlink = false } = {}) {
+  const flag = symlink ? "--symlink-install" : "";
+  const script = [
+    // --ignore-installed: don't try to uninstall debian-managed packages
+    // (e.g. psutil), which fails with "RECORD file not found".
+    "pip install -r requirements.txt --break-system-packages --ignore-installed -q || true",
+    "cd ros2_ws",
+    `colcon build ${flag}`.trim(),
+  ].join(" && ");
+  log.step(`colcon build${symlink ? " --symlink-install" : ""} (in container)…`);
+  const r = spawnSync(
+    "docker",
+    ["run", "--rm", "-v", `${root}:/plugin`, "-w", "/plugin", image, "bash", "-lc", script],
+    { cwd: root, stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("colcon build failed.");
+}

package/cli/src/type.mjs

@@ -0,0 +1,82 @@
+// muscat-pk type change — switch an existing plugin's backend type.
+//   python ↔ ros2.  python→ros2 adds the ros2_ws/ overlay; ros2→python flips
+//   the manifest type and leaves ros2_ws/ in place (never deletes user code).
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { basename, resolve } from "node:path";
+import { findPluginRoot, log } from "./util.mjs";
+import { applyTokens, deriveNames, overlayRos2 } from "./new.mjs";
+
+const TYPES = ["python", "ros2"];
+
+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 readManifest(root) {
+  const path = resolve(root, "manifest.json");
+  if (!existsSync(path)) throw new Error(`manifest.json not found in ${root}`);
+  return { path, json: JSON.parse(readFileSync(path, "utf8")) };
+}
+
+export async function runType(args) {
+  // accept `type change`, `type`, `type --to ros2`
+  const sub = args[0];
+  const toFlagIdx = args.indexOf("--to");
+  let to = toFlagIdx >= 0 ? args[toFlagIdx + 1] : undefined;
+
+  const root = findPluginRoot();
+  const { path, json } = readManifest(root);
+  const current = json.runtime?.type ?? "python";
+
+  if (sub && sub !== "change") {
+    log.warn(`unknown subcommand '${sub}'. Usage: muscat-pk type change [--to python|ros2]`);
+  }
+
+  if (!to) {
+    console.log(`\n현재 타입: ${current}`);
+    console.log("변경할 타입을 선택하세요:");
+    console.log("  1) Python");
+    console.log("  2) ROS2(rclpy)");
+    const choice = await prompt("\n선택 [1/2]: ", "");
+    to = choice === "1" ? "python" : choice === "2" ? "ros2" : undefined;
+  }
+
+  if (!TYPES.includes(to)) {
+    throw new Error(`invalid type. choose python or ros2.`);
+  }
+  if (to === current) {
+    log.info(`already '${current}' — nothing to change.`);
+    return;
+  }
+
+  if (to === "ros2") {
+    const { slug, pluginName, pluginClass, pluginId } = deriveNames(root);
+    if (existsSync(resolve(root, "ros2_ws"))) {
+      log.warn("ros2_ws/ already exists — keeping it, only flipping manifest type.");
+    } else {
+      log.step("adding ros2_ws/ overlay");
+      overlayRos2(root, slug);
+      applyTokens(root, {
+        __PLUGIN_ID__: pluginId,
+        __PLUGIN_NAME__: pluginName,
+        __PLUGIN_SLUG__: slug,
+        __PLUGIN_CLASS__: pluginClass,
+        __RUNTIME_TYPE__: "ros2",
+      });
+    }
+  } else {
+    // ros2 → python
+    if (existsSync(resolve(root, "ros2_ws"))) {
+      log.warn("ros2_ws/ left in place (not deleted). Remove it manually if unused.");
+    }
+  }
+
+  json.runtime = { ...json.runtime, type: to };
+  writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
+  log.ok(`${basename(root)} type: ${current} → ${to}`);
+}

package/cli/src/util.mjs

@@ -1,8 +1,42 @@
 // Shared helpers for muscat-pk.
+import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+/** True if an executable is on PATH (cross-platform). */
+export function hasBin(bin) {
+  const probe = process.platform === "win32" ? "where" : "which";
+  return spawnSync(probe, [bin]).status === 0;
+}
+
+/**
+ * Find a Python 3.12 interpreter (robot targets 3.12), cross-platform.
+ * Returns the command as an argv array, e.g. ["py","-3.12"] or ["python3.12"].
+ * Falls back to a generic python3/python with a warning flag.
+ */
+export function detectPythonCmd() {
+  const candidates =
+    process.platform === "win32"
+      ? [["py", "-3.12"], ["python3.12"], ["py", "-3"], ["python"]]
+      : [["python3.12"], ["python3"], ["python"]];
+  for (const cmd of candidates) {
+    const r = spawnSync(cmd[0], [...cmd.slice(1), "--version"]);
+    if (r.status === 0) {
+      const ver = String(r.stdout || r.stderr || "");
+      return { cmd, is312: ver.includes("3.12") };
+    }
+  }
+  return { cmd: process.platform === "win32" ? ["python"] : ["python3"], is312: false };
+}
+
+/** Path to the venv's python interpreter (cross-platform). */
+export function venvPython(venvDir) {
+  return process.platform === "win32"
+    ? resolve(venvDir, "Scripts", "python.exe")
+    : resolve(venvDir, "bin", "python");
+}
+
 /** Published install/CLI package name. Author imports use @rainbow-robotics/plugin-ui separately. */
 export const KIT_PUBLISHED_NAME = "@rainbow-robotics/muscat-plugin-kit";
 
@@ -45,11 +79,14 @@ export function findPluginRoot(start = process.cwd()) {
   );
 }
 
+const ORANGE = "\x1b[33m";
+const RESET  = "\x1b[0m";
+
 export const log = {
   info: (...m) => console.log(...m),
   step: (...m) => console.log("›", ...m),
-  ok: (...m) => console.log("✓", ...m),
-  warn: (...m) => console.warn("⚠", ...m),
+  ok:   (...m) => console.log("✓", ...m),
+  warn: (...m) => console.warn(`${ORANGE}⚠${RESET}`, ...m.map(s => `${ORANGE}${s}${RESET}`)),
 };
 
 export function humanSize(bytes) {