@gaonjs/cli 0.15.0 → 0.18.0

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

@@ -36,8 +36,9 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 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) 전용.
+    `this.render('Auth/Login')` + `gaonjs/vue` 의 `useForm(...).post()`
+    (DELETE 등은 `router`) → 서버 redirect(결정 64). REST + `fetch()`
+    는 API 앱(JWT) 전용.
 11. **컴포저블·레이아웃**(errata E-5): 컴포저블은 컴포넌트와 대칭
     (`apps/<앱>/composables/` + `shared/composables/`, `use` 접두사).
     shared 컴포저블은 인자로만 받는 순수 로직(api·pageProps 금지).

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

@@ -115,21 +115,29 @@ await OrderPlaced.emit({ orderId: 1n })
 ### 4. 아웃박스 (트랜잭션 정합)
 
 이벤트를 DB 트랜잭션과 **원자적으로** 발행하려면 아웃박스를 쓴다.
-`runInTransaction` 안에서 발행한 이벤트는 같은 트랜잭션의 아웃박스
-테이블에 스테이징되고, 트랜잭션이 커밋돼야 릴레이가 실제로 NATS 에
-발행한다. 트랜잭션이 롤백되면 이벤트도 사라진다.
+트랜잭션 안에서 발행한 이벤트는 같은 트랜잭션의 아웃박스 테이블에
+스테이징되고, 트랜잭션이 커밋돼야 릴레이가 실제로 NATS 에 발행한다.
+트랜잭션이 롤백되면 이벤트도 사라진다. `service()` 본문 전체가 한
+트랜잭션이므로(§서비스), 본문 안 `emit` 이 곧 아웃박스 스테이징이다.
 
 ```ts
-import { runInTransaction } from 'gaonjs/async'
+// domain/services/placeOrder.ts — service() 본문 = 한 트랜잭션.
+import { service } from 'gaonjs/service'
+import { Order } from '../models/Order.js'
+import { OrderPlaced } from '../events/orderPlaced.js'
 
-await runInTransaction(async () => {
-  await Order.create({ /* … */ })
-  await OrderPlaced.emit({ orderId })   // 커밋돼야 실제 발행됨
+export const PlaceOrder = service(async (input: { name: string }) => {
+  const order = await Order.create(input)
+  await OrderPlaced.emit({ orderId: order.id })   // 트랜잭션 안 → 아웃박스 스테이징 · 커밋돼야 발행
+  return order
 })
 ```
 
 - 트랜잭션 안의 `emit` 은 `AsyncLocalStorage` 로 투명하게 감지돼
   아웃박스에 스테이징된다(별도 API 호출 불필요).
+- 저수준 원시는 `runInTransaction(db, fn)`(커넥션을 넘긴다) — `service()`
+  가 내부에서 이를 쓴다. 대부분의 도메인 코드는 `service()` 본문에서
+  emit 하거나, "커밋 후 즉시 발행"이면 `afterCommit(fn)`(§서비스)을 쓴다.
 - 릴레이(`gaon work` 내장)가 `SKIP LOCKED` 로 아웃박스를 폴링해 발행
   한다 (기본 폴 1000ms · 배치 100).
 - at-least-once — 발행 후 표시하므로 중복 가능성이 있고, dedup(msgID)이

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

@@ -160,8 +160,13 @@ import 한다. `gaon doctor` 의 **no-auto-import** 검사가 자동 import
 이 엔드포인트는 `gaon dev` 에서만 등록되고(운영 빌드엔 없음), 404 면 컴포저블이
 `available=false` 로 우아하게 degrade 한다.
 
-- **스타일은 SFC `<style scoped>` + CSS 변수** — 스캐폴드에 Tailwind 를 넣지
-  않는다(의존성 경량 · 결정 69). 유틸 클래스 대신 scoped CSS 로 캡슐화.
+- **HUB 카드는 실 introspection(결정 71)** — jobs = JetStream 스트림 대기(pending)
+  수 · channels = 프레즌스 KV 권위의 채널별 실 접속자 수. 조회 실패·미접속을 0/true
+  로 가장하지 않는다(과대 약속 금지) — 버킷·스트림 미생성이면 각각 null 로 degrade.
+- **스타일은 Tailwind 유틸 + UI 킷(결정 74·75)** — 스캐폴드는 Tailwind
+  (`tailwind.config.ts`·`postcss.config.js`·`apps/<앱>/style.css`)를 편입한다.
+  랜딩·auth 페이지는 Tailwind 유틸과 UI 킷 컴포넌트(§8)로 그린다(결정 69 의
+  scoped-CSS 미편입 방침은 결정 74 로 뒤집혔다).
 - **auth 링크는 수동(결정 70)** — `gaon g auth` 는 auth 페이지·라우트만 신설하고
   랜딩·레이아웃 nav 를 편집하지 않는다. 헤더에 로그인 링크를 두려면 `Default.vue`
   의 nav 에 `<a href="/session/new">로그인</a>` 을 직접 추가한다(Rails 관례).
@@ -169,6 +174,55 @@ import 한다. `gaon doctor` 의 **no-auto-import** 검사가 자동 import
   ·`Auth/Signup.vue` 를 내고 컨트롤러는 `this.render('Auth/Login')` 로 부른다.
   소문자 `auth/` 는 doctor page-filename 이 잡는다(결정 32·46).
 
+### 8. UI 킷 (결정 74·75 · shadcn 참조 · 복사-소유)
+
+`gaon new` 는 기본 앱에 UI 킷을 심고(배터리 포함), `gaon g ui-kit [--app <앱>]`
+로 다른 앱에도 추가한다. 컴포넌트는 **프로젝트에 복사된 여러분 코드**다 — npm
+의존이 아니라 파일이므로 자유롭게 고친다(shadcn 방식). 외부 런타임 의존이 없다
+(clsx·tailwind-merge·cva·reka-ui 미도입 · `cn` 은 자작 · Dialog/Sheet 는 Teleport+
+Transition 자작).
+
+배치·import:
+
+```
+apps/<앱>/lib/utils.ts            # cn() — 조건부 클래스 병합
+apps/<앱>/components/ui/*.vue      # Button·Input·Label·Badge·Card…·Alert…·Form…·Dialog·Sheet
+```
+
+```vue
+<script setup lang="ts">
+import Button from '../../components/ui/Button.vue'   // 앱 로컬 · 상대 경로
+import Card from '../../components/ui/Card.vue'
+import CardContent from '../../components/ui/CardContent.vue'
+</script>
+
+<template>
+  <Card>
+    <CardContent>
+      <Button variant="default">저장</Button>       <!-- variant·size 로 모양 선택 -->
+    </CardContent>
+  </Card>
+</template>
+```
+
+- **폼은 UI 킷 Form + gaonjs `useForm`(결정 64)** — `Form` 은 얇은 `<form>` 래퍼로
+  `@submit` 을 `useForm` 의 `post/put/delete` 로 넘긴다. vee-validate 를 끌어오지
+  않는다(검증·상태는 `useForm`). `FormField label error` + `FormMessage` 로 라벨·
+  오류를 붙이고, `:error="form.errors.<field>"` 로 서버 검증을 표시한다.
+- **`class` 는 폴스루로 병합** — 단일 루트 컴포넌트는 `<Button class="w-full">` 처럼
+  넘긴 클래스가 루트로 흘러간다(별도 `class` prop 선언 없음). `cn` 은 충돌 클래스
+  자동 해소를 하지 않는다 — 오버라이드가 잦으면 tailwind-merge 를 설치해 `cn` 만 교체.
+- **디자인 토큰은 `style.css` 한 곳(결정 74)** — 컴포넌트는 `bg-primary`·
+  `text-muted-foreground` 같은 의미 토큰만 쓰고, 실색은 `apps/<앱>/style.css` 의
+  `:root`/`.dark` CSS 변수에서 바꾼다(다크 모드 = `<html class="dark">`).
+- **멀티앱은 앱마다 배선이 따로다(결정 76)** — `gaon g app admin` 은 새 앱에
+  프론트 배선(`apps/admin/{style.css,main.ts,index.html}`)을 web 앱과 동등하게
+  함께 심는다. 그래서 `gaon g ui-kit --app admin` 으로 심은 UI 킷이 Tailwind
+  유틸을 그대로 받는다(`g ui-kit --app` 은 배선이 없으면 멱등으로 보정한다).
+  `tailwind.config.ts`·`postcss.config.js` 는 프로젝트 루트 공유(앱마다 두지
+  않는다). 앱이 UI 킷을 import 하는데 그 앱에 `style.css` 배선이 없으면 doctor
+  **ui-kit-wiring** 이 경고한다.
+
 ## 정본 예시
 
 ```vue
@@ -204,7 +258,7 @@ async function runSearch(q: string) {
 - **shared 컴포넌트/컴포저블에서 `pageProps`/`api` 호출 금지** — doctor
   shared-composable-purity 위반. 데이터는 props/인자로.
 - **Vue 페이지에서 `fetch()` 로 폼 구현 금지** — 세션 앱 폼은
-  `Inertia.post()` (`agents/web.md` §4).
+  `gaonjs/vue` 의 `useForm(...).post()` (`agents/web.md` §4 · 결정 64).
 - **레이아웃을 shared 에 두지 않는다** — 앱별이 정상.
 - **페이지 파일명은 PascalCase** — `pages/Posts/Index.vue`(폴더 세그먼트도
   Route 이름). 소문자(`posts/index.vue`)는 doctor **page-filename** 이 잡는다
@@ -221,6 +275,10 @@ async function runSearch(q: string) {
 | 결정 25 (E-5) | 컴포저블·레이아웃 관례 · 프론트 로직 배치 3규칙 · 자동 import 금지 |
 | 결정 37 | bigint PK 컨트롤러 `String()` 정규화 |
 | 결정 46 | doctor page-filename(페이지 PascalCase)·model/column 검사 3종 |
-| 결정 69 | 랜딩 정본(라이브 헬스 카드 · 다크 헤더 레이아웃 · Tailwind 미편입 · scoped CSS) |
+| 결정 69 | 랜딩 정본(라이브 헬스 카드 · 다크 헤더 레이아웃 · 실 상태 · 코드 블록) |
 | 결정 70 | auth 통합 = 수동(`gaon g auth` 는 랜딩·nav 를 안 건드림 · Rails 관례) |
+| 결정 71 | HUB 카드 실 introspection(jobs=스트림 pending · channels=프레즌스 실 접속자 · 과대 약속 금지) |
+| 결정 74 | Tailwind 스캐폴드 편입(tailwind.config.ts·postcss.config.js·style.css · 결정 69 scoped-CSS 방침 뒤집기) |
+| 결정 75 | shadcn 식 UI 킷(`gaon g ui-kit` · 복사-소유 · Vue 3 신작 · 외부 런타임 의존 0) |
+| 결정 76 | 멀티앱 UI 킷 배선 자동화(`g app`·`g ui-kit --app` 이 앱별 Tailwind 배선 동봉·멱등 보정 · doctor ui-kit-wiring) |
 | E-3 §C | 타입드 `api()` 클라이언트 (routes.d.ts 브리지 재사용) |

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

@@ -28,7 +28,9 @@ export interface HealthDatabase {
 export interface HealthHub {
   configured: boolean
   connected?: boolean
+  // jobs: JetStream 스트림 대기 수 · channels: 채널별 실 접속자 수(결정 71).
   streams?: { stream: string; waiting: number | null }[]
+  channels?: { channel: string; members: number }[] | null
   error?: string
 }
 export interface HealthDoctor {

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

@@ -6,114 +6,39 @@
 // 레이아웃은 shared 에 두지 않는다(E-5 §2.3) — 앱마다 레이아웃이 다른 것이
 // 정상이고, 공용 조각(로고·푸터 등) 만 shared/components 로 뽑는다.
 //
-// 다크 헤더 + 라이트 본문(결정 69). 버전은 스캐폴드 시점 gaonjs 버전이 박힌다.
-//
-// 결정 70(auth = 수동): gaon g auth 는 이 nav 를 건드리지 않는다. 로그인 링크를
-// 헤더에 두려면 아래 nav 에 <a href="/session/new">로그인</a> 을 직접 추가한다.
+// 다크 헤더 + 라이트 본문(결정 69). 스타일은 Tailwind 유틸(결정 74) — 다크
+// 헤더는 본문 테마와 무관하게 항상 어둡게 두려고 브랜드 색을 명시값으로 박는다.
+// 버전은 스캐폴드 시점 gaonjs 버전이 박힌다.
 
 // package.json 의 gaonjs 의존 범위(예: ^0.9.2)에서 캐럿·틸드를 벗겨 표기.
 const version = '{{GAONJS_VERSION}}'.replace(/^[\^~]/, '')
 </script>
 
 <template>
-  <div class="gaon-layout">
-    <header class="gaon-header">
-      <a class="gaon-brand" href="/">
-        <span class="gaon-brand-mark">가온</span>
-        <span class="gaon-brand-word">GAONJS</span>
-        <span class="gaon-brand-ver">v{{ version }}</span>
+  <div class="flex min-h-screen flex-col bg-background text-foreground">
+    <header
+      class="flex items-center justify-between gap-4 border-b border-[#21262d] bg-[#0d1117] px-6 py-3.5 text-[#e6edf3]"
+    >
+      <a href="/" class="inline-flex items-baseline gap-2.5 text-inherit no-underline">
+        <span
+          class="inline-block rounded-md bg-gradient-to-br from-[#4f8cff] to-[#7c5cff] px-1.5 py-0.5 text-xs font-bold tracking-wide text-white"
+        >가온</span>
+        <span class="text-[0.95rem] font-bold tracking-[0.08em]">GAONJS</span>
+        <span class="text-xs tabular-nums text-[#8b949e]">v{{ version }}</span>
       </a>
-      <nav class="gaon-nav">
-        <a href="https://gaonjs.dev" target="_blank" rel="noreferrer">문서</a>
-        <a href="https://github.com/gaonjs" target="_blank" rel="noreferrer">GitHub</a>
+      <nav class="flex gap-[1.1rem] text-sm">
+        <a href="https://gaonjs.dev" target="_blank" rel="noreferrer" class="text-[#c9d1d9] no-underline hover:text-white">문서</a>
+        <a href="https://github.com/gaonjs" target="_blank" rel="noreferrer" class="text-[#c9d1d9] no-underline hover:text-white">GitHub</a>
       </nav>
     </header>
 
-    <main class="gaon-main">
+    <main class="w-full flex-1">
       <slot />
     </main>
 
-    <footer class="gaon-footer">
+    <footer class="border-t border-border px-6 py-5 text-center text-muted-foreground">
       <small>{{PROJECT_NAME}} · Powered by
-        <a href="https://gaonjs.dev" target="_blank" rel="noreferrer">Gaon</a></small>
+        <a href="https://gaonjs.dev" target="_blank" rel="noreferrer" class="text-[#4f8cff] no-underline">Gaon</a></small>
     </footer>
   </div>
 </template>
-
-<style scoped>
-.gaon-layout {
-  min-height: 100vh;
-  display: flex;
-  flex-direction: column;
-  background: #ffffff;
-  color: #1b1f24;
-  font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
-}
-
-/* 다크 헤더 — 본문 테마와 무관하게 브랜드 바는 어둡게. */
-.gaon-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 1rem;
-  padding: 0.85rem 1.5rem;
-  background: #0d1117;
-  color: #e6edf3;
-  border-bottom: 1px solid #21262d;
-}
-.gaon-brand {
-  display: inline-flex;
-  align-items: baseline;
-  gap: 0.55rem;
-  text-decoration: none;
-  color: inherit;
-}
-.gaon-brand-mark {
-  display: inline-block;
-  padding: 0.15rem 0.45rem;
-  border-radius: 6px;
-  background: linear-gradient(135deg, #4f8cff, #7c5cff);
-  color: #fff;
-  font-weight: 700;
-  font-size: 0.8rem;
-  letter-spacing: 0.02em;
-}
-.gaon-brand-word {
-  font-weight: 700;
-  letter-spacing: 0.08em;
-  font-size: 0.95rem;
-}
-.gaon-brand-ver {
-  font-size: 0.72rem;
-  color: #8b949e;
-  font-variant-numeric: tabular-nums;
-}
-.gaon-nav {
-  display: flex;
-  gap: 1.1rem;
-  font-size: 0.85rem;
-}
-.gaon-nav a {
-  color: #c9d1d9;
-  text-decoration: none;
-}
-.gaon-nav a:hover {
-  color: #fff;
-}
-
-.gaon-main {
-  flex: 1;
-  width: 100%;
-}
-
-.gaon-footer {
-  padding: 1.25rem 1.5rem;
-  text-align: center;
-  color: #6a737d;
-  border-top: 1px solid #eaecef;
-}
-.gaon-footer a {
-  color: #4f8cff;
-  text-decoration: none;
-}
-</style>

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

@@ -9,6 +9,10 @@
 // import.meta.glob 으로 만든다. 심볼 출처가 코드에 그대로 보인다.
 import { createGaonApp } from 'gaonjs/vue'
 
+// 전역 스타일 — Tailwind 레이어 + 디자인 토큰(결정 74). 부수효과 import 라
+// 번들에 CSS 가 실린다. 앱마다 하나(관례 = 배치).
+import './style.css'
+
 // 페이지는 지연 로드(코드 스플리팅) — 큰 앱에서도 첫 페이지 로딩이 빠르다.
 // eager 로 바꿔도 되지만, One Way 의 기본은 지연 로드다.
 const pages = import.meta.glob('./pages/**/*.vue')