@thomas.f/prnext 0.1.0-alpha.1

package/build/metadata-routes.mjs

@@ -0,0 +1,77 @@
+import { readFile, writeFile, access } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parse } from '@babel/parser';
+import { validateAppConfig, mergeAppConfig } from './app-config.mjs';
+import { scanMetadataImages } from './metadata-images.mjs';
+import { pageExtensionPattern, validatePageSource } from './page-extensions.mjs';
+
+const contentTypes = { robots: 'text/plain', sitemap: 'application/xml', manifest: 'application/manifest+json' };
+
+export async function scanMetadataRoutes({ root, appRoot, files, routes, patterns, validatePattern, basePath, pageExtensions, appNotFound }) {
+  let manifest;
+  const sourceExtension = pageExtensionPattern(pageExtensions);
+  for (const file of files) {
+    const relative = path.relative(appRoot, file).replaceAll(path.sep, '/');
+    const parts = relative.split('/');
+    const name = parts.pop();
+    if (parts.some(part => part.startsWith('_'))) continue;
+    const dynamic = sourceExtension.test(name);
+    const match = dynamic ? /^(robots|sitemap|manifest)$/.exec(name.replace(sourceExtension, '')) : /^(robots|sitemap|manifest)\.(txt|xml|json|webmanifest)$/.exec(name);
+    if (!match) continue;
+    const [, kind, extension] = match;
+    if (dynamic) validatePageSource(file);
+    if (!dynamic && !{ robots: ['txt'], sitemap: ['xml'], manifest: ['json', 'webmanifest'] }[kind].includes(extension)) continue;
+    if (kind !== 'sitemap' && parts.length) continue;
+    if (parts.some(part => part.startsWith('@') || /^\(\.{1,3}\)/.test(part))) throw new Error(`Parallel and intercepting metadata routes are not implemented: ${relative}.`);
+    const names = dynamic ? metadataExportNames(await readFile(file, 'utf8'), file) : [];
+    const multiple = kind === 'sitemap' && names.includes('generateSitemaps');
+    const filename = kind === 'robots' ? 'robots.txt' : kind === 'sitemap' ? multiple ? 'sitemap' : 'sitemap.xml' : dynamic ? 'manifest.webmanifest' : name;
+    const pattern = validatePattern([...parts.filter(part => !/^\([^()]+\)$/.test(part)), filename, ...(multiple ? ['[__metadata_id__]'] : [])], relative);
+    const signature = pattern.replace(/\[[^\]]+\]/g, '[]');
+    if (patterns.has(signature)) throw new Error(`Conflicting metadata route ${relative} and ${patterns.get(signature)} at ${pattern}.`);
+    if (kind === 'manifest' && manifest) throw new Error('Multiple manifest metadata files found in the App Router root.');
+    try { await access(path.join(root, 'public', pattern.slice(1))); throw new Error(`Metadata route ${pattern} conflicts with a file in public/.`); }
+    catch (error) { if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error; }
+    patterns.set(signature, relative);
+    const handlerConfig = dynamic ? await validateAppConfig(file) : {};
+    if (dynamic) {
+      if (names.some(name => ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'].includes(name))) throw new Error(`${relative} must export a default metadata function, not HTTP methods.`);
+    }
+    handlerConfig.revalidate ??= false;
+    if (multiple) handlerConfig.generateStaticParams = true;
+    routes.push({ id: `app-metadata-${createHash('sha256').update(pattern).digest('hex').slice(0, 12)}`, pattern, router: 'app', kind: 'api', file, handlerConfig,
+      cacheConfig: mergeAppConfig([handlerConfig]), metadataFile: { kind, dynamic, multiple, contentType: contentTypes[kind] } });
+    if (kind === 'manifest') manifest = `${basePath}${pattern}`;
+  }
+  await scanMetadataImages({ root, appRoot, files, routes, patterns, validatePattern, basePath, pageExtensions, appNotFound });
+  if (appNotFound && manifest) appNotFound.staticMetadata = { manifest };
+  return manifest;
+}
+
+export function metadataExportNames(source, file) {
+  const ast = parse(source, { sourceType: 'module', plugins: ['jsx', ...(/\.tsx?$/.test(file) ? ['typescript'] : [])] });
+  return ast.program.body.flatMap(node => node.type === 'ExportNamedDeclaration' ? [node.declaration?.id?.name, ...(node.declaration?.declarations || []).map(item => item.id.name), ...node.specifiers.map(item => item.exported?.name)] : []);
+}
+
+export async function prepareMetadataRoutes(project, stage) {
+  for (const route of project.routes) {
+    if (!route.metadataFile) continue;
+    const { kind, dynamic, contentType, multiple, image } = route.metadataFile;
+    let source;
+    if (dynamic) {
+      const config = await validateAppConfig(route.file);
+      source = `import * as source from ${JSON.stringify(route.file)};import {metadataHandler,metadataStaticParams} from '../runtime/metadata-route.mjs';export * from ${JSON.stringify(route.file)};\n`;
+      if (config.revalidate === undefined) source += 'export const revalidate=false;\n';
+      const options = JSON.stringify({ kind, image, multiple, contentType });
+      source += `export const GET=metadataHandler(source,${options});\n`;
+      if (multiple) source += `export const generateStaticParams=(props)=>metadataStaticParams(source,${options},props);\n`;
+    } else {
+      const body = await readFile(route.file);
+      if (body.length > 16 * 1024 * 1024) throw new Error(`Metadata file ${route.file} exceeds the 16 MiB response limit.`);
+      source = `export const revalidate=false;const body=Buffer.from(${JSON.stringify(body.toString('base64'))},'base64');export function GET(){return new Response(body,{headers:{'content-type':${JSON.stringify(contentType)}}});}`;
+    }
+    route.file = path.join(stage, '.entries', route.id + '.mjs');
+    await writeFile(route.file, source);
+  }
+}

package/build/middleware.mjs

@@ -0,0 +1,231 @@
+import { withLocale } from '../compat/locale.cjs';
+import {frameworkImportName, frameworkImportPattern} from './framework-imports.mjs';
+import { moduleResolutionPlugin } from './module-resolution.mjs';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse } from '@babel/parser';
+import { build as bundle } from './compiler.mjs';
+import { compileRouteMatcher } from './custom-routes.mjs';
+import { createNativePackages } from './native-packages.mjs';
+import { compileEdge } from './edge.mjs';
+
+const extensions = ['js', 'jsx', 'ts', 'tsx', 'mjs', 'cjs'];
+const loaders = { '.js': 'jsx', '.jsx': 'jsx', '.mjs': 'jsx', '.cjs': 'jsx', '.ts': 'ts', '.tsx': 'tsx' };
+const compatibility = new Map([['server', 'server'], ['headers', 'headers'], ['cache', 'cache'], ['navigation', 'navigation-server'], ['constants', 'constants']]);
+const forbiddenConfig = new Set(['preferredRegion', 'maxDuration', 'dynamic', 'dynamicParams', 'revalidate', 'fetchCache']);
+const MAX_MATCHERS = 1000;
+const MAX_CONFIG_BYTES = 2 * 1024 * 1024;
+const MAX_CONFIG_VISITS = 300_000;
+
+function fail(file, message) { throw new Error(`Invalid middleware/proxy ${file}: ${message}`); }
+function unwrap(node) {
+  while (['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'TypeCastExpression', 'ParenthesizedExpression'].includes(node?.type)) node = node.expression;
+  return node;
+}
+function keyOf(property) {
+  return !property.computed && (property.key?.type === 'Identifier' ? property.key.name : property.key?.value);
+}
+function member(node) {
+  if (node?.type === 'Identifier') return node.name;
+  if (node?.type !== 'MemberExpression' || node.optional) return;
+  const owner = member(node.object);
+  const name = node.computed ? node.property.type === 'StringLiteral' && node.property.value : node.property.name;
+  return owner && typeof name === 'string' ? `${owner}.${name}` : undefined;
+}
+
+function configBudget(file) {
+  let visits = 0, bytes = 0;
+  return {
+    visit() { if (++visits > MAX_CONFIG_VISITS) fail(file, 'configuration constant expansion exceeds the evaluation budget'); },
+    bytes(length) { if ((bytes += length) > MAX_CONFIG_BYTES) fail(file, 'configuration constant expansion exceeds 2 MiB'); },
+    string(value) {
+      // Reject a large literal before JSON escaping can allocate another copy.
+      if (Buffer.byteLength(value) > MAX_CONFIG_BYTES - bytes) fail(file, 'configuration constant expansion exceeds 2 MiB');
+      this.bytes(Buffer.byteLength(JSON.stringify(value)));
+    },
+  };
+}
+
+function literal(node, locals, file, seen = new Set(), depth = 0, budget = configBudget(file)) {
+  budget.visit();
+  if (depth > 32) fail(file, 'configuration nesting exceeds 32 levels');
+  node = unwrap(node);
+  if (!node) { budget.bytes(4); return undefined; }
+  if (node.type === 'StringLiteral') { budget.string(node.value); return node.value; }
+  if (['NumericLiteral', 'BooleanLiteral'].includes(node.type)) { budget.bytes(String(node.value).length); return node.value; }
+  if (node.type === 'NullLiteral') { budget.bytes(4); return null; }
+  if (node.type === 'TemplateLiteral' && !node.expressions.length) {
+    budget.string(node.quasis[0].value.cooked);
+    return node.quasis[0].value.cooked;
+  }
+  if (node.type === 'Identifier') {
+    if (node.name === 'undefined') { budget.bytes(4); return undefined; }
+    if (!locals.has(node.name) || seen.has(node.name)) fail(file, `configuration must be statically analyzable; cannot resolve ${node.name}`);
+    return literal(locals.get(node.name), locals, file, new Set([...seen, node.name]), depth + 1, budget);
+  }
+  if (node.type === 'ArrayExpression') {
+    if (node.elements.length > MAX_MATCHERS) fail(file, `configuration arrays may contain at most ${MAX_MATCHERS} items`);
+    budget.bytes(2 + Math.max(0, node.elements.length - 1));
+    return node.elements.map(item => {
+      if (!item || item.type === 'SpreadElement') fail(file, 'configuration arrays cannot contain holes or spreads');
+      return literal(item, locals, file, seen, depth + 1, budget);
+    });
+  }
+  if (node.type === 'ObjectExpression') {
+    budget.bytes(2 + Math.max(0, node.properties.length - 1));
+    const result = {};
+    for (const property of node.properties) {
+      const key = keyOf(property);
+      if (property.type !== 'ObjectProperty' || typeof key !== 'string') fail(file, 'configuration requires literal object properties without spreads or computed keys');
+      if (Object.hasOwn(result, key)) fail(file, `duplicate configuration field ${key}`);
+      budget.string(key); budget.bytes(1);
+      Object.defineProperty(result, key, { value: literal(property.value, locals, file, seen, depth + 1, budget), enumerable: true });
+    }
+    return result;
+  }
+  fail(file, 'configuration must be statically analyzable literals, not executable expressions');
+}
+
+function collectExports(ast, file) {
+  const locals = new Map();
+  const exported = new Map();
+  let commonjs = false;
+  for (const statement of ast.program.body) {
+    const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+    if (declaration?.type === 'VariableDeclaration') for (const item of declaration.declarations) {
+      if (item.id.type !== 'Identifier') continue;
+      if (declaration.kind === 'const') locals.set(item.id.name, item.init);
+      if (statement.type === 'ExportNamedDeclaration') exported.set(item.id.name, item.init);
+    }
+    if (['FunctionDeclaration', 'ClassDeclaration'].includes(declaration?.type) && declaration.id) {
+      locals.set(declaration.id.name, declaration);
+      if (statement.type === 'ExportNamedDeclaration') exported.set(declaration.id.name, declaration);
+    }
+    if (statement.type === 'ExportDefaultDeclaration') exported.set('default', statement.declaration);
+    if (statement.type === 'ExportNamedDeclaration' && statement.exportKind !== 'type') for (const specifier of statement.specifiers) {
+      if (specifier.exportKind === 'type') continue;
+      const name = specifier.exported.name ?? specifier.exported.value;
+      if (statement.source && (name === 'config' || name === 'runtime')) fail(file, `${name} must be declared in this file, not re-exported`);
+      exported.set(name, statement.source ? null : specifier.local);
+    }
+    if (statement.type === 'ExportAllDeclaration') fail(file, 'wildcard exports cannot define middleware or its static configuration; use explicit exports');
+    if (statement.type !== 'ExpressionStatement' || statement.expression.type !== 'AssignmentExpression' || statement.expression.operator !== '=') continue;
+    const assignment = statement.expression;
+    const target = member(assignment.left);
+    if (!target || !(target === 'module.exports' || /^(?:module\.exports|exports)\.[^.]+$/.test(target))) continue;
+    commonjs = true;
+    if (target === 'module.exports') {
+      const value = unwrap(assignment.right);
+      if (value.type === 'ObjectExpression') {
+        for (const property of value.properties) {
+          const key = keyOf(property);
+          if (typeof key !== 'string' || !['ObjectProperty', 'ObjectMethod'].includes(property.type)) fail(file, 'CommonJS middleware exports require explicit named properties');
+          exported.set(key, property.type === 'ObjectMethod' ? property : property.value);
+        }
+      } else exported.set('default', value);
+    } else exported.set(target.split('.').at(-1), assignment.right);
+  }
+  return { locals, exported, commonjs };
+}
+
+export async function inspectMiddleware(file, convention = path.basename(file).split('.')[0], { basePath = '', i18n } = {}) {
+  const ast = parse(await readFile(file, 'utf8'), { sourceType: 'unambiguous', sourceFilename: file,
+    plugins: ['jsx', ...(/\.tsx?$/.test(file) ? ['typescript'] : [])] });
+  if (ast.program.directives.some(directive => ['use client', 'use server'].includes(directive.value.value))) fail(file, 'React Client Components and Server Actions cannot define middleware');
+  const { locals, exported, commonjs } = collectExports(ast, file);
+  for (const name of forbiddenConfig) if (exported.has(name)) fail(file, `route segment option ${name} is unsupported here`);
+  const raw = exported.has('config') ? literal(exported.get('config'), locals, file) : {};
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) fail(file, 'config must be a literal object');
+  const unknown = Object.keys(raw).filter(key => !['matcher', 'runtime'].includes(key));
+  if (unknown.length) fail(file, `unsupported config fields: ${unknown.join(', ')}`);
+  const declaredRuntime = exported.has('runtime') ? literal(exported.get('runtime'), locals, file) : raw.runtime;
+  if (convention === 'proxy' && (exported.has('runtime') || raw.runtime !== undefined)) fail(file, 'proxy always uses Node.js and cannot configure runtime');
+  if ([declaredRuntime, raw.runtime].some(value => value !== undefined && !['nodejs', 'edge', 'experimental-edge'].includes(value))) fail(file, 'runtime must be nodejs, edge or experimental-edge');
+  const exportName = exported.has(convention) ? convention : exported.has('default') ? 'default' : undefined;
+  if (!exportName) fail(file, `export a default function or a named ${convention} function`);
+  let handler = unwrap(exported.get(exportName));
+  const seen = new Set();
+  while (handler?.type === 'Identifier' && locals.has(handler.name) && !seen.has(handler.name)) {
+    seen.add(handler.name); handler = unwrap(locals.get(handler.name));
+  }
+  if (handler && ['StringLiteral', 'NumericLiteral', 'BooleanLiteral', 'NullLiteral', 'ObjectExpression', 'ArrayExpression', 'ClassDeclaration', 'ClassExpression'].includes(handler.type)) fail(file, `${exportName} must be a function`);
+  const matchers = raw.matcher === undefined ? ['/:path*'] : typeof raw.matcher === 'string' ? [raw.matcher] : raw.matcher;
+  if (!Array.isArray(matchers) || matchers.length > MAX_MATCHERS) fail(file, `matcher must be a string or at most ${MAX_MATCHERS} matcher entries`);
+  const localized = i18n ? matchers.flatMap(input => {const value = typeof input === 'string' ? {source: input} : input; return value.locale === false ? [value] : i18n.locales.map(locale=>({...value,source:withLocale(value.source,locale,i18n.defaultLocale)}));}) : matchers;
+  if (localized.length > MAX_MATCHERS) fail(file, `localized matchers exceed ${MAX_MATCHERS} entries`);
+  const compiled = localized.map((matcher, index) => compileRouteMatcher(matcher, `${file}.config.matcher[${index}]`, { basePath }));
+  if (Buffer.byteLength(JSON.stringify(compiled)) > MAX_CONFIG_BYTES) fail(file, 'compiled matchers exceed 2 MiB');
+  return { file, convention, exportName, commonjs, runtime: declaredRuntime === 'edge' || declaredRuntime === 'experimental-edge' ? 'edge' : 'nodejs',
+    ...(declaredRuntime !== undefined ? { declaredRuntime } : {}), matchers: compiled };
+}
+
+export async function scanMiddleware(root, { basePath = '', pageExtensions = extensions, i18n } = {}) {
+  const candidates = [];
+  for (const directory of ['', 'src']) for (const convention of ['middleware', 'proxy']) for (const extension of pageExtensions) {
+    const file = path.join(root, directory, `${convention}.${extension}`);
+    try { await access(file); candidates.push({ file, convention }); }
+    catch (error) { if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error; }
+  }
+  if (candidates.length > 1) throw new Error(`Conflicting middleware/proxy files: ${candidates.map(item => path.relative(root, item.file)).join(', ')}. Keep exactly one middleware or proxy entry.`);
+  return candidates.length ? inspectMiddleware(candidates[0].file, candidates[0].convention, { basePath, i18n }) : undefined;
+}
+
+/** Build request interception independently of either React router graph. */
+export async function compileMiddleware({ project, stage, manifest, dev, defineEnvironment = {}, moduleResolution = {} }) {
+  const descriptor = project.middleware;
+  if (!descriptor) return;
+  if (descriptor.runtime === 'edge') {
+    await compileEdge({ file: descriptor.file, outfile: path.join(stage, 'server/middleware.mjs'), projectRoot: project.root,
+      dev, defineEnvironment, plugins: [moduleResolutionPlugin(moduleResolution, project.root)], defaultExport: descriptor.exportName === 'default' });
+    manifest.middleware = { module: 'server/middleware.mjs', exportName: descriptor.exportName, convention: descriptor.convention,
+      runtime: 'edge', declaredRuntime: descriptor.declaredRuntime, matchers: descriptor.matchers };
+    return;
+  }
+  const entry = path.join(stage, '.entries', 'middleware.mjs');
+  const selected = descriptor.exportName;
+  const statement = descriptor.commonjs
+    ? `import module from ${JSON.stringify(descriptor.file)};\n${selected === 'default' ? "export default typeof module==='function'?module:module.default;" : `export const ${selected}=module[${JSON.stringify(selected)}];`}`
+    : `export {${selected}} from ${JSON.stringify(descriptor.file)};`;
+  await writeFile(entry, statement);
+  const native = createNativePackages(project.root, { isClientSource: () => false });
+  const compatibilityPlugin = {
+    name: 'prnext-middleware-compatibility',
+    setup(esbuild) {
+      esbuild.onResolve({ filter: frameworkImportPattern }, args => {
+        const name = frameworkImportName(args.path);
+        const compatible = compatibility.get(name);
+        return compatible ? { path: `../compat/${compatible}.cjs`, external: true }
+          : { errors: [{ text: `Unsupported middleware import ${args.path}; use next/server, next/headers, next/cache, next/navigation or next/constants.` }] };
+      });
+      esbuild.onResolve({ filter: /^(?:server-only|client-only)$/ }, args => args.path === 'server-only'
+        ? { path: args.path, namespace: 'prnext-middleware-empty' }
+        : { errors: [{ text: 'client-only modules cannot run in middleware/proxy.' }] });
+      esbuild.onResolve({ filter: /\.css$/ }, () => ({ errors: [{ text: 'Middleware/proxy cannot import stylesheet assets.' }] }));
+      esbuild.onLoad({ filter: /.*/, namespace: 'prnext-middleware-empty' }, () => ({ contents: '', loader: 'js' }));
+      esbuild.onLoad({ filter: /\.(?:[cm]?js|jsx|tsx?)$/, namespace: 'file' }, async args => {
+        const contents = args.prnextSource ?? await readFile(args.path, 'utf8');
+        if (/['"]use (?:client|server)['"]/.test(contents)) {
+          const ast = parse(contents, { sourceType: 'unambiguous', plugins: ['jsx', ...(/\.tsx?$/.test(args.path) ? ['typescript'] : [])] });
+          if (ast.program.directives.some(directive => ['use client', 'use server'].includes(directive.value.value))) fail(args.path, 'React Client Components and Server Actions cannot run in middleware');
+        }
+        return { contents, loader: loaders[path.extname(args.path)] || 'jsx', resolveDir: path.dirname(args.path) };
+      });
+    },
+  };
+  let output;
+  for (;;) {
+    const version = native.version;
+    try {
+      output = await bundle({ absWorkingDir: project.root, entryPoints: [entry], outfile: path.join(stage, 'server/middleware.mjs'),
+        bundle: true, write: false, platform: 'node', format: 'esm', target: 'node22', conditions: ['node'], jsx: 'automatic',
+        sourcemap: dev, logLevel: 'silent', define: { 'process.env.NODE_ENV': JSON.stringify(dev ? 'development' : 'production'), ...defineEnvironment },
+        banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" },
+        plugins: [moduleResolutionPlugin(moduleResolution, project.root), compatibilityPlugin, native.plugin('middleware')],
+      });
+      if (version === native.version) break;
+    } catch (error) { if (version === native.version) throw error; }
+  }
+  for (const file of output.outputFiles) { await mkdir(path.dirname(file.path), { recursive: true }); await writeFile(file.path, file.contents); }
+  manifest.middleware = { module: 'server/middleware.mjs', exportName: selected, convention: descriptor.convention,
+    runtime: 'nodejs', ...(descriptor.declaredRuntime !== undefined ? { declaredRuntime: descriptor.declaredRuntime } : {}), matchers: descriptor.matchers };
+}

package/build/migrate.mjs

@@ -0,0 +1,289 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { readFile, writeFile, rename, rm, lstat, realpath, access } from 'node:fs/promises';
+import { checkProject } from './check.mjs';
+import { sourceCheckout } from '../native/resolve.mjs';
+
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+const dependencyFields = ['dependencies', 'devDependencies', 'optionalDependencies'];
+const locks = ['package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb'];
+const own = (object, key) => Object.hasOwn(object, key);
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+async function optionalFile(file) {
+  try { return await readFile(file); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+export function parseMigrationArgs(args) {
+  const options = { dryRun: false, install: true, json: false };
+  let directory;
+  for (const arg of args) {
+    if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--no-install') options.install = false;
+    else if (arg === '--json') options.json = true;
+    else if (arg.startsWith('-')) throw new Error(`Unknown migrate option: ${arg}. Use --dry-run, --no-install or --json.`);
+    else if (directory === undefined) directory = arg;
+    else throw new Error('migrate accepts a single project directory.');
+  }
+  return { directory: path.resolve(directory || '.'), options };
+}
+
+// Preserve literal shell words without evaluating them. Complex shell programs
+// need a manual edit: replacing a substring could drop a build step or rewrite
+// a quoted example instead of the executable command.
+function words(script) {
+  if (/[\r\n]/.test(script)) throw new Error('contains multiple shell lines');
+  const result = [];
+  const token = /\s*((?:[^\s'"\\;&|<>`$()*?#[\]{}~!]+|'[^']*'|"[^"\\`$]*")+)/gy;
+  let offset = 0;
+  while (offset < script.length) {
+    if (!script.slice(offset).trim()) break;
+    token.lastIndex = offset;
+    const match = token.exec(script);
+    if (!match) throw new Error('contains shell chaining, substitution or escaping');
+    result.push({ raw: match[1], value: match[1].replace(/'([^']*)'|"([^"]*)"/g, (_all, a, b) => a ?? b) });
+    offset = token.lastIndex;
+  }
+  return result;
+}
+
+export function migrateScript(script, command) {
+  if (script === undefined) return { value: `prn ${command}`, removed: [] };
+  if (typeof script !== 'string') throw new Error(`scripts.${command} must be a string.`);
+  // Existing PRNext scripts, including customized wrappers, are not rewritten.
+  if (/^(?:prn|prnext)\s+/.test(script.trim())) return { value: script, removed: [] };
+  let tokens;
+  try { tokens = words(script); }
+  catch (error) { throw new Error(`scripts.${command} ${error.message}. Adapt it to prn ${command} manually before migrating; no scripts were overwritten.`); }
+  const prefix = [];
+  let environmentPort;
+  if (tokens[0]?.value === 'cross-env') prefix.push(tokens.shift().raw);
+  while (tokens[0] && /^[A-Za-z_][A-Za-z\d_]*=/.test(tokens[0].value)) {
+    const assignment = tokens.shift();
+    prefix.push(assignment.raw);
+    if (assignment.value.startsWith('PORT=')) environmentPort = assignment.value.slice(5);
+  }
+  if (tokens[0]?.value === 'npx') {
+    tokens.shift();
+    if (tokens[0]?.value === '--no-install') tokens.shift();
+  }
+  const executable = tokens.shift()?.value;
+  if (!['next', 'rx'].includes(executable) || tokens.shift()?.value !== command) {
+    throw new Error(`scripts.${command} is customized. Adapt it to prn ${command} manually before migrating; no scripts were overwritten.`);
+  }
+  // Upgrade the former shortcut without interpreting its native PRNext options
+  // as Next.js bundler flags. Complex shell programs still require a manual edit.
+  if (executable === 'rx') return { value: [...prefix, 'prn', command, ...tokens.map(token => token.raw)].join(' '), removed: [] };
+  const kept = [], removed = [];
+  let directory = false, explicitPort = false;
+  for (let i = 0; i < tokens.length; i++) {
+    const { value, raw } = tokens[i];
+    if (['--turbo', '--turbopack', '--webpack'].includes(value) && command !== 'start') { removed.push(value); continue; }
+    const option = /^(-p|--port|-H|--hostname)(?:=(.*))?$/.exec(value);
+    if (option && command !== 'build') {
+      const flag = ['-p', '--port'].includes(option[1]) ? '--port' : '--hostname';
+      if (flag === '--port') explicitPort = true;
+      if (option[2] !== undefined) kept.push(raw.replace(/^(['"]?)(?:-p|--port|-H|--hostname)/, `$1${flag}`));
+      else {
+        const argument = tokens[++i];
+        if (!argument || argument.value.startsWith('-')) throw new Error(`scripts.${command}: ${option[1]} requires a value.`);
+        kept.push(flag, argument.raw);
+      }
+    } else if (!value.startsWith('-') && !directory) {
+      directory = true;
+      // The PRNext CLI takes the directory before its server options.
+      kept.unshift(raw);
+    } else throw new Error(`scripts.${command}: unsupported Next option ${raw}. Adapt the script before migrating.`);
+  }
+  // The native server takes an explicit port; preserve Next's literal PORT
+  // prefix when the script does not already override it with a CLI option.
+  if (command !== 'build' && !explicitPort && environmentPort !== undefined) {
+    if (!/^\d+$/.test(environmentPort) || Number(environmentPort) > 65535) throw new Error(`scripts.${command}: PORT must be a literal port number. Adapt the script before migrating.`);
+    kept.push('--port', environmentPort);
+  }
+  return { value: [...prefix, 'prn', command, ...kept].join(' '), removed };
+}
+
+export function migrationPackage(input, framework, spec) {
+  if (!record(input)) throw new Error('package.json must contain an object.');
+  for (const field of ['scripts', ...dependencyFields]) {
+    if (input[field] !== undefined && !record(input[field])) throw new Error(`package.json ${field} must be an object.`);
+  }
+  const output = structuredClone(input);
+  const changes = [], notes = [];
+  output.scripts ||= {};
+  for (const command of ['dev', 'build', 'start']) {
+    const previous = input.scripts?.[command];
+    const migrated = migrateScript(previous, command);
+    if (previous === migrated.value) continue;
+    if (previous !== undefined) {
+      let backup = `${command}:next`, suffix = 2;
+      while (own(output.scripts, backup) && output.scripts[backup] !== previous) backup = `${command}:next:${suffix++}`;
+      if (!own(output.scripts, backup)) {
+        output.scripts[backup] = previous;
+        changes.push({ field: `scripts.${backup}`, before: null, after: previous });
+      }
+    }
+    output.scripts[command] = migrated.value;
+    changes.push({ field: `scripts.${command}`, before: previous ?? null, after: migrated.value });
+    if (migrated.removed.length) notes.push(`scripts.${command}: removed Next bundler flags ${migrated.removed.join(', ')}; PRNext selects its compiler from the project configuration.`);
+  }
+  const expected = framework.peerDependencies['react-server-dom-webpack'];
+  const wanted = { [framework.name]: spec, react: expected, 'react-dom': expected, 'react-server-dom-webpack': expected };
+  // Remove the former local package name so two packages cannot compete for
+  // the same prn/prnext executable after installing the scoped release.
+  if (framework.name !== 'prnext') {
+    for (const field of dependencyFields) {
+      if (!output[field] || !own(output[field], 'prnext')) continue;
+      changes.push({ field: `${field}.prnext`, before: output[field].prnext, after: null });
+      delete output[field].prnext;
+    }
+  }
+  output.dependencies ||= {};
+  for (const [name, version] of Object.entries(wanted)) {
+    if (output.dependencies[name] !== version) {
+      changes.push({ field: `dependencies.${name}`, before: output.dependencies[name] ?? null, after: version });
+      output.dependencies[name] = version;
+    }
+    for (const field of ['devDependencies', 'optionalDependencies']) {
+      if (output[field] && own(output[field], name)) {
+        changes.push({ field: `${field}.${name}`, before: output[field][name], after: null });
+        delete output[field][name];
+      }
+    }
+  }
+  if (changes.some(change => /^dependencies\.react/.test(change.field))) notes.push(`React protocol packages are aligned to ${expected}. Check other libraries' peer dependencies during installation.`);
+  notes.push('Next.js, application sources and next.config files are kept. Existing Next scripts are saved as dev:next, build:next and start:next when applicable.');
+  return { package: output, changes, notes };
+}
+
+async function installContext(root, pkg) {
+  const present = [];
+  for (const name of locks) if (await optionalFile(path.join(root, name))) present.push(name);
+  const manager = pkg.packageManager?.split('@')[0];
+  if (manager && manager !== 'npm') return { allowed: false, reason: `This project uses ${manager}. Use --no-install, then install with ${manager}.`, locks: present };
+  if (present.some(name => !['package-lock.json', 'npm-shrinkwrap.json'].includes(name))) {
+    return { allowed: false, reason: 'A non-npm lockfile is present. Use --no-install and the existing package manager to preserve its lockfile.', locks: present };
+  }
+  for (let directory = root; ; directory = path.dirname(directory)) {
+    const contents = directory === root ? null : await optionalFile(path.join(directory, 'package.json'));
+    let ancestor;
+    try { ancestor = directory === root ? pkg : contents && JSON.parse(contents); } catch { ancestor = null; }
+    if (ancestor?.workspaces) return { allowed: false, reason: 'A workspace package manager must be run from its workspace root. Use --no-install, then install from that root.', locks: present };
+    if (directory === path.dirname(directory)) break;
+  }
+  return { allowed: true, locks: present };
+}
+
+async function backup(file, contents) {
+  for (let index = 0; index < 1000; index++) {
+    const destination = `${file}.prnext-backup${index ? '.' + index : ''}`;
+    try { await writeFile(destination, contents, { flag: 'wx', mode: 0o600 }); return destination; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if ((await readFile(destination)).equals(contents)) return destination;
+    }
+  }
+  throw new Error(`Too many migration backups for ${file}.`);
+}
+
+async function replacePackage(file, original, text, mode) {
+  const temporary = `${file}.prnext-${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, text, { flag: 'wx', mode });
+    if (!(await readFile(file)).equals(original)) throw new Error('package.json changed during migration. Retry after the other edit finishes.');
+    await rename(temporary, file);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+export async function installMigrationDependencies(root, { json = false, local = false } = {}) {
+  const npm = process.env.npm_execpath;
+  // Never use a shell to interpolate a project path or a package specification.
+  const args = ['install', '--workspaces=false', ...(local ? ['--install-links=false'] : [])];
+  const command = npm && /(?:^|[/\\])npm(?:-cli)?\.(?:c?js)$/.test(npm) ? process.execPath : process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const argv = command === process.execPath ? [npm, ...args] : args;
+  await new Promise((resolve, reject) => {
+    // Windows .cmd launchers require a shell; argv contains only fixed flags,
+    // never project data. npx/npm invocations use npm-cli.js directly instead.
+    const child = spawn(command, argv, { cwd: root, stdio: json ? ['inherit', 2, 2] : 'inherit', shell: process.platform === 'win32' && command === 'npm.cmd' });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => code === 0 ? resolve() : reject(new Error(`npm install failed (${signal || code}). Backups are available; fix the dependency conflict and retry. No --force or --legacy-peer-deps override was used.`)));
+  });
+  for (const name of ['prn', 'prnext']) {
+    const executable = path.join(root, 'node_modules/.bin', name + (process.platform === 'win32' ? '.cmd' : ''));
+    try { await access(executable, process.platform === 'win32' ? constants.F_OK : constants.X_OK); }
+    catch { throw new Error(`npm did not install the ${name} executable. Check npm's bin-links setting and the local PRNext dependency path, then retry.`); }
+  }
+}
+
+export async function migrateProject(directory, { dryRun = false, install = true, json = false } = {}, services = {}) {
+  const root = path.resolve(directory), file = path.join(root, 'package.json');
+  const report = { root, ok: false, status: 'checking', dryRun, changes: [], backups: [], notes: [], preflight: null };
+  try {
+    const stat = await lstat(file);
+    if (!stat.isFile()) throw new Error('Migration requires a regular package.json file, not a symlink or directory.');
+    const original = await readFile(file);
+    const source = original.toString('utf8');
+    const input = JSON.parse(source.replace(/^\uFEFF/, ''));
+    if (!record(input)) throw new Error('package.json must contain an object.');
+    const framework = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+    if ([framework.name, 'prnext', 'prnext-monorepo'].includes(input.name)) throw new Error('Choose the Next.js application directory, not the PRNext framework repository.');
+    const local = sourceCheckout() !== null;
+    // npm resolves file dependencies from the physical working directory. A
+    // symlink such as macOS /var -> /private/var otherwise changes ../ depth.
+    const relative = path.relative(await realpath(root), await realpath(packageRoot)).split(path.sep).join('/') || '.';
+    const spec = local ? `file:${relative}` : framework.version;
+    const plan = migrationPackage(input, framework, spec);
+    report.changes = plan.changes;
+    report.notes = plan.notes;
+    if (local) report.notes.push(`This unpublished checkout uses a local PRNext dependency (${spec}); keep this checkout available. Rust is required on the first native build.`);
+    const context = await installContext(root, input);
+    if (!context.allowed) {
+      report.notes.push(context.reason);
+      if (install && !dryRun) throw new Error(context.reason);
+    }
+    const check = services.check || checkProject;
+    report.preflight = await check(root, { validateDependencies: false });
+    if (!report.preflight.ok) throw new Error(`Project preflight failed: ${report.preflight.errors.join(' ')}`);
+    if (!report.preflight.routes.length) throw new Error('No application routes found. Choose the Next.js app directory containing app/ or pages/.');
+    if (dryRun) { report.ok = true; report.status = 'preview'; return report; }
+    if (plan.changes.length || install) {
+      report.backups.push(await backup(file, original));
+      for (const name of context.locks) {
+        const lockFile = path.join(root, name);
+        const stat = await lstat(lockFile);
+        if (!stat.isFile()) throw new Error(`Migration requires a regular ${name} file.`);
+        report.backups.push(await backup(lockFile, await readFile(lockFile)));
+      }
+    }
+    if (plan.changes.length) {
+      const indent = /\n([\t ]+)"/.exec(source)?.[1] || 2;
+      const newline = source.includes('\r\n') ? '\r\n' : '\n';
+      const text = (source.startsWith('\uFEFF') ? '\uFEFF' : '') + JSON.stringify(plan.package, null, indent).replaceAll('\n', newline) + (/\r?\n$/.test(source) ? newline : '');
+      await replacePackage(file, original, text, stat.mode & 0o777);
+    }
+    report.status = plan.changes.length ? 'prepared' : 'unchanged';
+    if (!install) {
+      report.ok = true;
+      report.notes.push('Dependency installation and installed-version validation are pending. Install with your package manager, then run prn check and prn build.');
+      return report;
+    }
+    report.status = 'installing';
+    await (services.install || installMigrationDependencies)(root, { json, local });
+    report.preflight = await check(root);
+    if (!report.preflight.ok) throw new Error(`Dependencies were installed, but final preflight failed: ${report.preflight.errors.join(' ')}`);
+    report.ok = true;
+    report.status = 'migrated';
+    report.notes.push('Migration prepared and dependencies checked. Run npm run build and test your application before deploying.');
+    return report;
+  } catch (error) {
+    report.error = error.message;
+    if (report.status === 'checking') report.status = 'blocked';
+    else report.status = 'incomplete';
+    return report;
+  }
+}