pi-web-ui 0.1.1 → 0.2.0

package/README.md

@@ -43,6 +43,105 @@ npm run build        # compiles server (tsc) + frontend (vite)
 npm start            # serves everything on http://localhost:8787
 ```
 
+## npm package (install / start / stop / update / uninstall)
+
+The package is published on npm as [`pi-web-ui`](https://www.npmjs.com/package/pi-web-ui).
+
+### Install
+
+```bash
+# install globally (recommended)
+npm i -g pi-web-ui
+
+# or run without installing (pulls the latest, starts on :8787)
+npx pi-web-ui
+
+# or install the local checkout (for testing changes before publishing)
+npm i -g .
+```
+
+> **pi-managed npm?** If your `npm` is the pi wrapper that blocks dependency
+> install scripts, approve node-pty's native build once after installing:
+> `npm approve-scripts node-pty@1.1.0` (standard npm does this automatically).
+
+### Start
+
+```bash
+pi-web-ui                                            # foreground, http://localhost:8787
+PORT=9000 PI_WEB_CWD=/path/to/project pi-web-ui      # custom port / workspace
+```
+
+To run it in the background or auto-start on boot, use a system service —
+see [Deploy & auto-start on boot](#deploy--auto-start-on-boot) (systemd /
+launchd / Docker).
+
+The `pi-web-ui` command serves the built frontend and the WebSocket API from
+wherever the package is installed — no repo checkout needed. It uses **your**
+`~/.pi/agent` config (auth/models/skills) and stores per-client sessions under
+`<PI_WEB_CWD>/.pi-web`.
+
+### Stop
+
+- **Foreground**: press `Ctrl+C` in the terminal running it.
+- **systemd**: `sudo systemctl stop pi-web-ui`
+- **launchd**: `launchctl bootout gui/$(id -u)/com.xingshuyin.pi-web-ui`
+- **Docker**: `docker compose stop` (stop + remove the container: `docker compose down`)
+
+(Background processes should be managed by a system service, not `nohup` —
+service stop commands above also stop and disable auto-start.)
+
+### Verify / version
+
+```bash
+pi-web-ui --version     # CLI version
+npm ls -g pi-web-ui     # installed? which version?
+which pi-web-ui         # executable location
+```
+
+### Update
+
+```bash
+npm i -g pi-web-ui@latest   # upgrade to the latest published version
+# restart the server afterwards for the new version to take effect
+```
+
+### Uninstall
+
+```bash
+npm uninstall -g pi-web-ui
+```
+
+Uninstalling does **not** delete your chats: session data lives in
+`<PI_WEB_CWD>/.pi-web` (or `PI_WEB_DATA_DIR`) and survives uninstall/upgrade.
+
+### Manage as a system service (auto-start)
+
+Install the server as a system service that starts on boot, with a custom
+port and workspace:
+
+```bash
+pi-web-ui server install --port 9000 --cwd /path/to/project   # install + start
+pi-web-ui server status                # running? auto-start?
+pi-web-ui server restart               # restart (also applies config changes)
+pi-web-ui server stop                  # stop + disable auto-start
+pi-web-ui server start                 # start again
+pi-web-ui server uninstall             # remove the service entirely
+```
+
+- **macOS** → launchd agent (no sudo): writes and loads
+  `~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist`, restarts on crash
+  (`KeepAlive`), logs to `/tmp/pi-web-ui.log` / `/tmp/pi-web-ui.err`.
+- **Linux** → systemd unit (auto-sudo): writes
+  `/etc/systemd/system/pi-web-ui.service` and runs `systemctl enable --now`,
+  logs via `journalctl -u pi-web-ui -f`.
+- Options: `--port` (default 8787 or `$PORT`), `--cwd` (default `$PI_WEB_CWD`
+  or the current directory), `--data-dir` (sessions), `--name` (custom service
+  name; on macOS the label is `com.xingshuyin.pi-web-ui`, custom names become
+  `com.<name>.server`). `--print` previews the generated unit/plist without
+  applying it.
+- Rerunning `install` with new options regenerates the config and restarts the
+  service — that's how you change the port/cwd of an installed service.
+
 ## Configuration
 
 | Env var | Default | Description |
@@ -83,6 +182,12 @@ Key design points:
   event it schedules a throttled (60 ms) full-state snapshot, and the browser
   renders purely from snapshots. Reconnects just re-request `get_state`. Large
   payloads (tool output, text) are capped during serialization (`server/serialize.ts`).
+- **Live assistant streaming.** The in-progress message (SDK
+  `agent.state.streamingMessage`) is serialized into every snapshot, so thinking
+  blocks and answer text appear in the browser as they are generated — with a
+  blinking cursor — instead of only after the turn finishes. The partial message
+  gets a stable `stream-<ts>` id so it stays mounted (open thinking/tool blocks
+  keep their state) across snapshots.
 - **Size-aware attachments.** Clicking + on a file queues it as an attachment
   (shown as chips above the input). On send, the server attaches each file as an
   independent custom message (SDK `sendCustomMessage` + `nextTurn` asides) — the
@@ -158,6 +263,52 @@ Server → client: `ready`, `snapshot` (full `UiState`), `tool_delta`, `notice`,
 | `node terminal-smoke-test.mjs` | WS-level terminal/commands protocol test (build first) |
 | `node terminal-browser-test.mjs` | headless-browser E2E of the terminal view (build first) |
 
+## Deploy & auto-start on boot
+
+Quickest path: `pi-web-ui server install --port 8787 --cwd /path` — installs
+and starts the service on boot (see [Manage as a system service](#manage-as-a-system-service-auto-start)).
+The manual alternatives below are kept for reference / non-standard setups.
+
+### Docker (one command)
+
+```bash
+docker compose up -d     # builds, starts on :8787, auto-restarts on boot
+docker compose stop      # stop (keeps the container)
+docker compose down      # stop and remove the container
+```
+
+`restart: unless-stopped` in `docker-compose.yml` brings the server back up
+whenever the Docker daemon starts (boot, crashes, reboots). Mount a volume for
+`/app/.pi-web` (sessions persist) and, optionally, your `~/.pi/agent` config
+and a workspace — see the comments in `docker-compose.yml`.
+
+### Linux — systemd
+
+```bash
+sudo npm i -g pi-web-ui
+sudo cp deploy/pi-web-ui.service /etc/systemd/system/
+# edit User/WorkingDirectory/Environment in the unit first
+sudo systemctl daemon-reload
+sudo systemctl enable --now pi-web-ui     # starts now + on every boot
+sudo systemctl stop pi-web-ui             # stop
+sudo systemctl disable pi-web-ui          # stop auto-start on boot
+journalctl -u pi-web-ui -f                # logs
+```
+
+### macOS — launchd
+
+```bash
+npm i -g pi-web-ui
+cp deploy/com.xingshuyin.pi-web-ui.plist ~/Library/LaunchAgents/
+# edit ProgramArguments / WorkingDirectory / PI_WEB_CWD (which pi-web-ui)
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist
+launchctl bootout gui/$(id -u)/com.xingshuyin.pi-web-ui   # stop + remove auto-start
+# logs: /tmp/pi-web-ui.log, /tmp/pi-web-ui.err
+```
+
+Both templates use `KeepAlive`/`Restart=on-failure` so the server survives
+crashes, and start at login/boot automatically.
+
 ## License
 
 MIT

package/bin/pi-web-ui.mjs

@@ -1,9 +1,518 @@
 #!/usr/bin/env node
 /**
- * pi-web-ui CLI entry.
+ * pi-web-ui CLI.
  *
- * Starts the production server (serves the built frontend + WebSocket API).
- * Env vars: PORT (default 8787), PI_WEB_CWD, PI_WEB_DATA_DIR, PI_CODING_AGENT_DIR.
- * See README.md for details.
+ *   pi-web-ui                              启动生产服务器（前台，Ctrl+C 停止）
+ *   pi-web-ui --port 9000 --cwd /path      同上，覆盖端口 / 工作目录 / 数据目录
+ *   pi-web-ui --version | --help
+ *   pi-web-ui server install [选项]         安装系统服务（开机自启）并启动
+ *   pi-web-ui server uninstall [选项]       卸载系统服务
+ *   pi-web-ui server start|stop|restart|status [选项]
+ *
+ * 系统服务：
+ *   - macOS  → launchd 用户代理，label 默认 com.xingshuyin.pi-web-ui
+ *             （--name 自定义时 com.<name>.server），无需 sudo
+ *   - Linux  → systemd 单元 <name>.service（/etc/systemd/system/，自动 sudo）
+ *
+ * 环境变量（前台与系统服务均适用）：PORT / PI_WEB_CWD / PI_WEB_DATA_DIR /
+ * PI_CODING_AGENT_DIR。
  */
-import "../dist/server/index.js";
+import { spawnSync } from "node:child_process";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+
+const BIN_DIR = dirname(fileURLToPath(import.meta.url));
+/** <pkg>/dist/server/index.js — the actual server entry. */
+const SERVER_ENTRY = join(BIN_DIR, "..", "dist", "server", "index.js");
+const NODE = process.execPath;
+let pkg = { version: "0.0.0" };
+try {
+	pkg = JSON.parse(readFileSync(join(BIN_DIR, "..", "package.json"), "utf8"));
+} catch {
+	// version is best-effort — the server itself doesn't need it
+}
+
+const HELP = `pi-web-ui v${pkg.version} — web chat for the pi coding agent
+
+用法:
+  pi-web-ui                               启动服务器（前台，Ctrl+C 停止）
+  pi-web-ui --port 9000 --cwd /path       启动并指定端口 / 工作目录 / 数据目录
+  pi-web-ui server install [选项]         安装系统服务（开机自启）并启动
+  pi-web-ui server uninstall [选项]       卸载系统服务
+  pi-web-ui server start|stop|restart|status [选项]
+  pi-web-ui --version / --help
+
+server 选项:
+  --port <n>        端口（默认 8787，或 $PORT）
+  --cwd <dir>       工作目录（默认 $PI_WEB_CWD 或当前目录）
+  --data-dir <dir>  会话数据目录（默认 <cwd>/.pi-web）
+  --name <name>     服务名（默认 pi-web-ui；macOS 的 launchd label
+                    为 com.xingshuyin.pi-web-ui，自定义名时为 com.<name>.server）
+  --print           只打印将生成的配置文件，不实际安装
+
+环境变量（前台与系统服务均适用）:
+  PORT / PI_WEB_CWD / PI_WEB_DATA_DIR / PI_CODING_AGENT_DIR
+`;
+
+function fail(msg) {
+	console.error(`✖ ${msg}`);
+	process.exit(1);
+}
+
+/** Run a command, inheriting stdio; exits on failure unless ignoreError. */
+function run(cmd, args, { ignoreError = false, silent = false } = {}) {
+	const res = spawnSync(cmd, args, {
+		stdio: silent ? ["inherit", "ignore", "ignore"] : "inherit",
+	});
+	if (!ignoreError && res.status !== 0) process.exit(res.status ?? 1);
+	return res;
+}
+
+/** Parse --flag value / --flag=value options; returns { opts, positionals }. */
+function parseFlags(argv) {
+	const opts = {
+		port: undefined,
+		cwd: undefined,
+		dataDir: undefined,
+		name: undefined,
+		print: false,
+		help: false,
+	};
+	const positionals = [];
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		const eq = a.indexOf("=");
+		const key = eq >= 0 ? a.slice(0, eq) : a;
+		const inline = eq >= 0 ? a.slice(eq + 1) : undefined;
+		const take = (flag) => {
+			if (inline !== undefined) return inline;
+			if (i + 1 < argv.length) {
+				i++;
+				return argv[i];
+			}
+			fail(`缺少选项 ${flag} 的值`);
+		};
+		switch (key) {
+			case "--port":
+				opts.port = take("--port");
+				break;
+			case "--cwd":
+				opts.cwd = take("--cwd");
+				break;
+			case "--data-dir":
+				opts.dataDir = take("--data-dir");
+				break;
+			case "--name":
+				opts.name = take("--name");
+				break;
+			case "--print":
+				opts.print = true;
+				break;
+			case "--help":
+			case "-h":
+				opts.help = true;
+				break;
+			default:
+				if (key.startsWith("-")) fail(`未知选项: ${key}`);
+				positionals.push(a);
+		}
+	}
+	return { opts, positionals };
+}
+
+// ---------------------------------------------------------------------------
+// 前台启动
+// ---------------------------------------------------------------------------
+
+async function startForeground(opts) {
+	if (opts.port) process.env.PORT = opts.port;
+	if (opts.cwd) process.env.PI_WEB_CWD = resolve(opts.cwd);
+	if (opts.dataDir) process.env.PI_WEB_DATA_DIR = resolve(opts.dataDir);
+	await import(pathToFileURL(SERVER_ENTRY).href);
+}
+
+// ---------------------------------------------------------------------------
+// 系统服务管理
+// ---------------------------------------------------------------------------
+
+const isMac = process.platform === "darwin";
+const isLinux = process.platform === "linux";
+
+function uid() {
+	try {
+		return userInfo().uid;
+	} catch {
+		return process.getuid?.() ?? 501;
+	}
+}
+
+/** launchd label / systemd unit name for a service name. */
+function serviceLabel(name) {
+	if (isMac) {
+		return name === "pi-web-ui"
+			? "com.xingshuyin.pi-web-ui"
+			: `com.${name}.server`;
+	}
+	return name;
+}
+
+function launchAgentPlist(name) {
+	return join(
+		homedir(),
+		"Library",
+		"LaunchAgents",
+		`${serviceLabel(name)}.plist`,
+	);
+}
+
+function systemdUnitPath(name) {
+	return `/etc/systemd/system/${name}.service`;
+}
+
+function esc(s) {
+	return s
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;");
+}
+
+/** Build the launchd plist XML. */
+function buildPlist(label, cwd, env) {
+	const entries = Object.entries(env)
+		.map(([k, v]) => `    <key>${esc(k)}</key>\n    <string>${esc(v)}</string>`)
+		.join("\n");
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- Generated by: pi-web-ui server install (do not edit by hand — rerun to change) -->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${esc(label)}</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>${esc(NODE)}</string>
+    <string>${esc(SERVER_ENTRY)}</string>
+  </array>
+
+  <key>RunAtLoad</key>
+  <true/>
+
+  <!-- Restart if it crashes -->
+  <key>KeepAlive</key>
+  <true/>
+
+  <key>WorkingDirectory</key>
+  <string>${esc(cwd)}</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+${entries}
+  </dict>
+
+  <key>StandardOutPath</key>
+  <string>/tmp/pi-web-ui.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/pi-web-ui.err</string>
+</dict>
+</plist>
+`;
+}
+
+/** Build the systemd unit file. */
+function buildUnit(cwd, env) {
+	const envLines = Object.entries(env)
+		.map(([k, v]) => `Environment=${k}=${v}`)
+		.join("\n");
+	return `# Generated by: pi-web-ui server install (do not edit by hand — rerun to change)
+[Unit]
+Description=pi-web-ui — web chat for the pi coding agent
+After=network.target
+
+[Service]
+Type=simple
+User=${process.env.SUDO_USER ?? userInfo().username}
+WorkingDirectory=${cwd}
+${envLines}
+ExecStart=${JSON.stringify(NODE)} ${JSON.stringify(SERVER_ENTRY)}
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+/** If not root on Linux, re-exec the same server command through sudo. */
+function ensureRootForSystemctl() {
+	if (typeof process.getuid === "function" && process.getuid() === 0) return;
+	// process.argv = [node, <bin>, "server", <action>, ...rest] — forward
+	// everything after "server" so flags like --port/--cwd survive.
+	const res = spawnSync(
+		"sudo",
+		[NODE, fileURLToPath(import.meta.url), "server", ...process.argv.slice(3)],
+		{ stdio: "inherit" },
+	);
+	process.exit(res.status ?? 1);
+}
+
+/** Shared option normalization for install. */
+function serviceOptions(opts) {
+	const name = opts.name ?? "pi-web-ui";
+	const port = String(opts.port ?? process.env.PORT ?? "8787");
+	if (!/^\d{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65535) {
+		fail(`无效端口: ${port}`);
+	}
+	const cwd = resolve(opts.cwd ?? process.env.PI_WEB_CWD ?? process.cwd());
+	if (!existsSync(cwd)) fail(`工作目录不存在: ${cwd}`);
+	let dataDir;
+	if (opts.dataDir) {
+		dataDir = resolve(opts.dataDir);
+	} else if (process.env.PI_WEB_DATA_DIR) {
+		dataDir = resolve(process.env.PI_WEB_DATA_DIR);
+	}
+	return { name, port, cwd, dataDir };
+}
+
+function serviceEnv(port, cwd, dataDir) {
+	const env = {
+		PORT: port,
+		PI_WEB_CWD: cwd,
+		PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+	};
+	if (dataDir) env.PI_WEB_DATA_DIR = dataDir;
+	return env;
+}
+
+function installLaunchd(opts) {
+	const { name, port, cwd, dataDir } = serviceOptions(opts);
+	const label = serviceLabel(name);
+	const plist = launchAgentPlist(name);
+	const content = buildPlist(label, cwd, serviceEnv(port, cwd, dataDir));
+	if (opts.print) {
+		console.log(`# ${plist}\n${content}`);
+		return;
+	}
+	// Unload any existing instance (ignore "not loaded"), then (re)install.
+	run("launchctl", ["bootout", `gui/${uid()}/${label}`], {
+		ignoreError: true,
+		silent: true,
+	});
+	mkdirSync(dirname(plist), { recursive: true });
+	writeFileSync(plist, content);
+	run("launchctl", ["bootstrap", `gui/${uid()}`, plist]);
+	console.log(`✅ 已安装并启动 launchd 服务 ${label}`);
+	console.log(`   端口 : ${port}`);
+	console.log(`   目录 : ${cwd}`);
+	console.log(`   访问 : http://localhost:${port}`);
+	console.log(`   日志 : /tmp/pi-web-ui.log  /tmp/pi-web-ui.err`);
+	console.log(`   管理 : pi-web-ui server status|restart|stop|uninstall`);
+}
+
+function installSystemd(opts) {
+	const { name, port, cwd, dataDir } = serviceOptions(opts);
+	const content = buildUnit(cwd, serviceEnv(port, cwd, dataDir));
+	const unitPath = systemdUnitPath(name);
+	if (opts.print) {
+		console.log(`# ${unitPath}\n${content}`);
+		return;
+	}
+	ensureRootForSystemctl();
+	writeFileSync(unitPath, content);
+	run("systemctl", ["daemon-reload"]);
+	run("systemctl", ["enable", "--now", `${name}.service`]);
+	console.log(`✅ 已安装并启动 systemd 服务 ${name}.service`);
+	console.log(`   端口 : ${port}`);
+	console.log(`   目录 : ${cwd}`);
+	console.log(`   访问 : http://localhost:${port}`);
+	console.log(`   日志 : journalctl -u ${name}.service -f`);
+	console.log(`   管理 : pi-web-ui server status|restart|stop|uninstall`);
+}
+
+function uninstallLaunchd(opts) {
+	const name = opts.name ?? "pi-web-ui";
+	const label = serviceLabel(name);
+	const plist = launchAgentPlist(name);
+	run("launchctl", ["bootout", `gui/${uid()}/${label}`], {
+		ignoreError: true,
+		silent: true,
+	});
+	if (existsSync(plist)) rmSync(plist);
+	console.log(`🗑  已卸载 ${label}（plist 已删除，不再开机自启）`);
+}
+
+function uninstallSystemd(opts) {
+	const name = opts.name ?? "pi-web-ui";
+	ensureRootForSystemctl();
+	run("systemctl", ["disable", "--now", `${name}.service`], {
+		ignoreError: true,
+	});
+	const unitPath = systemdUnitPath(name);
+	if (existsSync(unitPath)) rmSync(unitPath);
+	run("systemctl", ["daemon-reload"]);
+	console.log(`🗑  已卸载 ${name}.service（不再开机自启）`);
+}
+
+function controlService(action, opts) {
+	const name = opts.name ?? "pi-web-ui";
+
+	if (isMac) {
+		const label = serviceLabel(name);
+		const target = `gui/${uid()}/${label}`;
+		const loaded = () =>
+			spawnSync("launchctl", ["print", target], { stdio: "ignore" }).status ===
+			0;
+
+		if (action === "status") {
+			if (loaded()) {
+				const res = spawnSync("launchctl", ["print", target], {
+					encoding: "utf8",
+				});
+				const state = (res.stdout.match(/state = (\w+)/) ?? [])[1] ?? "loaded";
+				console.log(`${label}: ${state}（已加载，开机自启中）`);
+			} else {
+				console.log(`${label}: 未安装（运行 pi-web-ui server install 安装）`);
+			}
+			return;
+		}
+
+		if (action === "start") {
+			if (loaded()) {
+				run("launchctl", ["kickstart", target]);
+			} else {
+				const plist = launchAgentPlist(name);
+				if (!existsSync(plist)) {
+					fail(`找不到 ${plist}，请先运行 pi-web-ui server install`);
+				}
+				run("launchctl", ["bootstrap", `gui/${uid()}`, plist]);
+			}
+			console.log(`✅ 已启动 ${label}`);
+			return;
+		}
+
+		if (action === "restart") {
+			if (!loaded()) fail(`${label} 未加载，请先 pi-web-ui server start`);
+			run("launchctl", ["kickstart", "-k", target]);
+			console.log(`✅ 已重启 ${label}`);
+			return;
+		}
+
+		if (action === "stop") {
+			run("launchctl", ["bootout", target], {
+				ignoreError: true,
+				silent: true,
+			});
+			console.log(`⏹  已停止 ${label}（已卸载，不再开机自启；start 恢复）`);
+			return;
+		}
+
+		fail(`未知操作: ${action}`);
+	}
+
+	if (isLinux) {
+		ensureRootForSystemctl();
+		if (action === "status") {
+			run("systemctl", ["status", `${name}.service`, "--no-pager"]);
+			return;
+		}
+		run("systemctl", [action, `${name}.service`]);
+		console.log(`✅ ${action} ${name}.service`);
+		return;
+	}
+
+	fail(`不支持的系统服务平台: ${process.platform}（仅 macOS / Linux）`);
+}
+
+async function serverCmd(argv) {
+	const { opts, positionals } = parseFlags(argv);
+	if (opts.help) {
+		console.log(HELP);
+		return;
+	}
+	if (positionals.length === 0) {
+		console.log(HELP);
+		console.log("--- 当前服务状态 ---");
+		controlService("status", opts);
+		return;
+	}
+	const action = positionals[0];
+	if (positionals.length > 1)
+		fail(`多余的参数: ${positionals.slice(1).join(" ")}`);
+	switch (action) {
+		case "install": {
+			if (isMac) {
+				installLaunchd(opts);
+			} else if (isLinux) {
+				installSystemd(opts);
+			} else {
+				fail(`不支持的系统服务平台: ${process.platform}（仅 macOS / Linux）`);
+			}
+			break;
+		}
+		case "uninstall": {
+			if (isMac) {
+				uninstallLaunchd(opts);
+			} else if (isLinux) {
+				uninstallSystemd(opts);
+			} else {
+				fail(`不支持的系统服务平台: ${process.platform}（仅 macOS / Linux）`);
+			}
+			break;
+		}
+		case "start":
+		case "stop":
+		case "restart":
+		case "status":
+			controlService(action, opts);
+			break;
+		default:
+			fail(
+				`未知操作: ${action}（install / uninstall / start / stop / restart / status）`,
+			);
+	}
+}
+
+async function main() {
+	const argv = process.argv.slice(2);
+	if (argv.length === 0) {
+		await startForeground({});
+		return;
+	}
+	const first = argv[0];
+	if (first === "--version" || first === "-v") {
+		console.log(pkg.version);
+		return;
+	}
+	if (first === "--help" || first === "-h") {
+		console.log(HELP);
+		return;
+	}
+	if (first === "server") {
+		await serverCmd(argv.slice(1));
+		return;
+	}
+	// One-shot server with optional --port/--cwd/--data-dir overrides.
+	const { opts, positionals } = parseFlags(argv);
+	if (opts.help) {
+		console.log(HELP);
+		return;
+	}
+	if (positionals.length > 0)
+		fail(`未知命令: ${positionals[0]}（--help 查看用法）`);
+	await startForeground(opts);
+}
+
+main().catch((err) => {
+	console.error(`✖ ${err instanceof Error ? err.message : String(err)}`);
+	process.exit(1);
+});