@mandujs/core 0.53.3 → 0.54.1

package/src/plugins/define.ts

@@ -1,124 +1,124 @@
-/**
- * Ergonomic helper for authoring `ManduPlugin` objects — Phase 18.τ.
- *
- * Passes the plugin through unchanged while validating the shape at
- * definition time. Fail-fast is critical: a plugin that silently
- * corrupts the hook chain (e.g. typo on the hook name, non-function
- * `setup`) is nearly impossible to diagnose from a 5xx log line.
- *
- * Importable from the `@mandujs/core/plugins/define` subpath so users
- * who only want the lightweight plugin API do not pull the whole
- * `@mandujs/core/plugins` surface (registry + categories + etc.) into
- * their dependency graph.
- *
- * @example
- * ```ts
- * import { definePlugin } from "@mandujs/core/plugins/define";
- *
- * export const sitemap = definePlugin({
- *   name: "sitemap",
- *   hooks: {
- *     async onManifestBuilt(manifest) {
- *       await writeSitemap(manifest);
- *     },
- *   },
- * });
- * ```
- *
- * @throws {TypeError} when `name` is missing / empty, `hooks` isn't an
- *   object, or `setup` isn't a function. These errors fire at import
- *   time so bad plugins never reach production.
- */
-
-import type { ManduHooks, ManduPlugin } from "./hooks";
-
-/**
- * Known hook names — used to catch `onRouteRegitered` style typos at
- * definition time. Kept in a runtime-visible array so adding a hook to
- * `ManduHooks` only requires one diff instead of two.
- */
-const KNOWN_HOOK_NAMES: ReadonlyArray<keyof ManduHooks> = [
-  // Legacy lifecycle
-  "onBeforeBuild",
-  "onAfterBuild",
-  "onDevStart",
-  "onDevStop",
-  "onRouteChange",
-  "onBeforeStart",
-  // Phase 18.τ
-  "onRouteRegistered",
-  "onManifestBuilt",
-  "defineBundlerPlugin",
-  "onBundleComplete",
-  "definePrerenderHook",
-  "defineMiddlewareChain",
-  "defineTestTransform",
-];
-
-/**
- * Validate + pass through a `ManduPlugin`. Use at export time:
- *
- * ```ts
- * export default definePlugin({ name: "my-plugin", hooks: { ... } });
- * ```
- *
- * The returned value is `===` the input — the helper does not clone,
- * wrap, or freeze the object, so users retain full control over the
- * plugin instance (e.g. swapping hooks at runtime for tests).
- */
-export function definePlugin(plugin: ManduPlugin): ManduPlugin {
-  if (!plugin || typeof plugin !== "object") {
-    throw new TypeError(
-      "[Mandu Plugin] definePlugin() requires a plugin object"
-    );
-  }
-  if (typeof plugin.name !== "string" || plugin.name.length === 0) {
-    throw new TypeError(
-      "[Mandu Plugin] definePlugin() requires a non-empty `name` string"
-    );
-  }
-
-  if (plugin.hooks !== undefined) {
-    if (typeof plugin.hooks !== "object" || plugin.hooks === null) {
-      throw new TypeError(
-        `[Mandu Plugin "${plugin.name}"] hooks must be an object`
-      );
-    }
-    for (const key of Object.keys(plugin.hooks)) {
-      const asHookKey = key as keyof ManduHooks;
-      if (!KNOWN_HOOK_NAMES.includes(asHookKey)) {
-        throw new TypeError(
-          `[Mandu Plugin "${plugin.name}"] unknown hook "${key}". Known hooks: ${KNOWN_HOOK_NAMES.join(", ")}`
-        );
-      }
-      const fn = (plugin.hooks as Record<string, unknown>)[key];
-      if (fn !== undefined && typeof fn !== "function") {
-        throw new TypeError(
-          `[Mandu Plugin "${plugin.name}"] hook "${key}" must be a function (got ${typeof fn})`
-        );
-      }
-    }
-  }
-
-  if (plugin.setup !== undefined && typeof plugin.setup !== "function") {
-    throw new TypeError(
-      `[Mandu Plugin "${plugin.name}"] setup must be a function when provided (got ${typeof plugin.setup})`
-    );
-  }
-
-  return plugin;
-}
-
-/**
- * Type guard for runtime checks (e.g. in `validate.ts`).
- */
-export function isManduPlugin(value: unknown): value is ManduPlugin {
-  if (!value || typeof value !== "object") return false;
-  const v = value as Record<string, unknown>;
-  if (typeof v.name !== "string" || v.name.length === 0) return false;
-  if (v.hooks !== undefined && (typeof v.hooks !== "object" || v.hooks === null)) {
-    return false;
-  }
-  if (v.setup !== undefined && typeof v.setup !== "function") return false;
-  return true;
-}
+/**
+ * Ergonomic helper for authoring `ManduPlugin` objects — Phase 18.τ.
+ *
+ * Passes the plugin through unchanged while validating the shape at
+ * definition time. Fail-fast is critical: a plugin that silently
+ * corrupts the hook chain (e.g. typo on the hook name, non-function
+ * `setup`) is nearly impossible to diagnose from a 5xx log line.
+ *
+ * Importable from the `@mandujs/core/plugins/define` subpath so users
+ * who only want the lightweight plugin API do not pull the whole
+ * `@mandujs/core/plugins` surface (registry + categories + etc.) into
+ * their dependency graph.
+ *
+ * @example
+ * ```ts
+ * import { definePlugin } from "@mandujs/core/plugins/define";
+ *
+ * export const sitemap = definePlugin({
+ *   name: "sitemap",
+ *   hooks: {
+ *     async onManifestBuilt(manifest) {
+ *       await writeSitemap(manifest);
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @throws {TypeError} when `name` is missing / empty, `hooks` isn't an
+ *   object, or `setup` isn't a function. These errors fire at import
+ *   time so bad plugins never reach production.
+ */
+
+import type { ManduHooks, ManduPlugin } from "./hooks";
+
+/**
+ * Known hook names — used to catch `onRouteRegitered` style typos at
+ * definition time. Kept in a runtime-visible array so adding a hook to
+ * `ManduHooks` only requires one diff instead of two.
+ */
+const KNOWN_HOOK_NAMES: ReadonlyArray<keyof ManduHooks> = [
+  // Legacy lifecycle
+  "onBeforeBuild",
+  "onAfterBuild",
+  "onDevStart",
+  "onDevStop",
+  "onRouteChange",
+  "onBeforeStart",
+  // Phase 18.τ
+  "onRouteRegistered",
+  "onManifestBuilt",
+  "defineBundlerPlugin",
+  "onBundleComplete",
+  "definePrerenderHook",
+  "defineMiddlewareChain",
+  "defineTestTransform",
+];
+
+/**
+ * Validate + pass through a `ManduPlugin`. Use at export time:
+ *
+ * ```ts
+ * export default definePlugin({ name: "my-plugin", hooks: { ... } });
+ * ```
+ *
+ * The returned value is `===` the input — the helper does not clone,
+ * wrap, or freeze the object, so users retain full control over the
+ * plugin instance (e.g. swapping hooks at runtime for tests).
+ */
+export function definePlugin(plugin: ManduPlugin): ManduPlugin {
+  if (!plugin || typeof plugin !== "object") {
+    throw new TypeError(
+      "[Mandu Plugin] definePlugin() requires a plugin object"
+    );
+  }
+  if (typeof plugin.name !== "string" || plugin.name.length === 0) {
+    throw new TypeError(
+      "[Mandu Plugin] definePlugin() requires a non-empty `name` string"
+    );
+  }
+
+  if (plugin.hooks !== undefined) {
+    if (typeof plugin.hooks !== "object" || plugin.hooks === null) {
+      throw new TypeError(
+        `[Mandu Plugin "${plugin.name}"] hooks must be an object`
+      );
+    }
+    for (const key of Object.keys(plugin.hooks)) {
+      const asHookKey = key as keyof ManduHooks;
+      if (!KNOWN_HOOK_NAMES.includes(asHookKey)) {
+        throw new TypeError(
+          `[Mandu Plugin "${plugin.name}"] unknown hook "${key}". Known hooks: ${KNOWN_HOOK_NAMES.join(", ")}`
+        );
+      }
+      const fn = (plugin.hooks as Record<string, unknown>)[key];
+      if (fn !== undefined && typeof fn !== "function") {
+        throw new TypeError(
+          `[Mandu Plugin "${plugin.name}"] hook "${key}" must be a function (got ${typeof fn})`
+        );
+      }
+    }
+  }
+
+  if (plugin.setup !== undefined && typeof plugin.setup !== "function") {
+    throw new TypeError(
+      `[Mandu Plugin "${plugin.name}"] setup must be a function when provided (got ${typeof plugin.setup})`
+    );
+  }
+
+  return plugin;
+}
+
+/**
+ * Type guard for runtime checks (e.g. in `validate.ts`).
+ */
+export function isManduPlugin(value: unknown): value is ManduPlugin {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.name !== "string" || v.name.length === 0) return false;
+  if (v.hooks !== undefined && (typeof v.hooks !== "object" || v.hooks === null)) {
+    return false;
+  }
+  if (v.setup !== undefined && typeof v.setup !== "function") return false;
+  return true;
+}

package/src/plugins/examples/dep-check-plugin.ts

@@ -1,80 +1,80 @@
-/**
- * Example plugin: dependency gate.
- *
- * Demonstrates `onRouteRegistered` — we read each route's source file
- * and warn (or throw) when it imports from a forbidden package. Useful
- * for keeping e.g. `node:fs` out of edge-bound routes.
- *
- * Educational only. A production-ready version would use the module
- * graph from the bundler rather than a line-wise regex scan.
- *
- * @example
- * ```ts
- * export default {
- *   plugins: [
- *     depCheckPlugin({
- *       forbidden: ["node:fs", "node:child_process"],
- *       severity: "error",
- *     }),
- *   ],
- * } satisfies ManduConfig;
- * ```
- */
-
-import { readFile } from "fs/promises";
-import path from "path";
-import { definePlugin } from "../define";
-import type { ManduPlugin } from "../hooks";
-
-export interface DepCheckPluginOptions {
-  /** Bare-specifier prefixes that routes must NOT import. */
-  forbidden: readonly string[];
-  /**
-   * How to react to a violation:
-   *   - `"warn"` (default) — log to stderr.
-   *   - `"error"` — throw. The runner captures the error per-route so
-   *     other plugins still run, but the CLI sees a non-empty errors
-   *     array in `FSGenerateResult.warnings`.
-   */
-  severity?: "warn" | "error";
-}
-
-export function depCheckPlugin(options: DepCheckPluginOptions): ManduPlugin {
-  const { forbidden, severity = "warn" } = options;
-
-  return definePlugin({
-    name: "dep-check",
-    hooks: {
-      async onRouteRegistered(route) {
-        const modulePath = path.resolve(process.cwd(), route.module);
-        let source: string;
-        try {
-          source = await readFile(modulePath, "utf-8");
-        } catch {
-          return; // Module not readable — not a gate concern.
-        }
-        const offenders: string[] = [];
-        const importRegex =
-          /(?:import|from|require)\s*\(?\s*["']([^"']+)["']/g;
-        for (const match of source.matchAll(importRegex)) {
-          const specifier = match[1];
-          for (const f of forbidden) {
-            if (specifier === f || specifier.startsWith(`${f}/`)) {
-              offenders.push(specifier);
-              break;
-            }
-          }
-        }
-        if (offenders.length === 0) return;
-
-        const message =
-          `[dep-check] route ${route.id} (${route.module}) imports forbidden ` +
-          `specifiers: ${offenders.join(", ")}`;
-        if (severity === "error") {
-          throw new Error(message);
-        }
-        console.warn(message);
-      },
-    },
-  });
-}
+/**
+ * Example plugin: dependency gate.
+ *
+ * Demonstrates `onRouteRegistered` — we read each route's source file
+ * and warn (or throw) when it imports from a forbidden package. Useful
+ * for keeping e.g. `node:fs` out of edge-bound routes.
+ *
+ * Educational only. A production-ready version would use the module
+ * graph from the bundler rather than a line-wise regex scan.
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   plugins: [
+ *     depCheckPlugin({
+ *       forbidden: ["node:fs", "node:child_process"],
+ *       severity: "error",
+ *     }),
+ *   ],
+ * } satisfies ManduConfig;
+ * ```
+ */
+
+import { readFile } from "fs/promises";
+import path from "path";
+import { definePlugin } from "../define";
+import type { ManduPlugin } from "../hooks";
+
+export interface DepCheckPluginOptions {
+  /** Bare-specifier prefixes that routes must NOT import. */
+  forbidden: readonly string[];
+  /**
+   * How to react to a violation:
+   *   - `"warn"` (default) — log to stderr.
+   *   - `"error"` — throw. The runner captures the error per-route so
+   *     other plugins still run, but the CLI sees a non-empty errors
+   *     array in `FSGenerateResult.warnings`.
+   */
+  severity?: "warn" | "error";
+}
+
+export function depCheckPlugin(options: DepCheckPluginOptions): ManduPlugin {
+  const { forbidden, severity = "warn" } = options;
+
+  return definePlugin({
+    name: "dep-check",
+    hooks: {
+      async onRouteRegistered(route) {
+        const modulePath = path.resolve(process.cwd(), route.module);
+        let source: string;
+        try {
+          source = await readFile(modulePath, "utf-8");
+        } catch {
+          return; // Module not readable — not a gate concern.
+        }
+        const offenders: string[] = [];
+        const importRegex =
+          /(?:import|from|require)\s*\(?\s*["']([^"']+)["']/g;
+        for (const match of source.matchAll(importRegex)) {
+          const specifier = match[1];
+          for (const f of forbidden) {
+            if (specifier === f || specifier.startsWith(`${f}/`)) {
+              offenders.push(specifier);
+              break;
+            }
+          }
+        }
+        if (offenders.length === 0) return;
+
+        const message =
+          `[dep-check] route ${route.id} (${route.module}) imports forbidden ` +
+          `specifiers: ${offenders.join(", ")}`;
+        if (severity === "error") {
+          throw new Error(message);
+        }
+        console.warn(message);
+      },
+    },
+  });
+}

package/src/plugins/examples/prerender-cache-plugin.ts

@@ -1,111 +1,111 @@
-/**
- * Example plugin: prerender output cache.
- *
- * Demonstrates `definePrerenderHook` — we keep a disk-backed cache of
- * previously rendered pages keyed by pathname + content hash. When the
- * next build encounters an unchanged pathname, we short-circuit with
- * the cached HTML. The bundler's fetch handler is still invoked (we
- * don't get a chance to intercept BEFORE), but we demonstrate how a
- * plugin might use the override return to swap the eventual output.
- *
- * Educational only — a production cache would key off upstream content
- * (markdown source, database row, etc.) rather than the rendered
- * HTML hash. Useful as a scaffold for "only rerender changed pages"
- * strategies.
- *
- * @example
- * ```ts
- * import { prerenderCachePlugin } from "@mandujs/core/plugins/examples/prerender-cache-plugin";
- *
- * export default {
- *   plugins: [prerenderCachePlugin({ cacheFile: ".mandu/prerender-cache.json" })],
- * } satisfies ManduConfig;
- * ```
- */
-
-import { readFile, writeFile, mkdir } from "fs/promises";
-import path from "path";
-import { createHash } from "node:crypto";
-import { definePlugin } from "../define";
-import type { ManduPlugin } from "../hooks";
-
-export interface PrerenderCachePluginOptions {
-  /** Absolute / cwd-relative cache file path. Default `".mandu/prerender-cache.json"`. */
-  cacheFile?: string;
-}
-
-interface CacheEntry {
-  hash: string;
-  html: string;
-}
-type CacheShape = Record<string, CacheEntry>;
-
-function hashContent(s: string): string {
-  return createHash("sha256").update(s).digest("hex").slice(0, 16);
-}
-
-async function loadCache(file: string): Promise<CacheShape> {
-  try {
-    const raw = await readFile(file, "utf-8");
-    const parsed = JSON.parse(raw) as unknown;
-    return parsed && typeof parsed === "object"
-      ? (parsed as CacheShape)
-      : {};
-  } catch {
-    return {};
-  }
-}
-
-async function saveCache(file: string, data: CacheShape): Promise<void> {
-  await mkdir(path.dirname(file), { recursive: true });
-  await writeFile(file, JSON.stringify(data, null, 2), "utf-8");
-}
-
-export function prerenderCachePlugin(
-  options: PrerenderCachePluginOptions = {}
-): ManduPlugin {
-  const cacheFile = path.resolve(
-    process.cwd(),
-    options.cacheFile ?? ".mandu/prerender-cache.json"
-  );
-  // Cache is loaded lazily on first hit so plugins don't pay the I/O
-  // cost when nobody prerenders.
-  let cache: CacheShape | null = null;
-  // Track the set of pathnames we've touched this build so we can
-  // prune stale entries on `onBundleComplete`.
-  const touched = new Set<string>();
-
-  return definePlugin({
-    name: "prerender-cache",
-    hooks: {
-      async definePrerenderHook(ctx) {
-        if (!cache) cache = await loadCache(cacheFile);
-        const hash = hashContent(ctx.html);
-        const prev = cache[ctx.pathname];
-        touched.add(ctx.pathname);
-        if (prev && prev.hash === hash) {
-          // Content unchanged — no override needed, caller writes the
-          // same bytes. We could return `{ html: prev.html }` if we
-          // wanted to guarantee byte-identical output even if the
-          // renderer adds a timestamp.
-          return undefined;
-        }
-        cache[ctx.pathname] = { hash, html: ctx.html };
-        await saveCache(cacheFile, cache);
-        return undefined;
-      },
-      async onBundleComplete() {
-        // Prune entries that weren't touched this build.
-        if (!cache) return;
-        let changed = false;
-        for (const key of Object.keys(cache)) {
-          if (!touched.has(key)) {
-            delete cache[key];
-            changed = true;
-          }
-        }
-        if (changed) await saveCache(cacheFile, cache);
-      },
-    },
-  });
-}
+/**
+ * Example plugin: prerender output cache.
+ *
+ * Demonstrates `definePrerenderHook` — we keep a disk-backed cache of
+ * previously rendered pages keyed by pathname + content hash. When the
+ * next build encounters an unchanged pathname, we short-circuit with
+ * the cached HTML. The bundler's fetch handler is still invoked (we
+ * don't get a chance to intercept BEFORE), but we demonstrate how a
+ * plugin might use the override return to swap the eventual output.
+ *
+ * Educational only — a production cache would key off upstream content
+ * (markdown source, database row, etc.) rather than the rendered
+ * HTML hash. Useful as a scaffold for "only rerender changed pages"
+ * strategies.
+ *
+ * @example
+ * ```ts
+ * import { prerenderCachePlugin } from "@mandujs/core/plugins/examples/prerender-cache-plugin";
+ *
+ * export default {
+ *   plugins: [prerenderCachePlugin({ cacheFile: ".mandu/prerender-cache.json" })],
+ * } satisfies ManduConfig;
+ * ```
+ */
+
+import { readFile, writeFile, mkdir } from "fs/promises";
+import path from "path";
+import { createHash } from "node:crypto";
+import { definePlugin } from "../define";
+import type { ManduPlugin } from "../hooks";
+
+export interface PrerenderCachePluginOptions {
+  /** Absolute / cwd-relative cache file path. Default `".mandu/prerender-cache.json"`. */
+  cacheFile?: string;
+}
+
+interface CacheEntry {
+  hash: string;
+  html: string;
+}
+type CacheShape = Record<string, CacheEntry>;
+
+function hashContent(s: string): string {
+  return createHash("sha256").update(s).digest("hex").slice(0, 16);
+}
+
+async function loadCache(file: string): Promise<CacheShape> {
+  try {
+    const raw = await readFile(file, "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object"
+      ? (parsed as CacheShape)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+async function saveCache(file: string, data: CacheShape): Promise<void> {
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, JSON.stringify(data, null, 2), "utf-8");
+}
+
+export function prerenderCachePlugin(
+  options: PrerenderCachePluginOptions = {}
+): ManduPlugin {
+  const cacheFile = path.resolve(
+    process.cwd(),
+    options.cacheFile ?? ".mandu/prerender-cache.json"
+  );
+  // Cache is loaded lazily on first hit so plugins don't pay the I/O
+  // cost when nobody prerenders.
+  let cache: CacheShape | null = null;
+  // Track the set of pathnames we've touched this build so we can
+  // prune stale entries on `onBundleComplete`.
+  const touched = new Set<string>();
+
+  return definePlugin({
+    name: "prerender-cache",
+    hooks: {
+      async definePrerenderHook(ctx) {
+        if (!cache) cache = await loadCache(cacheFile);
+        const hash = hashContent(ctx.html);
+        const prev = cache[ctx.pathname];
+        touched.add(ctx.pathname);
+        if (prev && prev.hash === hash) {
+          // Content unchanged — no override needed, caller writes the
+          // same bytes. We could return `{ html: prev.html }` if we
+          // wanted to guarantee byte-identical output even if the
+          // renderer adds a timestamp.
+          return undefined;
+        }
+        cache[ctx.pathname] = { hash, html: ctx.html };
+        await saveCache(cacheFile, cache);
+        return undefined;
+      },
+      async onBundleComplete() {
+        // Prune entries that weren't touched this build.
+        if (!cache) return;
+        let changed = false;
+        for (const key of Object.keys(cache)) {
+          if (!touched.has(key)) {
+            delete cache[key];
+            changed = true;
+          }
+        }
+        if (changed) await saveCache(cacheFile, cache);
+      },
+    },
+  });
+}