@mandujs/core 0.54.1 → 0.54.2

package/package.json

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

package/src/a11y/run-audit.ts

@@ -69,8 +69,11 @@ interface DomProvider {
   fromHtml(html: string, url: string): Promise<{ window: unknown; dispose: () => Promise<void> }>;
 }
 
-const DEFAULT_MAX_FILES = 500;
-const DEFAULT_MIN_IMPACT: AuditImpact = "minor";
+const DEFAULT_MAX_FILES = 500;
+const DEFAULT_MIN_IMPACT: AuditImpact = "minor";
+const AXE_CORE_MODULE = "axe-core";
+const JSDOM_MODULE = "jsdom";
+const HAPPY_DOM_MODULE = "happy-dom";
 
 /**
  * Zero every entry in an impact-count record. Returned by value so
@@ -100,11 +103,10 @@ async function resolveAxe(options: RunAuditOptions): Promise<AxeLike | null> {
       return null;
     }
   };
-
-  if (options.axeLoader) return tryLoad(options.axeLoader);
-  // @ts-ignore -- optional peer dependency, may not be resolvable at typecheck time
-  return tryLoad(() => import("axe-core"));
-}
+
+  if (options.axeLoader) return tryLoad(options.axeLoader);
+  return tryLoad(() => import(AXE_CORE_MODULE));
+}
 
 /**
  * Resolve a DOM provider. Prefers jsdom; falls back to HappyDOM via
@@ -126,10 +128,9 @@ async function resolveDomProvider(options: RunAuditOptions): Promise<DomProvider
     return null;
   }
 
-  // Preferred path — jsdom.
-  try {
-    // @ts-ignore -- optional peer dependency, may not be resolvable at typecheck time
-    const jsdom = await import("jsdom");
+  // Preferred path — jsdom.
+  try {
+    const jsdom = await import(JSDOM_MODULE);
     const JSDOMCtor = (jsdom as { JSDOM?: new (html: string, opts?: unknown) => unknown }).JSDOM;
     if (JSDOMCtor) {
       return {
@@ -153,10 +154,9 @@ async function resolveDomProvider(options: RunAuditOptions): Promise<DomProvider
     // jsdom not installed — fall through to HappyDOM.
   }
 
-  // Fallback path — HappyDOM.
-  try {
-    // @ts-ignore -- optional peer dependency, may not be resolvable at typecheck time
-    const happy = await import("happy-dom");
+  // Fallback path — HappyDOM.
+  try {
+    const happy = await import(HAPPY_DOM_MODULE);
     const WindowCtor = (happy as { Window?: new (opts?: { url?: string; innerWidth?: number }) => unknown }).Window;
     if (WindowCtor) {
       return {

package/src/brain/doctor/analyzer.ts

@@ -206,13 +206,13 @@ export function generateTemplatePatches(
             "Do NOT import or re-export the island in page.tsx — island() returns " +
             "a config object, not a React component. Use data-island attributes instead.",
           type: "modify",
-          content:
-            `// Example: app/my-feature.island.tsx\n` +
-            `import { island } from "@mandujs/core/client";\n\n` +
-            `export default island("visible", MyComponent);\n\n` +
-            `// In page.tsx, reference via: <div data-island="my-feature">...</div>`,
-          confidence: 0.9,
-        });
+          content:
+            `// Example: app/my-feature.island.tsx\n` +
+            `import { wrapComponent } from "@mandujs/core/client";\n\n` +
+            `export default wrapComponent(MyComponent);\n\n` +
+            `// In page.tsx, reference via: <div data-island="my-feature">...</div>`,
+          confidence: 0.9,
+        });
         break;
 
       default:

package/src/bundler/build.ts

@@ -1607,9 +1607,9 @@ async function buildVendorShims(
     }
   }
 
-  const buildShim = async (
-    shim: { name: string; source: string; key: VendorShimKey; cacheId: string }
-  ): Promise<{ key: VendorShimKey; cacheId: string; outputName?: string; outputPath?: string; error?: string }> => {
+  const buildShim = async (
+    shim: { name: string; source: string; key: VendorShimKey; cacheId: string }
+  ): Promise<{ key: VendorShimKey; cacheId: string; outputName?: string; outputPath?: string; error?: string }> => {
     const srcPath = path.join(outDir, `${shim.name}.src.js`);
     const outputName = `${shim.name}.js`;
 
@@ -1645,14 +1645,14 @@ async function buildVendorShims(
 
       await fs.unlink(srcPath).catch(() => {});
 
-      if (!result.success) {
-        const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
-        return {
-          key: shim.key,
-          cacheId: shim.cacheId,
-          error: `Vendor shim '${shim.name}' build failed (source: ${srcPath}):\n${grouped}\n  Hint: Check the import paths and ensure the vendor package is installed.`,
-        };
-      }
+      if (!result.success) {
+        const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
+        return {
+          key: shim.key,
+          cacheId: shim.cacheId,
+          error: `Vendor shim '${shim.name}' build failed (source: ${srcPath}):\n${grouped}\n  ${vendorShimFailureHint(shim.name)}`,
+        };
+      }
 
       return {
         key: shim.key,
@@ -1662,13 +1662,13 @@ async function buildVendorShims(
       };
     } catch (error) {
       await fs.unlink(srcPath).catch(() => {});
-      return {
-        key: shim.key,
-        cacheId: shim.cacheId,
-        error: `[${shim.name}] ${String(error)}`,
-      };
-    }
-  };
+      return {
+        key: shim.key,
+        cacheId: shim.cacheId,
+        error: `[${shim.name}] ${String(error)}\n  ${vendorShimFailureHint(shim.name)}`,
+      };
+    }
+  };
 
   const buildResults = await Promise.all(shims.map((shim) => buildShim(shim)));
   const writeEntries: VendorCacheWriteEntry[] = [];
@@ -1711,7 +1711,14 @@ async function buildVendorShims(
     fastRefreshRuntime: results.fastRefreshRuntime,
     errors,
   };
-}
+}
+
+function vendorShimFailureHint(shimName: string): string {
+  if (shimName.includes("react-refresh")) {
+    return "Hint: install the optional dev peer dependency with `bun add -d react-refresh`.";
+  }
+  return "Hint: check the import paths and ensure the vendor package is installed.";
+}
 
 /**
  * 단일 Island 번들 빌드

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

@@ -80,15 +80,19 @@ describe("defaultAllowImporter", () => {
 });
 
 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();
-  });
-});
+  test("matches __generated__ specifiers", () => {
+    expect("./__generated__/foo").toMatch(DEFAULT_BLOCK_FILTER);
+    expect("../../src/__generated__/routes").toMatch(DEFAULT_BLOCK_FILTER);
+  });
+  test("matches direct .mandu/generated relative specifiers", () => {
+    expect("../.mandu/generated/routes").toMatch(DEFAULT_BLOCK_FILTER);
+    expect("../../../.mandu/generated/server/repos/party.repo").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", () => {

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

@@ -1,5 +1,5 @@
 /**
- * Bun bundler plugin — hard-fail on direct `__generated__/` imports.
+ * Bun bundler plugin — hard-fail on direct generated-artifact imports.
  *
  * Background
  * ──────────
@@ -8,14 +8,15 @@
  * 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.
+ * installs it by default, and any import whose specifier targets
+ * `__generated__` or `.mandu/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.
+ * - `onResolve({ filter: DEFAULT_BLOCK_FILTER })` — 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.
@@ -90,8 +91,8 @@ export interface BlockGeneratedImportsOptions {
   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.
+   * generated-artifact paths. Mandu ships a single default — exposing this
+   * for test harnesses that want to narrow or broaden the filter.
    */
   filter?: RegExp;
 }
@@ -114,7 +115,7 @@ export function defaultAllowImporter(importerPath: string): boolean {
 }
 
 /**
- * Build a `BunPlugin` that blocks direct `__generated__/` imports.
+ * Build a `BunPlugin` that blocks direct generated-artifact imports.
  *
  * Usage — call from `defaultBundlerPlugins(config)` (see `./index.ts`).
  * Every `safeBuild` / `Bun.build` invocation in Mandu funnels through
@@ -123,7 +124,7 @@ export function defaultAllowImporter(importerPath: string): boolean {
 export function blockGeneratedImports(
   options: BlockGeneratedImportsOptions = {},
 ): BunPlugin {
-  const filter = options.filter ?? /__generated__/;
+  const filter = options.filter ?? DEFAULT_BLOCK_FILTER;
   const allowImporter = options.allowImporter ?? defaultAllowImporter;
 
   return {
@@ -151,5 +152,5 @@ export function blockGeneratedImports(
   };
 }
 
-/** Exported for unit-test convenience — keep the filter text assertable. */
-export const DEFAULT_BLOCK_FILTER = /__generated__/;
+/** Exported for unit-test convenience — keep the filter text assertable. */
+export const DEFAULT_BLOCK_FILTER = /__generated__|(?:^|[\/\\])\.mandu[\/\\]generated(?:[\/\\]|$)/;

package/src/config/validate.ts

@@ -43,7 +43,7 @@ function _strictWithWarnings<T extends z.ZodRawShape>(
  */
 const ServerConfigSchema = z
   .object({
-    port: z.number().min(1).max(65535).default(3000),
+    port: z.number().min(1).max(65535).default(3333),
     // Default `"::"` (IPv6 wildcard, dual-stack): accepts both IPv4 and
     // IPv6 clients on one socket. Fixes Windows Node 17+ fetch failing
     // with `ECONNREFUSED ::1:PORT` because `localhost` resolves to `::1`

package/src/deploy/inference/context.ts

@@ -78,8 +78,8 @@ export async function buildDeployInferenceContext(
     // still gets the manifest metadata and falls back to defaults.
   }
 
-  const imports = extractImports(source);
-  const dependencyClasses = classifyImports(imports);
+  const imports = extractImports(source);
+  const dependencyClasses = classifySourceDependencies(source, imports);
   // Mandu's manifest patterns use `:param` / `*` (path-pattern style),
   // not bracket-form. Detect both shapes so the heuristic doesn't
   // misclassify dynamic routes as prerenderable. Examples:
@@ -139,18 +139,82 @@ export function extractImports(source: string): string[] {
 }
 
 /** Map import specifiers to coarse dependency classes. */
-export function classifyImports(imports: string[]): ReadonlySet<DependencyClass> {
-  const classes = new Set<DependencyClass>();
-  for (const spec of imports) {
+export function classifyImports(imports: string[]): ReadonlySet<DependencyClass> {
+  const classes = new Set<DependencyClass>();
+  for (const spec of imports) {
     const cls = classifyOne(spec);
     if (cls) classes.add(cls);
   }
   if (classes.size === 0) classes.add("fetch-only");
-  return classes;
-}
-
-function classifyOne(spec: string): DependencyClass | null {
-  const s = spec.toLowerCase();
+  return classes;
+}
+
+/**
+ * Classify dependency signals that do not always appear as bare imports.
+ *
+ * Dogfooding surfaced Mandu API routes importing project-local
+ * `src/server/infra/db` helpers and using `db` tagged templates. Those
+ * are server-only even when the bare imports look edge-safe.
+ */
+export function classifySourceDependencies(
+  source: string,
+  imports: string[] = extractImports(source),
+): ReadonlySet<DependencyClass> {
+  const classes = new Set<DependencyClass>(classifyImports(imports));
+  if (classes.size === 1 && classes.has("fetch-only")) {
+    classes.delete("fetch-only");
+  }
+
+  const allImports = extractAllImportSpecifiers(source);
+  if (allImports.some(isServerInfraImport)) {
+    classes.add("db");
+  }
+
+  if (/\bBun\.SQL\b|\bBun\.sqlite\b/i.test(source)) {
+    classes.add("bun-native");
+  }
+
+  if (
+    /(?:^|[^\w$])db\s*`/.test(source) ||
+    /\bctx\.deps\.db\b/.test(source) ||
+    /\bdb\.(?:query|execute|select|insert|update|delete)\b/.test(source)
+  ) {
+    classes.add("db");
+  }
+
+  if (classes.size === 0) {
+    classes.add("fetch-only");
+  }
+  return classes;
+}
+
+function extractAllImportSpecifiers(source: string): string[] {
+  const out = new Set<string>();
+  const staticImport = /^\s*import\b[^"']*?["']([^"']+)["']/gm;
+  const dynamicImport = /\bimport\(\s*["']([^"']+)["']\s*\)/g;
+  for (const re of [staticImport, dynamicImport]) {
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(source)) !== null) {
+      out.add(m[1]!);
+    }
+  }
+  return [...out].sort();
+}
+
+function isServerInfraImport(specifier: string): boolean {
+  const s = specifier.replace(/\\/g, "/").toLowerCase();
+  return (
+    s === "@/server/infra" ||
+    s.startsWith("@/server/infra/") ||
+    s === "src/server/infra" ||
+    s.startsWith("src/server/infra/") ||
+    s.endsWith("/server/infra") ||
+    s.includes("/server/infra/")
+  );
+}
+
+function classifyOne(spec: string): DependencyClass | null {
+  const s = spec.toLowerCase();
   if (
     s === "bun:sqlite" ||
     s === "bun:ffi" ||
@@ -167,11 +231,14 @@ function classifyOne(spec: string): DependencyClass | null {
   if (s === "node:child_process" || s === "child_process" || s === "node:worker_threads" || s === "worker_threads") {
     return "node-child";
   }
-  if (
-    /^(postgres|pg|mysql2?|drizzle-orm(\/.*)?|@prisma\/client|prisma|mongodb|mongoose|@neondatabase\/.+|kysely|sqlite3|better-sqlite3|@planetscale\/.+)$/.test(s)
-  ) {
-    return "db";
-  }
+  if (
+    /^(postgres|pg|mysql2?|drizzle-orm(\/.*)?|@prisma\/client|prisma|mongodb|mongoose|@neondatabase\/.+|kysely|sqlite3|better-sqlite3|@planetscale\/.+)$/.test(s)
+  ) {
+    return "db";
+  }
+  if (s === "@mandujs/core/db" || s.startsWith("@mandujs/core/db/")) {
+    return "db";
+  }
   if (/^(@anthropic-ai\/sdk|openai|ai|@ai-sdk\/.+|@google\/generative-ai|cohere-ai)$/.test(s)) {
     return "ai-sdk";
   }

package/src/filling/context.ts

@@ -628,10 +628,23 @@ export class ManduContext {
     return this.withCookies(new Response(null, { status: 204 }));
   }
 
-  /** 400 Bad Request */
-  error(message: string, details?: unknown): Response {
-    return this.json({ status: "error", message, details }, 400);
-  }
+  /** 400 Bad Request, or custom 4xx/5xx error with ctx.error(status, message). */
+  error(message: string, details?: unknown): Response;
+  error(status: number, message: string, details?: unknown): Response;
+  error(
+    statusOrMessage: number | string,
+    messageOrDetails?: string | unknown,
+    maybeDetails?: unknown
+  ): Response {
+    if (typeof statusOrMessage === "number") {
+      const status = Number.isInteger(statusOrMessage) && statusOrMessage >= 400 && statusOrMessage <= 599
+        ? statusOrMessage
+        : 400;
+      const message = typeof messageOrDetails === "string" ? messageOrDetails : "Error";
+      return this.json({ status: "error", message, details: maybeDetails }, status);
+    }
+    return this.json({ status: "error", message: statusOrMessage, details: messageOrDetails }, 400);
+  }
 
   /** 401 Unauthorized */
   unauthorized(message: string = "Unauthorized"): Response {

package/src/guard/check.ts

@@ -30,21 +30,21 @@ 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).
+ * Build the user-facing message for a detected direct generated-artifact
+ * 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}`
-  );
-}
+export function buildForbiddenGeneratedImportMessage(specifier: string): string {
+  return (
+    `Direct generated artifact imports are forbidden: ${specifier}. ` +
+    `Use the runtime registry: see ${GENERATED_IMPORT_DOCS_URL}`
+  );
+}
 
 /**
  * Shared remediation hint. Points at `getGenerated()` from

package/src/kitchen/api/file-api.ts

@@ -229,14 +229,17 @@ export class FileAPI {
     for (const line of stdout.split("\n")) {
       if (!line.trim()) continue;
 
-      const statusCode = line.substring(0, 2);
-      const gitFilePath = line.substring(3).trim();
-      const filePath = this.getProjectRelativePath(gitFilePath, gitRoot);
-
-      changes.push({
-        filePath,
-        status: parseGitStatus(statusCode),
-      });
+      const statusCode = line.substring(0, 2);
+      const gitFilePath = line.substring(3).trim();
+      const filePath = this.getProjectRelativePath(gitFilePath, gitRoot);
+      if (!filePath || filePath === ".") {
+        continue;
+      }
+
+      changes.push({
+        filePath,
+        status: parseGitStatus(statusCode),
+      });
     }
 
     return changes;

package/src/resource/__tests__/schema.test.ts

@@ -108,15 +108,20 @@ describe("validateResourceDefinition", () => {
 });
 
 describe("getPluralName", () => {
-  test("should add 's' for simple pluralization", () => {
-    const result = getPluralName(userResourceFixture);
-    expect(result).toBe("users");
-  });
-
-  test("should use custom plural name if provided", () => {
-    const result = getPluralName(productResourceFixture);
-    expect(result).toBe("inventory");
-  });
+  test("should add 's' for simple pluralization", () => {
+    const result = getPluralName(userResourceFixture);
+    expect(result).toBe("users");
+  });
+
+  test("should use conservative English pluralization for common resource names", () => {
+    expect(getPluralName({ ...minimalResourceFixture, name: "party" })).toBe("parties");
+    expect(getPluralName({ ...minimalResourceFixture, name: "box" })).toBe("boxes");
+  });
+
+  test("should use custom plural name if provided", () => {
+    const result = getPluralName(productResourceFixture);
+    expect(result).toBe("inventory");
+  });
 
   test("should respect autoPlural: false", () => {
     const definition = {