@aiot-nexus/plugin-sdk 2.1.1 → 3.1.0

package/dist/src/nexus-dev-control.js

@@ -30,7 +30,7 @@ const net = __importStar(require("net"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const dev_1 = require("./dev");
-const protocolVersion = 2;
+const protocolVersion = 3;
 const maximumMessageBytes = 64 * 1024;
 const requestTimeoutMs = 10000;
 class NexusDevControlServer {
@@ -371,7 +371,7 @@ function isUpdateResult(value) {
     return isRecord(value)
         && value.type === "updateResult"
         && typeof value.requestId === "string"
-        && (value.updateType === "rendererUpdated" || value.updateType === "manifestUpdated" || value.updateType === "packageUpdatePreparing" || value.updateType === "packageUpdated")
+        && (value.updateType === "hostReady" || value.updateType === "rendererUpdated" || value.updateType === "manifestUpdated")
         && typeof value.pluginId === "string"
         && typeof value.ok === "boolean"
         && typeof value.message === "string"

package/dist/src/nexus-dev.d.ts

@@ -13,9 +13,6 @@ export interface PluginNexusDevIo {
 }
 export type PluginSourceChangeKind = "renderer" | "manifest" | "package";
 export declare function runPluginNexusDev(options: PluginNexusDevOptions, io: PluginNexusDevIo): Promise<number>;
-export declare function recoverPreparedPluginPackageUpdate(transaction: {
-    rollback(): void;
-} | undefined, pluginId: string, control: Pick<NexusDevControlServer, "sendUpdate">): Promise<void>;
 export declare function classifyPluginSourceChange(projectDirectory: string, changedPath: string): PluginSourceChangeKind | undefined;
 export declare function manifestChangeRequiresPackageUpdate(previous: PluginManifest, next: PluginManifest): boolean;
 export declare function mergePluginSourceChange(current: PluginSourceChangeKind | undefined, incoming: PluginSourceChangeKind): PluginSourceChangeKind;

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/scaffold.js

@@ -29,6 +29,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const url_1 = require("url");
 const index_1 = require("./index");
+const sdk_info_1 = require("./sdk-info");
 class PluginScaffoldError extends Error {
     constructor(message, exitCode) {
         super(message);
@@ -209,9 +210,9 @@ function createPackageJson(options, sdkSource) {
     };
     const devDependencies = {
         [sdkPackageName]: sdkSource,
-        "@types/node": "16.18.126",
-        electron: "22.3.27",
-        typescript: "4.9.4"
+        "@types/node": sdk_info_1.PLUGIN_SDK_TYPES_NODE_VERSION,
+        electron: sdk_info_1.PLUGIN_SDK_ELECTRON_VERSION,
+        typescript: sdk_info_1.PLUGIN_SDK_TYPESCRIPT_VERSION
     };
     const packageJson = {
         name: options.pluginId,
@@ -222,12 +223,12 @@ function createPackageJson(options, sdkSource) {
     };
     if (options.template === "sqlite") {
         scripts.build = "npm run rebuild:native && node scripts/build.js && npm run validate";
-        scripts["rebuild:native"] = "electron-rebuild -v 22.3.27 -m . -w better-sqlite3";
+        scripts["rebuild:native"] = "electron-rebuild -v " + sdk_info_1.PLUGIN_SDK_ELECTRON_VERSION + " -m . -w better-sqlite3";
         packageJson.dependencies = { "better-sqlite3": "8.7.0" };
         devDependencies["@electron/rebuild"] = "3.7.2";
     }
     packageJson.devDependencies = devDependencies;
-    packageJson.engines = { node: ">=16.20.0 <17" };
+    packageJson.engines = { node: sdk_info_1.PLUGIN_SDK_NODE_ENGINE };
     return packageJson;
 }
 function createManifest(options) {

package/dist/src/sdk-info.d.ts

@@ -0,0 +1,17 @@
+export declare const PLUGIN_SDK_VERSION = "3.1.0";
+export declare const PLUGIN_SDK_NODE_ENGINE = ">=16.20.0 <17";
+export declare const PLUGIN_SDK_NPM_ENGINE = ">=6.13.4";
+export declare const PLUGIN_SDK_ELECTRON_VERSION = "22.3.27";
+export declare const PLUGIN_SDK_TYPESCRIPT_VERSION = "4.9.4";
+export declare const PLUGIN_SDK_TYPES_NODE_VERSION = "16.18.126";
+export interface PluginSdkInfo {
+    sdkVersion: string;
+    frameworkApiVersion: string;
+    manifestSchemaVersion: number;
+    nodeEngine: string;
+    npmEngine: string;
+    electronVersion: string;
+    typescriptVersion: string;
+    typesNodeVersion: string;
+}
+export declare function getPluginSdkInfo(): PluginSdkInfo;

package/dist/src/sdk-info.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPluginSdkInfo = exports.PLUGIN_SDK_TYPES_NODE_VERSION = exports.PLUGIN_SDK_TYPESCRIPT_VERSION = exports.PLUGIN_SDK_ELECTRON_VERSION = exports.PLUGIN_SDK_NPM_ENGINE = exports.PLUGIN_SDK_NODE_ENGINE = exports.PLUGIN_SDK_VERSION = void 0;
+const plugin_framework_version_1 = require("../.generated/plugin-framework-version");
+exports.PLUGIN_SDK_VERSION = "3.1.0";
+exports.PLUGIN_SDK_NODE_ENGINE = ">=16.20.0 <17";
+exports.PLUGIN_SDK_NPM_ENGINE = ">=6.13.4";
+exports.PLUGIN_SDK_ELECTRON_VERSION = "22.3.27";
+exports.PLUGIN_SDK_TYPESCRIPT_VERSION = "4.9.4";
+exports.PLUGIN_SDK_TYPES_NODE_VERSION = "16.18.126";
+function getPluginSdkInfo() {
+    return {
+        sdkVersion: exports.PLUGIN_SDK_VERSION,
+        frameworkApiVersion: plugin_framework_version_1.PLUGIN_FRAMEWORK_VERSION,
+        manifestSchemaVersion: plugin_framework_version_1.PLUGIN_MANIFEST_SCHEMA_VERSION,
+        nodeEngine: exports.PLUGIN_SDK_NODE_ENGINE,
+        npmEngine: exports.PLUGIN_SDK_NPM_ENGINE,
+        electronVersion: exports.PLUGIN_SDK_ELECTRON_VERSION,
+        typescriptVersion: exports.PLUGIN_SDK_TYPESCRIPT_VERSION,
+        typesNodeVersion: exports.PLUGIN_SDK_TYPES_NODE_VERSION
+    };
+}
+exports.getPluginSdkInfo = getPluginSdkInfo;

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;
@@ -32,6 +30,7 @@ export interface BusinessDescriptor {
     pageRoute?: string;
     isFullBleed?: boolean;
     showBusinessLogToggle?: boolean;
+    showHostStatusBar?: boolean;
 }
 export interface ToolDescriptor {
     toolId: string;
@@ -109,103 +108,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 +137,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/dist/src/upgrade.d.ts

@@ -0,0 +1,44 @@
+export type PluginSdkUpgradeStatus = "up-to-date" | "upgrade-available" | "upgraded" | "rolled-back" | "blocked";
+export type PluginSdkUpgradeCheckStatus = "passed" | "warning" | "skipped" | "failed";
+export interface PluginSdkUpgradeCheck {
+    name: string;
+    status: PluginSdkUpgradeCheckStatus;
+    detail: string;
+}
+export interface PluginSdkUpgradeRollback {
+    attempted: boolean;
+    succeeded: boolean;
+    detail: string;
+}
+export interface PluginSdkUpgradeResult {
+    status: PluginSdkUpgradeStatus;
+    projectDirectory: string;
+    currentVersion: string | null;
+    targetVersion: string;
+    source: string;
+    dependencySection: "dependencies" | "devDependencies" | null;
+    changedFiles: string[];
+    checks: PluginSdkUpgradeCheck[];
+    rollback: PluginSdkUpgradeRollback | null;
+}
+export interface PluginSdkUpgradeOptions {
+    projectDirectory: string;
+    workingDirectory: string;
+    sdkSource?: string;
+    checkOnly: boolean;
+    allowMajor: boolean;
+    skipProjectChecks: boolean;
+}
+export interface PluginSdkUpgradeCommandResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+export interface PluginSdkUpgradeRuntime {
+    nodeVersion: string;
+    runNpm(args: string[], cwd: string): PluginSdkUpgradeCommandResult;
+    runNode(args: string[], cwd: string): PluginSdkUpgradeCommandResult;
+}
+export declare function runPluginSdkUpgrade(options: PluginSdkUpgradeOptions, runtime?: PluginSdkUpgradeRuntime): PluginSdkUpgradeResult;
+export declare function formatPluginSdkUpgradeResult(result: PluginSdkUpgradeResult): string;