@gaonjs/cli 0.60.0 → 0.62.0

package/dist/commands/check.js

@@ -255,15 +255,20 @@ function verifyI18nCatalogs(cwd) {
     const resources = existsSync(abs) ? loadLocales(abs) : {};
     if (Object.keys(resources).length === 0) {
         return (`i18n 이 설정됐지만 로케일 카탈로그가 비어 있습니다: ${abs}\n` +
-            `  → ${dir}/${cfg.fallbackLng ?? '<fallbackLng>'}.json 을 만들거나(최소 fallbackLng 카탈로그),\n` +
+            `  → ${dir}/${cfg.fallbackLng ?? '<fallbackLng>'}/frontend.json (화면 문구) 또는 ` +
+            `${dir}/${cfg.fallbackLng ?? '<fallbackLng>'}/backend.json (서버 전용 문구)을 만드세요 — 결정 454.\n` +
+            `  → 단일 파일 레이아웃(${dir}/${cfg.fallbackLng ?? '<fallbackLng>'}.json)도 계속 지원합니다(서버 전용으로 취급).\n` +
             `  → gaon.config.ts 의 i18n.dir 이 실제 카탈로그 폴더를 가리키는지 확인하세요.\n` +
             `  (이 상태로는 gaon serve 가 부팅에서 실패합니다 — 결정 353)`);
     }
     const wanted = [...(cfg.fallbackLng ? [cfg.fallbackLng] : []), ...(cfg.supportedLngs ?? [])];
     const missing = wanted.filter((lng, i, arr) => arr.indexOf(lng) === i && !resources[lng]);
     if (missing.length > 0) {
-        return (`i18n 설정이 지목한 로케일의 카탈로그 파일이 없습니다: ${missing.join(', ')}\n` +
-            `  → ${dir}/ 에 ${missing.map((l) => `${l}.json`).join(' · ')} 을 추가하거나,\n` +
+        return (`i18n 설정이 지목한 로케일의 카탈로그가 없습니다: ${missing.join(', ')}\n` +
+            `  → ${dir}/ 에 ${missing.map((l) => `${l}/frontend.json`).join(' · ')} (또는 ${missing
+                .map((l) => `${l}/backend.json`)
+                .join(' · ')})을 추가하거나,\n` +
+            `  → 단일 파일 레이아웃이면 ${missing.map((l) => `${l}.json`).join(' · ')} 을 추가하거나,\n` +
             `  → gaon.config.ts 의 fallbackLng/supportedLngs 에서 해당 로케일을 제거하세요.\n` +
             `  (이 상태로는 gaon serve 가 부팅에서 실패합니다 — 결정 353)`);
     }

package/dist/dev.d.ts

@@ -4,6 +4,16 @@ export interface DevApp {
     readonly appDir: string;
     /** apps/<app>/.gaon/routes.d.ts */
     readonly routesOut: string;
+    /** apps/<app>/locales (앱 전용 frontend 카탈로그 · 결정 454). */
+    readonly localesDir: string;
+    /** apps/<app>/.gaon/messages.catalog.ts (클라 카탈로그 값 모듈 · 결정 454). */
+    readonly catalogOut: string;
+}
+/** 메시지 축이 카탈로그 모듈을 낼 앱 참조(결정 454 · messages-gen.MessagesApp 과 구조 호환). */
+export interface MessagesAppRef {
+    readonly name: string;
+    readonly localesDir: string;
+    readonly catalogOut: string;
 }
 export interface DevLayout {
     /** domain/schema (없으면 undefined — tables 워치 생략). */
@@ -28,8 +38,11 @@ export interface DevDeps {
     readonly layout: DevLayout;
     regenerateTables(schemaDir: string, out: string): Promise<unknown>;
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
-    /** locales/ → .gaon/messages.d.ts (결정 158 · W2 · 기준 로케일 = 결정 352). i18n 축을 쓰는 호출자만 준다. */
-    regenerateMessages?(localesDir: string, out: string, baseLng?: string): unknown;
+    /**
+     * locales/ → .gaon/messages.d.ts (결정 158 · W2 · 기준 로케일 = 결정 352) + 앱별
+     * messages.catalog.ts (결정 454 · apps 를 넘긴 호출자만). i18n 축을 쓰는 호출자만 준다.
+     */
+    regenerateMessages?(localesDir: string, out: string, baseLng?: string, apps?: readonly MessagesAppRef[]): unknown;
     /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
     regenerateEnv?(envFile: string, out: string): unknown;
     watch(dir: string, opts: WatchOptions): WatchHandle;
@@ -60,8 +73,8 @@ export declare function startDev(deps: DevDeps): Promise<DevHandle>;
 export interface RegenDeps {
     regenerateTables(schemaDir: string, out: string): Promise<unknown>;
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
-    /** locales/ → .gaon/messages.d.ts (결정 158 · W2 · 기준 로케일 = 결정 352). i18n 축을 쓰는 호출자만 준다. */
-    regenerateMessages?(localesDir: string, out: string, baseLng?: string): unknown;
+    /** locales/ → .gaon/messages.d.ts + 앱별 messages.catalog.ts (결정 158 · 352 · 454). */
+    regenerateMessages?(localesDir: string, out: string, baseLng?: string, apps?: readonly MessagesAppRef[]): unknown;
     /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
     regenerateEnv?(envFile: string, out: string): unknown;
 }

package/dist/dev.js

@@ -40,7 +40,7 @@ export async function startDev(deps) {
     }
     // 결정 158(W2): locales/ → messages.d.ts.
     if (layout.localesDir && deps.regenerateMessages) {
-        await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng);
+        await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng, messagesAppsOf(layout));
         deps.log({ kind: 'regen', target: 'messages' });
     }
     // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts(VITE_* 타입 브리지). `.env` 부재는
@@ -80,7 +80,7 @@ export async function startDev(deps) {
         handles.push(deps.watch(localesDir, {
             filter: isMessagesChange,
             onChange: async () => {
-                await regenerateMessages(localesDir, layout.messagesOut, layout.messagesBaseLng);
+                await regenerateMessages(localesDir, layout.messagesOut, layout.messagesBaseLng, messagesAppsOf(layout));
                 deps.log({ kind: 'regen', target: 'messages' });
             },
             onError: deps.onError,
@@ -111,7 +111,8 @@ export async function regenerateGaonOnce(layout, deps) {
     // 결정 158(W2): locales/ 가 있으면 messages.d.ts 도 재생성한다(i18n 키 타입 브리지).
     let messages = false;
     if (layout.localesDir && deps.regenerateMessages) {
-        messages = (await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng)) === true;
+        messages =
+            (await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng, messagesAppsOf(layout))) === true;
     }
     // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts. `.env` 부재는 throw(수리 안내).
     let env = false;
@@ -120,6 +121,10 @@ export async function regenerateGaonOnce(layout, deps) {
     }
     return { tables: !!layout.schemaDir, apps: layout.apps.map((a) => a.name), messages, env };
 }
+/** 결정 454: 레이아웃의 앱 목록을 메시지 축 입력(카탈로그 모듈 경로)으로 좁힌다. */
+function messagesAppsOf(layout) {
+    return layout.apps.map((a) => ({ name: a.name, localesDir: a.localesDir, catalogOut: a.catalogOut }));
+}
 /** cwd 관례로 프로젝트 레이아웃을 해석한다(존재하는 것만 포함). */
 export function resolveDevLayout(cwd) {
     const root = resolve(cwd);
@@ -142,6 +147,8 @@ export function resolveDevLayout(cwd) {
                 name: entry.name,
                 appDir,
                 routesOut: join(appDir, '.gaon', 'routes.d.ts'),
+                localesDir: join(appDir, 'locales'),
+                catalogOut: join(appDir, '.gaon', 'messages.catalog.ts'),
             });
         }
     }

package/dist/doctor/fixers/i18n-layout.d.ts

@@ -0,0 +1,7 @@
+import type { DoctorCheck } from '../types.js';
+import type { FixerPlan } from './types.js';
+/**
+ * i18n-layout 위반(레거시 단일 파일)을 폴더 레이아웃으로 옮기는 계획을 만든다.
+ * 내용은 그대로다 — 키 이름도 바뀌지 않는다(결정 454 R4).
+ */
+export declare function fixI18nLayout(issues: readonly DoctorCheck[], cwd: string): Promise<readonly FixerPlan[]>;

package/dist/doctor/fixers/i18n-layout.js

@@ -0,0 +1,40 @@
+// @gaonjs/cli · doctor fixer · 레거시 단일 파일 카탈로그 → 폴더 레이아웃 이관 (결정 454)
+//
+// `locales/<로케일>.json` → `locales/<로케일>/backend.json` **이동만** 한다(rename 계획).
+//
+// **왜 전량 backend 인가(안전 방향 자동화)**: 자동 분류가 오판하면 서버 전용 문구를
+// frontend 로 보내 클라 번들·CDN 캐시에 노출된다 — 되돌리기 어려운 방향의 사고다.
+// 되돌리기 쉬운 방향(전량 backend = 클라에서 안 보임)으로만 자동화하고, 화면 문구를
+// frontend.json 으로 옮기는 판단은 사람이 한다(doctor 경고가 그 다음 단계를 안내).
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * i18n-layout 위반(레거시 단일 파일)을 폴더 레이아웃으로 옮기는 계획을 만든다.
+ * 내용은 그대로다 — 키 이름도 바뀌지 않는다(결정 454 R4).
+ */
+export async function fixI18nLayout(issues, cwd) {
+    const plans = [];
+    for (const issue of issues) {
+        const to = issue.detail?.to;
+        if (typeof to !== 'string' || issue.file === undefined)
+            continue;
+        let before;
+        try {
+            before = await readFile(join(cwd, issue.file), 'utf8');
+        }
+        catch {
+            continue; // 그 사이 파일이 사라졌으면 계획에서 제외(상위가 부분 적용을 감당하지 않게).
+        }
+        plans.push({
+            kind: 'rename',
+            file: issue.file,
+            to,
+            before,
+            summary: `카탈로그를 폴더 레이아웃으로 이동: ${issue.file} → ${to} (결정 454)\n` +
+                `  내용·키는 그대로다. 이 상태에서는 **서버 전용**(클라로 나가지 않음)이다.\n` +
+                `  → 화면에 보이는 문구만 같은 폴더의 frontend.json 으로 옮긴 뒤 gaon gen 을 실행하세요.`,
+            refEdits: [], // JSON 카탈로그는 소스가 import 하지 않는다(경로 참조 갱신 없음).
+        });
+    }
+    return plans;
+}

package/dist/doctor/fixers/index.d.ts

@@ -5,6 +5,7 @@ export { fixDependencyDirection, fixDomainToSharedTypeOnly, } from './dependency
 export { fixSchemaFilename, rewriteSchemaImport } from './schema-filename.js';
 export { fixModelFilename, rewriteModelImport } from './model-filename.js';
 export { fixSealClientWiring, wireSealClient } from './seal-client-wiring.js';
+export { fixI18nLayout } from './i18n-layout.js';
 /**
  * 규칙별 fixer 표. 없는 규칙(값 undefined)은 "수동 수정 필요" 로 리포트된다.
  * 새 fixer 를 만들면 이 표에만 추가하면 된다(runDoctorFix 는 표를 순회).

package/dist/doctor/fixers/index.js

@@ -10,10 +10,12 @@ import { fixDependencyDirection } from './dependency-direction.js';
 import { fixSchemaFilename } from './schema-filename.js';
 import { fixModelFilename } from './model-filename.js';
 import { fixSealClientWiring } from './seal-client-wiring.js';
+import { fixI18nLayout } from './i18n-layout.js';
 export { fixDependencyDirection, fixDomainToSharedTypeOnly, } from './dependency-direction.js';
 export { fixSchemaFilename, rewriteSchemaImport } from './schema-filename.js';
 export { fixModelFilename, rewriteModelImport } from './model-filename.js';
 export { fixSealClientWiring, wireSealClient } from './seal-client-wiring.js';
+export { fixI18nLayout } from './i18n-layout.js';
 /**
  * 규칙별 fixer 표. 없는 규칙(값 undefined)은 "수동 수정 필요" 로 리포트된다.
  * 새 fixer 를 만들면 이 표에만 추가하면 된다(runDoctorFix 는 표를 순회).
@@ -23,6 +25,7 @@ export const FIXERS = {
     'schema-filename': fixSchemaFilename,
     'model-filename': fixModelFilename,
     'seal-security': fixSealClientWiring,
+    'i18n-layout': fixI18nLayout,
 };
 /**
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
@@ -35,6 +38,16 @@ export const FIXERS = {
  * (`fixers/capabilities.test.ts` · ALL_RULES ↔ 카탈로그 대칭).
  */
 export const FIXER_CAPABILITIES = [
+    {
+        rule: 'i18n-layout',
+        hasFixer: true,
+        note: '자동 · locales/<로케일>.json → locales/<로케일>/backend.json 이동(결정 454). 화면 문구를 frontend.json 으로 나누는 것은 노출 방향이라 사람이 판단한다.',
+    },
+    {
+        rule: 'i18n-app-scope',
+        hasFixer: false,
+        note: '수동 · 그 키를 이 앱 카탈로그(apps/<앱>/locales/<로케일>.json) 또는 공용 locales/<로케일>/frontend.json 에 추가(어느 앱 문구인지는 설계 판단).',
+    },
     {
         rule: 'response-mixing',
         hasFixer: false,
@@ -195,4 +208,9 @@ export const FIXER_CAPABILITIES = [
         hasFixer: false,
         note: '수동 · 공유 .env 에서 NODE_ENV 줄을 지우세요 — 모드는 명령이 정합니다(gaon dev=development · gaon serve=production · 결정 430). 지웠을 때 어떤 모드로 돌리려던 것인지는 사람이 알아야 해서 자동 정정하지 않습니다.',
     },
+    {
+        rule: 'page-fetch',
+        hasFixer: false,
+        note: '수동 · raw fetch 를 api()/useForm 으로 바꾸려면 대응 라우트 키(<앱>:<컨트롤러>#<액션>) 추론이 필요해 기계 변환이 불가합니다 — JSON 액션은 api(), 폼은 useForm, 부득이한 커스텀 전송은 readCsrfToken() 탈출구를 쓰세요(결정 453).',
+    },
 ];

package/dist/doctor/i18n-app-scope.d.ts

@@ -0,0 +1,8 @@
+import type { RuleReport } from './types.js';
+/**
+ * 주석을 공백으로 지운다(문자열 리터럴 안의 `//`·`/*` 는 보존). 스캐폴드·문서 주석이
+ * 예시로 적은 `t('키')` 를 실 호출로 오인해 **오탐 에러**를 내던 것을 막는다(브라우저 e2e
+ * 게이트가 실제로 잡았다). 길이를 보존해 라인 번호 계산이 어긋나지 않는다.
+ */
+export declare function stripComments(src: string): string;
+export declare function checkI18nAppScope(cwd: string): Promise<RuleReport>;

package/dist/doctor/i18n-app-scope.js

@@ -0,0 +1,178 @@
+// @gaonjs/cli · doctor · 앱 경계를 넘는 클라 번역 키 (결정 454 · 에러)
+//
+// **왜 doctor 가 필요한가(타입으로 못 잡는 축)**: 두 앱이 `GaonMessages.keys` 를 서로 다른
+// 유니온으로 augment 하면 TS2717(Subsequent property declarations must have the same type)이
+// 나고, `gaon check` 는 단일 tsc 프로그램이라 앱별 클라 키 유니온을 만들 수 없다(실측 · 결정 454).
+// 그래서 클라 키 유니온은 **프로젝트 전체 frontend 합집합**이고, 앱 경계는 두 층이 강제한다:
+//   · 런타임 = 앱 청크에 그 앱 카탈로그만 실린다(물리적).
+//   · 정적   = 이 검사 — 앱 코드가 **다른 앱 전용 키**를 쓰면 에러로 잡는다.
+//
+// 그냥 두면 컴파일은 통과하고 화면에는 키 문자열이 그대로 뜬다(조용한 실패).
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { flattenKeys, loadAppLocales, loadScopedLocales, withPluralBaseKeys } from '@gaonjs/i18n';
+import { analyzeProjectI18n, resolveLocalesDir } from '../i18n-config.js';
+// `import { t } from 'gaonjs/vue'` 를 쓴 파일에서만 본다 — 서버 t(gaonjs/i18n)는 대상이 아니다.
+const CLIENT_T_IMPORT = /from\s+['"]gaonjs\/vue['"]/;
+// t('key') · t("key") · t(`key`) 의 리터럴 키만 본다(동적 키는 정적 검출 대상 아님).
+const T_CALL = /\bt\(\s*['"`]([^'"`]+)['"`]/g;
+/**
+ * 주석을 공백으로 지운다(문자열 리터럴 안의 `//`·`/*` 는 보존). 스캐폴드·문서 주석이
+ * 예시로 적은 `t('키')` 를 실 호출로 오인해 **오탐 에러**를 내던 것을 막는다(브라우저 e2e
+ * 게이트가 실제로 잡았다). 길이를 보존해 라인 번호 계산이 어긋나지 않는다.
+ */
+export function stripComments(src) {
+    const out = src.split('');
+    let i = 0;
+    let state = 'code';
+    const blank = (from, to) => {
+        for (let k = from; k < to; k++)
+            if (out[k] !== '\n')
+                out[k] = ' ';
+    };
+    while (i < src.length) {
+        const two = src.slice(i, i + 2);
+        if (state === 'code') {
+            if (two === '//') {
+                const end = src.indexOf('\n', i);
+                const stop = end === -1 ? src.length : end;
+                blank(i, stop);
+                i = stop;
+                continue;
+            }
+            if (two === '/*') {
+                const end = src.indexOf('*/', i + 2);
+                const stop = end === -1 ? src.length : end + 2;
+                blank(i, stop);
+                i = stop;
+                continue;
+            }
+            if (src.startsWith('<!--', i)) {
+                const end = src.indexOf('-->', i + 4);
+                const stop = end === -1 ? src.length : end + 3;
+                blank(i, stop);
+                i = stop;
+                continue;
+            }
+            const c = src[i];
+            if (c === "'")
+                state = 'single';
+            else if (c === '"')
+                state = 'double';
+            else if (c === '`')
+                state = 'tick';
+            i++;
+            continue;
+        }
+        // 문자열 안 — 이스케이프를 건너뛰고 닫는 따옴표에서 code 로 돌아간다.
+        const c = src[i];
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if ((state === 'single' && c === "'") || (state === 'double' && c === '"') || (state === 'tick' && c === '`')) {
+            state = 'code';
+        }
+        i++;
+    }
+    return out.join('');
+}
+const SOURCE_EXT = ['.vue', '.ts'];
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.gaon']);
+function walk(dir, out = []) {
+    if (!existsSync(dir))
+        return out;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.') && entry.name !== '.gaon')
+            continue;
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        const p = join(dir, entry.name);
+        if (entry.isDirectory())
+            walk(p, out);
+        else if (SOURCE_EXT.some((e) => entry.name.endsWith(e)))
+            out.push(p);
+    }
+    return out;
+}
+/** 그 앱의 클라가 실제로 받는 키 집합 = 공용 frontend ∪ 자기 앱 카탈로그(전 로케일 합집합). */
+function keysForApp(localesDir, appLocalesDir) {
+    const scoped = loadScopedLocales(localesDir);
+    const keys = new Set();
+    for (const res of Object.values(scoped.frontend)) {
+        for (const k of withPluralBaseKeys(flattenKeys(res.translation)))
+            keys.add(k);
+    }
+    for (const res of Object.values(loadAppLocales(appLocalesDir))) {
+        for (const k of withPluralBaseKeys(flattenKeys(res.translation)))
+            keys.add(k);
+    }
+    return keys;
+}
+/** 프로젝트 전체(모든 앱)의 클라 키 — "다른 앱에는 있는 키" 인지 구분해 안내를 정확히 한다. */
+function allClientKeys(localesDir, appDirs) {
+    const keys = keysForApp(localesDir, '');
+    for (const appDir of appDirs) {
+        for (const res of Object.values(loadAppLocales(join(appDir, 'locales')))) {
+            for (const k of withPluralBaseKeys(flattenKeys(res.translation)))
+                keys.add(k);
+        }
+    }
+    return keys;
+}
+export async function checkI18nAppScope(cwd) {
+    const appsDir = join(cwd, 'apps');
+    if (!existsSync(appsDir))
+        return { rule: 'i18n-app-scope', issues: [] };
+    const cfg = analyzeProjectI18n(cwd);
+    const localesDir = resolveLocalesDir(cwd, cfg.dir);
+    if (!existsSync(localesDir))
+        return { rule: 'i18n-app-scope', issues: [] };
+    const appDirs = readdirSync(appsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => join(appsDir, e.name));
+    // frontend 카탈로그가 하나도 없으면(레거시 레이아웃) 클라 t() 자체가 없다 — 무소음.
+    const scoped = loadScopedLocales(localesDir);
+    if (Object.keys(scoped.frontend).length === 0)
+        return { rule: 'i18n-app-scope', issues: [] };
+    const everyKey = allClientKeys(localesDir, appDirs);
+    const issues = [];
+    for (const appDir of appDirs) {
+        const appLocales = join(appDir, 'locales');
+        const own = keysForApp(localesDir, appLocales);
+        for (const file of walk(appDir)) {
+            if (!statSync(file).isFile())
+                continue;
+            const raw = readFileSync(file, 'utf8');
+            if (!CLIENT_T_IMPORT.test(raw))
+                continue;
+            // 주석 안 예시(`t('키')` 같은 설명)를 실 호출로 세지 않는다 — 오탐은 빌드를 세운다.
+            const src = stripComments(raw);
+            for (const m of src.matchAll(T_CALL)) {
+                const key = m[1];
+                if (own.has(key))
+                    continue;
+                const line = src.slice(0, m.index).split('\n').length;
+                const rel = relative(cwd, file);
+                const elsewhere = everyKey.has(key);
+                issues.push({
+                    rule: 'i18n-app-scope',
+                    level: 'error',
+                    file: rel,
+                    line,
+                    message: elsewhere
+                        ? `'${key}' 는 **다른 앱 전용** 번역 키입니다 — 이 앱의 카탈로그에 없습니다: ${rel}:${line} (결정 454)\n` +
+                            `  앱 번들에는 그 앱 카탈로그만 실리므로 런타임에 번역 대신 키 문자열이 그대로 보입니다.\n` +
+                            `→ 이 앱에서도 쓸 문구면 공용 ${relative(cwd, join(localesDir, '<로케일>', 'frontend.json'))} 로 옮기고,\n` +
+                            `→ 이 앱 전용 문구면 ${relative(cwd, join(appLocales, '<로케일>.json'))} 에 추가한 뒤 gaon gen 을 실행하세요.`
+                        : `'${key}' 를 어느 카탈로그에서도 찾을 수 없습니다: ${rel}:${line} (결정 454)\n` +
+                            `→ ${relative(cwd, join(appLocales, '<로케일>.json'))}(앱 전용) 또는 ` +
+                            `${relative(cwd, join(localesDir, '<로케일>', 'frontend.json'))}(앱 공용)에 키를 추가하고 gaon gen 을 실행하세요.\n` +
+                            `  (서버 전용 문구는 backend.json 에 두고 서버 t()(gaonjs/i18n)로 쓰세요 — 클라로 나가지 않습니다.)`,
+                    detail: { key, app: relative(cwd, appDir), definedInAnotherApp: elsewhere },
+                });
+            }
+        }
+    }
+    return { rule: 'i18n-app-scope', issues };
+}

package/dist/doctor/i18n-layout.d.ts

@@ -0,0 +1,4 @@
+import type { RuleReport } from './types.js';
+/** 레거시 단일 파일 로케일 목록(폴더 레이아웃과 공존하면 로더가 별도로 fail-loud). */
+export declare function legacyLocaleFiles(localesDir: string): string[];
+export declare function checkI18nLayout(cwd: string): Promise<RuleReport>;

package/dist/doctor/i18n-layout.js

@@ -0,0 +1,47 @@
+// @gaonjs/cli · doctor · i18n 카탈로그 레이아웃 안내 (결정 454 · 경고)
+//
+// 결정 454 의 정본 저작 레이아웃은 언어별 폴더 + 스코프 분리다:
+//   locales/<로케일>/backend.json  — 메일·잡·검증 등 **서버 전용**(클라로 안 나감)
+//   locales/<로케일>/frontend.json — 화면 문구(클라 t() 가 쓰는 카탈로그)
+//
+// 레거시 단일 파일(`locales/<로케일>.json`)도 계속 **동작**하지만, 미분류 카탈로그는
+// 안전 기본으로 전량 backend 취급이라 **클라 `t()` 를 쓸 수 없다**(클라 키 축 미생성).
+// 그 사실을 조용히 두면 "왜 gaonjs/vue 의 t 가 키를 그대로 뱉지?" 로 시간을 태운다 —
+// 경고로 짚고 `--fix` 로 폴더 이관까지 해 준다(노출 방향 자동 분류는 하지 않는다).
+import { existsSync, readdirSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { analyzeProjectI18n, resolveLocalesDir } from '../i18n-config.js';
+/** 레거시 단일 파일 로케일 목록(폴더 레이아웃과 공존하면 로더가 별도로 fail-loud). */
+export function legacyLocaleFiles(localesDir) {
+    if (!existsSync(localesDir))
+        return [];
+    return readdirSync(localesDir, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith('.json'))
+        .map((e) => basename(e.name, '.json'))
+        .sort();
+}
+export async function checkI18nLayout(cwd) {
+    const cfg = analyzeProjectI18n(cwd);
+    const localesDir = resolveLocalesDir(cwd, cfg.dir);
+    if (!existsSync(localesDir))
+        return { rule: 'i18n-layout', issues: [] };
+    const legacy = legacyLocaleFiles(localesDir);
+    if (legacy.length === 0)
+        return { rule: 'i18n-layout', issues: [] };
+    const issues = legacy.map((lng) => {
+        const rel = relative(cwd, join(localesDir, `${lng}.json`));
+        const dirRel = relative(cwd, join(localesDir, lng));
+        return {
+            rule: 'i18n-layout',
+            level: 'warning',
+            file: rel,
+            message: `로케일 '${lng}' 이 단일 파일 레이아웃입니다: ${rel} (결정 454)\n` +
+                `  이 카탈로그는 **서버 전용**으로 취급돼 클라이언트 t()(gaonjs/vue)가 쓸 수 없습니다.\n` +
+                `→ 자동 이관: gaon doctor --fix  (${rel} → ${dirRel}/backend.json)\n` +
+                `→ 그 뒤 화면에 보이는 문구만 ${dirRel}/frontend.json 으로 옮기고 gaon gen 을 실행하세요.\n` +
+                `  (frontend 만 클라 번들 청크로 나갑니다 — backend 문구는 노출되지 않습니다.)`,
+            detail: { locale: lng, from: rel, to: `${dirRel}/backend.json` },
+        };
+    });
+    return { rule: 'i18n-layout', issues };
+}

package/dist/doctor/locale-parity.js

@@ -10,7 +10,7 @@
 // 빌드를 세우지 않는다. --json 은 detail.locale·detail.missing 으로 구조화한다.
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { loadLocales, flattenKeys } from '@gaonjs/i18n';
+import { loadScopedLocales, flattenKeys } from '@gaonjs/i18n';
 import { analyzeProjectI18n, resolveLocalesDir } from '../i18n-config.js';
 // 경고 한 줄이 폭주하지 않게 나열 상한 — 넘으면 "…외 N개" 로 접는다(detail 에는 전량).
 const MAX_KEYS_SHOWN = 20;
@@ -32,10 +32,22 @@ export async function checkLocaleParity(cwd) {
     const localesDir = resolveLocalesDir(cwd, analyzeProjectI18n(cwd).dir);
     if (!existsSync(localesDir))
         return { rule: 'locale-parity', issues: [] };
-    const resources = loadLocales(localesDir);
+    // 결정 454: 스코프(backend·frontend)별로 따로 비교한다 — 같은 키를 로케일마다 다른
+    // 스코프에 두면(ko 는 frontend, ja 는 backend) 클라 카탈로그가 갈리므로, 병합본으로
+    // 비교하면 그 배치 불일치를 못 본다. 파일 경로도 스코프별로 정확히 짚는다.
+    const scoped = loadScopedLocales(localesDir);
+    const issues = [];
+    for (const scope of ['backend', 'frontend']) {
+        const resources = scoped[scope];
+        issues.push(...parityIssues(cwd, localesDir, resources, scoped.layout, scope));
+    }
+    return { rule: 'locale-parity', issues };
+}
+/** 한 스코프 안에서 로케일 간 키 diff 를 계산한다(레거시 단일 파일은 backend 스코프에 담긴다). */
+function parityIssues(cwd, localesDir, resources, layout, scope) {
     const langs = Object.keys(resources).sort();
     if (langs.length < 2)
-        return { rule: 'locale-parity', issues: [] };
+        return [];
     // 로케일별 키 집합과 전체 union(어느 로케일에든 등장한 키의 합집합)을 만든다.
     // 복수형 접미사는 base 로 정규화해 로케일별 정당한 복수형 차이를 오탐으로 잡지 않는다.
     const keysByLang = new Map();
@@ -52,7 +64,10 @@ export async function checkLocaleParity(cwd) {
         const missing = [...union].filter((k) => !have.has(k)).sort();
         if (missing.length === 0)
             continue;
-        const rel = relative(cwd, join(localesDir, `${lng}.json`));
+        // 파일 경로는 레이아웃에 맞춘다 — 폴더 분리면 <lng>/<scope>.json, 레거시면 <lng>.json.
+        const rel = layout[lng] === 'legacy'
+            ? relative(cwd, join(localesDir, `${lng}.json`))
+            : relative(cwd, join(localesDir, lng, `${scope}.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}개` : '');
@@ -64,8 +79,8 @@ export async function checkLocaleParity(cwd) {
                 `  누락 키: ${list}\n` +
                 `→ ${rel} 에 이 키들을 채우세요 — 없으면 '${lng}' 사용자에게 fallback(대개 다른 언어)\n` +
                 `  번역이 조용히 노출됩니다. messages.d.ts 는 기준 로케일 기준이라 컴파일로 못 잡습니다(결정 216).`,
-            detail: { locale: lng, missing },
+            detail: { locale: lng, scope, missing },
         });
     }
-    return { rule: 'locale-parity', issues };
+    return issues;
 }

package/dist/doctor/page-fetch.d.ts

@@ -0,0 +1,8 @@
+import type { RuleReport } from './types.js';
+/** 소스에서 내부 경로 raw fetch 호출을 찾는다(단위 테스트 진입점 · 주석 제외). */
+export declare function internalFetchCalls(source: string): {
+    line: number;
+    path: string;
+}[];
+/** 세션 앱(비 JWT)의 .vue 를 훑어 내부 경로 raw fetch 를 경고로 낸다. */
+export declare function checkPageFetch(cwd: string): Promise<RuleReport>;

package/dist/doctor/page-fetch.js

@@ -0,0 +1,107 @@
+// @gaonjs/cli · doctor · 세션 앱 프론트의 내부 경로 raw fetch 검출 (결정 453 · 경고)
+//
+// 세션 앱의 `.vue` 에서 앱 내부 경로를 raw `fetch('/...')` 로 부르면 CSRF
+// 토큰이 어디에도 실리지 않아 상태 변경 요청(POST/PUT/PATCH/DELETE)이 403
+// 으로 죽는다 — 자동 부착(결정 166·341·342)은 `api()`·`useForm`·`router` 를
+// 탈 때만 작동한다(rooms 샘플 실사용에서 강퇴/위임이 이 경로로 죽었다).
+// csrf-wiring(결정 93)은 서버 세션 배선만 보므로 클라이언트 우회는 이 검사가
+// 잡는다. 폼은 `useForm`, JSON 액션은 `api()` 가 정본(agents/frontend.md §2).
+//
+// 오탐 방지: 첫 인자가 `/` 로 시작하는 **문자열/템플릿 리터럴**일 때만 —
+// 외부 URL(http…)·변수/식 인자(정적 판별 불가)·`//`(프로토콜-상대)는 건드리지
+// 않는다. JWT/API 앱은 토큰 인증이라 REST + fetch 가 정본 경로 — 제외한다.
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { usesJwtStrategy } from './auth-wiring.js';
+// 주석을 공백 치환하되 줄바꿈은 보존(라인 번호 유지) — internal-anchor 와 동형.
+function stripCommentsKeepLines(source) {
+    const blank = (m) => m.replace(/[^\n]/g, ' ');
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, blank)
+        .replace(/<!--[\s\S]*?-->/g, blank)
+        .replace(/(^|[^:])\/\/[^\n]*/g, (_m, p1) => p1 + ' '.repeat(_m.length - p1.length));
+}
+// `fetch(` 의 첫 인자가 내부 경로 리터럴인 호출만 잡는다. 앞이 식별자/점이면
+// (`myFetch(`·`api.fetch(`) 다른 함수다 — 전역 fetch 호출만 본다.
+const INTERNAL_FETCH = /(?<![.\w$])fetch\s*\(\s*(['"`])(\/(?!\/)[^'"`\n]*)\1/g;
+/** 소스에서 내부 경로 raw fetch 호출을 찾는다(단위 테스트 진입점 · 주석 제외). */
+export function internalFetchCalls(source) {
+    const stripped = stripCommentsKeepLines(source);
+    const out = [];
+    for (const m of stripped.matchAll(INTERNAL_FETCH)) {
+        const line = stripped.slice(0, m.index ?? 0).split('\n').length;
+        out.push({ line, path: m[2] });
+    }
+    return out;
+}
+/** 세션 앱(비 JWT)의 .vue 를 훑어 내부 경로 raw fetch 를 경고로 낸다. */
+export async function checkPageFetch(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        // JWT/API 앱은 REST + fetch 가 정본 — 제외(csrf-wiring 과 동일 판정).
+        const acPath = join(appsDir, app, 'app.config.ts');
+        if (existsSync(acPath)) {
+            const acSource = await readFile(acPath, 'utf8').catch(() => '');
+            if (usesJwtStrategy(acSource))
+                continue;
+        }
+        for (const abs of await walkVue(join(appsDir, app))) {
+            const source = await readFile(abs, 'utf8').catch(() => '');
+            const rel = relative(cwd, abs);
+            for (const hit of internalFetchCalls(source)) {
+                issues.push({
+                    rule: 'page-fetch',
+                    level: 'warning',
+                    file: rel,
+                    line: hit.line,
+                    message: `내부 경로 raw fetch 발견: ${rel}:${hit.line} 이 \`fetch('${hit.path}')\` 로 앱 내부를 ` +
+                        `직접 호출합니다. 세션 앱의 CSRF 토큰 자동 부착(결정 166·341·342)은 \`api()\`·\`useForm\`·` +
+                        `\`router\` 를 탈 때만 작동해, raw fetch 의 상태 변경 요청은 403 으로 죽습니다(결정 453).\n` +
+                        `→ JSON 액션(강퇴·위임·좋아요 등 커맨드 포함)은 \`gaonjs/vue\` 의 \`api()\` 로 부르세요: ` +
+                        `\`await api('<앱>:<컨트롤러>#<액션>', { ...params })\` (agents/frontend.md §2).\n` +
+                        `→ 폼 제출은 \`useForm(...).post()\`, DELETE 등은 \`router.delete(...)\` (agents/web.md §4).\n` +
+                        `→ 부득이한 커스텀 전송은 \`readCsrfToken()\` 으로 토큰을 직접 실으세요(탈출구 · 결정 342).`,
+                    detail: { file: rel, line: hit.line, path: hit.path },
+                });
+            }
+        }
+    }
+    return { rule: 'page-fetch', issues };
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** 앱 하위 .vue 절대경로(내림차순 아님 · node_modules/.gaon 제외). */
+async function walkVue(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')
+                    continue;
+                await walk(abs);
+            }
+            else if (e.isFile() && e.name.endsWith('.vue')) {
+                out.push(abs);
+            }
+        }
+    };
+    await walk(dir);
+    return out.sort();
+}