@wular/pnext 0.0.1

package/src/css/postcss.ts

@@ -0,0 +1,236 @@
+// The app's postcss/Tailwind pipeline. Lives in its own module because it runs
+// on the CSS worker thread (./worker.ts) rather than the event loop:
+// Tailwind v4's postcss plugin is synchronous CPU work — its oxide scan and
+// compile starved every concurrent request while it ran in-process.
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { readText } from '../utils/fs';
+
+export interface PostcssOptions {
+  dev?: boolean;
+  /** pnext's output directory — kept out of Tailwind's content scan. */
+  outDir?: string;
+}
+
+// One long-lived processor per root+mode. Keeping it alive is what makes dev fast: Tailwind v4's postcss
+// plugin holds a compiler and an oxide scanner per input file, so rebuilds are incremental candidate scans
+// instead of a CLI spawn plus a full project re-scan. It also means other plugins in the config actually
+// execute - the old CLI path treated postcss.config purely as a Tailwind trigger. Config-file edits need a
+// dev-server restart; Tailwind tracks its own dependencies and refreshes them itself.
+const postcssProcessors = new Map<string, Promise<LoadedPostcss | undefined>>();
+
+interface PostcssProcessor {
+  process(css: string, options: { from: string; to: string }): PromiseLike<{ css: string }>;
+}
+
+/** A processor plus the `@source not` directives to append for it (if any). */
+interface LoadedPostcss {
+  processor: PostcssProcessor;
+  sources: string;
+}
+
+type PostcssPluginFactory = (options?: unknown) => unknown;
+
+interface PostcssConfig {
+  plugins?: Record<string, unknown> | unknown[];
+}
+
+export function postcssConfigFile(root: string) {
+  for (const file of ['postcss.config.cjs', 'postcss.config.js', 'postcss.config.mjs']) {
+    const full = path.join(root, file);
+    if (existsSync(full)) return full;
+  }
+  return undefined;
+}
+
+/** Build (or reuse) the processor for this root+mode without processing a file. */
+export function loadPostcss(root: string, options: PostcssOptions) {
+  const key = `${root}\0${options.dev ? 'dev' : 'build'}\0${options.outDir ?? ''}`;
+  let processor = postcssProcessors.get(key);
+  if (!processor) {
+    processor = createPostcssProcessor(root, options).catch((error: unknown) => {
+      // Drop failed setups so a fixed config or install is retried.
+      postcssProcessors.delete(key);
+      throw error;
+    });
+    postcssProcessors.set(key, processor);
+  }
+  return processor;
+}
+
+export async function runPostcss(
+  root: string,
+  cssFile: string,
+  options: PostcssOptions,
+  fromSource?: string,
+) {
+  const loaded = await loadPostcss(root, options);
+  if (!loaded) return;
+  // `from` labels the input for postcss plugins' diagnostics/source maps. Point
+  // it at the original CSS source (not the synthesized bundle outfile) so
+  // plugins like `@tailwindcss/postcss` report the real path (e.g. its
+  // `DEBUG=tailwindcss` marker keys off `result.opts.from`). We still write the
+  // processed output back to the bundle outfile via `to`.
+  const from = fromSource ?? cssFile;
+  // The scan directives go last so they don't shift the line numbers plugins
+  // report against the real source; `@source` is order-independent to Tailwind.
+  const result = await loaded.processor.process((await readText(cssFile)) + loaded.sources, {
+    from,
+    to: cssFile,
+  });
+  await writeFile(cssFile, result.css);
+}
+
+async function createPostcssProcessor(root: string, options: PostcssOptions) {
+  const configFile = postcssConfigFile(root);
+  if (!configFile) return undefined;
+  const loaded = (await import(pathToFileURL(configFile).href)) as
+    | PostcssConfig
+    | { default: PostcssConfig };
+  const config = 'default' in loaded && loaded.default ? loaded.default : loaded;
+  const plugins = postcssPlugins(root, config as PostcssConfig, options);
+  if (plugins.length === 0) return undefined;
+  const appRequire = createRequire(path.join(root, 'package.json'));
+  const postcss = interopDefault(resolvePostcss(appRequire)) as (
+    plugins: unknown[],
+  ) => PostcssProcessor;
+  const tailwind = pluginEntries(config as PostcssConfig).some(
+    ([specifier, pluginOptions]) => specifier === '@tailwindcss/postcss' && pluginOptions !== false,
+  );
+  return {
+    processor: postcss(plugins),
+    sources: tailwind ? scanExclusions(root, appRequire, options) : '',
+  };
+}
+
+/**
+ * Tailwind's automatic content detection only skips dependencies and build output when it can read
+ * the project's git ignore rules. Off a git checkout - Docker build contexts, staged copies,
+ * tarball deploys - oxide walks them instead and mints utilities from stale build artifacts.
+ * Excluding these three by name restores that behaviour without narrowing what a correctly-ignored
+ * checkout already scans. Apps that really do keep Tailwind-classed sources in one of them set
+ * `PNEXT_TAILWIND_SCAN_ALL`.
+ */
+function scanExclusions(root: string, appRequire: NodeJS.Require, options: PostcssOptions) {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  if (process.env.PNEXT_TAILWIND_SCAN_ALL) return '';
+  // `@source not` landed in Tailwind 4.1; older versions error on the at-rule.
+  const [major, minor] = packageVersion(appRequire, '@tailwindcss/postcss');
+  if (major < 4 || (major === 4 && minor < 1)) return '';
+  const dirs = ['node_modules', '.next', options.outDir ?? '.pnext'];
+  const excluded = [...new Set(dirs.map(dir => path.resolve(root, dir)))].filter(
+    dir => dir.startsWith(root + path.sep) && existsSync(dir),
+  );
+  if (excluded.length === 0) return '';
+  // Leading and trailing newlines keep the stylesheet's own first and last
+  // lines exactly as they were, so the emitted CSS stays byte-identical.
+  return `\n${excluded
+    .map(dir => `@source not ${JSON.stringify(dir.split(path.sep).join('/'))};`)
+    .join('\n')}\n`;
+}
+
+/** `[major, minor]` of a resolvable package, or `[0, 0]` when unknown. */
+function packageVersion(req: NodeJS.Require, name: string): [number, number] {
+  try {
+    const pkg = JSON.parse(readFileSync(req.resolve(`${name}/package.json`), 'utf8')) as {
+      version?: string;
+    };
+    const [major, minor] = (pkg.version ?? '').split('.');
+    return [Number.parseInt(major ?? '', 10) || 0, Number.parseInt(minor ?? '', 10) || 0];
+  } catch {
+    return [0, 0];
+  }
+}
+
+function pluginEntries(config: PostcssConfig): [unknown, unknown][] {
+  return Array.isArray(config.plugins)
+    ? config.plugins.map(entry =>
+        Array.isArray(entry)
+          ? ([entry[0], entry[1]] as [unknown, unknown])
+          : ([entry, undefined] as [unknown, unknown]),
+      )
+    : Object.entries(config.plugins ?? {});
+}
+
+function postcssPlugins(root: string, config: PostcssConfig, options: PostcssOptions) {
+  const appRequire = createRequire(path.join(root, 'package.json'));
+  const entries = pluginEntries(config);
+
+  const plugins: unknown[] = [];
+  for (const [specifier, pluginOptions] of entries) {
+    if (pluginOptions === false) continue;
+    if (typeof specifier !== 'string') {
+      // Already-instantiated plugin object or factory in an array config.
+      if (specifier) plugins.push(specifier);
+      continue;
+    }
+    const factory = interopDefault(appRequire(specifier) as unknown);
+    const resolvedOptions = pluginOptionsFor(root, specifier, pluginOptions, options);
+    plugins.push(
+      typeof factory === 'function' ? (factory as PostcssPluginFactory)(resolvedOptions) : factory,
+    );
+  }
+  return plugins;
+}
+
+function pluginOptionsFor(
+  root: string,
+  specifier: string,
+  userOptions: unknown,
+  options: PostcssOptions,
+) {
+  if (specifier !== '@tailwindcss/postcss') return userOptions;
+  // Scan candidates from the app root — the bundled css Tailwind reads lives
+  // under .pnext, where a default input-relative scan would find nothing.
+  return {
+    base: root,
+    optimize: options.dev ? false : { minify: true },
+    ...(typeof userOptions === 'object' && userOptions !== null ? userOptions : {}),
+  };
+}
+
+function resolvePostcss(appRequire: NodeJS.Require): unknown {
+  // Next runs the PostCSS pipeline through its OWN bundled PostCSS 8, never the app's copy. That matters
+  // when a legacy plugin dep pins an old major: `postcss-nested@4` declares `postcss@^7` as a regular
+  // dependency, which the package manager hoists to the app's top-level node_modules, so requiring
+  // 'postcss' from the app would return PostCSS 7 and a modern app plugin using the v8 API throws. Prefer
+  // the app's postcss only when it is already v8+, otherwise fall back to pnext's own.
+  let appPostcss: unknown;
+  try {
+    appPostcss = appRequire('postcss');
+    if (packageVersion(appRequire, 'postcss')[0] >= 8) return appPostcss;
+  } catch {
+    // App has no resolvable postcss; fall through to pnext's own / plugin copy.
+  }
+  const ownPostcss = resolveOwnPostcss();
+  if (ownPostcss) return ownPostcss;
+  try {
+    // A Tailwind-based app ships a v8 postcss under its plugin package.
+    const pluginPackage = appRequire.resolve('@tailwindcss/postcss/package.json');
+    return createRequire(pluginPackage)('postcss');
+  } catch {
+    // Last resort: whatever the app resolved (even if <8) — better than nothing.
+    if (appPostcss) return appPostcss;
+    throw new Error('Could not resolve a PostCSS installation for the CSS pipeline.');
+  }
+}
+
+/** pnext's own PostCSS 8 (mirrors Next's bundled copy), or undefined. */
+function resolveOwnPostcss(): unknown {
+  try {
+    const ownRequire = createRequire(import.meta.url);
+    if (packageVersion(ownRequire, 'postcss')[0] >= 8) return ownRequire('postcss');
+  } catch {
+    // pnext's install carries no resolvable postcss; caller falls back.
+  }
+  return undefined;
+}
+
+function interopDefault(mod: unknown): unknown {
+  if (typeof mod === 'function') return mod;
+  if (mod && typeof mod === 'object' && 'default' in mod && mod.default) return mod.default;
+  return mod;
+}

package/src/css/worker.ts

@@ -0,0 +1,34 @@
+// CSS worker entry — runs the postcss/Tailwind pipeline off the event loop.
+// One message per built stylesheet; the processor cache in ./postcss.ts lives
+// here for the worker's lifetime, so Tailwind stays incremental across rebuilds.
+import { loadPostcss, runPostcss } from './postcss';
+export type CssWorkerRequest = { id: number; root: string; dev: boolean; outDir?: string } & (
+  | { kind: 'warm' }
+  | { kind: 'process'; cssFile: string; from?: string }
+);
+
+export interface CssWorkerResponse {
+  id: number;
+  error?: { name: string; message: string; stack?: string };
+}
+
+declare const self: Worker;
+
+self.onmessage = async (event: MessageEvent<CssWorkerRequest>) => {
+  const request = event.data;
+  const reply = (response: CssWorkerResponse) => postMessage(response);
+  try {
+    const options = { dev: request.dev, outDir: request.outDir };
+    if (request.kind === 'warm') await loadPostcss(request.root, options);
+    else await runPostcss(request.root, request.cssFile, options, request.from);
+    reply({ id: request.id });
+  } catch (error) {
+    reply({
+      id: request.id,
+      error:
+        error instanceof Error
+          ? { name: error.name, message: error.message, stack: error.stack }
+          : { name: 'Error', message: String(error) },
+    });
+  }
+};

package/src/dev/client-actions.ts

@@ -0,0 +1,35 @@
+// Client-action bundler seam (CORE - imports ZERO compat).
+//
+// The dev route-client bundle resolves every module into its own `pnext-route-client` esbuild namespace, so
+// a standalone esbuild plugin cannot intercept that graph the way it can a plain client build. This holder
+// is the extension point dev/imports reads to turn a client-side import of a `'use server'` module into the
+// RPC stub, without core statically importing compat/actions.
+//
+// Compat populates it; a pure-core app leaves it unset, and dev/imports treats every module as a normal
+// source module. Mirrors the routing/request-runtime.ts holder pattern.
+
+/** Compat client-action bundler surface dev/imports consults. */
+export interface ClientActionBundler {
+  /**
+   * Ensure the client-action module set is discovered for the active dev import version (a dev reload bumps
+   * it). Awaited before a route-client build so the stub check below sees the current set - the discovery
+   * that used to run inline at startup/reload now happens lazily here. Idempotent per version.
+   */
+  ensureArmed: () => Promise<void>;
+  /** True when `file` is a discovered `'use server'` module (stub it on the client). */
+  isClientActionModule: (file: string) => boolean;
+  /** Generate the client fetch-stub source for an action module file. */
+  stubSource: (file: string) => Promise<string>;
+}
+
+let bundler: ClientActionBundler | undefined;
+
+/** Publish the compat client-action bundler (register-actions). */
+export function setClientActionBundler(next: ClientActionBundler): void {
+  bundler = next;
+}
+
+/** The compat client-action bundler, or undefined for a pure-core app. */
+export function getClientActionBundler(): ClientActionBundler | undefined {
+  return bundler;
+}

package/src/dev/client-chunk-store.ts

@@ -0,0 +1,92 @@
+// Content-addressed store for dev client build output. Generation dirs under
+// cache/client/<key>/ repeat the same chunk bytes across saves (~42% of
+// cache/client measured byte-duplicate on a zero-edit warm-up).
+// Hardlinking each file into a shared store keyed by its own hash collapses
+// duplicates to one inode while every generation dir keeps a normal-looking
+// path; eviction of one generation just drops its link, leaving the others
+// (and the store's own link) intact.
+import { createHash } from 'node:crypto';
+import { link, mkdir, readFile, readdir, rm, stat, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { listFiles } from '../utils/fs';
+
+export function clientChunkStoreDir(outPath: string) {
+  return path.join(outPath, 'cache', 'client-store');
+}
+
+function contentHash(data: Buffer) {
+  return createHash('sha1').update(data).digest('hex');
+}
+
+/**
+ * Replace every file under `dir` with a hardlink into the shared store, deduping
+ * identical content written by unrelated generations. Falls back to a plain
+ * copy when linking fails (e.g. store and outDir on different devices) so the
+ * file always ends up in place either way.
+ */
+export async function contentAddressDir(dir: string, storeDir: string) {
+  await mkdir(storeDir, { recursive: true });
+  const files = await listFiles(dir);
+  await Promise.all(files.map(file => contentAddressFile(file, storeDir)));
+}
+
+async function contentAddressFile(file: string, storeDir: string) {
+  const data = await readFile(file);
+  const storePath = path.join(storeDir, `${contentHash(data)}${path.extname(file)}`);
+  if (!(await pathExists(storePath))) {
+    // Claim the store slot from this file's own bytes: link first (cheap, same
+    // device), and only fall back to a copy if that's impossible. Either way the
+    // original file stays at `file` — nothing below needs to re-link it there.
+    try {
+      await link(file, storePath);
+      return;
+    } catch {
+      await copyFileFallback(file, storePath);
+      return;
+    }
+  }
+  // Store already holds this content: swap the freshly-written file for a link
+  // to the shared inode so duplicate bytes stop being duplicate on disk.
+  try {
+    await unlink(file);
+    await link(storePath, file);
+  } catch {
+    // Cross-device or racing unlink: leave the original file in place, it is
+    // already correct content, just not deduped this time.
+  }
+}
+
+async function copyFileFallback(file: string, storePath: string) {
+  try {
+    const data = await readFile(file);
+    await Bun.write(storePath, data);
+  } catch {
+    // Best-effort: dedup is an optimization, not a correctness requirement.
+  }
+}
+
+async function pathExists(target: string) {
+  return stat(target)
+    .then(() => true)
+    .catch(() => false);
+}
+
+/**
+ * Sweep store entries no generation dir links to anymore. A store file's link count is 1 exactly when the
+ * store's own hardlink is the only one left - every generation that once pointed at it has been evicted.
+ */
+export async function sweepClientChunkStore(storeDir: string) {
+  let entries: string[];
+  try {
+    entries = await readdir(storeDir);
+  } catch {
+    return;
+  }
+  await Promise.allSettled(
+    entries.map(async entry => {
+      const full = path.join(storeDir, entry);
+      const info = await stat(full).catch(() => null);
+      if (info && info.nlink <= 1) await rm(full, { force: true });
+    }),
+  );
+}

package/src/dev/client-key-cache.ts

@@ -0,0 +1,178 @@
+// Persisted client cache keys - the restart half of dev/module-cache.ts. A route's client bundle
+// already lives in a content-keyed out-dir, so a restart never has to rebuild it; deriving that key
+// did, by walking every source the route's client graph reaches and hashing the bytes. The bytes
+// cannot have moved while nothing was watching them *unless* the file did, so this persists the
+// walk's result next to the artifacts it named and re-validates it with one stat per source.
+//
+// The same three-step ladder module-cache uses:
+//   stat matches      -> reuse (the common case, and the only O(1) one)
+//   stat moved        -> read + hash; equal content still reuses the key
+//   content differs   -> full walk, new key, new out-dir
+// so an edit made while the server was not running invalidates, and a touch that changed nothing
+// does not.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { mkdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  clientCacheKeyParts,
+  clientCacheStaticHash,
+  clientSourceHash,
+  type ClientCacheSource,
+} from '../client/build';
+import type { ResolvedConfig } from '../config';
+import type { RouteManifestEntry } from '../types';
+import { writeFileAtomic } from '../utils/fs';
+import { restartCacheEnabled } from './restart-cache';
+
+/** `[file, mtimeMs, size, contentHash]` — the same record shape the module index uses. */
+type SourceEntry = [string, number, number, string];
+
+interface RouteEntry {
+  /** Hash of everything in the key that is not a walked source. */
+  static: string;
+  key: string;
+  files: SourceEntry[];
+}
+
+interface IndexFile {
+  version: number;
+  routes: Record<string, RouteEntry>;
+}
+
+/** Bumped whenever a record's shape changes; an older index is simply ignored. */
+const INDEX_VERSION = 1;
+
+interface KeyCache {
+  file: string;
+  routes: Map<string, RouteEntry>;
+  dirty: boolean;
+  flush?: Timer;
+  retries: number;
+}
+
+const caches = new Map<string, KeyCache>();
+
+function keyCache(config: ResolvedConfig): KeyCache {
+  const file = path.join(config.outPath, 'cache', 'client', 'keys.json');
+  const existing = caches.get(file);
+  if (existing) return existing;
+  const created: KeyCache = { file, routes: readIndex(file), dirty: false, retries: 0 };
+  caches.set(file, created);
+  // A short-lived process can exit before the debounce fires; without this its
+  // walk would not survive to the next boot.
+  process.on('exit', () => {
+    if (!created.dirty) return;
+    created.dirty = false;
+    try {
+      writeFileSync(created.file, serializeIndex(created.routes));
+    } catch {
+      // Best effort: a missing index only costs the next boot a walk.
+    }
+  });
+  return created;
+}
+
+/**
+ * This route's client cache key, from the persisted walk when every source it
+ * named still has the content it was named for, and from a fresh walk otherwise.
+ */
+export async function devClientCacheKey(
+  config: ResolvedConfig,
+  route: RouteManifestEntry,
+  nextCompat: boolean,
+): Promise<string> {
+  if (!restartCacheEnabled()) return (await clientCacheKeyParts(route, nextCompat, config)).key;
+  const cache = keyCache(config);
+  const staticHash = await clientCacheStaticHash(route, nextCompat, config);
+  const entry = cache.routes.get(route.id);
+  if (entry?.static === staticHash) {
+    const revalidated = await revalidate(entry.files);
+    if (revalidated) {
+      // Only the stats moved (a touch, a checkout): keep the key, record the
+      // new stats so the next boot takes the O(1) path again.
+      if (revalidated !== entry.files) {
+        cache.routes.set(route.id, { ...entry, files: revalidated });
+        persist(cache);
+      }
+      return entry.key;
+    }
+  }
+
+  const parts = await clientCacheKeyParts(route, nextCompat, config, staticHash);
+  cache.routes.set(route.id, {
+    static: parts.staticHash,
+    key: parts.key,
+    files: parts.sources.map(sourceEntry),
+  });
+  persist(cache);
+  return parts.key;
+}
+
+function sourceEntry(source: ClientCacheSource): SourceEntry {
+  return [source.file, source.mtimeMs, source.size, source.hash];
+}
+
+/**
+ * The recorded sources, re-stated: `files` itself when nothing moved, a fresh list when only stats moved,
+ * `undefined` when any content actually differs - or a source is gone, which is the same thing, since the
+ * walk has to run again.
+ */
+async function revalidate(files: SourceEntry[]): Promise<SourceEntry[] | undefined> {
+  let moved = false;
+  const checked = await Promise.all(
+    files.map(async (entry): Promise<SourceEntry | undefined> => {
+      const [file, mtimeMs, size, hash] = entry;
+      const stats = await stat(file).catch(() => undefined);
+      if (!stats) return undefined;
+      if (stats.mtimeMs === mtimeMs && stats.size === size) return entry;
+      const source = await readFile(file, 'utf8').catch(() => undefined);
+      if (source === undefined || clientSourceHash(source) !== hash) return undefined;
+      moved = true;
+      return [file, stats.mtimeMs, stats.size, hash];
+    }),
+  );
+  if (checked.some(entry => entry === undefined)) return undefined;
+  return moved ? (checked as SourceEntry[]) : files;
+}
+
+function persist(cache: KeyCache) {
+  cache.dirty = true;
+  if (cache.flush) return;
+  cache.flush = setTimeout(async () => {
+    cache.flush = undefined;
+    if (!cache.dirty) return;
+    const contents = serializeIndex(cache.routes);
+    try {
+      await mkdir(path.dirname(cache.file), { recursive: true });
+      await writeFileAtomic(cache.file, contents);
+      cache.dirty = false;
+    } catch {
+      // A write that lost a race with a cache wipe must not look persisted.
+      if (++cache.retries < 3) persist(cache);
+    }
+  }, 50);
+  // The index is a pure optimization; never hold the process open for it.
+  cache.flush.unref?.();
+}
+
+function readIndex(file: string) {
+  const routes = new Map<string, RouteEntry>();
+  let parsed: IndexFile | undefined;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8')) as IndexFile;
+  } catch {
+    return routes;
+  }
+  if (parsed?.version !== INDEX_VERSION) return routes;
+  for (const [id, entry] of Object.entries(parsed.routes ?? {})) {
+    if (entry?.key && entry.static && Array.isArray(entry.files)) routes.set(id, entry);
+  }
+  return routes;
+}
+
+function serializeIndex(routes: Map<string, RouteEntry>) {
+  return JSON.stringify({
+    version: INDEX_VERSION,
+    routes: Object.fromEntries(routes),
+  } satisfies IndexFile);
+}