@gaonjs/cli 0.5.0 → 0.10.1

package/dist/doctor/schema-filename.js

@@ -0,0 +1,81 @@
+// @gaonjs/cli · doctor · 스키마 파일명 관례 (결정 38 · 2026-07-25)
+//
+// 정본 §1.1: 스키마 파일명 = 테이블명을 **camelCase** 로 바꾼 것. 테이블명에
+// `_` 가 있어도 파일명엔 `_` 를 쓰지 않는다 — 조인 테이블 `posts_tags` →
+// `domain/schema/postsTags.ts` (파일 안 `table('posts_tags', …)` 는 스네이크
+// 유지). 소형 모델(haiku)이 다단어 테이블에서 파일명을 스네이크로 쓰는
+// 실측(feature-slice T4)이 있어, 잘못된 파일명을 검출해 §7.5.3 수리 안내를
+// 준다. `The One Way` — 두 형태 허용 없이 camelCase 하나로 못박는다.
+//
+// 판정 범위: **파일명이 camelCase 가 아닌 경우만**(스네이크·케밥·Pascal) 잡는다.
+// 단수/복수(`post.ts` vs `posts.ts`)는 이 결정의 대상이 아니라 건드리지 않는다
+// — 기존 fixture 가 단수 파일명(`post.ts`)을 쓰므로 그것까지 실격시키면 결정
+// 범위를 넘는다. 그래서 기대 파일명은 **실제 파일명 stem 을 camelCase 로 정규화**
+// 한 값이다(테이블명 단수화가 아님). 이미 camelCase 면 정규화해도 그대로라 통과.
+// table() 선언이 있는 파일만 대상으로 삼아 배럴·비스키마 파일 오탐을 막는다.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, join, relative } from 'node:path';
+import { toCamel, toPascal } from '../scaffold/inflect.js';
+/** 파일 stem 을 camelCase 로 정규화(`posts_tags`→`postsTags` · `Posts`→`posts` · `posts`→`posts`). */
+export function expectedSchemaStem(stem) {
+    return toCamel(toPascal(stem));
+}
+/** 소스에서 첫 `table('<이름>', …)` 의 테이블명을 뽑는다(없으면 undefined). */
+export function extractTableName(source) {
+    const m = source.match(/\btable\(\s*['"`]([^'"`]+)['"`]/);
+    return m ? m[1] : undefined;
+}
+export async function checkSchemaFilename(cwd) {
+    const schemaDir = join(cwd, 'domain', 'schema');
+    const files = [];
+    await collectTsFiles(schemaDir, files);
+    const issues = [];
+    for (const abs of files) {
+        const source = await readFile(abs, 'utf8');
+        const tableName = extractTableName(source);
+        if (!tableName)
+            continue; // table() 없음 = 스키마 테이블 파일 아님 · 건너뜀
+        const actualStem = basename(abs).replace(/\.ts$/, '');
+        const expected = expectedSchemaStem(actualStem);
+        if (actualStem === expected)
+            continue; // 이미 camelCase(단수/복수 무관) · 통과
+        const rel = relative(cwd, abs).split('\\').join('/');
+        const expectedRel = rel.replace(/[^/]+\.ts$/, `${expected}.ts`);
+        issues.push({
+            rule: 'schema-filename',
+            level: 'error',
+            file: rel,
+            message: `스키마 파일명이 관례(§1.1 · camelCase)와 어긋납니다: '${actualStem}.ts' ` +
+                `(테이블 '${tableName}' · 기대 파일명 '${expected}.ts').\n` +
+                `→ '${rel}' 를 '${expectedRel}' 로 이름을 바꾸고, 이 스키마를 import 하는 ` +
+                `모델(예: '../schema/${expected}.js')의 경로도 함께 고치세요. ` +
+                `테이블명 문자열('${tableName}')은 그대로 둡니다.`,
+            detail: { tableName, actual: `${actualStem}.ts`, expected: `${expected}.ts` },
+        });
+    }
+    return { rule: 'schema-filename', issues };
+}
+/** domain/schema/ 아래 .ts(선언·테스트 제외)를 재귀 수집. migration-diff 와 동일 패턴. */
+async function collectTsFiles(root, out) {
+    let entries;
+    try {
+        entries = (await readdir(root, { withFileTypes: true }));
+    }
+    catch {
+        return; // domain/schema/ 없음 = 검사할 것 없음
+    }
+    for (const e of entries) {
+        const p = join(root, e.name);
+        if (e.isDirectory()) {
+            await collectTsFiles(p, out);
+        }
+        else if (e.isFile() &&
+            e.name.endsWith('.ts') &&
+            !e.name.endsWith('.d.ts') &&
+            !e.name.endsWith('.test.ts')) {
+            const s = await stat(p);
+            if (s.isFile())
+                out.push(p);
+        }
+    }
+}

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';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -8,12 +8,45 @@ export { extractConfigDbKeys, extractKeyUses, checkConnections } from './doctor/
 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';
 export interface DoctorCommandOptions {
     readonly cwd?: string;
     readonly json?: boolean;
     readonly checks?: readonly DoctorRule[];
+    /**
+     * 자동 정정 모드(v0.16 §7.5.3). true 면 각 규칙의 fixer 를 계획한다.
+     * `yes` 가 없으면 dry-run(계획만 보고 · 파일 편집 X), 있으면 실제 편집.
+     * 편집 전 원본은 `<파일>.bak-<타임스탬프>` 로 백업된다(--yes 여도 안전망).
+     */
+    readonly fix?: boolean;
+    /** 실제 파일 편집 승인. `fix` 와 함께 줘야 편집이 일어난다. */
+    readonly yes?: boolean;
+}
+/** --fix 리포트의 파일별 결과. FixerPlan 위에 dry/applied 상태를 얹는다. */
+export interface FixOutcome {
+    readonly rule: DoctorRule;
+    readonly file: string;
+    readonly summary: string;
+    /** true 이면 실제 편집됨, false 이면 dry-run(계획만 · --yes 없음). */
+    readonly applied: boolean;
+    /** 실제 편집 시 원본 백업 경로(프로젝트 상대). dry-run 은 undefined. */
+    readonly backup?: string;
+}
+/** --fix 실행 결과. runCli 는 fixesApplied · fixesPlanned 로 종료 코드 결정. */
+export interface DoctorFixReport {
+    /** fixer 가 있는 규칙별 계획·적용 결과. */
+    readonly outcomes: readonly FixOutcome[];
+    /** fixer 가 없어서 수동 수정이 필요한 규칙별 위반 수(요약). */
+    readonly manualRequired: readonly {
+        rule: DoctorRule;
+        issueCount: number;
+        note: string;
+    }[];
+    /** 실제로 편집이 일어났는지(--yes 여부). */
+    readonly applied: boolean;
 }
 /**
  * `gaon doctor` 진입점 (M9-E · 확장 · M9-E-Fix 하드닝).
@@ -35,6 +68,22 @@ export interface DoctorCommandOptions {
  * 나머지 규칙은 계속 실행(부분 결과 확보).
  */
 export declare function runDoctorCommand(opts?: DoctorCommandOptions): Promise<DoctorResult>;
+/**
+ * fixer 를 계획·(승인 시)실행한다. 파일 편집은 여기서만 일어난다 —
+ * fixer 자체는 순수 계산 함수.
+ *
+ * 안전:
+ *  1) apply=false(=--yes 없음) 면 dry-run — 파일을 만지지 않는다.
+ *  2) apply=true 면 원본을 `<파일>.bak-<타임스탬프>` 로 백업 후 편집.
+ *  3) 편집 중 예외가 나면 그 파일만 실패로 리포트하고 다음 파일을 계속.
+ */
+export declare function runDoctorFix(reports: readonly RuleReport[], cwd: string, apply: boolean): Promise<DoctorFixReport>;
+/** 리포트에 함께 실려 나가는 확장 결과. runCli 가 종료 코드를 결정하는 근거. */
+export interface DoctorResultWithFix extends DoctorResult {
+    readonly fix: DoctorFixReport;
+}
+/** 사람 친화 fix 리포트. json 은 상위 renderJson 이 그대로 직렬화. */
+export declare function renderFixHuman(report: DoctorFixReport): string;
 export interface DoctorIssue {
     readonly file: string;
     readonly line: number;

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 7 검사를 조립한다:
+ * 8 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -9,6 +9,7 @@
  *  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)를 위해 반드시 파싱 가능한
@@ -17,7 +18,9 @@
  * 하위 호환: 기존 응답 혼용 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';
@@ -26,9 +29,12 @@ 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';
@@ -36,6 +42,8 @@ export { extractConfigDbKeys, extractKeyUses, checkConnections } from './doctor/
 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';
 /**
@@ -49,6 +57,8 @@ const ALL_RULES = [
     'migration-diff',
     'shared-composable-purity',
     'no-auto-import',
+    'schema-filename',
+    'agents-doc-index',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -58,6 +68,8 @@ const CHECKERS = {
     '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 하드닝).
@@ -130,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

@@ -15,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

@@ -24,6 +24,7 @@ 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";
@@ -40,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) {
@@ -99,19 +101,25 @@ function renderHelp(version = VERSION) {
         "    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 으로 출력",
@@ -220,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) => {
@@ -235,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") {
@@ -271,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;
@@ -287,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) => {
@@ -310,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);
@@ -339,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;
             }
@@ -349,7 +389,7 @@ 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;

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';

package/dist/mcp/server.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @gaonjs/cli · MCP 서버 배선 — v0.15 §13.5 M10 · 질문 8.
+ *
+ * `gaon mcp` 가 이 함수를 stdio 트랜스포트로 부트업한다. Node.js MCP SDK
+ * (@modelcontextprotocol/sdk) 의 Server + StdioServerTransport 를 사용해
+ * JSON-RPC 2.0 over stdio 로 4 도구를 노출한다(§9 실 프로토콜).
+ *
+ * 도구 목록/호출은 tools.ts 의 TOOLS 카탈로그를 그대로 소비 — 카탈로그가
+ * 단일 진실 원천(SSOT). 여기서 도구를 추가하지 않는다.
+ *
+ * transport:
+ *   - stdio (기본 · MCP 표준)
+ *   - http 는 v1 범위 외(§13.5 M10 명시 X · 필요 시 후속 마일스톤에서 추가)
+ *
+ * 종료: transport 가 닫히면(SIGINT / stdin 종료) close() 로 정리한다.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+/** 서버 이름·버전 — MCP initialize 응답의 serverInfo. */
+export declare const SERVER_NAME = "gaon";
+/**
+ * 서버 버전 — CLI 가 주입한다(호출자가 넘긴 값 · 미주입 시 'dev').
+ * 실제 값은 packages/cli/package.json 의 version(파사드 gaonjs 로 재수출됨).
+ */
+export type McpServerVersion = string;
+export interface McpServerOptions {
+    /** 프로젝트 루트 — 각 도구가 이 cwd 기준으로 관례를 해석. */
+    readonly cwd: string;
+    /** 서버 버전 — 미주입 시 'dev'. */
+    readonly version?: McpServerVersion;
+}
+/** 서버 핸들 — 종료 대기·강제 종료용. */
+export interface McpServerHandle {
+    /** transport 가 종료될 때까지 대기. stdin close / SIGINT 시 resolve. */
+    wait(): Promise<void>;
+    /** 강제 종료 — server + transport 정리. */
+    close(): Promise<void>;
+}
+/**
+ * MCP 서버 인스턴스 만들기 + tool handlers 등록.
+ * transport 연결은 startMcpServer 에서 한다(테스트 격리를 위해 분리).
+ */
+export declare function createMcpServer(opts: McpServerOptions): Server;
+/**
+ * `gaon mcp` 본체 — stdio transport 로 서버를 부트업하고 stdin close 를 기다린다.
+ * 반환 핸들의 wait() 는 transport 가 종료될 때 resolve.
+ *
+ * 테스트에서는 stdio 를 파이프로 감싼 자식 프로세스로 실행하고, 이 함수는
+ * 자식 프로세스 내부에서 호출된다(§9 실 프로토콜 왕복).
+ */
+export declare function startMcpServer(opts: McpServerOptions): Promise<McpServerHandle>;