@aiot-nexus/plugin-sdk 1.0.0

package/dist/src/types.d.ts

@@ -0,0 +1,142 @@
+export interface NexusError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export type NexusResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: NexusError;
+};
+export type ThemeMode = "light" | "dark" | "system";
+export type LaunchPageParams = Record<string, string>;
+export type PluginPermission = "businessLog" | "settings" | "filesystem" | "udp" | "serial" | "externalProcess" | "dialog";
+export type PluginPermissionSupportState = "implemented" | "routeGuard" | "reserved";
+export interface PluginPermissionSummary {
+    permission: PluginPermission;
+    supportState: PluginPermissionSupportState;
+    statusMessage: string;
+}
+export interface BusinessDescriptor {
+    businessId: string;
+    titleKey: string;
+    iconKey: string;
+    section: string;
+    order: number;
+    component: string;
+    descriptionKey?: string;
+    pageRoute?: string;
+    isFullBleed?: boolean;
+    showBusinessLogToggle?: boolean;
+}
+export interface ToolDescriptor {
+    toolId: string;
+    titleKey: string;
+    iconKey: string;
+    navGroup: string;
+    order: number;
+    component: string;
+    descriptionKey?: string;
+}
+export interface SettingsSectionDescriptor {
+    sectionId: string;
+    titleKey: string;
+    order: number;
+    component: string;
+    descriptionKey?: string;
+}
+export interface PluginManifest {
+    schemaVersion: number;
+    pluginId: string;
+    displayNameKey: string;
+    descriptionKey: string;
+    pluginVersion: string;
+    hostApiVersion: string;
+    minHostVersion: string;
+    supportedCultures: string[];
+    permissions: PluginPermission[];
+    mainEntry?: string;
+    rendererEntry?: string;
+    businessEntries?: BusinessDescriptor[];
+    tools?: ToolDescriptor[];
+    settingsSections?: SettingsSectionDescriptor[];
+    resources?: Record<string, Record<string, string>>;
+    deferred?: boolean;
+}
+export type PluginRendererSurface = "business" | "tool" | "settings";
+export type PluginRendererMethod = "getContext" | "getSettings" | "updateSettings" | "appendLog" | "invokeMain";
+export interface PluginRendererContext {
+    schemaVersion: number;
+    pluginId: string;
+    surface: PluginRendererSurface;
+    contributionId: string;
+    launchParams?: LaunchPageParams;
+    language: string;
+    themeMode: ThemeMode;
+    hostApiVersion: string;
+}
+export interface PluginSettingsDocument {
+    schemaVersion: number;
+    pluginId: string;
+    values: Record<string, unknown>;
+}
+export interface BusinessLogEntry {
+    timestamp: string;
+    level: "debug" | "info" | "warn" | "error";
+    category: string;
+    message: string;
+    exception?: string;
+}
+export interface BusinessLogAppendRequest {
+    level: BusinessLogEntry["level"];
+    message: string;
+    category?: string;
+    exception?: string;
+}
+export interface PluginRendererOperationRequest<TInput extends Record<string, unknown> = Record<string, unknown>> {
+    readonly pluginId: string;
+    readonly surface: PluginRendererSurface;
+    readonly contributionId: string;
+    readonly operation: string;
+    readonly input?: TInput;
+}
+export type PluginRendererOperationHandler<TInput extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = (request: PluginRendererOperationRequest<TInput>) => NexusResult<TResult> | TResult;
+export interface PluginUnsupportedCapabilityApi {
+    readonly permission: PluginPermission;
+    readonly supportState: PluginPermissionSupportState;
+    describe(): NexusResult<PluginPermissionSummary>;
+    unsupported(operation?: unknown): NexusResult<never>;
+    [operation: string]: unknown;
+}
+export interface PluginHostApi {
+    readonly hostVersion: string;
+    readonly hostApiVersion: string;
+    readonly pluginId: string;
+    readonly pluginDataDirectory: string;
+    hasPermission(permission: PluginPermission): boolean;
+    registerRendererMethod(name: string, handler: PluginRendererOperationHandler): NexusResult<boolean>;
+    getCapabilityStatus(permission: unknown): NexusResult<PluginPermissionSummary>;
+    unsupportedCapability(permission: unknown, operation?: unknown): NexusResult<never>;
+    log(level: BusinessLogEntry["level"], message: string, exception?: string): NexusResult<BusinessLogEntry>;
+    getSettings(): NexusResult<PluginSettingsDocument>;
+    updateSettings(values: Record<string, unknown>): NexusResult<PluginSettingsDocument>;
+    filesystem: PluginUnsupportedCapabilityApi;
+    udp: PluginUnsupportedCapabilityApi;
+    serial: PluginUnsupportedCapabilityApi;
+    dialog: PluginUnsupportedCapabilityApi;
+    externalProcess: PluginUnsupportedCapabilityApi;
+}
+export interface PluginMainActivationContext {
+    readonly pluginId: string;
+    readonly pluginDirectory: string;
+    readonly manifest: PluginManifest;
+    readonly host: PluginHostApi;
+}
+export interface PluginMainModule {
+    activate?: (context: PluginMainActivationContext) => unknown;
+    default?: {
+        activate?: (context: PluginMainActivationContext) => unknown;
+    };
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/validation.d.ts

@@ -0,0 +1,9 @@
+import type { PluginManifest } from "./types";
+export interface PluginPackageValidationResult {
+    valid: boolean;
+    packageDirectory: string;
+    pluginId?: string;
+    manifest?: PluginManifest;
+    errors: string[];
+}
+export declare function validatePluginPackage(packageDirectory: string): PluginPackageValidationResult;

package/dist/src/validation.js

@@ -0,0 +1,160 @@
+"use strict";
+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;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePluginPackage = void 0;
+const _2020_1 = __importDefault(require("ajv/dist/2020"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const plugin_manifest_schema_json_1 = __importDefault(require("../.generated/plugin-manifest.schema.json"));
+const plugin_framework_version_1 = require("../.generated/plugin-framework-version");
+const manifestValidator = new _2020_1.default({ allErrors: true, strict: true })
+    .compile(plugin_manifest_schema_json_1.default);
+function validatePluginPackage(packageDirectory) {
+    const resolvedDirectory = path.resolve(packageDirectory);
+    try {
+        return validateResolvedPluginPackage(resolvedDirectory);
+    }
+    catch (error) {
+        return invalid(resolvedDirectory, "Plugin package could not be inspected: " + errorMessage(error));
+    }
+}
+exports.validatePluginPackage = validatePluginPackage;
+function validateResolvedPluginPackage(resolvedDirectory) {
+    const errors = [];
+    if (!fs.existsSync(resolvedDirectory)) {
+        return invalid(resolvedDirectory, "Plugin package directory does not exist.");
+    }
+    const directoryStat = fs.lstatSync(resolvedDirectory);
+    if (!directoryStat.isDirectory()) {
+        return invalid(resolvedDirectory, "Plugin package path is not a directory.");
+    }
+    if (directoryStat.isSymbolicLink()) {
+        return invalid(resolvedDirectory, "Plugin package directory cannot be a symbolic link.");
+    }
+    const manifestPath = path.join(resolvedDirectory, "manifest.json");
+    if (!fs.existsSync(manifestPath)) {
+        return invalid(resolvedDirectory, "manifest.json is missing.");
+    }
+    const manifestStat = fs.lstatSync(manifestPath);
+    if (!manifestStat.isFile() || manifestStat.isSymbolicLink()) {
+        return invalid(resolvedDirectory, "manifest.json must be a regular file and cannot be a symbolic link.");
+    }
+    if (!isPathInside(fs.realpathSync(resolvedDirectory), fs.realpathSync(manifestPath))) {
+        return invalid(resolvedDirectory, "manifest.json resolves outside the plugin package directory.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    }
+    catch (error) {
+        return invalid(resolvedDirectory, "manifest.json is not valid JSON: " + errorMessage(error));
+    }
+    if (!manifestValidator(parsed)) {
+        return {
+            valid: false,
+            packageDirectory: resolvedDirectory,
+            errors: formatAjvErrors(manifestValidator.errors)
+        };
+    }
+    const manifest = parsed;
+    if (!(0, plugin_framework_version_1.isPluginFrameworkVersionCompatible)(manifest.hostApiVersion, plugin_framework_version_1.PLUGIN_FRAMEWORK_VERSION)) {
+        errors.push("Plugin Framework API version is incompatible with " + plugin_framework_version_1.PLUGIN_FRAMEWORK_VERSION + ".");
+    }
+    if (!(0, plugin_framework_version_1.parsePluginCompatibleVersion)(manifest.minHostVersion)) {
+        errors.push("minHostVersion contains an unsupported numeric version.");
+    }
+    validateEntry(resolvedDirectory, "mainEntry", manifest.mainEntry, errors);
+    validateEntry(resolvedDirectory, "rendererEntry", manifest.rendererEntry, errors);
+    if (manifest.rendererEntry && path.extname(manifest.rendererEntry).toLowerCase() !== ".html") {
+        errors.push("rendererEntry must point to an HTML file.");
+    }
+    if (usesPluginFrame(manifest) && !manifest.rendererEntry) {
+        errors.push("PluginFrame contributions require rendererEntry.");
+    }
+    return {
+        valid: errors.length === 0,
+        packageDirectory: resolvedDirectory,
+        pluginId: manifest.pluginId,
+        manifest,
+        errors
+    };
+}
+function validateEntry(rootDirectory, fieldName, relativePath, errors) {
+    if (!relativePath) {
+        return;
+    }
+    if (path.isAbsolute(relativePath)) {
+        errors.push(fieldName + " must be relative to the plugin package directory.");
+        return;
+    }
+    const entryPath = path.resolve(rootDirectory, relativePath);
+    if (!isPathInside(rootDirectory, entryPath)) {
+        errors.push(fieldName + " escapes the plugin package directory.");
+        return;
+    }
+    if (!fs.existsSync(entryPath)) {
+        errors.push(fieldName + " does not exist: " + relativePath);
+        return;
+    }
+    const entryStat = fs.lstatSync(entryPath);
+    if (!entryStat.isFile()) {
+        errors.push(fieldName + " must point to a file: " + relativePath);
+        return;
+    }
+    if (entryStat.isSymbolicLink()) {
+        errors.push(fieldName + " cannot be a symbolic link: " + relativePath);
+        return;
+    }
+    if (!isPathInside(fs.realpathSync(rootDirectory), fs.realpathSync(entryPath))) {
+        errors.push(fieldName + " resolves outside the plugin package directory.");
+    }
+}
+function usesPluginFrame(manifest) {
+    return (manifest.businessEntries || []).some((entry) => entry.component === "PluginFrame")
+        || (manifest.tools || []).some((entry) => entry.component === "PluginFrame")
+        || (manifest.settingsSections || []).some((entry) => entry.component === "PluginFrame");
+}
+function isPathInside(rootDirectory, childPath) {
+    const relative = path.relative(path.resolve(rootDirectory), path.resolve(childPath));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function invalid(packageDirectory, message) {
+    return { valid: false, packageDirectory, errors: [message] };
+}
+function formatAjvErrors(errors) {
+    return (errors || []).map((error) => {
+        const location = error.instancePath || "/";
+        const missingProperty = typeof error.params === "object" && error.params !== null && "missingProperty" in error.params
+            ? String(error.params.missingProperty)
+            : "";
+        return [location, missingProperty, error.message || "schema validation failed"].filter(Boolean).join(" ");
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@aiot-nexus/plugin-sdk",
+  "version": "1.0.0",
+  "description": "Types, PluginFrame client, and CLI for AIoT Nexus independent plugins.",
+  "license": "UNLICENSED",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "require": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/frame-client.d.ts",
+      "import": "./dist/browser/frame-client.mjs",
+      "default": "./dist/browser/frame-client.mjs"
+    },
+    "./manifest-schema": "./dist/.generated/plugin-manifest.schema.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "nexus-plugin": "./dist/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "dev-host",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "test": "npm run build && node tests/package.test.js && node tests/cli.test.js && node tests/frame-client.test.js",
+    "pack:sdk": "npm run build && node scripts/pack.js"
+  },
+  "dependencies": {
+    "ajv": "8.17.1"
+  },
+  "devDependencies": {
+    "@types/node": "16.18.126",
+    "typescript": "4.9.4"
+  },
+  "engines": {
+    "node": ">=16.20.0 <17",
+    "npm": ">=6.13.4"
+  }
+}

package/templates/minimal/.gitignore.tmpl

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

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

@@ -0,0 +1,22 @@
+# __DISPLAY_NAME_MARKDOWN__
+
+AIoT Nexus independent PluginFrame plugin generated from the `minimal` template.
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm run dev
+```
+
+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.
+
+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. Add or 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. `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. 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/minimal/scripts/build.js.tmpl

@@ -0,0 +1,83 @@
+#!/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 sdkModuleSpecifier = "@aiot-nexus/plugin-sdk/browser";
+
+run();
+
+function run() {
+  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();
+  fs.rmSync(buildDirectory, { recursive: true, force: true });
+  console.log("[" + pluginId + "] built " + outputDirectory);
+}
+
+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"));
+}

package/templates/minimal/src/main.ts.tmpl

@@ -0,0 +1,23 @@
+import type { PluginMainActivationContext } from "@aiot-nexus/plugin-sdk";
+
+export function activate(context: PluginMainActivationContext): void {
+  const registration = context.host.registerRendererMethod("demo.echo", (request) => {
+    const value = request.input && typeof request.input.value === "string"
+      ? request.input.value.trim()
+      : "";
+    if (!value || value.length > 200) {
+      return {
+        ok: false,
+        error: {
+          code: "InvalidRequest",
+          message: "Echo value must contain 1 to 200 characters."
+        }
+      };
+    }
+    return { value, echoedAt: new Date().toISOString() };
+  });
+  if (!registration.ok) {
+    throw new Error(registration.error.message);
+  }
+  context.host.log("info", "__PLUGIN_ID__ activated.");
+}