@aiot-nexus/plugin-sdk 2.1.1 → 3.0.2

package/templates/sqlite/README.md.tmpl

@@ -17,16 +17,18 @@ The check follows the npm-configured registry, falls back to the official npm re
 
 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.
 
 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 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;