@aiot-nexus/plugin-sdk 1.0.1 → 1.1.0

package/dist/src/cli.js

@@ -2,8 +2,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const run_1 = require("./cli/run");
-process.exitCode = (0, run_1.runCli)(process.argv.slice(2), {
+const result = (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")
 });
+if (typeof result === "number") {
+    process.exitCode = result;
+}
+else {
+    result.then((exitCode) => { process.exitCode = exitCode; }, (error) => {
+        process.stderr.write("nexus-plugin failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
+        process.exitCode = 1;
+    });
+}

package/dist/src/dev.d.ts

@@ -1,36 +1,48 @@
 import type { PluginManifest, PluginRendererSurface, ThemeMode } from "./types";
 export type PluginMainInspectorMode = "inspect" | "inspect-brk";
-export interface PluginDevOptions {
+export interface PluginDebugSelection {
     projectDirectory: string;
-    build: boolean;
-    openDevTools: boolean;
-    inspectorMode?: PluginMainInspectorMode;
-    inspectorPort?: number;
     language?: string;
     themeMode?: ThemeMode;
     surface?: PluginRendererSurface;
     contributionId?: string;
+}
+export interface PluginDevOptions extends PluginDebugSelection {
+    build: boolean;
+    openDevTools: boolean;
+    hostVersion?: string;
+    inspectorMode?: PluginMainInspectorMode;
+    inspectorPort?: number;
     smoke?: boolean;
 }
 export interface PluginDevIo {
     stdout(message: string): void;
     stderr(message: string): void;
 }
-export interface PluginDevTarget {
+export interface PluginDebugTarget {
     projectDirectory: string;
     packageDirectory: string;
     pluginId: string;
-    manifest: PluginManifest;
-    electronExecutable: string;
-    devHostMainPath: string;
+    manifest: PluginManifest & {
+        rendererEntry: string;
+    };
     surface: PluginRendererSurface;
     contributionId: string;
     language: string;
     themeMode: ThemeMode;
 }
+export interface PluginDevTarget extends PluginDebugTarget {
+    electronExecutable: string;
+    devHostMainPath: string;
+    hostVersion: string;
+}
 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;
+export declare function preparePluginDebugTarget(options: PluginDebugSelection): PluginDebugTarget;
+export declare function preparePluginBrowserDebugTarget(options: PluginDebugSelection, packageKind?: "auto" | "web" | "package"): PluginDebugTarget;
+export declare function buildPluginForDevelopment(projectDirectory: string): void;
+export declare function buildPluginRendererForDevelopment(projectDirectory: string): "web" | "package";

package/dist/src/dev.js

@@ -23,11 +23,12 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.preparePluginDev = exports.runPluginDev = exports.PluginDevError = void 0;
+exports.buildPluginRendererForDevelopment = exports.buildPluginForDevelopment = exports.preparePluginBrowserDebugTarget = exports.preparePluginDebugTarget = exports.preparePluginDev = exports.runPluginDev = exports.PluginDevError = void 0;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const module_1 = require("module");
 const path = __importStar(require("path"));
+const plugin_framework_version_1 = require("../.generated/plugin-framework-version");
 const validation_1 = require("./validation");
 class PluginDevError extends Error {
     constructor(message) {
@@ -43,12 +44,13 @@ function runPluginDev(options, io) {
     assertPluginProject(projectDirectory);
     if (options.build) {
         io.stdout("Building plugin with development source maps: " + projectDirectory);
-        runProjectBuild(projectDirectory);
+        buildPluginForDevelopment(projectDirectory);
     }
     const target = preparePluginDev({ ...options, projectDirectory });
     io.stdout("Starting plugin dev host: " + target.pluginId
         + "\nPlugin package: " + target.packageDirectory
-        + "\nContribution: " + target.surface + ":" + target.contributionId);
+        + "\nContribution: " + target.surface + ":" + target.contributionId
+        + "\nSimulated Nexus application version: " + target.hostVersion);
     if (options.inspectorMode) {
         io.stdout("Main process debugger: " + options.inspectorMode
             + " on 127.0.0.1:" + String(options.inspectorPort || 9229));
@@ -57,7 +59,7 @@ function runPluginDev(options, io) {
     if (options.inspectorMode) {
         electronArgs.push("--" + options.inspectorMode + "=" + String(options.inspectorPort || 9229));
     }
-    electronArgs.push(target.devHostMainPath, "--plugin-package=" + target.packageDirectory, "--project-directory=" + target.projectDirectory, "--surface=" + target.surface, "--contribution-id=" + target.contributionId, "--language=" + target.language, "--theme=" + target.themeMode);
+    electronArgs.push(target.devHostMainPath, "--plugin-package=" + target.packageDirectory, "--project-directory=" + target.projectDirectory, "--surface=" + target.surface, "--contribution-id=" + target.contributionId, "--language=" + target.language, "--theme=" + target.themeMode, "--host-version=" + target.hostVersion);
     if (!options.openDevTools) {
         electronArgs.push("--no-devtools");
     }
@@ -79,39 +81,76 @@ function runPluginDev(options, io) {
 }
 exports.runPluginDev = runPluginDev;
 function preparePluginDev(options) {
+    const target = preparePluginDebugTarget(options);
+    const hostVersion = normalizeHostVersion(options.hostVersion || readDefaultHostVersion());
+    const hostVersionComparison = (0, plugin_framework_version_1.comparePluginVersions)(target.manifest.minHostVersion, hostVersion);
+    if (hostVersionComparison === undefined) {
+        throw new PluginDevError("Plugin or simulated Nexus application version is invalid.");
+    }
+    if (hostVersionComparison > 0) {
+        throw new PluginDevError("Plugin requires Nexus " + target.manifest.minHostVersion
+            + " or newer; simulated host version is " + hostVersion + ".");
+    }
+    const electronExecutable = resolveElectronExecutable(target.projectDirectory);
+    const devHostMainPath = path.join(resolvePackageRoot(), "dev-host", "main.js");
+    if (!fs.existsSync(devHostMainPath) || !fs.statSync(devHostMainPath).isFile()) {
+        throw new PluginDevError("Plugin SDK dev host is missing: " + devHostMainPath);
+    }
+    return {
+        ...target,
+        electronExecutable,
+        devHostMainPath,
+        hostVersion
+    };
+}
+exports.preparePluginDev = preparePluginDev;
+function preparePluginDebugTarget(options) {
     const projectDirectory = path.resolve(options.projectDirectory);
     assertPluginProject(projectDirectory);
     const sourceManifest = readManifest(path.join(projectDirectory, "src", "manifest.json"), "Plugin source manifest");
     const packageDirectory = path.join(projectDirectory, "dist", sourceManifest.pluginId);
-    const validation = (0, validation_1.validatePluginPackage)(packageDirectory);
+    return preparePluginDebugTargetFromPackage(options, projectDirectory, packageDirectory, sourceManifest, "package");
+}
+exports.preparePluginDebugTarget = preparePluginDebugTarget;
+function preparePluginBrowserDebugTarget(options, packageKind = "auto") {
+    const projectDirectory = path.resolve(options.projectDirectory);
+    assertPluginProject(projectDirectory);
+    const sourceManifest = readManifest(path.join(projectDirectory, "src", "manifest.json"), "Plugin source manifest");
+    const webPackageDirectory = path.join(projectDirectory, ".nexus-plugin-dev", "web-package", sourceManifest.pluginId);
+    const packageDirectory = packageKind === "package"
+        ? path.join(projectDirectory, "dist", sourceManifest.pluginId)
+        : packageKind === "web" || fs.existsSync(webPackageDirectory)
+            ? webPackageDirectory
+            : path.join(projectDirectory, "dist", sourceManifest.pluginId);
+    return preparePluginDebugTargetFromPackage(options, projectDirectory, packageDirectory, sourceManifest, "renderer");
+}
+exports.preparePluginBrowserDebugTarget = preparePluginBrowserDebugTarget;
+function preparePluginDebugTargetFromPackage(options, projectDirectory, packageDirectory, sourceManifest, validationTarget) {
+    const validation = (0, validation_1.validatePluginPackage)(packageDirectory, { target: validationTarget });
     if (!validation.valid) {
         throw new PluginDevError("Plugin package is not ready for debugging: " + packageDirectory
             + "\n" + validation.errors.map((error) => "  - " + error).join("\n"));
     }
-    const manifest = readManifest(path.join(packageDirectory, "manifest.json"), "Built plugin manifest");
-    if (manifest.pluginId !== sourceManifest.pluginId) {
+    const manifestValue = readManifest(path.join(packageDirectory, "manifest.json"), "Built plugin manifest");
+    if (manifestValue.pluginId !== sourceManifest.pluginId) {
         throw new PluginDevError("Built plugin id does not match src/manifest.json.");
     }
-    const contribution = resolveContribution(manifest, options.surface, options.contributionId);
-    const electronExecutable = resolveElectronExecutable(projectDirectory);
-    const devHostMainPath = path.join(resolvePackageRoot(), "dev-host", "main.js");
-    if (!fs.existsSync(devHostMainPath) || !fs.statSync(devHostMainPath).isFile()) {
-        throw new PluginDevError("Plugin SDK dev host is missing: " + devHostMainPath);
+    if (!manifestValue.rendererEntry) {
+        throw new PluginDevError("Built plugin rendererEntry is required for independent debugging.");
     }
+    const manifest = manifestValue;
+    const contribution = resolveContribution(manifest, options.surface, options.contributionId);
     return {
         projectDirectory,
         packageDirectory,
         pluginId: manifest.pluginId,
         manifest,
-        electronExecutable,
-        devHostMainPath,
         surface: contribution.surface,
         contributionId: contribution.contributionId,
         language: normalizeLanguage(options.language, manifest),
         themeMode: options.themeMode || "system"
     };
 }
-exports.preparePluginDev = preparePluginDev;
 function assertPluginProject(projectDirectory) {
     if (!fs.existsSync(projectDirectory) || !fs.statSync(projectDirectory).isDirectory()) {
         throw new PluginDevError("Plugin project directory does not exist: " + projectDirectory);
@@ -121,19 +160,61 @@ function assertPluginProject(projectDirectory) {
         throw new PluginDevError("Plugin project package.json is missing: " + packageJsonPath);
     }
 }
-function runProjectBuild(projectDirectory) {
+function buildPluginForDevelopment(projectDirectory) {
+    runPluginBuildScript(projectDirectory, "build", "Plugin development build");
+}
+exports.buildPluginForDevelopment = buildPluginForDevelopment;
+function buildPluginRendererForDevelopment(projectDirectory) {
+    if (hasPluginBuildScript(projectDirectory, "build:web")) {
+        runPluginBuildScript(projectDirectory, "build:web", "Plugin browser UI development build");
+        return "web";
+    }
+    buildPluginForDevelopment(projectDirectory);
+    return "package";
+}
+exports.buildPluginRendererForDevelopment = buildPluginRendererForDevelopment;
+function runPluginBuildScript(projectDirectory, scriptName, label) {
+    assertPluginProject(projectDirectory);
+    if (!hasPluginBuildScript(projectDirectory, scriptName)) {
+        throw new PluginDevError("Plugin project is missing the npm script required for debugging: " + scriptName + ".");
+    }
     const command = process.platform === "win32" ? "npm.cmd" : "npm";
-    const result = (0, child_process_1.spawnSync)(command, ["run", "build"], {
+    const result = (0, child_process_1.spawnSync)(command, ["run", scriptName], {
         cwd: projectDirectory,
         env: { ...process.env, NEXUS_PLUGIN_DEV: "1" },
         stdio: "inherit"
     });
     if (result.error) {
-        throw new PluginDevError("Plugin development build could not start: " + result.error.message);
+        throw new PluginDevError(label + " could not start: " + result.error.message);
     }
     if (result.status !== 0) {
-        throw new PluginDevError("Plugin development build failed with exit code " + String(result.status === null ? 1 : result.status) + ".");
+        throw new PluginDevError(label + " failed with exit code " + String(result.status === null ? 1 : result.status) + ".");
+    }
+}
+function hasPluginBuildScript(projectDirectory, scriptName) {
+    assertPluginProject(projectDirectory);
+    const packageJson = readJsonRecord(path.join(projectDirectory, "package.json"), "Plugin project package metadata");
+    const scripts = packageJson.scripts;
+    return Boolean(scripts
+        && typeof scripts === "object"
+        && !Array.isArray(scripts)
+        && typeof scripts[scriptName] === "string");
+}
+function readDefaultHostVersion() {
+    const metadataPath = path.join(resolvePackageRoot(), "dist", "dev-host-metadata.json");
+    const metadata = readJsonRecord(metadataPath, "Plugin SDK dev host metadata");
+    if (typeof metadata.nexusApplicationVersion !== "string") {
+        throw new PluginDevError("Plugin SDK dev host metadata does not contain a Nexus application version.");
+    }
+    return metadata.nexusApplicationVersion;
+}
+function normalizeHostVersion(value) {
+    const normalized = value.trim();
+    const match = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.exec(normalized);
+    if (!match || [match[1], match[2], match[3]].some((segment) => !Number.isSafeInteger(Number(segment)))) {
+        throw new PluginDevError("Simulated Nexus host version must use X.Y.Z format: " + value);
     }
+    return normalized;
 }
 function readManifest(filePath, label) {
     if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 import pluginManifestSchema from "../.generated/plugin-manifest.schema.json";
-export declare const PLUGIN_SDK_VERSION = "1.0.1";
+export declare const PLUGIN_SDK_VERSION = "1.1.0";
 export { pluginManifestSchema };
 export * from "../.generated/plugin-framework-version";
 export * from "./types";

package/dist/src/index.js

@@ -20,7 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.pluginManifestSchema = exports.PLUGIN_SDK_VERSION = void 0;
 const plugin_manifest_schema_json_1 = __importDefault(require("../.generated/plugin-manifest.schema.json"));
 exports.pluginManifestSchema = plugin_manifest_schema_json_1.default;
-exports.PLUGIN_SDK_VERSION = "1.0.1";
+exports.PLUGIN_SDK_VERSION = "1.1.0";
 __exportStar(require("../.generated/plugin-framework-version"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./browser/frame-client"), exports);

package/dist/src/nexus-dev-control.d.ts

@@ -0,0 +1,42 @@
+export type NexusDevUpdateType = "rendererUpdated" | "manifestUpdated";
+export interface NexusDevUpdateResult {
+    ok: boolean;
+    message: string;
+    requiresRestart?: boolean;
+}
+export declare class NexusDevControlServer {
+    readonly token: string;
+    readonly pipePath: string;
+    private server;
+    private socket;
+    private receiveBuffer;
+    private helloAccepted;
+    private authenticated;
+    private authenticationResolve;
+    private authenticationReject;
+    private authenticationPromise;
+    private disconnectionPromise;
+    private disconnectionResolve;
+    private disconnectHandler;
+    private readonly pendingUpdates;
+    private readonly pendingShutdowns;
+    private nextRequestId;
+    start(): Promise<void>;
+    waitForAuthentication(timeoutMs?: number): Promise<void>;
+    sendUpdate(type: NexusDevUpdateType, pluginId: string): Promise<NexusDevUpdateResult>;
+    requestShutdown(): Promise<void>;
+    waitForDisconnection(timeoutMs?: number): Promise<void>;
+    setDisconnectHandler(handler: (error: Error) => void): () => void;
+    isConnected(): boolean;
+    close(): Promise<void>;
+    private handleConnection;
+    private handleData;
+    private handleMessage;
+    private handleDisconnect;
+    private rejectPending;
+    private rejectPendingShutdowns;
+    private ensureAuthenticationPromise;
+    private ensureDisconnectionPromise;
+    private rejectAuthentication;
+}
+export declare function helloProofPayload(version: number, pid: number, nonce: string): string;