mega-framework 0.1.0

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

@@ -0,0 +1,386 @@
+// @ts-check
+/**
+ * 데모 흐름 통합 테스트(ADR-157) — 실 mongo(notes) + redis(카운터·캐시) + postgres(세션 사용자)로 sample/crud 를
+ * 부팅하고 HTTP 전 경로를 검증한다: 비로그인 가드 → 로그인 → notes CRUD(mongo) → redis 방문 카운터·캐시 hit/miss.
+ *
+ * 인프라(pg·redis·mongo) env 가 없으면 통째로 skip 한다(단위 테스트가 인프라 없이 로직을 커버).
+ * 실행에 필요한 env(.env): DATABASE_URL·REDIS_SESSION_URL·REDIS_RATE_URL·REDIS_DEMO_URL·MONGO_URL·SESSION_SECRET.
+ */
+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 { existsSync, readFileSync, rmSync } from 'node:fs'
+import { User } from '../../../apps/main/models/user.js'
+import { Note } from '../../../apps/main/models/note.js'
+import { RedisDemoService } from '../../../apps/main/services/redis-demo-service.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.REDIS_DEMO_URL &&
+    process.env.MONGO_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('&')
+}
+
+/** 업로드 폼의 data-csrf 속성에서 토큰을 뽑는다(multipart 는 헤더로 보냄). @param {string} html @returns {string} */
+function csrfDataFrom(html) {
+  const m = /data-csrf="([^"]+)"/.exec(html)
+  if (!m) throw new Error('data-csrf token not found in upload form HTML')
+  return m[1]
+}
+
+/** N개 파일 multipart/form-data 본문 조립(추가 dep 없이). @param {Array<{ name?: string, filename?: string, contentType?: string, value?: string }>} files @param {string} [boundary] */
+function multipartBody(files, boundary = '----megademo') {
+  const chunks = []
+  for (const f of files) {
+    chunks.push(
+      Buffer.from(
+        `--${boundary}\r\nContent-Disposition: form-data; name="${f.name ?? 'file'}"; filename="${f.filename ?? 'a.bin'}"\r\n` +
+          `Content-Type: ${f.contentType ?? 'application/octet-stream'}\r\n\r\n`,
+        'utf8',
+      ),
+    )
+    chunks.push(Buffer.from(String(f.value ?? ''), 'utf8'))
+    chunks.push(Buffer.from('\r\n', 'utf8'))
+  }
+  chunks.push(Buffer.from(`--${boundary}--\r\n`, 'utf8'))
+  return { body: Buffer.concat(chunks), contentType: `multipart/form-data; boundary=${boundary}` }
+}
+
+d('데모 흐름 E2E — sample/crud 실 mongo+redis+pg (ADR-157)', () => {
+  /** @type {Awaited<ReturnType<typeof bootApp>>} */
+  let boot
+  /** @type {any} */
+  let fastify
+  /** @type {Record<string,string>} 로그인 세션 쿠키 jar. */
+  const jar = {}
+  const EMAIL = `itest-demo-${Date.now()}@example.com`
+  const PASSWORD = 'secret-pass-123'
+  const NAME = 'Demo 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()
+    // 스키마 보장(멱등) + 테스트 계정 정리.
+    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])
+
+    // 회원가입 → 자동 로그인 → 세션 쿠키 확보(가드된 /demo/** 접근에 필요).
+    const regForm = await fastify.inject({ method: 'GET', url: '/register' })
+    applyCookies(regForm, jar)
+    const reg = await fastify.inject({
+      method: 'POST',
+      url: '/register',
+      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+      payload: form({ _csrf: csrfFrom(regForm.body), name: NAME, email: EMAIL, password: PASSWORD }),
+    })
+    applyCookies(reg, jar)
+  })
+
+  afterAll(async () => {
+    if (!boot) return
+    await User.query('DELETE FROM users WHERE email = $1', [EMAIL]).catch(() => {})
+    await Note.collection.deleteMany({ title: { $regex: /^itest / } }).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.cache('demo').disconnect().catch(() => {})
+    await boot.ctx.db('mongo').disconnect().catch(() => {})
+    await boot.ctx.db('primary').disconnect().catch(() => {})
+    MegaShutdown._reset()
+  })
+
+  test('비로그인: /demo/notes 와 /demo/redis 는 로그인으로 302', async () => {
+    const notes = await fastify.inject({ method: 'GET', url: '/demo/notes' })
+    expect(notes.statusCode).toBe(302)
+    expect(notes.headers.location).toBe('/auth/login')
+    const redis = await fastify.inject({ method: 'GET', url: '/demo/redis' })
+    expect(redis.statusCode).toBe(302)
+    expect(redis.headers.location).toBe('/auth/login')
+  })
+
+  test('notes CRUD (mongo): 생성 → 목록 표시 → 수정 → 삭제', async () => {
+    const TITLE = `itest ${Date.now()}`
+    const EDITED = `${TITLE} (edited)`
+
+    // 신규 폼 GET — CSRF 토큰.
+    const newForm = await fastify.inject({ method: 'GET', url: '/demo/notes/new', headers: { cookie: cookieHeader(jar) } })
+    expect(newForm.statusCode).toBe(200)
+
+    // 생성 POST → 목록으로 302.
+    const created = await fastify.inject({
+      method: 'POST',
+      url: '/demo/notes',
+      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+      payload: form({ _csrf: csrfFrom(newForm.body), title: TITLE, body: 'hello mongo' }),
+    })
+    expect(created.statusCode).toBe(302)
+    expect(created.headers.location).toBe('/demo/notes?notice=created')
+
+    // 목록에 방금 만든 제목이 보인다.
+    const list = await fastify.inject({ method: 'GET', url: '/demo/notes', headers: { cookie: cookieHeader(jar) } })
+    expect(list.statusCode).toBe(200)
+    expect(list.body).toContain(TITLE)
+
+    // 방금 만든 노트의 id 를 모델로 직접 찾는다(목록 HTML 파싱 대신 — edit URL 구성용).
+    const all = await Note.list()
+    const mine = /** @type {any} */ (all).find((n) => n.title === TITLE)
+    expect(mine).toBeTruthy()
+
+    // 수정 폼 GET → 수정 POST → 목록으로 302.
+    const editForm = await fastify.inject({ method: 'GET', url: `/demo/notes/${mine.id}/edit`, headers: { cookie: cookieHeader(jar) } })
+    expect(editForm.statusCode).toBe(200)
+    expect(editForm.body).toContain(TITLE)
+    const updated = await fastify.inject({
+      method: 'POST',
+      url: `/demo/notes/${mine.id}`,
+      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+      payload: form({ _csrf: csrfFrom(editForm.body), title: EDITED, body: 'edited body' }),
+    })
+    expect(updated.statusCode).toBe(302)
+    expect(await Note.findById(mine.id)).toMatchObject({ title: EDITED })
+
+    // 삭제 POST → 목록으로 302, 모델에서도 사라진다.
+    const delList = await fastify.inject({ method: 'GET', url: '/demo/notes', headers: { cookie: cookieHeader(jar) } })
+    const del = await fastify.inject({
+      method: 'POST',
+      url: `/demo/notes/${mine.id}/delete`,
+      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+      payload: form({ _csrf: csrfFrom(delList.body) }),
+    })
+    expect(del.statusCode).toBe(302)
+    expect(del.headers.location).toBe('/demo/notes?notice=deleted')
+    expect(await Note.findById(mine.id)).toBeNull()
+  })
+
+  test('redis 방문 카운터: 페이지 로드마다 누적 카운터가 1씩 증가한다', async () => {
+    const redis = boot.ctx.cache('demo').native
+    const before = Number((await redis.get(RedisDemoService.VISITS_TOTAL_KEY)) ?? 0)
+    await fastify.inject({ method: 'GET', url: '/demo/redis', headers: { cookie: cookieHeader(jar) } })
+    await fastify.inject({ method: 'GET', url: '/demo/redis', headers: { cookie: cookieHeader(jar) } })
+    const after = Number(await redis.get(RedisDemoService.VISITS_TOTAL_KEY))
+    expect(after).toBe(before + 2)
+  })
+
+  test('redis 캐시: 비운 직후 첫 로드는 miss, 다음 로드는 hit', async () => {
+    // 캐시 키를 직접 비워 결정적 상태로 만든다.
+    await boot.ctx.cache('demo').del(RedisDemoService.USER_COUNT_KEY)
+
+    const miss = await fastify.inject({ method: 'GET', url: '/demo/redis', headers: { cookie: cookieHeader(jar) } })
+    expect(miss.statusCode).toBe(200)
+    expect(miss.body).toContain('캐시 미스') // 기본 로케일 ko.
+
+    const hit = await fastify.inject({ method: 'GET', url: '/demo/redis', headers: { cookie: cookieHeader(jar) } })
+    expect(hit.statusCode).toBe(200)
+    expect(hit.body).toContain('캐시 적중')
+  })
+
+  // ── 관측 데모(ADR-163) — 메트릭/Swagger/트레이싱/로그/업로드 ──────────────────────────
+
+  test('관측 데모 비로그인 가드: 메트릭/트레이싱/로그/업로드/docs 는 로그인으로 302', async () => {
+    for (const url of ['/demo/metrics', '/demo/tracing', '/demo/logs', '/demo/upload', '/docs']) {
+      const res = await fastify.inject({ method: 'GET', url })
+      expect(res.statusCode, url).toBe(302)
+      expect(res.headers.location, url).toBe('/auth/login')
+    }
+  })
+
+  test('메트릭 데모: 로그인 시 200 + 카드 렌더', async () => {
+    const res = await fastify.inject({ method: 'GET', url: '/demo/metrics', headers: { cookie: cookieHeader(jar) } })
+    expect(res.statusCode).toBe(200)
+    expect(res.body).toContain('메트릭') // h1 title(ko).
+  })
+
+  test('Swagger: /docs/json 이 라우트 schema 를 수집한 OpenAPI 명세를 준다', async () => {
+    const res = await fastify.inject({ method: 'GET', url: '/docs/json', headers: { cookie: cookieHeader(jar) } })
+    expect(res.statusCode).toBe(200)
+    const spec = res.json()
+    expect(spec.openapi).toMatch(/^3\./)
+    // users 라우트가 자동 수집됐는지(경로 + 태그).
+    expect(spec.paths['/users']).toBeTruthy()
+    expect(JSON.stringify(spec)).toContain('users')
+  })
+
+  test('트레이싱 데모: 200 + generate POST(사용자 span + DB 핑) 302', async () => {
+    const page = await fastify.inject({ method: 'GET', url: '/demo/tracing', headers: { cookie: cookieHeader(jar) } })
+    expect(page.statusCode).toBe(200)
+    const gen = await fastify.inject({
+      method: 'POST',
+      url: '/demo/tracing/generate',
+      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+      payload: form({ _csrf: csrfFrom(page.body) }),
+    })
+    expect(gen.statusCode).toBe(302)
+    expect(gen.headers.location).toBe('/demo/tracing?notice=generated')
+  })
+
+  test('로그 데모: emit POST 302 → 최근 목록에 메시지 표시', async () => {
+    const page = await fastify.inject({ method: 'GET', url: '/demo/logs', headers: { cookie: cookieHeader(jar) } })
+    expect(page.statusCode).toBe(200)
+    const MSG = `itest log ${Date.now()}`
+    const emit = await fastify.inject({
+      method: 'POST',
+      url: '/demo/logs/emit',
+      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+      payload: form({ _csrf: csrfFrom(page.body), level: 'warn', message: MSG }),
+    })
+    expect(emit.statusCode).toBe(302)
+    expect(emit.headers.location).toBe('/demo/logs?notice=emitted')
+    const after = await fastify.inject({ method: 'GET', url: '/demo/logs', headers: { cookie: cookieHeader(jar) } })
+    expect(after.body).toContain(MSG)
+  })
+
+  // ── 가이드 뷰어(/guide) — 라우터 params 스키마 검증(ADR-019) + i18n ──────────────────────
+
+  test('가이드 목록: 로그인 시 200 + 카드 그리드', async () => {
+    const res = await fastify.inject({ method: 'GET', url: '/guide', headers: { cookie: cookieHeader(jar) } })
+    expect(res.statusCode).toBe(200)
+    expect(res.body).toContain('가이드') // guide_index_title(ko).
+  })
+
+  test('가이드 단일: 유효 slug 는 200 + 목차 렌더', async () => {
+    const res = await fastify.inject({ method: 'GET', url: '/guide/01-cli', headers: { cookie: cookieHeader(jar) } })
+    expect(res.statusCode).toBe(200)
+    expect(res.body).toContain('목차') // guide_toc(ko) — 좌측 목차.
+  })
+
+  test('가이드 단일: 형식 위반 slug 는 라우터 params 스키마가 400(validation.failed)으로 막는다', async () => {
+    for (const bad of ['INVALID', 'foo_bar', 'a.b']) {
+      const res = await fastify.inject({ method: 'GET', url: `/guide/${encodeURIComponent(bad)}`, headers: { cookie: cookieHeader(jar) } })
+      expect(res.statusCode, bad).toBe(400)
+      expect(res.json().error.code, bad).toBe('validation.failed')
+    }
+  })
+
+  test('가이드 단일: 형식은 맞지만 없는 slug 는 서비스가 404(guide.not_found)', async () => {
+    const res = await fastify.inject({ method: 'GET', url: '/guide/99-does-not-exist', headers: { cookie: cookieHeader(jar) } })
+    expect(res.statusCode).toBe(404)
+    expect(res.json().error.code).toBe('guide.not_found')
+  })
+
+  test('i18n: 검증 에러 메시지가 locale(ko 기본 / en 쿠키)로 번역된다', async () => {
+    const ko = await fastify.inject({ method: 'GET', url: '/guide/BAD', headers: { cookie: cookieHeader(jar) } })
+    expect(ko.json().error.message).toBe('입력값이 올바르지 않습니다.')
+    const en = await fastify.inject({ method: 'GET', url: '/guide/BAD', headers: { cookie: `${cookieHeader(jar)}; mega.lang=en` } })
+    expect(en.json().error.message).toBe('Validation failed.')
+  })
+
+  test('로그 데모: message 가 상한(500자)을 넘으면 body 스키마가 400 으로 막는다', async () => {
+    const page = await fastify.inject({ method: 'GET', url: '/demo/logs', headers: { cookie: cookieHeader(jar) } })
+    const res = await fastify.inject({
+      method: 'POST',
+      url: '/demo/logs/emit',
+      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+      payload: form({ _csrf: csrfFrom(page.body), level: 'info', message: 'x'.repeat(501) }),
+    })
+    expect(res.statusCode).toBe(400)
+    expect(res.json().error.code).toBe('validation.failed')
+  })
+
+  test('업로드 데모: multipart + csrf-token 헤더로 저장 → JSON envelope + 최근 목록', async () => {
+    // 폼 GET — _csrf 쿠키 확보 + data-csrf 토큰 추출(multipart 는 헤더로 전송).
+    const page = await fastify.inject({ method: 'GET', url: '/demo/upload', headers: { cookie: cookieHeader(jar) } })
+    expect(page.statusCode).toBe(200)
+    applyCookies(page, jar)
+    const token = csrfDataFrom(page.body)
+
+    const FNAME = `itest-${Date.now()}.txt`
+    const { body, contentType } = multipartBody([{ filename: FNAME, contentType: 'text/plain', value: 'hello upload' }])
+    const up = await fastify.inject({
+      method: 'POST',
+      url: '/demo/upload',
+      headers: { cookie: cookieHeader(jar), 'content-type': contentType, 'csrf-token': token },
+      payload: body,
+    })
+    expect(up.statusCode).toBe(200)
+    const env = up.json()
+    expect(env.ok).toBe(true)
+    expect(env.data.files[0]).toMatchObject({ filename: FNAME, mimetype: 'text/plain' })
+    // 저장 경로는 프로젝트 루트 기준 상대(var/uploads/...) — 절대경로 비노출.
+    expect(env.data.files[0].path).toMatch(/^var[/\\]uploads[/\\]/)
+
+    // 실제 디스크에 저장됐는지 확인(프로젝트 루트 기준).
+    const savedAbs = resolve(PROJECT, env.data.files[0].path)
+    expect(existsSync(savedAbs)).toBe(true)
+    expect(readFileSync(savedAbs, 'utf8')).toBe('hello upload')
+
+    // 최근 업로드 목록에 파일명 + 다운로드 링크가 보인다.
+    const after = await fastify.inject({ method: 'GET', url: '/demo/upload', headers: { cookie: cookieHeader(jar) } })
+    expect(after.body).toContain(FNAME)
+    expect(after.body).toContain(`/demo/upload/file/${encodeURIComponent(FNAME)}`)
+
+    // 다운로드 — 인증 사용자는 소스에서 읽은 파일 내용을 받는다(정적 서빙 아님).
+    const dl = await fastify.inject({ method: 'GET', url: `/demo/upload/file/${encodeURIComponent(FNAME)}`, headers: { cookie: cookieHeader(jar) } })
+    expect(dl.statusCode).toBe(200)
+    expect(dl.body).toBe('hello upload')
+    expect(dl.headers['content-disposition']).toContain('attachment')
+
+    // 비로그인 다운로드는 로그인으로 리다이렉트(가드).
+    const dlGuard = await fastify.inject({ method: 'GET', url: `/demo/upload/file/${encodeURIComponent(FNAME)}` })
+    expect(dlGuard.statusCode).toBe(302)
+    expect(dlGuard.headers.location).toBe('/auth/login')
+
+    rmSync(savedAbs, { force: true }) // 테스트 산출물 정리.
+  })
+
+  test('업로드 데모: 비허용 MIME 은 415 로 거부', async () => {
+    const page = await fastify.inject({ method: 'GET', url: '/demo/upload', headers: { cookie: cookieHeader(jar) } })
+    applyCookies(page, jar)
+    const token = csrfDataFrom(page.body)
+    const { body, contentType } = multipartBody([{ filename: 'evil.bin', contentType: 'application/octet-stream', value: 'x' }])
+    const up = await fastify.inject({
+      method: 'POST',
+      url: '/demo/upload',
+      headers: { cookie: cookieHeader(jar), 'content-type': contentType, 'csrf-token': token },
+      payload: body,
+    })
+    expect(up.statusCode).toBe(415)
+  })
+})

package/sample/crud/test/apps/main/email-job.test.js

@@ -0,0 +1,76 @@
+// @ts-check
+/**
+ * EmailJob 단위 테스트 — 'demo' 캐시 native(incr/expire/lpush/ltrim)를 가짜로 갈음해 NATS 없이 run() 의 세
+ * 모드(ok/flaky/fail) 흐름과 이벤트 기록을 검증한다. 실 큐/재시도/DLQ 는 통합 검증(E2E)이 커버한다.
+ */
+import { describe, test, expect, vi } from 'vitest'
+import { EmailJob } from '../../../apps/main/jobs/email-job.js'
+
+/** 시도 카운터(incr) + 이벤트 LIST 를 추적하는 가짜 ctx. */
+function makeCtx() {
+  /** @type {Map<string, number>} */
+  const counters = new Map()
+  /** @type {string[]} */
+  const events = []
+  const native = {
+    /** @param {string} k */
+    async incr(k) {
+      const n = (counters.get(k) ?? 0) + 1
+      counters.set(k, n)
+      return n
+    },
+    expire: vi.fn(async () => 1),
+    /** @param {string} _k @param {string} v */
+    async lpush(_k, v) {
+      events.unshift(v)
+      return events.length
+    },
+    ltrim: vi.fn(async () => 'OK'),
+  }
+  const ctx = { log: { debug() {} }, cache: (/** @type {string} */ a) => (a === 'demo' ? { native } : null) }
+  return { ctx, events, native }
+}
+
+describe('EmailJob.run — ok 모드', () => {
+  test('첫 시도에 sent 를 반환하고 sent 이벤트를 남긴다', async () => {
+    const { ctx, events } = makeCtx()
+    const job = new EmailJob()
+    const r = await job.run({ id: 'e1', to: 'a@b.c', mode: 'ok' }, /** @type {any} */ (ctx))
+    expect(r).toEqual({ id: 'e1', status: 'sent', attempt: 1 })
+    expect(JSON.parse(events[0])).toMatchObject({ id: 'e1', status: 'sent', attempt: 1 })
+  })
+})
+
+describe('EmailJob.run — flaky 모드', () => {
+  test('1번째 시도는 throw(재시도 유발), 2번째 시도에 성공한다', async () => {
+    const { ctx, events } = makeCtx()
+    const job = new EmailJob()
+    const payload = { id: 'e2', to: 'a@b.c', mode: /** @type {const} */ ('flaky') }
+    await expect(job.run(payload, /** @type {any} */ (ctx))).rejects.toThrow(/transient failure on attempt 1/)
+    expect(JSON.parse(events[0])).toMatchObject({ status: 'retry', attempt: 1 })
+    // 같은 잡 재실행(재시도) → 시도 카운터 2 → 성공.
+    const r = await job.run(payload, /** @type {any} */ (ctx))
+    expect(r).toEqual({ id: 'e2', status: 'sent', attempt: 2 })
+    expect(JSON.parse(events[0])).toMatchObject({ status: 'sent', attempt: 2 })
+  })
+})
+
+describe('EmailJob.run — fail 모드', () => {
+  test('매 시도 throw 하고 failed 이벤트를 남긴다(재시도 소진 시 DLQ 로 라우팅됨)', async () => {
+    const { ctx, events } = makeCtx()
+    const job = new EmailJob()
+    const payload = { id: 'e3', to: 'a@b.c', mode: /** @type {const} */ ('fail') }
+    await expect(job.run(payload, /** @type {any} */ (ctx))).rejects.toThrow(/permanent failure on attempt 1/)
+    await expect(job.run(payload, /** @type {any} */ (ctx))).rejects.toThrow(/permanent failure on attempt 2/)
+    expect(JSON.parse(events[0])).toMatchObject({ status: 'failed', attempt: 2 })
+  })
+})
+
+describe('EmailJob 설정', () => {
+  test('subject/bus/concurrency/retries 가 정본 값과 일치한다', () => {
+    expect(EmailJob.subject).toBe('demo.email')
+    expect(EmailJob.bus).toBe('jobs')
+    expect(EmailJob.retries).toBe(2)
+    expect(EmailJob.concurrency).toBe(2)
+  })
+})

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

@@ -0,0 +1,68 @@
+// @ts-check
+/**
+ * GuideService 단위 테스트 — 레포 루트 docs/guide 의 실제 마크다운을 읽어 목록·렌더를 검증한다.
+ * 가이드 파일은 정적 자산이라 가짜를 두지 않고 실물을 읽는다(서버사이드 렌더 결과의 핵심 계약만 확인).
+ */
+import { describe, test, expect } from 'vitest'
+import { GuideService } from '../../../apps/main/services/guide-service.js'
+import { MegaNotFoundError } from 'mega-framework/errors'
+
+/** ctx 최소 스텁 — GuideService 는 ctx.log.debug 만 쓴다. */
+function makeCtx() {
+  return /** @type {any} */ ({ log: { debug() {} } })
+}
+
+describe('GuideService — listGuides', () => {
+  test('docs/guide 의 모든 가이드를 slug·title 로 나열한다(번호순)', async () => {
+    const svc = new GuideService(makeCtx())
+    const guides = await svc.listGuides()
+    expect(guides.length).toBeGreaterThanOrEqual(8)
+    // 파일명 오름차순 = 가이드 번호순.
+    const slugs = guides.map((g) => g.slug)
+    expect(slugs).toEqual([...slugs].sort())
+    // 각 항목은 비어있지 않은 slug·title 을 가진다.
+    for (const g of guides) {
+      expect(g.slug).toMatch(/^[a-z0-9-]+$/)
+      expect(g.title.length).toBeGreaterThan(0)
+    }
+  })
+
+  test('title 은 파일의 첫 H1 텍스트다', async () => {
+    const svc = new GuideService(makeCtx())
+    const guides = await svc.listGuides()
+    const cli = guides.find((g) => g.slug === '01-cli')
+    expect(cli?.title).toBe('CLI 사용법')
+  })
+})
+
+describe('GuideService — renderGuide', () => {
+  test('마크다운을 HTML 로 렌더하고 코드블록을 highlight.js 로 하이라이트한다', async () => {
+    const svc = new GuideService(makeCtx())
+    const guide = await svc.renderGuide('01-cli')
+    expect(guide.slug).toBe('01-cli')
+    // 코드블록은 hljs 클래스 + 언어 클래스를 받는다(서버사이드 하이라이트). 01-cli 는 bash 예시가 있다.
+    expect(guide.html).toContain('<code class="hljs language-bash">')
+    // highlight.js 가 토큰을 span 으로 감쌌다.
+    expect(guide.html).toContain('hljs-')
+  })
+
+  test('헤딩에 목차 앵커용 id 를 단다(github-slugger 규칙)', async () => {
+    const svc = new GuideService(makeCtx())
+    const guide = await svc.renderGuide('01-cli')
+    // "## mega g / generate" → 슬러그 "mega-g--generate"(목차 링크 #mega-g--generate 와 일치).
+    expect(guide.html).toContain('id="mega-g--generate"')
+    // "## 설치 + 빠른 시작" → "설치--빠른-시작"(한글 보존).
+    expect(guide.html).toContain('id="설치--빠른-시작"')
+  })
+
+  test('존재하지 않는 slug 는 MegaNotFoundError 를 던진다', async () => {
+    const svc = new GuideService(makeCtx())
+    await expect(svc.renderGuide('does-not-exist')).rejects.toBeInstanceOf(MegaNotFoundError)
+  })
+
+  test('경로 조작 slug 는 형식 검증에서 막힌다(MegaNotFoundError)', async () => {
+    const svc = new GuideService(makeCtx())
+    await expect(svc.renderGuide('../../etc/passwd')).rejects.toBeInstanceOf(MegaNotFoundError)
+    await expect(svc.renderGuide('01-cli/../02-router-controller')).rejects.toBeInstanceOf(MegaNotFoundError)
+  })
+})

package/sample/crud/test/apps/main/hash-task.test.js

@@ -0,0 +1,30 @@
+// @ts-check
+/**
+ * hash.task(sha256Loop) 단위 테스트 — 워커 task 함수가 결정적(deterministic)으로 SHA-256 을 N회 체인 해시하는지
+ * 검증한다. 워커 경계(worker_threads) 없이 함수만 직접 호출해 로직을 본다.
+ */
+import { describe, test, expect } from 'vitest'
+import { createHash } from 'node:crypto'
+import { sha256Loop } from '../../../apps/main/workers/hash.task.js'
+
+/** @param {string} input @param {number} rounds */
+function expected(input, rounds) {
+  let d = input
+  for (let i = 0; i < rounds; i++) d = createHash('sha256').update(d).digest('hex')
+  return d
+}
+
+describe('sha256Loop', () => {
+  test('rounds 회 체인 해시 결과가 결정적이다', async () => {
+    const r = await sha256Loop({ input: 'mega', rounds: 1 })
+    expect(r).toEqual({ digest: expected('mega', 1), rounds: 1 })
+    const r3 = await sha256Loop({ input: 'mega', rounds: 3 })
+    expect(r3.digest).toBe(expected('mega', 3))
+    expect(r3.rounds).toBe(3)
+  })
+
+  test('input 미지정 시 기본 입력(mega)을 쓴다', async () => {
+    const r = await sha256Loop({ rounds: 2 })
+    expect(r.digest).toBe(expected('mega', 2))
+  })
+})

package/sample/crud/test/apps/main/jobs-demo-service.test.js

@@ -0,0 +1,88 @@
+// @ts-check
+/**
+ * JobsDemoService 단위 테스트 — events()/dlq() 읽기 로직을 가짜 redis/NATS 핸들로 검증한다. enqueue(실 NATS
+ * publish)와 워커 소비·재시도·DLQ 라우팅은 통합 검증(E2E)이 커버한다.
+ */
+import { describe, test, expect } from 'vitest'
+import { JobsDemoService } from '../../../apps/main/services/jobs-demo-service.js'
+import { EmailJob } from '../../../apps/main/jobs/email-job.js'
+
+/**
+ * @param {{ events?: string[], jsm?: any }} [opts]
+ */
+function makeCtx({ events = [], jsm } = {}) {
+  const cache = {
+    native: {
+      /** @param {string} _k @param {number} start @param {number} stop */
+      async lrange(_k, start, stop) {
+        return events.slice(start, stop + 1)
+      },
+    },
+  }
+  const bus = { native: { jetstreamManager: async () => jsm } }
+  const ctx = {
+    log: { debug() {} },
+    cache: (/** @type {string} */ a) => (a === 'demo' ? cache : null),
+    bus: (/** @type {string} */ a) => (a === 'jobs' ? bus : null),
+  }
+  return { ctx }
+}
+
+/** code 프로퍼티를 단 에러(JetStream 404 모사). @param {string} code */
+function apiError(code) {
+  const e = new Error(`api error ${code}`)
+  Object.assign(e, { code })
+  return e
+}
+
+describe('JobsDemoService.events', () => {
+  test('redis LIST 의 JSON 문자열들을 파싱해 돌려준다', async () => {
+    const raw = [JSON.stringify({ id: 'e1', status: 'sent', attempt: 1 })]
+    const { ctx } = makeCtx({ events: raw })
+    const svc = new JobsDemoService(/** @type {any} */ (ctx))
+    const out = await svc.events()
+    expect(out).toEqual([{ id: 'e1', status: 'sent', attempt: 1 }])
+  })
+})
+
+describe('JobsDemoService.dlq', () => {
+  test('DLQ 스트림 미존재(404) 시 빈 상태를 돌려준다', async () => {
+    const jsm = { streams: { info: async () => { throw apiError('404') } } }
+    const { ctx } = makeCtx({ jsm })
+    const svc = new JobsDemoService(/** @type {any} */ (ctx))
+    expect(await svc.dlq()).toEqual({ count: 0, latest: null })
+  })
+
+  test('메시지가 있으면 카운트 + 가장 최근 1건을 돌려준다', async () => {
+    const body = {
+      originalSubject: EmailJob.subject,
+      failedAt: '2026-06-07T00:00:00.000Z',
+      deliveryCount: 3,
+      error: { name: 'Error', message: 'boom' },
+      payload: { id: 'e3', mode: 'fail' },
+    }
+    const jsm = {
+      streams: {
+        info: async () => ({ state: { messages: 2 } }),
+        getMessage: async () => ({ json: () => body }),
+      },
+    }
+    const { ctx } = makeCtx({ jsm })
+    const svc = new JobsDemoService(/** @type {any} */ (ctx))
+    const out = await svc.dlq()
+    expect(out.count).toBe(2)
+    expect(out.latest).toEqual({
+      failedAt: body.failedAt,
+      deliveryCount: 3,
+      error: 'boom',
+      payload: { id: 'e3', mode: 'fail' },
+    })
+  })
+
+  test('info 가 404 가 아닌 에러면 전파한다(인프라 장애를 묻지 않음)', async () => {
+    const jsm = { streams: { info: async () => { throw apiError('503') } } }
+    const { ctx } = makeCtx({ jsm })
+    const svc = new JobsDemoService(/** @type {any} */ (ctx))
+    await expect(svc.dlq()).rejects.toThrow(/503/)
+  })
+})