mega-framework 0.1.6 → 0.1.8

package/src/core/migration/generate.js

@@ -0,0 +1,508 @@
+// @ts-check
+/**
+ * `mega migrate:generate` 호스트 (ADR-204) — journal 방식 자동 마이그레이션 생성의 오케스트레이션.
+ *
+ *   1) `apps/<app>/models/**` file-scan → `static schema` 모델 수집(옵트인)
+ *   2) 빌더 실행 → adapter(globalKey) 별 record 그룹화 → 검증(FK 해석 포함)
+ *   3) `.mega/journal/snapshot.json`(직전 상태)과 diff — rename 은 사용자 확인으로만 합성(P1)
+ *   4) dialect(driver 별 — postgres PoC)로 up/down SQL 렌더 → `apps/<app>/migrations/<ts>-<slug>.js` 생성
+ *   5) snapshot 갱신 + `history/<ts>-<slug>.json` 보존
+ *
+ * **DB 연결이 필요 없다** — 적용은 기존 `mega migrate`(러너)가 담당하며 락·트랜잭션·checksum
+ * (ADR-149/190)이 자동 생성 파일에도 동일하게 적용된다(같은 `up(db)/down(db)` 계약).
+ *
+ * @module core/migration/generate
+ */
+import { mkdirSync, writeFileSync, existsSync, readdirSync, renameSync } from 'node:fs'
+import { join } from 'node:path'
+import { MegaConfigError } from '../../errors/config-error.js'
+import { loadAndValidateConfig } from '../config-loader.js'
+import { MIGRATION_FILE_RE } from '../migration-runner.js'
+import { scanSchemaModels } from './model-scan.js'
+import { buildModelRecord } from './schema-builder.js'
+import { validateModels } from './schema-validator.js'
+import { readSnapshot, writeSnapshot, appendHistory, acquireGenerateLock, SNAPSHOT_VERSION } from './journal.js'
+import { diffModels, parseRenamesSpec } from './differ.js'
+import { getDialect, SUPPORTED_DRIVERS } from './dialect-registry.js'
+
+/** 14자리 타임스탬프(UTC) — 러너 파일 규약({@link MIGRATION_FILE_RE})의 prefix. @param {Date} [d] @returns {string} */
+export function migrationTimestamp(d = new Date()) {
+  const p = (/** @type {number} */ n, /** @type {number} */ w = 2) => String(n).padStart(w, '0')
+  return `${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}`
+}
+
+/**
+ * 대상 migrations 디렉토리의 기존 파일 prefix 보다 **항상 큰** 타임스탬프 보장 — 같은 초의 연속
+ * generate(스크립트·테스트)나 시계 역행 시 파일 정렬(=러너 적용 순서)이 slug 사전순으로 붕괴하는
+ * 것을 막는다. 충돌 시 최대 prefix + 1 (숫자 순서만 의미 — 실제 시각일 필요 없음).
+ * @param {string} dir - migrations 디렉토리(부재 가능). @param {string} ts - 후보 14자리 prefix.
+ * @returns {string}
+ */
+function ensureMonotonicTimestamp(dir, ts) {
+  if (!existsSync(dir)) return ts
+  let max = null
+  for (const f of readdirSync(dir)) {
+    const m = f.match(/^(\d{14})-/)
+    if (m !== null && (max === null || m[1] > max)) max = m[1]
+  }
+  if (max === null || ts > max) return ts
+  return String(Number(max) + 1).padStart(14, '0')
+}
+
+/** 임의 문자열 → 파일 규약에 맞는 kebab slug. @param {string} s @returns {string} */
+function toSlug(s) {
+  const slug = s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return slug.length > 0 ? slug : 'schema-update'
+}
+
+/**
+ * ops 로부터 slug 자동 추론 — 변경 종류를 분류해 파일명이 내용을 오도하지 않게 한다
+ * (예: 인덱스만 추가인데 create-* 가 되던 것 교정).
+ * @param {any[]} ops @returns {string}
+ */
+function inferSlug(ops) {
+  const tables = [...new Set(ops.map((o) => o.table))]
+  if (tables.length !== 1) return 'schema-update'
+  const table = tables[0]
+  const kinds = new Set(ops.map((o) => o.kind))
+  // 인덱스 전용이 최우선 — createTable 분류(addIndex 동반 허용)에 잘못 흡수되지 않도록.
+  if ([...kinds].every((k) => k === 'addIndex' || k === 'dropIndex')) {
+    if (!kinds.has('dropIndex')) return toSlug(`add-index-${table}`)
+    if (!kinds.has('addIndex')) return toSlug(`drop-index-${table}`)
+    return toSlug(`index-${table}`)
+  }
+  if (kinds.has('createTable')) return toSlug(`create-${table}`)
+  if (kinds.has('dropTable')) return toSlug(`drop-${table}`)
+  return toSlug(`alter-${table}`)
+}
+
+/** SQL 을 template literal 에 안전하게 싣기 위한 escape. @param {string} sql @returns {string} */
+function escapeForTemplate(sql) {
+  return sql.replaceAll('\\', '\\\\').replaceAll('`', '\\`').replaceAll('${', '\\${')
+}
+
+/**
+ * 마이그레이션 파일 본문 합성 — 러너 계약 `up(db)/down(db)` (ADR-149, 레거시 raw SQL 과 동일
+ * escape hatch 인터페이스 — 생성 후 자유롭게 편집 가능, 편집은 checksum 드리프트로 표면화).
+ * noTransaction 사유('concurrent' | 'rebuild')에 따라 `export const transaction = false` 와
+ * **사유별 헤더**(CONCURRENTLY 안내 vs sqlite rebuild 의 트리거/뷰·foreign_key_check 안내)를 싣는다 —
+ * "적용 전 검토" 가 계약인 도구에서 첫 문단이 오정보면 안 된다(ADR-208 M-3).
+ * mongo dialect(`usesSqlDdl: false`)는 SQL 이 아니라 mongo command JS 문을 받으므로 본문을
+ * `db.query(...)` 래핑 없이 그대로 싣고, `db` 는 mongodb `Db` 인스턴스다(ADR-209). mongo DDL 은
+ * 트랜잭션 안에서 실행할 수 없어 파일은 항상 no-tx('mongo' 사유 헤더)다.
+ * @param {{ base: string, slug: string, ts: string, up: string[], down: string[], noTransaction?: false | 'concurrent' | 'rebuild' | 'mongo', rebuildTriggers?: string[], style?: 'sql' | 'mongo' }} o
+ * @returns {string}
+ */
+function renderMigrationFile({ base, slug, ts, up, down, noTransaction = false, rebuildTriggers = [], style = 'sql' }) {
+  // mongo 문은 이미 완성된 JS 문(await …, 경고 주석 동반 가능) — 들여쓰기만 입힌다.
+  const stmt =
+    style === 'mongo'
+      ? (/** @type {string} */ code) => code.split('\n').map((l) => `  ${l}`).join('\n')
+      : (/** @type {string} */ sql) => `  await db.query(\`${escapeForTemplate(sql)}\`)`
+  // no-tx 사유별 헤더 — 검토자가 읽는 첫 문단이 실제 내용과 맞아야 한다(오정보 금지).
+  /** @type {string} */
+  let noTxBlock = ''
+  if (noTransaction === 'concurrent') {
+    noTxBlock = `
+/**
+ * CONCURRENTLY 는 트랜잭션 안에서 실행할 수 없어 러너의 자동 트랜잭션을 끈다(ADR-205) —
+ * 부분 실패 시 롤백되지 않으므로 본 파일에는 인덱스 변경만 담는다. 실패한 CONCURRENTLY 인덱스는
+ * INVALID 상태로 남을 수 있다 — \`DROP INDEX\` 후 재적용하세요(PostgreSQL 공식 문서).
+ */
+export const transaction = false
+`
+  } else if (noTransaction === 'rebuild') {
+    const triggerLine =
+      rebuildTriggers.length > 0
+        ? ` * ⚠️ 이 DB 에는 재생성 대상 테이블의 **트리거가 존재**한다: [${rebuildTriggers.join(', ')}] —\n *    재생성과 함께 소실되므로 본 파일 끝(또는 후속 raw 마이그레이션)에 재생성 SQL 을 추가하세요.\n`
+        : ` * ⚠️ 재생성 테이블에 트리거가 걸려 있다면 DROP TABLE 과 함께 **소실**된다 — 적용 전\n *    \`SELECT name FROM sqlite_master WHERE type='trigger'\` 로 확인하고 재생성 SQL 을 추가하세요.\n`
+    noTxBlock = `
+/**
+ * sqlite 테이블 재생성(12-step, ADR-207) — \`PRAGMA foreign_keys\` 는 트랜잭션 안에서 변경할 수
+ * 없어 러너의 자동 트랜잭션을 끄고 본문이 자체 BEGIN IMMEDIATE/COMMIT 으로 진행한다.
+${triggerLine} * 테이블을 참조하는 **뷰**가 있으면 RENAME 시점에 재파싱 실패로 적용이 불가하다 — 뷰를 먼저
+ * DROP 하고 적용 후 재생성하세요. \`PRAGMA foreign_key_check\` 는 위반 행을 반환만 하므로(에러 아님)
+ * 적용 후 결과를 확인하세요.
+ */
+export const transaction = false
+`
+  } else if (noTransaction === 'mongo') {
+    noTxBlock = `
+/**
+ * mongo DDL(createCollection/collMod/drop/인덱스)은 multi-document 트랜잭션 안에서 실행할 수
+ * 없어(공식 문서) 러너의 자동 트랜잭션을 끈다 — 중간 실패 시 롤백되지 않으므로 적용 전 검토 필수.
+ * validator 는 기존 도큐먼트를 변환하지 않는다 — 새 required 필드의 backfill(updateMany)은 본문의
+ * 경고 주석 안내를 따라 직접 추가하세요. cross-field 검증($expr)·renameCollection 등 $jsonSchema
+ * 범위 밖 변경도 본 파일 raw 편집으로 추가한다(편집은 checksum 드리프트로 표면화, ADR-209).
+ */
+export const transaction = false
+`
+  }
+  const dbParamDoc =
+    style === 'mongo'
+      ? ` * @param {import('mongodb').Db} db - 대상 DB(native Db — db.collection(...) / db.command(...)).`
+      : ` * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db - 대상 DB 어댑터(트랜잭션 내 query).`
+  const reviewLine =
+    style === 'mongo'
+      ? ' * 적용 전 명령 검토 필수 — 파괴적 변경(// 경고)·backfill 안내 주석이 있으면 직접 확정하세요.'
+      : ' * 적용 전 SQL 검토 필수 — 파괴적 변경(-- 경고)·캐스트(-- TODO) 주석이 있으면 직접 확정하세요.'
+  return `// @ts-check${noTxBlock}
+/**
+ * 마이그레이션 ${slug} (${ts}) — \`mega migrate:generate\` 자동 생성 (ADR-204).
+ * 기준 스냅샷: .mega/journal/history/${base}.json
+${reviewLine}
+ * 적용은 \`mega migrate\`(락·checksum 은 러너 관리, ADR-149/190), 롤백은 \`mega migrate:down\`.
+ *
+${dbParamDoc}
+ * @returns {Promise<void>}
+ */
+export async function up(db) {
+${up.map(stmt).join('\n')}
+}
+
+/**
+${dbParamDoc}
+ * @returns {Promise<void>}
+ */
+export async function down(db) {
+${down.map(stmt).join('\n')}
+}
+`
+}
+
+/**
+ * 기본 rename 확인기 — TTY 면 `prompts` 로 후보를 1쌍씩 확인, 비 TTY 면 확인 불가(null 반환 →
+ * 호출부가 drop+add 유지 + --renames 안내). 테스트는 `confirmRenames` 주입으로 대체.
+ *
+ * @param {Array<{ table: string, dropped: string[], added: string[] }>} candidates
+ * @returns {Promise<Record<string, Record<string, string>> | null>}
+ */
+async function promptRenames(candidates) {
+  if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) return null
+  const { default: prompts } = await import('prompts')
+  // 취소(ESC/Ctrl+C)를 "삭제 확정"으로 흡수하면 안 된다 — onCancel 미지정 시 prompts 는 빈 응답으로
+  // 계속 진행한다. 취소는 generate 전체 중단으로 해석한다(P4 — silent 강행 금지).
+  const onCancel = () => {
+    throw new MegaConfigError('migration.rename_cancelled', 'rename 확인이 취소됐습니다 — migrate:generate 를 중단합니다(파일·journal 무변경).', {
+      details: { candidates },
+    })
+  }
+  /** @type {Record<string, Record<string, string>>} */
+  const out = {}
+  for (const c of candidates) {
+    const remaining = new Set(c.added)
+    for (const dropped of c.dropped) {
+      if (remaining.size === 0) break
+      const { target } = /** @type {{ target: string | null }} */ (await prompts({
+        type: 'select',
+        name: 'target',
+        message: `table '${c.table}': 컬럼 '${dropped}' 삭제가 rename 인가요?`,
+        choices: [
+          { title: `아니오 — '${dropped}' 는 정말 삭제 (데이터 손실)`, value: null },
+          ...[...remaining].map((a) => ({ title: `예 — '${dropped}' → '${a}' rename (데이터 보존)`, value: a })),
+        ],
+      }, { onCancel }))
+      if (typeof target === 'string') {
+        out[c.table] = { ...(out[c.table] ?? {}), [dropped]: target }
+        remaining.delete(target)
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * `mega migrate:generate` 실행.
+ *
+ * @param {string} projectRoot
+ * @typedef {{
+ *   name?: string,
+ *   renames?: string,
+ *   dryRun?: boolean,
+ *   check?: boolean,
+ *   concurrent?: boolean,
+ *   allowDestroyDrops?: boolean,
+ *   adapter?: string,
+ *   app?: string,
+ *   out?: (msg: string) => void,
+ *   logger?: { debug?: Function, info?: Function, warn?: Function },
+ *   confirmRenames?: (candidates: Array<{ table: string, dropped: string[], added: string[] }>) => Promise<Record<string, Record<string, string>> | null>,
+ *   now?: () => Date,
+ * }} GenerateOpts
+ */
+
+/**
+ * @param {string} projectRoot
+ * @param {GenerateOpts} [opts]
+ * @returns {Promise<{ changed: boolean, files: string[], adapters: string[] }>}
+ */
+export async function runMigrateGenerate(projectRoot, opts = {}) {
+  // 락은 config 검증 뒤(잘못된 디렉토리에 .mega 생성 방지) generateInner 가 잡고, 해제는 여기서
+  // 보장한다 — 쓰기 경로(파일·journal)만 락 대상(dry-run/--check 는 읽기 전용 + 원자 rename 덕에 안전).
+  /** @type {{ release: (() => void) | null }} */
+  const lock = { release: null }
+  try {
+    return await generateInner(projectRoot, opts, lock)
+  } finally {
+    lock.release?.()
+  }
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {GenerateOpts} opts
+ * @param {{ release: (() => void) | null }} lock
+ * @returns {Promise<{ changed: boolean, files: string[], adapters: string[] }>}
+ */
+async function generateInner(projectRoot, opts, lock) {
+  const { name, renames, dryRun = false, check = false, concurrent = false, allowDestroyDrops = false, adapter: adapterFilter, app = 'main', out = console.log, logger, confirmRenames = promptRenames, now = () => new Date() } = opts
+
+  const { global, apps } = await loadAndValidateConfig(projectRoot)
+  const appNames = apps.map((/** @type {any} */ a) => a.name)
+  if (!appNames.includes(app)) {
+    throw new MegaConfigError('migration.app_unknown', `--app '${app}' 이 config apps 에 없습니다. 선언됨: [${appNames.join(', ')}].`, {
+      details: { app, declared: appNames },
+    })
+  }
+  const databases = /** @type {Record<string, any>} */ (/** @type {any} */ (global)?.services?.databases ?? {})
+
+  // 1) 스캔 + record 빌드 + 검증(FK 대상 테이블 해석 + dialect 식별자 한도 포함).
+  const scanned = await scanSchemaModels({ projectRoot, appNames })
+  const models = scanned.map((m) => ({ name: m.name, table: m.table, adapter: m.adapter, app: m.app, file: m.file, record: buildModelRecord(m.Model) }))
+  validateModels(models, {
+    // 지원 dialect 만 한도 적용 — 미지원 driver 는 diff 단계의 dialect_unsupported 가 정본 에러
+    // (--adapter 필터로 의도적으로 제외된 그룹을 검증이 먼저 죽이지 않도록).
+    identifierMaxBytesOf: (adapter) => {
+      const driver = databases[adapter]?.driver
+      return typeof driver === 'string' && SUPPORTED_DRIVERS.includes(driver) ? getDialect(driver).identifierMaxBytes : Infinity
+    },
+  })
+  logger?.debug?.({ models: models.length }, 'migrate.generate models scanned')
+
+  // 2) adapter(globalKey) 별 그룹화 + driver 해석(미선언 어댑터는 fail-fast).
+  /** @type {Map<string, { driver: string, models: Array<{ name: string, table: string, record: any }> }>} */
+  const groups = new Map()
+  for (const m of models) {
+    if (!groups.has(m.adapter)) {
+      const driver = databases[m.adapter]?.driver
+      if (typeof driver !== 'string') {
+        throw new MegaConfigError(
+          'migration.adapter_not_declared',
+          `model '${m.name}' 의 adapter '${m.adapter}' 가 services.databases 에 없습니다. 선언됨: [${Object.keys(databases).join(', ') || '(none)'}].`,
+          { details: { model: m.name, adapter: m.adapter, declared: Object.keys(databases) } },
+        )
+      }
+      groups.set(m.adapter, { driver, models: [] })
+    }
+    /** @type {any} */ (groups.get(m.adapter)).models.push({ name: m.name, table: m.table, record: m.record })
+  }
+
+  // 3) 직전 snapshot 과 diff — 대상 adapter = 현재 ∪ 직전(전체 모델 제거도 감지), --adapter 필터 적용.
+  //    쓰기 모드는 읽기 전에 generate 락 선점 — 동시 generate 의 snapshot 갱신 유실 차단.
+  if (!dryRun && !check) lock.release = acquireGenerateLock(projectRoot)
+  const prevSnapshot = readSnapshot(projectRoot)
+  const adapterKeys = [...new Set([...Object.keys(prevSnapshot.adapters), ...groups.keys()])]
+    .filter((k) => adapterFilter === undefined || k === adapterFilter)
+    .sort()
+  if (adapterFilter !== undefined && !adapterKeys.includes(adapterFilter)) {
+    throw new MegaConfigError('migration.adapter_not_declared', `--adapter '${adapterFilter}' 에 schema 모델도 journal 이력도 없습니다.`, {
+      details: { adapter: adapterFilter },
+    })
+  }
+
+  /** @type {Array<{ key: string, driver: string, dialect: Record<string, any>, ops: any[], candidates: any[], currModels: any[] }>} */
+  const diffs = []
+  for (const key of adapterKeys) {
+    const curr = groups.get(key)
+    const prev = prevSnapshot.adapters[key]
+    const driver = curr?.driver ?? prev?.driver
+    const dialect = getDialect(/** @type {string} */ (driver)) // 미지원 driver/contract 위반은 여기서 명시 fail-fast(P7)
+    const { ops, renameCandidates } = diffModels(prev?.models ?? [], curr?.models ?? [], { dialect })
+    diffs.push({ key, driver: /** @type {string} */ (driver), dialect, ops, candidates: renameCandidates, currModels: curr?.models ?? [] })
+  }
+
+  // 4) rename 확정 — --renames 우선, 없으면 confirm(기본: TTY prompt). 확정되면 diff 재계산.
+  //    비인터랙티브에서 확인 수단이 없으면 fail-fast — 모르고 DROP COLUMN(데이터 손실) 마이그레이션이
+  //    생성되는 것을 차단한다. 의식적 drop 의도는 --allow-destroy-drops 로만 통과.
+  const allCandidates = diffs.flatMap((d) => d.candidates)
+  if (allCandidates.length > 0 && !check) {
+    /** @type {Record<string, Record<string, string>> | null} */
+    let mapping = null
+    if (renames !== undefined) {
+      mapping = parseRenamesSpec(renames, allCandidates)
+    } else {
+      mapping = await confirmRenames(allCandidates)
+      if (mapping === null) {
+        if (allowDestroyDrops !== true) {
+          throw new MegaConfigError(
+            'migration.rename_unconfirmed',
+            'rename 후보가 있으나 비인터랙티브 환경이라 확인할 수 없습니다 — 그대로 진행하면 무경고 DROP COLUMN(데이터 손실) 마이그레이션이 생성됩니다. ' +
+              `rename 이면 --renames "${allCandidates.map((c) => `${c.dropped[0]}:${c.added[0]}`).join(',')}" 로 지정하고, ` +
+              '정말 삭제+추가 의도라면 --allow-destroy-drops 로 명시하세요. ' +
+              `후보: ${allCandidates.map((c) => `${c.table}(drop: [${c.dropped.join(', ')}], add: [${c.added.join(', ')}])`).join(' / ')}`,
+            { details: { candidates: allCandidates } },
+          )
+        }
+        out('[migrate:generate] --allow-destroy-drops — rename 후보를 drop+add 로 진행합니다(데이터 손실 주의).')
+        mapping = {}
+      }
+    }
+    for (const d of diffs) {
+      const prev = prevSnapshot.adapters[d.key]
+      const curr = groups.get(d.key)
+      const { ops } = diffModels(prev?.models ?? [], curr?.models ?? [], { renames: mapping, dialect: d.dialect })
+      d.ops = ops
+    }
+  }
+
+  // 모델 제거/table 변경 = 테이블(컬렉션) 전체 DROP — 컬럼 rename 후보(1컬럼)도 게이트하면서
+  // 훨씬 파괴적인 전체 drop 이 무게이트인 비대칭을 해소한다(ADR-210 L-1, 전 dialect 공통).
+  // 파일을 쓰는 모드만 게이트(--check 는 보고 전용, dry-run 은 출력 전용 — CI 프리뷰 무중단).
+  if (!dryRun && !check && allowDestroyDrops !== true) {
+    const dropTables = diffs.flatMap((d) => d.ops.filter((/** @type {any} */ o) => o.kind === 'dropTable').map((/** @type {any} */ o) => `${d.key}:${o.table}`))
+    if (dropTables.length > 0) {
+      throw new MegaConfigError(
+        'migration.drop_unconfirmed',
+        `테이블(컬렉션) 전체 DROP 이 산출됐습니다: [${dropTables.join(', ')}] — 모든 행(도큐먼트)이 영구 삭제되는 ` +
+          '마이그레이션입니다. 의도한 제거라면 --allow-destroy-drops 로 명시하고, 이름 변경 의도라면 모델을 되돌린 뒤 ' +
+          'raw 마이그레이션(rename)으로 처리하세요.',
+        { details: { tables: dropTables } },
+      )
+    }
+  }
+
+  const changed = diffs.filter((d) => d.ops.length > 0)
+  if (changed.length === 0) {
+    out(check ? '[migrate:generate] --check — 드리프트 없음.' : '[migrate:generate] 변경 없음.')
+    return { changed: false, files: [], adapters: [] }
+  }
+
+  // --check: CI 드리프트 게이트 — 변경 요약만 출력하고 파일/journal 무변경. 호출자(CLI)가
+  // changed=true 를 exit non-0 으로 변환한다("모델은 바뀌었는데 generate 안 돌림" 검출).
+  if (check) {
+    for (const d of changed) {
+      const tables = [...new Set(d.ops.map((/** @type {any} */ o) => o.table))]
+      out(`[migrate:generate] --check 드리프트: adapter '${d.key}' — 변경 연산 ${d.ops.length}건 (tables: ${tables.join(', ')})`)
+    }
+    out("[migrate:generate] 모델 schema 와 journal 이 어긋났습니다 — 'mega migrate:generate' 를 실행해 마이그레이션을 생성·커밋하세요.")
+    return { changed: true, files: [], adapters: changed.map((d) => d.key) }
+  }
+
+  // --concurrent: 인덱스 전용 생성만 허용 — CONCURRENTLY 는 트랜잭션 밖 실행이 필요해 파일 전체가
+  // no-tx 가 되므로, 다른(롤백 보호가 필요한) 변경과 섞이면 안전하지 않다.
+  if (concurrent) {
+    for (const d of changed) {
+      if (d.dialect.supportsConcurrentIndex !== true) {
+        throw new MegaConfigError('migration.concurrent_unsupported', `--concurrent: driver '${d.driver}' 는 동시(온라인) 인덱스 생성을 지원하지 않습니다.`, {
+          details: { adapter: d.key, driver: d.driver },
+        })
+      }
+      const nonIndex = d.ops.filter((/** @type {any} */ o) => o.kind !== 'addIndex' && o.kind !== 'dropIndex')
+      if (nonIndex.length > 0) {
+        throw new MegaConfigError(
+          'migration.concurrent_mixed',
+          `--concurrent 는 인덱스 변경만 담을 수 있습니다(파일 전체가 트랜잭션 없이 실행됨). ` +
+            `섞인 변경 ${nonIndex.length}건(${[...new Set(nonIndex.map((/** @type {any} */ o) => o.kind))].join(', ')}) — ` +
+            '먼저 --concurrent 없이 generate→적용으로 모델 변경을 반영한 뒤, 인덱스 추가만 남겨 다시 실행하세요.',
+          { details: { adapter: d.key, nonIndex: nonIndex.map((/** @type {any} */ o) => o.kind) } },
+        )
+      }
+      for (const op of d.ops) if (op.kind === 'addIndex') op.concurrent = true
+    }
+  }
+
+  // 5) 렌더 + 파일/journal 기록 (dry-run 은 출력만). 타임스탬프는 기존 파일보다 항상 크게 —
+  // 같은 초 연속 생성이 적용 순서를 깨지 않도록. crash window 최소화: 본문은 .tmp 로 전부 쓴 뒤
+  // 마이그레이션 파일 rename → history → snapshot 순으로 확정한다(best effort — snapshot 이
+  // 마지막이라 중간 crash 는 "파일은 있고 기준은 옛 상태"로 남고, 다음 generate 의 중복 ops 가
+  // 파일명 충돌·검토 단계에서 드러난다).
+  const ts = ensureMonotonicTimestamp(join(projectRoot, 'apps', app, 'migrations'), migrationTimestamp(now()))
+  /** @type {string[]} */
+  const files = []
+  /** @type {Array<{ tmp: string, file: string, rel: string, d: any, base: string, up: number, down: number }>} */
+  const staged = []
+  for (const d of changed) {
+    const dialect = d.dialect
+    const { up, down } = dialect.renderOps(d.ops)
+    const baseSlug = name !== undefined ? toSlug(name) : inferSlug(d.ops)
+    const slug = changed.length > 1 ? toSlug(`${baseSlug}-${d.key}`) : baseSlug
+    const base = `${ts}-${slug}`
+    if (!MIGRATION_FILE_RE.test(`${base}.js`)) {
+      throw new MegaConfigError('migration.schema_invalid', `생성 파일명 '${base}.js' 이 마이그레이션 파일 규약에 맞지 않습니다.`, {
+        details: { base },
+      })
+    }
+
+    const isMongo = dialect.usesSqlDdl === false
+
+    if (dryRun) {
+      out(`[migrate:generate] (dry-run) adapter '${d.key}' (${d.driver}) — up ${up.length}문 / down ${down.length}문`)
+      out('-- up ----------------------------------------')
+      for (const s of up) out(isMongo ? s : s + ';')
+      out('-- down --------------------------------------')
+      for (const s of down) out(isMongo ? s : s + ';')
+      continue
+    }
+
+    const dir = join(projectRoot, 'apps', app, 'migrations')
+    mkdirSync(dir, { recursive: true })
+    const file = join(dir, `${base}.js`)
+    if (existsSync(file)) {
+      throw new MegaConfigError('migration.schema_invalid', `생성 대상 파일이 이미 존재합니다: ${file}`, { details: { file } })
+    }
+    // no-tx 파일: --concurrent(CONCURRENTLY) 또는 sqlite rebuild(PRAGMA foreign_keys 는 트랜잭션 내
+    // 변경 불가 — 12-step 이 자체 BEGIN IMMEDIATE/COMMIT 보유). 헤더는 사유별로 다르다(M-3).
+    const rebuildOps = d.ops.filter((/** @type {any} */ o) => o.kind === 'rebuildTable')
+    // mongo 는 DDL 이 트랜잭션 불가라 사유가 항상 'mongo'(--concurrent 여부와 무관 — 헤더 오정보 방지).
+    /** @type {false | 'concurrent' | 'rebuild' | 'mongo'} */
+    const noTransaction = isMongo ? 'mongo' : concurrent ? 'concurrent' : rebuildOps.length > 0 ? 'rebuild' : false
+    /** @type {string[]} */
+    let rebuildTriggers = []
+    if (rebuildOps.length > 0 && d.driver === 'sqlite' && typeof d.dialect.inspectRebuildHazards === 'function') {
+      // best-effort 사전 검사 — sqlite 는 파일 DB 라 generate 가 직접 읽을 수 있다(서버 무연결 유지).
+      const tables = rebuildOps.map((/** @type {any} */ o) => o.table)
+      const hazards = await d.dialect.inspectRebuildHazards(databases[d.key]?.filename, tables)
+      if (hazards.conflictViews.length > 0) {
+        throw new MegaConfigError(
+          'migration.rebuild_view_conflict',
+          `sqlite rebuild 는 대상 테이블(${tables.join(', ')})을 참조하는 뷰가 있으면 자동 처리할 수 없습니다 — ` +
+            `RENAME 시점에 뷰 재파싱이 실패해 적용 자체가 불가합니다. 뷰 [${hazards.conflictViews.join(', ')}] 를 ` +
+            'raw 마이그레이션으로 먼저 DROP 하고, 적용 후 재생성하세요.',
+          { details: { tables, views: hazards.conflictViews } },
+        )
+      }
+      rebuildTriggers = hazards.triggers
+      if (rebuildTriggers.length > 0) {
+        out(`[migrate:generate] 경고: 재생성 테이블의 트리거 [${rebuildTriggers.join(', ')}] 는 적용 시 소실됩니다 — 파일 헤더 안내를 따라 재생성 SQL 을 추가하세요.`)
+      }
+    }
+    const tmp = `${file}.tmp`
+    writeFileSync(tmp, renderMigrationFile({ base, slug, ts, up, down, noTransaction, rebuildTriggers, style: isMongo ? 'mongo' : 'sql' }))
+    staged.push({ tmp, file, rel: join('apps', app, 'migrations', `${base}.js`), d, base, up: up.length, down: down.length })
+  }
+
+  if (!dryRun) {
+    // 확정 단계 — rename(원자) 순서: 마이그레이션 파일 → history → snapshot.
+    for (const s of staged) {
+      renameSync(s.tmp, s.file)
+      files.push(s.file)
+      // journal 갱신 — 처리한 adapter 의 그룹을 현재 상태로 교체(모델 0 이면 그룹 제거).
+      if (s.d.currModels.length > 0) {
+        prevSnapshot.adapters[s.d.key] = { driver: s.d.driver, models: s.d.currModels }
+      } else {
+        delete prevSnapshot.adapters[s.d.key]
+      }
+      out(`[migrate:generate] 생성: ${s.rel} (adapter '${s.d.key}', up ${s.up}문 / down ${s.down}문)`)
+      appendHistory(projectRoot, s.base, { version: SNAPSHOT_VERSION, generatedAt: now().toISOString(), adapters: prevSnapshot.adapters })
+    }
+    prevSnapshot.version = SNAPSHOT_VERSION
+    prevSnapshot.generatedAt = now().toISOString()
+    writeSnapshot(projectRoot, prevSnapshot)
+    out(`[migrate:generate] journal 갱신: ${join('.mega', 'journal', 'snapshot.json')}`)
+  }
+
+  return { changed: true, files, adapters: changed.map((d) => d.key) }
+}

package/src/core/migration/journal.js

@@ -0,0 +1,167 @@
+// @ts-check
+/**
+ * Journal snapshot 저장소 (ADR-204) — Drizzle 식 journal 방식의 "직전 상태" 정본.
+ *
+ * - `.mega/journal/snapshot.json` — 마지막 `migrate:generate` 시점의 전 모델 record.
+ *   diff 의 비교 기준이며 **git 추적 대상**(정본 일부 — DB introspection 없이 오프라인 diff).
+ * - `.mega/journal/history/<ts>-<slug>.json` — 각 생성 시점 스냅샷 보존(감사·수동 롤백 참고).
+ *
+ * DB 연결이 전혀 필요 없다 — 파일 시스템만 본다(러너의 파일 스캔·결정론 패턴 정합).
+ *
+ * @module core/migration/journal
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, linkSync } from 'node:fs'
+import { join } from 'node:path'
+import { MegaConfigError } from '../../errors/config-error.js'
+
+/** journal 디렉토리 (projectRoot 상대). */
+export const JOURNAL_DIR = join('.mega', 'journal')
+
+/** snapshot 포맷 버전 — 포맷 변경 시 증가(하위 포맷은 마이그레이션 가이드와 함께 거부). */
+export const SNAPSHOT_VERSION = 1
+
+/**
+ * @typedef {{ version: number, generatedAt: string | null, adapters: Record<string, { driver: string, models: Array<{ name: string, table: string, record: any }> }> }} Snapshot
+ */
+
+/** 빈 스냅샷(첫 generate — 모든 모델이 신규로 diff 됨). @returns {Snapshot} */
+export function emptySnapshot() {
+  return { version: SNAPSHOT_VERSION, generatedAt: null, adapters: {} }
+}
+
+/**
+ * snapshot.json 로드. 부재 시 빈 스냅샷(정상 — 첫 실행). 손상/버전 불일치는 fail-fast —
+ * 잘못된 기준으로 diff 하면 파괴적 SQL 이 잘못 생성된다(P7).
+ *
+ * @param {string} projectRoot
+ * @returns {Snapshot}
+ * @throws {MegaConfigError} `migration.journal_corrupt` | `migration.journal_version`
+ */
+export function readSnapshot(projectRoot) {
+  const file = join(projectRoot, JOURNAL_DIR, 'snapshot.json')
+  if (!existsSync(file)) return emptySnapshot()
+  let parsed
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'))
+  } catch (err) {
+    throw new MegaConfigError(
+      'migration.journal_corrupt',
+      `journal snapshot 파싱 실패: ${file} — 손상된 스냅샷으로 diff 하면 잘못된 SQL 이 생성됩니다. git 이력에서 복원하세요.`,
+      { cause: err, details: { file } },
+    )
+  }
+  if (parsed?.version !== SNAPSHOT_VERSION) {
+    throw new MegaConfigError(
+      'migration.journal_version',
+      `journal snapshot 버전 불일치: ${parsed?.version} (지원: ${SNAPSHOT_VERSION}) — ${file}`,
+      { details: { file, version: parsed?.version ?? null, supported: SNAPSHOT_VERSION } },
+    )
+  }
+  if (parsed.adapters === null || typeof parsed.adapters !== 'object') {
+    throw new MegaConfigError('migration.journal_corrupt', `journal snapshot 형식 오류(adapters 부재): ${file}`, { details: { file } })
+  }
+  return parsed
+}
+
+/**
+ * snapshot.json 기록(+디렉토리 생성). 모델은 이름순 정렬해 직렬화 — diff 노이즈 없는 결정적 출력.
+ * @param {string} projectRoot @param {Snapshot} snapshot
+ * @returns {string} 기록한 파일 경로.
+ */
+export function writeSnapshot(projectRoot, snapshot) {
+  const dir = join(projectRoot, JOURNAL_DIR)
+  mkdirSync(dir, { recursive: true })
+  const normalized = {
+    version: snapshot.version,
+    generatedAt: snapshot.generatedAt,
+    adapters: Object.fromEntries(
+      Object.entries(snapshot.adapters)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, group]) => [key, { driver: group.driver, models: [...group.models].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) }]),
+    ),
+  }
+  const file = join(dir, 'snapshot.json')
+  atomicWrite(file, JSON.stringify(normalized, null, 2) + '\n')
+  return file
+}
+
+/**
+ * temp 파일 기록 후 rename — 같은 파일시스템에서 rename 은 원자적이라 중간 crash 가
+ * 절반 기록된(파싱 불가) snapshot 을 남기지 않는다.
+ * @param {string} file @param {string} content
+ */
+function atomicWrite(file, content) {
+  const tmp = `${file}.tmp`
+  writeFileSync(tmp, content)
+  renameSync(tmp, file)
+}
+
+/** generate 동시 실행 차단 lock 파일 경로. @param {string} projectRoot @returns {string} */
+function lockPath(projectRoot) {
+  return join(projectRoot, JOURNAL_DIR, 'generate.lock')
+}
+
+/**
+ * generate 락 획득 — snapshot 읽기→쓰기 구간(프롬프트 대기 포함)이 길어 동시 generate 가
+ * 한쪽 갱신을 유실시킬 수 있다(CI 병렬 잡 등). `wx` 플래그(존재 시 실패)가 원자적 선점.
+ *
+ * @param {string} projectRoot
+ * @returns {() => void} 해제 함수(finally 에서 호출).
+ * @throws {MegaConfigError} `migration.generate_locked` - 다른 generate 진행 중(또는 stale lock).
+ */
+export function acquireGenerateLock(projectRoot) {
+  const dir = join(projectRoot, JOURNAL_DIR)
+  mkdirSync(dir, { recursive: true })
+  const file = lockPath(projectRoot)
+  // 내용을 임시 파일에 먼저 완성하고 link 로 원자 선점한다 — `wx` 직접 기록은 "파일 생성 ↔ 내용
+  // 기록" 사이의 빈 파일을 패자가 읽어 보유자 PID 가 공란으로 보이는 race 가 있었다(ADR-208 L-2).
+  const tmp = `${file}.${process.pid}.tmp`
+  writeFileSync(tmp, `${process.pid} ${new Date().toISOString()}\n`)
+  try {
+    linkSync(tmp, file)
+  } catch (err) {
+    try {
+      unlinkSync(tmp)
+    } catch (cleanupErr) {
+      // 임시 파일 정리 실패는 비치명적 — 원인 에러(락 충돌 등)가 진짜 신호다.
+      if (/** @type {any} */ (cleanupErr).code !== 'ENOENT') throw cleanupErr
+    }
+    if (/** @type {any} */ (err).code !== 'EEXIST') throw err
+    let holder = ''
+    try {
+      holder = readFileSync(file, 'utf8').trim()
+    } catch {
+      // 막 해제된(삭제 경합) lock — 보유자 정보 없이도 아래 안내는 유효하다.
+      holder = '(unknown)'
+    }
+    throw new MegaConfigError(
+      'migration.generate_locked',
+      `다른 migrate:generate 가 진행 중입니다(lock 보유: ${holder}). 동시 실행은 journal 갱신을 유실시킵니다. ` +
+        `진행 중인 프로세스가 없는데도 반복되면 stale lock — '${file}' 을 삭제 후 재시도하세요.`,
+      { details: { file, holder } },
+    )
+  }
+  unlinkSync(tmp)
+  return () => {
+    try {
+      unlinkSync(file)
+    } catch (err) {
+      if (/** @type {any} */ (err).code !== 'ENOENT') throw err
+      // 이미 사라진 lock(수동 정리 등)은 해제 목적이 달성된 상태 — 무해.
+    }
+  }
+}
+
+/**
+ * history 스냅샷 보존 — 마이그레이션 파일과 같은 base 이름의 .json.
+ * @param {string} projectRoot @param {string} baseName - `<ts>-<slug>` (확장자 없이).
+ * @param {Snapshot} snapshot
+ * @returns {string} 기록한 파일 경로.
+ */
+export function appendHistory(projectRoot, baseName, snapshot) {
+  const dir = join(projectRoot, JOURNAL_DIR, 'history')
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, `${baseName}.json`)
+  atomicWrite(file, JSON.stringify(snapshot, null, 2) + '\n')
+  return file
+}