@mandujs/mcp 0.37.2 → 0.37.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.37.2",
+  "version": "0.37.3",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "^0.54.2",
+    "@mandujs/core": "^0.54.3",
     "@mandujs/ate": "^0.26.1",
     "@mandujs/skills": "^0.20.1",
     "@modelcontextprotocol/sdk": "^1.25.3"

package/src/resources/skills/guides.ts

@@ -377,21 +377,21 @@ Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티
 | \`idle\` | 브라우저 유휴 시 | 비중요 기능 |
 | \`interaction\` | 사용자 상호작용 시 | 클릭해야 활성화 |
 
-## Island 만들기
-
-### 1. 클라이언트 컴포넌트 작성
-
-\`\`\`tsx
-// app/counter/client.tsx
-
-"use client";
-
-import { useState } from "react";
-
-export default function Counter({ initial = 0 }: { initial?: number }) {
-  const [count, setCount] = useState(initial);
-
-  return (
+## Inline client region 만들기
+
+### 1. 클라이언트 컴포넌트 작성
+
+\`\`\`tsx
+// app/counter/client.tsx
+
+"use client";
+
+import { useState } from "react";
+
+export function Counter({ initial = 0 }: { initial?: number }) {
+  const [count, setCount] = useState(initial);
+
+  return (
     <div>
       <p>Count: {count}</p>
       <button onClick={() => setCount(c => c - 1)}>-</button>
@@ -399,34 +399,43 @@ export default function Counter({ initial = 0 }: { initial?: number }) {
     </div>
   );
 }
-\`\`\`
-
-### 2. 페이지에서 사용
-
-\`\`\`tsx
-// app/counter/page.tsx
-
-import Counter from "./client";
-
-export default function CounterPage() {
-  return (
+\`\`\`
+
+### 2. 서버 페이지에서 partial로 사용
+
+\`\`\`tsx
+// app/counter/page.tsx
+
+import { partial } from "@mandujs/core/client";
+import { Counter } from "./client";
+
+const CounterPartial = partial({
+  component: Counter,
+  priority: "visible",
+});
+
+export default function CounterPage() {
+  return (
     <div>
       <h1>Counter Demo</h1>
       <p>이 텍스트는 정적 HTML입니다.</p>
-
-      {/* 이 부분만 hydration됩니다 */}
-      <Counter initial={10} />
-    </div>
-  );
-}
-\`\`\`
-
-## Mandu.island() API
-
-고급 Island 패턴을 위한 API:
-
-\`\`\`typescript
-// spec/slots/todos.client.ts
+
+      {/* 이 부분만 hydration됩니다 */}
+      <CounterPartial.Render initial={10} />
+    </div>
+  );
+}
+\`\`\`
+
+## Mandu.island() API
+
+고급 page-level Island 패턴을 위한 API입니다. \`Mandu.island()\`는 단일
+정의 객체만 받습니다. \`island("visible", Component)\` 형태는 지원하지
+않으며, 서버 페이지 안에 inline으로 렌더링할 영역은 \`partial()\`을
+사용하세요.
+
+\`\`\`typescript
+// spec/slots/todos.client.ts
 
 import { Mandu } from "@mandujs/core/client";
 import { useState, useCallback } from "react";

package/src/resources/skills/mandu-hydration/SKILL.md

@@ -57,17 +57,25 @@ Reference these guidelines when:
 - `hydration-data-server` - Access server data with useServerData
 - `hydration-data-event` - Communicate between Islands with useIslandEvent
 
-## Hydration Strategies
-
-| Strategy | Description | Use Case |
-|----------|-------------|----------|
-| `none` | No JavaScript | Pure static pages |
-| `island` | Partial hydration (default) | Static + interactive mix |
-| `full` | Full hydration | SPA-style pages |
-
-## Client Hooks
-
-```typescript
+## Hydration Strategies
+
+| Strategy | Description | Use Case |
+|----------|-------------|----------|
+| `none` | No JavaScript | Pure static pages |
+| `island` | Partial hydration (default) | Static + interactive mix |
+| `full` | Full hydration | SPA-style pages |
+
+## Runtime API Constraints
+
+- `island()` / `Mandu.island()` takes one definition object: `island({ setup, render })`.
+- Do not call `island("visible", Component)`; use `wrapComponent(Component)` for a simple page-level island wrapper.
+- Islands are page-level client bundles. Do not render them as inline JSX like `<MyIsland />`.
+- For an embedded interactive region inside a server page, use `partial()`: put it in `*.partial.tsx`, export `partial({ id, component })`, and render the returned `.Render` component from the server page.
+- A server page that renders partials must opt into hydration, for example `export const hydration = { strategy: "island", priority: "visible", preload: false }`.
+
+## Client Hooks
+
+```typescript
 import {
   useServerData,
   useHydrated,

package/src/resources/skills/mandu-hydration/rules/hydration-island-setup.md

@@ -5,13 +5,60 @@ impactDescription: Proper Island structure
 tags: hydration, island, setup
 ---
 
-## Use Mandu.island() with Setup Function
-
-For complex Islands, use `Mandu.island()` API to separate state logic from rendering.
-
-**Incorrect (mixed concerns):**
-
-```tsx
+## Use Mandu.island() with Setup Function
+
+For complex Islands, use `Mandu.island()` API to separate state logic from rendering.
+`Mandu.island()` takes a single definition object. The shorthand
+`island("visible", Component)` is not a supported Mandu runtime API.
+
+Islands are page-level client bundles. They are discovered and rendered by
+the framework wrapper, not embedded directly as inline JSX. Use `partial()`
+when a server page needs an inline interactive region.
+
+```tsx
+// Simple page-level island wrapper
+"use client";
+
+import { wrapComponent } from "@mandujs/core/client";
+
+function Counter() {
+  return <button>Count</button>;
+}
+
+export default wrapComponent(Counter);
+```
+
+```tsx
+// Inline client region inside a server-rendered page
+// app/Counter.partial.tsx
+import { partial } from "@mandujs/core/client";
+import { Counter } from "./counter.client";
+
+export default partial({
+  id: "Counter",
+  component: Counter,
+  priority: "visible",
+});
+```
+
+```tsx
+// app/page.tsx
+import CounterPartial from "./Counter.partial";
+
+export const hydration = {
+  strategy: "island",
+  priority: "visible",
+  preload: false,
+};
+
+export default function Page() {
+  return <CounterPartial.Render initial={0} />;
+}
+```
+
+**Incorrect (mixed concerns):**
+
+```tsx
 "use client";
 
 export default function TodoList({ initialTodos }) {

package/src/resources/skills/mandu-hydration/rules/hydration-priority-visible.md

@@ -18,43 +18,66 @@ Set hydration priority based on when the component needs to be interactive.
 | `idle` | Browser idle | Non-critical features (analytics widgets) |
 | `interaction` | User action | Click-to-activate components |
 
-## Examples
-
-### Immediate: Always-visible interactions
-
-```tsx
-// Header with navigation - needs to work immediately
-<Island priority="immediate">
-  <HeaderNav />
-</Island>
-```
-
-### Visible: Below-fold content (default)
-
-```tsx
-// Comments section - load when scrolled into view
-<Island priority="visible">
-  <CommentsSection postId={postId} />
-</Island>
-```
-
-### Idle: Background features
-
-```tsx
-// Chat widget - can wait until browser is idle
-<Island priority="idle">
-  <ChatWidget />
-</Island>
-```
-
-### Interaction: On-demand activation
-
-```tsx
-// Video player - only hydrate when user clicks play
-<Island priority="interaction">
-  <VideoPlayer videoId={videoId} />
-</Island>
-```
+## Examples
+
+Inline client regions live in `*.partial.tsx` files and use
+`partial({ id, component, priority })`, then render the returned `.Render`
+component from the server page. The page must export a non-`none` hydration
+config.
+
+### Immediate: Always-visible interactions
+
+```tsx
+// Header with navigation - needs to work immediately
+import { partial } from "@mandujs/core/client";
+
+const HeaderNavPartial = partial({
+  id: "HeaderNav",
+  component: HeaderNav,
+  priority: "immediate",
+});
+
+<HeaderNavPartial.Render />
+```
+
+### Visible: Below-fold content (default)
+
+```tsx
+// Comments section - load when scrolled into view
+const CommentsPartial = partial({
+  id: "Comments",
+  component: CommentsSection,
+  priority: "visible",
+});
+
+<CommentsPartial.Render postId={postId} />
+```
+
+### Idle: Background features
+
+```tsx
+// Chat widget - can wait until browser is idle
+const ChatPartial = partial({
+  id: "Chat",
+  component: ChatWidget,
+  priority: "idle",
+});
+
+<ChatPartial.Render />
+```
+
+### Interaction: On-demand activation
+
+```tsx
+// Video player - only hydrate when user clicks play
+const VideoPartial = partial({
+  id: "Video",
+  component: VideoPlayer,
+  priority: "interaction",
+});
+
+<VideoPartial.Render videoId={videoId} />
+```
 
 ## Performance Impact
 

package/src/resources/skills/recipes.ts

@@ -469,24 +469,30 @@ export default function Counter({ initial = 0, step = 1 }: CounterProps) {
 }
 \`\`\`
 
-## Step 2: 페이지에서 사용
-
-\`\`\`tsx
-// app/counter/page.tsx
-
-import Counter from "./client";
-
-export default function CounterPage() {
-  return (
+## Step 2: 서버 페이지에서 partial로 사용
+
+\`\`\`tsx
+// app/counter/page.tsx
+
+import { partial } from "@mandujs/core/client";
+import Counter from "./client";
+
+const CounterPartial = partial({
+  component: Counter,
+  priority: "visible",
+});
+
+export default function CounterPage() {
+  return (
     <div style={{ padding: "20px" }}>
       <h1>Counter Demo</h1>
       <p>아래 카운터는 클라이언트에서 hydration됩니다.</p>
-
-      {/* Island 컴포넌트 */}
-      <Counter initial={10} step={5} />
-
-      <p style={{ marginTop: "20px", color: "#666" }}>
-        이 텍스트는 정적 HTML입니다.
+
+      {/* Inline client region */}
+      <CounterPartial.Render initial={10} step={5} />
+
+      <p style={{ marginTop: "20px", color: "#666" }}>
+        이 텍스트는 정적 HTML입니다.
       </p>
     </div>
   );
@@ -618,10 +624,13 @@ export default function UserList() {
 
 ## Mandu.island() API (고급)
 
-서버 데이터와 클라이언트 상태를 분리하려면:
-
-\`\`\`typescript
-// spec/slots/todos.client.ts
+서버 데이터와 클라이언트 상태를 분리하는 page-level Island가 필요하면
+\`Mandu.island({ setup, render })\`를 사용합니다. \`island("visible",
+Component)\`는 지원하지 않습니다. 서버 페이지 안에 inline으로 렌더링할
+영역은 \`partial()\`을 사용하세요.
+
+\`\`\`typescript
+// spec/slots/todos.client.ts
 
 import { Mandu } from "@mandujs/core/client";
 import { useState } from "react";

package/src/tools/guard.ts

@@ -1,10 +1,13 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { type ManduError } from "@mandujs/core/error";
-import {
-  loadManifest,
-  runGuardCheck,
-  runAutoCorrect,
-  type GeneratedMap,
+import {
+  checkDirectory,
+  getDefaultFsRoutesGuardPolicy,
+  validateAndReport,
+  loadManifest,
+  runGuardCheck,
+  runAutoCorrect,
+  type GeneratedMap,
   // Self-Healing Guard imports
   checkWithHealing,
   healAll,
@@ -12,16 +15,19 @@ import {
   // Follow-up E — type-aware lint bridge
   runTsgolint,
   type GuardConfig,
-  type ViolationType,
-  type GuardPreset,
-} from "@mandujs/core";
-import { getProjectPaths, readJsonFile, readConfig } from "../utils/project.js";
+  type ViolationType,
+  type GuardPreset,
+  type Violation,
+} from "@mandujs/core";
+import { getProjectPaths, readJsonFile, readConfig } from "../utils/project.js";
+import fs from "fs/promises";
+import path from "path";
 
 export const guardToolDefinitions: Tool[] = [
   {
-    name: "mandu.guard.check",
-    description:
-      "Run guard checks to validate spec integrity, generated files, and slot files. Set typeAware=true to additionally run `oxlint --type-aware` (tsgolint) and merge its results.",
+    name: "mandu.guard.check",
+    description:
+      "Run the same architecture guard used by `mandu guard`, plus legacy spec/generated/slot checks. Set typeAware=true to additionally run `oxlint --type-aware` (tsgolint) and merge its results.",
     annotations: {
       readOnlyHint: true,
     },
@@ -120,8 +126,37 @@ export const guardToolDefinitions: Tool[] = [
   },
 ];
 
-export function guardTools(projectRoot: string) {
-  const paths = getProjectPaths(projectRoot);
+export function guardTools(projectRoot: string) {
+  const paths = getProjectPaths(projectRoot);
+
+  const pathExists = async (candidate: string): Promise<boolean> => {
+    try {
+      await fs.access(candidate);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const summarizeArchitectureViolation = (violation: Violation) => ({
+    ruleId: violation.ruleName,
+    type: violation.type,
+    file: path.relative(projectRoot, violation.filePath).replace(/\\/g, "/") || violation.filePath,
+    line: violation.line,
+    column: violation.column,
+    message: violation.ruleDescription,
+    suggestion: violation.suggestions[0],
+    fromLayer: violation.fromLayer,
+    toLayer: violation.toLayer,
+    importStatement: violation.importStatement,
+  });
+
+  const summarizeLegacyViolation = (v: Awaited<ReturnType<typeof runGuardCheck>>["violations"][number]) => ({
+    ruleId: v.ruleId,
+    file: v.file,
+    message: v.message,
+    suggestion: v.suggestion,
+  });
 
   const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
     "mandu.guard.check": async (args: Record<string, unknown>) => {
@@ -137,25 +172,44 @@ export function guardTools(projectRoot: string) {
           error: "Failed to load manifest",
           details: manifestResult.errors,
         };
-      }
-
-      // Run guard check
-      const checkResult = await runGuardCheck(manifestResult.data, projectRoot);
+      }
+
+      const projectConfig = await validateAndReport(projectRoot);
+      const guardConfigFromFile = (projectConfig?.guard ?? {}) as GuardConfig;
+      const preset = guardConfigFromFile.preset ?? "mandu";
+      const enableFsRoutes = await pathExists(paths.appDir);
+
+      const architectureReport = await checkDirectory(
+        {
+          preset,
+          srcDir: guardConfigFromFile.srcDir ?? "src",
+          exclude: guardConfigFromFile.exclude,
+          fsRoutes: getDefaultFsRoutesGuardPolicy(enableFsRoutes),
+        },
+        projectRoot
+      );
+      const architecturePassed = architectureReport.bySeverity.error === 0;
+      const architectureViolations = architectureReport.violations.map(
+        summarizeArchitectureViolation
+      );
+
+      // Run guard check
+      const checkResult = await runGuardCheck(manifestResult.data, projectRoot);
 
       // Follow-up E — resolve type-aware defaulting from config, then
       // run the bridge when enabled. Result envelope is always included
       // in the tool response so MCP clients have a single stable shape.
-      let projectConfig: Awaited<ReturnType<typeof readConfig>> | undefined;
-      try {
-        projectConfig = await readConfig(projectRoot);
-      } catch {
-        projectConfig = undefined;
-      }
-      const typeAwareCfg = (
-        projectConfig?.guard as
-          | { typeAware?: Record<string, unknown> }
-          | undefined
-      )?.typeAware;
+      let rawProjectConfig: Awaited<ReturnType<typeof readConfig>> | undefined;
+      try {
+        rawProjectConfig = projectConfig ?? await readConfig(projectRoot);
+      } catch {
+        rawProjectConfig = projectConfig ?? undefined;
+      }
+      const typeAwareCfg = (
+        rawProjectConfig?.guard as
+          | { typeAware?: Record<string, unknown> }
+          | undefined
+      )?.typeAware;
       const typeAwareEnabled =
         typeAwareArg !== undefined ? typeAwareArg : typeAwareCfg !== undefined;
 
@@ -175,21 +229,40 @@ export function guardTools(projectRoot: string) {
           skipped: bridge.skipped,
           summary: bridge.summary,
           violations: bridge.violations,
-        };
-      }
-
-      if (checkResult.passed) {
-        return {
-          passed: typeAwareResponse
-            ? (typeAwareResponse.violations as Array<{ severity: string }>).filter(
-                (v) => v.severity === "error",
-              ).length === 0
-            : true,
-          violations: [],
-          message: "All guard checks passed",
-          relatedSkills: ["mandu-guard-guide", "mandu-debug"],
-          ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
-        };
+        };
+      }
+
+      const typeAwareViolations = typeAwareResponse
+        ? typeAwareResponse.violations as Array<{ severity: string }>
+        : [];
+      const typeAwareErrorCount = typeAwareViolations.filter(
+        (v) => v.severity === "error",
+      ).length;
+      const legacyViolations = checkResult.violations.map(summarizeLegacyViolation);
+      const combinedViolations = [
+        ...architectureViolations,
+        ...legacyViolations,
+      ];
+      const allPassed = checkResult.passed && architecturePassed && typeAwareErrorCount === 0;
+      const blockingViolationCount = combinedViolations.length + typeAwareErrorCount;
+
+      if (allPassed) {
+        return {
+          passed: true,
+          violations: [],
+          message: "All guard checks passed",
+          architecture: {
+            passed: true,
+            totalViolations: architectureReport.totalViolations,
+            bySeverity: architectureReport.bySeverity,
+          },
+          legacy: {
+            passed: true,
+            violations: 0,
+          },
+          relatedSkills: ["mandu-guard-guide", "mandu-debug"],
+          ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
+        };
       }
 
       // If auto-correct requested and there are violations
@@ -200,33 +273,54 @@ export function guardTools(projectRoot: string) {
           projectRoot
         );
 
-        return {
-          passed: autoCorrectResult.fixed,
-          violations: autoCorrectResult.remainingViolations,
-          autoCorrect: {
-            attempted: true,
-            fixed: autoCorrectResult.fixed,
+        return {
+          passed:
+            autoCorrectResult.fixed &&
+            architecturePassed &&
+            typeAwareErrorCount === 0,
+          violations: [
+            ...architectureViolations,
+            ...autoCorrectResult.remainingViolations.map(summarizeLegacyViolation),
+          ],
+          autoCorrect: {
+            attempted: true,
+            fixed: autoCorrectResult.fixed,
             steps: autoCorrectResult.steps,
             retriedCount: autoCorrectResult.retriedCount,
             rolledBack: autoCorrectResult.rolledBack,
-            changeId: autoCorrectResult.changeId,
-          },
-          ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
-        };
-      }
-
-      return {
-        passed: false,
-        violations: checkResult.violations.map((v) => ({
-          ruleId: v.ruleId,
-          file: v.file,
-          message: v.message,
-          suggestion: v.suggestion,
-        })),
-        message: `Found ${checkResult.violations.length} violation(s)`,
-        tip: "Use autoCorrect: true to attempt automatic fixes",
-        relatedSkills: ["mandu-guard-guide", "mandu-debug"],
-        ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
+            changeId: autoCorrectResult.changeId,
+          },
+          architecture: {
+            passed: architecturePassed,
+            totalViolations: architectureReport.totalViolations,
+            bySeverity: architectureReport.bySeverity,
+            violations: architectureViolations,
+          },
+          legacy: {
+            passed: autoCorrectResult.fixed,
+            violations: autoCorrectResult.remainingViolations.length,
+          },
+          ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
+        };
+      }
+
+      return {
+        passed: false,
+        violations: combinedViolations,
+        message: `Found ${blockingViolationCount} violation(s)`,
+        architecture: {
+          passed: architecturePassed,
+          totalViolations: architectureReport.totalViolations,
+          bySeverity: architectureReport.bySeverity,
+          violations: architectureViolations,
+        },
+        legacy: {
+          passed: checkResult.passed,
+          violations: legacyViolations.length,
+        },
+        tip: "Use autoCorrect: true to attempt automatic fixes",
+        relatedSkills: ["mandu-guard-guide", "mandu-debug"],
+        ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
       };
     },