pi-web-ui 0.1.1 → 0.2.1

package/README.md

@@ -43,15 +43,122 @@ npm run build        # compiles server (tsc) + frontend (vite)
 npm start            # serves everything on http://localhost:8787
 ```
 
+## npm package (install / start / stop / update / uninstall)
+
+The package is published on npm as [`pi-web-ui`](https://www.npmjs.com/package/pi-web-ui).
+
+### Install
+
+```bash
+# install globally (recommended)
+npm i -g pi-web-ui
+
+# or run without installing (pulls the latest, starts on :8787)
+npx pi-web-ui
+
+# or install the local checkout (for testing changes before publishing)
+npm i -g .
+```
+
+> **pi-managed npm?** If your `npm` is the pi wrapper that blocks dependency
+> install scripts, approve node-pty's native build once after installing:
+> `npm approve-scripts node-pty@1.1.0` (standard npm does this automatically).
+
+### Start
+
+```bash
+pi-web-ui                                            # foreground, http://localhost:8787
+PORT=9000 PI_WEB_CWD=/path/to/project pi-web-ui      # custom port / workspace
+```
+
+To run it in the background or auto-start on boot, use a system service —
+see [Deploy & auto-start on boot](#deploy--auto-start-on-boot) (systemd /
+launchd / Docker).
+
+The `pi-web-ui` command serves the built frontend and the WebSocket API from
+wherever the package is installed — no repo checkout needed. It uses **your**
+`~/.pi/agent` config (auth/models/skills) and stores per-client sessions under
+`<PI_WEB_CWD>/.pi-web`.
+
+### Stop
+
+- **Foreground**: press `Ctrl+C` in the terminal running it.
+- **systemd**: `sudo systemctl stop pi-web-ui`
+- **launchd**: `launchctl bootout gui/$(id -u)/com.xingshuyin.pi-web-ui`
+- **Windows (scheduled task)**: `pi-web-ui server stop` (or
+  `schtasks /End /TN pi-web-ui`; stops the running instance, auto-start stays
+  until `server uninstall`)
+- **Docker**: `docker compose stop` (stop + remove the container: `docker compose down`)
+
+(Background processes should be managed by a system service, not `nohup` —
+service stop commands above also stop and disable auto-start.)
+
+### Verify / version
+
+```bash
+pi-web-ui --version     # CLI version
+npm ls -g pi-web-ui     # installed? which version?
+which pi-web-ui         # executable location
+```
+
+### Update
+
+```bash
+npm i -g pi-web-ui@latest   # upgrade to the latest published version
+# restart the server afterwards for the new version to take effect
+```
+
+### Uninstall
+
+```bash
+npm uninstall -g pi-web-ui
+```
+
+Uninstalling does **not** delete your chats: session data lives in
+`<PI_WEB_CWD>/.pi-web` (or `PI_WEB_DATA_DIR`) and survives uninstall/upgrade.
+
+### Manage as a system service (auto-start)
+
+Install the server as a system service that starts on boot, with a custom
+port and workspace:
+
+```bash
+pi-web-ui server install --port 9000 --cwd /path/to/project   # install + start
+pi-web-ui server status                # running? auto-start?
+pi-web-ui server restart               # restart (also applies config changes)
+pi-web-ui server stop                  # stop + disable auto-start
+pi-web-ui server start                 # start again
+pi-web-ui server uninstall             # remove the service entirely
+```
+
+- **macOS** → launchd agent (no sudo): writes and loads
+  `~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist`, restarts on crash
+  (`KeepAlive`), logs to `/tmp/pi-web-ui.log` / `/tmp/pi-web-ui.err`.
+- **Linux** → systemd unit (auto-sudo): writes
+  `/etc/systemd/system/pi-web-ui.service` and runs `systemctl enable --now`,
+  logs via `journalctl -u pi-web-ui -f`.
+- **Windows** → Task Scheduler (no admin): creates a user task that starts at
+  logon (same as a launchd agent). It runs a `.cmd` wrapper generated at
+  `%APPDATA%\pi-web-ui\pi-web-ui.cmd` (sets env, cd's to the workspace,
+  launches node, appends logs to `%USERPROFILE%\pi-web-ui.log`). The task XML
+  is saved next to it; restarts on failure.
+- Options: `--port` (default 8787 or `$PORT`), `--cwd` (default `$PI_WEB_CWD`
+  or the current directory), `--data-dir` (sessions), `--name` (custom service
+  name; on macOS the label is `com.xingshuyin.pi-web-ui`, custom names become
+  `com.<name>.server`). `--print` previews the generated unit/plist/task files
+  without applying it.
+- Rerunning `install` with new options regenerates the config and restarts the
+  service — that's how you change the port/cwd of an installed service.
+
 ## Configuration
 
-| Env var | Default | Description |
-| --- | --- | --- |
-| `PORT` | `8787` | HTTP/WebSocket port |
-| `PI_WEB_CWD` | server's cwd | The workspace directory the agent operates in (read/edit/bash/write) |
-| `PI_WEB_DATA_DIR` | `<cwd>/.pi-web` | Where per-client session dirs are stored |
-| `PI_WEB_INLINE_FILE_MAX` | `12288` (12KB) | Text attachments at or below this size are inlined into the model context; larger files are passed as path references and the model reads them on demand (saves tokens for small edits) |
-| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | pi config dir (auth.json, models.json, skills, extensions) |
+| Env var                    | Default           | Description                                                                                                                                                                             |
+| -------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                   | `8787`          | HTTP/WebSocket port                                                                                                                                                                     |
+| `PI_WEB_CWD`             | server's cwd      | The workspace directory the agent operates in (read/edit/bash/write)                                                                                                                    |
+| `PI_WEB_DATA_DIR`        | `<cwd>/.pi-web` | Where per-client session dirs are stored                                                                                                                                                |
+| `PI_WEB_INLINE_FILE_MAX` | `12288` (12KB)  | Text attachments at or below this size are inlined into the model context; larger files are passed as path references and the model reads them on demand (saves tokens for small edits) |
+| `PI_CODING_AGENT_DIR`    | `~/.pi/agent`   | pi config dir (auth.json, models.json, skills, extensions)                                                                                                                              |
 
 Example — point the agent at a project:
 
@@ -83,6 +190,12 @@ Key design points:
   event it schedules a throttled (60 ms) full-state snapshot, and the browser
   renders purely from snapshots. Reconnects just re-request `get_state`. Large
   payloads (tool output, text) are capped during serialization (`server/serialize.ts`).
+- **Live assistant streaming.** The in-progress message (SDK
+  `agent.state.streamingMessage`) is serialized into every snapshot, so thinking
+  blocks and answer text appear in the browser as they are generated — with a
+  blinking cursor — instead of only after the turn finishes. The partial message
+  gets a stable `stream-<ts>` id so it stays mounted (open thinking/tool blocks
+  keep their state) across snapshots.
 - **Size-aware attachments.** Clicking + on a file queues it as an attachment
   (shown as chips above the input). On send, the server attaches each file as an
   independent custom message (SDK `sendCustomMessage` + `nextTurn` asides) — the
@@ -123,10 +236,10 @@ with three panes:
   `${pwd}` resolves to the agent's current working directory (the one shown in the chat
   view's file panel, changeable via set_cwd); `~` and relative paths also work. The `+`
   button at the top of the command panel creates a new entry.
-
-- **Middle — the terminal**: each tab is a real PTY (your `$SHELL`); output streams live
-  and you can type, Ctrl+C, resize, etc. exactly like a desktop terminal.
-
+- **Middle — the terminal**: each tab is a real PTY (your `$SHELL` on
+  macOS/Linux; PowerShell or cmd.exe — `$COMSPEC` — on Windows); output
+  streams live and you can type, Ctrl+C, resize, etc. exactly like a desktop
+  terminal. Git Bash users on Windows get their `$SHELL` automatically.
 - **Right — 终端 (tabs)**: VSCode-style vertical tab strip. `+` opens a plain shell in the
   current directory. Closing a tab kills its process.
 
@@ -149,15 +262,89 @@ Server → client: `ready`, `snapshot` (full `UiState`), `tool_delta`, `notice`,
 
 ## Scripts
 
-| Script | What it does |
-| --- | --- |
-| `npm run dev` | server (tsx watch) + Vite dev server with WS proxy |
-| `npm run build` | type-check + build frontend and server |
-| `npm start` | run the production server (serves `web/dist`) |
-| `npm run typecheck` | `tsc --noEmit` for both server and web |
-| `node terminal-smoke-test.mjs` | WS-level terminal/commands protocol test (build first) |
+| Script                             | What it does                                            |
+| ---------------------------------- | ------------------------------------------------------- |
+| `npm run dev`                    | server (tsx watch) + Vite dev server with WS proxy      |
+| `npm run build`                  | type-check + build frontend and server                  |
+| `npm start`                      | run the production server (serves`web/dist`)          |
+| `npm run typecheck`              | `tsc --noEmit` for both server and web                |
+| `node terminal-smoke-test.mjs`   | WS-level terminal/commands protocol test (build first)  |
 | `node terminal-browser-test.mjs` | headless-browser E2E of the terminal view (build first) |
 
+## Deploy & auto-start on boot
+
+Quickest path: `pi-web-ui server install --port 8787 --cwd /path` — installs
+and starts the service on boot (see [Manage as a system service](#manage-as-a-system-service-auto-start)).
+The manual alternatives below are kept for reference / non-standard setups.
+
+### Docker (one command)
+
+```bash
+docker compose up -d     # builds, starts on :8787, auto-restarts on boot
+docker compose stop      # stop (keeps the container)
+docker compose down      # stop and remove the container
+```
+
+`restart: unless-stopped` in `docker-compose.yml` brings the server back up
+whenever the Docker daemon starts (boot, crashes, reboots). Mount a volume for
+`/app/.pi-web` (sessions persist) and, optionally, your `~/.pi/agent` config
+and a workspace — see the comments in `docker-compose.yml`.
+
+### Linux — systemd
+
+```bash
+sudo npm i -g pi-web-ui
+sudo cp deploy/pi-web-ui.service /etc/systemd/system/
+# edit User/WorkingDirectory/Environment in the unit first
+sudo systemctl daemon-reload
+sudo systemctl enable --now pi-web-ui     # starts now + on every boot
+sudo systemctl stop pi-web-ui             # stop
+sudo systemctl disable pi-web-ui          # stop auto-start on boot
+journalctl -u pi-web-ui -f                # logs
+```
+
+### macOS — launchd
+
+```bash
+npm i -g pi-web-ui
+cp deploy/com.xingshuyin.pi-web-ui.plist ~/Library/LaunchAgents/
+# edit ProgramArguments / WorkingDirectory / PI_WEB_CWD (which pi-web-ui)
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist
+launchctl bootout gui/$(id -u)/com.xingshuyin.pi-web-ui   # stop + remove auto-start
+# logs: /tmp/pi-web-ui.log, /tmp/pi-web-ui.err
+```
+
+### Windows — Task Scheduler
+
+Easiest path (no admin, generates everything):
+
+```bat
+npm i -g pi-web-ui
+pi-web-ui server install --port 8787 --cwd C:\path\to\project
+pi-web-ui server status
+pi-web-ui server restart
+pi-web-ui server stop        :: stop the running instance (auto-start stays)
+pi-web-ui server uninstall   :: remove the task entirely
+```
+
+What it does: writes `%APPDATA%\pi-web-ui\pi-web-ui.cmd` (a `.cmd` wrapper
+that sets `PORT`/`PI_WEB_CWD`, cd's to the workspace, launches node and
+appends output to `%USERPROFILE%\pi-web-ui.log`) plus the Task Scheduler XML,
+then registers a **logon** task (`schtasks /Create /XML` — the task runs when
+you log in, same as a launchd agent; no admin needed). Preview both generated
+files without installing: `pi-web-ui server install --print`.
+
+Manual alternative with `deploy/pi-web-ui-task.xml`: edit the paths, save the
+file as **UTF-16 LE** (schtasks requires it), then
+`schtasks /Create /TN "pi-web-ui" /XML pi-web-ui-task.xml /F` and
+`schtasks /Run /TN "pi-web-ui"`.
+
+> **Boot-start without login?** A logon task needs an interactive session, just
+> like a launchd agent. For headless/always-on Windows use Docker (see above).
+
+The three templates use `KeepAlive` / `Restart=on-failure` / `RestartOnFailure`
+so the server survives crashes, and start at login/boot automatically.
+
 ## License
 
 MIT