@gaonjs/cli 0.47.0 → 0.52.0

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 27 검사를 조립한다:
+ * 28 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -29,6 +29,7 @@
  * 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 조용 노출 경고)
+ * 28) render-return (결정 340 · this.render/redirect/json 호출만 하고 return 누락 = 무신호 204 경고)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -42,6 +43,7 @@ import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import ts from 'typescript';
 import { checkResponseMixing } from './doctor/response-mixing.js';
+import { checkRenderReturn } from './doctor/render-return.js';
 import { checkNPlusOne } from './doctor/n-plus-one.js';
 import { checkDependencyDirection } from './doctor/dependency-direction.js';
 import { checkConnections } from './doctor/connections.js';
@@ -73,6 +75,7 @@ import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, }
 import { makeResult, } from './doctor/types.js';
 import { FIXERS, FIXER_CAPABILITIES } from './doctor/fixers/index.js';
 export { inspectControllerSource, checkResponseMixing } from './doctor/response-mixing.js';
+export { inspectDiscardedResponses, checkRenderReturn } from './doctor/render-return.js';
 export { inspectControllerForNPlusOne, checkNPlusOne } from './doctor/n-plus-one.js';
 export { extractRelativeImports, checkDependencyDirection } from './doctor/dependency-direction.js';
 export { extractConfigDbKeys, analyzeConfigDb, extractKeyUses, checkConnections, } from './doctor/connections.js';
@@ -97,10 +100,10 @@ export { checkLocaleParity } from './doctor/locale-parity.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 27개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 28개 모두.
  */
 /**
- * doctor 정적 검사 27종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 28종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */
@@ -132,6 +135,7 @@ export const ALL_RULES = [
     'schema-relations',
     'no-import-meta-env',
     'locale-parity',
+    'render-return',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -161,6 +165,7 @@ const CHECKERS = {
     'schema-relations': checkSchemaRelations,
     'no-import-meta-env': checkNoImportMetaEnv,
     'locale-parity': checkLocaleParity,
+    'render-return': checkRenderReturn,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는
@@ -269,10 +274,16 @@ export async function runDoctorCommand(opts = {}) {
     // --fix: fixer 를 계획하고, --yes 이면 실제 편집한다. reports 를 그대로
     // 넘겨 규칙별 위반을 fixer 가 판단한다(passed 는 건너뜀).
     const fixReport = await runDoctorFix(reports, root, opts.yes === true);
-    const resultWithFix = { ...baseResult, fix: fixReport };
+    // 결정 359: 편집이 실제로 일어났으면 **재검사 결과**를 리포트·종료 코드의 기준으로
+    // 삼는다 — 적용 전 리포트로 판정하면 "전부 자동 수정됐는데 exit 1" 로 역전돼
+    // CI 자동화(--fix --yes 후 green 기대)가 깨졌다. errors/warnings = 적용 후 잔여.
+    const finalResult = fixReport.applied && fixReport.outcomes.some((o) => o.applied)
+        ? makeResult(await runRules(root, rules))
+        : baseResult;
+    const resultWithFix = { ...finalResult, fix: fixReport };
     const out = json
         ? JSON.stringify(resultWithFix)
-        : renderHuman(baseResult) + '\n\n' + renderFixHuman(fixReport);
+        : renderHuman(finalResult) + '\n\n' + renderFixHuman(fixReport);
     process.stdout.write(out + '\n');
     return resultWithFix;
 }

package/dist/generate.d.ts

@@ -7,6 +7,12 @@ export interface AuthScaffoldOptions {
      * `--public` 로 비-web 앱도 공개 가입을 opt-in 한다(공개 비-web 앱용 탈출구).
      */
     readonly public?: boolean;
+    /**
+     * 결정 338: JWT(API 앱) 변형 — 세션·페이지 대신 토큰 발급/재발급/내 정보
+     * 컨트롤러(JSON 전용)와 `auth: { strategy:'jwt' }` 배선을 깐다. API 앱 전용이라
+     * `--app <이름>`(비-web) 이 필수다(web 은 세션이 정본 · §7).
+     */
+    readonly jwt?: boolean;
 }
 /** 생성할 파일 하나 — 경로는 프로젝트 루트 기준. */
 export interface ScaffoldFile {
@@ -19,6 +25,12 @@ export interface ScaffoldResult {
     readonly patched: string[];
     /** 손 수리가 필요한 지점 — 수리 안내 문장(§7.5.3)을 그대로 담는다. */
     readonly warnings: string[];
+    /**
+     * 결정 361: 인증 **배선이 미완**인가(app.config auth/routes 자동 패치 실패 —
+     * 이대로면 currentUser 영구 null / 로그인 라우트 부재). 안내성 경고(JWT stateless
+     * 한계 등)와 구분해, 이 값만 종료 코드(비-0)·JSON ok:false 로 이어진다.
+     */
+    readonly incomplete: boolean;
 }
 /**
  * 결정 155·142: `g auth --app <앱>` 이 앱별 세션 secret 환경변수를 .env·.env.example
@@ -32,7 +44,7 @@ export interface ScaffoldResult {
  * .env 를 새로 만드는 관례가 없어(사용자가 cp .env.example .env), 존재하는 파일만 패치한다.
  * 반환: 실제로 키를 추가한 상대 경로들.
  */
-export declare function patchEnvFiles(root: string, app: string): string[];
+export declare function patchEnvFiles(root: string, app: string, kind?: 'session' | 'jwt'): string[];
 /** 인증 스캐폴드가 생성하는 파일 목록(라우트 제외). 템플릿을 읽어 렌더링한다.
  *  결정 155: 공개 가입 여부(includePublic)로 registration·Signup·dashboard 변형을 가른다. */
 export declare function authScaffoldFiles(opts?: AuthScaffoldOptions): ScaffoldFile[];
@@ -40,6 +52,11 @@ export declare function authScaffoldFiles(opts?: AuthScaffoldOptions): ScaffoldF
  * 기존 routes.ts 에 세션·회원가입 리소스를 끼워 넣는다. 이미 있으면 null.
  * `routes((r) => {` 콜백 여는 지점 뒤에 두 줄을 삽입한다.
  */
+/**
+ * 결정 338: 기존 routes.ts 에 JWT 토큰 라우트 3종을 끼워 넣는다. 이미 session#create
+ * 참조가 있으면 null(중복 방지). 삽입 지점 규칙은 patchRoutes 와 동일.
+ */
+export declare function patchRoutesJwt(existing: string): string | null;
 export declare function patchRoutes(existing: string, includePublic?: boolean): string | null;
 /**
  * 기존 app.config.ts 에 auth 배선을 끼워 넣는다 (결정 93 · gaon new 기본 web 앱은
@@ -57,6 +74,8 @@ export interface GenerateAuthOptions {
     readonly json?: boolean;
     /** 결정 155: 비-web 앱도 공개 회원가입을 opt-in(공개 비-web 앱용 탈출구). */
     readonly public?: boolean;
+    /** 결정 338: JWT(API 앱) 변형 — `--app <비-web 이름>` 필수 · `--public` 과 배타. */
+    readonly jwt?: boolean;
 }
 /** `gaon g auth` 진입점. 스캐폴드를 쓰고 결과를 사람/JSON 으로 출력한다. */
 export declare function runGenerateAuthCommand(opts?: GenerateAuthOptions): number;

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.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);
@@ -225,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];
@@ -234,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 {
@@ -408,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") {
@@ -421,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);
@@ -498,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;
@@ -518,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;
         }

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>;
 /**