@gaonjs/cli 0.4.0 → 0.10.0

package/dist/doctor.js

@@ -1,12 +1,15 @@
 /**
- * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성)
+ * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 5 검사를 조립한다:
+ * 8 검사를 조립한다:
  *  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)
+ *  6) shared-composable-purity (errata E-5 §2.2 · 결정 25)
+ *  7) no-auto-import (errata E-5 §2.4 · v0.15 §1.2)
+ *  8) schema-filename (§1.1 · 결정 38 · 스키마 파일명 camelCase)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -15,25 +18,36 @@
  * 하위 호환: 기존 응답 혼용 API(`inspectControllerSource`·`runDoctor`)는
  * 그대로 export — 기존 테스트가 계속 동작한다.
  */
-import { resolve } from 'node:path';
+import { rename, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import ts from 'typescript';
 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 { checkSharedComposablePurity } from './doctor/shared-composable-purity.js';
+import { checkNoAutoImport } from './doctor/no-auto-import.js';
+import { checkSchemaFilename } from './doctor/schema-filename.js';
+import { checkAgentsDocIndex } from './doctor/agents-doc-index.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
+import { FIXERS, FIXER_CAPABILITIES } from './doctor/fixers/index.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 { inspectSharedComposable, checkSharedComposablePurity, } from './doctor/shared-composable-purity.js';
+export { inspectConfigForAutoImport, inspectPackageJson, checkNoAutoImport, } from './doctor/no-auto-import.js';
+export { expectedSchemaStem, extractTableName, checkSchemaFilename, } from './doctor/schema-filename.js';
+export { extractAgentDocRefs, checkAgentsDocIndex } from './doctor/agents-doc-index.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 5개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 7개 모두.
  */
 const ALL_RULES = [
     'response-mixing',
@@ -41,6 +55,10 @@ const ALL_RULES = [
     'dependency-direction',
     'connections',
     'migration-diff',
+    'shared-composable-purity',
+    'no-auto-import',
+    'schema-filename',
+    'agents-doc-index',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -48,6 +66,10 @@ const CHECKERS = {
     'dependency-direction': checkDependencyDirection,
     connections: checkConnections,
     'migration-diff': checkMigrationDiff,
+    'shared-composable-purity': checkSharedComposablePurity,
+    'no-auto-import': checkNoAutoImport,
+    'schema-filename': checkSchemaFilename,
+    'agents-doc-index': checkAgentsDocIndex,
 };
 /**
  * `gaon doctor` 진입점 (M9-E · 확장 · M9-E-Fix 하드닝).
@@ -120,10 +142,172 @@ export async function runDoctorCommand(opts = {}) {
             });
         }
     }
-    const result = makeResult(reports);
-    const out = json ? renderJson(result) : renderHuman(result);
+    const baseResult = makeResult(reports);
+    // --fix 가 없으면 종전 동작 그대로.
+    if (!opts.fix) {
+        const out = json ? renderJson(baseResult) : renderHuman(baseResult);
+        process.stdout.write(out + '\n');
+        return baseResult;
+    }
+    // --fix: fixer 를 계획하고, --yes 이면 실제 편집한다. reports 를 그대로
+    // 넘겨 규칙별 위반을 fixer 가 판단한다(passed 는 건너뜀).
+    const fixReport = await runDoctorFix(reports, root, opts.yes === true);
+    const resultWithFix = { ...baseResult, fix: fixReport };
+    const out = json
+        ? JSON.stringify(resultWithFix)
+        : renderHuman(baseResult) + '\n\n' + renderFixHuman(fixReport);
     process.stdout.write(out + '\n');
-    return result;
+    return resultWithFix;
+}
+/**
+ * fixer 를 계획·(승인 시)실행한다. 파일 편집은 여기서만 일어난다 —
+ * fixer 자체는 순수 계산 함수.
+ *
+ * 안전:
+ *  1) apply=false(=--yes 없음) 면 dry-run — 파일을 만지지 않는다.
+ *  2) apply=true 면 원본을 `<파일>.bak-<타임스탬프>` 로 백업 후 편집.
+ *  3) 편집 중 예외가 나면 그 파일만 실패로 리포트하고 다음 파일을 계속.
+ */
+export async function runDoctorFix(reports, cwd, apply) {
+    const outcomes = [];
+    const manualRequired = [];
+    const ts = timestampSuffix(new Date());
+    for (const report of reports) {
+        const issues = report.issues.filter((i) => i.level !== 'passed');
+        if (issues.length === 0)
+            continue;
+        const fixer = FIXERS[report.rule];
+        if (!fixer) {
+            const cap = FIXER_CAPABILITIES.find((c) => c.rule === report.rule);
+            manualRequired.push({
+                rule: report.rule,
+                issueCount: issues.length,
+                note: cap?.note ?? '수동 수정 필요',
+            });
+            continue;
+        }
+        let plans;
+        try {
+            plans = await fixer(issues, cwd);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            outcomes.push({
+                rule: report.rule,
+                file: '(fixer error)',
+                summary: `fixer 실행 실패: ${msg}`,
+                applied: false,
+            });
+            continue;
+        }
+        for (const plan of plans) {
+            const label = plan.kind === 'rename' ? `${plan.file} → ${plan.to}` : plan.file;
+            if (!apply) {
+                outcomes.push({
+                    rule: report.rule,
+                    file: label,
+                    summary: plan.summary,
+                    applied: false,
+                });
+                continue;
+            }
+            try {
+                if (plan.kind === 'rename') {
+                    // 이동 대상이 이미 있으면 데이터를 덮지 않고 건너뛴다(수동 확인).
+                    if (existsSync(join(cwd, plan.to))) {
+                        outcomes.push({
+                            rule: report.rule,
+                            file: label,
+                            summary: `이동 대상이 이미 존재해 건너뜀(수동 확인 필요): ${plan.to}`,
+                            applied: false,
+                        });
+                        continue;
+                    }
+                    // importer 참조를 먼저 갱신(각각 백업), 그다음 파일 이동(내용 불변).
+                    const backups = [];
+                    for (const ref of plan.refEdits) {
+                        const bak = `${ref.file}.bak-${ts}`;
+                        await writeFile(join(cwd, bak), ref.before, 'utf8');
+                        await writeFile(join(cwd, ref.file), ref.after, 'utf8');
+                        backups.push(bak);
+                    }
+                    await rename(join(cwd, plan.file), join(cwd, plan.to));
+                    outcomes.push({
+                        rule: report.rule,
+                        file: label,
+                        summary: plan.summary + (backups.length ? `\n  ↳ importer 백업: ${backups.join(', ')}` : ''),
+                        applied: true,
+                        backup: backups[0],
+                    });
+                    continue;
+                }
+                // 내용 재작성 — 원본 백업 먼저.
+                const abs = join(cwd, plan.file);
+                const backupRel = `${plan.file}.bak-${ts}`;
+                await writeFile(join(cwd, backupRel), plan.before, 'utf8');
+                await writeFile(abs, plan.after, 'utf8');
+                outcomes.push({
+                    rule: report.rule,
+                    file: plan.file,
+                    summary: plan.summary,
+                    applied: true,
+                    backup: backupRel,
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                outcomes.push({
+                    rule: report.rule,
+                    file: label,
+                    summary: `편집 실패(원본 유지): ${msg}`,
+                    applied: false,
+                });
+            }
+        }
+    }
+    return { outcomes, manualRequired, applied: apply };
+}
+/** 사람 친화 fix 리포트. json 은 상위 renderJson 이 그대로 직렬화. */
+export function renderFixHuman(report) {
+    const lines = [];
+    const mode = report.applied ? '적용' : 'dry-run(--yes 없음 · 계획만)';
+    lines.push(`  gaon doctor --fix · ${mode}`);
+    if (report.outcomes.length === 0 && report.manualRequired.length === 0) {
+        lines.push('    (자동 정정할 대상이 없습니다.)');
+        return lines.join('\n');
+    }
+    for (const o of report.outcomes) {
+        const mark = o.applied ? '✓' : '·';
+        lines.push('');
+        lines.push(`  ${mark} [${o.rule}] ${o.file}`);
+        for (const ln of o.summary.split('\n'))
+            lines.push(`    ${ln}`);
+        if (o.backup)
+            lines.push(`    ↳ 원본 백업: ${o.backup}`);
+    }
+    if (report.manualRequired.length > 0) {
+        lines.push('');
+        lines.push('  수동 수정 필요:');
+        for (const m of report.manualRequired) {
+            lines.push(`   · [${m.rule}] 위반 ${m.issueCount}건 · ${m.note}`);
+        }
+    }
+    if (!report.applied && report.outcomes.some((o) => !o.applied)) {
+        lines.push('');
+        lines.push('  → 실제 편집은 --fix --yes 로 진행하세요(원본은 자동 백업).');
+    }
+    return lines.join('\n');
+}
+/** 파일명 안전 문자만으로 만든 로컬 타임스탬프(YYYYMMDD-HHMMSS). */
+function timestampSuffix(d) {
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    const y = d.getFullYear();
+    const M = pad(d.getMonth() + 1);
+    const D = pad(d.getDate());
+    const h = pad(d.getHours());
+    const m = pad(d.getMinutes());
+    const s = pad(d.getSeconds());
+    return `${y}${M}${D}-${h}${m}${s}`;
 }
 /**
  * 하위 호환: 응답 혼용만 검사해 legacy shape 을 낸다.

package/dist/generate.js

@@ -26,8 +26,8 @@ function renderTemplate(name, app) {
 }
 /** 템플릿 파일 → 생성 경로 매핑(라우트 제외 — 라우트는 패치로 처리). */
 const TEMPLATES = [
-    { tpl: 'user.schema.ts.tpl', out: () => 'domain/schema/user.ts' },
-    { tpl: 'user.model.ts.tpl', out: () => 'domain/models/user.ts' },
+    { tpl: 'user.schema.ts.tpl', out: () => 'domain/schema/users.ts' },
+    { tpl: 'user.model.ts.tpl', out: () => 'domain/models/User.ts' },
     { tpl: 'auth.wiring.ts.tpl', out: (a) => `apps/${a}/auth.ts` },
     { tpl: 'session.controller.ts.tpl', out: (a) => `apps/${a}/controllers/session.ts` },
     { tpl: 'registration.controller.ts.tpl', out: (a) => `apps/${a}/controllers/registration.ts` },

package/dist/hub.d.ts

@@ -1,6 +1,6 @@
 export interface HubCommandOptions {
     readonly json?: boolean;
-    /** NATS 접속지. 생략 시 GAON_NATS_URL, 그다음 기본(4222). */
+    /** NATS 접속지. 생략 시 NATS_URL(그다음 하위호환 GAON_NATS_URL), 기본(4222). */
     readonly natsUrl?: string;
     /** 리스 TTL(ms). 생략 시 env GAON_HUB_TTL_MS, 그다음 허브 기본(5000). */
     readonly ttlMs?: number;

package/dist/index.d.ts

@@ -2,7 +2,10 @@ import { type DoctorRule } from "./doctor.js";
 export { startDev, resolveDevLayout, type DevDeps, type DevLayout, type DevApp, type DevEvent, type DevHandle, } from "./dev.js";
 export { runDevCommand, type DevCommandOptions } from "./commands/dev.js";
 export { createDevConsole, findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, startTscWatchers, killChild, startRestartWatcher, isRestartChange, resolveWatchRoots, type DevConsole, type DevConsoleOptions, type DevSource, type DevLevel, type ComposeStatus, type ComposeUpOptions, type EnsureInfraResult, type DockerLocateOptions, type TscWatcherOptions, type TscWatcherHandle, type RestartWatcherOptions, type RestartWatcherHandle, } from "./dev/index.js";
-export { runCheck, runCheckCommand, type CheckDeps, type CheckResult, type TypecheckResult, type CheckCommandOptions, } from "./check.js";
+export { runCheckCommand, type CheckCommandOptions, type CheckStep, type CheckStepStatus, type CheckStepResult, } from "./commands/check.js";
+export { runNewCommand, type NewCommandOptions, type NewCommandResult } from "./commands/new.js";
+export { runConsoleCommand, type ConsoleCommandOptions } from "./commands/console.js";
+export { runTestCommand, type TestCommandOptions, type TestScope } from "./commands/test.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";
@@ -12,7 +15,8 @@ export { runJobsCommand, type JobsCommandOptions } from "./jobs.js";
 export { runDbSeedCommand, loadSeed, type DbSeedOptions, type DbSeedResult } from "./db.js";
 export { runDbCommand, type DbSubcommand, type DbCommandOptions, } from "./commands/db.js";
 export { runDbDiff, runDbMigrate, runDbReset, resolveDbTarget, type DbDiffOptions, type DbDiffResult, type DbMigrateOptions, type DbMigrateResult, type DbResetOptions, type DbResetResult, type ResolveDbOptions, type ResolvedDbTarget, } from "./db/index.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 { runDoctorCommand, runDoctor, runDoctorFix, renderFixHuman, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, type DoctorResult, type DoctorResultWithFix, type DoctorCheck, type DoctorLevel, type DoctorRule, type RuleReport, type DoctorIssue, type LegacyDoctorResult, type ActionUsage, type ResponseKind, type DoctorCommandOptions, type FixOutcome, type DoctorFixReport, } from "./doctor.js";
+export { FIXERS, FIXER_CAPABILITIES, fixDependencyDirection, fixDomainToSharedTypeOnly, type Fixer, type FixerCapability, type FixerPlan, } from "./doctor/fixers/index.js";
 export { loadDomain, type LoadedDomain } from "./domain.js";
 export interface RoadmapReport {
     readonly name: "gaon";

package/dist/index.js

@@ -12,7 +12,10 @@
  */
 import { MILESTONES, VERSION, HOMEPAGE } from "@gaonjs/core";
 import { runDevCommand } from "./commands/dev.js";
-import { runCheckCommand } from "./check.js";
+import { runCheckCommand } from "./commands/check.js";
+import { runNewCommand } from "./commands/new.js";
+import { runConsoleCommand } from "./commands/console.js";
+import { runTestCommand } from "./commands/test.js";
 import { runGenerateAuthCommand } from "./generate.js";
 import { runGenerateCommand } from "./commands/g.js";
 import { runHubCommand } from "./hub.js";
@@ -21,10 +24,14 @@ import { runWorkCommand } from "./work.js";
 import { runJobsCommand } from "./jobs.js";
 import { runDbCommand } from "./commands/db.js";
 import { runDoctorCommand } from "./doctor.js";
+import { runMcpCommand } from "./commands/mcp.js";
 export { startDev, resolveDevLayout, } from "./dev.js";
 export { runDevCommand } from "./commands/dev.js";
 export { createDevConsole, findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, startTscWatchers, killChild, startRestartWatcher, isRestartChange, resolveWatchRoots, } from "./dev/index.js";
-export { runCheck, runCheckCommand, } from "./check.js";
+export { runCheckCommand, } from "./commands/check.js";
+export { runNewCommand } from "./commands/new.js";
+export { runConsoleCommand } from "./commands/console.js";
+export { runTestCommand } from "./commands/test.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, } from "./generate.js";
 export { runGenerateCommand, planScaffold, parseGenerateArgs, } from "./commands/g.js";
 export { runHubCommand } from "./hub.js";
@@ -34,7 +41,8 @@ export { runJobsCommand } from "./jobs.js";
 export { runDbSeedCommand, loadSeed } from "./db.js";
 export { runDbCommand, } from "./commands/db.js";
 export { runDbDiff, runDbMigrate, runDbReset, resolveDbTarget, } from "./db/index.js";
-export { runDoctorCommand, runDoctor, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, } from "./doctor.js";
+export { runDoctorCommand, runDoctor, runDoctorFix, renderFixHuman, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, } from "./doctor.js";
+export { FIXERS, FIXER_CAPABILITIES, fixDependencyDirection, fixDomainToSharedTypeOnly, } from "./doctor/fixers/index.js";
 export { loadDomain } from "./domain.js";
 /** `--json` 출력용 구조화 리포트. */
 export function roadmapReport(version = VERSION) {
@@ -79,6 +87,7 @@ function renderHelp(version = VERSION) {
         "",
         "  사용법:",
         "    gaon               로드맵과 개발 상태를 출력",
+        "    gaon new <name>    새 프로젝트 스캐폴드 (파일 → 설치 → git · --skip-install · --skip-git · --pm <이름>)",
         "    gaon dev           개발 스택 통합 (Docker · .gaon · serve · tsc/vue-tsc · 재시작 워처)",
         "    gaon dev --stop-docker  Ctrl+C 시 Docker Compose 도 down",
         "    gaon dev --no-watch|--no-tsc|--no-vue-tsc|--no-docker  개별 debug 옵션",
@@ -86,23 +95,31 @@ function renderHelp(version = VERSION) {
         "    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        정적 검사 (5 검사 · 응답 혼용·N+1·의존 방향·커넥션·마이그)",
+        "    gaon check         typecheck · vue-tsc · build 통합 검사 (--only <step> · --include-doctor)",
+        "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
+        "    gaon test          테스트 러너 (--scope unit|integration|all · -- vitest 인자)",
+        "    gaon doctor        정적 검사 (7 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
+        "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
+        "    gaon doctor --fix --yes                   실제 편집 적용(원본은 .bak-<타임스탬프> 로 자동 백업)",
         "    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 app <name>          앱 스캐폴드 (apps/<name>/ · routes·controllers·pages·layouts)",
         "    gaon g <type> --overwrite  기존 파일 덮어쓰기 · --app <이름> · --json",
+        "    gaon mcp           내장 MCP 서버 · AI 도구 4종 (list_routes·get_schema·run_migration·run_tests · --http)",
         "    gaon hub           실시간 허브 프로세스 (프레즌스 권위·중계 · 리더 선출 HA)",
         "    gaon work          워커 프로세스 (잡·리스너·스케줄·아웃박스 · graceful drain)",
         "    gaon jobs list --failed   DLQ(실패 잡) 목록",
         "    gaon jobs retry <id>      DLQ 잡 재적재",
-        "    gaon db diff              스키마 ↔ DB 차이 계산 (적용 X · --json · --db <키>)",
-        "    gaon db migrate           스키마 변경을 실제 적용 + _gaon_migrations 이력",
-        "    gaon db migrate --dry-run 적용 없이 up SQL 만 출력",
+        "    gaon db diff              스키마 ↔ DB 차이 미리보기 (적용 X · --json · --db <키>)",
+        "    gaon db migrate           db/migrations/*.ts replay + 스키마 diff 적용 + 이력",
+        "    gaon db migrate down      가장 최근 이력 한 건 롤백",
+        "    gaon db migrate --dry-run 적용 없이 실행 예정 파일 + up SQL 만 출력",
+        "    gaon db status            마이그레이션 파일 적용/대기 + 스키마 drift",
         "    gaon db reset --yes       DROP ALL → 재마이그 → seed (--yes 필수 · production 거부)",
         "    gaon db seed              domain/seed.ts 실행 (M8)",
         "    gaon --json        같은 정보를 JSON 으로 출력",
@@ -124,6 +141,8 @@ export function parseDoctorChecks(argv) {
         "dependency-direction",
         "connections",
         "migration-diff",
+        "shared-composable-purity",
+        "no-auto-import",
     ];
     const isKnown = (s) => known.includes(s);
     const out = [];
@@ -179,9 +198,21 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon check` — .gaon 재생성 후 타입 검사(§13.4-5). 종료 코드로 결과 전달.
+    // `gaon check` — typecheck · vue-tsc · build (·doctor) 통합 검사(M9-G).
+    // package.json 스크립트 관례 재사용. --only <step> 로 단일 단계, --include-doctor
+    // 로 doctor 포함. 종료 코드로 결과 전달.
     if (argv[0] === "check") {
-        void runCheckCommand({ json: argv.includes("--json") })
+        const knownSteps = ["typecheck", "vue-tsc", "build", "doctor"];
+        const onlyIdx = argv.indexOf("--only");
+        const onlyRaw = onlyIdx >= 0 ? argv[onlyIdx + 1] : undefined;
+        const only = onlyRaw && knownSteps.includes(onlyRaw)
+            ? onlyRaw
+            : undefined;
+        void runCheckCommand({
+            json: argv.includes("--json"),
+            only,
+            includeDoctor: argv.includes("--include-doctor"),
+        })
             .then((code) => {
             process.exitCode = code;
         })
@@ -197,12 +228,18 @@ export function runCli(argv, opts = {}) {
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {
         const checks = parseDoctorChecks(argv);
-        void runDoctorCommand({ json: argv.includes("--json"), checks })
+        const fix = argv.includes("--fix");
+        const yes = argv.includes("--yes");
+        void runDoctorCommand({ json: argv.includes("--json"), checks, fix, yes })
             .then((result) => {
             if (result.fatal) {
                 process.exitCode = 2;
                 return;
             }
+            // --fix --yes: 편집이 실제로 일어났고 나머지 위반이 없으면 0,
+            //              아직 수동 수정이 남아 있으면 1(자동화 정합).
+            // --fix (dry-run): errors > 0 이면 1(안 고침) · 계획만 있어도 1.
+            // 기본: errors > 0 이면 1.
             process.exitCode = result.errors.length > 0 ? 1 : 0;
         })
             .catch((err) => {
@@ -212,6 +249,25 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
+    // `gaon mcp` — 내장 MCP 서버(M10-B · 정본 §12 질문 8). AI 에이전트에게 4종
+    // 도구(list_routes·get_schema·run_migration·run_tests)를 노출한다. stdio(기본)
+    // 또는 --http 전송. 표시 버전은 파사드 버전을 주입한다.
+    if (argv[0] === "mcp") {
+        void runMcpCommand({
+            json: argv.includes("--json"),
+            transport: argv.includes("--http") ? "http" : "stdio",
+            version,
+        })
+            .then((code) => {
+            process.exitCode = code;
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon mcp 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
     // `gaon hub` — 실시간 허브 프로세스(§7 M6). 운영 프로세스 3종 중 하나.
     // NATS·리더 선출 대기로 프로세스를 살려 두고, SIGINT/SIGTERM 에 그레이스풀 종료.
     if (argv[0] === "hub") {
@@ -248,10 +304,10 @@ export function runCli(argv, opts = {}) {
     // `gaon db <sub>` — diff · migrate · reset · seed (§7 M8/M9-D).
     if (argv[0] === "db") {
         const sub = argv[1];
-        const known = ["diff", "migrate", "reset", "seed"];
+        const known = ["diff", "migrate", "reset", "seed", "status"];
         if (!sub || !known.includes(sub)) {
             process.stderr.write(`  ✗ 알 수 없는 db 서브커맨드: ${sub ?? "(없음)"}\n` +
-                `  → 지원: gaon db diff | migrate | reset | seed\n` +
+                `  → 지원: gaon db diff | migrate | reset | seed | status\n` +
                 `  → 옵션: --json · --db <키> · --config <path> · --yes · --dry-run\n`);
             process.exitCode = 1;
             return;
@@ -264,6 +320,8 @@ export function runCli(argv, opts = {}) {
             config: cfgIdx >= 0 ? argv[cfgIdx + 1] : undefined,
             yes: argv.includes("--yes"),
             dryRun: argv.includes("--dry-run"),
+            // `gaon db migrate down` — 위치 인자로 롤백 지시.
+            down: sub === "migrate" && argv[2] === "down",
         };
         void runDbCommand(sub, dbOpts)
             .then((code) => {
@@ -287,7 +345,7 @@ export function runCli(argv, opts = {}) {
             process.exitCode = code;
             return;
         }
-        const known = ["controller", "model", "page", "job"];
+        const known = ["controller", "model", "page", "job", "app"];
         const type = argv[1];
         if (type && known.includes(type)) {
             const rest = argv.slice(2);
@@ -316,8 +374,13 @@ export function runCli(argv, opts = {}) {
                     name = a;
             }
             if (!name) {
+                const example = type === "page"
+                    ? "Posts/Index"
+                    : type === "app"
+                        ? "admin"
+                        : "Post";
                 process.stderr.write(`  ✗ gaon g ${type}: 이름이 없습니다.\n` +
-                    `  → 예: gaon g ${type} ${type === "page" ? "Posts/Index" : "Post"}\n`);
+                    `  → 예: gaon g ${type} ${example}\n`);
                 process.exitCode = 1;
                 return;
             }
@@ -326,11 +389,86 @@ export function runCli(argv, opts = {}) {
             return;
         }
         process.stderr.write(`  ✗ 알 수 없는 제너레이터: ${argv[1] ?? "(없음)"}\n` +
-            `  → 현재 지원: gaon g auth | controller | model | page | job\n` +
+            `  → 현재 지원: gaon g auth | controller | model | page | job | app\n` +
             `  → 옵션: --app <이름> · --overwrite · --json\n`);
         process.exitCode = 1;
         return;
     }
+    // `gaon new <name>` — 프로젝트 스캐폴드(M9-F). 파일 생성 → 의존성 설치 → git init.
+    if (argv[0] === "new") {
+        const rest = argv.slice(1);
+        let name;
+        for (const a of rest) {
+            if (!a.startsWith("--") && name === undefined)
+                name = a;
+        }
+        if (!name) {
+            process.stderr.write("  ✗ gaon new: 프로젝트 이름이 없습니다.\n  → 예: gaon new demo\n");
+            process.exitCode = 1;
+            return;
+        }
+        const pmIdx = rest.indexOf("--pm");
+        const pmRaw = pmIdx >= 0 ? rest[pmIdx + 1] : undefined;
+        const packageManager = pmRaw === "pnpm" || pmRaw === "npm" || pmRaw === "yarn" ? pmRaw : undefined;
+        void runNewCommand(name, {
+            json: argv.includes("--json"),
+            skipInstall: argv.includes("--skip-install"),
+            skipGit: argv.includes("--skip-git"),
+            packageManager,
+        })
+            .then((code) => {
+            process.exitCode = code;
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon new 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
+    // `gaon console` — 프로젝트 컨텍스트 REPL(M9-G). --no-config 로 배선 없이 기동.
+    if (argv[0] === "console") {
+        void runConsoleCommand({
+            json: argv.includes("--json"),
+            noConfig: argv.includes("--no-config"),
+        }).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon console 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
+    // `gaon test [--scope unit|integration|all] [-- vitest 인자]` — 테스트 러너(M9-G).
+    if (argv[0] === "test") {
+        const rest = argv.slice(1);
+        const scopeIdx = rest.indexOf("--scope");
+        const scopeRaw = scopeIdx >= 0 ? rest[scopeIdx + 1] : undefined;
+        const scope = scopeRaw === "unit" || scopeRaw === "integration" || scopeRaw === "all"
+            ? scopeRaw
+            : undefined;
+        const passthrough = [];
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (a === "--scope") {
+                i++;
+                continue;
+            }
+            if (a === "--json")
+                continue;
+            if (a !== undefined)
+                passthrough.push(a);
+        }
+        void runTestCommand(passthrough, { json: argv.includes("--json"), scope })
+            .then((code) => {
+            process.exitCode = code;
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon test 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
     if (argv.includes("--help") || argv.includes("-h")) {
         process.stdout.write(renderHelp(version) + "\n");
         return;

package/dist/mcp/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @gaonjs/cli · MCP 모듈 public exports — v0.15 §13.5 M10.
+ *
+ * `gaon mcp` 명령이 소비하는 조립 API. tools.ts 의 TOOLS 카탈로그는 SSOT.
+ */
+export { createMcpServer, startMcpServer, SERVER_NAME, type McpServerOptions, type McpServerHandle, type McpServerVersion, } from './server.js';
+export { TOOLS, findTool, listRoutesTool, getSchemaTool, runMigrationTool, runTestsTool, projectSummary, type McpToolSpec, type ToolResult, type ToolArgs, } from './tools.js';

package/dist/mcp/index.js

@@ -0,0 +1,7 @@
+/**
+ * @gaonjs/cli · MCP 모듈 public exports — v0.15 §13.5 M10.
+ *
+ * `gaon mcp` 명령이 소비하는 조립 API. tools.ts 의 TOOLS 카탈로그는 SSOT.
+ */
+export { createMcpServer, startMcpServer, SERVER_NAME, } from './server.js';
+export { TOOLS, findTool, listRoutesTool, getSchemaTool, runMigrationTool, runTestsTool, projectSummary, } from './tools.js';