create-sonamu 0.1.3 → 0.1.4

package/README.md

@@ -124,8 +124,8 @@ pnpm dev
 
 🎉 **완료!**
 
-- API: http://localhost:1028
-- Sonamu UI: http://localhost:1028/sonamu-ui (엔티티 관리)
+- API: http://localhost:34900
+- Sonamu UI: http://localhost:34900/sonamu-ui (엔티티 관리)
 - Web: http://localhost:3028
 
 ---
@@ -167,8 +167,8 @@ pnpm dev
 
 | 서비스         | 포트               | URL                              |
 | -------------- | ------------------ | -------------------------------- |
-| **API 서버**   | `BASE_PORT` (1028) | http://localhost:1028            |
-| **Sonamu UI**  | -                  | http://localhost:1028/sonamu-ui  |
+| **API 서버**   | `BASE_PORT` (34900) | http://localhost:34900            |
+| **Sonamu UI**  | -                  | http://localhost:34900/sonamu-ui  |
 | **Web 개발**   | `BASE_PORT + 2000` (3028) | http://localhost:3028     |
 | **PostgreSQL** | 5432               | -                                |
 
@@ -188,11 +188,13 @@ pnpm dev
 | `pnpm build`     | 프로덕션 빌드                             |
 | `pnpm start`     | 프로덕션 서버 실행                        |
 | `pnpm test`      | 테스트 실행                               |
-| `pnpm db:up`     | Docker 데이터베이스 시작                  |
-| `pnpm db:down`   | Docker 데이터베이스 중지                  |
-| `pnpm db:reset`  | 데이터베이스 초기화 (볼륨 삭제 후 재시작) |
+| `pnpm docker:up`     | Docker 데이터베이스 시작                  |
+| `pnpm docker:down`   | Docker 데이터베이스 중지                  |
+| `pnpm docker:reset`  | 데이터베이스 초기화 (볼륨 삭제 후 재시작) |
 | `pnpm dump`      | 테스트 DB → 덤프 파일 생성                |
 | `pnpm seed`      | 덤프 파일 → fixture DB 적용               |
+| `pnpm sonamu skills sync` | 공식 Skills 동기화                   |
+| `pnpm sonamu skills create <name>` | 커스텀 Skill 생성             |
 
 ### Web (`web/`)
 
@@ -210,7 +212,7 @@ pnpm dev
 
 ### 1. 엔티티 생성
 
-API 서버를 실행한 상태에서 http://localhost:1028/sonamu-ui 접속 → **Entities** 탭 → **+ Entity** 클릭
+API 서버를 실행한 상태에서 http://localhost:34900/sonamu-ui 접속 → **Entities** 탭 → **+ Entity** 클릭
 
 ### 2. 자동 생성되는 파일들
 
@@ -292,6 +294,120 @@ function UserListPage() {
 
 ---
 
+## 🤖 AI 개발 도우미 (Skills)
+
+Sonamu 프로젝트는 **Claude Code**와 함께 사용하도록 설계되었습니다. Skills는 AI가 Sonamu 프레임워크를 더 잘 이해하고 활용할 수 있도록 돕는 지식 베이스입니다.
+
+### 자동 설치
+
+프로젝트를 생성하면 `.claude/skills/sonamu` 디렉토리가 자동으로 설정됩니다 (postinstall 스크립트 실행).
+
+```
+.claude/
+├── skills/
+│   ├── sonamu/          # 공식 Sonamu Skills (자동 동기화)
+│   │   ├── api.md
+│   │   ├── entity-basic.md
+│   │   ├── model.md
+│   │   ├── puri.md
+│   │   └── ...
+│   └── local/           # 프로젝트별 커스텀 Skills
+│       └── my-skill.md
+└── CLAUDE.md            # 프로젝트 AI 가이드 (Sonamu 섹션 포함)
+```
+
+### Skills 동기화
+
+Sonamu 업데이트 후 최신 Skills를 반영하려면:
+
+```bash
+pnpm sonamu skills sync
+```
+
+이 명령은:
+- 최신 공식 Skills를 `.claude/skills/sonamu`로 동기화 (symlink 또는 복사)
+- `CLAUDE.md`의 Sonamu 관련 섹션을 업데이트 (마커 영역만)
+
+### 커스텀 Skill 생성
+
+프로젝트에서 발견한 해결 방법이나 팁을 Skill로 저장:
+
+```bash
+pnpm sonamu skills create migration-helper
+```
+
+생성된 파일을 편집:
+
+```markdown
+---
+name: migration-helper
+category: other
+created_at: 2026-02-03
+status: draft
+---
+
+# 마이그레이션 FK 순서 문제 해결
+
+## 상황
+
+마이그레이션에서 외래키를 추가할 때 테이블 생성 순서가 맞지 않아 에러 발생
+
+## 해결 방법
+
+참조되는 테이블을 먼저 생성하고, 참조하는 테이블을 나중에 생성
+
+## 코드 예시
+
+\`\`\`typescript
+// 1. users 테이블 먼저 생성
+await knex.schema.createTable('users', ...)
+
+// 2. posts 테이블 나중에 생성 (users 참조)
+await knex.schema.createTable('posts', (table) => {
+  table.integer('user_id').references('users.id')
+})
+\`\`\`
+```
+
+**파일명 규칙**:
+- 자동으로 안전한 이름으로 변환됩니다
+- 예: `"bug fix"` → `bug-fix.md`
+- 예: `"마이그레이션/헬퍼"` → `마이그레이션-헬퍼.md`
+
+### 사용 가능한 Skills
+
+생성된 프로젝트에 포함된 주요 Skills:
+
+| Skill | 설명 |
+|-------|------|
+| **project-init** | 프로젝트 생성 및 초기화 |
+| **entity-basic** | Entity 생성/수정 기본 |
+| **entity-relations** | Entity 관계 정의 (BelongsToOne, HasMany 등) |
+| **model** | Model 클래스 작성 패턴 |
+| **api** | @api 데코레이터로 API 노출 |
+| **puri** | 타입 안전 쿼리 빌더 사용법 |
+| **subset** | API 응답 필드 범위 정의 |
+| **upsert** | 관계 데이터 저장 (UpsertBuilder) |
+| **testing** | 테스트 작성 (bootstrap, test, testAs) |
+| **migration** | 데이터베이스 마이그레이션 |
+| **frontend** | 프론트엔드에서 API 호출 |
+| **i18n** | 다국어 지원 |
+| **workflow** | 전체 개발 워크플로우 |
+
+### Claude Code 사용 팁
+
+Skills가 설정되면 Claude에게 다음과 같이 요청할 수 있습니다:
+
+```
+"User 엔티티를 생성하고 CRUD API를 만들어줘"
+"Post와 Comment의 관계를 설정해줘"
+"API 테스트 코드를 작성해줘"
+```
+
+Claude는 `.claude/skills/sonamu`의 지식을 활용하여 Sonamu 방식에 맞는 코드를 작성합니다.
+
+---
+
 ## 🗄️ 데이터베이스
 
 ### Docker 이미지
@@ -356,7 +472,7 @@ pnpm sonamu fixture sync       # 테스트 DB로 동기화
 
 ## 📚 더 알아보기
 
-- 📖 [Sonamu 공식 문서](https://rurruur.github.io/test-docs)
+- 📖 [Sonamu 공식 문서](https://sonamu.cartanova.ai/)
 - 💬 [이슈 & 피드백](https://github.com/cartanova-ai/sonamu/issues)
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sonamu",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Create a new Sonamu project",
   "keywords": [
     "sonamu",

package/template/src/README.md

@@ -56,12 +56,12 @@ pnpm dev
 ```
 
 API 서버가 시작되면 다음 주소로 접속할 수 있습니다:
-- **API 서버**: http://localhost:1028
-- **Sonamu UI**: http://localhost:1028/sonamu-ui (엔티티 관리)
+- **API 서버**: http://localhost:34900
+- **Sonamu UI**: http://localhost:34900/sonamu-ui (엔티티 관리)
 
 ### 4. 첫 번째 엔티티 생성
 
-1. Sonamu UI 열기: http://localhost:1028/sonamu-ui
+1. Sonamu UI 열기: http://localhost:34900/sonamu-ui
 2. **Entities** 탭 → **"+ Entity"** 클릭
 3. 엔티티 정의 (예: `User`, `Post`)
 4. `api/src/application/`과 `web/src/services/`에 파일이 자동으로 생성됩니다
@@ -107,8 +107,8 @@ web/src/services/
 
 | 서비스      | 포트                    | URL                             |
 | ----------- | ----------------------- | ------------------------------- |
-| API 서버    | `BASE_PORT` (기본 1028) | http://localhost:1028           |
-| Sonamu UI   | -                       | http://localhost:1028/sonamu-ui |
+| API 서버    | `BASE_PORT` (기본 34900) | http://localhost:34900           |
+| Sonamu UI   | -                       | http://localhost:34900/sonamu-ui |
 | Web 클라이언트 | `BASE_PORT + 2000`      | http://localhost:3028           |
 | PostgreSQL  | 5432                    | -                               |
 
@@ -135,6 +135,8 @@ web/src/services/
 | `pnpm docker:reset` | Docker DB 초기화 (볼륨 삭제 후 재시작) |
 | `pnpm dump`         | 테스트 DB 덤프 생성                    |
 | `pnpm seed`         | 덤프를 fixture DB에 적용               |
+| `pnpm sonamu skills sync` | 공식 Skills 동기화                   |
+| `pnpm sonamu skills create <name>` | 커스텀 Skill 생성             |
 
 ### Web (`packages/web/`)
 
@@ -148,7 +150,7 @@ web/src/services/
 
 ### 1. 엔티티 생성
 
-1. API 서버 시작 후 Sonamu UI 열기 (http://localhost:1028/sonamu-ui)
+1. API 서버 시작 후 Sonamu UI 열기 (http://localhost:34900/sonamu-ui)
 2. **Entities** 탭 → **"+ Entity"** 클릭
 3. 엔티티 정보 입력 (이름, 필드 등)
 4. **Create** 클릭 - 파일이 자동으로 생성됩니다!
@@ -224,6 +226,118 @@ pnpm seed
 pnpm sonamu fixture sync
 ```
 
+---
+
+## 🤖 AI 개발 도우미 (Skills)
+
+이 프로젝트는 **Claude Code**와 함께 사용하도록 구성되어 있습니다. `.claude/skills/sonamu` 디렉토리에는 Sonamu 프레임워크 사용법을 Claude가 이해할 수 있도록 돕는 지식 베이스가 포함되어 있습니다.
+
+### Skills 디렉토리 구조
+
+```
+.claude/
+├── skills/
+│   ├── sonamu/          # 공식 Sonamu Skills (자동 동기화)
+│   │   ├── api.md
+│   │   ├── entity-basic.md
+│   │   ├── model.md
+│   │   ├── puri.md
+│   │   └── ...
+│   └── local/           # 프로젝트별 커스텀 Skills
+│       └── my-skill.md
+└── CLAUDE.md            # 프로젝트 AI 가이드 (Sonamu 섹션 포함)
+```
+
+### Skills 최신화
+
+Sonamu 업데이트 후 최신 Skills를 반영하려면:
+
+```bash
+pnpm sonamu skills sync
+```
+
+이 명령은:
+- 최신 공식 Skills를 `.claude/skills/sonamu`로 동기화
+- `CLAUDE.md`의 Sonamu 관련 섹션을 업데이트
+
+### 커스텀 Skill 생성
+
+프로젝트 개발 중 발견한 해결 방법이나 팁을 Skill로 저장할 수 있습니다:
+
+```bash
+pnpm sonamu skills create migration-helper
+```
+
+생성된 `.claude/skills/local/migration-helper.md` 파일을 편집:
+
+```markdown
+---
+name: migration-helper
+category: other
+created_at: 2026-02-03
+status: draft
+---
+
+# 마이그레이션 FK 순서 문제 해결
+
+## 상황
+
+마이그레이션에서 외래키를 추가할 때 테이블 생성 순서가 맞지 않아 에러 발생
+
+## 해결 방법
+
+참조되는 테이블을 먼저 생성하고, 참조하는 테이블을 나중에 생성
+
+## 코드 예시
+
+\`\`\`typescript
+// 1. users 테이블 먼저 생성
+await knex.schema.createTable('users', ...)
+
+// 2. posts 테이블 나중에 생성 (users 참조)
+await knex.schema.createTable('posts', (table) => {
+  table.integer('user_id').references('users.id')
+})
+\`\`\`
+```
+
+**파일명 규칙**:
+- 자동으로 안전한 이름으로 변환됩니다
+- 예: `"bug fix"` → `bug-fix.md`
+- 예: `"마이그레이션/헬퍼"` → `마이그레이션-헬퍼.md`
+
+### 주요 Skills
+
+| Skill | 설명 |
+|-------|------|
+| **project-init** | 프로젝트 생성 및 초기화 |
+| **entity-basic** | Entity 생성/수정 기본 |
+| **entity-relations** | Entity 관계 정의 (BelongsToOne, HasMany 등) |
+| **model** | Model 클래스 작성 패턴 |
+| **api** | @api 데코레이터로 API 노출 |
+| **puri** | 타입 안전 쿼리 빌더 사용법 |
+| **subset** | API 응답 필드 범위 정의 |
+| **upsert** | 관계 데이터 저장 (UpsertBuilder) |
+| **testing** | 테스트 작성 (bootstrap, test, testAs) |
+| **migration** | 데이터베이스 마이그레이션 |
+| **frontend** | 프론트엔드에서 API 호출 |
+| **i18n** | 다국어 지원 |
+| **workflow** | 전체 개발 워크플로우 |
+
+### Claude Code 사용 예시
+
+Skills가 설정되어 있으므로 Claude에게 다음과 같이 요청할 수 있습니다:
+
+```
+"User 엔티티를 생성하고 CRUD API를 만들어줘"
+"Post와 Comment의 관계를 설정해줘"
+"API 테스트 코드를 작성해줘"
+```
+
+Claude는 `.claude/skills/sonamu`의 지식을 활용하여 Sonamu 방식에 맞는 코드를 작성합니다.
+
+---
+
 ## 데이터베이스
 
 ### Docker 이미지
@@ -267,8 +381,8 @@ pnpm sonamu fixture sync
 
 ## 📚 더 알아보기
 
-- [Sonamu 문서](https://rurruur.github.io/test-docs)
-- [Sonamu GitHub](https://github.com/ping-alive/sonamu)
+- [Sonamu 문서](https://sonamu.cartanova.ai)
+- [Sonamu GitHub](https://github.com/cartanova-ai/sonamu)
 - [Fastify 문서](https://www.fastify.io/)
 - [TanStack Router](https://tanstack.com/router)
 - [TanStack Query](https://tanstack.com/query)

package/template/src/packages/api/package.json

@@ -32,13 +32,14 @@
     "@swc/core": "^1.13.5",
     "ai": "^6.0.1",
     "bcrypt": "^6.0.0",
+    "better-auth": "^1.4.18",
     "chalk": "^4.1.2",
     "date-fns": "^4.1.0",
     "dotenv": "^16",
     "knex": "^3.1.0",
     "pg": "^8.16.3",
     "radashi": "^12.2.0",
-    "sonamu": "^0.7.50",
+    "sonamu": "^0.7.51",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/template/src/packages/api/package.json.bak

@@ -32,6 +32,7 @@
     "@swc/core": "catalog:",
     "ai": "catalog:",
     "bcrypt": "catalog:",
+    "better-auth": "catalog:",
     "chalk": "catalog:",
     "date-fns": "catalog:",
     "dotenv": "catalog:",

package/template/src/packages/api/src/sonamu.config.ts

@@ -45,32 +45,26 @@ export default defineConfig({
         root: path.join(import.meta.dirname, "/../", "public"),
         prefix: "/api/public",
       },
-      session: {
-        secret: process.env.SESSION_SECRET || "sonamu-secret-key-change-this-in-production",
-        salt: process.env.SESSION_SALT || "mq9hDxBCDbsQDR6N",
-        cookie: {
-          domain: "localhost",
-          path: "/",
-          maxAge: 60 * 60 * 24 * 365 * 10,
-        },
-      },
       custom: (_server) => {
         // nothing yet
       },
     },
-
-    auth: true,
-    // auth: {
-    //   userSerializer: async (user, _request) => user,
-    //   userDeserializer: async (serialized, _request) => serialized,
-    // },
+    
+    auth:{
+      emailAndPassword: { enabled: true },
+      baseURL: process.env.BETTER_AUTH_URL ?? `http://${host}:${port}`,
+      secret: process.env.BETTER_AUTH_SECRET ?? "miomock-secret-key-change-this-in-production",
+      trustedOrigins: ["http://localhost:5173"],
+      session: {
+        expiresIn: 60 * 60 * 24 * 365,
+      },
+    },
 
     apiConfig: {
       contextProvider: (defaultContext, request) => {
         return {
           ...defaultContext,
           ip: request.ip,
-          session: request.session,
           body: request.body,
         };
       },

package/template/src/packages/api/src/typings/sonamu.d.ts

@@ -1,12 +1,10 @@
 /** biome-ignore-all lint/correctness/noUnusedImports: d.ts */
 
-import type { Session } from "@fastify/secure-session";
 import {} from "sonamu";
 
 declare module "sonamu" {
   export interface ContextExtend {
     ip: string;
-    session: Session;
   }
 
   export interface GuardKeys {

package/template/src/packages/web/package.json

@@ -14,6 +14,7 @@
     "@tanstack/react-query": "^5.90.12",
     "@tanstack/react-router": "1.143.11",
     "axios": "^1.13.2",
+    "better-auth": "^1.4.18",
     "clsx": "^2.1.1",
     "dotenv": "^16",
     "eventsource": "^4.1.0",

package/template/src/packages/web/package.json.bak

@@ -14,6 +14,7 @@
     "@tanstack/react-query": "catalog:",
     "@tanstack/react-router": "catalog:",
     "axios": "catalog:",
+    "better-auth": "catalog:",
     "clsx": "catalog:",
     "dotenv": "catalog:",
     "eventsource": "catalog:",