@mandujs/mcp 0.12.2 → 0.13.0

package/src/resources/skills/mandu-composition/rules/comp-island-slot-split.md

@@ -1,167 +1,167 @@
----
-title: Separate Server Logic (Slot) from Client (Island)
-impact: MEDIUM
-impactDescription: Clear server-client boundary
-tags: composition, island, slot, separation
----
-
-## Separate Server Logic (Slot) from Client (Island)
-
-**Impact: MEDIUM (Clear server-client boundary)**
-
-서버 로직(slot)과 클라이언트 로직(Island)을 명확히 분리하세요. slot은 데이터 페칭과 비즈니스 로직, Island는 인터랙션을 담당합니다.
-
-**Incorrect (혼합된 관심사):**
-
-```tsx
-// ❌ 클라이언트 컴포넌트에서 데이터 페칭
-"use client";
-
-export function TodosIsland() {
-  const [todos, setTodos] = useState([]);
-
-  useEffect(() => {
-    // 클라이언트에서 데이터 페칭 → 워터폴 발생
-    fetch("/api/todos")
-      .then(res => res.json())
-      .then(setTodos);
-  }, []);
-
-  return <TodoList todos={todos} />;
-}
-```
-
-**Correct (slot-client 분리):**
-
-```typescript
-// spec/slots/todos.slot.ts - 서버 로직
-import { Mandu } from "@mandujs/core";
-import { db } from "@/lib/db";
-
-export default Mandu.filling()
-  .guard((ctx) => {
-    // 인증 체크 (서버에서)
-    if (!ctx.get("user")) {
-      return ctx.unauthorized("Login required");
-    }
-  })
-  .get(async (ctx) => {
-    // 데이터 페칭 (서버에서)
-    const todos = await db.todo.findMany({
-      where: { userId: ctx.get("user").id },
-      orderBy: { createdAt: "desc" },
-    });
-
-    return ctx.ok({ todos });
-  })
-  .post(async (ctx) => {
-    // 생성 로직 (서버에서)
-    const body = await ctx.body<{ text: string }>();
-    const todo = await db.todo.create({
-      data: { text: body.text, userId: ctx.get("user").id },
-    });
-
-    return ctx.created({ todo });
-  });
-```
-
-```tsx
-// app/todos/client.tsx - 클라이언트 인터랙션
-"use client";
-
-import { useState, useCallback } from "react";
-
-interface TodosIslandProps {
-  initialTodos: Todo[];  // 서버에서 받은 초기 데이터
-}
-
-export function TodosIsland({ initialTodos }: TodosIslandProps) {
-  const [todos, setTodos] = useState(initialTodos);
-  const [input, setInput] = useState("");
-
-  const addTodo = useCallback(async () => {
-    // 낙관적 업데이트
-    const optimisticTodo = { id: Date.now(), text: input, done: false };
-    setTodos(prev => [optimisticTodo, ...prev]);
-    setInput("");
-
-    // 서버에 요청
-    const res = await fetch("/api/todos", {
-      method: "POST",
-      body: JSON.stringify({ text: input }),
-    });
-    const { todo } = await res.json();
-
-    // 실제 데이터로 교체
-    setTodos(prev => prev.map(t =>
-      t.id === optimisticTodo.id ? todo : t
-    ));
-  }, [input]);
-
-  return (
-    <div>
-      <input
-        value={input}
-        onChange={(e) => setInput(e.target.value)}
-        placeholder="New todo..."
-      />
-      <button onClick={addTodo}>Add</button>
-      <ul>
-        {todos.map(todo => (
-          <TodoItem key={todo.id} todo={todo} />
-        ))}
-      </ul>
-    </div>
-  );
-}
-```
-
-```tsx
-// app/todos/page.tsx - 페이지 (서버 컴포넌트)
-import { TodosIsland } from "./client";
-import { loadTodos } from "./slot";
-
-export default async function TodosPage() {
-  // 서버에서 데이터 로드 (워터폴 없음)
-  const { todos } = await loadTodos();
-
-  return (
-    <div>
-      <h1>My Todos</h1>
-      {/* 초기 데이터를 Island에 전달 */}
-      <TodosIsland initialTodos={todos} />
-    </div>
-  );
-}
-```
-
-## 분리 원칙
-
-| 관심사 | 위치 | 예시 |
-|--------|------|------|
-| 데이터 페칭 | Slot | DB 쿼리, API 호출 |
-| 인증/인가 | Slot Guard | 권한 체크 |
-| 비즈니스 로직 | Slot | 유효성 검사, 계산 |
-| 인터랙션 | Island | 클릭, 입력, 애니메이션 |
-| 클라이언트 상태 | Island | useState, useReducer |
-| 낙관적 업데이트 | Island | 즉시 UI 반영 |
-
-## 데이터 흐름
-
-```
-┌─────────────────────────────────────────┐
-│  Page (Server Component)                │
-│  └─ loadTodos() from slot               │
-│     └─ DB Query                         │
-│                                         │
-│  ↓ initialTodos prop                    │
-│                                         │
-│  ┌───────────────────────────────────┐  │
-│  │ TodosIsland (Client Component)    │  │
-│  │ └─ useState(initialTodos)         │  │
-│  │ └─ User interactions              │  │
-│  │ └─ Optimistic updates             │  │
-│  │ └─ POST to /api/todos             │  │
-│  └───────────────────────────────────┘  │
-└─────────────────────────────────────────┘
-```
+---
+title: Separate Server Logic (Slot) from Client (Island)
+impact: MEDIUM
+impactDescription: Clear server-client boundary
+tags: composition, island, slot, separation
+---
+
+## Separate Server Logic (Slot) from Client (Island)
+
+**Impact: MEDIUM (Clear server-client boundary)**
+
+서버 로직(slot)과 클라이언트 로직(Island)을 명확히 분리하세요. slot은 데이터 페칭과 비즈니스 로직, Island는 인터랙션을 담당합니다.
+
+**Incorrect (혼합된 관심사):**
+
+```tsx
+// ❌ 클라이언트 컴포넌트에서 데이터 페칭
+"use client";
+
+export function TodosIsland() {
+  const [todos, setTodos] = useState([]);
+
+  useEffect(() => {
+    // 클라이언트에서 데이터 페칭 → 워터폴 발생
+    fetch("/api/todos")
+      .then(res => res.json())
+      .then(setTodos);
+  }, []);
+
+  return <TodoList todos={todos} />;
+}
+```
+
+**Correct (slot-client 분리):**
+
+```typescript
+// spec/slots/todos.slot.ts - 서버 로직
+import { Mandu } from "@mandujs/core";
+import { db } from "@/lib/db";
+
+export default Mandu.filling()
+  .guard((ctx) => {
+    // 인증 체크 (서버에서)
+    if (!ctx.get("user")) {
+      return ctx.unauthorized("Login required");
+    }
+  })
+  .get(async (ctx) => {
+    // 데이터 페칭 (서버에서)
+    const todos = await db.todo.findMany({
+      where: { userId: ctx.get("user").id },
+      orderBy: { createdAt: "desc" },
+    });
+
+    return ctx.ok({ todos });
+  })
+  .post(async (ctx) => {
+    // 생성 로직 (서버에서)
+    const body = await ctx.body<{ text: string }>();
+    const todo = await db.todo.create({
+      data: { text: body.text, userId: ctx.get("user").id },
+    });
+
+    return ctx.created({ todo });
+  });
+```
+
+```tsx
+// app/todos/client.tsx - 클라이언트 인터랙션
+"use client";
+
+import { useState, useCallback } from "react";
+
+interface TodosIslandProps {
+  initialTodos: Todo[];  // 서버에서 받은 초기 데이터
+}
+
+export function TodosIsland({ initialTodos }: TodosIslandProps) {
+  const [todos, setTodos] = useState(initialTodos);
+  const [input, setInput] = useState("");
+
+  const addTodo = useCallback(async () => {
+    // 낙관적 업데이트
+    const optimisticTodo = { id: Date.now(), text: input, done: false };
+    setTodos(prev => [optimisticTodo, ...prev]);
+    setInput("");
+
+    // 서버에 요청
+    const res = await fetch("/api/todos", {
+      method: "POST",
+      body: JSON.stringify({ text: input }),
+    });
+    const { todo } = await res.json();
+
+    // 실제 데이터로 교체
+    setTodos(prev => prev.map(t =>
+      t.id === optimisticTodo.id ? todo : t
+    ));
+  }, [input]);
+
+  return (
+    <div>
+      <input
+        value={input}
+        onChange={(e) => setInput(e.target.value)}
+        placeholder="New todo..."
+      />
+      <button onClick={addTodo}>Add</button>
+      <ul>
+        {todos.map(todo => (
+          <TodoItem key={todo.id} todo={todo} />
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+```tsx
+// app/todos/page.tsx - 페이지 (서버 컴포넌트)
+import { TodosIsland } from "./client";
+import { loadTodos } from "./slot";
+
+export default async function TodosPage() {
+  // 서버에서 데이터 로드 (워터폴 없음)
+  const { todos } = await loadTodos();
+
+  return (
+    <div>
+      <h1>My Todos</h1>
+      {/* 초기 데이터를 Island에 전달 */}
+      <TodosIsland initialTodos={todos} />
+    </div>
+  );
+}
+```
+
+## 분리 원칙
+
+| 관심사 | 위치 | 예시 |
+|--------|------|------|
+| 데이터 페칭 | Slot | DB 쿼리, API 호출 |
+| 인증/인가 | Slot Guard | 권한 체크 |
+| 비즈니스 로직 | Slot | 유효성 검사, 계산 |
+| 인터랙션 | Island | 클릭, 입력, 애니메이션 |
+| 클라이언트 상태 | Island | useState, useReducer |
+| 낙관적 업데이트 | Island | 즉시 UI 반영 |
+
+## 데이터 흐름
+
+```
+┌─────────────────────────────────────────┐
+│  Page (Server Component)                │
+│  └─ loadTodos() from slot               │
+│     └─ DB Query                         │
+│                                         │
+│  ↓ initialTodos prop                    │
+│                                         │
+│  ┌───────────────────────────────────┐  │
+│  │ TodosIsland (Client Component)    │  │
+│  │ └─ useState(initialTodos)         │  │
+│  │ └─ User interactions              │  │
+│  │ └─ Optimistic updates             │  │
+│  │ └─ POST to /api/todos             │  │
+│  └───────────────────────────────────┘  │
+└─────────────────────────────────────────┘
+```

package/src/resources/skills/mandu-composition/rules/comp-pattern-children.md

@@ -1,149 +1,149 @@
----
-title: Use Children for Composition Over Render Props
-impact: MEDIUM
-impactDescription: Simpler API, better composition
-tags: composition, children, render-props, pattern
----
-
-## Use Children for Composition Over Render Props
-
-**Impact: MEDIUM (Simpler API, better composition)**
-
-`renderX` props 대신 `children`을 사용하여 컴포지션하세요. 더 선언적이고 유연합니다.
-
-**Incorrect (render props):**
-
-```tsx
-// ❌ renderX props 패턴
-function Modal({
-  renderHeader,
-  renderBody,
-  renderFooter,
-  renderCloseButton,
-}: ModalProps) {
-  return (
-    <div className="modal">
-      <div className="modal-header">
-        {renderCloseButton?.()}
-        {renderHeader?.()}
-      </div>
-      <div className="modal-body">
-        {renderBody?.()}
-      </div>
-      <div className="modal-footer">
-        {renderFooter?.()}
-      </div>
-    </div>
-  );
-}
-
-// 사용 시 복잡함
-<Modal
-  renderHeader={() => <h2>Title</h2>}
-  renderBody={() => <p>Content</p>}
-  renderFooter={() => (
-    <>
-      <Button>Cancel</Button>
-      <Button>Save</Button>
-    </>
-  )}
-  renderCloseButton={() => <CloseButton />}
-/>
-```
-
-**Correct (children + compound):**
-
-```tsx
-// ✅ children과 컴파운드 패턴
-function Modal({ children }: { children: React.ReactNode }) {
-  return <div className="modal">{children}</div>;
-}
-
-function ModalHeader({ children }: { children: React.ReactNode }) {
-  return <div className="modal-header">{children}</div>;
-}
-
-function ModalBody({ children }: { children: React.ReactNode }) {
-  return <div className="modal-body">{children}</div>;
-}
-
-function ModalFooter({ children }: { children: React.ReactNode }) {
-  return <div className="modal-footer">{children}</div>;
-}
-
-function ModalClose({ onClose }: { onClose: () => void }) {
-  return <button onClick={onClose} className="modal-close">×</button>;
-}
-
-export { Modal, ModalHeader, ModalBody, ModalFooter, ModalClose };
-```
-
-**사용:**
-
-```tsx
-// 선언적이고 명확함
-<Modal>
-  <ModalHeader>
-    <ModalClose onClose={handleClose} />
-    <h2>Title</h2>
-  </ModalHeader>
-
-  <ModalBody>
-    <p>Content goes here</p>
-  </ModalBody>
-
-  <ModalFooter>
-    <Button onClick={handleClose}>Cancel</Button>
-    <Button onClick={handleSave}>Save</Button>
-  </ModalFooter>
-</Modal>
-```
-
-## 장점
-
-| render props | children |
-|--------------|----------|
-| 숨겨진 구조 | 명시적 구조 |
-| 함수 호출 문법 | JSX 문법 |
-| 순서가 props에 의존 | 순서를 소비자가 제어 |
-| 어떤 props가 있는지 봐야 함 | 자동완성 지원 |
-
-## Mandu Island에서의 적용
-
-```tsx
-// ❌ 피해야 할 패턴
-<FormIsland
-  renderInput={(value, onChange) => <Input value={value} onChange={onChange} />}
-  renderSubmit={(onSubmit) => <Button onClick={onSubmit}>Submit</Button>}
-  renderError={(error) => <ErrorMessage error={error} />}
-/>
-
-// ✅ 권장 패턴
-<Form.Provider>
-  <Form.Frame>
-    <Form.Input name="email" />
-    <Form.Input name="password" type="password" />
-    <Form.Error />
-    <Form.Submit>Sign In</Form.Submit>
-  </Form.Frame>
-</Form.Provider>
-```
-
-## 언제 Render Props를 사용하나?
-
-render props가 여전히 유용한 경우:
-- 부모가 데이터를 제공하고 자식이 렌더링 방법을 결정 (예: virtualized list)
-- 자식에게 상태를 노출해야 하는 headless 컴포넌트
-
-```tsx
-// Render props가 적합한 예: Virtualized List
-<VirtualList
-  items={items}
-  itemHeight={50}
-  renderItem={(item, index) => (
-    <div key={item.id}>{item.name}</div>
-  )}
-/>
-```
-
-Reference: [Compound Components](https://kentcdodds.com/blog/compound-components-with-react-hooks)
+---
+title: Use Children for Composition Over Render Props
+impact: MEDIUM
+impactDescription: Simpler API, better composition
+tags: composition, children, render-props, pattern
+---
+
+## Use Children for Composition Over Render Props
+
+**Impact: MEDIUM (Simpler API, better composition)**
+
+`renderX` props 대신 `children`을 사용하여 컴포지션하세요. 더 선언적이고 유연합니다.
+
+**Incorrect (render props):**
+
+```tsx
+// ❌ renderX props 패턴
+function Modal({
+  renderHeader,
+  renderBody,
+  renderFooter,
+  renderCloseButton,
+}: ModalProps) {
+  return (
+    <div className="modal">
+      <div className="modal-header">
+        {renderCloseButton?.()}
+        {renderHeader?.()}
+      </div>
+      <div className="modal-body">
+        {renderBody?.()}
+      </div>
+      <div className="modal-footer">
+        {renderFooter?.()}
+      </div>
+    </div>
+  );
+}
+
+// 사용 시 복잡함
+<Modal
+  renderHeader={() => <h2>Title</h2>}
+  renderBody={() => <p>Content</p>}
+  renderFooter={() => (
+    <>
+      <Button>Cancel</Button>
+      <Button>Save</Button>
+    </>
+  )}
+  renderCloseButton={() => <CloseButton />}
+/>
+```
+
+**Correct (children + compound):**
+
+```tsx
+// ✅ children과 컴파운드 패턴
+function Modal({ children }: { children: React.ReactNode }) {
+  return <div className="modal">{children}</div>;
+}
+
+function ModalHeader({ children }: { children: React.ReactNode }) {
+  return <div className="modal-header">{children}</div>;
+}
+
+function ModalBody({ children }: { children: React.ReactNode }) {
+  return <div className="modal-body">{children}</div>;
+}
+
+function ModalFooter({ children }: { children: React.ReactNode }) {
+  return <div className="modal-footer">{children}</div>;
+}
+
+function ModalClose({ onClose }: { onClose: () => void }) {
+  return <button onClick={onClose} className="modal-close">×</button>;
+}
+
+export { Modal, ModalHeader, ModalBody, ModalFooter, ModalClose };
+```
+
+**사용:**
+
+```tsx
+// 선언적이고 명확함
+<Modal>
+  <ModalHeader>
+    <ModalClose onClose={handleClose} />
+    <h2>Title</h2>
+  </ModalHeader>
+
+  <ModalBody>
+    <p>Content goes here</p>
+  </ModalBody>
+
+  <ModalFooter>
+    <Button onClick={handleClose}>Cancel</Button>
+    <Button onClick={handleSave}>Save</Button>
+  </ModalFooter>
+</Modal>
+```
+
+## 장점
+
+| render props | children |
+|--------------|----------|
+| 숨겨진 구조 | 명시적 구조 |
+| 함수 호출 문법 | JSX 문법 |
+| 순서가 props에 의존 | 순서를 소비자가 제어 |
+| 어떤 props가 있는지 봐야 함 | 자동완성 지원 |
+
+## Mandu Island에서의 적용
+
+```tsx
+// ❌ 피해야 할 패턴
+<FormIsland
+  renderInput={(value, onChange) => <Input value={value} onChange={onChange} />}
+  renderSubmit={(onSubmit) => <Button onClick={onSubmit}>Submit</Button>}
+  renderError={(error) => <ErrorMessage error={error} />}
+/>
+
+// ✅ 권장 패턴
+<Form.Provider>
+  <Form.Frame>
+    <Form.Input name="email" />
+    <Form.Input name="password" type="password" />
+    <Form.Error />
+    <Form.Submit>Sign In</Form.Submit>
+  </Form.Frame>
+</Form.Provider>
+```
+
+## 언제 Render Props를 사용하나?
+
+render props가 여전히 유용한 경우:
+- 부모가 데이터를 제공하고 자식이 렌더링 방법을 결정 (예: virtualized list)
+- 자식에게 상태를 노출해야 하는 headless 컴포넌트
+
+```tsx
+// Render props가 적합한 예: Virtualized List
+<VirtualList
+  items={items}
+  itemHeight={50}
+  renderItem={(item, index) => (
+    <div key={item.id}>{item.name}</div>
+  )}
+/>
+```
+
+Reference: [Compound Components](https://kentcdodds.com/blog/compound-components-with-react-hooks)