@mandujs/core 0.54.9 → 0.54.10

package/package.json

@@ -1,200 +1,200 @@
-{
-  "name": "@mandujs/core",
-  "version": "0.54.9",
-  "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
-  "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "exports": {
-    ".": "./src/index.ts",
-    "./a11y": "./src/a11y/index.ts",
-    "./agent": "./src/agent/index.ts",
-    "./auth": "./src/auth/index.ts",
-    "./auth/login": "./src/auth/login.ts",
-    "./auth/password": "./src/auth/password.ts",
-    "./auth/reset": "./src/auth/reset.ts",
-    "./auth/verification": "./src/auth/verification.ts",
-    "./client": "./src/client/index.ts",
-    "./client/rpc": "./src/client/rpc.ts",
-    "./contract": "./src/contract/index.ts",
-    "./contract/rpc": "./src/contract/rpc.ts",
-    "./content": "./src/content/index.ts",
-    "./content/prebuild": "./src/content/prebuild.ts",
-    "./content/collection": "./src/content/collection.ts",
-    "./content/sidebar": "./src/content/sidebar.ts",
-    "./content/slug": "./src/content/slug.ts",
-    "./content/llms-txt": "./src/content/llms-txt.ts",
-    "./content/schema": "./src/content/schema.ts",
-    "./config": "./src/config/index.ts",
-    "./config/mandu": "./src/config/mandu.ts",
-    "./config/validate": "./src/config/validate.ts",
-    "./db": "./src/db/index.ts",
-    "./db/migrations": "./src/db/migrations/index.ts",
-    "./db/migrations/history-table": "./src/db/migrations/history-table.ts",
-    "./db/migrations/runner": "./src/db/migrations/runner.ts",
-    "./deploy": "./src/deploy/index.ts",
-    "./design": "./src/design/index.ts",
-    "./desktop": "./src/desktop/index.ts",
-    "./desktop/worker": "./src/desktop/worker.ts",
-    "./email": "./src/email/index.ts",
-    "./filling": "./src/filling/index.ts",
-    "./filling/cookie-codec": "./src/filling/cookie-codec.ts",
-    "./filling/session-sqlite": "./src/filling/session-sqlite.ts",
-    "./kitchen": "./src/kitchen/index.ts",
-    "./logging": "./src/logging/index.ts",
-    "./middleware": "./src/middleware/index.ts",
-    "./middleware/csrf": "./src/middleware/csrf.ts",
-    "./middleware/oauth": "./src/middleware/oauth/index.ts",
-    "./middleware/secure": "./src/middleware/secure/index.ts",
-    "./middleware/rate-limit": "./src/middleware/rate-limit/index.ts",
-    "./middleware/session": "./src/middleware/session.ts",
-    "./testing": "./src/testing/index.ts",
-    "./testing/db": "./src/testing/db.ts",
-    "./testing/mocks": "./src/testing/mocks.ts",
-    "./testing/reporter": "./src/testing/reporter.ts",
-    "./testing/server": "./src/testing/server.ts",
-    "./testing/session": "./src/testing/session.ts",
-    "./testing/snapshot": "./src/testing/snapshot.ts",
-    "./plugins": "./src/plugins/index.ts",
-    "./plugins/define": "./src/plugins/define.ts",
-    "./plugins/runner": "./src/plugins/runner.ts",
-    "./error": "./src/error/index.ts",
-    "./i18n": "./src/i18n/index.ts",
-    "./id": "./src/id/index.ts",
-    "./observability": "./src/observability/index.ts",
-    "./openapi/generator": "./src/openapi/generator.ts",
-    "./perf": "./src/perf/index.ts",
-    "./perf/hmr-markers": "./src/perf/hmr-markers.ts",
-    "./perf/user-marks": "./src/perf/user-marks.ts",
-    "./resource": "./src/resource/index.ts",
-    "./resource/ddl/diff": "./src/resource/ddl/diff.ts",
-    "./resource/ddl/emit": "./src/resource/ddl/emit.ts",
-    "./resource/ddl/snapshot": "./src/resource/ddl/snapshot.ts",
-    "./resource/ddl/type-map": "./src/resource/ddl/type-map.ts",
-    "./resource/ddl/types": "./src/resource/ddl/types.ts",
-    "./resource/generator-repo": "./src/resource/generator-repo.ts",
-    "./resource/parser": "./src/resource/parser.ts",
-    "./resource/schema": "./src/resource/schema.ts",
-    "./router": "./src/router/index.ts",
-    "./routes": "./src/routes/index.ts",
-    "./runtime": "./src/runtime/index.ts",
-    "./runtime/cache": "./src/runtime/cache.ts",
-    "./runtime/router": "./src/runtime/router.ts",
-    "./runtime/server": "./src/runtime/server.ts",
-    "./scheduler": "./src/scheduler/index.ts",
-    "./storage/s3": "./src/storage/s3/index.ts",
-    "./guard": "./src/guard/index.ts",
-    "./guard/define-rule": "./src/guard/define-rule.ts",
-    "./guard/design-inline-class": "./src/guard/design-inline-class.ts",
-    "./guard/rule-presets": "./src/guard/rule-presets.ts",
-    "./guard/tsgolint-bridge": "./src/guard/tsgolint-bridge.ts",
-    "./bundler": "./src/bundler/index.ts",
-    "./bundler/prerender": "./src/bundler/prerender.ts",
-    "./bundler/safe-build": "./src/bundler/safe-build.ts",
-    "./bundler/types": "./src/bundler/types.ts",
-    "./bundler/hmr-types": "./src/bundler/hmr-types.ts",
-    "./bundler/scenario-matrix": "./src/bundler/scenario-matrix.ts",
-    "./bundler/vendor-cache-types": "./src/bundler/vendor-cache-types.ts",
-    "./bundler/manifest-schema": "./src/bundler/manifest-schema.ts",
-    "./bundler/analyzer": "./src/bundler/analyzer.ts",
-    "./bundler/budget": "./src/bundler/budget.ts",
-    "./bundler/plugins": "./src/bundler/plugins/index.ts",
-    "./bundler/plugins/block-generated-imports": "./src/bundler/plugins/block-generated-imports.ts",
-    "./bundler/generate-static-params": "./src/bundler/generate-static-params.ts",
-    "./diagnose": "./src/diagnose/index.ts",
-    "./dev-error-overlay": "./src/dev-error-overlay/index.ts",
-    "./middleware/compose": "./src/middleware/compose.ts",
-    "./middleware/define": "./src/middleware/define.ts",
-    "./middleware/bridge": "./src/middleware/bridge.ts",
-    "./client/hydrate": "./src/client/hydrate.ts",
-    "./runtime/fast-refresh-types": "./src/runtime/fast-refresh-types.ts",
-    "./components/Image": "./src/components/Image.tsx"
-  },
-  "files": [
-    "src/**/*",
-    "scripts/postinstall-lock.ts"
-  ],
-  "scripts": {
-    "postinstall": "bun ./scripts/postinstall-lock.ts",
-    "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
-    "test:hydration": "bun test tests/hydration",
-    "test:streaming": "bun test tests/streaming-ssr",
-    "test:watch": "bun test --watch"
-  },
-  "devDependencies": {
-    "@happy-dom/global-registrator": "^15.0.0"
-  },
-  "keywords": [
-    "mandu",
-    "framework",
-    "agent",
-    "ai",
-    "code-generation"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/konamgil/mandu.git",
-    "directory": "packages/core"
-  },
-  "author": "konamgil",
-  "license": "MPL-2.0",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "bun": ">=1.3.12"
-  },
-  "peerDependencies": {
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "react-refresh": ">=0.18.0",
-    "@tailwindcss/cli": ">=4.0.0",
-    "webview-bun": "^2.4.0",
-    "axe-core": ">=4.8.0",
-    "jsdom": ">=24.0.0",
-    "happy-dom": ">=15.0.0",
-    "@babel/core": "^7.29.0",
-    "babel-plugin-react-compiler": "^1.0.0",
-    "eslint": "^9.0.0",
-    "eslint-plugin-react-compiler": "^19.0.0 || ^1.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@tailwindcss/cli": {
-      "optional": true
-    },
-    "react-refresh": {
-      "optional": true
-    },
-    "webview-bun": {
-      "optional": true
-    },
-    "axe-core": {
-      "optional": true
-    },
-    "jsdom": {
-      "optional": true
-    },
-    "happy-dom": {
-      "optional": true
-    },
-    "@babel/core": {
-      "optional": true
-    },
-    "babel-plugin-react-compiler": {
-      "optional": true
-    },
-    "eslint": {
-      "optional": true
-    },
-    "eslint-plugin-react-compiler": {
-      "optional": true
-    }
-  },
-  "dependencies": {
-    "chokidar": "^5.0.0",
-    "fast-glob": "^3.3.2",
-    "glob": "^13.0.0",
-    "minimatch": "^10.1.1",
-    "zod": "^3.23.8"
-  }
-}
+{
+  "name": "@mandujs/core",
+  "version": "0.54.10",
+  "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./a11y": "./src/a11y/index.ts",
+    "./agent": "./src/agent/index.ts",
+    "./auth": "./src/auth/index.ts",
+    "./auth/login": "./src/auth/login.ts",
+    "./auth/password": "./src/auth/password.ts",
+    "./auth/reset": "./src/auth/reset.ts",
+    "./auth/verification": "./src/auth/verification.ts",
+    "./client": "./src/client/index.ts",
+    "./client/rpc": "./src/client/rpc.ts",
+    "./contract": "./src/contract/index.ts",
+    "./contract/rpc": "./src/contract/rpc.ts",
+    "./content": "./src/content/index.ts",
+    "./content/prebuild": "./src/content/prebuild.ts",
+    "./content/collection": "./src/content/collection.ts",
+    "./content/sidebar": "./src/content/sidebar.ts",
+    "./content/slug": "./src/content/slug.ts",
+    "./content/llms-txt": "./src/content/llms-txt.ts",
+    "./content/schema": "./src/content/schema.ts",
+    "./config": "./src/config/index.ts",
+    "./config/mandu": "./src/config/mandu.ts",
+    "./config/validate": "./src/config/validate.ts",
+    "./db": "./src/db/index.ts",
+    "./db/migrations": "./src/db/migrations/index.ts",
+    "./db/migrations/history-table": "./src/db/migrations/history-table.ts",
+    "./db/migrations/runner": "./src/db/migrations/runner.ts",
+    "./deploy": "./src/deploy/index.ts",
+    "./design": "./src/design/index.ts",
+    "./desktop": "./src/desktop/index.ts",
+    "./desktop/worker": "./src/desktop/worker.ts",
+    "./email": "./src/email/index.ts",
+    "./filling": "./src/filling/index.ts",
+    "./filling/cookie-codec": "./src/filling/cookie-codec.ts",
+    "./filling/session-sqlite": "./src/filling/session-sqlite.ts",
+    "./kitchen": "./src/kitchen/index.ts",
+    "./logging": "./src/logging/index.ts",
+    "./middleware": "./src/middleware/index.ts",
+    "./middleware/csrf": "./src/middleware/csrf.ts",
+    "./middleware/oauth": "./src/middleware/oauth/index.ts",
+    "./middleware/secure": "./src/middleware/secure/index.ts",
+    "./middleware/rate-limit": "./src/middleware/rate-limit/index.ts",
+    "./middleware/session": "./src/middleware/session.ts",
+    "./testing": "./src/testing/index.ts",
+    "./testing/db": "./src/testing/db.ts",
+    "./testing/mocks": "./src/testing/mocks.ts",
+    "./testing/reporter": "./src/testing/reporter.ts",
+    "./testing/server": "./src/testing/server.ts",
+    "./testing/session": "./src/testing/session.ts",
+    "./testing/snapshot": "./src/testing/snapshot.ts",
+    "./plugins": "./src/plugins/index.ts",
+    "./plugins/define": "./src/plugins/define.ts",
+    "./plugins/runner": "./src/plugins/runner.ts",
+    "./error": "./src/error/index.ts",
+    "./i18n": "./src/i18n/index.ts",
+    "./id": "./src/id/index.ts",
+    "./observability": "./src/observability/index.ts",
+    "./openapi/generator": "./src/openapi/generator.ts",
+    "./perf": "./src/perf/index.ts",
+    "./perf/hmr-markers": "./src/perf/hmr-markers.ts",
+    "./perf/user-marks": "./src/perf/user-marks.ts",
+    "./resource": "./src/resource/index.ts",
+    "./resource/ddl/diff": "./src/resource/ddl/diff.ts",
+    "./resource/ddl/emit": "./src/resource/ddl/emit.ts",
+    "./resource/ddl/snapshot": "./src/resource/ddl/snapshot.ts",
+    "./resource/ddl/type-map": "./src/resource/ddl/type-map.ts",
+    "./resource/ddl/types": "./src/resource/ddl/types.ts",
+    "./resource/generator-repo": "./src/resource/generator-repo.ts",
+    "./resource/parser": "./src/resource/parser.ts",
+    "./resource/schema": "./src/resource/schema.ts",
+    "./router": "./src/router/index.ts",
+    "./routes": "./src/routes/index.ts",
+    "./runtime": "./src/runtime/index.ts",
+    "./runtime/cache": "./src/runtime/cache.ts",
+    "./runtime/router": "./src/runtime/router.ts",
+    "./runtime/server": "./src/runtime/server.ts",
+    "./scheduler": "./src/scheduler/index.ts",
+    "./storage/s3": "./src/storage/s3/index.ts",
+    "./guard": "./src/guard/index.ts",
+    "./guard/define-rule": "./src/guard/define-rule.ts",
+    "./guard/design-inline-class": "./src/guard/design-inline-class.ts",
+    "./guard/rule-presets": "./src/guard/rule-presets.ts",
+    "./guard/tsgolint-bridge": "./src/guard/tsgolint-bridge.ts",
+    "./bundler": "./src/bundler/index.ts",
+    "./bundler/prerender": "./src/bundler/prerender.ts",
+    "./bundler/safe-build": "./src/bundler/safe-build.ts",
+    "./bundler/types": "./src/bundler/types.ts",
+    "./bundler/hmr-types": "./src/bundler/hmr-types.ts",
+    "./bundler/scenario-matrix": "./src/bundler/scenario-matrix.ts",
+    "./bundler/vendor-cache-types": "./src/bundler/vendor-cache-types.ts",
+    "./bundler/manifest-schema": "./src/bundler/manifest-schema.ts",
+    "./bundler/analyzer": "./src/bundler/analyzer.ts",
+    "./bundler/budget": "./src/bundler/budget.ts",
+    "./bundler/plugins": "./src/bundler/plugins/index.ts",
+    "./bundler/plugins/block-generated-imports": "./src/bundler/plugins/block-generated-imports.ts",
+    "./bundler/generate-static-params": "./src/bundler/generate-static-params.ts",
+    "./diagnose": "./src/diagnose/index.ts",
+    "./dev-error-overlay": "./src/dev-error-overlay/index.ts",
+    "./middleware/compose": "./src/middleware/compose.ts",
+    "./middleware/define": "./src/middleware/define.ts",
+    "./middleware/bridge": "./src/middleware/bridge.ts",
+    "./client/hydrate": "./src/client/hydrate.ts",
+    "./runtime/fast-refresh-types": "./src/runtime/fast-refresh-types.ts",
+    "./components/Image": "./src/components/Image.tsx"
+  },
+  "files": [
+    "src/**/*",
+    "scripts/postinstall-lock.ts"
+  ],
+  "scripts": {
+    "postinstall": "bun ./scripts/postinstall-lock.ts",
+    "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
+    "test:hydration": "bun test tests/hydration",
+    "test:streaming": "bun test tests/streaming-ssr",
+    "test:watch": "bun test --watch"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^15.0.0"
+  },
+  "keywords": [
+    "mandu",
+    "framework",
+    "agent",
+    "ai",
+    "code-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/konamgil/mandu.git",
+    "directory": "packages/core"
+  },
+  "author": "konamgil",
+  "license": "MPL-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.12"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-refresh": ">=0.18.0",
+    "@tailwindcss/cli": ">=4.0.0",
+    "webview-bun": "^2.4.0",
+    "axe-core": ">=4.8.0",
+    "jsdom": ">=24.0.0",
+    "happy-dom": ">=15.0.0",
+    "@babel/core": "^7.29.0",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint": "^9.0.0",
+    "eslint-plugin-react-compiler": "^19.0.0 || ^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tailwindcss/cli": {
+      "optional": true
+    },
+    "react-refresh": {
+      "optional": true
+    },
+    "webview-bun": {
+      "optional": true
+    },
+    "axe-core": {
+      "optional": true
+    },
+    "jsdom": {
+      "optional": true
+    },
+    "happy-dom": {
+      "optional": true
+    },
+    "@babel/core": {
+      "optional": true
+    },
+    "babel-plugin-react-compiler": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    },
+    "eslint-plugin-react-compiler": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "fast-glob": "^3.3.2",
+    "glob": "^13.0.0",
+    "minimatch": "^10.1.1",
+    "zod": "^3.23.8"
+  }
+}

package/src/agent/__tests__/context.test.ts

@@ -27,13 +27,31 @@ import {
   writeAgentVerifyReport,
 } from "../verify";
 
-async function writeFile(root: string, rel: string, content: string): Promise<void> {
-  const abs = path.join(root, rel);
-  await fs.mkdir(path.dirname(abs), { recursive: true });
-  await fs.writeFile(abs, content, "utf8");
-}
-
-describe("agent context", () => {
+async function writeFile(root: string, rel: string, content: string): Promise<void> {
+  const abs = path.join(root, rel);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, content, "utf8");
+}
+
+async function runGit(root: string, args: string[]): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+  try {
+    const proc = Bun.spawn(["git", ...args], {
+      cwd: root,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { ok: exitCode === 0, stdout, stderr };
+  } catch (error) {
+    return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+describe("agent context", () => {
   let root: string;
 
   beforeEach(async () => {
@@ -172,19 +190,48 @@ describe("agent context", () => {
       includeContract: false,
     });
 
-    expect(report.framework).toBe("mandu");
-    expect(report.ok).toBe(true);
-    expect(report.checks.map((check) => check.id)).toEqual(["manifest"]);
+    expect(report.framework).toBe("mandu");
+    expect(report.ok).toBe(true);
+    expect(report.checks.map((check) => check.id)).toEqual(["internal-api", "manifest"]);
     expect(report.suggestedCommands.map((cmd) => cmd.command)).toContain("bun run typecheck");
     expect(report.nextRepairInput).toBe(".mandu/agent-verify.json");
 
     const result = await writeAgentVerifyReport(root, report);
     expect(result.path).toBe(agentVerifyReportPath(root));
     const parsed = JSON.parse(await fs.readFile(result.path, "utf8"));
-    expect(parsed.project.name).toBe("agent-app");
-  });
-
-  it("turns a verify report into repair actions", async () => {
+    expect(parsed.project.name).toBe("agent-app");
+  });
+
+  it("records changed file reasons and warns on internal API edits", async () => {
+    const version = await runGit(root, ["--version"]);
+    if (!version.ok) return;
+
+    expect((await runGit(root, ["init"])).ok).toBe(true);
+    await runGit(root, ["config", "user.email", "agent@example.com"]);
+    await runGit(root, ["config", "user.name", "Agent"]);
+    expect((await runGit(root, ["add", "."])).ok).toBe(true);
+    expect((await runGit(root, ["commit", "-m", "initial"])).ok).toBe(true);
+
+    await writeFile(root, "packages/core/src/runtime/internal-change.ts", "export const value = 1;\n");
+
+    const report = await buildAgentVerifyReport(root, {
+      includeDiagnose: false,
+      includeGuard: false,
+      includeContract: false,
+    });
+
+    const reason = report.changedFileReasons.find(
+      (entry) => entry.file === "packages/core/src/runtime/internal-change.ts",
+    );
+    expect(reason?.internalApi).toBe(true);
+    expect(reason?.recommendedChecks).toContain("bun run check:public-api && bun run check:target-boundaries");
+    expect(report.diagnostics.some((diag) => diag.code === "MANDU_VERIFY_INTERNAL_API_EDIT")).toBe(true);
+    expect(report.suggestedCommands.map((cmd) => cmd.command)).toContain(
+      "bun run check:public-api && bun run check:target-boundaries",
+    );
+  });
+
+  it("turns a verify report into repair actions", async () => {
     await writeAgentVerifyReport(root, {
       schemaVersion: 1,
       framework: "mandu",
@@ -195,9 +242,10 @@ describe("agent context", () => {
         root,
         packageManager: "bun",
         configFile: null,
-      },
-      changedFiles: [],
-      gitAvailable: false,
+      },
+      changedFiles: [],
+      changedFileReasons: [],
+      gitAvailable: false,
       notes: [],
       ok: false,
       checks: [],

package/src/agent/types.ts

@@ -153,19 +153,27 @@ export interface AgentVerifyCheck {
   details?: Record<string, unknown>;
 }
 
-export interface AgentSuggestedCommand {
-  command: string;
-  reason: string;
-  required: boolean;
-}
-
-export interface AgentVerifyReport {
+export interface AgentSuggestedCommand {
+  command: string;
+  reason: string;
+  required: boolean;
+}
+
+export interface AgentChangedFileReason {
+  file: string;
+  reasons: string[];
+  recommendedChecks: string[];
+  internalApi: boolean;
+}
+
+export interface AgentVerifyReport {
   schemaVersion: 1;
   framework: "mandu";
   generatedAt: string;
-  project: AgentProjectSummary;
-  changedFiles: string[];
-  gitAvailable: boolean;
+  project: AgentProjectSummary;
+  changedFiles: string[];
+  changedFileReasons: AgentChangedFileReason[];
+  gitAvailable: boolean;
   notes: string[];
   ok: boolean;
   checks: AgentVerifyCheck[];

package/src/agent/verify.ts

@@ -7,8 +7,9 @@ import type { ContractViolation } from "../guard/contract-guard";
 import {
   buildAgentContext,
 } from "./context";
-import type {
-  AgentDiagnostic,
+import type {
+  AgentChangedFileReason,
+  AgentDiagnostic,
   AgentDiagnosticSeverity,
   AgentSuggestedCommand,
   AgentVerifyCheck,
@@ -208,7 +209,11 @@ function matchesChanged(
   return candidates.some((file) => changed.has(file));
 }
 
-function commandSuggestions(changedFiles: string[], diagnostics: AgentDiagnostic[]): AgentSuggestedCommand[] {
+function commandSuggestions(
+  changedFiles: string[],
+  diagnostics: AgentDiagnostic[],
+  changedFileReasons: AgentChangedFileReason[] = [],
+): AgentSuggestedCommand[] {
   const files = changedFiles.map(normalizePath).filter((value): value is string => Boolean(value));
   const out: AgentSuggestedCommand[] = [];
   const add = (command: string, reason: string, required: boolean) => {
@@ -240,15 +245,101 @@ function commandSuggestions(changedFiles: string[], diagnostics: AgentDiagnostic
   if (files.some((file) => file.startsWith("packages/mcp/"))) {
     add("bun test packages/mcp/tests", "MCP package files changed.", true);
   }
-  if (files.some((file) => file.includes("package.json") || file === "bun.lock")) {
-    add("bun run check:publish", "Package metadata or lockfile changed.", true);
-  }
-  if (diagnostics.some((d) => d.severity === "error" || d.severity === "fatal")) {
+  if (files.some((file) => file.includes("package.json") || file === "bun.lock")) {
+    add("bun run check:publish", "Package metadata or lockfile changed.", true);
+  }
+  if (changedFileReasons.some((entry) => entry.internalApi)) {
+    add("bun run check:public-api && bun run check:target-boundaries", "Internal framework boundaries changed.", true);
+  }
+  if (diagnostics.some((d) => d.severity === "error" || d.severity === "fatal")) {
     add("mandu agent repair --from .mandu/agent-verify.json", "Verification produced repairable diagnostics.", false);
   }
 
   return out;
-}
+}
+
+function isInternalApiEdit(file: string): boolean {
+  return [
+    "packages/core/src/runtime/",
+    "packages/core/src/bundler/",
+    "packages/core/src/server/",
+    "packages/core/src/guard/",
+    "packages/core/src/spec/",
+    "packages/core/src/router/",
+    "packages/core/src/internal/",
+  ].some((prefix) => file.startsWith(prefix));
+}
+
+function changedFileReason(file: string): AgentChangedFileReason {
+  const normalized = normalizePath(file) ?? file;
+  const reasons: string[] = [];
+  const recommendedChecks: string[] = [];
+
+  if (/\.(ts|tsx|js|jsx)$/.test(normalized)) {
+    reasons.push("Source code changed.");
+    recommendedChecks.push("bun run typecheck");
+  }
+  if (/\.test\.(ts|tsx|js|jsx)$/.test(normalized)) {
+    reasons.push("Test code changed.");
+    recommendedChecks.push(`bun test ${normalized}`);
+  }
+  if (normalized.startsWith("packages/cli/")) {
+    reasons.push("CLI behavior or documentation changed.");
+    recommendedChecks.push("bun test packages/cli/src");
+  }
+  if (normalized.startsWith("packages/mcp/")) {
+    reasons.push("MCP tool surface changed.");
+    recommendedChecks.push("bun test packages/mcp/tests");
+  }
+  if (normalized.startsWith("docs/") || normalized.endsWith("README.md") || normalized.endsWith("README.ko.md")) {
+    reasons.push("User-facing documentation changed.");
+    recommendedChecks.push("bun run check:docs-drift");
+  }
+  if (normalized === "package.json" || normalized === "bun.lock" || normalized.endsWith("/package.json")) {
+    reasons.push("Package metadata or dependency graph changed.");
+    recommendedChecks.push("bun run check:publish");
+  }
+
+  const internalApi = isInternalApiEdit(normalized);
+  if (internalApi) {
+    reasons.push("Framework internal API changed.");
+    recommendedChecks.push("bun run check:public-api && bun run check:target-boundaries");
+  }
+
+  return {
+    file: normalized,
+    reasons: reasons.length > 0 ? reasons : ["Changed file requires standard verification."],
+    recommendedChecks: [...new Set(recommendedChecks)],
+    internalApi,
+  };
+}
+
+function buildChangedFileReasons(changedFiles: string[]): AgentChangedFileReason[] {
+  return changedFiles
+    .map(normalizePath)
+    .filter((file): file is string => Boolean(file))
+    .map(changedFileReason);
+}
+
+function internalApiDiagnostics(changedFileReasons: AgentChangedFileReason[]): AgentDiagnostic[] {
+  return changedFileReasons
+    .filter((entry) => entry.internalApi)
+    .map((entry) => ({
+      code: "MANDU_VERIFY_INTERNAL_API_EDIT",
+      severity: "warning" as const,
+      title: "Internal framework API changed",
+      file: entry.file,
+      cause: "This file is part of Mandu's internal runtime/bundler/guard surface and can affect public behavior indirectly.",
+      suggestedFix: {
+        type: "run_command" as const,
+        command: "bun run check:public-api && bun run check:target-boundaries",
+        description: "Verify public API classification and target-safe import boundaries.",
+      },
+      docs: "docs/architect/public-api-boundary.md",
+      repairable: false,
+      source: "agent.verify",
+    }));
+}
 
 function check(
   id: string,
@@ -281,16 +372,22 @@ export async function buildAgentVerifyReport(
   rootDir: string = process.cwd(),
   options: BuildAgentVerifyOptions = {},
 ): Promise<AgentVerifyReport> {
-  const root = path.resolve(rootDir);
-  const changed = await collectChangedFiles(root, options);
-  const changedSet = new Set(changed.files.map(normalizePath).filter((value): value is string => Boolean(value)));
+  const root = path.resolve(rootDir);
+  const changed = await collectChangedFiles(root, options);
+  const changedSet = new Set(changed.files.map(normalizePath).filter((value): value is string => Boolean(value)));
+  const changedFileReasons = buildChangedFileReasons(changed.files);
   const context = await buildAgentContext(root, {
     includeDiagnose: false,
     includeGit: false,
   });
   const notes = [...changed.notes];
-  const checks: AgentVerifyCheck[] = [];
-  const diagnostics: AgentDiagnostic[] = [];
+  const checks: AgentVerifyCheck[] = [];
+  const diagnostics: AgentDiagnostic[] = [];
+  const internalDiagnostics = internalApiDiagnostics(changedFileReasons);
+  diagnostics.push(...internalDiagnostics);
+  checks.push(check("internal-api", "Internal API boundary", internalDiagnostics, {
+    changedFiles: changedFileReasons.filter((entry) => entry.internalApi).length,
+  }));
 
   if (options.includeDiagnose !== false) {
     try {
@@ -382,14 +479,15 @@ export async function buildAgentVerifyReport(
     schemaVersion: 1,
     framework: "mandu",
     generatedAt: new Date().toISOString(),
-    project: context.project,
-    changedFiles: changed.files,
-    gitAvailable: changed.gitAvailable,
+    project: context.project,
+    changedFiles: changed.files,
+    changedFileReasons,
+    gitAvailable: changed.gitAvailable,
     notes,
     ok,
     checks,
     diagnostics,
-    suggestedCommands: commandSuggestions(changed.files, diagnostics),
+    suggestedCommands: commandSuggestions(changed.files, diagnostics, changedFileReasons),
     nextRepairInput: AGENT_VERIFY_RELATIVE_PATH,
   };
 }

package/src/bundler/build.test.ts

@@ -248,7 +248,7 @@ describe("buildClientBundles vendor shims", () => {
       expect(noClientResult.success).toBe(false);
       expect(errors).toContain("no clientModule could be resolved");
       expect(errors).toContain("LoginForm.client");
-      expect(errors).toContain("partial({ component }).Render");
+      expect(errors).toContain("run mandu generate");
     } finally {
       await rm(missingRoot, { recursive: true, force: true });
     }

package/src/error/formatter.ts

@@ -21,15 +21,20 @@ export function formatErrorResponse(error: ManduError, options: FormatOptions =
 
   const response: Record<string, unknown> = {
     errorType: error.errorType,
-    code: error.code,
-    message: error.message,
-    summary: error.summary,
-    fix: error.fix,
-  };
-
-  if (error.route) {
-    response.route = error.route;
-  }
+    code: error.code,
+    message: error.message,
+    summary: error.summary,
+    cause: error.summary,
+    fix: error.fix,
+    filePath: error.fix.file,
+    solution: error.fix.suggestion,
+  };
+
+  if (error.route) {
+    response.route = error.route;
+    response.routeId = error.route.id;
+    response.routePattern = error.route.pattern;
+  }
 
   // 개발 모드에서만 디버그 정보 포함
   if (isDev && error.debug) {
@@ -60,27 +65,31 @@ export function formatErrorForConsole(error: ManduError, options: FormatOptions
   lines.push(`  ${error.message}`);
 
   // 요약
-  if (useColors) {
-    lines.push(`  ${CYAN}→ ${error.summary}${RESET}`);
-  } else {
-    lines.push(`  → ${error.summary}`);
-  }
+  if (useColors) {
+    lines.push(`  ${CYAN}→ ${error.summary}${RESET}`);
+  } else {
+    lines.push(`  → ${error.summary}`);
+  }
+  lines.push(`  Cause: ${error.summary}`);
 
   // 수정 안내
   lines.push("");
   if (useColors) {
     lines.push(`  ${YELLOW}Fix:${RESET} ${error.fix.file}${error.fix.line ? `:${error.fix.line}` : ""}`);
     lines.push(`       ${error.fix.suggestion}`);
-  } else {
-    lines.push(`  Fix: ${error.fix.file}${error.fix.line ? `:${error.fix.line}` : ""}`);
-    lines.push(`       ${error.fix.suggestion}`);
-  }
+  } else {
+    lines.push(`  Fix: ${error.fix.file}${error.fix.line ? `:${error.fix.line}` : ""}`);
+    lines.push(`       ${error.fix.suggestion}`);
+  }
+  lines.push(`  File: ${error.fix.file}${error.fix.line ? `:${error.fix.line}` : ""}`);
+  lines.push(`  Solution: ${error.fix.suggestion}`);
 
   // 라우트 컨텍스트
-  if (error.route) {
-    lines.push("");
-    lines.push(`  Route: ${error.route.id} (${error.route.pattern})`);
-  }
+  if (error.route) {
+    lines.push("");
+    lines.push(`  Route ID: ${error.route.id}`);
+    lines.push(`  Route: ${error.route.pattern}`);
+  }
 
   // 디버그 정보 (개발 모드)
   if (isDev && includeStack && error.debug?.stack) {

package/src/router/client-entry.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "bun:test";
 import {
   findClientComponentImports,
   findRouteLevelClientComponentImport,
+  findRouteLevelClientComponentImports,
 } from "./client-entry";
 
 describe("findClientComponentImports", () => {
@@ -15,7 +16,7 @@ describe("findClientComponentImports", () => {
       {
         module: "@/client/widgets/login-form/LoginForm.client",
         kind: "named",
-        names: ["LoginForm", "SubmitButton"],
+        names: ["LoginForm", "Button"],
       },
       {
         module: "./Header.client.tsx",
@@ -60,7 +61,22 @@ describe("findClientComponentImports", () => {
     });
   });
 
-  it("does not promote embedded client imports inside a larger server page", () => {
+  it("detects a named-imported client component when the page returns only that component", () => {
+    const routeClient = findRouteLevelClientComponentImport(`
+      import { NotificationsPage } from "@/client/pages/notifications/NotificationsPage.client";
+
+      export default function Page() {
+        return <NotificationsPage />;
+      }
+    `);
+
+    expect(routeClient).toEqual({
+      module: "@/client/pages/notifications/NotificationsPage.client",
+      localName: "NotificationsPage",
+    });
+  });
+
+  it("promotes embedded client imports inside a larger server page", () => {
     const routeClient = findRouteLevelClientComponentImport(`
       import HomeApp from "@/client/pages/home/HomeApp.client";
 
@@ -72,10 +88,13 @@ describe("findClientComponentImports", () => {
       }
     `);
 
-    expect(routeClient).toBeNull();
+    expect(routeClient).toEqual({
+      module: "@/client/pages/home/HomeApp.client",
+      localName: "HomeApp",
+    });
   });
 
-  it("does not promote client imports when the page wrapper passes props", () => {
+  it("promotes client imports when the page wrapper passes props", () => {
     const routeClient = findRouteLevelClientComponentImport(`
       import PledgePage from "@/client/pages/pledges/PledgePage.client";
 
@@ -84,6 +103,38 @@ describe("findClientComponentImports", () => {
       }
     `);
 
-    expect(routeClient).toBeNull();
+    expect(routeClient).toEqual({
+      module: "@/client/pages/pledges/PledgePage.client",
+      localName: "PledgePage",
+    });
+  });
+
+  it("detects multiple rendered client imports in a server shell", () => {
+    const routeClients = findRouteLevelClientComponentImports(`
+      import { CommentsSection } from "@/client/widgets/comments-section/CommentsSection.client";
+      import { PledgeActions } from "@/client/widgets/pledge-actions/PledgeActions.client";
+
+      export default async function PledgePage({ params }) {
+        const pledge = await Promise.resolve(params.id);
+        return (
+          <main>
+            <article>{pledge}</article>
+            <PledgeActions pledgeId={params.id} />
+            <CommentsSection pledgeId={params.id} />
+          </main>
+        );
+      }
+    `);
+
+    expect(routeClients).toEqual([
+      {
+        module: "@/client/widgets/comments-section/CommentsSection.client",
+        localName: "CommentsSection",
+      },
+      {
+        module: "@/client/widgets/pledge-actions/PledgeActions.client",
+        localName: "PledgeActions",
+      },
+    ]);
   });
 });

package/src/router/client-entry.ts

@@ -62,7 +62,8 @@ export function findClientComponentImports(source: string): ClientComponentImpor
       for (const rawName of namedMatch[1].split(",")) {
         const name = rawName.trim();
         if (!name) continue;
-        names.push(name.split(/\s+as\s+/i)[0].trim());
+        const parts = name.split(/\s+as\s+/i).map((part) => part.trim()).filter(Boolean);
+        names.push(parts[1] ?? parts[0]);
       }
     }
 
@@ -100,19 +101,18 @@ export function findClientComponentImports(source: string): ClientComponentImpor
 }
 
 export function findRouteLevelClientComponentImport(source: string): RouteLevelClientComponentImport | null {
-  const defaultImports = findClientComponentImports(source).filter((entry) => {
-    const localName = entry.names[0] ?? "";
-    return entry.kind === "default" && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(localName);
-  });
-
-  if (defaultImports.length !== 1) return null;
+  return findRouteLevelClientComponentImports(source)[0] ?? null;
+}
 
-  const entry = defaultImports[0];
-  const localName = entry.names[0];
-  if (!entry.module || !localName) return null;
-  if (!defaultExportReturnsOnlyClientComponent(source, localName)) return null;
+export function findRouteLevelClientComponentImports(source: string): RouteLevelClientComponentImport[] {
+  const candidates = findClientComponentImports(source).flatMap((entry) =>
+    entry.names
+      .filter((localName) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(localName))
+      .map((localName) => ({ module: entry.module, localName }))
+  );
 
-  return { module: entry.module, localName };
+  if (candidates.length === 0) return [];
+  return defaultExportRendersClientComponents(source, candidates);
 }
 
 export async function resolveClientImportModulePath(
@@ -168,15 +168,28 @@ function expandClientModuleCandidates(basePath: string): string[] {
   ];
 }
 
-function defaultExportReturnsOnlyClientComponent(source: string, localName: string): boolean {
+function defaultExportRendersClientComponents(
+  source: string,
+  candidates: RouteLevelClientComponentImport[],
+): RouteLevelClientComponentImport[] {
   const functionBody = extractDefaultExportFunctionBody(source);
   if (functionBody !== null) {
-    const returned = extractOnlyReturnExpression(functionBody);
-    return returned !== null && jsxExpressionRendersClientComponent(returned, localName);
+    const returned = extractTopLevelReturnExpression(functionBody);
+    return returned !== null ? jsxExpressionRendersClientComponents(returned, candidates) : [];
   }
 
   const arrowExpression = extractDefaultExportArrowExpression(source);
-  return arrowExpression !== null && jsxExpressionRendersClientComponent(arrowExpression, localName);
+  if (arrowExpression !== null) {
+    return jsxExpressionRendersClientComponents(arrowExpression, candidates);
+  }
+
+  const arrowBody = extractDefaultExportArrowFunctionBody(source);
+  if (arrowBody !== null) {
+    const returned = extractTopLevelReturnExpression(arrowBody);
+    return returned !== null ? jsxExpressionRendersClientComponents(returned, candidates) : [];
+  }
+
+  return [];
 }
 
 function extractDefaultExportFunctionBody(source: string): string | null {
@@ -201,44 +214,109 @@ function extractDefaultExportArrowExpression(source: string): string | null {
   return semicolon === -1 ? rest : rest.slice(0, semicolon);
 }
 
-function extractOnlyReturnExpression(body: string): string | null {
-  const match = /^\s*return\s+([\s\S]*?)\s*;?\s*$/.exec(body);
-  return match?.[1]?.trim() ?? null;
+function extractDefaultExportArrowFunctionBody(source: string): string | null {
+  const match = /export\s+default\s+(?:async\s+)?(?:\([^)]*\)|[A-Za-z_$][A-Za-z0-9_$]*)\s*=>\s*\{/m.exec(source);
+  if (!match) return null;
+
+  const openBrace = match.index + match[0].lastIndexOf("{");
+  const closeBrace = findMatchingBrace(source, openBrace);
+  if (closeBrace === -1) return null;
+  return source.slice(openBrace + 1, closeBrace);
 }
 
-function jsxExpressionRendersClientComponent(expression: string, localName: string): boolean {
-  const expr = stripWrappingParentheses(expression.trim());
-  return isBareClientElement(expr, localName) || isHeadOnlyFragmentWrapper(expr, localName);
+function extractTopLevelReturnExpression(body: string): string | null {
+  let quote: '"' | "'" | "`" | null = null;
+  let lineComment = false;
+  let blockComment = false;
+  let braceDepth = 0;
+  let parenDepth = 0;
+  let bracketDepth = 0;
+
+  for (let i = 0; i < body.length; i++) {
+    const char = body[i];
+    const next = body[i + 1];
+    const prev = body[i - 1];
+
+    if (lineComment) {
+      if (char === "\n" || char === "\r") lineComment = false;
+      continue;
+    }
+
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        i++;
+      }
+      continue;
+    }
+
+    if (quote) {
+      if (char === quote && prev !== "\\") quote = null;
+      continue;
+    }
+
+    if (char === "/" && next === "/") {
+      lineComment = true;
+      i++;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      i++;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+
+    if (braceDepth === 0 && parenDepth === 0 && bracketDepth === 0 && body.startsWith("return", i)) {
+      const before = body[i - 1] ?? "";
+      const after = body[i + "return".length] ?? "";
+      if (!isIdentifierChar(before) && !isIdentifierChar(after)) {
+        const expr = body.slice(i + "return".length).trim();
+        return trimTrailingSemicolon(expr);
+      }
+    }
+
+    if (char === "{") braceDepth++;
+    if (char === "}") braceDepth = Math.max(0, braceDepth - 1);
+    if (char === "(") parenDepth++;
+    if (char === ")") parenDepth = Math.max(0, parenDepth - 1);
+    if (char === "[") bracketDepth++;
+    if (char === "]") bracketDepth = Math.max(0, bracketDepth - 1);
+  }
+
+  return null;
 }
 
-function isBareClientElement(expression: string, localName: string): boolean {
-  const expr = stripWrappingParentheses(expression.trim());
-  const escaped = escapeRegExp(localName);
-  return new RegExp(`^<${escaped}\\s*/>$`).test(expr);
+function trimTrailingSemicolon(value: string): string {
+  const trimmed = value.trim();
+  return trimmed.endsWith(";") ? trimmed.slice(0, -1).trim() : trimmed;
 }
 
-function isHeadOnlyFragmentWrapper(expression: string, localName: string): boolean {
+function jsxExpressionRendersClientComponents(
+  expression: string,
+  candidates: RouteLevelClientComponentImport[],
+): RouteLevelClientComponentImport[] {
   const expr = stripWrappingParentheses(expression.trim());
-  const fragmentMatch = /^<>\s*([\s\S]*?)\s*<\/>$/.exec(expr);
-  if (!fragmentMatch) return false;
+  const seen = new Set<string>();
+  const rendered: RouteLevelClientComponentImport[] = [];
+
+  for (const candidate of candidates) {
+    const key = `${candidate.module}\0${candidate.localName}`;
+    if (seen.has(key)) continue;
+    if (!jsxExpressionContainsClientElement(expr, candidate.localName)) continue;
+    seen.add(key);
+    rendered.push(candidate);
+  }
+
+  return rendered;
+}
 
+function jsxExpressionContainsClientElement(expression: string, localName: string): boolean {
   const escaped = escapeRegExp(localName);
-  const clientElementPattern = new RegExp(`<${escaped}(?:\\s[^>]*)?(?:/>|>)`, "g");
-  const matches = [...(fragmentMatch[1] ?? "").matchAll(clientElementPattern)];
-  if (matches.length !== 1) return false;
-  const clientElement = matches[0][0];
-  if (!isBareClientElement(clientElement, localName)) return false;
-
-  const rest = (fragmentMatch[1] ?? "")
-    .replace(clientElement, "")
-    .replace(/<meta\b[^>]*\/>/gi, "")
-    .replace(/<link\b[^>]*\/>/gi, "")
-    .replace(/<base\b[^>]*\/>/gi, "")
-    .replace(/<title\b[^>]*>[\s\S]*?<\/title>/gi, "")
-    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "")
-    .trim();
-
-  return rest.length === 0;
+  return new RegExp(`<${escaped}(?:\\s|/|>)`).test(expression);
 }
 
 function stripWrappingParentheses(value: string): string {
@@ -317,6 +395,10 @@ function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+function isIdentifierChar(value: string): boolean {
+  return /[A-Za-z0-9_$]/.test(value);
+}
+
 export async function validateClientModuleForBrowserBundle(
   route: RouteSpec,
   rootDir: string,
@@ -349,9 +431,13 @@ async function routeComponentHasResolvableClientEntry(
   routeModule: string,
   source: string,
 ): Promise<boolean> {
-  const routeLevelClientImport = findRouteLevelClientComponentImport(source);
-  if (!routeLevelClientImport) return false;
-  return (await resolveClientImportModulePath(rootDir, routeModule, routeLevelClientImport.module)) !== null;
+  const routeLevelClientImports = findRouteLevelClientComponentImports(source);
+  for (const routeLevelClientImport of routeLevelClientImports) {
+    if ((await resolveClientImportModulePath(rootDir, routeModule, routeLevelClientImport.module)) !== null) {
+      return true;
+    }
+  }
+  return false;
 }
 
 export async function describeMissingHydrationClientModule(
@@ -393,8 +479,8 @@ export async function describeMissingHydrationClientModule(
 
   return (
     `${base}\n` +
-    `  The page imports client-looking modules, but inline .client.tsx imports are not route bundles:\n` +
+    `  The page imports client-looking modules, but none was linked into the route manifest:\n` +
     `${importList}\n` +
-    `  Fix: use partial({ component }).Render for embedded client regions, or expose a route-level client module.`
+    `  Fix: run mandu generate with the current source, or set an explicit route-level clientModule.`
   );
 }

package/src/router/fs-scanner.ts

@@ -31,7 +31,7 @@ import {
 import { mark, measure } from "../perf";
 import { METADATA_ROUTES } from "../routes/types";
 import {
-  findRouteLevelClientComponentImport,
+  findRouteLevelClientComponentImports,
   hasUseClientDirective,
   resolveClientImportModulePath,
 } from "./client-entry";
@@ -399,8 +399,8 @@ export class FSScanner {
         if (hasUseClient) {
           clientModule = modulePath;
         } else {
-          const routeLevelClientImport = findRouteLevelClientComponentImport(pageFileContent);
-          if (routeLevelClientImport) {
+          const routeLevelClientImports = findRouteLevelClientComponentImports(pageFileContent);
+          for (const routeLevelClientImport of routeLevelClientImports) {
             const resolvedClientImport = await resolveClientImportModulePath(
               rootDir,
               modulePath,
@@ -408,6 +408,7 @@ export class FSScanner {
             );
             if (resolvedClientImport) {
               clientModule = modulePath;
+              break;
             }
           }
         }