@gaonjs/cli 0.43.0 → 0.52.0

package/README.md

@@ -2,7 +2,7 @@
 
 Gaon CLI — `gaon` 명령. 프로젝트 스캐폴드(`gaon new`), 개발 스택 통합(`gaon dev`),
 제너레이터(`gaon g auth`·scaffold), 마이그레이션(`gaon db …`), 통합 검사
-(`gaon check`), 정적 검사(`gaon doctor` · 20종), 운영 부팅(`gaon serve`). 모든
+(`gaon check`), 정적 검사(`gaon doctor` · `--fix`), 운영 부팅(`gaon serve`). 모든
 명령은 `--json` 출력을 지원합니다.
 
 이 패키지는 [`gaonjs`](https://www.npmjs.com/package/gaonjs) 파사드에 포함됩니다 —

package/dist/commands/check.d.ts

@@ -52,7 +52,7 @@ export interface CheckReport {
 /**
  * `gaon check` 진입점. 검사 전에 .gaon 을 재생성(규칙 3)한 뒤 각 단계를
  * 순서대로 실행하고, 하나라도 실패하면 exit 1. --only 지정 시 그 단계만
- * 실행. --include-doctor 시 doctor 추가.
+ * 실행. doctor 는 기본 포함(결정 157) — --no-doctor 로만 뺀다.
  *
  * §9 실 인프라 · 목업 X — 실 spawn 으로 검증한다.
  */

package/dist/commands/check.js

@@ -271,7 +271,7 @@ async function regenerateGaon(cwd) {
 /**
  * `gaon check` 진입점. 검사 전에 .gaon 을 재생성(규칙 3)한 뒤 각 단계를
  * 순서대로 실행하고, 하나라도 실패하면 exit 1. --only 지정 시 그 단계만
- * 실행. --include-doctor 시 doctor 추가.
+ * 실행. doctor 는 기본 포함(결정 157) — --no-doctor 로만 뺀다.
  *
  * §9 실 인프라 · 목업 X — 실 spawn 으로 검증한다.
  */

package/dist/commands/db.js

@@ -11,7 +11,7 @@ import { runDbDiff } from '../db/diff.js';
 import { runDbMigrate } from '../db/migrate.js';
 import { runDbReset } from '../db/reset.js';
 import { runDbStatus } from '../db/status.js';
-import { listConnectionKeys } from '../db/resolve.js';
+import { listConnectionKeysByKind } from '../db/resolve.js';
 import { runDbSeedCommand } from '../db.js';
 /** 전 커넥션 순회 대상 서브커맨드(결정 139 · reset 은 파괴적이라 제외 · 단일 유지). */
 const MULTI_CONN_SUBS = new Set(['diff', 'migrate', 'status', 'seed']);
@@ -57,14 +57,29 @@ export async function runDbCommand(subcommand, opts = {}) {
         // `--db <키>` 는 단일 좁힘. reset(파괴적)은 항상 단일(main 폴백).
         const wantsAll = subcommand !== 'reset' && (opts.db === undefined || opts.db === 'all');
         if (wantsAll && MULTI_CONN_SUBS.has(subcommand)) {
-            const keys = await listConnectionKeys(cwd, configPath);
-            // 단일 커넥션이면 종전 출력과 100% 동일(하위 호환).
-            if (keys.length === 1) {
+            // 결정 292: 문서형(mongodb) 커넥션은 마이그레이션이 없어(§7.4) 순회에서 **건너뛴다** —
+            // 종전에는 mongo 키가 실패로 계상돼 mongo 커넥션이 하나라도 있으면 항상 exit 1 이었다.
+            // `--db <mongo키>` 명시 지정은 아래 단일 경로에서 여전히 fail-loud(resolveDbTarget).
+            const { sql: keys, mongo: mongoKeys } = await listConnectionKeysByKind(cwd, configPath);
+            if (keys.length === 0) {
+                // 문서형만 있는 프로젝트 — 마이그레이션 대상 없음 = 성공 no-op(수리 대상 아님).
+                const note = `문서형(mongodb) 커넥션 ${mongoKeys.join(', ')} 은 마이그레이션 대상이 아닙니다(§7.4) — SQL 커넥션 없음, ${subcommand} 할 것 없음.`;
+                emit(`  ○ ${note}`, {
+                    command: subcommand,
+                    connections: [],
+                    skipped: mongoKeys.map((db) => ({ db, adapter: 'mongodb', reason: 'documental-no-migration' })),
+                    ok: true,
+                    results: [],
+                });
+                return 0;
+            }
+            // 단일 SQL 커넥션 + 문서형 없음이면 종전 출력과 100% 동일(하위 호환).
+            if (keys.length === 1 && mongoKeys.length === 0) {
                 const r = await runOne(keys[0]);
                 emit(r.text, r.json);
                 return r.exitCode;
             }
-            return runAcrossConnections(subcommand, keys, runOne, emit, json);
+            return runAcrossConnections(subcommand, keys, runOne, emit, json, mongoKeys);
         }
         // 단일 커넥션 경로(--db <키> · reset · env-only 폴백) — 종전 동작 그대로.
         if (subcommand === 'reset' && opts.db === 'all') {
@@ -97,7 +112,7 @@ export async function runDbCommand(subcommand, opts = {}) {
  * 실패해도 나머지를 계속한다(부분 적용 방지가 아니라 부분 진행 후 전체 보고 — 어느
  * 커넥션이 성공/실패했는지가 사용자에게 필요). exitCode = 하나라도 실패면 1.
  */
-async function runAcrossConnections(subcommand, keys, runOne, emit, json) {
+async function runAcrossConnections(subcommand, keys, runOne, emit, json, skippedMongo = []) {
     const results = [];
     for (const key of keys) {
         try {
@@ -121,12 +136,19 @@ async function runAcrossConnections(subcommand, keys, runOne, emit, json) {
         emit('', {
             command: subcommand,
             connections: keys,
+            // 결정 292: 문서형(mongodb) 커넥션은 순회 대상이 아니다 — skipped 로 명시 보고.
+            ...(skippedMongo.length > 0
+                ? { skipped: skippedMongo.map((db) => ({ db, adapter: 'mongodb', reason: 'documental-no-migration' })) }
+                : {}),
             ok: failed.length === 0,
             results: results.map((r) => ({ db: r.db, ok: r.ok, ...r.json })),
         });
         return exitCode;
     }
-    const header = `  gaon db ${subcommand} · 커넥션 ${keys.length}개 순회: ${keys.join(', ')}`;
+    const skippedNote = skippedMongo.length > 0
+        ? `\n  ○ 문서형(mongodb) 커넥션 건너뜀: ${skippedMongo.join(', ')} — 문서형은 마이그레이션이 없습니다(§7.4 · 인덱스는 Mongoose 스키마 선언).`
+        : '';
+    const header = `  gaon db ${subcommand} · 커넥션 ${keys.length}개 순회: ${keys.join(', ')}${skippedNote}`;
     const sections = results.map((r) => `  ── [${r.db}] ${'─'.repeat(Math.max(0, 40 - r.db.length))}\n${r.text}`);
     const footer = failed.length === 0
         ? `  ✓ 전 커넥션 완료(${keys.length}개).`

package/dist/commands/new.d.ts

@@ -44,6 +44,8 @@ export interface NewCommandResult {
     readonly totalMs: number;
     readonly error?: string;
 }
+/** 이름 유효성 — npm 패키지명 규칙(단순 부분)만 검사. */
+export declare function validateProjectName(name: string): void;
 /**
  * `gaon new <name>` 실행. 파일 생성 → pnpm install → git init 순서.
  * 각 단계는 옵션으로 스킵 가능. 반환값은 프로세스 종료 코드(0=성공).

package/dist/commands/new.js

@@ -26,7 +26,7 @@ import { renderProjectFiles, PACKAGE_MANAGER_PINS, } from '../templates/index.js
 import { writeUiKitScaffold } from '../uikit.js';
 import { regenerateProjectGaon } from './gen.js';
 /** 이름 유효성 — npm 패키지명 규칙(단순 부분)만 검사. */
-function validateProjectName(name) {
+export function validateProjectName(name) {
     if (!name)
         throw new Error('프로젝트 이름이 비어 있습니다.');
     if (name.includes('/') || name.includes('\\')) {
@@ -35,8 +35,13 @@ function validateProjectName(name) {
     if (name.includes('..')) {
         throw new Error(`프로젝트 이름에 '..' 는 사용할 수 없습니다: ${name}`);
     }
-    if (!/^[a-z0-9][a-z0-9_-]*$/i.test(name)) {
-        throw new Error(`프로젝트 이름은 영문/숫자/-/_ 로 시작해 같은 문자만 씁니다: ${name}\n` +
+    // 결정 315: 소문자·숫자·하이픈만 — 이름이 compose 프로젝트명(소문자만 유효)과
+    // MinIO/S3 버킷명(`_`·대문자 불허)으로 그대로 치환되므로(docker-compose.yaml.tpl),
+    // 대문자·언더스코어를 받으면 gaon dev 인프라 기동·첫 업로드가 뒤늦게 깨진다.
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+        throw new Error(`프로젝트 이름은 소문자 영문/숫자로 시작해 소문자/숫자/하이픈(-)만 씁니다: ${name}\n` +
+            `  → 이름은 Docker Compose 프로젝트명과 스토리지 버킷명으로 그대로 쓰여\n` +
+            `    대문자·언더스코어(_)는 인프라 기동·버킷 생성에서 실패합니다.\n` +
             `  → 예: gaon new my-app · gaon new demo`);
     }
 }

package/dist/commands/test.js

@@ -106,7 +106,11 @@ async function provisionTestDatabases(cwd, json, onOutput) {
                 connectionOverride: testCfg,
             });
             if (res.exitCode !== 0) {
-                if (!json)
+                // 결정 360: json 모드도 구조화 에러를 낸다 — 이전엔 이 분기만 0 바이트로
+                // exit 1 이라 자동화가 실패 원인을 전혀 못 받았다(catch 분기와 비대칭).
+                if (json)
+                    writeOut(JSON.stringify({ ok: false, kind: 'provision', db: key, error: res.text }) + '\n');
+                else
                     writeErr(`  ✗ 테스트 DB '${key}' 마이그레이션 실패\n${res.text}\n`);
                 return false;
             }
@@ -211,18 +215,27 @@ export async function runTestCommand(args = [], opts = {}) {
     else {
         writeOut(`  gaon test · ${cmd} ${spawnArgs.join(' ')} (scope=${scope})\n`);
     }
+    // 결정 360: --json 은 stdout 이 순수 JSON 라인이어야 한다(결정 269 check 와 대칭).
+    // 이전엔 json 모드도 stdio:'inherit' 라 vitest 사람용 출력이 JSON 라인 사이에 섞여
+    // `gaon test --json | jq` 류 자동화가 깨졌다. 자식 출력은 {kind:'output'} 라인으로 감싼다.
+    const jsonPipe = json && !capture;
     const exitCode = await new Promise((resolvePromise) => {
         // capture(MCP) 모드는 자식 출력을 파이프로 모아 싱크로 흘린다(도구 응답에 담기).
-        // CLI 경로(미지정)는 vitest 컬러 출력·리포터를 그대로 보이게 stdio 를 상속한다.
+        // CLI 사람 경로(미지정)는 vitest 컬러 출력·리포터를 그대로 보이게 stdio 를 상속한다.
         const child = spawn(cmd, spawnArgs, {
             cwd,
             env: testEnv,
-            stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+            stdio: capture || jsonPipe ? ['ignore', 'pipe', 'pipe'] : 'inherit',
         });
         if (capture) {
             child.stdout?.on('data', (d) => opts.onOutput(d.toString('utf8')));
             child.stderr?.on('data', (d) => opts.onOutput(d.toString('utf8')));
         }
+        else if (jsonPipe) {
+            const emit = (stream) => (d) => writeOut(JSON.stringify({ kind: 'output', stream, chunk: d.toString('utf8') }) + '\n');
+            child.stdout?.on('data', emit('stdout'));
+            child.stderr?.on('data', emit('stderr'));
+        }
         child.on('error', (err) => {
             writeErr(`  ✗ gaon test spawn 실패: ${String(err)}\n`);
             resolvePromise(127);

package/dist/db/journal.d.ts

@@ -1,4 +1,5 @@
 import { type Kysely } from 'kysely';
+import { type AdapterName } from '@gaonjs/data';
 export type MigrationKind = 'file' | 'schema';
 export interface JournalEntry {
     readonly id: string;
@@ -17,7 +18,7 @@ export interface JournalEntry {
  * pg 는 count 를 bigint(문자열)로, mysql 은 number 로 돌려주므로 `Number()` 로 통일한다
  * (양 방언 공통 · 결정 268).
  */
-export declare function journalExists(db: Kysely<any>): Promise<boolean>;
+export declare function journalExists(db: Kysely<any>, adapter?: AdapterName): Promise<boolean>;
 /**
  * _gaon_migrations 를 만든다(존재하면 no-op). id/kind/applied_at/db_key/
  * statements/summary/down_sql — text·varchar·timestamp·integer 는 postgres·
@@ -35,7 +36,7 @@ export interface RecordArgs {
 /** 이력 한 행을 남긴다. 호출자가 트랜잭션(trx)을 넘기면 그 안에서 실행된다. */
 export declare function recordEntry(db: Kysely<any>, e: RecordArgs): Promise<void>;
 /** 가장 최근 적용된 이력(롤백 대상). 원장 미존재 시 undefined. */
-export declare function latestEntry(db: Kysely<any>): Promise<JournalEntry | undefined>;
+export declare function latestEntry(db: Kysely<any>, adapter?: AdapterName): Promise<JournalEntry | undefined>;
 /** kind='file' 로 적용된 파일명 집합. 원장 미존재 시 빈 집합. */
-export declare function appliedFileMigrations(db: Kysely<any>): Promise<Set<string>>;
+export declare function appliedFileMigrations(db: Kysely<any>, adapter?: AdapterName): Promise<Set<string>>;
 export declare function deleteEntry(db: Kysely<any>, id: string): Promise<void>;

package/dist/db/journal.js

@@ -17,12 +17,23 @@ import { MIGRATIONS_TABLE } from '@gaonjs/data';
  * pg 는 count 를 bigint(문자열)로, mysql 은 number 로 돌려주므로 `Number()` 로 통일한다
  * (양 방언 공통 · 결정 268).
  */
-export async function journalExists(db) {
-    const rows = await sql `
-    select count(*) as n
-    from information_schema.tables
-    where table_name = ${MIGRATIONS_TABLE}
-  `.execute(db);
+export async function journalExists(db, adapter = 'postgres') {
+    // 결정 326: mysql/mariadb 의 information_schema.tables 는 **서버 전체(모든 database)** 를
+    // 보므로 같은 서버 다른 DB 의 _gaon_migrations 에 오탐했다 — 존재 오판 뒤
+    // appliedFileMigrations 가 없는 테이블을 select 해 migrate/status 가 죽는다(공유 dev 서버
+    // 현실 시나리오) → database() 로 현재 DB 에 한정한다. pg 는 카탈로그가 database 단위라
+    // 종전대로 둔다(스키마('public') 한정은 커스텀 search_path 프로젝트를 깨서 안 한다).
+    const rows = adapter === 'mysql'
+        ? await sql `
+          select count(*) as n
+          from information_schema.tables
+          where table_name = ${MIGRATIONS_TABLE} and table_schema = database()
+        `.execute(db)
+        : await sql `
+          select count(*) as n
+          from information_schema.tables
+          where table_name = ${MIGRATIONS_TABLE}
+        `.execute(db);
     const first = rows.rows[0];
     return first ? Number(first.n) > 0 : false;
 }
@@ -53,8 +64,8 @@ export async function recordEntry(db, e) {
   `.execute(db);
 }
 /** 가장 최근 적용된 이력(롤백 대상). 원장 미존재 시 undefined. */
-export async function latestEntry(db) {
-    if (!(await journalExists(db)))
+export async function latestEntry(db, adapter = 'postgres') {
+    if (!(await journalExists(db, adapter)))
         return undefined;
     const rows = await sql `
     select id, kind, db_key, statements, summary, down_sql, applied_at
@@ -65,8 +76,8 @@ export async function latestEntry(db) {
     return rows.rows[0];
 }
 /** kind='file' 로 적용된 파일명 집합. 원장 미존재 시 빈 집합. */
-export async function appliedFileMigrations(db) {
-    if (!(await journalExists(db)))
+export async function appliedFileMigrations(db, adapter = 'postgres') {
+    if (!(await journalExists(db, adapter)))
         return new Set();
     const rows = await sql `
     select id from ${sql.ref(MIGRATIONS_TABLE)} where kind = 'file'

package/dist/db/migrate.d.ts

@@ -1,4 +1,4 @@
-import { type ConnectionConfig } from '@gaonjs/data';
+import { type MigrationOp, type ConnectionConfig } from '@gaonjs/data';
 import { listMigrationFiles } from './replay.js';
 export interface DbMigrateOptions {
     readonly cwd: string;
@@ -16,6 +16,8 @@ export interface DbMigrateResult {
     readonly text: string;
     readonly json: unknown;
 }
+/** drop 계열 부속 op 을 사람이 읽는 한 줄로 — 크게 알리는 note 용(status 도 재사용 · 결정 326). */
+export declare function describeDeferred(op: MigrationOp): string;
 /**
  * `gaon db migrate` — 진짜 apply(합성형: replay → schema-diff). 실 DB 필요(§9).
  */

package/dist/db/migrate.js

@@ -17,8 +17,8 @@ import { computeMigration, renderUp, renderDown, summarizeOp, DEFERRED_DROP_KIND
 import { resolveDbTarget } from './resolve.js';
 import { ensureJournal, journalExists, recordEntry } from './journal.js';
 import { listMigrationFiles, replayPending, rollbackLast } from './replay.js';
-/** drop 계열 부속 op 을 사람이 읽는 한 줄로 — 크게 알리는 note 용. */
-function describeDeferred(op) {
+/** drop 계열 부속 op 을 사람이 읽는 한 줄로 — 크게 알리는 note 용(status 도 재사용 · 결정 326). */
+export function describeDeferred(op) {
     switch (op.kind) {
         case 'dropUnique':
             return `unique(${op.name}: ${op.columns.join(', ')})`;
@@ -116,7 +116,7 @@ export async function runDbMigrate(opts) {
             };
         }
         // baseline 감지 — journal 이 없는데 createTable 이 포함 → 안내(§7.5.3).
-        const hadJournal = await journalExists(target.db);
+        const hadJournal = await journalExists(target.db, target.adapter);
         const hasCreate = plan.ops.some((o) => o.kind === 'createTable');
         const baselineNote = !hadJournal && hasCreate
             ? `  ℹ 최초 마이그레이션(_gaon_migrations 미존재) — 이 배치가 baseline 이 됩니다.\n` +

package/dist/db/replay.js

@@ -66,7 +66,7 @@ export async function replayPending(opts) {
     const all = listMigrationFiles(opts.cwd);
     if (all.length === 0)
         return { applied: [], pending: [], all: [] };
-    const done = await appliedFileMigrations(opts.db);
+    const done = await appliedFileMigrations(opts.db, opts.adapter);
     const pending = all.filter((f) => !done.has(f));
     if (opts.dryRun || pending.length === 0) {
         return { applied: [], pending, all };
@@ -104,7 +104,7 @@ export async function replayPending(opts) {
  * 되돌린 뒤 이력 행을 지운다. --dry-run 은 대상만 보고 실행하지 않는다.
  */
 export async function rollbackLast(opts) {
-    const entry = await latestEntry(opts.db);
+    const entry = await latestEntry(opts.db, opts.adapter);
     if (!entry)
         return { rolledBack: null, kind: null };
     if (opts.dryRun)

package/dist/db/resolve.d.ts

@@ -33,4 +33,19 @@ export interface ResolvedDbTarget {
  * 폴백(GAON_DATABASE_URL 관례) — 단일 커넥션 프로젝트의 종전 동작과 정합.
  */
 export declare function listConnectionKeys(cwd: string, configPath?: string): Promise<string[]>;
+/** SQL 키 / 문서형(mongodb) 키 분리 목록 — 전 커넥션 순회의 skip 판단용(결정 292). */
+export interface ConnectionKeysByKind {
+    /** SQL(postgres·mysql) 커넥션 키 — diff/migrate/status/seed 순회 대상. */
+    readonly sql: string[];
+    /** 문서형(mongodb) 커넥션 키 — 마이그레이션 없음(§7.4) · 순회에서 건너뛴다. */
+    readonly mongo: string[];
+}
+/**
+ * 전 커넥션 순회(결정 139)용으로 커넥션 키를 SQL/문서형으로 갈라 돌려준다(결정 292).
+ * 문서형(mongodb)은 마이그레이션이 없어(§7.4) 순회에서 **건너뛰는** 대상이다 —
+ * 종전에는 순회가 mongo 키를 실패로 계상해 `gaon db migrate` 가 항상 exit 1 이었다.
+ * `--db <mongo키>` 명시 지정은 여전히 resolveDbTarget 이 fail-loud 로 안내한다.
+ * config 선언이 없으면(env-only) SQL ['main'] 폴백 — listConnectionKeys 와 정합.
+ */
+export declare function listConnectionKeysByKind(cwd: string, configPath?: string): Promise<ConnectionKeysByKind>;
 export declare function resolveDbTarget(opts: ResolveDbOptions): Promise<ResolvedDbTarget>;

package/dist/db/resolve.js

@@ -97,6 +97,28 @@ export async function listConnectionKeys(cwd, configPath) {
     const keys = Object.keys(config.db ?? {});
     return keys.length ? keys : ['main'];
 }
+/**
+ * 전 커넥션 순회(결정 139)용으로 커넥션 키를 SQL/문서형으로 갈라 돌려준다(결정 292).
+ * 문서형(mongodb)은 마이그레이션이 없어(§7.4) 순회에서 **건너뛰는** 대상이다 —
+ * 종전에는 순회가 mongo 키를 실패로 계상해 `gaon db migrate` 가 항상 exit 1 이었다.
+ * `--db <mongo키>` 명시 지정은 여전히 resolveDbTarget 이 fail-loud 로 안내한다.
+ * config 선언이 없으면(env-only) SQL ['main'] 폴백 — listConnectionKeys 와 정합.
+ */
+export async function listConnectionKeysByKind(cwd, configPath) {
+    const { config } = await loadDbConfig(resolvePath(cwd), configPath);
+    const entries = Object.entries(config.db ?? {});
+    if (entries.length === 0)
+        return { sql: ['main'], mongo: [] };
+    const sql = [];
+    const mongo = [];
+    for (const [key, cfg] of entries) {
+        if (cfg?.adapter === 'mongodb')
+            mongo.push(key);
+        else
+            sql.push(key);
+    }
+    return { sql, mongo };
+}
 export async function resolveDbTarget(opts) {
     const cwd = resolvePath(opts.cwd);
     // 사용자가 --config <path> 를 준 경우 그 경로에서 default export 를 로드한다.
@@ -132,8 +154,8 @@ export async function resolveDbTarget(opts) {
     // introspect)로 흘리지 않고 명확히 안내한다. 몽고 인덱스는 Mongoose 스키마 선언으로 관리한다.
     if (connCfg.adapter === 'mongodb') {
         throw new Error(`[gaon db] 커넥션 '${dbKey}' 은 문서형(mongodb)입니다 — 문서형은 마이그레이션이 없습니다(§7.4).\n` +
-            `  → 몽고 인덱스는 Mongoose 스키마 선언(index:true / schema.index())으로 관리합니다(dev 자동 ensureIndexes).\n` +
-            `  → gaon db diff/migrate 는 SQL 커넥션(postgres·mysql)에만 실행하세요.`);
+            `  → 몽고 인덱스는 Mongoose 스키마 선언(index:true / schema.index())으로 관리합니다(mongoose autoIndex 기본값이 부팅 시 보장).\n` +
+            `  → gaon db diff/migrate 는 SQL 커넥션(postgres·mysql)에만 실행하세요(키 생략 시 순회가 문서형을 자동으로 건너뜁니다 · 결정 292).`);
     }
     const db = createDb(connCfg);
     registerConnection(dbKey, db, connCfg.adapter);

package/dist/db/status.js

@@ -2,9 +2,10 @@
 //
 // db/migrations/*.ts 각각의 적용/미적용과, 스키마↔DB 사이에 아직 반영 안 된
 // 변경(schema drift) 수를 함께 보여준다. 아무것도 실행하지 않는다.
-import { computeMigration } from '@gaonjs/data';
+import { computeMigration, summarizeOp, DEFERRED_DROP_KINDS } from '@gaonjs/data';
 import { resolveDbTarget } from './resolve.js';
 import { appliedFileMigrations } from './journal.js';
+import { describeDeferred } from './migrate.js';
 import { listMigrationFiles } from './replay.js';
 export async function runDbStatus(opts) {
     const target = await resolveDbTarget({
@@ -14,7 +15,7 @@ export async function runDbStatus(opts) {
     });
     try {
         const files = listMigrationFiles(opts.cwd);
-        const done = await appliedFileMigrations(target.db);
+        const done = await appliedFileMigrations(target.db, target.adapter);
         const migrations = files.map((f) => ({ file: `db/migrations/${f}`, applied: done.has(f) }));
         const pendingFiles = migrations.filter((m) => !m.applied).length;
         // migrate 는 스키마에 없는 테이블을 자동 DROP 하지 않으므로(결정 39 · §4.8)
@@ -23,7 +24,11 @@ export async function runDbStatus(opts) {
         const extraTables = plan.ops
             .filter((o) => o.kind === 'dropTable')
             .map((o) => o.name);
-        const schemaChanges = plan.ops.length - extraTables.length;
+        // 결정 326: deferred aux drop(제약·인덱스·기본값 제거)도 migrate 가 자동 적용하지
+        // 않는다(결정 220) — drift 로 세면 "'gaon db migrate' 로 반영하세요" 가 영원히 안
+        // 지워지는 거짓 안내가 된다. dropTable 과 같은 축의 참고 항목으로 분리한다.
+        const deferredDrops = plan.ops.filter((o) => o.kind !== 'dropTable' && DEFERRED_DROP_KINDS.has(o.kind));
+        const schemaChanges = plan.ops.length - extraTables.length - deferredDrops.length;
         const lines = [];
         if (migrations.length === 0) {
             lines.push(`  [${opts.dbKey}] 마이그레이션 파일 없음 (db/migrations/).`);
@@ -42,6 +47,10 @@ export async function runDbStatus(opts) {
         if (extraTables.length > 0) {
             lines.push(`  참고: 스키마에 없는 테이블 ${extraTables.length}개(자동 DROP 안 함): ${extraTables.join(', ')}`);
         }
+        if (deferredDrops.length > 0) {
+            lines.push(`  참고: 스키마에서 사라진 제약·인덱스·기본값 ${deferredDrops.length}개(자동 제거 안 함 — ` +
+                `'gaon db diff' 의 down SQL 로 손작성 마이그): ${deferredDrops.map(describeDeferred).join(', ')}`);
+        }
         return {
             exitCode: 0,
             text: lines.join('\n'),
@@ -52,6 +61,7 @@ export async function runDbStatus(opts) {
                 pendingFiles,
                 schemaChanges,
                 extraTables,
+                deferredDrops: deferredDrops.map(summarizeOp),
             },
         };
     }

package/dist/dev.d.ts

@@ -13,6 +13,8 @@ export interface DevLayout {
     readonly apps: readonly DevApp[];
     /** locales/ (없으면 undefined — messages 축 생략 · 결정 158 · W2). */
     readonly localesDir?: string;
+    /** 기준 로케일 = config i18n.fallbackLng (정적 분석 · 결정 352 · 못 읽으면 undefined). */
+    readonly messagesBaseLng?: string;
     /** .gaon/messages.d.ts */
     readonly messagesOut: string;
     /** 프론트 진입(index.html)이 있는 앱이 하나라도 있는가 — env 축 적용 조건(결정 198). */
@@ -26,8 +28,8 @@ export interface DevDeps {
     readonly layout: DevLayout;
     regenerateTables(schemaDir: string, out: string): Promise<unknown>;
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
-    /** locales/ → .gaon/messages.d.ts (결정 158 · W2). i18n 축을 쓰는 호출자만 준다. */
-    regenerateMessages?(localesDir: string, out: string): unknown;
+    /** locales/ → .gaon/messages.d.ts (결정 158 · W2 · 기준 로케일 = 결정 352). i18n 축을 쓰는 호출자만 준다. */
+    regenerateMessages?(localesDir: string, out: string, baseLng?: string): unknown;
     /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
     regenerateEnv?(envFile: string, out: string): unknown;
     watch(dir: string, opts: WatchOptions): WatchHandle;
@@ -58,8 +60,8 @@ export declare function startDev(deps: DevDeps): Promise<DevHandle>;
 export interface RegenDeps {
     regenerateTables(schemaDir: string, out: string): Promise<unknown>;
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
-    /** locales/ → .gaon/messages.d.ts (결정 158 · W2). i18n 축을 쓰는 호출자만 준다. */
-    regenerateMessages?(localesDir: string, out: string): unknown;
+    /** locales/ → .gaon/messages.d.ts (결정 158 · W2 · 기준 로케일 = 결정 352). i18n 축을 쓰는 호출자만 준다. */
+    regenerateMessages?(localesDir: string, out: string, baseLng?: string): unknown;
     /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
     regenerateEnv?(envFile: string, out: string): unknown;
 }

package/dist/dev.js

@@ -13,6 +13,7 @@
  */
 import { readdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { analyzeProjectI18n } from './i18n-config.js';
 /** locales/*.json 변경(메시지 카탈로그) — messages.d.ts 재생성 트리거. */
 const isMessagesChange = (f) => !f.includes('.gaon') && f.endsWith('.json');
 const isSchemaChange = (f) => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts') && !f.includes('.gaon');
@@ -39,7 +40,7 @@ export async function startDev(deps) {
     }
     // 결정 158(W2): locales/ → messages.d.ts.
     if (layout.localesDir && deps.regenerateMessages) {
-        await deps.regenerateMessages(layout.localesDir, layout.messagesOut);
+        await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng);
         deps.log({ kind: 'regen', target: 'messages' });
     }
     // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts(VITE_* 타입 브리지). `.env` 부재는
@@ -79,7 +80,7 @@ export async function startDev(deps) {
         handles.push(deps.watch(localesDir, {
             filter: isMessagesChange,
             onChange: async () => {
-                await regenerateMessages(localesDir, layout.messagesOut);
+                await regenerateMessages(localesDir, layout.messagesOut, layout.messagesBaseLng);
                 deps.log({ kind: 'regen', target: 'messages' });
             },
             onError: deps.onError,
@@ -110,7 +111,7 @@ export async function regenerateGaonOnce(layout, deps) {
     // 결정 158(W2): locales/ 가 있으면 messages.d.ts 도 재생성한다(i18n 키 타입 브리지).
     let messages = false;
     if (layout.localesDir && deps.regenerateMessages) {
-        messages = (await deps.regenerateMessages(layout.localesDir, layout.messagesOut)) === true;
+        messages = (await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng)) === true;
     }
     // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts. `.env` 부재는 throw(수리 안내).
     let env = false;
@@ -144,12 +145,16 @@ export function resolveDevLayout(cwd) {
             });
         }
     }
-    const localesDirPath = join(root, 'locales');
+    // 결정 352: 카탈로그 위치·기준 로케일은 gaon.config.ts 의 i18n 블록을 따른다
+    // (정적 분석 · 하드코딩 'locales' 는 dir 커스텀 프로젝트에서 타입 축을 무소음으로 껐다).
+    const i18nCfg = analyzeProjectI18n(root);
+    const localesDirPath = join(root, i18nCfg.dir ?? 'locales');
     return {
         schemaDir: existsSync(schemaDirPath) ? schemaDirPath : undefined,
         tablesOut: join(root, '.gaon', 'tables.d.ts'),
         apps: apps.sort((a, b) => a.name.localeCompare(b.name)),
         localesDir: existsSync(localesDirPath) ? localesDirPath : undefined,
+        messagesBaseLng: i18nCfg.fallbackLng,
         messagesOut: join(root, '.gaon', 'messages.d.ts'),
         hasFrontendApps,
         envFile: join(root, '.env'),

package/dist/doctor/fixers/index.d.ts

@@ -14,7 +14,7 @@ export declare const FIXERS: Partial<Record<DoctorRule, Fixer>>;
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
  * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
  *
- * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 27종을 **빠짐없이** 담는다 —
+ * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 28종을 **빠짐없이** 담는다 —
  * fixer 가 없는 규칙도 `hasFixer:false` + 구체적 수동 안내로 명시한다. 항목이
  * 빠지면 --fix 리포트가 그 규칙 위반에 대해 일반 문구("수동 수정 필요")만 내
  * 사용자가 왜 자동이 안 되는지 알 수 없다. 전수성은 테스트가 고정한다

package/dist/doctor/fixers/index.js

@@ -28,7 +28,7 @@ export const FIXERS = {
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
  * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
  *
- * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 27종을 **빠짐없이** 담는다 —
+ * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 28종을 **빠짐없이** 담는다 —
  * fixer 가 없는 규칙도 `hasFixer:false` + 구체적 수동 안내로 명시한다. 항목이
  * 빠지면 --fix 리포트가 그 규칙 위반에 대해 일반 문구("수동 수정 필요")만 내
  * 사용자가 왜 자동이 안 되는지 알 수 없다. 전수성은 테스트가 고정한다
@@ -165,6 +165,11 @@ export const FIXER_CAPABILITIES = [
         hasFixer: false,
         note: '수동 · .vue 의 import.meta.env(TS1470)는 env 접근자로 전환하세요 — 접근자 도입은 코드 편집이 필요합니다(결정 198).',
     },
+    {
+        rule: 'render-return',
+        hasFixer: false,
+        note: '수동 · this.render/redirect/json 호출 앞에 return 을 붙이세요 — 반환값이 곧 응답입니다(결정 340 · 의도된 204 는 응답 호출 없이 return).',
+    },
     {
         rule: 'locale-parity',
         hasFixer: false,

package/dist/doctor/locale-parity.js

@@ -11,6 +11,7 @@
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { loadLocales, flattenKeys } from '@gaonjs/i18n';
+import { analyzeProjectI18n } from '../i18n-config.js';
 // 경고 한 줄이 폭주하지 않게 나열 상한 — 넘으면 "…외 N개" 로 접는다(detail 에는 전량).
 const MAX_KEYS_SHOWN = 20;
 // i18next 복수형 접미사(결정 181 · generator.ts 와 동일 규약). 로케일마다 필요한 접미사만
@@ -26,7 +27,9 @@ function pluralBase(key) {
  * 비교 대상이 없어 건너뛴다(i18n 미사용·단일 로케일 프로젝트는 무소음).
  */
 export async function checkLocaleParity(cwd) {
-    const localesDir = join(cwd, 'locales');
+    // 결정 352: 카탈로그 위치는 config i18n.dir 을 따른다(정적 분석 · 하드코딩이던
+    // 'locales' 는 dir 커스텀 프로젝트에서 이 검사를 무소음으로 껐다).
+    const localesDir = join(cwd, analyzeProjectI18n(cwd).dir ?? 'locales');
     if (!existsSync(localesDir))
         return { rule: 'locale-parity', issues: [] };
     const resources = loadLocales(localesDir);

package/dist/doctor/pageprops-destructure.d.ts

@@ -1,5 +1,5 @@
 import type { RuleReport } from './types.js';
-/** 소스에 pageProps() 구조분해가 있는지(단위 테스트 진입점 · 주석은 제외). */
+/** 소스에 pageProps()/useShared() 구조분해가 있는지(단위 테스트 진입점 · 주석은 제외). */
 export declare function usesPagePropsDestructure(source: string): boolean;
-/** apps/ 의 .vue 를 훑어 pageProps() 구조분해를 경고로 낸다. */
+/** apps/ 의 .vue + .ts(컴포저블 등)를 훑어 pageProps()/useShared() 구조분해를 경고로 낸다. */
 export declare function checkPagePropsDestructure(cwd: string): Promise<RuleReport>;