auvezy-terminal-remote 0.4.4 → 0.4.5

package/README.md

@@ -1,107 +1,297 @@
 # auvezy-terminal-remote
 
-> 局域网内通过手机 / 平板浏览器远程控制 PC 上的任意终端程序（zsh / bash / claude / 任何 CLI）。
+**English** | [简体中文](https://github.com/jjj201200/auvezy-terminal-remote/blob/main/README.zh-CN.md)
+
+> Remote-control any terminal program on your PC (zsh / bash / claude / any CLI)
+> from a phone or tablet browser over LAN.
 >
-> 一行命令 `atr <program>`，多终端多实例自动出现在浏览器顶栏 tab 切换。
+> One command — `atr <program>` — and every instance shows up as a tab in your
+> browser's top bar.
+
+> **License: [PolyForm Noncommercial 1.0.0](./LICENSE)** —
+> free for personal, educational, and nonprofit use, including modification and
+> redistribution. Commercial use requires a separate license.
+
+## What is this
 
-## 这是什么
+You're on the couch with your phone. A long-running CLI on your PC
+(Claude Code / a deploy script / a debug session…) is doing its thing and
+you want to:
 
-你坐在沙发上拿着手机，PC 上某个 CLI（Claude Code / 部署脚本 / 调试会话…）正在跑一个长任务。你希望：
+- See its live output (ANSI colors included)
+- Type the next command, hit arrow keys
+- Get a phone notification when Claude triggers an approval hook
+- Not open any port to the public internet, not depend on a cloud service
 
-- 实时看到终端输出（包括 ANSI 颜色）
-- 输入下一条指令、按方向键
-- Claude 触发审批 hook 时，手机锁屏弹通知
-- 不开公网、不依赖云
+That's exactly what this project does. PTY output is bridged over WebSocket
+to a webapp; webapp input is bridged back to the PTY. Listens on LAN IPs only,
+authed by token + local cookie.
 
-这正是这个项目要做的。把 PTY 输出经 WebSocket 桥到 webapp，
-把 webapp 输入桥回 PTY。仅绑 LAN IP，用 token + 本地 cookie 鉴权。
+## Quick start
 
-## 安装
+### Global install (npm users)
 
 ```bash
-npm install -g auvezy-terminal-remote
+npm install -g auvezy-terminal-remote   # -g is required
 ```
 
-## 使用
+> ⚠️ The default `npm i auvezy-terminal-remote` shown at the top right of the
+> npm package page is **missing `-g`**. This is a CLI tool — without `-g` the
+> `atr` binary won't be on your PATH. Use the command above.
+
+Then in any terminal:
 
 ```bash
-atr                       # 跑当前 $SHELL（zsh / bash 自动检测）
-atr claude                # 跑 claude
-atr zsh                   # 跑 zsh
-atr claude --resume foo   # 透传任意参数给子进程
+atr                       # runs your $SHELL (auto-detects zsh / bash)
+atr claude                # runs claude
+atr zsh                   # runs zsh
+atr claude --resume foo   # passes any args through to the child process
 ```
 
-启动后扫终端打印的二维码 → webapp 自动登录（token 在 `~/.auvezy/terminal-remote/config.json`）。
+After it starts, scan the QR code printed in the terminal — the webapp logs in
+automatically (token lives in `~/.auvezy/terminal-remote/config.json`).
 
-**多实例**：在不同终端多次 `atr <prog>`，每次会自动占一个新端口（3000、3001、3002…），
-浏览器顶栏会自动出现新 tab，点击即可切换。
+**Multiple instances**: Run `atr <prog>` in different terminals; each grabs the
+next available port (3000, 3001, 3002…). Tabs for new instances appear in the
+browser's top bar automatically — click to switch.
 
 ```bash
-atr list                  # 列出本机所有实例
-atr stop                  # 停止本机所有实例
-atr attach <url>          # 命令行接管已有实例
+atr list                  # list all running instances on this machine
+atr stop                  # stop all instances on this machine
+atr attach <url>          # take over a running instance from the command line
 ```
 
-## 启动选项
+### From source (development or self-build)
+
+```bash
+# GitHub (primary)
+git clone https://github.com/jjj201200/auvezy-terminal-remote.git
+# or Gitee mirror (faster from mainland China)
+git clone https://gitee.com/drowsyflesh/auvezy-terminal-remote.git
 
+cd auvezy-terminal-remote
+bash install.sh           # checks Node 20+ / pnpm 9+ / build deps → installs → builds
+node backend/dist/cli.js  # equivalent to `atr`
 ```
-atr [子命令] [选项]
-
-子命令：
-  start          启动 backend（默认）
-  attach         attach 到运行中的实例（命令行接管）
-  list           列出本机所有运行中实例
-  stop           停止本机所有实例
-
-选项：
-  -p, --port <n>      端口（默认 3000，多实例自动递增；除非 -S）
-  -S, --strict-port   严格端口模式：被占即报错退出，不自适应
-  --spawn-timeout <s> PTY spawn 兜底秒数（默认 30；0=不超时；
-                      首个浏览器连入 / 按 Enter / 超时三选一触发）
-  --wait-confirm      强制必须按 Enter 才 spawn（覆盖浏览器/超时触发）
-  --name <s>          实例名（用于 webapp 显示）
-  --no-terminal       不打印二维码（CI / 守护进程友好）
-  --command <cmd>     PTY 启动命令（默认当前 $SHELL）
-  --args <json>       命令参数（JSON 数组字符串）
-  -h, --help          显示帮助
-  -v, --version       显示版本号
+
+
+## Feature matrix
+
+| Feature | How it's implemented |
+|---|---|
+| PTY bridge | node-pty + xterm.js 5 |
+| Auth | timingSafeEqual token + Session Cookie (port-bound) |
+| Multi-instance | port-finder auto-increment + cookie-name suffix isolation |
+| Reconnect / replay | OutputBuffer + history_sync (alt-screen filtered by default) |
+| Approval push | Web Push (VAPID, 3 priorities) + iOS Safari LocalNotification fallback |
+| IP drift detection | 30s polling + stability threshold + ip_changed broadcast |
+| Config rewrite | Webapp Settings dialog → /api/config |
+| `attach` subcommand | Master arbitration (webapp > attach > PC) |
+
+## Configuration
+
+On startup the backend reads `~/.auvezy/terminal-remote/config.json`:
+
+```json
+{
+  "token": "<64-char hex, auto-generated>",
+  "shortcuts": [
+    { "label": "ESC", "data": "" },
+    { "label": "↑",   "data": "[A" }
+  ],
+  "command": null,
+  "args": null,
+  "rateLimitPerMinute": 10,
+  "sessionTtlMs": 86400000
+}
+```
+
+VAPID keys live in the same directory: `vapid.json` (mode 0o600, auto-generated
+or read from env vars `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY`).
+
+Subscriptions are in `push-subscriptions.json`; the multi-instance registry is in
+`instances/<port>.json`.
+
+## Startup options
+
 ```
+atr [subcommand] [options]
 
-环境变量：
+Subcommands:
+  start          start the backend (default)
+  attach         attach to a running instance from the command line
+  list           list all running instances on this machine
+  stop           stop all instances on this machine
 
-| 变量 | 用途 |
+Options:
+  -p, --port <n>      port (default 3000, auto-increments unless -S)
+  -S, --strict-port   strict port mode: fail if port is taken, no fallback
+  --spawn-timeout <s> PTY spawn fallback seconds (default 30; 0 = no timeout;
+                      first browser connect / Enter / timeout — whichever first)
+  --wait-confirm      require Enter to spawn (overrides browser/timeout triggers)
+  --name <s>          instance name (shown in webapp)
+  --no-terminal       don't print QR code (CI / daemon-friendly)
+  --command <cmd>     PTY command (default: 'claude')
+  --args <json>       command args (JSON array string)
+  -h, --help          show help
+  -v, --version       show version
+```
+
+Environment variables:
+
+| Variable | Purpose |
 |---|---|
-| `OCR_COMMAND` | 子进程命令（默认 `$SHELL`，没有则 `/bin/sh`；显式设为 `claude` 跑 Claude）|
-| `OCR_ARGS`    | 命令参数（JSON 数组字符串，如 `'["-c","tail -f /dev/null"]'`）|
-| `OCR_CWD`     | 子进程工作目录（默认 `process.cwd()`）|
-| `OCR_ANSI_FILTER` | 是否过滤 alt-screen 输出（默认 `false`）。设 `true` 让 vim/htop 退出后重连回放更干净；但全程 alt-screen TUI（claude/tmux/...）仍受内置黑名单保护 |
-| `OCR_ANSI_FILTER_TUI_NAMES` | 追加自家 alt-screen TUI 黑名单（逗号分隔），例如 `"lazygit,k9s,gh-dash"` |
-| `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` | 注入 VAPID（高优先级，跳过文件）|
-| `PORT`        | 同 `--port` |
-| `STRICT_PORT` | 同 `--strict-port`（设 `true` 启用严格模式）|
-| `OCR_SPAWN_TIMEOUT` | 同 `--spawn-timeout`（秒；0 = 无超时）|
-| `AUTH_TOKEN`  | 指定 token（默认自动生成）|
-| `LOG_LEVEL`   | pino 级别（默认 info）|
+| `OCR_COMMAND` | Child command (default `$SHELL`, or `/bin/sh`; set to `claude` to run Claude) |
+| `OCR_ARGS`    | Command args (JSON array string, e.g. `'["-c","tail -f /dev/null"]'`) |
+| `OCR_CWD`     | Child process working directory (default: `process.cwd()`) |
+| `OCR_ANSI_FILTER` | Filter alt-screen output (default `false`). Set `true` for cleaner reconnect replay after vim/htop exits; full-time alt-screen TUIs (claude/tmux/...) are still protected by built-in blocklist |
+| `OCR_ANSI_FILTER_TUI_NAMES` | Append to your own alt-screen TUI blocklist (comma-separated), e.g. `"lazygit,k9s,gh-dash"` |
+| `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` | Inject VAPID keys (highest priority, skips file) |
+| `PORT`        | Same as `--port` |
+| `STRICT_PORT` | Same as `--strict-port` (set `true` to enable strict mode) |
+| `OCR_SPAWN_TIMEOUT` | Same as `--spawn-timeout` (seconds; 0 = no timeout) |
+| `AUTH_TOKEN`  | Specify token (default: auto-generated) |
+| `LOG_LEVEL`   | pino level (default `info`) |
+
+> Legacy names `CLAUDE_COMMAND` / `CLAUDE_ARGS` / `CLAUDE_CWD` still work
+> (warned once at startup). Renamed to make it clear: this project is not tied
+> to Claude — it can run any PTY program.
+
+## Install as a PWA (recommended on mobile)
+
+The webapp ships with a manifest. "Add to Home Screen" gives you a near-native
+app experience:
+
+- **Android Chrome**: top-right ⋮ → "Install app" (or the address bar shows an
+  "Install" prompt)
+- **iOS Safari**: share button → "Add to Home Screen"
+
+After install: no browser UI (no address bar, no bottom nav), independent task
+card, status bar matches the app color.
+
+> **Web Push limitations**: browsers require Push to be in a secure context
+> (HTTPS / localhost). LAN HTTP (http://192.168.x.x) cannot subscribe to push.
+> The settings panel will display "HTTPS required". Workarounds: use Tailscale /
+> Cloudflare Tunnel to put HTTPS in front of the backend, or deploy with a
+> self-signed certificate.
+
+## Running in WSL, accessing from Windows browser
+
+WSL2 has two network modes that behave differently:
+
+- **Mirrored mode** (Win11 22H2+ default): WSL gets the Windows LAN IP directly
+  (e.g. `192.168.x.x`). Windows browsers can use the IP printed on the banner,
+  no extra config.
+- **NAT mode** (default): WSL is on `172.x.x.x` private network — Windows
+  browsers can't connect directly. The backend detects this on startup and
+  prints PowerShell config commands at the end of the banner.
+
+**One-shot auto config** (admin PowerShell):
+
+```powershell
+# Forward common port range (default 3000–3010)
+.\scripts\wsl-port-forward.ps1
+
+# Forward specific ports only
+.\scripts\wsl-port-forward.ps1 -Ports 3000,3001
+
+# Register to re-forward on login (no manual re-run when WSL IP changes)
+.\scripts\wsl-port-forward.ps1 -Persist
+
+# Cleanup
+.\scripts\wsl-port-forward.ps1 -Reset
+```
+
+## Architecture / decisions
+
+- Design doc: [`docs/plans/open-claude-remote-clone/design.md`](./docs/plans/open-claude-remote-clone/design.md)
+- Module diagram and data flow: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)
+- Architecture decision records (ADRs):
+  [`docs/plans/open-claude-remote-clone/adrs/`](./docs/plans/open-claude-remote-clone/adrs/)
+
+## Development
+
+```bash
+pnpm install
+pnpm dev          # backend (tsx watch) + frontend (vite) in parallel
+pnpm test         # shared + backend + frontend unit tests
+pnpm typecheck
+pnpm build        # full build artifacts (frontend copied into backend/frontend-dist)
+```
+
+
+## Roadmap
+
+### Tier 1 (must-have for mobile, low effort, big UX win)
+
+1. **Local Echo** (Mosh / Blink / code-server)
+   Input lag killer on mobile 4G/weak networks. xterm prediction plugin shows
+   keystrokes immediately, PTY response replaces.
+2. **Multi-line paste warning + bracketed paste** (VS Code, Tabby)
+   Mobile users paste 5-line commands from WeChat/email — currently goes
+   straight to PTY, dangerous. Detect multi-line → confirm dialog.
+3. **Shell Integration subset (OSC 633/133)**
+   - Command decorations (green/red dot)
+   - Run Recent Command — fuzzy cross-session history quick pick
+   - Both extremely friendly on mobile (slow typing → cross-session history
+     search is core)
+4. **Auto Reply** (VS Code)
+   Match prompt → auto-respond y/N. Mobile users hate typing `[y/N]`.
+5. **Process Revive** (VS Code terminal revive)
+   You already have instances.json; serialize scrollback into it. After restart
+   webapp can see the previous content. The only hard part on the LAN-only
+   route is serialization size — bumping to 5MB is fine.
 
-## 配置
+### Tier 2 (mobile UX bonus)
 
-启动时自动读 `~/.auvezy/terminal-remote/config.json`（首次启动自动生成）。
-VAPID 在 `~/.auvezy/terminal-remote/vapid.json`，多实例注册表在
-`~/.auvezy/terminal-remote/instances/<port>.json`。
+6. **SmartKeys long-press menu** (Blink)
+   On-screen keyboard expansion row: long-press Tab → Shift+Tab; long-press Esc
+   → `^[`; long-press Ctrl → sticky until next key. We already have a Toolbar
+   shortcut panel, missing "long-press menu" + "modifier sticky".
+7. **Thumb-drag cursor strip** (Termius: long-press space as trackpad)
+   Bottom 8px transparent strip on the terminal area; drag = arrow key
+   sequence. Best solution for precise cursor movement on mobile.
+8. **OSC 8 hyperlinks + word-link / file-link** (VS Code)
+   xterm.js native LinkProvider — a few lines makes `src/foo.ts:42` clickable.
+9. **Multi-chord shortcuts / modifier sticky** (Tabby, Blink)
+   Mobile virtual modifier + Cmd-K Cmd-S two-step combos save more screen than
+   a wall of buttons.
+10. **Quick Fixes** (VS Code)
+    Scan output, suggest fixes. `fatal: ... --set-upstream` one-click apply.
+    High effort but very flashy.
 
-## 在 WSL 中跑、Windows 浏览器访问
+### Tier 3 (write permission / security / collaboration)
 
-WSL2 的两种网络模式行为不同：
+11. **Writable / Read-only split** (ttyd -W, gotty -w)
+    When multiple devices connect to one instance, others can be set to
+    read-only. Very low effort (distinguish at WS handshake).
+12. **Broadcast Input** (Termius: simultaneous input on multiple terminals)
+    When multiple webapps connect to one instance, broadcast the same input to
+    all PTYs. Easy to add to our multi-instance arch.
+13. **TLS self-signed cert** (ttyd -S, gotty -t)
+    HTTPS on LAN lets Web Push API work in more browsers (currently restricted
+    on LAN HTTP).
+14. **OAuth / client cert auth** (ttyd client cert)
+    On top of our token, add client cert for hardware auth. Low priority —
+    token is already enough.
 
-- **mirrored 模式**（Win11 22H2+ 默认）：WSL 直接拿 Windows LAN IP（如 `192.168.x.x`），
-  Windows 浏览器可以直接用 banner 上的 IP 访问，无需任何额外配置
-- **NAT 模式**（默认）：WSL 在 `172.x.x.x` 私网，Windows 浏览器无法直连。
-  backend 启动时会自动检测并在 banner 末尾打印 PowerShell 配置命令
+### Tier 4 (explicitly NOT copying)
 
-## 系统要求
+- ❌ Plugin system (Tabby): unnecessary for a LAN-only single binary
+- ❌ Cloud Settings Sync (VS Code): conflicts with the LAN-only red line
+- ❌ Sixel/iTerm image protocols: low value on mobile, xterm.js doesn't
+  natively support them
+- ❌ asciinema public sharing: conflicts with LAN-only; if anything we'd only
+  do local `.cast` export
+- ❌ SFTP/SCP file management (Termius/Wetty): outside the "remote PTY control"
+  scope
+- ❌ End-to-end encrypted Vault: home LAN users don't need this
 
-- Node.js ≥ 20
+---
 
-## 许可
+## Pain points unique to us (others haven't done these)
 
-专有软件，保留所有权利。详见 LICENSE。
+- **Tailscale / VPN QR code labeling**: we already do dual LAN+Tailscale codes —
+  a thoughtful detail on the LAN-only route
+- **Webapp toast notification + iOS LocalNotification fallback**: under iOS PWA
+  push restrictions, this fallback strategy isn't considered by anyone else

package/dist/cli.js

@@ -37,7 +37,7 @@ function isServerMessage(value) {
   if (!value || typeof value !== "object")
     return false;
   const type = value.type;
-  return type === "terminal_output" || type === "status_update" || type === "history_sync" || type === "heartbeat" || type === "error" || type === "session_ended" || type === "terminal_resize" || type === "ip_changed";
+  return type === "terminal_output" || type === "status_update" || type === "history_sync" || type === "heartbeat" || type === "error" || type === "session_ended" || type === "terminal_resize" || type === "ip_changed" || type === "alt_screen_change";
 }
 var init_ws_protocol = __esm({
   "shared/dist/ws-protocol.js"() {
@@ -1755,7 +1755,7 @@ var init_pty_manager = __esm({
        */
       write(data) {
         if (!this.process) {
-          logger.warn({ dataLength: data.length }, "\u5C1D\u8BD5\u5199\u5165 PTY \u4F46\u8FDB\u7A0B\u672A\u8FD0\u884C");
+          logger.debug({ dataLength: data.length }, "\u5C1D\u8BD5\u5199\u5165 PTY \u4F46\u8FDB\u7A0B\u672A\u8FD0\u884C");
           return;
         }
         this.process.write(data);
@@ -1864,6 +1864,7 @@ var init_pty_manager = __esm({
           if (this._inAltScreen !== isEnter) {
             this._inAltScreen = isEnter;
             logger.debug({ inAltScreen: isEnter }, "PTY alt-screen \u72B6\u6001\u5207\u6362");
+            this.emit("altScreenChange", isEnter);
           }
         }
       }
@@ -1974,7 +1975,7 @@ var init_ws_server = __esm({
           }
           const clientType = this.opts.authenticate ? this.opts.authenticate(req) : "webapp";
           if (clientType === null) {
-            logger.warn({ url: req.url }, "WS upgrade \u88AB\u9274\u6743\u62D2\u7EDD");
+            logger.debug({ url: req.url }, "WS upgrade \u88AB\u9274\u6743\u62D2\u7EDD");
             socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
             socket.destroy();
             return;
@@ -2433,6 +2434,9 @@ var init_session_controller = __esm({
         this.pty.on("resize", (cols, rows) => {
           this.ws.broadcast({ type: "terminal_resize", cols, rows });
         });
+        this.pty.on("altScreenChange", (inAltScreen) => {
+          this.ws.broadcast({ type: "alt_screen_change", inAltScreen });
+        });
       }
       /**
        * 入队一段 PTY 输出，按三阈值决定是否立即 flush
@@ -2931,7 +2935,7 @@ function createWsAuthenticate(authModule) {
         logger.info({ remoteAddress: req.socket.remoteAddress }, "WS \u901A\u8FC7 URL token \u8BA4\u8BC1\uFF08attach\uFF09");
         return "attach";
       }
-      logger.warn({ remoteAddress: req.socket.remoteAddress }, "WS URL token \u65E0\u6548");
+      logger.debug({ remoteAddress: req.socket.remoteAddress }, "WS URL token \u65E0\u6548");
       return null;
     }
     const cookieHeader = req.headers.cookie ?? "";
@@ -2939,7 +2943,7 @@ function createWsAuthenticate(authModule) {
     if (sid && authModule.validateSession(sid)) {
       return "webapp";
     }
-    logger.warn({
+    logger.debug({
       remoteAddress: req.socket.remoteAddress,
       cookieNames: cookieHeader.split(";").map((c) => c.trim().split("=")[0]).filter(Boolean),
       expectedCookie: authModule.getCookieName()
@@ -4747,11 +4751,11 @@ var init_attach_client = __esm({
           try {
             parsed = JSON.parse(raw.toString());
           } catch {
-            logger.warn("\u6536\u5230\u975E JSON WS \u6D88\u606F\uFF0C\u5FFD\u7565");
+            logger.debug("\u6536\u5230\u975E JSON WS \u6D88\u606F\uFF0C\u5FFD\u7565");
             return;
           }
           if (!isServerMessage(parsed)) {
-            logger.warn("\u6536\u5230\u4E0D\u8BC6\u522B\u7684 server message\uFF0C\u5FFD\u7565");
+            logger.debug("\u6536\u5230\u4E0D\u8BC6\u522B\u7684 server message\uFF0C\u5FFD\u7565");
             return;
           }
           this.handleServerMessage(parsed);