herdr-remote 0.2.17 → 0.2.19

package/dist/i18n/zh.js

@@ -0,0 +1,222 @@
+// 简体中文文案。键名必须与 en.ts 完全一致，由类型和 tests/i18n.test.js 校验。
+const zh = {
+    '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 {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.official': '官方 Relay',
+    'mode.remote': '自建 Relay',
+    'mode.local.description': '监听 127.0.0.1，仅本机可访问。',
+    'mode.lan.description': '监听 0.0.0.0，局域网与 Tailscale 设备可访问。',
+    'mode.official.description': '使用官方 Relay 跨网访问，无需自建服务器。',
+    'mode.remote.description': '连接自建 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.locked': '固定',
+    'relay.officialFixed': '官方 relay 地址固定，不可修改。',
+    'relay.officialHint': '官方 relay：地址固定，无需密码。',
+    'relay.password': 'Relay 密码',
+    'relay.passwordHint': '须与 Relay 端的 RELAY_PASSWORD 一致。留空为公用 Relay。',
+    'relay.passwordSet': '已设置',
+    'relay.passwordEmpty': '未设置（公用）',
+    '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': '未找到非回环地址。',
+    'relay.docsHint': '自建指南：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': '已开启开机自启。',
+    'keepalive.lingerDisabled': '未开启开机自启（仅登录期间运行）。',
+    'keepalive.enableLinger': '开启开机自启',
+    'keepalive.lingerDone': '已为 {username} 开启开机自启。',
+    'keepalive.fallbackNote': '无系统服务管理器，使用后台守护进程，重启后不自动恢复。',
+    'herdr.title': 'Herdr 集成',
+    'herdr.socketPath': '套接字路径',
+    'herdr.args': '附加参数',
+    'herdr.autoStartHint': '关：Herdr 只在你手动运行，或在浏览器里确认后才启动。开：herdr-remote 每次启动（包括开机）时一并启动 Herdr。下次 herdr-remote 启动时生效。',
+    'herdr.cliMissing': '未找到 herdr 命令，可将 HERDR_BIN_PATH 设为其完整路径。',
+    'herdr.version': 'Herdr 版本',
+    'herdr.versionOutdated': 'Herdr {version} 低于 {minimum}，请运行 “herdr update”：在该版本之前，浏览器窗口的标题、后台机器激活与大段粘贴都会出问题。',
+    'about.title': '语言与关于',
+    'about.language': '界面语言',
+    'about.languageAuto': '跟随系统（{detected}）',
+    'about.languageZh': '中文',
+    'about.languageEn': 'English',
+    'about.version': '版本',
+    'about.configPath': '配置文件',
+    'about.statePath': '状态目录',
+    'about.relayPackage': 'Relay 包',
+    'about.docs': '自建指南：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。未设留空。',
+    '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.herdrAutoStart': '随服务启动 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.removedHerdrArg': 'Herdr 0.9.0 已移除 --no-session，请从附加参数中移除。',
+    '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 取消',
+    'update.title': '更新',
+    'update.banner': 'herdr-remote {latest} 已发布（当前 {current}），按 7 进入「语言与关于」，在更新一行按 Enter 安装。',
+    'update.check': '检查更新',
+    'update.checking': '查询 npm 中…',
+    'update.upToDate': '已是最新（{version}）',
+    'update.available': '新版本 {version} 可用（按 Enter 安装）',
+    'update.updating': '安装 {version} 中…',
+    'update.updatingRetry': '安装 {version} 中…（npm 尚未同步，第 {attempt} 次尝试）',
+    'update.done': '已更新至 {version}',
+    'update.restartHint': '更新已安装，重启 herdr-remote 生效。',
+    'update.errorNetwork': '所有 npm registry 均无法连接',
+    'update.errorNetworkDetail': '无 registry 应答：{message}',
+    'update.errorFailed': '更新失败，可手动执行：npm install -g herdr-remote@{version} --prefer-online',
+    'update.errorFailedDetail': 'npm：{message}',
+    'update.errorNotYetPublished': 'npm 还没同步到 {version}（刚发布的几分钟内常见），稍后按 Enter 重试。',
+    'update.errorNotApplied': 'npm 报告成功，但安装的仍是 {installed}',
+    'update.mirrorBehind': '{registries} 仍是旧版本，将从 {source} 安装',
+    'update.cannot.source': '源码目录运行，请使用 git 更新',
+    'update.cannot.linked': 'npm link 工作副本，由 npm link 管理',
+};
+export default zh;

package/dist/keepalive/detached.js

@@ -0,0 +1,78 @@
+// The fallback where no service manager is usable: a detached copy of our own
+// supervisor, tracked by a pid file. It does not survive a reboot.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureDir, readJson, writeJsonAtomic } from 'herdr-remote-relay/state';
+import { pidAlive } from '../lib/process.js';
+import { logPath, PACKAGE_ROOT, stateDir } from '../paths.js';
+import { cliEntryPoint, serviceEnvironment } from './environment.js';
+function fallbackPidPath() {
+    return path.join(stateDir(), 'supervisor.pid');
+}
+function readPid() {
+    const record = readJson(fallbackPidPath(), {});
+    return Number.isInteger(record.pid) ? record.pid : null;
+}
+function start() {
+    const running = readPid();
+    if (pidAlive(running))
+        return { ok: true, alreadyRunning: true, pid: running };
+    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', ...serviceEnvironment() },
+            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 stopAndForget() {
+    const pid = readPid();
+    if (pid !== null && pidAlive(pid)) {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch {
+            // Exited between the check and the signal.
+        }
+    }
+    fs.rmSync(fallbackPidPath(), { force: true });
+    return { ok: true, stoppedPid: pid };
+}
+export const detached = {
+    name: 'supervisor',
+    status() {
+        const pid = readPid();
+        const alive = pidAlive(pid);
+        return {
+            manager: 'supervisor',
+            installed: alive,
+            active: alive,
+            enabled: false,
+            pid: alive ? pid : null,
+            unitPath: fallbackPidPath(),
+            state: alive ? 'running' : 'stopped',
+        };
+    },
+    install: start,
+    uninstall: stopAndForget,
+    restart() {
+        stopAndForget();
+        return start();
+    },
+    stop() {
+        stopAndForget();
+    },
+    logsHint() {
+        return `tail -f ${logPath('supervisor')}`;
+    },
+};

package/dist/keepalive/environment.js

@@ -0,0 +1,44 @@
+// What a supervised copy needs from the shell that installed it.
+import os from 'node:os';
+import path from 'node:path';
+import { findHerdrCommand } from '../herdr-command.js';
+import { PACKAGE_ROOT } from '../paths.js';
+export function cliEntryPoint() {
+    return path.join(PACKAGE_ROOT, 'bin', 'herdr-remote.js');
+}
+/**
+ * `PATH` for the unit: the one that is resolving commands right now, plus the
+ * directory Herdr was found in.
+ *
+ * A service manager does not inherit the shell's environment. `systemd --user`
+ * hands a unit something close to `/usr/local/bin:/usr/bin:/bin` and `launchd`
+ * is no more generous, so a copy that works from a terminal loses `~/.local/bin`
+ * — and with it `herdr` — the moment it is installed as a service. Freezing the
+ * installing shell's `PATH` into the unit keeps the supervised copy able to find
+ * Herdr, and Herdr able to find the tools it spawns in turn.
+ */
+export function servicePath({ env = process.env, herdrCommand = null, } = {}) {
+    const entries = String(env.PATH || '')
+        .split(path.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    // The override already pins the exact binary; this is only so the session
+    // itself can still reach it by name.
+    if (herdrCommand)
+        entries.push(path.dirname(herdrCommand));
+    return [...new Set(entries)].join(path.delimiter);
+}
+/**
+ * What has to be written into the unit file for a supervised start to behave
+ * like the one the user just ran by hand.
+ */
+export function serviceEnvironment({ env = process.env, home = os.homedir(), directories, } = {}) {
+    const environment = {};
+    const herdr = findHerdrCommand({ env, home, ...(directories ? { directories } : {}) });
+    if (herdr.found)
+        environment.HERDR_BIN_PATH = herdr.command;
+    const searchPath = servicePath({ env, herdrCommand: herdr.found ? herdr.command : null });
+    if (searchPath)
+        environment.PATH = searchPath;
+    return environment;
+}

package/dist/keepalive/index.js

@@ -0,0 +1,110 @@
+// 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.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadConfig } from '../config.js';
+import { detached } from './detached.js';
+import { launchd } from './launchd.js';
+import { systemd } from './systemd.js';
+export { serviceEnvironment, servicePath } from './environment.js';
+export { escapeXml, renderLaunchdPlist } from './launchd.js';
+export { renderSystemdUnit, systemdEnvironmentLine } from './systemd.js';
+/**
+ * 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) {
+    return (process.env.PATH || '')
+        .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. */
+export 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';
+}
+function managerOf(config) {
+    return detectManager(config.keepalive?.manager || 'auto');
+}
+/** The backend for `config`. With keep-alive off, uninstalling still cleans up the fallback. */
+function backendOf(config) {
+    const manager = managerOf(config);
+    if (manager === 'systemd')
+        return systemd;
+    if (manager === 'launchd')
+        return launchd;
+    return detached;
+}
+export function status(config = loadConfig()) {
+    if (managerOf(config) === 'none')
+        return { manager: 'none', installed: false, active: false, enabled: false };
+    return backendOf(config).status();
+}
+export function install(config = loadConfig()) {
+    if (managerOf(config) === 'none')
+        throw new Error('keep-alive is disabled in the configuration');
+    const backend = backendOf(config);
+    return { manager: backend.name, ...backend.install() };
+}
+export function uninstall(config = loadConfig()) {
+    const backend = backendOf(config);
+    return { manager: backend.name, ...backend.uninstall() };
+}
+/** Restart whatever manages the services, so config edits take effect. */
+export function restart(config = loadConfig()) {
+    const backend = backendOf(config);
+    return { manager: backend.name, ...backend.restart() };
+}
+/**
+ * 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.
+ */
+export function stopManaged(config = loadConfig()) {
+    const current = status(config);
+    if (current.manager === 'none' || (!current.installed && !current.active))
+        return { managed: false };
+    backendOf(config).stop();
+    return { managed: true, manager: current.manager };
+}
+export 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 };
+}
+export function logsHint(config = loadConfig()) {
+    return backendOf(config).logsHint();
+}

package/dist/keepalive/launchd.js

@@ -0,0 +1,117 @@
+// launchd: a LaunchAgent that runs `herdr-remote run` and keeps it alive.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ensureDir } from 'herdr-remote-relay/state';
+import { logPath, stateDir } from '../paths.js';
+import { cliEntryPoint, serviceEnvironment } from './environment.js';
+const LAUNCHD_LABEL = 'dev.herdr.remote';
+function launchdPlistPath() {
+    return path.join(os.homedir(), 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+}
+export function escapeXml(value) {
+    return String(value)
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+export 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>
+`;
+}
+function domainTarget() {
+    return `gui/${process.getuid ? process.getuid() : ''}`;
+}
+function serviceTarget() {
+    return `${domainTarget()}/${LAUNCHD_LABEL}`;
+}
+function launchctl(args) {
+    return spawnSync('launchctl', args, { encoding: 'utf8' });
+}
+/** A launchctl call whose outcome does not matter (bootout of nothing, say). */
+function launchctlQuietly(args) {
+    spawnSync('launchctl', args, { stdio: 'ignore' });
+}
+export const launchd = {
+    name: 'launchd',
+    status() {
+        const plistPath = launchdPlistPath();
+        if (!fs.existsSync(plistPath))
+            return { manager: 'launchd', installed: false, active: false, enabled: false };
+        const result = launchctl(['print', serviceTarget()]);
+        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',
+        };
+    },
+    install() {
+        const plistPath = launchdPlistPath();
+        ensureDir(path.dirname(plistPath));
+        ensureDir(stateDir());
+        fs.writeFileSync(plistPath, renderLaunchdPlist({ environment: serviceEnvironment() }), {
+            mode: 0o644,
+        });
+        // bootout first so a re-install picks up the rewritten plist.
+        launchctlQuietly(['bootout', serviceTarget()]);
+        const result = launchctl(['bootstrap', domainTarget(), plistPath]);
+        if (result.status !== 0) {
+            throw new Error(`launchctl bootstrap failed: ${String(result.stderr || '').trim()}`);
+        }
+        launchctlQuietly(['enable', serviceTarget()]);
+        return { ok: true, unitPath: plistPath };
+    },
+    uninstall() {
+        const plistPath = launchdPlistPath();
+        launchctlQuietly(['bootout', serviceTarget()]);
+        fs.rmSync(plistPath, { force: true });
+        return { ok: true, unitPath: plistPath };
+    },
+    restart() {
+        launchctlQuietly(['kickstart', '-k', serviceTarget()]);
+        return { ok: true };
+    },
+    stop() {
+        launchctlQuietly(['bootout', serviceTarget()]);
+    },
+    // The plist sends the supervisor's output to its log file.
+    logsHint() {
+        return `tail -f ${logPath('supervisor')}`;
+    },
+};