@gaonjs/cli 0.29.0 → 0.31.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/commands/test.js

@@ -155,8 +155,14 @@ export async function runTestCommand(args = [], opts = {}) {
         cmd = vitestBin;
         spawnArgs = ['run', ...passthrough];
     }
+    // 결정 130: 테스트 프로세스에 스트림 네임스페이스 접두를 주입해 잡·이벤트
+    // NATS 스트림을 개발 스택과 격리한다(규칙 10 · DB `<db>_test` 와 대칭). 접두가
+    // 붙으면 테스트가 쓰는 스트림/subject 가 `GAON_TEST_JOBS`·`test.gaon.jobs.>` 로
+    // 갈려, 개발용 `gaon work` 가 떠 있어도 서로 잡을 훔치지 않는다. 사용자가 이미
+    // 값을 세팅했으면 존중한다(고급 · 다중 테스트 컨텍스트 분리).
+    const testEnv = { ...process.env, GAON_STREAM_PREFIX: process.env.GAON_STREAM_PREFIX ?? 'test' };
     if (json) {
-        process.stdout.write(JSON.stringify({ kind: 'starting', cmd, args: spawnArgs, scope }) + '\n');
+        process.stdout.write(JSON.stringify({ kind: 'starting', cmd, args: spawnArgs, scope, streamPrefix: testEnv.GAON_STREAM_PREFIX }) + '\n');
     }
     else {
         process.stdout.write(`  gaon test · ${cmd} ${spawnArgs.join(' ')} (scope=${scope})\n`);
@@ -164,7 +170,7 @@ export async function runTestCommand(args = [], opts = {}) {
     const exitCode = await new Promise((resolvePromise) => {
         const child = spawn(cmd, spawnArgs, {
             cwd,
-            env: process.env,
+            env: testEnv,
             // vitest 컬러 출력·리포터를 그대로 보여주기 위해 stdio 를 상속한다.
             stdio: 'inherit',
         });

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/async.md.tpl

@@ -86,6 +86,10 @@ await SendWelcomeMail.at(someDate, user.id) // 특정 시각 실행
   `curve`(백오프 곡선 ms) · `jitter` · `concurrency`.
 - **실패** — 재시도를 소진하면 DLQ 로 간다. `gaon jobs list --failed` ·
   `gaon jobs retry <id>` 로 조회·재적재한다.
+- **실행 컨텍스트(결정 129)** — `gaon work` 는 `gaon serve` 와 **같은 도메인
+  배선**(DB 커넥션 · 메일)을 태운다. 그래서 잡 핸들러에서 모델 조회(`User.find`),
+  `Mail.deliver`, `broadcast`, 다른 잡 `.later()` 를 웹 컨트롤러에서와 똑같이 쓴다
+  — 워커라서 못 쓰는 배터리는 없다.
 - 기본 백오프 곡선은 `[1s, 5s, 30s, 5m, 1h]` + 지터 0.2, 재시도 3
   (총 4시도) — §7 · 벤치마크로 확정된 값.
 

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

@@ -361,8 +361,11 @@ async function runSearch(q: string) {
   **method-override** 가 잡는다(결정 89).
 - **채널 구독은 `useChannel()`** — 실시간 클라이언트는 `gaonjs/vue` 의
   `useChannel(name, opts)` 가 정본(결정 87). `new WebSocket` 을 손으로 짜면
-  URL(`/gaon/ws/<채널>`)·봉투(`{ t:'msg', data }`)·라이프사이클을 재구현하다
-  틀린다(`agents/realtime.md` §4). 구독 래핑은 컴포저블에.
+  URL(`/gaon/ws/<채널>`)·봉투(`{ t:'msg', data }`)·라이프사이클·**자동 재연결**을
+  재구현하다 틀린다(`agents/realtime.md` §4). 구독 래핑은 컴포저블에. 소켓이 끊기면
+  useChannel 이 지수 백오프로 **자동 재접속**하고 프레즌스를 재동기한다(결정 128 · 기본
+  켬 · `status='reconnecting'` · `onReconnect` 로 놓친 데이터 따라잡기 · 미인가 4401 은
+  재연결 안 함). 손 WebSocket 재연결 루프를 짜지 말 것.
 - **레이아웃을 shared 에 두지 않는다** — 앱별이 정상(UI 킷 §8 은 예외 — 성격
   중립 순수 UI 라 `shared/components/ui` 프로젝트당 한 벌 · 결정 105).
 - **UI 킷은 `@shared/components/ui/…` 로 import** — `../../../shared/...` 같은 깊은

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) {
@@ -138,6 +144,7 @@ export function useRoom(roomId: number) {
     params: { room: roomId },
     onMessage: (data) => { /* 서버가 broadcast/send 한 데이터 */ },
     onPresence: (delta) => { /* 접속자 join/leave */ },
+    onReconnect: () => { /* 재연결됨 — 놓친 데이터를 Inertia partial reload 로 따라잡기 */ },
   })
   return { messages, status, send }
 }
@@ -147,8 +154,18 @@ export function useRoom(roomId: number) {
   정답 경로). 날 페이로드를 직접 보내면 서버가 안 흘린다.
 - **받기** — `msg` 프레임은 `messages` 에 축적 + `onMessage` 호출, `presence` 는
   `onPresence`. 그 외는 `onFrame`.
+- **자동 재연결(결정 128 · 기본 켬)** — 소켓이 끊기면(서버 재시작·네트워크 blip)
+  useChannel 이 **지수 백오프**(1s·2s·5s·10s · 이후 10s 반복 · 지터)로 자동 재접속한다.
+  새 소켓은 서버가 다시 인가하고 프레즌스 스냅샷을 다시 밀어주므로 접속자 목록이
+  재동기된다(`messages` 는 유지 · 놓친 이벤트 리플레이는 범위 밖). `status` 는
+  `'connecting' | 'open' | 'reconnecting' | 'closed'` 로, 드롭 후 `'reconnecting'`,
+  성공하면 `'open'`. **재연결 성공 시 `onReconnect` 콜백**으로 놓친 데이터를 따라잡는다
+  (Inertia partial reload). **미인가(4401 close · authorize 거부·세션 만료)면 재연결하지
+  않고 `'closed'`** — 서버 다운(재시도)과 인가 거부(포기)를 close code 로 가른다. 끄려면
+  `reconnect: false`, 튜닝은 `reconnect: { curveMs, maxDelayMs, maxAttempts }`. 언마운트·
+  수동 `close()` = 의도적 종료라 재연결하지 않는다.
 - **탈출구** — 표준 WebSocket 이 필요하면 `new WebSocket('<프리픽스>/gaon/ws/<채널명>')`
-  을 직접 쓸 수 있다(봉투·라이프사이클을 스스로 책임진다). 기본 경로는 `useChannel`.
+  을 직접 쓸 수 있다(봉투·라이프사이클·재연결을 스스로 책임진다). 기본 경로는 `useChannel`.
 
 ### 5. 허브 프로세스 (`gaon hub`)
 
@@ -181,10 +198,26 @@ 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).
 
@@ -194,6 +227,10 @@ export default channel({
   앱 소속 · 라우트처럼 앱 경계 안).
 - **`presenceInfo` 에 민감 정보 금지** — 접속자 목록은 채널 전원에게
   공개된다. 공개 메타만.
+- **raw data 에코는 반정본** — `onMessage(ctx, data) { ctx.broadcast(data) }` 처럼
+  클라 페이로드를 통째로 되쏘면 작성자 위조·XSS 표면이 열린다. 본문만 검증·상한해
+  취하고, 작성자 같은 신뢰 필드는 **서버 권위 `ctx.user`** 로 붙인 봉투만 broadcast
+  한다(§2 · 정본 예시 chatMessages.ts).
 - **웹서버 ↔ 허브를 NATS 로 잇지 않는다** — TCP 지속 연결이 정본
   (E-2). NATS 는 broadcast 팬아웃 전용.
 - **서버 푸시 데이터를 `api()` 폴링으로 대체 금지** — 데이터 경로

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 이 막나 | 진짜 방어 |
@@ -102,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 · 키 유도 =
@@ -119,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 봉인을 정면 단언한다.
 
 ## 알려진 함정
 

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

@@ -15,13 +15,19 @@
 테스트만 다른 DB 로 돌리는 것은 자기모순이며, 방언 차이 버그가
 테스트를 통과해 운영에서 터지는 구멍이었다.
 
-- 테스트 전에 compose 로 DB · NATS 를 띄우고, **테스트 전용
-  데이터베이스**(truncate 격리 · 결정 111) + **테스트 전용 스트림
-  프리픽스**를 쓴다.
+- 테스트 전에 compose 로 DB · NATS 를 띄운다. `gaon test` 가 **테스트 전용
+  데이터베이스**(`<db>_test` · truncate 격리 · 결정 111) 와 **테스트 전용 NATS
+  스트림 네임스페이스**(`GAON_STREAM_PREFIX` · 결정 130) 를 **자동으로** 격리한다.
 - `gaon test` 가 테스트 전용 데이터베이스(`<db>_test`)를 **자동 준비**한다
   — 없으면 만들고(CREATE DATABASE) 마이그레이션까지 적용한 뒤 vitest 를
   돌린다. 스캐폴드 `test/setup.ts` 가 그 DB 에 붙고(`connectTestDatabase`)
   매 테스트 뒤 전 테이블을 비운다(`truncateAll`). 아래 §5 참고.
+- `gaon test` 가 잡·이벤트 NATS 스트림도 **자동 격리**한다(결정 130) —
+  테스트 프로세스에 `GAON_STREAM_PREFIX` 를 주입해 스트림·subject 가
+  `GAON_TEST_JOBS`·`test.gaon.jobs.>` 로 갈린다. 그래서 개발용 `gaon work` 가
+  떠 있어도 테스트 잡을 훔치지 않고, 테스트가 남긴 잡을 개발 워커가 처리하지도
+  않는다 — **테스트 전에 워커를 내릴 필요가 없다.** (직접 `vitest` 로 돌리면 이
+  격리가 없어 개발 스택과 섞이니 `gaon test` 를 쓴다.)
 - SQLite 는 Docker 가 불가능한 환경의 폴백으로만 남고 공식 경로가
   아니다.
 
@@ -170,8 +176,10 @@ hidden 값은 **서버 코드에서는 여전히 읽힌다**(직렬화 경계에
 - **`expect(true).toBe(true)` 류 무의미 단언 금지** — 실 인프라에
   접속하지 않는 통합 테스트는 §9 위반으로 판정된다.
 - **NATS·DB 목업 금지** — `vi.mock` 으로 전송을 막으면 검증이 무효.
-- **테스트 격리** — 공유 큐 이름을 쓰면 병렬 테스트가 서로의 잡을
-  소비한다. 큐·스트림 프리픽스를 테스트 전용으로.
+- **테스트 격리는 `gaon test` 가 해 준다(결정 130)** — 잡·이벤트 스트림을
+  테스트 네임스페이스(`GAON_STREAM_PREFIX`)로 자동 격리하므로, 개발용 `gaon work`
+  와 나란히 돌려도 서로의 잡을 소비하지 않는다. 직접 `vitest` 로 돌리면 이 격리가
+  없으니(개발 스택 공유) `gaon test` 를 쓴다.
 - **워커 정리** — 직접 `runWorker` 를 쓰면 테스트 종료 전 `stop()` 을
   보장하라 (`expectJobProcessed` 는 자동 정리).
 - **직렬화 테스트가 직접 행만 봄** — hidden 검증을 `Model.create()` 결과
@@ -185,5 +193,6 @@ hidden 값은 **서버 코드에서는 여전히 읽힌다**(직렬화 경계에
 | 결정 42 | 비동기 테스트 헬퍼 `expectJobProcessed` (`gaonjs/testing`) |
 | 결정 122 | 직렬화 경계 테스트는 관계 경유 hidden 을 반드시 포함(재귀 no-leak 단언) |
 | 결정 111 | `gaon test` 테스트 DB 자동 준비 + `connectTestDatabase`·`truncateAll` 격리(truncate · service COMMIT 실측) |
+| 결정 130 | `gaon test` 가 NATS 스트림도 자동 격리(`GAON_STREAM_PREFIX` → `GAON_TEST_JOBS`·`test.gaon.jobs.>`) — 개발 워커 병행 시 잡 누출 방지(규칙 10 이행) |
 | §9 (v0.15) | 실 인프라 필수 · 목업/인메모리 금지 |
 | 결정 32 | 잡 발행 위치 자유 — publish 함수가 서비스 경유여도 검증 대상 |

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/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/dist/work.js

@@ -11,7 +11,8 @@
  */
 import { hostname } from 'node:os';
 import { connectNats, runWork } from '@gaonjs/async';
-import { createDb } from '@gaonjs/data';
+import { createDb, registerConnection, hasConnection, getConnection } from '@gaonjs/data';
+import { loadGaonConfig, wireDomain } from '@gaonjs/config';
 import { loadDomain } from './domain.js';
 /** DB URL 에서 어댑터를 추정한다(postgres·mysql). */
 function dbConfigFromUrl(url) {
@@ -69,12 +70,23 @@ export async function runWorkCommand(opts = {}) {
         }
     };
     const nats = await connectNats({ servers: opts.natsUrl, name: `work@${id}` });
-    let db;
+    // 도메인 배터리 배선(결정 129) — 잡 핸들러가 모델을 읽고(registerConnection)
+    // 메일을 보내려면(configureMailer) work 도 serve 와 같은 도메인 배선을 태워야
+    // 한다. serve 는 wireGaon → wireDomain, work 은 여기서 직접 wireDomain 을
+    // 호출한다. 이 배선이 없으면 잡에서 모델 조회·메일 발송이 운영 워커에서만
+    // 조용히 깨진다(gaon dev 는 serve 프로세스가 대신 배선해 가려짐).
+    const config = await loadGaonConfig(root);
+    const domainWiring = await wireDomain(config, root);
+    // 아웃박스 릴레이·모델 읽기용 main 커넥션. gaon.config 에 db.main 이 있으면
+    // wireDomain 이 이미 등록했다. config 없이 env(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));
+    if (!hasConnection('main') && dbUrl) {
+        const cfg = dbConfigFromUrl(dbUrl);
+        registerConnection('main', createDb(cfg), cfg.adapter);
+    }
+    const db = hasConnection('main') ? getConnection('main') : undefined;
     const domain = await loadDomain(root);
     // 로드된 도메인 자산 요약(파일=등록 관측용). 잡·리스너·메일 수를 노출한다.
     if (json) {
@@ -99,8 +111,7 @@ export async function runWorkCommand(opts = {}) {
         });
     }
     catch (err) {
-        if (db)
-            await db.destroy().catch(() => { });
+        await domainWiring.closeDomain().catch(() => { });
         await nats.close();
         throw err;
     }
@@ -110,8 +121,7 @@ export async function runWorkCommand(opts = {}) {
             signals.off('SIGTERM', stop);
             void (async () => {
                 await work.stop();
-                if (db)
-                    await db.destroy().catch(() => { });
+                await domainWiring.closeDomain().catch(() => { });
                 await nats.close();
                 if (json)
                     process.stdout.write(JSON.stringify({ kind: 'stopped' }) + '\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.29.0",
+  "version": "0.31.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/async": "0.7.0",
-    "@gaonjs/config": "0.9.1",
+    "@gaonjs/async": "0.8.0",
+    "@gaonjs/config": "0.10.0",
     "@gaonjs/data": "0.13.1",
+    "@gaonjs/core": "0.2.1",
     "@gaonjs/mail": "0.1.3",
-    "@gaonjs/web": "0.12.0",
-    "@gaonjs/core": "0.2.1"
+    "@gaonjs/web": "0.13.1"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""