@thomas.f/prnext 0.1.19-alpha → 0.1.21-alpha

package/build/app.mjs

@@ -6,9 +6,9 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { createRequire, builtinModules } from 'node:module';
 import { fileURLToPath } from 'node:url';
-import { parse } from '@babel/parser';
 import * as t from '@babel/types';
-import { rewriteServerChunks } from './transform.mjs';
+import {analyzeSourceSummary} from './source-analysis.mjs';
+import { rewriteServerChunkOutputFiles } from './transform.mjs';
 import { transformDynamicImports } from './dynamic.mjs';
 import { createServerActions } from './actions.mjs';
 import { expandActionExports } from './action-exports.mjs';
@@ -22,6 +22,8 @@ import {createAppStyleGraph, appStyleScopes, planAppStyleEntries} from './app-st
 import {selectHtmlOnlyRoutes} from './html-only-config.mjs';
 import {createHtmlOnlyGraph} from './html-only-graph.mjs';
 import {createLazyDynamicImports} from './lazy-dynamic-imports.mjs';
+import {developmentActionMetadata} from './dev-action-graph.mjs';
+import {immutableStylePlan, executeStylePlan, createStyleOutputWriter} from './parallel-plan.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const extensions = { '.js': 'jsx', '.jsx': 'jsx', '.mjs': 'jsx', '.cjs': 'jsx', '.ts': 'ts', '.tsx': 'tsx', '.mts': 'ts', '.cts': 'ts' };
@@ -43,77 +45,28 @@ export async function validateReactVersions(resolveFromProject) {
   }
 }
 
-function sourceAst(source, filename) {
-  return parse(source, { sourceType: 'unambiguous', sourceFilename: filename, plugins: ['jsx', ...(/\.[cm]?tsx?$/.test(filename) ? ['typescript'] : [])] });
-}
 function clientDirective(source, filename) {
   if (!source.includes('use client')) return false;
-  return sourceAst(source, filename).program.directives.some(directive => directive.value.value === 'use client');
+  return analyzeSourceSummary(source,filename).directives.includes('use client');
 }
 
 function frameworkDirective(source, filename) {
   if (clientDirective(source, filename)) return true;
   if (!source.includes('use server')) return false;
-  function contains(node) {
-    if (!node || typeof node !== 'object') return false;
-    if (t.isDirective(node) && node.value.value === 'use server') return true;
-    return (t.VISITOR_KEYS[node.type] || []).some(key => Array.isArray(node[key]) ? node[key].some(contains) : contains(node[key]));
-  }
-  return contains(sourceAst(source, filename));
+  return analyzeSourceSummary(source,filename).hasServerDirective;
 }
 
 /** Enumerate runtime ESM exports without evaluating client code in the server build. */
-async function exportedNames(file, esbuild, seen = new Set()) {
+export async function exportedNames(file, esbuild, seen = new Set()) {
   if (seen.has(file)) return new Set();
   seen.add(file);
   const source = await compilerSource(file);
-  const ast = sourceAst(source, file);
-  const names = new Set();
-  for (const node of ast.program.body) {
-    if (t.isExportDefaultDeclaration(node)) { names.add('default'); continue; }
-    if (node.exportKind === 'type') continue;
-    if (t.isExportNamedDeclaration(node)) {
-      if (node.declaration && !t.isTSInterfaceDeclaration(node.declaration) && !t.isTSTypeAliasDeclaration(node.declaration) && !node.declaration.declare) {
-        for (const name of Object.keys(t.getOuterBindingIdentifiers(node.declaration))) names.add(name);
-      }
-      for (const specifier of node.specifiers) if (specifier.exportKind !== 'type') names.add(specifier.exported.name ?? specifier.exported.value);
-    }
-    if (t.isExportAllDeclaration(node)) {
-      const resolved = await esbuild.resolve(node.source.value, { resolveDir: path.dirname(file), kind: 'import-statement', pluginData: { prnextExportScan: true } });
-      if (resolved.errors.length || !resolved.path || resolved.external) throw new Error(`Cannot enumerate client boundary exports from ${node.source.value} in ${file}. Use explicit named re-exports.`);
+  const analysis=analyzeSourceSummary(source,file),names=new Set(analysis.runtimeExports);
+  for (const specifier of analysis.exportStars) {
+      const resolved = await esbuild.resolve(specifier, { resolveDir: path.dirname(file), kind: 'import-statement', pluginData: { prnextExportScan: true } });
+      if (resolved.errors.length || !resolved.path || resolved.external) throw new Error(`Cannot enumerate client boundary exports from ${specifier} in ${file}. Use explicit named re-exports.`);
       for (const name of await exportedNames(resolved.path, esbuild, seen)) if (name !== 'default') names.add(name);
-    }
   }
-  // CommonJS is supported for npm and PRNext compatibility components. The default
-  // is module.exports; statically assigned properties are named exports as in Node.
-  function visit(node) {
-    if (!node || typeof node !== 'object') return;
-    if (t.isCallExpression(node) && t.isMemberExpression(node.callee) && t.isIdentifier(node.callee.object, { name: 'Object' }) && t.isIdentifier(node.callee.property, { name: 'defineProperty' }) && t.isIdentifier(node.arguments[0], { name: 'exports' }) && t.isStringLiteral(node.arguments[1]) && node.arguments[1].value !== '__esModule') {
-      names.add('default');
-      names.add(node.arguments[1].value);
-    }
-    if (t.isAssignmentExpression(node) && t.isMemberExpression(node.left)) {
-      const left = node.left;
-      const property = left.computed ? left.property.value : left.property.name;
-      if (t.isIdentifier(left.object, { name: 'module' }) && property === 'exports') {
-        names.add('default');
-        if (t.isObjectExpression(node.right)) for (const item of node.right.properties) {
-          const key = item.computed ? item.key?.value : item.key?.name ?? item.key?.value;
-          if (typeof key === 'string') names.add(key);
-        }
-      }
-      if (t.isIdentifier(left.object, { name: 'exports' }) || (t.isMemberExpression(left.object) && t.isIdentifier(left.object.object, { name: 'module' }) && left.object.property.name === 'exports')) {
-        names.add('default');
-        if (typeof property === 'string') names.add(property);
-      }
-    }
-    for (const key of t.VISITOR_KEYS[node.type] || []) {
-      const child = node[key];
-      if (Array.isArray(child)) child.forEach(visit); else visit(child);
-    }
-  }
-  visit(ast.program);
-  names.delete('__esModule');
   return names;
 }
 
@@ -178,7 +131,7 @@ function routeEntry(route, globalError, dev) {
 }
 
 /** Compile independent React Server and client graphs. The RSC graph contains only references to client boundaries. */
-export async function compileApp({ project, stage, manifest, cssModules, fonts, images, dev, devActionSecret, reactCompiler = false, defineEnvironment = {}, productionBrowserSourceMaps = false, serverExternalPackages = [], moduleResolution = {},lazyDynamicImports=false,devLazyRequest,devLazyOnly=false,devLazyActivated=[] }) {
+export async function compileApp({ project, stage, manifest, cssModules, fonts, images, dev, devActionSecret, reactCompiler = false, defineEnvironment = {}, productionBrowserSourceMaps = false, serverExternalPackages = [], moduleResolution = {},lazyDynamicImports=false,devLazyRequest,devLazyOnly=false,devLazyActivated=[], parallelBuilds=false }) {
   if(devLazyOnly&&(!dev||!lazyDynamicImports||!devLazyRequest))throw Error('Deferred-only compilation requires a registered development import');
   const refresh = dev ? createRefreshTransform(project.root, {generation:manifest.cacheId,forceGeneration:manifest.devForceRefresh,forceFiles:manifest.devAffectedModules}) : undefined;
   const locations = dev ? createSourceLocationTransform(project.root) : undefined;
@@ -229,6 +182,7 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     for (const segment of route.segments || []) if (segment.layout) cacheSegments.set(await canonicalFile(segment.layout), 'layout');
   }
   let browserStyleRevision;
+  const writeParallelStyles = parallelBuilds ? createStyleOutputWriter(path.join(stage, 'assets')) : undefined;
   const resolveFromProject = createRequire(path.join(project.root, 'package.json'));
   await validateReactVersions(resolveFromProject);
   const nativePackages = createNativePackages(project.root, { isClientSource: frameworkDirective });
@@ -317,8 +271,11 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
           htmlGraph?.source(args.path, original);
           // Only Client Component graphs use React's memo-cache runtime. Server
           // Components, route handlers and Server Action graphs remain untouched.
-          const compiled=compileReact && (browser || mode==='ssr') ? await compileReact(original,args.path,{loaderOutput:args.prnextSource!==undefined}) : original;
-          const source = await fonts.transform(await expandActionExports(locations?await locations(compiled,args.path):compiled, args.path, async (specifier, importer) => {
+          const compile = compileReact && (browser || mode==='ssr');
+          const locateFirst = !!(compile && reactCompiler.backend==='oxc' && locations);
+          const input = locateFirst ? await locations(original,args.path) : original;
+          const compiled = compile ? await compileReact(input,args.path,{loaderOutput:args.prnextSource!==undefined}) : input;
+          const source = await fonts.transform(await expandActionExports(locations && !locateFirst ? await locations(compiled,args.path) : compiled, args.path, async (specifier, importer) => {
             const resolved = await esbuild.resolve(specifier, { resolveDir: path.dirname(importer), kind: 'import-statement', pluginData: { prnextExportScan: true } });
             return resolved.errors.length || resolved.external || resolved.namespace !== 'file' ? undefined : resolved.path;
           }), args.path);
@@ -401,8 +358,11 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     const result = await compileEdge({ file, outfile, projectRoot: project.root, dev, defineEnvironment, reactMode: mode, defaultExport, transformTypedHelpers:!!compileReact && mode==='ssr',
       plugins: [moduleResolutionPlugin(moduleResolution, project.root), edgeGraphPlugin(mode), images.plugin(), fonts.plugin(), cssModules.plugin(false)],
       transformSource: async (source, file, builder, {loaderOutput=false}={}) => {
-        const compiled=compileReact && mode==='ssr' ? await compileReact(source,file,{loaderOutput}) : source;
-        return actionTransform(await fonts.transform(await expandActionExports(locations?await locations(compiled,file):compiled, file, async (specifier, importer) => {
+        const compile = compileReact && mode==='ssr';
+        const locateFirst = !!(compile && reactCompiler.backend==='oxc' && locations);
+        const input = locateFirst ? await locations(source,file) : source;
+        const compiled = compile ? await compileReact(input,file,{loaderOutput}) : input;
+        return actionTransform(await fonts.transform(await expandActionExports(locations && !locateFirst ? await locations(compiled,file) : compiled, file, async (specifier, importer) => {
           const resolved = await builder.resolve(specifier, {resolveDir:path.dirname(importer),kind:'import-statement',pluginData:{prnextExportScan:true}});
           return resolved.errors.length || resolved.external || resolved.namespace !== 'file' ? undefined : resolved.path;
         }), file), file, mode, 'edge', source);
@@ -439,14 +399,15 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     fonts.record(output.metafile);
     styleGraph.record(output.metafile);
     htmlGraph?.record(output.metafile);
+    const chunks = new Set(Object.keys(output.metafile.outputs).filter(file => file.endsWith('.mjs')).map(file => path.basename(file)));
+    const importers = new Set(Object.entries(output.metafile.outputs).filter(([file,metadata])=>file.endsWith('.mjs')&&metadata.imports.some(item=>!item.external)).map(([file])=>path.resolve(project.root,file)));
+    output={...output,outputFiles:rewriteServerChunkOutputFiles(output.outputFiles,chunks,assetBase,importers)};
     for (const file of output.outputFiles) {
       await mkdir(path.dirname(file.path), { recursive: true });
       await writeFile(file.path, file.contents);
     }
-    const chunks = new Set(Object.keys(output.metafile.outputs).filter(file => file.endsWith('.mjs')).map(file => path.basename(file)));
     for (const [file, metadata] of Object.entries(output.metafile.outputs)) {
       const absolute = path.resolve(project.root, file);
-      if (file.endsWith('.mjs') && metadata.imports.some(item => !item.external)) await rewriteServerChunks(absolute, chunks, assetBase);
       if (!metadata.entryPoint && !file.endsWith('.map') && !file.endsWith('.mjs')) await cp(absolute, path.join(stage, 'assets', path.basename(file)));
     }
     return output;
@@ -597,24 +558,30 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
       if (!id) continue;
       manifest.app.clientModules[id] = { id, chunks: [id, publicPath + path.basename(output)], name: '*', ssrModule: `app-ssr/${id}.mjs`, ...(edgeBoundaries.has(id) ? { edgeSsrModule: `app-ssr-edge/${id}.mjs` } : {}), browserModule: publicPath + path.basename(output) };
     }
-    const styleBundles = new Map();
-    for (const route of routes.filter(route => route.kind === 'page')) {
+    const styledRoutes = routes.filter(route => route.kind === 'page');
+    for (const route of styledRoutes) {
       // All esbuild graphs canonicalize their inputs, including symlinked
       // convention files. Match those identities before querying reachability.
       for (const files of appStyleScopes(route)) for (const file of files) styleGraph.alias(file, await canonicalFile(file));
-      const plan = planAppStyleEntries(route, styleGraph);
+    }
+    // Freeze discovery before any independent emission starts. Deduplication
+    // owns each output path once, and linking follows source order even when
+    // builds complete out of order. Failure drains all started jobs first.
+    const plan = immutableStylePlan(styledRoutes, route => planAppStyleEntries(route, styleGraph));
+    const {outputs: styleBundles, concurrency} = await executeStylePlan(plan, async ({styles: files}) => {
+      const id = 'app-style-' + createHash('sha256').update(files.map(file => path.relative(project.root, file).replaceAll(path.sep, '/')).join('\0')).digest('hex').slice(0, 16);
+      const styleEntry = path.join(stage, '.entries', id + '.mjs');
+      await writeFile(styleEntry, files.map(file => `import ${JSON.stringify(file)};`).join('\n'));
+      const output = await bundle({ ...common, ...(writeParallelStyles ? {write: false} : {}), entryPoints: { [id]: styleEntry }, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], minify: !dev, sourcemap: dev || productionBrowserSourceMaps,
+        plugins: [moduleResolutionPlugin(moduleResolution, project.root), images.plugin(), fonts.plugin(), graphPlugin('browser', { omitGlobalStyles: false }), cssModules.plugin(true)] }, { role: 'styles' });
+      if (writeParallelStyles) await writeParallelStyles(output.outputFiles);
+      return Object.values(output.metafile.outputs).filter(output => output.cssBundle).map(output => publicPath + path.basename(output.cssBundle));
+    }, dev ? false : parallelBuilds);
+    if (!dev && parallelBuilds) manifest.buildParallelism = {version: 1, phase: 'app-styles', jobs: plan.jobs.length, concurrency};
+    for (const route of plan.routes) {
       const styles = [];
       const cssScopes = [];
-      for (const { styles:files, path:scopePath, kind } of plan) {
-        const signature = JSON.stringify(files);
-        if (!styleBundles.has(signature)) {
-          const id = 'app-style-' + createHash('sha256').update(files.map(file => path.relative(project.root, file).replaceAll(path.sep, '/')).join('\0')).digest('hex').slice(0, 16);
-          const styleEntry = path.join(stage, '.entries', id + '.mjs');
-          await writeFile(styleEntry, files.map(file => `import ${JSON.stringify(file)};`).join('\n'));
-          const output = await bundle({ ...common, entryPoints: { [id]: styleEntry }, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], minify: !dev, sourcemap: dev || productionBrowserSourceMaps,
-            plugins: [moduleResolutionPlugin(moduleResolution, project.root), images.plugin(), fonts.plugin(), graphPlugin('browser', { omitGlobalStyles: false }), cssModules.plugin(true)] }, { role: 'styles' });
-          styleBundles.set(signature, Object.values(output.metafile.outputs).filter(output => output.cssBundle).map(output => publicPath + path.basename(output.cssBundle)));
-        }
+      for (const { signature, path:scopePath, kind } of route.scopes) {
         const css = styleBundles.get(signature);
         styles.push(...css);
         if (route.parallel) cssScopes.push({ path:scopePath, kind, css });
@@ -634,6 +601,7 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
   }
 
   lazy?.finish();
+  if (dev) manifest.devActions = developmentActionMetadata(project.root, actions.actions.values());
 
   if (htmlGraph) for (const route of routes) if (htmlOnly.has(route.id)) {
     for (const file of [...appStyleScopes(route).flat(), ...(route.metadataFiles || []).map(item=>item.file)].filter(Boolean)) htmlGraph.alias(file, await canonicalFile(file));

package/build/build-lock.mjs

@@ -1,71 +1,2 @@
-import { mkdir, writeFile, rename, rm, realpath, lstat, open } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
-import { hostname } from 'node:os';
-import path from 'node:path';
-
-const LOCK = '.prnext-build.lock';
-const busy = message => Object.assign(new Error(message), { code: 'PRNEXT_BUILD_LOCKED' });
-function alive(pid) {
-  try { process.kill(pid, 0); return true; }
-  catch (error) { return error.code !== 'ESRCH'; }
-}
-async function owner(directory) {
-  const info = await lstat(directory);
-  if (!info.isDirectory() || info.isSymbolicLink()) throw busy(`The project lock is not a real directory. Check ${path.basename(directory)} before retrying.`);
-  const file = await open(path.join(directory, 'owner.json'), 'r');
-  try {
-    if ((await file.stat()).size > 4096) throw new Error('oversized owner');
-    const value = JSON.parse(await file.readFile('utf8'));
-    if (!Number.isSafeInteger(value.pid) || value.pid < 1 || typeof value.host !== 'string' || !/^[a-f0-9-]{36}$/.test(value.token)) throw new Error('invalid owner');
-    return value;
-  } finally { await file.close(); }
-}
-
-/** One publisher per canonical project, covering React and direct static imports. */
-export async function withBuildLock(directory, action, {development = false} = {}) {
-  const root = await realpath(directory), lock = path.join(root, development ? '.prnext-dev.lock' : LOCK);
-  const identity = { pid: process.pid, host: hostname(), token: randomUUID(), createdAt: new Date().toISOString() };
-  const prepared = path.join(root, `.prnext-lock-${identity.token}`);
-  await mkdir(prepared, { mode: 0o700 });
-  try {
-    await writeFile(path.join(prepared, 'owner.json'), JSON.stringify(identity), { flag: 'wx', mode: 0o600 });
-    for (let attempt = 0; ; attempt++) {
-      try { await rename(prepared, lock); break; }
-      catch (error) {
-        if (!['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES'].includes(error.code)) throw error;
-        let previous;
-        try { previous = await owner(lock); }
-        catch (cause) {
-          if (cause.code === 'ENOENT' && attempt < 8) continue;
-          throw busy(`Cannot verify the project lock. Check ${path.basename(lock)} before retrying.`);
-        }
-        if (previous.host !== identity.host || alive(previous.pid)) throw busy(development ? `A development server is already running for this project (PID ${previous.pid}). Stop it before starting another.` : `A build is already running for this project (PID ${previous.pid}). Wait for it to finish.`);
-        // Exactly one contender can recover this generation. Never delete a lock
-        // merely because it is old: long builds and suspended processes are valid.
-        let claim;
-        try { claim = await open(path.join(lock, 'recovery'), 'wx', 0o600); }
-        catch (cause) {
-          if (cause.code === 'ENOENT' && attempt < 8) continue;
-          throw busy(`Project lock recovery is in progress. Retry shortly; if recovery was interrupted, check ${path.basename(lock)} manually.`);
-        }
-        const retired = path.join(root, `.prnext-lock-retired-${identity.token}`);
-        try {
-          await claim.writeFile(JSON.stringify(identity)); await claim.close(); claim = null;
-          const current = await owner(lock);
-          if (current.token !== previous.token) {
-            // Do not unlink through this path: the new owner can release and
-            // another generation can appear between our read and the unlink.
-            throw busy('The build lock changed during recovery. Retry the build.');
-          }
-          await rename(lock, retired);
-          await rm(retired, { recursive: true });
-        } finally { await claim?.close(); }
-      }
-    }
-    try { return await action(root); }
-    finally {
-      // Ownership must still match before releasing a lock.
-      if ((await owner(lock)).token === identity.token) await rm(lock, { recursive: true });
-    }
-  } finally { await rm(prepared, { recursive: true, force: true }); }
-}
+// Compiler entry point for the shared publisher and maintenance lock protocol.
+export {withBuildLock} from '../runtime/project-lock.mjs';

package/build/build-retention.mjs

@@ -0,0 +1,119 @@
+// Recovery journal for framework-owned build stages. Uncommitted backups can
+// be the only working build after a crash: keep them for explicit recovery.
+import {mkdir,open,opendir,lstat,rename,unlink,rm,realpath} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {randomUUID} from 'node:crypto';
+import {hostname} from 'node:os';
+import path from 'node:path';
+import {captureStorageDirectory,verifyStorageDirectories,sameStoragePath} from '../runtime/storage-path.mjs';
+const uuid='[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}';
+const recordName=new RegExp('^'+uuid+'\\.json$'),stageName=new RegExp('^\\.prnext-build-'+uuid+'$'),backupName=new RegExp('^\\.prnext-backup-'+uuid+'$');
+const MAX_JOURNAL_NAMES=32768,MAX_PAGE=128;
+async function container(root){
+  const directory=path.join(root,'.prnext-gc');
+  await mkdir(directory,{mode:0o700}).catch(error=>{if(error.code!=='EEXIST')throw error;});
+  const info=await lstat(directory);if(!info.isDirectory()||info.isSymbolicLink())throw Error('Build recovery journal must be a real directory.');
+  return directory;
+}
+async function readValue(file){
+  let handle;
+  try{
+    const info=await lstat(file);if(!info.isFile()||info.isSymbolicLink()||info.size>4096)return null;
+    handle=await open(file,constants.O_RDONLY|(constants.O_NOFOLLOW||0));if((await handle.stat()).size>4096)return null;
+    return JSON.parse(await handle.readFile('utf8'));
+  }catch{return null;}finally{await handle?.close().catch(()=>{});}
+}
+async function read(file){
+  const value=await readValue(file);
+  if(!value||value.version!==1||!Number.isSafeInteger(value.pid)||value.pid<1||typeof value.host!=='string'||!Number.isSafeInteger(value.createdAt)||!stageName.test(value.stage)||!backupName.test(value.backup)||typeof value.committed!=='boolean')return null;
+  return value;
+}
+async function save(file,value){
+  const temporary=file+'.'+randomUUID()+'.tmp';
+  try{const handle=await open(temporary,'wx',0o600);try{await handle.writeFile(JSON.stringify(value));}finally{await handle.close();}await rename(temporary,file);}
+  finally{await unlink(temporary).catch(()=>{});}
+}
+function alive(pid){try{process.kill(pid,0);return true;}catch(error){return error.code!=='ESRCH';}}
+async function remove(root,name,pattern){
+  if(!pattern.test(name))return false;
+  const target=path.resolve(root,name);if(path.dirname(target)!==root)return false;
+  const rootGuard=await captureStorageDirectory(root);if(!rootGuard)return false;
+  const info=await lstat(target).catch(error=>{if(error.code!=='ENOENT')throw error;});
+  if(!info)return 'missing';if(!info.isDirectory()||info.isSymbolicLink())return false;
+  const targetGuard=await captureStorageDirectory(target);
+  if(!targetGuard||!await verifyStorageDirectories([rootGuard,targetGuard]))return false;
+  // Root and basename were checked immediately before this scoped removal.
+  await rm(target,{recursive:true,force:true,maxRetries:3,retryDelay:50});return 'removed';
+}
+
+/** Caller holds withBuildLock for this canonical root. No age-only deletion. */
+export async function reclaimBuildStages(root,{now=Date.now(),graceMs=3600000,maxEntries=MAX_PAGE,maxListingEntries=MAX_JOURNAL_NAMES}={}){
+  const report={scanned:0,listed:0,removedStages:0,removedBackups:0,retainedRecoveryBackups:0,scanComplete:true,deferred:false};
+  const pageSize=Number.isSafeInteger(maxEntries)&&maxEntries>0?Math.min(maxEntries,MAX_PAGE):MAX_PAGE;
+  const listingLimit=Number.isSafeInteger(maxListingEntries)&&maxListingEntries>0?Math.min(maxListingEntries,MAX_JOURNAL_NAMES):MAX_JOURNAL_NAMES;
+  try{
+    root=path.resolve(root);const rootGuard=await captureStorageDirectory(root);
+    if(!rootGuard)return {...report,scanComplete:false,deferred:true,reason:'The build recovery root changed.'};
+    const directory=await container(root);
+    const guards=[rootGuard,await captureStorageDirectory(directory)];
+    if(!await verifyStorageDirectories(guards))return {...report,scanComplete:false,deferred:true,reason:'The build recovery directory changed.'};
+    const cursorFile=path.join(directory,'cursor.json');
+    const cursorInfo=await lstat(cursorFile).catch(error=>{if(error.code!=='ENOENT')throw error;});
+    if(cursorInfo&&(!cursorInfo.isFile()||cursorInfo.isSymbolicLink()))return {...report,scanComplete:false,deferred:true,reason:'The build recovery cursor is not an ordinary file.'};
+    const saved=await readValue(cursorFile);
+    const after=saved?.version===1&&typeof saved.after==='string'&&recordName.test(saved.after)?saved.after:null;
+    const names=[];
+    for await(const entry of await opendir(directory)){
+      if(report.listed>=listingLimit)return {...report,scanComplete:false,deferred:true,reason:'The build recovery journal listing limit was reached; no stages were removed.'};
+      report.listed++;
+      if(recordName.test(entry.name))names.push(entry.name);
+    }
+    names.sort();
+    let start=after?names.findIndex(name=>name>after):0;if(start<0)start=0;
+    const page=names.slice(start,start+pageSize);
+    report.scanComplete=start+page.length>=names.length;
+    report.deferred=!report.scanComplete;
+    if(report.deferred)report.reason='More build recovery journals remain; the next build resumes this scan.';
+    for(const name of page){
+      if(!await verifyStorageDirectories(guards))return {...report,scanComplete:false,deferred:true,reason:'The build recovery directory changed.'};
+      report.scanned++;
+      const file=path.join(directory,name),owner=await read(file);
+      if(!owner||owner.host!==hostname()||alive(owner.pid)||now-owner.createdAt<graceMs)continue;
+      let stageGone=false,backupGone=false;
+      try{stageGone=await remove(root,owner.stage,stageName);if(stageGone==='removed')report.removedStages++;}catch{}
+      if(owner.committed){try{backupGone=await remove(root,owner.backup,backupName);if(backupGone==='removed')report.removedBackups++;}catch{}}
+      else{
+        const backup=await lstat(path.join(root,owner.backup)).catch(()=>null);
+        backupGone=!backup;if(backup)report.retainedRecoveryBackups++;
+      }
+      if(stageGone&&backupGone&&await verifyStorageDirectories(guards))await unlink(file).catch(()=>{});
+    }
+    if(!await verifyStorageDirectories(guards))return {...report,scanComplete:false,deferred:true,reason:'The build recovery directory changed.'};
+    // The caller owns the publisher lock, so a single persistent cursor advances
+    // across fresh CLI processes without renaming any live owner's journals.
+    await save(cursorFile,{version:1,after:report.scanComplete?null:page.at(-1)||null});
+  }catch{report.scanComplete=false;report.deferred=true;report.reason='Build recovery maintenance is unavailable; retry on a later build.';}
+  return report;
+}
+
+export async function trackBuildStage(root,{stage,backup}){
+  root=path.resolve(root);const rootGuard=await captureStorageDirectory(root);
+  if(!rootGuard)throw Error('Build recovery root must be a canonical physical directory.');
+  const value={version:1,pid:process.pid,host:hostname(),createdAt:Date.now(),stage:path.basename(stage),backup:path.basename(backup),committed:false};
+  if(!stageName.test(value.stage)||!backupName.test(value.backup)||!sameStoragePath(await realpath(path.dirname(path.resolve(stage))),root)||!sameStoragePath(await realpath(path.dirname(path.resolve(backup))),root))throw Error('Build recovery paths must be owned stages inside the project.');
+  const file=path.join(await container(root),randomUUID()+'.json');
+  const guards=[rootGuard,await captureStorageDirectory(path.dirname(file))];
+  if(!await verifyStorageDirectories(guards))throw Error('Build recovery directory changed before publication.');
+  await save(file,value);
+  return {
+    async committed(){value.committed=true;if(await verifyStorageDirectories(guards))await save(file,value);},
+    async cleanup(){
+      try{
+        const stageGone=await remove(root,value.stage,stageName);
+        // An uncommitted backup is kept until rollback has restored it.
+        const backupGone=value.committed?await remove(root,value.backup,backupName):!await lstat(path.join(root,value.backup)).catch(()=>null);
+        if(stageGone&&backupGone&&await verifyStorageDirectories(guards))await unlink(file);
+      }catch{/* Keep the journal so a later build can retry Windows busy files. */}
+    },
+  };
+}

package/build/build-timings.mjs

@@ -0,0 +1,38 @@
+import {AsyncLocalStorage} from 'node:async_hooks';
+
+const storage = new AsyncLocalStorage();
+const names = new Set(['configuration', 'discovery', 'runtime-inputs', 'pages-server', 'pages-browser', 'pages-output', 'middleware', 'metadata', 'app', 'instrumentation', 'types', 'runtime-bundle', 'prerender', 'native-ppr', 'retention', 'precompression', 'analysis', 'standalone', 'compiler-node', 'compiler-browser', 'compiler-edge']);
+
+/** Wall times include awaited native/compiler work; nested phases are not additive. */
+export async function withBuildTimings(run, clock = () => performance.now()) {
+  const state = {clock, started: clock(), phases: new Map()};
+  return storage.run(state, async () => {
+    try { return {result: await run(), timings: report(state)}; }
+    catch (error) {
+      // Diagnostics must never replace the original application/build failure.
+      try { if (error && typeof error === 'object') Object.defineProperty(error, 'buildTimings', {value: report(state), configurable: true}); } catch {}
+      throw error;
+    }
+  });
+}
+
+export async function measureBuildPhase(name, run) {
+  if (!names.has(name)) throw new TypeError('Unknown build timing phase');
+  const state = storage.getStore();
+  if (!state) return run();
+  const started = state.clock();
+  let failed = false;
+  try { return await run(); }
+  catch (error) { failed = true; throw error; }
+  finally {
+    const row = state.phases.get(name) || {calls: 0, failedCalls: 0, milliseconds: 0};
+    row.calls++; row.failedCalls += Number(failed); row.milliseconds += Math.max(0, state.clock() - started);
+    state.phases.set(name, row);
+  }
+}
+
+function report(state) {
+  return {version: 1, scope: 'build-wall-time-excluding-module-startup', nestedPhasesAreAdditive: false,
+    totalMilliseconds: Math.max(0, state.clock() - state.started),
+    phases: Object.fromEntries([...state.phases].map(([name, value]) => [name, {...value}]))};
+}

package/build/bundle-runtime.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {version as esbuildVersion} from 'esbuild';
 import {privateCacheDirectory,readCacheRecord,writeCacheRecord} from './persistent-cache.mjs';
+import {mapConcurrent} from './concurrent.mjs';
 
 // Paths used by the native worker, generated application modules, prerender,
 // standalone tracing, compatibility modules and the runtime lifecycle contract.
@@ -15,7 +16,7 @@ export const runtimeEntryNames = Object.freeze([
 ].sort());
 
 /** Run once, after compiling application/Edge graphs and before any prerender. */
-export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
+export async function bundleRuntime(stage,{projectRoot,sourceDirectory,imageResponse=true}={}) {
   const resolvedStage = path.resolve(stage);
   if (!path.basename(resolvedStage).startsWith('.prnext-build-')) {
     throw new Error('Runtime bundling requires an unpublished PRNext build stage.');
@@ -35,24 +36,24 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
   if (originals.some(entry => !entry.isFile() || entry.isSymbolicLink())) {
     throw new Error('Runtime source modules must be ordinary files.');
   }
-  for (const name of runtimeEntryNames) {
+  const selectedEntries = imageResponse ? runtimeEntryNames : runtimeEntryNames.filter(name => name !== 'og-loader');
+  for (const name of selectedEntries) {
     if (!originals.some(entry => entry.name === `${name}.mjs`)) throw new Error(`Missing runtime entry ${name}.mjs`);
   }
-  const sources=new Map();
   // Production compiles the installed sources directly. Only generated stage
   // overrides (currently the bundled env loader) replace an installed module.
   // Hash and compile the same captured bytes; do not trust mtimes or skip app
   // graph callbacks. This avoids copying hundreds of modules into every stage.
-  for(const entry of originals){
+  const sources=new Map(await mapConcurrent(originals,async entry=>{
     let file=path.join(input,entry.name);
     if(sourceDirectory){const override=path.join(runtime,entry.name);const info=await lstat(override).catch(e=>{if(e.code!=='ENOENT')throw e;});if(info){if(!info.isFile()||info.isSymbolicLink())throw Error('Runtime overrides must be ordinary files');file=override;}}
-    sources.set(path.join(input,entry.name),await readFile(file));
-  }
+    return [path.join(input,entry.name),await readFile(file)];
+  },8));
   let directory,key,cached;
   if(projectRoot){
     directory=await privateCacheDirectory(projectRoot,'runtime-bundle-v2');
     if(directory){
-      const hash=createHash('sha256').update(esbuildVersion).update(JSON.stringify(runtimeEntryNames)).update(await readFile(new URL('./bundle-runtime.mjs',import.meta.url)));
+      const hash=createHash('sha256').update(esbuildVersion).update(JSON.stringify(selectedEntries)).update(await readFile(new URL('./bundle-runtime.mjs',import.meta.url)));
       for(const entry of [...originals].sort((a,b)=>a.name.localeCompare(b.name)))hash.update(JSON.stringify([entry.name,createHash('sha256').update(sources.get(path.join(input,entry.name))).digest('hex')]));
       key=hash.digest('hex');cached=await readCacheRecord(directory,key);
     }
@@ -61,10 +62,10 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
   // no files change if parsing or resolution fails. The virtual output is a
   // sibling so all relative paths have the same depth as the final runtime.
   const virtualOutput = path.join(resolvedStage, '.runtime-bundle');
-  const validCache=cached&&Array.isArray(cached.files)&&cached.files.length<=128&&cached.files.every(item=>Array.isArray(item)&&item.length===2&&/^[\w-]+\.mjs$/.test(item[0])&&typeof item[1]==='string')&&new Set(cached.files.map(([name])=>name)).size===cached.files.length&&runtimeEntryNames.every(name=>cached.files.some(([file])=>file===name+'.mjs'));
+  const validCache=cached&&Array.isArray(cached.files)&&cached.files.length<=128&&cached.files.every(item=>Array.isArray(item)&&item.length===2&&/^[\w-]+\.mjs$/.test(item[0])&&typeof item[1]==='string')&&new Set(cached.files.map(([name])=>name)).size===cached.files.length&&selectedEntries.every(name=>cached.files.some(([file])=>file===name+'.mjs'))&& (imageResponse || !cached.files.some(([file])=>file==='og-loader.mjs'));
   const result = validCache?null:await build({
     absWorkingDir: input,
-    entryPoints: runtimeEntryNames.map(name => path.join(input, `${name}.mjs`)),
+    entryPoints: selectedEntries.map(name => path.join(input, `${name}.mjs`)),
     outdir: virtualOutput,
     outbase: input,
     entryNames: '[name]',
@@ -78,7 +79,7 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
     packages: 'external',
     // Edge's prepared VM is already a self-contained CJS artifact. Keeping it
     // external preserves its delayed import and original execution boundary.
-    external: ['../compat/*', './profiles.json', './*.cjs'],
+    external: ['../compat/*', './profiles.json', './*.cjs', './og/*'],
     minify: false,
     sourcemap: false,
     metafile: true,
@@ -94,17 +95,17 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
     }
     emitted.set(path.basename(file.path), file.contents);
   }
-  if (runtimeEntryNames.some(name => !emitted.has(`${name}.mjs`))) throw new Error('Runtime bundle omitted a required entry.');
+  if (selectedEntries.some(name => !emitted.has(`${name}.mjs`))) throw new Error('Runtime bundle omitted a required entry.');
   if(directory&&!validCache)await writeCacheRecord(directory,key,{files:[...emitted].map(([name,bytes])=>[name,Buffer.from(bytes).toString()])});
   // This is an unpublished, disposable stage. On any write failure buildProject
   // discards the stage and preserves the previous published build unchanged.
-  for (const [name, contents] of emitted) await writeFile(path.join(runtime, name), contents);
-  for (const entry of await readdir(runtime,{withFileTypes:true})) {
-    if(!entry.name.endsWith('.mjs')||!entry.isFile())continue;
+  await mapConcurrent(emitted,async([name,contents])=>writeFile(path.join(runtime,name),contents),8);
+  await mapConcurrent(await readdir(runtime,{withFileTypes:true}),async entry=>{
+    if(!entry.name.endsWith('.mjs')||!entry.isFile())return;
     if (!emitted.has(entry.name)) await unlink(path.join(runtime, entry.name));
-  }
+  },8);
   // JSON, CJS, license files and the OG assets directory are never traversed or
   // removed. The caller writes the normal runtime contract after prerender.
-  return { entryCount: runtimeEntryNames.length, moduleCount: emitted.size,cached:!!validCache,
+  return { entryCount: selectedEntries.length, moduleCount: emitted.size,cached:!!validCache,
     bytes: [...emitted.values()].reduce((sum, contents) => sum + contents.length, 0) };
 }

package/build/cache-command.mjs

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import {inspectCompilationStorage,pruneCompilationStorage,validateCompilationCache} from './compilation-storage.mjs';
+
+export async function cacheCommand(args){
+  if(args.length===1&&['--help','-h'].includes(args[0])){
+    console.log('prnext cache [directory] [--json]\nprnext cache [directory] --prune [--dry-run] [--max-bytes N] [--json]\n\nInspect compiler caches without executing application config. The budget comes\nfrom the last build (default 256 MiB). --max-bytes overrides this purge only.\nRuntime data, SQLite, page/image caches and application files are excluded.\nStop development before purging. Active worker caches remain pinned.');return;
+  }
+  let directory,prune=false,dryRun=false,json=false,maxDiskSize;
+  const seen=new Set();
+  for(let i=0;i<args.length;i++){
+    const arg=args[i];
+    if(arg.startsWith('--')){if(seen.has(arg))throw Error(`Duplicate cache option: ${arg}`);seen.add(arg);}
+    if(arg==='--prune')prune=true;
+    else if(arg==='--dry-run')dryRun=true;
+    else if(arg==='--json')json=true;
+    else if(arg==='--max-bytes'){
+      const value=args[++i];if(!/^\d+$/.test(value||''))throw Error('--max-bytes requires a byte count from 0 to 4294967296.');
+      maxDiskSize=validateCompilationCache({maxDiskSize:Number(value)}).maxDiskSize;
+    }else if(arg.startsWith('-')||directory!==undefined)throw Error('cache accepts one directory, --prune, --dry-run, --max-bytes N and --json.');
+    else directory=arg;
+  }
+  if((dryRun||maxDiskSize!==undefined)&&!prune)throw Error('--dry-run and --max-bytes require --prune.');
+  const root=path.resolve(directory||'.');
+  const report=prune?await pruneCompilationStorage(root,{maxDiskSize,dryRun}):await inspectCompilationStorage(root);
+  if(json){console.log(JSON.stringify(report,null,2));return;}
+  const size=value=>(value/1024/1024).toFixed(2)+' MiB';
+  console.log(`Compilation caches: ${size(report.bytes)} / ${size(report.maxDiskSize)}`);
+  for(const category of report.categories)console.log(`  ${category.name}: ${size(category.bytes)}, ${category.files} files${category.pinned?' (active worker)':''}`);
+  if(prune)console.log(report.deferred?report.reason:`${dryRun?'Would reclaim':'Reclaimed'} ${size(report.removedBytes)} in ${report.removedFiles} files; ${size(report.afterBytes)} retained.${report.overBudget?' Active or busy files remain above the budget.':''}`);
+  else if(!report.scanComplete)console.log('The scan limit was reached; totals are a lower bound.');
+}