@kood/claude-code 0.3.6 → 0.3.8

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

@@ -0,0 +1,366 @@
+# Server Actions
+
+> Type-safe server functions (React 19 Server Actions)
+
+---
+
+## Basic Usage
+
+### File-level Declaration
+
+```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
+}
+```
+
+### Inline Declaration
+
+```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 Validation
+
+```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
+}
+```
+
+---
+
+## Authentication
+
+```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, // Delete only own posts
+    },
+  })
+
+  revalidatePath("/posts")
+}
+```
+
+---
+
+## Error Handling
+
+```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: "Update failed" }
+  }
+}
+```
+
+---
+
+## Client Usage
+
+### 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">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 ? "Submitting..." : "Submit"}
+      </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: "Please enter a title" }
+  }
+
+  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">Submit</button>
+    </form>
+  )
+}
+```
+
+---
+
+## Cache Invalidation
+
+### revalidatePath
+
+```typescript
+"use server"
+
+import { revalidatePath } from "next/cache"
+
+export async function createPost(data: PostInput) {
+  const post = await prisma.post.create({ data })
+
+  // Invalidate specific path cache
+  revalidatePath("/posts")
+  revalidatePath(`/posts/${post.id}`)
+
+  // Invalidate all caches including layouts
+  revalidatePath("/posts", "layout")
+
+  return post
+}
+```
+
+### revalidateTag
+
+```typescript
+// Set tag when fetching data
+const posts = await fetch("https://api.example.com/posts", {
+  next: { tags: ["posts"] },
+})
+
+// Invalidate tag in Server Action
+"use server"
+
+import { revalidateTag } from "next/cache"
+
+export async function createPost(data: PostInput) {
+  const post = await prisma.post.create({ data })
+  revalidateTag("posts") // Invalidate "posts" tag cache
+  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}`) // Navigate to page
+}
+```
+
+---
+
+## File Upload
+
+```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("No file provided")
+  }
+
+  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}` }
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+```typescript
+"use server"
+
+// 1. Zod validation
+const schema = z.object({ title: z.string().min(1) })
+
+// 2. Authentication check
+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: "Creation failed" }
+}
+```
+
+### ❌ DON'T
+
+```typescript
+// 1. Defining Server Action in Client Component
+"use client"
+
+async function createPost() {
+  "use server" // ❌ Error
+}
+
+// 2. Using without validation
+export async function createPost(formData: FormData) {
+  const title = formData.get("title") // ❌ Missing validation
+  await prisma.post.create({ data: { title } })
+}
+
+// 3. Using without try-catch
+export async function createPost(data: PostInput) {
+  const post = await prisma.post.create({ data }) // ❌ Missing error handling
+  return post
+}
+```
+
+---
+
+## References
+
+- [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-based serverless database. Different workflow from standard Prisma migrations.
+
+⚠️ No transaction support | Cannot use prisma migrate - use wrangler instead | Preview status
+
+## Setup
+
+```prisma
+// schema.prisma
+generator client {
+  provider = "prisma-client"
+  output   = "../src/generated/prisma"
+  runtime  = "cloudflare"  // required
+}
+
+datasource db {
+  provider = "sqlite"
+}
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "ID" }]
+}
+```
+
+## Usage
+
+```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))
+  },
+}
+```
+
+## Migration Workflow
+
+```bash
+# 1. Create D1
+npx wrangler d1 create my-database
+
+# 2. Create migration
+npx wrangler d1 migrations create my-database init
+
+# 3. Generate SQL (initial)
+npx prisma migrate diff --from-empty --to-schema-datamodel prisma/schema.prisma --script --output prisma/migrations/0001.sql
+
+# 4. Generate SQL (subsequent)
+npx prisma migrate diff --from-local-d1 --to-schema-datamodel prisma/schema.prisma --script
+
+# 5. Apply
+npx wrangler d1 migrations apply my-database --local   # local
+npx wrangler d1 migrations apply my-database --remote  # production
+
+# 6. Generate client
+npx prisma generate
+```
+
+## Limitations
+
+| Feature | Regular SQLite | D1 |
+|---------|----------------|-----|
+| Migration | prisma migrate | wrangler d1 |
+| Transaction | ✅ | ❌ |
+| Connection | Direct | HTTP adapter |

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

@@ -0,0 +1,77 @@
+# Prisma - Config File
+
+Prisma v7 `prisma.config.ts` configuration.
+
+## Multi-File Schema (Required)
+
+```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'),  // folder path!
+  migrations: {
+    path: 'prisma/migrations',
+    seed: 'tsx prisma/seed.ts',
+  },
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+})
+```
+
+## Folder Structure
+
+```
+project/
+├── prisma.config.ts
+├── prisma/
+│   ├── schema/
+│   │   ├── +base.prisma   # datasource, generator
+│   │   ├── +enum.prisma   # enum definitions
+│   │   └── user.prisma    # models
+│   └── migrations/
+```
+
+## +base.prisma
+
+```prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client"
+  output   = "../../generated/prisma"
+}
+```
+
+## Configuration Options
+
+| Option | Description |
+|--------|-------------|
+| `schema` | Schema folder path |
+| `datasource.url` | Database URL (required) |
+| `datasource.shadowDatabaseUrl` | Shadow database URL |
+| `migrations.path` | Migrations folder |
+| `migrations.seed` | Seed command |
+
+## Seed File
+
+```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: 'Admin', role: 'ADMIN' },
+  })
+}
+
+main().catch(console.error).finally(() => prisma.$disconnect())
+```

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

@@ -0,0 +1,90 @@
+# Prisma - CRUD Operations
+
+## Create
+
+```typescript
+// Single
+const user = await prisma.user.create({
+  data: { email: 'alice@prisma.io', name: 'Alice' },
+})
+
+// With relations
+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
+// Single
+const user = await prisma.user.findUnique({ where: { email } })
+
+// Multiple
+const users = await prisma.user.findMany({ where: { name: 'Alice' } })
+
+// With relations
+const users = await prisma.user.findMany({ where: { role: 'ADMIN' }, include: { posts: true } })
+
+// Select fields
+const user = await prisma.user.findUnique({
+  where: { email },
+  select: { email: true, posts: { select: { title: true } } },
+})
+
+// Filter by relation
+const users = await prisma.user.findMany({
+  where: { posts: { some: { published: false } } },
+})
+```
+
+## Update
+
+```typescript
+// Single
+const user = await prisma.user.update({ where: { id }, data: { name: 'Updated' } })
+
+// Multiple
+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({})  // all
+await prisma.post.deleteMany({ where: { published: false } })  // conditional
+```
+
+## Filter Operators
+
+```typescript
+// String
+{ contains: 'prisma', startsWith: 'A', endsWith: 'io' }
+
+// Number
+{ gt: 18, gte: 18, lt: 65, lte: 65 }
+
+// Array
+{ in: [1, 2, 3], notIn: [4, 5] }
+
+// Logical
+{ 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 path!
+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 } })
+
+// With relations
+const userWithPosts = await prisma.user.findUnique({
+  where: { id },
+  include: { posts: true },
+})
+```
+
+### v7 schema.prisma (⚠️ Important)
+
+```prisma
+generator client {
+  provider = "prisma-client"        // v7! (not prisma-client-js)
+  output   = "../generated/prisma"  // output required!
+}
+```
+
+### ⛔ Claude Code Forbidden
+
+| Forbidden Actions |
+|-------------------|
+| Auto-running prisma db push |
+| Auto-running prisma migrate |
+| Auto-running prisma generate |
+| Unauthorized schema.prisma modifications |
+
+---
+
+## Prisma Client Setup
+
+```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
+```
+
+## Migration Commands
+
+```bash
+npx prisma migrate dev --name init   # development migration
+npx prisma migrate deploy            # production migration
+npx prisma db push                   # schema sync (dev only)
+npx prisma generate                  # generate client
+npx prisma studio                    # GUI
+```