herdr-remote 0.2.0

package/src/i18n/zh.js

@@ -0,0 +1,218 @@
+'use strict';
+
+// 简体中文文案。键名必须与 en.js 完全一致，由 tests/i18n.test.js 校验。
+
+module.exports = {
+  'app.name': 'Herdr Remote',
+  'app.tagline': '在浏览器里远程使用你的 Herdr 工作区',
+
+  'common.yes': '是',
+  'common.no': '否',
+  'common.on': '开',
+  'common.off': '关',
+  'common.none': '无',
+  'common.auto': '自动',
+  'common.unknown': '未知',
+  'common.running': '运行中',
+  'common.stopped': '已停止',
+  'common.connected': '已连接',
+  'common.disconnected': '未连接',
+  'common.installed': '已安装',
+  'common.notInstalled': '未安装',
+  'common.enabled': '已启用',
+  'common.disabled': '已停用',
+  'common.loading': '处理中…',
+  'common.save': '保存设置',
+  'common.saved': '配置已保存到 {path}',
+  'common.back': '返回',
+  'common.cancel': '取消',
+  'common.confirm': '确认',
+  'common.pid': '进程 {pid}',
+  'common.notApplicable': '不适用',
+
+  'nav.overview': '概览',
+  'nav.pair': '配对设备',
+  'nav.services': '服务',
+  'nav.relay': 'Relay',
+  'nav.keepalive': '保活',
+  'nav.herdr': 'Herdr',
+  'nav.about': '语言与关于',
+
+  'mode.local': '仅本机',
+  'mode.lan': '局域网 / Tailscale',
+  'mode.remote': '自建 relay',
+  'mode.local.description': 'relay 监听 127.0.0.1，只有本机浏览器能访问。',
+  'mode.lan.description': 'relay 监听 0.0.0.0（所有网卡），局域网或 tailnet 里的手机都能访问。',
+  'mode.remote.description': '不启动本地 relay。本机连接你自建的 relay，这是从外网访问的唯一方式。',
+
+  'overview.title': '状态',
+  'overview.mode': '访问方式',
+  'overview.relay': 'Relay',
+  'overview.host': '主机连接器',
+  'overview.socket': 'Herdr 套接字',
+  'overview.webUrl': 'Web 界面',
+  'overview.keepalive': '保活服务',
+  'overview.devices': '浏览器',
+  'overview.hosts': '工作站',
+  'overview.uptime': 'Relay 运行时长',
+  'overview.relayLocal': '本地，{bind}:{port}',
+  'overview.relayRemote': '远程，{url}',
+  'overview.socketMissing': '未找到 — Herdr 在运行吗？',
+  'overview.unreachable': '无法访问：{message}',
+  'overview.notStarted': '服务未运行，请到「服务」页面启动。',
+
+  'pair.title': '配对设备',
+  'pair.generate': '生成一次性配对码',
+  'pair.regenerate': '重新生成配对码',
+  'pair.working': '正在启动服务并申请配对码…',
+  'pair.code': '配对码',
+  'pair.url': '在手机上打开',
+  'pair.expires': '剩余 {minutes}（至 {time}）',
+  'pair.expired': '配对码已过期，请重新生成。',
+  'pair.instructions': '打开链接、输入配对码，之后这台浏览器就长期可用了。',
+  'pair.qrHint': '用手机相机扫码即可打开链接。',
+  'pair.qrUnavailable': '终端宽度不足以显示二维码，请使用上面的链接。',
+  'pair.failed': '生成配对码失败：{message}',
+  'pair.hostOffline': 'relay 上还没有工作站连接，请先启动服务。',
+
+  'services.title': '服务',
+  'services.start': '启动服务',
+  'services.stop': '停止服务',
+  'services.restart': '重启服务',
+  'services.started': '服务已启动。',
+  'services.stopped': '服务已停止。',
+  'services.restarted': '服务已重启。',
+  'services.startFailed': '启动服务失败：{message}',
+  'services.stopFailed': '停止服务失败：{message}',
+  'services.unsavedBlocked': '有未保存的修改。请先保存，否则服务会用磁盘上的旧配置重启。',
+  'services.managedNotice': '服务由 {manager} 托管，已通过保活服务执行此操作。',
+  'services.logs': '最近日志',
+  'services.logEmpty': '暂无日志输出。',
+  'services.logRelay': 'Relay',
+  'services.logHost': '主机连接器',
+
+  'relay.title': 'Relay 设置',
+  'relay.settings': '设置',
+  'relay.password': 'Relay 密码',
+  'relay.passwordHint': '需与 relay 上的 RELAY_PASSWORD 一致。留空表示公用 relay。',
+  'relay.passwordSet': '已设置',
+  'relay.passwordEmpty': '未设置（公用 relay）',
+  'relay.passwordSaved': 'Relay 密码已保存，重启服务后生效。',
+  'relay.showPassword': '显示密码',
+  'relay.hidePassword': '隐藏密码',
+  'relay.identity': '工作站标识',
+  'relay.regenerate': '重新生成工作站标识',
+  'relay.regenerated': '已生成新的工作站标识，重启服务后会重新注册。',
+  'relay.envSnippet': 'relay 服务器启动命令',
+  'relay.envHint': '在 relay 主机上执行这条命令。',
+  'relay.test': '测试 relay 连接',
+  'relay.testOk': 'relay 可访问：版本 {version}，已连接 {hosts} 台工作站。',
+  'relay.testFailed': 'relay 无法访问：{message}',
+  'relay.selectAddress': '选择对外公布的地址',
+  'relay.listenAddress': '监听地址',
+  'relay.listenAddressHint': '这是服务器绑定地址；下面的对外公布地址才是浏览器要打开的地址。',
+  'relay.addressTailscale': 'Tailscale',
+  'relay.addressLan': '局域网',
+  'relay.addressVirtual': '虚拟网卡',
+  'relay.addressLoopback': '回环',
+  'relay.noAddresses': '没有找到非回环地址，请先连接网络或启动 Tailscale。',
+  'relay.docsHint': '自建 relay 请参阅 docs/self-hosted-relay.zh-CN.md',
+
+  'keepalive.title': '后台保活服务',
+  'keepalive.manager': '管理方式',
+  'keepalive.state': '状态',
+  'keepalive.install': '安装并启动',
+  'keepalive.uninstall': '停止并移除',
+  'keepalive.restart': '重启保活服务',
+  'keepalive.installed': '已通过 {manager} 安装保活服务。',
+  'keepalive.uninstalled': '保活服务已移除。',
+  'keepalive.restarted': '保活服务已重启。',
+  'keepalive.failed': '保活操作失败：{message}',
+  'keepalive.unitPath': '单元文件',
+  'keepalive.logsHint': '查看日志：{command}',
+  'keepalive.linger': '未登录也开机自启',
+  'keepalive.lingerEnabled': '已开启 linger：开机即启动。',
+  'keepalive.lingerDisabled': '未开启 linger，服务只在你登录期间运行。',
+  'keepalive.enableLinger': '开启开机自启',
+  'keepalive.lingerDone': '已为 {username} 开启 linger。',
+  'keepalive.fallbackNote': '系统没有可用的服务管理器，改用内置的后台守护进程，重启电脑后不会自动恢复。',
+
+  'herdr.title': 'Herdr 集成',
+  'herdr.socketPath': '套接字路径',
+  'herdr.args': '附加参数',
+  'herdr.plugin': '插件注册',
+  'herdr.pluginRegistered': '已注册到 Herdr。',
+  'herdr.pluginMissing': '尚未注册到 Herdr。',
+  'herdr.register': '把本包注册为 Herdr 插件',
+  'herdr.unregister': '取消注册 Herdr 插件',
+  'herdr.registerDone': '已注册：{path}',
+  'herdr.unregisterDone': '插件已取消注册。',
+  'herdr.registerFailed': '注册失败：{message}',
+  'herdr.cliMissing': 'PATH 中找不到 herdr 命令。',
+
+  'about.title': '语言与关于',
+  'about.language': '界面语言',
+  'about.languageAuto': '跟随系统（{detected}）',
+  'about.languageZh': '中文',
+  'about.languageEn': 'English',
+  'about.version': '版本',
+  'about.configPath': '配置文件',
+  'about.statePath': '状态目录',
+  'about.relayPackage': 'Relay 包',
+  'about.docs': '自建 relay 指南：docs/self-hosted-relay.zh-CN.md',
+
+  'wizard.title': '首次设置',
+  'wizard.step': '第 {current} / {total} 步',
+  'wizard.languageTitle': '选择语言',
+  'wizard.accessTitle': '你打算怎么访问这台机器？',
+  'wizard.accessHint': '之后可以在 Relay 页面随时修改。',
+  'wizard.addressTitle': '手机应该使用哪个地址？',
+  'wizard.relayTitle': '你的 relay 服务器',
+  'wizard.relayUrlLabel': 'Relay 地址（wss://…）',
+  'wizard.relayHint': 'relay 需要已经在运行。搭建方法见 docs/self-hosted-relay.zh-CN.md。',
+  'wizard.passwordTitle': 'Relay 密码',
+  'wizard.passwordHint': 'relay 启动时设置的 RELAY_PASSWORD。relay 没设密码就留空。',
+  'wizard.finishTitle': '完成',
+  'wizard.finishHint': '配置将保存到 {path}。',
+  'wizard.startNow': '立即启动服务',
+  'wizard.installKeepalive': '让服务在后台保持运行',
+  'wizard.finish': '保存并继续',
+
+  'field.mode': '访问方式',
+  'field.port': 'Relay 端口',
+  'field.lanHost': '浏览器地址',
+  'field.remoteUrl': 'Relay 地址',
+  'field.publicUrl': '浏览器地址（覆盖）',
+  'field.socketPath': 'Herdr 套接字路径',
+  'field.herdrArgs': 'Herdr 参数',
+  'field.language': '语言',
+  'field.keepalive': '保活管理方式',
+
+  'placeholder.autoDiscovered': '自动探测',
+  'placeholder.none': '无',
+
+  'error.invalidMode': '未知的访问方式。',
+  'error.invalidPort': '端口必须是 1 到 65535 之间的数字。',
+  'error.invalidLanHost': '浏览器地址必须是可访问的局域网或 Tailscale 地址，不能填写回环地址或 0.0.0.0。',
+  'error.invalidRelayUrl': 'Relay 地址需以 wss://、ws://、https:// 或 http:// 开头。',
+  'error.invalidPublicUrl': '浏览器地址需以 https:// 或 http:// 开头，不能使用 0.0.0.0 或 ::。',
+  'error.invalidLanguage': '未知的语言。',
+  'error.invalidKeepalive': '未知的保活管理方式。',
+  'error.unknownField': '未知的设置项。',
+  'error.remoteUrlRequired': '自建 relay 模式必须填写 Relay 地址。',
+  'error.saveFailed': '保存配置失败：{message}',
+
+  'hint.navigate': '↑↓ 移动',
+  'hint.select': '↵ 选择',
+  'hint.edit': '↵ 编辑',
+  'hint.tabs': '← → 切换页面',
+  'hint.back': 'esc 返回',
+  'hint.quit': 'q 退出',
+  'hint.mouseOn': 'm 关闭鼠标',
+  'hint.mouseOff': 'm 开启鼠标',
+  'hint.mouseUnsupported': '不支持鼠标',
+  'hint.restartRequired': '需要重启服务才能生效。',
+  'hint.unsavedChanges': '有未保存的修改 — 按 s 保存。',
+  'hint.save': 's 保存',
+  'hint.editing': '↵ 确认 · esc 取消',
+};

package/src/keepalive.js

@@ -0,0 +1,404 @@
+'use strict';
+
+// Keep-alive integration.
+//
+// "Start the services" and "keep the services running" are different problems:
+// a detached spawn dies with the first crash and never comes back. This module
+// hands supervision to the platform's service manager where one exists
+// (systemd --user on Linux, launchd on macOS) and falls back to a detached copy
+// of our own supervisor where neither does.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn, spawnSync } = require('node:child_process');
+const { PACKAGE_ROOT, loadConfig, stateDir } = require('./config');
+const { ensureDir, readJson, writeJsonAtomic } = require('./state');
+const { logPath, pidAlive } = require('./service');
+
+const SYSTEMD_UNIT_NAME = 'herdr-remote.service';
+const LAUNCHD_LABEL = 'dev.herdr.remote';
+const FALLBACK_PID_FILE = 'supervisor.pid';
+
+function cliEntryPoint() {
+  return path.join(PACKAGE_ROOT, 'bin', 'herdr-remote.js');
+}
+
+function systemdUnitPath() {
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(configHome, 'systemd', 'user', SYSTEMD_UNIT_NAME);
+}
+
+function launchdPlistPath() {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+}
+
+function fallbackPidPath() {
+  return path.join(stateDir(), FALLBACK_PID_FILE);
+}
+
+/**
+ * Look for an executable on PATH without going through a shell: `spawnSync`
+ * with `shell: true` concatenates rather than escapes its arguments, and Node
+ * now warns about it on every call.
+ */
+function commandExists(command) {
+  const searchPath = process.env.PATH || '';
+  return searchPath.split(path.delimiter).filter(Boolean).some((directory) => {
+    try {
+      fs.accessSync(path.join(directory, command), fs.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** Which manager to use given the platform, the user's preference and reality. */
+function detectManager(preference = 'auto') {
+  if (preference && preference !== 'auto') return preference;
+  if (process.platform === 'linux') {
+    // `systemctl --user` needs a user bus; containers and bare TTY logins often
+    // have systemd installed but no session bus, where it would fail at runtime.
+    if (commandExists('systemctl') && (process.env.DBUS_SESSION_BUS_ADDRESS || process.env.XDG_RUNTIME_DIR)) {
+      return 'systemd';
+    }
+    return 'supervisor';
+  }
+  if (process.platform === 'darwin') {
+    return commandExists('launchctl') ? 'launchd' : 'supervisor';
+  }
+  return 'supervisor';
+}
+
+// ---------------------------------------------------------------------------
+// Unit file rendering (pure, so it can be asserted in tests)
+// ---------------------------------------------------------------------------
+
+function renderSystemdUnit({ nodePath = process.execPath, entryPoint = cliEntryPoint(), environment = {} } = {}) {
+  const environmentLines = Object.entries(environment)
+    .map(([key, value]) => `Environment=${key}=${value}`)
+    .join('\n');
+  return `[Unit]
+Description=Herdr Remote (relay and host connector)
+Documentation=https://github.com/herdr/herdr-remote
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=${nodePath} ${entryPoint} run
+Restart=always
+RestartSec=3
+# Give the relay and host connector time to close sessions cleanly.
+TimeoutStopSec=15
+${environmentLines}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function renderLaunchdPlist({
+  nodePath = process.execPath,
+  entryPoint = cliEntryPoint(),
+  label = LAUNCHD_LABEL,
+  outLog = logPath('supervisor'),
+  errLog = logPath('supervisor'),
+  environment = {},
+} = {}) {
+  const environmentEntries = Object.entries(environment)
+    .map(([key, value]) => `      <key>${escapeXml(key)}</key>\n      <string>${escapeXml(value)}</string>`)
+    .join('\n');
+  const environmentBlock = environmentEntries
+    ? `    <key>EnvironmentVariables</key>\n    <dict>\n${environmentEntries}\n    </dict>\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>${escapeXml(label)}</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>${escapeXml(nodePath)}</string>
+      <string>${escapeXml(entryPoint)}</string>
+      <string>run</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ProcessType</key>
+    <string>Background</string>
+${environmentBlock}    <key>StandardOutPath</key>
+    <string>${escapeXml(outLog)}</string>
+    <key>StandardErrorPath</key>
+    <string>${escapeXml(errLog)}</string>
+  </dict>
+</plist>
+`;
+}
+
+// ---------------------------------------------------------------------------
+// systemd
+// ---------------------------------------------------------------------------
+
+function systemctl(args, { capture = true } = {}) {
+  return spawnSync('systemctl', ['--user', ...args], {
+    encoding: 'utf8',
+    stdio: capture ? 'pipe' : 'inherit',
+  });
+}
+
+function systemdStatus() {
+  const installed = fs.existsSync(systemdUnitPath());
+  if (!installed) return { manager: 'systemd', installed: false, active: false, enabled: false };
+  const active = systemctl(['is-active', SYSTEMD_UNIT_NAME]);
+  const enabled = systemctl(['is-enabled', SYSTEMD_UNIT_NAME]);
+  const lingering = spawnSync('loginctl', ['show-user', os.userInfo().username, '--property=Linger'], { encoding: 'utf8' });
+  return {
+    manager: 'systemd',
+    installed: true,
+    active: String(active.stdout || '').trim() === 'active',
+    enabled: String(enabled.stdout || '').trim().startsWith('enabled'),
+    linger: String(lingering.stdout || '').includes('Linger=yes'),
+    unitPath: systemdUnitPath(),
+    state: String(active.stdout || active.stderr || '').trim(),
+  };
+}
+
+function systemdInstall() {
+  const unitPath = systemdUnitPath();
+  ensureDir(path.dirname(unitPath));
+  fs.writeFileSync(unitPath, renderSystemdUnit(), { mode: 0o644 });
+  const reload = systemctl(['daemon-reload']);
+  if (reload.status !== 0) {
+    throw new Error(`systemctl --user daemon-reload failed: ${String(reload.stderr || '').trim()}`);
+  }
+  const enable = systemctl(['enable', '--now', SYSTEMD_UNIT_NAME]);
+  if (enable.status !== 0) {
+    throw new Error(`systemctl --user enable --now failed: ${String(enable.stderr || '').trim()}`);
+  }
+  return { ok: true, unitPath, hint: `loginctl enable-linger ${os.userInfo().username}` };
+}
+
+function systemdUninstall() {
+  const unitPath = systemdUnitPath();
+  systemctl(['disable', '--now', SYSTEMD_UNIT_NAME]);
+  if (fs.existsSync(unitPath)) fs.rmSync(unitPath, { force: true });
+  systemctl(['daemon-reload']);
+  return { ok: true, unitPath };
+}
+
+// ---------------------------------------------------------------------------
+// launchd
+// ---------------------------------------------------------------------------
+
+function launchdDomainTarget() {
+  return `gui/${process.getuid ? process.getuid() : ''}`;
+}
+
+function launchdStatus() {
+  const plistPath = launchdPlistPath();
+  const installed = fs.existsSync(plistPath);
+  if (!installed) return { manager: 'launchd', installed: false, active: false, enabled: false };
+  const result = spawnSync('launchctl', ['print', `${launchdDomainTarget()}/${LAUNCHD_LABEL}`], { encoding: 'utf8' });
+  const output = String(result.stdout || '');
+  return {
+    manager: 'launchd',
+    installed: true,
+    active: result.status === 0 && /state = running/.test(output),
+    enabled: result.status === 0,
+    unitPath: plistPath,
+    state: result.status === 0 ? 'loaded' : 'not loaded',
+  };
+}
+
+function launchdInstall() {
+  const plistPath = launchdPlistPath();
+  ensureDir(path.dirname(plistPath));
+  ensureDir(stateDir());
+  fs.writeFileSync(plistPath, renderLaunchdPlist(), { mode: 0o644 });
+  // bootout first so a re-install picks up the rewritten plist.
+  spawnSync('launchctl', ['bootout', `${launchdDomainTarget()}/${LAUNCHD_LABEL}`], { stdio: 'ignore' });
+  const result = spawnSync('launchctl', ['bootstrap', launchdDomainTarget(), plistPath], { encoding: 'utf8' });
+  if (result.status !== 0) {
+    throw new Error(`launchctl bootstrap failed: ${String(result.stderr || '').trim()}`);
+  }
+  spawnSync('launchctl', ['enable', `${launchdDomainTarget()}/${LAUNCHD_LABEL}`], { stdio: 'ignore' });
+  return { ok: true, unitPath: plistPath };
+}
+
+function launchdUninstall() {
+  const plistPath = launchdPlistPath();
+  spawnSync('launchctl', ['bootout', `${launchdDomainTarget()}/${LAUNCHD_LABEL}`], { stdio: 'ignore' });
+  if (fs.existsSync(plistPath)) fs.rmSync(plistPath, { force: true });
+  return { ok: true, unitPath: plistPath };
+}
+
+// ---------------------------------------------------------------------------
+// Fallback supervisor daemon
+// ---------------------------------------------------------------------------
+
+function readFallbackPid() {
+  const record = readJson(fallbackPidPath(), {});
+  return Number.isInteger(record.pid) ? record.pid : null;
+}
+
+function fallbackStatus() {
+  const pid = readFallbackPid();
+  const alive = pidAlive(pid);
+  return {
+    manager: 'supervisor',
+    installed: alive,
+    active: alive,
+    enabled: false,
+    pid: alive ? pid : null,
+    unitPath: fallbackPidPath(),
+    state: alive ? 'running' : 'stopped',
+  };
+}
+
+function fallbackInstall() {
+  if (pidAlive(readFallbackPid())) return { ok: true, alreadyRunning: true, pid: readFallbackPid() };
+  ensureDir(stateDir());
+  const logFd = fs.openSync(logPath('supervisor'), 'a');
+  try {
+    const child = spawn(process.execPath, [cliEntryPoint(), 'run', '--daemon'], {
+      cwd: PACKAGE_ROOT,
+      env: { ...process.env, HERDR_REMOTE_SERVICE: '1' },
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+    });
+    child.unref();
+    writeJsonAtomic(fallbackPidPath(), { pid: child.pid, startedAt: new Date().toISOString() });
+    return { ok: true, pid: child.pid, note: 'this fallback does not survive a reboot' };
+  } finally {
+    fs.closeSync(logFd);
+  }
+}
+
+function fallbackUninstall() {
+  const pid = readFallbackPid();
+  if (pidAlive(pid)) {
+    try { process.kill(pid, 'SIGTERM'); } catch {}
+  }
+  try { fs.rmSync(fallbackPidPath(), { force: true }); } catch {}
+  return { ok: true, stoppedPid: pid };
+}
+
+// ---------------------------------------------------------------------------
+// Public surface
+// ---------------------------------------------------------------------------
+
+function resolveManager(config = loadConfig()) {
+  return detectManager(config.keepalive?.manager || 'auto');
+}
+
+function status(config = loadConfig()) {
+  const manager = resolveManager(config);
+  if (manager === 'none') return { manager: 'none', installed: false, active: false, enabled: false };
+  if (manager === 'systemd') return systemdStatus();
+  if (manager === 'launchd') return launchdStatus();
+  return fallbackStatus();
+}
+
+function install(config = loadConfig()) {
+  const manager = resolveManager(config);
+  if (manager === 'systemd') return { manager, ...systemdInstall() };
+  if (manager === 'launchd') return { manager, ...launchdInstall() };
+  if (manager === 'none') throw new Error('keep-alive is disabled in the configuration');
+  return { manager: 'supervisor', ...fallbackInstall() };
+}
+
+function uninstall(config = loadConfig()) {
+  const manager = resolveManager(config);
+  if (manager === 'systemd') return { manager, ...systemdUninstall() };
+  if (manager === 'launchd') return { manager, ...launchdUninstall() };
+  return { manager: 'supervisor', ...fallbackUninstall() };
+}
+
+/** Restart whatever manages the services, so config edits take effect. */
+function restart(config = loadConfig()) {
+  const manager = resolveManager(config);
+  if (manager === 'systemd') {
+    const result = systemctl(['restart', SYSTEMD_UNIT_NAME]);
+    if (result.status !== 0) throw new Error(String(result.stderr || '').trim() || 'systemctl restart failed');
+    return { manager, ok: true };
+  }
+  if (manager === 'launchd') {
+    spawnSync('launchctl', ['kickstart', '-k', `${launchdDomainTarget()}/${LAUNCHD_LABEL}`], { stdio: 'ignore' });
+    return { manager, ok: true };
+  }
+  fallbackUninstall();
+  return { manager: 'supervisor', ...fallbackInstall() };
+}
+
+/**
+ * Stop the managed services. Killing the child pids directly would only make
+ * the service manager start them again, so an installed manager is asked to
+ * stop instead.
+ */
+function stopManaged(config = loadConfig()) {
+  const current = status(config);
+  if (!current.installed && !current.active) return { managed: false };
+  if (current.manager === 'systemd') {
+    systemctl(['stop', SYSTEMD_UNIT_NAME]);
+    return { managed: true, manager: 'systemd' };
+  }
+  if (current.manager === 'launchd') {
+    spawnSync('launchctl', ['bootout', `${launchdDomainTarget()}/${LAUNCHD_LABEL}`], { stdio: 'ignore' });
+    return { managed: true, manager: 'launchd' };
+  }
+  if (current.manager === 'supervisor' && current.active) {
+    fallbackUninstall();
+    return { managed: true, manager: 'supervisor' };
+  }
+  return { managed: false };
+}
+
+function enableLinger() {
+  const username = os.userInfo().username;
+  const result = spawnSync('loginctl', ['enable-linger', username], { encoding: 'utf8' });
+  if (result.status !== 0) {
+    throw new Error(String(result.stderr || '').trim() || 'loginctl enable-linger failed');
+  }
+  return { ok: true, username };
+}
+
+function logsHint(config = loadConfig()) {
+  const manager = resolveManager(config);
+  if (manager === 'systemd') return `journalctl --user -u ${SYSTEMD_UNIT_NAME} -f`;
+  if (manager === 'launchd') return `tail -f ${logPath('supervisor')}`;
+  return `tail -f ${logPath('supervisor')}`;
+}
+
+module.exports = {
+  SYSTEMD_UNIT_NAME,
+  LAUNCHD_LABEL,
+  cliEntryPoint,
+  systemdUnitPath,
+  launchdPlistPath,
+  fallbackPidPath,
+  detectManager,
+  resolveManager,
+  renderSystemdUnit,
+  renderLaunchdPlist,
+  escapeXml,
+  status,
+  install,
+  uninstall,
+  restart,
+  stopManaged,
+  enableLinger,
+  logsHint,
+};

package/src/lifecycle.js

@@ -0,0 +1,58 @@
+'use strict';
+
+// Start/stop/restart that respect the keep-alive manager.
+//
+// When systemd or launchd supervises the services, killing the processes just
+// makes the manager start them again — and starting them by hand produces a
+// second, unmanaged copy fighting for the port. Every entry point goes through
+// here so the managed and unmanaged paths behave the same from the outside.
+
+const { loadConfig } = require('./config');
+const keepalive = require('./keepalive');
+const { restartServices, startServices, statusServices, stopServices } = require('./service');
+
+function managerInUse(config) {
+  const status = keepalive.status(config);
+  return status.installed || status.active ? status : null;
+}
+
+function startAll(config = loadConfig()) {
+  const managed = managerInUse(config);
+  if (managed) {
+    keepalive.restart(config);
+    return { ok: true, managed: true, manager: managed.manager };
+  }
+  return { ...startServices(), managed: false };
+}
+
+function stopAll(config = loadConfig()) {
+  const result = keepalive.stopManaged(config);
+  if (result.managed) {
+    // The manager stops the supervisor, which stops its children; clear the
+    // recorded pids so status does not report ghosts.
+    stopServices();
+    return { ok: true, managed: true, manager: result.manager };
+  }
+  return { ...stopServices(), managed: false };
+}
+
+function restartAll(config = loadConfig()) {
+  const managed = managerInUse(config);
+  if (managed) {
+    keepalive.restart(config);
+    return { ok: true, managed: true, manager: managed.manager };
+  }
+  return { ...restartServices(), managed: false };
+}
+
+/** Service status plus the keep-alive picture, which is what the TUI shows. */
+async function fullStatus(config = loadConfig()) {
+  const [services, keepaliveStatus] = [await statusServices(), keepalive.status(config)];
+  return {
+    ...services,
+    keepalive: keepaliveStatus,
+    logsHint: keepalive.logsHint(config),
+  };
+}
+
+module.exports = { startAll, stopAll, restartAll, fullStatus, managerInUse };