@wular/pnext 0.0.1

package/src/cli/dev.ts

@@ -0,0 +1,276 @@
+import { dim } from '../utils/ansi';
+import { moduleGenerationStats } from '../dev/module-generations';
+import { markBoot, printBootTrace } from './boot-trace';
+import { browserHost, ensurePortFree, openBrowser, printServerReady } from './serve-ui';
+
+export const devProcessTitle = 'pnext-dev';
+export const devRestartEnv = 'PNEXT_DEV_RESTART';
+
+const defaultMaxDevRssMb = 2048;
+const defaultMaxEsbuildRssMb = 1024;
+// A leaf edit supersedes a couple of generations, so this caps stale mass at roughly 300 MB -
+// about one recycle per 75 leaf edits, and one per ~30 on wide-shared-module edits that rename
+// most of a route graph.
+const defaultMaxStaleModules = 150;
+/** How long a recycle waits for in-flight responses before replacing the image. */
+const drainTimeoutMs = 5_000;
+
+export function nameDevProcess() {
+  process.title = devProcessTitle;
+}
+
+export interface DevOptions {
+  root?: string;
+  port?: number;
+  hostname?: string;
+}
+
+/**
+ * The dev server, running directly in the process bin/pnext exec'd - there is no supervisor.
+ * Resilience comes from self-replacement instead: a memory watchdog trip re-execs this process in
+ * place, which frees the module graph without paying a second process spawn on every boot.
+ */
+export async function dev(options: DevOptions = {}) {
+  nameDevProcess();
+  // Loaded lazily so config resolution and the server graph start in parallel.
+  const [{ loadConfig }, { startDevServer }] = await Promise.all([
+    import('../config'),
+    import('../dev/server'),
+  ]);
+  markBoot('dev:imports');
+  const config = await loadConfig(options.root, { dev: true });
+  markBoot('dev:config');
+  const port = options.port ?? 3000;
+  const hostname = options.hostname ?? 'localhost';
+  // A memory-triggered restart can briefly race the previous listener's
+  // shutdown, so give the port a moment to free before failing.
+  await ensurePortFree(port, hostname, { attempts: 10 });
+  markBoot('dev:port');
+  const start = Date.now();
+  // Bisect switch, same role `PNEXT_DEV_RESTART_CACHE=0` plays for the restart
+  // caches: turns the boot warm-up off so a measurement can price it.
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const warm = process.env.PNEXT_DEV_WARM !== '0';
+  const server = await startDevServer({ config, port, hostname, warm });
+  markBoot('dev:server');
+  const elapsedMs = Date.now() - start;
+  const url = `http://${browserHost(hostname)}:${server.port ?? port}`;
+  printServerReady({ mode: 'dev', hostname, port: server.port ?? port, elapsedMs });
+  printBootTrace();
+  registerShutdown(server);
+  watchServerMemory(server);
+  watchStaleModules(server);
+  watchEsbuildMemory();
+  // Hold the browser until the entry route has compiled, so it opens onto an
+  // already-built page instead of a multi-second cold compile.
+  if (server.warmup) console.log(dim('Warming up and opening the browser...'));
+  await server.warmup;
+  // A memory-triggered restart should refresh silently, not open another tab.
+  if (process.env[devRestartEnv] !== '1') openBrowser(url);
+  return server;
+}
+
+// Every dev reload imports changed modules under fresh URLs, and the ES module
+// registry never evicts, so a long session pins every stale graph in memory.
+// Once RSS crosses the limit, trade a seconds-long restart (vendor bundles are
+// preserved on disk) for getting the memory back.
+function watchServerMemory(server: DevServerHandle) {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const limitMb = Number(process.env.PNEXT_DEV_MAX_RSS_MB || defaultMaxDevRssMb);
+  if (!Number.isFinite(limitMb) || limitMb <= 0) return;
+  const limitBytes = limitMb * 1024 * 1024;
+  const timer = setInterval(() => {
+    const rss = process.memoryUsage.rss();
+    if (rss < limitBytes) return;
+    clearInterval(timer);
+    const usedMb = Math.round(rss / (1024 * 1024));
+    console.log(
+      dim(
+        `Dev server reached ${usedMb}MB of memory (limit ${limitMb}MB, set PNEXT_DEV_MAX_RSS_MB to change); restarting to release stale modules...`,
+      ),
+    );
+    void restartDevProcess(server);
+  }, 15_000);
+  timer.unref();
+}
+
+// The esbuild Go service self-drains its heap when idle, so two consecutive readings above the
+// limit mean it is genuinely parked high. Stopping it is lossless - pnext only issues one-shot
+// builds, never incremental contexts. A stop that races an in-flight build fails that one build;
+// dev asset caches drop failed builds, so the next request retries.
+function watchEsbuildMemory() {
+  if (process.platform === 'win32') return;
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const limitMb = Number(process.env.PNEXT_DEV_MAX_ESBUILD_RSS_MB || defaultMaxEsbuildRssMb);
+  if (!Number.isFinite(limitMb) || limitMb <= 0) return;
+  let highTicks = 0;
+  const timer = setInterval(() => {
+    const rssMb = esbuildServiceRssMb();
+    highTicks = rssMb > limitMb ? highTicks + 1 : 0;
+    if (highTicks < 2) return;
+    highTicks = 0;
+    console.log(
+      dim(
+        `esbuild reached ${Math.round(rssMb)}MB of memory (limit ${limitMb}MB, set PNEXT_DEV_MAX_ESBUILD_RSS_MB to change); restarting it to release the heap...`,
+      ),
+    );
+    void (async () => {
+      try {
+        const esbuild = await import('esbuild');
+        await esbuild.stop();
+      } catch {
+        // ignore: the service may already be gone
+      }
+      // stop() can strand in-flight build promises unsettled; fail their
+      // waiters so requests retry against the respawned service.
+      const { failInFlightClientBuilds } = await import('../dev/server');
+      failInFlightClientBuilds('esbuild service restarted by the memory watchdog');
+    })();
+  }, 15_000);
+  timer.unref();
+}
+
+/**
+ * Recycle on stale registry mass rather than on RSS. Every save renames the modules it changes and
+ * Bun's registry never unlinks the old ones, so a session accumulates superseded generations at a
+ * fixed rate that nothing in-process can free. RSS is a lagging proxy: it trips only after the
+ * growth has already cost save latency, and it also trips on a warm route set that is entirely
+ * live. The replacement re-warms from the content-keyed disk cache, so the cost is a restart, not
+ * a cold build.
+ */
+function watchStaleModules(server: DevServerHandle) {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const limit = Number(process.env.PNEXT_DEV_MAX_STALE_MODULES || defaultMaxStaleModules);
+  if (!Number.isFinite(limit) || limit <= 0) return;
+  const timer = setInterval(() => {
+    const { stale } = moduleGenerationStats();
+    if (stale < limit) return;
+    clearInterval(timer);
+    console.log(
+      dim(
+        `Dev server is holding ${stale} superseded module generations (limit ${limit}, set PNEXT_DEV_MAX_STALE_MODULES to change); restarting to release them...`,
+      ),
+    );
+    void restartDevProcess(server);
+  }, 15_000);
+  timer.unref();
+}
+
+// Our esbuild service children: [pid, RSS in MB] per process.
+function esbuildServices(): [number, number][] {
+  const found: [number, number][] = [];
+  try {
+    const stdout = Bun.spawnSync(['ps', '-ax', '-o', 'pid=,ppid=,rss=,ucomm=']).stdout.toString();
+    for (const line of stdout.split('\n')) {
+      const [pid, ppid, rss, ...name] = line.trim().split(/\s+/);
+      if (Number(ppid) === process.pid && name.join(' ').includes('esbuild')) {
+        found.push([Number(pid), Number(rss) / 1024]);
+      }
+    }
+  } catch {
+    // ignore: no ps available means no monitoring, not a broken dev server
+  }
+  return found;
+}
+
+// RSS of our esbuild service, in MB (0 when not running).
+function esbuildServiceRssMb() {
+  return esbuildServices().reduce((total, [, rssMb]) => total + rssMb, 0);
+}
+
+interface DevServerHandle {
+  stop(closeActiveConnections?: boolean): unknown;
+  /** Resolves once nothing is being served (or the timeout elapses). */
+  drain?(timeoutMs: number): Promise<boolean>;
+}
+
+/**
+ * Replace this process with a fresh dev server. A real execve keeps the pid, the stdio and the
+ * shell's job control intact, so the restart is invisible from the terminal - and because the image
+ * is replaced, every byte of the stale module graph goes away. Bun exposes no exec, so libc's is
+ * called directly; where that is unavailable (Windows) the replacement is spawned instead, which
+ * frees the same memory but detaches the server from the shell's foreground job.
+ */
+async function restartDevProcess(server: DevServerHandle): Promise<void> {
+  try {
+    // Stop accepting, then let what is already being served finish: an exec
+    // mid-response would leave the browser with a truncated page and no error.
+    server.stop(false);
+    await server.drain?.(drainTimeoutMs);
+    server.stop(true);
+  } catch {
+    // ignore: we are being replaced regardless
+  }
+  // The esbuild service keeps its pipes across an exec, so it would outlive the
+  // image that owned it — with exactly the heap this restart is reclaiming.
+  for (const [pid] of esbuildServices()) {
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch {
+      // ignore: already gone
+    }
+  }
+  const argv = [process.execPath, '--conditions=react-server', ...process.argv.slice(1)];
+  const env = { ...process.env, [devRestartEnv]: '1' };
+  try {
+    await execSelf(argv, env);
+  } catch {
+    // ignore: fall through to the spawn path
+  }
+  // Only reached when exec is unavailable or failed.
+  Bun.spawn(argv, { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit', env });
+  process.exit(0);
+}
+
+// execve(2) via libc. argv/envp are NUL-terminated C string arrays, and the
+// pointer array must stay reachable until the call returns (it never does on
+// success).
+async function execSelf(argv: string[], env: Record<string, string | undefined>): Promise<void> {
+  if (process.platform === 'win32') return;
+  const { dlopen, FFIType, ptr, suffix } = await import('bun:ffi');
+  const libc = process.platform === 'darwin' ? '/usr/lib/libSystem.B.dylib' : `libc.${suffix}.6`;
+  const { symbols } = dlopen(libc, {
+    execve: {
+      args: [FFIType.cstring, FFIType.ptr, FFIType.ptr],
+      returns: FFIType.i32,
+    },
+  });
+  const encoder = new TextEncoder();
+  const cString = (value: string) => encoder.encode(`${value}\0`);
+  const cArray = (values: string[]) => {
+    const cells = values.map(cString);
+    const array = new BigInt64Array(cells.length + 1);
+    cells.forEach((cell, index) => {
+      array[index] = BigInt(ptr(cell));
+    });
+    return { array, cells };
+  };
+  const args = cArray(argv);
+  const envp = cArray(
+    Object.entries(env)
+      .filter(([, value]) => value !== undefined)
+      .map(([key, value]) => `${key}=${value}`),
+  );
+  symbols.execve(cString(argv[0]!), ptr(args.array), ptr(envp.array));
+  // execve only returns on failure; keep the buffers alive until then.
+  void [args.cells, envp.cells];
+}
+
+// Stop the server and run process `exit` handlers on a terminating signal,
+// so killing the dev server never leaves orphaned subprocesses behind.
+function registerShutdown(server: DevServerHandle) {
+  let closing = false;
+  const shutdown = () => {
+    if (closing) return;
+    closing = true;
+    try {
+      server.stop(true);
+    } catch {
+      // ignore: process is exiting regardless
+    }
+    process.exit(0);
+  };
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) {
+    process.once(signal, shutdown);
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,196 @@
+#!/usr/bin/env bun
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { markBoot } from './boot-trace';
+import { commandBinaryName, nameEsbuildProcess, namedBunBinary } from './named-bin';
+
+const [, , command, ...args] = process.argv;
+markBoot('cli:entry');
+
+// A no-op once we already run under the command's name; otherwise it creates
+// the hardlink so bin/pnext can exec it directly from the next run on.
+namedBunBinary(commandBinaryName(command));
+
+// Before any command lazily imports esbuild, which captures the binary path on
+// module load.
+nameEsbuildProcess();
+markBoot('cli:naming');
+
+try {
+  if (command === 'dev') {
+    const { dev } = await import('./dev');
+    await dev({
+      root: positionalRoot(args),
+      port: optionNumber(args, '--port'),
+      hostname: optionString(args, '--hostname'),
+    });
+  } else if (command === 'build') {
+    const { buildProject } = await import('./build');
+    await buildProject(positionalRoot(args), {
+      adapter: adapterOption(args),
+      verbose: args.includes('--verbose'),
+      debugBuildPaths: optionString(args, '--debug-build-paths'),
+      buildMode: buildModeOption(args),
+      debugPrerender: args.includes('--debug-prerender'),
+    });
+    // Nothing here keeps the event loop alive on success, but a project's
+    // next.config can (e.g. a stray setInterval) and Next's own `next build`
+    // force-exits regardless of such handles. Do the same so `build` always
+    // terminates once buildProject resolves.
+    process.exit(0);
+  } else if (command === 'start') {
+    const { start } = await import('./start');
+    await start({
+      root: positionalRoot(args),
+      port: optionNumber(args, '--port'),
+      hostname: optionString(args, '--hostname'),
+    });
+  } else if (command === 'analyze') {
+    const { analyzeProject } = await import('./analyze');
+    const { route, root } = analyzePositionals(args);
+    const result = await analyzeProject(root, {
+      compression: analyzeCompression(args),
+      route,
+    });
+    if (args.includes('--json')) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      const { printAnalyzeResult } = await import('./analyze-print');
+      printAnalyzeResult(result, { route, files: args.includes('--files') });
+    }
+  } else if (command === 'typegen') {
+    const { typegenProject } = await import('../typegen');
+    const result = await typegenProject(positionalRoot(args));
+    console.log(
+      `Generated ${result.routes} route types, ${result.aliases} aliases, and ${result.checks} checks at ${result.file}`,
+    );
+    // Like `next typegen`, exit even when the loaded next.config leaves open
+    // handles (timers/connections) alive — a one-shot command must not hang.
+    process.exit(0);
+  } else {
+    printHelp();
+    process.exit(command ? 1 : 0);
+  }
+} catch (error) {
+  const formatted = formatCliError(error);
+  console.error(formatted.message);
+  if (formatted.trace) console.log(`\n${formatted.trace}`);
+  process.exit(1);
+}
+
+function formatCliError(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  const traceStart = message.indexOf('\npnext client import trace for route ');
+  if (traceStart === -1) return { message };
+  return {
+    message: message.slice(0, traceStart),
+    trace: message.slice(traceStart + 1),
+  };
+}
+
+function positionalRoot(args: string[]) {
+  return positionals(args)[0];
+}
+
+// The analyze command takes optional [route] and [directory] positionals. A
+// leading-slash argument is the route filter unless it points at a directory
+// that looks like a project root — system directories like /home or /run
+// collide with real route names.
+function analyzePositionals(args: string[]) {
+  let route: string | undefined;
+  let root: string | undefined;
+  for (const arg of positionals(args)) {
+    if (!route && arg.startsWith('/') && !isProjectDirectory(arg)) route = arg;
+    else root ??= arg;
+  }
+  return { route, root };
+}
+
+function isProjectDirectory(candidate: string) {
+  if (!isDirectory(candidate)) return false;
+  return ['package.json', '.pnext', 'app', path.join('src', 'app')].some(entry =>
+    existsSync(path.join(candidate, entry)),
+  );
+}
+
+function positionals(args: string[]) {
+  const out: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    if (
+      arg === '--port' ||
+      arg === '--adapter' ||
+      arg === '--hostname' ||
+      arg === '--debug-build-paths' ||
+      arg === '--experimental-build-mode'
+    ) {
+      index += 1;
+      continue;
+    }
+    if (!arg.startsWith('--')) out.push(arg);
+  }
+  return out;
+}
+
+function isDirectory(candidate: string) {
+  try {
+    return statSync(candidate).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function optionNumber(args: string[], name: string) {
+  const index = args.indexOf(name);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  return value ? Number(value) : undefined;
+}
+
+function optionString(args: string[], name: string) {
+  // Accept both `--name value` and `--name=value`.
+  const inline = args.find(arg => arg.startsWith(`${name}=`));
+  if (inline !== undefined) return inline.slice(name.length + 1);
+  const index = args.indexOf(name);
+  if (index === -1) return undefined;
+  return args[index + 1];
+}
+
+/**
+ * `next build --experimental-build-mode compile|generate` parity. Both the
+ * space (`--experimental-build-mode generate`) and equals
+ * (`--experimental-build-mode=generate`) forms are accepted; `generate` runs
+ * the standard full build (idempotent over a prior `compile` run).
+ */
+function buildModeOption(args: string[]): 'compile' | 'generate' | undefined {
+  const value = optionString(args, '--experimental-build-mode');
+  if (value === 'compile' || value === 'generate') return value;
+  if (value !== undefined) {
+    console.error(
+      `error: option '--experimental-build-mode <mode>' argument '${value}' is invalid. Expected 'compile' or 'generate'.`,
+    );
+    process.exit(1);
+  }
+  return undefined;
+}
+
+function adapterOption(args: string[]) {
+  const index = args.indexOf('--adapter');
+  if (index === -1) return undefined;
+  const adapter = args[index + 1];
+  if (adapter === 'vercel') return adapter;
+  throw new Error(`Unsupported adapter: ${adapter ?? ''}`);
+}
+
+function analyzeCompression(args: string[]) {
+  return args.includes('--brotli') ? 'brotli' : 'gzip';
+}
+
+function printHelp() {
+  console.log(`pnext dev [directory] [--port 3000] [--hostname 127.0.0.1]
+pnext build [directory] [--adapter vercel] [--verbose]
+pnext start [directory] [--port 3000] [--hostname 127.0.0.1]
+pnext analyze [route] [directory] [--brotli] [--files] [--json]
+pnext typegen [directory]`);
+}

package/src/cli/named-bin.ts

@@ -0,0 +1,119 @@
+import {
+  chmodSync,
+  constants as fsConstants,
+  copyFileSync,
+  existsSync,
+  linkSync,
+  mkdirSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+
+export const namedBinaryName = 'pnext';
+
+// Keep in sync with the command case in bin/pnext, which resolves the same name.
+const cliCommands = new Set(['dev', 'build', 'start', 'analyze', 'typegen']);
+
+/** Process name for a CLI command: `pnext dev` runs as `pnext-dev`, etc. */
+export function commandBinaryName(command: string | undefined) {
+  if (command && cliCommands.has(command)) return `${namedBinaryName}-${command}`;
+  return namedBinaryName;
+}
+
+/**
+ * Path to a bun executable whose file is literally named `name`.
+ *
+ * Activity Monitor and `ps -o ucomm` show the kernel's process name, set from the basename of the
+ * executable file at exec time - `argv0`, `exec -a` and `process.title` only change the argv that
+ * plain `ps` prints. So the running bun binary is hardlinked (or cloned/copied) into the user cache
+ * once per role and every process spawns through its role's link. Hardlinks share the inode, so the
+ * extra names are free.
+ *
+ * Falls back to the plain bun binary when the cache is unavailable: naming is cosmetic and must never
+ * break spawning.
+ */
+export function namedBunBinary(name: string = namedBinaryName): string {
+  if (process.platform === 'win32') return process.execPath;
+  if (path.basename(process.execPath) === name) return process.execPath;
+  return namedExecutable(process.execPath, `bun-${Bun.version}`, name);
+}
+
+/**
+ * Label esbuild's service process. The esbuild JS API spawns its own Go binary, so pnext never execs
+ * it - but esbuild honors `ESBUILD_BINARY_PATH`, so pointing that at a hardlink of the platform
+ * binary renames the service. The lib captures the variable at module load, so this must run before
+ * anything imports esbuild.
+ */
+export function nameEsbuildProcess() {
+  if (process.platform === 'win32') return;
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  if (process.env.ESBUILD_BINARY_PATH) return; // respect an explicit override
+  try {
+    const require = createRequire(import.meta.url);
+    const { version } = require('esbuild/package.json') as { version: string };
+    const binPath = require.resolve(`@esbuild/${process.platform}-${process.arch}/bin/esbuild`);
+    const named = namedExecutable(binPath, `esbuild-${version}`, 'pnext-esbuild');
+    // eslint-disable-next-line turbo/no-undeclared-env-vars
+    if (named !== binPath) process.env.ESBUILD_BINARY_PATH = named;
+  } catch {
+    // unknown platform package or unavailable cache: esbuild resolves its own
+    // binary and just keeps its name
+  }
+}
+
+function namedExecutable(sourcePath: string, versionDir: string, name: string): string {
+  try {
+    // One directory per tool version, so upgrades switch paths instead of
+    // serving a stale binary.
+    const binRoot = path.join(cacheRoot(), 'bin');
+    const dir = path.join(binRoot, versionDir);
+    const named = path.join(dir, name);
+    if (!existsSync(named)) {
+      mkdirSync(dir, { recursive: true });
+      // Land under a temp name and rename, so a concurrent pnext process can
+      // never exec a half-written binary.
+      const staging = path.join(dir, `.${name}-${process.pid}`);
+      rmSync(staging, { force: true });
+      try {
+        linkSync(sourcePath, staging);
+      } catch {
+        // Cross-volume or hardlink-restricted: clone when the filesystem
+        // supports it (free on APFS), else fall back to a full copy.
+        copyFileSync(sourcePath, staging, fsConstants.COPYFILE_FICLONE);
+        chmodSync(staging, 0o755);
+      }
+      renameSync(staging, named);
+      removeStaleVersions(binRoot, path.basename(dir));
+    }
+    return named;
+  } catch {
+    return sourcePath;
+  }
+}
+
+// Best-effort sweep of binaries linked for previous versions of the same
+// tool: keeping `bun-1.3.6` removes other `bun-*` dirs but leaves
+// `esbuild-*` alone.
+function removeStaleVersions(binRoot: string, keep: string) {
+  const toolPrefix = keep.slice(0, keep.indexOf('-') + 1);
+  try {
+    for (const entry of readdirSync(binRoot)) {
+      if (entry === keep || !entry.startsWith(toolPrefix)) continue;
+      rmSync(path.join(binRoot, entry), { recursive: true, force: true });
+    }
+  } catch {
+    // ignore: stale versions only waste a hardlink's worth of space
+  }
+}
+
+/** pnext's user cache dir — survives the build wiping the output directory. */
+export function cacheRoot() {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const xdg = process.env.XDG_CACHE_HOME;
+  if (xdg) return path.join(xdg, 'pnext');
+  return path.join(os.homedir(), '.cache', 'pnext');
+}