@rainbow-robotics/muscat-plugin-kit 1.10.1-dev.1 → 1.10.1

package/cli/src/new.mjs

@@ -1,343 +1,343 @@
-// muscat-pk new — scaffold a new plugin project from templates.
-import { execSync } from "node:child_process";
-import {
-  cpSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  renameSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
-import { basename, dirname, resolve } from "node:path";
-import { color, ensureIdeVenv, hasBin, kitVersion, parseArgs, prompt, templatesDir, log } from "./util.mjs";
-import { agentsMd, CLAUDE_MD } from "./ai-rules.mjs";
-
-// Like cpSync(src, dst, {recursive:true}) but reads from the embedded snapshot
-// when the templates dir doesn't exist on disk (compiled binary mode).
-// 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"];
-
-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);
-      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);
-  }
-}
-
-// 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, "_");
-  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.${idPart(base)}`,
-  };
-}
-
-// 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.
-//   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|cpp|ros2|ros2-cpp] [--pm npm|yarn|pnpm|bun]\n" +
-        "                 [--author <name>] [--email <email>] [--description <text>]\n" +
-        "                 [--yes] [--no-install]",
-    );
-    return;
-  }
-
-  const dirArg = opts._[0];
-  const targetName =
-    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${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) {
-    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";
-
-  const { dir, slug, pluginName, pluginClass, pluginId } = deriveNames(target);
-
-  mkdirSync(target, { recursive: true });
-
-  // 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}`);
-  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,
-    __PLUGIN_NAME__: pluginName,
-    __PLUGIN_DIR__: dir,
-    __PLUGIN_SLUG__: slug,
-    __PLUGIN_CLASS__: pluginClass,
-    __PLUGIN_AUTHOR__: authorArg || "",
-    __PLUGIN_EMAIL__: emailArg || "",
-    __PM__: pm,
-    __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", ".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);
-
-  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}`);
-    }
-
-    // Local .venv is for your editor/linter (pylint, pyright, ...) only — the
-    // backend actually RUNS in Docker (see README), this never affects that.
-    // rclcpp is C++, so no venv applies there.
-    const needsIdeVenv =
-      runtimeChoice.type === "python" ||
-      (runtimeChoice.type === "ros2" && runtimeChoice.rosClient === "rclpy");
-    if (needsIdeVenv) {
-      log.step("creating .venv for your editor (pylint/pyright)…");
-      if (ensureIdeVenv(target)) {
-        log.ok(".venv ready — point your editor's Python interpreter there.");
-      } else {
-        log.warn("Could not create .venv (no local Python/uv?) — skipping, Docker dev still works.");
-      }
-    }
-    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 {
-      log.warn("git init failed — run it manually if you want version control here.");
-    }
-  }
-
-  // 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 || 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 (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("");
-  }
-}
+// muscat-pk new — scaffold a new plugin project from templates.
+import { execSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { color, ensureIdeVenv, hasBin, kitVersion, parseArgs, prompt, templatesDir, log } from "./util.mjs";
+import { agentsMd, CLAUDE_MD } from "./ai-rules.mjs";
+
+// Like cpSync(src, dst, {recursive:true}) but reads from the embedded snapshot
+// when the templates dir doesn't exist on disk (compiled binary mode).
+// 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"];
+
+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);
+      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);
+  }
+}
+
+// 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, "_");
+  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.${idPart(base)}`,
+  };
+}
+
+// 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.
+//   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|cpp|ros2|ros2-cpp] [--pm npm|yarn|pnpm|bun]\n" +
+        "                 [--author <name>] [--email <email>] [--description <text>]\n" +
+        "                 [--yes] [--no-install]",
+    );
+    return;
+  }
+
+  const dirArg = opts._[0];
+  const targetName =
+    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${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) {
+    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";
+
+  const { dir, slug, pluginName, pluginClass, pluginId } = deriveNames(target);
+
+  mkdirSync(target, { recursive: true });
+
+  // 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}`);
+  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,
+    __PLUGIN_NAME__: pluginName,
+    __PLUGIN_DIR__: dir,
+    __PLUGIN_SLUG__: slug,
+    __PLUGIN_CLASS__: pluginClass,
+    __PLUGIN_AUTHOR__: authorArg || "",
+    __PLUGIN_EMAIL__: emailArg || "",
+    __PM__: pm,
+    __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", ".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);
+
+  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}`);
+    }
+
+    // Local .venv is for your editor/linter (pylint, pyright, ...) only — the
+    // backend actually RUNS in Docker (see README), this never affects that.
+    // rclcpp is C++, so no venv applies there.
+    const needsIdeVenv =
+      runtimeChoice.type === "python" ||
+      (runtimeChoice.type === "ros2" && runtimeChoice.rosClient === "rclpy");
+    if (needsIdeVenv) {
+      log.step("creating .venv for your editor (pylint/pyright)…");
+      if (ensureIdeVenv(target)) {
+        log.ok(".venv ready — point your editor's Python interpreter there.");
+      } else {
+        log.warn("Could not create .venv (no local Python/uv?) — skipping, Docker dev still works.");
+      }
+    }
+    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 {
+      log.warn("git init failed — run it manually if you want version control here.");
+    }
+  }
+
+  // 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 || 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 (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("");
+  }
+}