mega-framework 0.1.4 → 0.1.6

package/src/cli/commands/new.js

@@ -1,26 +1,94 @@
 // @ts-check
 /**
- * `mega new <project>` — 빈 폴더에서 멀티앱 hello world 까지 한 명령 스캐폴드 (roadmap §336, ADR-142).
+ * `mega new <project>` — `sample/crud` 데모앱을 그대로 스캐폴드한다(ADR-179, 기존 미니멀/--views 모드 대체).
  *
- * 기본 앱 `main` + `*.localhost` 호스트 + README · `.env.example` · `.gitignore` · `package.json`
- * (scripts + concurrently devDep + PM2 `ecosystem.config.cjs`) 를 만든다. `ejsMate` 옵트인이면 EJS +
- * ejs-mate 뷰 골격(ADR-011/136) + i18next 다국어(ADR-037~039) + Bootstrap 5 디자인(ADR-151)을 더한다 —
- * 뷰 렌더 라우트, ko/en 로케일, 그리고 토큰 치환 없이 그대로 복사하는 정적 자산(vendored Bootstrap +
- * 브랜드 CSS/JS). 신규 dep 설치는 하지 않고(네트워크 회피) 안내만 출력한다.
+ * 빈 폴더에 14개 기능(auth·notes/users CRUD·WS 채팅·jobs·cron·metrics·logs·perf·redis·tracing·upload·
+ * worker·guide)을 모두 갖춘 멀티앱 데모를 찍어낸다. 원본은 레포의 `sample/crud`(npm `files` 에 포함돼
+ * 패키지에도 동봉) 트리를 **바이트 그대로 복사**하고, 프로젝트 이름이 박힌 소수 파일(package.json·README·
+ * ecosystem·.env)만 토큰 치환한다 — `sample-crud` → 프로젝트명, dep `file:../..` → 실제 버전(`^x.y.z`).
+ * 로컬 인프라 기동용 루트 `docker-compose.yml` 도 함께 복사한다(개발자 학습용, ADR-103).
+ *
+ * 복사 제외: 빌드 산출물(node_modules·coverage)·로크파일(package-lock/yarn.lock)·런타임 로그(*.log)·VCS,
+ * 그리고 런타임 업로드 데이터(`var/uploads/*` — 개인정보 포함 가능). 업로드 데모가 쓰는 디렉토리는
+ * 빈 `.gitkeep` 으로만 만든다. 신규 dep 설치는 하지 않고(네트워크 회피) 안내만 출력한다.
  *
  * @module cli/commands/new
  */
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
+import { copyFileSync, 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'
+import { nameVariants } from '../template-engine.js'
+
+/** 이 파일이 있는 디렉토리(src/cli/commands). 아래 원본 경로의 기준점. */
+const HERE = dirname(fileURLToPath(import.meta.url))
+/** 스캐폴드 원본 = 레포의 `sample/crud` 데모앱(src/cli/commands 기준 3단계 위 + sample/crud). */
+const SAMPLE_ROOT = resolve(HERE, '../../../sample/crud')
+/** 루트 `docker-compose.yml` — 로컬 인프라(postgres·mariadb·mongo·redis·nats·zipkin·otel) 기동용. */
+const COMPOSE_SRC = resolve(HERE, '../../../docker-compose.yml')
+/** 프레임워크 자체 package.json — 스캐폴드 dep 버전 핀(`^x.y.z`) 의 소스. */
+const FRAMEWORK_PKG = resolve(HERE, '../../../package.json')
+
+/** 복사 제외 디렉토리/파일 basename — 빌드 산출물·로크파일·VCS·런타임 데이터 디렉토리. */
+const EXCLUDE_NAMES = new Set([
+  'node_modules',
+  '.git',
+  'coverage',
+  '.nyc_output',
+  '.vitest',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  '.DS_Store',
+])
+/** 복사 제외 상대경로 prefix — 런타임 업로드 산출물(개인정보 포함 가능, 대신 .gitkeep 만 생성). */
+const EXCLUDE_PREFIXES = ['var/uploads']
+/** 프로젝트 이름 토큰 치환을 적용할 텍스트 파일(그 외는 바이트 그대로 복사 — 바이너리 보존). */
+const TRANSFORM_FILES = new Set(['package.json', 'README.md', 'ecosystem.config.cjs', '.env', '.env.example'])
+
+/**
+ * 한 상대경로가 복사 제외 대상인지.
+ * @param {string} rel - POSIX 슬래시 상대경로.
+ * @returns {boolean}
+ */
+function isExcluded(rel) {
+  if (rel.endsWith('.log')) return true
+  if (EXCLUDE_PREFIXES.some((p) => rel === p || rel.startsWith(`${p}/`))) return true
+  return rel.split('/').some((seg) => EXCLUDE_NAMES.has(seg))
+}
 
-/** templates/project 루트. src/cli/commands/new.js 기준 3단계 위 + templates/project. */
-const PROJECT_TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), '../../../templates/project')
+/**
+ * 디렉토리를 재귀 순회해 복사 대상 파일의 상대경로(POSIX 슬래시) 목록을 만든다. 제외 디렉토리는
+ * 통째로 건너뛴다(node_modules 등 큰 트리 순회 비용 회피).
+ * @param {string} dir - 현재 순회 디렉토리(절대).
+ * @param {string} base - 상대경로 기준 루트(절대).
+ * @param {string[]} acc - 누적 결과.
+ * @returns {string[]}
+ */
+function walk(dir, base, acc) {
+  for (const ent of readdirSync(dir, { withFileTypes: true })) {
+    const abs = join(dir, ent.name)
+    const rel = relative(base, abs).split(sep).join('/')
+    if (isExcluded(rel)) continue
+    if (ent.isDirectory()) walk(abs, base, acc)
+    else acc.push(rel)
+  }
+  return acc
+}
 
-/** 프로젝트 템플릿을 읽어 토큰 치환. @param {string} file @param {Record<string,string>} vars @returns {string} */
-function renderProject(file, vars) {
-  return renderTemplate(readFileSync(join(PROJECT_TEMPLATES, file), 'utf8'), vars)
+/**
+ * 토큰 치환 — `sample-crud` 를 프로젝트명으로, package.json 의 모노레포 dep(`file:../..`)을 실제 버전으로.
+ * @param {string} rel - 파일 상대경로.
+ * @param {string} content - 원본 텍스트.
+ * @param {{ name: string, version: string }} vars
+ * @returns {string}
+ */
+function transformText(rel, content, vars) {
+  let out = content.replaceAll('sample-crud', vars.name)
+  if (rel === 'package.json') {
+    // 모노레포 로컬 링크 → 퍼블리시된 프레임워크 버전 핀. 스캐폴드된 프로젝트는 독립 패키지라 file: 가 안 풀린다.
+    out = out.replace('"file:../.."', `"^${vars.version}"`)
+  }
+  return out
 }
 
 /**
@@ -28,74 +96,54 @@ function renderProject(file, vars) {
  * @param {string} targetDir - 프로젝트 루트 절대/상대 경로.
  * @param {object} [opts]
  * @param {string} [opts.name] - 프로젝트 이름(기본: targetDir 의 마지막 세그먼트).
- * @param {boolean} [opts.ejsMate] - EJS + ejs-mate 뷰 골격 포함(기본 false).
  * @param {boolean} [opts.force] - 기존 파일 덮어쓰기(기본 false — 건너뜀).
  * @returns {{ root: string, written: string[], skipped: string[] }}
  */
-export function scaffoldProject(targetDir, { name, ejsMate = false, force = false } = {}) {
+export function scaffoldProject(targetDir, { name, force = false } = {}) {
   const root = resolve(targetDir)
   const projectName = nameVariants(name ?? root.split(/[/\\]/).pop() ?? 'mega-app').kebab
-  const vars = { name: projectName, Name: nameVariants(projectName).pascal }
-
-  // 뷰 옵트인이면 GET / 를 뷰 렌더로 바꾸고(JSON hello 대신) 그에 맞는 테스트를 쓴다.
-  /** @type {Array<{ rel: string, tpl: string }>} */
-  const files = [
-    { rel: 'mega.config.js', tpl: 'mega.config.tpl' },
-    { rel: 'apps/main/app.config.js', tpl: ejsMate ? 'app.config.views.tpl' : 'app.config.tpl' },
-    { rel: 'apps/main/routes/index.js', tpl: ejsMate ? 'route.views.tpl' : 'route.tpl' },
-    { rel: 'test/apps/main/index.test.js', tpl: ejsMate ? 'route.test.views.tpl' : 'route.test.tpl' },
-    { rel: 'package.json', tpl: 'package.tpl' },
-    { rel: 'README.md', tpl: 'readme.tpl' },
-    { rel: '.env.example', tpl: 'env.tpl' },
-    { rel: '.gitignore', tpl: 'gitignore.tpl' },
-    { rel: 'vitest.config.js', tpl: 'vitest.config.tpl' },
-    { rel: 'ecosystem.config.cjs', tpl: 'ecosystem.config.tpl' },
-  ]
-  if (ejsMate) {
-    files.push(
-      { rel: 'apps/main/views/layouts/main.ejs', tpl: 'views/layout.ejs.tpl' },
-      { rel: 'apps/main/views/index.ejs', tpl: 'views/index.ejs.tpl' },
-      { rel: 'apps/main/locales/server/ko.json', tpl: 'locales/server/ko.json.tpl' },
-      { rel: 'apps/main/locales/server/en.json', tpl: 'locales/server/en.json.tpl' },
-      { rel: 'apps/main/locales/client/ko.json', tpl: 'locales/client/ko.json.tpl' },
-      { rel: 'apps/main/locales/client/en.json', tpl: 'locales/client/en.json.tpl' },
-    )
-  }
-
-  // 정적 자산 — 토큰 치환 없이 바이트 그대로 복사한다(vendored Bootstrap 5 min 번들 + 브랜드 CSS/JS).
-  // 이들은 템플릿이 아니라 정적 파일이므로 renderTemplate(`{{token}}`)을 거치지 않는다.
-  /** @type {Array<{ rel: string, src: string }>} */
-  const assets = ejsMate
-    ? [
-        { rel: 'apps/main/public/vendor/bootstrap/bootstrap.min.css', src: 'public/vendor/bootstrap/bootstrap.min.css' },
-        { rel: 'apps/main/public/vendor/bootstrap/bootstrap.bundle.min.js', src: 'public/vendor/bootstrap/bootstrap.bundle.min.js' },
-        { rel: 'apps/main/public/css/app.css', src: 'public/css/app.css' },
-        { rel: 'apps/main/public/js/app.js', src: 'public/js/app.js' },
-        { rel: 'apps/main/public/js/theme-init.js', src: 'public/js/theme-init.js' },
-      ]
-    : []
+  /** @type {string} */
+  const version = JSON.parse(readFileSync(FRAMEWORK_PKG, 'utf8')).version
+  const vars = { name: projectName, version }
 
   /** @type {string[]} */ const written = []
   /** @type {string[]} */ const skipped = []
-  for (const { rel, tpl } of files) {
-    const out = join(root, rel)
+
+  /**
+   * 출력 파일 1개를 기록(존재 + !force 면 skip).
+   * @param {string} out - 출력 절대경로.
+   * @param {() => void} write - 실제 기록 동작.
+   */
+  const emit = (out, write) => {
     if (existsSync(out) && !force) {
       skipped.push(out)
-      continue
+      return
     }
     mkdirSync(dirname(out), { recursive: true })
-    writeFileSync(out, renderProject(tpl, vars))
+    write()
     written.push(out)
   }
-  for (const { rel, src } of assets) {
+
+  // 1) sample/crud 트리 복사(제외 규칙 적용). 토큰 치환 대상만 텍스트로 렌더, 그 외는 바이트 그대로.
+  for (const rel of walk(SAMPLE_ROOT, SAMPLE_ROOT, [])) {
+    const src = join(SAMPLE_ROOT, rel)
     const out = join(root, rel)
-    if (existsSync(out) && !force) {
-      skipped.push(out)
-      continue
-    }
-    mkdirSync(dirname(out), { recursive: true })
-    copyFileSync(join(PROJECT_TEMPLATES, src), out)
-    written.push(out)
+    emit(out, () => {
+      if (TRANSFORM_FILES.has(rel)) {
+        writeFileSync(out, transformText(rel, readFileSync(src, 'utf8'), vars))
+      } else {
+        copyFileSync(src, out)
+      }
+    })
   }
+
+  // 2) 루트 docker-compose.yml — 로컬 인프라(개발자 학습용). 프로젝트 이름과 무관해 그대로 복사.
+  const compose = join(root, 'docker-compose.yml')
+  emit(compose, () => copyFileSync(COMPOSE_SRC, compose))
+
+  // 3) 업로드 데모가 쓰는 디렉토리 placeholder — 실제 업로드 데이터(개인정보 PDF 등)는 동봉하지 않는다.
+  const gitkeep = join(root, 'var/uploads/.gitkeep')
+  emit(gitkeep, () => writeFileSync(gitkeep, ''))
+
   return { root, written, skipped }
 }

package/src/cli/commands/scaffold.js

@@ -7,7 +7,6 @@
  * @module cli/commands/scaffold
  */
 import { Command } from 'commander'
-import prompts from 'prompts'
 import { generate, GENERATOR_KINDS } from '../generators/index.js'
 import { scaffoldProject } from './new.js'
 import { runRoutesCommand } from './routes.js'
@@ -50,21 +49,16 @@ export async function runScaffoldCommand(argv, { out, err, projectRoot, logger }
 
   program
     .command('new <project>')
-    .description('빈 폴더에서 멀티앱 hello world 스캐폴드')
-    .option('--views', 'EJS + ejs-mate 뷰 골격 포함')
+    .description('sample/crud 데모앱(14기능) 전체를 빈 폴더에 스캐폴드')
     .option('--force', '기존 파일 덮어쓰기')
-    .action(async (/** @type {string} */ project, /** @type {any} */ opts) => {
-      // --views 미지정 + 대화형 터미널이면 ejs-mate 옵트인을 묻는다(비-TTY/CI 는 기본 false).
-      let ejsMate = opts.views === true
-      if (opts.views === undefined && process.stdin.isTTY) {
-        const ans = /** @type {any} */ (await prompts({ type: 'confirm', name: 'views', message: 'EJS + ejs-mate 뷰 골격을 포함할까요?', initial: false }))
-        ejsMate = ans.views === true
-      }
+    .action((/** @type {string} */ project, /** @type {any} */ opts) => {
       const target = project === '.' ? projectRoot : `${projectRoot}/${project}`
-      const r = scaffoldProject(target, { name: project === '.' ? undefined : project, ejsMate, force: opts.force === true })
+      const r = scaffoldProject(target, { name: project === '.' ? undefined : project, force: opts.force === true })
       out(`mega: scaffolded project at ${r.root}`)
       reportFiles(out, r, r.root)
-      out('\n다음 단계:\n  cd ' + project + '\n  npm install\n  npm run dev')
+      // 풀 데모는 로컬 인프라(postgres·redis·mongo·nats)가 있어야 부팅된다 — docker compose 로 띄운 뒤 마이그레이션.
+      const cd = project === '.' ? '' : `  cd ${project}\n`
+      out(`\n다음 단계:\n${cd}  npm install\n  docker compose up -d        # 로컬 인프라 기동(postgres·redis·mongo·nats)\n  npm run migrate             # DB 스키마 생성\n  npm run dev                 # 개발 서버`)
     })
 
   program

package/src/cli/index.js

@@ -21,6 +21,7 @@
 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'
@@ -32,6 +33,7 @@ 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'
 
@@ -39,13 +41,13 @@ import { SCAFFOLD_COMMANDS, runScaffoldCommand } from './commands/scaffold.js'
 export const USAGE = `mega — MEGA-FRAMEWORK CLI
 
 Usage:
-  mega start [--port N] [--host H] [--cluster N|max] [--root DIR]   앱 부팅 + HTTP listen (별칭: serve)
+  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> [--views] [--force]           빈 폴더에서 멀티앱 hello world 스캐폴드
+  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]                          등록 라우트 트리 출력
@@ -63,6 +65,8 @@ Options:
   --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)·도움말. 그 외 런타임/부팅 명령은 로드. */
@@ -202,6 +206,51 @@ export function resolveHost(setting) {
   return setting
 }
 
+/**
+ * `mega start --watch` 가 자신을 `node --watch` 로 재실행해야 하는지 (ADR-182). `--watch` 플래그가 있고
+ * 아직 watch 하에 재실행되지 않았을 때만 true — 가드 env(`MEGA_WATCH_REEXEC`)로 무한재귀를 막는다.
+ * @param {Record<string, string|boolean>} flags
+ * @param {Record<string, string|undefined>} env
+ * @returns {boolean}
+ */
+export function shouldReexecForWatch(flags, env) {
+  return flags.watch === true && env.MEGA_WATCH_REEXEC !== '1'
+}
+
+/**
+ * `mega start --watch` → `node --watch … <self> start … --cluster 1` 재실행 명령을 빌드한다 (ADR-182).
+ *
+ * - `--watch` 인자는 **node 플래그**로 옮기고 mega 인자에선 제거한다.
+ * - **단일 프로세스 강제**(`--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[] }}
+ */
+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`(값 포함) 제거. */
+  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 (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] }
+}
+
 /**
  * `mega` CLI 진입점. 파싱 → 명령 분기. **이 함수는 process.exit 를 호출하지 않는다**(테스트 가능) —
  * exit code 를 반환하고, bin 래퍼가 `process.exitCode` 로 반영한다.
@@ -212,9 +261,11 @@ export function resolveHost(setting) {
  * @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]
+ * @param {Function} [deps.spawn] - child_process.spawn 주입(기본 node:child_process). `--watch` 재실행 테스트용.
+ * @param {string} [deps.selfPath] - mega 진입 스크립트 경로(기본 `process.argv[1]`). `--watch` 재실행 대상.
  * @returns {Promise<number>} exit code(0=성공, 1=실패/미지정 명령).
  */
-export async function runCli(argv, { out = console.log, err = console.error, cwd, logger } = {}) {
+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())
@@ -232,6 +283,35 @@ export async function runCli(argv, { out = console.log, err = console.error, cwd
   }
 
   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 은 무의미 — 무시(비치명적).
+        }
+      }
+      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)
+        })
+      })
+    }
+
     // listen 포트/호스트는 부팅(어댑터 connect) 전에 fail-closed 검증한다 — 잘못된 값을 늦게(listen 시점)
     // cryptic 에러로 만나거나 silent 강등(특권/랜덤 포트)하지 않도록(per ADR-167 후속).
     const port = resolvePort(flags.port)
@@ -246,35 +326,51 @@ export async function runCli(argv, { out = console.log, err = console.error, cwd
     }
     const workers = resolveClusterWorkers(clusterSetting)
 
+    // 시작 확인 메시지 — pino 로거가 있으면 그쪽 info 로(구조적·sink 라우팅, ADR-180), 없으면 CLI stdout
+    // (`out`)으로 폴백한다. listen/forked 는 운영 라이프사이클 이벤트라 로그로 남기는 게 정합.
+    const announce = (/** @type {any} */ lg, /** @type {string} */ msg) => {
+      if (lg && typeof lg.info === 'function') lg.info(msg)
+      else out(`mega: ${msg}`)
+    }
+
     // 워커 부팅 함수 — 단일/클러스터 모드 공통. 클러스터에선 각 워커 프로세스가 이 함수를 실행한다.
     const bootListen = async () => {
-      const { server } = await bootApp(projectRoot, { listen: true, port, host, logger })
+      const { server, appLogger } = 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
+      return { server, appLogger }
     }
 
     if (workers === null) {
       // 단일 프로세스(클러스터 비활성) — 기존 경로 유지.
-      const server = await bootListen()
-      out(`mega: listening on [${server.hosts.join(', ')}]`)
+      const { server, appLogger } = await bootListen()
+      announce(appLogger, `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 })
+    // 마스터 조율 로그(SIGINT 수신·워커 종료/respawn 등)를 pino 로(ADR-180). 마스터는 bootApp 을 안 해
+    // pino 인스턴스가 없으므로 config 로 직접 만든다. 워커는 bootApp 의 appLogger 를 쓰니 primary 에서만
+    // 만들어(워커당 중복 transport worker 회피) start 전에 주입한다.
+    /** @type {any} */ let masterLogger = null
+    if (mega.isPrimary()) {
+      const { global: masterGlobal } = await loadAndValidateConfig(projectRoot)
+      masterLogger = buildLogger(/** @type {any} */ (masterGlobal).logger)
+      mega.setLogger(masterLogger)
+    }
     await mega.start(async () => {
-      const server = await bootListen()
-      out(`mega: worker ${process.pid} listening on [${server.hosts.join(', ')}]`)
+      const { server, appLogger } = await bootListen()
+      announce(appLogger, `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)`)
+      announce(masterLogger, `cluster master ${process.pid} forked ${workers} worker(s)`)
     }
     return 0
   }
@@ -352,6 +448,29 @@ export function collectRegistrations(global, host, kind) {
   return [...staticPart, ...dynamicPart]
 }
 
+/**
+ * CLI 호스트(worker/scheduler) 로거 배선 — `bin/mega.js` 는 `runCli` 에 logger 를 주입하지 않으므로
+ * (undefined), config 의 pino 로거를 만들어 종료 로그(`MegaShutdown.setLogger`)·flush 훅에 쓴다. 이로써
+ * `mega worker`/`mega scheduler` 의 자기 로그·종료 로그가 console 이 아니라 pino 로 나간다(ADR-180).
+ * 주입(테스트)이 있으면 그쪽을 그대로 쓰고 pino 는 만들지 않는다(side-effect 회피).
+ * @param {Object} global - global config(`logger` 보유 가능).
+ * @param {{ info?: Function, warn?: Function } | undefined} injectedLogger - 주입 로거(테스트) 또는 undefined.
+ * @returns {{ info?: Function, warn?: Function } | null} 호스트 로그에 쓸 로거(없으면 null).
+ */
+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 된다.
+    MegaShutdown.setLogger(appLogger)
+    MegaShutdown.register('mega-logger', async () => {
+      await new Promise((resolve) => appLogger.flush(() => resolve(undefined)))
+    })
+  }
+  return appLogger
+}
+
 /**
  * `mega worker` 호스트 골격 — config + 어댑터 connect + ctx + `MegaJobWorker` 인스턴스 + graceful.
  * 등록 소스 = `config.jobs` + 플러그인 `mega.jobs.register` 분(`collectRegistrations`, ADR-123).
@@ -362,6 +481,7 @@ export function collectRegistrations(global, host, kind) {
 export async function runWorkerHost(projectRoot, logger) {
   // bootApp 과 같은 토대(config → 플러그인 install → 어댑터 connect → ctx).
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
+  const log = wireHostLogger(global, logger)
   const worker = new MegaJobWorker({ ctx })
   // 잡 메트릭 (ADR-132) — prepareRuntime 이 health.exposeMetrics 시 이미 MegaMetrics.init 했고,
   // 옵트인 OFF 면 subscribeJobs 는 no-op() 을 반환한다. start 전에 구독해 enqueue(dispatch)부터 잡는다. 구독은
@@ -371,7 +491,7 @@ export async function runWorkerHost(projectRoot, logger) {
   // 미선언·중복을 부팅 시 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')
+  log?.info?.({ count: jobs.length }, 'worker.jobs registered')
   await worker.start()
   MegaShutdown.register('mega-worker', async () => {
     await worker.stop()
@@ -388,12 +508,13 @@ export async function runWorkerHost(projectRoot, logger) {
  */
 export async function runSchedulerHost(projectRoot, logger) {
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
+  const log = wireHostLogger(global, 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')
+  log?.info?.({ count: schedules.length }, 'scheduler.schedules registered')
   scheduler.start()
   MegaShutdown.register('mega-scheduler', async () => {
     await scheduler.stop()

package/src/core/boot.js

@@ -66,6 +66,7 @@ import { MegaWsHub } from '../cli/ws-hub.js'
  * @property {MegaApp[]} megaApps - 생성된 MegaApp 인스턴스(등록 순서).
  * @property {BootContext} ctx - lifecycle hook 에 넘긴 boot context.
  * @property {import('../cli/ws-hub.js').MegaWsHub | null} wsHub - embedded wsHub(ADR-137, `wsHub.enabled` OFF 면 null).
+ * @property {import('pino').Logger | null} appLogger - 공유 pino 로거(ADR-141, logger 비활성이면 null). CLI 시작 메시지 등에 재사용.
  */
 
 /**
@@ -188,6 +189,28 @@ export async function prepareRuntime(projectRoot, { ping = false, logger } = {})
   return { global, apps, host, ctx, wsHub }
 }
 
+/**
+ * `global.server` 의 운영 옵션을 각 앱 Fastify 인스턴스 옵션으로 매핑한다(ADR-181, 04-data-models
+ * §MegaServerConfig). 미지정 키는 생략해 Fastify 기본값을 따른다. boot 가 모든 MegaApp 에 동일 주입한다
+ * (port/host 는 MegaServer.listen 이, 아래 런타임 옵션은 Fastify 인스턴스가 소비).
+ *   - trustProxy / trustedProxies → Fastify `trustProxy`(프록시/LB 뒤 req.ip·X-Forwarded-* 신뢰).
+ *     trustedProxies(목록)가 있으면 그것을, 없으면 trustProxy(boolean/number/string)를 그대로 넘긴다.
+ *   - timeouts.requestMs → Fastify `requestTimeout`(요청 수신 제한, slow-loris 보호).
+ *   - keepAliveMs       → Fastify `keepAliveTimeout`(keep-alive 소켓 idle 제한, ALB 정합).
+ * @param {any} server - `global.server` config(없으면 빈 객체).
+ * @returns {{ trustProxy?: any, requestTimeout?: number, keepAliveTimeout?: number }}
+ */
+export function serverFastifyOptions(server) {
+  const s = server ?? {}
+  /** @type {any} */
+  const out = {}
+  const trust = s.trustedProxies !== undefined ? s.trustedProxies : s.trustProxy
+  if (trust !== undefined) out.trustProxy = trust
+  if (s.timeouts && s.timeouts.requestMs !== undefined) out.requestTimeout = s.timeouts.requestMs
+  if (s.keepAliveMs !== undefined) out.keepAliveTimeout = s.keepAliveMs
+  return out
+}
+
 /**
  * embedded wsHub 기동 (ADR-137) — `cfg.enabled === true` 일 때만 `MegaWsHub` 를 같은 프로세스에 띄우고
  * `MegaShutdown` 에 drain 종료 hook 을 등록한다. 아니면 `null`(미기동). 검증(빈 토큰 등)은 MegaWsHub
@@ -244,6 +267,9 @@ export async function bootApp(projectRoot, { listen = true, port, host: listenHo
   // 않게(로그가 종료 과정 끝까지 살아 있도록) — 마지막 flush 단계(07-sequence §6).
   const appLogger = buildLogger(/** @type {any} */ (global).logger)
   if (appLogger) {
+    // 전역 에러 핸들러(unhandledRejection/uncaughtException, ADR-178)가 fatal 로그에 쓸 공유 로거를 주입한다.
+    // process 레벨 핸들러는 이 DI 그래프 밖이라 MegaShutdown 모듈 스코프로 넘긴다(globalThis 오염 회피).
+    MegaShutdown.setLogger(appLogger)
     MegaShutdown.register('mega-logger', async () => {
       await new Promise((resolve) => appLogger.flush(() => resolve(undefined)))
     })
@@ -275,6 +301,9 @@ export async function bootApp(projectRoot, { listen = true, port, host: listenHo
       // 운영 관측성 config 는 Global-only(ADR-072/131) — global `health` 블록을 모든 앱에 주입한다(/metrics
       // 라우트 등록 + 보안 면제 + IP allowList). sessionSecret 주입과 동일 패턴.
       health: /** @type {any} */ (global).health,
+      // server 운영 옵션(trustProxy/requestTimeout/keepAliveTimeout) → Fastify 인스턴스 옵션(ADR-181).
+      // Global-only 라 모든 앱에 동일 주입. MegaApp 이 Fastify({ ...fastifyOptions }) 로 전달.
+      fastifyOptions: serverFastifyOptions(serverCfg),
       plugins: host.fastifyPlugins,
       globalMiddlewares: host.globalMiddlewares,
     })
@@ -388,5 +417,5 @@ export async function bootApp(projectRoot, { listen = true, port, host: listenHo
   }
 
   logger?.debug?.('boot.done')
-  return { server, host, config: global, apps, megaApps, ctx, wsHub }
+  return { server, host, config: global, apps, megaApps, ctx, wsHub, appLogger }
 }

package/src/core/config-validator.js

@@ -94,6 +94,31 @@ export function validateGlobalConfig(globalConfig) {
   //    앱에서 registerSession 이 fail-fast 로 잡으므로(여긴 server.sessionSecret 가 "정의됐을 때만"
   //    강도를 검증) — 정의됐다면 (a) 기본 placeholder 거부, (b) ≥32자 강제(부팅 fail-fast, ADR-062).
   validateSessionSecret(globalConfig.server?.sessionSecret)
+
+  // 7) server 런타임 타임아웃(ADR-181) — 정의됐다면 음 아닌 정수만(Fastify requestTimeout/keepAliveTimeout).
+  validateServerTimeouts(globalConfig.server)
+}
+
+/**
+ * `server.timeouts.requestMs` · `server.keepAliveMs` 검증(ADR-181, Fastify 인스턴스 옵션으로 매핑).
+ * 정의됐다면 음 아닌 정수(ms)만 허용 — 잘못된 값은 부팅 fail-fast. `trustProxy`/`trustedProxies` 는
+ * 타입 유연(boolean/number/string/array)이라 Fastify 에 위임(여기서 검증 안 함). 미정의는 통과(선택 키).
+ * @param {any} server - `globalConfig.server`.
+ * @throws {MegaConfigError} `server.invalid_timeout`.
+ */
+function validateServerTimeouts(server) {
+  const s = server ?? {}
+  /** @param {string} name @param {unknown} v */
+  const check = (name, v) => {
+    if (v === undefined) return
+    if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
+      throw new MegaConfigError('server.invalid_timeout', `${name} must be a non-negative integer (ms). Got ${JSON.stringify(v)}.`, {
+        details: { value: v },
+      })
+    }
+  }
+  check('server.timeouts.requestMs', s.timeouts?.requestMs)
+  check('server.keepAliveMs', s.keepAliveMs)
 }
 
 /** sessionSecret 강도 검증의 최소 길이(바이트 수가 아닌 문자 길이 — base64url 32바이트 ≈ 43자). */