@fuzionx/framework 0.1.2

package/bin/fx.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * fx CLI — @fuzionx/framework 내장 명령줄 도구.
+ *
+ * @see docs/framework/16-cli.md
+ */
+import { run } from '../cli/index.js';
+
+run(process.argv.slice(2)).catch((err) => {
+    console.error(err.message || err);
+    process.exit(1);
+});

package/index.js

@@ -0,0 +1,64 @@
+/**
+ * @fuzionx/framework
+ *
+ * Full-stack MVC framework built on @fuzionx/core.
+ */
+
+// ── Core ──
+export { default as AppError, ServiceError, ValidationError } from './lib/core/AppError.js';
+export { default as Config } from './lib/core/Config.js';
+export { default as Base } from './lib/core/Base.js';
+export { default as Application } from './lib/core/Application.js';
+export { default as Context } from './lib/core/Context.js';
+export { default as AutoLoader } from './lib/core/AutoLoader.js';
+
+// ── HTTP ──
+export { default as Router, RouteGroup } from './lib/http/Router.js';
+export { default as Controller } from './lib/http/Controller.js';
+export { default as Middleware, runMiddlewareChain } from './lib/http/Middleware.js';
+export { default as ErrorHandler } from './lib/http/ErrorHandler.js';
+export { default as Validation, parseRules } from './lib/http/Validation.js';
+
+// ── Database ──
+export { default as Model } from './lib/database/Model.js';
+export { default as SqlModel } from './lib/database/SqlModel.js';
+export { default as SQLiteModel } from './lib/database/SQLiteModel.js';
+export { default as MariaModel } from './lib/database/MariaModel.js';
+export { default as PostgreModel } from './lib/database/PostgreModel.js';
+export { default as MongoModel } from './lib/database/MongoModel.js';
+export { default as ModelRegistry } from './lib/database/ModelRegistry.js';
+export { default as QueryBuilder } from './lib/database/QueryBuilder.js';
+export { default as SqlQueryBuilder } from './lib/database/SqlQueryBuilder.js';
+export { default as ConnectionManager } from './lib/database/ConnectionManager.js';
+export { default as Pagination } from './lib/database/Pagination.js';
+
+// ── Services ──
+export { default as Service } from './lib/services/Service.js';
+export { default as EventBus } from './lib/services/EventBus.js';
+export { default as Storage } from './lib/services/Storage.js';
+
+// ── Realtime ──
+export { default as WsHandler, EventBuilder } from './lib/realtime/WsHandler.js';
+export { default as RoomManager } from './lib/realtime/RoomManager.js';
+
+// ── Schedule ──
+export { default as Scheduler } from './lib/schedule/Scheduler.js';
+export { default as Queue } from './lib/schedule/Queue.js';
+export { default as Job } from './lib/schedule/Job.js';
+export { default as Task } from './lib/schedule/Task.js';
+export { default as WorkerPool } from './lib/schedule/WorkerPool.js';
+
+// ── Helpers (Bridge N-API) ──
+export { default as Logger } from './lib/helpers/Logger.js';
+export { default as I18nHelper } from './lib/helpers/I18nHelper.js';
+export { default as CryptoHelper } from './lib/helpers/CryptoHelper.js';
+export { default as HashHelper } from './lib/helpers/HashHelper.js';
+export { default as MediaHelper } from './lib/helpers/MediaHelper.js';
+export { default as FileHelper } from './lib/helpers/FileHelper.js';
+
+// ── View ──
+export { default as View } from './lib/view/View.js';
+export { default as OpenAPI } from './lib/view/OpenAPI.js';
+
+// ── Built-in Middleware ──
+export { bodyParser, cors, auth, apiAuth, csrf, session, theme } from './lib/middleware/index.js';

package/lib/core/AppError.js

@@ -0,0 +1,46 @@
+/**
+ * AppError — 프레임워크 에러 타입
+ *
+ * HTTP 상태 코드 + 추가 데이터를 포함하는 에러.
+ * ServiceError, ValidationError 등의 기반 클래스.
+ *
+ * @see docs/framework/08-error-handling.md
+ */
+export default class AppError extends Error {
+    /**
+     * @param {string} message - 에러 메시지
+     * @param {number} [status=500] - HTTP 상태 코드
+     * @param {object|null} [data=null] - 추가 데이터 (validation errors 등)
+     */
+    constructor(message, status = 500, data = null) {
+        super(message);
+        this.name = 'AppError';
+        this.status = status;
+        this.data = data;
+    }
+}
+
+/**
+ * ServiceError — 비즈니스 로직 에러 (400/403/404)
+ */
+export class ServiceError extends AppError {
+    constructor(message, status = 400, data = null) {
+        super(message, status, data);
+        this.name = 'ServiceError';
+    }
+}
+
+/**
+ * ValidationError — 입력 검증 실패 (422)
+ */
+export class ValidationError extends AppError {
+    /**
+     * @param {string} message - 에러 메시지
+     * @param {object} fields - 필드별 에러 메시지 { email: '필수 입력', name: '2자 이상' }
+     */
+    constructor(message = 'Validation failed', fields = {}) {
+        super(message, 422, { fields });
+        this.name = 'ValidationError';
+        this.fields = fields;
+    }
+}

package/lib/core/Application.js

@@ -0,0 +1,553 @@
+/**
+ * Application — 서비스 컨테이너 + 부트스트랩 오케스트레이터 + Bridge 어댑터
+ *
+ * @fuzionx/core의 FuzionXApp을 내부적으로 사용하여 Bridge 서버 시작.
+ * rawReq → Context 변환 → 미들웨어 체인 → 컨트롤러 → toResponse().
+ *
+ * @see docs/framework/00-overview.md
+ * @see docs/framework/04-bootstrap-lifecycle.md
+ */
+import path from 'node:path';
+import Config from './Config.js';
+import Context from './Context.js';
+import Router from '../http/Router.js';
+import ModelRegistry from '../database/ModelRegistry.js';
+import ErrorHandler from '../http/ErrorHandler.js';
+import AutoLoader from './AutoLoader.js';
+import Logger from '../helpers/Logger.js';
+import I18nHelper from '../helpers/I18nHelper.js';
+import CryptoHelper from '../helpers/CryptoHelper.js';
+import HashHelper from '../helpers/HashHelper.js';
+import MediaHelper from '../helpers/MediaHelper.js';
+import FileHelper from '../helpers/FileHelper.js';
+import View from '../view/View.js';
+import Scheduler from '../schedule/Scheduler.js';
+import Queue from '../schedule/Queue.js';
+import Storage from '../services/Storage.js';
+import ConnectionManager from '../database/ConnectionManager.js';
+import SqlModel from '../database/SqlModel.js';
+import MongoModel from '../database/MongoModel.js';
+import WorkerPool from '../schedule/WorkerPool.js';
+
+// Bridge: lazy-load (테스트 환경에서 native 바인딩 없을 수 있음)
+let FuzionXApp;
+try {
+    const core = await import('@fuzionx/core');
+    FuzionXApp = core.FuzionXApp || core.RuxyApp;
+} catch {}
+
+export default class Application {
+    /**
+     * @param {object} [opts]
+     * @param {object} [opts.config] - 이미 파싱된 설정 객체 또는 Config 인스턴스
+     * @param {string} [opts.configPath] - YAML 설정 파일 경로
+     * @param {string} [opts.baseDir='.'] - 프로젝트 루트 경로
+     * @param {object} [opts.bridge] - @fuzionx/core bridge 인스턴스 (선택)
+     */
+    constructor(opts = {}) {
+        // Config
+        if (opts.config instanceof Config) {
+            this.config = opts.config;
+        } else {
+            this.config = new Config(opts.config || {});
+        }
+
+        // 프로젝트 루트 (반드시 절대경로 — ESM import 호환)
+        this.baseDir = path.resolve(opts.baseDir || process.cwd());
+        this.configPath = opts.configPath || null;
+
+        // Bridge 참조 (listen() 시 FuzionXApp 생성)
+        this._bridge = null;
+        this._coreApp = null;
+
+        // DI 컨테이너
+        this._services = new Map();
+        this._factories = new Map();
+
+        // 이벤트 핸들러
+        this._eventHandlers = new Map();
+        this._errorHandlers = [];
+
+        // 라우터
+        this._router = new Router();
+
+        // 미들웨어
+        this._globalMiddleware = [];
+        this._middlewareRegistry = new Map();
+
+        // 프레임워크 컴포넌트
+        this.db = new ModelRegistry();
+        this.logger = new Logger({
+            level: this.config.get('bridge.logging.level', 'info'),
+            bridge: this._bridge,
+            json: this.config.get('bridge.logging.json', false),
+        });
+        this.crypto = new CryptoHelper(this._bridge);
+        this.hash = new HashHelper(this._bridge);
+        this.media = new MediaHelper(this._bridge);
+        this.file = new FileHelper(this._bridge);
+        this.ws = null;
+        this.i18n = new I18nHelper({
+            defaultLocale: this.config.get('app.i18n.default_locale', 'ko'),
+            fallback: this.config.get('app.i18n.fallback', 'en'),
+            dir: this.config.get('app.i18n.dir', './locales'),
+            bridge: this._bridge,
+        });
+        this.storage = null;
+        this._scheduler = null;
+        this._queue = null;
+        this._view = null;
+        this._wsHandlers = new Map();
+
+        // DB 연결 매니저
+        this._connectionManager = new ConnectionManager();
+
+        // Worker 매니저
+        this._workerPool = new WorkerPool(this);
+
+        /** @type {WorkerPool} public worker 접근 */
+        this.worker = this._workerPool;
+
+        // 에러 핸들러
+        this._errorHandler = new ErrorHandler({
+            isDev: this.config.get('app.environment', 'development') === 'development',
+            logger: (...args) => this.logger.error(...args),
+        });
+
+        // 라이프사이클 상태
+        this._booted = false;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  DI — 서비스 컨테이너
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    register(name, factory) {
+        this._factories.set(name, factory);
+    }
+
+    make(name) {
+        if (this._services.has(name)) return this._services.get(name);
+        const factory = this._factories.get(name);
+        if (!factory) throw new Error(`Service '${name}' is not registered`);
+        const instance = factory(this);
+        this._services.set(name, instance);
+        return instance;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  라우터 접근
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /** 라우터 인스턴스 */
+    get router() { return this._router; }
+
+    /**
+     * 라우트 파일 로드
+     * @param {Function} routeCallback - (r: RouteGroup) => void
+     * @see docs/framework/01-routing-controllers.md
+     */
+    routes(routeCallback) {
+        this._router.load(routeCallback);
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  미들웨어
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 글로벌 미들웨어 등록
+     * @param {Function} fn - (ctx, next) => void
+     */
+    use(fn) {
+        this._globalMiddleware.push(fn);
+        return this;
+    }
+
+    /**
+     * 이름으로 미들웨어 인스턴스 조회
+     * @param {string} name - 'auth', 'csrf' 등
+     * @returns {Function} - (ctx, next) => void
+     */
+    resolveMiddleware(name) {
+        // 캐시 히트 → zero-allocation (M-1)
+        if (this._mwFnCache?.has(name)) return this._mwFnCache.get(name);
+
+        // 파라미터화: 'role:admin' → name='role', params=['admin']
+        const [mwName, ...params] = name.split(':');
+        const MwClass = this._middlewareRegistry.get(mwName);
+        if (!MwClass) return null;
+
+        const instance = new MwClass(this);
+        const fn = (ctx, next) => instance.handle(ctx, next, ...params);
+
+        // 캐시 저장
+        if (!this._mwFnCache) this._mwFnCache = new Map();
+        this._mwFnCache.set(name, fn);
+        return fn;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  이벤트 시스템
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    on(event, handler) {
+        if (!this._eventHandlers.has(event)) {
+            this._eventHandlers.set(event, []);
+        }
+        this._eventHandlers.get(event).push(handler);
+    }
+
+    async emit(event, data, opts) {
+        const handlers = this._eventHandlers.get(event);
+        if (!handlers) return;
+        const meta = { remote: false, server: this.config.get('app.name', 'fuzionx'), timestamp: Date.now() };
+        for (const handler of handlers) {
+            try { await handler(data, meta); } catch (err) {
+                this.logger.error(`Event '${event}' handler error:`, err);
+            }
+        }
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  에러 핸들러
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    useError(pathOrHandler, handler) {
+        if (typeof pathOrHandler === 'function') {
+            this._errorHandlers.push({ path: null, handler: pathOrHandler });
+        } else {
+            this._errorHandlers.push({ path: pathOrHandler, handler });
+        }
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  큐 디스패치
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    dispatch(taskOrName, data, opts) {
+        if (this._queue) this._queue.dispatch(taskOrName, data, opts);
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  부트스트랩
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    async boot() {
+        if (this._booted) return;
+
+        // 1. .env 로드 (17-config.md)
+        this.config.loadEnv(this.baseDir);
+        // .env 로드 후 캐시 클리어 (새로운 환경변수 반영)
+        this.config._cache?.clear();
+
+        await this.emit('booting');
+
+        // 6. i18n 로드 (04-bootstrap-lifecycle.md)
+        await this.i18n.load();
+
+        // View 초기화
+        this._view = new View({
+            viewsPath: path.resolve(this.baseDir, 'views'),
+            theme: this.config.get('themes.default', 'default'),
+            bridge: this._bridge,
+        });
+
+        // Scheduler / Queue / Storage 초기화 (04-bootstrap-lifecycle.md)
+        this._scheduler = new Scheduler(this);
+        this._queue = new Queue(this, { driver: this.config.get('queue.driver', 'memory') });
+        this.storage = new Storage({
+            driver: this.config.get('storage.driver', 'local'),
+            basePath: path.resolve(this.baseDir, this.config.get('storage.path', './storage')),
+            fileHelper: this.file,
+        });
+
+        // 자동 스캔 (models, services, middleware, events, jobs, ws, routes)
+        const loader = new AutoLoader(this, this.baseDir);
+        await loader.load();
+
+        // DB 연결 매니저 초기화 (database 섹션이 있을 때만)
+        const dbConfig = this.config.get('database');
+        if (dbConfig && dbConfig.connections) {
+            this._connectionManager.configure(dbConfig);
+            SqlModel.setConnectionManager(this._connectionManager);
+            MongoModel.setConnectionManager(this._connectionManager);
+        }
+
+        this._booted = true;
+        await this.emit('booted');
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  서버 시작 — Bridge 연결
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * Bridge 서버 시작
+     * FuzionXApp과 연동하여 rawReq를 Context로 변환.
+     * @param {number} [port]
+     * @param {Function} [callback]
+     */
+    async listen(port, callback) {
+        if (typeof port === 'function') { callback = port; port = undefined; }
+        port = port || this.config.get('bridge.server.port', 3000);
+
+        if (!this._booted) await this.boot();
+        await this.emit('ready');
+
+        // Bridge 연동
+        if (FuzionXApp) {
+            if (!this._coreApp) {
+                this._coreApp = new FuzionXApp({
+                    config: this.configPath
+                        ? path.resolve(this.baseDir, this.configPath)
+                        : undefined,
+                    port,
+                });
+            }
+            this._registerBridgeRoutes(this._coreApp);
+            this._coreApp.listen(port, callback);
+            // Bridge가 자체 graceful shutdown 처리 → Framework 중복 등록 불필요
+        } else {
+            // Bridge 미설치 (테스트 환경)
+            this._initControllers();
+            if (callback) callback();
+            this._setupGracefulShutdown();
+        }
+
+        await this.emit('listening');
+        return this;
+    }
+
+    /**
+     * 싱글톤 컨트롤러 초기화
+     * @private
+     */
+    _initControllers() {
+        this._controllerCache = new Map();
+
+        for (const route of this._router.getRoutes()) {
+            const handler = route.handler;
+            if (handler?.__handler__ && handler.controller) {
+                const CtrlClass = handler.controller;
+                if (!this._controllerCache.has(CtrlClass)) {
+                    this._controllerCache.set(CtrlClass, new CtrlClass(this));
+                }
+            }
+        }
+    }
+
+    /**
+     * 프레임워크 라우트 → Bridge FuzionXApp 라우트 변환
+     * @private
+     */
+    _registerBridgeRoutes(coreApp) {
+        this._initControllers();
+        const routes = this._router.getRoutes();
+
+        for (const route of routes) {
+            const bridgeHandler = this._createBridgeHandler(route);
+            const method = route.method.toLowerCase();
+
+            if (typeof coreApp[method] === 'function') {
+                coreApp[method](route.path, bridgeHandler);
+            }
+        }
+    }
+
+    /**
+     * 단일 라우트의 Bridge 핸들러 생성
+     * rawReq → Context → middleware → controller → toResponse
+     * @private
+     */
+    _createBridgeHandler(route) {
+        // 미들웨어 체인 사전 구성
+        const middlewareFns = [];
+
+        // 글로벌 미들웨어
+        middlewareFns.push(...this._globalMiddleware);
+
+        // 라우트 미들웨어 (이름 → 인스턴스 변환)
+        if (route.middleware?.length) {
+            for (const mwName of route.middleware) {
+                const fn = this.resolveMiddleware(mwName);
+                if (fn) middlewareFns.push(fn);
+            }
+        }
+
+        return (req, res) => {
+            // rawReq → Context 변환
+            const ctx = new Context({
+                method: req.method,
+                url: req.url,
+                path: req.path,
+                query: req.query,
+                params: req.params,
+                headers: req.headers,
+                body: req.body || req.json,
+                remoteIp: req.ip,
+                handlerId: req.handlerId,
+                requestId: req.requestId,
+                sessionId: req.sessionId,
+                session: req.session?._data || {},
+                files: req.files || null,
+                formFields: req.formFields || null,
+            }, this);
+
+            // Framework → async 체인 실행 후 직접 sendAsyncResponse
+            const promise = this._executeChain(middlewareFns, route, ctx, res);
+
+            promise.then(() => {
+                const response = ctx.toResponse();
+                const contentType = response.headers?.['Content-Type'] || 'application/json';
+                const headerParts = [];
+                if (response.headers) {
+                    for (const [k, v] of Object.entries(response.headers)) {
+                        if (k !== 'Content-Type') headerParts.push(`${k}: ${v}`);
+                    }
+                }
+                const extraHeaders = headerParts.length > 0 ? headerParts.join('\r\n') + '\r\n' : '';
+                try {
+                    this._coreApp._bridge.sendAsyncResponse(
+                        req.requestId, response.status,
+                        response.body || '', contentType, extraHeaders,
+                    );
+                } catch (e) {
+                    console.error('[fuzionx] sendAsyncResponse failed:', e.message);
+                }
+            }).catch((err) => {
+                console.error('[fuzionx] Handler error:', err.message || err);
+                try {
+                    this._coreApp._bridge.sendAsyncResponse(
+                        req.requestId, 500,
+                        JSON.stringify({ error: err.message || 'Internal Server Error' }),
+                        'application/json', '',
+                    );
+                } catch (e) {
+                    console.error('[fuzionx] sendAsyncResponse error failed:', e.message);
+                }
+            });
+
+            return { async: true };
+        };
+    }
+
+    /**
+     * 미들웨어 체인 + 핸들러 실행
+     * @private
+     */
+    async _executeChain(middlewareFns, route, ctx, res) {
+        let idx = 0;
+
+        const next = async () => {
+            if (ctx._sent) return;
+            if (idx < middlewareFns.length) {
+                const fn = middlewareFns[idx++];
+                await fn(ctx, next);
+                return;
+            }
+
+            // 미들웨어 완료 → 핸들러 실행
+            await this._executeHandler(route.handler, ctx);
+        };
+
+        try {
+            await next();
+        } catch (err) {
+            // 커스텀 에러 핸들러 체크 (useError로 등록)
+            let handled = false;
+            for (const { path: ePath, handler } of this._errorHandlers) {
+                if (!ePath || ctx.path?.startsWith(ePath)) {
+                    try {
+                        await handler(err, ctx);
+                        handled = true;
+                        break;
+                    } catch { /* 커스텀 핸들러 실패 시 기본으로 */ }
+                }
+            }
+            if (!handled) this._errorHandler.handle(err, ctx);
+        }
+
+        // Context → Bridge res 변환 (이중 응답 방지 — Core res는 _sent 사용)
+        if (!res._sent) {
+            const response = ctx.toResponse();
+            res.status(response.status);
+            if (response.headers) {
+                for (const [k, v] of Object.entries(response.headers)) {
+                    res.header(k, v);
+                }
+            }
+            res.send(response.body);
+        }
+    }
+
+    /**
+     * 핸들러 실행 (싱글톤 컨트롤러 or 일반 함수)
+     * @private
+     */
+    async _executeHandler(handler, ctx) {
+        if (handler?.__handler__) {
+            // 싱글톤 컨트롤러 메서드 참조
+            const instance = this._controllerCache.get(handler.controller);
+            if (instance && typeof instance[handler.method] === 'function') {
+                await instance[handler.method](ctx);
+                return;
+            }
+        }
+
+        // 일반 함수 핸들러
+        if (typeof handler === 'function') {
+            await handler(ctx);
+        }
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Graceful Shutdown
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    _setupGracefulShutdown() {
+        let shutdownCalled = false;
+
+        const shutdown = async (signal) => {
+            if (shutdownCalled) return;
+            shutdownCalled = true;
+
+            this.logger.info(`[fuzionx] ${signal} received — shutting down`);
+            await this.emit('shutting-down', { signal });
+
+            // 1. 스케줄러 정지 (04-bootstrap-lifecycle.md)
+            if (this._scheduler) this._scheduler.stop();
+
+            // 2. 큐 drain — 처리 중 Task 완료 대기 (doc 04 순서 3)
+            if (this._queue && this._queue.pending > 0) {
+                this.logger.info(`[fuzionx] Draining queue (${this._queue.pending} pending)...`);
+                const drainTimeout = this.config.get('app.shutdown_timeout', 30000);
+                const start = Date.now();
+                while (this._queue.pending > 0 && (Date.now() - start) < drainTimeout) {
+                    await new Promise(r => setTimeout(r, 100));
+                }
+            }
+
+            // 3. DB 연결 해제 (ConnectionManager)
+            if (this._connectionManager) {
+                try { await this._connectionManager.closeAll(); } catch {}
+            }
+
+            // 3-1. Worker 종료
+            if (this._workerPool) {
+                try { await this._workerPool.terminate(); } catch {}
+            }
+
+            // 4. Bridge 서버 정지
+            if (this._coreApp?._bridge) {
+                try { this._coreApp._bridge.stopFusionServer(); } catch {}
+            }
+
+            await this.emit('shutdown');
+            setTimeout(() => process.exit(0), 2000);
+        };
+
+        process.once('SIGTERM', () => shutdown('SIGTERM'));
+        process.once('SIGINT', () => shutdown('SIGINT'));
+    }
+}