@gaonjs/cli 0.21.2 → 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/csrf-wiring.d.ts

@@ -0,0 +1,5 @@
+import type { RuleReport } from './types.js';
+/** routes.ts 소스에 상태 변경(비-GET) 라우트가 있는지 판정한다(단위 테스트 진입점). */
+export declare function hasStateChangingRoutes(routesSource: string): boolean;
+/** apps/ 를 훑어 CSRF/세션 미배선(비-GET 라우트 + session 없음)을 경고로 낸다. */
+export declare function checkCsrfWiring(cwd: string): Promise<RuleReport>;

package/dist/doctor/csrf-wiring.js

@@ -0,0 +1,72 @@
+// @gaonjs/cli · doctor · CSRF/세션 배선 검사 (결정 93)
+//
+// 규칙 8(§2.5.1): 보안 기본값(CORS·rate limit·CSRF)은 코어에서 기본 켬이다.
+// CSRF 는 세션 위에 얹힌다(session.ts) — 세션이 없으면 CSRF 토큰을 저장·검증할
+// 곳이 없어 상태 변경 요청(POST/PUT/PATCH/DELETE)이 **무방비**로 통과한다.
+//
+// 이 검사는 앱 routes.ts 에 비-GET 라우트가 있는데 그 앱 app.config.ts 에
+// session 배선이 없으면 경고한다 — 컴파일은 통과하지만 CSRF 가 실질적으로 꺼진
+// 상태다. JWT/API 앱(strategy:'jwt')은 토큰 인증이라 CSRF 대상이 아니므로 제외한다.
+//
+// 판정은 소스 텍스트 기반(가벼운 정적 검사) — routes.ts·app.config.ts 를 실행하지
+// 않는다. gaon new 스캐폴드는 web 앱에 세션을 기본 배선하므로(결정 93) 관례를
+// 따르면 이 경고는 나오지 않는다.
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { hasSessionWiring } from './auth-wiring.js';
+/** routes.ts 소스에 상태 변경(비-GET) 라우트가 있는지 판정한다(단위 테스트 진입점). */
+export function hasStateChangingRoutes(routesSource) {
+    // r.post('/x', ...) · r.put/patch/delete — 메서드 + 경로 문자열.
+    if (/\.\s*(post|put|patch|delete)\s*\(\s*['"]/.test(routesSource))
+        return true;
+    // resource(s)('posts') — 리소스 라우트는 create/update/destroy(POST/PUT/DELETE)를 만든다.
+    if (/\.\s*resources?\s*\(\s*['"]/.test(routesSource))
+        return true;
+    return false;
+}
+/** apps/ 를 훑어 CSRF/세션 미배선(비-GET 라우트 + session 없음)을 경고로 낸다. */
+export async function checkCsrfWiring(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        const routesPath = join(appsDir, app, 'routes.ts');
+        const routesSource = await readFile(routesPath, 'utf8').catch(() => undefined);
+        if (routesSource === undefined)
+            continue;
+        if (!hasStateChangingRoutes(routesSource))
+            continue;
+        const acPath = join(appsDir, app, 'app.config.ts');
+        const acRel = relative(cwd, acPath);
+        const acSource = existsSync(acPath) ? await readFile(acPath, 'utf8') : undefined;
+        // JWT/API 앱은 토큰 인증 — CSRF 대상 아님(제외).
+        const jwt = acSource != null && /strategy\s*:\s*['"]jwt['"]/.test(acSource);
+        if (jwt)
+            continue;
+        if (acSource != null && hasSessionWiring(acSource))
+            continue;
+        issues.push({
+            rule: 'csrf-wiring',
+            level: 'warning',
+            file: `apps/${app}/routes.ts`,
+            message: `CSRF 미배선: apps/${app} 에 비-GET 라우트(POST/PUT/PATCH/DELETE)가 있는데 ` +
+                `${acRel} 에 session 배선이 없습니다 — CSRF 는 세션 위에 얹히므로(규칙 8 · §2.5.1) ` +
+                `이대로면 상태 변경 요청이 CSRF 검증 없이 통과합니다(결정 93).\n` +
+                `→ apps/${app}/app.config.ts 의 defineAppConfig({...}) 에 다음을 추가하세요:\n` +
+                `   session: { secret: process.env.SESSION_SECRET ?? '32자 이상 비밀' }\n` +
+                `→ 루트 gaon.config.ts 에 redis: { url: process.env.REDIS_URL } 이 켜져 있는지 확인하세요(세션 스토어).\n` +
+                `→ 토큰 인증 API 앱이라면 app.config 에 auth: { strategy: 'jwt', ... } 를 선언하세요(CSRF 대상 제외).`,
+            detail: { app },
+        });
+    }
+    return { rule: 'csrf-wiring', issues };
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/doctor/internal-anchor.d.ts

@@ -0,0 +1,6 @@
+import type { RuleReport } from './types.js';
+export declare function internalAnchorHref(openTag: string): string | null;
+/** 소스에 내부 이동 일반 앵커가 있는지(단위 테스트 진입점 · 주석은 제외). */
+export declare function usesInternalAnchor(source: string): boolean;
+/** apps/ 의 .vue 를 훑어 내부 이동 일반 앵커를 경고로 낸다. */
+export declare function checkInternalAnchor(cwd: string): Promise<RuleReport>;

package/dist/doctor/internal-anchor.js

@@ -0,0 +1,122 @@
+// @gaonjs/cli · doctor · 앱 내부 이동 일반 <a> 앵커 검출 (결정 96 · 경고)
+//
+// 앱 내부 경로로 이동하는 일반 `<a href="/...">` 는 클릭마다 전체 문서를
+// 다시 로드한다 — Inertia SPA 상태(스크롤·폼·구독)가 초기화되고, "메인
+// 경로" 로 이동할 때마다 풀 리로드가 난다(첫 실사용 블로그에서 관측된 결함).
+// 앱 내부 이동은 `gaonjs/vue` 의 `Link`(선언적) 또는 `router.visit`(프로그램적)
+// 를 쓴다. 이 검사가 내부 경로 일반 앵커를 경고로 잡는다. 판정은 소스 텍스트 기반.
+//
+// 오탐 방지(결정 96): 외부 URL(http/https·//·mailto·tel)·프래그먼트(#)·
+// `target="_blank"`·정적 판별 불가한 바인딩(`:href="expr"` 중 템플릿 리터럴이
+// 아닌 것)은 건드리지 않는다. 내부로 확정 가능한 경우만 — 정적 `href="/..."`
+// 와 `/` 로 시작하는 템플릿 리터럴 `:href="`/...`"` — 잡는다.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+// 주석을 공백으로 치환하되 줄바꿈은 보존한다(라인 번호 유지) — 안티패턴을
+// "쓰지 말라"고 설명하는 주석(줄/블록/HTML-Vue)이 오탐을 내지 않도록.
+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));
+}
+// 값이 앱 내부 경로(루트-상대)인지. 외부·프래그먼트·스킴은 제외.
+function isInternalStaticHref(value) {
+    const v = value.trim();
+    if (v === '')
+        return false;
+    if (v.startsWith('//'))
+        return false; // 프로토콜-상대 → 외부
+    if (/^[a-z][a-z0-9+.-]*:/i.test(v))
+        return false; // http:·mailto:·tel:·data: 등 스킴
+    if (v.startsWith('#'))
+        return false; // 페이지 내 프래그먼트
+    return v.startsWith('/'); // 루트-상대만 내부로 확정
+}
+// 여는 `<a ...>` 태그 하나가 "내부 이동 일반 앵커" 인지 판정해, 그렇다면
+// 문제의 href 문자열을 돌려준다(아니면 null). 정적 판별 불가는 null(오탐 방지).
+export function internalAnchorHref(openTag) {
+    // target="_blank" = 외부 의도 → 건드리지 않는다.
+    if (/\btarget\s*=\s*['"]_blank['"]/i.test(openTag))
+        return null;
+    // 정적 href="..."
+    const staticM = openTag.match(/\shref\s*=\s*(['"])([^'"]*)\1/i);
+    if (staticM)
+        return isInternalStaticHref(staticM[2]) ? staticM[2].trim() : null;
+    // 바인딩 :href / v-bind:href — 템플릿 리터럴 `/...` 만 내부로 확정.
+    const boundM = openTag.match(/(?::|v-bind:)href\s*=\s*(['"])([^'"]*)\1/i);
+    if (boundM) {
+        const expr = boundM[2].trim();
+        const tl = expr.match(/^`([^`]*)`$/); // `...` 전체가 템플릿 리터럴
+        if (tl && tl[1].startsWith('/') && !tl[1].startsWith('//'))
+            return expr;
+        return null; // 바인딩된 식(prop·식별자)은 정적 판별 불가 → 건드리지 않는다
+    }
+    return null;
+}
+/** 소스에 내부 이동 일반 앵커가 있는지(단위 테스트 진입점 · 주석은 제외). */
+export function usesInternalAnchor(source) {
+    const stripped = stripCommentsKeepLines(source);
+    for (const m of stripped.matchAll(/<a\b[^>]*>/gi)) {
+        if (internalAnchorHref(m[0]) !== null)
+            return true;
+    }
+    return false;
+}
+/** apps/ 의 .vue 를 훑어 내부 이동 일반 앵커를 경고로 낸다. */
+export async function checkInternalAnchor(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(/<a\b[^>]*>/gi)) {
+            const href = internalAnchorHref(m[0]);
+            if (href === null)
+                continue;
+            const line = stripped.slice(0, m.index ?? 0).split('\n').length;
+            issues.push({
+                rule: 'internal-anchor',
+                level: 'warning',
+                file: rel,
+                line,
+                message: `내부 이동 일반 앵커 발견: ${rel}:${line} 이 \`<a href="${href}">\` 로 앱 내부 경로를 ` +
+                    `가리킵니다. 일반 \`<a>\` 는 클릭마다 전체 문서를 다시 로드해 Inertia SPA 상태가 ` +
+                    `초기화됩니다(첫 실사용에서 관측된 결함 · 결정 96).\n` +
+                    `→ \`gaonjs/vue\` 의 \`Link\` 를 쓰세요: \`import { Link } from 'gaonjs/vue'\` 후 ` +
+                    `\`<Link href="${href}">…</Link>\`. 프로그램적 이동은 \`router.visit(...)\`. ` +
+                    `외부 URL·\`target="_blank"\` 만 \`<a>\` 를 유지합니다.`,
+                detail: { file: rel, line, href },
+            });
+        }
+    }
+    return { rule: 'internal-anchor', 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/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>;