mega-framework 0.1.6 → 0.1.7

package/types/adapters/redis-session-adapter.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @typedef {object} RedisSessionConfig
+ * @property {string} [driver] - 'redis' (팩토리가 사용 — 어댑터는 무시).
+ * @property {string} [url] - `redis://[:pw@]host:port[/db]` (discrete 와 배타).
+ * @property {string} [connectionString] - `url` 의 deprecated 별칭.
+ * @property {string} [host] @property {number} [port] @property {string} [user] @property {string} [password]
+ * @property {number} [db] - 논리 DB 번호 0~15.
+ * @property {string} [keyPrefix] - 세션 키 prefix(기본 'mega:sess:').
+ * @property {number} [ttlMs] - save() 가 적용할 기본 TTL(ms). 미지정 시 24시간.
+ * @property {Record<string, any>} [options] - ioredis passthrough.
+ */
+export class MegaRedisSessionAdapter extends MegaSessionAdapter {
+    /**
+     * @param {RedisSessionConfig} [config]
+     * @throws {MegaValidationError} `adapter.connection_required` / `adapter.connection_conflict` / `session.invalid_option`
+     */
+    constructor(config?: RedisSessionConfig);
+    /**
+     * raw ioredis handle (ADR-009).
+     * @protected
+     * @returns {import('ioredis').Redis}
+     */
+    protected _native(): import("ioredis").Redis;
+    /**
+     * 헬스 체크 — 실제 ping. 비밀번호/url 은 노출하지 않는다.
+     * @returns {Promise<{ ok: boolean, driver: 'redis', state: string, db?: number, error?: string }>}
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        driver: "redis";
+        state: string;
+        db?: number;
+        error?: string;
+    }>;
+    /**
+     * 누적 통계 + redis 세션 특화.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, db: number | undefined, keyPrefix: string, ttlMs: number, status: string | undefined }}
+     */
+    getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
+        driver: string;
+        db: number | undefined;
+        keyPrefix: string;
+        ttlMs: number;
+        status: string | undefined;
+    };
+    #private;
+}
+export type RedisSessionConfig = {
+    /**
+     * - 'redis' (팩토리가 사용 — 어댑터는 무시).
+     */
+    driver?: string;
+    /**
+     * - `redis://[:pw@]host:port[/db]` (discrete 와 배타).
+     */
+    url?: string;
+    /**
+     * - `url` 의 deprecated 별칭.
+     */
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    /**
+     * - 논리 DB 번호 0~15.
+     */
+    db?: number;
+    /**
+     * - 세션 키 prefix(기본 'mega:sess:').
+     */
+    keyPrefix?: string;
+    /**
+     * - save() 가 적용할 기본 TTL(ms). 미지정 시 24시간.
+     */
+    ttlMs?: number;
+    /**
+     * - ioredis passthrough.
+     */
+    options?: Record<string, any>;
+};
+import { MegaSessionAdapter } from './mega-session-adapter.js';

package/types/adapters/redlock-adapter.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @typedef {object} RedlockConfig
+ * @property {string} [driver] - 'redlock' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} redis - 참조할 Redis 캐시 어댑터 key (services.caches.<key>). 필수.
+ * @property {Partial<RedlockSettings>} [options] - redlock Settings passthrough(driftFactor/retryCount/retryDelay/retryJitter/automaticExtensionThreshold).
+ */
+export class MegaRedlockAdapter extends MegaLockAdapter {
+    /**
+     * redlock Settings 검증·정규화. options 없으면 빈 객체(=redlock 디폴트 사용). 알 수 없는 키는 오타로
+     * 보고 거부, 숫자 4종은 음 아닌 정수, driftFactor 는 [0,1) 유한수.
+     * @param {unknown} options @returns {Partial<RedlockSettings>}
+     */
+    static "__#private@#normalizeSettings"(options: unknown): Partial<RedlockSettings>;
+    /**
+     * @param {RedlockConfig} [config] - services.locks.<key> 설정.
+     * @throws {MegaValidationError} `lock.redis_required` - `redis` 키 누락/비문자열.
+     * @throws {MegaValidationError} `adapter.invalid_option` - options 타입/알 수 없는 settings 키/음수.
+     */
+    constructor(config?: RedlockConfig);
+    /**
+     * raw redlock handle (ADR-009). 베이스 `native` getter 가 connected 상태에서만 호출한다.
+     * @protected
+     * @returns {import('redlock').default}
+     */
+    protected _native(): import("redlock").default;
+    /**
+     * 헬스 체크 — 락 가용성은 곧 참조 Redis 의 가용성이라 그 어댑터의 healthCheck 에 위임한다.
+     * 실패는 throw 없이 `ok:false` + 사유(베이스 계약).
+     * @returns {Promise<{ ok: boolean, driver: 'redlock', state: string, redis: string, redisOk?: boolean, error?: string }>}
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        driver: "redlock";
+        state: string;
+        redis: string;
+        redisOk?: boolean;
+        error?: string;
+    }>;
+    /**
+     * 누적 통계 + redlock 특화(driver/redis 키/settings). settings 는 숫자 계수뿐이라 시크릿 없음.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, redis: string, settings: Partial<RedlockSettings> }}
+     */
+    getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
+        driver: string;
+        redis: string;
+        settings: Partial<RedlockSettings>;
+    };
+    /**
+     * 락 획득 — `redlock.acquire([key], ttl, settings)`. 경합 시 retry(opts) 소진 후 실패하면 redlock 이
+     * `ExecutionError` 를 throw(정상 도메인 결과 — 호출부가 처리).
+     *
+     * @param {string} key - 락 자원 키.
+     * @param {{ ttl?: number, retryCount?: number, retryDelay?: number, retryJitter?: number }} [opts]
+     *   - `ttl`(ms, 양의 정수 필수). retry 3종은 이번 호출 한정 override(미지정 시 생성자 settings 사용).
+     * @returns {Promise<import('redlock').Lock>} redlock Lock 핸들.
+     */
+    acquire(key: string, opts?: {
+        ttl?: number;
+        retryCount?: number;
+        retryDelay?: number;
+        retryJitter?: number;
+    }): Promise<import("redlock").Lock>;
+    /**
+     * 락 해제 — `lock.release()`. 이미 만료/탈취된 락 release 는 redlock 이 'error' 로 표면화하거나
+     * throw 할 수 있다(비치명 — 락은 어차피 만료됨). 본 메서드는 정상 해제 경로를 instrument 한다.
+     *
+     * @param {import('redlock').Lock} lock - {@link acquire}/{@link extend} 가 돌려준 핸들.
+     * @returns {Promise<void>}
+     */
+    release(lock: import("redlock").Lock): Promise<void>;
+    /**
+     * 락 TTL 연장 — `redlock.extend(lock, ttl)`. **새 Lock 핸들을 반환**한다(redlock 이 연장 시 새 핸들을
+     * 만듦) — 이후 release/extend 는 반환된 핸들을 써야 한다(기존 핸들 무효, ADR-113).
+     *
+     * @param {import('redlock').Lock} lock @param {number} ttl - 추가 보유 시간(ms, 양의 정수).
+     * @returns {Promise<import('redlock').Lock>} 연장된 새 Lock 핸들.
+     */
+    extend(lock: import("redlock").Lock, ttl: number): Promise<import("redlock").Lock>;
+    /**
+     * convenience — `redlock.using([key], ttl, settings, routine)`. 락 획득 + **자동 연장**
+     * (automaticExtensionThreshold 임박 시 자동 extend) + 종료 시 자동 release(routine 이 throw 해도 보장).
+     *
+     * routine 은 `(signal)` 을 받는다 — `signal.aborted` 가 true 면 자동 연장이 실패해 더는 배타성을
+     * 보장할 수 없는 상태다(`signal.error` 에 사유). routine 은 이때 즉시 중단하고 예외 상황으로 처리해야
+     * 한다(베이스 `withLock` 의 `(lock)` 시그니처와 다름 — auto-extension 모델 차이, ADR-113).
+     *
+     * @template T
+     * @param {string} key
+     * @param {{ ttl?: number, retryCount?: number, retryDelay?: number, retryJitter?: number }} opts - `ttl`(ms) 필수.
+     * @param {(signal: RedlockAbortSignal) => Promise<T>} fn - 임계구역 routine.
+     * @returns {Promise<T>} routine 반환값.
+     */
+    withLock<T>(key: string, opts: {
+        ttl?: number;
+        retryCount?: number;
+        retryDelay?: number;
+        retryJitter?: number;
+    }, fn: (signal: RedlockAbortSignal) => Promise<T>): Promise<T>;
+    #private;
+}
+/**
+ * redlock Settings 부분집합. redlock 패키지의 `Settings` interface 는 **type-only export** 라 패키지
+ * `exports` 맵(→ .d.ts 없는 esm .js)을 통과하면 TS 에 안 보인다(런타임 값 있는 class 만 보임). 그래서
+ * 같은 shape 를 로컬 typedef 로 둔다(redlock 정의와 1:1, dist/index.d.ts 확인).
+ */
+export type RedlockSettings = {
+    /**
+     * - 시계 드리프트 보정 계수 [0,1).
+     */
+    driftFactor?: number;
+    /**
+     * - 경합 시 재시도 횟수.
+     */
+    retryCount?: number;
+    /**
+     * - 재시도 간 지연(ms).
+     */
+    retryDelay?: number;
+    /**
+     * - 재시도 지연 지터(ms).
+     */
+    retryJitter?: number;
+    /**
+     * - `using` 자동 연장 임계(ms).
+     */
+    automaticExtensionThreshold?: number;
+};
+/**
+ * redlock `using` routine 이 받는 중단 신호 (redlock 의 `RedlockAbortSignal` 과 동일 shape — 위와 같은
+ * type-only export 사유로 로컬 정의). `aborted` 가 true 면 자동 연장 실패로 배타성 상실, `error` 에 사유.
+ */
+export type RedlockAbortSignal = AbortSignal & {
+    error?: Error;
+};
+export type RedlockConfig = {
+    /**
+     * - 'redlock' (매니저가 사용 — 어댑터는 무시).
+     */
+    driver?: string;
+    /**
+     * - 참조할 Redis 캐시 어댑터 key (services.caches.<key>). 필수.
+     */
+    redis: string;
+    /**
+     * - redlock Settings passthrough(driftFactor/retryCount/retryDelay/retryJitter/automaticExtensionThreshold).
+     */
+    options?: Partial<RedlockSettings>;
+};
+import { MegaLockAdapter } from './mega-lock-adapter.js';

package/types/adapters/registry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * driver → 어댑터 클래스 등록. 이미 같은 driver 가 **다른 클래스**로 등록돼 있으면 throw
+ * (silent override 방지). 같은 클래스 재등록은 idempotent no-op.
+ *
+ * @param {string} driver - driver 이름 (예: 'postgres').
+ * @param {typeof MegaAdapter} AdapterClass - MegaAdapter 를 상속한 어댑터 클래스.
+ * @returns {void}
+ */
+export function register(driver: string, AdapterClass: typeof MegaAdapter): void;
+/**
+ * `config.adapters.register` 맵을 일괄 등록 (ADR-044 3rd party). 빌트인 예약어 점유 시 throw.
+ *
+ * @param {Record<string, typeof MegaAdapter>} [registerMap]
+ * @returns {void}
+ */
+export function registerFromConfig(registerMap?: Record<string, typeof MegaAdapter>): void;
+/**
+ * driver 이름으로 등록된 어댑터 클래스 조회. 없으면 `adapter.unknown_driver` throw.
+ *
+ * @param {string} driver
+ * @returns {typeof MegaAdapter}
+ */
+export function resolve(driver: string): typeof MegaAdapter;
+/**
+ * driver 가 등록돼 있는지 (Boolean — `has*`, ADR-036).
+ * @param {string} driver
+ * @returns {boolean}
+ */
+export function has(driver: string): boolean;
+/**
+ * 등록된 driver 이름 목록.
+ * @returns {string[]}
+ */
+export function list(): string[];
+/**
+ * 테스트용 reset — 등록 전부 비움.
+ * @returns {void}
+ */
+export function _reset(): void;
+/**
+ * 빌트인 driver 예약어 (ADR-044, ADR-082 file 포함, ADR-113 redlock 포함). 구체 클래스는 각 Step 에서 등록.
+ * 3rd party 가 이 이름을 점유하지 못하도록 예약 — `registerFromConfig` 가 거부.
+ * @type {ReadonlySet<string>}
+ */
+export const BUILTIN_DRIVERS: ReadonlySet<string>;
+import { MegaAdapter } from './mega-adapter.js';

package/types/adapters/sqlite-adapter.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @typedef {object} SqliteConfig
+ * @property {string} [driver] - 'sqlite' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} filename - DB 파일 경로 또는 ':memory:' (필수).
+ * @property {boolean} [readonly] - 읽기 전용 연결.
+ * @property {boolean} [fileMustExist] - 파일이 없으면 connect 시 throw.
+ * @property {number} [timeout] - 잠긴 DB 대기 ms (SQLITE_BUSY 전, 기본 5000).
+ * @property {boolean} [wal] - true 면 connect 후 `journal_mode = WAL` 적용.
+ * @property {Record<string, string | number>} [pragmas] - connect 후 적용할 추가 PRAGMA 맵.
+ */
+export class MegaSqliteAdapter extends MegaDbAdapter {
+    /**
+     * @param {SqliteConfig} [config] - services.databases.<key> 설정.
+     * @throws {MegaValidationError} `sqlite.filename_required` - filename 누락/빈 문자열.
+     * @throws {MegaValidationError} `sqlite.invalid_option` - 옵션 타입 오류.
+     */
+    constructor(config?: SqliteConfig);
+    /** driver 식별자 — dialect 디스패치(getDialect)·CRUD 의 단일 출처(ADR-212). @returns {'sqlite'} */
+    get driver(): "sqlite";
+    /**
+     * raw Database handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
+     * @protected
+     * @returns {import('better-sqlite3').Database}
+     */
+    protected _native(): import("better-sqlite3").Database;
+    /**
+     * 헬스 체크 — 실제 `SELECT 1` 으로 응답성 확인 (베이스 디폴트는 상태만 반영).
+     * connect 전이거나 쿼리 실패면 `ok:false` + 사유. `/health/ready` 가 모든 어댑터 ok 를 AND.
+     *
+     * @returns {Promise<{ ok: boolean, driver: 'sqlite', state: string, filename?: string, error?: string }>}
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        driver: "sqlite";
+        state: string;
+        filename?: string;
+        error?: string;
+    }>;
+    /**
+     * 누적 통계 + sqlite 특화 필드.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, filename: string, inMemory: boolean, readonly: boolean, journalMode: string | undefined }}
+     */
+    getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
+        driver: string;
+        filename: string;
+        inMemory: boolean;
+        readonly: boolean;
+        journalMode: string | undefined;
+    };
+    /**
+     * 명시적 트랜잭션 경계 (ADR-010, ADR-105). manual `BEGIN/COMMIT/ROLLBACK` 으로
+     * async `fn` 과 better-sqlite3 의 동기 트랜잭션 모델을 정합시킨다(모듈 docstring 참조).
+     *
+     * `fn` 은 **트랜잭션 컨텍스트 native handle**(= 같은 Database 인스턴스)을 인자로 받는다.
+     * 성공 시 COMMIT 후 `fn` 반환값을 그대로 돌려주고, `fn` 이 throw 하면 ROLLBACK 후 원본 에러를
+     * re-throw 한다. nested / 동시 호출은 `db.inTransaction` 으로 감지해 거부(ADR-105).
+     *
+     * `opts.isolation`(ADR-190) — SQLite 트랜잭션은 항상 SERIALIZABLE 동작(단일 writer, 공식 문서)이라
+     * `'serializable'` 만 수용(no-op)하고 다른 값은 `adapter.invalid_option` 으로 명시 거부한다
+     * (조용히 무시하면 사용자가 다른 격리수준이 적용된 줄 오인 — P4).
+     *
+     * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
+     *
+     * @template T
+     * @param {(db: import('better-sqlite3').Database) => Promise<T> | T} fn
+     * @param {{ isolation?: 'serializable' }} [opts] - 트랜잭션 옵션(ADR-190).
+     * @returns {Promise<T>}
+     * @throws {MegaInternalError} `adapter.nested_transaction_unsupported` - 이미 트랜잭션 진행 중.
+     * @throws {MegaValidationError} `adapter.invalid_option` - 'serializable' 외 isolation 값.
+     */
+    withTransaction<T>(fn: (db: import("better-sqlite3").Database) => Promise<T> | T, opts?: {
+        isolation?: "serializable";
+    }): Promise<T>;
+    #private;
+}
+export type SqliteConfig = {
+    /**
+     * - 'sqlite' (매니저가 사용 — 어댑터는 무시).
+     */
+    driver?: string;
+    /**
+     * - DB 파일 경로 또는 ':memory:' (필수).
+     */
+    filename: string;
+    /**
+     * - 읽기 전용 연결.
+     */
+    readonly?: boolean;
+    /**
+     * - 파일이 없으면 connect 시 throw.
+     */
+    fileMustExist?: boolean;
+    /**
+     * - 잠긴 DB 대기 ms (SQLITE_BUSY 전, 기본 5000).
+     */
+    timeout?: number;
+    /**
+     * - true 면 connect 후 `journal_mode = WAL` 적용.
+     */
+    wal?: boolean;
+    /**
+     * - connect 후 적용할 추가 PRAGMA 맵.
+     */
+    pragmas?: Record<string, string | number>;
+};
+import { MegaDbAdapter } from './mega-db-adapter.js';

package/types/auth/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 로그인(세션 `userId` 존재)을 요구하는 `before` 가드. 통과 시 `req.user`(`{ id, roles }`)를 채운다.
+ * 실패 시 401 `auth.required`.
+ *
+ * @param {import('fastify').FastifyRequest} req
+ * @param {import('fastify').FastifyReply} _reply
+ * @param {Record<string, any>} [ctx] - 글로벌 미들웨어 경로에서만 주입(라우트 before 에선 undefined).
+ * @returns {Promise<void>}
+ * @throws {MegaAuthError} 세션·userId 부재 시 401.
+ * @example
+ * router.http.get('/api/me', MeController.show, { before: [requireAuth] })
+ */
+export function requireAuth(req: import("fastify").FastifyRequest, _reply: import("fastify").FastifyReply, ctx?: Record<string, any>): Promise<void>;
+/**
+ * 지정한 역할 중 하나 이상을 가진 로그인 사용자를 요구하는 `before` 가드 팩토리. 먼저 인증을
+ * 확정(`requireAuth` 동일 로직)한 뒤 역할 교집합을 검사한다.
+ *
+ * @param {...string} roles - 허용 역할 목록(하나라도 보유 시 통과). 최소 1개 필수.
+ * @returns {(req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply, ctx?: Record<string, any>) => Promise<void>}
+ * @throws {TypeError} 역할 인자가 비었거나 문자열이 아니면(설정 실수 fail-fast).
+ * @example
+ * router.http.post('/api/users', UsersController.create, { before: [requireRole('admin')] })
+ */
+export function requireRole(...roles: string[]): (req: import("fastify").FastifyRequest, reply: import("fastify").FastifyReply, ctx?: Record<string, any>) => Promise<void>;

package/types/cli/commands/console-cmd.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 앱 컨텍스트를 로딩하고 REPL 을 연다.
+ * @param {string} projectRoot
+ * @param {object} [deps]
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [deps.logger]
+ * @param {() => { context: Record<string, any>, on?: (event: string, listener: (...args: any[]) => void) => void }} [deps.replFactory] -
+ *   주입용(테스트). context 객체를 가진 REPL-유사 객체를 반환해야 한다('exit' 이벤트용 `on` 은 선택).
+ * @param {(msg: string) => void} [deps.out]
+ * @param {() => (Promise<void> | void)} [deps.shutdown] - 주입용(테스트). REPL 종료 시 호출하는 graceful
+ *   shutdown 트리거. 기본 {@link MegaShutdown.now}(등록 hook 실행 후 process.exit).
+ * @param {(opts: { signals?: string[], globalErrorHandlers?: boolean }) => void} [deps.setupSignals] - 주입용(테스트). 시그널 핸들러 등록.
+ *   기본 {@link MegaShutdown.setupSignals}.
+ * @returns {Promise<{ ctx: Record<string, any>, config: object, server: { context: Record<string, any> } }>}
+ */
+export function startConsole(projectRoot: string, { logger, replFactory, out, shutdown, setupSignals }?: {
+    logger?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+    replFactory?: () => {
+        context: Record<string, any>;
+        on?: (event: string, listener: (...args: any[]) => void) => void;
+    };
+    out?: (msg: string) => void;
+    shutdown?: () => (Promise<void> | void);
+    setupSignals?: (opts: {
+        signals?: string[];
+        globalErrorHandlers?: boolean;
+    }) => void;
+}): Promise<{
+    ctx: Record<string, any>;
+    config: object;
+    server: {
+        context: Record<string, any>;
+    };
+}>;

package/types/cli/commands/new.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 프로젝트를 스캐폴드한다(순수 — prompts 없이 opts 로만 동작, 테스트 가능).
+ * @param {string} targetDir - 프로젝트 루트 절대/상대 경로.
+ * @param {object} [opts]
+ * @param {string} [opts.name] - 프로젝트 이름(기본: targetDir 의 마지막 세그먼트).
+ * @param {boolean} [opts.force] - 기존 파일 덮어쓰기(기본 false — 건너뜀).
+ * @returns {{ root: string, written: string[], skipped: string[] }}
+ */
+export function scaffoldProject(targetDir: string, { name, force }?: {
+    name?: string;
+    force?: boolean;
+}): {
+    root: string;
+    written: string[];
+    skipped: string[];
+};

package/types/cli/commands/routes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 프로젝트의 앱별 라우트를 수집한다.
+ * @param {string} projectRoot
+ * @returns {Promise<Array<{ app: string, hosts: string[], routes: Array<{ method: string, path: string, file: string }> }>>}
+ */
+export function collectRoutes(projectRoot: string): Promise<Array<{
+    app: string;
+    hosts: string[];
+    routes: Array<{
+        method: string;
+        path: string;
+        file: string;
+    }>;
+}>>;
+/**
+ * 수집한 라우트를 사람이 읽는 트리 문자열로 포맷.
+ * @param {Array<{ app: string, hosts: string[], routes: Array<{ method: string, path: string }> }>} data
+ * @returns {string}
+ */
+export function formatRoutes(data: Array<{
+    app: string;
+    hosts: string[];
+    routes: Array<{
+        method: string;
+        path: string;
+    }>;
+}>): string;
+/**
+ * `mega routes` 명령 본체.
+ * @param {string} projectRoot
+ * @param {{ out?: (msg: string) => void }} [deps]
+ * @returns {Promise<number>} exit code.
+ */
+export function runRoutesCommand(projectRoot: string, { out }?: {
+    out?: (msg: string) => void;
+}): Promise<number>;

package/types/cli/commands/scaffold.d.ts

@@ -0,0 +1,78 @@
+/**
+ * scaffold/dev 명령 5종을 commander program 에 등록한다 — 명령 정의의 단일 정본(ADR-195).
+ * action 은 `process.exit` 를 부르지 않고 `setExit(code)` 로 종료 코드를 보고한다(runCli 계약).
+ *
+ * @param {import('commander').Command} program - 등록 대상 program.
+ * @param {object} deps
+ * @param {(msg: string) => void} deps.out
+ * @param {string} deps.projectRoot - 이미 `--root` 해석된 기준 디렉토리.
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [deps.logger]
+ * @param {(kind: string) => Promise<{ dir: string, files: Array<{ path: string, template: string }> } | undefined>} [deps.resolvePluginGenerator] -
+ *   빌트인이 아닌 kind 의 플러그인 scaffold manifest 조회(`mega.scaffold.register`, 03-api-spec §11).
+ *   호출측(runCli)이 config 로드 + 플러그인 install 을 감싼 함수를 주입한다 — 본 모듈이 cli/index.js 를
+ *   import 하면 순환이라 주입식으로 푼다. 미주입/미발견이면 unknown kind 에러.
+ * @param {(code: number) => void} deps.setExit - 명령 종료 코드 보고 콜백.
+ * @returns {void}
+ */
+export function registerScaffoldCommands(program: import("commander").Command, { out, projectRoot, logger, resolvePluginGenerator, setExit }: {
+    out: (msg: string) => void;
+    projectRoot: string;
+    logger?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+    resolvePluginGenerator?: (kind: string) => Promise<{
+        dir: string;
+        files: Array<{
+            path: string;
+            template: string;
+        }>;
+    } | undefined>;
+    setExit: (code: number) => void;
+}): void;
+/**
+ * commander 의 exitOverride 예외를 exit code 로 환산한다 — help/version 출력은 정상 종료(0),
+ * CommanderError 는 자체 exitCode, 그 외 에러는 메시지 출력 후 1. commander 가 아닌 에러를 그대로
+ * 삼키지 않도록 `rethrowUnknown` 옵션을 둔다(runCli 가 부팅·config 에러를 bin 으로 전파할 때 사용).
+ *
+ * @param {unknown} e - parseAsync 가 던진 예외.
+ * @param {(msg: string) => void} err
+ * @param {{ rethrowUnknown?: boolean }} [opts] - true 면 CommanderError 가 아닌 예외를 재throw.
+ * @returns {number} exit code.
+ */
+export function commanderErrorToExitCode(e: unknown, err: (msg: string) => void, { rethrowUnknown }?: {
+    rethrowUnknown?: boolean;
+}): number;
+/**
+ * scaffold/dev 명령만 담은 독립 program 으로 실행한다(하위호환 진입점 — 단위 테스트 경계 유지).
+ * commander 로 파싱하되 `process.exit` 를 부르지 않고 exit code 를 반환한다(runCli 계약 정합).
+ *
+ * @param {string[]} argv - `process.argv.slice(2)` (첫 토큰 = 명령).
+ * @param {object} deps
+ * @param {(msg: string) => void} deps.out
+ * @param {(msg: string) => void} deps.err
+ * @param {string} deps.projectRoot - 이미 `--root` 해석된 기준 디렉토리.
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [deps.logger]
+ * @param {(kind: string) => Promise<{ dir: string, files: Array<{ path: string, template: string }> } | undefined>} [deps.resolvePluginGenerator]
+ * @returns {Promise<number>} exit code.
+ */
+export function runScaffoldCommand(argv: string[], { out, err, projectRoot, logger, resolvePluginGenerator }: {
+    out: (msg: string) => void;
+    err: (msg: string) => void;
+    projectRoot: string;
+    logger?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+    resolvePluginGenerator?: (kind: string) => Promise<{
+        dir: string;
+        files: Array<{
+            path: string;
+            template: string;
+        }>;
+    } | undefined>;
+}): Promise<number>;
+/** scaffold/dev 명령 이름(별칭 포함). */
+export const SCAFFOLD_COMMANDS: Set<string>;

package/types/cli/commands/test-cmd.d.ts

@@ -0,0 +1,14 @@
+/**
+ * vitest 를 자식 프로세스로 실행한다.
+ * @param {string} projectRoot - 실행 cwd.
+ * @param {string[]} [args] - vitest 에 넘길 추가 인자.
+ * @param {object} [deps]
+ * @param {typeof nodeSpawn} [deps.spawn] - 주입용(테스트).
+ * @param {(msg: string) => void} [deps.out]
+ * @returns {Promise<number>} vitest exit code.
+ */
+export function runTestCommand(projectRoot: string, args?: string[], { spawn, out }?: {
+    spawn?: typeof nodeSpawn;
+    out?: (msg: string) => void;
+}): Promise<number>;
+import { spawn as nodeSpawn } from 'node:child_process';