@gaonjs/cli 0.5.0 → 0.10.0

package/dist/db/migrate.js

@@ -1,21 +1,22 @@
-// @gaonjs/cli · `gaon db migrate` — 스키마 diff 적용 + 이력 기록 (M9-D)
+// @gaonjs/cli · `gaon db migrate` — 합성형 마이그레이션 (결정 39 · v0.16 §4.8)
 //
-// 흐름:
-//   1) resolveDbTarget → computeMigration 로 up/down·ops 산출.
-//   2) --dry-run 이면 SQL 만 출력하고 종료(실행 X).
-//   3) 트랜잭션 안에서 up 을 순차 실행하고, 완료 후 _gaon_migrations 에
-//      배치 한 행을 남긴다(감사 로그 — 스냅샷 기반 diff 는 재실행 시
-//      idempotent 지만, 이력은 언제 무엇이 적용됐는지를 남긴다).
-//   4) journal 미존재 상태에서 createTable 이 포함되면 §7.5.3 방식 안내를
-//      함께 낸다(baseline · 사용자가 기존 DB 를 갖고 있다면 diff 를 먼저
-//      확인하도록).
+// 흐름(합성형):
+//   1) resolveDbTarget → 커넥션·스키마·방언 확보.
+//   2) replay 단계 — 아직 적용 안 된 db/migrations/*.ts 를 파일명 순으로
+//      실행하고 이력(kind='file')에 남긴다(손작성·백필 등 1급 실행 · §4.8).
+//   3) schema-diff 단계 — computeMigration 으로 스키마↔DB 차이를 계산해
+//      나머지를 적용하고 이력(kind='schema')에 남긴다. replay 가 만든 테이블은
+//      introspection 에 잡혀 다시 만들지 않는다(두 단계가 충돌 없이 합쳐짐).
+//   4) `gaon db migrate down` — 가장 최근 이력 한 건을 되돌린다(rollbackLast).
+//   5) --dry-run 이면 replay 예정 파일 + schema up SQL 만 출력(실행 X).
 //
-// 트랜잭션: postgres 는 트랜잭셔널 DDL 이라 안전, mysql/mariadb 는 DDL 이
-// autocommit 이라 실패 시 부분 적용이 남을 수 있다 — mysql 에서는 이력 행
-// 삽입만 트랜잭션에 감싼다(에러 안내로 사용자에게 알린다).
+// 트랜잭션: postgres 는 트랜잭셔널 DDL 이라 각 단계가 원자적. mysql/mariadb 는
+// DDL 이 autocommit 이라 순차 실행하고 이력만 남긴다(§4.5 방언 차이).
 import { sql } from 'kysely';
-import { computeMigration, MIGRATIONS_TABLE } from '@gaonjs/data';
+import { computeMigration, renderUp, renderDown } from '@gaonjs/data';
 import { resolveDbTarget } from './resolve.js';
+import { ensureJournal, journalExists, recordEntry } from './journal.js';
+import { listMigrationFiles, replayPending, rollbackLast } from './replay.js';
 function opSummary(op) {
     switch (op.kind) {
         case 'createTable':
@@ -28,44 +29,12 @@ function opSummary(op) {
             return { kind: op.kind, table: op.table, column: op.column };
     }
 }
-/** _gaon_migrations 존재 여부. information_schema 조회로 방언 무관하게 검사. */
-async function journalExists(db) {
-    const rows = await sql `
-    select count(*)::text as n
-    from information_schema.tables
-    where table_name = ${MIGRATIONS_TABLE}
-  `.execute(db);
-    const first = rows.rows[0];
-    if (!first)
-        return false;
-    return Number(first.n) > 0;
-}
-/**
- * _gaon_migrations 를 만든다(존재하면 no-op). 컬럼:
- *   id           문자열 PK — 배치 식별자 (`<epochMs>-<적용문수>`).
- *   applied_at   타임스탬프 — 서버 기준 시각.
- *   db_key       커넥션 키 (§4.5).
- *   statements   이 배치의 SQL 문 수.
- *   summary      JSON 문자열(ops 요약).
- * text/varchar/timestamp/integer 는 postgres·mysql 공통 지원 타입.
- */
-async function ensureJournal(db) {
-    // postgres·mysql 공통 CREATE TABLE IF NOT EXISTS.
-    // 기본값 표현은 각 방언이 자동으로 처리(now()/CURRENT_TIMESTAMP 모두 표준).
-    await sql.raw(`create table if not exists ${MIGRATIONS_TABLE} (` +
-        ` id varchar(64) not null primary key,` +
-        ` applied_at timestamp not null,` +
-        ` db_key varchar(64) not null,` +
-        ` statements integer not null,` +
-        ` summary text not null` +
-        `)`).execute(db);
-}
 /** 배치 식별자 — 초 단위 epoch + 적용 문수. 사람도 읽고 정렬도 된다. */
 function batchId(count) {
     return `${Date.now()}-${count}`;
 }
 /**
- * `gaon db migrate` — 진짜 apply. 실 DB 필요(§9).
+ * `gaon db migrate` — 진짜 apply(합성형: replay → schema-diff). 실 DB 필요(§9).
  */
 export async function runDbMigrate(opts) {
     const target = await resolveDbTarget({
@@ -74,90 +43,107 @@ export async function runDbMigrate(opts) {
         configPath: opts.configPath,
     });
     try {
-        const plan = await computeMigration(target.db, target.tables, target.dialect);
+        if (opts.down)
+            return await runRollback(opts, target);
+        // 1) replay — db/migrations/*.ts 를 먼저 실행.
+        const replay = await replayPending({
+            cwd: opts.cwd,
+            db: target.db,
+            dbKey: opts.dbKey,
+            adapter: target.adapter,
+            dryRun: opts.dryRun,
+        });
+        // 2) schema-diff — replay 이후 상태를 다시 읽어 나머지를 계산.
+        // 합성형(결정 39): migrate 는 스키마에 없는 테이블을 **자동 DROP 하지 않는다**
+        // — replay(파일 마이그)가 만든 테이블·외부 테이블을 보호한다. 테이블 제거는
+        // 손작성 마이그(down 포함)로 한다. dropTable 은 'gaon db diff' 가 계속 보여준다.
+        const full = await computeMigration(target.db, target.tables, target.dialect);
+        const droppedTables = full.ops
+            .filter((o) => o.kind === 'dropTable')
+            .map((o) => o.name);
+        const schemaOps = full.ops.filter((o) => o.kind !== 'dropTable');
+        const plan = {
+            ops: schemaOps,
+            up: renderUp(schemaOps, target.dialect),
+            down: renderDown(schemaOps, target.dialect),
+        };
         const ops = plan.ops.map(opSummary);
-        // 아무것도 적용할 게 없다 — 성공으로 취급(스냅샷 diff 관례).
+        const dropNote = droppedTables.length > 0
+            ? `  ℹ 스키마에 없는 테이블 ${droppedTables.length}개는 자동 DROP 하지 않았습니다: ${droppedTables.join(', ')}\n` +
+                `    → 제거하려면 손작성 마이그(down 포함)를 쓰거나, 'gaon db diff' 로 계획을 확인하세요.`
+            : '';
+        const replayLine = replay.applied.length > 0
+            ? `  [${opts.dbKey}] 마이그레이션 파일 ${replay.applied.length}개 실행: ${replay.applied.join(', ')}`
+            : replay.pending.length > 0 && opts.dryRun
+                ? `  [${opts.dbKey}] 실행 예정 마이그레이션 파일 ${replay.pending.length}개: ${replay.pending.join(', ')}`
+                : '';
+        const baseJson = {
+            command: 'migrate',
+            db: opts.dbKey,
+            replayed: replay.applied,
+            pendingMigrations: replay.pending,
+            migrationFiles: replay.all,
+            skippedDropTables: droppedTables,
+        };
+        const prefixLines = (body) => (replayLine ? replayLine + '\n' : '') + (dropNote ? dropNote + '\n' : '') + body;
+        // schema 변경이 없다 — replay 만 있었을 수 있다. 성공으로 취급.
         if (plan.up.length === 0) {
             return {
                 exitCode: 0,
-                text: `  [${opts.dbKey}] 적용할 마이그레이션이 없습니다 — 스키마와 DB 가 일치합니다.`,
-                json: {
-                    command: 'migrate',
-                    db: opts.dbKey,
-                    applied: 0,
-                    ops: [],
-                    dryRun: opts.dryRun,
-                },
+                text: prefixLines(`  [${opts.dbKey}] 적용할 스키마 변경이 없습니다 — 스키마와 DB 가 일치합니다.`),
+                json: { ...baseJson, applied: 0, ops: [], dryRun: opts.dryRun },
             };
         }
-        // --dry-run: SQL 만 출력. 이력 테이블도 만들지 않는다.
+        // --dry-run: replay 예정 + schema up SQL 만 출력.
         if (opts.dryRun) {
             return {
                 exitCode: 0,
-                text: `  [${opts.dbKey}] --dry-run · 적용하지 않고 SQL 만 출력합니다 (${plan.up.length}문)\n` +
-                    plan.up.map((s) => `    ${s}`).join('\n'),
-                json: {
-                    command: 'migrate',
-                    db: opts.dbKey,
-                    applied: 0,
-                    ops,
-                    up: plan.up,
-                    dryRun: true,
-                },
+                text: prefixLines(`  [${opts.dbKey}] --dry-run · 적용하지 않고 SQL 만 출력합니다 (${plan.up.length}문)\n` +
+                    plan.up.map((s) => `    ${s}`).join('\n')),
+                json: { ...baseJson, applied: 0, ops, up: plan.up, dryRun: true },
             };
         }
         // baseline 감지 — journal 이 없는데 createTable 이 포함 → 안내(§7.5.3).
-        // 에러가 아니라 정보성 노트로 처리(실행은 진행). 사용자가 기존 DB 를 갖고
-        // 있다면 diff 로 먼저 계획을 봐야 한다.
         const hadJournal = await journalExists(target.db);
         const hasCreate = plan.ops.some((o) => o.kind === 'createTable');
         const baselineNote = !hadJournal && hasCreate
             ? `  ℹ 최초 마이그레이션(_gaon_migrations 미존재) — 이 배치가 baseline 이 됩니다.\n` +
-                `    → 기존 DB 를 이어 쓰고 있었다면, 먼저 'gaon db diff' 로 계획을 확인하세요.\n` +
-                `    → 이미 존재하는 테이블은 스키마와 일치해야 합니다(불일치 시 alterColumn 이 함께 실행됩니다).`
+                `    → 기존 DB 를 이어 쓰고 있었다면, 먼저 'gaon db diff' 로 계획을 확인하세요.`
             : '';
-        // apply — up 을 순차 적용하고 이력 한 행을 남긴다. postgres 는 트랜잭셔널 DDL.
-        // ensureJournal 은 트랜잭션 밖에서(mysql 호환) 만들고, insert 만 트랜잭션 안.
+        // 3) schema-diff apply — up 을 순차 적용하고 이력 한 행(kind='schema')을 남긴다.
         await ensureJournal(target.db);
         const id = batchId(plan.up.length);
         const summary = JSON.stringify(ops);
-        if (target.adapter === 'postgres') {
-            // postgres: DDL + insert 를 한 트랜잭션에 넣는다(원자적).
-            await target.db.transaction().execute(async (trx) => {
-                for (const stmt of plan.up) {
-                    if (stmt.trim().startsWith('--'))
-                        continue;
-                    await sql.raw(stmt).execute(trx);
-                }
-                await sql `
-          insert into ${sql.ref(MIGRATIONS_TABLE)}
-            (id, applied_at, db_key, statements, summary)
-          values (${id}, ${new Date()}, ${opts.dbKey}, ${plan.up.length}, ${summary})
-        `.execute(trx);
-            });
-        }
-        else {
-            // mysql/mariadb: DDL 은 autocommit 이라 트랜잭션에 감싸도 롤백되지 않는다.
-            // 정직하게 순차 실행하고, 이력만 별도로 남긴다(§4.5 방언 차이).
+        const downSql = JSON.stringify(plan.down);
+        const applySchema = async (db) => {
             for (const stmt of plan.up) {
                 if (stmt.trim().startsWith('--'))
                     continue;
-                await sql.raw(stmt).execute(target.db);
+                await sql.raw(stmt).execute(db);
             }
-            await sql `
-        insert into ${sql.ref(MIGRATIONS_TABLE)}
-          (id, applied_at, db_key, statements, summary)
-        values (${id}, ${new Date()}, ${opts.dbKey}, ${plan.up.length}, ${summary})
-      `.execute(target.db);
+            await recordEntry(db, {
+                id,
+                kind: 'schema',
+                dbKey: opts.dbKey,
+                statements: plan.up.length,
+                summary,
+                downSql,
+            });
+        };
+        if (target.adapter === 'postgres') {
+            await target.db.transaction().execute(applySchema);
         }
-        const text = (baselineNote ? baselineNote + '\n' : '') +
-            `  [${opts.dbKey}] ${plan.up.length}개 문 적용 완료 (batch ${id}).`;
+        else {
+            // mysql/mariadb: DDL autocommit — 순차 실행 후 이력만 남긴다(§4.5).
+            await applySchema(target.db);
+        }
+        const text = prefixLines((baselineNote ? baselineNote + '\n' : '') +
+            `  [${opts.dbKey}] ${plan.up.length}개 문 적용 완료 (batch ${id}).`);
         return {
             exitCode: 0,
             text,
             json: {
-                command: 'migrate',
-                db: opts.dbKey,
+                ...baseJson,
                 applied: plan.up.length,
                 ops,
                 up: plan.up,
@@ -171,3 +157,35 @@ export async function runDbMigrate(opts) {
         await target.close();
     }
 }
+/** `gaon db migrate down` — 가장 최근 이력 한 건을 되돌린다. */
+async function runRollback(opts, target) {
+    const r = await rollbackLast({
+        cwd: opts.cwd,
+        db: target.db,
+        adapter: target.adapter,
+        dryRun: opts.dryRun,
+    });
+    const baseJson = { command: 'migrate', db: opts.dbKey, down: true, dryRun: opts.dryRun };
+    if (r.rolledBack === null) {
+        return {
+            exitCode: 0,
+            text: `  [${opts.dbKey}] 되돌릴 마이그레이션 이력이 없습니다.`,
+            json: { ...baseJson, rolledBack: null, kind: null },
+        };
+    }
+    if (opts.dryRun) {
+        return {
+            exitCode: 0,
+            text: `  [${opts.dbKey}] --dry-run · 되돌릴 대상: ${r.rolledBack} (${r.kind}) — 실행하지 않았습니다.`,
+            json: { ...baseJson, rolledBack: r.rolledBack, kind: r.kind },
+        };
+    }
+    const what = r.kind === 'file' ? `마이그레이션 파일 ${r.rolledBack}` : `스키마 배치 ${r.rolledBack}`;
+    return {
+        exitCode: 0,
+        text: `  [${opts.dbKey}] 롤백 완료 — ${what} 을(를) 되돌렸습니다.`,
+        json: { ...baseJson, rolledBack: r.rolledBack, kind: r.kind },
+    };
+}
+/** `gaon db status` 가 재사용하는 마이그레이션 파일 목록(파일명 순). */
+export { listMigrationFiles };

package/dist/db/replay.d.ts

@@ -0,0 +1,49 @@
+import { type Kysely } from 'kysely';
+import type { AdapterName } from '@gaonjs/data';
+import { type MigrationKind } from './journal.js';
+export interface MigrationModule {
+    up(db: Kysely<any>): Promise<void>;
+    down?(db: Kysely<any>): Promise<void>;
+}
+/** db/migrations/ 아래 리플레이 대상 파일(파일명 오름차순). */
+export declare function listMigrationFiles(cwd: string): string[];
+/** db/migrations/<file> 을 동적 import 한다(tsResolve 훅 전제 — resolveDbTarget 이 등록). */
+export declare function loadMigration(cwd: string, file: string): Promise<MigrationModule>;
+export interface ReplayOptions {
+    readonly cwd: string;
+    readonly db: Kysely<any>;
+    readonly dbKey: string;
+    readonly adapter: AdapterName;
+    readonly dryRun: boolean;
+}
+export interface ReplayResult {
+    /** 이번에 실행된 파일명(파일명 순). */
+    readonly applied: string[];
+    /** (dry-run 또는 실행 전) 실행 예정 파일명. */
+    readonly pending: string[];
+    /** 전체 마이그레이션 파일 목록. */
+    readonly all: string[];
+}
+/**
+ * 아직 적용되지 않은 db/migrations/*.ts 를 파일명 순으로 실행한다.
+ * postgres 는 파일 up() + 이력 기록을 한 트랜잭션에 넣어 원자적이다.
+ * mysql/mariadb 는 DDL 이 autocommit 이라 파일 단위로 정직하게 순차 실행한다.
+ */
+export declare function replayPending(opts: ReplayOptions): Promise<ReplayResult>;
+export interface RollbackResult {
+    /** 되돌린 이력 id(파일명 또는 schema 배치 id). 되돌릴 게 없으면 null. */
+    readonly rolledBack: string | null;
+    readonly kind: MigrationKind | null;
+}
+/**
+ * 가장 최근 적용된 이력 한 건을 되돌린다(`gaon db migrate down`).
+ *  · kind='file'   → 파일 down() 호출(없으면 §7.5.3 안내 에러).
+ *  · kind='schema' → 저장된 down SQL 실행.
+ * 되돌린 뒤 이력 행을 지운다. --dry-run 은 대상만 보고 실행하지 않는다.
+ */
+export declare function rollbackLast(opts: {
+    readonly cwd: string;
+    readonly db: Kysely<any>;
+    readonly adapter: AdapterName;
+    readonly dryRun: boolean;
+}): Promise<RollbackResult>;

package/dist/db/replay.js

@@ -0,0 +1,148 @@
+// @gaonjs/cli · db/migrations 파일 리플레이 엔진 (결정 39 · v0.16 §4.8)
+//
+// 손작성(또는 생성된) db/migrations/*.ts 를 파일명 순으로 실행한다. 각 파일은
+//   export async function up(db: Kysely<any>): Promise<void>
+//   export async function down(db: Kysely<any>): Promise<void>   // 롤백용(선택)
+// 을 내보낸다. `gaon db migrate` 는 이 리플레이를 **먼저** 돌리고, 그 뒤
+// schema-diff 로 나머지를 반영한다(합성형 · 결정 39). schema-diff 는 실 DB
+// introspection 기반이라 리플레이가 만든 테이블을 다시 만들지 않는다 — 두
+// 단계가 충돌 없이 합쳐진다.
+//
+// 이력은 _gaon_migrations 에 파일별 한 행(kind='file', id=파일명)으로 남겨
+// 재실행 시 건너뛴다(중복 방지). 파일명이 곧 버전 키다 — `0001_*` 시퀀스든
+// `20260724_*` 타임스탬프든 사전순 정렬이 안정적이다(§4.8 파일명 규약).
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { sql } from 'kysely';
+import { appliedFileMigrations, deleteEntry, ensureJournal, latestEntry, recordEntry, } from './journal.js';
+/** db/migrations/ 아래 리플레이 대상 파일(파일명 오름차순). */
+export function listMigrationFiles(cwd) {
+    const dir = join(cwd, 'db', 'migrations');
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return []; // db/migrations/ 없음 = 파일 없음
+    }
+    const out = [];
+    for (const name of entries) {
+        // 리플레이는 up()/down() 함수를 부르므로 실행 가능한 모듈만 대상.
+        if (!/\.(ts|js|mjs|cjs)$/.test(name))
+            continue;
+        if (name.endsWith('.d.ts'))
+            continue;
+        try {
+            if (!statSync(join(dir, name)).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        out.push(name);
+    }
+    return out.sort();
+}
+/** db/migrations/<file> 을 동적 import 한다(tsResolve 훅 전제 — resolveDbTarget 이 등록). */
+export async function loadMigration(cwd, file) {
+    const abs = join(cwd, 'db', 'migrations', file);
+    const mod = (await import(pathToFileURL(abs).href));
+    if (typeof mod.up !== 'function') {
+        throw new Error(`[gaon db] 마이그레이션 파일에 up() export 가 없습니다: db/migrations/${file}\n` +
+            `  → 다음 형태로 두세요:\n` +
+            `      import type { Kysely } from 'kysely'\n` +
+            `      export async function up(db: Kysely<any>): Promise<void> { /* ... */ }\n` +
+            `      export async function down(db: Kysely<any>): Promise<void> { /* ... */ }`);
+    }
+    return mod;
+}
+/**
+ * 아직 적용되지 않은 db/migrations/*.ts 를 파일명 순으로 실행한다.
+ * postgres 는 파일 up() + 이력 기록을 한 트랜잭션에 넣어 원자적이다.
+ * mysql/mariadb 는 DDL 이 autocommit 이라 파일 단위로 정직하게 순차 실행한다.
+ */
+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 pending = all.filter((f) => !done.has(f));
+    if (opts.dryRun || pending.length === 0) {
+        return { applied: [], pending, all };
+    }
+    await ensureJournal(opts.db);
+    const applied = [];
+    for (const file of pending) {
+        const mig = await loadMigration(opts.cwd, file);
+        const record = (db) => recordEntry(db, {
+            id: file,
+            kind: 'file',
+            dbKey: opts.dbKey,
+            statements: 0, // 임의 up() 이라 문 수를 세지 않는다.
+            summary: JSON.stringify({ file, kind: 'file' }),
+            downSql: null,
+        });
+        if (opts.adapter === 'postgres') {
+            await opts.db.transaction().execute(async (trx) => {
+                await mig.up(trx);
+                await record(trx);
+            });
+        }
+        else {
+            await mig.up(opts.db);
+            await record(opts.db);
+        }
+        applied.push(file);
+    }
+    return { applied, pending: [], all };
+}
+/**
+ * 가장 최근 적용된 이력 한 건을 되돌린다(`gaon db migrate down`).
+ *  · kind='file'   → 파일 down() 호출(없으면 §7.5.3 안내 에러).
+ *  · kind='schema' → 저장된 down SQL 실행.
+ * 되돌린 뒤 이력 행을 지운다. --dry-run 은 대상만 보고 실행하지 않는다.
+ */
+export async function rollbackLast(opts) {
+    const entry = await latestEntry(opts.db);
+    if (!entry)
+        return { rolledBack: null, kind: null };
+    if (opts.dryRun)
+        return { rolledBack: entry.id, kind: entry.kind };
+    if (entry.kind === 'file') {
+        const mig = await loadMigration(opts.cwd, entry.id);
+        if (typeof mig.down !== 'function') {
+            throw new Error(`[gaon db] 롤백할 down() 이 없습니다: db/migrations/${entry.id}\n` +
+                `  → 이 파일에 export async function down(db: Kysely<any>) {…} 을 추가하거나,\n` +
+                `    수동으로 되돌린 뒤 _gaon_migrations 에서 이 행을 지우세요.`);
+        }
+        const down = mig.down;
+        if (opts.adapter === 'postgres') {
+            await opts.db.transaction().execute(async (trx) => {
+                await down(trx);
+                await deleteEntry(trx, entry.id);
+            });
+        }
+        else {
+            await down(opts.db);
+            await deleteEntry(opts.db, entry.id);
+        }
+    }
+    else {
+        const stmts = entry.down_sql ? JSON.parse(entry.down_sql) : [];
+        const run = async (db) => {
+            for (const s of stmts) {
+                if (!s.trim().startsWith('--'))
+                    await sql.raw(s).execute(db);
+            }
+            await deleteEntry(db, entry.id);
+        };
+        if (opts.adapter === 'postgres') {
+            await opts.db.transaction().execute(run);
+        }
+        else {
+            await run(opts.db);
+        }
+    }
+    return { rolledBack: entry.id, kind: entry.kind };
+}

package/dist/db/status.d.ts

@@ -0,0 +1,12 @@
+export interface DbStatusOptions {
+    readonly cwd: string;
+    readonly dbKey: string;
+    readonly json: boolean;
+    readonly configPath?: string;
+}
+export interface DbStatusResult {
+    readonly exitCode: number;
+    readonly text: string;
+    readonly json: unknown;
+}
+export declare function runDbStatus(opts: DbStatusOptions): Promise<DbStatusResult>;

package/dist/db/status.js

@@ -0,0 +1,61 @@
+// @gaonjs/cli · `gaon db status` — 마이그레이션 적용 현황 (결정 39 · v0.16 §4.8)
+//
+// db/migrations/*.ts 각각의 적용/미적용과, 스키마↔DB 사이에 아직 반영 안 된
+// 변경(schema drift) 수를 함께 보여준다. 아무것도 실행하지 않는다.
+import { computeMigration } from '@gaonjs/data';
+import { resolveDbTarget } from './resolve.js';
+import { appliedFileMigrations } from './journal.js';
+import { listMigrationFiles } from './replay.js';
+export async function runDbStatus(opts) {
+    const target = await resolveDbTarget({
+        cwd: opts.cwd,
+        dbKey: opts.dbKey,
+        configPath: opts.configPath,
+    });
+    try {
+        const files = listMigrationFiles(opts.cwd);
+        const done = await appliedFileMigrations(target.db);
+        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)
+        // dropTable 은 drift 로 세지 않는다 — 별도로 참고 정보(extraTables)로만 보고.
+        const plan = await computeMigration(target.db, target.tables, target.dialect);
+        const extraTables = plan.ops
+            .filter((o) => o.kind === 'dropTable')
+            .map((o) => o.name);
+        const schemaChanges = plan.ops.length - extraTables.length;
+        const lines = [];
+        if (migrations.length === 0) {
+            lines.push(`  [${opts.dbKey}] 마이그레이션 파일 없음 (db/migrations/).`);
+        }
+        else {
+            lines.push(`  [${opts.dbKey}] 마이그레이션 파일 ${migrations.length}개`);
+            for (const m of migrations) {
+                lines.push(`    ${m.applied ? '✓ 적용' : '· 대기'}  ${m.file}`);
+            }
+            if (pendingFiles > 0)
+                lines.push(`  → 대기 ${pendingFiles}개 — 'gaon db migrate' 로 적용하세요.`);
+        }
+        lines.push(schemaChanges === 0
+            ? `  스키마 drift 없음 — 스키마와 DB 가 일치합니다.`
+            : `  스키마 drift ${schemaChanges}개 — 'gaon db migrate' 로 반영하세요('gaon db diff' 로 미리보기).`);
+        if (extraTables.length > 0) {
+            lines.push(`  참고: 스키마에 없는 테이블 ${extraTables.length}개(자동 DROP 안 함): ${extraTables.join(', ')}`);
+        }
+        return {
+            exitCode: 0,
+            text: lines.join('\n'),
+            json: {
+                command: 'status',
+                db: opts.dbKey,
+                migrations,
+                pendingFiles,
+                schemaChanges,
+                extraTables,
+            },
+        };
+    }
+    finally {
+        await target.close();
+    }
+}

package/dist/dev/index.d.ts

@@ -12,3 +12,5 @@ export { startTscWatchers, killChild } from './tsc.js';
 export type { TscWatcherOptions, TscWatcherHandle } from './tsc.js';
 export { startRestartWatcher, isRestartChange, resolveWatchRoots } from './watcher.js';
 export type { RestartWatcherOptions, RestartWatcherHandle } from './watcher.js';
+export { createGaonViteServer } from './vite.js';
+export type { GaonViteServer, CreateGaonViteServerOptions } from './vite.js';

package/dist/dev/index.js

@@ -8,3 +8,5 @@ export { createDevConsole } from './console.js';
 export { findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, } from './docker.js';
 export { startTscWatchers, killChild } from './tsc.js';
 export { startRestartWatcher, isRestartChange, resolveWatchRoots } from './watcher.js';
+// Vite dev server 프로그램적 기동 (M3-runtime) — dev.ts 배선은 M1 이 통합.
+export { createGaonViteServer } from './vite.js';

package/dist/dev/vite.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @gaonjs/cli · dev/vite — Vite dev server 프로그램적 기동 (M3-runtime)
+ *
+ * 정본 정합:
+ *   · §6.4 Vue 어댑터 인터페이스 — `vite: () => [vuePlugin()]` 은 서버 배선
+ *     시 프론트엔드 어댑터가 제공한다. 이 파일은 그 배선을 CLI 측에서
+ *     쉽게 부를 수 있는 최소 래퍼일 뿐이다.
+ *   · The One Way (§CLAUDE.md 6) — Vite 를 middlewareMode 로 띄운다. Fastify
+ *     한 포트로 API 와 프론트가 함께 서빙된다 — 두 포트·프록시 규칙 X.
+ *
+ * 이 파일은 `dev.ts` 에 배선되지 않는다(사용자 지침) — M1 세션이 통합
+ * 커밋에서 배선한다. 여기서는 함수만 노출한다.
+ *
+ * 참고: vite 는 이 파일을 실행하는 환경에 이미 설치돼 있어야 한다
+ * (packages/cli/package.json 에 dep 등록). vite 가 없으면 명확한 에러를
+ * 던져 사용자에게 설치 안내를 준다(§7.5.3 에러=수리 안내서).
+ */
+/** Vite dev server 핸들 — Fastify 에서 middlewares 로 소비하고, close() 로 정리. */
+export interface GaonViteServer {
+    /**
+     * Vite 가 만든 connect 스타일 미들웨어 체인. Fastify 에서
+     * `app.register(fastifyMiddie).then(() => app.use(server.middlewares))` 로
+     * 태우거나, 원시 `app.server.on('request', server.middlewares)` 로 붙인다.
+     */
+    readonly middlewares: (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+    /**
+     * data-page 를 담은 서버 HTML 을 Vite 가 변환한다 — HMR 클라이언트 스크립트
+     * 주입, `<script type="module" src="/apps/<앱>/main.ts">` 처리 등.
+     * Fastify inertia 응답에서 최초 문서 로드 시 이 함수를 통과시킨다.
+     */
+    transformIndexHtml(url: string, html: string): Promise<string>;
+    /** dev-only URL 로 모듈 로딩(SSR 렌더링 · 스크립트 확장 · 진단용). */
+    ssrLoadModule<T = unknown>(id: string): Promise<T>;
+    /** graceful shutdown — Fastify close 훅에서 부른다. */
+    close(): Promise<void>;
+    /** 진단·테스트용 — Vite 인스턴스가 봤을 최종 config 의 root. */
+    readonly root: string;
+}
+export interface CreateGaonViteServerOptions {
+    /** 프로젝트 루트(package.json 이 있는 곳). vite.config.ts 도 이 곳에서 찾는다. */
+    readonly cwd: string;
+    /**
+     * 프론트엔드 앱 루트 — 이 폴더의 `index.html` 이 Vite 의 진입 HTML이 된다.
+     * The One Way 관례: apps/web(기본 앱). 다른 앱은 사용자 설정으로 override.
+     */
+    readonly appRoot?: string;
+    /**
+     * Vite 를 켤지 여부. false 면 이 함수는 아무 것도 하지 않고 undefined 를
+     * 반환한다 — dev.ts 가 CLI 옵션에서 결정한다.
+     */
+    readonly enabled?: boolean;
+    /**
+     * 서버 로그를 통합 콘솔로 흘리는 훅. dev/console.ts 의 log('vite', ...)
+     * 를 여기에 연결한다.
+     */
+    readonly onLog?: (line: string, level: 'info' | 'warn' | 'error') => void;
+}
+/**
+ * Vite dev server 를 middleware 모드로 띄운다. Fastify 에 붙여 하나의
+ * 포트로 API + 프론트를 함께 서빙한다(The One Way).
+ *
+ * 파일이 존재하지 않는 경우(초기 프로젝트에 apps/web/index.html 이 없는
+ * 순간)에는 명확한 에러를 던진다 — dev.ts 가 이 예외를 잡아 사용자에게
+ * "→ apps/<앱>/index.html 을 만들거나 gaon new 로 새 프로젝트를 만드세요"
+ * 라고 알린다.
+ */
+export declare function createGaonViteServer(opts: CreateGaonViteServerOptions): Promise<GaonViteServer | undefined>;