mega-framework 0.1.0

package/templates/project/route.test.tpl

@@ -0,0 +1,13 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import routes from '../../../apps/main/routes/index.js'
+
+describe('main app index route', () => {
+  test('GET / 등록 + hello world 반환', 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({ message: 'Hello from {{name}}!' })
+  })
+})

package/templates/project/route.test.views.tpl

@@ -0,0 +1,15 @@
+// @ts-check
+import { describe, test, expect, vi } from 'vitest'
+import routes from '../../../apps/main/routes/index.js'
+
+describe('main app index route (views)', () => {
+  test('GET / 가 index 뷰를 렌더', async () => {
+    /** @type {Function|undefined} */
+    let handler
+    routes({ http: { get: (/** @type {string} */ _p, /** @type {Function} */ h) => void (handler = h) } })
+    expect(typeof handler).toBe('function')
+    const ctx = { t: (/** @type {string} */ k) => k, render: vi.fn(() => 'html') }
+    await /** @type {any} */ (handler)({}, {}, ctx)
+    expect(ctx.render).toHaveBeenCalledWith('index', { title: 'welcome' })
+  })
+})

package/templates/project/route.tpl

@@ -0,0 +1,10 @@
+// @ts-check
+/**
+ * apps/main 기본 라우트 — 자동 로딩(loadRoutes). `mega start` 후 GET / 로 hello world.
+ */
+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 { message: 'Hello from {{name}}!' }
+  })
+}

package/templates/project/route.views.tpl

@@ -0,0 +1,10 @@
+// @ts-check
+/**
+ * apps/main 기본 라우트 — 자동 로딩(loadRoutes). `mega start` 후 GET / 로 Bootstrap 5 뷰를 렌더한다.
+ */
+export default (/** @type {any} */ router) => {
+  router.http.get('/', async (/** @type {any} */ _req, /** @type {any} */ _reply, /** @type {any} */ ctx) => {
+    // ctx.render 가 EJS + ejs-mate 로 index.ejs 를 렌더한다(req.t/req.lang 자동 병합 → 다국어 뷰).
+    return ctx.render('index', { title: ctx.t('welcome') })
+  })
+}

package/templates/project/views/index.ejs.tpl

@@ -0,0 +1,58 @@
+<% layout('layouts/main') %>
+
+<section class="hero p-4 p-md-5 mb-5">
+  <div class="row align-items-center g-4">
+    <div class="col-lg-7">
+      <span class="badge text-bg-light border mb-3">{{name}}</span>
+      <h1 class="display-5 fw-bold mb-3"><%= t('hero_title') %></h1>
+      <p class="fs-5 text-body-secondary mb-4"><%= t('hero_subtitle') %></p>
+      <div class="d-flex flex-wrap gap-2">
+        <a href="https://www.npmjs.com/package/mega-framework" class="btn btn-primary btn-lg" target="_blank" rel="noopener"
+          ><%= t('hero_cta_primary') %></a
+        >
+        <a href="https://getbootstrap.com/" class="btn btn-outline-secondary btn-lg" target="_blank" rel="noopener"
+          ><%= t('hero_cta_secondary') %></a
+        >
+      </div>
+    </div>
+    <div class="col-lg-5 text-center d-none d-lg-block">
+      <div class="display-1">🚀</div>
+    </div>
+  </div>
+</section>
+
+<section>
+  <h2 class="h4 mb-4"><%= t('features_heading') %></h2>
+  <div class="row g-4">
+    <div class="col-md-4">
+      <div class="card h-100 feature-card border-0 shadow-sm">
+        <div class="card-body">
+          <div class="feature-icon mb-3">🎨</div>
+          <h3 class="h5 card-title"><%= t('feature1_title') %></h3>
+          <p class="card-text text-body-secondary mb-0"><%= t('feature1_desc') %></p>
+        </div>
+      </div>
+    </div>
+    <div class="col-md-4">
+      <div class="card h-100 feature-card border-0 shadow-sm">
+        <div class="card-body">
+          <div class="feature-icon mb-3">🌐</div>
+          <h3 class="h5 card-title"><%= t('feature2_title') %></h3>
+          <p class="card-text text-body-secondary mb-0"><%= t('feature2_desc') %></p>
+        </div>
+      </div>
+    </div>
+    <div class="col-md-4">
+      <div class="card h-100 feature-card border-0 shadow-sm">
+        <div class="card-body">
+          <div class="feature-icon mb-3">🌓</div>
+          <h3 class="h5 card-title"><%= t('feature3_title') %></h3>
+          <p class="card-text text-body-secondary mb-0"><%= t('feature3_desc') %></p>
+        </div>
+      </div>
+    </div>
+  </div>
+  <p class="text-body-secondary small mt-4 mb-0">
+    <code>apps/main/views/index.ejs</code> · <code>lang=<%= lang %></code>
+  </p>
+</section>

package/templates/project/views/layout.ejs.tpl

@@ -0,0 +1,73 @@
+<!doctype html>
+<html lang="<%= lang %>" data-bs-theme="light">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title><%= typeof title !== 'undefined' ? title : '{{name}}' %></title>
+    <%# FOUC 방지 — 저장된 테마를 페인트 전에 적용. CSP(script-src 'self')라 인라인 불가 → 외부 파일. %>
+    <script src="/static/js/theme-init.js"></script>
+    <link rel="stylesheet" href="/static/vendor/bootstrap/bootstrap.min.css" />
+    <link rel="stylesheet" href="/static/css/app.css" />
+  </head>
+  <body class="d-flex flex-column min-vh-100">
+    <nav class="navbar navbar-expand-md border-bottom">
+      <div class="container">
+        <a class="navbar-brand" href="/">{{name}}</a>
+        <button
+          class="navbar-toggler"
+          type="button"
+          data-bs-toggle="collapse"
+          data-bs-target="#navmenu"
+          aria-controls="navmenu"
+          aria-expanded="false"
+          aria-label="menu"
+        >
+          <span class="navbar-toggler-icon"></span>
+        </button>
+        <div class="collapse navbar-collapse" id="navmenu">
+          <ul class="navbar-nav me-auto">
+            <li class="nav-item"><a class="nav-link" href="/"><%= t('nav_home') %></a></li>
+          </ul>
+          <div class="d-flex align-items-center gap-2">
+            <button
+              type="button"
+              class="btn btn-outline-secondary btn-sm"
+              data-theme-toggle
+              aria-label="<%= t('theme_toggle') %>"
+              title="<%= t('theme_toggle') %>"
+            >
+              <span class="theme-icon-light">☀️</span><span class="theme-icon-dark">🌙</span>
+            </button>
+            <div class="dropdown">
+              <button
+                class="btn btn-outline-secondary btn-sm dropdown-toggle"
+                type="button"
+                data-bs-toggle="dropdown"
+                aria-expanded="false"
+              >
+                <%= lang === 'ko' ? '한국어' : 'English' %>
+              </button>
+              <ul class="dropdown-menu dropdown-menu-end">
+                <li><a class="dropdown-item" href="#" data-lang="ko">한국어</a></li>
+                <li><a class="dropdown-item" href="#" data-lang="en">English</a></li>
+              </ul>
+            </div>
+          </div>
+        </div>
+      </div>
+    </nav>
+
+    <main class="container py-4 py-md-5 flex-grow-1">
+      <%- body %>
+    </main>
+
+    <footer class="site-footer py-4 mt-auto">
+      <div class="container text-center text-body-secondary small">
+        <%= t('footer_built') %>
+      </div>
+    </footer>
+
+    <script src="/static/vendor/bootstrap/bootstrap.bundle.min.js"></script>
+    <script src="/static/js/app.js"></script>
+  </body>
+</html>

package/templates/project/vitest.config.tpl

@@ -0,0 +1,8 @@
+// @ts-check
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.js', 'apps/**/*.test.js', 'shared/**/*.test.js'],
+  },
+})

package/templates/route/code.tpl

@@ -0,0 +1,11 @@
+// @ts-check
+/**
+ * {{name}} 라우트 — 자동 로딩(loadRoutes) 대상. `export default (router) => { ... }` 단일 시그니처
+ * (ADR-074/089). 핸들러는 인라인 함수 또는 정적 메서드 참조(둘 다 그냥 함수).
+ */
+export default (/** @type {any} */ router) => {
+  router.http.get('/{{name}}', async (/** @type {any} */ _req, /** @type {any} */ _res, /** @type {any} */ _ctx) => {
+    // 핸들러는 raw data 만 반환한다 — 프레임워크가 `{ ok, data, meta }` envelope 로 자동 wrap(ADR-018).
+    return { resource: '{{name}}' }
+  })
+}

package/templates/route/test.tpl

@@ -0,0 +1,26 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import routes from '{{importPath}}'
+
+describe('{{name}} routes', () => {
+  /** @returns {{ http: Record<string, any>, calls: any[] }} */
+  function makeRouter() {
+    /** @type {any[]} */
+    const calls = []
+    const rec = (/** @type {string} */ method) => (/** @type {string} */ path, /** @type {Function} */ handler) => calls.push({ method, path, handler })
+    return { http: { get: rec('get'), post: rec('post'), put: rec('put'), patch: rec('patch'), delete: rec('delete') }, calls }
+  }
+
+  test('GET /{{name}} 등록', () => {
+    const router = makeRouter()
+    routes(router)
+    expect(router.calls).toContainEqual(expect.objectContaining({ method: 'get', path: '/{{name}}' }))
+  })
+
+  test('핸들러가 data 반환', async () => {
+    const router = makeRouter()
+    routes(router)
+    const handler = router.calls.find((/** @type {any} */ c) => c.path === '/{{name}}').handler
+    expect(await handler({}, {}, {})).toEqual({ resource: '{{name}}' })
+  })
+})

package/templates/schedule/code.tpl

@@ -0,0 +1,19 @@
+// @ts-check
+import { MegaSchedule } from 'mega-framework'
+
+/**
+ * {{Name}}Schedule — cron 정기 작업(ADR-028). `mega scheduler` 프로세스가 실행한다. 다중 인스턴스
+ * 중복 방지가 필요하면 `static lock = { lock: '<alias>', ttl: 60000 }`(ms) 을 추가한다(ADR-029).
+ */
+export class {{Name}}Schedule extends MegaSchedule {
+  static cron = '{{cron}}'
+  static timezone = 'Asia/Seoul'
+
+  /**
+   * @param {Record<string, any>} ctx
+   * @returns {Promise<void>}
+   */
+  async run(ctx) {
+    ctx.log?.info?.('{{camelName}}: run')
+  }
+}

package/templates/schedule/test.tpl

@@ -0,0 +1,17 @@
+// @ts-check
+import { describe, test, expect, vi } from 'vitest'
+import { MegaSchedule } from 'mega-framework'
+import { {{Name}}Schedule } from '{{importPath}}'
+
+describe('{{Name}}Schedule', () => {
+  test('MegaSchedule 상속 + static cron 설정', () => {
+    expect(Object.getPrototypeOf({{Name}}Schedule)).toBe(MegaSchedule)
+    expect(typeof {{Name}}Schedule.cron).toBe('string')
+  })
+
+  test('run — ctx.log 호출', async () => {
+    const info = vi.fn()
+    await new {{Name}}Schedule().run({ log: { info } })
+    expect(info).toHaveBeenCalled()
+  })
+})

package/templates/service/code.tpl

@@ -0,0 +1,18 @@
+// @ts-check
+import { MegaService } from 'mega-framework'
+
+/**
+ * {{Name}}Service — {{name}} 도메인 비즈니스 로직. 컨트롤러는 모델을 직접 import 하지 않고 서비스를
+ * 경유한다(ADR-022). 서비스 안에서는 모델 import 가 허용된다(모델의 유일한 접근 경로).
+ */
+export class {{Name}}Service extends MegaService {
+  /**
+   * 목록 조회 예시. 실제 구현은 모델을 호출한다(예: `return {{Name}}.list(query)`).
+   * @param {object} [query]
+   * @returns {Promise<object[]>}
+   */
+  async list(query = {}) {
+    this.log.debug({ query }, '{{camelName}}.list')
+    return []
+  }
+}

package/templates/service/test.tpl

@@ -0,0 +1,17 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import { MegaService } from 'mega-framework'
+import { {{Name}}Service } from '{{importPath}}'
+
+describe('{{Name}}Service', () => {
+  const ctx = { log: { debug() {} } }
+
+  test('MegaService 를 상속', () => {
+    expect(new {{Name}}Service(ctx)).toBeInstanceOf(MegaService)
+  })
+
+  test('list — 기본 빈 배열', async () => {
+    const svc = new {{Name}}Service(ctx)
+    expect(await svc.list({ page: 1 })).toEqual([])
+  })
+})

package/templates/worker/code.tpl

@@ -0,0 +1,14 @@
+// @ts-check
+import { MegaWorker } from 'mega-framework'
+
+/**
+ * {{Name}}Worker — CPU 격리 워커 풀(ADR-124). 작업 로직은 `static taskFile` 모듈에 named export 한
+ * async 함수다(worker_threads/process 경계는 함수·클로저를 못 넘기므로 파일 경로 필수). 호출:
+ * `ctx.workers['{{name}}'].run('{{camelName}}', args)`.
+ */
+export class {{Name}}Worker extends MegaWorker {
+  static name = '{{name}}'
+  static taskFile = '{{taskFile}}'
+  static mode = 'thread'
+  static poolSize = 2
+}

package/templates/worker/task.tpl

@@ -0,0 +1,13 @@
+// @ts-check
+/**
+ * {{Name}}Worker 의 작업 함수 모듈(= `static taskFile`). named export 한 async 함수를 워커가 로드해
+ * `run(taskName, args)` 의 taskName 으로 디스패치한다(ADR-124). 보일러플레이트 없이 함수만 export.
+ */
+
+/**
+ * @param {{ value?: number }} task - 워커 경계를 넘는 직렬화 가능한 데이터만.
+ * @returns {Promise<object>}
+ */
+export async function {{camelName}}(task) {
+  return { value: task.value, done: true }
+}

package/templates/worker/test.tpl

@@ -0,0 +1,18 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import { MegaWorker } from 'mega-framework'
+import { {{Name}}Worker } from '{{importPath}}'
+import { {{camelName}} } from '{{taskImportPath}}'
+
+describe('{{Name}}Worker', () => {
+  test('MegaWorker 상속 + static taskFile/mode/name', () => {
+    expect(Object.getPrototypeOf({{Name}}Worker)).toBe(MegaWorker)
+    expect({{Name}}Worker.name).toBe('{{name}}')
+    expect({{Name}}Worker.taskFile).toContain('{{name}}.task')
+    expect(['thread', 'process']).toContain({{Name}}Worker.mode)
+  })
+
+  test('task 함수 {{camelName}} — 순수 실행', async () => {
+    expect(await {{camelName}}({ value: 2 })).toEqual({ value: 2, done: true })
+  })
+})

package/vitest.config.js

@@ -0,0 +1,33 @@
+import { defineConfig } from 'vitest/config'
+import { loadEnv } from 'vite'
+
+// ── .env 자동 로드 (ADR-128) ───────────────────────────────────────────
+// 통합 테스트(redis/pg/mongo/nats 등)는 process.env 의 연결 URL 로 docker 실
+// 인프라 가동 여부를 판단해 skip/run 을 결정한다(예: REDIS_CACHE_URL 없으면
+// describe.skip). 하지만 vitest 는 기본적으로 .env 를 process.env 로 주입하지
+// 않아, .env 가 있어도 통합 테스트 63건이 전부 skip 되던 문제가 있었다.
+//   → Vite 내장 loadEnv(mode, cwd, '') 로 .env(+.env.<mode>) 를 읽어 test.env 에
+//     주입한다. 세 번째 인자 '' 는 prefix 필터('VITE_') 를 해제해 모든 키를 노출.
+//   → 새 npm 의존성 0 (loadEnv 는 vite 내장). dotenv 미도입. (P8 불필요)
+// mode 기본값은 'test' (vitest). CI 에서 컨테이너 미기동이면 URL 도 없어 자연히 skip.
+export default defineConfig(({ mode }) => ({
+  test: {
+    env: loadEnv(mode, process.cwd(), ''),
+    include: ['test/**/*.test.js', 'test/**/*.integration.test.js'],
+    exclude: ['test/**/*.e2e.test.js', 'node_modules/**'],
+    coverage: {
+      provider: 'v8',
+      include: ['src/**/*.js'],
+      exclude: [
+        'src/**/*.test.js',
+        // 워커 런타임 진입 스크립트(ADR-124) — worker_threads/child_process **안에서만** 실행돼 부모
+        // 프로세스 v8 커버리지가 측정할 수 없다(별도 isolate/process). 실 동작은 mega-worker E2E 가
+        // 디스패치·결과·crash 로 증명하고, 핵심 로직(task-dispatch.js)은 in-process 단위로 별도 커버.
+        // 두 파일은 import + 리스너 부착 + ready 송신뿐인 얇은 wiring 이라 제외해도 사각 위험 낮음.
+        'src/lib/worker-runner/thread-entry.js',
+        'src/lib/worker-runner/process-entry.js',
+      ],
+      thresholds: { lines: 90, functions: 90, branches: 85, statements: 90 },
+    },
+  },
+}))