@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.9 → 1.0.0

package/cli/src/devUi.mjs

@@ -1,38 +1,56 @@
-// muscat-pk dev:ui — preview the plugin inside a mini-Muscat (preview-host).
+
 import { spawn, spawnSync } from "node:child_process";
+import { createServer as createNetServer } from "node:net";
 import { createRequire } from "node:module";
-import { existsSync, mkdirSync } 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, hasBin, 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");
 
-/**
- * Resolve preview-host root in order:
- *  1. Standard require (npm/yarn global install)
- *  2. Monorepo sibling (dev workspace)
- *  3. ~/.muscat-pk cache (previous auto-install)
- *  4. Auto-install to ~/.muscat-pk via npm (binary users who have Node.js)
- */
+
+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;
+}
+
 function findPreviewHostRoot() {
-  // 1. npm/yarn 설치 경로
   try {
     const req = createRequire(import.meta.url);
     return dirname(req.resolve(`${PREVIEW_PKG}/package.json`));
   } catch {}
 
-  // 2. 모노레포 sibling
   const sibling = resolve(kitRoot, "../preview-host");
   if (existsSync(resolve(sibling, "package.json"))) return sibling;
 
-  // 3. 캐시
   if (existsSync(resolve(CACHE_ROOT, "package.json"))) return CACHE_ROOT;
 
-  // 4. npm 자동 설치 → 캐시
   if (!hasBin("npm")) {
     throw new Error(
       `preview-host를 찾을 수 없습니다.\n` +
@@ -53,20 +71,128 @@ function findPreviewHostRoot() {
   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 {
+    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(process.execPath, [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"))));
     });
@@ -74,11 +200,30 @@ export async function runDevUi(args = []) {
 
   log.step(`starting preview-host on :${port}`);
   const child = spawn(
-    process.execPath,
-    [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, 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/host_agent.py

@@ -0,0 +1,162 @@
+"""Host-side raw Zenoh byte-proxy.
+
+Runs on the host as a normal Zenoh peer (reverse-dials the robot, same as the
+SDK's own connect()) and serves a tiny domain-agnostic byte protocol over TCP
+— {query, put, subscribe} by keyexpr + bytes only — so a Docker Desktop
+container, which cannot join the robot's Zenoh mesh itself, can talk to a
+process that can.
+
+Env: MUSCAT_ROBOT_HOST, MUSCAT_ROBOT_TOKEN, MUSCAT_ZENOH_ADVERTISE_HOST,
+MUSCAT_ZENOH_PORT (robot-facing), MUSCAT_PROXY_PORT (container-facing).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import socket
+import struct
+import threading
+
+
+def _send_frame(conn: socket.socket, lock: threading.Lock, obj: dict) -> None:
+    body = json.dumps(obj).encode()
+    with lock:
+        conn.sendall(struct.pack(">I", len(body)) + body)
+
+
+def _recv_frame(conn: socket.socket) -> dict | None:
+    hdr = b""
+    while len(hdr) < 4:
+        chunk = conn.recv(4 - len(hdr))
+        if not chunk:
+            return None
+        hdr += chunk
+    n = struct.unpack(">I", hdr)[0]
+    buf = b""
+    while len(buf) < n:
+        chunk = conn.recv(n - len(buf))
+        if not chunk:
+            return None
+        buf += chunk
+    return json.loads(buf.decode())
+
+
+def _handle_conn(conn: socket.socket, zenoh_client) -> None:
+    send_lock = threading.Lock()
+    sub_ids: dict[str, int] = {}
+    try:
+        while True:
+            req = _recv_frame(conn)
+            if req is None:
+                return
+            op = req.get("type")
+
+            if op == "query":
+                payload = bytes.fromhex(req["payload_hex"]) if req.get("payload_hex") else None
+                try:
+                    replies = zenoh_client._client.query(
+                        req["keyexpr"], payload, req.get("timeout_ms", 2000), req.get("target", 0)
+                    )
+                    out = {
+                        "type": "query_resp", "id": req["id"], "ok": True,
+                        "replies": [
+                            {"key": k, "payload_hex": bytes(p).hex(), "att": a, "encoding": e, "is_error": ie}
+                            for (k, p, a, e, ie) in replies
+                        ],
+                    }
+                except Exception as exc:
+                    out = {"type": "query_resp", "id": req["id"], "ok": False, "error": f"{type(exc).__name__}: {exc}"}
+                _send_frame(conn, send_lock, out)
+
+            elif op == "put":
+                payload = bytes.fromhex(req["payload_hex"]) if req.get("payload_hex") else b""
+                try:
+                    zenoh_client._client.publish(req["keyexpr"], payload, "", 0, 5, False)
+                    out = {"type": "put_resp", "id": req["id"], "ok": True}
+                except Exception as exc:
+                    out = {"type": "put_resp", "id": req["id"], "ok": False, "error": f"{type(exc).__name__}: {exc}"}
+                _send_frame(conn, send_lock, out)
+
+            elif op == "subscribe":
+                keyexpr = req["keyexpr"]
+
+                def on_sample(topic: str, payload_bytes: bytes, att: str, _ke: str = keyexpr) -> None:
+                    _send_frame(conn, send_lock, {
+                        "type": "sample", "keyexpr": _ke, "key": topic,
+                        "payload_hex": bytes(payload_bytes).hex(), "att": att,
+                    })
+
+                try:
+                    sub_id = zenoh_client._client.declare_subscriber(keyexpr, on_sample)
+                    sub_ids[keyexpr] = sub_id
+                    out = {"type": "subscribe_resp", "id": req["id"], "ok": True}
+                except Exception as exc:
+                    out = {"type": "subscribe_resp", "id": req["id"], "ok": False, "error": f"{type(exc).__name__}: {exc}"}
+                _send_frame(conn, send_lock, out)
+
+            elif op == "unsubscribe":
+                keyexpr = req["keyexpr"]
+                sub_id = sub_ids.pop(keyexpr, None)
+                if sub_id is not None:
+                    try:
+                        zenoh_client._client.undeclare_subscriber(sub_id)
+                    except Exception:
+                        pass
+                _send_frame(conn, send_lock, {"type": "unsubscribe_resp", "id": req["id"], "ok": True})
+
+            else:
+                _send_frame(conn, send_lock, {"type": "error", "error": f"unknown op {op!r}"})
+    except (ConnectionResetError, BrokenPipeError, OSError):
+        pass
+    finally:
+        for sub_id in sub_ids.values():
+            try:
+                zenoh_client._client.undeclare_subscriber(sub_id)
+            except Exception:
+                pass
+        conn.close()
+
+
+def main() -> None:
+    from rainbow.rb_sdk.base import RBBaseSDK
+
+    host = os.environ["MUSCAT_ROBOT_HOST"]
+    token = os.environ.get("MUSCAT_ROBOT_TOKEN", "")
+    advertise = os.environ["MUSCAT_ZENOH_ADVERTISE_HOST"]
+    zenoh_port = int(os.environ["MUSCAT_ZENOH_PORT"])
+    proxy_port = int(os.environ["MUSCAT_PROXY_PORT"])
+
+    # The robot reverse-dials the advertised host:port; force it to the host's
+    # real LAN IP (matches what dev.mjs computed via ensureRemoteZenohEnv).
+    RBBaseSDK._detect_local_ip = staticmethod(lambda _host: advertise)
+
+    peer = RBBaseSDK()
+    connect_kwargs = {"host": host, "zenoh_port": zenoh_port, "mesh_timeout": 15.0}
+    if token:
+        connect_kwargs["token"] = token
+
+    asyncio.run(peer.connect(**connect_kwargs))
+    print(f"[host-agent] zenoh peer joined robot mesh (listening :{zenoh_port})", flush=True)
+
+    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    srv.bind(("0.0.0.0", proxy_port))
+    srv.listen(32)
+    print(f"[host-agent] byte-proxy listening :{proxy_port} (container connects via host.docker.internal)", flush=True)
+
+    try:
+        while True:
+            conn, _addr = srv.accept()
+            threading.Thread(target=_handle_conn, args=(conn, peer.zenoh_client), daemon=True).start()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        with contextlib.suppress(Exception):
+            asyncio.run(peer.disconnect())
+
+
+if __name__ == "__main__":
+    main()

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