@mandujs/mcp 0.9.21 → 0.9.42

package/package.json

@@ -1,41 +1,41 @@
-{
-  "name": "@mandujs/mcp",
-  "version": "0.9.21",
-  "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
-  "type": "module",
-  "main": "./src/index.ts",
-  "bin": {
-    "mandu-mcp": "./src/index.ts"
-  },
-  "exports": {
-    ".": "./src/index.ts"
-  },
-  "files": [
-    "src/**/*"
-  ],
-  "keywords": [
-    "mandu",
-    "mcp",
-    "model-context-protocol",
-    "ai",
-    "agent",
-    "code-generation"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/konamgil/mandu.git",
-    "directory": "packages/mcp"
-  },
-  "author": "konamgil",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@mandujs/core": "^0.9.25",
-    "@modelcontextprotocol/sdk": "^1.25.3"
-  },
-  "engines": {
-    "bun": ">=1.0.0"
-  }
-}
+{
+  "name": "@mandujs/mcp",
+  "version": "0.9.42",
+  "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
+  "type": "module",
+  "main": "./src/index.ts",
+  "bin": {
+    "mandu-mcp": "./src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/**/*"
+  ],
+  "keywords": [
+    "mandu",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "code-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/konamgil/mandu.git",
+    "directory": "packages/mcp"
+  },
+  "author": "konamgil",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mandujs/core": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.25.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

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

@@ -1,92 +1,90 @@
 ---
 name: Mandu Styling
-description: CSS framework integration and Island styling patterns
+description: Tailwind CSS v4 integration and Island styling patterns for Mandu Framework
 metadata:
-  version: "1.0.0"
+  version: "2.0.0"
   author: mandu
+  tailwind: "v4.1+"
 globs:
-  - "tailwind.config.{js,ts}"
-  - "panda.config.{js,ts}"
-  - "postcss.config.{js,ts}"
   - "**/*.css"
   - "**/*.module.css"
+  - "app/globals.css"
 ---
 
 # Mandu Styling Skill
 
-Mandu Island 아키텍처에 최적화된 CSS 스타일링 가이드입니다.
+Mandu Island 아키텍처에 최적화된 Tailwind CSS v4 스타일링 가이드입니다.
 
 ## 핵심 원칙
 
 1. **Zero-Runtime**: 빌드 타임 CSS 생성 (SSR 호환)
-2. **Island 격리**: 컴포넌트 간 스타일 충돌 방지
-3. **Composition**: Tailwind utility + 컴포넌트 패턴
-4. **Performance**: Critical CSS, Tree-shaking
+2. **CSS-First**: JavaScript 설정 대신 CSS에서 테마 정의
+3. **Island 격리**: 컴포넌트 간 스타일 충돌 방지
+4. **Auto Integration**: Mandu가 Tailwind v4 자동 감지 및 빌드
 
 ## 권장 스택
 
 ```
-Primary:   Tailwind CSS + clsx/tailwind-merge
-Alternative: Panda CSS (type-safe 선호 시)
-Fallback:  CSS Modules (최소 의존성)
+Primary:    Tailwind CSS v4 + clsx/tailwind-merge
+Alternative: CSS Modules (최소 의존성)
 ```
 
 ## 빠른 시작
 
-### Tailwind CSS 설정
+### 1. 설치
 
 ```bash
-bun add -d tailwindcss postcss autoprefixer
-bunx tailwindcss init -p
+bun add -d tailwindcss@^4.1 @tailwindcss/cli@^4.1
+bun add clsx tailwind-merge
 ```
 
-```typescript
-// tailwind.config.ts
-import type { Config } from "tailwindcss";
-
-export default {
-  content: ["./app/**/*.{ts,tsx}"],
-  theme: {
-    extend: {
-      colors: {
-        mandu: {
-          primary: "#3b82f6",
-          secondary: "#64748b",
-        },
-      },
-    },
-  },
-  plugins: [],
-} satisfies Config;
-```
+### 2. app/globals.css
 
 ```css
-/* app/globals.css */
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+@import "tailwindcss";
+
+@theme {
+  --color-primary: hsl(222.2 47.4% 11.2%);
+  --color-primary-foreground: hsl(210 40% 98%);
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(222.2 84% 4.9%);
+  --radius-md: 0.5rem;
+  --font-sans: 'Inter', system-ui, sans-serif;
+}
+
+body {
+  background-color: var(--color-background);
+  color: var(--color-foreground);
+}
 ```
 
-### Island 스타일링
+### 3. Mandu 자동 통합
 
-```tsx
-// app/counter/client.tsx
-"use client";
+```
+mandu dev 실행 시:
+├─ @import "tailwindcss" 감지
+├─ Tailwind CLI --watch 자동 시작
+├─ 출력: .mandu/client/globals.css
+├─ SSR에서 <link> 자동 주입
+└─ CSS 변경 시 HMR 핫 리로드
+```
 
-import { cn } from "@/lib/utils";
+## Island 스타일링
 
-interface CounterProps {
-  variant?: "default" | "outline";
-}
+```tsx
+// src/client/widgets/counter/Counter.island.tsx
+"use client";
 
-export function CounterIsland({ variant = "default" }: CounterProps) {
-  const variants = {
-    default: "bg-mandu-primary text-white",
-    outline: "border-2 border-mandu-primary text-mandu-primary",
-  };
+import { cn } from "@/shared/lib/utils";
 
+export function CounterIsland({ variant = "default" }) {
   return (
-    <button className={cn("px-4 py-2 rounded-lg", variants[variant])}>
+    <button className={cn(
+      "px-4 py-2 rounded-md font-medium transition-colors",
+      variant === "default"
+        ? "bg-primary text-primary-foreground hover:bg-primary/90"
+        : "border border-primary text-primary hover:bg-primary/10"
+    )}>
       Count: 0
     </button>
   );
@@ -96,7 +94,7 @@ export function CounterIsland({ variant = "default" }: CounterProps) {
 ## cn 유틸리티
 
 ```typescript
-// lib/utils.ts
+// src/client/shared/lib/utils.ts
 import { clsx, type ClassValue } from "clsx";
 import { twMerge } from "tailwind-merge";
 
@@ -105,14 +103,52 @@ export function cn(...inputs: ClassValue[]) {
 }
 ```
 
+## Custom Utilities
+
+```css
+/* v4 방식: @utility 사용 */
+@utility text-balance {
+  text-wrap: balance;
+}
+
+@utility scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+  &::-webkit-scrollbar { display: none; }
+}
+```
+
+## v4 주요 변경사항
+
+| v3 | v4 |
+|----|-----|
+| `@tailwind base/utilities` | `@import "tailwindcss"` |
+| `tailwind.config.ts` | `@theme { }` in CSS |
+| `!bg-red-500` | `bg-red-500!` |
+| `@layer utilities` | `@utility` |
+| `bg-[--var]` | `bg-(--var)` |
+
+> 자세한 내용은 `rules/style-tailwind-v4-gotchas.md` 참조
+
 ## 규칙 카테고리
 
 | Category | Description | Rules |
 |----------|-------------|-------|
-| Setup | 프레임워크 설정 | 3 |
+| Setup | Tailwind v4 설정 | 1 |
+| Gotchas | v4 주의사항/마이그레이션 | 1 |
 | Island | Island 스타일 패턴 | 3 |
 | Component | 컴포넌트 스타일 | 3 |
 | Performance | 최적화 | 2 |
 | Theme | 테마/다크모드 | 1 |
 
 → 세부 규칙은 `rules/` 폴더 참조
+
+## Browser Support
+
+```
+Safari 16.4+ | Chrome 111+ | Firefox 128+
+```
+
+> IE 및 구형 브라우저 미지원. 레거시 프로젝트는 Tailwind v3 유지 권장.
+
+Reference: [Tailwind CSS v4](https://tailwindcss.com/docs)

package/src/resources/skills/mandu-styling/_sections.md

@@ -1,12 +1,19 @@
 # Mandu Styling - Rule Categories
 
 ## Setup
-CSS 프레임워크 초기 설정 및 Bun 통합
+CSS 프레임워크 초기 설정 및 Mandu 통합 (Tailwind v4 CSS-first)
 
 | Impact | Description |
 |--------|-------------|
 | CRITICAL | 프레임워크 설정 없이 스타일링 불가 |
 
+## Gotchas
+Tailwind CSS v4 마이그레이션 주의사항 및 Breaking Changes
+
+| Impact | Description |
+|--------|-------------|
+| HIGH | v3→v4 마이그레이션 시 필수 확인 사항 |
+
 ## Island
 Island 컴포넌트 특화 스타일링 패턴
 

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

@@ -1,13 +1,15 @@
 {
   "id": "mandu-styling",
   "name": "Mandu Styling",
-  "version": "1.0.0",
-  "description": "CSS framework integration and Island styling patterns",
+  "version": "2.0.0",
+  "description": "Tailwind CSS v4 integration and Island styling patterns for Mandu Framework",
   "author": "mandu",
+  "tailwind": "v4.1+",
   "references": [
     "https://tailwindcss.com/docs",
+    "https://tailwindcss.com/docs/upgrade-guide",
     "https://panda-css.com/docs",
     "https://lightningcss.dev/"
   ],
-  "abstract": "Mandu Island 아키텍처에 최적화된 CSS 스타일링 패턴. Tailwind CSS를 primary로, Panda CSS와 CSS Modules를 대안으로 제공합니다."
+  "abstract": "Mandu Island 아키텍처에 최적화된 Tailwind CSS v4 스타일링 가이드. CSS-first 설정, @theme 블록, Mandu 자동 통합(CSS Auto-Build, HMR)을 지원합니다."
 }

package/src/resources/skills/mandu-styling/rules/style-setup-tailwind.md

@@ -1,97 +1,93 @@
 ---
-title: Tailwind CSS Setup
+title: Tailwind CSS v4 Setup
 impact: CRITICAL
-impactDescription: Primary CSS framework for Mandu applications
-tags: styling, tailwind, setup, postcss
+impactDescription: Primary CSS framework for Mandu applications (v4 required)
+tags: styling, tailwind, setup, v4, css-first
 ---
 
-## Tailwind CSS Setup
+## Tailwind CSS v4 Setup
 
 **Impact: CRITICAL (Primary CSS framework for Mandu applications)**
 
-Tailwind CSS를 Mandu 프로젝트에 설정하세요. Bun과 PostCSS 통합을 포함합니다.
+Tailwind CSS v4를 Mandu 프로젝트에 설정합니다. v4는 Oxide Engine(Rust)으로 재작성되어 빌드 속도가 3.5~5배 향상되었습니다.
 
-**설치:**
+## 설치
 
 ```bash
-bun add -d tailwindcss postcss autoprefixer
+bun add -d tailwindcss@^4.1 @tailwindcss/cli@^4.1
 bun add clsx tailwind-merge
-bunx tailwindcss init -p
 ```
 
-**tailwind.config.ts:**
+> **Note:** PostCSS, autoprefixer는 불필요합니다. Tailwind v4가 내장 처리합니다.
 
-```typescript
-import type { Config } from "tailwindcss";
+## app/globals.css (CSS-first Configuration)
 
-export default {
-  content: [
-    "./app/**/*.{ts,tsx}",
-    "./components/**/*.{ts,tsx}",
-    "./lib/**/*.{ts,tsx}",
-  ],
-  theme: {
-    extend: {
-      colors: {
-        mandu: {
-          primary: "hsl(var(--mandu-primary))",
-          secondary: "hsl(var(--mandu-secondary))",
-          accent: "hsl(var(--mandu-accent))",
-          background: "hsl(var(--mandu-background))",
-          foreground: "hsl(var(--mandu-foreground))",
-        },
-      },
-      borderRadius: {
-        mandu: "var(--mandu-radius)",
-      },
-    },
-  },
-  plugins: [],
-} satisfies Config;
-```
+```css
+@import "tailwindcss";
+
+/*
+ * Tailwind CSS v4 - CSS-first Configuration
+ * JavaScript 설정 파일 대신 CSS에서 직접 테마 정의
+ */
+
+@theme {
+  /* Colors - shadcn/ui compatible */
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(222.2 84% 4.9%);
+  --color-card: hsl(0 0% 100%);
+  --color-card-foreground: hsl(222.2 84% 4.9%);
+  --color-primary: hsl(222.2 47.4% 11.2%);
+  --color-primary-foreground: hsl(210 40% 98%);
+  --color-secondary: hsl(210 40% 96.1%);
+  --color-secondary-foreground: hsl(222.2 47.4% 11.2%);
+  --color-muted: hsl(210 40% 96.1%);
+  --color-muted-foreground: hsl(215.4 16.3% 46.9%);
+  --color-accent: hsl(210 40% 96.1%);
+  --color-accent-foreground: hsl(222.2 47.4% 11.2%);
+  --color-destructive: hsl(0 84.2% 60.2%);
+  --color-destructive-foreground: hsl(210 40% 98%);
+  --color-border: hsl(214.3 31.8% 91.4%);
+  --color-input: hsl(214.3 31.8% 91.4%);
+  --color-ring: hsl(222.2 84% 4.9%);
+
+  /* Radius */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 0.75rem;
+
+  /* Fonts */
+  --font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
+}
 
-**postcss.config.js:**
+/* Base styles */
+* {
+  border-color: var(--color-border);
+}
 
-```javascript
-export default {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-};
+body {
+  background-color: var(--color-background);
+  color: var(--color-foreground);
+  font-family: var(--font-sans);
+}
 ```
 
-**app/globals.css:**
+## Mandu 자동 통합
 
-```css
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer base {
-  :root {
-    --mandu-primary: 221.2 83.2% 53.3%;
-    --mandu-secondary: 210 40% 96.1%;
-    --mandu-accent: 210 40% 96.1%;
-    --mandu-background: 0 0% 100%;
-    --mandu-foreground: 222.2 84% 4.9%;
-    --mandu-radius: 0.5rem;
-  }
+Mandu는 Tailwind v4를 자동으로 감지하고 처리합니다:
 
-  .dark {
-    --mandu-primary: 217.2 91.2% 59.8%;
-    --mandu-secondary: 217.2 32.6% 17.5%;
-    --mandu-accent: 217.2 32.6% 17.5%;
-    --mandu-background: 222.2 84% 4.9%;
-    --mandu-foreground: 210 40% 98%;
-  }
-}
+```
+mandu dev 실행 시:
+1. app/globals.css에서 @import "tailwindcss" 감지
+2. bunx @tailwindcss/cli --watch 자동 시작
+3. 출력: .mandu/client/globals.css
+4. SSR에서 <link> 태그 자동 주입
+5. CSS 변경 시 HMR 핫 리로드
 ```
 
 ## cn 유틸리티 함수
 
 ```typescript
-// lib/utils.ts
+// src/client/shared/lib/utils.ts
 import { clsx, type ClassValue } from "clsx";
 import { twMerge } from "tailwind-merge";
 
@@ -100,62 +96,75 @@ export function cn(...inputs: ClassValue[]) {
 }
 ```
 
-## 사용 예시
+## Island 컴포넌트 스타일링
 
 ```tsx
-// app/button/client.tsx
+// src/client/features/counter/CounterIsland.tsx
 "use client";
 
-import { cn } from "@/lib/utils";
+import { cn } from "@/shared/lib/utils";
 
-interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-  variant?: "default" | "outline" | "ghost";
-  size?: "sm" | "md" | "lg";
+interface CounterProps {
+  variant?: "default" | "outline";
 }
 
-export function ButtonIsland({
-  variant = "default",
-  size = "md",
-  className,
-  ...props
-}: ButtonProps) {
+export function CounterIsland({ variant = "default" }: CounterProps) {
+  const variants = {
+    default: "bg-primary text-primary-foreground",
+    outline: "border-2 border-primary text-primary",
+  };
+
   return (
-    <button
-      className={cn(
-        // Base
-        "inline-flex items-center justify-center rounded-mandu font-medium transition-colors",
-        // Variants
-        {
-          default: "bg-mandu-primary text-white hover:bg-mandu-primary/90",
-          outline: "border border-mandu-primary text-mandu-primary hover:bg-mandu-primary/10",
-          ghost: "hover:bg-mandu-secondary",
-        }[variant],
-        // Sizes
-        {
-          sm: "h-8 px-3 text-sm",
-          md: "h-10 px-4",
-          lg: "h-12 px-6 text-lg",
-        }[size],
-        className
-      )}
-      {...props}
-    />
+    <button className={cn(
+      "px-4 py-2 rounded-md transition-colors",
+      variants[variant]
+    )}>
+      Count: 0
+    </button>
   );
 }
 ```
 
+## Custom Utilities (v4 방식)
+
+```css
+/* @layer utilities 대신 @utility 사용 */
+@utility text-balance {
+  text-wrap: balance;
+}
+
+@utility scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+```
+
 ## VSCode 설정
 
 ```json
 // .vscode/settings.json
 {
   "tailwindCSS.experimental.classRegex": [
-    ["cn\\(([^)]*)\\)", "'([^']*)'"]
+    ["cn\\(([^)]*)\\)", "'([^']*)'"],
+    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
   ],
   "editor.quickSuggestions": {
     "strings": true
+  },
+  "files.associations": {
+    "*.css": "tailwindcss"
   }
 }
 ```
 
-Reference: [Tailwind CSS Documentation](https://tailwindcss.com/docs)
+## 삭제할 파일 (v3에서 마이그레이션 시)
+
+```bash
+rm -f tailwind.config.ts tailwind.config.js
+rm -f postcss.config.js postcss.config.ts
+```
+
+Reference: [Tailwind CSS v4 Documentation](https://tailwindcss.com/docs)

package/src/resources/skills/mandu-styling/rules/style-tailwind-v4-gotchas.md

@@ -0,0 +1,179 @@
+---
+title: Tailwind CSS v4 Gotchas
+impact: HIGH
+impactDescription: Critical breaking changes when using or migrating to Tailwind v4
+tags: styling, tailwind, v4, gotchas, migration, breaking-changes
+---
+
+## Tailwind CSS v4 Gotchas
+
+**Impact: HIGH (Critical breaking changes when using or migrating to Tailwind v4)**
+
+Tailwind v4는 완전히 재작성된 프레임워크입니다. v3에서 마이그레이션 시 반드시 확인해야 할 주의사항입니다.
+
+## Browser Support
+
+```
+Safari 16.4+ | Chrome 111+ | Firefox 128+
+```
+
+> **Warning:** IE 및 구형 브라우저 지원 불가. 레거시 프로젝트는 v3 유지 권장.
+
+## Import Syntax 변경
+
+```css
+/* v3 (deprecated) */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* v4 (required) */
+@import "tailwindcss";
+```
+
+## Important Modifier 위치 변경
+
+```css
+/* v3 */
+!bg-red-500
+
+/* v4 - 끝에 위치 */
+bg-red-500!
+```
+
+## Custom Utilities 문법 변경
+
+```css
+/* v3 */
+@layer utilities {
+  .text-balance {
+    text-wrap: balance;
+  }
+}
+
+/* v4 - @utility 사용 */
+@utility text-balance {
+  text-wrap: balance;
+}
+```
+
+## Stacked Variants 순서 변경
+
+```html
+<!-- v3: right-to-left (hover가 dark보다 우선) -->
+<div class="dark:hover:bg-blue-500">
+
+<!-- v4: left-to-right (dark가 hover보다 우선) -->
+<div class="dark:hover:bg-blue-500">
+```
+
+> v4에서는 왼쪽부터 적용되므로 variant 순서에 주의하세요.
+
+## CSS Variable Syntax 변경
+
+```html
+<!-- v3 -->
+<div class="bg-[var(--brand-color)]">
+<div class="bg-[--brand-color]">
+
+<!-- v4 - 괄호 문법 사용 -->
+<div class="bg-(--brand-color)">
+```
+
+## hover: 동작 변경
+
+```html
+<!-- v4에서 hover:는 hover 지원 기기에서만 적용 -->
+<!-- 터치 기기에서는 적용되지 않음 -->
+<button class="hover:bg-blue-500">
+
+<!-- 모든 기기에서 적용하려면 -->
+<button class="hover:bg-blue-500 active:bg-blue-500">
+```
+
+## Default Color 변경
+
+```css
+/* v4 기본값 변경 */
+border-color: currentColor; /* v3: gray-200 */
+ring-width: 1px;           /* v3: 3px */
+ring-color: currentColor;   /* v3: blue-500/50 */
+```
+
+> 기존 디자인이 깨질 수 있으니 명시적 색상 지정 권장.
+
+## Transform 초기화 변경
+
+```html
+<!-- v3 -->
+<div class="transform-none">
+
+<!-- v4 - 개별 속성 사용 -->
+<div class="scale-none rotate-none translate-none">
+```
+
+## space-* / divide-* 선택자 변경
+
+```html
+<!-- 레이아웃이 깨지면 gap으로 대체 -->
+<div class="flex gap-4">  <!-- space-x-4 대신 -->
+<div class="grid gap-4">  <!-- space-y-4 대신 -->
+```
+
+## CSS Modules에서 Theme 변수 접근
+
+```css
+/* Component.module.css */
+@reference "tailwindcss";  /* v4 필수 */
+
+.button {
+  background-color: var(--color-primary);
+}
+```
+
+## Prefix 설정 변경
+
+```css
+/* v3: tailwind.config.js */
+module.exports = { prefix: 'tw-' }
+
+/* v4: CSS에서 설정 */
+@import "tailwindcss" prefix(tw);
+
+/* 사용 시 콜론 형식 */
+<div class="tw:bg-blue-500">
+```
+
+## Mandu 특화 주의사항
+
+### Island 컴포넌트에서 @reference
+
+```tsx
+// Island에서 CSS Modules 사용 시
+import styles from './Counter.module.css';
+
+// Counter.module.css에 @reference 필수
+```
+
+### SSR과 CSS 순서
+
+Mandu의 CSS Auto-Build는 `/.mandu/client/globals.css`에 출력합니다.
+SSR 시 이 경로로 자동 주입되므로 별도 설정 불필요.
+
+### HMR 동작
+
+CSS 변경 시 `css-update` HMR 메시지로 스타일시트만 교체됩니다.
+페이지 전체 리로드 없이 스타일 변경 확인 가능.
+
+## 마이그레이션 체크리스트
+
+- [ ] Browser support 확인 (Safari 16.4+)
+- [ ] `@tailwind` → `@import "tailwindcss"` 변경
+- [ ] `tailwind.config.ts` 삭제, `@theme`으로 이전
+- [ ] `postcss.config.js` 삭제
+- [ ] Important modifier 위치 변경 (`!` → 끝)
+- [ ] `@layer utilities` → `@utility` 변경
+- [ ] CSS variable 문법 확인 `[--var]` → `(--var)`
+- [ ] space-*/divide-* 레이아웃 확인
+
+Reference: [Tailwind CSS v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide)