mega-framework 0.1.0

package/src/lib/mega-plugin.js

@@ -0,0 +1,650 @@
+// @ts-check
+/**
+ * 플러그인 시스템 — 명시 등록 + `install(mega)` 패턴 + apiVersion 호환 강제.
+ *
+ * 정본: [ADR-079](../../docs/09-decisions-and-open-questions.md), [ADR-122] / 03-api-spec §11 /
+ * 02-architecture §14. **자족형 플러그인 호스트(ADR-122 옵션 A + ADR-123 jobs/schedules 확장 +
+ * ADR-134 workers 확장)** — 코어 hook 의 *등록 표면*을 제공한다:
+ *   - `adapters.register` 는 실 어댑터 드라이버 레지스트리(ADR-044)에 **즉시 위임**(live consumer).
+ *   - `cli.command`/`app.use`/`middlewares.global`/`scaffold.register`/`lib.register`/`jobs.register`/
+ *     `schedules.register`/`workers.register` 는 호스트 내부의 **실제 queryable 레지스트리**(Map/배열)에
+ *     수집 → 후속 CLI/호스트가 소비(`jobs`/`schedules` 는 `mega worker`/`mega scheduler` 가
+ *     `config.jobs`/`config.schedules` 정적 등록분과 함께 흡수, ADR-123; `workers` 는 `bootApp`/CLI 호스트의
+ *     `buildWorkers` 가 `config.workers` 정적 등록분과 함께 흡수, ADR-134).
+ *   - `on('beforeBoot'|'afterBoot'|'beforeShutdown')` 은 lifecycle hook 배열에 수집 → 부팅/종료
+ *     orchestrator(`bootApp`, ADR-123)가 {@link MegaPluginHost#runLifecycle} 로 구동.
+ *
+ * **자족적**이라 중앙 부팅 orchestrator 없이도 단위/통합 테스트가 완결된다(`install(host)` 한 줄).
+ * 실 부팅 시퀀스에 {@link loadPlugins} 를 끼우는 배선은 중앙 orchestrator
+ * 영역(ADR-122).
+ *
+ * @module lib/mega-plugin
+ */
+import { resolve as pathResolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { MegaConfigError } from '../errors/config-error.js'
+import { register as registerAdapterDriver, BUILTIN_DRIVERS } from '../adapters/registry.js'
+
+/**
+ * 코어 플러그인 API 계약 메이저 버전 (ADR-122). npm 패키지 버전(`package.json`, 현재 pre-1.0 `0.x`)과
+ * **분리**한다 — 패키지 0.x 는 자주 바뀌어 거기 묶으면 0.x bump 마다 모든 플러그인이 깨진다. 플러그인은
+ * 코어 *내부 구조*가 아니라 *공개 hook 계약*에 의존하므로, 계약이 바뀔 때만 올리는 독립 버전이 맞다.
+ * 03-api-spec/02-architecture 의 예시(`apiVersion: '1'`)와도 정합.
+ * @type {string}
+ */
+export const CORE_API_VERSION = '1'
+
+/** lifecycle 이벤트 화이트리스트 (오타 차단 — 형제 MegaScheduler/MegaCircuitBreaker `on` 정책). */
+const LIFECYCLE_EVENTS = /** @type {const} */ (['beforeBoot', 'afterBoot', 'beforeShutdown'])
+
+/**
+ * @typedef {Object} MegaPlugin
+ * @property {string} name        - npm 패키지명 또는 식별자.
+ * @property {string} version     - semver (예: '1.0.0').
+ * @property {string} apiVersion  - 코어 API 계약 메이저 버전. mismatch 시 부팅 throw.
+ * @property {(mega: MegaPluginHost, options?: object) => void | Promise<void>} install
+ */
+
+/**
+ * @typedef {Object} MegaCliCommandDef
+ * @property {string} description
+ * @property {(args: object) => unknown} handler - 03-api-spec 은 `Promise<void>|void` 로 적었으나,
+ *   핸들러가 결과(예: exit code·출력)를 반환할 수 있게 `unknown` 으로 넓힘(CLI 가 소비).
+ */
+
+/**
+ * @typedef {Object} MegaScaffoldDef
+ * @property {string} dir
+ * @property {Array<{ path: string, template: string }>} files
+ */
+
+/**
+ * @typedef {Object} LoadedPluginMeta
+ * @property {string} name
+ * @property {string} version
+ * @property {string} apiVersion
+ */
+
+/**
+ * `mega.config.js` 의 `plugins` 배열 (04-data-models §1.1 MegaPluginsConfig).
+ * @typedef {Array<string | { name: string, options?: object }>} MegaPluginsConfig
+ */
+
+/**
+ * `MegaPluginContext` — `install(mega)` 가 받는 `mega` 인자(03-api-spec §11).
+ *
+ * 코어 hook 의 등록 표면을 dot-notation(`mega.adapters.register(...)`)으로 노출하고, 등록 결과를
+ * 내부 레지스트리에 수집한다. 수집물은 getter/list 메서드로 queryable 하다(후속 Step 이 소비).
+ */
+export class MegaPluginHost {
+  /** @type {{ debug?: Function } | null} */
+  #logger
+  /** @type {Map<string, MegaCliCommandDef>} */
+  #commands = new Map()
+  /** @type {Map<string, MegaScaffoldDef>} */
+  #generators = new Map()
+  /** @type {Map<string, Function>} */
+  #libs = new Map()
+  /** @type {Array<{ plugin: Function, opts: object | undefined }>} */
+  #fastifyPlugins = []
+  /** @type {Function[]} */
+  #globalMiddlewares = []
+  /** @type {{ beforeBoot: Function[], afterBoot: Function[], beforeShutdown: Function[] }} */
+  #lifecycle = { beforeBoot: [], afterBoot: [], beforeShutdown: [] }
+  /** @type {Function[]} 플러그인이 등록한 MegaJob 서브클래스(등록 순서). */
+  #jobs = []
+  /** @type {Set<Function>} 잡 중복 등록 차단(같은 클래스 2회). */
+  #jobSet = new Set()
+  /** @type {Function[]} 플러그인이 등록한 MegaSchedule 서브클래스(등록 순서). */
+  #schedules = []
+  /** @type {Set<Function>} 스케줄 중복 등록 차단. */
+  #scheduleSet = new Set()
+  /** @type {Function[]} 플러그인이 등록한 MegaWorker 서브클래스(등록 순서). */
+  #workers = []
+  /** @type {Set<Function>} 워커 중복 등록 차단(같은 클래스 2회). */
+  #workerSet = new Set()
+  /** @type {LoadedPluginMeta[]} */
+  #loaded = []
+
+  /**
+   * @param {{ logger?: { debug?: Function } }} [opts] - 길목 debug 로그용(선택). 순수 등록 유틸이라
+   *   미주입이 기본 — 미주입 시 no-op.
+   */
+  constructor({ logger } = {}) {
+    this.#logger = logger ?? null
+
+    // dot-notation hook 표면 (03-api-spec §11). 각 hook 은 private 등록 메서드로 위임.
+    /** 3rd party 어댑터 등록 (ADR-044) — 실 드라이버 레지스트리에 즉시 위임. */
+    this.adapters = {
+      /** @param {string} driver @param {Function} AdapterClass */
+      register: (driver, AdapterClass) => this.#registerAdapter(driver, AdapterClass),
+    }
+    /** CLI 명령 등록 — `mega <name>`(소비는 CLI). */
+    this.cli = {
+      /** @param {string} name @param {MegaCliCommandDef} opts */
+      command: (name, opts) => this.#registerCommand(name, opts),
+    }
+    /** Fastify 플러그인을 모든 앱에 등록(소비는 부팅 orchestrator). */
+    this.app = {
+      /** @param {Function} fastifyPlugin @param {object} [opts] */
+      use: (fastifyPlugin, opts) => this.#useFastifyPlugin(fastifyPlugin, opts),
+    }
+    /** 글로벌 미들웨어 등록(소비는 라우트 파이프라인). */
+    this.middlewares = {
+      /** @param {Function} mw */
+      global: (mw) => this.#registerGlobalMiddleware(mw),
+    }
+    /** 스캐폴드 generator 등록 — `mega g <name>`(소비는 CLI). */
+    this.scaffold = {
+      /** @param {string} name @param {MegaScaffoldDef} def */
+      register: (name, def) => this.#registerGenerator(name, def),
+    }
+    /** 코어 lib 노출 — `ctx.lib.<name>`(소비는 ctx 빌더). */
+    this.lib = {
+      /** @param {string} name @param {Function} Class */
+      register: (name, Class) => this.#registerLib(name, Class),
+    }
+    /** 잡 등록 — `mega worker` 가 `config.jobs` 정적 등록분과 함께 흡수(ADR-123). */
+    this.jobs = {
+      /** @param {Function} JobClass - MegaJob 서브클래스. */
+      register: (JobClass) => this.#registerJob(JobClass),
+    }
+    /** 스케줄 등록 — `mega scheduler` 가 `config.schedules` 정적 등록분과 함께 흡수(ADR-123). */
+    this.schedules = {
+      /** @param {Function} TaskClass - MegaSchedule 서브클래스. */
+      register: (TaskClass) => this.#registerSchedule(TaskClass),
+    }
+    /** 워커 등록 — `buildWorkers` 가 `config.workers` 정적 등록분과 함께 흡수(ADR-134). */
+    this.workers = {
+      /** @param {Function} WorkerClass - MegaWorker 서브클래스. */
+      register: (WorkerClass) => this.#registerWorker(WorkerClass),
+    }
+  }
+
+  /**
+   * 3rd party 어댑터 드라이버 등록(ADR-044). 빌트인 8종 이름은 점유 금지(registerFromConfig 와 동일
+   * 보호) — 실 클래스 검증·중복 충돌은 어댑터 레지스트리가 throw.
+   * @param {string} driver
+   * @param {Function} AdapterClass - MegaAdapter 서브클래스.
+   * @returns {void}
+   */
+  #registerAdapter(driver, AdapterClass) {
+    if (typeof driver === 'string' && BUILTIN_DRIVERS.has(driver)) {
+      throw new MegaConfigError(
+        'plugin.builtin_driver_conflict',
+        `Plugin cannot register builtin driver "${driver}" (reserved).`,
+        { details: { driver } },
+      )
+    }
+    // 어댑터 레지스트리에 위임 — 비-클래스/충돌은 거기서 fail-fast(MegaValidationError/MegaInternalError).
+    registerAdapterDriver(driver, /** @type {any} */ (AdapterClass))
+  }
+
+  /**
+   * CLI 명령 등록. 같은 이름 재등록은 fail-fast(silent override 금지 — 형제 register 패턴).
+   * @param {string} name
+   * @param {MegaCliCommandDef} opts
+   * @returns {void}
+   */
+  #registerCommand(name, opts) {
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new TypeError('mega.cli.command: name must be a non-empty string.')
+    }
+    if (!opts || typeof opts.handler !== 'function') {
+      throw new TypeError(`mega.cli.command('${name}'): opts.handler must be a function.`)
+    }
+    if (this.#commands.has(name)) {
+      throw new MegaConfigError('plugin.duplicate_command', `CLI command '${name}' is already registered.`, {
+        details: { name },
+      })
+    }
+    this.#commands.set(name, {
+      description: typeof opts.description === 'string' ? opts.description : '',
+      handler: opts.handler,
+    })
+  }
+
+  /**
+   * Fastify 플러그인을 모든 앱 인스턴스에 등록(수집 — 부팅 orchestrator 가 각 MegaApp 에 register).
+   * @param {Function} fastifyPlugin
+   * @param {object} [opts]
+   * @returns {void}
+   */
+  #useFastifyPlugin(fastifyPlugin, opts) {
+    if (typeof fastifyPlugin !== 'function') {
+      throw new TypeError('mega.app.use: fastifyPlugin must be a function.')
+    }
+    this.#fastifyPlugins.push({ plugin: fastifyPlugin, opts })
+  }
+
+  /**
+   * 글로벌 미들웨어 등록(수집 — 라우트 파이프라인이 소비).
+   * @param {Function} middleware
+   * @returns {void}
+   */
+  #registerGlobalMiddleware(middleware) {
+    if (typeof middleware !== 'function') {
+      throw new TypeError('mega.middlewares.global: middleware must be a function.')
+    }
+    this.#globalMiddlewares.push(middleware)
+  }
+
+  /**
+   * 스캐폴드 generator 등록. 같은 이름 재등록은 fail-fast.
+   * @param {string} name
+   * @param {MegaScaffoldDef} def
+   * @returns {void}
+   */
+  #registerGenerator(name, def) {
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new TypeError('mega.scaffold.register: name must be a non-empty string.')
+    }
+    if (!def || typeof def.dir !== 'string' || !Array.isArray(def.files)) {
+      throw new TypeError(`mega.scaffold.register('${name}'): def must be { dir: string, files: array }.`)
+    }
+    if (this.#generators.has(name)) {
+      throw new MegaConfigError('plugin.duplicate_generator', `Scaffold generator '${name}' is already registered.`, {
+        details: { name },
+      })
+    }
+    this.#generators.set(name, { dir: def.dir, files: [...def.files] })
+  }
+
+  /**
+   * 코어 lib 노출 등록. 같은 이름 재등록은 fail-fast.
+   * @param {string} name
+   * @param {Function} Class
+   * @returns {void}
+   */
+  #registerLib(name, Class) {
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new TypeError('mega.lib.register: name must be a non-empty string.')
+    }
+    if (typeof Class !== 'function') {
+      throw new TypeError(`mega.lib.register('${name}'): Class must be a function/constructor.`)
+    }
+    if (this.#libs.has(name)) {
+      throw new MegaConfigError('plugin.duplicate_lib', `Lib '${name}' is already registered.`, {
+        details: { name },
+      })
+    }
+    this.#libs.set(name, Class)
+  }
+
+  /**
+   * 잡 등록(수집 — `mega worker` 가 `config.jobs` 정적 등록분과 함께 흡수, ADR-123). 같은 클래스 재등록은
+   * fail-fast(silent double-consume 금지 — 형제 register 패턴). subject/bus 검증은 `MegaJobWorker.register`
+   * 가 부팅 시 수행하므로 여기선 클래스 형태·중복만 본다.
+   * @param {Function} JobClass - MegaJob 서브클래스.
+   * @returns {void}
+   */
+  #registerJob(JobClass) {
+    if (typeof JobClass !== 'function') {
+      throw new TypeError('mega.jobs.register: JobClass must be a class (MegaJob subclass).')
+    }
+    if (this.#jobSet.has(JobClass)) {
+      throw new MegaConfigError('plugin.duplicate_job', `Job '${JobClass.name}' is already registered.`, {
+        details: { name: JobClass.name },
+      })
+    }
+    this.#jobSet.add(JobClass)
+    this.#jobs.push(JobClass)
+  }
+
+  /**
+   * 스케줄 등록(수집 — `mega scheduler` 가 `config.schedules` 정적 등록분과 함께 흡수, ADR-123). 같은 클래스
+   * 재등록은 fail-fast. cron 검증은 `MegaScheduler.register` 가 부팅 시 수행한다.
+   * @param {Function} TaskClass - MegaSchedule 서브클래스.
+   * @returns {void}
+   */
+  #registerSchedule(TaskClass) {
+    if (typeof TaskClass !== 'function') {
+      throw new TypeError('mega.schedules.register: TaskClass must be a class (MegaSchedule subclass).')
+    }
+    if (this.#scheduleSet.has(TaskClass)) {
+      throw new MegaConfigError(
+        'plugin.duplicate_schedule',
+        `Schedule '${TaskClass.name}' is already registered.`,
+        { details: { name: TaskClass.name } },
+      )
+    }
+    this.#scheduleSet.add(TaskClass)
+    this.#schedules.push(TaskClass)
+  }
+
+  /**
+   * 워커 등록(수집 — `buildWorkers` 가 `config.workers` 정적 등록분과 함께 흡수, ADR-134). 같은 클래스
+   * 재등록은 fail-fast(silent double-consume 금지 — 형제 register 패턴). MegaWorker 서브클래스 검증·`static
+   * name` 중복은 `buildWorkers` 가 부팅 시 수행하므로(어댑터 connect 후 인스턴스화 시점) 여기선 클래스
+   * 형태·중복만 본다(잡/스케줄 register 와 동일 분업).
+   * @param {Function} WorkerClass - MegaWorker 서브클래스.
+   * @returns {void}
+   */
+  #registerWorker(WorkerClass) {
+    if (typeof WorkerClass !== 'function') {
+      throw new TypeError('mega.workers.register: WorkerClass must be a class (MegaWorker subclass).')
+    }
+    if (this.#workerSet.has(WorkerClass)) {
+      throw new MegaConfigError('plugin.duplicate_worker', `Worker '${WorkerClass.name}' is already registered.`, {
+        details: { name: WorkerClass.name },
+      })
+    }
+    this.#workerSet.add(WorkerClass)
+    this.#workers.push(WorkerClass)
+  }
+
+  /**
+   * 라이프사이클 이벤트 구독. 미지정 이벤트는 `RangeError`(오타 차단 — 형제 MegaScheduler `on` 정책).
+   * hook 은 부팅 orchestrator 가 넘기는 boot context 를 선택적으로 받는다(L-2/ADR-123, `(ctx?) => ...`).
+   * @param {'beforeBoot' | 'afterBoot' | 'beforeShutdown'} event
+   * @param {(ctx?: object) => Promise<void> | void} fn
+   * @returns {this}
+   */
+  on(event, fn) {
+    this.#assertLifecycleEvent(event)
+    if (typeof fn !== 'function') {
+      throw new TypeError(`mega.on('${event}'): fn must be a function.`)
+    }
+    this.#lifecycle[event].push(fn)
+    return this
+  }
+
+  /**
+   * 한 lifecycle 단계의 구독 hook 을 **등록 순서대로** 실행한다(부팅 orchestrator 가 호출).
+   * beforeBoot/afterBoot 는 fail-fast(에러 전파)로 부팅을 멈춘다. beforeShutdown 은 graceful
+   * shutdown 경로에서 보통 `MegaShutdown.register`(per-hook catch)로 브리지된다(ADR-122).
+   *
+   * **L-2(ADR-123)**: 부팅 orchestrator 가 boot context(`{ config, log, db/cache/bus/lock }`)를
+   * 인자로 넘기면 각 hook 이 `fn(ctx)` 로 받는다. ctx 미주입 시 `undefined` 전달(03-api-spec 의
+   * `() => void` 시그니처와 하위 호환 — 인자 안 받는 hook 은 그대로 동작).
+   * @param {'beforeBoot' | 'afterBoot' | 'beforeShutdown'} event
+   * @param {object} [ctx] - boot context(L-2). orchestrator 가 주입, 미주입 시 undefined.
+   * @returns {Promise<void>}
+   */
+  async runLifecycle(event, ctx) {
+    this.#assertLifecycleEvent(event)
+    for (const fn of this.#lifecycle[event]) {
+      this.#logger?.debug?.({ event }, 'plugin.lifecycle run')
+      await fn(ctx)
+    }
+  }
+
+  /**
+   * lifecycle 이벤트명 화이트리스트 검증.
+   * @param {string} event
+   * @returns {void}
+   */
+  #assertLifecycleEvent(event) {
+    if (!LIFECYCLE_EVENTS.includes(/** @type {any} */ (event))) {
+      throw new RangeError(
+        `MegaPluginHost: unknown lifecycle event '${event}'. Known: ${LIFECYCLE_EVENTS.join(' | ')}.`,
+      )
+    }
+  }
+
+  /**
+   * loadPlugins 가 install 성공 후 메타를 기록한다(framework-internal).
+   * @param {LoadedPluginMeta} meta
+   * @returns {void}
+   */
+  _recordLoaded(meta) {
+    this.#loaded.push(meta)
+  }
+
+  // ── queryable 접근자 (후속 Step·테스트가 소비) ──────────────────────────────
+
+  /** 등록 순서대로 install 된 플러그인 메타 목록. @returns {LoadedPluginMeta[]} */
+  get loadedPlugins() {
+    return [...this.#loaded]
+  }
+
+  /** 등록된 CLI 명령 이름 목록. @returns {string[]} */
+  listCommands() {
+    return [...this.#commands.keys()]
+  }
+
+  /** CLI 명령 정의 조회(없으면 undefined). @param {string} name @returns {MegaCliCommandDef | undefined} */
+  getCommand(name) {
+    return this.#commands.get(name)
+  }
+
+  /** CLI 명령 존재 여부. @param {string} name @returns {boolean} */
+  hasCommand(name) {
+    return this.#commands.has(name)
+  }
+
+  /** 등록된 스캐폴드 generator 이름 목록. @returns {string[]} */
+  listGenerators() {
+    return [...this.#generators.keys()]
+  }
+
+  /** 스캐폴드 generator 정의 조회. @param {string} name @returns {MegaScaffoldDef | undefined} */
+  getGenerator(name) {
+    return this.#generators.get(name)
+  }
+
+  /** 등록된 lib 이름 목록. @returns {string[]} */
+  listLibs() {
+    return [...this.#libs.keys()]
+  }
+
+  /** lib 클래스 조회. @param {string} name @returns {Function | undefined} */
+  getLib(name) {
+    return this.#libs.get(name)
+  }
+
+  /** 플러그인이 등록한 잡 클래스 목록(복사본 — `mega worker` 가 소비). @returns {Function[]} */
+  listJobs() {
+    return [...this.#jobs]
+  }
+
+  /** 플러그인이 등록한 스케줄 클래스 목록(복사본 — `mega scheduler` 가 소비). @returns {Function[]} */
+  listSchedules() {
+    return [...this.#schedules]
+  }
+
+  /** 플러그인이 등록한 워커 클래스 목록(복사본 — `buildWorkers` 가 소비). @returns {Function[]} */
+  listWorkers() {
+    return [...this.#workers]
+  }
+
+  /** 등록된 Fastify 플러그인 목록(복사본). @returns {Array<{ plugin: Function, opts: object | undefined }>} */
+  get fastifyPlugins() {
+    return [...this.#fastifyPlugins]
+  }
+
+  /** 등록된 글로벌 미들웨어 목록(복사본). @returns {Function[]} */
+  get globalMiddlewares() {
+    return [...this.#globalMiddlewares]
+  }
+
+  /**
+   * 한 lifecycle 단계의 구독 hook 목록(복사본).
+   * @param {'beforeBoot' | 'afterBoot' | 'beforeShutdown'} event
+   * @returns {Function[]}
+   */
+  lifecycleHooks(event) {
+    this.#assertLifecycleEvent(event)
+    return [...this.#lifecycle[event]]
+  }
+}
+
+/**
+ * `plugins` 배열을 순서대로 로딩한다 — resolve → shape 검증 → apiVersion 체크 → `install(mega, options)`.
+ *
+ * 02-architecture §14 부팅 시퀀스 4·5단계. 배열에 **명시된 것만** 로딩(auto-discovery X) → 배열에 없는
+ * 패키지는 `node_modules` 에 있어도 `install` 이 호출되지 않는다(ADR-079). 어느 단계든 실패하면
+ * `MegaConfigError` 로 fail-fast(부팅 중단, silent skip 금지).
+ *
+ * @param {MegaPluginsConfig | null | undefined} plugins -
+ *   `Array<string | { name, options }>`. 테스트·프로그램 편의로 **인라인 플러그인 객체**(`install` 함수
+ *   보유)도 원소로 허용한다.
+ * @param {MegaPluginHost} host - 코어가 만든 hook 컨텍스트.
+ * @param {{ projectRoot?: string, importer?: (spec: string) => Promise<MegaPlugin>, logger?: { debug?: Function } }} [opts] -
+ *   `projectRoot` 는 로컬 경로(`./...`) 해석 기준. `importer` 주입 시 모듈 해석을 가로채(테스트). `logger`
+ *   는 길목 debug 로그.
+ * @returns {Promise<LoadedPluginMeta[]>} 로딩된 플러그인 메타 목록(등록 순서).
+ * @throws {MegaConfigError} 잘못된 config/entry/shape/apiVersion/로드 실패/중복 플러그인(plugin.duplicate_plugin).
+ * @throws {TypeError} host 가 MegaPluginHost 인스턴스가 아님.
+ */
+export async function loadPlugins(plugins, host, { projectRoot, importer, logger } = {}) {
+  if (plugins === undefined || plugins === null) return []
+  if (!Array.isArray(plugins)) {
+    throw new MegaConfigError('plugin.invalid_config', 'config.plugins must be an array (MegaPluginsConfig).', {
+      details: { type: typeof plugins },
+    })
+  }
+  if (!(host instanceof MegaPluginHost)) {
+    throw new TypeError('loadPlugins: host must be a MegaPluginHost instance.')
+  }
+  const doImport = importer ?? createDefaultImporter(projectRoot)
+
+  /** @type {LoadedPluginMeta[]} */
+  const loaded = []
+  // 중복 플러그인 fail-fast(M-1). 같은 name 이 배열에 두 번 기재되면 on/middlewares.global/app.use 가
+  // silent double-registration 된다(배열 push 라 dedup 0) → 부팅을 멈춰 의도치 않은 중복 hook 을 차단.
+  const seenNames = new Set()
+  for (const entry of plugins) {
+    const { plugin, options, spec } = await resolvePluginEntry(entry, doImport)
+    assertPluginShape(plugin, spec)
+    assertApiVersion(plugin)
+    if (seenNames.has(plugin.name)) {
+      throw new MegaConfigError(
+        'plugin.duplicate_plugin',
+        `Plugin '${plugin.name}' is registered more than once in config.plugins.`,
+        { details: { name: plugin.name } },
+      )
+    }
+    seenNames.add(plugin.name)
+    logger?.debug?.({ plugin: plugin.name, version: plugin.version }, 'plugin.install enter')
+    await plugin.install(host, options)
+    const meta = { name: plugin.name, version: plugin.version, apiVersion: plugin.apiVersion }
+    host._recordLoaded(meta)
+    loaded.push(meta)
+    logger?.debug?.({ plugin: plugin.name }, 'plugin.install done')
+  }
+  return loaded
+}
+
+/**
+ * plugins 배열 원소를 `{ plugin, options, spec }` 로 해석한다.
+ *   - `string` — npm 패키지명/로컬 경로 → import.
+ *   - `{ name, options }` — name 을 import, options 를 install 2번째 인자로.
+ *   - 인라인 플러그인 객체(`install` 함수 보유) — 그대로 사용(options 없음).
+ * @param {unknown} entry
+ * @param {(spec: string) => Promise<MegaPlugin>} doImport
+ * @returns {Promise<{ plugin: MegaPlugin, options: object | undefined, spec: string }>}
+ */
+async function resolvePluginEntry(entry, doImport) {
+  if (typeof entry === 'string') {
+    if (entry.length === 0) {
+      throw new MegaConfigError('plugin.invalid_entry', 'plugins entry string must be non-empty.', { details: {} })
+    }
+    return { plugin: await doImport(entry), options: undefined, spec: entry }
+  }
+  if (entry && typeof entry === 'object') {
+    const obj = /** @type {Record<string, any>} */ (entry)
+    // 인라인 플러그인 객체(프로그램·테스트 편의) — install 함수가 있으면 import 없이 그대로.
+    if (typeof obj.install === 'function') {
+      return { plugin: /** @type {MegaPlugin} */ (entry), options: undefined, spec: obj.name ?? '(inline)' }
+    }
+    // 정본 { name, options } 형태.
+    if (typeof obj.name === 'string' && obj.name.length > 0) {
+      return { plugin: await doImport(obj.name), options: obj.options, spec: obj.name }
+    }
+  }
+  throw new MegaConfigError(
+    'plugin.invalid_entry',
+    `Invalid plugins entry: expected string | { name, options } | plugin object, got ${describeType(entry)}.`,
+    { details: { type: describeType(entry) } },
+  )
+}
+
+/**
+ * 기본 importer — 로컬 경로는 projectRoot 기준 file URL, 그 외는 bare specifier 로 dynamic import.
+ * @param {string} [projectRoot]
+ * @returns {(spec: string) => Promise<MegaPlugin>}
+ */
+function createDefaultImporter(projectRoot) {
+  return async (spec) => {
+    let target = spec
+    const isLocal = spec.startsWith('.') || spec.startsWith('/')
+    if (isLocal) {
+      if (spec.startsWith('.') && !projectRoot) {
+        throw new MegaConfigError(
+          'plugin.load_failed',
+          `Cannot resolve local plugin '${spec}' without projectRoot.`,
+          { details: { spec } },
+        )
+      }
+      const abs = spec.startsWith('/') ? spec : pathResolve(/** @type {string} */ (projectRoot), spec)
+      target = pathToFileURL(abs).href
+    }
+    let mod
+    try {
+      mod = await import(target)
+    } catch (err) {
+      throw new MegaConfigError('plugin.load_failed', `Failed to load plugin '${spec}': ${err.message}`, {
+        cause: err,
+      })
+    }
+    if (!mod.default) {
+      throw new MegaConfigError('plugin.no_default_export', `Plugin '${spec}' must have a default export.`, {
+        details: { spec },
+      })
+    }
+    return mod.default
+  }
+}
+
+/**
+ * 플러그인 default export 모양 검증 — `{ name, version, apiVersion, install }` (ADR-079).
+ * @param {unknown} plugin
+ * @param {string} spec - 에러 메시지용 식별자(이름 추출 실패 시 fallback).
+ * @returns {asserts plugin is MegaPlugin}
+ */
+function assertPluginShape(plugin, spec) {
+  const p = /** @type {Record<string, any>} */ (plugin)
+  const name = p && typeof p.name === 'string' && p.name.length > 0 ? p.name : spec
+  const ok =
+    p &&
+    typeof p === 'object' &&
+    typeof p.name === 'string' &&
+    p.name.length > 0 &&
+    typeof p.version === 'string' &&
+    typeof p.apiVersion === 'string' &&
+    typeof p.install === 'function'
+  if (!ok) {
+    throw new MegaConfigError(
+      'plugin.invalid_shape',
+      `Plugin '${name}' must export { name, version, apiVersion, install } object`,
+      { details: { plugin: name } },
+    )
+  }
+}
+
+/**
+ * apiVersion 이 코어 계약 메이저와 일치하는지 검증. mismatch → 부팅 throw(silent skip 금지, ADR-079).
+ * @param {MegaPlugin} plugin
+ * @returns {void}
+ */
+function assertApiVersion(plugin) {
+  if (String(plugin.apiVersion) !== String(CORE_API_VERSION)) {
+    throw new MegaConfigError(
+      'plugin.api_version_mismatch',
+      `Plugin '${plugin.name}' requires apiVersion '${plugin.apiVersion}' but core provides '${CORE_API_VERSION}'`,
+      { details: { plugin: plugin.name, required: plugin.apiVersion, provided: CORE_API_VERSION } },
+    )
+  }
+}
+
+/**
+ * 에러 메시지용 타입 설명.
+ * @param {unknown} v
+ * @returns {string}
+ */
+function describeType(v) {
+  if (v === null) return 'null'
+  if (Array.isArray(v)) return 'array'
+  return typeof v
+}