@gaonjs/cli 0.13.0 → 0.13.2

package/dist/templates/auth/Dashboard.vue.tpl

@@ -1,16 +1,22 @@
 <script setup lang="ts">
-import { pageProps } from 'gaonjs/vue'
+import { pageProps, router } from 'gaonjs/vue'
 
 // dashboard#show 의 render props — user 는 직렬화되며 passwordDigest 는 없다(§4.2).
-const { user } = pageProps<'{{APP_NAME}}:dashboard#show'>()
+const { user, csrf } = pageProps<'{{APP_NAME}}:dashboard#show'>()
+
+// 로그아웃 = DELETE /session (r.resource('session') 의 destroy).
+// HTML <form> 은 DELETE 를 보낼 수 없으므로 Inertia 라우터로 실제 메서드를
+// 보낸다(결정 64) — `?_method=DELETE` 우회는 서버가 해석하지 않아 POST /session
+// (= 로그인 create) 으로 잘못 라우팅됐다.
+function logout(): void {
+  router.delete('/session', { headers: { 'x-csrf-token': csrf } })
+}
 </script>
 
 <template>
   <main>
     <h1>환영합니다, {{ user.name }}님</h1>
     <p>{{ user.email }}</p>
-    <form method="post" action="/session?_method=DELETE">
-      <button type="submit">로그아웃</button>
-    </form>
+    <button type="button" @click="logout">로그아웃</button>
   </main>
 </template>

package/dist/templates/auth/Login.vue.tpl

@@ -1,18 +1,21 @@
 <script setup lang="ts">
-import { pageProps } from 'gaonjs/vue'
+import { pageProps, useForm } from 'gaonjs/vue'
 
 // 컨트롤러 session#new 의 render props 타입이 그대로 흐른다(§6.2).
 const { error, csrf } = pageProps<'{{APP_NAME}}:session#new'>()
+
+// 세션 앱 폼 = Inertia SPA 제출(결정 64) — fetch() 로 만들지 않는다.
+// 서버는 redirect(Inertia 응답)로 답하고, 실패 시 같은 페이지를 다시 render 한다.
+const form = useForm({ email: '', password: '', _csrf: csrf })
 </script>
 
 <template>
-  <form method="post" action="/session">
-    <input type="hidden" name="_csrf" :value="csrf" />
+  <form @submit.prevent="form.post('/session')">
     <h1>로그인</h1>
     <p v-if="error" class="error">{{ error }}</p>
-    <label>이메일 <input name="email" type="email" required /></label>
-    <label>비밀번호 <input name="password" type="password" required /></label>
-    <button type="submit">로그인</button>
+    <label>이메일 <input v-model="form.email" type="email" required /></label>
+    <label>비밀번호 <input v-model="form.password" type="password" required /></label>
+    <button type="submit" :disabled="form.processing">로그인</button>
     <a href="/registration/new">회원가입</a>
   </form>
 </template>

package/dist/templates/auth/Signup.vue.tpl

@@ -1,18 +1,20 @@
 <script setup lang="ts">
-import { pageProps } from 'gaonjs/vue'
+import { pageProps, useForm } from 'gaonjs/vue'
 
 const { error, csrf } = pageProps<'{{APP_NAME}}:registration#new'>()
+
+// 세션 앱 폼 = Inertia SPA 제출(결정 64) — fetch() 로 만들지 않는다.
+const form = useForm({ name: '', email: '', password: '', _csrf: csrf })
 </script>
 
 <template>
-  <form method="post" action="/registration">
-    <input type="hidden" name="_csrf" :value="csrf" />
+  <form @submit.prevent="form.post('/registration')">
     <h1>회원가입</h1>
     <p v-if="error" class="error">{{ error }}</p>
-    <label>이름 <input name="name" required /></label>
-    <label>이메일 <input name="email" type="email" required /></label>
-    <label>비밀번호 <input name="password" type="password" required /></label>
-    <button type="submit">회원가입</button>
+    <label>이름 <input v-model="form.name" required /></label>
+    <label>이메일 <input v-model="form.email" type="email" required /></label>
+    <label>비밀번호 <input v-model="form.password" type="password" required /></label>
+    <button type="submit" :disabled="form.processing">회원가입</button>
     <a href="/session/new">로그인</a>
   </form>
 </template>

package/dist/templates/auth/dashboard.controller.ts.tpl

@@ -5,6 +5,7 @@ export default controller({
   // GET /dashboard — 로그인해야 볼 수 있는 보호 페이지. 비로그인은 로그인으로 보내진다.
   async show() {
     const user = this.requireAuth()
-    return this.render('Dashboard', { user })
+    // csrf 는 로그아웃(DELETE /session · 결정 64)이 헤더로 실어 보낸다.
+    return this.render('Dashboard', { user, csrf: this.csrfToken() })
   },
 })

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

@@ -67,8 +67,9 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
    설정으로만 (`agents/security.md`).
 5. **테스트는 Docker 실인프라 필수** — DB·NATS 목업·인메모리 대체 절대
    금지 (§9 · `agents/testing.md`).
-6. **인증·폼은 Inertia SPA 방식** (SSR 아님). 폼은 `Inertia.post()` →
-   서버 redirect. REST + `fetch()` 는 **API 앱(JWT) 전용**.
+6. **인증·폼은 Inertia SPA 방식** (SSR 아님). 폼은 `gaonjs/vue` 의
+   `useForm(...).post(...)` → 서버 redirect (HTML 폼이 못 보내는 메서드는
+   `router.delete(...)` 등). REST + `fetch()` 는 **API 앱(JWT) 전용**.
 7. **한 액션은 한 종류 응답만** (render 또는 JSON 또는 redirect —
    혼용 금지 · doctor response-mixing).
 8. **`.gaon/` 자동 생성 파일 편집 금지** — `routes.d.ts`·`tables.d.ts`

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

@@ -434,6 +434,28 @@ gaon db seed          # domain/seed.ts 실행
 **파일명 순으로 실제 실행**(replay)하고, ② 그 뒤 스키마 diff 로 나머지를
 적용한다.
 
+- **replay 가 diff 보다 먼저다 — 손작성 마이그는 "아직 diff 가 안 만든 테이블"을
+  참조할 수 없다** (결정 65). 스키마에만 선언돼 있고 아직 DB 에 없는 테이블을
+  FK 로 거는 마이그레이션은 **빈 DB 에서만** `relation "posts" does not exist` 로
+  실패한다(테이블이 이미 있는 개발 DB 에서는 통과 — 그래서 CI·새 클론에서만
+  터진다). 조인 테이블처럼 남의 테이블을 참조해야 하면 **참조 대상도 같은/앞선
+  마이그 파일에서 함께 만든다**:
+
+  ```ts
+  // 20260728_add_tags.ts — posts 를 FK 로 걸려면 posts 가 먼저 존재해야 한다.
+  export async function up(db: Kysely<any>): Promise<void> {
+    await db.schema.createTable('tags')/* … */.execute()
+    await db.schema.createTable('posts_tags')
+      .addColumn('postId', 'bigint', (c) => c.notNull().references('posts.id').onDelete('cascade'))
+      // ↑ posts 가 스키마에만 있고 DB 에 없으면 빈 DB 에서 실패한다.
+      .execute()
+  }
+  ```
+
+  전부 스키마 우선으로 두면(손작성 마이그 없이) diff 가 의존 순서를 알아서
+  잡으므로 이 함정 자체가 없다 — **손작성 마이그는 diff 로 표현 못 하는 것에만**
+  쓴다(rename·백필·수동 DDL).
+
 - **손작성 마이그는 `db/migrations/<파일명>.ts`** 에 두고 `up(db)`·`down(db)`
   (Kysely) 를 export 한다. **파일명이 곧 버전 키** — `0001_add_posts.ts`
   시퀀스든 `20260724_add_posts.ts` 타임스탬프든 사전순 정렬이 안정적이면 된다

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

@@ -94,14 +94,22 @@ const members = await ctx.presence()
 브라우저는 표준 WebSocket 으로 채널에 접속한다. 세션 앱은 세션 쿠키로,
 JWT 앱은 쿼리(`access_token`)로 인증한다.
 
+**경로는 `<앱 프리픽스>/gaon/ws/<채널명>`** 이고, 보내는 프레임은 `{ t: 'msg',
+data }` **봉투** 다 — 날 페이로드를 그대로 보내면 서버가 `onMessage` 로
+흘리지 않는다. 받는 프레임도 같은 모양(`t` 로 종류를 가른다).
+
 ```ts
-// 브라우저측 (요지) — 채널 구독 래핑은 컴포저블에 (agents/frontend.md)
-const ws = new WebSocket(`wss://example.com/channels/room?room=42`)
+// 브라우저측 — 채널 구독 래핑은 컴포저블에 (agents/frontend.md)
+// web 앱(프리픽스 /)의 room 채널 = /gaon/ws/room. admin 앱이면 /admin/gaon/ws/room.
+const ws = new WebSocket(`wss://example.com/gaon/ws/room?room=42`)
 ws.onmessage = (ev) => {
-  const msg = JSON.parse(ev.data)
-  // 서버가 broadcast/send 한 데이터 · 프레즌스 델타
+  const frame = JSON.parse(ev.data)      // { t: 'msg' | 'presence' | ... , data }
+  if (frame.t === 'msg') {
+    // 서버가 broadcast/send 한 데이터
+  }
 }
-ws.send(JSON.stringify({ text: '안녕하세요' }))   // onMessage 로 전달
+// 보낼 때도 봉투로 감싼다 — 이래야 채널의 onMessage 가 호출된다.
+ws.send(JSON.stringify({ t: 'msg', data: { text: '안녕하세요' } }))
 ```
 
 ### 5. 허브 프로세스 (`gaon hub`)

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

@@ -105,10 +105,26 @@ export default controller({
 데이터가 필요할 때는 루트 `AGENTS.md` 의 데이터 경로 4종 판단표를 따른다
 (Inertia partial reload · 채널/프레즌스 · JSON 액션 + `api()` · 별도 API 앱 + JWT).
 **Inertia = SPA + 서버 라우팅**이지 SSR 이 아니다. 로그인·회원가입도 컨트롤러
-`this.render('auth/Login')` + Vue 페이지 `Inertia.post()` → 서버
+`this.render('Auth/Login')` + Vue 페이지의 `useForm(...).post(...)` → 서버
 redirect 로 처리한다 — 전체 페이지 리로드도, 별도 REST 엔드포인트도
 없다. REST + `fetch()` 는 **API 앱(JWT) 전용**.
 
+폼 API 는 **`gaonjs/vue` 의 `useForm`·`router`** 뿐이다(결정 64) —
+`@inertiajs/vue3` 를 직접 import 하지 않는다(파사드가 The One Way).
+
+```ts
+// 로그인 폼 — 제출은 Inertia SPA 방식, 서버는 redirect 로 답한다.
+const { error, csrf } = pageProps<'web:session#new'>()
+const form = useForm({ email: '', password: '', _csrf: csrf })
+// <form @submit.prevent="form.post('/session')">
+
+// HTML <form> 이 못 보내는 메서드(DELETE 등)는 router 로 보낸다.
+router.delete('/session', { headers: { 'x-csrf-token': csrf } })
+```
+
+`?_method=DELETE` 같은 우회는 **서버가 해석하지 않는다** — POST 로 나가
+엉뚱한 액션(create)에 도달한다.
+
 ### 5. 비밀번호 해싱 — `hashPassword` · `verifyPassword` (`gaonjs/web`)
 
 회원가입·로그인에서 비밀번호를 다룰 때는 **직접 crypto/bcrypt 를 import 하거나
@@ -156,6 +172,35 @@ const ok = await verifyPassword(plain, user.passwordDigest) // Promise<boolean>
   }
   ```
 
+- **세션을 확정·해제하는 것은 `this.auth`** (결정 65). `requireAuth()` 는 이미
+  로그인된 요청을 **지키는** 쪽이고, 로그인 자체를 **성립시키는** 호출은 따로다:
+
+  | 호출 | 하는 일 |
+  |---|---|
+  | `this.auth.user` | 현재 사용자 (`GaonCurrentUser \| null`) |
+  | `this.auth.login(user)` | 세션에 사용자 id 를 심어 로그인 상태로 만든다 |
+  | `this.auth.logout()` | 세션에서 사용자를 지운다 |
+
+  ```ts
+  // 로그인 — 폼 액션의 유일한 render+redirect 혼용 예외(결정 57 보완)
+  async create() {
+    const { email, password } = this.params({ _row: {} as { email: string; password: string } })
+    const user = await User.where('email', '=', email).first()
+    if (!user || !(await verifyPassword(password, user.passwordDigest))) {
+      return this.render('Auth/Login', { error: '이메일 또는 비밀번호가 올바르지 않습니다.', csrf: this.csrfToken() })
+    }
+    this.auth.login(user)                       // 세션 확정
+    return this.redirect('/dashboard')
+  }
+  // 로그아웃 — DELETE /session (페이지에서 router.delete 로 호출 · 결정 64)
+  async destroy() {
+    this.auth.logout()
+    return this.redirect('/session/new')
+  }
+  ```
+
+  API 앱(JWT)은 세션 대신 `this.jwt.issue(user)` / `this.jwt.refresh(token)` 를 쓴다.
+
 - **`this.auth.user`/`requireAuth()` 사용자 타입은 앱이 증강한다** (결정 58).
   `GaonCurrentUser` 는 빈 인터페이스라 증강 없이는 `user.id` 접근이 타입에러다.
   `gaon g auth` 가 `apps/<app>/auth.ts` 에 심는다:
@@ -220,8 +265,8 @@ export default controller({
 - **render/JSON/redirect 를 한 액션에서 조건 혼용하면 doctor
   response-mixing 위반** — 액션을 나눈다. 예외는 폼 액션의
   "실패 render + 성공 redirect" 조합 하나뿐(결정 57 보완).
-- **`fetch()` 로 로그인 폼 구현 금지** — 세션 앱 폼은 `Inertia.post()`.
-  REST + fetch 는 API 앱(JWT) 전용.
+- **`fetch()` 로 로그인 폼 구현 금지** — 세션 앱 폼은 `gaonjs/vue` 의
+  `useForm(...).post(...)`(결정 64). REST + fetch 는 API 앱(JWT) 전용.
 - **컨트롤러에 비즈니스 로직 인라인 금지** (§5.3 One Way) — 여러 모델·
   트랜잭션·외부 API 가 얽히면 `domain/services/`.
 - **컨트롤러에서 메일·외부 발송 직접 호출 금지** — 잡 발행만

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -28,11 +28,11 @@
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
     "@gaonjs/async": "0.3.1",
-    "@gaonjs/config": "0.3.0",
-    "@gaonjs/web": "0.5.3",
+    "@gaonjs/core": "0.1.4",
     "@gaonjs/mail": "0.1.1",
     "@gaonjs/data": "0.8.4",
-    "@gaonjs/core": "0.1.4"
+    "@gaonjs/web": "0.5.3",
+    "@gaonjs/config": "0.3.0"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""