@gaonjs/cli 0.21.2 → 0.24.0

package/dist/doctor/pageprops-destructure.js

@@ -0,0 +1,84 @@
+// @gaonjs/cli · doctor · pageProps() 구조분해 검출 (결정 99 · 경고)
+//
+// `pageProps()` 는 반응형 프록시다 — 같은 페이지로의 리다이렉트/리로드로 서버가
+// 새 props 를 주면(댓글 작성·삭제 등) 재마운트 없이 화면이 즉시 갱신된다. 하지만
+// `const { posts } = pageProps<...>()` 처럼 **구조분해**하면 그 순간 값을 한 번
+// 읽어 반응성이 끊긴다(Vue defineProps 를 구조분해하면 안 되는 것과 같은 함정 ·
+// 첫 실사용 블로그에서 preserveState:false 강제 리로드 우회로 나타난 근본 원인).
+// 이 검사가 그 구조분해를 경고로 잡는다. 판정은 소스 텍스트 기반(주석 제외).
+//
+// 오탐 방지: `const props = pageProps<...>()`(변수 바인딩)는 정상이므로 건드리지
+// 않는다 — 여는 중괄호 `{` 로 시작하는 구조분해 바인딩만 잡는다.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+// 주석을 공백으로 치환하되 줄바꿈은 보존한다(라인 번호 유지) — "구조분해하지
+// 말라"고 설명하는 주석이 오탐을 내지 않도록.
+function stripCommentsKeepLines(source) {
+    const blank = (m) => m.replace(/[^\n]/g, ' ');
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, blank)
+        .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() 구조분해가 있는지(단위 테스트 진입점 · 주석은 제외). */
+export function usesPagePropsDestructure(source) {
+    DESTRUCTURE_RE.lastIndex = 0;
+    return DESTRUCTURE_RE.test(stripCommentsKeepLines(source));
+}
+/** apps/ 의 .vue 를 훑어 pageProps() 구조분해를 경고로 낸다. */
+export async function checkPagePropsDestructure(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const abs of await walkVue(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 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 를 구조분해하면 안 되는 것과 같은 이유입니다.)`,
+                detail: { file: rel, line },
+            });
+        }
+    }
+    return { rule: 'pageprops-destructure', issues };
+}
+/** apps/ 하위 .vue 절대경로. */
+async function walkVue(dir) {
+    const out = [];
+    const walk = async (d) => {
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const abs = join(d, e.name);
+            if (e.isDirectory()) {
+                if (e.name === 'node_modules' || e.name === '.gaon')
+                    continue;
+                await walk(abs);
+            }
+            else if (e.isFile() && e.name.endsWith('.vue')) {
+                out.push(abs);
+            }
+        }
+    };
+    await walk(dir);
+    return out.sort();
+}

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-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';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-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';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor/types.js

@@ -1,9 +1,7 @@
 // @gaonjs/cli · doctor 공용 타입 (M9-E · M9-E-Fix · M9-E 확장 · E-5)
 //
-// 17 검사(response-mixing · n-plus-one · dependency-direction · connections
-// · migration-diff · shared-composable-purity · no-auto-import · schema-filename
-// · agents-doc-index · column-casing · model-filename · page-filename · auth-wiring
-// · ui-kit-wiring)가 모두 이 DoctorCheck 를 낸다. 상위(runDoctorCommand)는 level 로 passed/
+// 21 검사(전체 목록은 AGENTS §2.2 · doctor.ts `ALL_RULES`)가 모두 이 DoctorCheck
+// 를 낸다. 상위(runDoctorCommand)는 level 로 passed/
 // warnings/errors 로 갈라 담는다. 자동화(CI)는 JSON 을 파싱해
 // errors.length > 0 이면 fail 로 판단한다.
 //

package/dist/doctor.d.ts

@@ -15,6 +15,10 @@ export { isPascalCase, checkModelFilename } from './doctor/model-filename.js';
 export { checkPageFilename } from './doctor/page-filename.js';
 export { usesAuthSurface, hasAuthWiring, hasSessionWiring, checkAuthWiring, } from './doctor/auth-wiring.js';
 export { importsUiKit, checkUiKitWiring } from './doctor/ui-kit-wiring.js';
+export { hasStateChangingRoutes, checkCsrfWiring } from './doctor/csrf-wiring.js';
+export { internalAnchorHref, usesInternalAnchor, checkInternalAnchor, } from './doctor/internal-anchor.js';
+export { usesPagePropsDestructure, checkPagePropsDestructure, } from './doctor/pageprops-destructure.js';
+export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActions, checkAsyncOffload, } from './doctor/async-offload.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 export interface DoctorCommandOptions {

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 17 검사를 조립한다:
+ * 21 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -19,6 +19,10 @@
  * 15) route-registration (결정 79 · 고아 컨트롤러 = routes.ts 미참조 경고)
  * 16) static-collision (결정 85 · 정적 파일이 라우트/에셋에 가려짐 경고)
  * 17) method-override (결정 89 · _method HTTP 스푸핑 hack 경고)
+ * 18) csrf-wiring (결정 93 · 비-GET 라우트 + session 미배선 = CSRF 무방비 경고)
+ * 19) internal-anchor (결정 96 · 앱 내부 이동 일반 <a> = 풀 리로드 경고)
+ * 20) pageprops-destructure (결정 99 · pageProps() 구조분해 = 반응성 끊김 경고)
+ * 21) async-offload (결정 102·103 · 컨트롤러 인라인 메일·이미지·외부 HTTP = 응답 지연 경고)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -48,6 +52,10 @@ import { checkUiKitWiring } from './doctor/ui-kit-wiring.js';
 import { checkRouteRegistration } from './doctor/route-registration.js';
 import { checkStaticCollision } from './doctor/static-collision.js';
 import { checkMethodOverride } from './doctor/method-override.js';
+import { checkCsrfWiring } from './doctor/csrf-wiring.js';
+import { checkInternalAnchor } from './doctor/internal-anchor.js';
+import { checkPagePropsDestructure } from './doctor/pageprops-destructure.js';
+import { checkAsyncOffload } from './doctor/async-offload.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -66,10 +74,14 @@ export { isPascalCase, checkModelFilename } from './doctor/model-filename.js';
 export { checkPageFilename } from './doctor/page-filename.js';
 export { usesAuthSurface, hasAuthWiring, hasSessionWiring, checkAuthWiring, } from './doctor/auth-wiring.js';
 export { importsUiKit, checkUiKitWiring } from './doctor/ui-kit-wiring.js';
+export { hasStateChangingRoutes, checkCsrfWiring } from './doctor/csrf-wiring.js';
+export { internalAnchorHref, usesInternalAnchor, checkInternalAnchor, } from './doctor/internal-anchor.js';
+export { usesPagePropsDestructure, checkPagePropsDestructure, } from './doctor/pageprops-destructure.js';
+export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActions, checkAsyncOffload, } from './doctor/async-offload.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 17개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 21개 모두.
  */
 const ALL_RULES = [
     'response-mixing',
@@ -89,6 +101,10 @@ const ALL_RULES = [
     'route-registration',
     'static-collision',
     'method-override',
+    'csrf-wiring',
+    'internal-anchor',
+    'pageprops-destructure',
+    'async-offload',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -108,6 +124,10 @@ const CHECKERS = {
     'route-registration': checkRouteRegistration,
     'static-collision': checkStaticCollision,
     'method-override': checkMethodOverride,
+    'csrf-wiring': checkCsrfWiring,
+    'internal-anchor': checkInternalAnchor,
+    'pageprops-destructure': checkPagePropsDestructure,
+    'async-offload': checkAsyncOffload,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/generate.d.ts

@@ -21,6 +21,14 @@ export declare function authScaffoldFiles(opts?: AuthScaffoldOptions): ScaffoldF
  * `routes((r) => {` 콜백 여는 지점 뒤에 두 줄을 삽입한다.
  */
 export declare function patchRoutes(existing: string): string | null;
+/**
+ * 기존 app.config.ts 에 auth 배선을 끼워 넣는다 (결정 93 · gaon new 기본 web 앱은
+ * 세션만 배선돼 있어 g auth 는 auth 만 추가하면 완성된다). 반환:
+ *  · auth 가 이미 있으면 null (그대로 둔다),
+ *  · defineAppConfig 객체 리터럴을 못 찾으면 null (안전 · 상위에서 경고 폴백).
+ * 성공 시 loadUser import 도 함께 보장한다.
+ */
+export declare function patchAppConfigAddAuth(existing: string): string | null;
 /** 스캐폴드를 디스크에 쓴다. 기존 파일은 덮어쓰지 않고 skip 한다. routes.ts 는 패치. */
 export declare function writeAuthScaffold(cwd: string, opts?: AuthScaffoldOptions): ScaffoldResult;
 export interface GenerateAuthOptions {

package/dist/generate.js

@@ -69,6 +69,38 @@ export function patchRoutes(existing) {
         "\n  r.resource('registration') // 회원가입 (gaon g auth)";
     return existing.slice(0, insertAt) + inject + existing.slice(insertAt);
 }
+/**
+ * 기존 app.config.ts 에 auth 배선을 끼워 넣는다 (결정 93 · gaon new 기본 web 앱은
+ * 세션만 배선돼 있어 g auth 는 auth 만 추가하면 완성된다). 반환:
+ *  · auth 가 이미 있으면 null (그대로 둔다),
+ *  · defineAppConfig 객체 리터럴을 못 찾으면 null (안전 · 상위에서 경고 폴백).
+ * 성공 시 loadUser import 도 함께 보장한다.
+ */
+export function patchAppConfigAddAuth(existing) {
+    if (/\bauth\s*:/.test(existing))
+        return null;
+    const m = existing.match(/defineAppConfig\(\s*\{/);
+    if (!m || m.index === undefined)
+        return null;
+    const insertAt = m.index + m[0].length;
+    let out = existing.slice(0, insertAt) +
+        "\n  // 결정 59: 세션 userId → 사용자 로드 배선(g auth). 이게 있어야 로그인 후" +
+        "\n  // this.currentUser / this.requireAuth() 가 실제 사용자를 받는다." +
+        "\n  auth: { loadUser, loginRedirect: '/session/new' }," +
+        existing.slice(insertAt);
+    // loadUser import 보장 — gaonjs/config import 바로 뒤에 넣는다.
+    if (!/from\s+['"]\.\/auth\.js['"]/.test(out)) {
+        const im = out.match(/import\s+\{[^}]*\}\s+from\s+['"]gaonjs\/config['"][^\n]*\n/);
+        if (im && im.index !== undefined) {
+            const at = im.index + im[0].length;
+            out = out.slice(0, at) + "import { loadUser } from './auth.js'\n" + out.slice(at);
+        }
+        else {
+            out = "import { loadUser } from './auth.js'\n" + out;
+        }
+    }
+    return out;
+}
 /** 스캐폴드를 디스크에 쓴다. 기존 파일은 덮어쓰지 않고 skip 한다. routes.ts 는 패치. */
 export function writeAuthScaffold(cwd, opts = {}) {
     const root = resolve(cwd);
@@ -87,19 +119,31 @@ export function writeAuthScaffold(cwd, opts = {}) {
     for (const file of authScaffoldFiles(opts)) {
         const abs = join(root, file.path);
         if (existsSync(abs)) {
-            skipped.push(file.path);
-            // 결정 59: app.config.ts 가 이미 있는데 auth 배선이 없으면 로그인 후에도
-            // currentUser 가 영구 null 이다 — skip 으로 끝내지 않고 수리 안내를 남긴다.
+            // 결정 93: gaon new 기본 web 앱은 app.config.ts 에 세션만 배선돼 있다.
+            // g auth 는 이를 skip 하지 않고 **auth 배선을 패치로 추가**해 완성한다 —
+            // 결정 59: auth 배선이 없으면 로그인 후에도 currentUser 가 영구 null 이다.
             if (file.path === `apps/${app}/app.config.ts`) {
                 const existing = readFileSync(abs, 'utf8');
-                if (!/\bauth\s*:/.test(existing)) {
-                    warnings.push(`apps/${app}/app.config.ts 가 이미 있어 인증 배선을 건너뛰었습니다.\n` +
-                        `→ apps/${app}/app.config.ts 의 defineAppConfig({...}) 에 다음 두 항목을 추가하세요:\n` +
-                        `   session: { secret: process.env.SESSION_SECRET ?? '32자 이상 비밀' },\n` +
+                const patchedConfig = patchAppConfigAddAuth(existing);
+                if (patchedConfig) {
+                    writeFileSync(abs, patchedConfig, 'utf8');
+                    patched.push(file.path);
+                }
+                else if (!/\bauth\s*:/.test(existing)) {
+                    // 패치 불가(비관례 config) — skip + 수리 안내로 폴백.
+                    skipped.push(file.path);
+                    warnings.push(`apps/${app}/app.config.ts 가 이미 있어 인증 배선을 자동 추가하지 못했습니다.\n` +
+                        `→ apps/${app}/app.config.ts 의 defineAppConfig({...}) 에 다음을 추가하세요:\n` +
                         `   auth: { loadUser, loginRedirect: '/session/new' }  // import { loadUser } from './auth.js'\n` +
                         `→ 이 배선이 없으면 로그인해도 this.currentUser/requireAuth() 가 사용자를 받지 못합니다.`);
                 }
+                else {
+                    // 이미 auth 배선됨 — 그대로 둔다.
+                    skipped.push(file.path);
+                }
+                continue;
             }
+            skipped.push(file.path);
             continue;
         }
         mkdirSync(dirname(abs), { recursive: true });

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export { loadDomain, type LoadedDomain } from "./domain.js";
 export interface RoadmapReport {
     readonly name: "gaon";
     readonly version: string;
-    readonly stage: "stub";
+    readonly stage: "stable";
     readonly homepage: string;
     readonly docs: string;
     readonly milestones: readonly {
@@ -34,7 +34,11 @@ export interface RoadmapReport {
 }
 /** `--json` 출력용 구조화 리포트. */
 export declare function roadmapReport(version?: string): RoadmapReport;
-/** 사람이 읽는 로드맵 텍스트. */
+/**
+ * 인자 없이 실행했을 때의 사람용 배너 — 정식 배포(v1.0) 자기 소개 + 사용법 안내.
+ * 결정 94(W3): M1 스텁 시절 "개발 초기·런타임 없음" 오정보를 제거한다 — AI 가
+ * 사용 불가로 오판하거나 소형 모델이 멈추는 것을 막는다.
+ */
 export declare function renderRoadmap(version?: string): string;
 /** runCli 옵션. version 은 파사드가 주입하는 표시 버전(설치 패키지 버전). */
 export interface RunOptions {

package/dist/index.js

@@ -1,8 +1,8 @@
 /**
  * @gaonjs/cli — Gaon CLI 구현.
  *
- * 인자 없이 실행하면 로드맵·개발 상태를 출력하는 스텁이다. M9-C 부터
- * `gaon dev` 가 통합 개발 오케스트레이션을 담당한다 — Docker Compose
+ * 인자 없이 실행하면 정식 배포(v1.0) 배너와 사용법을 출력한다. `gaon dev`
+ * 가 통합 개발 오케스트레이션을 담당한다 — Docker Compose
  * 자동 기동 + .gaon 타입 브리지 재생성 + serve 자식 프로세스 + tsc/vue-tsc
  * --watch + 소스 변경 시 서버 재시작(commands/dev.ts). 모든 명령은 `--json`
  * 출력을 함께 제공한다 (CLAUDE.md §4).
@@ -10,7 +10,7 @@
  * 표시 버전은 호출자(파사드)가 주입한다 — 사용자가 설치한 패키지
  * (`gaonjs`) 버전을 그대로 보여주기 위함. 미주입 시 core 버전을 쓴다.
  */
-import { MILESTONES, VERSION, HOMEPAGE } from "@gaonjs/core";
+import { MILESTONES, VERSION, HOMEPAGE, loadDotEnv } from "@gaonjs/core";
 import { runDevCommand } from "./commands/dev.js";
 import { runCheckCommand } from "./commands/check.js";
 import { runNewCommand } from "./commands/new.js";
@@ -54,41 +54,38 @@ export function roadmapReport(version = VERSION) {
     return {
         name: "gaon",
         version,
-        stage: "stub",
+        stage: "stable",
         homepage: HOMEPAGE,
         docs: HOMEPAGE,
         milestones: MILESTONES.map((m) => ({ id: m.id, title: m.title, status: m.status })),
     };
 }
-/** 사람이 읽는 로드맵 텍스트. */
+/**
+ * 인자 없이 실행했을 때의 사람용 배너 — 정식 배포(v1.0) 자기 소개 + 사용법 안내.
+ * 결정 94(W3): M1 스텁 시절 "개발 초기·런타임 없음" 오정보를 제거한다 — AI 가
+ * 사용 불가로 오판하거나 소형 모델이 멈추는 것을 막는다.
+ */
 export function renderRoadmap(version = VERSION) {
     const lines = [];
     lines.push("");
     lines.push(`  Gaon (가온) — AI가 개발을 가장 잘하는 Node.js 풀스택 웹 프레임웍`);
-    lines.push(`  v${version} · 개발 중 (스텁) · ${HOMEPAGE}`);
+    lines.push(`  v${version} · 정식 배포 · ${HOMEPAGE}`);
     lines.push("");
-    lines.push("  이 패키지는 아직 개발 초기 단계입니다. 런타임 기능은 아직 없고,");
-    lines.push("  자리(스코프·이름)를 잡아 두기 위한 동작하는 스텁입니다.");
+    lines.push("  데이터·인증·실시간·비동기·메일/스토리지·CLI 배터리가 모두 동작합니다.");
+    lines.push("  새 프로젝트를 만들고 개발 스택을 통합 기동하려면:");
     lines.push("");
-    lines.push("  로드맵");
-    lines.push("  ──────");
-    for (const m of MILESTONES) {
-        const mark = m.status === "in-progress" ? "▶" : "·";
-        const tag = m.status === "in-progress" ? " (진행 중)" : "";
-        lines.push(`   ${mark} ${m.id}  ${m.title}${tag}`);
-    }
+    lines.push("    gaon new <name>    새 프로젝트 스캐폴드");
+    lines.push("    gaon dev           개발 스택 통합 기동 (Docker · .gaon · serve · watch)");
+    lines.push("    gaon --help        전체 명령 목록");
     lines.push("");
-    lines.push("  참여 · 소식");
-    lines.push("  ──────────");
-    lines.push(`   문서 / 진행 상황:  ${HOMEPAGE}`);
-    lines.push(`   JSON 출력:         gaon --json`);
+    lines.push(`  문서: ${HOMEPAGE}   ·   JSON 출력: gaon --json`);
     lines.push("");
     return lines.join("\n");
 }
 function renderHelp(version = VERSION) {
     return [
         "",
-        "  gaon — Gaon 프레임웍 CLI (v" + version + ", 스텁)",
+        "  gaon — Gaon 프레임웍 CLI (v" + version + " · 정식 배포)",
         "",
         "  사용법:",
         "    gaon               로드맵과 개발 상태를 출력",
@@ -104,7 +101,7 @@ function renderHelp(version = VERSION) {
         "    gaon check         typecheck · vue-tsc · build 통합 검사 (--only <step> · --include-doctor)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
         "    gaon test          테스트 러너 (--scope unit|integration|all · -- vitest 인자)",
-        "    gaon doctor        정적 검사 (17 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method)",
+        "    gaon doctor        정적 검사 (21 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
@@ -149,6 +146,8 @@ export function parseDoctorChecks(argv) {
         "migration-diff",
         "shared-composable-purity",
         "no-auto-import",
+        "csrf-wiring",
+        "async-offload",
     ];
     const isKnown = (s) => known.includes(s);
     const out = [];
@@ -165,6 +164,13 @@ export function parseDoctorChecks(argv) {
 /** CLI 진입점. argv 는 실행 인자(process.argv.slice(2))를 받는다. */
 export function runCli(argv, opts = {}) {
     const version = opts.version ?? VERSION;
+    // 결정 92(W1): `.env` 를 **진입점에서 한 번** 로드해 모든 명령이 동일하게
+    // 받는다. 이전엔 serve·dev·console 만 개별 호출해 db·work·hub·jobs·doctor·
+    // check 가 `.env` 없이 실행됐고(특히 work·hub 는 조용히 안 뜨는 부류),
+    // 실사용에서 `set -a; . ./.env` 수동 우회가 필요했다. 명령별 나열은 새
+    // 명령이 추가될 때마다 또 빠지므로 여기서 공통화한다. loadDotEnv 는 이미
+    // 설정된 env 를 덮지 않고 파일이 없으면 조용히 지나가 멱등하다(재호출 안전).
+    loadDotEnv();
     // `gaon dev` — 통합 개발 오케스트레이션(M9-C · v0.15 §13.5). Docker Compose
     // 자동 기동 + .gaon 재생성 + serve 자식 + tsc/vue-tsc watch + 서버 재시작 워처.
     // SIGINT/SIGTERM 시 순서대로 정리(serve → tsc → 워처 → Docker[--stop-docker 시]).

package/dist/serve.js

@@ -149,6 +149,13 @@ export async function runServeCommand(opts = {}) {
     await wired.app.listen({ host, port });
     const displayHost = host === '0.0.0.0' ? 'localhost' : host;
     emit({ kind: 'listening', host, port, url: `http://${displayHost}:${port}` });
+    // 결정 98: serve 는 빌드된 번들을 서빙하며 코드 변경을 감시하지 않는다 —
+    // 수정이 조용히 반영 안 되는 혼란(첫 실사용 관측)을 막으려 한 줄 안내한다.
+    // dev 자식(gaon dev · opts.dev)은 이미 감시하므로 그때는 안내하지 않고,
+    // production 은 운영 로그 소음을 막으려 출력하지 않는다. json 은 파싱 안전상 제외.
+    if (!json && !opts.dev && process.env.NODE_ENV !== 'production') {
+        process.stdout.write('  ℹ serve 는 빌드된 번들을 서빙하며 코드 변경을 감시하지 않습니다 → 개발 중이면 `gaon dev` 를 쓰세요.\n');
+    }
     await new Promise((resolvePromise) => {
         const stop = () => {
             signals.off('SIGINT', stop);

package/dist/templates/auth/Dashboard.vue.tpl

@@ -9,14 +9,15 @@ import CardFooter from '../components/ui/CardFooter.vue'
 import Button from '../components/ui/Button.vue'
 
 // dashboard#show 의 render props — user 는 직렬화되며 passwordDigest 는 없다(§4.2).
-const { user, csrf } = pageProps<'{{APP_NAME}}:dashboard#show'>()
+// pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
+const props = pageProps<'{{APP_NAME}}:dashboard#show'>()
 
 // 로그아웃 = DELETE /session (r.resource('session') 의 destroy).
 // HTML <form> 은 DELETE 를 보낼 수 없으므로 Inertia 라우터로 실제 메서드를
 // 보낸다(결정 64) — `?_method=DELETE` 우회는 서버가 해석하지 않아 POST /session
 // (= 로그인 create) 으로 잘못 라우팅됐다.
 function logout(): void {
-  router.delete('/session', { headers: { 'x-csrf-token': csrf } })
+  router.delete('/session', { headers: { 'x-csrf-token': props.csrf } })
 }
 </script>
 
@@ -24,8 +25,8 @@ function logout(): void {
   <div class="mx-auto max-w-2xl px-4 py-10">
     <Card>
       <CardHeader>
-        <CardTitle>환영합니다, {{ user.name }}님</CardTitle>
-        <CardDescription>{{ user.email }}</CardDescription>
+        <CardTitle>환영합니다, {{ props.user.name }}님</CardTitle>
+        <CardDescription>{{ props.user.email }}</CardDescription>
       </CardHeader>
       <CardContent>
         <p class="text-sm text-muted-foreground">보호된 페이지입니다 — this.requireAuth() 로 지킵니다.</p>

package/dist/templates/auth/Login.vue.tpl

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { pageProps, useForm } from 'gaonjs/vue'
+import { pageProps, useForm, Link } from 'gaonjs/vue'
 import Card from '../../components/ui/Card.vue'
 import CardHeader from '../../components/ui/CardHeader.vue'
 import CardTitle from '../../components/ui/CardTitle.vue'
@@ -12,12 +12,14 @@ import Button from '../../components/ui/Button.vue'
 import Alert from '../../components/ui/Alert.vue'
 import AlertDescription from '../../components/ui/AlertDescription.vue'
 
-// 컨트롤러 session#new 의 render props 타입이 그대로 흐른다(§6.2).
-const { error, csrf } = pageProps<'{{APP_NAME}}:session#new'>()
+// 컨트롤러 session#new 의 render props 타입이 그대로 흐른다(§6.2). pageProps 는
+// 반응형이라 변수로 받아 props.x 로 접근한다 — 구조분해 금지(결정 99). 로그인
+// 실패로 서버가 같은 페이지를 다시 render 하면 props.error 가 즉시 갱신된다.
+const props = pageProps<'{{APP_NAME}}:session#new'>()
 
 // 세션 앱 폼 = Inertia SPA 제출(결정 64) — fetch() 로 만들지 않는다.
 // 서버는 redirect(Inertia 응답)로 답하고, 실패 시 같은 페이지를 다시 render 한다.
-const form = useForm({ email: '', password: '', _csrf: csrf })
+const form = useForm({ email: '', password: '', _csrf: props.csrf })
 </script>
 
 <template>
@@ -28,8 +30,8 @@ const form = useForm({ email: '', password: '', _csrf: csrf })
         <CardDescription>계정으로 로그인하세요.</CardDescription>
       </CardHeader>
       <CardContent>
-        <Alert v-if="error" variant="destructive" class="mb-4">
-          <AlertDescription>{{ error }}</AlertDescription>
+        <Alert v-if="props.error" variant="destructive" class="mb-4">
+          <AlertDescription>{{ props.error }}</AlertDescription>
         </Alert>
         <Form @submit="form.post('/session')">
           <FormField label="이메일" :error="form.errors.email">
@@ -42,7 +44,7 @@ const form = useForm({ email: '', password: '', _csrf: csrf })
         </Form>
         <p class="mt-4 text-center text-sm text-muted-foreground">
           계정이 없으신가요?
-          <a href="/registration/new" class="font-medium text-primary underline-offset-4 hover:underline">회원가입</a>
+          <Link href="/registration/new" class="font-medium text-primary underline-offset-4 hover:underline">회원가입</Link>
         </p>
       </CardContent>
     </Card>

package/dist/templates/auth/Signup.vue.tpl

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { pageProps, useForm } from 'gaonjs/vue'
+import { pageProps, useForm, Link } from 'gaonjs/vue'
 import Card from '../../components/ui/Card.vue'
 import CardHeader from '../../components/ui/CardHeader.vue'
 import CardTitle from '../../components/ui/CardTitle.vue'
@@ -12,10 +12,11 @@ import Button from '../../components/ui/Button.vue'
 import Alert from '../../components/ui/Alert.vue'
 import AlertDescription from '../../components/ui/AlertDescription.vue'
 
-const { error, csrf } = pageProps<'{{APP_NAME}}:registration#new'>()
+// pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
+const props = pageProps<'{{APP_NAME}}:registration#new'>()
 
 // 세션 앱 폼 = Inertia SPA 제출(결정 64) — fetch() 로 만들지 않는다.
-const form = useForm({ name: '', email: '', password: '', _csrf: csrf })
+const form = useForm({ name: '', email: '', password: '', _csrf: props.csrf })
 </script>
 
 <template>
@@ -26,8 +27,8 @@ const form = useForm({ name: '', email: '', password: '', _csrf: csrf })
         <CardDescription>새 계정을 만드세요.</CardDescription>
       </CardHeader>
       <CardContent>
-        <Alert v-if="error" variant="destructive" class="mb-4">
-          <AlertDescription>{{ error }}</AlertDescription>
+        <Alert v-if="props.error" variant="destructive" class="mb-4">
+          <AlertDescription>{{ props.error }}</AlertDescription>
         </Alert>
         <Form @submit="form.post('/registration')">
           <FormField label="이름" :error="form.errors.name">
@@ -43,7 +44,7 @@ const form = useForm({ name: '', email: '', password: '', _csrf: csrf })
         </Form>
         <p class="mt-4 text-center text-sm text-muted-foreground">
           이미 계정이 있으신가요?
-          <a href="/session/new" class="font-medium text-primary underline-offset-4 hover:underline">로그인</a>
+          <Link href="/session/new" class="font-medium text-primary underline-offset-4 hover:underline">로그인</Link>
         </p>
       </CardContent>
     </Card>

package/dist/templates/project/AGENTS.md.tpl

@@ -104,7 +104,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 17종
+### 2.2 `gaon doctor` 검사 21종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -123,6 +123,10 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 15. `route-registration` — 고아 컨트롤러(파일은 있는데 `routes.ts` 미참조 · 도달 불가) (결정 79 · 경고)
 16. `static-collision` — 정적 파일(`apps/<앱>/static/`)이 라우트/에셋에 가려져 도달 불가 (결정 85 · 경고)
 17. `method-override` — `_method` HTTP 메서드 스푸핑 hack(Gaon 미지원 · router.delete 를 쓰라) (결정 89 · 경고)
+18. `csrf-wiring` — 비-GET 라우트(POST/PUT/PATCH/DELETE)가 있는데 `app.config.ts` 에 session 미배선 = CSRF 무방비 (결정 93 · 경고)
+19. `internal-anchor` — 앱 내부 경로 일반 `<a href="/...">`(풀 리로드로 SPA 파손 · `Link`/`router.visit` 를 쓰라 · 외부 URL·`target="_blank"` 는 제외) (결정 96 · 경고)
+20. `pageprops-destructure` — `const { x } = pageProps(…)` 구조분해(반응성 끊김 · 리다이렉트/리로드 후 갱신 안 됨 · `const props = pageProps(…)` 후 `props.x` 로 접근하라) (결정 99 · 경고)
+21. `async-offload` — 컨트롤러 액션 인라인의 무거운/외부 작업(메일 SDK·이미지 처리 sharp/jimp·외부 HTTP)이 응답을 지연 (`domain/jobs/` 잡 + `.later()` 로 빼라 · JSON/API 앱 외부 호출·빠른 내부 호출은 오탐 방지로 제외) (결정 102·103 · 경고)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -156,6 +160,26 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 위치를 강제하지 않는다 (`agents/async.md` §2). DB 커밋 정합이 필요하면
 서비스 `afterCommit()` 또는 아웃박스.
 
+### 3.5 비동기 배치 (동기 인라인 vs 잡/이벤트/스케줄 · 결정 102)
+
+§3.1~§3.4 가 "로직을 **어느 층**에 둘까"라면, 이 표는 "그 로직을 **동기로 둘까
+비동기로 뺄까**"의 One Way 다. 상세·예시는 `agents/async.md` 서두 판단표.
+
+| 상황 | 배치 | 이유 |
+|---|---|---|
+| 응답에 결과가 **필요** | 요청 인라인 | 사용자가 그 값을 기다린다 |
+| 응답 불필요 · 실패 시 재시도 (메일·알림·웹훅) | **잡** (`domain/jobs/`) | 응답 지연 제거 + 재시도(백오프·DLQ) |
+| 느리거나 불안정한 **외부 API** | **잡** | 이벤트 루프·응답 시간 보호 |
+| **CPU 무거운** 작업 (이미지 리사이즈·리포트·대량 연산) | **잡** | 루프 블로킹 = 이웃 요청 전부 정지 |
+| 트랜잭션 커밋 **파생 효과** | **이벤트 + 아웃박스** (`afterCommit`) | DB 확정과 정합 (롤백 시 발행 취소) |
+| **주기** 작업 (정리·집계·랭킹) | **`domain/schedule.ts`** | 요청과 무관한 시간축 · 리더 1인만 |
+
+**실무 신호**: 요청 중 수백 ms 이상 걸리는 일은 잡 후보. Node 는 싱글 스레드라
+무거운 작업 하나가 이웃 요청을 세운다. **"잡으로 뺀다 = `work` 프로세스로
+옮긴다"** — 인라인은 `serve`(웹)가, 잡·`afterCommit`·`schedule` 은 `work` 가
+처리하므로 웹 응답이 그 무게를 지지 않는다. `gaon doctor` 의 `async-offload`
+가 컨트롤러 인라인 메일·이미지 처리·외부 HTTP 를 경고로 잡는다(결정 103).
+
 ## 4. 검증 루프
 
 작업마다 실행한다:
@@ -163,7 +187,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 17종 (§2.2)
+gaon doctor       # 정적 검사 21종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)
@@ -171,8 +195,8 @@ gaon doctor       # 정적 검사 17종 (§2.2)
 | 명령 | 역할 |
 |---|---|
 | `gaon new <name>` | 프로젝트 스캐폴드 |
-| `gaon dev` | 통합 개발 오케스트레이션 (Docker·`.gaon` 재생성·워처) |
-| `gaon serve` / `work` / `hub` | 운영 프로세스 3종 (웹 · 워커 · 실시간 허브) |
+| `gaon dev` | 통합 개발 오케스트레이션 (Docker·`.gaon` 재생성·**코드 변경 감시·재시작**) |
+| `gaon serve` / `work` / `hub` | 운영 프로세스 3종 (웹 · 워커 · 실시간 허브) — **감시 없음** |
 | `gaon g <type> <name>` | 스캐폴드: `auth`·`controller`·`model`·`page`·`job` |
 | `gaon db <sub>` | `diff`·`migrate`(`down`)·`status`·`reset`·`seed` (`agents/data.md` §10) |
 | `gaon check` / `test` / `doctor` | 검증 루프 |
@@ -184,6 +208,11 @@ gaon doctor       # 정적 검사 17종 (§2.2)
 으로 더듬는 대신 프레임웍에게 직접 묻는다. `read_agent_doc` 은 §0
 카테고리 문서를 조회한다 (결정 40).
 
+**개발 중엔 `gaon dev`, 배포 실행은 `gaon serve`** (결정 98) — `gaon serve` 는
+빌드된 번들을 서빙하며 **코드 변경을 감시하지 않는다**(수정해도 반영 안 됨).
+개발 중이면 `gaon dev`(감시·재시작·`.gaon` 재생성 통합)를 쓴다. `serve` 는
+비-production 부팅 시 이 안내를 한 줄 출력한다.
+
 ## 5. npm 배포본 (2026-07-23 실측 · `npm view <pkg> version`)
 
 | 패키지 | 버전 | 역할 |