@mandujs/core 0.27.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/bundler/build.ts

@@ -16,6 +16,8 @@ import type {
 import { HYDRATION } from "../constants";
 import { safeBuild } from "./safe-build";
 import { fastRefreshPlugin } from "./fast-refresh-plugin";
+import { defaultBundlerPlugins } from "./plugins";
+import type { BunPlugin } from "bun";
 import { mark, measure } from "../perf";
 import { HMR_PERF } from "../perf/hmr-markers";
 import {
@@ -29,6 +31,24 @@ import {
 import path from "path";
 import fs from "fs/promises";
 
+/**
+ * Resolve Mandu's default bundler plugin set from a `BundlerOptions`
+ * object. Currently returns the `mandu:block-generated-imports` plugin
+ * unless `options.blockGeneratedImport === false`. Centralised here so
+ * every `safeBuild(...)` call-site can compose
+ * `[...manduDefaultPlugins(options), ...buildLocalPlugins]` and stay in
+ * sync as the default set grows.
+ */
+function manduDefaultPlugins(options: BundlerOptions): BunPlugin[] {
+  return defaultBundlerPlugins({
+    config: {
+      guard: {
+        blockGeneratedImport: options.blockGeneratedImport,
+      },
+    },
+  });
+}
+
 /**
  * Scan for *.island.tsx / *.island.ts files across hydrated route directories.
  *
@@ -121,7 +141,7 @@ async function buildPerIslandBundle(
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
       ...(isDev ? { reactFastRefresh: true } : {}),
-      plugins: isDev ? [fastRefreshPlugin()] : [],
+      plugins: [...manduDefaultPlugins(options), ...(isDev ? [fastRefreshPlugin()] : [])],
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: { "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"), ...options.define },
     });
@@ -1063,6 +1083,7 @@ if (typeof window !== 'undefined') {
       minify: false, // dev only
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
+      plugins: manduDefaultPlugins(options),
       // React를 인라인 번들링 (import map 없이도 독립 동작)
       // DevTools는 Shadow DOM 격리 → 앱 React와 충돌 없음
       define: {
@@ -1117,6 +1138,7 @@ async function buildRouterRuntime(
       minify: options.minify ?? process.env.NODE_ENV === "production",
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
+      plugins: manduDefaultPlugins(options),
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
         ...options.define,
@@ -1193,6 +1215,7 @@ async function buildRuntime(
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
       external: ["react", "react-dom", "react-dom/client"],
+      plugins: manduDefaultPlugins(options),
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
         ...options.define,
@@ -1482,6 +1505,7 @@ async function buildVendorShims(
         sourcemap: options.sourcemap ? "external" : "none",
         target: "browser",
         external: shimExternal,
+        plugins: manduDefaultPlugins(options),
         define: {
           "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
           ...options.define,
@@ -1590,7 +1614,7 @@ async function buildIsland(
       target: "browser",
       splitting: options.splitting ?? (process.env.NODE_ENV === "production"),
       ...(isDev ? { reactFastRefresh: true } : {}),
-      plugins: isDev ? [fastRefreshPlugin()] : [],
+      plugins: [...manduDefaultPlugins(options), ...(isDev ? [fastRefreshPlugin()] : [])],
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),

package/src/bundler/index.ts

@@ -7,3 +7,4 @@ export * from "./types";
 export * from "./build";
 export * from "./dev";
 export * from "./css";
+export * from "./plugins";

package/src/bundler/plugins/__tests__/block-generated-imports.test.ts

@@ -0,0 +1,263 @@
+/**
+ * Regression tests for `mandu:block-generated-imports` (issue #207).
+ *
+ * Split into two sections:
+ *   A — pure unit tests on `ForbiddenGeneratedImportError` + helpers.
+ *   B — integration tests driving a real `Bun.build` with a synthetic
+ *       `__generated__/` import in a tmpdir, asserting the build fails
+ *       with the expected error text.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import path from "path";
+
+import {
+  ForbiddenGeneratedImportError,
+  blockGeneratedImports,
+  defaultAllowImporter,
+  DEFAULT_BLOCK_FILTER,
+  defaultBundlerPlugins,
+} from "../index";
+import { GENERATED_IMPORT_DOCS_URL } from "../../../guard/check";
+
+// ────────────────────────────────────────────────────────────────────
+// Section A — unit
+// ────────────────────────────────────────────────────────────────────
+
+describe("ForbiddenGeneratedImportError", () => {
+  test("captures specifier and importer fields", () => {
+    const err = new ForbiddenGeneratedImportError(
+      "./__generated__/routes",
+      "/repo/src/app.ts",
+    );
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(ForbiddenGeneratedImportError);
+    expect(err.specifier).toBe("./__generated__/routes");
+    expect(err.importer).toBe("/repo/src/app.ts");
+    expect(err.docsUrl).toBe(GENERATED_IMPORT_DOCS_URL);
+    expect(err.name).toBe("ForbiddenGeneratedImportError");
+  });
+
+  test("message includes specifier, importer, docs URL, and getGenerated() hint", () => {
+    const err = new ForbiddenGeneratedImportError(
+      "./__generated__/data",
+      "/repo/src/page.tsx",
+    );
+    expect(err.message).toContain("./__generated__/data");
+    expect(err.message).toContain("/repo/src/page.tsx");
+    expect(err.message).toContain(GENERATED_IMPORT_DOCS_URL);
+    expect(err.message).toContain("getGenerated");
+    expect(err.message).toContain('@mandujs/core/runtime');
+  });
+
+  test("message falls back to <unknown> importer when empty", () => {
+    const err = new ForbiddenGeneratedImportError("./__generated__/x", "");
+    expect(err.message).toContain("<unknown>");
+  });
+});
+
+describe("defaultAllowImporter", () => {
+  test("exempts packages/core/src/runtime/** paths", () => {
+    expect(
+      defaultAllowImporter("/repo/packages/core/src/runtime/registry.ts"),
+    ).toBe(true);
+  });
+
+  test("normalises Windows backslashes", () => {
+    expect(
+      defaultAllowImporter(
+        "C:\\repo\\packages\\core\\src\\runtime\\registry.ts",
+      ),
+    ).toBe(true);
+  });
+
+  test("does NOT exempt regular user code", () => {
+    expect(defaultAllowImporter("/repo/src/app.ts")).toBe(false);
+    expect(defaultAllowImporter("")).toBe(false);
+  });
+});
+
+describe("DEFAULT_BLOCK_FILTER", () => {
+  test("matches __generated__ specifiers", () => {
+    expect("./__generated__/foo").toMatch(DEFAULT_BLOCK_FILTER);
+    expect("../../src/__generated__/routes").toMatch(DEFAULT_BLOCK_FILTER);
+  });
+  test("does NOT match look-alikes without double underscores", () => {
+    expect("./generated/foo".match(DEFAULT_BLOCK_FILTER)).toBeNull();
+    expect("./src/generate/foo".match(DEFAULT_BLOCK_FILTER)).toBeNull();
+  });
+});
+
+describe("defaultBundlerPlugins", () => {
+  test("installs block-generated-imports by default", () => {
+    const plugins = defaultBundlerPlugins();
+    expect(plugins).toHaveLength(1);
+    expect(plugins[0]?.name).toBe("mandu:block-generated-imports");
+  });
+
+  test("respects opt-out via guard.blockGeneratedImport === false", () => {
+    const plugins = defaultBundlerPlugins({
+      config: { guard: { blockGeneratedImport: false } },
+    });
+    expect(plugins).toHaveLength(0);
+  });
+
+  test("treats undefined as default-on", () => {
+    const plugins = defaultBundlerPlugins({ config: { guard: {} } });
+    expect(plugins).toHaveLength(1);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────
+// Section B — integration against real Bun.build
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Integration tests invoke real `Bun.build`. On shards where the
+ * Windows `onResolve` panic is flaky, set `MANDU_SKIP_BUNDLER_TESTS=1`
+ * to skip — matches the convention used by `fast-refresh.test.ts`.
+ */
+const SKIP_BUNDLER = process.env.MANDU_SKIP_BUNDLER_TESTS === "1";
+
+describe.skipIf(SKIP_BUNDLER)("blockGeneratedImports — Bun.build integration", () => {
+  let tmpRoot: string;
+
+  beforeAll(async () => {
+    tmpRoot = await mkdtemp(path.join(tmpdir(), "mandu-block-gen-"));
+  });
+
+  afterAll(async () => {
+    await rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
+  });
+
+  test("Bun.build fails when source imports a __generated__ file", async () => {
+    const dir = path.join(tmpRoot, "scenario-block");
+    await mkdir(path.join(dir, "__generated__"), { recursive: true });
+    await writeFile(
+      path.join(dir, "__generated__/data.ts"),
+      "export const routes = [];\n",
+    );
+    await writeFile(
+      path.join(dir, "entry.ts"),
+      `import { routes } from "./__generated__/data";\nconsole.log(routes);\n`,
+    );
+
+    // Bun's plugin host surfaces a thrown onResolve error either as an
+    // exception from `Bun.build(...)` OR as an unsuccessful result whose
+    // logs contain the message. Accept either shape so the assertion is
+    // robust across Bun patch releases.
+    // Bun's plugin host surfaces a thrown onResolve error via multiple
+    // channels across patch releases: an exception from `Bun.build()`
+    // (with `AggregateError.errors[]` on recent versions), or an
+    // unsuccessful `result.logs[]`. Collect from every channel and assert
+    // the aggregated text.
+    const collected: string[] = [];
+    try {
+      const result = await Bun.build({
+        entrypoints: [path.join(dir, "entry.ts")],
+        outdir: path.join(dir, "out"),
+        target: "browser",
+        plugins: [blockGeneratedImports()],
+      });
+      expect(result.success).toBe(false);
+      for (const log of result.logs) {
+        collected.push(String(log?.message ?? log));
+      }
+    } catch (err) {
+      if (err instanceof Error) collected.push(err.message);
+      const maybeAgg = err as { errors?: unknown[] };
+      if (Array.isArray(maybeAgg.errors)) {
+        for (const inner of maybeAgg.errors) {
+          if (inner instanceof Error) collected.push(inner.message);
+          else collected.push(String(inner));
+        }
+      }
+    }
+
+    const message = collected.join("\n");
+    expect(message).toContain("__generated__");
+    expect(message).toContain(GENERATED_IMPORT_DOCS_URL);
+    expect(message).toContain("getGenerated");
+  });
+
+  test("Bun.build succeeds when opt-out is set (no plugin installed)", async () => {
+    const dir = path.join(tmpRoot, "scenario-optout");
+    await mkdir(path.join(dir, "__generated__"), { recursive: true });
+    await writeFile(
+      path.join(dir, "__generated__/data.ts"),
+      "export const routes = [];\n",
+    );
+    await writeFile(
+      path.join(dir, "entry.ts"),
+      `import { routes } from "./__generated__/data";\nconsole.log(routes);\n`,
+    );
+
+    // Simulate the opt-out path: defaultBundlerPlugins with the flag off
+    // returns an empty plugin list, so the build has nothing to reject it.
+    const plugins = defaultBundlerPlugins({
+      config: { guard: { blockGeneratedImport: false } },
+    });
+
+    const result = await Bun.build({
+      entrypoints: [path.join(dir, "entry.ts")],
+      outdir: path.join(dir, "out"),
+      target: "browser",
+      plugins,
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test("Bun.build succeeds when source has no __generated__ imports", async () => {
+    const dir = path.join(tmpRoot, "scenario-clean");
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      path.join(dir, "clean.ts"),
+      `export const value = 42;\n`,
+    );
+    await writeFile(
+      path.join(dir, "entry.ts"),
+      `import { value } from "./clean";\nconsole.log(value);\n`,
+    );
+
+    const result = await Bun.build({
+      entrypoints: [path.join(dir, "entry.ts")],
+      outdir: path.join(dir, "out"),
+      target: "browser",
+      plugins: [blockGeneratedImports()],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test("allowImporter lets whitelisted files import __generated__", async () => {
+    const dir = path.join(tmpRoot, "scenario-allow");
+    const runtimeDir = path.join(dir, "packages/core/src/runtime");
+    await mkdir(path.join(dir, "__generated__"), { recursive: true });
+    await mkdir(runtimeDir, { recursive: true });
+    await writeFile(
+      path.join(dir, "__generated__/data.ts"),
+      "export const routes = [];\n",
+    );
+    // Use a relative import so the filter can see `__generated__` in the
+    // specifier and invoke our hook — at which point the importer path
+    // matches the default allow-list.
+    await writeFile(
+      path.join(runtimeDir, "registry.ts"),
+      `import { routes } from "../../../../__generated__/data";\nexport { routes };\n`,
+    );
+
+    const result = await Bun.build({
+      entrypoints: [path.join(runtimeDir, "registry.ts")],
+      outdir: path.join(dir, "out"),
+      target: "browser",
+      plugins: [blockGeneratedImports()],
+    });
+
+    // The allow predicate lets the import fall through to Bun's default
+    // resolution, which succeeds because the file exists.
+    expect(result.success).toBe(true);
+  });
+});

package/src/bundler/plugins/block-generated-imports.ts

@@ -0,0 +1,155 @@
+/**
+ * Bun bundler plugin — hard-fail on direct `__generated__/` imports.
+ *
+ * Background
+ * ──────────
+ * The Guard rule `INVALID_GENERATED_IMPORT` (see `guard/check.ts`) already
+ * scans source files for literal `import … from '…generated…'` statements,
+ * but it only runs when the user (or CI) invokes `mandu guard check`.
+ * Autonomous coding agents routinely bypass that step. This plugin closes
+ * the gap at the bundler level: every `mandu dev` / `mandu build` pass
+ * installs it by default, and any import whose specifier contains
+ * `__generated__` fails the build with a structured, actionable error.
+ *
+ * Design
+ * ──────
+ * - `onResolve({ filter: /__generated__/ })` — Bun hands us every import
+ *   whose *specifier* matches the regex, along with the importer's path
+ *   (`args.importer`). We never return a result; we always throw.
+ * - The error is `ForbiddenGeneratedImportError`, a named subclass of
+ *   `Error`. Tests can `instanceof`-check; Bun surfaces `error.message` in
+ *   its `result.logs` output for CLI display.
+ * - The message is built via the shared Guard helper
+ *   (`buildForbiddenGeneratedImportMessage`) so the bundler path and the
+ *   static Guard pass cannot drift out of sync.
+ *
+ * Legitimate escape hatches
+ * ─────────────────────────
+ * 1. `getGenerated()` / `tryGetGenerated()` from `@mandujs/core/runtime`
+ *    read through a global manifest slot (`__MANDU_MANIFEST__`). They do
+ *    NOT trigger an ESM import for the generated artifact, so they never
+ *    hit this plugin. That is the officially supported API.
+ * 2. `import type` statements are allowed by the rule — TS erases them
+ *    before emit, so they never become runtime imports. However, a
+ *    bundler `onResolve` hook cannot distinguish `import type` from a
+ *    value import because Bun strips the `type` keyword before plugin
+ *    dispatch. For this reason the plugin exposes an `allowImporter`
+ *    option (defaulted to recognise `@mandujs/core/runtime` internals)
+ *    but deliberately does NOT try to parse the source for `type`-only
+ *    imports. User type imports go through the type-checker, not the
+ *    bundler, so they remain unaffected in practice.
+ * 3. The per-project opt-out lives in `ManduConfig.guard.blockGeneratedImport
+ *    = false`. The plugin is simply not installed when the flag is off.
+ */
+
+import type { BunPlugin } from "bun";
+import {
+  buildForbiddenGeneratedImportMessage,
+  FORBIDDEN_GENERATED_IMPORT_SUGGESTION,
+  GENERATED_IMPORT_DOCS_URL,
+} from "../../guard/check";
+
+/**
+ * Raised by the plugin's `onResolve` hook. Named so tests can
+ * `instanceof`-check, and so Bun's log output clearly attributes the
+ * failure to the plugin.
+ */
+export class ForbiddenGeneratedImportError extends Error {
+  /** The literal `from "…"` specifier that tripped the guard. */
+  readonly specifier: string;
+  /** Absolute path of the file that issued the import (best-effort). */
+  readonly importer: string;
+  /** Docs URL that explains the official replacement. */
+  readonly docsUrl: string;
+  /** Short, one-line remediation hint. */
+  readonly suggestion: string;
+
+  constructor(specifier: string, importer: string) {
+    const message =
+      `${buildForbiddenGeneratedImportMessage(specifier)}\n` +
+      `  Importer: ${importer || "<unknown>"}\n` +
+      `  Replacement: import { getGenerated } from "@mandujs/core/runtime";\n` +
+      `  Then: const data = getGenerated(<key>);\n` +
+      `  Docs: ${GENERATED_IMPORT_DOCS_URL}`;
+    super(message);
+    this.name = "ForbiddenGeneratedImportError";
+    this.specifier = specifier;
+    this.importer = importer;
+    this.docsUrl = GENERATED_IMPORT_DOCS_URL;
+    this.suggestion = FORBIDDEN_GENERATED_IMPORT_SUGGESTION;
+  }
+}
+
+export interface BlockGeneratedImportsOptions {
+  /**
+   * Predicate that returns `true` when the importer should be exempted
+   * from the rule. Default exempts `@mandujs/core/runtime` (which in
+   * principle never imports `__generated__`, but is listed here so
+   * framework boot code cannot trip over itself during upgrades).
+   */
+  allowImporter?: (importerPath: string) => boolean;
+  /**
+   * Custom filter regex applied to the import specifier. Defaults to
+   * `/__generated__/`. Mandu ships a single default — exposing this for
+   * test harnesses that want to narrow or broaden the filter.
+   */
+  filter?: RegExp;
+}
+
+/**
+ * Default exempt predicate — matches `@mandujs/core/runtime` internals.
+ * The runtime package reads generated artifacts via the global registry,
+ * so in practice it never imports `__generated__/*`. Kept as a belt-and-
+ * suspenders guard against self-inflicted regressions.
+ */
+export function defaultAllowImporter(importerPath: string): boolean {
+  if (!importerPath) return false;
+  // Normalize Windows backslashes so a single check covers both platforms.
+  const norm = importerPath.replace(/\\/g, "/");
+  return (
+    norm.includes("/@mandujs/core/runtime/") ||
+    norm.includes("/packages/core/src/runtime/") ||
+    norm.includes("packages/core/src/runtime/")
+  );
+}
+
+/**
+ * Build a `BunPlugin` that blocks direct `__generated__/` imports.
+ *
+ * Usage — call from `defaultBundlerPlugins(config)` (see `./index.ts`).
+ * Every `safeBuild` / `Bun.build` invocation in Mandu funnels through
+ * that helper, so a single install point enforces the rule everywhere.
+ */
+export function blockGeneratedImports(
+  options: BlockGeneratedImportsOptions = {},
+): BunPlugin {
+  const filter = options.filter ?? /__generated__/;
+  const allowImporter = options.allowImporter ?? defaultAllowImporter;
+
+  return {
+    name: "mandu:block-generated-imports",
+    setup(build) {
+      build.onResolve({ filter }, (args) => {
+        // Normalise the specifier so a Windows-style import (which would
+        // be exotic but technically legal in some toolchains) is still
+        // caught.
+        const specifier = args.path;
+        const importer = args.importer ?? "";
+
+        if (allowImporter(importer)) {
+          // Internal runtime code gets a pass. Return `undefined` so
+          // Bun resolves the path through its normal pipeline.
+          return undefined;
+        }
+
+        // Throw a structured error. Bun surfaces `error.message` in
+        // `BuildResult.logs` (non-success) or re-throws on an exception
+        // path; either way the message reaches the developer.
+        throw new ForbiddenGeneratedImportError(specifier, importer);
+      });
+    },
+  };
+}
+
+/** Exported for unit-test convenience — keep the filter text assertable. */
+export const DEFAULT_BLOCK_FILTER = /__generated__/;

package/src/bundler/plugins/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Bundler-plugin barrel.
+ *
+ * `defaultBundlerPlugins()` is the single choke point for the plugin
+ * set that Mandu installs on every `Bun.build` invocation. Adding a new
+ * default-on plugin means adding it here — every call-site in
+ * `bundler/build.ts` and `cli/src/util/bun.ts` composes the result of
+ * this helper with any build-specific plugins.
+ */
+
+import type { BunPlugin } from "bun";
+import {
+  blockGeneratedImports,
+  type BlockGeneratedImportsOptions,
+} from "./block-generated-imports";
+
+export {
+  blockGeneratedImports,
+  ForbiddenGeneratedImportError,
+  defaultAllowImporter,
+  DEFAULT_BLOCK_FILTER,
+  type BlockGeneratedImportsOptions,
+} from "./block-generated-imports";
+
+/**
+ * Subset of `ManduConfig.guard` consumed by `defaultBundlerPlugins()`.
+ * We deliberately don't import the full `ManduConfig` type to keep the
+ * plugins module cycle-free.
+ */
+export interface DefaultBundlerPluginsConfig {
+  guard?: {
+    blockGeneratedImport?: boolean;
+  };
+}
+
+export interface DefaultBundlerPluginsOptions {
+  /** Mandu config (only `guard.blockGeneratedImport` is consulted). */
+  config?: DefaultBundlerPluginsConfig;
+  /** Override options for the block-generated-imports plugin. */
+  blockGeneratedImports?: BlockGeneratedImportsOptions;
+}
+
+/**
+ * Compose Mandu's default plugin list. Current contents:
+ *
+ *   - `mandu:block-generated-imports` — hard-fail on direct
+ *     `__generated__/` imports. Opt-out via
+ *     `config.guard.blockGeneratedImport = false`.
+ *
+ * Always returns a fresh array; callers are free to concat build-local
+ * plugins (e.g. `fastRefreshPlugin()` in dev) without mutating the
+ * default set.
+ */
+export function defaultBundlerPlugins(
+  options: DefaultBundlerPluginsOptions = {},
+): BunPlugin[] {
+  const plugins: BunPlugin[] = [];
+  const blockEnabled = options.config?.guard?.blockGeneratedImport !== false;
+  if (blockEnabled) {
+    plugins.push(blockGeneratedImports(options.blockGeneratedImports));
+  }
+  return plugins;
+}

package/src/bundler/types.ts

@@ -156,4 +156,12 @@ export interface BundlerOptions {
    * - 안전성: 기존 `.mandu/manifest.json` 이 없으면 자동으로 full build로 fallback.
    */
   skipFrameworkBundles?: boolean;
+  /**
+   * Issue #207 — opt-out for the `mandu:block-generated-imports` bundler
+   * plugin. Default `true` (plugin installed on every build). Set
+   * `false` to skip installation — mirrors
+   * `ManduConfig.guard.blockGeneratedImport`. CLI callers pass the
+   * resolved config flag straight through.
+   */
+  blockGeneratedImport?: boolean;
 }

package/src/config/mandu.ts

@@ -147,6 +147,22 @@ export interface ManduConfig {
     realtime?: boolean;
     rules?: Record<string, GuardRuleSeverity>;
     contractRequired?: GuardRuleSeverity;
+    /**
+     * Issue #207 — hard-fail on direct `__generated__/` imports at the
+     * bundler level. When `true` (default), every `mandu dev` /
+     * `mandu build` pass installs the
+     * `mandu:block-generated-imports` Bun plugin, which throws
+     * `ForbiddenGeneratedImportError` the moment any source file
+     * resolves an import whose specifier contains `__generated__`.
+     *
+     * Set to `false` only when a migration path literally requires
+     * the legacy barrel re-export pattern. User code should always
+     * prefer `getGenerated()` from `@mandujs/core/runtime`; see
+     * https://mandujs.com/docs/architect/generated-access.
+     *
+     * Default: `true`.
+     */
+    blockGeneratedImport?: boolean;
   };
   build?: {
     outDir?: string;

package/src/config/validate.ts

@@ -80,6 +80,12 @@ const GuardConfigSchema = z
     exclude: z.array(z.string()).default([]),
     realtime: z.boolean().default(true),
     rules: z.record(z.enum(["error", "warn", "warning", "off"])).optional(),
+    /**
+     * Issue #207 — bundler-level hard-fail on direct `__generated__/`
+     * imports. Default `true`. Set `false` to opt out of the
+     * `mandu:block-generated-imports` Bun plugin.
+     */
+    blockGeneratedImport: z.boolean().default(true),
   })
   .strict();
 

package/src/guard/check.ts

@@ -12,6 +12,40 @@ export interface GuardCheckResult {
   violations: GuardViolation[];
 }
 
+/**
+ * Canonical docs URL for the `getGenerated()` runtime-registry pattern.
+ * Shared by the Guard `INVALID_GENERATED_IMPORT` rule and the bundler
+ * plugin `block-generated-imports` so both paths surface the same
+ * remediation target.
+ */
+export const GENERATED_IMPORT_DOCS_URL =
+  "https://mandujs.com/docs/architect/generated-access";
+
+/**
+ * Build the user-facing message for a detected direct `__generated__/`
+ * import. `specifier` is the literal import string that tripped the
+ * guard (not the resolved path).
+ *
+ * This helper is the single source of truth for the message text — both
+ * the static Guard pass (`checkInvalidGeneratedImport`) and the bundler
+ * plugin (`blockGeneratedImports`) call through it so the two paths
+ * cannot drift.
+ */
+export function buildForbiddenGeneratedImportMessage(specifier: string): string {
+  return (
+    `Direct __generated__/ imports are forbidden: ${specifier}. ` +
+    `Use the runtime registry: see ${GENERATED_IMPORT_DOCS_URL}`
+  );
+}
+
+/**
+ * Shared remediation hint. Points at `getGenerated()` from
+ * `@mandujs/core/runtime` and the decision-tree docs.
+ */
+export const FORBIDDEN_GENERATED_IMPORT_SUGGESTION =
+  "Import getGenerated() from @mandujs/core/runtime and read the generated artifact through the manifest. " +
+  `See ${GENERATED_IMPORT_DOCS_URL} for the decision tree.`;
+
 function normalizeSeverity(level: GuardRuleSeverity): "error" | "warning" | "off" {
   if (level === "warn") return "warning";
   return level;
@@ -119,12 +153,8 @@ export async function checkInvalidGeneratedImport(
         violations.push({
           ruleId: GUARD_RULES.INVALID_GENERATED_IMPORT.id,
           file: relativePath,
-          message:
-            `Direct __generated__/ imports are forbidden: ${match[1]}. ` +
-            `Use the runtime registry: see https://mandujs.com/docs/architect/generated-access`,
-          suggestion:
-            "Import getGenerated() from @mandujs/core/runtime and read the generated artifact through the manifest. " +
-            "See https://mandujs.com/docs/architect/generated-access for the decision tree.",
+          message: buildForbiddenGeneratedImportMessage(match[1]),
+          suggestion: FORBIDDEN_GENERATED_IMPORT_SUGGESTION,
         });
       }
     }