@kood/claude-code 0.3.8 → 0.3.10

package/templates/npx/CLAUDE.md

@@ -48,6 +48,7 @@
 | Task | Required Actions |
 |------|-----------------|
 | **Before Starting** | Read relevant docs (Commander → commander, Files → fs-extra) |
+| **Document Search** | Use serena mcp (document indexing/search, context length optimization) |
 | **Console Output** | Use logger functions (info/success/error/warn) |
 | **File Operations** | Async API (`fs-extra`), `path.join` for paths |
 | **Error Handling** | try-catch + `process.exit(1)`, clear error messages to users |

package/templates/tanstack-start/CLAUDE.md

@@ -54,6 +54,7 @@
 | Task | Required Actions |
 |------|-----------------|
 | **Before Starting** | Read related docs (UI → design, API → tanstack-start, DB → prisma, Auth → better-auth) |
+| **Document Search** | Use serena mcp (document indexing/search, context length optimization) |
 | **Code Search** | Use ast-grep (function/component/pattern search) |
 | **Complex Tasks** | Sequential Thinking MCP (5+ step tasks) |
 | **Large Changes** | gemini-review (3+ file changes, architecture decisions) |

package/templates/tanstack-start/docs/library/better-auth/index.md

@@ -1,10 +1,43 @@
 # Better Auth
 
-> TypeScript Authentication Library
+> v1.x | TypeScript Authentication Framework
+
+<context>
+
+**Purpose:** Framework-agnostic authentication and authorization for TypeScript
+**Features:** Email/Password, Social OAuth, 2FA, Passkeys, Multi-session, SSO
+
+</context>
+
+---
+
+<forbidden>
+
+| 분류 | 금지 |
+|------|------|
+| **보안** | 하드코딩된 시크릿, HTTP 프로덕션 배포 |
+| **클라이언트** | 직접 세션 조작, 토큰 localStorage 저장 |
+| **서버** | `authClient` 사용 (서버는 `auth.api.*`) |
+| **설정** | 절대 경로 하드코딩 (환경변수 사용) |
+
+</forbidden>
 
 ---
 
-<quick_start>
+<required>
+
+| 분류 | 필수 |
+|------|------|
+| **환경변수** | `BETTER_AUTH_SECRET` (32+ chars), `BETTER_AUTH_URL` |
+| **서버** | `auth.api.getSession()` 사용 |
+| **클라이언트** | `authClient.*` 메서드 사용 |
+| **프로덕션** | HTTPS, 환경별 `baseURL` 설정 |
+
+</required>
+
+---
+
+<installation>
 
 ## Installation
 
@@ -12,6 +45,20 @@
 npm install better-auth
 ```
 
+## Environment Variables
+
+```bash
+# .env
+BETTER_AUTH_SECRET="$(openssl rand -base64 32)"
+BETTER_AUTH_URL="http://localhost:3000"
+```
+
+</installation>
+
+---
+
+<setup>
+
 ## Minimal Setup
 
 ```typescript
@@ -43,35 +90,71 @@ export const GET = async ({ request }: { request: Request }) => auth.handler(req
 export const POST = async ({ request }: { request: Request }) => auth.handler(request)
 ```
 
-</quick_start>
+## Database Adapters
+
+| Adapter | Import | Provider |
+|---------|--------|----------|
+| **Prisma** | `better-auth/adapters/prisma` | `postgresql`, `mysql`, `sqlite` |
+| **Drizzle** | `better-auth/adapters/drizzle` | `pg`, `mysql2`, `better-sqlite3` |
+| **Kysely** | `better-auth/adapters/kysely` | dialect 기반 |
+
+## Config Options
+
+| 옵션 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `database` | `Adapter` | 필수 | DB 어댑터 |
+| `baseURL` | `string` | `http://localhost:3000` | 앱 URL |
+| `basePath` | `string` | `/api/auth` | Auth 경로 |
+| `secret` | `string` | 환경변수 | JWT 시크릿 |
+| `trustedOrigins` | `string[]` | `[]` | CORS 허용 오리진 |
+
+</setup>
 
 ---
 
-<setup>
+<auth_methods>
 
-## Database Adapters
+## Email & Password
 
-| Adapter | Import | Provider |
-|---------|--------|----------|
-| Prisma | `better-auth/adapters/prisma` | `postgresql`, `mysql`, `sqlite` |
-| Drizzle | `better-auth/adapters/drizzle` | `pg`, `mysql2`, `better-sqlite3` |
-| Kysely | `better-auth/adapters/kysely` | dialect-based |
+```typescript
+// ✅ 서버 설정
+export const auth = betterAuth({
+  emailAndPassword: {
+    enabled: true,
+    requireEmailVerification: false,
+    sendResetPassword: async ({ user, url }) => {
+      await sendEmail({
+        to: user.email,
+        subject: 'Reset Password',
+        html: `<a href="${url}">Reset</a>`,
+      })
+    },
+  },
+})
 
-## Auth Config
+// ✅ 회원가입
+await authClient.signUp.email({
+  email: 'user@example.com',
+  password: 'password123',
+  name: 'User Name',
+})
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `database` | `Adapter` | Required | DB adapter |
-| `baseURL` | `string` | `http://localhost:3000` | App URL |
-| `basePath` | `string` | `/api/auth` | Auth path |
-| `secret` | `string` | Environment variable | JWT secret |
-| `trustedOrigins` | `string[]` | `[]` | CORS allowed origins |
+// ✅ 로그인
+await authClient.signIn.email({
+  email: 'user@example.com',
+  password: 'password123',
+})
 
-## Social Providers
+// ✅ 비밀번호 재설정
+await authClient.forgetPassword({ email: 'user@example.com' })
+await authClient.resetPassword({ token, password: 'newpassword' })
+```
+
+## Social OAuth
 
 ```typescript
+// ✅ 서버 설정
 export const auth = betterAuth({
-  database: prismaAdapter(prisma),
   socialProviders: {
     google: {
       clientId: process.env.GOOGLE_CLIENT_ID!,
@@ -83,23 +166,70 @@ export const auth = betterAuth({
     },
   },
 })
+
+// ✅ 클라이언트 로그인
+await authClient.signIn.social({ provider: 'google', callbackURL: '/dashboard' })
+await authClient.signIn.social({ provider: 'github', callbackURL: '/dashboard' })
 ```
 
-## Email & Password
+## Two-Factor Authentication
 
 ```typescript
+// ✅ 서버 플러그인
+import { twoFactor } from 'better-auth/plugins'
+
 export const auth = betterAuth({
-  emailAndPassword: {
-    enabled: true,
-    requireEmailVerification: false,
-    sendResetPassword: async ({ user, url }) => {
-      await sendEmail({ to: user.email, subject: 'Reset Password', html: `<a href="${url}">Reset</a>` })
-    },
-  },
+  plugins: [
+    twoFactor({
+      issuer: 'My App',
+      otpOptions: {
+        async sendOTP({ user, otp }) {
+          await sendEmail({
+            to: user.email,
+            subject: 'Your OTP Code',
+            html: `Your code: ${otp}`,
+          })
+        },
+        period: 300,  // 5분
+        length: 6,    // 6자리
+      },
+      backupCodeLength: 10,
+      backupCodeCount: 10,
+    }),
+  ],
+})
+
+// ✅ 클라이언트 플러그인
+import { twoFactorClient } from 'better-auth/client/plugins'
+
+export const authClient = createAuthClient({
+  plugins: [
+    twoFactorClient({
+      twoFactorPage: '/two-factor',
+    }),
+  ],
 })
+
+// ✅ TOTP 활성화
+const { data } = await authClient.twoFactor.enable({ password: 'current-password' })
+// → { totpURI: 'otpauth://...', backupCodes: ['ABCD-1234', ...] }
+
+// ✅ TOTP 검증
+await authClient.twoFactor.verifyTotp({ code: '123456' })
+
+// ✅ OTP 전송/검증
+await authClient.twoFactor.sendOtp()
+await authClient.twoFactor.verifyOtp({ code: '123456' })
+
+// ✅ 백업 코드
+await authClient.twoFactor.useBackupCode({ code: 'ABCD-1234' })
+await authClient.twoFactor.regenerateBackupCodes({ password: 'current-password' })
+
+// ✅ 2FA 비활성화
+await authClient.twoFactor.disable({ password: 'current-password' })
 ```
 
-</setup>
+</auth_methods>
 
 ---
 
@@ -107,22 +237,22 @@ export const auth = betterAuth({
 
 ## Session Config
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `expiresIn` | `number` | `604800` (7 days) | Session expiration time (seconds) |
-| `updateAge` | `number` | `86400` (1 day) | Session renewal period (seconds) |
-| `cookieCache.enabled` | `boolean` | `true` | Enable cookie cache |
-| `cookieCache.maxAge` | `number` | `300` (5 min) | Cache validity time (seconds) |
-| `cookieCache.strategy` | `'compact' \| 'jwt' \| 'jwe'` | `'compact'` | Cache strategy |
+| 옵션 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `expiresIn` | `number` | `604800` (7일) | 세션 만료 (초) |
+| `updateAge` | `number` | `86400` (1일) | 세션 갱신 주기 (초) |
+| `cookieCache.enabled` | `boolean` | `true` | 쿠키 캐시 활성화 |
+| `cookieCache.maxAge` | `number` | `300` (5분) | 캐시 유효 시간 (초) |
+| `cookieCache.strategy` | `'compact' \| 'jwt' \| 'jwe'` | `'compact'` | 캐시 전략 |
 
 ```typescript
 export const auth = betterAuth({
   session: {
-    expiresIn: 604800, // 7 days
-    updateAge: 86400,  // Renew every day
+    expiresIn: 604800,
+    updateAge: 86400,
     cookieCache: {
       enabled: true,
-      maxAge: 300,     // 5 minutes
+      maxAge: 300,
       strategy: 'compact',
     },
   },
@@ -131,22 +261,27 @@ export const auth = betterAuth({
 
 ## Session Methods
 
+| 환경 | 메서드 |
+|------|--------|
+| **클라이언트** | `authClient.getSession()` |
+| **서버** | `auth.api.getSession({ headers })` |
+
 ```typescript
-// ✅ Client
+// ✅ 클라이언트
 const session = await authClient.getSession()
 const session = await authClient.getSession({ query: { disableCookieCache: true } })
 
-// ✅ Server (TanStack Start)
+// ✅ 서버 (TanStack Start)
 export const getSession = createServerFn({ method: 'GET' })
   .handler(async ({ request }) => {
     const session = await auth.api.getSession({ headers: request.headers })
     return session
   })
 
-// ✅ Update session
+// ✅ 세션 업데이트
 await authClient.updateUser({ name: 'New Name' })
 
-// ✅ Sign out
+// ✅ 로그아웃
 await authClient.signOut()
 ```
 
@@ -183,148 +318,39 @@ export const auth = betterAuth({
 
 ---
 
-<auth_methods>
-
-## Email/Password
-
-```typescript
-// ✅ Sign up
-await authClient.signUp.email({
-  email: 'user@example.com',
-  password: 'password123',
-  name: 'User Name',
-})
-
-// ✅ Sign in
-await authClient.signIn.email({
-  email: 'user@example.com',
-  password: 'password123',
-})
-
-// ✅ Request password reset
-await authClient.forgetPassword({ email: 'user@example.com' })
-
-// ✅ Reset password
-await authClient.resetPassword({ token, password: 'newpassword' })
-```
-
-## Social Login
-
-```typescript
-// ✅ Social sign in
-await authClient.signIn.social({ provider: 'google', callbackURL: '/dashboard' })
-await authClient.signIn.social({ provider: 'github', callbackURL: '/dashboard' })
-
-// ✅ SSO
-await authClient.signIn.sso({ providerId: 'provider-id', callbackURL: '/dashboard' })
-```
-
-## Two-Factor Authentication
-
-### Server Setup
-
-```typescript
-import { twoFactor } from 'better-auth/plugins'
-
-export const auth = betterAuth({
-  plugins: [
-    twoFactor({
-      issuer: 'My App',
-      otpOptions: {
-        async sendOTP({ user, otp }) {
-          await sendEmail({
-            to: user.email,
-            subject: 'Your OTP Code',
-            html: `Your code: ${otp}`,
-          })
-        },
-        period: 300,  // 5분
-        length: 6,    // 6자리
-      },
-      backupCodeLength: 10,
-      backupCodeCount: 10,
-    }),
-  ],
-})
-```
-
-### Client Setup
-
-```typescript
-import { twoFactorClient } from 'better-auth/client/plugins'
-
-export const authClient = createAuthClient({
-  plugins: [
-    twoFactorClient({
-      twoFactorPage: '/two-factor',
-    }),
-  ],
-})
-```
-
-### 2FA Usage
-
-```typescript
-// ✅ Enable TOTP
-const { data } = await authClient.twoFactor.enable({ password: 'current-password' })
-// data: { totpURI: 'otpauth://...', backupCodes: ['ABCD-1234', ...] }
-
-// ✅ Verify TOTP
-await authClient.twoFactor.verifyTotp({ code: '123456' })
-
-// ✅ Send OTP
-await authClient.twoFactor.sendOtp()
-
-// ✅ Verify OTP
-await authClient.twoFactor.verifyOtp({ code: '123456' })
-
-// ✅ Use backup code
-await authClient.twoFactor.useBackupCode({ code: 'ABCD-1234' })
-
-// ✅ Regenerate backup codes
-const { data } = await authClient.twoFactor.regenerateBackupCodes({ password: 'current-password' })
-
-// ✅ Disable 2FA
-await authClient.twoFactor.disable({ password: 'current-password' })
-```
-
-</auth_methods>
-
----
-
 <plugins>
 
 ## Plugin System
 
-| Plugin | Import | Features |
-|--------|--------|----------|
-| `multiSession` | `better-auth/plugins` | Multi-session management |
-| `customSession` | `better-auth/plugins` | Session field extension |
-| `twoFactor` | `better-auth/plugins` | Two-factor authentication |
-| `captcha` | `better-auth/plugins` | CAPTCHA verification |
+| Plugin | 기능 |
+|--------|------|
+| `twoFactor` | TOTP, OTP, 백업 코드 |
+| `multiSession` | 다중 세션 관리 |
+| `customSession` | 세션 필드 확장 |
+| `captcha` | reCAPTCHA 검증 |
 
 ## Multi-Session
 
 ```typescript
-// ✅ Server
+// ✅ 서버
 import { multiSession } from 'better-auth/plugins'
 
 export const auth = betterAuth({
   plugins: [
     multiSession({
-      maximumSessions: 5, // Maximum number of sessions
+      maximumSessions: 5,
     }),
   ],
 })
 
-// ✅ Client
+// ✅ 클라이언트
 import { multiSessionClient } from 'better-auth/client/plugins'
 
 export const authClient = createAuthClient({
   plugins: [multiSessionClient()],
 })
 
-// Usage
+// ✅ 사용
 const sessions = await authClient.multiSession.listSessions()
 await authClient.multiSession.revokeSession({ sessionId: 'session-id' })
 await authClient.multiSession.revokeOtherSessions()
@@ -333,7 +359,7 @@ await authClient.multiSession.revokeOtherSessions()
 ## CAPTCHA
 
 ```typescript
-// ✅ Server
+// ✅ 서버
 import { captcha } from 'better-auth/plugins'
 
 export const auth = betterAuth({
@@ -347,7 +373,7 @@ export const auth = betterAuth({
   ],
 })
 
-// ✅ Client
+// ✅ 클라이언트
 import { captchaClient } from 'better-auth/client/plugins'
 
 export const authClient = createAuthClient({
@@ -368,10 +394,24 @@ export const authClient = createAuthClient({
 ## SIWE (Ethereum)
 
 ```typescript
-// Server: siwe({ domain, uri })
-// Client:
+// ✅ 서버
+import { siwe } from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  plugins: [
+    siwe({
+      domain: 'example.com',
+      uri: 'https://example.com',
+    }),
+  ],
+})
+
+// ✅ 클라이언트
 const { data } = await authClient.siwe.getNonce()
-const message = await authClient.siwe.prepareMessage({ address: '0x...', nonce: data.nonce })
+const message = await authClient.siwe.prepareMessage({
+  address: '0x...',
+  nonce: data.nonce,
+})
 const signature = await signer.signMessage(message)
 await authClient.siwe.signIn({ message, signature })
 ```
@@ -379,7 +419,7 @@ await authClient.siwe.signIn({ message, signature })
 ## Stateless Mode
 
 ```typescript
-// ✅ Social login without DB
+// ✅ DB 없이 소셜 로그인만
 export const auth = betterAuth({
   socialProviders: {
     google: {
@@ -422,8 +462,8 @@ export const auth = betterAuth({
 
 ## TanStack Start Integration
 
-| Pattern | Purpose |
-|---------|---------|
+| 패턴 | 파일 |
+|------|------|
 | API Handler | `src/routes/api/auth/$.ts` |
 | Server Function | `createServerFn` + `auth.api.getSession` |
 | Middleware | `auth.api.getSession` + redirect |
@@ -431,7 +471,7 @@ export const auth = betterAuth({
 ### Server Function Pattern
 
 ```typescript
-// ✅ Auth check Server Function
+// ✅ 인증 체크
 export const requireAuth = createServerFn({ method: 'GET' })
   .handler(async ({ request }) => {
     const session = await auth.api.getSession({ headers: request.headers })
@@ -441,7 +481,7 @@ export const requireAuth = createServerFn({ method: 'GET' })
     return session.user
   })
 
-// ✅ Fetch protected data
+// ✅ 보호된 데이터 조회
 export const getProtectedData = createServerFn({ method: 'GET' })
   .handler(async ({ request }) => {
     const user = await requireAuth()
@@ -465,23 +505,23 @@ export const Route = createFileRoute('/dashboard')({
 
 ## Common Patterns
 
-| Action | Pattern |
-|--------|---------|
-| Sign in | `authClient.signIn.email({ email, password })` |
-| Sign up | `authClient.signUp.email({ email, password, name })` |
-| Sign out | `authClient.signOut()` |
-| Get session | `authClient.getSession()` |
-| Update user | `authClient.updateUser({ name })` |
-| Reset password | `authClient.forgetPassword({ email })` → `authClient.resetPassword({ token, password })` |
+| 작업 | 패턴 |
+|------|------|
+| 로그인 | `authClient.signIn.email({ email, password })` |
+| 회원가입 | `authClient.signUp.email({ email, password, name })` |
+| 로그아웃 | `authClient.signOut()` |
+| 세션 조회 | `authClient.getSession()` |
+| 사용자 업데이트 | `authClient.updateUser({ name })` |
+| 비밀번호 재설정 | `authClient.forgetPassword({ email })` → `authClient.resetPassword({ token, password })` |
 
 ## Do's & Don'ts
 
 | ✅ Do | ❌ Don't |
 |-------|----------|
-| Use `auth.api.getSession()` on server | Directly manipulate sessions on client |
-| Use `authClient` on client | Hardcode secrets |
-| Manage secrets via environment variables | Store session tokens in localStorage |
-| HTTPS required in production | Deploy production with HTTP |
-| Configure `baseURL` per environment | Hardcode absolute paths |
+| `auth.api.getSession()` 서버에서 사용 | 클라이언트에서 직접 세션 조작 |
+| `authClient` 클라이언트에서 사용 | 하드코딩된 시크릿 |
+| 환경변수로 시크릿 관리 | 세션 토큰 localStorage 저장 |
+| HTTPS 프로덕션 필수 | HTTP 프로덕션 배포 |
+| `baseURL` 환경별 설정 | 절대 경로 하드코딩 |
 
 </patterns>