@mandujs/skills 1.0.0

package/skills/mandu-deploy/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: mandu-deploy
+description: "프로덕션 배포 파이프라인. Docker/CI-CD/nginx"
+disable-model-invocation: true
+---
+
+# Mandu Deploy
+
+프로덕션 배포 파이프라인 가이드.
+Build -> Test -> Deploy 체크리스트와 Docker/CI-CD/nginx 설정을 다룹니다.
+
+## Build -> Test -> Deploy Checklist
+
+### 1. Pre-Deploy Checks
+
+```bash
+# Architecture validation
+bunx mandu guard arch --ci
+
+# TypeScript check
+bunx tsc --noEmit
+
+# Run tests
+bun test
+
+# Production build
+bun run build
+```
+
+### 2. Dockerfile
+
+```dockerfile
+FROM oven/bun:1.2-alpine AS base
+WORKDIR /app
+
+# Install dependencies
+FROM base AS deps
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile --production
+
+# Build
+FROM base AS build
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile
+COPY . .
+RUN bun run build
+
+# Production
+FROM base AS production
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=build /app/.mandu ./.mandu
+COPY --from=build /app/app ./app
+COPY --from=build /app/src ./src
+COPY --from=build /app/spec ./spec
+COPY --from=build /app/package.json ./
+
+ENV NODE_ENV=production
+ENV PORT=3333
+EXPOSE 3333
+
+CMD ["bun", "run", "start"]
+```
+
+### 3. docker-compose.yml
+
+```yaml
+version: "3.8"
+services:
+  app:
+    build: .
+    ports:
+      - "3333:3333"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL=${DATABASE_URL}
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3333/api/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+
+### 4. GitHub Actions CI/CD
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - run: bun install --frozen-lockfile
+      - run: bunx mandu guard arch --ci
+      - run: bun test
+      - run: bun run build
+
+      - name: Deploy
+        run: |
+          # docker build & push, or platform-specific deploy
+          docker build -t myapp:${{ github.sha }} .
+          docker push myapp:${{ github.sha }}
+```
+
+### 5. nginx Reverse Proxy
+
+```nginx
+upstream mandu_app {
+    server 127.0.0.1:3333;
+    keepalive 32;
+}
+
+server {
+    listen 80;
+    server_name example.com;
+
+    # Static assets (long cache)
+    location /.mandu/client/ {
+        proxy_pass http://mandu_app;
+        proxy_cache_valid 200 30d;
+        add_header Cache-Control "public, max-age=2592000, immutable";
+    }
+
+    # API routes
+    location /api/ {
+        proxy_pass http://mandu_app;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # All other routes (SSR)
+    location / {
+        proxy_pass http://mandu_app;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+## Environment Variables
+
+```bash
+# .env.production
+NODE_ENV=production
+PORT=3333
+DATABASE_URL=postgresql://user:pass@host:5432/db
+```
+
+IMPORTANT: `.env` 파일은 절대 git에 커밋하지 않기. `.gitignore`에 추가 확인.
+
+## Production Optimizations
+
+| Area | Action |
+|------|--------|
+| Build | `bun run build` (minification, tree-shaking) |
+| CSS | Tailwind purge (자동) |
+| Islands | `"visible"` or `"idle"` priority (not `"immediate"`) |
+| Static | nginx에서 `.mandu/client/` 장기 캐시 |
+| Health | `/api/health` endpoint 필수 |

package/skills/mandu-explain/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: mandu-explain
+description: |
+  Mandu 개념 설명. Island/Filling/Guard/Contract/Slot/SSR/ISR 등 '뭐야'/'어떻게' 시 자동 호출
+---
+
+# Mandu Explain
+
+Mandu 프레임워크의 핵심 개념 18가지를 설명하는 레퍼런스.
+
+## Core Concepts
+
+### 1. Island Architecture
+페이지의 대부분은 정적 HTML로 서버 렌더링하고, 인터랙티브한 부분만 JavaScript를 로드하는 패턴.
+```
+[Static HTML] [Static HTML] [Island: JS] [Static HTML]
+```
+장점: 초기 로딩 속도, 작은 번들 크기, SEO 친화적.
+
+### 2. Filling (Mandu.filling())
+API 핸들러를 체이닝으로 작성하는 API. Express의 미들웨어와 유사하지만 타입 안전.
+```typescript
+Mandu.filling().guard(authCheck).get(handler).post(handler)
+```
+
+### 3. Guard
+아키텍처 규칙을 코드 레벨에서 강제하는 시스템. import 방향, 파일 위치, 금지된 의존성을 검사.
+```bash
+bunx mandu guard arch  # 전체 프로젝트 검사
+```
+
+### 4. Contract
+Zod 스키마 기반 API 계약. 클라이언트-서버 간 타입을 공유하고 런타임 validation을 수행.
+```typescript
+// src/shared/contracts/user.contract.ts
+export const CreateUser = z.object({ name: z.string(), email: z.string().email() });
+```
+
+### 5. Slot
+서버에서 렌더링 전에 실행되는 데이터 로더. `spec/slots/*.slot.ts`에 위치.
+```typescript
+// spec/slots/dashboard.slot.ts - page 렌더링 전에 데이터를 fetch
+export default Mandu.filling().get(async (ctx) => ctx.ok({ stats: await getStats() }));
+```
+
+### 6. SSR (Server-Side Rendering)
+모든 페이지를 서버에서 HTML로 렌더링. `app/layout.tsx`에서 `<html>/<head>/<body>` 태그 불필요 (자동 생성).
+
+### 7. Streaming SSR
+서버에서 HTML을 청크 단위로 스트리밍. 첫 바이트 시간(TTFB)을 단축.
+
+### 8. Hydration
+서버 렌더링된 HTML에 JavaScript 인터랙티비티를 부착하는 과정.
+Priority: `immediate` > `visible` > `idle` > `interaction`
+
+### 9. FS Routes
+파일 시스템 기반 라우팅. `app/` 폴더 구조가 URL이 됨.
+- `app/page.tsx` -> `/`
+- `app/users/[id]/page.tsx` -> `/users/:id`
+
+### 10. Layout
+페이지를 감싸는 공통 UI 래퍼. `<html>/<head>/<body>` 사용 금지.
+```tsx
+export default function Layout({ children }) {
+  return <div className="min-h-screen">{children}</div>;
+}
+```
+
+### 11. Route Groups
+`(name)` 괄호로 감싼 폴더는 URL에 영향 없이 라우트를 그룹화.
+```
+app/(auth)/login/page.tsx -> /login
+app/(auth)/signup/page.tsx -> /signup
+```
+
+### 12. MCP (Model Context Protocol)
+AI 에이전트가 프레임워크 도구를 직접 호출하는 인터페이스.
+`@mandujs/mcp`가 50+ 도구를 제공: negotiate, generate, guard, brain 등.
+
+### 13. ATE (Automated Test Engine)
+API 엔드포인트의 테스트를 자동 생성하는 엔진.
+
+### 14. Brain
+코드 분석 및 진단 시스템. 프로젝트 구조, 의존성, 성능 이슈를 분석.
+
+### 15. Presets
+Guard가 사용하는 아키텍처 템플릿: `mandu`, `fsd`, `clean`, `hexagonal`, `atomic`, `cqrs`
+
+### 16. Lockfile (.mandu/lockfile.json)
+프로젝트 설정의 무결성을 보장하는 해시 기반 잠금 파일.
+
+### 17. useServerData
+Island에서 서버 Slot이 주입한 데이터를 읽는 클라이언트 훅.
+```typescript
+const data = useServerData<UserData>("user-profile");
+```
+
+### 18. useIslandEvent
+Island 간 통신을 위한 이벤트 시스템.
+```typescript
+const { emit, on } = useIslandEvent();
+emit("cart:updated", { count: 5 });
+```
+
+## Architecture Layers
+
+```
+app/           UI (pages, layouts, islands)
+src/client/    Client-side code
+src/server/    Server-side business logic
+src/shared/    Shared types, contracts, utils
+spec/          Slots, tests
+```
+
+## Key Import Rules
+
+| From | Import |
+|------|--------|
+| Island files | `@mandujs/core/client` |
+| Server files | `@mandujs/core` |
+| Shared code | `@/shared/*` |

package/skills/mandu-fs-routes/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: mandu-fs-routes
+description: |
+  파일 시스템 라우팅 규칙. layout에 html/head/body 금지.
+  app/ 폴더, page.tsx, route.ts, layout.tsx, [id] 작업 시 자동 호출.
+---
+
+# Mandu FS Routes
+
+파일 시스템 기반 라우팅. `app/` 폴더의 파일 구조가 URL이 됩니다.
+
+## File Naming Conventions
+
+| File | Purpose | Export |
+|------|---------|--------|
+| `page.tsx` | Page component | `default` function component |
+| `route.ts` | API handler | `default` Mandu.filling() chain |
+| `layout.tsx` | Shared layout | `default` function with `children` prop |
+| `loading.tsx` | Loading UI | `default` function component |
+| `error.tsx` | Error UI | `default` function component |
+
+## URL Mapping
+
+| File Path | URL |
+|-----------|-----|
+| `app/page.tsx` | `/` |
+| `app/about/page.tsx` | `/about` |
+| `app/blog/[slug]/page.tsx` | `/blog/:slug` |
+| `app/users/[id]/page.tsx` | `/users/:id` |
+| `app/docs/[...path]/page.tsx` | `/docs/*` (catch-all) |
+| `app/(auth)/login/page.tsx` | `/login` (grouped) |
+| `app/api/users/route.ts` | `/api/users` |
+| `app/api/users/[id]/route.ts` | `/api/users/:id` |
+
+## Layout Rules (CRITICAL)
+
+Layout MUST NOT include `<html>`, `<head>`, or `<body>` tags.
+Mandu SSR generates these automatically.
+
+```tsx
+// app/layout.tsx - CORRECT
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="min-h-screen bg-background font-sans antialiased">
+      {children}
+    </div>
+  );
+}
+```
+
+```tsx
+// app/layout.tsx - WRONG (causes double-wrapping)
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>          // <-- DO NOT include
+      <head />      // <-- DO NOT include
+      <body>        // <-- DO NOT include
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+Nested layouts wrap child pages:
+```
+app/layout.tsx              -> wraps ALL pages
+app/dashboard/layout.tsx    -> wraps /dashboard/* pages
+```
+
+## Page Components
+
+```tsx
+// app/dashboard/page.tsx
+export default function DashboardPage() {
+  return (
+    <main>
+      <h1>Dashboard</h1>
+    </main>
+  );
+}
+```
+
+Pages are server-rendered by default. No `"use client"` needed unless using Islands.
+
+## API Routes
+
+```typescript
+// app/api/users/route.ts
+import { Mandu } from "@mandujs/core";
+
+export default Mandu.filling()
+  .get((ctx) => ctx.ok({ users: [] }))
+  .post(async (ctx) => {
+    const body = await ctx.body<{ name: string }>();
+    return ctx.created({ user: body });
+  });
+```
+
+API routes use `.ts` extension (NOT `.tsx`).
+
+## Dynamic Routes
+
+```tsx
+// app/users/[id]/page.tsx
+export default function UserPage({ params }: { params: { id: string } }) {
+  return <h1>User {params.id}</h1>;
+}
+
+// app/docs/[...path]/page.tsx
+export default function DocsPage({ params }: { params: { path: string[] } }) {
+  return <h1>Doc: {params.path.join("/")}</h1>;
+}
+```
+
+## Route Groups
+
+Parenthesized folders create logical groups without affecting the URL:
+
+```
+app/(marketing)/about/page.tsx   -> /about
+app/(marketing)/pricing/page.tsx -> /pricing
+app/(app)/dashboard/page.tsx     -> /dashboard
+```
+
+## Common Mistakes
+
+- Adding `<html>/<head>/<body>` in layout.tsx (SSR does this)
+- Using `route.tsx` instead of `route.ts` for API handlers
+- Forgetting to export default from page/layout files
+- Mixing page.tsx and route.ts in the same directory

package/skills/mandu-guard-guide/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: mandu-guard-guide
+description: |
+  Guard 아키텍처 가이드. 위반 수정/프리셋 선택/레이어 규칙. guard violation 시 자동 호출
+---
+
+# Mandu Guard Guide
+
+Mandu Guard 아키텍처 강제 시스템의 상세 가이드.
+6개 프리셋, 위반 유형별 수정 방법, 레이어 규칙을 다룹니다.
+
+## 6 Presets
+
+### mandu (default)
+FSD + Clean Architecture 하이브리드. 프론트엔드와 백엔드 모두 커버.
+```typescript
+// mandu.config.ts
+export default { guard: { preset: "mandu" } };
+```
+
+### fsd (Feature-Sliced Design)
+프론트엔드 전용. 7계층 레이어 구조.
+```
+app > pages > widgets > features > entities > shared
+```
+
+### clean (Clean Architecture)
+백엔드 전용. 의존성 역전 원칙.
+```
+api > application > domain > infra > core > shared
+```
+
+### hexagonal (Ports & Adapters)
+포트와 어댑터 패턴. domain이 중심, adapters가 외부 의존성 처리.
+```
+adapters > ports > application > domain
+```
+
+### atomic (Atomic Design)
+UI 컴포넌트 전용. atoms -> molecules -> organisms -> templates -> pages.
+
+### cqrs (Command Query Responsibility Segregation)
+명령과 조회를 분리. command, query, event, dto 전용 구조.
+
+## Violation Types and Fixes
+
+### LAYER_VIOLATION (error)
+상위 레이어가 하위 레이어를 import하는 것만 허용.
+
+```typescript
+// BAD: shared가 features를 import (하위 -> 상위)
+// src/shared/utils/helper.ts
+import { useAuth } from "@/features/auth"; // VIOLATION
+
+// FIX: 의존 방향 반전, 또는 shared에 인터페이스 정의
+// src/shared/types/auth.ts
+export interface AuthContext { userId: string; }
+```
+
+### FORBIDDEN_IMPORT (error)
+클라이언트 코드에서 서버 전용 모듈 import 금지.
+
+```typescript
+// BAD: island에서 fs import
+// app/editor.island.tsx
+import fs from "fs"; // VIOLATION
+
+// FIX: 서버 로직은 slot으로 분리
+// spec/slots/editor.slot.ts
+import fs from "fs"; // OK (server-only)
+```
+
+### WRONG_SLOT_LOCATION (warning)
+Slot 파일이 잘못된 위치에 있음.
+
+```
+BAD:  src/server/slots/user.slot.ts
+FIX:  spec/slots/user.slot.ts
+```
+
+### GENERATED_DIRECT_EDIT (error)
+자동 생성된 파일을 직접 수정하면 안 됨.
+
+```
+BAD:  .mandu/generated/server/routes.ts 직접 편집
+FIX:  소스 파일을 수정하고 regenerate
+```
+
+### CONTRACT_MISSING (warning)
+API route에 대응하는 contract가 없음.
+
+```
+Missing: src/shared/contracts/user.contract.ts
+For:     app/api/users/route.ts
+FIX:     contract 파일 생성
+```
+
+### SLOT_NAMING (warning)
+Slot 파일명이 규칙에 맞지 않음.
+
+```
+BAD:  spec/slots/userData.ts
+FIX:  spec/slots/user-data.slot.ts
+```
+
+## CLI Commands
+
+```bash
+# 전체 아키텍처 검사
+bunx mandu guard arch
+
+# 특정 프리셋으로 검사
+bunx mandu guard arch --preset fsd
+
+# CI 모드 (위반 시 exit 1)
+bunx mandu guard arch --ci
+
+# Watch 모드
+bunx mandu guard arch --watch
+
+# 단일 파일 검사
+bunx mandu guard check-file src/client/features/auth.ts
+```
+
+## Configuration
+
+```typescript
+// mandu.config.ts
+export default {
+  guard: {
+    preset: "mandu",
+    rules: {
+      LAYER_VIOLATION: "error",     // "error" | "warning" | "off"
+      FORBIDDEN_IMPORT: "error",
+      WRONG_SLOT_LOCATION: "warning",
+      CONTRACT_MISSING: "off",
+      GENERATED_DIRECT_EDIT: "error",
+      SLOT_NAMING: "warning",
+    }
+  }
+};
+```
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `mandu_guard` | Run architecture check |
+| `mandu_guard_heal` | Auto-fix violations |
+| `mandu_negotiate` | Analyze with preset awareness |

package/skills/mandu-hydration/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: mandu-hydration
+description: |
+  Island import 규칙. 반드시 @mandujs/core/client에서 import.
+  "use client", .island.tsx, useState, hydration 작업 시 자동 호출.
+---
+
+# Mandu Island Hydration
+
+Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티브하게 만드는 기술입니다.
+
+## Import Rule (CRITICAL)
+
+Client islands MUST import from `@mandujs/core/client`, NOT `@mandujs/core`.
+The main module includes server-side dependencies that break client bundles.
+
+```typescript
+// CORRECT
+import { island } from "@mandujs/core/client";
+import { useServerData, useHydrated, useIslandEvent } from "@mandujs/core/client";
+
+// WRONG - will cause build errors or bloated bundles
+import { island } from "@mandujs/core";
+```
+
+## Island File Conventions
+
+| File | Purpose |
+|------|---------|
+| `*.island.tsx` | Island component (auto-detected for hydration) |
+| `*.client.tsx` | Client-only logic file |
+| `*.slot.ts` / `*.slot.tsx` | Server-side data loader |
+
+All island files MUST have `"use client"` directive at the very top.
+
+## island() API
+
+### Declarative Style (simple)
+
+```tsx
+// app/counter.island.tsx
+"use client";
+
+import { island } from "@mandujs/core/client";
+import { useState } from "react";
+
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+
+export default island("visible", Counter);
+```
+
+### Client Island with Setup (advanced)
+
+```tsx
+// app/chat.island.tsx
+"use client";
+
+import { island } from "@mandujs/core/client";
+import { useState } from "react";
+
+export default island<ServerData>({
+  setup(data) {
+    const [messages, setMessages] = useState(data.initialMessages);
+    return { messages, setMessages };
+  },
+  render({ messages, setMessages }) {
+    return <div>{messages.map(m => <p key={m.id}>{m.text}</p>)}</div>;
+  }
+});
+```
+
+## Hydration Priorities
+
+| Priority | When loaded | Use case |
+|----------|------------|----------|
+| `"immediate"` | Page load | Critical interactions (nav, auth) |
+| `"visible"` | In viewport | Default - most components |
+| `"idle"` | Browser idle | Below-fold content |
+| `"interaction"` | User interacts | Heavy widgets (editor, map) |
+
+```tsx
+island("immediate", NavigationIsland);   // Load right away
+island("visible", CommentSection);       // Load when scrolled into view
+island("idle", AnalyticsDashboard);      // Load when browser is idle
+island("interaction", RichTextEditor);   // Load on first click/focus
+```
+
+## Client Hooks
+
+```typescript
+import { useServerData, useHydrated, useIslandEvent } from "@mandujs/core/client";
+
+// Access data from server slot
+const data = useServerData<UserData>("user", defaultValue);
+
+// Check if component has hydrated (SSR-safe code branching)
+const isHydrated = useHydrated();
+
+// Cross-island communication
+const { emit, on } = useIslandEvent();
+emit("cart:updated", { items: newItems });
+on("cart:updated", (data) => setCartItems(data.items));
+```
+
+## Server Data Flow
+
+```typescript
+// spec/slots/user-profile.slot.ts (server)
+import { Mandu } from "@mandujs/core";
+export default Mandu.filling()
+  .get(async (ctx) => {
+    const user = await db.getUser(ctx.params.id);
+    return ctx.ok({ user }); // Data available to Islands
+  });
+
+// app/user-profile.island.tsx (client)
+"use client";
+import { useServerData } from "@mandujs/core/client";
+export default function UserProfile() {
+  const { user } = useServerData("user-profile");
+  return <div>{user.name}</div>;
+}
+```
+
+## Common Mistakes
+
+- Importing from `@mandujs/core` instead of `@mandujs/core/client` in Islands
+- Forgetting `"use client"` directive in island files
+- Using `useState`/`useEffect` in server components (non-island files)
+- Setting all Islands to `"immediate"` priority (defeats partial hydration)
+- Putting heavy server imports in `.island.tsx` files (increases bundle size)