@aiot-nexus/plugin-sdk 1.1.0 → 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.0",
+  "version": "2.0.0",
   "description": "Types, PluginFrame client, and CLI for AIoT Nexus independent plugins.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -30,12 +30,14 @@
     "dist",
     "dev-host",
     "templates",
-    "README.md"
+    "README.md",
+    "scripts/sdk-update-check.js"
   ],
   "scripts": {
     "build": "node scripts/build.js",
+    "postinstall": "node scripts/sdk-update-check.js --install",
     "verify:package": "node scripts/verify-package.js",
-    "test": "npm run build && node tests/package.test.js && node tests/cli.test.js && node tests/dev.test.js && node tests/nexus-dev.test.js && node tests/frame-client.test.js && node tests/web-dev.test.js && npm run verify:package",
+    "test": "npm run build && node tests/package.test.js && node tests/sdk-update-check.test.js && node tests/cli.test.js && node tests/cli-entry.test.js && node tests/update-notice.test.js && node tests/dev.test.js && node tests/nexus-dev.test.js && node tests/frame-client.test.js && node tests/web-dev.test.js && npm run verify:package",
     "prepack": "node scripts/prepack.js",
     "pack:sdk": "npm run build && npm run verify:package && node scripts/pack.js",
     "publish:sdk": "npm publish"