@gaonjs/cli 0.28.0 → 0.30.0

package/dist/commands/check.js

@@ -279,10 +279,12 @@ function writeRegenLine(regen) {
         process.stdout.write('  · .gaon 재생성 — skipped (domain/schema · apps/* 없음)\n');
         return;
     }
+    // 실 출력 경로를 그대로 찍는다(W2): tables.d.ts 는 루트 `.gaon/`, routes.d.ts 는
+    // 앱별 `apps/<앱>/.gaon/`. 옛 로그는 `web/routes.d.ts` 로 찍어 실 경로를 오도했다.
     const parts = [];
     if (regen.tables)
-        parts.push('tables.d.ts');
+        parts.push('.gaon/tables.d.ts');
     for (const app of regen.apps)
-        parts.push(`${app}/routes.d.ts`);
+        parts.push(`apps/${app}/.gaon/routes.d.ts`);
     process.stdout.write(`  ✓ .gaon 재생성 — ${parts.join(', ')}\n`);
 }

package/dist/commands/gen.d.ts

@@ -0,0 +1,29 @@
+import { type RegenResult } from '../dev.js';
+export interface GenCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+}
+export interface GenResult {
+    readonly ok: boolean;
+    /** 재생성이 스킵됐는가(domain/schema · apps/* 없음). */
+    readonly skipped: boolean;
+    /** tables.d.ts 를 재생성했는가. */
+    readonly tables: boolean;
+    /** routes.d.ts·routes.manifest.ts 를 재생성한 앱 이름. */
+    readonly apps: readonly string[];
+    /** 실패 시 에러 + 수리 안내. */
+    readonly error?: string;
+}
+/**
+ * cwd 관례로 프로젝트 .gaon 을 1회 전체 재생성한다(검사·서버 없이). 생성기는 사용자
+ * .ts 를 동적 import 하므로 `.js`→`.ts` 해석 훅을 먼저 등록한다(gaon check 와 동일).
+ * 스키마·앱이 하나도 없으면 재생성 대상 없음으로 스킵한다. 실패는 throw 로 올린다.
+ */
+export declare function regenerateProjectGaon(cwd: string): Promise<RegenResult & {
+    skipped: boolean;
+}>;
+/**
+ * `gaon gen` 진입점. .gaon 을 재생성하고 결과를 보고한다. 재생성 대상이 없으면
+ * 스킵으로 리포트(우회가 아니라 "설정 부족" 노출). 실패 시 exit 1 + 수리 안내.
+ */
+export declare function runGenCommand(opts?: GenCommandOptions): Promise<number>;

package/dist/commands/gen.js

@@ -0,0 +1,79 @@
+/**
+ * @gaonjs/cli · `gaon gen` — .gaon 타입 브리지 + 런타임 매니페스트 재생성 (결정 127)
+ *
+ * `gaon dev`(워처)·`gaon check`(검사 직전) 는 이미 재생성을 편승시키지만, **개발 서버
+ * 없이 재생성만** 필요한 경로가 있다:
+ *   · 프로덕션 빌드 — 스캐폴드 `build` 스크립트가 `gaon gen && vite build` 로 돈다.
+ *     .gaon/ 은 gitignore 대상이라 fresh-clone 에는 없다 — 값 import 인
+ *     routes.manifest.ts 가 빌드 전에 존재해야 하므로 빌드가 재생성을 탄다(결정 127 · C-1).
+ *   · 편집기 타입 즉시 반영 — 사용자가 손으로 한 번 돌려 routes.d.ts·tables.d.ts 를 채운다.
+ *
+ * 규칙 3(결정 127): routes 축은 routes.d.ts(타입) + routes.manifest.ts(런타임 값) 2파일로
+ * 물성화된다 — generateRoutesDts 한 번이 둘을 함께 낳는다.
+ *
+ * §9 실 인프라 · 목업 X — 생성기는 사용자 스키마·컨트롤러 .ts 를 실제로 동적 import 한다.
+ */
+import { generateTablesDts } from '@gaonjs/data';
+import { generateRoutesDts } from '@gaonjs/web';
+import { regenerateGaonOnce, resolveDevLayout } from '../dev.js';
+import { registerTsResolve } from '../tsResolve.js';
+/**
+ * cwd 관례로 프로젝트 .gaon 을 1회 전체 재생성한다(검사·서버 없이). 생성기는 사용자
+ * .ts 를 동적 import 하므로 `.js`→`.ts` 해석 훅을 먼저 등록한다(gaon check 와 동일).
+ * 스키마·앱이 하나도 없으면 재생성 대상 없음으로 스킵한다. 실패는 throw 로 올린다.
+ */
+export async function regenerateProjectGaon(cwd) {
+    const layout = resolveDevLayout(cwd);
+    if (!layout.schemaDir && layout.apps.length === 0) {
+        return { tables: false, apps: [], skipped: true };
+    }
+    registerTsResolve();
+    const result = await regenerateGaonOnce(layout, {
+        regenerateTables: generateTablesDts,
+        regenerateRoutes: generateRoutesDts,
+    });
+    return { ...result, skipped: false };
+}
+/**
+ * `gaon gen` 진입점. .gaon 을 재생성하고 결과를 보고한다. 재생성 대상이 없으면
+ * 스킵으로 리포트(우회가 아니라 "설정 부족" 노출). 실패 시 exit 1 + 수리 안내.
+ */
+export async function runGenCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = opts.json ?? false;
+    let result;
+    try {
+        const r = await regenerateProjectGaon(cwd);
+        result = { ok: true, skipped: r.skipped, tables: r.tables, apps: r.apps };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        result = {
+            ok: false,
+            skipped: false,
+            tables: false,
+            apps: [],
+            error: `.gaon 재생성에 실패했습니다: ${msg}\n` +
+                `→ domain/schema/*.ts 와 apps/*/routes.ts·controllers/*.ts 의 구문 오류를 고친 뒤 다시 실행하세요.`,
+        };
+    }
+    if (json) {
+        process.stdout.write(JSON.stringify(result) + '\n');
+    }
+    else if (!result.ok) {
+        process.stderr.write(`  ✗ gaon gen — 실패\n    ${(result.error ?? '').split('\n').join('\n    ')}\n`);
+    }
+    else if (result.skipped) {
+        process.stdout.write('  · gaon gen — 재생성 대상 없음 (domain/schema · apps/* 확인)\n');
+    }
+    else {
+        const parts = [];
+        if (result.tables)
+            parts.push('.gaon/tables.d.ts');
+        for (const app of result.apps) {
+            parts.push(`apps/${app}/.gaon/routes.d.ts`, `apps/${app}/.gaon/routes.manifest.ts`);
+        }
+        process.stdout.write(`  ✓ gaon gen — ${parts.join(', ')}\n`);
+    }
+    return result.ok ? 0 : 1;
+}

package/dist/commands/new.js

@@ -24,6 +24,7 @@ import { fileURLToPath } from 'node:url';
 import { readFileSync } from 'node:fs';
 import { renderProjectFiles } from '../templates/index.js';
 import { writeUiKitScaffold } from '../uikit.js';
+import { regenerateProjectGaon } from './gen.js';
 /** 이름 유효성 — npm 패키지명 규칙(단순 부분)만 검사. */
 function validateProjectName(name) {
     if (!name)
@@ -224,6 +225,22 @@ export async function runNewCommand(name, opts = {}) {
             return 1;
         }
     }
+    // C-1(결정 127) — 설치 성공 후 .gaon 을 한 번 재생성한다. 생성기가 사용자 .ts 를
+    // 동적 import 하므로 node_modules 가 필요하다(skipInstall 이면 건너뜀 — dev/check/build
+    // 가 재생성을 탄다). 값 import 인 routes.manifest.ts 가 생겨 gaon new 직후 vite build 도
+    // 바로 돌고, routes.d.ts 로 편집기 타입이 즉시 잡힌다. 실패해도 스캐폴드는 성공으로
+    // 둔다(best-effort · 재생성은 dev/check/gen 이 상시 보장) — 경고만 남긴다.
+    if (installReport.ran && installReport.exitCode === 0) {
+        try {
+            await regenerateProjectGaon(root);
+        }
+        catch (err) {
+            if (!json) {
+                process.stderr.write(`  · .gaon 초기 재생성 경고: ${err instanceof Error ? err.message : String(err)}\n` +
+                    `    → gaon dev·gaon check·gaon gen 이 재생성하니 무시해도 됩니다.\n`);
+            }
+        }
+    }
     // git init + 첫 커밋 — 스킵 시 그대로 넘어감.
     const gitReport = { ran: false, skipped: opts.skipGit === true, initialized: false, firstCommit: false };
     if (!opts.skipGit) {

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { startDev, resolveDevLayout, regenerateGaonOnce, type DevDeps, type DevL
 export { runDevCommand, type DevCommandOptions } from "./commands/dev.js";
 export { createDevConsole, findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, startTscWatchers, killChild, startRestartWatcher, isRestartChange, resolveWatchRoots, type DevConsole, type DevConsoleOptions, type DevSource, type DevLevel, type ComposeStatus, type ComposeUpOptions, type EnsureInfraResult, type DockerLocateOptions, type TscWatcherOptions, type TscWatcherHandle, type RestartWatcherOptions, type RestartWatcherHandle, } from "./dev/index.js";
 export { runCheckCommand, type CheckCommandOptions, type CheckStep, type CheckStepStatus, type CheckStepResult, } from "./commands/check.js";
+export { runGenCommand, regenerateProjectGaon, type GenCommandOptions, type GenResult, } from "./commands/gen.js";
 export { runNewCommand, type NewCommandOptions, type NewCommandResult } from "./commands/new.js";
 export { runConsoleCommand, type ConsoleCommandOptions } from "./commands/console.js";
 export { runTestCommand, type TestCommandOptions, type TestScope } from "./commands/test.js";

package/dist/index.js

@@ -13,6 +13,7 @@
 import { MILESTONES, VERSION, HOMEPAGE, loadDotEnv } from "@gaonjs/core";
 import { runDevCommand } from "./commands/dev.js";
 import { runCheckCommand } from "./commands/check.js";
+import { runGenCommand } from "./commands/gen.js";
 import { runNewCommand } from "./commands/new.js";
 import { runConsoleCommand } from "./commands/console.js";
 import { runTestCommand } from "./commands/test.js";
@@ -30,6 +31,7 @@ export { startDev, resolveDevLayout, regenerateGaonOnce, } from "./dev.js";
 export { runDevCommand } from "./commands/dev.js";
 export { createDevConsole, findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, startTscWatchers, killChild, startRestartWatcher, isRestartChange, resolveWatchRoots, } from "./dev/index.js";
 export { runCheckCommand, } from "./commands/check.js";
+export { runGenCommand, regenerateProjectGaon, } from "./commands/gen.js";
 export { runNewCommand } from "./commands/new.js";
 export { runConsoleCommand } from "./commands/console.js";
 export { runTestCommand } from "./commands/test.js";
@@ -99,6 +101,7 @@ function renderHelp(version = VERSION) {
         "    gaon serve --port <n> --host <h>   리슨 포트·호스트 (config 값을 덮음)",
         "    gaon serve --workers <n|auto>      node:cluster 워커 다중화 (env WEB_CONCURRENCY · 기본 1)",
         "    gaon check         typecheck · vue-tsc · build 통합 검사 (--only <step> · --include-doctor)",
+        "    gaon gen           .gaon 타입 브리지 + api() 런타임 매니페스트만 재생성 (서버·검사 없이 · build 전제 · --json)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
         "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all · -- vitest 인자)",
         "    gaon doctor        정적 검사 (24 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전)",
@@ -241,6 +244,20 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
+    // `gaon gen` — .gaon 타입 브리지 + 런타임 매니페스트만 재생성(서버·검사 없이 · 결정 127).
+    // 스캐폴드 `build` 스크립트(`gaon gen && vite build`)와 편집기 타입 즉시 반영에 쓴다.
+    if (argv[0] === "gen") {
+        void runGenCommand({ json: argv.includes("--json") })
+            .then((code) => {
+            process.exitCode = code;
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon gen 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
     // `gaon doctor` — 정적 검사(M9-E · 17 검사). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 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.md.tpl

@@ -154,7 +154,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 | 상황 | 경로 | 근거 |
 |---|---|---|
 | 지금 페이지의 데이터를 다시 받기 (필터 변경·새로고침·무한 스크롤) | **Inertia partial reload** — 같은 액션 재호출, 필요한 props만 | §6.1 |
-| 서버가 먼저 밀어주는 데이터 (알림·채팅·접속자) | **채널/프레즌스** (`agents/realtime.md`) | §7 |
+| 서버가 먼저 밀어주는 데이터 (알림·채팅·접속자) | **채널/프레즌스** (`agents/realtime.md`) — 서버 개시는 `broadcast(name,data)`, 클라 메시지 응답은 `ctx.broadcast` | §7 |
 | 페이지와 무관한 데이터 요청 (자동완성·옵션 조회 등 앱 내부용) | **JSON 액션 + `api()` 클라이언트** (`agents/web.md`·`agents/frontend.md`) | E-3 |
 | 외부에 공개하는 API (모바일 앱·서드파티) | **별도 API 앱 + JWT 옵션** | §3, §7 |
 
@@ -200,7 +200,7 @@ gaon doctor       # 정적 검사 24종 (§2.2)
 |---|---|
 | `gaon new <name>` | 프로젝트 스캐폴드 |
 | `gaon dev` | 통합 개발 오케스트레이션 (Docker·`.gaon` 재생성·**코드 변경 감시·재시작**) |
-| `gaon serve` / `work` / `hub` | 운영 프로세스 3종 (웹 · 워커 · 실시간 허브) — **감시 없음** |
+| `gaon serve` / `work` / `hub` | 운영 프로세스 3종 (웹 · 워커 · 실시간 허브) — **감시 없음** · 웹은 `PORT`, 허브는 `GAON_HUB_PORT` |
 | `gaon g <type> <name>` | 스캐폴드: `auth`·`controller`·`model`·`page`·`job` |
 | `gaon db <sub>` | `diff`·`migrate`(`down`)·`status`·`reset`·`seed` (`agents/data.md` §10) |
 | `gaon check` / `test` / `doctor` | 검증 루프 |
@@ -217,6 +217,10 @@ gaon doctor       # 정적 검사 24종 (§2.2)
 개발 중이면 `gaon dev`(감시·재시작·`.gaon` 재생성 통합)를 쓴다. `serve` 는
 비-production 부팅 시 이 안내를 한 줄 출력한다.
 
+**스케일링 구분** — `serve --workers N`(한 포트 · node:cluster 수직) vs 웹 인스턴스
+여러 대(각각 다른 `PORT` · 허브 뒤 수평) vs `work`(포트 없음 · 프로세스만)는 서로
+다르다. 로컬 멀티 인스턴스 레시피·구분표는 `docs/guides/operations.md` "스케일링" 절 참고.
+
 ## 5. npm 배포본 — 패키지 → 역할
 
 개발자는 파사드 **`gaonjs`** 하나만 설치한다(CLI 명령 `gaon`). 아래는 내부 패키지의 역할 지도다.

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

@@ -39,9 +39,15 @@ export default channel({
   onJoin(ctx) {
     ctx.broadcast({ type: 'joined', member: ctx.member })
   },
-  // 클라이언트 메시지 수신
+  // 클라이언트 메시지 수신 — raw data 를 그대로 되쏘지 않는다(작성자 위조·XSS 표면).
   async onMessage(ctx, data) {
-    ctx.broadcast(data)           // 전 서버의 전 연결로 팬아웃
+    // 본문만 검증·상한해 취하고, 작성자는 서버 권위(ctx.user)로 붙인다 —
+    // 클라가 보낸 author/id 는 신뢰하지 않는다(§정본 예시 chatMessages.ts).
+    const raw = (data as { text?: unknown }).text
+    const text = typeof raw === 'string' ? raw.trim().slice(0, 2000) : ''
+    if (!text) return             // 빈/비정상 메시지는 흘리지 않는다
+    const u = ctx.user as { id: bigint; name: string } | null
+    ctx.broadcast({ text, author: u ? { id: String(u.id), name: u.name } : null })
   },
   // 이탈 (연결 종료·프레즌스 해제 후)
   onLeave(ctx) {
@@ -74,6 +80,37 @@ export default channel({
 
 멤버 식별자는 로그인 사용자면 `user:<id>`, 익명이면 `conn:<uuid>` 다.
 
+### 2.5 서버 개시 broadcast (결정 126)
+
+`ctx.broadcast` 는 클라이언트 연결 훅(`onJoin`/`onMessage`/`onLeave`) **안에서만** 쓸 수 있다 —
+클라 메시지가 있어야 도는 경로다. **컨트롤러·서비스·잡처럼 서버가 클라 메시지 없이 채널을 밀
+때는 `gaonjs/async` 의 `broadcast(name, data)`** 를 쓴다 — 이름으로 채널을 지목해 전 서버·전
+구독자에게 발화한다(여러 인스턴스 자동 팬아웃 · errata E-2).
+
+```ts
+// apps/web/controllers/posts.ts — service·job·listener 어디서든 동일하게 호출
+import { controller } from 'gaonjs/web'
+import { broadcast } from 'gaonjs/async'
+
+export default controller({
+  async create() {
+    const post = await Post.create(this.params(Post.form))
+    broadcast('feed', { type: 'new-post', id: String(post.id) })   // 클라 메시지 불필요
+    return { id: post.id }
+  },
+})
+```
+
+- **`authorize` 재실행 없음** — `authorize` 는 **구독(연결 수립) 시점** 게이트다(§2). 서버 발화
+  broadcast 는 authorize 를 **다시 실행하지 않는다** — 이미 접속(= 인가 통과)한 구독자만 받고,
+  broadcast 는 신뢰된 서버 코드가 그 대상에게 미는 행위다. 특정 사용자에게만 보내야 하면 **채널을
+  그렇게 분리**(예: `authorize` 로 소유자만 입장)하고 그 채널로 broadcast 한다.
+- **payload = `unknown`**(자유 JSON) · 클라 `useChannel` 이 `{ t:'msg', data }` 로 받는다.
+- **seal(결정 121)** — 재봉인은 각 수신 서버의 소켓 경계에서 일어난다. broadcast 는 기존 전달
+  경로를 그대로 재사용하므로 seal 앱에서도 봉인된다(추가 처리 불필요).
+- **realtime(NATS) 미설정 앱**에서 호출하면 수리 안내와 함께 throw · **구독자 없음**이면 조용히
+  아무 데도 안 간다(fire-and-forget · 예외 아님).
+
 ### 3. 프레즌스
 
 `ctx.presence()` 는 **전 서버의** 현재 접속자를 돌려준다. 목록의 권위는
@@ -136,25 +173,53 @@ export function useRoom(roomId: number) {
 
 서버가 먼저 밀어주는 데이터(알림·채팅·접속자)는 채널/프레즌스가 정답
 경로다 (루트 데이터 경로 판단표 2행). 폴링 `api()` 루프로 흉내내지
-않는다.
+않는다. 그 안에서 **누가 발화하느냐**로 표면이 갈린다:
+
+| 발화 주체 | 표면 | 쓰는 곳 |
+| --- | --- | --- |
+| 클라 메시지에 응답 | `ctx.broadcast(data)` | 채널 훅 `onMessage`(클라 메시지 필요) |
+| 서버가 단독으로 밀기 | `broadcast(name, data)` (`gaonjs/async`) | 컨트롤러·서비스·잡·리스너 (클라 메시지 없이 · 결정 126) |
 
 ```ts
-// apps/web/channels/chatMessages.ts — 파일명 camelCase
+// apps/web/channels/chatMessages.ts — 파일명 camelCase · 클라 메시지 응답형
 import { channel } from 'gaonjs/async'
 
 export default channel({
   authorize(ctx) { return ctx.user != null },
   presenceInfo(ctx) { return { name: (ctx.user as { name: string } | null)?.name ?? '익명' } },
-  async onMessage(ctx, data) { ctx.broadcast(data) },
+  async onMessage(ctx, data) {
+    // 1) 본문만 클라에서 취한다 — 검증·상한(신뢰 경계). raw data 통째 브로드캐스트 금지.
+    const raw = (data as { text?: unknown }).text
+    const text = typeof raw === 'string' ? raw.trim().slice(0, 2000) : ''
+    if (!text) return                          // 빈/비정상 메시지는 흘리지 않는다
+
+    // 2) 작성자는 **서버 권위** — ctx.user 로 못박는다(클라가 보낸 author/id 는 신뢰 금지).
+    const u = ctx.user as { id: bigint; name: string } | null
+
+    // 3) 필요하면 여기서 저장한다(영속·조회): 예) await Message.create({ text, userId: u!.id })
+
+    // 4) 서버가 조립한 안전한 봉투만 팬아웃한다.
+    ctx.broadcast({ text, author: u ? { id: String(u.id), name: u.name } : null })
+  },
 })
 ```
 
+클라가 보낸 페이로드를 통째로 `ctx.broadcast(data)` 로 되쏘는 건 **반정본**이다 — 작성자
+위조·XSS 표면이 열린다. 본문만 검증·상한하고, 작성자·타임스탬프 같은 신뢰 필드는 서버가 붙인다.
+
+서버 개시(HTTP 요청·잡 처리 결과 등)로 미는 경우는 §2.5 `broadcast(name, data)` 를 쓴다 —
+"flash 로 클라에 심고 클라가 다시 채널로 중계" 같은 우회는 **반정본**이다(탭 닫힘에 구멍 · 결정 126).
+
 ## 알려진 함정
 
 - **채널 파일 위치는 `apps/<앱>/channels/`** — domain 이 아니다 (채널은
   앱 소속 · 라우트처럼 앱 경계 안).
 - **`presenceInfo` 에 민감 정보 금지** — 접속자 목록은 채널 전원에게
   공개된다. 공개 메타만.
+- **raw data 에코는 반정본** — `onMessage(ctx, data) { ctx.broadcast(data) }` 처럼
+  클라 페이로드를 통째로 되쏘면 작성자 위조·XSS 표면이 열린다. 본문만 검증·상한해
+  취하고, 작성자 같은 신뢰 필드는 **서버 권위 `ctx.user`** 로 붙인 봉투만 broadcast
+  한다(§2 · 정본 예시 chatMessages.ts).
 - **웹서버 ↔ 허브를 NATS 로 잇지 않는다** — TCP 지속 연결이 정본
   (E-2). NATS 는 broadcast 팬아웃 전용.
 - **서버 푸시 데이터를 `api()` 폴링으로 대체 금지** — 데이터 경로
@@ -170,6 +235,7 @@ export default channel({
 |---|---|
 | E-2 | 웹서버 ↔ 허브 = TCP 지속 연결 · NATS = broadcast 전용 |
 | §7 (v0.15) | 실시간 v1 포함 — 채널·프레즌스·허브 · KV 영속 · 리스 리더 선출 HA |
+| 결정 126 | 서버 개시 `broadcast(name, data)`(`gaonjs/async`) — 컨트롤러·서비스·잡에서 클라 메시지 없이 채널 발화 · authorize 재실행 없음 · seal 재봉인 자동 |
 
 ## `@gaonjs/seal` 켠 앱의 채널
 

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

@@ -26,6 +26,26 @@ seal 은 이들 중 어느 것의 이유도 되지 못한다:
 > 그런 판단을 하는 순간 seal 은 보안을 **낮춘다**. `gaon doctor` 의 `seal-security` 가
 > seal 앱에서 rate limit·보안 헤더·CORS 를 명시적으로 끈 경우를 경고한다.
 
+### 은닉의 한계 — 여기까지다 (역공학 실측 · Kerckhoffs)
+
+불투명 export·non-literal 시드·미끼 시크릿에도 불구하고, 89KB wasm 은 디스어셈블(wasm2wat·Ghidra)로
+**알고리즘·시드 파생·개봉 로직이 전부 복원**되고, 공격자는 `sealHttp`/`sealWs` 를 직접 호출해 조작
+데이터를 **올바르게 봉인**할 수 있다. 은닉은 **캐주얼/자동 티어 비용 상승까지만**이며 작정한 공격자는
+못 막는다. 이유는 구조적이다:
+
+1. **알고리즘은 숨길 수 없다** — 클라이언트에서 실제로 돌아야 하니 바이너리에 있다.
+2. **시드 입력이 전부 공격자 통제·공지 값이다** — `domain`·`path`·`uaSlice`·`timestamp` 는 요청에서 나온다.
+3. **진짜 비밀 키가 없다** — masterSecret 은 미끼(공개 전제 · 결정 121·ADR-056).
+
+따라서 보안은 **알고리즘 비밀이 아니라 키 비밀에 있어야 한다(Kerckhoffs)**. 조작·위조를 실제로 막는
+것은 **서버측 검증**(스키마·인가·CSRF·rate limit)과 **replay 방어**(nonce+drift)·**HTTPS** 이며, seal 은
+이를 대체하지 않는다.
+
+> **"보안 강화" 명목으로 난독화를 더 쌓지 말 것 (security-through-obscurity · 기각).** "시드 포맷 추가 은닉 / 바이트 체인
+> 추가 / 알고리즘 커스터마이즈"는 실익 0(security-through-obscurity)이라 **하지 않는다.** wasm strings
+> 하드닝(자작 알고리즘 문자열·홈경로 제거 · §4)만 실효였고 그것만 했다. 알고리즘 은닉을 더 추격하는 것
+> 자체가 이 원칙 위반이다.
+
 ### 막는 것 / 못 막는 것 경계표
 
 | 위협 | seal 이 막나 | 진짜 방어 |
@@ -73,13 +93,17 @@ void createGaonApp({ pages, layouts, /* ... */ sealClient })
 - **요청/응답 JSON**: 클라 `installClientSeal()` 이 Inertia XHR 인터셉터(`XMLHttpRequest.prototype`) +
   `api()`/`fetch` 봉인을 설치한다. 서버는 Fastify **4-stage 훅**(`plugin.ts` · onRequest 분류/fail-closed →
   preParsing body 개봉+replay → preValidation query `?q=` 개봉+replay → onSend 응답 봉인)으로 대칭 복호.
-  **JSON-intent 판별**: `Accept`/`Content-Type: application/json` 요청만 봉인 강제(비-JSON HTML·form 은 자동 면제).
+  **봉인 대상 판별 (결정 125)**: `Accept`/`Content-Type: application/json` **또는** `X-Inertia: true`(Inertia
+  방문·네비게이션) 요청을 봉인 강제한다. Inertia GET 네비게이션은 `Accept: text/html` + `X-Inertia:true` 로
+  와서 application/json 이 없으므로, 이 헤더까지 봐야 네비게이션 props 가 평문으로 새지 않는다(결정 125 P0).
+  네이티브 브라우저 form·정적 자산·HTML 직접 로드는 셋 다 없어 자동 면제된다.
 - **최초 문서 data-page**: 서버가 `<script data-page="app" data-gaon-sealed="1">` 로 봉인 + `<meta gaon-seal-ts>`.
   클라 `createGaonApp` 이 Inertia 마운트 **전**에 wasm 으로 개봉 → 소스 보기·개발자도구에 평문 props 미노출.
 - **WS 프레임 (결정 124 · §3.4)**: `useChannel` 이 `setWsFrameCodec`(seal 클라 `wsEncode`/`wsDecode`)로
   채널 송수신을 봉인한다. 송신 `E:<ts>:<base64>` · seal namespace 는 평문 `P:` 프레임 **거부**(requireDecrypt · 결정 121).
-- **자동 제외 / 옵트아웃**: 정적 자산·헬스체크·multipart 업로드 body·비-JSON 은 **자동 제외**(사람 판단 없이
-  Content-Type 기계 판별). 외부(웹훅 등)가 봉인을 모르는 경로는 `seal: { except: ['/webhooks/*'] }`.
+- **자동 제외 / 옵트아웃**: 정적 자산·헬스체크·multipart 업로드 body·비대상(JSON 도 Inertia 도 아닌 HTML
+  직접 로드·네이티브 form)은 **자동 제외**(사람 판단 없이 헤더 기계 판별 · 결정 125). 외부(웹훅 등)가 봉인을
+  모르는 경로는 `seal: { except: ['/webhooks/*'] }`.
 - **fail-closed (403 · 결정 121)**: 봉인 강제 경로에 시그널 헤더 없이 온 요청, drift/replay/키 실패는
   **403 SealError** — 평문 통과 절대 없음. WS 개봉 실패는 소켓 4500 종료(silent fallback 없음).
 
@@ -98,6 +122,14 @@ seal 앱 응답에만 `script-src` 에 `'wasm-unsafe-eval'` 을 **자동 주입*
   wasm 바이너리 내장**(JS 번들 미노출). **domain·user-agent 는 wasm 이 브라우저(web-sys)에서 직접 읽고**
   path 는 넘겨받은 URL 에서 wasm 이 파싱한다 — JS 소스에 "무엇이 키 유도 입력인가" 힌트를 남기지 않는다.
   (위조는 서버가 실 요청 헤더로 독립 유도해 이미 막힌다 · 이 은닉은 힌트 제거·공격 비용 상승 목적.)
+- **wasm strings 하드닝 — 여기까지가 실효**: 빌드 산출 wasm 은 상주 게이트
+  (`wasm-hardening.test.ts`)로 ① JS 표면 불투명(고수준 4함수만) ② **자작 알고리즘 문자열 0**(에러/expect
+  라벨에 `aes-gcm`·`base64 decode`·`HMAC` 등 미노출 · `.map_err(|_| "seal …")` 로 중립화) ③ **홈경로(PII) 0**
+  (`--remap-path-prefix=$HOME=/` · 이전엔 빌드 머신 사용자명이 박혔다)을 강제한다. **잔존(의도)**: `panic = "abort"`
+  로도 **의존 crate 패닉 위치 경로**(`aes-0.8.4`·`sha2-0.10.9`·`base64-0.22.1` 등)는 안 지워져 `strings` 로
+  알고리즘 **계열**은 여전히 샌다. **완전 차단은 나이틀리 `build-std`+`panic_immediate_abort` 세금이 필요해
+  미채택** — 알고리즘은 비밀이 아니므로(§0 Kerckhoffs) 그 비용을 무는 것 자체가 obscurity 추격이다. 게이트는
+  "알고리즘 계열 0" 이 아니라 "자작 문자열 0 + 홈경로 0 + 표면 불투명" 으로 정의된다.
 - **서버는 wasm 이 아니다** — JS mirror(`crypto.ts`)로 봉인/개봉하고, Rust 정본(wasm)과 **known-vector parity**
   (`wasm-parity` 테스트)로 byte 호환을 강제한다.
 - **알고리즘**: AES-256-GCM(12-byte nonce · 16-byte tag) + nibble-swap XOR(0x5A) + base64 · 키 유도 =
@@ -115,6 +147,11 @@ seal 앱 응답에만 `script-src` 에 `'wasm-unsafe-eval'` 을 **자동 주입*
   경유 봉인 broadcast).
 - **목업 e2e 로 대체 금지.** 서버 inject·단위·wasm-parity 는 byte 호환을 잠글 뿐 "실 브라우저에서 마운트되나"를
   못 본다 — 원 wave 가 실-브라우저 e2e 를 미뤄 P0 3건(번들 불가·CSP 차단·Inertia 인터셉터 파손)을 놓친 교훈(결정 124).
+- **봉인 검증은 네트워크 날 바디로만 봐야 한다 (검증법 함정).** seal 앱에서 `page.evaluate(fetch(...))` 나 렌더된
+  DOM 으로 봉인을 확인하면 **안 된다** — 클라 인터셉터가 fetch/XHR 응답을 **자동 개봉**하고 화면 DOM 은 개봉된
+  평문이라, 봉인돼 있어도 평문으로 보인다(거짓 음성). 봉인은 **네트워크 계층의 날 응답 바디**
+  (Playwright `page.waitForResponse(...).text()`·`page.on('response')` · 외부 `curl`)로 **시그널 헤더 + 암호문**을
+  직접 봐야 드러난다. 정본 게이트 ⑨(결정 125)가 이 방식으로 네비게이션 wire 봉인을 정면 단언한다.
 
 ## 알려진 함정
 
@@ -129,3 +166,4 @@ seal 앱 응답에만 `script-src` 에 `'wasm-unsafe-eval'` 을 **자동 주입*
 
 - **결정 121** — `@gaonjs/seal` 신설(GSP 이식 · 인터셉터 설계 · 앱 토글 · WS requireDecrypt · 기각 대안 4건).
 - **결정 124** — §3.1 개정: **app-side 정적 주입**(변수 동적 import 폐기) · **wasm 표면 은닉**(불투명 함수 · domain/ua/path 를 wasm 이 확보 · 미끼 시크릿 내장) · **WS 클라 봉인**(`setWsFrameCodec`) · **seal 앱 한정 CSP** · doctor `seal-security` main.ts 배선 검사 + `seal-client-wiring` fixer · 실 브라우저 e2e 게이트 · 부수 정정(`.wasm` MIME · `session.csrf` forwarding).
+- **결정 125** — **Inertia 네비게이션 평문 P0** 수정: 봉인 대상 판별기(`isSealTarget`)에 `X-Inertia: true` 를 편입. Inertia GET 방문은 `Accept: text/html` 로 와 application/json 이 없어 자동 면제되던 탓에 응답 props 가 평문으로 새어나갔다(클라 인터셉터는 시그널을 붙였으나 서버가 봉인 안 함). 네비게이션 봉인 e2e 를 seal blocking 게이트에 편입(실 vite+chromium · wire 봉인/`?q=` 왕복 단언).

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

@@ -88,6 +88,11 @@
   작동한다. 토큰·다이제스트·개인정보 컬럼은 선언 시점에 hidden.
 - **`presenceInfo`** — 접속자 목록은 채널 전원에게 공개된다. 공개 메타만
   (`agents/realtime.md`).
+- **서버 개시 `broadcast(name, data)` 는 `authorize` 를 재실행하지 않는다** (결정 126) —
+  채널 `authorize` 는 **구독(연결) 시점** 게이트다. 서버 발화 broadcast 는 이미 접속(= 인가
+  통과)한 구독자에게만 도달하고 authorize 를 다시 돌리지 않는다. 수신 대상을 제한하려면
+  **채널을 그렇게 분리**(`authorize` 로 소유자·역할만 입장)하고 그 채널로 broadcast 한다 —
+  broadcast 자체에 대상 필터는 없다(`agents/realtime.md` §2.5).
 
 ### 6. 클라이언트 IP · 프록시 신뢰 (결정 120)
 

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

@@ -9,6 +9,10 @@
 // import.meta.glob 으로 만든다. 심볼 출처가 코드에 그대로 보인다.
 import { createGaonApp } from 'gaonjs/vue'
 
+// api() 런타임 매니페스트(결정 127) — 라우트 키 → { method, URL }. gaon dev·check·gen 이
+// .gaon/routes.manifest.ts 를 재생성한다. 이 값을 넘겨야 api() 가 요청 경로를 안다.
+import { routes } from './.gaon/routes.manifest.js'
+
 // 전역 스타일 — Tailwind 레이어 + 디자인 토큰(결정 74). 부수효과 import 라
 // 번들에 CSS 가 실린다. 앱마다 하나(관례 = 배치).
 import './style.css'
@@ -24,5 +28,6 @@ const layouts = import.meta.glob('./layouts/*.vue', { eager: true })
 void createGaonApp({
   pages,
   layouts,
+  routes,
   title: (t) => (t ? `${t} · {{PROJECT_NAME}}` : '{{PROJECT_NAME}}'),
 })

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

@@ -3,6 +3,12 @@
 #
 # 기동:  docker compose up -d          (gaon dev 가 자동 실행)
 # 정지:  docker compose down
+#
+# 한 머신에서 gaon 프로젝트를 **여러 개** 동시에 개발할 때: `name:` 이 프로젝트별로 고유해
+# 컨테이너·볼륨·네트워크는 서로 섞이지 않는다(다른 프로젝트 컨테이너를 recreate 하지 않음).
+# 다만 아래 **호스트 포트**(5432·6379·4222 …)는 머신에 하나뿐이라 두 스택을 동시에 띄우면
+# 충돌한다. 그럴 땐 한쪽에서 왼쪽(호스트) 포트만 바꾸고(예: "5433:5432"), 그 프로젝트의
+# `gaon.config.ts` 접속 URL 포트도 같은 값으로 맞춘다. 오른쪽(컨테이너) 포트는 그대로 둔다.
 name: {{PROJECT_NAME}}
 
 services:

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

@@ -9,7 +9,7 @@
   },
   "scripts": {
     "dev": "gaon dev",
-    "build": "vite build",
+    "build": "gaon gen && vite build",
     "serve": "gaon serve",
     "work": "gaon work",
     "hub": "gaon hub",

package/package.json

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