@gaonjs/cli 0.2.0 → 0.4.0

package/dist/db/diff.js

@@ -0,0 +1,57 @@
+// @gaonjs/cli · `gaon db diff` — 스키마(desired) ↔ DB(current) 차이 계산 (M9-D)
+//
+// 순수 diff — 아무것도 실행하지 않는다(SQL 만 출력). computeMigration 이
+// 방언별 up/down 을 이미 만든다(@gaonjs/data). 이 함수는 배선·표현 담당.
+import { computeMigration } from '@gaonjs/data';
+import { resolveDbTarget } from './resolve.js';
+function opSummary(op) {
+    switch (op.kind) {
+        case 'createTable':
+            return { kind: op.kind, table: op.table.name };
+        case 'dropTable':
+            return { kind: op.kind, table: op.name };
+        case 'addColumn':
+        case 'dropColumn':
+        case 'alterColumn':
+            return { kind: op.kind, table: op.table, column: op.column };
+    }
+}
+/**
+ * `gaon db diff` — 커넥션 대비 스키마 diff 를 계산해 텍스트·JSON 을 낳는다.
+ * 아무것도 적용하지 않는다. exitCode 는 항상 0(변경 없음도 성공 · CI 에서
+ * 변경 존재 여부만 보고 싶으면 --json 의 changes 를 읽어라).
+ */
+export async function runDbDiff(opts) {
+    const target = await resolveDbTarget({
+        cwd: opts.cwd,
+        dbKey: opts.dbKey,
+        configPath: opts.configPath,
+    });
+    try {
+        const plan = await computeMigration(target.db, target.tables, target.dialect);
+        const ops = plan.ops.map(opSummary);
+        const json = {
+            command: 'diff',
+            db: opts.dbKey,
+            changes: ops.length,
+            ops,
+            up: plan.up,
+            down: plan.down,
+        };
+        const text = ops.length === 0
+            ? `  [${opts.dbKey}] 변경 없음 — 스키마와 DB 가 일치합니다.`
+            : `  [${opts.dbKey}] ${ops.length}개 변경\n` +
+                `  -- up --\n${indent(plan.up.join('\n'))}\n` +
+                `  -- down --\n${indent(plan.down.join('\n'))}`;
+        return { exitCode: 0, text, json };
+    }
+    finally {
+        await target.close();
+    }
+}
+function indent(text) {
+    return text
+        .split('\n')
+        .map((l) => (l ? `    ${l}` : l))
+        .join('\n');
+}

package/dist/db/index.d.ts

@@ -0,0 +1,4 @@
+export { runDbDiff, type DbDiffOptions, type DbDiffResult, } from './diff.js';
+export { runDbMigrate, type DbMigrateOptions, type DbMigrateResult, } from './migrate.js';
+export { runDbReset, type DbResetOptions, type DbResetResult, } from './reset.js';
+export { resolveDbTarget, type ResolveDbOptions, type ResolvedDbTarget, } from './resolve.js';

package/dist/db/index.js

@@ -0,0 +1,8 @@
+// @gaonjs/cli · gaon db 서브커맨드 공용 모듈 (M9-D)
+//
+// dispatcher 는 commands/db.ts (runDbCommand) 가 담당하고, 여기서는 개별
+// 서브커맨드 로직·타입만 노출한다. seed 는 기존 db.ts (M8) 를 그대로 위임.
+export { runDbDiff, } from './diff.js';
+export { runDbMigrate, } from './migrate.js';
+export { runDbReset, } from './reset.js';
+export { resolveDbTarget, } from './resolve.js';

package/dist/db/migrate.d.ts

@@ -0,0 +1,16 @@
+export interface DbMigrateOptions {
+    readonly cwd: string;
+    readonly dbKey: string;
+    readonly json: boolean;
+    readonly dryRun: boolean;
+    readonly configPath?: string;
+}
+export interface DbMigrateResult {
+    readonly exitCode: number;
+    readonly text: string;
+    readonly json: unknown;
+}
+/**
+ * `gaon db migrate` — 진짜 apply. 실 DB 필요(§9).
+ */
+export declare function runDbMigrate(opts: DbMigrateOptions): Promise<DbMigrateResult>;

package/dist/db/migrate.js

@@ -0,0 +1,173 @@
+// @gaonjs/cli · `gaon db migrate` — 스키마 diff 적용 + 이력 기록 (M9-D)
+//
+// 흐름:
+//   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 를 먼저
+//      확인하도록).
+//
+// 트랜잭션: postgres 는 트랜잭셔널 DDL 이라 안전, mysql/mariadb 는 DDL 이
+// autocommit 이라 실패 시 부분 적용이 남을 수 있다 — mysql 에서는 이력 행
+// 삽입만 트랜잭션에 감싼다(에러 안내로 사용자에게 알린다).
+import { sql } from 'kysely';
+import { computeMigration, MIGRATIONS_TABLE } from '@gaonjs/data';
+import { resolveDbTarget } from './resolve.js';
+function opSummary(op) {
+    switch (op.kind) {
+        case 'createTable':
+            return { kind: op.kind, table: op.table.name };
+        case 'dropTable':
+            return { kind: op.kind, table: op.name };
+        case 'addColumn':
+        case 'dropColumn':
+        case 'alterColumn':
+            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).
+ */
+export async function runDbMigrate(opts) {
+    const target = await resolveDbTarget({
+        cwd: opts.cwd,
+        dbKey: opts.dbKey,
+        configPath: opts.configPath,
+    });
+    try {
+        const plan = await computeMigration(target.db, target.tables, target.dialect);
+        const ops = plan.ops.map(opSummary);
+        // 아무것도 적용할 게 없다 — 성공으로 취급(스냅샷 diff 관례).
+        if (plan.up.length === 0) {
+            return {
+                exitCode: 0,
+                text: `  [${opts.dbKey}] 적용할 마이그레이션이 없습니다 — 스키마와 DB 가 일치합니다.`,
+                json: {
+                    command: 'migrate',
+                    db: opts.dbKey,
+                    applied: 0,
+                    ops: [],
+                    dryRun: opts.dryRun,
+                },
+            };
+        }
+        // --dry-run: 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,
+                },
+            };
+        }
+        // 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 이 함께 실행됩니다).`
+            : '';
+        // apply — up 을 순차 적용하고 이력 한 행을 남긴다. postgres 는 트랜잭셔널 DDL.
+        // ensureJournal 은 트랜잭션 밖에서(mysql 호환) 만들고, insert 만 트랜잭션 안.
+        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 방언 차이).
+            for (const stmt of plan.up) {
+                if (stmt.trim().startsWith('--'))
+                    continue;
+                await sql.raw(stmt).execute(target.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);
+        }
+        const text = (baselineNote ? baselineNote + '\n' : '') +
+            `  [${opts.dbKey}] ${plan.up.length}개 문 적용 완료 (batch ${id}).`;
+        return {
+            exitCode: 0,
+            text,
+            json: {
+                command: 'migrate',
+                db: opts.dbKey,
+                applied: plan.up.length,
+                ops,
+                up: plan.up,
+                batchId: id,
+                baseline: !hadJournal && hasCreate,
+                dryRun: false,
+            },
+        };
+    }
+    finally {
+        await target.close();
+    }
+}

package/dist/db/reset.d.ts

@@ -0,0 +1,18 @@
+export interface DbResetOptions {
+    readonly cwd: string;
+    readonly dbKey: string;
+    readonly json: boolean;
+    readonly yes: boolean;
+    readonly dryRun: boolean;
+    readonly configPath?: string;
+}
+export interface DbResetResult {
+    readonly exitCode: number;
+    readonly text: string;
+    readonly json: unknown;
+}
+/**
+ * `gaon db reset` — 위험 명령. NODE_ENV=production 은 무조건 거부.
+ * --yes 로 실 파괴 확증. --dry-run 은 무엇을 지울지·만들지만 출력.
+ */
+export declare function runDbReset(opts: DbResetOptions): Promise<DbResetResult>;

package/dist/db/reset.js

@@ -0,0 +1,150 @@
+// @gaonjs/cli · `gaon db reset` — 스키마 초기화 후 재마이그+시드 (M9-D)
+//
+// 위험 명령이라 fail-closed 로 잠근다(CLAUDE.md §8 보안 기본 켬):
+//   1) NODE_ENV=production 이면 무조건 거부(옵션 무관).
+//   2) --yes 없이는 실행하지 않는다(사용자 확증).
+// 두 게이트 모두 통과 시 introspect → DROP ALL → 재마이그 → seed 순.
+//
+// seed 는 M8 존재 로직(runDbSeedCommand)을 그대로 위임한다 — domain/seed.ts
+// 가 없으면 건너뛴다(파일 없음은 정상 케이스).
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { sql } from 'kysely';
+import { snapshotFromDb, MIGRATIONS_TABLE } from '@gaonjs/data';
+import { resolveDbTarget } from './resolve.js';
+import { runDbMigrate } from './migrate.js';
+import { runDbSeedCommand } from '../db.js';
+/**
+ * `gaon db reset` — 위험 명령. NODE_ENV=production 은 무조건 거부.
+ * --yes 로 실 파괴 확증. --dry-run 은 무엇을 지울지·만들지만 출력.
+ */
+export async function runDbReset(opts) {
+    // 1) production fail-closed — 옵션·플래그 무관하게 거부.
+    if (process.env.NODE_ENV === 'production') {
+        const msg = `  ✗ [gaon db reset] NODE_ENV=production 에서 실행할 수 없습니다.\n` +
+            `  → 실 운영 데이터 파괴 위험 · 개발/테스트 환경에서만 사용하세요.\n` +
+            `  → 정말 필요하면 별도 절차(백업 + 수동 SQL)로 진행하고, 이 명령은\n` +
+            `    NODE_ENV 를 비운(또는 development/test) 셸에서만 씁니다.`;
+        return {
+            exitCode: 1,
+            text: msg,
+            json: {
+                command: 'reset',
+                db: opts.dbKey,
+                ok: false,
+                reason: 'production-fail-closed',
+            },
+        };
+    }
+    // 2) --yes 게이트 — 사용자 확증. 프롬프트는 CLI 진입점에서 다루고,
+    //    이 함수는 순수 로직으로만 두어 --json 자동화와 정합.
+    if (!opts.yes) {
+        const msg = `  ✗ [gaon db reset] --yes 없이 실행할 수 없습니다 (실 데이터 파괴 확증 필요).\n` +
+            `  → 확인 후 다음처럼 실행하세요:\n` +
+            `      gaon db reset --yes --db ${opts.dbKey}\n` +
+            `  → 무엇을 지울지·만들지만 보려면: gaon db reset --dry-run --db ${opts.dbKey}`;
+        // --dry-run 만 있고 --yes 없는 경우, dry-run 은 진행한다(파괴하지 않음).
+        if (!opts.dryRun) {
+            return {
+                exitCode: 1,
+                text: msg,
+                json: {
+                    command: 'reset',
+                    db: opts.dbKey,
+                    ok: false,
+                    reason: 'yes-required',
+                },
+            };
+        }
+    }
+    const target = await resolveDbTarget({
+        cwd: opts.cwd,
+        dbKey: opts.dbKey,
+        configPath: opts.configPath,
+    });
+    // seed 는 자체적으로 env GAON_DATABASE_URL 을 읽는다(M8 관례). config 에서
+    // 얻은 URL 이 있으면 그대로 넘겨 env 미설정 프로젝트도 reset → seed 가 돈다.
+    const resolvedUrl = target.url;
+    const droppedTables = [];
+    let dryRunResult;
+    try {
+        // 현재 DB 스냅샷 — 지울 테이블 목록. dialect.introspect 는 이미
+        // _gaon_migrations 를 제외하지만, reset 은 이력도 지워야 하므로 별도 처리.
+        const snapshot = await snapshotFromDb(target.db, target.dialect);
+        const userTables = Object.keys(snapshot).sort();
+        // dry-run: 무엇을 지울지·만들지를 계산해 출력. 실제 파괴는 안 함.
+        if (opts.dryRun) {
+            const dropSqls = userTables.map((t) => target.dialect.dropTable(t));
+            dryRunResult = {
+                exitCode: 0,
+                text: `  [${opts.dbKey}] --dry-run · 리셋 후 상태를 미리 봅니다.\n` +
+                    `  -- drop (${userTables.length}) --\n` +
+                    dropSqls.map((s) => `    ${s}`).join('\n') +
+                    (userTables.length ? '\n' : '') +
+                    `    drop table if exists ${MIGRATIONS_TABLE}\n` +
+                    `  → 이후 'gaon db migrate' 로 스키마 ${target.tables.length}개 테이블이 재생성됩니다.`,
+                json: {
+                    command: 'reset',
+                    db: opts.dbKey,
+                    dryRun: true,
+                    wouldDrop: [...userTables, MIGRATIONS_TABLE],
+                    wouldMigrateTables: target.tables.map((t) => t.name),
+                },
+            };
+        }
+        else {
+            // DROP ALL — 이력 테이블도 함께. 순서: 외래키 참조 대상이 나중에 지워지도록
+            // dialect.dropTable 이 CASCADE 를 붙인다(postgres). mysql 은 SET FOREIGN_KEY_CHECKS
+            // 우회가 필요하지만, 스키마 대상 테이블만 다루므로 대체로 안전.
+            for (const t of userTables) {
+                await sql.raw(target.dialect.dropTable(t)).execute(target.db);
+                droppedTables.push(t);
+            }
+            // 이력 테이블 삭제 — 존재하지 않아도 에러 없게.
+            await sql.raw(`drop table if exists ${MIGRATIONS_TABLE}`).execute(target.db);
+        }
+    }
+    finally {
+        // dryRun·성공·실패 모든 경로에서 커넥션 정리.
+        await target.close();
+    }
+    if (dryRunResult)
+        return dryRunResult;
+    // 재마이그 — runDbMigrate 로 위임(이력 기록도 그대로 남는다).
+    const migrated = await runDbMigrate({
+        cwd: opts.cwd,
+        dbKey: opts.dbKey,
+        json: false, // 내부 호출 · 결과는 우리가 합쳐서 낸다
+        dryRun: false,
+        configPath: opts.configPath,
+    });
+    // seed — domain/seed.ts 가 있으면 실행. 없으면 조용히 건너뛴다.
+    const seedPath = join(opts.cwd, 'domain', 'seed.ts');
+    let seeded = false;
+    let seedText = '';
+    if (existsSync(seedPath)) {
+        const seedRes = await runDbSeedCommand({
+            root: opts.cwd,
+            json: false,
+            databaseUrl: resolvedUrl,
+        });
+        seeded = seedRes.exitCode === 0;
+        seedText = seedRes.text;
+    }
+    const migrateJson = migrated.json;
+    const text = `  [${opts.dbKey}] reset · ${droppedTables.length}개 테이블 삭제 + _gaon_migrations 초기화 → ` +
+        `${migrateJson.applied ?? 0}개 문 재적용` +
+        (seeded ? `\n${seedText}` : seedText ? `\n${seedText}` : '');
+    return {
+        exitCode: 0,
+        text,
+        json: {
+            command: 'reset',
+            db: opts.dbKey,
+            ok: true,
+            dropped: droppedTables,
+            applied: migrateJson.applied ?? 0,
+            seeded,
+        },
+    };
+}

package/dist/db/resolve.d.ts

@@ -0,0 +1,32 @@
+import { type TableDef } from '@gaonjs/data';
+import type { Kysely } from 'kysely';
+import { type Dialect, type AdapterName } from '@gaonjs/data';
+export interface ResolveDbOptions {
+    readonly cwd: string;
+    readonly dbKey: string;
+    /** --config <path> 로 사용자가 지정한 config 경로. 없으면 cwd 관례. */
+    readonly configPath?: string;
+}
+export interface ResolvedDbTarget {
+    readonly dbKey: string;
+    readonly adapter: AdapterName;
+    readonly db: Kysely<any>;
+    readonly dialect: Dialect;
+    /** 이 커넥션에 바인딩된 스키마 테이블 정의 목록. */
+    readonly tables: TableDef[];
+    /** 실제 로드된 config 경로 (사람 출력용). 없으면 undefined. */
+    readonly configPath?: string;
+    /** 커넥션 URL — 다른 서브커맨드(seed)에 URL 전달용. url 없는 config 는 undefined. */
+    readonly url?: string;
+    /** 커넥션 정리 — CLI 종료 전 항상 호출. */
+    close(): Promise<void>;
+}
+/**
+ * gaon.config.ts 를 로드해 target db 커넥션을 등록하고 스키마 테이블을 모아 온다.
+ *
+ * 커넥션 결정 순서:
+ *  1) config.db[dbKey] 가 있으면 그 어댑터·URL 사용
+ *  2) dbKey='main' 이고 GAON_DATABASE_URL 이 있으면 그 URL 로 main 을 세움
+ *  3) 그 외 → 수리 안내 에러
+ */
+export declare function resolveDbTarget(opts: ResolveDbOptions): Promise<ResolvedDbTarget>;

package/dist/db/resolve.js

@@ -0,0 +1,130 @@
+// @gaonjs/cli · gaon db 공통 커넥션·스키마 해석 (M9-D)
+//
+// gaon.config.ts → db.<키> 로 커넥션을 조립하고, domain/schema/*.ts 를
+// 스캔해 이 커넥션의 TableDef[] 를 돌려준다. diff/migrate/reset 이 이 값을
+// 공유한다.
+//
+// config 우선순위:
+//  1) opts.config (사용자 명시 --config <path>)
+//  2) cwd/gaon.config.ts (findConfigPath 관례)
+// config 도 GAON_DATABASE_URL 도 없으면 수리 안내 에러(§7.5.3).
+//
+// domain/schema/ 가 없으면 tables=[] (diff 는 dropTable 만 있는 상태).
+// 스키마는 { db: '<키>' } 로 커넥션 바인딩된 것만 이 대상에 포함한다(§4.5).
+import { existsSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { env, EnvError } from '@gaonjs/core';
+import { findConfigPath, loadGaonConfig } from '@gaonjs/config';
+import { createDb, registerConnection, destroyAllConnections, scanSchemaDir, } from '@gaonjs/data';
+import { dialectFor } from '@gaonjs/data';
+import { registerTsResolve } from '../tsResolve.js';
+/** URL 에서 어댑터를 추정한다(seed·work 와 같은 관례). */
+function dbConfigFromUrl(url) {
+    if (url.startsWith('mysql://') || url.startsWith('mariadb://')) {
+        return { adapter: 'mysql', url, poolMax: 4 };
+    }
+    return { adapter: 'postgres', url, poolMax: 4 };
+}
+/**
+ * TableDef 정의를 스캔한다. 스키마 디렉터리가 없으면 [] 를 돌려준다.
+ * 스캔 결과는 커넥션 키로 걸러 diff·migrate 대상만 남긴다(§4.5).
+ */
+async function scanTables(cwd, dbKey) {
+    const schemaDir = join(cwd, 'domain', 'schema');
+    if (!existsSync(schemaDir))
+        return [];
+    // outDir 은 이 함수에서 실제로 파일을 쓰지 않으므로 관례 경로만 지정한다
+    // (scanSchemaDir 은 import 지정자 계산에만 사용). collectTables 는
+    // DiscoveredTable(이름·경로) 만 돌려주므로, 실제 TableDef 값은 모듈 네임스페이스에서
+    // 다시 꺼내야 한다 — 커넥션 키(§4.5)로 필터링해 이 db 것만 남긴다.
+    const outDir = join(cwd, '.gaon');
+    const modules = await scanSchemaDir(schemaDir, outDir);
+    const tables = [];
+    for (const mod of modules) {
+        for (const [, value] of Object.entries(mod.ns)) {
+            if (isTableDef(value) && value.db === dbKey)
+                tables.push(value);
+        }
+    }
+    return tables.sort((a, b) => a.name.localeCompare(b.name));
+}
+function isTableDef(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'name' in v &&
+        'defs' in v &&
+        'db' in v &&
+        typeof v.name === 'string');
+}
+/**
+ * gaon.config.ts 를 로드해 target db 커넥션을 등록하고 스키마 테이블을 모아 온다.
+ *
+ * 커넥션 결정 순서:
+ *  1) config.db[dbKey] 가 있으면 그 어댑터·URL 사용
+ *  2) dbKey='main' 이고 GAON_DATABASE_URL 이 있으면 그 URL 로 main 을 세움
+ *  3) 그 외 → 수리 안내 에러
+ */
+export async function resolveDbTarget(opts) {
+    const cwd = resolvePath(opts.cwd);
+    registerTsResolve();
+    // 사용자가 --config <path> 를 준 경우 그 경로에서 default export 를 로드한다.
+    // 없으면 cwd 관례.
+    let configPath;
+    let config;
+    if (opts.configPath) {
+        configPath = resolvePath(opts.configPath);
+        if (!existsSync(configPath)) {
+            throw new Error(`[gaon db] --config 로 지정한 파일이 없습니다: ${configPath}\n` +
+                `→ 경로를 확인하거나 --config 없이 실행해 cwd/gaon.config.ts 를 쓰세요.`);
+        }
+        const mod = (await import(pathToFileURL(configPath).href));
+        if (!mod.default || typeof mod.default !== 'object') {
+            throw new Error(`[gaon db] --config 파일의 default export 가 객체가 아닙니다: ${configPath}\n` +
+                `→ export default defineConfig({ db: { main: { adapter: 'postgres', url: '...' } } }) 형태로 두세요.`);
+        }
+        config = mod.default;
+    }
+    else {
+        configPath = findConfigPath(cwd);
+        config = await loadGaonConfig(cwd);
+    }
+    const dbKey = opts.dbKey;
+    const cfg = config.db?.[dbKey];
+    let connCfg;
+    if (cfg) {
+        connCfg = cfg;
+    }
+    else if (dbKey === 'main') {
+        // 폴백: GAON_DATABASE_URL (seed 와 같은 관례).
+        const url = env.optional('GAON_DATABASE_URL');
+        if (!url) {
+            throw new EnvError(`[gaon db] main 커넥션을 결정할 수 없습니다.\n` +
+                `  → gaon.config.ts 에 db.main 을 선언하거나, .env 에 다음 줄을 추가하세요:\n` +
+                `      GAON_DATABASE_URL=postgres://user:pass@localhost:5432/mydb`);
+        }
+        connCfg = dbConfigFromUrl(url);
+    }
+    else {
+        const known = Object.keys(config.db ?? {}).sort();
+        throw new Error(`[gaon db] 커넥션 '${dbKey}' 이(가) gaon.config.ts 에 없습니다.\n` +
+            `  등록된 키: ${known.length ? known.join(', ') : '(없음)'}\n` +
+            `  → gaon.config.ts 의 db.${dbKey} 를 선언하고 다시 실행하세요.`);
+    }
+    const db = createDb(connCfg);
+    registerConnection(dbKey, db, connCfg.adapter);
+    const dialect = dialectFor(connCfg.adapter);
+    const tables = await scanTables(cwd, dbKey);
+    return {
+        dbKey,
+        adapter: connCfg.adapter,
+        db,
+        dialect,
+        tables,
+        configPath,
+        url: 'url' in connCfg ? connCfg.url : undefined,
+        async close() {
+            await destroyAllConnections();
+        },
+    };
+}

package/dist/dev/console.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @gaonjs/cli · dev/console — `gaon dev` 통합 콘솔 (M9-C)
+ *
+ * `gaon dev` 는 여러 자식(Docker · serve · tsc · vue-tsc · 파일 워처)의
+ * 출력을 한 콘솔로 합친다. 어느 소스에서 왔는지 즉시 알아보게 [tag] 를
+ * 접두어로 붙이고, 소스별 색으로 시선을 잡는다.
+ *
+ * 두 가지 모드:
+ *   - human: `  [serve]  ▶ 리슨 중 — ...`  (색상 · 사람 눈)
+ *   - json : `{"source":"serve","level":"info","msg":"..."}`  (자동화 파싱)
+ *
+ * ANSI 는 TTY 일 때만 켠다(파이프 · 리다이렉트에는 순수 텍스트). 무의존
+ * 정책상 chalk 는 쓰지 않는다 — 필요한 코드만 직접 쓴다.
+ */
+/** 콘솔이 구분하는 로그 소스. */
+export type DevSource = 'dev' | 'docker' | 'serve' | 'watcher' | 'tsc' | 'vue-tsc';
+/** 로그 레벨 — human 은 색상 강조, json 은 필드로 실린다. */
+export type DevLevel = 'info' | 'warn' | 'error';
+export interface DevConsoleOptions {
+    readonly json?: boolean;
+    /** 색상 강제 on/off. 생략 시 stdout.isTTY 자동 감지. */
+    readonly color?: boolean;
+    /** 타임스탬프 표시(사람 모드). 생략 시 false. */
+    readonly timestamp?: boolean;
+    /** 출력 스트림(테스트 주입). 기본 process.stdout. */
+    readonly stdout?: NodeJS.WritableStream;
+    /** 에러 출력 스트림(테스트 주입). 기본 process.stderr. */
+    readonly stderr?: NodeJS.WritableStream;
+}
+export interface DevConsole {
+    log(source: DevSource, line: string, level?: DevLevel): void;
+    /** 여러 줄(개행 포함) 청크를 줄 단위로 나눠 로그. 자식 stdout 파이프용. */
+    pipe(source: DevSource, chunk: string | Buffer, level?: DevLevel): void;
+}
+/**
+ * 통합 콘솔을 만든다. json 모드면 소스별 JSON 라인, 그 외엔 색상 태그
+ * + 사람 텍스트로 출력한다. 에러 레벨은 stderr, 그 외는 stdout.
+ */
+export declare function createDevConsole(opts?: DevConsoleOptions): DevConsole;