@kood/claude-code 0.3.5 → 0.3.7

package/templates/nextjs/docs/library/nextjs/server-actions.md

@@ -0,0 +1,366 @@
+# Server Actions
+
+> 타입 안전한 서버 함수 (React 19 Server Actions)
+
+---
+
+## 기본 사용법
+
+### 파일 상단 선언
+
+```typescript
+// app/actions.ts
+"use server"
+
+import { z } from "zod"
+import { revalidatePath } from "next/cache"
+
+export async function createPost(formData: FormData) {
+  const title = formData.get("title") as string
+  const content = formData.get("content") as string
+
+  const post = await prisma.post.create({
+    data: { title, content },
+  })
+
+  revalidatePath("/posts")
+  return post
+}
+```
+
+### 인라인 선언
+
+```typescript
+// app/posts/page.tsx
+export default function PostsPage() {
+  async function createPost(formData: FormData) {
+    "use server"
+
+    const title = formData.get("title") as string
+    await prisma.post.create({ data: { title } })
+  }
+
+  return <form action={createPost}>...</form>
+}
+```
+
+---
+
+## Zod 검증
+
+```typescript
+"use server"
+
+import { z } from "zod"
+
+const createPostSchema = z.object({
+  title: z.string().min(1).max(100),
+  content: z.string().min(1),
+  published: z.boolean().default(false),
+})
+
+export async function createPost(formData: FormData) {
+  const parsed = createPostSchema.parse({
+    title: formData.get("title"),
+    content: formData.get("content"),
+    published: formData.get("published") === "on",
+  })
+
+  const post = await prisma.post.create({ data: parsed })
+  revalidatePath("/posts")
+  return post
+}
+```
+
+---
+
+## 인증
+
+```typescript
+"use server"
+
+import { auth } from "@/lib/auth"
+import { redirect } from "next/navigation"
+
+export async function deletePost(id: string) {
+  const session = await auth()
+
+  if (!session?.user) {
+    redirect("/login")
+  }
+
+  await prisma.post.delete({
+    where: {
+      id,
+      userId: session.user.id, // 본인 게시물만 삭제
+    },
+  })
+
+  revalidatePath("/posts")
+}
+```
+
+---
+
+## 에러 처리
+
+```typescript
+"use server"
+
+export async function updatePost(id: string, data: PostInput) {
+  try {
+    const post = await prisma.post.update({ where: { id }, data })
+    revalidatePath(`/posts/${id}`)
+    return { success: true, post }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return { success: false, errors: error.errors }
+    }
+    return { success: false, message: "업데이트 실패" }
+  }
+}
+```
+
+---
+
+## 클라이언트에서 사용
+
+### Form Action
+
+```typescript
+"use client"
+
+import { createPost } from "@/actions/posts"
+
+export function CreatePostForm() {
+  return (
+    <form action={createPost}>
+      <input name="title" required />
+      <textarea name="content" required />
+      <button type="submit">등록</button>
+    </form>
+  )
+}
+```
+
+### TanStack Query
+
+```typescript
+"use client"
+
+import { useMutation, useQueryClient } from "@tanstack/react-query"
+import { createPost } from "@/actions/posts"
+
+export function CreatePostForm() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: async (formData: FormData) => {
+      return createPost(formData)
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["posts"] })
+    },
+  })
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault()
+        const formData = new FormData(e.currentTarget)
+        mutation.mutate(formData)
+      }}
+    >
+      <input name="title" required />
+      <button type="submit" disabled={mutation.isPending}>
+        {mutation.isPending ? "등록 중..." : "등록"}
+      </button>
+    </form>
+  )
+}
+```
+
+---
+
+## useFormState (React 19)
+
+```typescript
+"use server"
+
+export async function createPost(prevState: any, formData: FormData) {
+  const title = formData.get("title") as string
+
+  if (!title) {
+    return { error: "제목을 입력하세요" }
+  }
+
+  const post = await prisma.post.create({ data: { title } })
+  return { success: true, post }
+}
+```
+
+```typescript
+"use client"
+
+import { useFormState } from "react-dom"
+import { createPost } from "@/actions/posts"
+
+export function CreatePostForm() {
+  const [state, formAction] = useFormState(createPost, null)
+
+  return (
+    <form action={formAction}>
+      <input name="title" />
+      {state?.error && <p>{state.error}</p>}
+      <button type="submit">등록</button>
+    </form>
+  )
+}
+```
+
+---
+
+## 캐시 무효화
+
+### revalidatePath
+
+```typescript
+"use server"
+
+import { revalidatePath } from "next/cache"
+
+export async function createPost(data: PostInput) {
+  const post = await prisma.post.create({ data })
+
+  // 특정 경로 캐시 무효화
+  revalidatePath("/posts")
+  revalidatePath(`/posts/${post.id}`)
+
+  // 레이아웃 포함 모든 캐시 무효화
+  revalidatePath("/posts", "layout")
+
+  return post
+}
+```
+
+### revalidateTag
+
+```typescript
+// 데이터 페칭 시 태그 설정
+const posts = await fetch("https://api.example.com/posts", {
+  next: { tags: ["posts"] },
+})
+
+// Server Action에서 태그 무효화
+"use server"
+
+import { revalidateTag } from "next/cache"
+
+export async function createPost(data: PostInput) {
+  const post = await prisma.post.create({ data })
+  revalidateTag("posts") // "posts" 태그 캐시 무효화
+  return post
+}
+```
+
+---
+
+## redirect
+
+```typescript
+"use server"
+
+import { redirect } from "next/navigation"
+
+export async function createPost(formData: FormData) {
+  const post = await prisma.post.create({
+    data: {
+      title: formData.get("title") as string,
+    },
+  })
+
+  redirect(`/posts/${post.id}`) // 페이지 이동
+}
+```
+
+---
+
+## 파일 업로드
+
+```typescript
+"use server"
+
+import { writeFile } from "fs/promises"
+import { join } from "path"
+
+export async function uploadFile(formData: FormData) {
+  const file = formData.get("file") as File
+
+  if (!file) {
+    throw new Error("파일이 없습니다")
+  }
+
+  const bytes = await file.arrayBuffer()
+  const buffer = Buffer.from(bytes)
+
+  const path = join(process.cwd(), "public", "uploads", file.name)
+  await writeFile(path, buffer)
+
+  return { url: `/uploads/${file.name}` }
+}
+```
+
+---
+
+## 베스트 프랙티스
+
+### ✅ DO
+
+```typescript
+"use server"
+
+// 1. Zod 검증
+const schema = z.object({ title: z.string().min(1) })
+
+// 2. 인증 체크
+const session = await auth()
+if (!session) throw new Error("Unauthorized")
+
+// 3. try-catch
+try {
+  const post = await prisma.post.create({ data })
+  revalidatePath("/posts")
+  return { success: true, post }
+} catch (error) {
+  return { success: false, message: "생성 실패" }
+}
+```
+
+### ❌ DON'T
+
+```typescript
+// 1. 클라이언트 컴포넌트에서 Server Action 정의
+"use client"
+
+async function createPost() {
+  "use server" // ❌ 에러
+}
+
+// 2. 검증 없이 사용
+export async function createPost(formData: FormData) {
+  const title = formData.get("title") // ❌ 검증 누락
+  await prisma.post.create({ data: { title } })
+}
+
+// 3. try-catch 없이 사용
+export async function createPost(data: PostInput) {
+  const post = await prisma.post.create({ data }) // ❌ 에러 처리 누락
+  return post
+}
+```
+
+---
+
+## 참조
+
+- [Next.js Server Actions](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations)

package/templates/nextjs/docs/library/prisma/cloudflare-d1.md

@@ -0,0 +1,76 @@
+# Prisma - Cloudflare D1
+
+SQLite 기반 서버리스 DB. 일반 Prisma 마이그레이션과 다른 워크플로우.
+
+⚠️ 트랜잭션 미지원 | prisma migrate 불가 - wrangler 사용 | Preview 상태
+
+## 설정
+
+```prisma
+// schema.prisma
+generator client {
+  provider = "prisma-client"
+  output   = "../src/generated/prisma"
+  runtime  = "cloudflare"  // 필수
+}
+
+datasource db {
+  provider = "sqlite"
+}
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "ID" }]
+}
+```
+
+## 사용법
+
+```typescript
+import { PrismaClient } from './generated/prisma'
+import { PrismaD1 } from '@prisma/adapter-d1'
+
+export interface Env { DB: D1Database }
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const adapter = new PrismaD1(env.DB)
+    const prisma = new PrismaClient({ adapter })
+    const users = await prisma.user.findMany()
+    return new Response(JSON.stringify(users))
+  },
+}
+```
+
+## 마이그레이션 워크플로우
+
+```bash
+# 1. D1 생성
+npx wrangler d1 create my-database
+
+# 2. 마이그레이션 생성
+npx wrangler d1 migrations create my-database init
+
+# 3. SQL 생성 (초기)
+npx prisma migrate diff --from-empty --to-schema-datamodel prisma/schema.prisma --script --output prisma/migrations/0001.sql
+
+# 4. SQL 생성 (후속)
+npx prisma migrate diff --from-local-d1 --to-schema-datamodel prisma/schema.prisma --script
+
+# 5. 적용
+npx wrangler d1 migrations apply my-database --local   # 로컬
+npx wrangler d1 migrations apply my-database --remote  # 프로덕션
+
+# 6. Client 생성
+npx prisma generate
+```
+
+## 제한사항
+
+| 항목 | 일반 SQLite | D1 |
+|------|-------------|-----|
+| 마이그레이션 | prisma migrate | wrangler d1 |
+| 트랜잭션 | ✅ | ❌ |
+| 접속 | 직접 | HTTP 어댑터 |

package/templates/nextjs/docs/library/prisma/config.md

@@ -0,0 +1,77 @@
+# Prisma - Config 파일
+
+Prisma v7 `prisma.config.ts` 설정.
+
+## Multi-File 스키마 (필수)
+
+```typescript
+// prisma.config.ts
+import 'dotenv/config'
+import path from 'node:path'
+import { defineConfig, env } from 'prisma/config'
+
+export default defineConfig({
+  schema: path.join('prisma', 'schema'),  // 폴더 경로!
+  migrations: {
+    path: 'prisma/migrations',
+    seed: 'tsx prisma/seed.ts',
+  },
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+})
+```
+
+## 폴더 구조
+
+```
+프로젝트/
+├── prisma.config.ts
+├── prisma/
+│   ├── schema/
+│   │   ├── +base.prisma   # datasource, generator
+│   │   ├── +enum.prisma   # enum 정의
+│   │   └── user.prisma    # 모델
+│   └── migrations/
+```
+
+## +base.prisma
+
+```prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client"
+  output   = "../../generated/prisma"
+}
+```
+
+## 설정 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `schema` | 스키마 폴더 경로 |
+| `datasource.url` | DB URL (필수) |
+| `datasource.shadowDatabaseUrl` | Shadow DB URL |
+| `migrations.path` | 마이그레이션 폴더 |
+| `migrations.seed` | 시드 명령어 |
+
+## 시드 파일
+
+```typescript
+// prisma/seed.ts
+import { PrismaClient } from '../generated/prisma'
+
+const prisma = new PrismaClient()
+
+async function main() {
+  await prisma.user.create({
+    data: { email: 'admin@example.com', name: '관리자', role: 'ADMIN' },
+  })
+}
+
+main().catch(console.error).finally(() => prisma.$disconnect())
+```

package/templates/nextjs/docs/library/prisma/crud.md

@@ -0,0 +1,90 @@
+# Prisma - CRUD 작업
+
+## Create
+
+```typescript
+// 단일
+const user = await prisma.user.create({
+  data: { email: 'alice@prisma.io', name: 'Alice' },
+})
+
+// 관계 포함
+const user = await prisma.user.create({
+  data: {
+    email: 'bob@prisma.io',
+    posts: { create: [{ title: 'Hello' }, { title: 'World' }] },
+  },
+  include: { posts: true },
+})
+
+// connectOrCreate
+posts: { create: [{
+  title: 'Post',
+  categories: { connectOrCreate: [{ create: { name: 'Tech' }, where: { name: 'Tech' } }] },
+}]}
+```
+
+## Read
+
+```typescript
+// 단일
+const user = await prisma.user.findUnique({ where: { email } })
+
+// 다중
+const users = await prisma.user.findMany({ where: { name: 'Alice' } })
+
+// 관계 포함
+const users = await prisma.user.findMany({ where: { role: 'ADMIN' }, include: { posts: true } })
+
+// 필드 선택
+const user = await prisma.user.findUnique({
+  where: { email },
+  select: { email: true, posts: { select: { title: true } } },
+})
+
+// 관계로 필터
+const users = await prisma.user.findMany({
+  where: { posts: { some: { published: false } } },
+})
+```
+
+## Update
+
+```typescript
+// 단일
+const user = await prisma.user.update({ where: { id }, data: { name: 'Updated' } })
+
+// 다중
+await prisma.user.updateMany({ where: { role: 'USER' }, data: { role: 'ADMIN' } })
+
+// Upsert
+const user = await prisma.user.upsert({
+  where: { email },
+  update: { name: 'Updated' },
+  create: { email, name: 'New' },
+})
+```
+
+## Delete
+
+```typescript
+await prisma.user.delete({ where: { id } })
+await prisma.user.deleteMany({})  // 전체
+await prisma.post.deleteMany({ where: { published: false } })  // 조건부
+```
+
+## 필터 연산자
+
+```typescript
+// 문자열
+{ contains: 'prisma', startsWith: 'A', endsWith: 'io' }
+
+// 숫자
+{ gt: 18, gte: 18, lt: 65, lte: 65 }
+
+// 배열
+{ in: [1, 2, 3], notIn: [4, 5] }
+
+// 논리
+{ OR: [...], AND: [...], NOT: {...} }
+```

package/templates/nextjs/docs/library/prisma/index.md

@@ -0,0 +1,73 @@
+# Prisma
+
+> **Version**: 7.x | Node.js/TypeScript ORM
+
+@setup.md
+@config.md
+@schema.md
+@crud.md
+@relations.md
+@transactions.md
+@cloudflare-d1.md
+
+---
+
+## Quick Reference
+
+```typescript
+import { PrismaClient } from './generated/prisma'  // v7 경로!
+export const prisma = new PrismaClient()
+
+// CRUD
+const users = await prisma.user.findMany()
+const user = await prisma.user.create({ data: { email, name } })
+const updated = await prisma.user.update({ where: { id }, data: { name } })
+const deleted = await prisma.user.delete({ where: { id } })
+
+// 관계 포함
+const userWithPosts = await prisma.user.findUnique({
+  where: { id },
+  include: { posts: true },
+})
+```
+
+### v7 schema.prisma (⚠️ 중요)
+
+```prisma
+generator client {
+  provider = "prisma-client"        // v7! (prisma-client-js 아님)
+  output   = "../generated/prisma"  // output 필수!
+}
+```
+
+### ⛔ Claude Code 금지
+
+| 금지 사항 |
+|----------|
+| prisma db push 자동 실행 |
+| prisma migrate 자동 실행 |
+| prisma generate 자동 실행 |
+| schema.prisma 임의 변경 |
+
+---
+
+## Prisma Client 설정
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from './generated/prisma'
+
+const globalForPrisma = globalThis as unknown as { prisma: PrismaClient | undefined }
+export const prisma = globalForPrisma.prisma ?? new PrismaClient({ log: ['query'] })
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma
+```
+
+## 마이그레이션 명령어
+
+```bash
+npx prisma migrate dev --name init   # 개발 마이그레이션
+npx prisma migrate deploy            # 프로덕션 마이그레이션
+npx prisma db push                   # 스키마 동기화 (개발용)
+npx prisma generate                  # Client 생성
+npx prisma studio                    # GUI
+```