mega-framework 0.1.6 → 0.1.8

package/src/cli/commands/scaffold.js

@@ -1,19 +1,27 @@
 // @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`)가 그대로 처리한다.
+ * scaffold/dev 명령군 (`new` / `generate`(g) / `routes` / `test` / `console`)의 commander 등록.
+ *
+ * ADR-142 가 commander 를 채택한 명령군이며, ADR-195(commander 전면 일원화) 이후 런타임 명령
+ * (start/worker/scheduler/migrate)과 **같은 program 트리**에 등록된다 — `registerScaffoldCommands` 를
+ * `cli/index.js` 의 `buildProgram` 이 호출한다. `runScaffoldCommand` 는 scaffold 명령군만 담은 독립
+ * program 을 돌리는 기존 진입점으로 유지한다(하위호환·단위 테스트 경계).
  *
  * @module cli/commands/scaffold
  */
 import { Command } from 'commander'
-import { generate, GENERATOR_KINDS } from '../generators/index.js'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { generate, generateFromScaffoldDef, nextAdrNumber, 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 가 이 집합으로 라우팅한다. */
+/** scaffold/dev 명령 이름(별칭 포함). */
 export const SCAFFOLD_COMMANDS = new Set(['new', 'generate', 'g', 'routes', 'test', 'console'])
 
 /**
@@ -25,28 +33,83 @@ function reportFiles(out, r, root) {
   for (const f of r.skipped) out(`  skip    ${f.startsWith(root) ? f.slice(root.length + 1) : f} (exists — use --force)`)
 }
 
+const execFileAsync = promisify(execFile)
+
 /**
- * scaffold/dev 명령을 실행한다. commander 로 파싱하되 `process.exit` 를 부르지 않고 exit code 를 반환한다
- * (runCli 계약 정합).
- * @param {string[]} argv - `process.argv.slice(2)` (첫 토큰 = 명령).
+ * `g adr` 의 다음 번호를 **원격 포함**으로 해석한다(ADR-218 — 병렬 task 번호 충돌 회피).
+ * `git fetch origin` 후 `origin/main` 의 `docs/adr/` 파일명에서 번호를 모아 로컬 스캔
+ * ({@link nextAdrNumber})과 합산한다 — 형제 task 가 방금 push 한 ADR 이 로컬 작업트리에 없어도
+ * 번호가 건너뛰어진다. git 부재/오프라인/비-repo 는 로컬 스캔만으로 폴백(경고 1줄 — 스캐폴드는
+ * 어디서든 동작해야 하므로 fail 아님).
+ *
+ * @param {string} projectRoot
+ * @param {(msg: string) => void} out
+ * @returns {Promise<number>}
+ */
+async function resolveAdrNumberWithRemote(projectRoot, out) {
+  /** @type {number[]} */
+  const remote = []
+  try {
+    await execFileAsync('git', ['fetch', 'origin', '--quiet'], { cwd: projectRoot })
+    const { stdout } = await execFileAsync('git', ['ls-tree', '--name-only', 'origin/main', 'docs/adr/'], { cwd: projectRoot })
+    for (const line of stdout.split('\n')) {
+      const m = line.match(/(\d{1,4})-[^/]+\.md$/)
+      if (m) remote.push(Number(m[1]))
+    }
+  } catch (err) {
+    // 오프라인/비-repo/origin 부재 — 로컬 스캔만으로 진행하되 충돌 가능성을 알린다(silent 금지).
+    out(`mega: 원격 ADR 번호 확인 실패(${/** @type {any} */ (err).message?.split('\n')[0] ?? err}) — 로컬 기준으로 번호를 할당합니다.`)
+  }
+  return nextAdrNumber(projectRoot, remote)
+}
+
+/**
+ * `g model --adapter <key>` 의 adapter 키/driver 해석 — mega.config.js 의 services.databases 를
+ * best-effort 로 읽는다(스캐폴드는 config 가 아직 없는 초기 프로젝트에서도 돌아야 하므로 로드
+ * 실패는 fail 이 아니라 기본값 + 경고 1줄). 키 미지정 시: 선언 db 가 1개면 그 키, 아니면 'primary'.
+ *
+ * @param {string} projectRoot @param {string | undefined} explicitKey
+ * @param {(msg: string) => void} out
+ * @returns {Promise<{ key: string, driver: string | undefined }>}
+ */
+async function resolveModelAdapter(projectRoot, explicitKey, out) {
+  /** @type {Record<string, any>} */
+  let databases = {}
+  const configPath = join(projectRoot, 'mega.config.js')
+  if (existsSync(configPath)) {
+    try {
+      const mod = await import(pathToFileURL(configPath).href)
+      databases = mod.default?.services?.databases ?? {}
+    } catch (err) {
+      // config 문법 오류 등 — 스캐폴드는 계속 가능해야 하므로 기본 템플릿으로 폴백하되 명시 안내(P4).
+      out(`mega: mega.config.js 를 읽지 못해 adapter driver 를 해석하지 못했습니다(${/** @type {any} */ (err).message}) — SQL 템플릿으로 생성합니다.`)
+    }
+  }
+  const keys = Object.keys(databases)
+  const key = explicitKey ?? (keys.length === 1 ? keys[0] : 'primary')
+  if (explicitKey !== undefined && keys.length > 0 && !keys.includes(explicitKey)) {
+    out(`mega: --adapter '${explicitKey}' 가 services.databases 에 없습니다(선언: [${keys.join(', ')}]) — 키를 그대로 쓰고 SQL 템플릿으로 생성합니다.`)
+  }
+  return { key, driver: databases[key]?.driver }
+}
+
+/**
+ * scaffold/dev 명령 5종을 commander program 에 등록한다 — 명령 정의의 단일 정본(ADR-195).
+ * action 은 `process.exit` 를 부르지 않고 `setExit(code)` 로 종료 코드를 보고한다(runCli 계약).
+ *
+ * @param {import('commander').Command} program - 등록 대상 program.
  * @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.
+ * @param {(kind: string) => Promise<{ dir: string, files: Array<{ path: string, template: string }> } | undefined>} [deps.resolvePluginGenerator] -
+ *   빌트인이 아닌 kind 의 플러그인 scaffold manifest 조회(`mega.scaffold.register`, 03-api-spec §11).
+ *   호출측(runCli)이 config 로드 + 플러그인 install 을 감싼 함수를 주입한다 — 본 모듈이 cli/index.js 를
+ *   import 하면 순환이라 주입식으로 푼다. 미주입/미발견이면 unknown kind 에러.
+ * @param {(code: number) => void} deps.setExit - 명령 종료 코드 보고 콜백.
+ * @returns {void}
  */
-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 가 해석)')
-
+export function registerScaffoldCommands(program, { out, projectRoot, logger, resolvePluginGenerator, setExit }) {
   program
     .command('new <project>')
     .description('sample/crud 데모앱(14기능) 전체를 빈 폴더에 스캐폴드')
@@ -64,24 +127,58 @@ export async function runScaffoldCommand(argv, { out, err, projectRoot, logger }
   program
     .command('generate <kind> <name>')
     .alias('g')
-    .description(`코드+테스트 생성 (kind: ${GENERATOR_KINDS.join('|')})`)
+    .description(`코드+테스트 생성 (kind: ${GENERATOR_KINDS.join('|')} 또는 플러그인 등록 generator)`)
     .option('--app <app>', '대상 앱', 'main')
     .option('--version <v>', '컨트롤러 API 버전(예 v2, ADR-069)')
     .option('--kind <adapterKind>', 'adapter 종류(db|cache|bus|session|log)')
+    .option('--adapter <key>', 'model 전용 — services.databases 키(driver 가 mongodb 면 mongo 템플릿, 기본: 유일 선언 db 또는 primary)')
     .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)
+    .action(async (/** @type {string} */ kind, /** @type {string} */ name, /** @type {any} */ opts) => {
+      /** @type {{ kind: string, name: string, written: string[], skipped: string[] }} */
+      let r
+      if (GENERATOR_KINDS.includes(/** @type {any} */ (kind))) {
+        /** @type {{ key: string, driver: string | undefined }} */
+        let modelAdapter = { key: 'primary', driver: undefined }
+        if (kind === 'model') modelAdapter = await resolveModelAdapter(projectRoot, opts.adapter, out)
+        // adr 은 번호를 원격 포함으로 해석한다(병렬 task 충돌 회피, ADR-218).
+        /** @type {number | undefined} */
+        let adrNumber
+        if (kind === 'adr') adrNumber = await resolveAdrNumberWithRemote(projectRoot, out)
+        r = generate(
+          kind,
+          name,
+          { app: opts.app, version: opts.version, kind: opts.kind, lng: opts.lng, force: opts.force === true, adapter: modelAdapter.key, adapterDriver: modelAdapter.driver, adrNumber },
+          projectRoot,
+        )
+      } else {
+        // 빌트인이 아니면 플러그인 등록 generator(manifest) 조회(03-api-spec §11 `mega g <name>` 계약).
+        // config 로드 실패(프로젝트 밖 등)는 unknown kind 메시지에 원인을 병기해 오도 없이 보고한다.
+        /** @type {{ dir: string, files: Array<{ path: string, template: string }> } | undefined} */
+        let def
+        try {
+          def = await resolvePluginGenerator?.(kind)
+        } catch (e) {
+          throw new Error(
+            `Unknown generator '${kind}'. Supported: ${GENERATOR_KINDS.join(', ')}. ` +
+              `(플러그인 generator 확인 실패: ${/** @type {any} */ (e).message ?? e})`,
+          )
+        }
+        if (def === undefined) {
+          throw new Error(`Unknown generator '${kind}'. Supported: ${GENERATOR_KINDS.join(', ')} (또는 플러그인 등록 generator).`)
+        }
+        r = generateFromScaffoldDef(kind, def, name, { app: opts.app, force: opts.force === true }, projectRoot)
+      }
       out(`mega: generated ${r.kind} '${r.name}'`)
       reportFiles(out, r, projectRoot)
-      if (r.written.length === 0) exitCode = 1
+      if (r.written.length === 0) setExit(1)
     })
 
   program
     .command('routes')
     .description('등록된 라우트 트리 출력')
     .action(async () => {
-      exitCode = await runRoutesCommand(projectRoot, { out })
+      setExit(await runRoutesCommand(projectRoot, { out }))
     })
 
   program
@@ -90,7 +187,7 @@ export async function runScaffoldCommand(argv, { out, err, projectRoot, logger }
     .allowUnknownOption()
     .argument('[args...]', 'vitest 인자')
     .action(async (/** @type {string[]} */ args) => {
-      exitCode = await runTestCommand(projectRoot, args ?? [], { out })
+      setExit(await runTestCommand(projectRoot, args ?? [], { out }))
     })
 
   program
@@ -99,16 +196,59 @@ export async function runScaffoldCommand(argv, { out, err, projectRoot, logger }
     .action(async () => {
       await startConsole(projectRoot, { logger, out })
     })
+}
+
+/**
+ * commander 의 exitOverride 예외를 exit code 로 환산한다 — help/version 출력은 정상 종료(0),
+ * CommanderError 는 자체 exitCode, 그 외 에러는 메시지 출력 후 1. commander 가 아닌 에러를 그대로
+ * 삼키지 않도록 `rethrowUnknown` 옵션을 둔다(runCli 가 부팅·config 에러를 bin 으로 전파할 때 사용).
+ *
+ * @param {unknown} e - parseAsync 가 던진 예외.
+ * @param {(msg: string) => void} err
+ * @param {{ rethrowUnknown?: boolean }} [opts] - true 면 CommanderError 가 아닌 예외를 재throw.
+ * @returns {number} exit code.
+ */
+export function commanderErrorToExitCode(e, err, { rethrowUnknown = false } = {}) {
+  const anyErr = /** @type {any} */ (e)
+  if (typeof anyErr?.code === 'string' && anyErr.code.startsWith('commander.')) {
+    // help/version 출력은 정상 종료(exitOverride 가 던지는 특수 코드).
+    if (anyErr.code === 'commander.helpDisplayed' || anyErr.code === 'commander.help' || anyErr.code === 'commander.version') return 0
+    return typeof anyErr.exitCode === 'number' ? anyErr.exitCode : 1
+  }
+  if (rethrowUnknown) throw e
+  err(`mega: ${anyErr?.message ?? e}`)
+  return 1
+}
+
+/**
+ * scaffold/dev 명령만 담은 독립 program 으로 실행한다(하위호환 진입점 — 단위 테스트 경계 유지).
+ * 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]
+ * @param {(kind: string) => Promise<{ dir: string, files: Array<{ path: string, template: string }> } | undefined>} [deps.resolvePluginGenerator]
+ * @returns {Promise<number>} exit code.
+ */
+export async function runScaffoldCommand(argv, { out, err, projectRoot, logger, resolvePluginGenerator }) {
+  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>', '프로젝트 루트(호출측이 해석)')
+  registerScaffoldCommands(program, { out, projectRoot, logger, resolvePluginGenerator, setExit: (c) => (exitCode = c) })
 
   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
+    return commanderErrorToExitCode(e, err)
   }
 }

package/src/cli/generators/index.js

@@ -13,7 +13,7 @@
  *
  * @module cli/generators
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { nameVariants, renderTemplate } from '../template-engine.js'
@@ -36,8 +36,23 @@ export const GENERATOR_KINDS = /** @type {const} */ ([
   'locale',
   'adapter',
   'migration',
+  'adr',
 ])
 
+/**
+ * 플러그인 scaffold manifest 의 토큰 계약(ADR-199) — `files[].path`/`files[].template` 의 `{{token}}`
+ * 에 쓸 수 있는 이름과 의미. 빌트인 generator 의 base 토큰과 동일 집합이라 템플릿 작성 관례가 하나다.
+ * 미정의 토큰은 renderTemplate 가 throw 한다(P4 — silent 치환 누락 방지).
+ * @type {Readonly<Record<string, string>>}
+ */
+export const SCAFFOLD_TOKENS = Object.freeze({
+  Name: 'PascalCase 이름 (예: userCard → UserCard)',
+  name: 'kebab-case 이름 (user-card)',
+  camelName: 'camelCase 이름 (userCard)',
+  snake: 'snake_case 이름 (user_card)',
+  app: '대상 앱 이름 (--app, 기본 main)',
+})
+
 /** adapter `--kind` → 베이스 클래스(mega-framework export 명). */
 const ADAPTER_BASES = /** @type {Record<string, string>} */ ({
   db: 'MegaDbAdapter',
@@ -121,8 +136,19 @@ export function planArtifacts(kind, rawName, opts, projectRoot) {
   }
 
   switch (kind) {
-    case 'model':
-      return pair({ codeRel: `apps/${app}/models/${v.kebab}.js`, vars: { table: v.snake } })
+    case 'model': {
+      // --adapter <key>: services.databases 키(static adapter 값). driver 가 mongodb 로 해석되면
+      // mongo 변형 템플릿(_id 자동·도큐먼트 API — ADR-209)을 쓴다. 해석은 scaffold 명령이
+      // best-effort 로 수행해 opts.adapterDriver 로 전달한다(config 부재 시 SQL 템플릿 기본).
+      const adapter = typeof opts.adapter === 'string' && opts.adapter.length > 0 ? opts.adapter : 'primary'
+      const isMongo = opts.adapterDriver === 'mongodb'
+      return pair({
+        codeRel: `apps/${app}/models/${v.kebab}.js`,
+        vars: { table: v.snake, adapter },
+        codeTpl: isMongo ? 'code-mongo.tpl' : 'code.tpl',
+        testTpl: isMongo ? 'test-mongo.tpl' : 'test.tpl',
+      })
+    }
 
     case 'service':
       return pair({ codeRel: `apps/${app}/services/${v.kebab}-service.js`, vars: {} })
@@ -160,11 +186,67 @@ export function planArtifacts(kind, rawName, opts, projectRoot) {
     case 'app':
       return planApp(v, projectRoot, base)
 
+    case 'adr':
+      return planAdr(v, opts, projectRoot)
+
     default:
       throw new Error(`Unknown generator kind '${kind}'. Supported: ${GENERATOR_KINDS.join(', ')}.`)
   }
 }
 
+/**
+ * 다음 ADR 번호를 해석한다 — `docs/adr/NNNN-*.md` 파일명 + 레거시 `docs/09` 헤딩(`### ADR-N:`) +
+ * 호출측이 모은 추가 번호(예: `git ls-tree origin/main` 의 원격 파일 — 병렬 task 충돌 회피)의
+ * 최댓값 + 1. 아무 ADR 도 없으면 1.
+ *
+ * @param {string} projectRoot
+ * @param {number[]} [extraNumbers] - 로컬 밖에서 관측한 번호(원격 스캔 등).
+ * @returns {number}
+ */
+export function nextAdrNumber(projectRoot, extraNumbers = []) {
+  let max = 0
+  const adrDir = join(projectRoot, 'docs/adr')
+  if (existsSync(adrDir)) {
+    for (const f of readdirSync(adrDir)) {
+      const m = f.match(/^(\d{1,4})-.+\.md$/)
+      if (m) max = Math.max(max, Number(m[1]))
+    }
+  }
+  const legacy = join(projectRoot, 'docs/09-decisions-and-open-questions.md')
+  if (existsSync(legacy)) {
+    for (const m of readFileSync(legacy, 'utf8').matchAll(/^### ADR-(\d+)/gm)) {
+      max = Math.max(max, Number(m[1]))
+    }
+  }
+  for (const n of extraNumbers) {
+    if (Number.isInteger(n)) max = Math.max(max, n)
+  }
+  return max + 1
+}
+
+/** adr — `docs/adr/NNNN-<name>.md` 1개(코드/테스트 쌍 아님 — 프로젝트 결정 기록 문서, ADR-218).
+ * 번호는 opts.adrNumber(호출측이 원격 포함 해석) 우선, 미지정 시 로컬 스캔({@link nextAdrNumber}).
+ * @param {Variants} v @param {Record<string, any>} opts @param {string} projectRoot
+ * @returns {Artifact[]} */
+function planAdr(v, opts, projectRoot) {
+  const number = Number.isInteger(opts.adrNumber) && opts.adrNumber > 0 ? opts.adrNumber : nextAdrNumber(projectRoot)
+  const padded = String(number).padStart(4, '0')
+  const d = new Date()
+  const p = (/** @type {number} */ n) => String(n).padStart(2, '0')
+  const vars = {
+    number: String(number),
+    title: v.words.join(' '),
+    date: `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`,
+  }
+  return [
+    {
+      outAbs: join(projectRoot, `docs/adr/${padded}-${v.kebab}.md`),
+      role: 'code',
+      content: renderTemplate(readTpl('adr', 'code.tpl'), vars),
+    },
+  ]
+}
+
 /**
  * @typedef {{ kebab: string, pascal: string, camel: string, snake: string, words: string[] }} Variants
  * @typedef {Record<string, string>} BaseVars
@@ -347,6 +429,61 @@ export function writeArtifacts(artifacts, { force = false } = {}) {
   return { written, skipped }
 }
 
+/**
+ * 플러그인 scaffold manifest(`mega.scaffold.register(name, { dir, files, description? })`,
+ * 03-api-spec §11 / ADR-199)를 artifact 목록으로 계획한다 — 빌트인 13종과 같은 plan→write 2단 분리.
+ * 토큰 계약은 {@link SCAFFOLD_TOKENS} 가 정본이며 미정의 토큰은 renderTemplate 가 throw(P4).
+ * `files[].path` 에도 토큰을 쓸 수 있다(예 `services/{{name}}-service.js`).
+ *
+ * @param {{ dir: string, files: Array<{ path: string, template: string }> }} def - 플러그인 등록 정의.
+ * @param {string} rawName - `mega g <kind> <name>` 의 name.
+ * @param {Record<string, any>} opts - { app }.
+ * @param {string} projectRoot - 출력 기준 루트. `def.dir` 는 이 루트 상대.
+ * @returns {Artifact[]}
+ * @throws {Error} def 파일 항목이 `{ path, template }` 문자열 쌍이 아니거나, 출력 경로가 projectRoot 를
+ *   벗어나면(경로 탐색 차단 — template.js resolveViewPath 정합) fail-fast.
+ */
+export function planScaffoldDef(def, rawName, opts, projectRoot) {
+  const app = typeof opts.app === 'string' && opts.app.length > 0 ? opts.app : 'main'
+  const v = nameVariants(rawName)
+  const vars = { Name: v.pascal, name: v.kebab, camelName: v.camel, snake: v.snake, app }
+  const rootAbs = resolve(projectRoot)
+  const baseDir = resolve(rootAbs, def.dir)
+  /** @type {Artifact[]} */
+  const out = []
+  for (const file of def.files) {
+    if (!file || typeof file.path !== 'string' || file.path.length === 0 || typeof file.template !== 'string') {
+      throw new Error(`scaffold def: files entries must be { path: string, template: string }. Got ${JSON.stringify(file)}.`)
+    }
+    const outAbs = resolve(baseDir, renderTemplate(file.path, vars))
+    // 출력은 projectRoot 내부로 제한 — def.dir/path 의 `..` 가 프로젝트 밖에 쓰는 걸 차단.
+    if (outAbs !== rootAbs && !outAbs.startsWith(rootAbs + sep)) {
+      throw new Error(`scaffold def: output '${file.path}' escapes the project root (path traversal blocked).`)
+    }
+    out.push({ outAbs, role: 'code', content: renderTemplate(file.template, vars) })
+  }
+  return out
+}
+
+/**
+ * 플러그인 등록 scaffold generator 실행 — `mega g <plugin-generator> <name>` 의 본체. 빌트인 `generate`
+ * 와 같은 계획 → 쓰기 → 결과 계약(존재 파일 skip, `--force` 덮어쓰기).
+ * @param {string} kindName - 플러그인이 등록한 generator 이름(결과 보고용).
+ * @param {{ dir: string, files: Array<{ path: string, template: string }> }} def
+ * @param {string} rawName
+ * @param {object} [opts] - { app, force }
+ * @param {string} [projectRoot]
+ * @returns {{ kind: string, name: string, written: string[], skipped: string[] }}
+ */
+export function generateFromScaffoldDef(kindName, def, rawName, opts = {}, projectRoot = process.cwd()) {
+  if (typeof rawName !== 'string' || rawName.trim().length === 0) {
+    throw new Error(`mega g ${kindName}: a name is required (e.g. 'mega g ${kindName} users').`)
+  }
+  const artifacts = planScaffoldDef(def, rawName, /** @type {any} */ (opts), projectRoot)
+  const { written, skipped } = writeArtifacts(artifacts, { force: /** @type {any} */ (opts).force === true })
+  return { kind: kindName, name: rawName, written, skipped }
+}
+
 /**
  * `mega g <kind> <name>` 실행 — 계획 → 쓰기 → 결과 반환.
  * @param {string} kind