@rexvane/piweb 0.3.1

package/src/lib/update-service.ts

@@ -0,0 +1,129 @@
+/**
+ * Fixed-command update preparation followed by a checked, isolated Next release.
+ * Source/node_modules changes are not snapshots: run only in a maintenance window.
+ * No serving process is stopped, and a build is selected only on a manual restart.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { installPiUpdate, PI_PACKAGE, prepareRelease } from "../../scripts/release.mjs";
+import { assertInstallation } from "../../scripts/build-output.mjs";
+import { runCommand } from "../../scripts/process-runner.mjs";
+import { isNewer } from "./semver";
+import { samePath } from "./path-security";
+import { getRuntimeVersions } from "./version";
+import { APP_ROOT } from "./app-root";
+
+export type UpdateTarget = "piweb" | "pi";
+
+export interface UpdateCheck {
+	current: string;
+	latest: string;
+	canUpdate: boolean;
+	/** Only piweb: commits behind the branch which the update command pulls. */
+	behind?: number;
+}
+
+export interface UpdateResult {
+	version: string;
+	needsRestart: boolean;
+	buildDir: string;
+	buildId: string;
+}
+
+export class UpdateBusyError extends Error {}
+
+type CommandRunner = typeof runCommand;
+
+interface UpdateServiceOptions {
+	root?: string;
+	run?: CommandRunner;
+	versions?: typeof getRuntimeVersions;
+	env?: Record<string, string | undefined>;
+}
+
+function assertTarget(target: UpdateTarget): void {
+	if (target !== "piweb" && target !== "pi") throw new Error("unknown target");
+}
+
+async function readPackageVersion(filePath: string): Promise<string> {
+	const raw = JSON.parse(await fs.readFile(filePath, "utf8")) as { version?: unknown };
+	if (typeof raw.version !== "string" || !raw.version) throw new Error(`no version field in ${filePath}`);
+	return raw.version;
+}
+
+/** Injectable process runner/root: tests never contact registries or update this checkout. */
+export function createUpdateService({ root = APP_ROOT, run = runCommand, versions = getRuntimeVersions, env = process.env }: UpdateServiceOptions = {}) {
+	let updateRunning = false;
+	const commandEnv = { ...env };
+	delete commandEnv.PI_WEB_PASSWORD;
+
+	async function checkedRoot(): Promise<string> {
+		return assertInstallation(root);
+	}
+
+	async function checkForUpdate(target: UpdateTarget): Promise<UpdateCheck> {
+		assertTarget(target);
+		if (updateRunning) throw new UpdateBusyError("an update is already running");
+		const installation = await checkedRoot();
+		const command = (cmd: string, args: string[], timeoutMs: number) => run(cmd, args, { cwd: installation, env: commandEnv, timeoutMs });
+		const { piWeb, piEngine } = await versions();
+		if (target === "pi") {
+			const latest = (await command("npm", ["view", PI_PACKAGE, "version"], 30_000)).trim().split(/\r?\n/)[0];
+			return { current: piEngine, latest, canUpdate: isNewer(latest, piEngine) };
+		}
+		await command("git", ["fetch", "origin", "main", "--tags"], 30_000);
+		const behind = Number((await command("git", ["rev-list", "--count", "HEAD..origin/main"], 15_000)).trim());
+		if (!Number.isSafeInteger(behind) || behind < 0) throw new Error("invalid upstream commit count");
+		const remotePkg = JSON.parse(await command("git", ["show", "origin/main:package.json"], 15_000)) as { name?: string; version?: string };
+		if ((remotePkg.name !== "piweb" && remotePkg.name !== "pi-web") || typeof remotePkg.version !== "string" || !remotePkg.version) throw new Error("upstream is not a PiWeb package");
+		// Do not advertise a tag version that `git pull origin main` will never install.
+		return { current: piWeb, latest: remotePkg.version, behind, canUpdate: isNewer(remotePkg.version, piWeb) || behind > 0 };
+	}
+
+	async function runUpdate(target: UpdateTarget, { assertIdle = async () => {} }: { assertIdle?: () => Promise<void> } = {}): Promise<UpdateResult> {
+		assertTarget(target);
+		if (updateRunning) throw new UpdateBusyError("an update is already running");
+		updateRunning = true;
+		try {
+			const installation = await checkedRoot();
+			let version = "";
+			const release = await prepareRelease({
+				root: installation, env, run,
+				beforePrepare: async () => {
+					await assertIdle();
+					if (target === "piweb") {
+						const command = (args: string[]) => run("git", args, { cwd: installation, env: commandEnv, timeoutMs: 15_000 });
+						const top = (await command(["rev-parse", "--show-toplevel"])).trim();
+						// Git may report a differently cased or 8.3-shortened path; compare canonically.
+						const realTop = await fs.realpath(top).catch(() => path.resolve(top));
+						if (!samePath(realTop, installation)) throw new Error("refusing to update: PiWeb is not the Git installation root");
+						if ((await command(["status", "--porcelain", "--untracked-files=no"])).trim()) {
+							throw new Error("PiWeb has local tracked changes; preserve them before updating (no files were reset)");
+						}
+					}
+					await assertIdle();
+				},
+				prepare: async (context) => {
+					const { env: releaseEnv, signal } = context;
+					const command = (cmd: string, args: string[], timeoutMs: number) => run(cmd, args, { cwd: installation, env: releaseEnv, timeoutMs, signal });
+					if (target === "pi") {
+						version = await installPiUpdate(context, assertIdle);
+					} else {
+						await assertIdle();
+						await command("git", ["pull", "--ff-only", "origin", "main"], 120_000);
+						assertInstallation(installation);
+						await assertIdle();
+						await command("npm", ["install", "--no-audit", "--no-fund"], 600_000);
+						version = await readPackageVersion(path.join(installation, "package.json"));
+					}
+				},
+			});
+			return { ...release, version, needsRestart: true };
+		} finally { updateRunning = false; }
+	}
+	return { checkForUpdate, runUpdate };
+}
+
+const service = createUpdateService();
+export const checkForUpdate = service.checkForUpdate;
+export const runUpdate = service.runUpdate;

package/src/lib/version.ts

@@ -0,0 +1,6 @@
+import { VERSION as PI_ENGINE_VERSION } from "@earendil-works/pi-coding-agent";
+import appManifest from "../../package.json";
+
+export function getRuntimeVersions(): Promise<{ piWeb: string; piEngine: string }> {
+	return Promise.resolve({ piWeb: appManifest.version, piEngine: PI_ENGINE_VERSION });
+}

package/src/lib/web-auth-shared.ts

@@ -0,0 +1,35 @@
+/**
+ * 会话认证的共享部分（客户端安全，无 node 内置模块依赖）：
+ * 登录页与 proxy / API 路由都用这些常量与纯函数。
+ */
+
+export const SESSION_COOKIE = "piweb_session";
+export const SESSION_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+
+/** 登录后跳转目标白名单：仅同源相对路径，防开放重定向 */
+export function safeNextPath(value: string | null | undefined): string {
+	if (!value || !value.startsWith("/") || value.startsWith("//") || value.includes("\\")) return "/";
+	try {
+		const parsed = new URL(value, "http://localhost");
+		return parsed.origin === "http://localhost" ? `${parsed.pathname}${parsed.search}` : "/";
+	} catch {
+		return "/";
+	}
+}
+
+/** 从 Cookie 请求头里取指定 cookie */
+export function readCookieHeader(header: string | null, name: string): string | undefined {
+	if (!header) return undefined;
+	for (const part of header.split(";")) {
+		const eq = part.indexOf("=");
+		if (eq < 0) continue;
+		if (part.slice(0, eq).trim() === name) {
+			try {
+				return decodeURIComponent(part.slice(eq + 1).trim());
+			} catch {
+				return undefined;
+			}
+		}
+	}
+	return undefined;
+}

package/src/lib/web-auth.ts

@@ -0,0 +1,53 @@
+/**
+ * 会话认证（服务端）：登录页用密码换一个无状态令牌（HMAC 派生），存 httpOnly Cookie。
+ * Basic 认证保留为 API / 脚本兜底（bin/piweb.js 探活与 curl 依赖它）。
+ * 纯常量与浏览器安全函数在 web-auth-shared（登录页引用，不能带上 node:crypto）。
+ */
+import { createHmac } from "node:crypto";
+import { equalText } from "./auth";
+import { SESSION_COOKIE, SESSION_MAX_AGE_SECONDS, readCookieHeader, safeNextPath } from "./web-auth-shared";
+
+export { SESSION_COOKIE, SESSION_MAX_AGE_SECONDS, readCookieHeader, safeNextPath };
+
+/** 校验登录密码（恒定时间比较） */
+export function validPassword(candidate: string, password: string): boolean {
+	return equalText(candidate, password);
+}
+
+/** 令牌 = 过期时间戳 + 以密码为密钥的 HMAC。密码变更即全部令牌失效。 */
+export function createSessionToken(password: string, now = Date.now()): string {
+	const expires = now + SESSION_MAX_AGE_SECONDS * 1000;
+	return `${expires}.${sign(password, String(expires))}`;
+}
+
+export function validSessionToken(token: string | undefined | null, password: string, now = Date.now()): boolean {
+	if (!token) return false;
+	const separator = token.indexOf(".");
+	if (separator <= 0) return false;
+	const expires = Number(token.slice(0, separator));
+	if (!Number.isSafeInteger(expires) || expires <= now) return false;
+	return equalText(token.slice(separator + 1), sign(password, String(expires)));
+}
+
+function sign(password: string, payload: string): string {
+	return createHmac("sha256", `piweb-session:${password}`).update(payload).digest("base64url");
+}
+
+export function isSecureRequest(request: Request): boolean {
+	if (new URL(request.url).protocol === "https:") return true;
+	return (request.headers.get("x-forwarded-proto") ?? "").split(",")[0].trim() === "https";
+}
+
+export function sessionCookieOptions(request: Request) {
+	return {
+		httpOnly: true,
+		sameSite: "strict" as const,
+		secure: isSecureRequest(request),
+		path: "/",
+		maxAge: SESSION_MAX_AGE_SECONDS,
+	};
+}
+
+export function clearedCookieOptions(request: Request) {
+	return { ...sessionCookieOptions(request), maxAge: 0 };
+}

package/src/lib/workspace-store.ts

@@ -0,0 +1,261 @@
+/**
+ * workspace-store：手动添加的工作区注册表（~/.pi/agent/web-workspaces.json）。
+ * 会话 cwd + 手动添加的目录共同构成侧栏「工作区」列表；pi 不受影响（独立文件）。
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { APP_ROOT } from "./app-root";
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import { getAgentDir } from "./pi";
+import { randomUUID } from "node:crypto";
+import { withExternalSettingsLock, withSettingsWriteLock } from "./settings-write-lock";
+
+interface WorkspaceFile {
+	workspaces: string[];
+	aliases?: Record<string, string>;
+	archivedSessions?: string[];
+	removedWorkspaces?: string[];
+}
+
+export interface WorkspaceRegistrySnapshot {
+	workspaces: string[];
+	aliases: Record<string, string>;
+	archivedSessions: string[];
+	removedWorkspaces: string[];
+}
+
+function file(): string {
+	return path.join(getAgentDir(), "web-workspaces.json");
+}
+
+async function readFile(target = file()): Promise<WorkspaceFile> {
+	try {
+		const parsed = JSON.parse(await fs.readFile(target, "utf8")) as WorkspaceFile;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("invalid workspace registry");
+		const aliases = Object.fromEntries(
+			Object.entries(typeof parsed.aliases === "object" && parsed.aliases !== null ? parsed.aliases : {})
+				.filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+		);
+		return {
+			workspaces: Array.isArray(parsed.workspaces) ? parsed.workspaces.filter((w) => typeof w === "string") : [],
+			aliases,
+			archivedSessions: Array.isArray(parsed.archivedSessions) ? parsed.archivedSessions.filter((s) => typeof s === "string") : [],
+			removedWorkspaces: Array.isArray(parsed.removedWorkspaces) ? parsed.removedWorkspaces.filter((s) => typeof s === "string") : [],
+		};
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	return { workspaces: [], aliases: {}, archivedSessions: [], removedWorkspaces: [] };
+}
+
+function pathKey(value: string): string {
+	const resolved = path.resolve(value);
+	return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+async function write(data: WorkspaceFile, target: string): Promise<void> {
+	await fs.mkdir(path.dirname(target), { recursive: true });
+	const temporary = `${target}.${randomUUID()}.tmp`;
+	try {
+		await fs.writeFile(temporary, JSON.stringify(data, null, 2), { encoding: "utf8", flag: "wx", mode: 0o600 });
+		await fs.rename(temporary, target);
+	} finally {
+		await fs.unlink(temporary).catch(() => undefined);
+	}
+}
+
+async function read(): Promise<WorkspaceFile> {
+	const target = file();
+	return withSettingsWriteLock(target, () => readFile(target));
+}
+
+async function mutate<T>(change: (data: WorkspaceFile, target: string) => Promise<T> | T): Promise<T> {
+	const target = file();
+	return withSettingsWriteLock(target, () => withExternalSettingsLock(target, async () => change(await readFile(target), target)));
+}
+
+export async function listAdded(): Promise<string[]> {
+	return (await read()).workspaces;
+}
+
+export async function getRemovedWorkspaces(): Promise<string[]> {
+	return (await read()).removedWorkspaces ?? [];
+}
+
+export async function getAliases(): Promise<Record<string, string>> {
+	return (await read()).aliases ?? {};
+}
+
+export async function setAlias(dir: string, name: string): Promise<Record<string, string>> {
+	const key = pathKey(path.resolve(dir));
+	return mutate(async (data, target) => {
+		if (!data.aliases) data.aliases = {};
+		// 键统一走 pathKey（win32 小写），并清掉历史遗留的大小写变体，避免别名时有时无
+		for (const existing of Object.keys(data.aliases)) {
+			if (existing !== key && pathKey(existing) === key) delete data.aliases[existing];
+		}
+		if (name.trim()) {
+			data.aliases[key] = name.trim();
+		} else {
+			delete data.aliases[key];
+		}
+		await write(data, target);
+		return data.aliases;
+	});
+}
+
+export async function getArchivedSessions(): Promise<string[]> {
+	return (await read()).archivedSessions ?? [];
+}
+
+export async function getWorkspaceRegistry(): Promise<WorkspaceRegistrySnapshot> {
+	const data = await read();
+	return {
+		workspaces: data.workspaces,
+		aliases: data.aliases ?? {},
+		archivedSessions: data.archivedSessions ?? [],
+		removedWorkspaces: data.removedWorkspaces ?? [],
+	};
+}
+
+export async function archiveSession(sessionPath: string): Promise<string[]> {
+	const norm = path.resolve(sessionPath);
+	const key = pathKey(norm);
+	return mutate(async (data, target) => {
+		if (!data.archivedSessions) data.archivedSessions = [];
+		if (!data.archivedSessions.some((p) => pathKey(p) === key)) {
+			data.archivedSessions.push(norm);
+			await write(data, target);
+		}
+		return data.archivedSessions;
+	});
+}
+
+export async function forgetSession(sessionPath: string): Promise<string[]> {
+	const norm = path.resolve(sessionPath);
+	const key = pathKey(norm);
+	return mutate(async (data, target) => {
+		const previous = data.archivedSessions ?? [];
+		const next = previous.filter((p) => pathKey(p) !== key);
+		if (next.length !== previous.length) {
+			data.archivedSessions = next;
+			await write(data, target);
+		}
+		return next;
+	});
+}
+
+export async function addWorkspace(dir: string): Promise<{ workspaces: string[]; removedWorkspaces: string[] }> {
+	const norm = path.resolve(dir);
+	const key = pathKey(norm);
+	return mutate(async (data, target) => {
+		let changed = false;
+		if (!data.workspaces.some((w) => pathKey(w) === key)) {
+			data.workspaces.push(norm);
+			changed = true;
+		}
+		if (data.removedWorkspaces) {
+			const next = data.removedWorkspaces.filter((w) => pathKey(w) !== key);
+			changed ||= next.length !== data.removedWorkspaces.length;
+			data.removedWorkspaces = next;
+		}
+		if (changed) await write(data, target);
+		return { workspaces: data.workspaces, removedWorkspaces: data.removedWorkspaces ?? [] };
+	});
+}
+
+export async function registerCwds(cwds: string[]): Promise<string[]> {
+	return mutate(async (data, target) => {
+		let changed = false;
+		const removedKeys = new Set((data.removedWorkspaces ?? []).map(pathKey));
+		const existingKeys = new Set(data.workspaces.map(pathKey));
+
+		for (const cwd of cwds) {
+			if (!cwd || typeof cwd !== "string") continue;
+			const norm = path.resolve(cwd);
+			const key = pathKey(norm);
+			if (!removedKeys.has(key) && !existingKeys.has(key)) {
+				data.workspaces.push(norm);
+				existingKeys.add(key);
+				changed = true;
+			}
+		}
+		if (changed) await write(data, target);
+		return data.workspaces;
+	});
+}
+
+export async function removeWorkspace(dir: string): Promise<{ workspaces: string[]; removedWorkspaces: string[]; aliases: Record<string, string> }> {
+	const norm = path.resolve(dir);
+	const key = pathKey(norm);
+	return mutate(async (data, target) => {
+		data.workspaces = data.workspaces.filter((w) => pathKey(w) !== key);
+		if (!data.removedWorkspaces) data.removedWorkspaces = [];
+		if (!data.removedWorkspaces.some((w) => pathKey(w) === key)) {
+			data.removedWorkspaces.push(norm);
+		}
+		if (data.aliases) {
+			for (const k of Object.keys(data.aliases)) {
+				if (pathKey(k) === key) delete data.aliases[k];
+			}
+		}
+		await write(data, target);
+		return { workspaces: data.workspaces, removedWorkspaces: data.removedWorkspaces, aliases: data.aliases ?? {} };
+	});
+}
+
+let picking = false;
+
+/** 弹出系统原生文件夹选择对话框（Windows 现代资源管理器风格，屏幕居中） */
+export async function pickFolderNative(): Promise<{ path: string | null; canceled: boolean }> {
+	if (process.platform !== "win32") throw new Error("native folder picker is currently available only on Windows");
+	if (picking) return { path: null, canceled: true };
+	picking = true;
+	try {
+		const script = path.join(APP_ROOT, "scripts", "pick-folder.ps1");
+		const out = await new Promise<string>((resolve, reject) => {
+			const child = spawn(
+				"powershell.exe",
+				["-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-File", script, "选择工作区文件夹"],
+				// windowsHide：不再先闪出一个黑色 PowerShell 控制台窗口，只出现资源管理器风格的选择对话框
+				{ stdio: ["ignore", "pipe", "pipe"], windowsHide: true },
+			);
+			const decoder = new StringDecoder("utf8");
+			let buf = "";
+			let stderr = "";
+			let decoderEnded = false;
+			child.stdout.on("data", (data: Buffer) => {
+				buf += decoder.write(data);
+			});
+			child.stderr.on("data", (data: Buffer) => { stderr = (stderr + data.toString("utf8")).slice(-1000); });
+			let settled = false;
+			let timeout: ReturnType<typeof setTimeout>;
+			const finish = (error?: Error) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timeout);
+				if (!decoderEnded) {
+					decoderEnded = true;
+					buf += decoder.end();
+				}
+				if (error) reject(error);
+				else resolve(buf.trim());
+			};
+			child.on("error", (error) => finish(error));
+			child.on("close", (code) => finish(code === 0 ? undefined : new Error(stderr || `folder picker exited with code ${code}`)));
+			// 5 分钟超时保护
+			timeout = setTimeout(() => {
+				try {
+					child.kill();
+				} catch {
+					/* ignore */
+				}
+				finish(new Error("folder picker timed out"));
+			}, 5 * 60 * 1000);
+		});
+		return out ? { path: out, canceled: false } : { path: null, canceled: true };
+	} finally {
+		picking = false;
+	}
+}

package/src/proxy.ts

@@ -0,0 +1,53 @@
+import { NextResponse, type NextRequest } from "next/server";
+import { isSafeHost, isSafeOrigin, validBasicAuthorization } from "@/lib/auth";
+import { SESSION_COOKIE, readCookieHeader, validSessionToken } from "@/lib/web-auth";
+
+const READ_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+/** 未认证也可达：登录页自身与认证接口 */
+const PUBLIC_PATHS = new Set(["/login", "/api/web-auth"]);
+/** 静态资源不参与认证（dev 的 assetPrefix 是 /_piweb-dev/<id>，生产是 /_next） */
+const ASSET_PREFIXES = ["/_next/", "/_piweb-dev/"];
+const ASSET_PATHS = new Set(["/icon.svg", "/favicon.ico"]);
+
+export function proxy(request: NextRequest) {
+	const password = process.env.PI_WEB_PASSWORD;
+	if (!isSafeHost(request, Boolean(password))) {
+		return NextResponse.json({ success: false, error: "untrusted host" }, { status: 403 });
+	}
+	if (!READ_METHODS.has(request.method) && !isSafeOrigin(request)) {
+		return NextResponse.json({ success: false, error: "cross-origin request rejected" }, { status: 403 });
+	}
+
+	if (!password) return NextResponse.next();
+
+	const pathname = request.nextUrl.pathname;
+	if (pathname === "/api/health" && (request.method === "GET" || request.method === "HEAD")) return NextResponse.next();
+	if (ASSET_PREFIXES.some((prefix) => pathname.startsWith(prefix)) || ASSET_PATHS.has(pathname)) return NextResponse.next();
+
+	const authenticated =
+		validBasicAuthorization(request.headers.get("authorization"), password) ||
+		validSessionToken(readCookieHeader(request.headers.get("cookie"), SESSION_COOKIE), password);
+	if (authenticated) return NextResponse.next();
+
+	if (PUBLIC_PATHS.has(pathname)) return NextResponse.next();
+
+	// 页面请求 → 登录页（带返回地址）；API → 401，保留脚本客户端的 Basic 挑战。
+	if (pathname.startsWith("/api/")) {
+		return new NextResponse(JSON.stringify({ success: false, error: "authentication required" }), {
+			status: 401,
+			headers: {
+				"Content-Type": "application/json; charset=utf-8",
+				"WWW-Authenticate": 'Basic realm="PiWeb", charset="UTF-8"',
+				"Cache-Control": "no-store",
+			},
+		});
+	}
+	const login = request.nextUrl.clone();
+	login.pathname = "/login";
+	login.search = `?next=${encodeURIComponent(`${pathname}${request.nextUrl.search}`)}`;
+	return NextResponse.redirect(login, 307);
+}
+
+export const config = {
+	matcher: ["/((?!_next/|_piweb-dev/|icon\\.svg|favicon\\.ico).*)"],
+};

package/tsconfig.json

@@ -0,0 +1,49 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    ".next-dev/types/**/*.ts",
+    ".next-dev/dev/types/**/*.ts",
+    ".next-dev-webpack/types/**/*.ts",
+    ".next-dev-webpack/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    ".next-releases",
+    "pi",
+    "dsh",
+    "bin"
+  ]
+}