icuewidget-cli 0.4.44

package/src-node/fs-utils.js

@@ -0,0 +1,48 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function ensureInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function toZipPath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+export async function walkFiles(root) {
+  const files = [];
+  async function walk(dir) {
+    for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) await walk(absolute);
+      else if (entry.isFile()) files.push(absolute);
+    }
+  }
+  await walk(root);
+  return files;
+}
+
+export async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`${path.basename(filePath)} is not valid JSON: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+export async function writeJson(filePath, value) {
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}

package/src-node/manifest-update.js

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { APP_VERSION_RE, DEFAULT_APP_VERSION, SEMVER_RE } from "./constants.js";
+import { readJson, writeJson } from "./fs-utils.js";
+import { promptValidated } from "./prompts.js";
+
+export function bumpPatchVersion(value) {
+  const [major, minor, patch] = value.split(".");
+  return `${major}.${minor}.${Number(patch) + 1}`;
+}
+
+export async function updateManifestToLatest(widgetDir, options = {}) {
+  const manifestPath = path.join(widgetDir, "manifest.json");
+  const manifest = await readJson(manifestPath);
+  const changes = [];
+  const requirementChanges = [];
+
+  if (typeof manifest.min_app_version !== "string" || !APP_VERSION_RE.test(manifest.min_app_version.trim())) {
+    let value = options.minAppVersion;
+    if (value !== undefined) {
+      value = value.trim();
+      if (!APP_VERSION_RE.test(value)) throw new Error("--min-app-version must use iCUE version format like 5.45 or 5.45.104.");
+    } else {
+      value = await promptValidated(
+        "Minimum iCUE version required",
+        DEFAULT_APP_VERSION,
+        (answer) => APP_VERSION_RE.test(answer),
+        "Use iCUE version format like 5.45 or 5.45.104.",
+      );
+    }
+    manifest.min_app_version = value;
+    requirementChanges.push("manifest.min_app_version");
+  }
+
+  if (options.version !== undefined) {
+    const version = options.version.trim();
+    if (!SEMVER_RE.test(version)) throw new Error("--version must use semantic version format like 1.0.1.");
+    if (manifest.version !== version) {
+      manifest.version = version;
+      changes.push("manifest.version");
+    }
+  } else if (requirementChanges.length) {
+    if (typeof manifest.version !== "string" || !SEMVER_RE.test(manifest.version.trim())) {
+      throw new Error("manifest.version must use semantic version format like 1.0.0, or pass --version to set it.");
+    }
+    manifest.version = bumpPatchVersion(manifest.version.trim());
+    changes.push("manifest.version");
+  }
+
+  changes.push(...requirementChanges);
+  if (changes.length) await writeJson(manifestPath, manifest);
+  return changes;
+}

package/src-node/prompts.js

@@ -0,0 +1,28 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+let rl;
+
+function reader() {
+  rl ??= readline.createInterface({ input, output });
+  return rl;
+}
+
+export async function prompt(label, defaultValue = "") {
+  const suffix = defaultValue ? ` (${defaultValue})` : "";
+  const answer = (await reader().question(`${label}${suffix}: `)).trim();
+  return answer || defaultValue;
+}
+
+export async function promptValidated(label, defaultValue, validator, errorMessage) {
+  while (true) {
+    const answer = await prompt(label, defaultValue);
+    if (validator(answer)) return answer;
+    console.error(errorMessage);
+  }
+}
+
+export function closePrompts() {
+  rl?.close();
+  rl = undefined;
+}

package/src-node/scaffold.js

@@ -0,0 +1,47 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  DEFAULT_APP_VERSION,
+  DEFAULT_DEVICE_TYPE,
+  DEFAULT_FRAMEWORK_VERSION,
+  DEFAULT_PLATFORM,
+} from "./constants.js";
+import {
+  cssTemplate,
+  iconTemplate,
+  indexTemplate,
+  jsTemplate,
+  translationTemplate,
+} from "./templates.js";
+import { writeJson } from "./fs-utils.js";
+
+export async function scaffoldWidget(targetDir, answers) {
+  await fs.mkdir(targetDir, { recursive: true });
+  await Promise.all([
+    fs.mkdir(path.join(targetDir, "resources"), { recursive: true }),
+    fs.mkdir(path.join(targetDir, "scripts"), { recursive: true }),
+    fs.mkdir(path.join(targetDir, "styles"), { recursive: true }),
+  ]);
+
+  const manifest = {
+    author: answers.author,
+    id: answers.widgetId,
+    name: answers.widgetName,
+    description: answers.description,
+    version: answers.version,
+    preview_icon: answers.previewIcon,
+    min_app_version: answers.minAppVersion ?? DEFAULT_APP_VERSION,
+    min_framework_version: DEFAULT_FRAMEWORK_VERSION,
+    os: [{ platform: DEFAULT_PLATFORM }],
+    supported_devices: [{ type: DEFAULT_DEVICE_TYPE }],
+  };
+
+  await writeJson(path.join(targetDir, "manifest.json"), manifest);
+  await writeJson(path.join(targetDir, "translation.json"), translationTemplate(answers.widgetName));
+  await fs.writeFile(path.join(targetDir, "index.html"), indexTemplate(answers.widgetName), "utf8");
+  await fs.writeFile(path.join(targetDir, "styles", "main.css"), cssTemplate, "utf8");
+  await fs.writeFile(path.join(targetDir, "scripts", "main.js"), jsTemplate, "utf8");
+  await fs.writeFile(path.join(targetDir, "resources", "icon.svg"), iconTemplate(answers.widgetName), "utf8");
+
+  return manifest;
+}

package/src-node/templates.js

@@ -0,0 +1,151 @@
+export function translationTemplate(widgetName) {
+  return {
+    widget_name: widgetName,
+    Layout: "Layout",
+    "Widget Personalization": "Widget Personalization",
+    Headline: "Headline",
+    Subtitle: "Subtitle",
+    "Show Subtitle": "Show Subtitle",
+    "Text Color": "Text Color",
+    "Accent Color": "Accent Color",
+    Background: "Background",
+    Transparency: "Transparency",
+    "Hello World": "Hello World",
+  };
+}
+
+export function indexTemplate(widgetName) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(widgetName)}</title>
+  <link rel="icon" href="resources/icon.svg" type="image/svg+xml">
+  <link rel="stylesheet" href="styles/main.css">
+  <meta name="x-icue-property" content='{"name":"headline","label":"Headline","type":"text","default":"Hello World"}'>
+  <meta name="x-icue-property" content='{"name":"showSubtitle","label":"Show Subtitle","type":"boolean","default":true}'>
+  <meta name="x-icue-property" content='{"name":"subtitle","label":"Subtitle","type":"text","default":"Built with iCUE Widget CLI"}'>
+  <meta name="x-icue-property" content='{"name":"textColor","label":"Text Color","type":"color","default":"#ffffff"}'>
+  <meta name="x-icue-property" content='{"name":"accentColor","label":"Accent Color","type":"color","default":"#59c2ff"}'>
+  <meta name="x-icue-property" content='{"name":"backgroundColor","label":"Background","type":"color","default":"#111827"}'>
+  <meta name="x-icue-property" content='{"name":"transparency","label":"Transparency","type":"number","min":0,"max":100,"default":20}'>
+</head>
+<body>
+  <main id="content">
+    <div id="accent"></div>
+    <h1 id="headline">Hello World</h1>
+    <p id="subtitle">Built with iCUE Widget CLI</p>
+  </main>
+  <script src="scripts/main.js"></script>
+</body>
+</html>
+`;
+}
+
+export const cssTemplate = `:root {
+  --text-color: #ffffff;
+  --accent-color: #59c2ff;
+  --background-color: #111827;
+  --transparency: 20%;
+}
+
+html,
+body {
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  display: grid;
+  place-items: center;
+  background: transparent;
+  font-family: Inter, Segoe UI, system-ui, sans-serif;
+}
+
+#content {
+  min-width: 60%;
+  padding: 24px 28px;
+  border-radius: 24px;
+  color: var(--text-color);
+  background: color-mix(in srgb, var(--background-color) calc(100% - var(--transparency)), transparent);
+  text-align: center;
+}
+
+#headline {
+  margin: 0;
+  font-size: 32px;
+  font-weight: 700;
+}
+
+#accent {
+  width: 56px;
+  height: 4px;
+  margin: 0 auto 16px;
+  border-radius: 999px;
+  background: var(--accent-color);
+}
+
+#subtitle {
+  margin: 10px 0 0;
+  font-size: 18px;
+  opacity: 0.8;
+}
+`;
+
+export const jsTemplate = `const state = {
+  headline: "Hello World",
+  subtitle: "Built with iCUE Widget CLI",
+  showSubtitle: true,
+  textColor: "#ffffff",
+  accentColor: "#59c2ff",
+  backgroundColor: "#111827",
+  transparency: 20,
+};
+
+function applySettings(settings = {}) {
+  Object.assign(state, settings);
+  document.documentElement.style.setProperty("--text-color", state.textColor);
+  document.documentElement.style.setProperty("--accent-color", state.accentColor);
+  document.documentElement.style.setProperty("--background-color", state.backgroundColor);
+  document.documentElement.style.setProperty("--transparency", state.transparency + "%");
+  document.getElementById("headline").textContent = state.headline;
+  const subtitle = document.getElementById("subtitle");
+  subtitle.textContent = state.subtitle;
+  subtitle.hidden = !state.showSubtitle;
+}
+
+window.icueEvents = {
+  onICUEInitialized(payload) {
+    applySettings(payload?.settings);
+  },
+  onDataUpdated(payload) {
+    applySettings(payload?.settings);
+  },
+};
+
+applySettings();
+`;
+
+export function iconTemplate(widgetName) {
+  const title = escapeHtml(widgetName);
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-label="${title}">
+  <defs>
+    <linearGradient id="g" x1="0" x2="1" y1="0" y2="1">
+      <stop stop-color="#59c2ff"/>
+      <stop offset="1" stop-color="#7c3aed"/>
+    </linearGradient>
+  </defs>
+  <rect width="128" height="128" rx="28" fill="#111827"/>
+  <path d="M29 84h70M34 64h60M43 44h42" stroke="url(#g)" stroke-width="10" stroke-linecap="round"/>
+</svg>
+`;
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}

package/src-node/theme.js

@@ -0,0 +1,70 @@
+const enabled = process.env.NO_COLOR === undefined && process.stdout.isTTY;
+
+const code = (open, close) => (value) => enabled ? `\u001b[${open}m${value}\u001b[${close}m` : String(value);
+
+export const color = {
+  bold: code(1, 22),
+  dim: code(2, 22),
+  cyan: code(36, 39),
+  green: code(32, 39),
+  yellow: code(33, 39),
+  red: code(31, 39),
+  magenta: code(35, 39),
+};
+
+export function header(appName, version) {
+  console.log(`${color.bold(appName)} ${color.cyan(version)}`);
+  console.log(color.dim("iCUE widget packaging and scaffolding CLI"));
+}
+
+export function panel(title, rows, borderColor = color.cyan) {
+  const rowText = rows.map((row) => Array.isArray(row) ? row.join("  ") : String(row));
+  const maxWidth = Math.max(40, Math.min(76, (process.stdout.columns ?? 80) - 4));
+  const normalized = rowText.flatMap((row) => wrapLine(row, maxWidth));
+  const contentWidth = Math.min(maxWidth, Math.max(
+    title.length + 2,
+    ...normalized.map((row) => visibleLength(row)),
+  ));
+  const top = `╭─ ${title} ${"─".repeat(Math.max(0, contentWidth - title.length - 1))}╮`;
+  const bottom = `╰${"─".repeat(contentWidth + 2)}╯`;
+  console.log(borderColor(top));
+  for (const content of normalized) {
+    console.log(`${borderColor("│")} ${content}${" ".repeat(Math.max(0, contentWidth - visibleLength(content)))} ${borderColor("│")}`);
+  }
+  console.log(borderColor(bottom));
+}
+
+export function table(title, rows) {
+  const keyWidth = Math.max(...rows.map(([key]) => key.length));
+  panel(title, rows.map(([key, value]) => [color.dim(key.padEnd(keyWidth)), value]), color.cyan);
+}
+
+export function success(message) {
+  panel("Success", [color.green(`✓ ${message}`)], color.green);
+}
+
+export function info(message) {
+  panel("Info", [color.cyan(message)], color.cyan);
+}
+
+function visibleLength(value) {
+  return String(value).replace(/\u001b\[[0-9;]*m/g, "").length;
+}
+
+function wrapLine(value, width) {
+  if (visibleLength(value) <= width) return [value];
+  const words = String(value).split(" ");
+  const lines = [];
+  let current = "";
+  for (const word of words) {
+    const next = current ? `${current} ${word}` : word;
+    if (visibleLength(next) <= width) {
+      current = next;
+    } else {
+      if (current) lines.push(current);
+      current = `  ${word}`;
+    }
+  }
+  if (current) lines.push(current);
+  return lines;
+}

package/src-node/update-check.js

@@ -0,0 +1,97 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { APP_NAME, CLI_VERSION, NPM_PACKAGE_NAME } from "./constants.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(NPM_PACKAGE_NAME).replace("%40", "@")}/latest`;
+
+export async function notifyAboutUpdate({
+  argv = process.argv,
+  env = process.env,
+  now = Date.now(),
+  stderr = process.stderr,
+} = {}) {
+  if (env.ICUEWIDGET_NO_UPDATE_CHECK === "1" || env.ICUEWIDGET_UPDATE_CHECK_WORKER === "1" || argv.includes("--update-check-worker")) return;
+
+  let cache;
+  try {
+    cache = await readCache(env);
+  } catch {
+    cache = undefined;
+  }
+
+  if (cache?.latestVersion && isNewerVersion(cache.latestVersion, CLI_VERSION)) {
+    printUpdateNotice(stderr, cache.latestVersion);
+  }
+
+  const checkedAt = Number(cache?.checkedAt ?? 0);
+  if (!Number.isFinite(checkedAt) || now - checkedAt >= DAY_MS) {
+    runUpdateCheckWorker({ env }).catch(() => {});
+  }
+}
+
+export async function runUpdateCheckWorker({ env = process.env, fetchImpl = globalThis.fetch, now = Date.now() } = {}) {
+  if (typeof fetchImpl !== "function") return;
+  try {
+    const latestVersion = await fetchLatestVersion(fetchImpl);
+    if (!latestVersion) return;
+    await writeCache(env, { latestVersion, checkedAt: now });
+  } catch {
+    // Update checks are best-effort and must never make CLI commands noisy/fail.
+  }
+}
+
+export function isNewerVersion(candidate, current) {
+  const a = parseSemver(candidate);
+  const b = parseSemver(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] > b[i]) return true;
+    if (a[i] < b[i]) return false;
+  }
+  return false;
+}
+
+async function fetchLatestVersion(fetchImpl) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+  try {
+    const response = await fetchImpl(REGISTRY_URL, {
+      headers: { "Accept": "application/json", "User-Agent": `${APP_NAME}/${CLI_VERSION}` },
+      signal: controller.signal,
+    });
+    if (!response.ok) return undefined;
+    const body = await response.json();
+    return typeof body.version === "string" ? body.version : undefined;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function readCache(env) {
+  return JSON.parse(await fs.readFile(cachePath(env), "utf8"));
+}
+
+async function writeCache(env, data) {
+  const filePath = cachePath(env);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(data)}\n`, "utf8");
+}
+
+function cachePath(env) {
+  const base = env.ICUEWIDGET_UPDATE_CACHE_DIR || env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+  return path.join(base, "icuewidget-cli", "update-check.json");
+}
+
+function parseSemver(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(value);
+  return match ? match.slice(1, 4).map(Number) : undefined;
+}
+
+function printUpdateNotice(stderr, latestVersion) {
+  stderr.write(`Update available: ${APP_NAME} ${CLI_VERSION} → ${latestVersion}\n`);
+  stderr.write("npm:\n");
+  stderr.write(`  npm install -g ${NPM_PACKAGE_NAME}@latest\n`);
+}

package/src-node/validation.js

@@ -0,0 +1,157 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import vm from "node:vm";
+import {
+  ALLOWED_DEVICE_TYPES,
+  ALLOWED_PLATFORMS,
+  APP_VERSION_RE,
+  IDENTIFIER_RE,
+  SEMVER_RE,
+} from "./constants.js";
+import { ensureInside, pathExists, readJson } from "./fs-utils.js";
+
+export class ValidationError extends Error {}
+
+export async function validateWidget(widgetDir) {
+  const root = path.resolve(widgetDir);
+  const warnings = [];
+
+  for (const file of ["manifest.json", "index.html"]) {
+    if (!(await pathExists(path.join(root, file)))) {
+      throw new ValidationError(`Required file missing: ${file}`);
+    }
+  }
+
+  const manifest = await validateManifest(root);
+  if (await pathExists(path.join(root, "translation.json"))) {
+    await readJson(path.join(root, "translation.json"));
+  } else {
+    warnings.push("translation.json is missing; localized labels will not be available.");
+  }
+
+  await validateIndex(root, warnings);
+  return { widgetDir: root, manifest, warnings };
+}
+
+async function validateManifest(root) {
+  const manifest = await readJson(path.join(root, "manifest.json"));
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    throw new ValidationError("manifest.json must contain a JSON object");
+  }
+
+  for (const key of [
+    "author",
+    "id",
+    "name",
+    "description",
+    "version",
+    "preview_icon",
+    "min_app_version",
+    "min_framework_version",
+  ]) {
+    requireString(manifest, key, `manifest.${key}`);
+  }
+
+  if (!IDENTIFIER_RE.test(manifest.id)) throw new ValidationError("manifest.id may only contain letters, numbers, dots, and hyphens");
+  if (!SEMVER_RE.test(manifest.version)) throw new ValidationError("manifest.version must use semantic version format (for example 1.0.0)");
+  if (!APP_VERSION_RE.test(manifest.min_app_version)) throw new ValidationError("manifest.min_app_version must use iCUE version format (for example 5.45)");
+  if (!SEMVER_RE.test(manifest.min_framework_version)) throw new ValidationError("manifest.min_framework_version must use semantic version format (for example 1.0.0)");
+
+  await validateRelativeFile(root, manifest.preview_icon, "manifest.preview_icon");
+
+  if (!Array.isArray(manifest.os) || manifest.os.length === 0) throw new ValidationError("manifest.os must be a non-empty array");
+  for (const [index, os] of manifest.os.entries()) {
+    if (!os || typeof os !== "object") throw new ValidationError(`manifest.os[${index}] must be an object`);
+    if (!ALLOWED_PLATFORMS.has(os.platform)) throw new ValidationError(`manifest.os[${index}].platform must be one of: ${[...ALLOWED_PLATFORMS].join(", ")}`);
+  }
+
+  if (!Array.isArray(manifest.supported_devices) || manifest.supported_devices.length === 0) {
+    throw new ValidationError("manifest.supported_devices must be a non-empty array");
+  }
+  for (const [index, device] of manifest.supported_devices.entries()) {
+    if (!device || typeof device !== "object") throw new ValidationError(`manifest.supported_devices[${index}] must be an object`);
+    if (!ALLOWED_DEVICE_TYPES.has(device.type)) throw new ValidationError(`manifest.supported_devices[${index}].type must be one of: ${[...ALLOWED_DEVICE_TYPES].join(", ")}`);
+    if (device.features !== undefined) validateStringArray(device.features, `manifest.supported_devices[${index}].features`);
+  }
+
+  if (manifest.interactive !== undefined && typeof manifest.interactive !== "boolean") {
+    throw new ValidationError("manifest.interactive must be a boolean when provided");
+  }
+  if (manifest.required_plugins !== undefined) validateStringArray(manifest.required_plugins, "manifest.required_plugins");
+  if (manifest.modules !== undefined) {
+    validateStringArray(manifest.modules, "manifest.modules");
+    for (const modulePath of manifest.modules) await validateRelativeFile(root, modulePath, "manifest.modules");
+  }
+
+  return manifest;
+}
+
+async function validateIndex(root, warnings) {
+  const html = await fs.readFile(path.join(root, "index.html"), "utf8");
+  if (!/<title>[^<]+<\/title>/i.test(html)) warnings.push("index.html does not define a <title>.");
+  if (!/rel=["'][^"']*icon/i.test(html)) warnings.push("index.html does not reference a favicon/icon.");
+  if (!html.includes("icueEvents")) warnings.push("index.html or scripts do not reference icueEvents.");
+
+  const assetRefs = [...extractAttributes(html, "href"), ...extractAttributes(html, "src")];
+  for (const ref of assetRefs) {
+    if (isRemote(ref) || ref.startsWith("data:") || ref.startsWith("#")) continue;
+    await validateRelativeFile(root, stripQuery(ref), `index.html asset reference ${ref}`);
+    if (ref.endsWith(".css")) await validateCss(path.join(root, stripQuery(ref)));
+    if (ref.endsWith(".js")) await validateJs(path.join(root, stripQuery(ref)));
+  }
+}
+
+function* extractAttributes(html, attribute) {
+  const re = new RegExp(`${attribute}=["']([^"']+)["']`, "gi");
+  let match;
+  while ((match = re.exec(html))) yield match[1];
+}
+
+function stripQuery(value) {
+  return value.split(/[?#]/, 1)[0];
+}
+
+function isRemote(value) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(value) || value.startsWith("//");
+}
+
+async function validateCss(filePath) {
+  const css = await fs.readFile(filePath, "utf8");
+  const stack = [];
+  const pairs = { "(": ")", "[": "]", "{": "}" };
+  for (const char of css) {
+    if (pairs[char]) stack.push(pairs[char]);
+    else if ([")", "]", "}"].includes(char) && stack.pop() !== char) {
+      throw new ValidationError(`${path.basename(filePath)} has unbalanced CSS delimiters`);
+    }
+  }
+  if (stack.length) throw new ValidationError(`${path.basename(filePath)} has unbalanced CSS delimiters`);
+}
+
+async function validateJs(filePath) {
+  const code = await fs.readFile(filePath, "utf8");
+  try {
+    new vm.Script(code, { filename: filePath });
+  } catch (error) {
+    throw new ValidationError(`${path.basename(filePath)} has invalid JavaScript: ${error.message}`);
+  }
+}
+
+async function validateRelativeFile(root, relativePath, label) {
+  const resolved = path.resolve(root, relativePath);
+  if (!ensureInside(root, resolved)) throw new ValidationError(`${label} must stay inside the widget directory`);
+  if (!(await pathExists(resolved))) throw new ValidationError(`${label} does not exist: ${relativePath}`);
+}
+
+function requireString(object, key, label) {
+  if (typeof object[key] !== "string" || object[key].trim() === "") {
+    throw new ValidationError(`${label} must be a non-empty string`);
+  }
+}
+
+function validateStringArray(value, label) {
+  if (!Array.isArray(value)) throw new ValidationError(`${label} must be an array`);
+  for (const [index, item] of value.entries()) {
+    if (typeof item !== "string" || item.trim() === "") throw new ValidationError(`${label}[${index}] must be a non-empty string`);
+  }
+}