@gaonjs/cli 0.24.0 → 0.26.0

package/dist/commands/test.js

@@ -22,6 +22,10 @@
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { loadGaonConfig } from '@gaonjs/config';
+import { deriveTestDatabaseConfig, ensureTestDatabaseExists, destroyAllConnections, } from '@gaonjs/data';
+import { registerTsResolve } from '../tsResolve.js';
+import { runDbMigrate } from '../db/migrate.js';
 /** 사용자 프로젝트에 `test` 스크립트가 있는지. */
 function hasTestScript(cwd) {
     const pkgPath = join(cwd, 'package.json');
@@ -52,6 +56,66 @@ function scopeArgs(scope) {
     }
     return [];
 }
+/**
+ * 결정 111: 테스트 전용 DB 자동 준비 — gaon.config 의 각 커넥션을 `<db>_test` 로
+ * 파생해 없으면 만들고(CREATE DATABASE) 마이그레이션을 적용한다. 테스트 프로세스는
+ * test/setup.ts 의 `connectTestDatabase()` 로 같은 DB 에 붙고, 매 테스트 뒤
+ * `truncateAll()` 로 격리한다(§9 실 인프라 · truncate 격리 근거는 결정 111).
+ *
+ * scope='unit' 은 실 인프라가 필요 없으므로 건너뛴다. config 가 없거나 db 커넥션이
+ * 없으면 조용히 스킵(순수 vitest 위임). DB 접속 실패는 수리 안내와 함께 실패한다.
+ */
+async function provisionTestDatabases(cwd, json) {
+    registerTsResolve();
+    let config;
+    try {
+        config = await loadGaonConfig(cwd);
+    }
+    catch {
+        return true; // config 로드 실패 = 최소 프로젝트 · DB 준비 스킵
+    }
+    const dbs = config.db ? Object.entries(config.db) : [];
+    if (dbs.length === 0)
+        return true;
+    const prepared = [];
+    try {
+        for (const [key, cfg] of dbs) {
+            const testCfg = deriveTestDatabaseConfig(cfg);
+            await ensureTestDatabaseExists(testCfg);
+            const res = await runDbMigrate({
+                cwd,
+                dbKey: key,
+                json: false,
+                dryRun: false,
+                connectionOverride: testCfg,
+            });
+            if (res.exitCode !== 0) {
+                if (!json)
+                    process.stderr.write(`  ✗ 테스트 DB '${key}' 마이그레이션 실패\n${res.text}\n`);
+                return false;
+            }
+            prepared.push(key);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const hint = `  ✗ 테스트 DB 준비 실패: ${msg}\n` +
+            `  → DB 가 떠 있는지 확인하세요(docker compose up -d db). 테스트는 실 인프라가 필요합니다(§9).\n`;
+        if (json)
+            process.stdout.write(JSON.stringify({ ok: false, kind: 'provision', error: msg }) + '\n');
+        else
+            process.stderr.write(hint);
+        return false;
+    }
+    finally {
+        await destroyAllConnections();
+    }
+    if (json)
+        process.stdout.write(JSON.stringify({ kind: 'provisioned', dbs: prepared }) + '\n');
+    else
+        process.stdout.write(`  gaon test · 테스트 DB 준비 완료 (${prepared.join(', ')}) — <db>_test\n`);
+    return true;
+}
 /**
  * `gaon test` 진입점. args 는 사용자가 넘긴 잔여 인자(필터 문자열 등).
  * pnpm test 는 pnpm 관례상 `pnpm test -- <args>` 로 넘겨야 vitest 까지 도달.
@@ -60,6 +124,12 @@ export async function runTestCommand(args = [], opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const scope = opts.scope ?? 'all';
     const json = opts.json ?? false;
+    // 결정 111: unit 이 아니면 실행 전 테스트 DB 를 준비한다(생성 + 마이그레이션).
+    if (scope !== 'unit') {
+        const ok = await provisionTestDatabases(cwd, json);
+        if (!ok)
+            return 1;
+    }
     const scopeExtras = scopeArgs(scope);
     const passthrough = [...scopeExtras, ...args];
     let cmd;

package/dist/db/migrate.d.ts

@@ -1,3 +1,4 @@
+import { type ConnectionConfig } from '@gaonjs/data';
 import { listMigrationFiles } from './replay.js';
 export interface DbMigrateOptions {
     readonly cwd: string;
@@ -7,6 +8,8 @@ export interface DbMigrateOptions {
     /** `gaon db migrate down` — 가장 최근 이력 한 건 롤백. */
     readonly down?: boolean;
     readonly configPath?: string;
+    /** 명시 커넥션 오버라이드(결정 111 · gaon test 의 <db>_test). */
+    readonly connectionOverride?: ConnectionConfig;
 }
 export interface DbMigrateResult {
     readonly exitCode: number;

package/dist/db/migrate.js

@@ -41,6 +41,7 @@ export async function runDbMigrate(opts) {
         cwd: opts.cwd,
         dbKey: opts.dbKey,
         configPath: opts.configPath,
+        connectionOverride: opts.connectionOverride,
     });
     try {
         if (opts.down)

package/dist/db/resolve.d.ts

@@ -1,4 +1,4 @@
-import { type TableDef } from '@gaonjs/data';
+import { type ConnectionConfig, type TableDef } from '@gaonjs/data';
 import type { Kysely } from 'kysely';
 import { type Dialect, type AdapterName } from '@gaonjs/data';
 export interface ResolveDbOptions {
@@ -6,6 +6,12 @@ export interface ResolveDbOptions {
     readonly dbKey: string;
     /** --config <path> 로 사용자가 지정한 config 경로. 없으면 cwd 관례. */
     readonly configPath?: string;
+    /**
+     * 명시 커넥션 설정 오버라이드(결정 111). 주면 config.db·GAON_DATABASE_URL 보다
+     * 우선한다 — `gaon test` 가 <db>_test 로 마이그레이션을 돌릴 때 쓴다. 스키마 스캔
+     * (tables)은 여전히 config/cwd 관례를 따른다.
+     */
+    readonly connectionOverride?: ConnectionConfig;
 }
 export interface ResolvedDbTarget {
     readonly dbKey: string;

package/dist/db/resolve.js

@@ -92,7 +92,11 @@ export async function resolveDbTarget(opts) {
     const dbKey = opts.dbKey;
     const cfg = config.db?.[dbKey];
     let connCfg;
-    if (cfg) {
+    if (opts.connectionOverride) {
+        // 결정 111: 명시 오버라이드(gaon test 의 <db>_test) 최우선.
+        connCfg = opts.connectionOverride;
+    }
+    else if (cfg) {
         connCfg = cfg;
     }
     else if (dbKey === 'main') {

package/dist/doctor/page-layout-breakpoint.d.ts

@@ -0,0 +1,8 @@
+import type { RuleReport } from './types.js';
+/** 소스에서 레이아웃 브레이크포인트 사용 위치(토큰·줄)를 모은다(단위 테스트 진입점). */
+export declare function usesLayoutBreakpoint(source: string): {
+    token: string;
+    line: number;
+}[];
+/** apps/<앱>/pages 를 훑어 페이지 레이아웃 브레이크포인트 사용을 경고로 낸다. */
+export declare function checkPageLayoutBreakpoint(cwd: string): Promise<RuleReport>;

package/dist/doctor/page-layout-breakpoint.js

@@ -0,0 +1,94 @@
+// @gaonjs/cli · doctor · 페이지 레이아웃 브레이크포인트 안내 (결정 107)
+//
+// 폭·여백·열 수 같은 레이아웃 반응형은 UI 킷 블록(PageShell·PageHeader …)이
+// 소유한다(결정 105·106·107). 페이지 파일이 레이아웃 브레이크포인트를 루트에서
+// 직접 쓰면 반응형 규칙이 여러 곳에 흩어져, "정답이 하나" 가 무너진다. 이 검사는
+// 그 사용을 **안내 경고(warning)** 로만 낸다 — 강제(error)가 아니다. 킷에 없는
+// 표현이면 Tailwind 유틸을 직접 써도 되므로(탈출구), 오탐을 줄이려 신호가 확실한
+// 레이아웃 유틸(반응형 flex-direction·grid 열 수)만 좁게 잡는다.
+//
+// 대상: apps/<앱>/pages/**/*.vue (페이지 파일만). shared/components/ui 의 킷 블록은
+// 반응형을 소유하므로 검사하지 않는다(그게 이 규칙의 목적).
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+/**
+ * 좁게 잡는 레이아웃 반응형 패턴: 반응형 접두사 + (flex-row/col · grid-cols-N/[).
+ * `sm:hidden`·`sm:text-lg`·`sm:px-6` 같은 흔한 반응형(표시·타이포·여백)은 잡지
+ * 않는다 — 오탐을 줄이려 페이지 레이아웃을 뒤집는 확실한 신호만 본다.
+ */
+const LAYOUT_BREAKPOINT = /\b(sm|md|lg|xl|2xl):(flex-(?:row|col)(?:-reverse)?|grid-cols-(?:\d+|\[))/;
+/** 소스에서 레이아웃 브레이크포인트 사용 위치(토큰·줄)를 모은다(단위 테스트 진입점). */
+export function usesLayoutBreakpoint(source) {
+    const out = [];
+    const lines = source.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const m = LAYOUT_BREAKPOINT.exec(lines[i]);
+        if (m)
+            out.push({ token: m[0], line: i + 1 });
+    }
+    return out;
+}
+/** apps/<앱>/pages 를 훑어 페이지 레이아웃 브레이크포인트 사용을 경고로 낸다. */
+export async function checkPageLayoutBreakpoint(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        const pagesDir = join(appsDir, app, 'pages');
+        for (const abs of await walkVueFiles(pagesDir)) {
+            const source = await readFile(abs, 'utf8').catch(() => '');
+            const hits = usesLayoutBreakpoint(source);
+            if (hits.length === 0)
+                continue;
+            const rel = relative(cwd, abs);
+            const first = hits[0];
+            issues.push({
+                rule: 'page-layout-breakpoint',
+                level: 'warning',
+                file: rel,
+                line: first.line,
+                message: `${rel} (line ${first.line})\n` +
+                    `  페이지가 레이아웃 브레이크포인트('${first.token}'${hits.length > 1 ? ` 외 ${hits.length - 1}건` : ''})를 직접 씁니다.\n` +
+                    `  반응형(폭·여백·열 수)은 UI 킷 블록이 책임집니다(결정 107).\n` +
+                    `→ shared/components/ui 의 블록(PageShell·PageHeader 등)으로 감싸 반응형을 킷에 두거나,\n` +
+                    `  킷에 없는 표현이면 그대로 둬도 됩니다 — 이 경고는 강제가 아닙니다(탈출구 유지).`,
+                detail: { token: first.token, count: hits.length },
+            });
+        }
+    }
+    return { rule: 'page-layout-breakpoint', issues };
+}
+/** 디렉터리 트리에서 .vue 파일 절대경로를 모은다(테스트·선언 제외 불필요 — .vue 만). */
+async function walkVueFiles(dir) {
+    const out = [];
+    const walk = async (d) => {
+        let entries;
+        try {
+            entries = (await readdir(d, { withFileTypes: true }));
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const abs = join(d, e.name);
+            if (e.isDirectory()) {
+                if (e.name === 'node_modules' || e.name === '.gaon' || e.name === 'dist')
+                    continue;
+                await walk(abs);
+            }
+            else if (e.isFile() && e.name.endsWith('.vue')) {
+                out.push(abs);
+            }
+        }
+    };
+    await walk(dir);
+    return out.sort();
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = (await readdir(dir, { withFileTypes: true }));
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor/ui-kit-wiring.js

@@ -1,10 +1,12 @@
-// @gaonjs/cli · doctor · UI 킷 배선 검사 (결정 76)
+// @gaonjs/cli · doctor · UI 킷 배선 검사 (결정 76 · 결정 105)
 //
-// 앱이 UI 킷 컴포넌트(apps/<앱>/components/ui/*)를 import 하는데 그 앱에
-// Tailwind 배선(apps/<앱>/style.css 의 @tailwind + main.ts 의 style.css import)이
-// 없으면, UI 킷이 쓰는 유틸 클래스(bg-primary·rounded-lg …)가 펼쳐지지 않아
-// 컴포넌트가 스타일 없이 렌더된다 — 컴파일은 통과하므로 check 로는 안 잡히는
-// 조용한 런타임 파손이다(결정 74·75·76). 이 검사가 그 상태를 경고로 낸다.
+// 앱이 UI 킷 컴포넌트(@shared/components/ui/* — 결정 105 로 shared 이전)를
+// import 하는데 그 앱에 Tailwind 배선(apps/<앱>/style.css 의 @tailwind +
+// main.ts 의 style.css import)이 없으면, UI 킷이 쓰는 유틸 클래스(bg-primary·
+// rounded-lg …)가 펼쳐지지 않아 컴포넌트가 스타일 없이 렌더된다 — 컴파일은
+// 통과하므로 check 로는 안 잡히는 조용한 런타임 파손이다(결정 74·75·76·105).
+// 이 검사가 그 상태를 경고로 낸다. 킷 위치와 무관하게 import 경로에 남는
+// 'components/ui/' 로 사용처를 잡으므로 @shared alias 도 그대로 감지된다.
 //
 // `gaon new`(web)·`gaon g app` 은 이제 배선을 함께 심으므로 정상 경로에서는
 // 걸리지 않는다. 이 규칙은 배선을 지웠거나 구버전 스캐폴드에서 만든 앱을 잡는
@@ -44,7 +46,9 @@ export async function checkUiKitWiring(cwd) {
 /** 앱 디렉터리를 재귀 스캔해 UI 킷을 import 하는 첫 .vue/.ts 파일(cwd 상대)을 찾는다. */
 async function findUiKitImporter(appDir, cwd) {
     for (const abs of await walkSources(appDir)) {
-        // components/ui 안의 컴포넌트 자체는 서로를 import 하므로 제외한다.
+        // 킷은 이제 shared/ 라 apps/ 스캔엔 안 들어오지만, 결정 105 이전의 앱별
+        // 사본(apps/<앱>/components/ui)이 남아 있으면 그 컴포넌트끼리의 상호 import 를
+        // 사용처로 오인하지 않도록 제외한다(마이그레이션 과도기 방어).
         if (abs.includes(`${join(appDir, 'components', 'ui')}`))
             continue;
         const source = await readFile(abs, 'utf8').catch(() => '');

package/dist/doctor.d.ts

@@ -19,6 +19,7 @@ export { hasStateChangingRoutes, checkCsrfWiring } from './doctor/csrf-wiring.js
 export { internalAnchorHref, usesInternalAnchor, checkInternalAnchor, } from './doctor/internal-anchor.js';
 export { usesPagePropsDestructure, checkPagePropsDestructure, } from './doctor/pageprops-destructure.js';
 export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActions, checkAsyncOffload, } from './doctor/async-offload.js';
+export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 export interface DoctorCommandOptions {

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 21 검사를 조립한다:
+ * 22 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -23,6 +23,7 @@
  * 19) internal-anchor (결정 96 · 앱 내부 이동 일반 <a> = 풀 리로드 경고)
  * 20) pageprops-destructure (결정 99 · pageProps() 구조분해 = 반응성 끊김 경고)
  * 21) async-offload (결정 102·103 · 컨트롤러 인라인 메일·이미지·외부 HTTP = 응답 지연 경고)
+ * 22) page-layout-breakpoint (결정 107 · 페이지 레이아웃 브레이크포인트 직접 사용 = 안내 경고)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -56,6 +57,7 @@ import { checkCsrfWiring } from './doctor/csrf-wiring.js';
 import { checkInternalAnchor } from './doctor/internal-anchor.js';
 import { checkPagePropsDestructure } from './doctor/pageprops-destructure.js';
 import { checkAsyncOffload } from './doctor/async-offload.js';
+import { checkPageLayoutBreakpoint } from './doctor/page-layout-breakpoint.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -78,6 +80,7 @@ export { hasStateChangingRoutes, checkCsrfWiring } from './doctor/csrf-wiring.js
 export { internalAnchorHref, usesInternalAnchor, checkInternalAnchor, } from './doctor/internal-anchor.js';
 export { usesPagePropsDestructure, checkPagePropsDestructure, } from './doctor/pageprops-destructure.js';
 export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActions, checkAsyncOffload, } from './doctor/async-offload.js';
+export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
@@ -105,6 +108,7 @@ const ALL_RULES = [
     'internal-anchor',
     'pageprops-destructure',
     'async-offload',
+    'page-layout-breakpoint',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -128,6 +132,7 @@ const CHECKERS = {
     'internal-anchor': checkInternalAnchor,
     'pageprops-destructure': checkPagePropsDestructure,
     'async-offload': checkAsyncOffload,
+    'page-layout-breakpoint': checkPageLayoutBreakpoint,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/index.js

@@ -100,8 +100,8 @@ function renderHelp(version = VERSION) {
         "    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        정적 검사 (21 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드)",
+        "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all · -- vitest 인자)",
+        "    gaon doctor        정적 검사 (22 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",

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

@@ -1,12 +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'
+import Card from '@shared/components/ui/Card.vue'
+import CardHeader from '@shared/components/ui/CardHeader.vue'
+import CardTitle from '@shared/components/ui/CardTitle.vue'
+import CardDescription from '@shared/components/ui/CardDescription.vue'
+import CardContent from '@shared/components/ui/CardContent.vue'
+import CardFooter from '@shared/components/ui/CardFooter.vue'
+import Button from '@shared/components/ui/Button.vue'
 
 // dashboard#show 의 render props — user 는 직렬화되며 passwordDigest 는 없다(§4.2).
 // pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).

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

@@ -1,16 +1,16 @@
 <script setup lang="ts">
 import { pageProps, useForm, Link } 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'
+import Card from '@shared/components/ui/Card.vue'
+import CardHeader from '@shared/components/ui/CardHeader.vue'
+import CardTitle from '@shared/components/ui/CardTitle.vue'
+import CardDescription from '@shared/components/ui/CardDescription.vue'
+import CardContent from '@shared/components/ui/CardContent.vue'
+import Form from '@shared/components/ui/Form.vue'
+import FormField from '@shared/components/ui/FormField.vue'
+import Input from '@shared/components/ui/Input.vue'
+import Button from '@shared/components/ui/Button.vue'
+import Alert from '@shared/components/ui/Alert.vue'
+import AlertDescription from '@shared/components/ui/AlertDescription.vue'
 
 // 컨트롤러 session#new 의 render props 타입이 그대로 흐른다(§6.2). pageProps 는
 // 반응형이라 변수로 받아 props.x 로 접근한다 — 구조분해 금지(결정 99). 로그인

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

@@ -1,16 +1,16 @@
 <script setup lang="ts">
 import { pageProps, useForm, Link } 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'
+import Card from '@shared/components/ui/Card.vue'
+import CardHeader from '@shared/components/ui/CardHeader.vue'
+import CardTitle from '@shared/components/ui/CardTitle.vue'
+import CardDescription from '@shared/components/ui/CardDescription.vue'
+import CardContent from '@shared/components/ui/CardContent.vue'
+import Form from '@shared/components/ui/Form.vue'
+import FormField from '@shared/components/ui/FormField.vue'
+import Input from '@shared/components/ui/Input.vue'
+import Button from '@shared/components/ui/Button.vue'
+import Alert from '@shared/components/ui/Alert.vue'
+import AlertDescription from '@shared/components/ui/AlertDescription.vue'
 
 // pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
 const props = pageProps<'{{APP_NAME}}:registration#new'>()

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

@@ -104,7 +104,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 21종
+### 2.2 `gaon doctor` 검사 22종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -127,6 +127,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 19. `internal-anchor` — 앱 내부 경로 일반 `<a href="/...">`(풀 리로드로 SPA 파손 · `Link`/`router.visit` 를 쓰라 · 외부 URL·`target="_blank"` 는 제외) (결정 96 · 경고)
 20. `pageprops-destructure` — `const { x } = pageProps(…)` 구조분해(반응성 끊김 · 리다이렉트/리로드 후 갱신 안 됨 · `const props = pageProps(…)` 후 `props.x` 로 접근하라) (결정 99 · 경고)
 21. `async-offload` — 컨트롤러 액션 인라인의 무거운/외부 작업(메일 SDK·이미지 처리 sharp/jimp·외부 HTTP)이 응답을 지연 (`domain/jobs/` 잡 + `.later()` 로 빼라 · JSON/API 앱 외부 호출·빠른 내부 호출은 오탐 방지로 제외) (결정 102·103 · 경고)
+22. `page-layout-breakpoint` — 페이지 파일이 레이아웃 브레이크포인트(`sm:flex-row`·`md:grid-cols-2` 등)를 직접 사용(반응형은 UI 킷 블록이 책임 · `PageShell` 등으로 감싸라 · 킷에 없는 표현이면 그대로 둬도 됨 · 표시/타이포/여백 반응형은 오탐 방지로 제외) (결정 107 · 안내 경고)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -187,7 +188,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 21종 (§2.2)
+gaon doctor       # 정적 검사 22종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)

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

@@ -179,9 +179,9 @@ export const posts = table('posts', {
 | `where` | `(col, op, val?)` | `Chain` | op 에 따라 val 형태 강제 (위 표) |
 | `whereIn` | `(col, vals)` | `Chain` | `where(col, 'in', vals)` 축약 |
 | `orWhere` | `(col, op, val?)` | `Chain` | op 12종 전부 (M2C) · 결합은 `(a AND b) OR c` (Rails 관습 · `model.ts:245-262`) |
-| `orderBy` | `(col, dir?)` | `Chain` | dir 기본 `'asc'` · 호출마다 누적 (다중 정렬) |
+| `orderBy` | `(col, dir?)` | `Chain` | dir 기본 `'asc'` · 호출마다 누적 (다중 정렬) · 정렬 뒤 PK 타이브레이커 자동 부가(결정 110) |
 | `reorder` | `(col, dir?)` | `Chain` | 기존 정렬 전부 버리고 재지정 |
-| `latest` | `()` | `Chain` | `orderBy('createdAt', 'desc')` 고정 축약 |
+| `latest` | `()` | `Chain` | `orderBy('createdAt', 'desc')` 고정 축약 · id 타이브레이커로 결정적(결정 110) |
 | `limit` | `(n)` | `Chain` | |
 | `offset` | `(n)` | `Chain` | 페이지네이션 = `orderBy·offset·limit` 조합 |
 | `first` | `()` | `Promise<Rec \| undefined>` | 자동 `limit 1` |
@@ -395,6 +395,37 @@ export const Post = model(posts, {
 })
 ```
 
+### 8.1 스키마 파생 폼 — `Model.form` · `Model.form.pick()` (결정 104)
+
+모든 모델은 `Model.form` 으로 **스키마 파생 폼**을 노출한다 — 컨트롤러의
+`this.params(Model.form)` 에 넘기면 컬럼 타입으로 런타임 강제 변환·검증
+(필수 강제 · 스키마 밖 키 제거 = 대량 할당 차단)까지 한다. 컨트롤러 쪽
+사용법(폼 모양 판단·라우트 파라미터 병합)은 `agents/web.md` §3 이 정본이다.
+
+**일부 컬럼만 검증해서 받으려면 `pick()`** — 지정한 컬럼만 담은 **새 폼**을
+돌려준다(원 폼 불변). 컬럼 타입·검증·기본값 정보가 그대로 따라오므로,
+"검증되는 부분 폼"이 필요할 때 애드혹 `{ _row: {} as T }`(검증 없음) 대신 쓴다.
+
+```ts
+// routes: r.post('/posts/:postId/comments', 'comments#create')
+// comments 스키마에서 postId·author·body 만 — :postId 는 라우트에서 자동 병합(결정 95).
+async create() {
+  const data = this.params(Comment.form.pick('postId', 'author', 'body'))
+  // data: { postId: bigint; author: string; body: string } — 안 고른 컬럼은 요구하지 않는다.
+  const comment = await Comment.create(data)
+  return this.redirect(`/posts/${String(data.postId)}`)
+}
+```
+
+- `pick()` 결과도 폼이다 — 부분집합으로 다시 `pick()` 할 수 있다.
+- 스키마에 없는 컬럼을 지정하면 즉시 throw(수리 안내 포함) · 빈
+  `pick()` 도 throw · 중복 지정은 조용히 하나로 합친다.
+- **정적 default 컬럼은 빈 입력이면 그 default 로 채워진다**(결정 108) —
+  `t.string().default('N/A')` 같은 컬럼을 pick 해 빈 값('')·미전송으로 받으면
+  런타임이 default 를 채운다(폼 타입이 required 인데 undefined 로 새지 않는다).
+  동적 default(`now()`·`gen_random_uuid()`·bigserial)는 채우지 않고 DB 가 채운다.
+- `omit`·`extend`·`merge` 는 **없다** — 폼 변형은 `pick()` 하나가 The One Way.
+
 ### 9. 서비스 (`service()`) — 트랜잭션 작업 흐름 (정본 §5.3 · `packages/data/src/service.ts`)
 
 로직 배치의 One Way 규칙은 루트 `AGENTS.md` 판단표가 정본이다 (정본 §5.3):
@@ -601,6 +632,9 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
   doctor **model-filename** 이 잡는다(`--fix` 지원 · 결정 32·46).
 - **잡·이벤트 발행을 트랜잭션과 정합시키려면** `afterCommit()`(service 안)
   또는 아웃박스(`agents/async.md`) — 커밋 전 발행은 롤백 시 유령 부수효과.
+- **폼 변형은 `pick()` 뿐** (결정 104) — `Model.form.omit/extend/merge` 는
+  없다. 검증되는 부분 폼 = `pick()`, 스키마와 무관한 입력만 애드혹
+  `{ _row: {} as T }`(검증 없음 · `agents/web.md` §3).
 
 ## 관련 결정 번호
 
@@ -615,4 +649,7 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
 | 결정 43 | 네이밍 정본화 · DB 네이밍 SSOT(§1.2 · 테이블 snake · 컬럼 camel) |
 | 결정 46 | doctor 컬럼(column-casing)·모델/페이지 파일명 검사 3종 |
 | 결정 47 | `gaon g model` 다단어 테이블명 snake_case(마지막 단어 복수) |
+| 결정 104 | 스키마 파생 폼에 name·defs 탑재(실검증) · `Model.form.pick()` 검증되는 부분 폼(§8.1) |
+| 결정 108 | 정적 default 컬럼 빈 입력 채움(§8.1) · 동적 default 는 DB 위임 |
+| 결정 110 | `latest()`·`orderBy` 정렬 뒤 PK 타이브레이커 자동 부가(결정적 페이지네이션 · §4) |
 | E-4 | 컬럼 타입·수식어·체이닝 확장 · `Post.query()` 정정 · Serialized 명명 |