@gaonjs/cli 0.15.0 → 0.21.2

package/dist/index.js

@@ -17,6 +17,7 @@ import { runNewCommand } from "./commands/new.js";
 import { runConsoleCommand } from "./commands/console.js";
 import { runTestCommand } from "./commands/test.js";
 import { runGenerateAuthCommand } from "./generate.js";
+import { runGenerateUiKitCommand } from "./uikit.js";
 import { runGenerateCommand } from "./commands/g.js";
 import { runHubCommand } from "./hub.js";
 import { runServeCommand } from "./serve.js";
@@ -25,7 +26,7 @@ import { runJobsCommand } from "./jobs.js";
 import { runDbCommand } from "./commands/db.js";
 import { runDoctorCommand } from "./doctor.js";
 import { runMcpCommand } from "./commands/mcp.js";
-export { startDev, resolveDevLayout, } from "./dev.js";
+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";
@@ -33,6 +34,7 @@ export { runNewCommand } from "./commands/new.js";
 export { runConsoleCommand } from "./commands/console.js";
 export { runTestCommand } from "./commands/test.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, } from "./generate.js";
+export { writeUiKitScaffold, writeUiKitFiles, uiKitScaffoldFiles, authUiKitFiles, runGenerateUiKitCommand, } from "./uikit.js";
 export { runGenerateCommand, planScaffold, parseGenerateArgs, } from "./commands/g.js";
 export { runHubCommand } from "./hub.js";
 export { runServeCommand } from "./serve.js";
@@ -98,10 +100,11 @@ function renderHelp(version = VERSION) {
         "    gaon dev --json    통합 콘솔을 JSON 라인으로 출력(자동화)",
         "    gaon serve         웹 서버 부팅 (gaon.config.ts 자동 배선 · Fastify listen)",
         "    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 console       프로젝트 컨텍스트 REPL (--no-config)",
         "    gaon test          테스트 러너 (--scope unit|integration|all · -- vitest 인자)",
-        "    gaon doctor        정적 검사 (13 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선)",
+        "    gaon doctor        정적 검사 (17 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
@@ -192,11 +195,15 @@ export function runCli(argv, opts = {}) {
     if (argv[0] === "serve") {
         const portIdx = argv.indexOf("--port");
         const hostIdx = argv.indexOf("--host");
+        const workersIdx = argv.indexOf("--workers");
         const port = portIdx >= 0 ? Number(argv[portIdx + 1]) : undefined;
         const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
+        // --workers <n|auto>: node:cluster 다중화(결정 84). env WEB_CONCURRENCY 도 가능.
+        const workersRaw = workersIdx >= 0 ? argv[workersIdx + 1] : undefined;
+        const workers = workersRaw === "auto" ? "auto" : workersRaw !== undefined ? Number(workersRaw) : undefined;
         // --dev: dev 전용 진단 라우트(/_gaon/health) 등록. gaon dev 가 자식
         // serve 에 넘긴다(결정 69 · dev-only by construction).
-        void runServeCommand({ json: argv.includes("--json"), port, host, dev: argv.includes("--dev") }).catch((err) => {
+        void runServeCommand({ json: argv.includes("--json"), port, host, workers, dev: argv.includes("--dev") }).catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`  ✗ gaon serve 실패: ${msg}\n`);
             process.exitCode = 1;
@@ -228,7 +235,7 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(M9-E · 13 검사). --check=<이름>[,<이름>...] 로
+    // `gaon doctor` — 정적 검사(M9-E · 17 검사). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {
@@ -351,6 +358,13 @@ export function runCli(argv, opts = {}) {
             process.exitCode = code;
             return;
         }
+        if (argv[1] === "ui-kit" || argv[1] === "ui") {
+            const appIdx = argv.indexOf("--app");
+            const app = appIdx >= 0 ? argv[appIdx + 1] : undefined;
+            const code = runGenerateUiKitCommand({ app, json: argv.includes("--json") });
+            process.exitCode = code;
+            return;
+        }
         const known = ["controller", "model", "page", "job", "app"];
         const type = argv[1];
         if (type && known.includes(type)) {
@@ -395,7 +409,7 @@ export function runCli(argv, opts = {}) {
             return;
         }
         process.stderr.write(`  ✗ 알 수 없는 제너레이터: ${argv[1] ?? "(없음)"}\n` +
-            `  → 현재 지원: gaon g auth | controller | model | page | job | app\n` +
+            `  → 현재 지원: gaon g auth | ui-kit | controller | model | page | job | app\n` +
             `  → 옵션: --app <이름> · --overwrite · --json\n`);
         process.exitCode = 1;
         return;

package/dist/scaffold/app-wiring.d.ts

@@ -0,0 +1,12 @@
+import type { ScaffoldFile } from './controller.js';
+/**
+ * 대상 앱의 프론트 배선 파일(main.ts·style.css·index.html)을 web 정본에서
+ * 파생해 반환한다. 실제 쓰기는 writeScaffold/writeUiKitFiles 가 담당(멱등).
+ */
+export declare function appWiringFiles(app: string, projectName: string): ScaffoldFile[];
+/** 배선 파일 3종의 대상 경로(존재 검사용). */
+export declare function appWiringPaths(app: string): string[];
+/** 대상 앱에 Tailwind 배선(style.css + main.ts 의 style.css import)이 있는지. */
+export declare function hasAppWiring(cwd: string, app: string): boolean;
+/** 프로젝트 package.json 의 name — 배선 title 치환용. 없으면 'app'. */
+export declare function readProjectName(cwd: string): string;

package/dist/scaffold/app-wiring.js

@@ -0,0 +1,68 @@
+// @gaonjs/cli · scaffold · app-wiring — 앱 프론트 배선 (결정 76)
+//
+// 새 앱(`gaon g app admin`)과 web 앱(`gaon new`)이 프론트 배선에서 동등해야
+// 한다: Tailwind CSS 파이프라인(style.css)·Vite 진입(main.ts·index.html).
+// 이 배선이 없으면 그 앱에서 `gaon g ui-kit --app admin` 으로 심은 UI 킷
+// 컴포넌트가 Tailwind 유틸을 못 받아 스타일 없이 렌더된다(결정 74·75).
+//
+// 단일 소스: web 앱의 정본 템플릿(templates/project/apps/web/{main.ts,style.css,
+// index.html}.tpl)을 그대로 읽어 `{{PROJECT_NAME}}` 만 치환하고 대상 앱으로
+// 재타겟한다. style.css 는 앱 무관(토큰만)이라 web 과 바이트 동일하고, main.ts·
+// index.html 은 프로젝트명 title 만 다르다 — 템플릿을 복제하지 않아 드리프트가
+// 없다(결정 76).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { renderTemplate, templateDir } from '../templates/index.js';
+/** web 정본 템플릿을 대상 앱으로 재타겟하는 배선 파일 3종의 원본 경로. */
+const WIRING = [
+    { tpl: 'apps/web/main.ts.tpl', out: 'main.ts' },
+    { tpl: 'apps/web/style.css.tpl', out: 'style.css' },
+    { tpl: 'apps/web/index.html.tpl', out: 'index.html' },
+];
+/**
+ * 대상 앱의 프론트 배선 파일(main.ts·style.css·index.html)을 web 정본에서
+ * 파생해 반환한다. 실제 쓰기는 writeScaffold/writeUiKitFiles 가 담당(멱등).
+ */
+export function appWiringFiles(app, projectName) {
+    const base = templateDir();
+    const tokens = { projectName, gaonjsVersion: readGaonjsVersion() };
+    return WIRING.map(({ tpl, out }) => {
+        const raw = readFileSync(join(base, tpl), 'utf8');
+        // 주석 안 `apps/web/…` 경로 표기를 대상 앱으로 맞춘다(import 는 상대라 무관).
+        const retargeted = renderTemplate(raw, tokens).replaceAll('apps/web/', `apps/${app}/`);
+        return { path: `apps/${app}/${out}`, contents: retargeted };
+    });
+}
+/** 배선 파일 3종의 대상 경로(존재 검사용). */
+export function appWiringPaths(app) {
+    return WIRING.map(({ out }) => `apps/${app}/${out}`);
+}
+/** 대상 앱에 Tailwind 배선(style.css + main.ts 의 style.css import)이 있는지. */
+export function hasAppWiring(cwd, app) {
+    const styleCss = join(cwd, 'apps', app, 'style.css');
+    const mainTs = join(cwd, 'apps', app, 'main.ts');
+    if (!existsSync(styleCss) || !existsSync(mainTs))
+        return false;
+    const css = readFileSync(styleCss, 'utf8');
+    const main = readFileSync(mainTs, 'utf8');
+    return /@tailwind\b/.test(css) && /['"]\.\/style\.css['"]/.test(main);
+}
+/** 프로젝트 package.json 의 name — 배선 title 치환용. 없으면 'app'. */
+export function readProjectName(cwd) {
+    return readPackageField(cwd, (pkg) => (typeof pkg.name === 'string' ? pkg.name : undefined)) ?? 'app';
+}
+/** 설치된 gaonjs 버전(배선 템플릿엔 미사용이나 렌더 계약상 채운다). */
+function readGaonjsVersion() {
+    return '';
+}
+function readPackageField(cwd, pick) {
+    const pj = join(cwd, 'package.json');
+    if (!existsSync(pj))
+        return undefined;
+    try {
+        return pick(JSON.parse(readFileSync(pj, 'utf8')));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/serve.d.ts

@@ -1,3 +1,8 @@
+/**
+ * 워커 수를 결정한다: 옵션 > env `WEB_CONCURRENCY` > 1. `'auto'` = 코어 수
+ * (availableParallelism). 0·음수·비수치는 1 로 떨어진다(안전 기본). 결정 84.
+ */
+export declare function resolveWorkerCount(workers: number | 'auto' | undefined, env?: NodeJS.ProcessEnv): number;
 export interface ServeCommandOptions {
     readonly cwd?: string;
     readonly json?: boolean;
@@ -5,6 +10,11 @@ export interface ServeCommandOptions {
     readonly port?: number;
     /** 리슨 호스트. 우선순위: 옵션 > config.web.host > '0.0.0.0'. */
     readonly host?: string;
+    /**
+     * 워커 수(node:cluster). 옵션 > env `WEB_CONCURRENCY` > 1. `'auto'` = 코어 수.
+     * 2 이상이면 프라이머리가 fork 해 다중화한다(결정 84).
+     */
+    readonly workers?: number | 'auto';
     /**
      * dev 모드(gaon dev 자식). true 면 dev 전용 진단 라우트(/_gaon/health)를
      * 등록한다. 운영 serve 는 이 플래그 없이 실행되어 진단 라우트가 노출되지

package/dist/serve.js

@@ -8,13 +8,32 @@
  * env 를 먼저 로드한다 — .env 의 값이 gaon.config.ts 안의 env('KEY') 에
  * 들어갈 수 있어야 하기 때문.
  *
- * 워커 수(--workers, WEB_CONCURRENCY)는 v0.8 정본이지만 컨테이너 안 기본
- * 1워커라 M9-A 는 단일 프로세스만 다룬다. node:cluster 통합은 후속(M9-C).
+ * 워커 다중화(--workers · WEB_CONCURRENCY)는 node:cluster 로 처리한다(결정 84):
+ * 기본 1(컨테이너 기본). 2 이상이면 프라이머리가 N 워커를 fork 하고 OS 가
+ * 연결을 분산(cluster 라운드로빈)한다. 워커가 예기치 않게 죽으면 교체 fork,
+ * SIGTERM/SIGINT 에 워커들을 graceful drain 후 종료한다.
  */
+import cluster from 'node:cluster';
+import { availableParallelism } from 'node:os';
 import { loadDotEnv } from '@gaonjs/core';
 import { loadGaonConfig, wireGaon, findConfigPath } from '@gaonjs/config';
 import { registerTsResolve } from './tsResolve.js';
 import { computeHealth, DEV_HEALTH_PATH } from './dev/health.js';
+/**
+ * 워커 수를 결정한다: 옵션 > env `WEB_CONCURRENCY` > 1. `'auto'` = 코어 수
+ * (availableParallelism). 0·음수·비수치는 1 로 떨어진다(안전 기본). 결정 84.
+ */
+export function resolveWorkerCount(workers, env = process.env) {
+    const raw = workers ?? env.WEB_CONCURRENCY;
+    if (raw === undefined || raw === '')
+        return 1;
+    if (raw === 'auto')
+        return Math.max(1, availableParallelism());
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return 1;
+    return Math.floor(n);
+}
 function humanEvent(e) {
     switch (e.kind) {
         case 'starting': {
@@ -24,17 +43,81 @@ function humanEvent(e) {
         }
         case 'listening':
             return `  ▶ 리슨 중 — ${e.url}  (Ctrl+C 로 종료)`;
+        case 'cluster':
+            return `  gaon serve · 클러스터 — 워커 ${e.workers}개 fork (node:cluster)`;
+        case 'worker-exit':
+            return `  ⚠ 워커 종료(pid ${e.pid ?? '?'} · code ${e.code}${e.signal ? ` · ${e.signal}` : ''})${e.restarted ? ' — 교체 fork' : ''}`;
         case 'stopping':
             return '  gaon serve · 종료 중 (graceful) ...';
         case 'stopped':
             return '  gaon serve · 종료';
     }
 }
+/**
+ * 클러스터 프라이머리 — N 워커를 fork 하고 감독한다. 워커가 예기치 않게 죽으면
+ * 교체 fork(복원력), SIGTERM/SIGINT 에 워커들을 SIGTERM 으로 graceful drain 한 뒤
+ * (상한 `GAON_WORKER_DRAIN_MS`, 기본 30s) SIGKILL 로 강제 종료한다. 결정 84.
+ */
+async function runClusterPrimary(workerCount, opts) {
+    const json = opts.json ?? false;
+    const signals = opts.signals ?? process;
+    const drainMs = process.env.GAON_WORKER_DRAIN_MS ? Number(process.env.GAON_WORKER_DRAIN_MS) : 30_000;
+    const emit = (e) => {
+        if (json)
+            process.stdout.write(JSON.stringify(e) + '\n');
+        else
+            process.stdout.write(humanEvent(e) + '\n');
+    };
+    emit({ kind: 'cluster', workers: workerCount });
+    let shuttingDown = false;
+    for (let i = 0; i < workerCount; i++)
+        cluster.fork();
+    cluster.on('exit', (worker, code, signal) => {
+        if (shuttingDown)
+            return;
+        // 예기치 않은 종료 → 교체 fork 로 워커 수를 유지한다.
+        emit({ kind: 'worker-exit', pid: worker.process.pid, code, signal, restarted: true });
+        cluster.fork();
+    });
+    await new Promise((resolvePromise) => {
+        const stop = () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            signals.off('SIGINT', stop);
+            signals.off('SIGTERM', stop);
+            emit({ kind: 'stopping' });
+            for (const w of Object.values(cluster.workers ?? {}))
+                w?.kill('SIGTERM');
+            const killTimer = setTimeout(() => {
+                for (const w of Object.values(cluster.workers ?? {}))
+                    w?.kill('SIGKILL');
+            }, drainMs);
+            const check = () => {
+                if (Object.keys(cluster.workers ?? {}).length === 0) {
+                    clearTimeout(killTimer);
+                    emit({ kind: 'stopped' });
+                    resolvePromise();
+                }
+            };
+            cluster.on('exit', check);
+            check();
+        };
+        signals.on('SIGINT', stop);
+        signals.on('SIGTERM', stop);
+    });
+}
 /**
  * `gaon serve` 진입점. loadDotEnv → loadGaonConfig → wireGaon → listen →
  * SIGINT 대기 → graceful close. 예외는 stderr + exit 1.
  */
 export async function runServeCommand(opts = {}) {
+    // 워커 다중화(결정 84): 2 이상이고 이 프로세스가 프라이머리면 감독만 한다.
+    // 워커(cluster.isWorker)와 단일 프로세스(count=1)는 아래 서버 본문을 실행한다.
+    const workerCount = resolveWorkerCount(opts.workers);
+    if (workerCount > 1 && cluster.isPrimary) {
+        return runClusterPrimary(workerCount, opts);
+    }
     const cwd = opts.cwd ?? process.cwd();
     const json = opts.json ?? false;
     const signals = opts.signals ?? process;
@@ -85,4 +168,9 @@ export async function runServeCommand(opts = {}) {
         signals.on('SIGINT', stop);
         signals.on('SIGTERM', stop);
     });
+    // 클러스터 워커는 graceful close 후에도 cluster IPC 채널이 이벤트 루프를 잡아
+    // 프로세스가 안 죽는다 → 프라이머리가 워커 소멸을 감지 못 해 매달린다. close 가
+    // 끝난 뒤 명시적으로 종료한다(안전). 단일 프로세스는 자연 종료(호출 안 함). 결정 84.
+    if (cluster.isWorker)
+        process.exit(0);
 }

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

@@ -1,5 +1,12 @@
 <script setup lang="ts">
 import { pageProps, router } from 'gaonjs/vue'
+import Card from '../components/ui/Card.vue'
+import CardHeader from '../components/ui/CardHeader.vue'
+import CardTitle from '../components/ui/CardTitle.vue'
+import CardDescription from '../components/ui/CardDescription.vue'
+import CardContent from '../components/ui/CardContent.vue'
+import CardFooter from '../components/ui/CardFooter.vue'
+import Button from '../components/ui/Button.vue'
 
 // dashboard#show 의 render props — user 는 직렬화되며 passwordDigest 는 없다(§4.2).
 const { user, csrf } = pageProps<'{{APP_NAME}}:dashboard#show'>()
@@ -14,9 +21,18 @@ function logout(): void {
 </script>
 
 <template>
-  <main>
-    <h1>환영합니다, {{ user.name }}님</h1>
-    <p>{{ user.email }}</p>
-    <button type="button" @click="logout">로그아웃</button>
-  </main>
+  <div class="mx-auto max-w-2xl px-4 py-10">
+    <Card>
+      <CardHeader>
+        <CardTitle>환영합니다, {{ user.name }}님</CardTitle>
+        <CardDescription>{{ user.email }}</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p class="text-sm text-muted-foreground">보호된 페이지입니다 — this.requireAuth() 로 지킵니다.</p>
+      </CardContent>
+      <CardFooter>
+        <Button variant="outline" @click="logout">로그아웃</Button>
+      </CardFooter>
+    </Card>
+  </div>
 </template>

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

@@ -1,5 +1,16 @@
 <script setup lang="ts">
 import { pageProps, useForm } from 'gaonjs/vue'
+import Card from '../../components/ui/Card.vue'
+import CardHeader from '../../components/ui/CardHeader.vue'
+import CardTitle from '../../components/ui/CardTitle.vue'
+import CardDescription from '../../components/ui/CardDescription.vue'
+import CardContent from '../../components/ui/CardContent.vue'
+import Form from '../../components/ui/Form.vue'
+import FormField from '../../components/ui/FormField.vue'
+import Input from '../../components/ui/Input.vue'
+import Button from '../../components/ui/Button.vue'
+import Alert from '../../components/ui/Alert.vue'
+import AlertDescription from '../../components/ui/AlertDescription.vue'
 
 // 컨트롤러 session#new 의 render props 타입이 그대로 흐른다(§6.2).
 const { error, csrf } = pageProps<'{{APP_NAME}}:session#new'>()
@@ -10,12 +21,30 @@ const form = useForm({ email: '', password: '', _csrf: csrf })
 </script>
 
 <template>
-  <form @submit.prevent="form.post('/session')">
-    <h1>로그인</h1>
-    <p v-if="error" class="error">{{ error }}</p>
-    <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>
+  <div class="mx-auto flex min-h-[70vh] max-w-sm items-center px-4">
+    <Card class="w-full">
+      <CardHeader>
+        <CardTitle>로그인</CardTitle>
+        <CardDescription>계정으로 로그인하세요.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Alert v-if="error" variant="destructive" class="mb-4">
+          <AlertDescription>{{ error }}</AlertDescription>
+        </Alert>
+        <Form @submit="form.post('/session')">
+          <FormField label="이메일" :error="form.errors.email">
+            <Input v-model="form.email" type="email" required />
+          </FormField>
+          <FormField label="비밀번호" :error="form.errors.password">
+            <Input v-model="form.password" type="password" required />
+          </FormField>
+          <Button type="submit" class="w-full" :disabled="form.processing">로그인</Button>
+        </Form>
+        <p class="mt-4 text-center text-sm text-muted-foreground">
+          계정이 없으신가요?
+          <a href="/registration/new" class="font-medium text-primary underline-offset-4 hover:underline">회원가입</a>
+        </p>
+      </CardContent>
+    </Card>
+  </div>
 </template>

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

@@ -1,5 +1,16 @@
 <script setup lang="ts">
 import { pageProps, useForm } from 'gaonjs/vue'
+import Card from '../../components/ui/Card.vue'
+import CardHeader from '../../components/ui/CardHeader.vue'
+import CardTitle from '../../components/ui/CardTitle.vue'
+import CardDescription from '../../components/ui/CardDescription.vue'
+import CardContent from '../../components/ui/CardContent.vue'
+import Form from '../../components/ui/Form.vue'
+import FormField from '../../components/ui/FormField.vue'
+import Input from '../../components/ui/Input.vue'
+import Button from '../../components/ui/Button.vue'
+import Alert from '../../components/ui/Alert.vue'
+import AlertDescription from '../../components/ui/AlertDescription.vue'
 
 const { error, csrf } = pageProps<'{{APP_NAME}}:registration#new'>()
 
@@ -8,13 +19,33 @@ const form = useForm({ name: '', email: '', password: '', _csrf: csrf })
 </script>
 
 <template>
-  <form @submit.prevent="form.post('/registration')">
-    <h1>회원가입</h1>
-    <p v-if="error" class="error">{{ error }}</p>
-    <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>
+  <div class="mx-auto flex min-h-[70vh] max-w-sm items-center px-4">
+    <Card class="w-full">
+      <CardHeader>
+        <CardTitle>회원가입</CardTitle>
+        <CardDescription>새 계정을 만드세요.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Alert v-if="error" variant="destructive" class="mb-4">
+          <AlertDescription>{{ error }}</AlertDescription>
+        </Alert>
+        <Form @submit="form.post('/registration')">
+          <FormField label="이름" :error="form.errors.name">
+            <Input v-model="form.name" required />
+          </FormField>
+          <FormField label="이메일" :error="form.errors.email">
+            <Input v-model="form.email" type="email" required />
+          </FormField>
+          <FormField label="비밀번호" :error="form.errors.password">
+            <Input v-model="form.password" type="password" required />
+          </FormField>
+          <Button type="submit" class="w-full" :disabled="form.processing">회원가입</Button>
+        </Form>
+        <p class="mt-4 text-center text-sm text-muted-foreground">
+          이미 계정이 있으신가요?
+          <a href="/session/new" class="font-medium text-primary underline-offset-4 hover:underline">로그인</a>
+        </p>
+      </CardContent>
+    </Card>
+  </div>
 </template>

package/dist/templates/project/.dockerignore.tpl

@@ -0,0 +1,12 @@
+# 컨테이너 빌드에서 제외 — 호스트 산출물이 이미지로 새지 않게 한다.
+# node_modules 는 반드시 제외: 호스트(예: darwin/arm64) 네이티브 바이너리가
+# 리눅스 컨테이너로 복사되면 esbuild 등이 깨진다(이미지 안에서 재설치).
+node_modules
+**/node_modules
+.gaon
+dist
+.git
+.env
+.env.*
+npm-debug.log*
+*.log

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

@@ -2,8 +2,8 @@
 
 이 문서는 **AI 코딩 에이전트**(Claude · Codex · Cursor · Copilot 등)와
 사람 개발자가 Gaon 프로젝트에서 작업할 때 참조하는 관례의 진입점이다.
-정본은 설계 문서(v0.15 동결 + errata E-1~E-5, v0.16 편입)이며, 관례
-문서는 **2층 구조**다 (결정 40):
+정본은 설계 문서(`docs/gaondesignv0.17.md` · v1.0 출시 기준 스냅샷 ·
+v0.15+errata→v0.16→v0.17 · 결정 31~89)이며, 관례 문서는 **2층 구조**다 (결정 40):
 
 - **이 파일 (코어)** — 절대 규칙 · 로직 배치 판단표 · 검증 루프 ·
   카테고리 색인. 여기엔 요약만 있다.
@@ -104,7 +104,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 13종
+### 2.2 `gaon doctor` 검사 17종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -119,6 +119,10 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 11. `model-filename` — 모델 파일명 PascalCase 관례 (결정 32·46 · `--fix` 지원)
 12. `page-filename` — Vue 페이지 파일명 PascalCase 관례 (결정 32·46)
 13. `auth-wiring` — requireAuth/this.auth 사용 ↔ `app.config.ts` 인증 배선 (결정 59)
+14. `ui-kit-wiring` — UI 킷 컴포넌트 import ↔ `apps/<앱>/style.css` Tailwind 배선 (결정 76 · 경고)
+15. `route-registration` — 고아 컨트롤러(파일은 있는데 `routes.ts` 미참조 · 도달 불가) (결정 79 · 경고)
+16. `static-collision` — 정적 파일(`apps/<앱>/static/`)이 라우트/에셋에 가려져 도달 불가 (결정 85 · 경고)
+17. `method-override` — `_method` HTTP 메서드 스푸핑 hack(Gaon 미지원 · router.delete 를 쓰라) (결정 89 · 경고)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -159,7 +163,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 13종 (§2.2)
+gaon doctor       # 정적 검사 17종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)
@@ -209,7 +213,8 @@ gaon doctor       # 정적 검사 13종 (§2.2)
 
 ## 7. 참고 문서
 
-- 설계 정본: `docs/gaondesignv0.15.md` (동결) + errata E-1~E-5
+- 설계 정본: `docs/gaondesignv0.17.md` (v1.0 출시 기준 스냅샷 · 결정 31~89) ·
+  이력 동결 = `gaondesignv0.16.md`·`v0.15.md` + errata E-1~E-5
   (E-1 파사드명 · E-2 실시간 TCP · E-3 JSON 액션/params · E-4 컬럼·
   체이닝 · E-5 컴포저블·레이아웃).
 - 가이드: `docs/guides/*.md` (getting-started · data · data-flow ·

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 금지).
@@ -84,7 +85,7 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 
 ```bash
 gaon check                        # .gaon 재생성 후 타입 검사 (CI 정합)
-gaon doctor                       # 정적 검사 5종 (응답·N+1·의존·커넥션·마이그)
+gaon doctor                       # 정적 검사 17종 (응답·N+1·의존·커넥션·마이그·순수·자동import·파일명/컬럼·인증·UI킷·라우트 · 상세 AGENTS §2.2)
 npm test                          # Vitest · DB 테스트는 실 Docker 필수 (§9)
 ```
 

package/dist/templates/project/Dockerfile.tpl

@@ -0,0 +1,30 @@
+# {{PROJECT_NAME}} 운영 이미지 — Node 22 · pnpm · TS 네이티브(gaon serve)
+#
+# gaonjs 는 TS 네이티브(Node 타입 스트리핑)라 별도 tsc 빌드가 없다. `vite build`
+# 로 프론트 번들만 만들고, 런타임은 소스 + 번들을 `gaon serve` 로 그대로 돌린다.
+# 웹·워커·허브 프로세스는 compose.prod.yaml 이 같은 이미지로 command 만 바꿔 띄운다.
+
+FROM node:22-slim AS base
+ENV PNPM_HOME=/pnpm PATH=/pnpm:$PATH
+RUN corepack enable
+WORKDIR /app
+
+# 1) 의존 설치 — lockfile 로 재현 가능하게(빌드에 dev 의존 필요).
+FROM base AS deps
+COPY package.json pnpm-lock.yaml* pnpm-workspace.yaml ./
+RUN pnpm install --frozen-lockfile
+
+# 2) 프론트 번들 빌드(vite build).
+FROM base AS build
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN pnpm build
+
+# 3) 런타임 — 소스 + 번들 + 의존을 그대로 실행.
+FROM base AS runtime
+ENV NODE_ENV=production
+COPY --from=build /app ./
+# 웹 서버 포트(gaon.config.ts 의 web.port · 기본 3000). 프록시 뒤에 둔다.
+EXPOSE 3000
+# 웹 프로세스. 워커(gaon work)·허브(gaon hub)는 compose.prod.yaml 의 별도 서비스.
+CMD ["pnpm", "serve"]

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

@@ -115,26 +115,38 @@ 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)이
   흡수한다.
 - 아웃박스 테이블(`_gaon_outbox`)은 코어 내장이며 워커 기동 시 보장된다.
+- 발행 완료 행은 릴레이가 **자동 정리(purge)** 한다 — 기본 7일 보존 후 삭제
+  (결정 78). 수동 cleanup 코드를 쓰지 말 것. 보존 기간·간격은 `gaon work` 의
+  `outboxRetentionMs`·`outboxPurgeIntervalMs` 로 조정한다(운영 상세는
+  `docs/guides/operations.md`). 미발행 행은 절대 삭제되지 않는다.
 
 ### 5. 스케줄러