@wular/pnext 0.0.1

package/src/compat/actions/detect.ts

@@ -0,0 +1,208 @@
+/**
+ * Source-text scanning to find Next-style server actions ('use server').
+ *
+ * This is deliberately regex/heuristic based, not a full parser. It targets the
+ * common Next fixture shapes and documents its limitations rather than trying to
+ * be a compiler. The reliable, fully-static path is a module-level 'use server'
+ * file with named exports; inline actions inside components are best-effort.
+ */
+
+export { actionId, workspaceRelative } from './ids';
+
+const DIRECTIVE = /^(['"])use server\1\s*;?$/;
+const CACHE_DIRECTIVE = /^(['"])use cache\1\s*;?$/;
+
+/**
+ * True when the file's FIRST statement is a 'use server' directive, marking the
+ * whole module as a server-action module (every export is an action).
+ *
+ * Leading comments (line and block), a shebang, and blank lines are skipped, as
+ * a real JS engine would when looking for a directive prologue.
+ */
+export function moduleLevelUseServer(source: string): boolean {
+  const first = firstStatementText(stripLeading(source));
+  return first !== undefined && DIRECTIVE.test(first.trim());
+}
+
+/**
+ * True when the file's FIRST statement is a plain 'use cache' directive. Such a module's exports are
+ * server references exactly like a 'use server' module: a client component that imports one must get
+ * RPC stubs, since the cached functions always execute (and cache) on the server. Named handler
+ * variants are function-level only in practice and excluded.
+ */
+export function moduleLevelUseCache(source: string): boolean {
+  const first = firstStatementText(stripLeading(source));
+  return first !== undefined && CACHE_DIRECTIVE.test(first.trim());
+}
+
+export interface InlineAction {
+  /** Local (and, when exported, exported) name of the action function. */
+  name: string;
+  /** True when the function is a named export (`export ...` / re-exported). */
+  exported: boolean;
+  /** Character offset of the start of the matched declaration in `source`. */
+  start: number;
+  /** Character offset just past the `"use server"` directive that marked it. */
+  directiveEnd: number;
+}
+
+/**
+ * Find inline 'use server' actions: functions whose body opens with a
+ * `"use server"` directive. Handles the two common Next shapes:
+ *
+ *   async function foo() { "use server"; ... }
+ *   const foo = async (...) => { "use server"; ... }
+ *
+ * Both with and without a leading `export`. Returns local names + spans.
+ *
+ * Limitations (documented, not fixed):
+ * - No full parser: a `"use server"` string that is not the first statement of a
+ *   function body may still match if it sits right after `{`; conversely unusual
+ *   formatting (directive on a line with trailing code) can be missed.
+ * - Default exports and object-method shorthand are not detected here.
+ * - Actions defined inline in a component and passed to <form action={fn}> are
+ *   found as local declarations, but whether they are truly exported/reachable
+ *   as an RPC target can't be resolved statically. Prefer named exports of a
+ *   module-level 'use server' file for the reliable wire path.
+ */
+export function inlineUseServerFunctions(source: string): InlineAction[] {
+  const found: InlineAction[] = [];
+  const seen = new Set<string>();
+
+  // Shape 1: [export] [async] function NAME(...) { "use server"
+  const fnDecl =
+    /(\bexport\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*\{\s*(['"])use server\3\s*;?/g;
+  collect(fnDecl, source, found, seen, { nameGroup: 2, exportGroup: 1, dirGroup: 3 });
+
+  // Shape 2: [export] const NAME = [async] (...) => { "use server"
+  //          also covers `= async function (...) { "use server"`
+  const arrowOrExpr =
+    /(\bexport\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[A-Za-z_$][\w$]*|function\s*\*?\s*\([^)]*\))\s*(?:=>\s*)?\{\s*(['"])use server\3\s*;?/g;
+  collect(arrowOrExpr, source, found, seen, { nameGroup: 2, exportGroup: 1, dirGroup: 3 });
+
+  return found.sort((a, b) => a.start - b.start);
+}
+
+interface Groups {
+  nameGroup: number;
+  exportGroup: number;
+  dirGroup: number;
+}
+
+function collect(
+  pattern: RegExp,
+  source: string,
+  out: InlineAction[],
+  seen: Set<string>,
+  groups: Groups,
+) {
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(source))) {
+    const name = match[groups.nameGroup];
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    out.push({
+      name,
+      exported: Boolean(match[groups.exportGroup]),
+      start: match.index,
+      directiveEnd: match.index + match[0].length,
+    });
+  }
+}
+
+/**
+ * Names to treat as action RPC targets for a module-level 'use server' file:
+ * every named export plus a default export flagged as `'default'`. Regex-based
+ * export scanning; covers `export function`, `export const`, `export { a, b }`,
+ * `export { a as b }`, `export default`.
+ */
+export function moduleActionExports(source: string): string[] {
+  const names = new Set<string>();
+
+  // export [async] function NAME / export const|let|var NAME
+  const declRe =
+    /\bexport\s+(?:async\s+)?(?:function\s*\*?\s+|const\s+|let\s+|var\s+|class\s+)([A-Za-z_$][\w$]*)/g;
+  for (let m; (m = declRe.exec(source)); ) if (m[1]) names.add(m[1]);
+
+  // export default ...
+  if (/\bexport\s+default\b/.test(source)) names.add('default');
+
+  // export { a, b as c }  (ignore `export type { ... }`)
+  const listRe = /\bexport\s+(?!type\b)\{([^}]*)\}/g;
+  for (let m; (m = listRe.exec(source)); ) {
+    for (const part of (m[1] ?? '').split(',')) {
+      const trimmed = part.trim();
+      if (!trimmed || trimmed.startsWith('type ')) continue;
+      const exportedName = /\bas\s+([A-Za-z_$][\w$]*)\s*$/.exec(trimmed)?.[1];
+      const name = exportedName ?? trimmed;
+      if (/^[A-Za-z_$][\w$]*$/.test(name)) names.add(name);
+    }
+  }
+
+  return [...names];
+}
+
+/** Strip a leading shebang and BOM so directive detection starts at real code. */
+function stripLeading(source: string): string {
+  let s = source.replace(/^\uFEFF/, '');
+  if (s.startsWith('#!')) {
+    const nl = s.indexOf('\n');
+    s = nl === -1 ? '' : s.slice(nl + 1);
+  }
+  return s;
+}
+
+/**
+ * Return the text of the first statement, skipping leading comments and blank
+ * lines. Used only to check the directive prologue; returns the first
+ * `;`-or-newline-terminated token run.
+ */
+function firstStatementText(source: string): string | undefined {
+  let i = 0;
+  const n = source.length;
+  while (i < n) {
+    const ch = source[i];
+    if (ch === ' ' || ch === '\t' || ch === '\r' || ch === '\n') {
+      i++;
+      continue;
+    }
+    if (ch === '/' && source[i + 1] === '/') {
+      const nl = source.indexOf('\n', i);
+      if (nl === -1) return undefined;
+      i = nl + 1;
+      continue;
+    }
+    if (ch === '/' && source[i + 1] === '*') {
+      const end = source.indexOf('*/', i + 2);
+      if (end === -1) return undefined;
+      i = end + 2;
+      continue;
+    }
+    break;
+  }
+  if (i >= n) return undefined;
+  // Read until end of line or a semicolon (directive is a single statement).
+  let j = i;
+  while (j < n && source[j] !== '\n' && source[j] !== ';') j++;
+  const end = source[j] === ';' ? j + 1 : j;
+  return source.slice(i, end);
+}
+
+/**
+ * Anonymous inline actions (`onClick={async () => { 'use server'; ... }}`)
+ * carry no compile-tagged id; the directive in the live function source is the
+ * only signal separating them from plain client handlers when serialization is
+ * restricted to identified actions.
+ */
+export function opensWithUseServerDirective(fn: unknown): boolean {
+  if (typeof fn !== 'function') return false;
+  let source: string;
+  try {
+    source = String(fn);
+  } catch {
+    return false;
+  }
+  const body = source.indexOf('{', source.indexOf(')') + 1);
+  if (body === -1) return false;
+  return /^\s*(['"])use server\1/.test(source.slice(body + 1));
+}

package/src/compat/actions/discovery.ts

@@ -0,0 +1,244 @@
+import path from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { builtinModules } from 'node:module';
+import { listFilesSync } from '../../utils/fs';
+import type { ResolvedConfig } from '../../config';
+import { nextCompatEnabled } from '..';
+import { importSpecifiers } from '../../resolve/scan-facts';
+import { readSourceSync } from '../../resolve/source-text';
+import {
+  packageNameOfSpecifier,
+  resolutionRootForFile,
+  resolvePackageSpecifier,
+} from '../../resolve/imports';
+import { moduleActionExports, moduleLevelUseCache, moduleLevelUseServer } from './detect';
+import { canonical, canonicalActionId } from './client-plugin';
+import { registerActionModule, type ActionEntry } from './registry';
+
+/**
+ * One discovered server-action module: its source path, the action export
+ * names, the wire ids for each, and the module path that runAction's
+ * importModule() should load (a compiled output path in prod, the source path
+ * in dev).
+ */
+export interface DiscoveredActionModule {
+  /** Source file of the 'use server' module. */
+  file: string;
+  /** Action export names (named exports + 'default'). */
+  exports: string[];
+  /** actionId(file, exportName, root) keyed by export name. */
+  ids: Record<string, string>;
+  /** What runAction hands to importModule() (defaults to `file`). */
+  modulePath: string;
+}
+
+export interface ActionDiscovery {
+  modules: DiscoveredActionModule[];
+  /** Every source file that is a 'use server' module, for the client alias. */
+  actionFiles: Set<string>;
+}
+
+/**
+ * Scan the app for module-level `'use server'` files - the reliable, fully static wire path. Each such
+ * file contributes every named export (plus a default export) as an RPC target.
+ *
+ * Inline `'use server'` functions inside Server Components are intentionally NOT discovered here: they
+ * cannot be resolved to a stable module export reachable as an RPC target. They still work when passed
+ * to <form action={fn}> as a local declaration rendered on the server.
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+export async function discoverActions(
+  config: ResolvedConfig,
+  options: { modulePathFor?: (file: string) => string } = {},
+): Promise<ActionDiscovery> {
+  const empty: ActionDiscovery = { modules: [], actionFiles: new Set() };
+  if (!nextCompatEnabled(config)) return empty;
+
+  const roots = actionScanRoots(config);
+  const seen = new Set<string>();
+  const files: string[] = [];
+  // Synchronous on purpose: every await hands the loop back to the build's sync route-fact walk and
+  // gate steps, which hold it long enough to stretch this work into a span the client stage then
+  // waits on. Running it straight through costs the same CPU and unblocks the stage.
+  const listings = roots.map(root => (existsSync(root) ? listFilesSync(root) : []));
+  for (const listing of listings) {
+    for (const file of listing) {
+      const resolved = path.resolve(file);
+      if (seen.has(resolved) || !isScriptFile(resolved)) continue;
+      seen.add(resolved);
+      files.push(resolved);
+    }
+  }
+  const sources = readSources(files);
+  for (const file of discoverNodeModuleActionFiles(config, files, sources, seen)) {
+    files.push(file);
+    seen.add(file);
+  }
+  for (const [file, source] of readSources(files.filter(file => !sources.has(file)))) {
+    sources.set(file, source);
+  }
+
+  const modules: DiscoveredActionModule[] = [];
+  const actionFiles = new Set<string>();
+  for (const file of files) {
+    const source = sources.get(file)!;
+    // Module-level 'use cache' files are server-reference modules too: their
+    // exports cross to client components as RPC stubs (Next semantics — the
+    // cached function always runs, and caches, on the server).
+    if (!moduleLevelUseServer(source) && !moduleLevelUseCache(source)) continue;
+    const exports = moduleActionExports(source);
+    if (exports.length === 0) continue;
+
+    const ids: Record<string, string> = {};
+    for (const exportName of exports) ids[exportName] = canonicalActionId(file, exportName, config.root);
+    modules.push({
+      file,
+      exports,
+      ids,
+      modulePath: options.modulePathFor ? options.modulePathFor(file) : file,
+    });
+    actionFiles.add(file);
+  }
+
+  return { modules, actionFiles };
+}
+
+/**
+ * Register discovered action modules into the process registry so the endpoint
+ * can resolve incoming ids. Returns the flat entry list (id/modulePath/export).
+ */
+export function registerDiscoveredActions(
+  config: ResolvedConfig,
+  discovery: ActionDiscovery,
+): ActionEntry[] {
+  const entries: ActionEntry[] = [];
+  const root = canonical(config.root);
+  for (const module of discovery.modules) {
+    // Canonical (file, root) so registry ids match the client stub / manifest.
+    entries.push(
+      ...registerActionModule(canonical(module.file), module.exports, {
+        root,
+        modulePath: module.modulePath,
+      }),
+    );
+  }
+  return entries;
+}
+
+// Server actions live under the app dir and (for monorepos) may be shared from
+// workspace packages, but scanning the whole workspace is too broad. Scan the
+// app dir plus the project src dir if present — the common home for a shared
+// actions module. node_modules and the build output are excluded.
+function actionScanRoots(config: ResolvedConfig) {
+  const roots = new Set<string>([config.appPath]);
+  if (config.appPath.includes('pnext-pages-compat')) {
+    const rootApp = path.join(config.root, 'app');
+    if (existsSync(rootApp)) roots.add(rootApp);
+    const srcApp = path.join(config.root, 'src', 'app');
+    if (existsSync(srcApp)) roots.add(srcApp);
+  }
+  const srcDir = path.join(config.root, 'src');
+  if (existsSync(srcDir)) roots.add(srcDir);
+  return [...roots];
+}
+
+function isScriptFile(file: string) {
+  if (file.includes(`${path.sep}node_modules${path.sep}`)) return false;
+  return /\.(?:tsx?|jsx?|mjs)$/.test(file) && !file.endsWith('.d.ts');
+}
+
+const ACTION_RESOLVE_CONDITIONS = ['react-server', 'node', 'import', 'module', 'default'] as const;
+/**
+ * node_modules packages that export module-level 'use server' modules the app imports directly.
+ * Reading a file's real imports costs an oxc parse - but an import specifier is always a quoted string
+ * literal, so the cheap textual superset below decides which files can possibly reach an action
+ * package. Only those are parsed; everything the set returns is confirmed against the parse.
+ */
+function discoverNodeModuleActionFiles(
+  config: ResolvedConfig,
+  sourceFiles: string[],
+  sources: Map<string, string>,
+  seen: Set<string>,
+) {
+  const actionFiles = new Set<string>();
+  // A bare specifier resolves purely from the importer's resolution root, so
+  // both the resolution and the 'use server' verdict are cached app-wide, and
+  // each is derived only for the specifiers a file actually reaches.
+  const targets = new Map<string, string | undefined>();
+  const verdicts = new Map<string, boolean>();
+  const actionTarget = (resolveRoot: string, file: string, specifier: string) => {
+    const packageName = packageNameOfSpecifier(specifier);
+    if (!packageName || builtinModules.includes(packageName)) return undefined;
+    const key = `${resolveRoot}\0${specifier}`;
+    if (!targets.has(key)) {
+      targets.set(key, resolvePackageSpecifier(config.root, file, specifier, ACTION_RESOLVE_CONDITIONS));
+    }
+    const resolved = targets.get(key);
+    if (!resolved) return undefined;
+    const absolute = path.resolve(resolved);
+    if (seen.has(absolute) || !isNodeModuleScriptFile(absolute)) return undefined;
+    let verdict = verdicts.get(absolute);
+    if (verdict === undefined) {
+      // An unreadable candidate is simply not an action module.
+      try {
+        verdict = moduleLevelUseServer(readFileSync(absolute, 'utf8'));
+      } catch {
+        verdict = false;
+      }
+      verdicts.set(absolute, verdict);
+    }
+    return verdict ? absolute : undefined;
+  };
+
+  for (const file of sourceFiles) {
+    const source = sources.get(file) ?? '';
+    const resolveRoot = resolutionRootForFile(config.root, file);
+    let reachable = false;
+    for (const candidate of candidateSpecifiers(source)) {
+      if (actionTarget(resolveRoot, file, candidate)) {
+        reachable = true;
+        break;
+      }
+    }
+    // No candidate resolves to an action module, so neither can the file's real
+    // imports (a subset) — the parse would only reproduce this answer.
+    if (!reachable) continue;
+    for (const specifier of importSpecifiers(source, file)) {
+      const target = actionTarget(resolveRoot, file, specifier);
+      if (target) actionFiles.add(target);
+    }
+  }
+  return [...actionFiles];
+}
+
+// Every string literal in an import position: `from 'x'`, `import 'x'`,
+// `import('x')`, `require('x')`. Deliberately looser than the grammar (it also
+// matches inside comments and strings) — over-reporting only costs a resolve.
+const importedLiteral =
+  /\b(?:from|import|require)\s*\(?\s*(?:\/\*[\s\S]*?\*\/\s*)?(['"])([^'"\n]{1,256})\1/g;
+// npm package names are lowercase `[a-z0-9._-]` with an optional @scope, so a
+// literal with whitespace or a leading ./ can never be a bare specifier.
+const bareSpecifier = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:\/[^\s]+)?$/i;
+
+/** Every literal in the source that could be an imported bare package specifier. */
+function candidateSpecifiers(source: string) {
+  const found = new Set<string>();
+  importedLiteral.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = importedLiteral.exec(source))) {
+    const value = match[2]!;
+    if (bareSpecifier.test(value)) found.add(value);
+  }
+  return found;
+}
+
+/** Read each file once (build-scope cached: the walk's reads are free here). */
+function readSources(files: string[]) {
+  const sources = new Map<string, string>();
+  for (const file of files) sources.set(file, readSourceSync(file));
+  return sources;
+}
+
+function isNodeModuleScriptFile(file: string) {
+  return /\.(?:tsx?|jsx?|mjs|cjs|cts)$/.test(file) && !file.endsWith('.d.ts');
+}

package/src/compat/actions/early-submit.ts

@@ -0,0 +1,40 @@
+/**
+ * Pre-hydration server-action form capture (Next parity).
+ *
+ * React/Next capture form submissions that happen BEFORE hydration and replay them once the client
+ * runtime is up, instead of letting the browser run the native progressive POST (which reloads the
+ * document, losing pending client state and streaming the response into a half-parsed page). This
+ * inline script mirrors that: it queues the submission (FormData snapshotted at submit time, including
+ * the submitter's pair) on the form node and in `window.__pnextEarlySubmits`; the action client
+ * runtime replays queued submissions when the form hydrates, or falls back to the native submit if
+ * hydration never claims it.
+ *
+ * Emitted for every next-compat document after the body content, so the forms it guards are parsed.
+ */
+export function earlySubmitCaptureScript(): string {
+  // Keep in sync with compat/actions/protocol.ts field names.
+  return (
+    '(function(){var h=function(e){' +
+    "var f=e.target;if(!f||f.nodeName!=='FORM')return;" +
+    'if(f.__pnextNativeReplay){f.__pnextNativeReplay=0;return;}' +
+    'if(e.defaultPrevented||window.__PNEXT_ACTIONS__)return;' +
+    'var s=e.submitter||null;' +
+    'var m=f.querySelector(\'input[name="$pnext_action_id"],input[name="$pnext_form_state"]\');' +
+    "if(!m&&!(s&&s.getAttribute('name')==='$pnext_submit_action_id'))return;" +
+    'e.preventDefault();' +
+    'var d;try{d=new FormData(f,s||undefined)}catch(_){d=new FormData(f)}' +
+    'f.__pnextQueuedSubmit={data:d,submitter:s};' +
+    '(window.__pnextEarlySubmits=window.__pnextEarlySubmits||[]).push(f);' +
+    // A page whose route emits no client runtime never drains the queue —
+    // fall back to the browser's native progressive POST (the whole point of
+    // progressive enhancement) once hydration has clearly not claimed it.
+    'setTimeout(function(){' +
+    'if(window.__PNEXT_ACTIONS__||!f.__pnextQueuedSubmit)return;' +
+    'f.__pnextQueuedSubmit=undefined;f.__pnextNativeReplay=1;' +
+    'try{s?f.requestSubmit(s):f.requestSubmit()}catch(_){f.submit()}' +
+    '},3000);' +
+    '};document.addEventListener("submit",h,false);' +
+    'window.__pnextRemoveEarlySubmit=function(){document.removeEventListener("submit",h,false)};' +
+    '})();'
+  );
+}