@aiot-nexus/plugin-sdk 1.0.0 → 1.0.2

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.0";
+export declare const PLUGIN_SDK_VERSION = "1.0.2";
 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.0";
+exports.PLUGIN_SDK_VERSION = "1.0.2";
 __exportStar(require("../.generated/plugin-framework-version"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./browser/frame-client"), exports);

package/dist/src/scaffold.js

@@ -199,7 +199,9 @@ function vendorSdkArchive(pluginDirectory, sourcePath) {
 function createPackageJson(options, sdkSource) {
     const scripts = {
         build: "node scripts/build.js && npm run validate",
+        "build:web": "node scripts/build.js --renderer-only",
         dev: "nexus-plugin dev .",
+        "dev:web": "nexus-plugin dev:web .",
         "dev:debug": "nexus-plugin dev . --inspect-brk=9229",
         typecheck: "tsc -p tsconfig.main.json --noEmit && tsc -p tsconfig.renderer.json --noEmit",
         validate: "nexus-plugin validate dist/" + options.pluginId

package/dist/src/validation.d.ts

@@ -6,4 +6,7 @@ export interface PluginPackageValidationResult {
     manifest?: PluginManifest;
     errors: string[];
 }
-export declare function validatePluginPackage(packageDirectory: string): PluginPackageValidationResult;
+export interface PluginPackageValidationOptions {
+    target?: "package" | "renderer";
+}
+export declare function validatePluginPackage(packageDirectory: string, options?: PluginPackageValidationOptions): PluginPackageValidationResult;

package/dist/src/validation.js

@@ -34,17 +34,17 @@ const plugin_manifest_schema_json_1 = __importDefault(require("../.generated/plu
 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) {
+function validatePluginPackage(packageDirectory, options = {}) {
     const resolvedDirectory = path.resolve(packageDirectory);
     try {
-        return validateResolvedPluginPackage(resolvedDirectory);
+        return validateResolvedPluginPackage(resolvedDirectory, options);
     }
     catch (error) {
         return invalid(resolvedDirectory, "Plugin package could not be inspected: " + errorMessage(error));
     }
 }
 exports.validatePluginPackage = validatePluginPackage;
-function validateResolvedPluginPackage(resolvedDirectory) {
+function validateResolvedPluginPackage(resolvedDirectory, options) {
     const errors = [];
     if (!fs.existsSync(resolvedDirectory)) {
         return invalid(resolvedDirectory, "Plugin package directory does not exist.");
@@ -88,7 +88,7 @@ function validateResolvedPluginPackage(resolvedDirectory) {
     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, "mainEntry", manifest.mainEntry, errors, options.target !== "renderer");
     validateEntry(resolvedDirectory, "rendererEntry", manifest.rendererEntry, errors);
     if (manifest.rendererEntry && path.extname(manifest.rendererEntry).toLowerCase() !== ".html") {
         errors.push("rendererEntry must point to an HTML file.");
@@ -104,7 +104,7 @@ function validateResolvedPluginPackage(resolvedDirectory) {
         errors
     };
 }
-function validateEntry(rootDirectory, fieldName, relativePath, errors) {
+function validateEntry(rootDirectory, fieldName, relativePath, errors, requireExistingFile = true) {
     if (!relativePath) {
         return;
     }
@@ -118,7 +118,9 @@ function validateEntry(rootDirectory, fieldName, relativePath, errors) {
         return;
     }
     if (!fs.existsSync(entryPath)) {
-        errors.push(fieldName + " does not exist: " + relativePath);
+        if (requireExistingFile) {
+            errors.push(fieldName + " does not exist: " + relativePath);
+        }
         return;
     }
     const entryStat = fs.lstatSync(entryPath);

package/dist/src/web-dev.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="node" />
+import * as http from "http";
+import { type PluginDebugSelection, type PluginDebugTarget, type PluginDevIo } from "./dev";
+export interface PluginWebDevOptions extends PluginDebugSelection {
+    build: boolean;
+    openBrowser: boolean;
+    port: number;
+}
+export declare function runPluginWebDev(options: PluginWebDevOptions, io: PluginDevIo): number;
+export declare function createPluginWebDevServer(target: PluginDebugTarget, io: PluginDevIo): http.Server;
+export declare function pluginWebDevServerUrl(server: http.Server): string;