mega-framework 0.1.5 → 0.1.7

package/types/cli/generators/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @typedef {object} Artifact
+ * @property {string} outAbs - 쓸 파일 절대경로.
+ * @property {string} content - 렌더된 내용.
+ * @property {'code'|'test'|'task'|'route'} role
+ */
+/**
+ * kind 별로 생성할 artifact 목록을 계획한다(아직 디스크에 쓰지 않음).
+ * @param {string} kind
+ * @param {string} rawName
+ * @param {Record<string, any>} opts - { app, version, kind(adapter), lng, ns }
+ * @param {string} projectRoot
+ * @returns {Artifact[]}
+ */
+export function planArtifacts(kind: string, rawName: string, opts: Record<string, any>, projectRoot: string): Artifact[];
+/**
+ * 계획된 artifact 를 디스크에 쓴다. 이미 있으면 건너뛴다(force 면 덮어씀).
+ * @param {Artifact[]} artifacts
+ * @param {{ force?: boolean }} [opts]
+ * @returns {{ written: string[], skipped: string[] }}
+ */
+export function writeArtifacts(artifacts: Artifact[], { force }?: {
+    force?: boolean;
+}): {
+    written: string[];
+    skipped: string[];
+};
+/**
+ * 플러그인 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: {
+    dir: string;
+    files: Array<{
+        path: string;
+        template: string;
+    }>;
+}, rawName: string, opts: Record<string, any>, projectRoot: string): Artifact[];
+/**
+ * 플러그인 등록 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: string, def: {
+    dir: string;
+    files: Array<{
+        path: string;
+        template: string;
+    }>;
+}, rawName: string, opts?: object, projectRoot?: string): {
+    kind: string;
+    name: string;
+    written: string[];
+    skipped: string[];
+};
+/**
+ * `mega g <kind> <name>` 실행 — 계획 → 쓰기 → 결과 반환.
+ * @param {string} kind
+ * @param {string} rawName
+ * @param {object} [opts] - { app, version, kind(adapter), lng, force }
+ * @param {string} [projectRoot]
+ * @returns {{ kind: string, name: string, written: string[], skipped: string[] }}
+ */
+export function generate(kind: string, rawName: string, opts?: object, projectRoot?: string): {
+    kind: string;
+    name: string;
+    written: string[];
+    skipped: string[];
+};
+/** 지원 generator 종류(roadmap §337 — 13종). */
+export const GENERATOR_KINDS: readonly ["app", "controller", "channel", "service", "model", "middleware", "route", "schedule", "job", "worker", "locale", "adapter", "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: Readonly<Record<string, string>>;
+export type Artifact = {
+    /**
+     * - 쓸 파일 절대경로.
+     */
+    outAbs: string;
+    /**
+     * - 렌더된 내용.
+     */
+    content: string;
+    role: "code" | "test" | "task" | "route";
+};
+export type Variants = {
+    kebab: string;
+    pascal: string;
+    camel: string;
+    snake: string;
+    words: string[];
+};
+export type BaseVars = Record<string, string>;

package/types/cli/index.d.ts

@@ -0,0 +1,249 @@
+/**
+ * 프로젝트 루트의 `.env` 를 `process.env` 로 로드한다(파일이 있을 때만). Node 내장
+ * `process.loadEnvFile`(20.6+) 사용 — 신규 dep 0. **이미 설정된 실제 환경변수는 덮어쓰지 않는다**
+ * (`--env-file` 과 동일 우선순위 — 실 env 우선). config(`mega.config.js`)들이 `process.env.X` 를
+ * 참조하고 비밀은 `.env` 에만 두는 컨벤션(CLAUDE.md)을 CLI 가 보장한다(ADR-152). config 로드보다 먼저
+ * 호출해야 `process.env` 참조가 채워진다.
+ *
+ * @param {string} projectRoot - `.env` 를 찾을 프로젝트 루트(`--root` 또는 cwd).
+ * @param {{ debug?: Function }} [logger]
+ * @returns {boolean} 로드했으면 true, `.env` 부재면 false.
+ * @throws {Error} `.env` 가 존재하나 파싱 실패 시(fail-fast — silent 무시 X).
+ */
+export function loadProjectEnv(projectRoot: string, logger?: {
+    debug?: Function;
+}): boolean;
+/**
+ * 인자 토큰을 `{ _: positionals[], flags: {} }` 로 파싱. `--key=value` / `--key value` / `--flag`(=true).
+ * commander 일원화(ADR-195) 이후에도 두 용도로 남는다 — ① runCli 의 사전 스캔(`--root`·명령어 판별,
+ * commander 진입 전), ② 플러그인 CLI 명령 핸들러 인자 계약(`handler({ _, flags })`, 03-api-spec §11).
+ * @param {string[]} argv - `process.argv.slice(2)` 형태.
+ * @returns {{ _: string[], flags: Record<string, string | boolean> }}
+ */
+export function parseArgs(argv: string[]): {
+    _: string[];
+    flags: Record<string, string | boolean>;
+};
+/**
+ * cluster 워커 수 설정값을 실제 워커 수로 해석한다(ADR-154 / 04-data-models §MegaServerConfig).
+ *
+ * 유효 도메인: **양의 정수** 또는 **'max'**(= CPU 코어 수). 그 외(0·음수·소수·'max' 아닌 문자열)는
+ * fail-closed 로 throw 한다 — 잘못된 값을 1로 조용히 강등하면 운영자가 클러스터가 안 뜬 줄 모른다(P4/P7).
+ * 워커가 1개로 해석되면(설정 `1`, 또는 단일 코어의 'max') 마스터+워커 2프로세스는 오버헤드만 더하므로
+ * **단일 프로세스(클러스터 비활성)** 로 본다 → `null` 반환.
+ *
+ * @param {string | number | boolean | undefined | null} setting - `--cluster` 플래그 / `MEGA_CLUSTER_WORKERS`
+ *   env / `server.cluster` config 값. 미지정(`undefined`/`null`/`''`)은 단일 프로세스. 베어 `--cluster`(=true)는 'max'.
+ * @param {() => number} [cpuCount] - CPU 코어 수 공급자(테스트 주입용). 기본 {@link defaultCpuCount}.
+ * @returns {number | null} 워커 수(≥2) 또는 단일 프로세스면 `null`.
+ * @throws {MegaConfigError} `config.invalid_cluster` — 양의 정수도 'max' 도 아닌 값.
+ */
+export function resolveClusterWorkers(setting: string | number | boolean | undefined | null, cpuCount?: () => number): number | null;
+/**
+ * `--port` 플래그를 검증된 listen 포트로 해석한다(fail-closed — {@link resolveClusterWorkers} 와 동형).
+ *
+ * 유효 도메인: **0~65535 정수**. 미지정(`undefined`)은 config/기본값에 위임하려 `undefined` 를 돌려준다.
+ * 값 없는 베어 `--port`(=`true`)·빈 값 `--port=`(=`''`)·정수 아님·범위 밖은 throw 한다 — 잘못된 값을
+ * 조용히 강등하면(`Number(true)=1` 특권포트, `Number('')=0` 랜덤포트, `Number('abc')=NaN` 은 어댑터
+ * connect 까지 부팅한 뒤 Node 가 `ERR_SOCKET_BAD_PORT` 로 늦게 throw) 운영자가 의도와 다른 포트를 쓰거나
+ * 늦은 cryptic 에러를 만난다(P4/P7). 명시적 `--port 0`(OS 랜덤 포트)은 정상 값으로 허용한다.
+ *
+ * @param {string | boolean | undefined | null} setting - `--port` 플래그 값.
+ * @returns {number | undefined} 검증된 포트, 또는 미지정이면 `undefined`(config/기본 위임).
+ * @throws {MegaConfigError} `config.invalid_port` — 값 없음/빈 값/정수 아님/범위 밖.
+ */
+export function resolvePort(setting: string | boolean | undefined | null): number | undefined;
+/**
+ * `--host` 플래그를 검증된 listen 호스트로 해석한다(fail-closed). 미지정은 config/기본값에 위임하려
+ * `undefined`. 값 없는 베어 `--host`·빈 값 `--host=`는 throw — 빈 호스트를 `MegaServer` 로 흘리면
+ * Node 가 전 인터페이스(`::`)에 silent bind 해 운영자 의도와 달라진다(P4). 비어 있지 않은 문자열은 그대로.
+ *
+ * @param {string | boolean | undefined | null} setting - `--host` 플래그 값.
+ * @returns {string | undefined} 검증된 호스트, 또는 미지정이면 `undefined`(config/기본 위임).
+ * @throws {MegaConfigError} `config.invalid_host` — 값 없음/빈 값.
+ */
+export function resolveHost(setting: string | boolean | undefined | null): string | undefined;
+/**
+ * `--root` 플래그를 검증된 프로젝트 루트로 해석한다(fail-closed — {@link resolveHost} 와 동형, OQ-029②).
+ *
+ * 미지정은 cwd 폴백에 위임하려 `undefined`. 값 없는 베어 `--root`(=`true`)·빈 값 `--root=`(=`''`)은
+ * throw — 빈 루트를 통과시키면 `join('', '.env')`/`loadAndValidateConfig('')` 가 cwd 상대로 silent
+ * 오동작해 운영자가 의도한 루트 지정 실패를 모른다(P4/P7). 비어 있지 않은 문자열은 그대로.
+ *
+ * @param {string | boolean | undefined | null} setting - `--root` 플래그 값.
+ * @returns {string | undefined} 검증된 루트, 또는 미지정이면 `undefined`(cwd 폴백 위임).
+ * @throws {MegaConfigError} `config.invalid_root` — 값 없음/빈 값.
+ */
+export function resolveRoot(setting: string | boolean | undefined | null): string | undefined;
+/**
+ * `--db` 플래그를 검증된 마이그레이션 대상 키로 해석한다(fail-closed — {@link resolveRoot} 와 동형, OQ-029②).
+ *
+ * 미지정은 자동 선택(`resolveMigrationAdapter` 의 유일 db/primary 규칙)에 위임하려 `undefined`. 값 없는
+ * 베어 `--db`(=`true`)·빈 값 `--db=`(=`''`)은 throw — 빈 키가 자동 선택으로 silent 강등되면 운영자가
+ * 지정 실패를 모른 채 다른 db 에 마이그레이션을 적용할 수 있다(P4/P7).
+ *
+ * @param {string | boolean | undefined | null} setting - `--db` 플래그 값.
+ * @returns {string | undefined} 검증된 db 키, 또는 미지정이면 `undefined`(자동 선택 위임).
+ * @throws {MegaConfigError} `config.invalid_db` — 값 없음/빈 값.
+ */
+export function resolveDb(setting: string | boolean | undefined | null): string | undefined;
+/**
+ * `mega start --watch` 가 자신을 `node --watch` 로 재실행해야 하는지 (ADR-182). `--watch` 플래그가 있고
+ * 아직 watch 하에 재실행되지 않았을 때만 true — 가드 env(`MEGA_WATCH_REEXEC`)로 무한재귀를 막는다.
+ * @param {Record<string, string|boolean>} flags
+ * @param {Record<string, string|undefined>} env
+ * @returns {boolean}
+ */
+export function shouldReexecForWatch(flags: Record<string, string | boolean>, env: Record<string, string | undefined>): boolean;
+/**
+ * `mega start --watch` → `node --watch … <self> start … --cluster 1` 재실행 명령을 빌드한다 (ADR-182).
+ *
+ * - `--watch` 인자는 **node 플래그**로 옮기고 mega 인자에선 제거한다.
+ * - **단일 프로세스 강제**(`--cluster 1`) — 멀티워커 watch 카오스 방지(기존 `--cluster` 값은 무시).
+ * - watchPaths 가 있으면 `--watch-path=…`(이게 모듈 그래프 watch 를 **대체**하므로 앱 소스·전역설정 경로를
+ *   명시해야 한다 — 실측 확인). 없으면 plain `--watch`(모듈 그래프 폴백).
+ *
+ * @param {Object} o
+ * @param {string[]} o.argv - 원본 mega argv(예: `['start','--watch','--port','3000']`).
+ * @param {string[]} o.watchPaths - 감시할 절대경로(존재하는 것만).
+ * @param {string} o.selfPath - mega 진입 스크립트(`process.argv[1]`).
+ * @param {string} o.execPath - node 바이너리(`process.execPath`).
+ * @returns {{ command: string, args: string[] }}
+ */
+export function buildWatchCommand({ argv, watchPaths, selfPath, execPath }: {
+    argv: string[];
+    watchPaths: string[];
+    selfPath: string;
+    execPath: string;
+}): {
+    command: string;
+    args: string[];
+};
+/**
+ * `mega` CLI 진입점. 파싱 → 명령 분기. **이 함수는 process.exit 를 호출하지 않는다**(테스트 가능) —
+ * exit code 를 반환하고, bin 래퍼가 `process.exitCode` 로 반영한다.
+ *
+ * @param {string[]} argv - `process.argv.slice(2)`.
+ * @param {Object} [deps] - 테스트 주입용.
+ * @param {(msg: string) => void} [deps.out] - stdout writer(기본 console.log).
+ * @param {(msg: string) => void} [deps.err] - stderr writer(기본 console.error).
+ * @param {string} [deps.cwd] - 기본 projectRoot(기본 process.cwd()).
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [deps.logger]
+ * @param {Function} [deps.spawn] - child_process.spawn 주입(기본 node:child_process). `--watch` 재실행 테스트용.
+ * @param {string} [deps.selfPath] - mega 진입 스크립트 경로(기본 `process.argv[1]`). `--watch` 재실행 대상.
+ * @returns {Promise<number>} exit code(0=성공, 1=실패/미지정 명령).
+ */
+export function runCli(argv: string[], { out, err, cwd, logger, spawn, selfPath }?: {
+    out?: (msg: string) => void;
+    err?: (msg: string) => void;
+    cwd?: string;
+    logger?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+    spawn?: Function;
+    selfPath?: string;
+}): Promise<number>;
+/**
+ * 플러그인 CLI 명령을 dispatch 한다 — config 로드 → 플러그인 install → `host.getCommand(name)` 조회.
+ * 어댑터 connect 는 하지 않는다(명령 핸들러가 필요하면 자체 처리 — 골격은 가볍게 유지, ADR-123).
+ *
+ * @param {string} projectRoot
+ * @param {string} name - 명령 이름.
+ * @param {{ _: string[], flags: Record<string, string | boolean> }} args - 핸들러에 그대로 전달.
+ * @param {{ debug?: Function }} [logger]
+ * @returns {Promise<{ found: boolean, code: number }>}
+ */
+export function dispatchPluginCommand(projectRoot: string, name: string, args: {
+    _: string[];
+    flags: Record<string, string | boolean>;
+}, logger?: {
+    debug?: Function;
+}): Promise<{
+    found: boolean;
+    code: number;
+}>;
+/**
+ * 잡/스케줄 **등록 소스 흡수**(ADR-123) — `config.<key>`(정적) + 플러그인 `host.list*()`(동적)을 합친다.
+ * 명시 등록만(auto-discovery X, ADR-079 정합). 순수 함수라 단위 검증 가능(register 부작용 분리).
+ * @param {Object} global - global config(`jobs`/`schedules` 배열 보유 가능).
+ * @param {import('../lib/mega-plugin.js').MegaPluginHost} host
+ * @param {'jobs' | 'schedules'} kind
+ * @returns {Function[]} 등록할 클래스 목록(config 먼저, 플러그인 등록분 뒤).
+ */
+export function collectRegistrations(global: Object, host: import("../lib/mega-plugin.js").MegaPluginHost, kind: "jobs" | "schedules"): Function[];
+/**
+ * `mega worker` 호스트 골격 — config + 어댑터 connect + ctx + `MegaJobWorker` 인스턴스 + graceful.
+ * 등록 소스 = `config.jobs` + 플러그인 `mega.jobs.register` 분(`collectRegistrations`, ADR-123).
+ * @param {string} projectRoot
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
+ * @returns {Promise<MegaJobWorker>}
+ */
+export function runWorkerHost(projectRoot: string, logger?: {
+    debug?: Function;
+    info?: Function;
+    warn?: Function;
+}): Promise<MegaJobWorker>;
+/**
+ * `mega scheduler` 호스트 골격 — config + 어댑터 connect + ctx + `MegaScheduler` 인스턴스 + graceful.
+ * @param {string} projectRoot
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
+ * @returns {Promise<MegaScheduler>}
+ */
+export function runSchedulerHost(projectRoot: string, logger?: {
+    debug?: Function;
+    info?: Function;
+    warn?: Function;
+}): Promise<MegaScheduler>;
+/**
+ * 마이그레이션 대상 DB 어댑터 해석 — `services.databases` 의 globalKey 로 조회한다. `--db <key>` 미지정
+ * 시 유일 선언 db, 그게 아니면 `primary`, 둘 다 아니면(다중·미선언) fail-fast 로 명시를 요구한다.
+ *
+ * 러너는 SQL `query` 기반이라(ADR-149 ⑥) `query` 도메인 메서드를 구현하지 않은 어댑터(mongodb 등
+ * Document DB)는 대상이 될 수 없다 — 베이스의 `adapter.not_implemented` 가 늦게 터지는 대신 여기서
+ * `migrate.unsupported_driver` 로 명시 fail-fast 한다(ADR-190).
+ *
+ * @param {Object} global - global config.
+ * @param {string} [dbKey] - `--db` 플래그.
+ * @returns {import('../adapters/mega-adapter.js').MegaAdapter}
+ */
+export function resolveMigrationAdapter(global: Object, dbKey?: string): import("../adapters/mega-adapter.js").MegaAdapter;
+/**
+ * `mega migrate` 일회성 호스트 — config 로드 → 플러그인 install → DB build/connect → 러너 실행 →
+ * disconnect. 워커/wsHub/메트릭은 띄우지 않는다(마이그레이션엔 불필요·이벤트루프 유지 회피).
+ * `MegaShutdown.now`(process.exit)를 쓰지 않고 직접 disconnect 해 반환값으로 결과를 돌려준다(테스트 가능).
+ *
+ * up/down 은 driver 별 마이그레이션 락({@link module:core/migration-lock}, ADR-190)으로 직렬화한다 —
+ * 동시 `mega migrate`(멀티 인스턴스 배포 훅)의 중복 적용 방지. status 는 읽기 전용이라 락 없이 실행.
+ *
+ * @param {string} projectRoot
+ * @param {{ direction?: 'up'|'down'|'status', dbKey?: string, logger?: { debug?: Function, info?: Function, warn?: Function }, out?: (msg: string) => void }} [opts]
+ * @returns {Promise<{ applied: string[] } | { rolledBack: string|null } | { applied: string[], pending: string[], modified: string[] }>}
+ */
+export function runMigrateHost(projectRoot: string, { direction, dbKey, logger, out }?: {
+    direction?: "up" | "down" | "status";
+    dbKey?: string;
+    logger?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+    out?: (msg: string) => void;
+}): Promise<{
+    applied: string[];
+} | {
+    rolledBack: string | null;
+} | {
+    applied: string[];
+    pending: string[];
+    modified: string[];
+}>;
+/** 빌트인 명령 이름·별칭 전체 — 이 표 밖의 첫 positional 은 플러그인 명령 dispatch 로 fallthrough 한다
+ * (ADR-123 계약 유지). `buildProgram` 의 commander 등록과 동기를 유지할 것. */
+export const BUILTIN_COMMANDS: Set<string>;
+/** CLI 사용법 텍스트 — commander 자동 생성(ADR-195) + 플러그인 명령 안내. 명령·옵션 정의가 곧 도움말의
+ * 단일 정본이라 수기 USAGE 와의 드리프트가 없다. */
+export const USAGE: string;
+import { MegaJobWorker } from '../lib/mega-job-worker.js';
+import { MegaScheduler } from '../lib/mega-schedule.js';

package/types/cli/template-engine.d.ts

@@ -0,0 +1,40 @@
+/**
+ * zero-dep 템플릿 엔진 + 이름 변형 유틸 (ADR-142).
+ *
+ * `templates/<kind>/*.tpl` 파일의 `{{token}}` 자리를 vars 로 치환한다. 외부 템플릿 dep(handlebars 등)
+ * 없이 `process.argv` 파싱(ADR-123)과 같은 정책으로 단순 토큰 치환만 한다 — generator 가 만드는 코드는
+ * 정적 골격이라 조건/루프 같은 복잡한 템플릿 기능이 필요 없다.
+ *
+ * 토큰 형식은 `{{word}}`(이중 중괄호)라 생성 코드의 JSDoc `@param {string}`·객체 리터럴 `{ x }`
+ * (단일 중괄호)와 충돌하지 않는다. 미정의 토큰은 즉시 throw(silent 치환 누락 방지, P4).
+ *
+ * @module cli/template-engine
+ */
+/**
+ * 입력 이름을 단어 배열로 분해한다. camelCase 경계와 구분자(`-`, `_`, 공백, `.`)를 모두 단어 경계로
+ * 본다. 예: `'UserProfile'`/`'user-profile'`/`'user_profile'` → `['user','profile']`.
+ * @param {string} raw
+ * @returns {string[]}
+ */
+export function toWords(raw: string): string[];
+/**
+ * 입력 이름에서 표준 변형 4종을 만든다.
+ * @param {string} raw
+ * @returns {{ kebab: string, pascal: string, camel: string, snake: string, words: string[] }}
+ * @throws {Error} 영숫자 단어가 하나도 없으면(빈/특수문자만) fail-fast.
+ */
+export function nameVariants(raw: string): {
+    kebab: string;
+    pascal: string;
+    camel: string;
+    snake: string;
+    words: string[];
+};
+/**
+ * 템플릿 문자열의 `{{token}}` 을 vars 값으로 치환한다.
+ * @param {string} tpl - 템플릿 본문.
+ * @param {Record<string, string>} vars - 토큰 → 값.
+ * @returns {string}
+ * @throws {Error} 템플릿에 vars 에 없는 토큰이 있으면(오타·누락 방지).
+ */
+export function renderTemplate(tpl: string, vars: Record<string, string>): string;

package/types/core/ajv-mapper.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Fastify 가 던진 AJV 검증 에러 객체 → MegaValidationError 로 매핑.
+ *
+ * Fastify 의 AJV 에러는 `err.validation: AjvErrorObject[]` + `err.validationContext: string`
+ * 형태. AjvErrorObject 는 { instancePath, schemaPath, keyword, message, params } 가짐.
+ *
+ * envelope details 형식 (ADR-075 배열):
+ *   [{ field: string, rule: string, value?: any, message: string }, ...]
+ *
+ * @param {Error & { validation?: any[], validationContext?: string }} err
+ * @returns {MegaValidationError | null}
+ *   AJV 에러가 아니면 null (호출자가 그대로 throw).
+ */
+export function ajvErrorToValidationError(err: Error & {
+    validation?: any[];
+    validationContext?: string;
+}): MegaValidationError | null;
+/**
+ * envelope `details` 배열 상한 (ADR-193 — allErrors DoS 방어의 응답측 bound).
+ *
+ * allErrors:true 는 위반을 전수 수집하므로(@fastify/ajv-compiler 디폴트가 allErrors:false 인 이유 =
+ * DoS 가능성 명시) 악의적 페이로드가 수천 개 위반을 만들 수 있다. 입력측은 Fastify bodyLimit
+ * (기본 1 MiB)이 막고, 응답·로그측은 이 cap 이 막는다 — 초과분은 잘라내되 silent 가 아니라
+ * `rule:'truncated'` 합성 항목으로 생략 개수를 명시한다.
+ */
+export const MAX_VALIDATION_DETAILS: 20;
+import { MegaValidationError } from '../errors/http-errors.js';

package/types/core/boot.d.ts

@@ -0,0 +1,233 @@
+/**
+ * boot/CLI 컨텍스트 — `db/cache/bus/lock` 을 글로벌 키로 직접 조회하고, `workers` 는 `static name` 으로
+ * lookup 한다(앱 별명 변환 없음 — 둘 다 글로벌 자원). worker/scheduler CLI 도 같은 형태를 재사용한다
+ * (잡/스케줄의 `static bus`/`static lock` = 글로벌 키; 잡이 CPU 작업을 `ctx.workers` 로 오프로드 가능).
+ * @param {Object} global - global config.
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
+ * @returns {BootContext}
+ */
+export function buildBootContext(global: Object, logger?: {
+    debug?: Function;
+    info?: Function;
+    warn?: Function;
+}): BootContext;
+/**
+ * 공유 어댑터 전수의 `healthCheck()` 를 `MegaHealth` 에 `<domain>:<globalKey>` 이름으로 등록한다.
+ * `/health/ready` 가 어댑터 생사를 실제로 반영하게 하는 배선 — `prepareRuntime` 이 connect 직후
+ * 호출한다(`health.autoChecks:false` 옵트아웃). 등록은 이름 기준 덮어쓰기라 재부팅(테스트)에도 멱등.
+ *
+ * @param {Array<{ domain: string, key: string, adapter: { healthCheck: () => Promise<{ ok: boolean }> } }>} [entries] -
+ *   대상 어댑터 엔트리(기본: 어댑터 매니저의 전체 등록분). 테스트 주입용.
+ * @returns {string[]} 등록한 체크 이름 목록.
+ */
+export function registerAdapterHealthChecks(entries?: Array<{
+    domain: string;
+    key: string;
+    adapter: {
+        healthCheck: () => Promise<{
+            ok: boolean;
+        }>;
+    };
+}>): string[];
+/**
+ * 부트 step 정의 — 부팅 시퀀스의 한 단계.
+ * @typedef {Object} BootStep
+ * @property {string} name - step 이름(로그·prerequisite 에러 식별자).
+ * @property {string[]} [needs] - 선행 step 이 state 에 만들어 둬야 하는 키(prerequisite). 누락 시
+ *   `boot.step_prerequisite` throw — step 순서 변경·누락 같은 배선 실수를 즉시 드러낸다.
+ * @property {'abort'|'warn'} [onFail] - 실패 정책. `'abort'`(기본) = fail-fast throw(M-1 정리 경로),
+ *   `'warn'` = best-effort(warn 로그 후 다음 step 계속 — 부팅을 막으면 안 되는 부가 단계용).
+ * @property {(state: Record<string, any>) => Promise<void>|void} run - 단계 본체. 산출물은 state 에 쓴다.
+ */
+/**
+ * step 배열 실행기 — 각 step 의 prerequisite 검증 → 실행 → 길목 debug 로그(start/done/tookMs).
+ * 실패는 step 의 `onFail` 정책을 따른다(기본 abort — 현재 부트 시퀀스 전 단계가 fail-fast).
+ *
+ * @param {BootStep[]} steps - 실행할 step 정의(순서 = 시퀀스 정본).
+ * @param {Record<string, any>} state - step 간 공유 상태(산출물 버스).
+ * @param {{ debug?: Function, warn?: Function }} [logger]
+ * @returns {Promise<void>}
+ * @throws {MegaConfigError} prerequisite 누락(`boot.step_prerequisite`) — 배선 오류는 즉시 abort.
+ */
+export function runBootSteps(steps: BootStep[], state: Record<string, any>, logger?: {
+    debug?: Function;
+    warn?: Function;
+}): Promise<void>;
+/**
+ * 런타임 공통 준비 — {@link PREPARE_STEPS}(config → plugins → adapters → health-auto-checks →
+ * metrics → tracing → workers → ws-hub → boot-context)를 {@link runBootSteps} 로 실행한다.
+ * `bootApp`(서버)·`mega worker`/`mega scheduler`(CLI 호스트)가 **같은 순서**를 공유한다.
+ *
+ * @param {string} projectRoot
+ * @param {{ ping?: boolean, logger?: { debug?: Function, info?: Function, warn?: Function } }} [opts]
+ * @returns {Promise<{ global: Object, apps: Array<{ name: string, config: Object }>, host: MegaPluginHost, ctx: BootContext, wsHub: (MegaWsHub | null) }>}
+ */
+export function prepareRuntime(projectRoot: string, { ping, logger }?: {
+    ping?: boolean;
+    logger?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+}): Promise<{
+    global: Object;
+    apps: Array<{
+        name: string;
+        config: Object;
+    }>;
+    host: MegaPluginHost;
+    ctx: BootContext;
+    wsHub: (MegaWsHub | null);
+}>;
+/**
+ * `global.server` 의 운영 옵션을 각 앱 Fastify 인스턴스 옵션으로 매핑한다(ADR-181, 04-data-models
+ * §MegaServerConfig). 미지정 키는 생략해 Fastify 기본값을 따른다. boot 가 모든 MegaApp 에 동일 주입한다
+ * (port/host 는 MegaServer.listen 이, 아래 런타임 옵션은 Fastify 인스턴스가 소비).
+ *   - trustProxy / trustedProxies → Fastify `trustProxy`(프록시/LB 뒤 req.ip·X-Forwarded-* 신뢰).
+ *     trustedProxies(목록)가 있으면 그것을, 없으면 trustProxy(boolean/number/string)를 그대로 넘긴다.
+ *   - timeouts.requestMs → Fastify `requestTimeout`(요청 수신 제한, slow-loris 보호).
+ *   - keepAliveMs       → Fastify `keepAliveTimeout`(keep-alive 소켓 idle 제한, ALB 정합).
+ *
+ * 프로덕션(`NODE_ENV==='production'`)에서 trustProxy/trustedProxies 미설정이면 **부팅 warn 1회**(ADR-186).
+ * 프록시/LB 뒤에서 미설정 시 `req.protocol`/`req.ip` 가 프록시 기준으로 잡혀 secure 쿠키 누락·rate-limit
+ * 키 왜곡·CSRF Origin 오판으로 번진다 — 직접 listen 배포면 무시해도 되는 안내성 경고다.
+ *
+ * @param {any} server - `global.server` config(없으면 빈 객체).
+ * @param {{ logger?: { warn?: Function }, env?: Record<string, string|undefined> }} [opts] - warn 출력용
+ *   logger 와 환경(테스트 주입용, 기본 `process.env`).
+ * @returns {{ trustProxy?: any, requestTimeout?: number, keepAliveTimeout?: number }}
+ */
+export function serverFastifyOptions(server: any, { logger, env }?: {
+    logger?: {
+        warn?: Function;
+    };
+    env?: Record<string, string | undefined>;
+}): {
+    trustProxy?: any;
+    requestTimeout?: number;
+    keepAliveTimeout?: number;
+};
+/**
+ * 프로젝트를 부팅한다 — {@link BOOT_STEPS}(runtime → before-boot-hook → logger → server → apps →
+ * cluster-transport → listen → after-boot-hook → shutdown-bridge)를 {@link runBootSteps} 로 실행한다.
+ *
+ * 어느 step 이든 실패하면 그대로 throw(fail-fast, 전 step onFail='abort'). 어댑터 connect 실패는
+ * 매니저가 LIFO cleanup 하고, 그 외 단계 실패(예: server.listen EADDRINUSE, beforeBoot hook throw)는
+ * 어댑터가 이미 connect 돼 `'adapters:disconnect'` MegaShutdown hook 이 등록된 상태라, 호출자가
+ * `MegaShutdown.now` 로 그 hook 을 실행해 정리해야 한다 — `bin/mega.js` 의 catch 가 이 정리 경로를
+ * 배선한다(M-1). 그러지 않으면 연결된 어댑터가 이벤트루프를 살려 프로세스가 hang 한다.
+ *
+ * @param {string} projectRoot - 프로젝트 루트 절대 경로(mega.config.js 가 있는 곳).
+ * @param {Object} [opts]
+ * @param {boolean} [opts.listen=true] - false 면 mount 까지만(테스트·검증용).
+ * @param {number} [opts.port] - listen 포트(미지정 시 server/global 기본).
+ * @param {string} [opts.host] - listen 호스트.
+ * @param {boolean} [opts.ping=false] - connectAll 시 healthCheck 까지 검증.
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [opts.logger] - 길목 debug 로그(선택).
+ * @returns {Promise<BootResult>}
+ */
+export function bootApp(projectRoot: string, { listen, port, host: listenHost, ping, logger }?: {
+    listen?: boolean;
+    port?: number;
+    host?: string;
+    ping?: boolean;
+    logger?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+}): Promise<BootResult>;
+/** prepareRuntime step 이름 시퀀스(정본) — introspection·테스트용. */
+export const PREPARE_STEP_NAMES: readonly string[];
+/** bootApp step 이름 시퀀스(정본) — introspection·테스트용. */
+export const BOOT_STEP_NAMES: readonly string[];
+/**
+ * 부팅 결과 핸들.
+ */
+export type BootResult = {
+    /**
+     * - mount 된 MegaServer(listen=false 면 미-listen 상태).
+     */
+    server: MegaServer;
+    /**
+     * - 플러그인 호스트(install 완료, queryable).
+     */
+    host: MegaPluginHost;
+    /**
+     * - mega.config.js default export(global).
+     */
+    config: Object;
+    /**
+     * - 로드된 앱 config 목록.
+     */
+    apps: Array<{
+        name: string;
+        config: Object;
+    }>;
+    /**
+     * - 생성된 MegaApp 인스턴스(등록 순서).
+     */
+    megaApps: MegaApp[];
+    /**
+     * - lifecycle hook 에 넘긴 boot context.
+     */
+    ctx: BootContext;
+    /**
+     * - embedded wsHub(ADR-137, `wsHub.enabled` OFF 면 null).
+     */
+    wsHub: import("../lib/ws-hub.js").MegaWsHub | null;
+    /**
+     * - 공유 pino 로거(ADR-141, logger 비활성이면 null). CLI 시작 메시지 등에 재사용.
+     */
+    appLogger: import("pino").Logger | null;
+};
+/**
+ * lifecycle hook(beforeBoot/afterBoot/beforeShutdown)이 받는 boot context (L-2/ADR-123).
+ * `db/cache/bus/lock` 은 **글로벌 키 직접 lookup**(앱 별명 변환 없음 — boot 레벨은 별명 스코프 밖).
+ */
+export type BootContext = {
+    /**
+     * - global config.
+     */
+    config: Object;
+    log?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+    db: (globalKey: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+    cache: (globalKey: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+    bus: (globalKey: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+    lock: (globalKey: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+    /**
+     * - `ctx.workers.<name>.run(task)` (ADR-124).
+     */
+    workers: Record<string, import("../lib/mega-worker.js").MegaWorker>;
+};
+/**
+ * 부트 step 정의 — 부팅 시퀀스의 한 단계.
+ */
+export type BootStep = {
+    /**
+     * - step 이름(로그·prerequisite 에러 식별자).
+     */
+    name: string;
+    /**
+     * - 선행 step 이 state 에 만들어 둬야 하는 키(prerequisite). 누락 시
+     * `boot.step_prerequisite` throw — step 순서 변경·누락 같은 배선 실수를 즉시 드러낸다.
+     */
+    needs?: string[];
+    /**
+     * - 실패 정책. `'abort'`(기본) = fail-fast throw(M-1 정리 경로),
+     * `'warn'` = best-effort(warn 로그 후 다음 step 계속 — 부팅을 막으면 안 되는 부가 단계용).
+     */
+    onFail?: "abort" | "warn";
+    /**
+     * - 단계 본체. 산출물은 state 에 쓴다.
+     */
+    run: (state: Record<string, any>) => Promise<void> | void;
+};
+import { MegaPluginHost } from '../lib/mega-plugin.js';
+import { MegaWsHub } from '../lib/ws-hub.js';
+import { MegaServer } from './mega-server.js';
+import { MegaApp } from './mega-app.js';