@gaonjs/cli 0.4.0 → 0.10.0

package/dist/commands/mcp.js

@@ -0,0 +1,78 @@
+/**
+ * @gaonjs/cli · `gaon mcp` — MCP 서버 부트업 명령 (M10-B · §13.5 M10 · 질문 8)
+ *
+ * 정본 §12 질문 8 확정 명세 4종(라우트 목록·스키마 조회·마이그레이션 실행·
+ * 테스트 실행)을 stdio JSON-RPC 로 노출한다. AI 에이전트(Claude Desktop ·
+ * Cursor · Codex 등)가 이 서버에 붙어 grep 대신 프레임웍에게 직접 묻는다.
+ *
+ * 트랜스포트:
+ *   - stdio (기본 · MCP 표준) — Claude Desktop 등의 mcpServers 설정이
+ *     기본으로 stdio.
+ *   - v1 범위: stdio 만. http/sse 는 후속(§13.5 M10 명시 X).
+ *
+ * 사용법:
+ *   gaon mcp                    # stdio 로 서버 부트, stdin close 까지 대기
+ *   gaon mcp --json             # 자동화용 배너 · 이벤트를 JSON 라인으로 stderr 출력
+ *
+ * 관례:
+ *   - 배너·상태 메시지는 stderr 로만 낸다(stdout 은 MCP 프로토콜 전용).
+ *   - --json 이면 { kind: 'listening' | 'stopped' | 'error' } 라인을 stderr 로.
+ *   - exit code: 정상 종료 0, transport 오류 1.
+ */
+import { startMcpServer } from '../mcp/server.js';
+function humanEvent(e) {
+    switch (e.kind) {
+        case 'listening':
+            return `  gaon mcp · stdio 리슨 중 (cwd=${e.cwd}) · 도구 ${e.tools.length}종: ${e.tools.join(', ')}`;
+        case 'stopped':
+            return `  gaon mcp · 종료`;
+        case 'error':
+            return `  ✗ gaon mcp · ${e.message}`;
+    }
+}
+/**
+ * `gaon mcp` 진입점. stdio transport 는 stdin close 까지 살아 있는다.
+ */
+export async function runMcpCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = opts.json ?? false;
+    const transport = opts.transport ?? 'stdio';
+    const version = opts.version ?? 'dev';
+    // 배너·이벤트는 stderr 로 낸다 — stdout 은 MCP JSON-RPC 프로토콜 스트림.
+    const emit = (e) => {
+        const line = json ? JSON.stringify(e) : humanEvent(e);
+        process.stderr.write(line + '\n');
+    };
+    if (transport !== 'stdio') {
+        emit({
+            kind: 'error',
+            message: `v1 은 stdio 트랜스포트만 지원합니다(요청값: ${transport}).\n` +
+                `  → gaon mcp (기본 stdio) 로 실행하세요.`,
+        });
+        return 1;
+    }
+    // 도구 목록 스냅샷(배너용) — TOOLS SSOT 는 tools.ts.
+    const { TOOLS } = await import('../mcp/tools.js');
+    const toolNames = TOOLS.map((t) => t.name);
+    try {
+        const handle = await startMcpServer({ cwd, version });
+        emit({ kind: 'listening', transport: 'stdio', cwd, tools: toolNames });
+        // stdin close (=상대편 파이프 종료) 시 transport 가 닫히고 wait() 이 resolve.
+        // SIGINT/SIGTERM 을 받아도 명시적으로 서버를 닫는다.
+        const onSignal = () => {
+            void handle.close();
+        };
+        process.on('SIGINT', onSignal);
+        process.on('SIGTERM', onSignal);
+        await handle.wait();
+        process.off('SIGINT', onSignal);
+        process.off('SIGTERM', onSignal);
+        emit({ kind: 'stopped' });
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        emit({ kind: 'error', message });
+        return 1;
+    }
+}

package/dist/commands/new.d.ts

@@ -0,0 +1,45 @@
+/** `gaon new` 옵션. 모두 선택적 — 기본값이 The One Way. */
+export interface NewCommandOptions {
+    /** 프로젝트 생성 위치의 부모 폴더. 기본 process.cwd(). */
+    readonly cwd?: string;
+    /** 자동화용 구조화 출력. */
+    readonly json?: boolean;
+    /** 의존성 설치 스킵(테스트·오프라인). */
+    readonly skipInstall?: boolean;
+    /** git init · 첫 커밋 스킵(테스트·기존 git 저장소에 삽입). */
+    readonly skipGit?: boolean;
+    /** 패키지 매니저. 기본 pnpm(모노레포 관례 정합). */
+    readonly packageManager?: 'pnpm' | 'npm' | 'yarn';
+    /**
+     * (테스트 훅) 템플릿의 gaonjs 의존성 버전. 미지정 시 파사드(gaonjs)
+     * 패키지의 실 버전을 자동 조회한다(package.json).
+     */
+    readonly gaonjsVersion?: string;
+}
+/** JSON 리포트(--json). 사람 모드는 콘솔에 사람이 읽는 요약을 출력한다. */
+export interface NewCommandResult {
+    readonly ok: boolean;
+    readonly project: string;
+    readonly path: string;
+    readonly filesCreated: number;
+    readonly install: {
+        readonly ran: boolean;
+        readonly skipped: boolean;
+        readonly packageManager: string;
+        readonly durationMs: number;
+        readonly exitCode: number | null;
+    };
+    readonly git: {
+        readonly ran: boolean;
+        readonly skipped: boolean;
+        readonly initialized: boolean;
+        readonly firstCommit: boolean;
+    };
+    readonly totalMs: number;
+    readonly error?: string;
+}
+/**
+ * `gaon new <name>` 실행. 파일 생성 → pnpm install → git init 순서.
+ * 각 단계는 옵션으로 스킵 가능. 반환값은 프로세스 종료 코드(0=성공).
+ */
+export declare function runNewCommand(name: string, opts?: NewCommandOptions): Promise<number>;

package/dist/commands/new.js

@@ -0,0 +1,274 @@
+// @gaonjs/cli · `gaon new <name>` — 프로젝트 스캐폴드 (M9-F).
+//
+// v0.15 §13.5 M9 완료 기준 "설치 후 첫 화면까지 60초" 를 만족시키기 위한
+// One Way. `gaon new demo` → cd demo → `gaon serve` → http://localhost:3000
+// 응답 이 전체 흐름의 목표. 60초 안에 이 왕복이 끝나야 한다.
+//
+// 관례(§2 · errata E-1 · E-3 · E-4 · E-5):
+//   · 폴더 배치: apps/<앱>/ + domain/ + shared/ (앱 밖에 domain)
+//   · 프론트: Vue + Inertia SPA (`gaonjs/vue`)
+//   · 인프라: docker-compose.yaml 5종(pg · redis · nats · mailpit · minio)
+//   · 컴포저블·레이아웃: E-5(apps/<앱>/composables + shared/composables, 대칭
+//     구조 · layouts/Default.vue 존재 시 자동 적용)
+//   · 자동 import 금지 — 모든 import 는 명시적으로(E-5 §2.4).
+//
+// 옵션은 최소로: --skip-install · --skip-git · --json · --package-manager.
+// The One Way — pnpm workspace monorepo · Vue · Inertia SPA · 5종 인프라.
+//
+// 이 파일은 파일 생성·설치·git init 만 담당하고, argv 파싱과 배선은
+// index.ts 가 통합한다(M9-F 는 편집 X — M1 이 통합 커밋).
+import { existsSync, mkdirSync, readdirSync, writeFileSync, } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+import { renderProjectFiles } from '../templates/index.js';
+/** 이름 유효성 — npm 패키지명 규칙(단순 부분)만 검사. */
+function validateProjectName(name) {
+    if (!name)
+        throw new Error('프로젝트 이름이 비어 있습니다.');
+    if (name.includes('/') || name.includes('\\')) {
+        throw new Error(`프로젝트 이름에 '/' 또는 '\\\\' 는 사용할 수 없습니다: ${name}`);
+    }
+    if (name.includes('..')) {
+        throw new Error(`프로젝트 이름에 '..' 는 사용할 수 없습니다: ${name}`);
+    }
+    if (!/^[a-z0-9][a-z0-9_-]*$/i.test(name)) {
+        throw new Error(`프로젝트 이름은 영문/숫자/-/_ 로 시작해 같은 문자만 씁니다: ${name}\n` +
+            `  → 예: gaon new my-app · gaon new demo`);
+    }
+}
+/** 파사드(gaonjs) 패키지의 실 버전을 찾는다 — package.json 을 위로 훑는다. */
+function detectGaonjsVersion() {
+    // 가장 안전한 방법: 이 파일 위치를 기준으로 packages/gaonjs/package.json 을
+    // 상향 탐색. 개발 트리(src)와 배포 트리(dist) 모두에서 동작한다.
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i++) {
+        const candidate = join(dir, '..', 'gaonjs', 'package.json');
+        if (existsSync(candidate)) {
+            try {
+                const raw = readFileSync(candidate, 'utf8');
+                const pkg = JSON.parse(raw);
+                if (typeof pkg.version === 'string')
+                    return `^${pkg.version}`;
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // 발견 못 하면 최근 스텁 배포 라인의 안전 하한.
+    return '^0.5.0';
+}
+/** 대상 폴더가 비어 있는지(생성 대상으로 안전한지) 확인. */
+function isEmptyOrMissing(dir) {
+    if (!existsSync(dir))
+        return true;
+    try {
+        const entries = readdirSync(dir);
+        return entries.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** 파일 전체를 디스크에 쓴다. 이미 있으면 예외. */
+function writeAll(root, files) {
+    let count = 0;
+    for (const f of files) {
+        const abs = join(root, f.path);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, f.contents, 'utf8');
+        count += 1;
+    }
+    return count;
+}
+/** 패키지 매니저 install 명령을 동기 실행. 반환값에 종료 코드·시간 포함.
+ *  json 모드에서는 stdout 을 완전 격리해 JSON 라인이 pnpm progress 로
+ *  오염되지 않도록 한다 — 파이프라인 파서 안전 정합. */
+function runInstall(root, pm, json) {
+    const args = ['install'];
+    const t0 = Date.now();
+    // stdio: json 모드에서는 stdout 을 ignore(우리 JSON 을 오염시키지 않게),
+    //        stderr 는 사용자에게 원인 진단이 필요할 수 있어 inherit.
+    //        human 모드에서는 모든 스트림을 inherit(사용자가 progress 를 본다).
+    const res = spawnSync(pm, args, {
+        cwd: root,
+        stdio: json ? ['ignore', 'ignore', 'inherit'] : 'inherit',
+        env: process.env,
+    });
+    const ms = Date.now() - t0;
+    if (res.error) {
+        process.stderr.write(`  ✗ ${pm} 을 찾지 못했습니다. → ${pm} 을 설치하거나 --skip-install 로 건너뛰세요.\n`);
+        return { code: -1, ms };
+    }
+    return { code: res.status, ms };
+}
+/** git init + 첫 커밋. git 이 없으면 조용히 스킵(로컬에 git 없이도 스캐폴드는 성공). */
+function runGitInit(root) {
+    const opts = { cwd: root, stdio: 'ignore', env: process.env };
+    const init = spawnSync('git', ['init', '--initial-branch=main'], opts);
+    if (init.error || init.status !== 0)
+        return { initialized: false, firstCommit: false };
+    spawnSync('git', ['add', '-A'], opts);
+    // 첫 커밋 — 사용자 git config 가 없어도 실패하지 않도록 -c 로 임시 identity 주입.
+    const commit = spawnSync('git', [
+        '-c',
+        'user.email=gaon@gaonjs.dev',
+        '-c',
+        'user.name=Gaon',
+        'commit',
+        '-m',
+        'chore: gaon new — initial scaffold',
+        '--no-gpg-sign',
+    ], opts);
+    return { initialized: true, firstCommit: commit.status === 0 };
+}
+/**
+ * `gaon new <name>` 실행. 파일 생성 → pnpm install → git init 순서.
+ * 각 단계는 옵션으로 스킵 가능. 반환값은 프로세스 종료 코드(0=성공).
+ */
+export async function runNewCommand(name, opts = {}) {
+    const t0 = Date.now();
+    const cwd = opts.cwd ?? process.cwd();
+    const pm = opts.packageManager ?? 'pnpm';
+    const json = opts.json ?? false;
+    const emitError = (msg, totalMs) => {
+        if (json) {
+            const result = {
+                ok: false,
+                project: name,
+                path: resolve(cwd, name),
+                filesCreated: 0,
+                install: { ran: false, skipped: true, packageManager: pm, durationMs: 0, exitCode: null },
+                git: { ran: false, skipped: true, initialized: false, firstCommit: false },
+                totalMs,
+                error: msg,
+            };
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        }
+        else {
+            process.stderr.write(`  ✗ gaon new: ${msg}\n`);
+        }
+        return 1;
+    };
+    try {
+        validateProjectName(name);
+    }
+    catch (err) {
+        return emitError(err instanceof Error ? err.message : String(err), Date.now() - t0);
+    }
+    const root = resolve(cwd, name);
+    if (!isEmptyOrMissing(root)) {
+        return emitError(`대상 폴더가 비어 있지 않습니다: ${root}\n` +
+            `  → 다른 이름을 쓰거나 폴더를 비운 뒤 다시 실행하세요.`, Date.now() - t0);
+    }
+    // 파일 생성 — 실패 시 부분 생성물이 남지 않도록 폴더를 정리하지는 않는다
+    // (사용자가 원인 파악 후 rm -rf 로 지우도록). 정상 흐름에서는 문제 없음.
+    const gaonjsVersion = opts.gaonjsVersion ?? detectGaonjsVersion();
+    const files = renderProjectFiles({ projectName: name, gaonjsVersion });
+    let filesCreated = 0;
+    try {
+        mkdirSync(root, { recursive: true });
+        filesCreated = writeAll(root, files);
+    }
+    catch (err) {
+        return emitError(`파일 생성 실패: ${err instanceof Error ? err.message : String(err)}`, Date.now() - t0);
+    }
+    // pnpm install (또는 npm/yarn) — 스킵 시 안내만.
+    const installReport = {
+        ran: false,
+        skipped: opts.skipInstall === true,
+        packageManager: pm,
+        durationMs: 0,
+        exitCode: null,
+    };
+    if (!opts.skipInstall) {
+        if (!json)
+            process.stdout.write(`\n  · 의존성 설치 (${pm} install) ...\n`);
+        const { code, ms } = runInstall(root, pm, json);
+        installReport.ran = true;
+        installReport.durationMs = ms;
+        installReport.exitCode = code;
+        if (code !== 0) {
+            // install 실패는 스캐폴드 자체 실패로 취급하지 않는다 — 파일은 이미
+            // 만들어졌으므로 사용자가 원인(레지스트리·네트워크) 확인 후 재시도 가능.
+            // 종료 코드는 실패로 반환(자동화 파이프라인 정합).
+            const total = Date.now() - t0;
+            if (json) {
+                const result = {
+                    ok: false,
+                    project: name,
+                    path: root,
+                    filesCreated,
+                    install: installReport,
+                    git: { ran: false, skipped: true, initialized: false, firstCommit: false },
+                    totalMs: total,
+                    error: `${pm} install 실패 (exit ${code})`,
+                };
+                process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`  ✗ ${pm} install 이 실패했습니다 (exit ${code}).\n` +
+                    `  → 네트워크·레지스트리 상태를 확인한 뒤 ${root} 에서 다시 ${pm} install 을 실행하세요.\n`);
+            }
+            return 1;
+        }
+    }
+    // git init + 첫 커밋 — 스킵 시 그대로 넘어감.
+    const gitReport = { ran: false, skipped: opts.skipGit === true, initialized: false, firstCommit: false };
+    if (!opts.skipGit) {
+        if (!json)
+            process.stdout.write(`  · git 저장소 초기화 (git init + 첫 커밋) ...\n`);
+        const g = runGitInit(root);
+        gitReport.ran = true;
+        gitReport.initialized = g.initialized;
+        gitReport.firstCommit = g.firstCommit;
+    }
+    const totalMs = Date.now() - t0;
+    if (json) {
+        const result = {
+            ok: true,
+            project: name,
+            path: root,
+            filesCreated,
+            install: installReport,
+            git: gitReport,
+            totalMs,
+        };
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return 0;
+    }
+    // 사람 모드 요약 — 다음 단계를 § 방향과 함께 안내(§7.5.3 원칙 정합).
+    const lines = [''];
+    lines.push(`  gaon new ${name} — 스캐폴드 완료 (${filesCreated}개 파일 · ${totalMs}ms)`);
+    lines.push('');
+    lines.push(`   폴더: ${root}`);
+    if (installReport.ran) {
+        lines.push(`   ${pm} install: ${installReport.exitCode === 0 ? '성공' : '실패'} (${installReport.durationMs}ms)`);
+    }
+    else {
+        lines.push(`   ${pm} install: 스킵 (--skip-install)`);
+    }
+    if (gitReport.ran) {
+        lines.push(`   git init: ${gitReport.initialized ? '완료' : '실패'} · 첫 커밋: ${gitReport.firstCommit ? '완료' : '실패(수동)'}`);
+    }
+    else {
+        lines.push(`   git init: 스킵 (--skip-git)`);
+    }
+    lines.push('');
+    lines.push('  다음 단계:');
+    lines.push(`   1) cd ${name}`);
+    lines.push('   2) cp .env.example .env       # 환경 변수 편집');
+    lines.push('   3) gaon dev                    # Docker + 타입 브리지 + serve 통합');
+    lines.push('   4) http://localhost:3000       # 홈 페이지 확인 (60초 실측 · v0.15 §13.5 M9)');
+    lines.push('');
+    lines.push('  문서: https://gaonjs.dev');
+    lines.push('');
+    process.stdout.write(lines.join('\n') + '\n');
+    return 0;
+}

package/dist/commands/test.d.ts

@@ -0,0 +1,11 @@
+export type TestScope = 'unit' | 'integration' | 'all';
+export interface TestCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+    readonly scope?: TestScope;
+}
+/**
+ * `gaon test` 진입점. args 는 사용자가 넘긴 잔여 인자(필터 문자열 등).
+ * pnpm test 는 pnpm 관례상 `pnpm test -- <args>` 로 넘겨야 vitest 까지 도달.
+ */
+export declare function runTestCommand(args?: readonly string[], opts?: TestCommandOptions): Promise<number>;

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.js

@@ -4,6 +4,7 @@
 // 방언별 up/down 을 이미 만든다(@gaonjs/data). 이 함수는 배선·표현 담당.
 import { computeMigration } from '@gaonjs/data';
 import { resolveDbTarget } from './resolve.js';
+import { listMigrationFiles } from './replay.js';
 function opSummary(op) {
     switch (op.kind) {
         case 'createTable':
@@ -30,6 +31,9 @@ export async function runDbDiff(opts) {
     try {
         const plan = await computeMigration(target.db, target.tables, target.dialect);
         const ops = plan.ops.map(opSummary);
+        // diff 는 스키마↔DB 차이만 미리 보여준다(적용 X). db/migrations/*.ts 는
+        // migrate 의 replay 단계가 실제로 실행한다(§4.8) — 여기선 목록만 참고로 싣는다.
+        const migrationFiles = listMigrationFiles(opts.cwd).map((f) => `db/migrations/${f}`);
         const json = {
             command: 'diff',
             db: opts.dbKey,
@@ -37,6 +41,7 @@ export async function runDbDiff(opts) {
             ops,
             up: plan.up,
             down: plan.down,
+            migrationFiles,
         };
         const text = ops.length === 0
             ? `  [${opts.dbKey}] 변경 없음 — 스키마와 DB 가 일치합니다.`

package/dist/db/journal.d.ts

@@ -0,0 +1,34 @@
+import { type Kysely } from 'kysely';
+export type MigrationKind = 'file' | 'schema';
+export interface JournalEntry {
+    readonly id: string;
+    readonly kind: MigrationKind;
+    readonly db_key: string;
+    readonly statements: number;
+    readonly summary: string;
+    readonly down_sql: string | null;
+    readonly applied_at: Date;
+}
+/** _gaon_migrations 존재 여부. information_schema 조회로 방언 무관. */
+export declare function journalExists(db: Kysely<any>): Promise<boolean>;
+/**
+ * _gaon_migrations 를 만든다(존재하면 no-op). id/kind/applied_at/db_key/
+ * statements/summary/down_sql — text·varchar·timestamp·integer 는 postgres·
+ * mysql 공통 지원 타입. kind 기본값 'schema' 는 구버전 스키마 호환용.
+ */
+export declare function ensureJournal(db: Kysely<any>): Promise<void>;
+export interface RecordArgs {
+    readonly id: string;
+    readonly kind: MigrationKind;
+    readonly dbKey: string;
+    readonly statements: number;
+    readonly summary: string;
+    readonly downSql: string | null;
+}
+/** 이력 한 행을 남긴다. 호출자가 트랜잭션(trx)을 넘기면 그 안에서 실행된다. */
+export declare function recordEntry(db: Kysely<any>, e: RecordArgs): Promise<void>;
+/** 가장 최근 적용된 이력(롤백 대상). 원장 미존재 시 undefined. */
+export declare function latestEntry(db: Kysely<any>): Promise<JournalEntry | undefined>;
+/** kind='file' 로 적용된 파일명 집합. 원장 미존재 시 빈 집합. */
+export declare function appliedFileMigrations(db: Kysely<any>): Promise<Set<string>>;
+export declare function deleteEntry(db: Kysely<any>, id: string): Promise<void>;

package/dist/db/journal.js

@@ -0,0 +1,71 @@
+// @gaonjs/cli · _gaon_migrations 이력 원장 (결정 39 · v0.16 §4.8)
+//
+// 한 원장에 두 종류를 기록한다:
+//   · kind='file'   — db/migrations/*.ts 파일 리플레이. id=파일명(커넥션 DB
+//                     안에서 유일). down 은 파일 안 down() 을 쓰므로 down_sql=null.
+//   · kind='schema' — schema-diff 배치. id=`<epochMs>-<문수>`. down_sql 에
+//                     롤백 SQL(JSON 배열)을 담아 `migrate down` 이 되돌릴 수 있다.
+//
+// 마이그레이션은 커넥션별로 돈다(§4.5) — 원장도 커넥션 DB 마다 따로 존재한다.
+import { sql } from 'kysely';
+import { MIGRATIONS_TABLE } from '@gaonjs/data';
+/** _gaon_migrations 존재 여부. information_schema 조회로 방언 무관. */
+export 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];
+    return first ? Number(first.n) > 0 : false;
+}
+/**
+ * _gaon_migrations 를 만든다(존재하면 no-op). id/kind/applied_at/db_key/
+ * statements/summary/down_sql — text·varchar·timestamp·integer 는 postgres·
+ * mysql 공통 지원 타입. kind 기본값 'schema' 는 구버전 스키마 호환용.
+ */
+export async function ensureJournal(db) {
+    await sql
+        .raw(`create table if not exists ${MIGRATIONS_TABLE} (` +
+        ` id varchar(255) not null primary key,` +
+        ` kind varchar(16) not null default 'schema',` +
+        ` applied_at timestamp not null,` +
+        ` db_key varchar(64) not null,` +
+        ` statements integer not null,` +
+        ` summary text not null,` +
+        ` down_sql text` +
+        `)`)
+        .execute(db);
+}
+/** 이력 한 행을 남긴다. 호출자가 트랜잭션(trx)을 넘기면 그 안에서 실행된다. */
+export async function recordEntry(db, e) {
+    await sql `
+    insert into ${sql.ref(MIGRATIONS_TABLE)}
+      (id, kind, applied_at, db_key, statements, summary, down_sql)
+    values (${e.id}, ${e.kind}, ${new Date()}, ${e.dbKey}, ${e.statements}, ${e.summary}, ${e.downSql})
+  `.execute(db);
+}
+/** 가장 최근 적용된 이력(롤백 대상). 원장 미존재 시 undefined. */
+export async function latestEntry(db) {
+    if (!(await journalExists(db)))
+        return undefined;
+    const rows = await sql `
+    select id, kind, db_key, statements, summary, down_sql, applied_at
+    from ${sql.ref(MIGRATIONS_TABLE)}
+    order by applied_at desc, id desc
+    limit 1
+  `.execute(db);
+    return rows.rows[0];
+}
+/** kind='file' 로 적용된 파일명 집합. 원장 미존재 시 빈 집합. */
+export async function appliedFileMigrations(db) {
+    if (!(await journalExists(db)))
+        return new Set();
+    const rows = await sql `
+    select id from ${sql.ref(MIGRATIONS_TABLE)} where kind = 'file'
+  `.execute(db);
+    return new Set(rows.rows.map((r) => r.id));
+}
+export async function deleteEntry(db, id) {
+    await sql `delete from ${sql.ref(MIGRATIONS_TABLE)} where id = ${id}`.execute(db);
+}