icuewidget-cli 0.4.47 → 0.4.49

package/README.md

@@ -4,9 +4,9 @@ This repository contains the `icuewidget` command-line tool for creating, valida
 
 The CLI uses:
 
-- Node.js so it can run through `npx` without a native installer
+- Node.js 18 or newer, so it runs through `npx` or a global npm install
 - built-in Node APIs for prompts, validation, and `.icuewidget` packaging
-- optional native installer builders for Windows `.exe` and macOS `.pkg`
+- no runtime dependencies
 
 ## Commands
 
@@ -21,18 +21,16 @@ The CLI uses:
 
 ```text
 .github/workflows/
-installer/
 node-bin/
-scripts/
 src-node/
 test-node/
 package-lock.json
 package.json
 ```
 
-## Run with npx
+## Install
 
-After publishing to npm:
+Run without installing:
 
 ```bash
 npx icuewidget-cli --help
@@ -42,6 +40,13 @@ npx icuewidget-cli update ./MyWidget --min-app-version 5.45
 npx icuewidget-cli package ./MyWidget
 ```
 
+Or install globally:
+
+```bash
+npm install -g icuewidget-cli
+icuewidget --help
+```
+
 ## Run locally without publishing
 
 ```bash
@@ -92,72 +97,5 @@ icuewidget init ./HelloWidget
 
 ## Versioning
 
-The source package uses the base version `0.4.0`. Release automation can set the
-third digit at build time with one of these environment variables:
-
-```bash
-CLI_BUILD_PATCH=123 npm run build
-CLI_BUILD_VERSION=0.4.123 npm run build
-```
-
-`CLI_BUILD_PATCH`, `BUILD_NUMBER`, or `GITHUB_RUN_NUMBER` produces
-`0.4.<patch>` for installer filenames and the bundled CLI `--version` output.
-
-For npm publishing, publish a full semantic version, for example:
-
-```bash
-npm version 0.4.123
-npm publish --access public
-```
-
-## npm publishing
-
-Before publishing, verify the package contents and tests:
-
-```bash
-npm test
-npm pack --dry-run
-```
-
-Then publish from this package directory:
-
-```bash
-npm publish --access public
-```
-
-Only the CLI runtime files listed in `package.json` are published to npm. The
-installer assets and build scripts stay in the repository and are excluded from
-the npm package.
-
-## Native installers
-
-The repository can also build native installers for users who do not want to use
-`npx` or `npm install -g`.
-
-Build standalone binaries first, then the platform installer:
-
-```bash
-npm run build
-```
-
-Outputs are written to:
-
-```text
-release/
-```
-
-Platform requirements:
-
-- Windows `.exe`: build on Windows with NSIS `makensis` on `PATH`
-- macOS `.pkg`: build on macOS with `pkgbuild` and `productbuild`
-
-By default, installer builds package the checked-out local CLI source. To build
-from a published npm package or tarball, set `CLI_PACKAGE_SPEC`:
-
-```bash
-CLI_PACKAGE_SPEC=icuewidget-cli@latest npm run build
-CLI_PACKAGE_SPEC=./corsair-icuewidget-cli-1.0.0.tgz npm run build
-```
-
-The installers include best-effort cleanup for older Python-distributed versions
-of `icuewidget-cli` before installing the standalone Node CLI binary.
+The CLI follows semantic versioning. The version lives only in `package.json`,
+and `icuewidget --version` reads it from there.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icuewidget-cli",
-  "version": "0.4.47",
+  "version": "0.4.49",
   "description": "Create, validate, update, and package CORSAIR iCUE widgets.",
   "keywords": [
     "corsair",
@@ -8,38 +8,33 @@
     "widget",
     "cli"
   ],
-  "homepage": "https://gitlab.com/corsair-gaming/various-projects/icuewidgets-cli#readme",
+  "homepage": "https://github.com/Corsair-Labs/icuewidget-cli#readme",
   "bugs": {
-    "url": "https://gitlab.com/corsair-gaming/various-projects/icuewidgets-cli/issues"
+    "url": "https://github.com/Corsair-Labs/icuewidget-cli/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/corsair-gaming/various-projects/icuewidgets-cli.git"
+    "url": "git+https://github.com/Corsair-Labs/icuewidget-cli.git"
   },
   "license": "Apache-2.0",
   "author": "CORSAIR",
   "type": "module",
-  "main": "index.js",
   "bin": {
     "icuewidget": "node-bin/icuewidget.js"
   },
   "files": [
     "node-bin/",
-    "src-node/",
-    "README.md"
+    "src-node/"
   ],
   "scripts": {
     "test": "node --test test-node/*.test.js",
-    "build:binaries": "node scripts/build-binaries.mjs",
-    "build:installers": "node scripts/build-installers.mjs",
-    "build": "npm run build:binaries && npm run build:installers",
-    "check": "node --check scripts/build-binaries.mjs && node --check scripts/build-installers.mjs"
-  },
-  "dependencies": {},
-  "devDependencies": {
-    "@yao-pkg/pkg": "^6.5.1"
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test"
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

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);
@@ -26,11 +28,18 @@ export async function main(argv = process.argv) {
       await runUpdateCheckWorker();
       return;
     }
-    if (args.length === 0 || has(args, "--help") || has(args, "-h")) {
+    if (args.length === 0) {
       printHelp();
       return;
     }
-    if (has(args, "--version") || has(args, "-v")) {
+    if (has(args, "--help") || has(args, "-h")) {
+      if (COMMANDS.includes(args[0])) printCommandHelp(args[0]);
+      else printHelp();
+      return;
+    }
+    // `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;
     }
@@ -165,9 +174,11 @@ function printHelp() {
   panel("Commands", [
     `${color.cyan("init")}      Creates a new widget from the starter template.`,
     `${color.cyan("validate")}  Validates widget files and manifest requirements.`,
-    `${color.cyan("update")}    Updates manifest requirements, bumps widget version, and regenerates package.`,
+    `${color.cyan("update")}    Sets the minimum iCUE version and/or widget version, then regenerates the package.`,
     `${color.cyan("package")}   Validates widget and creates an .icuewidget package.`,
   ]);
+  console.log(`Run ${color.bold(`${APP_NAME} <command> --help`)} for command-specific options.`);
+  console.log();
   panel("Examples", [
     `${APP_NAME} init HelloWidget`,
     `${APP_NAME} validate HelloWidget`,
@@ -177,6 +188,49 @@ function printHelp() {
   ], color.magenta);
 }
 
+const COMMAND_HELP = {
+  init: {
+    usage: "init [<dir>]",
+    summary: "Creates a new widget from the starter template, prompting for its details.",
+    options: [],
+    examples: ["init HelloWidget"],
+  },
+  validate: {
+    usage: "validate [<widget-dir>]",
+    summary: "Validates widget files and manifest requirements.",
+    options: [],
+    examples: ["validate HelloWidget"],
+  },
+  update: {
+    usage: "update [<widget-dir>] [--min-app-version <ver>] [--version <semver>] [-o <file>]",
+    summary: "Updates the manifest and regenerates the package. Prompts for min_app_version if it is missing.",
+    options: [
+      ["--min-app-version <ver>", "Set manifest.min_app_version (e.g. 5.45 or 5.45.104). Bumps the patch version unless --version is given."],
+      ["--version <semver>", "Set manifest.version (e.g. 1.0.1)."],
+      ["-o, --output <file>", "Write the package to this path."],
+    ],
+    examples: ["update HelloWidget --min-app-version 5.45", "update HelloWidget --version 1.0.1"],
+  },
+  package: {
+    usage: "package [<widget-dir>] [-o <file>]",
+    summary: "Validates the widget and creates an .icuewidget package.",
+    options: [["-o, --output <file>", "Write the package to this path."]],
+    examples: ["package HelloWidget", "package HelloWidget -o dist/hello.icuewidget"],
+  },
+};
+
+function printCommandHelp(command) {
+  const { usage, summary, options, examples } = COMMAND_HELP[command];
+  header(APP_NAME, CLI_VERSION);
+  console.log();
+  console.log(summary);
+  console.log();
+  console.log(`${color.yellow("Usage:")} ${color.bold(APP_NAME)} ${usage}`);
+  console.log();
+  if (options.length) panel("Options", options.map(([flag, text]) => `${color.cyan(flag)}  ${text}`));
+  panel("Examples", examples.map((example) => `${APP_NAME} ${example}`), color.magenta);
+}
+
 function parseArgs(args, specs = {}) {
   const options = {};
   const positionals = [];

package/src-node/constants.js

@@ -1,8 +1,12 @@
+import { readFileSync } from "node:fs";
+
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
 export const APP_NAME = "icuewidget";
-export const NPM_PACKAGE_NAME = "icuewidget-cli";
-export const CLI_VERSION = "0.4.47";
+export const NPM_PACKAGE_NAME = packageJson.name;
+export const CLI_VERSION = packageJson.version;
 export const DEFAULT_APP_VERSION = "5.45";
-export const DEFAULT_FRAMEWORK_VERSION = "1.0.0";
+export const DEFAULT_FRAMEWORK_VERSION = "1.4.0";
 export const DEFAULT_PLATFORM = "windows";
 export const DEFAULT_DEVICE_TYPE = "dashboard_lcd";
 

package/src-node/manifest-update.js

@@ -14,20 +14,23 @@ export async function updateManifestToLatest(widgetDir, options = {}) {
   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;
+  const currentMinAppVersion = typeof manifest.min_app_version === "string" ? manifest.min_app_version.trim() : "";
+  const currentIsValid = APP_VERSION_RE.test(currentMinAppVersion);
+  let minAppVersion;
+  if (options.minAppVersion !== undefined) {
+    // An explicit flag is a setter: validate it and apply it whenever it differs from the manifest.
+    minAppVersion = options.minAppVersion.trim();
+    if (!APP_VERSION_RE.test(minAppVersion)) throw new Error("--min-app-version must use iCUE version format like 5.45 or 5.45.104.");
+  } else if (!currentIsValid) {
+    minAppVersion = 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.",
+    );
+  }
+  if (minAppVersion !== undefined && minAppVersion !== manifest.min_app_version) {
+    manifest.min_app_version = minAppVersion;
     requirementChanges.push("manifest.min_app_version");
   }
 

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/validation.js

@@ -23,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 {
@@ -34,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");
@@ -78,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");
@@ -91,19 +103,23 @@ 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).
@@ -215,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) {