@gaonjs/cli 0.43.0 → 0.52.0

package/dist/doctor/pageprops-destructure.js

@@ -1,11 +1,16 @@
-// @gaonjs/cli · doctor · pageProps() 구조분해 검출 (결정 99 · 경고)
+// @gaonjs/cli · doctor · pageProps()/useShared() 구조분해 검출 (결정 99 · 302 · 경고)
 //
-// `pageProps()` 는 반응형 프록시다 — 같은 페이지로의 리다이렉트/리로드로 서버가
-// 새 props 를 주면(댓글 작성·삭제 등) 재마운트 없이 화면이 즉시 갱신된다. 하지만
-// `const { posts } = pageProps<...>()` 처럼 **구조분해**하면 그 순간 값을 한 번
-// 읽어 반응성이 끊긴다(Vue defineProps 를 구조분해하면 안 되는 것과 같은 함정 ·
-// 첫 실사용 블로그에서 preserveState:false 강제 리로드 우회로 나타난 근본 원인).
-// 이 검사가 그 구조분해를 경고로 잡는다. 판정은 소스 텍스트 기반(주석 제외).
+// `pageProps()`·`useShared()` 는 반응형 프록시다 — 같은 페이지로의 리다이렉트/
+// 리로드로 서버가 새 props 를 주면(댓글 작성·삭제·로그인 등) 재마운트 없이 화면이
+// 즉시 갱신된다. 하지만 `const { posts } = pageProps<...>()`·`const { csrf } =
+// useShared()` 처럼 **구조분해**하면 그 순간 값을 한 번 읽어 반응성이 끊긴다
+// (Vue defineProps 를 구조분해하면 안 되는 것과 같은 함정 · 첫 실사용 블로그에서
+// preserveState:false 강제 리로드 우회로 나타난 근본 원인). 이 검사가 그 구조분해를
+// 경고로 잡는다. 판정은 소스 텍스트 기반(주석 제외).
+//
+// 결정 302: 문서(agents/frontend.md)는 useShared 구조분해도 같은 함정으로 경고해
+// 왔는데 검사는 pageProps·`.vue` 만 봤다 — useShared 를 정규식에 더하고, pageProps/
+// useShared 사용이 허용되는 앱 전용 컴포저블(`apps/**/*.ts`)까지 순회를 넓힌다.
 //
 // 오탐 방지: `const props = pageProps<...>()`(변수 바인딩)는 정상이므로 건드리지
 // 않는다 — 여는 중괄호 `{` 로 시작하는 구조분해 바인딩만 잡는다.
@@ -20,44 +25,45 @@ function stripCommentsKeepLines(source) {
         .replace(/<!--[\s\S]*?-->/g, blank)
         .replace(/(^|[^:])\/\/[^\n]*/g, (_m, p1) => p1 + ' '.repeat(_m.length - p1.length));
 }
-// `const|let|var { ... } = pageProps` — 구조분해 바인딩의 초기화가 pageProps 호출.
-// 제네릭 인자(`<'web:posts#index'>`)·공백·중첩 중괄호는 허용하되, `{` 로 시작하는
-// 구조분해만 잡는다(변수 바인딩 `const props =` 은 제외).
-const DESTRUCTURE_RE = /\b(?:const|let|var)\s*\{[^}]*\}\s*=\s*pageProps\b/g;
-/** 소스에 pageProps() 구조분해가 있는지(단위 테스트 진입점 · 주석은 제외). */
+// `const|let|var { ... } = pageProps|useShared` — 구조분해 바인딩의 초기화가 반응형
+// 프록시 호출. 제네릭 인자(`<'web:posts#index'>`)·공백·중첩 중괄호는 허용하되,
+// `{` 로 시작하는 구조분해만 잡는다(변수 바인딩 `const props =` 은 제외 · 결정 302).
+const DESTRUCTURE_RE = /\b(?:const|let|var)\s*\{[^}]*\}\s*=\s*(pageProps|useShared)\b/g;
+/** 소스에 pageProps()/useShared() 구조분해가 있는지(단위 테스트 진입점 · 주석은 제외). */
 export function usesPagePropsDestructure(source) {
     DESTRUCTURE_RE.lastIndex = 0;
     return DESTRUCTURE_RE.test(stripCommentsKeepLines(source));
 }
-/** apps/ 의 .vue 를 훑어 pageProps() 구조분해를 경고로 낸다. */
+/** apps/ 의 .vue + .ts(컴포저블 등)를 훑어 pageProps()/useShared() 구조분해를 경고로 낸다. */
 export async function checkPagePropsDestructure(cwd) {
     const appsDir = join(cwd, 'apps');
     const issues = [];
-    for (const abs of await walkVue(appsDir)) {
+    for (const abs of await walkFrontendSources(appsDir)) {
         const source = await readFile(abs, 'utf8').catch(() => '');
         const stripped = stripCommentsKeepLines(source);
         const rel = relative(cwd, abs);
         for (const m of stripped.matchAll(DESTRUCTURE_RE)) {
+            const callee = m[1] ?? 'pageProps';
             const line = stripped.slice(0, m.index ?? 0).split('\n').length;
             issues.push({
                 rule: 'pageprops-destructure',
                 level: 'warning',
                 file: rel,
                 line,
-                message: `pageProps() 구조분해 발견: ${rel}:${line} 이 \`const { … } = pageProps(…)\` 로 ` +
-                    `props 를 구조분해합니다. pageProps() 는 반응형 프록시라, 구조분해하면 그 순간 값을 ` +
-                    `한 번 읽어 반응성이 끊깁니다 — 같은 페이지로의 리다이렉트/리로드(댓글 작성·삭제 등) ` +
-                    `후 새 데이터가 화면에 반영되지 않습니다(결정 99).\n` +
-                    `→ 변수로 받아 속성으로 접근하세요: \`const props = pageProps<'…'>()\` 후 ` +
-                    `\`props.posts\`. (Vue defineProps 를 구조분해하면 안 되는 것과 같은 이유입니다.)`,
+                message: `${callee}() 구조분해 발견: ${rel}:${line} 이 \`const { … } = ${callee}(…)\` 로 ` +
+                    `값을 구조분해합니다. ${callee}() 는 반응형 프록시라, 구조분해하면 그 순간 값을 ` +
+                    `한 번 읽어 반응성이 끊깁니다 — 같은 페이지로의 리다이렉트/리로드(댓글 작성·삭제·로그인 등) ` +
+                    `후 새 데이터가 화면에 반영되지 않습니다(결정 99 · 302).\n` +
+                    `→ 변수로 받아 속성으로 접근하세요: \`const v = ${callee}(…)\` 후 ` +
+                    `\`v.<필드>\`. (Vue defineProps 를 구조분해하면 안 되는 것과 같은 이유입니다.)`,
                 detail: { file: rel, line },
             });
         }
     }
     return { rule: 'pageprops-destructure', issues };
 }
-/** apps/ 하위 .vue 절대경로. */
-async function walkVue(dir) {
+/** apps/ 하위 .vue·.ts 절대경로(결정 302 — 컴포저블 .ts 포함 · 생성 파일 .gaon 제외). */
+async function walkFrontendSources(dir) {
     const out = [];
     const walk = async (d) => {
         let entries;
@@ -74,7 +80,7 @@ async function walkVue(dir) {
                     continue;
                 await walk(abs);
             }
-            else if (e.isFile() && e.name.endsWith('.vue')) {
+            else if (e.isFile() && (e.name.endsWith('.vue') || (e.name.endsWith('.ts') && !e.name.endsWith('.d.ts')))) {
                 out.push(abs);
             }
         }

package/dist/doctor/render-return.d.ts

@@ -0,0 +1,11 @@
+import type { RuleReport } from './types.js';
+export interface DiscardedResponse {
+    readonly file: string;
+    readonly action: string;
+    readonly method: string;
+    readonly line: number;
+}
+/** 소스 문자열 하나에서 "버려진 응답 호출" 을 수집한다(단위 테스트 진입점). */
+export declare function inspectDiscardedResponses(file: string, source: string): DiscardedResponse[];
+/** apps/ 를 훑어 버려진 응답 호출(무신호 204)을 모두 낸다(경고 등급). */
+export declare function checkRenderReturn(cwd: string): Promise<RuleReport>;

package/dist/doctor/render-return.js

@@ -0,0 +1,143 @@
+// @gaonjs/cli · doctor · render-return 검사 (결정 340)
+//
+// 액션 본문이 `this.render(...)` / `this.redirect(...)` / `this.json(...)` 을
+// **호출만 하고 return 하지 않으면** 반환값(=응답)이 버려져 액션이 void 로 끝나고,
+// 디스패처는 조용히 204 No Content 를 낸다 — 컴파일은 통과하고 페이지는 백지다
+// (무신호 파손 클래스 · agents/web.md 함정 "return 누락 = 204").
+//
+// 정적 분석: 컨트롤러 액션 안에서 위 3종 호출이 ExpressionStatement(또는
+// `await` 만 감싼 문장)로 서 있으면 경고. return · 변수 대입 · 인자 전달 등
+// 값이 소비되는 위치는 오탐 방지로 제외한다. notFound/requireAuth 는 throw
+// 기반 가드라 대상이 아니다(response-mixing 의 GUARD_METHODS 와 정합).
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import ts from 'typescript';
+const RESPONSE_METHODS = new Set(['render', 'redirect', 'json']);
+/** 소스 문자열 하나에서 "버려진 응답 호출" 을 수집한다(단위 테스트 진입점). */
+export function inspectDiscardedResponses(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const found = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && isControllerCall(node)) {
+            const arg = node.arguments[0];
+            if (arg && ts.isObjectLiteralExpression(arg)) {
+                for (const prop of arg.properties) {
+                    const action = actionName(prop);
+                    const body = actionBody(prop);
+                    if (!action || !body || !ts.isBlock(body))
+                        continue;
+                    collectDiscarded(sf, body, action, file, found);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return found;
+}
+function isControllerCall(node) {
+    const e = node.expression;
+    if (ts.isIdentifier(e) && e.text === 'controller')
+        return true;
+    if (ts.isPropertyAccessExpression(e) && e.name.text === 'controller')
+        return true;
+    return false;
+}
+function actionName(prop) {
+    if (ts.isMethodDeclaration(prop) && ts.isIdentifier(prop.name))
+        return prop.name.text;
+    if (ts.isPropertyAssignment(prop) &&
+        ts.isIdentifier(prop.name) &&
+        (ts.isArrowFunction(prop.initializer) || ts.isFunctionExpression(prop.initializer))) {
+        return prop.name.text;
+    }
+    return undefined;
+}
+function actionBody(prop) {
+    if (ts.isMethodDeclaration(prop))
+        return prop.body;
+    if (ts.isPropertyAssignment(prop)) {
+        if (ts.isArrowFunction(prop.initializer))
+            return prop.initializer.body;
+        if (ts.isFunctionExpression(prop.initializer))
+            return prop.initializer.body;
+    }
+    return undefined;
+}
+/** 문장 위치에 버려진 this.render/redirect/json 호출이 있으면 수집한다. */
+function collectDiscarded(sf, body, action, file, out) {
+    const visit = (node) => {
+        if (ts.isExpressionStatement(node)) {
+            const method = responseCallName(node.expression);
+            if (method) {
+                const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+                out.push({ file, action, method, line: line + 1 });
+                return; // 이 문장은 판정 완료 — 내부 재방문 불요.
+            }
+        }
+        // 중첩 함수(콜백) 안의 호출은 반환 의미가 달라 제외(오탐 방지).
+        if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node))
+            return;
+        ts.forEachChild(node, visit);
+    };
+    visit(body);
+}
+/** 식이 (await 를 벗긴) this.render/redirect/json 호출이면 메서드 이름을 돌려준다. */
+function responseCallName(expr) {
+    const inner = ts.isAwaitExpression(expr) ? expr.expression : expr;
+    if (!ts.isCallExpression(inner))
+        return undefined;
+    const c = inner.expression;
+    if (ts.isPropertyAccessExpression(c) &&
+        c.expression.kind === ts.SyntaxKind.ThisKeyword &&
+        RESPONSE_METHODS.has(c.name.text)) {
+        return c.name.text;
+    }
+    return undefined;
+}
+/** apps/ 를 훑어 버려진 응답 호출(무신호 204)을 모두 낸다(경고 등급). */
+export async function checkRenderReturn(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        const ctrlDir = join(appsDir, app, 'controllers');
+        for (const file of await safeListFiles(ctrlDir)) {
+            if (!file.endsWith('.ts') || file.endsWith('.d.ts') || file.endsWith('.test.ts'))
+                continue;
+            const full = join(ctrlDir, file);
+            const source = await readFile(full, 'utf8');
+            for (const d of inspectDiscardedResponses(full, source)) {
+                const rel = relative(cwd, full);
+                issues.push({
+                    rule: 'render-return',
+                    level: 'warning',
+                    file: rel,
+                    line: d.line,
+                    message: `버려진 응답 호출: ${rel}:${d.line} · 액션 '${d.action}' 이 this.${d.method}(...) 를 호출만 하고 return 하지 않습니다.\n` +
+                        `→ 반환값이 곧 응답입니다(errata E-3) — return 이 없으면 액션이 void 로 끝나 조용히 204 No Content(백지)가 나갑니다.\n` +
+                        `→ \`return this.${d.method}(...)\` 로 고치세요. (의도된 204 는 아무 응답 호출 없이 그냥 return 합니다.)`,
+                    detail: { action: d.action, method: d.method },
+                });
+            }
+        }
+    }
+    return { rule: 'render-return', issues };
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function safeListFiles(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isFile()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

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' | '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';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | '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';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -2,6 +2,7 @@ import { type DoctorCheck, type DoctorFatal, type DoctorFatalCode, type DoctorLe
 export type { DoctorCheck, DoctorFatal, DoctorFatalCode, DoctorLevel, DoctorResult, DoctorRule, RuleReport, };
 export type { ResponseKind, ActionUsage } from './doctor/response-mixing.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';
@@ -26,10 +27,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) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */

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 규칙)
@@ -21,7 +21,7 @@
  * 17) method-override (결정 89 · _method HTTP 스푸핑 hack 경고)
  * 18) csrf-wiring (결정 93 · 비-GET 라우트 + session 미배선 = CSRF 무방비 경고)
  * 19) internal-anchor (결정 96 · 앱 내부 이동 일반 <a> = 풀 리로드 경고)
- * 20) pageprops-destructure (결정 99 · pageProps() 구조분해 = 반응성 끊김 경고)
+ * 20) pageprops-destructure (결정 99·302 · pageProps()/useShared() 구조분해 = 반응성 끊김 경고 · .vue+.ts)
  * 21) async-offload (결정 102·103 · 컨트롤러 인라인 메일·이미지·외부 HTTP = 응답 지연 경고)
  * 22) page-layout-breakpoint (결정 107 · 페이지 레이아웃 브레이크포인트 직접 사용 = 안내 경고)
  * 23) link-button-nesting (결정 113 · Link 로 Button 감싸기 = <a><button> 중첩 경고)
@@ -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;