@gaonjs/cli 0.23.0 → 0.24.0

package/README.md

@@ -1,9 +1,16 @@
 # @gaonjs/cli
 
-Gaon CLI 구현 — 제너레이터·스캐폴딩. M1 에서는 로드맵 출력 스텁입니다.
+Gaon CLI — `gaon` 명령. 프로젝트 스캐폴드(`gaon new`), 개발 스택 통합(`gaon dev`),
+제너레이터(`gaon g auth`·scaffold), 마이그레이션(`gaon db …`), 통합 검사
+(`gaon check`), 정적 검사(`gaon doctor` · 20종), 운영 부팅(`gaon serve`). 모든
+명령은 `--json` 출력을 지원합니다.
 
-> ⚠️ **개발 중 (v0.1.0 스텁).** 모든 명령은 `--json` 출력을 함께 제공합니다.
+이 패키지는 [`gaonjs`](https://www.npmjs.com/package/gaonjs) 파사드에 포함됩니다 —
+`gaonjs` 를 설치하면 `gaon` 명령을 쓸 수 있습니다.
 
-개발자는 이 패키지를 직접 설치하지 않습니다 — [`gaon`](https://www.npmjs.com/package/gaon) 하나만 설치하세요.
+```bash
+gaon new my-app && cd my-app && gaon dev
+```
 
 - 홈페이지 / 문서: https://gaonjs.dev
+- 라이선스: MIT

package/dist/commands/db.js

@@ -57,8 +57,8 @@ export async function runDbCommand(subcommand, opts = {}) {
             return r.exitCode;
         }
         if (subcommand === 'seed') {
-            // 기존 M8 로직 — 옵션 shape 이 다르므로 필요한 것만 전달.
-            const r = await runDbSeedCommand({ root: cwd, json });
+            // 결정 101: seed 도 diff/migrate 와 같은 설정 해석 경로(config → env)를 쓴다.
+            const r = await runDbSeedCommand({ root: cwd, json, configPath, dbKey });
             emit(r.text, r.json);
             return r.exitCode;
         }

package/dist/db.d.ts

@@ -3,8 +3,12 @@ export interface DbSeedOptions {
     readonly json?: boolean;
     /** 도메인 루트(domain/ 의 부모). 기본 cwd. */
     readonly root?: string;
-    /** DB URL 오버라이드. 생략 시 env GAON_DATABASE_URL. */
+    /** DB URL 오버라이드(reset 내부 호출 등). 생략 시 config → GAON_DATABASE_URL. */
     readonly databaseUrl?: string;
+    /** --config <path> 오버라이드. 없으면 root/gaon.config.ts 관례. */
+    readonly configPath?: string;
+    /** 커넥션 키(§4.5). 기본 'main'. */
+    readonly dbKey?: string;
 }
 /** domain/seed.ts 의 default export 를 읽어 SeedDef 를 돌려준다(없으면 안내 에러). */
 export declare function loadSeed(root: string): Promise<SeedDef>;
@@ -15,6 +19,7 @@ export interface DbSeedResult {
 }
 /**
  * `gaon db seed` — main 커넥션을 연결하고 domain/seed.ts 를 실행한다.
- * 커넥션 정리(destroyAllConnections)는 항상 수행한다.
+ * 커넥션 해석은 diff·migrate·status·reset 과 같은 경로(resolveDbTarget)를
+ * 쓴다(결정 101). 커넥션 정리는 항상 수행한다.
  */
 export declare function runDbSeedCommand(opts?: DbSeedOptions): Promise<DbSeedResult>;

package/dist/db.js

@@ -1,15 +1,17 @@
 // @gaonjs/cli · `gaon db seed` (§7 M8 — domain/seed.ts 실행)
 //
 // 관례: `domain/seed.ts` 의 default export(seed 정의)를 실행한다. 커넥션은
-// `gaon work` 와 **같은 관례**로 연결한다 — `GAON_DATABASE_URL` 로 main
-// 커넥션을 세운다(§4.5 멀티 커넥션의 gaon.config.ts 전체 로더는 M9 CLI 완성).
-// 모든 명령은 --json 을 함께 낸다(CLAUDE.md §4).
+// diff·migrate·status·reset 과 **같은 해석 경로**(resolveDbTarget)로 연결한다
+// (결정 101). 우선순위: databaseUrl 오버라이드 > gaon.config.ts db.<키> >
+// GAON_DATABASE_URL. 과거엔 seed 만 GAON_DATABASE_URL 만 봐서, config 에
+// db.main 만 선언한 프로젝트는 migrate 는 되는데 seed 만 실패했다(.env 진입점
+// 통일 wave 동형). 모든 명령은 --json 을 함께 낸다(CLAUDE.md §4).
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { env, EnvError } from '@gaonjs/core';
 import { createDb, registerConnection, destroyAllConnections, isSeedDef, } from '@gaonjs/data';
 import { registerTsResolve } from './tsResolve.js';
+import { resolveDbTarget } from './db/resolve.js';
 /** DB URL 에서 어댑터를 추정한다(gaon work 와 동일 규칙). */
 function dbConfigFromUrl(url) {
     if (url.startsWith('mysql://') || url.startsWith('mariadb://')) {
@@ -34,29 +36,40 @@ export async function loadSeed(root) {
     }
     return mod.default;
 }
+const SEED_OK = {
+    text: `  gaon db seed · 완료 — domain/seed.ts 실행됨`,
+    json: { command: 'seed', ok: true },
+};
 /**
  * `gaon db seed` — main 커넥션을 연결하고 domain/seed.ts 를 실행한다.
- * 커넥션 정리(destroyAllConnections)는 항상 수행한다.
+ * 커넥션 해석은 diff·migrate·status·reset 과 같은 경로(resolveDbTarget)를
+ * 쓴다(결정 101). 커넥션 정리는 항상 수행한다.
  */
 export async function runDbSeedCommand(opts = {}) {
     const root = opts.root ?? process.cwd();
-    const dbUrl = opts.databaseUrl ?? env.optional('GAON_DATABASE_URL');
-    if (!dbUrl) {
-        throw new EnvError(`환경변수 GAON_DATABASE_URL 가 설정되지 않았습니다(시드에 DB 연결 필요).\n` +
-            `  → .env 에 다음 줄을 추가하고 다시 실행하세요:\n` +
-            `      GAON_DATABASE_URL=postgres://user:pass@localhost:5432/mydb`);
+    const dbKey = opts.dbKey ?? 'main';
+    // databaseUrl 명시 오버라이드(reset 내부 호출) — URL 로 직접 커넥션을 세운다.
+    if (opts.databaseUrl) {
+        const cfg = dbConfigFromUrl(opts.databaseUrl);
+        registerConnection(dbKey, createDb(cfg), cfg.adapter);
+        try {
+            const def = await loadSeed(root);
+            await def.run();
+            return { exitCode: 0, ...SEED_OK };
+        }
+        finally {
+            await destroyAllConnections();
+        }
     }
-    registerConnection('main', createDb(dbConfigFromUrl(dbUrl)), dbConfigFromUrl(dbUrl).adapter);
+    // 그 외 — migrate 와 같은 해석 경로: gaon.config.ts db.<키> → GAON_DATABASE_URL.
+    // config 도 env 도 없으면 resolveDbTarget 이 수리 안내 에러를 던진다(§7.5.3).
+    const target = await resolveDbTarget({ cwd: root, dbKey, configPath: opts.configPath });
     try {
         const def = await loadSeed(root);
         await def.run();
-        return {
-            exitCode: 0,
-            text: `  gaon db seed · 완료 — domain/seed.ts 실행됨`,
-            json: { command: 'seed', ok: true },
-        };
+        return { exitCode: 0, ...SEED_OK };
     }
     finally {
-        await destroyAllConnections();
+        await target.close();
     }
 }

package/dist/doctor/async-offload.d.ts

@@ -0,0 +1,23 @@
+import type { RuleReport } from './types.js';
+/** app.config 소스가 JWT/API 앱인가 (외부 HTTP arm 제외 대상 · csrf-wiring 과 동일 판정). */
+export declare function isApiApp(appConfigSource: string): boolean;
+/** 파일이 메일 SDK 를 직접 import 하는가(단위 테스트 진입점). */
+export declare function importsMailSdk(source: string): boolean;
+/** 파일이 이미지 처리 라이브러리를 직접 import 하는가(단위 테스트 진입점). */
+export declare function importsImageLib(source: string): boolean;
+/** 액션 본문 텍스트에 리터럴 외부 URL 로의 fetch/axios 호출이 있는가(단위 테스트 진입점). */
+export declare function callsExternalHttp(actionBody: string): boolean;
+/** apps/ 의 컨트롤러를 훑어 요청 경로 인라인 무거운/외부 작업을 경고로 낸다. */
+export declare function checkAsyncOffload(cwd: string): Promise<RuleReport>;
+interface PageAction {
+    readonly name: string;
+    readonly line: number;
+    readonly body: string;
+}
+/**
+ * controller({ … }) 안에서 **페이지 액션**(return this.render/redirect 을 담는
+ * 액션)만 골라 이름·라인·본문 텍스트를 낸다. JSON 액션(반환값=응답 · render/
+ * redirect 없음)은 제외한다 — 외부 프록시/집계가 정당한 자리라 C arm 대상 밖.
+ */
+export declare function pageActions(file: string, source: string): PageAction[];
+export {};

package/dist/doctor/async-offload.js

@@ -0,0 +1,236 @@
+// @gaonjs/cli · doctor · 요청 경로 인라인 무거운/외부 작업 검출 (결정 102·103 · 경고)
+//
+// 비동기 배치 판단표(결정 102 · AGENTS §3.5 · agents/async.md 서두)의 강제 장치다.
+// 컨트롤러 액션 안에서 "응답에 필요 없는데 무겁거나 느린 일" 을 동기로 하면 웹
+// 응답이 그 무게를 진다 — Node 는 싱글 스레드라 이웃 요청까지 전부 세운다. 정답은
+// `domain/jobs/` 잡으로 빼고 `.later()` 로 발행하는 것(§3.5 · async.md §1).
+//
+// 검출 3종(대표 인라인 패턴):
+//   A) 메일 SDK 직접 import (nodemailer·resend·@sendgrid/mail·mailgun) — 컨트롤러는
+//      잡 발행만 (async.md 함정 · async-flow forbidden 과 동일 집합). 앱 종류 무관.
+//   B) 이미지/미디어 처리 라이브러리 import (sharp·jimp·gm) — CPU 무거운 작업이
+//      요청 경로에 있다. 앱 종류 무관.
+//   C) 외부 HTTP 호출 (fetch/axios 에 **리터럴 `http(s)://` URL**) — 페이지 액션
+//      안에서. 느린/불안정 외부 호출은 응답 시간을 보호하려면 잡으로.
+//
+// 오탐 설계(결정 103 · response-mixing 교훈 "확신 없으면 잡지 않는다"):
+//   · **API 앱 제외** — app.config 에 `strategy: 'jwt'` 면 외부 API 호출이 정당
+//     (§3 데이터 경로 4종 · 외부 공개 API 앱). 해당 앱은 C(외부 HTTP)를 끈다.
+//   · **JSON 액션 제외** — 반환값=응답 액션(E-3)은 프록시/집계일 수 있어 C 제외.
+//     C 는 페이지 액션(render/redirect)에만 적용한다.
+//   · **리터럴 외부 URL 만** — 변수 URL·상대/내부 경로(`/...`)·`localhost`·
+//     `127.0.0.1` 은 정적 판별 불가/내부 호출이라 **잡지 않는다**(빠른 내부 호출
+//     오탐 방지). internal-anchor 가 루트-상대/템플릿리터럴만 잡은 것과 동형.
+//   · 주석은 라인 보존 스트립으로 제외 — "이렇게 쓰지 말라" 설명 주석 오탐 방지.
+//
+// 판정은 소스 텍스트 + TS AST(액션 경계)만 본다 — 파일을 실행하지 않는다.
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import ts from 'typescript';
+// ── 검출 시그니처 ─────────────────────────────────────────────────────
+/** 메일 SDK 모듈 import (컨트롤러 = 잡 발행만 · async.md 함정 · async-flow forbidden 동일 집합). */
+const MAIL_SDK_IMPORT = /import\s+[\s\S]*?\bfrom\s+['"](?:nodemailer|resend|@sendgrid\/mail|mailgun[.\-/][^'"]*|mailgun)['"]/;
+/** 이미지/미디어 처리 라이브러리 import (CPU 무거운 작업). */
+const IMAGE_LIB_IMPORT = /import\s+[\s\S]*?\bfrom\s+['"](?:sharp|jimp|gm)['"]/;
+/**
+ * 페이지 액션 본문 안 외부 HTTP 호출 — 리터럴 `http(s)://` URL 만.
+ * localhost·127.0.0.1(내부)은 음성 룩어헤드로 제외한다. 변수 URL·상대 경로는
+ * 매치하지 않는다(정적 판별 불가 = 잡지 않는다).
+ */
+const EXTERNAL_HTTP = [
+    // fetch('https://...') · fetch(`https://...`)
+    /\bfetch\s*\(\s*[`'"]https?:\/\/(?!localhost|127\.0\.0\.1)/i,
+    // axios('https://...') · axios.get('https://...') · axios({ url: 'https://...' })
+    /\baxios\s*(?:\.\s*(?:get|post|put|patch|delete|request|head)\s*)?\(\s*(?:\{[\s\S]*?\burl\s*:\s*)?[`'"]https?:\/\/(?!localhost|127\.0\.0\.1)/i,
+];
+/** app.config 소스가 JWT/API 앱인가 (외부 HTTP arm 제외 대상 · csrf-wiring 과 동일 판정). */
+export function isApiApp(appConfigSource) {
+    return /strategy\s*:\s*['"]jwt['"]/.test(appConfigSource);
+}
+/** 파일이 메일 SDK 를 직접 import 하는가(단위 테스트 진입점). */
+export function importsMailSdk(source) {
+    return MAIL_SDK_IMPORT.test(stripComments(source));
+}
+/** 파일이 이미지 처리 라이브러리를 직접 import 하는가(단위 테스트 진입점). */
+export function importsImageLib(source) {
+    return IMAGE_LIB_IMPORT.test(stripComments(source));
+}
+/** 액션 본문 텍스트에 리터럴 외부 URL 로의 fetch/axios 호출이 있는가(단위 테스트 진입점). */
+export function callsExternalHttp(actionBody) {
+    const stripped = stripComments(actionBody);
+    return EXTERNAL_HTTP.some((re) => re.test(stripped));
+}
+// ── 검사 본체 ─────────────────────────────────────────────────────────
+/** apps/ 의 컨트롤러를 훑어 요청 경로 인라인 무거운/외부 작업을 경고로 낸다. */
+export async function checkAsyncOffload(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        // 앱 종류 판정 — API 앱이면 외부 HTTP arm 을 끈다(오탐 방지 · 결정 103).
+        const acPath = join(appsDir, app, 'app.config.ts');
+        const acSource = existsSync(acPath) ? await readFile(acPath, 'utf8') : '';
+        const apiApp = isApiApp(acSource);
+        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 rel = relative(cwd, full);
+            const source = await readFile(full, 'utf8');
+            const clean = stripComments(source);
+            // A) 메일 SDK import — 앱 종류 무관 경고(컨트롤러는 잡 발행만).
+            const mailImport = firstMatch(clean, MAIL_SDK_IMPORT);
+            if (mailImport) {
+                issues.push(offloadIssue(rel, lineOf(source, mailImport.index), 'mail', app, `메일 SDK 직접 import (${mailImport.text.trim().slice(0, 60)}…)`, '메일 발송은 응답에 필요 없고 실패 시 재시도가 필요한 일'));
+            }
+            // B) 이미지 처리 라이브러리 import — 앱 종류 무관 경고(CPU 무거운 작업).
+            const imgImport = firstMatch(clean, IMAGE_LIB_IMPORT);
+            if (imgImport) {
+                issues.push(offloadIssue(rel, lineOf(source, imgImport.index), 'image', app, `이미지 처리 라이브러리 import (${imgImport.text.trim().slice(0, 60)}…)`, '이미지 리사이즈/변환은 CPU 무거운 작업 — 루프를 막아 이웃 요청을 세운다'));
+            }
+            // C) 외부 HTTP — 페이지 액션(render/redirect)에서만 · API 앱 제외.
+            if (apiApp)
+                continue;
+            for (const action of pageActions(full, source)) {
+                if (!callsExternalHttp(action.body))
+                    continue;
+                issues.push(offloadIssue(rel, action.line, 'http', app, `페이지 액션 '${action.name}' 안에서 외부 HTTP 호출(리터럴 URL)`, '느리거나 불안정한 외부 호출이 응답 시간에 그대로 실린다'));
+            }
+        }
+    }
+    return { rule: 'async-offload', issues };
+}
+/** 공통 경고 메시지 조립 — §7.5.3(에러 = 수리 안내서)대로 "→ 어떻게 고치라" 까지. */
+function offloadIssue(rel, line, kind, app, what, why) {
+    const apiHint = kind === 'http'
+        ? `\n→ 외부 공개 API 앱(모바일·서드파티)이라 외부 호출이 정당하면 apps/${app}/app.config.ts 에 auth: { strategy: 'jwt', ... } 를 선언하세요(이 경고 제외).`
+        : '';
+    return {
+        rule: 'async-offload',
+        level: 'warning',
+        file: rel,
+        line,
+        message: `요청 경로 인라인 작업: ${rel}:${line} · ${what}. ${why} — ` +
+            `Node 는 싱글 스레드라 무거운/느린 작업 하나가 이웃 요청을 전부 세웁니다(결정 102 판단표).\n` +
+            `→ domain/jobs/ 아래 잡으로 빼고 컨트롤러에서는 .later() 로 발행하세요:\n` +
+            `   // domain/jobs/<camel>.ts — export const <Pascal> = job(async (…) => { …무거운 일… }, { retries: 3 })\n` +
+            `   // 컨트롤러: await <Pascal>.later(…)  (응답은 즉시 반환 · 처리는 gaon work 프로세스)\n` +
+            `→ 커밋 뒤에만 나가야 하면 서비스 afterCommit() 또는 아웃박스(agents/async.md §4).` +
+            apiHint,
+        detail: { app, kind },
+    };
+}
+/**
+ * controller({ … }) 안에서 **페이지 액션**(return this.render/redirect 을 담는
+ * 액션)만 골라 이름·라인·본문 텍스트를 낸다. JSON 액션(반환값=응답 · render/
+ * redirect 없음)은 제외한다 — 외부 프록시/집계가 정당한 자리라 C arm 대상 밖.
+ */
+export function pageActions(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const out = [];
+    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 name = actionName(prop);
+                    const body = actionBodyNode(prop);
+                    if (!name || !body)
+                        continue;
+                    if (!rendersPage(body))
+                        continue; // JSON/void 액션 제외
+                    const { line } = sf.getLineAndCharacterOfPosition(prop.getStart(sf));
+                    out.push({ name, line: line + 1, body: body.getText(sf) });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return out;
+}
+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 actionBodyNode(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/this.redirect 를 하나라도 담는가(= 페이지 액션). */
+function rendersPage(body) {
+    let renders = false;
+    const visit = (node) => {
+        if (renders)
+            return;
+        // 중첩 함수(콜백)로 내려가지 않는다 — 액션 자신의 응답만 본다.
+        if (node !== body &&
+            (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node))) {
+            return;
+        }
+        if (ts.isPropertyAccessExpression(node) &&
+            node.expression.kind === ts.SyntaxKind.ThisKeyword &&
+            (node.name.text === 'render' || node.name.text === 'redirect')) {
+            renders = true;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(body);
+    return renders;
+}
+// ── 텍스트 유틸 ───────────────────────────────────────────────────────
+/** 라인 보존 주석 스트립 — 안티패턴을 설명하는 주석이 오탐을 내지 않도록. */
+function stripComments(source) {
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
+        .replace(/(^|[^:])\/\/[^\n]*/g, (m, p1) => p1 + ' '.repeat(m.length - p1.length));
+}
+function firstMatch(source, re) {
+    const m = re.exec(source);
+    return m ? { index: m.index, text: m[0] } : undefined;
+}
+/** 문자 오프셋 → 1-기반 라인 번호. */
+function lineOf(source, index) {
+    return source.slice(0, index).split('\n').length;
+}
+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/pageprops-destructure.d.ts

@@ -0,0 +1,5 @@
+import type { RuleReport } from './types.js';
+/** 소스에 pageProps() 구조분해가 있는지(단위 테스트 진입점 · 주석은 제외). */
+export declare function usesPagePropsDestructure(source: string): boolean;
+/** apps/ 의 .vue 를 훑어 pageProps() 구조분해를 경고로 낸다. */
+export declare function checkPagePropsDestructure(cwd: string): Promise<RuleReport>;

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' | 'csrf-wiring' | 'internal-anchor';
+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,6 +1,6 @@
 // @gaonjs/cli · doctor 공용 타입 (M9-E · M9-E-Fix · M9-E 확장 · E-5)
 //
-// 19 검사(전체 목록은 AGENTS §2.2 · doctor.ts `ALL_RULES`)가 모두 이 DoctorCheck
+// 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

@@ -17,6 +17,8 @@ export { usesAuthSurface, hasAuthWiring, hasSessionWiring, checkAuthWiring, } fr
 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 확장)
  *
- * 19 검사를 조립한다:
+ * 21 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -21,6 +21,8 @@
  * 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)를 위해 반드시 파싱 가능한
@@ -52,6 +54,8 @@ 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';
@@ -72,10 +76,12 @@ export { usesAuthSurface, hasAuthWiring, hasSessionWiring, checkAuthWiring, } fr
 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) = 19개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 21개 모두.
  */
 const ALL_RULES = [
     'response-mixing',
@@ -97,6 +103,8 @@ const ALL_RULES = [
     'method-override',
     'csrf-wiring',
     'internal-anchor',
+    'pageprops-destructure',
+    'async-offload',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -118,6 +126,8 @@ const CHECKERS = {
     'method-override': checkMethodOverride,
     'csrf-wiring': checkCsrfWiring,
     'internal-anchor': checkInternalAnchor,
+    'pageprops-destructure': checkPagePropsDestructure,
+    'async-offload': checkAsyncOffload,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/index.js

@@ -101,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        정적 검사 (19 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커)",
+        "    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)",
@@ -147,6 +147,7 @@ export function parseDoctorChecks(argv) {
         "shared-composable-purity",
         "no-auto-import",
         "csrf-wiring",
+        "async-offload",
     ];
     const isKnown = (s) => known.includes(s);
     const out = [];

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

@@ -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">

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

@@ -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">

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` 검사 19종
+### 2.2 `gaon doctor` 검사 21종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -125,6 +125,8 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 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 판단표
 
@@ -158,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. 검증 루프
 
 작업마다 실행한다:
@@ -165,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       # 정적 검사 19종 (§2.2)
+gaon doctor       # 정적 검사 21종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)

package/dist/templates/project/agents/async.md.tpl

@@ -5,6 +5,54 @@
 > 대상 패키지: `@gaonjs/async` (파사드 import 는 `gaonjs/async`). 백본 = NATS JetStream ·
 > 실행은 워커 프로세스(`gaon work`).
 
+## 비동기 배치의 One Way 판단표 (결정 102)
+
+`agents/data.md` §5.3 / `AGENTS.md` §3.1 이 **서버 로직을 어느 층**(모델·서비스·
+컨트롤러)에 둘지 정한다면, 이 표는 그 로직을 **동기(요청 인라인)로 둘지 비동기
+(잡·이벤트·스케줄)로 뺄지**를 정한다 — 같은 "정답이 하나" 원칙의 비동기 축이다.
+
+| 상황 | 배치 | 이유 |
+|---|---|---|
+| 응답에 결과가 **필요** | 요청 인라인 | 사용자가 그 값을 기다린다 (조회·검증·생성 결과) |
+| 응답 불필요 · 실패 시 재시도 (메일·알림·웹훅) | **잡** (`domain/jobs/`) | 응답 지연 제거 + 재시도 배터리(백오프·DLQ) |
+| 느리거나 불안정한 **외부 API** 호출 | **잡** | 이벤트 루프·응답 시간 보호 (외부 지연이 응답에 새지 않음) |
+| **CPU 무거운** 작업 (이미지 리사이즈·리포트·대량 연산) | **잡** | 루프 블로킹 = 그 사이 이웃 요청 전부 정지 |
+| 트랜잭션 커밋에 딸린 **파생 효과** | **이벤트 + 아웃박스** (`afterCommit`) | DB 확정과 정합 (롤백 시 발행도 취소 · §4) |
+| **주기** 작업 (정리·집계·랭킹) | **`domain/schedule.ts`** | 요청과 무관한 시간축 · 리더 1인만 실행 |
+
+**실무 신호**: 요청 처리 중 **수백 ms 이상** 걸리는 일은 잡 후보다. Node 는 싱글
+스레드라 무거운 작업 하나가 워커 앞에 이웃 요청을 전부 세운다(head-of-line
+blocking). 확신이 안 서면 "응답에 이 결과가 필요한가?" 만 묻는다 — 아니면 잡이다.
+
+**"잡으로 뺀다 = work 프로세스로 옮긴다".** 운영 프로세스는 3종(§6): `gaon serve`
+(웹 요청) · `gaon work`(잡·리스너·스케줄·아웃박스 릴레이) · `gaon hub`(실시간).
+인라인 코드는 `serve` 안에서 요청 스레드로 돈다. `.later()`·`afterCommit`·
+`schedule.ts` 로 뺀 일은 **`work` 프로세스**가 별도로 처리하므로 웹 응답이 그
+무게를 지지 않는다. 그래서 "느리다/무겁다/실패해도 재시도" 는 전부 `work` 행(行)이다.
+
+각 배치의 정본 예시 (전체 시그니처·옵션은 아래 §1·§4·§5):
+
+```ts
+// 잡 — 응답과 분리해 발행 (메일·알림·이미지 처리 등). 컨트롤러/서비스에서:
+await SendWelcomeMail.later(user.id)   // domain/jobs/sendWelcomeMail.ts (§1)
+```
+
+```ts
+// 파생 효과 — 커밋 뒤에만 나가야 하는 발행은 서비스 afterCommit (§4 아웃박스).
+export const RegisterUser = service(async (input: RegisterInput) => {
+  const user = await User.create(input)
+  afterCommit(() => ResizeAvatar.later(user.id))  // 커밋 성공 후에만 발행
+  return user
+})
+```
+
+```ts
+// 주기 작업 — domain/schedule.ts · 대상은 항상 잡 (§5 · 인라인 함수 금지).
+export default schedule((s) => {
+  s.cron('0 9 * * 1', SendWeeklyReport)  // 매주 월 09:00 · 리더 1인만
+})
+```
+
 ## 정본 규칙
 
 ### 1. 잡 (`job()`) (`packages/async/src/jobs.ts:146-185`)
@@ -209,6 +257,11 @@ async create() {
 
 - **컨트롤러에서 메일·외부 발송 직접 호출 = 함정** — 컨트롤러는 잡
   발행만. nodemailer·resend·@sendgrid/mail 직접 import 금지.
+- **무거운/느린 작업을 요청 인라인에 두면 함정** (판단표 · 결정 102) —
+  이미지 리사이즈(sharp·jimp)·외부 API 호출을 컨트롤러 액션 안에서 동기로
+  하면 응답이 그 무게를 진다. `domain/jobs/` 잡으로 빼고 `.later()` 로 발행한다.
+  `gaon doctor` 의 `async-offload` 가 이 인라인 패턴을 경고로 잡는다(결정 103 ·
+  JSON/API 앱의 정당한 외부 호출은 오탐 방지로 제외).
 - **클래스형 잡·데코레이터(`@Job`·`@Processor`) 금지** — `job()` 함수형만.
 - **잡 파일 위치는 `domain/jobs/`** — 앱 폴더가 아니다 (잡은 도메인
   소속 · 어느 앱에서든 큐잉).
@@ -225,6 +278,8 @@ async create() {
 
 | 결정 | 내용 |
 |---|---|
+| 결정 102 | 비동기 배치 One Way 판단표 (동기 인라인 vs 잡/이벤트/스케줄 · 서두 표) |
+| 결정 103 | doctor `async-offload` 검사 (컨트롤러 인라인 메일·이미지·외부 HTTP 경고) |
 | 결정 32 | 잡 발행 위치 자유 (컨트롤러·서비스·리스너 모두 정합) |
 | 결정 42 | 비동기 테스트 헬퍼 `expectJobProcessed` (`agents/testing.md`) |
 | §7 | 비동기 배터리 원문 (백오프 기본값 = M7 벤치마크 확정) |

package/dist/templates/project/agents/frontend.md.tpl

@@ -31,6 +31,13 @@ const props = pageProps<'web:posts#index'>()
 </template>
 ```
 
+- **변수로 받아 `props.x` 로 접근 — 구조분해 금지** (결정 99). `pageProps()` 는
+  반응형 프록시라, 같은 페이지로의 리다이렉트/리로드로 서버가 새 props 를 주면
+  (댓글 작성·삭제 등) 재마운트 없이 화면이 즉시 갱신된다. 하지만
+  `const { posts } = pageProps<...>()` 처럼 구조분해하면 그 순간 값을 한 번
+  읽어 **반응성이 끊긴다**(Vue `defineProps` 를 구조분해하면 안 되는 것과 같은
+  함정). 항상 `const props = pageProps<...>()` 로 받아 `props.posts` 로 쓴다.
+  구조분해는 doctor **pageprops-destructure** 가 잡는다(경고).
 - **라우트 키** = `<app>:<controller>#<action>` (앱 폴더명 · 컨트롤러 파일명
   stem · 소문자 복수 · 결정 55). `apps/web/controllers/posts.ts` 의 `index`
   액션 → `'web:posts#index'`.

package/dist/templates/project/agents/web.md.tpl

@@ -155,12 +155,13 @@ redirect 로 처리한다 — 전체 페이지 리로드도, 별도 REST 엔드
 
 ```ts
 // 로그인 폼 — 제출은 Inertia SPA 방식, 서버는 redirect 로 답한다.
-const { error, csrf } = pageProps<'web:session#new'>()
-const form = useForm({ email: '', password: '', _csrf: csrf })
-// <form @submit.prevent="form.post('/session')">
+// pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
+const props = pageProps<'web:session#new'>()
+const form = useForm({ email: '', password: '', _csrf: props.csrf })
+// <form @submit.prevent="form.post('/session')">  ·  실패 시 {{ props.error }} 가 반응형으로 갱신
 
 // HTML <form> 이 못 보내는 메서드(DELETE 등)는 router 로 보낸다.
-router.delete('/session', { headers: { 'x-csrf-token': csrf } })
+router.delete('/session', { headers: { 'x-csrf-token': props.csrf } })
 ```
 
 `?_method=DELETE` 같은 우회는 **서버가 해석하지 않는다** — POST 로 나가

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -28,11 +28,11 @@
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
     "@gaonjs/async": "0.6.1",
-    "@gaonjs/data": "0.9.1",
-    "@gaonjs/web": "0.7.1",
+    "@gaonjs/web": "0.7.2",
+    "@gaonjs/config": "0.5.3",
     "@gaonjs/core": "0.2.1",
-    "@gaonjs/config": "0.5.2",
-    "@gaonjs/mail": "0.1.3"
+    "@gaonjs/mail": "0.1.3",
+    "@gaonjs/data": "0.9.2"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""

package/dist/templates/auth/app.ts.tpl

@@ -1,29 +0,0 @@
-// 웹 앱 팩토리 — gaon g auth 스캐폴드. createWebApp 으로 세션·인증을 배선한다.
-import { createApp, type AppSessionOptions } from 'gaonjs/web'
-import appRoutes from './routes.js'
-import session from './controllers/session.js'
-import registration from './controllers/registration.js'
-import dashboard from './controllers/dashboard.js'
-import { loadUser } from './auth.js'
-
-export interface WebAppDeps {
-  /** 세션 설정 — { redisUrl, secret } (또는 redis 인스턴스). */
-  readonly session: AppSessionOptions
-  /** 서명 쿠키/CSRF 용 비밀. */
-  readonly cookieSecret?: string
-}
-
-export function createWebApp(deps: WebAppDeps) {
-  return createApp({
-    apps: [
-      {
-        name: '{{APP_NAME}}',
-        routes: appRoutes,
-        controllers: { session, registration, dashboard },
-        session: deps.session,
-        auth: { loadUser, loginRedirect: '/session/new' },
-      },
-    ],
-    cookieSecret: deps.cookieSecret,
-  })
-}

package/dist/templates/auth/server.ts.tpl

@@ -1,14 +0,0 @@
-// 서버 진입점 — gaon g auth 스캐폴드. `node dist/server.js` 로 실행.
-import { createWebApp } from './apps/{{APP_NAME}}/app.js'
-
-const app = await createWebApp({
-  session: {
-    redisUrl: process.env.REDIS_URL ?? 'redis://127.0.0.1:6379',
-    secret: process.env.SESSION_SECRET ?? 'change-me-to-a-32+char-random-secret!!',
-  },
-  cookieSecret: process.env.COOKIE_SECRET,
-})
-
-const port = Number(process.env.PORT ?? 3000)
-await app.listen({ port, host: '0.0.0.0' })
-console.log(`web 앱이 http://localhost:${port} 에서 실행 중입니다.`)