@aiot-nexus/plugin-sdk 1.0.2 → 1.1.1

package/README.md

@@ -22,10 +22,31 @@ nexus-plugin validate <plugin-package-directory>
 nexus-plugin create <plugin-id> --template minimal|sqlite --output <parent-directory>
 nexus-plugin dev [plugin-project-directory]
 nexus-plugin dev:web [plugin-project-directory]
+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
@@ -43,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.0.2.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
+默认来源从 npm registry 安装。离线开发时先执行 `npm run pack:sdk`，再通过 `--sdk-source /path/to/aiot-nexus-plugin-sdk-1.1.1.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
 
 ## 独立调试
 
@@ -81,3 +102,21 @@ nexus-plugin dev [plugin-project-directory]
 调试宿主工具栏中的语言和主题选择器用于模拟 Nexus 主框架 context，不属于插件页面。切换后调试宿主向同一 iframe 重发框架 `1.0.0` 已有的 `init` 消息；SDK 将后续 `init` 作为 context 更新并原地刷新语言和主题，同时仍接受可选的 `context-changed` 消息。调试宿主还复用正式的 `nexus-plugin://` 资源协议、iframe sandbox、CSP、消息结构、operation 校验以及当前 Host API 权限语义，但不包含 Nexus 的完整页面路由、Pinia 状态和应用级功能。交付前仍需把 `dist/<plugin-id>/` 放入正式 Nexus 完成集成验证。
 
 浏览器 UI 命令支持 `--no-build`、`--no-open`、`--port <port>`，以及与 Electron 调试宿主相同的 `--language`、`--theme`、`--surface` 和 `--contribution-id` 参数。它使用普通 `http://127.0.0.1` iframe，不模拟 `nexus-plugin://` 协议或 Electron sandbox，因此只作为 UI 开发入口。Renderer-only 输出不会覆盖正式插件制品。
+
+## 使用正式 Nexus 调试
+
+已经安装并构建插件后，可直接把编译好的正式 Nexus 作为宿主：
+
+```powershell
+npm run dev:nexus -- --host D:\prj\tmp\aiot-nexus\dist\electron\nexus-win32-x64\nexus.exe
+```
+
+`dev:nexus` 首次启动会完成正式构建，通过 staging 原子部署到 `<exeDir>/Plugins/<pluginId>/`，再由 CLI 以 `--plugin-dev`、随机控制管道和会话令牌启动 Nexus。开发通道只在这次由 CLI 管理的进程中启用；普通双击或不带 `--plugin-dev` 启动时不会创建控制管道，也不会打开 DevTools。
+
+| 修改范围 | 行为 |
+| --- | --- |
+| `src/renderer/**` | 只运行 `build:web` 并替换 renderer；宿主 PID 不变，iframe 重新完成 `ready/init`。 |
+| `src/manifest.json` 的展示、贡献点等安全字段 | 构建 renderer、原子替换 manifest 后重扫插件目录；宿主 PID 不变。 |
+| `src/main.ts`、依赖、原生模块或主进程相关 manifest 字段 | 完整构建成功后请求旧宿主退出，替换完整插件包并启动新宿主；宿主 PID 变化。 |
+
+更新构建或 manifest 重扫失败时保留上一个可运行部署；新宿主启动失败时回滚插件包并恢复旧版本。`mainEntry` 不通过清理 `require.cache` 热替换，主进程变化始终使用完整重启。默认打开 Renderer DevTools；可传 `--no-devtools`。主进程调试支持 `--inspect[=<port>]` 和 `--inspect-brk[=<port>]`，贡献点选择支持 `--surface` 与 `--contribution-id`。按 `Ctrl+C` 停止 CLI 时，CLI 会关闭其启动的正式宿主。

package/dist/src/cli/run.d.ts

@@ -3,5 +3,5 @@ export interface CliIo {
     stdout(message: string): void;
     stderr(message: string): void;
 }
-export declare function runCli(args: string[], io: CliIo): number;
+export declare function runCli(args: string[], io: CliIo): number | Promise<number>;
 export declare function usage(): string;

package/dist/src/cli/run.js

@@ -29,6 +29,7 @@ const index_1 = require("../index");
 const scaffold_1 = require("../scaffold");
 const dev_1 = require("../dev");
 const web_dev_1 = require("../web-dev");
+const nexus_dev_1 = require("../nexus-dev");
 const nodeEngine = ">=16.20.0 <17";
 function runCli(args, io) {
     const command = args[0];
@@ -70,6 +71,9 @@ function runCli(args, io) {
     if (command === "dev:web") {
         return runWebDev(args.slice(1), io);
     }
+    if (command === "dev:nexus") {
+        return runNexusDev(args.slice(1), io);
+    }
     return usageError(io, command ? "Unknown command: " + command : "A command is required.");
 }
 exports.runCli = runCli;
@@ -85,10 +89,100 @@ function usage() {
         "    [--contribution-id <id>] [--no-devtools]",
         "  nexus-plugin dev:web [plugin-project-directory] [--no-build] [--no-open] [--port <port>]",
         "    [--language <culture>] [--theme system|light|dark] [--surface business|tool|settings]",
+        "    [--contribution-id <id>]",
+        "  nexus-plugin dev:nexus [plugin-project-directory] --host <nexus.exe-or-directory>",
+        "    [--inspect[=<port>] | --inspect-brk[=<port>]] [--no-devtools]",
+        "    [--language <culture>] [--theme system|light|dark] [--surface business|tool|settings]",
         "    [--contribution-id <id>]"
     ].join("\n");
 }
 exports.usage = usage;
+function runNexusDev(args, io) {
+    if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
+        io.stdout(usage());
+        return 0;
+    }
+    let projectDirectory = io.cwd();
+    let index = 0;
+    if (args[0] && !args[0].startsWith("--")) {
+        projectDirectory = path.resolve(io.cwd(), args[0]);
+        index = 1;
+    }
+    const options = {
+        projectDirectory,
+        openDevTools: true
+    };
+    const seen = new Set();
+    for (; index < args.length; index += 1) {
+        const option = args[index];
+        if (option === "--no-devtools") {
+            if (seen.has(option)) {
+                return usageError(io, "Duplicate option: " + option);
+            }
+            seen.add(option);
+            options.openDevTools = false;
+            continue;
+        }
+        const inspector = parseInspectorOption(option);
+        if (inspector) {
+            if (options.inspectorMode) {
+                return usageError(io, "Only one main-process inspector option can be used.");
+            }
+            const key = "--" + inspector.mode;
+            if (seen.has(key)) {
+                return usageError(io, "Duplicate option: " + key);
+            }
+            seen.add(key);
+            options.inspectorMode = inspector.mode;
+            options.inspectorPort = inspector.port;
+            continue;
+        }
+        if (!["--host", "--language", "--theme", "--surface", "--contribution-id"].includes(option)) {
+            return usageError(io, "Unknown dev:nexus option: " + option);
+        }
+        if (seen.has(option)) {
+            return usageError(io, "Duplicate option: " + option);
+        }
+        seen.add(option);
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            return usageError(io, option + " requires a value.");
+        }
+        index += 1;
+        if (option === "--host") {
+            options.hostPath = path.resolve(io.cwd(), value);
+        }
+        else if (option === "--language") {
+            options.language = value;
+        }
+        else if (option === "--theme") {
+            if (value !== "system" && value !== "light" && value !== "dark") {
+                return usageError(io, "theme must be system, light, or dark.");
+            }
+            options.themeMode = value;
+        }
+        else if (option === "--surface") {
+            if (value !== "business" && value !== "tool" && value !== "settings") {
+                return usageError(io, "surface must be business, tool, or settings.");
+            }
+            options.surface = value;
+        }
+        else {
+            options.contributionId = value;
+        }
+    }
+    if (!options.hostPath) {
+        return usageError(io, "dev:nexus requires --host <nexus.exe-or-directory>.");
+    }
+    return (0, nexus_dev_1.runPluginNexusDev)(options, io).catch((error) => {
+        if (error instanceof dev_1.PluginDevError) {
+            io.stderr(error.message);
+            return error.exitCode;
+        }
+        io.stderr("Packaged Nexus plugin development failed: " + (error instanceof Error ? error.message : String(error)));
+        return 1;
+    });
+}
 function runWebDev(args, io) {
     if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
         io.stdout(usage());

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,9 +1,49 @@
 #!/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");
-process.exitCode = (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;
+}
+else {
+    result.then((exitCode) => { process.exitCode = exitCode; }, (error) => {
+        process.stderr.write("nexus-plugin failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
+        process.exitCode = 1;
+    });
+}

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.0.2";
+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.0.2";
+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/dist/src/nexus-dev-control.d.ts

@@ -0,0 +1,42 @@
+export type NexusDevUpdateType = "rendererUpdated" | "manifestUpdated";
+export interface NexusDevUpdateResult {
+    ok: boolean;
+    message: string;
+    requiresRestart?: boolean;
+}
+export declare class NexusDevControlServer {
+    readonly token: string;
+    readonly pipePath: string;
+    private server;
+    private socket;
+    private receiveBuffer;
+    private helloAccepted;
+    private authenticated;
+    private authenticationResolve;
+    private authenticationReject;
+    private authenticationPromise;
+    private disconnectionPromise;
+    private disconnectionResolve;
+    private disconnectHandler;
+    private readonly pendingUpdates;
+    private readonly pendingShutdowns;
+    private nextRequestId;
+    start(): Promise<void>;
+    waitForAuthentication(timeoutMs?: number): Promise<void>;
+    sendUpdate(type: NexusDevUpdateType, pluginId: string): Promise<NexusDevUpdateResult>;
+    requestShutdown(): Promise<void>;
+    waitForDisconnection(timeoutMs?: number): Promise<void>;
+    setDisconnectHandler(handler: (error: Error) => void): () => void;
+    isConnected(): boolean;
+    close(): Promise<void>;
+    private handleConnection;
+    private handleData;
+    private handleMessage;
+    private handleDisconnect;
+    private rejectPending;
+    private rejectPendingShutdowns;
+    private ensureAuthenticationPromise;
+    private ensureDisconnectionPromise;
+    private rejectAuthentication;
+}
+export declare function helloProofPayload(version: number, pid: number, nonce: string): string;