herdr-remote 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dibin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# herdr-remote
+
+Use your [Herdr](https://herdr.dev) terminal workspaces from a phone or any
+browser. A mobile-first web terminal with low-latency ANSI streaming, one-time
+pairing codes, and a bilingual configuration TUI.
+
+```bash
+npm install -g herdr-remote
+herdr-remote
+```
+
+That opens the setup wizard: pick a language, pick how you want to reach the
+machine, and it starts the services for you.
+
+## Two packages
+
+| Package | Runs on | Contains |
+|---|---|---|
+| **`herdr-remote`** | your workstation | Herdr plugin, host connector, configuration TUI |
+| **`herdr-remote-relay`** | wherever you want | the relay and the web terminal |
+
+The relay is completely separate: its only dependency is `ws`, so a server
+running one needs no compiler, no Herdr and no plugin. You do not have to
+install it yourself — `herdr-remote` starts one locally unless you point it at
+your own.
+
+## Three ways to connect
+
+| Mode | Who can reach it | Needs a server? |
+|---|---|---|
+| **This machine only** *(default)* | a browser on the workstation | no |
+| **Local network / Tailscale** | phones on your LAN or tailnet | no |
+| **Self-hosted relay** | anywhere, over the internet | yes — see [`herdr-remote-relay`](https://www.npmjs.com/package/herdr-remote-relay) |
+
+Without a relay configured, the web UI is served from a local address only.
+This already covers being away from home if you run Tailscale or WireGuard.
+Only a self-hosted relay opens access from outside your network.
+
+## The TUI
+
+`herdr-remote` with no arguments opens the interface. It is bilingual —
+Chinese or English, following `$LANG` unless you choose otherwise — and works
+with the keyboard or the mouse.
+
+```
+ Herdr Remote  Remote browser access to your Herdr workspaces
+
+ 1 Overview  2 Pair a device  3 Services  4 Relay  5 Keep-alive  6 Herdr  7 Language & about
+ ╭──────────────────────────────────────────────────────────────────────╮
+ │ Status                                                               │
+ │                                                                      │
+ │ Access mode         This machine only                                │
+ │ Relay               ● local, 127.0.0.1:8787  pid 1239815             │
+ │ Host connector      ● running  pid 1239816                           │
+ │ Herdr socket        ● /home/you/.config/herdr/herdr.sock             │
+ │ Web UI              http://127.0.0.1:8787                            │
+ │ Keep-alive          ● systemd — running                              │
+ │                                                                      │
+ │ Workstations        1                                                │
+ │ Browsers            0                                                │
+ │ Relay uptime        4m 2s                                            │
+ ╰──────────────────────────────────────────────────────────────────────╯
+  ↑↓ move  ·  ↵ select  ·  ← → switch tab  ·  m mouse off  ·  q quit
+```
+
+| Tab | |
+|---|---|
+| **Overview** | live service, socket and keep-alive status |
+| **Pair a device** | one-time code with a QR you can scan |
+| **Services** | start, stop, restart, recent logs |
+| **Relay** | access mode, port, listen address, browser access address, relay URL and password |
+| **Keep-alive** | install or remove the background service |
+| **Herdr** | socket path, arguments, plugin registration |
+| **Language & about** | Chinese / English / follow the system |
+
+Keys: `↑↓` move · `↵` select or edit · `←→` or `1`–`7` switch tab · `s` save ·
+`r` refresh · `m` toggle mouse · `q` quit.
+
+Mouse tracking turns itself on where the terminal supports it. It takes over
+text selection while active, so press `m` when you want to copy something.
+
+## Pairing
+
+Open **Pair a device** and press Enter. Scan the QR code, or enter the six
+characters on the page. The browser gets a long-lived token; the code is burned
+on first use and expires after ten minutes.
+
+## Keeping it running
+
+The **Keep-alive** tab installs a service that starts the relay and host
+connector at login and restarts them if they die — a systemd user unit on
+Linux, a LaunchAgent on macOS, and a supervised background process where
+neither is available.
+
+On Linux, "Enable start at boot" runs `loginctl enable-linger` so it also comes
+up before you log in.
+
+## Command line
+
+Everything the TUI does is scriptable:
+
+```bash
+herdr-remote start | stop | restart
+herdr-remote status [--json]
+herdr-remote pair [--json]
+herdr-remote url
+herdr-remote keepalive install | uninstall | restart | status
+herdr-remote plugin link | unlink | status
+herdr-remote --lang zh|en
+```
+
+## Herdr plugin
+
+The package is also a Herdr plugin. Register it from the **Herdr** tab, or:
+
+```bash
+herdr-remote plugin link
+```
+
+Nothing is compiled at registration time — the npm package ships prebuilt.
+
+> Upgrading from a source checkout? Unlink the old one first:
+> `herdr plugin unlink herdr.remote.web`. Your settings are migrated
+> automatically on first run.
+
+## Configuration
+
+`~/.config/herdr-remote/config.json`, edited through the TUI:
+
+```json
+{
+  "ui":        { "language": "auto" },
+  "relay":     { "mode": "local", "port": 8787, "lanHost": "", "publicUrl": "", "remoteUrl": "" },
+  "herdr":     { "socketPath": null, "args": [] },
+  "keepalive": { "manager": "auto" }
+}
+```
+
+Secrets are never stored here. The workstation's host token and the relay
+password live in `~/.local/state/herdr-remote/runtime.json`, mode 0600.
+
+## Security
+
+- The relay never runs a shell and never sees your Herdr socket; only the host
+  connector on your machine does.
+- Tokens are stored as SHA-256 hashes. Terminal content is never written to disk.
+- Pairing codes are single-use, expire in ten minutes, and are rate limited.
+- Secrets never appear in URLs or shell history; the web UI strips them from the
+  address bar after pairing.
+- One writable controller at a time, with explicit takeover; other devices watch
+  read-only.
+
+## License
+
+MIT

package/bin/herdr-remote.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+'use strict';
+
+// herdr-remote command line entry point.
+//
+// With no arguments (and a real terminal) this opens the configuration TUI;
+// the subcommands exist for scripting and for the actions declared in
+// herdr-plugin.toml, which Herdr runs without a terminal attached.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+
+const {
+  LANGUAGES,
+  configPath,
+  loadConfig,
+  migrateLegacyConfig,
+  resolvePublicUrl,
+  stateDir,
+} = require('../src/config');
+const { createTranslator, detectLocale } = require('../src/i18n');
+const { preferredLanAddress } = require('../src/net-interfaces');
+
+const VERSION = require('../package.json').version;
+
+const USAGE = `herdr-remote ${VERSION} — remote browser access to your Herdr workspaces
+
+Usage: herdr-remote [command] [options]
+
+Commands:
+  (none)               Open the configuration TUI
+  start                Start the relay and host connector
+  stop                 Stop them
+  restart              Restart them
+  status [--json]      Show service status
+  pair [--json]        Create a one-time pairing code
+  url                  Print the URL to open in a browser
+  run [--daemon]       Run the services in the foreground (used by keep-alive)
+  keepalive <action>   install | uninstall | restart | status
+  plugin <action>      link | unlink | status  (Herdr plugin registration)
+
+Options:
+  --lang <zh|en>       Force the interface language
+  --json               Machine readable output where supported
+  -h, --help           Show this help
+  -v, --version        Show the version
+
+Self-hosting a relay: docs/self-hosted-relay.md
+`;
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--json') { flags.json = true; continue; }
+    if (arg === '--daemon') { flags.daemon = true; continue; }
+    if (arg === '--help' || arg === '-h') { flags.help = true; continue; }
+    if (arg === '--version' || arg === '-v') { flags.version = true; continue; }
+    if (arg === '--lang') { flags.lang = argv[index + 1]; index += 1; continue; }
+    if (arg.startsWith('--lang=')) { flags.lang = arg.slice('--lang='.length); continue; }
+    if (arg.startsWith('-')) { flags.unknown = arg; continue; }
+    positional.push(arg);
+  }
+  return { positional, flags };
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function describeStatus(status, t) {
+  const lines = [];
+  lines.push(`${t('overview.mode')}: ${t(`mode.${status.mode}`)}`);
+  if (status.relay.local) {
+    lines.push(`${t('overview.relay')}: ${status.relay.alive ? t('common.running') : t('common.stopped')} (${status.relay.bind}:${status.relay.port})`);
+  } else {
+    lines.push(`${t('overview.relay')}: ${status.relay.remoteUrl}`);
+  }
+  lines.push(`${t('overview.host')}: ${status.host.alive ? t('common.running') : t('common.stopped')}`);
+  lines.push(`${t('overview.socket')}: ${status.host.socketPath}${status.host.socketExists ? '' : ` (${t('overview.socketMissing')})`}`);
+  lines.push(`${t('overview.webUrl')}: ${status.publicUrl}`);
+  if (status.keepalive) {
+    const state = status.keepalive.active ? t('common.running') : status.keepalive.installed ? t('common.installed') : t('common.notInstalled');
+    lines.push(`${t('overview.keepalive')}: ${status.keepalive.manager} — ${state}`);
+  }
+  if (status.relay.health && status.relay.health.ok === false) {
+    lines.push(`${t('overview.relay')}: ${t('overview.unreachable', { message: status.relay.health.message })}`);
+  }
+  return lines.join('\n');
+}
+
+async function runTui(options) {
+  // The TUI is an ESM bundle; import() keeps this entry point loadable on any
+  // Node 22 without relying on require(esm).
+  const bundle = path.join(__dirname, '..', 'dist', 'tui.mjs');
+  if (!fs.existsSync(bundle)) {
+    process.stderr.write(
+      'herdr-remote: the TUI bundle is missing.\n'
+      + 'If you are running from a source checkout, build it first:\n'
+      + '  npm run build -w herdr-remote\n',
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const module = await import(pathToFileURL(bundle).href);
+  await module.startTui(options);
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const { positional, flags } = parseArgs(argv);
+  const command = positional[0] || null;
+
+  migrateLegacyConfig();
+
+  // Ask the terminal for its colors while it is still a plain terminal: the
+  // TUI takes the screen a few lines below, and the services this command
+  // starts usually run detached with nothing to ask. Everything downstream
+  // inherits the answer through the environment.
+  require('../src/terminal-palette').captureTerminalPalette();
+
+  const config = loadConfig();
+  const preference = flags.lang && LANGUAGES.includes(flags.lang) ? flags.lang : config.ui.language;
+  const t = createTranslator(detectLocale({ preference }));
+
+  if (flags.help) { process.stdout.write(USAGE); return; }
+  if (flags.version) { process.stdout.write(`${VERSION}\n`); return; }
+
+  // Lazily required so that `--help` and the TUI do not pay for loading the
+  // service layer (which pulls in the relay package and node-pty).
+  const lifecycle = require('../src/lifecycle');
+  const service = require('../src/service');
+
+  switch (command) {
+    case null: {
+      if (process.stdin.isTTY && process.stdout.isTTY) {
+        await runTui({ language: flags.lang || null });
+        return;
+      }
+      // Herdr runs plugin panes and actions without a TTY; emit status instead
+      // of trying to paint an interface into a pipe.
+      printJson(await lifecycle.fullStatus(config));
+      return;
+    }
+    case 'start': {
+      const result = lifecycle.startAll(config);
+      if (flags.json) printJson(result);
+      else process.stdout.write(`${t('services.started')}\n${describeStatus(await lifecycle.fullStatus(config), t)}\n`);
+      return;
+    }
+    case 'stop': {
+      const result = lifecycle.stopAll(config);
+      if (flags.json) printJson(result);
+      else process.stdout.write(`${t('services.stopped')}\n`);
+      return;
+    }
+    case 'restart': {
+      const result = lifecycle.restartAll(config);
+      if (flags.json) printJson(result);
+      else process.stdout.write(`${t('services.restarted')}\n`);
+      return;
+    }
+    case 'status': {
+      const status = await lifecycle.fullStatus(config);
+      if (flags.json) printJson(status);
+      else process.stdout.write(`${describeStatus(status, t)}\n`);
+      return;
+    }
+    case 'pair': {
+      const pairing = await service.pair();
+      if (flags.json) { printJson(pairing); return; }
+      const code = service.extractPairingCode(pairing);
+      const url = pairing.pairUrl || `${resolvePublicUrl(config, preferredLanAddress())}/?pairCode=${encodeURIComponent(code)}`;
+      const minutes = `${Math.round((config.auth.pairingTtlMs || 600000) / 60000)}m`;
+      process.stdout.write(`${t('pair.code')}: ${code}\n${t('pair.url')}: ${url}\n${t('pair.expires', { minutes, time: new Date(pairing.expiresAt).toLocaleTimeString() })}\n`);
+      return;
+    }
+    case 'url': {
+      process.stdout.write(`${resolvePublicUrl(config, preferredLanAddress())}\n`);
+      return;
+    }
+    case 'run': {
+      const { runForeground } = require('../src/supervisor');
+      await runForeground({ logToFiles: Boolean(flags.daemon) });
+      return;
+    }
+    case 'keepalive': {
+      const keepalive = require('../src/keepalive');
+      const action = positional[1] || 'status';
+      if (action === 'install') printJson(keepalive.install(config));
+      else if (action === 'uninstall') printJson(keepalive.uninstall(config));
+      else if (action === 'restart') printJson(keepalive.restart(config));
+      else if (action === 'status') printJson(keepalive.status(config));
+      else throw new Error(`unknown keepalive action: ${action}`);
+      return;
+    }
+    case 'plugin': {
+      const plugin = require('../src/herdr-plugin');
+      const action = positional[1] || 'status';
+      if (action === 'link') printJson(plugin.register());
+      else if (action === 'unlink') printJson(plugin.unregister());
+      else if (action === 'status') printJson(plugin.registrationStatus());
+      else throw new Error(`unknown plugin action: ${action}`);
+      return;
+    }
+    case 'config': {
+      // Handy when reporting a problem: where does this install read from?
+      printJson({ configPath: configPath(), stateDir: stateDir(), config });
+      return;
+    }
+    default:
+      process.stderr.write(`herdr-remote: unknown command "${command}"\n\n${USAGE}`);
+      process.exitCode = 2;
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    process.stderr.write(`herdr-remote: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { main, parseArgs, describeStatus, USAGE, VERSION };

package/config.example.json

@@ -0,0 +1,19 @@
+{
+  "ui": {
+    "language": "auto"
+  },
+  "relay": {
+    "mode": "local",
+    "port": 8787,
+    "lanHost": "",
+    "publicUrl": "",
+    "remoteUrl": ""
+  },
+  "herdr": {
+    "socketPath": null,
+    "args": []
+  },
+  "keepalive": {
+    "manager": "auto"
+  }
+}