mega-framework 0.1.6 → 0.1.7

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)가 합친다 —
@@ -27,50 +28,32 @@ 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 { withMigrationLock } from '../core/migration-lock.js'
+import { runMigrateGenerate } from '../core/migration/generate.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 { MegaShutdown, DEFAULT_HARD_KILL_MS } 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 { 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 +77,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 +190,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`)로 무한재귀를 막는다.
@@ -268,25 +290,64 @@ 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()
+
+  // 도움말 — 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
+  }
 
-  // 런타임/부팅 명령은 config 로드 전에 프로젝트 `.env` 를 process.env 로 올린다(ADR-152). 스캐폴드
-  // 생성(new/g)은 대상 프로젝트가 아직 없거나 무관하므로 제외(cwd 의 무관한 .env 로드 방지).
-  if (command !== undefined && !NO_ENV_COMMANDS.has(command)) {
+  // 플러그인 등록 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') {
+/**
+ * `mega start`/`serve` 본체 — dev watch 재실행 또는 부팅+listen(단일/클러스터).
+ * @param {{ port?: string, host?: string, cluster?: string | boolean, watch?: boolean }} 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-182) — `--watch` 면 자신을 `node --watch` 로 재실행한다. 부모는 부팅하지 않고 watcher
     // 자식만 띄운 뒤 그 exit code 를 그대로 반영한다(가드 env 로 무한재귀 방지). 단일 프로세스 강제 +
     // NODE_ENV 미설정 시 development 기본. 시그널은 자식으로 전달해 Ctrl+C 가 watcher 까지 닿게 한다.
-    if (shouldReexecForWatch(flags, process.env)) {
+    if (shouldReexecForWatch({ watch: opts.watch === true }, 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'}]`)
@@ -314,12 +375,12 @@ export async function runCli(argv, { out = console.log, err = console.error, cwd
 
     // 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
@@ -336,7 +397,8 @@ export async function runCli(argv, { out = console.log, err = console.error, cwd
     // 워커 부팅 함수 — 단일/클러스터 모드 공통. 클러스터에선 각 워커 프로세스가 이 함수를 실행한다.
     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 +415,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 +438,185 @@ 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 — 파일 변경 시 자동 재시작(node 내장 --watch 재실행, 단일 프로세스 강제)')
+    .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 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')
+  }
 }
 
 /**
@@ -461,12 +668,12 @@ function wireHostLogger(global, injectedLogger) {
   if (injectedLogger) return injectedLogger
   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
 }
@@ -493,9 +700,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
 }
@@ -516,9 +724,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 +735,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 +764,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 +785,28 @@ 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)}`),
+    }
   const { global, apps } = await loadAndValidateConfig(projectRoot)
   // 플러그인 install 을 어댑터 build 보다 먼저(config-driven driver 제약, boot.js 주석 참조).
   const host = new MegaPluginHost({ logger })
@@ -570,21 +814,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 {