@aiot-nexus/plugin-sdk 1.0.1 → 1.1.0

package/README.md

@@ -15,14 +15,17 @@ AIoT Nexus 独立插件开发包，包含公开 TypeScript 契约、PluginFrame
 npm run build
 npm test
 npm run pack:sdk
+npm run publish:sdk
 
 nexus-plugin info
 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 pack:sdk` 将离线安装包写入 `package/`。该目录是本地构建产物，不进入 Git。`npm run publish:sdk` 发布到官方 npm registry；`prepack` 会强制运行测试、构建并核对实际 npm 文件清单，缺少任一公开入口时拒绝发布。
 
 ## 创建插件
 
@@ -39,23 +42,27 @@ nexus-plugin create my-frame-plugin \
 - `--sdk-source` 默认为当前 CLI 的 SDK 版本。也可传入严格的 `X.Y.Z` npm 版本、`@aiot-nexus/plugin-sdk@X.Y.Z` 或本地 `.tgz` 进行覆盖；本地包会复制到生成工程的 `vendor/`，并写入可迁移的相对 `file:` 依赖。
 - 默认不安装依赖；传入 `--install` 后执行 `npm install`。SQLite 模板在每次 `npm run build` 前强制执行 Electron 22.3.27 native rebuild。
 - 目标目录非空时命令以返回码 `2` 拒绝覆盖。生成或安装失败返回 `1`。
-- 两套模板均读取宿主 `PluginRendererContext.language`，通过 `onContextChanged` 在同一 iframe 内响应运行时语言切换，并内置 `zh-CN` / `en-US` renderer 文案；manifest 使用相同文化资源本地化宿主入口。
+- 两套模板均读取宿主 `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.1.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
+默认来源从 npm registry 安装。离线开发时先执行 `npm run pack:sdk`，再通过 `--sdk-source /path/to/aiot-nexus-plugin-sdk-1.1.0.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
 
 ## 独立调试
 
 生成工程安装依赖后，可以完全在插件目录启动调试宿主：
 
 ```bash
+npm run dev:web
 npm run dev
 npm run dev:debug
 ```
 
+- `npm run dev:web` 先运行模板独立的 `build:web`，只编译 Renderer 到 `.nexus-plugin-dev/web-package/<plugin-id>/`，再启动仅绑定 `127.0.0.1:4173` 的本地 HTTP 宿主并打开系统浏览器；它不执行 native rebuild、不复制原生运行时、不覆盖正式 `dist`，支持浏览器 DevTools 与源码映射。
+- 浏览器模式不加载 `mainEntry`，`invokeMain` 会返回 `PluginCapabilityUnsupported`；设置仅在本次服务进程内保存，日志输出到 CLI。涉及主进程、SQLite 或 Host API 时使用 `npm run dev`。
 - `npm run dev` 先构建和校验插件，再使用工程本地固定的 `electron@22.3.27` 启动 SDK 调试宿主；Renderer DevTools 默认自动打开。
+- Electron 调试宿主的 `host.hostVersion` 默认是 SDK 构建时记录的 Nexus 应用版本；使用 `nexus-plugin dev . --host-version <X.Y.Z>` 可模拟其他应用版本，并按 manifest `minHostVersion` 拒绝不兼容组合。
 - `npm run dev:debug` 额外使用 `--inspect-brk=9229` 暂停 Electron 主进程，可在 `src/main.ts` 启动阶段命中断点。
 - 生成工程包含 `.vscode/launch.json`。在 VS Code 中选择 `Debug Nexus plugin` 可直接启动；若本机关闭了子进程自动附加，则先运行 `npm run dev:debug`，再选择 `Attach Nexus plugin main (9229)`。renderer 断点在自动打开的 DevTools `Sources` 中设置。
-- 调试构建会内联 `src/main.ts` 和 `src/renderer/app.ts` source map。普通 `npm run build` 不内联源码，不改变部署制品形态。
+- Electron 调试构建会内联 `src/main.ts` 和 `src/renderer/app.ts` source map；浏览器 `build:web` 只内联 Renderer source map。普通 `npm run build` 不内联源码，不改变部署制品形态。模板在收到首个 Host context 前隐藏正文，应用语言和主题后再显示。
 - 调试数据保存在工程的 `.nexus-plugin-dev/`，该目录默认被忽略。关闭调试窗口会结束独立 Electron 进程；修改源码后重新运行调试命令。
 
 可直接使用的 CLI 选项：
@@ -64,6 +71,7 @@ npm run dev:debug
 nexus-plugin dev [plugin-project-directory]
   [--no-build]
   [--inspect[=<port>] | --inspect-brk[=<port>]]
+  [--host-version <X.Y.Z>]
   [--language <culture>]
   [--theme system|light|dark]
   [--surface business|tool|settings]
@@ -71,4 +79,24 @@ nexus-plugin dev [plugin-project-directory]
   [--no-devtools]
 ```
 
-调试宿主复用正式的 `nexus-plugin://` 资源协议、iframe sandbox、CSP、消息结构、operation 校验以及当前 Host API 权限语义，但不包含 Nexus 的完整页面路由、Pinia 状态和应用级功能。交付前仍需把 `dist/<plugin-id>/` 放入正式 Nexus 完成集成验证。
+调试宿主工具栏中的语言和主题选择器用于模拟 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/dev-host/host.html

@@ -154,18 +154,18 @@
     <header class="toolbar">
       <strong id="pluginName" class="plugin-name">Nexus Plugin Dev</strong>
       <label class="control" for="languageSelect">
-        <span>Language</span>
+        <span data-host-i18n="control.language">Language</span>
         <select id="languageSelect"></select>
       </label>
       <label class="control" for="themeSelect">
-        <span>Theme</span>
+        <span data-host-i18n="control.theme">Theme</span>
         <select id="themeSelect">
-          <option value="system">System</option>
-          <option value="light">Light</option>
-          <option value="dark">Dark</option>
+          <option value="system" data-host-i18n="theme.system">System</option>
+          <option value="light" data-host-i18n="theme.light">Light</option>
+          <option value="dark" data-host-i18n="theme.dark">Dark</option>
         </select>
       </label>
-      <button id="reloadButton" type="button">Reload frame</button>
+      <button id="reloadButton" type="button" data-host-i18n="action.reload">Reload frame</button>
       <span id="status" class="status" data-connected="false">Waiting</span>
     </header>
     <main class="frame-shell">
@@ -174,13 +174,13 @@
     <script>
       "use strict";
 
-      var api = window.nexusPluginDevHost;
+      var api = window.nexusPluginDevHost || createBrowserHostApi();
       var iframe = document.getElementById("pluginFrame");
       var pluginName = document.getElementById("pluginName");
       var languageSelect = document.getElementById("languageSelect");
       var themeSelect = document.getElementById("themeSelect");
       var reloadButton = document.getElementById("reloadButton");
-      var status = document.getElementById("status");
+      var statusOutput = document.getElementById("status");
       var configuration;
       var context;
       var initialized = false;
@@ -188,6 +188,32 @@
       var resizeSeen = false;
       var pendingRequests = 0;
       var smokeTimer;
+      var statusKey = "status.waiting";
+      var statusConnected = false;
+      var hostMessages = {
+        "en-US": {
+          "control.language": "Language",
+          "control.theme": "Theme",
+          "theme.system": "System",
+          "theme.light": "Light",
+          "theme.dark": "Dark",
+          "action.reload": "Reload frame",
+          "status.waiting": "Waiting",
+          "status.connected": "Connected",
+          "status.hostError": "Host error"
+        },
+        "zh-CN": {
+          "control.language": "语言",
+          "control.theme": "主题",
+          "theme.system": "跟随系统",
+          "theme.light": "浅色",
+          "theme.dark": "深色",
+          "action.reload": "重新加载",
+          "status.waiting": "等待中",
+          "status.connected": "已连接",
+          "status.hostError": "宿主错误"
+        }
+      };
 
       window.addEventListener("message", handleMessage);
       languageSelect.addEventListener("change", updateContext);
@@ -203,10 +229,11 @@
         iframe.title = value.pluginId;
         populateLanguages(value.supportedCultures, context.language);
         themeSelect.value = context.themeMode;
+        applyHostLanguage();
         applyTheme();
         iframe.src = value.frameUrl;
       }).catch(function reportInitializationFailure(error) {
-        setStatus("Host error", false);
+        setStatus("status.hostError", false);
         console.error(error);
       });
 
@@ -221,7 +248,7 @@
         if (message.type === "nexus-plugin:ready") {
           initialized = true;
           postToFrame({ type: "nexus-plugin:init", context: context });
-          setStatus("Connected", true);
+          setStatus("status.connected", true);
           return;
         }
         if (message.type === "nexus-plugin:resize" && typeof message.height === "number") {
@@ -260,9 +287,10 @@
           language: languageSelect.value,
           themeMode: themeSelect.value
         });
+        applyHostLanguage();
         applyTheme();
         if (initialized) {
-          postToFrame({ type: "nexus-plugin:context-changed", context: context });
+          postToFrame({ type: "nexus-plugin:init", context: context });
         }
       }
 
@@ -275,7 +303,7 @@
         resizeSeen = false;
         pendingRequests = 0;
         cancelSmokeReport();
-        setStatus("Waiting", false);
+        setStatus("status.waiting", false);
         iframe.src = "about:blank";
         window.setTimeout(function restoreFrame() {
           iframe.src = configuration.frameUrl;
@@ -306,6 +334,15 @@
         document.documentElement.dataset.theme = dark ? "dark" : "light";
       }
 
+      function applyHostLanguage() {
+        var language = context && String(context.language).toLowerCase().startsWith("zh") ? "zh-CN" : "en-US";
+        document.documentElement.lang = language;
+        document.querySelectorAll("[data-host-i18n]").forEach(function localize(element) {
+          element.textContent = hostMessages[language][element.dataset.hostI18n] || element.textContent;
+        });
+        statusOutput.textContent = hostMessages[language][statusKey];
+      }
+
       function respond(requestId, result) {
         postToFrame({ type: "nexus-plugin:response", requestId: requestId, result: result });
       }
@@ -314,9 +351,39 @@
         iframe.contentWindow && iframe.contentWindow.postMessage(message, configuration.frameOrigin);
       }
 
-      function setStatus(text, connected) {
-        status.textContent = text;
-        status.dataset.connected = connected ? "true" : "false";
+      function setStatus(key, connected) {
+        statusKey = key;
+        statusConnected = connected;
+        var language = context && String(context.language).toLowerCase().startsWith("zh") ? "zh-CN" : "en-US";
+        statusOutput.textContent = hostMessages[language][statusKey];
+        statusOutput.dataset.connected = statusConnected ? "true" : "false";
+      }
+
+      function createBrowserHostApi() {
+        return {
+          getConfig: function getConfig() {
+            return requestBrowserHost("/__nexus_plugin_dev/config");
+          },
+          invoke: function invoke(request) {
+            return requestBrowserHost("/__nexus_plugin_dev/invoke", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify(request)
+            });
+          },
+          notifyFrameReady: function notifyFrameReady() {}
+        };
+      }
+
+      function requestBrowserHost(url, options) {
+        return window.fetch(url, Object.assign({ credentials: "same-origin" }, options)).then(function parseResponse(response) {
+          return response.json().then(function handleBody(body) {
+            if (!response.ok) {
+              throw new Error(body && body.error ? body.error : "Browser host request failed.");
+            }
+            return body;
+          });
+        });
       }
 
       function scheduleSmokeReport() {

package/dev-host/main.js

@@ -43,6 +43,7 @@ app.setName("Nexus Plugin Dev: " + configuration.manifest.pluginId);
 
 let mainWindow;
 let smokeTimeout;
+let smokeVerificationRunning = false;
 
 app.whenReady().then(function startDevHost() {
   registerPluginRendererProtocol();
@@ -69,6 +70,10 @@ function loadConfiguration(args) {
   const contributionId = requiredArgument(args, "--contribution-id");
   const language = requiredArgument(args, "--language");
   const themeMode = requiredArgument(args, "--theme");
+  const hostVersion = requiredArgument(args, "--host-version");
+  if (!isStrictVersion(hostVersion)) {
+    throw new Error("--host-version must use X.Y.Z format.");
+  }
   if (!hasContribution(manifest, surface, contributionId)) {
     throw new Error("Selected PluginFrame contribution is not declared: " + surface + ":" + contributionId);
   }
@@ -84,6 +89,7 @@ function loadConfiguration(args) {
     contributionId,
     language,
     themeMode,
+    hostVersion,
     openDevTools: !args.includes("--no-devtools"),
     smoke: args.includes("--smoke"),
     devDataDirectory,
@@ -178,7 +184,7 @@ function activatePluginMain() {
 function createHostApi() {
   const manifest = configuration.manifest;
   return {
-    hostVersion: manifest.minHostVersion || "0.0.0",
+    hostVersion: configuration.hostVersion,
     hostApiVersion: sdk.PLUGIN_FRAMEWORK_VERSION,
     pluginId: manifest.pluginId,
     pluginDataDirectory: configuration.pluginDataDirectory,
@@ -291,16 +297,93 @@ function registerIpcHandlers() {
   });
   ipcMain.on(ipcChannels.frameReady, function frameReady(event) {
     assertMainWindowSender(event);
-    if (configuration.smoke) {
-      clearTimeout(smokeTimeout);
-      process.stdout.write("[nexus-plugin-dev] renderer initialization smoke passed.\n");
-      setTimeout(function exitAfterSmokeSettles() {
-        app.exit(0);
-      }, 100);
+    if (configuration.smoke && !smokeVerificationRunning) {
+      smokeVerificationRunning = true;
+      void verifyRendererContextSmoke().then(function reportSmokeSuccess() {
+        clearTimeout(smokeTimeout);
+        process.stdout.write("[nexus-plugin-dev] renderer context synchronization smoke passed.\n");
+        setTimeout(function exitAfterSmokeSettles() {
+          app.exit(0);
+        }, 100);
+      }).catch(function reportSmokeFailure(error) {
+        clearTimeout(smokeTimeout);
+        process.stderr.write("[nexus-plugin-dev] renderer context synchronization smoke failed: " + errorMessage(error) + "\n");
+        app.exit(1);
+      });
     }
   });
 }
 
+async function verifyRendererContextSmoke() {
+  if (!mainWindow || mainWindow.isDestroyed()) {
+    throw new Error("Development host window is unavailable.");
+  }
+  const frame = findPluginRendererFrame(mainWindow.webContents.mainFrame);
+  if (!frame) {
+    throw new Error("Plugin renderer frame was not found.");
+  }
+  const hostApi = createHostApi();
+  if (hostApi.hostVersion !== configuration.hostVersion
+    || hostApi.hostApiVersion !== sdk.PLUGIN_FRAMEWORK_VERSION
+    || configuration.manifest.minHostVersion === undefined) {
+    throw new Error("Development Host API version contract is inconsistent.");
+  }
+  const initialState = await readRendererContextState(frame);
+  const targetLanguage = configuration.manifest.supportedCultures.find(function findAlternative(culture) {
+    return culture !== configuration.language;
+  }) || configuration.language;
+  const targetTheme = configuration.themeMode === "dark" ? "light" : "dark";
+  await mainWindow.webContents.executeJavaScript(`(() => {
+    const languageSelect = document.getElementById("languageSelect");
+    const themeSelect = document.getElementById("themeSelect");
+    languageSelect.value = ${JSON.stringify(targetLanguage)};
+    languageSelect.dispatchEvent(new Event("change", { bubbles: true }));
+    themeSelect.value = ${JSON.stringify(targetTheme)};
+    themeSelect.dispatchEvent(new Event("change", { bubbles: true }));
+  })()`, true);
+
+  const deadline = Date.now() + 5000;
+  let lastState = initialState;
+  while (Date.now() < deadline) {
+    lastState = await readRendererContextState(frame);
+    const languageChanged = lastState.language === targetLanguage
+      && (targetLanguage === configuration.language || lastState.localizedText !== initialState.localizedText);
+    if (languageChanged && lastState.theme === targetTheme) {
+      return;
+    }
+    await new Promise(function wait(resolve) {
+      setTimeout(resolve, 100);
+    });
+  }
+  throw new Error(
+    "Expected language=" + targetLanguage + " and theme=" + targetTheme
+    + ", received " + JSON.stringify(lastState) + "."
+  );
+}
+
+function findPluginRendererFrame(frame) {
+  for (const childFrame of frame.frames) {
+    if (childFrame.url.startsWith(pluginRendererProtocol + "://" + configuration.manifest.pluginId + "/")) {
+      return childFrame;
+    }
+    const nested = findPluginRendererFrame(childFrame);
+    if (nested) {
+      return nested;
+    }
+  }
+  return undefined;
+}
+
+async function readRendererContextState(frame) {
+  return frame.executeJavaScript(`({
+    language: document.documentElement.lang,
+    theme: document.documentElement.dataset.theme || "",
+    localizedText: document.querySelector("[data-i18n]")
+      ? document.querySelector("[data-i18n]").textContent
+      : ""
+  })`, true);
+}
+
 function createRendererConfiguration() {
   const manifest = configuration.manifest;
   const frameOrigin = pluginRendererProtocol + "://" + manifest.pluginId;
@@ -457,7 +540,7 @@ function createWindow() {
   }
   if (configuration.smoke) {
     smokeTimeout = setTimeout(function failSmokeTimeout() {
-      process.stderr.write("[nexus-plugin-dev] renderer initialization smoke timed out.\n");
+      process.stderr.write("[nexus-plugin-dev] renderer context synchronization smoke timed out.\n");
       app.exit(1);
     }, 15000);
   }
@@ -660,6 +743,13 @@ function requiredPathArgument(args, name) {
   return resolved;
 }
 
+function isStrictVersion(value) {
+  const match = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.exec(value);
+  return Boolean(match && [match[1], match[2], match[3]].every(function isSafe(segment) {
+    return Number.isSafeInteger(Number(segment));
+  }));
+}
+
 function requiredArgument(args, name) {
   const prefix = name + "=";
   const argument = args.find(function findArgument(value) {

package/dist/dev-host-metadata.json

@@ -0,0 +1,3 @@
+{
+  "nexusApplicationVersion": "0.0.1"
+}

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

@@ -28,6 +28,8 @@ const path = __importStar(require("path"));
 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];
@@ -66,6 +68,12 @@ function runCli(args, io) {
     if (command === "dev") {
         return runDev(args.slice(1), 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;
@@ -77,11 +85,187 @@ function usage() {
         "  nexus-plugin create <plugin-id> [--template minimal|sqlite] [--output <parent-directory>]",
         "    [--display-name <name>] [--sdk-source <version-or-local-tgz>] [--install]",
         "  nexus-plugin dev [plugin-project-directory] [--no-build] [--inspect[=<port>] | --inspect-brk[=<port>]]",
+        "    [--host-version <X.Y.Z>] [--language <culture>] [--theme system|light|dark] [--surface business|tool|settings]",
+        "    [--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>] [--no-devtools]"
+        "    [--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());
+        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,
+        build: true,
+        openBrowser: true,
+        port: 4173
+    };
+    const seen = new Set();
+    for (; index < args.length; index += 1) {
+        const option = args[index];
+        if (option === "--no-build" || option === "--no-open") {
+            if (seen.has(option)) {
+                return usageError(io, "Duplicate option: " + option);
+            }
+            seen.add(option);
+            if (option === "--no-build") {
+                options.build = false;
+            }
+            else {
+                options.openBrowser = false;
+            }
+            continue;
+        }
+        if (!["--port", "--language", "--theme", "--surface", "--contribution-id"].includes(option)) {
+            return usageError(io, "Unknown dev:web 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 === "--port") {
+            const port = Number(value);
+            if (!Number.isInteger(port) || port < 1 || port > 65535) {
+                return usageError(io, "port must be an integer from 1 to 65535.");
+            }
+            options.port = port;
+        }
+        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;
+        }
+    }
+    try {
+        return (0, web_dev_1.runPluginWebDev)(options, io);
+    }
+    catch (error) {
+        if (error instanceof dev_1.PluginDevError) {
+            io.stderr(error.message);
+            return error.exitCode;
+        }
+        io.stderr("Plugin browser dev host failed: " + (error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+}
 function runDev(args, io) {
     if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
         io.stdout(usage());
@@ -131,7 +315,7 @@ function runDev(args, io) {
             options.inspectorPort = inspector.port;
             continue;
         }
-        if (!["--language", "--theme", "--surface", "--contribution-id"].includes(option)) {
+        if (!["--host-version", "--language", "--theme", "--surface", "--contribution-id"].includes(option)) {
             return usageError(io, "Unknown dev option: " + option);
         }
         if (seen.has(option)) {
@@ -143,7 +327,13 @@ function runDev(args, io) {
             return usageError(io, option + " requires a value.");
         }
         index += 1;
-        if (option === "--language") {
+        if (option === "--host-version") {
+            if (!isStrictVersion(value)) {
+                return usageError(io, "host-version must use X.Y.Z format.");
+            }
+            options.hostVersion = value;
+        }
+        else if (option === "--language") {
             options.language = value;
         }
         else if (option === "--theme") {
@@ -185,6 +375,10 @@ function parseInspectorOption(option) {
     }
     return { mode: match[1], port };
 }
+function isStrictVersion(value) {
+    const match = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.exec(value);
+    return Boolean(match && [match[1], match[2], match[3]].every((segment) => Number.isSafeInteger(Number(segment))));
+}
 function runCreate(args, io) {
     if (args.length === 0 || args[0].startsWith("--")) {
         return usageError(io, "create requires a plugin-id.");