@wular/pnext 0.0.1

package/src/compat-bootstrap.ts

@@ -0,0 +1,67 @@
+// THE SINGLE COMPAT SEAM (CORE). The ONLY core module permitted a reference to the compat layer,
+// and it does so through gated dynamic imports. Every other core file imports ZERO compat; they
+// read behavior from the extension registry (src/extensions.ts) which compat populates here.
+//
+// Registration comes in two tiers, because importing the compat implementation graph costs far
+// more than running the registrars themselves:
+//
+//   bootstrapCompatBoot(config) - loads ./compat/register/boot ONLY: the facts core reads before
+//     it compiles anything (route conventions, page/CSS extensions, bare-specifier aliases, proxy
+//     file names, lifecycle hooks).
+//   bootstrapCompat(config)     - loads ./compat/register/index: the full graph and every remaining
+//     registrar. Chains the boot tier first. `{ serve: true }` drops the build-only domains.
+//
+// Composition roots: build() and start() take the full tier; dev takes the boot tier at startup and
+// the full tier on the first request. Both are idempotent under repeated and concurrent calls.
+//
+// The enablement gate is inlined here (a pure read of config.compat) rather than imported from
+// compat, so this file carries no static edge into compat. It must stay in sync with
+// compat/index.ts reactCompatEnabled/nextCompatEnabled.
+
+import type { ResolvedConfig } from './config';
+import { onExtensionHostReset } from './extensions';
+
+/** True when either Next or React compatibility (or the React compiler) is on. */
+function compatEnabled(config: ResolvedConfig): boolean {
+  const compat = config.compat;
+  return Boolean(compat?.next || compat?.react || compat?.reactCompiler);
+}
+
+let bootRegistration: Promise<void> | undefined;
+let registration: Promise<void> | undefined;
+
+// A fresh host has none of compat's registrations, so the "already registered"
+// memo has to go with it — otherwise the next bootstrap call is a no-op and the
+// host stays empty for the rest of the process.
+onExtensionHostReset(() => {
+  bootRegistration = undefined;
+  registration = undefined;
+});
+
+/**
+ * Register the boot tier: the compat facts core consults before the first
+ * compile. No-op (and no compat code loaded) for a pure-core app.
+ */
+export function bootstrapCompatBoot(config: ResolvedConfig): Promise<void> {
+  if (!compatEnabled(config)) return Promise.resolve();
+  bootRegistration ??= import('./compat/register/boot').then(module =>
+    module.registerCompatBootExtensions(config),
+  );
+  return bootRegistration;
+}
+
+/**
+ * Populate the core extension registries with compat behavior when compat is enabled. No-op, and no compat
+ * code loaded, for a pure-core app. Idempotent - the underlying dynamic import and registration run at most
+ * once per process.
+ */
+export function bootstrapCompat(
+  config: ResolvedConfig,
+  options: { serve?: boolean } = {},
+): Promise<void> {
+  if (!compatEnabled(config)) return Promise.resolve();
+  registration ??= bootstrapCompatBoot(config)
+    .then(() => import('./compat/register/index'))
+    .then(module => module.registerCompatExtensions(config, options));
+  return registration;
+}

package/src/config.ts

@@ -0,0 +1,218 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import path from 'node:path';
+import { loadEnv } from './env';
+import { findWorkspaceRoot } from './resolve/imports';
+import type { PNextConfig } from './types';
+import { setCacheComponents } from './ppr';
+
+export type ResolvedConfig = Required<Pick<PNextConfig, 'outDir' | 'basePath'>> &
+  Omit<PNextConfig, 'outDir' | 'basePath'> & {
+    root: string;
+    workspaceRoot: string;
+    appDir: string;
+    publicDir: 'public';
+    appPath: string;
+    publicPath: string;
+    outPath: string;
+  };
+
+const defaultConfig = {
+  outDir: '.pnext',
+  basePath: '',
+} satisfies Required<Pick<PNextConfig, 'outDir' | 'basePath'>>;
+
+// configSources seam. Core owns the shape; compat populates it.
+//
+// A configSource loads an external framework config (Next's next.config.*), applies its side effects (env,
+// say), and returns the subset that maps onto pnext's core config. loadConfig invokes the registered
+// source, if any, after resolving the pnext config and merges its overrides on top of the defaults.
+//
+// The Next source is registered from src/compat/register/config.ts. Because loadConfig runs at each
+// composition root *before* bootstrapCompat, it also lazily loads that source itself through one gated
+// dynamic import when compat.next is enabled - mirroring the compat-bootstrap gate so core keeps no static
+// edge into compat.
+export interface ConfigSourceOverrides {
+  basePath?: string;
+  trailingSlash?: boolean;
+  skipTrailingSlashRedirect?: boolean;
+  outDir?: string;
+  assetPrefix?: string;
+  productionBrowserSourceMaps?: boolean;
+}
+export type ConfigSource = (
+  root: string,
+  options: { dev?: boolean },
+) => Promise<ConfigSourceOverrides>;
+
+let configSource: ConfigSource | undefined;
+
+export function registerConfigSource(source: ConfigSource): void {
+  configSource = source;
+}
+
+async function resolveConfigSource(
+  config: PNextConfig,
+  root: string,
+  options: { dev?: boolean },
+): Promise<ConfigSourceOverrides> {
+  if (!config.compat?.next) return {};
+  if (!configSource) {
+    await import('./compat/register/config').then(module => module.registerConfigSource());
+  }
+  if (!configSource) return {};
+  return configSource(root, options);
+}
+
+export async function loadConfig(
+  rootInput = process.cwd(),
+  options: { dev?: boolean } = {},
+): Promise<ResolvedConfig> {
+  const root = canonicalRoot(path.resolve(rootInput));
+  await loadEnv(root, options);
+  const configPath = path.join(root, 'pnext.config.ts');
+  const loadedConfig = existsSync(configPath)
+    ? ((await import(pathToFileHref(configPath))) as { default?: PNextConfig })
+    : {};
+  const config: PNextConfig = {
+    ...(loadedConfig.default ?? {}),
+    // eslint-disable-next-line turbo/no-undeclared-env-vars
+    ...(process.env.PNEXT_COMPAT === 'next'
+      ? { compat: { ...(loadedConfig.default?.compat ?? {}), next: true } }
+      : {}),
+  };
+  // cacheComponents is a per-app flag on a process-global cell: clear it before
+  // the next.config source re-derives it, so a pure-core (or flag-off) app
+  // loaded after a cacheComponents app never inherits the previous build's flag.
+  setCacheComponents(false);
+  const sourceOverrides = stripUndefined(await resolveConfigSource(config, root, options));
+  const merged = { ...defaultConfig, ...config, ...sourceOverrides };
+  const appPath = await resolveAppPath(root, config);
+  const workspaceRoot = canonicalRoot(
+    config.workspaceRoot
+      ? path.resolve(root, config.workspaceRoot)
+      : (findWorkspaceRoot(root) ?? root),
+  );
+
+  return {
+    ...config,
+    trailingSlash: merged.trailingSlash ?? config.trailingSlash,
+    productionBrowserSourceMaps:
+      merged.productionBrowserSourceMaps ?? config.productionBrowserSourceMaps,
+    skipTrailingSlashRedirect: merged.skipTrailingSlashRedirect ?? config.skipTrailingSlashRedirect,
+    appDir: path.relative(root, appPath),
+    publicDir: 'public',
+    outDir: merged.outDir,
+    basePath: merged.basePath,
+    // Assets are addressed under basePath (the server 404s outside it), so an
+    // app that sets basePath without an explicit assetPrefix serves assets at
+    // `${basePath}/assets/...` — Next's default (assetPrefix falls back to
+    // basePath).
+    assetPrefix: merged.assetPrefix ?? merged.basePath,
+    root,
+    workspaceRoot,
+    appPath,
+    publicPath: path.resolve(root, 'public'),
+    outPath: path.resolve(root, merged.outDir),
+  };
+}
+
+// Relative-import resolution realpaths the importing file (so a materialized shim resolves `./sibling`
+// against real source), so every containment check against root/workspaceRoot compares realpaths.
+// Canonicalize the roots to match - otherwise an app served through a symlinked directory (a macOS
+// tmpdir, a pnpm-linked checkout) reads as "outside the workspace" and its own source files stop
+// resolving. A no-op when the path holds no symlinks.
+function canonicalRoot(dir: string) {
+  try {
+    return realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
+function stripUndefined<T extends object>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as T;
+}
+
+export function pathToFileHref(filePath: string) {
+  // pathToFileURL percent-encodes literal special characters (notably `%`, so a
+  // directory physically named `%5Ffoo` on disk stays `%255Ffoo` in the href and
+  // import() decodes it back to the literal `%5Ffoo` rather than to `_foo`).
+  return pathToFileURL(path.resolve(filePath)).href;
+}
+
+export function publicEnvDefines() {
+  return Object.fromEntries(
+    [
+      // eslint-disable-next-line turbo/no-undeclared-env-vars
+      ['NODE_ENV', process.env.NODE_ENV ?? 'production'],
+      ...Object.entries(process.env).filter(
+        ([key]) => key.startsWith('NEXT_PUBLIC_') || key.startsWith('PNEXT_PUBLIC_'),
+      ),
+    ].map(([key, value]) => [
+      `process.env.${key}`,
+      value === undefined ? 'undefined' : JSON.stringify(value),
+    ]),
+  );
+}
+
+type FrameworkRuntimeAlias =
+  | 'preact'
+  | 'preact/hooks'
+  | 'preact/compat'
+  | 'preact/compat/client'
+  | 'preact/jsx-runtime'
+  | 'preact/jsx-dev-runtime'
+  | 'react-compiler-runtime';
+
+export type CompatAliasTarget = 'server' | 'client';
+
+/**
+ * Seven `import.meta.resolve` calls against the framework's OWN install - the answer cannot change for the
+ * life of the process, and every esbuild build builds an alias map (a vendor pass runs hundreds of those).
+ */
+let frameworkRuntimeAliases: Record<FrameworkRuntimeAlias, string> | undefined;
+
+export function frameworkRuntimeAliasEntries(): Record<FrameworkRuntimeAlias, string> {
+  frameworkRuntimeAliases ??= {
+    preact: resolveRuntimeModule('preact'),
+    'preact/hooks': resolveRuntimeModule('preact/hooks'),
+    'preact/compat': resolveRuntimeModule('preact/compat'),
+    'preact/compat/client': resolveRuntimeModule('preact/compat/client'),
+    'preact/jsx-runtime': resolveRuntimeModule('preact/jsx-runtime'),
+    'preact/jsx-dev-runtime': resolveRuntimeModule('preact/jsx-dev-runtime'),
+    'react-compiler-runtime': resolveRuntimeModule('react-compiler-runtime'),
+  };
+  return frameworkRuntimeAliases;
+}
+
+function resolveRuntimeModule(specifier: string) {
+  return fileURLToPath(import.meta.resolve(specifier));
+}
+
+export function pnextAliases(target: CompatAliasTarget): Record<string, string> {
+  if (target !== 'client') return {};
+  return {
+    '@wular/pnext/cache': path.resolve(import.meta.dirname, 'api/client-cache.ts'),
+  };
+}
+
+async function resolveAppPath(root: string, config: PNextConfig) {
+  const rootApp = path.join(root, 'app');
+  if (config.compat?.next) {
+    const pagesPath = path.join(root, 'pages');
+    const hasPages = existsSync(pagesPath);
+    if (existsSync(rootApp)) {
+      if (hasPages) {
+        const { materializePagesApp } = await import('./compat/pages');
+        const hybrid = await materializePagesApp(root);
+        if (hybrid) return hybrid;
+      }
+      return rootApp;
+    }
+    const { materializePagesApp } = await import('./compat/pages');
+    const pagesApp = await materializePagesApp(root);
+    if (pagesApp) return pagesApp;
+  } else if (existsSync(rootApp)) return rootApp;
+  return path.join(root, 'src', 'app');
+}