@fuzionx/framework 0.1.42 → 0.1.44

package/cli/index.js

@@ -1,494 +1,494 @@
-/**
- * CLI — fx 명령어 핸들러
- *
- * fx make:app --type=ssr|spa       앱 디렉토리 생성 (고정 이름)
- * fx make:controller <Name>        컨트롤러 생성
- * fx make:service <Name>           서비스 생성
- * fx make:model <Name>             모델 생성
- * fx make:middleware <Name>        미들웨어 생성
- * fx make:job <Name>               Job 생성
- * fx make:task <Name>              Task 생성
- * fx make:ws <Name>                WsHandler 생성
- * fx make:event <Name>              이벤트 핸들러 생성
- * fx make:worker <Name>             Worker 생성
- * fx make:test <Name>               테스트 생성
- * fx dev:spa                       FuzionX + Vite 동시 실행
- * fx build:spa                     Vite 프로덕션 빌드
- *
- * @see docs/framework/16-cli.md
- */
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { pathToFileURL } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const TPL_DIR = path.join(__dirname, 'templates');
-
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-//  Template Engine
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-/**
- * 간단 템플릿 치환 — {{varName}} → value
- * @param {string} template
- * @param {object} vars - { Name, name, nameLower, tableName, dbName }
- * @returns {string}
- */
-function render(template, vars) {
-    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? '');
-}
-
-/**
- * 템플릿 파일 읽기 + 치환
- * @param {string} relativePath - templates/ 기준 상대 경로
- * @param {object} vars
- * @returns {Promise<string>}
- */
-async function loadTemplate(relativePath, vars = {}) {
-    const content = await fs.readFile(path.join(TPL_DIR, relativePath), 'utf-8');
-    return render(content, vars);
-}
-
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-//  fx make:* — 코드 생성
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-/** 앱별 파일 (--app 필수) */
-const APP_TYPE_DIRS = {
-    controller: 'controllers',
-    service: 'services',
-    middleware: 'middleware',
-    ws: 'ws',
-};
-
-/** 공유 파일 (앱 무관) */
-const SHARED_TYPE_DIRS = {
-    model: 'database/models',
-    job: 'shared/jobs',
-    task: 'shared/jobs',
-    event: 'shared/events',
-    worker: 'shared/workers',
-    test: 'tests',
-};
-
-const TYPE_SUFFIXES = {
-    controller: 'Controller',
-    service: 'Service',
-    model: '',
-    middleware: 'Middleware',
-    job: 'Job',
-    task: '',
-    ws: 'Handler',
-    event: '',
-    worker: '',
-    test: '.test',
-};
-
-/**
- * fx make:<type> <Name> [--app=<appName>] — 코드 생성
- * @param {string} type - 'controller', 'service', 'model', 등
- * @param {string} name - PascalCase 이름 (e.g. 'User')
- * @param {string} [baseDir='.'] - 프로젝트 루트
- * @param {string} [appName] - 앱 이름 (controller/service/middleware/ws 시 필수)
- * @returns {Promise<string>} - 생성된 파일 경로
- */
-export async function makeFile(type, name, baseDir = '.', appName) {
-    let dir;
-    if (APP_TYPE_DIRS[type]) {
-        if (!appName) throw new Error(`--app option required for make:${type} (e.g. fx make:${type} ${name} --app=fuzionx)`);
-        dir = `app/${appName}/${APP_TYPE_DIRS[type]}`;
-    } else if (SHARED_TYPE_DIRS[type]) {
-        dir = SHARED_TYPE_DIRS[type];
-    } else {
-        throw new Error(`Unknown type: ${type}`);
-    }
-
-    const suffix = TYPE_SUFFIXES[type];
-    const fileName = `${name}${suffix}.js`;
-    const filePath = path.join(baseDir, dir, fileName);
-
-    const vars = {
-        Name: name,
-        name: name,
-        nameLower: name.toLowerCase(),
-        tableName: name.toLowerCase() + 's',
-    };
-
-    const content = await loadTemplate(`make/${type}.js.tpl`, vars);
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, content);
-
-    return filePath;
-}
-
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-//  유틸리티
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-/** 디렉토리 재귀 복사 (템플릿 → 프로젝트) */
-async function copyDirRecursive(src, dst) {
-    await fs.mkdir(dst, { recursive: true });
-    const entries = await fs.readdir(src, { withFileTypes: true });
-    for (const entry of entries) {
-        const srcPath = path.join(src, entry.name);
-        const dstPath = path.join(dst, entry.name);
-        if (entry.isDirectory()) {
-            await copyDirRecursive(srcPath, dstPath);
-        } else {
-            await fs.copyFile(srcPath, dstPath);
-        }
-    }
-}
-
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-//  CLI 엔트리
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-/**
- * CLI 엔트리 (fx 명령어)
- * @param {string[]} args - process.argv.slice(2)
- */
-export async function run(args) {
-    const [command, ...rest] = args;
-
-    // ── fx new → create-fuzionx 안내 ──
-    if (command === 'new') {
-        console.log(`\n  프로젝트 생성은 create-fuzionx를 사용하세요:\n`);
-        console.log(`    npx create-fuzionx <name>\n`);
-        return;
-    }
-
-    if (command === 'make:app') {
-        const typeFlag = rest.find(a => a.startsWith('--type='));
-        const type = typeFlag?.split('=')[1] || rest[0];
-        const validTypes = ['ssr', 'spa'];
-
-        if (!type || !validTypes.includes(type)) {
-            console.error(`Usage: fx make:app --type=ssr|spa`);
-            console.error(`  Available types: ${validTypes.join(', ')}`);
-            process.exit(1);
-        }
-
-        // 앱 이름은 타입에 따라 고정
-        const appName = type;
-        const appDir = path.join('.', 'app', appName);
-
-        // 기존 앱 확인
-        try {
-            await fs.access(appDir);
-            console.error(`❌ app/${appName}/ already exists.`);
-            process.exit(1);
-        } catch { /* 없으면 정상 */ }
-
-        // 빈 디렉토리 생성
-        for (const d of ['services', 'middleware', 'ws']) {
-            const fullDir = path.join(appDir, d);
-            await fs.mkdir(fullDir, { recursive: true });
-            await fs.writeFile(path.join(fullDir, '.gitkeep'), '');
-        }
-
-        // 기본 파일 복사 (HomeController, routes, views)
-        const appTplDir = path.join(TPL_DIR, 'make/app');
-        await copyDirRecursive(appTplDir, appDir);
-
-        console.log(`✅ Created app/${appName}/ (type: ${type})`);
-        console.log(`\n   fuzionx.yaml의 apps에 추가하세요:`);
-        console.log(`   "127.0.0.1:49080": ${appName}\n`);
-        return;
-    }
-
-    if (command?.startsWith('make:')) {
-        const type = command.replace('make:', '');
-        const name = rest[0];
-        if (!name) { console.error(`Usage: fx ${command} <Name> [--app=<appName>]`); process.exit(1); }
-        const appFlag = rest.find(a => a.startsWith('--app='));
-        const appName = appFlag?.split('=')[1] || undefined;
-        const file = await makeFile(type, name, '.', appName);
-        console.log(`✅ Created ${file}`);
-        return;
-    }
-
-    // ── fx dev — 개발 서버 (Node --watch) ──
-    if (command === 'dev') {
-        const { execSync } = await import('node:child_process');
-        const port = rest.find(a => a.startsWith('--port='))?.split('=')[1] || '';
-        const entry = 'app.js';
-        const env = port ? `PORT=${port} ` : '';
-        console.log(`🚀 Starting dev server...`);
-        try {
-            execSync(`${env}node --watch ${entry}`, { stdio: 'inherit', cwd: process.cwd() });
-        } catch {}
-        return;
-    }
-
-    // ── fx dev:spa — FuzionX + Vite HMR 동시 실행 ──
-    if (command === 'dev:spa') {
-        const { execSync } = await import('node:child_process');
-        const spaDir = path.resolve('app/spa/views/default/spa');
-        try {
-            await fs.access(spaDir);
-        } catch {
-            console.error('❌ app/spa/views/default/spa/ 디렉토리가 없습니다.');
-            console.error('   fx make:app --type=spa 로 SPA 앱을 먼저 생성하세요.');
-            process.exit(1);
-        }
-        console.log(`🚀 Starting dev server + Vite HMR...`);
-        try {
-            execSync(
-                'npx concurrently "node --watch app.js" "cd app/spa/views/default/spa && npx vite"',
-                { stdio: 'inherit', cwd: process.cwd() },
-            );
-        } catch {}
-        return;
-    }
-
-    // ── fx build:spa — Vite 프로덕션 빌드 ──
-    if (command === 'build:spa') {
-        const { execSync } = await import('node:child_process');
-        const spaDir = path.resolve('app/spa/views/default/spa');
-        try {
-            await fs.access(spaDir);
-        } catch {
-            console.error('❌ app/spa/views/default/spa/ 디렉토리가 없습니다.');
-            process.exit(1);
-        }
-        console.log(`📦 Building SPA for production...`);
-        try {
-            execSync('npx vite build', { stdio: 'inherit', cwd: spaDir });
-            console.log('\n✅ Build complete → public/dist/');
-        } catch { process.exit(1); }
-        return;
-    }
-
-    // ── fx stop — 서버 종료 ──
-    if (command === 'stop') {
-        const pidFile = path.resolve('fuzionx.pid');
-        try {
-            const pid = parseInt(await fs.readFile(pidFile, 'utf-8'), 10);
-            console.log(`🛑 Stopping PID ${pid}...`);
-            process.kill(pid, 'SIGTERM');
-            for (let i = 0; i < 50; i++) {
-                await new Promise(r => setTimeout(r, 100));
-                try { process.kill(pid, 0); } catch { break; }
-            }
-            await fs.unlink(pidFile).catch(() => {});
-            console.log('✅ Server stopped.');
-        } catch (err) {
-            if (err.code === 'ENOENT') {
-                console.log('⚠️  fuzionx.pid 없음 — 서버가 실행 중이 아닙니다.');
-            } else if (err.code === 'ESRCH') {
-                await fs.unlink(pidFile).catch(() => {});
-                console.log('⚠️  PID 프로세스가 이미 종료됨. PID 파일 삭제.');
-            } else {
-                console.error('❌ 종료 실패:', err.message);
-            }
-        }
-        return;
-    }
-
-    // ── fx restart — 서버 재시작 ──
-    if (command === 'restart') {
-        const pidFile = path.resolve('fuzionx.pid');
-        try {
-            const pid = parseInt(await fs.readFile(pidFile, 'utf-8'), 10);
-            console.log(`🔄 Stopping PID ${pid}...`);
-            process.kill(pid, 'SIGTERM');
-            for (let i = 0; i < 50; i++) {
-                await new Promise(r => setTimeout(r, 100));
-                try { process.kill(pid, 0); } catch { break; }
-            }
-        } catch (err) {
-            if (err.code === 'ENOENT') {
-                console.log('⚠️  fuzionx.pid 없음 — 새로 시작합니다.');
-            } else if (err.code === 'ESRCH') {
-                console.log('⚠️  PID 프로세스가 이미 종료됨.');
-            } else {
-                console.error('❌ 종료 실패:', err.message);
-            }
-        }
-        // 백그라운드로 재시작
-        const { spawn } = await import('node:child_process');
-        const logDir = path.resolve('storage/logs');
-        await fs.mkdir(logDir, { recursive: true });
-        const logFile = path.join(logDir, 'server.log');
-        const { openSync } = await import('node:fs');
-        const out = openSync(logFile, 'a');
-        const child = spawn('node', ['app.js'], {
-            cwd: process.cwd(),
-            detached: true,
-            stdio: ['ignore', out, out],
-        });
-        child.unref();
-        console.log(`🚀 Restarted (PID ${child.pid}) — logs: storage/logs/server.log`);
-        return;
-    }
-
-    // ── fx test — 테스트 실행 ──
-    if (command === 'test') {
-        const { execSync } = await import('node:child_process');
-        try {
-            execSync('npx vitest run', { stdio: 'inherit', cwd: process.cwd() });
-        } catch { process.exit(1); }
-        return;
-    }
-
-    // ── fx routes — 라우트 테이블 출력 ──
-    if (command === 'routes') {
-        try {
-            const appMod = await import(pathToFileURL(path.resolve('app.js')).href);
-            const app = appMod.default || appMod.app;
-            if (!app?._appRegistry) { console.error('Cannot load app routes'); return; }
-            console.log('');
-            console.log('  APP        METHOD   PATH                  HANDLER                   MIDDLEWARE');
-            console.log('  ──────     ──────   ─────                 ────────                  ──────────');
-            for (const [appName, appEntry] of app._appRegistry) {
-                const routes = appEntry.router.getRoutes();
-                for (const r of routes) {
-                    const aName = appName.padEnd(10);
-                    const method = r.method.padEnd(8);
-                    const rPath = r.path.padEnd(22);
-                    const handler = r.handler?.__handler__
-                        ? `${r.handler.controller?.name || ''}.${r.handler.method}`
-                        : (typeof r.handler === 'function' ? r.handler.name || 'anonymous' : '');
-                    const mw = (r.middleware || []).join(', ');
-                    console.log(`  ${aName} ${method} ${rPath} ${handler.padEnd(26)} ${mw}`);
-                }
-            }
-            console.log('');
-        } catch (err) { console.error('Failed to load routes:', err.message); }
-        return;
-    }
-
-    // ── fx config — fuzionx.yaml 출력 ──
-    if (command === 'config') {
-        try {
-            const configPath = path.resolve('fuzionx.yaml');
-            const content = await fs.readFile(configPath, 'utf-8');
-            console.log('\n📄 fuzionx.yaml:\n');
-            console.log(content);
-        } catch (err) { console.error('Cannot read fuzionx.yaml:', err.message); }
-        return;
-    }
-
-    // ── fx db:sync — 모델 ↔ DB 스키마 diff ──
-    if (command === 'db:sync') {
-        try {
-            const modelsDir = path.resolve('database/models');
-            const files = await fs.readdir(modelsDir);
-            const jsFiles = files.filter(f => f.endsWith('.js'));
-            const apply = rest.includes('--apply');
-
-            // fuzionx.yaml에서 DB 경로 읽기
-            let dbPath = './storage/database.sqlite';
-            try {
-                const yaml = await fs.readFile(path.resolve('fuzionx.yaml'), 'utf8');
-                const dbMatch = yaml.match(/database:\s*(.+\.sqlite)/);
-                if (dbMatch) dbPath = dbMatch[1].trim();
-            } catch {}
-
-            console.log('\n📊 Model Schema Status:\n');
-            const models = [];
-
-            for (const file of jsFiles) {
-                const mod = await import(pathToFileURL(path.join(modelsDir, file)).href);
-                const Model = mod.default;
-                if (!Model) continue;
-                const name = path.basename(file, '.js');
-                const table = Model.table || name.toLowerCase() + 's';
-                const cols = Model.columns || {};
-                models.push({ name, table, cols });
-            }
-
-            if (apply) {
-                // SQLite DB 열기
-                const resolvedDbPath = path.resolve(dbPath);
-                await fs.mkdir(path.dirname(resolvedDbPath), { recursive: true });
-                const { default: Database } = await import('better-sqlite3');
-                const db = new Database(resolvedDbPath);
-
-                for (const { name, table, cols } of models) {
-                    const colDefs = [];
-                    for (const [col, def] of Object.entries(cols)) {
-                        if (def.type === 'increments') {
-                            colDefs.push(`\`${col}\` INTEGER PRIMARY KEY AUTOINCREMENT`);
-                        } else if (def.type === 'integer') {
-                            colDefs.push(`\`${col}\` INTEGER NOT NULL DEFAULT 0`);
-                        } else if (def.type === 'text') {
-                            colDefs.push(`\`${col}\` TEXT NOT NULL DEFAULT ''`);
-                        } else if (def.type === 'datetime') {
-                            colDefs.push(`\`${col}\` DATETIME DEFAULT CURRENT_TIMESTAMP`);
-                        } else if (def.type === 'boolean') {
-                            colDefs.push(`\`${col}\` INTEGER NOT NULL DEFAULT 0`);
-                        } else {
-                            // string, etc.
-                            const unique = def.unique ? ' UNIQUE' : '';
-                            const dflt = def.default != null ? ` DEFAULT '${def.default}'` : " DEFAULT ''";
-                            colDefs.push(`\`${col}\` TEXT NOT NULL${dflt}${unique}`);
-                        }
-                    }
-                    const sql = `CREATE TABLE IF NOT EXISTS \`${table}\` (\n  ${colDefs.join(',\n  ')}\n)`;
-                    db.exec(sql);
-
-                    // ── 기존 테이블에 누락된 컬럼 추가 (ALTER TABLE) ──
-                    const existingCols = db.pragma(`table_info(${table})`).map(c => c.name);
-                    let addedCols = 0;
-                    for (const [col, def] of Object.entries(cols)) {
-                        if (existingCols.includes(col)) continue;
-
-                        let colSql;
-                        if (def.type === 'integer') {
-                            colSql = `INTEGER NOT NULL DEFAULT 0`;
-                        } else if (def.type === 'text') {
-                            colSql = `TEXT NOT NULL DEFAULT ''`;
-                        } else if (def.type === 'datetime') {
-                            colSql = `DATETIME DEFAULT NULL`;
-                        } else if (def.type === 'boolean') {
-                            colSql = `INTEGER NOT NULL DEFAULT 0`;
-                        } else {
-                            const dflt = def.default != null ? `'${def.default}'` : "''";
-                            colSql = `TEXT DEFAULT ${dflt}`;
-                        }
-                        db.exec(`ALTER TABLE \`${table}\` ADD COLUMN \`${col}\` ${colSql}`);
-                        addedCols++;
-                    }
-                    const status = addedCols > 0 ? `✅ synced (+${addedCols} columns)` : '✅ synced';
-                    console.log(`  ${name.padEnd(20)} table: ${table.padEnd(20)} columns: ${Object.keys(cols).length}  ${status}`);
-                }
-                db.close();
-                console.log(`\n  Database: ${path.resolve(dbPath)}`);
-            } else {
-                for (const { name, table, cols } of models) {
-                    console.log(`  ${name.padEnd(20)} table: ${table.padEnd(20)} columns: ${Object.keys(cols).length}  ⏳ pending`);
-                }
-                console.log('\n  Run with --apply to sync changes to database.');
-            }
-            console.log('');
-        } catch (err) { console.error('db:sync error:', err.message); }
-        return;
-    }
-
-    console.log(`
-  npx create-fuzionx <name>         Create new project
-  fx make:app --type=ssr|spa       Create app (fixed name: app/ssr or app/spa)
-  fx make:controller <Name> --app=  Create controller (app-specific)
-  fx make:service <Name> --app=     Create service (app-specific)
-  fx make:model <Name>              Create model (database/models)
-  fx make:middleware <Name> --app=   Create middleware (app-specific)
-  fx make:job <Name>                Create job (shared/jobs)
-  fx make:task <Name>               Create task (shared/jobs)
-  fx make:ws <Name> --app=          Create WsHandler (app-specific)
-  fx make:event <Name>              Create event handler (shared/events)
-  fx make:worker <Name>             Create worker (shared/workers)
-  fx make:test <Name>               Create test
-  fx dev                            Start dev server (--watch)
-  fx dev:spa                        Start dev server + Vite HMR
-  fx build:spa                      Build SPA for production
-  fx stop                            Stop server (graceful)
-  fx restart                         Restart server (graceful)
-  fx test                           Run tests
-  fx routes                         Print route table
-  fx config                         Print fuzionx.yaml
-  fx db:sync                        Sync models → DB (--apply)
-`);
-}
+/**
+ * CLI — fx 명령어 핸들러
+ *
+ * fx make:app --type=ssr|spa       앱 디렉토리 생성 (고정 이름)
+ * fx make:controller <Name>        컨트롤러 생성
+ * fx make:service <Name>           서비스 생성
+ * fx make:model <Name>             모델 생성
+ * fx make:middleware <Name>        미들웨어 생성
+ * fx make:job <Name>               Job 생성
+ * fx make:task <Name>              Task 생성
+ * fx make:ws <Name>                WsHandler 생성
+ * fx make:event <Name>              이벤트 핸들러 생성
+ * fx make:worker <Name>             Worker 생성
+ * fx make:test <Name>               테스트 생성
+ * fx dev:spa                       FuzionX + Vite 동시 실행
+ * fx build:spa                     Vite 프로덕션 빌드
+ *
+ * @see docs/framework/16-cli.md
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TPL_DIR = path.join(__dirname, 'templates');
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Template Engine
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * 간단 템플릿 치환 — {{varName}} → value
+ * @param {string} template
+ * @param {object} vars - { Name, name, nameLower, tableName, dbName }
+ * @returns {string}
+ */
+function render(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? '');
+}
+
+/**
+ * 템플릿 파일 읽기 + 치환
+ * @param {string} relativePath - templates/ 기준 상대 경로
+ * @param {object} vars
+ * @returns {Promise<string>}
+ */
+async function loadTemplate(relativePath, vars = {}) {
+    const content = await fs.readFile(path.join(TPL_DIR, relativePath), 'utf-8');
+    return render(content, vars);
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  fx make:* — 코드 생성
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/** 앱별 파일 (--app 필수) */
+const APP_TYPE_DIRS = {
+    controller: 'controllers',
+    service: 'services',
+    middleware: 'middleware',
+    ws: 'ws',
+};
+
+/** 공유 파일 (앱 무관) */
+const SHARED_TYPE_DIRS = {
+    model: 'database/models',
+    job: 'shared/jobs',
+    task: 'shared/jobs',
+    event: 'shared/events',
+    worker: 'shared/workers',
+    test: 'tests',
+};
+
+const TYPE_SUFFIXES = {
+    controller: 'Controller',
+    service: 'Service',
+    model: '',
+    middleware: 'Middleware',
+    job: 'Job',
+    task: '',
+    ws: 'Handler',
+    event: '',
+    worker: '',
+    test: '.test',
+};
+
+/**
+ * fx make:<type> <Name> [--app=<appName>] — 코드 생성
+ * @param {string} type - 'controller', 'service', 'model', 등
+ * @param {string} name - PascalCase 이름 (e.g. 'User')
+ * @param {string} [baseDir='.'] - 프로젝트 루트
+ * @param {string} [appName] - 앱 이름 (controller/service/middleware/ws 시 필수)
+ * @returns {Promise<string>} - 생성된 파일 경로
+ */
+export async function makeFile(type, name, baseDir = '.', appName) {
+    let dir;
+    if (APP_TYPE_DIRS[type]) {
+        if (!appName) throw new Error(`--app option required for make:${type} (e.g. fx make:${type} ${name} --app=fuzionx)`);
+        dir = `app/${appName}/${APP_TYPE_DIRS[type]}`;
+    } else if (SHARED_TYPE_DIRS[type]) {
+        dir = SHARED_TYPE_DIRS[type];
+    } else {
+        throw new Error(`Unknown type: ${type}`);
+    }
+
+    const suffix = TYPE_SUFFIXES[type];
+    const fileName = `${name}${suffix}.js`;
+    const filePath = path.join(baseDir, dir, fileName);
+
+    const vars = {
+        Name: name,
+        name: name,
+        nameLower: name.toLowerCase(),
+        tableName: name.toLowerCase() + 's',
+    };
+
+    const content = await loadTemplate(`make/${type}.js.tpl`, vars);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content);
+
+    return filePath;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  유틸리티
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/** 디렉토리 재귀 복사 (템플릿 → 프로젝트) */
+async function copyDirRecursive(src, dst) {
+    await fs.mkdir(dst, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const dstPath = path.join(dst, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirRecursive(srcPath, dstPath);
+        } else {
+            await fs.copyFile(srcPath, dstPath);
+        }
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  CLI 엔트리
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * CLI 엔트리 (fx 명령어)
+ * @param {string[]} args - process.argv.slice(2)
+ */
+export async function run(args) {
+    const [command, ...rest] = args;
+
+    // ── fx new → create-fuzionx 안내 ──
+    if (command === 'new') {
+        console.log(`\n  프로젝트 생성은 create-fuzionx를 사용하세요:\n`);
+        console.log(`    npx create-fuzionx <name>\n`);
+        return;
+    }
+
+    if (command === 'make:app') {
+        const typeFlag = rest.find(a => a.startsWith('--type='));
+        const type = typeFlag?.split('=')[1] || rest[0];
+        const validTypes = ['ssr', 'spa'];
+
+        if (!type || !validTypes.includes(type)) {
+            console.error(`Usage: fx make:app --type=ssr|spa`);
+            console.error(`  Available types: ${validTypes.join(', ')}`);
+            process.exit(1);
+        }
+
+        // 앱 이름은 타입에 따라 고정
+        const appName = type;
+        const appDir = path.join('.', 'app', appName);
+
+        // 기존 앱 확인
+        try {
+            await fs.access(appDir);
+            console.error(`❌ app/${appName}/ already exists.`);
+            process.exit(1);
+        } catch { /* 없으면 정상 */ }
+
+        // 빈 디렉토리 생성
+        for (const d of ['services', 'middleware', 'ws']) {
+            const fullDir = path.join(appDir, d);
+            await fs.mkdir(fullDir, { recursive: true });
+            await fs.writeFile(path.join(fullDir, '.gitkeep'), '');
+        }
+
+        // 기본 파일 복사 (HomeController, routes, views)
+        const appTplDir = path.join(TPL_DIR, 'make/app');
+        await copyDirRecursive(appTplDir, appDir);
+
+        console.log(`✅ Created app/${appName}/ (type: ${type})`);
+        console.log(`\n   fuzionx.yaml의 apps에 추가하세요:`);
+        console.log(`   "127.0.0.1:49080": ${appName}\n`);
+        return;
+    }
+
+    if (command?.startsWith('make:')) {
+        const type = command.replace('make:', '');
+        const name = rest[0];
+        if (!name) { console.error(`Usage: fx ${command} <Name> [--app=<appName>]`); process.exit(1); }
+        const appFlag = rest.find(a => a.startsWith('--app='));
+        const appName = appFlag?.split('=')[1] || undefined;
+        const file = await makeFile(type, name, '.', appName);
+        console.log(`✅ Created ${file}`);
+        return;
+    }
+
+    // ── fx dev — 개발 서버 (Node --watch) ──
+    if (command === 'dev') {
+        const { execSync } = await import('node:child_process');
+        const port = rest.find(a => a.startsWith('--port='))?.split('=')[1] || '';
+        const entry = 'app.js';
+        const env = port ? `PORT=${port} ` : '';
+        console.log(`🚀 Starting dev server...`);
+        try {
+            execSync(`${env}node --watch ${entry}`, { stdio: 'inherit', cwd: process.cwd() });
+        } catch {}
+        return;
+    }
+
+    // ── fx dev:spa — FuzionX + Vite HMR 동시 실행 ──
+    if (command === 'dev:spa') {
+        const { execSync } = await import('node:child_process');
+        const spaDir = path.resolve('app/spa/views/default/spa');
+        try {
+            await fs.access(spaDir);
+        } catch {
+            console.error('❌ app/spa/views/default/spa/ 디렉토리가 없습니다.');
+            console.error('   fx make:app --type=spa 로 SPA 앱을 먼저 생성하세요.');
+            process.exit(1);
+        }
+        console.log(`🚀 Starting dev server + Vite HMR...`);
+        try {
+            execSync(
+                'npx concurrently "node --watch app.js" "cd app/spa/views/default/spa && npx vite"',
+                { stdio: 'inherit', cwd: process.cwd() },
+            );
+        } catch {}
+        return;
+    }
+
+    // ── fx build:spa — Vite 프로덕션 빌드 ──
+    if (command === 'build:spa') {
+        const { execSync } = await import('node:child_process');
+        const spaDir = path.resolve('app/spa/views/default/spa');
+        try {
+            await fs.access(spaDir);
+        } catch {
+            console.error('❌ app/spa/views/default/spa/ 디렉토리가 없습니다.');
+            process.exit(1);
+        }
+        console.log(`📦 Building SPA for production...`);
+        try {
+            execSync('npx vite build', { stdio: 'inherit', cwd: spaDir });
+            console.log('\n✅ Build complete → public/dist/');
+        } catch { process.exit(1); }
+        return;
+    }
+
+    // ── fx stop — 서버 종료 ──
+    if (command === 'stop') {
+        const pidFile = path.resolve('fuzionx.pid');
+        try {
+            const pid = parseInt(await fs.readFile(pidFile, 'utf-8'), 10);
+            console.log(`🛑 Stopping PID ${pid}...`);
+            process.kill(pid, 'SIGTERM');
+            for (let i = 0; i < 50; i++) {
+                await new Promise(r => setTimeout(r, 100));
+                try { process.kill(pid, 0); } catch { break; }
+            }
+            await fs.unlink(pidFile).catch(() => {});
+            console.log('✅ Server stopped.');
+        } catch (err) {
+            if (err.code === 'ENOENT') {
+                console.log('⚠️  fuzionx.pid 없음 — 서버가 실행 중이 아닙니다.');
+            } else if (err.code === 'ESRCH') {
+                await fs.unlink(pidFile).catch(() => {});
+                console.log('⚠️  PID 프로세스가 이미 종료됨. PID 파일 삭제.');
+            } else {
+                console.error('❌ 종료 실패:', err.message);
+            }
+        }
+        return;
+    }
+
+    // ── fx restart — 서버 재시작 ──
+    if (command === 'restart') {
+        const pidFile = path.resolve('fuzionx.pid');
+        try {
+            const pid = parseInt(await fs.readFile(pidFile, 'utf-8'), 10);
+            console.log(`🔄 Stopping PID ${pid}...`);
+            process.kill(pid, 'SIGTERM');
+            for (let i = 0; i < 50; i++) {
+                await new Promise(r => setTimeout(r, 100));
+                try { process.kill(pid, 0); } catch { break; }
+            }
+        } catch (err) {
+            if (err.code === 'ENOENT') {
+                console.log('⚠️  fuzionx.pid 없음 — 새로 시작합니다.');
+            } else if (err.code === 'ESRCH') {
+                console.log('⚠️  PID 프로세스가 이미 종료됨.');
+            } else {
+                console.error('❌ 종료 실패:', err.message);
+            }
+        }
+        // 백그라운드로 재시작
+        const { spawn } = await import('node:child_process');
+        const logDir = path.resolve('storage/logs');
+        await fs.mkdir(logDir, { recursive: true });
+        const logFile = path.join(logDir, 'server.log');
+        const { openSync } = await import('node:fs');
+        const out = openSync(logFile, 'a');
+        const child = spawn('node', ['app.js'], {
+            cwd: process.cwd(),
+            detached: true,
+            stdio: ['ignore', out, out],
+        });
+        child.unref();
+        console.log(`🚀 Restarted (PID ${child.pid}) — logs: storage/logs/server.log`);
+        return;
+    }
+
+    // ── fx test — 테스트 실행 ──
+    if (command === 'test') {
+        const { execSync } = await import('node:child_process');
+        try {
+            execSync('npx vitest run', { stdio: 'inherit', cwd: process.cwd() });
+        } catch { process.exit(1); }
+        return;
+    }
+
+    // ── fx routes — 라우트 테이블 출력 ──
+    if (command === 'routes') {
+        try {
+            const appMod = await import(pathToFileURL(path.resolve('app.js')).href);
+            const app = appMod.default || appMod.app;
+            if (!app?._appRegistry) { console.error('Cannot load app routes'); return; }
+            console.log('');
+            console.log('  APP        METHOD   PATH                  HANDLER                   MIDDLEWARE');
+            console.log('  ──────     ──────   ─────                 ────────                  ──────────');
+            for (const [appName, appEntry] of app._appRegistry) {
+                const routes = appEntry.router.getRoutes();
+                for (const r of routes) {
+                    const aName = appName.padEnd(10);
+                    const method = r.method.padEnd(8);
+                    const rPath = r.path.padEnd(22);
+                    const handler = r.handler?.__handler__
+                        ? `${r.handler.controller?.name || ''}.${r.handler.method}`
+                        : (typeof r.handler === 'function' ? r.handler.name || 'anonymous' : '');
+                    const mw = (r.middleware || []).join(', ');
+                    console.log(`  ${aName} ${method} ${rPath} ${handler.padEnd(26)} ${mw}`);
+                }
+            }
+            console.log('');
+        } catch (err) { console.error('Failed to load routes:', err.message); }
+        return;
+    }
+
+    // ── fx config — fuzionx.yaml 출력 ──
+    if (command === 'config') {
+        try {
+            const configPath = path.resolve('fuzionx.yaml');
+            const content = await fs.readFile(configPath, 'utf-8');
+            console.log('\n📄 fuzionx.yaml:\n');
+            console.log(content);
+        } catch (err) { console.error('Cannot read fuzionx.yaml:', err.message); }
+        return;
+    }
+
+    // ── fx db:sync — 모델 ↔ DB 스키마 diff ──
+    if (command === 'db:sync') {
+        try {
+            const modelsDir = path.resolve('database/models');
+            const files = await fs.readdir(modelsDir);
+            const jsFiles = files.filter(f => f.endsWith('.js'));
+            const apply = rest.includes('--apply');
+
+            // fuzionx.yaml에서 DB 경로 읽기
+            let dbPath = './storage/database.sqlite';
+            try {
+                const yaml = await fs.readFile(path.resolve('fuzionx.yaml'), 'utf8');
+                const dbMatch = yaml.match(/database:\s*(.+\.sqlite)/);
+                if (dbMatch) dbPath = dbMatch[1].trim();
+            } catch {}
+
+            console.log('\n📊 Model Schema Status:\n');
+            const models = [];
+
+            for (const file of jsFiles) {
+                const mod = await import(pathToFileURL(path.join(modelsDir, file)).href);
+                const Model = mod.default;
+                if (!Model) continue;
+                const name = path.basename(file, '.js');
+                const table = Model.table || name.toLowerCase() + 's';
+                const cols = Model.columns || {};
+                models.push({ name, table, cols });
+            }
+
+            if (apply) {
+                // SQLite DB 열기
+                const resolvedDbPath = path.resolve(dbPath);
+                await fs.mkdir(path.dirname(resolvedDbPath), { recursive: true });
+                const { default: Database } = await import('better-sqlite3');
+                const db = new Database(resolvedDbPath);
+
+                for (const { name, table, cols } of models) {
+                    const colDefs = [];
+                    for (const [col, def] of Object.entries(cols)) {
+                        if (def.type === 'increments') {
+                            colDefs.push(`\`${col}\` INTEGER PRIMARY KEY AUTOINCREMENT`);
+                        } else if (def.type === 'integer') {
+                            colDefs.push(`\`${col}\` INTEGER NOT NULL DEFAULT 0`);
+                        } else if (def.type === 'text') {
+                            colDefs.push(`\`${col}\` TEXT NOT NULL DEFAULT ''`);
+                        } else if (def.type === 'datetime') {
+                            colDefs.push(`\`${col}\` DATETIME DEFAULT CURRENT_TIMESTAMP`);
+                        } else if (def.type === 'boolean') {
+                            colDefs.push(`\`${col}\` INTEGER NOT NULL DEFAULT 0`);
+                        } else {
+                            // string, etc.
+                            const unique = def.unique ? ' UNIQUE' : '';
+                            const dflt = def.default != null ? ` DEFAULT '${def.default}'` : " DEFAULT ''";
+                            colDefs.push(`\`${col}\` TEXT NOT NULL${dflt}${unique}`);
+                        }
+                    }
+                    const sql = `CREATE TABLE IF NOT EXISTS \`${table}\` (\n  ${colDefs.join(',\n  ')}\n)`;
+                    db.exec(sql);
+
+                    // ── 기존 테이블에 누락된 컬럼 추가 (ALTER TABLE) ──
+                    const existingCols = db.pragma(`table_info(${table})`).map(c => c.name);
+                    let addedCols = 0;
+                    for (const [col, def] of Object.entries(cols)) {
+                        if (existingCols.includes(col)) continue;
+
+                        let colSql;
+                        if (def.type === 'integer') {
+                            colSql = `INTEGER NOT NULL DEFAULT 0`;
+                        } else if (def.type === 'text') {
+                            colSql = `TEXT NOT NULL DEFAULT ''`;
+                        } else if (def.type === 'datetime') {
+                            colSql = `DATETIME DEFAULT NULL`;
+                        } else if (def.type === 'boolean') {
+                            colSql = `INTEGER NOT NULL DEFAULT 0`;
+                        } else {
+                            const dflt = def.default != null ? `'${def.default}'` : "''";
+                            colSql = `TEXT DEFAULT ${dflt}`;
+                        }
+                        db.exec(`ALTER TABLE \`${table}\` ADD COLUMN \`${col}\` ${colSql}`);
+                        addedCols++;
+                    }
+                    const status = addedCols > 0 ? `✅ synced (+${addedCols} columns)` : '✅ synced';
+                    console.log(`  ${name.padEnd(20)} table: ${table.padEnd(20)} columns: ${Object.keys(cols).length}  ${status}`);
+                }
+                db.close();
+                console.log(`\n  Database: ${path.resolve(dbPath)}`);
+            } else {
+                for (const { name, table, cols } of models) {
+                    console.log(`  ${name.padEnd(20)} table: ${table.padEnd(20)} columns: ${Object.keys(cols).length}  ⏳ pending`);
+                }
+                console.log('\n  Run with --apply to sync changes to database.');
+            }
+            console.log('');
+        } catch (err) { console.error('db:sync error:', err.message); }
+        return;
+    }
+
+    console.log(`
+  npx create-fuzionx <name>         Create new project
+  fx make:app --type=ssr|spa       Create app (fixed name: app/ssr or app/spa)
+  fx make:controller <Name> --app=  Create controller (app-specific)
+  fx make:service <Name> --app=     Create service (app-specific)
+  fx make:model <Name>              Create model (database/models)
+  fx make:middleware <Name> --app=   Create middleware (app-specific)
+  fx make:job <Name>                Create job (shared/jobs)
+  fx make:task <Name>               Create task (shared/jobs)
+  fx make:ws <Name> --app=          Create WsHandler (app-specific)
+  fx make:event <Name>              Create event handler (shared/events)
+  fx make:worker <Name>             Create worker (shared/workers)
+  fx make:test <Name>               Create test
+  fx dev                            Start dev server (--watch)
+  fx dev:spa                        Start dev server + Vite HMR
+  fx build:spa                      Build SPA for production
+  fx stop                            Stop server (graceful)
+  fx restart                         Restart server (graceful)
+  fx test                           Run tests
+  fx routes                         Print route table
+  fx config                         Print fuzionx.yaml
+  fx db:sync                        Sync models → DB (--apply)
+`);
+}