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

package/cli/src/manifest.mjs

@@ -1,287 +1,287 @@
-// 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";
-
-// 호스트가 이해하는 contribution point. plugin-ui의 CONTRIBUTION_POINTS와 동일해야 한다.
-export const CONTRIBUTION_POINTS = [
-  "toolbar",
-  "lnb",
-  "move.panel",
-  "program.panel",
-];
-const ICON_SIZES = ["16", "48", "128"];
-// Reverse-domain id: "."-separated parts of lowercase letters/digits joined by single "-",
-// each part starting with a letter. Keeps the ROS namespace derived from it (rosNamespace)
-// valid and collision-free (no "_" in ids, so "." and "-" map to distinct characters).
-export const PLUGIN_ID_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*(\.[a-z][a-z0-9]*(-[a-z0-9]+)*)*$/;
-
-/** ROS namespace for a plugin id: "." → "/", "-" → "_" (com.example.my-plugin → /com/example/my_plugin). */
-export function rosNamespace(id) {
-  return "/" + id.replace(/\./g, "/").replace(/-/g, "_");
-}
-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"];
-const VARIABLE_TYPES = ["number", "string", "boolean", "array"];
-const VARIABLE_NAME_PREFIX = "RBP_";
-const VARIABLE_NAME_RE = /^RBP_[A-Za-z0-9_]+$/;
-
-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`);
-}
-
-// variables: pyfm에 노출할 변수 선언. 없으면 UI가 사용 가능한 변수를 보여줄 수 없다.
-function validateVariables(variables, errors) {
-  if (variables === undefined || variables === null) return;
-  if (!Array.isArray(variables)) {
-    errors.push(`"variables" must be an array`);
-    return;
-  }
-  const names = variables.map((v) => v?.name).filter(Boolean);
-  const duplicates = names.filter((n, i) => names.indexOf(n) !== i);
-  if (duplicates.length > 0)
-    errors.push(`variables: "name" must be unique (duplicates: ${[...new Set(duplicates)].map((n) => `"${n}"`).join(", ")})`);
-
-  variables.forEach((v, i) => {
-    if (typeof v !== "object" || v === null || Array.isArray(v)) {
-      errors.push(`variables[${i}] must be an object ({ name, type, init, description? })`);
-      return;
-    }
-    if (typeof v.name !== "string" || v.name.length === 0)
-      errors.push(`variables[${i}].name is required`);
-    else if (!v.name.startsWith(VARIABLE_NAME_PREFIX))
-      errors.push(`variables[${i}].name: "${v.name}" must start with "${VARIABLE_NAME_PREFIX}" (e.g. "${VARIABLE_NAME_PREFIX}${v.name}")`);
-    else if (!VARIABLE_NAME_RE.test(v.name))
-      errors.push(`variables[${i}].name: "${v.name}" is not a valid identifier (after "${VARIABLE_NAME_PREFIX}": letters, digits, underscore only, at least one character)`);
-    if (!VARIABLE_TYPES.includes(v.type))
-      errors.push(`variables[${i}].type must be one of ${VARIABLE_TYPES.map((t) => `"${t}"`).join(" | ")}`);
-    if (v.init === undefined)
-      errors.push(`variables[${i}].init is required (initial value)`);
-    else if (v.type === "number" && typeof v.init !== "number")
-      errors.push(`variables[${i}].init must be a number when type is "number"`);
-    else if (v.type === "string" && typeof v.init !== "string")
-      errors.push(`variables[${i}].init must be a string when type is "string"`);
-    else if (v.type === "boolean" && typeof v.init !== "boolean")
-      errors.push(`variables[${i}].init must be a boolean when type is "boolean"`);
-    else if (v.type === "array" && !Array.isArray(v.init))
-      errors.push(`variables[${i}].init must be an array when type is "array"`);
-    if (v.description !== undefined && v.description !== null)
-      validateI18nLabel(v.description, `variables[${i}].description`, errors);
-  });
-}
-
-// No contributes (missing or []) = a backend-only plugin: no screens, nothing for vite to build.
-// A plugin with screens still needs a toolbar entry — that is where the host lists it.
-function validateContributes(contributes, errors) {
-  if (contributes === undefined || contributes === null) return;
-  if (!Array.isArray(contributes)) {
-    errors.push("contributes must be an array");
-    return;
-  }
-  if (contributes.length === 0) 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) => {
-    if (!CONTRIBUTION_POINTS.includes(c.point))
-      errors.push(`contributes[${i}].point: unknown point ${JSON.stringify(c.point)} (allowed: ${CONTRIBUTION_POINTS.join(", ")})`);
-    validateI18nLabel(c.label, `contributes[${i}].label`, errors);
-    if (c.point === "program.panel") {
-      if (!c.commandInfo)
-        errors.push(`contributes[${i}]: "commandInfo" is required when point is "program.panel"`);
-      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.id === "string" && manifest.id && !PLUGIN_ID_RE.test(manifest.id))
-    errors.push(`"id" must be "."-separated parts of lowercase letters/digits and single "-", each starting with a letter (e.g. com.example.my-plugin)`);
-  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);
-  validateVariables(manifest.variables, 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 assertManifestVariables(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 = [];
-  validateVariables(manifest.variables, errors);
-  if (errors.length > 0)
-    throw new Error(`manifest.json variable errors:\n${errors.map((e) => `  • ${e}`).join("\n")}`);
-}
-
-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);
-}
+// 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";
+
+// 호스트가 이해하는 contribution point. plugin-ui의 CONTRIBUTION_POINTS와 동일해야 한다.
+export const CONTRIBUTION_POINTS = [
+  "toolbar",
+  "lnb",
+  "move.panel",
+  "program.panel",
+];
+const ICON_SIZES = ["16", "48", "128"];
+// Reverse-domain id: "."-separated parts of lowercase letters/digits joined by single "-",
+// each part starting with a letter. Keeps the ROS namespace derived from it (rosNamespace)
+// valid and collision-free (no "_" in ids, so "." and "-" map to distinct characters).
+export const PLUGIN_ID_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*(\.[a-z][a-z0-9]*(-[a-z0-9]+)*)*$/;
+
+/** ROS namespace for a plugin id: "." → "/", "-" → "_" (com.example.my-plugin → /com/example/my_plugin). */
+export function rosNamespace(id) {
+  return "/" + id.replace(/\./g, "/").replace(/-/g, "_");
+}
+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"];
+const VARIABLE_TYPES = ["number", "string", "boolean", "array"];
+const VARIABLE_NAME_PREFIX = "RBP_";
+const VARIABLE_NAME_RE = /^RBP_[A-Za-z0-9_]+$/;
+
+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`);
+}
+
+// variables: pyfm에 노출할 변수 선언. 없으면 UI가 사용 가능한 변수를 보여줄 수 없다.
+function validateVariables(variables, errors) {
+  if (variables === undefined || variables === null) return;
+  if (!Array.isArray(variables)) {
+    errors.push(`"variables" must be an array`);
+    return;
+  }
+  const names = variables.map((v) => v?.name).filter(Boolean);
+  const duplicates = names.filter((n, i) => names.indexOf(n) !== i);
+  if (duplicates.length > 0)
+    errors.push(`variables: "name" must be unique (duplicates: ${[...new Set(duplicates)].map((n) => `"${n}"`).join(", ")})`);
+
+  variables.forEach((v, i) => {
+    if (typeof v !== "object" || v === null || Array.isArray(v)) {
+      errors.push(`variables[${i}] must be an object ({ name, type, init, description? })`);
+      return;
+    }
+    if (typeof v.name !== "string" || v.name.length === 0)
+      errors.push(`variables[${i}].name is required`);
+    else if (!v.name.startsWith(VARIABLE_NAME_PREFIX))
+      errors.push(`variables[${i}].name: "${v.name}" must start with "${VARIABLE_NAME_PREFIX}" (e.g. "${VARIABLE_NAME_PREFIX}${v.name}")`);
+    else if (!VARIABLE_NAME_RE.test(v.name))
+      errors.push(`variables[${i}].name: "${v.name}" is not a valid identifier (after "${VARIABLE_NAME_PREFIX}": letters, digits, underscore only, at least one character)`);
+    if (!VARIABLE_TYPES.includes(v.type))
+      errors.push(`variables[${i}].type must be one of ${VARIABLE_TYPES.map((t) => `"${t}"`).join(" | ")}`);
+    if (v.init === undefined)
+      errors.push(`variables[${i}].init is required (initial value)`);
+    else if (v.type === "number" && typeof v.init !== "number")
+      errors.push(`variables[${i}].init must be a number when type is "number"`);
+    else if (v.type === "string" && typeof v.init !== "string")
+      errors.push(`variables[${i}].init must be a string when type is "string"`);
+    else if (v.type === "boolean" && typeof v.init !== "boolean")
+      errors.push(`variables[${i}].init must be a boolean when type is "boolean"`);
+    else if (v.type === "array" && !Array.isArray(v.init))
+      errors.push(`variables[${i}].init must be an array when type is "array"`);
+    if (v.description !== undefined && v.description !== null)
+      validateI18nLabel(v.description, `variables[${i}].description`, errors);
+  });
+}
+
+// No contributes (missing or []) = a backend-only plugin: no screens, nothing for vite to build.
+// A plugin with screens still needs a toolbar entry — that is where the host lists it.
+function validateContributes(contributes, errors) {
+  if (contributes === undefined || contributes === null) return;
+  if (!Array.isArray(contributes)) {
+    errors.push("contributes must be an array");
+    return;
+  }
+  if (contributes.length === 0) 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) => {
+    if (!CONTRIBUTION_POINTS.includes(c.point))
+      errors.push(`contributes[${i}].point: unknown point ${JSON.stringify(c.point)} (allowed: ${CONTRIBUTION_POINTS.join(", ")})`);
+    validateI18nLabel(c.label, `contributes[${i}].label`, errors);
+    if (c.point === "program.panel") {
+      if (!c.commandInfo)
+        errors.push(`contributes[${i}]: "commandInfo" is required when point is "program.panel"`);
+      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.id === "string" && manifest.id && !PLUGIN_ID_RE.test(manifest.id))
+    errors.push(`"id" must be "."-separated parts of lowercase letters/digits and single "-", each starting with a letter (e.g. com.example.my-plugin)`);
+  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);
+  validateVariables(manifest.variables, 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 assertManifestVariables(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 = [];
+  validateVariables(manifest.variables, errors);
+  if (errors.length > 0)
+    throw new Error(`manifest.json variable errors:\n${errors.map((e) => `  • ${e}`).join("\n")}`);
+}
+
+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);
+}