@gaonjs/cli 0.47.0 → 0.55.0

package/dist/index.js

@@ -109,13 +109,15 @@ function renderHelp(version = VERSION) {
         "    gaon gen           .gaon 타입 브리지 + api() 런타임 매니페스트만 재생성 (서버·검사 없이 · build 전제 · --json)",
         "    gaon build         멀티 앱 프론트 프로덕션 빌드 (gaon gen + apps/* 순회 · 앱별 dist/<앱>·base=/<앱>/ · --json)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
-        "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all · -- vitest 인자)",
-        `    gaon doctor        정적 검사 (${ALL_RULES.length} 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계·import.meta.env·로케일 커버리지)`,
+        "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all)",
+        "    gaon test -- <인자>       `--` 뒤는 vitest 로 그대로 전달 (gaon 이 안 가로챔 · 예: gaon test -- --json --reporter=json)",
+        `    gaon doctor        정적 검사 (${ALL_RULES.length} 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계·import.meta.env·로케일 커버리지·render return 누락)`,
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
         "    gaon doctor --fix --yes                   실제 편집 적용(원본은 .bak-<타임스탬프> 로 자동 백업)",
-        "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트)",
+        "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트 · --jwt --app <api> = API 앱 토큰 변형 · --public = 비-web 앱 공개 가입)",
+        "    gaon g ui-kit      UI 킷 스캐폴드 (Button·Input 등 원자 프리미티브 · --app <이름>)",
         "    gaon g controller <name>   컨트롤러 스캐폴드 (Rails 관례 · 페이지+JSON 액션)",
         "    gaon g model <Name>        모델 스캐폴드 (스키마+모델 · E-4 컬럼 예시)",
         "    gaon g page <Path/Name>    Vue 페이지 (Inertia SPA · pageProps 브리지)",
@@ -147,19 +149,34 @@ function renderHelp(version = VERSION) {
  * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
  */
 export function parseDoctorChecks(argv) {
-    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 27종)를 단일 출처로 쓴다 — 과거
+    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 28종)를 단일 출처로 쓴다 — 과거
     // 손유지 9종 리스트가 뒤처져 --check=seal-security 같은 16종이 조용히 무시되고
     // 전체 검사로 되돌아가던 표류를 근본 차단한다(결정 168).
     const isKnown = (s) => ALL_RULES.includes(s);
     const out = [];
+    const unknown = [];
     for (const a of argv) {
         if (a.startsWith("--check=")) {
             for (const nm of a.slice("--check=".length).split(",")) {
-                if (isKnown(nm) && !out.includes(nm))
-                    out.push(nm);
+                if (isKnown(nm)) {
+                    if (!out.includes(nm))
+                        out.push(nm);
+                }
+                else if (nm !== "" && !unknown.includes(nm)) {
+                    unknown.push(nm);
+                }
             }
         }
     }
+    // 결정 411: 모르는 이름은 여전히 무시하되(안전 방향 — 전체 검사로 넓어짐) **조용히**
+    // 넘기지 않는다. 오타 하나가 "그 검사만 돌렸다" 는 착각으로 이어지고, 전부 오타면
+    // 28종 전체가 돌아가 선택 실행 의도가 통째로 사라진다.
+    if (unknown.length > 0) {
+        process.stderr.write(`  ! 알 수 없는 검사 이름 무시: ${unknown.join(", ")}\n` +
+            `    → 지원 이름은 gaon doctor --json 의 rule 값 또는 gaon help 참고` +
+            (out.length === 0 ? " (인정된 이름이 없어 전체 검사를 실행합니다)" : "") +
+            "\n");
+    }
     return out.length ? out : undefined;
 }
 /**
@@ -225,6 +242,24 @@ export function parseDbArgs(sub, argv) {
     const dbIdx = argv.indexOf("--db");
     const cfgIdx = argv.indexOf("--config");
     const valueFlags = new Set(["--db", "--config"]);
+    // 결정 404: 값 플래그의 **값 부재**도 fail-loud. `gaon db migrate --db`(값 없이 끝)는
+    // db=undefined 가 돼 "커넥션 하나만" 이던 의도가 조용히 **전 커넥션 적용**으로 확장됐다
+    // (결정 139 순회 기본값과 결합해 파괴 반경이 커진다). readPortFlag(결정 240)와 같은 규약.
+    for (const f of valueFlags) {
+        const i = argv.indexOf(f);
+        if (i < 0)
+            continue;
+        const v = argv[i + 1];
+        if (v === undefined || v.startsWith("-")) {
+            throw new Error(`gaon db ${sub}: ${f} 값이 없습니다.\n` +
+                `  → 예: gaon db ${sub} ${f} ${f === "--db" ? "main" : "gaon.config.ts"}\n` +
+                `  → 값 없이 두면 ${f === "--db" ? "전 커넥션에 적용" : "기본 설정 파일 사용"}으로 조용히 넓어져 멈춥니다.`);
+        }
+    }
+    // 결정 358: db 는 파괴 방향 오동작이 가능한 명령군이라 미지 플래그를 조용히
+    // 무시하지 않는다 — `--dryrun`(오타)이 무시되면 dry-run 의도가 **실제 마이그레이션
+    // 적용**으로 반전된다(결정 267 down-위치 문제와 동형). 인정 집합 밖 `--*` 는 throw.
+    const knownFlags = new Set(["--db", "--config", "--json", "--yes", "--dry-run"]);
     const positionals = [];
     for (let i = 2; i < argv.length; i++) {
         const a = argv[i];
@@ -234,10 +269,29 @@ export function parseDbArgs(sub, argv) {
             i++; // 플래그 값 스킵
             continue;
         }
-        if (a.startsWith("--"))
-            continue; // 불리언 플래그
+        if (a.startsWith("--")) {
+            if (!knownFlags.has(a)) {
+                throw new Error(`gaon db ${sub}: 알 수 없는 플래그 '${a}'.\n` +
+                    `  → 지원 플래그: --db <키> · --config <경로> · --dry-run · --yes · --json\n` +
+                    `  → 오타(예: --dryrun)가 조용히 무시되면 의도와 반대로 실행될 수 있어 멈춥니다.`);
+            }
+            continue; // 인정된 불리언 플래그
+        }
         positionals.push(a);
     }
+    // 결정 404: 미지 **위치 인자**도 막는다. 종전엔 positionals 가 'down' 판정에만 쓰이고
+    // 나머지는 버려져서 `gaon db migrate donw`(오타)·`rollback`(타 프레임웍 관례)이 무경고로
+    // **정방향 migrate 실 적용**으로 반전됐다 — 결정 358 이 플래그에서 막은 것과 같은 파괴
+    // 방향인데 위치 인자만 뚫려 있었다.
+    const allowedPositionals = sub === "migrate" ? ["down"] : [];
+    const unknown = positionals.find((p) => !allowedPositionals.includes(p));
+    if (unknown !== undefined) {
+        throw new Error(`gaon db ${sub}: 알 수 없는 인자 '${unknown}'.\n` +
+            (sub === "migrate"
+                ? `  → 지원 인자: down(롤백) 하나뿐입니다. 예: gaon db migrate down\n`
+                : `  → gaon db ${sub} 는 위치 인자를 받지 않습니다.\n`) +
+            `  → 오타가 조용히 무시되면 의도와 반대로(예: 롤백 대신 정방향 적용) 실행될 수 있어 멈춥니다.`);
+    }
     return {
         json: argv.includes("--json"),
         db: dbIdx >= 0 ? argv[dbIdx + 1] : undefined,
@@ -362,9 +416,17 @@ export function runCli(argv, opts = {}) {
         const knownSteps = ["typecheck", "vue-tsc", "build", "doctor"];
         const onlyIdx = argv.indexOf("--only");
         const onlyRaw = onlyIdx >= 0 ? argv[onlyIdx + 1] : undefined;
-        const only = onlyRaw && knownSteps.includes(onlyRaw)
-            ? onlyRaw
-            : undefined;
+        // 결정 411: `--only` 오타를 조용히 전체 실행으로 폴백하지 않는다 — "typecheck 만
+        // 돌렸다" 는 착각으로 CI 시간이 늘거나(안전 방향이라 더 안 보인다), 반대로
+        // 단일 단계만 돌린 줄 알고 넘어간다. 값 부재도 같이 막는다(--port 규약 · 결정 240).
+        if (onlyIdx >= 0 && (onlyRaw === undefined || !knownSteps.includes(onlyRaw))) {
+            process.stderr.write(`  ✗ gaon check: --only 값이 ${onlyRaw === undefined ? "없습니다" : `잘못됐습니다('${onlyRaw}')`}.\n` +
+                `    → 지원 단계: ${knownSteps.join(" · ")}\n` +
+                `    → 예: gaon check --only typecheck\n`);
+            process.exitCode = 2;
+            return;
+        }
+        const only = onlyRaw !== undefined ? onlyRaw : undefined;
         void runCheckCommand({
             json: argv.includes("--json"),
             only,
@@ -408,7 +470,7 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(M9-E · 27 검사 · ALL_RULES 단일 출처). --check=<이름>[,<이름>...] 로
+    // `gaon doctor` — 정적 검사(M9-E · 28 검사 · ALL_RULES 단일 출처). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {
@@ -421,11 +483,20 @@ export function runCli(argv, opts = {}) {
                 process.exitCode = 2;
                 return;
             }
-            // --fix --yes: 편집이 실제로 일어났고 나머지 위반이 없으면 0,
-            //              아직 수동 수정이 남아 있으면 1(자동화 정합).
-            // --fix (dry-run): errors > 0 이면 1(안 고침) · 계획만 있어도 1.
+            // 결정 359: 종료 코드 판정.
+            // --fix --yes: runDoctorCommand 가 적용 후 **재검사** 결과를 돌려주므로
+            //              errors = 잔여 위반 — 전부 자동 수정됐으면 0(자동화 정합).
+            // --fix (dry-run): errors > 0 이면 1 · errors 0 이어도 **계획이 있으면 1**
+            //              (고칠 게 있다는 신호 — 이전엔 warning-only 계획이 0 으로 삼켜짐).
             // 기본: errors > 0 이면 1.
-            process.exitCode = result.errors.length > 0 ? 1 : 0;
+            // 결정 410: `--fix --yes` 인데 **적용에 성공한 게 하나도 없으면** 비-0.
+            // 종전엔 잔여 errors 만 봐서, 위반이 warning 레벨이고 fixer 가 전부 실패하면
+            // (fixer 예외·대상 파일 선점 등) "고친 것 0" 인데 exit 0 이라 자동화가
+            // "고쳐졌다" 로 오판했다 — 시도했는데 아무것도 못 고친 건 성공이 아니다.
+            const fix = result.fix;
+            const dryPlans = fix !== undefined && !fix.applied && fix.outcomes.length > 0;
+            const nothingApplied = fix !== undefined && fix.applied && fix.outcomes.length > 0 && !fix.outcomes.some((o) => o.applied);
+            process.exitCode = result.errors.length > 0 || dryPlans || nothingApplied ? 1 : 0;
         })
             .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
@@ -491,14 +562,35 @@ export function runCli(argv, opts = {}) {
     if (argv[0] === "db") {
         const sub = argv[1];
         const known = ["diff", "migrate", "reset", "seed", "status"];
+        // 결정 411: --json 모드면 실패 사유도 **구조화**해서 낸다 — runDbCommand 는 이미
+        // JSON 에러를 방출하는데(commands/db.ts) 라우팅 단계 실패만 텍스트라 자동화가
+        // 사유를 못 받았다(비대칭).
+        const dbJson = argv.includes("--json");
+        const failDb = (message) => {
+            if (dbJson) {
+                process.stdout.write(JSON.stringify({ ok: false, kind: "usage", command: "db", message }) + "\n");
+            }
+            else {
+                process.stderr.write(`  ✗ ${message}\n`);
+            }
+            process.exitCode = 1;
+        };
         if (!sub || !known.includes(sub)) {
-            process.stderr.write(`  ✗ 알 수 없는 db 서브커맨드: ${sub ?? "(없음)"}\n` +
+            failDb(`알 수 없는 db 서브커맨드: ${sub ?? "(없음)"}\n` +
                 `  → 지원: gaon db diff | migrate | reset | seed | status\n` +
-                `  → 옵션: --json · --db <키>(생략 = 전 커넥션 순회) · --config <path> · --yes · --dry-run\n`);
-            process.exitCode = 1;
+                `  → 옵션: --json · --db <키>(생략 = 전 커넥션 순회) · --config <path> · --yes · --dry-run`);
+            return;
+        }
+        // 결정 358·404: 미지 플래그·미지 위치 인자·값 부재는 파싱 경계에서 fail-loud
+        // (오타 dry-run 이 실 적용되는 반전 방지).
+        let dbOpts;
+        try {
+            dbOpts = parseDbArgs(sub, argv);
+        }
+        catch (err) {
+            failDb(err instanceof Error ? err.message : String(err));
             return;
         }
-        const dbOpts = parseDbArgs(sub, argv);
         void runDbCommand(sub, dbOpts)
             .then((code) => {
             process.exitCode = code;
@@ -518,7 +610,13 @@ export function runCli(argv, opts = {}) {
             const appIdx = argv.indexOf("--app");
             const app = appIdx >= 0 ? argv[appIdx + 1] : undefined;
             // 결정 155: --public 은 비-web 앱도 공개 회원가입을 opt-in(공개 비-web 앱 탈출구).
-            const code = runGenerateAuthCommand({ app, json: argv.includes("--json"), public: argv.includes("--public") });
+            // 결정 338: --jwt 는 API 앱 토큰 변형(--app 필수 · --public 배타).
+            const code = runGenerateAuthCommand({
+                app,
+                json: argv.includes("--json"),
+                public: argv.includes("--public"),
+                jwt: argv.includes("--jwt"),
+            });
             process.exitCode = code;
             return;
         }
@@ -630,14 +728,27 @@ export function runCli(argv, opts = {}) {
     // `gaon test [--scope unit|integration|all] [-- vitest 인자]` — 테스트 러너(M9-G).
     if (argv[0] === "test") {
         const rest = argv.slice(1);
-        const scopeIdx = rest.indexOf("--scope");
-        const scopeRaw = scopeIdx >= 0 ? rest[scopeIdx + 1] : undefined;
-        const scope = scopeRaw === "unit" || scopeRaw === "integration" || scopeRaw === "all"
-            ? scopeRaw
-            : undefined;
+        // 결정 411: `--` 뒤는 **전부 vitest 몫**이다. 종전엔 gaon 이 위치와 무관하게
+        // --json·--scope 를 가로채 `gaon test -- --json`(vitest 자체 JSON 리포터)이
+        // 불가능했다 — 탈출구를 연다(help 에 적힌 계약과 코드를 일치시킨다).
+        const sepIdx = rest.indexOf("--");
+        const own = sepIdx >= 0 ? rest.slice(0, sepIdx) : rest;
+        const forwarded = sepIdx >= 0 ? rest.slice(sepIdx + 1) : [];
+        const scopeIdx = own.indexOf("--scope");
+        const scopeRaw = scopeIdx >= 0 ? own[scopeIdx + 1] : undefined;
+        // 결정 411: scope 오타를 조용히 전체 실행으로 폴백하지 않는다(--pm 오타를 막은
+        // 결정 167 과 대칭) — 통합만 돌리려던 CI 가 전체를 돌리며 실 인프라까지 띄운다.
+        if (scopeIdx >= 0 && scopeRaw !== "unit" && scopeRaw !== "integration" && scopeRaw !== "all") {
+            process.stderr.write(`  ✗ gaon test: --scope 값이 ${scopeRaw === undefined ? "없습니다" : `잘못됐습니다('${scopeRaw}')`}.\n` +
+                `    → 지원 값: unit · integration · all\n` +
+                `    → 예: gaon test --scope integration\n`);
+            process.exitCode = 2;
+            return;
+        }
+        const scope = scopeRaw !== undefined ? scopeRaw : undefined;
         const passthrough = [];
-        for (let i = 0; i < rest.length; i++) {
-            const a = rest[i];
+        for (let i = 0; i < own.length; i++) {
+            const a = own[i];
             if (a === "--scope") {
                 i++;
                 continue;
@@ -647,7 +758,8 @@ export function runCli(argv, opts = {}) {
             if (a !== undefined)
                 passthrough.push(a);
         }
-        void runTestCommand(passthrough, { json: argv.includes("--json"), scope })
+        passthrough.push(...forwarded);
+        void runTestCommand(passthrough, { json: own.includes("--json"), scope })
             .then((code) => {
             process.exitCode = code;
         })

package/dist/mcp/tools.d.ts

@@ -93,7 +93,7 @@ export declare function readAgentDocTool(args: ToolArgs, cwd: string): Promise<T
  * AI 에이전트가 자기 산출물을 스스로 확증하는 표준 경로.
  *
  * 인자:
- *   { only?: 'typecheck'|'vue-tsc'|'build'|'doctor', includeDoctor?: boolean }
+ *   { only?: 'typecheck'|'vue-tsc'|'build'|'doctor', noDoctor?: boolean }
  */
 export declare function runCheckTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
 /**

package/dist/mcp/tools.js

@@ -434,17 +434,20 @@ function parseJsonTail(output) {
  * AI 에이전트가 자기 산출물을 스스로 확증하는 표준 경로.
  *
  * 인자:
- *   { only?: 'typecheck'|'vue-tsc'|'build'|'doctor', includeDoctor?: boolean }
+ *   { only?: 'typecheck'|'vue-tsc'|'build'|'doctor', noDoctor?: boolean }
  */
 export async function runCheckTool(args, cwd) {
     const only = stringOpt(args, 'only');
-    const includeDoctor = boolOpt(args, 'includeDoctor');
+    // 결정 362: doctor 는 check 에 **기본 포함**(결정 157). 구 파라미터 includeDoctor 는
+    // no-op CLI 플래그(--include-doctor)로 흘러 "false 여도 doctor 가 도는" 유령이었다 —
+    // 실 토글은 noDoctor(--no-doctor)다. includeDoctor 는 하위 호환으로 받되 무시한다.
+    const noDoctor = boolOpt(args, 'noDoctor');
     const known = ['typecheck', 'vue-tsc', 'build', 'doctor'];
     if (only && !known.includes(only)) {
         return errorResult(`only 는 ${known.map((k) => `'${k}'`).join(' | ')} 중 하나여야 합니다. 입력값: '${only}'\n` +
             `→ 인자를 고치거나 생략해 전체 검사를 실행하세요.`);
     }
-    const cliArgs = ['check', '--json', ...(only ? ['--only', only] : []), ...(includeDoctor ? ['--include-doctor'] : [])];
+    const cliArgs = ['check', '--json', ...(only ? ['--only', only] : []), ...(noDoctor ? ['--no-doctor'] : [])];
     const r = await spawnGaon(cwd, cliArgs);
     if ('error' in r)
         return errorResult(r.error);
@@ -454,7 +457,7 @@ export async function runCheckTool(args, cwd) {
             ok: r.exitCode === 0,
             exitCode: r.exitCode,
             only: only ?? null,
-            includeDoctor,
+            noDoctor: noDoctor ?? false,
             report: parseJsonTail(r.output) ?? null,
             output: r.output,
         },
@@ -590,7 +593,7 @@ export const TOOLS = [
         name: 'run_check',
         description: '`gaon check` 를 실 실행한다 — 검사 전에 .gaon 타입 브리지를 재생성(규칙 3)한 뒤 ' +
             'typecheck·vue-tsc·build 를 순서대로 돌린다. 산출물을 고친 뒤 스스로 확증하는 표준 경로 ' +
-            '(CLAUDE.md §3 검증 루프). only 로 한 단계만, includeDoctor 로 doctor 까지 포함.',
+            '(CLAUDE.md §3 검증 루프). doctor 는 기본 포함(결정 157) — only 로 한 단계만, noDoctor 로 doctor 제외.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -599,7 +602,11 @@ export const TOOLS = [
                     enum: ['typecheck', 'vue-tsc', 'build', 'doctor'],
                     description: '지정 시 그 검사 하나만 실행. 생략 시 전체.',
                 },
-                includeDoctor: { type: 'boolean', description: 'true 면 doctor 도 함께 실행. 기본 false.' },
+                noDoctor: { type: 'boolean', description: 'true 면 doctor 를 제외(기본 false — doctor 는 기본 포함 · 결정 157).' },
+                // 결정 411: 폐기된 includeDoctor 를 스키마에 되살리지 **않는다**. 자리를 남기면
+                // strict 클라이언트의 구 호출이 "성공했는데 조용히 무시" 로 끝나 결정 362 가
+                // 없애려던 유령 파라미터 오도가 되살아난다 — 스키마 부재로 인한 검증 거부가
+                // 오히려 fail-loud(어느 파라미터를 쓰라는 신호)라 결정 362 계약을 유지한다.
             },
             additionalProperties: false,
         },

package/dist/messages-gen.d.ts

@@ -3,4 +3,4 @@
  * 있으면 생성하지 않는다(GaonMessages 를 비운 채로 둬 t() 키가 string 폴백 — i18n 을
  * 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
  */
-export declare function generateMessagesDts(localesDir: string, out: string): boolean;
+export declare function generateMessagesDts(localesDir: string, out: string, baseLng?: string): boolean;

package/dist/messages-gen.js

@@ -4,7 +4,7 @@
 // 카탈로그의 키를 유니온 타입으로 물성화해, t('key') 의 존재하지 않는 키를 컴파일
 // 타임에 잡는다(현재는 GaonMessages 가 비어 있어 키가 string 으로 열림). 생성 파일은
 // 타입만 담는다(규칙 3). @gaonjs/i18n 의 공개 API(loadLocales·renderMessagesDts)만 쓴다.
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { loadLocales, renderMessagesDts } from '@gaonjs/i18n';
 /**
@@ -12,13 +12,24 @@ import { loadLocales, renderMessagesDts } from '@gaonjs/i18n';
  * 있으면 생성하지 않는다(GaonMessages 를 비운 채로 둬 t() 키가 string 폴백 — i18n 을
  * 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
  */
-export function generateMessagesDts(localesDir, out) {
-    if (!existsSync(localesDir))
+export function generateMessagesDts(localesDir, out, baseLng) {
+    // 결정 414: 카탈로그가 사라졌으면 **옛 생성물을 지운다** — 남겨두면 없어진 키의
+    // 유니온이 그대로 살아 t('없어진키') 가 계속 컴파일된다(제거를 못 잡는 사각).
+    if (!existsSync(localesDir)) {
+        if (existsSync(out))
+            rmSync(out, { force: true });
         return false;
+    }
     const resources = loadLocales(localesDir);
-    if (Object.keys(resources).length === 0)
+    if (Object.keys(resources).length === 0) {
+        if (existsSync(out))
+            rmSync(out, { force: true });
         return false;
+    }
     mkdirSync(dirname(out), { recursive: true });
-    writeFileSync(out, renderMessagesDts(resources), 'utf8');
+    // 결정 352: 기준 로케일 = config i18n.fallbackLng(호출자가 정적 분석으로 전달).
+    // 이전엔 항상 알파벳순 첫 로케일이라 컴파일 보증이 fallback 체인과 다른 로케일에
+    // 정박했다(en/ko + fallbackLng:'ko' 프로젝트에서 기준이 en).
+    writeFileSync(out, renderMessagesDts(resources, baseLng), 'utf8');
     return true;
 }

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

@@ -8,15 +8,16 @@ import CardContent from '@shared/components/ui/CardContent.vue'
 import CardFooter from '@shared/components/ui/CardFooter.vue'
 import Button from '@shared/components/ui/Button.vue'
 
-// 사용자·csrf 는 자동 주입 공유 prop 이다(결정 116) — 컨트롤러가 넘기지 않고
+// 사용자는 자동 주입 공유 prop 이다(결정 116) — 컨트롤러가 넘기지 않고
 // useShared() 로 읽는다. currentUser 는 직렬화됨(passwordDigest 없음 · §4.2).
 // 이 페이지는 requireAuth 로 보호되므로 런타임엔 항상 로그인 상태(타입은 nullable).
 const shared = useShared()
 
 // 로그아웃 = DELETE {{URL_PREFIX}}/session (r.resource('session') 의 destroy).
 // HTML <form> 은 DELETE 를 못 보내므로 Inertia 라우터로 실제 메서드를 보낸다(결정 64).
+// CSRF 토큰은 프레임웍이 자동 부착한다(결정 342) — 헤더를 손으로 싣지 않는다.
 function logout(): void {
-  router.delete('{{URL_PREFIX}}/session', { headers: { 'x-csrf-token': shared.csrf } })
+  router.delete('{{URL_PREFIX}}/session')
 }
 </script>
 

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

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { pageProps, useForm, useShared, Link } from 'gaonjs/vue'
+import { pageProps, useForm, Link } from 'gaonjs/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'
@@ -17,12 +17,10 @@ import AlertDescription from '@shared/components/ui/AlertDescription.vue'
 // 실패로 서버가 같은 페이지를 다시 render 하면 props.error 가 즉시 갱신된다.
 const props = pageProps<'{{APP_NAME}}:session#new'>()
 
-// csrf 는 자동 주입 공유 prop 이다(결정 116) — useShared() 로 읽는다.
-const shared = useShared()
-
 // 세션 앱 폼 = Inertia SPA 제출(결정 64) — fetch() 로 만들지 않는다.
 // 서버는 redirect(Inertia 응답)로 답하고, 실패 시 같은 페이지를 다시 render 한다.
-const form = useForm({ email: '', password: '', _csrf: shared.csrf })
+// CSRF 토큰은 프레임웍이 자동 부착한다(결정 342) — 손으로 싣지 않는다.
+const form = useForm({ email: '', password: '' })
 </script>
 
 <template>

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

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { pageProps, useForm, useShared, Link } from 'gaonjs/vue'
+import { pageProps, useForm, Link } from 'gaonjs/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'
@@ -15,11 +15,9 @@ import AlertDescription from '@shared/components/ui/AlertDescription.vue'
 // pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
 const props = pageProps<'{{APP_NAME}}:registration#new'>()
 
-// csrf 는 자동 주입 공유 prop 이다(결정 116) — useShared() 로 읽는다.
-const shared = useShared()
-
 // 세션 앱 폼 = Inertia SPA 제출(결정 64) — fetch() 로 만들지 않는다.
-const form = useForm({ name: '', email: '', password: '', _csrf: shared.csrf })
+// CSRF 토큰은 프레임웍이 자동 부착한다(결정 342) — 손으로 싣지 않는다.
+const form = useForm({ name: '', email: '', password: '' })
 </script>
 
 <template>

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

@@ -0,0 +1,18 @@
+// API 앱 설정 — gaon g auth --jwt 스캐폴드. JWT(토큰) 인증을 표준 부팅(gaon dev / gaon serve)에 배선한다.
+// JWT 는 API 앱 전용이다(§7) — 세션·CSRF 없이 Authorization: Bearer 로 인증한다.
+import { defineAppConfig } from 'gaonjs/config'
+import { loadUser } from './auth.js'
+
+export default defineAppConfig({
+  // JWT secret 은 32자 이상 — .env 의 {{JWT_SECRET_ENV}} 로 주입한다(앱별 분리 · 결정 337).
+  // 운영(NODE_ENV=production)에서 아래 dev 폴백이 남아 있으면 부팅이 확정 종료된다(fail-loud).
+  auth: {
+    strategy: 'jwt',
+    secret: process.env.{{JWT_SECRET_ENV}} ?? 'dev-only-jwt-secret-{{APP_NAME}}-change-me-now!!',
+    loadUser,
+    // 액세스는 짧게, 리프레시는 길게(기본 15m / 7d). 토큰은 stateless 라 서버측
+    // 폐기 수단이 없다 — 민감한 앱은 refreshTtl 을 짧게 잡는다(agents/web.md §6).
+    accessTtl: '15m',
+    refreshTtl: '7d',
+  },
+})

package/dist/templates/auth/jwt.auth.wiring.ts.tpl

@@ -0,0 +1,16 @@
+// 인증 배선 — gaon g auth --jwt 스캐폴드 (API 앱 · 토큰).
+import type { JwtAuthOptions } from 'gaonjs/web'
+import { User } from '../../domain/models/User.js'
+
+// 액세스 토큰의 sub(사용자 id)로 사용자를 로드한다(§7 · JWT 는 API 앱 전용).
+export const loadUser: JwtAuthOptions['loadUser'] = async (id) =>
+  await User.where('id', '=', BigInt(String(id))).first()
+
+// this.currentUser 에 User 필드 타입을 얹는다(GaonRouteMap 과 동일 관례).
+declare module 'gaonjs/web' {
+  interface GaonCurrentUser {
+    id: bigint
+    name: string
+    email: string
+  }
+}

package/dist/templates/auth/jwt.routes.ts.tpl

@@ -0,0 +1,7 @@
+import { routes } from 'gaonjs/web'
+
+export default routes((r) => {
+  r.post('/session', 'session#create') // 로그인 → 토큰 발급 (gaon g auth --jwt)
+  r.post('/session/refresh', 'session#refresh') // 액세스 토큰 재발급 (gaon g auth --jwt)
+  r.get('/session', 'session#show') // 현재 사용자 · Bearer (gaon g auth --jwt)
+})

package/dist/templates/auth/jwt.session.controller.ts.tpl

@@ -0,0 +1,36 @@
+// 토큰 컨트롤러(발급/재발급/내 정보) — gaon g auth --jwt 스캐폴드 (API 앱 · JSON 전용).
+// API 앱은 프론트엔드가 없다 — 모든 응답이 JSON 이고 페이지·useForm 을 쓰지 않는다.
+import { controller, verifyPassword } from 'gaonjs/web'
+import { User } from '../../../domain/models/User.js'
+
+export default controller({
+  // POST {{URL_PREFIX}}/session — 로그인: 자격 검증 후 액세스+리프레시 토큰 발급.
+  //   curl -X POST -H 'Content-Type: application/json' \
+  //     -d '{"email":"a@x.com","password":"..."}' http://127.0.0.1:3000{{URL_PREFIX}}/session
+  async create() {
+    const { email, password } = this.params({ _row: {} as { email: string; password: string } })
+    const user = await User.where('email', '=', email).first()
+    if (!user || !(await verifyPassword(password, user.passwordDigest))) {
+      return this.json({ error: 'invalid_credentials', message: '이메일 또는 비밀번호가 올바르지 않습니다.' }, 401)
+    }
+    // this.jwt 는 JWT 앱에서만 존재한다(app.config 의 auth.strategy:'jwt' 배선).
+    const tokens = await this.jwt!.issue(user)
+    return this.json(tokens) // { accessToken, refreshToken }
+  },
+  // POST {{URL_PREFIX}}/session/refresh — 리프레시 토큰으로 액세스 토큰 재발급.
+  // 주의: 토큰은 stateless — 서버측 폐기(로그아웃·강제 무효화) 수단이 없다(결정 337).
+  // 유출된 리프레시 토큰은 만료까지 유효하므로 민감한 앱은 refreshTtl 을 짧게 잡는다.
+  async refresh() {
+    const { refreshToken } = this.params({ _row: {} as { refreshToken: string } })
+    const next = await this.jwt!.refresh(refreshToken)
+    if (!next) {
+      return this.json({ error: 'invalid_refresh_token', message: '리프레시 토큰이 유효하지 않거나 만료됐습니다.' }, 401)
+    }
+    return this.json(next) // { accessToken }
+  },
+  // GET {{URL_PREFIX}}/session — 현재 사용자 확인 (Authorization: Bearer <accessToken>).
+  async show() {
+    const user = this.requireAuth() // 토큰이 없거나 무효면 401
+    return this.json({ user }) // hidden 컬럼(passwordDigest)은 응답 경계에서 제외된다(§4.2)
+  },
+})

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

@@ -111,7 +111,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 27종
+### 2.2 `gaon doctor` 검사 28종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -140,6 +140,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 25. `schema-relations` — 커넥션을 가로지르는 belongsTo·역방향 관계(SQL 조인이 커넥션을 못 넘음)와 존재하지 않는 관계 대상 = **에러**(§4.5). **파티션 키 컬럼이 실제 컬럼인지도 검사**(결정 277 · `checkPartitions` — 오타·유령 컬럼). data 패키지 검사(`checkCrossConnectionRelations`·`checkRelationTargets`·`checkPartitions`)를 CLI 러너가 배선 — 배포 후 raw postgres 에러 대신 doctor 가 잡는다 (결정 134·277 · `agents/data.md`)
 26. `no-import-meta-env` — `.vue`(SFC) `<script>` 에서 `import.meta.env` 직접 사용 = **에러**. SFC 는 nodenext 아래 CommonJS 출력으로 분류돼 vue-tsc 가 TS1470 로 거부한다(`gaon check` red). 클라 공개 환경변수는 `import { env } from 'gaonjs/vue'` 로 읽으라(VITE_* 접두 제거·타입드 · `.gaon/env.d.ts` 는 `.env` 스캔 생성) — 템플릿 프로즈·주석의 언급은 오탐 제외 (결정 198 · `agents/frontend.md` §9)
 27. `locale-parity` — `locales/` 의 로케일 간 키 부분 누락 = **경고**. 어떤 키가 특정 로케일에만 빠지면 `messages.d.ts`(기준 로케일 기준)는 컴파일을 통과하고, 런타임에 그 로케일 사용자는 fallback(대개 다른 언어) 번역을 조용히 본다. 검사가 로케일 간 키 diff 를 계산해 빠진 파일·키를 짚는다(`--json` 은 `detail.missing` 으로 구조화). 로케일이 0·1개면 무소음 (결정 216 · `agents/i18n.md`)
+28. `render-return` — 액션이 `this.render`/`this.redirect`/`this.json` 을 호출만 하고 `return` 하지 않음 = 응답이 버려져 조용히 204(백지) — `return this.render(...)` 로 고치라 (결정 340 · 경고)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -200,7 +201,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build + doctor (기본 포함 · --no-doctor 로 뺌 · 결정 157)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 27종 (§2.2)
+gaon doctor       # 정적 검사 28종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)

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

@@ -86,7 +86,7 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 
 ```bash
 gaon check                        # .gaon 재생성 → 타입검사+build+doctor (CI 한 번에 · --no-doctor 로 doctor 뺌)
-gaon doctor                       # 정적 검사 27종 (상세 AGENTS §2.2)
+gaon doctor                       # 정적 검사 28종 (상세 AGENTS §2.2)
 npm test                          # Vitest · DB 테스트는 실 Docker 필수 (§9)
 ```
 

package/dist/templates/project/Dockerfile.tpl

@@ -18,12 +18,22 @@ RUN pnpm install --frozen-lockfile
 FROM base AS build
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
+# 결정 408: 브라우저에 실리는 공개 변수(VITE_*)는 **빌드 시점에 번들로 각인**된다 —
+# 런타임 env(compose.prod.yaml)로는 못 바꾼다. 값이 필요하면 빌드 인자로 넘긴다:
+#   docker build --build-arg VITE_API_BASE=https://api.example.com .
+# 넘기지 않으면 아래 .env.example 의 placeholder 가 그대로 각인되므로, 공개 변수를
+# 쓰는 앱은 반드시 build-arg 로 주거나 .env.example 에 **공개 가능한 실값**을 둔다.
+# (비밀은 VITE_ 로 만들지 말 것 — 번들은 누구나 읽는다.)
+ARG VITE_VARS=""
 # gaon build 는 .gaon/env.d.ts 생성에 .env 가 필수(결정 198)인데 .env 는 이미지에
 # 넣지 않는다(.dockerignore) — .env.example 을 임시 복제해 빌드하고 즉시 지운다.
 # 지우는 이유: example 의 placeholder(SESSION_SECRET 등)가 런타임에 남으면 compose
 # 가 env 를 안 넘겼을 때 fail-loud 검증을 조용히 통과시킨다(결정 313). 런타임 env
 # 는 compose.prod.yaml 의 environment 가 단일 소스다.
-RUN cp .env.example .env && pnpm build && rm -f .env
+RUN cp .env.example .env \
+  && for kv in $VITE_VARS; do printf '%s\n' "$kv" >> .env; done \
+  && pnpm build \
+  && rm -f .env
 
 # 3) 런타임 — 소스 + 번들 + 의존을 그대로 실행.
 FROM base AS runtime