mega-framework 0.1.0

package/src/lib/worker-runner/task-dispatch.js

@@ -0,0 +1,72 @@
+// @ts-check
+/**
+ * 워커 런타임(스레드/프로세스) **공통 디스패처** — `static taskFile` 모듈을 로드하고, 부모가 보낸
+ * `{ id, taskName, args }` 메시지를 그 모듈이 export 한 task 함수로 라우팅한다 (ADR-124).
+ *
+ * thread(`worker_threads`)·process(`child_process`) 진입점이 채널(parentPort vs process)만 다르고 로직은
+ * 동일하므로 한 곳으로 모은다. 사용자 taskFile 은 **평범한 async 함수들을 named export** 하면 된다
+ * (메시지 루프 보일러플레이트 없음):
+ *
+ * @example
+ * // workers/image-tasks.js  (= static taskFile)
+ * export async function resize({ src, dst, width }) { ... return result }
+ *
+ * @module lib/worker-runner/task-dispatch
+ */
+import { pathToFileURL } from 'node:url'
+
+/**
+ * taskFile 모듈을 동적 import 한다. 절대경로를 file:// URL 로 변환해 OS·ESM 호환성을 보장한다.
+ * @param {string} taskFile - 워커 진입 모듈 절대경로.
+ * @returns {Promise<Record<string, any>>} 모듈 네임스페이스(task 함수들).
+ */
+export function loadTaskModule(taskFile) {
+  return import(pathToFileURL(taskFile).href)
+}
+
+/**
+ * Error 를 스레드/프로세스 경계 너머로 보낼 수 있게 평탄화한다 (structuredClone/IPC 는 Error 인스턴스의
+ * name/message/stack 을 보존하지 않으므로 명시 직렬화). 부모가 이를 받아 다시 Error 로 복원한다.
+ * @param {unknown} err
+ * @returns {{ name: string, message: string, stack?: string, code?: string }}
+ */
+export function serializeError(err) {
+  if (err instanceof Error) {
+    return {
+      name: err.name,
+      message: err.message,
+      stack: err.stack,
+      // MegaError 계열의 code 도 보존(있으면).
+      ...(typeof (/** @type {any} */ (err).code) === 'string' ? { code: /** @type {any} */ (err).code } : {}),
+    }
+  }
+  return { name: 'Error', message: String(err) }
+}
+
+/**
+ * 부모가 보낸 task 디스패치 메시지 1건을 처리한다 — 모듈에서 `taskName` 함수를 찾아 실행하고 결과/에러를
+ * 부모로 돌려보낸다. 미존재 task·실행 실패를 묵살하지 않고 `{ ok:false, error }` 로 명시 보고.
+ *
+ * @param {Record<string, any>} mod - loadTaskModule 결과.
+ * @param {any} msg - 부모 메시지 `{ id, taskName, args }`.
+ * @param {(reply: any) => void} send - 부모로 회신하는 채널(`parentPort.postMessage` / `process.send`).
+ * @returns {Promise<void>}
+ */
+export async function handleTaskMessage(mod, msg, send) {
+  // ready 핸드셰이크 등 task 가 아닌 메시지는 무시(부모는 task 메시지에 number id 를 항상 싣는다).
+  if (!msg || typeof msg.id !== 'number') return
+  const { id, taskName, args } = msg
+  try {
+    const fn = mod[taskName]
+    if (typeof fn !== 'function') {
+      throw new Error(
+        `MegaWorker: task '${taskName}' is not an exported function in the task module ` +
+          `(exports: ${Object.keys(mod).filter((k) => typeof mod[k] === 'function').join(', ') || '(none)'}).`,
+      )
+    }
+    const result = await fn(args)
+    send({ id, ok: true, result })
+  } catch (err) {
+    send({ id, ok: false, error: serializeError(err) })
+  }
+}

package/src/lib/worker-runner/thread-entry.js

@@ -0,0 +1,26 @@
+// @ts-check
+/**
+ * `worker_threads` 진입점 (mode:'thread') — `MegaWorker` 가 `new Worker(thread-entry, { workerData })` 로
+ * 띄운다 (ADR-124). taskFile 을 로드한 뒤 `{ ready:true }` 핸드셰이크를 보내고, 이후
+ * 부모(`MegaWorker`)의 task 메시지를 공통 디스패처로 처리한다.
+ *
+ * 상단 await(동적 import)가 실패하면 모듈 평가가 reject 되어 워커가 `error`/`exit` 로 죽고, 부모의 spawn
+ * 핸드셰이크가 그걸 spawn 실패로 보고한다(silent 아님).
+ *
+ * @module lib/worker-runner/thread-entry
+ */
+import { parentPort, workerData } from 'node:worker_threads'
+import { loadTaskModule, handleTaskMessage } from './task-dispatch.js'
+
+if (!parentPort) {
+  throw new Error('thread-entry.js must run inside a worker_thread (parentPort is null).')
+}
+
+const port = parentPort
+const mod = await loadTaskModule(workerData.taskFile)
+port.on('message', (msg) => {
+  // handleTaskMessage 는 자체적으로 try/catch 해 항상 회신하므로 여기서 추가 처리는 불필요.
+  void handleTaskMessage(mod, msg, (reply) => port.postMessage(reply))
+})
+// 로드 완료 신호 — 부모는 이 메시지를 받고서야 task 를 디스패치한다(race 방지).
+port.postMessage({ ready: true })

package/src/models/index.js

@@ -0,0 +1,7 @@
+// @ts-check
+/**
+ * models 배럴 — 데이터 모델 베이스 (ADR-008/009/010/081).
+ *
+ * @module models
+ */
+export { MegaModel } from './mega-model.js'

package/src/models/mega-model.js

@@ -0,0 +1,151 @@
+// @ts-check
+/**
+ * MegaModel — SQL · Document DB 전용 얇은 모델 베이스 (ADR-008/009/010/081).
+ *
+ * ORM·쿼리 빌더는 **의도적으로 없다**(ADR-009). 모델은 세 가지만 한다:
+ *   1. `static get db` 로 어댑터 native handle(pg Pool / MongoClient / mariadb Pool /
+ *      better-sqlite3 Database)을 노출 → 사용자가 native API 로 도메인 메서드를 직접 작성.
+ *   2. `static withTransaction(fn)` 으로 명시적 트랜잭션 경계 제공(ADR-010) → 어댑터에 위임.
+ *   3. `static query(sql, params)` 로 **계측된** SQL 실행(ADR-138) → 어댑터 `query` 도메인 메서드에
+ *      위임(자동 span·메트릭). `this.db.query`(native, 계측 미통과)와 구분된다.
+ *
+ * # 사용 예 (13-sample-code §4)
+ *   ```js
+ *   export class User extends MegaModel {
+ *     static adapter = 'primary'   // mega.config.js 의 services.databases.primary 키 (글로벌, ADR-061)
+ *     static table   = 'users'     // 데이터 소스 식별자 (SQL table / Mongo collection 통일, ADR-081)
+ *     static async findByEmail(email) {
+ *       const { rows } = await this.db.query('select * from users where email = $1', [email])
+ *       return rows[0] ?? null
+ *     }
+ *   }
+ *   // 트랜잭션 (ADR-010 — 자동 request-scoped 트랜잭션 없음, 항상 명시적)
+ *   await User.withTransaction(async (tx) => { await tx.query('...') })
+ *   ```
+ *
+ * # 어댑터 lookup 경로 — `ctx.db(alias)` 와 다름 (중요)
+ *   `MegaModel.adapter` 는 **전역 services.databases 의 globalKey** 를 직접 가리킨다(03-api-spec
+ *   §162, 08-class-specs §3.1). 앱별 별명(app.config.js 의 `databases: { alias: globalKey }`)이
+ *   아니다 — 모델은 ctx(요청 컨텍스트) 없이 클래스 static 으로 평가되므로 글로벌 매니저
+ *   ({@link module:adapters/adapter-manager}) 에서 globalKey 로 바로 공유 인스턴스를 잡는다.
+ *   반면 `ctx.db('alias')` 는 앱 별명을 globalKey 로 바꾼 뒤 같은 매니저를 본다(ADR-102).
+ *   둘 다 종착지는 동일한 전역 공유 어댑터 인스턴스다.
+ *
+ * # db 는 native handle, withTransaction 만 어댑터 표면 (ADR-102 문구 정합)
+ *   `ctx.db(key)` 는 어댑터(MegaDbAdapter)를 돌려주지만(ADR-102), `MegaModel.db` 는 그 어댑터의
+ *   `.native`(raw handle)를 돌려준다 — 4개 정본(03/06/08/13)이 일관되게 `this.db.query(...)` 처럼
+ *   native API 직접 호출을 보인다. ADR-102 가 말한 "MegaModel 이 어댑터 표면을 쓴다"는
+ *   `withTransaction` 위임을 가리킨다(트랜잭션은 native handle 이 아니라 어댑터가 경계를 관리).
+ *
+ * @module models/mega-model
+ */
+import { MegaInternalError } from '../errors/http-errors.js'
+import * as MegaAdapterManager from '../adapters/adapter-manager.js'
+
+export class MegaModel {
+  /**
+   * 어댑터 globalKey — `mega.config.js` 의 `services.databases.<key>` 와 정확히 일치 (ADR-061).
+   * 서브클래스가 박는다. 비어 있으면 db/withTransaction 접근 시 throw.
+   * @type {string}
+   */
+  static adapter = ''
+
+  /**
+   * 데이터 소스 식별자. SQL 의 table 또는 MongoDB 의 collection 모두 본 필드에 명시 (ADR-081).
+   * 어댑터별 native 호출 시 의미는 동일. 비어 있으면 db/withTransaction 접근 시 throw.
+   * @type {string}
+   */
+  static table = ''
+
+  /**
+   * 자동 lookup — `adapter` 키로 어댑터의 driver native handle 반환
+   * (pg Pool / MongoClient / mariadb Pool / better-sqlite3 Database, ADR-009).
+   *
+   * 어댑터가 아직 `connect()` 전이면 어댑터 베이스가 `adapter.not_connected` 를 throw 한다
+   * (08-class-specs §3.2 불변식 — native 는 연결 후에만 유효).
+   *
+   * @returns {any} driver native handle.
+   */
+  static get db() {
+    return this._resolveAdapter().native
+  }
+
+  /**
+   * 명시적 트랜잭션 경계 (ADR-010). 어댑터의 `withTransaction` 에 위임한다 — 성공 시 commit,
+   * `fn` 이 throw 하면 driver native rollback 후 원본 에러 re-throw. **자동 request-scoped
+   * 트랜잭션은 만들지 않는다** (ADR-010).
+   *
+   * `fn` 이 받는 인자는 **트랜잭션 컨텍스트의 native handle**(예: pg client) 이다. 같은 모델의
+   * 다른 메서드(`this.db.query`)는 트랜잭션 **밖** 글로벌 handle 을 쓰므로, 트랜잭션 안에서는
+   * `fn` 인자를 명시적으로 써야 격리가 유지된다 (08-class-specs §3.1 — 사용자 책임).
+   *
+   * nested 트랜잭션 정책(postgres SAVEPOINT / Mongo throw)은 **구체 어댑터 책임**이다.
+   * 베이스는 위임만 한다.
+   *
+   * `fn` 인자 수는 어댑터별로 다르다 — SQL 어댑터는 `(client)` 1개, Mongo 어댑터는 `(db, session)`
+   * 2개를 넘긴다(ADR-108). 따라서 가변 인자로 타입을 둔다(어댑터가 인자 형태의 정본).
+   *
+   * @template T
+   * @param {(...args: any[]) => Promise<T>} fn - 트랜잭션 컨텍스트 native handle(들)을 받는 콜백.
+   * @returns {Promise<T>}
+   */
+  static async withTransaction(fn) {
+    return this._resolveAdapter().withTransaction(fn)
+  }
+
+  /**
+   * **계측된 쿼리** — `this.db.query`(native handle 직접 호출, 트레이싱 미통과)와 달리 어댑터의
+   * `query` 도메인 메서드에 위임해 자동 span(`<driver>.query`)·메트릭·stats 에 잡힌다(ADR-138).
+   * 진행 중 트랜잭션이 있으면 어댑터가 같은 connection 으로 실행하므로, `withTransaction(async (tx) => …)`
+   * 콜백 안에서 `Model.query(sql, params)` 를 부르면 격리가 유지되고 span 도 트랜잭션 span 의 자식이 된다
+   * (native `tx.query`는 계측 미통과 escape hatch). SQL 어댑터(postgres/maria/sqlite) 전용 — Document
+   * DB(mongo)는 `adapter.not_implemented`.
+   *
+   * @param {string} sql - 파라미터화된 SQL(placeholder 보존 — 값 인터폴레이션 금지).
+   * @param {any[]} [params] - placeholder 바인딩 값.
+   * @returns {Promise<any>} driver native 쿼리 결과(어댑터별 형태 — ADR-009).
+   */
+  static async query(sql, params) {
+    return this._resolveAdapter().query(sql, params)
+  }
+
+  /**
+   * `adapter`/`table` 정합성을 검증하고 글로벌 매니저에서 어댑터(MegaDbAdapter)를 잡아 반환한다.
+   *
+   * 정본은 "부팅 시 검증"(08-class-specs §3.1 라이프사이클, ADR-067)을 말하지만, 중앙 부팅
+   * 오케스트레이터(`mega serve` CLI)가 아직 미배선이라(ADR-102 미결 항목) **접근 시점 lazy 검증**
+   * 으로 둔다 — `ctx.db(alias)` 가 미등록 별명을 즉시 throw 하는 것과 같은 패턴(ADR-102).
+   * 오케스트레이터가 생기면 부팅 시 일괄 검증을 추가한다(ADR-104).
+   *
+   * @protected
+   * @returns {import('../adapters/mega-db-adapter.js').MegaDbAdapter}
+   */
+  static _resolveAdapter() {
+    const model = this.name
+    if (!this.adapter) {
+      throw new MegaInternalError(
+        'model.adapter_required',
+        `${model}.adapter is empty — set "static adapter = '<services.databases key>'" (ADR-061).`,
+        { details: { model } },
+      )
+    }
+    if (!this.table) {
+      throw new MegaInternalError(
+        'model.table_required',
+        `${model}.table is empty — set "static table = '<table-or-collection>'" (ADR-081).`,
+        { details: { model, adapter: this.adapter } },
+      )
+    }
+    if (!MegaAdapterManager.has('db', this.adapter)) {
+      throw new MegaInternalError(
+        'model.adapter_not_found',
+        `${model}.adapter "${this.adapter}" is not a registered database (services.databases). ` +
+          'Define it in mega.config.js and boot the adapter manager first.',
+        { details: { model, adapter: this.adapter } },
+      )
+    }
+    return /** @type {import('../adapters/mega-db-adapter.js').MegaDbAdapter} */ (
+      MegaAdapterManager.get('db', this.adapter)
+    )
+  }
+}

package/src/test/index.js

@@ -0,0 +1,288 @@
+// @ts-check
+/**
+ * `mega-framework/test` — 단위 테스트 fixture 헬퍼 `MegaTest` (ADR-144, 03-api-spec §12).
+ *
+ * 컨트롤러(정적 메서드)·WS 채널·서비스의 단위 테스트를 위한 가벼운 fixture 를 만든다. 실 Fastify·실
+ * 어댑터 없이 `(req, res, ctx)` / `(sock, ctx)` 모양만 충실히 흉내 내, 핸들러가 의존하는 표면(params·
+ * services·session·user 등)을 주입한다. zero-dep(node 빌트인만).
+ *
+ * 구현 범위(Phase 6): 단위 헬퍼 `makeHttp` · `makeWs` · `mockBus` · `mockCache`. 통합 fixture
+ * `makeApp` · `withDatabase`(03-api-spec §12)는 실 부팅·트랜잭션 격리가 필요해 별도 작업으로 연기한다
+ * (ADR-144 — 명시 추적, 우회 아님). 통합 테스트는 그동안 `bootApp`(core)을 직접 쓴다.
+ *
+ * @module test
+ */
+
+/** 아무것도 출력하지 않는 로거 — 단위 테스트 소음 제거. pino child() 체이닝 호환. */
+function silentLogger() {
+  /** @type {any} */
+  const log = {}
+  for (const level of ['trace', 'debug', 'info', 'warn', 'error', 'fatal']) log[level] = () => {}
+  log.child = () => log
+  return log
+}
+
+/** ctx.tracer no-op — `span(name, fn)` 이 noop span 으로 fn 을 실행하고 결과를 그대로 반환(옵트인 OFF 동형). */
+const noopTracer = {
+  /** @param {string} _name @param {(span: any) => any} fn */
+  span(_name, fn) {
+    const span = { setAttribute() {}, setAttributes() {}, addEvent() {}, recordException() {}, end() {} }
+    return fn(span)
+  },
+}
+
+/**
+ * 어댑터 접근자(`ctx.db('alias')` 등)를 mock 맵에서 만든다. 맵에 없는 별명 접근은 명확히 throw
+ * (silent undefined 금지 — 테스트가 잘못된 별명을 조용히 통과시키지 않게).
+ * @param {'db'|'cache'|'bus'|'lock'} domain
+ * @param {Record<string, any>} map - { alias: adapterMock }
+ * @returns {(alias: string) => any}
+ */
+function makeAccessor(domain, map) {
+  return (alias) => {
+    if (!(alias in map)) {
+      throw new Error(`MegaTest: ctx.${domain}('${alias}') — not provided. Pass { ${domain}: { '${alias}': mock } } to makeHttp/makeWs.`)
+    }
+    return map[alias]
+  }
+}
+
+/**
+ * Fastify reply 를 흉내 내는 mock. 체이닝(`res.code(201)`)과 상태/헤더/전송 payload 기록을 지원한다.
+ * @returns {Record<string, any>}
+ */
+function makeReply() {
+  /** @type {Record<string, any>} */
+  const reply = {
+    statusCode: 200,
+    sent: false,
+    payload: undefined,
+    headers: /** @type {Record<string, any>} */ ({}),
+    code(/** @type {number} */ n) {
+      this.statusCode = n
+      return this
+    },
+    status(/** @type {number} */ n) {
+      this.statusCode = n
+      return this
+    },
+    header(/** @type {string} */ k, /** @type {any} */ v) {
+      this.headers[String(k).toLowerCase()] = v
+      return this
+    },
+    getHeader(/** @type {string} */ k) {
+      return this.headers[String(k).toLowerCase()]
+    },
+    type(/** @type {string} */ t) {
+      this.headers['content-type'] = t
+      return this
+    },
+    send(/** @type {any} */ p) {
+      this.sent = true
+      this.payload = p
+      return this
+    },
+  }
+  return reply
+}
+
+/**
+ * WS 소켓을 흉내 내는 mock. `send` 한 메시지를 `sentMessages` 에 기록한다.
+ * @param {{ id?: string, metadata?: object }} [opts]
+ * @returns {Record<string, any>}
+ */
+function makeSocket({ id = 'test-sock', metadata = {} } = {}) {
+  /** @type {any[]} */
+  const sentMessages = []
+  return {
+    id,
+    metadata: { ...metadata },
+    sentMessages,
+    send(/** @type {any} */ msg) {
+      sentMessages.push(msg)
+    },
+    close(/** @type {number} */ code, /** @type {string} */ reason) {
+      this.closed = { code, reason }
+    },
+  }
+}
+
+/**
+ * 채널 broadcast/directToUser 를 기록하는 mock. `ctx.channel` 로 주입.
+ * @returns {Record<string, any>}
+ */
+function makeChannelStub() {
+  /** @type {any[]} */
+  const broadcasts = []
+  /** @type {any[]} */
+  const directs = []
+  return {
+    broadcasts,
+    directs,
+    broadcast(/** @type {any} */ msg) {
+      broadcasts.push(msg)
+    },
+    directToUser(/** @type {any} */ userId, /** @type {any} */ msg) {
+      directs.push({ userId, msg })
+    },
+  }
+}
+
+export class MegaTest {
+  /**
+   * HTTP 액션 단위 테스트용 fixture (03-api-spec §12). 정적 메서드 컨트롤러·인라인 핸들러를
+   * `(req, res, ctx)` 로 직접 호출해 검증할 수 있다.
+   *
+   * @param {object} [opts]
+   * @param {Record<string, any>} [opts.params] - 경로 파라미터(`req.params`).
+   * @param {Record<string, any>} [opts.query] - 쿼리스트링(`req.query`).
+   * @param {any} [opts.body] - 요청 본문(`req.body`).
+   * @param {Record<string, any>} [opts.headers] - 요청 헤더(`req.headers`).
+   * @param {Record<string, any>} [opts.services] - `ctx.services` 로 주입할 서비스 mock 맵.
+   * @param {any} [opts.user] - 인증 사용자(`req.user`/`ctx.user`). 가드 우회 단위 테스트용.
+   * @param {Record<string, any>|null} [opts.session] - `req.session`/`ctx.session` 객체.
+   * @param {string} [opts.method] - HTTP 메서드(기본 'GET').
+   * @param {string} [opts.url] - 요청 경로(기본 '/').
+   * @param {string} [opts.requestId] - `ctx.requestId`/`req.id`(기본 'test-req').
+   * @param {any} [opts.app] - `ctx.app`(기본 null).
+   * @param {any} [opts.log] - 로거(기본 silent).
+   * @param {Record<string, any>} [opts.db] - `ctx.db(alias)` mock 맵.
+   * @param {Record<string, any>} [opts.cache] - `ctx.cache(alias)` mock 맵.
+   * @param {Record<string, any>} [opts.bus] - `ctx.bus(alias)` mock 맵.
+   * @param {Record<string, any>} [opts.lock] - `ctx.lock(alias)` mock 맵.
+   * @returns {{ req: any, res: any, ctx: any }} 핸들러에 그대로 넘기는 fixture(느슨한 타입 — 테스트 편의).
+   */
+  static makeHttp({
+    params = {},
+    query = {},
+    body = undefined,
+    headers = {},
+    services = {},
+    user = null,
+    session = null,
+    method = 'GET',
+    url = '/',
+    requestId = 'test-req',
+    app = null,
+    log,
+    db = {},
+    cache = {},
+    bus = {},
+    lock = {},
+  } = {}) {
+    const logger = log ?? silentLogger()
+    const res = makeReply()
+    /** @type {Record<string, any>} */
+    const req = { params, query, body, headers, method, url, id: requestId, log: logger, session, user }
+
+    /** @type {Record<string, any>} */
+    const ctx = {
+      app,
+      log: logger,
+      requestId,
+      req,
+      reply: res,
+      services,
+      session,
+      lang: null,
+      t: (/** @type {string} */ key, /** @type {any} */ def) => (typeof def === 'string' ? def : key),
+      workers: {},
+      tracer: noopTracer,
+      db: makeAccessor('db', db),
+      cache: makeAccessor('cache', cache),
+      bus: makeAccessor('bus', bus),
+      lock: makeAccessor('lock', lock),
+      render: (/** @type {string} */ view) => {
+        throw new Error(`MegaTest: ctx.render('${view}') is not configured in unit fixtures.`)
+      },
+    }
+    // ctx.user — req.user 와 양방향(getter=read, setter=write) 동기화. 가드(ADR-143)·미들웨어(ADR-134)
+    // 두 주입 패턴 모두 호환.
+    Object.defineProperty(ctx, 'user', {
+      get: () => req.user ?? null,
+      set: (v) => {
+        req.user = v
+      },
+      enumerable: true,
+      configurable: true,
+    })
+    return { req, res, ctx }
+  }
+
+  /**
+   * WS 채널 단위 테스트용 fixture (03-api-spec §12). 채널 메서드(`async join(sock, payload, ctx)` 등)를
+   * 직접 호출해 검증한다. `ctx.channel` 은 broadcast/directToUser 를 기록하는 stub.
+   *
+   * @param {object} [opts]
+   * @param {any} [opts.user] - 인증 사용자(`ctx.user`).
+   * @param {Record<string, any>} [opts.services] - `ctx.services` mock 맵.
+   * @param {Record<string, any>|null} [opts.session] - `ctx.session`.
+   * @param {{ id?: string, metadata?: object }} [opts.socket] - 소켓 초기값.
+   * @param {any} [opts.log] - 로거(기본 silent).
+   * @returns {{ sock: any, ctx: any }} 채널 메서드에 넘기는 fixture(느슨한 타입 — 테스트 편의).
+   */
+  static makeWs({ user = null, services = {}, session = null, socket = {}, log } = {}) {
+    const logger = log ?? silentLogger()
+    const sock = makeSocket(socket)
+    /** @type {Record<string, any>} */
+    const ctx = {
+      log: logger,
+      services,
+      session,
+      user,
+      lang: null,
+      tracer: noopTracer,
+      channel: makeChannelStub(),
+    }
+    return { sock, ctx }
+  }
+
+  /**
+   * in-memory mock bus — `publish` 호출을 기록하고 `subscribe` 핸들러로 즉시 dispatch 한다. 실 NATS
+   * 없이 잡/이벤트 발행 검증용.
+   * @returns {Record<string, any>}
+   */
+  static mockBus() {
+    /** @type {Array<{ subject: string, payload: any }>} */
+    const published = []
+    /** @type {Map<string, Function[]>} */
+    const handlers = new Map()
+    return {
+      published,
+      async publish(/** @type {string} */ subject, /** @type {any} */ payload) {
+        published.push({ subject, payload })
+        for (const fn of handlers.get(subject) ?? []) await fn(payload)
+      },
+      async subscribe(/** @type {string} */ subject, /** @type {Function} */ handler) {
+        const list = handlers.get(subject) ?? []
+        list.push(handler)
+        handlers.set(subject, list)
+      },
+    }
+  }
+
+  /**
+   * in-memory mock cache — Map 백엔드 `get/set/del/has`. TTL 인자는 받지만 만료는 흉내 내지 않는다
+   * (단위 테스트는 만료 동작이 아니라 호출·값을 검증).
+   * @returns {Record<string, any>}
+   */
+  static mockCache() {
+    /** @type {Map<string, any>} */
+    const store = new Map()
+    return {
+      store,
+      async get(/** @type {string} */ key) {
+        return store.has(key) ? store.get(key) : null
+      },
+      async set(/** @type {string} */ key, /** @type {any} */ value) {
+        store.set(key, value)
+      },
+      async del(/** @type {string} */ key) {
+        return store.delete(key)
+      },
+      async has(/** @type {string} */ key) {
+        return store.has(key)
+      },
+    }
+  }
+}

package/templates/adapter/code.tpl

@@ -0,0 +1,40 @@
+// @ts-check
+import { {{Base}} } from 'mega-framework'
+
+/**
+ * Mega{{Name}}Adapter — {{kind}} 어댑터(driver '{{driver}}'). 표준 lifecycle 5종 구현(ADR-045).
+ * 사용: `MegaAdapterRegistry.register('{{driver}}', Mega{{Name}}Adapter)` 등록 후 config 의
+ * `services.{{kind}}s.<key>.driver: '{{driver}}'` 로 인스턴스화된다(ADR-044).
+ */
+export class Mega{{Name}}Adapter extends {{Base}} {
+  /** 자원 연결. 부팅 시 호출. */
+  async connect() {
+    throw new Error('Mega{{Name}}Adapter.connect: not implemented')
+  }
+
+  /** 자원 해제. 종료 시 호출. */
+  async disconnect() {
+    throw new Error('Mega{{Name}}Adapter.disconnect: not implemented')
+  }
+
+  /**
+   * 살아있는지 ping. `/health/ready` 등에서 활용.
+   * @returns {Promise<boolean>}
+   */
+  async healthCheck() {
+    return false
+  }
+
+  /**
+   * 연결 풀·요청 수 등 운영 지표.
+   * @returns {object}
+   */
+  getStats() {
+    return {}
+  }
+
+  /** 어댑터별 native handle(모델·ctx 가 사용). */
+  get native() {
+    throw new Error('Mega{{Name}}Adapter.native: not implemented')
+  }
+}

package/templates/adapter/test.tpl

@@ -0,0 +1,13 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import { {{Base}} } from 'mega-framework'
+import { Mega{{Name}}Adapter } from '{{importPath}}'
+
+describe('Mega{{Name}}Adapter', () => {
+  test('{{Base}} 를 상속하고 lifecycle 메서드를 가짐', () => {
+    expect(Object.getPrototypeOf(Mega{{Name}}Adapter)).toBe({{Base}})
+    for (const m of ['connect', 'disconnect', 'healthCheck', 'getStats']) {
+      expect(typeof Mega{{Name}}Adapter.prototype[m]).toBe('function')
+    }
+  })
+})

package/templates/app/app.config.tpl

@@ -0,0 +1,10 @@
+// @ts-check
+/**
+ * apps/{{name}}/app.config.js — App-only + Shared-Reference 스코프(ADR-061). 별명으로 전역 자원을
+ * 참조한다(예: `databases: { db: 'maindb' }` → ctx.db('db')). 활성화하려면 mega.config.js 의
+ * `apps` 배열에 '{{name}}' 을 추가한다(ADR-066).
+ */
+export default {
+  name: '{{name}}',
+  hosts: ['{{name}}.localhost'],
+}

package/templates/app/route.tpl

@@ -0,0 +1,10 @@
+// @ts-check
+/**
+ * apps/{{name}} 기본 라우트 — 자동 로딩(loadRoutes) 대상.
+ */
+export default (/** @type {any} */ router) => {
+  router.http.get('/', async (/** @type {any} */ _req, /** @type {any} */ _res, /** @type {any} */ _ctx) => {
+    // 핸들러는 raw data 만 반환한다 — 프레임워크가 `{ ok, data, meta }` envelope 로 자동 wrap(ADR-018).
+    return { app: '{{name}}' }
+  })
+}

package/templates/app/test.tpl

@@ -0,0 +1,13 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import routes from '{{importPath}}'
+
+describe('{{name}} app index route', () => {
+  test('GET / 등록 + data 반환', async () => {
+    /** @type {Function|undefined} */
+    let handler
+    routes({ http: { get: (/** @type {string} */ _p, /** @type {Function} */ h) => void (handler = h) } })
+    expect(typeof handler).toBe('function')
+    expect(await /** @type {any} */ (handler)({}, {}, {})).toEqual({ app: '{{name}}' })
+  })
+})

package/templates/channel/code.tpl

@@ -0,0 +1,38 @@
+// @ts-check
+import { MegaWebSocketController } from 'mega-framework'
+
+/**
+ * {{Name}}Channel — WS 채널(ADR-074: WS 는 인스턴스+이벤트 디스패치라 베이스 유지). 메시지 `type` 이
+ * 점(`.`)을 포함하면 같은 이름의 메서드로 자동 디스패치된다(ADR-015) — 없으면 onMessage 폴백.
+ */
+export class {{Name}}Channel extends MegaWebSocketController {
+  /**
+   * @param {any} _sock @param {any} ctx
+   */
+  async onConnect(_sock, ctx) {
+    ctx?.log?.debug?.({ user: ctx?.user?.id }, '{{camelName}}: connected')
+  }
+
+  /**
+   * @param {any} _sock @param {any} ctx
+   */
+  async onDisconnect(_sock, ctx) {
+    ctx?.log?.debug?.({ user: ctx?.user?.id }, '{{camelName}}: disconnected')
+  }
+
+  /**
+   * 메시지 type `{{camelName}}.message` 자동 디스패치. 핸들러는 `(sock, msg, ctx)` 를 받는다.
+   * @param {any} _sock @param {any} msg @param {any} ctx
+   */
+  async ['{{camelName}}.message'](_sock, msg, ctx) {
+    ctx.channel.broadcast({ type: '{{camelName}}.message', payload: msg.payload })
+  }
+
+  /**
+   * type 매칭 안 된 메시지 폴백.
+   * @param {any} _sock @param {any} msg @param {any} ctx
+   */
+  async onMessage(_sock, msg, ctx) {
+    ctx?.log?.warn?.({ type: msg?.type }, '{{camelName}}: unhandled message type')
+  }
+}