@gaonjs/cli 0.4.0 → 0.10.0

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

@@ -0,0 +1,177 @@
+# agents/web.md — 웹 레이어 (라우팅 · 컨트롤러 · params · JSON 액션 · 인증)
+
+> 골격: **정본 규칙 → 정본 예시 → 알려진 함정 → 관련 결정 번호** (결정 40 · 2층 구조).
+> 루트 `AGENTS.md` 는 코어 요약만 담는다 — 시그니처·규칙 상세의 정본은 이 파일이다.
+> 대상 패키지: `@gaonjs/web` (파사드 import 는 `gaonjs/web`).
+
+## 정본 규칙
+
+### 1. JSON 액션 — 반환값이 곧 응답 (errata E-3 §3.1)
+
+컨트롤러 액션이 `this.render(...)` 나 `this.redirect(...)` 대신
+**평범한 객체/배열을 반환하면 그것이 곧 JSON 응답**이다. 별도
+데코레이터·설정·헬퍼 호출이 없다 (E-3 §3.1 원문).
+
+```ts
+// apps/web/controllers/posts.ts
+import { controller } from 'gaonjs/web'                // 파사드 · 함수형 API
+import { Post } from '../../../domain/models/Post.js'  // 앱→도메인 (rule 5)
+
+export default controller({
+  async index() {
+    return this.render('Posts/Index', { posts: await Post.latest().limit(20).all() })
+  },
+
+  // JSON 액션 — 객체를 반환하면 JSON 응답
+  async search() {
+    const { q } = this.params(Post.searchForm)          // 검증 실패 시 자동 422 JSON
+    return { results: await Post.published().search(q).limit(10).all() }
+  },
+})
+```
+
+- **import 관례** — 프레임웍 심볼은 파사드 `gaonjs/*` 에서 (`gaonjs/web`·
+  `gaonjs/data`·`gaonjs/vue`·`gaonjs/async` 등), 도메인 모델은 상대경로
+  `../../../domain/models/<Pascal>.js` 로 참조한다. `@gaonjs/*` (스코프
+  이름) 은 내부 패키지 이름 — 앱 코드에서 직접 import 하지 않는다.
+  `@inertiajs/vue3` 는 어댑터 내부 의존 — 앱에서 직접 안 쓴다.
+- **`this.render` 인자** = `<PageFolder>/<Page>` (PascalCase 폴더 · Vue
+  파일명과 정합) — 예: `'Posts/Index'` → `apps/<app>/pages/Posts/Index.vue`.
+- **리소스 부재 = `this.notFound()`** — 조회 결과가 없으면 404 를 손으로 만들지
+  말고 `this.notFound()` 로 마감한다(`requireAuth()` 와 동형). `never` 를 반환해
+  이 뒤로 값이 존재하는 것으로 좁혀지므로, `render` 반환 타입(타입 브리지)도 그대로
+  유지된다. 메시지는 선택: `this.notFound('post 없음')`.
+
+  ```ts
+  async show() {
+    const post = await Post.find(this.params(Post.showForm).id)
+    if (!post) return this.notFound()   // 404 · 이 뒤로 post 는 non-null
+    return this.render('Posts/Show', { post })
+  }
+  ```
+
+### 2. 응답 규칙 — 한 액션은 한 종류 응답만
+
+- **한 액션은 한 종류 응답만 낸다** (render 또는 JSON 또는 redirect —
+  조건 분기 혼용 금지). `gaon doctor` 의 **response-mixing** 검사가
+  혼용을 잡는다.
+- 검증은 페이지 액션과 동일하게 `this.params(스키마)` — 실패 시
+  422 JSON.
+- 인증·세션은 같은 앱의 세션 쿠키를 그대로 쓴다. CSRF·rate limit 등
+  보안 기본값도 그대로 적용된다 (`agents/security.md` · 끄는 것은
+  명시적 설정으로만).
+
+### 3. `this.params` 통합 입력 · 안전 규칙 (errata E-3 §5 · 결정 24)
+
+`this.params` 는 라우트 파라미터·query·body(업로드 파일 포함)를
+하나로 합쳐서 주는 Rails 식 통합 입력이다. 안전을 위해 아래 세 규칙이
+반드시 함께 적용된다.
+
+**출처 우선순위 — 고정, 설정 불가:**
+
+- **라우트 파라미터 > body > query** 순서로 병합 (E-3 §5.1 원문).
+- 라우트 파라미터가 절대 덮어써지지 않는 것이 핵심 — `/posts/:id` 의
+  `id` 를 공격자가 body 의 `id: 999` 로 바꿔치기해서 권한 검사를
+  우회하는 파라미터 오염 공격을 원천 차단한다.
+- 이 우선순위는 문서화된 고정 규칙이며 **설정으로 바꿀 수 없다**.
+
+**중복 키:**
+
+- `?tag=a&tag=b` 처럼 같은 출처에서 키가 중복되면: 스키마의 해당
+  필드가 배열 타입이면 배열로 수집, 아니면 **마지막 값**을 쓴다
+  (E-3 §5.2 원문).
+
+**출처 명시 탈출구 — `this.body()` / `this.query()`:**
+
+- 출처 자체가 의미를 갖는 드문 경우(웹훅 수신처럼 반드시 body에서만
+  와야 하는 데이터, 서명 검증 대상 등)에만 쓴다.
+- 기본 경로는 여전히 `this.params` 하나(The One Way) — 스캐폴드·문서·
+  기본 예시는 `this.params` 만 쓴다 (E-3 §5.3 원문).
+
+### 4. 데이터 경로 판단 — 루트 판단표가 정본
+
+데이터가 필요할 때는 루트 `AGENTS.md` 의 데이터 경로 4종 판단표를 따른다
+(Inertia partial reload · 채널/프레즌스 · JSON 액션 + `api()` · 별도 API 앱 + JWT).
+**Inertia = SPA + 서버 라우팅**이지 SSR 이 아니다. 로그인·회원가입도 컨트롤러
+`this.render('auth/Login')` + Vue 페이지 `Inertia.post()` → 서버
+redirect 로 처리한다 — 전체 페이지 리로드도, 별도 REST 엔드포인트도
+없다. REST + `fetch()` 는 **API 앱(JWT) 전용**.
+
+### 5. 비밀번호 해싱 — `hashPassword` · `verifyPassword` (`gaonjs/web`)
+
+회원가입·로그인에서 비밀번호를 다룰 때는 **직접 crypto/bcrypt 를 import 하거나
+base64·해시를 손으로 짜지 말고** `gaonjs/web` 의 헬퍼를 쓴다(The One Way · §7 인증).
+bcrypt(cost 10)로 해싱하며 상수시간 비교를 제공한다.
+
+```ts
+import { hashPassword, verifyPassword } from 'gaonjs/web'
+
+// 가입 — 서비스에서 평문을 해싱해 hidden 컬럼(passwordDigest)에 저장.
+const passwordDigest = await hashPassword(plain)          // Promise<string>
+const user = await User.create({ name, email, passwordDigest })
+
+// 로그인 — 저장된 다이제스트와 평문을 비교(상수시간).
+const ok = await verifyPassword(plain, user.passwordDigest) // Promise<boolean>
+```
+
+- **시그니처** — `hashPassword(plain: string): Promise<string>` ·
+  `verifyPassword(plain: string, digest: string): Promise<boolean>`. 둘 다 async.
+- **기본값** — bcrypt cost 10(보안/지연 균형점). 순수 JS(`bcryptjs`)라 네이티브
+  빌드 없이 어느 환경에서나 설치가 확실하다.
+- **저장 위치** — 결과는 스키마의 hidden 컬럼(`passwordDigest: t.string().hidden()`)
+  에 담는다 — 응답 경계에서 타입·런타임 양쪽으로 페이지 노출이 막힌다.
+- 회원 생성 로직은 컨트롤러가 아니라 **서비스**(`agents/data.md` §9 · registerUser)에
+  둔다 — `const user = await RegisterUser.call({ name, email, password })`.
+
+### 6. 인증·세션 (v0.15 §7 · M5)
+
+- 세션 쿠키가 기본, JWT 는 **API 앱 전용 옵션** (v0.11 확정).
+- 세션은 앱별 완전 분리 (Fastify 캡슐화 스코프): 쿠키 이름(`<app>_sid`) ·
+  서명 secret · Redis 키 prefix · 쿠키 path 가 앱 단위로 갇힌다.
+- 스캐폴드는 `gaon g auth` — 로그인/회원가입 컨트롤러·페이지·라우트 일습.
+- 로그인 필요 액션은 `this.requireAuth()` 관례 (notFound 와 동형 — never 좁힘).
+
+## 정본 예시
+
+```ts
+// apps/web/controllers/registration.ts — 회원 가입 (E-3 · Inertia SPA)
+import { controller } from 'gaonjs/web'
+import { RegisterUser } from '../../../domain/services/registerUser.js'
+import { SendWelcomeMail } from '../../../domain/jobs/sendWelcomeMail.js'
+
+export default controller({
+  async new() {
+    return this.render('Auth/Register', {})
+  },
+  async create() {
+    const user = await RegisterUser.call(this.params(RegisterUser.form))
+    await SendWelcomeMail.later(user.id)      // 잡 발행 위치는 결정 32 — 서비스 afterCommit 도 정합
+    return this.redirect('/dashboard')
+  },
+})
+```
+
+## 알려진 함정
+
+- **render/JSON/redirect 를 한 액션에서 조건 혼용하면 doctor
+  response-mixing 위반** — 액션을 나눈다.
+- **`fetch()` 로 로그인 폼 구현 금지** — 세션 앱 폼은 `Inertia.post()`.
+  REST + fetch 는 API 앱(JWT) 전용.
+- **컨트롤러에 비즈니스 로직 인라인 금지** (§5.3 One Way) — 여러 모델·
+  트랜잭션·외부 API 가 얽히면 `domain/services/`.
+- **컨트롤러에서 메일·외부 발송 직접 호출 금지** — 잡 발행만
+  (`agents/async.md`). nodemailer·resend 등 SDK 직접 import 는 함정.
+- **bcrypt·crypto 직접 import 금지** — `hashPassword`/`verifyPassword`.
+- **`@gaonjs/*` 스코프 직접 import 금지** — 파사드 `gaonjs/*` 만.
+- **bigint PK 를 render props 로 흘릴 때는 `String(p.id)` 정규화**
+  (결정 37 · 상세는 `agents/frontend.md`).
+
+## 관련 결정 번호
+
+| 결정 | 내용 |
+|---|---|
+| 결정 23 (E-3) | 앱 내 JSON 액션 — 반환값 = 응답 |
+| 결정 24 (E-3 §5) | `this.params` 안전 규칙 (라우트 > body > query · 중복 키 · body/query 탈출구) |
+| 결정 32 | 잡 발행 위치 자유 (컨트롤러·서비스·리스너 — `agents/async.md`) |
+| 결정 37 | bigint PK 컨트롤러 `String()` 정규화 (`agents/frontend.md`) |
+| E-1 | 파사드 = `gaonjs` · CLI = `gaon` |

package/dist/templates/project/apps/web/channels/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/apps/web/components/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/apps/web/composables/useApiPing.ts.tpl

@@ -0,0 +1,25 @@
+// useApiPing — 앱 전용 컴포저블(errata E-5 §2.1).
+// 파일 하나에 컴포저블 하나 · 파일명 = 컴포저블명 · use 접두사.
+// 앱 전용 컴포저블은 api()/pageProps() 를 자유롭게 쓸 수 있다.
+// shared/composables 는 반대 — 인자로만 받는 순수 로직(E-5 §2.2).
+import { ref } from 'vue'
+
+/** GET /health 를 두드려 서버가 살아 있는지 확인하는 예시 컴포저블. */
+export function useApiPing() {
+  const ok = ref<boolean | null>(null)
+  const error = ref<string | null>(null)
+
+  async function ping(): Promise<void> {
+    try {
+      const res = await fetch('/health', { headers: { Accept: 'application/json' } })
+      const body = (await res.json()) as { ok: boolean }
+      ok.value = body.ok === true
+      error.value = null
+    } catch (err) {
+      ok.value = false
+      error.value = err instanceof Error ? err.message : String(err)
+    }
+  }
+
+  return { ok, error, ping }
+}

package/dist/templates/project/apps/web/controllers/home.ts.tpl

@@ -0,0 +1,19 @@
+// home 컨트롤러 — apps/web/controllers/home.ts. 페이지 액션(this.render)과
+// JSON 액션(반환값 = 응답 · errata E-3)의 두 대표 패턴을 함께 담는다.
+import { controller } from 'gaonjs/web'
+
+export default controller({
+  // GET / — Inertia SPA 홈. this.render 는 Vue 페이지(Home/Index.vue) 로 넘긴다.
+  async index() {
+    return this.render('Home/Index', {
+      title: '{{PROJECT_NAME}}',
+      docs: 'https://gaonjs.dev',
+    })
+  },
+
+  // GET /health — JSON 액션(errata E-3). 반환값이 곧 응답.
+  // 배포 후 헬스체크·60초 실측(v0.15 §13.5 M9 완료 기준)에 쓰인다.
+  async health() {
+    return { ok: true, service: '{{PROJECT_NAME}}' }
+  },
+})

package/dist/templates/project/apps/web/index.html.tpl

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="ko">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{PROJECT_NAME}}</title>
+  </head>
+  <body>
+    <!--
+      Vite 개발 서버가 이 index.html 을 서빙한다(dev). 운영 빌드는
+      vite build 가 이 파일을 진입점 삼아 프로덕션 번들을 만든다.
+      Fastify(gaonjs/web) 는 초기 SPA 응답 셸에서 아래와 같은 구조의
+      <div id="app" data-page="..."> 를 내려보낸다 — 개발과 운영이 같은 셸.
+    -->
+    <div id="app"></div>
+    <script type="module" src="/main.ts"></script>
+  </body>
+</html>

package/dist/templates/project/apps/web/layouts/Default.vue.tpl

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+// 기본 레이아웃 — apps/web/layouts/Default.vue (errata E-5 §2.3).
+// 파일이 존재하면 이 앱의 모든 페이지에 자동 적용된다(파일 존재 = 등록).
+// 다른 레이아웃이 필요한 페이지만 페이지 파일에서 명시적으로 바꾼다.
+//
+// 레이아웃은 shared 에 두지 않는다(E-5 §2.3) — 앱마다 레이아웃이 다른 것이
+// 정상이고, 공용 조각(로고·푸터 등) 만 shared/components 로 뽑는다.
+</script>
+
+<template>
+  <div class="layout">
+    <header class="layout-header">
+      <strong>{{PROJECT_NAME}}</strong>
+    </header>
+    <slot />
+    <footer class="layout-footer">
+      <small>Powered by <a href="https://gaonjs.dev" target="_blank">Gaon</a></small>
+    </footer>
+  </div>
+</template>
+
+<style scoped>
+.layout {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+.layout-header,
+.layout-footer {
+  padding: 1rem;
+  background: #f6f8fa;
+  border-color: #e1e4e8;
+}
+.layout-header {
+  border-bottom: 1px solid #e1e4e8;
+}
+.layout-footer {
+  border-top: 1px solid #e1e4e8;
+  margin-top: auto;
+  text-align: center;
+  color: #6a737d;
+}
+</style>

package/dist/templates/project/apps/web/main.ts.tpl

@@ -0,0 +1,24 @@
+// apps/web/main.ts — 프론트엔드 진입 (v0.16 §6.4 · M3 최소 웹 레이어).
+//
+// 브라우저 부팅 흐름:
+//   1) index.html 이 이 파일을 <script type="module"> 로 로드한다.
+//   2) createGaonApp 이 Inertia SPA 를 마운트한다.
+//   3) 서버 응답의 data-page 를 어댑터가 읽어 첫 페이지를 그린다.
+//
+// 자동 import 금지(E-5 §2.4) — 페이지·레이아웃 지도는 아래처럼 명시적으로
+// import.meta.glob 으로 만든다. 심볼 출처가 코드에 그대로 보인다.
+import { createGaonApp } from 'gaonjs/vue'
+
+// 페이지는 지연 로드(코드 스플리팅) — 큰 앱에서도 첫 페이지 로딩이 빠르다.
+// eager 로 바꿔도 되지만, One Way 의 기본은 지연 로드다.
+const pages = import.meta.glob('./pages/**/*.vue')
+
+// 레이아웃은 eager — 소수·최초 진입에도 필요하므로 굳이 지연 로드하지 않는다.
+// layouts/Default.vue 가 있으면 모든 페이지에 자동 적용된다(errata E-5 §2.3).
+const layouts = import.meta.glob('./layouts/*.vue', { eager: true })
+
+void createGaonApp({
+  pages,
+  layouts,
+  title: (t) => (t ? `${t} · {{PROJECT_NAME}}` : '{{PROJECT_NAME}}'),
+})

package/dist/templates/project/apps/web/pages/Home/Index.vue.tpl

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+import { pageProps } from 'gaonjs/vue'
+
+// home#index 의 render props — Serialized<> 로 넘어온다(§6.2).
+// 라우트 키는 .gaon/routes.d.ts 가 유효한 값을 알려준다.
+const props = pageProps<'home#index'>()
+</script>
+
+<template>
+  <main class="home">
+    <h1>{{ props.title }}</h1>
+    <p>Gaon 프레임웍이 방금 이 앱을 만들었습니다.</p>
+    <p>
+      문서: <a :href="props.docs" target="_blank">{{ props.docs }}</a>
+    </p>
+    <hr />
+    <h2>다음 단계</h2>
+    <ol>
+      <li><code>gaon g auth</code> — 인증 스캐폴드 생성 (회원가입·로그인·세션)</li>
+      <li><code>gaon g model Post</code> — 모델 스캐폴드 (스키마 + 모델 · E-4)</li>
+      <li><code>gaon g controller posts</code> — 컨트롤러 스캐폴드</li>
+      <li><code>gaon g page Posts/Index</code> — Vue 페이지 (Inertia SPA)</li>
+      <li><code>gaon dev</code> — Docker 자동 기동 · 타입 브리지 · watch</li>
+    </ol>
+  </main>
+</template>
+
+<style scoped>
+.home {
+  max-width: 640px;
+  margin: 4rem auto;
+  padding: 0 1rem;
+  font-family: system-ui, -apple-system, sans-serif;
+  line-height: 1.6;
+}
+</style>

package/dist/templates/project/apps/web/routes.ts.tpl

@@ -0,0 +1,8 @@
+// web 앱 라우트 — apps/web/routes.ts. 앱 폴더명(web)이 URL 프리픽스가 되지만
+// web 앱은 관례상 프리픽스 '/' 를 쓴다(v0.15 §6.1).
+import { routes } from 'gaonjs/web'
+
+export default routes((r) => {
+  r.get('/', 'home#index') // GET / → home#index (Inertia SPA · Home/Index.vue)
+  r.get('/health', 'home#health') // GET /health → JSON { ok: true } (헬스체크)
+})

package/dist/templates/project/docker-compose.yaml.tpl

@@ -0,0 +1,73 @@
+# {{PROJECT_NAME}} 개발 스택 — gaon dev 가 자동 기동한다(CLAUDE.md §2 · v0.15 §9).
+# 목업·인메모리 대체는 금지 — 개발·테스트·운영 모두 실 인프라를 쓴다.
+#
+# 기동:  docker compose up -d          (gaon dev 가 자동 실행)
+# 정지:  docker compose down
+name: {{PROJECT_NAME}}
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: {{PROJECT_NAME}}
+      POSTGRES_PASSWORD: {{PROJECT_NAME}}
+      POSTGRES_DB: {{PROJECT_NAME}}_dev
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U {{PROJECT_NAME}} -d {{PROJECT_NAME}}_dev"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  # 세션 스토어(§7.4). 캐시·세션은 Redis 가 기본이다.
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  # 실시간 백본(§7 · M6). NATS JetStream(-js) — 채널·잡·프레즌스 KV 를 모두 처리.
+  nats:
+    image: nats:2.10-alpine
+    command: ["-js", "-m", "8222"]
+    ports:
+      - "4222:4222"
+      - "8222:8222"
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:8222/healthz"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  # 메일 배터리(§7 · M8). MailPit = SMTP 싱크 + 웹 UI(:8025) — 개발 미리보기의 실 인프라.
+  mailpit:
+    image: axllent/mailpit:latest
+    ports:
+      - "1025:1025"
+      - "8025:8025"
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:8025/readyz"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  # 파일 스토리지(§7 · M8). MinIO = S3 호환 — 운영 R2/S3 와 동일 API.
+  minio:
+    image: minio/minio:latest
+    command: ["server", "/data", "--console-address", ":9001"]
+    environment:
+      MINIO_ROOT_USER: {{PROJECT_NAME}}
+      MINIO_ROOT_PASSWORD: {{PROJECT_NAME}}_secret
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 2s
+      timeout: 3s
+      retries: 30

package/dist/templates/project/domain/events/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/jobs/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/listeners/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/mails/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/models/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/schema/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/services/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/gaon.config.ts.tpl

@@ -0,0 +1,27 @@
+// {{PROJECT_NAME}} 루트 설정 (§3.3). 개발자는 이 파일 하나로 배터리를 켠다.
+// 환경 변수는 .env 에서 로드된다 — gaon dev / gaon serve 가 자동 배선.
+import { defineConfig } from 'gaonjs/config'
+
+export default defineConfig({
+  // DB — main 커넥션. 스키마에서 { db: '키' } 로 다른 커넥션에 붙일 수 있다(§4.5).
+  db: process.env.DATABASE_URL
+    ? {
+        main: {
+          adapter: 'postgres',
+          url: process.env.DATABASE_URL,
+        },
+      }
+    : undefined,
+
+  // Redis — 세션 스토어 · 캐시.
+  redis: process.env.REDIS_URL ? { url: process.env.REDIS_URL } : undefined,
+
+  // NATS — 실시간·비동기 백본(§7). broadcast 전용(errata E-2).
+  nats: process.env.NATS_URL ? { url: process.env.NATS_URL } : undefined,
+
+  // 웹 서버 리슨 옵션. --port · env PORT 로 덮을 수 있다.
+  web: {
+    port: process.env.PORT ? Number(process.env.PORT) : 3000,
+    cookieSecret: process.env.COOKIE_SECRET,
+  },
+})

package/dist/templates/project/package.json.tpl

@@ -0,0 +1,30 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "dev": "gaon dev",
+    "serve": "gaon serve",
+    "work": "gaon work",
+    "hub": "gaon hub",
+    "check": "gaon check",
+    "doctor": "gaon doctor",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "gaonjs": "{{GAONJS_VERSION}}",
+    "@inertiajs/vue3": "^3.6.0",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.0",
+    "typescript": "^5.9.0",
+    "vite": "^7.0.0",
+    "vue-tsc": "^3.3.0",
+    "vitest": "^3.0.0"
+  }
+}

package/dist/templates/project/pnpm-workspace.yaml.tpl

@@ -0,0 +1,11 @@
+# pnpm workspace — 앱은 apps/*, 도메인은 domain/, 공용은 shared/ 아래에 둔다.
+# 이 관례는 CLAUDE.md §2 · v0.15 §3.2 를 따른다(앱과 domain 은 별도 폴더).
+packages:
+  - "packages/*"
+
+# pnpm 11 부터 build script 실행은 명시적 승인 필요(보안 기본값 = 비 TTY 에서 exit 1).
+# 스캐폴드 첫 install 이 잡히지 않도록 완화하고, 실제 실행 허용 목록만 명시한다.
+# 정본 문서: https://pnpm.io/settings (구 package.json 의 pnpm 필드 대체).
+strictDepBuilds: false
+onlyBuiltDependencies:
+  - esbuild

package/dist/templates/project/shared/components/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/shared/composables/useDebounce.ts.tpl

@@ -0,0 +1,21 @@
+// useDebounce — shared 컴포저블(errata E-5 §2.2).
+// shared 는 shared 컴포넌트의 "props 로만" 규칙과 정확히 대칭이다:
+// gaonjs/vue 서브패스 import 금지 · domain 은 타입 import 만 · 인자로만
+// 받는 순수 로직. (`.gaon/routes.d.ts` 는 앱별 생성이라 구조적으로도
+// 라우트를 몰라야 한다.)
+
+/**
+ * fn 을 delay(ms) 만큼 지연 실행. 새 호출이 오면 이전 타이머를 취소한다.
+ * @param fn 실행할 함수 (인자로 받는다 — shared 는 라우트를 모른다).
+ * @param delay 지연 시간(ms).
+ */
+export function useDebounce<A extends readonly unknown[]>(
+  fn: (...args: A) => void,
+  delay: number,
+): (...args: A) => void {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  return (...args: A) => {
+    if (timer !== undefined) clearTimeout(timer)
+    timer = setTimeout(() => fn(...args), delay)
+  }
+}

package/dist/templates/project/tsconfig.json.tpl

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "jsx": "preserve",
+    "types": ["node"]
+  },
+  "include": [
+    "apps/**/*.ts",
+    "apps/**/*.vue",
+    "domain/**/*.ts",
+    "shared/**/*.ts",
+    "shared/**/*.vue",
+    "gaon.config.ts"
+  ],
+  "exclude": ["node_modules", "dist", ".gaon"]
+}

package/dist/templates/project/vite.config.ts.tpl

@@ -0,0 +1,23 @@
+// vite.config.ts — 프론트엔드 빌드/개발 서버 설정 (v0.16 §6.4).
+//
+// The One Way: gaon dev 가 Vite 를 middlewareMode 로 붙여 Fastify 한 포트로
+// 서빙한다(§CLAUDE.md 6 · 이 파일의 server 옵션은 그때 재정의된다). vite
+// build 는 이 파일을 그대로 사용한다.
+//
+// 앱이 하나 이상이면 각 앱마다 vite.config.ts 를 두는 것이 아니라, 이 루트
+// 파일 하나가 root 를 apps/<앱> 으로 잡고 여러 번 실행된다(gaon dev 가 앱별
+// Vite 서버를 띄운다). 관례가 곧 배치.
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  // 기본 앱은 apps/web · gaon dev 가 다른 앱에 대해 root 를 재정의한다.
+  root: 'apps/web',
+  plugins: [vue()],
+  build: {
+    outDir: '../../dist/web',
+    emptyOutDir: true,
+    // Inertia SPA 는 index.html 하나가 진입 · 라우팅은 서버 몫이다.
+    rollupOptions: {},
+  },
+})

package/dist/tsResolve.js

@@ -3,7 +3,7 @@
  *
  * 생성기(tables·routes)는 사용자 스키마·컨트롤러 .ts 를 런타임 동적
  * import 해 구조를 읽는다. TS-for-ESM 관례상 상대 import 는 `.js` 로
- * 쓰지만(`import { Post } from '../models/post.js'`), 개발 중 소스는
+ * 쓰지만(`import { Post } from '../models/Post.js'`), 개발 중 소스는
  * `.ts` 다 — Node 는 `.js`→`.ts` 재매핑을 하지 않아 그대로면 모듈을
  * 못 찾는다(vitest 는 Vite 가 재작성해 문제 없음, 실 gaon dev/check 만
  * 해당). 이 훅이 `.js` 가 없고 형제 `.ts` 가 있으면 `.ts` 로 넘긴다.

package/dist/work.d.ts

@@ -1,10 +1,10 @@
 export interface WorkCommandOptions {
     readonly json?: boolean;
-    /** NATS 접속지. 생략 시 GAON_NATS_URL, 그다음 기본(4222). */
+    /** NATS 접속지. 생략 시 NATS_URL(그다음 하위호환 GAON_NATS_URL), 기본(4222). */
     readonly natsUrl?: string;
     /** 도메인 루트(domain/ 의 부모). 기본 cwd. */
     readonly root?: string;
-    /** 아웃박스 릴레이용 DB URL. 생략 시 GAON_DATABASE_URL, 없으면 릴레이 미기동. */
+    /** 아웃박스 릴레이용 DB URL. 생략 시 DATABASE_URL(그다음 GAON_DATABASE_URL), 없으면 릴레이 미기동. */
     readonly databaseUrl?: string;
     /** 큐 기본 동시성. */
     readonly concurrency?: number;

package/dist/work.js

@@ -68,7 +68,9 @@ export async function runWorkCommand(opts = {}) {
     };
     const nats = await connectNats({ servers: opts.natsUrl, name: `work@${id}` });
     let db;
-    const dbUrl = opts.databaseUrl ?? process.env.GAON_DATABASE_URL;
+    // 스캐폴드 .env 관례(DATABASE_URL)를 정본으로 · GAON_DATABASE_URL 은 하위호환.
+    // serve(config 경유 DATABASE_URL)와 work 가 같은 env 를 보게 한다.
+    const dbUrl = opts.databaseUrl ?? process.env.DATABASE_URL ?? process.env.GAON_DATABASE_URL;
     if (dbUrl)
         db = createDb(dbConfigFromUrl(dbUrl));
     const domain = await loadDomain(root);