@nordbyte/nordrelay 0.8.1 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nordbyte/nordrelay",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Remote control plane for coding agents across messaging channels.",
   "type": "module",
   "author": "Ricardo",
@@ -34,7 +34,8 @@
   "files": [
     "dist/",
     "plugins/",
-    "launchd/",
+    "scripts/postinstall.mjs",
+    "scripts/launchd-start.sh",
     ".env.example",
     "Dockerfile",
     "docker-compose.yml"
@@ -43,14 +44,16 @@
     "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",
+    "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",
+    "size:check": "node scripts/check-module-size.mjs",
     "sbom": "npm sbom --json > sbom.json",
     "status": "node plugins/nordrelay/scripts/nordrelay.mjs status",
     "start": "node plugins/nordrelay/scripts/nordrelay.mjs start",

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;
@@ -1486,7 +1733,7 @@ function runtimeBuildStatus() {
   ]);
   const distTargets = [
     path.join(RUNTIME_ROOT, "dist", "index.js"),
-    path.join(RUNTIME_ROOT, "dist", "web-dashboard.js"),
+    path.join(RUNTIME_ROOT, "dist", "web", "web-dashboard.js"),
     path.join(RUNTIME_ROOT, "dist", "webui-assets", "dashboard.js"),
     path.join(RUNTIME_ROOT, "dist", "webui-assets", "dashboard.css"),
   ];
@@ -1583,12 +1830,12 @@ async function runInteractiveStep(label, command, args, settings = {}) {
 }
 
 async function resolveWebRuntimeEntry() {
-  const distEntry = path.join(RUNTIME_ROOT, "dist", "web-dashboard.js");
+  const distEntry = path.join(RUNTIME_ROOT, "dist", "web", "web-dashboard.js");
   if (fs.existsSync(distEntry)) {
     return { command: process.execPath, args: [distEntry] };
   }
 
-  const tsEntry = path.join(RUNTIME_ROOT, "src", "web-dashboard.ts");
+  const tsEntry = path.join(RUNTIME_ROOT, "src", "web", "web-dashboard.ts");
   const tsxBin = path.join(RUNTIME_ROOT, "node_modules", ".bin", process.platform === "win32" ? "tsx.cmd" : "tsx");
   if (fs.existsSync(tsEntry) && fs.existsSync(tsxBin)) {
     return { command: tsxBin, args: [tsEntry] };
@@ -1712,7 +1959,7 @@ function findExecutable(command, pathValue = process.env.PATH, pathextValue = pr
   if (command.includes(path.sep) && fs.existsSync(command)) return command;
   const paths = (pathValue || "").split(path.delimiter);
   const extensions = process.platform === "win32"
-    ? ["", ...(pathextValue || ".COM;.EXE;.BAT;.CMD").split(";")]
+    ? windowsExecutableExtensions(pathextValue)
     : [""];
   for (const dir of paths) {
     for (const extension of extensions) {
@@ -1723,6 +1970,79 @@ 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(";")
+    .map((extension) => extension.trim())
+    .filter(Boolean)
+    .map((extension) => extension.startsWith(".") ? extension : `.${extension}`);
+  return [...new Set([...pathext, ""])];
+}
+
 function isWindowsShellScript(filePath) {
   return process.platform === "win32" && /\.(?:cmd|bat)$/i.test(filePath);
 }
@@ -1783,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");
@@ -1797,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");
@@ -1815,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);
@@ -1831,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;
+  });
+}