mega-framework 0.1.4 → 0.1.6

package/src/core/mega-app.js

@@ -403,36 +403,40 @@ export class MegaApp {
     // onRoute 훅 등록 이후라 자동 envelope 적용됨. config.skip{Asp,Csrf,RateLimit} 3종이 각 보안 hook 의
     // 면제 신호다(ADR-072 면제 실효, ADR-127): ASP onRequest·CSRF preHandler·rate-limit allowList 가 검사.
     const HEALTH_EXEMPT = { skipAsp: true, skipCsrf: true, skipRateLimit: true }
-
-    // /health — liveness (항상 200)
-    this.fastify.get('/health', { config: HEALTH_EXEMPT }, async () => ({
-      status: 'ok',
-      app: this.name,
-      uptime_ms: Math.floor(process.uptime() * 1000),
-      ts: Date.now(),
-    }))
-
-    // /health/ready — readiness (checkAll 후 200 or 503)
-    this.fastify.get('/health/ready', { config: HEALTH_EXEMPT }, async (req, reply) => {
-      const snapshot = await MegaHealth.checkAll()
-      if (!snapshot.ok) reply.code(503)
-      return {
+    const healthCfg = opts.health && typeof opts.health === 'object' ? opts.health : {}
+    // 헬스 경로(ADR-072/181) — 설정 가능. 미지정/빈 문자열이면 기본 /health · /health/ready.
+    const livePath = typeof healthCfg.paths?.live === 'string' && healthCfg.paths.live.length > 0 ? healthCfg.paths.live : '/health'
+    const readyPath = typeof healthCfg.paths?.ready === 'string' && healthCfg.paths.ready.length > 0 ? healthCfg.paths.ready : '/health/ready'
+
+    // health 라우트 등록 — `health.enabled:false` 면 생략(ADR-181). 기본(미지정/true)은 등록한다.
+    if (healthCfg.enabled !== false) {
+      // liveness (항상 200)
+      this.fastify.get(livePath, { config: HEALTH_EXEMPT }, async () => ({
+        status: 'ok',
         app: this.name,
-        ...snapshot,
         uptime_ms: Math.floor(process.uptime() * 1000),
         ts: Date.now(),
-      }
-    })
+      }))
+
+      // readiness (checkAll 후 200 or 503)
+      this.fastify.get(readyPath, { config: HEALTH_EXEMPT }, async (req, reply) => {
+        const snapshot = await MegaHealth.checkAll()
+        if (!snapshot.ok) reply.code(503)
+        return {
+          app: this.name,
+          ...snapshot,
+          uptime_ms: Math.floor(process.uptime() * 1000),
+          ts: Date.now(),
+        }
+      })
+    }
 
     // /metrics — Prometheus 옵트인 (ADR-072/131). exposeMetrics:true 일 때만 등록 →
     // 디폴트(미등록)는 Fastify 가 404(roadmap 검증 기준). /health 와 동일 보안 면제(HEALTH_EXEMPT).
     // 접근 제어 = IP allowList(ADR-131) — 빈 list 면 메인 포트 전체 노출(운영자 결정).
-    const healthCfg = opts.health && typeof opts.health === 'object' ? opts.health : {}
     if (healthCfg.exposeMetrics === true) {
       const metricsPath = typeof healthCfg.metricsPath === 'string' && healthCfg.metricsPath.length > 0 ? healthCfg.metricsPath : '/metrics'
-      // metricsPath 충돌 검증(ADR-072/04-data-models) — health 경로와 겹치면 부팅 throw(fail-fast).
-      const livePath = healthCfg.paths?.live ?? '/health'
-      const readyPath = healthCfg.paths?.ready ?? '/health/ready'
+      // metricsPath 충돌 검증(ADR-072/04-data-models) — health 경로(위에서 해석)와 겹치면 부팅 throw(fail-fast).
       if (metricsPath === livePath || metricsPath === readyPath) {
         throw new MegaConfigError(
           'health.metrics_path_conflict',

package/src/core/mega-cluster.js

@@ -35,6 +35,8 @@ export class MegaCluster {
    * @param {number} [opts.gracePeriodMs=30000] - SIGTERM 후 강제 kill 까지 대기
    * @param {import('node:cluster').Cluster} [opts._cluster] - 테스트용 cluster 주입(기본 node:cluster). per ADR-165
    * @param {NodeJS.Process} [opts._proc] - 테스트용 process 주입(기본 전역 process). per ADR-165
+   * @param {{ info?: Function, warn?: Function, error?: Function } | null} [opts.logger] - 조율 로그용 pino 로거.
+   *   미설정이면 console 폴백(마스터는 bootApp 을 안 해 pino 인스턴스가 없을 수 있다, ADR-180).
    */
   constructor(opts = {}) {
     this._instances = resolveInstances(opts.instances)
@@ -45,6 +47,8 @@ export class MegaCluster {
     // cluster/process 를 주입 seam 으로 분리해 fake 로 in-process 단위 검증한다. per ADR-165
     this._cluster = opts._cluster ?? cluster
     this._proc = opts._proc ?? process
+    /** @type {{ info?: Function, warn?: Function, error?: Function } | null} 조율 로그용 로거(없으면 console). */
+    this._logger = opts.logger ?? null
     /** @type {Set<MegaWorker>} */
     this._workers = new Set()
     /** @type {(() => Promise<void>) | null} */
@@ -92,12 +96,43 @@ export class MegaCluster {
     return !this._cluster.isPrimary
   }
 
+  /**
+   * 조율 로그용 로거 주입(생성 후, start 전에 호출). 마스터는 bootApp 을 안 해 pino 가 없으므로 CLI 가
+   * config 로 만든 인스턴스를 넘긴다(ADR-180). 미주입이면 console 폴백.
+   * @param {{ info?: Function, warn?: Function, error?: Function } | null | undefined} logger
+   * @returns {void}
+   */
+  setLogger(logger) {
+    this._logger = logger ?? null
+  }
+
+  /**
+   * @private 조율 로그 — 주입 로거가 있으면 그 레벨로, 없으면 console 폴백(`[mega-cluster]` 접두).
+   * @param {'info'|'warn'|'error'} level @param {string} msg
+   */
+  _log(level, msg) {
+    const log = this._logger
+    const text = `[mega-cluster] ${msg}`
+    if (log && typeof (/** @type {any} */ (log)[level]) === 'function') /** @type {any} */ (log)[level](text)
+    else (level === 'warn' ? console.warn : level === 'error' ? console.error : console.log)(text)
+  }
+
   /**
    * @private 마스터 프로세스 부팅 시퀀스.
    * @param {() => Promise<void>} workerFn
    */
   async _startPrimary(workerFn) {
     this._workerFn = workerFn
+    // 멀티워커 + watch 방어(ADR-182) — 워커는 마스터의 `execArgv` 를 상속하므로, `--watch*` 가 있으면
+    // 제거해 각 워커가 자기-watch 로 폭주(파일 변경 시 제각각 재시작)하는 것을 막는다. dev 권장 경로는
+    // 단일 프로세스(`mega start --watch`)라 보통 안 타지만, 수동 `node --watch … mega start --cluster N`
+    // 케이스의 방어 가드다. 단언이 아닌 setupPrimary 로 fork 전에 1회 적용.
+    const execArgv = this._proc.execArgv ?? []
+    const cleaned = execArgv.filter((a) => !a.startsWith('--watch'))
+    if (cleaned.length !== execArgv.length && typeof this._cluster.setupPrimary === 'function') {
+      this._cluster.setupPrimary({ execArgv: cleaned })
+      this._log('warn', 'stripped --watch* from worker execArgv (multi-worker watch chaos guard, ADR-182)')
+    }
     // workerFn 은 마스터에서 사용 안 함 (정보 전달용 placeholder)
     for (let i = 0; i < this._instances; i++) {
       this._forkWorker()
@@ -107,13 +142,13 @@ export class MegaCluster {
     const onSignal = (/** @type {string} */ sig) => {
       if (this._shuttingDown) return
       this._shuttingDown = true
-      console.log(`[mega-cluster] received ${sig}, broadcasting shutdown to ${this._workers.size} workers (grace ${this._gracePeriodMs}ms)`)
+      this._log('info', `received ${sig}, broadcasting shutdown to ${this._workers.size} workers (grace ${this._gracePeriodMs}ms)`)
       this._broadcastShutdown()
       // grace 초과 시 강제 kill. 핸들을 보관해 전원 정상종료(exit 핸들러) 시 취소 — 정상 종료가 이 타이머의
       // exit(1) 과 경합해 exit code 가 흔들리지 않게 한다(k8s/systemd 종료 판정 노이즈 제거).
       this._graceTimer = setTimeout(() => {
         for (const w of this._workers) {
-          try { w.kill('SIGKILL') } catch (err) { console.warn('[mega-cluster] SIGKILL failed:', err.message) }
+          try { w.kill('SIGKILL') } catch (err) { this._log('warn', `SIGKILL failed: ${err.message}`) }
         }
         this._proc.exit(1)
       }, this._gracePeriodMs)
@@ -134,7 +169,7 @@ export class MegaCluster {
         if (this._workers.size === 0) {
           if (this._graceTimer) clearTimeout(this._graceTimer) // 전원 정상종료 — 강제-kill 타이머 취소(exit code 경합 제거).
           this._graceTimer = null
-          console.log('[mega-cluster] all workers exited, primary exiting 0')
+          this._log('info', 'all workers exited, primary exiting 0')
           this._proc.exit(0)
         }
         return
@@ -152,19 +187,21 @@ export class MegaCluster {
           if (this._rapidCrashTimes.length >= this._maxRapidRespawn) {
             // H-1 — crash-loop 포기 시 그냥 return 하면 이벤트루프가 비어 exit 0(성공)으로 보인다 →
             //   systemd/k8s 가 "정상 종료" 로 오판. 명시적 exit 1 로 비정상 종료를 알려 재시작을 유도한다.
-            console.error(
-              `[mega-cluster] rapid crash-loop detected (${this._rapidCrashTimes.length} rapid crashes within ${windowMs}ms), giving up — exiting 1. Last exit: code=${code}, signal=${signal}.`,
+            this._log(
+              'error',
+              `rapid crash-loop detected (${this._rapidCrashTimes.length} rapid crashes within ${windowMs}ms), giving up — exiting 1. Last exit: code=${code}, signal=${signal}.`,
             )
             this._proc.exit(1)
             return   // 실 process.exit 은 즉시 종료하나, 주입된 fake 는 계속 실행되므로 명시적 중단
           }
         }
-        console.warn(
-          `[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}, lifetime=${lifetimeMs}ms), respawning (rapid-crashes=${this._rapidCrashTimes.length}/${this._maxRapidRespawn} in ${windowMs}ms)`,
+        this._log(
+          'warn',
+          `worker ${worker.process.pid} died (code=${code}, signal=${signal}, lifetime=${lifetimeMs}ms), respawning (rapid-crashes=${this._rapidCrashTimes.length}/${this._maxRapidRespawn} in ${windowMs}ms)`,
         )
         this._forkWorker()
       } else {
-        console.warn(`[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}), respawn disabled`)
+        this._log('warn', `worker ${worker.process.pid} died (code=${code}, signal=${signal}), respawn disabled`)
       }
     })
   }
@@ -176,7 +213,7 @@ export class MegaCluster {
         w.send({ type: SHUTDOWN_MSG })
       } catch (err) {
         // 워커가 이미 disconnected — 무시 + 로그 (silent 금지)
-        console.warn(`[mega-cluster] failed to send shutdown to worker ${w.process.pid}:`, err.message)
+        this._log('warn', `failed to send shutdown to worker ${w.process.pid}: ${err.message}`)
       }
     }
   }
@@ -199,8 +236,9 @@ export class MegaCluster {
         //   핸들러가 있었으면 true, 없으면 false → 무핸들러 경고.
         const hadListener = this._proc.emit('SIGTERM')
         if (!hadListener) {
-          console.warn(
-            `[mega-cluster] worker ${this._proc.pid} has no SIGTERM handler registered. Will be force-killed by master after grace period. ` +
+          this._log(
+            'warn',
+            `worker ${this._proc.pid} has no SIGTERM handler registered. Will be force-killed by master after grace period. ` +
               `Register a SIGTERM handler (or use MegaShutdown.setupSignals) to enable graceful shutdown.`,
           )
         }
@@ -211,7 +249,7 @@ export class MegaCluster {
     try {
       await workerFn()
     } catch (err) {
-      console.error(`[mega-cluster] worker ${this._proc.pid} workerFn failed:`, err)
+      this._log('error', `worker ${this._proc.pid} workerFn failed: ${/** @type {any} */ (err)?.stack ?? err}`)
       this._proc.exit(1)
     }
   }

package/src/core/scope-registry.js

@@ -16,7 +16,6 @@ export const GLOBAL_ONLY_KEYS = Object.freeze([
   'apps', // 활성 앱 whitelist (ADR-066)
   'asp', // masterSecret 등 시크릿
   'health', // /health, /health/ready
-  'tracing', // OpenTelemetry (ADR-077)
   'plugins', // 명시 등록 배열 (ADR-079)
   'jobs', // MegaJob 서브클래스 배열 — mega worker 가 소비 (ADR-123)
   'schedules', // MegaSchedule 서브클래스 배열 — mega scheduler 가 소비 (ADR-123)

package/src/lib/mega-logger.js

@@ -133,7 +133,7 @@ function mergeRedact(userRedact) {
 /**
  * `logger` config → pino 옵션(또는 비활성 시 `null`). Fastify `logger` 또는 `pino()` 에 그대로 전달 가능.
  *
- * @param {unknown} config - `MegaLoggerConfig`(`{ level, sinks, redact?, includeRequestId? }`).
+ * @param {unknown} config - `MegaLoggerConfig`(`{ level, sinks, redact? }`).
  * @returns {{ level: string, mixin: Function, redact: { paths: string[] }, transport: { targets: any[] } } | null}
  */
 export function buildLoggerOptions(config) {

package/src/lib/mega-shutdown.js

@@ -37,6 +37,14 @@ let globalErrorsRegistered = false
 let unhandledRejectionHandler = null
 /** @type {((err: Error, origin?: string) => void) | null} */
 let uncaughtExceptionHandler = null
+/**
+ * 전역 에러 핸들러가 fatal 로그에 쓸 로거. boot 이 pino 공유 인스턴스(appLogger)를 주입한다(setLogger).
+ * 미설정(부팅 전 조기 크래시·로거 비활성 프로세스)이면 console.error 로 폴백한다. process 레벨 핸들러는
+ * bootApp 의 DI 그래프 밖이라 모듈 스코프 변수로 받아 둔다(전역 오염 회피, ADR-178).
+ * @typedef {{ info?: (...args: any[]) => void, warn?: (...args: any[]) => void, error?: (...args: any[]) => void, fatal?: (...args: any[]) => void }} ShutdownLogger
+ * @type {ShutdownLogger | null}
+ */
+let shutdownLogger = null
 
 /**
  * cleanup hook 등록. 순서는 등록 역순(LIFO)으로 실행.
@@ -111,22 +119,40 @@ function setupGlobalErrorHandlers({ exitCode = 1 } = {}) {
   if (globalErrorsRegistered) return
   globalErrorsRegistered = true
   unhandledRejectionHandler = (reason) => {
-    const log = /** @type {any} */ (globalThis).logger
     const err = reason instanceof Error ? reason : new Error(`unhandledRejection: ${String(reason)}`)
-    if (log?.fatal) log.fatal({ err }, 'unhandledRejection — initiating graceful shutdown')
-    else console.error('[mega-shutdown] unhandledRejection — initiating graceful shutdown:', err)
+    logShutdown('fatal', 'unhandledRejection — initiating graceful shutdown', { err })
     void now({ signal: 'unhandledRejection', exitCode })
   }
   uncaughtExceptionHandler = (err, origin) => {
-    const log = /** @type {any} */ (globalThis).logger
-    if (log?.fatal) log.fatal({ err, origin }, 'uncaughtException — initiating graceful shutdown')
-    else console.error('[mega-shutdown] uncaughtException — initiating graceful shutdown:', err, origin)
+    logShutdown('fatal', 'uncaughtException — initiating graceful shutdown', { err, origin })
     void now({ signal: 'uncaughtException', exitCode })
   }
   process.on('unhandledRejection', unhandledRejectionHandler)
   process.on('uncaughtException', uncaughtExceptionHandler)
 }
 
+/**
+ * 종료 시퀀스 로깅 — 주입된 로거(setLogger)가 있으면 그 레벨 메서드로, 없으면 console 폴백.
+ * process 레벨 종료 경로라 로거 미주입(부팅 전·로거 비활성 프로세스)일 수 있어 항상 폴백을 갖춘다.
+ * `fatal` 은 console 에 없으므로 폴백에선 `console.error` 로 매핑한다. fields 는 구조적 로그의 payload
+ * (pino `log.level(fields, msg)`)이자 console 폴백의 보조 인자.
+ * @param {'info'|'warn'|'error'|'fatal'} level - 로그 레벨.
+ * @param {string} msg - 메시지.
+ * @param {Record<string, any>} [fields] - 구조적 필드(선택).
+ * @returns {void}
+ */
+function logShutdown(level, msg, fields) {
+  const log = shutdownLogger
+  if (log && typeof (/** @type {any} */ (log)[level]) === 'function') {
+    if (fields) /** @type {any} */ (log)[level](fields, msg)
+    else /** @type {any} */ (log)[level](msg)
+    return
+  }
+  const consoleFn = level === 'warn' ? console.warn : level === 'info' ? console.log : console.error
+  if (fields) consoleFn(`[mega-shutdown] ${msg}`, fields)
+  else consoleFn(`[mega-shutdown] ${msg}`)
+}
+
 /**
  * 즉시 graceful shutdown 트리거.
  *
@@ -138,17 +164,17 @@ function setupGlobalErrorHandlers({ exitCode = 1 } = {}) {
 async function now({ signal, exitCode = 0 } = {}) {
   // M-3 — 두 번째 shutdown 시그널: 이미 진행 중이면 grace 무시하고 즉시 force exit 1.
   if (isShuttingDownFlag) {
-    console.error('[mega-shutdown] MegaShutdown: second shutdown signal — force exit 1')
+    logShutdown('error', 'second shutdown signal — force exit 1')
     process.exit(1)
     return   // process.exit mock 시(테스트) 아래로 흐르지 않도록 가드
   }
   isShuttingDownFlag = true
 
-  console.log(`[mega-shutdown] starting (signal=${signal ?? 'manual'}, handlers=${handlers.length}, grace=${gracePeriodMs}ms)`)
+  logShutdown('info', 'shutdown starting', { signal: signal ?? 'manual', handlers: handlers.length, graceMs: gracePeriodMs })
 
   // hardKill 보호 — hardKillMs 초과 시 강제 종료
   const hardKillTimer = setTimeout(() => {
-    console.error('[mega-shutdown] grace period exceeded, force exit(1)')
+    logShutdown('error', 'grace period exceeded — force exit(1)', { hardKillMs })
     process.exit(1)
   }, hardKillMs)
   hardKillTimer.unref()
@@ -158,7 +184,7 @@ async function now({ signal, exitCode = 0 } = {}) {
     const { name, fn } = handlers[i]
     if (exitedHandlers.has(i)) continue
     try {
-      console.log(`[mega-shutdown] running '${name}'`)
+      logShutdown('info', `running hook '${name}'`, { hook: name })
       await Promise.race([
         Promise.resolve(fn()),
         new Promise((_, reject) =>
@@ -166,18 +192,28 @@ async function now({ signal, exitCode = 0 } = {}) {
         ),
       ])
       exitedHandlers.add(i)
-      console.log(`[mega-shutdown] '${name}' done`)
+      logShutdown('info', `hook '${name}' done`, { hook: name })
     } catch (err) {
       // silent 금지. 핸들러 실패 시 warn 로그 + 다음 hook 진행.
-      console.warn(`[mega-shutdown] '${name}' failed (continuing):`, err?.message ?? err)
+      logShutdown('warn', `hook '${name}' failed (continuing)`, { hook: name, err: /** @type {any} */ (err)?.message ?? err })
     }
   }
 
   clearTimeout(hardKillTimer)
-  console.log(`[mega-shutdown] complete, exit(${exitCode})`)
+  logShutdown('info', `shutdown complete — exit(${exitCode})`, { exitCode })
   process.exit(exitCode)
 }
 
+/**
+ * 전역 에러 핸들러(unhandledRejection/uncaughtException)가 fatal 로그에 쓸 로거를 주입한다(ADR-178).
+ * boot 이 pino 공유 인스턴스(appLogger)를 만들 때 호출한다. 미호출이면 핸들러는 console.error 로 폴백한다.
+ * @param {ShutdownLogger | null | undefined} logger - pino 호환 로거(info/warn/error/fatal 사용) 또는 null.
+ * @returns {void}
+ */
+function setLogger(logger) {
+  shutdownLogger = logger ?? null  
+}
+
 /**
  * 테스트용 — 등록된 hook 수 (디버그).
  * @returns {number}
@@ -202,6 +238,7 @@ function _reset() {
   unhandledRejectionHandler = null
   uncaughtExceptionHandler = null
   globalErrorsRegistered = false
+  shutdownLogger = null
 }
 
 /**
@@ -214,6 +251,7 @@ export const MegaShutdown = {
   isShuttingDown,
   setupSignals,
   setupGlobalErrorHandlers,
+  setLogger,
   now,
   registeredCount,
   _reset,

package/sample/crud/test/apps/main/auth-flow.integration.test.js

@@ -1,177 +0,0 @@
-// @ts-check
-/**
- * 인증 흐름 통합 테스트(ADR-155) — 실 redis(세션·brute-force) + postgres 로 sample/crud 를 부팅하고
- * HTTP 전 경로(회원가입→자동로그인→보호자원→로그아웃→차단, 잘못된 비밀번호→brute-force 잠금)를 검증한다.
- *
- * 인프라(redis·pg) env 가 없으면 통째로 skip 한다(단위 테스트는 `auth-service.test.js` 가 인프라 없이 커버).
- * 실행에 필요한 env(.env): DATABASE_URL(또는 PG_URL)·REDIS_SESSION_URL·REDIS_RATE_URL·SESSION_SECRET.
- *
- * CSRF(쿠키 double-submit, ADR-051)가 켜져 있어 POST 마다 폼 토큰+쿠키를 왕복시킨다 — 실제 브라우저 폼과
- * 같은 경로다. 세션 쿠키(mega.sid)도 누적 쿠키 jar 로 왕복한다.
- */
-import { describe, test, expect, beforeAll, afterAll } from 'vitest'
-import { bootApp, MegaShutdown } from 'mega-framework'
-import { fileURLToPath } from 'node:url'
-import { dirname, resolve } from 'node:path'
-import { User } from '../../../apps/main/models/user.js'
-
-// 프로젝트 루트(mega.config.js 가 있는 sample/crud) — 이 파일 기준 상위 4단계.
-const PROJECT = resolve(dirname(fileURLToPath(import.meta.url)), '../../..')
-
-// .env 가 DATABASE_URL 대신 PG_URL 만 줄 수 있으므로(로컬 관례) 매핑한다.
-if (!process.env.DATABASE_URL && process.env.PG_URL) process.env.DATABASE_URL = process.env.PG_URL
-
-const hasInfra = Boolean(process.env.DATABASE_URL && process.env.REDIS_SESSION_URL && process.env.REDIS_RATE_URL && process.env.SESSION_SECRET)
-const d = hasInfra ? describe : describe.skip
-
-/** set-cookie 를 누적 쿠키 jar 에 반영(maxAge=0 → 삭제). @param {any} res @param {Record<string,string>} jar */
-function applyCookies(res, jar) {
-  const raw = res.headers['set-cookie']
-  const arr = Array.isArray(raw) ? raw : raw ? [raw] : []
-  for (const c of arr) {
-    const pair = String(c).split(';')[0]
-    const eq = pair.indexOf('=')
-    if (eq === -1) continue
-    const name = pair.slice(0, eq).trim()
-    const val = pair.slice(eq + 1).trim()
-    if (val === '') delete jar[name]
-    else jar[name] = val
-  }
-}
-
-/** @param {Record<string,string>} jar @returns {string} Cookie 헤더. */
-function cookieHeader(jar) {
-  return Object.entries(jar).map(([k, v]) => `${k}=${v}`).join('; ')
-}
-
-/** 렌더된 폼 HTML 에서 hidden `_csrf` 토큰을 뽑는다. @param {string} html @returns {string} */
-function csrfFrom(html) {
-  const m = /name="_csrf" value="([^"]+)"/.exec(html)
-  if (!m) throw new Error('csrf token not found in form HTML')
-  return m[1]
-}
-
-/** urlencoded 폼 바디 직렬화. @param {Record<string,string>} fields @returns {string} */
-function form(fields) {
-  return Object.entries(fields).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&')
-}
-
-d('인증 흐름 E2E — sample/crud 실 redis+pg (ADR-155)', () => {
-  /** @type {Awaited<ReturnType<typeof bootApp>>} */
-  let boot
-  /** @type {any} */
-  let fastify
-  const EMAIL = `itest-auth-${Date.now()}@example.com`
-  const PASSWORD = 'secret-pass-123'
-  const NAME = 'Auth Tester'
-
-  beforeAll(async () => {
-    MegaShutdown._reset()
-    boot = await bootApp(PROJECT, { listen: false })
-    const app = boot.megaApps.find((a) => a.name === 'main')
-    fastify = app?.fastify
-    await fastify.ready() // onReady → 세션 store connect(실 redis).
-    // 스키마 보장(마이그레이션과 동치, 멱등) — 테스트 전제. 실제 운영은 `mega migrate` 가 적용한다.
-    await User.query('CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE, created_at TIMESTAMPTZ NOT NULL DEFAULT now())')
-    await User.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS password_hash TEXT')
-    await User.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS last_login_at TIMESTAMPTZ')
-    await User.query('DELETE FROM users WHERE email = $1', [EMAIL])
-  })
-
-  afterAll(async () => {
-    if (!boot) return
-    await User.query('DELETE FROM users WHERE email = $1', [EMAIL]).catch(() => {})
-    await fastify?.close().catch(() => {})
-    const app = boot.megaApps.find((a) => a.name === 'main')
-    await app?.sessionStore?.disconnect().catch(() => {})
-    await boot.ctx.cache('rate').disconnect().catch(() => {})
-    await boot.ctx.db('primary').disconnect().catch(() => {})
-    MegaShutdown._reset()
-  })
-
-  test('비로그인: 랜딩(/)은 공개 200, /admin/users 는 로그인으로 302, /users API 는 401', async () => {
-    const home = await fastify.inject({ method: 'GET', url: '/' })
-    expect(home.statusCode).toBe(200)
-
-    const admin = await fastify.inject({ method: 'GET', url: '/admin/users' })
-    expect(admin.statusCode).toBe(302)
-    expect(admin.headers.location).toBe('/auth/login')
-
-    const api = await fastify.inject({ method: 'GET', url: '/users' })
-    expect(api.statusCode).toBe(401)
-    expect(api.json().error?.code).toBe('auth.required')
-  })
-
-  test('회원가입 → 자동 로그인 → 보호자원 접근 → API 접근 → 로그아웃 → 재차단', async () => {
-    /** @type {Record<string,string>} */
-    const jar = {}
-
-    // 1) 회원가입 폼 GET — _csrf 쿠키 + 토큰 확보.
-    const regForm = await fastify.inject({ method: 'GET', url: '/register' })
-    expect(regForm.statusCode).toBe(200)
-    applyCookies(regForm, jar)
-    const regToken = csrfFrom(regForm.body)
-
-    // 2) 회원가입 POST — 성공 시 자동 로그인(세션 발급) + /admin/users 로 302.
-    const reg = await fastify.inject({
-      method: 'POST',
-      url: '/register',
-      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
-      payload: form({ _csrf: regToken, name: NAME, email: EMAIL, password: PASSWORD }),
-    })
-    expect(reg.statusCode).toBe(302)
-    expect(reg.headers.location).toBe('/admin/users?notice=registered')
-    applyCookies(reg, jar)
-    expect(jar['mega.sid']).toBeTruthy() // 세션 쿠키 발급됨.
-
-    // 3) 보호 자원 GET — 세션 쿠키로 통과(200), 본문에 로그인 사용자 이름 표시.
-    const admin = await fastify.inject({ method: 'GET', url: '/admin/users', headers: { cookie: cookieHeader(jar) } })
-    expect(admin.statusCode).toBe(200)
-    expect(admin.body).toContain(NAME)
-    applyCookies(admin, jar)
-
-    // 4) JSON API GET — 같은 세션으로 통과(envelope ok).
-    const api = await fastify.inject({ method: 'GET', url: '/users', headers: { cookie: cookieHeader(jar) } })
-    expect(api.statusCode).toBe(200)
-    expect(api.json().ok).toBe(true)
-
-    // 5) 로그아웃 POST — 보호 페이지에서 받은 _csrf 토큰으로.
-    const logoutToken = csrfFrom(admin.body)
-    const logout = await fastify.inject({
-      method: 'POST',
-      url: '/auth/logout',
-      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
-      payload: form({ _csrf: logoutToken }),
-    })
-    expect(logout.statusCode).toBe(302)
-    expect(logout.headers.location).toBe('/auth/login?notice=logged_out')
-    applyCookies(logout, jar)
-
-    // 6) 로그아웃 후 보호 자원 재차단(302 → 로그인).
-    const blocked = await fastify.inject({ method: 'GET', url: '/admin/users', headers: { cookie: cookieHeader(jar) } })
-    expect(blocked.statusCode).toBe(302)
-    expect(blocked.headers.location).toBe('/auth/login')
-  })
-
-  test('잘못된 비밀번호 반복 → brute-force 잠금(423)', async () => {
-    const lockEmail = `itest-lock-${Date.now()}@example.com`
-    // 잠금 임계(기본 maxAttempts=5)까지 틀린 로그인을 반복한다. 없는 계정이라도 brute-force 는 subject(IP:email) 기준.
-    let lastStatus = 0
-    for (let i = 0; i < 6; i++) {
-      /** @type {Record<string,string>} */
-      const jar = {}
-      const formPage = await fastify.inject({ method: 'GET', url: '/auth/login' })
-      applyCookies(formPage, jar)
-      const token = csrfFrom(formPage.body)
-      const res = await fastify.inject({
-        method: 'POST',
-        url: '/auth/login',
-        headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
-        payload: form({ _csrf: token, email: lockEmail, password: 'definitely-wrong' }),
-      })
-      lastStatus = res.statusCode
-    }
-    // 임계 도달 후에는 잠금(423)으로 응답한다(401 invalid 가 아니라).
-    expect(lastStatus).toBe(423)
-  })
-})

package/sample/crud/test/apps/main/auth-service.test.js

@@ -1,93 +0,0 @@
-// @ts-check
-/**
- * AuthService 단위 테스트(ADR-155) — 모델(static)을 스파이로 갈음해 DB 없이 비즈니스 로직을 검증한다.
- * 해싱은 실 MegaHash(scrypt)를 그대로 써서 register→authenticate 왕복이 진짜로 맞물리는지 본다(인프라 불필요).
- */
-import { describe, test, expect, vi, afterEach } from 'vitest'
-import { AuthService } from '../../../apps/main/services/auth-service.js'
-import { User } from '../../../apps/main/models/user.js'
-
-/** @returns {AuthService} */
-function makeService() {
-  return new AuthService(/** @type {any} */ ({ log: { debug() {} } }))
-}
-
-afterEach(() => vi.restoreAllMocks())
-
-describe('AuthService.register', () => {
-  test('유효 입력 → 해시 후 User.register 위임(평문 미저장)', async () => {
-    const reg = vi
-      .spyOn(User, 'register')
-      .mockResolvedValue(/** @type {any} */ ({ id: 1, name: 'Ada', email: 'ada@x.io', created_at: 't' }))
-    const out = await makeService().register({ name: ' Ada ', email: ' Ada@X.io ', password: 'secret-12' })
-    expect(out).toEqual({ id: 1, name: 'Ada', email: 'ada@x.io', created_at: 't' })
-    const arg = reg.mock.calls[0][0]
-    expect(arg.name).toBe('Ada') // trim.
-    expect(arg.email).toBe('ada@x.io') // trim + lowercase.
-    expect(arg.passwordHash).toMatch(/^\$scrypt\$/) // 평문이 아니라 scrypt 해시.
-    expect(arg.passwordHash).not.toContain('secret-12')
-  })
-
-  test('이름/이메일 누락 → MegaValidationError(auth.invalid)', async () => {
-    await expect(makeService().register({ name: '', email: 'a@b.c', password: 'secret-12' })).rejects.toMatchObject({
-      code: 'auth.invalid',
-    })
-  })
-
-  test('비밀번호 8자 미만 → MegaValidationError(auth.invalid)', async () => {
-    await expect(makeService().register({ name: 'Ada', email: 'a@b.c', password: 'short' })).rejects.toMatchObject({
-      code: 'auth.invalid',
-    })
-  })
-
-  test('이메일 중복(23505) → MegaConflictError(user.email_taken)', async () => {
-    vi.spyOn(User, 'register').mockRejectedValue(/** @type {any} */ (Object.assign(new Error('dup'), { code: '23505' })))
-    await expect(makeService().register({ name: 'Ada', email: 'a@b.c', password: 'secret-12' })).rejects.toMatchObject({
-      status: 409,
-      code: 'user.email_taken',
-    })
-  })
-})
-
-describe('AuthService.authenticate', () => {
-  test('올바른 비밀번호 → 신원 반환 + last_login 갱신', async () => {
-    const { MegaHash } = await import('mega-framework')
-    const hash = await MegaHash.password.hash('secret-12')
-    vi.spyOn(User, 'findByEmailWithHash').mockResolvedValue(
-      /** @type {any} */ ({ id: 7, name: 'Ada', email: 'ada@x.io', password_hash: hash }),
-    )
-    const touch = vi.spyOn(User, 'touchLastLogin').mockResolvedValue(undefined)
-    const out = await makeService().authenticate({ email: 'Ada@X.io', password: 'secret-12' })
-    expect(out).toEqual({ id: 7, name: 'Ada' })
-    expect(touch).toHaveBeenCalledWith(7)
-  })
-
-  test('틀린 비밀번호 → null(이유 비노출), last_login 미갱신', async () => {
-    const { MegaHash } = await import('mega-framework')
-    const hash = await MegaHash.password.hash('secret-12')
-    vi.spyOn(User, 'findByEmailWithHash').mockResolvedValue(
-      /** @type {any} */ ({ id: 7, name: 'Ada', email: 'ada@x.io', password_hash: hash }),
-    )
-    const touch = vi.spyOn(User, 'touchLastLogin').mockResolvedValue(undefined)
-    expect(await makeService().authenticate({ email: 'ada@x.io', password: 'wrong-pass' })).toBeNull()
-    expect(touch).not.toHaveBeenCalled()
-  })
-
-  test('없는 이메일 → null', async () => {
-    vi.spyOn(User, 'findByEmailWithHash').mockResolvedValue(null)
-    expect(await makeService().authenticate({ email: 'nope@x.io', password: 'secret-12' })).toBeNull()
-  })
-
-  test('비밀번호 미설정 계정(admin CRUD 생성) → null', async () => {
-    vi.spyOn(User, 'findByEmailWithHash').mockResolvedValue(
-      /** @type {any} */ ({ id: 3, name: 'NoPass', email: 'np@x.io', password_hash: null }),
-    )
-    expect(await makeService().authenticate({ email: 'np@x.io', password: 'secret-12' })).toBeNull()
-  })
-
-  test('이메일/비밀번호 공란 → null(조회 안 함)', async () => {
-    const find = vi.spyOn(User, 'findByEmailWithHash').mockResolvedValue(null)
-    expect(await makeService().authenticate({ email: '', password: '' })).toBeNull()
-    expect(find).not.toHaveBeenCalled()
-  })
-})