@37chengshan/ompweb 0.3.5

package/bin/network-addresses.js

@@ -0,0 +1,197 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const os = require("os");
+
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1", "[::1]", "0:0:0:0:0:0:0:1", "[0:0:0:0:0:0:0:1]"]);
+const WILDCARD_HOSTNAMES = new Set(["0.0.0.0", "::", "[::]", "0:0:0:0:0:0:0:0", "[0:0:0:0:0:0:0:0]", ""]);
+
+function isWildcardHost(hostname) {
+  if (hostname == null) return true;
+  if (typeof hostname !== "string") return false;
+  return WILDCARD_HOSTNAMES.has(hostname.trim());
+}
+
+function isLoopbackHost(hostname) {
+  if (typeof hostname !== "string") return false;
+  const h = hostname.trim().toLowerCase();
+  if (h.startsWith("127.")) return true;
+  return LOOPBACK_HOSTNAMES.has(h);
+}
+function getBrowserUrl(hostname, port) {
+  if (isWildcardHost(hostname)) {
+    return `http://localhost:${port}`;
+  }
+  if (typeof hostname === "string" && hostname.includes(":") && !hostname.startsWith("[")) {
+    return `http://[${hostname}]:${port}`;
+  }
+  return `http://${hostname}:${port}`;
+}
+
+function isTailscaleAddress(ifaceName, address) {
+  if (typeof ifaceName === "string" && ifaceName.toLowerCase().includes("tailscale")) {
+    return true;
+  }
+  // Tailscale IPv4 uses CGNAT range 100.64.0.0/10 (100.64.0.0 to 100.127.255.255)
+  if (typeof address === "string") {
+    const parts = address.split(".").map(Number);
+    if (parts.length === 4 && parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isIgnoredAddress(ifaceName, address) {
+  if (!address || typeof address !== "string") return true;
+  // APIPA (Automatic Private IP Addressing: 169.254.0.0/16)
+  if (address.startsWith("169.254.")) return true;
+  // RFC 2544 benchmark / TUN proxy fake-ip range (198.18.0.0/15)
+  if (/^198\.(18|19)\./.test(address)) return true;
+  // Loopback
+  if (address.startsWith("127.")) return true;
+  return false;
+}
+
+function isVirtualBridge(ifaceName) {
+  if (!ifaceName || typeof ifaceName !== "string") return false;
+  const name = ifaceName.toLowerCase();
+  return (
+    name.includes("vethernet") ||
+    name.includes("veth") ||
+    name.includes("wsl") ||
+    name.includes("docker") ||
+    name.includes("hyper-v") ||
+    name.includes("vmware") ||
+    name.includes("virtualbox") ||
+    name.includes("virbr")
+  );
+}
+
+function isStandardPhysicalInterface(name) {
+  if (!name || typeof name !== "string") return false;
+  if (isVirtualBridge(name)) return false;
+  const lower = name.toLowerCase();
+  return (
+    lower.includes("以太网") ||
+    lower.includes("ethernet") ||
+    lower.includes("wi-fi") ||
+    lower.includes("wifi") ||
+    lower.includes("wlan") ||
+    lower.includes("无线") ||
+    /^en\d+$/.test(lower) ||
+    /^eth\d+$/.test(lower) ||
+    /^wlan\d+$/.test(lower) ||
+    /^enp\d+s\d+/.test(lower) ||
+    /^wlp\d+s\d+/.test(lower)
+  );
+}
+
+function getAccessibleAddresses({ hostname, port, interfaces = os.networkInterfaces() }) {
+  if (isLoopbackHost(hostname)) {
+    return {
+      entries: [{ label: "Local", url: `http://localhost:${port}` }],
+      hint: "use -H 0.0.0.0 to expose to the network",
+    };
+  }
+
+  if (!isWildcardHost(hostname)) {
+    return {
+      entries: [{ label: "Network", url: `http://${hostname}:${port}` }],
+    };
+  }
+
+  const entries = [{ label: "Local", url: `http://localhost:${port}` }];
+  const lanEntries = [];
+  const tailscaleEntries = [];
+  const otherEntries = [];
+  const seenAddresses = new Set(["127.0.0.1", "localhost"]);
+
+  for (const [name, addrs] of Object.entries(interfaces)) {
+    if (!addrs || !Array.isArray(addrs)) continue;
+    for (const info of addrs) {
+      if (info.family !== "IPv4" && info.family !== 4) continue;
+      if (info.internal) continue;
+      const addr = info.address;
+      if (seenAddresses.has(addr)) continue;
+      if (isIgnoredAddress(name, addr)) continue;
+
+      seenAddresses.add(addr);
+
+      if (isTailscaleAddress(name, addr)) {
+        tailscaleEntries.push({
+          label: "Tailscale",
+          url: `http://${addr}:${port}`,
+          name,
+          address: addr,
+        });
+      } else if (isStandardPhysicalInterface(name)) {
+        lanEntries.push({
+          label: "Network",
+          url: `http://${addr}:${port}`,
+          name,
+          address: addr,
+        });
+      } else {
+        otherEntries.push({
+          label: name,
+          url: `http://${addr}:${port}`,
+          name,
+          address: addr,
+        });
+      }
+    }
+  }
+
+  entries.push(...lanEntries, ...tailscaleEntries, ...otherEntries);
+  return { entries };
+}
+
+function formatAddressBanner({
+  version = "0.0.0",
+  entries = [],
+  hint,
+  passwordEnabled = false,
+  isTTY = process.stdout.isTTY,
+}) {
+  const dim = isTTY ? (s) => `\x1b[90m${s}\x1b[0m` : (s) => s;
+  const bold = isTTY ? (s) => `\x1b[1m${s}\x1b[0m` : (s) => s;
+  const green = isTTY ? (s) => `\x1b[32m${s}\x1b[0m` : (s) => s;
+  const cyan = isTTY ? (s) => `\x1b[36m${s}\x1b[0m` : (s) => s;
+
+  const lines = [];
+  lines.push("");
+  lines.push(`  ${bold("ompweb")} ${dim(`v${version}`)} ${green("is ready")}`);
+  lines.push("");
+
+  const maxLabelLen = Math.max(...entries.map((e) => e.label.length), hint ? 7 : 5);
+  for (const entry of entries) {
+    const padLabel = (entry.label + ":").padEnd(maxLabelLen + 2, " ");
+    lines.push(`  ${green("➜")}  ${bold(padLabel)} ${cyan(entry.url)}`);
+  }
+
+  if (hint) {
+    const padLabel = ("Network:").padEnd(maxLabelLen + 2, " ");
+    lines.push(`  ${dim("➜")}  ${dim(padLabel)} ${dim(hint)}`);
+  }
+
+  if (passwordEnabled) {
+    lines.push("");
+    lines.push(`  ${dim("🔒 Password protection enabled (OMP_WEB_PASSWORD)")}`);
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+module.exports = {
+  isWildcardHost,
+  isLoopbackHost,
+  getBrowserUrl,
+  isTailscaleAddress,
+  isIgnoredAddress,
+  isStandardPhysicalInterface,
+  isVirtualBridge,
+  getAccessibleAddresses,
+  formatAddressBanner,
+};

package/bin/node-version.js

@@ -0,0 +1,35 @@
+"use strict";
+
+const MIN_NODE_VERSION = "22.19.0";
+
+function parseNodeVersion(version) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version);
+  if (!match) return null;
+  return match.slice(1).map(Number);
+}
+
+function isNodeVersionSupported(version) {
+  const current = parseNodeVersion(version);
+  const minimum = parseNodeVersion(MIN_NODE_VERSION);
+  if (!current || !minimum) return false;
+
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (current[index] > minimum[index]) return true;
+    if (current[index] < minimum[index]) return false;
+  }
+  return true;
+}
+
+function getUnsupportedNodeVersionMessage(version) {
+  return [
+    `ompweb requires Node.js ${MIN_NODE_VERSION} or newer.`,
+    `Current Node.js version: ${version}.`,
+    "Upgrade Node.js and try again: https://nodejs.org/",
+  ].join("\n");
+}
+
+module.exports = {
+  MIN_NODE_VERSION,
+  getUnsupportedNodeVersionMessage,
+  isNodeVersionSupported,
+};

package/bin/omp-web-options.js

@@ -0,0 +1,86 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseArgs } = require("util");
+
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+
+function isEnabled(value) {
+  return typeof value === "string" && TRUE_VALUES.has(value.trim().toLowerCase());
+}
+
+
+function printHelp() {
+  console.log(`Usage: ompweb [options]
+
+Options:
+  -p, --port <port>        Server port (default 30177, env PORT)
+  -H, --hostname <host>    Bind hostname (default 127.0.0.1, env OMP_WEB_HOSTNAME)
+      --password <pass>    Password for the web sign-in screen (env OMP_WEB_PASSWORD)
+      --no-open            Do not open the browser automatically
+  -h, --help               Show this help
+      --version            Show version
+
+Password:
+  ompweb --password "a-long-random-password"
+  # env-variable forms (POSIX, PowerShell, CMD handled uniformly)
+  OMP_WEB_PASSWORD="secret" ompweb
+  $env:OMP_WEB_PASSWORD="secret"; ompweb   # PowerShell
+  set OMP_WEB_PASSWORD=secret&& ompweb     # CMD
+
+Security: use HTTPS via a trusted reverse proxy or VPN when binding to a
+non-loopback hostname, so the password and session cookie stay private.`);
+}
+
+function parseLaunchOptions(args = process.argv.slice(2), env = process.env) {
+  const { values: cliArgs } = parseArgs({
+    args,
+    options: {
+      port:      { type: "string", short: "p" },
+      hostname:  { type: "string", short: "H" },
+      password:  { type: "string" },
+      help:      { type: "boolean", short: "h" },
+      version:   { type: "boolean" },
+      "no-open": { type: "boolean" },
+    },
+    strict: false,
+  });
+
+  // --password wins over env so Windows users without POSIX inline-env syntax have a first-class option.
+  const password = cliArgs.password ?? env.OMP_WEB_PASSWORD;
+  if (cliArgs.version) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const pkg = require("../package.json");
+      console.log(pkg.version ?? "0.0.0");
+    } catch { console.log("0.0.0"); }
+    return {
+      port: cliArgs.port ?? env.PORT ?? "30177",
+      hostname: cliArgs.hostname ?? env.OMP_WEB_HOSTNAME ?? "127.0.0.1",
+      password,
+      openBrowser: !cliArgs["no-open"] && !isEnabled(env.OMP_WEB_NO_OPEN),
+      version: true,
+    };
+  }
+  // Expose help flag without exiting here — caller (bin/omp-web.js) decides
+  // whether to exit, keeping parseLaunchOptions testable. Print here so
+  // --help works even when the caller is a test.
+  if (cliArgs.help) {
+    printHelp();
+    return {
+      port: cliArgs.port ?? env.PORT ?? "30177",
+      hostname: cliArgs.hostname ?? env.OMP_WEB_HOSTNAME ?? "127.0.0.1",
+      password,
+      openBrowser: !cliArgs["no-open"] && !isEnabled(env.OMP_WEB_NO_OPEN),
+      help: true,
+    };
+  }
+  return {
+    port: cliArgs.port ?? env.PORT ?? "30177",
+    hostname: cliArgs.hostname ?? env.OMP_WEB_HOSTNAME ?? "127.0.0.1",
+    password,
+    openBrowser: !cliArgs["no-open"] && !isEnabled(env.OMP_WEB_NO_OPEN),
+  };
+}
+
+module.exports = { parseLaunchOptions };

package/bin/omp-web-security.test.mjs

@@ -0,0 +1,9 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+test("launcher refuses unauthenticated non-loopback binds", async () => {
+  const source = await readFile(new URL("./omp-web.js", import.meta.url), "utf8");
+  assert.match(source, /Refusing to listen on/);
+  assert.match(source, /!passwordEnabled/);
+});

package/bin/omp-web.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { getUnsupportedNodeVersionMessage, isNodeVersionSupported } = require("./node-version");
+
+if (!isNodeVersionSupported(process.versions.node)) {
+  console.error(getUnsupportedNodeVersionMessage(process.versions.node));
+  process.exit(1);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { spawn } = require("child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require("path");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fs = require("fs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseLaunchOptions } = require("./omp-web-options");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { isPortAvailable } = require("./port-availability");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { wireChildProcessLifecycle } = require("./process-lifecycle");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { getAccessibleAddresses, getBrowserUrl, formatAddressBanner, isLoopbackHost } = require("./network-addresses");
+
+const pkgDir = path.join(__dirname, "..");
+const nextDir = path.join(pkgDir, ".next");
+
+// Resolve next's CLI entry directly to avoid relying on .bin symlinks (which
+// may not exist when installed via npx).
+let nextBin;
+try {
+  nextBin = require.resolve("next/dist/bin/next", { paths: [pkgDir] });
+} catch {
+  // Fallback: locate next package root and derive the bin path manually.
+  try {
+    const nextPkg = require.resolve("next/package.json", { paths: [pkgDir] });
+    nextBin = path.join(path.dirname(nextPkg), "dist", "bin", "next");
+  } catch {
+    nextBin = path.join(pkgDir, "node_modules", "next", "dist", "bin", "next");
+  }
+}
+
+let pkgVersion = "0.0.0";
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const pkg = require("../package.json");
+  pkgVersion = pkg.version ?? "0.0.0";
+} catch { /* ignore */ }
+
+const launchOptions = parseLaunchOptions();
+if (launchOptions.help || launchOptions.version) {
+  process.exit(0);
+}
+const port = launchOptions.port;
+const hostname = launchOptions.hostname;
+const password = launchOptions.password;
+const openBrowser = launchOptions.openBrowser;
+// Propagate --password into the env for proxy.ts / lib/web-auth.ts and the spawned Next process.
+if (password) process.env.OMP_WEB_PASSWORD = password;
+const passwordEnabled = typeof password === "string" && password.length > 0;
+if (!fs.existsSync(nextDir)) {
+  console.error("Build artifacts not found. Please report this issue.");
+  process.exit(1);
+}
+
+if (!isLoopbackHost(hostname)) {
+  if (!passwordEnabled) {
+    console.error(`Refusing to listen on ${hostname} without OMP_WEB_PASSWORD (or --password). Set a strong password or bind to 127.0.0.1.`);
+    process.exit(1);
+  }
+  console.warn(`Warning: ompweb is listening on ${hostname} over HTTP. Use HTTPS or a trusted VPN to protect the password and session cookie in transit.`);
+}
+
+const nextArgs = ["start", "-p", port];
+nextArgs.push("-H", hostname);
+
+// Always run next's JS entry with node directly — avoids .bin symlink issues
+// and path-with-spaces problems on Windows when shell: true is used.
+const browserUrl = getBrowserUrl(hostname, port);
+async function main() {
+  if (!await isPortAvailable(port, hostname)) {
+    console.error(`Port ${port} on ${hostname} is already in use.`);
+    console.error(`If ompweb is already running, open ${browserUrl}. Otherwise, stop the process using it or run: ompweb --port ${Number(port) + 1}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const child = spawn(process.execPath, [nextBin, ...nextArgs], {
+    cwd: pkgDir,
+    stdio: ["inherit", "pipe", "inherit"],
+    env: {
+      ...process.env,
+      OMP_WEB_PACKAGE_DIR: pkgDir,
+      OMP_WEB_LAUNCHER_PID: String(process.pid),
+      OMP_WEB_PORT: port,
+      OMP_WEB_HOSTNAME: hostname,
+    },
+  });
+  wireChildProcessLifecycle(child);
+
+  let bannerPrinted = false;
+  let browserOpened = false;
+  let readyBuffer = "";
+  child.stdout.on("data", (chunk) => {
+    const text = chunk.toString();
+    process.stdout.write(text);
+    readyBuffer += text;
+    if (readyBuffer.length > 500) readyBuffer = readyBuffer.slice(-500);
+    if (readyBuffer.includes("Ready")) {
+      if (!bannerPrinted) {
+        bannerPrinted = true;
+        const { entries, hint } = getAccessibleAddresses({ hostname, port });
+        const banner = formatAddressBanner({
+          version: pkgVersion,
+          entries,
+          hint,
+          passwordEnabled,
+          isTTY: process.stdout.isTTY,
+        });
+        process.stdout.write(banner);
+      }
+      if (openBrowser && !browserOpened) {
+        browserOpened = true;
+        const isWindows = process.platform === "win32";
+        const isMac = process.platform === "darwin";
+        const openCmd = isWindows ? "explorer.exe" : isMac ? "open" : "xdg-open";
+        const opener = spawn(openCmd, [browserUrl], {
+          stdio: "ignore",
+          detached: true,
+        });
+
+        opener.on("error", (error) => {
+          console.warn(`Could not open browser automatically: ${error.message}`);
+        });
+
+        opener.unref();
+      }
+    }
+  });
+}
+
+main().catch((error) => {
+  console.error(`Could not check whether ${browserUrl} is available: ${error.message}`);
+  process.exit(1);
+});

package/bin/port-availability.js

@@ -0,0 +1,27 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const net = require("net");
+
+function isPortAvailable(port, hostname) {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+
+    server.once("error", (error) => {
+      if (error.code === "EADDRINUSE") {
+        resolve(false);
+      } else {
+        reject(error);
+      }
+    });
+
+    server.listen({ port: Number(port), host: hostname }, () => {
+      server.close((error) => {
+        if (error) reject(error);
+        else resolve(true);
+      });
+    });
+  });
+}
+
+module.exports = { isPortAvailable };

package/bin/process-lifecycle.js

@@ -0,0 +1,71 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const os = require("node:os");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { spawn } = require("node:child_process");
+
+const forwardedSignals = ["SIGINT", "SIGTERM"];
+const shutdownTimeoutMs = 5_000;
+
+function getSignalExitCode(signal) {
+  const signalNumber = signal ? os.constants.signals[signal] : undefined;
+  return typeof signalNumber === "number" ? 128 + signalNumber : 1;
+}
+
+function killChildTree(child, force, platform = process.platform) {
+  if (platform === "win32" && child.pid) {
+    const reaper = spawn("taskkill", ["/pid", String(child.pid), "/t", ...(force ? ["/f"] : [])], {
+      windowsHide: true,
+      stdio: "ignore",
+    });
+    reaper.once("error", () => {
+      try { child.kill(force ? "SIGKILL" : "SIGTERM"); } catch {}
+    });
+    reaper.unref?.();
+    return;
+  }
+
+  try { child.kill(force ? "SIGKILL" : "SIGTERM"); } catch {}
+}
+
+function wireChildProcessLifecycle(child, parentProcess = process, timeoutMs = shutdownTimeoutMs) {
+  const signalHandlers = new Map();
+  let shutdownTimer;
+  const platform = parentProcess.platform ?? process.platform;
+
+  const forceKill = () => killChildTree(child, true, platform);
+
+  for (const signal of forwardedSignals) {
+    const handler = () => {
+      if (shutdownTimer) {
+        forceKill();
+        return;
+      }
+
+      shutdownTimer = setTimeout(forceKill, timeoutMs);
+      shutdownTimer.unref?.();
+      try {
+        child.kill(signal);
+      } catch {
+        // Windows has limited signal support. Ask taskkill to terminate the
+        // child tree if the native signal could not be delivered.
+        if (platform === "win32") killChildTree(child, false, platform);
+      }
+    };
+    signalHandlers.set(signal, handler);
+    parentProcess.on(signal, handler);
+  }
+
+  child.once("exit", (code, signal) => {
+    if (shutdownTimer) clearTimeout(shutdownTimer);
+
+    for (const [forwardedSignal, handler] of signalHandlers) {
+      parentProcess.removeListener(forwardedSignal, handler);
+    }
+
+    parentProcess.exit(code ?? getSignalExitCode(signal));
+  });
+}
+
+module.exports = { wireChildProcessLifecycle };

package/bin/process-lifecycle.test.mjs

@@ -0,0 +1,83 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import test from "node:test";
+import { setTimeout as delay } from "node:timers/promises";
+
+import { wireChildProcessLifecycle } from "./process-lifecycle.js";
+
+function createProcesses() {
+  const parent = new EventEmitter();
+  const child = new EventEmitter();
+  const forwardedSignals = [];
+  const exitCodes = [];
+
+  child.kill = (signal) => {
+    forwardedSignals.push(signal);
+    return true;
+  };
+  parent.exit = (code) => {
+    exitCodes.push(code);
+  };
+
+  return { parent, child, forwardedSignals, exitCodes };
+}
+
+test("forwards the first shutdown signal and force-kills on repeated signals", () => {
+  const { parent, child, forwardedSignals } = createProcesses();
+
+  wireChildProcessLifecycle(child, parent);
+  parent.emit("SIGTERM");
+  parent.emit("SIGTERM");
+  parent.emit("SIGINT");
+
+  assert.deepEqual(forwardedSignals, ["SIGTERM", "SIGKILL", "SIGKILL"]);
+  child.emit("exit", null, "SIGKILL");
+});
+
+test("propagates a child exit code and clears its shutdown wiring", async () => {
+  const { parent, child, forwardedSignals, exitCodes } = createProcesses();
+  const existingSigtermListener = () => {};
+  parent.on("SIGTERM", existingSigtermListener);
+
+  wireChildProcessLifecycle(child, parent, 10);
+  assert.equal(parent.listenerCount("SIGINT"), 1);
+  assert.equal(parent.listenerCount("SIGTERM"), 2);
+
+  parent.emit("SIGTERM");
+  child.emit("exit", 23, null);
+  await delay(20);
+
+  assert.deepEqual(exitCodes, [23]);
+  assert.equal(parent.listenerCount("SIGINT"), 0);
+  assert.deepEqual(parent.listeners("SIGTERM"), [existingSigtermListener]);
+
+  parent.emit("SIGTERM");
+  assert.deepEqual(forwardedSignals, ["SIGTERM"]);
+});
+
+test("force-kills the child when graceful shutdown times out", async () => {
+  const { parent, child, forwardedSignals } = createProcesses();
+
+  wireChildProcessLifecycle(child, parent, 10);
+  parent.emit("SIGINT");
+  assert.deepEqual(forwardedSignals, ["SIGINT"]);
+
+  await delay(20);
+
+  assert.deepEqual(forwardedSignals, ["SIGINT", "SIGKILL"]);
+  child.emit("exit", null, "SIGKILL");
+});
+
+test("uses conventional exit statuses for known child signals", () => {
+  for (const [signal, expectedExitCode] of [
+    ["SIGTERM", 143],
+    ["SIGKILL", 137],
+  ]) {
+    const { parent, child, exitCodes } = createProcesses();
+
+    wireChildProcessLifecycle(child, parent);
+    child.emit("exit", null, signal);
+
+    assert.deepEqual(exitCodes, [expectedExitCode]);
+  }
+});