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

package/cli/src/esbuild.mjs

@@ -1,15 +1,55 @@
+// When compiled with `bun --compile`, esbuild's native subprocess binary is
+// not bundled. Use Bun's built-in bundler instead.
+async function buildWithBun(options) {
+  const { entryPoints, outfile, format, minify, loader, define, external } = options;
+  const { dirname } = await import("node:path");
+  const result = await Bun.build({
+    entrypoints: entryPoints,
+    outdir: dirname(outfile),
+    format: format ?? "esm",
+    minify: minify ?? false,
+    loader,
+    define,
+    external,
+    target: "node",
+    throw: false,
+  });
+  if (!result.success) {
+    for (const log of result.logs) console.error(log.message);
+    throw new Error("Bun.build() failed");
+  }
+}
+
+async function buildWithWasm(options) {
+  const wasm = await import("esbuild-wasm");
+  return wasm.build(options);
+}
+
+function isNativeMissing(err) {
+  const msg = String(err?.message || err?.code || err || "");
+  return (
+    msg.includes("another platform") ||
+    msg.includes("Cannot find module") ||
+    msg.includes("not found") ||
+    msg.includes("No such file") ||
+    msg.includes("ENOENT") ||
+    msg.includes("MODULE_NOT_FOUND")
+  );
+}
+
 export async function buildWithFallback(options) {
-  const native = await import("esbuild");
+  if (typeof Bun !== "undefined") return buildWithBun(options);
+
+  // Try native esbuild (faster, no extra setup). Falls back to wasm when:
+  // - esbuild was not installed (removed from hard dependencies to avoid
+  //   postinstall script blocking npm i -g on Windows)
+  // - binary was built for a different platform
   try {
+    const native = await import("esbuild");
     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);
+  } catch (err) {
+    if (!isNativeMissing(err)) throw err;
   }
+
+  return buildWithWasm(options);
 }

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, kitVersion, 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,25 @@ 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,
+    __RB_VERSION__: kitVersion(),
   });
 
   // gitignore (templates can't ship a literal .gitignore via npm reliably)
@@ -118,8 +149,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/preview.mjs

@@ -0,0 +1,91 @@
+// muscat-pk preview — build the plugin and open preview-host connected to a
+// real Muscat server (robot or local). No local Socket.IO server is started.
+import { createInterface } from "node:readline";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { buildPlugin } from "./build.mjs";
+import { findPreviewHostRoot } from "./devUi.mjs";
+import { checkKitUpdate, log, parseArgs } from "./util.mjs";
+
+function prompt(question, defaultValue) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((res) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      res(answer.trim() || defaultValue);
+    });
+  });
+}
+
+export async function runPreview(args = []) {
+  const opts = parseArgs(args, { booleans: ["help"] });
+
+  if (opts.help) {
+    console.log(
+      [
+        "",
+        "Usage: muscat-pk preview [options]",
+        "",
+        "  빌드된 플러그인을 실제 Muscat 서버에 연결해 미리봅니다.",
+        "  Socket.IO 서버를 직접 띄우지 않습니다.",
+        "",
+        "Options:",
+        "  --host <ip>    Muscat 서버 IP 또는 hostname (default: localhost)",
+        "  --port <n>     preview-host 로컬 포트 (default: 4180)",
+        "  --ws-port <n>  Muscat Socket.IO 포트 (default: 10000)",
+        "",
+      ].join("\n"),
+    );
+    return;
+  }
+
+  await checkKitUpdate();
+
+  // ── 로봇 IP 결정 ────────────────────────────────────────────────────────────
+  let robotHost = opts.host ?? "";
+  if (!robotHost) {
+    robotHost = await prompt(
+      "Muscat 서버 IP 또는 hostname [localhost]: ",
+      "localhost",
+    );
+  }
+  const wsPort = opts["ws-port"] ?? "10000";
+  const socketUrl = `ws://${robotHost}:${wsPort}`;
+
+  const previewPort = opts.port ?? "4180";
+
+  log.step(`Muscat 서버: ${socketUrl}`);
+
+  // ── 플러그인 빌드 ────────────────────────────────────────────────────────────
+  const { distDir } = await buildPlugin();
+
+  // ── preview-host 실행 ────────────────────────────────────────────────────────
+  const previewRoot = findPreviewHostRoot();
+  const serveEntry = resolve(previewRoot, "serve.mjs");
+
+  if (!existsSync(resolve(previewRoot, "dist", "index.html"))) {
+    log.step("preview-host 번들 빌드 중 (최초 1회)…");
+    await new Promise((res, rej) => {
+      const p = spawn(process.execPath, [resolve(previewRoot, "build.mjs")], {
+        stdio: "inherit",
+      });
+      p.on("exit", (c) => (c === 0 ? res() : rej(new Error("preview-host build failed"))));
+    });
+  }
+
+  log.step(`preview-host 시작 → http://localhost:${previewPort}`);
+  log.step(`Socket.IO URL: ${socketUrl}`);
+
+  const child = spawn(
+    process.execPath,
+    [
+      serveEntry,
+      "--plugin", distDir,
+      "--port", String(previewPort),
+      "--socket-url", socketUrl,
+    ],
+    { stdio: "inherit" },
+  );
+  child.on("exit", (code) => process.exit(code ?? 0));
+}

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

@@ -0,0 +1,122 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { Server } from "socket.io";
+import { log } from "./util.mjs";
+
+const DEFAULT_ACTION_TIMEOUT_MS = 10_000;
+
+export function startSocketBridge({ port = 10000, host = "0.0.0.0" } = {}) {
+  const httpServer = createServer();
+  const io = new Server(httpServer, {
+    cors: { origin: "*" },
+  });
+  const queryables = new Map();
+  const pendingReplies = new Map();
+
+  function cleanupSocket(socket) {
+    for (const [topic, sid] of queryables) {
+      if (sid === socket.id) queryables.delete(topic);
+    }
+
+    for (const [id, pending] of pendingReplies) {
+      if (pending.sid !== socket.id) continue;
+      clearTimeout(pending.timer);
+      pending.resolve(undefined);
+      pendingReplies.delete(id);
+    }
+  }
+
+  io.on("connection", (socket) => {
+    socket.on("sub", async (data = {}) => {
+      if (!data.topic) return;
+      await socket.join(`t:${data.topic}`);
+    });
+
+    socket.on("unsub", async (data = {}) => {
+      if (!data.topic) return;
+      await socket.leave(`t:${data.topic}`);
+    });
+
+    socket.on("pub", (data = {}) => {
+      const topic = data.topic;
+      if (!topic) return;
+      io.to(`t:${topic}`).emit("msg", {
+        topic,
+        payload: data.payload,
+      });
+    });
+
+    socket.on("serve_register", (data = {}) => {
+      if (!data.topic) return;
+      queryables.set(data.topic, socket.id);
+    });
+
+    socket.on("serve_unregister", (data = {}) => {
+      const topic = data.topic;
+      if (!topic) return;
+      if (queryables.get(topic) === socket.id) queryables.delete(topic);
+    });
+
+    socket.on("serve_reply", (data = {}) => {
+      const pending = pendingReplies.get(data.id);
+      if (!pending) return;
+      clearTimeout(pending.timer);
+      pending.resolve(data.payload);
+      pendingReplies.delete(data.id);
+    });
+
+    socket.on("action", (data = {}, ack) => {
+      const topic = data.topic;
+      const sid = topic ? queryables.get(topic) : undefined;
+      const target = sid ? io.sockets.sockets.get(sid) : undefined;
+
+      if (!target) {
+        if (typeof ack === "function") ack(undefined);
+        return;
+      }
+
+      const id = randomUUID();
+      const result = new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          pendingReplies.delete(id);
+          resolve(undefined);
+        }, DEFAULT_ACTION_TIMEOUT_MS);
+
+        pendingReplies.set(id, {
+          sid,
+          timer,
+          resolve,
+        });
+      });
+
+      target.emit("serve_call", {
+        id,
+        topic,
+        payload: data.payload,
+      });
+
+      result.then((payload) => {
+        if (typeof ack === "function") ack(payload);
+      });
+    });
+
+    socket.on("disconnect", () => cleanupSocket(socket));
+  });
+
+  httpServer.listen(port, host, () => {
+    log.step(`Socket.IO bridge listening on ws://127.0.0.1:${port}`);
+  });
+
+  const close = () => {
+    for (const pending of pendingReplies.values()) {
+      clearTimeout(pending.timer);
+      pending.resolve(undefined);
+    }
+    pendingReplies.clear();
+    queryables.clear();
+    io.close();
+    httpServer.close();
+  };
+
+  return { close };
+}

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}`);
+}