@aiot-nexus/plugin-sdk 2.1.1 → 3.1.0

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": "2.1.1",
+  "version": "3.1.0",
   "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/.vscode/launch.json

@@ -9,7 +9,7 @@
       "cwd": "${workspaceFolder}"
     },
     {
-      "name": "Attach Nexus plugin worker (9229)",
+      "name": "Attach Nexus plugin main process (9229)",
       "type": "node",
       "request": "attach",
       "address": "127.0.0.1",

package/templates/minimal/README.md.tmpl

@@ -13,24 +13,25 @@ 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 host coordinates worker shutdown, atomic replacement, and worker reactivation without changing the Nexus PID.
+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.
 
-## Electron Facade file dialogs
+## Native Electron file dialogs
 
-`mainEntry` receives an asynchronous Electron 22 Facade through `context.host.electron`. A regular plugin can open native file, folder, and save dialogs without declaring `electronHostControl` or the legacy `dialog` permission:
+Framework API 3.0 loads trusted `mainEntry` code in the Electron main process. Import Electron 22 directly to open native file, folder, and save dialogs; no Facade or dialog permission is required:
 
 ```ts
 import * as fs from "fs/promises";
+import { dialog } from "electron";
 import type { NexusResult, PluginMainActivationContext } from "@aiot-nexus/plugin-sdk";
 
 const maximumTextFileBytes = 1024 * 1024;
 
 export async function chooseAndReadText(
-  context: PluginMainActivationContext
+  _context: PluginMainActivationContext
 ): Promise<NexusResult<string | undefined>> {
-  const result = await context.host.electron.dialog.showOpenDialog({
+  const result = await dialog.showOpenDialog({
     properties: ["openFile"],
     filters: [{ name: "Text", extensions: ["txt", "md", "json"] }]
   });
@@ -83,35 +84,35 @@ function failure(code: string, message: string): NexusResult<never> {
   return { ok: false, error: { code, message } };
 }
 
-export async function chooseFolder(context: PluginMainActivationContext): Promise<string | undefined> {
-  const result = await context.host.electron.dialog.showOpenDialog({
+export async function chooseFolder(): Promise<string | undefined> {
+  const result = await dialog.showOpenDialog({
     properties: ["openDirectory", "createDirectory"]
   });
   return result.canceled ? undefined : result.filePaths[0];
 }
 
-export async function chooseSavePath(context: PluginMainActivationContext): Promise<string | undefined> {
-  const result = await context.host.electron.dialog.showSaveDialog({ defaultPath: "document.txt" });
+export async function chooseSavePath(): Promise<string | undefined> {
+  const result = await dialog.showSaveDialog({ defaultPath: "document.txt" });
   return result.canceled ? undefined : result.filePath;
 }
 ```
 
-Call these helpers from an operation registered with `context.host.registerRendererMethod`, then let the renderer invoke that narrow operation through `client.invokeMain()`. Return the `NexusResult` from `chooseAndReadText` directly so the renderer receives the stable `FileNotReadable`, `FileTooLarge`, or `FileReadFailed` code. Do not expose the Facade or unrestricted file paths to the iframe. For larger files, stream or paginate in `mainEntry` and return only bounded chunks or summaries instead of the whole file. `npm run dev:web` is renderer-only and deliberately has no `mainEntry`, Node filesystem, or Electron Facade; use `npm run dev` or a formal Nexus host to test these dialogs.
+Call these helpers from an operation registered with `context.host.registerRendererMethod`, then let the renderer invoke that narrow operation through `client.invokeMain()`. Return the `NexusResult` from `chooseAndReadText` directly so the renderer receives the stable `FileNotReadable`, `FileTooLarge`, or `FileReadFailed` code. Do not expose Electron objects or unrestricted file paths to the iframe. For larger files, stream or paginate in `mainEntry` and return only bounded chunks or summaries instead of the whole file. `npm run dev:web` is renderer-only and deliberately has no `mainEntry`, Node filesystem, or Electron main-process API; use `npm run dev` or a formal Nexus host to test these dialogs.
 
-The renderer calls the plugin-worker `demo.echo` operation through `@aiot-nexus/plugin-sdk`. The worker also calls `context.host.electron.app.getName()` during activation, so `npm run dev` verifies the real asynchronous Electron Facade path. Run `npm run validate` after changing the manifest or output layout.
+The renderer calls the trusted-main `demo.echo` operation through `@aiot-nexus/plugin-sdk`. The main entry also calls the directly imported `app.getName()` during activation, so `npm run dev` verifies the real Electron main-process path. Run `npm run validate` after changing the manifest or output layout.
 
 The renderer follows `context.language` and `context.themeMode` from Nexus, subscribes to in-place context updates without reloading the iframe, and includes `en-US` and `zh-CN` message catalogs. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host and simulate Nexus context changes. Below that toolbar, the iframe has no host padding, border, minimum size, or content-driven height and fills the remaining host viewport. Add or edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
 The current SDK has no generic business-event subscription API. For a long-running operation, register a fast `job.start` operation that returns a `taskId`, then expose `job.getStatus` and optional `job.cancel` for renderer polling. See the Nexus repository's plugin IPC and event notification example for the full contract and code.
 
-Use `npm run dev:web` for renderer-only UI work in the system browser. It runs `build:web`, writes an isolated package under `.nexus-plugin-dev/web-package/`, builds with source maps, serves only on `127.0.0.1:4173`, and opens the browser automatically. It does not execute `mainEntry`, create a worker, provide Electron Facade, or overwrite the deployable `dist` package. Language and theme controls still simulate Nexus context, while `invokeMain` is intentionally unavailable. Pass `-- --no-open` or `-- --port <port>` when needed; use `npm run dev` for Host API and Electron integration.
+Use `npm run dev:web` for renderer-only UI work in the system browser. It runs `build:web`, writes an isolated package under `.nexus-plugin-dev/web-package/`, builds with source maps, serves only on `127.0.0.1:4173`, and opens the browser automatically. It does not execute `mainEntry`, provide Node or Electron main-process APIs, or overwrite the deployable `dist` package. Language and theme controls still simulate Nexus context, while `invokeMain` is intentionally unavailable. Pass `-- --no-open` or `-- --port <port>` when needed; use `npm run dev` for Host API and Electron integration.
 
-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 worker-sensitive manifest changes rebuild the full package, stop the old plugin worker, replace the package, and start a new worker while keeping the Nexus PID. Failed builds keep the previous deployment; a failed worker reload rolls the package back and restores the previous worker. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
+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 plugin-worker breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. If child-process auto attach is disabled, start `npm run dev:debug` and select `Attach Nexus plugin worker (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.
+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.
 
 The independent host stores data under `.nexus-plugin-dev/` and mirrors the PluginFrame protocol and current Host API surface. Its simulated Nexus application version defaults to the version recorded by the SDK build; pass `npm run dev -- --host-version <X.Y.Z>` to exercise another compatibility branch. Run the deployable `dist/__PLUGIN_ID__/` in Nexus before delivery because the standalone host does not reproduce the full application shell or routing state.

package/templates/minimal/src/main.ts.tmpl

@@ -1,8 +1,9 @@
+import { app } from "electron";
 import type { PluginMainActivationContext } from "@aiot-nexus/plugin-sdk";
 
-export async function activate(context: PluginMainActivationContext): Promise<void> {
-  const applicationName = await context.host.electron.app.getName();
-  const registration = await context.host.registerRendererMethod("demo.echo", (request) => {
+export function activate(context: PluginMainActivationContext): void {
+  const applicationName = app.getName();
+  const registration = context.host.registerRendererMethod("demo.echo", (request) => {
     const value = request.input && typeof request.input.value === "string"
       ? request.input.value.trim()
       : "";
@@ -20,7 +21,7 @@ export async function activate(context: PluginMainActivationContext): Promise<vo
   if (!registration.ok) {
     throw new Error(registration.error.message);
   }
-  const logResult = await context.host.log("info", "__PLUGIN_ID__ activated in " + applicationName + ".");
+  const logResult = context.host.log("info", "__PLUGIN_ID__ activated in " + applicationName + ".");
   if (!logResult.ok) {
     throw new Error(logResult.error.message);
   }

package/templates/sqlite/.vscode/launch.json

@@ -9,7 +9,7 @@
       "cwd": "${workspaceFolder}"
     },
     {
-      "name": "Attach Nexus plugin worker (9229)",
+      "name": "Attach Nexus plugin main process (9229)",
       "type": "node",
       "request": "attach",
       "address": "127.0.0.1",

package/templates/sqlite/README.md.tmpl

@@ -13,20 +13,22 @@ 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.
 
-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 host coordinates worker shutdown, atomic replacement, and worker reactivation without changing the Nexus PID. Runtime data is stored in the host-provided plugin data directory and is not written into the plugin package.
+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. Runtime data is stored in the host-provided plugin data directory and is not written into the plugin package.
 
-The template is a schema-aware SQLite database browser. It opens `plugin.db` in the plugin data directory by default and initializes the `plugin_records` sample table there. **Open Database** calls `context.host.electron.dialog.showOpenDialog()` from `mainEntry`; it accepts a single existing SQLite file, including files without an extension. A regular plugin can use this dialog Facade without `electronHostControl`. The renderer only displays the selected path and invokes parameterized operations. It never receives an Electron object and does not expose a path input, arbitrary SQL, DDL, `ATTACH`, or a SQL console.
+The template is a schema-aware SQLite database browser. It opens `plugin.db` in the plugin data directory by default and initializes the `plugin_records` sample table there. **Open Database** calls Electron's directly imported `dialog.showOpenDialog()` from trusted `mainEntry`; it accepts a single existing SQLite file, including files without an extension. The renderer only displays the selected path and invokes parameterized operations. It never receives an Electron object and does not expose a path input, arbitrary SQL, DDL, `ATTACH`, or a SQL console.
 
-## Electron Facade database dialog
+## Native Electron database dialog
 
-The template's `sqlite.chooseDatabase` operation uses the same asynchronous Electron Facade available to other v2 plugins. The essential call in `src/main.ts` is:
+Framework API 3.0 loads trusted `mainEntry` code in the Electron main process. The `sqlite.chooseDatabase` operation imports Electron 22 directly; the essential call in `src/main.ts` is:
 
 ```ts
-const result = await context.host.electron.dialog.showOpenDialog({
+import { dialog } from "electron";
+
+const result = await dialog.showOpenDialog({
   title: "Open SQLite database",
   properties: ["openFile"],
   filters: [
@@ -41,24 +43,24 @@ if (!result.canceled && result.filePaths[0]) {
 }
 ```
 
-For related workflows, use `properties: ["openDirectory", "createDirectory"]` to choose a folder or `context.host.electron.dialog.showSaveDialog()` to choose a save path. These calls belong in `mainEntry`; the renderer should invoke a registered business operation such as `sqlite.chooseDatabase` through `client.invokeMain()` and receive only the result it needs. No `electronHostControl` or legacy `dialog` permission is required. Native dialogs are unavailable in `npm run dev:web`; use `npm run dev` or a formal Nexus host.
+For related workflows, use `properties: ["openDirectory", "createDirectory"]` to choose a folder or `dialog.showSaveDialog()` to choose a save path. These calls belong in trusted `mainEntry`; the renderer should invoke a registered business operation such as `sqlite.chooseDatabase` through `client.invokeMain()` and receive only the result it needs. Native dialogs are unavailable in `npm run dev:web`; use `npm run dev` or a formal Nexus host.
 
 External files are opened read/write only after a separate candidate connection can query `sqlite_schema`. Canceling the dialog or selecting a corrupt, locked, or inaccessible file keeps the current connection. The latest external path is atomically stored as `sqlite-browser-state.json` in the plugin data directory. Startup restores it when valid; otherwise the template clears the saved selection, falls back to `plugin.db`, and returns a visible notice. External databases do not receive the sample schema or journal pragma.
 
-The table selector lists ordinary user tables from the `main` schema. Dynamic headers show declared type, SQLite affinity, primary-key order, NULL, default, and generated-column metadata. The editor supports default/NULL/value modes for inserts and unchanged/NULL/value modes for updates. INTEGER input uses exact decimal integers, REAL must be finite, NUMERIC accepts integer, real, or text values, and BLOB input uses even-length hexadecimal text. The 1 MiB field and 4 MiB row limits count decoded BLOB bytes rather than hexadecimal characters. Ordinary rowid tables prefer an unshadowed built-in rowid; `WITHOUT ROWID` tables, or tables that shadow every rowid alias, fall back only to primary-key columns that are all non-NULL. A table without a unique locator remains browsable and insertable, but update and delete are unavailable. Primary-key locators larger than 16 KiB are also treated as browse-only so a page cannot copy unbounded keys into the plugin worker and iframe. Update and delete run in a transaction and must affect exactly one row. TEXT previews are capped at 16 KiB of UTF-8 data; BLOB previews show the byte length and first 32 bytes.
+The table selector lists ordinary user tables from the `main` schema. Dynamic headers show declared type, SQLite affinity, primary-key order, NULL, default, and generated-column metadata. The editor supports default/NULL/value modes for inserts and unchanged/NULL/value modes for updates. INTEGER input uses exact decimal integers, REAL must be finite, NUMERIC accepts integer, real, or text values, and BLOB input uses even-length hexadecimal text. The 1 MiB field and 4 MiB row limits count decoded BLOB bytes rather than hexadecimal characters. Ordinary rowid tables prefer an unshadowed built-in rowid; `WITHOUT ROWID` tables, or tables that shadow every rowid alias, fall back only to primary-key columns that are all non-NULL. A table without a unique locator remains browsable and insertable, but update and delete are unavailable. Primary-key locators larger than 16 KiB are also treated as browse-only so a page cannot copy unbounded keys into the trusted main process and iframe. Update and delete run in a transaction and must affect exactly one row. TEXT previews are capped at 16 KiB of UTF-8 data; BLOB previews show the byte length and first 32 bytes.
 
 The renderer follows `context.language` and `context.themeMode` from Nexus and preserves unfinished editor values during in-place context updates. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host. Below that toolbar, the iframe has no host padding, border, minimum size, or content-driven height and fills the remaining host viewport. This SDK template deliberately has no Quasar dependency, so its data grid uses a native `<table>` as a dependency-minimized template exception. It still provides pagination, contained horizontal scrolling, light/dark themes, `en-US` / `zh-CN`, and busy/empty/error states. Edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
 The current SDK has no generic business-event subscription API. For a long-running operation, register a fast `job.start` operation that returns a `taskId`, then expose `job.getStatus` and optional `job.cancel` for renderer polling. See the Nexus repository's plugin IPC and event notification example for the full contract and code.
 
-Use `npm run dev:web` for renderer-only layout, styling, localization, and responsive checks in the system browser. It runs `build:web`, writes an isolated package under `.nexus-plugin-dev/web-package/`, and does not rebuild or load `better-sqlite3`, execute `mainEntry`, create a worker, provide Electron Facade, copy native runtime files, or overwrite the deployable `dist` package. It builds with source maps, serves only on `127.0.0.1:4173`, and opens the browser automatically. The page explicitly reports `PluginCapabilityUnsupported`; file selection, table loading, and CRUD require `npm run dev` or a formal Nexus host. Pass `-- --no-open` or `-- --port <port>` when needed.
+Use `npm run dev:web` for renderer-only layout, styling, localization, and responsive checks in the system browser. It runs `build:web`, writes an isolated package under `.nexus-plugin-dev/web-package/`, and does not rebuild or load `better-sqlite3`, execute `mainEntry`, provide Node or Electron main-process APIs, copy native runtime files, or overwrite the deployable `dist` package. It builds with source maps, serves only on `127.0.0.1:4173`, and opens the browser automatically. The page explicitly reports `PluginCapabilityUnsupported`; file selection, table loading, and CRUD require `npm run dev` or a formal Nexus host. Pass `-- --no-open` or `-- --port <port>` when needed.
 
-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 worker-sensitive manifest changes run the complete build (including the Electron 22.3.27 native rebuild), stop the old plugin worker, replace the package, and start a new worker in the same Nexus process. The database remains under the host-provided plugin data directory across worker replacements. Failed builds keep the previous deployment, and a failed worker reload rolls the package back and restores the previous worker. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
+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 plugin-worker breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. If child-process auto attach is disabled, start `npm run dev:debug` and select `Attach Nexus plugin worker (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.
+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.
 
 The independent host stores the SQLite database and settings under `.nexus-plugin-dev/data/` and mirrors the PluginFrame protocol and current Host API surface. Its simulated Nexus application version defaults to the version recorded by the SDK build; pass `npm run dev -- --host-version <X.Y.Z>` to exercise another compatibility branch. Run the deployable `dist/__PLUGIN_ID__/` in Nexus before delivery because the standalone host does not reproduce the full application shell or routing state.

package/templates/sqlite/src/main.ts.tmpl

@@ -1,6 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import Database = require("better-sqlite3");
+import { app, dialog } from "electron";
 import type {
   NexusResult,
   PluginMainActivationContext,
@@ -149,24 +150,24 @@ let stateFilePath = "";
 let databaseNotice: string | undefined;
 let databaseSelectionPending = false;
 
-export async function activate(context: PluginMainActivationContext): Promise<void> {
+export function activate(context: PluginMainActivationContext): void {
   activationContext = context;
   fs.mkdirSync(context.host.pluginDataDirectory, { recursive: true });
   defaultDatabasePath = path.join(context.host.pluginDataDirectory, defaultDatabaseName);
   stateFilePath = path.join(context.host.pluginDataDirectory, stateFileName);
   activeDatabase = openInitialDatabase();
 
-  await register(context, "sqlite.getDatabaseInfo", handled(getDatabaseInfo));
-  await register(context, "sqlite.chooseDatabase", handledAsync(chooseDatabase));
-  await register(context, "sqlite.useDefaultDatabase", handledAsync(useDefaultDatabase));
-  await register(context, "sqlite.listTables", handled(listTables));
-  await register(context, "sqlite.readTable", handled(readTable));
-  await register(context, "sqlite.insertRow", handled(insertRow));
-  await register(context, "sqlite.updateRow", handled(updateRow));
-  await register(context, "sqlite.deleteRow", handled(deleteRow));
-
-  const applicationName = await context.host.electron.app.getName();
-  const logResult = await context.host.log(
+  register(context, "sqlite.getDatabaseInfo", handled(getDatabaseInfo));
+  register(context, "sqlite.chooseDatabase", handledAsync(chooseDatabase));
+  register(context, "sqlite.useDefaultDatabase", handledAsync(useDefaultDatabase));
+  register(context, "sqlite.listTables", handled(listTables));
+  register(context, "sqlite.readTable", handled(readTable));
+  register(context, "sqlite.insertRow", handled(insertRow));
+  register(context, "sqlite.updateRow", handled(updateRow));
+  register(context, "sqlite.deleteRow", handled(deleteRow));
+
+  const applicationName = app.getName();
+  const logResult = context.host.log(
     "info",
     "__PLUGIN_ID__ database " + (activeDatabase.created ? "created" : "loaded") + " in " + applicationName + ": " + activeDatabase.databasePath
   );
@@ -182,8 +183,8 @@ export function deactivate(): void {
   databaseSelectionPending = false;
 }
 
-async function register(context: PluginMainActivationContext, name: string, handler: PluginRendererOperationHandler): Promise<void> {
-  const result = await context.host.registerRendererMethod(name, handler);
+function register(context: PluginMainActivationContext, name: string, handler: PluginRendererOperationHandler): void {
+  const result = context.host.registerRendererMethod(name, handler);
   if (!result.ok) {
     throw new Error(result.error.message);
   }
@@ -286,11 +287,11 @@ async function chooseDatabase(): Promise<{ canceled: boolean; database: Database
   if (databaseSelectionPending) {
     throw codedError("Busy", "A database selection dialog is already open.");
   }
-  const context = requireActivationContext();
+  requireActivationContext();
   databaseSelectionPending = true;
   try {
     const current = requireDatabase();
-    const result = await context.host.electron.dialog.showOpenDialog({
+    const result = await dialog.showOpenDialog({
       title: "Open SQLite database",
       defaultPath: path.dirname(current.databasePath),
       properties: ["openFile"],
@@ -311,7 +312,7 @@ async function chooseDatabase(): Promise<{ canceled: boolean; database: Database
       candidate.connection.close();
       throw error;
     }
-    await logDatabaseSwitch("external", path.basename(candidate.databasePath));
+    logDatabaseSwitch("external", path.basename(candidate.databasePath));
     return { canceled: false, database: getDatabaseInfo() };
   } finally {
     databaseSelectionPending = false;
@@ -328,16 +329,19 @@ async function useDefaultDatabase(): Promise<{ database: DatabaseInfo }> {
     candidate.connection.close();
     throw error;
   }
-  await logDatabaseSwitch("default", defaultDatabaseName);
+  logDatabaseSwitch("default", defaultDatabaseName);
   return { database: getDatabaseInfo() };
 }
 
-async function logDatabaseSwitch(source: DatabaseSource, databaseName: string): Promise<void> {
+function logDatabaseSwitch(source: DatabaseSource, databaseName: string): void {
   const context = activationContext;
   if (!context) {
     return;
   }
-  await context.host.log("info", "__PLUGIN_ID__ switched to " + source + " database: " + databaseName);
+  const result = context.host.log("info", "__PLUGIN_ID__ switched to " + source + " database: " + databaseName);
+  if (!result.ok) {
+    throw new Error(result.error.message);
+  }
 }
 
 function replaceDatabase(candidate: ActiveDatabase): void {

package/dev-host/plugin-host.js

@@ -1,4 +0,0 @@
-"use strict";
-/* eslint-disable @typescript-eslint/no-var-requires */
-
-require("../dist/internal/src-electron/plugin-host-bootstrap.js");

package/dist/internal/src-electron/main/core/runtime-result.js

@@ -1,42 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.fail = exports.ok = exports.StatusCodes = void 0;
-exports.StatusCodes = {
-    InvalidRequest: "InvalidRequest",
-    NotFound: "NotFound",
-    UnexpectedFailure: "UnexpectedFailure",
-    ExternalAppDefinitionMissing: "ExternalAppDefinitionMissing",
-    ExternalAppDisabled: "ExternalAppDisabled",
-    ExternalAppLaunchSettingsMissing: "ExternalAppLaunchSettingsMissing",
-    ExternalAppExecutableNotConfigured: "ExternalAppExecutableNotConfigured",
-    ExternalAppExecutableInvalid: "ExternalAppExecutableInvalid",
-    ExternalAppExecutableMissing: "ExternalAppExecutableMissing",
-    ExternalAppWorkingDirectoryInvalid: "ExternalAppWorkingDirectoryInvalid",
-    ExternalAppWorkingDirectoryMissing: "ExternalAppWorkingDirectoryMissing",
-    ExternalAppStartFailed: "ExternalAppStartFailed",
-    DirectoryMissing: "DirectoryMissing",
-    PluginBlocked: "PluginBlocked",
-    PluginManifestInvalid: "PluginManifestInvalid",
-    PluginIncompatible: "PluginIncompatible",
-    PluginPermissionDenied: "PluginPermissionDenied",
-    PluginCapabilityUnsupported: "PluginCapabilityUnsupported",
-    PluginMainEntryFailed: "PluginMainEntryFailed",
-    ToolFileReadFailed: "ToolFileReadFailed",
-    XxbpDeferred: "XxbpDeferred",
-    XxbpInvalidRemotePath: "XxbpInvalidRemotePath",
-    XxbpToolUnavailable: "XxbpToolUnavailable",
-    XxbpCommandFailed: "XxbpCommandFailed",
-    XxbpCommandTimeout: "XxbpCommandTimeout",
-    XxbpOperationCancelled: "XxbpOperationCancelled",
-    XxbpDevicesSessionMissing: "XxbpDevicesSessionMissing",
-    XxbpResultFileMissing: "XxbpResultFileMissing",
-    XxbpNonTextFile: "XxbpNonTextFile"
-};
-function ok(value) {
-    return { ok: true, value };
-}
-exports.ok = ok;
-function fail(code, message, details) {
-    return { ok: false, error: { code, message, details } };
-}
-exports.fail = fail;