mega-framework 0.1.0

package/sample/crud/apps/main/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/sample/crud/apps/main/public/css/guide.css

@@ -0,0 +1,137 @@
+/* 가이드 뷰어 전용 스타일 — 좌측 목차 사이드바 + 서버사이드 렌더된 마크다운 본문. */
+
+/* --- 사이드바(목차) --- */
+.guide-sidebar {
+  position: sticky;
+  top: 1.5rem;
+}
+
+.guide-toc .nav-link {
+  padding: 0.25rem 0.5rem;
+  border-radius: 0.375rem;
+  color: var(--bs-secondary-color);
+  font-size: 0.9rem;
+}
+
+.guide-toc .nav-link:hover {
+  background: var(--bs-secondary-bg);
+  color: var(--bs-body-color);
+}
+
+.guide-toc .nav-link.active {
+  background: var(--bs-primary-bg-subtle);
+  color: var(--bs-primary-text-emphasis);
+  font-weight: 600;
+}
+
+/* --- 마크다운 본문 --- */
+.guide-content {
+  line-height: 1.75;
+  word-break: break-word;
+}
+
+/* 앵커 점프 시 헤딩이 화면 맨 위에 딱 붙지 않게 여유를 둔다(목차 링크 가독성). */
+.guide-content :is(h1, h2, h3, h4) {
+  scroll-margin-top: 1.5rem;
+  font-weight: 600;
+  line-height: 1.3;
+}
+
+.guide-content h1 {
+  font-size: 1.9rem;
+  margin-bottom: 1rem;
+}
+
+.guide-content h2 {
+  font-size: 1.5rem;
+  margin-top: 2.25rem;
+  margin-bottom: 0.85rem;
+  padding-bottom: 0.3rem;
+  border-bottom: 1px solid var(--bs-border-color);
+}
+
+.guide-content h3 {
+  font-size: 1.2rem;
+  margin-top: 1.75rem;
+  margin-bottom: 0.6rem;
+}
+
+.guide-content h4 {
+  font-size: 1.05rem;
+  margin-top: 1.25rem;
+  margin-bottom: 0.5rem;
+}
+
+.guide-content > p:first-child > strong:only-child,
+.guide-content blockquote {
+  color: var(--bs-secondary-color);
+}
+
+.guide-content blockquote {
+  margin: 1rem 0;
+  padding: 0.25rem 1rem;
+  border-left: 4px solid var(--bs-border-color);
+}
+
+.guide-content blockquote > :last-child {
+  margin-bottom: 0;
+}
+
+/* 인라인 코드 — 배경 칩. 코드블록(pre code)은 highlight.js 테마가 색을 입히므로 칩 스타일을 빼준다. */
+.guide-content :not(pre) > code {
+  padding: 0.15em 0.4em;
+  font-size: 0.875em;
+  background: var(--bs-secondary-bg);
+  border-radius: 0.3rem;
+}
+
+.guide-content pre {
+  margin: 1rem 0;
+  border: 1px solid var(--bs-border-color);
+  border-radius: 0.5rem;
+  overflow: hidden;
+}
+
+.guide-content pre code.hljs {
+  border-radius: 0.5rem;
+  font-size: 0.85rem;
+  line-height: 1.55;
+}
+
+/* 표 — Bootstrap 의 .table 클래스를 못 붙이므로 마크다운 표에 직접 스타일을 준다. */
+.guide-content table {
+  width: 100%;
+  margin: 1rem 0;
+  border-collapse: collapse;
+  font-size: 0.9rem;
+}
+
+.guide-content th,
+.guide-content td {
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--bs-border-color);
+  text-align: left;
+  vertical-align: top;
+}
+
+.guide-content thead th {
+  background: var(--bs-secondary-bg);
+}
+
+.guide-content img {
+  max-width: 100%;
+  height: auto;
+}
+
+.guide-content ul,
+.guide-content ol {
+  padding-left: 1.5rem;
+}
+
+.guide-content li + li {
+  margin-top: 0.25rem;
+}
+
+.guide-content hr {
+  margin: 2rem 0;
+}

package/sample/crud/apps/main/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/sample/crud/apps/main/public/js/perf.js

@@ -0,0 +1,129 @@
+// perf.js — /perf 벤치마크 UI 클라이언트. CSP(script-src 'self')라 외부 파일·인라인 핸들러 없음.
+// POST /perf/run 은 JSON 요청 → CSRF 토큰 면제(Origin 검증, ADR-051)라 토큰 헤더 불필요. 응답 envelope
+// { ok, data, meta } 에서 data 를 꺼내 결과 표에 한 행씩 누적한다(페이지 reload 시 초기화).
+(function () {
+  'use strict'
+
+  /** @param {string} id @returns {HTMLElement} */
+  function $(id) {
+    var el = document.getElementById(id)
+    if (!el) throw new Error('missing element #' + id)
+    return el
+  }
+
+  var runBtn = $('pf-run')
+  var clearBtn = $('pf-clear')
+  var spinner = $('pf-spinner')
+  var errorBox = $('pf-error')
+  var errorDetail = $('pf-error-detail')
+  var resultsBody = $('pf-results')
+
+  /** 텍스트 셀 생성(textContent — XSS 방지). @param {string|number} text @param {boolean} mono @returns {HTMLTableCellElement} */
+  function cell(text, mono) {
+    var td = document.createElement('td')
+    td.textContent = String(text)
+    td.className = mono ? 'text-end font-monospace' : 'text-end'
+    return td
+  }
+
+  /** 숫자 천단위 콤마. @param {number} v @returns {string} */
+  function n(v) {
+    return Number(v).toLocaleString('en-US')
+  }
+
+  /** 결과 1건을 표 맨 위에 추가. @param {object} d - 응답 data. */
+  function addRow(d) {
+    var empty = document.getElementById('pf-empty')
+    if (empty) empty.remove()
+
+    var tr = document.createElement('tr')
+
+    var nameTd = document.createElement('td')
+    nameTd.className = 'font-monospace'
+    nameTd.textContent = d.scenario
+    if (d.clamped) {
+      // 시나리오 상한으로 반복/동시성이 줄어든 경우 배지로 드러낸다(조용한 절삭 아님).
+      var badge = document.createElement('span')
+      badge.className = 'badge text-bg-warning ms-1'
+      badge.textContent = 'clamped'
+      var parts = []
+      if (d.clamped.iterations) parts.push('iter ' + d.clamped.iterations.requested + '→' + d.clamped.iterations.applied)
+      if (d.clamped.concurrency) parts.push('conc ' + d.clamped.concurrency.requested + '→' + d.clamped.concurrency.applied)
+      badge.title = parts.join(', ')
+      nameTd.appendChild(badge)
+    }
+    tr.appendChild(nameTd)
+
+    tr.appendChild(cell(n(d.iterations), false))
+    tr.appendChild(cell(n(d.concurrency), false))
+    tr.appendChild(cell(n(d.durationMs), true))
+    tr.appendChild(cell(n(d.rps), true))
+    tr.appendChild(cell(d.avg, true))
+    tr.appendChild(cell(d.p50, true))
+    tr.appendChild(cell(d.p90, true))
+    tr.appendChild(cell(d.p95, true))
+    tr.appendChild(cell(d.p99, true))
+    tr.appendChild(cell(d.min, true))
+    tr.appendChild(cell(d.max, true))
+    tr.appendChild(cell(d.ok + '/' + d.fail, true))
+
+    resultsBody.insertBefore(tr, resultsBody.firstChild)
+  }
+
+  /** 폼 입력을 요청 body 로. 빈 concurrency/payload 는 보내지 않음(서비스 디폴트 적용). @returns {object} */
+  function readForm() {
+    var body = {
+      scenario: $('pf-scenario').value,
+      iterations: Number($('pf-iterations').value),
+    }
+    var conc = $('pf-concurrency').value
+    var payload = $('pf-payload').value
+    if (conc !== '') body.concurrency = Number(conc)
+    if (payload !== '') body.payloadSize = Number(payload)
+    return body
+  }
+
+  runBtn.addEventListener('click', function () {
+    runBtn.disabled = true
+    spinner.classList.remove('d-none')
+    errorBox.classList.add('d-none')
+
+    fetch('/perf/run', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify(readForm()),
+    })
+      .then(function (res) {
+        return res.json().then(function (body) {
+          if (!res.ok || !body.ok) {
+            var msg = body && body.error ? body.error.code + ': ' + body.error.message : 'run ' + res.status
+            throw new Error(msg)
+          }
+          return body.data
+        })
+      })
+      .then(function (data) {
+        addRow(data)
+      })
+      .catch(function (err) {
+        errorDetail.textContent = String(err && err.message ? err.message : err)
+        errorBox.classList.remove('d-none')
+      })
+      .finally(function () {
+        runBtn.disabled = false
+        spinner.classList.add('d-none')
+      })
+  })
+
+  clearBtn.addEventListener('click', function () {
+    resultsBody.innerHTML = ''
+    var tr = document.createElement('tr')
+    tr.id = 'pf-empty'
+    var td = document.createElement('td')
+    td.colSpan = 13
+    td.className = 'text-center text-body-secondary py-3'
+    td.textContent = resultsBody.getAttribute('data-empty') || ''
+    tr.appendChild(td)
+    resultsBody.appendChild(tr)
+  })
+})()

package/sample/crud/apps/main/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 차단(사생활 모드 등)은 비치명적 — 기본 테마로 렌더된다.
+  }
+})()

package/sample/crud/apps/main/public/js/upload-demo.js

@@ -0,0 +1,63 @@
+// @ts-check
+/*
+ * /demo/upload 클라이언트 — 파일 업로드 데모(ADR-133).
+ *
+ * multipart/form-data 는 ADR-051 에서 "폼"으로 분류돼 CSRF 토큰 검증을 받는다. 스트리밍 multipart 는
+ * preHandler 시점에 body 가 안 파싱돼 `_csrf` 바디 필드를 못 읽으므로, 토큰을 **헤더**(`csrf-token`)로 보낸다.
+ * HTML 폼은 커스텀 헤더를 못 보내므로 fetch + FormData 로 제출한다. 성공하면 페이지를 새로고침해
+ * 서버 렌더 "최근 업로드" 목록(redis)을 갱신한다.
+ */
+;(function () {
+  var $ = function (/** @type {string} */ id) {
+    return /** @type {HTMLElement} */ (document.getElementById(id))
+  }
+
+  var form = /** @type {HTMLFormElement} */ ($('up-form'))
+  if (!form) return
+  var csrf = form.getAttribute('data-csrf') || ''
+  var fileInput = /** @type {HTMLInputElement} */ ($('up-file'))
+  var submitBtn = /** @type {HTMLButtonElement} */ ($('up-submit'))
+  var spinner = $('up-spinner')
+  var errorBox = $('up-error')
+  var errorDetail = $('up-error-detail')
+
+  form.addEventListener('submit', function (e) {
+    e.preventDefault()
+    if (!fileInput.files || fileInput.files.length === 0) return
+
+    submitBtn.disabled = true
+    spinner.classList.remove('d-none')
+    errorBox.classList.add('d-none')
+
+    var fd = new FormData()
+    for (var i = 0; i < fileInput.files.length; i++) fd.append('file', fileInput.files[i])
+
+    fetch('/demo/upload', {
+      method: 'POST',
+      headers: { 'csrf-token': csrf, accept: 'application/json' },
+      body: fd,
+    })
+      .then(function (res) {
+        return res.json().then(function (body) {
+          if (!res.ok) {
+            // 프레임워크 에러 엔벨로프 { ok:false, error:{ message } } — MIME 거부(415)/크기 초과(413) 등.
+            var msg = body && body.error && body.error.message ? body.error.message : 'upload ' + res.status
+            throw new Error(msg)
+          }
+          return body
+        })
+      })
+      .then(function () {
+        // 성공 — 서버 렌더 최근 목록을 갱신하러 새로고침.
+        window.location.assign('/demo/upload')
+      })
+      .catch(function (err) {
+        errorDetail.textContent = String(err && err.message ? err.message : err)
+        errorBox.classList.remove('d-none')
+      })
+      .finally(function () {
+        submitBtn.disabled = false
+        spinner.classList.add('d-none')
+      })
+  })
+})()

package/sample/crud/apps/main/public/js/worker-demo.js

@@ -0,0 +1,92 @@
+// @ts-check
+/*
+ * /demo/worker 클라이언트 — CPU 워커 풀 데모(ADR-124).
+ *
+ *  1) 하트비트: 250ms 마다 /demo/worker/ping(JSON)을 때려 왕복 지연을 잰다. 워커 계산이 도는 동안에도 이
+ *     지연이 작게 유지되면 메인 스레드(이벤트 루프)가 안 막힌 것이다 — 만약 계산을 메인 스레드에서 했다면
+ *     이 ping 들이 계산이 끝날 때까지 통째로 멈춘다.
+ *  2) 실행: Run 버튼이 /demo/worker/run 에 JSON POST(폼 아님 → CSRF 토큰 면제 + Origin 검증, ADR-051)로
+ *     반복 횟수를 보내 워커 풀에서 해시를 돌리고 결과(digest/rounds/ms)를 보여준다.
+ */
+;(function () {
+  var $ = function (/** @type {string} */ id) {
+    return /** @type {HTMLElement} */ (document.getElementById(id))
+  }
+
+  // ── 하트비트 ──────────────────────────────────────────────────────────────
+  var pingCount = 0
+  var countEl = $('wd-ping-count')
+  var latencyEl = $('wd-ping-latency')
+  var timeEl = $('wd-ping-time')
+
+  // 1초 간격 — 앱 기본 rate limit(100/분, ADR-073)을 넘지 않게 한다(라우터가 per-route 면제를 노출하지
+  // 않으므로 빈도 자체를 한도 안에 둔다). 탭이 숨겨지면 멈춰 불필요한 요청을 줄인다.
+  var HEARTBEAT_MS = 1000
+
+  function heartbeat() {
+    if (document.hidden) {
+      setTimeout(heartbeat, HEARTBEAT_MS)
+      return
+    }
+    var started = performance.now()
+    fetch('/demo/worker/ping', { headers: { accept: 'application/json' } })
+      .then(function (res) {
+        if (!res.ok) throw new Error('ping ' + res.status)
+        return res.json()
+      })
+      .then(function () {
+        pingCount += 1
+        countEl.textContent = String(pingCount)
+        latencyEl.textContent = String(Math.round(performance.now() - started))
+        timeEl.textContent = new Date().toLocaleTimeString('ko-KR', { hour12: false })
+      })
+      .catch(function () {
+        // 세션 만료(로그인 리다이렉트)·네트워크 끊김 등은 다음 주기에 자연 복구된다 — 표시만 비운다.
+        latencyEl.textContent = '—'
+      })
+      .finally(function () {
+        setTimeout(heartbeat, HEARTBEAT_MS)
+      })
+  }
+  heartbeat()
+
+  // ── 실행 ────────────────────────────────────────────────────────────────
+  var runBtn = /** @type {HTMLButtonElement} */ ($('wd-run'))
+  var spinner = $('wd-spinner')
+  var roundsInput = /** @type {HTMLInputElement} */ ($('wd-rounds'))
+  var resultBox = $('wd-result')
+  var errorBox = $('wd-error')
+  var errorDetail = $('wd-error-detail')
+
+  runBtn.addEventListener('click', function () {
+    runBtn.disabled = true
+    spinner.classList.remove('d-none')
+    errorBox.classList.add('d-none')
+
+    fetch('/demo/worker/run', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({ rounds: Number(roundsInput.value) }),
+    })
+      .then(function (res) {
+        if (!res.ok) throw new Error('run ' + res.status)
+        return res.json()
+      })
+      .then(function (body) {
+        // 프레임워크 응답 엔벨로프 { ok, data, meta } — 실제 결과는 body.data 에 있다.
+        var data = body && body.data ? body.data : body
+        $('wd-rounds-out').textContent = String(data.rounds)
+        $('wd-ms-out').textContent = data.ms + ' ms'
+        $('wd-digest-out').textContent = data.digest
+        resultBox.classList.remove('d-none')
+      })
+      .catch(function (err) {
+        errorDetail.textContent = String(err && err.message ? err.message : err)
+        errorBox.classList.remove('d-none')
+      })
+      .finally(function () {
+        runBtn.disabled = false
+        spinner.classList.add('d-none')
+      })
+  })
+})()