@mandujs/mcp 0.38.11 → 0.39.0-beta.1

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

@@ -1,160 +0,0 @@
----
-title: Use Mandu.island() with Setup Function
-impact: HIGH
-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.
-`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 }) {
-  // State, handlers, and JSX all mixed together
-  const [todos, setTodos] = useState(initialTodos);
-  const [input, setInput] = useState("");
-
-  const add = () => {
-    setTodos([...todos, { id: Date.now(), text: input }]);
-    setInput("");
-  };
-
-  return (
-    <div>
-      <input value={input} onChange={e => setInput(e.target.value)} />
-      <button onClick={add}>Add</button>
-      {todos.map(t => <li key={t.id}>{t.text}</li>)}
-    </div>
-  );
-}
-```
-
-**Correct (Mandu.island pattern):**
-
-```tsx
-// spec/slots/todos.client.ts
-
-import { Mandu } from "@mandujs/core/client";
-import { useState, useCallback } from "react";
-
-interface TodosData {
-  todos: { id: number; text: string; done: boolean }[];
-}
-
-export default Mandu.island<TodosData>({
-  // Setup: Initialize client state from server data
-  setup: (serverData) => {
-    const [todos, setTodos] = useState(serverData.todos);
-    const [input, setInput] = useState("");
-
-    const addTodo = useCallback(() => {
-      if (!input.trim()) return;
-      setTodos(prev => [...prev, { id: Date.now(), text: input, done: false }]);
-      setInput("");
-    }, [input]);
-
-    const toggleTodo = useCallback((id: number) => {
-      setTodos(prev => prev.map(t =>
-        t.id === id ? { ...t, done: !t.done } : t
-      ));
-    }, []);
-
-    return { todos, input, setInput, addTodo, toggleTodo };
-  },
-
-  // Render: Pure rendering logic
-  render: ({ todos, input, setInput, addTodo, toggleTodo }) => (
-    <div>
-      <input
-        value={input}
-        onChange={e => setInput(e.target.value)}
-        placeholder="New todo..."
-      />
-      <button onClick={addTodo}>Add</button>
-      <ul>
-        {todos.map(todo => (
-          <li
-            key={todo.id}
-            onClick={() => toggleTodo(todo.id)}
-            style={{ textDecoration: todo.done ? "line-through" : "none" }}
-          >
-            {todo.done ? "✅" : "⬜"} {todo.text}
-          </li>
-        ))}
-      </ul>
-    </div>
-  ),
-
-  // Optional: Error boundary
-  errorBoundary: (error, reset) => (
-    <div>
-      <p>Error: {error.message}</p>
-      <button onClick={reset}>Retry</button>
-    </div>
-  ),
-
-  // Optional: Loading state
-  loading: () => <p>Loading todos...</p>,
-});
-```
-
-## Mandu.island() Options
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `setup` | Yes | Initialize state from server data |
-| `render` | Yes | Pure render function |
-| `errorBoundary` | No | Error UI component |
-| `loading` | No | Loading UI component |

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

@@ -1,91 +0,0 @@
----
-title: Use Visible Priority for Below-Fold Content
-impact: MEDIUM
-impactDescription: Optimizes initial page load
-tags: hydration, priority, performance
----
-
-## Use Visible Priority for Below-Fold Content
-
-Set hydration priority based on when the component needs to be interactive.
-
-## Hydration Priorities
-
-| Priority | Load Time | Use Case |
-|----------|-----------|----------|
-| `immediate` | Page load | Critical interactions (header nav, auth forms) |
-| `visible` | Viewport entry (default) | Below-fold content |
-| `idle` | Browser idle | Non-critical features (analytics widgets) |
-| `interaction` | User action | Click-to-activate components |
-
-## 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
-
-```
-immediate: +JavaScript bundle at page load
-visible:   +JavaScript when component enters viewport
-idle:      +JavaScript during browser idle time
-interaction: +JavaScript on first user interaction
-```
-
-**Rule of thumb**: Use `visible` (default) unless you have a specific reason to choose another priority.

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

@@ -1,125 +0,0 @@
----
-name: mandu-performance
-description: |
-  Performance optimization patterns for Mandu applications. Use when optimizing
-  slot handlers, Island components, bundle size, or Bun runtime. Triggers on
-  tasks involving async/await, Promise.all, lazy loading, caching, or performance.
-license: MIT
-metadata:
-  author: mandu
-  version: "1.0.0"
----
-
-# Mandu Performance
-
-Mandu 애플리케이션의 성능 최적화 가이드. 워터폴 제거, 번들 최적화, 캐싱 패턴, Bun 런타임 활용법을 다룹니다. Vercel의 React Best Practices를 Mandu 컨텍스트로 변환하여 적용합니다.
-
-## Agent Workflow Contract
-
-This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
-Use it only after `mandu.agent.plan` selects performance, hydration, route, API, or runtime domains.
-
-Canonical workflow step: `plan -> verify -> repair`.
-
-Preferred MCP tools:
-
-| Step | Tools |
-|------|-------|
-| plan | `mandu.agent.plan`, `mandu.agent.context` |
-| apply | `mandu.agent.apply` |
-| verify | `mandu.agent.verify`, `mandu.build`, `mandu.run.tests` |
-| repair | `mandu.agent.repair` |
-
-Allowed file edits:
-
-- Route, slot, island, or cache code named in the plan
-- Import boundaries that reduce bundle/runtime cost
-- Benchmark/test files scoped to the performance claim
-
-Verification command:
-
-```bash
-mandu agent verify --changed --json --write
-```
-
-Common failures:
-
-- Optimizing without a measurable route, bundle, or runtime target
-- Moving server-only code into client islands for convenience
-- Skipping typecheck or targeted tests after cache/import rewrites
-
-Repair path:
-
-```bash
-mandu agent repair --from .mandu/agent-verify.json --json
-```
-
-## When to Apply
-
-Reference these guidelines when:
-- Optimizing slot handler response times
-- Reducing Island component bundle size
-- Implementing caching strategies
-- Working with async/await patterns
-- Leveraging Bun runtime features
-
-## Rule Categories by Priority
-
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Async Optimization | CRITICAL | `perf-async-` |
-| 2 | Bundle Optimization | CRITICAL | `perf-bundle-` |
-| 3 | Caching Strategies | HIGH | `perf-cache-` |
-| 4 | Bun Runtime | HIGH | `perf-bun-` |
-| 5 | Rendering | MEDIUM | `perf-render-` |
-
-## Quick Reference
-
-### 1. Async Optimization (CRITICAL)
-
-- `perf-async-parallel` - Use Promise.all() for independent operations
-- `perf-async-defer-await` - Move await into branches where actually used
-- `perf-async-early-start` - Start promises early, await late
-
-### 2. Bundle Optimization (CRITICAL)
-
-- `perf-bundle-imports` - Import directly, avoid barrel files
-- `perf-bundle-island-lazy` - Lazy load Islands with dynamic import
-- `perf-bundle-preload` - Preload on hover/focus for perceived speed
-
-### 3. Caching Strategies (HIGH)
-
-- `perf-cache-slot` - Cache slot responses with appropriate TTL
-- `perf-cache-react` - Use React.cache() for request deduplication
-- `perf-cache-lru` - Use LRU cache for cross-request caching
-
-### 4. Bun Runtime (HIGH)
-
-- `perf-bun-serve` - Optimize Bun.serve() configuration
-- `perf-bun-file` - Use Bun.file() for efficient file operations
-- `perf-bun-sqlite` - Leverage bun:sqlite for fast database access
-
-### 5. Rendering (MEDIUM)
-
-- `perf-render-island-priority` - Set appropriate hydration priority
-- `perf-render-transitions` - Use startTransition for non-urgent updates
-
-## Performance Impact Summary
-
-| Optimization | Typical Improvement |
-|--------------|---------------------|
-| Promise.all() | 2-10× faster |
-| Direct imports | 15-70% faster dev boot |
-| Island lazy loading | 40-60% smaller initial bundle |
-| React.cache() | Eliminates duplicate queries |
-| Bun.file() | 10× faster than Node fs |
-
-## How to Use
-
-Read individual rule files for detailed explanations:
-
-```
-rules/perf-async-parallel.md
-rules/perf-bundle-imports.md
-rules/perf-bun-serve.md
-```

package/src/resources/skills/mandu-performance/metadata.json

@@ -1,14 +0,0 @@
-{
-  "version": "1.0.0",
-  "organization": "Mandu Framework",
-  "date": "February 2026",
-  "abstract": "Mandu 애플리케이션 성능 최적화 가이드. 워터폴 제거 (Promise.all), 번들 최적화 (직접 import, lazy loading), 캐싱 전략 (React.cache, LRU), Bun 런타임 활용 (Bun.serve, Bun.file)을 다룹니다. Vercel React Best Practices 기반으로 Mandu 컨텍스트에 맞게 변환되었습니다.",
-  "references": [
-    "https://vercel.com/blog/how-we-optimized-package-imports-in-next-js",
-    "https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast",
-    "https://bun.sh/docs/api/http",
-    "https://bun.sh/docs/api/file-io",
-    "https://react.dev/reference/react/cache"
-  ],
-  "tags": ["performance", "async", "bundle", "cache", "bun", "mandu"]
-}

package/src/resources/skills/mandu-performance/rules/_sections.md

@@ -1,31 +0,0 @@
-# Sections
-
-This file defines all sections, their ordering, impact levels, and descriptions.
-The section ID (in parentheses) is the filename prefix used to group rules.
-
----
-
-## 1. Async Optimization (perf-async)
-
-**Impact:** CRITICAL
-**Description:** 워터폴은 성능의 #1 킬러입니다. 순차적 await는 매번 전체 네트워크 지연을 추가합니다. 워터폴 제거가 가장 큰 성능 향상을 가져옵니다.
-
-## 2. Bundle Optimization (perf-bundle)
-
-**Impact:** CRITICAL
-**Description:** 초기 번들 크기 감소는 Time to Interactive와 Largest Contentful Paint를 개선합니다. Island lazy loading과 직접 import가 핵심입니다.
-
-## 3. Caching Strategies (perf-cache)
-
-**Impact:** HIGH
-**Description:** 적절한 캐싱은 불필요한 연산과 네트워크 요청을 제거합니다. React.cache()는 요청 내 중복 제거, LRU는 요청 간 캐싱에 사용합니다.
-
-## 4. Bun Runtime (perf-bun)
-
-**Impact:** HIGH
-**Description:** Bun의 네이티브 API (Bun.serve, Bun.file, bun:sqlite)는 Node.js 대비 현저히 빠릅니다. Mandu는 Bun 기반이므로 이를 최대한 활용해야 합니다.
-
-## 5. Rendering Performance (perf-render)
-
-**Impact:** MEDIUM
-**Description:** Island hydration 우선순위 설정과 startTransition 활용으로 사용자 체감 성능을 개선합니다.

package/src/resources/skills/mandu-performance/rules/_template.md

@@ -1,64 +0,0 @@
-# Rule Template
-
-Use this template when creating new rules for mandu-performance.
-
----
-
-```markdown
----
-title: Rule Title Here
-impact: CRITICAL | HIGH | MEDIUM | LOW
-impactDescription: 개선 수치 (예: "2-10× improvement", "40% faster")
-tags: performance, tag1, tag2
----
-
-## Rule Title Here
-
-**Impact: {LEVEL} ({impactDescription})**
-
-규칙의 목적과 성능 영향을 설명합니다.
-
-**Incorrect (문제점 - 성능 영향 명시):**
-
-\`\`\`typescript
-// ❌ 순차 실행: 3번의 네트워크 왕복
-const user = await fetchUser();
-const posts = await fetchPosts();
-const comments = await fetchComments();
-// 총 시간: 100ms + 100ms + 100ms = 300ms
-\`\`\`
-
-**Correct (해결책 - 성능 개선 명시):**
-
-\`\`\`typescript
-// ✅ 병렬 실행: 1번의 네트워크 왕복
-const [user, posts, comments] = await Promise.all([
-  fetchUser(),
-  fetchPosts(),
-  fetchComments(),
-]);
-// 총 시간: max(100ms, 100ms, 100ms) = 100ms
-\`\`\`
-
-## Mandu Context
-
-Mandu에서 이 규칙을 적용하는 구체적인 방법을 설명합니다.
-
-Reference: [관련 문서 링크](https://example.com)
-```
-
----
-
-## Naming Convention
-
-- 파일명: `perf-{category}-{rule-name}.md`
-- 예시: `perf-async-parallel.md`, `perf-bundle-imports.md`
-
-## Impact Measurement
-
-| Level | Typical Improvement |
-|-------|---------------------|
-| CRITICAL | 2-10× or 50%+ |
-| HIGH | 20-50% |
-| MEDIUM | 10-20% |
-| LOW | < 10% |

package/src/resources/skills/mandu-performance/rules/perf-async-defer-await.md

@@ -1,103 +0,0 @@
----
-title: Defer await to Where Actually Used
-impact: CRITICAL
-impactDescription: Eliminates unnecessary blocking
-tags: performance, async, await, slot
----
-
-## Defer await to Where Actually Used
-
-**Impact: CRITICAL (Eliminates unnecessary blocking)**
-
-await는 실제로 값이 필요한 시점까지 지연하세요. 함수 시작에서 모든 것을 await하면 불필요한 블로킹이 발생합니다.
-
-**Incorrect (너무 일찍 await):**
-
-```typescript
-// spec/slots/user.slot.ts
-import { Mandu } from "@mandujs/core";
-
-export default Mandu.filling()
-  .get(async (ctx) => {
-    const userId = ctx.params.id;
-
-    // ❌ 캐시 확인 전에 DB 쿼리 시작하고 대기
-    const user = await fetchUserFromDB(userId);
-
-    // 캐시에 있으면 DB 쿼리는 불필요했음
-    const cached = cache.get(`user:${userId}`);
-    if (cached) {
-      return ctx.ok(cached);
-    }
-
-    return ctx.ok(user);
-  });
-```
-
-**Correct (필요한 시점에 await):**
-
-```typescript
-// spec/slots/user.slot.ts
-import { Mandu } from "@mandujs/core";
-
-export default Mandu.filling()
-  .get(async (ctx) => {
-    const userId = ctx.params.id;
-
-    // 캐시 먼저 확인
-    const cached = cache.get(`user:${userId}`);
-    if (cached) {
-      return ctx.ok(cached);  // DB 쿼리 안 함
-    }
-
-    // ✅ 캐시 미스일 때만 DB 쿼리
-    const user = await fetchUserFromDB(userId);
-    cache.set(`user:${userId}`, user);
-
-    return ctx.ok(user);
-  });
-```
-
-## Promise 시작은 일찍, await는 늦게
-
-```typescript
-export default Mandu.filling()
-  .get(async (ctx) => {
-    // ✅ Promise 시작 (블로킹 없음)
-    const userPromise = fetchUser(ctx.params.id);
-    const configPromise = fetchConfig();
-
-    // 동기 작업 수행
-    const requestId = generateRequestId();
-    const timestamp = Date.now();
-    logRequest(requestId, timestamp);
-
-    // ✅ 필요한 시점에 await
-    const [user, config] = await Promise.all([userPromise, configPromise]);
-
-    return ctx.ok({ user, config, requestId });
-  });
-```
-
-## 조건부 분기에서의 활용
-
-```typescript
-export default Mandu.filling()
-  .get(async (ctx) => {
-    const { type } = ctx.query;
-
-    if (type === "summary") {
-      // 요약만 필요하면 상세 데이터 불필요
-      const summary = await fetchSummary(ctx.params.id);
-      return ctx.ok({ summary });
-    }
-
-    // 상세 데이터가 필요한 경우에만 fetch
-    const [summary, details] = await Promise.all([
-      fetchSummary(ctx.params.id),
-      fetchDetails(ctx.params.id),
-    ]);
-
-    return ctx.ok({ summary, details });
-  });
-```

package/src/resources/skills/mandu-performance/rules/perf-async-parallel.md

@@ -1,95 +0,0 @@
----
-title: Use Promise.all() for Independent Operations
-impact: CRITICAL
-impactDescription: 2-10× improvement
-tags: performance, async, parallel, promises, slot
----
-
-## Use Promise.all() for Independent Operations
-
-**Impact: CRITICAL (2-10× improvement)**
-
-독립적인 비동기 작업은 `Promise.all()`로 병렬 실행하세요. 순차 실행은 각 await마다 전체 네트워크 지연을 추가합니다.
-
-**Incorrect (순차 실행, 3번의 왕복):**
-
-```typescript
-// spec/slots/dashboard.slot.ts
-import { Mandu } from "@mandujs/core";
-
-export default Mandu.filling()
-  .get(async (ctx) => {
-    // ❌ 순차 실행: 300ms (100ms × 3)
-    const user = await fetchUser(ctx.get("userId"));
-    const posts = await fetchPosts(ctx.get("userId"));
-    const notifications = await fetchNotifications(ctx.get("userId"));
-
-    return ctx.ok({ user, posts, notifications });
-  });
-```
-
-**Correct (병렬 실행, 1번의 왕복):**
-
-```typescript
-// spec/slots/dashboard.slot.ts
-import { Mandu } from "@mandujs/core";
-
-export default Mandu.filling()
-  .get(async (ctx) => {
-    const userId = ctx.get("userId");
-
-    // ✅ 병렬 실행: 100ms (가장 느린 것 기준)
-    const [user, posts, notifications] = await Promise.all([
-      fetchUser(userId),
-      fetchPosts(userId),
-      fetchNotifications(userId),
-    ]);
-
-    return ctx.ok({ user, posts, notifications });
-  });
-```
-
-## 부분 의존성이 있는 경우
-
-일부 작업이 다른 작업의 결과에 의존하는 경우:
-
-```typescript
-export default Mandu.filling()
-  .get(async (ctx) => {
-    // 1단계: 독립적인 작업 병렬 실행
-    const [user, config] = await Promise.all([
-      fetchUser(ctx.get("userId")),
-      fetchConfig(),
-    ]);
-
-    // 2단계: user에 의존하는 작업 병렬 실행
-    const [posts, followers] = await Promise.all([
-      fetchPosts(user.id),
-      fetchFollowers(user.id),
-    ]);
-
-    return ctx.ok({ user, config, posts, followers });
-  });
-```
-
-## Promise.allSettled() 사용
-
-일부 실패를 허용하는 경우:
-
-```typescript
-const results = await Promise.allSettled([
-  fetchUser(userId),
-  fetchPosts(userId),   // 실패해도 OK
-  fetchNotifications(userId),  // 실패해도 OK
-]);
-
-const [userResult, postsResult, notificationsResult] = results;
-
-return ctx.ok({
-  user: userResult.status === "fulfilled" ? userResult.value : null,
-  posts: postsResult.status === "fulfilled" ? postsResult.value : [],
-  notifications: notificationsResult.status === "fulfilled" ? notificationsResult.value : [],
-});
-```
-
-Reference: [MDN Promise.all()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all)