@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.5 → 0.1.2-dev.51

package/cli/src/devUi.mjs

@@ -1,38 +1,198 @@
-// muscat-pk dev:ui — preview the plugin inside a mini-Muscat (preview-host).
-import { spawn } from "node:child_process";
+
+import { spawn, spawnSync } from "node:child_process";
+import { createServer as createNetServer } from "node:net";
 import { createRequire } from "node:module";
-import { existsSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, watch } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
-import { buildPlugin } from "./build.mjs";
-import { checkKitUpdate, findPluginRoot, kitRoot, log } from "./util.mjs";
+import { fileURLToPath } from "node:url";
+import { checkKitUpdate, findPluginRoot, hasBin, kitRoot, log, parseArgs, prompt } from "./util.mjs";
+
+
+const DEV_PLUGIN_PORT = 4181;
+
+function getFreePort(preferred) {
+  return new Promise((res) => {
+    const srv = createNetServer();
+    srv.once("error", () => {
+      const s2 = createNetServer();
+      s2.listen(0, () => {
+        const { port } = s2.address();
+        s2.close(() => res(port));
+      });
+    });
+    srv.listen(preferred, () => srv.close(() => res(preferred)));
+  });
+}
+
+const PREVIEW_PKG = "@rainbow-robotics/preview-host";
+const CACHE_DIR = resolve(homedir(), ".muscat-pk");
+const CACHE_ROOT = resolve(CACHE_DIR, "node_modules", "@rainbow-robotics", "preview-host");
+
+
+const DEV_OUT = ".muscat-dev";
+
+function findNodeBin() {
+  if (typeof Bun === "undefined") return process.execPath;
+  for (const c of ["node", "node20", "node18"]) {
+    if (hasBin(c)) return c;
+  }
+  return null;
+}
 
-/** Resolve @rainbow-robotics/preview-host package root.
- *  Works in monorepo (yarn workspace hoisting) and when both packages are
- *  installed as deps of the plugin project. */
 function findPreviewHostRoot() {
   try {
     const req = createRequire(import.meta.url);
-    return dirname(req.resolve("@rainbow-robotics/preview-host/package.json"));
+    return dirname(req.resolve(`${PREVIEW_PKG}/package.json`));
+  } catch {}
+
+  const sibling = resolve(kitRoot, "../preview-host");
+  if (existsSync(resolve(sibling, "package.json"))) return sibling;
+
+  if (existsSync(resolve(CACHE_ROOT, "package.json"))) return CACHE_ROOT;
+
+  if (!hasBin("npm")) {
+    throw new Error(
+      `preview-host를 찾을 수 없습니다.\n` +
+      `Node.js 20+ 를 설치하면 자동으로 준비됩니다: https://nodejs.org`,
+    );
+  }
+  log.step(`preview-host 설치 중 (~/.muscat-pk) — 첫 실행 시 한 번만 수행됩니다…`);
+  mkdirSync(CACHE_DIR, { recursive: true });
+  const r = spawnSync(
+    "npm",
+    ["install", "--prefix", CACHE_DIR, "--save", PREVIEW_PKG],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("preview-host 설치 실패.");
+  if (!existsSync(resolve(CACHE_ROOT, "package.json"))) {
+    throw new Error("preview-host 설치 후에도 패키지를 찾을 수 없습니다.");
+  }
+  return CACHE_ROOT;
+}
+
+function syncAssets(pluginRoot, outDir) {
+  const assetsSrc = resolve(pluginRoot, "assets");
+  if (existsSync(assetsSrc)) cpSync(assetsSrc, resolve(outDir, "assets"), { recursive: true });
+}
+
+
+function stageDevAssets(pluginRoot) {
+  const outDir = resolve(pluginRoot, DEV_OUT);
+  mkdirSync(outDir, { recursive: true });
+  const manifestSrc = resolve(pluginRoot, "manifest.json");
+  if (existsSync(manifestSrc)) copyFileSync(manifestSrc, resolve(outDir, "manifest.json"));
+  syncAssets(pluginRoot, outDir);
+  return outDir;
+}
+
+function watchAssets(pluginRoot, outDir) {
+  const assetsSrc = resolve(pluginRoot, "assets");
+  if (!existsSync(assetsSrc)) return;
+  watch(assetsSrc, { recursive: true }, () => syncAssets(pluginRoot, outDir));
+}
+
+
+function findViteBin(pluginRoot) {
+  try {
+    const req = createRequire(resolve(pluginRoot, "package.json"));
+    const vitePkg = req.resolve("vite/package.json");
+    return resolve(dirname(vitePkg), "bin", "vite.js");
   } catch {
-    // fallback: sibling package in muscat-plugin-kit/ workspace
-    return resolve(kitRoot, "../preview-host");
+    return null;
   }
 }
 
+
+function spawnPluginDevServer(pluginRoot, node, port, readyFile, sharedRuntimeBase) {
+  if (!node || !findViteBin(pluginRoot)) return null;
+  const runner = fileURLToPath(new URL("./pluginDevServer.mjs", import.meta.url));
+
+  rmSync(resolve(pluginRoot, "node_modules", ".vite"), { recursive: true, force: true });
+  log.step(`vite dev server (HMR) starting at :${port} — ui/*.tsx`);
+
+  return spawn(node, [runner, pluginRoot, String(port), readyFile], {
+    cwd: pluginRoot,
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      VITE_PLUGIN_PREVIEW: "true",
+      MUSCAT_PLUGIN_SHARED_RUNTIME_BASE: sharedRuntimeBase,
+    },
+  });
+}
+
+function waitForPluginDevPort(readyFile, proc, timeoutMs = 15_000) {
+  const start = Date.now();
+  return new Promise((res, rej) => {
+    let exited = false;
+    proc.once("exit", (code) => {
+      exited = true;
+      rej(new Error(`plugin dev server exited before ready (code ${code ?? 0})`));
+    });
+
+    const tick = () => {
+      if (existsSync(readyFile)) {
+        try {
+          const { port } = JSON.parse(readFileSync(readyFile, "utf8"));
+          if (Number.isInteger(port)) return res(port);
+        } catch {
+        }
+      }
+      if (Date.now() - start > timeoutMs)
+        return rej(new Error("plugin dev server did not become ready in time"));
+      if (!exited) setTimeout(tick, 100);
+    };
+    tick();
+  });
+}
+
 export async function runDevUi(args = []) {
-  const portIdx = args.indexOf("--port");
-  const port = portIdx !== -1 ? args[portIdx + 1] : "4180";
+  const parsed = parseArgs(args);
+  const requestedPort = Number(parsed.port ?? "4180");
+  const robotIp = parsed["robot-ip"] ?? process.env.MUSCAT_ROBOT_HOST ?? await prompt("  Robot IP (skip if no robot): ");
 
   await checkKitUpdate();
-  const { distDir } = await buildPlugin();
+  const pluginRoot = findPluginRoot();
+  const outDir = stageDevAssets(pluginRoot);
+  const port = await getFreePort(requestedPort);
+  if (port !== requestedPort)
+    log.warn(`preview-host port ${requestedPort} is in use — using ${port} instead.`);
+
+  if (robotIp) log.info(`MUSCAT_API_ORIGIN → http://${robotIp}:*`);
+
+  watchAssets(pluginRoot, outDir);
+
+  const node = findNodeBin();
+  const readyFile = resolve(outDir, "plugin-dev-port.json");
+  rmSync(readyFile, { force: true });
+  const sharedRuntimeBase = `http://localhost:${port}/plugin-shared`;
+  const viteProc = spawnPluginDevServer(
+    pluginRoot,
+    node,
+    DEV_PLUGIN_PORT,
+    readyFile,
+    sharedRuntimeBase,
+  );
+  let devPort = DEV_PLUGIN_PORT;
+
+  if (!viteProc) {
+    log.warn("vite not found — UI will not load. Run `npm install` in the plugin project.");
+  } else {
+    devPort = await waitForPluginDevPort(readyFile, viteProc);
+    viteProc.on("exit", (code) => {
+      if (code) log.warn(`plugin dev server exited (code ${code}) — UI won't load (is :${devPort} free?).`);
+    });
+  }
 
   const previewRoot = findPreviewHostRoot();
   const serveEntry = resolve(previewRoot, "serve.mjs");
   if (!existsSync(resolve(previewRoot, "dist", "index.html"))) {
     log.step("building preview-host bundle (first run)…");
     await new Promise((res, rej) => {
-      const p = spawn("node", [resolve(previewRoot, "build.mjs")], {
+      const p = spawn(node ?? process.execPath, [resolve(previewRoot, "build.mjs")], {
         stdio: "inherit",
+        env: { ...process.env, VITE_PLUGIN_PREVIEW: "true" },
       });
       p.on("exit", (c) => (c === 0 ? res() : rej(new Error("preview-host build failed"))));
     });
@@ -40,11 +200,30 @@ export async function runDevUi(args = []) {
 
   log.step(`starting preview-host on :${port}`);
   const child = spawn(
-    "node",
-    [serveEntry, "--plugin", distDir, "--port", String(port)],
+    node ?? process.execPath,
+    [
+      serveEntry,
+      "--plugin", outDir,
+      "--port", String(port),
+      "--dev-server-url", `http://localhost:${devPort}`,
+      ...(robotIp ? ["--robot-host", robotIp] : []),
+    ],
     { stdio: "inherit" },
   );
-  child.on("exit", (code) => process.exit(code ?? 0));
+
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    if (viteProc && !viteProc.killed && viteProc.exitCode === null) viteProc.kill();
+    if (!child.killed && child.exitCode === null) child.kill();
+  };
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+  child.on("exit", (code) => {
+    cleanup();
+    process.exit(code ?? 0);
+  });
 }
 
-export { findPluginRoot };
+export { findPluginRoot, findPreviewHostRoot };

package/cli/src/esbuild.mjs

@@ -20,20 +20,37 @@ async function buildWithBun(options) {
   }
 }
 
+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("Cannot find package") ||
+    msg.includes("not found") ||
+    msg.includes("No such file") ||
+    msg.includes("ENOENT") ||
+    msg.includes("MODULE_NOT_FOUND")
+  );
+}
+
 export async function buildWithFallback(options) {
   if (typeof Bun !== "undefined") return buildWithBun(options);
 
-  const native = await import("esbuild");
+  // 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/manifest.mjs

@@ -0,0 +1,208 @@
+// manifest.mjs — manifest.json schema definition and validation
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { manifestPortRanges, validatePorts } from "./ports.mjs";
+
+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);
+  validatePorts(manifest.ports, 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;
+}
+
+export function assertManifestPorts(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 [];
+  const errors = [];
+  validatePorts(manifest.ports, errors);
+  if (errors.length > 0)
+    throw new Error(`manifest.json port errors:\n${errors.map((e) => `  • ${e}`).join("\n")}`);
+  return manifestPortRanges(manifest);
+}