mega-framework 0.1.6 → 0.1.8

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

@@ -0,0 +1,122 @@
+/**
+ * @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[];
+/**
+ * 다음 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: string, extraNumbers?: number[]): number;
+/**
+ * 계획된 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", "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: 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,234 @@
+/**
+ * 프로젝트 루트의 `.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` supervisor 의 **자식 인자**를 빌드한다 (ADR-220, ADR-182 개정).
+ *
+ * - `--watch`/`--watch-ignore`(값 포함)는 부모(supervisor) 전용 — 자식 인자에서 제거한다
+ *   (가드 env 와 이중 안전으로 무한재귀 방지).
+ * - **단일 프로세스 강제**(`--cluster 1`) — 멀티워커 watch 카오스 방지(기존 `--cluster` 값은 무시).
+ *
+ * @param {string[]} argv - 원본 mega argv(예: `['start','--watch','--port','3000']`).
+ * @returns {string[]} 자식 `mega` 인자(예: `['start','--port','3000','--cluster','1']`).
+ */
+export function buildWatchChildArgs(argv: string[]): 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<import('../lib/mega-job-worker.js').MegaJobWorker>}
+ */
+export function runWorkerHost(projectRoot: string, logger?: {
+    debug?: Function;
+    info?: Function;
+    warn?: Function;
+}): Promise<import("../lib/mega-job-worker.js").MegaJobWorker>;
+/**
+ * `mega scheduler` 호스트 골격 — config + 어댑터 connect + ctx + `MegaScheduler` 인스턴스 + graceful.
+ * @param {string} projectRoot
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
+ * @returns {Promise<import('../lib/mega-schedule.js').MegaScheduler>}
+ */
+export function runSchedulerHost(projectRoot: string, logger?: {
+    debug?: Function;
+    info?: Function;
+    warn?: Function;
+}): Promise<import("../lib/mega-schedule.js").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;

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/cli/watch.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 미니 glob → RegExp. 지원: 더블스타+슬래시(0개 이상의 디렉토리), 더블스타(경로 전체), `*`(세그먼트
+ * 내), `?`(1글자). 그 외 문자는 리터럴(정규식 특수문자 escape). 매칭 대상은 루트 상대 POSIX 경로
+ * 전체(^…$). 패턴 예시는 스캐폴드 `.env` 의 `WATCH_IGNORE` 참조 — JS 블록 주석 안에는
+ * 더블스타+슬래시 시퀀스를 쓸 수 없어(주석 조기 종료) 여기 직접 못 적는다.
+ *
+ * @param {string} pattern - glob 패턴(예 `.env.*`).
+ * @returns {RegExp}
+ */
+export function globToRegExp(pattern: string): RegExp;
+/**
+ * ignore 패턴 합성 — config(`watch.ignore`) + CLI(`--watch-ignore a,b`). 숨은 디폴트 없음(모듈
+ * docstring 참조). 잘못된 모양은 fail-fast(silent 무시 금지).
+ *
+ * @param {{ ignore?: unknown }} [watchConfig] - mega.config.js 의 `watch`.
+ * @param {string | undefined} [cliIgnore] - `--watch-ignore` 값(콤마 구분).
+ * @returns {string[]}
+ * @throws {TypeError} config `watch.ignore` 가 문자열 배열이 아닐 때.
+ */
+export function mergeWatchIgnore(watchConfig?: {
+    ignore?: unknown;
+}, cliIgnore?: string | undefined): string[];
+/**
+ * 루트 상대 경로가 ignore 에 걸리는지 (Boolean — `is*`).
+ * @param {string} rel - 루트 상대 POSIX 경로(예 `apps/main/locales/ko.json`).
+ * @param {RegExp[]} regexps - {@link globToRegExp} 컴파일 결과.
+ * @returns {boolean}
+ */
+export function isIgnoredPath(rel: string, regexps: RegExp[]): boolean;
+/**
+ * watch supervisor — 감시 경로의 변경(ignore 통과분)을 debounce 후 자식(`mega start`)을
+ * SIGTERM → respawn 한다. 자식이 스스로 죽으면(crash) 재시작하지 않고 다음 변경을 기다린다
+ * (crash-loop 방지 — nodemon 의 "app crashed - waiting for file changes" 와 동형).
+ *
+ * @param {object} o
+ * @param {string} o.projectRoot
+ * @param {string[]} o.watchPaths - 감시할 절대경로(존재하는 것만 — 호출측이 필터).
+ * @param {string[]} o.ignore - glob 패턴 목록.
+ * @param {() => import('node:child_process').ChildProcess} o.spawnChild - 자식 기동 팩토리(주입 — 테스트).
+ * @param {(msg: string) => void} o.out
+ * @param {number} [o.debounceMs=500] - 연속 변경 디바운스.
+ * @param {(dir: string, opts: object, cb: (event: string, filename: string | Buffer | null) => void) => { close(): void }} [o.watchFn] -
+ *   fs.watch 주입(테스트). 기본 node:fs watch.
+ * @returns {Promise<number>} 부모(supervisor)의 exit code — SIGINT/SIGTERM 수신 시 자식 정리 후 0.
+ */
+export function startWatchSupervisor({ projectRoot, watchPaths, ignore, spawnChild, out, debounceMs, watchFn }: {
+    projectRoot: string;
+    watchPaths: string[];
+    ignore: string[];
+    spawnChild: () => import("node:child_process").ChildProcess;
+    out: (msg: string) => void;
+    debounceMs?: number;
+    watchFn?: (dir: string, opts: object, cb: (event: string, filename: string | Buffer | null) => void) => {
+        close(): void;
+    };
+}): Promise<number>;
+/** {@link startWatchSupervisor} 의 watchPaths 기본 집합 — 존재하는 것만.
+ * @param {string} projectRoot @returns {string[]} */
+export function defaultWatchPaths(projectRoot: 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';