@kood/claude-code 0.2.5 → 0.3.0

package/templates/hono/docs/guides/env-setup.md

@@ -0,0 +1,347 @@
+# 환경 변수 설정
+
+> Hono 환경 변수 관리 (Node.js, Cloudflare Workers)
+
+<instructions>
+@../library/t3-env/index.md
+</instructions>
+
+---
+
+<runtime_differences>
+
+| 런타임 | 환경 변수 접근 | 용도 |
+|--------|---------------|------|
+| **Node.js** | `process.env.*` | 일반 서버 |
+| **Cloudflare Workers** | `c.env.*` (Bindings) | Edge Runtime |
+| **Deno** | `Deno.env.get()` | Deno Runtime |
+| **Bun** | `process.env.*` | Bun Runtime |
+
+</runtime_differences>
+
+---
+
+<file_structure>
+
+## 환경 파일 구조
+
+```
+├── .env                    # 기본 (커밋 O)
+├── .env.development        # 개발 (커밋 O)
+├── .env.production         # 프로덕션 (커밋 O)
+├── .env.local              # 로컬 오버라이드 (커밋 X)
+└── src/lib/env.ts          # 검증 및 타입 (t3-env)
+```
+
+| 우선순위 | 파일 | 설명 |
+|----------|------|------|
+| 1 | `.env.{mode}.local` | 최우선 (gitignore) |
+| 2 | `.env.local` | 로컬 오버라이드 |
+| 3 | `.env.{mode}` | 환경별 설정 |
+| 4 | `.env` | 기본 설정 |
+
+</file_structure>
+
+---
+
+<patterns>
+
+## 환경 파일 예시
+
+### .env.local (gitignore, 시크릿)
+
+```env
+DATABASE_URL=postgresql://user:password@localhost:5432/myapp
+JWT_SECRET=your-super-secret-jwt-key-at-least-32-chars
+OPENAI_API_KEY=sk-xxx
+```
+
+### .env.development
+
+```env
+NODE_ENV=development
+PORT=3000
+LOG_LEVEL=debug
+```
+
+### .env.production
+
+```env
+NODE_ENV=production
+PORT=8080
+LOG_LEVEL=info
+```
+
+## Node.js 환경 변수
+
+### 타입 안전한 환경 변수 (t3-env)
+
+```typescript
+// src/lib/env.ts
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+    DATABASE_URL: z.string().url(),
+    JWT_SECRET: z.string().min(32),
+    OPENAI_API_KEY: z.string().optional(),
+    PORT: z.coerce.number().default(3000),
+  },
+
+  runtimeEnv: process.env,
+})
+```
+
+### 사용 예시
+
+```typescript
+// src/index.ts
+import { Hono } from 'hono'
+import { env } from './lib/env'
+
+const app = new Hono()
+
+app.get('/', (c) => {
+  return c.json({
+    env: env.NODE_ENV,
+    port: env.PORT,
+  })
+})
+
+export default {
+  port: env.PORT,
+  fetch: app.fetch,
+}
+```
+
+## Cloudflare Workers 환경 변수
+
+### Bindings 타입 정의
+
+```typescript
+// src/types/index.ts
+export type Bindings = {
+  DATABASE_URL: string
+  JWT_SECRET: string
+  OPENAI_API_KEY?: string
+}
+```
+
+### wrangler.toml
+
+```toml
+name = "my-hono-app"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+[vars]
+NODE_ENV = "production"
+
+# 시크릿은 wrangler secret put 명령어로 설정
+# wrangler secret put DATABASE_URL
+# wrangler secret put JWT_SECRET
+```
+
+### 사용 예시
+
+```typescript
+// src/index.ts
+import { Hono } from 'hono'
+import type { Bindings } from './types'
+
+const app = new Hono<{ Bindings: Bindings }>()
+
+app.get('/', (c) => {
+  // c.env를 통해 환경 변수 접근
+  const dbUrl = c.env.DATABASE_URL
+  const jwtSecret = c.env.JWT_SECRET
+
+  return c.json({
+    hasDb: !!dbUrl,
+    hasJwt: !!jwtSecret,
+  })
+})
+
+export default app
+```
+
+### 미들웨어에서 사용
+
+```typescript
+// src/middleware/auth.ts
+import { createMiddleware } from 'hono/factory'
+import { HTTPException } from 'hono/http-exception'
+import type { Bindings } from '@/types'
+
+type Variables = {
+  userId: string
+}
+
+export const authMiddleware = createMiddleware<{
+  Bindings: Bindings
+  Variables: Variables
+}>(async (c, next) => {
+  const token = c.req.header('Authorization')?.replace('Bearer ', '')
+  if (!token) throw new HTTPException(401, { message: 'Unauthorized' })
+
+  // JWT Secret 사용
+  const jwtSecret = c.env.JWT_SECRET
+  // JWT 검증 로직...
+
+  c.set('userId', 'user-id')
+  await next()
+})
+```
+
+## Cloudflare Workers 시크릿 설정
+
+```bash
+# 시크릿 추가
+wrangler secret put DATABASE_URL
+wrangler secret put JWT_SECRET
+
+# 시크릿 목록 확인
+wrangler secret list
+
+# 시크릿 삭제
+wrangler secret delete DATABASE_URL
+```
+
+</patterns>
+
+---
+
+<gitignore>
+
+## .gitignore
+
+```gitignore
+# 시크릿 포함 (절대 커밋 X)
+.env.local
+.env.*.local
+
+# Cloudflare Workers
+.dev.vars
+
+# 공개 설정 (커밋 O)
+!.env
+!.env.development
+!.env.production
+```
+
+</gitignore>
+
+---
+
+<typescript_types>
+
+## TypeScript 타입
+
+### Node.js
+
+```typescript
+// src/env.d.ts
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      NODE_ENV: 'development' | 'production' | 'test'
+      DATABASE_URL: string
+      JWT_SECRET: string
+      OPENAI_API_KEY?: string
+      PORT?: string
+    }
+  }
+}
+
+export {}
+```
+
+### Cloudflare Workers
+
+```typescript
+// src/types/index.ts
+export type Bindings = {
+  // Database
+  DATABASE_URL: string
+
+  // Auth
+  JWT_SECRET: string
+
+  // External APIs
+  OPENAI_API_KEY?: string
+
+  // KV Namespaces (Cloudflare)
+  MY_KV: KVNamespace
+
+  // D1 Database (Cloudflare)
+  DB: D1Database
+}
+```
+
+</typescript_types>
+
+---
+
+<best_practices>
+
+| 원칙 | 설명 |
+|------|------|
+| **시크릿 분리** | `.env.local`에만 시크릿 저장, 커밋 금지 |
+| **타입 안전성** | t3-env 또는 Zod로 검증 |
+| **기본값** | `.env`에 안전한 기본값 설정 |
+| **문서화** | `.env.example` 파일로 필수 변수 목록 제공 |
+| **런타임별 차이** | Node.js는 `process.env`, Cloudflare는 `c.env` |
+
+</best_practices>
+
+---
+
+<cloudflare_specific>
+
+## Cloudflare Workers 추가 기능
+
+### KV Namespace
+
+```typescript
+// wrangler.toml
+[[kv_namespaces]]
+binding = "MY_KV"
+id = "your-kv-id"
+
+// 사용
+app.get('/cache/:key', async (c) => {
+  const key = c.req.param('key')
+  const value = await c.env.MY_KV.get(key)
+  return c.json({ key, value })
+})
+```
+
+### D1 Database
+
+```typescript
+// wrangler.toml
+[[d1_databases]]
+binding = "DB"
+database_name = "my-database"
+database_id = "your-db-id"
+
+// 사용
+app.get('/users', async (c) => {
+  const { results } = await c.env.DB.prepare('SELECT * FROM users').all()
+  return c.json({ users: results })
+})
+```
+
+</cloudflare_specific>
+
+---
+
+<sources>
+
+- [Hono Environment Variables](https://hono.dev/guides/env)
+- [Cloudflare Workers Environment Variables](https://developers.cloudflare.com/workers/configuration/environment-variables/)
+- [t3-env Documentation](https://env.t3.gg/docs/introduction)
+
+</sources>

package/templates/hono/docs/guides/getting-started.md

@@ -0,0 +1,239 @@
+# Getting Started
+
+> Hono 프로젝트 빠른 시작
+
+<instructions>
+@conventions.md
+@env-setup.md
+@../library/hono/index.md
+</instructions>
+
+---
+
+<prerequisites>
+
+| 요구사항 | 버전 |
+|----------|------|
+| Node.js | 18+ |
+| 패키지 관리자 | npm / yarn / pnpm |
+
+</prerequisites>
+
+---
+
+<installation>
+
+## 프로젝트 생성
+
+```bash
+# npm
+npm create hono@latest my-app
+
+# 템플릿 선택
+? Which template do you want to use?
+❯ cloudflare-workers
+  nodejs
+  bun
+  deno
+
+cd my-app
+npm install
+```
+
+## 필수 패키지
+
+```bash
+# Validation (Zod 4.x)
+npm install zod @hono/zod-validator
+
+# Database (Prisma 7.x)
+npm install @prisma/client@7
+npm install -D prisma@7
+
+# Environment Variables
+npm install @t3-oss/env-core
+```
+
+</installation>
+
+---
+
+<project_setup>
+
+## 프로젝트 구조
+
+```
+src/
+├── index.ts           # App 진입점
+├── routes/
+│   ├── index.ts       # Root routes
+│   ├── users.ts       # /users/*
+│   └── posts.ts       # /posts/*
+├── middleware/
+│   ├── auth.ts
+│   └── logger.ts
+├── services/
+│   ├── user.ts
+│   └── post.ts
+├── lib/
+│   ├── prisma.ts
+│   └── env.ts
+└── types/
+    └── index.ts
+```
+
+## App 설정
+
+```typescript
+// src/index.ts
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+import { logger } from 'hono/logger'
+import { HTTPException } from 'hono/http-exception'
+
+import users from './routes/users'
+import posts from './routes/posts'
+
+type Bindings = {
+  DATABASE_URL: string
+  JWT_SECRET: string
+}
+
+const app = new Hono<{ Bindings: Bindings }>()
+
+// 미들웨어
+app.use('*', logger())
+app.use('*', cors())
+
+// 라우트
+app.route('/users', users)
+app.route('/posts', posts)
+
+// 에러 핸들러
+app.onError((err, c) => {
+  if (err instanceof HTTPException) {
+    return c.json({ error: err.message }, err.status)
+  }
+  console.error(err)
+  return c.json({ error: 'Internal Server Error' }, 500)
+})
+
+app.notFound((c) => c.json({ error: 'Not Found' }, 404))
+
+export default app
+```
+
+## 라우트 예시
+
+```typescript
+// src/routes/users.ts
+import { Hono } from 'hono'
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+import { HTTPException } from 'hono/http-exception'
+
+const users = new Hono()
+
+// GET /users
+users.get('/', async (c) => {
+  const users = [
+    { id: '1', name: 'Alice' },
+    { id: '2', name: 'Bob' },
+  ]
+  return c.json({ users })
+})
+
+// GET /users/:id
+users.get('/:id', async (c) => {
+  const id = c.req.param('id')
+  const user = { id, name: 'Alice' }
+
+  if (!user) {
+    throw new HTTPException(404, { message: 'User not found' })
+  }
+
+  return c.json({ user })
+})
+
+// POST /users
+const createUserSchema = z.object({
+  name: z.string().min(1).trim(),
+  email: z.email(),
+})
+
+users.post('/', zValidator('json', createUserSchema), async (c) => {
+  const data = c.req.valid('json')
+  const user = { id: '3', ...data }
+
+  return c.json({ user }, 201)
+})
+
+export default users
+```
+
+## 미들웨어 예시
+
+```typescript
+// src/middleware/auth.ts
+import { createMiddleware } from 'hono/factory'
+import { HTTPException } from 'hono/http-exception'
+
+type Variables = {
+  userId: string
+}
+
+export const authMiddleware = createMiddleware<{ Variables: Variables }>(
+  async (c, next) => {
+    const token = c.req.header('Authorization')?.replace('Bearer ', '')
+
+    if (!token) {
+      throw new HTTPException(401, { message: 'Unauthorized' })
+    }
+
+    // JWT 검증 로직
+    // const decoded = await verifyJWT(token)
+
+    c.set('userId', 'user-id')
+    await next()
+  }
+)
+```
+
+</project_setup>
+
+---
+
+<commands>
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | 개발 서버 시작 |
+| `npm run build` | 프로덕션 빌드 |
+| `npm start` | 프로덕션 서버 실행 |
+| `npm run deploy` | 배포 (Cloudflare Workers 등) |
+
+</commands>
+
+---
+
+<next_steps>
+
+| 문서 | 내용 |
+|------|------|
+| [conventions.md](./conventions.md) | 코드 컨벤션, 파일명 규칙 |
+| [env-setup.md](./env-setup.md) | 환경 변수 설정 |
+| [../library/hono/](../library/hono/) | Hono API 상세 가이드 |
+| [../library/prisma/](../library/prisma/) | Prisma ORM 사용법 |
+| [../deployment/](../deployment/) | 배포 가이드 |
+
+</next_steps>
+
+---
+
+<sources>
+
+- [Hono Documentation](https://hono.dev/)
+- [Hono Getting Started](https://hono.dev/getting-started/basic)
+- [Hono Examples](https://github.com/honojs/hono/tree/main/examples)
+
+</sources>

package/templates/hono/docs/library/hono/error-handling.md

@@ -1,8 +1,8 @@
 # Hono 에러 처리
 
-> HTTPException과 onError를 사용한 체계적인 에러 관리
+> HTTPException과 onError로 체계적 에러 관리
 
----
+<patterns>
 
 ## HTTPException
 
@@ -20,21 +20,7 @@ app.get('/users/:id', async (c) => {
 })
 ```
 
-### 일반적인 상태 코드
-
-```typescript
-throw new HTTPException(400, { message: 'Invalid input' })      // Bad Request
-throw new HTTPException(401, { message: 'Unauthorized' })       // 인증 필요
-throw new HTTPException(403, { message: 'Access denied' })      // 권한 없음
-throw new HTTPException(404, { message: 'Not found' })          // 리소스 없음
-throw new HTTPException(409, { message: 'Already exists' })     // 충돌
-throw new HTTPException(422, { message: 'Validation failed' })  // 검증 실패
-throw new HTTPException(429, { message: 'Rate limit exceeded' })// 요청 제한
-```
-
----
-
-## 글로벌 에러 핸들러
+## 글로벌 핸들러
 
 ```typescript
 import { Hono } from 'hono'
@@ -57,9 +43,7 @@ app.notFound((c) => {
 })
 ```
 
----
-
-## 상세 에러 응답
+## 상세 응답
 
 ```typescript
 app.onError((err, c) => {
@@ -85,13 +69,10 @@ app.onError((err, c) => {
 })
 ```
 
----
-
 ## 커스텀 에러 클래스
 
-### lib/errors.ts
-
 ```typescript
+// lib/errors.ts
 import { HTTPException } from 'hono/http-exception'
 
 export class NotFoundError extends HTTPException {
@@ -113,9 +94,8 @@ export class ConflictError extends HTTPException {
 }
 ```
 
-### 사용
-
 ```typescript
+// 사용
 import { NotFoundError, ConflictError } from '@/lib/errors'
 
 app.get('/users/:id', async (c) => {
@@ -131,9 +111,20 @@ app.post('/users', async (c) => {
 })
 ```
 
+</patterns>
+
 ---
 
-## 관련 문서
+<status_codes>
+
+| 코드 | 사용 |
+|-----|------|
+| 400 | Invalid input |
+| 401 | Unauthorized (인증 필요) |
+| 403 | Access denied (권한 없음) |
+| 404 | Not found |
+| 409 | Already exists (충돌) |
+| 422 | Validation failed |
+| 429 | Rate limit exceeded |
 
-- [기본 사용법](./index.md)
-- [미들웨어](./middleware.md)
+</status_codes>