copilot-proxy-web 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# CHANGELOG
+
+## Unreleased
+- Architecture: refactor `bin/run-web.js` into service-oriented modules with TDD guardrails (`daemon-service`, `daemon-state`, `cloudflare-service`, `cloudflare-state`, `cloudflare-setup-service`, `cloudflare-setup-deps`, `cloudflare-utils`)
+- Tests: add focused unit tests for refactored modules (`cloudflare-utils`, `cloudflare-state`, `cloudflare-service`, `cloudflare-setup-service`, `cloudflare-setup-deps`, `daemon-service`)
+- CLI behavior: keep `run/start/stop/status/check/cloudflare/wc` user-facing behavior stable while moving logic behind injectable services
+- Cloudflare setup: preflight sections, domain inference, clearer hints, and overwrite guidance for DNS route conflicts
+- Cloudflare status/diagnose: configurable local health check URL/path and improved output details
+- Web UI: display app version in header (via API)
+- API: expose app version in `/api/status` and `X-App-Version` header
+- Web UI/API: interactive shell toggle for sessions (uses login+interactive shell)
+- Conversation API + UI view (JSON snapshot, polling, idle hook)
+- Conversation view: reduce duplicate output when terminal emits repetitive ANSI frames (planned)
+- Conversation view: headless terminal buffer with dirty-row deltas and optional context lines
+- Conversation view: profile selection now explicit (`none` or `copilot`), with `none` as default
+- Conversation view: removed `auto` profile mode to avoid false positives; profile behavior is now deterministic
+- Conversation view: Copilot prompt-block trimming remains profile-scoped (`copilot` only)
+- Conversation view: suppress duplicate spinner-only frames via canonical terminal text de-dup
+- Conversation view: show dirty row range in event meta header (e.g. `rows: 20-23`) for diagnostics
+- Web UI: Send now triggers submit sequence (focus + enter)
+- Web UI: textarea send uses API /keys + double submit to reliably trigger Copilot CLI thinking (WS-only input was flaky)
+- Web UI: support `#conversation` URL hash deep-link and mode sync on toggle/hash change
+- Web UI: new session default name increments as `tab01`, `tab02`, ... with local counter persistence
+- Xterm view: fixed PTY-mode intermittent clipping on refresh by avoiding FitAddon in PTY mode and capping local display rows to visible viewport capacity
+- Xterm view: improved replay/render settling with staged scroll-to-bottom callbacks after large writes
+- Debug tooling: added `enableDebugMode()` / `disableDebugMode()` browser helpers and `cp_debug_xterm` localStorage toggle
+- Debug tooling: added `Copy xterm debug` / `Reset xterm debug` buttons, in-memory log buffer, and clipboard reset support
+- Known issue: xterm view may show duplicate/garbled output after refresh or view toggles (tracking)
+- Packaging/metadata: tighten npm publish files, add description/keywords/engines, and update README install guidance
+- Security: trust `X-Forwarded-For` only when explicitly enabled via `--use-x-forwarded-for` (or `USE_X_FORWARDED_FOR=1`)
+- Security: simplified proxy trust config to a single switch (`--use-x-forwarded-for` / `USE_X_FORWARDED_FOR=1`)
+- Test tooling: added `clean:appledouble` and run it before `test:ui` to avoid Playwright parsing macOS `._*` files
+
+## 1.0.0
+- PTY-backed proxy for Copilot CLI
+- Web UI (xterm.js) with multi-session tabs
+- HTTP API + WebSocket streaming
+- Idle hooks with Markdown pipeline
+- Telegram sink support
+- Auth token for API/WS
+- Cloudflare Tunnel helpers (setup/start/stop/status/check)
+- WSS client via `npx copilot-proxy-web wc`
+- Unit tests for core helpers and CLI

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Copilot Proxy contributors
+
+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.arch.md

@@ -0,0 +1,87 @@
+# Architecture
+
+## Overview
+
+Copilot Proxy runs local PTY sessions and exposes them through Web UI, WebSocket streaming, and an HTTP API.
+
+The codebase is now split into three layers:
+
+- Launcher layer: `bin/run-web.js` (CLI parsing + command dispatch)
+- Runtime layer: `copilot-proxy.js` (session manager + API/WS server + hooks pipeline)
+- Service/helper layer: `lib/*` (daemon/cloudflare services, state stores, adapters, and pure helpers)
+
+## Diagram
+
+```
+User/UI/Client
+  ├─ Web UI (xterm.js)
+  ├─ WebSocket client
+  └─ HTTP API client
+           │
+           ▼
+     copilot-proxy.js
+       ├─ Session Manager
+       │    ├─ Session (default)
+       │    │    └─ PTY (copilot shell)
+       │    └─ Session (s-*)
+       │         └─ PTY (copilot shell)
+       ├─ Hook Registry
+       │    ├─ Markdown pipeline
+       │    └─ Telegram sink
+       └─ Log files (run.log / idle.log)
+
+ CLI (bin/run-web.js)
+   ├─ daemon-service + daemon-state
+   │    └─ run/start/stop/status/check
+   ├─ cloudflare-service + cloudflare-state + cloudflare-utils
+   │    └─ cloudflare start/stop/status/check/diagnose/token
+   └─ cloudflare setup (still in run-web, uses shared helpers)
+```
+
+## Components
+
+- `copilot-proxy.js`: runtime server, session manager, PTY spawn, API/WS wiring, hook pipeline.
+- `bin/run-web.js`: launcher entry; parses CLI flags and routes subcommands.
+- `public/`: Web UI (xterm.js) with session tabs.
+- `lib/daemon-service.js`: background process lifecycle for run/start/stop/status/check.
+- `lib/daemon-state.js`: pid/state file persistence for daemon lifecycle.
+- `lib/cloudflare-service.js`: cloudflare lifecycle checks and status flow.
+- `lib/cloudflare-state.js`: cloudflare pid/state/token persistence.
+- `lib/cloudflare-utils.js`: pure hostname/path/check formatting helpers.
+- `lib/`: other shared helpers (PTY utils, hooks, markdown, telegram, auth, log rotation).
+
+## Dependency direction
+
+- `bin/run-web.js` depends on `lib/*` services/stores/utils.
+- `copilot-proxy.js` depends on API/WS/helper modules under `lib/*`.
+- `lib/*` modules do not depend on `bin/*`.
+- State stores (`daemon-state`, `cloudflare-state`) are filesystem adapters used by services.
+
+## Data flow
+
+1) Web UI / WS client selects a session.
+2) Each session owns a PTY and its own history buffer.
+3) PTY output fan-outs to:
+   - Terminal stdout
+   - `run.log`
+   - WebSocket broadcast (per session)
+   - Idle buffer (per session)
+   - Hook registry (`raw_output`, `thinking_start`, `thinking_end`)
+4) Hooks can forward to:
+   - Markdown pipeline (idle log / markdown output)
+   - Telegram sink (MarkdownV2)
+
+## Auth
+
+- HTTP: `Authorization: Bearer <token>`
+- WebSocket: `Sec-WebSocket-Protocol: auth.<base64url(token)>`
+
+## Session scope
+
+- WebSocket: `ws(s)://host/ws?sessionId=...`
+- HTTP: `/api/sessions/:id/*` or `x-session-id` header or `?sessionId=...`
+- Default session id: `default`
+
+## Cloudflare Tunnel
+
+`cloudflare setup` writes an ingress rule that maps a public hostname (optional path) to a local service target (default: `http://127.0.0.1:<port>`).

package/README.md

@@ -0,0 +1,295 @@
+# Copilot Proxy
+
+NPM package: `copilot-proxy-web`.
+
+Proxy GitHub Copilot CLI through a PTY with a Web UI, WebSocket streaming, and an HTTP API, plus an idle-based output hook pipeline.
+
+## Screenshots
+
+![Web UI - Index 01](https://raw.githubusercontent.com/changyy/copilot-proxy-web/main/resource/screenshots/index-01.png)
+![Web UI - Index 02](https://raw.githubusercontent.com/changyy/copilot-proxy-web/main/resource/screenshots/index-02.png)
+
+## Quickstart
+
+Install:
+
+```bash
+npm i -g copilot-proxy-web
+```
+
+Run Web UI + API:
+
+```bash
+npx copilot-proxy-web run
+```
+
+Recommended run modes:
+
+```bash
+# Local/default (do not trust proxy headers)
+npx copilot-proxy-web run --web --auth-token YOUR_TOKEN
+
+# Behind a trusted reverse proxy (Cloudflare, etc.)
+npx copilot-proxy-web run --web --auth-token YOUR_TOKEN --use-x-forwarded-for
+```
+
+For local development:
+
+```bash
+npm install
+```
+
+Background mode:
+
+```bash
+npx copilot-proxy-web start
+npx copilot-proxy-web status
+npx copilot-proxy-web check
+npx copilot-proxy-web stop
+```
+
+Trusted reverse proxy mode:
+
+```bash
+npx copilot-proxy-web start --auth-token YOUR_TOKEN --use-x-forwarded-for
+```
+
+Open Web UI:
+
+```
+http://localhost:3000
+```
+
+Create a session in the Web UI and set the command to run, for example:
+
+```
+copilot --model gpt-5-mini
+```
+
+The session modal includes an "Interactive shell" toggle (default on). When enabled, commands run via a login+interactive shell (`-lic`).
+
+## CLI
+
+Primary commands:
+
+```bash
+npx copilot-proxy-web run
+npx copilot-proxy-web start
+npx copilot-proxy-web stop
+npx copilot-proxy-web status
+npx copilot-proxy-web check
+npx copilot-proxy-web wc --url ws://127.0.0.1:3000/ws --sessionId default
+npx copilot-proxy-web cloudflare setup --hostname proxy.example.com
+```
+
+## WebSocket client (wc)
+
+Basic:
+
+```bash
+npx copilot-proxy-web wc --url ws://127.0.0.1:3000/ws --sessionId default
+```
+
+With AUTH_TOKEN:
+
+```bash
+AUTH_TOKEN=YOUR_TOKEN npx copilot-proxy-web wc --url wss://proxy.example.com/ws --sessionId default
+```
+
+With Cloudflare Access (Service Token):
+
+```bash
+npx copilot-proxy-web wc \
+  --url wss://proxy.example.com/ws \
+  --sessionId default \
+  --token YOUR_TOKEN \
+  --cf-access-id YOUR_ACCESS_ID \
+  --cf-access-secret YOUR_ACCESS_SECRET
+```
+
+Custom headers / Origin:
+
+```bash
+npx copilot-proxy-web wc --url wss://ws.ptt.cc:443/bbs \
+  --origin https://term.ptt.cc \
+  --header "User-Agent: my-client/1.0"
+```
+
+## Cloudflare Zero Trust (Tunnel)
+
+Setup (DNS route is created by `cloudflared`):
+
+```bash
+npx copilot-proxy-web cloudflare setup --hostname proxy.example.com
+```
+
+During setup, the CLI prints a preflight report (DNS route, tunnel, credentials/token).
+
+Optional overrides:
+
+```bash
+npx copilot-proxy-web cloudflare setup \
+  --hostname proxy.example.com \
+  --domain example.com \
+  --tunnel-name copilot-proxy-web \
+  --port 3000 \
+  --service http
+```
+
+`--domain` is optional but recommended. It prevents mismatched zones and allows short hostnames. If omitted, it is auto-inferred from the last two labels of `--hostname` (e.g. `a.b.c.d` -> `c.d`):
+
+```bash
+npx copilot-proxy-web cloudflare setup --hostname office --domain ainfo.me
+```
+
+You can also pin a longer zone explicitly:
+
+```bash
+npx copilot-proxy-web cloudflare setup --hostname a.b.c.d --domain b.c.d
+```
+
+Or set a full service target (including path):
+
+```bash
+npx copilot-proxy-web cloudflare setup \
+  --hostname proxy.example.com \
+  --service-url https://127.0.0.1:3000/
+```
+
+Match a path on the public hostname:
+
+```bash
+npx copilot-proxy-web cloudflare setup \
+  --hostname proxy.example.com \
+  --path /path01 \
+  --service-url http://127.0.0.1:3000/path02
+```
+
+This maps `https://proxy.example.com/path01` to `http://127.0.0.1:3000/path02`.
+
+Start/stop/status/check:
+
+```bash
+npx copilot-proxy-web cloudflare start
+npx copilot-proxy-web cloudflare status
+npx copilot-proxy-web cloudflare check
+npx copilot-proxy-web cloudflare diagnose
+npx copilot-proxy-web cloudflare stop
+```
+
+Token mode (optional):
+
+```bash
+npx copilot-proxy-web cloudflare token set --token <TOKEN>
+npx copilot-proxy-web cloudflare token get
+npx copilot-proxy-web cloudflare token clear
+```
+
+## API
+
+Status:
+
+```bash
+curl http://localhost:3000/api/status
+```
+
+Send text:
+
+```bash
+curl -X POST http://localhost:3000/api/send \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"hello", "submit": true}'
+```
+
+Sessions:
+
+```bash
+curl -X POST http://localhost:3000/api/sessions \
+  -H 'Content-Type: application/json' \
+  -d '{"id":"s1", "autoStart": false}'
+
+curl -X POST http://localhost:3000/api/sessions/s1/start \
+  -H 'Content-Type: application/json' \
+  -d '{"command":"copilot --model gpt-5-mini"}'
+
+curl http://localhost:3000/api/sessions
+```
+
+Conversation (JSON):
+
+```bash
+curl http://localhost:3000/api/sessions/s1/conversation
+```
+
+Conversation rendering (server-side):
+
+- `CONVERSATION_CONTEXT` (default: 1) adds surrounding lines when emitting terminal deltas.
+- `CONVERSATION_PROFILE` (default: none) enables optional profile-specific filtering.
+- `--conversation-profile copilot|none` overrides profile per session start.
+
+Web UI deep link:
+
+- `http://localhost:3000/?sessionId=tab1#conversation` opens directly in Conversation view.
+
+## Auth (Token)
+
+Enable auth by providing a token (CLI or env). API requests must include:
+
+```
+Authorization: Bearer YOUR_TOKEN
+```
+
+CLI:
+
+```bash
+node copilot-proxy.js --auth-token YOUR_TOKEN --web --port 3000 --shell -- copilot
+```
+
+WebSocket auth uses `Sec-WebSocket-Protocol`:
+
+```
+auth.<base64url(token)>
+```
+
+## Security notes
+
+- Always set `AUTH_TOKEN` when binding to a non-loopback host.
+- `X-Forwarded-For` is ignored by default. Enable `--use-x-forwarded-for` (or `USE_X_FORWARDED_FOR=1`) only when running behind a trusted reverse proxy.
+- Web UI stores the token in `sessionStorage`; avoid logging in on shared or untrusted devices.
+- PTY input/output logs and idle hooks may contain sensitive content; protect or disable logging if needed.
+- Cloudflare tunnel credentials and tokens are stored under `~/.cloudflared` and `~/.copilot-proxy-web/cloudflare`. Treat them as secrets.
+
+## TODO
+
+- Conversation: reduce duplicate terminal output in conversation view.
+
+## Logs
+
+- Runtime output log follows `--log` (default: `run.log`).
+- Access ledger is written to `access.log` under the same log directory.
+- Access entries are JSON lines and include `type`, `ip`, `path`, `status`, `auth`, and timestamp.
+- `ACCESS_LOG_MODE` controls verbosity:
+- `auth` (default): only auth failures/blocks on `/api/*` (plus HTTP 5xx).
+- `all`: log all API/WS access events.
+- `off`: disable `access.log`.
+
+## Web UI notes
+
+- When `--no-default-session` is used, Web UI starts with no tabs and prompts to create a session.
+- Session tabs show running/stopped and allow start for stopped sessions.
+
+## Tests
+
+```bash
+npm test
+npm run test:ui
+npx playwright install
+```
+
+## Code layout
+
+- `copilot-proxy.js` main runtime
+- `bin/run-web.js` CLI entry
+- `public/` Web UI
+- `lib/` shared helpers
+- `test/` unit tests