@wular/pnext 0.0.1

package/src/compat/lifecycle/testmode.ts

@@ -0,0 +1,263 @@
+// testmode / experimental.testProxy (COMPAT).
+//
+// When a request carries `Next-Test-Proxy-Port` + `Next-Test-Data` headers, all outgoing fetch during
+// that request is proxied to the named localhost port following Next's testmode wire protocol. A
+// request interceptor stores the proxy info for the duration of the request; global.fetch is patched
+// exactly once at init and consults it - a no-op when no proxy info is active. Gated on
+// experimental.testProxy in next.config.
+
+import { PassThrough } from 'node:stream';
+import type * as http from 'node:http';
+import type * as https from 'node:https';
+import type { IncomingMessage } from 'node:http';
+import { createRequire } from 'node:module';
+import { currentRequest, getWorkUnit } from '../../request/context';
+
+// `import * as http` yields a frozen ES module namespace object under strict
+// runtimes (Bun); assigning to `.get` on it throws "Attempted to assign to
+// readonly property." `require()` returns the real, mutable CJS exports
+// object that node/http/https resolve `.get` calls through at runtime, so
+// patch that instead of the namespace binding.
+const requireNode = createRequire(import.meta.url);
+const httpModule = requireNode('node:http') as typeof http;
+const httpsModule = requireNode('node:https') as typeof https;
+
+interface TestProxyInfo {
+  proxyPort: number;
+  testData: string;
+}
+
+/**
+ * The proxy info rides on the core work unit (which spans the whole request lifecycle) rather than a
+ * private ALS, so the patched global.fetch - invoked deep inside a render or handler - can recover it
+ * via getWorkUnit(). The interceptor sets it before matching; the fetch patch reads it.
+ */
+const TEST_PROXY_KEY = Symbol.for('pnext.testProxy');
+
+/** Extract proxy info from a request's Next-Test-* headers, if present. */
+export function readTestProxyInfo(headers: Headers): TestProxyInfo | undefined {
+  const portHeader = headers.get('next-test-proxy-port');
+  if (!portHeader) return undefined;
+  return { proxyPort: Number(portHeader), testData: headers.get('next-test-data') ?? '' };
+}
+
+/** Record the request's test-proxy info onto the active work unit (if any). */
+export function activateTestProxy(headers: Headers): void {
+  const info = readTestProxyInfo(headers);
+  if (!info) return;
+  const unit = getWorkUnit();
+  if (!unit) return;
+  (unit.compat ??= {})[TEST_PROXY_KEY] = info;
+}
+
+function currentTestProxyInfo(): TestProxyInfo | undefined {
+  const workUnitInfo = getWorkUnit()?.compat?.[TEST_PROXY_KEY] as TestProxyInfo | undefined;
+  if (workUnitInfo) return workUnitInfo;
+  const request = currentRequest();
+  if (!request) return undefined;
+  return readTestProxyInfo(request.headers);
+}
+
+// pnext marks its own proxy round-trips via `next.internal` so the patched
+// fetch (below) doesn't re-intercept them. The `next` field is typed as
+// NextFetchRequestConfig globally, so extend it via intersection rather than
+// interface-extends (which errors on the conflicting `next` property).
+type InternalInit = RequestInit & { next?: { internal?: boolean } };
+
+interface ProxyFetchRequest {
+  testData: string;
+  api: 'fetch';
+  request: {
+    url: string;
+    method: string;
+    headers: [string, string][];
+    body: string | null;
+    cache: RequestCache;
+    credentials: RequestCredentials;
+    integrity: string;
+    mode: RequestMode;
+    redirect: RequestRedirect;
+    referrer: string;
+    referrerPolicy: ReferrerPolicy;
+  };
+}
+
+async function buildProxyRequest(testData: string, request: Request): Promise<ProxyFetchRequest> {
+  return {
+    testData,
+    api: 'fetch',
+    request: {
+      url: request.url,
+      method: request.method,
+      headers: [
+        ...Array.from(request.headers),
+        ['next-test-stack', getTestStack()],
+      ],
+      body: request.body ? Buffer.from(await request.arrayBuffer()).toString('base64') : null,
+      cache: request.cache,
+      credentials: request.credentials,
+      integrity: request.integrity,
+      // Bun defaults a Request built from a URL string to mode 'navigate'
+      // (undici/browsers use 'cors'). 'navigate' cannot be reconstructed via
+      // the Request constructor, so the test proxy's buildRequest() would throw
+      // "invalid request mode navigate". Normalize it to the browser default so
+      // the proxy can rebuild the forwarded request.
+      mode: request.mode === 'navigate' ? 'cors' : request.mode,
+      redirect: request.redirect,
+      referrer: request.referrer,
+      referrerPolicy: request.referrerPolicy,
+    },
+  };
+}
+
+function getTestStack(): string {
+  let stack = (new Error().stack ?? '').split('\n');
+  for (let i = 1; i < stack.length; i++) {
+    const line = stack[i];
+    if (line && line.length > 0) {
+      stack = stack.slice(i);
+      break;
+    }
+  }
+  stack = stack.filter(item => !item.includes('/next/dist/'));
+  stack = stack.slice(0, 5);
+  stack = stack.map(line => line.replace('webpack-internal:///(rsc)/', '').trim());
+  return stack.join('    ');
+}
+
+interface ProxyResponse {
+  api: 'continue' | 'abort' | 'unhandled' | 'fetch';
+  response?: { status: number; headers: [string, string][]; body: string | null };
+}
+
+async function handleProxiedFetch(
+  originalFetch: typeof fetch,
+  info: TestProxyInfo,
+  request: Request,
+): Promise<Response> {
+  const proxyRequest = await buildProxyRequest(info.testData, request);
+  const resp = await originalFetch(`http://localhost:${info.proxyPort}`, {
+    method: 'POST',
+    body: JSON.stringify(proxyRequest),
+    next: { internal: true },
+  } as InternalInit);
+  if (!resp.ok) throw new Error(`Proxy request failed: ${resp.status}`);
+  const proxyResponse = (await resp.json()) as ProxyResponse;
+  switch (proxyResponse.api) {
+    case 'continue':
+      return originalFetch(request);
+    case 'fetch': {
+      const r = proxyResponse.response!;
+      return new Response(r.body ? Buffer.from(r.body, 'base64') : null, {
+        status: r.status,
+        headers: new Headers(r.headers),
+      });
+    }
+    default:
+      throw new Error(`Proxy request aborted [${request.method} ${request.url}]`);
+  }
+}
+
+type TestGetCallback = (res: IncomingMessage) => void;
+type HttpGetInput = Parameters<typeof http.get>[0];
+
+function buildResponseMessage(responsePromise: Promise<Response>, callback?: TestGetCallback): IncomingMessage {
+  const stream = new PassThrough();
+  const message = stream as unknown as IncomingMessage;
+  void responsePromise.then(async response => {
+    const headers: Record<string, string> = {};
+    const rawHeaders: string[] = [];
+    for (const [name, value] of response.headers) {
+      headers[name.toLowerCase()] = value;
+      rawHeaders.push(name, value);
+    }
+    message.statusCode = response.status;
+    message.statusMessage = response.statusText;
+    message.headers = headers;
+    message.rawHeaders = rawHeaders;
+    message.complete = true;
+    callback?.(message);
+    const body = await response.arrayBuffer();
+    stream.end(Buffer.from(body));
+  }).catch(error => {
+    stream.emit('error', error);
+    stream.end();
+  });
+  return message;
+}
+
+function getStringForGetInput(input: HttpGetInput): string | undefined {
+  if (typeof input === 'string' || input instanceof URL) return input.toString();
+  const candidate = input as { href?: string; protocol?: string; hostname?: string; host?: string; path?: string; pathname?: string; search?: string; port?: number | string };
+  if (typeof candidate.href === 'string' && /^[a-z][a-z\d+.-]*:\/\//i.test(candidate.href)) return candidate.href;
+  const protocol = typeof candidate.protocol === 'string' ? candidate.protocol : 'http:';
+  const host = typeof candidate.host === 'string' ? candidate.host : typeof candidate.hostname === 'string' ? candidate.hostname : undefined;
+  if (!host) return undefined;
+  const port =
+    typeof candidate.port === 'number' ? `:${candidate.port}` : typeof candidate.port === 'string' ? `:${candidate.port}` : '';
+  const path = typeof candidate.path === 'string' ? candidate.path : typeof candidate.pathname === 'string' ? candidate.pathname : '/';
+  const search = typeof candidate.search === 'string' ? candidate.search : '';
+  return `${protocol}//${host}${port}${path}${search}`;
+}
+
+function patchableGet(
+  originalGet: typeof http.get,
+  originalFetch: typeof fetch,
+): typeof http.get {
+  return ((input: HttpGetInput, options?: Parameters<typeof http.get>[1]) => {
+    const callback = typeof options === 'function' ? options : undefined;
+    const url = getStringForGetInput(input);
+    const info = currentTestProxyInfo();
+    if (!url || !info) {
+      if (typeof options === 'function') {
+        return originalGet(input, options);
+      }
+      if (options === undefined) {
+        return originalGet(input);
+      }
+      return originalGet(input, options);
+    }
+    const request = new Request(url, {
+      method: typeof options === 'object' && options && 'method' in options && typeof options.method === 'string'
+        ? options.method
+        : 'GET',
+      headers:
+        typeof options === 'object' && options && 'headers' in options
+          ? (options.headers as HeadersInit)
+          : undefined,
+    });
+    return buildResponseMessage(handleProxiedFetch(originalFetch, info, request), callback) as unknown as ReturnType<
+      typeof http.get
+    >;
+  }) as typeof http.get;
+}
+
+let patched = false;
+
+/** Patch global.fetch and node http/https.get once for testmode outgoing requests. */
+export function installTestProxyFetch(): void {
+  if (patched) return;
+  patched = true;
+  const originalFetch = globalThis.fetch.bind(globalThis);
+
+  const testFetch = function testFetch(
+    input: Parameters<typeof fetch>[0],
+    init?: Parameters<typeof fetch>[1],
+  ): Promise<Response> {
+    const nextInit = (init as { next?: { internal?: boolean } } | undefined)?.next;
+    if (nextInit?.internal) {
+      return originalFetch(input, init);
+    }
+    const info = currentTestProxyInfo();
+    if (!info) return originalFetch(input, init);
+    return handleProxiedFetch(originalFetch, info, new Request(input, init));
+  };
+  // Preserve fetch.preconnect (typeof fetch requires it).
+  (testFetch as typeof fetch).preconnect = originalFetch.preconnect?.bind(originalFetch);
+  globalThis.fetch = testFetch as typeof fetch;
+
+  const originalHttpGet = httpModule.get;
+  const originalHttpsGet = httpsModule.get;
+  httpModule.get = patchableGet(originalHttpGet, originalFetch);
+  httpsModule.get = patchableGet(originalHttpsGet, originalFetch);
+}

package/src/compat/mdx/compile.ts

@@ -0,0 +1,219 @@
+// MDX compile core (COMPAT).
+//
+// Thin wrapper over `@mdx-js/mdx`'s `compile`. Kept dependency-light and lazy: `@mdx-js/mdx` is an
+// optionalDependency loaded on first `.mdx` compile, so a pure app that never touches MDX pays nothing
+// and builds without it installed.
+//
+// The user's remark/rehype/recma plugin arrays come from the wrapped next.config, read via
+// `getNextConfig()` so no wiring is required beyond registering the loader.
+//
+// Output is JSX targeting the preact automatic runtime; the esbuild loader that calls this returns
+// `loader: 'jsx'` so esbuild performs the final JSX-to-calls transform with the same jsxImportSource
+// every other compile site uses, keeping a single JSX runtime end to end.
+//
+// `providerImportSource` is set to our components provider only when the app ships an `mdx-components`
+// file; without one, MDX emits bare host elements, which is exactly the mdx-no-mdx-components contract.
+
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { getNextConfig } from '../next/config-loader';
+
+export interface MdxCompileResult {
+  code: string;
+}
+
+interface MdxModule {
+  compile: (
+    source: string | { value: string; path?: string },
+    options?: Record<string, unknown>,
+  ) => Promise<{ toString: () => string; value: string }>;
+}
+
+interface MdxOptions {
+  remarkPlugins?: unknown[];
+  rehypePlugins?: unknown[];
+  recmaPlugins?: unknown[];
+  remarkRehypeOptions?: Record<string, unknown>;
+  providerImportSource?: string;
+}
+
+let cachedModule: MdxModule | null | undefined;
+
+/**
+ * Load `@mdx-js/mdx` lazily. Returns `null` (not throwing) when the optional
+ * dependency is absent so the loader can surface a single actionable error only
+ * when an app actually imports `.mdx`.
+ */
+async function loadMdx(): Promise<MdxModule | null> {
+  if (cachedModule !== undefined) return cachedModule;
+  try {
+    const specifier = '@mdx-js/mdx';
+    cachedModule = (await import(/* @vite-ignore */ specifier)) as MdxModule;
+  } catch {
+    cachedModule = null;
+  }
+  return cachedModule;
+}
+
+/** The user's mdxOptions from the wrapped next.config, normalized. */
+export function mdxOptionsFromConfig(): MdxOptions {
+  const config = getNextConfig() as {
+    mdxOptions?: MdxOptions;
+    experimental?: { mdxRs?: unknown };
+  };
+  // @next/mdx stores the merged plugin options under `mdxOptions` on the config
+  // object the wrapper produces. `experimental.mdxRs` selects the Rust pipeline
+  // upstream; we always use the JS pipeline, so it is intentionally ignored.
+  return config.mdxOptions ?? {};
+}
+
+/**
+ * Resolve the app's `mdx-components.{tsx,ts,jsx,js,mjs}` provider file if present.
+ * Next looks for it at the project root (or `src/`). Returns the absolute path
+ * used as `providerImportSource`, or `undefined` when absent (bare host elements).
+ */
+export function resolveMdxComponents(root: string): string | undefined {
+  const bases = [root, path.join(root, 'src')];
+  const names = ['mdx-components.tsx', 'mdx-components.ts', 'mdx-components.jsx', 'mdx-components.js', 'mdx-components.mjs'];
+  for (const base of bases) {
+    for (const name of names) {
+      const candidate = path.join(base, name);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
+function interopDefault(module: unknown): unknown {
+  return (module as { default?: unknown })?.default ?? module;
+}
+
+// Sentinel returned when a configured plugin package can't be resolved from the
+// app, so `resolvePlugins` can filter it out.
+const UNRESOLVED_PLUGIN = Symbol('pnext.mdx.unresolved-plugin');
+
+/**
+ * Resolve a single plugin entry to the shape `@mdx-js/mdx` expects. `@next/mdx` stores plugins as
+ * serializable STRINGS (a bare package name) or `[name, opts]` tuples, because webpack loader options
+ * must serialize. Mirroring its mdx-js-loader: resolve the name from the project root and
+ * dynamic-import it, taking the default export. Entries that are already functions or tuples of
+ * functions pass through untouched.
+ *
+ * A configured plugin that cannot be resolved OR fails to load returns UNRESOLVED_PLUGIN (a warn, not a
+ * throw): neither a missing optional transform nor a broken transitive dependency may take down the
+ * whole `.mdx` render. This also matches `mdxRs: true`, where Next never JS-resolves these packages at
+ * all. Load failures are common when the toolchain resolves into a flat auto-install cache rather than
+ * a real node_modules tree, so the real error is surfaced to the log instead of silently 500ing pages.
+ */
+async function resolvePlugin(
+  entry: unknown,
+  resolveFrom: NodeRequire,
+): Promise<unknown> {
+  if (typeof entry === 'function') return entry;
+  if (typeof entry === 'string') {
+    return loadPlugin(entry, resolveFrom);
+  }
+  if (Array.isArray(entry) && typeof entry[0] === 'string') {
+    const tuple = entry as unknown[];
+    const plugin = await loadPlugin(tuple[0] as string, resolveFrom);
+    if (plugin === UNRESOLVED_PLUGIN) return UNRESOLVED_PLUGIN;
+    return [plugin, ...tuple.slice(1)];
+  }
+  return entry;
+}
+
+/**
+ * Resolve a plugin from the app root and import it. Returns the plugin's default
+ * export, or UNRESOLVED_PLUGIN (with a warning) when it is not installed or
+ * cannot be loaded. Resolution is rooted at the app (`createRequire(root/...)`)
+ * so the toolchain stays inside the app's node_modules.
+ */
+async function loadPlugin(name: string, resolveFrom: NodeRequire): Promise<unknown> {
+  let resolved: string;
+  try {
+    resolved = resolveFrom.resolve(name);
+  } catch {
+    console.warn(
+      `pnext: MDX plugin '${name}' is configured but not installed; skipping it. ` +
+        'Install it to apply this remark/rehype/recma plugin.',
+    );
+    return UNRESOLVED_PLUGIN;
+  }
+  try {
+    return interopDefault(await import(pathToFileURL(resolved).href));
+  } catch (error) {
+    console.warn(
+      `pnext: MDX plugin '${name}' failed to load and was skipped: ` +
+        `${error instanceof Error ? error.message : String(error)}. ` +
+        'Ensure it is installed in the app’s node_modules (not only Bun’s auto-install cache).',
+    );
+    return UNRESOLVED_PLUGIN;
+  }
+}
+
+/** Resolve every entry of a remark/rehype/recma plugin array (skipping absent packages). */
+async function resolvePlugins(plugins: unknown[], resolveFrom: NodeRequire): Promise<unknown[]> {
+  const resolved = await Promise.all(plugins.map(entry => resolvePlugin(entry, resolveFrom)));
+  return resolved.filter(entry => entry !== UNRESOLVED_PLUGIN);
+}
+
+/**
+ * Compile MDX source to JSX targeting the preact automatic runtime. `root` locates
+ * the optional mdx-components provider; `filePath` feeds source positions.
+ */
+export async function compileMdx(
+  source: string,
+  filePath: string,
+  root: string,
+): Promise<MdxCompileResult> {
+  const mdx = await loadMdx();
+  if (!mdx) {
+    throw new Error(
+      "MDX support requires the '@mdx-js/mdx' package. Install it to render .mdx files.",
+    );
+  }
+
+  const userOptions = mdxOptionsFromConfig();
+  const provider = resolveMdxComponents(root);
+
+  // Resolve string/tuple plugin names (@next/mdx's serialized form) to actual
+  // plugin functions from the app's node_modules before handing them to MDX.
+  const resolveFrom = createRequire(path.join(root, 'noop.js'));
+
+  const [remarkPlugins, rehypePlugins, recmaPlugins] = await Promise.all([
+    resolvePlugins(userOptions.remarkPlugins ?? [], resolveFrom),
+    resolvePlugins(userOptions.rehypePlugins ?? [], resolveFrom),
+    resolvePlugins(userOptions.recmaPlugins ?? [], resolveFrom),
+  ]);
+
+  const compiled = await mdx.compile(
+    { value: source, path: filePath },
+    {
+      // Emit JSX; esbuild's `jsx` loader performs the final transform with
+      // jsxImportSource: 'preact', matching every other compile site.
+      jsx: true,
+      jsxImportSource: 'preact',
+      // Full MDX (not just markdown) so `import`/`export` and JSX in `.mdx` work.
+      format: 'mdx',
+      // Development positions off — matches production build output.
+      development: false,
+      remarkPlugins,
+      rehypePlugins,
+      recmaPlugins,
+      ...(userOptions.remarkRehypeOptions
+        ? { remarkRehypeOptions: userOptions.remarkRehypeOptions }
+        : {}),
+      // Only wire a components provider when the app supplies one; otherwise MDX
+      // emits plain host elements (the mdx-no-mdx-components contract).
+      ...(userOptions.providerImportSource
+        ? { providerImportSource: userOptions.providerImportSource }
+        : provider
+          ? { providerImportSource: provider }
+          : {}),
+    },
+  );
+
+  return { code: compiled.toString() };
+}

package/src/compat/mdx/next-mdx-stub.ts

@@ -0,0 +1,46 @@
+// `@next/mdx` config-time stub (COMPAT).
+//
+// `createMDX(pluginOptions)(nextConfig)` embeds the user's remark/rehype/recma plugin options ONLY
+// inside a webpack/turbopack loader config it attaches to the returned next.config - it never exposes
+// them on a readable top-level field. pnext has no webpack, so those options would be lost and every
+// configured MDX plugin would silently not run.
+//
+// During config bundling, `@next/mdx` resolves to this stub instead of the real package. The stub
+// reproduces the wrapper's signature but stashes the plugin options on `config.mdxOptions`, exactly
+// where pnext's MDX compile pipeline reads them. It also removes the need for `@next/mdx` itself to be
+// installed for the config to load. The wrapped config's own webpack/turbopack/pageExtensions are
+// irrelevant to pnext, so the stub only needs to merge `mdxOptions`.
+
+import type { Plugin } from 'esbuild';
+
+// CJS so esbuild's default-import interop yields the wrapper factory for both
+// `import nextMDX from '@next/mdx'` and `require('@next/mdx')` config authors.
+const NEXT_MDX_STUB_CONTENTS = `
+const createMDX = (pluginOptions = {}) => (nextConfig = {}) => ({
+  ...nextConfig,
+  mdxOptions: (pluginOptions && pluginOptions.options) || {},
+});
+module.exports = createMDX;
+module.exports.default = createMDX;
+`;
+
+/**
+ * esbuild plugin (config-load only) that replaces `@next/mdx` (and its
+ * `@next/mdx/*` deep specifiers) with a stub capturing the plugin options onto
+ * `config.mdxOptions`.
+ */
+export function nextMdxConfigStubPlugin(): Plugin {
+  return {
+    name: 'pnext-next-mdx-config-stub',
+    setup(build) {
+      build.onResolve({ filter: /^@next\/mdx(?:\/|$)/ }, args => ({
+        path: args.path,
+        namespace: 'pnext-next-mdx-stub',
+      }));
+      build.onLoad({ filter: /.*/, namespace: 'pnext-next-mdx-stub' }, () => ({
+        contents: NEXT_MDX_STUB_CONTENTS,
+        loader: 'js',
+      }));
+    },
+  };
+}

package/src/compat/mdx/plugin.ts

@@ -0,0 +1,37 @@
+// MDX esbuild plugin (COMPAT).
+//
+// Intercepts `.mdx` (and `.md`) loads across every build graph - client bundle, dev RSC route bundle,
+// and prod server compile - and replaces the file contents with the JSX compiled from MDX. Returned as
+// `loader: 'jsx'` so esbuild does the final JSX-to-preact-runtime transform.
+//
+// The same factory is registered on both the client and server esbuild plugin lists. It resolves the
+// project root from the build's `absWorkingDir` (all pnext esbuild builds set it to the project root)
+// so the optional mdx-components provider is located correctly.
+
+import { readFile } from 'node:fs/promises';
+import type { Plugin } from 'esbuild';
+import { applyClientSourceTransforms } from '../../extensions';
+import { compileMdx } from './compile';
+
+const MDX_FILTER = /\.mdx?$/;
+
+/**
+ * esbuild plugin that compiles `.md`/`.mdx` modules through the JS MDX pipeline.
+ * `rootOverride` pins the project root; when omitted the plugin uses the build's
+ * `absWorkingDir` (falling back to `process.cwd()`).
+ */
+export function mdxEsbuildPlugin(rootOverride?: string): Plugin {
+  return {
+    name: 'pnext-mdx',
+    setup(build) {
+      const root = rootOverride ?? build.initialOptions.absWorkingDir ?? process.cwd();
+      build.onLoad({ filter: MDX_FILTER }, async args => {
+        const source = await readFile(args.path, 'utf8');
+        const { code } = await compileMdx(source, args.path, root);
+        // Compiled MDX must still pass through registered source transforms
+        // (e.g. modularizeImports) — raw compileMdx output bypasses them.
+        return { contents: applyClientSourceTransforms(code, args.path, root), loader: 'jsx' };
+      });
+    },
+  };
+}