@gaonjs/cli 0.34.0 → 0.35.0

package/dist/generate.d.ts

@@ -20,6 +20,19 @@ export interface ScaffoldResult {
     /** 손 수리가 필요한 지점 — 수리 안내 문장(§7.5.3)을 그대로 담는다. */
     readonly warnings: string[];
 }
+/**
+ * 결정 155·142: `g auth --app <앱>` 이 앱별 세션 secret 환경변수를 .env·.env.example
+ * 에도 시드한다. web 은 SESSION_SECRET 이 프로젝트 스캐폴드(.env.example.tpl)에 이미
+ * 있어 no-op 이지만, 비-web 앱(admin 등)은 이 키가 어디에도 없어 app.config 의
+ * `process.env.ADMIN_SESSION_SECRET ?? '공개 고정 dev secret'` 이 조용히 폴백으로
+ * 돌아 세션 위조 표면이 된다. env 파일에 키를 심어 사용자가 설정해야 함을 드러낸다
+ * (앱별 세션 완전 분리를 env 층까지 확장).
+ *
+ * 이미 그 키가 있으면 건드리지 않는다(멱등). 파일이 없으면 만들지 않는다 — 스캐폴드가
+ * .env 를 새로 만드는 관례가 없어(사용자가 cp .env.example .env), 존재하는 파일만 패치한다.
+ * 반환: 실제로 키를 추가한 상대 경로들.
+ */
+export declare function patchEnvFiles(root: string, app: string): string[];
 /** 인증 스캐폴드가 생성하는 파일 목록(라우트 제외). 템플릿을 읽어 렌더링한다.
  *  결정 155: 공개 가입 여부(includePublic)로 registration·Signup·dashboard 변형을 가른다. */
 export declare function authScaffoldFiles(opts?: AuthScaffoldOptions): ScaffoldFile[];

package/dist/generate.js

@@ -47,6 +47,41 @@ function sessionSecretEnvFor(app) {
 function devSessionSecretFor(app) {
     return `dev-only-session-secret-${app}-change-me-now!!`;
 }
+/** .env(.example)에 시드할 앱별 세션 secret 플레이스홀더 값(32자 이상 · 운영은 교체). */
+function envSecretPlaceholderFor(app) {
+    return `change-me-to-a-32-char-${app}-session-secret!!`;
+}
+/**
+ * 결정 155·142: `g auth --app <앱>` 이 앱별 세션 secret 환경변수를 .env·.env.example
+ * 에도 시드한다. web 은 SESSION_SECRET 이 프로젝트 스캐폴드(.env.example.tpl)에 이미
+ * 있어 no-op 이지만, 비-web 앱(admin 등)은 이 키가 어디에도 없어 app.config 의
+ * `process.env.ADMIN_SESSION_SECRET ?? '공개 고정 dev secret'` 이 조용히 폴백으로
+ * 돌아 세션 위조 표면이 된다. env 파일에 키를 심어 사용자가 설정해야 함을 드러낸다
+ * (앱별 세션 완전 분리를 env 층까지 확장).
+ *
+ * 이미 그 키가 있으면 건드리지 않는다(멱등). 파일이 없으면 만들지 않는다 — 스캐폴드가
+ * .env 를 새로 만드는 관례가 없어(사용자가 cp .env.example .env), 존재하는 파일만 패치한다.
+ * 반환: 실제로 키를 추가한 상대 경로들.
+ */
+export function patchEnvFiles(root, app) {
+    const secretEnv = sessionSecretEnvFor(app);
+    const patched = [];
+    for (const rel of ['.env', '.env.example']) {
+        const abs = join(root, rel);
+        if (!existsSync(abs))
+            continue;
+        const existing = readFileSync(abs, 'utf8');
+        // 라인 시작에서 `KEY=` 를 찾는다(주석·부분 일치 회피).
+        if (new RegExp(`^${secretEnv}=`, 'm').test(existing))
+            continue;
+        const block = `\n# ${app} 앱 세션 secret (32자 이상 · 앱별 세션 완전 분리 · 운영은 반드시 교체).\n` +
+            `${secretEnv}=${envSecretPlaceholderFor(app)}\n`;
+        const sep = existing.endsWith('\n') ? '' : '\n';
+        writeFileSync(abs, existing + sep + block, 'utf8');
+        patched.push(rel);
+    }
+    return patched;
+}
 /** 결정 155: Login 페이지의 회원가입 링크 — 공개 가입 앱에만 넣는다(시큐어 앱은 뺀다).
  *  템플릿의 `{{SIGNUP_LINK}}` 자리(8칸 들여쓰기)에 in-place 치환되므로 첫 줄은 들여쓰기 없이. */
 function signupLinkMarkup(app) {
@@ -228,6 +263,9 @@ export function writeAuthScaffold(cwd, opts = {}) {
         writeFileSync(routesPath, renderTemplate('routes.ts.tpl', app, includePublic), 'utf8');
         created.push(routesRel);
     }
+    // 결정 155·142(W3): 앱별 세션 secret 을 .env·.env.example 에 시드한다. web 은 이미
+    // 있어 멱등, 비-web 앱은 여기서 키가 심어져 "공개 고정 dev secret 폴백" 표면을 막는다.
+    patched.push(...patchEnvFiles(root, app));
     // 결정 155: 시큐어 앱(공개 가입 미생성)은 역할 게이트 대시보드를 깔았다 — role 컬럼을
     // 두라고 안내한다(§7.5.3 · authorize 예시가 실제 역할 규칙이 되도록).
     if (!includePublic) {
@@ -248,6 +286,7 @@ export function runGenerateAuthCommand(opts = {}) {
         process.stdout.write(JSON.stringify({ command: 'g auth', app, public: opts.public ?? app === 'web', ...result }, null, 2) + '\n');
         return 0;
     }
+    const includePublic = includesPublicRegistration({ app, public: opts.public });
     const lines = [''];
     lines.push(`  gaon g auth — 인증 스캐폴드 (${app} 앱)`);
     lines.push('');
@@ -266,7 +305,17 @@ export function runGenerateAuthCommand(opts = {}) {
     lines.push(`   1) .env 에 REDIS_URL·${secretEnv}(32자 이상)·COOKIE_SECRET 을 설정한다.`);
     lines.push('   2) gaon db diff && gaon db migrate 로 users 테이블을 만든다.');
     lines.push('   3) gaon dev 로 실행한다 (.gaon 타입 브리지 생성 + 세션·인증 자동 배선).');
-    lines.push(`   → ${prefix}/registration/new 회원가입 · ${prefix}/session/new 로그인 · ${prefix}/dashboard 보호 페이지 (this.requireAuth()).`);
+    // 결정 155(W4): 안내문을 실제 산출물과 정합시킨다. 시큐어 스캐폴드(비-web · 비-public)는
+    // 공개 가입을 안 깔았으므로 없는 /registration/new 경로를 광고하지 않는다 — 대신 역할
+    // 부여 경로(seed/DB)와 필요 시 --public 을 안내한다(생성물 ≠ 안내문 자기모순 제거).
+    if (includePublic) {
+        lines.push(`   → ${prefix}/registration/new 회원가입 · ${prefix}/session/new 로그인 · ${prefix}/dashboard 보호 페이지 (this.requireAuth()).`);
+    }
+    else {
+        lines.push(`   → ${prefix}/session/new 로그인 · ${prefix}/dashboard 보호 페이지 (this.requireAuth()).`);
+        lines.push(`   → 공개 회원가입 없음(시큐어 스캐폴드). 관리자 계정은 seed/DB 로 만들거나 승격하세요.`);
+        lines.push(`     공개 가입이 필요하면: gaon g auth --app ${app} --public`);
+    }
     lines.push('');
     process.stdout.write(lines.join('\n') + '\n');
     return 0;

package/dist/templates/auth/app.ts.tpl

@@ -0,0 +1,29 @@
+// 웹 앱 팩토리 — gaon g auth 스캐폴드. createWebApp 으로 세션·인증을 배선한다.
+import { createApp, type AppSessionOptions } from 'gaonjs/web'
+import appRoutes from './routes.js'
+import session from './controllers/session.js'
+import registration from './controllers/registration.js'
+import dashboard from './controllers/dashboard.js'
+import { loadUser } from './auth.js'
+
+export interface WebAppDeps {
+  /** 세션 설정 — { redisUrl, secret } (또는 redis 인스턴스). */
+  readonly session: AppSessionOptions
+  /** 서명 쿠키/CSRF 용 비밀. */
+  readonly cookieSecret?: string
+}
+
+export function createWebApp(deps: WebAppDeps) {
+  return createApp({
+    apps: [
+      {
+        name: '{{APP_NAME}}',
+        routes: appRoutes,
+        controllers: { session, registration, dashboard },
+        session: deps.session,
+        auth: { loadUser, loginRedirect: '/session/new' },
+      },
+    ],
+    cookieSecret: deps.cookieSecret,
+  })
+}

package/dist/templates/auth/server.ts.tpl

@@ -0,0 +1,14 @@
+// 서버 진입점 — gaon g auth 스캐폴드. `node dist/server.js` 로 실행.
+import { createWebApp } from './apps/{{APP_NAME}}/app.js'
+
+const app = await createWebApp({
+  session: {
+    redisUrl: process.env.REDIS_URL ?? 'redis://127.0.0.1:6379',
+    secret: process.env.SESSION_SECRET ?? 'change-me-to-a-32+char-random-secret!!',
+  },
+  cookieSecret: process.env.COOKIE_SECRET,
+})
+
+const port = Number(process.env.PORT ?? 3000)
+await app.listen({ port, host: '0.0.0.0' })
+console.log(`web 앱이 http://localhost:${port} 에서 실행 중입니다.`)

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

@@ -664,6 +664,29 @@ diff/migrate/status/seed 는 `--db` 를 생략하면 **등록된 전 커넥션
   미리 보여주고, migrate 는 건너뛴 테이블을 크게 알린다(조용한 무시 방지).
 - 마이그레이션은 커넥션별로 돈다(§7 · `--db <키>`).
 
+### 10.1 시드 — `domain/seed.ts` · `seed()` (§7)
+
+개발·데모용 초기 데이터를 `domain/seed.ts` 한 파일에 선언하고 `gaon db seed` 로
+실행한다. 파일이 존재하면 등록이고, **default export** 가 시드 정의여야 한다.
+
+- **시그니처**: `seed(fn: () => Promise<void> | void): SeedDef` — `gaonjs/data`
+  에서 import 한다. 본문(`fn`)은 **모델을 그대로** 쓴다 — 모델이 커넥션을 자동
+  바인딩하므로(§4.5·§7) 시드는 커넥션을 몰라도 된다.
+- **멱등하게 짠다** — 시드는 재적재에 자주 쓰이므로 여러 번 돌려도 안전해야
+  한다(예: `upsert`/존재 확인 후 생성).
+- `gaon db seed` 는 모델 레이어를 거치므로 **프로젝트 로컬로 실행**하는 것이
+  정본이다(`npx gaon db seed` · 결정 156 · 위 dual package hazard 노트).
+
+```ts
+// domain/seed.ts
+import { seed } from 'gaonjs/data'
+import { User } from './models/User'
+
+export default seed(async () => {
+  await User.create({ email: 'admin@example.com', name: 'Admin' })
+})
+```
+
 ## 정본 예시
 
 ```ts

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

@@ -58,15 +58,32 @@
   · 결정 145)를 예시로 깔고, `domain/schema/users.ts` 에 `role` 컬럼을 두라고 안내한다.
   관리자는 직접 만들거나 승격한다(공개 가입 라우트 없음). web 앱은 현행대로 공개 가입 O.
   공개 비-web 앱이 필요하면 `--public` 로 공개 가입을 opt-in 한다.
-- CSRF: 세션 앱은 상태 변경 메서드(POST/PUT/PATCH/DELETE)에 CSRF
-  강제. `api()` 클라이언트는 `<meta name="csrf-token">` 을 자동으로
-  읽어 `X-CSRF-Token` 헤더에 붙인다 (`packages/vue/src/api.ts:184`).
+- CSRF: 세션 앱은 상태 변경 메서드(POST/PUT/PATCH/DELETE)에 CSRF 강제.
+  **토큰은 `<meta>` 태그가 아니라 data-page 공유 prop 으로 온다 (결정 116).**
+  프레임웍 Inertia 셸은 `<meta name="csrf-token">` 을 **넣지 않는다** — csrf 는
+  모든 렌더에 자동 주입되는 공유 prop 이라 페이지에서 `useShared().csrf` 로 읽는다
+  (`packages/vue/src/shared.ts`). 폼은 그 값을 실어 보낸다 — `useForm({ ..., _csrf:
+  shared.csrf })` 또는 HTML 폼이 못 보내는 메서드는 헤더로: `router.delete(url, {
+  headers: { 'x-csrf-token': shared.csrf } })` (스캐폴드 Login/Signup/Dashboard 가
+  이 관례를 그대로 깐다).
+  - `api()` 클라이언트도 **같은 data-page csrf 를 자동으로 붙인다 (결정 166).** 세션
+    앱에서 상태 변경 JSON 액션(`api('web:posts#tagAdd', ...)` 등)을 불러도 손수 토큰을
+    넘길 필요가 없다 — `api()` 가 data-page 의 `props.csrf`(`useShared().csrf` 와 같은
+    단일 출처)를 읽어 `X-CSRF-Token` 에 실어 준다(`packages/vue/src/api.ts`). data-page
+    가 없거나(비-Inertia) 봉인(seal)이면 레거시 `<meta name="csrf-token">` 로 폴백한다.
+    JWT/API 앱은 토큰 인증이라 CSRF 대상이 아니다.
 - **CSRF 는 세션 위에 얹힌다 — 세션이 없으면 CSRF 도 없다 (결정 93).**
   세션이 있어야 토큰을 저장·검증할 곳이 생긴다. `gaon new` 기본 web 앱은
   `app.config.ts` 에 세션을 **기본 배선**해 규칙 8(기본 켬)이 실태가 되게
   한다 — 폼(POST)을 추가하는 순간 CSRF 가 이미 켜져 있다. 앱에 비-GET
   라우트가 있는데 `app.config.ts` 에 session 이 없으면 `gaon doctor` 의
   `csrf-wiring` 이 경고한다(JWT/API 앱은 토큰 인증이라 CSRF 대상 제외).
+- **CSRF/세션 실패는 코어가 Inertia-네이티브로 마감한다 (결정 165).** 세션 만료·
+  secret 로테이션·장시간 탭으로 CSRF 가 실패하면, Inertia 요청은 raw JSON 403 이 아니라
+  **409 + `X-Inertia-Location` 풀 리로드**(새 세션 쿠키+새 토큰) + `flash.error` 안내로
+  마감된다 — 앱이 안 깨지고 사용자는 재시도로 성공한다. 415(지원 안 되는 Content-Type)도
+  같은 핸들러가 Inertia-네이티브 에러+수리 안내로 마감한다. 비-Inertia(API/JWT)는 종전
+  JSON 유지(회귀 없음). 상세는 `agents/web.md` §4.1. 앱은 아무것도 안 한다.
 - JWT 는 API 앱 전용 옵션. 세션 쿠키가 기본 (v0.15 §7 · v0.11 확정).
 - **인증·인가는 3층이다** (결정 145 · 149):
   - **① 인증 `this.requireAuth()`** = **로그인 여부** — 비로그인이면 401(세션 앱은

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

@@ -87,6 +87,43 @@ describe('SendWelcomeMail (실 NATS JetStream)', () => {
 - `configureJobs` 는 헬퍼가 대신 해 준다 — 테스트가 부팅 코드를 흉내낼
   필요가 없다.
 
+### 4.1 이벤트/리스너 헬퍼 — `expectEventProcessed`
+
+이벤트 "emit → 리스너 실 처리" 는 잡의 대응 헬퍼 `expectEventProcessed`
+한 호출로 확증한다 — 임시로 등록 리스너를 실 스트림에 붙여 이 이벤트가
+**리스너 핸들러까지 실행**되는 것을 기다리고 정리한다(`expectJobProcessed`
+대칭). ⚠️ 검증 대상 리스너(`domain/listeners/*.ts`)가 import 되어 레지스트리에
+등록돼 있어야 한다(파일=등록).
+
+```ts
+// test/integration/postPublished.integration.test.ts
+import { describe, it } from 'vitest'
+import { connectNats, expectEventProcessed } from 'gaonjs/testing'
+import { PostPublished } from '../../domain/events/postPublished.js'
+import '../../domain/listeners/notifyFollowers.js'   // 파일=등록 — import 로 리스너 등록
+
+describe('PostPublished (실 NATS JetStream)', () => {
+  it('emit 하면 리스너가 처리한다', async () => {
+    const nats = await connectNats()
+    try {
+      await expectEventProcessed(PostPublished, () => PostPublished.emit({ postId: 1n }), { nats })
+    } finally {
+      await nats.close()
+    }
+  })
+})
+```
+
+- **시그니처** — `expectEventProcessed(event, trigger, { nats, timeoutMs?, listenerId?, maxDeliver? })`.
+  `trigger` 는 emit 을 일으키는 임의 함수 — 이벤트 직접 `emit` 도, 컨트롤러·서비스
+  경유도 된다. 여러 리스너가 붙었을 때 `listenerId`(= `domain/listeners/` 파일명 ·
+  `on(..., { id })`)로 특정 리스너만 좁힌다.
+- 리스너가 재전달을 소진하고 드롭되거나 `timeoutMs`(기본 10초) 안에 처리되지
+  않으면 수리 안내(§7.5.3)와 함께 실패한다. 실패 경로를 백오프 계단 없이 빨리
+  확증하려면 `maxDeliver: 1`(첫 실패에서 즉시 드롭).
+- `configureEvents` 는 헬퍼가 대신 해 주고, 끝나면 하네스 배선을 복원한다
+  (`expectJobProcessed` 와 동형 · 자기 nats 를 `close()` 해도 다음 테스트 무영향).
+
 ### 5. DB 테스트 격리 — `gaon test` + `test/setup.ts` (결정 111)
 
 DB 테스트는 손으로 커넥션을 배선하지 않는다 — `gaon test` 와 스캐폴드

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

@@ -39,6 +39,12 @@ export default controller({
   `../../../domain/models/<Pascal>.js` 로 참조한다. `@gaonjs/*` (스코프
   이름) 은 내부 패키지 이름 — 앱 코드에서 직접 import 하지 않는다.
   `@inertiajs/vue3` 는 어댑터 내부 의존 — 앱에서 직접 안 쓴다.
+- **직렬화는 자동이다** — JSON 액션 반환값·`this.json(...)`·`this.render` props 는
+  응답 경계에서 `serializeProps` 를 통과한다: `bigint`/`Date` → string, **hidden
+  컬럼 제외**(§4.2 · 결정 122), 함수 값 제거. 그래서 액션은 모델 Row 를 그대로
+  반환해도 안전하다(손 직렬화 불필요). 드물게 응답 경계 **밖**(예: 채널 broadcast
+  페이로드, 커스텀 문자열 응답)에서 같은 규칙으로 직렬화하고 싶으면 직접 부른다:
+  `import { serializeProps } from 'gaonjs/web'`.
 - **`this.render` 인자** = `<PageFolder>/<Page>` (PascalCase 폴더 · Vue
   파일명과 정합) — 예: `'Posts/Index'` → `apps/<app>/pages/Posts/Index.vue`.
 - **리소스 부재 = `this.notFound()`** — 조회 결과가 없으면 404 를 손으로 만들지
@@ -233,6 +239,22 @@ async create() {
 
 순수 JSON/API 앱(X-Inertia 아님·세션 없음)은 기존대로 **422 JSON** 을 받는다.
 
+#### 세션/CSRF 실패·415 도 코어가 Inertia-네이티브로 마감한다 (결정 165)
+
+폼 검증(결정 109)과 **대칭**으로, 컨트롤러 액션 밖(디스패처 try-catch 밖)에서 나는
+인프라 실패도 앱이 손댈 필요 없이 코어가 마감한다 — 세션 만료·secret 로테이션·장시간
+탭 등 운영 routine 에서 나던 raw JSON 403(앱이 깨지던 지점)을 없앤다:
+
+- **세션/CSRF 실패**(세션 만료·CSRF 토큰 불일치) → **409 + `X-Inertia-Location` 풀
+  리로드**. Inertia 클라가 새 문서(=새 세션 쿠키 + 새 CSRF 토큰)를 받고, `flash.error`
+  로 "세션이 만료돼 다시 시도해 주세요." 안내가 뜬다(레이아웃이 `useShared().flash` 를
+  표시하면 자동 · 스캐폴드 기본 레이아웃에 배선됨). 사용자는 재시도로 성공한다.
+- **415(지원 안 되는 Content-Type)** → **Inertia-네이티브 에러 + 수리 안내**. 지원 타입은
+  **`application/json` · `multipart/form-data`** 뿐이다 — 폼은 `useForm().post(...)`·
+  `router.<메서드>(...)`(gaonjs/vue)로 보내면 Content-Type 이 자동으로 맞는다. 수동
+  `fetch` 로 `application/x-www-form-urlencoded` 를 보내면 415 가 난다.
+- **비-Inertia(API/JWT) 요청은 종전 JSON** 마감을 유지한다(회귀 없음).
+
 ### 4.2 공유 prop 자동 주입 — currentUser·csrf·flash (결정 116·117)
 
 디스패처가 **모든** Inertia 렌더에 공유 prop 3종을 자동 주입한다 — 컨트롤러가

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

@@ -12,10 +12,17 @@
 //
 // 결정 96: 앱 내부 이동은 `Link`(선언적) — `<a href="/">` 는 전체 문서
 // 리로드라 SPA 가 깨진다. 외부 URL 만 `<a>`(문서·GitHub).
-import { Link } from 'gaonjs/vue'
+import { computed } from 'vue'
+import { Link, useShared } from 'gaonjs/vue'
 
 // package.json 의 gaonjs 의존 범위(예: ^0.9.2)에서 캐럿·틸드를 벗겨 표기.
 const version = '{{GAONJS_VERSION}}'.replace(/^[\^~]/, '')
+
+// 공유 prop flash(결정 116) 를 앱 전역에서 한 번 표시한다 — 세션 만료 안내(결정 165 ·
+// 코어가 심는 flash.error)나 this.flash('success', ...) 가 어느 페이지에서든 뜬다.
+const shared = useShared()
+const flashError = computed(() => shared.flash.error as string | undefined)
+const flashSuccess = computed(() => shared.flash.success as string | undefined)
 </script>
 
 <template>
@@ -37,6 +44,18 @@ const version = '{{GAONJS_VERSION}}'.replace(/^[\^~]/, '')
     </header>
 
     <main class="w-full flex-1">
+      <div v-if="flashError || flashSuccess" class="px-6 pt-4">
+        <div
+          v-if="flashError"
+          role="alert"
+          class="mx-auto max-w-3xl rounded-md border border-destructive/40 bg-destructive/10 px-4 py-2.5 text-sm text-destructive"
+        >{{ flashError }}</div>
+        <div
+          v-else-if="flashSuccess"
+          role="status"
+          class="mx-auto max-w-3xl rounded-md border border-primary/30 bg-primary/10 px-4 py-2.5 text-sm text-foreground"
+        >{{ flashSuccess }}</div>
+      </div>
       <slot />
     </main>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -27,13 +27,13 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.10.0",
-    "@gaonjs/core": "0.2.1",
-    "@gaonjs/config": "0.14.0",
-    "@gaonjs/i18n": "0.2.0",
+    "@gaonjs/config": "0.14.1",
     "@gaonjs/data": "0.16.0",
+    "@gaonjs/async": "0.11.0",
+    "@gaonjs/i18n": "0.2.0",
     "@gaonjs/mail": "0.2.0",
-    "@gaonjs/web": "0.16.0"
+    "@gaonjs/core": "0.2.1",
+    "@gaonjs/web": "0.17.0"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""