npm - @aiot-nexus/plugin-sdk - Versions diffs - 1.0.0 - Mend

@aiot-nexus/plugin-sdk 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (47) hide show

package/README.md +74 -0
package/dev-host/host.html +344 -0
package/dev-host/main.js +694 -0
package/dev-host/preload.js +22 -0
package/dist/.generated/plugin-framework-version.d.ts +11 -0
package/dist/.generated/plugin-framework-version.js +39 -0
package/dist/.generated/plugin-manifest.schema.json +106 -0
package/dist/browser/frame-client.d.ts +26 -0
package/dist/browser/frame-client.mjs +239 -0
package/dist/src/browser/frame-client.d.ts +26 -0
package/dist/src/browser/frame-client.js +244 -0
package/dist/src/cli/run.d.ts +7 -0
package/dist/src/cli/run.js +270 -0
package/dist/src/cli.d.ts +2 -0
package/dist/src/cli.js +9 -0
package/dist/src/dev.d.ts +36 -0
package/dist/src/dev.js +224 -0
package/dist/src/index.d.ts +7 -0
package/dist/src/index.js +27 -0
package/dist/src/scaffold.d.ts +23 -0
package/dist/src/scaffold.js +306 -0
package/dist/src/types.d.ts +142 -0
package/dist/src/types.js +2 -0
package/dist/src/validation.d.ts +9 -0
package/dist/src/validation.js +160 -0
package/package.json +47 -0
package/templates/minimal/.gitignore.tmpl +4 -0
package/templates/minimal/.vscode/launch.json +22 -0
package/templates/minimal/README.md.tmpl +22 -0
package/templates/minimal/scripts/build.js.tmpl +83 -0
package/templates/minimal/src/main.ts.tmpl +23 -0
package/templates/minimal/src/renderer/app.ts.tmpl +194 -0
package/templates/minimal/src/renderer/index.html +34 -0
package/templates/minimal/src/renderer/plugin.css +164 -0
package/templates/minimal/tsconfig.main.json +15 -0
package/templates/minimal/tsconfig.renderer.json +17 -0
package/templates/sqlite/.gitignore.tmpl +4 -0
package/templates/sqlite/.vscode/launch.json +22 -0
package/templates/sqlite/README.md.tmpl +22 -0
package/templates/sqlite/scripts/build.js.tmpl +143 -0
package/templates/sqlite/src/better-sqlite3.d.ts +22 -0
package/templates/sqlite/src/main.ts.tmpl +190 -0
package/templates/sqlite/src/renderer/app.ts.tmpl +428 -0
package/templates/sqlite/src/renderer/index.html +57 -0
package/templates/sqlite/src/renderer/plugin.css +275 -0
package/templates/sqlite/tsconfig.main.json +15 -0
package/templates/sqlite/tsconfig.renderer.json +17 -0

package/README.md ADDED Viewed

@@ -0,0 +1,74 @@
+# @aiot-nexus/plugin-sdk
+AIoT Nexus 独立插件开发包，包含公开 TypeScript 契约、PluginFrame 浏览器客户端和 `nexus-plugin` 命令行工具。
+## 环境
+- Node.js `>=16.20.0 <17`
+- npm `>=6.13.4`
+- 插件框架 API `1.0.0`
+- manifest schema `1`
+## 命令
+```bash
+npm run build
+npm test
+npm run pack: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]
+```
+`npm run pack:sdk` 将离线安装包写入 `package/`。该目录是本地构建产物，不进入 Git。
+## 创建插件
+```bash
+nexus-plugin create my-frame-plugin \
+  --template minimal \
+  --output . \
+  --display-name "My Frame Plugin" \
+  --sdk-source /path/to/aiot-nexus-plugin-sdk-1.0.0.tgz
+```
+- `--template` 默认为 `minimal`，也可选择带 `better-sqlite3` 的 `sqlite`。
+- `--output` 默认为当前目录，目标固定为 `<output>/<plugin-id>`。
+- `--sdk-source` 为必填项，接受严格的 `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 使用相同文化资源本地化宿主入口。
+当前 SDK 不发布到远程 registry。必须先执行 `npm run pack:sdk`，再把生成的 `.tgz` 路径传给 `--sdk-source`；CLI 不会默认写入当前无法安装的远程版本，并会把本地包一并放入生成工程。未来发布后可改用严格的 `X.Y.Z` 版本。
+## 独立调试
+生成工程安装依赖后，可以完全在插件目录启动调试宿主：
+```bash
+npm run dev
+npm run dev:debug
+```
+- `npm run dev` 先构建和校验插件，再使用工程本地固定的 `electron@22.3.27` 启动 SDK 调试宿主；Renderer DevTools 默认自动打开。
+- `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` 不内联源码，不改变部署制品形态。
+- 调试数据保存在工程的 `.nexus-plugin-dev/`，该目录默认被忽略。关闭调试窗口会结束独立 Electron 进程；修改源码后重新运行调试命令。
+可直接使用的 CLI 选项：
+```text
+nexus-plugin dev [plugin-project-directory]
+  [--no-build]
+  [--inspect[=<port>] | --inspect-brk[=<port>]]
+  [--language <culture>]
+  [--theme system|light|dark]
+  [--surface business|tool|settings]
+  [--contribution-id <id>]
+  [--no-devtools]
+```
+调试宿主复用正式的 `nexus-plugin://` 资源协议、iframe sandbox、CSP、消息结构、operation 校验以及当前 Host API 权限语义，但不包含 Nexus 的完整页面路由、Pinia 状态和应用级功能。交付前仍需把 `dist/<plugin-id>/` 放入正式 Nexus 完成集成验证。

package/dev-host/host.html ADDED Viewed

@@ -0,0 +1,344 @@
+<!doctype html>
+<html lang="en-US">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Nexus Plugin Dev</title>
+    <style>
+      :root {
+        color-scheme: light;
+        font-family: "Segoe UI", Arial, sans-serif;
+        letter-spacing: 0;
+        --page: #f4f5f7;
+        --surface: #ffffff;
+        --border: #cfd4dc;
+        --text: #20242a;
+        --muted: #5d6672;
+        --accent: #167451;
+      }
+      :root[data-theme="dark"] {
+        color-scheme: dark;
+        --page: #181a1d;
+        --surface: #22252a;
+        --border: #3e444d;
+        --text: #f2f4f7;
+        --muted: #aeb6c2;
+        --accent: #5fd0a2;
+      }
+      * {
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        width: 100%;
+        min-width: 0;
+        min-height: 100%;
+        margin: 0;
+        background: var(--page);
+        color: var(--text);
+      }
+      body {
+        display: flex;
+        flex-direction: column;
+      }
+      .toolbar {
+        position: sticky;
+        top: 0;
+        z-index: 1;
+        display: flex;
+        align-items: center;
+        min-height: 48px;
+        gap: 12px;
+        padding: 7px 12px;
+        border-bottom: 1px solid var(--border);
+        background: var(--surface);
+      }
+      .plugin-name {
+        min-width: 120px;
+        margin-right: auto;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+        font-size: 14px;
+      }
+      .control {
+        display: flex;
+        align-items: center;
+        gap: 6px;
+        color: var(--muted);
+        font-size: 12px;
+      }
+      select,
+      button {
+        min-height: 30px;
+        border: 1px solid var(--border);
+        border-radius: 4px;
+        background: var(--surface);
+        color: var(--text);
+        font: inherit;
+      }
+      select {
+        min-width: 104px;
+        padding: 3px 26px 3px 8px;
+      }
+      button {
+        padding: 3px 10px;
+        cursor: pointer;
+      }
+      button:hover {
+        border-color: var(--accent);
+      }
+      .status {
+        width: 86px;
+        overflow: hidden;
+        color: var(--muted);
+        font-size: 12px;
+        text-align: right;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+      .status[data-connected="true"] {
+        color: var(--accent);
+      }
+      .frame-shell {
+        flex: 1 1 auto;
+        min-width: 0;
+        padding: 12px;
+        overflow: auto;
+      }
+      iframe {
+        display: block;
+        width: 100%;
+        min-height: 360px;
+        border: 1px solid var(--border);
+        background: var(--surface);
+      }
+      @media (max-width: 760px) {
+        .toolbar {
+          align-items: stretch;
+          flex-wrap: wrap;
+        }
+        .plugin-name {
+          flex-basis: 100%;
+          width: 100%;
+        }
+        .status {
+          margin-left: auto;
+        }
+        .frame-shell {
+          padding: 8px;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <header class="toolbar">
+      <strong id="pluginName" class="plugin-name">Nexus Plugin Dev</strong>
+      <label class="control" for="languageSelect">
+        <span>Language</span>
+        <select id="languageSelect"></select>
+      </label>
+      <label class="control" for="themeSelect">
+        <span>Theme</span>
+        <select id="themeSelect">
+          <option value="system">System</option>
+          <option value="light">Light</option>
+          <option value="dark">Dark</option>
+        </select>
+      </label>
+      <button id="reloadButton" type="button">Reload frame</button>
+      <span id="status" class="status" data-connected="false">Waiting</span>
+    </header>
+    <main class="frame-shell">
+      <iframe id="pluginFrame" sandbox="allow-scripts allow-same-origin" title="Plugin renderer"></iframe>
+    </main>
+    <script>
+      "use strict";
+      var api = window.nexusPluginDevHost;
+      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 configuration;
+      var context;
+      var initialized = false;
+      var smokeReported = false;
+      var resizeSeen = false;
+      var pendingRequests = 0;
+      var smokeTimer;
+      window.addEventListener("message", handleMessage);
+      languageSelect.addEventListener("change", updateContext);
+      themeSelect.addEventListener("change", updateContext);
+      reloadButton.addEventListener("click", reloadFrame);
+      window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", applyTheme);
+      api.getConfig().then(function initialize(value) {
+        configuration = value;
+        context = value.context;
+        document.title = value.pluginId + " - Nexus Plugin Dev";
+        pluginName.textContent = value.pluginId;
+        iframe.title = value.pluginId;
+        populateLanguages(value.supportedCultures, context.language);
+        themeSelect.value = context.themeMode;
+        applyTheme();
+        iframe.src = value.frameUrl;
+      }).catch(function reportInitializationFailure(error) {
+        setStatus("Host error", false);
+        console.error(error);
+      });
+      function handleMessage(event) {
+        if (!configuration || event.source !== iframe.contentWindow || event.origin !== configuration.frameOrigin) {
+          return;
+        }
+        var message = event.data;
+        if (!message || typeof message !== "object") {
+          return;
+        }
+        if (message.type === "nexus-plugin:ready") {
+          initialized = true;
+          postToFrame({ type: "nexus-plugin:init", context: context });
+          setStatus("Connected", true);
+          return;
+        }
+        if (message.type === "nexus-plugin:resize" && typeof message.height === "number") {
+          iframe.style.height = Math.min(6000, Math.max(160, Math.ceil(message.height))) + "px";
+          resizeSeen = true;
+          scheduleSmokeReport();
+          return;
+        }
+        if (message.type !== "nexus-plugin:request" || typeof message.requestId !== "string" || typeof message.method !== "string") {
+          return;
+        }
+        if (message.method === "getContext") {
+          respond(message.requestId, { ok: true, value: context });
+          return;
+        }
+        pendingRequests += 1;
+        cancelSmokeReport();
+        api.invoke({ method: message.method, params: message.params }).then(function sendResult(result) {
+          respond(message.requestId, result);
+        }, function sendFailure(error) {
+          respond(message.requestId, {
+            ok: false,
+            error: { code: "UnexpectedFailure", message: error instanceof Error ? error.message : String(error) }
+          });
+        }).then(function finishRequest() {
+          pendingRequests -= 1;
+          scheduleSmokeReport();
+        });
+      }
+      function updateContext() {
+        if (!context) {
+          return;
+        }
+        context = Object.assign({}, context, {
+          language: languageSelect.value,
+          themeMode: themeSelect.value
+        });
+        applyTheme();
+        if (initialized) {
+          postToFrame({ type: "nexus-plugin:context-changed", context: context });
+        }
+      }
+      function reloadFrame() {
+        if (!configuration) {
+          return;
+        }
+        initialized = false;
+        smokeReported = false;
+        resizeSeen = false;
+        pendingRequests = 0;
+        cancelSmokeReport();
+        setStatus("Waiting", false);
+        iframe.src = "about:blank";
+        window.setTimeout(function restoreFrame() {
+          iframe.src = configuration.frameUrl;
+        }, 0);
+      }
+      function populateLanguages(cultures, selected) {
+        languageSelect.replaceChildren();
+        var values = Array.isArray(cultures) && cultures.length > 0 ? cultures : [selected];
+        values.forEach(function appendCulture(culture) {
+          var option = document.createElement("option");
+          option.value = culture;
+          option.textContent = culture;
+          languageSelect.appendChild(option);
+        });
+        if (!values.includes(selected)) {
+          var option = document.createElement("option");
+          option.value = selected;
+          option.textContent = selected;
+          languageSelect.appendChild(option);
+        }
+        languageSelect.value = selected;
+      }
+      function applyTheme() {
+        var mode = context ? context.themeMode : "system";
+        var dark = mode === "dark" || (mode === "system" && window.matchMedia("(prefers-color-scheme: dark)").matches);
+        document.documentElement.dataset.theme = dark ? "dark" : "light";
+      }
+      function respond(requestId, result) {
+        postToFrame({ type: "nexus-plugin:response", requestId: requestId, result: result });
+      }
+      function postToFrame(message) {
+        iframe.contentWindow && iframe.contentWindow.postMessage(message, configuration.frameOrigin);
+      }
+      function setStatus(text, connected) {
+        status.textContent = text;
+        status.dataset.connected = connected ? "true" : "false";
+      }
+      function scheduleSmokeReport() {
+        if (!configuration || !configuration.smoke || !initialized || !resizeSeen || smokeReported || pendingRequests !== 0) {
+          return;
+        }
+        cancelSmokeReport();
+        smokeTimer = window.setTimeout(function reportStableFrame() {
+          smokeTimer = undefined;
+          if (!smokeReported && pendingRequests === 0) {
+            smokeReported = true;
+            api.notifyFrameReady();
+          }
+        }, 300);
+      }
+      function cancelSmokeReport() {
+        if (smokeTimer !== undefined) {
+          window.clearTimeout(smokeTimer);
+          smokeTimer = undefined;
+        }
+      }
+    </script>
+  </body>
+</html>