icuewidget-cli 0.4.45 → 0.4.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icuewidget-cli",
-  "version": "0.4.45",
+  "version": "0.4.48",
   "description": "Create, validate, update, and package CORSAIR iCUE widgets.",
   "keywords": [
     "corsair",

package/src-node/cli.js

@@ -19,6 +19,8 @@ import { notifyAboutUpdate, runUpdateCheckWorker } from "./update-check.js";
 import { ValidationError, validateWidget } from "./validation.js";
 import { createPackage } from "./zip.js";
 
+const COMMANDS = ["init", "validate", "update", "package"];
+
 export async function main(argv = process.argv) {
   try {
     const args = argv.slice(2);
@@ -30,7 +32,9 @@ export async function main(argv = process.argv) {
       printHelp();
       return;
     }
-    if (has(args, "--version") || has(args, "-v")) {
+    // `update <widget> --version <semver>` uses --version as a subcommand option, so only
+    // treat it as the global flag when no subcommand leads the argument list.
+    if (!COMMANDS.includes(args[0]) && (has(args, "--version") || has(args, "-v"))) {
       console.log(CLI_VERSION);
       return;
     }

package/src-node/constants.js

@@ -1,6 +1,6 @@
 export const APP_NAME = "icuewidget";
 export const NPM_PACKAGE_NAME = "icuewidget-cli";
-export const CLI_VERSION = "0.4.45";
+export const CLI_VERSION = "0.4.48";
 export const DEFAULT_APP_VERSION = "5.45";
 export const DEFAULT_FRAMEWORK_VERSION = "1.0.0";
 export const DEFAULT_PLATFORM = "windows";
@@ -13,6 +13,21 @@ export const ALLOWED_DEVICE_TYPES = new Set([
   "keyboard_lcd",
 ]);
 
+// Control types accepted by iCUE for x-icue-property meta parameters (data-type).
+// Anything else makes iCUE reject the widget with "Invalid meta parameter data type".
+export const ALLOWED_PROPERTY_TYPES = new Set([
+  "slider",
+  "switch",
+  "color",
+  "combobox",
+  "search-combobox",
+  "tab-buttons",
+  "textfield",
+  "media-selector",
+  "sensors-combobox",
+  "sensors-factory",
+]);
+
 export const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 export const APP_VERSION_RE = /^\d+\.\d+(?:\.\d+)?$/;
 export const IDENTIFIER_RE = /^[A-Za-z0-9.-]+$/;

package/src-node/prompts.js

@@ -10,10 +10,30 @@ function reader() {
 
 export async function prompt(label, defaultValue = "") {
   const suffix = defaultValue ? ` (${defaultValue})` : "";
-  const answer = (await reader().question(`${label}${suffix}: `)).trim();
+  const answer = (await ask(`${label}${suffix}: `, label)).trim();
   return answer || defaultValue;
 }
 
+// readline never settles a pending question when stdin ends (closed pipe, CI, /dev/null), so
+// Node would exit 0 with the command half-run. Reject instead so the failure is visible.
+function ask(question, label) {
+  const rl = reader();
+  return new Promise((resolve, reject) => {
+    const onClose = () => reject(new Error(`Input ended while waiting for "${label}". Pass the value as a flag or run interactively.`));
+    rl.once("close", onClose);
+    rl.question(question).then(
+      (answer) => {
+        rl.off("close", onClose);
+        resolve(answer);
+      },
+      (error) => {
+        rl.off("close", onClose);
+        reject(error);
+      },
+    );
+  });
+}
+
 export async function promptValidated(label, defaultValue, validator, errorMessage) {
   while (true) {
     const answer = await prompt(label, defaultValue);

package/src-node/templates.js

@@ -15,21 +15,34 @@ export function translationTemplate(widgetName) {
 }
 
 export function indexTemplate(widgetName) {
-  return `<!doctype html>
+  // The widget title and the first property group share the widget name so the group
+  // merges with the default settings panel. tr() marks both for translation.
+  const titleExpr = `tr('${escapeSingleQuoted(widgetName)}')`;
+  const groups = renderGroups([
+    { title: titleExpr, properties: ["headline", "showSubtitle", "subtitle"] },
+    {
+      title: "tr('Widget Personalization')",
+      properties: ["textColor", "accentColor", "backgroundColor", "transparency"],
+    },
+  ]);
+  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}'>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(titleExpr)}</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="headline" data-label="tr('Headline')" data-type="textfield" data-default="'Hello World'" />
+  <meta name="x-icue-property" content="showSubtitle" data-label="tr('Show Subtitle')" data-type="switch" data-default="true" />
+  <meta name="x-icue-property" content="subtitle" data-label="tr('Subtitle')" data-type="textfield" data-default="'Built with iCUE Widget CLI'" />
+  <meta name="x-icue-property" content="textColor" data-label="tr('Text Color')" data-type="color" data-default="'#ffffff'" />
+  <meta name="x-icue-property" content="accentColor" data-label="tr('Accent Color')" data-type="color" data-default="'#59c2ff'" />
+  <meta name="x-icue-property" content="backgroundColor" data-label="tr('Background')" data-type="color" data-default="'#111827'" />
+  <meta name="x-icue-property" content="transparency" data-label="tr('Transparency')" data-type="slider" data-default="20" data-min="0" data-max="100" data-step="1" data-unit-label="'%'" />
+  <script id="x-icue-groups" type="application/json">
+${groups}
+  </script>
 </head>
 <body>
   <main id="content">
@@ -38,6 +51,16 @@ export function indexTemplate(widgetName) {
     <p id="subtitle">Built with iCUE Widget CLI</p>
   </main>
   <script src="scripts/main.js"></script>
+  <script>
+    icueEvents = {
+      onICUEInitialized: function(payload) { applySettings(payload && payload.settings); },
+      onDataUpdated: function(payload) { applySettings(payload && payload.settings); },
+    };
+
+    if (iCUE_initialized) {
+      applySettings();
+    }
+  </script>
 </body>
 </html>
 `;
@@ -115,15 +138,6 @@ function applySettings(settings = {}) {
   subtitle.hidden = !state.showSubtitle;
 }
 
-window.icueEvents = {
-  onICUEInitialized(payload) {
-    applySettings(payload?.settings);
-  },
-  onDataUpdated(payload) {
-    applySettings(payload?.settings);
-  },
-};
-
 applySettings();
 `;
 
@@ -149,3 +163,27 @@ function escapeHtml(value) {
     .replaceAll(">", "&gt;")
     .replaceAll('"', "&quot;");
 }
+
+// Escape a value for embedding inside a single-quoted JavaScript string, e.g. tr('...').
+function escapeSingleQuoted(value) {
+  return String(value).replaceAll("\\", "\\\\").replaceAll("'", "\\'");
+}
+
+// Render the x-icue-groups JSON body. Each group's title/info are already valid JS
+// expressions (e.g. tr('...')) and are serialized as JSON strings; properties stay inline.
+function renderGroups(groups) {
+  const body = groups
+    .map((group) => {
+      const props = group.properties.map((name) => JSON.stringify(name)).join(", ");
+      const lines = [
+        "    {",
+        `      "title": ${JSON.stringify(group.title)},`,
+        `      "properties": [${props}]${group.info ? "," : ""}`,
+      ];
+      if (group.info) lines.push(`      "info": ${JSON.stringify(group.info)}`);
+      lines.push("    }");
+      return lines.join("\n");
+    })
+    .join(",\n");
+  return `  [\n${body}\n  ]`;
+}

package/src-node/validation.js

@@ -4,6 +4,7 @@ import vm from "node:vm";
 import {
   ALLOWED_DEVICE_TYPES,
   ALLOWED_PLATFORMS,
+  ALLOWED_PROPERTY_TYPES,
   APP_VERSION_RE,
   IDENTIFIER_RE,
   SEMVER_RE,
@@ -22,7 +23,7 @@ export async function validateWidget(widgetDir) {
     }
   }
 
-  const manifest = await validateManifest(root);
+  const manifest = await validateManifest(root, warnings);
   if (await pathExists(path.join(root, "translation.json"))) {
     await readJson(path.join(root, "translation.json"));
   } else {
@@ -33,7 +34,7 @@ export async function validateWidget(widgetDir) {
   return { widgetDir: root, manifest, warnings };
 }
 
-async function validateManifest(root) {
+async function validateManifest(root, warnings) {
   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");
@@ -77,6 +78,18 @@ async function validateManifest(root) {
   if (manifest.interactive !== undefined && typeof manifest.interactive !== "boolean") {
     throw new ValidationError("manifest.interactive must be a boolean when provided");
   }
+  if (manifest.interactive === true) {
+    const nonDashboardTypes = manifest.supported_devices
+      .map((d) => d.type)
+      .filter((t) => t !== "dashboard_lcd");
+    if (nonDashboardTypes.length > 0) {
+      warnings.push(
+        `manifest.interactive is true, but supported_devices includes ${nonDashboardTypes.join(", ")}. ` +
+          `iCUE only recognizes interactive widgets on dashboard_lcd (Xeneon Edge). ` +
+          `The widget will not appear for ${nonDashboardTypes.join(" or ")} devices.`
+      );
+    }
+  }
   if (manifest.required_plugins !== undefined) validateStringArray(manifest.required_plugins, "manifest.required_plugins");
   if (manifest.modules !== undefined) {
     validateStringArray(manifest.modules, "manifest.modules");
@@ -90,15 +103,98 @@ 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.");
 
+  validateHeadWellFormed(html);
+  validatePropertyTypes(html);
+  validatePropertyGroups(html);
+
+  let referencesIcueEvents = html.includes("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)));
+    if (ref.endsWith(".js")) {
+      const code = await validateJs(path.join(root, stripQuery(ref)));
+      if (code.includes("icueEvents")) referencesIcueEvents = true;
+    }
   }
+  if (!referencesIcueEvents) warnings.push("index.html or scripts do not reference icueEvents.");
+}
+
+// iCUE imports a widget by parsing <head> with a strict XML parser (Qt QDomDocument).
+// HTML5 void elements written without a self-closing slash (e.g. `<meta charset="utf-8">`)
+// are well-formed HTML but invalid XML: the parser never closes the tag, fails at </head>,
+// and reports "Missing Title Element" because <title> is never reached. Catch it here so
+// the widget fails validation instead of silently producing a package iCUE cannot import.
+const VOID_ELEMENTS = ["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"];
+
+function validateHeadWellFormed(html) {
+  const headMatch = /<head\b[^>]*>([\s\S]*?)<\/head>/i.exec(html);
+  if (!headMatch) return;
+  const head = headMatch[1]
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/<script\b[\s\S]*?<\/script>/gi, "")
+    .replace(/<style\b[\s\S]*?<\/style>/gi, "");
+  const re = new RegExp(`<(${VOID_ELEMENTS.join("|")})\\b[^>]*?>`, "gi");
+  let match;
+  while ((match = re.exec(head))) {
+    if (!match[0].endsWith("/>")) {
+      throw new ValidationError(
+        `index.html <head> has a non-self-closed <${match[1].toLowerCase()}> element: ${match[0].trim()}. ` +
+          `iCUE parses the head as XML on import, so void elements must self-close (for example <${match[1].toLowerCase()} ... />). ` +
+          `Otherwise iCUE rejects the widget with "Missing Title Element".`
+      );
+    }
+  }
+}
+
+// Each x-icue-property meta declares a control via data-type. iCUE rejects the widget
+// with "Invalid meta parameter data type" if the value is not a known control type, so
+// catch unknown types (e.g. "text" instead of "textfield", "boolean" instead of "switch")
+// at validation time instead of on import.
+function validatePropertyTypes(html) {
+  const metaRe = /<meta\b[^>]*\bname=["']x-icue-property["'][^>]*>/gi;
+  let meta;
+  while ((meta = metaRe.exec(html))) {
+    const tag = meta[0];
+    const typeMatch = /\bdata-type=["']([^"']*)["']/i.exec(tag);
+    if (!typeMatch) {
+      throw new ValidationError(`x-icue-property is missing a data-type attribute: ${tag.trim()}`);
+    }
+    const type = typeMatch[1].trim();
+    if (!ALLOWED_PROPERTY_TYPES.has(type)) {
+      throw new ValidationError(
+        `x-icue-property has an invalid data-type "${type}". ` +
+          `iCUE accepts: ${[...ALLOWED_PROPERTY_TYPES].join(", ")}. ` +
+          `(For example use "textfield" for text input and "switch" for a boolean toggle.)`
+      );
+    }
+  }
+}
+
+// The x-icue-groups script organizes property controls into settings panels. iCUE
+// JSON-parses it, so malformed JSON or an empty group silently drops the panel. Catch
+// it here. Group title/info are JS expressions (e.g. tr('...')) but are always JSON
+// strings, so the block as a whole stays valid JSON.
+function validatePropertyGroups(html) {
+  const match = /<script\b[^>]*\bid=["']x-icue-groups["'][^>]*>([\s\S]*?)<\/script>/i.exec(html);
+  if (!match) return;
+  let groups;
+  try {
+    groups = JSON.parse(match[1]);
+  } catch (error) {
+    throw new ValidationError(`x-icue-groups is not valid JSON: ${error.message}`);
+  }
+  if (!Array.isArray(groups)) throw new ValidationError("x-icue-groups must be a JSON array of groups.");
+  groups.forEach((group, index) => {
+    if (!group || typeof group !== "object" || Array.isArray(group)) {
+      throw new ValidationError(`x-icue-groups[${index}] must be an object.`);
+    }
+    if (!Array.isArray(group.properties) || group.properties.length === 0) {
+      throw new ValidationError(`x-icue-groups[${index}] must list at least one property.`);
+    }
+  });
 }
 
 function* extractAttributes(html, attribute) {
@@ -135,6 +231,7 @@ async function validateJs(filePath) {
   } catch (error) {
     throw new ValidationError(`${path.basename(filePath)} has invalid JavaScript: ${error.message}`);
   }
+  return code;
 }
 
 async function validateRelativeFile(root, relativePath, label) {