@fuzionx/framework 0.1.29 → 0.1.31

package/cli/index.js

@@ -1,7 +1,7 @@
 /**
  * CLI — fx 명령어 핸들러
  *
- * fx new <name>                    앱 스캐폴딩
+ * fx make:app --type=ssr|spa       앱 디렉토리 생성 (고정 이름)
  * fx make:controller <Name>        컨트롤러 생성
  * fx make:service <Name>           서비스 생성
  * fx make:model <Name>             모델 생성
@@ -12,6 +12,8 @@
  * 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
  */
@@ -120,24 +122,9 @@ export async function makeFile(type, name, baseDir = '.', appName) {
 }
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-//  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/.env.example.tpl', dest: '.env.example' },
-    { tpl: 'app/.env.example.tpl', dest: '.env' },
-    { tpl: 'app/.gitignore.tpl', dest: '.gitignore' },
-];
-
-/** fuzionx 앱 템플릿 (.tpl 파일은 치환, 그 외는 직접 복사) */
-const FUZIONX_TPL_FILES = [
-    { tpl: 'app/fuzionx/routes/web.js.tpl', dest: 'app/fuzionx/routes/web.js' },
-    { tpl: 'app/fuzionx/routes/api.js.tpl', dest: 'app/fuzionx/routes/api.js' },
-];
-
 /** 디렉토리 재귀 복사 (템플릿 → 프로젝트) */
 async function copyDirRecursive(src, dst) {
     await fs.mkdir(dst, { recursive: true });
@@ -153,91 +140,6 @@ async function copyDirRecursive(src, dst) {
     }
 }
 
-/** 스캐폴딩 디렉토리 (빈 디렉토리 + .gitkeep) */
-const APP_DIRS = [
-    // fuzionx 앱 (개발자 작업 영역)
-    'app/fuzionx/services',
-    'app/fuzionx/middleware',
-    'app/fuzionx/ws',
-    // tester 앱 (빈 폴더가 아닌 것은 copyDirRecursive로 처리)
-    // 인프라
-    'database/migrations',
-    'database/seeds',
-    'storage/logs',
-    'storage/uploads',
-    'public/css',
-    'public/js',
-    'tests',
-];
-
-/**
- * fx new <name> — 앱 스캐폴딩 (fuzionx + tester 2-app 구조)
- * @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, '_'),
-    };
-
-    // 빈 디렉토리 생성 (.gitkeep 포함)
-    for (const d of APP_DIRS) {
-        const fullDir = path.join(dir, d);
-        await fs.mkdir(fullDir, { recursive: true });
-        const files = await fs.readdir(fullDir).catch(() => []);
-        if (files.length === 0) {
-            await fs.writeFile(path.join(fullDir, '.gitkeep'), '');
-        }
-    }
-
-    // 루트 템플릿 파일 생성 (.tpl 치환)
-    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);
-    }
-
-    // fuzionx 앱 — .tpl 파일 (치환 필요)
-    for (const { tpl, dest } of FUZIONX_TPL_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);
-    }
-
-    // fuzionx 앱 — 직접 복사 (controllers, views)
-    const fuzionxSrc = path.join(TPL_DIR, 'app/fuzionx');
-    await copyDirRecursive(
-        path.join(fuzionxSrc, 'controllers'),
-        path.join(dir, 'app/fuzionx/controllers'),
-    );
-    await copyDirRecursive(
-        path.join(fuzionxSrc, 'views'),
-        path.join(dir, 'app/fuzionx/views'),
-    );
-
-    // tester 앱 — 전체 복사
-    const testerSrc = path.join(TPL_DIR, 'app/tester');
-    await copyDirRecursive(testerSrc, path.join(dir, 'app/tester'));
-
-    // shared — 전체 복사
-    const sharedSrc = path.join(TPL_DIR, 'app/shared');
-    await copyDirRecursive(sharedSrc, path.join(dir, 'shared'));
-
-    // database/models — 복사
-    const dbSrc = path.join(TPL_DIR, 'app/database');
-    await copyDirRecursive(dbSrc, path.join(dir, 'database'));
-
-    // locales — 복사
-    const localesSrc = path.join(TPL_DIR, 'app/locales');
-    await copyDirRecursive(localesSrc, path.join(dir, 'locales'));
-
-    return dir;
-}
-
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 //  CLI 엔트리
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -249,14 +151,49 @@ export async function createApp(name, targetDir) {
 export async function run(args) {
     const [command, ...rest] = args;
 
+    // ── fx new → create-fuzionx 안내 ──
     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`);
+        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;
     }
 
@@ -284,6 +221,108 @@ export async function run(args) {
         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');
@@ -337,18 +376,90 @@ export async function run(args) {
             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(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}`);
+                const cols = Model.columns || {};
+                models.push({ name, table, cols });
             }
-            if (!rest.includes('--apply')) {
+
+            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('');
@@ -357,7 +468,8 @@ export async function run(args) {
     }
 
     console.log(`
-  fx new <name>                    Create new app (multi-app structure)
+  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)
@@ -369,6 +481,10 @@ export async function run(args) {
   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

package/cli/templates/{app/fuzionx → make/app}/controllers/HomeController.js

@@ -7,6 +7,7 @@ import { Controller } from '@fuzionx/framework';
 export default class HomeController extends Controller {
 
     /** 홈 페이지 */
+    static index;
     async index(ctx) {
         ctx.render('home');
     }

package/cli/templates/{app/tester → make/app}/views/default/errors/404.html

@@ -6,10 +6,6 @@
 <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/fuzionx/views/default/errors/404.html → make/app/views/default/errors/500.html}

@@ -1,12 +1,11 @@
 {% extends "layouts/main.html" %}
 
-{% block title %}404 — 찾을 수 없습니다{% endblock %}
+{% block title %}500 — 서버 오류{% 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 %}

package/cli/templates/make/app/views/default/pages/home.html

@@ -0,0 +1,11 @@
+{% extends "layouts/main.html" %}
+
+{% block title %}Welcome{% endblock %}
+
+{% block content %}
+<div style="text-align:center;padding:80px 20px;">
+    <h1 style="font-size:48px;color:#333;">🚀 Welcome</h1>
+    <p style="font-size:18px;color:#666;margin:16px 0;">Your new app is ready.</p>
+    <p style="color:#999;font-size:14px;">Edit <code style="background:#f0f0f0;padding:2px 8px;border-radius:4px;">routes/web.js</code> to get started</p>
+</div>
+{% endblock %}

package/index.js

@@ -60,5 +60,8 @@ export { default as FileHelper } from './lib/helpers/FileHelper.js';
 export { default as View } from './lib/view/View.js';
 export { default as OpenAPI } from './lib/view/OpenAPI.js';
 
+// ── Utilities (Stateless) ──
+export { PaginationUtil, StrUtil, NumUtil, DateUtil, ArrUtil, FunctionUtil, ObjectUtil } from './lib/utilities/index.js';
+
 // ── Built-in Middleware ──
 export { bodyParser, cors, auth, apiAuth, csrf, session, theme } from './lib/middleware/index.js';

package/lib/core/Application.js

@@ -8,6 +8,8 @@
  * @see docs/framework/04-bootstrap-lifecycle.md
  */
 import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import cluster from 'node:cluster';
 import Config from './Config.js';
 import Context from './Context.js';
 import Router from '../http/Router.js';
@@ -427,10 +429,19 @@ export default class Application {
 
         if (!this._booted) await this.boot();
 
-        // 포트 사용 여부 확인 — primary에서만 (워커는 SO_REUSEPORT로 공유)
-        const cluster = await import('node:cluster');
-        if (!cluster.default?.isWorker) {
+        // PID 파일 생성 (primary만)
+        if (!cluster.isWorker) {
             await this._checkPort(port);
+            const pidPath = path.join(this.baseDir, 'fuzionx.pid');
+            await fs.writeFile(pidPath, String(process.pid));
+        }
+
+        // process.title 설정 (ps에서 보이는 프로세스 이름)
+        const appName = this.config.get('app.name', 'fuzionx');
+        if (cluster.isWorker) {
+            process.title = `${appName}-worker-${cluster.worker.id}`;
+        } else {
+            process.title = `${appName}-primary`;
         }
 
         await this.emit('ready');
@@ -458,6 +469,14 @@ export default class Application {
         }
 
         await this.emit('listening');
+
+        // Scheduler 시작 — primary 프로세스에서만 (워커 중복 실행 방지)
+        // fuzionx 상위 레이어가 cluster.fork()로 워커를 생성하므로
+        // cluster.isPrimary로 단일 프로세스 보장
+        if (this._scheduler && this._scheduler._jobs.length > 0 && !cluster.isWorker) {
+            this._scheduler.start();
+        }
+
         return this;
     }
 
@@ -619,9 +638,15 @@ export default class Application {
                 // 미들웨어 체인 사전 구성
                 const middlewareFns = [...this._globalMiddleware];
                 if (route.middleware?.length) {
-                    for (const mwName of route.middleware) {
-                        const fn = this.resolveMiddleware(mwName, appName);
-                        if (fn) middlewareFns.push(fn);
+                    for (const mw of route.middleware) {
+                        // 함수면 직접 사용 (built-in: auth(), cors() 등)
+                        // 문자열이면 resolveMiddleware로 클래스 기반 조회
+                        if (typeof mw === 'function') {
+                            middlewareFns.push(mw);
+                        } else if (typeof mw === 'string') {
+                            const fn = this.resolveMiddleware(mw, appName);
+                            if (fn) middlewareFns.push(fn);
+                        }
                     }
                 }
 

package/lib/core/Context.js

@@ -28,6 +28,7 @@ export default class Context {
         this.body = rawReq.body || null;
         this.ip = rawReq.remoteIp || '';
         this.files = rawReq.files || null;
+        this.uploadError = rawReq.uploadError || null;
         this.formFields = rawReq.formFields || null;
         this.handlerId = rawReq.handlerId;
 
@@ -306,6 +307,22 @@ export default class Context {
 
     render(view, data) {
         // 글로벌 변수 주입 (03-views-templates.md)
+        const bridge = this.app?._bridge;
+        let aspVars = {};
+        if (bridge?.getAspConfig && bridge?.cryptoEncryptCustom) {
+            try {
+                const aspCfg = JSON.parse(bridge.getAspConfig());
+                const clientSecret = this.app?.config?.get('app.client_secret') || '';
+                if (clientSecret && aspCfg.masterSecret) {
+                    aspVars = {
+                        _fx_client_secret: clientSecret,
+                        _fx_asp_secret: bridge.cryptoEncryptCustom(clientSecret, aspCfg.masterSecret),
+                        _fx_asp_header: aspCfg.headerSignal || 'Ruxy-Enc-Mode',
+                    };
+                }
+            } catch {}
+        }
+
         const globals = {
             session: this._rawSession,
             auth: { user: this.user },
@@ -315,6 +332,7 @@ export default class Context {
             flash: this.session?.getFlash() || {},
             theme: this.theme || this.app?.config?.get('themes.default', 'default') || 'default',
             locale: this.locale,
+            ...aspVars,
             ...data,
         };
 
@@ -336,11 +354,18 @@ export default class Context {
     /** @private */
     _createSession(rawReq, app) {
         const data = rawReq.session || {};
+        // Flash 추출 + 세션에서 삭제 (one-time read)
         const flash = { ...(data._flash || {}) };
+        const hadFlash = !!data._flash;
         delete data._flash;
         const sessionId = rawReq.sessionId || null;
         const bridge = app?._bridge || null;
 
+        // Flash 소비 후 세션 저장소에 즉시 반영
+        if (hadFlash && sessionId && bridge?.sessionSet) {
+            try { bridge.sessionSet(sessionId, { ...data }); } catch {}
+        }
+
         return {
             /** 세션 값 조회 */
             get: (key) => key ? (data[key] ?? null) : { ...data },
@@ -350,7 +375,11 @@ export default class Context {
                 data[key] = value;
                 // Core SessionProto 참조: bridge.sessionSet(id, { ...data })
                 if (sessionId && bridge?.sessionSet) {
-                    try { bridge.sessionSet(sessionId, { ...data }); } catch {}
+                    try {
+                        bridge.sessionSet(sessionId, { ...data });
+                    } catch (e) {
+                        console.error('[Session] sessionSet failed:', e?.message || e);
+                    }
                 }
             },
 

package/lib/helpers/I18nHelper.js

@@ -60,7 +60,6 @@ export default class I18nHelper {
      */
     translate(locale, key, vars = {}) {
         // ── Bridge N-API 위임 ──
-        // Core i18n.js 참조: bridge.i18NTranslate(locale, key)
         if (this._bridge && typeof this._bridge.i18NTranslate === 'function') {
             try {
                 const result = this._bridge.i18NTranslate(locale, key);
@@ -72,12 +71,18 @@ export default class I18nHelper {
         const messages = this._messages.get(locale)
             || this._messages.get(this.fallback)
             || this._messages.get(this.defaultLocale);
-        if (!messages) return vars.default || key;
 
-        const value = messages[key];
-        if (value == null) return vars.default || key;
+        const value = messages?.[key];
+        if (value != null) return this._substitute(value, vars);
 
-        return this._substitute(value, vars);
+        // ── auto_complete: 누락 키 자동 등록 ──
+        // default 값이 제공된 경우, Bridge에 누락 키를 보고하여
+        // 모든 locale 파일에 자동으로 추가한다.
+        if (vars.default) {
+            this.updateMissing(key, vars.default);
+        }
+
+        return vars.default || key;
     }
 
     /**
@@ -86,7 +91,6 @@ export default class I18nHelper {
      * @returns {object}
      */
     all(locale) {
-        // Bridge: i18NGetLocales() 는 locale 목록만 반환, 전체 데이터 API 없음
         const messages = this._messages.get(locale) || this._messages.get(this.defaultLocale);
         if (!messages) return {};
         return { ...messages };