mega-framework 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Chu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# MEGA-FRAMEWORK
+
+Node.js 마이크로프레임웍 + CLI. **Slim** 의 가벼움(import 한 줄로 시작)과 **Ruby on Rails** 의
+convention-over-configuration(네이밍·구조·사용법을 코어가 정함) 철학을 합친 프레임워크.
+HTTP·WebSocket 을 동급 일급으로 다루고, 데이터 어댑터·잡/스케줄러·트레이싱·보안·세션·i18n·SSR 을
+검증된 라이브러리 위에 얇게 래핑한다.
+
+## 상태
+
+**Phase 1~6 완료.** (version `0.1.0`)
+
+- Phase 1 코어 골격 · Phase 2 WebSocket+Hub · Phase 3 데이터 어댑터+트레이싱 · Phase 4 잡/스케줄러/워커 ·
+  Phase 5 SSR+세션+보안+i18n 전부 완료.
+- Phase 6(CLI 스캐폴드 + 안정화 + 0.1.0): 이월 부채 2건 청산 완료(wsHub embedded ADR-137, native query span ADR-138).
+  **CLI 스캐폴드 본체 구현 완료** — `mega new` / `mega g <type>` 제너레이터(`src/cli/generators/index.js`) / `mega routes·test·console`(`src/cli/commands/`) 전부 배선됨(`src/cli/index.js`) — [05-roadmap §Phase 6](./docs/05-roadmap.md).
+- 검증: `npm test` **1510 그린 / 3 skip**(mongo RS 트랜잭션은 standalone 의도 skip, ADR-108), typecheck 0, lint 0, prod audit 0.
+
+## 핵심 기능
+
+| 영역 | 제공 |
+|---|---|
+| **HTTP** | `MegaApp`(Fastify v5 래퍼) · `MegaServer`(멀티앱 vhost 라우팅) · 단일 시그니처 `router.http.<method>(path, handler, opts?)` · 라우트 자동 로드 · 자동 envelope(`{ok, data\|error, meta}`) · AJV 검증 에러 → `details` 자동 매핑 |
+| **WebSocket** | `MegaWebSocketController`(타입 자동 디스패치) · Bridge↔Hub 12-타입 프로토콜 · presence · `broadcast`/`directToUser` fan-out · per-message deflate 압축 · embedded/별도 프로세스 hub |
+| **데이터** | `MegaModel`(ORM 없음, native API + 트랜잭션) · 어댑터 베이스 트리(Db/Cache/Bus/Lock/Session) · 드라이버: Postgres·MariaDB·SQLite·MongoDB·Redis·NATS·File · `MegaRedlockAdapter`(분산 락) |
+| **운영(잡/스케줄)** | `MegaJobQueue`(NATS JetStream + 재시도 + DLQ) · `MegaJobWorker` · `MegaScheduler`(croner + 분산 중복방지) · `MegaWorker`(worker_threads CPU 풀) |
+| **복원력** | `MegaRetry`(p-retry 지수 백오프) · `MegaCircuitBreaker`(opossum) · `MegaHealth`(`/health`·`/health/ready`) · `MegaShutdown`(LIFO graceful) |
+| **관측성** | `MegaTracing`(OpenTelemetry 옵트인, HTTP/WS/어댑터/native query 자동 span, Zipkin) · `MegaMetrics`(Prometheus `/metrics`) |
+| **보안** | helmet·CORS·rate-limit·CSRF 자동 등록 · `MegaHash`(scrypt) · `MegaBruteForce` · ASP 종단 암호화(HTTP/WS) · 파일 업로드 MIME 화이트리스트 + path traversal 방어 |
+| **세션·인증** | `MegaSessionAdapter`(file/redis) · ULID sid · 쿠키 HMAC · rolling TTL · CSRF 세션 모드 |
+| **SSR·i18n** | `MegaTemplate`(EJS + ejs-mate, XSS auto-escape) · `registerI18n`(i18next, 쿠키 locale, 에러코드↔locale 자동 번역) |
+| **확장** | `MegaPluginHost`(install 패턴 + apiVersion 호환 강제) · CLI 명령 등록 |
+
+## 빠른 시작
+
+```bash
+npm install
+npm run infra:up      # docker 인프라 가동(postgres/maria/mongo/redis/nats/otel/zipkin) — 통합 테스트용
+npm test              # 전체 테스트(실 인프라). .env 자동 로드(ADR-128)
+npm run infra:down    # 인프라 종료
+```
+
+프로젝트 루트에 `mega.config.js`(글로벌) + 앱별 `apps/<name>/app.config.js` 를 둔다.
+
+```js
+// mega.config.js — 글로벌 설정(활성 앱·서비스·플러그인)
+export default {
+  apps: ['main'],
+  services: {
+    databases: {
+      maindb: { driver: 'postgres', url: process.env.MEGA_PG_URL },
+    },
+  },
+  plugins: [],
+}
+```
+
+```js
+// apps/main/app.config.js — 앱 단위 설정(호스트·DB 별명 참조)
+export default {
+  name: 'main',
+  hosts: ['main.localhost'],
+  databases: { db: 'maindb' }, // services.databases.maindb 를 ctx.db('db') 로 참조
+}
+```
+
+```js
+// apps/main/routes/ping.js — 자동 로드되는 라우트(함수 default export)
+export default (router) => {
+  // 반환값은 자동으로 envelope 으로 감싸진다.
+  router.http.get('/api/ping', async () => ({ pong: true }))
+  router.http.get('/api/who', async (req, reply, ctx) => ({
+    driver: await ctx.db('db').ping(),
+  }))
+}
+```
+
+```bash
+mega start --port 3000   # 앱 부팅 + HTTP listen
+# → main.localhost:3000/api/ping  →  { "ok": true, "data": { "pong": true }, "meta": {...} }
+```
+
+## CLI
+
+```
+mega start [--port N] [--host H] [--root DIR]   앱 부팅 + HTTP listen (별칭: serve)
+mega worker [--root DIR]                         잡 소비 워커 런타임 호스트
+mega scheduler [--root DIR]                      분산 스케줄러 호스트
+mega migrate [--db KEY]                          DB 마이그레이션 적용(up, ADR-149)
+mega migrate:down [--db KEY]                     마이그레이션 롤백(down)
+mega migrate:status [--db KEY]                   마이그레이션 적용 상태 출력
+mega new <project> [--views] [--force]           멀티앱 hello world 스캐폴드
+mega generate <kind> <name> [--app A]            코드+테스트 제너레이터 (별칭: g)
+mega routes                                       등록된 라우트 트리 출력
+mega test [args...]                              vitest 실행(인자 그대로 전달)
+mega console                                      앱 컨텍스트 로딩 REPL
+mega <plugin:command> [args...]                  플러그인이 등록한 CLI 명령 실행
+mega help                                        도움말
+mega-ws-hub                                       WebSocket Hub 독립 프로세스(MEGA_WSHUB_* 환경변수)
+```
+
+## 디렉토리 구조
+
+```
+src/
+├── core/        HTTP 서버 + WS + 부팅 orchestrator(MegaApp/MegaServer/Router/boot/security/session/i18n/template)
+├── lib/         코어 라이브러리(스케줄·잡·워커·플러그인·트레이싱·메트릭·재시도·서킷·헬스·해시) + asp/(종단 암호화)
+├── adapters/    어댑터 베이스 트리 + 구체 드라이버(postgres/maria/sqlite/mongo/redis/nats/file/redlock/session)
+├── models/      MegaModel 데이터 모델 베이스(ORM 없음)
+├── middleware/  (예약)
+├── errors/      MegaError 계층(config/route/http/validation/auth/...)
+├── cli/         CLI 디스패처 + WS Hub
+├── eslint-plugin/  커스텀 룰(라우트에서 모델 직접 import 차단)
+└── index.js     공개 entry point
+
+bin/             mega.js(CLI) · mega-ws-hub.js(Hub 런처)
+packages/        mega-client-wasm(Rust/WASM ASP 클라이언트)
+docs/            설계·ADR·운영 문서
+```
+
+## 의존성
+
+- **런타임**: Node.js `>=20` (engines)
+- **HTTP/WS**: `fastify` v5 + `@fastify/*`(cookie/cors/csrf/helmet/multipart/rate-limit) · `ws`
+- **데이터**: `pg` · `mariadb` · `mongodb` · `better-sqlite3` · `ioredis` · `nats` · `redlock`
+- **복원력·운영**: `p-retry` · `opossum` · `croner`
+- **관측성**: `@opentelemetry/*`(api/sdk-trace/sdk-metrics/exporter-zipkin/exporter-prometheus/exporter-otlp)
+- **SSR·i18n·검증**: `ejs` + `ejs-mate` · `i18next` · `ajv`
+
+> 모든 신규 의존성은 [docs/09](./docs/09-decisions-and-open-questions.md) 에 ADR 로 1줄 기록(P8). 커스텀 구현은 Node 빌트인만 사용(scrypt/HMAC/cluster/worker_threads).
+
+## 문서
+
+| 문서 | 내용 |
+|---|---|
+| [CLAUDE.md](./CLAUDE.md) | 절대 원칙·네이밍·개발 원칙(P1~P8) |
+| [docs/01-vision.md](./docs/01-vision.md) | 비전·핵심 가치·차별점 |
+| [docs/02-architecture.md](./docs/02-architecture.md) | 전체 아키텍처 |
+| [docs/03-api-spec.md](./docs/03-api-spec.md) | 클래스/메서드 시그니처 |
+| [docs/04-data-models.md](./docs/04-data-models.md) | config 스키마·타입 |
+| [docs/05-roadmap.md](./docs/05-roadmap.md) | Phase 0~6 로드맵 + 현재 위치 |
+| [docs/06-class-diagrams.md](./docs/06-class-diagrams.md) | 클래스 다이어그램(Mermaid) |
+| [docs/07-sequence-diagrams.md](./docs/07-sequence-diagrams.md) | 시퀀스 다이어그램 |
+| [docs/08-class-specs.md](./docs/08-class-specs.md) | 클래스별 행동 스펙 |
+| [docs/09-decisions-and-open-questions.md](./docs/09-decisions-and-open-questions.md) | 결정 기록(ADR-001~138) + 미해결 질문(OQ) |
+| [docs/10-state-diagrams.md](./docs/10-state-diagrams.md) | 상태 다이어그램 |
+| [docs/11-test-scenarios.md](./docs/11-test-scenarios.md) | 테스트 시나리오 |
+| [docs/12-performance-security.md](./docs/12-performance-security.md) | 성능 목표 + STRIDE 위협 모델 |
+| [docs/13-sample-code.md](./docs/13-sample-code.md) | 동작 코드 묶음 |
+| [docs/INFRA.md](./docs/INFRA.md) | 로컬 docker 인프라·트레이싱·메트릭·DLQ 운영 가이드 |
+
+## 라이선스
+
+MIT

package/bin/mega-ws-hub.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * `mega ws-hub` 실행 launcher (ADR-032). 실제 로직은 src/cli/ws-hub.js.
+ *
+ * 사용: MEGA_WSHUB_TOKENS=tok1,tok2 [MEGA_WSHUB_PORT=3100] [MEGA_WSHUB_HOST=0.0.0.0]
+ *       [MEGA_WSHUB_HEARTBEAT_MS=25000] mega-ws-hub
+ */
+import { runWsHubCli } from '../src/cli/ws-hub.js'
+
+runWsHubCli().catch((err) => {
+  // 부팅 실패는 fail-fast — 메시지 출력 후 비정상 종료 (P4: 이유 명확, silent X).
+  console.error(`[mega:ws-hub] failed to start: ${err.message}`)
+  process.exitCode = 1
+})

package/bin/mega.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * `mega` CLI 실행 launcher (Phase 4 Step 6, ADR-123). 실제 로직은 src/cli/index.js.
+ *
+ * 사용:
+ *   mega start [--port N] [--host H] [--root DIR]
+ *   mega worker | scheduler [--root DIR]
+ *   mega <plugin:command> [args...]
+ *   mega help
+ */
+import { runCli } from '../src/cli/index.js'
+import { MegaShutdown } from '../src/lib/mega-shutdown.js'
+
+runCli(process.argv.slice(2))
+  .then((code) => {
+    // 명령 핸들러가 정한 exit code 를 반영. start/worker/scheduler 는 0 을 돌려주지만 시그널
+    // 대기로 프로세스가 살아 있으므로 즉시 종료되지 않는다(MegaShutdown 이 SIGTERM 에 종료).
+    process.exitCode = code
+  })
+  .catch(async (err) => {
+    // 부팅·명령 실패는 fail-fast — 메시지 출력 후 비정상 종료 (P4: 이유 명확, silent X).
+    console.error(`[mega] failed: ${err?.message ?? err}`)
+    // M-1 — 부팅이 어댑터 connect(buildFromGlobalConfig 가 'adapters:disconnect' hook 등록)까지 진행한 뒤
+    // 후속 단계(예: server.listen EADDRINUSE, beforeBoot hook throw)에서 실패하면, 연결된 어댑터가 정리
+    // 없이 남아 이벤트루프를 살려 프로세스가 hang 한다(boot.js:116 주석이 약속한 정리). 등록된 cleanup
+    // hook 을 LIFO 로 실행해(어댑터 disconnect 등) 자원을 회수한 뒤 exit 1 한다. MegaShutdown.now 가
+    // 마지막에 process.exit 하므로 정상 경로에선 아래 process.exit 는 도달하지 않는다.
+    try {
+      await MegaShutdown.now({ exitCode: 1 })
+    } catch (cleanupErr) {
+      // 정리 중 예외(now 의 per-hook catch 를 벗어난 드문 경우)도 묻지 않는다(P4) — 메시지 후 강제 종료.
+      console.error(`[mega] cleanup failed: ${cleanupErr?.message ?? cleanupErr}`)
+      process.exit(1)
+    }
+    // now() 가 exit 하지 않은 경우(테스트 mock 등)를 위한 보장.
+    process.exit(1)
+  })

package/docker-compose.yml

@@ -0,0 +1,201 @@
+# MEGA-FRAMEWORK — Phase 3 통합 테스트 인프라 (ADR-103)
+#
+# Step 3~6 어댑터 통합 테스트가 실 인스턴스로 검증되도록, Step 9 산출물을
+# Step 3 이전으로 당겨온 docker-compose 정의.
+#
+# 포함 서비스 (docker 필요한 5종):
+#   - Postgres 16   (Step 4, pg)
+#   - MariaDB 11    (Step 4, mariadb)
+#   - MongoDB 7     (Step 5, mongodb)
+#   - Redis 7       (Step 6, ioredis)
+#   - NATS 2.10     (Step 6, nats) — JetStream 활성(-js, Phase 4 Step 3 MegaJob)
+#
+# 제외 (docker 불필요):
+#   - Sqlite (Step 3, better-sqlite3 file-based / in-memory)
+#   - File   (Step 6, 로컬 파일시스템)
+#
+# 데이터 정책: ephemeral (tmpfs). 컨테이너 종료 시 데이터 소멸 → 테스트 격리.
+#   `npm run infra:down` 은 `down -v` 로 익명 볼륨까지 청소.
+#
+# 비밀번호는 모두 dev/test 전용 약한 값. ⚠️ 운영 환경 사용 금지.
+#
+# docker compose v2 (subcommand) 기준. legacy `docker-compose`(하이픈) 아님.
+# 모든 포트/credential 은 .env 로 오버라이드 가능 (.env.example 참조).
+#
+# ── 어댑터 옵션과의 관계 (ADR-109) ────────────────────────────────────
+# 아래 각 컨테이너 environment 의 MEGA_<SERVICE>_USER/PASSWORD/DB/PORT 는 **컨테이너 초기화용**이다.
+# 같은 이름들이 services.<domain>.<key>.envPrefix 지정 시 어댑터 연결필드로도 매핑된다(env-mapper).
+# 어댑터의 advanced 옵션(pool.*, options.*, mariadb bigIntStrategy 등)은 컨테이너가 아니라 **앱**이
+# 읽으므로 docker-compose 가 아닌 .env(MEGA_<SERVICE>_POOL_*/OPTIONS_*)에 둔다 — 예시는 .env.example.
+# (DB 컨테이너 environment 에 풀/드라이버 옵션을 넣는 것은 의미가 없어 의도적으로 분리.)
+
+name: mega-test
+
+services:
+  # ── Postgres (Step 4) ─────────────────────────────────────────────
+  postgres:
+    image: postgres:16-alpine
+    container_name: mega-postgres
+    restart: ${MEGA_INFRA_RESTART:-unless-stopped}
+    ports:
+      - "${MEGA_PG_PORT:-5432}:5432"
+    environment:
+      POSTGRES_USER: ${MEGA_PG_USER:-mega}
+      POSTGRES_PASSWORD: ${MEGA_PG_PASSWORD:-mega-dev-only}
+      POSTGRES_DB: ${MEGA_PG_DB:-mega_test}
+    # ephemeral: 데이터 디렉토리를 tmpfs(RAM)에 둬 종료 시 소멸
+    tmpfs:
+      - /var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${MEGA_PG_USER:-mega} -d ${MEGA_PG_DB:-mega_test}"]
+      interval: 3s
+      timeout: 3s
+      retries: 10
+      start_period: 5s
+    networks:
+      - mega-test-net
+
+  # ── MariaDB (Step 4) ──────────────────────────────────────────────
+  mariadb:
+    image: mariadb:11
+    container_name: mega-mariadb
+    restart: ${MEGA_INFRA_RESTART:-unless-stopped}
+    ports:
+      - "${MEGA_MARIA_PORT:-3306}:3306"
+    environment:
+      MARIADB_ROOT_PASSWORD: ${MEGA_MARIA_ROOT_PASSWORD:-mega-dev-only}
+      MARIADB_DATABASE: ${MEGA_MARIA_DB:-mega_test}
+      MARIADB_USER: ${MEGA_MARIA_USER:-mega}
+      MARIADB_PASSWORD: ${MEGA_MARIA_PASSWORD:-mega-dev-only}
+    tmpfs:
+      - /var/lib/mysql
+    # mariadb 공식 이미지 제공 스크립트 (innodb 초기화까지 확인)
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 3s
+      timeout: 3s
+      retries: 15
+      start_period: 8s
+    networks:
+      - mega-test-net
+
+  # ── MongoDB (Step 5) ──────────────────────────────────────────────
+  # ⚠️ standalone 모드 — 도큐먼트 CRUD 통합은 동작하나 **트랜잭션은 미지원**이다
+  #    (MongoDB 트랜잭션은 replica set/mongos 필요, ADR-108). 트랜잭션 통합 테스트는
+  #    replica set Mongo(예: MEGA_MONGO_URL 에 ?replicaSet=rs0)를 주입할 때만 실행되고
+  #    standalone 이면 해당 테스트만 자동 skip 된다. auth 활성 상태에서 replSet 을 켜려면
+  #    멤버 간 keyFile + rs.initiate() 가 필요해 docker 가용 환경에서 별도 검증 후 결정(ADR-103 갱신).
+  mongodb:
+    image: mongo:7
+    container_name: mega-mongodb
+    restart: ${MEGA_INFRA_RESTART:-unless-stopped}
+    ports:
+      - "${MEGA_MONGO_PORT:-27017}:27017"
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: ${MEGA_MONGO_USER:-mega}
+      MONGO_INITDB_ROOT_PASSWORD: ${MEGA_MONGO_PASSWORD:-mega-dev-only}
+      MONGO_INITDB_DATABASE: ${MEGA_MONGO_DB:-mega_test}
+    tmpfs:
+      - /data/db
+    # mongo:7 은 mongosh 내장
+    healthcheck:
+      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
+      interval: 3s
+      timeout: 5s
+      retries: 15
+      start_period: 8s
+    networks:
+      - mega-test-net
+
+  # ── Redis (Step 6) ────────────────────────────────────────────────
+  redis:
+    image: redis:7-alpine
+    container_name: mega-redis
+    restart: ${MEGA_INFRA_RESTART:-unless-stopped}
+    ports:
+      - "${MEGA_REDIS_PORT:-6379}:6379"
+    # dev/test 전용 패스워드. persistence off (--save "") → 인메모리, 종료 시 소멸
+    command: >
+      redis-server
+      --requirepass ${MEGA_REDIS_PASSWORD:-mega-dev-only}
+      --save ""
+      --appendonly no
+    healthcheck:
+      test: ["CMD", "redis-cli", "-a", "${MEGA_REDIS_PASSWORD:-mega-dev-only}", "ping"]
+      interval: 3s
+      timeout: 3s
+      retries: 10
+      start_period: 3s
+    networks:
+      - mega-test-net
+
+  # ── NATS (Step 6 + Phase 4 Step 3 JetStream) ──────────────────────
+  nats:
+    image: nats:2.10-alpine
+    container_name: mega-nats
+    restart: ${MEGA_INFRA_RESTART:-unless-stopped}
+    ports:
+      - "${MEGA_NATS_PORT:-4222}:4222"        # client
+      - "${MEGA_NATS_MONITOR_PORT:-8222}:8222" # HTTP monitoring (/healthz)
+    # -m 8222: HTTP 모니터링 활성 → healthcheck 가 /healthz 폴링
+    # -js -sd /data/jetstream: JetStream(영속 큐) 활성화 + store dir 지정. MegaJob/MegaJobQueue
+    #   (Phase 4 Step 3, ADR-119)가 영속 큐·재시도·DLQ 에 JetStream 을 쓴다. store dir 은 아래 tmpfs
+    #   (RAM)에 둬 **데이터 정책(ephemeral)을 유지** — 종료 시 스트림·메시지 소멸 → 테스트 격리.
+    command: ["--name", "mega-nats", "-m", "8222", "-js", "-sd", "/data/jetstream"]
+    tmpfs:
+      - /data/jetstream
+    # nats:2.10-alpine 은 busybox wget 내장 (non-alpine scratch 이미지는 shell 없어 불가)
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8222/healthz"]
+      interval: 3s
+      timeout: 3s
+      retries: 10
+      start_period: 3s
+    networks:
+      - mega-test-net
+
+  # ── Zipkin (Phase 5 Step 1 트레이싱 백엔드, ADR-128) ───────────────
+  # OTLP collector 가 변환·전달한 span 을 저장·조회하는 백엔드 + UI(:9411).
+  # 통합 테스트는 /api/v2/traces 로 span 도달을 검증한다. 저장은 in-memory(종료 시 소멸).
+  zipkin:
+    image: openzipkin/zipkin:3.4
+    container_name: mega-zipkin
+    restart: ${MEGA_INFRA_RESTART:-unless-stopped}
+    ports:
+      - "${MEGA_ZIPKIN_PORT:-9411}:9411"
+    # openzipkin/zipkin 이미지에 healthcheck 용 wget 내장. /health 는 zipkin 자체 헬스 엔드포인트.
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:9411/health"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+      start_period: 5s
+    networks:
+      - mega-test-net
+
+  # ── OpenTelemetry Collector (ADR-128) ─────────────────────────────
+  # 앱(OTLP exporter) → collector → zipkin. config 는 infra/otel-collector-config.yaml.
+  # 이미지가 distroless 라 컨테이너 내 shell 이 없어 compose healthcheck(CMD-SHELL)는 불가.
+  #   → health_check extension(:13133)을 노출하고, 통합 테스트가 HTTP 폴링으로 준비를 확인한다.
+  #   collector 가 config 오류로 죽으면 depends_on(zipkin) 과 무관하게 컨테이너가 Exit → 테스트가 즉시 감지.
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:0.110.0
+    container_name: mega-otel-collector
+    restart: ${MEGA_INFRA_RESTART:-unless-stopped}
+    command: ["--config=/etc/otel-collector-config.yaml"]
+    volumes:
+      - ./infra/otel-collector-config.yaml:/etc/otel-collector-config.yaml:ro
+    ports:
+      - "${MEGA_OTEL_OTLP_GRPC_PORT:-4317}:4317" # OTLP gRPC
+      - "${MEGA_OTEL_OTLP_HTTP_PORT:-4318}:4318" # OTLP HTTP
+      - "${MEGA_OTEL_HEALTH_PORT:-13133}:13133"  # health_check extension
+    depends_on:
+      zipkin:
+        condition: service_healthy
+    networks:
+      - mega-test-net
+
+networks:
+  mega-test-net:
+    name: mega-test-net
+    driver: bridge

package/eslint.config.js

@@ -0,0 +1,57 @@
+// eslint.config.js — ESLint v9 flat config
+// MEGA-FRAMEWORK 린트 정책 (ADR-026 promise plugin + CLAUDE.md P4 silent catch 금지)
+
+import js from '@eslint/js'
+import promise from 'eslint-plugin-promise'
+import globals from 'globals'
+import mega from './src/eslint-plugin/index.js'
+
+export default [
+  js.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: { ...globals.node, ...globals.es2024 },
+    },
+    plugins: { promise, mega },
+    rules: {
+      // CLAUDE.md P4 — silent catch 절대 금지
+      'no-empty': ['error', { allowEmptyCatch: false }],
+      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+
+      // ADR-026 — Promise 안전성 정적 보강.
+      // 주의: no-floating-promises 는 @typescript-eslint 의 타입 기반 룰이며
+      // JS 전용 eslint-plugin-promise(v7)에는 존재하지 않는다. 타입 정보 없이
+      // floating promise 를 정적 검출할 수단이 없으므로, JS 환경에서는
+      // catch-or-return(then 체인 미처리 검출)으로 대체한다. (docs/09 ADR-026)
+      'promise/catch-or-return': 'error',
+
+      // ADR-022 — 라우트·컨트롤러는 모델 직접 import 금지
+      'mega/no-direct-model-import': 'error',
+    },
+  },
+  {
+    // 테스트 파일은 vitest 글로벌 (describe/test/expect 등) 노출
+    files: ['test/**/*.js', '**/*.test.js'],
+    languageOptions: {
+      globals: { ...globals.node, ...globals.es2024 },
+    },
+    rules: {
+      'no-unused-vars': ['warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    ignores: [
+      'node_modules/**',
+      'dist/**',
+      'coverage/**',
+      'packages/*/pkg/**',
+      'packages/*/target/**',
+      'logs/**',
+      'storage/**',
+      '.git/**',
+      '.idea/**',
+    ],
+  },
+]

package/infra/otel-collector-config.yaml

@@ -0,0 +1,43 @@
+# MEGA-FRAMEWORK — OpenTelemetry Collector 설정 (ADR-128)
+#
+# 역할: 앱(OTLP HTTP/gRPC exporter)이 보낸 trace span 을 수신해 Zipkin 백엔드로 전달.
+#   파이프라인:  앱 ──OTLP──▶ collector ──Zipkin v2──▶ mega-zipkin(:9411)
+#                                       └─debug(stdout) ── infra:logs 로 span 확인
+#
+# 통합 테스트(tracing/otel-collector-e2e)는 앱에서 OTLP 로 span 을 보내고, Zipkin API
+#   (/api/v2/traces)를 폴링해 collector→zipkin 경로가 실제로 동작함을 검증한다.
+#
+# ⚠️ dev/test 전용. 운영용 보안(인증/TLS/샘플링 정책)은 포함하지 않는다.
+# collector-contrib 0.110.0 기준. 이미지는 distroless 라 컨테이너 내 shell 없음.
+
+receivers:
+  # OTLP receiver — HTTP(4318)/gRPC(4317) 둘 다 수신.
+  # 0.110 대에서 디폴트 bind 가 localhost 로 바뀌어, 컨테이너 외부(호스트) 접근을
+  # 위해 0.0.0.0 으로 명시한다(미명시 시 컨테이너 내부에서만 listen → 호스트 연결 거부).
+  otlp:
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+      grpc:
+        endpoint: 0.0.0.0:4317
+
+exporters:
+  # Zipkin v2 JSON 으로 변환해 zipkin 컨테이너로 전송.
+  zipkin:
+    endpoint: http://mega-zipkin:9411/api/v2/spans
+  # stdout 디버그(개발 편의 — `docker compose logs mega-otel-collector` 로 span 확인).
+  debug:
+    verbosity: normal
+
+extensions:
+  # 헬스 체크 엔드포인트(:13133). distroless 라 compose healthcheck(shell)는 불가하나,
+  # 통합 테스트가 이 엔드포인트를 HTTP 폴링해 collector 준비 완료를 확인한다.
+  health_check:
+    endpoint: 0.0.0.0:13133
+
+service:
+  extensions: [health_check]
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [zipkin, debug]

package/jsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "checkJs": false,
+    "allowJs": true,
+    "noEmit": true,
+    "noImplicitAny": true,
+    "strict": false,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.js", "test/**/*.js", "bin/**/*.js"],
+  "exclude": ["node_modules", "coverage", "packages/**/pkg"]
+}