@gaonjs/cli 0.38.0 → 0.40.0

package/dist/doctor/fixers/index.js

@@ -55,9 +55,9 @@ export const FIXER_CAPABILITIES = [
         note: '수동 · `gaon db diff` → 리뷰 → `gaon db migrate` (SQL 은 사람이 확인).',
     },
     {
-        rule: 'shared-composable-purity',
+        rule: 'shared-purity',
         hasFixer: false,
-        note: '수동 · 컴포저블에 든 앱 종속 로직을 앱 쪽으로 옮겨야 합니다(E-5 §2.2).',
+        note: '수동 · shared(.ts·.vue)에 든 앱 종속 로직(api/pageProps·domain 값)을 앱 쪽으로 옮기거나 props/인자로 받으세요(E-5 §2.2 · 결정 217).',
     },
     {
         rule: 'no-auto-import',

package/dist/doctor/locale-parity.d.ts

@@ -0,0 +1,6 @@
+import type { RuleReport } from './types.js';
+/**
+ * locales/ 의 로케일 간 키 diff 를 계산해 부분 누락을 경고로 낸다. 로케일이 0·1개면
+ * 비교 대상이 없어 건너뛴다(i18n 미사용·단일 로케일 프로젝트는 무소음).
+ */
+export declare function checkLocaleParity(cwd: string): Promise<RuleReport>;

package/dist/doctor/locale-parity.js

@@ -0,0 +1,68 @@
+// @gaonjs/cli · doctor · 로케일 키 부분 누락 검출 (결정 216 · 13차 W4 · 경고)
+//
+// .gaon/messages.d.ts 의 키 유니온은 **기준 로케일 하나**에서 뽑는다(generator.ts ·
+// renderMessagesDts). 그래서 어떤 키가 특정 로케일에만 빠져 있으면 타입 검사는 통과하고,
+// 런타임에 그 로케일 사용자는 fallback 번역(대개 다른 언어)을 조용히 보게 된다 — 타입도
+// 못 잡고 화면에도 티가 안 나는 사각(결정 216). 이 검사가 locales/ 를 훑어 로케일 간 키
+// 집합을 비교해, 다른 로케일엔 있는데 이 로케일엔 없는 키를 파일·키로 경고한다.
+//
+// 경고(error 아님): 부분 누락은 fallback 으로 화면이 깨지진 않는 소프트 결함이라
+// 빌드를 세우지 않는다. --json 은 detail.locale·detail.missing 으로 구조화한다.
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { loadLocales, flattenKeys } from '@gaonjs/i18n';
+// 경고 한 줄이 폭주하지 않게 나열 상한 — 넘으면 "…외 N개" 로 접는다(detail 에는 전량).
+const MAX_KEYS_SHOWN = 20;
+// i18next 복수형 접미사(결정 181 · generator.ts 와 동일 규약). 로케일마다 필요한 접미사만
+// 두는 것이 정상이라(en `_one`·`_other` / ko `_other`), 접미사 변형 차이는 부분 누락이
+// 아니다 — base 키로 정규화해 비교해야 정당한 복수형 카탈로그에 오탐(경고)을 안 낸다.
+const PLURAL_SUFFIX = /_(zero|one|two|few|many|other)$/;
+/** 키를 복수형 base 로 정규화한다(접미사 제거 · 비복수 키는 그대로). */
+function pluralBase(key) {
+    return key.replace(PLURAL_SUFFIX, '');
+}
+/**
+ * locales/ 의 로케일 간 키 diff 를 계산해 부분 누락을 경고로 낸다. 로케일이 0·1개면
+ * 비교 대상이 없어 건너뛴다(i18n 미사용·단일 로케일 프로젝트는 무소음).
+ */
+export async function checkLocaleParity(cwd) {
+    const localesDir = join(cwd, 'locales');
+    if (!existsSync(localesDir))
+        return { rule: 'locale-parity', issues: [] };
+    const resources = loadLocales(localesDir);
+    const langs = Object.keys(resources).sort();
+    if (langs.length < 2)
+        return { rule: 'locale-parity', issues: [] };
+    // 로케일별 키 집합과 전체 union(어느 로케일에든 등장한 키의 합집합)을 만든다.
+    // 복수형 접미사는 base 로 정규화해 로케일별 정당한 복수형 차이를 오탐으로 잡지 않는다.
+    const keysByLang = new Map();
+    const union = new Set();
+    for (const lng of langs) {
+        const keys = new Set(flattenKeys(resources[lng].translation).map(pluralBase));
+        keysByLang.set(lng, keys);
+        for (const k of keys)
+            union.add(k);
+    }
+    const issues = [];
+    for (const lng of langs) {
+        const have = keysByLang.get(lng);
+        const missing = [...union].filter((k) => !have.has(k)).sort();
+        if (missing.length === 0)
+            continue;
+        const rel = relative(cwd, join(localesDir, `${lng}.json`));
+        const shown = missing.slice(0, MAX_KEYS_SHOWN);
+        const more = missing.length - shown.length;
+        const list = shown.map((k) => `'${k}'`).join(', ') + (more > 0 ? ` …외 ${more}개` : '');
+        issues.push({
+            rule: 'locale-parity',
+            level: 'warning',
+            file: rel,
+            message: `로케일 '${lng}' 에 다른 로케일엔 있는 키 ${missing.length}개가 빠졌습니다: ${rel}\n` +
+                `  누락 키: ${list}\n` +
+                `→ ${rel} 에 이 키들을 채우세요 — 없으면 '${lng}' 사용자에게 fallback(대개 다른 언어)\n` +
+                `  번역이 조용히 노출됩니다. messages.d.ts 는 기준 로케일 기준이라 컴파일로 못 잡습니다(결정 216).`,
+            detail: { locale: lng, missing },
+        });
+    }
+    return { rule: 'locale-parity', issues };
+}

package/dist/doctor/shared-purity.d.ts

@@ -0,0 +1,9 @@
+import type { DoctorCheck, RuleReport } from './types.js';
+/**
+ * 단일 shared 소스(.ts 원문 또는 .vue script 블록)를 검사해 순수성 위반
+ * 목록을 낸다(단위 테스트 진입점). file 확장자가 .vue 면 <script> 만 뽑아
+ * 파싱한다 — line 번호는 script 블록 기준(안내 정확도보다 위반 유무가 우선).
+ */
+export declare function inspectSharedSource(file: string, source: string, cwd: string): DoctorCheck[];
+/** shared/ 전체(.ts · .vue)를 훑어 순수성 위반을 모두 낸다. */
+export declare function checkSharedPurity(cwd: string): Promise<RuleReport>;

package/dist/doctor/shared-purity.js

@@ -0,0 +1,188 @@
+// @gaonjs/cli · doctor · shared 순수성 검사 (M9-E 확장 · 결정 217 · errata E-5 §2.2)
+//
+// shared/ 는 앱을 몰라야 한다(§5 · CLAUDE.md rule 5). 라우트를 몰라야 하고
+// (api·pageProps 값 import 금지) · domain 은 타입으로만 참조해야 한다. 필요한
+// 데이터·호출 함수는 props/인자로 받는다. 이 규칙은 shared 컴포저블뿐 아니라
+// shared 컴포넌트(.vue)에도 똑같이 적용된다 — 관례가 컴포저블·컴포넌트에 대칭
+// 이므로(결정 25) 검사도 한 규칙으로 통일한다(결정 217).
+//
+// 이력: M9-E 때는 `shared-composable-purity` 라는 이름으로 shared/composables/
+// 의 .ts 만 훑었다. 그러나 shared/components/*.vue 안에서 domain 모델을 값으로
+// import 해도 27 검사가 전부 통과하는 공백이 12차 실사용(support-desk)에서 드러났다
+// (§4.5 잔재). 결정 217: 규칙명을 `shared-purity` 로 개정하고 검사 범위를
+// shared/ 전체(.ts · .vue)로 넓혀 The One Way 로 통일한다.
+//
+// 검사 대상(파일 종류 무관):
+//  1) 프레임웍 모듈(gaonjs · gaonjs/vue · @gaonjs/vue · @gaonjs/web) 에서
+//     'api' · 'pageProps' 를 value import 하면 error.
+//     - type-only 는 무해(구조 참조뿐 · 라우트 지식 필요 없음).
+//  2) domain 을 value import 하면 error.
+//     - type-only 는 허용(모델 Row 타입 등 · 순수 타입 참조).
+//
+// 방법: shared/ 아래 .ts 는 소스 그대로, .vue 는 <script> 블록만 뽑아 TS AST 로
+// 파싱해 import 선언만 훑는다. 상대 import 는 실 파일까지 해석하지 않고 경로
+// 접두사(domain/) 로 판정 — 이 검사는 순수성 게이트라 정확도보다 재현성이 우선
+// (false positive 는 오히려 안전).
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, resolve, dirname } from 'node:path';
+import ts from 'typescript';
+/** 라우트 지식을 담은 심볼 — shared 는 참조할 수 없다. */
+const FORBIDDEN_FRAMEWORK_NAMES = new Set(['api', 'pageProps']);
+/**
+ * 프레임웍 모듈 패턴. 문서 표기(gaon/vue)는 실 패키지 이름의 짧은
+ * 별칭이며, 실 배포본은 gaonjs 파사드 subpath 와 @gaonjs 스코프를 쓴다.
+ * 하나만 잡으면 우회가 쉬우므로 알려진 표기 3종을 모두 매치한다.
+ */
+const FRAMEWORK_MODULE_PATTERNS = [
+    /^gaonjs$/,
+    /^gaonjs\/vue$/,
+    /^@gaonjs\/vue$/,
+    /^@gaonjs\/web$/,
+];
+/** import 선언에서 이름과 type-only 플래그를 추출한다. */
+function collectImportedNames(node) {
+    const out = [];
+    const clause = node.importClause;
+    if (!clause)
+        return out;
+    const clauseTypeOnly = clause.isTypeOnly;
+    if (clause.name)
+        out.push({ name: clause.name.text, typeOnly: clauseTypeOnly });
+    const bindings = clause.namedBindings;
+    if (bindings) {
+        if (ts.isNamespaceImport(bindings)) {
+            out.push({ name: bindings.name.text, typeOnly: clauseTypeOnly });
+        }
+        else if (ts.isNamedImports(bindings)) {
+            for (const el of bindings.elements) {
+                out.push({ name: el.name.text, typeOnly: clauseTypeOnly || el.isTypeOnly });
+            }
+        }
+    }
+    return out;
+}
+function isRelativeSpecifier(s) {
+    return s.startsWith('./') || s.startsWith('../');
+}
+function matchesFrameworkModule(spec) {
+    return FRAMEWORK_MODULE_PATTERNS.some((re) => re.test(spec));
+}
+/**
+ * .vue SFC 에서 <script>·<script setup> 블록 안 텍스트만 뽑아 하나로 잇는다.
+ * doctor 는 import 선언만 보므로 script 밖(<template>·<style>)은 무시한다.
+ * 두 블록(일반+setup)이 다 있을 수 있어 전부 이어 붙인다.
+ */
+function extractVueScript(source) {
+    const blocks = [];
+    const re = /<script\b[^>]*>([\s\S]*?)<\/script>/g;
+    let m;
+    while ((m = re.exec(source)) !== null)
+        blocks.push(m[1] ?? '');
+    return blocks.join('\n');
+}
+/**
+ * 단일 shared 소스(.ts 원문 또는 .vue script 블록)를 검사해 순수성 위반
+ * 목록을 낸다(단위 테스트 진입점). file 확장자가 .vue 면 <script> 만 뽑아
+ * 파싱한다 — line 번호는 script 블록 기준(안내 정확도보다 위반 유무가 우선).
+ */
+export function inspectSharedSource(file, source, cwd) {
+    const issues = [];
+    const rel = relative(cwd, file);
+    const code = file.endsWith('.vue') ? extractVueScript(source) : source;
+    const sf = ts.createSourceFile(file, code, ts.ScriptTarget.ES2022, true);
+    const baseDir = dirname(file);
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+            const spec = node.moduleSpecifier.text;
+            const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+            const names = collectImportedNames(node);
+            // 1) 프레임웍의 api/pageProps 를 value import → error
+            if (matchesFrameworkModule(spec)) {
+                for (const n of names) {
+                    if (n.typeOnly)
+                        continue; // type-only 는 라우트 실행 지식이 아님
+                    if (!FORBIDDEN_FRAMEWORK_NAMES.has(n.name))
+                        continue;
+                    issues.push({
+                        rule: 'shared-purity',
+                        level: 'error',
+                        file: rel,
+                        line: line + 1,
+                        message: `${rel} (line ${line + 1})\n` +
+                            `  '${spec}' 의 '${n.name}' import 발견 · shared 는 라우트를 몰라야 함\n` +
+                            `→ 옵션: apps/<앱>/ 로 옮기거나 · ${n.name} 결과를 props/인자로 받도록 바꾸라`,
+                        detail: {
+                            kind: 'framework-api',
+                            module: spec,
+                            name: n.name,
+                        },
+                    });
+                }
+            }
+            // 2) domain value import → error (type-only 는 허용)
+            if (isRelativeSpecifier(spec)) {
+                const abs = resolve(baseDir, spec);
+                const parts = relative(cwd, abs).split(/[\\/]/).filter(Boolean);
+                if (parts[0] === 'domain') {
+                    const valueNames = names.filter((n) => !n.typeOnly);
+                    if (valueNames.length > 0) {
+                        issues.push({
+                            rule: 'shared-purity',
+                            level: 'error',
+                            file: rel,
+                            line: line + 1,
+                            message: `${rel} (line ${line + 1})\n` +
+                                `  domain 값 import 발견 · shared 는 domain 을 타입으로만 참조해야 함\n` +
+                                `→ 'import type { ... } from ...' 형태로 바꾸거나 · 필요한 값은 props/인자로 받도록 바꾸라`,
+                            detail: {
+                                kind: 'domain-value',
+                                module: spec,
+                                names: valueNames.map((n) => n.name),
+                            },
+                        });
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return issues;
+}
+/** shared/ 전체(.ts · .vue)를 훑어 순수성 위반을 모두 낸다. */
+export async function checkSharedPurity(cwd) {
+    const sharedDir = join(cwd, 'shared');
+    const files = [];
+    await collectSharedFiles(sharedDir, files);
+    const issues = [];
+    for (const file of files) {
+        const src = await readFile(file, 'utf8');
+        issues.push(...inspectSharedSource(file, src, cwd));
+    }
+    return { rule: 'shared-purity', issues };
+}
+async function collectSharedFiles(root, out) {
+    let entries;
+    try {
+        entries = (await readdir(root, { withFileTypes: true }));
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        const name = e.name;
+        if (name === 'node_modules' || name === 'dist' || name === '.gaon')
+            continue;
+        const full = join(root, name);
+        if (e.isDirectory())
+            await collectSharedFiles(full, out);
+        else if (e.isFile() && isScannable(name))
+            out.push(full);
+    }
+}
+/** shared 순수성 검사 대상 파일인가 — .ts(선언·테스트 제외) 또는 .vue. */
+function isScannable(name) {
+    if (name.endsWith('.vue'))
+        return true;
+    return name.endsWith('.ts') && !name.endsWith('.d.ts') && !name.endsWith('.test.ts');
+}

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' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-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' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env' | 'locale-parity';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -7,7 +7,7 @@ export { extractRelativeImports, checkDependencyDirection } from './doctor/depen
 export { extractConfigDbKeys, analyzeConfigDb, extractKeyUses, checkConnections, } from './doctor/connections.js';
 export { checkSchemaRelations } from './doctor/schema-relations.js';
 export { scanSchema, checkMigrationDiff } from './doctor/migration-diff.js';
-export { inspectSharedComposable, checkSharedComposablePurity, } from './doctor/shared-composable-purity.js';
+export { inspectSharedSource, checkSharedPurity, } from './doctor/shared-purity.js';
 export { inspectConfigForAutoImport, inspectPackageJson, checkNoAutoImport, } from './doctor/no-auto-import.js';
 export { expectedSchemaStem, extractTableName, checkSchemaFilename, } from './doctor/schema-filename.js';
 export { extractAgentDocRefs, checkAgentsDocIndex } from './doctor/agents-doc-index.js';
@@ -22,13 +22,14 @@ export { usesPagePropsDestructure, checkPagePropsDestructure, } from './doctor/p
 export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActions, checkAsyncOffload, } from './doctor/async-offload.js';
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
+export { checkLocaleParity } from './doctor/locale-parity.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 26개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 27개 모두.
  */
 /**
- * doctor 정적 검사 26종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 27종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */

package/dist/doctor.js

@@ -1,13 +1,13 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 26 검사를 조립한다:
+ * 27 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
  *  4) connections (v0.15 §4.5)
  *  5) migration-diff (최소 감지 · 상세는 M9-D)
- *  6) shared-composable-purity (errata E-5 §2.2 · 결정 25)
+ *  6) shared-purity (errata E-5 §2.2 · 결정 25·217 · shared/ 전체 .ts·.vue)
  *  7) no-auto-import (errata E-5 §2.4 · v0.15 §1.2)
  *  8) schema-filename (§1.1 · 결정 38 · 스키마 파일명 camelCase)
  *  9) agents-doc-index (§0 색인 ↔ agents/ 실 파일 · 결정 40)
@@ -28,6 +28,7 @@
  * 24) seal-security (결정 121 · seal 클라 배선 · 보안 역전)
  * 25) schema-relations (§4.5 · 결정 134 · 커넥션 가로지르는 belongsTo·관계 · 대상 부재 error)
  * 26) no-import-meta-env (결정 198 · F-9 ② · `.vue` 의 import.meta.env = TS1470 → env 접근자 안내 error)
+ * 27) locale-parity (결정 216 · 13차 W4 · 로케일 간 키 부분 누락 = fallback 조용 노출 경고)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -46,7 +47,7 @@ import { checkDependencyDirection } from './doctor/dependency-direction.js';
 import { checkConnections } from './doctor/connections.js';
 import { checkSchemaRelations } from './doctor/schema-relations.js';
 import { checkMigrationDiff } from './doctor/migration-diff.js';
-import { checkSharedComposablePurity } from './doctor/shared-composable-purity.js';
+import { checkSharedPurity } from './doctor/shared-purity.js';
 import { checkNoAutoImport } from './doctor/no-auto-import.js';
 import { checkSchemaFilename } from './doctor/schema-filename.js';
 import { checkAgentsDocIndex } from './doctor/agents-doc-index.js';
@@ -66,6 +67,7 @@ import { checkSealSecurity } from './doctor/seal-security.js';
 import { checkPageLayoutBreakpoint } from './doctor/page-layout-breakpoint.js';
 import { checkLinkButtonNesting } from './doctor/link-button-nesting.js';
 import { checkNoImportMetaEnv } from './doctor/no-import-meta-env.js';
+import { checkLocaleParity } from './doctor/locale-parity.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -76,7 +78,7 @@ export { extractRelativeImports, checkDependencyDirection } from './doctor/depen
 export { extractConfigDbKeys, analyzeConfigDb, extractKeyUses, checkConnections, } from './doctor/connections.js';
 export { checkSchemaRelations } from './doctor/schema-relations.js';
 export { scanSchema, checkMigrationDiff } from './doctor/migration-diff.js';
-export { inspectSharedComposable, checkSharedComposablePurity, } from './doctor/shared-composable-purity.js';
+export { inspectSharedSource, checkSharedPurity, } from './doctor/shared-purity.js';
 export { inspectConfigForAutoImport, inspectPackageJson, checkNoAutoImport, } from './doctor/no-auto-import.js';
 export { expectedSchemaStem, extractTableName, checkSchemaFilename, } from './doctor/schema-filename.js';
 export { extractAgentDocRefs, checkAgentsDocIndex } from './doctor/agents-doc-index.js';
@@ -91,13 +93,14 @@ export { usesPagePropsDestructure, checkPagePropsDestructure, } from './doctor/p
 export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActions, checkAsyncOffload, } from './doctor/async-offload.js';
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
+export { checkLocaleParity } from './doctor/locale-parity.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 26개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 27개 모두.
  */
 /**
- * doctor 정적 검사 26종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 27종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */
@@ -107,7 +110,7 @@ export const ALL_RULES = [
     'dependency-direction',
     'connections',
     'migration-diff',
-    'shared-composable-purity',
+    'shared-purity',
     'no-auto-import',
     'schema-filename',
     'agents-doc-index',
@@ -128,6 +131,7 @@ export const ALL_RULES = [
     'seal-security',
     'schema-relations',
     'no-import-meta-env',
+    'locale-parity',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -135,7 +139,7 @@ const CHECKERS = {
     'dependency-direction': checkDependencyDirection,
     connections: checkConnections,
     'migration-diff': checkMigrationDiff,
-    'shared-composable-purity': checkSharedComposablePurity,
+    'shared-purity': checkSharedPurity,
     'no-auto-import': checkNoAutoImport,
     'schema-filename': checkSchemaFilename,
     'agents-doc-index': checkAgentsDocIndex,
@@ -156,6 +160,7 @@ const CHECKERS = {
     'seal-security': checkSealSecurity,
     'schema-relations': checkSchemaRelations,
     'no-import-meta-env': checkNoImportMetaEnv,
+    'locale-parity': checkLocaleParity,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/generate.js

@@ -33,6 +33,20 @@ const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'templates',
 function urlPrefixFor(app) {
     return app === 'web' ? '' : `/${app}`;
 }
+/**
+ * 결정 219: `~ 패치` 라벨을 파일별 실제 편집 내용으로 정확히 붙인다. patchEnvFiles·
+ * patchAppConfigAddAuth·patchRoutes 가 서로 다른 편집을 하는데 예전엔 전부 "라우트 추가"
+ * 로 라벨해 .env·app.config 편집을 오도했다(scaffold 로그 정확성).
+ */
+function patchLabel(rel) {
+    if (rel === '.env' || rel === '.env.example')
+        return '세션 secret 추가';
+    if (rel.endsWith('/app.config.ts') || rel === 'app.config.ts')
+        return '인증 배선 추가';
+    if (rel.endsWith('/routes.ts') || rel === 'routes.ts')
+        return '라우트 추가';
+    return '수정';
+}
 /**
  * 앱의 세션 secret 환경변수명 — web 은 'SESSION_SECRET'(기존), 그 외는
  * '<APP>_SESSION_SECRET'(결정 141 · 앱별 세션 완전 분리 · session.ts 는 앱마다
@@ -99,6 +113,9 @@ function renderTemplate(name, app, includePublic) {
         .replaceAll('{{APP_NAME}}', app)
         .replaceAll('{{URL_PREFIX}}', urlPrefixFor(app))
         .replaceAll('{{SESSION_SECRET_ENV}}', sessionSecretEnvFor(app))
+        // 결정 218: 시큐어 세션 컨트롤러의 로그인 역할 게이트 기준. 결정 155·145 의 대시보드
+        // 역할 게이트(role === 'admin')와 같은 값으로 고정해 두 층이 어긋나지 않게 한다.
+        .replaceAll('{{REQUIRED_ROLE}}', 'admin')
         .replaceAll('{{SIGNUP_LINK}}', includePublic ? signupLinkMarkup(app) : '');
 }
 /** 인증 스캐폴드가 생성하는 파일 목록(라우트 제외). 템플릿을 읽어 렌더링한다.
@@ -110,7 +127,13 @@ export function authScaffoldFiles(opts = {}) {
         { tpl: 'user.schema.ts.tpl', out: 'domain/schema/users.ts' },
         { tpl: 'user.model.ts.tpl', out: 'domain/models/User.ts' },
         { tpl: 'auth.wiring.ts.tpl', out: `apps/${app}/auth.ts` },
-        { tpl: 'session.controller.ts.tpl', out: `apps/${app}/controllers/session.ts` },
+        // 결정 218: 시큐어 앱은 로그인 시점에 역할을 검증하는 세션 컨트롤러를 깐다 — 고객이
+        // 인증만 통과해 세션을 얻은 뒤 대시보드에서 403 을 만나는 rough UX 를 진입점에서 막는다.
+        // 공개 앱(web 등)은 역할 개념이 없어 표준 세션 컨트롤러(로그인 = 세션 생성)를 쓴다.
+        {
+            tpl: includePublic ? 'session.controller.ts.tpl' : 'session.secure.controller.ts.tpl',
+            out: `apps/${app}/controllers/session.ts`,
+        },
         // 결정 155: 시큐어(비-web · 비-public) 앱은 역할 게이트 대시보드, 공개 앱은 requireAuth 대시보드.
         {
             tpl: includePublic ? 'dashboard.controller.ts.tpl' : 'dashboard.secure.controller.ts.tpl',
@@ -266,14 +289,16 @@ export function writeAuthScaffold(cwd, opts = {}) {
     // 결정 155·142(W3): 앱별 세션 secret 을 .env·.env.example 에 시드한다. web 은 이미
     // 있어 멱등, 비-web 앱은 여기서 키가 심어져 "공개 고정 dev secret 폴백" 표면을 막는다.
     patched.push(...patchEnvFiles(root, app));
-    // 결정 155: 시큐어 앱(공개 가입 미생성)은 역할 게이트 대시보드를 깔았다 — role 컬럼을
-    // 두라고 안내한다(§7.5.3 · authorize 예시가 실제 역할 규칙이 되도록).
+    // 결정 155·218: 시큐어 앱(공개 가입 미생성)은 로그인 시점 역할 게이트 세션 컨트롤러 +
+    // 역할 게이트 대시보드를 깔았다 — 두 층 다 role 컬럼이 있어야 동작하므로 추가를 안내한다
+    // (§7.5.3 · authorize·로그인 게이트 예시가 실제 역할 규칙이 되도록).
     if (!includePublic) {
-        warnings.push(`apps/${app}/ 는 시큐어 스캐폴드입니다(공개 회원가입 미생성 · 결정 155).\n` +
+        warnings.push(`apps/${app}/ 는 시큐어 스캐폴드입니다(공개 회원가입 미생성 · 결정 155·218).\n` +
             `→ 관리자는 직접 만들거나 승격하세요(공개 가입 라우트 없음). 공개 가입이 필요하면 --public 로 다시 생성.\n` +
             `→ 역할 인가를 완성하려면 domain/schema/users.ts 에 role 컬럼을 추가하세요:\n` +
             `   role: t.string().default('user'),\n` +
-            `   그러면 apps/${app}/controllers/dashboard.ts 의 authorize(역할) 게이트가 실제 역할로 동작합니다.`);
+            `   그러면 로그인(controllers/session.ts)이 역할 부족 시 세션을 만들지 않고,\n` +
+            `   apps/${app}/controllers/dashboard.ts 의 authorize(역할) 게이트도 실제 역할로 동작합니다.`);
     }
     return { created: created.sort(), skipped: skipped.sort(), patched: patched.sort(), warnings };
 }
@@ -292,8 +317,10 @@ export function runGenerateAuthCommand(opts = {}) {
     lines.push('');
     for (const f of result.created)
         lines.push(`   + ${f}`);
+    // 결정 219: 패치 대상은 파일마다 편집 내용이 다르다 — routes.ts(라우트) · app.config.ts(인증
+    // 배선) · .env(세션 secret). 전부 "라우트 추가" 로 라벨하면 .env·app.config 편집을 오도한다.
     for (const f of result.patched)
-        lines.push(`   ~ ${f} (라우트 추가)`);
+        lines.push(`   ~ ${f} (${patchLabel(f)})`);
     for (const f of result.skipped)
         lines.push(`   · ${f} (이미 있음 — 건너뜀)`);
     for (const w of result.warnings)

package/dist/index.js

@@ -109,7 +109,7 @@ function renderHelp(version = VERSION) {
         "    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        정적 검사 (25 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계)",
+        "    gaon doctor        정적 검사 (27 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계·import.meta.env·로케일 커버리지)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
@@ -146,7 +146,7 @@ function renderHelp(version = VERSION) {
  * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
  */
 export function parseDoctorChecks(argv) {
-    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 26종)를 단일 출처로 쓴다 — 과거
+    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 27종)를 단일 출처로 쓴다 — 과거
     // 손유지 9종 리스트가 뒤처져 --check=seal-security 같은 16종이 조용히 무시되고
     // 전체 검사로 되돌아가던 표류를 근본 차단한다(결정 168).
     const isKnown = (s) => ALL_RULES.includes(s);
@@ -307,7 +307,7 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(M9-E · 17 검사). --check=<이름>[,<이름>...] 로
+    // `gaon doctor` — 정적 검사(M9-E · 27 검사 · ALL_RULES 단일 출처). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {

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

@@ -0,0 +1,46 @@
+// 세션 컨트롤러(로그인/로그아웃 · 관리 앱) — gaon g auth --app {{APP_NAME}}.
+// 시큐어 앱은 로그인 **시점**에 역할을 검증한다(결정 218). 인증(비밀번호)만 통과한
+// 고객이 세션을 얻은 뒤 대시보드에서야 403 을 만나는 rough UX 를 진입점에서 막는다:
+//   · 자격 증명이 틀리면       → 인증 실패(401 성격) · 세션 안 만듦 · 재렌더
+//   · 자격은 맞지만 역할 부족  → 인가 실패(403 성격) · 세션 안 만듦 · 재렌더
+// 401 vs 403 을 메시지로 구분한다 — 어느 쪽도 세션을 만들지 않는다.
+import { controller, verifyPassword } from 'gaonjs/web'
+import { User } from '../../../domain/models/User.js'
+
+// 이 앱에 로그인할 수 있는 역할. domain/schema/users.ts 에 role 컬럼을 두고
+// (예: role: t.string().default('user')) 관리자에게 '{{REQUIRED_ROLE}}' 을 부여하세요.
+const REQUIRED_ROLE = '{{REQUIRED_ROLE}}'
+
+export default controller({
+  // GET {{URL_PREFIX}}/session/new — 로그인 폼. csrf 는 자동 주입되므로 넘기지 않는다(결정 116).
+  async new() {
+    return this.render('Auth/Login', { error: null as string | null })
+  },
+  // POST {{URL_PREFIX}}/session — 로그인 + 역할 게이트
+  async create() {
+    const { email, password } = this.params({ _row: {} as { email: string; password: string } })
+    const user = await User.where('email', '=', email).first()
+    // 인증(401 성격): 자격 증명이 틀리면 세션을 만들지 않고 같은 폼을 재렌더한다.
+    // passwordDigest 는 hidden 이지만 서버 코드에서는 투명하게 읽힌다(§4.2).
+    if (!user || !(await verifyPassword(password, user.passwordDigest))) {
+      return this.render('Auth/Login', {
+        error: '이메일 또는 비밀번호가 올바르지 않습니다.' as string | null,
+      })
+    }
+    // 인가(403 성격): 자격은 맞지만 역할이 부족하면 세션을 만들지 않고 재렌더한다.
+    // 고객이 "로그인은 됐는데 403" 을 겪지 않도록 진입점에서 막는다(결정 218 · 결정 155·145 의
+    // 대시보드 역할 게이트와 정합 — 여기서 세션 자체를 안 만들어 관리 앱을 깨끗이 격리).
+    if ((user as { role?: string }).role !== REQUIRED_ROLE) {
+      return this.render('Auth/Login', {
+        error: '이 앱에 접근할 권한이 없습니다.' as string | null,
+      })
+    }
+    this.auth.login(user)
+    return this.redirect('{{URL_PREFIX}}/dashboard')
+  },
+  // DELETE {{URL_PREFIX}}/session — 로그아웃
+  async destroy() {
+    this.auth.logout()
+    return this.redirect('{{URL_PREFIX}}/session/new')
+  },
+})

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

@@ -108,14 +108,14 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 26종
+### 2.2 `gaon doctor` 검사 27종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
 3. `dependency-direction` — 의존 방향 4규칙 위반
 4. `connections` — 스키마·`getConnection` 이 쓰는 커넥션 키가 `gaon.config.ts` 에 등록됐는지 · db 설정 정적 분석(삼항·`??` 지원 · 못 읽으면 안내) (§4.5 · 결정 135)
 5. `migration-diff` — 스키마 vs DB 상태 불일치
-6. `shared-composable-purity` — shared 안 `api`/`pageProps` import (결정 25)
+6. `shared-purity` — shared/ 전체(.ts·.vue)가 `api`/`pageProps`·domain 값을 import (컴포저블·컴포넌트 통일 · 결정 25·217)
 7. `no-auto-import` — 자동 import 설정 (E-5 §2.4)
 8. `schema-filename` — 스키마 파일명 camelCase 관례 (결정 38 · `--fix` 지원)
 9. `agents-doc-index` — 이 문서 색인(§0) ↔ `agents/` 실 파일 불일치 (결정 40)
@@ -136,6 +136,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 24. `seal-security` — `@gaonjs/seal` 을 켠 앱에서 (a) `gaon.config.ts` 가 진짜 방어층(rate limit·보안 헤더·CORS)을 **명시적으로 껐을** 때 = 봉인을 켜고 방어를 끄는 역전 **경고**, (b) `main.ts` 가 seal 클라이언트를 배선(`@gaonjs/seal/client` 정적 import + `createGaonApp` sealClient)하지 않았을 때 = 봉인 문서를 브라우저가 못 열어 blank 가 되는 **에러**(`gaon check --fix` 의 `seal-client-wiring` fixer 가 자동 배선). seal 은 서버 검증을 대체하지 않는다 (결정 121·124 · `agents/seal.md`)
 25. `schema-relations` — 커넥션을 가로지르는 belongsTo·역방향 관계(SQL 조인이 커넥션을 못 넘음)와 존재하지 않는 관계 대상 = **에러**(§4.5). data 패키지 검사(`checkCrossConnectionRelations`·`checkRelationTargets`)를 CLI 러너가 배선 — 배포 후 raw postgres 에러 대신 doctor 가 잡는다 (결정 134 · `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`)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -196,7 +197,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       # 정적 검사 26종 (§2.2)
+gaon doctor       # 정적 검사 27종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)

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

@@ -50,6 +50,9 @@ const props = pageProps<'web:posts#index'>()
   // <template> 에서 shared.currentUser?.name · shared.csrf · shared.flash.success
   // 앱이 app.config sharedProps 로 등록한 키(locale·theme 등)도 같은 자리에서 읽힌다(결정 150).
   ```
+  **i18n 문구도 이 경로로 온다** — Vue 는 `t()` 를 직접 부르지 않는다(서버 ALS 전용).
+  페이지 문구는 컨트롤러 render props, nav·레이아웃 같은 앱 chrome 문구는 `sharedProps`
+  로 서버가 번역해 흘려보낸다(`agents/i18n.md` §5 · 결정 213).
   `pageProps<K>()` 반환에도 교차되어 `props.csrf` 로도 읽히지만, 라우트 키가 필요 없는
   `useShared()` 가 정본 표면이다(임의 라우트 키를 빌려 currentUser 를 읽던 우회 트릭을 없앤다).
 - **파사드는 `gaonjs/vue`** — `@gaonjs/vue` (스코프)·`@inertiajs/vue3` (내부 의존)
@@ -150,15 +153,17 @@ shared/composables/useDebounce.ts      # 앱 간 공용 컴포저블 (순수 로
 | 컴포넌트 | 자유 (pageProps·api 사용 가능) | props 로만 받는 순수 UI |
 | 컴포저블 | 자유 (api·채널 래핑 가능) | 인자로만 받는 순수 로직 |
 
-**shared 컴포저블 제약:**
+**shared 순수성 제약 (컴포저블·컴포넌트 공통):**
 
 - **라우트를 몰라야 한다** — `api()`·`pageProps()` 호출 금지.
   `.gaon/routes.d.ts` 는 앱별 생성이므로 구조적으로도 불가능하다.
-- 필요한 데이터·호출 함수는 **인자로 받는다** (순수 로직).
+- 필요한 데이터·호출 함수는 **props/인자로 받는다** (순수 로직·순수 UI).
 - domain 은 **타입 import 만** 허용.
 
-`gaon doctor` 의 **shared-composable-purity** 검사가 shared 안에서
-`gaonjs/vue` 의 `api`/`pageProps` import 를 잡는다.
+`gaon doctor` 의 **shared-purity** 검사가 `shared/` 전체(`.ts` 컴포저블 +
+`.vue` 컴포넌트)에서 `gaonjs/vue` 의 `api`/`pageProps` 값 import 와 domain
+값 import 를 잡는다 (결정 217 — 컴포저블·컴포넌트 한 규칙으로 통일 · `.vue` 는
+`<script>` 블록을 훑는다).
 
 **shared 컴포넌트(UI 킷 §8)의 허용/금지도 같은 기준(결정 25·105):** 허용 = 라우트 키와
 무관한 범용 API(`useForm`·`Link`·`router`) · 금지 = 앱 라우트 지식(`api()`·`pageProps`).
@@ -392,8 +397,8 @@ async function runSearch(q: string) {
   경계 우회로 타입 안전 붕괴.
 - **`api()` 에 제네릭 인자 직접 붙이지 않는다** — key 리터럴이 타입을
   결정한다.
-- **shared 컴포넌트/컴포저블에서 `pageProps`/`api` 호출 금지** — doctor
-  shared-composable-purity 위반. 데이터는 props/인자로.
+- **shared 컴포넌트/컴포저블에서 `pageProps`/`api` 호출·domain 값 import 금지** —
+  doctor **shared-purity** 위반(`.ts`·`.vue` 공통 · 결정 217). 데이터는 props/인자로.
 - **Vue 페이지에서 `fetch()` 로 폼 구현 금지** — 세션 앱 폼은
   `gaonjs/vue` 의 `useForm(...).post()` (`agents/web.md` §4 · 결정 64).
 - **내부 경로 일반 `<a href="/...">` 금지** — 클릭마다 전체 문서를 다시
@@ -457,6 +462,7 @@ async function runSearch(q: string) {
 | 결정 119 | `Pagination` 블록이 `chain.paginate()` 결과에 정합(`:page`·`:pageCount` 필드 그대로 · 매핑 0 · `agents/data.md`) |
 | 결정 198 | 클라 환경변수 접근자 `env`(gaonjs/vue · `.vue` 의 import.meta.env TS1470 회피) · VITE_* 접두만 노출·접두 제거 · `.gaon/env.d.ts`(.env 스캔) 타입 브리지 · doctor no-import-meta-env(§9) |
 | 결정 206 | UI 킷 §8 슬롯·props 요약표(카탈로그가 이름만이라 소스 열람 유발 · O-2 해소) · named slot 비대칭 명시(PageHeader `#actions` 복수 vs EmptyState `#action` 단수) |
+| 결정 213 | i18n Vue 소비 = 서버 주도 render props/sharedProps 만 · `t()`·`useT()` 클라 미노출(`agents/i18n.md` §5) |
 | E-3 §C | 타입드 `api()` 클라이언트 (routes.d.ts 브리지 재사용) |
 
 ## `@gaonjs/seal` 켠 앱의 프론트

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

@@ -96,6 +96,112 @@ async setLocale() {
 카탈로그에 없는 키·오타가 `gaon check` 에서 걸린다(카탈로그가 없으면 키는
 `string` 폴백). 이 파일은 자동 생성이니 직접 수정하지 않는다.
 
+### 5. Vue 페이지 소비 — 서버가 번역해 흘려보낸다 (결정 213)
+
+**`t()` 는 서버 전용이다** — 요청 컨텍스트(ALS)의 로케일을 읽으므로 `gaonjs/vue`
+는 `t()`·`useT()` 를 **내보내지 않는다**(설계 의도). Vue 페이지·컴포넌트는 번역을
+직접 하지 않고, **서버에서 번역한 문자열을 받아 쓴다.** 번역 소스가 서버 하나로
+고정되므로(The One Way) 카탈로그가 클라 번들에 중복 실리지 않고, 키 타입 검사
+(§4)도 서버 한 곳에서만 성립한다. 경로는 두 가지다:
+
+**(a) 페이지 문구 = 컨트롤러 render props.** 그 페이지에서만 쓰는 문구는 컨트롤러가
+`t()` 로 번역해 `this.render` props 로 넘긴다 — 페이지는 이미 현지화된 문자열을 받는다.
+
+```ts
+// apps/web/controllers/posts.ts
+import { t } from 'gaonjs/i18n'
+async index() {
+  return this.render('Posts/Index', {
+    heading: t('posts.heading'),          // 서버가 요청 로케일로 번역
+    empty: t('posts.empty'),
+    posts: (await Post.latest().all()).map((p) => ({ id: String(p.id), title: p.title })),
+  })
+}
+```
+
+```vue
+<!-- apps/web/pages/Posts/Index.vue -->
+<script setup lang="ts">
+import { pageProps } from 'gaonjs/vue'
+const props = pageProps<'web:posts#index'>()   // heading·empty 가 현지화된 채로 온다
+</script>
+<template>
+  <h1>{{ props.heading }}</h1>
+  <p v-if="!props.posts.length">{{ props.empty }}</p>
+</template>
+```
+
+**(b) 앱 chrome(전 페이지 공용 문구) = `app.config.ts` 의 `sharedProps` (결정 150 동형).**
+nav 라벨·레이아웃 문구처럼 앱의 **모든** 페이지가 쓰는 chrome 문구는 컨트롤러마다
+넘기지 않고 `sharedProps` 로 한 번 등록한다 — `useShared()` 로 라우트 키 없이 읽힌다
+(레이아웃·공용 컴포넌트에서 특히 유용 · `agents/frontend.md` §1·web.md §4.2).
+
+```ts
+// apps/web/app.config.ts
+import { t } from 'gaonjs/i18n'
+export default defineAppConfig({
+  sharedProps: () => ({
+    nav: { home: t('nav.home'), posts: t('nav.posts') },   // 요청 로케일로 번역돼 전 렌더에 주입
+  }),
+})
+```
+
+읽는 쪽은 타입 브리지를 **선언 병합**으로 확장한다(코어 3종 currentUser·csrf·flash 는
+고정 · 앱 키만 추가):
+
+```ts
+// shared/gaon-shared.d.ts (또는 아무 .d.ts)
+import 'gaonjs/vue'
+declare module 'gaonjs/vue' {
+  interface GaonSharedProps { nav: { home: string; posts: string } }
+}
+```
+
+```vue
+<!-- apps/web/layouts/Default.vue -->
+<script setup lang="ts">
+import { useShared, Link } from 'gaonjs/vue'
+const shared = useShared()              // 타입 안전 · 반응형
+</script>
+<template>
+  <nav>
+    <Link href="/">{{ shared.nav.home }}</Link>
+    <Link href="/posts">{{ shared.nav.posts }}</Link>
+  </nav>
+</template>
+```
+
+- **서버 주도가 The One Way** — 로케일 전환(`this.setLocale`·§3) 후 다음 요청의
+  render props·sharedProps 가 새 로케일로 다시 번역돼 흘러든다. 클라가 카탈로그를
+  들고 다시 번역할 일이 없다(같은 정답이 둘로 갈라지지 않는다).
+- **함수형 `sharedProps` 로 매 요청 번역** — `sharedProps: () => ({...})` 는 요청마다
+  실행되므로 `t()` 가 그 요청의 로케일을 읽는다. 상수 객체로 굳히면 첫 로케일에
+  박제된다(변이 축은 함수로 계산 · web.md §4.2).
+
+### 6. `<html lang>` 은 요청 로케일을 자동으로 따른다 (결정 214)
+
+`i18n` 이 설정된 프로젝트는 최초 문서 응답(Inertia 셸)의 `<html lang>` 이 그 요청의
+협상 로케일로 자동 치환된다 — `apps/<앱>/index.html` 의 `<html lang="ko">` 는 정적
+기본값일 뿐이고, `Accept-Language: ja`(또는 `gaon_locale=ja` 쿠키·세션)면 응답 셸은
+`<html lang="ja">` 로 나간다. 손으로 배선할 것이 없다(자동 · SEO·스크린리더·`:lang`
+CSS 가 올바른 언어를 안다). 비-i18n 프로젝트는 템플릿 정적값을 그대로 유지한다.
+
+- **템플릿의 `lang` 을 요청마다 바꾸려 하지 말 것** — `index.html` 은 정적 기본값만
+  둔다. 실제 치환은 서버 셸 조립이 한다(SPA X-Inertia JSON 응답은 대상 아님 · 최초
+  문서에만 `<html>` 이 있다).
+- **로케일 전환(`this.setLocale`·§3) 후에도 추종** — 다음 요청의 협상 로케일이
+  쿠키/세션으로 실려 셸 `lang` 도 함께 바뀐다.
+
+### 7. 로케일 커버리지 — `locale-parity` 경고 (결정 216)
+
+`messages.d.ts` 의 키 유니온은 **기준 로케일 하나**에서 나온다(§4). 그래서 어떤 키를
+`ko.json`·`en.json` 에는 넣고 `ja.json` 에만 빠뜨리면 **컴파일은 통과**하고, 런타임에
+일본어 사용자만 fallback(대개 다른 언어) 번역을 조용히 본다 — 타입도 화면도 못 잡는
+사각이다. `gaon doctor`/`gaon check` 의 `locale-parity`(§2.2 27번)가 `locales/` 의
+로케일 간 키 diff 를 계산해 빠진 파일·키를 **경고**로 짚는다(`--json` 은 `detail.missing`).
+로케일이 0·1개면 비교 대상이 없어 무소음이다. 경고이므로 빌드를 세우진 않지만, 로케일을
+추가할 때 키를 전 로케일에 나란히 채워 커버리지를 맞추는 것이 관례다.
+
 ## 정본 예시
 
 ```ts
@@ -123,6 +229,10 @@ export function greetLine(name: string): string {
 - **검증 실패 문안도 로케일화된다** — 예약 namespace `validation.<code>`(예 `validation.required`)
   를 `locales/` 에 넣으면 필드별 사유가 요청 로케일로 번역된다(`agents/web.md` §4.1 · 결정 183).
   프레임웍은 코드만 노출하고 번역은 앱 몫이다(미제공 시 내장 fallback).
+- **Vue 에서 `t()` 를 부르지 말 것** — `gaonjs/vue` 에는 `t()`·`useT()` 가 없다(서버 ALS
+  전용 · 결정 213). 페이지 문구는 컨트롤러 render props, 앱 chrome 은 `sharedProps` 로
+  서버가 번역해 흘려보낸다(§5). 클라 번역 접근자를 자작하지 않는다(카탈로그 이중 존재·
+  번들 비용).
 
 ## 관련 결정 번호
 
@@ -131,3 +241,6 @@ export function greetLine(name: string): string {
 | §7 (v0.15) | i18n 배터리 · locales/ 카탈로그 · t() |
 | 결정 158 (13차 W2) | `.gaon/messages.d.ts` 키 타입 브리지 — 없는 키 컴파일 에러 |
 | 결정 159 (13차 W1) | 요청별 로케일 자동 협상(wireGaon onRequest) · `this.setLocale` · detect 설정 |
+| 결정 213 | Vue 클라 소비 = 서버 주도 render props/sharedProps 만(§5) · `t()`·`useT()` 클라 미노출(서버 ALS 전용) · sharedProps 는 결정 150 동형 |
+| 결정 214 (13차 W2) | 최초 문서 셸 `<html lang>` 이 요청 협상 로케일 자동 추종(§6) · 템플릿 정적값은 기본값 · 비-i18n 무회귀 |
+| 결정 216 (13차 W4) | `locale-parity` doctor 경고(§7) — 로케일 간 키 부분 누락 = fallback 조용 노출 · 기준 로케일 유니온의 사각 |

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

@@ -126,6 +126,23 @@ describe('PostPublished (실 NATS JetStream)', () => {
   확증하려면 `maxDeliver: 1`(첫 실패에서 즉시 드롭).
 - `configureEvents` 는 헬퍼가 대신 해 주고, 끝나면 하네스 배선을 복원한다
   (`expectJobProcessed` 와 동형 · 자기 nats 를 `close()` 해도 다음 테스트 무영향).
+- **`service()` 안에서 emit 한 이벤트도 그대로 확증된다(결정 215).** 서비스 트랜잭션 안의
+  `emit` 은 즉시 NATS 로 가지 않고 같은 트랜잭션으로 `_gaon_outbox` 에 스테이징된다
+  (커밋과 발행의 원자성 · 결정 144). 운영에선 `gaon work` 릴레이가 이를 NATS 로 옮기지만
+  테스트엔 릴레이가 없다 — 그래서 `expectEventProcessed` 가 **`trigger` 완료 직후 아웃박스를
+  1회 자동 드레인**해 리스너가 받게 한다. 테스트 작성자는 emit 이 직접이든 `service()`
+  경유든 **같은 헬퍼만** 쓴다(The One Way · 손으로 릴레이를 돌릴 필요 없음). 자동 드레인은
+  표준 하네스(`connectTestDatabase` · `config.nats` + `main` 커넥션)가 배선하므로, `gaon test`
+  로 도는 통합 테스트에서 그냥 성립한다.
+
+```ts
+// service() 가 emit 하는 흐름도 같은 한 줄로 확증된다(트리거만 서비스 호출로 바꾸면 됨).
+await expectEventProcessed(PostPublished, () => PublishPost.call({ postId: 1n }), { nats })
+```
+
+- **타이밍 제어가 필요한 다단계 시나리오**만 명시 탈출구 `drainOutbox()`(`gaonjs/testing`)를
+  직접 부른다 — 스테이징된 아웃박스 행을 즉시 릴레이하고 발행 건수를 돌려준다. 기본 경로엔
+  필요 없다(자동 드레인이 The One Way).
 
 ### 5. DB 테스트 격리 — `gaon test` + `test/setup.ts` (결정 111)
 
@@ -256,6 +273,7 @@ hidden 값은 **서버 코드에서는 여전히 읽힌다**(직렬화 경계에
 | 결정 | 내용 |
 |---|---|
 | 결정 42 | 비동기 테스트 헬퍼 `expectJobProcessed` (`gaonjs/testing`) |
+| 결정 215 (13차 W3) | `expectEventProcessed` 가 trigger 뒤 아웃박스 1회 자동 드레인 — `service()` 경유 emit(결정 144 스테이징)도 같은 헬퍼로 확증(§4.1) · 명시 탈출구 `drainOutbox()` |
 | 결정 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 이행) |

package/dist/templates/project/apps/web/index.html.tpl

@@ -9,8 +9,10 @@
     <!--
       Vite 개발 서버가 이 index.html 을 서빙한다(dev). 운영 빌드는
       vite build 가 이 파일을 진입점 삼아 프로덕션 번들을 만든다.
-      Fastify(gaonjs/web) 는 초기 SPA 응답 셸에서 아래와 같은 구조의
-      <div id="app" data-page="..."> 를 내려보낸다 — 개발과 운영이 같은 셸.
+      Fastify(gaonjs/web) 는 초기 SPA 응답 셸에서 빈 <div id="app"></div> 와
+      함께 초기 페이지 객체를 <script type="application/json" data-page="app">…</script>
+      엘리먼트로 내려보낸다(data-page 는 div 속성이 아니라 이 script 태그에 실린다) —
+      개발과 운영이 같은 셸이다.
     -->
     <div id="app"></div>
     <script type="module" src="/main.ts"></script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Gaon CLI — 스캐폴딩·제너레이터·마이그레이션·dev/serve/work/hub·doctor·check (bin: gaon)",
   "type": "module",
   "license": "MIT",
@@ -27,13 +27,13 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.12.0",
-    "@gaonjs/data": "0.16.1",
-    "@gaonjs/config": "0.15.2",
+    "@gaonjs/config": "0.16.0",
+    "@gaonjs/async": "0.13.0",
+    "@gaonjs/mail": "0.2.1",
     "@gaonjs/core": "0.2.2",
     "@gaonjs/i18n": "0.2.1",
-    "@gaonjs/web": "0.18.1",
-    "@gaonjs/mail": "0.2.1"
+    "@gaonjs/data": "0.16.1",
+    "@gaonjs/web": "0.19.0"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""