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

package/build/create.mjs

@@ -0,0 +1,239 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, readdir, realpath, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { packageManifest } from '../native/resolve.mjs';
+import { supportedNode } from '../native/diagnostics.mjs';
+import { npmCommand } from '../native/npm.mjs';
+
+export const createHelp = `Usage: prnext create <directory> [--js] [--no-install] [--json]
+
+Create a minimal App Router project and install its dependencies with npm.
+TypeScript is the default; --js creates a JavaScript project.
+The directory must be absent or completely empty. Existing files are never replaced.
+--no-install prepares files without running npm or accessing the network.
+Inside an existing workspace, use --no-install and its own package manager.
+
+  npx @thomas.f/prnext create my-app
+  cd my-app
+  npm run dev
+`;
+
+export function parseCreateArgs(args, cwd = process.cwd()) {
+  const flags = new Set(), positional = [];
+  let literal = false;
+  for (const arg of args) {
+    if (literal) positional.push(arg);
+    else if (arg === '--') literal = true;
+    else if (['--no-install', '--js', '--json'].includes(arg)) {
+      if (flags.has(arg)) throw new Error(`Duplicate create option: ${arg}`);
+      flags.add(arg);
+    } else if (arg.startsWith('-')) throw new Error(`Unknown create option: ${arg}`);
+    else positional.push(arg);
+  }
+  if (positional.length !== 1 || !positional[0].trim() || /[\0\r\n]/.test(positional[0])) throw new Error('Provide one project directory: prnext create my-app');
+  return { directory: path.resolve(cwd, positional[0]), options: { install: !flags.has('--no-install'), typescript: !flags.has('--js'), json: flags.has('--json') } };
+}
+
+const samePath = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino;
+async function info(file, options) {
+  try { return await lstat(file, options); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+async function physicalDirectory(directory, missing = false) {
+  // macOS exposes standard directories through root-owned /private aliases.
+  // Resolve only those exact system targets; every user-controlled descendant
+  // still goes through the strict no-symlink walk below, on every write.
+  if (process.platform === 'darwin') {
+    const alias = /^\/(?:var|tmp|etc)(?=\/|$)/.exec(directory)?.[0];
+    if (alias && (await info(alias))?.isSymbolicLink() && await realpath(alias) === `/private${alias}`) {
+      directory = `/private${directory}`;
+    }
+  }
+  const root = path.parse(directory).root;
+  const inspected = [];
+  let current = root;
+  for (const part of path.relative(root, directory).split(path.sep).filter(Boolean)) {
+    if (process.platform === 'win32' && (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part) || /[<>:"|?*]|[. ]$/.test(part))) throw new Error(`Invalid Windows directory name: ${part}`);
+    current = path.join(current, part);
+    const entry = await info(current, { bigint: true });
+    if (!entry && missing) continue;
+    if (!entry?.isDirectory() || entry.isSymbolicLink()) throw new Error(`Project directories must not be files, symbolic links or junctions: ${current}`);
+    inspected.push([current, entry]);
+  }
+  if (!missing) {
+    const canonical = await realpath(directory);
+    if (!samePath(canonical, directory)) {
+      if (process.platform !== 'win32') throw new Error('Use a physical project directory without symbolic links or junctions.');
+      // DOS 8.3 names are directory aliases, not reparse points. Accept the
+      // expanded name only after rechecking every observed directory identity
+      // and proving that the canonical target is the same physical directory.
+      for (const [file, original] of inspected) {
+        const observed = await info(file, { bigint: true });
+        if (!observed?.isDirectory() || observed.isSymbolicLink() || !sameFile(original, observed)) throw new Error(`Project directory changed during creation: ${file}`);
+      }
+      const original = inspected.at(-1)?.[1] || await info(directory, { bigint: true });
+      const resolved = await info(canonical, { bigint: true });
+      if (!original?.isDirectory() || original.isSymbolicLink() || original.ino === 0n || !resolved?.isDirectory() || resolved.isSymbolicLink() || !sameFile(original, resolved)) throw new Error('Use a physical project directory without symbolic links or junctions.');
+    }
+  }
+}
+
+async function parentWorkspace(directory) {
+  for (let current = path.dirname(directory); ; current = path.dirname(current)) {
+    const workspace = await info(path.join(current, 'pnpm-workspace.yaml'));
+    if (workspace) return current;
+    const file = path.join(current, 'package.json'), entry = await info(file);
+    if (entry) {
+      if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 1024 * 1024) throw new Error(`Cannot safely inspect parent package.json: ${file}`);
+      let manifest;
+      try { manifest = JSON.parse((await readFile(file, 'utf8')).replace(/^\uFEFF/, '')); }
+      catch { throw new Error(`Parent package.json is invalid: ${file}`); }
+      if (manifest.workspaces) return current;
+    }
+    if (current === path.dirname(current)) return null;
+  }
+}
+
+function projectName(directory) {
+  const name = path.basename(directory).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[._-]+|[._-]+$/g, '').slice(0, 100);
+  return !name || ['node_modules', 'favicon.ico'].includes(name) ? 'prnext-app' : name;
+}
+const json = value => JSON.stringify(value, null, 2) + '\n';
+
+function projectFiles(name, typescript) {
+  const extension = typescript ? 'tsx' : 'jsx';
+  const scripts = { dev: 'prnext dev', build: 'prnext build', start: 'prnext start', check: 'prnext check', ...(typescript ? { typecheck: 'prnext typecheck' } : {}) };
+  const manifest = { name, version: '0.0.0', private: true, type: 'module', scripts,
+    dependencies: { [packageManifest.name]: packageManifest.version, ...Object.fromEntries(Object.entries(packageManifest.peerDependencies).filter(([name])=>!packageManifest.peerDependenciesMeta?.[name]?.optional)) },
+    ...(typescript ? { devDependencies: { typescript: '^5.9.0', '@types/node': '^22.0.0', '@types/react': '^19.0.0', '@types/react-dom': '^19.0.0' } } : {}),
+    engines: { node: packageManifest.engines.node } };
+  const files = new Map([
+    ['package.json', json(manifest)],
+    [`app/layout.${extension}`, `import './globals.css';\n${typescript ? "import type { ReactNode } from 'react';\n" : ''}
+export const metadata = { title: 'My PRNext app', description: 'A React application built with PRNext.' };
+
+export default function RootLayout({ children }${typescript ? ': { children: ReactNode }' : ''}) {
+  return <html lang="en"><body>{children}</body></html>;
+}
+`],
+    [`app/page.${extension}`, `export default function Home() {
+  return <main><h1>PRNext</h1><p>Edit <code>app/page.${extension}</code> to get started.</p></main>;
+}
+`],
+    ['app/globals.css', `:root { color-scheme: dark; font-family: system-ui, sans-serif; background: #0a0a0a; color: #ededed; }
+* { box-sizing: border-box; }
+body { margin: 0; }
+main { max-width: 64rem; margin: auto; padding: clamp(2rem, 8vw, 6rem) 1.5rem; }
+h1 { font-size: clamp(2.5rem, 8vw, 4rem); letter-spacing: -.04em; }
+p { line-height: 1.6; }
+code { font-size: .95em; }
+`],
+    ['.gitignore', 'node_modules/\n.prnext/\n.prnext-types/\n.prnext-dev/\n.prnext-cache/\n.env*\n!.env.example\n*.tsbuildinfo\n'],
+    ['README.md', `# ${name}\n\nA minimal PRNext application.\n\nRun \`npm install\` if dependencies have not been installed, then:\n\n\`\`\`sh\nnpm run dev\n\`\`\`\n\nEdit \`app/page.${extension}\`. Use the local URL printed by the server.\n\n\`\`\`sh\nnpm run check\n${typescript ? 'npm run typecheck\n' : ''}npm run build\nnpm start\n\`\`\`\n\nUse another port with \`npm run dev -- --port 3001\` when needed.\n\n[PRNext documentation](https://prnext.dev) · Installed AI guide: \`npx --no-install prnext docs --ai\`.\nPRNext is experimental; Next.js compatibility is partial.\n`],
+    ['AGENTS.md', `# PRNext project\n\nThis application uses \`@thomas.f/prnext\`. Before changing routing, configuration, data fetching or deployment, read the installed guide at \`node_modules/@thomas.f/prnext/AI.md\` or run:\n\n\`\`\`sh\nnpx --no-install prnext docs --ai\nnpx --no-install prnext docs --ai --list\n\`\`\`\n\nRead only the relevant topic with \`npx --no-install prnext docs --ai <topic>\`. The installed documentation is version-specific; do not assume full Next.js compatibility. Preserve the project's package manager and lockfile.\n`],
+  ]);
+  if (typescript) files.set('tsconfig.json', json({ compilerOptions: { target: 'ES2022', lib: ['DOM', 'DOM.Iterable', 'ES2022'], module: 'ESNext', moduleResolution: 'Bundler', jsx: 'preserve', strict: true, noEmit: true, esModuleInterop: true, skipLibCheck: true }, include: ['**/*.ts', '**/*.tsx'], exclude: ['node_modules', '.prnext', '.prnext-dev', '.prnext-cache'] }));
+  return files;
+}
+
+function abortError() { const error = new Error('Project creation canceled.'); error.name = 'AbortError'; return error; }
+function aborted(signal) { if (signal?.aborted) throw abortError(); }
+
+/** Run npm without a shell; a canceled command waits for its own installer tree. */
+export async function installProject(directory, { signal, onOutput = () => {} } = {}) {
+  aborted(signal);
+  // npm resolves its working directory physically. Keep its environment on
+  // that same path so macOS aliases cannot split the lock tree.
+  directory = await realpath(directory);
+  aborted(signal);
+  const env = { ...process.env, INIT_CWD: directory, PWD: directory };
+  for (const key of Object.keys(env)) if (/^npm_config_(?:workspace|workspaces|global|prefix)$/i.test(key)) delete env[key];
+  const npm = npmCommand(env);
+  await new Promise((resolve, reject) => {
+    // The generated package.json already anchors npm's local project here.
+    // npm 10 on Windows treats an explicit --prefix as its global top and can
+    // add the project to its own dependencies even with --global=false.
+    const child = spawn(npm.command, [...npm.args, 'install', '--workspaces=false', '--global=false'], { cwd: directory, env, windowsHide: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+    let tail = '', timer, canceling = false;
+    const receive = stream => chunk => { tail = (tail + chunk).slice(-16000); onOutput(String(chunk), stream); };
+    child.stdout.on('data', receive('stdout'));
+    child.stderr.on('data', receive('stderr'));
+    function terminate(force) {
+      if (!child.pid) return;
+      if (process.platform === 'win32') {
+        if (child.exitCode !== null || child.signalCode) return;
+        const executable = path.join(env.SystemRoot || 'C:\\Windows', 'System32', 'taskkill.exe');
+        const killer = spawn(executable, ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+        killer.on('error', () => child.kill());
+      } else {
+        try { process.kill(-child.pid, force ? 'SIGKILL' : 'SIGTERM'); } catch (error) { if (error.code !== 'ESRCH') child.kill(force ? 'SIGKILL' : 'SIGTERM'); }
+      }
+    }
+    function cancel() { canceling = true; terminate(false); timer ||= setTimeout(() => terminate(true), 5000); }
+    function cleanup() { clearTimeout(timer); signal?.removeEventListener('abort', cancel); }
+    child.once('error', error => { cleanup(); reject(error); });
+    child.once('close', (code, childSignal) => {
+      // A detached lifecycle script can close npm's pipes before it exits.
+      // Do not let npm's exit cancel escalation for that remaining group.
+      if ((canceling || signal?.aborted) && process.platform !== 'win32') terminate(true);
+      cleanup();
+      if (canceling || signal?.aborted) reject(abortError());
+      else if (code === 0) resolve();
+      else reject(new Error(`npm install failed (${childSignal || code}).${tail.trim() ? '\n' + tail.trim() : ''}`));
+    });
+    signal?.addEventListener('abort', cancel, { once: true });
+    if (signal?.aborted) cancel();
+  });
+}
+
+export async function createProject(directory, options = {}, services = {}) {
+  const root = path.resolve(directory), typescript = options.typescript !== false, install = options.install !== false;
+  aborted(options.signal);
+  const nodeVersion = services.nodeVersion || process.version;
+  if (!supportedNode(nodeVersion)) throw new Error(`Node ${nodeVersion} is unsupported. Use Node ${packageManifest.engines.node}.`);
+  await physicalDirectory(root, true);
+  const existing = await info(root);
+  if (existing && (await readdir(root)).length) throw new Error(`Project directory must be empty; no files were changed: ${root}`);
+  if (install && await parentWorkspace(root)) throw new Error('Automatic installation inside an existing workspace is not supported. Use --no-install, then add the project with the workspace package manager. No files were changed.');
+  aborted(options.signal);
+  await mkdir(root, { recursive: true });
+  await physicalDirectory(root);
+  const lockPath = path.join(root, '.prnext-create.lock');
+  const lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW || 0), 0o600);
+  const locked = await lock.stat();
+  try {
+    if ((await readdir(root)).some(name => name !== '.prnext-create.lock')) throw new Error(`Project directory is no longer empty; existing files were preserved: ${root}`);
+    const name = projectName(root), files = projectFiles(name, typescript);
+    for (const [relative, content] of files) {
+      aborted(options.signal);
+      await physicalDirectory(root);
+      const target = path.join(root, relative), parent = path.dirname(target);
+      await physicalDirectory(parent, true);
+      await mkdir(parent, { recursive: true });
+      await physicalDirectory(parent);
+      const file = await open(target, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW || 0), 0o644);
+      try { await file.writeFile(content, 'utf8'); } finally { await file.close(); }
+    }
+    const report = { ok: true, status: 'prepared', root, name, typescript, files: [...files.keys()], installed: false, next: install ? ['npm run dev'] : ['npm install', 'npm run dev'] };
+    if (install) {
+      try {
+        aborted(options.signal);
+        await (services.runInstall || installProject)(root, { signal: options.signal, onOutput: options.onOutput });
+        aborted(options.signal);
+        report.installed = true;
+        report.status = 'created';
+      } catch (error) {
+        report.ok = false;
+        report.status = error.name === 'AbortError' || options.signal?.aborted ? 'cancelled' : 'install-failed';
+        report.error = error.message;
+        report.next = ['npm install', 'npm run dev'];
+      }
+    }
+    return report;
+  } finally {
+    await lock.close();
+    const current = await info(lockPath);
+    if (current?.isFile() && !current.isSymbolicLink() && sameFile(current, locked)) await unlink(lockPath);
+  }
+}

package/build/css-modules.mjs

@@ -1,13 +1,15 @@
 import { build as bundle } from 'esbuild';
-import { mkdir, writeFile, realpath } from 'node:fs/promises';
+import { mkdir, writeFile, realpath, readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { runInNewContext } from 'node:vm';
 import { createRequire } from 'node:module';
-import { createStyleProcessor, stylesheetPattern, moduleStylesheetPattern } from './styles.mjs';
+import { createStyleProcessor, resolveStandardBrowserTargets, stylesheetPattern, moduleStylesheetPattern } from './styles.mjs';
 import {rename} from '../runtime/fs.mjs';
 import {randomUUID} from 'node:crypto';
 import {rm} from 'node:fs/promises';
+import {cachedCompilation} from './compilation-cache.mjs';
+import {compactCssModule,globalCssNames} from './compact-css.mjs';
 
 const assetLoaders = Object.fromEntries(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg', '.ico', '.woff', '.woff2', '.ttf', '.eot'].map(ext => [ext, 'file']));
 
@@ -23,13 +25,34 @@ async function resolveCss(esbuild, args) {
 }
 
 /** One cached CSS compilation supplies identical class maps to the server and the browser. */
-export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/assets', sassOptions, cssEngine }) {
-  const cache = new Map();
-  const processor = createStyleProcessor({ projectRoot, sassOptions, cssEngine });
+export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/assets', sassOptions, cssEngine, dev = false, config = {} }) {
+  const cache = new Map(), compactNames = new Map();
+  let targets;
+  const browserTargets=()=>targets ??= Promise.resolve().then(()=>resolveStandardBrowserTargets(projectRoot));
+  const processor = createStyleProcessor({ projectRoot, sassOptions, cssEngine, browserTargets });
   const hash = file => createHash('sha256').update(path.relative(projectRoot, file).replaceAll(path.sep, '/')).digest('hex').slice(0, 12);
+  let eligibility;
+  async function cacheEligible() {
+    if (dev || cssEngine==='postcss' || config.webpack || Object.keys(config.turbopack?.rules || {}).length || process.env.BROWSERSLIST_CONFIG || process.env.BROWSERSLIST_STATS || /\b(?:extends|stats)\b/i.test(process.env.BROWSERSLIST || '')) return false;
+    // A user PostCSS plugin can read arbitrary files, glob directories or use
+    // network/time without declaring dependencies. Its output is never cached.
+    const names = await readdir(projectRoot);
+    if (names.some(name => /^(?:postcss\.config|\.postcssrc)(?:\.|$)/.test(name))) return false;
+    try { if (JSON.parse(await readFile(path.join(projectRoot, 'package.json'), 'utf8')).postcss !== undefined) return false; }
+    catch (error) { if (error.code !== 'ENOENT') return false; }
+    return true;
+  }
+  const validMapping = value => {try{const parsed=JSON.parse(value);return parsed&&typeof parsed==='object'&&!Array.isArray(parsed)&&Object.values(parsed).every(value=>typeof value==='string');}catch{return false;}};
+  const validResult = value => value && typeof value.mapping === 'string' && value.mapping.length <= 16*1024*1024 && validMapping(value.mapping) && typeof value.css === 'string' && value.css.length <= 16*1024*1024
+    && Array.isArray(value.compactNames) && value.compactNames.length <= 65536 && value.compactNames.every(item=>Array.isArray(item)&&item.length===2&&typeof item[0]==='string'&&item[0].length<=4096&&typeof item[1]==='string'&&/^p[\w-]{10}$/.test(item[1]))
+    && Array.isArray(value.watchFiles) && value.watchFiles.length <= 4096 && value.watchFiles.every(file => typeof file==='string' && path.isAbsolute(file) && !file.includes('\0') && !/\.s[ac]ss$/i.test(file))
+    && Array.isArray(value.assets) && value.assets.length <= 4096 && value.assets.every(asset => asset && typeof asset.name === 'string'
+      && asset.name && asset.name === path.basename(asset.name) && !/[\\/\0<>:"|?*#]/.test(asset.name) && asset.name !== '.' && asset.name !== '..'
+      && typeof asset.data === 'string' && asset.data.length<=24*1024*1024 && asset.data.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(asset.data))
+    && new Set(value.assets.map(asset=>asset.name)).size===value.assets.length && value.assets.reduce((sum,asset)=>sum+asset.data.length,0)<=48*1024*1024;
 
   async function compile(file) {
-    const dependencies=new Set([file]);
+    const dependencies=new Set([file]), globals = new Set();
     const result = await bundle({
       absWorkingDir: projectRoot,
       stdin: { contents: `import styles from ${JSON.stringify(file)}; export default styles;`, resolveDir: projectRoot, loader: 'js' },
@@ -57,11 +80,13 @@ export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/ass
           });
           esbuild.onLoad({ filter: /.*/, namespace: 'prnext-local-css' }, async args => {
             const transformed = await processor.process(args.pluginData.source);
+            if (!dev) globalCssNames(transformed.css, {local:true}, globals);
             for(const file of transformed.watchFiles)dependencies.add(file);
             return { contents: transformed.css, loader: 'local-css', resolveDir: path.dirname(args.pluginData.source), watchFiles: transformed.watchFiles };
           });
           esbuild.onLoad({ filter: stylesheetPattern, namespace: 'file' }, async args => {
             const transformed = await processor.process(args.path);
+            if (!dev) globalCssNames(transformed.css, {local:false}, globals);
             for(const file of transformed.watchFiles)dependencies.add(file);
             return { contents: transformed.css, loader: 'css', resolveDir: path.dirname(args.path), watchFiles: transformed.watchFiles };
           });
@@ -77,18 +102,37 @@ export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/ass
     // The isolated context deliberately has no require, process, network, or filesystem.
     const module = { exports: {} };
     runInNewContext(javascript.text, { module }, { timeout: 1000, filename: 'prnext-css-exports.cjs' });
-    const mapping = JSON.stringify({ ...module.exports.default, ...(await processor.process(file)).exports });
-    await mkdir(path.join(stage, 'assets'), { recursive: true });
+    const compact = dev ? {mapping:module.exports.default,css:stylesheet.text,names:[]} : compactCssModule(stylesheet.text,module.exports.default,{globals});
+    const mapping = JSON.stringify({ ...compact.mapping, ...(await processor.process(file)).exports });
+    const assets = [];
     for (const output of result.outputFiles) {
       if (output === javascript || output === stylesheet) continue;
-      const target=path.join(stage,'assets',path.basename(output.path)),temporary=target+'.'+randomUUID()+'.tmp';
-      try{await writeFile(temporary,output.contents);await rename(temporary,target);}finally{await rm(temporary,{force:true});}
+      assets.push({name:path.basename(output.path),data:Buffer.from(output.contents).toString('base64')});
     }
-    return { mapping, css: stylesheet.text,watchFiles:[...dependencies] };
+    return { mapping, css: compact.css,compactNames:compact.names,watchFiles:[...dependencies],assets };
   }
 
   function get(file) {
-    if (!cache.has(file)) cache.set(file, compile(file));
+    if (!cache.has(file)) cache.set(file, (async () => {
+      eligibility ??= cacheEligible();
+      const enabled = await eligibility && /\.css$/i.test(file);
+      const result = await cachedCompilation({root:projectRoot,kind:'css-modules',inputs:[file],excluded:[path.resolve(projectRoot,config.distDir || '.prnext'),...(config.output==='export'?[path.join(projectRoot,'out')]:[])],styleTargets:true,settings:{file,assetBase,cssEngine:cssEngine || 'auto',...(enabled?{browserTargets:await browserTargets()}:{})},
+        enabled,reason:dev?'development':'custom-style-pipeline',validate:validResult,
+        bytes:value=>Buffer.byteLength(value.mapping)+Buffer.byteLength(value.css)+Buffer.byteLength(JSON.stringify(value.compactNames))+value.assets.reduce((sum,asset)=>sum+Buffer.byteLength(asset.data,'base64'),0),
+        produce:async()=>{const value=await compile(file);return {value,dependencies:value.watchFiles};}});
+      await mkdir(path.join(stage,'assets'),{recursive:true});
+      for(const [original,short] of result.compactNames || []) {
+        if(compactNames.has(short)&&compactNames.get(short)!==original)throw new Error('CSS Module compact-name collision across modules.');
+        compactNames.set(short,original);
+      }
+      for (const asset of result.assets) {
+        const target=path.join(stage,'assets',asset.name),temporary=target+'.'+randomUUID()+'.tmp';
+        try{await writeFile(temporary,Buffer.from(asset.data,'base64'));await rename(temporary,target);}finally{await rm(temporary,{force:true});}
+      }
+      // Keep the original public result and release replay-only binary payloads.
+      // The per-build mapping cache must not retain a base64 copy of every asset.
+      return {mapping:result.mapping,css:result.css,watchFiles:result.watchFiles};
+    })());
     return cache.get(file);
   }
 

package/build/deployment-assets.mjs

@@ -0,0 +1,89 @@
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const INDEX = 'deployment-assets.json';
+const MAX_FILES = 1024, MAX_BYTES = 64 * 1024 * 1024, MAX_FILE_BYTES = 8 * 1024 * 1024;
+const MAX_AGE = 60 * 60 * 1000, MAX_GENERATIONS = 2;
+// Only build-owned, immutable code/styles. Never JSON, maps, HTML, public/ or server/.
+const safeName = value => typeof value === 'string' && value.length < 240 && /^[a-zA-Z0-9_.-]+-[a-zA-Z0-9]{8,64}\.(?:js|mjs|css|woff2?|ttf|otf|eot|png|jpe?g|avif|webp|gif|svg|ico|wasm)$/.test(value);
+const assetKey = name => process.platform === 'win32' ? name.toLowerCase() : name;
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+async function regular(file, limit) {
+  const info = await lstat(file);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > limit) return;
+  return info;
+}
+async function indexAt(directory) {
+  try {
+    if (!await regular(path.join(directory, INDEX), 1024 * 1024)) return;
+    const value = JSON.parse(await readFile(path.join(directory, INDEX), 'utf8'));
+    if (value.version !== 1 || !Array.isArray(value.generations) || value.generations.length > 6) return;
+    for (const generation of value.generations) {
+      if (typeof generation.id !== 'string' || generation.id.length > 128 || !Number.isSafeInteger(generation.createdAt) || !Array.isArray(generation.files) || generation.files.length > MAX_FILES) return;
+      const seen = new Set();
+      for (const file of generation.files) {
+        if (!safeName(file.name) || seen.has(assetKey(file.name)) || !Number.isSafeInteger(file.bytes) || file.bytes < 0 || file.bytes > MAX_FILE_BYTES || !/^[a-f0-9]{64}$/.test(file.hash)) return;
+        seen.add(assetKey(file.name));
+      }
+    }
+    return value;
+  } catch (error) { if (!['ENOENT', 'ENOTDIR'].includes(error.code)) { /* Corrupt previous metadata is an optional retention miss. */ } }
+}
+
+/** Copy only public immutable assets into a stage, before its atomic publication. */
+export async function retainDeploymentAssets({ stage, destination, manifest, policy, now = Date.now() }) {
+  if (manifest.dev) return { generations: 0, files: 0, bytes: 0 };
+  const maxAge = (policy && policy.maxAge !== undefined ? policy.maxAge * 1000 : MAX_AGE);
+  const maxGenerations = policy && policy.maxGenerations !== undefined ? policy.maxGenerations : MAX_GENERATIONS;
+  const maxBytes = policy && policy.maxBytes !== undefined ? policy.maxBytes : MAX_BYTES;
+  const assets = path.join(stage, 'assets');
+  const assetInfo = await lstat(assets);
+  if (!assetInfo.isDirectory() || assetInfo.isSymbolicLink()) throw new Error('Deployment assets must be a regular directory');
+  const current = { id: manifest.cacheId, createdAt: now, eligible: true, files: [] };
+  let indexedBytes = 0;
+  for (const name of (await readdir(assets)).sort()) {
+    if (!safeName(name)) {
+      // Maps/manifests do not participate in executable chunk graphs. Unknown
+      // content-addressed media and auxiliary directories make retention unsafe.
+      if (/\.(?:map|json|html|txt|gz|br)$/.test(name)) continue;
+      current.eligible = false; current.files = []; break;
+    }
+    const file = path.join(assets, name), info = await regular(file, MAX_FILE_BYTES);
+    if (!info || (indexedBytes += info.size) > 256 * 1024 * 1024) { current.eligible = false; current.files = []; break; }
+    const bytes = await readFile(file);
+    current.files.push({ name, bytes: bytes.length, hash: hash(bytes) });
+    if (current.files.length > MAX_FILES) { current.eligible = false; current.files = []; break; }
+  }
+  const previousRoot = await lstat(path.join(destination, 'assets')).catch(() => null);
+  const previous = !current.eligible || policy === false || !previousRoot?.isDirectory() || previousRoot.isSymbolicLink() ? undefined : await indexAt(destination), generations = [current], known = new Map(current.files.map(file => [assetKey(file.name), file]));
+  const retained = Object.create(null); let bytes = 0, count = 0;
+  for (const generation of previous?.generations || []) {
+    if (generation.eligible !== true || generations.length > maxGenerations || generation.id === current.id || generation.createdAt > now || now - generation.createdAt >= maxAge) continue;
+    if (generation.files.some(file => { const value = known.get(assetKey(file.name)); return value && (value.hash !== file.hash || value.bytes !== file.bytes); })) continue;
+    const candidates = generation.files.filter(file => !known.has(assetKey(file.name)));
+    const size = candidates.reduce((sum, file) => sum + file.bytes, 0);
+    if (bytes + size > maxBytes || count + candidates.length > MAX_FILES) continue;
+    const verified = [];
+    for (const file of candidates) {
+      const source = path.join(destination, 'assets', file.name);
+      try {
+        if (!await regular(source, MAX_FILE_BYTES)) continue;
+        const contents = await readFile(source);
+        if (contents.length !== file.bytes || hash(contents) !== file.hash) continue;
+        verified.push({file, contents});
+      } catch { /* An unreadable previous asset is an optional retention miss. */ }
+    }
+    // An incomplete previous generation cannot promise a working chunk graph.
+    if (verified.length !== candidates.length) continue;
+    for (const {file, contents} of verified) {
+      await writeFile(path.join(assets, file.name), contents, {flag:'wx'});
+      known.set(assetKey(file.name), file); retained[file.name] = generation.createdAt + maxAge;
+      bytes += file.bytes; count++;
+    }
+    generations.push(generation);
+  }
+  manifest.config.retainedAssets = retained;
+  await writeFile(path.join(stage, INDEX), JSON.stringify({ version: 1, generations }) + '\n');
+  return { generations: generations.length - 1, files: count, bytes };
+}

package/build/deployment-config.mjs

@@ -0,0 +1,18 @@
+const defaults=Object.freeze({maxAge:3600,maxGenerations:2,maxBytes:64*1024*1024});
+const limits={maxAge:[1,86400],maxGenerations:[1,5],maxBytes:[1024,256*1024*1024]};
+
+/** Retain only bounded, immutable public assets; false revokes all carry-over. */
+export function validateDeploymentRetention(value){
+  if(value===false)return false;
+  if(value===undefined)return {...defaults};
+  if(!value||typeof value!=='object'||Array.isArray(value)||![Object.prototype,null].includes(Object.getPrototypeOf(value)))throw new TypeError('deploymentRetention must be false or an object.');
+  const output={...defaults};
+  for(const key of Reflect.ownKeys(value)){
+    if(!Object.hasOwn(limits,key))throw new TypeError(`deploymentRetention.${String(key)} is not supported.`);
+    if(value[key]===undefined)continue;
+    const [minimum,maximum]=limits[key];
+    if(!Number.isSafeInteger(value[key])||value[key]<minimum||value[key]>maximum)throw new TypeError(`deploymentRetention.${key} must be an integer from ${minimum} to ${maximum}.`);
+    output[key]=value[key];
+  }
+  return output;
+}

package/build/dev-css-assets.mjs

@@ -0,0 +1,173 @@
+import { copyFile, link, lstat, mkdir, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { rename } from '../runtime/fs.mjs';
+
+export const STYLE_OVERLAY_LIMITS = Object.freeze({ files: 4096, bytes: 64 * 1024 * 1024, catalogueBytes: 4 * 1024 * 1024, references: 16384 });
+const digest = data => createHash('sha256').update(data).digest('hex');
+const filename = name => typeof name === 'string' && name.length > 0 && name.length <= 255 && name !== '.' && name !== '..'
+  && !/[\\/\x00-\x1f<>:"|?*#]/.test(name) && path.basename(name) === name;
+const inside = (root, file) => { const relative = path.relative(root, file); return relative !== '' && !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep); };
+
+export class StyleOverlayFallback extends Error {
+  constructor(code) { super(code); this.code = code; }
+}
+const fallback = code => { throw new StyleOverlayFallback(code); };
+
+function assetsFor(bundles) {
+  const assets = new Map();
+  let references = 0, bytes = 0;
+  for (const files of bundles.values()) for (const file of files) {
+    if (++references > STYLE_OVERLAY_LIMITS.references) fallback('style-overlay-budget');
+    if (!file || !filename(file.name) || !Number.isSafeInteger(file.bytes) || file.bytes < 0 || file.bytes > STYLE_OVERLAY_LIMITS.bytes || !/^[a-f0-9]{64}$/.test(file.sha256)) fallback('invalid-style-overlay');
+    const previous = assets.get(file.name);
+    if (previous && (previous.bytes !== file.bytes || previous.sha256 !== file.sha256)) fallback('conflicting-style-overlay');
+    if (!previous) {
+      assets.set(file.name, file);
+      bytes += file.bytes;
+      if (assets.size > STYLE_OVERLAY_LIMITS.files || bytes > STYLE_OVERLAY_LIMITS.bytes) fallback('style-overlay-budget');
+    }
+  }
+  return assets;
+}
+
+function catalogue(previous, plans) {
+  const bundles = new Map();
+  if (!previous) return bundles;
+  if (previous.version !== 1 || typeof previous.baseDirectory !== 'string' || previous.baseDirectory.length > 4096
+    || !Array.isArray(previous.bundles) || previous.bundles.length > STYLE_OVERLAY_LIMITS.files) fallback('invalid-style-overlay');
+  let references = 0;
+  for (const entry of previous.bundles) {
+    if (!Array.isArray(entry) || entry.length !== 2 || !plans.has(entry[0]) || bundles.has(entry[0]) || !Array.isArray(entry[1]) || entry[1].length > STYLE_OVERLAY_LIMITS.files) fallback('invalid-style-overlay');
+    references += entry[1].length;
+    if (references > STYLE_OVERLAY_LIMITS.references) fallback('style-overlay-budget');
+    if (!entry[1].some(file => file?.name === entry[0])) fallback('invalid-style-overlay');
+    bundles.set(entry[0], entry[1]);
+  }
+  assetsFor(bundles);
+  if (Buffer.byteLength(JSON.stringify(previous)) > STYLE_OVERLAY_LIMITS.catalogueBytes) fallback('style-overlay-budget');
+  return bundles;
+}
+
+async function inspect(file) {
+  const info = await lstat(file);
+  if (!info.isFile() || info.size > STYLE_OVERLAY_LIMITS.bytes) fallback('invalid-style-overlay');
+  const data = await readFile(file);
+  return { name: path.basename(file), bytes: data.byteLength, sha256: digest(data) };
+}
+
+/** A CSS generation owns only explicitly catalogued stylesheet assets. */
+export async function createStyleOverlay({ root, source, destination, baseSource = source, manifest, plans, selected }) {
+  const previous = manifest.devStyles.overlay;
+  if (!previous && manifest.devStyles.baseClient) fallback('missing-style-overlay');
+  if (previous && !manifest.devStyles.baseClient) fallback('invalid-style-overlay');
+  if (!Array.isArray(plans) || plans.length > STYLE_OVERLAY_LIMITS.files) fallback('style-overlay-budget');
+  const names = new Set(plans.map(([name]) => name));
+  if (names.size !== plans.length || ![...names].every(filename)) fallback('invalid-style-overlay');
+  const bundles = catalogue(previous, names), previousAssets = assetsFor(bundles);
+  const selectedNames = new Set(selected.map(([name]) => name));
+  if ([...selectedNames].some(name => !names.has(name))) fallback('invalid-style-overlay');
+  for (const route of manifest.routes || []) for (const url of route.css || []) {
+    if (url.includes('?v=') && !bundles.has(path.posix.basename(url.split('?')[0]))) fallback('missing-style-overlay');
+  }
+  const [canonicalRoot, canonicalSource, canonicalBase, parent, sourceAssets] = await Promise.all([realpath(root), realpath(source), realpath(baseSource), realpath(path.dirname(destination)), realpath(path.join(source, 'assets'))]).catch(error => {
+    if (error.code === 'ENOENT') fallback('missing-style-overlay');
+    throw error;
+  });
+  // The destination does not exist yet. Its existing parent supplies the real
+  // identity, including macOS /var aliases and Windows short-name prefixes.
+  const canonicalDestination = path.join(parent, path.basename(destination));
+  if (!inside(canonicalRoot, canonicalSource) || !inside(canonicalRoot, canonicalBase)
+    || parent !== canonicalRoot && !inside(canonicalRoot, parent) || !inside(canonicalRoot, canonicalDestination)
+    || canonicalDestination === canonicalSource || canonicalDestination === canonicalBase
+    || inside(canonicalDestination, canonicalSource) || inside(canonicalSource, canonicalDestination)
+    || inside(canonicalDestination, canonicalBase) || inside(canonicalBase, canonicalDestination)
+    || sourceAssets !== path.join(canonicalSource, 'assets')) fallback('invalid-style-overlay-directory');
+  const baseDirectory = path.relative(canonicalRoot, canonicalBase).replaceAll(path.sep, '/');
+  if (previous ? previous.baseDirectory !== baseDirectory : canonicalSource !== canonicalBase) fallback('invalid-style-overlay-base');
+  const assetsDirectory = path.join(destination, 'assets');
+  let owned = false;
+  async function inherit(file) {
+    const from = path.join(source, 'assets', file.name), target = path.join(assetsDirectory, file.name);
+    let actual;
+    try { actual = await inspect(from); } catch (error) { if (error.code === 'ENOENT') fallback('missing-style-overlay-asset'); throw error; }
+    if (actual.bytes !== file.bytes || actual.sha256 !== file.sha256) fallback('invalid-style-overlay-asset');
+    try { await link(from, target); }
+    catch (error) {
+      if (!['EXDEV', 'EPERM', 'ENOTSUP', 'EACCES'].includes(error.code)) throw error;
+      await copyFile(from, target);
+    }
+  }
+  try {
+    await mkdir(destination);
+    owned = true;
+    await mkdir(assetsDirectory);
+    for (const name of selected.map(([name]) => name)) bundles.delete(name);
+    for (const file of assetsFor(bundles).values()) await inherit(file);
+  } catch (error) {
+    if (owned) await rm(destination, { recursive: true, force: true });
+    throw error;
+  }
+
+  return {
+    async recordBundle(name, result) {
+      if (!selectedNames.has(name)) fallback('invalid-style-overlay-output');
+      const files = new Map();
+      for (const output of result.outputFiles) {
+        if (path.dirname(path.resolve(output.path)) !== path.resolve(assetsDirectory) || !filename(path.basename(output.path))) fallback('invalid-style-overlay-output');
+        const file = { name: path.basename(output.path), bytes: output.contents.byteLength, sha256: digest(output.contents) };
+        files.set(file.name, file);
+      }
+      if (!files.has(name)) fallback('invalid-style-overlay-output');
+      // CSS Module compilation emits its URL assets before the outer CSS
+      // bundle. Its absolute, external URL-token imports identify exactly the
+      // emitted images/fonts to retain, without scanning the JavaScript build.
+      const prefix = manifest.config.assetBase.replace(/\/$/, '') + '/';
+      for (const output of Object.values(result.metafile.outputs)) for (const item of output.imports || []) {
+        if (item.kind !== 'url-token' || !item.external || !item.path.startsWith(prefix)) continue;
+        let name;
+        try { name = decodeURIComponent(item.path.slice(prefix.length).split(/[?#]/)[0]); }
+        catch { fallback('invalid-style-overlay-output'); }
+        if (!filename(name) || files.has(name)) continue;
+        let file;
+        try { file = await inspect(path.join(assetsDirectory, name)); }
+        catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+          const previous = previousAssets.get(name);
+          if (!previous) continue; // An unchanged base or public asset stays in its original generation.
+          await inherit(previous);
+          file = previous;
+        }
+        files.set(name, file);
+      }
+      bundles.set(name, [...files.values()]);
+      assetsFor(bundles); // Validate the aggregate budget before publishing bytes.
+      for (const output of result.outputFiles) {
+        const file = files.get(path.basename(output.path));
+        let existing;
+        try { existing = await inspect(output.path); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+        if (existing) {
+          if (existing.bytes !== file.bytes || existing.sha256 !== file.sha256) fallback('conflicting-style-overlay');
+          continue;
+        }
+        const temporary = output.path + '.' + randomUUID() + '.tmp';
+        try { await writeFile(temporary, output.contents); await rename(temporary, output.path); }
+        finally { await rm(temporary, { force: true }); }
+      }
+    },
+    async finish() {
+      const assets = assetsFor(bundles);
+      const value = { version: 1, baseDirectory, bundles: [...bundles] };
+      if (Buffer.byteLength(JSON.stringify(value)) > STYLE_OVERLAY_LIMITS.catalogueBytes) fallback('style-overlay-budget');
+      // This directory was created above for CSS only. Remove module assets
+      // that no current bundle references, rather than accumulating old URLs.
+      const entries = await readdir(assetsDirectory, { withFileTypes: true });
+      if (entries.length > STYLE_OVERLAY_LIMITS.references) fallback('style-overlay-budget');
+      for (const entry of entries) {
+        if (!entry.isFile() || !filename(entry.name)) fallback('invalid-style-overlay-output');
+        if (!assets.has(entry.name)) await rm(path.join(assetsDirectory, entry.name));
+      }
+      return value;
+    },
+  };
+}