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

package/bin/pi-web-update.js

@@ -0,0 +1,148 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { execFileSync, spawnSync } = require("child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fs = require("fs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require("path");
+
+const NPM_LATEST_URL = "https://registry.npmjs.org/@colinxu%2Fpi-web-classic/latest";
+const FETCH_TIMEOUT_MS = 10_000;
+const MANUAL_COMMAND = "npm install -g @colinxu/pi-web-classic@latest";
+
+// Port of lib/app-update.ts (bin cannot import TypeScript).
+function parseStableVersion(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+  if (!match) return null;
+  const parts = match.slice(1).map(Number);
+  return parts.every(Number.isSafeInteger) ? parts : null;
+}
+
+function isNewerStableVersion(candidate, current) {
+  const candidateParts = parseStableVersion(candidate);
+  const currentParts = parseStableVersion(current);
+  if (!candidateParts || !currentParts) return false;
+  for (let index = 0; index < candidateParts.length; index += 1) {
+    if (candidateParts[index] !== currentParts[index]) {
+      return candidateParts[index] > currentParts[index];
+    }
+  }
+  return false;
+}
+
+async function fetchLatestVersion() {
+  const response = await fetch(NPM_LATEST_URL, {
+    headers: { Accept: "application/json" },
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!response.ok) throw new Error(`npm registry returned HTTP ${response.status}`);
+  const { version } = await response.json();
+  if (typeof version !== "string" || !parseStableVersion(version)) {
+    throw new Error("npm registry returned an invalid version");
+  }
+  return version;
+}
+
+// npm's own CLI script run through this node, so no shell is needed on
+// Windows (same lookup as lib/node-cli.ts). null: no way to run npm safely.
+function findNpmInvocation(args, nodeDir = path.dirname(process.execPath), platform = process.platform, exists = fs.existsSync) {
+  for (const script of [
+    path.join(nodeDir, "node_modules", "npm", "bin", "npm-cli.js"),
+    path.join(nodeDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+  ]) {
+    if (exists(script)) return { command: process.execPath, args: [script, ...args] };
+  }
+  return platform === "win32" ? null : { command: "npm", args };
+}
+
+function realpathOrSelf(target, realpath = fs.realpathSync) {
+  try {
+    return realpath(target);
+  } catch {
+    return path.resolve(target);
+  }
+}
+
+// "global": pkgDir is <npm root -g>/@colinxu/pi-web-classic; "npx": an npx cache; else "other".
+function getInstallKind({ pkgDir, npmRoot, realpath = fs.realpathSync }) {
+  const realPkgDir = realpathOrSelf(pkgDir, realpath);
+  if (realPkgDir.split(/[\\/]/).includes("_npx")) return "npx";
+  if (!npmRoot) return "other";
+  const inGlobalRoot =
+    path.basename(realPkgDir) === "pi-web-classic" &&
+    path.basename(path.dirname(realPkgDir)) === "@colinxu" &&
+    realpathOrSelf(path.dirname(path.dirname(realPkgDir)), realpath) === realpathOrSelf(npmRoot, realpath);
+  return inGlobalRoot ? "global" : "other";
+}
+
+function getGlobalNpmRoot() {
+  const invocation = findNpmInvocation(["root", "-g"]);
+  if (!invocation) return null;
+  try {
+    return execFileSync(invocation.command, invocation.args, { encoding: "utf8", timeout: 30_000 }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function runNpmInstall(version) {
+  const invocation = findNpmInvocation(["install", "-g", `@colinxu/pi-web-classic@${version}`]);
+  if (!invocation) return null;
+  const result = spawnSync(invocation.command, invocation.args, { stdio: "inherit" });
+  return result.status ?? 1;
+}
+
+async function runUpdate({
+  check,
+  currentVersion,
+  pkgDir,
+  listRecords,
+  formatRecord,
+  fetchLatest = fetchLatestVersion,
+  getNpmRoot = getGlobalNpmRoot,
+  install = runNpmInstall,
+  realpath = fs.realpathSync,
+  log = console.log,
+  error = console.error,
+}) {
+  let latest;
+  try {
+    latest = await fetchLatest();
+  } catch (fetchError) {
+    error(`Could not check for updates: ${fetchError.message}`);
+    return 1;
+  }
+  if (!isNewerStableVersion(latest, currentVersion)) {
+    log(`pi-web ${currentVersion} is up to date.`);
+    return 0;
+  }
+  log(`pi-web ${latest} is available (installed: ${currentVersion}).`);
+  if (check) return 0;
+
+  // A running `next start` has .next/ open; never replace it underneath.
+  const running = await listRecords();
+  if (running.length > 0) {
+    error(`pi-web is running:\n${running.map(formatRecord).join("\n")}\nRun \`pwc stop\` first, then update.`);
+    return 1;
+  }
+
+  const kind = getInstallKind({ pkgDir, npmRoot: getNpmRoot(), realpath });
+  if (kind === "npx") {
+    error("This pi-web runs from the npx cache. Run `npx @colinxu/pi-web-classic@latest` instead.");
+    return 1;
+  }
+  if (kind !== "global") {
+    error(`This pi-web is not a global npm install. Update it yourself, for example: ${MANUAL_COMMAND}`);
+    return 1;
+  }
+
+  const code = install(latest);
+  if (code === null) {
+    error(`Could not find npm. Run: ${MANUAL_COMMAND}`);
+    return 1;
+  }
+  return code;
+}
+
+module.exports = { findNpmInvocation, getInstallKind, isNewerStableVersion, runUpdate };

package/bin/pi-web.js

@@ -0,0 +1,157 @@
+#!/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 { getHelpText, parseCommandLine } = require("./pi-web-options");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { getNextNodeArgs } = require("./pi-web-node-args");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { wireChildProcessLifecycle } = require("./process-lifecycle");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { rotatePreviewSecrets, getRotationWarning } = require("./rotate-preview-secrets");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { openInBrowser } = require("./browser-opener");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { createRunRecordTracker, getOpenUrl, getRunDir } = require("./run-records");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { getPackageVersion, runCommand } = require("./pi-web-commands");
+
+let launchOptions;
+try {
+  launchOptions = parseCommandLine();
+} catch (error) {
+  fs.writeSync(
+    process.stderr.fd,
+    `${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exit(1);
+}
+
+if (launchOptions.help) {
+  fs.writeSync(process.stdout.fd, getHelpText());
+  process.exit(0);
+}
+
+if (launchOptions.command === "start") {
+  startServer(launchOptions);
+} else {
+  runCommand(launchOptions).then(
+    exitWhenIdle,
+    (error) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      exitWhenIdle(1);
+    },
+  );
+}
+
+// Leave once the event loop drains instead of calling process.exit() right
+// after a fetch(): on Windows, Node.js 23 up to 24.19 / 26.6 can then abort
+// with a libuv assertion (UV_HANDLE_CLOSING, win/async.c) while background
+// work from the fetch is still winding down (#1174, nodejs/node#56645). The
+// unref'd timer only fires if something still holds the loop open.
+function exitWhenIdle(code) {
+  process.exitCode = code;
+  setTimeout(() => process.exit(code), 2_000).unref();
+}
+
+function startServer({ port, hostname, openBrowser }) {
+
+  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 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);
+  }
+
+  // Replace the published preview-mode secrets with fresh random values so the
+  // previewModeId baked into the npm tarball cannot be used to skip the proxy
+  // (via the x-prerender-revalidate header). Must happen before `next start`.
+  const rotation = rotatePreviewSecrets(nextDir);
+  if (!rotation.ok) {
+    console.warn(getRotationWarning(rotation.reason));
+  }
+
+  if (!loopbackHostnames.has(hostname)) {
+    if (passwordEnabled) {
+      console.warn(
+        `Warning: pi-web is listening on ${hostname} with password authentication 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, getNextNodeArgs(nextBin, nextArgs), {
+    cwd: pkgDir,
+    stdio: ["inherit", "pipe", "inherit"],
+    env: { ...process.env, PI_WEB_HOSTNAME: hostname },
+  });
+  wireChildProcessLifecycle(child);
+
+  // Port 0 lets the OS pick a port we never learn, so such a server gets no record.
+  const runRecord = createRunRecordTracker({
+    dir: getRunDir,
+    record: {
+      pid: process.pid,
+      nextPid: child.pid,
+      port: Number(port),
+      hostname,
+      url: getOpenUrl(hostname, port),
+      version: getPackageVersion(pkgDir),
+      startedAt: new Date().toISOString(),
+    },
+  });
+
+  let serverReady = false;
+  const url = `http://${hostname}:${port}`;
+
+  child.stdout.on("data", (chunk) => {
+    const text = chunk.toString();
+    process.stdout.write(text);
+    if (!serverReady && text.includes("Ready")) {
+      serverReady = true;
+      if (port !== "0") runRecord.markReady();
+      if (openBrowser) openInBrowser(url);
+    }
+  });
+}

package/bin/prepare-terminal.js

@@ -0,0 +1,14 @@
+// node-pty 1.1.0 ships macOS spawn-helper binaries without executable bits.
+// Remove this workaround once the upstream package preserves those modes.
+/* eslint-disable @typescript-eslint/no-require-imports */
+const { chmodSync, statSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+
+if (process.platform === "darwin") {
+  const root = dirname(require.resolve("node-pty/package.json"));
+  for (const directory of ["build/Release", "build/Debug", `prebuilds/darwin-${process.arch}`]) {
+    const helper = join(root, directory, "spawn-helper");
+    const stat = statSync(helper, { throwIfNoEntry: false });
+    if (stat?.isFile() && (stat.mode & 0o111) !== 0o111) chmodSync(helper, stat.mode | 0o111);
+  }
+}

package/bin/process-lifecycle.js

@@ -0,0 +1,81 @@
+"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,
+  log = console.error,
+) {
+  const signalHandlers = new Map();
+  let shutdownTimer;
+  // Set once we forward a signal, so an exit we asked for stays quiet and one
+  // we did not gets reported.
+  let shuttingDown = false;
+
+  const forceKill = () => child.kill("SIGKILL");
+
+  function unwire() {
+    if (shutdownTimer) clearTimeout(shutdownTimer);
+    for (const [forwardedSignal, handler] of signalHandlers) {
+      parentProcess.removeListener(forwardedSignal, handler);
+    }
+    child.removeListener("error", handleError);
+  }
+
+  function handleError(error) {
+    const failedToSpawn = child.pid === undefined;
+    log(
+      `[pi-web] ${failedToSpawn ? "could not run the Next.js process" : "Next.js process error"}: ${error.message}`,
+    );
+
+    if (failedToSpawn) {
+      unwire();
+      parentProcess.exit(1);
+    }
+  }
+
+  for (const signal of forwardedSignals) {
+    const handler = () => {
+      if (shutdownTimer) {
+        forceKill();
+        return;
+      }
+
+      shuttingDown = true;
+      shutdownTimer = setTimeout(forceKill, timeoutMs);
+      shutdownTimer.unref();
+      child.kill(signal);
+    };
+    signalHandlers.set(signal, handler);
+    parentProcess.on(signal, handler);
+  }
+
+  child.on("error", handleError);
+
+  child.once("exit", (code, signal) => {
+    unwire();
+
+    // A shutdown the user asked for needs no explanation; anything else left
+    // the window closing with no stated reason.
+    if (!shuttingDown) {
+      log(
+        `[pi-web] Next.js exited unexpectedly (${signal ? `signal ${signal}` : `code ${code}`})`,
+      );
+    }
+
+    parentProcess.exit(code ?? getSignalExitCode(signal));
+  });
+}
+
+module.exports = { wireChildProcessLifecycle };

package/bin/rotate-preview-secrets.js

@@ -0,0 +1,105 @@
+"use strict";
+
+// The published npm tarball ships `.next/prerender-manifest.json`, whose
+// `preview` block holds the build's preview-mode secrets. One of them,
+// `previewModeId`, is the value Next compares against the `x-prerender-revalidate`
+// request header: when they match, Next treats the request as an on-demand
+// revalidation and skips middleware/proxy entirely (see next-server.js
+// `runMiddleware`). Because the value is baked into every published version, an
+// attacker who reads the tarball can send that header and bypass `proxy.ts` —
+// the central password gate and the Host/Origin/Fetch-Metadata checks.
+//
+// `next start` reads these secrets only from this file (there is no runtime env
+// override) and never regenerates them, so we rewrite the three preview secrets
+// with fresh random values before launching Next. That makes the published
+// values useless and unique per launch. Done at startup rather than in a
+// postinstall hook so it runs on the guaranteed launch path and cannot be
+// skipped with `--ignore-scripts`.
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const crypto = require("crypto");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fs = require("fs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require("path");
+
+const PRERENDER_MANIFEST = "prerender-manifest.json";
+
+function freshPreviewSecrets() {
+  return {
+    // Lengths mirror what Next generates at build time.
+    previewModeId: crypto.randomBytes(16).toString("hex"),
+    previewModeSigningKey: crypto.randomBytes(32).toString("hex"),
+    previewModeEncryptionKey: crypto.randomBytes(32).toString("hex"),
+  };
+}
+
+/**
+ * Rewrite the preview-mode secrets in `.next/prerender-manifest.json` with fresh
+ * random values. Never throws: returns a status the caller can surface so a
+ * read-only install (where the rewrite cannot happen) is visible rather than a
+ * silent bypass.
+ *
+ * @param {string} nextDir absolute path to the package's `.next` directory
+ * @returns {{ ok: boolean, reason?: string, error?: Error }}
+ */
+function rotatePreviewSecrets(nextDir) {
+  const manifestPath = path.join(nextDir, PRERENDER_MANIFEST);
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return { ok: false, reason: "missing" };
+    }
+    return { ok: false, reason: "unreadable", error };
+  }
+
+  if (!manifest || typeof manifest !== "object" || typeof manifest.preview !== "object") {
+    return { ok: false, reason: "unexpected-shape" };
+  }
+
+  manifest.preview = { ...manifest.preview, ...freshPreviewSecrets() };
+
+  // Write to a sibling temp file and rename so a concurrent `next start` never
+  // reads a half-written manifest.
+  const tempPath = path.join(nextDir, `${PRERENDER_MANIFEST}.${process.pid}.tmp`);
+  try {
+    fs.writeFileSync(tempPath, JSON.stringify(manifest));
+    fs.renameSync(tempPath, manifestPath);
+  } catch (error) {
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+      // Best effort: leaving a stray temp file is harmless.
+    }
+    return { ok: false, reason: "unwritable", error };
+  }
+
+  return { ok: true };
+}
+
+function getRotationWarning(reason) {
+  const detail =
+    reason === "unwritable"
+      ? "the install directory is not writable"
+      : reason === "missing"
+        ? "its prerender manifest is missing"
+        : reason === "unreadable"
+          ? "its prerender manifest could not be read"
+          : "its prerender manifest has an unexpected format";
+  return [
+    `Warning: could not rotate pi-web's preview-mode secrets because ${detail}.`,
+    "This instance keeps the published preview id, so a client that knows it can",
+    "bypass the proxy's authentication and Host/Origin checks via the",
+    "x-prerender-revalidate header. Run from a writable install, or restrict",
+    "network access to this instance.",
+  ].join("\n");
+}
+
+module.exports = {
+  PRERENDER_MANIFEST,
+  rotatePreviewSecrets,
+  getRotationWarning,
+};