@gaonjs/cli 0.3.0 → 0.4.0

package/dist/__fixtures__/db-minimal/domain/schema/widgets.d.ts

@@ -0,0 +1,12 @@
+import { type RowOf } from '@gaonjs/data';
+export declare const m9dWidgets: import("@gaonjs/data").TableDef<"m9d_widgets", {
+    id: import("@gaonjs/data").BigintCol<{
+        hasDefault: true;
+    }>;
+    name: import("@gaonjs/data").StringCol<{}>;
+}>;
+declare module '@gaonjs/data' {
+    interface GaonTables {
+        m9d_widgets: RowOf<typeof m9dWidgets>;
+    }
+}

package/dist/__fixtures__/db-minimal/domain/schema/widgets.js

@@ -0,0 +1,7 @@
+// db 통합 테스트 픽스처 — main 커넥션의 유일한 테이블.
+// 이름은 m9d_widgets (M8 seed 픽스처의 widgets 와 GaonTables 병합 충돌 회피).
+import { table, t } from '@gaonjs/data';
+export const m9dWidgets = table('m9d_widgets', {
+    id: t.id(),
+    name: t.string().max(30),
+});

package/dist/__fixtures__/db-minimal/gaon.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@gaonjs/config").GaonConfig;
+export default _default;

package/dist/__fixtures__/db-minimal/gaon.config.js

@@ -0,0 +1,11 @@
+// db 통합 테스트 픽스처 — main 커넥션만 있는 최소 gaon.config.ts.
+// url 은 GAON_TEST_PG_URL 우선 · 로컬 default 는 packages/data/compose.yaml 정합.
+import { defineConfig } from '@gaonjs/config';
+export default defineConfig({
+    db: {
+        main: {
+            adapter: 'postgres',
+            url: process.env.GAON_TEST_PG_URL ?? 'postgres://gaon:gaon@127.0.0.1:5433/gaon_test',
+        },
+    },
+});

package/dist/commands/db.d.ts

@@ -0,0 +1,20 @@
+export type DbSubcommand = 'diff' | 'migrate' | 'reset' | 'seed';
+export interface DbCommandOptions {
+    /** 프로젝트 루트 — gaon.config.ts·domain/schema 위치. 기본 process.cwd(). */
+    readonly cwd?: string;
+    /** 자동화 출력. 기본 false(사람 텍스트). */
+    readonly json?: boolean;
+    /** 커넥션 키(§4.5). 기본 'main'. */
+    readonly db?: string;
+    /** --config <path> 오버라이드. 없으면 cwd/gaon.config.ts 관례. */
+    readonly config?: string;
+    /** reset 확증 — 없으면 거부(--dry-run 은 예외). */
+    readonly yes?: boolean;
+    /** migrate/reset dry-run — 실행 없이 SQL 만 출력. */
+    readonly dryRun?: boolean;
+}
+/**
+ * `gaon db <sub>` 진입점. 사람/JSON 출력을 자체 처리하고 exitCode 를
+ * 돌려준다. seed 는 기존 M8 runDbSeedCommand 로 위임(신규 서명에 정합).
+ */
+export declare function runDbCommand(subcommand: DbSubcommand, opts?: DbCommandOptions): Promise<number>;

package/dist/commands/db.js

@@ -0,0 +1,74 @@
+// @gaonjs/cli · `gaon db <sub>` — 서브커맨드 디스패처 (M9-D)
+//
+// 4종을 한 곳에서 배선한다: diff · migrate · reset · seed.
+//  · diff/migrate/reset 은 db/*.ts 로 위임.
+//  · seed 는 기존 M8 로직(runDbSeedCommand · packages/cli/src/db.ts) 을
+//    그대로 위임 — 이 세션은 seed 를 건드리지 않는다.
+//
+// runCli 는 argv 를 이 함수로 넘긴다. 사람/JSON 출력·exitCode 전달까지
+// 여기서 마감해서 index.ts 는 dispatch 만 한다.
+import { runDbDiff } from '../db/diff.js';
+import { runDbMigrate } from '../db/migrate.js';
+import { runDbReset } from '../db/reset.js';
+import { runDbSeedCommand } from '../db.js';
+/**
+ * `gaon db <sub>` 진입점. 사람/JSON 출력을 자체 처리하고 exitCode 를
+ * 돌려준다. seed 는 기존 M8 runDbSeedCommand 로 위임(신규 서명에 정합).
+ */
+export async function runDbCommand(subcommand, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = opts.json ?? false;
+    const dbKey = opts.db ?? 'main';
+    const configPath = opts.config;
+    const dryRun = opts.dryRun ?? false;
+    const emit = (text, jsonValue) => {
+        if (json)
+            process.stdout.write(JSON.stringify(jsonValue) + '\n');
+        else
+            process.stdout.write(text + '\n');
+    };
+    try {
+        if (subcommand === 'diff') {
+            const r = await runDbDiff({ cwd, dbKey, json, configPath });
+            emit(r.text, r.json);
+            return r.exitCode;
+        }
+        if (subcommand === 'migrate') {
+            const r = await runDbMigrate({ cwd, dbKey, json, dryRun, configPath });
+            emit(r.text, r.json);
+            return r.exitCode;
+        }
+        if (subcommand === 'reset') {
+            const r = await runDbReset({
+                cwd,
+                dbKey,
+                json,
+                yes: opts.yes ?? false,
+                dryRun,
+                configPath,
+            });
+            emit(r.text, r.json);
+            return r.exitCode;
+        }
+        if (subcommand === 'seed') {
+            // 기존 M8 로직 — 옵션 shape 이 다르므로 필요한 것만 전달.
+            const r = await runDbSeedCommand({ root: cwd, json });
+            emit(r.text, r.json);
+            return r.exitCode;
+        }
+        // 방어 — dispatcher 라 도달할 수 없지만 컴파일러 만족용.
+        process.stderr.write(`  ✗ 알 수 없는 db 서브커맨드: ${String(subcommand)}\n` +
+            `  → 지원: diff | migrate | reset | seed\n`);
+        return 1;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (json) {
+            process.stdout.write(JSON.stringify({ command: subcommand, ok: false, error: msg }) + '\n');
+        }
+        else {
+            process.stderr.write(`  ✗ gaon db ${subcommand} 실패: ${msg}\n`);
+        }
+        return 1;
+    }
+}

package/dist/commands/dev.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @gaonjs/cli · `gaon dev` — 개발 오케스트레이션 (M9-C · v0.15 §13.5)
+ *
+ * 하나의 명령이 개발 스택 전체를 띄운다:
+ *   1) Docker Compose  — pg · redis · nats · mailpit · minio 자동 up -d
+ *   2) .gaon 워처       — tables.d.ts · routes.d.ts 재생성 (기존 M3)
+ *   3) serve 자식       — 실 웹 서버(Fastify) · 소스 변경 시 재시작
+ *   4) tsc / vue-tsc    — --watch 모드 · 타입 에러 즉시 리포트
+ *   5) restart 워처     — apps/ · domain/ · packages/ 변경 → serve 재시작
+ *   6) 통합 콘솔        — [source] 태그·색상별 · JSON 모드 지원
+ *
+ * The One Way: `gaon dev` 하나로 전부 · 옵션은 개별 debug 용만 노출.
+ * fail-closed: Docker 없으면 명확 안내(§7.5.3), 목업 대체 절대 X (§9).
+ * ctrl-C: graceful — serve → tsc → 워처 순 정리 · Docker 는 유지(재사용)
+ *   또는 --stop-docker 시 down.
+ *
+ * HMR: v1 Vue 어댑터는 아직 Vite 통합이 없어(§6.4) 서버 재시작 방식만
+ * 지원한다. 진짜 Vue HMR 은 어댑터 통합 이후 확장 예정.
+ */
+import { existsSync } from 'node:fs';
+export interface DevCommandOptions {
+    readonly cwd?: string;
+    /** JSON 라인 모드(자동화 · CI 파싱). */
+    readonly json?: boolean;
+    /** Ctrl+C 시 Docker Compose 도 down 시킨다(기본 false — 재사용). */
+    readonly stopDocker?: boolean;
+    /** serve 리슨 포트. 생략 시 config 기본값. */
+    readonly port?: number;
+    /** serve 리슨 호스트. 생략 시 config 기본값. */
+    readonly host?: string;
+    /** 서버 재시작 워처 끄기(개별 debug). */
+    readonly noWatch?: boolean;
+    /** tsc 워치 끄기(개별 debug). */
+    readonly noTsc?: boolean;
+    /** vue-tsc 워치 끄기(개별 debug). */
+    readonly noVueTsc?: boolean;
+    /** Docker 자동 기동 끄기(개별 debug · 사용자가 이미 띄운 경우). */
+    readonly noDocker?: boolean;
+    /** 통합 콘솔 타임스탬프 표시. */
+    readonly timestamp?: boolean;
+    /** 시그널(테스트 주입 · 기본 process). */
+    readonly signals?: {
+        on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+        off(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+    };
+}
+/**
+ * gaon 셀프 경로를 찾는다. 부모가 gaon 으로 실행됐다면 argv[1] 이
+ * gaonjs/dist/cli.js (또는 개발 시 packages/gaonjs/src/cli.ts). 자식
+ * serve 도 같은 진입점을 재사용한다 — 사용자 환경에서 강제 폴백 없이
+ * 동일 CLI 를 다시 부른다.
+ */
+declare function resolveSelfCliEntry(): {
+    node: string;
+    args: string[];
+};
+/**
+ * `gaon dev` 진입점. 자식들을 순서대로 띄우고, SIGINT/SIGTERM 로 정리한다.
+ * 반환 프라미스는 완전 종료 시 resolve — 프로세스는 자식 워처가 살아 있는
+ * 동안 유지된다.
+ */
+export declare function runDevCommand(opts?: DevCommandOptions): Promise<void>;
+export declare const _internals: {
+    resolveSelfCliEntry: typeof resolveSelfCliEntry;
+    fileURLToPathSafe: (u: string) => string;
+    existsSync: typeof existsSync;
+};
+export {};

package/dist/commands/dev.js

@@ -0,0 +1,287 @@
+/**
+ * @gaonjs/cli · `gaon dev` — 개발 오케스트레이션 (M9-C · v0.15 §13.5)
+ *
+ * 하나의 명령이 개발 스택 전체를 띄운다:
+ *   1) Docker Compose  — pg · redis · nats · mailpit · minio 자동 up -d
+ *   2) .gaon 워처       — tables.d.ts · routes.d.ts 재생성 (기존 M3)
+ *   3) serve 자식       — 실 웹 서버(Fastify) · 소스 변경 시 재시작
+ *   4) tsc / vue-tsc    — --watch 모드 · 타입 에러 즉시 리포트
+ *   5) restart 워처     — apps/ · domain/ · packages/ 변경 → serve 재시작
+ *   6) 통합 콘솔        — [source] 태그·색상별 · JSON 모드 지원
+ *
+ * The One Way: `gaon dev` 하나로 전부 · 옵션은 개별 debug 용만 노출.
+ * fail-closed: Docker 없으면 명확 안내(§7.5.3), 목업 대체 절대 X (§9).
+ * ctrl-C: graceful — serve → tsc → 워처 순 정리 · Docker 는 유지(재사용)
+ *   또는 --stop-docker 시 down.
+ *
+ * HMR: v1 Vue 어댑터는 아직 Vite 통합이 없어(§6.4) 서버 재시작 방식만
+ * 지원한다. 진짜 Vue HMR 은 어댑터 통합 이후 확장 예정.
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadDotEnv, VERSION } from '@gaonjs/core';
+import { registerTsResolve } from '../tsResolve.js';
+import { startDev, resolveDevLayout } from '../dev.js';
+import { generateTablesDts, watchDir } from '@gaonjs/data';
+import { generateRoutesDts } from '@gaonjs/web';
+import { createDevConsole } from '../dev/console.js';
+import { ensureInfra, composeDown } from '../dev/docker.js';
+import { startTscWatchers, killChild } from '../dev/tsc.js';
+import { startRestartWatcher } from '../dev/watcher.js';
+/**
+ * gaon 셀프 경로를 찾는다. 부모가 gaon 으로 실행됐다면 argv[1] 이
+ * gaonjs/dist/cli.js (또는 개발 시 packages/gaonjs/src/cli.ts). 자식
+ * serve 도 같은 진입점을 재사용한다 — 사용자 환경에서 강제 폴백 없이
+ * 동일 CLI 를 다시 부른다.
+ */
+function resolveSelfCliEntry() {
+    const scriptPath = process.argv[1];
+    if (!scriptPath) {
+        throw new Error('gaon dev · CLI 자기참조 실패: process.argv[1] 이 비어 있습니다.\n' +
+            '→ gaon 을 npm 스크립트나 bin 을 통해 실행했는지 확인하세요.');
+    }
+    // .ts 진입점(모노레포 dev)은 --experimental-strip-types 필요.
+    const isTs = scriptPath.endsWith('.ts');
+    const flags = isTs ? ['--experimental-strip-types', '--no-warnings'] : [];
+    return { node: process.execPath, args: [...flags, scriptPath] };
+}
+/**
+ * serve 자식을 하나 띄운다. stdout/stderr 을 통합 콘솔로 파이프하고,
+ * exit 콜백에서 종료 코드를 알려준다(비정상 종료 감시용).
+ */
+function spawnServe(args) {
+    const { node, args: nodeArgs } = resolveSelfCliEntry();
+    const serveArgs = ['serve'];
+    if (args.json)
+        serveArgs.push('--json');
+    if (args.port != null)
+        serveArgs.push('--port', String(args.port));
+    if (args.host != null)
+        serveArgs.push('--host', args.host);
+    const child = spawn(node, [...nodeArgs, ...serveArgs], {
+        cwd: args.cwd,
+        // detached=false + own signal handling: 부모가 명시적으로 kill 한다.
+        // 셸에서 Ctrl+C 를 누르면 자식도 같이 SIGINT 를 받는데(같은 프로세스
+        // 그룹), serve 는 자체 handler 로 graceful 종료하므로 안전.
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env },
+    });
+    child.stdout?.on('data', (b) => args.console.pipe('serve', b, 'info'));
+    child.stderr?.on('data', (b) => args.console.pipe('serve', b, 'error'));
+    child.on('exit', (code, signal) => args.onExit(code, signal));
+    return child;
+}
+/**
+ * .gaon 재생성 파이프라인(M3)을 띄운다. 로그는 통합 콘솔로 흘리고,
+ * 이 모듈은 층분리를 위해 startDev 를 그대로 재사용한다.
+ */
+async function startGaonRegen(args) {
+    const layout = resolveDevLayout(args.cwd);
+    return await startDev({
+        layout,
+        regenerateTables: generateTablesDts,
+        regenerateRoutes: generateRoutesDts,
+        watch: watchDir,
+        log: (e) => {
+            if (e.kind === 'ready') {
+                const parts = [];
+                if (e.schema)
+                    parts.push('schema→tables.d.ts');
+                for (const a of e.apps)
+                    parts.push(`${a}→routes.d.ts`);
+                args.console.log('watcher', parts.length
+                    ? `.gaon 재생성 준비 완료 — ${parts.join(', ')}`
+                    : `.gaon 재생성 대상 없음 (domain/schema · apps/* 확인)`);
+            }
+            else if (e.kind === 'regen') {
+                args.console.log('watcher', e.target === 'tables' ? '↻ tables.d.ts 재생성' : `↻ ${e.app}/.gaon/routes.d.ts 재생성`);
+            }
+            else {
+                args.console.log('watcher', '.gaon 워처 종료');
+            }
+        },
+        onError: (err) => args.console.log('watcher', err.message, 'error'),
+    });
+}
+/**
+ * `gaon dev` 진입점. 자식들을 순서대로 띄우고, SIGINT/SIGTERM 로 정리한다.
+ * 반환 프라미스는 완전 종료 시 resolve — 프로세스는 자식 워처가 살아 있는
+ * 동안 유지된다.
+ */
+export async function runDevCommand(opts = {}) {
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    const json = opts.json ?? false;
+    const stopDocker = opts.stopDocker ?? false;
+    const signals = opts.signals ?? process;
+    registerTsResolve();
+    loadDotEnv(cwd);
+    const consoleOut = createDevConsole({ json, timestamp: opts.timestamp });
+    const startedAt = Date.now();
+    consoleOut.log('dev', `gaon dev · 시작 (v${VERSION}) — ${cwd}`);
+    // ── 1) Docker Compose 자동 기동 ─────────────────────────────────
+    let composeFile;
+    if (opts.noDocker !== true) {
+        try {
+            const infra = await ensureInfra({
+                cwd,
+                onLine: (line, level) => consoleOut.log('docker', line, level),
+            });
+            if (infra) {
+                composeFile = infra.composeFile;
+                consoleOut.log('docker', infra.startedNow
+                    ? `▶ compose up 완료 — ${infra.status.runningCount}/${infra.status.definedCount} 서비스 · ${infra.composeFile}`
+                    : `▶ 이미 실행 중(재사용) — ${infra.status.runningCount}/${infra.status.definedCount} 서비스 · ${infra.composeFile}`);
+            }
+            else {
+                consoleOut.log('docker', 'compose 파일이 없어 인프라 자동 기동을 건너뜁니다.');
+            }
+        }
+        catch (err) {
+            consoleOut.log('docker', err.message, 'error');
+            throw err;
+        }
+    }
+    else {
+        consoleOut.log('docker', '--no-docker · 인프라 자동 기동 비활성화');
+    }
+    // ── 2) .gaon 재생성 워처 ─────────────────────────────────────────
+    const regen = await startGaonRegen({ cwd, console: consoleOut });
+    // ── 3) tsc / vue-tsc 워치 ────────────────────────────────────────
+    const tsc = opts.noTsc && opts.noVueTsc
+        ? undefined
+        : startTscWatchers({
+            cwd,
+            enableTsc: opts.noTsc !== true,
+            enableVueTsc: opts.noVueTsc !== true,
+            onLine: (source, line, level) => consoleOut.log(source, line, level),
+            onExit: (source, code) => {
+                // 비정상 종료(code≠0) 는 알린다 · 정상(SIGTERM=null) 은 조용히.
+                if (code != null && code !== 0) {
+                    consoleOut.log(source, `[${source}] 비정상 종료 (code=${code})`, 'warn');
+                }
+            },
+        });
+    // ── 4) serve 자식 · 재시작 스케줄러 ─────────────────────────────
+    let serveChild;
+    let shuttingDown = false;
+    let restartInFlight;
+    const startServe = () => {
+        consoleOut.log('serve', '▶ serve 자식 프로세스 spawn');
+        return spawnServe({
+            cwd,
+            json,
+            port: opts.port,
+            host: opts.host,
+            console: consoleOut,
+            onExit: (code, signal) => {
+                if (shuttingDown)
+                    return;
+                // 사용자 편집으로 인한 재시작 중이면 무시 — restart 흐름이 다시 띄운다.
+                if (restartInFlight)
+                    return;
+                if (code === 0 || signal === 'SIGTERM' || signal === 'SIGINT')
+                    return;
+                consoleOut.log('serve', `serve 자식이 비정상 종료 (code=${code}, signal=${signal}) — 파일을 저장해 재시도하거나 로그를 확인하세요.`, 'error');
+            },
+        });
+    };
+    serveChild = startServe();
+    const restartServe = async (changed) => {
+        if (shuttingDown)
+            return;
+        // 이미 재시작 중이면 그 프라미스에 대기(중첩 방지).
+        if (restartInFlight)
+            return restartInFlight;
+        const summary = changed.slice(0, 3).join(', ') + (changed.length > 3 ? ` ... (+${changed.length - 3})` : '');
+        consoleOut.log('watcher', `↻ 재시작 — ${summary}`);
+        restartInFlight = (async () => {
+            try {
+                if (serveChild && serveChild.exitCode === null && serveChild.signalCode === null) {
+                    await killChild(serveChild, 3000);
+                }
+                if (shuttingDown)
+                    return;
+                serveChild = startServe();
+            }
+            finally {
+                restartInFlight = undefined;
+            }
+        })();
+        return restartInFlight;
+    };
+    // ── 5) 파일 워처(서버 재시작 트리거) ───────────────────────────
+    let restartWatcher;
+    if (opts.noWatch !== true) {
+        restartWatcher = startRestartWatcher({
+            cwd,
+            onRestart: (changed) => restartServe(changed),
+            onError: (err) => consoleOut.log('watcher', err.message, 'error'),
+        });
+        consoleOut.log('watcher', restartWatcher.roots.length > 0
+            ? `▶ 재시작 워치 — ${restartWatcher.roots.map((r) => shortenPath(r, cwd)).join(', ')}`
+            : `▶ 재시작 워치 — 감시 대상 없음(apps/ · domain/ 등 확인)`);
+    }
+    consoleOut.log('dev', `준비 완료 — 부팅 ${Date.now() - startedAt}ms (Ctrl+C 로 종료)`);
+    // ── 6) SIGINT/SIGTERM → graceful ────────────────────────────────
+    await new Promise((resolvePromise) => {
+        const stop = () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            signals.off('SIGINT', stop);
+            signals.off('SIGTERM', stop);
+            consoleOut.log('dev', '종료 신호 수신 — 정리 중...');
+            void (async () => {
+                try {
+                    // 순서: 재시작 워처 → serve → tsc → .gaon 워처 → Docker(옵션)
+                    restartWatcher?.close();
+                    if (serveChild) {
+                        await killChild(serveChild, 5000);
+                    }
+                    if (tsc) {
+                        await tsc.stop();
+                    }
+                    regen.close();
+                    if (stopDocker && composeFile) {
+                        consoleOut.log('docker', '--stop-docker · compose down 실행');
+                        try {
+                            await composeDown(composeFile, {
+                                onLine: (line, level) => consoleOut.log('docker', line, level),
+                            });
+                        }
+                        catch (err) {
+                            consoleOut.log('docker', err.message, 'error');
+                        }
+                    }
+                    else if (composeFile) {
+                        consoleOut.log('docker', 'compose 는 유지 · 다음 gaon dev 에서 재사용');
+                    }
+                }
+                finally {
+                    consoleOut.log('dev', 'gaon dev · 종료');
+                    resolvePromise();
+                }
+            })();
+        };
+        signals.on('SIGINT', stop);
+        signals.on('SIGTERM', stop);
+    });
+}
+/** cwd 기준 상대경로로 짧게(로그 가독성). */
+function shortenPath(p, cwd) {
+    const normP = resolve(p);
+    const normCwd = resolve(cwd);
+    if (normP === normCwd)
+        return '.';
+    if (normP.startsWith(normCwd + '/'))
+        return normP.slice(normCwd.length + 1);
+    return normP;
+}
+// (test·doc 목적으로 노출) — 파일이 실제 존재하는지 여부는 호출자 판단.
+export const _internals = {
+    resolveSelfCliEntry,
+    fileURLToPathSafe: (u) => (u.startsWith('file:') ? fileURLToPath(u) : u),
+    existsSync,
+};

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