@gaonjs/cli 0.23.0 → 0.25.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/page-layout-breakpoint.d.ts

@@ -0,0 +1,8 @@
+import type { RuleReport } from './types.js';
+/** 소스에서 레이아웃 브레이크포인트 사용 위치(토큰·줄)를 모은다(단위 테스트 진입점). */
+export declare function usesLayoutBreakpoint(source: string): {
+    token: string;
+    line: number;
+}[];
+/** apps/<앱>/pages 를 훑어 페이지 레이아웃 브레이크포인트 사용을 경고로 낸다. */
+export declare function checkPageLayoutBreakpoint(cwd: string): Promise<RuleReport>;

package/dist/doctor/page-layout-breakpoint.js

@@ -0,0 +1,94 @@
+// @gaonjs/cli · doctor · 페이지 레이아웃 브레이크포인트 안내 (결정 107)
+//
+// 폭·여백·열 수 같은 레이아웃 반응형은 UI 킷 블록(PageShell·PageHeader …)이
+// 소유한다(결정 105·106·107). 페이지 파일이 레이아웃 브레이크포인트를 루트에서
+// 직접 쓰면 반응형 규칙이 여러 곳에 흩어져, "정답이 하나" 가 무너진다. 이 검사는
+// 그 사용을 **안내 경고(warning)** 로만 낸다 — 강제(error)가 아니다. 킷에 없는
+// 표현이면 Tailwind 유틸을 직접 써도 되므로(탈출구), 오탐을 줄이려 신호가 확실한
+// 레이아웃 유틸(반응형 flex-direction·grid 열 수)만 좁게 잡는다.
+//
+// 대상: apps/<앱>/pages/**/*.vue (페이지 파일만). shared/components/ui 의 킷 블록은
+// 반응형을 소유하므로 검사하지 않는다(그게 이 규칙의 목적).
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+/**
+ * 좁게 잡는 레이아웃 반응형 패턴: 반응형 접두사 + (flex-row/col · grid-cols-N/[).
+ * `sm:hidden`·`sm:text-lg`·`sm:px-6` 같은 흔한 반응형(표시·타이포·여백)은 잡지
+ * 않는다 — 오탐을 줄이려 페이지 레이아웃을 뒤집는 확실한 신호만 본다.
+ */
+const LAYOUT_BREAKPOINT = /\b(sm|md|lg|xl|2xl):(flex-(?:row|col)(?:-reverse)?|grid-cols-(?:\d+|\[))/;
+/** 소스에서 레이아웃 브레이크포인트 사용 위치(토큰·줄)를 모은다(단위 테스트 진입점). */
+export function usesLayoutBreakpoint(source) {
+    const out = [];
+    const lines = source.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const m = LAYOUT_BREAKPOINT.exec(lines[i]);
+        if (m)
+            out.push({ token: m[0], line: i + 1 });
+    }
+    return out;
+}
+/** apps/<앱>/pages 를 훑어 페이지 레이아웃 브레이크포인트 사용을 경고로 낸다. */
+export async function checkPageLayoutBreakpoint(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        const pagesDir = join(appsDir, app, 'pages');
+        for (const abs of await walkVueFiles(pagesDir)) {
+            const source = await readFile(abs, 'utf8').catch(() => '');
+            const hits = usesLayoutBreakpoint(source);
+            if (hits.length === 0)
+                continue;
+            const rel = relative(cwd, abs);
+            const first = hits[0];
+            issues.push({
+                rule: 'page-layout-breakpoint',
+                level: 'warning',
+                file: rel,
+                line: first.line,
+                message: `${rel} (line ${first.line})\n` +
+                    `  페이지가 레이아웃 브레이크포인트('${first.token}'${hits.length > 1 ? ` 외 ${hits.length - 1}건` : ''})를 직접 씁니다.\n` +
+                    `  반응형(폭·여백·열 수)은 UI 킷 블록이 책임집니다(결정 107).\n` +
+                    `→ shared/components/ui 의 블록(PageShell·PageHeader 등)으로 감싸 반응형을 킷에 두거나,\n` +
+                    `  킷에 없는 표현이면 그대로 둬도 됩니다 — 이 경고는 강제가 아닙니다(탈출구 유지).`,
+                detail: { token: first.token, count: hits.length },
+            });
+        }
+    }
+    return { rule: 'page-layout-breakpoint', issues };
+}
+/** 디렉터리 트리에서 .vue 파일 절대경로를 모은다(테스트·선언 제외 불필요 — .vue 만). */
+async function walkVueFiles(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' || e.name === 'dist')
+                    continue;
+                await walk(abs);
+            }
+            else if (e.isFile() && e.name.endsWith('.vue')) {
+                out.push(abs);
+            }
+        }
+    };
+    await walk(dir);
+    return out.sort();
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = (await readdir(dir, { withFileTypes: true }));
+        return entries.filter((e) => e.isDirectory()).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' | 'page-layout-breakpoint';
 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/ui-kit-wiring.js

@@ -1,10 +1,12 @@
-// @gaonjs/cli · doctor · UI 킷 배선 검사 (결정 76)
+// @gaonjs/cli · doctor · UI 킷 배선 검사 (결정 76 · 결정 105)
 //
-// 앱이 UI 킷 컴포넌트(apps/<앱>/components/ui/*)를 import 하는데 그 앱에
-// Tailwind 배선(apps/<앱>/style.css 의 @tailwind + main.ts 의 style.css import)이
-// 없으면, UI 킷이 쓰는 유틸 클래스(bg-primary·rounded-lg …)가 펼쳐지지 않아
-// 컴포넌트가 스타일 없이 렌더된다 — 컴파일은 통과하므로 check 로는 안 잡히는
-// 조용한 런타임 파손이다(결정 74·75·76). 이 검사가 그 상태를 경고로 낸다.
+// 앱이 UI 킷 컴포넌트(@shared/components/ui/* — 결정 105 로 shared 이전)를
+// import 하는데 그 앱에 Tailwind 배선(apps/<앱>/style.css 의 @tailwind +
+// main.ts 의 style.css import)이 없으면, UI 킷이 쓰는 유틸 클래스(bg-primary·
+// rounded-lg …)가 펼쳐지지 않아 컴포넌트가 스타일 없이 렌더된다 — 컴파일은
+// 통과하므로 check 로는 안 잡히는 조용한 런타임 파손이다(결정 74·75·76·105).
+// 이 검사가 그 상태를 경고로 낸다. 킷 위치와 무관하게 import 경로에 남는
+// 'components/ui/' 로 사용처를 잡으므로 @shared alias 도 그대로 감지된다.
 //
 // `gaon new`(web)·`gaon g app` 은 이제 배선을 함께 심으므로 정상 경로에서는
 // 걸리지 않는다. 이 규칙은 배선을 지웠거나 구버전 스캐폴드에서 만든 앱을 잡는
@@ -44,7 +46,9 @@ export async function checkUiKitWiring(cwd) {
 /** 앱 디렉터리를 재귀 스캔해 UI 킷을 import 하는 첫 .vue/.ts 파일(cwd 상대)을 찾는다. */
 async function findUiKitImporter(appDir, cwd) {
     for (const abs of await walkSources(appDir)) {
-        // components/ui 안의 컴포넌트 자체는 서로를 import 하므로 제외한다.
+        // 킷은 이제 shared/ 라 apps/ 스캔엔 안 들어오지만, 결정 105 이전의 앱별
+        // 사본(apps/<앱>/components/ui)이 남아 있으면 그 컴포넌트끼리의 상호 import 를
+        // 사용처로 오인하지 않도록 제외한다(마이그레이션 과도기 방어).
         if (abs.includes(`${join(appDir, 'components', 'ui')}`))
             continue;
         const source = await readFile(abs, 'utf8').catch(() => '');