@aiot-nexus/plugin-sdk 3.0.2 → 3.1.1

package/dist/src/validation.js

@@ -34,6 +34,7 @@ const plugin_manifest_schema_json_1 = __importDefault(require("../.generated/plu
 const plugin_framework_version_1 = require("../.generated/plugin-framework-version");
 const manifestValidator = new _2020_1.default({ allErrors: true, strict: true })
     .compile(plugin_manifest_schema_json_1.default);
+const hostStatusBarFrameworkVersion = "3.1.0";
 function validatePluginPackage(packageDirectory, options = {}) {
     const resolvedDirectory = path.resolve(packageDirectory);
     try {
@@ -85,6 +86,11 @@ function validateResolvedPluginPackage(resolvedDirectory, options) {
     if (!(0, plugin_framework_version_1.isPluginFrameworkVersionCompatible)(manifest.hostApiVersion, plugin_framework_version_1.PLUGIN_FRAMEWORK_VERSION)) {
         errors.push("Plugin Framework API version is incompatible with " + plugin_framework_version_1.PLUGIN_FRAMEWORK_VERSION + ".");
     }
+    const hostStatusBarVersionComparison = (0, plugin_framework_version_1.comparePluginVersions)(manifest.hostApiVersion, hostStatusBarFrameworkVersion);
+    if (usesHostStatusBarDeclaration(manifest)
+        && (hostStatusBarVersionComparison === undefined || hostStatusBarVersionComparison < 0)) {
+        errors.push("businessEntries.showHostStatusBar requires Plugin Framework API 3.1.0 or newer.");
+    }
     if (!(0, plugin_framework_version_1.parsePluginCompatibleVersion)(manifest.minHostVersion)) {
         errors.push("minHostVersion contains an unsupported numeric version.");
     }
@@ -141,6 +147,9 @@ function usesPluginFrame(manifest) {
         || (manifest.tools || []).some((entry) => entry.component === "PluginFrame")
         || (manifest.settingsSections || []).some((entry) => entry.component === "PluginFrame");
 }
+function usesHostStatusBarDeclaration(manifest) {
+    return (manifest.businessEntries || []).some((entry) => (Object.prototype.hasOwnProperty.call(entry, "showHostStatusBar")));
+}
 function isPathInside(rootDirectory, childPath) {
     const relative = path.relative(path.resolve(rootDirectory), path.resolve(childPath));
     return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiot-nexus/plugin-sdk",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "description": "Types, PluginFrame client, and CLI for AIoT Nexus independent plugins.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -38,7 +38,7 @@
     "postinstall": "node scripts/sdk-update-check.js --install",
     "verify:package": "node scripts/verify-package.js",
     "test:types": "tsc -p tsconfig.types-test.json",
-    "test": "npm run build && npm run test:types && node tests/package.test.js && node tests/sdk-update-check.test.js && node tests/cli.test.js && node tests/cli-entry.test.js && node tests/update-notice.test.js && node tests/dev.test.js && node tests/nexus-dev.test.js && node tests/frame-client.test.js && node tests/web-dev.test.js && npm run verify:package",
+    "test": "npm run build && npm run test:types && node tests/package.test.js && node tests/sdk-update-check.test.js && node tests/cli.test.js && node tests/cli-entry.test.js && node tests/update-notice.test.js && node tests/upgrade.test.js && node tests/dev.test.js && node tests/nexus-dev.test.js && node tests/frame-client.test.js && node tests/web-dev.test.js && npm run verify:package",
     "prepack": "node scripts/prepack.js",
     "pack:sdk": "npm run build && npm run verify:package && node scripts/pack.js",
     "publish:sdk": "npm publish"

package/scripts/sdk-update-check.js

@@ -348,7 +348,7 @@ function formatUpdateNotice(result) {
   const lines = [
     "npm notice",
     "npm notice Update available for " + result.packageName + ": " + result.currentVersion + " -> " + result.latestVersion,
-    "npm notice Run npm install --save-dev " + result.packageName + "@latest"
+    "npm notice Run npx --package=" + result.packageName + "@" + result.latestVersion + " nexus-plugin upgrade ."
   ];
   if (result.isMajorUpdate) {
     lines.push("npm notice Major update: first confirm Nexus Framework API compatibility.");

package/templates/minimal/README.md.tmpl

@@ -13,7 +13,7 @@ npm run dev:nexus -- --host C:\path\to\nexus.exe
 
 SDK checks for a newer `@aiot-nexus/plugin-sdk` in two steps. The package `postinstall` refreshes a user cache; npm 7+ hides dependency lifecycle output by default, so use `npm install --foreground-scripts` to see it. The `nexus-plugin` CLI reads that cache and prints npm-style notices when it is fresh; missing or older-than-24-hours cache data is checked in the background without blocking the command. `npm install --ignore-scripts` skips only the install check, while CLI checks remain available.
 
-The check follows the npm-configured registry, falls back to the official npm registry when needed, and silently ignores offline, timeout, malformed-response, or corrupt-cache failures. Use `NEXUS_PLUGIN_SDK_UPDATE_CHECK=0` or `NO_UPDATE_NOTIFIER=1` to disable both checks. A major SDK update requires confirming Nexus Framework API compatibility; upgrades are never automatic. When a notice appears, review compatibility and run `npm install --save-dev @aiot-nexus/plugin-sdk@latest` manually.
+The check follows the npm-configured registry, falls back to the official npm registry when needed, and silently ignores offline, timeout, malformed-response, or corrupt-cache failures. Use `NEXUS_PLUGIN_SDK_UPDATE_CHECK=0` or `NO_UPDATE_NOTIFIER=1` to disable both checks. Notices never modify the project. When one appears, substitute the exact version printed by the notice for `X.Y.Z`: `npx --package=@aiot-nexus/plugin-sdk@X.Y.Z nexus-plugin upgrade . --check`, then repeat without `--check`. The transaction synchronizes package.json, package-lock.json, and node_modules, runs project checks, and rolls back on failure. A major update additionally requires `--allow-major` and the migration guide linked by the CLI; source and manifest files are never rewritten.
 
 The deployable plugin package is `dist/__PLUGIN_ID__/`. For a manual installation, stop Nexus before replacing `Plugins/__PLUGIN_ID__/`, then start it again. During development, use `npm run dev:nexus` so the CLI coordinates Nexus shutdown, atomic replacement, and restart for trusted `mainEntry` changes.
 
@@ -109,9 +109,9 @@ Use `npm run dev:web` for renderer-only UI work in the system browser. It runs `
 
 Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` for live development against a compiled, packaged Nexus. The CLI atomically deploys this plugin to `<exeDir>/Plugins/__PLUGIN_ID__/`. Renderer changes rebuild and reload the iframe without changing the Nexus PID; safe manifest changes rescan contributions in the same process; `mainEntry`, dependency, native-module, or restart-sensitive manifest changes stop Nexus, replace the complete package, and start a new Nexus process because trusted modules cannot be unloaded safely from Node's module cache. Failed builds keep the previous deployment; launch or readiness failures restore the previous package and host. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
 
-When this project was created from a local SDK archive, `vendor/aiot-nexus-plugin-sdk.tgz` is part of the source project and must be kept when the project is moved or committed.
+When this project was created from a local SDK archive, `vendor/aiot-nexus-plugin-sdk.tgz` is part of the source project and must be kept when the project is moved or committed. An explicit local upgrade copies the target archive to `vendor/aiot-nexus-plugin-sdk-<version>.tgz` and updates the exact file dependency.
 
-For a local SDK archive, the tgz version remains the plugin's current SDK version for comparison. It is not replaced automatically by a newer npm package; fully offline work can disable checks with the environment variables above.
+For a local SDK archive, the tgz version remains the plugin's current SDK version for comparison. It is not replaced automatically by a newer npm package; pass the target archive to both npx and `nexus-plugin upgrade --sdk-source <archive>`. Fully offline work can disable checks with the environment variables above.
 
 For trusted-main breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. To attach manually, start `npm run dev:debug` and select `Attach Nexus plugin main process (9229)`. Renderer DevTools opens automatically, with `src/renderer/app.ts` available through the development source map. `npm run dev` rebuilds before launch; use `npm run dev -- --no-build` only when intentionally reusing the current `dist` output.
 

package/templates/sqlite/README.md.tmpl

@@ -13,7 +13,7 @@ npm run dev:nexus -- --host C:\path\to\nexus.exe
 
 SDK checks for a newer `@aiot-nexus/plugin-sdk` in two steps. The package `postinstall` refreshes a user cache; npm 7+ hides dependency lifecycle output by default, so use `npm install --foreground-scripts` to see it. The `nexus-plugin` CLI reads that cache and prints npm-style notices when it is fresh; missing or older-than-24-hours cache data is checked in the background without blocking the command. `npm install --ignore-scripts` skips only the install check, while CLI checks remain available.
 
-The check follows the npm-configured registry, falls back to the official npm registry when needed, and silently ignores offline, timeout, malformed-response, or corrupt-cache failures. Use `NEXUS_PLUGIN_SDK_UPDATE_CHECK=0` or `NO_UPDATE_NOTIFIER=1` to disable both checks. A major SDK update requires confirming Nexus Framework API compatibility; upgrades are never automatic. When a notice appears, review compatibility and run `npm install --save-dev @aiot-nexus/plugin-sdk@latest` manually.
+The check follows the npm-configured registry, falls back to the official npm registry when needed, and silently ignores offline, timeout, malformed-response, or corrupt-cache failures. Use `NEXUS_PLUGIN_SDK_UPDATE_CHECK=0` or `NO_UPDATE_NOTIFIER=1` to disable both checks. Notices never modify the project. When one appears, substitute the exact version printed by the notice for `X.Y.Z`: `npx --package=@aiot-nexus/plugin-sdk@X.Y.Z nexus-plugin upgrade . --check`, then repeat without `--check`. The transaction synchronizes package.json, package-lock.json, and node_modules, runs project checks (including the Electron 22 native rebuild), and rolls back on failure. A major update additionally requires `--allow-major` and the migration guide linked by the CLI; source and manifest files are never rewritten.
 
 Every `npm run build` rebuilds `better-sqlite3@8.7.0` for Electron 22.3.27 with `@electron/rebuild@3.7.2` before packaging. `npm run rebuild:native` remains available as a standalone diagnostic command.
 
@@ -57,9 +57,9 @@ Use `npm run dev:web` for renderer-only layout, styling, localization, and respo
 
 Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` to run the plugin inside a compiled, packaged Nexus. The initial deployment and every full package replacement are atomic. Renderer-only and safe manifest updates keep the Nexus PID; `mainEntry`, dependency, native-module, or restart-sensitive manifest changes run the complete build (including the Electron 22.3.27 native rebuild), stop Nexus, replace the package, and start a new Nexus process. The database remains under the host-provided plugin data directory across host restarts. Failed builds keep the previous deployment, and launch or readiness failures roll the package back and restore the previous host. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
 
-When this project was created from a local SDK archive, `vendor/aiot-nexus-plugin-sdk.tgz` is part of the source project and must be kept when the project is moved or committed.
+When this project was created from a local SDK archive, `vendor/aiot-nexus-plugin-sdk.tgz` is part of the source project and must be kept when the project is moved or committed. An explicit local upgrade copies the target archive to `vendor/aiot-nexus-plugin-sdk-<version>.tgz` and updates the exact file dependency.
 
-For a local SDK archive, the tgz version remains the plugin's current SDK version for comparison. It is not replaced automatically by a newer npm package; fully offline work can disable checks with the environment variables above.
+For a local SDK archive, the tgz version remains the plugin's current SDK version for comparison. It is not replaced automatically by a newer npm package; pass the target archive to both npx and `nexus-plugin upgrade --sdk-source <archive>`. Fully offline work can disable checks with the environment variables above.
 
 For trusted-main breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. To attach manually, start `npm run dev:debug` and select `Attach Nexus plugin main process (9229)`. Renderer DevTools opens automatically, with `src/renderer/app.ts` available through the development source map. The default debug build also runs the Electron 22.3.27 native rebuild before launch. Use `npm run dev -- --no-build` only when intentionally reusing a compatible current `dist` output.