herdr-remote 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +16 -121
  2. package/README.zh-CN.md +50 -0
  3. package/bin/herdr-remote.js +14 -15
  4. package/dist/tui.mjs +327 -199
  5. package/herdr-plugin.toml +7 -7
  6. package/package.json +4 -3
  7. package/src/i18n/en.js +76 -72
  8. package/src/i18n/zh.js +77 -73
  9. package/src/settings-model.js +44 -1
  10. package/src/updater.js +127 -23
package/README.md CHANGED
@@ -1,103 +1,26 @@
1
1
  # herdr-remote
2
2
 
3
- Use your [Herdr](https://herdr.dev) terminal workspaces from a phone or any
4
- browser. A mobile-first web terminal with low-latency ANSI streaming, one-time
5
- pairing codes, and a bilingual configuration TUI.
3
+ *[English](README.md) · [简体中文](README.zh-CN.md)*
4
+
5
+ Web terminal client for [Herdr](https://herdr.dev) workspaces. Mobile-friendly UI, low-latency ANSI streaming, and bilingual configuration TUI.
6
+
7
+ ## Installation & Usage
6
8
 
7
9
  ```bash
8
10
  npm install -g herdr-remote
9
11
  herdr-remote
10
12
  ```
11
13
 
12
- That opens the setup wizard: pick a language, pick how you want to reach the
13
- machine, and it starts the services for you.
14
-
15
- ## Two packages
16
-
17
- | Package | Runs on | Contains |
18
- |---|---|---|
19
- | **`herdr-remote`** | your workstation | Herdr plugin, host connector, configuration TUI |
20
- | **`herdr-remote-relay`** | wherever you want | the relay and the web terminal |
21
-
22
- The relay is completely separate: its only dependency is `ws`, so a server
23
- running one needs no compiler, no Herdr and no plugin. You do not have to
24
- install it yourself — `herdr-remote` starts one locally unless you point it at
25
- your own.
26
-
27
- ## Three ways to connect
28
-
29
- | Mode | Who can reach it | Needs a server? |
30
- |---|---|---|
31
- | **This machine only** *(default)* | a browser on the workstation | no |
32
- | **Local network / Tailscale** | phones on your LAN or tailnet | no |
33
- | **Self-hosted relay** | anywhere, over the internet | yes — see [`herdr-remote-relay`](https://www.npmjs.com/package/herdr-remote-relay) |
34
-
35
- Without a relay configured, the web UI is served from a local address only.
36
- This already covers being away from home if you run Tailscale or WireGuard.
37
- Only a self-hosted relay opens access from outside your network.
38
-
39
- ## The TUI
40
-
41
- `herdr-remote` with no arguments opens the interface. It is bilingual —
42
- Chinese or English, following `$LANG` unless you choose otherwise — and works
43
- with the keyboard or the mouse.
44
-
45
- ```
46
- Herdr Remote Remote browser access to your Herdr workspaces
47
-
48
- 1 Overview 2 Pair a device 3 Services 4 Relay 5 Keep-alive 6 Herdr 7 Language & about
49
- ╭──────────────────────────────────────────────────────────────────────╮
50
- │ Status │
51
- │ │
52
- │ Access mode This machine only │
53
- │ Relay ● local, 127.0.0.1:8787 pid 1239815 │
54
- │ Host connector ● running pid 1239816 │
55
- │ Herdr socket ● /home/you/.config/herdr/herdr.sock │
56
- │ Web UI http://127.0.0.1:8787 │
57
- │ Keep-alive ● systemd — running │
58
- │ │
59
- │ Workstations 1 │
60
- │ Browsers 0 │
61
- │ Relay uptime 4m 2s │
62
- ╰──────────────────────────────────────────────────────────────────────╯
63
- ↑↓ move · ↵ select · ← → switch tab · m mouse off · q quit
64
- ```
65
-
66
- | Tab | |
67
- |---|---|
68
- | **Overview** | live service, socket and keep-alive status |
69
- | **Pair a device** | one-time code with a QR you can scan |
70
- | **Services** | start, stop, restart, recent logs |
71
- | **Relay** | access mode, port, listen address, browser access address, relay URL and password |
72
- | **Keep-alive** | install or remove the background service |
73
- | **Herdr** | socket path, arguments, plugin registration |
74
- | **Language & about** | Chinese / English / follow the system |
14
+ Running `herdr-remote` without arguments launches the setup wizard and configuration TUI.
75
15
 
76
- Keys: `↑↓` move · `↵` select or edit · `←→` or `1`–`7` switch tab · `s` save ·
77
- `r` refresh · `m` toggle mouse · `q` quit.
16
+ ## Connection Modes
78
17
 
79
- Mouse tracking turns itself on where the terminal supports it. It takes over
80
- text selection while active, so press `m` when you want to copy something.
18
+ - **This machine only** *(default)*: Local workstation browser (127.0.0.1).
19
+ - **Local network / Tailscale**: Accessible over LAN or Tailnet (0.0.0.0).
20
+ - **Official relay**: Public relay at `wss://herdr-remote.564616.xyz`.
21
+ - **Self-hosted relay**: External access via standalone [`herdr-remote-relay`](https://www.npmjs.com/package/herdr-remote-relay).
81
22
 
82
- ## Pairing
83
-
84
- Open **Pair a device** and press Enter. Scan the QR code, or enter the six
85
- characters on the page. The browser gets a long-lived token; the code is burned
86
- on first use and expires after ten minutes.
87
-
88
- ## Keeping it running
89
-
90
- The **Keep-alive** tab installs a service that starts the relay and host
91
- connector at login and restarts them if they die — a systemd user unit on
92
- Linux, a LaunchAgent on macOS, and a supervised background process where
93
- neither is available.
94
-
95
- On Linux, "Enable start at boot" runs `loginctl enable-linger` so it also comes
96
- up before you log in.
97
-
98
- ## Command line
99
-
100
- Everything the TUI does is scriptable:
23
+ ## CLI Commands
101
24
 
102
25
  ```bash
103
26
  herdr-remote start | stop | restart
@@ -109,46 +32,18 @@ herdr-remote plugin link | unlink | status
109
32
  herdr-remote --lang zh|en
110
33
  ```
111
34
 
112
- ## Herdr plugin
35
+ ## Herdr Plugin
113
36
 
114
- The package is also a Herdr plugin. Register it from the **Herdr** tab, or:
37
+ Register as a native Herdr plugin:
115
38
 
116
39
  ```bash
117
40
  herdr-remote plugin link
118
41
  ```
119
42
 
120
- Nothing is compiled at registration time — the npm package ships prebuilt.
121
-
122
- > Upgrading from a source checkout? Unlink the old one first:
123
- > `herdr plugin unlink herdr.remote.web`. Your settings are migrated
124
- > automatically on first run.
125
-
126
43
  ## Configuration
127
44
 
128
- `~/.config/herdr-remote/config.json`, edited through the TUI:
129
-
130
- ```json
131
- {
132
- "ui": { "language": "auto" },
133
- "relay": { "mode": "local", "port": 8787, "lanHost": "", "publicUrl": "", "remoteUrl": "" },
134
- "herdr": { "socketPath": null, "args": [] },
135
- "keepalive": { "manager": "auto" }
136
- }
137
- ```
138
-
139
- Secrets are never stored here. The workstation's host token and the relay
140
- password live in `~/.local/state/herdr-remote/runtime.json`, mode 0600.
141
-
142
- ## Security
143
-
144
- - The relay never runs a shell and never sees your Herdr socket; only the host
145
- connector on your machine does.
146
- - Tokens are stored as SHA-256 hashes. Terminal content is never written to disk.
147
- - Pairing codes are single-use, expire in ten minutes, and are rate limited.
148
- - Secrets never appear in URLs or shell history; the web UI strips them from the
149
- address bar after pairing.
150
- - One writable controller at a time, with explicit takeover; other devices watch
151
- read-only.
45
+ - Settings: `~/.config/herdr-remote/config.json`
46
+ - Runtime state: `~/.local/state/herdr-remote/runtime.json` (mode `0600`)
152
47
 
153
48
  ## License
154
49
 
package/README.zh-CN.md ADDED
@@ -0,0 +1,50 @@
1
+ # herdr-remote
2
+
3
+ *[English](README.md) · [简体中文](README.zh-CN.md)*
4
+
5
+ [Herdr](https://herdr.dev) 工作区的 Web 终端客户端。支持移动端触控、低延迟 ANSI 传输与双语配置 TUI。
6
+
7
+ ## 安装与运行
8
+
9
+ ```bash
10
+ npm install -g herdr-remote
11
+ herdr-remote
12
+ ```
13
+
14
+ 直接运行 `herdr-remote` 即可启动向导并进入配置 TUI。
15
+
16
+ ## 访问模式
17
+
18
+ - **仅本机** *(默认)*：仅本机浏览器可访问 (127.0.0.1)。
19
+ - **局域网 / Tailscale**：局域网或 Tailnet 内设备可访问 (0.0.0.0)。
20
+ - **官方 Relay**：使用官方公开 Relay (`wss://herdr-remote.564616.xyz`)。
21
+ - **自建 Relay**：连接独立部署的 [`herdr-remote-relay`](https://www.npmjs.com/package/herdr-remote-relay) 服务。
22
+
23
+ ## 常用命令
24
+
25
+ ```bash
26
+ herdr-remote start | stop | restart
27
+ herdr-remote status [--json]
28
+ herdr-remote pair [--json]
29
+ herdr-remote url
30
+ herdr-remote keepalive install | uninstall | restart | status
31
+ herdr-remote plugin link | unlink | status
32
+ herdr-remote --lang zh|en
33
+ ```
34
+
35
+ ## Herdr 插件
36
+
37
+ 注册为 Herdr 插件：
38
+
39
+ ```bash
40
+ herdr-remote plugin link
41
+ ```
42
+
43
+ ## 配置路径
44
+
45
+ - 配置文件：`~/.config/herdr-remote/config.json`
46
+ - 运行状态：`~/.local/state/herdr-remote/runtime.json` (权限 `0600`)
47
+
48
+ ## 开源协议
49
+
50
+ MIT
package/bin/herdr-remote.js CHANGED
@@ -24,29 +24,29 @@ const { preferredLanAddress } = require('../src/net-interfaces');
24
24
 
25
25
  const VERSION = require('../package.json').version;
26
26
 
27
- const USAGE = `herdr-remote ${VERSION} — remote browser access to your Herdr workspaces
27
+ const USAGE = `herdr-remote ${VERSION} — browser access to Herdr workspaces
28
28
 
29
29
  Usage: herdr-remote [command] [options]
30
30
 
31
31
  Commands:
32
32
  (none) Open the configuration TUI
33
- start Start the relay and host connector
34
- stop Stop them
35
- restart Restart them
33
+ start Start relay and host connector
34
+ stop Stop services
35
+ restart Restart services
36
36
  status [--json] Show service status
37
- pair [--json] Create a one-time pairing code
38
- url Print the URL to open in a browser
39
- run [--daemon] Run the services in the foreground (used by keep-alive)
37
+ pair [--json] Create pairing code
38
+ url Print browser access URL
39
+ run [--daemon] Run services in foreground (keep-alive)
40
40
  keepalive <action> install | uninstall | restart | status
41
- plugin <action> link | unlink | status (Herdr plugin registration)
41
+ plugin <action> link | unlink | status (Herdr plugin)
42
42
 
43
43
  Options:
44
- --lang <zh|en> Force the interface language
45
- --json Machine readable output where supported
46
- -h, --help Show this help
47
- -v, --version Show the version
44
+ --lang <zh|en> Interface language
45
+ --json JSON output
46
+ -h, --help Show help
47
+ -v, --version Show version
48
48
 
49
- Self-hosting a relay: docs/self-hosted-relay.md
49
+ Self-hosting: docs/self-hosted-relay.md
50
50
  `;
51
51
 
52
52
  function parseArgs(argv) {
@@ -97,8 +97,7 @@ async function runTui(options) {
97
97
  const bundle = path.join(__dirname, '..', 'dist', 'tui.mjs');
98
98
  if (!fs.existsSync(bundle)) {
99
99
  process.stderr.write(
100
- 'herdr-remote: the TUI bundle is missing.\n'
101
- + 'If you are running from a source checkout, build it first:\n'
100
+ 'herdr-remote: TUI bundle missing. Build first:\n'
102
101
  + ' npm run build -w herdr-remote\n',
103
102
  );
104
103
  process.exitCode = 1;