mega-framework 0.1.5 → 0.1.7

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