mega-framework 0.1.6 → 0.1.8

package/src/cli/index.js

@@ -1,14 +1,15 @@
 // @ts-check
 /**
- * `mega` CLI 디스패처 — zero-dep(`process.argv` 직접 파싱) (ADR-123).
+ * `mega` CLI 디스패처 — 전 빌트인 명령을 단일 commander program 으로 파싱한다(ADR-195, ADR-123 개정).
  *
- * 명령 수가 적고 MegaApp/MegaScheduler 의 "정적 클래스 + register" 패턴과 일관되게 commander/yargs
- * 없이 직접 파싱한다(신규 의존성 0). 명령 표:
- *   - `mega start` (별칭 `serve`)  — 부팅 orchestrator(`bootApp`) + HTTP listen + graceful 시그널.
- *   - `mega worker`                — 잡 소비 워커 런타임(`MegaJobWorker`) 호스트 골격.
- *   - `mega scheduler`             — 분산 스케줄러(`MegaScheduler`) 호스트 골격.
- *   - `mega <plugin:command>`      — 플러그인이 `mega.cli.command(...)` 로 등록한 명령 dispatch.
- *   - `mega help` / `--help`       — 도움말.
+ * 명령 표는 {@link buildProgram} 이 정본이다(도움말 자동 생성 — 수기 USAGE 드리프트 제거):
+ *   - `mega start`(별칭 `serve`) / `worker` / `scheduler` / `migrate[:down|:status]` — 런타임 호스트.
+ *   - `mega new` / `generate`(g) / `routes` / `test` / `console` — scaffold/dev(commands/scaffold.js).
+ *   - `mega <plugin:command>` — 빌트인 표({@link BUILTIN_COMMANDS}) 밖 명령은 플러그인 dispatch 로
+ *     fallthrough(ADR-123 계약 유지). `mega help` 가 프로젝트 플러그인 명령을 동적 병기한다.
+ *
+ * `runCli` 는 `process.exit` 를 부르지 않고 exit code 를 반환하며(테스트 가능), commander 가 아닌
+ * 예외(MegaConfigError·부팅 실패)는 bin 으로 전파해 정리 경로(MegaShutdown.now)를 태운다.
  *
  * worker/scheduler 의 **잡·스케줄 등록 소스 = `config.jobs` / `config.schedules`**(정적 배열) + 플러그인
  * `host.listJobs()` / `host.listSchedules()`(동적)를 {@link collectRegistrations}(ADR-123)가 합친다 —
@@ -18,59 +19,35 @@
  *
  * @module cli/index
  */
+// 무거운 런타임 그래프(boot→fastify·OTel·pino·ejs·보안 플러그인, 클러스터, 마이그레이션 러너)는
+// 정적 import 하지 않는다 — `mega help`/`g`/`new` 같은 비부팅 명령이 전체 그래프를 평가해 4배
+// 느려지는 것을 막기 위해, 각 런타임 명령의 action/호스트 함수 내부에서 dynamic import 한다.
+// 모듈 레벨 싱글톤(adapter-manager·MegaShutdown 등)은 dynamic import 도 같은 인스턴스를 본다.
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import os from 'node:os'
 import { spawn as nodeSpawn } from 'node:child_process'
-import { bootApp, prepareRuntime } from '../core/boot.js'
-import { MegaCluster } from '../core/mega-cluster.js'
-import { installPrimaryAggregator, installWorkerResponder } from '../core/cluster-metrics.js'
 import { loadAndValidateConfig } from '../core/config-loader.js'
-import { migrateUp, migrateDown, migrateStatus } from '../core/migration-runner.js'
 import { buildFromGlobalConfig, connectAll, disconnectAll, get as getAdapter } from '../adapters/adapter-manager.js'
+import { MegaDbAdapter } from '../adapters/mega-db-adapter.js'
 import { MegaConfigError } from '../errors/config-error.js'
 import { MegaPluginHost, loadPlugins } from '../lib/mega-plugin.js'
-import { MegaJobWorker } from '../lib/mega-job-worker.js'
-import { MegaScheduler } from '../lib/mega-schedule.js'
-import { MegaShutdown } from '../lib/mega-shutdown.js'
-import { buildLogger } from '../lib/mega-logger.js'
-import * as MegaMetrics from '../lib/mega-metrics.js'
-import { SCAFFOLD_COMMANDS, runScaffoldCommand } from './commands/scaffold.js'
-
-/** CLI 사용법 텍스트. */
-export const USAGE = `mega — MEGA-FRAMEWORK CLI
-
-Usage:
-  mega start [--port N] [--host H] [--cluster N|max] [--watch] [--root DIR]   앱 부팅 + HTTP listen (별칭: serve)
-  mega worker [--root DIR]                         잡 소비 워커 런타임 호스트
-  mega scheduler [--root DIR]                      분산 스케줄러 호스트
-  mega migrate [--db KEY] [--root DIR]             pending 마이그레이션 일괄 적용(up)
-  mega migrate:down [--db KEY]                      마지막 적용 마이그레이션 1개 롤백(down)
-  mega migrate:status [--db KEY]                    적용/미적용 마이그레이션 목록
-  mega new <project> [--force]                     sample/crud 데모앱(14기능) 전체를 스캐폴드
-  mega g <kind> <name> [--app A] [--version vN]    코드+테스트 생성 (별칭: generate)
-                       [--kind K] [--lng L] [--force]
-  mega routes [--root DIR]                          등록 라우트 트리 출력
-  mega test [--root DIR] [-- vitest args...]        vitest 실행
-  mega console [--root DIR]                         앱 컨텍스트 REPL
-  mega <plugin:command> [args...]                  플러그인 등록 CLI 명령 실행
-  mega help                                        이 도움말
-
-generator kinds:
-  app controller channel service model middleware route schedule job worker locale adapter migration
-
-Options:
-  --root DIR    프로젝트 루트(기본: 현재 디렉토리)
-  --port N      listen 포트(start, 기본: server/global 설정 또는 3000)
-  --host H      listen 호스트(start)
-  --cluster X   워커 프로세스 수(start). 정수 N 또는 max(CPU 코어 수). 우선순위:
-                --cluster > MEGA_CLUSTER_WORKERS env > server.cluster config. 1/미지정=단일 프로세스.
-  --watch       dev watch 모드(start). 파일 변경 시 자동 재시작 — node 내장 --watch 로 자신을 재실행한다
-                (nodemon 불요). 단일 프로세스 강제 + NODE_ENV 미설정 시 development. apps/·mega.config.js 감시.
-`
-
-/** 프로젝트 `.env` 를 로드하지 않는 명령 — 스캐폴드 생성(new/g)·도움말. 그 외 런타임/부팅 명령은 로드. */
-const NO_ENV_COMMANDS = new Set(['new', 'g', 'generate', 'help'])
+import { MegaShutdown, DEFAULT_HARD_KILL_MS } from '../lib/mega-shutdown.js'
+import { Command } from 'commander'
+import { registerScaffoldCommands, commanderErrorToExitCode } from './commands/scaffold.js'
+
+/** 빌트인 명령 이름·별칭 전체 — 이 표 밖의 첫 positional 은 플러그인 명령 dispatch 로 fallthrough 한다
+ * (ADR-123 계약 유지). `buildProgram` 의 commander 등록과 동기를 유지할 것. */
+export const BUILTIN_COMMANDS = new Set([
+  'start', 'serve', 'worker', 'scheduler',
+  'migrate', 'migrate:down', 'migrate:status', 'migrate:generate',
+  'new', 'generate', 'g', 'routes', 'test', 'console', 'help',
+])
+
+/** 프로젝트 `.env` 를 로드하지 않는 명령(commander 정식 이름 기준 — 별칭 `g` 는 `generate` 로 해석됨).
+ * 스캐폴드 생성은 대상 프로젝트가 아직 없거나 무관하므로 제외(cwd 의 무관한 .env 로드 방지). `help` 는
+ * runCli 가 commander 진입 전에 처리한다. 그 외 런타임/부팅 명령은 로드(ADR-152). */
+const NO_ENV_COMMANDS = new Set(['new', 'generate'])
 
 /**
  * 프로젝트 루트의 `.env` 를 `process.env` 로 로드한다(파일이 있을 때만). Node 내장
@@ -94,7 +71,8 @@ export function loadProjectEnv(projectRoot, logger) {
 
 /**
  * 인자 토큰을 `{ _: positionals[], flags: {} }` 로 파싱. `--key=value` / `--key value` / `--flag`(=true).
- * zero-dep — 명령 표가 작아 직접 파싱(commander/yargs 회피).
+ * commander 일원화(ADR-195) 이후에도 두 용도로 남는다 — ① runCli 의 사전 스캔(`--root`·명령어 판별,
+ * commander 진입 전), ② 플러그인 CLI 명령 핸들러 인자 계약(`handler({ _, flags })`, 03-api-spec §11).
  * @param {string[]} argv - `process.argv.slice(2)` 형태.
  * @returns {{ _: string[], flags: Record<string, string | boolean> }}
  */
@@ -206,6 +184,44 @@ export function resolveHost(setting) {
   return setting
 }
 
+/**
+ * `--root` 플래그를 검증된 프로젝트 루트로 해석한다(fail-closed — {@link resolveHost} 와 동형, OQ-029②).
+ *
+ * 미지정은 cwd 폴백에 위임하려 `undefined`. 값 없는 베어 `--root`(=`true`)·빈 값 `--root=`(=`''`)은
+ * throw — 빈 루트를 통과시키면 `join('', '.env')`/`loadAndValidateConfig('')` 가 cwd 상대로 silent
+ * 오동작해 운영자가 의도한 루트 지정 실패를 모른다(P4/P7). 비어 있지 않은 문자열은 그대로.
+ *
+ * @param {string | boolean | undefined | null} setting - `--root` 플래그 값.
+ * @returns {string | undefined} 검증된 루트, 또는 미지정이면 `undefined`(cwd 폴백 위임).
+ * @throws {MegaConfigError} `config.invalid_root` — 값 없음/빈 값.
+ */
+export function resolveRoot(setting) {
+  if (setting === undefined || setting === null) return undefined
+  if (typeof setting !== 'string' || setting === '') {
+    throw new MegaConfigError('config.invalid_root', '--root requires a value (e.g. --root ./my-app).', { details: { setting } })
+  }
+  return setting
+}
+
+/**
+ * `--db` 플래그를 검증된 마이그레이션 대상 키로 해석한다(fail-closed — {@link resolveRoot} 와 동형, OQ-029②).
+ *
+ * 미지정은 자동 선택(`resolveMigrationAdapter` 의 유일 db/primary 규칙)에 위임하려 `undefined`. 값 없는
+ * 베어 `--db`(=`true`)·빈 값 `--db=`(=`''`)은 throw — 빈 키가 자동 선택으로 silent 강등되면 운영자가
+ * 지정 실패를 모른 채 다른 db 에 마이그레이션을 적용할 수 있다(P4/P7).
+ *
+ * @param {string | boolean | undefined | null} setting - `--db` 플래그 값.
+ * @returns {string | undefined} 검증된 db 키, 또는 미지정이면 `undefined`(자동 선택 위임).
+ * @throws {MegaConfigError} `config.invalid_db` — 값 없음/빈 값.
+ */
+export function resolveDb(setting) {
+  if (setting === undefined || setting === null) return undefined
+  if (typeof setting !== 'string' || setting === '') {
+    throw new MegaConfigError('config.invalid_db', '--db requires a value (e.g. --db primary).', { details: { setting } })
+  }
+  return setting
+}
+
 /**
  * `mega start --watch` 가 자신을 `node --watch` 로 재실행해야 하는지 (ADR-182). `--watch` 플래그가 있고
  * 아직 watch 하에 재실행되지 않았을 때만 true — 가드 env(`MEGA_WATCH_REEXEC`)로 무한재귀를 막는다.
@@ -218,37 +234,35 @@ export function shouldReexecForWatch(flags, env) {
 }
 
 /**
- * `mega start --watch` → `node --watch … <self> start … --cluster 1` 재실행 명령을 빌드한다 (ADR-182).
+ * `mega start --watch` supervisor 의 **자식 인자**를 빌드한다 (ADR-220, ADR-182 개정).
  *
- * - `--watch` 인자는 **node 플래그**로 옮기고 mega 인자에선 제거한다.
+ * - `--watch`/`--watch-ignore`(값 포함)는 부모(supervisor) 전용 — 자식 인자에서 제거한다
+ *   (가드 env 와 이중 안전으로 무한재귀 방지).
  * - **단일 프로세스 강제**(`--cluster 1`) — 멀티워커 watch 카오스 방지(기존 `--cluster` 값은 무시).
- * - watchPaths 가 있으면 `--watch-path=…`(이게 모듈 그래프 watch 를 **대체**하므로 앱 소스·전역설정 경로를
- *   명시해야 한다 — 실측 확인). 없으면 plain `--watch`(모듈 그래프 폴백).
  *
- * @param {Object} o
- * @param {string[]} o.argv - 원본 mega argv(예: `['start','--watch','--port','3000']`).
- * @param {string[]} o.watchPaths - 감시할 절대경로(존재하는 것만).
- * @param {string} o.selfPath - mega 진입 스크립트(`process.argv[1]`).
- * @param {string} o.execPath - node 바이너리(`process.execPath`).
- * @returns {{ command: string, args: string[] }}
+ * @param {string[]} argv - 원본 mega argv(예: `['start','--watch','--port','3000']`).
+ * @returns {string[]} 자식 `mega` 인자(예: `['start','--port','3000','--cluster','1']`).
  */
-export function buildWatchCommand({ argv, watchPaths, selfPath, execPath }) {
-  const nodeFlags =
-    Array.isArray(watchPaths) && watchPaths.length > 0 ? watchPaths.map((p) => `--watch-path=${p}`) : ['--watch']
-  /** @type {string[]} mega 인자 — `--watch` 제거 + `--cluster`(값 포함) 제거. */
+export function buildWatchChildArgs(argv) {
+  /** @type {string[]} */
   const megaArgs = []
   for (let i = 0; i < argv.length; i++) {
     const tok = argv[i]
     if (tok === '--watch' || tok.startsWith('--watch=')) continue
-    if (tok === '--cluster') {
+    if (tok === '--watch-ignore') {
       if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) i++ // 값 토큰도 건너뜀.
       continue
     }
+    if (tok.startsWith('--watch-ignore=')) continue
+    if (tok === '--cluster') {
+      if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) i++
+      continue
+    }
     if (tok.startsWith('--cluster=')) continue
     megaArgs.push(tok)
   }
   megaArgs.push('--cluster', '1') // 단일 프로세스 강제.
-  return { command: execPath, args: [...nodeFlags, selfPath, ...megaArgs] }
+  return megaArgs
 }
 
 /**
@@ -268,58 +282,106 @@ export function buildWatchCommand({ argv, watchPaths, selfPath, execPath }) {
 export async function runCli(argv, { out = console.log, err = console.error, cwd, logger, spawn = nodeSpawn, selfPath = process.argv[1] } = {}) {
   const { _, flags } = parseArgs(argv)
   const command = _[0]
-  const projectRoot = typeof flags.root === 'string' ? flags.root : (cwd ?? process.cwd())
+  // `--root` 는 fail-closed 검증(OQ-029② — 베어/빈 값은 throw, 미지정만 cwd 폴백).
+  const projectRoot = resolveRoot(flags.root) ?? cwd ?? process.cwd()
 
-  // 런타임/부팅 명령은 config 로드 전에 프로젝트 `.env` 를 process.env 로 올린다(ADR-152). 스캐폴드
-  // 생성(new/g)은 대상 프로젝트가 아직 없거나 무관하므로 제외(cwd 의 무관한 .env 로드 방지).
-  if (command !== undefined && !NO_ENV_COMMANDS.has(command)) {
+  // 도움말 — commander 자동 생성(USAGE) + 프로젝트 플러그인 명령 동적 병기(ADR-195). 명령 없이
+  // 호출(`mega`)은 도움말 + 실패 코드(쉘 스크립트 친화), 명시적 help/`--help` 는 0.
+  // `mega help <command>`(인자 있는 help)·`mega <command> --help` 는 commander 가 명령별 도움말을 낸다.
+  if (command === undefined || (command === 'help' && _.length === 1)) {
+    out(USAGE)
+    await appendPluginCommandsHelp(projectRoot, out, logger)
+    return command === 'help' || flags.help === true ? 0 : 1
+  }
+
+  // 플러그인 등록 CLI 명령 fallthrough(예: `mega sample:ping`) — 빌트인 표 밖의 명령만(ADR-123 계약).
+  // 이름 컨벤션은 `<plugin>:<verb>` 이지만 강제는 아니다 — host 에 등록된 임의 이름을 그대로 조회한다.
+  if (!BUILTIN_COMMANDS.has(command)) {
     loadProjectEnv(projectRoot, logger)
+    /** @type {{ found: boolean, code: number }} */
+    let dispatched
+    try {
+      dispatched = await dispatchPluginCommand(projectRoot, command, { _: _.slice(1), flags }, logger)
+    } catch (e) {
+      // config 부재/오류(프로젝트 밖 등)로 플러그인 확인 자체가 불가 — unknown command 에 원인을 병기해
+      // config 에러로 오도되지 않게 보고한다(F6 audit §2.2-⑥).
+      err(`mega: unknown command '${command}' (플러그인 명령 확인 실패: ${/** @type {any} */ (e).message ?? e}).\n`)
+      err(USAGE)
+      return 1
+    }
+    if (dispatched.found) return dispatched.code
+    err(`mega: unknown command '${command}'.\n`)
+    err(USAGE)
+    return 1
   }
 
-  if (command === undefined || command === 'help' || flags.help === true) {
-    out(USAGE)
-    // 명령 없이 호출(`mega`)은 도움말 + 실패 코드(쉘 스크립트 친화), 명시적 help 는 0.
-    return command === 'help' || flags.help === true ? 0 : 1
+  // 빌트인 명령 — 단일 commander program 으로 파싱·디스패치(ADR-195). action 은 setExit 로 종료 코드를
+  // 보고하고, commander 가 아닌 예외(MegaConfigError·부팅 실패 등)는 그대로 전파해 bin 의 정리 경로
+  // (MegaShutdown.now)를 태운다.
+  let exitCode = 0
+  const program = buildProgram({ argv, out, err, projectRoot, logger, spawn, selfPath, setExit: (c) => (exitCode = c) })
+  try {
+    await program.parseAsync(argv, { from: 'user' })
+    return exitCode
+  } catch (e) {
+    return commanderErrorToExitCode(e, err, { rethrowUnknown: true })
   }
+}
 
-  if (command === 'start' || command === 'serve') {
-    // dev watch (ADR-182) — `--watch` 면 자신을 `node --watch` 로 재실행한다. 부모는 부팅하지 않고 watcher
-    // 자식만 띄운 뒤 그 exit code 를 그대로 반영한다(가드 env 로 무한재귀 방지). 단일 프로세스 강제 +
-    // NODE_ENV 미설정 시 development 기본. 시그널은 자식으로 전달해 Ctrl+C 가 watcher 까지 닿게 한다.
-    if (shouldReexecForWatch(flags, process.env)) {
-      const watchPaths = [join(projectRoot, 'apps'), join(projectRoot, 'mega.config.js')].filter(existsSync)
-      const { command: cmd, args } = buildWatchCommand({ argv, watchPaths, selfPath, execPath: process.execPath })
-      out(`mega: watch mode (single process) — restarting on changes in [${watchPaths.length ? watchPaths.join(', ') : 'module graph'}]`)
-      const child = spawn(cmd, args, {
-        stdio: 'inherit',
-        env: { ...process.env, MEGA_WATCH_REEXEC: '1', NODE_ENV: process.env.NODE_ENV ?? 'development' },
-      })
-      /** @type {NodeJS.Signals[]} */
-      const sigs = ['SIGINT', 'SIGTERM']
-      const forward = (/** @type {NodeJS.Signals} */ sig) => {
-        try {
-          child.kill(sig)
-        } catch {
-          // 자식이 이미 종료 중이면 kill 은 무의미 — 무시(비치명적).
-        }
+/**
+ * `mega start`/`serve` 본체 — dev watch 재실행 또는 부팅+listen(단일/클러스터).
+ * @param {{ port?: string, host?: string, cluster?: string | boolean, watch?: boolean, watchIgnore?: string }} opts - commander 옵션.
+ * @param {{ argv: string[], out: (msg: string) => void, projectRoot: string, logger?: { debug?: Function, info?: Function, warn?: Function }, spawn: Function, selfPath: string }} ctx
+ * @returns {Promise<number>} exit code.
+ */
+async function runStart(opts, { argv, out, projectRoot, logger, spawn, selfPath }) {
+  {
+    // dev watch (ADR-220, ADR-182 개정) — `--watch` 면 자체 supervisor 가 자식(`mega start`)을 띄우고
+    // fs.watch(recursive) + ignore 패턴 + debounce 로 재시작을 조율한다. node 내장 --watch 는 ignore 가
+    // 없어 런타임 산출물(locales saveMissing·업로드·journal)이 재시작 루프를 만들었다. 단일 프로세스
+    // 강제 + NODE_ENV 미설정 시 development 기본 + 가드 env 로 무한재귀 방지는 기존과 동일.
+    if (shouldReexecForWatch({ watch: opts.watch === true }, process.env)) {
+      const { mergeWatchIgnore, startWatchSupervisor, defaultWatchPaths } = await import('./watch.js')
+      // config 의 watch.ignore 는 best-effort — dev 루프는 config 가 깨진 동안에도 살아 있어야
+      // 하므로(고치면 재시작) 로드 실패 시 디폴트 ignore 로 진행하고 이유를 알린다.
+      /** @type {{ ignore?: unknown, ignoreDefaults?: unknown }} */
+      let watchConfig = {}
+      try {
+        const { global } = await loadAndValidateConfig(projectRoot)
+        watchConfig = /** @type {any} */ (global).watch ?? {}
+      } catch (e) {
+        out(`mega: watch — mega.config.js 를 읽지 못해 디폴트 ignore 로 감시합니다(${/** @type {any} */ (e).message?.split('\n')[0] ?? e}).`)
+      }
+      const ignore = mergeWatchIgnore(watchConfig, typeof opts.watchIgnore === 'string' ? opts.watchIgnore : undefined)
+      const watchPaths = defaultWatchPaths(projectRoot)
+      const childArgs = buildWatchChildArgs(argv)
+      out(`mega: watch mode (single process) — watching [${watchPaths.join(', ')}], ignore ${ignore.length} patterns`)
+      if (ignore.length === 0) {
+        // 숨은 디폴트가 없으므로(ADR-220) 미설정은 "모든 변경이 재시작" — locales(saveMissing 자동
+        // 기입)·업로드 같은 런타임 쓰기 영역이 있으면 루프가 날 수 있어 가시화한다(P4).
+        out('mega: watch ignore 가 비어 있습니다 — locales/업로드 등 런타임 쓰기 폴더가 있으면 .env 의 WATCH_IGNORE(또는 config watch.ignore) 설정을 권장합니다.')
       }
-      for (const s of sigs) process.on(s, forward)
-      return await new Promise((resolve) => {
-        child.on('exit', (/** @type {number|null} */ code) => {
-          for (const s of sigs) process.removeListener(s, forward)
-          resolve(typeof code === 'number' ? code : 0)
-        })
+      return await startWatchSupervisor({
+        projectRoot,
+        watchPaths,
+        ignore,
+        out,
+        spawnChild: () =>
+          spawn(process.execPath, [selfPath, ...childArgs], {
+            stdio: 'inherit',
+            env: { ...process.env, MEGA_WATCH_REEXEC: '1', NODE_ENV: process.env.NODE_ENV ?? 'development' },
+          }),
       })
     }
 
     // listen 포트/호스트는 부팅(어댑터 connect) 전에 fail-closed 검증한다 — 잘못된 값을 늦게(listen 시점)
     // cryptic 에러로 만나거나 silent 강등(특권/랜덤 포트)하지 않도록(per ADR-167 후속).
-    const port = resolvePort(flags.port)
-    const host = resolveHost(flags.host)
+    const port = resolvePort(opts.port)
+    const host = resolveHost(opts.host)
 
     // cluster 워커 수 해석(ADR-154) — `--cluster` 플래그 > `MEGA_CLUSTER_WORKERS` env > `server.cluster`
     // config 순. 앞선 소스가 정해지면 config 로드를 생략한다(env/플래그만으로 동작 — port 패턴과 동일).
-    let clusterSetting = flags.cluster ?? process.env.MEGA_CLUSTER_WORKERS
+    let clusterSetting = opts.cluster ?? process.env.MEGA_CLUSTER_WORKERS
     if (clusterSetting === undefined) {
       const { global } = await loadAndValidateConfig(projectRoot)
       clusterSetting = /** @type {any} */ (global).server?.cluster
@@ -333,10 +395,20 @@ export async function runCli(argv, { out = console.log, err = console.error, cwd
       else out(`mega: ${msg}`)
     }
 
+    // 런타임 그래프 lazy 로드 — 부팅 명령에서만 프레임워크 전체를 지불한다(모듈 상단 주석).
+    const [{ bootApp }, { MegaCluster }, { installPrimaryAggregator, installWorkerResponder }, { buildLogger }] =
+      await Promise.all([
+        import('../core/boot.js'),
+        import('../core/mega-cluster.js'),
+        import('../core/cluster-metrics.js'),
+        import('../lib/mega-logger.js'),
+      ])
+
     // 워커 부팅 함수 — 단일/클러스터 모드 공통. 클러스터에선 각 워커 프로세스가 이 함수를 실행한다.
     const bootListen = async () => {
       const { server, appLogger } = await bootApp(projectRoot, { listen: true, port, host, logger })
-      MegaShutdown.register('mega-cli:server', async () => server.close())
+      // 'server' stage — HTTP/WS 수용을 가장 먼저 끊는다(진행 중 요청·WS drain 포함).
+      MegaShutdown.register('mega-cli:server', async () => server.close(), { stage: 'server' })
       MegaShutdown.setupSignals()
       // 클러스터 워커면 메트릭 collect 응답기 설치(ADR-163) — 마스터의 집계 요청에 자기 메트릭 회신.
       // 단일 프로세스면 no-op(cluster.isWorker=false).
@@ -353,7 +425,9 @@ export async function runCli(argv, { out = console.log, err = console.error, cwd
 
     // 클러스터 모드 — 마스터는 워커 N개 fork·respawn·graceful 협응(MegaCluster), 각 워커가 bootApp+listen.
     // Node cluster 가 마스터의 공유 listen 소켓을 워커들에 분배하므로 SO_REUSEPORT 불필요(ADR-030/154).
-    const mega = new MegaCluster({ instances: workers })
+    // 마스터 grace 는 워커 shutdown 예산 상한(MegaShutdown hardKill 60s) + 마진으로 위계화한다 —
+    // 마스터 기본값(30s)을 그대로 쓰면 워커가 hook(어댑터 disconnect 등)을 다 돌기 전에 SIGKILL 된다.
+    const mega = new MegaCluster({ instances: workers, gracePeriodMs: DEFAULT_HARD_KILL_MS + 5_000 })
     // 마스터 조율 로그(SIGINT 수신·워커 종료/respawn 등)를 pino 로(ADR-180). 마스터는 bootApp 을 안 해
     // pino 인스턴스가 없으므로 config 로 직접 만든다. 워커는 bootApp 의 appLogger 를 쓰니 primary 에서만
     // 만들어(워커당 중복 transport worker 회피) start 전에 주입한다.
@@ -374,42 +448,187 @@ export async function runCli(argv, { out = console.log, err = console.error, cwd
     }
     return 0
   }
+}
 
-  if (command === 'worker') {
-    await runWorkerHost(projectRoot, logger)
-    out('mega: worker started')
-    return 0
-  }
+/**
+ * 빌트인 명령 전체를 담은 commander program 을 만든다(ADR-195 — 파서 단일화의 정본).
+ * {@link BUILTIN_COMMANDS} 와 동기 유지. action 은 `process.exit` 없이 `setExit(code)` 로 보고한다.
+ *
+ * @param {object} deps
+ * @param {string[]} deps.argv - 원본 argv(`--watch` 재실행 명령 빌드용).
+ * @param {(msg: string) => void} deps.out
+ * @param {(msg: string) => void} deps.err
+ * @param {string} deps.projectRoot - 이미 `--root` 해석된 기준 디렉토리.
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [deps.logger]
+ * @param {Function} deps.spawn
+ * @param {string} deps.selfPath
+ * @param {(code: number) => void} deps.setExit
+ * @returns {import('commander').Command}
+ */
+function buildProgram({ argv, out, err, projectRoot, logger, spawn, selfPath, setExit }) {
+  const program = new Command()
+  program
+    .name('mega')
+    .description('MEGA-FRAMEWORK CLI')
+    .exitOverride()
+    // 도움말 폭 고정 — 터미널 폭에 따라 줄바꿈이 달라지면 USAGE 가 비결정적이 된다(테스트·문서 안정).
+    .configureHelp({ helpWidth: 100 })
+    .configureOutput({
+      writeOut: (s) => out(s.replace(/\n+$/, '')),
+      writeErr: (s) => err(s.replace(/\n+$/, '')),
+    })
+    .option('--root <dir>', '프로젝트 루트(기본: 현재 디렉토리)')
 
-  if (command === 'scheduler') {
-    await runSchedulerHost(projectRoot, logger)
-    out('mega: scheduler started')
-    return 0
-  }
+  // 프로젝트 `.env` 자동 로드(ADR-152) — 스캐폴드 생성(new/generate)만 제외(NO_ENV_COMMANDS).
+  // preAction 시점이라 각 명령의 config 로드보다 항상 먼저다.
+  program.hook('preAction', (_thisCmd, actionCmd) => {
+    if (!NO_ENV_COMMANDS.has(actionCmd.name())) loadProjectEnv(projectRoot, logger)
+  })
 
-  // 마이그레이션 러너(ADR-149) — 일회성. `migrate:down`/`migrate:status` 는 콜론 포함이라 플러그인
-  // 명령 dispatch 보다 먼저 가로챈다.
-  if (command === 'migrate' || command === 'migrate:down' || command === 'migrate:status') {
-    const direction = command === 'migrate:down' ? 'down' : command === 'migrate:status' ? 'status' : 'up'
-    const dbKey = typeof flags.db === 'string' ? flags.db : undefined
-    await runMigrateHost(projectRoot, { direction, dbKey, logger, out })
-    return 0
-  }
+  program
+    .command('start')
+    .alias('serve')
+    .description('앱 부팅 + HTTP listen')
+    .option('--port <n>', 'listen 포트(기본: server/global 설정 또는 3000)')
+    .option('--host <h>', 'listen 호스트')
+    .option(
+      '--cluster [n]',
+      "워커 프로세스 수 — 정수 N 또는 'max'(CPU 코어 수, 베어 플래그도 max). 우선순위: 플래그 > MEGA_CLUSTER_WORKERS env > server.cluster config. 1/미지정 = 단일 프로세스",
+    )
+    .option('--watch', 'dev watch — 파일 변경 시 자동 재시작(단일 프로세스 강제). locales/views/public/uploads/var/.mega/.env* 등은 디폴트 ignore')
+    .option('--watch-ignore <globs>', 'watch 추가 ignore(콤마 구분 glob, 디폴트에 더해짐). config watch.ignore 와 병합')
+    .action(async (/** @type {any} */ opts) => {
+      setExit(await runStart(opts, { argv, out, projectRoot, logger, spawn, selfPath }))
+    })
+
+  program
+    .command('worker')
+    .description('잡 소비 워커 런타임 호스트')
+    .action(async () => {
+      await runWorkerHost(projectRoot, logger)
+      out('mega: worker started')
+    })
+
+  program
+    .command('scheduler')
+    .description('분산 스케줄러 호스트')
+    .action(async () => {
+      await runSchedulerHost(projectRoot, logger)
+      out('mega: scheduler started')
+    })
 
-  // scaffold/dev 명령군(new/g/routes/test/console)은 commander 로 파싱·디스패치(ADR-142). 런타임 명령
-  // (start/worker/scheduler)·플러그인 명령은 기존 zero-dep 경로(ADR-123) 유지.
-  if (SCAFFOLD_COMMANDS.has(command)) {
-    return runScaffoldCommand(argv, { out, err, projectRoot, logger })
+  // 마이그레이션 러너(ADR-149) — 일회성 호스트 3종. `--db` 는 fail-closed 해석(resolveDb).
+  const migrateAction = (/** @type {'up'|'down'|'status'} */ direction) =>
+    async (/** @type {any} */ opts) => {
+      await runMigrateHost(projectRoot, { direction, dbKey: resolveDb(opts.db), logger, out })
+    }
+  program
+    .command('migrate')
+    .description('pending 마이그레이션 일괄 적용(up)')
+    .option('--db <key>', '대상 db(services.databases 키, 기본: 유일 선언 db 또는 primary)')
+    .action(migrateAction('up'))
+  program
+    .command('migrate:down')
+    .description('마지막 적용 마이그레이션 1개 롤백(down)')
+    .option('--db <key>', '대상 db')
+    .action(migrateAction('down'))
+  program
+    .command('migrate:status')
+    .description('적용/미적용 마이그레이션 목록')
+    .option('--db <key>', '대상 db')
+    .action(migrateAction('status'))
+  // 자동 생성(ADR-204) — journal diff 기반. DB 연결 불요, 적용은 기존 `mega migrate` 가 담당.
+  program
+    .command('migrate:generate')
+    .description('모델 static schema ↔ journal snapshot diff 로 마이그레이션 파일 자동 생성')
+    .argument('[name]', '마이그레이션 이름(kebab-case, 기본: 변경 내용에서 자동 추론)')
+    .option('--renames <map>', '비인터랙티브 rename 매핑 — "old:new[,old2:new2]" (후보 불일치 시 fail-fast)')
+    .option('--dry-run', 'SQL 출력만(파일·journal 변경 없음)')
+    .option('--check', 'CI 드리프트 게이트 — 변경 있으면 exit 1, 파일 생성 없음')
+    .option('--concurrent', '인덱스 전용 생성을 온라인(no-tx)으로 — postgres CONCURRENTLY / maria ALGORITHM=INPLACE,LOCK=NONE / mongo 는 4.2+ 항상 online(표기); sqlite 미지원(거부)')
+    .option('--allow-destroy-drops', '파괴적 산출의 명시 옵트인 — 비인터랙티브 rename 후보의 drop+add 진행 + 모델 제거/table 변경의 테이블(컬렉션) 전체 DROP(ADR-210 게이트)')
+    .option('--adapter <key>', '특정 adapter(services.databases 키)만 처리(기본: 전부)')
+    .option('--app <name>', '마이그레이션 파일을 둘 앱(기본: main)', 'main')
+    .action(async (/** @type {string | undefined} */ name, /** @type {any} */ opts) => {
+      const { runMigrateGenerate } = await import('../core/migration/generate.js')
+      const r = await runMigrateGenerate(projectRoot, {
+        name,
+        renames: opts.renames,
+        dryRun: opts.dryRun === true,
+        check: opts.check === true,
+        concurrent: opts.concurrent === true,
+        allowDestroyDrops: opts.allowDestroyDrops === true,
+        adapter: opts.adapter,
+        app: opts.app,
+        out,
+        logger,
+      })
+      // --check 드리프트 발견은 CI 게이트용 비정상 종료("generate 안 돌림" 검출).
+      if (opts.check === true && r.changed) setExit(1)
+    })
+
+  // scaffold/dev 명령군(new/generate/routes/test/console) — 정의는 commands/scaffold.js 가 정본.
+  // 빌트인이 아닌 generator kind 는 플러그인 scaffold manifest 를 조회한다(`mega.scaffold.register`,
+  // 03-api-spec §11). 이 폴백 경로에 한해 `.env` 를 로드한다 — 플러그인은 대상 프로젝트의 config 에
+  // 선언되므로(NO_ENV_COMMANDS 의 "프로젝트 무관" 전제가 깨짐) process.env 참조가 채워져 있어야 한다.
+  const resolvePluginGenerator = async (/** @type {string} */ kind) => {
+    loadProjectEnv(projectRoot, logger)
+    const { global } = await loadAndValidateConfig(projectRoot)
+    const host = new MegaPluginHost({ logger })
+    await loadPlugins(/** @type {any} */ (global).plugins, host, { projectRoot, logger })
+    return host.getGenerator(kind)
   }
+  registerScaffoldCommands(program, { out, projectRoot, logger, resolvePluginGenerator, setExit })
 
-  // 플러그인 등록 CLI 명령(예: `mega sample:ping`). 명령 이름 컨벤션은 `<plugin>:<verb>` 이지만
-  // 강제는 아니다 — host 에 등록된 임의 이름을 그대로 조회한다.
-  const dispatched = await dispatchPluginCommand(projectRoot, command, { _: _.slice(1), flags }, logger)
-  if (dispatched.found) return dispatched.code
+  return program
+}
 
-  err(`mega: unknown command '${command}'.\n`)
-  err(USAGE)
-  return 1
+/** 도움말 생성용 no-op deps — action 은 호출되지 않으므로 안전. @returns {Parameters<typeof buildProgram>[0]} */
+function helpProgramDeps() {
+  const noop = () => {}
+  return { argv: [], out: noop, err: noop, projectRoot: '', logger: undefined, spawn: nodeSpawn, selfPath: '', setExit: noop }
+}
+
+/** CLI 사용법 텍스트 — commander 자동 생성(ADR-195) + 플러그인 명령 안내. 명령·옵션 정의가 곧 도움말의
+ * 단일 정본이라 수기 USAGE 와의 드리프트가 없다. */
+export const USAGE = `${buildProgram(helpProgramDeps()).helpInformation()}
+플러그인 명령:
+  mega <plugin:command> [args...]  mega.config.js 의 plugins 가 등록한 CLI 명령 실행 (mega help 가 프로젝트 안에서 목록 병기)`
+
+/**
+ * `mega help` 에 프로젝트 플러그인 등록물(CLI 명령 + scaffold generator manifest)을 동적으로 병기한다
+ * (ADR-195/199). 프로젝트 밖/config 오류면 병기만 생략 — help 는 어디서든 떠야 하므로 비치명적이다
+ * (P4: debug 로그로 가시화).
+ * @param {string} projectRoot
+ * @param {(msg: string) => void} out
+ * @param {{ debug?: Function }} [logger]
+ * @returns {Promise<void>}
+ */
+async function appendPluginCommandsHelp(projectRoot, out, logger) {
+  try {
+    const { global } = await loadAndValidateConfig(projectRoot)
+    const host = new MegaPluginHost({ logger })
+    await loadPlugins(/** @type {any} */ (global).plugins, host, { projectRoot, logger })
+    const names = host.listCommands()
+    if (names.length > 0) {
+      out('\n등록된 플러그인 명령:')
+      for (const n of names) {
+        const desc = host.getCommand(n)?.description ?? ''
+        out(`  mega ${n}${desc ? `  ${desc}` : ''}`)
+      }
+    }
+    const generators = host.listGenerators()
+    if (generators.length > 0) {
+      out('\n등록된 플러그인 generator:')
+      for (const g of generators) {
+        const desc = host.getGenerator(g)?.description ?? ''
+        out(`  mega g ${g} <name>${desc ? `  ${desc}` : ''}`)
+      }
+    }
+  } catch (e) {
+    // help 는 프로젝트 밖(config 부재)에서도 떠야 한다 — 플러그인 목록 병기만 생략(비치명적).
+    logger?.debug?.({ err: e }, 'cli.help plugin listing skipped')
+  }
 }
 
 /**
@@ -455,18 +674,19 @@ export function collectRegistrations(global, host, kind) {
  * 주입(테스트)이 있으면 그쪽을 그대로 쓰고 pino 는 만들지 않는다(side-effect 회피).
  * @param {Object} global - global config(`logger` 보유 가능).
  * @param {{ info?: Function, warn?: Function } | undefined} injectedLogger - 주입 로거(테스트) 또는 undefined.
- * @returns {{ info?: Function, warn?: Function } | null} 호스트 로그에 쓸 로거(없으면 null).
+ * @returns {Promise<{ info?: Function, warn?: Function } | null>} 호스트 로그에 쓸 로거(없으면 null).
  */
-function wireHostLogger(global, injectedLogger) {
+async function wireHostLogger(global, injectedLogger) {
   if (injectedLogger) return injectedLogger
+  const { buildLogger } = await import('../lib/mega-logger.js') // pino 그래프 — 호스트 경로에서만 로드.
   const appLogger = buildLogger(/** @type {any} */ (global).logger)
   if (appLogger) {
-    // 종료 시퀀스 로그를 pino 로(ADR-178) + graceful 시 로그 버퍼 flush. flush 훅은 LIFO 상 가장 먼저
-    // 등록 = 가장 나중 실행이라, 다른 hook 들이 로그를 남긴 뒤 마지막에 drain 된다.
+    // 종료 시퀀스 로그를 pino 로(ADR-178) + graceful 시 로그 버퍼 flush. 'logs' stage 라 종료
+    // 시퀀스의 마지막에 drain 된다(다른 stage 의 hook 들이 남긴 로그까지 포함).
     MegaShutdown.setLogger(appLogger)
     MegaShutdown.register('mega-logger', async () => {
       await new Promise((resolve) => appLogger.flush(() => resolve(undefined)))
-    })
+    }, { stage: 'logs' })
   }
   return appLogger
 }
@@ -476,12 +696,17 @@ function wireHostLogger(global, injectedLogger) {
  * 등록 소스 = `config.jobs` + 플러그인 `mega.jobs.register` 분(`collectRegistrations`, ADR-123).
  * @param {string} projectRoot
  * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
- * @returns {Promise<MegaJobWorker>}
+ * @returns {Promise<import('../lib/mega-job-worker.js').MegaJobWorker>}
  */
 export async function runWorkerHost(projectRoot, logger) {
-  // bootApp 과 같은 토대(config → 플러그인 install → 어댑터 connect → ctx).
+  // bootApp 과 같은 토대(config → 플러그인 install → 어댑터 connect → ctx). 런타임 그래프는 lazy.
+  const [{ prepareRuntime }, { MegaJobWorker }, MegaMetrics] = await Promise.all([
+    import('../core/boot.js'),
+    import('../lib/mega-job-worker.js'),
+    import('../lib/mega-metrics.js'),
+  ])
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
-  const log = wireHostLogger(global, logger)
+  const log = await wireHostLogger(global, logger)
   const worker = new MegaJobWorker({ ctx })
   // 잡 메트릭 (ADR-132) — prepareRuntime 이 health.exposeMetrics 시 이미 MegaMetrics.init 했고,
   // 옵트인 OFF 면 subscribeJobs 는 no-op() 을 반환한다. start 전에 구독해 enqueue(dispatch)부터 잡는다. 구독은
@@ -493,9 +718,10 @@ export async function runWorkerHost(projectRoot, logger) {
   for (const JobClass of jobs) worker.register(/** @type {any} */ (JobClass))
   log?.info?.({ count: jobs.length }, 'worker.jobs registered')
   await worker.start()
+  // 'jobs' stage — 새 잡 수신을 멈추고 진행 중 잡을 완료시킨 뒤 어댑터가 끊기게 한다.
   MegaShutdown.register('mega-worker', async () => {
     await worker.stop()
-  })
+  }, { stage: 'jobs' })
   MegaShutdown.setupSignals()
   return worker
 }
@@ -504,11 +730,15 @@ export async function runWorkerHost(projectRoot, logger) {
  * `mega scheduler` 호스트 골격 — config + 어댑터 connect + ctx + `MegaScheduler` 인스턴스 + graceful.
  * @param {string} projectRoot
  * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
- * @returns {Promise<MegaScheduler>}
+ * @returns {Promise<import('../lib/mega-schedule.js').MegaScheduler>}
  */
 export async function runSchedulerHost(projectRoot, logger) {
+  const [{ prepareRuntime }, { MegaScheduler }] = await Promise.all([
+    import('../core/boot.js'),
+    import('../lib/mega-schedule.js'),
+  ])
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
-  const log = wireHostLogger(global, logger)
+  const log = await wireHostLogger(global, logger)
   const scheduler = new MegaScheduler({ ctx })
   // 등록 소스(ADR-123) = config.schedules(정적) + 플러그인 host.listSchedules()(동적). register 가
   // cron 미선언·중복을 부팅 시 fail-fast.
@@ -516,9 +746,10 @@ export async function runSchedulerHost(projectRoot, logger) {
   for (const TaskClass of schedules) scheduler.register(/** @type {any} */ (TaskClass))
   log?.info?.({ count: schedules.length }, 'scheduler.schedules registered')
   scheduler.start()
+  // 'jobs' stage — cron 트리거를 멈추고 실행 중 핸들러를 완료시킨다(ClosingScheduler).
   MegaShutdown.register('mega-scheduler', async () => {
     await scheduler.stop()
-  })
+  }, { stage: 'jobs' })
   MegaShutdown.setupSignals()
   return scheduler
 }
@@ -526,6 +757,11 @@ export async function runSchedulerHost(projectRoot, logger) {
 /**
  * 마이그레이션 대상 DB 어댑터 해석 — `services.databases` 의 globalKey 로 조회한다. `--db <key>` 미지정
  * 시 유일 선언 db, 그게 아니면 `primary`, 둘 다 아니면(다중·미선언) fail-fast 로 명시를 요구한다.
+ *
+ * 러너는 SQL `query` 기반이라(ADR-149 ⑥) `query` 도메인 메서드를 구현하지 않은 어댑터(mongodb 등
+ * Document DB)는 대상이 될 수 없다 — 베이스의 `adapter.not_implemented` 가 늦게 터지는 대신 여기서
+ * `migrate.unsupported_driver` 로 명시 fail-fast 한다(ADR-190).
+ *
  * @param {Object} global - global config.
  * @param {string} [dbKey] - `--db` 플래그.
  * @returns {import('../adapters/mega-adapter.js').MegaAdapter}
@@ -550,7 +786,20 @@ export function resolveMigrationAdapter(global, dbKey) {
       details: { db: key, declared: keys },
     })
   }
-  return getAdapter('db', key)
+  const adapter = getAdapter('db', key)
+  // mongodb 는 SQL 이 아니라 도큐먼트 API 마이그레이션 대상(ADR-209) — 러너 부기는 호스트가
+  // mongo 셈({@link module:core/migration/mongo-migration-db})으로 번역하므로 query 검사를 거치지 않는다.
+  if (dbs[key]?.driver === 'mongodb') return adapter
+  // 구체 어댑터가 query 를 override 하지 않았으면 SQL 마이그레이션 실행 불가(Document DB 등) — 명시 거부.
+  if (/** @type {any} */ (adapter).query === MegaDbAdapter.prototype.query) {
+    throw new MegaConfigError(
+      'migrate.unsupported_driver',
+      `db '${key}' (driver '${dbs[key]?.driver ?? '?'}') 는 SQL query 를 지원하지 않아 마이그레이션 대상이 될 수 없습니다 — ` +
+        '마이그레이션은 postgres/mariadb/sqlite(SQL) + mongodb(도큐먼트 API, ADR-209)만 지원합니다(ADR-149).',
+      { details: { db: key, driver: dbs[key]?.driver ?? null } },
+    )
+  }
+  return adapter
 }
 
 /**
@@ -558,11 +807,35 @@ export function resolveMigrationAdapter(global, dbKey) {
  * disconnect. 워커/wsHub/메트릭은 띄우지 않는다(마이그레이션엔 불필요·이벤트루프 유지 회피).
  * `MegaShutdown.now`(process.exit)를 쓰지 않고 직접 disconnect 해 반환값으로 결과를 돌려준다(테스트 가능).
  *
+ * up/down 은 driver 별 마이그레이션 락({@link module:core/migration-lock}, ADR-190)으로 직렬화한다 —
+ * 동시 `mega migrate`(멀티 인스턴스 배포 훅)의 중복 적용 방지. status 는 읽기 전용이라 락 없이 실행.
+ *
  * @param {string} projectRoot
  * @param {{ direction?: 'up'|'down'|'status', dbKey?: string, logger?: { debug?: Function, info?: Function, warn?: Function }, out?: (msg: string) => void }} [opts]
- * @returns {Promise<{ applied: string[] } | { rolledBack: string|null } | { applied: string[], pending: string[] }>}
+ * @returns {Promise<{ applied: string[] } | { rolledBack: string|null } | { applied: string[], pending: string[], modified: string[] }>}
  */
 export async function runMigrateHost(projectRoot, { direction = 'up', dbKey, logger, out = console.log } = {}) {
+  // bin 경유 실행은 logger 가 없다 — 러너의 운영 경고(checksum 드리프트·no-tx 등)가 무음으로
+  // 사라지지 않도록 CLI 출력으로 폴백한다(배포 훅이 드리프트 상태를 조용히 통과하는 것 방지).
+  // pino 시그니처 양형(`(obj, msg)` / `(msg)`)을 모두 수용한다 — 락 모듈은 문자열 단독으로 호출.
+  const fmt = (/** @type {any} */ o, /** @type {string | undefined} */ msg) => {
+    const text = msg ?? (typeof o === 'string' ? o : '')
+    const suffix = typeof o === 'object' && o !== null && typeof o.migration === 'string' ? ` — ${o.migration}` : ''
+    return `${text}${suffix}`
+  }
+  const log =
+    logger ??
+    {
+      info: (/** @type {any} */ o, /** @type {string} */ msg) => out(`[migrate] ${fmt(o, msg)}`),
+      warn: (/** @type {any} */ o, /** @type {string} */ msg) => out(`[migrate] 경고: ${fmt(o, msg)}`),
+    }
+  // 빌트인 어댑터 배럴을 명시 로드(ADR-150) — migrate 는 boot.js 를 거치지 않고 buildFromGlobalConfig
+  // 를 직접 부르므로, boot 정적 import 가 사라진 lazy CLI 에선 여기서 driver 자기등록을 보장해야 한다.
+  const [{ migrateUp, migrateDown, migrateStatus }, { withMigrationLock }] = await Promise.all([
+    import('../core/migration-runner.js'),
+    import('../core/migration-lock.js'),
+    import('../adapters/index.js'),
+  ])
   const { global, apps } = await loadAndValidateConfig(projectRoot)
   // 플러그인 install 을 어댑터 build 보다 먼저(config-driven driver 제약, boot.js 주석 참조).
   const host = new MegaPluginHost({ logger })
@@ -570,21 +843,30 @@ export async function runMigrateHost(projectRoot, { direction = 'up', dbKey, log
   buildFromGlobalConfig(global)
   await connectAll({ logger })
   try {
-    const db = /** @type {any} */ (resolveMigrationAdapter(global, dbKey))
+    const adapter = /** @type {any} */ (resolveMigrationAdapter(global, dbKey))
+    // mongodb 는 러너 부기 SQL 을 collection 연산으로 번역하는 셈을 끼운다 — 러너/마이그레이션
+    // 파일 모두 이 객체를 받는다(파일의 db 는 사실상 native Db, ADR-209). 락은 어댑터 기준.
+    let db = adapter
+    if (adapter?.getStats?.().driver === 'mongodb') {
+      const { createMongoMigrationDb } = await import('../core/migration/mongo-migration-db.js')
+      db = createMongoMigrationDb(adapter.native)
+    }
     const appNames = apps.map((a) => a.name)
     if (direction === 'status') {
       const s = await migrateStatus({ db, projectRoot, appNames })
       out(`migrations — applied: ${s.applied.length}, pending: ${s.pending.length}`)
       for (const n of s.applied) out(`  [x] ${n}`)
       for (const n of s.pending) out(`  [ ] ${n}`)
+      // 적용 후 수정된(checksum 불일치) 파일 — 실행된 스키마와 어긋난 드리프트 경고(ADR-190).
+      for (const n of s.modified) out(`  [!] ${n} (modified after apply — checksum mismatch)`)
       return s
     }
     if (direction === 'down') {
-      const r = await migrateDown({ db, projectRoot, appNames, log: logger })
+      const r = await withMigrationLock(adapter, () => migrateDown({ db, projectRoot, appNames, log }), { logger: log })
       out(r.rolledBack ? `rolled back: ${r.rolledBack}` : 'nothing to roll back')
       return r
     }
-    const r = await migrateUp({ db, projectRoot, appNames, log: logger })
+    const r = await withMigrationLock(adapter, () => migrateUp({ db, projectRoot, appNames, log }), { logger: log })
     out(r.applied.length ? `applied ${r.applied.length} migration(s): ${r.applied.join(', ')}` : 'no pending migrations')
     return r
   } finally {