@rexvane/piweb 0.3.1

package/scripts/launcher.mjs

@@ -0,0 +1,249 @@
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { assertInstallation, selectProductionBuild } from "./build-output.mjs";
+import { ensureInstallBuild, isProductionOnlyInstall } from "./install-build.mjs";
+export { isMainModule } from "./entrypoint.mjs";
+
+const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** @typedef {Record<string, string | undefined>} Environment */
+/** @typedef {{port: number, hostname: string, noOpen: boolean, isDev: boolean, help: boolean}} ParsedOptions */
+/** @typedef {import('node:events').EventEmitter & {kill(signal?: NodeJS.Signals | number): boolean}} LauncherChild */
+/**
+ * @typedef {Object} LauncherOptions
+ * @property {string[]} [args]
+ * @property {Environment} [env]
+ * @property {string} [root]
+ * @property {{log?: (message: string) => void, probePort?: typeof probePort,
+ * isPiWebRunning?: typeof isPiWebRunning, openBrowser?: (url: string) => Promise<void>,
+ * spawn?: (command: string, args: string[], options: import('node:child_process').SpawnOptions) => LauncherChild}} [dependencies]
+ */
+
+export function isLoopback(hostname) {
+	const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+	if (host === "localhost") return true;
+	if (net.isIP(host) === 4) return host.startsWith("127.");
+	return net.isIP(host) === 6 && new URL(`http://[${host}]`).hostname === "[::1]";
+}
+
+function normalizeHostname(value) {
+	if (typeof value !== "string" || !value) throw new Error("无效监听地址");
+	const host = value.toLowerCase().replace(/^\[([^\]]+)\]$/, "$1");
+	if (net.isIP(host)) return host;
+	if (host.length > 253 || !host.split(".").every((part) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(part))) {
+		throw new Error(`无效监听地址：${value}`);
+	}
+	return host;
+}
+
+/** @param {string[]} [args] @param {Environment} [env] @returns {ParsedOptions} */
+export function parseLauncherArgs(args = [], env = process.env) {
+	let port = Number(env.PORT || 30141);
+	let hostname = env.PI_WEB_HOSTNAME || "127.0.0.1";
+	let noOpen = env.PI_WEB_NO_OPEN === "1";
+	let isDev = env.PI_WEB_DEV === "1";
+	let help = false;
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === "-p" || arg === "--port") port = Number(args[++i]);
+		else if (arg.startsWith("--port=")) port = Number(arg.slice(7));
+		else if (arg === "-H" || arg === "--hostname") hostname = args[++i];
+		else if (arg.startsWith("--hostname=")) hostname = arg.slice(11);
+		else if (arg === "--no-open") noOpen = true;
+		else if (arg === "--dev") isDev = true;
+		else if (arg === "-h" || arg === "--help") help = true;
+		else throw new Error(`未知参数：${arg}`);
+	}
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`无效端口：${port}`);
+	return { port, hostname: normalizeHostname(hostname), noOpen, isDev, help };
+}
+
+/**
+ * @param {string} root
+ * @param {ParsedOptions} options
+ * @param {Environment} [env]
+ * @returns {{root: string, command: 'dev' | 'start', env: Environment}}
+ */
+export function createLaunchPlan(root, options, env = process.env) {
+	const loopback = isLoopback(options.hostname);
+	if (!loopback && options.isDev) {
+		throw new Error("拒绝非本机开发模式：PI_WEB_PASSWORD 不能保护 Next 开发工具端点。请绑定 127.0.0.1，或先运行 npm run build:release 后用生产模式启动。");
+	}
+	if (!loopback && !env.PI_WEB_PASSWORD) throw new Error("拒绝无密码的非本机监听。请设置 PI_WEB_PASSWORD，或绑定 127.0.0.1。");
+	const installation = assertInstallation(root);
+	const build = options.isDev ? null : selectProductionBuild(installation, env.PIWEB_BUILD_DIR);
+	if (!build && !loopback) {
+		throw new Error("找不到可用生产构建，拒绝对外自动回退到开发模式。请先运行 npm run build:release，再以相同启动参数重试。");
+	}
+	const command = options.isDev || !build ? "dev" : "start";
+	const childEnv = {
+		...env,
+		PI_WEB_ROOT: installation,
+		PYTHONUTF8: env.PYTHONUTF8 ?? "1",
+		PYTHONIOENCODING: env.PYTHONIOENCODING ?? "utf-8",
+	};
+	if (command === "start") childEnv.PIWEB_BUILD_DIR = build.buildDir;
+	else {
+		delete childEnv.PIWEB_BUILD_DIR;
+		childEnv.PIWEB_DEV_ASSET_ID = `${Date.now().toString(36)}-${process.pid.toString(36)}`;
+		childEnv.NODE_OPTIONS = [env.NODE_OPTIONS, "--max-old-space-size=3072"].filter(Boolean).join(" ");
+	}
+	return { root: installation, command, env: childEnv };
+}
+
+export function localUrl(hostname, port) {
+	const host = hostname === "0.0.0.0" ? "127.0.0.1" : hostname === "::" ? "::1" : hostname;
+	return `http://${net.isIP(host) === 6 ? `[${host}]` : host}:${port}`;
+}
+
+/**
+ * Never send credentials to a port occupant, even if it forges PiWeb JSON/401.
+ * @param {string} base
+ * @param {{fetchImpl?: typeof fetch, timeoutMs?: number, signal?: AbortSignal}} [options]
+ * @returns {Promise<boolean>}
+ */
+export async function isPiWebRunning(base, { fetchImpl = fetch, timeoutMs = 1500, signal } = {}) {
+	try {
+		const url = new URL("/api/health", base);
+		if (url.username || url.password || url.protocol !== "http:") return false;
+		const timeout = AbortSignal.timeout(timeoutMs);
+		const response = await fetchImpl(url, {
+			credentials: "omit",
+			redirect: "error",
+			headers: { accept: "application/json" },
+			signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+		});
+		if (response.status !== 200 || !response.body) return false;
+		const reader = response.body.getReader();
+		let text = "";
+		let bytes = 0;
+		const decoder = new TextDecoder();
+		try {
+			for (;;) {
+				const chunk = await reader.read();
+				if (chunk.done) break;
+				bytes += chunk.value.byteLength;
+				if (bytes > 4096) return false;
+				text += decoder.decode(chunk.value, { stream: true });
+			}
+			text += decoder.decode();
+		} finally {
+			await reader.cancel().catch(() => {});
+			reader.releaseLock();
+		}
+		const body = JSON.parse(text);
+		return body?.success === true && body?.data?.ok === true && body?.data?.service === "piweb";
+	} catch {
+		return false;
+	}
+}
+
+/** @param {number} port @param {string} hostname @returns {Promise<'busy' | 'free' | NodeJS.ErrnoException>} */
+export function probePort(port, hostname) {
+	return new Promise((resolve) => {
+		const server = net.createServer();
+		server.once("error", (error) => resolve(error.code === "EADDRINUSE" ? "busy" : error));
+		server.once("listening", () => server.close(() => resolve("free")));
+		server.listen({ port, host: hostname, exclusive: true });
+	});
+}
+
+async function openBrowser(url) {
+	const command = process.platform === "win32" ? "cmd.exe" : process.platform === "darwin" ? "open" : "xdg-open";
+	const args = process.platform === "win32" ? ["/d", "/c", "start", "", url] : [url];
+	const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+	child.once("error", () => {});
+	child.unref();
+}
+
+/**
+ * Import-safe entrypoint; injectable I/O keeps launcher tests off real services.
+ * @param {LauncherOptions} [options]
+ * @returns {Promise<number>}
+ */
+export async function runLauncher({ args = process.argv.slice(2), env = process.env, root = DEFAULT_ROOT, dependencies = {} } = {}) {
+	const options = parseLauncherArgs(args, env);
+	const log = dependencies.log ?? console.log;
+	if (options.help) {
+		log("Usage: pi web [-p, --port <port>] [-H, --hostname <host>] [--dev] [--no-open]");
+		log("默认绑定 127.0.0.1:30141；端口被占自动 +1。开发模式仅允许本机监听。");
+		log("对外监听必须使用生产构建与 PI_WEB_PASSWORD。构建/恢复发布：npm run build:release。");
+		return 0;
+	}
+	// Validate before probing/reusing: an existing server must not hide an unsafe request.
+	// Production-only installs (`npm i -g piweb`) have no dev dependencies, so the
+	// development fallback is unusable there: prepare the one-time build first.
+	if (!options.isDev) {
+		const prepared = ensureInstallBuild(root, { log, warn: dependencies.warn ?? console.warn });
+		if (prepared === "failed" && isProductionOnlyInstall(root)) {
+			throw new Error("无法准备生产构建，且该安装没有开发依赖。请用 `npm rebuild -g piweb` 重试，或改用仓库中的 npm run dev。");
+		}
+	}
+	const plan = createLaunchPlan(root, options, env);
+	const checkPort = dependencies.probePort ?? probePort;
+	const checkHealth = dependencies.isPiWebRunning ?? isPiWebRunning;
+	const browse = dependencies.openBrowser ?? openBrowser;
+	const start = dependencies.spawn ?? spawn;
+	let port = options.port;
+	for (let attempts = 0; ; attempts += 1) {
+		const state = await checkPort(port, options.hostname);
+		if (state === "free") break;
+		if (state !== "busy") throw new Error(`无法监听 ${options.hostname}:${port}：${state.code ?? state.message ?? state}`);
+		const url = localUrl(options.hostname, port);
+		if (await checkHealth(url)) {
+			log(`[piweb] 检测到已有 PiWeb：${url}（未发送凭据）`);
+			if (!options.noOpen) await browse(url);
+			return 0;
+		}
+		if (attempts >= 50 || port >= 65535) throw new Error(`连续 ${attempts + 1} 个端口都被占用，请用 -p 指定端口`);
+		log(`[piweb] 端口 ${port} 被占用，尝试 ${port + 1}`);
+		port += 1;
+	}
+	const url = localUrl(options.hostname, port);
+	log(`[piweb] 启动 ${url} (${plan.command} 模式)`);
+	if (env.PI_WEB_PASSWORD) log(plan.command === "dev" ? "[piweb] 开发模式仅限本机；密码不保护 Next 开发工具端点。" : "[piweb] 已启用密码认证（浏览器登录页，API 兼容 Basic 用户名 pi）");
+	if (!isLoopback(options.hostname)) {
+		for (const addresses of Object.values(os.networkInterfaces())) {
+			for (const address of addresses ?? []) {
+				if (address.family === "IPv4" && !address.internal && !address.address.startsWith("169.254.")) {
+					log(`[piweb] 局域网/手机访问地址（需同一网络；已启用密码认证）：http://${address.address}:${port}`);
+				}
+			}
+		}
+	}
+	const next = path.join(plan.root, "node_modules", "next", "dist", "bin", "next");
+	const child = start(process.execPath, [next, plan.command, ...(plan.command === "dev" ? ["--webpack"] : []), "-p", String(port), "-H", options.hostname], {
+		cwd: plan.root, stdio: "inherit", env: plan.env,
+	});
+	const controller = new AbortController();
+	let timer;
+	const ready = async (attempt = 0) => {
+		if (controller.signal.aborted || attempt > 120) return;
+		if (await checkHealth(url, { signal: controller.signal })) {
+			if (controller.signal.aborted) return;
+			log(`[piweb] 就绪：${url}`);
+			if (!options.noOpen) await browse(url);
+		} else if (!controller.signal.aborted) {
+			timer = setTimeout(() => void ready(attempt + 1), 500);
+			timer.unref();
+		}
+	};
+	return new Promise((resolve, reject) => {
+		const interrupt = () => { child.kill("SIGINT"); };
+		const terminate = () => { child.kill("SIGTERM"); };
+		const cleanup = () => {
+			controller.abort();
+			clearTimeout(timer);
+			process.off("SIGINT", interrupt);
+			process.off("SIGTERM", terminate);
+		};
+		process.once("SIGINT", interrupt);
+		process.once("SIGTERM", terminate);
+		child.once("error", (error) => { cleanup(); reject(error); });
+		child.once("exit", (code) => { cleanup(); resolve(code ?? 1); });
+		void ready().catch(() => {});
+	});
+}

package/scripts/pick-folder.ps1

@@ -0,0 +1,110 @@
+# Pop the Windows modern folder picker (IFileOpenDialog, Explorer style, centered).
+# Usage: powershell -NoProfile -STA -ExecutionPolicy Bypass -File pick-folder.ps1 [title]
+# Output: the selected path on one line; empty when canceled.
+#
+# Encoding contract: this file must stay pure ASCII. Windows PowerShell 5.1 reads
+# BOM-less .ps1 files with the active ANSI code page (GBK on zh-CN), so any literal
+# CJK character here would reach the dialog mojibake'd. Non-ASCII UI strings are
+# embedded as C# \uXXXX escapes instead.
+param([string]$Title = 'Select workspace folder')
+
+# PowerShell 5.1 otherwise emits text using the active Windows code page.
+try {
+  [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+  $OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+} catch {}
+
+$src = @'
+using System;
+using System.Runtime.InteropServices;
+
+public class PiFolderPicker {
+  [ComImport, Guid("DC1C5A9C-E88A-4dde-A5A1-60F82A20AEF7")]
+  private class FileOpenDialogRCW {}
+
+  [ComImport, Guid("D57C7288-D4AD-4768-BE02-9D969532D960"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  private interface IFileDialog {
+    [PreserveSig] int Show(IntPtr hwndOwner);
+    [PreserveSig] int SetFileTypes(uint cFileTypes, IntPtr rgFilterSpec);
+    [PreserveSig] int SetFileTypeIndex(uint iFileType);
+    [PreserveSig] int GetFileTypeIndex(out uint piFileType);
+    [PreserveSig] int Advise(IntPtr pfde, out uint pdwCookie);
+    [PreserveSig] int Unadvise(uint pdwCookie);
+    [PreserveSig] int SetOptions(uint fos);
+    [PreserveSig] int GetOptions(out uint pfos);
+    [PreserveSig] int SetDefaultFolder(IShellItem psi);
+    [PreserveSig] int SetFolder(IShellItem psi);
+    [PreserveSig] int GetFolder(out IShellItem ppsi);
+    [PreserveSig] int GetCurrentSelection(out IShellItem ppsi);
+    [PreserveSig] int SetFileName([MarshalAs(UnmanagedType.LPWStr)] string pszName);
+    [PreserveSig] int GetFileName([MarshalAs(UnmanagedType.LPWStr)] out string pszName);
+    [PreserveSig] int SetTitle([MarshalAs(UnmanagedType.LPWStr)] string pszTitle);
+    [PreserveSig] int SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string pszText);
+    [PreserveSig] int SetFileNameLabel([MarshalAs(UnmanagedType.LPWStr)] string pszLabel);
+    [PreserveSig] int GetResult(out IShellItem ppsi);
+    [PreserveSig] int AddPlace(IShellItem psi, int fdap);
+    [PreserveSig] int SetDefaultExtension([MarshalAs(UnmanagedType.LPWStr)] string pszDefaultExtension);
+    [PreserveSig] int Close(int hr);
+    [PreserveSig] int SetClientGuid(ref Guid guid);
+    [PreserveSig] int ClearClientData();
+    [PreserveSig] int SetFilter(IntPtr pFilter);
+  }
+
+  [ComImport, Guid("43826D1E-E718-42EE-BC55-A1E261C37BFE"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  private interface IShellItem {
+    [PreserveSig] int BindToHandler(IntPtr pbc, ref Guid bhid, ref Guid riid, out IntPtr ppv);
+    [PreserveSig] int GetParent(out IShellItem ppsi);
+    [PreserveSig] int GetDisplayName(uint sigdnName, [MarshalAs(UnmanagedType.LPWStr)] out string ppszName);
+    [PreserveSig] int GetAttributes(uint sfgaoMask, out uint psfgaoAttribs);
+    [PreserveSig] int Compare(IShellItem psi, uint hint, out int piOrder);
+  }
+
+  private const uint FOS_PICKFOLDERS = 0x20;
+  private const uint FOS_FORCEFILESYSTEM = 0x40;
+  private const uint SIGDN_FILESYSPATH = 0x80058000;
+
+  // Ok-button label ("select this folder", zh) as escapes: keep this .ps1 ASCII.
+  private const string OkLabel = "\u9009\u62E9\u6B64\u6587\u4EF6\u5939";
+
+  [DllImport("user32.dll")] private static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] private static extern bool SetProcessDpiAwarenessContext(IntPtr value);
+  [DllImport("user32.dll")] private static extern bool SetProcessDPIAware();
+
+  // A non-DPI-aware host process gets the dialog bitmap-stretched on scaled
+  // displays (blurry). Per-Monitor V2 (-4) keeps it crisp; fall back to the
+  // legacy declaration on pre-1703 Windows. Best effort: both may no-op when
+  // awareness is already set by a manifest.
+  private static void EnableDpiAwareness() {
+    try {
+      if (!SetProcessDpiAwarenessContext(new IntPtr(-4))) SetProcessDPIAware();
+    } catch {
+      try { SetProcessDPIAware(); } catch {}
+    }
+  }
+
+  public static string Pick(string title) {
+    try {
+      EnableDpiAwareness();
+      var dlg = (IFileDialog)(new FileOpenDialogRCW());
+      uint options;
+      dlg.GetOptions(out options);
+      dlg.SetOptions(options | FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM);
+      if (!string.IsNullOrEmpty(title)) dlg.SetTitle(title);
+      dlg.SetOkButtonLabel(OkLabel);
+      int hr = dlg.Show(GetForegroundWindow());
+      if (hr != 0) return "";
+      IShellItem item;
+      dlg.GetResult(out item);
+      string path;
+      item.GetDisplayName(SIGDN_FILESYSPATH, out path);
+      return path ?? "";
+    } catch {
+      return "";
+    }
+  }
+}
+'@
+
+Add-Type -TypeDefinition $src -Language CSharp
+$result = [PiFolderPicker]::Pick($Title)
+Write-Output $result

package/scripts/postinstall.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * npm postinstall hook: prepare the production build for production-only installs.
+ * The same helper also runs from the first `piweb` start, so installs that skip
+ * lifecycle scripts heal themselves on first use.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureInstallBuild } from "./install-build.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+ensureInstallBuild(root);

package/scripts/process-runner.mjs

@@ -0,0 +1,60 @@
+import { spawn } from "node:child_process";
+
+/** Kill only the command tree that this helper started, never the serving app. */
+async function terminateProcessTree(child) {
+	if (!child.pid) { child.kill(); return; }
+	if (process.platform !== "win32") {
+		try { process.kill(-child.pid, "SIGKILL"); } catch { child.kill("SIGKILL"); }
+		return;
+	}
+	await new Promise((resolve) => {
+		const killer = spawn("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+		const timer = setTimeout(() => { child.kill(); killer.kill(); resolve(); }, 10_000);
+		const done = () => { clearTimeout(timer); resolve(); };
+		killer.once("error", () => { child.kill(); done(); });
+		killer.once("close", done);
+	});
+}
+
+/**
+ * Fixed argument arrays, bounded output and whole-tree timeouts for update/build commands.
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{cwd: string, env?: Record<string, string | undefined>, timeoutMs?: number, signal?: AbortSignal}} options
+ * @returns {Promise<string>}
+ */
+export function runCommand(command, args, { cwd, env = process.env, timeoutMs = 600_000, signal }) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) { reject(new Error("release cancelled")); return; }
+		// Only npm needs cmd.exe to resolve npm.cmd. Never enable a general shell.
+		const npmShell = process.platform === "win32" && command === "npm";
+		const child = spawn(npmShell ? env.ComSpec || "cmd.exe" : command, npmShell ? ["/d", "/c", "npm", ...args] : args, {
+			cwd, env, windowsHide: true, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"],
+		});
+		let output = "";
+		let errorOutput = "";
+		let stopping = false;
+		let settled = false;
+		const cleanup = () => { clearTimeout(timer); signal?.removeEventListener("abort", abort); };
+		const fail = (error) => { if (!settled) { settled = true; cleanup(); reject(error); } };
+		const stop = (message) => {
+			if (settled || stopping) return;
+			stopping = true;
+			void terminateProcessTree(child).then(() => fail(new Error(message)), fail);
+		};
+		const abort = () => stop("release cancelled; command process tree terminated");
+		const timer = setTimeout(() => stop(`timeout after ${Math.round(timeoutMs / 1000)}s: ${command} ${args.join(" ")}`), timeoutMs);
+		signal?.addEventListener("abort", abort, { once: true });
+		if (signal?.aborted) abort();
+		child.stdout.on("data", (chunk) => { output = (output + chunk).slice(-256 * 1024); });
+		child.stderr.on("data", (chunk) => { errorOutput = (errorOutput + chunk).slice(-256 * 1024); });
+		child.once("error", (error) => { if (!stopping) fail(error); });
+		child.once("close", (code) => {
+			if (stopping || settled) return;
+			if (code !== 0) { fail(new Error((errorOutput || output || `exit code ${code}`).trim().slice(-1000))); return; }
+			settled = true;
+			cleanup();
+			resolve(output);
+		});
+	});
+}

package/scripts/release.mjs

@@ -0,0 +1,172 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { assertInstallation, assertLocalPath, readProductionBuild, resolveBuildOutput, RELEASES_DIR, RELEASE_MANIFEST } from "./build-output.mjs";
+import { runCommand } from "./process-runner.mjs";
+import { isMainModule } from "./entrypoint.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const LOCK_PATH = `${RELEASES_DIR}/update.lock`;
+const CONFIG_PATH = `${RELEASES_DIR}/tsconfig.json`;
+
+/** Rename within one directory: a launcher sees the complete old or new state. */
+async function atomicJson(root, relative, value) {
+	const target = assertLocalPath(root, relative);
+	const temporary = assertLocalPath(root, `${relative}.${randomUUID()}.tmp`);
+	const handle = await fs.open(temporary, "wx", 0o600);
+	try {
+		try {
+			await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+			await handle.sync();
+		} finally { await handle.close(); }
+		await fs.rename(temporary, target);
+	} finally { await fs.rm(temporary, { force: true }); }
+}
+
+async function acquireLock(root) {
+	const lockPath = assertLocalPath(root, LOCK_PATH);
+	let lock;
+	try { lock = await fs.open(lockPath, "wx", 0o600); }
+	catch (error) {
+		if (error.code === "EEXIST") throw new Error(`an update/build is already running (${lockPath}); after an interrupted build, confirm its process tree has stopped before removing this lock and retrying npm run build:release`);
+		throw error;
+	}
+	try { await lock.writeFile(JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })); }
+	catch (error) { await lock.close(); await fs.unlink(lockPath); throw error; }
+	return async () => { await lock.close(); await fs.unlink(lockPath); };
+}
+
+async function writeReleaseTypeConfig(root, buildDir) {
+	const id = buildDir.slice(`${RELEASES_DIR}/`.length);
+	await atomicJson(root, CONFIG_PATH, {
+		extends: "../tsconfig.json",
+		compilerOptions: { tsBuildInfoFile: `./${id}.tsbuildinfo` },
+		include: [
+			"../next-env.d.ts", "../*.ts", "../*.mts", "../src/**/*.ts", "../src/**/*.tsx",
+			"../tests/**/*.ts", "../tests/**/*.tsx", `./${id}/types/**/*.ts`, `./${id}/dev/types/**/*.ts`,
+		],
+		exclude: ["../node_modules", "../pi", "../dsh", "../bin"],
+	});
+}
+
+/** Run in a fresh process, after install/pull, so cached config/Next modules cannot lie. */
+export async function verifyReleaseConfig(root = process.cwd(), env = process.env) {
+	const installation = assertInstallation(root);
+	const buildDir = resolveBuildOutput(installation, env.PIWEB_BUILD_DIR);
+	if (!buildDir.startsWith(`${RELEASES_DIR}/`)) throw new Error("release requires an isolated build output");
+	const require = createRequire(path.join(installation, "package.json"));
+	const module = await import(pathToFileURL(require.resolve("next/dist/server/config.js")).href);
+	const loadConfig = typeof module.default === "function" ? module.default : module.default.default;
+	const { PHASE_PRODUCTION_BUILD } = require("next/constants");
+	const config = await loadConfig(PHASE_PRODUCTION_BUILD, installation, { silent: true });
+	if (config.distDir !== buildDir || config.typescript?.tsconfigPath !== CONFIG_PATH || config.typescript?.ignoreBuildErrors) {
+		throw new Error("Next config does not honor the isolated release directory/typecheck; refusing to build over the serving output");
+	}
+}
+
+export const PI_PACKAGE = "@earendil-works/pi-coding-agent";
+const PI_AI_PACKAGE = "@earendil-works/pi-ai";
+
+/**
+ * Shared by the UI and update:pi; called only after the building state is durable.
+ * @param {{root: string, env: Record<string, string | undefined>, run: typeof runCommand, signal?: AbortSignal}} context
+ * @param {() => Promise<void>} [assertIdle]
+ * @returns {Promise<string>}
+ */
+export async function installPiUpdate({ root, env, run, signal }, assertIdle = async () => {}) {
+	await assertIdle();
+	await run("npm", ["install", "--save-exact", `${PI_PACKAGE}@latest`, `${PI_AI_PACKAGE}@latest`, "--no-audit", "--no-fund"], {
+		cwd: root, env, timeoutMs: 600_000, signal,
+	});
+	await run("npm", ["run", "sync:provider-icons"], { cwd: root, env, timeoutMs: 60_000, signal });
+	const manifest = JSON.parse(await fs.readFile(path.join(root, "node_modules", PI_PACKAGE, "package.json"), "utf8"));
+	if (typeof manifest.version !== "string" || !manifest.version) throw new Error("Pi engine package version is missing");
+	return manifest.version;
+}
+
+/**
+ * Prepare one production output without touching the serving .next/release.
+ * Source/dependency preparation is deliberately a caller callback: this command
+ * alone never fetches Git or installs packages, and works in a no-Git source copy.
+ * @param {{root?: string, env?: Record<string, string | undefined>, run?: typeof runCommand,
+ * beforePrepare?: () => Promise<void>, prepare?: (context: {root: string, buildDir: string, env: Record<string, string | undefined>, run: typeof runCommand, signal?: AbortSignal}) => Promise<void>,
+ * signal?: AbortSignal}} options
+ */
+export async function prepareRelease({ root = ROOT, env = process.env, run = runCommand, beforePrepare, prepare, signal } = {}) {
+	const installation = assertInstallation(root);
+	const releases = assertLocalPath(installation, RELEASES_DIR);
+	await fs.mkdir(releases, { recursive: true });
+	assertLocalPath(installation, RELEASES_DIR);
+	const releaseLock = await acquireLock(installation);
+	let started = false;
+	let state;
+	try {
+		await beforePrepare?.();
+		signal?.throwIfAborted();
+		const buildDir = resolveBuildOutput(installation, `${RELEASES_DIR}/${Date.now().toString(36)}-${randomUUID()}`);
+		// Never reuse a failed or previous directory, even if it has a BUILD_ID.
+		await fs.mkdir(assertLocalPath(installation, buildDir));
+		state = { schema: 1, state: "building", buildDir, startedAt: new Date().toISOString() };
+		await atomicJson(installation, RELEASE_MANIFEST, state);
+		started = true;
+		const childEnv = {
+			...env, PI_WEB_ROOT: installation, PIWEB_BUILD_DIR: buildDir,
+			PYTHONUTF8: env.PYTHONUTF8 ?? "1", PYTHONIOENCODING: env.PYTHONIOENCODING ?? "utf-8",
+		};
+		// Do not pass the live web password to Git/npm/package build scripts.
+		delete childEnv.PI_WEB_PASSWORD;
+		delete childEnv.PI_WEB_DEV;
+		delete childEnv.NODE_ENV;
+		const context = { root: installation, buildDir, env: childEnv, run, signal };
+		await prepare?.(context);
+		signal?.throwIfAborted();
+		assertInstallation(installation);
+		await writeReleaseTypeConfig(installation, buildDir);
+		await run(process.execPath, [path.join(installation, "scripts", "release.mjs"), "--verify-config"], {
+			cwd: installation, env: childEnv, timeoutMs: 60_000, signal,
+		});
+		await run("npm", ["run", "check"], { cwd: installation, env: childEnv, timeoutMs: 600_000, signal });
+		signal?.throwIfAborted();
+		const build = readProductionBuild(installation, buildDir);
+		const version = JSON.parse(await fs.readFile(path.join(installation, "package.json"), "utf8")).version;
+		if (typeof version !== "string" || !version) throw new Error("PiWeb package version is missing");
+		await atomicJson(installation, RELEASE_MANIFEST, { ...state, ...build, state: "ready", version, finishedAt: new Date().toISOString() });
+		return { ...build, version, needsRestart: true };
+	} catch (error) {
+		if (started) {
+			try { await atomicJson(installation, RELEASE_MANIFEST, { ...state, state: "failed", finishedAt: new Date().toISOString() }); }
+			catch { /* The previously persisted building state still blocks stale fallback. */ }
+		}
+		throw error;
+	} finally { await releaseLock(); }
+}
+
+if (isMainModule(import.meta.url)) {
+	const controller = new AbortController();
+	const cancel = () => controller.abort();
+	process.once("SIGINT", cancel);
+	process.once("SIGTERM", cancel);
+	try {
+		if (process.argv.length === 3 && process.argv[2] === "--verify-config") {
+			await verifyReleaseConfig();
+		} else {
+			const updatePi = process.argv.length === 3 && process.argv[2] === "--update-pi";
+			if (process.argv.length > 2 && !updatePi) throw new Error("Usage: node scripts/release.mjs [--update-pi]");
+			console.log("[piweb] Checking and building an isolated release; the existing server is not restarted.");
+			if (updatePi) console.log("[piweb] Pi dependency update: use a maintenance window with no active sessions; node_modules is shared.");
+			const release = await prepareRelease({
+				signal: controller.signal,
+				prepare: updatePi ? async (context) => { await installPiUpdate(context); } : undefined,
+			});
+			console.log(`[piweb] Release ready: ${release.buildDir} (${release.buildId}). Restart PiWeb manually when idle to use it.`);
+		}
+	} catch (error) {
+		console.error(`[piweb] Release failed: ${error instanceof Error ? error.message : error}`);
+		process.exitCode = 1;
+	} finally {
+		process.off("SIGINT", cancel);
+		process.off("SIGTERM", cancel);
+	}
+}