auvezy-terminal-remote 0.6.0 → 0.7.0

package/README.md

@@ -12,8 +12,8 @@
 **English** · [简体中文](./README.zh-CN.md)
 
 Remote-control any terminal program on your PC from a phone or tablet
-browser over LAN. One command — `atr [program]` — and every instance
-shows up as a tab in your browser's top bar.
+browser over LAN. Start a broker once at boot — open the browser any
+time to log in, create instances, and run Claude / your shell / any TUI.
 
 <img src="./frontend/public/screenshots/desktop.png" alt="Webapp running Claude Code in a browser tab" width="720">
 
@@ -23,15 +23,61 @@ shows up as a tab in your browser's top bar.
 
 - **PTY bridge** — node-pty + xterm.js 5, full ANSI, alt-screen TUI safe
 - **Claude Code / TUI tuned** — Ink/Yoga reflow fix on resize, alt-screen blocklist, "adapt to current device" PTY sizing
-- **Multi-instance** — every `atr` grabs the next free port; one tab bar shows them all
+- **Multi-instance** — every instance is its own subprocess; one tab bar shows them all, URL is the instance (`/i/<id>/`)
 - **Multi-client** — many browsers / `attach` clients on one instance, with master arbitration
 - **Mobile-first PWA** — IME guard, long-press, swipe scroll, viewport-aware fit, install to home screen
 - **Custom shortcuts & commands** — define on-screen keys and saved command snippets in the settings panel
 - **Reconnect with replay** — scrollback rehydrated on every reconnect, alt-screen TUIs protected
-- **LAN-only by design** — token + port-bound cookie, `timingSafeEqual`, loopback-only `/api/hook`
-- **WSL aware** — mirrored / NAT auto-detected, PowerShell port-forward script generated
+- **LAN-only design** — token + shared sessions, `timingSafeEqual`, `/api/hook` is loopback-only, workers bind to 127.0.0.1
+- **WSL aware** — auto-detects mirrored vs NAT mode; prints a one-liner PowerShell port-forward snippet when needed
+- **Boot autostart** — `atr broker service install` writes the systemd / launchd config in one shot
 
-Full inventory in [`docs/FEATURES.md`](./docs/FEATURES.md).
+Full list: [`docs/FEATURES.md`](./docs/FEATURES.md).
+
+## 🏛️ Architecture
+
+`atr` is a two-process model: **broker** is the LAN entry and coordinator,
+**worker** is a single PTY instance.
+
+```
+        Browser / phone                  Your PC
+        ┌──────────────┐                ┌──────────────────────────────────┐
+        │              │   ws://host    │  broker (LAN: 0.0.0.0:3000)      │
+        │  webapp PWA  │ ──────────────►│  ├─ /api/*  (auth / instances /  │
+        │              │                │  │           push / config / …)  │
+        │              │                │  ├─ /i/<id>/  → SPA + base href  │
+        │              │                │  ├─ /i/<id>/api/* → proxy worker │
+        │              │                │  └─ /i/<id>/ws    → proxy worker │
+        └──────────────┘                │            │                     │
+                                        │            ▼                     │
+                                        │  worker A   worker B   …         │
+                                        │  127.0.0.1: 127.0.0.1:           │
+                                        │  3001       3002       …         │
+                                        │  ├─ PTY (claude / shell / TUI)   │
+                                        │  ├─ /api/health  /api/hook       │
+                                        │  └─ /ws (PTY IO)                 │
+                                        └──────────────────────────────────┘
+```
+
+- **broker** (LAN entry point): the only outward-facing process, listens on
+  `0.0.0.0:3000`. Owns all "system-level" APIs: login, user config,
+  instance list, push subscriptions, SSE live stream. Serves the static
+  frontend and injects `<base href>` for `/i/<id>/`. Long-lived — start
+  once at boot.
+- **worker** (PTY instance): one subprocess per instance, listens on a
+  high port at `127.0.0.1` only. Exposes only `/api/health` (probe),
+  `/api/hook` (loopback only), and `/ws` (PTY IO). Spawned by the broker
+  via `POST /api/instances`, detached + unref so it outlives broker
+  restarts.
+- **Shared sessions**: broker and workers share a file-locked sessions
+  store — one cookie authenticates everywhere.
+- **Entry model**: the browser always talks to the broker; URL `/i/<id>/`
+  identifies an instance. F5 doesn't lose context. Single PWA, multiple
+  instances.
+
+Module diagram and data flow: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
+Design decisions (broker/worker split, lifecycle, API ownership, base
+href injection, …): [`docs/plans/path-routing/adrs/`](./docs/plans/path-routing/adrs/).
 
 ## 📦 Install
 
@@ -39,44 +85,100 @@ Full inventory in [`docs/FEATURES.md`](./docs/FEATURES.md).
 npm install -g auvezy-terminal-remote   # -g is required (it's a CLI)
 ```
 
-> ⚠️ The default `npm i` command shown on the npm package page is **missing
-> `-g`** — without it the `atr` binary won't be on your PATH.
+> ⚠️ The default `npm i` command shown on the npm package page is
+> **missing `-g`** — without it the `atr` binary won't be on your PATH.
 
 ## 🚀 Quick start
 
+### Run the background service once at boot (recommended)
+
 ```bash
-atr                       # runs your $SHELL (zsh / bash auto-detected)
-atr claude                # runs claude
-atr claude --resume foo   # extra args passed through to claude
+atr --install            # writes systemd (Linux/WSL2) / launchd (macOS) config
+# Follow the printed steps to enable + start; auto-starts at boot.
 ```
 
-After it starts, scan the QR code printed in the terminal — the webapp
-logs in automatically (token lives in `~/.auvezy/terminal-remote/config.json`).
+Or run it manually (for testing / no autostart):
+
+```bash
+atr --start              # foreground, Ctrl+C to quit
+```
+
+### Open in a browser
+
+```bash
+atr --status             # one-shot view: process / token / entry URLs / instances
+```
+
+The "entry URLs" section lists every reachable URL with `?token=<token>`
+appended — paste any of them into a browser to log in. The default entry
+is marked with ★ (Tailscale > LAN > IPv6 > loopback).
+
+After the webapp loads, click "+ New instance", pick a cwd, and a PTY
+spawns. Default command is `$SHELL`; run `claude` (or anything else)
+inside it.
+
+### Spawn an instance directly (CLI, classic usage)
+
+```bash
+atr                          # runs your $SHELL
+atr claude                   # runs claude
+atr claude --resume foo      # extra args pass through
+```
 
-Run `atr` in different terminals to spawn more instances; the browser tab
-bar updates live.
+The CLI auto-ensures the background service is up (forks one if not),
+spawns the instance, and prints the URL.
 
 ## 🔧 Usage
 
 ```
-atr [atr-flags...] [program] [program-args...]
-atr <subcommand> [args]
+atr <service-flag>                          # manage background service (must follow atr)
+atr [run-flags...] [program] [args...]      # spawn a PTY instance
+atr <subcommand> [args]                     # instance-level operations
 ```
 
-Most-used flags:
+### Service-level flags (must follow `atr`; mutually exclusive)
 
 | Flag | Purpose |
 |---|---|
-| `-p, --port <n>` | Port (default 3000, auto-increments) |
+| `atr --start` | Start the background service (foreground, Ctrl+C to quit) |
+| `atr --stop` | Stop the background service (SIGTERM → 5s grace → SIGKILL) |
+| `atr --status` | One-shot view: process, token, entry URLs, instances |
+| `atr --list` | List all live instances |
+| `atr --logs` | Tail today's service log (`~/.atr/broker-YYYY-MM-DD.log`) |
+| `atr --install` | Register autostart (systemd / launchd) |
+| `atr --uninstall` | Remove autostart |
+
+### Run flags (used with `atr [program]`)
+
+| Flag | Purpose |
+|---|---|
+| `-p, --port <n>` | Service port (default 3000); instance ports are auto-assigned |
 | `--name <s>` | Instance name (shown in webapp) |
-| `--no-terminal` | Don't print QR (CI / daemon-friendly) |
+| `--no-terminal` | Don't print the QR / banner (CI / daemon-friendly) |
 | `--workdir <path>` | Child process cwd |
-| `--token <s>` | Use a fixed token instead of auto-generated |
+| `--token <s>` | Use a fixed token instead of reading `~/.atrrc` |
+
+### Instance-level subcommands
 
-Subcommands: `atr list` · `atr stop [pattern]` · `atr attach <url>`.
+| Command | Purpose |
+|---|---|
+| `atr stop [pattern]` | Stop an instance (substring match on name / cwd / host:port; no pattern = stop all) |
+| `atr attach <url>` | CLI client to share a PTY with a running instance |
 
-Full reference (all flags, env vars, config file): [`docs/CLI.md`](./docs/CLI.md).
-Run `atr -h` for the inline help.
+Full reference (all flags, env vars, config file):
+[`docs/CLI.md`](./docs/CLI.md). Run `atr -h` for the inline help.
+
+## 📂 File locations
+
+| Path | Contents |
+|---|---|
+| `~/.atrrc` | Main config: token, user prefs, shortcuts, command snippets |
+| `~/.atr/instances.json` | Live instance registry (broker / worker share it) |
+| `~/.atr/broker.json` | Broker process state (pid / port / startedAt) |
+| `~/.atr/broker-YYYY-MM-DD.log` | Broker daily log (kept for 7 days) |
+| `~/.atr/sessions/` | Shared session files |
+| `~/.atr/vapid-keys.json` | Web Push VAPID keys |
+| `~/.atr/push-subscriptions.json` | Subscribed push endpoints |
 
 ## 📱 Install as a PWA
 
@@ -88,28 +190,39 @@ app: no browser chrome, status bar tinted to match.
 
 ## 🌐 WSL → Windows browser
 
-WSL2 backend works out of the box on **mirrored mode**. On **NAT mode**
-the banner prints a one-shot PowerShell snippet to make the port reachable
-from Windows. Details: [`docs/WSL.md`](./docs/WSL.md).
+WSL2 works out of the box on **mirrored mode**. On **NAT mode** the banner
+prints a one-shot PowerShell snippet to make the port reachable from
+Windows. Details: [`docs/WSL.md`](./docs/WSL.md).
 
 ## 🛣️ Roadmap
 
 Planned, evaluating, and explicitly out-of-scope items live in
-[`docs/ROADMAP.md`](./docs/ROADMAP.md). The README only lists what already ships.
-
-## 🏛️ Architecture
-
-- Module diagram & data flow: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)
-- Design doc & ADRs: [`docs/plans/open-claude-remote-clone/`](./docs/plans/open-claude-remote-clone/)
+[`docs/ROADMAP.md`](./docs/ROADMAP.md). The README only lists what
+already ships.
 
 ## 🛠️ Development
 
 ```bash
 git clone https://github.com/jjj201200/auvezy-terminal-remote.git
 cd auvezy-terminal-remote
-bash install.sh           # checks Node 20+ / pnpm 9+ / build deps → installs → builds
-pnpm dev                  # backend (tsx watch) + frontend (vite) in parallel
-pnpm test                 # shared + backend + frontend unit tests
+bash install.sh            # checks Node 20+ / pnpm 9+ / build deps → installs → builds
+```
+
+Dev startup order (broker first, then vite):
+
+```bash
+# Terminal 1: start broker in dev mode (tsx running src)
+pnpm --filter auvezy-terminal-remote exec tsx src/cli.ts broker start
+
+# Terminal 2: vite dev server; proxies /api and /i/ to the broker (3000)
+pnpm --filter auvezy-terminal-remote-frontend dev
+# Open http://localhost:5173/
+```
+
+Run tests:
+
+```bash
+pnpm test                  # shared + backend + frontend unit tests
 ```
 
 Gitee mirror (faster from mainland China):