mega-framework 0.1.6 → 0.1.7

package/src/adapters/maria-adapter.js

@@ -73,9 +73,9 @@
  * @module adapters/maria-adapter
  */
 import { AsyncLocalStorage } from 'node:async_hooks'
-import { MegaValidationError } from '../errors/http-errors.js'
+import { MegaInternalError, MegaValidationError } from '../errors/http-errors.js'
 import { MegaDbAdapter } from './mega-db-adapter.js'
-import { resolveConnection, normalizePool, assertPlainObject, MARIA_POOL_SPEC } from './adapter-options.js'
+import { resolveConnection, normalizePool, assertPlainObject, resolveTxIsolation, MARIA_POOL_SPEC } from './adapter-options.js'
 import * as Registry from './registry.js'
 
 /**
@@ -165,6 +165,11 @@ function resolveBigIntStrategy(options) {
 }
 
 export class MegaMariaAdapter extends MegaDbAdapter {
+  /** driver 식별자 — dialect 디스패치(getDialect)·CRUD 의 단일 출처(ADR-212). @returns {'mariadb'} */
+  get driver() {
+    return 'mariadb'
+  }
+
   /** @type {import('mariadb').Pool | null} 연결된 Pool 인스턴스 (connect 후에만). */
   #pool = null
   /** @type {Record<string, unknown>} _connect 의 `createPool()` 인자 (url 도 discrete 로 파싱해 항상 객체, ADR-109). */
@@ -318,23 +323,41 @@ export class MegaMariaAdapter extends MegaDbAdapter {
    * RELEASE SAVEPOINT) 후 반환값을 그대로 돌려주고, throw 시 rollback(또는 ROLLBACK TO SAVEPOINT)
    * 후 원본 에러 re-throw.
    *
+   * `opts.isolation`(ADR-190) — top-level 이면 `beginTransaction()` **직전에** 같은 연결에서
+   * `SET TRANSACTION ISOLATION LEVEL` 을 실행한다(MariaDB 의 `SET TRANSACTION` 은 같은 세션의
+   * **다음** 트랜잭션 1회에만 적용 — 공식 문서). 격리수준은 트랜잭션 시작 시 고정되므로
+   * nested(SAVEPOINT) 호출에 지정하면 `adapter.nested_isolation_unsupported` 로 거부한다.
+   *
    * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
    *
    * @template T
    * @param {(conn: import('mariadb').PoolConnection) => Promise<T> | T} fn
+   * @param {{ isolation?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable' }} [opts] - 트랜잭션 옵션(ADR-190).
    * @returns {Promise<T>}
+   * @throws {MegaInternalError} `adapter.nested_isolation_unsupported` - nested 호출에 isolation 지정.
    */
-  async withTransaction(fn) {
+  async withTransaction(fn, opts) {
+    // 옵션 검증은 연결 상태와 무관한 설정 오류라 _instrument(상태 검증) 전에 fail-fast 한다.
+    const isolationSql = resolveTxIsolation(opts?.isolation, 'mariadb')
     return this._instrument('withTransaction', { table: undefined }, async () => {
       const existing = this.#txContext.getStore()
       // nested — 진행 중 트랜잭션이 있으면 같은 연결에 SAVEPOINT 를 건다(Sqlite 와 분기).
       if (existing !== undefined) {
+        if (isolationSql !== undefined) {
+          throw new MegaInternalError(
+            'adapter.nested_isolation_unsupported',
+            `${this.constructor.name}.withTransaction() cannot set an isolation level on a nested (SAVEPOINT) transaction — isolation is fixed when the top-level transaction starts (ADR-190).`,
+            { details: { adapter: this.constructor.name, isolation: opts?.isolation } },
+          )
+        }
         return this.#runSavepoint(existing, fn)
       }
       // top-level — 풀에서 연결 1개 획득 후 beginTransaction/commit/rollback.
       const pool = /** @type {import('mariadb').Pool} */ (this.#pool)
       const conn = await pool.getConnection()
       try {
+        // SET TRANSACTION 은 다음 트랜잭션 1회에만 적용 — 반드시 beginTransaction 직전, 같은 연결에서.
+        if (isolationSql !== undefined) await conn.query(`SET TRANSACTION ISOLATION LEVEL ${isolationSql}`)
         await conn.beginTransaction()
         let result
         try {

package/src/adapters/mega-db-adapter.js

@@ -30,11 +30,17 @@ export class MegaDbAdapter extends MegaAdapter {
    * driver 별 구현 (postgres `BEGIN/COMMIT/ROLLBACK`, MongoDB `session.withTransaction`).
    * nested 호출은 driver 별 (postgres SAVEPOINT, MongoDB throw `adapter.nested_transaction_unsupported`).
    *
+   * `opts.isolation`(ADR-190) — SQL 격리수준 옵트인. 미지정이면 driver 디폴트. driver 별 지원:
+   * postgres/maria 는 top-level 트랜잭션에 `SET TRANSACTION ISOLATION LEVEL` 로 반영(nested 엔 불가 —
+   * `adapter.nested_isolation_unsupported`), sqlite 는 항상 SERIALIZABLE 동작이라 'serializable' 만 수용,
+   * mongodb 는 SQL 격리수준 개념이 없어 지정 시 `adapter.invalid_option`.
+   *
    * @template T
    * @param {(db: any) => Promise<T>} _fn - 트랜잭션 컨텍스트의 `db` 를 받는 콜백.
+   * @param {{ isolation?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable' }} [_opts] - 트랜잭션 옵션(ADR-190).
    * @returns {Promise<T>}
    */
-  async withTransaction(_fn) {
+  async withTransaction(_fn, _opts) {
     return this._notImplemented('withTransaction')
   }
 

package/src/adapters/mongo-adapter.js

@@ -140,6 +140,11 @@ function buildMongoUri({ host, port, user, password }) {
  */
 
 export class MegaMongoAdapter extends MegaDbAdapter {
+  /** driver 식별자 — dialect 디스패치·CRUD 의 단일 출처(ADR-212). mongo 는 SQL CRUD 미지원(P3). @returns {'mongodb'} */
+  get driver() {
+    return 'mongodb'
+  }
+
   /** @type {import('mongodb').MongoClient | null} 연결된 MongoClient (connect 후에만). */
   #client = null
   /** @type {import('mongodb').Db | null} 선택된 Db 인스턴스 (connect 후에만). */
@@ -320,14 +325,27 @@ export class MegaMongoAdapter extends MegaDbAdapter {
    * throw 시 abort 후 원본 에러를 re-throw 한다. nested 호출은 ALS 로 감지해 거부(Sqlite 와 동일).
    * `session.endSession()` 은 `finally` 에서 반드시 호출(leak 방지).
    *
+   * `opts.isolation`(ADR-190) — MongoDB 트랜잭션에는 SQL 격리수준 개념이 없다(snapshot 의미는 driver/
+   * readConcern 관할). 지정 시 `adapter.invalid_option` 으로 명시 거부한다(조용히 무시 X — P4).
+   *
    * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
    *
    * @template T
    * @param {(db: import('mongodb').Db, session: import('mongodb').ClientSession) => Promise<T> | T} fn
+   * @param {{ isolation?: never }} [opts] - 트랜잭션 옵션(ADR-190) — mongodb 는 isolation 미지원.
    * @returns {Promise<T>}
    * @throws {MegaInternalError} `adapter.nested_transaction_unsupported` - 이미 트랜잭션 진행 중.
+   * @throws {MegaValidationError} `adapter.invalid_option` - isolation 지정(미지원).
    */
-  async withTransaction(fn) {
+  async withTransaction(fn, opts) {
+    // 옵션 검증은 연결 상태와 무관한 설정 오류라 _instrument(상태 검증) 전에 fail-fast 한다.
+    if (opts?.isolation !== undefined) {
+      throw new MegaValidationError(
+        'adapter.invalid_option',
+        'mongodb: SQL isolation levels do not apply to MongoDB transactions — remove the "isolation" option (snapshot semantics are managed by the driver/readConcern).',
+        { details: { driver: 'mongodb', option: 'isolation', value: opts.isolation } },
+      )
+    }
     return this._instrument('withTransaction', { table: undefined }, async () => {
       // nested 거부 — 진행 중 트랜잭션이 있으면 즉시 throw (Sqlite 와 동일 정책·에러 코드, ADR-108).
       // 검사를 driver 호출 전에 두어, standalone(트랜잭션 미지원)에서도 nested 거부는 동작한다.

package/src/adapters/postgres-adapter.js

@@ -67,8 +67,9 @@
  * @module adapters/postgres-adapter
  */
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { MegaInternalError } from '../errors/http-errors.js'
 import { MegaDbAdapter } from './mega-db-adapter.js'
-import { resolveConnection, normalizePool, assertPlainObject, PG_POOL_SPEC } from './adapter-options.js'
+import { resolveConnection, normalizePool, assertPlainObject, resolveTxIsolation, PG_POOL_SPEC } from './adapter-options.js'
 import * as Registry from './registry.js'
 
 /**
@@ -89,6 +90,11 @@ import * as Registry from './registry.js'
  */
 
 export class MegaPostgresAdapter extends MegaDbAdapter {
+  /** driver 식별자 — dialect 디스패치(getDialect)·CRUD 의 단일 출처(ADR-212). @returns {'postgres'} */
+  get driver() {
+    return 'postgres'
+  }
+
   /** @type {import('pg').Pool | null} 연결된 Pool 인스턴스 (connect 후에만). */
   #pool = null
   /** @type {import('pg').PoolConfig} _connect 에서 `new Pool()` 에 넘길 설정 (생성자에서 구성·고정). */
@@ -234,17 +240,32 @@ export class MegaPostgresAdapter extends MegaDbAdapter {
    * RELEASE SAVEPOINT) 후 `fn` 반환값을 그대로 돌려주고, throw 시 ROLLBACK(또는 ROLLBACK TO
    * SAVEPOINT) 후 원본 에러를 re-throw 한다.
    *
+   * `opts.isolation`(ADR-190) — top-level 이면 `BEGIN` 직후 `SET TRANSACTION ISOLATION LEVEL` 로
+   * 반영한다(PostgreSQL 은 트랜잭션 첫 쿼리 전이라 유효). 격리수준은 트랜잭션 시작 시 고정되므로
+   * nested(SAVEPOINT) 호출에 지정하면 `adapter.nested_isolation_unsupported` 로 거부한다.
+   *
    * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
    *
    * @template T
    * @param {(client: import('pg').PoolClient) => Promise<T> | T} fn
+   * @param {{ isolation?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable' }} [opts] - 트랜잭션 옵션(ADR-190).
    * @returns {Promise<T>}
+   * @throws {MegaInternalError} `adapter.nested_isolation_unsupported` - nested 호출에 isolation 지정.
    */
-  async withTransaction(fn) {
+  async withTransaction(fn, opts) {
+    // 옵션 검증은 연결 상태와 무관한 설정 오류라 _instrument(상태 검증) 전에 fail-fast 한다.
+    const isolationSql = resolveTxIsolation(opts?.isolation, 'postgres')
     return this._instrument('withTransaction', { table: undefined }, async () => {
       const existing = this.#txContext.getStore()
       // nested — 진행 중 트랜잭션이 있으면 같은 클라이언트에 SAVEPOINT 를 건다(Sqlite 와 분기).
       if (existing !== undefined) {
+        if (isolationSql !== undefined) {
+          throw new MegaInternalError(
+            'adapter.nested_isolation_unsupported',
+            `${this.constructor.name}.withTransaction() cannot set an isolation level on a nested (SAVEPOINT) transaction — isolation is fixed when the top-level transaction starts (ADR-190).`,
+            { details: { adapter: this.constructor.name, isolation: opts?.isolation } },
+          )
+        }
         return this.#runSavepoint(existing, fn)
       }
       // top-level — 풀에서 클라이언트 1개 획득 후 BEGIN/COMMIT/ROLLBACK.
@@ -252,6 +273,8 @@ export class MegaPostgresAdapter extends MegaDbAdapter {
       const client = await pool.connect()
       try {
         await client.query('BEGIN')
+        // 격리수준은 트랜잭션 첫 쿼리 전에만 설정 가능 — BEGIN 직후 반영(화이트리스트 SQL 조각이라 안전).
+        if (isolationSql !== undefined) await client.query(`SET TRANSACTION ISOLATION LEVEL ${isolationSql}`)
         let result
         try {
           result = await this.#txContext.run({ client, depth: 0 }, () => fn(client))

package/src/adapters/sqlite-adapter.js

@@ -65,6 +65,11 @@ import * as Registry from './registry.js'
  */
 
 export class MegaSqliteAdapter extends MegaDbAdapter {
+  /** driver 식별자 — dialect 디스패치(getDialect)·CRUD 의 단일 출처(ADR-212). @returns {'sqlite'} */
+  get driver() {
+    return 'sqlite'
+  }
+
   /** @type {import('better-sqlite3').Database | null} 연결된 Database 인스턴스 (connect 후에만). */
   #db = null
   /** @type {string} DB 파일 경로 또는 ':memory:'. */
@@ -237,14 +242,28 @@ export class MegaSqliteAdapter extends MegaDbAdapter {
    * 성공 시 COMMIT 후 `fn` 반환값을 그대로 돌려주고, `fn` 이 throw 하면 ROLLBACK 후 원본 에러를
    * re-throw 한다. nested / 동시 호출은 `db.inTransaction` 으로 감지해 거부(ADR-105).
    *
+   * `opts.isolation`(ADR-190) — SQLite 트랜잭션은 항상 SERIALIZABLE 동작(단일 writer, 공식 문서)이라
+   * `'serializable'` 만 수용(no-op)하고 다른 값은 `adapter.invalid_option` 으로 명시 거부한다
+   * (조용히 무시하면 사용자가 다른 격리수준이 적용된 줄 오인 — P4).
+   *
    * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
    *
    * @template T
    * @param {(db: import('better-sqlite3').Database) => Promise<T> | T} fn
+   * @param {{ isolation?: 'serializable' }} [opts] - 트랜잭션 옵션(ADR-190).
    * @returns {Promise<T>}
    * @throws {MegaInternalError} `adapter.nested_transaction_unsupported` - 이미 트랜잭션 진행 중.
+   * @throws {MegaValidationError} `adapter.invalid_option` - 'serializable' 외 isolation 값.
    */
-  async withTransaction(fn) {
+  async withTransaction(fn, opts) {
+    // 옵션 검증은 연결 상태와 무관한 설정 오류라 _instrument(상태 검증) 전에 fail-fast 한다.
+    if (opts?.isolation !== undefined && opts.isolation !== 'serializable') {
+      throw new MegaValidationError(
+        'adapter.invalid_option',
+        `sqlite transactions are always SERIALIZABLE — withTransaction "isolation" accepts only 'serializable'. Got ${JSON.stringify(opts.isolation)}.`,
+        { details: { driver: 'sqlite', option: 'isolation', value: opts.isolation } },
+      )
+    }
     return this._instrument('withTransaction', { table: undefined }, async () => {
       const db = /** @type {import('better-sqlite3').Database} */ (this.#db)
       if (db.inTransaction) {

package/src/cli/commands/new.js

@@ -15,6 +15,7 @@
  * @module cli/commands/new
  */
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
 import { dirname, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { nameVariants } from '../template-engine.js'
@@ -76,10 +77,11 @@ function walk(dir, base, acc) {
 }
 
 /**
- * 토큰 치환 — `sample-crud` 를 프로젝트명으로, package.json 의 모노레포 dep(`file:../..`)을 실제 버전으로.
+ * 토큰 치환 — `sample-crud` 를 프로젝트명으로, package.json 의 모노레포 dep(`file:../..`)을 실제 버전으로,
+ * `.env` 의 SESSION_SECRET 을 프로젝트별 신규 시크릿으로.
  * @param {string} rel - 파일 상대경로.
  * @param {string} content - 원본 텍스트.
- * @param {{ name: string, version: string }} vars
+ * @param {{ name: string, version: string, sessionSecret: string }} vars
  * @returns {string}
  */
 function transformText(rel, content, vars) {
@@ -88,6 +90,12 @@ function transformText(rel, content, vars) {
     // 모노레포 로컬 링크 → 퍼블리시된 프레임워크 버전 핀. 스캐폴드된 프로젝트는 독립 패키지라 file: 가 안 풀린다.
     out = out.replace('"file:../.."', `"^${vars.version}"`)
   }
+  if (rel === '.env') {
+    // 세션 쿠키 HMAC 시크릿은 데모 값을 복제하면 모든 `mega new` 프로젝트가 같은 서명 키를 공유한다
+    // (세션 위조·cross-app 쿠키 수용 위험) — 프로젝트마다 신규 생성으로 치환한다. `.env.example` 은
+    // placeholder("change-me-...") 그대로 둔다(문서 역할).
+    out = out.replace(/^SESSION_SECRET=.*$/m, `SESSION_SECRET=${vars.sessionSecret}`)
+  }
   return out
 }
 
@@ -104,7 +112,9 @@ export function scaffoldProject(targetDir, { name, force = false } = {}) {
   const projectName = nameVariants(name ?? root.split(/[/\\]/).pop() ?? 'mega-app').kebab
   /** @type {string} */
   const version = JSON.parse(readFileSync(FRAMEWORK_PKG, 'utf8')).version
-  const vars = { name: projectName, version }
+  // 프로젝트별 세션 시크릿 — base64url(영숫자·-·_ 만)이라 .env 값·쉘 복붙에 안전(=/+// 회피).
+  const sessionSecret = randomBytes(32).toString('base64url')
+  const vars = { name: projectName, version, sessionSecret }
 
   /** @type {string[]} */ const written = []
   /** @type {string[]} */ const skipped = []

package/src/cli/commands/scaffold.js

@@ -1,19 +1,25 @@
 // @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 { generate, generateFromScaffoldDef, 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'])
 
 /**
@@ -26,27 +32,52 @@ function reportFiles(out, r, root) {
 }
 
 /**
- * scaffold/dev 명령을 실행한다. commander 로 파싱하되 `process.exit` 를 부르지 않고 exit code 를 반환한다
- * (runCli 계약 정합).
- * @param {string[]} argv - `process.argv.slice(2)` (첫 토큰 = 명령).
+ * `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 +95,54 @@ 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)
+        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 },
+          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 +151,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 +160,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

@@ -38,6 +38,20 @@ export const GENERATOR_KINDS = /** @type {const} */ ([
   'migration',
 ])
 
+/**
+ * 플러그인 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 +135,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: {} })
@@ -347,6 +372,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