@kood/claude-code 0.2.5 → 0.3.0

package/templates/hono/docs/library/t3-env/index.md

@@ -0,0 +1,374 @@
+# t3-env - Type-Safe Environment Variables
+
+> Zod 기반 타입 안전 환경 변수 관리
+
+<context>
+
+**용도:** 서버 환경 변수 검증, 런타임 타입 안전성
+
+**특징:**
+- Zod 스키마로 검증 + 타입 추론
+- Transform & Default 값 지원
+- 런타임 검증
+- 프레임워크 무관
+
+</context>
+
+---
+
+<forbidden>
+
+| 분류 | 금지 |
+|------|------|
+| **직접 접근** | `process.env` 직접 사용 (env 객체 필수) |
+| **타입** | any 타입으로 env 변수 접근 |
+| **검증 우회** | 스키마 정의 없이 환경 변수 사용 |
+
+</forbidden>
+
+---
+
+<required>
+
+| 분류 | 필수 |
+|------|------|
+| **설치** | `@t3-oss/env-core zod` |
+| **구조** | `src/env.ts` 파일 생성 |
+| **Import** | `import { env } from '@/env'` |
+
+</required>
+
+---
+
+<setup>
+
+## Installation
+
+```bash
+npm install @t3-oss/env-core zod
+```
+
+## Basic Setup
+
+`src/env.ts`:
+
+```typescript
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    // Database
+    DATABASE_URL: z.url(),
+
+    // API Keys
+    OPENAI_API_KEY: z.string().min(1),
+
+    // App Config
+    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+    PORT: z.coerce.number().positive().default(3000),
+  },
+
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+})
+```
+
+</setup>
+
+---
+
+<patterns>
+
+## Common Patterns
+
+### Hono App
+
+```typescript
+// src/index.ts
+import { Hono } from 'hono'
+import { env } from '@/env'
+
+const app = new Hono()
+
+app.get('/health', (c) => {
+  return c.json({
+    status: 'ok',
+    env: env.NODE_ENV,
+    //        ^? "development" | "production" | "test"
+  })
+})
+
+export default {
+  port: env.PORT,
+  //         ^? number
+  fetch: app.fetch,
+}
+```
+
+### Database Connection
+
+```typescript
+import { PrismaClient } from '@prisma/client'
+import { env } from '@/env'
+
+export const prisma = new PrismaClient({
+  datasourceUrl: env.DATABASE_URL,
+  //                  ^? string (타입 안전)
+})
+```
+
+### API Routes
+
+```typescript
+import { Hono } from 'hono'
+import { env } from '@/env'
+
+const api = new Hono()
+
+api.post('/ai/generate', async (c) => {
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    headers: {
+      Authorization: `Bearer ${env.OPENAI_API_KEY}`,
+      //                         ^? string
+    },
+  })
+  return c.json(await response.json())
+})
+```
+
+### Environment-Specific Defaults
+
+```typescript
+server: {
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  ENABLE_CORS: z.coerce.boolean().default(true),
+}
+```
+
+### Transform Values
+
+```typescript
+server: {
+  PORT: z.string().transform((val) => parseInt(val, 10)).pipe(z.number().positive()),
+  MAX_CONNECTIONS: z.coerce.number().default(10),
+  RATE_LIMIT: z.coerce.number().max(1000),
+}
+```
+
+</patterns>
+
+---
+
+<examples>
+
+## Real-World Examples
+
+### Database + Auth
+
+```typescript
+// src/env.ts
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.url(),
+    DIRECT_URL: z.url().optional(), // Prisma connection pooling
+
+    JWT_SECRET: z.string().min(32),
+    JWT_EXPIRES_IN: z.string().default('7d'),
+
+    BCRYPT_ROUNDS: z.coerce.number().min(10).default(12),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+})
+```
+
+### API Integration
+
+```typescript
+// src/env.ts
+export const env = createEnv({
+  server: {
+    OPENAI_API_KEY: z.string().min(1),
+    STRIPE_SECRET_KEY: z.string().min(1),
+    STRIPE_WEBHOOK_SECRET: z.string().min(1),
+
+    RESEND_API_KEY: z.string().min(1),
+    FROM_EMAIL: z.email().default('noreply@example.com'),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+})
+```
+
+### Multi-Environment
+
+```typescript
+// src/env.ts
+export const env = createEnv({
+  server: {
+    NODE_ENV: z.enum(['development', 'production', 'test']),
+    PORT: z.coerce.number().positive().default(3000),
+
+    DATABASE_URL: z.url(),
+    REDIS_URL: z.url().optional(), // Production only
+
+    CORS_ORIGIN: z.string().url().default('http://localhost:5173'),
+    ENABLE_LOGGING: z.coerce.boolean().default(true),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+})
+```
+
+### Cloudflare Workers
+
+```typescript
+// src/env.ts
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const createWorkerEnv = (bindings: Record<string, unknown>) =>
+  createEnv({
+    server: {
+      DATABASE_URL: z.url(),
+      KV_NAMESPACE: z.unknown(), // Cloudflare KV
+      R2_BUCKET: z.unknown(),    // Cloudflare R2
+
+      API_KEY: z.string().min(1),
+    },
+    runtimeEnv: bindings,
+    emptyStringAsUndefined: true,
+  })
+
+// Usage
+export default {
+  fetch(request: Request, env: Env) {
+    const workerEnv = createWorkerEnv(env)
+    // workerEnv.DATABASE_URL is type-safe
+  },
+}
+```
+
+</examples>
+
+---
+
+<validation>
+
+## Validation Patterns
+
+### Email
+
+```typescript
+server: {
+  ADMIN_EMAIL: z.email(),
+  SUPPORT_EMAIL: z.email().default('support@example.com'),
+}
+```
+
+### URL
+
+```typescript
+server: {
+  API_URL: z.url(),
+  WEBHOOK_URL: z.url().optional(),
+}
+```
+
+### Enum
+
+```typescript
+server: {
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']),
+  DATABASE_PROVIDER: z.enum(['postgresql', 'mysql', 'sqlite']),
+}
+```
+
+### Number
+
+```typescript
+server: {
+  PORT: z.coerce.number().positive().default(3000),
+  MAX_UPLOAD_SIZE: z.coerce.number().max(10485760), // 10MB
+  RATE_LIMIT_WINDOW: z.coerce.number().min(60).default(900), // 15min
+}
+```
+
+### Boolean
+
+```typescript
+server: {
+  ENABLE_CACHE: z.coerce.boolean().default(true),
+  DEBUG_MODE: z.coerce.boolean().default(false),
+}
+```
+
+### Custom Validation
+
+```typescript
+server: {
+  API_VERSION: z.string().regex(/^v\d+$/), // v1, v2, etc.
+  ALLOWED_ORIGINS: z.string().transform((val) => val.split(',')),
+}
+```
+
+</validation>
+
+---
+
+<middleware>
+
+## Hono Middleware Integration
+
+### Environment Validation Middleware
+
+```typescript
+import { createMiddleware } from 'hono/factory'
+import { env } from '@/env'
+
+export const envMiddleware = createMiddleware(async (c, next) => {
+  // env 객체가 초기화되었는지 확인
+  if (!env.DATABASE_URL) {
+    return c.json({ error: 'Server misconfigured' }, 500)
+  }
+  await next()
+})
+
+// Usage
+app.use('*', envMiddleware)
+```
+
+### CORS with Environment
+
+```typescript
+import { cors } from 'hono/cors'
+import { env } from '@/env'
+
+app.use(
+  '*',
+  cors({
+    origin: env.CORS_ORIGIN,
+    //          ^? string
+  })
+)
+```
+
+</middleware>
+
+---
+
+<tips>
+
+## Tips
+
+| 상황 | 방법 |
+|------|------|
+| **Cloudflare** | `createWorkerEnv(env)` 패턴 사용 |
+| **Monorepo** | 각 패키지마다 별도 `env.ts` |
+| **Testing** | `.env.test` + `NODE_ENV=test` |
+| **Docker** | `docker run -e DATABASE_URL=...` |
+| **CI/CD** | GitHub Secrets → Environment Variables |
+
+</tips>

package/templates/npx/CLAUDE.md

@@ -1,97 +1,197 @@
-# CLAUDE.md - NPX CLI 프로젝트
+# CLAUDE.md - NPX CLI
 
-> Node.js CLI 도구 개발 지침
+> Node.js CLI 도구 개발
 
-## Instructions
+<context>
 
+**Purpose:** Node.js CLI 도구 개발을 위한 작업 지침
+
+**Scope:** npx 배포 가능한 CLI 패키지 구현
+
+**Key Features:**
+- Commander.js 명령어 체계
+- 대화형 프롬프트 (prompts)
+- 파일 시스템 작업 (fs-extra)
+- TypeScript + ESM
+- 색상 출력 (picocolors)
+
+</context>
+
+---
+
+<instructions>
+@../../commands/git.md
 @docs/library/commander/index.md
 @docs/library/fs-extra/index.md
 @docs/library/prompts/index.md
+@docs/references/patterns.md
+</instructions>
 
 ---
 
-## 금지 사항
-
-### Git 커밋
-- `Generated with Claude Code` 포함 금지
-- AI 관련 이모지/표시 금지
-- `Co-Authored-By:` 헤더 금지
-- 여러 줄 커밋 메시지 금지
+<forbidden>
 
-### CLI 구현
-- `process.exit()` 없이 에러 종료 금지
-- `console.log` 직접 사용 금지 (logger 사용)
-- 동기 파일 작업 (`fs.readFileSync` 등) 금지
-- hardcoded 경로 금지 (`path.join` 사용)
-- 사용자 입력 미검증 처리 금지
+| 분류 | 금지 행동 |
+|------|----------|
+| **Git 커밋** | AI 표시 (`Generated with Claude Code`, `🤖`, `Co-Authored-By:`), 여러 줄 메시지, 이모지 |
+| **콘솔 출력** | `console.log` 직접 사용 (logger 함수 사용) |
+| **파일 작업** | 동기 API (`fs.readFileSync` 등), 하드코딩된 경로 (path.join 사용) |
+| **에러 처리** | `process.exit()` 누락, try-catch 없는 async 작업 |
+| **코드 검색** | Bash의 grep/rg/find 명령어 (ast-grep 또는 전용 도구 사용) |
 
-### 코드 검색
-- `grep`, `rg` 사용 금지 → `ast-grep` 필수
+</forbidden>
 
 ---
 
-## 필수 사항
+<required>
 
-### 작업 전
-| 작업 | 참조 문서 |
+| 작업 | 필수 행동 |
 |------|----------|
-| CLI 작업 | `docs/library/commander/` |
-| 파일 작업 | `docs/library/fs-extra/` |
-| 사용자 입력 | `docs/library/prompts/` |
+| **작업 시작 전** | 관련 docs 읽기 (Commander → commander, 파일 → fs-extra) |
+| **콘솔 출력** | logger 함수 사용 (info/success/error/warn) |
+| **파일 작업** | async API (`fs-extra`), `path.join`으로 경로 조합 |
+| **에러 처리** | try-catch + `process.exit(1)`, 사용자에게 명확한 에러 메시지 |
+| **코드 검색** | ast-grep 사용 (함수/클래스/패턴 검색) |
+| **코드 작성** | UTF-8 인코딩, 코드 묶음별 한글 주석, const 함수 선언 |
+| **복잡한 작업** | Sequential Thinking MCP (5+ 단계 작업) |
 
-### 커밋 형식
-```
-<prefix>: <설명>
+</required>
+
+---
+
+<tech_stack>
+
+| 기술 | 버전 |
+|------|------|
+| Node.js | >= 18 (ESM) |
+| TypeScript | 5.x (strict) |
+| Commander | 12.x |
+| fs-extra | 11.x |
+| prompts | 2.x |
+| picocolors | 1.x |
+| tsup | 8.x |
+
+</tech_stack>
+
+---
+
+<structure>
 ```
+src/
+├── index.ts      # CLI 진입점
+├── commands/     # 명령어 모듈
+├── utils/        # logger, copy
+└── types/        # 타입
 
-| Prefix | 용도 |
-|--------|------|
-| feat | 새 기능 |
-| fix | 버그 수정 |
-| refactor | 리팩토링 |
-| docs | 문서 수정 |
-| chore | 빌드/설정 |
+templates/        # 빌드 시 복사
+dist/             # 빌드 결과물
+```
+</structure>
 
 ---
 
-## Tech Stack
+<conventions>
+
+**파일명:** kebab-case
+**TypeScript:** const 선언, 명시적 return type, interface(객체)/type(유니온), any→unknown
+**Import 순서:** 외부 → 내부 → type
 
-| 기술 | 버전 | 비고 |
-|------|------|------|
-| Node.js | >= 18 | ESM 모듈 |
-| TypeScript | 5.x | strict mode |
-| Commander | 12.x | CLI 프레임워크 |
-| fs-extra | 11.x | 파일 시스템 |
-| prompts | 2.x | Interactive prompts |
-| picocolors | 1.x | 터미널 색상 |
-| tsup | 8.x | 번들러 |
+</conventions>
 
 ---
 
-## Directory Structure
+<quick_patterns>
+
+```typescript
+// CLI 진입점 (index.ts)
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { logger } from './utils/logger.js'
+
+const program = new Command()
+  .name('my-cli')
+  .version('1.0.0')
+  .description('CLI tool description')
+
+program
+  .command('init')
+  .description('Initialize project')
+  .option('-f, --force', 'Force overwrite')
+  .action(async (options) => {
+    try {
+      await initCommand(options)
+    } catch (error) {
+      logger.error(`Failed: ${error.message}`)
+      process.exit(1)
+    }
+  })
+
+program.parse()
+```
+
+```typescript
+// Logger (utils/logger.ts)
+import pc from 'picocolors'
 
+export const logger = {
+  info: (msg: string) => console.log(pc.blue('ℹ'), msg),
+  success: (msg: string) => console.log(pc.green('✔'), msg),
+  error: (msg: string) => console.log(pc.red('✖'), msg),
+  warn: (msg: string) => console.log(pc.yellow('⚠'), msg),
+}
 ```
-src/
-├── index.ts          # CLI 진입점
-├── commands/         # 명령어 모듈
-│   └── init.ts
-├── utils/            # 유틸리티
-│   ├── copy.ts
-│   └── logger.ts
-└── types/            # 타입 정의
-
-templates/            # 템플릿 (빌드 시 복사)
-scripts/              # 빌드 스크립트
-dist/                 # 빌드 결과물
+
+```typescript
+// 파일 복사 (utils/copy.ts)
+import path from 'node:path'
+import { copy, pathExists } from 'fs-extra'
+
+export const copyTemplate = async (
+  templatePath: string,
+  targetPath: string,
+  force: boolean = false
+): Promise<void> => {
+  const exists = await pathExists(targetPath)
+
+  if (exists && !force) {
+    throw new Error(`${targetPath} already exists`)
+  }
+
+  await copy(templatePath, targetPath, { overwrite: force })
+}
 ```
 
----
+```typescript
+// 대화형 프롬프트
+import prompts from 'prompts'
+
+const response = await prompts([
+  {
+    type: 'select',
+    name: 'template',
+    message: 'Select template',
+    choices: [
+      { title: 'React', value: 'react' },
+      { title: 'Vue', value: 'vue' },
+    ],
+  },
+  {
+    type: 'confirm',
+    name: 'install',
+    message: 'Install dependencies?',
+    initial: true,
+  },
+])
+```
 
-## 참조
+</quick_patterns>
 
-| 문서 | 경로 |
-|------|------|
-| Commander 가이드 | [docs/library/commander/](docs/library/commander/index.md) |
-| fs-extra 가이드 | [docs/library/fs-extra/](docs/library/fs-extra/index.md) |
-| prompts 가이드 | [docs/library/prompts/](docs/library/prompts/index.md) |
-| 코드 패턴 | [docs/references/patterns.md](docs/references/patterns.md) |
+---
+
+<docs_structure>
+```
+docs/
+├── library/      # commander, fs-extra, prompts
+└── references/   # CLI 패턴, 베스트 프랙티스
+```
+</docs_structure>