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

package/cli/src/manifest.mjs

@@ -0,0 +1,193 @@
+// manifest.mjs — manifest.json schema definition and validation
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export const CONTRIBUTION_POINTS = ["program.command", "toolbar", "move.rnb"];
+const ICON_SIZES = ["16", "48", "128"];
+const RUNTIME_TYPES = ["none", "python", "cpp", "ros2"];
+const ROS_CLIENTS = ["rclpy", "rclcpp"];
+const I18N_LANGS = ["ko", "en", "ja", "zh", "vi", "th", "es"];
+const TARGET_CATEGORIES = ["manipulate", "amr", "rby1", "vision"];
+
+function validateI18nLabel(value, field, errors) {
+  if (value === undefined || value === null) {
+    errors.push(`${field} is required`);
+    return;
+  }
+  if (typeof value === "string") return;
+  if (typeof value === "object") {
+    if (typeof value.en !== "string")
+      errors.push(`${field}: "en" is required when using object form`);
+    const unknown = Object.keys(value).filter((k) => !I18N_LANGS.includes(k));
+    if (unknown.length > 0)
+      errors.push(`${field}: unsupported language key(s) — ${unknown.map((k) => `"${k}"`).join(", ")} (allowed: ${I18N_LANGS.join(", ")})`);
+    return;
+  }
+  errors.push(`${field}: must be a string or { en (required), ko, ja, zh, vi, th, es }`);
+}
+
+export function readManifest(root) {
+  const path = resolve(root, "manifest.json");
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function manifestRuntime(root) {
+  return readManifest(root)?.runtime?.type ?? "python";
+}
+
+function validateIcons(icons, errors) {
+  if (icons === undefined || icons === null) {
+    errors.push("icons is required");
+    return;
+  }
+  if (typeof icons === "string") {
+    if (!icons.toLowerCase().endsWith(".svg"))
+      errors.push(`icons: non-SVG images (PNG, JPG, etc.) must use the { "16": "...", "48": "...", "128": "..." } object form`);
+  } else if (typeof icons === "object") {
+    const missing = ICON_SIZES.filter((s) => typeof icons[s] !== "string" || icons[s].length === 0);
+    if (missing.length > 0)
+      errors.push(`icons: missing size(s) ${missing.map((s) => `"${s}"`).join(", ")} — all three (16, 48, 128) are required for image files`);
+  } else {
+    errors.push(`icons: must be a string (SVG path) or { "16", "48", "128" } object (PNG/JPG)`);
+  }
+}
+
+function validateRuntime(runtime, errors) {
+  if (runtime === undefined || runtime === null) {
+    errors.push("runtime is required");
+    return;
+  }
+  if (typeof runtime !== "object") {
+    errors.push("runtime must be an object");
+    return;
+  }
+  if (!RUNTIME_TYPES.includes(runtime.type))
+    errors.push(`runtime.type must be one of ${RUNTIME_TYPES.map((t) => `"${t}"`).join(" | ")}`);
+  if (runtime.type === "python" && !runtime.entry)
+    errors.push("runtime.entry is required for python runtime");
+  if (runtime.type === "cpp" && !runtime.entry)
+    errors.push("runtime.entry is required for cpp runtime (the built executable name)");
+  if (runtime.type === "ros2") {
+    if (!runtime.package) errors.push("runtime.package is required for ros2 runtime");
+    if (!runtime.launch) errors.push("runtime.launch is required for ros2 runtime");
+    if (!ROS_CLIENTS.includes(runtime.rosClient))
+      errors.push(`runtime.rosClient must be one of ${ROS_CLIENTS.map((c) => `"${c}"`).join(" | ")}`);
+  }
+}
+
+function validateCommandInfo(info, prefix, errors) {
+  if (typeof info.name !== "string" || info.name.length === 0)
+    errors.push(`${prefix}.commandInfo.name is required`);
+  if (typeof info.icon !== "string" || info.icon.length === 0)
+    errors.push(`${prefix}.commandInfo.icon is required`);
+  if (info.iconClassName !== undefined && typeof info.iconClassName !== "string")
+    errors.push(`${prefix}.commandInfo.iconClassName must be a string`);
+  if (info.funcName !== undefined && typeof info.funcName !== "string")
+    errors.push(`${prefix}.commandInfo.funcName must be a string`);
+  if (info.args !== undefined && (typeof info.args !== "object" || Array.isArray(info.args)))
+    errors.push(`${prefix}.commandInfo.args must be an object`);
+  for (const key of ["disabled", "syncGroupId", "disableCopy", "disableDelete", "requireChildren", "requireParent"]) {
+    if (info[key] !== undefined && typeof info[key] !== "boolean")
+      errors.push(`${prefix}.commandInfo.${key} must be a boolean`);
+  }
+  for (const key of ["allowChildren", "allowParents", "notAllowChildren"]) {
+    if (info[key] !== undefined && (!Array.isArray(info[key]) || info[key].some((v) => typeof v !== "string")))
+      errors.push(`${prefix}.commandInfo.${key} must be a string[]`);
+  }
+  if (info.childrenCommand !== undefined && typeof info.childrenCommand !== "string")
+    errors.push(`${prefix}.commandInfo.childrenCommand must be a string`);
+}
+
+function validateContributes(contributes, errors) {
+  if (!Array.isArray(contributes) || contributes.length === 0) {
+    errors.push("contributes is required and must be a non-empty array");
+    return;
+  }
+  if (!contributes.some((c) => c.point === "toolbar"))
+    errors.push(`contributes: at least one "toolbar" entry is required`);
+
+  const uiValues = contributes.map((c) => c.ui).filter(Boolean);
+  const duplicateUi = uiValues.filter((v, i) => uiValues.indexOf(v) !== i);
+  if (duplicateUi.length > 0)
+    errors.push(`contributes: "ui" values must be unique across all entries (duplicates: ${[...new Set(duplicateUi)].map((v) => `"${v}"`).join(", ")})`);
+
+  contributes.forEach((c, i) => {
+    validateI18nLabel(c.label, `contributes[${i}].label`, errors);
+    if (c.point === "program.command") {
+      if (!c.commandInfo)
+        errors.push(`contributes[${i}]: "commandInfo" is required when point is "program.command"`);
+      else
+        validateCommandInfo(c.commandInfo, `contributes[${i}]`, errors);
+    }
+  });
+}
+
+/**
+ * Validate manifest.json. Returns an array of error messages (empty = valid).
+ */
+export function validateManifest(manifest) {
+  const errors = [];
+
+  if (typeof manifest !== "object" || manifest === null)
+    return ["manifest.json is not a valid JSON object"];
+
+  for (const key of ["id", "name", "version", "minMuscatVersion"]) {
+    if (typeof manifest[key] !== "string" || manifest[key].length === 0)
+      errors.push(`"${key}" is required`);
+  }
+  if (typeof manifest.author !== "string" || manifest.author.length === 0)
+    errors.push(`"author" is required`);
+  if (typeof manifest.email !== "string" || manifest.email.length === 0)
+    errors.push(`"email" is required`);
+  if (manifest.company !== undefined && manifest.company !== null && typeof manifest.company !== "string")
+    errors.push(`"company" must be a string`);
+
+  const hasModels = manifest.targetModels !== undefined && manifest.targetModels !== null;
+  const hasCategorys = manifest.targetCategorys !== undefined && manifest.targetCategorys !== null;
+  if (!hasModels && !hasCategorys) {
+    errors.push(`"targetModels" or "targetCategorys" is required`);
+  } else {
+    if (hasModels) {
+      if (manifest.targetModels !== "all" && (!Array.isArray(manifest.targetModels) || manifest.targetModels.length === 0))
+        errors.push(`"targetModels" must be "all" or a non-empty array of model strings`);
+      else if (Array.isArray(manifest.targetModels) && manifest.targetModels.some((m) => typeof m !== "string"))
+        errors.push(`"targetModels": all entries must be strings`);
+    }
+    if (hasCategorys) {
+      if (manifest.targetCategorys !== "all" && (!Array.isArray(manifest.targetCategorys) || manifest.targetCategorys.length === 0))
+        errors.push(`"targetCategorys" must be "all" or a non-empty array`);
+      else if (Array.isArray(manifest.targetCategorys)) {
+        const invalid = manifest.targetCategorys.filter((c) => !TARGET_CATEGORIES.includes(c));
+        if (invalid.length > 0)
+          errors.push(`"targetCategorys": invalid value(s) ${invalid.map((c) => `"${c}"`).join(", ")} — allowed: ${TARGET_CATEGORIES.join(", ")}`);
+      }
+    }
+  }
+  validateI18nLabel(manifest.description, "description", errors);
+
+  validateIcons(manifest.icons, errors);
+  validateRuntime(manifest.runtime, errors);
+  validateContributes(manifest.contributes, errors);
+
+  return errors;
+}
+
+/**
+ * Read and validate manifest.json. Throws if any errors are found.
+ */
+export function assertManifest(root) {
+  const manifest = readManifest(root);
+  if (manifest === null)
+    throw new Error("manifest.json parse failed — check JSON syntax");
+  if (Object.keys(manifest).length === 0)
+    return manifest;
+  const errors = validateManifest(manifest);
+  if (errors.length > 0)
+    throw new Error(`manifest.json errors:\n${errors.map((e) => `  • ${e}`).join("\n")}`);
+  return manifest;
+}

package/cli/src/new.mjs

@@ -6,26 +6,56 @@ import {
   mkdirSync,
   readFileSync,
   readdirSync,
+  renameSync,
+  rmSync,
   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 { basename, dirname, resolve } from "node:path";
+import { hasBin, kitVersion, parseArgs, prompt, templatesDir, log } from "./util.mjs";
 
-const TYPES = ["sdk", "ros2", "ui"];
+// 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.
+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"];
-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;
+
+// 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" };
+  }
 }
 
-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 +75,55 @@ 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.
+//   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 sdk|ros2|ui] [--pm npm|yarn|pnpm|bun]\n" +
-        "                 [--sdk-version <v>] [--yes] [--no-install]",
+      "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;
   }
@@ -63,50 +136,88 @@ export async function runNew(args) {
     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("Author name: ", "");
+    if (!emailArg) emailArg = await prompt("Email (required): ", "");
+    if (!descriptionArg) descriptionArg = await prompt("Description (English): ", "");
+  }
+
   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) C++");
+    console.log("  3) ROS2 (rclpy / Python)");
+    console.log("  4) ROS2 (rclcpp / C++)");
+    const choice = await prompt("\n선택 [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;
+    }
   }
-  type = TYPES.includes(type) ? type : "sdk";
 
   let pm = opts.pm;
   if (!pm && !opts.yes) {
-    pm = await prompt(`Package manager (${PMS.join("/")}) [npm]: `, "npm");
+    const defaultPm = isInsideYarnWorkspace(process.cwd()) ? "yarn" : "npm";
+    pm = await prompt(`Front-end package manager (${PMS.join("/")}) [${defaultPm}]: `, defaultPm);
   }
   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 + manifest/config)은 항상 포함. 백엔드 오버레이는 타입별로 얹는다.
+  //   python   → common의 py/ 사용
+  //   cpp      → cpp/ 오버레이, py/·requirements.txt 제거
+  //   ros2(*)  → ros2_ws/ 오버레이 (rclpy=ament_python, rclcpp=ament_cmake)
   log.step(`scaffolding ${type} plugin → ${target}`);
-  cpSync(resolve(templatesDir, "common"), target, { recursive: true });
-  if (type === "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");
-    }
+  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 });
   }
 
   applyTokens(target, {
     __PLUGIN_ID__: pluginId,
     __PLUGIN_NAME__: pluginName,
-    __SDK_VERSION__: sdkVersion,
+    __PLUGIN_DIR__: dir,
+    __PLUGIN_SLUG__: slug,
+    __PLUGIN_CLASS__: pluginClass,
+    __PLUGIN_AUTHOR__: authorArg || "",
+    __PLUGIN_EMAIL__: emailArg || "",
     __PM__: pm,
-    __RUNTIME_TYPE__: type === "ui" ? "none" : type === "ros2" ? "ros2" : "python",
+    __RUNTIME_TYPE__: runtimeChoice.type,
+    __RB_VERSION__: kitVersion(),
   });
 
+  // Write the correct runtime block into manifest.json (per-type fields).
+  const manifestPath = resolve(target, "manifest.json");
+  const manifestJson = JSON.parse(readFileSync(manifestPath, "utf8"));
+  manifestJson.runtime = runtimeForChoice(runtimeChoice, slug);
+  if (descriptionArg) manifestJson.description = { en: descriptionArg };
+  writeFileSync(manifestPath, JSON.stringify(manifestJson, null, 2) + "\n");
+
   // gitignore (templates can't ship a literal .gitignore via npm reliably)
   writeFileSync(
     resolve(target, ".gitignore"),
-    ["node_modules", "dist", ".venv", "*.zip", "ros2_ws/install", ""].join("\n"),
+    ["node_modules", "dist", ".muscat-dev", ".venv", "*.zip", "ros2_ws/install", "cpp/build", ""].join("\n"),
   );
 
   if (!opts["no-install"]) {
@@ -118,8 +229,28 @@ export async function runNew(args) {
     }
   }
 
+  // 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");
+
   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 build    # build + distributable ZIP\n`);
+
+  // ── 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("");
+  }
 }

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

@@ -0,0 +1,122 @@
+// Shared Python Docker helpers (Ubuntu 24.04 + Python 3.12 — matches the robot).
+// Used by dev:back (hot-reload) and build (lock + wheel vendor).
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+
+export const PYTHON_DEV_IMAGE = "muscat-pk-python-dev";
+
+export function assertDockerReady() {
+  if (!hasBin("docker")) {
+    throw new Error("Docker not found. The Python backend runs in a container (Ubuntu 24.04 + Python 3.12).");
+  }
+}
+
+/** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
+export async function ensureImage(image = PYTHON_DEV_IMAGE, { platform = null } = {}) {
+  const dockerfile = await resolveDockerfile("Dockerfile.python");
+  log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
+  const platformFlags = platform ? ["--platform", platform] : [];
+  const r = spawnSync(
+    "docker",
+    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("docker build failed.");
+  pruneMuskatImages();
+}
+
+// Docker --platform 플래그: 컨테이너를 target arch로 띄우면
+// pip이 glibc + arch를 자동 감지해 올바른 휠을 받는다.
+const ARCH_DOCKER_PLATFORM = {
+  amd64: "linux/amd64",
+  arm64: "linux/arm64",
+};
+
+/**
+ * Ubuntu 24.04 + py3.12 컨테이너 안에서:
+ *   1. uv pip compile requirements.txt → dist/requirements.lock  (arch 무관, 1회)
+ *   2. archs별 pip download --platform <manylinux_tag> → dist/wheels/  (네이티브 휠 벤더링)
+ *
+ * none-any 휠은 pip이 두 번째 arch에서 자동 skip → 중복 없음.
+ * requirements.txt 없으면 조용히 건너뜀.
+ */
+export async function lockAndVendor(pluginRoot, archs = ["x86_64", "aarch64"]) {
+  const reqTxt = resolve(pluginRoot, "requirements.txt");
+  if (!existsSync(reqTxt)) {
+    log.warn("requirements.txt not found — lock/vendor skipped");
+    return;
+  }
+
+  await ensureImage();
+
+  log.step("generating lock (uv pip compile)…");
+  const lockResult = spawnSync(
+    "docker",
+    [
+      "run", "--rm",
+      "-v", `${pluginRoot}:/plugin`,
+      PYTHON_DEV_IMAGE,
+      "bash", "-c",
+      "set -e && cd /plugin && mkdir -p dist && uv pip compile requirements.txt --python-version 3.12 -o dist/requirements.lock",
+    ],
+    { stdio: "inherit" },
+  );
+  if (lockResult.status !== 0) throw new Error("lock generation failed (uv pip compile)");
+  log.ok("dist/requirements.lock ready");
+
+  // arch별 휠 벤더링 — QEMU 불필요 (download only, --platform 고정)
+  // 한 arch가 실패해도 나머지 arch는 계속 시도한다.
+  const failed = [];
+  for (const arch of archs) {
+    const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
+    if (!dockerPlatform) {
+      log.warn(`unknown arch '${arch}' — skipped`);
+      continue;
+    }
+    // arch별 이미지 빌드 (--platform 지정) → pip이 glibc+arch 자동 감지 → 올바른 휠 선택.
+    const archImage = `${PYTHON_DEV_IMAGE}-${arch}`;
+    await ensureImage(archImage, { platform: dockerPlatform });
+
+    log.step(`vendoring wheels for ${arch} (${dockerPlatform})…`);
+    // 패키지별 개별 download로 private/미공개 패키지 실패 시에도 나머지 계속 진행.
+    const script = [
+      `set -e`,
+      `cd /plugin`,
+      `mkdir -p dist/wheels`,
+      `pkgs=$(grep -v '^#' dist/requirements.lock | grep -v '^[[:space:]]' | grep -v '^$')`,
+      `SKIP=""`,
+      `for pkg in $pkgs; do`,
+      `  pip3 download "$pkg" --no-deps --only-binary=:all: -d dist/wheels -q 2>&1 || SKIP="$SKIP $pkg"`,
+      `done`,
+      `[ -z "$SKIP" ] || echo "WARN: no wheel found (package not on PyPI or missing binary wheel):$SKIP"`,
+    ].join("\n");
+    const r = spawnSync(
+      "docker",
+      [
+        "run", "--rm",
+        "--platform", dockerPlatform,
+        "-v", `${pluginRoot}:/plugin`,
+        archImage,
+        "bash", "-c", script,
+      ],
+      { stdio: "inherit" },
+    );
+    if (r.status !== 0) {
+      log.warn(`wheel vendoring failed for ${arch} — some packages may not have manylinux wheels`);
+      failed.push(arch);
+    } else {
+      log.ok(`dist/wheels/ ready (${arch})`);
+    }
+  }
+
+  if (failed.length === archs.length) {
+    throw new Error(`wheel vendoring failed for all archs: ${failed.join(", ")}`);
+  }
+  if (failed.length > 0) {
+    log.warn(`wheel vendoring partial — failed: ${failed.join(", ")}, ok: ${archs.filter((a) => !failed.includes(a)).join(", ")}`);
+  } else {
+    log.ok(`dist/wheels/ ready (${archs.join(", ")})`);
+  }
+}