@wangjian2254/pi-web 0.8.10

package/README.md

@@ -0,0 +1,156 @@
+# Pi Web
+
+[中文文档](./README.zh-CN.md) | [日本語](./README.ja.md) | [Русский](./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.
+
+![Pi Web displaying a pi session with structured Markdown, tool calls, and project navigation](https://raw.githubusercontent.com/agegr/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 and Simplified 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 @wangjian2254/pi-web@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 `pi-web` command globally:
+
+```bash
+npm install -g @wangjian2254/pi-web@latest
+pi-web
+```
+
+To update, stop the running process with `Ctrl+C` and run the same install command again. To uninstall, run `npm uninstall -g @wangjian2254/pi-web`.
+
+## 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.
+
+| Option or environment variable | Purpose | Default |
+| --- | --- | --- |
+| `--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_ALLOWED_HOSTS` | Additional exact proxy or custom hostnames, comma-separated | Unset |
+| `PI_WEB_PASSWORD` | Enable HTTP Basic Auth; the username is always `pi` | Authentication disabled |
+
+For example:
+
+```bash
+pi-web -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' pi-web --hostname 0.0.0.0
+```
+
+Basic Auth does not encrypt the password in transit. 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 @wangjian2254/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 @wangjian2254/pi-web@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 preserves the
+browser's native context menu. This hook is browser-side and independent of
+Pi agent extensions.
+
+## 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.
+
+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
+```
+
+See [AGENTS.md](./AGENTS.md) for the architecture notes and detailed file map.
+
+## License
+
+[MIT](./LICENSE)

package/README.ru.md

@@ -0,0 +1,132 @@
+# Pi Web
+
+[English](./README.md) | [中文文档](./README.zh-CN.md) | [日本語](./README.ja.md)
+
+Локальный браузерный интерфейс для [pi coding agent](https://github.com/earendil-works/pi). Pi Web использует те же локальные настройки и файлы сессий, что и pi, поэтому в браузере можно находить и продолжать диалоги, запускать агента, настраивать модели и ресурсы, а также просматривать файлы проекта.
+
+![Pi Web показывает сессию pi со структурированным Markdown, вызовами инструментов и навигацией по проекту](https://raw.githubusercontent.com/agegr/pi-web/main/docs/screenshot2.png)
+
+## Возможности
+
+- **Рабочее пространство сессий**: просмотр, продолжение, переименование, экспорт и удаление диалогов, сгруппированных по проектам, с отображением состояния выполнения, использования контекста, стоимости и сведений о сжатии.
+- **Два способа создать ветку**: **New session** создаёт независимый файл сессии из более раннего сообщения, а **Edit from here** создаёт ветку внутри текущей сессии.
+- **Инструменты для файлов проекта**: просмотр и загрузка файлов, проверка Git Diff, предпросмотр исходного кода, Markdown, изображений, аудио, PDF и DOCX с автоматическим обновлением.
+- **Git worktree**: переключение рабочих деревьев в боковой панели с сохранением общей группы сессий одного репозитория.
+- **Настройка через Web**: управление входом в Provider и API Key, моделями, тестами моделей, пакетами плагинов и навыками без выхода из Pi Web.
+- **Интерфейс на английском и упрощённом китайском**: при первом запуске Pi Web учитывает язык браузера, а затем язык можно переключить в верхней панели.
+
+## Быстрый старт
+
+Для работы Pi Web требуется Node.js 22.19.0 или новее. Проверьте версию командой `node --version`, затем выполните:
+
+```bash
+npx @wangjian2254/pi-web@latest
+```
+
+Когда сервер будет готов, CLI попытается открыть браузер автоматически. Если этого не произошло, откройте [http://127.0.0.1:30141](http://127.0.0.1:30141). По умолчанию Pi Web прослушивает только `127.0.0.1`.
+
+Если Provider модели ещё не настроен, откройте панель **Models**, войдите в учётную запись или добавьте API Key.
+
+Чтобы установить команду `pi-web` глобально:
+
+```bash
+npm install -g @wangjian2254/pi-web@latest
+pi-web
+```
+
+Для обновления остановите запущенный процесс с помощью `Ctrl+C` и повторите ту же команду установки. Для удаления выполните `npm uninstall -g @wangjian2254/pi-web`.
+
+## Настройка
+
+Для порта и имени хоста параметры командной строки имеют приоритет над соответствующими переменными окружения. И `--no-open`, и `PI_WEB_NO_OPEN=1` отключают автоматическое открытие браузера независимо друг от друга.
+
+| Параметр или переменная окружения | Назначение | Значение по умолчанию |
+| --- | --- | --- |
+| `--port <port>`, `-p <port>` или `PORT` | Порт сервера | `30141` |
+| `--hostname <host>`, `-H <host>` или `PI_WEB_HOSTNAME` | Имя хоста для привязки | `127.0.0.1` |
+| `--no-open` или `PI_WEB_NO_OPEN=1` | Не открывать браузер автоматически | Браузер открывается |
+| `PI_WEB_ALLOWED_HOSTS` | Дополнительные точные имена прокси или пользовательских хостов через запятую | Не задано |
+| `PI_WEB_PASSWORD` | Включить HTTP Basic Auth; имя пользователя всегда `pi` | Аутентификация отключена |
+
+Пример:
+
+```bash
+pi-web -p 8080 -H 0.0.0.0 --no-open
+```
+
+### Удалённый доступ
+
+Привязка к адресу, отличному от loopback, открывает сетевой доступ к агенту, способному выполнять операции с широкими полномочиями. Даже в доверенной локальной сети используйте длинный случайный пароль:
+
+```bash
+PI_WEB_PASSWORD='длинный-случайный-пароль' pi-web --hostname 0.0.0.0
+```
+
+Basic Auth не шифрует пароль при передаче. Не публикуйте Pi Web в интернете по обычному HTTP; используйте HTTPS через доверенный обратный прокси или надёжное VPN-подключение. Если обратный прокси передаёт внешнее имя хоста, добавьте это точное имя в `PI_WEB_ALLOWED_HOSTS`. Этот список разрешённых имён не меняет адрес, к которому привязывается Pi Web.
+
+### HTTP-прокси
+
+Для серверных запросов к моделям и 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 @wangjian2254/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 @wangjian2254/pi-web@latest
+```
+
+## Примечания
+
+- **Данные агента**: по умолчанию Pi Web читает данные pi из `~/.pi/agent`, включая файлы сессий в `sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`. Чтобы использовать другой каталог агента pi, задайте `PI_CODING_AGENT_DIR`.
+- **Доступ к файловой системе**: Pi Web должен иметь доступ для чтения к каталогу данных агента и рабочим каталогам, записанным в сессиях. При совместном использовании существующих сессий запускайте Pi Web в той же файловой среде, что и pi.
+- **Общие настройки**: панель Models использует хранилища моделей, настроек и учётных данных pi, поэтому изменения видны в обоих интерфейсах.
+- **Граница доступа к файлам**: файловый браузер ограничен рабочими каталогами, выбранными в Pi Web, и уже известными корнями проектов или сессий; это не универсальный файловый менеджер.
+- **Git worktree**: условия отображения переключателя, создание рабочих деревьев и их удаление описаны в документе [Worktrees in Pi Web](./docs/worktrees.md).
+
+## Разработка
+
+```bash
+npm install
+npm run dev
+```
+
+Сервер разработки доступен по адресу [http://127.0.0.1:30141](http://127.0.0.1:30141). Основные проверки запускаются командами:
+
+```bash
+npm test
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+Не запускайте `next build` или `npm run build` во время обычной разработки. Эти команды записывают данные в `.next/` и могут помешать работе сервера разработки; выполняйте сборку только при подготовке релиза.
+
+Руководства для участников: [Internationalization](./docs/i18n.md) и [Release process](./docs/release.md).
+
+## Структура репозитория
+
+```text
+app/             UI Next.js и маршруты API
+components/      Компоненты интерфейса React
+hooks/           Состояние клиента и обработчики взаимодействий
+lib/             Логика сессий, агента, моделей, файлов, Git и безопасности
+public/          Статические ресурсы и файлы PWA
+bin/             Точка входа npm CLI и разбор параметров запуска
+docs/            Тематические руководства для пользователей и участников
+```
+
+Описание архитектуры и подробная карта файлов приведены в [AGENTS.md](./AGENTS.md).
+
+## Лицензия
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,134 @@
+# Pi Web
+
+[English](./README.md) | [日本語](./README.ja.md) | [Русский](./README.ru.md)
+
+[pi 编程智能体](https://github.com/earendil-works/pi)的本地浏览器界面。Pi Web 与 pi 共用本机配置和会话文件，可在浏览器中查找和继续对话、运行智能体、配置模型与资源，并查看项目文件。
+
+中文微信群：请查看 [GitHub Discussions 帖子](https://github.com/agegr/pi-web/discussions/271)。
+
+![Pi Web 展示包含结构化 Markdown、工具调用和项目导航的 pi 会话](https://raw.githubusercontent.com/agegr/pi-web/main/docs/screenshot2.png)
+
+## 功能
+
+- **会话工作区**：按项目查找、继续、重命名、导出和删除对话，并查看运行状态、上下文占用、花费和压缩信息。
+- **两种分支方式**：**新会话**会从较早的消息创建独立会话文件；**从此处编辑**会在当前会话内创建分支。
+- **项目文件工具**：浏览和上传文件、查看 Git Diff，并预览源码、Markdown、图片、音频、PDF 和 DOCX；文件变化后会自动刷新。
+- **Git worktree**：从侧边栏切换 checkout，同时把同一仓库不同 worktree 的会话归在一起。
+- **网页配置**：无需离开 Pi Web，即可管理 Provider 登录和 API Key、模型、模型测试、插件包及技能。
+- **英文和简体中文界面**：Pi Web 首次打开时跟随浏览器语言，也可从顶部栏切换语言。
+
+## 快速开始
+
+Pi Web 要求 Node.js 22.19.0 或更高版本。先用 `node --version` 检查版本，然后运行：
+
+```bash
+npx @wangjian2254/pi-web@latest
+```
+
+服务就绪后，命令行会尝试自动打开浏览器。如果没有打开，请访问 [http://127.0.0.1:30141](http://127.0.0.1:30141)。Pi Web 默认仅监听 `127.0.0.1`。
+
+如果尚未配置模型 Provider，请打开**模型（Models）**面板登录或添加 API Key。
+
+如需全局安装 `pi-web` 命令：
+
+```bash
+npm install -g @wangjian2254/pi-web@latest
+pi-web
+```
+
+更新前先用 `Ctrl+C` 停止正在运行的进程，再次执行同一条安装命令。卸载时运行 `npm uninstall -g @wangjian2254/pi-web`。
+
+## 配置
+
+端口和主机名以命令行参数为准，优先于对应的环境变量。`--no-open` 与 `PI_WEB_NO_OPEN=1` 中任意一个都会关闭自动打开浏览器。
+
+| 参数或环境变量 | 用途 | 默认值 |
+| --- | --- | --- |
+| `--port <端口>`、`-p <端口>` 或 `PORT` | 服务端口 | `30141` |
+| `--hostname <主机>`、`-H <主机>` 或 `PI_WEB_HOSTNAME` | 监听主机名 | `127.0.0.1` |
+| `--no-open` 或 `PI_WEB_NO_OPEN=1` | 不自动打开浏览器 | 自动打开 |
+| `PI_WEB_ALLOWED_HOSTS` | 额外允许的代理或自定义主机名，多个值用逗号分隔，必须精确匹配 | 未设置 |
+| `PI_WEB_PASSWORD` | 启用 HTTP Basic Auth，用户名固定为 `pi` | 不启用认证 |
+
+例如：
+
+```bash
+pi-web -p 8080 -H 0.0.0.0 --no-open
+```
+
+### 远程访问
+
+监听非回环地址会暴露一个可执行高权限操作的智能体。在可信局域网中使用时，请设置足够长的随机密码：
+
+```bash
+PI_WEB_PASSWORD='足够长的随机密码' pi-web --hostname 0.0.0.0
+```
+
+Basic Auth 不会加密传输中的密码。不要通过明文 HTTP 将 Pi Web 暴露到互联网；远程访问应使用可信反向代理提供 HTTPS，或通过可信 VPN。如果反向代理传递外部主机名，请把该名称精确加入 `PI_WEB_ALLOWED_HOSTS`。这个白名单不会改变 Pi Web 的监听地址。
+
+### HTTP 代理
+
+服务端的模型和 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 @wangjian2254/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 @wangjian2254/pi-web@latest
+```
+
+## 注意事项
+
+- **智能体数据**：Pi Web 默认读取 `~/.pi/agent` 下的 pi 数据，包括 `sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl` 中的会话文件。可通过 `PI_CODING_AGENT_DIR` 指定其他 pi agent 目录。
+- **文件系统访问**：Pi Web 必须能读取智能体数据目录及会话记录中的工作目录。与现有 pi 会话共用数据时，请让 Pi Web 运行在与 pi 相同的文件系统环境中。
+- **共享配置**：模型面板使用 pi 的模型、设置和凭据存储，因此两种界面都能看到相关更改。
+- **文件访问边界**：文件浏览器仅能访问在 Pi Web 中选择过的工作目录，以及它已识别的项目或会话根目录；它不是通用的文件系统浏览器。
+- **Git worktree**：切换器何时显示、如何创建 worktree，以及删除会产生什么影响，见 [Pi Web 里的 Worktree](./docs/worktrees.zh-CN.md)。
+
+## 开发
+
+```bash
+npm install
+npm run dev
+```
+
+开发服务器运行在 [http://127.0.0.1:30141](http://127.0.0.1:30141)。常用检查命令：
+
+```bash
+npm test
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+日常开发时不要运行 `next build` 或 `npm run build`。它们会写入 `.next/`，可能干扰开发服务器；仅在发布流程中执行构建。
+
+贡献者文档：[国际化](./docs/i18n.md)和[发布流程](./docs/release.md)。
+
+## 仓库结构
+
+```text
+app/             Next.js 界面和 API 路由
+components/      React 界面组件
+hooks/           客户端状态和交互 hooks
+lib/             会话、智能体、模型、文件、Git 和安全逻辑
+public/          静态资源和 PWA 文件
+bin/             npm CLI 入口及启动参数解析
+docs/            面向用户和贡献者的专题文档
+```
+
+架构说明和详细文件地图见 [AGENTS.md](./AGENTS.md)。
+
+## 许可证
+
+[MIT](./LICENSE)

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-options.js

@@ -0,0 +1,43 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseArgs } = require("util");
+
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+
+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);
+}
+
+function parseLaunchOptions(args = process.argv.slice(2), env = process.env) {
+  const { values: cliArgs } = parseArgs({
+    args,
+    options: {
+      port:      { type: "string", short: "p" },
+      hostname:  { type: "string", short: "H" },
+      "no-open": { type: "boolean" },
+    },
+    strict: false,
+  });
+
+  return {
+    port: normalizePort(cliArgs.port ?? env.PORT ?? "30141"),
+    hostname: cliArgs.hostname ?? env.PI_WEB_HOSTNAME ?? "127.0.0.1",
+    openBrowser: !cliArgs["no-open"] && !isEnabled(env.PI_WEB_NO_OPEN),
+  };
+}
+
+module.exports = { parseLaunchOptions };

package/bin/pi-web.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { getUnsupportedNodeVersionMessage, isNodeVersionSupported } = require("./node-version");
+
+if (!isNodeVersionSupported(process.versions.node)) {
+  console.error(getUnsupportedNodeVersionMessage(process.versions.node));
+  process.exit(1);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { spawn } = 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 fs = require("fs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseLaunchOptions } = require("./pi-web-options");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { wireChildProcessLifecycle } = require("./process-lifecycle");
+
+const pkgDir = path.join(__dirname, "..");
+const nextDir = path.join(pkgDir, ".next");
+
+// Resolve next's CLI entry directly to avoid relying on .bin symlinks (which
+// may not exist when installed via npx).
+let nextBin;
+try {
+  nextBin = require.resolve("next/dist/bin/next", { paths: [pkgDir] });
+} catch {
+  // Fallback: locate next package root and derive the bin path manually.
+  try {
+    const nextPkg = require.resolve("next/package.json", { paths: [pkgDir] });
+    nextBin = path.join(path.dirname(nextPkg), "dist", "bin", "next");
+  } catch {
+    nextBin = path.join(pkgDir, "node_modules", "next", "dist", "bin", "next");
+  }
+}
+
+const { port, hostname, openBrowser } = parseLaunchOptions();
+const loopbackHostnames = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+const passwordEnabled = Boolean(process.env.PI_WEB_PASSWORD);
+
+if (!fs.existsSync(nextDir)) {
+  console.error("Build artifacts not found. Please report this issue.");
+  process.exit(1);
+}
+
+if (!loopbackHostnames.has(hostname)) {
+  if (passwordEnabled) {
+    console.warn(
+      `Warning: pi-web is listening on ${hostname} with Basic Auth over HTTP. Use HTTPS or a trusted VPN to protect the password in transit.`,
+    );
+  } else {
+    console.warn(
+      `Warning: pi-web is listening on ${hostname} without authentication. Only use this on a trusted network.`,
+    );
+  }
+}
+
+const nextArgs = ["start", "-p", port];
+nextArgs.push("-H", hostname);
+
+// Always run next's JS entry with node directly — avoids .bin symlink issues
+// and path-with-spaces problems on Windows when shell: true is used.
+const child = spawn(process.execPath, [nextBin, ...nextArgs], {
+  cwd: pkgDir,
+  stdio: ["inherit", "pipe", "inherit"],
+  env: { ...process.env, PI_WEB_HOSTNAME: hostname },
+});
+wireChildProcessLifecycle(child);
+
+let browserOpened = false;
+const url = `http://${hostname}:${port}`;
+
+child.stdout.on("data", (chunk) => {
+  const text = chunk.toString();
+  process.stdout.write(text);
+  if (openBrowser && !browserOpened && text.includes("Ready")) {
+    browserOpened = true;
+    const isWindows = process.platform === "win32";
+    const isMac = process.platform === "darwin";
+    // 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 (isWindows) {
+      // `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 if (isMac) {
+      opener = spawn("open", [url], {
+        stdio: "ignore",
+        detached: true,
+      });
+    } else {
+      opener = spawn("xdg-open", [url], {
+        stdio: "ignore",
+        detached: true,
+      });
+    }
+
+    opener.on("error", (error) => {
+      console.warn(`Could not open browser automatically: ${error.message}`);
+    });
+
+    opener.unref();
+  }
+});

package/bin/process-lifecycle.js

@@ -0,0 +1,46 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const os = require("node:os");
+
+const forwardedSignals = ["SIGINT", "SIGTERM"];
+const shutdownTimeoutMs = 5_000;
+
+function getSignalExitCode(signal) {
+  const signalNumber = signal ? os.constants.signals[signal] : undefined;
+  return typeof signalNumber === "number" ? 128 + signalNumber : 1;
+}
+
+function wireChildProcessLifecycle(child, parentProcess = process, timeoutMs = shutdownTimeoutMs) {
+  const signalHandlers = new Map();
+  let shutdownTimer;
+
+  const forceKill = () => child.kill("SIGKILL");
+
+  for (const signal of forwardedSignals) {
+    const handler = () => {
+      if (shutdownTimer) {
+        forceKill();
+        return;
+      }
+
+      shutdownTimer = setTimeout(forceKill, timeoutMs);
+      shutdownTimer.unref();
+      child.kill(signal);
+    };
+    signalHandlers.set(signal, handler);
+    parentProcess.on(signal, handler);
+  }
+
+  child.once("exit", (code, signal) => {
+    if (shutdownTimer) clearTimeout(shutdownTimer);
+
+    for (const [forwardedSignal, handler] of signalHandlers) {
+      parentProcess.removeListener(forwardedSignal, handler);
+    }
+
+    parentProcess.exit(code ?? getSignalExitCode(signal));
+  });
+}
+
+module.exports = { wireChildProcessLifecycle };