@elementspanel/panel 0.0.0-stage → 1.0.0

package/runtime/cli.cjs

@@ -0,0 +1,305 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { createRequire, registerHooks } = require("node:module");
+const { resolveNpmPlugins } = require("./npm-plugins.cjs");
+const { ensureRuntimeTools } = require("./daemon-tools.cjs");
+const { fork } = require("node:child_process");
+
+function parseArgs(argv, side) {
+  const options = { command: "start", withDaemon: false, open: false };
+  if (argv[0] && !argv[0].startsWith("-")) options.command = argv.shift();
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index];
+    if (["--help", "-h"].includes(argument)) options.command = "help";
+    else if (["--version", "-v"].includes(argument)) options.command = "version";
+    else if (argument === "--with-daemon") options.withDaemon = true;
+    else if (argument === "--open") options.open = true;
+    else if (["--cwd", "--panel-dir", "--daemon-dir"].includes(argument)) {
+      const value = argv[++index];
+      if (!value || value.startsWith("--")) throw new Error(`Missing value for ${argument}.`);
+      options[argument.slice(2)] = value;
+    } else throw new Error(`Unknown option: ${argument}`);
+  }
+  if (!["start", "help", "version"].includes(options.command))
+    throw new Error(`Unknown command: ${options.command}`);
+  if (side === "daemon" && (options.withDaemon || options.open || options["panel-dir"])) {
+    throw new Error("--with-daemon, --open and --panel-dir belong to the panel command.");
+  }
+  return options;
+}
+
+function help(side) {
+  return `Usage: ${side === "panel" ? "epanel" : "epanel-daemon"} start [options]
+
+  --cwd <directory>         Project directory (default: current directory)
+  --${side}-dir <directory>  Existing runtime directory (default: ./${side})
+${
+  side === "panel"
+    ? "  --with-daemon            Start the local daemon before the panel\n  --daemon-dir <directory>  Local daemon directory (default: ./daemon)\n  --open                   Open the panel in a browser on Windows\n"
+    : ""
+}  --help                   Show this help
+  --version                Show the installed package version
+`;
+}
+
+function runtimeDirectory(project, override, side) {
+  return path.resolve(project, override || side);
+}
+
+function workerEnvironment(plan, worker) {
+  const environment = { ...process.env, EPANEL_PROJECT_ROOT: plan.project };
+  delete environment.EPANEL_PACKAGE_ROOT;
+  delete environment.EPANEL_LOCAL_DAEMON_CONFIG;
+  if (worker.side === "panel" && plan.localDaemonConfig)
+    environment.EPANEL_LOCAL_DAEMON_CONFIG = plan.localDaemonConfig;
+
+  // fork() pipes worker output so the parent can add a side prefix. That makes
+  // supports-color think stdout is not a terminal, even when npm start is
+  // running in one. Preserve explicit color settings and otherwise propagate
+  // the parent's terminal capability to the worker.
+  if (
+    environment.FORCE_COLOR === undefined &&
+    environment.NO_COLOR === undefined &&
+    (process.stdout.isTTY || process.stderr.isTTY)
+  ) {
+    environment.FORCE_COLOR = "3";
+  }
+  return environment;
+}
+
+function workerPrefix(side, target) {
+  const color = side === "daemon" ? "\u001b[36m" : "\u001b[32m";
+  const forceColor = process.env.FORCE_COLOR;
+  const colored =
+    process.env.NO_COLOR === undefined &&
+    (target.isTTY ||
+      (forceColor !== undefined && forceColor !== "0" && forceColor !== "false"));
+  return colored ? `${color}[${side}]\u001b[39m ` : `[${side}] `;
+}
+
+/** Prefix worker output without breaking lines split across child-process chunks. */
+function pipeWorkerOutput(stream, target, side) {
+  let pending = "";
+  const prefix = workerPrefix(side, target);
+  const write = (chunk) => {
+    pending += chunk.toString();
+    const lines = pending.split("\n");
+    pending = lines.pop() || "";
+    for (const line of lines) target.write(`${prefix}${line.replace(/\r$/, "")}\n`);
+  };
+  const flush = () => {
+    if (!pending) return;
+    target.write(`${prefix}${pending.replace(/\r$/, "")}\n`);
+    pending = "";
+  };
+  stream.on("data", write);
+  stream.once("end", flush);
+  return flush;
+}
+
+function validateRuntime(packageRoot, side) {
+  for (const item of ["app.js", "runtime/worker.cjs"]) {
+    if (!fs.existsSync(path.join(packageRoot, item)))
+      throw new Error(`Incomplete ${side} package: missing ${item}.`);
+  }
+  const plugins = resolveNpmPlugins(packageRoot, side, { skipInvalid: true });
+  for (const id of [
+    "i18n",
+    "storage",
+    "runtime",
+    "server",
+    ...(side === "panel" ? ["console"] : [])
+  ]) {
+    if (!plugins.some((plugin) => plugin.id === id))
+      throw new Error(`Incomplete ${side} installation: missing npm plugin ${id}.`);
+  }
+  if (side === "panel" && !fs.existsSync(path.join(packageRoot, "public/index.html"))) {
+    throw new Error("Incomplete panel package: missing public/index.html.");
+  }
+}
+
+function planWorkers(side, packageRoot, options) {
+  const project = path.resolve(options.cwd || process.cwd());
+  const panelDirectory = runtimeDirectory(project, options["panel-dir"], "panel");
+  const daemonDirectory = runtimeDirectory(project, options["daemon-dir"], "daemon");
+  const workers = [];
+  if (side === "panel" && options.withDaemon) {
+    let daemonRoot;
+    try {
+      const projectRequire = createRequire(path.join(project, "package.json"));
+      daemonRoot = path.dirname(projectRequire.resolve("@elementspanel/daemon/package.json"));
+    } catch {
+      throw new Error(
+        "The project needs @elementspanel/daemon. Run npm install @elementspanel/daemon or start without --with-daemon."
+      );
+    }
+    if (panelDirectory === daemonDirectory)
+      throw new Error("Panel and daemon need different runtime directories.");
+    workers.push({ side: "daemon", packageRoot: daemonRoot, directory: daemonDirectory });
+  }
+  workers.push({
+    side,
+    packageRoot,
+    directory: side === "panel" ? panelDirectory : daemonDirectory
+  });
+  for (const worker of workers) validateRuntime(worker.packageRoot, worker.side);
+  return {
+    workers,
+    project,
+    localDaemonConfig: options.withDaemon
+      ? path.join(daemonDirectory, "data/Config/global.json")
+      : undefined
+  };
+}
+
+/** Supervise foreground workers. No shells, detached children or background servers. */
+async function startWorkers(plan, options = {}) {
+  if (!plan.workers.length) throw new Error("No runtime was selected.");
+  const startupTimeout = options.startupTimeout ?? 120_000;
+  const shutdownTimeout = options.shutdownTimeout ?? 90_000;
+  const children = new Set();
+  let stopping = false;
+  let exitCode = 0;
+  let forceTimer;
+  let done;
+  const finished = new Promise((resolve) => {
+    done = resolve;
+  });
+  const finish = () => {
+    if (!stopping || children.size) return;
+    clearTimeout(forceTimer);
+    done(exitCode);
+  };
+  const forceStop = () => {
+    for (const child of children) child.kill("SIGKILL");
+  };
+  const stop = (code = 0) => {
+    if (stopping) return;
+    stopping = true;
+    exitCode = code;
+    for (const child of children) {
+      if (child.connected)
+        child.send({ type: "elementspanel:stop" }, (error) => {
+          if (error && children.has(child)) child.kill("SIGTERM");
+        });
+      else child.kill("SIGTERM");
+    }
+    forceTimer = setTimeout(forceStop, shutdownTimeout);
+    forceTimer.unref();
+    finish();
+  };
+  const onSignal = () => (stopping ? forceStop() : stop(0));
+  const onInput = (data) => {
+    if (data.toString().trim().toLowerCase() === "exit") stop(0);
+  };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  process.stdin.on("data", onInput);
+  process.stdin.resume();
+
+  try {
+    for (const worker of plan.workers) {
+      if (stopping) break;
+      fs.mkdirSync(worker.directory, { recursive: true });
+      if (worker.side === "daemon") {
+        await ensureRuntimeTools(worker.directory, {
+          onDownload: (spec) =>
+            console.log(`${workerPrefix("daemon", process.stdout)}Downloading ${spec.filename}...`)
+        });
+      }
+      const environment = workerEnvironment(plan, worker);
+      const child = fork(
+        path.join(worker.packageRoot, "runtime/worker.cjs"),
+        options.open && worker.side === "panel" ? ["--open"] : [],
+        {
+          cwd: worker.directory,
+          env: environment,
+          execArgv: ["--enable-source-maps"],
+          stdio: ["ignore", "pipe", "pipe", "ipc"]
+        }
+      );
+      const flushOutput = [
+        pipeWorkerOutput(child.stdout, process.stdout, worker.side),
+        pipeWorkerOutput(child.stderr, process.stderr, worker.side)
+      ];
+      children.add(child);
+      let rejectReady;
+      child.on("error", (error) => {
+        if (!stopping) console.error(error.message);
+        rejectReady?.(error);
+        stop(1);
+      });
+      child.once("close", (code, signal) => {
+        flushOutput.forEach((flush) => flush());
+        children.delete(child);
+        const starting = Boolean(rejectReady);
+        const error = new Error(`${worker.side} exited before becoming ready (${signal || code}).`);
+        if (starting && !stopping) console.error(error.message);
+        rejectReady?.(error);
+        if (!stopping) stop(starting || code !== 0 ? 1 : 0);
+        finish();
+      });
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(
+          () =>
+            settle(
+              new Error(
+                `${worker.side} did not become ready within ${startupTimeout / 1000} seconds.`
+              )
+            ),
+          startupTimeout
+        );
+        const onMessage = (message) => {
+          if (message?.type === "elementspanel:ready") settle();
+        };
+        const settle = (error) => {
+          clearTimeout(timer);
+          child.off("message", onMessage);
+          rejectReady = undefined;
+          if (error) reject(error);
+          else resolve();
+        };
+        rejectReady = settle;
+        child.on("message", onMessage);
+      });
+    }
+  } catch (error) {
+    if (!stopping) {
+      console.error(error.message);
+      stop(1);
+    }
+  }
+  try {
+    return await finished;
+  } finally {
+    clearTimeout(forceTimer);
+    process.off("SIGINT", onSignal);
+    process.off("SIGTERM", onSignal);
+    process.stdin.off("data", onInput);
+    process.stdin.pause();
+  }
+}
+
+async function run(side, packageRoot, argv = process.argv.slice(2)) {
+  try {
+    const options = parseArgs([...argv], side);
+    if (options.command === "help") return void console.log(help(side));
+    const metadata = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+    if (options.command === "version") return void console.log(metadata.version);
+    if (typeof registerHooks !== "function")
+      throw new Error("ElementsPanel requires Node.js 22.15 or newer.");
+    process.exitCode = await startWorkers(planWorkers(side, packageRoot, options), options);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  parseArgs,
+  planWorkers,
+  startWorkers,
+  pipeWorkerOutput,
+  workerEnvironment,
+  run
+};

package/runtime/daemon-tools.cjs

@@ -0,0 +1,113 @@
+const fs = require("node:fs");
+const http = require("node:http");
+const https = require("node:https");
+const path = require("node:path");
+
+const sources = [
+  ["file_zip", "linux", "arm64", "file_zip_linux_arm64", "https://github.com/MCSManager/Zip-Tools/releases/latest/download/file_zip_linux_arm64"],
+  ["file_zip", "linux", "x64", "file_zip_linux_x64", "https://github.com/MCSManager/Zip-Tools/releases/latest/download/file_zip_linux_x64"],
+  ["file_zip", "win32", "x64", "file_zip_win32_x64.exe", "https://github.com/MCSManager/Zip-Tools/releases/latest/download/file_zip_win32_x64.exe"],
+  ["file_zip", "darwin", "arm64", "file_zip_darwin_arm64", "https://github.com/MCSManager/Zip-Tools/releases/latest/download/file_zip_darwin_arm64"],
+  ["file_zip", "darwin", "x64", "file_zip_darwin_amd64", "https://github.com/MCSManager/Zip-Tools/releases/latest/download/file_zip_darwin_amd64"],
+  ["7z", "linux", "arm64", "7z_linux_arm64", "https://github.com/MCSManager/Zip-Tools/releases/latest/download/7z_linux_arm64"],
+  ["7z", "linux", "x64", "7z_linux_x64", "https://github.com/MCSManager/Zip-Tools/releases/latest/download/7z_linux_x64"],
+  ["7z", "win32", "arm64", "7z_win32_arm64.exe", "https://github.com/MCSManager/Zip-Tools/releases/latest/download/7z_win32_arm64.exe"],
+  ["7z", "win32", "x64", "7z_win32_x64.exe", "https://github.com/MCSManager/Zip-Tools/releases/latest/download/7z_win32_x64.exe"],
+  ["7z", "darwin", "arm64", "7z_darwin_arm64", "https://github.com/MCSManager/Zip-Tools/releases/latest/download/7z_darwin_arm64"],
+  ["7z", "darwin", "x64", "7z_darwin_x64", "https://github.com/MCSManager/Zip-Tools/releases/latest/download/7z_darwin_x64"],
+  ["pty", "linux", "arm64", "pty_linux_arm64", "https://github.com/MCSManager/PTY/releases/download/latest/pty_linux_arm64"],
+  ["pty", "linux", "loong64", "pty_linux_loong64", "https://github.com/MCSManager/PTY/releases/download/latest/pty_linux_loong64"],
+  ["pty", "linux", "x64", "pty_linux_x64", "https://github.com/MCSManager/PTY/releases/download/latest/pty_linux_x64"],
+  ["pty", "win32", "x64", "pty_win32_x64.exe", "https://github.com/MCSManager/PTY/releases/download/latest/pty_win32_x64.exe"],
+  ["pty", "darwin", "arm64", "pty_darwin_arm64", "https://github.com/MCSManager/PTY/releases/download/latest/pty_darwin_arm64"],
+  ["pty", "darwin", "x64", "pty_darwin_x64", "https://github.com/MCSManager/PTY/releases/download/latest/pty_darwin_x64"]
+].map(([name, platform, arch, filename, url]) => ({ name, platform, arch, filename, url }));
+
+const requiredTools = ["file_zip", "pty", "7z"];
+
+function toolSpec(name, platform = process.platform, arch = process.arch) {
+  return sources.find((item) => item.name === name && item.platform === platform && item.arch === arch);
+}
+
+function toolPath(directory, name, platform = process.platform, arch = process.arch) {
+  const spec = toolSpec(name, platform, arch);
+  return spec ? path.join(directory, "lib", spec.filename) : undefined;
+}
+
+function downloadFile(url, target, redirects = 0) {
+  if (redirects > 5) return Promise.reject(new Error(`Too many redirects while downloading ${url}.`));
+  const client = url.startsWith("https:") ? https : http;
+  return new Promise((resolve, reject) => {
+    const temporary = `${target}.download-${process.pid}-${Date.now()}`;
+    let settled = false;
+    const cleanup = () => fs.rm(temporary, { force: true }, () => {});
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+    const request = client.get(url, { headers: { "User-Agent": "ElementsPanel daemon" } }, (response) => {
+      const status = response.statusCode || 0;
+      if (status >= 300 && status < 400 && response.headers.location) {
+        response.resume();
+        downloadFile(new URL(response.headers.location, url).href, target, redirects + 1).then(resolve, reject);
+        return;
+      }
+      if (status < 200 || status >= 300) {
+        response.resume();
+        fail(new Error(`Download failed (${status}) for ${url}.`));
+        return;
+      }
+      const output = fs.createWriteStream(temporary, { flags: "wx" });
+      output.on("error", fail);
+      response.on("error", fail);
+      output.once("finish", () => {
+        output.close(() => {
+          if (settled) return;
+          fs.chmod(temporary, process.platform === "win32" ? 0o666 : 0o755, (chmodError) => {
+            if (chmodError) return fail(chmodError);
+            fs.rename(temporary, target, (renameError) => {
+              if (renameError) return fail(renameError);
+              settled = true;
+              resolve();
+            });
+          });
+        });
+      });
+      response.pipe(output);
+    });
+    request.on("error", fail);
+  });
+}
+
+function usable(filename) {
+  try {
+    return fs.statSync(filename).isFile() && fs.statSync(filename).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureRuntimeTools(directory, options = {}) {
+  const targetDirectory = path.join(directory, "lib");
+  fs.mkdirSync(targetDirectory, { recursive: true });
+  const download = options.download || downloadFile;
+  for (const name of requiredTools) {
+    const spec = toolSpec(name, options.platform || process.platform, options.arch || process.arch);
+    if (!spec) {
+      throw new Error(
+        `No daemon binary download is available for ${name} on ${options.platform || process.platform}/${options.arch || process.arch}.`
+      );
+    }
+    const target = path.join(targetDirectory, spec.filename);
+    if (usable(target)) continue;
+    fs.rmSync(target, { force: true });
+    options.onDownload?.(spec);
+    await download(spec.url, target);
+    if (!usable(target)) throw new Error(`Downloaded daemon binary is empty: ${spec.filename}.`);
+  }
+  return targetDirectory;
+}
+
+module.exports = { requiredTools, sources, toolSpec, toolPath, downloadFile, ensureRuntimeTools };

package/runtime/npm-plugins.cjs

@@ -0,0 +1,176 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { createRequire } = require("node:module");
+
+const readJson = (filename) => JSON.parse(fs.readFileSync(filename, "utf8"));
+const readOptional = (filename) => {
+  try {
+    return readJson(filename);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+};
+const validId = /^[a-z][a-z0-9_-]{1,63}$/;
+const validName = /^(?:@[a-z0-9_.-]+\/)?epanel-plugin-[a-z0-9_.-]+$/;
+
+function within(root, filename) {
+  const relative = path.relative(root, filename);
+  return (
+    relative === "" ||
+    (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+  );
+}
+
+function projectRoot(packageRoot) {
+  if (process.env.EPANEL_PROJECT_ROOT) return path.resolve(process.env.EPANEL_PROJECT_ROOT);
+  const parent = path.resolve(packageRoot, "..");
+  // An installed runtime sits at <project>/node_modules/@scope/<side>; the
+  // project itself is three levels above the package. A development checkout
+  // sits directly under the project instead.
+  const scope = parent;
+  const nodeModules = path.dirname(scope);
+  if (path.basename(nodeModules) === "node_modules" && path.basename(scope).startsWith("@")) {
+    return path.dirname(nodeModules);
+  }
+  return parent;
+}
+
+function projectManifestFile(packageRoot) {
+  const root = projectRoot(packageRoot);
+  const filename = path.join(root, "package.json");
+  return path.resolve(filename) === path.resolve(path.join(packageRoot, "package.json"))
+    ? null
+    : filename;
+}
+
+function mappingOf(manifest) {
+  const plugins = manifest?.elementspanel?.plugins;
+  return plugins && typeof plugins === "object" && !Array.isArray(plugins) ? plugins : {};
+}
+
+function dependenciesOf(manifest) {
+  const dependencies = manifest?.dependencies;
+  return dependencies && typeof dependencies === "object" ? dependencies : {};
+}
+
+/**
+ * Resolve declared plugins through the host's dependency graph, including nested
+ * installs and project-level dependencies installed by the plugin market. The
+ * resolver also returns whether the mapping belongs to the built-in or project
+ * installation layer, so project plugins can remain dormant until enabled.
+ * Runtime startup passes skipInvalid so an optional package being removed does
+ * not stop the host; the caller separately validates the small set of core
+ * plugins.
+ */
+function resolveNpmPlugins(packageRoot, side, options = {}) {
+  const skipInvalid = options.skipInvalid === true;
+  const host = readJson(path.join(packageRoot, "package.json"));
+  const projectFile = projectManifestFile(packageRoot);
+  const project = projectFile ? readOptional(projectFile) : null;
+  const selectedSide = side || host.elementspanel?.side;
+
+  // Project mappings are read first so the host's built-in plugins win an id
+  // collision: a market package must not shadow a plugin that ships with the runtime.
+  const configured = new Map();
+  for (const [id, name] of Object.entries(mappingOf(project))) configured.set(id, { name, source: "project" });
+  for (const [id, name] of Object.entries(mappingOf(host))) configured.set(id, { name, source: "bundled" });
+
+  const hostDependencies = dependenciesOf(host);
+  const projectDependencies = dependenciesOf(project);
+  const roots = [packageRoot];
+  const parentRoot = projectRoot(packageRoot);
+  if (path.resolve(parentRoot) !== path.resolve(packageRoot)) roots.push(parentRoot);
+  const requireAt = (root) => createRequire(path.join(root, "package.json"));
+  const folders = new Set();
+  const records = [];
+
+  for (const [id, mapping] of configured) {
+    const name = mapping.name;
+    if (
+      !validId.test(id) ||
+      typeof name !== "string" ||
+      !validName.test(name) ||
+      (hostDependencies[name] === undefined && projectDependencies[name] === undefined)
+    ) {
+      if (skipInvalid) continue;
+      throw new Error(`Invalid npm plugin dependency: ${id}.`);
+    }
+
+    let manifestPath;
+    let failure;
+    for (const root of roots) {
+      try {
+        manifestPath = requireAt(root).resolve(`${name}/package.json`);
+        break;
+      } catch (error) {
+        failure = error;
+      }
+    }
+    if (!manifestPath) {
+      if (skipInvalid) continue;
+      throw new Error(`Missing npm plugin ${name}. Run npm install in the project directory.`, {
+        cause: failure
+      });
+    }
+    let metadata;
+    try {
+      metadata = readJson(manifestPath);
+    } catch (error) {
+      if (skipInvalid) continue;
+      throw error;
+    }
+    const definition = metadata.elementspanel?.[selectedSide];
+    // A project dependency may only ship one side; the other side simply does
+    // not see it. A built-in plugin declared by the runtime must carry this side.
+    if (!definition) {
+      if (mapping.source === "project" || skipInvalid) continue;
+      throw new Error(`Invalid ${selectedSide} entry in npm plugin ${name}.`);
+    }
+    const pluginRoot = path.dirname(manifestPath);
+    if (
+      typeof definition.directory !== "string" ||
+      typeof definition.folder !== "string" ||
+      !validId.test(definition.folder) ||
+      path.isAbsolute(definition.directory)
+    ) {
+      if (skipInvalid) continue;
+      throw new Error(`Npm plugin entry escapes its package: ${name}.`);
+    }
+    const directory = path.resolve(pluginRoot, definition.directory);
+    if (directory === pluginRoot || !within(pluginRoot, directory)) {
+      if (skipInvalid) continue;
+      throw new Error(`Npm plugin entry escapes its package: ${name}.`);
+    }
+    let manifest;
+    try {
+      manifest = readJson(path.join(directory, "plugin.json"));
+    } catch (error) {
+      if (skipInvalid) continue;
+      throw error;
+    }
+    if (manifest.id !== id || manifest.version !== metadata.version) {
+      if (skipInvalid) continue;
+      throw new Error(`Npm plugin identity or version does not match its manifest: ${name}.`);
+    }
+    if (folders.has(definition.folder)) {
+      if (skipInvalid) continue;
+      throw new Error(`Duplicate npm plugin asset directory: ${definition.folder}.`);
+    }
+    folders.add(definition.folder);
+    records.push({
+      id,
+      name,
+      version: metadata.version,
+      source: mapping.source,
+      defaultEnabled: mapping.source !== "project",
+      packageRoot: pluginRoot,
+      directory,
+      folder: definition.folder,
+      dependencies: Object.keys(metadata.dependencies || {})
+    });
+  }
+  return records;
+}
+
+module.exports = { resolveNpmPlugins, projectManifestFile };