@gaonjs/cli 0.4.0 → 0.10.0

package/dist/templates/project/CLAUDE.md.tpl

@@ -0,0 +1,119 @@
+# {{PROJECT_NAME}} — AI 작업 지침
+
+이 파일은 이 프로젝트에서 AI(Claude 등)가 코드를 만질 때 지켜야 할
+관례를 담는다. Gaon 프레임웍이 이 관례를 스캐폴드(`gaon new`)로 자동
+심어 두는 이유는 하나다 — 첫 시도부터 프로젝트 관례에 맞게 코드를 짜
+반복 수정을 없애기 위함(§1.1 AI 첫 시도 성공률).
+
+## 0. 먼저 읽을 것
+
+Gaon 프레임웍 문서: https://gaonjs.dev
+
+- 설계 정본(v0.15) · errata E-1(파사드 = `gaonjs`) · E-3(JSON 액션 +
+  `api()`) · E-4(컬럼 확장) · E-5(컴포저블·레이아웃)
+- 앱 내 One Way(§1) — 선택지가 있는 것을 만들지 않는다. 하나로 정한다.
+
+## 1. 절대 규칙 (12개 · 프레임웍 정본에서 유래)
+
+1. **TypeScript 전용.** JS 파일 추가 금지. 데코레이터 금지 — 함수·객체
+   스타일(`model()`·`controller()`·`job()`) 만 쓴다.
+2. **`.gaon/` 자동 생성 파일 편집 금지.** `routes.d.ts`·`tables.d.ts`
+   는 `gaon check` / `gaon dev` 가 재생성한다.
+3. **의존 방향 4규칙**(doctor 강제): 앱→domain 허용 · domain→앱 금지 ·
+   앱→앱 금지 · 앱→shared 허용(shared 는 앱 import 금지, domain 은
+   타입 import 만).
+4. **PM2·pnpm dev-server 금지.** 클러스터는 `node:cluster` 내장이 유일.
+   컨테이너 기본 워커 1.
+5. **프론트엔드는 프로젝트당 하나.** v1 은 Vue 단일. 앱 간 Vue/React
+   혼용 금지.
+6. **보안 기본값(CORS·rate limit·CSRF)은 켠 채로 둔다.** 끄는 것은
+   명시적 설정으로만.
+7. **멀티 DB 커넥션 규칙**(§4.5): 스키마는 `{ db: '키' }` 로 바인딩,
+   생략 = main. 커넥션을 가로지르는 belongsTo 금지, 서비스 트랜잭션은
+   단일 커넥션에서만 원자적. MongoDB 는 v1 구현 금지.
+8. **테스트는 Docker 실 인프라 필수 · DB·NATS 목업 절대 금지**(§9).
+   SQLite 인메모리·NATS 목업으로 테스트 돌리는 코드 만들지 말 것.
+9. **실시간은 v1 포함**(§7): 웹서버 ↔ 허브는 TCP 지속 연결 · NATS 는
+   broadcast 전용(errata E-2). 운영 프로세스는 serve·work·hub 3종.
+10. **인증·폼은 Inertia SPA**(§6 · SSR 아님). 로그인/회원가입은
+    `this.render('auth/Login')` + `Inertia.post()` → 서버 redirect.
+    REST + `fetch()` 는 API 앱(JWT) 전용.
+11. **컴포저블·레이아웃**(errata E-5): 컴포저블은 컴포넌트와 대칭
+    (`apps/<앱>/composables/` + `shared/composables/`, `use` 접두사).
+    shared 컴포저블은 인자로만 받는 순수 로직(api·pageProps 금지).
+    레이아웃은 `apps/<앱>/layouts/Default.vue` 존재 시 자동 적용.
+    **자동 import 금지** — 모든 import 는 명시적으로.
+12. **JSON 액션 + 타입드 `api()`**(errata E-3): 페이지와 무관한 데이터
+    요청은 컨트롤러의 JSON 액션(반환값 = 응답) · Vue 는 `api()`
+    클라이언트로 호출. `this.params()` 출처 우선순위 = 라우트 > body >
+    query(고정). 출처 명시는 `this.body()`·`this.query()`.
+
+## 2. 프로젝트 구조
+
+```
+{{PROJECT_NAME}}/
+├─ apps/                          앱마다 폴더 = URL 프리픽스
+│  └─ web/                        web 앱 (프리픽스 '/')
+│     ├─ app.config.ts            (선택) 앱 오버라이드
+│     ├─ routes.ts                라우트 정의
+│     ├─ controllers/             컨트롤러 (Rails 관례)
+│     ├─ pages/                   Vue 페이지 (Inertia SPA)
+│     ├─ components/              앱 전용 컴포넌트
+│     ├─ composables/             앱 전용 컴포저블 (E-5)
+│     ├─ layouts/                 앱별 레이아웃 (E-5 · Default.vue 자동)
+│     └─ channels/                (선택) 실시간 채널 (M6)
+├─ domain/                        비즈니스 로직 · 앱 간 공유
+│  ├─ schema/                     테이블 스키마 (@gaonjs/data)
+│  ├─ models/                     모델 (조회·연관·훅)
+│  ├─ services/                   트랜잭션 · 규칙
+│  ├─ jobs/                       비동기 잡 (@gaonjs/async)
+│  ├─ events/                     이벤트 정의
+│  ├─ listeners/                  이벤트 리스너
+│  ├─ mails/                      메일 (@gaonjs/mail)
+│  └─ schedule.ts                 (선택) 크론 스케줄
+├─ shared/                        앱 간 공용 (props로만)
+│  ├─ components/                 shared 컴포넌트 (순수 UI)
+│  └─ composables/                shared 컴포저블 (인자로만 · E-5)
+├─ gaon.config.ts                 루트 설정 (DB · Redis · NATS · ...)
+├─ docker-compose.yaml            개발 인프라 (gaon dev 자동 기동)
+├─ .env.example                   env 템플릿 (cp .env.example .env)
+└─ package.json                   개발자는 gaonjs 하나만 설치
+```
+
+## 3. 개발 검증 루프 (작업마다 실행)
+
+```bash
+gaon check                        # .gaon 재생성 후 타입 검사 (CI 정합)
+gaon doctor                       # 정적 검사 5종 (응답·N+1·의존·커넥션·마이그)
+npm test                          # Vitest · DB 테스트는 실 Docker 필수 (§9)
+```
+
+## 4. 작업 관례
+
+- **추론 금지 · 사실 검증.** 확인 안 된 것은 실행·측정으로 검증하거나
+  사용자에게 묻는다.
+- **주석은 개발자가 단 것처럼.** AI가 단 티가 나는 주석(`// AI 판단…`
+  `// TODO(AI)` 등) 금지. 기술적 이유(왜 이 코드가 이런지, 특수 케이스
+  근거) 만 담는다.
+- **파일 작게 · 역할은 하나로.** 영리한 코드보다 읽히는 코드.
+- **에러 메시지**(§7.5.3): "어느 파일에 무엇을 추가/수정하고 어떤
+  명령을 실행하라" 까지 쓴다.
+
+## 5. 자주 쓰는 명령
+
+```bash
+gaon dev                          # 개발 (Docker · 타입 브리지 · watch)
+gaon serve                        # 서버만 (운영 프로세스 1/3)
+gaon work                         # 워커 (잡·리스너·아웃박스)
+gaon hub                          # 실시간 허브 (프레즌스 · 리더 선출 HA)
+gaon g controller <name>          # 컨트롤러 스캐폴드
+gaon g model <Name>               # 스키마 + 모델 스캐폴드 (E-4)
+gaon g page <Path>/<Name>         # Vue 페이지 (Inertia SPA · pageProps)
+gaon g job <Name>                 # 비동기 잡
+gaon g auth                       # 인증 스캐폴드 (세션 + JWT 옵션)
+gaon db diff                      # 스키마 ↔ DB 차이 (적용 X)
+gaon db migrate                   # 실제 적용 + _gaon_migrations 이력
+gaon db seed                      # domain/seed.ts 실행
+```
+
+문서 · 진행 상황: https://gaonjs.dev

package/dist/templates/project/agents/async.md.tpl

@@ -0,0 +1,218 @@
+# agents/async.md — 비동기 (잡 · 이벤트 · 리스너 · 아웃박스 · 스케줄러)
+
+> 골격: **정본 규칙 → 정본 예시 → 알려진 함정 → 관련 결정 번호** (결정 40 · 2층 구조).
+> 루트 `AGENTS.md` 는 코어 요약만 담는다 — 시그니처·표·예시의 정본은 이 파일이다.
+> 대상 패키지: `@gaonjs/async` (파사드 import 는 `gaonjs/async`). 백본 = NATS JetStream ·
+> 실행은 워커 프로세스(`gaon work`).
+
+## 정본 규칙
+
+### 1. 잡 (`job()`) (`packages/async/src/jobs.ts:146-185`)
+
+잡은 도메인 소속이다 — `domain/jobs/*.ts` 에 파일을 놓으면 등록이고,
+어느 앱에서 큐잉하든 같은 워커(`gaon work`)가 처리한다. 모델·서비스와
+같은 함수/객체 스타일(데코레이터 금지).
+
+```ts
+// domain/jobs/sendWelcomeMail.ts — 파일명 camelCase (루트 §네이밍)
+import { job } from 'gaonjs/async'
+
+export const SendWelcomeMail = job(async (userId: bigint) => {
+  // 실 발송 로직 (예: gaonjs/mail 사용)
+}, { retries: 3 })
+```
+
+```ts
+await SendWelcomeMail.later(user.id)        // 즉시 큐잉(인자 타입 그대로 추론)
+await SendWelcomeMail.in('10m', user.id)    // 지연 실행
+await SendWelcomeMail.at(someDate, user.id) // 특정 시각 실행
+```
+
+- **시그니처** — `job(handler, options?)`. 첫 인자는 평범한 async
+  함수(`(...args) => Promise<void> | void`) — `defineJob` 이나
+  `{ perform }` 객체 형태가 아니다.
+- **이름** — `options.name` 으로 명시하거나, 생략하면 `domain/jobs/`
+  파일 로더가 **파일명**으로 채운다(`assignName`). 이름을 얻기 전까지
+  `.later()` 등을 호출하면 에러 — 파일로 두거나 `name` 을 직접 준다.
+- **옵션** — `queue`(기본 `'default'`) · `retries`(기본 3) ·
+  `curve`(백오프 곡선 ms) · `jitter` · `concurrency`.
+- **실패** — 재시도를 소진하면 DLQ 로 간다. `gaon jobs list --failed` ·
+  `gaon jobs retry <id>` 로 조회·재적재한다.
+- 기본 백오프 곡선은 `[1s, 5s, 30s, 5m, 1h]` + 지터 0.2, 재시도 3
+  (총 4시도) — §7 · 벤치마크로 확정된 값.
+
+### 2. 잡 발행 위치 (결정 32 · 2026-07-24 종결)
+
+잡(`.later(...)`)은 **컨트롤러 · 서비스 · 리스너 어디서든 발행
+가능**하다. The One Way 로 발행 위치를 강제하지 않는다 — 사용 맥락에
+따라 선택한다 (v0.16 §12 결정 32).
+
+- **컨트롤러** — 요청 응답 시 즉시 발행 (예: 회원가입 응답 후 환영
+  메일 잡):
+
+  ```ts
+  async create() {
+    const user = await User.create(this.params(User.registerForm))
+    await SendWelcomeMail.later(user.id)      // 컨트롤러에서 발행
+    return this.redirect('/dashboard')
+  }
+  ```
+
+- **서비스** — 여러 컨트롤러 재사용 · 트랜잭션 · 복잡 로직:
+
+  ```ts
+  // domain/services/registerUser.ts — service() 상세는 agents/data.md §9
+  import { service } from 'gaonjs/service'
+
+  export const RegisterUser = service(async (input: RegisterInput) => {
+    const user = await User.create(input)
+    await SendWelcomeMail.later(user.id)      // 서비스에서 발행
+    return user
+  })
+  // 컨트롤러에서: const user = await RegisterUser.call(input)
+  ```
+
+- **리스너** — 이벤트 반응 (예: OrderPlaced 이벤트 → EmailReceipt 잡).
+
+**어디서 발행하든 정합이다.** 컨트롤러 발행 = 즉시성 · 서비스 발행 =
+재사용성 · 리스너 발행 = 이벤트 기반. DB 커밋과 정합이 필요하면
+서비스 `afterCommit()`(`agents/data.md` §9) 또는 아웃박스(§4)를 쓴다.
+
+### 3. 이벤트와 리스너
+
+이벤트는 페이로드 shape 에서 타입이 **구조적으로** 추론된다. 리스너는
+`domain/listeners/*.ts` 의 default export 이고, durable 컨슈머 id 는
+**파일명**에서 채워진다(재시작해도 같은 컨슈머).
+
+```ts
+// domain/events/orderPlaced.ts
+import { event } from 'gaonjs/async'
+import { t } from 'gaonjs/data'
+
+export const OrderPlaced = event('order.placed', {
+  orderId: t.bigint(),
+})
+```
+
+```ts
+// domain/listeners/notifyAdmin.ts
+import { on } from 'gaonjs/async'
+import { OrderPlaced } from '../events/orderPlaced.js'
+
+export default on(OrderPlaced, ({ orderId }) => {
+  // orderId 는 bigint 로 추론됨
+})
+```
+
+이벤트 발행:
+
+```ts
+await OrderPlaced.emit({ orderId: 1n })
+```
+
+여러 리스너가 같은 이벤트를 durable 컨슈머로 구독하며, 각자 재시도된다.
+
+### 4. 아웃박스 (트랜잭션 정합)
+
+이벤트를 DB 트랜잭션과 **원자적으로** 발행하려면 아웃박스를 쓴다.
+`runInTransaction` 안에서 발행한 이벤트는 같은 트랜잭션의 아웃박스
+테이블에 스테이징되고, 트랜잭션이 커밋돼야 릴레이가 실제로 NATS 에
+발행한다. 트랜잭션이 롤백되면 이벤트도 사라진다.
+
+```ts
+import { runInTransaction } from 'gaonjs/async'
+
+await runInTransaction(async () => {
+  await Order.create({ /* … */ })
+  await OrderPlaced.emit({ orderId })   // 커밋돼야 실제 발행됨
+})
+```
+
+- 트랜잭션 안의 `emit` 은 `AsyncLocalStorage` 로 투명하게 감지돼
+  아웃박스에 스테이징된다(별도 API 호출 불필요).
+- 릴레이(`gaon work` 내장)가 `SKIP LOCKED` 로 아웃박스를 폴링해 발행
+  한다 (기본 폴 1000ms · 배치 100).
+- at-least-once — 발행 후 표시하므로 중복 가능성이 있고, dedup(msgID)이
+  흡수한다.
+- 아웃박스 테이블(`_gaon_outbox`)은 코어 내장이며 워커 기동 시 보장된다.
+
+### 5. 스케줄러
+
+`domain/schedule.ts` 에서 반복 작업을 선언한다. 실행 대상은 **항상 잡**
+이다(인라인 함수 금지). 여러 워커가 떠 있어도 **리더로 선출된 하나**만
+발행하므로 중복 실행이 없다.
+
+```ts
+// domain/schedule.ts
+import { schedule } from 'gaonjs/async'
+import { CleanupExpiredSessions } from './jobs/cleanupExpiredSessions.js'
+import { SendDailyDigest } from './jobs/sendDailyDigest.js'
+import { SendWeeklyReport } from './jobs/sendWeeklyReport.js'
+
+export default schedule((s) => {
+  s.every('10m', CleanupExpiredSessions)     // 주기 실행
+  s.daily.at('04:00', SendDailyDigest)       // 매일 특정 시각
+  s.cron('0 9 * * 1', SendWeeklyReport)      // 크론 표현식 (5필드)
+})
+```
+
+| 빌더 | 설명 |
+| --- | --- |
+| `s.every(interval, Job)` | `'10m'`·`'700ms'` 등 주기 또는 ms |
+| `s.daily.at('HH:MM', Job)` | 매일 지정 시각 |
+| `s.cron('분 시 일 월 요일', Job)` | 5필드 크론 표현식 |
+
+### 6. 워커 프로세스 (`gaon work`)
+
+잡·리스너·스케줄러·아웃박스 릴레이를 한 프로세스로 조립한다. 운영
+프로세스 3종(serve·work·hub) 중 하나. SIGTERM/SIGINT 에 graceful
+drain — 스케줄러 리더를 반납하고 진행 중인 잡을 완료한 뒤 종료한다.
+
+## 정본 예시
+
+회원 가입 → 환영 메일 비동기 발송 세로 조각 (§7 원문 예시):
+
+```ts
+// domain/jobs/sendWelcomeMail.ts
+import { job } from 'gaonjs/async'
+
+export const SendWelcomeMail = job(async (userId: bigint) => {
+  // 실 발송 (stub 도 OK — 파일 관례가 관건)
+}, { retries: 3 })
+```
+
+```ts
+// apps/web/controllers/registration.ts — 컨트롤러는 잡 발행만 (직접 발송 금지)
+async create() {
+  const user = await RegisterUser.call(this.params(RegisterUser.form))
+  await SendWelcomeMail.later(user.id)
+  return this.redirect('/dashboard')
+}
+```
+
+발행·처리를 검증하는 실 NATS 테스트는 `agents/testing.md` (결정 42 ·
+`expectJobProcessed`) 를 따른다.
+
+## 알려진 함정
+
+- **컨트롤러에서 메일·외부 발송 직접 호출 = 함정** — 컨트롤러는 잡
+  발행만. nodemailer·resend·@sendgrid/mail 직접 import 금지.
+- **클래스형 잡·데코레이터(`@Job`·`@Processor`) 금지** — `job()` 함수형만.
+- **잡 파일 위치는 `domain/jobs/`** — 앱 폴더가 아니다 (잡은 도메인
+  소속 · 어느 앱에서든 큐잉).
+- **`export const <Pascal> = job(...)`** — export 없이 정의만 하면
+  컨트롤러가 import 해 `.later()` 를 부를 수 없다.
+- **스케줄 대상은 항상 잡** — `s.every('10m', async () => ...)` 인라인
+  함수 금지.
+- **커밋 전 발행 주의** — 트랜잭션 안에서 DB 확정 후에만 나가야 하는
+  발행은 `afterCommit()` 또는 아웃박스로.
+- **테스트에서 NATS 목업 금지** (§9) — 실 JetStream 에 접속한다
+  (`agents/testing.md`).
+
+## 관련 결정 번호
+
+| 결정 | 내용 |
+|---|---|
+| 결정 32 | 잡 발행 위치 자유 (컨트롤러·서비스·리스너 모두 정합) |
+| 결정 42 | 비동기 테스트 헬퍼 `expectJobProcessed` (`agents/testing.md`) |
+| §7 | 비동기 배터리 원문 (백오프 기본값 = M7 벤치마크 확정) |