zevairouter 1.0.153 → 1.0.155

package/cli/src/cli/updateRuntimeState.js

@@ -0,0 +1,976 @@
+"use strict";
+
+const path = require("path");
+
+const DEFAULT_PORT = 1997;
+const DEFAULT_HOST = "127.0.0.1";
+const LAUNCH_AGENT_LABEL = "com.zevairouter.autostart";
+
+function normalizePort(value) {
+  const text = typeof value === "number" ? String(value) : String(value ?? "").trim();
+  if (!/^\d{1,5}$/.test(text)) return null;
+  const port = Number(text);
+  return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : null;
+}
+
+function readPortOption(args) {
+  const values = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = String(args[index]);
+    if (arg === "--port" || arg === "-p") {
+      values.push(normalizePort(args[index + 1]));
+      index += 1;
+    } else if (arg.startsWith("--port=")) {
+      values.push(normalizePort(arg.slice("--port=".length)));
+    }
+  }
+
+  const validValues = values.filter((value) => value != null);
+  const distinctValues = [...new Set(validValues)];
+  const invalid = values.some((value) => value == null);
+  const conflict = distinctValues.length > 1;
+  return {
+    specified: values.length > 0,
+    value: !invalid && !conflict && distinctValues.length === 1 ? distinctValues[0] : null,
+    invalid,
+    conflict,
+  };
+}
+
+function normalizeHost(value) {
+  const host = String(value ?? "").trim();
+  if (!host || host.length > 253 || host.startsWith("-")) return null;
+  if (!/^[A-Za-z0-9._:[\]%-]+$/.test(host)) return null;
+  return host;
+}
+
+function decodeSystemdHost(value) {
+  let decoded = "";
+  const encoded = String(value);
+  for (let index = 0; index < encoded.length; index += 1) {
+    if (encoded[index] !== "%") {
+      decoded += encoded[index];
+      continue;
+    }
+    if (encoded[index + 1] !== "%") return null;
+    decoded += "%";
+    index += 1;
+  }
+  return normalizeHost(decoded);
+}
+
+function readHostOption(args) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = String(args[index]);
+    if (arg === "--host" || arg === "-H") {
+      values.push(normalizeHost(args[index + 1]));
+      index += 1;
+    } else if (arg.startsWith("--host=")) {
+      values.push(normalizeHost(arg.slice("--host=".length)));
+    }
+  }
+
+  const validValues = values.filter((value) => value != null);
+  const distinctValues = [...new Set(validValues)];
+  const invalid = values.some((value) => value == null);
+  const conflict = distinctValues.length > 1;
+  return {
+    specified: values.length > 0,
+    value: !invalid && !conflict && distinctValues.length === 1 ? distinctValues[0] : null,
+    invalid,
+    conflict,
+  };
+}
+
+function explicitMode(args, env) {
+  const trayRequested = args.some((arg) => arg === "--tray" || arg === "-t")
+    || String(env.TRAY_MODE ?? "") === "1";
+  const serverRequested = (
+    String(env.ZEVAI_SERVER_MODE ?? "") === "1"
+    || args.some((arg) => arg === "--no-browser" || arg === "-n" || arg === "--log" || arg === "-l")
+  );
+  if (trayRequested && serverRequested) {
+    throw new Error("Conflicting update modes; choose either tray or server mode.");
+  }
+  return trayRequested ? "tray" : serverRequested ? "server" : null;
+}
+
+function splitCommandLine(command) {
+  const tokens = [];
+  let token = "";
+  let quote = null;
+  let escaped = false;
+  let started = false;
+
+  for (const character of String(command || "")) {
+    if (escaped) {
+      token += character;
+      escaped = false;
+      started = true;
+      continue;
+    }
+    if (character === "\\" && quote !== "'") {
+      escaped = true;
+      started = true;
+      continue;
+    }
+    if (quote) {
+      if (character === quote) quote = null;
+      else token += character;
+      started = true;
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      quote = character;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(character)) {
+      if (started) {
+        tokens.push(token);
+        token = "";
+        started = false;
+      }
+      continue;
+    }
+    token += character;
+    started = true;
+  }
+
+  if (escaped || quote) return null;
+  if (started) tokens.push(token);
+  return tokens;
+}
+
+function decodeXml(value) {
+  const decodeCodePoint = (raw, radix, original) => {
+    const codePoint = Number.parseInt(raw, radix);
+    if (!Number.isInteger(codePoint) || codePoint < 0 || codePoint > 0x10FFFF) return original;
+    if (codePoint >= 0xD800 && codePoint <= 0xDFFF) return original;
+    return String.fromCodePoint(codePoint);
+  };
+  return String(value)
+    .replace(/&#x([0-9a-f]+);/gi, (original, digits) => decodeCodePoint(digits, 16, original))
+    .replace(/&#(\d+);/g, (original, digits) => decodeCodePoint(digits, 10, original))
+    .replaceAll("&quot;", '"')
+    .replaceAll("&apos;", "'")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&amp;", "&");
+}
+
+function defaultCanonicalize(filePath) {
+  return path.resolve(String(filePath));
+}
+
+function samePath(candidate, expected, canonicalizePath = defaultCanonicalize) {
+  if (!candidate || !expected) return false;
+  try {
+    const left = canonicalizePath(candidate);
+    const right = canonicalizePath(expected);
+    return process.platform === "win32"
+      ? left.toLowerCase() === right.toLowerCase()
+      : left === right;
+  } catch {
+    return false;
+  }
+}
+
+function cliArgsFromTokens(tokens, cliPath, canonicalizePath) {
+  if (!Array.isArray(tokens) || tokens.length === 0) return null;
+  if (samePath(tokens[0], cliPath, canonicalizePath)) return tokens.slice(1);
+  if (
+    /^(?:node|nodejs)(?:\.exe)?$/i.test(path.basename(tokens[0]))
+    && samePath(tokens[1], cliPath, canonicalizePath)
+  ) {
+    return tokens.slice(2);
+  }
+  return null;
+}
+
+function hasTrayArg(args) {
+  return args.some((arg) => arg === "--tray" || arg === "-t");
+}
+
+function inferProcessMode(args, portSpecified) {
+  if (hasTrayArg(args)) return "tray";
+  if (
+    args.some((arg) => (
+      arg === "--no-browser"
+      || arg === "-n"
+      || arg === "--host"
+      || arg === "-H"
+      || arg === "--log"
+      || arg === "-l"
+    ))
+    || (portSpecified && args.includes("--skip-update"))
+  ) {
+    return "server";
+  }
+  return null;
+}
+
+const SYSTEMD_XVFB_PREFIX = 'if "';
+const SYSTEMD_XVFB_AFTER_XDPYINFO = '" -display :99 >/dev/null 2>&1; then :; else owner=0; for candidate in $$(pgrep -f "Xvfb[[:space:]]+:99([[:space:]]|$)" || true); do comm=$$(cat "/proc/$$candidate/comm" 2>/dev/null || true); exe=$$(readlink -f "/proc/$$candidate/exe" 2>/dev/null || true); if [ "$$comm" = Xvfb ] && [ -n "$$exe" ]; then owner=1; break; fi; done; [ "$$owner" = 0 ] || exit 1; rm -f /tmp/.X99-lock /tmp/.X11-unix/X99; "';
+const SYSTEMD_XVFB_AFTER_XVFB = '" :99 -screen 0 1280x900x24 -ac -nolisten tcp & pid=$$!; ready=0; for _ in {1..30}; do if "';
+const SYSTEMD_XVFB_AFTER_SECOND_XDPYINFO = '" -display :99 >/dev/null 2>&1; then ready=1; break; fi; kill -0 "$$pid" 2>/dev/null || exit 1; sleep 0.1; done; [ "$$ready" = 1 ] || exit 1; fi; exec ';
+const INSTALLER_SYSTEMD_BETWEEN_EXEC_PATHS = '" "';
+const INSTALLER_SYSTEMD_BEFORE_PORT = '" --port "';
+const INSTALLER_SYSTEMD_BEFORE_HOST = '" --host ';
+const INSTALLER_SYSTEMD_SUFFIX = ' --no-browser --skip-update --log';
+const UPDATER_SYSTEMD_EXEC_PREFIX = '"$$1" "$$2" --port "$$3" --host ';
+const LEGACY_UPDATER_SYSTEMD_PREFIX = `exec ${UPDATER_SYSTEMD_EXEC_PREFIX}`;
+const LEGACY_SOCKET_UPDATER_SYSTEMD_PREFIX = 'if command -v Xvfb >/dev/null 2>&1; then if pgrep -f "Xvfb[[:space:]]+:99([[:space:]]|$$)" >/dev/null; then [ -S /tmp/.X11-unix/X99 ] || exit 1; else rm -f /tmp/.X99-lock; Xvfb :99 -screen 0 1280x900x24 -ac -nolisten tcp >/var/log/xvfb-zevai.log 2>&1 & xvfb_pid=$$!; ready=0; for _ in {1..30}; do if [ -S /tmp/.X11-unix/X99 ]; then ready=1; break; fi; kill -0 "$$xvfb_pid" 2>/dev/null || exit 1; sleep 0.1; done; [ "$$ready" = 1 ] || exit 1; fi; fi; exec "$$1" "$$2" --port "$$3" --host ';
+const UPDATER_SYSTEMD_SUFFIX = ' --no-browser --skip-update --log';
+const LEGACY_INSTALLER_SYSTEMD_PREFIX = 'if pgrep -f "Xvfb[[:space:]]+:99([[:space:]]|$)" >/dev/null; then [ -S /tmp/.X11-unix/X99 ] || exit 1; else rm -f /tmp/.X99-lock; "';
+const LEGACY_INSTALLER_SYSTEMD_AFTER_XVFB = '" :99 -screen 0 1280x900x24 -ac -nolisten tcp >/var/log/xvfb-zevai.log 2>&1 & pid=$$!; ready=0; for _ in {1..30}; do if [ -S /tmp/.X11-unix/X99 ]; then ready=1; break; fi; kill -0 "$$pid" 2>/dev/null || exit 1; sleep 0.1; done; [ "$$ready" = 1 ] || exit 1; fi; exec "';
+
+function safeSystemdExecutablePath(filePath, basenamePattern) {
+  const value = String(filePath || "");
+  return path.isAbsolute(value)
+    && !/["'\\$`%\r\n]/.test(value)
+    && basenamePattern.test(path.basename(value));
+}
+
+function parseSystemdXvfbWrapper(script) {
+  let remaining = String(script || "");
+  if (!remaining.startsWith(SYSTEMD_XVFB_PREFIX)) return null;
+  remaining = remaining.slice(SYSTEMD_XVFB_PREFIX.length);
+  const takeUntil = (delimiter) => {
+    const delimiterIndex = remaining.indexOf(delimiter);
+    if (delimiterIndex < 0) return null;
+    const value = remaining.slice(0, delimiterIndex);
+    remaining = remaining.slice(delimiterIndex + delimiter.length);
+    return value;
+  };
+  const firstXdpyinfoPath = takeUntil(SYSTEMD_XVFB_AFTER_XDPYINFO);
+  const xvfbPath = takeUntil(SYSTEMD_XVFB_AFTER_XVFB);
+  const secondXdpyinfoPath = takeUntil(SYSTEMD_XVFB_AFTER_SECOND_XDPYINFO);
+  if (!firstXdpyinfoPath || !xvfbPath || !secondXdpyinfoPath) return null;
+  if (!safeSystemdExecutablePath(xvfbPath, /^Xvfb$/)) return null;
+  if (!safeSystemdExecutablePath(firstXdpyinfoPath, /^xdpyinfo$/)) return null;
+  if (!safeSystemdExecutablePath(secondXdpyinfoPath, /^xdpyinfo$/)) return null;
+  if (!samePath(firstXdpyinfoPath, secondXdpyinfoPath)) return null;
+  return { remaining, xvfbPath, xdpyinfoPath: firstXdpyinfoPath };
+}
+
+function parseExactUpdaterSystemdScript(script) {
+  if (
+    script.startsWith(LEGACY_SOCKET_UPDATER_SYSTEMD_PREFIX)
+    && script.endsWith(UPDATER_SYSTEMD_SUFFIX)
+  ) {
+    return decodeSystemdHost(script.slice(
+      LEGACY_SOCKET_UPDATER_SYSTEMD_PREFIX.length,
+      -UPDATER_SYSTEMD_SUFFIX.length,
+    ));
+  }
+  let executablePart = null;
+  let suffix = UPDATER_SYSTEMD_SUFFIX;
+  if (script.startsWith(LEGACY_UPDATER_SYSTEMD_PREFIX)) {
+    executablePart = script.slice("exec ".length);
+    suffix = "";
+  } else {
+    executablePart = parseSystemdXvfbWrapper(script)?.remaining ?? null;
+  }
+  if (
+    executablePart == null
+    || !executablePart.startsWith(UPDATER_SYSTEMD_EXEC_PREFIX)
+    || !executablePart.endsWith(suffix)
+  ) return null;
+  const hostEnd = suffix ? -suffix.length : executablePart.length;
+  return decodeSystemdHost(executablePart.slice(
+    UPDATER_SYSTEMD_EXEC_PREFIX.length,
+    hostEnd,
+  ));
+}
+
+function parseLegacyInstallerSystemdExec(tokens, options) {
+  let remaining = tokens[2];
+  if (!remaining.startsWith(LEGACY_INSTALLER_SYSTEMD_PREFIX)) return null;
+  remaining = remaining.slice(LEGACY_INSTALLER_SYSTEMD_PREFIX.length);
+  const takeUntil = (delimiter) => {
+    const delimiterIndex = remaining.indexOf(delimiter);
+    if (delimiterIndex < 0) return null;
+    const value = remaining.slice(0, delimiterIndex);
+    remaining = remaining.slice(delimiterIndex + delimiter.length);
+    return value;
+  };
+  const xvfbPath = takeUntil(LEGACY_INSTALLER_SYSTEMD_AFTER_XVFB);
+  const nodePath = takeUntil(INSTALLER_SYSTEMD_BETWEEN_EXEC_PATHS);
+  const cliPath = takeUntil(INSTALLER_SYSTEMD_BEFORE_PORT);
+  const portText = takeUntil(INSTALLER_SYSTEMD_BEFORE_HOST);
+  if (
+    xvfbPath == null
+    || nodePath == null
+    || cliPath == null
+    || portText == null
+    || !remaining.endsWith(INSTALLER_SYSTEMD_SUFFIX)
+  ) return null;
+  const port = normalizePort(portText);
+  const host = normalizeHost(remaining.slice(0, -INSTALLER_SYSTEMD_SUFFIX.length));
+  if (!safeSystemdExecutablePath(xvfbPath, /^Xvfb$/)) return null;
+  if (!safeSystemdExecutablePath(nodePath, /^(?:node|nodejs)(?:\.exe)?$/i)) return null;
+  if (!samePath(cliPath, options.cliPath, options.canonicalizePath)) return null;
+  return port != null && host != null ? { port, host } : null;
+}
+
+function parseInstallerSystemdExec(tokens, options) {
+  if (!Array.isArray(tokens) || tokens.length !== 3) return null;
+  if (tokens[1] !== "-c") return null;
+  if (!samePath(tokens[0], options.shellPath || "/bin/bash", options.canonicalizePath)) return null;
+
+  const wrapper = parseSystemdXvfbWrapper(tokens[2]);
+  if (!wrapper) return parseLegacyInstallerSystemdExec(tokens, options);
+  let { remaining } = wrapper;
+
+  const takeUntil = (delimiter) => {
+    const delimiterIndex = remaining.indexOf(delimiter);
+    if (delimiterIndex < 0) return null;
+    const value = remaining.slice(0, delimiterIndex);
+    remaining = remaining.slice(delimiterIndex + delimiter.length);
+    return value;
+  };
+  if (!remaining.startsWith('"')) return null;
+  remaining = remaining.slice(1);
+  const nodePath = takeUntil(INSTALLER_SYSTEMD_BETWEEN_EXEC_PATHS);
+  const cliPath = takeUntil(INSTALLER_SYSTEMD_BEFORE_PORT);
+  if (nodePath == null || cliPath == null) return null;
+  const portText = takeUntil(INSTALLER_SYSTEMD_BEFORE_HOST);
+  if (portText == null || !remaining.endsWith(INSTALLER_SYSTEMD_SUFFIX)) return null;
+  const port = normalizePort(portText);
+  const host = normalizeHost(remaining.slice(0, -INSTALLER_SYSTEMD_SUFFIX.length));
+
+  if (!safeSystemdExecutablePath(nodePath, /^(?:node|nodejs)(?:\.exe)?$/i)) return null;
+  if (!samePath(cliPath, options.cliPath, options.canonicalizePath)) return null;
+  if (port == null || host == null) return null;
+  return { port, host };
+}
+
+function parseSystemdCliExec(tokens, options) {
+  if (!Array.isArray(tokens) || !options.cliPath) return null;
+  const directArgs = cliArgsFromTokens(tokens, options.cliPath, options.canonicalizePath);
+  if (directArgs) {
+    return { port: null, host: null };
+  }
+
+  const shellMatches = samePath(
+    tokens[0],
+    options.shellPath || "/bin/bash",
+    options.canonicalizePath,
+  );
+  const nodeMatches = /^(?:node|nodejs)(?:\.exe)?$/i.test(path.basename(tokens[4] || ""));
+  const wrappedHost = parseExactUpdaterSystemdScript(tokens[2] || "");
+  const positionalWrapper = shellMatches
+    && tokens.length === 7
+    && tokens[1] === "-c"
+    && wrappedHost != null
+    && tokens[3] === "zevai-service"
+    && nodeMatches
+    && samePath(tokens[5], options.cliPath, options.canonicalizePath)
+    && normalizePort(tokens[6]) != null;
+  if (positionalWrapper) {
+    return { port: normalizePort(tokens[6]), host: wrappedHost };
+  }
+  return parseInstallerSystemdExec(tokens, options);
+}
+
+function parseSystemdRuntime(unitText, options = {}) {
+  if (typeof unitText !== "string" || !unitText.trim()) return null;
+  const execLines = unitText.match(/^\s*ExecStart\s*=.*$/gim) || [];
+  const execEntries = execLines.map((line) => {
+    const tokens = splitCommandLine(line.replace(/^\s*ExecStart\s*=/i, ""));
+    const parsed = parseSystemdCliExec(tokens, options);
+    return parsed ? { ...parsed, tokens } : null;
+  });
+  if (execEntries.some((entry) => entry == null)) return null;
+  const recognizedExecs = execEntries.filter(Boolean);
+  if (recognizedExecs.length === 0) return null;
+  if (recognizedExecs.some((entry) => {
+    const portOption = readPortOption(entry.tokens);
+    return portOption.specified && portOption.value == null;
+  })) return null;
+  if (recognizedExecs.some((entry) => {
+    const hostOption = readHostOption(entry.tokens);
+    return hostOption.specified && hostOption.value == null;
+  })) return null;
+
+  const execPorts = recognizedExecs
+    .map((entry) => readPortOption(entry.tokens).value ?? entry.port)
+    .filter((port) => port != null);
+  const distinctExecPorts = [...new Set(execPorts)];
+  if (distinctExecPorts.length > 1) return null;
+  const execPort = distinctExecPorts[0] ?? null;
+  const execHosts = recognizedExecs
+    .map((entry) => readHostOption(entry.tokens).value ?? entry.host)
+    .filter((host) => host != null);
+  const distinctExecHosts = [...new Set(execHosts)];
+  if (distinctExecHosts.length > 1) return null;
+  const execHost = distinctExecHosts[0] ?? null;
+
+  const environmentPorts = [];
+  const environmentHosts = [];
+  for (const match of unitText.matchAll(/^\s*Environment\s*=\s*(.+)$/gim)) {
+    const assignments = splitCommandLine(match[1]);
+    for (const assignment of assignments || []) {
+      if (assignment.startsWith("PORT=")) environmentPorts.push(normalizePort(assignment.slice(5)));
+      if (assignment.startsWith("HOSTNAME=")) environmentHosts.push(normalizeHost(assignment.slice(9)));
+    }
+  }
+  const validEnvironmentPorts = environmentPorts.filter((port) => port != null);
+  const distinctEnvironmentPorts = [...new Set(validEnvironmentPorts)];
+  const environmentPort = environmentPorts.length > 0
+    && validEnvironmentPorts.length === environmentPorts.length
+    && distinctEnvironmentPorts.length === 1
+    ? distinctEnvironmentPorts[0]
+    : null;
+  const validEnvironmentHosts = environmentHosts.filter((host) => host != null);
+  const distinctEnvironmentHosts = [...new Set(validEnvironmentHosts)];
+  const environmentHost = environmentHosts.length > 0
+    && validEnvironmentHosts.length === environmentHosts.length
+    && distinctEnvironmentHosts.length === 1
+    ? distinctEnvironmentHosts[0]
+    : null;
+  if (environmentPort != null && execPort != null && environmentPort !== execPort) return null;
+  if (environmentHost != null && execHost != null && environmentHost !== execHost) return null;
+  return {
+    mode: "server",
+    port: environmentPort ?? execPort,
+    host: environmentHost ?? execHost ?? "0.0.0.0",
+    source: "systemd",
+  };
+}
+
+function parseProcessTable(psOutput) {
+  const processes = [];
+  for (const line of String(psOutput || "").split(/\r?\n/)) {
+    const withParent = line.match(/^\s*(\d+)\s+(\d+)\s+(.+)$/);
+    const legacy = withParent ? null : line.match(/^\s*(\d+)\s+(.+)$/);
+    if (!withParent && !legacy) continue;
+    const pid = Number((withParent || legacy)[1]);
+    const ppid = withParent ? Number(withParent[2]) : null;
+    const command = withParent ? withParent[3] : legacy[2];
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    processes.push({ pid, ppid, command });
+  }
+  return processes;
+}
+
+function parseRunningCliProcesses(psOutput, options) {
+  const { cliPath, currentPid, canonicalizePath = defaultCanonicalize } = options;
+  const processes = [];
+
+  for (const processInfo of parseProcessTable(psOutput)) {
+    const { pid, ppid, command } = processInfo;
+    if (!Number.isInteger(pid) || pid <= 1 || pid === Number(currentPid)) continue;
+    const tokens = splitCommandLine(command);
+    const cliArgs = cliArgsFromTokens(tokens, cliPath, canonicalizePath);
+    if (!cliArgs) continue;
+    const portOption = readPortOption(cliArgs);
+    if (portOption.specified && portOption.value == null) continue;
+    const hostOption = readHostOption(cliArgs);
+    if (hostOption.specified && hostOption.value == null) continue;
+    processes.push({
+      pid,
+      ppid,
+      mode: inferProcessMode(cliArgs, portOption.specified),
+      port: portOption.specified ? portOption.value : DEFAULT_PORT,
+      host: hostOption.specified ? hostOption.value : DEFAULT_HOST,
+      args: cliArgs,
+      command,
+    });
+  }
+
+  return processes;
+}
+
+function parseMacAutostart(plistText, options) {
+  if (typeof plistText !== "string" || !plistText.trim()) return null;
+  const label = plistText.match(
+    /<key>\s*Label\s*<\/key>\s*<string>([\s\S]*?)<\/string>/i,
+  );
+  if (!label || decodeXml(label[1]).trim() !== LAUNCH_AGENT_LABEL) return null;
+  const programArguments = plistText.match(
+    /<key>\s*ProgramArguments\s*<\/key>\s*<array>([\s\S]*?)<\/array>/i,
+  );
+  if (!programArguments) return null;
+  const args = [...programArguments[1].matchAll(/<string>([\s\S]*?)<\/string>/gi)]
+    .map((match) => decodeXml(match[1]));
+  const cliArgs = cliArgsFromTokens(args, options.cliPath, options.canonicalizePath);
+  if (!cliArgs || !hasTrayArg(cliArgs)) return null;
+  const portOption = readPortOption(cliArgs);
+  if (portOption.specified && portOption.value == null) return null;
+  const hostOption = readHostOption(cliArgs);
+  if (hostOption.specified && hostOption.value == null) return null;
+  return {
+    mode: "tray",
+    port: portOption.specified ? portOption.value : DEFAULT_PORT,
+    host: hostOption.specified ? hostOption.value : DEFAULT_HOST,
+    source: "autostart",
+  };
+}
+
+function parseLinuxAutostart(desktopText, options) {
+  if (typeof desktopText !== "string" || !desktopText.trim()) return null;
+  const values = new Map();
+  for (const line of desktopText.split(/\r?\n/)) {
+    const match = line.match(/^([A-Za-z0-9-]+)\s*=\s*(.*)$/);
+    if (match) values.set(match[1], match[2]);
+  }
+  if (/^true$/i.test(values.get("Hidden") || "")) return null;
+  if (/^false$/i.test(values.get("X-GNOME-Autostart-enabled") || "")) return null;
+  const tokens = splitCommandLine(values.get("Exec") || "");
+  const cliArgs = cliArgsFromTokens(tokens, options.cliPath, options.canonicalizePath);
+  if (!cliArgs || !hasTrayArg(cliArgs)) return null;
+  const portOption = readPortOption(cliArgs);
+  if (portOption.specified && portOption.value == null) return null;
+  const hostOption = readHostOption(cliArgs);
+  if (hostOption.specified && hostOption.value == null) return null;
+  return {
+    mode: "tray",
+    port: portOption.specified ? portOption.value : DEFAULT_PORT,
+    host: hostOption.specified ? hostOption.value : DEFAULT_HOST,
+    source: "autostart",
+  };
+}
+
+function parseAutostartRuntime(content, options) {
+  if (options.platform === "darwin") return parseMacAutostart(content, options);
+  if (options.platform === "linux") return parseLinuxAutostart(content, options);
+  return null;
+}
+
+function runtimeFromArgsAndEnv(args, env, defaultMode = "server") {
+  const portOption = readPortOption(args);
+  const hostOption = readHostOption(args);
+  if (portOption.specified && portOption.value == null) return null;
+  if (hostOption.specified && hostOption.value == null) return null;
+
+  const envPortSpecified = Object.hasOwn(env, "PORT");
+  const envPort = envPortSpecified ? normalizePort(env.PORT) : null;
+  if (envPortSpecified && envPort == null) return null;
+  for (const name of ["TRAY_MODE", "ZEVAI_SERVER_MODE"]) {
+    if (
+      Object.hasOwn(env, name)
+      && !["", "0", "1"].includes(String(env[name]))
+    ) return null;
+  }
+  const envModeConfigured = String(env.TRAY_MODE ?? "") === "1"
+    || String(env.ZEVAI_SERVER_MODE ?? "") === "1";
+  const envHostSpecified = envModeConfigured && Object.hasOwn(env, "HOSTNAME");
+  const envHost = envHostSpecified ? normalizeHost(env.HOSTNAME) : null;
+  if (envHostSpecified && envHost == null) return null;
+  if (portOption.value != null && envPort != null && portOption.value !== envPort) return null;
+  if (hostOption.value != null && envHost != null && hostOption.value !== envHost) return null;
+
+  let mode;
+  try {
+    mode = explicitMode(args, env) ?? inferProcessMode(args, portOption.specified) ?? defaultMode;
+  } catch {
+    return null;
+  }
+  return {
+    port: portOption.value ?? envPort ?? DEFAULT_PORT,
+    host: hostOption.value ?? envHost ?? DEFAULT_HOST,
+    mode,
+  };
+}
+
+function parsePm2Runtime(jlistText, options) {
+  if (jlistText == null || jlistText === "") {
+    return { apps: [], invalidOwned: [], parseError: false };
+  }
+  let list;
+  try {
+    list = typeof jlistText === "string" ? JSON.parse(jlistText) : jlistText;
+  } catch {
+    return { apps: [], invalidOwned: [], parseError: true };
+  }
+  if (!Array.isArray(list)) return { apps: [], invalidOwned: [], parseError: true };
+
+  const apps = [];
+  const invalidOwned = [];
+  for (const app of list) {
+    const pm2Env = app?.pm2_env;
+    if (!pm2Env || typeof pm2Env !== "object") continue;
+    const execPath = String(pm2Env.pm_exec_path || app.pm_exec_path || "");
+    const rawId = app.pm_id ?? pm2Env.pm_id;
+    const identity = {
+      id: typeof rawId === "number" && Number.isInteger(rawId) && rawId >= 0 ? rawId : null,
+      name: String(app.name || pm2Env.name || ""),
+    };
+    const directCliExec = samePath(execPath, options.cliPath, options.canonicalizePath);
+    let rawArgs;
+    if (Array.isArray(pm2Env.args)) rawArgs = pm2Env.args.map(String);
+    else if (typeof pm2Env.args === "string") rawArgs = splitCommandLine(pm2Env.args);
+    else if (pm2Env.args == null) rawArgs = [];
+    else rawArgs = null;
+    if (!rawArgs) {
+      if (directCliExec) invalidOwned.push(identity);
+      continue;
+    }
+
+    let cliArgs = null;
+    if (directCliExec) {
+      cliArgs = rawArgs;
+    } else if (
+      /^(?:node|nodejs)(?:\.exe)?$/i.test(path.basename(execPath))
+      && samePath(rawArgs[0], options.cliPath, options.canonicalizePath)
+    ) {
+      cliArgs = rawArgs.slice(1);
+    }
+    if (!cliArgs) continue;
+
+    const nestedEnv = pm2Env.env
+      && typeof pm2Env.env === "object"
+      && !Array.isArray(pm2Env.env)
+      ? pm2Env.env
+      : {};
+    if (pm2Env.env != null && nestedEnv !== pm2Env.env) {
+      invalidOwned.push(identity);
+      continue;
+    }
+    const runtimeEnv = { ...nestedEnv };
+    for (const key of ["PORT", "HOSTNAME", "TRAY_MODE", "ZEVAI_SERVER_MODE"]) {
+      if (Object.hasOwn(pm2Env, key)) runtimeEnv[key] = pm2Env[key];
+    }
+    const runtime = runtimeFromArgsAndEnv(cliArgs, runtimeEnv, "server");
+    if (identity.id == null || !runtime) {
+      invalidOwned.push(identity);
+      continue;
+    }
+    apps.push({
+      type: "pm2",
+      ...identity,
+      ...runtime,
+      pid: Number.isInteger(Number(app.pid)) && Number(app.pid) > 0 ? Number(app.pid) : null,
+      status: String(pm2Env.status || "unknown"),
+      execPath,
+      args: cliArgs,
+    });
+  }
+  return { apps, invalidOwned, parseError: false };
+}
+
+function parseLaunchdRuntime(printOutput, options) {
+  if (typeof printOutput !== "string" || !printOutput.trim()) return null;
+  const lines = printOutput.split(/\r?\n/);
+  if (lines[0]?.trim() !== `${options.target} = {`) return null;
+  const readField = (field) => {
+    const prefix = `${field} = `;
+    const line = lines.find((entry) => entry.trimStart().startsWith(prefix));
+    return line ? line.trimStart().slice(prefix.length).trim() : null;
+  };
+  if (readField("type") !== "LaunchAgent") return null;
+  const loadedPath = readField("path");
+  if (!samePath(loadedPath, options.plistPath, defaultCanonicalize)) return null;
+
+  const argumentsStart = lines.findIndex((line) => line.trim() === "arguments = {");
+  if (argumentsStart < 0) return null;
+  const argumentsEnd = lines.findIndex((line, index) => index > argumentsStart && line.trim() === "}");
+  if (argumentsEnd < 0) return null;
+  const args = lines.slice(argumentsStart + 1, argumentsEnd)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const cliArgs = cliArgsFromTokens(args, options.cliPath, options.canonicalizePath);
+  if (!cliArgs || !hasTrayArg(cliArgs)) return null;
+  const runtime = runtimeFromArgsAndEnv(cliArgs, {}, "tray");
+  if (!runtime || runtime.mode !== "tray") return null;
+  const program = readField("program");
+  if (!samePath(program, args[0], options.canonicalizePath)) return null;
+  const parsedPid = Number(readField("pid"));
+  const pid = Number.isInteger(parsedPid) && parsedPid > 0 ? parsedPid : null;
+  return {
+    type: "launchd",
+    target: options.target,
+    plistPath: options.plistPath,
+    state: readField("state") || "unknown",
+    pid,
+    ...runtime,
+    args: cliArgs,
+  };
+}
+
+function isDescendant(processTable, pid, ancestorPid) {
+  const parents = new Map(processTable.map((processInfo) => [processInfo.pid, processInfo.ppid]));
+  const visited = new Set();
+  let current = pid;
+  while (Number.isInteger(current) && current > 0 && !visited.has(current)) {
+    if (current === ancestorPid) return true;
+    visited.add(current);
+    current = parents.get(current);
+  }
+  return false;
+}
+
+function hasProcessAncestorMatching(processTable, pid, matches) {
+  if (typeof matches !== "function") return false;
+  const processes = new Map(processTable.map((processInfo) => [processInfo.pid, processInfo]));
+  const visited = new Set([pid]);
+  let current = processes.get(pid)?.ppid;
+  while (Number.isInteger(current) && current > 0 && !visited.has(current)) {
+    visited.add(current);
+    const processInfo = processes.get(current);
+    if (!processInfo) return false;
+    if (matches(processInfo)) return true;
+    current = processInfo.ppid;
+  }
+  return false;
+}
+
+function selectOwnedRouterParent(options) {
+  const snapshots = options.snapshots || [];
+  const currentProcesses = options.currentProcesses || [];
+  const processTable = options.processTable || [];
+  const listenerPids = options.listenerPids || [];
+  const candidates = snapshots.filter((snapshot) => (
+    snapshot.port === options.port
+    && currentProcesses.some((current) => (
+      current.pid === snapshot.pid
+      && current.ppid === snapshot.ppid
+      && current.command === snapshot.command
+      && current.port === snapshot.port
+      && current.mode === snapshot.mode
+      && current.host === snapshot.host
+    ))
+  ));
+  const owned = listenerPids.length === 0
+    ? candidates
+    : candidates.filter((candidate) => (
+        listenerPids.every((pid) => isDescendant(processTable, pid, candidate.pid))
+      ));
+  return owned.length === 1 ? owned[0] : null;
+}
+
+function uniqueValue(items, key, description) {
+  const values = [...new Set(items.map((item) => item[key]).filter((value) => value != null))];
+  if (values.length > 1) {
+    const option = key === "host" ? "--host" : "--port";
+    throw new Error(`Multiple running ZevaiRouter ${description} detected; pass ${option} to select one instance.`);
+  }
+  return values[0] ?? null;
+}
+
+function resolveUpdateRuntimeState(options = {}) {
+  const args = Array.isArray(options.args) ? options.args.map(String) : [];
+  const env = options.env || {};
+  const explicitPort = readPortOption(args);
+  if (explicitPort.conflict) {
+    throw new Error("Conflicting --port values; provide exactly one port.");
+  }
+  if (explicitPort.invalid) {
+    throw new Error("Invalid --port value; expected an integer from 1 to 65535.");
+  }
+  const explicitHost = readHostOption(args);
+  if (explicitHost.conflict) {
+    throw new Error("Conflicting --host values; provide exactly one host.");
+  }
+  if (explicitHost.invalid) {
+    throw new Error("Invalid --host value; use a hostname or IP address without whitespace.");
+  }
+  const selectedExplicitMode = explicitMode(args, env);
+
+  const envPortSpecified = Object.hasOwn(env, "PORT");
+  const envPort = envPortSpecified ? normalizePort(env.PORT) : null;
+  if (envPortSpecified && envPort == null) {
+    throw new Error("Invalid PORT environment variable; expected an integer from 1 to 65535.");
+  }
+  const envHostSpecified = (
+    String(env.ZEVAI_SERVER_MODE ?? "") === "1"
+    || String(env.TRAY_MODE ?? "") === "1"
+  ) && Object.hasOwn(env, "HOSTNAME");
+  const envHost = envHostSpecified ? normalizeHost(env.HOSTNAME) : null;
+  if (envHostSpecified && envHost == null) {
+    throw new Error("Invalid HOSTNAME environment variable for server mode.");
+  }
+
+  const systemd = options.systemdOperational
+    ? parseSystemdRuntime(options.systemdUnit, {
+        cliPath: options.cliPath,
+        canonicalizePath: options.canonicalizePath,
+        shellPath: options.shellPath,
+      })
+    : null;
+  const runningProcesses = parseRunningCliProcesses(options.psOutput, {
+    cliPath: options.cliPath,
+    currentPid: options.currentPid,
+    canonicalizePath: options.canonicalizePath,
+  });
+  const autostart = parseAutostartRuntime(options.autostartContent, {
+    platform: options.platform,
+    cliPath: options.cliPath,
+    canonicalizePath: options.canonicalizePath,
+  });
+  const pm2Inspection = parsePm2Runtime(options.pm2Output, {
+    cliPath: options.cliPath,
+    canonicalizePath: options.canonicalizePath,
+  });
+  if (pm2Inspection.parseError) {
+    throw new Error("PM2 returned malformed process metadata; refusing an ownership-ambiguous update.");
+  }
+  if (pm2Inspection.invalidOwned.length > 0) {
+    throw new Error("An owned PM2 ZevaiRouter app has invalid or ambiguous runtime metadata.");
+  }
+  const launchd = parseLaunchdRuntime(options.launchdOutput, {
+    target: options.launchdTarget,
+    plistPath: options.autostartPath,
+    cliPath: options.cliPath,
+    canonicalizePath: options.canonicalizePath,
+  });
+  if (options.launchdOutput && !launchd) {
+    throw new Error("The registered launchd job could not be verified as this ZevaiRouter install.");
+  }
+  if (launchd?.state === "running" && launchd.pid == null) {
+    throw new Error("The running launchd job did not expose a verifiable PID.");
+  }
+  if (launchd?.state !== "running" && launchd?.pid != null) {
+    throw new Error("The launchd job exposed a PID while reporting a non-running state.");
+  }
+  if (launchd?.pid != null) {
+    const launchdProcess = runningProcesses.find((processInfo) => processInfo.pid === launchd.pid);
+    if (
+      !launchdProcess
+      || launchdProcess.port !== launchd.port
+      || launchdProcess.mode !== launchd.mode
+      || launchdProcess.host !== launchd.host
+    ) {
+      throw new Error("The launchd PID does not match its exact ZevaiRouter runtime arguments.");
+    }
+  }
+  const directProcessUsesStoppedLaunchdPort = Boolean(launchd)
+    && launchd.pid == null
+    && launchd.state !== "running"
+    && runningProcesses.some((processInfo) => processInfo.port === launchd.port);
+  const effectiveLaunchd = directProcessUsesStoppedLaunchdPort ? null : launchd;
+
+  const explicitPortValue = explicitPort.value ?? envPort ?? null;
+  let pm2 = null;
+  if (pm2Inspection.apps.length === 1) {
+    [pm2] = pm2Inspection.apps;
+  } else if (pm2Inspection.apps.length > 1) {
+    const matching = explicitPortValue == null
+      ? []
+      : pm2Inspection.apps.filter((app) => app.port === explicitPortValue);
+    if (matching.length !== 1) {
+      throw new Error("Multiple owned PM2 ZevaiRouter apps found; pass --port to select exactly one.");
+    }
+    [pm2] = matching;
+  }
+
+  const managers = [
+    systemd ? { type: "systemd", ...systemd } : null,
+    effectiveLaunchd,
+    pm2,
+  ].filter(Boolean);
+  if (managers.length > 1) {
+    throw new Error("Multiple ZevaiRouter service managers were detected; refusing an ambiguous update.");
+  }
+  const manager = managers[0] || null;
+  if (manager?.port != null && explicitPortValue != null && manager.port !== explicitPortValue) {
+    throw new Error(`Explicit port ${explicitPortValue} conflicts with ${manager.type} port ${manager.port}.`);
+  }
+  if (manager?.mode && selectedExplicitMode && manager.mode !== selectedExplicitMode) {
+    throw new Error(`Explicit ${selectedExplicitMode} mode conflicts with ${manager.type} ${manager.mode} mode.`);
+  }
+  const explicitHostValue = explicitHost.value ?? envHost ?? null;
+  if (manager?.host && explicitHostValue && manager.host !== explicitHostValue) {
+    throw new Error(`Explicit host ${explicitHostValue} conflicts with ${manager.type} host ${manager.host}.`);
+  }
+
+  const higherPriorityPort = explicitPortValue ?? manager?.port ?? null;
+  const matchingProcesses = higherPriorityPort == null
+    ? runningProcesses
+    : runningProcesses.filter((processInfo) => processInfo.port === higherPriorityPort);
+  const processPort = higherPriorityPort == null
+    ? uniqueValue(runningProcesses, "port", "ports")
+    : null;
+  const port = higherPriorityPort ?? processPort ?? autostart?.port ?? DEFAULT_PORT;
+  const modeCandidates = matchingProcesses.length > 0 ? matchingProcesses : runningProcesses;
+  const processMode = selectedExplicitMode == null && manager?.mode == null
+    ? uniqueValue(modeCandidates, "mode", "modes")
+    : null;
+  const mode = selectedExplicitMode ?? manager?.mode ?? processMode ?? autostart?.mode ?? "server";
+  const processHost = explicitHostValue == null && manager?.host == null
+    ? uniqueValue(modeCandidates, "host", "hosts")
+    : null;
+  const host = explicitHostValue ?? manager?.host ?? processHost ?? autostart?.host ?? DEFAULT_HOST;
+  const portSource = explicitPort.specified
+    ? "argv"
+    : envPort != null
+      ? "env"
+      : manager?.port != null
+        ? manager.type
+        : processPort != null
+          ? "process"
+          : autostart?.port != null
+            ? "autostart"
+            : "default";
+  const modeSource = selectedExplicitMode
+    ? "explicit"
+    : manager?.mode
+      ? manager.type
+      : processMode
+        ? "process"
+        : autostart?.mode
+          ? "autostart"
+          : "default";
+  const hostSource = explicitHost.specified
+    ? "argv"
+    : envHost != null
+      ? "env"
+      : manager?.host
+        ? manager.type
+        : processHost
+          ? "process"
+          : autostart?.host
+            ? "autostart"
+            : "default";
+
+  return {
+    port,
+    mode,
+    host,
+    portSource,
+    modeSource,
+    hostSource,
+    systemdRecognized: Boolean(systemd),
+    manager,
+    runningProcesses,
+    autostartRecognized: Boolean(autostart),
+    registeredLaunchd: launchd,
+  };
+}
+
+function buildUpdateRelaunchArgs(runtime) {
+  const port = normalizePort(runtime?.port);
+  const host = normalizeHost(runtime?.host ?? DEFAULT_HOST);
+  if (port == null) throw new Error("Cannot relaunch ZevaiRouter with an invalid port.");
+  if (host == null) throw new Error("Cannot relaunch ZevaiRouter with an invalid host.");
+  if (runtime.mode === "tray") {
+    return ["--tray", "--skip-update", "--port", String(port), "--host", host];
+  }
+  if (runtime.mode !== "server") throw new Error("Cannot relaunch ZevaiRouter with an invalid mode.");
+  return ["--port", String(port), "--host", host, "--no-browser", "--skip-update", "--log"];
+}
+
+module.exports = {
+  DEFAULT_HOST,
+  DEFAULT_PORT,
+  buildUpdateRelaunchArgs,
+  normalizeHost,
+  normalizePort,
+  hasProcessAncestorMatching,
+  parseLaunchdRuntime,
+  parseLinuxAutostart,
+  parseMacAutostart,
+  parsePm2Runtime,
+  parseProcessTable,
+  parseRunningCliProcesses,
+  parseSystemdRuntime,
+  readHostOption,
+  readPortOption,
+  resolveUpdateRuntimeState,
+  selectOwnedRouterParent,
+  splitCommandLine,
+};