@aiot-nexus/plugin-sdk 1.1.0 → 1.1.1

package/README.md

@@ -27,6 +27,26 @@ nexus-plugin dev:nexus [plugin-project-directory] --host <nexus.exe-or-directory
 
 `npm run pack:sdk` 将离线安装包写入 `package/`。该目录是本地构建产物，不进入 Git。`npm run publish:sdk` 发布到官方 npm registry；`prepack` 会强制运行测试、构建并核对实际 npm 文件清单，缺少任一公开入口时拒绝发布。
 
+## SDK 版本提示
+
+SDK 提供两层非阻塞版本检查：
+
+- 安装阶段的 `postinstall` 会强制查询 `dist-tags.latest` 并写入当前用户缓存。npm 7+ 默认隐藏依赖包的 lifecycle 输出；需要看到安装阶段 notice 时使用 `npm install --foreground-scripts`。`npm install --ignore-scripts` 会跳过该阶段，但不影响后续 CLI 检查。
+- `nexus-plugin` 启动时先读取缓存。缓存新鲜期为 24 小时；缓存缺失或过期时在后台检查，不等待网络，不改变命令退出码。检测到普通更新时会显示：
+
+  ```text
+  npm notice Update available for @aiot-nexus/plugin-sdk: 1.1.1 -> 1.2.0
+  npm notice Run npm install --save-dev @aiot-nexus/plugin-sdk@latest
+  ```
+
+检查会优先使用 npm 当前配置的 registry（包括私有 registry），主源失败后回退官方 npm registry；不会发送 token、密码或项目路径。离线、超时、registry 返回非法数据或缓存损坏都静默降级，安装、构建、调试和正式宿主启动不会被阻断。
+
+大版本更新会额外提示先确认 Nexus Framework API 兼容性；检查不会自动修改 `package.json`、升级依赖或新增交互式命令。确认兼容后，推荐手动执行 `npm install --save-dev @aiot-nexus/plugin-sdk@latest`。
+
+可用环境变量：`NEXUS_PLUGIN_SDK_UPDATE_CHECK=0` 或 `NO_UPDATE_NOTIFIER=1` 会同时关闭安装和 CLI 检查。内部 SDK 打包环境也会自动跳过联网检查。
+
+使用本地 `--sdk-source ...tgz` 时，生成工程依赖的是 tgz 内记录的 SDK 版本；安装阶段仍可能按 npm registry 写入该版本的缓存，CLI 后续按“当前版本 + registry”读取。完全离线开发可设置上述禁用变量，或接受检查静默失败；本地 SDK 不会自动替换正式 npm SDK，也不会因为有新版本自动升级。
+
 ## 创建插件
 
 ```bash
@@ -44,7 +64,7 @@ nexus-plugin create my-frame-plugin \
 - 目标目录非空时命令以返回码 `2` 拒绝覆盖。生成或安装失败返回 `1`。
 - 两套模板均读取宿主 `PluginRendererContext.language` 和 `themeMode`，通过 `onContextChanged` 在同一 iframe 内响应运行时语言与主题切换，并内置 `zh-CN` / `en-US` renderer 文案；manifest 使用相同文化资源本地化宿主入口。模板页面自身不提供语言或主题选择控件。
 
-默认来源从 npm registry 安装。离线开发时先执行 `npm run pack:sdk`，再通过 `--sdk-source /path/to/aiot-nexus-plugin-sdk-1.1.0.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
+默认来源从 npm registry 安装。离线开发时先执行 `npm run pack:sdk`，再通过 `--sdk-source /path/to/aiot-nexus-plugin-sdk-1.1.1.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
 
 ## 独立调试
 

package/dist/src/cli/update-notice.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+export interface SdkUpdateResult {
+    status: string;
+    hasUpdate: boolean;
+    packageName: string;
+    currentVersion: string | null;
+    latestVersion: string | null;
+    isMajorUpdate: boolean;
+}
+export interface SdkUpdateCheckModule {
+    checkForSdkUpdate(options: {
+        currentVersion: string;
+    }): Promise<SdkUpdateResult>;
+    formatUpdateNotice(result: SdkUpdateResult): string;
+    isDisabled(env: NodeJS.ProcessEnv): boolean;
+    readCachedSdkUpdate(options: {
+        currentVersion: string;
+    }): SdkUpdateResult | null;
+}
+export declare function showSdkUpdateNotice(args: string[], stdout: (message: string) => void, updateCheck: SdkUpdateCheckModule, currentVersion: string): void;

package/dist/src/cli/update-notice.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.showSdkUpdateNotice = void 0;
+function showSdkUpdateNotice(args, stdout, updateCheck, currentVersion) {
+    if (args.includes("--help") || args.includes("-h") || updateCheck.isDisabled(process.env)) {
+        return;
+    }
+    const cached = updateCheck.readCachedSdkUpdate({ currentVersion });
+    if (cached && cached.hasUpdate) {
+        const notice = updateCheck.formatUpdateNotice(cached);
+        if (notice) {
+            stdout(notice);
+        }
+    }
+    if (cached) {
+        return;
+    }
+    void updateCheck
+        .checkForSdkUpdate({ currentVersion })
+        .then((result) => {
+        if (result.status !== "checked" || !result.hasUpdate) {
+            return;
+        }
+        const notice = updateCheck.formatUpdateNotice(result);
+        if (notice) {
+            stdout(notice);
+        }
+    })
+        .catch(() => {
+        // Version checks are advisory and must never affect a CLI command.
+    });
+}
+exports.showSdkUpdateNotice = showSdkUpdateNotice;

package/dist/src/cli.js

@@ -1,12 +1,43 @@
 #!/usr/bin/env node
 "use strict";
+/* eslint-disable @typescript-eslint/no-var-requires */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("path"));
+const index_1 = require("./index");
 const run_1 = require("./cli/run");
-const result = (0, run_1.runCli)(process.argv.slice(2), {
+const update_notice_1 = require("./cli/update-notice");
+const sdkUpdateCheck = require(path.resolve(__dirname, "../../scripts/sdk-update-check.js"));
+const args = process.argv.slice(2);
+const io = {
     cwd: () => process.cwd(),
     stdout: (message) => process.stdout.write(message + "\n"),
     stderr: (message) => process.stderr.write(message + "\n")
-});
+};
+(0, update_notice_1.showSdkUpdateNotice)(args, io.stdout, sdkUpdateCheck, index_1.PLUGIN_SDK_VERSION);
+const result = (0, run_1.runCli)(args, io);
 if (typeof result === "number") {
     process.exitCode = result;
 }

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 import pluginManifestSchema from "../.generated/plugin-manifest.schema.json";
-export declare const PLUGIN_SDK_VERSION = "1.1.0";
+export declare const PLUGIN_SDK_VERSION = "1.1.1";
 export { pluginManifestSchema };
 export * from "../.generated/plugin-framework-version";
 export * from "./types";

package/dist/src/index.js

@@ -20,7 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.pluginManifestSchema = exports.PLUGIN_SDK_VERSION = void 0;
 const plugin_manifest_schema_json_1 = __importDefault(require("../.generated/plugin-manifest.schema.json"));
 exports.pluginManifestSchema = plugin_manifest_schema_json_1.default;
-exports.PLUGIN_SDK_VERSION = "1.1.0";
+exports.PLUGIN_SDK_VERSION = "1.1.1";
 __exportStar(require("../.generated/plugin-framework-version"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./browser/frame-client"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiot-nexus/plugin-sdk",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "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"

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/README.md.tmpl

@@ -11,6 +11,10 @@ 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.
+
 The deployable plugin package is `dist/__PLUGIN_ID__/`. Copy that directory to the Nexus executable's `Plugins/__PLUGIN_ID__/` directory, then restart Nexus.
 
 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.
@@ -23,6 +27,8 @@ Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` for live development agai
 
 When this project was created from a local SDK archive, `vendor/aiot-nexus-plugin-sdk.tgz` is part of the source project and must be kept when the project is moved or committed.
 
+For a local SDK archive, the tgz version remains the plugin's current SDK version for comparison. It is not replaced automatically by a newer npm package; fully offline work can disable checks with the environment variables above.
+
 For main-process breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. If child-process auto attach is disabled, start `npm run dev:debug` and select `Attach Nexus plugin main (9229)`. Renderer DevTools opens automatically, with `src/renderer/app.ts` available through the development source map. `npm run dev` rebuilds before launch; use `npm run dev -- --no-build` only when intentionally reusing the current `dist` output.
 
 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/sqlite/README.md.tmpl

@@ -11,6 +11,10 @@ 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.
@@ -23,6 +27,8 @@ Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` to run the plugin inside
 
 When this project was created from a local SDK archive, `vendor/aiot-nexus-plugin-sdk.tgz` is part of the source project and must be kept when the project is moved or committed.
 
+For a local SDK archive, the tgz version remains the plugin's current SDK version for comparison. It is not replaced automatically by a newer npm package; fully offline work can disable checks with the environment variables above.
+
 For main-process breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. If child-process auto attach is disabled, start `npm run dev:debug` and select `Attach Nexus plugin main (9229)`. Renderer DevTools opens automatically, with `src/renderer/app.ts` available through the development source map. The default debug build also runs the Electron 22.3.27 native rebuild before launch. Use `npm run dev -- --no-build` only when intentionally reusing a compatible current `dist` output.
 
 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.