@mandujs/mcp 0.9.19 → 0.9.21

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

@@ -0,0 +1,36 @@
+# 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. Layer Rules (guard-layer)
+
+**Impact:** CRITICAL
+**Description:** 레이어 의존성 방향 규칙. 상위→하위만 허용, 역방향 import 금지. 아키텍처 무결성의 핵심입니다.
+
+## 2. Presets (guard-preset)
+
+**Impact:** HIGH
+**Description:** mandu, fsd, clean, hexagonal 프리셋 선택. 프로젝트 유형에 맞는 아키텍처 템플릿입니다.
+
+## 3. Validation (guard-validate)
+
+**Impact:** HIGH
+**Description:** import 경로, 파일 위치, 네이밍 검증. 실시간 위반 감지와 리포팅입니다.
+
+## 4. Configuration (guard-config)
+
+**Impact:** MEDIUM
+**Description:** 규칙 severity 설정, ignore 패턴. 프로젝트 특성에 맞게 가드를 커스터마이징합니다.
+
+## 5. CI Integration (guard-ci)
+
+**Impact:** MEDIUM
+**Description:** --ci 플래그, exit code, 리포트 생성. 자동화된 아키텍처 검증 파이프라인입니다.
+
+## 6. Auto Fix (guard-fix)
+
+**Impact:** LOW
+**Description:** --auto-correct 옵션. 일부 위반의 자동 수정 기능입니다.

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

@@ -0,0 +1,82 @@
+# Rule Template
+
+Use this template when creating new rules for mandu-guard.
+
+---
+
+```markdown
+---
+title: Rule Title Here
+impact: CRITICAL | HIGH | MEDIUM | LOW
+impactDescription: 영향 설명
+tags: guard, tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: {LEVEL} ({impactDescription})**
+
+규칙의 목적과 중요성을 설명합니다.
+
+**Incorrect (위반 예시):**
+
+\`\`\`typescript
+// ❌ entities → features (역방향 의존)
+// src/entities/user/index.ts
+import { useAuth } from "@/features/auth";  // VIOLATION!
+
+export function User() {
+  const { isLoggedIn } = useAuth();
+}
+\`\`\`
+
+**Correct (올바른 방향):**
+
+\`\`\`typescript
+// ✅ features → entities (순방향 의존)
+// src/features/auth/index.ts
+import { User } from "@/entities/user";
+
+export function useAuth() {
+  const user = getCurrentUser();
+  return { user, isLoggedIn: !!user };
+}
+\`\`\`
+
+## CLI Command
+
+\`\`\`bash
+bunx mandu guard arch --ci
+\`\`\`
+
+Reference: [관련 문서 링크](https://example.com)
+```
+
+---
+
+## Naming Convention
+
+- 파일명: `{section}-{rule-name}.md`
+- 예시: `guard-layer-direction.md`, `guard-preset-mandu.md`
+
+## Layer Hierarchy Quick Reference
+
+### Frontend (FSD)
+```
+app → pages → widgets → features → entities → shared
+```
+
+### Backend (Clean)
+```
+api → application → domain → infra → core → shared
+```
+
+## Rule IDs Quick Reference
+
+| Rule ID | Description |
+|---------|-------------|
+| `LAYER_VIOLATION` | 레이어 의존성 위반 |
+| `GENERATED_DIRECT_EDIT` | generated 파일 직접 수정 |
+| `WRONG_SLOT_LOCATION` | 잘못된 slot 파일 위치 |
+| `SLOT_NAMING` | slot 파일 이름 규칙 위반 |
+| `FORBIDDEN_IMPORT` | 금지된 import |

package/src/resources/skills/mandu-guard/rules/guard-config-rules.md

@@ -0,0 +1,100 @@
+---
+title: Configure Rule Severity Levels
+impact: MEDIUM
+impactDescription: Customize guard behavior
+tags: guard, config, rules
+---
+
+## Configure Rule Severity Levels
+
+Set severity levels for each guard rule based on your project needs.
+
+## Severity Levels
+
+| Level | Behavior | Use Case |
+|-------|----------|----------|
+| `error` | Fails check, blocks CI | Critical violations |
+| `warn` | Reports issue, continues | Gradual migration |
+| `off` | Ignores rule | Not applicable to project |
+
+## Configuration File
+
+```typescript
+// mandu.config.ts
+
+export default {
+  guard: {
+    preset: "mandu",
+    rules: {
+      // Core rules
+      "LAYER_VIOLATION": "error",      // Always enforce layers
+      "GENERATED_DIRECT_EDIT": "error", // Protect generated files
+
+      // Naming rules
+      "SLOT_NAMING": "warn",           // Warn during migration
+      "WRONG_SLOT_LOCATION": "error",
+
+      // Security rules
+      "FORBIDDEN_IMPORT": "error",     // Block dangerous imports
+    },
+  },
+};
+```
+
+## Available Rules
+
+| Rule ID | Default | Description |
+|---------|---------|-------------|
+| `LAYER_VIOLATION` | error | Layer dependency violation |
+| `GENERATED_DIRECT_EDIT` | error | Direct edit of generated files |
+| `WRONG_SLOT_LOCATION` | error | Slot file in wrong directory |
+| `SLOT_NAMING` | error | Incorrect slot file naming |
+| `FORBIDDEN_IMPORT` | warn | Importing fs, child_process, etc. in browser code |
+| `CIRCULAR_DEPENDENCY` | warn | Circular import detected |
+| `DEEP_IMPORT` | warn | Importing from nested paths instead of index |
+
+## Ignoring Paths
+
+```typescript
+export default {
+  guard: {
+    ignore: [
+      "**/test/**",       // Test files
+      "**/*.test.ts",     // Test files
+      "**/*.spec.ts",     // Spec files
+      "**/mocks/**",      // Mock files
+      "scripts/**",       // Build scripts
+    ],
+  },
+};
+```
+
+## Per-File Override
+
+```typescript
+// src/features/legacy/index.ts
+
+// @guard-disable LAYER_VIOLATION
+import { oldHelper } from "@/entities/legacy";  // Allowed temporarily
+// @guard-enable LAYER_VIOLATION
+```
+
+## Gradual Migration
+
+```typescript
+// Start with warnings for legacy code
+{
+  rules: {
+    "LAYER_VIOLATION": "warn",  // Start with warn
+    "SLOT_NAMING": "off",       // Fix later
+  }
+}
+
+// After migration, enforce strictly
+{
+  rules: {
+    "LAYER_VIOLATION": "error", // Now enforce
+    "SLOT_NAMING": "error",     // Now enforce
+  }
+}
+```

package/src/resources/skills/mandu-guard/rules/guard-layer-direction.md

@@ -0,0 +1,76 @@
+---
+title: Dependencies Must Flow Downward Only
+impact: CRITICAL
+impactDescription: Core architecture principle
+tags: guard, layer, dependency
+---
+
+## Dependencies Must Flow Downward Only
+
+In layered architecture, imports must always flow from higher to lower layers.
+
+**Incorrect (upward dependency):**
+
+```typescript
+// ❌ entities/user/index.ts importing from features (higher layer)
+import { useAuth } from "@/features/auth";
+
+export function User() {
+  const { isLoggedIn } = useAuth();  // VIOLATION!
+  // ...
+}
+```
+
+**Correct (downward dependency):**
+
+```typescript
+// ✅ features/auth/index.ts importing from entities (lower layer)
+import { User } from "@/entities/user";
+
+export function useAuth() {
+  const user = getCurrentUser();  // Uses entity
+  return { user, isLoggedIn: !!user };
+}
+```
+
+## Layer Hierarchy (Mandu Preset)
+
+### Frontend Layers (top to bottom)
+
+```
+app         → Can import: pages, widgets, features, entities, shared
+pages       → Can import: widgets, features, entities, shared
+widgets     → Can import: features, entities, shared
+features    → Can import: entities, shared
+entities    → Can import: shared
+shared      → Can import: (nothing above)
+```
+
+### Backend Layers (top to bottom)
+
+```
+api         → Can import: application, domain, infra, core, shared
+application → Can import: domain, infra, core, shared
+domain      → Can import: core, shared
+infra       → Can import: core, shared
+core        → Can import: shared
+shared      → Can import: (nothing above)
+```
+
+## Common Violations
+
+| Violation | Fix |
+|-----------|-----|
+| Entity imports Feature | Move shared logic to Entity or Shared |
+| Domain imports API | Use dependency injection |
+| Shared imports Feature | Extract to Shared or keep in Feature |
+
+## Checking Dependencies
+
+```bash
+# Check all architecture rules
+bunx mandu guard arch
+
+# Check specific file
+bunx mandu guard check src/entities/user/index.ts
+```

package/src/resources/skills/mandu-guard/rules/guard-preset-mandu.md

@@ -0,0 +1,81 @@
+---
+title: Use Mandu Preset for Full-Stack Projects
+impact: HIGH
+impactDescription: Recommended architecture preset
+tags: guard, preset, architecture
+---
+
+## Use Mandu Preset for Full-Stack Projects
+
+The Mandu preset combines FSD (Feature-Sliced Design) for frontend with Clean Architecture for backend.
+
+## Preset Selection Guide
+
+| Preset | Use Case | Frontend | Backend |
+|--------|----------|----------|---------|
+| `mandu` | Full-stack projects | FSD | Clean |
+| `fsd` | Frontend-focused | FSD | - |
+| `clean` | Backend-focused | - | Clean |
+| `hexagonal` | Domain-heavy | - | Hexagonal |
+| `atomic` | Component libraries | Atomic | - |
+
+## Mandu Preset Structure
+
+```
+src/
+├── app/                    # App entry, routing
+├── pages/                  # Page components
+├── widgets/                # Complex UI blocks
+├── features/               # Feature modules
+│   ├── auth/
+│   ├── cart/
+│   └── search/
+├── entities/               # Business entities
+│   ├── user/
+│   ├── product/
+│   └── order/
+├── shared/                 # Shared utilities
+│   ├── ui/                 # UI components
+│   ├── lib/                # Utility functions
+│   ├── api/                # API client
+│   └── config/             # Configuration
+└── api/                    # Backend
+    ├── application/        # Use cases
+    ├── domain/             # Business logic
+    ├── infra/              # Database, external
+    └── core/               # Core utilities
+```
+
+## Configuration
+
+```typescript
+// mandu.config.ts
+
+export default {
+  guard: {
+    preset: "mandu",  // Use mandu preset
+    rules: {
+      "LAYER_VIOLATION": "error",
+      "SLOT_NAMING": "warn",
+    },
+    ignore: [
+      "**/test/**",
+      "**/*.test.ts",
+      "**/*.spec.ts",
+    ],
+  },
+};
+```
+
+## Switching Presets
+
+```bash
+# Use FSD only (frontend project)
+bunx mandu guard arch --preset fsd
+
+# Use Clean only (backend project)
+bunx mandu guard arch --preset clean
+
+# Use Mandu (full-stack, default)
+bunx mandu guard arch --preset mandu
+```

package/src/resources/skills/mandu-guard/rules/guard-validate-import.md

@@ -0,0 +1,80 @@
+---
+title: Validate Import Paths Against Architecture
+impact: HIGH
+impactDescription: Prevents architecture violations
+tags: guard, validate, import
+---
+
+## Validate Import Paths Against Architecture
+
+Check that all imports respect layer boundaries before committing code.
+
+## Valid Import Examples
+
+```typescript
+// ✅ features/auth/login.ts → entities/user
+import { User, createUser } from "@/entities/user";
+
+// ✅ widgets/header/index.tsx → features/auth
+import { useAuth } from "@/features/auth";
+
+// ✅ pages/home/page.tsx → widgets/header
+import { Header } from "@/widgets/header";
+
+// ✅ Any layer → shared
+import { formatDate } from "@/shared/lib/date";
+```
+
+## Invalid Import Examples
+
+```typescript
+// ❌ entities/user → features/auth (upward)
+import { useAuth } from "@/features/auth";  // VIOLATION!
+
+// ❌ shared/lib → entities/user (upward)
+import { User } from "@/entities/user";  // VIOLATION!
+
+// ❌ features/auth → features/cart (same layer cross-import)
+import { CartItem } from "@/features/cart";  // VIOLATION!
+```
+
+## Checking Imports
+
+### CLI
+
+```bash
+# Check single import
+bunx mandu guard check-import \
+  --from "src/features/auth/index.ts" \
+  --import "@/entities/user"
+
+# Check all imports in a file
+bunx mandu guard check src/features/auth/index.ts
+```
+
+### MCP Tool
+
+```typescript
+// Check import validity
+mandu_check_import({
+  fromFile: "src/features/auth/index.ts",
+  importPath: "@/entities/user"
+})
+// Returns: { valid: true, layer: "features", targetLayer: "entities" }
+```
+
+## Fixing Violations
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Upward import | Lower layer needs higher | Move shared logic down or use DI |
+| Cross-feature import | Feature A uses Feature B | Extract to shared or create entity |
+| Circular import | A → B → A | Restructure or use interfaces |
+
+## CI Integration
+
+```yaml
+# .github/workflows/guard.yml
+- name: Check Architecture
+  run: bunx mandu guard arch --ci
+```

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

@@ -0,0 +1,91 @@
+---
+name: mandu-hydration
+description: |
+  Island Hydration pattern for Mandu. Use when creating interactive components,
+  client-side state, or partial hydration. Triggers on tasks involving
+  "use client", client.tsx, useState, useEffect, Island, or hydration.
+license: MIT
+metadata:
+  author: mandu
+  version: "1.0.0"
+---
+
+# Mandu Island Hydration
+
+Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티브하게 만드는 기술입니다.
+대부분의 페이지는 정적 HTML로 유지하고, 필요한 부분만 JavaScript를 로드합니다.
+
+## When to Apply
+
+Reference these guidelines when:
+- Creating interactive client components
+- Adding client-side state to pages
+- Implementing partial hydration
+- Setting up client-server data flow
+- Working with Island communication
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Client Directive | CRITICAL | `hydration-directive-` |
+| 2 | Island Structure | HIGH | `hydration-island-` |
+| 3 | Hydration Priority | MEDIUM | `hydration-priority-` |
+| 4 | Data Flow | MEDIUM | `hydration-data-` |
+
+## Quick Reference
+
+### 1. Client Directive (CRITICAL)
+
+- `hydration-directive-use-client` - Add "use client" directive for client components
+- `hydration-directive-file-naming` - Use .client.tsx for client component files
+
+### 2. Island Structure (HIGH)
+
+- `hydration-island-setup` - Use Mandu.island() with setup function
+- `hydration-island-render` - Separate state logic from render
+
+### 3. Hydration Priority (MEDIUM)
+
+- `hydration-priority-immediate` - Load on page load (critical interactions)
+- `hydration-priority-visible` - Load when visible (default)
+- `hydration-priority-idle` - Load when browser idle
+- `hydration-priority-interaction` - Load on user interaction
+
+### 4. Data Flow (MEDIUM)
+
+- `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
+import {
+  useServerData,
+  useHydrated,
+  useIslandEvent,
+} from "@mandujs/core/client";
+
+// Access SSR data
+const data = useServerData<UserData>("user", defaultValue);
+
+// Check hydration status
+const isHydrated = useHydrated();
+```
+
+## How to Use
+
+Read individual rule files for detailed explanations:
+
+```
+rules/hydration-directive-use-client.md
+rules/hydration-island-setup.md
+```

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

@@ -0,0 +1,12 @@
+{
+  "version": "1.0.0",
+  "organization": "Mandu Framework",
+  "date": "February 2026",
+  "abstract": "Island Hydration 패턴 가이드. 부분 hydration으로 페이지의 일부만 인터랙티브하게 만드는 기술입니다. \"use client\" 지시어, Mandu.island() API, hydration 우선순위, Island 간 통신을 다룹니다.",
+  "references": [
+    "https://jasonformat.com/islands-architecture/",
+    "https://docs.astro.build/en/concepts/islands/",
+    "https://fresh.deno.dev/docs/concepts/islands"
+  ],
+  "tags": ["hydration", "island", "client", "interactive", "mandu"]
+}

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

@@ -0,0 +1,31 @@
+# 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. Client Directive (hydration-directive)
+
+**Impact:** CRITICAL
+**Description:** "use client" 지시어와 .client.tsx 파일 명명. 클라이언트 컴포넌트 식별에 필수입니다.
+
+## 2. Island Structure (hydration-island)
+
+**Impact:** HIGH
+**Description:** Mandu.island() API로 Island 컴포넌트 구조화. setup/render 분리 패턴을 다룹니다.
+
+## 3. Hydration Priority (hydration-priority)
+
+**Impact:** MEDIUM
+**Description:** immediate, visible, idle, interaction 우선순위. 초기 로드 성능 최적화에 중요합니다.
+
+## 4. Data Flow (hydration-data)
+
+**Impact:** MEDIUM
+**Description:** useServerData, useIslandEvent를 통한 데이터 흐름. 서버-클라이언트, Island 간 통신입니다.
+
+## 5. Error Handling (hydration-error)
+
+**Impact:** LOW
+**Description:** errorBoundary, loading 상태 처리. 사용자 경험 향상을 위한 폴백 UI입니다.

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

@@ -0,0 +1,72 @@
+# Rule Template
+
+Use this template when creating new rules for mandu-hydration.
+
+---
+
+```markdown
+---
+title: Rule Title Here
+impact: CRITICAL | HIGH | MEDIUM | LOW
+impactDescription: 영향 설명
+tags: hydration, tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: {LEVEL} ({impactDescription})**
+
+규칙의 목적과 중요성을 설명합니다.
+
+**Incorrect (문제점 설명):**
+
+\`\`\`tsx
+// 잘못된 예시
+import { useState } from "react";
+
+export default function Counter() {
+  const [count, setCount] = useState(0);  // ❌ "use client" 없음
+  return <button>{count}</button>;
+}
+\`\`\`
+
+**Correct (올바른 방법):**
+
+\`\`\`tsx
+// 올바른 예시
+"use client";
+
+import { useState } from "react";
+
+export default function Counter() {
+  const [count, setCount] = useState(0);  // ✅ 작동함
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+\`\`\`
+
+Reference: [관련 문서 링크](https://example.com)
+```
+
+---
+
+## Naming Convention
+
+- 파일명: `{section}-{rule-name}.md`
+- 예시: `hydration-directive-use-client.md`, `hydration-island-setup.md`
+
+## Hydration Strategies Quick Reference
+
+| Strategy | JavaScript | Use Case |
+|----------|------------|----------|
+| `none` | 없음 | 순수 정적 페이지 |
+| `island` | 부분 | 정적 + 인터랙티브 혼합 (기본값) |
+| `full` | 전체 | SPA 스타일 페이지 |
+
+## Priority Quick Reference
+
+| Priority | Load Time | Use Case |
+|----------|-----------|----------|
+| `immediate` | 페이지 로드 | 중요한 인터랙션 |
+| `visible` | 뷰포트 진입 | 스크롤 아래 콘텐츠 (기본값) |
+| `idle` | 브라우저 유휴 | 비중요 기능 |
+| `interaction` | 사용자 액션 | 클릭해야 활성화 |