@gaonjs/cli 0.47.0 → 0.55.0

package/dist/generate.js

@@ -65,6 +65,14 @@ function devSessionSecretFor(app) {
 function envSecretPlaceholderFor(app) {
     return `change-me-to-a-32-char-${app}-session-secret!!`;
 }
+/** 결정 338: 앱별 JWT secret 환경변수명 — '<APP>_JWT_SECRET' (세션 secret 관례와 대칭). */
+function jwtSecretEnvFor(app) {
+    return `${app.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_JWT_SECRET`;
+}
+/** .env(.example)에 시드할 앱별 JWT secret 플레이스홀더(32자 이상 · 운영은 교체 — 결정 337 가드 대상). */
+function envJwtPlaceholderFor(app) {
+    return `change-me-to-a-32-char-${app}-jwt-secret!!!`;
+}
 /**
  * 결정 155·142: `g auth --app <앱>` 이 앱별 세션 secret 환경변수를 .env·.env.example
  * 에도 시드한다. web 은 SESSION_SECRET 이 프로젝트 스캐폴드(.env.example.tpl)에 이미
@@ -77,8 +85,13 @@ function envSecretPlaceholderFor(app) {
  * .env 를 새로 만드는 관례가 없어(사용자가 cp .env.example .env), 존재하는 파일만 패치한다.
  * 반환: 실제로 키를 추가한 상대 경로들.
  */
-export function patchEnvFiles(root, app) {
-    const secretEnv = sessionSecretEnvFor(app);
+export function patchEnvFiles(root, app, kind = 'session') {
+    // 결정 338: JWT 변형은 세션 secret 대신 <APP>_JWT_SECRET 을 시드한다(동일 멱등 규칙).
+    const secretEnv = kind === 'jwt' ? jwtSecretEnvFor(app) : sessionSecretEnvFor(app);
+    const comment = kind === 'jwt'
+        ? `# ${app} 앱 JWT secret (32자 이상 · 앱별 분리 · 운영은 반드시 교체 — dev 폴백은 부팅 거부 · 결정 337).`
+        : `# ${app} 앱 세션 secret (32자 이상 · 앱별 세션 완전 분리 · 운영은 반드시 교체).`;
+    const placeholder = kind === 'jwt' ? envJwtPlaceholderFor(app) : envSecretPlaceholderFor(app);
     const patched = [];
     for (const rel of ['.env', '.env.example']) {
         const abs = join(root, rel);
@@ -88,8 +101,7 @@ export function patchEnvFiles(root, app) {
         // 라인 시작에서 `KEY=` 를 찾는다(주석·부분 일치 회피).
         if (new RegExp(`^${secretEnv}=`, 'm').test(existing))
             continue;
-        const block = `\n# ${app} 앱 세션 secret (32자 이상 · 앱별 세션 완전 분리 · 운영은 반드시 교체).\n` +
-            `${secretEnv}=${envSecretPlaceholderFor(app)}\n`;
+        const block = `\n${comment}\n${secretEnv}=${placeholder}\n`;
         const sep = existing.endsWith('\n') ? '' : '\n';
         writeFileSync(abs, existing + sep + block, 'utf8');
         patched.push(rel);
@@ -113,6 +125,7 @@ function renderTemplate(name, app, includePublic) {
         .replaceAll('{{APP_NAME}}', app)
         .replaceAll('{{URL_PREFIX}}', urlPrefixFor(app))
         .replaceAll('{{SESSION_SECRET_ENV}}', sessionSecretEnvFor(app))
+        .replaceAll('{{JWT_SECRET_ENV}}', jwtSecretEnvFor(app))
         // 결정 218: 시큐어 세션 컨트롤러의 로그인 역할 게이트 기준. 결정 155·145 의 대시보드
         // 역할 게이트(role === 'admin')와 같은 값으로 고정해 두 층이 어긋나지 않게 한다.
         .replaceAll('{{REQUIRED_ROLE}}', 'admin')
@@ -123,6 +136,18 @@ function renderTemplate(name, app, includePublic) {
 export function authScaffoldFiles(opts = {}) {
     const app = opts.app ?? 'web';
     const includePublic = includesPublicRegistration(opts);
+    // 결정 338: JWT(API 앱) 변형 — 페이지·UI 킷·회원가입 없이 스키마/모델(공유) +
+    // 토큰 컨트롤러(JSON 전용) + auth.strategy:'jwt' 배선만. API 앱은 프론트가 없다.
+    if (opts.jwt) {
+        const specs = [
+            { tpl: 'user.schema.ts.tpl', out: 'domain/schema/users.ts' },
+            { tpl: 'user.model.ts.tpl', out: 'domain/models/User.ts' },
+            { tpl: 'jwt.auth.wiring.ts.tpl', out: `apps/${app}/auth.ts` },
+            { tpl: 'jwt.session.controller.ts.tpl', out: `apps/${app}/controllers/session.ts` },
+            { tpl: 'jwt.app.config.ts.tpl', out: `apps/${app}/app.config.ts` },
+        ];
+        return specs.map(({ tpl, out }) => ({ path: out, contents: renderTemplate(tpl, app, false) }));
+    }
     const specs = [
         { tpl: 'user.schema.ts.tpl', out: 'domain/schema/users.ts' },
         { tpl: 'user.model.ts.tpl', out: 'domain/models/User.ts' },
@@ -157,6 +182,22 @@ export function authScaffoldFiles(opts = {}) {
  * 기존 routes.ts 에 세션·회원가입 리소스를 끼워 넣는다. 이미 있으면 null.
  * `routes((r) => {` 콜백 여는 지점 뒤에 두 줄을 삽입한다.
  */
+/**
+ * 결정 338: 기존 routes.ts 에 JWT 토큰 라우트 3종을 끼워 넣는다. 이미 session#create
+ * 참조가 있으면 null(중복 방지). 삽입 지점 규칙은 patchRoutes 와 동일.
+ */
+export function patchRoutesJwt(existing) {
+    if (existing.includes("'session#create'") || existing.includes("resource('session')"))
+        return null;
+    const m = existing.match(/routes\(\s*\(\s*\w+\s*\)\s*=>\s*\{/);
+    if (!m || m.index === undefined)
+        return null;
+    const insertAt = m.index + m[0].length;
+    const inject = "\n  r.post('/session', 'session#create') // 로그인 → 토큰 발급 (gaon g auth --jwt)" +
+        "\n  r.post('/session/refresh', 'session#refresh') // 액세스 토큰 재발급 (gaon g auth --jwt)" +
+        "\n  r.get('/session', 'session#show') // 현재 사용자 · Bearer (gaon g auth --jwt)";
+    return existing.slice(0, insertAt) + inject + existing.slice(insertAt);
+}
 export function patchRoutes(existing, includePublic = true) {
     if (existing.includes("resource('session')"))
         return null;
@@ -225,17 +266,35 @@ export function writeAuthScaffold(cwd, opts = {}) {
     const skipped = [];
     const patched = [];
     const warnings = [];
+    let incomplete = false;
     // 결정 75: auth 페이지(Login/Signup/Dashboard)는 UI 킷 컴포넌트를 쓴다.
     // 필요한 최소 세트를 먼저 보장한다 — 이미 있으면(gaon g ui-kit 를 먼저 돌린
     // 경우) skip, 없으면 생성. 이 보장이 없으면 스캐폴드 직후 페이지가 컴포넌트를
     // 해상하지 못해 vue-tsc 가 깨진다(gaon new → g auth 단독 경로 · 결정 60 게이트).
     const includePublic = includesPublicRegistration(opts);
-    const ui = writeUiKitFiles(root, authUiKitFiles(app));
-    created.push(...ui.created);
-    skipped.push(...ui.skipped);
+    // 결정 338: JWT 변형은 프론트가 없다(API 앱 · JSON 전용) — UI 킷을 깔지 않는다.
+    if (!opts.jwt) {
+        const ui = writeUiKitFiles(root, authUiKitFiles(app));
+        created.push(...ui.created);
+        skipped.push(...ui.skipped);
+    }
     for (const file of authScaffoldFiles(opts)) {
         const abs = join(root, file.path);
         if (existsSync(abs)) {
+            // 결정 338: JWT 변형의 app.config 자동 패치는 지원하지 않는다(세션 병존 등
+            // 판단이 필요) — 이미 있으면 skip + 수리 안내로 폴백한다.
+            if (opts.jwt && file.path === `apps/${app}/app.config.ts`) {
+                const existing = readFileSync(abs, 'utf8');
+                skipped.push(file.path);
+                if (!/\bauth\s*:/.test(existing)) {
+                    incomplete = true;
+                    warnings.push(`apps/${app}/app.config.ts 가 이미 있어 JWT 인증 배선을 자동 추가하지 못했습니다.\n` +
+                        `→ defineAppConfig({...}) 에 다음을 추가하세요 (import { loadUser } from './auth.js'):\n` +
+                        `   auth: { strategy: 'jwt', secret: process.env.${jwtSecretEnvFor(app)} ?? '32자 이상 dev 비밀', loadUser },\n` +
+                        `→ secret 은 32자 이상 · 운영은 .env 의 ${jwtSecretEnvFor(app)} 로 주입해야 부팅합니다(결정 337).`);
+                }
+                continue;
+            }
             // 결정 93: gaon new 기본 web 앱은 app.config.ts 에 세션만 배선돼 있다.
             // g auth 는 이를 skip 하지 않고 **auth 배선을 패치로 추가**해 완성한다 —
             // 결정 59: auth 배선이 없으면 로그인 후에도 currentUser 가 영구 null 이다.
@@ -249,6 +308,7 @@ export function writeAuthScaffold(cwd, opts = {}) {
                 else if (!/\bauth\s*:/.test(existing)) {
                     // 패치 불가(비관례 config) — skip + 수리 안내로 폴백.
                     skipped.push(file.path);
+                    incomplete = true;
                     warnings.push(`apps/${app}/app.config.ts 가 이미 있어 인증 배선을 자동 추가하지 못했습니다.\n` +
                         `→ apps/${app}/app.config.ts 의 defineAppConfig({...}) 에 다음을 추가하세요:\n` +
                         `   session: { secret: process.env.${sessionSecretEnvFor(app)} ?? '32자 이상 비밀' },\n` +
@@ -268,31 +328,45 @@ export function writeAuthScaffold(cwd, opts = {}) {
         writeFileSync(abs, file.contents, 'utf8');
         created.push(file.path);
     }
-    // routes.ts — 있으면 패치, 없으면 템플릿에서 생성.
+    // routes.ts — 있으면 패치, 없으면 템플릿에서 생성. JWT 변형은 토큰 라우트 3종(결정 338).
     const routesPath = join(root, 'apps', app, 'routes.ts');
     const routesRel = `apps/${app}/routes.ts`;
     if (existsSync(routesPath)) {
-        const patchedContent = patchRoutes(readFileSync(routesPath, 'utf8'), includePublic);
+        const existing = readFileSync(routesPath, 'utf8');
+        const patchedContent = opts.jwt ? patchRoutesJwt(existing) : patchRoutes(existing, includePublic);
         if (patchedContent) {
             writeFileSync(routesPath, patchedContent, 'utf8');
             patched.push(routesRel);
         }
+        else if (existing.includes("resource('session')") || existing.includes("'session#create'")) {
+            skipped.push(routesRel); // 이미 배선 — 정상 멱등.
+        }
         else {
+            // 결정 361: routes( ... ) 골격을 못 찾아 패치 불가 — 인증 라우트가 등록되지 않는다.
             skipped.push(routesRel);
+            incomplete = true;
+            warnings.push(`apps/${app}/routes.ts 가 관례 골격(routes((r) => { ... }))이 아니어서 인증 라우트를 자동 추가하지 못했습니다.\n` +
+                `→ apps/${app}/routes.ts 에 ${opts.jwt ? "r.post('/session', 'session#create') 등 토큰 라우트 3종" : "r.resource('session') 및 r.get('/dashboard', 'dashboard#show')"} 를 직접 추가하세요.`);
         }
     }
     else {
         mkdirSync(dirname(routesPath), { recursive: true });
-        writeFileSync(routesPath, renderTemplate('routes.ts.tpl', app, includePublic), 'utf8');
+        writeFileSync(routesPath, renderTemplate(opts.jwt ? 'jwt.routes.ts.tpl' : 'routes.ts.tpl', app, includePublic), 'utf8');
         created.push(routesRel);
     }
-    // 결정 155·142(W3): 앱별 세션 secret 을 .env·.env.example 에 시드한다. web 은 이미
-    // 있어 멱등, 비-web 앱은 여기서 키가 심어져 "공개 고정 dev secret 폴백" 표면을 막는다.
-    patched.push(...patchEnvFiles(root, app));
+    // 결정 155·142(W3)·338: 앱별 secret 을 .env·.env.example 에 시드한다(세션 또는 JWT).
+    // web 은 이미 있어 멱등, 비-web 앱은 여기서 키가 심어져 dev 폴백 표면을 드러낸다.
+    patched.push(...patchEnvFiles(root, app, opts.jwt ? 'jwt' : 'session'));
+    // 결정 338: JWT 변형의 stateless 한계를 스캐폴드 시점에 명시한다(§7.5.3).
+    if (opts.jwt) {
+        warnings.push(`JWT 토큰은 stateless 입니다 — 서버측 폐기(로그아웃·강제 무효화) 수단이 없습니다(결정 337).\n` +
+            `→ 유출된 리프레시 토큰은 만료(기본 7d)까지 유효합니다. 민감한 앱은 app.config 의 refreshTtl 을 짧게 잡으세요.\n` +
+            `→ 사용자 계정은 이 API 앱에 회원가입이 없습니다 — web 앱 가입(gaon g auth) 또는 seed 로 만드세요.`);
+    }
     // 결정 155·218: 시큐어 앱(공개 가입 미생성)은 로그인 시점 역할 게이트 세션 컨트롤러 +
     // 역할 게이트 대시보드를 깔았다 — 두 층 다 role 컬럼이 있어야 동작하므로 추가를 안내한다
     // (§7.5.3 · authorize·로그인 게이트 예시가 실제 역할 규칙이 되도록).
-    if (!includePublic) {
+    if (!includePublic && !opts.jwt) {
         warnings.push(`apps/${app}/ 는 시큐어 스캐폴드입니다(공개 회원가입 미생성 · 결정 155·218).\n` +
             `→ 관리자는 직접 만들거나 승격하세요(공개 가입 라우트 없음). 공개 가입이 필요하면 --public 로 다시 생성.\n` +
             `→ 역할 인가를 완성하려면 domain/schema/users.ts 에 role 컬럼을 추가하세요:\n` +
@@ -300,20 +374,33 @@ export function writeAuthScaffold(cwd, opts = {}) {
             `   그러면 로그인(controllers/session.ts)이 역할 부족 시 세션을 만들지 않고,\n` +
             `   apps/${app}/controllers/dashboard.ts 의 authorize(역할) 게이트도 실제 역할로 동작합니다.`);
     }
-    return { created: created.sort(), skipped: skipped.sort(), patched: patched.sort(), warnings };
+    return { created: created.sort(), skipped: skipped.sort(), patched: patched.sort(), warnings, incomplete };
 }
 /** `gaon g auth` 진입점. 스캐폴드를 쓰고 결과를 사람/JSON 으로 출력한다. */
 export function runGenerateAuthCommand(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const app = opts.app ?? 'web';
-    const result = writeAuthScaffold(cwd, { app, public: opts.public });
+    // 결정 338: JWT 는 API 앱 전용(§7 · web 은 세션이 정본). 형식 불량은 즉시 수리 안내.
+    if (opts.jwt && (opts.app === undefined || app === 'web')) {
+        process.stderr.write(`  ✗ gaon g auth --jwt: JWT 는 API 앱 전용입니다 — 대상 API 앱을 --app 으로 지정하세요(web 불가 · 세션이 정본).\n` +
+            `  → 예: gaon g app api && gaon g auth --jwt --app api\n`);
+        return 1;
+    }
+    if (opts.jwt && opts.public) {
+        process.stderr.write(`  ✗ gaon g auth --jwt: --public 은 세션 스캐폴드 전용입니다 — JWT 변형은 회원가입을 깔지 않습니다(계정은 web 가입 또는 seed).\n`);
+        return 1;
+    }
+    const result = writeAuthScaffold(cwd, { app, public: opts.public, jwt: opts.jwt });
+    // 결정 361: 배선 미완(incomplete)은 성공이 아니다 — 이전엔 무조건 exit 0 이라
+    // 자동화가 "currentUser 영구 null" 스캐폴드를 성공으로 처리했다(g controller 의
+    // skip=1 과도 비대칭). JSON 은 ok 필드로, 종료 코드는 1 로 신호한다.
     if (opts.json) {
-        process.stdout.write(JSON.stringify({ command: 'g auth', app, public: opts.public ?? app === 'web', ...result }, null, 2) + '\n');
-        return 0;
+        process.stdout.write(JSON.stringify({ command: 'g auth', ok: !result.incomplete, app, jwt: opts.jwt ?? false, public: opts.jwt ? false : (opts.public ?? app === 'web'), ...result }, null, 2) + '\n');
+        return result.incomplete ? 1 : 0;
     }
-    const includePublic = includesPublicRegistration({ app, public: opts.public });
+    const includePublic = !opts.jwt && includesPublicRegistration({ app, public: opts.public });
     const lines = [''];
-    lines.push(`  gaon g auth — 인증 스캐폴드 (${app} 앱)`);
+    lines.push(`  gaon g auth — 인증 스캐폴드 (${app} 앱${opts.jwt ? ' · JWT/API 변형' : ''})`);
     lines.push('');
     for (const f of result.created)
         lines.push(`   + ${f}`);
@@ -327,6 +414,18 @@ export function runGenerateAuthCommand(opts = {}) {
         lines.push('', `  ⚠ ${w.split('\n').join('\n  ')}`);
     lines.push('');
     const prefix = urlPrefixFor(app);
+    // 결정 338: JWT 변형은 다음 단계가 토큰 흐름이다(세션·Redis 불요 — 토큰 stateless).
+    if (opts.jwt) {
+        const jwtEnv = jwtSecretEnvFor(app);
+        lines.push('  다음 단계:');
+        lines.push(`   1) .env 에 ${jwtEnv}(32자 이상 무작위)를 설정한다 — 운영은 dev 폴백이면 부팅 거부(결정 337).`);
+        lines.push('   2) gaon db diff && gaon db migrate 로 users 테이블을 만든다.');
+        lines.push('   3) gaon dev 로 실행한다 (.gaon 타입 브리지 생성 + JWT 인증 자동 배선).');
+        lines.push(`   → POST ${prefix}/session 로그인(토큰 발급) · POST ${prefix}/session/refresh 재발급 · GET ${prefix}/session 현재 사용자(Bearer).`);
+        lines.push('');
+        process.stdout.write(lines.join('\n') + '\n');
+        return result.incomplete ? 1 : 0; // 결정 361
+    }
     const secretEnv = sessionSecretEnvFor(app);
     lines.push('  다음 단계:');
     lines.push(`   1) .env 에 REDIS_URL·${secretEnv}(32자 이상)·COOKIE_SECRET 을 설정한다.`);
@@ -345,5 +444,5 @@ export function runGenerateAuthCommand(opts = {}) {
     }
     lines.push('');
     process.stdout.write(lines.join('\n') + '\n');
-    return 0;
+    return result.incomplete ? 1 : 0; // 결정 361
 }

package/dist/hub.js

@@ -62,6 +62,8 @@ export async function runHubCommand(opts = {}) {
             pingTimeoutMs: opts.pingTimeoutMs ?? envInt('GAON_HUB_PING_TIMEOUT_MS'),
             sweepMs: opts.sweepMs ?? envInt('GAON_HUB_SWEEP_MS'),
             reclaimGraceMs: envInt('GAON_HUB_RECLAIM_GRACE_MS'),
+            // 결정 350: 공유 토큰(선택). 설정 시 웹서버(serve)도 같은 GAON_HUB_TOKEN 필요.
+            authToken: process.env.GAON_HUB_TOKEN,
             onState: (s) => emit({ kind: 'leader', leader: s.leader, id }),
         });
     }

package/dist/i18n-config.d.ts

@@ -0,0 +1,32 @@
+export interface ConfigI18nAnalysis {
+    /** defineConfig 인자에 i18n 프로퍼티가 존재하는가. */
+    readonly declared: boolean;
+    /** 정적 리터럴로 읽힌 dir(상대 경로 원문). 못 읽으면 undefined. */
+    readonly dir?: string;
+    /** 정적 리터럴로 읽힌 fallbackLng. 못 읽으면 undefined. */
+    readonly fallbackLng?: string;
+    /** 정적 리터럴 배열로 읽힌 supportedLngs(결정 413 · check 미러용). 못 읽으면 undefined. */
+    readonly supportedLngs?: readonly string[];
+    /**
+     * 결정 412: **선언은 있는데 정적으로 못 읽은** 키들(예 `dir: LOCALES_DIR`).
+     * 이 경우 런타임은 실값을, 타입 축·doctor 는 폴백('locales'·정렬 첫 로케일)을 써서
+     * 두 축이 갈라진다 — 호출자가 경고를 낼 수 있게 표면화한다(무신호 금지).
+     */
+    readonly unresolved: readonly ('dir' | 'fallbackLng')[];
+}
+/** gaon.config.ts 소스에서 i18n 블록의 dir·fallbackLng 리터럴을 뽑는다. */
+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).
+ */
+export declare function warnUnresolvedI18n(analysis: ConfigI18nAnalysis, write: (s: string) => void): void;

package/dist/i18n-config.js

@@ -0,0 +1,170 @@
+// @gaonjs/cli · gaon.config.ts 의 i18n 블록 정적 분석 (결정 352)
+//
+// messages.d.ts 축(생성기·워처)과 doctor(locale-parity)는 런타임 config 로드 없이
+// 돌아야 한다(.env 부재·부분 프로젝트에서도) — connections.ts(결정 135)와 같은
+// 정적 AST 분석으로 `i18n.dir`(카탈로그 위치)·`i18n.fallbackLng`(기준 로케일)를
+// 뽑는다. 이전엔 dir 이 'locales' 로 하드코딩돼 커스텀 dir 프로젝트에서 타입 축과
+// doctor 가 무소음으로 죽었고, 기준 로케일은 fallbackLng 가 아니라 알파벳순 첫
+// 로케일이었다(컴파일 보증이 fallback 체인과 다른 로케일에 정박).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import ts from 'typescript';
+/** gaon.config.ts 소스에서 i18n 블록의 dir·fallbackLng 리터럴을 뽑는다. */
+export function analyzeConfigI18n(source) {
+    const sf = ts.createSourceFile('gaon.config.ts', source, ts.ScriptTarget.ES2022, true);
+    let declared = false;
+    let dir;
+    let fallbackLng;
+    let supportedLngs;
+    const unresolved = new Set();
+    // 결정 412: `as`·`satisfies` 래핑을 벗긴다 — defineConfig({...} satisfies GaonConfig)
+    // 는 실사용 형태인데 종전엔 객체 리터럴이 아니라고 보고 i18n 선언 자체를 놓쳤다.
+    const unwrap = (node) => {
+        let e = node;
+        while (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isSatisfiesExpression(e)) {
+            e = e.expression;
+        }
+        return e;
+    };
+    // 문자열 리터럴 + 치환 없는 템플릿 리터럴(`translations`)을 함께 읽는다 — 개발자
+    // 눈에는 똑같은 리터럴인데 종전엔 템플릿만 무소음으로 빠졌다(결정 412).
+    const literalText = (e) => {
+        const n = unwrap(e);
+        if (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n))
+            return n.text;
+        return undefined;
+    };
+    // i18n 초기화식에서 객체 리터럴을 찾는다 — 삼항·??·&&·괄호는 양변을 훑는다
+    // (connections.ts 와 동일 규약 · env 조건부 블록 대응). 두 분기가 서로 다른
+    // 리터럴을 주는 병리적 케이스는 먼저 읽힌 값을 쓴다(실사용 형태 아님).
+    const collect = (raw) => {
+        const node = unwrap(raw);
+        if (ts.isObjectLiteralExpression(node)) {
+            for (const p of node.properties) {
+                // 결정 412: shorthand(`{ i18n }`)·스프레드는 값을 여기서 알 수 없다 — 조용히
+                // 넘기지 않고 미해석으로 표시한다.
+                if (ts.isShorthandPropertyAssignment(p) || ts.isSpreadAssignment(p)) {
+                    unresolved.add('dir');
+                    unresolved.add('fallbackLng');
+                    continue;
+                }
+                if (!ts.isPropertyAssignment(p))
+                    continue;
+                const name = propNameText(p.name);
+                // 결정 413: supportedLngs 는 리터럴 배열일 때만 읽는다(check 정적 미러용).
+                if (name === 'supportedLngs' && supportedLngs === undefined) {
+                    const arr = unwrap(p.initializer);
+                    if (ts.isArrayLiteralExpression(arr)) {
+                        const items = arr.elements.map((el) => literalText(el));
+                        if (items.every((v) => v !== undefined))
+                            supportedLngs = items;
+                    }
+                    continue;
+                }
+                if (name !== 'dir' && name !== 'fallbackLng')
+                    continue;
+                const text = literalText(p.initializer);
+                if (text === undefined) {
+                    // 변수 참조·env 표현식 등 — 런타임 실값과 갈라지는 지점.
+                    unresolved.add(name);
+                    continue;
+                }
+                if (name === 'dir' && dir === undefined)
+                    dir = text;
+                if (name === 'fallbackLng' && fallbackLng === undefined)
+                    fallbackLng = text;
+            }
+            return;
+        }
+        if (ts.isConditionalExpression(node)) {
+            collect(node.whenTrue);
+            collect(node.whenFalse);
+            return;
+        }
+        if (ts.isBinaryExpression(node)) {
+            const op = node.operatorToken.kind;
+            if (op === ts.SyntaxKind.QuestionQuestionToken ||
+                op === ts.SyntaxKind.BarBarToken ||
+                op === ts.SyntaxKind.AmpersandAmpersandToken) {
+                collect(node.left);
+                collect(node.right);
+            }
+        }
+    };
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && isDefineConfig(node.expression)) {
+            const arg = node.arguments[0];
+            const obj = arg ? unwrap(arg) : undefined;
+            if (obj && ts.isObjectLiteralExpression(obj)) {
+                for (const p of obj.properties) {
+                    if (ts.isShorthandPropertyAssignment(p) && p.name.text === 'i18n') {
+                        // `defineConfig({ i18n })` — 선언은 확실하나 값은 정적으로 못 읽는다.
+                        declared = true;
+                        unresolved.add('dir');
+                        unresolved.add('fallbackLng');
+                        continue;
+                    }
+                    if (ts.isPropertyAssignment(p) && propNameText(p.name) === 'i18n') {
+                        declared = true;
+                        collect(p.initializer);
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    // 읽힌 키는 미해석 목록에서 뺀다(한 분기만 리터럴인 경우 값이 있으면 그 값을 쓴다).
+    if (dir !== undefined)
+        unresolved.delete('dir');
+    if (fallbackLng !== undefined)
+        unresolved.delete('fallbackLng');
+    return { declared, dir, fallbackLng, supportedLngs, unresolved: [...unresolved] };
+}
+/** cwd 의 gaon.config.ts 를 읽어 i18n 블록을 분석한다. 파일이 없으면 미선언. */
+export function analyzeProjectI18n(cwd) {
+    const configPath = join(cwd, 'gaon.config.ts');
+    if (!existsSync(configPath))
+        return { declared: false, unresolved: [] };
+    try {
+        return analyzeConfigI18n(readFileSync(configPath, 'utf8'));
+    }
+    catch {
+        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).
+ */
+export function warnUnresolvedI18n(analysis, write) {
+    if (analysis.unresolved.length === 0)
+        return;
+    write(`  ! gaon.config.ts 의 i18n ${analysis.unresolved.join('·')} 을(를) 정적으로 읽지 못했습니다 — ` +
+        `타입 축(.gaon/messages.d.ts)과 doctor 는 기본값(dir='locales' · 기준=정렬 첫 로케일)을 씁니다.\n` +
+        `    → 문자열 리터럴로 직접 쓰면 정확히 반영됩니다: i18n: { dir: 'locales', fallbackLng: 'ko' }\n`);
+}
+function isDefineConfig(e) {
+    if (ts.isIdentifier(e) && e.text === 'defineConfig')
+        return true;
+    if (ts.isPropertyAccessExpression(e) && e.name.text === 'defineConfig')
+        return true;
+    return false;
+}
+function propNameText(n) {
+    if (ts.isIdentifier(n))
+        return n.text;
+    if (ts.isStringLiteral(n))
+        return n.text;
+    return undefined;
+}