@mandujs/core 0.31.0 → 0.33.0

package/src/plugins/runner.ts

@@ -0,0 +1,361 @@
+/**
+ * Canonical Plugin Hook Runner — Phase 18.τ.
+ *
+ * This module is the only place where plugin hook dispatch + merge
+ * semantics are implemented. Every integration point (bundler, prerender,
+ * router scanner, runtime server) imports from here so the rules are
+ * consistent and easy to audit.
+ *
+ * Dispatch order, common to every hook:
+ *   1. Config-level hooks (from `ManduConfig.hooks`) run FIRST.
+ *   2. Plugin hooks (from `ManduConfig.plugins[].hooks`) run in
+ *      declaration order.
+ *   3. Each invocation is isolated in try/catch — one failure does not
+ *      block subsequent hooks. Errors are collected in the returned
+ *      {@link HookRunReport} so callers can surface a single rollup.
+ *
+ * Merge semantics (per hook type):
+ *
+ *   | Hook                    | Return type            | Merge rule          |
+ *   | ----------------------- | ---------------------- | ------------------- |
+ *   | `onRouteRegistered`     | void                   | —                   |
+ *   | `onBundleComplete`      | void                   | —                   |
+ *   | `definePrerenderHook`   | PrerenderOverride|void | Object spread       |
+ *   | `onManifestBuilt`       | RoutesManifest|void    | Pipe (last wins)    |
+ *   | `defineBundlerPlugin`   | BunPlugin|BunPlugin[]  | Concat              |
+ *   | `defineMiddlewareChain` | Middleware[]           | Concat              |
+ *   | `defineTestTransform`   | string                 | Pipe (each sees prev)|
+ *
+ * @see `docs/architect/plugin-api.md`
+ * @see `./hooks.ts` for the typed surface
+ */
+
+import type { BunPlugin } from "bun";
+import type { Middleware } from "../middleware/define";
+import type { BundleStats } from "../bundler/types";
+import type { RouteSpec, RoutesManifest } from "../spec/schema";
+import type {
+  ManduPlugin,
+  ManduHooks,
+  PluginContext,
+  PrerenderContext,
+  PrerenderOverride,
+  TestTransformContext,
+} from "./hooks";
+
+// ═══════════════════════════════════════════════════════════════════════
+// Shared types
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Per-hook-invocation error record. Attached to the returned report so
+ * callers can log "plugin X failed on hook Y" without swallowing the
+ * stack trace.
+ */
+export interface HookError {
+  /** Hook name that failed. */
+  hook: keyof ManduHooks;
+  /** Plugin label — either `"config"` or `plugin.name`. */
+  source: string;
+  /** Captured error. */
+  error: Error;
+}
+
+export interface HookRunReport<T = unknown> {
+  /** Merged result (shape varies by hook — see merge table above). */
+  result: T;
+  /** Errors swallowed per hook invocation. Empty when all plugins succeeded. */
+  errors: HookError[];
+}
+
+/**
+ * Args common to every runner call.
+ */
+export interface RunnerArgs {
+  plugins: readonly ManduPlugin[];
+  configHooks?: Partial<ManduHooks>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Internal helpers
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Yield every `(source, fn)` pair for a given hook name, in the canonical
+ * dispatch order: config hook first, then plugin hooks by declaration.
+ */
+function* iterateHook<K extends keyof ManduHooks>(
+  hookName: K,
+  args: RunnerArgs,
+): Generator<{ source: string; fn: NonNullable<ManduHooks[K]> }> {
+  const configFn = args.configHooks?.[hookName];
+  if (configFn) {
+    yield { source: "config", fn: configFn as NonNullable<ManduHooks[K]> };
+  }
+  for (const plugin of args.plugins) {
+    const pluginFn = plugin.hooks?.[hookName];
+    if (pluginFn) {
+      yield {
+        source: plugin.name,
+        fn: pluginFn as NonNullable<ManduHooks[K]>,
+      };
+    }
+  }
+}
+
+/**
+ * Invoke a hook function and surface any thrown error as a HookError so
+ * the caller can carry on with the next plugin. Returns the function's
+ * return value (or `undefined` on error).
+ */
+async function invokeSafely<R>(
+  hookName: keyof ManduHooks,
+  source: string,
+  thunk: () => R | Promise<R>,
+  errors: HookError[],
+): Promise<R | undefined> {
+  try {
+    return await thunk();
+  } catch (raw) {
+    const error = raw instanceof Error ? raw : new Error(String(raw));
+    errors.push({ hook: hookName, source, error });
+    // Surface to stderr too — matches the legacy `runHook` behaviour so
+    // users see the failure even if the caller ignores the report.
+    console.error(`[plugin] ${hookName} failed in ${source}: ${error.message}`);
+    return undefined;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Observer runners (void return — "fire and forget")
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Fire `onRouteRegistered` for each scanned route. Errors in one plugin
+ * don't stop the scan, or even other plugins for the same route.
+ */
+export async function runOnRouteRegistered(
+  route: RouteSpec,
+  args: RunnerArgs,
+): Promise<HookRunReport<void>> {
+  const errors: HookError[] = [];
+  for (const { source, fn } of iterateHook("onRouteRegistered", args)) {
+    await invokeSafely("onRouteRegistered", source, () => fn(route), errors);
+  }
+  return { result: undefined, errors };
+}
+
+/**
+ * Fire `onBundleComplete` with the final BundleStats.
+ */
+export async function runOnBundleComplete(
+  stats: BundleStats,
+  args: RunnerArgs,
+): Promise<HookRunReport<void>> {
+  const errors: HookError[] = [];
+  for (const { source, fn } of iterateHook("onBundleComplete", args)) {
+    await invokeSafely("onBundleComplete", source, () => fn(stats), errors);
+  }
+  return { result: undefined, errors };
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Transformer runners (return-value pipe / spread)
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Merge strategy for `definePrerenderHook`:
+ *
+ *   - Each plugin's non-undefined return spreads onto the accumulator so
+ *     later plugins can override earlier fields (`{ skip: true }` wins
+ *     unless a later plugin sets `{ skip: false }` explicitly).
+ *   - An undefined / void return is treated as "no change".
+ */
+export async function runDefinePrerenderHook(
+  ctx: PrerenderContext,
+  args: RunnerArgs,
+): Promise<HookRunReport<PrerenderOverride>> {
+  const errors: HookError[] = [];
+  let merged: PrerenderOverride = {};
+  for (const { source, fn } of iterateHook("definePrerenderHook", args)) {
+    const out = await invokeSafely(
+      "definePrerenderHook",
+      source,
+      () => fn(ctx),
+      errors,
+    );
+    if (out && typeof out === "object") {
+      merged = { ...merged, ...out };
+    }
+  }
+  return { result: merged, errors };
+}
+
+/**
+ * Pipe `onManifestBuilt` across plugins. Each plugin receives the
+ * manifest the previous plugin returned. A `void` / `undefined` return
+ * means "no change, pass through".
+ */
+export async function runOnManifestBuilt(
+  manifest: RoutesManifest,
+  args: RunnerArgs,
+): Promise<HookRunReport<RoutesManifest>> {
+  const errors: HookError[] = [];
+  let current: RoutesManifest = manifest;
+  for (const { source, fn } of iterateHook("onManifestBuilt", args)) {
+    const out = await invokeSafely(
+      "onManifestBuilt",
+      source,
+      () => fn(current),
+      errors,
+    );
+    if (out && typeof out === "object") {
+      current = out;
+    }
+  }
+  return { result: current, errors };
+}
+
+/**
+ * Collect BunPlugin contributions across every plugin. Scalar returns are
+ * wrapped into a single-element array; array returns are concatenated.
+ * `undefined` is skipped.
+ */
+export async function runDefineBundlerPlugin(
+  args: RunnerArgs,
+): Promise<HookRunReport<BunPlugin[]>> {
+  const errors: HookError[] = [];
+  const collected: BunPlugin[] = [];
+  for (const { source, fn } of iterateHook("defineBundlerPlugin", args)) {
+    const out = await invokeSafely(
+      "defineBundlerPlugin",
+      source,
+      () => fn(),
+      errors,
+    );
+    if (!out) continue;
+    if (Array.isArray(out)) {
+      collected.push(...out);
+    } else {
+      collected.push(out);
+    }
+  }
+  return { result: collected, errors };
+}
+
+/**
+ * Concatenate Middleware arrays from every plugin that provides a
+ * `defineMiddlewareChain`. The returned array is prepended to the
+ * user-declared `ManduConfig.middleware` at server boot time (see
+ * `runtime/server.ts`).
+ */
+export async function runDefineMiddlewareChain(
+  ctx: PluginContext,
+  args: RunnerArgs,
+): Promise<HookRunReport<Middleware[]>> {
+  const errors: HookError[] = [];
+  const collected: Middleware[] = [];
+  for (const { source, fn } of iterateHook("defineMiddlewareChain", args)) {
+    const out = await invokeSafely(
+      "defineMiddlewareChain",
+      source,
+      () => fn(ctx),
+      errors,
+    );
+    if (Array.isArray(out)) {
+      collected.push(...out);
+    }
+  }
+  return { result: collected, errors };
+}
+
+/**
+ * Pipe test-file source through every plugin's `defineTestTransform`.
+ * Each plugin sees the output of the previous plugin. A thrown error
+ * leaves the source unchanged for that step.
+ */
+export async function runDefineTestTransform(
+  ctx: TestTransformContext,
+  args: RunnerArgs,
+): Promise<HookRunReport<string>> {
+  const errors: HookError[] = [];
+  let current = ctx.source;
+  for (const { source, fn } of iterateHook("defineTestTransform", args)) {
+    const out = await invokeSafely(
+      "defineTestTransform",
+      source,
+      () => fn({ testFile: ctx.testFile, source: current }),
+      errors,
+    );
+    if (typeof out === "string") {
+      current = out;
+    }
+  }
+  return { result: current, errors };
+}
+
+/**
+ * Driver-friendly wrapper for `runDefineMiddlewareChain` that returns
+ * the merged Middleware[] directly (errors are logged to stderr via
+ * the same path as the inner runner). Use when a sync caller like
+ * `startServer()` needs the array pre-resolved — wrap the call in
+ * `await` from your driver (the CLI), then pass the result in as a
+ * PREFIX to `options.middleware`.
+ *
+ * @example
+ * ```ts
+ * const pluginMiddleware = await resolvePluginMiddleware({
+ *   plugins: config.plugins ?? [],
+ *   configHooks: config.hooks,
+ *   rootDir: process.cwd(),
+ *   mode: isDev ? "development" : "production",
+ * });
+ * startServer(manifest, {
+ *   ...serverOptions,
+ *   middleware: [...pluginMiddleware, ...(config.middleware ?? [])],
+ *   plugins: config.plugins,
+ *   configHooks: config.hooks,
+ * });
+ * ```
+ */
+export async function resolvePluginMiddleware(input: {
+  plugins: readonly ManduPlugin[];
+  configHooks?: Partial<ManduHooks>;
+  rootDir: string;
+  mode: "development" | "production";
+}): Promise<Middleware[]> {
+  const ctx: PluginContext = {
+    rootDir: input.rootDir,
+    mode: input.mode,
+    logger: {
+      debug: (m, d) => console.debug(`[plugin] ${m}`, d ?? ""),
+      info: (m, d) => console.info(`[plugin] ${m}`, d ?? ""),
+      warn: (m, d) => console.warn(`[plugin] ${m}`, d ?? ""),
+      error: (m, d) => console.error(`[plugin] ${m}`, d ?? ""),
+    },
+  };
+  const report = await runDefineMiddlewareChain(ctx, {
+    plugins: input.plugins,
+    configHooks: input.configHooks,
+  });
+  return report.result;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Convenience: summarize errors for CLI output
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Render an error rollup the CLI can print. Returns `null` when the
+ * report is clean — callers should treat `null` as "nothing to log".
+ */
+export function formatHookErrors(
+  report: HookRunReport<unknown>,
+): string | null {
+  if (report.errors.length === 0) return null;
+  const lines = [`[plugin] ${report.errors.length} hook failure(s):`];
+  for (const e of report.errors) {
+    lines.push(`  - ${e.hook} in ${e.source}: ${e.error.message}`);
+  }
+  return lines.join("\n");
+}

package/src/router/fs-routes.ts

@@ -13,6 +13,11 @@ import type { FSRouteConfig, FSScannerConfig, ScanResult } from "./fs-types";
 import { DEFAULT_SCANNER_CONFIG } from "./fs-types";
 import { scanRoutes } from "./fs-scanner";
 import { loadManduConfig } from "../config";
+import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
+import {
+  runOnRouteRegistered,
+  runOnManifestBuilt,
+} from "../plugins/runner";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Types
@@ -41,6 +46,20 @@ export interface GenerateOptions {
 
   /** 출력 파일 경로 (지정 시 파일로 저장) */
   outputPath?: string;
+
+  /**
+   * Phase 18.τ — optional plugins + config-level hooks bundle.
+   *
+   * When provided, `generateManifest()` fires two plugin hooks:
+   *   - `onRouteRegistered(route)` — once per scanned route.
+   *   - `onManifestBuilt(manifest)` — after assembly, BEFORE the
+   *     manifest is written to disk. A plugin may return a mutated
+   *     manifest (pipe semantics across plugins).
+   *
+   * Omitted → zero overhead, identical to pre-τ behaviour.
+   */
+  plugins?: readonly ManduPlugin[];
+  configHooks?: Partial<ManduHooks>;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -244,12 +263,36 @@ export async function generateManifest(
   }
 
   // FS Routes 매니페스트 생성
-  const manifest = scanResultToManifest(scanResult);
+  let manifest = scanResultToManifest(scanResult);
   const warnings: string[] = [];
 
   // Auto-linking: spec/slots/, spec/contracts/ 자동 연결
   await resolveAutoLinks(manifest, rootDir);
 
+  // Phase 18.τ — fire plugin hooks AFTER auto-linking so plugins see the
+  // final RouteSpec (including slot/contract/client modules). Both hooks
+  // are opt-in; zero-overhead when `options.plugins` / `options.configHooks`
+  // are omitted.
+  const pluginArgs = {
+    plugins: options.plugins ?? [],
+    configHooks: options.configHooks,
+  };
+  if (pluginArgs.plugins.length > 0 || pluginArgs.configHooks) {
+    for (const route of manifest.routes) {
+      const { errors } = await runOnRouteRegistered(route, pluginArgs);
+      for (const e of errors) {
+        warnings.push(
+          `onRouteRegistered[${e.source}] ${route.id}: ${e.error.message}`
+        );
+      }
+    }
+    const manifestReport = await runOnManifestBuilt(manifest, pluginArgs);
+    manifest = manifestReport.result;
+    for (const e of manifestReport.errors) {
+      warnings.push(`onManifestBuilt[${e.source}]: ${e.error.message}`);
+    }
+  }
+
   // 기존 매니페스트에서 사용자 설정 필드 보존 (clientModule, hydration 등)
   const outputPath = options.outputPath ?? ".mandu/routes.manifest.json";
   const outputFullPath = join(rootDir, outputPath);
@@ -272,6 +315,26 @@ export async function generateManifest(
         if (prev.hydration && !route.hydration) {
           route.hydration = prev.hydration;
         }
+        // Issue #214 — preserve prerender-time fields (`dynamicParams`,
+        // `staticParams`) across manifest rescans. `mandu build`'s prerender
+        // phase stamps these onto the manifest; a subsequent `mandu dev`
+        // rescan must not wipe them out.
+        if (route.kind === "page" && prev.kind === "page") {
+          const prevPage = prev as typeof prev & {
+            dynamicParams?: boolean;
+            staticParams?: unknown[];
+          };
+          const routePage = route as typeof route & {
+            dynamicParams?: boolean;
+            staticParams?: unknown[];
+          };
+          if (prevPage.dynamicParams !== undefined && routePage.dynamicParams === undefined) {
+            routePage.dynamicParams = prevPage.dynamicParams;
+          }
+          if (prevPage.staticParams !== undefined && routePage.staticParams === undefined) {
+            routePage.staticParams = prevPage.staticParams;
+          }
+        }
       }
     }
   } catch {

package/src/router/fs-scanner.ts

@@ -619,6 +619,107 @@ function escapeRegex(char: string): string {
   return /[\\^$.*+?()[\]{}|]/.test(char) ? `\\${char}` : char;
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 18.μ — i18n path-prefix route synthesis
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Options for {@link synthesizeLocaleRoutes}. Mirrors the relevant subset
+ * of `I18nDefinition` so callers don't need to pull the whole
+ * `@mandujs/core/i18n` surface into pure-router code paths.
+ */
+export interface LocaleSynthesisOptions {
+  /** Allow-list of locale codes to materialize. */
+  locales: readonly string[];
+  /** Default locale — its routes stay unprefixed (Next.js parity). */
+  defaultLocale: string;
+}
+
+/**
+ * Phase 18.μ — synthesize per-locale route variants at manifest-build
+ * time. Given a set of scanned routes, produces `locales.length` copies
+ * for every `page` / `api` route with a locale prefix baked into
+ * `id` + `pattern`. The default locale's routes are emitted unprefixed
+ * (so legacy links keep working and SEO stays intact).
+ *
+ * The synthesis is pure: it re-uses existing `FSRouteConfig` objects as
+ * source of truth, producing *new* objects with:
+ *
+ *   - `pattern`    : `/en/blog/:slug`
+ *   - `id`         : `en::<original-id>`
+ *   - `module`     : unchanged (same loader on disk)
+ *   - everything else: shallow-copied
+ *
+ * Metadata routes (sitemap/robots/llms-txt/manifest) are NOT duplicated —
+ * they always sit at site root regardless of locale (same SEO rule as
+ * Next.js).
+ *
+ * The caller is responsible for passing the output through
+ * {@link sortRoutesByPriority} before writing the manifest.
+ *
+ * @example
+ * ```ts
+ * const scan = await scanRoutes(rootDir);
+ * const prefixed = synthesizeLocaleRoutes(scan.routes, {
+ *   locales: ["en", "ko"],
+ *   defaultLocale: "en",
+ * });
+ * // scan.routes   : [/, /blog, /blog/:slug]
+ * // prefixed      : [/, /blog, /blog/:slug, /ko, /ko/blog, /ko/blog/:slug]
+ * ```
+ */
+export function synthesizeLocaleRoutes(
+  routes: FSRouteConfig[],
+  options: LocaleSynthesisOptions
+): FSRouteConfig[] {
+  const { locales, defaultLocale } = options;
+  if (!Array.isArray(locales) || locales.length === 0) return [...routes];
+  if (!locales.includes(defaultLocale)) {
+    throw new Error(
+      `[router] synthesizeLocaleRoutes: defaultLocale "${defaultLocale}" not in locales [${locales.join(", ")}]`
+    );
+  }
+
+  const out: FSRouteConfig[] = [];
+  for (const route of routes) {
+    // Metadata routes live at site root; never prefix them.
+    if (route.kind === "metadata") {
+      out.push(route);
+      continue;
+    }
+
+    // Default locale: unprefixed copy preserved verbatim (legacy +
+    // SEO neutral).
+    out.push(route);
+
+    for (const locale of locales) {
+      if (locale === defaultLocale) continue;
+      const prefixed = prefixRouteWithLocale(route, locale);
+      out.push(prefixed);
+    }
+  }
+  return out;
+}
+
+function prefixRouteWithLocale(route: FSRouteConfig, locale: string): FSRouteConfig {
+  const prefixedPattern = route.pattern === "/"
+    ? `/${locale}`
+    : `/${locale}${route.pattern.startsWith("/") ? route.pattern : `/${route.pattern}`}`;
+
+  return {
+    ...route,
+    id: `${locale}::${route.id}`,
+    pattern: prefixedPattern,
+    // `segments` is used for priority calculation + layout resolution;
+    // prepending a static locale segment keeps priority sensible and
+    // avoids collisions with real `[param]` segments.
+    segments: [
+      { raw: locale, type: "static" },
+      ...route.segments,
+    ],
+  };
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Factory Function
 // ═══════════════════════════════════════════════════════════════════════════

package/src/router/index.ts

@@ -68,7 +68,13 @@ export {
 } from "./fs-patterns";
 
 // Scanner
-export { FSScanner, createFSScanner, scanRoutes } from "./fs-scanner";
+export {
+  FSScanner,
+  createFSScanner,
+  scanRoutes,
+  synthesizeLocaleRoutes,
+  type LocaleSynthesisOptions,
+} from "./fs-scanner";
 
 // Generator
 export type { FSGenerateResult, GenerateOptions, RouteChangeCallback, FSRoutesWatcher } from "./fs-routes";