@gaonjs/cli 0.2.0 → 0.3.0

package/dist/doctor.js

@@ -1,218 +1,88 @@
 /**
- * @gaonjs/cli · `gaon doctor` — 정적 검사 (M3 · errata E-3)
+ * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성)
  *
- * v1 첫 검사 항목: **응답 혼용 금지**. 한 컨트롤러 액션은 render/JSON/
- * redirect 중 한 가지 응답 형태만 낼 수 있다(§C · The One Way). 조건 분기로
- * 섞으면 "이 라우트가 무엇을 돌려주는지"가 코드를 읽어야 알게 돼 AI 첫 시도
- * 성공률이 떨어진다.
+ * 5 검사를 조립한다:
+ *  1) response-mixing (errata E-3 §C · 라이브)
+ *  2) n-plus-one (errata E-4 (e))
+ *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
+ *  4) connections (v0.15 §4.5)
+ *  5) migration-diff (최소 감지 · 상세는 M9-D)
  *
- * 검사 방법(정적 분석):
- *  · apps/<app>/controllers/*.ts 를 TS AST 로 파싱.
- *  · export default controller({ ... }) 의 액션 함수마다 return 노드에서
- *    최종 응답 형태를 분류(render | redirect | json | plain).
- *  · 서로 다른 형태가 두 종류 이상이면 위반.
- *  · this.render/this.redirect/this.json/평범한 객체 반환의 4종을 구별한다.
+ * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
+ * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
+ * 구조를 유지한다(CLAUDE.md §4 · 모든 명령 --json).
  *
- * 위반 시: 파일·라인·액션 이름 + 감지된 형태 목록 + "→ 한 액션은 한 응답
- * 형태만 유지하세요(errata E-3 §C)" 안내를 낸다.
- *
- * 나머지 doctor 검사(의존 방향 §1-5, 커넥션 §4.5 등)는 후속 마일스톤에서
- * 이 모듈에 규칙을 얹는다.
+ * 하위 호환: 기존 응답 혼용 API(`inspectControllerSource`·`runDoctor`)는
+ * 그대로 export — 기존 테스트가 계속 동작한다.
  */
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { join, relative, resolve } from 'node:path';
-import ts from 'typescript';
-/** 컨트롤러 파일 하나를 검사한다. */
-export function inspectControllerSource(file, source) {
-    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
-    const usages = [];
-    const visit = (node) => {
-        if (ts.isCallExpression(node) && isControllerCall(node)) {
-            const arg = node.arguments[0];
-            if (arg && ts.isObjectLiteralExpression(arg)) {
-                for (const prop of arg.properties) {
-                    const action = actionName(prop);
-                    if (!action)
-                        continue;
-                    const body = actionBody(prop);
-                    if (!body)
-                        continue;
-                    const kinds = classifyReturns(body);
-                    const { line } = sf.getLineAndCharacterOfPosition(prop.getStart(sf));
-                    usages.push({ file, action, line: line + 1, kinds });
-                }
-            }
-        }
-        ts.forEachChild(node, visit);
-    };
-    visit(sf);
-    return usages;
-}
-function isControllerCall(node) {
-    const e = node.expression;
-    if (ts.isIdentifier(e) && e.text === 'controller')
-        return true;
-    if (ts.isPropertyAccessExpression(e) && e.name.text === 'controller')
-        return true;
-    return false;
-}
-function actionName(prop) {
-    if (ts.isMethodDeclaration(prop) && ts.isIdentifier(prop.name))
-        return prop.name.text;
-    if (ts.isPropertyAssignment(prop) &&
-        ts.isIdentifier(prop.name) &&
-        (ts.isArrowFunction(prop.initializer) || ts.isFunctionExpression(prop.initializer))) {
-        return prop.name.text;
-    }
-    return undefined;
-}
-function actionBody(prop) {
-    if (ts.isMethodDeclaration(prop))
-        return prop.body;
-    if (ts.isPropertyAssignment(prop)) {
-        if (ts.isArrowFunction(prop.initializer))
-            return prop.initializer.body;
-        if (ts.isFunctionExpression(prop.initializer))
-            return prop.initializer.body;
-    }
-    return undefined;
-}
-/** 액션 본문의 모든 return 표현식을 응답 형태로 분류하고 중복을 제거해 반환한다. */
-function classifyReturns(body) {
-    const kinds = new Set();
-    const classify = (expr) => {
-        // await x → x 로 되짚어 본다.
-        if (ts.isAwaitExpression(expr))
-            return classify(expr.expression);
-        // this.render / this.redirect / this.json
-        if (ts.isCallExpression(expr)) {
-            const c = expr.expression;
-            if (ts.isPropertyAccessExpression(c) && c.expression.kind === ts.SyntaxKind.ThisKeyword) {
-                if (c.name.text === 'render')
-                    return 'render';
-                if (c.name.text === 'redirect')
-                    return 'redirect';
-                if (c.name.text === 'json')
-                    return 'json';
-            }
-            // 삼항·논리 연산 결과라도 호출식이 나오면 함수 반환값에 의존 — 보수적으로 plain.
-            return 'plain';
-        }
-        // 삼항 연산자 — 양쪽 각각 분류
-        if (ts.isConditionalExpression(expr)) {
-            kinds.add(classify(expr.whenTrue));
-            kinds.add(classify(expr.whenFalse));
-            return classify(expr.whenTrue); // 반환값(대표) — Set 에 이미 다 넣음
-        }
-        // 그 외(객체·배열·literal·식별자 등) → plain(JSON 액션)
-        return 'plain';
-    };
-    const visit = (node) => {
-        if (ts.isReturnStatement(node)) {
-            if (node.expression)
-                kinds.add(classify(node.expression));
-            else
-                kinds.add('plain'); // 빈 return 은 undefined → 204 (plain 으로 취급, 혼용 검사에서만 의미)
-            return; // return 안의 하위 함수는 다른 스코프 — 이 return 만 잡는다
-        }
-        // 중첩 함수/화살표는 다른 스코프 — 파고들지 않는다.
-        if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node))
-            return;
-        ts.forEachChild(node, visit);
-    };
-    // 표현식 본문 화살표(=> render(...))는 body 가 표현식.
-    if (ts.isBlock(body))
-        visit(body);
-    else
-        kinds.add(classify(body));
-    return [...kinds];
-}
+import { resolve } from 'node:path';
+import { checkResponseMixing } from './doctor/response-mixing.js';
+import { checkNPlusOne } from './doctor/n-plus-one.js';
+import { checkDependencyDirection } from './doctor/dependency-direction.js';
+import { checkConnections } from './doctor/connections.js';
+import { checkMigrationDiff } from './doctor/migration-diff.js';
+import { renderHuman, renderJson } from './doctor/reporter.js';
+import { makeResult, } from './doctor/types.js';
+export { inspectControllerSource, checkResponseMixing } from './doctor/response-mixing.js';
+export { inspectControllerForNPlusOne, checkNPlusOne } from './doctor/n-plus-one.js';
+export { extractRelativeImports, checkDependencyDirection } from './doctor/dependency-direction.js';
+export { extractConfigDbKeys, extractKeyUses, checkConnections } from './doctor/connections.js';
+export { scanSchema, checkMigrationDiff } from './doctor/migration-diff.js';
+export { renderHuman, renderJson } from './doctor/reporter.js';
+/**
+ * 실행할 검사 이름. 지정 없음(undefined) = 5개 모두.
+ */
+const ALL_RULES = [
+    'response-mixing',
+    'n-plus-one',
+    'dependency-direction',
+    'connections',
+    'migration-diff',
+];
+const CHECKERS = {
+    'response-mixing': checkResponseMixing,
+    'n-plus-one': checkNPlusOne,
+    'dependency-direction': checkDependencyDirection,
+    connections: checkConnections,
+    'migration-diff': checkMigrationDiff,
+};
 /**
- * apps/<app>/controllers/ 를 훑어 응답 혼용 액션을 찾는다. 액션 하나의 kinds
- * 배열이 2종 이상이면 위반(단, 'plain' 하나만 있는 것과 render 만 있는 것은 통과).
+ * `gaon doctor` 진입점 (M9-E · 확장).
  *
- * 명시적 예외: 반환 없는 return(=undefined→204)만 있는 경우는 통과 — void 액션은
- * 흔히 혼용 없이 정상적으로 쓰인다.
+ * 반환: DoctorResult({passed, warnings, errors}).
+ * exit code 는 진입점(runCli)이 errors.length 로 결정한다.
  */
-export async function runDoctor(appsDir) {
-    const issues = [];
-    let checked = 0;
-    const apps = await safeListDirs(appsDir);
-    for (const app of apps) {
-        const ctrlDir = join(appsDir, app, 'controllers');
-        for (const file of await safeListFiles(ctrlDir)) {
-            if (!file.endsWith('.ts') || file.endsWith('.d.ts') || file.endsWith('.test.ts'))
-                continue;
-            const full = join(ctrlDir, file);
-            const source = await readFile(full, 'utf8');
-            const usages = inspectControllerSource(full, source);
-            checked += usages.length;
-            for (const u of usages) {
-                if (u.kinds.length < 2)
-                    continue;
-                // 'plain' 이 유일한 다른 형태이면서 실제 return 문에 undefined 만 있는 경우는 걸러야
-                // 하지만, 액션이 render|json 를 하다가 조건에 따라 undefined 반환하면 혼용이다. 유지.
-                const rel = relative(process.cwd(), full);
-                issues.push({
-                    file: rel,
-                    line: u.line,
-                    action: u.action,
-                    kinds: u.kinds,
-                    message: `[doctor] 응답 혼용 감지: ${rel}:${u.line} · 액션 '${u.action}' 이 서로 다른 응답 형태를 섞습니다 (${u.kinds.join(', ')}).\n` +
-                        `→ 한 액션은 한 응답 형태만 유지하세요 (render | JSON | redirect · errata E-3 §C).\n` +
-                        `→ 조건 분기가 필요하면 액션을 둘로 나누거나, JSON 반환에는 예외를 던져 상태 코드를 표현하세요.`,
-                });
-            }
-        }
-    }
-    return { ok: issues.length === 0, checked, issues };
-}
-async function safeListDirs(dir) {
-    try {
-        const entries = await readdir(dir, { withFileTypes: true });
-        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
-    }
-    catch {
-        return [];
-    }
-}
-async function safeListFiles(dir) {
-    try {
-        const entries = await readdir(dir, { withFileTypes: true });
-        return entries.filter((e) => e.isFile()).map((e) => e.name);
-    }
-    catch {
-        return [];
-    }
-}
-// stat 은 API 표면 유지용 — 파일 존재 확인이 필요할 때 씀.
-export async function fileExists(file) {
-    try {
-        await stat(file);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/** `gaon doctor` 진입점. */
 export async function runDoctorCommand(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
-    const appsDir = resolve(cwd, 'apps');
-    const result = await runDoctor(appsDir);
-    if (opts.json) {
-        process.stdout.write(JSON.stringify(result) + '\n');
-    }
-    else {
-        process.stdout.write(`  검사한 액션: ${result.checked}개\n`);
-        if (result.ok) {
-            process.stdout.write(`  ✓ 응답 혼용 없음\n`);
-        }
-        else {
-            process.stdout.write(`  ✗ 응답 혼용 ${result.issues.length}건\n`);
-            for (const i of result.issues)
-                process.stdout.write(i.message + '\n');
-        }
+    const root = resolve(cwd);
+    const rules = opts.checks && opts.checks.length ? opts.checks : ALL_RULES;
+    const reports = [];
+    for (const rule of rules) {
+        const fn = CHECKERS[rule];
+        reports.push(await fn(root));
     }
-    return result.ok ? 0 : 1;
+    const result = makeResult(reports);
+    const out = opts.json ? renderJson(result) : renderHuman(result);
+    process.stdout.write(out + '\n');
+    return result;
+}
+/**
+ * 하위 호환: 응답 혼용만 검사해 legacy shape 을 낸다.
+ * appsDir 은 프로젝트의 apps/ 절대 경로. 상위(진입점)는 runDoctorCommand
+ * 를 쓴다.
+ */
+export async function runDoctor(appsDir) {
+    // apps/ 의 부모를 cwd 로 간주(관례).
+    const cwd = resolve(appsDir, '..');
+    const report = await checkResponseMixing(cwd);
+    const issues = report.issues.map((i) => ({
+        file: i.file ?? '',
+        line: i.line ?? 0,
+        action: String(i.detail?.action ?? ''),
+        kinds: i.detail?.kinds ?? [],
+        message: i.message,
+    }));
+    // checked 는 컨트롤러 액션 수 — 응답 혼용 검사가 순회한 액션 수와 정합.
+    // 하위 호환 목적으로 issues 수로 대체(정확한 checked 는 신규 API 를 쓰라).
+    return { ok: issues.length === 0, checked: issues.length, issues };
 }

package/dist/index.d.ts

@@ -1,11 +1,14 @@
+import { type DoctorRule } from "./doctor.js";
 export { runDevCommand, startDev, resolveDevLayout, type DevDeps, type DevLayout, type DevApp, type DevEvent, type DevHandle, type DevCommandOptions, } from "./dev.js";
 export { runCheck, runCheckCommand, type CheckDeps, type CheckResult, type TypecheckResult, type CheckCommandOptions, } from "./check.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, type AuthScaffoldOptions, type ScaffoldFile, type ScaffoldResult, type GenerateAuthOptions, } from "./generate.js";
+export { runGenerateCommand, planScaffold, parseGenerateArgs, type GenerateType, type GenerateOptions, type GenerateResult, } from "./commands/g.js";
 export { runHubCommand, type HubCommandOptions } from "./hub.js";
+export { runServeCommand, type ServeCommandOptions } from "./serve.js";
 export { runWorkCommand, type WorkCommandOptions } from "./work.js";
 export { runJobsCommand, type JobsCommandOptions } from "./jobs.js";
 export { runDbSeedCommand, loadSeed, type DbSeedOptions, type DbSeedResult } from "./db.js";
-export { runDoctorCommand, runDoctor, inspectControllerSource, type DoctorResult, type DoctorIssue, type ActionUsage, type ResponseKind, type DoctorCommandOptions, } from "./doctor.js";
+export { runDoctorCommand, runDoctor, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, type DoctorResult, type DoctorCheck, type DoctorLevel, type DoctorRule, type RuleReport, type DoctorIssue, type LegacyDoctorResult, type ActionUsage, type ResponseKind, type DoctorCommandOptions, } from "./doctor.js";
 export { loadDomain, type LoadedDomain } from "./domain.js";
 export interface RoadmapReport {
     readonly name: "gaon";
@@ -27,5 +30,10 @@ export declare function renderRoadmap(version?: string): string;
 export interface RunOptions {
     readonly version?: string;
 }
+/**
+ * `gaon doctor --check=<이름>[,<이름>...]` 파싱(M9-E).
+ * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
+ */
+export declare function parseDoctorChecks(argv: readonly string[]): DoctorRule[] | undefined;
 /** CLI 진입점. argv 는 실행 인자(process.argv.slice(2))를 받는다. */
 export declare function runCli(argv: readonly string[], opts?: RunOptions): void;

package/dist/index.js

@@ -13,7 +13,9 @@ import { MILESTONES, VERSION, HOMEPAGE } from "@gaonjs/core";
 import { runDevCommand } from "./dev.js";
 import { runCheckCommand } from "./check.js";
 import { runGenerateAuthCommand } from "./generate.js";
+import { runGenerateCommand } from "./commands/g.js";
 import { runHubCommand } from "./hub.js";
+import { runServeCommand } from "./serve.js";
 import { runWorkCommand } from "./work.js";
 import { runJobsCommand } from "./jobs.js";
 import { runDbSeedCommand } from "./db.js";
@@ -21,11 +23,13 @@ import { runDoctorCommand } from "./doctor.js";
 export { runDevCommand, startDev, resolveDevLayout, } from "./dev.js";
 export { runCheck, runCheckCommand, } from "./check.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, } from "./generate.js";
+export { runGenerateCommand, planScaffold, parseGenerateArgs, } from "./commands/g.js";
 export { runHubCommand } from "./hub.js";
+export { runServeCommand } from "./serve.js";
 export { runWorkCommand } from "./work.js";
 export { runJobsCommand } from "./jobs.js";
 export { runDbSeedCommand, loadSeed } from "./db.js";
-export { runDoctorCommand, runDoctor, inspectControllerSource, } from "./doctor.js";
+export { runDoctorCommand, runDoctor, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, } from "./doctor.js";
 export { loadDomain } from "./domain.js";
 /** `--json` 출력용 구조화 리포트. */
 export function roadmapReport(version = VERSION) {
@@ -72,9 +76,18 @@ function renderHelp(version = VERSION) {
         "    gaon               로드맵과 개발 상태를 출력",
         "    gaon dev           .gaon 타입 브리지를 감시·재생성 (스키마·라우트)",
         "    gaon dev --json    재생성 이벤트를 JSON 으로 출력",
+        "    gaon serve         웹 서버 부팅 (gaon.config.ts 자동 배선 · Fastify listen)",
+        "    gaon serve --port <n> --host <h>   리슨 포트·호스트 (config 값을 덮음)",
         "    gaon check         .gaon 재생성 후 타입 검사 (CI·AI 정합)",
-        "    gaon doctor        정적 검사 (응답 혼용·의존 방향 등)",
+        "    gaon doctor        정적 검사 (5 검사 · 응답 혼용·N+1·의존 방향·커넥션·마이그)",
+        "    gaon doctor --json                        자동화용 JSON 출력",
+        "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트)",
+        "    gaon g controller <name>   컨트롤러 스캐폴드 (Rails 관례 · 페이지+JSON 액션)",
+        "    gaon g model <Name>        모델 스캐폴드 (스키마+모델 · E-4 컬럼 예시)",
+        "    gaon g page <Path/Name>    Vue 페이지 (Inertia SPA · pageProps 브리지)",
+        "    gaon g job <Name>          비동기 잡 (domain/jobs · later/in/at)",
+        "    gaon g <type> --overwrite  기존 파일 덮어쓰기 · --app <이름> · --json",
         "    gaon hub           실시간 허브 프로세스 (프레즌스 권위·중계 · 리더 선출 HA)",
         "    gaon work          워커 프로세스 (잡·리스너·스케줄·아웃박스 · graceful drain)",
         "    gaon jobs list --failed   DLQ(실패 잡) 목록",
@@ -87,6 +100,30 @@ function renderHelp(version = VERSION) {
         "",
     ].join("\n");
 }
+/**
+ * `gaon doctor --check=<이름>[,<이름>...]` 파싱(M9-E).
+ * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
+ */
+export function parseDoctorChecks(argv) {
+    const known = [
+        "response-mixing",
+        "n-plus-one",
+        "dependency-direction",
+        "connections",
+        "migration-diff",
+    ];
+    const isKnown = (s) => known.includes(s);
+    const out = [];
+    for (const a of argv) {
+        if (a.startsWith("--check=")) {
+            for (const nm of a.slice("--check=".length).split(",")) {
+                if (isKnown(nm) && !out.includes(nm))
+                    out.push(nm);
+            }
+        }
+    }
+    return out.length ? out : undefined;
+}
 /** CLI 진입점. argv 는 실행 인자(process.argv.slice(2))를 받는다. */
 export function runCli(argv, opts = {}) {
     const version = opts.version ?? VERSION;
@@ -100,6 +137,19 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
+    // `gaon serve` — 웹 서버 부팅(§7 · M9-A). gaon.config.ts 자동 배선 후 listen.
+    if (argv[0] === "serve") {
+        const portIdx = argv.indexOf("--port");
+        const hostIdx = argv.indexOf("--host");
+        const port = portIdx >= 0 ? Number(argv[portIdx + 1]) : undefined;
+        const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
+        void runServeCommand({ json: argv.includes("--json"), port, host }).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon serve 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
     // `gaon check` — .gaon 재생성 후 타입 검사(§13.4-5). 종료 코드로 결과 전달.
     if (argv[0] === "check") {
         void runCheckCommand({ json: argv.includes("--json") })
@@ -113,11 +163,13 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(응답 혼용 등 · errata E-3 §C). --fix 는 후속.
+    // `gaon doctor` — 정적 검사(M9-E · 5 검사). --check=<이름>[,<이름>...] 로
+    // 선택 실행, --json 은 자동화 파싱용. exit code: errors.length > 0 이면 1.
     if (argv[0] === "doctor") {
-        void runDoctorCommand({ json: argv.includes("--json") })
-            .then((code) => {
-            process.exitCode = code;
+        const checks = parseDoctorChecks(argv);
+        void runDoctorCommand({ json: argv.includes("--json"), checks })
+            .then((result) => {
+            process.exitCode = result.errors.length > 0 ? 1 : 0;
         })
             .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
@@ -174,7 +226,9 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon g auth` — 인증 스캐폴드 제너레이터(§7 M5). 다른 제너레이터는 후속.
+    // `gaon g <type> <name>` — 스캐폴드(§7 M5·M9-B).
+    //  · auth 는 인증 스캐폴드(별도 진입점)
+    //  · controller/model/page/job 은 M9-B 통합 라우터
     if (argv[0] === "g" || argv[0] === "generate") {
         if (argv[1] === "auth") {
             const appIdx = argv.indexOf("--app");
@@ -183,8 +237,47 @@ export function runCli(argv, opts = {}) {
             process.exitCode = code;
             return;
         }
+        const known = ["controller", "model", "page", "job"];
+        const type = argv[1];
+        if (type && known.includes(type)) {
+            const rest = argv.slice(2);
+            // name = 첫 위치 인자(--플래그 제외 · --app <v> 스킵)
+            let name;
+            let app;
+            let overwrite = false;
+            let json = false;
+            for (let i = 0; i < rest.length; i++) {
+                const a = rest[i];
+                if (a === "--json") {
+                    json = true;
+                    continue;
+                }
+                if (a === "--overwrite") {
+                    overwrite = true;
+                    continue;
+                }
+                if (a === "--app") {
+                    app = rest[++i];
+                    continue;
+                }
+                if (a?.startsWith("--"))
+                    continue;
+                if (name === undefined)
+                    name = a;
+            }
+            if (!name) {
+                process.stderr.write(`  ✗ gaon g ${type}: 이름이 없습니다.\n` +
+                    `  → 예: gaon g ${type} ${type === "page" ? "Posts/Index" : "Post"}\n`);
+                process.exitCode = 1;
+                return;
+            }
+            const code = runGenerateCommand(type, name, { app, overwrite, json });
+            process.exitCode = code;
+            return;
+        }
         process.stderr.write(`  ✗ 알 수 없는 제너레이터: ${argv[1] ?? "(없음)"}\n` +
-            `  → 현재 지원: gaon g auth [--app <이름>]\n`);
+            `  → 현재 지원: gaon g auth | controller | model | page | job\n` +
+            `  → 옵션: --app <이름> · --overwrite · --json\n`);
         process.exitCode = 1;
         return;
     }

package/dist/scaffold/controller.d.ts

@@ -0,0 +1,12 @@
+import type { ModelNames } from './inflect.js';
+/** 스캐폴드가 만들 파일 하나 — path 는 프로젝트 루트 기준 상대 경로. */
+export interface ScaffoldFile {
+    readonly path: string;
+    readonly contents: string;
+}
+/**
+ * 컨트롤러 스캐폴드 파일을 만든다.
+ * @param names 이름 변형(카멜/파스칼/복수) — inflect() 결과.
+ * @param app 대상 앱 폴더(apps/<app>/).
+ */
+export declare function controllerScaffold(names: ModelNames, app: string): ScaffoldFile;

package/dist/scaffold/controller.js

@@ -0,0 +1,50 @@
+// @gaonjs/cli · scaffold · controller (M9-B)
+//
+// `gaon g controller <name>` — Rails 관례의 컨트롤러 스캐폴드.
+// 페이지 액션(this.render)과 JSON 액션(반환값=응답 · errata E-3) 두 예시를
+// 함께 담는다 — 실 프로젝트에서 가장 자주 쓰는 두 패턴이라 첫 코드에서
+// 노출하는 편이 AI/사람 첫 시도 성공률에 유리하다.
+//
+// 응답 혼용 주의: 한 컨트롤러 안에서 페이지 액션과 JSON 액션을 섞는 것은
+// doctor 가 경고한다(errata E-3 §C). 스캐폴드는 이유를 주석으로 남기고,
+// 규모가 커지면 분리하도록 안내한다.
+//
+// 모델 참조: apps/<app>/controllers/*.ts → domain/models/*.ts. 프로젝트 관습
+// (CLAUDE.md §2): 모델·잡은 domain/ 아래 두어 앱 간 재사용을 허용한다
+// (apps→apps 금지 · rule 5).
+/**
+ * 컨트롤러 스캐폴드 파일을 만든다.
+ * @param names 이름 변형(카멜/파스칼/복수) — inflect() 결과.
+ * @param app 대상 앱 폴더(apps/<app>/).
+ */
+export function controllerScaffold(names, app) {
+    const { pascal, camel, plural } = names;
+    const lines = [
+        `// ${plural} 컨트롤러 — gaon g controller (M9-B).`,
+        `// 페이지 액션(this.render)과 JSON 액션(반환값=응답 · errata E-3) 예시를 담는다.`,
+        `// 응답 종류를 한 컨트롤러에서 섞으면 doctor 가 경고한다(§C) — 규모가 커지면 분리.`,
+        `import { controller } from 'gaonjs/web'`,
+        `import { ${pascal} } from '../../../domain/models/${camel}.js'`,
+        ``,
+        `export default controller({`,
+        `  // GET /${plural} — 목록 페이지 (Inertia render).`,
+        `  // E-4 체이닝 예시: orderBy · limit · all.`,
+        `  async index() {`,
+        `    const items = await ${pascal}.orderBy('createdAt', 'desc').limit(20).all()`,
+        `    return this.render('${pascal}/Index', { items })`,
+        `  },`,
+        ``,
+        `  // GET /${plural}/count.json — JSON 액션 (errata E-3).`,
+        `  // 반환값 = 응답. api('${plural}#count') 클라이언트가 Serialized<> 로 받는다.`,
+        `  // this.params() 안전 규칙: 라우트 > body > query (errata E-3 §5.1).`,
+        `  async count() {`,
+        `    return { total: await ${pascal}.count() }`,
+        `  },`,
+        `})`,
+        ``,
+    ];
+    return {
+        path: `apps/${app}/controllers/${plural}.ts`,
+        contents: lines.join('\n'),
+    };
+}

package/dist/scaffold/index.d.ts

@@ -0,0 +1,20 @@
+export type { ScaffoldFile } from './controller.js';
+export { controllerScaffold } from './controller.js';
+export { modelScaffold, modelScaffoldFiles, schemaScaffold } from './model.js';
+export { pageScaffold } from './page.js';
+export { jobScaffold } from './job.js';
+export { inflectModel, toCamel, toPascal, singularize, pluralize, type ModelNames, } from './inflect.js';
+import type { ScaffoldFile } from './controller.js';
+export interface WriteResult {
+    readonly created: string[];
+    readonly overwritten: string[];
+    /** overwrite=false 로 스킵된 기존 파일. */
+    readonly skipped: string[];
+}
+/**
+ * 파일 계획을 실제로 쓴다. 기본은 기존 파일 skip(멱등 · 사고 방지).
+ * overwrite=true 이면 덮어쓴다(기존 파일 목록을 overwritten 에 반환).
+ */
+export declare function writeScaffold(cwd: string, files: readonly ScaffoldFile[], opts?: {
+    overwrite?: boolean;
+}): WriteResult;

package/dist/scaffold/index.js

@@ -0,0 +1,41 @@
+// @gaonjs/cli · scaffold · public export (M9-B)
+//
+// `gaon g <type> <name>` 스캐폴드 진입점 모음. runCli 가 여기서 팩토리를
+// 골라 파일을 쓴다. 각 팩토리는 순수 함수 — 디스크 접근 없이 파일 계획을
+// 반환한다. 실제 쓰기는 writeScaffold 가 담당(멱등·overwrite 옵션 처리).
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+export { controllerScaffold } from './controller.js';
+export { modelScaffold, modelScaffoldFiles, schemaScaffold } from './model.js';
+export { pageScaffold } from './page.js';
+export { jobScaffold } from './job.js';
+export { inflectModel, toCamel, toPascal, singularize, pluralize, } from './inflect.js';
+/**
+ * 파일 계획을 실제로 쓴다. 기본은 기존 파일 skip(멱등 · 사고 방지).
+ * overwrite=true 이면 덮어쓴다(기존 파일 목록을 overwritten 에 반환).
+ */
+export function writeScaffold(cwd, files, opts = {}) {
+    const root = resolve(cwd);
+    const created = [];
+    const overwritten = [];
+    const skipped = [];
+    for (const file of files) {
+        const abs = join(root, file.path);
+        const exists = existsSync(abs);
+        if (exists && !opts.overwrite) {
+            skipped.push(file.path);
+            continue;
+        }
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, file.contents, 'utf8');
+        if (exists)
+            overwritten.push(file.path);
+        else
+            created.push(file.path);
+    }
+    return {
+        created: created.sort(),
+        overwritten: overwritten.sort(),
+        skipped: skipped.sort(),
+    };
+}

package/dist/scaffold/inflect.d.ts

@@ -0,0 +1,19 @@
+/** 파스칼케이스 → 카멜케이스 (`Post` → `post`, `SendEmail` → `sendEmail`). */
+export declare function toCamel(s: string): string;
+/** 카멜/스네이크/케밥 → 파스칼케이스 (`post` → `Post`, `send_email` → `SendEmail`). */
+export declare function toPascal(s: string): string;
+/** 단순 단수화 — 끝의 s 하나만 벗긴다 ('users' → 'user' · 'ss' 는 유지). */
+export declare function singularize(s: string): string;
+/** 단순 복수화 — 끝에 s 를 붙인다 ('user' → 'users' · 이미 s 로 끝나면 유지). */
+export declare function pluralize(s: string): string;
+/** 모델 이름 · 표준 변형 묶음. 스캐폴드가 파일명·클래스명·테이블명에 쓴다. */
+export interface ModelNames {
+    /** 파스칼 단수 — 클래스/const 명 (`Post`). */
+    readonly pascal: string;
+    /** 카멜 단수 — 파일 stem·변수명 (`post`). */
+    readonly camel: string;
+    /** 카멜 복수 — 테이블명·경로 (`posts`). */
+    readonly plural: string;
+}
+/** 사용자 입력(어느 형태든)에서 세 가지 변형을 파생한다. */
+export declare function inflectModel(input: string): ModelNames;