@aiot-nexus/plugin-sdk 2.1.1 → 3.0.2

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.manifestChangeRequiresPackageUpdate = exports.classifyPluginSourceChange = exports.recoverPreparedPluginPackageUpdate = exports.runPluginNexusDev = void 0;
+exports.shouldSuppressNativeBuildEvent = exports.isRetryablePluginDeploymentError = exports.createNexusHostArguments = exports.mergePluginSourceChange = exports.manifestChangeRequiresPackageUpdate = exports.classifyPluginSourceChange = exports.runPluginNexusDev = void 0;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -43,6 +43,7 @@ class PluginNexusDevSession {
         this.deployedPluginDirectory = "";
         this.expectedExits = new Set();
         this.stopping = false;
+        this.restartingHost = false;
         this.terminalSettled = false;
         this.terminalPromise = new Promise((resolve) => {
             this.terminalResolve = resolve;
@@ -54,9 +55,16 @@ class PluginNexusDevSession {
             this.stopping = true;
             this.watcher?.close();
             void (async () => {
+                let exitCode = 0;
+                try {
+                    await this.stopCurrentHost(true);
+                }
+                catch (error) {
+                    exitCode = 1;
+                    this.io.stderr(errorMessage(error));
+                }
                 await this.watcher?.drain();
-                await this.stopCurrentHost();
-                this.settleTerminal(0);
+                this.settleTerminal(exitCode);
             })();
         };
         this.projectDirectory = path.resolve(options.projectDirectory);
@@ -67,7 +75,6 @@ class PluginNexusDevSession {
         (0, dev_1.buildPluginForDevelopment)(this.projectDirectory);
         const target = (0, dev_1.preparePluginDebugTarget)({ ...this.options, projectDirectory: this.projectDirectory });
         const deployment = (0, nexus_dev_deployment_1.beginPluginPackageDeployment)(target.packageDirectory, this.nexusExecutable, target.pluginId);
-        deployment.commit();
         this.target = target;
         this.deployedPluginDirectory = path.join(path.dirname(this.nexusExecutable), "Plugins", target.pluginId);
         this.io.stdout("Deployed plugin package: " + this.deployedPluginDirectory
@@ -75,13 +82,14 @@ class PluginNexusDevSession {
         try {
             await this.control.start();
             this.disposeDisconnectHandler = this.control.setDisconnectHandler((error) => {
-                if (!this.stopping) {
+                if (!this.stopping && !this.restartingHost) {
                     this.io.stderr("Packaged Nexus plugin development control disconnected: " + error.message);
                     this.settleTerminal(1);
                 }
             });
             this.installSignalHandlers();
             await this.launchHost(target);
+            deployment.commit();
             if (this.stopping) {
                 return await this.terminalPromise;
             }
@@ -93,6 +101,26 @@ class PluginNexusDevSession {
             this.io.stdout("Watching plugin source changes. Press Ctrl+C to stop.");
             return await this.terminalPromise;
         }
+        catch (error) {
+            this.stopping = true;
+            const recoveryErrors = [];
+            try {
+                await this.stopCurrentHost(true);
+            }
+            catch (stopError) {
+                recoveryErrors.push("host shutdown failed: " + errorMessage(stopError));
+            }
+            try {
+                await retryFileOperation(() => deployment.rollback(), "roll back the initial plugin deployment");
+            }
+            catch (rollbackError) {
+                recoveryErrors.push("deployment rollback failed: " + errorMessage(rollbackError));
+            }
+            if (recoveryErrors.length > 0) {
+                throw new dev_1.PluginDevError(errorMessage(error) + " Initial deployment recovery failed: " + recoveryErrors.join(" "));
+            }
+            throw error;
+        }
         finally {
             this.stopping = true;
             this.watcher?.close();
@@ -106,7 +134,7 @@ class PluginNexusDevSession {
     }
     async updatePluginPackage() {
         const previousTarget = this.requireTarget();
-        this.io.stdout("Building complete plugin package before restarting the plugin worker...");
+        this.io.stdout("Building complete plugin package before restarting Nexus...");
         this.runBuild(() => (0, dev_1.buildPluginForDevelopment)(this.projectDirectory));
         const updatedTarget = (0, dev_1.preparePluginDebugTarget)({
             projectDirectory: this.projectDirectory,
@@ -119,18 +147,19 @@ class PluginNexusDevSession {
             throw new dev_1.PluginDevError("Plugin id cannot change during a Nexus development session.");
         }
         let transaction;
-        let prepareAttempted = false;
+        this.restartingHost = true;
         try {
-            prepareAttempted = true;
-            const prepareResult = await this.control.sendUpdate("packageUpdatePreparing", previousTarget.pluginId);
-            if (!prepareResult.ok) {
-                throw new dev_1.PluginDevError(prepareResult.message);
+            await this.stopCurrentHost(true);
+            if (this.stopping) {
+                return;
             }
             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);
+            if (this.stopping) {
+                await retryFileOperation(() => transaction?.rollback(), "roll back the plugin package after shutdown");
+                transaction = undefined;
+                return;
             }
+            await this.launchHost(updatedTarget);
             try {
                 await retryFileOperation(() => transaction?.commit(), "remove the previous plugin package backup");
             }
@@ -138,18 +167,48 @@ 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("Plugin package reloaded in a new worker; Nexus PID unchanged: " + String(this.child?.pid || "unknown"));
+            this.io.stdout("Plugin package loaded after Nexus restart. New PID: " + String(this.child?.pid || "unknown"));
         }
         catch (error) {
-            if (prepareAttempted) {
+            const recoveryErrors = [];
+            try {
+                await this.stopCurrentHost(true);
+            }
+            catch (stopError) {
+                recoveryErrors.push("updated host shutdown failed: " + errorMessage(stopError));
+            }
+            if (transaction) {
                 try {
-                    await recoverPreparedPluginPackageUpdate(transaction, previousTarget.pluginId, this.control);
+                    await retryFileOperation(() => transaction?.rollback(), "roll back the plugin package");
                 }
-                catch (recoveryError) {
-                    throw new dev_1.PluginDevError(errorMessage(error) + " Package update recovery failed: " + errorMessage(recoveryError));
+                catch (rollbackError) {
+                    recoveryErrors.push("package rollback failed: " + errorMessage(rollbackError));
                 }
             }
-            throw error;
+            if (this.stopping && recoveryErrors.length === 0) {
+                return;
+            }
+            if (!this.stopping && recoveryErrors.length === 0) {
+                try {
+                    await this.launchHost(previousTarget);
+                }
+                catch (launchError) {
+                    recoveryErrors.push("previous Nexus host restart failed: " + errorMessage(launchError));
+                    try {
+                        await this.stopCurrentHost(true);
+                    }
+                    catch (stopError) {
+                        recoveryErrors.push("failed recovery host shutdown failed: " + errorMessage(stopError));
+                    }
+                }
+            }
+            if (recoveryErrors.length > 0) {
+                throw new dev_1.PluginDevError(errorMessage(error) + " Package update recovery failed: " + recoveryErrors.join(" "));
+            }
+            throw new dev_1.PluginDevError(errorMessage(error) + " The previous plugin package was restored and Nexus was restarted.");
+        }
+        finally {
+            this.restartingHost = false;
         }
     }
     async launchHost(target) {
@@ -165,7 +224,12 @@ class PluginNexusDevSession {
         const hostExit = waitForHostExit(child);
         this.childExit = hostExit;
         hostExit.then((result) => this.handleHostExit(child, result), (error) => {
-            if (!this.stopping) {
+            if (this.child === child) {
+                this.child = undefined;
+                this.childExit = undefined;
+            }
+            this.expectedExits.delete(child);
+            if (!this.stopping && !this.restartingHost) {
                 this.io.stderr(errorMessage(error));
                 this.settleTerminal(1);
             }
@@ -180,7 +244,14 @@ class PluginNexusDevSession {
             })
         ]);
         if (this.stopping) {
-            return child;
+            throw new dev_1.PluginDevError("Packaged Nexus startup was cancelled because plugin development is stopping.");
+        }
+        if (child.exitCode !== null || this.child !== child) {
+            throw new dev_1.PluginDevError(formatEarlyHostExit({ status: child.exitCode, signal: child.signalCode }));
+        }
+        const readyResult = await this.control.sendUpdate("hostReady", target.pluginId);
+        if (!readyResult.ok) {
+            throw new dev_1.PluginDevError("Packaged Nexus started, but the target plugin is not ready: " + readyResult.message);
         }
         this.io.stdout("Packaged Nexus plugin development control connected. PID: " + String(child.pid || "unknown"));
         return child;
@@ -190,7 +261,7 @@ class PluginNexusDevSession {
             this.child = undefined;
             this.childExit = undefined;
         }
-        if (this.expectedExits.delete(child) || this.stopping) {
+        if (this.expectedExits.delete(child) || this.stopping || this.restartingHost) {
             return;
         }
         const exitCode = result.status === null ? 1 : result.status;
@@ -199,25 +270,41 @@ class PluginNexusDevSession {
             + (result.signal ? " (" + result.signal + ")" : "") + ".");
         this.settleTerminal(exitCode === 0 ? 1 : exitCode);
     }
-    async stopCurrentHost() {
+    async stopCurrentHost(requireTermination = false) {
         const child = this.child;
         const hostExit = this.childExit;
         if (!child || !hostExit) {
             return;
         }
         this.expectedExits.add(child);
+        let gracefulFailure;
         try {
             await this.control.requestShutdown();
             await promiseWithTimeout(hostExit, 5000, "Nexus did not exit during plugin development shutdown.");
         }
-        catch {
+        catch (error) {
+            gracefulFailure = error;
             child.kill();
             try {
                 await promiseWithTimeout(hostExit, 3000, "Nexus did not terminate after plugin development shutdown.");
             }
-            catch {
-                // The CLI is already stopping; do not start another shutdown path.
+            catch (terminationError) {
+                this.expectedExits.delete(child);
+                if (requireTermination) {
+                    throw new dev_1.PluginDevError(errorMessage(terminationError) + " Graceful shutdown also failed: " + errorMessage(gracefulFailure));
+                }
+                this.io.stderr(errorMessage(terminationError));
+                return;
+            }
+        }
+        try {
+            await this.control.waitForDisconnection(3000);
+        }
+        catch (error) {
+            if (requireTermination) {
+                throw error;
             }
+            this.io.stderr(errorMessage(error));
         }
     }
     runBuild(operation) {
@@ -246,30 +333,6 @@ 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)) {
@@ -296,6 +359,9 @@ function classifyPluginSourceChange(projectDirectory, changedPath) {
 }
 exports.classifyPluginSourceChange = classifyPluginSourceChange;
 function manifestChangeRequiresPackageUpdate(previous, next) {
+    if (previous.mainEntry || next.mainEntry) {
+        return stableJson(previous) !== stableJson(next);
+    }
     const packageSensitiveFields = [
         "schemaVersion",
         "pluginId",
@@ -375,8 +441,7 @@ async function finishUpdateTransaction(transaction, updateType, pluginId, contro
 function createNexusHostArguments(control, target, options) {
     const args = [];
     if (options.inspectorMode) {
-        args.push("--plugin-dev-worker-inspector=" + options.inspectorMode + ":" + String(options.inspectorPort || 9229));
-        args.push("--plugin-dev-worker-plugin=" + target.pluginId);
+        args.push("--" + options.inspectorMode + "=" + String(options.inspectorPort || 9229));
     }
     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

@@ -1,5 +1,3 @@
-/// <reference types="node" />
-/// <reference types="node" />
 export interface NexusError {
     code: string;
     message: string;
@@ -14,8 +12,8 @@ export type NexusResult<T> = {
 };
 export type ThemeMode = "light" | "dark" | "system";
 export type LaunchPageParams = Record<string, string>;
-export type PluginPermission = "businessLog" | "settings" | "filesystem" | "udp" | "serial" | "externalProcess" | "dialog" | "electronHostControl";
-export type PluginPermissionSupportState = "implemented" | "hostControl" | "routeGuard" | "reserved";
+export type PluginPermission = "businessLog" | "settings" | "filesystem" | "udp" | "serial" | "externalProcess" | "dialog";
+export type PluginPermissionSupportState = "implemented" | "routeGuard" | "reserved";
 export interface PluginPermissionSummary {
     permission: PluginPermission;
     supportState: PluginPermissionSupportState;
@@ -109,103 +107,22 @@ export type PluginRendererOperationHandler<TInput extends Record<string, unknown
 export interface PluginUnsupportedCapabilityApi {
     readonly permission: PluginPermission;
     readonly supportState: PluginPermissionSupportState;
-    describe(): Promise<NexusResult<PluginPermissionSummary>>;
-    unsupported(operation?: unknown): Promise<NexusResult<never>>;
+    describe(): NexusResult<PluginPermissionSummary>;
+    unsupported(operation?: unknown): NexusResult<never>;
     [operation: string]: unknown;
 }
-type ElectronExports = typeof import("electron");
-type PluginElectronFacadeScalar = string | number | boolean | bigint | null | undefined | Date | Buffer | Error;
-type PluginElectronFacadeRemoteObject = import("electron").BrowserView | import("electron").BrowserWindow | import("electron").ClientRequest | import("electron").CommandLine | import("electron").Cookies | import("electron").Debugger | import("electron").DownloadItem | import("electron").Dock | import("electron").Event | import("electron").IncomingMessage | import("electron").IpcMainEvent | import("electron").IpcMainInvokeEvent | import("electron").Menu | import("electron").MenuItem | import("electron").MessageChannelMain | import("electron").MessagePortMain | import("electron").NativeImage | import("electron").Notification | import("electron").Session | import("electron").ServiceWorkers | import("electron").ShareMenu | import("electron").TouchBar | import("electron").TouchBarButton | import("electron").TouchBarColorPicker | import("electron").TouchBarGroup | import("electron").TouchBarLabel | import("electron").TouchBarOtherItemsProxy | import("electron").TouchBarPopover | import("electron").TouchBarScrubber | import("electron").TouchBarSegmentedControl | import("electron").TouchBarSlider | import("electron").TouchBarSpacer | import("electron").Tray | import("electron").UtilityProcess | import("electron").WebContents | import("electron").WebFrameMain | import("electron").WebRequest;
-type PluginElectronFacadeArguments<T extends readonly unknown[]> = {
-    [K in keyof T]: PluginElectronFacadeArgument<T[K]>;
-};
-type PluginElectronFacadeArgument<T> = T extends PluginElectronFacadeScalar ? T : T extends PluginElectronFacadeRemoteObject ? PluginElectronFacadeModule<T> : T extends (...args: infer TArgs) => infer TResult ? (...args: PluginElectronFacadeArguments<TArgs>) => PluginElectronFacadeValue<TResult> | Promise<PluginElectronFacadeValue<TResult>> : T extends readonly unknown[] ? PluginElectronFacadeArguments<T> : T extends object ? {
-    [K in keyof T]: PluginElectronFacadeArgument<T[K]>;
-} : T;
-type PluginElectronFacadeValue<T> = T extends PromiseLike<infer TValue> ? PluginElectronFacadeValue<TValue> : T extends PluginElectronFacadeScalar ? T : T extends PluginElectronFacadeRemoteObject ? PluginElectronFacadeModule<T> : T extends readonly unknown[] ? {
-    [K in keyof T]: PluginElectronFacadeValue<T[K]>;
-} : T extends object ? {
-    readonly [K in keyof T]: PluginElectronFacadeValue<T[K]>;
-} : T;
-type PluginElectronFacadeAsyncMembers<T> = {
-    readonly [K in keyof T as T[K] extends (...args: never[]) => unknown ? K : never]: T[K] extends (...args: infer TArgs) => infer TResult ? (...args: PluginElectronFacadeArguments<TArgs>) => Promise<PluginElectronFacadeValue<TResult>> : never;
-};
-type PluginElectronFacadeConstructed<T> = T extends abstract new (...args: never[]) => infer TInstance ? TInstance : Record<string, unknown>;
-type PluginElectronFacadeConstructorArguments<T> = T extends abstract new (...args: infer TArgs) => unknown ? PluginElectronFacadeArguments<TArgs> : unknown[];
-export type PluginElectronFacadeMethod<TArgs extends readonly unknown[] = unknown[], TResult = unknown> = (...args: PluginElectronFacadeArguments<TArgs>) => Promise<PluginElectronFacadeValue<TResult>>;
-export interface PluginElectronFacadeSubscription {
-    readonly $typeName?: "ElectronEventSubscription" | string;
-    $release(): Promise<void>;
-}
-export interface PluginElectronFacadeEventSnapshot {
-    readonly defaultPrevented: boolean;
-    readonly preventDefaultSupported: false;
-    readonly senderId?: number | string;
-}
-export type PluginElectronFacadeModule<TModule = Record<string, unknown>> = PluginElectronFacadeAsyncMembers<TModule> & {
-    readonly $typeName?: string;
-    $construct(...args: PluginElectronFacadeConstructorArguments<TModule>): Promise<PluginElectronFacadeModule<PluginElectronFacadeConstructed<TModule>>>;
-    $get<TKey extends keyof TModule>(member: TKey): Promise<PluginElectronFacadeValue<TModule[TKey]>>;
-    $get(member: string): Promise<unknown>;
-    $set<TKey extends keyof TModule>(member: TKey, value: PluginElectronFacadeArgument<TModule[TKey]>): Promise<void>;
-    $set(member: string, value: unknown): Promise<void>;
-    $on(event: string, listener: (...args: unknown[]) => unknown): Promise<PluginElectronFacadeSubscription>;
-    $once(event: string, listener: (...args: unknown[]) => unknown): Promise<PluginElectronFacadeSubscription>;
-    $release(): Promise<void>;
-};
-export interface PluginElectronFacade {
-    readonly app: PluginElectronFacadeModule<ElectronExports["app"]>;
-    readonly autoUpdater: PluginElectronFacadeModule<ElectronExports["autoUpdater"]>;
-    readonly BrowserView: PluginElectronFacadeModule<ElectronExports["BrowserView"]>;
-    readonly BrowserWindow: PluginElectronFacadeModule<ElectronExports["BrowserWindow"]>;
-    readonly clipboard: PluginElectronFacadeModule<ElectronExports["clipboard"]>;
-    readonly contentTracing: PluginElectronFacadeModule<ElectronExports["contentTracing"]>;
-    readonly contextBridge: PluginElectronFacadeModule<ElectronExports["contextBridge"]>;
-    readonly crashReporter: PluginElectronFacadeModule<ElectronExports["crashReporter"]>;
-    readonly desktopCapturer: PluginElectronFacadeModule<ElectronExports["desktopCapturer"]>;
-    readonly dialog: PluginElectronFacadeModule<ElectronExports["dialog"]>;
-    readonly globalShortcut: PluginElectronFacadeModule<ElectronExports["globalShortcut"]>;
-    readonly inAppPurchase: PluginElectronFacadeModule<ElectronExports["inAppPurchase"]>;
-    readonly ipcMain: PluginElectronFacadeModule<ElectronExports["ipcMain"]>;
-    readonly ipcRenderer: PluginElectronFacadeModule<ElectronExports["ipcRenderer"]>;
-    readonly Menu: PluginElectronFacadeModule<ElectronExports["Menu"]>;
-    readonly MenuItem: PluginElectronFacadeModule<ElectronExports["MenuItem"]>;
-    readonly MessageChannelMain: PluginElectronFacadeModule<ElectronExports["MessageChannelMain"]>;
-    readonly nativeImage: PluginElectronFacadeModule<ElectronExports["nativeImage"]>;
-    readonly nativeTheme: PluginElectronFacadeModule<ElectronExports["nativeTheme"]>;
-    readonly net: PluginElectronFacadeModule<ElectronExports["net"]>;
-    readonly netLog: PluginElectronFacadeModule<ElectronExports["netLog"]>;
-    readonly Notification: PluginElectronFacadeModule<ElectronExports["Notification"]>;
-    readonly powerMonitor: PluginElectronFacadeModule<ElectronExports["powerMonitor"]>;
-    readonly powerSaveBlocker: PluginElectronFacadeModule<ElectronExports["powerSaveBlocker"]>;
-    readonly protocol: PluginElectronFacadeModule<ElectronExports["protocol"]>;
-    readonly pushNotifications: PluginElectronFacadeModule<ElectronExports["pushNotifications"]>;
-    readonly safeStorage: PluginElectronFacadeModule<ElectronExports["safeStorage"]>;
-    readonly screen: PluginElectronFacadeModule<ElectronExports["screen"]>;
-    readonly session: PluginElectronFacadeModule<ElectronExports["session"]>;
-    readonly ShareMenu: PluginElectronFacadeModule<ElectronExports["ShareMenu"]>;
-    readonly shell: PluginElectronFacadeModule<ElectronExports["shell"]>;
-    readonly systemPreferences: PluginElectronFacadeModule<ElectronExports["systemPreferences"]>;
-    readonly TouchBar: PluginElectronFacadeModule<ElectronExports["TouchBar"]>;
-    readonly Tray: PluginElectronFacadeModule<ElectronExports["Tray"]>;
-    readonly utilityProcess: PluginElectronFacadeModule<ElectronExports["utilityProcess"]>;
-    readonly webContents: PluginElectronFacadeModule<ElectronExports["webContents"]>;
-    readonly webFrame: PluginElectronFacadeModule<ElectronExports["webFrame"]>;
-    readonly webFrameMain: PluginElectronFacadeModule<ElectronExports["webFrameMain"]>;
-}
 export interface PluginHostApi {
     readonly hostVersion: string;
     readonly hostApiVersion: string;
     readonly pluginId: string;
     readonly pluginDataDirectory: string;
     hasPermission(permission: PluginPermission): boolean;
-    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>>;
-    readonly electron: PluginElectronFacade;
+    registerRendererMethod(name: string, handler: PluginRendererOperationHandler): NexusResult<boolean>;
+    getCapabilityStatus(permission: unknown): NexusResult<PluginPermissionSummary>;
+    unsupportedCapability(permission: unknown, operation?: unknown): NexusResult<never>;
+    log(level: PluginHostLogLevel, message: string, exception?: string): NexusResult<BusinessLogEntry>;
+    getSettings(): NexusResult<PluginSettingsDocument>;
+    updateSettings(values: Record<string, unknown>): NexusResult<PluginSettingsDocument>;
     filesystem: PluginUnsupportedCapabilityApi;
     udp: PluginUnsupportedCapabilityApi;
     serial: PluginUnsupportedCapabilityApi;
@@ -219,11 +136,10 @@ export interface PluginMainActivationContext {
     readonly host: PluginHostApi;
 }
 export interface PluginMainModule {
-    activate?: (context: PluginMainActivationContext) => unknown;
-    deactivate?: (reason: string) => unknown;
+    activate?: (context: PluginMainActivationContext) => void;
+    deactivate?: (reason: "reload" | "disable" | "quit") => void;
     default?: {
-        activate?: (context: PluginMainActivationContext) => unknown;
-        deactivate?: (reason: string) => unknown;
+        activate?: (context: PluginMainActivationContext) => void;
+        deactivate?: (reason: "reload" | "disable" | "quit") => void;
     };
 }
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiot-nexus/plugin-sdk",
-  "version": "2.1.1",
+  "version": "3.0.2",
   "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 worker (9229)",
+      "name": "Attach Nexus plugin main process (9229)",
       "type": "node",
       "request": "attach",
       "address": "127.0.0.1",

package/templates/minimal/README.md.tmpl

@@ -15,22 +15,23 @@ 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__/`. 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.
 
 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. `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",