@aiot-nexus/plugin-sdk 1.0.0

package/dev-host/main.js

@@ -0,0 +1,694 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-var-requires */
+
+const fs = require("fs");
+const path = require("path");
+const { app, BrowserWindow, ipcMain, protocol } = require("electron");
+const sdk = require(path.join(__dirname, "..", "dist", "src", "index.js"));
+
+const pluginRendererProtocol = "nexus-plugin";
+const ipcChannels = {
+  getConfig: "nexus-plugin-dev:get-config",
+  invoke: "nexus-plugin-dev:invoke",
+  frameReady: "nexus-plugin-dev:frame-ready"
+};
+const pluginPermissions = ["businessLog", "settings", "filesystem", "udp", "serial", "externalProcess", "dialog"];
+const implementedPermissions = new Set(["businessLog", "settings"]);
+const routeGuardPermissions = new Set(["filesystem", "udp", "serial", "dialog"]);
+const handlers = new Map();
+
+protocol.registerSchemesAsPrivileged([
+  {
+    scheme: pluginRendererProtocol,
+    privileges: {
+      standard: true,
+      secure: true,
+      supportFetchAPI: true
+    }
+  }
+]);
+
+let configuration;
+try {
+  configuration = loadConfiguration(process.argv.slice(1));
+} catch (error) {
+  process.stderr.write("[nexus-plugin-dev] " + errorMessage(error) + "\n");
+  process.exit(1);
+}
+
+fs.mkdirSync(configuration.devDataDirectory, { recursive: true });
+fs.mkdirSync(configuration.pluginDataDirectory, { recursive: true });
+app.setPath("userData", path.join(configuration.devDataDirectory, "electron-user-data"));
+app.setName("Nexus Plugin Dev: " + configuration.manifest.pluginId);
+
+let mainWindow;
+let smokeTimeout;
+
+app.whenReady().then(function startDevHost() {
+  registerPluginRendererProtocol();
+  activatePluginMain();
+  registerIpcHandlers();
+  createWindow();
+}).catch(failStartup);
+
+app.on("window-all-closed", function quitAfterWindowClose() {
+  app.quit();
+});
+
+function loadConfiguration(args) {
+  const packageDirectory = requiredPathArgument(args, "--plugin-package");
+  const projectDirectory = requiredPathArgument(args, "--project-directory");
+  const validation = sdk.validatePluginPackage(packageDirectory);
+  if (!validation.valid) {
+    throw new Error("Plugin package validation failed:\n" + validation.errors.map(function format(error) {
+      return "  - " + error;
+    }).join("\n"));
+  }
+  const manifest = readJson(path.join(packageDirectory, "manifest.json"));
+  const surface = requiredArgument(args, "--surface");
+  const contributionId = requiredArgument(args, "--contribution-id");
+  const language = requiredArgument(args, "--language");
+  const themeMode = requiredArgument(args, "--theme");
+  if (!hasContribution(manifest, surface, contributionId)) {
+    throw new Error("Selected PluginFrame contribution is not declared: " + surface + ":" + contributionId);
+  }
+  if (!manifest.rendererEntry) {
+    throw new Error("Plugin rendererEntry is required for independent debugging.");
+  }
+  const devDataDirectory = path.join(projectDirectory, ".nexus-plugin-dev");
+  return {
+    packageDirectory,
+    projectDirectory,
+    manifest,
+    surface,
+    contributionId,
+    language,
+    themeMode,
+    openDevTools: !args.includes("--no-devtools"),
+    smoke: args.includes("--smoke"),
+    devDataDirectory,
+    pluginDataDirectory: path.join(devDataDirectory, "data")
+  };
+}
+
+function registerPluginRendererProtocol() {
+  const registered = protocol.registerFileProtocol(pluginRendererProtocol, function resolvePluginAsset(request, callback) {
+    try {
+      const result = resolvePluginRendererFile(request.url);
+      if (!result.ok) {
+        callback({ error: -6 });
+        return;
+      }
+      callback(result.value);
+    } catch (error) {
+      process.stderr.write("[nexus-plugin-dev] renderer asset failed: " + errorMessage(error) + "\n");
+      callback({ error: -6 });
+    }
+  });
+  if (!registered) {
+    throw new Error("Failed to register the nexus-plugin renderer protocol.");
+  }
+}
+
+function resolvePluginRendererFile(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return fail("InvalidRequest", "Plugin renderer URL is invalid.");
+  }
+  if (parsed.protocol !== pluginRendererProtocol + ":" || parsed.hostname !== configuration.manifest.pluginId) {
+    return fail("InvalidRequest", "Plugin renderer URL identity is invalid.");
+  }
+  const entryPath = path.resolve(configuration.packageDirectory, configuration.manifest.rendererEntry);
+  const rendererRoot = path.dirname(entryPath);
+  let requestedRelativePath;
+  try {
+    requestedRelativePath = decodeURIComponent(parsed.pathname.replace(/^\/+/, "")) || configuration.manifest.rendererEntry;
+  } catch {
+    return fail("InvalidRequest", "Plugin renderer asset path is invalid.");
+  }
+  const requestedPath = path.resolve(configuration.packageDirectory, requestedRelativePath);
+  if (!isPathInside(rendererRoot, requestedPath)) {
+    return fail("PluginBlocked", "Plugin renderer asset resolves outside renderer directory.");
+  }
+  if (!fs.existsSync(requestedPath) || !fs.statSync(requestedPath).isFile() || fs.lstatSync(requestedPath).isSymbolicLink()) {
+    return fail("NotFound", "Plugin renderer asset was not found.");
+  }
+  const realRoot = fs.realpathSync(rendererRoot);
+  const realPath = fs.realpathSync(requestedPath);
+  if (!isPathInside(realRoot, realPath)) {
+    return fail("PluginBlocked", "Plugin renderer asset resolves outside renderer directory.");
+  }
+  return ok({
+    path: realPath,
+    mimeType: mimeType(realPath),
+    headers: {
+      "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'",
+      "X-Content-Type-Options": "nosniff"
+    }
+  });
+}
+
+function activatePluginMain() {
+  if (!configuration.manifest.mainEntry) {
+    return;
+  }
+  const mainEntryPath = path.resolve(configuration.packageDirectory, configuration.manifest.mainEntry);
+  const pluginModule = require(mainEntryPath);
+  const activate = typeof pluginModule.activate === "function"
+    ? pluginModule.activate
+    : pluginModule.default && typeof pluginModule.default.activate === "function"
+      ? pluginModule.default.activate
+      : undefined;
+  if (activate) {
+    activate({
+      pluginId: configuration.manifest.pluginId,
+      pluginDirectory: configuration.packageDirectory,
+      manifest: configuration.manifest,
+      host: createHostApi()
+    });
+  }
+  process.stdout.write(
+    "[nexus-plugin-dev] activated " + configuration.manifest.pluginId
+    + " with " + String(handlers.size) + " renderer operation(s).\n"
+  );
+}
+
+function createHostApi() {
+  const manifest = configuration.manifest;
+  return {
+    hostVersion: manifest.minHostVersion || "0.0.0",
+    hostApiVersion: sdk.PLUGIN_FRAMEWORK_VERSION,
+    pluginId: manifest.pluginId,
+    pluginDataDirectory: configuration.pluginDataDirectory,
+    hasPermission: function hasPermission(permission) {
+      return manifest.permissions.includes(permission);
+    },
+    registerRendererMethod: function registerRendererMethod(name, handler) {
+      if (!isSafeOperationName(name)) {
+        return fail("InvalidRequest", "Plugin renderer operation name is invalid.", { operation: name });
+      }
+      if (typeof handler !== "function") {
+        return fail("InvalidRequest", "Plugin renderer operation handler must be a function.", { operation: name });
+      }
+      if (handlers.has(name)) {
+        return fail("InvalidRequest", "Plugin renderer operation is already registered.", { operation: name });
+      }
+      handlers.set(name, handler);
+      return ok(true);
+    },
+    getCapabilityStatus: function getCapabilityStatus(permission) {
+      return isPluginPermission(permission)
+        ? ok(createPermissionSummary(permission))
+        : fail("InvalidRequest", "Plugin capability name is invalid.", { permission });
+    },
+    unsupportedCapability: function unsupportedCapability(permission, operation) {
+      return unsupportedCapability(manifest, permission, operation);
+    },
+    log: function log(level, message, exception) {
+      if (!manifest.permissions.includes("businessLog")) {
+        return fail("PluginPermissionDenied", "Plugin does not declare businessLog permission.");
+      }
+      return ok(appendLog(level, "plugin:" + manifest.pluginId, message, exception));
+    },
+    getSettings: function getSettings() {
+      return manifest.permissions.includes("settings")
+        ? ok(loadSettings())
+        : fail("PluginPermissionDenied", "Plugin does not declare settings permission.");
+    },
+    updateSettings: function updateSettings(values) {
+      if (!manifest.permissions.includes("settings")) {
+        return fail("PluginPermissionDenied", "Plugin does not declare settings permission.");
+      }
+      if (!isRecord(values)) {
+        return fail("InvalidRequest", "Plugin settings values must be an object.");
+      }
+      return ok(saveSettings(values));
+    },
+    filesystem: createUnsupportedCapabilityApi(manifest, "filesystem"),
+    udp: createUnsupportedCapabilityApi(manifest, "udp"),
+    serial: createUnsupportedCapabilityApi(manifest, "serial"),
+    dialog: createUnsupportedCapabilityApi(manifest, "dialog"),
+    externalProcess: createUnsupportedCapabilityApi(manifest, "externalProcess")
+  };
+}
+
+function createUnsupportedCapabilityApi(manifest, permission) {
+  const target = {
+    permission,
+    supportState: permissionSupportState(permission),
+    describe: function describe() {
+      return ok(createPermissionSummary(permission));
+    },
+    unsupported: function unsupported(operation) {
+      return unsupportedCapability(manifest, permission, operation);
+    }
+  };
+  return new Proxy(target, {
+    get: function get(apiTarget, property) {
+      if (property in apiTarget) {
+        return Reflect.get(apiTarget, property);
+      }
+      if (typeof property === "symbol" || property === "then") {
+        return undefined;
+      }
+      return function unsupportedOperation() {
+        return unsupportedCapability(manifest, permission, property);
+      };
+    }
+  });
+}
+
+function unsupportedCapability(manifest, permission, operation) {
+  if (!isPluginPermission(permission)) {
+    return fail("InvalidRequest", "Plugin capability name is invalid.", { permission });
+  }
+  if (!manifest.permissions.includes(permission)) {
+    return fail("PluginPermissionDenied", "Plugin does not declare " + permission + " permission.", { permission });
+  }
+  const summary = createPermissionSummary(permission);
+  return fail(
+    "PluginCapabilityUnsupported",
+    "Plugin Host API capability is not available to trusted mainEntry.",
+    {
+      permission,
+      operation: typeof operation === "string" ? operation : undefined,
+      supportState: summary.supportState,
+      statusMessage: summary.statusMessage
+    }
+  );
+}
+
+function registerIpcHandlers() {
+  ipcMain.handle(ipcChannels.getConfig, function getConfig(event) {
+    assertMainWindowSender(event);
+    return createRendererConfiguration();
+  });
+  ipcMain.handle(ipcChannels.invoke, function invoke(event, request) {
+    assertMainWindowSender(event);
+    return invokeRendererRequest(request);
+  });
+  ipcMain.on(ipcChannels.frameReady, function frameReady(event) {
+    assertMainWindowSender(event);
+    if (configuration.smoke) {
+      clearTimeout(smokeTimeout);
+      process.stdout.write("[nexus-plugin-dev] renderer initialization smoke passed.\n");
+      setTimeout(function exitAfterSmokeSettles() {
+        app.exit(0);
+      }, 100);
+    }
+  });
+}
+
+function createRendererConfiguration() {
+  const manifest = configuration.manifest;
+  const frameOrigin = pluginRendererProtocol + "://" + manifest.pluginId;
+  const encodedEntry = manifest.rendererEntry.split("/").map(encodeURIComponent).join("/");
+  const query = new URLSearchParams({
+    surface: configuration.surface,
+    contributionId: configuration.contributionId
+  });
+  return {
+    pluginId: manifest.pluginId,
+    frameOrigin,
+    frameUrl: frameOrigin + "/" + encodedEntry + "?" + query.toString(),
+    supportedCultures: manifest.supportedCultures,
+    smoke: configuration.smoke,
+    context: {
+      schemaVersion: sdk.PLUGIN_MANIFEST_SCHEMA_VERSION,
+      pluginId: manifest.pluginId,
+      surface: configuration.surface,
+      contributionId: configuration.contributionId,
+      language: configuration.language,
+      themeMode: configuration.themeMode,
+      hostApiVersion: sdk.PLUGIN_FRAMEWORK_VERSION
+    }
+  };
+}
+
+function invokeRendererRequest(request) {
+  if (!isRecord(request) || typeof request.method !== "string") {
+    return fail("InvalidRequest", "Plugin renderer request is invalid.");
+  }
+  const params = isRecord(request.params) ? request.params : undefined;
+  if (request.method === "getSettings") {
+    return configuration.manifest.permissions.includes("settings")
+      ? ok(loadSettings())
+      : fail("PluginPermissionDenied", "Plugin does not declare settings permission.");
+  }
+  if (request.method === "updateSettings") {
+    if (!configuration.manifest.permissions.includes("settings")) {
+      return fail("PluginPermissionDenied", "Plugin does not declare settings permission.");
+    }
+    if (!params || !isRecord(params.values)) {
+      return fail("InvalidRequest", "Plugin renderer settings update requires values.");
+    }
+    return ok(saveSettings(params.values));
+  }
+  if (request.method === "appendLog") {
+    if (!configuration.manifest.permissions.includes("businessLog")) {
+      return fail("PluginPermissionDenied", "Plugin does not declare businessLog permission.");
+    }
+    if (!params || !isLogLevel(params.level) || typeof params.message !== "string" || !params.message.trim()) {
+      return fail("InvalidRequest", "Plugin renderer log request is invalid.");
+    }
+    const category = typeof params.category === "string" && params.category.trim()
+      ? ":" + params.category.trim()
+      : "";
+    const exception = typeof params.exception === "string" && params.exception.trim()
+      ? params.exception.trim()
+      : undefined;
+    return ok(appendLog(params.level, "plugin:" + configuration.manifest.pluginId + category, params.message.trim(), exception));
+  }
+  if (request.method === "invokeMain") {
+    return invokeMain(params);
+  }
+  return fail("InvalidRequest", "Plugin renderer request method is invalid.", { method: request.method });
+}
+
+function invokeMain(params) {
+  if (!params || typeof params.operation !== "string") {
+    return fail("InvalidRequest", "Plugin renderer invokeMain request requires an operation name.");
+  }
+  if (params.input !== undefined && !isRecord(params.input)) {
+    return fail("InvalidRequest", "Plugin renderer invokeMain input must be an object.", { operation: params.operation });
+  }
+  if (!isSafeOperationName(params.operation)) {
+    return fail("InvalidRequest", "Plugin renderer operation name is invalid.", { operation: params.operation });
+  }
+  const handler = handlers.get(params.operation);
+  if (!handler) {
+    return fail("NotFound", "Plugin renderer operation was not registered.", { operation: params.operation });
+  }
+  try {
+    const value = handler({
+      pluginId: configuration.manifest.pluginId,
+      surface: configuration.surface,
+      contributionId: configuration.contributionId,
+      operation: params.operation,
+      input: isRecord(params.input) ? params.input : undefined
+    });
+    return normalizeRendererOperationResult(value);
+  } catch (error) {
+    process.stderr.write("[nexus-plugin-dev] operation failed: " + params.operation + ": " + errorMessage(error) + "\n");
+    return fail("UnexpectedFailure", "Plugin renderer operation failed.", {
+      operation: params.operation,
+      message: errorMessage(error)
+    });
+  }
+}
+
+function normalizeRendererOperationResult(value) {
+  if (isNexusResult(value)) {
+    if (value.ok) {
+      return ok(sanitizeJsonValue(value.value));
+    }
+    return fail(
+      value.error.code,
+      value.error.message,
+      value.error.details === undefined ? undefined : sanitizeJsonValue(value.error.details)
+    );
+  }
+  return ok(sanitizeJsonValue(value));
+}
+
+function createWindow() {
+  mainWindow = new BrowserWindow({
+    width: 1200,
+    height: 800,
+    minWidth: 640,
+    minHeight: 480,
+    show: !configuration.smoke,
+    backgroundColor: configuration.themeMode === "dark" ? "#181a1d" : "#f4f5f7",
+    webPreferences: {
+      preload: path.join(__dirname, "preload.js"),
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+      webSecurity: true
+    }
+  });
+  mainWindow.webContents.setWindowOpenHandler(function denyWindowOpen() {
+    return { action: "deny" };
+  });
+  mainWindow.webContents.on("did-fail-load", function reportLoadFailure(_event, errorCode, errorDescription, validatedUrl, isMainFrame) {
+    process.stderr.write(
+      "[nexus-plugin-dev] load failed: " + String(errorCode) + " " + errorDescription + " " + validatedUrl + "\n"
+    );
+    if (configuration.smoke && isMainFrame) {
+      app.exit(1);
+    }
+  });
+  mainWindow.webContents.on("render-process-gone", function reportRendererExit(_event, details) {
+    process.stderr.write("[nexus-plugin-dev] renderer process exited: " + details.reason + "\n");
+    if (configuration.smoke) {
+      app.exit(1);
+    }
+  });
+  mainWindow.on("closed", function clearWindow() {
+    mainWindow = undefined;
+  });
+  void mainWindow.loadFile(path.join(__dirname, "host.html"));
+  if (configuration.openDevTools && !configuration.smoke) {
+    mainWindow.webContents.once("did-finish-load", function openDevTools() {
+      mainWindow && mainWindow.webContents.openDevTools({ mode: "detach" });
+    });
+  }
+  if (configuration.smoke) {
+    smokeTimeout = setTimeout(function failSmokeTimeout() {
+      process.stderr.write("[nexus-plugin-dev] renderer initialization smoke timed out.\n");
+      app.exit(1);
+    }, 15000);
+  }
+}
+
+function assertMainWindowSender(event) {
+  if (!mainWindow || event.sender !== mainWindow.webContents) {
+    throw new Error("Rejected IPC request from an unexpected renderer.");
+  }
+}
+
+function loadSettings() {
+  const filePath = settingsFilePath();
+  if (!fs.existsSync(filePath)) {
+    return emptySettings();
+  }
+  try {
+    const value = readJson(filePath);
+    return {
+      schemaVersion: sdk.PLUGIN_MANIFEST_SCHEMA_VERSION,
+      pluginId: configuration.manifest.pluginId,
+      values: isRecord(value.values) ? sanitizeJsonObject(value.values) : {}
+    };
+  } catch (error) {
+    process.stderr.write("[nexus-plugin-dev] settings reset after read failure: " + errorMessage(error) + "\n");
+    return emptySettings();
+  }
+}
+
+function saveSettings(values) {
+  const existing = loadSettings();
+  const document = {
+    schemaVersion: sdk.PLUGIN_MANIFEST_SCHEMA_VERSION,
+    pluginId: configuration.manifest.pluginId,
+    values: Object.assign({}, existing.values, sanitizeJsonObject(values))
+  };
+  const filePath = settingsFilePath();
+  const temporaryPath = filePath + ".tmp";
+  fs.writeFileSync(temporaryPath, JSON.stringify(document, null, 2) + "\n", "utf8");
+  fs.renameSync(temporaryPath, filePath);
+  return document;
+}
+
+function settingsFilePath() {
+  fs.mkdirSync(configuration.pluginDataDirectory, { recursive: true });
+  return path.join(configuration.pluginDataDirectory, "settings.json");
+}
+
+function emptySettings() {
+  return {
+    schemaVersion: sdk.PLUGIN_MANIFEST_SCHEMA_VERSION,
+    pluginId: configuration.manifest.pluginId,
+    values: {}
+  };
+}
+
+function appendLog(level, category, message, exception) {
+  const entry = {
+    timestamp: new Date().toISOString(),
+    level,
+    category,
+    message,
+    exception
+  };
+  const output = "[nexus-plugin-dev][" + String(level) + "][" + category + "] " + String(message)
+    + (exception ? "\n" + exception : "") + "\n";
+  if (level === "error" || level === "warn") {
+    process.stderr.write(output);
+  } else {
+    process.stdout.write(output);
+  }
+  return entry;
+}
+
+function hasContribution(manifest, surface, contributionId) {
+  if (surface === "business") {
+    return (manifest.businessEntries || []).some(function matchesBusiness(entry) {
+      return entry.component === "PluginFrame" && entry.businessId === contributionId;
+    });
+  }
+  if (surface === "tool") {
+    return (manifest.tools || []).some(function matchesTool(entry) {
+      return entry.component === "PluginFrame" && entry.toolId === contributionId;
+    });
+  }
+  if (surface === "settings") {
+    return (manifest.settingsSections || []).some(function matchesSettings(entry) {
+      return entry.component === "PluginFrame" && entry.sectionId === contributionId;
+    });
+  }
+  return false;
+}
+
+function isSafeOperationName(value) {
+  return typeof value === "string"
+    && value.length <= 80
+    && /^[a-z][A-Za-z0-9]*(?:\.[a-z][A-Za-z0-9]*){1,4}$/.test(value)
+    && value.split(".").every(function isSafePart(part) {
+      return part !== "constructor" && part !== "prototype" && part !== "__proto__";
+    });
+}
+
+function isNexusResult(value) {
+  if (!isRecord(value) || typeof value.ok !== "boolean") {
+    return false;
+  }
+  return value.ok
+    ? Object.prototype.hasOwnProperty.call(value, "value")
+    : isRecord(value.error) && typeof value.error.code === "string" && typeof value.error.message === "string";
+}
+
+function isPluginPermission(value) {
+  return typeof value === "string" && pluginPermissions.includes(value);
+}
+
+function permissionSupportState(permission) {
+  if (implementedPermissions.has(permission)) {
+    return "implemented";
+  }
+  if (routeGuardPermissions.has(permission)) {
+    return "routeGuard";
+  }
+  return "reserved";
+}
+
+function createPermissionSummary(permission) {
+  const supportState = permissionSupportState(permission);
+  const statusMessage = supportState === "implemented"
+    ? "Available to trusted mainEntry Host API."
+    : supportState === "routeGuard"
+      ? "Declared for renderer route guards; not exposed to trusted mainEntry Host API."
+      : "Reserved for a future Host API; trusted mainEntry calls return PluginCapabilityUnsupported.";
+  return { permission, supportState, statusMessage };
+}
+
+function sanitizeJsonValue(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sanitizeJsonValue);
+  }
+  if (isRecord(value)) {
+    return sanitizeJsonObject(value);
+  }
+  return null;
+}
+
+function sanitizeJsonObject(value) {
+  return Object.fromEntries(Object.entries(value).map(function sanitizeEntry(entry) {
+    return [entry[0], sanitizeJsonValue(entry[1])];
+  }));
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isLogLevel(value) {
+  return value === "debug" || value === "info" || value === "warn" || value === "error";
+}
+
+function isPathInside(rootDirectory, childPath) {
+  const root = path.resolve(rootDirectory);
+  const child = path.resolve(childPath);
+  const relative = path.relative(root, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function mimeType(filePath) {
+  const types = {
+    ".html": "text/html",
+    ".js": "text/javascript",
+    ".mjs": "text/javascript",
+    ".css": "text/css",
+    ".json": "application/json",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf"
+  };
+  return types[path.extname(filePath).toLowerCase()] || "application/octet-stream";
+}
+
+function requiredPathArgument(args, name) {
+  const value = requiredArgument(args, name);
+  const resolved = path.resolve(value);
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+    throw new Error(name + " directory does not exist: " + resolved);
+  }
+  return resolved;
+}
+
+function requiredArgument(args, name) {
+  const prefix = name + "=";
+  const argument = args.find(function findArgument(value) {
+    return value.startsWith(prefix);
+  });
+  if (!argument || argument.length === prefix.length) {
+    throw new Error("Missing required argument: " + name);
+  }
+  return argument.slice(prefix.length);
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function ok(value) {
+  return { ok: true, value };
+}
+
+function fail(code, message, details) {
+  return { ok: false, error: { code, message, details } };
+}
+
+function failStartup(error) {
+  clearTimeout(smokeTimeout);
+  process.stderr.write("[nexus-plugin-dev] startup failed: " + errorMessage(error) + "\n");
+  app.exit(1);
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.stack || error.message : String(error);
+}