@fuzionx/framework 0.1.8 → 0.1.20

package/cli/db-sync.js

@@ -0,0 +1,99 @@
+/**
+ * db:sync — 모델 기반 스키마 SQL 생성
+ *
+ * 사용: fx db:sync [--dry-run]
+ *
+ * 모델의 static 멤버(table, primaryKey, timestamps, softDelete)에서
+ * CREATE TABLE SQL을 생성합니다. 실제 마이그레이션 시스템이 아닌
+ * 빠른 프로토타이핑용 도구입니다.
+ *
+ * @see docs/framework/02-database-orm.md
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 모델 클래스에서 CREATE TABLE SQL 생성
+ * @param {typeof import('../lib/Model.js').default} ModelClass
+ * @returns {string}
+ */
+export function generateCreateTable(ModelClass) {
+    const table = ModelClass.table;
+    const pk = ModelClass.primaryKey || 'id';
+    const timestamps = ModelClass.timestamps !== false;
+    const softDelete = ModelClass.softDelete || false;
+
+    if (!table) return '';
+
+    const columns = [];
+
+    // 기본키
+    columns.push(`  \`${pk}\` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY`);
+
+    // timestamps
+    if (timestamps) {
+        columns.push(`  \`created_at\` DATETIME DEFAULT CURRENT_TIMESTAMP`);
+        columns.push(`  \`updated_at\` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP`);
+    }
+
+    // softDelete
+    if (softDelete) {
+        columns.push(`  \`deleted_at\` DATETIME DEFAULT NULL`);
+    }
+
+    return `CREATE TABLE IF NOT EXISTS \`${table}\` (\n${columns.join(',\n')}\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;\n`;
+}
+
+/**
+ * 디렉토리의 모든 모델에서 SQL 생성
+ * @param {string} modelsDir
+ * @returns {Promise<string>}
+ */
+export async function generateSchema(modelsDir) {
+    const sqls = [];
+
+    try {
+        const entries = await fs.readdir(modelsDir, { withFileTypes: true });
+        const files = entries
+            .filter(e => e.isFile() && e.name.endsWith('.js') && !e.name.startsWith('.'))
+            .map(e => path.join(modelsDir, e.name));
+
+        for (const file of files) {
+            const mod = await import(file);
+            const ModelClass = mod.default;
+            if (ModelClass?.table) {
+                sqls.push(generateCreateTable(ModelClass));
+            }
+        }
+    } catch {
+        // 디렉토리 없음
+    }
+
+    return sqls.join('\n');
+}
+
+/**
+ * CLI 엔트리
+ */
+export async function run(args) {
+    const dryRun = args.includes('--dry-run');
+    const modelsDir = path.resolve('app/models');
+
+    console.log(`[db:sync] Scanning ${modelsDir}...`);
+
+    const sql = await generateSchema(modelsDir);
+
+    if (!sql) {
+        console.log('[db:sync] No models found.');
+        return;
+    }
+
+    if (dryRun) {
+        console.log('\n-- DRY RUN (preview only) --\n');
+        console.log(sql);
+    } else {
+        console.log('\n-- Generated SQL --\n');
+        console.log(sql);
+        console.log('-- Execute this SQL against your database to sync schema --');
+    }
+}

package/cli/fx.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from './index.js';
+run(process.argv.slice(2));

package/cli/index.js

@@ -0,0 +1,329 @@
+/**
+ * CLI — fx 명령어 핸들러
+ *
+ * fx new <name>                    앱 스캐폴딩
+ * 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>               테스트 생성
+ *
+ * @see docs/framework/16-cli.md
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } 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:* — 코드 생성
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const TYPE_DIRS = {
+    controller: 'controllers',
+    service: 'services',
+    model: 'models',
+    middleware: 'middleware',
+    job: 'jobs',
+    task: 'jobs',
+    ws: 'ws',
+    event: 'events',
+    worker: '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> — 코드 생성
+ * @param {string} type - 'controller', 'service', 'model', 등
+ * @param {string} name - PascalCase 이름 (e.g. 'User')
+ * @param {string} [baseDir='.'] - 프로젝트 루트
+ * @returns {Promise<string>} - 생성된 파일 경로
+ */
+export async function makeFile(type, name, baseDir = '.') {
+    const dir = TYPE_DIRS[type];
+    if (!dir) 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;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  fx new <name> — 앱 스캐폴딩
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const APP_FILES = [
+    { tpl: 'app/package.json.tpl', dest: 'package.json' },
+    { tpl: 'app/fuzionx.yaml.tpl', dest: 'fuzionx.yaml' },
+    { tpl: 'app/app.js.tpl', dest: 'app.js' },
+    { tpl: 'app/routes/web.js.tpl', dest: 'routes/web.js' },
+    { tpl: 'app/routes/api.js.tpl', dest: 'routes/api.js' },
+    { tpl: 'app/.env.example.tpl', dest: '.env.example' },
+    { tpl: 'app/.env.example.tpl', dest: '.env' },
+    { tpl: 'app/.gitignore.tpl', dest: '.gitignore' },
+];
+
+/** 스캐폴딩 디렉토리 (16-cli.md) */
+const APP_DIRS = [
+    'controllers',
+    'models',
+    'services',
+    'middleware',
+    'ws',
+    'jobs',
+    'events',
+    'workers',
+    'migrations',
+    'seeds',
+    'storage/logs',
+    'storage/uploads',
+    'public/css',
+    'public/js',
+    'locales',
+    'tests',
+];
+
+/**
+ * fx new <name> — 앱 스캐폴딩
+ * @param {string} name - 프로젝트 이름
+ * @param {string} [targetDir] - 기본: ./<name>
+ */
+export async function createApp(name, targetDir) {
+    const dir = targetDir || path.resolve(name);
+    const vars = {
+        name,
+        dbName: name.replace(/-/g, '_'),
+    };
+
+    // 디렉토리 생성
+    for (const d of APP_DIRS) {
+        await fs.mkdir(path.join(dir, d), { recursive: true });
+        await fs.writeFile(path.join(dir, d, '.gitkeep'), '');
+    }
+
+    // 템플릿 파일 생성
+    for (const { tpl, dest } of APP_FILES) {
+        const content = await loadTemplate(tpl, vars);
+        const fullPath = path.join(dir, dest);
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        await fs.writeFile(fullPath, content);
+    }
+
+    // HomeController 복사 (16-cli.md)
+    const hcSrc = path.join(TPL_DIR, 'app/controllers/HomeController.js');
+    const hcDst = path.join(dir, 'controllers/HomeController.js');
+    await fs.copyFile(hcSrc, hcDst);
+
+    // Views — views/{theme}/ 구조 (03, 16-cli.md)
+    const viewsSrc = path.join(TPL_DIR, 'app/views/default');
+    const viewsDst = path.join(dir, 'views/default');
+
+    // layouts/main.html
+    const layoutDir = path.join(viewsDst, 'layouts');
+    await fs.mkdir(layoutDir, { recursive: true });
+    await fs.copyFile(path.join(viewsSrc, 'layouts/main.html'), path.join(layoutDir, 'main.html'));
+
+    // pages/home.html
+    const pagesDir = path.join(viewsDst, 'pages');
+    await fs.mkdir(pagesDir, { recursive: true });
+    await fs.copyFile(path.join(viewsSrc, 'pages/home.html'), path.join(pagesDir, 'home.html'));
+
+    // errors/404.html, 500.html
+    const errDir = path.join(viewsDst, 'errors');
+    await fs.mkdir(errDir, { recursive: true });
+    await fs.copyFile(path.join(viewsSrc, 'errors/404.html'), path.join(errDir, '404.html'));
+    await fs.copyFile(path.join(viewsSrc, 'errors/500.html'), path.join(errDir, '500.html'));
+
+    return dir;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  CLI 엔트리
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * CLI 엔트리 (fx 명령어)
+ * @param {string[]} args - process.argv.slice(2)
+ */
+export async function run(args) {
+    const [command, ...rest] = args;
+
+    if (command === 'new') {
+        const name = rest[0];
+        if (!name) { console.error('Usage: fx new <name>'); process.exit(1); }
+        const dir = await createApp(name);
+        console.log(`✅ Created ${name} at ${dir}`);
+        console.log(`\n   cd ${name}`);
+        console.log(`   npm install`);
+        console.log(`   npm run dev\n`);
+        return;
+    }
+
+    if (command?.startsWith('make:')) {
+        const type = command.replace('make:', '');
+        const name = rest[0];
+        if (!name) { console.error(`Usage: fx ${command} <Name>`); process.exit(1); }
+        const file = await makeFile(type, name);
+        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 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(path.resolve('app.js'));
+            const app = appMod.default || appMod.app;
+            if (!app?._router) { console.error('Cannot load app routes'); return; }
+            const routes = app._router.getRoutes();
+            console.log('');
+            console.log('  METHOD   PATH                  HANDLER                   MIDDLEWARE');
+            console.log('  ──────   ─────                 ────────                  ──────────');
+            for (const r of routes) {
+                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(`  ${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('models');
+            const files = await fs.readdir(modelsDir);
+            const jsFiles = files.filter(f => f.endsWith('.js'));
+            console.log('\n📊 Model Schema Status:\n');
+            for (const file of jsFiles) {
+                const mod = await import(path.join(modelsDir, file));
+                const Model = mod.default;
+                if (!Model) continue;
+                const name = path.basename(file, '.js');
+                const table = Model.table || name.toLowerCase() + 's';
+                const cols = Object.keys(Model.columns || {});
+                const status = rest.includes('--apply') ? '✅ synced' : '⏳ pending';
+                console.log(`  ${name.padEnd(20)} table: ${table.padEnd(20)} columns: ${cols.length}  ${status}`);
+            }
+            if (!rest.includes('--apply')) {
+                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(`
+  fx new <name>              Create new app
+  fx make:controller <Name>  Create controller
+  fx make:service <Name>     Create service
+  fx make:model <Name>       Create model
+  fx make:middleware <Name>  Create middleware
+  fx make:job <Name>         Create job
+  fx make:task <Name>        Create task
+  fx make:ws <Name>          Create WsHandler
+  fx make:event <Name>       Create event handler
+  fx make:worker <Name>      Create worker (worker_threads)
+  fx make:test <Name>        Create test
+  fx dev                     Start dev server (--watch)
+  fx test                    Run tests
+  fx routes                  Print route table
+  fx config                  Print fuzionx.yaml
+  fx db:sync                 Sync models → DB (--apply)
+`);
+}

package/cli/templates/app/.env.example.tpl

@@ -0,0 +1,14 @@
+# .env — 이 파일을 .env로 복사 후 값을 채우세요
+
+# Database
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=
+DB_NAME={{dbName}}
+
+# Auth
+JWT_SECRET=
+
+# Redis (세션/큐 공용)
+REDIS_URL=

package/cli/templates/app/.gitignore.tpl

@@ -0,0 +1,4 @@
+.env
+node_modules/
+storage/logs/
+storage/uploads/

package/cli/templates/app/app.js.tpl

@@ -0,0 +1,14 @@
+import { Application } from '@fuzionx/framework';
+import webRoutes from './routes/web.js';
+import apiRoutes from './routes/api.js';
+
+const app = new Application({ configPath: './fuzionx.yaml' });
+
+app.routes(webRoutes);
+app.routes(apiRoutes);
+
+await app.boot();
+
+app.listen(49080, () => {
+    console.log('🚀 FuzionX running on http://localhost:49080');
+});

package/cli/templates/app/controllers/HomeController.js

@@ -0,0 +1,13 @@
+import { Controller } from '@fuzionx/framework';
+
+/**
+ * Home 컨트롤러.
+ * routes/web.js에서 라우트를 등록하세요.
+ */
+export default class HomeController extends Controller {
+
+    /** 홈 페이지 */
+    async index(ctx) {
+        ctx.render('pages/home');
+    }
+}

package/cli/templates/app/fuzionx.yaml.tpl

@@ -0,0 +1,32 @@
+# FuzionX Configuration
+bridge:
+  port: 49080
+  workers: 4
+  worker_timeout: 30
+
+  rate_limit:
+    enabled: true
+    per_ip: 1000
+
+database:
+  default: main
+  connections:
+    main:
+      driver: sqlite
+      database: ./storage/database.sqlite
+
+app:
+  name: '{{name}}'
+  environment: development
+  auth:
+    secret: 'change-me-in-production'
+    accessTtl: '15m'
+  i18n:
+    default_locale: 'ko'
+    fallback: 'en'
+  docs:
+    enabled: true
+    path: '/docs'
+
+themes:
+  default: 'default'

package/cli/templates/app/package.json.tpl

@@ -0,0 +1,15 @@
+{
+  "name": "{{name}}",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "fx dev",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@fuzionx/framework": "^0.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  }
+}

package/cli/templates/app/routes/api.js.tpl

@@ -0,0 +1,7 @@
+export default (r) => {
+    r.group('/api', (r) => {
+        r.get('/health', (ctx) => {
+            ctx.json({ status: 'ok', timestamp: Date.now() });
+        });
+    });
+};

package/cli/templates/app/routes/web.js.tpl

@@ -0,0 +1,5 @@
+export default (r) => {
+    r.get('/', (ctx) => {
+        ctx.render('home');
+    });
+};

package/cli/templates/app/views/default/errors/404.html

@@ -0,0 +1,15 @@
+{% extends "layouts/main.html" %}
+
+{% block title %}404 — 찾을 수 없습니다{% endblock %}
+
+{% block content %}
+<div style="text-align:center;padding:80px 20px;">
+    <h1 style="font-size:72px;color:#e74c3c;">{{ error.code }}</h1>
+    <p style="font-size:20px;margin:16px 0;">{{ error.message }}</p>
+    <p style="color:#888;">요청: {{ request.url }}</p>
+    {% if config.debug %}
+        <pre style="text-align:left;max-width:600px;margin:24px auto;background:#f5f5f5;padding:16px;border-radius:8px;overflow:auto;">{{ error.stack }}</pre>
+    {% endif %}
+    <a href="/" style="display:inline-block;margin-top:24px;padding:12px 24px;background:#e74c3c;color:#fff;text-decoration:none;border-radius:6px;">홈으로 돌아가기</a>
+</div>
+{% endblock %}

package/cli/templates/app/views/default/errors/500.html

@@ -0,0 +1,14 @@
+{% extends "layouts/main.html" %}
+
+{% block title %}500 — 서버 오류{% endblock %}
+
+{% block content %}
+<div style="text-align:center;padding:80px 20px;">
+    <h1 style="font-size:72px;color:#e74c3c;">500</h1>
+    <p style="font-size:20px;margin:16px 0;">{{ error.message | default(value='Internal Server Error') }}</p>
+    {% if config.debug and error.stack %}
+        <pre style="text-align:left;max-width:600px;margin:24px auto;background:#f5f5f5;padding:16px;border-radius:8px;overflow:auto;">{{ error.stack }}</pre>
+    {% endif %}
+    <a href="/" style="display:inline-block;margin-top:24px;padding:12px 24px;background:#e74c3c;color:#fff;text-decoration:none;border-radius:6px;">홈으로 돌아가기</a>
+</div>
+{% endblock %}

package/cli/templates/app/views/default/layouts/main.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="{{ locale | default(value='ko') }}">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>{% block title %}{{ config.app.name | default(value='FuzionX') }}{% endblock %}</title>
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body { font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; color: #333; }
+    </style>
+    {% block head %}{% endblock %}
+</head>
+<body>
+    {% include "partials/header.html" ignore missing %}
+
+    <main>
+        {% block content %}{% endblock %}
+    </main>
+
+    {% include "partials/footer.html" ignore missing %}
+</body>
+</html>