@rexvane/piweb 0.3.4 → 0.3.6

package/README.md

@@ -14,109 +14,84 @@
 
 ---
 
-**PiWeb** brings a sleek, feature-rich browser interface to the [pi coding agent](https://github.com/earendil-works/pi) with zero modifications to the core Pi engine. Built with Next.js and Tailwind CSS.
+**PiWeb** brings a sleek, feature-rich browser interface to the [pi coding agent](https://github.com/earendil-works/pi) with zero modifications to the core Pi engine. Install with one command, and all your existing pi configuration, sessions, models, skills, and plugins work out of the box.
 
-## Key Features
+## Features
 
-- **Real-Time Streaming**: Full SSE snapshots with ordered deltas, automatic replay via `Last-Event-ID`, real-time thinking process and inline tool execution cards.
-- **Composer & Input**: Image attachments (paste, pick, drag-and-drop), 2-level model selector, model cycling forward/backward, queue management (steering / follow-up), and `/` slash commands.
-- **Decoupled Workspaces & Sessions**: Group sessions by workspace folders, native system folder picker on Windows, rename/delete workspaces with centered confirmation modals, preserve sessions under "Ungrouped", and maintain empty workspaces independently.
-- **Session Exploration**: Session tree branch visualization & navigation, user message draft recovery, export session logs to JSONL / HTML, and trajectory views.
-- **Comprehensive Settings**:
-  - **General**: Tool presets (Read Only / Workspace Write / Full Access), language (zh/en), appearance, enter key behaviors, and auto-compact.
-  - **Models**: Manage 30+ built-in providers, custom providers in `models.json`, and OAuth logins (Claude, Codex, Copilot, etc.).
-  - **Plugins & Skills**: View and manage extensions and skills directly via Pi's built-in package manager.
-- **Security & Sandboxing**: Optional HTTP Basic Auth via `PI_WEB_PASSWORD`, origin validation on write actions, and strict path boundary checks.
+### Real-Time Streaming Chat
 
-## Quick Start
+Full SSE snapshots with ordered deltas and automatic replay via `Last-Event-ID`. The thinking process and inline tool execution cards stream live.
 
-**Prerequisites**: Node.js ≥ 22.19.0 (Node.js 24 recommended) and Git for repository and growth-history features.
+<p align="center"><img src="assets/showcase.png" alt="Streaming chat with tool cards" width="840" /></p>
 
-### Install from npm (recommended)
+### Workspaces & Sessions
 
-```bash
-npm install -g @rexvane/piweb
-piweb
-```
+Sessions grouped by project folder, with a native folder picker (Windows / macOS / Linux), rename and archive. Session tree branches, draft recovery, and JSONL / HTML export.
 
-A global install prepares the production bundle once (during install, or on the first run if the script was skipped) and then starts in production mode. If that build fails, `piweb` reports it instead of falling back to a development server that cannot work without dev dependencies; retry with `npm rebuild -g @rexvane/piweb`. The package registers only the `piweb` command, so it never conflicts with the official `pi` CLI (`npm i -g @earendil-works/pi-coding-agent`) if you have both.
+### Project Growth Tree
 
-### Inside this repository
+Every step the agent takes on your codebase is snapshotted: navigate the timeline round by round, see added/modified/deleted files, and open line-level diffs for any file at any step — even if the workspace has no git history of its own.
 
-```bash
-npm install
-npm run dev        # development server with hot reload
-```
+### Context Meter
 
-Or run a production build locally:
+Click the ring next to the composer to see the context window broken down into 13 segments — System Prompt, System/Custom Tools, Memory (AGENTS.md), Skills, messages by type, Compacted Data, Auto-Compact Buffer, and Free Space.
 
-```bash
-npm install
-npm run build      # or: npm run build:release (staged, does not touch a running build)
-npm start          # serves on http://127.0.0.1:30141 (auto-increments if busy)
-```
+### Model & Provider Management
 
-### CLI Options (`bin/piweb.js`)
+30+ built-in providers, OAuth logins (Claude, Codex, Copilot, etc.), custom providers written to `models.json`, one-click model discovery, and a placeholder key auto-filled for local gateways like Ollama.
 
-```
--p, --port <port>      Listen port (default 30141, env PORT; auto-increments if in use)
--H, --hostname <host>  Bind address (default 127.0.0.1, env PI_WEB_HOSTNAME)
---dev                  Start in development mode (`next dev`; env PI_WEB_DEV=1; also used when no production build exists)
---no-open              Do not automatically open browser (env PI_WEB_NO_OPEN=1)
--h, --help             Show help
-```
+### Plugins & Skills
+
+Install, update, and uninstall pi packages directly from the UI. Enable/disable or delete skills; every change applies to running sessions immediately.
 
-Environment variables: `PI_WEB_PASSWORD` enables a browser login session and HTTP Basic Auth for API clients (user `pi`). It is **required** for any non-loopback production bind address. Development mode is loopback-only, even with a password; if no production build exists, an external bind fails rather than falling back to an exposed development server. Use HTTPS or a trusted VPN for remote access. `PI_WEB_EDITOR` overrides the editor used by "open in editor" (default `code`). Without a password, PiWeb only accepts requests whose `Host` is loopback.
+### Security
 
-`GET /api/health` exposes only a fixed service identifier for credential-free startup probes. Runtime versions are available from the authenticated `/api/version` endpoint. Tool presets limit the tools offered to the agent; they are not an operating-system sandbox, and installed extensions run with the server process's permissions.
+Optional login via `PI_WEB_PASSWORD` (required for non-loopback binds), origin validation on write actions, strict path boundary checks, and tool presets (Read Only / Workspace Write / Full Access).
 
-Model catalog discovery blocks loopback, private, and reserved network addresses by default. If you intentionally use a local model gateway, set `PI_WEB_ALLOW_PRIVATE_MODEL_DISCOVERY=1` before starting PiWeb. This relaxes the discovery endpoint only; use it only on a trusted PiWeb instance.
+## Usage
 
-### Development
+### Install
 
 ```bash
-npm run dev        # Run Next.js in development mode
-npm run typecheck  # TypeScript check
-npm test           # Service, protocol and component regressions
-npm run check      # Full check (types + tests + build)
-npm run build:release # Validate and stage a production build without replacing the running build
+npm install -g @rexvane/piweb
+piweb
 ```
 
-## Status and known limitations (2026-09-14)
-
-The audit follow-up is merged into this branch and has been through an isolated release plus a local production deployment. It covers the production login build, upload integrity through the Next.js proxy, per-session extension isolation and tool-policy reloads, lossless model/settings writes, composer and pending-extension-UI lifecycle, Git/Growth/diff correctness, and isolated release preparation.
+The package registers only the `piweb` command, so it never conflicts with the official `pi` CLI. Requires Node.js ≥ 22.19.0 (24 recommended); Git is needed for growth-history features.
 
-The latest local validation passed TypeScript checking, **355 tests across 52 files** (one additional test skipped), `npm run build`, and `git diff --check`. The skipped test requires Windows symlink privileges or Developer Mode.
+### Update
 
-Known limitations: saving the model configuration normalizes it to plain JSON (comments are not preserved, data is); updates replace dependencies in place during a maintenance window rather than being zero-downtime; a custom tool allowlist lives only for the session lifetime; third-party extension module globals are not isolated.
+```bash
+npm update -g @rexvane/piweb
+```
 
-## Production builds and updates
+Or install a specific version: `npm install -g @rexvane/piweb@0.3.4`.
 
-Use `npm run build:release` when preparing a build while PiWeb is running. It validates types and tests, builds into a fresh `.next-releases/<id>` directory, and only then publishes the build selection for the next start. It does not restart the server or replace the output used by an existing process. `npm start` uses the last successfully prepared release; after a failed or interrupted release attempt it reports the problem instead of silently serving a stale build. Correct the error and run `npm run build:release` again to recover.
+### Uninstall
 
-The in-app updater uses the same validation path. Source files and npm dependencies are still updated in the installation directory, so perform updates during a maintenance window with no running agent turns. This is not a fully isolated zero-downtime deployment system. Restart PiWeb manually after a successful update; running processes do not automatically switch to the new build.
+```bash
+npm uninstall -g @rexvane/piweb
+```
 
-CI runs the full checks on Linux and Windows with Node.js 22.19.0 and 24. Ordinary `npm run build` still uses `.next`, so do not run it against an installation whose active production process is using that directory.
+This removes PiWeb only — your pi data lives in `~/.pi/agent/` and is left untouched.
 
-## Architecture
+### Run
 
+```bash
+piweb                    # http://127.0.0.1:30141 (auto-increments if busy)
+piweb -p 30143 --no-open # custom port, don't open the browser
+piweb -H 0.0.0.0         # LAN access (requires PI_WEB_PASSWORD)
 ```
-Browser (React 19 + Tailwind, src/components)
-   │  REST commands (POST /api/agent/[id]) + SSE streams (GET /api/agent/[id]/events)
-   ▼
-Next.js Server (src/app/api, src/lib)
-   ├─ agent-manager    AgentSession pool: lazy startup, event translation, idle eviction
-   ├─ session-reader   Direct read ~/.pi/agent/sessions/**.jsonl (cold render without running agent)
-   ├─ trajectory       Trajectory ledger + server-side timing (TTFT / decode)
-   ├─ skills/prompts   Skills & Prompt template discovery + frontmatter toggles
-   ├─ models-service   Model catalogue, auth, OAuth bridge & models.json
-   ├─ security-service Tool presets & project trust
-   ├─ plugins-service  Pi package management (DefaultPackageManager) & extension registry
-   ├─ workspace-store  Persistent workspaces registry & native folder picker
-   ▼
-@earendil-works/pi-coding-agent  (Official Pi SDK, zero engine modifications)
-```
+
+| Option | Description |
+| --- | --- |
+| `-p, --port <port>` | Listen port (default 30141, env `PORT`) |
+| `-H, --hostname <host>` | Bind address (default 127.0.0.1, env `PI_WEB_HOSTNAME`) |
+| `--dev` | Development mode |
+| `--no-open` | Do not auto-open the browser |
+
+Set `PI_WEB_PASSWORD` to enable the login page and HTTP Basic Auth (user `pi`). Remote access over plain HTTP is not recommended; use HTTPS or a trusted VPN.
 
 ## License
 
-[MIT License](LICENSE)
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rexvane/piweb",
-	"version": "0.3.4",
+	"version": "0.3.6",
 	"license": "MIT",
 	"type": "module",
 	"description": "Modern web UI for the pi coding agent, driven by the official pi SDK without modifying pi",

package/scripts/install-build.mjs

@@ -9,6 +9,7 @@
  * Repository checkouts always have dev dependencies and keep `npm run dev`.
  */
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
@@ -65,12 +66,63 @@ export function resolveNextBin(root) {
  * neither compiled nor mapped through the `@/*` path alias. Build in a staging
  * directory outside `node_modules` (same drive, so the dependency links resolve)
  * and copy the finished output back into the package.
+ *
+ * The staging directory must NOT sit inside any `node_modules`: for a global
+ * install like ~/.local/lib/node_modules/@rexvane/piweb, the grandparent IS
+ * node_modules, and Next would exclude the staged sources exactly the same way.
+ * Walk up until we are outside every node_modules segment; give up and use the
+ * system temp dir (cross-device copy is still correct, just slower).
  */
+function stagingParent(root) {
+	// Split on BOTH separators: a win32 Node can see POSIX paths (and vice versa)
+	// when the package is installed through a compatibility layer or the test
+	// suite simulates foreign layouts.
+	const segments = path.dirname(root).split(/[\\/]/).filter(Boolean);
+	// Drop trailing path components while the path still contains a node_modules segment.
+	while (segments.length > 1 && segments.includes("node_modules")) {
+		segments.pop();
+	}
+	const candidate = segments.length ? path.resolve(`/${segments.join(path.sep)}`) : path.sep;
+	try {
+		fs.mkdirSync(candidate, { recursive: true });
+		fs.accessSync(candidate, fs.constants.W_OK);
+		return candidate;
+	} catch {
+		return os.tmpdir();
+	}
+}
+
+/** Staging directory must live outside EVERY node_modules on the way up (Next excludes those paths). */
+export function assertStagingOutsideNodeModules(root) {
+	const parent = stagingParent(root);
+	if (parent.split(/[\\/]/).includes("node_modules")) {
+		throw new Error(`staging parent is inside node_modules: ${parent}`);
+	}
+	return parent;
+}
+
+function linkOrCopyDependencies(root, staging, log) {
+	const target = path.join(root, "node_modules");
+	const linkPath = path.join(staging, "node_modules");
+	// Windows: junction 不需要符号链接权限；跨卷时 junction 也会失败（试回退）。
+	// POSIX（macOS/Linux）: 目录符号链接即可，"junction" 类型会被 libuv 拒绝
+	// （0.3.5 的 Mac 现场：symlinkSync(..., 'junction') 抛 EINVAL）。
+	const type = process.platform === "win32" ? "junction" : "dir";
+	try {
+		fs.symlinkSync(target, linkPath, type);
+		return;
+	} catch {
+		/* fall through to the copy */
+	}
+	// 兜底：符号链接不可用（如无权限）时整份复制依赖。慢但保证构建可解析。
+	log("[piweb] Symlink unavailable; copying dependencies into the staging build (slower)...");
+	fs.cpSync(target, linkPath, { recursive: true, verbatimSymlinks: true });
+}
+
 function buildInStaging(root, nextBin, env, log, warn) {
-	const parent = path.dirname(path.dirname(root));
 	let staging;
 	try {
-		staging = fs.mkdtempSync(path.join(parent, ".piweb-build-"));
+		staging = fs.mkdtempSync(path.join(stagingParent(root), ".piweb-build-"));
 	} catch {
 		staging = fs.mkdtempSync(path.join(os.tmpdir(), "piweb-build-"));
 	}
@@ -83,12 +135,7 @@ function buildInStaging(root, nextBin, env, log, warn) {
 			const from = path.join(root, file);
 			if (fs.existsSync(from)) fs.copyFileSync(from, path.join(staging, file));
 		}
-		try {
-			fs.symlinkSync(path.join(root, "node_modules"), path.join(staging, "node_modules"), "junction");
-		} catch (error) {
-			warn(`[piweb] Could not link dependencies into the staging build: ${error.message}`);
-			return false;
-		}
+		linkOrCopyDependencies(root, staging, log);
 		log(`[piweb] Building in ${staging} ...`);
 		const result = spawnSync(process.execPath, [nextBin, "build", "--webpack"], { cwd: staging, stdio: "inherit", env });
 		const produced = path.join(staging, ".next", "BUILD_ID");
@@ -98,6 +145,8 @@ function buildInStaging(root, nextBin, env, log, warn) {
 		fs.cpSync(path.join(staging, ".next"), target, { recursive: true });
 		return fs.existsSync(path.join(target, "BUILD_ID"));
 	} finally {
+		// 复制兜底时 staging 里是整份 node_modules，必须删掉；rmSync 跟随链接删除
+		// 的是链接本身（Node 14+ 目录符号链接不穿透），真实依赖不受影响。
 		fs.rmSync(staging, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
 	}
 }

package/src/components/AppShell.tsx

@@ -81,7 +81,6 @@ export function AppShell() {
 		setGroupBy,
 		setOrderBy,
 		addWorkspaceByPicker,
-		addWorkspaceByPath,
 		removeWorkspace,
 		refreshModels,
 		sendCommand,
@@ -702,7 +701,6 @@ export function AppShell() {
 							providerNames={providerNames}
 							authByProvider={authByProvider}
 							addWorkspaceByPicker={addWorkspaceByPicker}
-							addWorkspaceByPath={addWorkspaceByPath}
 							heroModel={heroModel}
 							onSelectHeroModel={(provider, id) => {
 								setHeroModel({ provider, id });
@@ -1021,7 +1019,6 @@ function Hero({
 	providerNames,
 	authByProvider,
 	addWorkspaceByPicker,
-	addWorkspaceByPath,
 	heroModel,
 	onSelectHeroModel,
 	defaultModel,
@@ -1048,7 +1045,6 @@ function Hero({
 	providerNames: Record<string, string>;
 	authByProvider: Record<string, boolean>;
 	addWorkspaceByPicker: () => Promise<string | null>;
-	addWorkspaceByPath: (dir: string) => Promise<string | null>;
 	heroModel: { provider: string; id: string } | null;
 	onSelectHeroModel: (provider: string, id: string) => void;
 	defaultModel?: ModelChoice;
@@ -1058,8 +1054,6 @@ function Hero({
 }) {
 	const { t } = useI18n();
 	const [wsMenu, setWsMenu] = useState(false);
-	const [wsPathDraft, setWsPathDraft] = useState("");
-	const [wsPathError, setWsPathError] = useState<string | null>(null);
 	const menuRef = useRef<HTMLDivElement>(null);
 
 	useEffect(() => {
@@ -1081,19 +1075,6 @@ function Hero({
 		}
 	};
 
-	// 手动输入路径添加（原生选择器不可用 / 无桌面环境兜底）
-	const addByPath = async () => {
-		const p = await addWorkspaceByPath(wsPathDraft);
-		if (p) {
-			setWsPathDraft("");
-			setWsPathError(null);
-			setCwd(p);
-			setWsMenu(false);
-		} else {
-			setWsPathError(t.workspacePathInvalid);
-		}
-	};
-
 	const currentLabel = cwd ? (getWorkspaceName ? getWorkspaceName(cwd) : basename(cwd)) : t.startWith;
 
 	return (
@@ -1155,24 +1136,6 @@ function Hero({
 									<IconProjectAddOutline16 size={14} style={{ flex: "none", color: "var(--dsw-label-tertiary)" }} />
 									{t.addWorkspace}
 								</button>
-								<div className="flex items-center gap-1.5 px-2 py-1.5" style={{ fontSize: 12.5 }}>
-									<input
-										className="min-w-0 flex-1 rounded-lg px-2 py-1"
-										style={{ border: "0.5px solid var(--dsw-border-l3)", background: "var(--dsw-input-bg, transparent)", color: "inherit" }}
-										placeholder={t.workspacePathPlaceholder}
-										value={wsPathDraft}
-										onChange={(e) => { setWsPathDraft(e.target.value); setWsPathError(null); }}
-										onKeyDown={(e) => {
-											if (e.key === "Enter") { e.preventDefault(); void addByPath(); }
-										}}
-									/>
-									<button type="button" className="pw-chip" style={{ flex: "none" }} disabled={!wsPathDraft.trim()} onClick={() => void addByPath()}>
-										{t.workspacePathAdd}
-									</button>
-								</div>
-								{wsPathError && (
-									<div className="px-3.5 pb-1.5" style={{ fontSize: 11, color: "var(--dsw-danger)" }}>{wsPathError}</div>
-								)}
 							</div>
 						)}
 					</div>

package/src/hooks/usePiWeb.ts

@@ -496,27 +496,6 @@ export function usePiWeb() {
 		}
 	}, [refreshWorkspaces]);
 
-	/** 手动输入路径添加工作区（原生选择器不可用 / 无桌面环境时的兜底） */
-	const addWorkspaceByPath = useCallback(async (dir: string): Promise<string | null> => {
-		const trimmed = dir.trim().replace(/^["']|["']$/g, "");
-		if (!trimmed) return null;
-		try {
-			const r = await fetch("/api/workspaces", {
-				method: "POST",
-				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify({ action: "add", path: trimmed }),
-			});
-			const j = await r.json();
-			if (!r.ok || !j.success) throw new Error(j.error || `request failed (${r.status})`);
-			setAddedWorkspaces(j.data?.workspaces ?? []);
-			await refreshWorkspaces();
-			return trimmed;
-		} catch (error) {
-			const message = error instanceof Error ? error.message : "failed to add workspace";
-			setState((current) => ({ ...current, error: message }));
-			return null;
-		}
-	}, [refreshWorkspaces]);
 
 	const removeWorkspace = useCallback(
 		async (dir: string) => {
@@ -906,7 +885,6 @@ export function usePiWeb() {
 		setGroupBy,
 		setOrderBy,
 		addWorkspaceByPicker,
-		addWorkspaceByPath,
 		removeWorkspace,
 		refreshModels,
 		sendCommand,

package/src/i18n.tsx

@@ -145,9 +145,6 @@ const zh = {
 	workspaces: "工作区",
 	searchSessions: "搜索会话...",
 	addWorkspace: "添加工作区",
-	workspacePathPlaceholder: "输入路径添加…",
-	workspacePathInvalid: "路径无效或目录不存在",
-	workspacePathAdd: "添加",
 	groupBy: "分组方式",
 	sortBy: "排序方式",
 	byWorkspace: "按工作区",
@@ -678,9 +675,6 @@ const en: Dict = {
 	workspaces: "Workspaces",
 	searchSessions: "Search sessions...",
 	addWorkspace: "Add workspace",
-	workspacePathPlaceholder: "Type a path to add…",
-	workspacePathInvalid: "Invalid path or directory does not exist",
-	workspacePathAdd: "Add",
 	groupBy: "Group by",
 	sortBy: "Sort by",
 	byWorkspace: "Workspace",