@wular/pnext 0.0.1 → 0.0.3

package/src/cache/context.ts

@@ -22,7 +22,10 @@ export interface CacheScope {
   controller?: AbortController;
 }
 
-const storage = new AsyncLocalStorage<CacheScope>();
+// globalThis-anchored: the prebundled server entry inlines its own copy of this module.
+const CACHE_SCOPE_STORAGE = Symbol.for('pnext.cacheScopeStorage');
+const storage = ((globalThis as Record<PropertyKey, unknown>)[CACHE_SCOPE_STORAGE] ??=
+  new AsyncLocalStorage<CacheScope>()) as AsyncLocalStorage<CacheScope>;
 
 export function currentCacheScope() {
   return storage.getStore();

package/src/cli/build.ts

@@ -1,11 +1,11 @@
 import { copyFile, mkdir, rename, writeFile } from 'node:fs/promises';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeVercelOutput } from './adapters/vercel';
 import { startWarmChild } from './adapters/vercel-warm';
-import { loadConfig, pathToFileHref } from '../config';
+import { devOutSegment, loadConfig, pathToFileHref } from '../config';
 import { bootstrapCompat } from '../compat-bootstrap';
 import {
   buildParallelPhaseError,
@@ -21,6 +21,7 @@ import {
 } from '../extensions';
 import { buildClientEntries, emitStaticClientChunks, startClientSources } from '../client/build';
 import { beginSourceScope, endSourceScope, sourceCacheStats } from '../resolve/source-text';
+import { flushDevModuleCaches } from '../dev/module-cache';
 import { scanFactsStats } from '../resolve/scan-facts';
 import { clientEntryName } from '../client/paths';
 import { registerServerRuntime, serverBundleTargetForRuntime } from '../runtime/server';
@@ -99,6 +100,9 @@ interface BuildStepState {
   /** Root-relative 'use server' module paths — known from discovery, so the
    * client stage keys off this instead of waiting for their compile. */
   actionSources?: string[];
+  /** First-party files that import a node_modules action module (absolute paths) — see
+   * ActionDiscovery.actionImporters; route.sourceFiles never reaches into node_modules itself. */
+  actionImporters?: string[];
   /** Work a step handed back rather than finishing inline; awaited before the
    * build manifest is written, so it lands under the client stage. */
   deferred?: Promise<void>;
@@ -160,6 +164,7 @@ export async function buildProject(root?: string, options: BuildOptions = {}) {
   } finally {
     endSourceScope();
     restoreSpecifiersManifest();
+    flushDevModuleCaches();
   }
 }
 
@@ -190,9 +195,20 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
   // adapter step.
   const warm = options.adapter === 'vercel' ? startWarmChild(config) : undefined;
   await log.step('prepare output directory', async () => {
-    await ensureEmptyDir(config.outPath);
+    // Build-owned outputs only: `<outRoot>/dev` belongs to a possibly-running
+    // dev server and must survive.
+    await ensureEmptyDir(config.outPath, [devOutSegment]);
     await copyPublicDir(config.publicPath, path.join(config.outPath, 'public'));
   });
+  // Prebundled server entry for `pnext start`: framework-only, independent of the
+  // app build, so it runs in a child process for the whole build — its bundling
+  // heap never stacks on the build's peak RSS and its wall hides under the build.
+  // Best-effort — a failure only costs start time. Awaited before the summary.
+  const serverEntryDone = import('./server-entry')
+    .then(entry => entry.emitServerEntryChild(config.outPath))
+    .catch((error: Error) => {
+      console.warn(`pnext build: server entry bundling skipped — ${error.message}`);
+    });
   // The document-level stylesheets run their postcss/Tailwind pass on the CSS
   // worker, so they overlap with the route scan below instead of serializing
   // ahead of it. Awaited before prepareRouteCssChunks — route CSS still builds
@@ -319,11 +335,19 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
   );
 
   const actionSources = buildState.actionSources ?? buildState.actions.map(a => a.sourceKey);
-  const actionFiles = new Set(actionSources.map(source => path.resolve(config.root, source)));
+  // realpath, not resolve: a hybrid app's routes are scanned through the pages-compat mirror, whose
+  // `source-app` is a symlink to the real app dir - the two spellings of one file must compare equal.
+  const actionFiles = new Set(actionSources.map(source => realFilePath(path.resolve(config.root, source))));
+  // A node_modules action module never lands in route.sourceFiles itself (that walk stops at the
+  // package boundary), so a route reaching one only through a first-party importer is matched here.
+  const actionImporters = new Set((buildState.actionImporters ?? []).map(realFilePath));
   for (const route of routes) {
     if (
       route.kind === 'page' &&
-      route.sourceFiles.some(file => actionFiles.has(path.resolve(file)))
+      route.sourceFiles.some(file => {
+        const real = realFilePath(file);
+        return actionFiles.has(real) || actionImporters.has(real);
+      })
     ) {
       addClientEntryReason(route, 'actions');
     }
@@ -871,6 +895,7 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
   };
   await writeBuildManifest(config.outPath, manifest);
   log.log(`wrote manifest.json (${routes.length} route${routes.length === 1 ? '' : 's'})`);
+  await log.step('server entry', () => serverEntryDone);
   for (const hook of getBuildExtensions().completeHooks) {
     await hook({ config, manifest, log });
   }
@@ -3053,6 +3078,15 @@ function isAfterPrerenderError(error: unknown): boolean {
   );
 }
 
+/** Symlink-resolved path, for comparing two spellings of one file. Missing files keep their path. */
+function realFilePath(file: string): string {
+  try {
+    return realpathSync.native(file);
+  } catch {
+    return path.resolve(file);
+  }
+}
+
 function safePublicPath(outPath: string, ...segments: string[]) {
   const publicPath = path.join(outPath, 'public');
   const file = path.join(publicPath, ...segments);

package/src/cli/create.ts

@@ -0,0 +1,146 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { bold, cyan, dim, green } from '../utils/ansi';
+
+export interface CreateAppOptions {
+  install: boolean;
+}
+
+export async function createApp(dir: string | undefined, options: CreateAppOptions) {
+  if (!dir) {
+    console.log('Usage: pnext create <directory> [--no-install]');
+    throw new Error('pnext create requires a directory argument');
+  }
+
+  const target = path.resolve(dir);
+  if (existsSync(target)) {
+    if ((await readdir(target)).length > 0) {
+      throw new Error(`Directory already exists and is not empty: ${target}`);
+    }
+  } else {
+    await mkdir(target, { recursive: true });
+  }
+
+  const name = sanitizePackageName(path.basename(target));
+  console.log(`${cyan('▲')} ${bold('pnext create')} ${dim(`— scaffolding ${name}`)}\n`);
+
+  const files = scaffoldFiles(name);
+  await Promise.all(
+    Object.entries(files).map(([file, source]) => Bun.write(path.join(target, file), source)),
+  );
+  for (const file of Object.keys(files)) console.log(`  ${green('+')} ${dim(file)}`);
+
+  let installed = false;
+  if (options.install) {
+    console.log('');
+    installed = await install(target, dir);
+  }
+
+  printNextSteps(dir, installed);
+}
+
+// npm package name rules: lowercase, url-safe, no leading dot/underscore.
+function sanitizePackageName(raw: string) {
+  const name = raw
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[-._]+|[-._]+$/g, '');
+  return name || 'pnext-app';
+}
+
+async function install(target: string, dir: string) {
+  const stop = spinner('Installing dependencies...');
+  const start = Bun.nanoseconds();
+  const proc = Bun.spawn(['bun', 'install'], { cwd: target, stdout: 'pipe', stderr: 'pipe' });
+  // Drain both pipes: an unread pipe can fill and stall the child.
+  const [stderr, , code] = await Promise.all([
+    new Response(proc.stderr).text(),
+    new Response(proc.stdout).text(),
+    proc.exited,
+  ]);
+  stop();
+
+  if (code === 0) {
+    const durationMs = (Bun.nanoseconds() - start) / 1e6;
+    console.log(`${green('✓')} ${bold('Installed dependencies')} ${dim(`in ${formatDuration(durationMs)}`)}`);
+    return true;
+  }
+  console.log(`${dim('Install failed. Run it manually:')}`);
+  console.log(`  ${cyan('cd')} ${dir}`);
+  console.log(`  ${cyan('bun install')}`);
+  if (stderr.trim()) console.log(dim(stderr.trim()));
+  return false;
+}
+
+/** Braille spinner, TTY-only; a plain line prints once and stays put otherwise. */
+function spinner(label: string) {
+  if (!process.stdout.isTTY) {
+    console.log(label);
+    return () => undefined;
+  }
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let frame = 0;
+  process.stdout.write(`${cyan(frames[0]!)} ${label}`);
+  const timer = setInterval(() => {
+    frame = (frame + 1) % frames.length;
+    process.stdout.write(`\r${cyan(frames[frame]!)} ${label}`);
+  }, 80);
+  return () => {
+    clearInterval(timer);
+    process.stdout.write('\r\x1b[K');
+  };
+}
+
+function formatDuration(durationMs: number) {
+  const totalSeconds = Math.max(0, durationMs) / 1000;
+  return `${totalSeconds.toFixed(totalSeconds < 10 ? 2 : 1)}s`;
+}
+
+function printNextSteps(dir: string, installed: boolean) {
+  const commands = installed ? [`cd ${dir}`, 'bun dev'] : [`cd ${dir}`, 'bun install', 'bun dev'];
+  const title = 'Next steps';
+  const width = Math.max(title.length, ...commands.map(c => c.length)) + 2;
+  const row = (text: string, colorFn: (s: string) => string = s => s) =>
+    `${dim('│')} ${colorFn(text.padEnd(width))} ${dim('│')}`;
+
+  console.log('');
+  console.log(dim(`┌${'─'.repeat(width + 2)}┐`));
+  console.log(row(title, bold));
+  console.log(row(''));
+  for (const cmd of commands) console.log(row(cmd, cyan));
+  console.log(dim(`└${'─'.repeat(width + 2)}┘`));
+}
+
+function scaffoldFiles(name: string): Record<string, string> {
+  return {
+    'package.json': `${JSON.stringify(
+      {
+        name,
+        private: true,
+        scripts: { dev: 'pnext dev', build: 'pnext build', start: 'pnext start', analyze: 'pnext analyze' },
+        dependencies: { preact: '^10' },
+        devDependencies: { '@wular/pnext': '^0.0.1', typescript: '^5', '@types/bun': '^1' },
+      },
+      null,
+      2,
+    )}\n`,
+    'pnext.config.ts': `// See node_modules/@wular/pnext/reference/config.md for available options.\nexport default {};\n`,
+    'tsconfig.json': `${JSON.stringify(
+      {
+        extends: '@wular/pnext/config/ts/react.json',
+        compilerOptions: { jsxImportSource: 'preact', paths: { '#gen/*': ['./.pnext/types/*'] } },
+        include: ['**/*.ts', '**/*.tsx', '.pnext/types/**/*.ts'],
+      },
+      null,
+      2,
+    )}\n`,
+    'app/layout.tsx': `import type { LayoutProps } from '@wular/pnext';\nimport './globals.css';\n\nexport const metadata = {\n  title: '${name}',\n};\n\nexport default function RootLayout({ children }: LayoutProps) {\n  return (\n    <html>\n      <body>{children}</body>\n    </html>\n  );\n}\n`,
+    'app/page.tsx': `import Counter from './counter';\n\nexport default async function Home() {\n  return (\n    <>\n      <h1>Welcome to ${name}</h1>\n      <p>Edit app/page.tsx to get started.</p>\n      <Counter />\n    </>\n  );\n}\n`,
+    'app/counter.tsx': `'use client';\n\nimport { useState } from 'preact/hooks';\n\nexport default function Counter() {\n  const [count, setCount] = useState(0);\n  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;\n}\n`,
+    'app/globals.css': `body {\n  margin: 0;\n  font-family: system-ui, sans-serif;\n}\n`,
+    '.gitignore': `node_modules\n.pnext\n`,
+    'README.md': `# ${name}\n\nA pnext app.\n\n\`\`\`\nbun install\nbun dev\n\`\`\`\n\nDocs: node_modules/@wular/pnext/reference/overview.md\n`,
+  };
+}

package/src/cli/dev.ts

@@ -57,6 +57,12 @@ export async function dev(options: DevOptions = {}) {
   const url = `http://${browserHost(hostname)}:${server.port ?? port}`;
   printServerReady({ mode: 'dev', hostname, port: server.port ?? port, elapsedMs });
   printBootTrace();
+  // Boot compiles nothing (config loads natively), so the first compile would pay esbuild's service
+  // spawn. Warm it here, after the banner - readiness must not wait on it. PNEXT_DEV_ESBUILD_WARM=0 opts out.
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  if (process.env.PNEXT_DEV_ESBUILD_WARM !== '0') {
+    void import('../utils/esbuild').then(module => module.warmEsbuildService());
+  }
   registerShutdown(server);
   watchServerMemory(server);
   watchStaleModules(server);

package/src/cli/index.ts

@@ -33,15 +33,26 @@ try {
       buildMode: buildModeOption(args),
       debugPrerender: args.includes('--debug-prerender'),
     });
+    // A live CSS worker thread races Bun's exit teardown (Linux: silent exit 1
+    // after a successful build); stop it before force-exiting.
+    await (await import('../css/build')).stopCssWorker();
     // Nothing here keeps the event loop alive on success, but a project's
     // next.config can (e.g. a stray setInterval) and Next's own `next build`
     // force-exits regardless of such handles. Do the same so `build` always
     // terminates once buildProject resolves.
     process.exit(0);
   } else if (command === 'start') {
-    const { start } = await import('./start');
+    const root = positionalRoot(args);
+    // The build emits src/cli/start.ts prebundled into one file; parsing that
+    // instead of walking the framework's source graph is most of `start`'s
+    // spawn→first-200. Absent (no build yet, custom outDir) → source path.
+    const { prebuiltServerEntry } = await import('./server-entry');
+    const prebuilt = prebuiltServerEntry(root);
+    const { start } = prebuilt
+      ? ((await import(prebuilt)) as typeof import('./start'))
+      : await import('./start');
     await start({
-      root: positionalRoot(args),
+      root,
       port: optionNumber(args, '--port'),
       hostname: optionString(args, '--hostname'),
     });
@@ -67,13 +78,24 @@ try {
     // Like `next typegen`, exit even when the loaded next.config leaves open
     // handles (timers/connections) alive — a one-shot command must not hang.
     process.exit(0);
+  } else if (command === 'create') {
+    const { createApp } = await import('./create');
+    await createApp(positionals(args)[0], { install: !args.includes('--no-install') });
+    process.exit(0);
+  } else if (command === 'migrate') {
+    const { migrateApp } = await import('./migrate');
+    const code = await migrateApp(positionalRoot(args), { dryRun: args.includes('--dry-run') });
+    process.exit(code);
   } else {
     printHelp();
     process.exit(command ? 1 : 0);
   }
 } catch (error) {
   const formatted = formatCliError(error);
-  console.error(formatted.message);
+  // A blank formatted message exits 1 with no explanation; fall back to the
+  // raw error so the failure is never silent.
+  if (formatted.message.trim()) console.error(formatted.message);
+  else console.error(error instanceof Error ? (error.stack ?? `${error.name}: ${error.message}`) : String(error));
   if (formatted.trace) console.log(`\n${formatted.trace}`);
   process.exit(1);
 }
@@ -192,5 +214,7 @@ function printHelp() {
 pnext build [directory] [--adapter vercel] [--verbose]
 pnext start [directory] [--port 3000] [--hostname 127.0.0.1]
 pnext analyze [route] [directory] [--brotli] [--files] [--json]
-pnext typegen [directory]`);
+pnext typegen [directory]
+pnext create <directory> [--no-install]
+pnext migrate [directory] [--dry-run]`);
 }

package/src/cli/migrate/index.ts

@@ -0,0 +1,96 @@
+// `pnext migrate [directory] [--dry-run]` — converts a Next.js app in place.
+//
+// Only structured, safe edits are applied (package.json, tsconfig.json,
+// pnext.config.ts, .gitignore, next-env.d.ts). Application source is never
+// rewritten: it is scanned and reported so the user stays in control.
+
+import { existsSync } from 'node:fs';
+import { appendFile, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { bold } from '../../utils/ansi';
+import { migratePackageJson, readPackageJson } from './package-json';
+import { emptyResult, printHeader, printResult, type MigrationResult } from './report';
+import { scanSources } from './scan';
+import { withSpinner } from './spinner';
+import { migrateTsconfig } from './tsconfig';
+
+const NEXT_CONFIG_FILES = ['next.config.ts', 'next.config.js', 'next.config.mjs', 'next.config.cjs'];
+const PNEXT_CONFIG_FILES = ['pnext.config.ts', 'pnext.config.js', 'pnext.config.mjs'];
+
+export async function migrateApp(directory: string | undefined, options: { dryRun: boolean }) {
+  const root = path.resolve(directory ?? process.cwd());
+  const pkg = await readPackageJson(root);
+  const hasNextDependency = Boolean(
+    pkg &&
+      (hasDependency(pkg.dependencies, 'next') || hasDependency(pkg.devDependencies, 'next')),
+  );
+  const hasNextConfig = NEXT_CONFIG_FILES.some(name => existsSync(path.join(root, name)));
+
+  if (!hasNextDependency && !hasNextConfig) {
+    console.error(
+      `${bold('Not a Next.js app')}: ${root}\n` +
+        `  - ${pkg ? 'package.json has no "next" dependency' : 'no readable package.json'}\n` +
+        '  - no next.config.{ts,js,mjs,cjs}',
+    );
+    return 1;
+  }
+
+  printHeader(root, options.dryRun);
+  const result = emptyResult();
+  if (pkg) await migratePackageJson(root, pkg, result, options.dryRun);
+  await createPnextConfig(root, result, options.dryRun);
+  await migrateTsconfig(root, result, options.dryRun);
+  await removeNextEnv(root, result, options.dryRun);
+  await updateGitignore(root, result, options.dryRun);
+  await withSpinner('Scanning sources ...', () => scanSources(root, result));
+
+  printResult(result, { install: installCommand(root) });
+  return 0;
+}
+
+async function createPnextConfig(root: string, result: MigrationResult, dryRun: boolean) {
+  const existing = PNEXT_CONFIG_FILES.find(name => existsSync(path.join(root, name)));
+  if (existing) {
+    result.reports.push({
+      title: `${existing} already exists`,
+      detail: 'Make sure it sets compat: { next: true }. See reference/compat.md.',
+    });
+    return;
+  }
+  if (!dryRun) {
+    await writeFile(
+      path.join(root, 'pnext.config.ts'),
+      'export default { compat: { next: true } };\n',
+    );
+  }
+  result.edits.push({ file: 'pnext.config.ts', description: 'created with compat.next enabled' });
+}
+
+async function removeNextEnv(root: string, result: MigrationResult, dryRun: boolean) {
+  const file = path.join(root, 'next-env.d.ts');
+  if (!existsSync(file)) return;
+  if (!dryRun) await rm(file);
+  result.edits.push({ file: 'next-env.d.ts', description: 'deleted' });
+}
+
+async function updateGitignore(root: string, result: MigrationResult, dryRun: boolean) {
+  const file = path.join(root, '.gitignore');
+  if (!existsSync(file)) return;
+  const text = await readFile(file, 'utf8');
+  if (text.split(/\r?\n/).some(line => line.trim() === '.pnext/')) return;
+  if (!dryRun) await appendFile(file, `${text.endsWith('\n') || text === '' ? '' : '\n'}.pnext/\n`);
+  result.edits.push({ file: '.gitignore', description: 'appended .pnext/' });
+}
+
+function installCommand(root: string) {
+  if (existsSync(path.join(root, 'bun.lock')) || existsSync(path.join(root, 'bun.lockb'))) {
+    return 'bun install';
+  }
+  if (existsSync(path.join(root, 'pnpm-lock.yaml'))) return 'pnpm install';
+  if (existsSync(path.join(root, 'yarn.lock'))) return 'yarn';
+  return 'npm install';
+}
+
+function hasDependency(bucket: unknown, name: string) {
+  return typeof bucket === 'object' && bucket !== null && name in bucket;
+}

package/src/cli/migrate/package-json.ts

@@ -0,0 +1,183 @@
+// package.json rewriting: scripts and dependencies. Structured edit only —
+// JSON.parse -> mutate -> stringify, which preserves key insertion order.
+
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { MigrationResult } from './report';
+
+const SEPARATORS = new Set(['&&', '||', ';', '|', '&']);
+const MAPPED_SUBCOMMANDS = new Set(['dev', 'build', 'start', 'typegen']);
+const DROPPED_FLAGS = new Set(['--turbo', '--turbopack']);
+
+type Json = Record<string, unknown>;
+
+/**
+ * Rewrite `next` only where it is a command word: the first token of the
+ * script or the first token after a shell separator. Substrings like
+ * `nextron build` or `npx next-sitemap` are never touched.
+ */
+export function rewriteScript(script: string): { script: string; reports: string[] } {
+  const tokens = script.split(/\s+/).filter(Boolean);
+  const reports: string[] = [];
+  const out: string[] = [];
+  let commandStart = true;
+  let changed = false;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index]!;
+    if (SEPARATORS.has(token)) {
+      out.push(token);
+      commandStart = true;
+      continue;
+    }
+    // Env-var prefixes (NODE_OPTIONS=x next dev) don't end the command position.
+    if (commandStart && /^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) {
+      out.push(token);
+      continue;
+    }
+    if (!commandStart || token !== 'next') {
+      out.push(token);
+      commandStart = false;
+      continue;
+    }
+
+    let end = index + 1;
+    while (end < tokens.length && !SEPARATORS.has(tokens[end]!)) end += 1;
+    const subcommand = tokens[index + 1];
+    const rest = tokens.slice(index + 2, end);
+
+    if (subcommand && MAPPED_SUBCOMMANDS.has(subcommand)) {
+      out.push('pnext', subcommand, ...translateFlags(subcommand, rest));
+      changed = true;
+    } else if (subcommand === 'lint') {
+      out.push(...tokens.slice(index, end));
+      reports.push('`next lint` left as-is — pnext has no lint command; run eslint directly.');
+    } else {
+      out.push(...tokens.slice(index, end));
+      const command = subcommand ? `next ${subcommand}` : 'next';
+      reports.push(`\`${command}\` has no pnext equivalent — left as-is.`);
+    }
+    index = end - 1;
+    commandStart = false;
+  }
+
+  return { script: changed ? out.join(' ') : script, reports };
+}
+
+function translateFlags(subcommand: string, rest: string[]) {
+  const out: string[] = [];
+  for (const flag of rest) {
+    if (DROPPED_FLAGS.has(flag)) continue;
+    if (flag === '-p' && (subcommand === 'dev' || subcommand === 'start')) {
+      out.push('--port');
+      continue;
+    }
+    out.push(flag);
+  }
+  return out;
+}
+
+export async function migratePackageJson(
+  root: string,
+  pkg: Json,
+  result: MigrationResult,
+  dryRun: boolean,
+) {
+  const scripts = isObject(pkg.scripts) ? pkg.scripts : undefined;
+  if (scripts) {
+    const rewritten: string[] = [];
+    for (const [name, value] of Object.entries(scripts)) {
+      if (typeof value !== 'string') continue;
+      const { script, reports } = rewriteScript(value);
+      if (script !== value) {
+        scripts[name] = script;
+        rewritten.push(`${name}: ${value} → ${script}`);
+      }
+      for (const detail of reports) {
+        result.reports.push({ title: `package.json script "${name}"`, detail });
+      }
+    }
+    if (rewritten.length > 0) {
+      result.edits.push({
+        file: 'package.json',
+        description: `scripts rewritten (${rewritten.length})`,
+        details: rewritten,
+      });
+    }
+  }
+
+  const dependencies = ensureObject(pkg, 'dependencies');
+  const devDependencies = ensureObject(pkg, 'devDependencies');
+
+  for (const [field, bucket] of [
+    ['dependencies', dependencies],
+    ['devDependencies', devDependencies],
+  ] as const) {
+    if ('next' in bucket) {
+      delete bucket.next;
+      result.edits.push({
+        file: 'package.json',
+        description: 'next removed',
+        details: [`next removed from ${field}`],
+      });
+    }
+  }
+  if (!('@wular/pnext' in devDependencies) && !('@wular/pnext' in dependencies)) {
+    devDependencies['@wular/pnext'] = '^0.0.1';
+    result.edits.push({
+      file: 'package.json',
+      description: '@wular/pnext added',
+      details: ['devDependencies: @wular/pnext ^0.0.1'],
+    });
+  }
+  if (!('preact' in dependencies) && !('preact' in devDependencies)) {
+    dependencies.preact = '^10';
+    result.edits.push({
+      file: 'package.json',
+      description: 'preact added',
+      details: ['dependencies: preact ^10 (react/react-dom kept — compat aliases them)'],
+    });
+  }
+
+  const leftovers = [...Object.keys(dependencies), ...Object.keys(devDependencies)].filter(
+    name => name === 'eslint-config-next' || name.startsWith('@next/'),
+  );
+  if (leftovers.length > 0) {
+    result.reports.push({
+      title: 'Next-specific packages still installed',
+      detail: 'Optional cleanup — these are unused under pnext. See reference/compat.md.',
+      files: leftovers,
+    });
+  }
+
+  pruneEmpty(pkg, 'dependencies');
+  pruneEmpty(pkg, 'devDependencies');
+
+  if (!dryRun) {
+    await writeFile(path.join(root, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
+  }
+}
+
+export async function readPackageJson(root: string): Promise<Json | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8')) as unknown;
+    return isObject(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isObject(value: unknown): value is Json {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// Create the bucket in place so an existing key keeps its position.
+function ensureObject(pkg: Json, key: string): Json {
+  if (!isObject(pkg[key])) pkg[key] = {};
+  return pkg[key] as Json;
+}
+
+function pruneEmpty(pkg: Json, key: string) {
+  const value = pkg[key];
+  if (isObject(value) && Object.keys(value).length === 0) delete pkg[key];
+}