@aiot-nexus/plugin-sdk 1.0.0

package/dist/src/browser/frame-client.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPluginFrameClient = exports.PluginFrameClientError = void 0;
+const initMessageType = "nexus-plugin:init";
+const contextChangedMessageType = "nexus-plugin:context-changed";
+const readyMessageType = "nexus-plugin:ready";
+const requestMessageType = "nexus-plugin:request";
+const responseMessageType = "nexus-plugin:response";
+const resizeMessageType = "nexus-plugin:resize";
+const defaultRequestTimeoutMs = 15000;
+class PluginFrameClientError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "PluginFrameClientError";
+        this.code = code;
+    }
+}
+exports.PluginFrameClientError = PluginFrameClientError;
+function createPluginFrameClient(options = {}) {
+    const resolvedFrameWindow = options.frameWindow || (typeof window === "undefined" ? undefined : window);
+    if (!resolvedFrameWindow) {
+        throw new PluginFrameClientError("ProtocolError", "PluginFrame client requires a browser window.");
+    }
+    const frameWindow = resolvedFrameWindow;
+    const targetWindow = options.targetWindow || frameWindow.parent;
+    const requestTimeoutMs = options.requestTimeoutMs === undefined ? defaultRequestTimeoutMs : options.requestTimeoutMs;
+    if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+        throw new PluginFrameClientError("ProtocolError", "requestTimeoutMs must be a positive finite number.");
+    }
+    let requestSequence = 0;
+    let disposed = false;
+    let contextValue;
+    let hostOrigin;
+    let contextSettled = false;
+    let contextTimeoutId;
+    let resizeTimer;
+    let resizeObserver;
+    const pendingRequests = new Map();
+    const contextListeners = new Set();
+    let resolveContext;
+    let rejectContext;
+    const contextPromise = new Promise((resolve, reject) => {
+        resolveContext = resolve;
+        rejectContext = reject;
+    });
+    void contextPromise.catch(() => undefined);
+    contextTimeoutId = frameWindow.setTimeout(() => {
+        contextTimeoutId = undefined;
+        if (!contextSettled) {
+            contextSettled = true;
+            rejectContext(new PluginFrameClientError("RequestTimeout", "PluginFrame initialization timed out."));
+        }
+    }, requestTimeoutMs);
+    frameWindow.addEventListener("message", handleMessage);
+    if (options.autoResize !== false) {
+        frameWindow.addEventListener("resize", scheduleResize);
+        const ResizeObserverConstructor = frameWindow.ResizeObserver;
+        if (typeof ResizeObserverConstructor === "function") {
+            const observer = new ResizeObserverConstructor(scheduleResize);
+            observer.observe(options.resizeRoot || frameWindow.document.documentElement);
+            resizeObserver = observer;
+        }
+    }
+    targetWindow.postMessage({ type: readyMessageType }, "*");
+    function waitForContext() {
+        if (disposed) {
+            return Promise.reject(disposedError());
+        }
+        return contextValue ? Promise.resolve(contextValue) : contextPromise;
+    }
+    function onContextChanged(listener) {
+        if (disposed) {
+            throw disposedError();
+        }
+        contextListeners.add(listener);
+        return () => {
+            contextListeners.delete(listener);
+        };
+    }
+    async function request(method, params) {
+        await waitForContext();
+        if (disposed) {
+            throw disposedError();
+        }
+        const requestId = "nexus-sdk-" + Date.now() + "-" + (++requestSequence);
+        return new Promise((resolve, reject) => {
+            const timeoutId = frameWindow.setTimeout(() => {
+                pendingRequests.delete(requestId);
+                reject(new PluginFrameClientError("RequestTimeout", "PluginFrame request timed out: " + method));
+            }, requestTimeoutMs);
+            pendingRequests.set(requestId, {
+                resolve: (result) => resolve(result),
+                reject,
+                timeoutId
+            });
+            post({ type: requestMessageType, requestId, method, params });
+        });
+    }
+    function getSettings() {
+        return request("getSettings");
+    }
+    function updateSettings(values) {
+        return request("updateSettings", { values });
+    }
+    function appendLog(logRequest) {
+        return request("appendLog", logRequest);
+    }
+    function invokeMain(operation, input) {
+        return request("invokeMain", { operation, input });
+    }
+    function handleMessage(event) {
+        if (disposed || event.source !== targetWindow || !isRecord(event.data)) {
+            return;
+        }
+        if (hostOrigin !== undefined && event.origin !== hostOrigin) {
+            return;
+        }
+        if (event.data.type === initMessageType || event.data.type === contextChangedMessageType) {
+            if (!isPluginRendererContext(event.data.context)) {
+                return;
+            }
+            const hadContext = contextValue !== undefined;
+            hostOrigin = event.origin;
+            contextValue = event.data.context;
+            if (!contextSettled) {
+                contextSettled = true;
+                if (contextTimeoutId !== undefined) {
+                    frameWindow.clearTimeout(contextTimeoutId);
+                    contextTimeoutId = undefined;
+                }
+                resolveContext(contextValue);
+            }
+            if (hadContext) {
+                notifyContextChanged(contextValue);
+            }
+            scheduleResize();
+            return;
+        }
+        if (event.data.type !== responseMessageType || typeof event.data.requestId !== "string") {
+            return;
+        }
+        const pending = pendingRequests.get(event.data.requestId);
+        if (!pending) {
+            return;
+        }
+        pendingRequests.delete(event.data.requestId);
+        frameWindow.clearTimeout(pending.timeoutId);
+        if (!isNexusResult(event.data.result)) {
+            pending.reject(new PluginFrameClientError("ProtocolError", "PluginFrame response is malformed."));
+            return;
+        }
+        pending.resolve(event.data.result);
+    }
+    function notifyContextChanged(context) {
+        for (const listener of Array.from(contextListeners)) {
+            try {
+                listener(context);
+            }
+            catch (error) {
+                const logger = frameWindow.console;
+                logger?.error("PluginFrame context listener failed.", error);
+            }
+        }
+    }
+    function scheduleResize() {
+        if (disposed || !contextValue || options.autoResize === false) {
+            return;
+        }
+        if (resizeTimer !== undefined) {
+            frameWindow.clearTimeout(resizeTimer);
+        }
+        if (contextTimeoutId !== undefined) {
+            frameWindow.clearTimeout(contextTimeoutId);
+        }
+        resizeTimer = frameWindow.setTimeout(() => {
+            resizeTimer = undefined;
+            notifyResize();
+        }, 0);
+    }
+    function notifyResize() {
+        if (disposed || !contextValue) {
+            return;
+        }
+        const root = options.resizeRoot || frameWindow.document.documentElement;
+        const body = frameWindow.document.body;
+        const height = Math.max(root.scrollHeight, root.offsetHeight, body?.scrollHeight || 0, body?.offsetHeight || 0);
+        post({ type: resizeMessageType, height });
+    }
+    function post(message) {
+        targetWindow.postMessage(message, hostOrigin && hostOrigin !== "null" ? hostOrigin : "*");
+    }
+    function dispose() {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        frameWindow.removeEventListener("message", handleMessage);
+        frameWindow.removeEventListener("resize", scheduleResize);
+        resizeObserver?.disconnect();
+        if (resizeTimer !== undefined) {
+            frameWindow.clearTimeout(resizeTimer);
+        }
+        const error = disposedError();
+        if (!contextSettled) {
+            contextSettled = true;
+            rejectContext(error);
+        }
+        for (const pending of pendingRequests.values()) {
+            frameWindow.clearTimeout(pending.timeoutId);
+            pending.reject(error);
+        }
+        pendingRequests.clear();
+        contextListeners.clear();
+    }
+    return { waitForContext, onContextChanged, request, getSettings, updateSettings, appendLog, invokeMain, notifyResize, dispose };
+}
+exports.createPluginFrameClient = createPluginFrameClient;
+function disposedError() {
+    return new PluginFrameClientError("Disposed", "PluginFrame client has been disposed.");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPluginRendererContext(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return typeof value.schemaVersion === "number"
+        && typeof value.pluginId === "string"
+        && (value.surface === "business" || value.surface === "tool" || value.surface === "settings")
+        && typeof value.contributionId === "string"
+        && typeof value.language === "string"
+        && (value.themeMode === "light" || value.themeMode === "dark" || value.themeMode === "system")
+        && typeof value.hostApiVersion === "string";
+}
+function isNexusResult(value) {
+    if (!isRecord(value) || typeof value.ok !== "boolean") {
+        return false;
+    }
+    if (value.ok) {
+        return Object.prototype.hasOwnProperty.call(value, "value");
+    }
+    return isRecord(value.error) && typeof value.error.code === "string" && typeof value.error.message === "string";
+}

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

@@ -0,0 +1,7 @@
+export interface CliIo {
+    cwd(): string;
+    stdout(message: string): void;
+    stderr(message: string): void;
+}
+export declare function runCli(args: string[], io: CliIo): number;
+export declare function usage(): string;

package/dist/src/cli/run.js

@@ -0,0 +1,270 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usage = exports.runCli = void 0;
+const path = __importStar(require("path"));
+const index_1 = require("../index");
+const scaffold_1 = require("../scaffold");
+const dev_1 = require("../dev");
+const nodeEngine = ">=16.20.0 <17";
+function runCli(args, io) {
+    const command = args[0];
+    if (command === "--help" || command === "-h") {
+        io.stdout(usage());
+        return 0;
+    }
+    if (command === "info") {
+        if (args.length !== 1) {
+            return usageError(io, "info does not accept arguments.");
+        }
+        io.stdout([
+            "SDK version: " + index_1.PLUGIN_SDK_VERSION,
+            "Plugin Framework API: " + index_1.PLUGIN_FRAMEWORK_VERSION,
+            "Manifest schema: " + index_1.PLUGIN_MANIFEST_SCHEMA_VERSION,
+            "Node engine: " + nodeEngine
+        ].join("\n"));
+        return 0;
+    }
+    if (command === "validate") {
+        if (args.length !== 2) {
+            return usageError(io, "validate requires one plugin package directory.");
+        }
+        const packageDirectory = path.resolve(io.cwd(), args[1]);
+        const result = (0, index_1.validatePluginPackage)(packageDirectory);
+        if (!result.valid) {
+            io.stderr("Invalid plugin package: " + packageDirectory + "\n" + result.errors.map((error) => "  - " + error).join("\n"));
+            return 1;
+        }
+        io.stdout("Valid plugin package: " + result.pluginId + " (" + packageDirectory + ")");
+        return 0;
+    }
+    if (command === "create") {
+        return runCreate(args.slice(1), io);
+    }
+    if (command === "dev") {
+        return runDev(args.slice(1), io);
+    }
+    return usageError(io, command ? "Unknown command: " + command : "A command is required.");
+}
+exports.runCli = runCli;
+function usage() {
+    return [
+        "Usage:",
+        "  nexus-plugin info",
+        "  nexus-plugin validate <plugin-package-directory>",
+        "  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>]]",
+        "    [--language <culture>] [--theme system|light|dark] [--surface business|tool|settings]",
+        "    [--contribution-id <id>] [--no-devtools]"
+    ].join("\n");
+}
+exports.usage = usage;
+function runDev(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,
+        openDevTools: true
+    };
+    const seen = new Set();
+    for (; index < args.length; index += 1) {
+        const option = args[index];
+        if (option === "--no-build" || option === "--no-devtools" || option === "--smoke") {
+            if (seen.has(option)) {
+                return usageError(io, "Duplicate option: " + option);
+            }
+            seen.add(option);
+            if (option === "--no-build") {
+                options.build = false;
+            }
+            else if (option === "--no-devtools") {
+                options.openDevTools = false;
+            }
+            else {
+                options.smoke = true;
+            }
+            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 (!["--language", "--theme", "--surface", "--contribution-id"].includes(option)) {
+            return usageError(io, "Unknown dev 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 === "--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, dev_1.runPluginDev)(options, io);
+    }
+    catch (error) {
+        if (error instanceof dev_1.PluginDevError) {
+            io.stderr(error.message);
+            return error.exitCode;
+        }
+        io.stderr("Plugin dev host failed: " + (error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+}
+function parseInspectorOption(option) {
+    const match = /^--(inspect|inspect-brk)(?:=([0-9]+))?$/.exec(option);
+    if (!match) {
+        return undefined;
+    }
+    const port = match[2] === undefined ? 9229 : Number(match[2]);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        return undefined;
+    }
+    return { mode: match[1], port };
+}
+function runCreate(args, io) {
+    if (args.length === 0 || args[0].startsWith("--")) {
+        return usageError(io, "create requires a plugin-id.");
+    }
+    const pluginId = args[0];
+    let template = "minimal";
+    let outputDirectory = io.cwd();
+    let displayName = (0, scaffold_1.defaultPluginDisplayName)(pluginId);
+    let sdkSource;
+    let install = false;
+    const seen = new Set();
+    for (let index = 1; index < args.length; index += 1) {
+        const option = args[index];
+        if (option === "--install") {
+            if (seen.has(option)) {
+                return usageError(io, "Duplicate option: " + option);
+            }
+            seen.add(option);
+            install = true;
+            continue;
+        }
+        if (!["--template", "--output", "--display-name", "--sdk-source"].includes(option)) {
+            return usageError(io, "Unknown create 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 === "--template") {
+            if (value !== "minimal" && value !== "sqlite") {
+                return usageError(io, "template must be minimal or sqlite.");
+            }
+            template = value;
+        }
+        else if (option === "--output") {
+            outputDirectory = path.resolve(io.cwd(), value);
+        }
+        else if (option === "--display-name") {
+            displayName = value.trim();
+        }
+        else {
+            sdkSource = value;
+        }
+    }
+    if (!sdkSource) {
+        return usageError(io, "create requires --sdk-source; use a local SDK .tgz until @aiot-nexus/plugin-sdk is published.");
+    }
+    try {
+        const result = (0, scaffold_1.createPluginScaffold)({
+            pluginId,
+            template,
+            workingDirectory: io.cwd(),
+            outputDirectory,
+            displayName,
+            sdkSource,
+            install
+        });
+        io.stdout("Created " + result.template + " plugin: " + result.pluginDirectory
+            + "\nSDK source: " + result.sdkSource
+            + "\nDependencies installed: " + (result.installed ? "yes" : "no"));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof scaffold_1.PluginScaffoldError) {
+            if (error.exitCode === 2) {
+                return usageError(io, error.message);
+            }
+            io.stderr(error.message);
+            return 1;
+        }
+        io.stderr("Plugin scaffold failed: " + (error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+}
+function usageError(io, message) {
+    io.stderr(message + "\n" + usage());
+    return 2;
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const run_1 = require("./cli/run");
+process.exitCode = (0, run_1.runCli)(process.argv.slice(2), {
+    cwd: () => process.cwd(),
+    stdout: (message) => process.stdout.write(message + "\n"),
+    stderr: (message) => process.stderr.write(message + "\n")
+});

package/dist/src/dev.d.ts

@@ -0,0 +1,36 @@
+import type { PluginManifest, PluginRendererSurface, ThemeMode } from "./types";
+export type PluginMainInspectorMode = "inspect" | "inspect-brk";
+export interface PluginDevOptions {
+    projectDirectory: string;
+    build: boolean;
+    openDevTools: boolean;
+    inspectorMode?: PluginMainInspectorMode;
+    inspectorPort?: number;
+    language?: string;
+    themeMode?: ThemeMode;
+    surface?: PluginRendererSurface;
+    contributionId?: string;
+    smoke?: boolean;
+}
+export interface PluginDevIo {
+    stdout(message: string): void;
+    stderr(message: string): void;
+}
+export interface PluginDevTarget {
+    projectDirectory: string;
+    packageDirectory: string;
+    pluginId: string;
+    manifest: PluginManifest;
+    electronExecutable: string;
+    devHostMainPath: string;
+    surface: PluginRendererSurface;
+    contributionId: string;
+    language: string;
+    themeMode: ThemeMode;
+}
+export declare class PluginDevError extends Error {
+    readonly exitCode: 1;
+    constructor(message: string);
+}
+export declare function runPluginDev(options: PluginDevOptions, io: PluginDevIo): number;
+export declare function preparePluginDev(options: PluginDevOptions): PluginDevTarget;