mega-framework 0.1.7 → 0.1.8

package/src/cli/commands/console-cmd.js

@@ -9,7 +9,6 @@
  * @module cli/commands/console-cmd
  */
 import repl from 'node:repl'
-import { prepareRuntime } from '../../core/boot.js'
 import { MegaShutdown } from '../../lib/mega-shutdown.js'
 
 /**
@@ -38,6 +37,9 @@ export async function startConsole(
   projectRoot,
   { logger, replFactory = defaultReplFactory, out = console.log, shutdown = () => MegaShutdown.now(), setupSignals = (opts) => MegaShutdown.setupSignals(opts) } = {},
 ) {
+  // boot 그래프(fastify·OTel·pino 등)는 콘솔 기동 시점에만 로드 — scaffold.js 가 본 모듈을 정적
+  // import 하므로, 여기서 정적 import 하면 `mega help`/`g` 까지 전체 그래프를 지불하게 된다.
+  const { prepareRuntime } = await import('../../core/boot.js')
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
   out('mega: console ready — globals: ctx, config, mega')
   // prepareRuntime 이 어댑터/워커/wsHub 를 connect 하고 각자 MegaShutdown hook 을 자기등록한다. 정리 없이

package/src/cli/commands/scaffold.js

@@ -13,7 +13,9 @@ import { Command } from 'commander'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { generate, generateFromScaffoldDef, GENERATOR_KINDS } from '../generators/index.js'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { generate, generateFromScaffoldDef, nextAdrNumber, GENERATOR_KINDS } from '../generators/index.js'
 import { scaffoldProject } from './new.js'
 import { runRoutesCommand } from './routes.js'
 import { runTestCommand } from './test-cmd.js'
@@ -31,6 +33,36 @@ function reportFiles(out, r, root) {
   for (const f of r.skipped) out(`  skip    ${f.startsWith(root) ? f.slice(root.length + 1) : f} (exists — use --force)`)
 }
 
+const execFileAsync = promisify(execFile)
+
+/**
+ * `g adr` 의 다음 번호를 **원격 포함**으로 해석한다(ADR-218 — 병렬 task 번호 충돌 회피).
+ * `git fetch origin` 후 `origin/main` 의 `docs/adr/` 파일명에서 번호를 모아 로컬 스캔
+ * ({@link nextAdrNumber})과 합산한다 — 형제 task 가 방금 push 한 ADR 이 로컬 작업트리에 없어도
+ * 번호가 건너뛰어진다. git 부재/오프라인/비-repo 는 로컬 스캔만으로 폴백(경고 1줄 — 스캐폴드는
+ * 어디서든 동작해야 하므로 fail 아님).
+ *
+ * @param {string} projectRoot
+ * @param {(msg: string) => void} out
+ * @returns {Promise<number>}
+ */
+async function resolveAdrNumberWithRemote(projectRoot, out) {
+  /** @type {number[]} */
+  const remote = []
+  try {
+    await execFileAsync('git', ['fetch', 'origin', '--quiet'], { cwd: projectRoot })
+    const { stdout } = await execFileAsync('git', ['ls-tree', '--name-only', 'origin/main', 'docs/adr/'], { cwd: projectRoot })
+    for (const line of stdout.split('\n')) {
+      const m = line.match(/(\d{1,4})-[^/]+\.md$/)
+      if (m) remote.push(Number(m[1]))
+    }
+  } catch (err) {
+    // 오프라인/비-repo/origin 부재 — 로컬 스캔만으로 진행하되 충돌 가능성을 알린다(silent 금지).
+    out(`mega: 원격 ADR 번호 확인 실패(${/** @type {any} */ (err).message?.split('\n')[0] ?? err}) — 로컬 기준으로 번호를 할당합니다.`)
+  }
+  return nextAdrNumber(projectRoot, remote)
+}
+
 /**
  * `g model --adapter <key>` 의 adapter 키/driver 해석 — mega.config.js 의 services.databases 를
  * best-effort 로 읽는다(스캐폴드는 config 가 아직 없는 초기 프로젝트에서도 돌아야 하므로 로드
@@ -109,10 +141,14 @@ export function registerScaffoldCommands(program, { out, projectRoot, logger, re
         /** @type {{ key: string, driver: string | undefined }} */
         let modelAdapter = { key: 'primary', driver: undefined }
         if (kind === 'model') modelAdapter = await resolveModelAdapter(projectRoot, opts.adapter, out)
+        // adr 은 번호를 원격 포함으로 해석한다(병렬 task 충돌 회피, ADR-218).
+        /** @type {number | undefined} */
+        let adrNumber
+        if (kind === 'adr') adrNumber = await resolveAdrNumberWithRemote(projectRoot, out)
         r = generate(
           kind,
           name,
-          { app: opts.app, version: opts.version, kind: opts.kind, lng: opts.lng, force: opts.force === true, adapter: modelAdapter.key, adapterDriver: modelAdapter.driver },
+          { app: opts.app, version: opts.version, kind: opts.kind, lng: opts.lng, force: opts.force === true, adapter: modelAdapter.key, adapterDriver: modelAdapter.driver, adrNumber },
           projectRoot,
         )
       } else {

package/src/cli/generators/index.js

@@ -13,7 +13,7 @@
  *
  * @module cli/generators
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { nameVariants, renderTemplate } from '../template-engine.js'
@@ -36,6 +36,7 @@ export const GENERATOR_KINDS = /** @type {const} */ ([
   'locale',
   'adapter',
   'migration',
+  'adr',
 ])
 
 /**
@@ -185,11 +186,67 @@ export function planArtifacts(kind, rawName, opts, projectRoot) {
     case 'app':
       return planApp(v, projectRoot, base)
 
+    case 'adr':
+      return planAdr(v, opts, projectRoot)
+
     default:
       throw new Error(`Unknown generator kind '${kind}'. Supported: ${GENERATOR_KINDS.join(', ')}.`)
   }
 }
 
+/**
+ * 다음 ADR 번호를 해석한다 — `docs/adr/NNNN-*.md` 파일명 + 레거시 `docs/09` 헤딩(`### ADR-N:`) +
+ * 호출측이 모은 추가 번호(예: `git ls-tree origin/main` 의 원격 파일 — 병렬 task 충돌 회피)의
+ * 최댓값 + 1. 아무 ADR 도 없으면 1.
+ *
+ * @param {string} projectRoot
+ * @param {number[]} [extraNumbers] - 로컬 밖에서 관측한 번호(원격 스캔 등).
+ * @returns {number}
+ */
+export function nextAdrNumber(projectRoot, extraNumbers = []) {
+  let max = 0
+  const adrDir = join(projectRoot, 'docs/adr')
+  if (existsSync(adrDir)) {
+    for (const f of readdirSync(adrDir)) {
+      const m = f.match(/^(\d{1,4})-.+\.md$/)
+      if (m) max = Math.max(max, Number(m[1]))
+    }
+  }
+  const legacy = join(projectRoot, 'docs/09-decisions-and-open-questions.md')
+  if (existsSync(legacy)) {
+    for (const m of readFileSync(legacy, 'utf8').matchAll(/^### ADR-(\d+)/gm)) {
+      max = Math.max(max, Number(m[1]))
+    }
+  }
+  for (const n of extraNumbers) {
+    if (Number.isInteger(n)) max = Math.max(max, n)
+  }
+  return max + 1
+}
+
+/** adr — `docs/adr/NNNN-<name>.md` 1개(코드/테스트 쌍 아님 — 프로젝트 결정 기록 문서, ADR-218).
+ * 번호는 opts.adrNumber(호출측이 원격 포함 해석) 우선, 미지정 시 로컬 스캔({@link nextAdrNumber}).
+ * @param {Variants} v @param {Record<string, any>} opts @param {string} projectRoot
+ * @returns {Artifact[]} */
+function planAdr(v, opts, projectRoot) {
+  const number = Number.isInteger(opts.adrNumber) && opts.adrNumber > 0 ? opts.adrNumber : nextAdrNumber(projectRoot)
+  const padded = String(number).padStart(4, '0')
+  const d = new Date()
+  const p = (/** @type {number} */ n) => String(n).padStart(2, '0')
+  const vars = {
+    number: String(number),
+    title: v.words.join(' '),
+    date: `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`,
+  }
+  return [
+    {
+      outAbs: join(projectRoot, `docs/adr/${padded}-${v.kebab}.md`),
+      role: 'code',
+      content: renderTemplate(readTpl('adr', 'code.tpl'), vars),
+    },
+  ]
+}
+
 /**
  * @typedef {{ kebab: string, pascal: string, camel: string, snake: string, words: string[] }} Variants
  * @typedef {Record<string, string>} BaseVars

package/src/cli/index.js

@@ -19,26 +19,20 @@
  *
  * @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 { 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, 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 { Command } from 'commander'
 import { registerScaffoldCommands, commanderErrorToExitCode } from './commands/scaffold.js'
 
@@ -240,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
 }
 
 /**
@@ -338,38 +330,47 @@ export async function runCli(argv, { out = console.log, err = console.error, cwd
 
 /**
  * `mega start`/`serve` 본체 — dev watch 재실행 또는 부팅+listen(단일/클러스터).
- * @param {{ port?: string, host?: string, cluster?: string | boolean, watch?: boolean }} opts - commander 옵션.
+ * @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-182) — `--watch` 면 자신을 `node --watch` 로 재실행한다. 부모는 부팅하지 않고 watcher
-    // 자식만 띄운 뒤 그 exit code 를 그대로 반영한다(가드 env 로 무한재귀 방지). 단일 프로세스 강제 +
-    // NODE_ENV 미설정 시 development 기본. 시그널은 자식으로 전달해 Ctrl+C 가 watcher 까지 닿게 한다.
+    // 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 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 은 무의미 — 무시(비치명적).
-        }
+      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' },
+          }),
       })
     }
 
@@ -394,6 +395,15 @@ async function runStart(opts, { argv, out, projectRoot, logger, spawn, selfPath
       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 })
@@ -485,7 +495,8 @@ function buildProgram({ argv, out, err, projectRoot, logger, spawn, selfPath, se
       '--cluster [n]',
       "워커 프로세스 수 — 정수 N 또는 'max'(CPU 코어 수, 베어 플래그도 max). 우선순위: 플래그 > MEGA_CLUSTER_WORKERS env > server.cluster config. 1/미지정 = 단일 프로세스",
     )
-    .option('--watch', 'dev watch — 파일 변경 시 자동 재시작(node 내장 --watch 재실행, 단일 프로세스 강제)')
+    .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 }))
     })
@@ -539,6 +550,7 @@ function buildProgram({ argv, out, err, projectRoot, logger, spawn, selfPath, se
     .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,
@@ -662,10 +674,11 @@ 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. 'logs' stage 라 종료
@@ -683,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)부터 잡는다. 구독은
@@ -712,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.
@@ -807,6 +829,13 @@ export async function runMigrateHost(projectRoot, { direction = 'up', dbKey, log
       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 })

package/src/cli/watch.js

@@ -0,0 +1,188 @@
+// @ts-check
+/**
+ * `mega start --watch` 의 dev watch supervisor (ADR-220, ADR-182 개정).
+ *
+ * Node 내장 `--watch-path` 재실행(구 ADR-182)은 **ignore 패턴이 없어** 런타임이 쓰는 파일까지
+ * 재시작을 유발했다 — dev 의 i18n saveMissing 이 `locales/*.json` 자동 기입(재시작 무한 루프),
+ * 업로드가 `uploads/`/`var/` 에 파일 저장(사용자 입력이 서버를 재시작), 마이그레이션 generate 가
+ * `.mega/` journal 갱신. 본 모듈이 그 재실행을 **자체 supervisor**(fs.watch recursive + 미니 glob
+ * ignore + debounce + SIGTERM respawn)로 대체한다 — 신규 dep 0(chokidar 미도입: 필요한 매칭이
+ * `**`/`*`/`?` 수준이라 풀스펙 glob 라이브러리가 과함).
+ *
+ * ignore 합성 = config `watch.ignore` + CLI `--watch-ignore`. **숨은 코드 디폴트는 없다**(사용자
+ * 결정 — 개발자가 보지 못하는 목록은 폴더명이 다른 프로젝트에서 오히려 혼란) — 권장 목록은 스캐폴드
+ * `.env` 의 `WATCH_IGNORE` 가 실값으로 명시하고 `mega.config.js` 가 읽어 `watch.ignore` 로 넘긴다.
+ * ignore 0 이면 supervisor 가 기동 시 경고 1줄을 낸다(locales saveMissing 루프 등 위험 가시화).
+ *
+ * @module cli/watch
+ */
+import { watch as fsWatch, existsSync, statSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+
+/**
+ * 미니 glob → RegExp. 지원: 더블스타+슬래시(0개 이상의 디렉토리), 더블스타(경로 전체), `*`(세그먼트
+ * 내), `?`(1글자). 그 외 문자는 리터럴(정규식 특수문자 escape). 매칭 대상은 루트 상대 POSIX 경로
+ * 전체(^…$). 패턴 예시는 스캐폴드 `.env` 의 `WATCH_IGNORE` 참조 — JS 블록 주석 안에는
+ * 더블스타+슬래시 시퀀스를 쓸 수 없어(주석 조기 종료) 여기 직접 못 적는다.
+ *
+ * @param {string} pattern - glob 패턴(예 `.env.*`).
+ * @returns {RegExp}
+ */
+export function globToRegExp(pattern) {
+  let re = ''
+  let i = 0
+  while (i < pattern.length) {
+    const ch = pattern[i]
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        // `**/` 는 0개 이상의 디렉토리(루트 레벨 포함), 그 외 `**` 는 임의 문자열.
+        if (pattern[i + 2] === '/') {
+          re += '(?:.*/)?'
+          i += 3
+        } else {
+          re += '.*'
+          i += 2
+        }
+      } else {
+        re += '[^/]*'
+        i += 1
+      }
+    } else if (ch === '?') {
+      re += '[^/]'
+      i += 1
+    } else {
+      re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      i += 1
+    }
+  }
+  return new RegExp(`^${re}$`)
+}
+
+/**
+ * ignore 패턴 합성 — config(`watch.ignore`) + CLI(`--watch-ignore a,b`). 숨은 디폴트 없음(모듈
+ * docstring 참조). 잘못된 모양은 fail-fast(silent 무시 금지).
+ *
+ * @param {{ ignore?: unknown }} [watchConfig] - mega.config.js 의 `watch`.
+ * @param {string | undefined} [cliIgnore] - `--watch-ignore` 값(콤마 구분).
+ * @returns {string[]}
+ * @throws {TypeError} config `watch.ignore` 가 문자열 배열이 아닐 때.
+ */
+export function mergeWatchIgnore(watchConfig = {}, cliIgnore = undefined) {
+  /** @type {string[]} */
+  const merged = []
+  if (watchConfig.ignore !== undefined) {
+    if (!Array.isArray(watchConfig.ignore) || watchConfig.ignore.some((p) => typeof p !== 'string' || p.length === 0)) {
+      throw new TypeError('config watch.ignore 는 비어있지 않은 문자열 배열이어야 합니다.')
+    }
+    merged.push(...watchConfig.ignore)
+  }
+  if (typeof cliIgnore === 'string' && cliIgnore.length > 0) {
+    merged.push(...cliIgnore.split(',').map((p) => p.trim()).filter((p) => p.length > 0))
+  }
+  return merged
+}
+
+/**
+ * 루트 상대 경로가 ignore 에 걸리는지 (Boolean — `is*`).
+ * @param {string} rel - 루트 상대 POSIX 경로(예 `apps/main/locales/ko.json`).
+ * @param {RegExp[]} regexps - {@link globToRegExp} 컴파일 결과.
+ * @returns {boolean}
+ */
+export function isIgnoredPath(rel, regexps) {
+  return regexps.some((r) => r.test(rel))
+}
+
+/**
+ * watch supervisor — 감시 경로의 변경(ignore 통과분)을 debounce 후 자식(`mega start`)을
+ * SIGTERM → respawn 한다. 자식이 스스로 죽으면(crash) 재시작하지 않고 다음 변경을 기다린다
+ * (crash-loop 방지 — nodemon 의 "app crashed - waiting for file changes" 와 동형).
+ *
+ * @param {object} o
+ * @param {string} o.projectRoot
+ * @param {string[]} o.watchPaths - 감시할 절대경로(존재하는 것만 — 호출측이 필터).
+ * @param {string[]} o.ignore - glob 패턴 목록.
+ * @param {() => import('node:child_process').ChildProcess} o.spawnChild - 자식 기동 팩토리(주입 — 테스트).
+ * @param {(msg: string) => void} o.out
+ * @param {number} [o.debounceMs=500] - 연속 변경 디바운스.
+ * @param {(dir: string, opts: object, cb: (event: string, filename: string | Buffer | null) => void) => { close(): void }} [o.watchFn] -
+ *   fs.watch 주입(테스트). 기본 node:fs watch.
+ * @returns {Promise<number>} 부모(supervisor)의 exit code — SIGINT/SIGTERM 수신 시 자식 정리 후 0.
+ */
+export function startWatchSupervisor({ projectRoot, watchPaths, ignore, spawnChild, out, debounceMs = 500, watchFn = /** @type {any} */ (fsWatch) }) {
+  const regexps = ignore.map(globToRegExp)
+  /** @type {import('node:child_process').ChildProcess | null} */
+  let child = null
+  /** @type {NodeJS.Timeout | null} */
+  let pending = null
+  let shuttingDown = false
+  let restarting = false
+
+  const start = () => {
+    child = spawnChild()
+    child.on('exit', (code, signal) => {
+      if (shuttingDown) return
+      if (restarting) {
+        restarting = false
+        start()
+        return
+      }
+      // 자식이 스스로 종료(crash/정상) — 재시작 폭주 대신 다음 변경 대기(P4: 이유 출력).
+      out(`mega: app exited (code=${code ?? `signal:${signal}`}) — waiting for file changes before restart`)
+      child = null
+    })
+  }
+
+  const scheduleRestart = (/** @type {string} */ rel) => {
+    if (pending) clearTimeout(pending)
+    pending = setTimeout(() => {
+      pending = null
+      out(`mega: restarting due to changes (${rel})`)
+      if (child && child.exitCode === null && !child.killed) {
+        restarting = true
+        child.kill('SIGTERM') // graceful — exit 핸들러가 respawn.
+      } else {
+        start() // crash 후 대기 상태 — 변경으로 재기동.
+      }
+    }, debounceMs)
+  }
+
+  /** @type {Array<{ close(): void }>} */
+  const watchers = []
+  for (const abs of watchPaths) {
+    const isDir = statSync(abs).isDirectory()
+    const watcher = watchFn(abs, { recursive: isDir }, (_event, filename) => {
+      // filename 은 감시 루트 상대(파일 watch 면 basename) — 루트 상대로 정규화해 ignore 매칭.
+      const name = typeof filename === 'string' ? filename : (filename ? String(filename) : '')
+      const rel = relative(projectRoot, isDir ? join(abs, name) : abs).split(sep).join('/')
+      if (isIgnoredPath(rel, regexps)) return
+      scheduleRestart(rel)
+    })
+    watchers.push(watcher)
+  }
+
+  start()
+
+  return new Promise((resolve) => {
+    /** @type {NodeJS.Signals[]} */
+    const sigs = ['SIGINT', 'SIGTERM']
+    const onSignal = () => {
+      shuttingDown = true
+      if (pending) clearTimeout(pending)
+      for (const w of watchers) w.close()
+      for (const s of sigs) process.removeListener(s, onSignal)
+      if (child && child.exitCode === null && !child.killed) {
+        child.once('exit', () => resolve(0))
+        child.kill('SIGTERM')
+      } else {
+        resolve(0)
+      }
+    }
+    for (const s of sigs) process.on(s, onSignal)
+  })
+}
+
+/** {@link startWatchSupervisor} 의 watchPaths 기본 집합 — 존재하는 것만.
+ * @param {string} projectRoot @returns {string[]} */
+export function defaultWatchPaths(projectRoot) {
+  return [join(projectRoot, 'apps'), join(projectRoot, 'shared'), join(projectRoot, 'mega.config.js')].filter(existsSync)
+}

package/src/core/ajv-mapper.js

@@ -74,7 +74,9 @@ function ajvItemToDetail(e) {
   if (e.keyword === 'required' && missing) {
     field = field ? `${field}.${missing}` : missing
   }
-  const isSensitive = SENSITIVE_FIELD_RE.test(field) || SENSITIVE_FIELD_RE.test(missing)
+  // 정규식 1회 실행 (G1 M-2, ADR-214) — field·missingProperty 를 합쳐 한 번만 검사한다. allErrors
+  // (ADR-193) 이후 400 1건당 detail × 2회 실행되던 비용 절반화. 매칭 의미는 동일(부분 일치 OR).
+  const isSensitive = SENSITIVE_FIELD_RE.test(missing ? `${field} ${missing}` : field)
   return {
     field,
     rule: e.keyword || 'unknown',