mega-framework 0.1.0

package/src/cli/commands/new.js

@@ -0,0 +1,101 @@
+// @ts-check
+/**
+ * `mega new <project>` — 빈 폴더에서 멀티앱 hello world 까지 한 명령 스캐폴드 (roadmap §336, ADR-142).
+ *
+ * 기본 앱 `main` + `*.localhost` 호스트 + README · `.env.example` · `.gitignore` · `package.json`
+ * (scripts + concurrently devDep + PM2 `ecosystem.config.cjs`) 를 만든다. `ejsMate` 옵트인이면 EJS +
+ * ejs-mate 뷰 골격(ADR-011/136) + i18next 다국어(ADR-037~039) + Bootstrap 5 디자인(ADR-151)을 더한다 —
+ * 뷰 렌더 라우트, ko/en 로케일, 그리고 토큰 치환 없이 그대로 복사하는 정적 자산(vendored Bootstrap +
+ * 브랜드 CSS/JS). 신규 dep 설치는 하지 않고(네트워크 회피) 안내만 출력한다.
+ *
+ * @module cli/commands/new
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { nameVariants, renderTemplate } from '../template-engine.js'
+
+/** templates/project 루트. src/cli/commands/new.js 기준 3단계 위 + templates/project. */
+const PROJECT_TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), '../../../templates/project')
+
+/** 프로젝트 템플릿을 읽어 토큰 치환. @param {string} file @param {Record<string,string>} vars @returns {string} */
+function renderProject(file, vars) {
+  return renderTemplate(readFileSync(join(PROJECT_TEMPLATES, file), 'utf8'), vars)
+}
+
+/**
+ * 프로젝트를 스캐폴드한다(순수 — prompts 없이 opts 로만 동작, 테스트 가능).
+ * @param {string} targetDir - 프로젝트 루트 절대/상대 경로.
+ * @param {object} [opts]
+ * @param {string} [opts.name] - 프로젝트 이름(기본: targetDir 의 마지막 세그먼트).
+ * @param {boolean} [opts.ejsMate] - EJS + ejs-mate 뷰 골격 포함(기본 false).
+ * @param {boolean} [opts.force] - 기존 파일 덮어쓰기(기본 false — 건너뜀).
+ * @returns {{ root: string, written: string[], skipped: string[] }}
+ */
+export function scaffoldProject(targetDir, { name, ejsMate = false, force = false } = {}) {
+  const root = resolve(targetDir)
+  const projectName = nameVariants(name ?? root.split(/[/\\]/).pop() ?? 'mega-app').kebab
+  const vars = { name: projectName, Name: nameVariants(projectName).pascal }
+
+  // 뷰 옵트인이면 GET / 를 뷰 렌더로 바꾸고(JSON hello 대신) 그에 맞는 테스트를 쓴다.
+  /** @type {Array<{ rel: string, tpl: string }>} */
+  const files = [
+    { rel: 'mega.config.js', tpl: 'mega.config.tpl' },
+    { rel: 'apps/main/app.config.js', tpl: ejsMate ? 'app.config.views.tpl' : 'app.config.tpl' },
+    { rel: 'apps/main/routes/index.js', tpl: ejsMate ? 'route.views.tpl' : 'route.tpl' },
+    { rel: 'test/apps/main/index.test.js', tpl: ejsMate ? 'route.test.views.tpl' : 'route.test.tpl' },
+    { rel: 'package.json', tpl: 'package.tpl' },
+    { rel: 'README.md', tpl: 'readme.tpl' },
+    { rel: '.env.example', tpl: 'env.tpl' },
+    { rel: '.gitignore', tpl: 'gitignore.tpl' },
+    { rel: 'vitest.config.js', tpl: 'vitest.config.tpl' },
+    { rel: 'ecosystem.config.cjs', tpl: 'ecosystem.config.tpl' },
+  ]
+  if (ejsMate) {
+    files.push(
+      { rel: 'apps/main/views/layouts/main.ejs', tpl: 'views/layout.ejs.tpl' },
+      { rel: 'apps/main/views/index.ejs', tpl: 'views/index.ejs.tpl' },
+      { rel: 'apps/main/locales/server/ko.json', tpl: 'locales/server/ko.json.tpl' },
+      { rel: 'apps/main/locales/server/en.json', tpl: 'locales/server/en.json.tpl' },
+      { rel: 'apps/main/locales/client/ko.json', tpl: 'locales/client/ko.json.tpl' },
+      { rel: 'apps/main/locales/client/en.json', tpl: 'locales/client/en.json.tpl' },
+    )
+  }
+
+  // 정적 자산 — 토큰 치환 없이 바이트 그대로 복사한다(vendored Bootstrap 5 min 번들 + 브랜드 CSS/JS).
+  // 이들은 템플릿이 아니라 정적 파일이므로 renderTemplate(`{{token}}`)을 거치지 않는다.
+  /** @type {Array<{ rel: string, src: string }>} */
+  const assets = ejsMate
+    ? [
+        { rel: 'apps/main/public/vendor/bootstrap/bootstrap.min.css', src: 'public/vendor/bootstrap/bootstrap.min.css' },
+        { rel: 'apps/main/public/vendor/bootstrap/bootstrap.bundle.min.js', src: 'public/vendor/bootstrap/bootstrap.bundle.min.js' },
+        { rel: 'apps/main/public/css/app.css', src: 'public/css/app.css' },
+        { rel: 'apps/main/public/js/app.js', src: 'public/js/app.js' },
+        { rel: 'apps/main/public/js/theme-init.js', src: 'public/js/theme-init.js' },
+      ]
+    : []
+
+  /** @type {string[]} */ const written = []
+  /** @type {string[]} */ const skipped = []
+  for (const { rel, tpl } of files) {
+    const out = join(root, rel)
+    if (existsSync(out) && !force) {
+      skipped.push(out)
+      continue
+    }
+    mkdirSync(dirname(out), { recursive: true })
+    writeFileSync(out, renderProject(tpl, vars))
+    written.push(out)
+  }
+  for (const { rel, src } of assets) {
+    const out = join(root, rel)
+    if (existsSync(out) && !force) {
+      skipped.push(out)
+      continue
+    }
+    mkdirSync(dirname(out), { recursive: true })
+    copyFileSync(join(PROJECT_TEMPLATES, src), out)
+    written.push(out)
+  }
+  return { root, written, skipped }
+}

package/src/cli/commands/routes.js

@@ -0,0 +1,107 @@
+// @ts-check
+/**
+ * `mega routes` — 앱별 등록 라우트 트리 출력 (roadmap §338, ADR-142).
+ *
+ * 서버를 띄우지 않고(부팅·어댑터 connect·listen 없이) 라우트만 수집한다 — 각 `apps/<name>/routes/*.js`
+ * 를 import 해 **기록용 라우터 stub** 으로 `router.http.<method>(path)`/`router.ws(path)` 호출을 잡는다.
+ * (loadRoutes 의 자동 스캔과 동형이되 부작용 없음 — 운영 환경에서도 안전.)
+ *
+ * @module cli/commands/routes
+ */
+import { readdirSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { loadAndValidateConfig } from '../../core/config-loader.js'
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head']
+
+/**
+ * 라우트 등록을 기록하는 라우터 stub.
+ * @param {Array<{ method: string, path: string, file: string }>} sink @param {string} file
+ * @returns {Record<string, any>}
+ */
+function makeRecordingRouter(sink, file) {
+  /** @type {Record<string, any>} */
+  const http = {}
+  for (const m of HTTP_METHODS) {
+    http[m] = (/** @type {string} */ path) => sink.push({ method: m.toUpperCase(), path: String(path), file })
+  }
+  return {
+    http,
+    ws: (/** @type {string} */ path) => sink.push({ method: 'WS', path: String(path), file }),
+    use: () => {}, // 파일 레벨 미들웨어(router.use) — 수집엔 불필요한 no-op.
+    // 실 Router 의 `app` getter 미러(standalone Router 면 null, router.js). 라우트 모듈이 등록 시점에
+    // `router.app` 을 읽어도 undefined 가 아니라 null 이라 옵셔널 가드(`router.app?.x`)가 동형 동작(ADR-167).
+    app: null,
+  }
+}
+
+/**
+ * 프로젝트의 앱별 라우트를 수집한다.
+ * @param {string} projectRoot
+ * @returns {Promise<Array<{ app: string, hosts: string[], routes: Array<{ method: string, path: string, file: string }> }>>}
+ */
+export async function collectRoutes(projectRoot) {
+  const { apps } = await loadAndValidateConfig(projectRoot)
+  /** @type {Array<{ app: string, hosts: string[], routes: any[] }>} */
+  const result = []
+  for (const { name, config } of apps) {
+    const routesDir = join(projectRoot, 'apps', name, 'routes')
+    /** @type {any[]} */
+    const routes = []
+    /** @type {string[]} */
+    let files = []
+    try {
+      files = readdirSync(routesDir)
+        .filter((f) => f.endsWith('.js') && !f.endsWith('.test.js'))
+        .sort()
+    } catch (err) {
+      if (/** @type {any} */ (err).code !== 'ENOENT') throw err
+    }
+    for (const file of files) {
+      const abs = resolve(routesDir, file)
+      // `.js` 로 끝나는 디렉토리 등 비파일은 스킵한다(import 가 디렉토리에 던짐) — loadRoutes 의 statSync
+      // isFile 가드와 동형(routes-loader.js, ADR-167).
+      if (!statSync(abs).isFile()) continue
+      const mod = await import(pathToFileURL(abs).href)
+      if (typeof mod.default !== 'function') continue
+      // async 라우트 모듈(`export default async (router) => {...}`)도 끝까지 기다린다 — await 안 하면
+      // await 경계 뒤 등록 라우트가 수집 전에 누락된다. loadRoutes 도 `await mod.default(router)`(ADR-167).
+      await mod.default(makeRecordingRouter(routes, file))
+    }
+    result.push({ app: name, hosts: /** @type {any} */ (config).hosts ?? [], routes })
+  }
+  return result
+}
+
+/**
+ * 수집한 라우트를 사람이 읽는 트리 문자열로 포맷.
+ * @param {Array<{ app: string, hosts: string[], routes: Array<{ method: string, path: string }> }>} data
+ * @returns {string}
+ */
+export function formatRoutes(data) {
+  /** @type {string[]} */
+  const lines = []
+  for (const { app, hosts, routes } of data) {
+    lines.push(`${app}  [${hosts.join(', ') || 'no hosts'}]`)
+    if (routes.length === 0) {
+      lines.push('  (no routes)')
+      continue
+    }
+    const sorted = [...routes].sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
+    for (const r of sorted) lines.push(`  ${r.method.padEnd(7)} ${r.path}`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * `mega routes` 명령 본체.
+ * @param {string} projectRoot
+ * @param {{ out?: (msg: string) => void }} [deps]
+ * @returns {Promise<number>} exit code.
+ */
+export async function runRoutesCommand(projectRoot, { out = console.log } = {}) {
+  const data = await collectRoutes(projectRoot)
+  out(formatRoutes(data))
+  return 0
+}

package/src/cli/commands/scaffold.js

@@ -0,0 +1,120 @@
+// @ts-check
+/**
+ * scaffold/dev 명령군 (`new` / `generate`(g) / `routes` / `test` / `console`)을 commander 로 묶는다
+ * (ADR-142 — CLI 파서 dep 채택, ADR-123 의 zero-dep 런타임 명령과 공존). 런타임 명령(start/worker/
+ * scheduler/plugin)은 기존 zero-dep 디스패치(`src/cli/index.js`)가 그대로 처리한다.
+ *
+ * @module cli/commands/scaffold
+ */
+import { Command } from 'commander'
+import prompts from 'prompts'
+import { generate, GENERATOR_KINDS } from '../generators/index.js'
+import { scaffoldProject } from './new.js'
+import { runRoutesCommand } from './routes.js'
+import { runTestCommand } from './test-cmd.js'
+import { startConsole } from './console-cmd.js'
+
+/** scaffold/dev 명령 이름(별칭 포함). runCli 가 이 집합으로 라우팅한다. */
+export const SCAFFOLD_COMMANDS = new Set(['new', 'generate', 'g', 'routes', 'test', 'console'])
+
+/**
+ * 생성 결과를 사람이 읽게 출력.
+ * @param {(msg: string) => void} out @param {{ written: string[], skipped: string[] }} r @param {string} root
+ */
+function reportFiles(out, r, root) {
+  for (const f of r.written) out(`  create  ${f.startsWith(root) ? f.slice(root.length + 1) : f}`)
+  for (const f of r.skipped) out(`  skip    ${f.startsWith(root) ? f.slice(root.length + 1) : f} (exists — use --force)`)
+}
+
+/**
+ * scaffold/dev 명령을 실행한다. commander 로 파싱하되 `process.exit` 를 부르지 않고 exit code 를 반환한다
+ * (runCli 계약 정합).
+ * @param {string[]} argv - `process.argv.slice(2)` (첫 토큰 = 명령).
+ * @param {object} deps
+ * @param {(msg: string) => void} deps.out
+ * @param {(msg: string) => void} deps.err
+ * @param {string} deps.projectRoot - 이미 `--root` 해석된 기준 디렉토리.
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [deps.logger]
+ * @returns {Promise<number>} exit code.
+ */
+export async function runScaffoldCommand(argv, { out, err, projectRoot, logger }) {
+  let exitCode = 0
+  const program = new Command()
+  program.name('mega').exitOverride()
+  program.configureOutput({
+    writeOut: (s) => out(s.replace(/\n+$/, '')),
+    writeErr: (s) => err(s.replace(/\n+$/, '')),
+  })
+  // --root 는 runCli 가 이미 해석함 — commander 가 "unknown option" 으로 막지 않도록 받아만 둔다.
+  program.option('--root <dir>', '프로젝트 루트(runCli 가 해석)')
+
+  program
+    .command('new <project>')
+    .description('빈 폴더에서 멀티앱 hello world 스캐폴드')
+    .option('--views', 'EJS + ejs-mate 뷰 골격 포함')
+    .option('--force', '기존 파일 덮어쓰기')
+    .action(async (/** @type {string} */ project, /** @type {any} */ opts) => {
+      // --views 미지정 + 대화형 터미널이면 ejs-mate 옵트인을 묻는다(비-TTY/CI 는 기본 false).
+      let ejsMate = opts.views === true
+      if (opts.views === undefined && process.stdin.isTTY) {
+        const ans = /** @type {any} */ (await prompts({ type: 'confirm', name: 'views', message: 'EJS + ejs-mate 뷰 골격을 포함할까요?', initial: false }))
+        ejsMate = ans.views === true
+      }
+      const target = project === '.' ? projectRoot : `${projectRoot}/${project}`
+      const r = scaffoldProject(target, { name: project === '.' ? undefined : project, ejsMate, force: opts.force === true })
+      out(`mega: scaffolded project at ${r.root}`)
+      reportFiles(out, r, r.root)
+      out('\n다음 단계:\n  cd ' + project + '\n  npm install\n  npm run dev')
+    })
+
+  program
+    .command('generate <kind> <name>')
+    .alias('g')
+    .description(`코드+테스트 생성 (kind: ${GENERATOR_KINDS.join('|')})`)
+    .option('--app <app>', '대상 앱', 'main')
+    .option('--version <v>', '컨트롤러 API 버전(예 v2, ADR-069)')
+    .option('--kind <adapterKind>', 'adapter 종류(db|cache|bus|session|log)')
+    .option('--lng <lng>', 'locale 언어(기본 en)')
+    .option('--force', '기존 파일 덮어쓰기')
+    .action((/** @type {string} */ kind, /** @type {string} */ name, /** @type {any} */ opts) => {
+      const r = generate(kind, name, { app: opts.app, version: opts.version, kind: opts.kind, lng: opts.lng, force: opts.force === true }, projectRoot)
+      out(`mega: generated ${r.kind} '${r.name}'`)
+      reportFiles(out, r, projectRoot)
+      if (r.written.length === 0) exitCode = 1
+    })
+
+  program
+    .command('routes')
+    .description('등록된 라우트 트리 출력')
+    .action(async () => {
+      exitCode = await runRoutesCommand(projectRoot, { out })
+    })
+
+  program
+    .command('test')
+    .description('vitest 실행(추가 인자 그대로 전달)')
+    .allowUnknownOption()
+    .argument('[args...]', 'vitest 인자')
+    .action(async (/** @type {string[]} */ args) => {
+      exitCode = await runTestCommand(projectRoot, args ?? [], { out })
+    })
+
+  program
+    .command('console')
+    .description('앱 컨텍스트를 로딩한 REPL')
+    .action(async () => {
+      await startConsole(projectRoot, { logger, out })
+    })
+
+  try {
+    await program.parseAsync(argv, { from: 'user' })
+    return exitCode
+  } catch (e) {
+    // commander 의 help/version 출력은 정상 종료(exitOverride 가 던지는 특수 코드).
+    const code = /** @type {any} */ (e).exitCode
+    if (/** @type {any} */ (e).code === 'commander.helpDisplayed' || /** @type {any} */ (e).code === 'commander.help') return 0
+    if (typeof code === 'number') return code
+    err(`mega: ${/** @type {any} */ (e).message ?? e}`)
+    return 1
+  }
+}

package/src/cli/commands/test-cmd.js

@@ -0,0 +1,45 @@
+// @ts-check
+/**
+ * `mega test [...args]` — 프로젝트의 vitest 래퍼 (roadmap §338, ADR-142).
+ *
+ * 프로젝트 루트에서 `vitest run` 을 실행하고 추가 인자를 그대로 넘긴다. 별도 테스트 러너 dep 없이
+ * 프로젝트가 설치한 vitest 를 `npx` 로 호출한다(생성 package.json 의 devDependency).
+ *
+ * @module cli/commands/test-cmd
+ */
+import { spawn as nodeSpawn } from 'node:child_process'
+import os from 'node:os'
+
+/**
+ * 자식 프로세스 종료를 exit code 로 환산한다. 정상 종료면 그 code(number)를, **시그널로 죽었으면**
+ * (code=null·signal=문자열) `128+signo`(bash 관례)를 돌려준다 — `code ?? 0` 으로 0(성공)을 돌려주면
+ * 비정상 종료를 통과로 오판하므로 금지(fail-closed, P4, ADR-167).
+ * @param {number|null} code - close 이벤트의 종료 code.
+ * @param {NodeJS.Signals|null} signal - close 이벤트의 종료 시그널.
+ * @returns {number}
+ */
+function exitCodeFromClose(code, signal) {
+  if (typeof code === 'number') return code
+  const signo = signal ? (os.constants.signals[signal] ?? 0) : 0
+  return signo ? 128 + signo : 1
+}
+
+/**
+ * vitest 를 자식 프로세스로 실행한다.
+ * @param {string} projectRoot - 실행 cwd.
+ * @param {string[]} [args] - vitest 에 넘길 추가 인자.
+ * @param {object} [deps]
+ * @param {typeof nodeSpawn} [deps.spawn] - 주입용(테스트).
+ * @param {(msg: string) => void} [deps.out]
+ * @returns {Promise<number>} vitest exit code.
+ */
+export function runTestCommand(projectRoot, args = [], { spawn = nodeSpawn, out = console.log } = {}) {
+  out('mega: running vitest...')
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn('npx', ['vitest', 'run', ...args], { cwd: projectRoot, stdio: 'inherit', shell: false })
+    child.on('error', reject)
+    child.on('close', (/** @type {number|null} */ code, /** @type {NodeJS.Signals|null} */ signal) =>
+      resolvePromise(exitCodeFromClose(code, signal)),
+    )
+  })
+}