@lvgl/lvglpro 2.0.1-120-g4cb6d6

package/README.md

@@ -0,0 +1,163 @@
+# LVGL Pro CLI
+
+The LVGL Pro CLI provides command-line access to LVGL Pro Editor workflows. It can generate C code from XML projects, compile project runtimes, validate projects, compare generated output, run XML interaction tests, and capture screenshots.
+
+**NOTE**: The LVGL Pro CLI requires a token to operate. You can obtain the token from your [lvgl.io/pro](lvgl.io/pro) dashhboard, if your license supports it.
+
+## Features
+
+- Generate C code from LVGL XML projects
+- Compile editor or CLI runtimes
+- Validate project XML and report contextual errors
+- Compare generated output against reference directories
+- Run one or all XML interaction tests in a headless runtime
+- Capture screenshots from LVGL 9.5 or newer projects
+- Keep the local LVGL resource cache synchronized with the CLI package
+
+## Installation
+
+`npm install --global @lvgl/lvglpro`
+
+## Usage
+
+```bash
+lvglpro <command> [arguments] [options]
+```
+
+Use `--help` for the complete command list or `<command> --help` for command-specific options:
+
+```bash
+lvglpro --help
+lvglpro generate --help
+```
+
+## Authentication
+
+Every command requires a valid LVGL license token. Pass it to an individual command with `--token`:
+
+```bash
+lvglpro generate ./my-project --token <license-token>
+```
+
+Alternatively, set `LVGLPRO_CLI_TOKEN` for the current shell or CI job:
+
+```bash
+# macOS/Linux
+export LVGLPRO_CLI_TOKEN=<license-token>
+
+# PowerShell
+$env:LVGLPRO_CLI_TOKEN = '<license-token>'
+```
+
+The `--token` value takes precedence over `LVGLPRO_CLI_TOKEN`.
+
+## Resources
+
+The CLI distribution includes `lvgl-resources.zip`. During normal setup, the CLI checks the cached resource hash and extracts updated resources into:
+
+- Windows: `%APPDATA%\lvgl-editor\resources`
+- macOS: `~/Library/Application Support/lvgl-editor/resources`
+- Linux: `~/.config/lvgl-editor/resources`
+
+`generate` and `compile` accept `--skip-resources` when the cache has already been prepared. This skips both the hash check and resource copy.
+
+## Commands
+
+### `generate <project-path>`
+
+Generate C code from the XML project.
+
+Options:
+
+- `--token <license-token>`: Provide the license token for this command.
+- `--ignore-fonts`: Skip font conversion.
+- `--ignore-images`: Skip image conversion.
+- `--skip-resources`: Skip checking and copying the resource cache.
+
+### `compile <project-path>`
+
+Compile the project runtime.
+
+Options:
+
+- `--target <target>`: Build `cli` or `editor` output. Defaults to `cli`.
+- `--token <license-token>`: Provide the license token for this command.
+- `--skip-resources`: Skip checking and copying the resource cache.
+
+The `cli` target builds the Node runtime used by test and screenshot commands. The `editor` target builds the web runtime used by the editor.
+
+### `validate <project-path>`
+
+Validate the XML project and report files containing errors.
+
+Options:
+
+- `-l, --errorlimit <amount>`: Maximum number of errors to display. Defaults to `10`.
+- `--token <license-token>`: Provide the license token for this command.
+
+### `compare <first-project-path> <second-project-path>`
+
+Recursively compare two directories and report missing, additional, or changed files.
+
+Options:
+
+- `--token <license-token>`: Provide the license token for this command.
+
+### `run-test <project-path> <testing-file>`
+
+Run one XML interaction test. `testing-file` is relative to the project directory. A CLI runtime is built automatically if the project does not already contain one.
+
+Options:
+
+- `--slowdown <number>`: Delay test execution for observation. `0` is fastest and is the default.
+- `--token <license-token>`: Provide the license token for this command.
+
+### `run-all-tests <project-path>`
+
+Recursively run project XML files whose names start with `test` and end with `.xml`. A CLI runtime is built automatically if necessary.
+
+Options:
+
+- `--slowdown <number>`: Delay test execution for observation. `0` is fastest and is the default.
+- `--token <license-token>`: Provide the license token for this command.
+
+### `screenshot <project-path> <screen>`
+
+Capture a PNG of the selected screen. Screenshots require LVGL 9.5 or newer. A CLI runtime is built automatically if necessary.
+
+Options:
+
+- `--out <out-file>`: Output path. Defaults to `<screen-name>.png` in the current directory.
+- `--delay <delay>`: Delay capture by the given number of milliseconds. Defaults to `0`.
+- `--token <license-token>`: Provide the license token for this command.
+
+## Examples
+
+```bash
+# Generate code without converting fonts or images
+lvglpro generate ./my-project --ignore-fonts --ignore-images
+
+# Generate code using an already-prepared resource cache
+lvglpro generate ./my-project --skip-resources
+
+# Compile the Node runtime used by CLI tests
+lvglpro compile ./my-project --target cli
+
+# Compile the editor web runtime
+lvglpro compile ./my-project --target editor
+
+# Validate a project and display at most five errors
+lvglpro validate ./my-project --errorlimit 5
+
+# Compare generated output with a reference directory
+lvglpro compare ./output ./expected
+
+# Run one interaction test
+lvglpro run-test ./my-project tests/test-navigation.xml --slowdown 2
+
+# Run every interaction test
+lvglpro run-all-tests ./my-project
+
+# Capture a screen after a 500 ms delay
+lvglpro screenshot ./my-project screens/main.xml --delay 500 --out ./main.png
+```

package/bin/lvglpro.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Entry point for the root @lvgl/lvglpro npm package. Delegates to the prebuilt bundle published
+// as a platform-specific optional dependency (e.g. @lvgl/lvglpro-linux-x64).
+'use strict';
+
+const platformKey = `${process.platform}-${process.arch}`;
+const rootPackageName = require('../package.json').name;
+const platformPackageName = `${rootPackageName}-${platformKey}`;
+
+let bundlePath;
+try {
+    bundlePath = require.resolve(`${platformPackageName}/lvglpro.js`);
+} catch {
+    console.error(`The LVGL CLI does not support this platform (${platformKey}).`);
+    console.error(`Expected optional dependency "${platformPackageName}" to be installed.`);
+    process.exit(1);
+}
+
+require(bundlePath);

package/package.json

@@ -0,0 +1,14 @@
+{
+    "name": "@lvgl/lvglpro",
+    "version": "2.0.1-120-g4cb6d6",
+    "description": "Command-line access to LVGL Pro Editor workflows: generate C code from XML projects, compile runtimes, validate projects, and more.",
+    "license": "MIT",
+    "bin": {
+        "lvglpro": "bin/lvglpro.js"
+    },
+    "optionalDependencies": {
+        "@lvgl/lvglpro-win32-x64": "2.0.1-120-g4cb6d6",
+        "@lvgl/lvglpro-linux-x64": "2.0.1-120-g4cb6d6",
+        "@lvgl/lvglpro-darwin-arm64": "2.0.1-120-g4cb6d6"
+    }
+}