mega-framework 0.1.0

package/src/adapters/registry.js

@@ -0,0 +1,157 @@
+// @ts-check
+/**
+ * 어댑터 드라이버 레지스트리 (ADR-044, ADR-079).
+ *
+ * driver 이름 → 어댑터 클래스 매핑을 관리한다.
+ *   - **빌트인 8종** (`postgres / mongodb / mariadb / sqlite / redis / file / nats / redlock`) 은
+ *     각 구체 어댑터 모듈이 import 시 `register()` 로 자기 자신을 등록한다.
+ *     → 본 배럴은 매핑 *메커니즘* 만 제공하고, 구체 클래스는 위 어댑터 모듈들이 등록한다.
+ *   - **3rd party** 는 `config.adapters.register: { 'cassandra': MegaCassandraAdapter }` 를
+ *     {@link registerFromConfig} 로 주입 (ADR-044).
+ *
+ * 부팅 시 driver 매핑으로 `new AdapterClass(config)` 한다 (08-class-specs §3.2 lifecycle 1단계).
+ *
+ * 사용:
+ *   register('sqlite', MegaSqliteAdapter)        // 빌트인 자기 등록
+ *   registerFromConfig(config.adapters?.register) // 3rd party 주입
+ *   const AdapterClass = resolve('sqlite')        // 부팅 시 클래스 lookup
+ *
+ * @module adapters/registry
+ */
+import { MegaInternalError, MegaValidationError } from '../errors/http-errors.js'
+import { MegaAdapter } from './mega-adapter.js'
+
+/**
+ * 빌트인 driver 예약어 (ADR-044, ADR-082 file 포함, ADR-113 redlock 포함). 구체 클래스는 각 Step 에서 등록.
+ * 3rd party 가 이 이름을 점유하지 못하도록 예약 — `registerFromConfig` 가 거부.
+ * @type {ReadonlySet<string>}
+ */
+export const BUILTIN_DRIVERS = new Set([
+  'postgres',
+  'mongodb',
+  'mariadb',
+  'sqlite',
+  'redis',
+  'file',
+  'nats',
+  'redlock',
+])
+
+/** @type {Map<string, typeof MegaAdapter>} */
+const registry = new Map()
+
+/**
+ * driver 이름이 MegaAdapter 서브클래스 클래스인지 검증.
+ * @param {string} driver
+ * @param {unknown} AdapterClass
+ * @returns {void}
+ */
+function assertValid(driver, AdapterClass) {
+  if (typeof driver !== 'string' || driver.length === 0) {
+    throw new MegaValidationError('adapter.invalid_driver', 'driver name must be a non-empty string', {
+      details: { driver },
+    })
+  }
+  // MegaAdapter 자신(추상) 또는 그 서브클래스 생성자만 허용.
+  const isAdapterClass =
+    typeof AdapterClass === 'function' &&
+    (AdapterClass === MegaAdapter || AdapterClass.prototype instanceof MegaAdapter)
+  if (!isAdapterClass) {
+    throw new MegaValidationError(
+      'adapter.invalid_class',
+      `Adapter for driver "${driver}" must be a class extending MegaAdapter.`,
+      { details: { driver } },
+    )
+  }
+}
+
+/**
+ * driver → 어댑터 클래스 등록. 이미 같은 driver 가 **다른 클래스**로 등록돼 있으면 throw
+ * (silent override 방지). 같은 클래스 재등록은 idempotent no-op.
+ *
+ * @param {string} driver - driver 이름 (예: 'postgres').
+ * @param {typeof MegaAdapter} AdapterClass - MegaAdapter 를 상속한 어댑터 클래스.
+ * @returns {void}
+ */
+export function register(driver, AdapterClass) {
+  assertValid(driver, AdapterClass)
+  const existing = registry.get(driver)
+  if (existing !== undefined && existing !== AdapterClass) {
+    throw new MegaInternalError(
+      'adapter.driver_conflict',
+      `driver "${driver}" is already registered to ${existing.name}; cannot re-register to ${AdapterClass.name}.`,
+      { details: { driver, existing: existing.name, incoming: AdapterClass.name } },
+    )
+  }
+  registry.set(driver, AdapterClass)
+}
+
+/**
+ * `config.adapters.register` 맵을 일괄 등록 (ADR-044 3rd party). 빌트인 예약어 점유 시 throw.
+ *
+ * @param {Record<string, typeof MegaAdapter>} [registerMap]
+ * @returns {void}
+ */
+export function registerFromConfig(registerMap) {
+  if (registerMap === undefined || registerMap === null) return
+  // L5: 배열도 typeof 'object' 라 그냥 두면 Object.entries 가 인덱스를 driver 이름으로 등록한다.
+  // adapters.register 는 `{ driver: Class }` 평탄 객체만 허용 — 배열은 명시 거부.
+  if (typeof registerMap !== 'object' || Array.isArray(registerMap)) {
+    throw new MegaValidationError('adapter.invalid_register_map', 'adapters.register must be a plain object', {
+      details: { type: Array.isArray(registerMap) ? 'array' : typeof registerMap },
+    })
+  }
+  for (const [driver, AdapterClass] of Object.entries(registerMap)) {
+    if (BUILTIN_DRIVERS.has(driver)) {
+      throw new MegaInternalError(
+        'adapter.driver_conflict',
+        `driver "${driver}" is a builtin and cannot be overridden via adapters.register.`,
+        { details: { driver } },
+      )
+    }
+    register(driver, AdapterClass)
+  }
+}
+
+/**
+ * driver 이름으로 등록된 어댑터 클래스 조회. 없으면 `adapter.unknown_driver` throw.
+ *
+ * @param {string} driver
+ * @returns {typeof MegaAdapter}
+ */
+export function resolve(driver) {
+  const AdapterClass = registry.get(driver)
+  if (AdapterClass === undefined) {
+    throw new MegaValidationError(
+      'adapter.unknown_driver',
+      `Unknown adapter driver "${driver}". Registered: [${list().join(', ') || '(none)'}].`,
+      { details: { driver, registered: list() } },
+    )
+  }
+  return AdapterClass
+}
+
+/**
+ * driver 가 등록돼 있는지 (Boolean — `has*`, ADR-036).
+ * @param {string} driver
+ * @returns {boolean}
+ */
+export function has(driver) {
+  return registry.has(driver)
+}
+
+/**
+ * 등록된 driver 이름 목록.
+ * @returns {string[]}
+ */
+export function list() {
+  return [...registry.keys()]
+}
+
+/**
+ * 테스트용 reset — 등록 전부 비움.
+ * @returns {void}
+ */
+export function _reset() {
+  registry.clear()
+}

package/src/adapters/sqlite-adapter.js

@@ -0,0 +1,309 @@
+// @ts-check
+/**
+ * MegaSqliteAdapter — SQLite 어댑터 (`better-sqlite3` 래퍼, ADR-105).
+ *
+ * **첫 실 어댑터**. docker 없이 in-memory(`:memory:`) / file-based DB 로
+ * `MegaDbAdapter` 베이스 + `MegaModel` 정합을 끝단 검증하는 기준점이다.
+ *
+ * # 표준 표면 (MegaDbAdapter 상속)
+ *   - `_connect()`   — `new Database(filename, opts)` (driver 는 connect 시점 lazy import).
+ *   - `_disconnect()`— `db.close()`.
+ *   - `_native()`    — `better-sqlite3` Database 인스턴스(raw handle, ADR-009). `MegaModel.db` 가 노출.
+ *   - `healthCheck()`— `SELECT 1` 실행으로 실제 응답성 확인 (베이스 디폴트=상태만 → override).
+ *   - `getStats()`   — 베이스 stats + sqlite 특화(filename / inMemory / readonly / journalMode).
+ *   - `withTransaction(fn)` — 명시적 트랜잭션 경계 (ADR-010). 아래 "트랜잭션 패턴" 참조.
+ *
+ * # 트랜잭션 패턴 — manual `BEGIN/COMMIT/ROLLBACK` (중요)
+ *   `better-sqlite3` 의 `db.transaction(fn)` 은 **동기 콜백 전용**이다 — 공식 문서가
+ *   "async 함수는 첫 `await` 에서 반환되므로 실제 비동기 코드 실행 전에 트랜잭션이 이미
+ *   commit 된다"며 async 콜백을 명시적으로 금지한다. 그러나 `MegaDbAdapter.withTransaction(fn)`
+ *   계약의 `fn` 은 `async` 일 수 있다(`Promise<T>` 반환). 두 모델을 정합시키기 위해
+ *   `db.transaction()` 대신 **수동 `db.exec('BEGIN' | 'COMMIT' | 'ROLLBACK')`** 로 경계를 긋는다.
+ *   성공 시 COMMIT, `fn` throw 시 ROLLBACK 후 원본 에러 re-throw (ADR-010).
+ *
+ * # nested / 동시 트랜잭션 정책 — 재진입 거부 (ADR-105)
+ *   SQLite 는 본 어댑터당 **단일 연결**(`better-sqlite3` 는 connection-per-Database)이다. 이미
+ *   열린 트랜잭션 위에서 또 `BEGIN` 을 걸면 SQLite 가 거부한다. 게다가 `withTransaction(fn)` 은
+ *   async 라 `fn` 의 `await` 동안 다른 `withTransaction` 호출이 끼어들 수 있다(인터리빙). 두 경우
+ *   모두 `db.inTransaction`(better-sqlite3 공식 프로퍼티)으로 감지해 즉시
+ *   `adapter.nested_transaction_unsupported` 를 throw 한다 — postgres 의 SAVEPOINT 기반 nested 와
+ *   달리(08-class-specs §3.3), async 경계에서 SAVEPOINT 깊이 추적은 신뢰할 수 없어 **명시적 거부**가
+ *   silent 혼선보다 안전하다. MongoDB 어댑터와 동일한 에러 코드를 쓴다.
+ *
+ * # 설정 (services.databases.<key>)
+ *   ```js
+ *   services: {
+ *     databases: {
+ *       primary: {
+ *         driver: 'sqlite',
+ *         filename: ':memory:',          // 필수. ':memory:' = in-memory, 그 외 = 파일 경로
+ *         readonly: false,               // (옵션) 읽기 전용
+ *         fileMustExist: false,          // (옵션) 파일 없으면 throw
+ *         timeout: 5000,                 // (옵션) SQLITE_BUSY 대기 ms
+ *         wal: false,                    // (옵션) true → journal_mode=WAL
+ *         pragmas: { foreign_keys: 'ON' } // (옵션) connect 후 추가 PRAGMA 적용
+ *       },
+ *     },
+ *   }
+ *   ```
+ *
+ * @module adapters/sqlite-adapter
+ */
+import { MegaInternalError, MegaValidationError } from '../errors/http-errors.js'
+import { MegaDbAdapter } from './mega-db-adapter.js'
+import * as Registry from './registry.js'
+
+/**
+ * @typedef {object} SqliteConfig
+ * @property {string} [driver] - 'sqlite' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} filename - DB 파일 경로 또는 ':memory:' (필수).
+ * @property {boolean} [readonly] - 읽기 전용 연결.
+ * @property {boolean} [fileMustExist] - 파일이 없으면 connect 시 throw.
+ * @property {number} [timeout] - 잠긴 DB 대기 ms (SQLITE_BUSY 전, 기본 5000).
+ * @property {boolean} [wal] - true 면 connect 후 `journal_mode = WAL` 적용.
+ * @property {Record<string, string | number>} [pragmas] - connect 후 적용할 추가 PRAGMA 맵.
+ */
+
+export class MegaSqliteAdapter extends MegaDbAdapter {
+  /** @type {import('better-sqlite3').Database | null} 연결된 Database 인스턴스 (connect 후에만). */
+  #db = null
+  /** @type {string} DB 파일 경로 또는 ':memory:'. */
+  #filename
+  /** @type {{ readonly: boolean, fileMustExist: boolean, timeout?: number }} */
+  #openOptions
+  /** @type {boolean} */
+  #wal
+  /** @type {Record<string, string | number>} */
+  #pragmas
+  /** @type {string | undefined} connect 후 캐시된 journal_mode (연결 동안 불변, disconnect 시 리셋). */
+  #journalMode
+
+  /**
+   * @param {SqliteConfig} [config] - services.databases.<key> 설정.
+   * @throws {MegaValidationError} `sqlite.filename_required` - filename 누락/빈 문자열.
+   * @throws {MegaValidationError} `sqlite.invalid_option` - 옵션 타입 오류.
+   */
+  constructor(config = /** @type {any} */ ({})) {
+    super(config)
+
+    const filename = /** @type {any} */ (config).filename
+    // filename 은 필수 — 빈 문자열(=better-sqlite3 의 임시 on-disk DB)도 모호하므로 명시 거부.
+    if (typeof filename !== 'string' || filename.length === 0) {
+      throw new MegaValidationError(
+        'sqlite.filename_required',
+        "services.databases.<key>.filename is required for the sqlite driver (e.g. ':memory:' or '/path/to/app.db').",
+        { details: { filename: filename ?? null } },
+      )
+    }
+    this.#filename = filename
+
+    const { readonly = false, fileMustExist = false, timeout, wal = false, pragmas = {} } = config
+    // 부팅 시 fail-fast — connect 까지 미루지 않고 잘못된 옵션 타입을 생성자에서 잡는다.
+    this.#assertBool('readonly', readonly)
+    this.#assertBool('fileMustExist', fileMustExist)
+    this.#assertBool('wal', wal)
+    // better-sqlite3 는 timeout 0 이상을 허용(`timeout < 0` 만 거부)하나, 0ms 대기는 무의미하므로
+    // 우리는 **양의 정수만** 허용한다. 또 better-sqlite3 의 상한은 `0x7fffffff`(=2147483647)로 초과 시
+    // _connect() 의 RangeError 로 미뤄지므로, 부팅 fail-fast 를 위해 생성자에서 상·하한을 함께 잡는다.
+    // 미지정(undefined)이면 옵션 객체에서 키 자체를 뺀다(better-sqlite3 디폴트 5000ms).
+    if (timeout !== undefined && (!Number.isInteger(timeout) || timeout <= 0 || timeout > 0x7fffffff)) {
+      throw new MegaValidationError(
+        'sqlite.invalid_option',
+        'sqlite "timeout" must be a positive integer (ms) not greater than 2147483647.',
+        { details: { timeout } },
+      )
+    }
+    if (pragmas === null || typeof pragmas !== 'object' || Array.isArray(pragmas)) {
+      throw new MegaValidationError('sqlite.invalid_option', 'sqlite "pragmas" must be a plain object of { name: value }.', {
+        details: { type: Array.isArray(pragmas) ? 'array' : typeof pragmas },
+      })
+    }
+
+    this.#openOptions = timeout === undefined ? { readonly, fileMustExist } : { readonly, fileMustExist, timeout }
+    this.#wal = wal
+    this.#pragmas = pragmas
+  }
+
+  /**
+   * boolean 옵션 검증 헬퍼.
+   * @param {string} name @param {unknown} value @returns {void}
+   */
+  #assertBool(name, value) {
+    if (typeof value !== 'boolean') {
+      throw new MegaValidationError('sqlite.invalid_option', `sqlite "${name}" must be a boolean.`, {
+        details: { option: name, type: typeof value },
+      })
+    }
+  }
+
+  /**
+   * `better-sqlite3` Database 인스턴스 생성 + 옵션 PRAGMA 적용.
+   * driver 는 **connect 시점에 lazy import** — 모듈 import(배럴 경유 자기등록)만으로는
+   * native binding 을 로드하지 않아, 본 어댑터를 안 쓰는 환경이 better-sqlite3 설치를
+   * 강제받지 않는다(pg/mongo 등도 같은 패턴).
+   *
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _connect() {
+    // CJS 모듈 — ESM 동적 import 의 default 가 Database 생성자.
+    const { default: Database } = await import('better-sqlite3')
+    const db = new Database(this.#filename, this.#openOptions)
+    // WAL 은 동시 read/write 처리량을 높이는 표준 옵션 — 옵트인.
+    if (this.#wal) db.pragma('journal_mode = WAL')
+    for (const [name, value] of Object.entries(this.#pragmas)) {
+      db.pragma(`${name} = ${value}`)
+    }
+    this.#db = db
+    // journal_mode 는 connect 후 불변 → 한 번만 조회해 캐시. getStats() 가 매 호출마다
+    // PRAGMA SQL 을 실행하지 않도록(WAL 등 옵션 PRAGMA 적용 뒤의 최종값을 고정).
+    this.#journalMode = /** @type {any} */ (db.pragma('journal_mode', { simple: true }))
+  }
+
+  /**
+   * Database 연결 닫기. 베이스 상태 머신이 connected 상태에서만 호출을 보장한다.
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _disconnect() {
+    if (this.#db !== null) {
+      this.#db.close()
+      this.#db = null
+      // 캐시 무효화 — 다음 connect 가 새 값으로 다시 채운다(연결 끊긴 상태에선 journalMode 없음).
+      this.#journalMode = undefined
+    }
+  }
+
+  /**
+   * raw Database handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
+   * @protected
+   * @returns {import('better-sqlite3').Database}
+   */
+  _native() {
+    if (this.#db === null) {
+      // 베이스 native getter 가 state 검증을 먼저 하므로 정상 경로에선 도달 안 함 — 방어.
+      return this._notImplemented('native')
+    }
+    return this.#db
+  }
+
+  /**
+   * 헬스 체크 — 실제 `SELECT 1` 으로 응답성 확인 (베이스 디폴트는 상태만 반영).
+   * connect 전이거나 쿼리 실패면 `ok:false` + 사유. `/health/ready` 가 모든 어댑터 ok 를 AND.
+   *
+   * @returns {Promise<{ ok: boolean, driver: 'sqlite', state: string, filename?: string, error?: string }>}
+   */
+  async healthCheck() {
+    if (this.state !== 'connected' || this.#db === null) {
+      return { ok: false, driver: 'sqlite', state: this.state }
+    }
+    try {
+      const row = this.#db.prepare('SELECT 1 AS ok').get()
+      const ok = /** @type {any} */ (row)?.ok === 1
+      return { ok, driver: 'sqlite', state: this.state, filename: this.#filename }
+    } catch (err) {
+      // ping 실패는 비치명적 보고값 — healthCheck 는 throw 하지 않고 ok:false 로 표현(베이스 계약).
+      return {
+        ok: false,
+        driver: 'sqlite',
+        state: this.state,
+        filename: this.#filename,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+
+  /**
+   * 누적 통계 + sqlite 특화 필드.
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, filename: string, inMemory: boolean, readonly: boolean, journalMode: string | undefined }}
+   */
+  getStats() {
+    return {
+      ...super.getStats(),
+      driver: 'sqlite',
+      filename: this.#filename,
+      inMemory: this.#filename === ':memory:',
+      readonly: this.#openOptions.readonly,
+      // _connect() 에서 캐시한 불변값 사용 — 미연결이면 undefined(매 호출 PRAGMA 실행 제거, L-4).
+      journalMode: this.#journalMode,
+    }
+  }
+
+  /**
+   * 명시적 트랜잭션 경계 (ADR-010, ADR-105). manual `BEGIN/COMMIT/ROLLBACK` 으로
+   * async `fn` 과 better-sqlite3 의 동기 트랜잭션 모델을 정합시킨다(모듈 docstring 참조).
+   *
+   * `fn` 은 **트랜잭션 컨텍스트 native handle**(= 같은 Database 인스턴스)을 인자로 받는다.
+   * 성공 시 COMMIT 후 `fn` 반환값을 그대로 돌려주고, `fn` 이 throw 하면 ROLLBACK 후 원본 에러를
+   * re-throw 한다. nested / 동시 호출은 `db.inTransaction` 으로 감지해 거부(ADR-105).
+   *
+   * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
+   *
+   * @template T
+   * @param {(db: import('better-sqlite3').Database) => Promise<T> | T} fn
+   * @returns {Promise<T>}
+   * @throws {MegaInternalError} `adapter.nested_transaction_unsupported` - 이미 트랜잭션 진행 중.
+   */
+  async withTransaction(fn) {
+    return this._instrument('withTransaction', { table: undefined }, async () => {
+      const db = /** @type {import('better-sqlite3').Database} */ (this.#db)
+      if (db.inTransaction) {
+        throw new MegaInternalError(
+          'adapter.nested_transaction_unsupported',
+          `${this.constructor.name}.withTransaction() cannot nest — a transaction is already in progress on this single SQLite connection (ADR-105).`,
+          { details: { adapter: this.constructor.name, filename: this.#filename } },
+        )
+      }
+      db.exec('BEGIN')
+      let result
+      try {
+        result = await fn(db)
+      } catch (err) {
+        // rollback. ROLLBACK 자체가 실패해도(드묾) 원본 에러를 가리지 않도록 격리 후 원본 re-throw.
+        if (db.inTransaction) {
+          try {
+            db.exec('ROLLBACK')
+          } catch (rollbackErr) {
+            // 비치명적: 원본 실패가 진짜 원인 — rollback 실패는 경고만.
+            console.warn(
+              `[MegaSqliteAdapter] ROLLBACK failed after transaction error (original error wins):`,
+              rollbackErr,
+            )
+          }
+        }
+        throw err
+      }
+      db.exec('COMMIT')
+      return result
+    })
+  }
+
+  /**
+   * 계측된 SQL 쿼리 (ADR-138). better-sqlite3 는 동기 API 라 `prepare` 후 reader 면 `all`(SELECT — row
+   * 배열), 아니면 `run`(DML — `{ changes, lastInsertRowid }`)을 쓴다. 단일 연결이라 트랜잭션 진행 중에도
+   * 같은 `#db` 를 쓰므로(`db.inTransaction`) 자연히 트랜잭션 안에서 실행된다. `_instrument('query', …)`
+   * 가 자동 span(`sqlite.query`, `db.system.name`/`db.query.text`/`mega.rows_affected`)·stats·상태 검증을 처리한다.
+   *
+   * @param {string} sql - 파라미터화된 SQL(placeholder `?` 보존).
+   * @param {any[]} [params] - placeholder 바인딩 값.
+   * @returns {Promise<any>} reader 면 row 배열, 아니면 `{ changes, lastInsertRowid }`.
+   */
+  async query(sql, params) {
+    return this._instrument(
+      'query',
+      this._queryStartAttrs(sql),
+      async () => {
+        const db = /** @type {import('better-sqlite3').Database} */ (this.#db)
+        const stmt = db.prepare(sql)
+        const args = params === undefined ? [] : params
+        return stmt.reader ? stmt.all(...args) : stmt.run(...args)
+      },
+      // SELECT 는 row 배열 길이, DML 은 changes(영향 행 수).
+      (res) => ({ 'mega.rows_affected': Array.isArray(res) ? res.length : Number(res?.changes ?? 0) }),
+    )
+  }
+}
+
+// 빌트인 driver 자기등록 (ADR-044) — 배럴(`adapters/index.js`)이 본 모듈을 import 하면 트리거된다.
+// better-sqlite3 native binding 은 _connect() 의 lazy import 까지 로드되지 않으므로 등록은 안전.
+Registry.register('sqlite', MegaSqliteAdapter)

package/src/auth/index.js

@@ -0,0 +1,103 @@
+// @ts-check
+/**
+ * `mega-framework/auth` — 라우트 인증·권한 가드 미들웨어 (ADR-143).
+ *
+ * 세션 기반(ADR-129) 인증 가드를 `before` 미들웨어로 제공한다. 라우트 옵션
+ * `{ before: [requireAuth] }` 또는 글로벌 미들웨어로 그대로 쓸 수 있다.
+ *
+ * **시그니처 호환** — 라우트 레벨 `before` 는 Fastify `preHandler` 로 `(req, reply)` 만 받고,
+ * 글로벌 미들웨어는 `(req, reply, ctx)` 를 받는다(ADR-134). 두 가드 모두 세션을 `req.session`
+ * (= `ctx.session`)에서 읽으므로 양쪽 호출 경로에서 동일하게 동작한다. 인증 결과는 `req.user` 에
+ * 심으며, 핸들러는 `req.user` 또는 `ctx.user`(요청당 동일 ctx, ADR-134)로 읽는다.
+ *
+ * 세션에 `userId` 가 없으면 {@link MegaAuthError}(401), 권한 부족이면 {@link MegaForbiddenError}(403)
+ * 를 throw 한다 — 글로벌 에러 핸들러(error-mapper)가 envelope(ADR-014)로 변환한다. silent fallback
+ * 없음(P4): 인증 실패는 항상 표면화된다.
+ *
+ * @module auth
+ */
+import { MegaAuthError, MegaForbiddenError } from '../errors/http-errors.js'
+
+/**
+ * 요청에서 현재 세션 객체를 꺼낸다. 라우트 `before`(ctx 없음)와 글로벌(ctx 있음) 양쪽 호환 —
+ * `req.session` 우선, 없으면 `ctx.session`.
+ * @param {import('fastify').FastifyRequest} req
+ * @param {Record<string, any>} [ctx]
+ * @returns {Record<string, any> | null}
+ */
+function resolveSession(req, ctx) {
+  const fromReq = /** @type {any} */ (req)?.session
+  if (fromReq != null) return fromReq
+  return ctx?.session ?? null
+}
+
+/**
+ * 세션에서 인증 사용자를 확정해 `req.user` 에 심는다. 이미 `req.user` 가 있으면 그대로 둔다(멱등).
+ * 세션이 없거나 `userId` 가 비면 인증 실패로 간주하고 user 를 만들지 않는다.
+ * @param {import('fastify').FastifyRequest} req
+ * @param {Record<string, any>} [ctx]
+ * @returns {{ id: any, roles: string[] } | null}
+ */
+function ensureUser(req, ctx) {
+  const existing = /** @type {any} */ (req).user
+  if (existing != null) return existing
+  const session = resolveSession(req, ctx)
+  const userId = session?.userId
+  if (userId == null) return null
+  const roles = Array.isArray(session?.roles) ? session.roles : []
+  const user = { id: userId, roles }
+  ;/** @type {any} */ (req).user = user
+  return user
+}
+
+/**
+ * 로그인(세션 `userId` 존재)을 요구하는 `before` 가드. 통과 시 `req.user`(`{ id, roles }`)를 채운다.
+ * 실패 시 401 `auth.required`.
+ *
+ * @param {import('fastify').FastifyRequest} req
+ * @param {import('fastify').FastifyReply} _reply
+ * @param {Record<string, any>} [ctx] - 글로벌 미들웨어 경로에서만 주입(라우트 before 에선 undefined).
+ * @returns {Promise<void>}
+ * @throws {MegaAuthError} 세션·userId 부재 시 401.
+ * @example
+ * router.http.get('/api/me', MeController.show, { before: [requireAuth] })
+ */
+export async function requireAuth(req, _reply, ctx) {
+  const log = req.log ?? ctx?.log
+  const user = ensureUser(req, ctx)
+  if (user == null) {
+    log?.debug?.({ route: req.url }, 'auth.require denied — no session user')
+    throw new MegaAuthError('auth.required', 'Authentication required')
+  }
+  log?.debug?.({ userId: user.id }, 'auth.require ok')
+}
+
+/**
+ * 지정한 역할 중 하나 이상을 가진 로그인 사용자를 요구하는 `before` 가드 팩토리. 먼저 인증을
+ * 확정(`requireAuth` 동일 로직)한 뒤 역할 교집합을 검사한다.
+ *
+ * @param {...string} roles - 허용 역할 목록(하나라도 보유 시 통과). 최소 1개 필수.
+ * @returns {(req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply, ctx?: Record<string, any>) => Promise<void>}
+ * @throws {TypeError} 역할 인자가 비었거나 문자열이 아니면(설정 실수 fail-fast).
+ * @example
+ * router.http.post('/api/users', UsersController.create, { before: [requireRole('admin')] })
+ */
+export function requireRole(...roles) {
+  if (roles.length === 0 || roles.some((r) => typeof r !== 'string' || r.length === 0)) {
+    throw new TypeError('requireRole(...roles): at least one non-empty role string is required.')
+  }
+  return async function requireRoleGuard(req, _reply, ctx) {
+    const log = req.log ?? ctx?.log
+    const user = ensureUser(req, ctx)
+    if (user == null) {
+      log?.debug?.({ route: req.url, roles }, 'auth.role denied — no session user')
+      throw new MegaAuthError('auth.required', 'Authentication required')
+    }
+    const hasRole = user.roles.some((/** @type {string} */ r) => roles.includes(r))
+    if (!hasRole) {
+      log?.debug?.({ userId: user.id, need: roles, have: user.roles }, 'auth.role denied — missing role')
+      throw new MegaForbiddenError('auth.forbidden', 'Forbidden', { details: { required: roles } })
+    }
+    log?.debug?.({ userId: user.id, roles }, 'auth.role ok')
+  }
+}

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

@@ -0,0 +1,56 @@
+// @ts-check
+/**
+ * `mega console` — 앱 컨텍스트를 로딩한 상태의 REPL (roadmap §338, ADR-142).
+ *
+ * `prepareRuntime`(config → 플러그인 install → 어댑터 connect → ctx, ADR-123)으로 런타임을 띄운 뒤
+ * Node REPL 의 전역에 `ctx`(요청 무관 boot ctx)·`config`(global config)·`mega`(host 등)를 노출한다.
+ * 어댑터를 직접 만져 디버깅·데이터 확인을 할 수 있다.
+ *
+ * @module cli/commands/console-cmd
+ */
+import repl from 'node:repl'
+import { prepareRuntime } from '../../core/boot.js'
+import { MegaShutdown } from '../../lib/mega-shutdown.js'
+
+/**
+ * 기본 REPL 팩토리 — `mega>` 프롬프트로 node REPL 시작.
+ * @returns {import('node:repl').REPLServer}
+ */
+function defaultReplFactory() {
+  return repl.start({ prompt: 'mega> ', useGlobal: false })
+}
+
+/**
+ * 앱 컨텍스트를 로딩하고 REPL 을 연다.
+ * @param {string} projectRoot
+ * @param {object} [deps]
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [deps.logger]
+ * @param {() => { context: Record<string, any>, on?: (event: string, listener: (...args: any[]) => void) => void }} [deps.replFactory] -
+ *   주입용(테스트). context 객체를 가진 REPL-유사 객체를 반환해야 한다('exit' 이벤트용 `on` 은 선택).
+ * @param {(msg: string) => void} [deps.out]
+ * @param {() => (Promise<void> | void)} [deps.shutdown] - 주입용(테스트). REPL 종료 시 호출하는 graceful
+ *   shutdown 트리거. 기본 {@link MegaShutdown.now}(등록 hook 실행 후 process.exit).
+ * @param {(opts: { signals?: string[] }) => void} [deps.setupSignals] - 주입용(테스트). 시그널 핸들러 등록.
+ *   기본 {@link MegaShutdown.setupSignals}.
+ * @returns {Promise<{ ctx: Record<string, any>, config: object, server: { context: Record<string, any> } }>}
+ */
+export async function startConsole(
+  projectRoot,
+  { logger, replFactory = defaultReplFactory, out = console.log, shutdown = () => MegaShutdown.now(), setupSignals = (opts) => MegaShutdown.setupSignals(opts) } = {},
+) {
+  const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
+  out('mega: console ready — globals: ctx, config, mega')
+  // prepareRuntime 이 어댑터/워커/wsHub 를 connect 하고 각자 MegaShutdown hook 을 자기등록한다. 정리 없이
+  // 두면 REPL 종료 후에도 열린 핸들(DB 풀·redis·wsHub listen)로 프로세스가 행하고 어댑터가 미정리된다.
+  // 따라서 SIGTERM 은 graceful shutdown 으로 받는다. SIGINT 은 REPL 이 소유(빈 줄 클리어 / 이중 입력 시
+  // 'exit')하므로 가로채지 않는다 — 가로채면 한 번의 Ctrl-C 가 콘솔을 죽인다(ADR-167).
+  setupSignals({ signals: ['SIGTERM'] })
+  const server = replFactory()
+  Object.assign(server.context, { ctx, config: global, mega: { config: global, host } })
+  // REPL 종료(.exit / Ctrl-D / 이중 Ctrl-C)는 'exit' 이벤트로 온다 — 이때 graceful shutdown 으로 어댑터 등을
+  // 정리하고 프로세스를 닫는다. 주입 fake REPL(테스트)은 `.on` 이 없을 수 있어 옵셔널 호출(ADR-167).
+  server.on?.('exit', () => {
+    void shutdown()
+  })
+  return { ctx, config: global, server }
+}