@aiot-nexus/plugin-sdk 1.1.0 → 2.0.0

package/scripts/sdk-update-check.js

@@ -0,0 +1,388 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-var-requires */
+
+const childProcess = require("child_process");
+const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const os = require("os");
+const path = require("path");
+
+const PACKAGE_NAME = "@aiot-nexus/plugin-sdk";
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const REQUEST_TIMEOUT_MS = 2000;
+const MAX_RESPONSE_BYTES = 256 * 1024;
+
+async function checkForSdkUpdate(options) {
+  const config = options || {};
+  const env = config.env || process.env;
+  const packageName = config.packageName || PACKAGE_NAME;
+  const currentVersion = config.currentVersion || readPackageVersion();
+  const now = typeof config.now === "number" ? config.now : Date.now();
+
+  if (isDisabled(env)) {
+    return createResult("disabled", currentVersion, null, null, packageName);
+  }
+
+  const registries = getRegistryCandidates(config);
+  if (registries.length === 0 || !isValidVersion(currentVersion)) {
+    return createResult("unavailable", currentVersion, null, registries[0] || null, packageName);
+  }
+
+  const cachePath = config.cachePath || getDefaultCachePath(env, os.platform());
+  const cache = readCache(cachePath);
+  for (const registry of registries) {
+    const cacheMatches =
+      cache &&
+      cache.packageName === packageName &&
+      cache.currentVersion === currentVersion &&
+      cache.registry === registry &&
+      isValidVersion(cache.latestVersion) &&
+      typeof cache.checkedAt === "number";
+    const cacheIsFresh = cacheMatches && now - cache.checkedAt < CACHE_TTL_MS;
+    if (!config.force && cacheIsFresh) {
+      return createResult("cache", currentVersion, cache.latestVersion, registry, packageName);
+    }
+
+    const endpoint = buildMetadataUrl(registry, packageName);
+    try {
+      const request = config.request || requestJson;
+      const metadata = await request(endpoint, {
+        timeoutMs: config.timeoutMs || REQUEST_TIMEOUT_MS,
+        headers: {
+          Accept: "application/vnd.npm.install-v1+json",
+          "User-Agent": "@aiot-nexus/plugin-sdk update check"
+        }
+      });
+      const latestVersion = extractLatestVersion(metadata);
+      if (!isValidVersion(latestVersion)) {
+        continue;
+      }
+
+      writeCache(cachePath, {
+        packageName,
+        currentVersion,
+        registry,
+        latestVersion,
+        checkedAt: now
+      });
+      return createResult("checked", currentVersion, latestVersion, registry, packageName);
+    } catch (_error) {
+      // Try the official registry after a configured registry failure.
+    }
+  }
+  return createResult("unavailable", currentVersion, null, registries[0], packageName);
+}
+
+function readCachedSdkUpdate(options) {
+  const config = options || {};
+  const env = config.env || process.env;
+  const packageName = config.packageName || PACKAGE_NAME;
+  const currentVersion = config.currentVersion || readPackageVersion();
+  if (isDisabled(env)) {
+    return createResult("disabled", currentVersion, null, null, packageName);
+  }
+
+  const registries = getRegistryCandidates(config);
+  if (registries.length === 0 || !isValidVersion(currentVersion)) {
+    return createResult("unavailable", currentVersion, null, registries[0] || null, packageName);
+  }
+
+  const cachePath = config.cachePath || getDefaultCachePath(env, os.platform());
+  const cache = readCache(cachePath);
+  const now = typeof config.now === "number" ? config.now : Date.now();
+  for (const registry of registries) {
+    if (
+      cache &&
+      cache.packageName === packageName &&
+      cache.currentVersion === currentVersion &&
+      cache.registry === registry &&
+      isValidVersion(cache.latestVersion) &&
+      typeof cache.checkedAt === "number" &&
+      now - cache.checkedAt < CACHE_TTL_MS
+    ) {
+      return createResult("cache", currentVersion, cache.latestVersion, registry, packageName);
+    }
+  }
+  return null;
+}
+
+function getRegistryCandidates(options) {
+  const config = options || {};
+  const env = config.env || process.env;
+  const configured = config.registry || resolveRegistry({ env, execFileSync: config.execFileSync });
+  const primary = normalizeRegistry(configured);
+  const official = normalizeRegistry(DEFAULT_REGISTRY);
+  return Array.from(new Set([primary, official].filter(Boolean)));
+}
+
+function createResult(status, currentVersion, latestVersion, registry, packageName) {
+  const hasUpdate =
+    isValidVersion(currentVersion) &&
+    isValidVersion(latestVersion) &&
+    compareVersions(latestVersion, currentVersion) > 0;
+  return {
+    status,
+    packageName: packageName || PACKAGE_NAME,
+    currentVersion,
+    latestVersion,
+    registry,
+    hasUpdate,
+    isMajorUpdate: hasUpdate && getMajor(latestVersion) > getMajor(currentVersion)
+  };
+}
+
+function isDisabled(env) {
+  return (
+    env.NEXUS_PLUGIN_SDK_UPDATE_CHECK === "0" ||
+    env.NO_UPDATE_NOTIFIER === "1" ||
+    env.NEXUS_PLUGIN_SDK_INTERNAL_PACK === "1"
+  );
+}
+
+function resolveRegistry(options) {
+  const config = options || {};
+  const env = config.env || process.env;
+  const configured = env.npm_config_registry || env.NPM_CONFIG_REGISTRY;
+  if (configured) {
+    return configured;
+  }
+
+  const execFileSync = config.execFileSync || childProcess.execFileSync;
+  try {
+    const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+    const output = execFileSync(npmCommand, ["config", "get", "registry"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (String(output).trim()) {
+      return String(output).trim();
+    }
+  } catch (_error) {
+    // A missing npm executable must not prevent a plugin from running.
+  }
+  return DEFAULT_REGISTRY;
+}
+
+function normalizeRegistry(value) {
+  if (!value) {
+    return null;
+  }
+  try {
+    const url = new URL(String(value).trim());
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return null;
+    }
+    url.username = "";
+    url.password = "";
+    url.hash = "";
+    url.search = "";
+    url.pathname = url.pathname.replace(/\/+$/, "");
+    return url.toString().replace(/\/$/, "");
+  } catch (_error) {
+    return null;
+  }
+}
+
+function buildMetadataUrl(registry, packageName) {
+  return registry + "/" + encodeURIComponent(packageName);
+}
+
+function requestJson(url, options, redirectCount) {
+  const requestOptions = options || {};
+  const redirects = typeof redirectCount === "number" ? redirectCount : 0;
+  const client = url.startsWith("https:") ? https : http;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let responseBytes = 0;
+    const finishResolve = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    const finishReject = (error) => {
+      if (!settled) {
+        settled = true;
+        reject(error);
+      }
+    };
+    const request = client.get(
+      url,
+      { headers: requestOptions.headers || {} },
+      (response) => {
+        if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+          response.resume();
+          if (redirects >= 2) {
+            finishReject(new Error("registry redirect limit exceeded"));
+            return;
+          }
+          let redirectUrl;
+          try {
+            redirectUrl = new URL(response.headers.location, url).toString();
+            if (!redirectUrl.startsWith("http:") && !redirectUrl.startsWith("https:")) {
+              throw new Error("registry redirect protocol is not supported");
+            }
+          } catch (error) {
+            finishReject(error);
+            return;
+          }
+          requestJson(redirectUrl, requestOptions, redirects + 1).then(finishResolve, finishReject);
+          return;
+        }
+        if (response.statusCode !== 200) {
+          response.resume();
+          finishReject(new Error("registry responded with HTTP " + response.statusCode));
+          return;
+        }
+
+        const chunks = [];
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          responseBytes += Buffer.byteLength(chunk, "utf8");
+          if (responseBytes > MAX_RESPONSE_BYTES) {
+            finishReject(new Error("registry response is too large"));
+            request.destroy();
+            return;
+          }
+          chunks.push(chunk);
+        });
+        response.once("error", finishReject);
+        response.on("end", () => {
+          try {
+            finishResolve(JSON.parse(chunks.join("")));
+          } catch (error) {
+            finishReject(error);
+          }
+        });
+      }
+    );
+    request.once("error", finishReject);
+    request.setTimeout(requestOptions.timeoutMs || REQUEST_TIMEOUT_MS, () => {
+      request.destroy(new Error("registry request timed out"));
+    });
+  });
+}
+
+function extractLatestVersion(metadata) {
+  if (!metadata || typeof metadata !== "object") {
+    return null;
+  }
+  const distTags = metadata["dist-tags"];
+  return distTags && typeof distTags.latest === "string" ? distTags.latest : null;
+}
+
+function getDefaultCachePath(env, platform) {
+  const values = env || process.env;
+  if (platform === "win32") {
+    const base = values.LOCALAPPDATA || path.join(values.USERPROFILE || os.homedir(), "AppData", "Local");
+    return path.join(base, "AIoT-Nexus", "plugin-sdk", "update-check.json");
+  }
+  if (platform === "darwin") {
+    return path.join(values.HOME || os.homedir(), "Library", "Caches", "AIoT-Nexus", "plugin-sdk", "update-check.json");
+  }
+  return path.join(
+    values.XDG_CACHE_HOME || path.join(values.HOME || os.homedir(), ".cache"),
+    "aiot-nexus",
+    "plugin-sdk",
+    "update-check.json"
+  );
+}
+
+function readCache(cachePath) {
+  try {
+    const cache = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+    return cache && typeof cache === "object" ? cache : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function writeCache(cachePath, cache) {
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    const temporaryPath = cachePath + ".tmp-" + process.pid;
+    fs.writeFileSync(temporaryPath, JSON.stringify(cache) + "\n", "utf8");
+    fs.renameSync(temporaryPath, cachePath);
+  } catch (_error) {
+    try {
+      fs.unlinkSync(cachePath + ".tmp-" + process.pid);
+    } catch (_ignored) {
+      // Cache persistence is best effort only.
+    }
+  }
+}
+
+function readPackageVersion() {
+  try {
+    return require(path.join(__dirname, "..", "package.json")).version;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function isValidVersion(version) {
+  return typeof version === "string" && /^\d+\.\d+\.\d+$/.test(version);
+}
+
+function compareVersions(left, right) {
+  const leftParts = left.split(".").map(Number);
+  const rightParts = right.split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) {
+      return leftParts[index] > rightParts[index] ? 1 : -1;
+    }
+  }
+  return 0;
+}
+
+function getMajor(version) {
+  return Number(version.split(".")[0]);
+}
+
+function formatUpdateNotice(result) {
+  if (!result || !result.hasUpdate) {
+    return "";
+  }
+  const lines = [
+    "npm notice",
+    "npm notice Update available for " + result.packageName + ": " + result.currentVersion + " -> " + result.latestVersion,
+    "npm notice Run npm install --save-dev " + result.packageName + "@latest"
+  ];
+  if (result.isMajorUpdate) {
+    lines.push("npm notice Major update: first confirm Nexus Framework API compatibility.");
+  }
+  lines.push("npm notice");
+  return lines.join("\n");
+}
+
+module.exports = {
+  CACHE_TTL_MS,
+  DEFAULT_REGISTRY,
+  PACKAGE_NAME,
+  buildMetadataUrl,
+  checkForSdkUpdate,
+  compareVersions,
+  extractLatestVersion,
+  formatUpdateNotice,
+  getDefaultCachePath,
+  isDisabled,
+  isValidVersion,
+  normalizeRegistry,
+  readCachedSdkUpdate,
+  resolveRegistry
+};
+
+if (require.main === module) {
+  checkForSdkUpdate({ force: process.argv.includes("--install") })
+    .then((result) => {
+      const notice = formatUpdateNotice(result);
+      if (notice) {
+        process.stdout.write(notice + "\n");
+      }
+    })
+    .catch(() => {
+      process.exitCode = 0;
+    });
+}

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

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

package/templates/minimal/README.md.tmpl

@@ -11,18 +11,24 @@ npm run dev
 npm run dev:nexus -- --host C:\path\to\nexus.exe
 ```
 
-The deployable plugin package is `dist/__PLUGIN_ID__/`. Copy that directory to the Nexus executable's `Plugins/__PLUGIN_ID__/` directory, then restart Nexus.
+SDK checks for a newer `@aiot-nexus/plugin-sdk` in two steps. The package `postinstall` refreshes a user cache; npm 7+ hides dependency lifecycle output by default, so use `npm install --foreground-scripts` to see it. The `nexus-plugin` CLI reads that cache and prints npm-style notices when it is fresh; missing or older-than-24-hours cache data is checked in the background without blocking the command. `npm install --ignore-scripts` skips only the install check, while CLI checks remain available.
 
-The renderer calls the main-process `demo.echo` operation through `@aiot-nexus/plugin-sdk`. Run `npm run validate` after changing the manifest or output layout.
+The 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 renderer calls the plugin-worker `demo.echo` operation through `@aiot-nexus/plugin-sdk`. Run `npm run validate` after changing the manifest or output layout.
 
 The renderer follows `context.language` and `context.themeMode` from Nexus, subscribes to in-place context updates without reloading the iframe, and includes `en-US` and `zh-CN` message catalogs. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host and simulate Nexus context changes. Add or edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
 Use `npm run dev:web` for renderer-only UI work in the system browser. It runs `build:web`, writes an isolated package under `.nexus-plugin-dev/web-package/`, builds with source maps, serves only on `127.0.0.1:4173`, and opens the browser automatically. It does not execute `mainEntry` or overwrite the deployable `dist` package. Language and theme controls still simulate Nexus context, while `invokeMain` is intentionally unavailable. Pass `-- --no-open` or `-- --port <port>` when needed; use `npm run dev` for Host API integration.
 
-Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` for live development against a compiled, packaged Nexus. The CLI atomically deploys this plugin to `<exeDir>/Plugins/__PLUGIN_ID__/`. Renderer changes rebuild and reload the iframe without changing the Nexus PID; safe manifest changes rescan contributions in the same process; `mainEntry`, dependency, native-module, or restart-sensitive manifest changes rebuild the full package and restart Nexus. Failed builds keep the previous deployment, and a failed restarted host rolls back the package. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
+Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` for live development against a compiled, packaged Nexus. The CLI atomically deploys this plugin to `<exeDir>/Plugins/__PLUGIN_ID__/`. Renderer changes rebuild and reload the iframe without changing the Nexus PID; safe manifest changes rescan contributions in the same process; `mainEntry`, dependency, native-module, or worker-sensitive manifest changes rebuild the full package, stop the old plugin worker, replace the package, and start a new worker while keeping the Nexus PID. Failed builds keep the previous deployment; a failed worker reload rolls the package back and restores the previous worker. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
 
 When this project was created from a local SDK archive, `vendor/aiot-nexus-plugin-sdk.tgz` is part of the source project and must be kept when the project is moved or committed.
 
-For main-process breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. If child-process auto attach is disabled, start `npm run dev:debug` and select `Attach Nexus plugin main (9229)`. Renderer DevTools opens automatically, with `src/renderer/app.ts` available through the development source map. `npm run dev` rebuilds before launch; use `npm run dev -- --no-build` only when intentionally reusing the current `dist` output.
+For 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.
 
 The independent host stores data under `.nexus-plugin-dev/` and mirrors the PluginFrame protocol and current Host API surface. Its simulated Nexus application version defaults to the version recorded by the SDK build; pass `npm run dev -- --host-version <X.Y.Z>` to exercise another compatibility branch. Run the deployable `dist/__PLUGIN_ID__/` in Nexus before delivery because the standalone host does not reproduce the full application shell or routing state.

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

@@ -1,7 +1,7 @@
 import type { PluginMainActivationContext } from "@aiot-nexus/plugin-sdk";
 
-export function activate(context: PluginMainActivationContext): void {
-  const registration = context.host.registerRendererMethod("demo.echo", (request) => {
+export async function activate(context: PluginMainActivationContext): Promise<void> {
+  const registration = await context.host.registerRendererMethod("demo.echo", (request) => {
     const value = request.input && typeof request.input.value === "string"
       ? request.input.value.trim()
       : "";
@@ -19,5 +19,8 @@ export function activate(context: PluginMainActivationContext): void {
   if (!registration.ok) {
     throw new Error(registration.error.message);
   }
-  context.host.log("info", "__PLUGIN_ID__ activated.");
+  const logResult = await context.host.log("info", "__PLUGIN_ID__ activated.");
+  if (!logResult.ok) {
+    throw new Error(logResult.error.message);
+  }
 }

package/templates/sqlite/.vscode/launch.json

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

package/templates/sqlite/README.md.tmpl

@@ -11,18 +11,24 @@ npm run dev
 npm run dev:nexus -- --host C:\path\to\nexus.exe
 ```
 
+SDK checks for a newer `@aiot-nexus/plugin-sdk` in two steps. The package `postinstall` refreshes a user cache; npm 7+ hides dependency lifecycle output by default, so use `npm install --foreground-scripts` to see it. The `nexus-plugin` CLI reads that cache and prints npm-style notices when it is fresh; missing or older-than-24-hours cache data is checked in the background without blocking the command. `npm install --ignore-scripts` skips only the install check, while CLI checks remain available.
+
+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.
+
 Every `npm run build` rebuilds `better-sqlite3@8.7.0` for Electron 22.3.27 with `@electron/rebuild@3.7.2` before packaging. `npm run rebuild:native` remains available as a standalone diagnostic command.
 
-The deployable plugin package is `dist/__PLUGIN_ID__/`. Copy that directory to the Nexus executable's `Plugins/__PLUGIN_ID__/` directory, then restart Nexus. Runtime data is stored in the host-provided plugin data directory and is not written into the plugin package.
+The deployable plugin package is `dist/__PLUGIN_ID__/`. For a manual installation, stop Nexus before replacing `Plugins/__PLUGIN_ID__/`, then start it again. During development, use `npm run dev:nexus` so the host coordinates worker shutdown, atomic replacement, and worker reactivation without changing the Nexus PID. Runtime data is stored in the host-provided plugin data directory and is not written into the plugin package.
 
 The renderer follows `context.language` and `context.themeMode` from Nexus, subscribes to in-place context updates without reloading the iframe, and includes `en-US` and `zh-CN` message catalogs. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host and simulate Nexus context changes. Static labels, CRUD status messages, action buttons, validation text, and date formatting switch together. Edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
 Use `npm run dev:web` for renderer-only layout, styling, localization, and responsive checks in the system browser. It runs `build:web`, writes an isolated package under `.nexus-plugin-dev/web-package/`, and does not rebuild or load `better-sqlite3`, execute `mainEntry`, copy native runtime files, or overwrite the deployable `dist` package. It builds with source maps, serves only on `127.0.0.1:4173`, and opens the browser automatically. Database operations report unsupported; use `npm run dev` for SQLite and Host API integration. Pass `-- --no-open` or `-- --port <port>` when needed.
 
-Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` to run the plugin inside a compiled, packaged Nexus. The initial deployment and every full package replacement are atomic. Renderer-only and safe manifest updates keep the Nexus PID; `mainEntry`, dependency, native-module, or restart-sensitive manifest changes run the complete build (including the Electron 22.3.27 native rebuild) before restarting Nexus. The database remains under the host-provided plugin data directory across restarts. Failed builds keep the previous deployment, and a failed restarted host rolls back the package. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
+Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` to run the plugin inside a compiled, packaged Nexus. The initial deployment and every full package replacement are atomic. Renderer-only and safe manifest updates keep the Nexus PID; `mainEntry`, dependency, native-module, or worker-sensitive manifest changes run the complete build (including the Electron 22.3.27 native rebuild), stop the old plugin worker, replace the package, and start a new worker in the same Nexus process. The database remains under the host-provided plugin data directory across worker replacements. Failed builds keep the previous deployment, and a failed worker reload rolls the package back and restores the previous worker. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
 
 When this project was created from a local SDK archive, `vendor/aiot-nexus-plugin-sdk.tgz` is part of the source project and must be kept when the project is moved or committed.
 
-For main-process breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. If child-process auto attach is disabled, start `npm run dev:debug` and select `Attach Nexus plugin main (9229)`. Renderer DevTools opens automatically, with `src/renderer/app.ts` available through the development source map. The default debug build also runs the Electron 22.3.27 native rebuild before launch. Use `npm run dev -- --no-build` only when intentionally reusing a compatible current `dist` output.
+For a local SDK archive, the tgz version remains the plugin's current SDK version for comparison. It is not replaced automatically by a newer npm package; fully offline work can disable checks with the environment variables above.
+
+For plugin-worker breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. If child-process auto attach is disabled, start `npm run dev:debug` and select `Attach Nexus plugin worker (9229)`. Renderer DevTools opens automatically, with `src/renderer/app.ts` available through the development source map. The default debug build also runs the Electron 22.3.27 native rebuild before launch. Use `npm run dev -- --no-build` only when intentionally reusing a compatible current `dist` output.
 
 The independent host stores the SQLite database and settings under `.nexus-plugin-dev/data/` and mirrors the PluginFrame protocol and current Host API surface. Its simulated Nexus application version defaults to the version recorded by the SDK build; pass `npm run dev -- --host-version <X.Y.Z>` to exercise another compatibility branch. Run the deployable `dist/__PLUGIN_ID__/` in Nexus before delivery because the standalone host does not reproduce the full application shell or routing state.

package/templates/sqlite/src/better-sqlite3.d.ts

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

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

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