@mandujs/mcp 0.9.19 → 0.9.21

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

@@ -0,0 +1,95 @@
+---
+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)

package/src/resources/skills/mandu-performance/rules/perf-bun-file.md

@@ -0,0 +1,124 @@
+---
+title: Use Bun.file() for Efficient File Operations
+impact: HIGH
+impactDescription: 10× faster than Node.js fs
+tags: performance, bun, file, io
+---
+
+## Use Bun.file() for Efficient File Operations
+
+**Impact: HIGH (10× faster than Node.js fs)**
+
+Bun.file()은 lazy 로딩과 스트리밍을 지원하여 Node.js fs보다 훨씬 빠릅니다.
+
+**Incorrect (Node.js 방식):**
+
+```typescript
+import { readFile, writeFile } from "fs/promises";
+
+// ❌ 전체 파일을 메모리에 로드
+const content = await readFile("./data.json", "utf-8");
+const data = JSON.parse(content);
+```
+
+**Correct (Bun.file 방식):**
+
+```typescript
+// ✅ Lazy 로딩, 필요할 때만 읽음
+const file = Bun.file("./data.json");
+
+// 메타데이터만 읽기 (파일 내용 로드 안 함)
+console.log(file.size);  // 빠름
+console.log(file.type);  // "application/json"
+
+// 필요할 때 내용 읽기
+const data = await file.json();  // JSON 파싱 내장
+```
+
+## Mandu Slot에서의 활용
+
+```typescript
+// spec/slots/files.slot.ts
+import { Mandu } from "@mandujs/core";
+
+export default Mandu.filling()
+  .get(async (ctx) => {
+    const filename = ctx.params.filename;
+    const file = Bun.file(`./uploads/${filename}`);
+
+    // ✅ 파일 존재 확인
+    if (!(await file.exists())) {
+      return ctx.notFound("File not found");
+    }
+
+    // ✅ 스트리밍 응답
+    return new Response(file, {
+      headers: {
+        "Content-Type": file.type,
+        "Content-Length": String(file.size),
+      },
+    });
+  })
+
+  .post(async (ctx) => {
+    const body = await ctx.body<{ content: string }>();
+
+    // ✅ 효율적인 파일 쓰기
+    await Bun.write("./uploads/new-file.txt", body.content);
+
+    return ctx.created({ message: "File saved" });
+  });
+```
+
+## 대용량 파일 스트리밍
+
+```typescript
+export default Mandu.filling()
+  .get(async (ctx) => {
+    const file = Bun.file("./large-video.mp4");
+
+    // ✅ Range 요청 지원 (비디오 스트리밍)
+    const range = ctx.headers.get("range");
+
+    if (range) {
+      const [start, end] = parseRange(range, file.size);
+      const chunk = file.slice(start, end + 1);
+
+      return new Response(chunk, {
+        status: 206,
+        headers: {
+          "Content-Range": `bytes ${start}-${end}/${file.size}`,
+          "Content-Length": String(end - start + 1),
+          "Content-Type": file.type,
+        },
+      });
+    }
+
+    return new Response(file);
+  });
+```
+
+## 파일 타입별 메서드
+
+```typescript
+const file = Bun.file("./data.json");
+
+// 타입별 파싱 메서드
+await file.text();        // string
+await file.json();        // object
+await file.arrayBuffer(); // ArrayBuffer
+await file.stream();      // ReadableStream
+```
+
+## 여러 파일 동시 읽기
+
+```typescript
+// ✅ 병렬로 여러 파일 읽기
+const [config, data, schema] = await Promise.all([
+  Bun.file("./config.json").json(),
+  Bun.file("./data.json").json(),
+  Bun.file("./schema.json").json(),
+]);
+```
+
+Reference: [Bun.file() documentation](https://bun.sh/docs/api/file-io)

package/src/resources/skills/mandu-performance/rules/perf-bun-serve.md

@@ -0,0 +1,125 @@
+---
+title: Optimize Bun.serve() Configuration
+impact: HIGH
+impactDescription: 2-5× faster than Node.js http
+tags: performance, bun, serve, runtime
+---
+
+## Optimize Bun.serve() Configuration
+
+**Impact: HIGH (2-5× faster than Node.js http)**
+
+Mandu는 Bun.serve()를 기반으로 합니다. 적절한 설정으로 최대 성능을 끌어내세요.
+
+**기본 최적화 설정:**
+
+```typescript
+// server.ts
+Bun.serve({
+  port: 3000,
+
+  // ✅ 개발 환경에서만 에러 스택 노출
+  development: process.env.NODE_ENV !== "production",
+
+  // ✅ 정적 파일 직접 서빙 (미들웨어 우회)
+  static: {
+    "/public/*": "./public/",
+  },
+
+  fetch(req) {
+    // Mandu 라우터 처리
+    return handleRequest(req);
+  },
+
+  // ✅ 에러 핸들링
+  error(error) {
+    return new Response(`Error: ${error.message}`, { status: 500 });
+  },
+});
+```
+
+## 정적 파일 최적화
+
+```typescript
+Bun.serve({
+  fetch(req) {
+    const url = new URL(req.url);
+
+    // ✅ 정적 파일은 Bun.file()로 직접 서빙
+    if (url.pathname.startsWith("/assets/")) {
+      const filePath = `./public${url.pathname}`;
+      const file = Bun.file(filePath);
+
+      return new Response(file, {
+        headers: {
+          // 캐시 헤더 설정
+          "Cache-Control": "public, max-age=31536000, immutable",
+        },
+      });
+    }
+
+    return handleRequest(req);
+  },
+});
+```
+
+## 스트리밍 응답
+
+대용량 데이터는 스트리밍으로 메모리 효율 향상:
+
+```typescript
+export default Mandu.filling()
+  .get(async (ctx) => {
+    // ✅ 스트리밍 응답
+    const stream = new ReadableStream({
+      async start(controller) {
+        const cursor = db.query("SELECT * FROM large_table");
+
+        for await (const row of cursor) {
+          controller.enqueue(JSON.stringify(row) + "\n");
+        }
+
+        controller.close();
+      },
+    });
+
+    return new Response(stream, {
+      headers: { "Content-Type": "application/x-ndjson" },
+    });
+  });
+```
+
+## TLS 설정 (HTTPS)
+
+```typescript
+Bun.serve({
+  port: 443,
+
+  // ✅ TLS 인증서 설정
+  tls: {
+    cert: Bun.file("./cert.pem"),
+    key: Bun.file("./key.pem"),
+  },
+
+  fetch(req) {
+    return handleRequest(req);
+  },
+});
+```
+
+## 동시 연결 처리
+
+Bun은 기본적으로 높은 동시성을 지원하지만, 리소스 제한이 있는 환경에서는:
+
+```typescript
+Bun.serve({
+  // ✅ 최대 동시 연결 제한 (메모리 보호)
+  maxRequestBodySize: 1024 * 1024 * 10, // 10MB
+
+  fetch(req) {
+    return handleRequest(req);
+  },
+});
+```
+
+Reference: [Bun.serve() documentation](https://bun.sh/docs/api/http)

package/src/resources/skills/mandu-performance/rules/perf-bundle-imports.md

@@ -0,0 +1,80 @@
+---
+title: Import Directly, Avoid Barrel Files
+impact: CRITICAL
+impactDescription: 15-70% faster dev boot, 40% faster cold starts
+tags: performance, bundle, imports, tree-shaking
+---
+
+## Import Directly, Avoid Barrel Files
+
+**Impact: CRITICAL (15-70% faster dev boot, 40% faster cold starts)**
+
+배럴 파일(index.ts에서 re-export)을 통하지 않고 소스 파일에서 직접 import하세요. 대형 라이브러리의 배럴 파일은 수천 개의 모듈을 로드합니다.
+
+**Incorrect (전체 라이브러리 로드):**
+
+```typescript
+// app/page.tsx
+import { Check, X, Menu } from "lucide-react";
+// ❌ 1,583개 모듈 로드, 개발 시 ~2.8초 추가
+// 런타임 비용: 콜드 스타트마다 200-800ms
+
+import { Button, TextField } from "@mui/material";
+// ❌ 2,225개 모듈 로드, 개발 시 ~4.2초 추가
+```
+
+**Correct (필요한 것만 로드):**
+
+```typescript
+// app/page.tsx
+import Check from "lucide-react/dist/esm/icons/check";
+import X from "lucide-react/dist/esm/icons/x";
+import Menu from "lucide-react/dist/esm/icons/menu";
+// ✅ 3개 모듈만 로드 (~2KB vs ~1MB)
+
+import Button from "@mui/material/Button";
+import TextField from "@mui/material/TextField";
+// ✅ 필요한 것만 로드
+```
+
+## Mandu 프로젝트에서의 적용
+
+```typescript
+// ❌ 잘못된 방식
+import { useAuth, useUser, usePermissions } from "@/features/auth";
+
+// ✅ 올바른 방식
+import { useAuth } from "@/features/auth/hooks/useAuth";
+import { useUser } from "@/features/auth/hooks/useUser";
+```
+
+## 자체 배럴 파일 피하기
+
+```typescript
+// ❌ features/auth/index.ts (배럴 파일)
+export * from "./hooks/useAuth";
+export * from "./hooks/useUser";
+export * from "./components/LoginForm";
+export * from "./utils/validators";
+// 모든 것을 로드하게 만듦
+
+// ✅ 직접 import
+import { useAuth } from "@/features/auth/hooks/useAuth";
+```
+
+## 영향받는 일반적인 라이브러리
+
+- `lucide-react`, `react-icons`
+- `@mui/material`, `@mui/icons-material`
+- `@radix-ui/react-*`
+- `lodash`, `date-fns`
+- `@headlessui/react`
+
+## 번들 분석
+
+```bash
+# 번들 크기 분석
+bunx vite-bundle-visualizer
+```
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)

package/src/resources/skills/mandu-performance/rules/perf-bundle-island-lazy.md

@@ -0,0 +1,145 @@
+---
+title: Lazy Load Islands with Dynamic Import
+impact: CRITICAL
+impactDescription: 40-60% smaller initial bundle
+tags: performance, bundle, island, lazy, dynamic-import
+---
+
+## Lazy Load Islands with Dynamic Import
+
+**Impact: CRITICAL (40-60% smaller initial bundle)**
+
+무거운 Island 컴포넌트는 동적 import로 lazy loading하세요. 초기 번들에서 제외되어 페이지 로드가 빨라집니다.
+
+**Incorrect (즉시 로드):**
+
+```tsx
+// app/dashboard/page.tsx
+import HeavyChart from "./client";  // ❌ 200KB 차트 라이브러리 즉시 로드
+import DataTable from "./table.client";  // ❌ 150KB 테이블 라이브러리 즉시 로드
+
+export default function DashboardPage() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <HeavyChart data={chartData} />
+      <DataTable rows={tableData} />
+    </div>
+  );
+}
+```
+
+**Correct (lazy loading):**
+
+```tsx
+// app/dashboard/page.tsx
+import { lazy, Suspense } from "react";
+
+// ✅ 동적 import로 코드 스플리팅
+const HeavyChart = lazy(() => import("./client"));
+const DataTable = lazy(() => import("./table.client"));
+
+export default function DashboardPage() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      <Suspense fallback={<ChartSkeleton />}>
+        <HeavyChart data={chartData} />
+      </Suspense>
+
+      <Suspense fallback={<TableSkeleton />}>
+        <DataTable rows={tableData} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+## 조건부 로딩
+
+사용자 액션 시에만 로드:
+
+```tsx
+"use client";
+
+import { lazy, Suspense, useState } from "react";
+
+const HeavyEditor = lazy(() => import("./editor.client"));
+
+export default function EditorToggle() {
+  const [showEditor, setShowEditor] = useState(false);
+
+  return (
+    <div>
+      <button onClick={() => setShowEditor(true)}>
+        Edit
+      </button>
+
+      {showEditor && (
+        <Suspense fallback={<p>Loading editor...</p>}>
+          <HeavyEditor />
+        </Suspense>
+      )}
+    </div>
+  );
+}
+```
+
+## Preload on Hover
+
+호버 시 미리 로드하여 체감 속도 향상:
+
+```tsx
+"use client";
+
+import { lazy, Suspense, useState } from "react";
+
+// 프리로드 함수 분리
+const editorImport = () => import("./editor.client");
+const HeavyEditor = lazy(editorImport);
+
+export default function EditorToggle() {
+  const [showEditor, setShowEditor] = useState(false);
+
+  const handleMouseEnter = () => {
+    // ✅ 호버 시 프리로드 시작
+    editorImport();
+  };
+
+  return (
+    <div>
+      <button
+        onMouseEnter={handleMouseEnter}
+        onClick={() => setShowEditor(true)}
+      >
+        Edit
+      </button>
+
+      {showEditor && (
+        <Suspense fallback={<p>Loading...</p>}>
+          <HeavyEditor />
+        </Suspense>
+      )}
+    </div>
+  );
+}
+```
+
+## Island Priority와 함께 사용
+
+```tsx
+// 뷰포트 진입 시 로드 (기본값)
+<Island priority="visible">
+  <Suspense fallback={<Skeleton />}>
+    <LazyComponent />
+  </Suspense>
+</Island>
+
+// 브라우저 유휴 시 로드
+<Island priority="idle">
+  <Suspense fallback={<Skeleton />}>
+    <LazyAnalytics />
+  </Suspense>
+</Island>
+```

package/src/resources/skills/mandu-performance/rules/perf-cache-react.md

@@ -0,0 +1,98 @@
+---
+title: Use React.cache() for Request Deduplication
+impact: HIGH
+impactDescription: Eliminates duplicate queries within request
+tags: performance, cache, react-cache, deduplication, slot
+---
+
+## Use React.cache() for Request Deduplication
+
+**Impact: HIGH (Eliminates duplicate queries within request)**
+
+`React.cache()`를 사용하여 단일 요청 내에서 중복 쿼리를 제거하세요. 인증 확인과 데이터베이스 쿼리에 특히 효과적입니다.
+
+**사용법:**
+
+```typescript
+// lib/auth.ts
+import { cache } from "react";
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth();
+  if (!session?.user?.id) return null;
+
+  return await db.user.findUnique({
+    where: { id: session.user.id },
+  });
+});
+```
+
+단일 요청 내에서 `getCurrentUser()`를 여러 번 호출해도 쿼리는 한 번만 실행됩니다.
+
+**Incorrect (항상 캐시 미스):**
+
+```typescript
+// ❌ 인라인 객체는 매번 새 참조 생성
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } });
+});
+
+// 각 호출이 새 객체, 캐시 미스
+getUser({ uid: 1 });
+getUser({ uid: 1 });  // 캐시 미스, 쿼리 다시 실행
+```
+
+**Correct (캐시 히트):**
+
+```typescript
+// ✅ 프리미티브 인자는 값 동등성 사용
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } });
+});
+
+getUser(1);
+getUser(1);  // ✅ 캐시 히트, 캐시된 결과 반환
+```
+
+## Mandu Slot에서의 활용
+
+```typescript
+// lib/data.ts
+import { cache } from "react";
+
+export const getProductWithCategory = cache(async (productId: string) => {
+  const product = await db.product.findUnique({
+    where: { id: productId },
+    include: { category: true },
+  });
+  return product;
+});
+
+// spec/slots/product.slot.ts
+import { Mandu } from "@mandujs/core";
+import { getProductWithCategory } from "@/lib/data";
+
+export default Mandu.filling()
+  .get(async (ctx) => {
+    const productId = ctx.params.id;
+
+    // 여러 컴포넌트에서 호출해도 한 번만 실행
+    const product = await getProductWithCategory(productId);
+
+    return ctx.ok({ product });
+  });
+```
+
+## React.cache() 적합한 사용 사례
+
+- 데이터베이스 쿼리 (Prisma, Drizzle 등)
+- 무거운 계산
+- 인증 확인
+- 파일 시스템 작업
+- fetch가 아닌 모든 비동기 작업
+
+## 주의사항
+
+`React.cache()`는 요청 단위로 캐시됩니다. 요청 간 캐싱이 필요하면 LRU 캐시를 사용하세요.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)