@nordbyte/nordrelay 0.8.2 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nordbyte/nordrelay",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Remote control plane for coding agents across messaging channels.",
   "type": "module",
   "author": "Ricardo",
@@ -34,6 +34,7 @@
   "files": [
     "dist/",
     "plugins/",
+    "scripts/postinstall.mjs",
     "scripts/launchd-start.sh",
     ".env.example",
     "Dockerfile",
@@ -43,11 +44,12 @@
     "api:check": "node --import tsx scripts/generate-web-api-routes.mjs --check",
     "api:generate": "node --import tsx scripts/generate-web-api-routes.mjs",
     "build": "node scripts/clean-dist.mjs && npm run api:generate && tsc && node scripts/build-web-assets.mjs",
-    "check": "node --check plugins/nordrelay/scripts/nordrelay.mjs && npm run api:check && tsc --noEmit && npm run webui:check && node scripts/build-web-assets.mjs --check && node --import tsx scripts/generate-env-example.mjs --check && npm run size:check",
+    "check": "node --check plugins/nordrelay/scripts/nordrelay.mjs && node --check plugins/nordrelay/scripts/service-installer.mjs && npm run api:check && tsc --noEmit && npm run webui:check && node scripts/build-web-assets.mjs --check && node --import tsx scripts/generate-env-example.mjs --check && npm run size:check",
     "dev": "tsx src/index.ts",
     "env:check": "node --import tsx scripts/generate-env-example.mjs --check",
     "env:generate": "node --import tsx scripts/generate-env-example.mjs",
     "foreground": "node plugins/nordrelay/scripts/nordrelay.mjs foreground",
+    "postinstall": "node scripts/postinstall.mjs",
     "prepack": "npm run build",
     "prepublishOnly": "npm run check && npm test && npm run build",
     "security:audit": "npm audit --audit-level=high",

package/plugins/nordrelay/scripts/nordrelay.mjs

@@ -6,8 +6,15 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import readline from "node:readline/promises";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  buildLaunchdServiceSpec,
+  buildSystemdUserServiceSpec,
+  buildWindowsTaskServiceSpec,
+  parseServiceFlags,
+  serviceInstallSpec,
+} from "./service-installer.mjs";
 
 const FALLBACK_VERSION = "0.3.1";
 const require = createRequire(import.meta.url);
@@ -238,6 +245,7 @@ function formatDashboardUrl(endpoint) {
 async function commandStart(options, settings = {}) {
   await mkdirp(options.home);
   loadEnvFiles(options.home);
+  warnIfCliPathMissing();
   await prepareRuntimeForLaunch(options);
   const dashboard = resolveDashboardEndpoint(options);
 
@@ -431,6 +439,46 @@ async function commandStatus(options) {
   if (state.error) console.log(`Error: ${state.error}`);
 }
 
+function cliPathDiagnostics() {
+  const resolved = findExecutable(APP_NAME);
+  const globalBin = resolveNpmGlobalBinDir();
+  const candidate = globalBin ? path.join(globalBin, process.platform === "win32" ? `${APP_NAME}.cmd` : APP_NAME) : null;
+  const pathContainsGlobalBin = globalBin ? pathListIncludes(globalBin) : false;
+  const expected = [candidate, SCRIPT_PATH].filter(Boolean);
+  const resolvedKnown = Boolean(resolved && expected.some((item) => pathsEqualOrLinked(resolved, item)));
+  const hint = globalBin
+    ? process.platform === "win32"
+      ? `Add ${globalBin} to PATH and reopen the terminal.`
+      : `Add ${globalBin} to PATH, for example: export PATH="${globalBin}:$PATH"`
+    : "Ensure the npm global bin directory is on PATH.";
+  return {
+    ok: Boolean(resolved),
+    resolved,
+    globalBin,
+    pathContainsGlobalBin,
+    expected: candidate,
+    resolvedKnown,
+    detail: resolved
+      ? resolvedKnown
+        ? resolved
+        : `${resolved} (different command target; current wrapper: ${SCRIPT_PATH})`
+      : `not found on PATH${globalBin ? `; npm global bin: ${globalBin}` : ""}`,
+    hint,
+  };
+}
+
+function warnIfCliPathMissing() {
+  if (envFlag("NORDRELAY_SUPPRESS_PATH_WARNING")) {
+    return;
+  }
+  const diagnostics = cliPathDiagnostics();
+  if (diagnostics.ok) {
+    return;
+  }
+  console.warn(`Warning: \`${APP_NAME}\` is not available on PATH.`);
+  console.warn(`Hint: ${diagnostics.hint}`);
+}
+
 async function commandUpdate(options) {
   await mkdirp(options.home);
   loadEnvFiles(options.home);
@@ -671,6 +719,7 @@ function quoteWindowsCmdArg(value) {
 
 async function commandInit(options) {
   await mkdirp(options.home);
+  warnIfCliPathMissing();
   const envPath = path.join(options.home, "nordrelay.env");
   const userStore = await createUserStore(options.home);
   if (fs.existsSync(envPath) && !options.force) {
@@ -818,7 +867,7 @@ function parsePeerFlags(argv) {
   const copy = [...argv];
   const subcommand = copy[0] && !copy[0].startsWith("-") ? copy.shift() : "list";
   const flags = { subcommand, url: undefined };
-  if (["add", "test", "check", "revoke"].includes(subcommand) && copy[0] && !copy[0].startsWith("-")) {
+  if (["add", "test", "check", "revoke", "trust", "rotate"].includes(subcommand) && copy[0] && !copy[0].startsWith("-")) {
     flags.url = copy.shift();
     flags.id = flags.url;
   }
@@ -881,6 +930,7 @@ async function commandPeer(options) {
       if (peer.lastSeenAt) console.log(`  Last seen: ${peer.lastSeenAt}`);
       if (peer.lastLatencyMs !== undefined) console.log(`  Latency: ${peer.lastLatencyMs}ms`);
       if (peer.remoteVersion) console.log(`  Remote version: ${peer.remoteVersion}`);
+      if (peer.trustStatus) console.log(`  Trust: ${peer.trustStatus}${peer.trustWarnings?.length ? ` (${peer.trustWarnings.join("; ")})` : ""}`);
       if (peer.lastError) console.log(`  Last error: ${peer.lastError}`);
     }
     return;
@@ -957,7 +1007,187 @@ async function commandPeer(options) {
     return;
   }
 
-  throw new Error("Usage: nordrelay peer [identity|list|invite|add|test|check|revoke]");
+  if (flags.subcommand === "trust") {
+    const id = flags.id || await ask(null, "Peer id", "");
+    const peer = store.get(id);
+    if (!peer?.url) throw new Error("Peer URL is required before TLS trust can be updated.");
+    const probe = await clientMod.checkPeerIdentityEndpoint(peer.url, { timeoutMs: 5000 });
+    if (!probe.ok || !probe.identity) throw new Error(`Peer identity could not be verified: ${probe.detail}`);
+    if (probe.identity.nodeId !== peer.nodeId || probe.identity.publicKey !== peer.publicKey || probe.identity.fingerprint !== peer.fingerprint) {
+      throw new Error("Peer identity changed. Re-pair this peer instead of trusting the TLS fingerprint.");
+    }
+    const updated = store.updatePeerTlsFingerprint(peer.id, probe.tlsFingerprint);
+    console.log(`Trusted TLS fingerprint for ${updated.name}: ${updated.tlsFingerprint || "-"}`);
+    return;
+  }
+
+  if (flags.subcommand === "rotate") {
+    const id = flags.id || await ask(null, "Peer id", "");
+    const url = process.env.NORDRELAY_PEER_PUBLIC_URL || `${process.env.NORDRELAY_PEER_TLS_ENABLED === "false" ? "http" : "https"}://${process.env.NORDRELAY_PEER_HOST || "127.0.0.1"}:${process.env.NORDRELAY_PEER_PORT || "31979"}`;
+    const created = store.createRotationInvitation(id, { expiresInMs: Number.isFinite(flags.expiresMinutes) ? flags.expiresMinutes * 60 * 1000 : undefined });
+    console.log(`Rotation invite for ${created.peer.name} (${created.peer.id}).`);
+    console.log(`Pairing code: ${created.code}`);
+    console.log(`Expires: ${created.invitation.expiresAt}`);
+    console.log(`Command: nordrelay peer add ${url} --code ${created.code}`);
+    return;
+  }
+
+  throw new Error("Usage: nordrelay peer [identity|list|invite|add|test|check|trust|rotate|revoke]");
+}
+
+async function commandService(options) {
+  await mkdirp(options.home);
+  loadEnvFiles(options.home);
+  warnIfCliPathMissing();
+  const flags = parseServiceFlags(options.rawFlags);
+  const specOptions = { ...options, scriptPath: SCRIPT_PATH };
+
+  if (flags.subcommand === "install") {
+    if (flags.dryRun) {
+      printServiceInstallDryRun(specOptions, flags);
+      return;
+    }
+    if (flags.platform === "darwin") {
+      await installLaunchdService(specOptions, flags);
+      return;
+    }
+    if (flags.platform === "win32") {
+      await installWindowsTask(specOptions, flags);
+      return;
+    }
+    await installSystemdUserService(specOptions, flags);
+    return;
+  }
+
+  if (flags.subcommand === "uninstall" || flags.subcommand === "remove") {
+    if (flags.platform === "darwin") {
+      await uninstallLaunchdService(flags);
+      return;
+    }
+    if (flags.platform === "win32") {
+      await uninstallWindowsTask(flags);
+      return;
+    }
+    await uninstallSystemdUserService(flags);
+    return;
+  }
+
+  if (flags.subcommand === "status") {
+    await commandServiceStatus(flags);
+    return;
+  }
+
+  throw new Error("Usage: nordrelay service [install|uninstall|status] [--no-start] [--name <name>] [--label <label>]");
+}
+
+async function installSystemdUserService(options, flags) {
+  const spec = buildSystemdUserServiceSpec(options, flags);
+  const unitDir = path.dirname(spec.path);
+  const unitPath = spec.path;
+  await mkdirp(unitDir);
+  await fsp.writeFile(unitPath, spec.content);
+  console.log(`Installed systemd user service: ${unitPath}`);
+  for (const command of spec.commands) {
+    runPlatformCommand(command.command, command.args, command.label, command.settings);
+  }
+  console.log(`Status: nordrelay service status`);
+}
+
+async function uninstallSystemdUserService(flags) {
+  runPlatformCommand("systemctl", ["--user", "disable", "--now", `${flags.name}.service`], `Disable ${flags.name}.service`);
+  const unitPath = path.join(os.homedir(), ".config", "systemd", "user", `${flags.name}.service`);
+  await fsp.rm(unitPath, { force: true });
+  runPlatformCommand("systemctl", ["--user", "daemon-reload"], "Reload systemd user units");
+  console.log(`Removed systemd user service: ${unitPath}`);
+}
+
+async function installLaunchdService(options, flags) {
+  const spec = buildLaunchdServiceSpec(options, flags);
+  const launchAgentsDir = path.dirname(spec.path);
+  const plistPath = spec.path;
+  await mkdirp(launchAgentsDir);
+  await fsp.writeFile(plistPath, spec.content);
+  console.log(`Installed launchd service: ${plistPath}`);
+  for (const command of spec.commands) {
+    runPlatformCommand(command.command, command.args, command.label, command.settings);
+  }
+  if (!flags.start) {
+    const domain = launchdDomain();
+    console.log(`Start later with: launchctl bootstrap ${domain} ${plistPath}`);
+  }
+}
+
+async function uninstallLaunchdService(flags) {
+  const plistPath = path.join(os.homedir(), "Library", "LaunchAgents", `${flags.label}.plist`);
+  const domain = `gui/${process.getuid?.() ?? ""}`;
+  runPlatformCommand("launchctl", ["bootout", domain, plistPath], `Unload ${flags.label}`, { allowFailure: true });
+  await fsp.rm(plistPath, { force: true });
+  console.log(`Removed launchd service: ${plistPath}`);
+}
+
+async function installWindowsTask(options, flags) {
+  const spec = buildWindowsTaskServiceSpec(options, flags);
+  for (const command of spec.commands) {
+    runPlatformCommand(command.command, command.args, command.label, command.settings);
+  }
+  console.log(`Installed Windows task: ${flags.name}`);
+}
+
+async function uninstallWindowsTask(flags) {
+  runPlatformCommand("schtasks", ["/Delete", "/F", "/TN", flags.name], `Delete Windows task ${flags.name}`, { allowFailure: true });
+  console.log(`Removed Windows task: ${flags.name}`);
+}
+
+async function commandServiceStatus(flags) {
+  if (process.platform === "darwin") {
+    const domain = `gui/${process.getuid?.() ?? ""}`;
+    runPlatformCommand("launchctl", ["print", `${domain}/${flags.label}`], `launchd status ${flags.label}`, { allowFailure: true });
+    return;
+  }
+  if (process.platform === "win32") {
+    runPlatformCommand("schtasks", ["/Query", "/TN", flags.name], `Windows task status ${flags.name}`, { allowFailure: true });
+    return;
+  }
+  runPlatformCommand("systemctl", ["--user", "status", `${flags.name}.service`, "--no-pager"], `systemd user status ${flags.name}.service`, { allowFailure: true });
+}
+
+function printServiceInstallDryRun(options, flags) {
+  const spec = serviceInstallSpec(options, flags);
+  console.log(`Service install dry-run (${spec.platform})`);
+  console.log(`Target: ${spec.path}`);
+  if (spec.content) {
+    console.log("--- file content ---");
+    console.log(spec.content.trimEnd());
+  }
+  console.log("--- commands ---");
+  for (const command of spec.commands) {
+    console.log(formatCommand(command.command, command.args));
+  }
+}
+
+function launchdDomain() {
+  return `gui/${process.getuid?.() ?? ""}`;
+}
+
+function runPlatformCommand(command, args, label, settings = {}) {
+  const resolved = findExecutable(command);
+  if (!resolved) {
+    console.log(`${label}: ${command} not found. Run this step manually if this platform service manager is available.`);
+    return false;
+  }
+  const useShell = isWindowsShellScript(resolved);
+  console.log(`${label}: ${formatCommand(resolved, args)}`);
+  const result = spawnSync(useShell ? formatShellCommand(resolved, args) : resolved, useShell ? [] : args, {
+    cwd: RUNTIME_ROOT,
+    env: process.env,
+    shell: useShell,
+    stdio: "inherit",
+    windowsHide: false,
+  });
+  if (result.status !== 0 && !settings.allowFailure) {
+    throw new Error(`${label} failed with exit code ${result.status ?? "unknown"}`);
+  }
+  return result.status === 0;
 }
 
 function parseUserFlags(argv) {
@@ -1092,6 +1322,11 @@ async function commandDoctor(options) {
   const userSnapshot = userStore?.snapshot();
   const checks = [];
   checks.push(check("Node.js >= 22", Number.parseInt(process.versions.node.split(".")[0], 10) >= 22, process.version));
+  const cliPath = cliPathDiagnostics();
+  checks.push(check("NordRelay CLI on PATH", cliPath.ok, cliPath.ok ? cliPath.detail : `${cliPath.detail}; ${cliPath.hint}`, "warn"));
+  if (cliPath.globalBin) {
+    checks.push(check("npm global bin on PATH", cliPath.pathContainsGlobalBin, cliPath.globalBin, "warn"));
+  }
   const telegramRequested = process.env.TELEGRAM_ENABLED !== "false";
   const discordRequested = process.env.DISCORD_ENABLED === "true";
   const slackRequested = process.env.SLACK_ENABLED === "true";
@@ -1245,11 +1480,20 @@ async function checkOpenClawGateway() {
 async function commandWeb(options) {
   await mkdirp(options.home);
   loadEnvFiles(options.home);
+  warnIfCliPathMissing();
   await prepareRuntimeForLaunch(options);
   await ensureConnectorStartedForWeb(options);
   await startWebDashboard(options, { detached: false });
 }
 
+async function commandServiceRun(options) {
+  await mkdirp(options.home);
+  loadEnvFiles(options.home);
+  await prepareRuntimeForLaunch(options);
+  await ensureConnectorStartedForWeb(options);
+  await startWebDashboard(options, { detached: false, stopConnectorOnExit: true });
+}
+
 async function startWebDashboard(options, settings = {}) {
   await mkdirp(options.home);
   loadEnvFiles(options.home);
@@ -1335,6 +1579,9 @@ async function startWebDashboard(options, settings = {}) {
     exitCode: exit.code,
     signal: exit.signal,
   });
+  if (settings.stopConnectorOnExit) {
+    await commandStop(options, { keepWeb: true });
+  }
   if (exit.signal) {
     process.kill(process.pid, exit.signal);
     return;
@@ -1723,6 +1970,70 @@ function findExecutable(command, pathValue = process.env.PATH, pathextValue = pr
   return null;
 }
 
+function resolveNpmGlobalBinDir(env = process.env) {
+  const prefix = resolveNpmGlobalPrefix(env);
+  if (!prefix) {
+    return null;
+  }
+  return process.platform === "win32" ? prefix : path.join(prefix, "bin");
+}
+
+function resolveNpmGlobalPrefix(env = process.env) {
+  if (env.npm_config_prefix) {
+    return path.resolve(env.npm_config_prefix);
+  }
+  const npm = resolveNpmSpawnCommand(env);
+  if (!npm) {
+    return null;
+  }
+  const command = npm.shell
+    ? formatShellCommand(npm.command, [...npm.argsPrefix, "prefix", "-g"])
+    : npm.command;
+  const args = npm.shell ? [] : [...npm.argsPrefix, "prefix", "-g"];
+  const result = spawnSync(command, args, {
+    cwd: os.homedir(),
+    env,
+    shell: npm.shell,
+    encoding: "utf8",
+    windowsHide: true,
+    timeout: 5000,
+  });
+  if (result.status !== 0) {
+    return null;
+  }
+  const prefix = String(result.stdout || "").trim().split(/\r?\n/).at(-1)?.trim();
+  return prefix ? path.resolve(prefix) : null;
+}
+
+function pathListIncludes(directory, pathValue = process.env.PATH) {
+  const normalized = normalizePathForCompare(directory);
+  return (pathValue || "")
+    .split(path.delimiter)
+    .filter(Boolean)
+    .some((entry) => normalizePathForCompare(entry) === normalized);
+}
+
+function pathsEqualOrLinked(left, right) {
+  if (!left || !right) {
+    return false;
+  }
+  const normalizedLeft = normalizePathForCompare(left);
+  const normalizedRight = normalizePathForCompare(right);
+  if (normalizedLeft === normalizedRight) {
+    return true;
+  }
+  try {
+    return normalizePathForCompare(fs.realpathSync(left)) === normalizePathForCompare(fs.realpathSync(right));
+  } catch {
+    return false;
+  }
+}
+
+function normalizePathForCompare(value) {
+  const resolved = path.resolve(value || "");
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
 function windowsExecutableExtensions(pathextValue) {
   const pathext = (pathextValue || ".COM;.EXE;.BAT;.CMD")
     .split(";")
@@ -1792,6 +2103,7 @@ function printHelp() {
   console.log("  init                 Create local config and first admin user");
   console.log("  user                 Manage users, groups, and channel links");
   console.log("  peer                 Manage secure NordRelay peer federation");
+  console.log("  service              Install, remove, or inspect the OS service");
   console.log("  doctor               Validate the local setup");
   console.log("  web, dashboard       Start the WebUI and connector");
   console.log("  start                Start the connector");
@@ -1806,6 +2118,7 @@ function printHelp() {
   console.log("  --home <path>        Runtime home directory");
   console.log("  --host <host>        WebUI bind host");
   console.log("  --port <port>        WebUI port");
+  console.log("  service install --dry-run [--platform linux|darwin|win32]");
   console.log("  --build              Build source runtime before start/web/restart");
   console.log("  --force              Overwrite existing config during init");
   console.log("  --help, -h           Show this help");
@@ -1824,6 +2137,7 @@ async function main() {
   if (options.command === "init") return commandInit(options);
   if (options.command === "user") return commandUser(options);
   if (options.command === "peer") return commandPeer(options);
+  if (options.command === "service") return commandService(options);
   if (options.command === "doctor") return commandDoctor(options);
   if (options.command === "update") return commandUpdate(options);
   if (options.command === "web" || options.command === "dashboard") return commandWeb(options);
@@ -1840,18 +2154,29 @@ async function main() {
     return;
   }
   if (options.command === "foreground") return commandForeground(options);
+  if (options.command === "service-run") return commandServiceRun(options);
   if (options.command === "--version" || options.command === "version") {
     console.log(`${APP_NAME} ${VERSION}`);
     return;
   }
 
   console.error(`Unknown command: ${options.command}`);
-  console.error("Usage: nordrelay [init|user|peer|doctor|web|start|stop|restart|status|update|foreground|version]");
+  console.error("Usage: nordrelay [init|user|peer|service|doctor|web|start|stop|restart|status|update|foreground|version]");
   console.error("Run `nordrelay --help` for details.");
   process.exitCode = 2;
 }
 
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exitCode = 1;
-});
+export {
+  buildLaunchdServiceSpec,
+  buildSystemdUserServiceSpec,
+  buildWindowsTaskServiceSpec,
+  parseServiceFlags,
+  serviceInstallSpec,
+};
+
+if (process.argv[1] && path.resolve(process.argv[1]) === SCRIPT_PATH) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/plugins/nordrelay/scripts/service-installer.mjs

@@ -0,0 +1,183 @@
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_SCRIPT_PATH = fileURLToPath(new URL("./nordrelay.mjs", import.meta.url));
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith("-")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function parseServiceFlags(argv) {
+  const copy = [...argv];
+  const subcommand = copy[0] && !copy[0].startsWith("-") ? copy.shift() : "status";
+  const flags = {
+    subcommand,
+    start: true,
+    name: process.platform === "win32" ? "NordRelay" : "nordrelay",
+    label: "io.nordbyte.nordrelay",
+    dryRun: false,
+    platform: process.platform,
+  };
+  for (let i = 0; i < copy.length; i += 1) {
+    const arg = copy[i];
+    if (arg === "--no-start") flags.start = false;
+    else if (arg === "--dry-run") flags.dryRun = true;
+    else if (arg === "--platform") flags.platform = requireValue(copy, ++i, arg);
+    else if (arg === "--name") flags.name = requireValue(copy, ++i, arg);
+    else if (arg === "--label") flags.label = requireValue(copy, ++i, arg);
+  }
+  return flags;
+}
+
+function serviceRunArgs(options) {
+  const args = ["service-run", "--home", options.home];
+  if (options.host) args.push("--host", options.host);
+  if (options.port) args.push("--port", String(options.port));
+  return args;
+}
+
+function buildSystemdUserServiceSpec(options, flags) {
+  const scriptPath = options.scriptPath || DEFAULT_SCRIPT_PATH;
+  const unitPath = path.join(os.homedir(), ".config", "systemd", "user", `${flags.name}.service`);
+  const execStart = [process.execPath, scriptPath, ...serviceRunArgs(options)].map(systemdQuote).join(" ");
+  const content = [
+    "[Unit]",
+    "Description=NordRelay connector and WebUI",
+    "After=network-online.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    `ExecStart=${execStart}`,
+    "Restart=on-failure",
+    "RestartSec=5",
+    `Environment=NORDRELAY_HOME=${systemdQuote(options.home)}`,
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    "",
+  ].join("\n");
+  const action = flags.start ? "enable --now" : "enable";
+  return {
+    platform: "linux",
+    path: unitPath,
+    content,
+    commands: [
+      { command: "systemctl", args: ["--user", "daemon-reload"], label: "Reload systemd user units" },
+      { command: "systemctl", args: ["--user", "enable", flags.start ? "--now" : "", `${flags.name}.service`].filter(Boolean), label: `systemctl --user ${action} ${flags.name}.service` },
+    ],
+  };
+}
+
+function buildLaunchdServiceSpec(options, flags) {
+  const scriptPath = options.scriptPath || DEFAULT_SCRIPT_PATH;
+  const plistPath = path.join(os.homedir(), "Library", "LaunchAgents", `${flags.label}.plist`);
+  const domain = launchdDomain();
+  const commands = [
+    { command: "launchctl", args: ["bootout", domain, plistPath], label: `Unload existing ${flags.label}`, settings: { allowFailure: true } },
+  ];
+  if (flags.start) {
+    commands.push(
+      { command: "launchctl", args: ["bootstrap", domain, plistPath], label: `Load ${flags.label}` },
+      { command: "launchctl", args: ["enable", `${domain}/${flags.label}`], label: `Enable ${flags.label}`, settings: { allowFailure: true } },
+      { command: "launchctl", args: ["kickstart", "-k", `${domain}/${flags.label}`], label: `Start ${flags.label}`, settings: { allowFailure: true } },
+    );
+  }
+  return {
+    platform: "darwin",
+    path: plistPath,
+    content: launchdPlist(flags.label, process.execPath, [scriptPath, ...serviceRunArgs(options)], options.home),
+    commands,
+  };
+}
+
+function buildWindowsTaskServiceSpec(options, flags) {
+  const scriptPath = options.scriptPath || DEFAULT_SCRIPT_PATH;
+  const taskCommand = windowsTaskCommand(process.execPath, [scriptPath, ...serviceRunArgs(options)]);
+  const commands = [
+    { command: "schtasks", args: ["/Create", "/F", "/SC", "ONLOGON", "/TN", flags.name, "/TR", taskCommand], label: `Create Windows task ${flags.name}` },
+  ];
+  if (flags.start) {
+    commands.push({ command: "schtasks", args: ["/Run", "/TN", flags.name], label: `Start Windows task ${flags.name}`, settings: { allowFailure: true } });
+  }
+  return {
+    platform: "win32",
+    path: flags.name,
+    content: "",
+    commands,
+  };
+}
+
+function serviceInstallSpec(options, flags) {
+  if (flags.platform === "darwin") return buildLaunchdServiceSpec(options, flags);
+  if (flags.platform === "win32") return buildWindowsTaskServiceSpec(options, flags);
+  return buildSystemdUserServiceSpec(options, flags);
+}
+
+function systemdQuote(value) {
+  return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function launchdDomain() {
+  return `gui/${process.getuid?.() ?? ""}`;
+}
+
+function launchdPlist(label, command, args, home) {
+  const programArguments = [command, ...args]
+    .map((value) => `    <string>${xmlEscape(value)}</string>`)
+    .join("\n");
+  return [
+    "<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
+    "<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">",
+    "<plist version=\"1.0\">",
+    "<dict>",
+    "  <key>Label</key>",
+    `  <string>${xmlEscape(label)}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    programArguments,
+    "  </array>",
+    "  <key>EnvironmentVariables</key>",
+    "  <dict>",
+    "    <key>NORDRELAY_HOME</key>",
+    `    <string>${xmlEscape(home)}</string>`,
+    "  </dict>",
+    "  <key>RunAtLoad</key>",
+    "  <true/>",
+    "  <key>KeepAlive</key>",
+    "  <true/>",
+    "  <key>StandardOutPath</key>",
+    `  <string>${xmlEscape(path.join(home, "service.log"))}</string>`,
+    "  <key>StandardErrorPath</key>",
+    `  <string>${xmlEscape(path.join(home, "service.log"))}</string>`,
+    "</dict>",
+    "</plist>",
+    "",
+  ].join("\n");
+}
+
+function windowsTaskCommand(command, args) {
+  return [command, ...args].map((part) => `"${String(part).replace(/"/g, '""')}"`).join(" ");
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+export {
+  buildLaunchdServiceSpec,
+  buildSystemdUserServiceSpec,
+  buildWindowsTaskServiceSpec,
+  parseServiceFlags,
+  serviceInstallSpec,
+};