@aiot-nexus/plugin-sdk 1.1.1 → 2.0.0

package/dist/src/nexus-dev.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.shouldSuppressNativeBuildEvent = exports.isRetryablePluginDeploymentError = exports.createNexusHostArguments = exports.mergePluginSourceChange = exports.manifestChangeRequiresRestart = exports.classifyPluginSourceChange = exports.runPluginNexusDev = void 0;
+exports.shouldSuppressNativeBuildEvent = exports.isRetryablePluginDeploymentError = exports.createNexusHostArguments = exports.mergePluginSourceChange = exports.manifestChangeRequiresPackageUpdate = exports.classifyPluginSourceChange = exports.recoverPreparedPluginPackageUpdate = exports.runPluginNexusDev = void 0;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -41,8 +41,6 @@ class PluginNexusDevSession {
         this.control = new nexus_dev_control_1.NexusDevControlServer();
         this.deployedPluginDirectory = "";
         this.expectedExits = new Set();
-        this.provisionalChildren = new Set();
-        this.restarting = false;
         this.stopping = false;
         this.terminalSettled = false;
         this.terminalPromise = new Promise((resolve) => {
@@ -76,7 +74,7 @@ class PluginNexusDevSession {
         try {
             await this.control.start();
             this.disposeDisconnectHandler = this.control.setDisconnectHandler((error) => {
-                if (!this.stopping && !this.restarting) {
+                if (!this.stopping) {
                     this.io.stderr("Packaged Nexus plugin development control disconnected: " + error.message);
                     this.settleTerminal(1);
                 }
@@ -88,7 +86,7 @@ class PluginNexusDevSession {
             }
             this.watcher = new PluginSourceWatcher(this.projectDirectory, async (kind) => {
                 const currentTarget = this.requireTarget();
-                await applyPluginSourceChange(kind, this.options, currentTarget, this.deployedPluginDirectory, this.control, this.io, () => this.restartHost(), () => this.runBuild(() => (0, dev_1.buildPluginRendererForDevelopment)(currentTarget.projectDirectory)));
+                await applyPluginSourceChange(kind, this.options, currentTarget, this.deployedPluginDirectory, this.control, this.io, () => this.updatePluginPackage(), () => this.runBuild(() => (0, dev_1.buildPluginRendererForDevelopment)(currentTarget.projectDirectory)));
             }, this.io);
             this.watcher.start();
             this.io.stdout("Watching plugin source changes. Press Ctrl+C to stop.");
@@ -105,9 +103,9 @@ class PluginNexusDevSession {
             await this.control.close();
         }
     }
-    async restartHost() {
+    async updatePluginPackage() {
         const previousTarget = this.requireTarget();
-        this.io.stdout("Building complete plugin package before restarting Nexus...");
+        this.io.stdout("Building complete plugin package before restarting the plugin worker...");
         this.runBuild(() => (0, dev_1.buildPluginForDevelopment)(this.projectDirectory));
         const updatedTarget = (0, dev_1.preparePluginDebugTarget)({
             projectDirectory: this.projectDirectory,
@@ -119,27 +117,19 @@ class PluginNexusDevSession {
         if (updatedTarget.pluginId !== previousTarget.pluginId) {
             throw new dev_1.PluginDevError("Plugin id cannot change during a Nexus development session.");
         }
-        this.restarting = true;
         let transaction;
-        let transactionCommitted = false;
+        let prepareAttempted = false;
         try {
-            await this.shutdownHostForRestart();
-            transaction = await retryFileOperation(() => (0, nexus_dev_deployment_1.beginPluginPackageDeployment)(updatedTarget.packageDirectory, this.nexusExecutable, updatedTarget.pluginId), "replace the plugin package");
-            try {
-                const updatedChild = await this.launchHost(updatedTarget, true);
-                await this.ensureProvisionalHostIsStable(updatedChild);
-                this.acceptProvisionalHost(updatedChild);
+            prepareAttempted = true;
+            const prepareResult = await this.control.sendUpdate("packageUpdatePreparing", previousTarget.pluginId);
+            if (!prepareResult.ok) {
+                throw new dev_1.PluginDevError(prepareResult.message);
             }
-            catch (error) {
-                await this.stopCurrentHost();
-                await retryFileOperation(() => transaction?.rollback(), "roll back the plugin package");
-                const previousChild = await this.launchHost(previousTarget, true);
-                await this.ensureProvisionalHostIsStable(previousChild);
-                this.acceptProvisionalHost(previousChild);
-                throw new dev_1.PluginDevError("Updated Nexus host failed to start; the previous plugin package was restored. " + errorMessage(error));
+            transaction = await retryFileOperation(() => (0, nexus_dev_deployment_1.beginPluginPackageDeployment)(updatedTarget.packageDirectory, this.nexusExecutable, updatedTarget.pluginId), "replace the plugin package");
+            const updateResult = await this.control.sendUpdate("packageUpdated", updatedTarget.pluginId);
+            if (!updateResult.ok) {
+                throw new dev_1.PluginDevError(updateResult.message);
             }
-            transactionCommitted = true;
-            this.restarting = false;
             try {
                 await retryFileOperation(() => transaction?.commit(), "remove the previous plugin package backup");
             }
@@ -147,24 +137,21 @@ class PluginNexusDevSession {
                 this.io.stderr("Updated plugin is active, but its previous package backup could not be removed: " + errorMessage(error));
             }
             this.target = updatedTarget;
-            this.io.stdout("Packaged Nexus restarted for plugin mainEntry update. PID: " + String(this.child?.pid || "unknown"));
+            this.io.stdout("Plugin package reloaded in a new worker; Nexus PID unchanged: " + String(this.child?.pid || "unknown"));
         }
         catch (error) {
-            if (!this.child) {
-                if (transaction && !transactionCommitted) {
-                    await retryFileOperation(() => transaction?.rollback(), "roll back the plugin package");
+            if (prepareAttempted) {
+                try {
+                    await recoverPreparedPluginPackageUpdate(transaction, previousTarget.pluginId, this.control);
+                }
+                catch (recoveryError) {
+                    throw new dev_1.PluginDevError(errorMessage(error) + " Package update recovery failed: " + errorMessage(recoveryError));
                 }
-                const previousChild = await this.launchHost(previousTarget, true);
-                await this.ensureProvisionalHostIsStable(previousChild);
-                this.acceptProvisionalHost(previousChild);
             }
             throw error;
         }
-        finally {
-            this.restarting = false;
-        }
     }
-    async launchHost(target, provisional = false) {
+    async launchHost(target) {
         const hostArgs = createNexusHostArguments(this.control, target, this.options);
         this.io.stdout("Starting packaged Nexus host: " + this.nexusExecutable);
         const child = (0, child_process_1.spawn)(this.nexusExecutable, hostArgs, {
@@ -174,13 +161,10 @@ class PluginNexusDevSession {
             windowsHide: false
         });
         this.child = child;
-        if (provisional) {
-            this.provisionalChildren.add(child);
-        }
         const hostExit = waitForHostExit(child);
         this.childExit = hostExit;
         hostExit.then((result) => this.handleHostExit(child, result), (error) => {
-            if (!this.restarting && !this.stopping) {
+            if (!this.stopping) {
                 this.io.stderr(errorMessage(error));
                 this.settleTerminal(1);
             }
@@ -205,8 +189,7 @@ class PluginNexusDevSession {
             this.child = undefined;
             this.childExit = undefined;
         }
-        const provisional = this.provisionalChildren.delete(child);
-        if (this.expectedExits.delete(child) || provisional || this.stopping) {
+        if (this.expectedExits.delete(child) || this.stopping) {
             return;
         }
         const exitCode = result.status === null ? 1 : result.status;
@@ -215,30 +198,6 @@ class PluginNexusDevSession {
             + (result.signal ? " (" + result.signal + ")" : "") + ".");
         this.settleTerminal(exitCode === 0 ? 1 : exitCode);
     }
-    async shutdownHostForRestart() {
-        const child = this.child;
-        const hostExit = this.childExit;
-        if (!child || !hostExit) {
-            throw new dev_1.PluginDevError("Packaged Nexus host is not running.");
-        }
-        this.expectedExits.add(child);
-        try {
-            await this.control.requestShutdown();
-        }
-        catch (error) {
-            this.expectedExits.delete(child);
-            throw error;
-        }
-        try {
-            await promiseWithTimeout(hostExit, 10000, "Nexus did not exit after accepting the plugin development restart.");
-        }
-        catch (error) {
-            child.kill();
-            await promiseWithTimeout(hostExit, 5000, "Nexus could not be stopped for the plugin development restart.");
-            this.io.stderr("Nexus required forced termination before plugin replacement: " + errorMessage(error));
-        }
-        await this.control.waitForDisconnection();
-    }
     async stopCurrentHost() {
         const child = this.child;
         const hostExit = this.childExit;
@@ -256,22 +215,10 @@ class PluginNexusDevSession {
                 await promiseWithTimeout(hostExit, 3000, "Nexus did not terminate after plugin development shutdown.");
             }
             catch {
-                // The CLI is already stopping; do not start another host or a restart loop.
+                // The CLI is already stopping; do not start another shutdown path.
             }
         }
     }
-    async ensureProvisionalHostIsStable(child) {
-        await new Promise((resolve) => setTimeout(resolve, 250));
-        if (this.child !== child || child.exitCode !== null || child.signalCode !== null || !this.control.isConnected()) {
-            throw new dev_1.PluginDevError("Restarted Nexus host did not remain connected after authentication.");
-        }
-    }
-    acceptProvisionalHost(child) {
-        if (this.child !== child || !this.control.isConnected()) {
-            throw new dev_1.PluginDevError("Restarted Nexus host disconnected before activation completed.");
-        }
-        this.provisionalChildren.delete(child);
-    }
     runBuild(operation) {
         return this.watcher ? this.watcher.runBuild(operation) : operation();
     }
@@ -298,6 +245,30 @@ class PluginNexusDevSession {
         this.terminalResolve = undefined;
     }
 }
+async function recoverPreparedPluginPackageUpdate(transaction, pluginId, control) {
+    const recoveryErrors = [];
+    if (transaction) {
+        try {
+            await retryFileOperation(() => transaction.rollback(), "roll back the plugin package");
+        }
+        catch (error) {
+            recoveryErrors.push("package rollback failed: " + errorMessage(error));
+        }
+    }
+    try {
+        const rollbackResult = await control.sendUpdate("packageUpdated", pluginId);
+        if (!rollbackResult.ok) {
+            recoveryErrors.push("previous worker activation failed: " + rollbackResult.message);
+        }
+    }
+    catch (error) {
+        recoveryErrors.push("previous worker activation failed: " + errorMessage(error));
+    }
+    if (recoveryErrors.length > 0) {
+        throw new dev_1.PluginDevError(recoveryErrors.join(" "));
+    }
+}
+exports.recoverPreparedPluginPackageUpdate = recoverPreparedPluginPackageUpdate;
 function classifyPluginSourceChange(projectDirectory, changedPath) {
     const relativePath = path.relative(path.resolve(projectDirectory), path.resolve(changedPath)).replace(/\\/g, "/");
     if (relativePath.startsWith("../") || relativePath === ".." || path.isAbsolute(relativePath)) {
@@ -310,7 +281,7 @@ function classifyPluginSourceChange(projectDirectory, changedPath) {
         return "renderer";
     }
     if (relativePath.toLowerCase().endsWith(".node") || relativePath === "binding.gyp") {
-        return "restart";
+        return "package";
     }
     if (relativePath.startsWith("src/")
         || relativePath.startsWith("scripts/")
@@ -318,13 +289,13 @@ function classifyPluginSourceChange(projectDirectory, changedPath) {
         || relativePath === "package-lock.json"
         || relativePath === "npm-shrinkwrap.json"
         || relativePath === "tsconfig.main.json") {
-        return "restart";
+        return "package";
     }
     return undefined;
 }
 exports.classifyPluginSourceChange = classifyPluginSourceChange;
-function manifestChangeRequiresRestart(previous, next) {
-    const restartSensitiveFields = [
+function manifestChangeRequiresPackageUpdate(previous, next) {
+    const packageSensitiveFields = [
         "schemaVersion",
         "pluginId",
         "pluginVersion",
@@ -334,17 +305,17 @@ function manifestChangeRequiresRestart(previous, next) {
         "mainEntry",
         "deferred"
     ];
-    return restartSensitiveFields.some((field) => stableJson(previous[field]) !== stableJson(next[field]));
+    return packageSensitiveFields.some((field) => stableJson(previous[field]) !== stableJson(next[field]));
 }
-exports.manifestChangeRequiresRestart = manifestChangeRequiresRestart;
+exports.manifestChangeRequiresPackageUpdate = manifestChangeRequiresPackageUpdate;
 function mergePluginSourceChange(current, incoming) {
-    const priority = { renderer: 1, manifest: 2, restart: 3 };
+    const priority = { renderer: 1, manifest: 2, package: 3 };
     return !current || priority[incoming] > priority[current] ? incoming : current;
 }
 exports.mergePluginSourceChange = mergePluginSourceChange;
-async function applyPluginSourceChange(kind, options, initialTarget, deployedPluginDirectory, control, io, restartHost, buildRenderer) {
-    if (kind === "restart") {
-        await restartHost();
+async function applyPluginSourceChange(kind, options, initialTarget, deployedPluginDirectory, control, io, updatePackage, buildRenderer) {
+    if (kind === "package") {
+        await updatePackage();
         return;
     }
     try {
@@ -363,8 +334,8 @@ async function applyPluginSourceChange(kind, options, initialTarget, deployedPlu
         const rendererDirectory = path.join(updatedTarget.packageDirectory, "renderer");
         if (kind === "manifest") {
             const previousManifest = readManifest(path.join(deployedPluginDirectory, "manifest.json"));
-            if (manifestChangeRequiresRestart(previousManifest, updatedTarget.manifest)) {
-                await restartHost();
+            if (manifestChangeRequiresPackageUpdate(previousManifest, updatedTarget.manifest)) {
+                await updatePackage();
                 return;
             }
             const transaction = (0, nexus_dev_deployment_1.beginManifestAndRendererDeployment)(path.join(updatedTarget.packageDirectory, "manifest.json"), rendererDirectory, deployedPluginDirectory);
@@ -398,13 +369,13 @@ async function finishUpdateTransaction(transaction, updateType, pluginId, contro
         throw new dev_1.PluginDevError(result.message);
     }
     transaction.commit();
-    io.stdout((updateType === "rendererUpdated" ? "Plugin renderer reloaded." : "Plugin manifest rescanned.")
-        + (result.requiresRestart ? " Existing mainEntry state will remain active until the next host restart." : ""));
+    io.stdout(updateType === "rendererUpdated" ? "Plugin renderer reloaded." : "Plugin manifest rescanned.");
 }
 function createNexusHostArguments(control, target, options) {
     const args = [];
     if (options.inspectorMode) {
-        args.push("--" + options.inspectorMode + "=" + String(options.inspectorPort || 9229));
+        args.push("--plugin-dev-worker-inspector=" + options.inspectorMode + ":" + String(options.inspectorPort || 9229));
+        args.push("--plugin-dev-worker-plugin=" + target.pluginId);
     }
     args.push("--plugin-dev", "--plugin-dev-control=" + control.pipePath, "--plugin-dev-token=" + control.token, "--page=" + resolveContributionPage(target));
     if (target.surface !== "business") {

package/dist/src/types.d.ts

@@ -95,6 +95,7 @@ export interface BusinessLogAppendRequest {
     category?: string;
     exception?: string;
 }
+export type PluginHostLogLevel = Exclude<BusinessLogEntry["level"], "debug">;
 export interface PluginRendererOperationRequest<TInput extends Record<string, unknown> = Record<string, unknown>> {
     readonly pluginId: string;
     readonly surface: PluginRendererSurface;
@@ -102,12 +103,12 @@ export interface PluginRendererOperationRequest<TInput extends Record<string, un
     readonly operation: string;
     readonly input?: TInput;
 }
-export type PluginRendererOperationHandler<TInput extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = (request: PluginRendererOperationRequest<TInput>) => NexusResult<TResult> | TResult;
+export type PluginRendererOperationHandler<TInput extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = (request: PluginRendererOperationRequest<TInput>) => NexusResult<TResult> | TResult | Promise<NexusResult<TResult> | TResult>;
 export interface PluginUnsupportedCapabilityApi {
     readonly permission: PluginPermission;
     readonly supportState: PluginPermissionSupportState;
-    describe(): NexusResult<PluginPermissionSummary>;
-    unsupported(operation?: unknown): NexusResult<never>;
+    describe(): Promise<NexusResult<PluginPermissionSummary>>;
+    unsupported(operation?: unknown): Promise<NexusResult<never>>;
     [operation: string]: unknown;
 }
 export interface PluginHostApi {
@@ -116,12 +117,12 @@ export interface PluginHostApi {
     readonly pluginId: string;
     readonly pluginDataDirectory: string;
     hasPermission(permission: PluginPermission): boolean;
-    registerRendererMethod(name: string, handler: PluginRendererOperationHandler): NexusResult<boolean>;
-    getCapabilityStatus(permission: unknown): NexusResult<PluginPermissionSummary>;
-    unsupportedCapability(permission: unknown, operation?: unknown): NexusResult<never>;
-    log(level: BusinessLogEntry["level"], message: string, exception?: string): NexusResult<BusinessLogEntry>;
-    getSettings(): NexusResult<PluginSettingsDocument>;
-    updateSettings(values: Record<string, unknown>): NexusResult<PluginSettingsDocument>;
+    registerRendererMethod(name: string, handler: PluginRendererOperationHandler): Promise<NexusResult<boolean>>;
+    getCapabilityStatus(permission: unknown): Promise<NexusResult<PluginPermissionSummary>>;
+    unsupportedCapability(permission: unknown, operation?: unknown): Promise<NexusResult<never>>;
+    log(level: PluginHostLogLevel, message: string, exception?: string): Promise<NexusResult<BusinessLogEntry>>;
+    getSettings(): Promise<NexusResult<PluginSettingsDocument>>;
+    updateSettings(values: Record<string, unknown>): Promise<NexusResult<PluginSettingsDocument>>;
     filesystem: PluginUnsupportedCapabilityApi;
     udp: PluginUnsupportedCapabilityApi;
     serial: PluginUnsupportedCapabilityApi;
@@ -136,7 +137,9 @@ export interface PluginMainActivationContext {
 }
 export interface PluginMainModule {
     activate?: (context: PluginMainActivationContext) => unknown;
+    deactivate?: (reason: string) => unknown;
     default?: {
         activate?: (context: PluginMainActivationContext) => unknown;
+        deactivate?: (reason: string) => unknown;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiot-nexus/plugin-sdk",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "description": "Types, PluginFrame client, and CLI for AIoT Nexus independent plugins.",
   "license": "UNLICENSED",
   "publishConfig": {

package/templates/minimal/.vscode/launch.json

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

package/templates/minimal/README.md.tmpl

@@ -15,20 +15,20 @@ SDK checks for a newer `@aiot-nexus/plugin-sdk` in two steps. The package `posti
 
 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 deployable plugin package is `dist/__PLUGIN_ID__/`. Copy that directory to the Nexus executable's `Plugins/__PLUGIN_ID__/` directory, then restart Nexus.
+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 renderer calls the main-process `demo.echo` operation through `@aiot-nexus/plugin-sdk`. Run `npm run validate` after changing the manifest or output layout.
+The renderer calls the plugin-worker `demo.echo` operation through `@aiot-nexus/plugin-sdk`. 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. Add or edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
 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` 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 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 restart-sensitive manifest changes rebuild the full package and restart Nexus. Failed builds keep the previous deployment, and a failed restarted host rolls back the package. 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 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.
 
 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 main-process 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 main (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 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.
 
 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,7 +1,7 @@
 import type { PluginMainActivationContext } from "@aiot-nexus/plugin-sdk";
 
-export function activate(context: PluginMainActivationContext): void {
-  const registration = context.host.registerRendererMethod("demo.echo", (request) => {
+export async function activate(context: PluginMainActivationContext): Promise<void> {
+  const registration = await context.host.registerRendererMethod("demo.echo", (request) => {
     const value = request.input && typeof request.input.value === "string"
       ? request.input.value.trim()
       : "";
@@ -19,5 +19,8 @@ export function activate(context: PluginMainActivationContext): void {
   if (!registration.ok) {
     throw new Error(registration.error.message);
   }
-  context.host.log("info", "__PLUGIN_ID__ activated.");
+  const logResult = await context.host.log("info", "__PLUGIN_ID__ activated.");
+  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 main (9229)",
+      "name": "Attach Nexus plugin worker (9229)",
       "type": "node",
       "request": "attach",
       "address": "127.0.0.1",

package/templates/sqlite/README.md.tmpl

@@ -17,18 +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__/`. Copy that directory to the Nexus executable's `Plugins/__PLUGIN_ID__/` directory, then restart Nexus. 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 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 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. Static labels, CRUD status messages, action buttons, validation text, and date formatting switch together. Edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
 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`, 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. Database operations report unsupported; use `npm run dev` for SQLite and Host API integration. 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 restart-sensitive manifest changes run the complete build (including the Electron 22.3.27 native rebuild) before restarting Nexus. The database remains under the host-provided plugin data directory across restarts. Failed builds keep the previous deployment, and a failed restarted host rolls back the package. 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 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.
 
 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 main-process 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 main (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 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.
 
 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/better-sqlite3.d.ts

@@ -1,6 +1,7 @@
 declare module "better-sqlite3" {
   class Database {
     constructor(filename: string);
+    close(): void;
     pragma(source: string): unknown;
     prepare(source: string): Database.Statement;
   }

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

@@ -19,7 +19,7 @@ let database: Database | undefined;
 let databasePath = "";
 let databaseCreated = false;
 
-export function activate(context: PluginMainActivationContext): void {
+export async function activate(context: PluginMainActivationContext): Promise<void> {
   const fs = require("fs") as typeof import("fs");
   const path = require("path") as typeof import("path");
   fs.mkdirSync(context.host.pluginDataDirectory, { recursive: true });
@@ -36,16 +36,24 @@ export function activate(context: PluginMainActivationContext): void {
     ")"
   ).run();
 
-  register(context, "sqlite.getInfo", getInfo);
-  register(context, "sqlite.listRecords", listRecords);
-  register(context, "sqlite.insertRecord", insertRecord);
-  register(context, "sqlite.updateRecord", updateRecord);
-  register(context, "sqlite.deleteRecord", deleteRecord);
-  context.host.log("info", "__PLUGIN_ID__ database " + (databaseCreated ? "created" : "loaded") + ": " + databasePath);
+  await register(context, "sqlite.getInfo", getInfo);
+  await register(context, "sqlite.listRecords", listRecords);
+  await register(context, "sqlite.insertRecord", insertRecord);
+  await register(context, "sqlite.updateRecord", updateRecord);
+  await register(context, "sqlite.deleteRecord", deleteRecord);
+  const logResult = await context.host.log("info", "__PLUGIN_ID__ database " + (databaseCreated ? "created" : "loaded") + ": " + databasePath);
+  if (!logResult.ok) {
+    throw new Error(logResult.error.message);
+  }
+}
+
+export function deactivate(): void {
+  database?.close();
+  database = undefined;
 }
 
-function register(context: PluginMainActivationContext, name: string, handler: PluginRendererOperationHandler): void {
-  const result = context.host.registerRendererMethod(name, handler);
+async function register(context: PluginMainActivationContext, name: string, handler: PluginRendererOperationHandler): Promise<void> {
+  const result = await context.host.registerRendererMethod(name, handler);
   if (!result.ok) {
     throw new Error(result.error.message);
   }