@colinxu/pi-web-classic 0.0.0-stage → 0.12.3

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 agegr
+Copyright (c) 2026 colinxu (fork: @colinxu/pi-web)
+
+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

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+# Pi Web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文文档](./docs/README.zh-CN.md) | [日本語](./docs/README.ja.md) | [Русский](./docs/README.ru.md)
+
+Local browser UI for the [pi coding agent](https://github.com/earendil-works/pi). Pi Web uses the same local configuration and session files as pi, so you can browse and resume conversations, run agent turns, configure models and resources, and inspect project files from a browser.
+
+> **Fork notice.** This is `@colinxu/pi-web-classic`, a fork of [agegr/pi-web](https://github.com/agegr/pi-web). The global command is `pwc`, so it can be installed alongside the original. MIT licensed; see [LICENSE](./LICENSE).
+
+**[Try the interactive demo →](https://agegr.github.io/pi-web/)** The real Pi Web UI runs entirely in your browser, with sample sessions, files and models. There is nothing to install; replies are pre-written and no model is called.
+
+![Pi Web displaying a pi session with structured Markdown, tool calls, and project navigation](https://raw.githubusercontent.com/xuzhonglin/pi-web/main/docs/screenshot2.png)
+
+## Features
+
+- **Session workspace**: browse, resume, rename, export, and delete conversations grouped by project, with running state, context usage, cost, and compaction details.
+- **Two ways to branch**: **New session** creates an independent session file from an earlier message; **Edit from here** creates a branch inside the current session.
+- **Project file tools**: browse and upload files, inspect Git diffs, and preview source, Markdown, images, audio, PDFs, and DOCX files with automatic refresh.
+- **Git worktrees**: switch checkouts from the sidebar while keeping sessions from the same repository grouped together.
+- **Web-based configuration**: manage provider login and API keys, models, model tests, plugin packages, and skills without leaving Pi Web.
+- **English, Simplified Chinese, and Traditional Chinese UI**: Pi Web follows the browser language initially and provides a language switcher in the top bar.
+
+## Quick Start
+
+Pi Web requires Node.js 22.19.0 or newer. Check your version with `node --version`, then run:
+
+```bash
+npx @colinxu/pi-web-classic@latest
+```
+
+The CLI opens a browser after the server is ready. If it does not, open [http://127.0.0.1:30141](http://127.0.0.1:30141). Pi Web listens only on `127.0.0.1` by default.
+
+If no model provider is configured yet, open the **Models** panel to sign in or add an API key.
+
+To install the `pwc` command globally:
+
+```bash
+npm install -g @colinxu/pi-web-classic@latest
+pwc
+```
+
+Commands:
+
+```bash
+pwc version          # print the installed version
+pwc status           # list running servers
+pwc stop [--port N]  # stop a running server
+pwc open [--port N]  # open a running server in the browser
+pwc update [--check] # update a global npm install
+```
+
+To update, run `pwc stop`, then `pwc update` (or run the same install command again). To uninstall, run `npm uninstall -g @colinxu/pi-web-classic`.
+
+## Configuration
+
+For port and hostname, command-line options override the corresponding environment variables. Either `--no-open` or `PI_WEB_NO_OPEN=1` disables automatic browser opening. Run `pwc --help` (or `-h`) to print startup options and exit without starting the server. Unknown options exit with an error.
+
+| Option or environment variable | Purpose | Default |
+| --- | --- | --- |
+| `--help`, `-h` | Print startup options and exit | — |
+| `--port <port>`, `-p <port>`, or `PORT` | Server port | `30141` |
+| `--hostname <host>`, `-H <host>`, or `PI_WEB_HOSTNAME` | Bind hostname | `127.0.0.1` |
+| `--no-open` or `PI_WEB_NO_OPEN=1` | Do not open a browser automatically | Browser opens |
+| `PI_WEB_APP_NAME` | PWA manifest `name` and `short_name`; surrounding whitespace is trimmed, empty values use the default | `Pi Web` |
+| `PI_WEB_SKIP_VERSION_CHECK=1` | Disable Pi Web update checks | Unset |
+| `PI_WEB_ALLOWED_HOSTS` | Additional exact proxy or custom hostnames, comma-separated | Unset |
+| `PI_WEB_PASSWORD` | Enable browser password login; API clients may use Basic Auth with username `pi` | Authentication disabled |
+| `PI_WEB_IDLE_TIMEOUT_MS` | Session idle timeout in milliseconds, up to `2147483647`; `0` disables idle shutdown; invalid or out-of-range values use the default | `600000` (10 min) |
+| `PI_WEB_SHUTDOWN_DEADLINE_MS` | How long extensions get to handle `session_shutdown` before a closing session is disposed anyway, in milliseconds up to `2147483647`; `0`, invalid or out-of-range values use the default | `5000` (5 s) |
+
+Set `PI_WEB_APP_NAME` before starting the server (for example, `PI_WEB_APP_NAME='Work Pi' pwc`). After changing it, restart the server to serve the new manifest; no rebuild is required. Updates to the name of an already installed PWA are managed by the browser and are not guaranteed to appear immediately. This does not change the page title or icons.
+
+For example:
+
+```bash
+pwc --help
+pwc -p 8080 -H 0.0.0.0 --no-open
+```
+
+### Remote Access
+
+Binding to a non-loopback address exposes an agent that can execute high-privilege actions. On a trusted LAN, require a long random password:
+
+```bash
+PI_WEB_PASSWORD='a-long-random-password' pwc --hostname 0.0.0.0
+```
+
+Password authentication does not encrypt the connection. Do not expose Pi Web over plain HTTP to the internet; use HTTPS through a trusted reverse proxy or a trusted VPN. If a reverse proxy sends an external hostname, add that exact name to `PI_WEB_ALLOWED_HOSTS`. This allow-list does not change the address Pi Web binds to.
+
+### HTTP Proxy
+
+Server-side model and API requests honor the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables.
+
+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 @colinxu/pi-web-classic@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 @colinxu/pi-web-classic@latest
+```
+
+## Notes
+
+- **Agent data**: Pi Web reads pi data from `~/.pi/agent` by default, including session files under `sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`. Set `PI_CODING_AGENT_DIR` to use another pi agent directory.
+- **Filesystem access**: Pi Web must be able to read the agent data directory and the working directories recorded by its sessions. Run Pi Web in the same filesystem environment as pi when sharing existing sessions.
+- **Shared configuration**: the Models panel uses pi's model, settings, and credential storage, so changes are visible to both interfaces.
+- **File access boundary**: the file browser is limited to working directories selected in Pi Web and project or session roots it already knows about; it is not a general filesystem browser.
+- **Git worktrees**: see [Worktrees in Pi Web](./docs/worktrees.md) for switcher visibility, worktree creation, and removal behavior.
+
+### Downstream Session Context Menu
+
+Electron wrappers and other downstream integrations can provide a session-row
+context menu without patching `SessionSidebar`. Listen for the cancelable
+`pi-web:session-row-contextmenu` browser event and call `preventDefault()`
+synchronously when the integration will handle it:
+
+```js
+window.addEventListener("pi-web:session-row-contextmenu", (event) => {
+  event.preventDefault();
+  const { id, path, cwd, name, clientX, clientY, refresh } = event.detail;
+
+  void openSessionMenu({ id, path, cwd, name, clientX, clientY }).then((changed) => {
+    if (changed) refresh();
+  });
+});
+```
+
+The detail object contains `id`, `path`, `cwd`, optional `name`, pointer
+coordinates, and a `refresh()` callback for actions that change the session
+list. If no listener cancels the extension event, Pi Web opens its built-in
+session menu (pin, rename, fork, mark read or unread, archive, open in new
+tab, delete) at the pointer instead of the browser's native context menu.
+The row's `⋯` button always opens the built-in menu and does not dispatch the
+event. Sessions not yet saved to disk get no built-in menu, so the native one
+still appears for them. This hook is browser-side and independent of Pi agent
+extensions.
+
+### Extension Session Liveness
+
+Server-side Pi extensions with detached work can prevent automatic idle
+session eviction through the versioned global registry:
+
+```js
+const liveness = globalThis[Symbol.for("@colinxu/pi-web-classic/session-liveness/v1")];
+const release = liveness?.version === 1
+  ? liveness.register({
+      name: "my-extension",
+      sessionId,
+      sessionFile: sessionFile || undefined,
+      isActive: () => detachedJobs.size > 0,
+    })
+  : () => {};
+```
+
+Register once per active extension session and call the returned idempotent
+`release` function on session shutdown, replacement, or reload. `isActive`
+must be synchronous, cheap, and scoped to the supplied exact session id or
+file. Provider errors fail safe by preserving that session. This lease only
+affects automatic idle eviction; explicit shutdown and Stop fallback cleanup
+still take precedence.
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+The development server runs at [http://127.0.0.1:30141](http://127.0.0.1:30141). Run the common checks with:
+
+```bash
+npm test
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+Do not run `next build` or `npm run build` during normal development. It writes to `.next/` and can interfere with the development server; leave builds for release work.
+
+Before starting on a feature, read [Contributing](./CONTRIBUTING.md) for what is in scope and the pull request checklist.
+
+Contributor guides: [Internationalization](./docs/i18n.md) and [Release process](./docs/release.md).
+
+## Repository Layout
+
+```text
+app/             Next.js UI and API routes
+components/      React UI components
+hooks/           Client state and interaction hooks
+lib/             Session, agent, model, file, Git, and security logic
+public/          Static assets and PWA files
+bin/             npm CLI entrypoint and launch option parsing
+docs/            Focused user and contributor guides
+demo/            Static browser demo published to GitHub Pages (see demo/README.md)
+```
+
+See [AGENTS.md](./AGENTS.md) for the architecture notes and detailed file map.
+
+## License
+
+[MIT](./LICENSE)

package/bin/browser-opener.js

@@ -0,0 +1,34 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { spawn } = require("child_process");
+
+function openInBrowser(url, platform = process.platform) {
+  // Avoid `shell: true` to suppress Node.js DEP0190 deprecation
+  // ("Passing args to a child process with shell option true can lead to
+  // security vulnerabilities, as the arguments are not escaped").
+  // Pass a structured argv so Node.js handles escaping instead of
+  // concatenating the args into a shell command string.
+  let opener;
+  if (platform === "win32") {
+    // `start` is a cmd.exe built-in, so invoke cmd directly. The empty
+    // title argument is required by `start` before the target URL.
+    opener = spawn(process.env.ComSpec || "cmd.exe", ["/c", "start", "", url], {
+      stdio: "ignore",
+      detached: true,
+    });
+  } else {
+    opener = spawn(platform === "darwin" ? "open" : "xdg-open", [url], {
+      stdio: "ignore",
+      detached: true,
+    });
+  }
+
+  opener.on("error", (error) => {
+    console.warn(`Could not open browser automatically: ${error.message}`);
+  });
+
+  opener.unref();
+}
+
+module.exports = { openInBrowser };

package/bin/node-version.js

@@ -0,0 +1,35 @@
+"use strict";
+
+const MIN_NODE_VERSION = "22.19.0";
+
+function parseNodeVersion(version) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version);
+  if (!match) return null;
+  return match.slice(1).map(Number);
+}
+
+function isNodeVersionSupported(version) {
+  const current = parseNodeVersion(version);
+  const minimum = parseNodeVersion(MIN_NODE_VERSION);
+  if (!current || !minimum) return false;
+
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (current[index] > minimum[index]) return true;
+    if (current[index] < minimum[index]) return false;
+  }
+  return true;
+}
+
+function getUnsupportedNodeVersionMessage(version) {
+  return [
+    `Pi Web requires Node.js ${MIN_NODE_VERSION} or newer.`,
+    `Current Node.js version: ${version}.`,
+    "Upgrade Node.js and try again: https://nodejs.org/",
+  ].join("\n");
+}
+
+module.exports = {
+  MIN_NODE_VERSION,
+  getUnsupportedNodeVersionMessage,
+  isNodeVersionSupported,
+};

package/bin/pi-web-commands.js

@@ -0,0 +1,118 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { spawnSync } = require("child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require("path");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { openInBrowser } = require("./browser-opener");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { runUpdate } = require("./pi-web-update");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const records = require("./run-records");
+
+const STOP_TIMEOUT_MS = 10_000;
+const STOP_POLL_MS = 200;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function getPackageVersion(pkgDir = path.join(__dirname, "..")) {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return require(path.join(pkgDir, "package.json")).version;
+}
+
+function killWindowsProcessTree(pid) {
+  const result = spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { encoding: "utf8" });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error((result.stderr || result.stdout || `taskkill exited ${result.status}`).trim());
+}
+
+async function stopServer(record, {
+  kill = process.kill,
+  killTree = killWindowsProcessTree,
+  platform = process.platform,
+  isAlive = records.isProcessAlive,
+  wait = sleep,
+  timeoutMs = STOP_TIMEOUT_MS,
+  log = console.log,
+  error = console.error,
+} = {}) {
+  // The launcher, or the Next.js server a killed launcher left serving.
+  const pid = record.stopPid ?? record.pid;
+  try {
+    // The launcher forwards SIGTERM to Next.js and exits after it. Windows has
+    // no SIGTERM: process.kill() would end the launcher alone and leave Next.js
+    // serving the port, so end the whole process tree there.
+    if (platform === "win32") killTree(pid);
+    else kill(pid, "SIGTERM");
+  } catch (killError) {
+    if (killError.code !== "ESRCH") {
+      error(`Could not stop pi-web (pid ${pid}): ${killError.message}`);
+      return 1;
+    }
+  }
+  for (let waited = 0; isAlive(pid); waited += STOP_POLL_MS) {
+    if (waited >= timeoutMs) {
+      error(`pi-web on ${record.url} (pid ${pid}) is still running after ${timeoutMs / 1000} s.`);
+      return 1;
+    }
+    await wait(STOP_POLL_MS);
+  }
+  log(`Stopped pi-web on ${record.url} (pid ${pid}).`);
+  return 0;
+}
+
+async function runCommand(options, {
+  runDir = records.getRunDir(),
+  pkgDir = path.join(__dirname, ".."),
+  open = openInBrowser,
+  isAnswering = records.isServerAnswering,
+  isOurs = records.isRecordProcess,
+  log = console.log,
+  error = console.error,
+} = {}) {
+  const list = () => records.listRunRecords(runDir, { isAnswering, isOurs });
+  switch (options.command) {
+    case "version":
+      log(getPackageVersion(pkgDir));
+      return 0;
+    case "status": {
+      const running = await list();
+      log(running.length === 0
+        ? "No pi-web server is running."
+        : `Running pi-web servers:\n${running.map(records.formatRunRecord).join("\n")}`);
+      return 0;
+    }
+    case "stop":
+    case "open": {
+      const selected = records.selectRunRecord(await list(), options.port);
+      if (!selected.record) {
+        error(selected.error);
+        return 1;
+      }
+      if (options.command === "stop") {
+        const code = await stopServer(selected.record, { log, error });
+        if (code === 0) records.removeRunRecord(runDir, selected.record.pid);
+        return code;
+      }
+      log(`Opening ${selected.record.url}`);
+      open(selected.record.url);
+      return 0;
+    }
+    case "update":
+      return runUpdate({
+        check: options.check,
+        currentVersion: getPackageVersion(pkgDir),
+        pkgDir,
+        listRecords: list,
+        formatRecord: records.formatRunRecord,
+        log,
+        error,
+      });
+    default:
+      error(`Unknown command: ${options.command}`);
+      return 1;
+  }
+}
+
+module.exports = { getPackageVersion, runCommand, stopServer };

package/bin/pi-web-node-args.js

@@ -0,0 +1,11 @@
+"use strict";
+
+function getNextNodeArgs(nextBin, nextArgs, arch = process.arch) {
+  if (arch === "riscv64") {
+    return ["--no-wasm-lazy-compilation", nextBin, ...nextArgs];
+  }
+
+  return [nextBin, ...nextArgs];
+}
+
+module.exports = { getNextNodeArgs };

package/bin/pi-web-options.js

@@ -0,0 +1,141 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseArgs } = require("util");
+
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+
+const CLI_OPTIONS = {
+  port: { type: "string", short: "p" },
+  hostname: { type: "string", short: "H" },
+  "no-open": { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+};
+
+function isEnabled(value) {
+  return typeof value === "string" && TRUE_VALUES.has(value.trim().toLowerCase());
+}
+
+function normalizePort(value) {
+  if (typeof value !== "string" || !/^\d+$/.test(value)) {
+    throw new Error("Port must be a non-negative integer.");
+  }
+
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port > 65535) {
+    throw new Error("Port must be between 0 and 65535.");
+  }
+
+  return String(port);
+}
+
+// Subcommands and their own options. Matched only as the first argument, so a
+// bare `pwc [options]` still starts the server.
+const COMMAND_OPTIONS = {
+  version: {},
+  status: {},
+  stop: { port: { type: "string", short: "p" } },
+  open: { port: { type: "string", short: "p" } },
+  update: { check: { type: "boolean" } },
+};
+
+function getHelpText() {
+  return `Usage: pwc [command] [options]
+
+Start the Pi Web UI server, or run one of the commands below.
+
+Commands:
+  version                    Print the installed Pi Web version (also -v, --version)
+  status                     List running Pi Web servers
+  stop [--port <port>]       Stop a running server
+  open [--port <port>]       Open a running server in the browser
+  update [--check]           Update a global npm install to the latest version
+
+Options:
+  -p, --port <port>          Server port (default: 30141, or PORT)
+  -H, --hostname <host>      Bind hostname (default: 127.0.0.1, or PI_WEB_HOSTNAME)
+      --no-open              Do not open a browser automatically
+  -h, --help                 Show this help message and exit
+
+Environment:
+  PORT                       Default port when --port is omitted
+  PI_WEB_HOSTNAME            Default hostname when --hostname is omitted
+  PI_WEB_NO_OPEN             Set to 1/true/yes/on to disable browser open
+  PI_WEB_APP_NAME            PWA manifest name (trimmed; default Pi Web)
+  PI_WEB_PASSWORD            Enable browser password login and API Basic Auth
+  PI_WEB_ALLOWED_HOSTS       Extra exact proxy/custom hostnames, comma-separated
+  PI_WEB_SKIP_VERSION_CHECK  Set to 1 to disable Pi Web update checks
+  PI_WEB_IDLE_TIMEOUT_MS     Session idle timeout in ms (0 disables; default 600000)
+  PI_WEB_SHUTDOWN_DEADLINE_MS  Shutdown wait for extensions in ms (default 5000)
+`;
+}
+
+function toParseError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const err = new Error(`${message}\nUse --help to see available options.`);
+  err.code = "ERR_PARSE_ARGS_UNKNOWN_OPTION";
+  return err;
+}
+
+// Returns { command: "start", ...launch options } for a bare launch, or
+// { command, help, port?, check? } for a subcommand.
+function parseCommandLine(args = process.argv.slice(2), env = process.env) {
+  const first = args[0];
+  const command = first === "-v" || first === "--version" ? "version" : first;
+  if (!Object.hasOwn(COMMAND_OPTIONS, command)) {
+    return { command: "start", ...parseLaunchOptions(args, env) };
+  }
+
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: args.slice(1),
+      options: { ...COMMAND_OPTIONS[command], help: { type: "boolean", short: "h" } },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (error) {
+    throw toParseError(error);
+  }
+  if (values.help) return { command, help: true };
+  return {
+    command,
+    help: false,
+    port: values.port === undefined ? undefined : normalizePort(values.port),
+    check: values.check === true,
+  };
+}
+
+function parseLaunchOptions(args = process.argv.slice(2), env = process.env) {
+  let values;
+  let positionals;
+  try {
+    ({ values, positionals } = parseArgs({
+      args,
+      options: CLI_OPTIONS,
+      strict: true,
+      allowPositionals: true,
+    }));
+  } catch (error) {
+    throw toParseError(error);
+  }
+
+  if (values.help) {
+    return { help: true };
+  }
+
+  if (positionals.length > 0) {
+    throw new Error(
+      `Unexpected argument(s): ${positionals.join(" ")}\nUse --help to see available options.`,
+    );
+  }
+
+  return {
+    help: false,
+    port: normalizePort(values.port ?? env.PORT ?? "30141"),
+    hostname: values.hostname ?? env.PI_WEB_HOSTNAME ?? "127.0.0.1",
+    openBrowser: !values["no-open"] && !isEnabled(env.PI_WEB_NO_OPEN),
+  };
+}
+
+module.exports = { parseCommandLine, parseLaunchOptions, getHelpText };