mega-framework 0.1.0

package/templates/channel/test.tpl

@@ -0,0 +1,19 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import { MegaTest } from 'mega-framework/test'
+import { {{Name}}Channel } from '{{importPath}}'
+
+describe('{{Name}}Channel', () => {
+  test('{{camelName}}.message 디스패치 → broadcast', async () => {
+    const ch = new {{Name}}Channel()
+    const { sock, ctx } = MegaTest.makeWs({ user: { id: 1 } })
+    await ch.dispatch(sock, { type: '{{camelName}}.message', payload: { text: 'hi' } }, ctx)
+    expect(ctx.channel.broadcasts).toContainEqual({ type: '{{camelName}}.message', payload: { text: 'hi' } })
+  })
+
+  test('알 수 없는 type → onMessage 폴백(throw 없음)', async () => {
+    const ch = new {{Name}}Channel()
+    const { sock, ctx } = MegaTest.makeWs({})
+    await expect(ch.dispatch(sock, { type: 'nope' }, ctx)).resolves.toBeUndefined()
+  })
+})

package/templates/controller/code.tpl

@@ -0,0 +1,16 @@
+// @ts-check
+/**
+ * {{Name}}Controller — HTTP 컨트롤러는 코어 베이스 클래스 없음(ADR-074). 모든 메서드 static,
+ * 단순 namespace 역할(this 미사용). 라우트에서 `router.http.get(path, {{Name}}Controller.index)` 로 참조.
+ */
+export class {{Name}}Controller {
+  /**
+   * 목록 — ctx.services.{{camelName}}.list 위임. 반환값은 자동 envelope 로 감싸진다(ADR-018).
+   * @param {import('fastify').FastifyRequest} req
+   * @param {import('fastify').FastifyReply} _res
+   * @param {Record<string, any>} ctx
+   */
+  static async index(req, _res, ctx) {
+    return ctx.services.{{camelName}}.list(req.query)
+  }
+}

package/templates/controller/route.tpl

@@ -0,0 +1,9 @@
+// @ts-check
+import { {{Name}}Controller } from '{{controllerImport}}'
+
+/**
+ * apps/{{app}} {{version}} 라우트 — {{Name}}Controller 정적 메서드 참조 등록(ADR-069/074).
+ */
+export default (/** @type {any} */ router) => {
+  router.http.get('/api/{{version}}/{{name}}', {{Name}}Controller.index)
+}

package/templates/controller/test.tpl

@@ -0,0 +1,14 @@
+// @ts-check
+import { describe, test, expect, vi } from 'vitest'
+import { MegaTest } from 'mega-framework/test'
+import { {{Name}}Controller } from '{{importPath}}'
+
+describe('{{Name}}Controller', () => {
+  test('index — ctx.services.{{camelName}}.list 에 위임', async () => {
+    const list = vi.fn(async () => [{ id: 1 }])
+    const { req, res, ctx } = MegaTest.makeHttp({ query: { page: '1' }, services: { {{camelName}}: { list } } })
+    const result = await {{Name}}Controller.index(req, res, ctx)
+    expect(result).toEqual([{ id: 1 }])
+    expect(list).toHaveBeenCalledWith({ page: '1' })
+  })
+})

package/templates/job/code.tpl

@@ -0,0 +1,23 @@
+// @ts-check
+import { MegaJob } from 'mega-framework'
+
+/**
+ * {{Name}}Job — NATS subject 구독 잡(ADR-028). `mega worker` 프로세스가 소비한다. `run` 이 throw 하면
+ * `static retries`·backoff 로 재시도하고 한도 초과 시 DLQ 로 이동한다.
+ */
+export class {{Name}}Job extends MegaJob {
+  static subject = '{{subject}}'
+  static bus = 'jobs'
+  static concurrency = 1
+  static retries = 3
+
+  /**
+   * @param {Record<string, any>} payload
+   * @param {Record<string, any>} ctx
+   * @returns {Promise<object>}
+   */
+  async run(payload, ctx) {
+    ctx.log?.info?.({ payload }, '{{camelName}}: run')
+    return { ok: true }
+  }
+}

package/templates/job/test.tpl

@@ -0,0 +1,17 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import { MegaJob } from 'mega-framework'
+import { {{Name}}Job } from '{{importPath}}'
+
+describe('{{Name}}Job', () => {
+  test('MegaJob 상속 + static subject/bus', () => {
+    expect(Object.getPrototypeOf({{Name}}Job)).toBe(MegaJob)
+    expect({{Name}}Job.subject).toBe('{{subject}}')
+    expect(typeof {{Name}}Job.bus).toBe('string')
+  })
+
+  test('run — payload 처리 후 결과 반환', async () => {
+    const job = new {{Name}}Job()
+    expect(await job.run({ a: 1 }, { log: { info() {} } })).toEqual({ ok: true })
+  })
+})

package/templates/locale/code.tpl

@@ -0,0 +1,3 @@
+{
+  "greeting": "{{Name}}"
+}

package/templates/locale/test.tpl

@@ -0,0 +1,13 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+describe('{{ns}} locale ({{lng}})', () => {
+  test('유효한 JSON 객체', () => {
+    const path = fileURLToPath(new URL('{{importPath}}', import.meta.url))
+    const data = JSON.parse(readFileSync(path, 'utf8'))
+    expect(typeof data).toBe('object')
+    expect(data).not.toBeNull()
+  })
+})

package/templates/middleware/code.tpl

@@ -0,0 +1,13 @@
+// @ts-check
+/**
+ * {{camelName}} 미들웨어 (ADR-091 — before/transform/after 중 before 단계). 라우트 `before` 로 쓰면
+ * `(req, reply)`, 글로벌 미들웨어로 쓰면 `(req, reply, ctx)` 를 받는다(ADR-134). 양쪽 호환.
+ * @param {import('fastify').FastifyRequest} req
+ * @param {import('fastify').FastifyReply} _res
+ * @param {Record<string, any>} [ctx]
+ * @returns {Promise<void>}
+ */
+export async function {{camelName}}(req, _res, ctx) {
+  const log = ctx?.log ?? req.log
+  log?.debug?.({ url: req.url }, '{{camelName}}: enter')
+}

package/templates/middleware/test.tpl

@@ -0,0 +1,11 @@
+// @ts-check
+import { describe, test, expect, vi } from 'vitest'
+import { {{camelName}} } from '{{importPath}}'
+
+describe('{{camelName}} 미들웨어', () => {
+  test('debug 로그 후 통과(throw 없음)', async () => {
+    const debug = vi.fn()
+    await {{camelName}}(/** @type {any} */ ({ url: '/x', log: { debug } }), /** @type {any} */ ({}), undefined)
+    expect(debug).toHaveBeenCalled()
+  })
+})

package/templates/migration/code.tpl

@@ -0,0 +1,20 @@
+// @ts-check
+/**
+ * 마이그레이션 {{name}} ({{timestamp}}). up = 적용, down = 롤백. `mega migrate`(up 일괄)·
+ * `mega migrate:down`(마지막 1개 롤백)·`mega migrate:status`(목록)로 실행한다(ADR-149). 적용 이력은
+ * 대상 DB 의 `mega_migrations` 테이블이 추적하며, 각 마이그레이션은 트랜잭션으로 감싸 적용된다.
+ *
+ * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db - 대상 DB 어댑터(트랜잭션 내 query).
+ * @returns {Promise<void>}
+ */
+export async function up(db) {
+  await db.query('-- TODO: {{name}} 적용(up) SQL')
+}
+
+/**
+ * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db
+ * @returns {Promise<void>}
+ */
+export async function down(db) {
+  await db.query('-- TODO: {{name}} 롤백(down) SQL')
+}

package/templates/migration/test.tpl

@@ -0,0 +1,14 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import { up, down } from '{{importPath}}'
+
+describe('migration {{name}}', () => {
+  test('up/down — db.query 호출', async () => {
+    /** @type {string[]} */
+    const sqls = []
+    const db = { query: async (/** @type {string} */ sql) => void sqls.push(sql) }
+    await up(db)
+    await down(db)
+    expect(sqls).toHaveLength(2)
+  })
+})

package/templates/model/code.tpl

@@ -0,0 +1,21 @@
+// @ts-check
+import { MegaModel } from 'mega-framework'
+
+/**
+ * {{Name}} 모델 — 데이터 소스는 `static table` 로 통일(SQL table / Mongo collection, ADR-081).
+ * `static adapter` 는 mega.config.js 의 services.databases 키를 가리킨다(ADR-061).
+ */
+export class {{Name}} extends MegaModel {
+  static adapter = 'primary'
+  static table = '{{table}}'
+
+  /**
+   * id 로 1건 조회. `this.query` 는 계측된 어댑터 query 위임(ADR-138).
+   * @param {string|number} id
+   * @returns {Promise<object|null>}
+   */
+  static async findById(id) {
+    const { rows } = await this.query('select * from {{table}} where id = $1', [id])
+    return rows[0] ?? null
+  }
+}

package/templates/model/test.tpl

@@ -0,0 +1,29 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import { MegaModel } from 'mega-framework'
+import { {{Name}} } from '{{importPath}}'
+
+describe('{{Name}} model', () => {
+  test('MegaModel 을 상속하고 static table/adapter 설정됨', () => {
+    expect(Object.getPrototypeOf({{Name}})).toBe(MegaModel)
+    expect({{Name}}.table).toBe('{{table}}')
+    expect(typeof {{Name}}.adapter).toBe('string')
+  })
+
+  test('findById — 어댑터 query 에 위임', async () => {
+    const orig = {{Name}}.query
+    /** @type {any[]} */
+    const calls = []
+    {{Name}}.query = async (/** @type {string} */ sql, /** @type {any[]} */ params) => {
+      calls.push({ sql, params })
+      return { rows: [{ id: params[0] }] }
+    }
+    try {
+      const row = await {{Name}}.findById(7)
+      expect(row).toEqual({ id: 7 })
+      expect(calls[0].params).toEqual([7])
+    } finally {
+      {{Name}}.query = orig
+    }
+  })
+})

package/templates/project/app.config.tpl

@@ -0,0 +1,8 @@
+// @ts-check
+/**
+ * apps/main/app.config.js — App-only + Shared-Reference 스코프(ADR-061). 기본 앱 `main`.
+ */
+export default {
+  name: 'main',
+  hosts: ['localhost', 'main.localhost'],
+}

package/templates/project/app.config.views.tpl

@@ -0,0 +1,37 @@
+// @ts-check
+/**
+ * apps/main/app.config.js — App-only + Shared-Reference 스코프(ADR-061). 기본 앱 `main`.
+ * EJS + ejs-mate 서버사이드 템플릿(ADR-011/136) + i18next 다국어(ADR-037/038/039) +
+ * @fastify/static 정적 자산(ADR-071) + Bootstrap 5 뷰(ADR-151)를 함께 켠 골격.
+ */
+export default {
+  name: 'main',
+  hosts: ['localhost', 'main.localhost'],
+
+  // EJS + ejs-mate — `views.dir` 기준 레이아웃/파셜 lookup. 렌더 시 req.t/req.lang 자동 병합.
+  // views 옵트인이라 HTML 폼 제출(urlencoded)도 자동 파싱된다(ADR-151, @fastify/formbody).
+  views: {
+    dir: 'apps/main/views',
+    layoutDir: 'layouts',
+    partialsDir: 'partials',
+  },
+
+  // i18next 다국어 — locale 은 쿠키(`mega.lang`)로만 결정(ADR-038). `<localesDir>/<scope>/<lng>.json`
+  // 레이아웃(scope=server/client, ADR-039). `ctx.t()`/뷰 `t()` 는 server scope. navbar 의 언어 메뉴가
+  // 쿠키를 굽고 새로고침한다.
+  i18n: {
+    default: 'ko',
+    available: ['ko', 'en'],
+    fallback: 'en',
+    localesDir: 'apps/main/locales',
+    exposeTranslations: true,
+  },
+
+  // 정적 자산 — `${prefix}/<파일>` 로 디스크 서빙(prefix 디폴트 `/static`). Bootstrap 5 vendored +
+  // 브랜드 CSS/JS 가 `apps/main/public/` 아래에 있다. dotfiles 기본 차단.
+  staticAssets: {
+    enabled: true,
+    dir: 'apps/main/public',
+    prefix: '/static',
+  },
+}

package/templates/project/ecosystem.config.tpl

@@ -0,0 +1,10 @@
+// PM2 ecosystem — server / scheduler / worker / ws-hub 프로세스 정의.
+// 사용: pm2 start ecosystem.config.cjs  (PM2 는 별도 설치: npm i -g pm2)
+module.exports = {
+  apps: [
+    { name: '{{name}}-server', script: 'node_modules/.bin/mega', args: 'start', instances: 1, autorestart: true },
+    { name: '{{name}}-scheduler', script: 'node_modules/.bin/mega', args: 'scheduler', instances: 1, autorestart: true },
+    { name: '{{name}}-worker', script: 'node_modules/.bin/mega', args: 'worker', instances: 2, autorestart: true },
+    { name: '{{name}}-ws-hub', script: 'node_modules/.bin/mega-ws-hub', instances: 1, autorestart: true },
+  ],
+}

package/templates/project/env.tpl

@@ -0,0 +1,12 @@
+# {{name}} 환경변수 (.env.example) — 복사해서 .env 로 쓰고 실제 값 채우기. .env 는 git 에 안 올림.
+
+# HTTP 포트
+PORT=3000
+
+# 세션 서명 시크릿(세션 사용 시 필수) — 32바이트 이상 랜덤
+# SESSION_SECRET=change-me
+
+# 데이터베이스/캐시/버스 연결 (어댑터 사용 시)
+# DATABASE_URL=postgres://user:pass@localhost:5432/{{name}}
+# REDIS_URL=redis://localhost:6379
+# NATS_URL=nats://localhost:4222

package/templates/project/gitignore.tpl

@@ -0,0 +1,8 @@
+node_modules/
+.env
+.env.local
+logs/
+*.log
+coverage/
+storage/
+.DS_Store

package/templates/project/locales/client/en.json.tpl

@@ -0,0 +1,3 @@
+{
+  "app_title": "{{name}}"
+}

package/templates/project/locales/client/ko.json.tpl

@@ -0,0 +1,3 @@
+{
+  "app_title": "{{name}}"
+}

package/templates/project/locales/server/en.json.tpl

@@ -0,0 +1,17 @@
+{
+  "welcome": "Welcome",
+  "nav_home": "Home",
+  "theme_toggle": "Toggle theme",
+  "footer_built": "Built with MEGA-FRAMEWORK · Bootstrap 5",
+  "hero_title": "Welcome to {{name}}",
+  "hero_subtitle": "A project built with MEGA-FRAMEWORK. EJS + ejs-mate server-side views, cookie-based i18n, and a Bootstrap 5 design come built in.",
+  "hero_cta_primary": "Framework docs",
+  "hero_cta_secondary": "Bootstrap docs",
+  "features_heading": "Built in",
+  "feature1_title": "Polished views",
+  "feature1_desc": "A Bootstrap 5 navbar, hero, and card grid make up the first screen.",
+  "feature2_title": "Language toggle",
+  "feature2_desc": "Switch Korean / English instantly from the navbar menu (cookie-based).",
+  "feature3_title": "Light & dark mode",
+  "feature3_desc": "Bootstrap 5.3 color modes toggle the theme and remember it in the browser."
+}

package/templates/project/locales/server/ko.json.tpl

@@ -0,0 +1,17 @@
+{
+  "welcome": "환영합니다",
+  "nav_home": "홈",
+  "theme_toggle": "테마 전환",
+  "footer_built": "MEGA-FRAMEWORK 로 제작 · Bootstrap 5",
+  "hero_title": "{{name}} 에 오신 걸 환영합니다",
+  "hero_subtitle": "MEGA-FRAMEWORK 로 만든 프로젝트입니다. EJS + ejs-mate 서버사이드 뷰, 쿠키 기반 다국어, Bootstrap 5 디자인이 기본 탑재되어 있습니다.",
+  "hero_cta_primary": "프레임워크 문서",
+  "hero_cta_secondary": "Bootstrap 문서",
+  "features_heading": "기본 탑재 기능",
+  "feature1_title": "세련된 뷰",
+  "feature1_desc": "Bootstrap 5 navbar · hero · 카드 그리드로 첫 화면이 구성됩니다.",
+  "feature2_title": "다국어 토글",
+  "feature2_desc": "navbar 의 언어 메뉴로 한국어/English 를 즉시 전환합니다(쿠키 기반).",
+  "feature3_title": "라이트·다크 모드",
+  "feature3_desc": "Bootstrap 5.3 color modes 로 테마를 전환하고 브라우저에 저장합니다."
+}

package/templates/project/mega.config.tpl

@@ -0,0 +1,11 @@
+// @ts-check
+/**
+ * mega.config.js — Global-only 스코프(ADR-061). 활성 앱 whitelist·전역 자원(databases/caches/buses)·
+ * 서버 설정만 둔다. App-only 키(cors/helmet 등)는 apps/<name>/app.config.js 로.
+ */
+export default {
+  apps: ['main'],
+  server: {
+    port: Number(process.env.PORT ?? 3000),
+  },
+}

package/templates/project/package.tpl

@@ -0,0 +1,25 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "mega start",
+    "start": "mega start",
+    "scheduler": "mega scheduler",
+    "worker": "mega worker",
+    "ws-hub": "mega-ws-hub",
+    "dev:all": "concurrently -n server,scheduler,worker -c blue,green,magenta \"mega start\" \"mega scheduler\" \"mega worker\"",
+    "test": "mega test"
+  },
+  "dependencies": {
+    "mega-framework": "^0.1.0"
+  },
+  "devDependencies": {
+    "concurrently": "^9.0.0",
+    "vitest": "^4.0.0"
+  }
+}

package/templates/project/public/css/app.css

@@ -0,0 +1,101 @@
+/*
+ * app.css — MEGA-FRAMEWORK 브랜드 소폭 커스텀(Bootstrap 5.3 위에 얹는다).
+ * Bootstrap 컴포넌트는 인스턴스 CSS 변수(--bs-btn-*, --bs-link-* 등)로 색을 잡으므로
+ * Sass 재컴파일 없이 변수만 덮어써 브랜드 색을 입힌다. per Bootstrap 5.3 CSS variables 문서.
+ */
+
+:root {
+  --brand: #5b4bff;
+  --brand-rgb: 91, 75, 255;
+  --brand-dark: #4a3fd6;
+  --brand-light: #efedff;
+}
+
+/* 링크·primary 강조를 브랜드 색으로(라이트/다크 공통) */
+a {
+  --bs-link-color-rgb: var(--brand-rgb);
+  --bs-link-hover-color-rgb: 74, 63, 214;
+}
+
+.btn-primary {
+  --bs-btn-bg: var(--brand);
+  --bs-btn-border-color: var(--brand);
+  --bs-btn-hover-bg: var(--brand-dark);
+  --bs-btn-hover-border-color: var(--brand-dark);
+  --bs-btn-active-bg: var(--brand-dark);
+  --bs-btn-active-border-color: var(--brand-dark);
+  --bs-btn-disabled-bg: var(--brand);
+  --bs-btn-disabled-border-color: var(--brand);
+}
+
+.btn-outline-primary {
+  --bs-btn-color: var(--brand);
+  --bs-btn-border-color: var(--brand);
+  --bs-btn-hover-bg: var(--brand);
+  --bs-btn-hover-border-color: var(--brand);
+  --bs-btn-active-bg: var(--brand);
+  --bs-btn-active-border-color: var(--brand);
+}
+
+.text-brand {
+  color: var(--brand) !important;
+}
+
+.navbar-brand {
+  font-weight: 700;
+  letter-spacing: -0.02em;
+}
+
+.navbar-brand .brand-dot {
+  color: var(--brand);
+}
+
+/* hero — 브랜드 그라데이션 배경 + 넉넉한 여백 */
+.hero {
+  background: radial-gradient(120% 120% at 0% 0%, rgba(var(--brand-rgb), 0.12), transparent 60%),
+    radial-gradient(120% 120% at 100% 0%, rgba(var(--brand-rgb), 0.08), transparent 55%);
+  border-radius: 1rem;
+}
+
+.hero h1 {
+  letter-spacing: -0.03em;
+}
+
+/* feature 카드 — hover 살짝 떠오르는 인터랙션 */
+.feature-card {
+  transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+
+.feature-card:hover {
+  transform: translateY(-3px);
+  box-shadow: 0 0.75rem 1.5rem rgba(var(--brand-rgb), 0.12);
+}
+
+.feature-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 3rem;
+  height: 3rem;
+  border-radius: 0.75rem;
+  background: var(--brand-light);
+  color: var(--brand);
+  font-size: 1.5rem;
+}
+
+[data-bs-theme='dark'] .feature-icon {
+  background: rgba(var(--brand-rgb), 0.18);
+}
+
+footer.site-footer {
+  border-top: 1px solid var(--bs-border-color);
+}
+
+/* 테마 토글 아이콘 — 현재 테마에서 "전환 대상"을 보여준다(라이트면 🌙, 다크면 ☀️). */
+[data-bs-theme='light'] .theme-icon-light {
+  display: none;
+}
+
+[data-bs-theme='dark'] .theme-icon-dark {
+  display: none;
+}

package/templates/project/public/js/app.js

@@ -0,0 +1,54 @@
+/*
+ * app.js — 다크모드 토글 + 언어 토글 + 삭제 확인 모달 wiring(클라이언트 동작).
+ *
+ * helmet CSP(script-src 'self')가 인라인 스크립트를 막으므로 모든 클라 동작은 외부 파일로 둔다(ADR-153).
+ * 다크모드: 페인트 전 적용은 theme-init.js(<head>), 토글은 여기서. localStorage('mega.theme') 저장.
+ * 언어:     프레임워크가 locale 을 쿠키(mega.lang)로만 감지하므로(ADR-038), 토글은 쿠키를 굽고 새로고침.
+ * 삭제모달: 트리거 버튼의 data-action/data-name 으로 form action·문구를 채운다(#deleteModal 있을 때만).
+ */
+;(function () {
+  'use strict'
+
+  /** @param {string} theme */
+  function applyTheme(theme) {
+    document.documentElement.setAttribute('data-bs-theme', theme)
+    try {
+      localStorage.setItem('mega.theme', theme)
+    } catch (e) {
+      // localStorage 차단(사생활 모드 등)은 비치명적 — 이번 페이지에서만 테마가 안 남을 뿐.
+      console.debug('theme persist skipped:', e && e.message)
+    }
+  }
+
+  document.querySelectorAll('[data-theme-toggle]').forEach(function (btn) {
+    btn.addEventListener('click', function () {
+      var current = document.documentElement.getAttribute('data-bs-theme') === 'dark' ? 'dark' : 'light'
+      applyTheme(current === 'dark' ? 'light' : 'dark')
+    })
+  })
+
+  document.querySelectorAll('[data-lang]').forEach(function (el) {
+    el.addEventListener('click', function (e) {
+      e.preventDefault()
+      var lang = el.getAttribute('data-lang')
+      // 1년 유지, 같은 사이트 요청에만 전송(samesite=lax).
+      document.cookie = 'mega.lang=' + encodeURIComponent(lang) + '; path=/; max-age=31536000; samesite=lax'
+      location.reload()
+    })
+  })
+
+  // 삭제 확인 모달 — 클릭된 행 버튼의 data-action(삭제 URL)·data-name 으로 form·문구를 채운다.
+  // #deleteModal 이 있는 페이지(예: 목록)에서만 동작하고, 없으면 no-op.
+  var deleteModal = document.getElementById('deleteModal')
+  if (deleteModal) {
+    deleteModal.addEventListener('show.bs.modal', function (event) {
+      var btn = event.relatedTarget
+      if (!btn) return
+      var form = document.getElementById('deleteForm')
+      var action = btn.getAttribute('data-action')
+      if (form && action) form.setAttribute('action', action)
+      var nameEl = document.getElementById('deleteModalName')
+      if (nameEl) nameEl.textContent = btn.getAttribute('data-name') || ''
+    })
+  }
+})()

package/templates/project/public/js/theme-init.js

@@ -0,0 +1,12 @@
+/*
+ * theme-init.js — 저장된 테마를 페인트 전에 적용(FOUC 방지). layout <head> 에서 동기 로드한다.
+ * helmet CSP(script-src 'self')가 인라인 스크립트를 막으므로 외부 파일로 둔다(ADR-153).
+ */
+;(function () {
+  try {
+    var t = localStorage.getItem('mega.theme')
+    if (t) document.documentElement.setAttribute('data-bs-theme', t)
+  } catch (e) {
+    // localStorage 차단(사생활 모드 등)은 비치명적 — 기본 테마로 렌더된다.
+  }
+})()