@rainmanhhh/pi-web 0.8.7

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 agegr
+Copyright (c) 2026 rainmanhhh
+
+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.md

@@ -0,0 +1,147 @@
+# Pi Web
+
+[中文文档](./README.zh-CN.md)
+
+Local web UI for the [pi coding agent](https://github.com/earendil-works/pi) (core npm package [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai)). Pi Web reads your local pi session files and gives you a browser workspace for session browsing, real-time chat, model configuration, skill management, and project file preview.
+
+This project is a fork of [@agegr/pi-web](https://github.com/agegr/pi-web).
+
+The same pi session in CLI and Pi Web: structured tool calls, readable Markdown, session browsing, and cleaner results.
+
+## Quick Start
+
+Pi Web requires Node.js 22.19.0 or newer. Check your version with `node --version`.
+
+**Run without installing:**
+
+```bash
+npx @rainmanhhh/pi-web@latest
+```
+
+**Or install globally:**
+
+```bash
+npm install -g @rainmanhhh/pi-web  # 或 bun add -g @rainmanhhh/pi-web
+pi-web
+```
+
+The packaged server listens on `http://127.0.0.1:3142` by default and binds `127.0.0.1`. It serves the API and the built frontend from one process; add `--open` to open the browser automatically once it is ready.
+
+**Options:**
+
+```bash
+pi-web --port 8080              # custom port
+pi-web --hostname 0.0.0.0       # expose on a trusted network
+pi-web -p 8080 -H 0.0.0.0       # combine options
+pi-web --open                   # open the browser when the server is ready
+pi-web --agent-dir ~/.pi/agent  # point at another pi agent directory
+
+PORT=8080 pi-web                # environment variable is also supported
+HOST=0.0.0.0 pi-web             # explicit network exposure
+PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web  # allow an exact proxy/custom hostname
+PI_WEB_PASSWORD='a-long-random-password' pi-web  # require Basic Auth (username: pi)
+```
+
+Set `PI_WEB_PASSWORD` to protect the web interface and every API endpoint with HTTP Basic Auth. The username is always `pi`. Leaving the variable unset or empty disables authentication.
+
+Pi Web can invoke a high-privilege agent. Basic Auth does not encrypt the password in transit, so do not expose plain HTTP to the internet. Use HTTPS through a trusted reverse proxy or a trusted VPN for remote access.
+API requests accept loopback names, IP literals, and exact comma-separated names in `PI_WEB_ALLOWED_HOSTS`. Configure that variable when a trusted reverse proxy uses a different external hostname. `PI_WEB_HOSTNAME` is a legacy alias for the same allow-list — it does **not** control the bind address (use `HOST` for that).
+
+## HTTP Proxy
+
+Pi Web reads the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables for server-side model and API requests.
+
+On macOS or Linux:
+
+```bash
+HTTP_PROXY=http://127.0.0.1:7890 \
+HTTPS_PROXY=http://127.0.0.1:7890 \
+NO_PROXY=localhost,127.0.0.1 \
+npx @rainmanhhh/pi-web@latest
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:HTTP_PROXY = "http://127.0.0.1:7890"
+$env:HTTPS_PROXY = "http://127.0.0.1:7890"
+$env:NO_PROXY = "localhost,127.0.0.1"
+npx @rainmanhhh/pi-web@latest
+```
+
+## Features
+
+- **Pick work back up**: browse previous pi conversations by project without digging through terminal history or session paths.
+- **Try different directions safely**: continue from an earlier message or fork a session into a separate route.
+- **Work across branches**: switch Git worktrees from the sidebar so new sessions and the Explorer follow the checkout you choose.
+- **Chat beside the project**: browse files on the left and preview source, docs, images, audio, and PDFs on the right while the agent works.
+- **See session state clearly**: context usage, cost, compaction state, and system prompt details are visible from the top bar.
+- **Configure less from the terminal**: manage models, login/API keys, model tests, and skill switches from the web UI.
+- **Use the interface in your language**: switch between the supported UI languages from the top bar.
+
+## Notes
+
+- **Data directory**: Pi Web reads `~/.pi/agent/sessions` by default. Set `PI_CODING_AGENT_DIR` to point at another pi agent directory.
+- **Session files**: files are stored as `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`.
+- **Model config**: the Models panel reads and writes `models.json` in the pi agent directory. Model lists and defaults come from pi's config.
+- **Preferences**: UI preferences (scroll step, auto-reload, long-block collapse, …) live in `pi-web-preferences.json` in the pi agent directory (default `~/.pi/agent/pi-web-preferences.json`). The browser's `localStorage` holds a front-end copy; the server file is the source of truth for other clients.
+- **File access**: file browsing and preview are scoped to the selected project directory and working directories that appear in sessions.
+- **Git worktrees**: see [Worktrees in Pi Web](./docs/worktrees.md) for when the switcher appears, how new worktrees are created, and what removal does.
+- **Forks vs in-session branches**: Fork creates a new `.jsonl` file. "Edit from here" creates another branch inside the same session file.
+- **Internationalization**: see [Internationalization](./docs/i18n.md) for using translations and adding languages or UI text.
+
+## Development
+
+Requires [Bun](https://bun.sh) and Node.js 22.19.0+.
+
+```bash
+bun install
+```
+
+Run the API server and the Vite dev server in two terminals:
+
+```bash
+bun run api     # Hono API server on http://127.0.0.1:30002
+bun run dev     # Vite dev server on http://127.0.0.1:30001 (proxies /api → :30002)
+```
+
+Open [http://127.0.0.1:30001](http://127.0.0.1:30001). The dev proxy target defaults to `30002`; override it with `VITE_API_PORT` if your API server runs elsewhere.
+
+Common checks:
+
+```bash
+bun run check        # tsc --noEmit
+bun run lint
+bun run test:unit
+bun run test:e2e   # Playwright; e2e uses isolated ports (E2E_API_PORT etc.)
+```
+
+Avoid running `bun run build` during local development. It writes to `dist/` and can interfere with the dev server; leave builds for release work.
+
+Other scripts: `bun run check` (tsc --noEmit), `bun run format` (biome), `bun run build:server` (bundle the API for Node), `bun run api:node` (run the bundled server), `bun run e2e:stop` (kill leftover e2e processes). Publish with `pnpm publish` (use `pnpm publish --dry-run` to preview the pack) — `prepublishOnly` runs check + builds both the frontend and the server bundle first, and `publishConfig.access` makes the scoped package public.
+
+Known issue: `bun publish` does not read the `//registry.npmjs.org/:_authToken` from `.npmrc`/`~/.npmrc` (loginless publish config) and fails with `error: missing authentication (run bunx npm login)` — use `pnpm publish` instead, which reads the token.
+
+## Project Structure
+
+```text
+src/
+  components/   # React UI: AppShell, SessionSidebar, ChatWindow, ChatInput,
+                #   MessageView, ModelsConfig, SkillsConfig, FileExplorer, FileViewer, …
+  hooks/        # useAgentSession (SSE state machine), useTheme, useDragDrop, …
+  lib/          # session .jsonl parsing, RPC manager, file-access safety,
+                #   request security, i18n, markdown setup
+  main.tsx      # frontend entry
+server/
+  main.ts       # API entry + pi-web CLI (Bun or Node, honors PORT/HOST,
+                #   --port/--hostname/--open/--agent-dir)
+  index.ts      # Hono app wiring
+  routes/       # API handlers: agent, auth, cwd, files, git, models,
+                #   sessions, skills, worktrees, preferences, project-trust, …
+  static.ts     # serves dist/static in production (single-process mode)
+  mount.ts      # Next-style route-module adapter for Hono
+scripts/        # e2e-stop, cdp-capture helpers
+tests/e2e/      # Playwright specs and fixtures
+vite.config.ts        # dev server (:30001), /api proxy → :30002, build outDir
+playwright.config.ts  # e2e webServers (API + Vite) on isolated ports
+```

package/README.zh-CN.md

@@ -0,0 +1,145 @@
+# Pi Web
+
+[English](./README.md)
+
+[pi 编程智能体](https://github.com/earendil-works/pi)（核心 npm 包 [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai)）的本地网页界面。它会读取本机的 pi 会话文件，在浏览器里提供会话管理、实时对话、模型配置、技能管理和项目文件预览。
+
+本项目是 [@agegr/pi-web](https://github.com/agegr/pi-web) 的 fork。
+
+## 快速开始
+
+Pi Web 要求 Node.js 22.19.0 或更高版本。可通过 `node --version` 检查当前版本。
+
+**无需安装，直接运行：**
+
+```bash
+npx @rainmanhhh/pi-web@latest
+```
+
+**或全局安装后使用：**
+
+```bash
+npm install -g @rainmanhhh/pi-web
+pi-web
+```
+
+发布版服务默认监听 `http://127.0.0.1:3142` 并绑定 `127.0.0.1`，单进程同时提供 API 和构建后的前端；加 `--open` 可在服务就绪后自动打开浏览器。
+
+**可选参数：**
+
+```bash
+pi-web --port 8080              # 自定义端口
+pi-web --hostname 0.0.0.0       # 在可信网络中开放访问
+pi-web -p 8080 -H 0.0.0.0       # 组合使用
+pi-web --open                   # 服务就绪后自动打开浏览器
+pi-web --agent-dir ~/.pi/agent  # 指定其他 pi agent 目录
+
+PORT=8080 pi-web                # 也支持环境变量
+HOST=0.0.0.0 pi-web             # 显式开放网络访问
+PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web  # 允许指定的代理或自定义主机名
+PI_WEB_PASSWORD='足够长的随机密码' pi-web  # 启用 Basic Auth（用户名固定为 pi）
+```
+
+设置 `PI_WEB_PASSWORD` 后，网页和所有 API 端点都会启用 HTTP Basic Auth，用户名固定为 `pi`。未设置或设置为空值时不启用认证。
+
+Pi Web 可以调用高权限智能体。Basic Auth 不会加密传输中的密码，因此不要把明文 HTTP 暴露到互联网。远程访问时应使用可信反向代理提供 HTTPS，或通过可信 VPN 访问。
+API 请求仅接受 loopback 名称、IP 字面量，以及 `PI_WEB_ALLOWED_HOSTS` 中以逗号分隔的精确主机名。可信反向代理使用不同的外部主机名时，请配置该变量。`PI_WEB_HOSTNAME` 是该白名单的旧别名，**不**控制监听地址（绑定地址请用 `HOST`）。
+
+## HTTP 代理
+
+Pi Web 的服务端模型请求和 API 请求会读取标准的 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY` 环境变量。
+
+macOS 或 Linux：
+
+```bash
+HTTP_PROXY=http://127.0.0.1:7890 \
+HTTPS_PROXY=http://127.0.0.1:7890 \
+NO_PROXY=localhost,127.0.0.1 \
+npx @rainmanhhh/pi-web@latest
+```
+
+Windows PowerShell：
+
+```powershell
+$env:HTTP_PROXY = "http://127.0.0.1:7890"
+$env:HTTPS_PROXY = "http://127.0.0.1:7890"
+$env:NO_PROXY = "localhost,127.0.0.1"
+npx @rainmanhhh/pi-web@latest
+```
+
+## 功能介绍
+
+- **把历史工作接回来**：打开网页就能按项目找到以前的 pi 对话，不必在终端里翻文件或记住会话路径。
+- **放心试不同方向**：可以从某条历史消息重新开始，也可以复制出一条独立的新路线，探索方案时不怕弄乱原来的对话。
+- **跨分支工作**：在侧边栏切换 Git worktree，让新会话和 Explorer 跟随你选择的 checkout。
+- **边聊边看项目文件**：左侧浏览项目文件，右侧打开源码、文档、图片、音频和 PDF；文件变化会自动刷新，适合边让 agent 改边检查结果。
+- **随时掌握会话状态**：在顶部就能看到上下文占用、花费、压缩结果和系统提示，长会话不再像黑箱。
+- **少离开当前界面**：模型、登录/API key、模型测试和技能开关都能在网页里处理，配置 agent 时不用在多个工具之间来回切换。
+- **界面语言可选**：在顶部栏切换界面支持的 UI 语言。
+
+## 注意事项
+
+- **数据目录**：默认读取 `~/.pi/agent/sessions` 下的会话文件。可通过环境变量 `PI_CODING_AGENT_DIR` 指定其他 pi agent 目录。
+- **会话文件**：路径形如 `~/.pi/agent/sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl`。
+- **模型配置**：Models 面板读写 pi agent 目录下的 `models.json`，模型列表和默认模型由 pi 的配置解析得到。
+- **偏好配置**：UI 偏好（滚动步长、自动刷新、长块折叠等）保存在 pi agent 目录下的 `pi-web-preferences.json`（默认 `~/.pi/agent/pi-web-preferences.json`）。浏览器 `localStorage` 是前端副本，服务端文件是其他客户端读取的权威来源。
+- **文件访问**：文件浏览和预览面向当前选择的项目目录，以及会话中已出现过的工作目录。
+- **Git worktree**：什么时候显示切换器、新建目录在哪里、删除会影响什么，见 [Pi Web 里的 Worktree](./docs/worktrees.zh-CN.md)。
+- **Fork 与会话内分支不同**：Fork 会创建新的 `.jsonl` 文件；“Edit from here” 是同一会话文件里的分支。
+- **国际化**：翻译使用与新增语言/UI 文案的方法见 [Internationalization](./docs/i18n.md)。
+
+## 开发
+
+需要 [Bun](https://bun.sh) 和 Node.js 22.19.0+。
+
+```bash
+bun install
+```
+
+两个终端分别跑 API 服务和 Vite dev server：
+
+```bash
+bun run api     # Hono API 服务，http://127.0.0.1:30002
+bun run dev     # Vite dev server，http://127.0.0.1:30001（/api 代理到 :30002）
+```
+
+打开 [http://127.0.0.1:30001](http://127.0.0.1:30001)。dev 代理目标默认 `30002`，API 跑在其他端口时用 `VITE_API_PORT` 覆盖。
+
+常用检查：
+
+```bash
+node_modules/.bin/tsc --noEmit
+bun run lint
+bun run test:unit
+bun run test:e2e   # Playwright；e2e 使用隔离端口（E2E_API_PORT 等）
+```
+
+开发时不要运行 `bun run build`,它会写入 `dist/`,容易影响正在运行的 dev server。发布流程再执行构建。
+
+其他脚本：`bun run check`（tsc --noEmit）、`bun run format`（biome）、`bun run build:server`（打包 API 供 Node 运行）、`bun run api:node`（运行打包后的服务）、`bun run e2e:stop`（清理残留 e2e 进程）。发布用 `pnpm publish`（可用 `pnpm publish --dry-run` 预览打包内容）— `prepublishOnly` 会先执行 check 并构建前端和服务端 bundle，`publishConfig.access` 保证 scoped 包公开。
+
+已知问题：`bun publish` 不读取 `.npmrc`/`~/.npmrc` 里的 `//registry.npmjs.org/:_authToken`（无登录发布配置），会报 `error: missing authentication (run bunx npm login)` — 请改用会读取该 token 的 `pnpm publish`。
+
+## 项目结构
+
+```text
+src/
+  components/   # React UI：AppShell、SessionSidebar、ChatWindow、ChatInput、
+                #   MessageView、ModelsConfig、SkillsConfig、FileExplorer、FileViewer 等
+  hooks/        # useAgentSession（SSE 状态机）、useTheme、useDragDrop 等
+  lib/          # 会话 .jsonl 解析、RPC manager、文件访问安全边界、
+                #   请求安全、i18n、markdown 配置
+  main.tsx      # 前端入口
+server/
+  main.ts       # API 入口 + pi-web CLI（Bun 或 Node，支持 PORT/HOST、
+                #   --port/--hostname/--open/--agent-dir）
+  index.ts      # Hono app 装配
+  routes/       # API 处理器：agent、auth、cwd、files、git、models、
+                #   sessions、skills、worktrees、preferences、project-trust 等
+  static.ts     # 生产环境提供 dist/static（单进程模式）
+  mount.ts      # Next 风格路由模块到 Hono 的适配
+scripts/        # e2e-stop、cdp-capture 辅助脚本
+tests/e2e/      # Playwright 测试与 fixtures
+vite.config.ts        # dev server（:30001）、/api 代理 → :30002、build outDir
+playwright.config.ts  # e2e webServer（API + Vite）隔离端口
+```