@mandujs/mcp 0.9.19 → 0.9.21

package/src/resources/skills/mandu-composition/rules/comp-state-context-interface.md

@@ -0,0 +1,148 @@
+---
+title: Define Generic Context Interface for Dependency Injection
+impact: HIGH
+impactDescription: Enables dependency-injectable state across use-cases
+tags: composition, context, state, typescript, dependency-injection
+---
+
+## Define Generic Context Interface for Dependency Injection
+
+**Impact: HIGH (Enables dependency-injectable state across use-cases)**
+
+컴포넌트 context를 위한 제네릭 인터페이스를 `state`, `actions`, `meta` 세 부분으로 정의하세요. 어떤 Provider든 이 인터페이스를 구현할 수 있어, 같은 UI 컴포넌트가 완전히 다른 상태 구현과 작동할 수 있습니다.
+
+**핵심 원칙:** Lift state, compose internals, make state dependency-injectable.
+
+**Incorrect (특정 상태 구현에 결합):**
+
+```tsx
+// ❌ 특정 훅에 강하게 결합
+function ComposerInput() {
+  const { input, setInput } = useChannelComposerState();
+  return <TextInput value={input} onChangeText={setInput} />;
+}
+```
+
+**Correct (제네릭 인터페이스로 의존성 주입):**
+
+```tsx
+// ✅ 어떤 Provider든 구현할 수 있는 제네릭 인터페이스
+interface ComposerState {
+  input: string;
+  attachments: Attachment[];
+  isSubmitting: boolean;
+}
+
+interface ComposerActions {
+  update: (updater: (state: ComposerState) => ComposerState) => void;
+  submit: () => void;
+  addAttachment: (file: File) => void;
+}
+
+interface ComposerMeta {
+  inputRef: React.RefObject<HTMLTextAreaElement>;
+  maxLength?: number;
+}
+
+interface ComposerContextValue {
+  state: ComposerState;
+  actions: ComposerActions;
+  meta: ComposerMeta;
+}
+
+const ComposerContext = createContext<ComposerContextValue | null>(null);
+```
+
+**UI 컴포넌트는 인터페이스만 소비:**
+
+```tsx
+function ComposerInput() {
+  const {
+    state,
+    actions: { update },
+    meta,
+  } = use(ComposerContext)!;
+
+  // 이 컴포넌트는 인터페이스를 구현한 어떤 Provider와도 작동
+  return (
+    <textarea
+      ref={meta.inputRef}
+      value={state.input}
+      maxLength={meta.maxLength}
+      onChange={(e) => update((s) => ({ ...s, input: e.target.value }))}
+    />
+  );
+}
+```
+
+**서로 다른 Provider가 같은 인터페이스 구현:**
+
+```tsx
+// Provider A: 임시 폼을 위한 로컬 상태
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState);
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+  const submit = useForwardMessage();
+
+  return (
+    <ComposerContext value={{
+      state,
+      actions: { update: setState, submit, addAttachment: ... },
+      meta: { inputRef },
+    }}>
+      {children}
+    </ComposerContext>
+  );
+}
+
+// Provider B: 채널을 위한 전역 동기화 상태
+function ChannelProvider({ channelId, children }: Props) {
+  const { state, update, submit } = useGlobalChannel(channelId);
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+
+  return (
+    <ComposerContext value={{
+      state,
+      actions: { update, submit, addAttachment: ... },
+      meta: { inputRef, maxLength: 2000 },
+    }}>
+      {children}
+    </ComposerContext>
+  );
+}
+```
+
+**같은 UI가 두 Provider와 모두 작동:**
+
+```tsx
+// ForwardMessageProvider와 작동 (로컬 상태)
+<ForwardMessageProvider>
+  <Composer.Frame>
+    <Composer.Input />
+    <Composer.Submit />
+  </Composer.Frame>
+</ForwardMessageProvider>
+
+// ChannelProvider와 작동 (전역 동기화 상태)
+<ChannelProvider channelId="abc">
+  <Composer.Frame>
+    <Composer.Input />
+    <Composer.Submit />
+  </Composer.Frame>
+</ChannelProvider>
+```
+
+## Mandu Island에서의 활용
+
+```tsx
+// Island 컴포넌트는 인터페이스만 알면 됨
+// slot에서 어떤 Provider를 사용하든 같은 Island 재사용 가능
+
+// spec/slots/forward.slot.ts → ForwardMessageProvider 사용
+// spec/slots/channel.slot.ts → ChannelProvider 사용
+// 둘 다 같은 Composer Island 컴포넌트 사용
+```
+
+UI는 재사용 가능한 조각들이고, 상태는 Provider가 주입합니다. Provider를 바꾸면 UI는 그대로!
+
+Reference: [Context Interface Pattern](https://kentcdodds.com/blog/how-to-use-react-context-effectively)

package/src/resources/skills/mandu-composition/rules/comp-state-lift-state.md

@@ -0,0 +1,150 @@
+---
+title: Lift State into Provider for Sibling Access
+impact: HIGH
+impactDescription: Enables state sharing without prop drilling
+tags: composition, state, provider, lift-state
+---
+
+## Lift State into Provider for Sibling Access
+
+**Impact: HIGH (Enables state sharing without prop drilling)**
+
+형제 컴포넌트가 상태를 공유해야 할 때, 상태를 Provider로 끌어올리세요. Provider 경계 내의 모든 컴포넌트가 상태에 접근할 수 있습니다.
+
+**Incorrect (prop drilling):**
+
+```tsx
+// ❌ 상태를 여러 단계로 전달
+function ChatPage() {
+  const [message, setMessage] = useState("");
+  const [isTyping, setIsTyping] = useState(false);
+
+  return (
+    <div>
+      <MessageList
+        isTyping={isTyping}
+        typingMessage={message}  // prop drilling
+      />
+      <Composer
+        message={message}
+        setMessage={setMessage}
+        setIsTyping={setIsTyping}
+      />
+      <TypingIndicator isTyping={isTyping} />  // prop drilling
+    </div>
+  );
+}
+```
+
+**Correct (Provider로 끌어올리기):**
+
+```tsx
+// ✅ Provider가 상태 관리
+interface ChatContextValue {
+  state: { message: string; isTyping: boolean };
+  actions: { setMessage: (msg: string) => void; setIsTyping: (val: boolean) => void };
+}
+
+const ChatContext = createContext<ChatContextValue | null>(null);
+
+function ChatProvider({ children }: { children: React.ReactNode }) {
+  const [message, setMessage] = useState("");
+  const [isTyping, setIsTyping] = useState(false);
+
+  return (
+    <ChatContext value={{
+      state: { message, isTyping },
+      actions: { setMessage, setIsTyping },
+    }}>
+      {children}
+    </ChatContext>
+  );
+}
+
+// 각 컴포넌트가 필요한 것만 가져감
+function MessageList() {
+  const { state } = use(ChatContext)!;
+  return (
+    <div>
+      {messages.map(msg => <Message key={msg.id} {...msg} />)}
+      {state.isTyping && <TypingPreview text={state.message} />}
+    </div>
+  );
+}
+
+function Composer() {
+  const { state, actions } = use(ChatContext)!;
+  return (
+    <textarea
+      value={state.message}
+      onChange={(e) => {
+        actions.setMessage(e.target.value);
+        actions.setIsTyping(e.target.value.length > 0);
+      }}
+    />
+  );
+}
+
+function TypingIndicator() {
+  const { state } = use(ChatContext)!;
+  if (!state.isTyping) return null;
+  return <span>Someone is typing...</span>;
+}
+```
+
+**사용:**
+
+```tsx
+function ChatPage() {
+  return (
+    <ChatProvider>
+      <div>
+        <MessageList />    {/* context에서 상태 읽음 */}
+        <Composer />       {/* context에서 상태 수정 */}
+        <TypingIndicator /> {/* context에서 상태 읽음 */}
+      </div>
+    </ChatProvider>
+  );
+}
+```
+
+## Provider 경계 이해하기
+
+Provider 경계 내라면 시각적 위치와 무관하게 상태 접근 가능:
+
+```tsx
+<ChatProvider>
+  <Dialog>
+    {/* Dialog 내부 */}
+    <Composer.Frame>
+      <Composer.Input />
+    </Composer.Frame>
+
+    {/* Frame 외부지만 Provider 내부! */}
+    <MessagePreview />  {/* ✅ context 접근 가능 */}
+
+    <DialogActions>
+      <SendButton />    {/* ✅ context 접근 가능 */}
+    </DialogActions>
+  </Dialog>
+</ChatProvider>
+```
+
+## Mandu Island에서의 적용
+
+```tsx
+// app/chat/page.tsx
+import { ChatIsland } from "./client";
+
+export default function ChatPage({ data }) {
+  return (
+    <div>
+      <h1>Chat</h1>
+      {/* Island 내부에서 Provider로 상태 관리 */}
+      <ChatIsland initialMessages={data.messages} />
+    </div>
+  );
+}
+```
+
+Reference: [Lifting State Up](https://react.dev/learn/sharing-state-between-components)

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

@@ -0,0 +1,92 @@
+---
+name: Mandu Deployment
+description: Production deployment patterns for Mandu applications
+metadata:
+  version: "1.0.0"
+  author: mandu
+globs:
+  - "render.yaml"
+  - "Dockerfile"
+  - "docker-compose.yml"
+  - ".github/workflows/*.yml"
+  - "bunfig.toml"
+---
+
+# Mandu Deployment Skill
+
+Mandu 앱을 프로덕션 환경에 안전하고 효율적으로 배포하기 위한 가이드입니다.
+
+## 핵심 원칙
+
+1. **Bun 네이티브**: Bun 런타임과 번들러를 최대한 활용
+2. **환경 분리**: 개발/스테이징/프로덕션 환경 명확히 구분
+3. **자동화**: CI/CD를 통한 일관된 배포 프로세스
+4. **보안 우선**: 민감 정보는 환경 변수로 관리
+
+## 빠른 시작
+
+### Render 배포 (권장)
+
+```yaml
+# render.yaml
+services:
+  - type: web
+    name: mandu-app
+    runtime: node
+    buildCommand: bun install && bun run build
+    startCommand: bun run start
+    envVars:
+      - key: NODE_ENV
+        value: production
+      - key: BUN_ENV
+        value: production
+```
+
+### Docker 배포
+
+```dockerfile
+FROM oven/bun:1.0
+
+WORKDIR /app
+COPY package.json bun.lockb ./
+RUN bun install --frozen-lockfile --production
+
+COPY . .
+RUN bun run build
+
+EXPOSE 3000
+CMD ["bun", "run", "start"]
+```
+
+## 배포 체크리스트
+
+### 빌드 준비
+- [ ] `bun run build` 성공 확인
+- [ ] 번들 크기 최적화 (tree-shaking, code-splitting)
+- [ ] 환경 변수 설정 완료
+
+### 플랫폼 설정
+- [ ] Render/Docker 설정 파일 작성
+- [ ] 헬스체크 엔드포인트 구현
+- [ ] 로깅 설정 완료
+
+### 보안
+- [ ] 민감 정보 환경 변수로 분리
+- [ ] HTTPS 강제 적용
+- [ ] 보안 헤더 설정
+
+### 모니터링
+- [ ] 에러 트래킹 설정
+- [ ] 성능 모니터링 구성
+- [ ] 알림 설정
+
+## 규칙 카테고리
+
+| Category | Description | Rules |
+|----------|-------------|-------|
+| Build | 프로덕션 빌드 최적화 | 2 |
+| Platform | 플랫폼별 배포 설정 | 3 |
+| Container | Docker 컨테이너화 | 2 |
+| CI/CD | 자동화 파이프라인 | 1 |
+
+→ 세부 규칙은 `rules/` 폴더 참조

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

@@ -0,0 +1,41 @@
+# Mandu Deployment - Rule Categories
+
+## Build
+프로덕션 빌드 최적화 및 번들링 설정
+
+| Impact | Description |
+|--------|-------------|
+| CRITICAL | 빌드 실패 시 배포 불가 |
+| HIGH | 번들 크기, 빌드 시간에 큰 영향 |
+
+## Platform
+배포 플랫폼별 설정 및 최적화
+
+| Impact | Description |
+|--------|-------------|
+| CRITICAL | 플랫폼 호환성 필수 |
+| HIGH | 성능, 비용에 큰 영향 |
+
+## Container
+Docker 컨테이너화 및 오케스트레이션
+
+| Impact | Description |
+|--------|-------------|
+| HIGH | 일관된 배포 환경 보장 |
+| MEDIUM | 개발/프로덕션 환경 일치 |
+
+## CI/CD
+지속적 통합 및 배포 파이프라인
+
+| Impact | Description |
+|--------|-------------|
+| HIGH | 자동화된 품질 보증 |
+| MEDIUM | 배포 속도 및 안정성 향상 |
+
+## Environment
+환경 변수 및 설정 관리
+
+| Impact | Description |
+|--------|-------------|
+| CRITICAL | 보안 민감 정보 보호 |
+| HIGH | 환경별 설정 분리 |

package/src/resources/skills/mandu-deployment/_template.md

@@ -0,0 +1,38 @@
+---
+title: Rule Title Here
+impact: CRITICAL | HIGH | MEDIUM | LOW
+impactDescription: One-line description of why this matters
+tags: deployment, tag2, tag3
+---
+
+## Rule Title Here
+
+**Impact: LEVEL (Impact description)**
+
+규칙에 대한 간단한 설명.
+
+**설정 예시:**
+
+```yaml
+# 설정 파일 예시
+key: value
+```
+
+**구현 예시:**
+
+```typescript
+// 코드 예시
+```
+
+## 추가 설정
+
+```bash
+# 명령어 예시
+```
+
+## 주의사항
+
+- 첫 번째 주의사항
+- 두 번째 주의사항
+
+Reference: [문서 링크](https://example.com)

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

@@ -0,0 +1,13 @@
+{
+  "id": "mandu-deployment",
+  "name": "Mandu Deployment",
+  "version": "1.0.0",
+  "description": "Production deployment patterns for Mandu applications",
+  "author": "mandu",
+  "references": [
+    "https://bun.sh/docs/bundler",
+    "https://render.com/docs",
+    "https://docs.docker.com/"
+  ],
+  "abstract": "Mandu 앱을 프로덕션 환경에 배포하기 위한 패턴과 가이드. Bun 빌드 최적화, Render/Docker 배포, CI/CD 파이프라인, 환경 설정을 다룹니다."
+}

package/src/resources/skills/mandu-deployment/rules/deploy-build-bun.md

@@ -0,0 +1,109 @@
+---
+title: Bun Production Build
+impact: CRITICAL
+impactDescription: Build failure blocks deployment
+tags: deployment, build, bun, bundler
+---
+
+## Bun Production Build
+
+**Impact: CRITICAL (Build failure blocks deployment)**
+
+Bun 번들러를 사용하여 프로덕션 최적화된 빌드를 생성하세요.
+
+**bunfig.toml 설정:**
+
+```toml
+[build]
+target = "bun"
+minify = true
+sourcemap = "external"
+
+[build.define]
+"process.env.NODE_ENV" = "'production'"
+```
+
+**빌드 스크립트:**
+
+```typescript
+// scripts/build.ts
+import { $ } from "bun";
+
+// 클린 빌드
+await $`rm -rf dist`;
+
+// 서버 빌드
+await Bun.build({
+  entrypoints: ["./src/server.ts"],
+  outdir: "./dist",
+  target: "bun",
+  minify: true,
+  sourcemap: "external",
+  define: {
+    "process.env.NODE_ENV": JSON.stringify("production"),
+  },
+});
+
+// 클라이언트 빌드 (Islands)
+await Bun.build({
+  entrypoints: ["./app/**/client.tsx"],
+  outdir: "./dist/public",
+  target: "browser",
+  minify: true,
+  splitting: true,
+  sourcemap: "external",
+});
+
+console.log("✅ Build complete");
+```
+
+## package.json 스크립트
+
+```json
+{
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "start": "NODE_ENV=production bun run dist/server.js",
+    "preview": "bun run build && bun run start"
+  }
+}
+```
+
+## 빌드 최적화 옵션
+
+```typescript
+await Bun.build({
+  entrypoints: ["./src/index.ts"],
+  outdir: "./dist",
+
+  // 필수 최적화
+  minify: true,           // 코드 압축
+  splitting: true,        // 코드 분할
+
+  // 선택적 최적화
+  treeshaking: true,      // 미사용 코드 제거 (기본값)
+
+  // 외부 패키지 처리
+  external: ["better-sqlite3"],  // 네이티브 모듈 제외
+
+  // 환경 변수 주입
+  define: {
+    "process.env.API_URL": JSON.stringify(process.env.API_URL),
+  },
+});
+```
+
+## 빌드 검증
+
+```bash
+# 빌드 크기 확인
+du -sh dist/
+
+# 번들 분석
+bun build --analyze ./src/server.ts
+
+# 빌드 테스트
+bun run dist/server.js
+```
+
+Reference: [Bun Bundler](https://bun.sh/docs/bundler)

package/src/resources/skills/mandu-deployment/rules/deploy-build-output.md

@@ -0,0 +1,115 @@
+---
+title: Build Output Configuration
+impact: HIGH
+impactDescription: Affects bundle size and load performance
+tags: deployment, build, output, optimization
+---
+
+## Build Output Configuration
+
+**Impact: HIGH (Affects bundle size and load performance)**
+
+빌드 출력을 최적화하여 번들 크기를 줄이고 로딩 성능을 개선하세요.
+
+**디렉토리 구조:**
+
+```
+dist/
+├── server.js          # 서버 엔트리포인트
+├── public/
+│   ├── islands/       # Island 컴포넌트 청크
+│   │   ├── counter-abc123.js
+│   │   └── form-def456.js
+│   ├── shared/        # 공유 청크
+│   │   └── react-vendor-xyz789.js
+│   └── assets/        # 정적 자산
+│       ├── styles.css
+│       └── images/
+└── server.js.map      # 소스맵 (프로덕션 디버깅용)
+```
+
+**청크 분할 설정:**
+
+```typescript
+// scripts/build.ts
+await Bun.build({
+  entrypoints: ["./app/**/client.tsx"],
+  outdir: "./dist/public/islands",
+  target: "browser",
+  splitting: true,        // 공유 코드 자동 분리
+  minify: true,
+  naming: {
+    chunk: "[name]-[hash].js",
+    entry: "[name]-[hash].js",
+    asset: "[name]-[hash][ext]",
+  },
+});
+```
+
+## 정적 자산 처리
+
+```typescript
+// 정적 파일 복사
+import { $ } from "bun";
+
+// public 폴더 복사
+await $`cp -r public/* dist/public/`;
+
+// CSS 최적화 (optional)
+await $`bunx lightningcss --minify public/styles.css -o dist/public/styles.css`;
+```
+
+## Gzip/Brotli 압축
+
+```typescript
+// 프로덕션 서버에서 압축
+import { gzipSync } from "bun";
+
+// 또는 빌드 시 사전 압축
+import { $ } from "bun";
+
+const files = await Array.fromAsync(
+  new Bun.Glob("dist/public/**/*.{js,css}").scan()
+);
+
+for (const file of files) {
+  const content = await Bun.file(file).arrayBuffer();
+  await Bun.write(`${file}.gz`, gzipSync(new Uint8Array(content)));
+}
+```
+
+## 빌드 매니페스트
+
+```typescript
+// 빌드 후 매니페스트 생성
+const manifest = {
+  version: process.env.BUILD_VERSION || Date.now().toString(),
+  files: {},
+};
+
+const files = await Array.fromAsync(
+  new Bun.Glob("dist/public/**/*").scan()
+);
+
+for (const file of files) {
+  const hash = Bun.hash(await Bun.file(file).arrayBuffer());
+  manifest.files[file] = hash.toString(16);
+}
+
+await Bun.write("dist/manifest.json", JSON.stringify(manifest, null, 2));
+```
+
+## 번들 크기 모니터링
+
+```bash
+# 번들 크기 리포트
+bun run scripts/bundle-size.ts
+
+# CI에서 크기 제한 체크
+if [ $(du -sb dist/public | cut -f1) -gt 1048576 ]; then
+  echo "Bundle size exceeds 1MB limit"
+  exit 1
+fi
+```
+
+Reference: [Bun Build Naming](https://bun.sh/docs/bundler#naming)