mega-framework 0.1.5 → 0.1.7

package/types/core/migration/generate.d.ts

@@ -0,0 +1,56 @@
+/** 14자리 타임스탬프(UTC) — 러너 파일 규약({@link MIGRATION_FILE_RE})의 prefix. @param {Date} [d] @returns {string} */
+export function migrationTimestamp(d?: Date): string;
+/**
+ * `mega migrate:generate` 실행.
+ *
+ * @param {string} projectRoot
+ * @typedef {{
+ *   name?: string,
+ *   renames?: string,
+ *   dryRun?: boolean,
+ *   check?: boolean,
+ *   concurrent?: boolean,
+ *   allowDestroyDrops?: boolean,
+ *   adapter?: string,
+ *   app?: string,
+ *   out?: (msg: string) => void,
+ *   logger?: { debug?: Function, info?: Function, warn?: Function },
+ *   confirmRenames?: (candidates: Array<{ table: string, dropped: string[], added: string[] }>) => Promise<Record<string, Record<string, string>> | null>,
+ *   now?: () => Date,
+ * }} GenerateOpts
+ */
+/**
+ * @param {string} projectRoot
+ * @param {GenerateOpts} [opts]
+ * @returns {Promise<{ changed: boolean, files: string[], adapters: string[] }>}
+ */
+export function runMigrateGenerate(projectRoot: string, opts?: GenerateOpts): Promise<{
+    changed: boolean;
+    files: string[];
+    adapters: string[];
+}>;
+/**
+ * `mega migrate:generate` 실행.
+ */
+export type GenerateOpts = {
+    name?: string;
+    renames?: string;
+    dryRun?: boolean;
+    check?: boolean;
+    concurrent?: boolean;
+    allowDestroyDrops?: boolean;
+    adapter?: string;
+    app?: string;
+    out?: (msg: string) => void;
+    logger?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+    confirmRenames?: (candidates: Array<{
+        table: string;
+        dropped: string[];
+        added: string[];
+    }>) => Promise<Record<string, Record<string, string>> | null>;
+    now?: () => Date;
+};

package/types/core/migration/journal.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @typedef {{ version: number, generatedAt: string | null, adapters: Record<string, { driver: string, models: Array<{ name: string, table: string, record: any }> }> }} Snapshot
+ */
+/** 빈 스냅샷(첫 generate — 모든 모델이 신규로 diff 됨). @returns {Snapshot} */
+export function emptySnapshot(): Snapshot;
+/**
+ * snapshot.json 로드. 부재 시 빈 스냅샷(정상 — 첫 실행). 손상/버전 불일치는 fail-fast —
+ * 잘못된 기준으로 diff 하면 파괴적 SQL 이 잘못 생성된다(P7).
+ *
+ * @param {string} projectRoot
+ * @returns {Snapshot}
+ * @throws {MegaConfigError} `migration.journal_corrupt` | `migration.journal_version`
+ */
+export function readSnapshot(projectRoot: string): Snapshot;
+/**
+ * snapshot.json 기록(+디렉토리 생성). 모델은 이름순 정렬해 직렬화 — diff 노이즈 없는 결정적 출력.
+ * @param {string} projectRoot @param {Snapshot} snapshot
+ * @returns {string} 기록한 파일 경로.
+ */
+export function writeSnapshot(projectRoot: string, snapshot: Snapshot): string;
+/**
+ * generate 락 획득 — snapshot 읽기→쓰기 구간(프롬프트 대기 포함)이 길어 동시 generate 가
+ * 한쪽 갱신을 유실시킬 수 있다(CI 병렬 잡 등). `wx` 플래그(존재 시 실패)가 원자적 선점.
+ *
+ * @param {string} projectRoot
+ * @returns {() => void} 해제 함수(finally 에서 호출).
+ * @throws {MegaConfigError} `migration.generate_locked` - 다른 generate 진행 중(또는 stale lock).
+ */
+export function acquireGenerateLock(projectRoot: string): () => void;
+/**
+ * history 스냅샷 보존 — 마이그레이션 파일과 같은 base 이름의 .json.
+ * @param {string} projectRoot @param {string} baseName - `<ts>-<slug>` (확장자 없이).
+ * @param {Snapshot} snapshot
+ * @returns {string} 기록한 파일 경로.
+ */
+export function appendHistory(projectRoot: string, baseName: string, snapshot: Snapshot): string;
+/** journal 디렉토리 (projectRoot 상대). */
+export const JOURNAL_DIR: string;
+/** snapshot 포맷 버전 — 포맷 변경 시 증가(하위 포맷은 마이그레이션 가이드와 함께 거부). */
+export const SNAPSHOT_VERSION: 1;
+export type Snapshot = {
+    version: number;
+    generatedAt: string | null;
+    adapters: Record<string, {
+        driver: string;
+        models: Array<{
+            name: string;
+            table: string;
+            record: any;
+        }>;
+    }>;
+};

package/types/core/migration/model-scan.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 모든 앱의 models 폴더를 스캔해 schema 모델을 수집한다.
+ *
+ * @param {{ projectRoot: string, appNames: string[] }} opts
+ * @returns {Promise<ScannedModel[]>}
+ * @throws {MegaConfigError} `migration.model_load_failed` - 모델 파일 import 실패(문법 오류 등).
+ */
+export function scanSchemaModels({ projectRoot, appNames }: {
+    projectRoot: string;
+    appNames: string[];
+}): Promise<ScannedModel[]>;
+export type ScannedModel = {
+    name: string;
+    table: string;
+    adapter: string;
+    app: string;
+    file: string;
+    Model: any;
+};

package/types/core/migration/mongo-migration-db.d.ts

@@ -0,0 +1,7 @@
+/**
+ * native `Db` → 러너/마이그레이션 파일 공용 db 셈.
+ *
+ * @param {import('mongodb').Db} nativeDb - 연결된 mongodb `Db` (adapter.native).
+ * @returns {any} Proxy — `query(sql)` 은 부기 SQL 번역, 그 외는 native `Db` 위임.
+ */
+export function createMongoMigrationDb(nativeDb: import("mongodb").Db): any;

package/types/core/migration/schema-builder.d.ts

@@ -0,0 +1,197 @@
+/**
+ * 모델 클래스(또는 동형 객체)의 `static schema`/`static indexes` 를 실행해 record 를 만든다.
+ * 모델 식별은 duck-typing — `schema` 함수 + `table`/`adapter` 문자열(클래스 identity 비의존,
+ * 패키지 사본이 달라도 동작). 검증은 {@link module:core/migration/schema-validator} 가 별도 수행.
+ *
+ * @param {{ name?: string, table?: string, adapter?: string, schema?: Function, indexes?: Function }} Model
+ * @returns {{ table: string, adapter: string, columns: Record<string, any>, primaryKey?: string[], indexes: any[], validation?: any }}
+ * @throws {MegaConfigError} `migration.schema_invalid` - table/adapter 누락, schema 반환 형태 오류.
+ */
+export function buildModelRecord(Model: {
+    name?: string;
+    table?: string;
+    adapter?: string;
+    schema?: Function;
+    indexes?: Function;
+}): {
+    table: string;
+    adapter: string;
+    columns: Record<string, any>;
+    primaryKey?: string[];
+    indexes: any[];
+    validation?: any;
+};
+/** FK onDelete/onUpdate 허용 동작 (PostgreSQL 참조 동작 5종). */
+export const FK_ACTIONS: string[];
+/**
+ * 컬럼 정의 체인 빌더 — 타입 메서드(`t.<type>()`)가 만들고, 제약 메서드를 체인한다.
+ * 최종 직렬화는 {@link ColumnBuilder#build} 가 수행한다(플레인 객체 반환).
+ */
+export class ColumnBuilder {
+    /** @param {Record<string, any>} def - 타입 메서드가 만든 초기 정의(`{ type, ... }`). */
+    constructor(def: Record<string, any>);
+    /** PRIMARY KEY 지정(단일 컬럼). 복합 PK 는 `t.primary([cols])` 사용. @returns {this} */
+    primary(): this;
+    /** NOT NULL 지정. @returns {this} */
+    notNull(): this;
+    /**
+     * 명시 null 허용(ADR-210) — SQL 에선 nullable 이 기본이라 no-op(선언적 표시)이고, mongo 에선
+     * `bsonType: ['<type>', 'null']` 유니온으로 렌더된다(미선언 시 mongo 는 필드 **생략만** 허용 —
+     * 명시 null 은 121 거부, 실측). `.notNull()` 과 동시 사용 불가.
+     * @returns {this}
+     */
+    nullable(): this;
+    /**
+     * UNIQUE 제약. 이름 미지정 시 dialect 명명 표준(`uniq_<table>_<col>`)을 따른다.
+     * @param {{ name?: string }} [opts]
+     * @returns {this}
+     */
+    unique(opts?: {
+        name?: string;
+    }): this;
+    /**
+     * DEFAULT 값. literal(string/number/boolean/null) 또는 `{ raw: 'expr' }`(raw SQL 식).
+     * @param {string | number | boolean | null | { raw: string }} value
+     * @returns {this}
+     */
+    default(value: string | number | boolean | null | {
+        raw: string;
+    }): this;
+    /** `DEFAULT CURRENT_TIMESTAMP` 단축. @returns {this} */
+    defaultNow(): this;
+    /**
+     * CHECK 제약. 이름 미지정 시 `chk_<table>_<col>`.
+     * @param {string} expr - CHECK 식(raw SQL).
+     * @param {{ name?: string }} [opts]
+     * @returns {this}
+     */
+    check(expr: string, opts?: {
+        name?: string;
+    }): this;
+    /**
+     * FK 참조. 대상은 **모델 이름**(file-scan 결과의 클래스 이름)과 그 컬럼 — 실제 테이블명은
+     * 스냅샷 구성 시 해석된다.
+     * @param {string} modelName - 대상 모델 이름(예: 'Organization').
+     * @param {string} columnName - 대상 컬럼 이름(예: 'id').
+     * @param {{ onDelete?: string, onUpdate?: string, name?: string }} [opts]
+     * @returns {this}
+     */
+    references(modelName: string, columnName: string, opts?: {
+        onDelete?: string;
+        onUpdate?: string;
+        name?: string;
+    }): this;
+    /** 컬럼 코멘트(`COMMENT ON COLUMN`). @param {string} text @returns {this} */
+    comment(text: string): this;
+    /** 직렬화 — 누적 정의의 플레인 사본 반환. @returns {Record<string, any>} */
+    build(): Record<string, any>;
+    #private;
+}
+/**
+ * 테이블 스키마 빌더 — `schema(t)`/`indexes(t)` 콜백이 받는 `t`.
+ * 타입 메서드는 {@link ColumnBuilder} 를, `index()` 는 IndexDef 를 반환한다.
+ * `primary([cols])` 는 복합 PK 를 빌더 내부 상태에 기록한다.
+ */
+export class SchemaBuilder {
+    /** @type {string[] | undefined} 복합 PRIMARY KEY 컬럼 목록 (`t.primary([...])`). */
+    compositePrimaryKey: string[] | undefined;
+    /** 자동증가 INT (postgres SERIAL). @returns {ColumnBuilder} */
+    serial(): ColumnBuilder;
+    /** 자동증가 BIGINT (postgres BIGSERIAL). @returns {ColumnBuilder} */
+    bigSerial(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    integer(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    bigInteger(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    smallInteger(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    real(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    doublePrecision(): ColumnBuilder;
+    /**
+     * 고정 정밀 십진수 (postgres NUMERIC).
+     * @param {number} precision @param {number} scale @returns {ColumnBuilder}
+     */
+    decimal(precision: number, scale: number): ColumnBuilder;
+    /** @param {number} maxLength @returns {ColumnBuilder} */
+    varchar(maxLength: number): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    text(): ColumnBuilder;
+    /** @param {number} length @returns {ColumnBuilder} */
+    char(length: number): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    boolean(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    timestamp(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    timestamptz(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    date(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    time(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    uuid(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    json(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    jsonb(): ColumnBuilder;
+    /** @returns {ColumnBuilder} */
+    bytea(): ColumnBuilder;
+    /**
+     * MongoDB ObjectId (mongo 전용 — SQL dialect 는 렌더 시점에 거부). `_id` 는 생략해도 자동이며,
+     * 명시 선언은 `_id: t.objectId().primary()` 형태만 허용된다(ADR-209).
+     * @returns {ColumnBuilder}
+     */
+    objectId(): ColumnBuilder;
+    /**
+     * 중첩 도큐먼트(embedded object — mongo 전용). shape 미지정 시 자유형 object.
+     * 중첩 필드의 제약은 타입·길이·enum·notNull(→required)만 — unique/primary/references/check 는
+     * 최상위 전용이다(mongo dialect 가 렌더 시점에 거부).
+     * @param {Record<string, ColumnBuilder>} [shape] - { 필드명: t.<type>()… }.
+     * @returns {ColumnBuilder}
+     * @throws {MegaConfigError} shape 값이 빌더가 아닐 때.
+     */
+    object(shape?: Record<string, ColumnBuilder>): ColumnBuilder;
+    /**
+     * 배열(mongo 전용). items 미지정 시 자유형 배열.
+     * @param {ColumnBuilder} [items] - 요소 타입(t.<type>()…).
+     * @param {{ uniqueItems?: boolean }} [opts]
+     * @returns {ColumnBuilder}
+     * @throws {MegaConfigError} items 가 빌더가 아닐 때.
+     */
+    array(items?: ColumnBuilder, opts?: {
+        uniqueItems?: boolean;
+    }): ColumnBuilder;
+    /**
+     * 열거형 — postgres 렌더는 `TEXT` + `CHECK (col IN (...))` (native enum 타입 미사용 —
+     * 값 추가/삭제가 제약 교체로 단순해짐).
+     * @param {string[]} values @param {{ name?: string }} [opts] - name: CHECK 제약 이름 override.
+     * @returns {ColumnBuilder}
+     */
+    enum(values: string[], opts?: {
+        name?: string;
+    }): ColumnBuilder;
+    /**
+     * 복합 PRIMARY KEY 선언 — schema 콜백 안에서 `t.primary(['a','b'])` 로 호출(반환값 없음,
+     * 컬럼 맵에는 넣지 않는다). 단일 PK 는 컬럼 체인 `.primary()` 사용.
+     * @param {string[]} columns
+     * @returns {void}
+     */
+    primary(columns: string[]): void;
+    /**
+     * 인덱스 정의 — `static indexes = (t) => [t.index(...)]` 에서 사용.
+     * @param {string | string[] | { expression: string }} columnsOrExpr - 컬럼(들) 또는 표현식 인덱스.
+     * @param {{ name?: string, unique?: boolean, where?: string, using?: string }} [opts]
+     * @returns {Record<string, any>} IndexDef.
+     */
+    index(columnsOrExpr: string | string[] | {
+        expression: string;
+    }, opts?: {
+        name?: string;
+        unique?: boolean;
+        where?: string;
+        using?: string;
+    }): Record<string, any>;
+    #private;
+}

package/types/core/migration/schema-validator.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 스캔된 모델 record 집합을 검증하고 FK 대상 테이블을 해석(in-place)한다.
+ *
+ * @param {Array<{ name: string, table: string, adapter: string, record: any, file?: string }>} models - 스캔 결과
+ *   (name = 모델 이름, file = 출처 파일 경로 — 충돌 메시지에 동반, record =
+ *   {@link module:core/migration/schema-builder.buildModelRecord} 산출).
+ * @param {{ identifierMaxBytesOf?: (adapter: string) => number }} [opts] - adapter 별 식별자 byte 한도
+ *   공급자(dialect.identifierMaxBytes — 합성 이름은 dialect 의 quoteIdent 깔때기가 추가 검증).
+ * @returns {void}
+ * @throws {MegaConfigError} `migration.schema_invalid` | `migration.identifier_too_long`
+ */
+export function validateModels(models: Array<{
+    name: string;
+    table: string;
+    adapter: string;
+    record: any;
+    file?: string;
+}>, { identifierMaxBytesOf }?: {
+    identifierMaxBytesOf?: (adapter: string) => number;
+}): void;

package/types/core/migration-lock.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @typedef {{ debug?: Function, info?: Function, warn?: Function }} LockLogger
+ */
+/**
+ * driver 별 마이그레이션 락 안에서 `fn` 을 실행한다. 락 획득/해제는 같은 고정 연결에서 수행하고,
+ * 해제 실패는 원본 결과/에러를 가리지 않는다(세션 락은 연결 반납·종료 시 서버가 자동 해제).
+ *
+ * @template T
+ * @param {import('../adapters/mega-adapter.js').MegaAdapter} adapter - 연결된 대상 DB 어댑터.
+ * @param {() => Promise<T>} fn - 락 보유 중 실행할 작업(마이그레이션 up/down).
+ * @param {{ logger?: LockLogger }} [opts]
+ * @returns {Promise<T>}
+ * @throws {MegaConfigError} `migrate.lock_timeout` - mariadb GET_LOCK 대기 한도 초과.
+ */
+export function withMigrationLock<T>(adapter: import("../adapters/mega-adapter.js").MegaAdapter, fn: () => Promise<T>, { logger }?: {
+    logger?: LockLogger;
+}): Promise<T>;
+/** postgres advisory lock 키 — 'mega' ASCII(0x6d656761). 프레임워크 고정값(임의 64-bit 앱 키). */
+export const PG_ADVISORY_LOCK_KEY: 1835362145;
+/** mariadb GET_LOCK 이름. */
+export const MARIA_LOCK_NAME: "mega_migrations";
+/** mariadb GET_LOCK 대기 한도(초) — 초과 시 `migrate.lock_timeout` fail-fast. */
+export const MARIA_LOCK_TIMEOUT_SEC: 60;
+/** mongodb 락 컬렉션 이름. */
+export const MONGO_LOCK_COLLECTION: "mega_migrations_lock";
+/** mongodb 락 대기 한도(ms)·폴링 간격(ms) — 한도 초과 시 `migrate.lock_timeout` fail-fast. */
+export const MONGO_LOCK_TIMEOUT_MS: 60000;
+export const MONGO_LOCK_POLL_MS: 500;
+export type LockLogger = {
+    debug?: Function;
+    info?: Function;
+    warn?: Function;
+};

package/types/core/migration-runner.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @typedef {{ query: (sql: string, params?: any[]) => Promise<any>, withTransaction?: (fn: () => Promise<any>) => Promise<any> }} MigrationDb
+ */
+/**
+ * @typedef {{ name: string, file: string, app: string, absPath: string }} MigrationFile
+ */
+/**
+ * 모든 앱의 `migrations/` 폴더를 스캔해 마이그레이션 파일 목록을 **타임스탬프(파일명 prefix) 오름차순**으로
+ * 반환한다. 형식(`MIGRATION_FILE_RE`)에 맞지 않는 파일·`*.test.js` 는 건너뛴다. 폴더 부재는 정상.
+ *
+ * @param {{ projectRoot: string, appNames: string[] }} opts
+ * @returns {MigrationFile[]}
+ */
+export function collectMigrationFiles({ projectRoot, appNames }: {
+    projectRoot: string;
+    appNames: string[];
+}): MigrationFile[];
+/**
+ * 마이그레이션 모듈 로드 + up/down 검증. `export const transaction = false`(옵트아웃, ADR-205)면
+ * 러너가 트랜잭션 래핑을 끈다 — `CREATE INDEX CONCURRENTLY` 처럼 트랜잭션 안에서 실행 불가한
+ * 문장을 위한 escape hatch(부분 실패 시 롤백 없음은 파일 작성자 책임 — 생성기가 헤더에 명시).
+ * @param {string} absPath
+ * @returns {Promise<{ up: Function, down: Function, useTransaction: boolean }>}
+ * @throws {MegaConfigError} import 실패 / up·down 누락.
+ */
+export function loadMigration(absPath: string): Promise<{
+    up: Function;
+    down: Function;
+    useTransaction: boolean;
+}>;
+/**
+ * 미적용(pending) 마이그레이션을 타임스탬프 순으로 모두 적용한다. 각 마이그레이션의 up + 이력 기록
+ * (sha-256 checksum 포함, ADR-190)을 한 트랜잭션으로 묶어 원자적으로 처리한다. 이미 적용된 파일이
+ * 적용 후 수정됐으면(checksum 불일치) 경고 로그를 남긴다 — 실행된 스키마와 파일이 어긋난 상태.
+ *
+ * @param {{ db: MigrationDb, projectRoot: string, appNames: string[], now?: () => string, log?: { info?: Function, warn?: Function, debug?: Function } }} opts
+ *   - now: 적용 시각 ISO 문자열 공급자(테스트 주입용, 기본 `new Date().toISOString()`).
+ * @returns {Promise<{ applied: string[] }>}
+ */
+export function migrateUp({ db, projectRoot, appNames, now, log }: {
+    db: MigrationDb;
+    projectRoot: string;
+    appNames: string[];
+    now?: () => string;
+    log?: {
+        info?: Function;
+        warn?: Function;
+        debug?: Function;
+    };
+}): Promise<{
+    applied: string[];
+}>;
+/**
+ * 가장 최근 적용된 마이그레이션 1개를 롤백한다(down + 이력 삭제, 한 트랜잭션). 적용분이 없으면 no-op.
+ *
+ * 이력상 최신 적용분의 **파일이 사라진 경우 fail-fast** 한다(`migration.history_file_missing`, ADR-190) —
+ * 조용히 건너뛰면 더 오래된 마이그레이션이 롤백되어(순서 역전) 이력과 실제 스키마가 어긋난다.
+ *
+ * @param {{ db: MigrationDb, projectRoot: string, appNames: string[], log?: { info?: Function, warn?: Function } }} opts
+ * @returns {Promise<{ rolledBack: string | null }>}
+ * @throws {MegaConfigError} `migration.history_file_missing` - 최신 적용 이력의 파일 부재.
+ */
+export function migrateDown({ db, projectRoot, appNames, log }: {
+    db: MigrationDb;
+    projectRoot: string;
+    appNames: string[];
+    log?: {
+        info?: Function;
+        warn?: Function;
+    };
+}): Promise<{
+    rolledBack: string | null;
+}>;
+/**
+ * 적용/미적용/드리프트(적용 후 수정) 마이그레이션 목록(타임스탬프 순, ADR-190).
+ * @param {{ db: MigrationDb, projectRoot: string, appNames: string[] }} opts
+ * @returns {Promise<{ applied: string[], pending: string[], modified: string[] }>}
+ */
+export function migrateStatus({ db, projectRoot, appNames }: {
+    db: MigrationDb;
+    projectRoot: string;
+    appNames: string[];
+}): Promise<{
+    applied: string[];
+    pending: string[];
+    modified: string[];
+}>;
+/** 적용 이력 테이블 이름. */
+export const MIGRATIONS_TABLE: "mega_migrations";
+/** 마이그레이션 파일명 형식 — `<YYYYMMDDHHmmss>-<kebab>.js`. generator(ADR-012)가 이 prefix 를 생성. */
+export const MIGRATION_FILE_RE: RegExp;
+export type MigrationDb = {
+    query: (sql: string, params?: any[]) => Promise<any>;
+    withTransaction?: (fn: () => Promise<any>) => Promise<any>;
+};
+export type MigrationFile = {
+    name: string;
+    file: string;
+    app: string;
+    absPath: string;
+};

package/types/core/multipart.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 업로드 자동 등록 결과 요약(디버그·테스트용).
+ * @typedef {Object} MultipartSummary
+ * @property {boolean} enabled - 등록 여부.
+ * @property {number} maxFileSize - 적용된 파일 크기 상한(bytes).
+ * @property {number|null} maxFiles - 파일 개수 상한(null=무제한).
+ * @property {string[]} allowedMimeTypes - 허용 MIME 목록(빈 배열=전부 허용).
+ */
+/**
+ * 파일명을 안전한 단일 파일명으로 살균한다 (path traversal 차단).
+ *
+ * `basename` 으로 디렉터리 성분(`../`, `/`, `\`)을 모두 제거하고, 남은 선행 점(`.`/`..`/`.bashrc` 류)과
+ * NUL·제어문자를 제거한다. 빈 문자열이 되면 `'upload'` 로 폴백한다 — 빈 파일명이 디렉터리로 해석되는 걸 막는다.
+ *
+ * @param {unknown} name - 클라가 보낸 원본 파일명(신뢰 불가).
+ * @returns {string} 디렉터리 성분 없는 안전한 파일명.
+ * @example sanitizeFilename('../../etc/passwd') // 'passwd'
+ * @example sanitizeFilename('..')               // 'upload'
+ */
+export function sanitizeFilename(name: unknown): string;
+/**
+ * 살균된 파일명에 타임스탬프+랜덤 접미를 붙여 저장 파일명을 유일화한다.
+ *
+ * 살균만으로는 **같은 이름의 동시/연속 업로드가 silent 덮어쓰기**된다(두 사용자가 'photo.jpg' 를 올리면
+ * 나중 것이 이김, 동시면 스트림 교차 가능). 저장 파일명에 `-<ts36>-<rand8hex>` 를 붙여 충돌을 막는다 —
+ * 반환 메타의 `filename`(표시명)은 살균 원본 그대로 유지하고 `savedAs`(실제 경로)만 유일명을 갖는다.
+ *
+ * @param {string} name - {@link sanitizeFilename} 을 통과한 파일명.
+ * @returns {string} 예: 'photo.jpg' → 'photo-mbz3k1x2-9f2ac01b.jpg'.
+ * @example uniquifyFilename('report.pdf') // 'report-<ts36>-<rand>.pdf'
+ */
+export function uniquifyFilename(name: string): string;
+/**
+ * MIME 타입이 화이트리스트에 허용되는지 (Boolean — `is*`). 빈 목록/미지정이면 **전부 허용**(게이트 비활성).
+ * 정확 매치 + `type/*` 와일드카드(예: `'image/*'` 는 `'image/png'` 허용)를 지원한다.
+ *
+ * @param {string} mimetype - 검사할 MIME(part header 선언값).
+ * @param {string[]} [allowedMimeTypes] - 허용 목록. 빈 배열/미지정 → 전부 허용.
+ * @returns {boolean}
+ */
+export function isMimeAllowed(mimetype: string, allowedMimeTypes?: string[]): boolean;
+/**
+ * Fastify 인스턴스에 `@fastify/multipart` 를 자동 등록하고 MIME 게이트·안전 저장·관측성을 배선한다.
+ *
+ * `upload` 가 없으면 **미등록**(옵트인) — multipart 요청은 Fastify 가 415(파서 없음)로 거부한다. session.js
+ * 패턴 정합. 호출 순서는 보안 플러그인 등록 이후·라우트 등록 이전 어디든 무방하다(글로벌 onRequest hook +
+ * request 데코레이터라 라우트 등록 순서와 무관).
+ *
+ * @param {import('fastify').FastifyInstance} fastify - 대상 앱 Fastify 인스턴스.
+ * @param {Object} opts
+ * @param {unknown} opts.upload - `MegaUploadConfig`(maxFileSize/maxFiles/allowedMimeTypes). falsy 면 미등록.
+ * @param {string} [opts.appName] - 앱 이름(메트릭 라벨·로그용).
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger] - 흐름 길목 debug 로그(선택).
+ * @returns {MultipartSummary}
+ */
+export function registerMultipart(fastify: import("fastify").FastifyInstance, { upload, appName, logger }?: {
+    upload: unknown;
+    appName?: string;
+    logger?: {
+        debug?: Function;
+        warn?: Function;
+    };
+}): MultipartSummary;
+/** 업로드 파일 크기 디폴트 상한 (10 MB — 02-architecture §1502). */
+export const DEFAULT_MAX_FILE_SIZE: number;
+/**
+ * 업로드 자동 등록 결과 요약(디버그·테스트용).
+ */
+export type MultipartSummary = {
+    /**
+     * - 등록 여부.
+     */
+    enabled: boolean;
+    /**
+     * - 적용된 파일 크기 상한(bytes).
+     */
+    maxFileSize: number;
+    /**
+     * - 파일 개수 상한(null=무제한).
+     */
+    maxFiles: number | null;
+    /**
+     * - 허용 MIME 목록(빈 배열=전부 허용).
+     */
+    allowedMimeTypes: string[];
+};

package/types/core/openapi.d.ts

@@ -0,0 +1,62 @@
+/**
+ * OpenAPI 자동 등록 결과 요약(디버그·테스트용).
+ * @typedef {Object} OpenapiSummary
+ * @property {boolean} enabled - 등록 여부.
+ * @property {string|null} path - swagger-ui 경로(미등록 시 null).
+ */
+/**
+ * `openapi` config 를 정규화한다. `enabled !== true` 면 `null`(미옵트인).
+ *
+ * @param {unknown} openapi - `MegaOpenApiAppConfig`.
+ * @param {string} [appName] - info.title 디폴트용.
+ * @returns {{ path: string, info: { title: string, version: string, description?: string }, auth: Function[], theme: Object } | null}
+ */
+export function normalizeOpenapi(openapi: unknown, appName?: string): {
+    path: string;
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    auth: Function[];
+    theme: Object;
+} | null;
+/**
+ * Fastify 인스턴스에 OpenAPI 명세 수집기 + swagger-ui 를 옵트인 등록한다.
+ *
+ * `openapi.enabled !== true` 면 **미등록**. `@fastify/swagger` 는 **라우트 등록보다 먼저** 등록돼야 onRoute 로
+ * 스키마를 수집하므로 `MegaApp` 생성자(3g, 보안·정적 자산 뒤·`/health` 앞)에서 호출한다. 멀티앱은 각자 Fastify
+ * 인스턴스라 docs 경로 충돌 없음(같은 앱 안에서 `path` 가 사용자 라우트와 겹치면 Fastify 가 중복 라우트로 부팅 throw).
+ *
+ * @param {import('fastify').FastifyInstance} fastify - 대상 앱 Fastify 인스턴스.
+ * @param {Object} opts
+ * @param {unknown} opts.openapi - `MegaOpenApiAppConfig`. `enabled:true` 일 때만 등록.
+ * @param {string} [opts.appName] - 앱 이름(info.title 디폴트·로그).
+ * @param {(req: any, reply: any) => any} [opts.buildCtx] - docs auth 미들웨어에 넘길 ctx 팩토리(요청당). 미지정 시 auth 는 `(req, reply)` 로만 호출.
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger] - 흐름 길목 debug 로그(선택).
+ * @returns {OpenapiSummary}
+ */
+export function registerOpenapi(fastify: import("fastify").FastifyInstance, { openapi, appName, buildCtx, logger }?: {
+    openapi: unknown;
+    appName?: string;
+    buildCtx?: (req: any, reply: any) => any;
+    logger?: {
+        debug?: Function;
+        warn?: Function;
+    };
+}): OpenapiSummary;
+/** swagger-ui 마운트 경로 디폴트 (04-data-models §2 정본). */
+export const DEFAULT_OPENAPI_PATH: "/docs";
+/**
+ * OpenAPI 자동 등록 결과 요약(디버그·테스트용).
+ */
+export type OpenapiSummary = {
+    /**
+     * - 등록 여부.
+     */
+    enabled: boolean;
+    /**
+     * - swagger-ui 경로(미등록 시 null).
+     */
+    path: string | null;
+};