mega-framework 0.1.0

package/src/cli/index.js

@@ -0,0 +1,472 @@
+// @ts-check
+/**
+ * `mega` CLI 디스패처 — zero-dep(`process.argv` 직접 파싱) (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`       — 도움말.
+ *
+ * worker/scheduler 의 **잡·스케줄 등록 소스 = `config.jobs` / `config.schedules`**(정적 배열) + 플러그인
+ * `host.listJobs()` / `host.listSchedules()`(동적)를 {@link collectRegistrations}(ADR-123)가 합친다 —
+ * 둘 다 scope-registry 의 GLOBAL_ONLY_KEYS 에 등록된 정식 글로벌 키다. 본 모듈(worker/scheduler 호스트)은
+ * config 로드 + 어댑터 connect + ctx 배선 + 인스턴스 생성·register + graceful shutdown 을 담당한다(CPU
+ * 워커 풀 `config.workers` 는 본 호스트가 아니라 `mega start`/boot 가 `ctx.workers` 로 배선).
+ *
+ * @module cli/index
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import os from 'node:os'
+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 { 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 * 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] [--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> [--views] [--force]           빈 폴더에서 멀티앱 hello world 스캐폴드
+  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/미지정=단일 프로세스.
+`
+
+/** 프로젝트 `.env` 를 로드하지 않는 명령 — 스캐폴드 생성(new/g)·도움말. 그 외 런타임/부팅 명령은 로드. */
+const NO_ENV_COMMANDS = new Set(['new', 'g', 'generate', 'help'])
+
+/**
+ * 프로젝트 루트의 `.env` 를 `process.env` 로 로드한다(파일이 있을 때만). Node 내장
+ * `process.loadEnvFile`(20.6+) 사용 — 신규 dep 0. **이미 설정된 실제 환경변수는 덮어쓰지 않는다**
+ * (`--env-file` 과 동일 우선순위 — 실 env 우선). config(`mega.config.js`)들이 `process.env.X` 를
+ * 참조하고 비밀은 `.env` 에만 두는 컨벤션(CLAUDE.md)을 CLI 가 보장한다(ADR-152). config 로드보다 먼저
+ * 호출해야 `process.env` 참조가 채워진다.
+ *
+ * @param {string} projectRoot - `.env` 를 찾을 프로젝트 루트(`--root` 또는 cwd).
+ * @param {{ debug?: Function }} [logger]
+ * @returns {boolean} 로드했으면 true, `.env` 부재면 false.
+ * @throws {Error} `.env` 가 존재하나 파싱 실패 시(fail-fast — silent 무시 X).
+ */
+export function loadProjectEnv(projectRoot, logger) {
+  const envPath = join(projectRoot, '.env')
+  if (!existsSync(envPath)) return false
+  process.loadEnvFile(envPath)
+  logger?.debug?.({ envPath }, 'cli.env loaded')
+  return true
+}
+
+/**
+ * 인자 토큰을 `{ _: positionals[], flags: {} }` 로 파싱. `--key=value` / `--key value` / `--flag`(=true).
+ * zero-dep — 명령 표가 작아 직접 파싱(commander/yargs 회피).
+ * @param {string[]} argv - `process.argv.slice(2)` 형태.
+ * @returns {{ _: string[], flags: Record<string, string | boolean> }}
+ */
+export function parseArgs(argv) {
+  /** @type {string[]} */
+  const positionals = []
+  /** @type {Record<string, string | boolean>} */
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i]
+    if (tok.startsWith('--')) {
+      const body = tok.slice(2)
+      const eq = body.indexOf('=')
+      if (eq !== -1) {
+        flags[body.slice(0, eq)] = body.slice(eq + 1)
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+        flags[body] = argv[++i]
+      } else {
+        flags[body] = true
+      }
+    } else {
+      positionals.push(tok)
+    }
+  }
+  return { _: positionals, flags }
+}
+
+/**
+ * 사용 가능한 CPU 코어 수(최소 1). `cluster:'max'` 해석에 쓴다 — Node 22+ `availableParallelism`
+ * (컨테이너 cgroup 인식)을 우선하고, 미지원 런타임은 `cpus().length` 로 폴백한다.
+ * @returns {number}
+ */
+function defaultCpuCount() {
+  return Math.max(1, os.availableParallelism?.() ?? os.cpus().length)
+}
+
+/**
+ * cluster 워커 수 설정값을 실제 워커 수로 해석한다(ADR-154 / 04-data-models §MegaServerConfig).
+ *
+ * 유효 도메인: **양의 정수** 또는 **'max'**(= CPU 코어 수). 그 외(0·음수·소수·'max' 아닌 문자열)는
+ * fail-closed 로 throw 한다 — 잘못된 값을 1로 조용히 강등하면 운영자가 클러스터가 안 뜬 줄 모른다(P4/P7).
+ * 워커가 1개로 해석되면(설정 `1`, 또는 단일 코어의 'max') 마스터+워커 2프로세스는 오버헤드만 더하므로
+ * **단일 프로세스(클러스터 비활성)** 로 본다 → `null` 반환.
+ *
+ * @param {string | number | boolean | undefined | null} setting - `--cluster` 플래그 / `MEGA_CLUSTER_WORKERS`
+ *   env / `server.cluster` config 값. 미지정(`undefined`/`null`/`''`)은 단일 프로세스. 베어 `--cluster`(=true)는 'max'.
+ * @param {() => number} [cpuCount] - CPU 코어 수 공급자(테스트 주입용). 기본 {@link defaultCpuCount}.
+ * @returns {number | null} 워커 수(≥2) 또는 단일 프로세스면 `null`.
+ * @throws {MegaConfigError} `config.invalid_cluster` — 양의 정수도 'max' 도 아닌 값.
+ */
+export function resolveClusterWorkers(setting, cpuCount = defaultCpuCount) {
+  if (setting === undefined || setting === null || setting === '') return null
+  let n
+  if (setting === true || setting === 'max' || setting === 'auto') {
+    n = cpuCount()
+  } else {
+    n = typeof setting === 'number' ? setting : Number(setting)
+    if (!Number.isInteger(n) || n < 1) {
+      throw new MegaConfigError(
+        'config.invalid_cluster',
+        `cluster workers must be a positive integer or 'max', got "${setting}".`,
+        { details: { setting } },
+      )
+    }
+  }
+  return n <= 1 ? null : n
+}
+
+/**
+ * `--port` 플래그를 검증된 listen 포트로 해석한다(fail-closed — {@link resolveClusterWorkers} 와 동형).
+ *
+ * 유효 도메인: **0~65535 정수**. 미지정(`undefined`)은 config/기본값에 위임하려 `undefined` 를 돌려준다.
+ * 값 없는 베어 `--port`(=`true`)·빈 값 `--port=`(=`''`)·정수 아님·범위 밖은 throw 한다 — 잘못된 값을
+ * 조용히 강등하면(`Number(true)=1` 특권포트, `Number('')=0` 랜덤포트, `Number('abc')=NaN` 은 어댑터
+ * connect 까지 부팅한 뒤 Node 가 `ERR_SOCKET_BAD_PORT` 로 늦게 throw) 운영자가 의도와 다른 포트를 쓰거나
+ * 늦은 cryptic 에러를 만난다(P4/P7). 명시적 `--port 0`(OS 랜덤 포트)은 정상 값으로 허용한다.
+ *
+ * @param {string | boolean | undefined | null} setting - `--port` 플래그 값.
+ * @returns {number | undefined} 검증된 포트, 또는 미지정이면 `undefined`(config/기본 위임).
+ * @throws {MegaConfigError} `config.invalid_port` — 값 없음/빈 값/정수 아님/범위 밖.
+ */
+export function resolvePort(setting) {
+  if (setting === undefined || setting === null) return undefined
+  // 베어 `--port`(=`true`)·빈 값(`''`) 등 문자열 아닌/빈 입력은 "값 필요" — 숫자 강등 전에 차단.
+  if (typeof setting !== 'string' || setting === '') {
+    throw new MegaConfigError('config.invalid_port', '--port requires a value (e.g. --port 3000).', { details: { setting } })
+  }
+  const n = Number(setting)
+  if (!Number.isInteger(n) || n < 0 || n > 65535) {
+    throw new MegaConfigError('config.invalid_port', `--port must be an integer in [0, 65535], got "${setting}".`, { details: { setting } })
+  }
+  return n
+}
+
+/**
+ * `--host` 플래그를 검증된 listen 호스트로 해석한다(fail-closed). 미지정은 config/기본값에 위임하려
+ * `undefined`. 값 없는 베어 `--host`·빈 값 `--host=`는 throw — 빈 호스트를 `MegaServer` 로 흘리면
+ * Node 가 전 인터페이스(`::`)에 silent bind 해 운영자 의도와 달라진다(P4). 비어 있지 않은 문자열은 그대로.
+ *
+ * @param {string | boolean | undefined | null} setting - `--host` 플래그 값.
+ * @returns {string | undefined} 검증된 호스트, 또는 미지정이면 `undefined`(config/기본 위임).
+ * @throws {MegaConfigError} `config.invalid_host` — 값 없음/빈 값.
+ */
+export function resolveHost(setting) {
+  if (setting === undefined || setting === null) return undefined
+  if (typeof setting !== 'string' || setting === '') {
+    throw new MegaConfigError('config.invalid_host', '--host requires a value (e.g. --host 0.0.0.0).', { details: { setting } })
+  }
+  return setting
+}
+
+/**
+ * `mega` CLI 진입점. 파싱 → 명령 분기. **이 함수는 process.exit 를 호출하지 않는다**(테스트 가능) —
+ * exit code 를 반환하고, bin 래퍼가 `process.exitCode` 로 반영한다.
+ *
+ * @param {string[]} argv - `process.argv.slice(2)`.
+ * @param {Object} [deps] - 테스트 주입용.
+ * @param {(msg: string) => void} [deps.out] - stdout writer(기본 console.log).
+ * @param {(msg: string) => void} [deps.err] - stderr writer(기본 console.error).
+ * @param {string} [deps.cwd] - 기본 projectRoot(기본 process.cwd()).
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [deps.logger]
+ * @returns {Promise<number>} exit code(0=성공, 1=실패/미지정 명령).
+ */
+export async function runCli(argv, { out = console.log, err = console.error, cwd, logger } = {}) {
+  const { _, flags } = parseArgs(argv)
+  const command = _[0]
+  const projectRoot = typeof flags.root === 'string' ? flags.root : (cwd ?? process.cwd())
+
+  // 런타임/부팅 명령은 config 로드 전에 프로젝트 `.env` 를 process.env 로 올린다(ADR-152). 스캐폴드
+  // 생성(new/g)은 대상 프로젝트가 아직 없거나 무관하므로 제외(cwd 의 무관한 .env 로드 방지).
+  if (command !== undefined && !NO_ENV_COMMANDS.has(command)) {
+    loadProjectEnv(projectRoot, logger)
+  }
+
+  if (command === undefined || command === 'help' || flags.help === true) {
+    out(USAGE)
+    // 명령 없이 호출(`mega`)은 도움말 + 실패 코드(쉘 스크립트 친화), 명시적 help 는 0.
+    return command === 'help' || flags.help === true ? 0 : 1
+  }
+
+  if (command === 'start' || command === 'serve') {
+    // listen 포트/호스트는 부팅(어댑터 connect) 전에 fail-closed 검증한다 — 잘못된 값을 늦게(listen 시점)
+    // cryptic 에러로 만나거나 silent 강등(특권/랜덤 포트)하지 않도록(per ADR-167 후속).
+    const port = resolvePort(flags.port)
+    const host = resolveHost(flags.host)
+
+    // cluster 워커 수 해석(ADR-154) — `--cluster` 플래그 > `MEGA_CLUSTER_WORKERS` env > `server.cluster`
+    // config 순. 앞선 소스가 정해지면 config 로드를 생략한다(env/플래그만으로 동작 — port 패턴과 동일).
+    let clusterSetting = flags.cluster ?? process.env.MEGA_CLUSTER_WORKERS
+    if (clusterSetting === undefined) {
+      const { global } = await loadAndValidateConfig(projectRoot)
+      clusterSetting = /** @type {any} */ (global).server?.cluster
+    }
+    const workers = resolveClusterWorkers(clusterSetting)
+
+    // 워커 부팅 함수 — 단일/클러스터 모드 공통. 클러스터에선 각 워커 프로세스가 이 함수를 실행한다.
+    const bootListen = async () => {
+      const { server } = await bootApp(projectRoot, { listen: true, port, host, logger })
+      MegaShutdown.register('mega-cli:server', async () => server.close())
+      MegaShutdown.setupSignals()
+      // 클러스터 워커면 메트릭 collect 응답기 설치(ADR-163) — 마스터의 집계 요청에 자기 메트릭 회신.
+      // 단일 프로세스면 no-op(cluster.isWorker=false).
+      installWorkerResponder()
+      return server
+    }
+
+    if (workers === null) {
+      // 단일 프로세스(클러스터 비활성) — 기존 경로 유지.
+      const server = await bootListen()
+      out(`mega: listening on [${server.hosts.join(', ')}]`)
+      return 0
+    }
+
+    // 클러스터 모드 — 마스터는 워커 N개 fork·respawn·graceful 협응(MegaCluster), 각 워커가 bootApp+listen.
+    // Node cluster 가 마스터의 공유 listen 소켓을 워커들에 분배하므로 SO_REUSEPORT 불필요(ADR-030/154).
+    const mega = new MegaCluster({ instances: workers })
+    await mega.start(async () => {
+      const server = await bootListen()
+      out(`mega: worker ${process.pid} listening on [${server.hosts.join(', ')}]`)
+    })
+    if (mega.isPrimary()) {
+      // 마스터에 메트릭 집계기 설치(ADR-163) — 워커의 /metrics 요청을 받아 전 워커 합산해 회신.
+      installPrimaryAggregator()
+      out(`mega: cluster master ${process.pid} forked ${workers} worker(s)`)
+    }
+    return 0
+  }
+
+  if (command === 'worker') {
+    await runWorkerHost(projectRoot, logger)
+    out('mega: worker started')
+    return 0
+  }
+
+  if (command === 'scheduler') {
+    await runSchedulerHost(projectRoot, logger)
+    out('mega: scheduler started')
+    return 0
+  }
+
+  // 마이그레이션 러너(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
+  }
+
+  // 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 })
+  }
+
+  // 플러그인 등록 CLI 명령(예: `mega sample:ping`). 명령 이름 컨벤션은 `<plugin>:<verb>` 이지만
+  // 강제는 아니다 — host 에 등록된 임의 이름을 그대로 조회한다.
+  const dispatched = await dispatchPluginCommand(projectRoot, command, { _: _.slice(1), flags }, logger)
+  if (dispatched.found) return dispatched.code
+
+  err(`mega: unknown command '${command}'.\n`)
+  err(USAGE)
+  return 1
+}
+
+/**
+ * 플러그인 CLI 명령을 dispatch 한다 — config 로드 → 플러그인 install → `host.getCommand(name)` 조회.
+ * 어댑터 connect 는 하지 않는다(명령 핸들러가 필요하면 자체 처리 — 골격은 가볍게 유지, ADR-123).
+ *
+ * @param {string} projectRoot
+ * @param {string} name - 명령 이름.
+ * @param {{ _: string[], flags: Record<string, string | boolean> }} args - 핸들러에 그대로 전달.
+ * @param {{ debug?: Function }} [logger]
+ * @returns {Promise<{ found: boolean, code: number }>}
+ */
+export async function dispatchPluginCommand(projectRoot, name, args, logger) {
+  const { global } = await loadAndValidateConfig(projectRoot)
+  const host = new MegaPluginHost({ logger })
+  await loadPlugins(/** @type {any} */ (global).plugins, host, { projectRoot, logger })
+  const cmd = host.getCommand(name)
+  if (cmd === undefined) return { found: false, code: 1 }
+  // 핸들러 반환값을 exit code 로 해석(number 면 그대로, 그 외는 0). 에러는 호출자(runCli→bin)가 처리.
+  const result = await cmd.handler(args)
+  return { found: true, code: typeof result === 'number' ? result : 0 }
+}
+
+/**
+ * 잡/스케줄 **등록 소스 흡수**(ADR-123) — `config.<key>`(정적) + 플러그인 `host.list*()`(동적)을 합친다.
+ * 명시 등록만(auto-discovery X, ADR-079 정합). 순수 함수라 단위 검증 가능(register 부작용 분리).
+ * @param {Object} global - global config(`jobs`/`schedules` 배열 보유 가능).
+ * @param {import('../lib/mega-plugin.js').MegaPluginHost} host
+ * @param {'jobs' | 'schedules'} kind
+ * @returns {Function[]} 등록할 클래스 목록(config 먼저, 플러그인 등록분 뒤).
+ */
+export function collectRegistrations(global, host, kind) {
+  const fromConfig = /** @type {any} */ (global)?.[kind]
+  const staticPart = Array.isArray(fromConfig) ? fromConfig : []
+  const dynamicPart = kind === 'jobs' ? host.listJobs() : host.listSchedules()
+  return [...staticPart, ...dynamicPart]
+}
+
+/**
+ * `mega worker` 호스트 골격 — config + 어댑터 connect + ctx + `MegaJobWorker` 인스턴스 + graceful.
+ * 등록 소스 = `config.jobs` + 플러그인 `mega.jobs.register` 분(`collectRegistrations`, ADR-123).
+ * @param {string} projectRoot
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
+ * @returns {Promise<MegaJobWorker>}
+ */
+export async function runWorkerHost(projectRoot, logger) {
+  // bootApp 과 같은 토대(config → 플러그인 install → 어댑터 connect → ctx).
+  const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
+  const worker = new MegaJobWorker({ ctx })
+  // 잡 메트릭 (ADR-132) — prepareRuntime 이 health.exposeMetrics 시 이미 MegaMetrics.init 했고,
+  // 옵트인 OFF 면 subscribeJobs 는 no-op() 을 반환한다. start 전에 구독해 enqueue(dispatch)부터 잡는다. 구독은
+  // MegaMetrics.shutdown(boot 가 'mega-metrics' MegaShutdown hook 으로 등록)에서 일괄 해제되므로 별도 등록 불필요.
+  MegaMetrics.subscribeJobs(worker)
+  // 등록 소스(ADR-123) = config.jobs(정적) + 플러그인 host.listJobs()(동적). register 가 subject/bus
+  // 미선언·중복을 부팅 시 fail-fast.
+  const jobs = collectRegistrations(global, host, 'jobs')
+  for (const JobClass of jobs) worker.register(/** @type {any} */ (JobClass))
+  logger?.info?.({ count: jobs.length }, 'worker.jobs registered')
+  await worker.start()
+  MegaShutdown.register('mega-worker', async () => {
+    await worker.stop()
+  })
+  MegaShutdown.setupSignals()
+  return worker
+}
+
+/**
+ * `mega scheduler` 호스트 골격 — config + 어댑터 connect + ctx + `MegaScheduler` 인스턴스 + graceful.
+ * @param {string} projectRoot
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
+ * @returns {Promise<MegaScheduler>}
+ */
+export async function runSchedulerHost(projectRoot, logger) {
+  const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
+  const scheduler = new MegaScheduler({ ctx })
+  // 등록 소스(ADR-123) = config.schedules(정적) + 플러그인 host.listSchedules()(동적). register 가
+  // cron 미선언·중복을 부팅 시 fail-fast.
+  const schedules = collectRegistrations(global, host, 'schedules')
+  for (const TaskClass of schedules) scheduler.register(/** @type {any} */ (TaskClass))
+  logger?.info?.({ count: schedules.length }, 'scheduler.schedules registered')
+  scheduler.start()
+  MegaShutdown.register('mega-scheduler', async () => {
+    await scheduler.stop()
+  })
+  MegaShutdown.setupSignals()
+  return scheduler
+}
+
+/**
+ * 마이그레이션 대상 DB 어댑터 해석 — `services.databases` 의 globalKey 로 조회한다. `--db <key>` 미지정
+ * 시 유일 선언 db, 그게 아니면 `primary`, 둘 다 아니면(다중·미선언) fail-fast 로 명시를 요구한다.
+ * @param {Object} global - global config.
+ * @param {string} [dbKey] - `--db` 플래그.
+ * @returns {import('../adapters/mega-adapter.js').MegaAdapter}
+ */
+export function resolveMigrationAdapter(global, dbKey) {
+  const dbs = /** @type {any} */ (global)?.services?.databases ?? {}
+  const keys = Object.keys(dbs)
+  let key = dbKey
+  if (!key) {
+    if (keys.length === 1) key = keys[0]
+    else if (Object.prototype.hasOwnProperty.call(dbs, 'primary')) key = 'primary'
+    else {
+      throw new MegaConfigError(
+        'migrate.db_ambiguous',
+        `여러 db 가 선언됨 [${keys.join(', ') || '(none)'}]. 대상은 --db <key> 로 지정하세요.`,
+        { details: { declared: keys } },
+      )
+    }
+  }
+  if (!keys.includes(key)) {
+    throw new MegaConfigError('migrate.db_not_declared', `db '${key}' 가 services.databases 에 없습니다. 선언됨: [${keys.join(', ') || '(none)'}].`, {
+      details: { db: key, declared: keys },
+    })
+  }
+  return getAdapter('db', key)
+}
+
+/**
+ * `mega migrate` 일회성 호스트 — config 로드 → 플러그인 install → DB build/connect → 러너 실행 →
+ * disconnect. 워커/wsHub/메트릭은 띄우지 않는다(마이그레이션엔 불필요·이벤트루프 유지 회피).
+ * `MegaShutdown.now`(process.exit)를 쓰지 않고 직접 disconnect 해 반환값으로 결과를 돌려준다(테스트 가능).
+ *
+ * @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[] }>}
+ */
+export async function runMigrateHost(projectRoot, { direction = 'up', dbKey, logger, out = console.log } = {}) {
+  const { global, apps } = await loadAndValidateConfig(projectRoot)
+  // 플러그인 install 을 어댑터 build 보다 먼저(config-driven driver 제약, boot.js 주석 참조).
+  const host = new MegaPluginHost({ logger })
+  await loadPlugins(/** @type {any} */ (global).plugins, host, { projectRoot, logger })
+  buildFromGlobalConfig(global)
+  await connectAll({ logger })
+  try {
+    const db = /** @type {any} */ (resolveMigrationAdapter(global, dbKey))
+    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}`)
+      return s
+    }
+    if (direction === 'down') {
+      const r = await migrateDown({ db, projectRoot, appNames, log: logger })
+      out(r.rolledBack ? `rolled back: ${r.rolledBack}` : 'nothing to roll back')
+      return r
+    }
+    const r = await migrateUp({ db, projectRoot, appNames, log: logger })
+    out(r.applied.length ? `applied ${r.applied.length} migration(s): ${r.applied.join(', ')}` : 'no pending migrations')
+    return r
+  } finally {
+    await disconnectAll({ logger })
+  }
+}

package/src/cli/template-engine.js

@@ -0,0 +1,72 @@
+// @ts-check
+/**
+ * zero-dep 템플릿 엔진 + 이름 변형 유틸 (ADR-142).
+ *
+ * `templates/<kind>/*.tpl` 파일의 `{{token}}` 자리를 vars 로 치환한다. 외부 템플릿 dep(handlebars 등)
+ * 없이 `process.argv` 파싱(ADR-123)과 같은 정책으로 단순 토큰 치환만 한다 — generator 가 만드는 코드는
+ * 정적 골격이라 조건/루프 같은 복잡한 템플릿 기능이 필요 없다.
+ *
+ * 토큰 형식은 `{{word}}`(이중 중괄호)라 생성 코드의 JSDoc `@param {string}`·객체 리터럴 `{ x }`
+ * (단일 중괄호)와 충돌하지 않는다. 미정의 토큰은 즉시 throw(silent 치환 누락 방지, P4).
+ *
+ * @module cli/template-engine
+ */
+
+/**
+ * 입력 이름을 단어 배열로 분해한다. camelCase 경계와 구분자(`-`, `_`, 공백, `.`)를 모두 단어 경계로
+ * 본다. 예: `'UserProfile'`/`'user-profile'`/`'user_profile'` → `['user','profile']`.
+ * @param {string} raw
+ * @returns {string[]}
+ */
+export function toWords(raw) {
+  return String(raw)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((w) => w.toLowerCase())
+}
+
+/**
+ * 한 단어의 첫 글자를 대문자로.
+ * @param {string} w @returns {string}
+ */
+function capitalize(w) {
+  return w.length === 0 ? w : w[0].toUpperCase() + w.slice(1)
+}
+
+/**
+ * 입력 이름에서 표준 변형 4종을 만든다.
+ * @param {string} raw
+ * @returns {{ kebab: string, pascal: string, camel: string, snake: string, words: string[] }}
+ * @throws {Error} 영숫자 단어가 하나도 없으면(빈/특수문자만) fail-fast.
+ */
+export function nameVariants(raw) {
+  const words = toWords(raw)
+  if (words.length === 0) {
+    throw new Error(`Invalid name '${raw}': must contain at least one alphanumeric character.`)
+  }
+  const pascal = words.map(capitalize).join('')
+  return {
+    words,
+    kebab: words.join('-'),
+    snake: words.join('_'),
+    pascal,
+    camel: pascal[0].toLowerCase() + pascal.slice(1),
+  }
+}
+
+/**
+ * 템플릿 문자열의 `{{token}}` 을 vars 값으로 치환한다.
+ * @param {string} tpl - 템플릿 본문.
+ * @param {Record<string, string>} vars - 토큰 → 값.
+ * @returns {string}
+ * @throws {Error} 템플릿에 vars 에 없는 토큰이 있으면(오타·누락 방지).
+ */
+export function renderTemplate(tpl, vars) {
+  return tpl.replace(/\{\{(\w+)\}\}/g, (_m, key) => {
+    if (!(key in vars)) {
+      throw new Error(`Template token '{{${key}}}' has no value. Provided: [${Object.keys(vars).join(', ')}].`)
+    }
+    return vars[key]
+  })
+}