@gaonjs/cli 0.3.0 → 0.5.0

package/dist/commands/test.js

@@ -0,0 +1,119 @@
+/**
+ * @gaonjs/cli · `gaon test` — vitest wrapper (M9-G · v0.15 §13.5)
+ *
+ * The One Way — 하나의 명령이 vitest 를 얇게 감싼다. 사용자는
+ * `gaon test` 로 전체를, `gaon test posts` 로 필터를, `gaon test --unit`
+ * 으로 단위만 실행한다. 나머지는 전부 vitest 에 그대로 위임 — 우리가
+ * 관례를 재발명하지 않는다.
+ *
+ * 스코프 필터(§9 실 인프라 관례):
+ *   --unit         *.test.ts (통합 제외)
+ *   --integration  *.integration.test.ts 만
+ *   (기본)         둘 다 실행
+ *
+ * 실행 경로 우선순위:
+ *   1) 사용자 package.json 의 `test` 스크립트가 있으면 `pnpm test -- <args>`
+ *   2) 로컬 node_modules/.bin/vitest 가 있으면 직접 spawn(`run` 모드)
+ *   3) 둘 다 없으면 exit 127 + 설치 안내
+ *
+ * §9 실 인프라 · 목업 X — 실 vitest 프로세스를 spawn 한다.
+ * exit code · signal 은 vitest 그대로 propagate.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** 사용자 프로젝트에 `test` 스크립트가 있는지. */
+function hasTestScript(cwd) {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath))
+        return false;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return typeof pkg.scripts?.test === 'string' && pkg.scripts.test.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 스코프 → vitest CLI 인자로 매핑. vitest 는 위치 인자를 파일 패턴으로
+ * 해석한다(맨 뒤에 붙는 값이 include 필터). --include 플래그는 vitest
+ * CLI 에 없다 — 그래서 unit 은 --exclude 로, integration 은 위치 인자
+ * 패턴으로 처리한다.
+ */
+function scopeArgs(scope) {
+    if (scope === 'unit') {
+        // 통합 테스트 제외 — vitest 의 --exclude 로 스킵.
+        return ['--exclude', '**/*.integration.test.ts'];
+    }
+    if (scope === 'integration') {
+        // integration 만 — 위치 인자 필터(파일 경로 substring 매칭).
+        return ['integration.test'];
+    }
+    return [];
+}
+/**
+ * `gaon test` 진입점. args 는 사용자가 넘긴 잔여 인자(필터 문자열 등).
+ * pnpm test 는 pnpm 관례상 `pnpm test -- <args>` 로 넘겨야 vitest 까지 도달.
+ */
+export async function runTestCommand(args = [], opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const scope = opts.scope ?? 'all';
+    const json = opts.json ?? false;
+    const scopeExtras = scopeArgs(scope);
+    const passthrough = [...scopeExtras, ...args];
+    let cmd;
+    let spawnArgs;
+    if (hasTestScript(cwd)) {
+        cmd = 'pnpm';
+        // pnpm test -- <extras> — `--` 로 뒤 인자를 스크립트에 전달.
+        spawnArgs = ['test', ...(passthrough.length ? ['--', ...passthrough] : [])];
+    }
+    else {
+        const vitestBin = join(cwd, 'node_modules', '.bin', 'vitest');
+        if (!existsSync(vitestBin)) {
+            const msg = `vitest 가 설치돼 있지 않고 package.json 에 "test" 스크립트도 없습니다.\n` +
+                `→ pnpm add -D vitest 후 다시 실행하거나, package.json 에 "test": "vitest run" 을 추가하세요.`;
+            if (json) {
+                process.stdout.write(JSON.stringify({ ok: false, error: msg }) + '\n');
+            }
+            else {
+                process.stderr.write(`  ✗ ${msg}\n`);
+            }
+            return 127;
+        }
+        cmd = vitestBin;
+        spawnArgs = ['run', ...passthrough];
+    }
+    if (json) {
+        process.stdout.write(JSON.stringify({ kind: 'starting', cmd, args: spawnArgs, scope }) + '\n');
+    }
+    else {
+        process.stdout.write(`  gaon test · ${cmd} ${spawnArgs.join(' ')} (scope=${scope})\n`);
+    }
+    const exitCode = await new Promise((resolvePromise) => {
+        const child = spawn(cmd, spawnArgs, {
+            cwd,
+            env: process.env,
+            // vitest 컬러 출력·리포터를 그대로 보여주기 위해 stdio 를 상속한다.
+            stdio: 'inherit',
+        });
+        child.on('error', (err) => {
+            process.stderr.write(`  ✗ gaon test spawn 실패: ${String(err)}\n`);
+            resolvePromise(127);
+        });
+        child.on('close', (code, signal) => {
+            if (signal) {
+                // SIGINT 등으로 종료된 경우 — 130(SIGINT) 관례.
+                resolvePromise(signal === 'SIGINT' ? 130 : 1);
+            }
+            else {
+                resolvePromise(code ?? 1);
+            }
+        });
+    });
+    if (json) {
+        process.stdout.write(JSON.stringify({ kind: 'exited', exitCode }) + '\n');
+    }
+    return exitCode;
+}

package/dist/db/diff.d.ts

@@ -0,0 +1,17 @@
+export interface DbDiffOptions {
+    readonly cwd: string;
+    readonly dbKey: string;
+    readonly json: boolean;
+    readonly configPath?: string;
+}
+export interface DbDiffResult {
+    readonly exitCode: number;
+    readonly text: string;
+    readonly json: unknown;
+}
+/**
+ * `gaon db diff` — 커넥션 대비 스키마 diff 를 계산해 텍스트·JSON 을 낳는다.
+ * 아무것도 적용하지 않는다. exitCode 는 항상 0(변경 없음도 성공 · CI 에서
+ * 변경 존재 여부만 보고 싶으면 --json 의 changes 를 읽어라).
+ */
+export declare function runDbDiff(opts: DbDiffOptions): Promise<DbDiffResult>;

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