@aiot-nexus/plugin-sdk 1.0.0

package/templates/minimal/src/renderer/app.ts.tmpl

@@ -0,0 +1,194 @@
+import { createPluginFrameClient } from "@aiot-nexus/plugin-sdk/browser";
+
+interface EchoResponse {
+  value: string;
+  echoedAt: string;
+}
+
+type SupportedLanguage = "en-US" | "zh-CN";
+
+const englishMessages = {
+  "document.title": "Plugin Echo",
+  "heading.echo": "Echo",
+  "section.request": "Request",
+  "field.value": "Value",
+  "action.send": "Send",
+  "result.response": "Response",
+  "status.connecting": "Connecting",
+  "status.waiting": "Waiting",
+  "status.ready": "Ready",
+  "status.sending": "Sending",
+  "status.error": "Error",
+  "validation.enterValue": "Enter a value.",
+  "surface.business": "Business",
+  "surface.tool": "Tool",
+  "surface.settings": "Settings"
+} as const;
+
+type MessageKey = keyof typeof englishMessages;
+
+const messages: Record<SupportedLanguage, Record<MessageKey, string>> = {
+  "en-US": englishMessages,
+  "zh-CN": {
+    "document.title": "插件回显",
+    "heading.echo": "回显",
+    "section.request": "请求",
+    "field.value": "内容",
+    "action.send": "发送",
+    "result.response": "响应",
+    "status.connecting": "正在连接",
+    "status.waiting": "等待中",
+    "status.ready": "已就绪",
+    "status.sending": "正在发送",
+    "status.error": "错误",
+    "validation.enterValue": "请输入内容。",
+    "surface.business": "业务",
+    "surface.tool": "工具",
+    "surface.settings": "设置"
+  }
+};
+
+type OutputState =
+  | { kind: "message"; key: MessageKey }
+  | { kind: "literal"; value: string };
+
+const client = createPluginFrameClient();
+const input = requireElement<HTMLInputElement>("echoInput");
+const button = requireElement<HTMLButtonElement>("echoButton");
+const resultOutput = requireElement<HTMLOutputElement>("echoResult");
+const contextOutput = requireElement<HTMLElement>("pluginContext");
+const connectionState = requireElement<HTMLElement>("connectionState");
+
+let language: SupportedLanguage = "en-US";
+let pluginId = "";
+let surface = "";
+let connectionStateKey: MessageKey = "status.waiting";
+let outputState: OutputState = { kind: "message", key: "status.waiting" };
+
+button.addEventListener("click", () => {
+  void echoValue();
+});
+input.addEventListener("keydown", (event) => {
+  if (event.key === "Enter") {
+    event.preventDefault();
+    void echoValue();
+  }
+});
+const stopContextUpdates = client.onContextChanged((context) => {
+  pluginId = context.pluginId;
+  surface = context.surface;
+  applyLanguage(resolveLanguage(context.language));
+});
+window.addEventListener("beforeunload", () => {
+  stopContextUpdates();
+  client.dispose();
+});
+
+applyLanguage(language);
+
+void client.waitForContext().then((context) => {
+  pluginId = context.pluginId;
+  surface = context.surface;
+  connectionStateKey = "status.ready";
+  applyLanguage(resolveLanguage(context.language));
+}).catch((error: unknown) => {
+  connectionStateKey = "status.error";
+  outputState = { kind: "literal", value: errorMessage(error) };
+  renderLocalizedState();
+});
+
+async function echoValue(): Promise<void> {
+  const value = input.value.trim();
+  if (!value) {
+    setOutputMessage("validation.enterValue");
+    return;
+  }
+  button.disabled = true;
+  setConnectionState("status.sending");
+  try {
+    const result = await client.invokeMain<Record<string, unknown>, EchoResponse>("demo.echo", { value });
+    if (!result.ok) {
+      setOutputLiteral(result.error.code + ": " + result.error.message);
+      return;
+    }
+    setOutputLiteral(result.value.value + " (" + result.value.echoedAt + ")");
+  } catch (error: unknown) {
+    setOutputLiteral(errorMessage(error));
+  } finally {
+    button.disabled = false;
+    setConnectionState("status.ready");
+  }
+}
+
+function applyLanguage(nextLanguage: SupportedLanguage): void {
+  language = nextLanguage;
+  document.documentElement.lang = language;
+  document.querySelectorAll<HTMLElement>("[data-i18n]").forEach((element) => {
+    const key = element.dataset.i18n;
+    if (key && isMessageKey(key)) {
+      element.textContent = text(key);
+    }
+  });
+  renderLocalizedState();
+  client.notifyResize();
+}
+
+function renderLocalizedState(): void {
+  contextOutput.textContent = pluginId
+    ? pluginId + " / " + localizedSurface(surface)
+    : text("status.connecting");
+  connectionState.textContent = text(connectionStateKey);
+  resultOutput.textContent = outputState.kind === "message" ? text(outputState.key) : outputState.value;
+}
+
+function setConnectionState(key: MessageKey): void {
+  connectionStateKey = key;
+  connectionState.textContent = text(key);
+}
+
+function setOutputMessage(key: MessageKey): void {
+  outputState = { kind: "message", key };
+  resultOutput.textContent = text(key);
+}
+
+function setOutputLiteral(value: string): void {
+  outputState = { kind: "literal", value };
+  resultOutput.textContent = value;
+}
+
+function localizedSurface(value: string): string {
+  if (value === "business") {
+    return text("surface.business");
+  }
+  if (value === "tool") {
+    return text("surface.tool");
+  }
+  if (value === "settings") {
+    return text("surface.settings");
+  }
+  return value;
+}
+
+function resolveLanguage(value: string): SupportedLanguage {
+  return value.toLowerCase().startsWith("zh") ? "zh-CN" : "en-US";
+}
+
+function text(key: MessageKey): string {
+  return messages[language][key];
+}
+
+function isMessageKey(value: string): value is MessageKey {
+  return Object.prototype.hasOwnProperty.call(englishMessages, value);
+}
+
+function requireElement<T extends HTMLElement>(id: string): T {
+  const element = document.getElementById(id);
+  if (!element) {
+    throw new Error("Required element is missing: " + id);
+  }
+  return element as T;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/templates/minimal/src/renderer/index.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en-US">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title data-i18n="document.title">Plugin Echo</title>
+    <link rel="stylesheet" href="assets/plugin.css">
+  </head>
+  <body>
+    <main class="plugin-shell">
+      <header class="plugin-header">
+        <div>
+          <h1 data-i18n="heading.echo">Echo</h1>
+          <p id="pluginContext" data-i18n="status.connecting">Connecting</p>
+        </div>
+        <span id="connectionState" class="status" data-i18n="status.waiting">Waiting</span>
+      </header>
+
+      <section class="echo-panel" aria-labelledby="echoTitle">
+        <h2 id="echoTitle" data-i18n="section.request">Request</h2>
+        <div class="echo-controls">
+          <label for="echoInput" data-i18n="field.value">Value</label>
+          <input id="echoInput" type="text" maxlength="200" autocomplete="off" value="Hello Nexus">
+          <button id="echoButton" type="button" data-i18n="action.send">Send</button>
+        </div>
+        <div class="result-row">
+          <span data-i18n="result.response">Response</span>
+          <output id="echoResult" data-i18n="status.waiting">Waiting</output>
+        </div>
+      </section>
+    </main>
+    <script type="module" src="assets/app.js"></script>
+  </body>
+</html>

package/templates/minimal/src/renderer/plugin.css

@@ -0,0 +1,164 @@
+:root {
+  color-scheme: light dark;
+  font-family: "Segoe UI", Arial, sans-serif;
+  background: #f3f5f7;
+  color: #20252b;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 0;
+  background: #f3f5f7;
+}
+
+.plugin-shell {
+  display: grid;
+  gap: 12px;
+  padding: 16px;
+}
+
+.plugin-header,
+.echo-panel {
+  border: 1px solid #d4d9df;
+  border-radius: 8px;
+  background: #ffffff;
+}
+
+.plugin-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 14px 16px;
+}
+
+h1,
+h2,
+p {
+  margin: 0;
+}
+
+h1 {
+  font-size: 22px;
+}
+
+h2 {
+  font-size: 15px;
+}
+
+p,
+.result-row > span {
+  margin-top: 4px;
+  color: #65717e;
+  font-size: 12px;
+}
+
+.status {
+  color: #12663f;
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.echo-panel {
+  padding: 16px;
+}
+
+.echo-controls {
+  display: grid;
+  grid-template-columns: auto minmax(160px, 1fr) auto;
+  gap: 10px;
+  align-items: center;
+  margin-top: 12px;
+}
+
+label {
+  font-size: 13px;
+  font-weight: 600;
+}
+
+input {
+  min-width: 0;
+  height: 36px;
+  border: 1px solid #aeb7c2;
+  border-radius: 6px;
+  padding: 0 10px;
+  background: #ffffff;
+  color: #20252b;
+  font: inherit;
+}
+
+button {
+  height: 36px;
+  border: 1px solid #1768a6;
+  border-radius: 6px;
+  padding: 0 16px;
+  background: #1768a6;
+  color: #ffffff;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+button:disabled {
+  cursor: default;
+  opacity: 0.55;
+}
+
+.result-row {
+  display: grid;
+  grid-template-columns: 80px minmax(0, 1fr);
+  gap: 10px;
+  margin-top: 14px;
+  border-top: 1px solid #e7eaee;
+  padding-top: 12px;
+}
+
+output {
+  overflow-wrap: anywhere;
+  font-family: Consolas, monospace;
+  font-size: 12px;
+}
+
+@media (max-width: 560px) {
+  .echo-controls,
+  .result-row {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (prefers-color-scheme: dark) {
+  :root,
+  body {
+    background: #16191d;
+    color: #edf0f2;
+  }
+
+  .plugin-header,
+  .echo-panel {
+    border-color: #454b52;
+    background: #24282d;
+  }
+
+  p,
+  .result-row > span {
+    color: #aeb7c2;
+  }
+
+  input {
+    border-color: #59616a;
+    background: #191c20;
+    color: #edf0f2;
+  }
+
+  .result-row {
+    border-top-color: #454b52;
+  }
+
+  .status {
+    color: #75d6a5;
+  }
+}

package/templates/minimal/tsconfig.main.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2020"],
+    "rootDir": "src",
+    "outDir": ".build/main",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/main.ts"]
+}

package/templates/minimal/tsconfig.renderer.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "lib": ["ES2020", "DOM"],
+    "baseUrl": ".",
+    "paths": {
+      "@aiot-nexus/plugin-sdk/browser": ["node_modules/@aiot-nexus/plugin-sdk/dist/browser/frame-client.d.ts"]
+    },
+    "rootDir": "src/renderer",
+    "outDir": ".build/renderer",
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/renderer/app.ts"]
+}

package/templates/sqlite/.gitignore.tmpl

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.build/
+.nexus-plugin-dev/

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

@@ -0,0 +1,22 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Nexus plugin",
+      "type": "node-terminal",
+      "request": "launch",
+      "command": "npm run dev:debug",
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "name": "Attach Nexus plugin main (9229)",
+      "type": "node",
+      "request": "attach",
+      "address": "127.0.0.1",
+      "port": 9229,
+      "sourceMaps": true,
+      "outFiles": ["${workspaceFolder}/dist/**/*.cjs"],
+      "skipFiles": ["<node_internals>/**"]
+    }
+  ]
+}

package/templates/sqlite/README.md.tmpl

@@ -0,0 +1,22 @@
+# __DISPLAY_NAME_MARKDOWN__
+
+AIoT Nexus independent PluginFrame plugin generated from the `sqlite` template.
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm run dev
+```
+
+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 renderer follows `context.language` from Nexus, subscribes to in-place context updates without reloading the iframe, and includes `en-US` and `zh-CN` message catalogs. 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.
+
+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.
+
+The independent host stores the SQLite database and settings under `.nexus-plugin-dev/data/` and mirrors the PluginFrame protocol and current Host API surface. 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/scripts/build.js.tmpl

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const ts = require("typescript");
+
+const pluginId = "__PLUGIN_ID__";
+const pluginRoot = path.resolve(__dirname, "..");
+const buildDirectory = path.join(pluginRoot, ".build");
+const outputDirectory = path.join(pluginRoot, "dist", pluginId);
+const nodeModulesDirectory = path.join(pluginRoot, "node_modules");
+const sdkModuleSpecifier = "@aiot-nexus/plugin-sdk/browser";
+const runtimePackages = ["better-sqlite3", "bindings", "file-uri-to-path"];
+
+run();
+
+function run() {
+  verifyNativeDependency();
+  fs.rmSync(buildDirectory, { recursive: true, force: true });
+  fs.rmSync(outputDirectory, { recursive: true, force: true });
+  runTypeScript("tsconfig.main.json");
+  runTypeScript("tsconfig.renderer.json");
+
+  fs.mkdirSync(path.join(outputDirectory, "renderer", "assets"), { recursive: true });
+  fs.copyFileSync(path.join(pluginRoot, "src", "manifest.json"), path.join(outputDirectory, "manifest.json"));
+  fs.copyFileSync(path.join(buildDirectory, "main", "main.js"), path.join(outputDirectory, "main.cjs"));
+  fs.copyFileSync(path.join(pluginRoot, "src", "renderer", "index.html"), path.join(outputDirectory, "renderer", "index.html"));
+  fs.copyFileSync(path.join(pluginRoot, "src", "renderer", "plugin.css"), path.join(outputDirectory, "renderer", "assets", "plugin.css"));
+  rewriteRendererSdkImport(
+    path.join(buildDirectory, "renderer", "app.js"),
+    path.join(outputDirectory, "renderer", "assets", "app.js")
+  );
+  copyBrowserSdk();
+  for (const packageName of runtimePackages) {
+    copyRuntimePackage(packageName);
+  }
+  fs.rmSync(buildDirectory, { recursive: true, force: true });
+  console.log("[" + pluginId + "] built " + outputDirectory);
+}
+
+function verifyNativeDependency() {
+  const packageDirectory = path.join(nodeModulesDirectory, "better-sqlite3");
+  if (!fs.existsSync(packageDirectory)) {
+    throw new Error("better-sqlite3 is not installed. Run npm install first.");
+  }
+  const nativeFiles = findFiles(packageDirectory, function isNativeAddon(filePath) {
+    return path.basename(filePath).toLowerCase() === "better_sqlite3.node";
+  });
+  if (nativeFiles.length === 0) {
+    throw new Error("better-sqlite3 is not rebuilt. Run npm run rebuild:native first.");
+  }
+}
+
+function runTypeScript(configName) {
+  const tscPath = require.resolve("typescript/bin/tsc");
+  const args = [tscPath, "-p", path.join(pluginRoot, configName)];
+  if (process.env.NEXUS_PLUGIN_DEV === "1") {
+    args.push("--inlineSourceMap", "--inlineSources");
+  }
+  const result = spawnSync(process.execPath, args, {
+    cwd: pluginRoot,
+    stdio: "inherit"
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    process.exit(result.status || 1);
+  }
+}
+
+function rewriteRendererSdkImport(sourcePath, outputPath) {
+  const sourceText = fs.readFileSync(sourcePath, "utf8");
+  const sourceFile = ts.createSourceFile(sourcePath, sourceText, ts.ScriptTarget.ES2020, true, ts.ScriptKind.JS);
+  const matches = [];
+  sourceFile.forEachChild(function findSdkImport(node) {
+    if (ts.isImportDeclaration(node)
+      && ts.isStringLiteral(node.moduleSpecifier)
+      && node.moduleSpecifier.text === sdkModuleSpecifier) {
+      matches.push(node.moduleSpecifier);
+    }
+  });
+  if (matches.length !== 1) {
+    throw new Error("Expected one browser SDK import, found " + matches.length + ".");
+  }
+  const moduleSpecifier = matches[0];
+  const rewritten = sourceText.slice(0, moduleSpecifier.getStart(sourceFile))
+    + JSON.stringify("./plugin-sdk.mjs")
+    + sourceText.slice(moduleSpecifier.getEnd());
+  fs.writeFileSync(outputPath, rewritten, "utf8");
+}
+
+function copyBrowserSdk() {
+  const sdkPackageRoot = path.dirname(require.resolve("@aiot-nexus/plugin-sdk/package.json"));
+  const sourcePath = path.join(sdkPackageRoot, "dist", "browser", "frame-client.mjs");
+  if (!fs.existsSync(sourcePath)) {
+    throw new Error("Plugin SDK browser module is missing: " + sourcePath);
+  }
+  fs.copyFileSync(sourcePath, path.join(outputDirectory, "renderer", "assets", "plugin-sdk.mjs"));
+}
+
+function copyRuntimePackage(packageName) {
+  const sourcePath = path.join(nodeModulesDirectory, packageName);
+  if (!fs.existsSync(sourcePath)) {
+    throw new Error("Runtime package is missing: " + packageName);
+  }
+  copyDirectory(sourcePath, path.join(outputDirectory, "node_modules", packageName));
+}
+
+function copyDirectory(sourceDirectory, targetDirectory) {
+  fs.mkdirSync(targetDirectory, { recursive: true });
+  for (const entry of fs.readdirSync(sourceDirectory, { withFileTypes: true })) {
+    const sourcePath = path.join(sourceDirectory, entry.name);
+    const targetPath = path.join(targetDirectory, entry.name);
+    if (entry.isSymbolicLink()) {
+      throw new Error("Runtime package contains an unsupported symbolic link: " + sourcePath);
+    }
+    if (entry.isDirectory()) {
+      copyDirectory(sourcePath, targetPath);
+      continue;
+    }
+    if (entry.isFile()) {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+  }
+}
+
+function findFiles(directory, predicate) {
+  const results = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const filePath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      results.push.apply(results, findFiles(filePath, predicate));
+      continue;
+    }
+    if (entry.isFile() && predicate(filePath)) {
+      results.push(filePath);
+    }
+  }
+  return results;
+}

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

@@ -0,0 +1,22 @@
+declare module "better-sqlite3" {
+  class Database {
+    constructor(filename: string);
+    pragma(source: string): unknown;
+    prepare(source: string): Database.Statement;
+  }
+
+  namespace Database {
+    interface RunResult {
+      changes: number;
+      lastInsertRowid: number | bigint;
+    }
+
+    interface Statement {
+      run(...params: unknown[]): RunResult;
+      get(...params: unknown[]): unknown;
+      all(...params: unknown[]): unknown[];
+    }
+  }
+
+  export = Database;
+}