@gaonjs/cli 0.43.0 → 0.52.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,12 @@
+export interface ConfigI18nAnalysis {
+    /** defineConfig 인자에 i18n 프로퍼티가 존재하는가. */
+    readonly declared: boolean;
+    /** 정적 리터럴로 읽힌 dir(상대 경로 원문). 못 읽으면 undefined. */
+    readonly dir?: string;
+    /** 정적 리터럴로 읽힌 fallbackLng. 못 읽으면 undefined. */
+    readonly fallbackLng?: string;
+}
+/** 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;

package/dist/i18n-config.js

@@ -0,0 +1,95 @@
+// @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;
+    // i18n 초기화식에서 객체 리터럴을 찾는다 — 삼항·??·&&·괄호는 양변을 훑는다
+    // (connections.ts 와 동일 규약 · env 조건부 블록 대응). 두 분기가 서로 다른
+    // 리터럴을 주는 병리적 케이스는 먼저 읽힌 값을 쓴다(실사용 형태 아님).
+    const collect = (node) => {
+        if (ts.isParenthesizedExpression(node))
+            return collect(node.expression);
+        if (ts.isObjectLiteralExpression(node)) {
+            for (const p of node.properties) {
+                if (!ts.isPropertyAssignment(p))
+                    continue;
+                const name = propNameText(p.name);
+                if (name === 'dir' && ts.isStringLiteral(p.initializer) && dir === undefined) {
+                    dir = p.initializer.text;
+                }
+                if (name === 'fallbackLng' && ts.isStringLiteral(p.initializer) && fallbackLng === undefined) {
+                    fallbackLng = p.initializer.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];
+            if (arg && ts.isObjectLiteralExpression(arg)) {
+                for (const p of arg.properties) {
+                    if (ts.isPropertyAssignment(p) && propNameText(p.name) === 'i18n') {
+                        declared = true;
+                        collect(p.initializer);
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return { declared, dir, fallbackLng };
+}
+/** cwd 의 gaon.config.ts 를 읽어 i18n 블록을 분석한다. 파일이 없으면 미선언. */
+export function analyzeProjectI18n(cwd) {
+    const configPath = join(cwd, 'gaon.config.ts');
+    if (!existsSync(configPath))
+        return { declared: false };
+    try {
+        return analyzeConfigI18n(readFileSync(configPath, 'utf8'));
+    }
+    catch {
+        return { declared: false };
+    }
+}
+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;
+}

package/dist/index.d.ts

@@ -64,6 +64,12 @@ export interface ParsedNewArgs {
     readonly packageManager?: "pnpm" | "npm" | "yarn";
     /** pm 값이 주어졌으나 pnpm·npm·yarn 이 아닐 때 그 원문(에러 안내용). */
     readonly unknownPm?: string;
+    /**
+     * 결정 314: 파사드 버전 스펙(예 `^1.21.0`). create-gaon 이 자기 발행 메타에서
+     * 해석해 주입한다 — npx 설치 트리엔 gaonjs 패키지가 없어 상향 탐색(결정 242)이
+     * fail-loud 로 죽기 때문. 미지정이면 기존 자동 감지 경로 그대로.
+     */
+    readonly gaonjsVersion?: string;
 }
 /**
  * `gaon new <name>` 의 인자를 파싱한다.

package/dist/index.js

@@ -110,12 +110,12 @@ 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        정적 검사 (${ALL_RULES.length} 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계·import.meta.env·로케일 커버리지)`,
+        `    gaon doctor        정적 검사 (${ALL_RULES.length} 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계·import.meta.env·로케일 커버리지·render return 누락)`,
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
         "    gaon doctor --fix --yes                   실제 편집 적용(원본은 .bak-<타임스탬프> 로 자동 백업)",
-        "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트)",
+        "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트 · --jwt --app <api> = API 앱 토큰 변형)",
         "    gaon g controller <name>   컨트롤러 스캐폴드 (Rails 관례 · 페이지+JSON 액션)",
         "    gaon g model <Name>        모델 스캐폴드 (스키마+모델 · E-4 컬럼 예시)",
         "    gaon g page <Path/Name>    Vue 페이지 (Inertia SPA · pageProps 브리지)",
@@ -147,7 +147,7 @@ function renderHelp(version = VERSION) {
  * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
  */
 export function parseDoctorChecks(argv) {
-    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 27종)를 단일 출처로 쓴다 — 과거
+    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 28종)를 단일 출처로 쓴다 — 과거
     // 손유지 9종 리스트가 뒤처져 --check=seal-security 같은 16종이 조용히 무시되고
     // 전체 검사로 되돌아가던 표류를 근본 차단한다(결정 168).
     const isKnown = (s) => ALL_RULES.includes(s);
@@ -172,12 +172,22 @@ export function parseDoctorChecks(argv) {
 export function parseNewArgs(rest) {
     let name;
     let pmRaw;
+    let gaonjsVersion;
     for (let i = 0; i < rest.length; i++) {
         const a = rest[i];
         if (a === "--package-manager" || a === "--pm") {
             pmRaw = rest[++i];
             continue;
         }
+        // 결정 314: 값을 취하는 플래그라 pm 과 같은 이유로 값을 건너뛴다(이름 오인 방지).
+        if (a === "--gaonjs-version") {
+            gaonjsVersion = rest[++i];
+            continue;
+        }
+        if (a.startsWith("--gaonjs-version=")) {
+            gaonjsVersion = a.slice("--gaonjs-version=".length);
+            continue;
+        }
         const eqPrefix = a.startsWith("--package-manager=")
             ? "--package-manager="
             : a.startsWith("--pm=")
@@ -192,10 +202,15 @@ export function parseNewArgs(rest) {
         if (name === undefined)
             name = a;
     }
+    const version = gaonjsVersion === undefined || gaonjsVersion === "" ? undefined : gaonjsVersion;
     if (pmRaw === "pnpm" || pmRaw === "npm" || pmRaw === "yarn") {
-        return { name, packageManager: pmRaw };
+        return { name, packageManager: pmRaw, gaonjsVersion: version };
     }
-    return { name, unknownPm: pmRaw === undefined || pmRaw === "" ? undefined : pmRaw };
+    return {
+        name,
+        unknownPm: pmRaw === undefined || pmRaw === "" ? undefined : pmRaw,
+        gaonjsVersion: version,
+    };
 }
 /**
  * `gaon db <sub>` 의 인자를 파싱한다(argv = 전체 · argv[0]='db', argv[1]=sub).
@@ -210,6 +225,10 @@ export function parseDbArgs(sub, argv) {
     const dbIdx = argv.indexOf("--db");
     const cfgIdx = argv.indexOf("--config");
     const valueFlags = new Set(["--db", "--config"]);
+    // 결정 358: db 는 파괴 방향 오동작이 가능한 명령군이라 미지 플래그를 조용히
+    // 무시하지 않는다 — `--dryrun`(오타)이 무시되면 dry-run 의도가 **실제 마이그레이션
+    // 적용**으로 반전된다(결정 267 down-위치 문제와 동형). 인정 집합 밖 `--*` 는 throw.
+    const knownFlags = new Set(["--db", "--config", "--json", "--yes", "--dry-run"]);
     const positionals = [];
     for (let i = 2; i < argv.length; i++) {
         const a = argv[i];
@@ -219,8 +238,14 @@ export function parseDbArgs(sub, argv) {
             i++; // 플래그 값 스킵
             continue;
         }
-        if (a.startsWith("--"))
-            continue; // 불리언 플래그
+        if (a.startsWith("--")) {
+            if (!knownFlags.has(a)) {
+                throw new Error(`gaon db ${sub}: 알 수 없는 플래그 '${a}'.\n` +
+                    `  → 지원 플래그: --db <키> · --config <경로> · --dry-run · --yes · --json\n` +
+                    `  → 오타(예: --dryrun)가 조용히 무시되면 의도와 반대로 실행될 수 있어 멈춥니다.`);
+            }
+            continue; // 인정된 불리언 플래그
+        }
         positionals.push(a);
     }
     return {
@@ -393,7 +418,7 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(M9-E · 27 검사 · ALL_RULES 단일 출처). --check=<이름>[,<이름>...] 로
+    // `gaon doctor` — 정적 검사(M9-E · 28 검사 · ALL_RULES 단일 출처). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {
@@ -406,11 +431,15 @@ export function runCli(argv, opts = {}) {
                 process.exitCode = 2;
                 return;
             }
-            // --fix --yes: 편집이 실제로 일어났고 나머지 위반이 없으면 0,
-            //              아직 수동 수정이 남아 있으면 1(자동화 정합).
-            // --fix (dry-run): errors > 0 이면 1(안 고침) · 계획만 있어도 1.
+            // 결정 359: 종료 코드 판정.
+            // --fix --yes: runDoctorCommand 가 적용 후 **재검사** 결과를 돌려주므로
+            //              errors = 잔여 위반 — 전부 자동 수정됐으면 0(자동화 정합).
+            // --fix (dry-run): errors > 0 이면 1 · errors 0 이어도 **계획이 있으면 1**
+            //              (고칠 게 있다는 신호 — 이전엔 warning-only 계획이 0 으로 삼켜짐).
             // 기본: errors > 0 이면 1.
-            process.exitCode = result.errors.length > 0 ? 1 : 0;
+            const fix = result.fix;
+            const dryPlans = fix !== undefined && !fix.applied && fix.outcomes.length > 0;
+            process.exitCode = result.errors.length > 0 || dryPlans ? 1 : 0;
         })
             .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
@@ -483,7 +512,16 @@ export function runCli(argv, opts = {}) {
             process.exitCode = 1;
             return;
         }
-        const dbOpts = parseDbArgs(sub, argv);
+        // 결정 358: 미지 플래그는 파싱 경계에서 fail-loud(오타 dry-run 이 실 적용되는 반전 방지).
+        let dbOpts;
+        try {
+            dbOpts = parseDbArgs(sub, argv);
+        }
+        catch (err) {
+            process.stderr.write(`  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 1;
+            return;
+        }
         void runDbCommand(sub, dbOpts)
             .then((code) => {
             process.exitCode = code;
@@ -503,7 +541,13 @@ export function runCli(argv, opts = {}) {
             const appIdx = argv.indexOf("--app");
             const app = appIdx >= 0 ? argv[appIdx + 1] : undefined;
             // 결정 155: --public 은 비-web 앱도 공개 회원가입을 opt-in(공개 비-web 앱 탈출구).
-            const code = runGenerateAuthCommand({ app, json: argv.includes("--json"), public: argv.includes("--public") });
+            // 결정 338: --jwt 는 API 앱 토큰 변형(--app 필수 · --public 배타).
+            const code = runGenerateAuthCommand({
+                app,
+                json: argv.includes("--json"),
+                public: argv.includes("--public"),
+                jwt: argv.includes("--jwt"),
+            });
             process.exitCode = code;
             return;
         }
@@ -588,6 +632,7 @@ export function runCli(argv, opts = {}) {
             skipInstall: argv.includes("--skip-install"),
             skipGit: argv.includes("--skip-git"),
             packageManager,
+            gaonjsVersion: parsed.gaonjsVersion,
         })
             .then((code) => {
             process.exitCode = code;

package/dist/mcp/tools.d.ts

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

package/dist/mcp/tools.js

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

package/dist/messages-gen.d.ts

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

package/dist/messages-gen.js

@@ -12,13 +12,16 @@ import { loadLocales, renderMessagesDts } from '@gaonjs/i18n';
  * 있으면 생성하지 않는다(GaonMessages 를 비운 채로 둬 t() 키가 string 폴백 — i18n 을
  * 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
  */
-export function generateMessagesDts(localesDir, out) {
+export function generateMessagesDts(localesDir, out, baseLng) {
     if (!existsSync(localesDir))
         return false;
     const resources = loadLocales(localesDir);
     if (Object.keys(resources).length === 0)
         return false;
     mkdirSync(dirname(out), { recursive: true });
-    writeFileSync(out, renderMessagesDts(resources), 'utf8');
+    // 결정 352: 기준 로케일 = config i18n.fallbackLng(호출자가 정적 분석으로 전달).
+    // 이전엔 항상 알파벳순 첫 로케일이라 컴파일 보증이 fallback 체인과 다른 로케일에
+    // 정박했다(en/ko + fallbackLng:'ko' 프로젝트에서 기준이 en).
+    writeFileSync(out, renderMessagesDts(resources, baseLng), 'utf8');
     return true;
 }