@mandujs/core 0.32.0 → 0.33.1

package/src/plugins/hooks.ts

@@ -1,64 +1,297 @@
-/**
- * CLI Lifecycle Hook System
- *
- * Lightweight hook runner for build/dev/start lifecycle events.
- * Hooks defined in mandu.config.ts run first, then plugin hooks
- * in registration order. Each hook is isolated -- one failure
- * does not block subsequent hooks.
- */
-
-export interface ManduHooks {
-  onBeforeBuild?: () => void | Promise<void>;
-  onAfterBuild?: (result: { success: boolean; duration: number }) => void | Promise<void>;
-  onDevStart?: (info: { port: number; hostname: string }) => void | Promise<void>;
-  onDevStop?: () => void | Promise<void>;
-  onRouteChange?: (info: { routeId: string; pattern: string; kind: string }) => void | Promise<void>;
-  onBeforeStart?: () => void | Promise<void>;
-}
-
-export interface ManduPlugin {
-  name: string;
-  hooks?: Partial<ManduHooks>;
-  setup?: (config: Record<string, unknown>) => void | Promise<void>;
-}
-
-/**
- * Run a named lifecycle hook across config-level hooks and plugins.
- *
- * Execution order:
- *   1. Config hook (from mandu.config.ts `hooks` field)
- *   2. Plugin hooks (from `plugins[].hooks`, in array order)
- *
- * Each invocation is wrapped in try/catch so a single failing hook
- * does not prevent the remaining hooks from executing.
- */
-export async function runHook<K extends keyof ManduHooks>(
-  hookName: K,
-  plugins: ManduPlugin[],
-  configHooks: Partial<ManduHooks> | undefined,
-  ...args: Parameters<NonNullable<ManduHooks[K]>>
-): Promise<void> {
-  const invoke = async (
-    label: string,
-    fn: ((...a: unknown[]) => void | Promise<void>) | undefined,
-  ) => {
-    if (!fn) return;
-    try {
-      await fn(...args);
-    } catch (error) {
-      const msg = error instanceof Error ? error.message : String(error);
-      console.error(`[plugin] ${hookName} failed in ${label}: ${msg}`);
-    }
-  };
-
-  // Config-level hook runs first
-  await invoke("config", configHooks?.[hookName] as ((...a: unknown[]) => void | Promise<void>) | undefined);
-
-  // Plugin hooks run in registration order
-  for (const plugin of plugins) {
-    await invoke(
-      plugin.name,
-      plugin.hooks?.[hookName] as ((...a: unknown[]) => void | Promise<void>) | undefined,
-    );
-  }
-}
+/**
+ * CLI Lifecycle Hook System — Phase 18.τ expansion.
+ *
+ * The original `ManduHooks` surface covered a few coarse lifecycle points
+ * (`onBeforeBuild`, `onAfterBuild`, `onDevStart`, `onDevStop`,
+ * `onRouteChange`, `onBeforeStart`). Phase 18.τ extends it so consumers
+ * can extend the bundler / prerender / middleware / router pipeline
+ * without forking the core. Every new hook is **optional** and defaults
+ * to "no-op" — existing plugins remain source-compatible.
+ *
+ * Contract:
+ *   - Each hook is isolated: one failure does not block subsequent hooks.
+ *   - Config-level hooks run first, plugin hooks run in declaration order.
+ *   - Hooks that "return a value" (e.g. `definePrerenderHook`,
+ *     `onManifestBuilt`, `defineTestTransform`, `defineMiddlewareChain`,
+ *     `defineBundlerPlugin`) compose via documented merge semantics
+ *     implemented in `./runner.ts`.
+ *
+ * The canonical runner lives in `./runner.ts`. The legacy `runHook()` in
+ * this file remains for back-compat with callers that already wire the
+ * original coarse hooks.
+ *
+ * @see `docs/architect/plugin-api.md`
+ */
+
+import type { BunPlugin } from "bun";
+import type { Middleware } from "../middleware/define";
+import type { BundleStats } from "../bundler/types";
+import type { RouteSpec, RoutesManifest } from "../spec/schema";
+
+// ═══════════════════════════════════════════════════════════════════════
+// Contexts exposed to plugin hooks
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Shared context every hook receives. Kept intentionally small so
+ * plugins do not couple to internals that are not part of the stable API.
+ */
+export interface PluginContext {
+  /** Absolute project root directory. */
+  rootDir: string;
+  /** `"development"` during `mandu dev`, `"production"` during `mandu build`. */
+  mode: "development" | "production";
+  /** Plugin-scoped logger — honours the framework's structured log format. */
+  logger: {
+    debug: (msg: string, data?: unknown) => void;
+    info: (msg: string, data?: unknown) => void;
+    warn: (msg: string, data?: unknown) => void;
+    error: (msg: string, data?: unknown) => void;
+  };
+}
+
+/**
+ * Context passed to `definePrerenderHook`. A plugin may inspect the
+ * pathname / params / HTML being emitted and return a {@link PrerenderOverride}
+ * to skip, rewrite, or replace the output.
+ */
+export interface PrerenderContext extends PluginContext {
+  /** The URL pathname being prerendered (e.g. `/blog/hello-world`). */
+  pathname: string;
+  /** The route pattern (e.g. `/blog/:slug`) that matched. `undefined` for free-form `routes[]` paths. */
+  pattern?: string;
+  /** Dynamic params extracted from the pattern, when available. */
+  params?: Record<string, string>;
+  /**
+   * The HTML the fetch handler produced. Plugins may return a mutated
+   * copy via {@link PrerenderOverride.html}.
+   */
+  html: string;
+}
+
+/**
+ * Return value of `definePrerenderHook`. All fields are optional; the
+ * first plugin to set a field "wins" (later plugins in the chain may
+ * override via the same field — last-write semantics documented in the
+ * runner).
+ */
+export interface PrerenderOverride {
+  /**
+   * When `true`, the page is removed from the prerender output entirely.
+   * The runtime will fall back to SSR for that URL.
+   */
+  skip?: boolean;
+  /** Replacement HTML. Passed verbatim to `fs.writeFile`. */
+  html?: string;
+  /**
+   * Rewrite the output pathname. Useful for e.g. writing `/about` to
+   * `/about.html` for static hosts that need explicit extensions.
+   */
+  pathname?: string;
+}
+
+/**
+ * Pair passed to `defineTestTransform`. Plugins return the new source
+ * string (or a Promise thereof). Returning the original `source`
+ * unchanged is a legal no-op.
+ */
+export interface TestTransformContext {
+  /** Absolute path of the test file being processed. */
+  testFile: string;
+  /** Current source (may already be transformed by an earlier plugin). */
+  source: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Hook surface — the plugin authoring contract
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Full `ManduHooks` surface. Every hook is optional; the runner gracefully
+ * skips undefined entries. Hooks fall into three categories:
+ *
+ *   1. **Observers** — `onBeforeBuild`, `onAfterBuild`, `onDevStart`,
+ *      `onDevStop`, `onRouteChange`, `onBeforeStart`, `onRouteRegistered`,
+ *      `onBundleComplete`. Return value is ignored.
+ *
+ *   2. **Contributors** — `defineBundlerPlugin`, `defineMiddlewareChain`,
+ *      `defineTestTransform`. The runner collects return values from all
+ *      plugins and concatenates / pipes them (see merge semantics in
+ *      `./runner.ts`).
+ *
+ *   3. **Transformers** — `definePrerenderHook`, `onManifestBuilt`. The
+ *      runner folds the return value back into subsequent hook invocations
+ *      (last non-undefined return wins).
+ */
+export interface ManduHooks {
+  // ───── Legacy lifecycle observers (kept for back-compat) ─────
+  onBeforeBuild?: () => void | Promise<void>;
+  onAfterBuild?: (result: {
+    success: boolean;
+    duration: number;
+  }) => void | Promise<void>;
+  onDevStart?: (info: {
+    port: number;
+    hostname: string;
+  }) => void | Promise<void>;
+  onDevStop?: () => void | Promise<void>;
+  onRouteChange?: (info: {
+    routeId: string;
+    pattern: string;
+    kind: string;
+  }) => void | Promise<void>;
+  onBeforeStart?: () => void | Promise<void>;
+
+  // ───── Phase 18.τ — router / manifest ─────
+
+  /**
+   * Fires once per route as the FS scanner discovers it. Pure observer —
+   * throwing does not abort the scan; the runner isolates the error and
+   * proceeds. Useful for dependency audits, custom guards, or telemetry.
+   */
+  onRouteRegistered?: (route: RouteSpec) => void | Promise<void>;
+
+  /**
+   * Fires after the routes manifest is built but before it is persisted
+   * to `.mandu/manifest.json`. A plugin may return a mutated manifest;
+   * subsequent plugins see the mutated form ("pipe" semantics).
+   */
+  onManifestBuilt?: (
+    manifest: RoutesManifest
+  ) => RoutesManifest | Promise<RoutesManifest | void> | void;
+
+  // ───── Phase 18.τ — bundler ─────
+
+  /**
+   * Contribute additional `BunPlugin` entries to every `Bun.build` call
+   * issued by the bundler (runtime / router / vendor / island paths).
+   * May return a single plugin or an array. The returned plugins run
+   * AFTER Mandu's default plugins so user transforms see already-resolved
+   * imports.
+   */
+  defineBundlerPlugin?: () =>
+    | BunPlugin
+    | BunPlugin[]
+    | Promise<BunPlugin | BunPlugin[]>;
+
+  /**
+   * Fires once per successful `buildClientBundles()` completion with the
+   * final `BundleStats`. Purely observational — used for analytics,
+   * size-budget enforcement, report emission, etc. Throwing does not
+   * invalidate the build; the error is logged and swallowed.
+   */
+  onBundleComplete?: (stats: BundleStats) => void | Promise<void>;
+
+  // ───── Phase 18.τ — prerender ─────
+
+  /**
+   * Intercept each prerender step. The runner calls every plugin's
+   * hook in declaration order; returns are merged field-by-field with
+   * last-write semantics. A plugin may short-circuit by returning
+   * `{ skip: true }` — subsequent plugins still see the skip flag and
+   * may unset it.
+   */
+  definePrerenderHook?: (
+    ctx: PrerenderContext
+  ) => PrerenderOverride | void | Promise<PrerenderOverride | void>;
+
+  // ───── Phase 18.τ — middleware / test ─────
+
+  /**
+   * Contribute additional request-level middleware to the global chain
+   * (prepended — runs BEFORE user-declared `ManduConfig.middleware`).
+   * Returns are concatenated across all plugins in declaration order.
+   *
+   * Bridge wrappers like `csrfMiddleware()` / `sessionMiddleware()`
+   * compose naturally here. See `@mandujs/core/middleware`.
+   */
+  defineMiddlewareChain?: (
+    ctx: PluginContext
+  ) => Middleware[] | Promise<Middleware[]>;
+
+  /**
+   * Transform test source before execution (Phase 12.1 `mandu test`).
+   * Returns the new source string — returning the original input is a
+   * legal no-op. Multiple plugins pipe through in declaration order:
+   * each plugin sees the source produced by the previous one.
+   */
+  defineTestTransform?: (
+    ctx: TestTransformContext
+  ) => string | Promise<string>;
+}
+
+/**
+ * A Mandu plugin — a named object with optional `hooks` + `setup`.
+ *
+ * Construct with {@link definePlugin} (from `./define.ts`) for validation
+ * at definition time, or inline as a plain object literal — both work.
+ */
+export interface ManduPlugin {
+  /** Plugin identifier shown in diagnostics. Must be unique per config. */
+  name: string;
+  /** Optional hook implementations. */
+  hooks?: Partial<ManduHooks>;
+  /**
+   * One-shot setup hook. Called once at `loadPlugins()` time with the
+   * plugin's slice of the user config (if any). Useful for registering
+   * resources, opening files, or spinning up background workers.
+   */
+  setup?: (config: Record<string, unknown>) => void | Promise<void>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Legacy coarse runner — preserved for back-compat
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Run a named lifecycle hook across config-level hooks and plugins.
+ *
+ * Execution order:
+ *   1. Config hook (from mandu.config.ts `hooks` field)
+ *   2. Plugin hooks (from `plugins[].hooks`, in array order)
+ *
+ * Each invocation is wrapped in try/catch so a single failing hook
+ * does not prevent the remaining hooks from executing.
+ *
+ * This is a thin observer-only runner — hook return values are ignored.
+ * For transforming / contributing hooks (e.g. `definePrerenderHook`,
+ * `onManifestBuilt`, `defineBundlerPlugin`) use the canonical runner in
+ * `./runner.ts`.
+ */
+export async function runHook<K extends keyof ManduHooks>(
+  hookName: K,
+  plugins: ManduPlugin[],
+  configHooks: Partial<ManduHooks> | undefined,
+  ...args: Parameters<NonNullable<ManduHooks[K]>>
+): Promise<void> {
+  const invoke = async (
+    label: string,
+    fn: ((...a: unknown[]) => void | Promise<void>) | undefined,
+  ) => {
+    if (!fn) return;
+    try {
+      await fn(...args);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      console.error(`[plugin] ${hookName} failed in ${label}: ${msg}`);
+    }
+  };
+
+  // Config-level hook runs first
+  await invoke(
+    "config",
+    configHooks?.[hookName] as
+      | ((...a: unknown[]) => void | Promise<void>)
+      | undefined,
+  );
+
+  // Plugin hooks run in registration order
+  for (const plugin of plugins) {
+    await invoke(
+      plugin.name,
+      plugin.hooks?.[hookName] as
+        | ((...a: unknown[]) => void | Promise<void>)
+        | undefined,
+    );
+  }
+}

package/src/plugins/index.ts

@@ -1,41 +1,80 @@
-/**
- * DNA-001: Plugin System
- *
- * Mandu 플러그인 시스템
- * - Guard 프리셋 플러그인
- * - 빌드 플러그인
- * - 로거 전송 플러그인
- * - MCP 도구 플러그인
- * - 미들웨어 플러그인
- */
-
-export {
-  PluginRegistry,
-  globalPluginRegistry,
-  definePlugin,
-} from "./registry";
-
-export type {
-  Plugin,
-  PluginApi,
-  PluginCategory,
-  PluginMeta,
-  PluginHooks,
-  GuardPresetPlugin,
-  GuardRule,
-  GuardRuleContext,
-  PluginGuardViolation,
-  LayerDefinition,
-  ImportInfo,
-  ExportInfo,
-  BuildPlugin,
-  BuildContext,
-  BuildResult,
-  LoggerTransportPlugin,
-  LogEntry,
-  McpToolPlugin,
-  MiddlewarePlugin,
-} from "./types";
-
-export { runHook } from "./hooks";
-export type { ManduPlugin, ManduHooks } from "./hooks";
+/**
+ * DNA-001: Plugin System
+ *
+ * Mandu 플러그인 시스템
+ * - Guard 프리셋 플러그인
+ * - 빌드 플러그인
+ * - 로거 전송 플러그인
+ * - MCP 도구 플러그인
+ * - 미들웨어 플러그인
+ *
+ * Phase 18.τ — expanded `ManduPlugin` hook surface (bundler / prerender /
+ * middleware / test pipeline). The lightweight `definePlugin()` helper
+ * for that shape lives in `./define.ts` and is re-exported as
+ * `defineManduPlugin` to avoid colliding with the legacy heavy
+ * `Plugin`-type `definePlugin` from `./registry.ts`.
+ *
+ * @see `./hooks.ts` for the typed hook surface.
+ * @see `./runner.ts` for canonical dispatch + merge semantics.
+ * @see `docs/architect/plugin-api.md`.
+ */
+
+export {
+  PluginRegistry,
+  globalPluginRegistry,
+  definePlugin,
+} from "./registry";
+
+export type {
+  Plugin,
+  PluginApi,
+  PluginCategory,
+  PluginMeta,
+  PluginHooks,
+  GuardPresetPlugin,
+  GuardRule,
+  GuardRuleContext,
+  PluginGuardViolation,
+  LayerDefinition,
+  ImportInfo,
+  ExportInfo,
+  BuildPlugin,
+  BuildContext,
+  BuildResult,
+  LoggerTransportPlugin,
+  LogEntry,
+  McpToolPlugin,
+  MiddlewarePlugin,
+} from "./types";
+
+export { runHook } from "./hooks";
+export type {
+  ManduPlugin,
+  ManduHooks,
+  PluginContext,
+  PrerenderContext,
+  PrerenderOverride,
+  TestTransformContext,
+} from "./hooks";
+
+// Phase 18.τ — canonical hook runner + lightweight definePlugin helper.
+export {
+  runOnRouteRegistered,
+  runOnManifestBuilt,
+  runOnBundleComplete,
+  runDefineBundlerPlugin,
+  runDefinePrerenderHook,
+  runDefineMiddlewareChain,
+  runDefineTestTransform,
+  resolvePluginMiddleware,
+  formatHookErrors,
+  type HookError,
+  type HookRunReport,
+  type RunnerArgs,
+} from "./runner";
+
+// Rename to avoid symbol collision with the legacy `definePlugin` helper
+// (which takes the heavier `Plugin` type and is used by the built-in
+// registry). `defineManduPlugin` is the go-to helper for the modern
+// lightweight `ManduPlugin` shape introduced in Phase 18.τ.
+export { definePlugin as defineManduPlugin, isManduPlugin } from "./define";