@gaonjs/cli 0.64.0 → 0.65.0

package/dist/doctor/locale-parity.js

@@ -9,18 +9,17 @@
 // 경고(error 아님): 부분 누락은 fallback 으로 화면이 깨지진 않는 소프트 결함이라
 // 빌드를 세우지 않는다. --json 은 detail.locale·detail.missing 으로 구조화한다.
 //
-// 결정 456: **앱 스코프 카탈로그(`apps/<앱>/locales/<로케일>.json`)까지 훑는다.**
-// 결정 454 가 앱 전용 화면 문구의 정본 배치로 이 경로를 지정했고 `agents/i18n.md`
-// 정본 예시가 "같은 키를 나란히(locale-parity)" 라고 **약속**하는데, 검사는 루트
-// `locales/` 만 보고 있었다(auction 샘플 실측 — 앱 카탈로그에서 키를 지워도 무소음).
-// `i18n-app-scope` 도 대신 못 잡는다: 그 검사의 키 집합은 **전 로케일 합집합**이라
-// en 에만 있는 키도 "있는 키" 로 세기 때문이다(축이 다르다 — 앱 경계 침범 검출).
-// 비교는 **앱 내부에서만** 한다 — 앱 카탈로그와 루트를 교차 비교하면 앱 전용 키가
-// 전부 "루트에 없음" 으로 뜨는 오탐이 된다(앱 카탈로그는 루트의 초과분이 정상).
-import { existsSync, readdirSync } from 'node:fs';
+// 결정 456: **앱 스코프 카탈로그까지 훑는다.** `i18n-app-scope` 는 대신 못 잡는다:
+// 그 검사의 키 집합은 **전 로케일 합집합**이라 en 에만 있는 키도 "있는 키" 로 세기
+// 때문이다(축이 다르다 — 앱 경계 침범 검출).
+//
+// 결정 459: 소유자가 domain / 앱 N개로 재편되면서 비교 단위가 **3종**이 된다:
+//   ① domain-backend 로케일 간  ② 앱별 frontend 로케일 간  ③ 앱별 backend 로케일 간
+// **스코프·소유자를 가로지르는 비교는 하지 않는다** — 앱 전용 키가 전량 "도메인에 없음"
+// 으로 뜨는 오탐이 되고(결정 456 이 이미 기각한 축), frontend↔backend 는 애초에 다른 축이다.
 import { join, relative } from 'node:path';
-import { loadAppLocales, loadScopedLocales, flattenKeys } from '@gaonjs/i18n';
-import { analyzeProjectI18n, resolveLocalesDir } from '../i18n-config.js';
+import { loadProjectLocales, flattenKeys } from '@gaonjs/i18n';
+import { analyzeProjectI18n } from '../i18n-config.js';
 // 경고 한 줄이 폭주하지 않게 나열 상한 — 넘으면 "…외 N개" 로 접는다(detail 에는 전량).
 const MAX_KEYS_SHOWN = 20;
 // i18next 복수형 접미사(결정 181 · generator.ts 와 동일 규약). 로케일마다 필요한 접미사만
@@ -36,66 +35,27 @@ function pluralBase(key) {
  * 비교 대상이 없어 건너뛴다(i18n 미사용·단일 로케일 프로젝트는 무소음).
  */
 export async function checkLocaleParity(cwd) {
-    // 결정 352: 카탈로그 위치는 config i18n.dir 을 따른다(정적 분석 · 하드코딩이던
-    // 'locales' 는 dir 커스텀 프로젝트에서 이 검사를 무소음으로 껐다).
-    const localesDir = resolveLocalesDir(cwd, analyzeProjectI18n(cwd).dir);
-    if (!existsSync(localesDir))
+    if (!analyzeProjectI18n(cwd).declared)
         return { rule: 'locale-parity', issues: [] };
-    // 결정 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));
-    }
-    issues.push(...appParityIssues(cwd));
-    return { rule: 'locale-parity', issues };
-}
-/** `apps/` 아래 앱 폴더 이름들(없으면 빈 배열). */
-function appNames(cwd) {
+    let project;
     try {
-        return readdirSync(join(cwd, 'apps'), { withFileTypes: true })
-            .filter((e) => e.isDirectory())
-            .map((e) => e.name)
-            .sort();
+        project = loadProjectLocales(cwd);
     }
     catch {
-        return [];
+        // 로더 fail-loud 는 i18n-layout·check 가 소유한다 — 여기선 침묵(중복 진단 금지).
+        return { rule: 'locale-parity', issues: [] };
     }
-}
-/**
- * 결정 456: 앱 스코프 카탈로그의 로케일 간 키 diff. 앱 **내부에서만** 비교한다
- * (앱 카탈로그는 루트 frontend 의 초과분이 정상이라 교차 비교는 전량 오탐).
- * 앱 카탈로그는 frontend 전용이므로(결정 454 R7) 스코프 분리는 없다.
- */
-function appParityIssues(cwd) {
     const issues = [];
-    for (const app of appNames(cwd)) {
-        const appLocalesDir = join(cwd, 'apps', app, 'locales');
-        if (!existsSync(appLocalesDir))
-            continue;
-        const resources = loadAppLocales(appLocalesDir);
-        for (const [lng, missing] of missingByLang(resources)) {
-            const rel = relative(cwd, join(appLocalesDir, `${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} 에 이 키들을 채우고 gaon gen 을 실행하세요 — 없으면 '${lng}' 사용자 화면에\n` +
-                    `  키 문자열이 그대로 노출됩니다(결정 455 런타임 degrade). 앱 공용 문구면 대신\n` +
-                    `  locales/${lng}/frontend.json 으로 올리세요.`,
-                detail: { locale: lng, scope: `app:${app}`, app, missing },
-            });
+    // ① 도메인 — backend 만 정당하다(frontend 가 있으면 로더가 이미 throw).
+    issues.push(...parityIssues(cwd, join(cwd, 'domain', 'locales'), project.domain.backend, project.domain.layout, 'backend', 'domain'));
+    // ②③ 앱별 — frontend·backend 를 **각각** 그 앱 안에서만 비교한다.
+    for (const [app, scoped] of Object.entries(project.apps).sort(([a], [b]) => a.localeCompare(b))) {
+        const dir = join(cwd, 'apps', app, 'locales');
+        for (const scope of ['backend', 'frontend']) {
+            issues.push(...parityIssues(cwd, dir, scoped[scope], scoped.layout, scope, `app:${app}`));
         }
     }
-    return issues;
+    return { rule: 'locale-parity', issues };
 }
 /**
  * 로케일 간 키 diff — 로케일별 "다른 로케일엔 있는데 나에겐 없는 키" 를 낸다.
@@ -123,8 +83,8 @@ function missingByLang(resources) {
     }
     return out;
 }
-/** 한 스코프 안에서 로케일 간 키 diff 를 계산한다(레거시 단일 파일은 backend 스코프에 담긴다). */
-function parityIssues(cwd, localesDir, resources, layout, scope) {
+/** 한 소유자의 한 스코프 안에서 로케일 간 키 diff 를 계산한다(레거시 단일 파일 경로 포함). */
+function parityIssues(cwd, localesDir, resources, layout, scope, owner) {
     const issues = [];
     for (const [lng, missing] of missingByLang(resources)) {
         // 파일 경로는 레이아웃에 맞춘다 — 폴더 분리면 <lng>/<scope>.json, 레거시면 <lng>.json.
@@ -138,11 +98,12 @@ function parityIssues(cwd, localesDir, resources, layout, scope) {
             rule: 'locale-parity',
             level: 'warning',
             file: rel,
-            message: `로케일 '${lng}' 에 다른 로케일엔 있는 키 ${missing.length}개가 빠졌습니다: ${rel}\n` +
+            message: `로케일 '${lng}' 에 같은 스코프의 다른 로케일엔 있는 키 ${missing.length}개가 빠졌습니다: ${rel} (${owner})\n` +
                 `  누락 키: ${list}\n` +
                 `→ ${rel} 에 이 키들을 채우세요 — 없으면 '${lng}' 사용자에게 fallback(대개 다른 언어)\n` +
-                `  번역이 조용히 노출됩니다. messages.d.ts 는 기준 로케일 기준이라 컴파일로 못 잡습니다(결정 216).`,
-            detail: { locale: lng, scope, missing },
+                `  번역이 조용히 노출되거나(서버), 키 문자열이 그대로 뜹니다(클라 · 결정 455).\n` +
+                `  messages.d.ts 는 기준 로케일 기준이라 컴파일로 못 잡습니다(결정 216).`,
+            detail: { locale: lng, scope, owner, missing },
         });
     }
     return issues;

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'agents-docs-stale' | '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' | 'render-return' | 'channel-collision' | 'channel-instance-authorize' | 'dotenv-node-env' | 'page-fetch' | 'i18n-layout' | 'i18n-app-scope';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'agents-docs-stale' | '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' | 'render-return' | 'channel-collision' | 'channel-instance-authorize' | 'dotenv-node-env' | 'page-fetch' | 'i18n-layout' | 'i18n-app-scope' | 'i18n-server-scope';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -27,6 +27,7 @@ export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-bu
 export { checkLocaleParity } from './doctor/locale-parity.js';
 export { checkI18nLayout } from './doctor/i18n-layout.js';
 export { checkI18nAppScope } from './doctor/i18n-app-scope.js';
+export { checkI18nServerScope } from './doctor/i18n-server-scope.js';
 export { checkChannelCollision, reexportSpecifier } from './doctor/channel-collision.js';
 export { checkChannelInstanceAuthorize, declaresInstance, hasAuthorize, } from './doctor/channel-instance-authorize.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
@@ -35,7 +36,7 @@ export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, }
  * 실행할 검사 이름. 지정 없음(undefined) = 31개 모두.
  */
 /**
- * doctor 정적 검사 35종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 36종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 33 검사를 조립한다:
+ * 검사를 조립한다(수는 ALL_RULES 가 단일 출처 — CLI help·AGENTS §2.2 가 그걸 읽는다):
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -30,13 +30,15 @@
  * 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 조용 노출 경고)
- * 34) i18n-layout (결정 454 · 레거시 단일 파일 = 클라 t() 불가 안내 · --fix 로 폴더 이관)
- * 35) i18n-app-scope (결정 454 · 앱 카탈로그에 없는 클라 t() 키 = 런타임 키 노출)
  * 28) render-return (결정 340 · this.render/redirect/json 호출만 하고 return 누락 = 무신호 204 경고)
  * 29) channel-collision (§7 · 앱간 동명 채널 = 전역 subject·프레즌스 병합 error)
  * 30) channel-instance-authorize (결정 440 · authorize 없는 인스턴스 채널 = 임의 인스턴스 공개 입장 경고)
  * 31) dotenv-node-env (결정 430 · 공유 .env 의 NODE_ENV = 모드 누출 경고)
  * 32) page-fetch (결정 453 · 세션 앱 .vue 의 내부 경로 raw fetch = CSRF 미부착 403 경고)
+ * 33) i18n-layout (결정 454·459 · 옛 카탈로그 배치 = 안 읽히는 폴더 안내 · --fix 로 이관)
+ * 34) i18n-app-scope (결정 454·459 · 그 앱 카탈로그에 없는 클라 t() 키 = 런타임 키 노출 ·
+ *     shared/ 가 쓰는 키는 전 앱에 있어야 한다)
+ * 35) i18n-server-scope (결정 459 · 소유자 경계를 넘는 서버 t() 키 = 워커·크론에서 조용히 빔)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -45,9 +47,9 @@
  * 하위 호환: 기존 응답 혼용 API(`inspectControllerSource`·`runDoctor`)는
  * 그대로 export — 기존 테스트가 계속 동작한다.
  */
-import { rename, writeFile } from 'node:fs/promises';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import ts from 'typescript';
 import { checkResponseMixing } from './doctor/response-mixing.js';
 import { checkRenderReturn } from './doctor/render-return.js';
@@ -80,6 +82,7 @@ import { checkNoImportMetaEnv } from './doctor/no-import-meta-env.js';
 import { checkLocaleParity } from './doctor/locale-parity.js';
 import { checkI18nLayout } from './doctor/i18n-layout.js';
 import { checkI18nAppScope } from './doctor/i18n-app-scope.js';
+import { checkI18nServerScope } from './doctor/i18n-server-scope.js';
 import { checkChannelCollision } from './doctor/channel-collision.js';
 import { checkChannelInstanceAuthorize } from './doctor/channel-instance-authorize.js';
 import { checkDotenvNodeEnv } from './doctor/dotenv-node-env.js';
@@ -114,6 +117,7 @@ export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-bu
 export { checkLocaleParity } from './doctor/locale-parity.js';
 export { checkI18nLayout } from './doctor/i18n-layout.js';
 export { checkI18nAppScope } from './doctor/i18n-app-scope.js';
+export { checkI18nServerScope } from './doctor/i18n-server-scope.js';
 export { checkChannelCollision, reexportSpecifier } from './doctor/channel-collision.js';
 export { checkChannelInstanceAuthorize, declaresInstance, hasAuthorize, } from './doctor/channel-instance-authorize.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
@@ -122,7 +126,7 @@ export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, }
  * 실행할 검사 이름. 지정 없음(undefined) = 31개 모두.
  */
 /**
- * doctor 정적 검사 35종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 36종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */
@@ -162,6 +166,7 @@ export const ALL_RULES = [
     'page-fetch',
     'i18n-layout',
     'i18n-app-scope',
+    'i18n-server-scope',
 ];
 /**
  * `gaon help` 이 doctor 한 줄에 요약할 규칙별 문구(§2.2 상세는 AGENTS). 타입이
@@ -199,7 +204,8 @@ export const RULE_SUMMARIES = {
     'no-import-meta-env': 'import.meta.env',
     'locale-parity': '로케일 커버리지',
     'i18n-layout': 'i18n 카탈로그 레이아웃(단일 파일 → backend/frontend 분리 안내 · 결정 454)',
-    'i18n-app-scope': '앱 경계를 넘는 클라 번역 키(그 앱 카탈로그에 없는 t() 키 · 결정 454)',
+    'i18n-app-scope': '앱 경계를 넘는 클라 번역 키(그 앱 카탈로그에 없는 t() 키 · 결정 454·459)',
+    'i18n-server-scope': '소유자 경계를 넘는 서버 번역 키(도메인이 앱 키를 쓰면 워커에서 빔 · 결정 459)',
     'render-return': 'render return 누락',
     'channel-collision': '앱간 동명 채널',
     'channel-instance-authorize': '인스턴스 채널 authorize',
@@ -237,6 +243,7 @@ const CHECKERS = {
     'locale-parity': checkLocaleParity,
     'i18n-layout': checkI18nLayout,
     'i18n-app-scope': checkI18nAppScope,
+    'i18n-server-scope': checkI18nServerScope,
     'render-return': checkRenderReturn,
     'channel-collision': checkChannelCollision,
     'channel-instance-authorize': checkChannelInstanceAuthorize,
@@ -435,6 +442,9 @@ export async function runDoctorFix(reports, cwd, apply) {
                         await writeFile(join(cwd, ref.file), ref.after, 'utf8');
                         backups.push(bak);
                     }
+                    // 이관 대상은 새 폴더일 수 있다(예 locales/ko.json → domain/locales/ko/backend.json)
+                    // — 부모가 없으면 rename 이 ENOENT 로 죽는다(결정 459).
+                    await mkdir(dirname(join(cwd, plan.to)), { recursive: true });
                     await rename(join(cwd, plan.file), join(cwd, plan.to));
                     outcomes.push({
                         rule: report.rule,
@@ -445,17 +455,33 @@ export async function runDoctorFix(reports, cwd, apply) {
                     });
                     continue;
                 }
-                // 내용 재작성 — 원본 백업 먼저.
+                if (plan.kind === 'remove') {
+                    // 결정 459: 원본을 백업한 뒤 지운다(복제가 이미 끝난 이관의 마지막 단계).
+                    const backupRel = `${plan.file}.bak-${ts}`;
+                    await writeFile(join(cwd, backupRel), plan.before, 'utf8');
+                    await rm(join(cwd, plan.file), { force: true });
+                    outcomes.push({
+                        rule: report.rule,
+                        file: plan.file,
+                        summary: plan.summary,
+                        applied: true,
+                        backup: backupRel,
+                    });
+                    continue;
+                }
+                // 내용 재작성 — 원본 백업 먼저. 새 파일(before='')이면 부모 폴더를 만든다.
                 const abs = join(cwd, plan.file);
                 const backupRel = `${plan.file}.bak-${ts}`;
-                await writeFile(join(cwd, backupRel), plan.before, 'utf8');
+                await mkdir(dirname(abs), { recursive: true });
+                if (plan.before !== '')
+                    await writeFile(join(cwd, backupRel), plan.before, 'utf8');
                 await writeFile(abs, plan.after, 'utf8');
                 outcomes.push({
                     rule: report.rule,
                     file: plan.file,
                     summary: plan.summary,
                     applied: true,
-                    backup: backupRel,
+                    backup: plan.before === '' ? undefined : backupRel,
                 });
             }
             catch (err) {

package/dist/i18n-config.d.ts

@@ -1,7 +1,11 @@
 export interface ConfigI18nAnalysis {
     /** defineConfig 인자에 i18n 프로퍼티가 존재하는가. */
     readonly declared: boolean;
-    /** 정적 리터럴로 읽힌 dir(상대 경로 원문). 못 읽으면 undefined. */
+    /**
+     * 결정 459: `i18n.dir` 은 **제거된 설정**이다(카탈로그 위치는 관례 고정). 여기서는
+     * 더 이상 카탈로그를 찾는 데 쓰지 않고, **남아 있으면 doctor 가 error 로 잡기 위해서만**
+     * 읽는다(조용히 무시하면 "설정했는데 왜 안 먹지" 로 시간이 녹는다).
+     */
     readonly dir?: string;
     /** 정적 리터럴로 읽힌 fallbackLng. 못 읽으면 undefined. */
     readonly fallbackLng?: string;
@@ -18,15 +22,11 @@ export interface ConfigI18nAnalysis {
 export declare function analyzeConfigI18n(source: string): ConfigI18nAnalysis;
 /** cwd 의 gaon.config.ts 를 읽어 i18n 블록을 분석한다. 파일이 없으면 미선언. */
 export declare function analyzeProjectI18n(cwd: string): ConfigI18nAnalysis;
-/**
- * 결정 412: 카탈로그 디렉터리의 절대 경로. `dir` 이 절대 경로면 그대로 쓴다 —
- * wire(런타임)는 이미 그렇게 해석하는데 CLI 축만 무조건 join 해서
- * `join('/proj','/var/locales')` = `/proj/var/locales` 로 조용히 빗나갔다.
- */
-export declare function resolveLocalesDir(cwd: string, dir: string | undefined): string;
 /**
  * 결정 412: 정적으로 못 읽은 i18n 키를 한 줄 경고로 알린다(무신호 금지). 런타임은
- * 실값을, 타입 축·doctor 는 폴백을 쓰므로 messages.d.ts 가 엉뚱한 카탈로그를 보거나
- * 아예 안 생길 수 있다 — 어느 형태로 바꾸면 되는지까지 쓴다(§7.5.3).
+ * 실값을, 타입 축·doctor 는 폴백을 쓰므로 messages.d.ts 가 엉뚱한 기준 로케일을 볼 수
+ * 있다 — 어느 형태로 바꾸면 되는지까지 쓴다(§7.5.3).
+ * 결정 459: 카탈로그 **위치**는 관례 고정이라 `dir` 미해석은 더 이상 축을 갈라놓지 않는다
+ * (남아 있는 `dir` 자체는 doctor `i18n-layout` 이 error 로 잡는다) — fallbackLng 만 경고한다.
  */
 export declare function warnUnresolvedI18n(analysis: ConfigI18nAnalysis, write: (s: string) => void): void;

package/dist/i18n-config.js

@@ -133,26 +133,19 @@ export function analyzeProjectI18n(cwd) {
         return { declared: false, unresolved: [] };
     }
 }
-/**
- * 결정 412: 카탈로그 디렉터리의 절대 경로. `dir` 이 절대 경로면 그대로 쓴다 —
- * wire(런타임)는 이미 그렇게 해석하는데 CLI 축만 무조건 join 해서
- * `join('/proj','/var/locales')` = `/proj/var/locales` 로 조용히 빗나갔다.
- */
-export function resolveLocalesDir(cwd, dir) {
-    const d = dir ?? 'locales';
-    return d.startsWith('/') ? d : join(cwd, d);
-}
 /**
  * 결정 412: 정적으로 못 읽은 i18n 키를 한 줄 경고로 알린다(무신호 금지). 런타임은
- * 실값을, 타입 축·doctor 는 폴백을 쓰므로 messages.d.ts 가 엉뚱한 카탈로그를 보거나
- * 아예 안 생길 수 있다 — 어느 형태로 바꾸면 되는지까지 쓴다(§7.5.3).
+ * 실값을, 타입 축·doctor 는 폴백을 쓰므로 messages.d.ts 가 엉뚱한 기준 로케일을 볼 수
+ * 있다 — 어느 형태로 바꾸면 되는지까지 쓴다(§7.5.3).
+ * 결정 459: 카탈로그 **위치**는 관례 고정이라 `dir` 미해석은 더 이상 축을 갈라놓지 않는다
+ * (남아 있는 `dir` 자체는 doctor `i18n-layout` 이 error 로 잡는다) — fallbackLng 만 경고한다.
  */
 export function warnUnresolvedI18n(analysis, write) {
-    if (analysis.unresolved.length === 0)
+    if (!analysis.unresolved.includes('fallbackLng'))
         return;
-    write(`  ! gaon.config.ts 의 i18n ${analysis.unresolved.join('·')} 을(를) 정적으로 읽지 못했습니다 — ` +
-        `타입 축(.gaon/messages.d.ts)과 doctor 는 기본값(dir='locales' · 기준=정렬 첫 로케일)을 씁니다.\n` +
-        `    → 문자열 리터럴로 직접 쓰면 정확히 반영됩니다: i18n: { dir: 'locales', fallbackLng: 'ko' }\n`);
+    write(`  ! gaon.config.ts 의 i18n fallbackLng 를 정적으로 읽지 못했습니다 — ` +
+        `타입 축(.gaon/messages.d.ts)과 doctor 는 기본값(기준=정렬 첫 로케일)을 씁니다.\n` +
+        `    → 문자열 리터럴로 직접 쓰면 정확히 반영됩니다: i18n: { fallbackLng: 'ko' }\n`);
 }
 function isDefineConfig(e) {
     if (ts.isIdentifier(e) && e.text === 'defineConfig')

package/dist/messages-gen.d.ts

@@ -1,27 +1,27 @@
-import { type LocaleResources } from '@gaonjs/i18n';
+import { type ScopedLocaleResources } from '@gaonjs/i18n';
 /** 메시지 축이 카탈로그 모듈을 낼 앱(결정 454). dev 레이아웃이 만들어 넘긴다. */
 export interface MessagesApp {
     readonly name: string;
-    /** apps/<앱>/locales (앱 전용 frontend 카탈로그 · 없어도 된다). */
+    /** apps/<앱>/locales (그 앱의 스코프 카탈로그 · 없어도 된다). */
     readonly localesDir: string;
     /** apps/<앱>/.gaon/messages.catalog.ts */
     readonly catalogOut: string;
 }
 /**
- * locales/ 카탈로그에서 `.gaon/messages.d.ts`(두 갈래)와 앱별 카탈로그 값 모듈을 생성한다.
- * 카탈로그가 없거나 비면 생성하지 않는다(GaonMessages 를 비운 채로 둬 키가 string 폴백 —
- * i18n 을 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
+ * 프로젝트 카탈로그(domain/locales · apps/*&#47;locales)에서 `.gaon/messages.d.ts`(두 갈래)와
+ * 앱별 카탈로그 값 모듈을 생성한다. 카탈로그가 없거나 비면 생성하지 않는다(GaonMessages 를
+ * 비운 채로 둬 키가 string 폴백 — i18n 을 안 쓰는 프로젝트가 never 로 깨지지 않게).
+ * 생성 여부를 돌려준다.
  */
-export declare function generateMessagesDts(localesDir: string, out: string, baseLng?: string, apps?: readonly MessagesApp[]): boolean;
+export declare function generateMessagesDts(root: string, out: string, baseLng?: string, apps?: readonly MessagesApp[]): boolean;
 interface CatalogInput {
-    readonly localesDir: string;
     readonly app: MessagesApp;
-    readonly appLocales: LocaleResources;
-    readonly frontendLangs: readonly string[];
+    /** 그 앱의 스코프 카탈로그(없으면 undefined = locales 폴더 부재). */
+    readonly appScoped: ScopedLocaleResources | undefined;
     readonly fallbackLng: string;
 }
 /**
- * 결정 454: 앱별 카탈로그 값 모듈을 쓴다. 로케일별 로더가 **공용 frontend + 앱 카탈로그**를
+ * 결정 454·459: 앱별 카탈로그 값 모듈을 쓴다. 로케일별 로더가 **그 앱의 frontend.json 하나**를
  * 동적 import 해 vite 가 로케일별 해시 청크(.js)로 쪼갠다 — `/assets/*` immutable 캐시 대상이며
  * `text/javascript` 라 seal 봉인 대상(application/json)에서 자연 면제된다.
  * 생성 여부를 돌려준다(프론트 카탈로그가 없으면 false + 스테일 제거).

package/dist/messages-gen.js

@@ -1,19 +1,23 @@
-// @gaonjs/cli · .gaon 메시지 축 생성기 (결정 158 · 13차 W2 · 결정 454)
+// @gaonjs/cli · .gaon 메시지 축 생성기 (결정 158 · 13차 W2 · 결정 454 · 459)
 //
-// tables.d.ts·routes.d.ts 와 같은 .gaon 파이프라인의 메시지 축. 결정 454 부터 두 산출을 낸다:
+// tables.d.ts·routes.d.ts 와 같은 .gaon 파이프라인의 메시지 축. 두 산출을 낸다:
 //
-//  1) `.gaon/messages.d.ts` — **두 갈래 타입 브리지**
-//     · `gaonjs/i18n`(서버) = backend ∪ frontend ∪ 앱 frontend
-//     · `gaonjs/vue`(클라)  = frontend 만(+ 키별 보간 파라미터) → 서버 전용 문구를
+//  1) `.gaon/messages.d.ts` — **두 갈래 타입 브리지**(루트 단일 · 결정 459 O7)
+//     · `gaonjs/i18n`(서버) = domain-backend ∪ 전 앱 backend ∪ 전 앱 frontend
+//     · `gaonjs/vue`(클라)  = 전 앱 frontend 만(+ 키별 보간 파라미터) → 서버 전용 문구를
 //       클라에서 참조하면 컴파일 에러.
+//     유니온이 **프로젝트 전역**인 것은 타협이 아니라 제약이다 — 앱마다 다른 유니온으로
+//     `GaonMessages.keys` 를 augment 하면 TS2717(결정 454 실측 · 결정 459 §5.1 로 유효).
+//     앱 경계는 ① 번들 물리 경계 ② doctor(i18n-app-scope·i18n-server-scope)가 강제한다.
 //  2) `apps/<앱>/.gaon/messages.catalog.ts` — **앱별 값 모듈**(routes.manifest.ts 선례).
 //     그 앱의 frontend 카탈로그만 동적 import 로 묶어 vite 가 로케일별 청크로 쪼갠다.
 //     backend.json 은 입력에 아예 없다(노출 차단은 번들 경계가 물리적으로 강제).
+//     결정 459: 공용 스코프가 사라져 **로케일당 소스가 정확히 하나**다.
 //
-// @gaonjs/i18n 의 공개 API(loadScopedLocales·loadAppLocales·renderMessagesDtsSplit 등)만 쓴다.
+// @gaonjs/i18n 의 공개 API(loadProjectLocales·renderMessagesDtsSplit 등)만 쓴다.
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, sep } from 'node:path';
-import { extractParams, flattenKeys, loadAppLocales, loadScopedLocales, renderMessagesDtsSplit, withPluralBaseKeys, } from '@gaonjs/i18n';
+import { extractParams, flattenKeys, loadProjectLocales, projectLanguages, renderMessagesDtsSplit, withPluralBaseKeys, } from '@gaonjs/i18n';
 /** 번역 트리 두 개를 깊은 병합한다(리프 충돌은 로더가 이미 fail-loud). */
 function mergeTrees(a, b) {
     const out = { ...a };
@@ -36,42 +40,35 @@ function pickBaseLng(langs, baseLng) {
     return [...langs].sort()[0];
 }
 /**
- * locales/ 카탈로그에서 `.gaon/messages.d.ts`(두 갈래)와 앱별 카탈로그 값 모듈을 생성한다.
- * 카탈로그가 없거나 비면 생성하지 않는다(GaonMessages 를 비운 채로 둬 키가 string 폴백 —
- * i18n 을 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
+ * 프로젝트 카탈로그(domain/locales · apps/*&#47;locales)에서 `.gaon/messages.d.ts`(두 갈래)와
+ * 앱별 카탈로그 값 모듈을 생성한다. 카탈로그가 없거나 비면 생성하지 않는다(GaonMessages 를
+ * 비운 채로 둬 키가 string 폴백 — i18n 을 안 쓰는 프로젝트가 never 로 깨지지 않게).
+ * 생성 여부를 돌려준다.
  */
-export function generateMessagesDts(localesDir, out, baseLng, apps = []) {
+export function generateMessagesDts(root, out, baseLng, apps = []) {
+    const project = loadProjectLocales(root);
+    const langs = projectLanguages(project);
     // 결정 414: 카탈로그가 사라졌으면 **옛 생성물을 지운다** — 남겨두면 없어진 키의
     // 유니온이 그대로 살아 t('없어진키') 가 계속 컴파일된다(제거를 못 잡는 사각).
-    if (!existsSync(localesDir)) {
+    if (langs.length === 0) {
         if (existsSync(out))
             rmSync(out, { force: true });
         for (const app of apps)
             removeStale(app.catalogOut);
         return false;
     }
-    const scoped = loadScopedLocales(localesDir);
-    const appResources = new Map();
-    for (const app of apps)
-        appResources.set(app.name, loadAppLocales(app.localesDir));
-    const langs = new Set([...Object.keys(scoped.backend), ...Object.keys(scoped.frontend)]);
-    for (const res of appResources.values())
-        for (const lng of Object.keys(res))
-            langs.add(lng);
-    if (langs.size === 0) {
-        if (existsSync(out))
-            rmSync(out, { force: true });
-        for (const app of apps)
-            removeStale(app.catalogOut);
-        return false;
+    const base = pickBaseLng(langs, baseLng);
+    // 결정 459: 클라 키 = **전 앱 frontend 합집합**(공용 스코프는 폐지됐다). 앱×앱 축을
+    // 타입으로 못 나누는 것은 TS2717 제약이라 그대로다 — 경계는 청크 분리와 doctor 가 강제한다.
+    let clientTree = {};
+    let appBackendTree = {};
+    for (const scoped of Object.values(project.apps)) {
+        clientTree = mergeTrees(clientTree, translationOf(scoped.frontend, base));
+        appBackendTree = mergeTrees(appBackendTree, translationOf(scoped.backend, base));
     }
-    const base = pickBaseLng([...langs], baseLng);
-    // 클라 키 = 공용 frontend ∪ 모든 앱 frontend(결정 454 · 앱×앱 축은 타입으로 못 나눈다 —
-    // TS2717. 앱 경계는 청크 분리와 doctor `i18n-app-scope` 가 강제한다).
-    let clientTree = translationOf(scoped.frontend, base);
-    for (const res of appResources.values())
-        clientTree = mergeTrees(clientTree, translationOf(res, base));
-    const serverTree = mergeTrees(translationOf(scoped.backend, base), clientTree);
+    // 서버 키 = domain-backend ∪ 전 앱 backend ∪ 전 앱 frontend(결정 459 O5 — 서버는
+    // 화면 문구도 볼 수 있다: SSR·로그·관리 스크립트 경로를 좁히지 않는다).
+    const serverTree = mergeTrees(mergeTrees(translationOf(project.domain.backend, base), appBackendTree), clientTree);
     const clientKeys = withPluralBaseKeys(flattenKeys(clientTree));
     const serverKeys = withPluralBaseKeys(flattenKeys(serverTree));
     mkdirSync(dirname(out), { recursive: true });
@@ -81,14 +78,12 @@ export function generateMessagesDts(localesDir, out, baseLng, apps = []) {
         clientKeys,
         clientParams: extractParams(clientTree),
     }), 'utf8');
-    // 앱별 카탈로그 값 모듈 — frontend 소스가 하나도 없으면 만들지 않는다(레거시 레이아웃).
+    // 앱별 카탈로그 값 모듈 — 그 앱에 frontend 소스가 없으면 만들지 않는다.
     const fallback = base ?? 'en';
     for (const app of apps) {
         generateMessagesCatalog({
-            localesDir,
             app,
-            appLocales: appResources.get(app.name) ?? {},
-            frontendLangs: Object.keys(scoped.frontend),
+            appScoped: project.apps[app.name],
             fallbackLng: fallback,
         });
     }
@@ -104,40 +99,33 @@ function importPath(fromDir, target) {
     return rel.startsWith('.') ? rel : `./${rel}`;
 }
 /**
- * 결정 454: 앱별 카탈로그 값 모듈을 쓴다. 로케일별 로더가 **공용 frontend + 앱 카탈로그**를
+ * 결정 454·459: 앱별 카탈로그 값 모듈을 쓴다. 로케일별 로더가 **그 앱의 frontend.json 하나**를
  * 동적 import 해 vite 가 로케일별 해시 청크(.js)로 쪼갠다 — `/assets/*` immutable 캐시 대상이며
  * `text/javascript` 라 seal 봉인 대상(application/json)에서 자연 면제된다.
  * 생성 여부를 돌려준다(프론트 카탈로그가 없으면 false + 스테일 제거).
  */
 export function generateMessagesCatalog(input) {
     const outDir = dirname(input.app.catalogOut);
-    const langs = [...new Set([...input.frontendLangs, ...Object.keys(input.appLocales)])].sort();
+    const frontend = input.appScoped?.frontend ?? {};
+    const langs = Object.keys(frontend).sort();
     if (langs.length === 0) {
         removeStale(input.app.catalogOut);
         return false;
     }
     const lines = [];
     lines.push('// AUTO-GENERATED by @gaonjs/cli — 편집 금지.');
-    lines.push('// `gaon check` / `gaon dev` / `gaon gen` 가 이 파일을 재생성한다(결정 454).');
-    lines.push('// 클라이언트 번역 카탈로그: 로케일 → 로더(공용 frontend + 이 앱의 카탈로그).');
-    lines.push('// 서버 전용 문구(locales/<로케일>/backend.json)는 여기에 실리지 않는다 — 클라로 나가지 않는다.');
+    lines.push('// `gaon check` / `gaon dev` / `gaon gen` 가 이 파일을 재생성한다(결정 454 · 459).');
+    lines.push('// 클라이언트 번역 카탈로그: 로케일 → 로더(이 앱의 frontend.json).');
+    lines.push('// 서버 전용 문구(backend.json)는 여기에 실리지 않는다 — 클라로 나가지 않는다.');
     lines.push("import type { CatalogLoaders } from 'gaonjs/vue'");
     lines.push('');
     lines.push('export const catalogs: CatalogLoaders = {');
     for (const lng of langs) {
-        const sources = [];
-        const shared = join(input.localesDir, lng, 'frontend.json');
-        if (existsSync(shared))
-            sources.push(importPath(outDir, shared));
-        const appFile = join(input.app.localesDir, `${lng}.json`);
-        if (input.appLocales[lng] !== undefined && existsSync(appFile))
-            sources.push(importPath(outDir, appFile));
-        if (sources.length === 0)
+        // 결정 459: 로케일당 소스가 정확히 하나다(공용 스코프 폐지) — 다중 import 분기가 없다.
+        const file = join(input.app.localesDir, lng, 'frontend.json');
+        if (!existsSync(file))
             continue;
-        const body = sources.length === 1
-            ? `import('${sources[0]}')`
-            : `Promise.all([${sources.map((s) => `import('${s}')`).join(', ')}])`;
-        lines.push(`  '${lng}': () => ${body},`);
+        lines.push(`  '${lng}': () => import('${importPath(outDir, file)}'),`);
     }
     lines.push('}');
     lines.push('');

package/dist/scaffold/app.d.ts

@@ -1,5 +1,14 @@
 import type { ScaffoldFile } from './controller.js';
 /** 이름 유효성 — apps/<name>/ 이 안전하고 URL 프리픽스로도 무리 없는 부분집합. */
 export declare function validateAppName(name: string): void;
+/** 앱 스캐폴드 옵션. */
+export interface AppScaffoldOptions {
+    /**
+     * 결정 459: i18n 을 쓰는 프로젝트의 기준 로케일. 주면 그 앱의 **필수** frontend
+     * 카탈로그(`apps/<앱>/locales/<로케일>/frontend.json`)를 함께 만든다. 생략 =
+     * i18n 미사용 프로젝트라 카탈로그를 만들지 않는다.
+     */
+    readonly fallbackLng?: string;
+}
 /** 앱 스캐폴드 파일 계획. 순수 함수 — 실제 쓰기는 writeScaffold 가 담당. */
-export declare function appScaffoldFiles(name: string): ScaffoldFile[];
+export declare function appScaffoldFiles(name: string, options?: AppScaffoldOptions): ScaffoldFile[];

package/dist/scaffold/app.js

@@ -47,7 +47,7 @@ export function validateAppName(name) {
     }
 }
 /** 앱 스캐폴드 파일 계획. 순수 함수 — 실제 쓰기는 writeScaffold 가 담당. */
-export function appScaffoldFiles(name) {
+export function appScaffoldFiles(name, options = {}) {
     validateAppName(name);
     const files = [];
     // 1) routes.ts — 관례상 GET / + /health 두 라우트로 시작한다.
@@ -160,7 +160,17 @@ export function appScaffoldFiles(name) {
             ``,
         ].join('\n'),
     });
-    // 6-8) 관례 폴더 유지 — git 이 빈 폴더를 추적하지 않아 .gitkeep 을 둔다.
+    // 6) locales/<로케일>/frontend.json — 결정 459: **화면 문구의 소유자는 그 앱**이다.
+    //    frontend 카탈로그는 앱마다 필수라 스캐폴드가 자리를 만들어 둔다(빈 파일이 아니라
+    //    실제로 쓰이는 키 하나를 둬야 "여기에 넣으면 되는구나" 가 보인다). 서버 문구가
+    //    필요해지면 같은 폴더에 backend.json 을 추가한다(선택).
+    if (options.fallbackLng) {
+        files.push({
+            path: `apps/${name}/locales/${options.fallbackLng}/frontend.json`,
+            contents: `${JSON.stringify({ nav: { home: name } }, null, 2)}\n`,
+        });
+    }
+    // 7-9) 관례 폴더 유지 — git 이 빈 폴더를 추적하지 않아 .gitkeep 을 둔다.
     //     components · composables · channels 는 앱이 클수록 자주 채워지는
     //     세 자리다(E-5 §2.2 · M6 실시간).
     for (const sub of ['components', 'composables', 'channels']) {