herdr-remote 0.2.18 → 0.2.20

package/dist/herdr-server.js

@@ -0,0 +1,189 @@
+// Whether Herdr's server is running on this workstation, and starting it when
+// the user asked for that.
+//
+// herdr-remote never starts Herdr on its own initiative. It starts one when a
+// browser paired to this workstation asks for it, or at service start when the
+// user switched that on — and both go through here.
+//
+// Two traps shape this file:
+//
+// - A socket file is not a server. Herdr leaves `herdr.sock` behind when it dies
+//   without cleaning up (a crash, a power cut), and a `herdr` client pointed at
+//   a dead socket quietly starts a server of its own. So "running" means a
+//   connection was accepted, not that the path exists.
+// - A server started from inside herdr-remote's systemd service lives in that
+//   service's cgroup, and `systemctl restart herdr-remote` — an update, a keep-
+//   alive restart, Herdr's own plugin startup hook — would kill it along with
+//   every agent in it. Under a service it is therefore started in a transient
+//   scope of its own, the same place it would live had the user started it
+//   from a terminal.
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { inspectSocket } from './socket-discovery.js';
+import { ensureDir } from 'herdr-remote-relay/state';
+/** A Unix socket either accepts at once or is dead; this only guards a hang. */
+const PROBE_TIMEOUT_MS = 1_000;
+/** Herdr restores the saved session before its API socket opens. */
+const START_TIMEOUT_MS = 20_000;
+const START_POLL_MS = 200;
+/**
+ * Is Herdr's server answering on `socketPath`?
+ *
+ * Resolves `{ state }`: `running`, `stopped` (no socket, or a socket nothing is
+ * listening on), or `unavailable` with a `reason` — a path that is not a socket
+ * or belongs to another user. That last one is never "stopped": the socket may
+ * well be live, just not ours to use, and starting a second server beside it
+ * would be starting somebody else's Herdr.
+ */
+function probeHerdrServer(socketPath, { connect = net.connect, timeout = PROBE_TIMEOUT_MS } = {}) {
+    const info = inspectSocket(socketPath);
+    if (!info.ok) {
+        return Promise.resolve(info.missing ? { state: 'stopped' } : { state: 'unavailable', reason: info.reason });
+    }
+    return new Promise((resolve) => {
+        let socket;
+        const finish = (result) => {
+            clearTimeout(timer);
+            if (socket) {
+                socket.removeAllListeners();
+                socket.on('error', () => { });
+                socket.destroy();
+            }
+            resolve(result);
+        };
+        // A socket that neither accepts nor refuses has a listener behind it that
+        // is slow, not absent; starting another server would only fight it.
+        const timer = setTimeout(() => finish({ state: 'running' }), timeout);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        socket = connect(socketPath);
+        socket.once('connect', () => finish({ state: 'running' }));
+        socket.once('error', (error) => finish(error.code === 'ECONNREFUSED' || error.code === 'ENOENT'
+            ? { state: 'stopped', stale: true }
+            : { state: 'unavailable', reason: error.message }));
+    });
+}
+/**
+ * True when this process is a systemd service (herdr-remote's keep-alive), so
+ * anything it starts would be killed with it.
+ */
+function runningInSystemdService({ platform = process.platform, readCgroup = () => fs.readFileSync('/proc/self/cgroup', 'utf8'), } = {}) {
+    if (platform !== 'linux')
+        return false;
+    try {
+        const unified = readCgroup()
+            .split('\n')
+            .find((line) => line.startsWith('0::'));
+        return unified !== undefined && /\.service$/.test(unified.trim());
+    }
+    catch {
+        return false;
+    }
+}
+/** The server's environment: the one a Herdr pane would give its client. */
+function serverEnv(socketPath, env = process.env) {
+    const next = { ...env };
+    for (const key of Object.keys(next)) {
+        if (key.startsWith('HERDR_'))
+            delete next[key];
+    }
+    if (socketPath)
+        next.HERDR_SOCKET_PATH = socketPath;
+    return next;
+}
+/**
+ * The argv that starts Herdr's server: Herdr's own global arguments (a
+ * `--session`, say) followed by `server`, wrapped in `systemd-run --scope` when
+ * the caller is a systemd service.
+ */
+function serverCommand({ command, args = [], inService = runningInSystemdService(), }) {
+    const herdr = [command, ...args, 'server'];
+    if (!inService)
+        return { file: herdr[0], args: herdr.slice(1) };
+    return {
+        file: 'systemd-run',
+        args: [
+            '--user',
+            '--scope',
+            '--quiet',
+            '--collect',
+            '--description=Herdr server started by herdr-remote',
+            '--',
+            ...herdr,
+        ],
+    };
+}
+/**
+ * Start Herdr's server in the background. Detached from this process, with its
+ * output appended to `logPath` rather than piped here: a pipe would break the
+ * moment herdr-remote exits and take the server with it.
+ */
+function launchHerdrServer({ command, args = [], socketPath, cwd, logPath, spawnProcess = spawn, inService, }) {
+    const { file, args: argv } = serverCommand({ command, args, inService });
+    ensureDir(path.dirname(logPath));
+    const out = fs.openSync(logPath, 'a');
+    let child;
+    try {
+        child = spawnProcess(file, argv, {
+            cwd,
+            env: serverEnv(socketPath),
+            detached: true,
+            stdio: ['ignore', out, out],
+        });
+    }
+    finally {
+        fs.closeSync(out);
+    }
+    child.on('error', () => { });
+    child.unref();
+    return child;
+}
+function readLogTail(logPath, bytes = 2_000) {
+    try {
+        const text = fs.readFileSync(logPath, 'utf8');
+        return text.slice(-bytes).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Make sure Herdr's server is running, starting it if it is not.
+ *
+ * Resolves `{ started }`, or rejects with a message that says what happened:
+ * the socket belongs to someone else, the server exited, or it never opened
+ * its socket. The last lines Herdr printed ride along, because "did not start"
+ * with no reason is a message nobody can act on.
+ */
+async function ensureHerdrServer({ command, args = [], socketPath, cwd, logPath, probe = probeHerdrServer, launch = launchHerdrServer, timeout = START_TIMEOUT_MS, interval = START_POLL_MS, }) {
+    const before = await probe(socketPath);
+    if (before.state === 'running')
+        return { started: false };
+    if (before.state === 'unavailable') {
+        throw new Error(`Herdr socket at ${socketPath} cannot be used: ${before.reason}`);
+    }
+    const child = launch({ command, args, socketPath, cwd, logPath });
+    // Assigned by the listener; `as` keeps TypeScript from assuming it stays null.
+    let exit = null;
+    child.once('exit', (code, signal) => {
+        exit = { code, signal };
+    });
+    const deadline = Date.now() + timeout;
+    for (;;) {
+        await new Promise((resolve) => setTimeout(resolve, interval));
+        const now = await probe(socketPath);
+        if (now.state === 'running')
+            return { started: true };
+        const tail = readLogTail(logPath);
+        const detail = tail ? `\n${tail}` : '';
+        if (exit) {
+            throw new Error(`Herdr server exited (${exit.signal || `code ${exit.code}`}) before opening ${socketPath}.${detail}`);
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Herdr server did not open ${socketPath} within ${Math.round(timeout / 1000)}s.${detail}`);
+        }
+    }
+}
+export { probeHerdrServer, runningInSystemdService, serverEnv, serverCommand, ensureHerdrServer };

package/dist/i18n/en.js

@@ -0,0 +1,223 @@
+// English message catalogue. This file is the reference: zh.ts must define
+// exactly the same keys, which its type and tests/i18n.test.js enforce.
+const en = {
+    'app.name': 'Herdr Remote',
+    'app.tagline': 'Remote browser access to Herdr workspaces',
+    'common.yes': 'Yes',
+    'common.no': 'No',
+    'common.on': 'on',
+    'common.off': 'off',
+    'common.none': 'none',
+    'common.auto': 'auto',
+    'common.unknown': 'unknown',
+    'common.running': 'running',
+    'common.stopped': 'stopped',
+    'common.connected': 'connected',
+    'common.disconnected': 'disconnected',
+    'common.installed': 'installed',
+    'common.notInstalled': 'not installed',
+    'common.enabled': 'enabled',
+    'common.disabled': 'disabled',
+    'common.loading': 'Working…',
+    'common.save': 'Save settings',
+    'common.saved': 'Configuration saved to {path}',
+    'common.back': 'Back',
+    'common.cancel': 'Cancel',
+    'common.confirm': 'Confirm',
+    'common.pid': 'pid {pid}',
+    'common.notApplicable': 'n/a',
+    'nav.overview': 'Overview',
+    'nav.pair': 'Pair a device',
+    'nav.services': 'Services',
+    'nav.relay': 'Relay',
+    'nav.keepalive': 'Keep-alive',
+    'nav.herdr': 'Herdr',
+    'nav.about': 'Language & about',
+    'mode.local': 'This machine only',
+    'mode.lan': 'Local network / Tailscale',
+    'mode.official': 'Official relay',
+    'mode.remote': 'Self-hosted relay',
+    'mode.local.description': 'Relay listens on 127.0.0.1. Local browser only.',
+    'mode.lan.description': 'Relay listens on 0.0.0.0. Accessible over LAN or Tailscale.',
+    'mode.official.description': 'Connect via official relay. No server needed.',
+    'mode.remote.description': 'Connect via self-hosted relay for external access.',
+    'overview.title': 'Status',
+    'overview.mode': 'Access mode',
+    'overview.relay': 'Relay',
+    'overview.host': 'Host connector',
+    'overview.socket': 'Herdr socket',
+    'overview.webUrl': 'Web UI',
+    'overview.keepalive': 'Keep-alive',
+    'overview.devices': 'Browsers',
+    'overview.hosts': 'Workstations',
+    'overview.uptime': 'Relay uptime',
+    'overview.relayLocal': 'local, {bind}:{port}',
+    'overview.relayRemote': 'remote, {url}',
+    'overview.socketMissing': 'not found — is Herdr running?',
+    'overview.unreachable': 'unreachable: {message}',
+    'overview.notStarted': 'Services not running. Open Services tab to start.',
+    'pair.title': 'Pair a device',
+    'pair.generate': 'Generate pairing code',
+    'pair.regenerate': 'Regenerate code',
+    'pair.working': 'Generating pairing code…',
+    'pair.code': 'Pairing code',
+    'pair.url': 'Access URL',
+    'pair.expires': 'Expires in {minutes} (at {time})',
+    'pair.expired': 'Code expired. Generate a new one.',
+    'pair.instructions': 'Open URL and enter code to pair.',
+    'pair.qrHint': 'Scan QR code to open URL.',
+    'pair.qrUnavailable': 'Terminal too narrow for QR code; use URL above.',
+    'pair.failed': 'Could not create pairing code: {message}',
+    'pair.hostOffline': 'Relay has no workstation connected. Start services first.',
+    'services.title': 'Services',
+    'services.start': 'Start services',
+    'services.stop': 'Stop services',
+    'services.restart': 'Restart services',
+    'services.started': 'Services started.',
+    'services.stopped': 'Services stopped.',
+    'services.restarted': 'Services restarted.',
+    'services.startFailed': 'Could not start services: {message}',
+    'services.stopFailed': 'Could not stop services: {message}',
+    'services.unsavedBlocked': 'Unsaved changes. Save before restarting.',
+    'services.managedNotice': 'Managed by {manager}; applied via keep-alive service.',
+    'services.logs': 'Recent logs',
+    'services.logEmpty': 'No logs.',
+    'services.logRelay': 'Relay',
+    'services.logHost': 'Host connector',
+    'relay.title': 'Relay settings',
+    'relay.settings': 'Settings',
+    'relay.locked': 'fixed',
+    'relay.officialFixed': 'The official relay address is fixed and cannot be edited.',
+    'relay.officialHint': 'Official relay: address is fixed and no password is needed.',
+    'relay.password': 'Relay password',
+    'relay.passwordHint': 'Must match RELAY_PASSWORD on relay. Leave empty if public.',
+    'relay.passwordSet': 'set',
+    'relay.passwordEmpty': 'not set (public)',
+    'relay.passwordSaved': 'Relay password saved. Restart services to apply.',
+    'relay.showPassword': 'Show password',
+    'relay.hidePassword': 'Hide password',
+    'relay.identity': 'Workstation ID',
+    'relay.regenerate': 'Generate new ID',
+    'relay.regenerated': 'New workstation identity generated. Restart services to re-register.',
+    'relay.envSnippet': 'Relay startup command',
+    'relay.envHint': 'Run this command on the relay host.',
+    'relay.test': 'Test relay connection',
+    'relay.testOk': 'Relay reachable: version {version}, {hosts} workstation(s) connected.',
+    'relay.testFailed': 'Relay unreachable: {message}',
+    'relay.selectAddress': 'Choose advertised address',
+    'relay.listenAddress': 'Listen address',
+    'relay.listenAddressHint': 'Server bind address. Browsers use advertised address below.',
+    'relay.addressTailscale': 'Tailscale',
+    'relay.addressLan': 'LAN',
+    'relay.addressVirtual': 'virtual',
+    'relay.addressLoopback': 'loopback',
+    'relay.noAddresses': 'No non-loopback addresses found.',
+    'relay.docsHint': 'Self-hosting guide: docs/self-hosted-relay.md',
+    'keepalive.title': 'Keep-alive service',
+    'keepalive.manager': 'Manager',
+    'keepalive.state': 'State',
+    'keepalive.install': 'Install and start',
+    'keepalive.uninstall': 'Stop and remove',
+    'keepalive.restart': 'Restart service',
+    'keepalive.installed': 'Keep-alive installed with {manager}.',
+    'keepalive.uninstalled': 'Keep-alive removed.',
+    'keepalive.restarted': 'Keep-alive service restarted.',
+    'keepalive.failed': 'Keep-alive operation failed: {message}',
+    'keepalive.unitPath': 'Unit file',
+    'keepalive.logsHint': 'View logs: {command}',
+    'keepalive.linger': 'Start at boot',
+    'keepalive.lingerEnabled': 'Start at boot enabled.',
+    'keepalive.lingerDisabled': 'Start at boot disabled (runs while logged in).',
+    'keepalive.enableLinger': 'Enable start at boot',
+    'keepalive.lingerDone': 'Start at boot enabled for {username}.',
+    'keepalive.fallbackNote': 'No system service manager found; background process will not survive reboot.',
+    'herdr.title': 'Herdr integration',
+    'herdr.socketPath': 'Socket path',
+    'herdr.args': 'Extra arguments',
+    'herdr.autoStartHint': 'Off: Herdr starts only when you run it, or when you confirm it from a browser. On: herdr-remote also starts it every time it starts, at boot included. Takes effect the next time herdr-remote starts.',
+    'herdr.cliMissing': 'Command herdr not found. Set HERDR_BIN_PATH to its full path.',
+    'herdr.version': 'Herdr version',
+    'herdr.versionOutdated': 'Herdr {version} is older than {minimum}. Run "herdr update": window titles, background machine activation and large pastes misbehave in browser windows before that release.',
+    'about.title': 'Language & about',
+    'about.language': 'Interface language',
+    'about.languageAuto': 'Follow system ({detected})',
+    'about.languageZh': '中文',
+    'about.languageEn': 'English',
+    'about.version': 'Version',
+    'about.configPath': 'Config file',
+    'about.statePath': 'State directory',
+    'about.relayPackage': 'Relay package',
+    'about.docs': 'Self-hosting guide: docs/self-hosted-relay.md',
+    'wizard.title': 'First-time setup',
+    'wizard.step': 'Step {current} of {total}',
+    'wizard.languageTitle': 'Choose language',
+    'wizard.accessTitle': 'Access mode',
+    'wizard.accessHint': 'Can be changed later in Relay settings.',
+    'wizard.addressTitle': 'Browser access address',
+    'wizard.relayTitle': 'Relay server',
+    'wizard.relayUrlLabel': 'Relay URL (wss://…)',
+    'wizard.relayHint': 'Relay must be running. See docs/self-hosted-relay.md.',
+    'wizard.passwordTitle': 'Relay password',
+    'wizard.passwordHint': 'RELAY_PASSWORD of the relay. Leave empty if unset.',
+    'wizard.finishTitle': 'Finish',
+    'wizard.finishHint': 'Configuration will be saved to {path}.',
+    'wizard.startNow': 'Start services now',
+    'wizard.installKeepalive': 'Run in background',
+    'wizard.finish': 'Save and finish',
+    'field.mode': 'Access mode',
+    'field.port': 'Relay port',
+    'field.lanHost': 'Browser address',
+    'field.remoteUrl': 'Relay URL',
+    'field.publicUrl': 'Browser URL override',
+    'field.socketPath': 'Herdr socket path',
+    'field.herdrArgs': 'Herdr arguments',
+    'field.herdrAutoStart': 'Auto-start Herdr',
+    'field.language': 'Language',
+    'field.keepalive': 'Keep-alive manager',
+    'placeholder.autoDiscovered': 'auto-discovered',
+    'placeholder.none': 'none',
+    'error.invalidMode': 'Unknown access mode.',
+    'error.invalidPort': 'Port must be a number between 1 and 65535.',
+    'error.invalidLanHost': 'Browser address must be a reachable LAN or Tailscale address, not loopback or 0.0.0.0.',
+    'error.invalidRelayUrl': 'Relay URL must start with wss://, ws://, https:// or http://.',
+    'error.invalidPublicUrl': 'Browser URL must start with https:// or http:// and cannot use 0.0.0.0 or ::.',
+    'error.invalidLanguage': 'Unknown language.',
+    'error.invalidKeepalive': 'Unknown keep-alive manager.',
+    'error.unknownField': 'Unknown setting.',
+    'error.remoteUrlRequired': 'Relay URL is required for self-hosted relay mode.',
+    'error.removedHerdrArg': 'Herdr 0.9.0 removed --no-session; remove it from the extra arguments.',
+    'error.saveFailed': 'Could not save configuration: {message}',
+    'hint.navigate': '↑↓ move',
+    'hint.select': '↵ select',
+    'hint.edit': '↵ edit',
+    'hint.tabs': '← → switch tab',
+    'hint.back': 'esc back',
+    'hint.quit': 'q quit',
+    'hint.mouseOn': 'm mouse off',
+    'hint.mouseOff': 'm mouse on',
+    'hint.mouseUnsupported': 'mouse unsupported',
+    'hint.restartRequired': 'Restart services to apply changes.',
+    'hint.unsavedChanges': 'Unsaved changes (press s to save).',
+    'hint.save': 's save',
+    'hint.editing': '↵ confirm · esc cancel',
+    'update.title': 'Updates',
+    'update.banner': 'herdr-remote {latest} is out (running {current}). Press 7 and Enter on the update row to install.',
+    'update.check': 'Check for updates',
+    'update.checking': 'Checking npm…',
+    'update.upToDate': 'Up to date ({version})',
+    'update.available': 'Update {version} available (press Enter to install)',
+    'update.updating': 'Installing {version}…',
+    'update.updatingRetry': 'Installing {version}… (npm has not caught up yet, attempt {attempt})',
+    'update.done': 'Updated to {version}',
+    'update.restartHint': 'Update installed. Restart herdr-remote to apply.',
+    'update.errorNetwork': 'Could not reach any npm registry',
+    'update.errorNetworkDetail': 'No registry answered: {message}',
+    'update.errorFailed': 'Update failed. Run: npm install -g herdr-remote@{version} --prefer-online',
+    'update.errorFailedDetail': 'npm: {message}',
+    'update.errorNotYetPublished': 'npm has not caught up with {version} yet (common in the first minutes after a release). Press Enter to try again shortly.',
+    'update.errorNotApplied': 'npm reported success, but {installed} is still installed',
+    'update.mirrorBehind': '{registries} still has an older version; installing from {source}',
+    'update.cannot.source': 'Source checkout — update with git',
+    'update.cannot.linked': 'Linked package — managed by npm link',
+};
+export default en;

package/dist/i18n/index.js

@@ -0,0 +1,48 @@
+import en from './en.js';
+import zh from './zh.js';
+const CATALOGUES = { en, zh };
+const DEFAULT_LOCALE = 'en';
+function isLocale(value) {
+    return typeof value === 'string' && Object.hasOwn(CATALOGUES, value);
+}
+/**
+ * Work out the interface language from the environment.
+ *
+ * Order matters: an explicit override wins, then the saved preference, then the
+ * POSIX locale variables in the order the C library itself consults them.
+ */
+function detectLocale({ env = process.env, preference = 'auto', } = {}) {
+    if (preference && preference !== 'auto' && isLocale(preference))
+        return preference;
+    if (isLocale(env.HERDR_REMOTE_LANG))
+        return env.HERDR_REMOTE_LANG;
+    const raw = env.LC_ALL || env.LC_MESSAGES || env.LANG || env.LANGUAGE || '';
+    const primary = String(raw).split(/[:.@]/)[0].toLowerCase();
+    if (primary.startsWith('zh'))
+        return 'zh';
+    return DEFAULT_LOCALE;
+}
+function interpolate(template, values) {
+    if (!values)
+        return template;
+    return template.replace(/\{(\w+)\}/g, (match, key) => Object.hasOwn(values, key) ? String(values[key]) : match);
+}
+/**
+ * Build a translator for a locale.
+ *
+ * A missing key falls back to English and finally to the key itself, so a typo
+ * shows up as a visible key rather than an empty gap in the layout.
+ */
+function createTranslator(locale = DEFAULT_LOCALE) {
+    const active = isLocale(locale) ? CATALOGUES[locale] : CATALOGUES[DEFAULT_LOCALE];
+    const fallback = CATALOGUES[DEFAULT_LOCALE];
+    const t = (key, values) => {
+        const template = active[key] ?? fallback[key] ?? key;
+        return interpolate(template, values);
+    };
+    return Object.assign(t, {
+        locale,
+        has: (key) => Object.hasOwn(active, key),
+    });
+}
+export { CATALOGUES, detectLocale, createTranslator, interpolate };