@thomas.f/prnext 0.1.0-alpha.1 → 0.1.1-alpha

package/runtime/fetch-cache.mjs

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import cache from '../compat/data-cache.cjs';
 import { dynamicUsage, trackStaticDependency } from '../compat/static-generation.cjs';
 import { recordCacheDependency } from '../compat/use-cache.cjs';
+import diagnostics from '../compat/diagnostics.cjs';
 
 const { cachedValue, deferredValue, optionalRequestContext, cacheState, getCachePaths,
   inCacheScope, nativeFetch, MAX_CACHE_VALUE_BYTES } = cache;
@@ -294,7 +295,15 @@ export function installFetchCache() {
       for (let index = dispatcher.handlers.length - 1; index >= 0; index--) {
         const handler = dispatcher.handlers[index];
         const context = handler.context();
-        if (context) return handler.fetch(input, init, context);
+        if (context) {
+          if (!diagnostics.enabled) return handler.fetch(input, init, context);
+          const started = performance.now();
+          const fields = { route: diagnostics.route(context), destination: diagnostics.destination(input) };
+          return Promise.resolve().then(() => handler.fetch(input, init, context)).then(response => {
+            diagnostics.record('fetch', { ...fields, status: response.status, durationMs: performance.now() - started });
+            return response;
+          }, error => { diagnostics.record('fetch', { ...fields, error: true, durationMs: performance.now() - started }); throw error; });
+        }
       }
       return nativeFetch(input, init);
     };
@@ -320,6 +329,8 @@ export function installFetchCache() {
     const memoize = context.phase === 'render' && method === 'GET' && !explicitSignal;
     const hardRefresh = !context.production && /(?:^|,)\s*no-cache\s*(?:,|$)/i.test(context.headers?.get?.('cache-control') || '');
     const persist = policy.persist && !hardRefresh && !context.draftMode && !context.cacheConfig?.forceNoStore;
+    if (diagnostics.enabled && !persist) diagnostics.record('cache', { route: diagnostics.route(context), state: 'bypass',
+      reason: context.draftMode ? 'draft mode' : hardRefresh ? 'development hard refresh' : context.cacheConfig?.forceNoStore ? 'route disables caching' : 'fetch policy does not opt into persistent caching' });
     if (!persist && !memoize) return nativeFetch(input, init);
     const prepared = await prepareRequest(input, init);
     if (!prepared) return nativeFetch(input, init);

package/runtime/fs.mjs

@@ -0,0 +1,15 @@
+import { rename as move } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+
+// Windows scanners and recently closed file handles can briefly deny rename.
+// Keep the atomic swap: never delete the destination to work around a lock.
+export async function rename(source, destination) {
+  const deadline = Date.now() + 2000;
+  for (let attempt = 0; ; attempt++) {
+    try { return await move(source, destination); }
+    catch (error) {
+      if (process.platform !== 'win32' || !['EPERM', 'EACCES', 'EBUSY'].includes(error.code) || Date.now() >= deadline) throw error;
+      await delay(Math.min(10 * (attempt + 1), 100));
+    }
+  }
+}

package/runtime/persistent/client.mjs

@@ -0,0 +1,164 @@
+import { spawn } from 'node:child_process';
+import { readFile, realpath, open } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { initializeHome, rpc, delay, environment, validName, validHealthPath } from './common.mjs';
+import { resolveNativeBinary } from '../../native/resolve.mjs';
+
+export const persistentHelp = `Persistent apps (ordinary prn start stays in the foreground):
+  prn pstart [directory] [options]   Start a built app in the background
+  prn prestart [name] [--all]        Check a new instance, switch traffic, drain the old
+  prn pstop [name] [--all]           Stop apps and disable their automatic restoration
+  prn pdelete [name] [--all]         Stop apps and remove their saved settings
+  prn pstatus [name] [--json]        Show supervised apps (alias: plist)
+  prn plogs [name] [--follow]        Read application logs (last 100 lines)
+  prn plogs --supervisor            Read supervisor logs
+  prn pstartup [--remove]           Enable or remove restoration at user login
+  prn pdown                        Stop the supervisor; keep apps saved for restoration
+
+pstart options: --name NAME --port 3000 --hostname 127.0.0.1 --workers 1
+  --profile balanced|speed|memory|classic --inspect
+  --health-path / --health-timeout 15000 --drain-timeout 30000 (milliseconds)
+prestart/pstop/plogs default to the app in the current directory.
+plogs options: --lines 100 --follow. App environment comes from its .env files.
+State and logs: ~/.prnext/processes (override with PRNEXT_PM_HOME).
+`;
+
+export function parsePersistent(command, argv) {
+  const allowed = command === 'pstart' ? ['name', 'port', 'hostname', 'workers', 'profile', 'inspect', 'health-path', 'health-timeout', 'drain-timeout']
+    : command === 'plogs' ? ['follow', 'lines', 'supervisor'] : command === 'pstartup' ? ['remove']
+    : ['pstatus', 'plist'].includes(command) ? ['json'] : ['prestart', 'pstop', 'pdelete'].includes(command) ? ['all'] : [];
+  const flags = new Set(['inspect', 'follow', 'supervisor', 'remove', 'json', 'all']);
+  const options = {}; let target;
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg.startsWith('-')) {
+      const key = arg.slice(2);
+      if (!arg.startsWith('--') || !allowed.includes(key)) throw new Error(`Unknown ${command} option: ${arg}`);
+      if (key in options) throw new Error(`Duplicate option: ${arg}`);
+      if (flags.has(key)) options[key] = true;
+      else { const value = argv[++index]; if (!value || value.startsWith('--')) throw new Error(`Provide a value for ${arg}`); options[key] = value; }
+    } else { if (target !== undefined) throw new Error(`${command} accepts one ${command === 'pstart' ? 'directory' : 'app name'}`); target = arg; }
+  }
+  if (target && (options.all || options.supervisor || ['pstartup', 'pdown'].includes(command))) throw new Error('Choose an app name or a global option, not both.');
+  for (const key of ['port', 'workers', 'health-timeout', 'drain-timeout', 'lines']) if (key in options) {
+    const max = key === 'port' ? 65535 : key === 'workers' ? 64 : key === 'lines' ? 10000 : 60000;
+    const min = key.endsWith('timeout') ? 100 : 1;
+    if (!/^\d+$/.test(options[key]) || Number(options[key]) < min || Number(options[key]) > max) throw new Error(`--${key} must be between ${min} and ${max}`);
+    options[key] = Number(options[key]);
+  }
+  if (options.name) validName(options.name);
+  if (options['health-path']) validHealthPath(options['health-path']);
+  if (command !== 'pstart' && target) validName(target);
+  return { target, options };
+}
+async function ensure(connection) {
+  let running;
+  try { running = await rpc(connection, { command: 'ping' }, 1500); }
+  catch (error) { if (!['ECONNREFUSED', 'ECONNRESET'].includes(error.code)) throw error; }
+  if (!running) {
+    const child = spawn(process.execPath, [fileURLToPath(new URL('./watchdog.mjs', import.meta.url)), connection.home], { cwd: connection.home, detached: true, windowsHide: true, stdio: 'ignore', env: environment() });
+    child.on('error', () => {}); child.unref();
+  }
+  for (let i = 0; i < 200; i++) {
+    try { const result = await rpc(connection, { command: 'ping' }, 1500); if (result.version !== 1) throw new Error('Supervisor protocol mismatch. Run prn pdown before upgrading.'); if (result.ready) return; }
+    catch (error) { if (!['ECONNREFUSED', 'ECONNRESET'].includes(error.code)) throw error; }
+    await delay(100);
+  }
+  throw new Error('Supervisor did not become ready. Check prn plogs --supervisor.');
+}
+async function offline(connection) {
+  let saved;
+  try { saved = JSON.parse(await readFile(path.join(connection.home, 'apps.json'), 'utf8')); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  return { daemonPid: null, apps: (saved?.apps || []).map(entry => ({ ...entry.config, enabled: entry.enabled, pid: null, state: 'supervisor-offline', starts: null })) };
+}
+async function tail(file, lines) {
+  let text = '', current;
+  for (const suffix of ['.3', '.2', '.1', '']) {
+    let handle;
+    try {
+      handle = await open(file + suffix, 'r'); const info = await handle.stat();
+      if (!suffix) current = info;
+      const size = Math.min(info.size, 1024 * 1024);
+      const buffer = Buffer.alloc(size); await handle.read(buffer, 0, size, info.size - size);
+      text = (text + buffer.toString()).slice(-1024 * 1024);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; } finally { await handle?.close(); }
+  }
+  return { text: text.split('\n').slice(-(lines + 1)).join('\n'), size: current?.size || 0, ino: current?.ino };
+}
+async function logs(connection, target, options) {
+  let name = target;
+  if (!options.supervisor && !name) {
+    const root = await realpath(process.cwd());
+    const saved = await offline(connection);
+    const matching = saved.apps.filter(app => app.root === root);
+    if (matching.length !== 1) throw new Error('Choose an app name from prn pstatus.');
+    name = matching[0].name;
+  }
+  const file = path.join(connection.home, 'logs', options.supervisor ? 'supervisor.log' : `app-${validName(name)}.log`);
+  const output = await tail(file, options.lines || 100);
+  process.stdout.write(output.text || 'No logs yet.\n');
+  if (!options.follow) return;
+  let offset = output.size, ino = output.ino, stopped = false;
+  const stop = () => { stopped = true; }; process.once('SIGINT', stop); process.once('SIGTERM', stop);
+  try {
+    while (!stopped) {
+      await delay(250); let handle;
+      try {
+        handle = await open(file, 'r'); const info = await handle.stat();
+        if (info.ino !== ino || info.size < offset) offset = 0;
+        ino = info.ino;
+        while (offset < info.size && !stopped) {
+          const buffer = Buffer.alloc(Math.min(65536, info.size - offset));
+          const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+          if (!bytesRead) break; offset += bytesRead;
+          if (!process.stdout.write(buffer.subarray(0, bytesRead))) await new Promise(resolve => process.stdout.once('drain', resolve));
+        }
+      } catch (error) { if (error.code !== 'ENOENT') throw error; } finally { await handle?.close(); }
+    }
+  } finally { process.off('SIGINT', stop); process.off('SIGTERM', stop); }
+}
+export async function persistentCommand(command, argv) {
+  if (argv.includes('--help') || argv.includes('-h')) { console.log(persistentHelp); return; }
+  const { target, options } = parsePersistent(command, argv);
+  const connection = await initializeHome();
+  if (command === 'pstartup') {
+    const { startup } = await import('./startup.mjs');
+    console.log(await startup(connection.home, { remove: !!options.remove })); return;
+  }
+  if (command === 'plogs') { await logs(connection, target, options); return; }
+  if (command === 'pdown') {
+    try {
+      const owner = await rpc(connection, { command: 'ping' });
+      const result = await rpc(connection, { command: 'shutdown' });
+      for (let i = 0; i < 100; i++) {
+        let alive = true;
+        try { process.kill(owner.pid, 0); } catch (error) { if (error.code === 'ESRCH') alive = false; }
+        if (!alive) { console.log(result); return; }
+        await delay(50);
+      }
+      throw new Error('Supervisor is still exiting. Check prn pstatus before starting another instance.');
+    }
+    catch (error) { if (error.code !== 'ECONNREFUSED') throw error; console.log('Supervisor is already stopped.'); }
+    return;
+  }
+  if (['pstatus', 'plist'].includes(command)) {
+    let report;
+    try { report = await rpc(connection, { command: 'status' }); }
+    catch (error) { if (error.code !== 'ECONNREFUSED') throw error; report = await offline(connection); }
+    if (target) { report.apps = report.apps.filter(app => app.name === target); if (!report.apps.length) throw new Error(`Unknown persistent app: ${target}`); }
+    if (options.json) console.log(JSON.stringify(report, null, 2));
+    else if (!report.apps.length) console.log('No persistent apps. Run prn pstart in a built project.');
+    else for (const app of report.apps) console.log(`${app.name}: ${app.state} | ${app.hostname}:${app.port} | pid ${app.pid || '—'}${app.error ? ' | ' + app.error : ''}`);
+    return;
+  }
+  let request;
+  if (command === 'pstart') {
+    const root = await realpath(path.resolve(target || '.'));
+    const name = validName(options.name || path.basename(root).replace(/[^a-zA-Z0-9_-]/g, '-').replace(/^[^a-zA-Z0-9]+/, '').slice(0, 64));
+    request = { command: 'start', config: { name, root, binary: await resolveNativeBinary(), node: process.execPath, port: options.port || 3000, hostname: options.hostname || '127.0.0.1', workers: options.workers || 1, profile: options.profile || process.env.PRNEXT_PROFILE || 'balanced', inspect: !!options.inspect, healthPath: options['health-path'] || '/', healthTimeout: options['health-timeout'] || 15000, drainTimeout: options['drain-timeout'] || 30000 } };
+  } else request = { command: ({ prestart: 'restart', pstop: 'stop', pdelete: 'delete' })[command], name: target, all: !!options.all, root: target || options.all ? undefined : await realpath(process.cwd()) };
+  await ensure(connection);
+  const report = await rpc(connection, request);
+  for (const app of Array.isArray(report) ? report : [report]) console.log(`${app.name}: ${app.state} | ${app.hostname}:${app.port}${app.pid ? ' | pid ' + app.pid : ''}`);
+}

package/runtime/persistent/common.mjs

@@ -0,0 +1,67 @@
+import { mkdir, readFile, writeFile, realpath, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import net from 'node:net';
+import path from 'node:path';
+import { rename } from '../fs.mjs';
+
+export const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+export const homeDirectory = () => path.resolve(process.env.PRNEXT_PM_HOME || path.join(homedir(), '.prnext', 'processes'));
+export async function initializeHome(directory = homeDirectory()) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const home = await realpath(directory);
+  const file = path.join(home, 'control.token');
+  try { await writeFile(file, randomBytes(32).toString('hex'), { flag: 'wx', mode: 0o600 }); }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+  let token = '';
+  // A second launcher may see the exclusive file between creation and write.
+  for (let attempt = 0; attempt < 50; attempt++) {
+    token = await readFile(file, 'utf8');
+    if (token.length) break;
+    await delay(20);
+  }
+  if (!/^[a-f0-9]{64}$/.test(token)) throw new Error(`Invalid supervisor credentials in ${file}`);
+  // A kernel-owned listener arbitrates simultaneous launches. No stale PID file
+  // is used to kill a process or steal a filesystem lock after a crash.
+  const key = process.platform === 'win32' ? home.toLowerCase() : home;
+  const port = 35000 + createHash('sha256').update(key).digest().readUInt16BE(0) % 20000;
+  return { home, token, port };
+}
+export async function atomicJSON(file, value) {
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+    await rename(temporary, file);
+  } finally { await rm(temporary, { force: true }); }
+}
+export function environment() {
+  const allowed = /^(?:path|home|userprofile|systemroot|windir|temp|tmp|tmpdir|lang|lc_all|localappdata|appdata|pathext|comspec)$/i;
+  return Object.fromEntries(Object.entries(process.env).filter(([key]) => allowed.test(key)));
+}
+export function validName(value) {
+  if (typeof value !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(value)) throw new Error('Choose an app name of 1–64 letters, digits, underscores or hyphens, starting with a letter or digit.');
+  return value;
+}
+export function validHealthPath(value) {
+  if (typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') || /[\\\x00-\x20\x7f#]/.test(value) || value.length > 2048) throw new Error('--health-path must be a local URL path such as /api/health');
+  return value;
+}
+export async function rpc(connection, request, timeout = 120000) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect({ host: '127.0.0.1', port: connection.port });
+    socket.setEncoding('utf8');
+    let buffer = '', finished = false;
+    const finish = (error, value) => { if (finished) return; finished = true; socket.destroy(); error ? reject(error) : resolve(value); };
+    socket.setTimeout(timeout, () => finish(new Error('Supervisor request timed out. Check prn plogs --supervisor.')));
+    socket.on('error', error => finish(error));
+    socket.once('connect', () => socket.write(JSON.stringify({ ...request, token: connection.token }) + '\n'));
+    socket.on('data', chunk => {
+      buffer += chunk.toString();
+      if (buffer.length > 1024 * 1024) return finish(new Error('Supervisor response is too large'));
+      if (!buffer.includes('\n')) return;
+      try { const result = JSON.parse(buffer.slice(0, buffer.indexOf('\n'))); finish(result.ok ? null : new Error(result.error || 'Supervisor request failed'), result.value); }
+      catch (error) { finish(error); }
+    });
+    socket.on('end', () => { if (!finished) finish(new Error('Supervisor disconnected')); });
+  });
+}

package/runtime/persistent/daemon.mjs

@@ -0,0 +1,312 @@
+import { spawn } from 'node:child_process';
+import { Agent, createServer, request } from 'node:http';
+import { cp, mkdir, readFile, rm, realpath } from 'node:fs/promises';
+import { randomUUID, createHash } from 'node:crypto';
+import path from 'node:path';
+import { readBuildDirectory } from '../build-directory.mjs';
+import { atomicJSON, delay, environment, validName, validHealthPath } from './common.mjs';
+import { RotatingLog } from './logger.mjs';
+
+const home = process.argv[2];
+const registry = path.join(home, 'apps.json');
+const owner = createHash('sha256').update(home).digest('hex').slice(0, 16);
+const apps = new Map();
+let closing = false, sequence = Promise.resolve();
+const send = message => { if (process.connected) process.send(message); };
+
+function validate(config) {
+  validName(config.name); validHealthPath(config.healthPath);
+  if (!path.isAbsolute(config.root) || !path.isAbsolute(config.binary) || !path.isAbsolute(config.node)) throw new Error('Application, Node and native executable paths must be absolute');
+  if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535) throw new Error('--port must be between 1 and 65535');
+  if (typeof config.hostname !== 'string' || !config.hostname || /[\s\x00-\x1f]/.test(config.hostname)) throw new Error('Choose a valid --hostname');
+  if (!Number.isInteger(config.workers) || config.workers < 1 || config.workers > 64) throw new Error('--workers must be between 1 and 64');
+  if (!['balanced', 'speed', 'memory', 'classic', 'standard', 'compact'].includes(config.profile)) throw new Error('Choose --profile balanced, speed, memory or classic');
+  for (const key of ['healthTimeout', 'drainTimeout']) if (!Number.isInteger(config[key]) || config[key] < 100 || config[key] > 60000) throw new Error(`${key} must be between 100 and 60000 milliseconds`);
+}
+async function persist() {
+  await atomicJSON(registry, { version: 1, apps: [...apps.values()].map(app => ({ config: app.config, enabled: app.enabled, snapshots: [...app.snapshots] })) });
+}
+function newApp(config, enabled = false) {
+  return { config, enabled, snapshots: new Set(), active: null, generations: new Set(), gateway: null, sockets: new Set(), state: 'stopped', error: null, starts: 0, failures: [], retry: null,
+    log: new RotatingLog(path.join(home, 'logs', `app-${config.name}.log`)) };
+}
+function summary(app) {
+  return { name: app.config.name, root: app.config.root, hostname: app.config.hostname, port: app.config.port,
+    state: app.state, enabled: app.enabled, pid: app.active?.child.pid || null, starts: app.starts,
+    activeRequests: [...app.generations].reduce((sum, generation) => sum + generation.active, 0),
+    draining: [...app.generations].filter(generation => generation !== app.active).length,
+    buildId: app.active?.buildId || null, startedAt: app.active?.startedAt || null, error: app.error,
+    log: path.join(home, 'logs', `app-${app.config.name}.log`) };
+}
+function hopHeaders(headers) {
+  const result = { ...headers };
+  const nominated = String(headers.connection || '').split(',').map(value => value.trim().toLowerCase());
+  for (const key of ['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade', ...nominated]) delete result[key];
+  return result;
+}
+async function listen(app) {
+  if (app.gateway) return;
+  const server = createServer({ requestTimeout: 300000, headersTimeout: 30000 }, (incoming, outgoing) => {
+    const generation = app.active;
+    if (!incoming.url.startsWith('/')) { outgoing.writeHead(400).end('Use a local request path.'); return; }
+    if (!generation || generation.dead) { outgoing.writeHead(503, { 'retry-after': '1' }).end('Application is restarting.'); incoming.resume(); return; }
+    if (generation.active >= 512) { outgoing.writeHead(503, { 'retry-after': '1' }).end('Application is busy.'); incoming.resume(); return; }
+    generation.active++;
+    const headers = hopHeaders(incoming.headers);
+    // Preserve original Host and trusted reverse-proxy headers. Never invent
+    // retry/replay behavior for POSTs or requests that have already streamed.
+    const upstream = request({ host: '127.0.0.1', port: generation.port, method: incoming.method, path: incoming.url, headers, agent: generation.agent }, response => {
+      outgoing.writeHead(response.statusCode, hopHeaders(response.headers));
+      response.on('error', () => outgoing.destroy()); response.pipe(outgoing);
+    });
+    generation.requests.add(upstream);
+    let released = false;
+    const release = () => { if (released) return; released = true; generation.active--; generation.requests.delete(upstream); upstream.destroy(); };
+    outgoing.once('finish', release); outgoing.once('close', release);
+    incoming.once('aborted', () => outgoing.destroy());
+    incoming.once('error', () => outgoing.destroy());
+    upstream.once('error', () => { if (!outgoing.headersSent) outgoing.writeHead(502).end('Application connection closed.'); else outgoing.destroy(); });
+    incoming.pipe(upstream);
+  });
+  server.on('upgrade', (_request, socket) => socket.end('HTTP/1.1 501 Not Implemented\r\nConnection: close\r\nContent-Length: 0\r\n\r\n'));
+  server.on('connection', socket => { app.sockets.add(socket); socket.once('close', () => app.sockets.delete(socket)); });
+  server.maxConnections = 1024;
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(app.config.port, app.config.hostname, resolve); });
+  server.on('error', error => { app.error = error.message; app.log.message(error.message); });
+  app.gateway = server;
+}
+async function removeSnapshot(app, relative) {
+  // Only delete a directory generated by this manager inside this exact root.
+  const prefix = `.prnext-persistent/${owner}/`;
+  if (!relative.startsWith(prefix) || !/^[a-f0-9-]{36}$/.test(relative.slice(prefix.length))) throw new Error('Invalid managed build path');
+  const root = await realpath(app.config.root);
+  const target = path.join(root, relative);
+  const actual = await realpath(target).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (actual && (actual !== target && (process.platform !== 'win32' || actual.toLowerCase() !== target.toLowerCase()))) throw new Error('Managed build path must not be a symbolic link');
+  if (actual) await rm(target, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  app.snapshots.delete(relative);
+}
+async function snapshot(app) {
+  const root = await realpath(app.config.root);
+  const dist = await readBuildDirectory(root);
+  if (dist.split('/')[0] === '.prnext-persistent') throw new Error('distDir cannot use .prnext-persistent');
+  const source = path.join(root, dist);
+  const before = await readFile(path.join(source, 'manifest.json'), 'utf8');
+  const manifest = JSON.parse(before);
+  if (manifest.dev || manifest.version !== 1 || !Array.isArray(manifest.routes)) throw new Error('Run prn build before prn pstart; a production build is required.');
+  const relative = `.prnext-persistent/${owner}/${randomUUID()}`;
+  app.snapshots.add(relative); await persist();
+  const destination = path.join(root, relative);
+  try {
+    await mkdir(path.dirname(destination), { recursive: true });
+    const container = await realpath(path.dirname(destination));
+    if (path.relative(root, container).startsWith('..') || path.isAbsolute(path.relative(root, container))) throw new Error('Managed builds must remain inside the project');
+    await cp(source, destination, { recursive: true, verbatimSymlinks: true, filter: file => file !== path.join(source, 'standalone') });
+    if (await readFile(path.join(source, 'manifest.json'), 'utf8') !== before || await readFile(path.join(destination, 'manifest.json'), 'utf8') !== before) throw new Error('Build changed while copying. Finish prn build, then retry prn prestart.');
+    return { relative, buildId: manifest.buildId || null };
+  } catch (error) { await removeSnapshot(app, relative); throw error; }
+}
+function health(generation, config, timeout) {
+  return new Promise((resolve, reject) => {
+    const req = request({ host: '127.0.0.1', port: generation.port, path: config.healthPath, method: 'GET', headers: { host: `${config.hostname.includes(':') ? '[' + config.hostname + ']' : config.hostname}:${config.port}` }, signal: AbortSignal.timeout(timeout) }, res => {
+      const ok = res.statusCode >= 200 && res.statusCode < 400;
+      res.destroy(); ok ? resolve() : reject(new Error(`Health check ${config.healthPath} returned HTTP ${res.statusCode}`));
+    });
+    req.once('error', reject); req.end();
+  });
+}
+async function stopGeneration(app, generation, drain = true) {
+  if (generation.stopping) return generation.stopping;
+  generation.expected = true;
+  generation.stopping = (async () => {
+    const deadline = Date.now() + (drain ? app.config.drainTimeout : 0);
+    while (generation.active && Date.now() < deadline && !generation.dead) await delay(25);
+    for (const req of generation.requests) req.destroy();
+    generation.agent.destroy();
+    generation.child.stdin?.end();
+    await Promise.race([generation.closed, delay(3000)]);
+    if (!generation.dead) generation.child.kill('SIGKILL');
+    if (process.platform !== 'win32' && generation.child.pid) { try { process.kill(-generation.child.pid, 'SIGKILL'); } catch {} }
+    await generation.closed;
+    app.generations.delete(generation);
+    await removeSnapshot(app, generation.relative);
+  })();
+  return generation.stopping;
+}
+function retry(app, error) {
+  if (!app.enabled || closing || app.retry) return;
+  app.error = error.message; app.state = 'restarting';
+  const now = Date.now(); app.failures = app.failures.filter(time => now - time < 300000); app.failures.push(now);
+  if (app.failures.length >= 10) { app.state = 'errored'; app.log.message('Stopped automatic retries after 10 failures in 5 minutes. Run prn prestart to retry.'); return; }
+  const wait = Math.min(30000, 500 * 2 ** Math.min(app.failures.length - 1, 6));
+  app.log.message(`Restart in ${wait} ms: ${error.message}`);
+  app.retry = setTimeout(() => {
+    app.retry = null;
+    sequence = sequence.then(async () => {
+      if (!app.enabled || closing || app.active) return;
+      try { await activate(app); } catch (error) { retry(app, error); }
+    }).catch(error => app.log.message(error.stack));
+  }, wait);
+}
+async function launch(app) {
+  const config = app.config;
+  const build = await snapshot(app);
+  const child = spawn(config.binary, ['start', config.root, '--build-dir', build.relative, '--hostname', '127.0.0.1', '--port', '0', '--node', config.node, '--workers', String(config.workers), '--profile', config.profile, '--shutdown-on-stdin-eof'], {
+    cwd: config.root, windowsHide: true, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...environment(), NODE_ENV: 'production', ...(config.inspect ? { PRNEXT_INSPECT_DIR: path.join(config.root, '.prnext-cache/inspect') } : {}) },
+  });
+  child.stdin.on('error', () => {});
+  const generation = { child, ...build, active: 0, requests: new Set(), agent: new Agent({ keepAlive: true, maxSockets: 512, maxFreeSockets: 16, timeout: 30000 }), dead: false, expected: false, port: null, startedAt: Date.now() };
+  app.generations.add(generation);
+  if (child.pid) send({ type: 'child', pid: child.pid, running: true });
+  let output = '', failure;
+  const started = chunk => { output = (output + chunk.toString()).slice(-8192); generation.port ||= Number(/http:\/\/127\.0\.0\.1:(\d+)/.exec(output)?.[1]) || null; };
+  child.stdout.on('data', started);
+  child.once('error', error => { failure = error; });
+  child.once('exit', () => {
+    generation.dead = true;
+    // On Unix an abruptly killed native parent cannot close descendants itself.
+    // Kill its private group before waiting for inherited log pipes to close.
+    if (!generation.expected && process.platform !== 'win32' && child.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} }
+  });
+  app.log.attach(child.stdout, 'stdout'); app.log.attach(child.stderr, 'stderr');
+  generation.closed = new Promise(resolve => child.once('close', (code, signal) => {
+    generation.dead = true;
+    if (child.pid) send({ type: 'child', pid: child.pid, running: false });
+    if (app.active === generation) app.active = null;
+    if (!generation.expected) {
+      app.log.message(`Process ${child.pid || 'unknown'} exited (${signal || code}).`);
+      if (generation.ready) {
+        // Serialize recovery and cleanup with explicit lifecycle commands.
+        sequence = sequence.then(async () => { await stopGeneration(app, generation, false); await persist(); retry(app, new Error(`Application exited (${signal || code})`)); }).catch(error => app.log.message(error.stack));
+      }
+    }
+    resolve();
+  }));
+  try {
+    const deadline = Date.now() + config.healthTimeout;
+    while (!generation.port) {
+      if (failure || generation.dead) throw failure || new Error('Application exited before listening. Check prn plogs.');
+      if (Date.now() >= deadline) throw new Error('Application did not listen before --health-timeout');
+      await delay(25);
+    }
+    await health(generation, config, Math.max(1, deadline - Date.now()));
+    if (generation.dead) throw new Error('Application exited during its health check');
+    generation.ready = true; app.starts++;
+    return generation;
+  } catch (error) { await stopGeneration(app, generation, false); throw error; }
+  finally { child.stdout.off('data', started); }
+}
+async function activate(app) {
+  await listen(app);
+  const previous = app.active;
+  const wasEnabled = app.enabled;
+  let next;
+  app.state = previous ? 'reloading' : 'starting';
+  try {
+    next = await launch(app);
+    app.enabled = true;
+    await persist();
+    if (next.dead) throw new Error('Application exited before traffic could switch');
+    app.active = next; app.state = 'online'; app.error = null;
+    app.log.message(`Ready: pid ${next.child.pid}, build ${next.buildId || 'unknown'}, ${app.config.hostname}:${app.config.port}`);
+  } catch (error) {
+    if (next) await stopGeneration(app, next, false).catch(cleanup => app.log.message(cleanup.message));
+    app.enabled = wasEnabled;
+    app.state = previous && !previous.dead ? 'online' : 'errored'; app.error = error.message;
+    await persist().catch(saved => app.log.message(saved.message));
+    app.log.message(`Start failed; ${previous && !previous.dead ? 'previous generation remains active' : 'no healthy generation'}: ${error.message}`);
+    throw error;
+  }
+  if (previous) {
+    await stopGeneration(app, previous).catch(error => app.log.message(`Previous build cleanup: ${error.message}`));
+    await persist();
+  }
+}
+async function stopApp(app) {
+  app.enabled = false; clearTimeout(app.retry); app.retry = null;
+  await persist();
+  app.state = 'stopping'; app.active = null;
+  const gateway = app.gateway; app.gateway = null;
+  const closed = gateway ? new Promise(resolve => gateway.close(resolve)) : Promise.resolve();
+  gateway?.closeIdleConnections();
+  await Promise.all([...app.generations].map(generation => stopGeneration(app, generation)));
+  for (const socket of app.sockets) socket.destroy();
+  await closed; app.state = 'stopped'; app.error = null; await persist();
+  app.log.message('Stopped.');
+}
+function select(message) {
+  const selected = message.all ? [...apps.values()] : [...apps.values()].filter(app => message.name ? app.config.name === message.name : app.config.root === message.root);
+  if (!selected.length && !message.all) throw new Error('No matching persistent app. Run prn pstatus to see app names.');
+  if (selected.length > 1 && !message.all) throw new Error('Several apps use this directory. Choose an app name.');
+  return selected;
+}
+async function command(message) {
+  if (message.command === 'status') return { daemonPid: process.pid, apps: [...apps.values()].map(summary) };
+  if (message.command === 'start') {
+    validate(message.config);
+    message.config.root = await realpath(message.config.root);
+    let app = apps.get(message.config.name);
+    if (app) {
+      if (JSON.stringify(app.config) !== JSON.stringify(message.config)) throw new Error('This app name already has different settings. Use prn pdelete, then prn pstart with the new settings.');
+      if (app.active) return summary(app);
+    } else {
+      if (apps.size >= 128) throw new Error('The supervisor supports up to 128 apps');
+      if ([...apps.keys()].some(name => name.toLowerCase() === message.config.name.toLowerCase())) throw new Error('App names must be distinct regardless of letter case.');
+      app = newApp(message.config); apps.set(message.config.name, app);
+    }
+    clearTimeout(app.retry); app.retry = null; app.failures = [];
+    try { await activate(app); }
+    catch (error) { await stopApp(app); app.state = 'errored'; app.error = error.message; throw error; }
+    return summary(app);
+  }
+  const selected = select(message);
+  if (message.command === 'restart') {
+    for (const app of selected) { clearTimeout(app.retry); app.retry = null; app.failures = []; await activate(app); }
+  } else if (message.command === 'stop' || message.command === 'delete') {
+    for (const app of selected) { await stopApp(app); if (message.command === 'delete') { apps.delete(app.config.name); app.log.end(); } }
+    await persist();
+  } else throw new Error('Unknown supervisor command');
+  return selected.map(summary);
+}
+async function shutdown() {
+  if (closing) return; closing = true;
+  await sequence;
+  // A supervisor shutdown preserves each enabled flag for the next launch.
+  await Promise.all([...apps.values()].map(async app => {
+    clearTimeout(app.retry); app.active = null; app.gateway?.close();
+    await Promise.all([...app.generations].map(generation => stopGeneration(app, generation)));
+    for (const socket of app.sockets) socket.destroy();
+    app.log.end();
+  }));
+  await persist(); process.exit(0);
+}
+process.on('disconnect', () => void shutdown());
+process.on('SIGTERM', () => void shutdown());
+process.on('SIGINT', () => void shutdown());
+process.on('message', message => {
+  if (message.type === 'heartbeat') { send({ type: 'heartbeat' }); return; }
+  if (message.type === 'shutdown') { void shutdown(); return; }
+  if (message.type !== 'request') return;
+  const perform = async () => {
+    try { if (closing) throw new Error('Supervisor is shutting down'); send({ type: 'reply', id: message.id, ok: true, value: await command(message.request) }); }
+    catch (error) { send({ type: 'reply', id: message.id, ok: false, error: error.message }); }
+  };
+  if (message.request.command === 'status') void perform(); else sequence = sequence.then(perform);
+});
+try {
+  let saved;
+  try { saved = JSON.parse(await readFile(registry, 'utf8')); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (saved && (saved.version !== 1 || !Array.isArray(saved.apps) || saved.apps.length > 128)) throw new Error('Unsupported persistent application registry');
+  for (const entry of saved?.apps || []) {
+    validate(entry.config);
+    if ([...apps.keys()].some(name => name.toLowerCase() === entry.config.name.toLowerCase())) throw new Error('Duplicate app names in persistent registry');
+    const app = newApp(entry.config, entry.enabled); apps.set(app.config.name, app);
+    app.snapshots = new Set(entry.snapshots || []);
+    for (const relative of app.snapshots) await removeSnapshot(app, relative).catch(error => app.log.message(error.message));
+  }
+  sequence = sequence.then(async () => {
+    for (const app of apps.values()) if (app.enabled) { try { await activate(app); } catch (error) { retry(app, error); } }
+  });
+  send({ type: 'ready' });
+} catch (error) { console.error(error.stack); process.exit(1); }

package/runtime/persistent/logger.mjs

@@ -0,0 +1,52 @@
+import { Writable } from 'node:stream';
+import { mkdir, open, stat, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+// Backpressure reaches the child's stdout/stderr; even a noisy app cannot grow
+// an unbounded in-memory write queue. Each file retains three older segments.
+export class RotatingLog extends Writable {
+  constructor(file, { maxBytes = 10 * 1024 * 1024, backups = 3 } = {}) {
+    super({ highWaterMark: 64 * 1024 });
+    this.file = file; this.maxBytes = maxBytes; this.backups = backups; this.size = 0;
+    this.on('error', () => {});
+  }
+  _construct(callback) {
+    (async () => {
+      await mkdir(path.dirname(this.file), { recursive: true, mode: 0o700 });
+      this.size = await stat(this.file).then(info => info.size, () => 0);
+      this.handle = await open(this.file, 'a', 0o600);
+    })().then(() => callback(), callback);
+  }
+  async rotate() {
+    await this.handle.close(); this.handle = undefined;
+    await rm(`${this.file}.${this.backups}`, { force: true });
+    for (let i = this.backups - 1; i >= 0; i--) {
+      try { await rename(i ? `${this.file}.${i}` : this.file, `${this.file}.${i + 1}`); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    this.handle = await open(this.file, 'a', 0o600); this.size = 0;
+  }
+  _write(chunk, encoding, callback) {
+    (async () => {
+      let offset = 0;
+      while (offset < chunk.length) {
+        if (this.size >= this.maxBytes) await this.rotate();
+        const count = Math.min(chunk.length - offset, this.maxBytes - this.size);
+        const { bytesWritten } = await this.handle.write(chunk.subarray(offset, offset + count));
+        if (!bytesWritten) throw new Error('Unable to write application log');
+        offset += bytesWritten; this.size += bytesWritten;
+      }
+    })().then(() => callback(), callback);
+  }
+  _final(callback) { this.handle?.close().then(() => callback(), callback) ?? callback(); }
+  _destroy(error, callback) { this.handle?.close().then(() => callback(error), () => callback(error)) ?? callback(error); }
+  message(value) { return this.write(`[${new Date().toISOString()}] ${value}\n`); }
+  attach(stream, label) {
+    const resume = () => stream.resume();
+    stream.on('data', chunk => { if (!this.destroyed && !this.write(Buffer.concat([Buffer.from(`[${label}] `), chunk]))) stream.pause(); });
+    this.on('drain', resume);
+    const cleanup = () => { this.off('drain', resume); stream.resume(); };
+    this.once('error', cleanup);
+    stream.once('close', () => { this.off('drain', resume); this.off('error', cleanup); });
+  }
+}