mega-framework 0.1.5 → 0.1.7

package/bin/mega-ws-hub.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 // @ts-check
 /**
- * `mega ws-hub` 실행 launcher (ADR-032). 실제 로직은 src/cli/ws-hub.js.
+ * `mega ws-hub` 실행 launcher (ADR-032). 실제 로직은 src/lib/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'
+import { runWsHubCli } from '../src/lib/ws-hub.js'
 
 runWsHubCli().catch((err) => {
   // 부팅 실패는 fail-fast — 메시지 출력 후 비정상 종료 (P4: 이유 명확, silent X).

package/package.json

@@ -1,33 +1,53 @@
 {
   "name": "mega-framework",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {
     "node": ">=20.6.0"
   },
   "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "workspaces": [
+    "sample/crud",
+    "sample/simple"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://git.nyx-zone.com/mega/mega-framework.git"
   },
   "exports": {
-    ".": "./src/index.js",
-    "./lib": "./src/lib/index.js",
-    "./errors": "./src/errors/index.js",
-    "./auth": "./src/auth/index.js",
-    "./test": "./src/test/index.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./lib": {
+      "types": "./types/lib/index.d.ts",
+      "default": "./src/lib/index.js"
+    },
+    "./errors": {
+      "types": "./types/errors/index.d.ts",
+      "default": "./src/errors/index.js"
+    },
+    "./auth": {
+      "types": "./types/auth/index.d.ts",
+      "default": "./src/auth/index.js"
+    },
+    "./test": {
+      "types": "./types/test/index.d.ts",
+      "default": "./src/test/index.js"
+    },
     "./eslint-plugin": "./src/eslint-plugin/index.js",
     "./package.json": "./package.json"
   },
   "files": [
     "src/**/*.js",
+    "types/**/*.d.ts",
     "bin/**/*.js",
     "templates/**",
     "sample/**",
     "infra/**",
     "docker-compose.yml",
-    ".env",
     ".env.example",
     "eslint.config.js",
     "vitest.config.js",
@@ -51,6 +71,7 @@
     "test:coverage": "vitest run --coverage",
     "lint": "eslint src test",
     "typecheck": "tsc -p jsconfig.json --noEmit",
+    "build:types": "rm -rf types && tsc -p tsconfig.build.json",
     "format": "prettier -w src test packages",
     "infra:up": "docker compose up -d --wait",
     "infra:down": "docker compose down -v",
@@ -58,7 +79,8 @@
     "infra:reset": "docker compose down -v && docker compose up -d --wait",
     "test:integration": "npm run infra:up && vitest run test/integration && npm run infra:down",
     "test:unit": "vitest run test/unit",
-    "prepublishOnly": "npm run lint && npm run typecheck && npm run test:unit",
+    "prepublishOnly": "npm run build:types && npm run lint && npm run typecheck && npm run test:unit",
+    "prepare": "npm run build:types",
     "release": "bash scripts/publish.sh"
   },
   "devDependencies": {
@@ -89,6 +111,7 @@
     "@fastify/swagger": "^9.7.0",
     "@fastify/swagger-ui": "^5.2.6",
     "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/core": "^2.7.1",
     "@opentelemetry/exporter-prometheus": "^0.218.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
     "@opentelemetry/exporter-zipkin": "^2.7.1",
@@ -97,6 +120,7 @@
     "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.41.1",
     "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "better-sqlite3": "^12.10.0",
     "commander": "^15.0.0",
     "croner": "^10.0.1",

package/sample/crud/.env

@@ -1,27 +1,175 @@
+# =============================================================================
+# sample-crud 환경변수 (.env) — 프레임워크 전체 설정 참조
+# =============================================================================
+# CLI(`mega start`/`worker`/`scheduler`)가 부팅 전에 이 파일을 process.env 로
+# 자동 로드한다(Node `process.loadEnvFile`, 20.6+, ADR-152). 이미 설정된 실제
+# 환경변수는 덮어쓰지 않는다(실 env 우선 — `--env-file` 과 동일). 그 뒤 mega.config.js·
+# apps/<app>/app.config.js 가 `process.env.X` 로 이 값들을 참조한다.
+#
+# [표기 규칙]
+#   KEY=value     → 이 데모(crud)가 실제로 쓰는 값.
+#   # KEY=value   → 프레임워크는 지원하지만 이 데모는 안 쓰는 옵션(참고용 — 필요 시 주석 해제).
+#
+# ⚠️ 아래 시크릿/비밀번호는 로컬 도커 데모 전용. 운영 배포 전 반드시 교체할 것.
+# =============================================================================
+
+
+# ── 실행 환경 ────────────────────────────────────────────────────────────────
+# development | production | test. pretty 로깅·정적자산 캐싱·i18n 자동완성 등에 영향.
+# 보통 npm 스크립트(dev=development / start=production)가 설정하므로 .env 에선 생략 가능.
+# NODE_ENV=development
+
+
+# ── 서버 (mega.config.js > server) ───────────────────────────────────────────
+# HTTP listen 포트 — server.port. CLI `--port N` 이 우선(ADR-146).
 PORT=3000
-DATABASE_URL=postgres://mega:dkTkqkfl12@localhost:5432/mega_test
-MEGA_CLUSTER_WORKERS=8
+# 세션 쿠키 HMAC 서명 시크릿(필수) — server.sessionSecret. 32자 이상 랜덤 강제(ADR-129/155).
 SESSION_SECRET=Zz4VoSzf0sYMEoqASu8G_wx5l3uKi2MlHsxDK3MSkoE
+# cluster 워커 프로세스 수(CLI 가 읽음, ADR-154) — 정수 N 또는 max(CPU 코어 수). 미설정/1=단일.
+#   우선순위: `--cluster` 플래그 > MEGA_CLUSTER_WORKERS > server.cluster config.
+MEGA_CLUSTER_WORKERS=8
+
+
+# ── ASP: Application-layer Secure Protocol (mega.config.js > asp) ─────────────
+# /ws/chat 의 E:/P: 프레임 키 유도 masterSecret(필수) — asp.masterSecret (ADR-127/158).
+# 클라이언트(WASM MegaSocket)도 같은 secret 으로 키를 유도하는 공유키 구조라 데모 전용 값을 둔다.
+ASP_MASTER_SECRET=demo-asp-master-7Qe2mWzR1tYbN8sLpKvX0cAfH4dG6jU
+
+
+# ── 데이터베이스 (mega.config.js > services.databases) ────────────────────────
+# Postgres(필수) — databases.primary.url. 모델·마이그레이션(mega migrate)·세션 사용자.
+DATABASE_URL=postgres://mega:dkTkqkfl12@localhost:5432/mega_test
+# MongoDB(필수) — databases.mongo.url. /demo/notes 컬렉션(ADR-108). url path 의 dbName 추출,
+#   authSource=인증 DB(보통 admin).
+MONGO_URL=mongodb://mega:dkTkqkfl12@localhost:27017/mega_test?authSource=admin
+# MariaDB(미사용) — 프레임워크는 mariadb 드라이버 지원. 쓰려면 mega.config 의 services.databases 에
+#   { driver:'mariadb', url: process.env.MARIA_URL } 추가. (url 은 query string 미지원)
+# MARIA_URL=mariadb://mega:dkTkqkfl12@localhost:3306/mega_test
+
+
+# ── Redis 캐시 (mega.config.js > services.caches, app.config > session) ───────
+# 논리 DB 인덱스를 분리해 키 충돌 회피(/0 세션 · /1 demo · /2 rate · /3 lock).
+# 세션 store(app.config.js session.store.url, ADR-129/155).
 REDIS_SESSION_URL=redis://:dkTkqkfl12@localhost:6379/0
+# brute-force 카운터(ctx.bruteForce, ADR-049/130) — caches.rate.
 REDIS_RATE_URL=redis://:dkTkqkfl12@localhost:6379/2
+# /demo/redis·cron·jobs 데모 캐시 — caches.demo.
 REDIS_DEMO_URL=redis://:dkTkqkfl12@localhost:6379/1
+# 분산 락(redlock, ADR-113) — caches.lock(locks.main 이 빌려 씀). /demo/cron leader election.
 REDIS_LOCK_URL=redis://:dkTkqkfl12@localhost:6379/3
-MONGO_URL=mongodb://mega:dkTkqkfl12@localhost:27017/mega_test?authSource=admin
+# 범용 캐시(미사용) — 별도 캐시 어댑터가 필요하면 services.caches 에 추가해 참조.
+# REDIS_CACHE_URL=redis://:dkTkqkfl12@localhost:6379/4
+
+
+# ── NATS 버스 (mega.config.js > services.buses) ──────────────────────────────
+# 잡 큐(EmailJob JetStream, ADR-119) — buses.jobs.url. `mega worker` 가 소비, 웹이 enqueue.
+#   JetStream 활성 서버 필요(nats-server -js).
 NATS_JOBS_URL=nats://localhost:4222
-ASP_MASTER_SECRET=demo-asp-master-7Qe2mWzR1tYbN8sLpKvX0cAfH4dG6jU
+# 이벤트 버스(미사용) — pub/sub 등 두 번째 버스가 필요하면 services.buses 에 추가.
+# NATS_EVENTS_URL=nats://localhost:4222
+
 
+# ── WS Hub: 클러스터 채팅 브릿지 (ADR-059/065/137/176) ────────────────────────
+# crud 는 app.config.js 의 bridgeHub 로 /ws/chat 을 클러스터 전파한다. 허브는 `mega ws-hub`(scripts/
+# start-ws-hub.sh)로 별도 프로세스 기동. 아래 MEGA_WSHUB_* 는 src/lib/ws-hub.js 가 읽는다.
+# --- 허브 서버가 읽는 값 (`mega ws-hub`) ---
+# 수락 토큰 CSV(필수) — 브릿지 인증. 빈 값이면 허브 기동 실패. 운영 교체.
 MEGA_WSHUB_TOKENS=dev-bridge-token-change-me
-MEGA_WSHUB_TOKEN=dev-bridge-token-change-me
 MEGA_WSHUB_PORT=3100
 MEGA_WSHUB_HOST=0.0.0.0
+# 허브 튜닝(선택) — 미설정 시 코드 기본값(heartbeat 25000 / maxPayload 1 MiB / 압축 off).
+MEGA_WSHUB_HEARTBEAT_MS=25000
+MEGA_WSHUB_MAX_PAYLOAD=1048576
+MEGA_WSHUB_COMPRESSION=false
+MEGA_WSHUB_COMPRESSION_THRESHOLD=1024     # MEGA_WSHUB_COMPRESSION=true 일 때만 적용
+# --- 앱(브릿지 클라이언트)이 읽는 값 (app.config.js > bridgeHub) ---
 MEGA_WSHUB_URL=ws://localhost:3100
+MEGA_WSHUB_TOKEN=dev-bridge-token-change-me
+# 이 노드(브릿지) 식별자 — bridgeHub.bridgeId. roster/로그 구분용(클러스터 워커는 -w{id} suffix 자동).
+BRIDGE_ID=crud-1
+
 
+# ── OpenTelemetry 분산 트레이싱 (선택, ADR-104/114/126/163) ───────────────────
+# MegaTracing.fromEnv() 가 부팅 시 읽는다(boot.js). ENABLED!=='true' 면 0 비용 no-op.
+# /demo/tracing 데모가 요청별 trace_id 를 만들고 Zipkin 딥링크로 잇는다. docker 의
+# otel-collector(:4318 OTLP HTTP)·zipkin(:9411) 가동 시 true 로 켠다(collector 부재 시 export 실패 로그).
 MEGA_OTEL_ENABLED=true
 MEGA_OTEL_SERVICE_NAME=sample-crud
 MEGA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
-MEGA_OTEL_EXPORTER=otlp
-MEGA_OTEL_SAMPLING_RATIO=1.0
+MEGA_OTEL_EXPORTER=otlp                      # otlp | zipkin | console | inmemory
+MEGA_OTEL_SAMPLING_RATIO=1.0                 # 0.0~1.0 또는 always_on | always_off
+# Zipkin UI API base — /demo/tracing 딥링크 base(앱 코드가 읽음).
 MEGA_OTEL_ZIPKIN_API=http://localhost:9411/api/v2
+# resource 속성(선택) — 미설정 시 생략.
+# MEGA_OTEL_VERSION=1.0.0
+# MEGA_OTEL_ENVIRONMENT=local
+
+
+# ── Prometheus 메트릭 (선택, ADR-072/131) ────────────────────────────────────
+# crud 는 mega.config.js 의 health.exposeMetrics:true 로 /metrics 를 켠다(config 주도 — env 아님).
+# 아래 env 는 MegaMetrics.fromEnv() 를 직접 호출하는 커스텀 부팅에서만 효과(기본 boot 는 config 사용).
+# METRICS_ENABLED=true                       # 또는 MEGA_METRICS_ENABLED
+# MEGA_METRICS_SERVICE_NAME=sample-crud
+# MEGA_METRICS_ENVIRONMENT=local
+
+
+# ── 로깅 (mega.config.js > logger, ADR-023/141) ──────────────────────────────
+# pino 레벨 — logger.level. fatal | error | warn | info | debug | trace.
+LOG_LEVEL=info
+# (참고) 파일/텔레그램 sink 등은 .env 가 아니라 mega.config.js 의 logger.sinks 배열로 설정한다.
+
+
+# ── 데모 (앱 코드가 읽음) ─────────────────────────────────────────────────────
+# /demo/upload 저장 디렉터리. 상대경로=프로젝트 루트(cwd) 기준. 미설정 시 var/uploads.
 DEMO_UPLOAD_DIR=var/uploads
 
-BRIDGE_ID=crud-1
+
+# =============================================================================
+# Docker 인프라 (docker-compose.yml 이 읽음, ADR-103) — 전부 선택/주석
+# =============================================================================
+# 위 연결 문자열(DATABASE_URL 등)은 아래 도커 기본값과 정합한다. docker-compose.yml 에 인라인
+# 디폴트가 있어 미설정이어도 컨테이너가 뜨지만, 포트/비번을 바꾸려면 아래를 켜고 위 URL 도 함께 맞춘다.
+# 네이밍: MEGA_<SERVICE>_<FIELD>.
+# MEGA_PG_PORT=5432
+# MEGA_PG_USER=mega
+# MEGA_PG_PASSWORD=dkTkqkfl12
+# MEGA_PG_DB=mega_test
+# MEGA_MONGO_PORT=27017
+# MEGA_MONGO_USER=mega
+# MEGA_MONGO_PASSWORD=dkTkqkfl12
+# MEGA_MONGO_DB=mega_test
+# MEGA_REDIS_PORT=6379
+# MEGA_REDIS_PASSWORD=dkTkqkfl12
+# MEGA_NATS_PORT=4222
+# MEGA_NATS_MONITOR_PORT=8222
+# MEGA_MARIA_PORT=3306
+# MEGA_MARIA_ROOT_PASSWORD=dkTkqkfl12
+# MEGA_MARIA_USER=mega
+# MEGA_MARIA_PASSWORD=dkTkqkfl12
+# MEGA_MARIA_DB=mega_test
+# 컨테이너 restart 정책: 개발=unless-stopped / CI 일회성=no.
+# MEGA_INFRA_RESTART=unless-stopped
+
+
+# =============================================================================
+# 어댑터 옵션 자동매핑 (ADR-109, 12-factor) — 전부 선택/주석
+# =============================================================================
+# services.<domain>.<key> 에 `envPrefix: 'PG'` 처럼 지정하면 MegaAdapterManager 가
+# MEGA_<PREFIX>_<KEY> 를 읽어 어댑터 옵션에 병합(env 우선). url 직접 지정 대신 12-factor 분리용.
+# (crud 는 url 직접 방식이라 미사용 — 아래는 문법 참고.)
+#   문법: MEGA_<PREFIX>_<KEY>
+#     URL                     → url
+#     HOST / PORT / USER / PASSWORD → 연결필드 (PORT 만 정수, 나머지 문자열)
+#     DATABASE | DB           → database   /   DBNAME → dbName(Mongo)
+#     POOL_<X>                → pool.{camelCase(X)}    (드라이버 공통, 값 자동 타입변환)
+#     OPTIONS_<X>             → options.{드라이버 표기}  (postgres/sqlite=snake, 그 외=camel; MS 대문자 보존)
+# 공통 풀 인터페이스(min/max/idleTimeoutMs/acquireTimeoutMs/maxLifetimeMs) 예:
+# MEGA_PG_POOL_MIN=0
+# MEGA_PG_POOL_MAX=10
+# MEGA_PG_POOL_IDLE_TIMEOUT_MS=10000
+# 드라이버 특화 옵션 예:
+# MEGA_PG_OPTIONS_SSL=true                          # → options.ssl
+# MEGA_PG_OPTIONS_STATEMENT_TIMEOUT=30000           # → options.statement_timeout (pg=snake)
+# MEGA_MONGO_OPTIONS_AUTH_SOURCE=admin              # → options.authSource (mongo=camel)
+# MEGA_MONGO_OPTIONS_SERVER_SELECTION_TIMEOUT_MS=5000  # → options.serverSelectionTimeoutMS
+# MEGA_MARIA_OPTIONS_BIG_INT_STRATEGY=number        # number(기본,2^53 초과 손실) | bigint | string

package/sample/crud/.env.example

@@ -1,50 +1,175 @@
-# sample-crud 환경변수 (.env.example) — 복사해서 .env 로 쓰고 실제 값 채우기. .env 는 git 에 안 올림.
+# =============================================================================
+# sample-crud 환경변수 (.env.example) — 프레임워크 전체 설정 참조
+# =============================================================================
+# 복사해서 `.env` 로 쓰고 시크릿/비밀번호를 실제 값으로 채운다. CLI(`mega start`/`worker`/
+# `scheduler`)가 부팅 전에 `.env` 를 process.env 로 자동 로드한다(Node `process.loadEnvFile`,
+# 20.6+, ADR-152). 이미 설정된 실제 환경변수는 덮어쓰지 않는다(실 env 우선). 그 뒤 mega.config.js·
+# apps/<app>/app.config.js 가 `process.env.X` 로 이 값들을 참조한다.
+#
+# [표기 규칙]
+#   KEY=value     → 이 데모(crud)가 실제로 쓰는 값.
+#   # KEY=value   → 프레임워크는 지원하지만 이 데모는 안 쓰는 옵션(참고용 — 필요 시 주석 해제).
+#
+# ⚠️ change-me 로 표시된 값은 반드시 교체할 것(시크릿은 32자 이상 랜덤 권장).
+# =============================================================================
 
-# HTTP 포트
+
+# ── 실행 환경 ────────────────────────────────────────────────────────────────
+# development | production | test. pretty 로깅·정적자산 캐싱·i18n 자동완성 등에 영향.
+# 보통 npm 스크립트(dev=development / start=production)가 설정하므로 .env 에선 생략 가능.
+# NODE_ENV=development
+
+
+# ── 서버 (mega.config.js > server) ───────────────────────────────────────────
+# HTTP listen 포트 — server.port. CLI `--port N` 이 우선(ADR-146).
 PORT=3000
+# 세션 쿠키 HMAC 서명 시크릿(필수) — server.sessionSecret. 32자 이상 랜덤 강제(ADR-129/155).
+SESSION_SECRET=change-me-to-a-long-random-secret-at-least-32-chars
+# cluster 워커 프로세스 수(CLI 가 읽음, ADR-154) — 정수 N 또는 max(CPU 코어 수). 미설정/1=단일.
+#   우선순위: `--cluster` 플래그 > MEGA_CLUSTER_WORKERS > server.cluster config.
+MEGA_CLUSTER_WORKERS=8
+
+
+# ── ASP: Application-layer Secure Protocol (mega.config.js > asp) ─────────────
+# /ws/chat 의 E:/P: 프레임 키 유도 masterSecret(필수) — asp.masterSecret (ADR-127/158).
+# 클라이언트(WASM MegaSocket)도 같은 secret 으로 키를 유도하는 공유키 구조라 데모 전용 값을 둔다.
+ASP_MASTER_SECRET=change-me-to-a-demo-asp-secret
 
-# cluster 워커 프로세스 수(ADR-154) — 정수 N 또는 max(CPU 코어 수). 미설정/1=단일 프로세스.
-# MEGA_CLUSTER_WORKERS=max
 
-# Postgres 연결 (필수) — services.databases.primary.url 이 읽는다.
-# 예: docker compose 의 postgres
+# ── 데이터베이스 (mega.config.js > services.databases) ────────────────────────
+# Postgres(필수) — databases.primary.url. 모델·마이그레이션(mega migrate)·세션 사용자.
 DATABASE_URL=postgres://mega:change-me@localhost:5432/mega_test
+# MongoDB(필수) — databases.mongo.url. /demo/notes 컬렉션(ADR-108). url path 의 dbName 추출,
+#   authSource=인증 DB(보통 admin).
+MONGO_URL=mongodb://mega:change-me@localhost:27017/mega_test?authSource=admin
+# MariaDB(미사용) — 프레임워크는 mariadb 드라이버 지원. 쓰려면 mega.config 의 services.databases 에
+#   { driver:'mariadb', url: process.env.MARIA_URL } 추가. (url 은 query string 미지원)
+# MARIA_URL=mariadb://mega:change-me@localhost:3306/mega_test
 
-# 세션 쿠키 HMAC 서명 시크릿 (필수, ADR-155) — server.sessionSecret 이 읽는다. 충분히 긴 랜덤 문자열.
-SESSION_SECRET=change-me-to-a-long-random-secret
 
-# Redis 연결 (필수, ADR-155/157) — 세션 store·brute-force·/demo/redis·cron·jobs 데모 캐시 + 분산 락(redlock).
-# DB 인덱스를 분리해 키 충돌을 피한다(/0 세션, /1 demo, /2 rate, /3 lock).
+# ── Redis 캐시 (mega.config.js > services.caches, app.config > session) ───────
+# 논리 DB 인덱스를 분리해 키 충돌 회피(/0 세션 · /1 demo · /2 rate · /3 lock).
+# 세션 store(app.config.js session.store.url, ADR-129/155).
 REDIS_SESSION_URL=redis://:change-me@localhost:6379/0
+# brute-force 카운터(ctx.bruteForce, ADR-049/130) — caches.rate.
 REDIS_RATE_URL=redis://:change-me@localhost:6379/2
+# /demo/redis·cron·jobs 데모 캐시 — caches.demo.
 REDIS_DEMO_URL=redis://:change-me@localhost:6379/1
-# 분산 락(redlock, ADR-113) — services.caches.lock 이 읽는다. /demo/cron 스케줄의 클러스터 중복방지(leader election).
+# 분산 락(redlock, ADR-113) — caches.lock(locks.main 이 빌려 씀). /demo/cron leader election.
 REDIS_LOCK_URL=redis://:change-me@localhost:6379/3
+# 범용 캐시(미사용) — 별도 캐시 어댑터가 필요하면 services.caches 에 추가해 참조.
+# REDIS_CACHE_URL=redis://:change-me@localhost:6379/4
+
 
-# NATS 연결 (필수, ADR-119) — services.buses.jobs.url 이 읽는다. /demo/jobs 잡 큐(EmailJob)의 JetStream 백엔드.
-# `mega worker` 프로세스가 소비하고 웹은 enqueue 한다. JetStream 활성 NATS 서버 필요(nats-server -js).
+# ── NATS 버스 (mega.config.js > services.buses) ──────────────────────────────
+# 잡 큐(EmailJob JetStream, ADR-119) — buses.jobs.url. `mega worker` 가 소비, 웹이 enqueue.
+#   JetStream 활성 서버 필요(nats-server -js).
 NATS_JOBS_URL=nats://localhost:4222
+# 이벤트 버스(미사용) — pub/sub 등 두 번째 버스가 필요하면 services.buses 에 추가.
+# NATS_EVENTS_URL=nats://localhost:4222
 
-# MongoDB 연결 (필수, ADR-157) — services.databases.mongo.url 이 읽는다. /demo/notes 데모 컬렉션의 백엔드.
-# url path 의 dbName(mega_test)을 어댑터가 추출한다. authSource 는 인증 DB(보통 admin).
-MONGO_URL=mongodb://mega:change-me@localhost:27017/mega_test?authSource=admin
 
-# ASP WebSocket 데모 masterSecret (필수, ADR-158) — asp.masterSecret 이 읽는다. /ws/chat 의 E:/P:
-# 프레임 키 유도에 쓰인다. ASP 는 클라이언트(WASM MegaSocket)도 같은 secret 으로 키를 만드는 공유-키
-# 구조라 데모 페이지가 이 값을 브라우저에 주입한다 — 운영 secret 과 섞이지 않게 데모 전용 값을 둔다.
-ASP_MASTER_SECRET=change-me-to-a-demo-asp-secret
+# ── WS Hub: 클러스터 채팅 브릿지 (ADR-059/065/137/176) ────────────────────────
+# crud 는 app.config.js 의 bridgeHub 로 /ws/chat 을 클러스터 전파한다. 허브는 `mega ws-hub`(scripts/
+# start-ws-hub.sh)로 별도 프로세스 기동. 아래 MEGA_WSHUB_* 는 src/lib/ws-hub.js 가 읽는다.
+# --- 허브 서버가 읽는 값 (`mega ws-hub`) ---
+# 수락 토큰 CSV(필수) — 브릿지 인증. 빈 값이면 허브 기동 실패. 운영 교체.
+MEGA_WSHUB_TOKENS=change-me-hub-token
+MEGA_WSHUB_PORT=3100
+MEGA_WSHUB_HOST=0.0.0.0
+# 허브 튜닝(선택) — 미설정 시 코드 기본값(heartbeat 25000 / maxPayload 1 MiB / 압축 off).
+# MEGA_WSHUB_HEARTBEAT_MS=25000
+# MEGA_WSHUB_MAX_PAYLOAD=1048576
+# MEGA_WSHUB_COMPRESSION=false
+# MEGA_WSHUB_COMPRESSION_THRESHOLD=1024     # MEGA_WSHUB_COMPRESSION=true 일 때만 적용
+# --- 앱(브릿지 클라이언트)이 읽는 값 (app.config.js > bridgeHub) ---
+MEGA_WSHUB_URL=ws://localhost:3100
+MEGA_WSHUB_TOKEN=change-me-hub-token
+# 이 노드(브릿지) 식별자 — bridgeHub.bridgeId. roster/로그 구분용(클러스터 워커는 -w{id} suffix 자동).
+BRIDGE_ID=crud-1
 
-# OpenTelemetry 트레이싱 (선택, ADR-104/126/163) — /demo/tracing 데모가 요청별 trace_id 를 만들고 Zipkin 으로
-# 잇는다. 미설정/false 면 트레이싱 OFF(데모는 비활성 안내를 보여줌). docker 의 otel-collector(:4318 OTLP HTTP)·
-# zipkin(:9411) 가동 시 true 로 켠다. exporter otlp → collector → zipkin 경로로 span 이 전달된다.
+
+# ── OpenTelemetry 분산 트레이싱 (선택, ADR-104/114/126/163) ───────────────────
+# MegaTracing.fromEnv() 가 부팅 시 읽는다(boot.js). ENABLED!=='true' 면 0 비용 no-op.
+# /demo/tracing 데모가 요청별 trace_id 를 만들고 Zipkin 딥링크로 잇는다. docker 의
+# otel-collector(:4318 OTLP HTTP)·zipkin(:9411) 가동 시 true 로 켠다(collector 부재 시 export 실패 로그).
 MEGA_OTEL_ENABLED=false
 MEGA_OTEL_SERVICE_NAME=sample-crud
 MEGA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
-MEGA_OTEL_EXPORTER=otlp
-MEGA_OTEL_SAMPLING_RATIO=1.0
-# Zipkin UI API base — /demo/tracing 이 trace 딥링크 base(.../api/v2 를 떼 UI 루트)로 쓴다.
+MEGA_OTEL_EXPORTER=otlp                      # otlp | zipkin | console | inmemory
+MEGA_OTEL_SAMPLING_RATIO=1.0                 # 0.0~1.0 또는 always_on | always_off
+# Zipkin UI API base — /demo/tracing 딥링크 base(앱 코드가 읽음).
 MEGA_OTEL_ZIPKIN_API=http://localhost:9411/api/v2
+# resource 속성(선택) — 미설정 시 생략.
+# MEGA_OTEL_VERSION=1.0.0
+# MEGA_OTEL_ENVIRONMENT=local
+
+
+# ── Prometheus 메트릭 (선택, ADR-072/131) ────────────────────────────────────
+# crud 는 mega.config.js 의 health.exposeMetrics:true 로 /metrics 를 켠다(config 주도 — env 아님).
+# 아래 env 는 MegaMetrics.fromEnv() 를 직접 호출하는 커스텀 부팅에서만 효과(기본 boot 는 config 사용).
+# METRICS_ENABLED=true                       # 또는 MEGA_METRICS_ENABLED
+# MEGA_METRICS_SERVICE_NAME=sample-crud
+# MEGA_METRICS_ENVIRONMENT=local
+
+
+# ── 로깅 (mega.config.js > logger, ADR-023/141) ──────────────────────────────
+# pino 레벨 — logger.level. fatal | error | warn | info | debug | trace.
+LOG_LEVEL=info
+# (참고) 파일/텔레그램 sink 등은 .env 가 아니라 mega.config.js 의 logger.sinks 배열로 설정한다.
 
-# 업로드 저장 디렉터리 (선택, ADR-163) — /demo/upload 이 파일을 저장할 위치. 상대경로는 프로젝트 루트
-# (cwd) 기준, 절대경로면 그대로. 미설정 시 var/uploads(.gitignore). 다운로드도 같은 위치에서 소스로 읽는다.
+
+# ── 데모 (앱 코드가 읽음) ─────────────────────────────────────────────────────
+# /demo/upload 저장 디렉터리. 상대경로=프로젝트 루트(cwd) 기준. 미설정 시 var/uploads.
 DEMO_UPLOAD_DIR=var/uploads
+
+
+# =============================================================================
+# Docker 인프라 (docker-compose.yml 이 읽음, ADR-103) — 전부 선택/주석
+# =============================================================================
+# 위 연결 문자열(DATABASE_URL 등)은 아래 도커 기본값과 정합한다. docker-compose.yml 에 인라인
+# 디폴트가 있어 미설정이어도 컨테이너가 뜨지만, 포트/비번을 바꾸려면 아래를 켜고 위 URL 도 함께 맞춘다.
+# 네이밍: MEGA_<SERVICE>_<FIELD>.
+# MEGA_PG_PORT=5432
+# MEGA_PG_USER=mega
+# MEGA_PG_PASSWORD=change-me
+# MEGA_PG_DB=mega_test
+# MEGA_MONGO_PORT=27017
+# MEGA_MONGO_USER=mega
+# MEGA_MONGO_PASSWORD=change-me
+# MEGA_MONGO_DB=mega_test
+# MEGA_REDIS_PORT=6379
+# MEGA_REDIS_PASSWORD=change-me
+# MEGA_NATS_PORT=4222
+# MEGA_NATS_MONITOR_PORT=8222
+# MEGA_MARIA_PORT=3306
+# MEGA_MARIA_ROOT_PASSWORD=change-me
+# MEGA_MARIA_USER=mega
+# MEGA_MARIA_PASSWORD=change-me
+# MEGA_MARIA_DB=mega_test
+# 컨테이너 restart 정책: 개발=unless-stopped / CI 일회성=no.
+# MEGA_INFRA_RESTART=unless-stopped
+
+
+# =============================================================================
+# 어댑터 옵션 자동매핑 (ADR-109, 12-factor) — 전부 선택/주석
+# =============================================================================
+# services.<domain>.<key> 에 `envPrefix: 'PG'` 처럼 지정하면 MegaAdapterManager 가
+# MEGA_<PREFIX>_<KEY> 를 읽어 어댑터 옵션에 병합(env 우선). url 직접 지정 대신 12-factor 분리용.
+# (crud 는 url 직접 방식이라 미사용 — 아래는 문법 참고.)
+#   문법: MEGA_<PREFIX>_<KEY>
+#     URL                     → url
+#     HOST / PORT / USER / PASSWORD → 연결필드 (PORT 만 정수, 나머지 문자열)
+#     DATABASE | DB           → database   /   DBNAME → dbName(Mongo)
+#     POOL_<X>                → pool.{camelCase(X)}    (드라이버 공통, 값 자동 타입변환)
+#     OPTIONS_<X>             → options.{드라이버 표기}  (postgres/sqlite=snake, 그 외=camel; MS 대문자 보존)
+# 공통 풀 인터페이스(min/max/idleTimeoutMs/acquireTimeoutMs/maxLifetimeMs) 예:
+# MEGA_PG_POOL_MIN=0
+# MEGA_PG_POOL_MAX=10
+# MEGA_PG_POOL_IDLE_TIMEOUT_MS=10000
+# 드라이버 특화 옵션 예:
+# MEGA_PG_OPTIONS_SSL=true                          # → options.ssl
+# MEGA_PG_OPTIONS_STATEMENT_TIMEOUT=30000           # → options.statement_timeout (pg=snake)
+# MEGA_MONGO_OPTIONS_AUTH_SOURCE=admin              # → options.authSource (mongo=camel)
+# MEGA_MONGO_OPTIONS_SERVER_SELECTION_TIMEOUT_MS=5000  # → options.serverSelectionTimeoutMS
+# MEGA_MARIA_OPTIONS_BIG_INT_STRATEGY=number        # number(기본,2^53 초과 손실) | bigint | string