bro-framework 2.4.5 → 3.0.0

package/README.md

@@ -84,6 +84,8 @@ export default defineConfig({
 
 `cors: false` disables HTTP CORS middleware. Helmet is enabled by default and can be disabled with `helmet: false`. Redis is optional; when configured it powers distributed rate limiting, route caching, and Socket.IO scaling. In `NODE_ENV=test`, bro.js can inject `ioredis-mock`; install it in the consuming project's development dependencies.
 
+> **Production Security Note**: When deploying behind a reverse proxy (Nginx, AWS ALB, Vercel, Render), ensure your load balancer properly sets `X-Forwarded-For`. Rate limiting and trusted IP functionality relies on this proxy configuration.
+
 ---
 
 ## The Core Experience
@@ -243,6 +245,40 @@ Handlers receive:
 
 For Redis-backed integration tests without an external Redis server, install `ioredis-mock` in the consuming project and run with `NODE_ENV=test`. bro.js injects a mock Redis client and exercises cache, rate-limit, Socket.IO adapter, and shutdown paths.
 
+### Supertest + Vitest Recipe
+
+You can programmatically bootstrap `bro.js` using `createServer` for blazing fast integration tests. Here's a complete `vitest` recipe:
+
+```javascript
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import request from 'supertest';
+import path from 'path';
+import { createServer } from 'bro-framework';
+import config from '../bro.config.js';
+
+describe('API Tests', () => {
+  let app, shutdown;
+
+  beforeAll(async () => {
+    // 1. Initialize the server programmatically
+    const instance = await createServer(config, path.resolve('./routes'), null);
+    app = instance.app;
+    shutdown = instance.shutdown;
+  });
+
+  afterAll(async () => {
+    // 2. Cleanly teardown tasks, redis, and sockets
+    if (shutdown) await shutdown();
+  });
+
+  it('should return a 200 from the healthcheck', async () => {
+    const res = await request(app).get('/health/live');
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe('ok');
+  });
+});
+```
+
 ---
 
 ## Architecture & Request Lifecycle
@@ -339,6 +375,14 @@ export const POST = defineRoute({
 
 ---
 
+## Compatibility Table
+
+| bro.js Version | Node.js   | Next.js App Router | Express | Zod     |
+| :------------- | :-------- | :----------------- | :------ | :------ |
+| `>= 2.0.0`     | `>= 18.x` | `>= 13.4.x`        | `4.x`   | `3.x`   |
+
+---
+
 ## Author & License
 
 - **Author**: Yass1n (@medyass1ne)

package/bin/bro.js

@@ -1,293 +1,195 @@
 #!/usr/bin/env node
-
-import path from 'path';
-import fs from 'fs';
-import { pathToFileURL } from 'url';
-import { register } from 'tsx/esm/api';
-
-register();
-
-import { createServer } from '../src/server.js';
-import { colors, printBanner, printRoute, printHotReload } from '../src/logger.js';
-import { generateSDK } from '../src/sdk.js';
-import dotenv from 'dotenv';
-import chokidar from 'chokidar';
-
-dotenv.config();
-
-const command = process.argv[2] || 'dev';
-
-if (command === 'dev') {
-  process.env.NODE_ENV = process.env.NODE_ENV || 'development';
-} else if (command === 'start') {
-  process.env.NODE_ENV = 'production';
-}
-
-const CONFIG_TEMPLATE = `import { defineConfig } from 'bro-framework';
-
-export default defineConfig({
-  // Server Settings
-  server: {
-    port: 5000,
-    cors: true, // Set to true to allow all, or pass a CORS options object
-    helmet: true // Enable security headers
-  },
-
-  // Authentication Settings
-  auth: {
-    jwtSecret: 'dev_secret_please_change',
-    expiresIn: '7d',
-    apiKey: process.env.API_KEY || ['dev_key_1', 'dev_key_2'] // Supports array for zero-downtime rotation
-  },
-
-  // Optional file-based API translations
-  // Add locale/en.js, locale/fr.js, etc.
-  locale: {
-    defaultLocale: 'en'
-  },
-  
-  // API Documentation (Scalar UI)
-  docs: process.env.NODE_ENV !== 'production', // Set to false to disable completely, or true to force in prod
-
-  // Rate Limiting
-  rateLimit: {
-    windowMs: 15 * 60 * 1000, // 15 minutes
-    max: 100 // limit each IP to 100 requests per windowMs
-  },
-
-  // Redis Configuration (Auto-scales WebSockets, distributed caches & rate-limiting)
-  redisUrl: process.env.REDIS_URL, // e.g., 'redis://localhost:6379'
-
-  // WebSockets Setup
-  sockets: async (io, db) => {
-    io.on('connection', (socket) => {
-      console.log('Client connected:', socket.id);
-    });
-  },
-
-  // Database Context Injection
-  // This instance will be injected into every route's ctx.db (if defined)
-  db: async () => {
-    // If you use a database, set up your connection here
-    // and return the connection instance or an object of your models.
-    // Could be MongoDB, MySQL, etc. (your choice)
-    // --- MONGOOSE EXAMPLE ---
-    // import mongoose from 'mongoose';
-    
-    // await mongoose.connect(process.env.MONGO_URI || 'mongodb://localhost:27017/bro_database');
-    // console.log("Connected to MongoDB");
-    
-    // You can return mongoose itself, or an object of your models 
-    // to access them instantly in your routes without importing them!
-    // Example: return { User, Post };
-    
-    // return mongoose.connection; 
-    // --------------------------
-    return null;
-  },
-
-  // Graceful Teardown Hook
-  onShutdown: async (db) => {
-    // Close application-owned database resources gracefully here
-  }
-});
-`;
-
-function scaffoldConfig() {
-  const configPath = path.join(process.cwd(), 'bro.config.js');
-  if (!fs.existsSync(configPath)) {
-    fs.writeFileSync(configPath, CONFIG_TEMPLATE, 'utf-8');
-    console.log(`\n  ${colors.green} Created default bro.config.js${colors.reset}\n`);
-  }
-}
-
-function ensureTypeModule() {
-  const pkgPath = path.join(process.cwd(), 'package.json');
-  
-  if (fs.existsSync(pkgPath)) {
-    try {
-      const pkgRaw = fs.readFileSync(pkgPath, 'utf-8');
-      const pkg = JSON.parse(pkgRaw);
-      
-      if (pkg.type !== 'module') {
-        pkg.type = 'module';
-        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2), 'utf-8');
-        console.log(`\n  ${colors.green} Auto-configured package.json for ES Modules${colors.reset}`);
-      }
-    } catch (err) {
-      console.error(`\n  ${colors.red} Failed to parse package.json for ES Modules setup${colors.reset}`, err);
-    }
-  } else {
-    const defaultPkg = {
-      name: "bro-app",
-      version: "1.0.0",
-      type: "module",
-      private: true
-    };
-    fs.writeFileSync(pkgPath, JSON.stringify(defaultPkg, null, 2), 'utf-8');
-    console.log(`\n  ${colors.green} Created package.json with ES Modules enabled${colors.reset}`);
-  }
-}
-
-if (command === 'init') {
-  ensureTypeModule();
-  scaffoldConfig();
-  process.exit(0);
-}
-
-if (['sdk', 'generate-client', 'client'].includes(command)) {
-  generateSDK().then(() => {
-    console.log(`\n  ${colors.green} bro-sdk.js generated successfully!${colors.reset}\n`);
-    process.exit(0);
-  }).catch(err => {
-    console.error(`\n  ${colors.red} Error generating SDK:${colors.reset}`, err.message);
-    process.exit(1);
-  });
-}
-
-async function bootstrap() {
-  if (command === 'dev') {
-    ensureTypeModule();
-    scaffoldConfig();
-  }
-
-  const startTime = performance.now();
-  
-  const cwd = process.cwd();
-  const configPath = path.join(cwd, 'bro.config.js');
-  const routesDir = path.join(cwd, 'routes');
-  
-  let globalConfig = {
-    port: process.env.PORT || 5000,
-    jwtSecret: process.env.JWT_SECRET || 'dev_secret_please_change'
-  };
-
-  let db = null;
-
-  if (fs.existsSync(configPath)) {
-    try {
-      const configModule = await import(pathToFileURL(configPath).href);
-      const userConfig = configModule.default || configModule.config || {};
-      
-      if (userConfig.server?.port) globalConfig.port = userConfig.server.port;
-      if (userConfig.auth?.jwtSecret) globalConfig.jwtSecret = userConfig.auth.jwtSecret;
-      
-      globalConfig = { ...globalConfig, ...userConfig };
-      
-      if (typeof globalConfig.db === 'function') {
-        db = await globalConfig.db();
-      } else if (globalConfig.db && typeof globalConfig.db.init === 'function') {
-        db = await globalConfig.db.init();
-      } else if (globalConfig.db) {
-        db = globalConfig.db;
-        if (db instanceof Promise) db = await db;
-      }
-    } catch (err) {
-      console.error('✗ Failed to load bro.config.js:', err);
-    }
-  }
-
-  if (globalConfig.env) {
-    const envResult = globalConfig.env.safeParse(process.env);
-    if (!envResult.success) {
-      console.error(`\n  ${colors.red} Environment Validation Failed${colors.reset}`);
-      envResult.error.errors.forEach(err => {
-        console.error(`  ${colors.dim}-${colors.reset} ${colors.bold}${err.path.join('.')}${colors.reset}: ${err.message}`);
-      });
-      console.error("");
-      process.exit(1);
-    }
-    globalConfig.envData = envResult.data;
-  }
-
-  if (!fs.existsSync(routesDir)) {
-    console.error(`✗ Error: 'routes' directory not found in ${cwd}`);
-    console.error(`  Please create a 'routes/' folder and add your first route.`);
-    process.exit(1);
-  }
-
-  const localeDir = globalConfig.locale?.directory || path.join(cwd, 'locale');
-  const tasksDir = path.join(cwd, 'tasks');
-  const { app, server, routes: initialRoutes, reload, reloadLocale, reloadTasks, io, shutdown } = await createServer(globalConfig, routesDir, db);
-  const port = globalConfig.port;
-  
-  let currentRoutes = initialRoutes;
-  
-  server.listen(port, async () => {
-    if (command === 'dev') {
-      console.clear();
-      printBanner(port, performance.now() - startTime);
-    } else if (command === 'start') {
-      console.log(`[bro.js] Server running in production on port ${port}`);
-    }
-    
-    if (command === 'dev') {
-      const printCurrentRoutes = (routesToPrint) => {
-        if (routesToPrint.length > 0) {
-          routesToPrint.forEach((r, i) => {
-            printRoute(r.method, r.path, r.auth, i === routesToPrint.length - 1);
-          });
-          console.log("");
-        } else {
-          console.log("  No routes found.\n");
-        }
-      };
-      
-      printCurrentRoutes(currentRoutes);
-
-      const localeGlob = localeDir.replace(/\\/g, '/') + '/*.{js,mjs,ts,json}';
-      const watcher = chokidar.watch([routesDir, localeGlob, tasksDir], { ignoreInitial: true });
-      
-      watcher.on('all', async (event, filepath) => {
-        const isValidFile = filepath.match(/\.(js|ts|mjs|json)$/);
-        if (!isValidFile) return;
-        const relLocale = path.relative(path.resolve(localeDir), filepath);
-        const isLocaleFile = !relLocale.startsWith('..') && !path.isAbsolute(relLocale);
-        
-        const relTask = path.relative(path.resolve(tasksDir), filepath);
-        const isTaskFile = !relTask.startsWith('..') && !path.isAbsolute(relTask);
-
-        try {
-          const reloadStartTime = performance.now();
-          if (isLocaleFile) {
-            await reloadLocale();
-          } else if (isTaskFile) {
-            await reloadTasks();
-          } else {
-            currentRoutes = await reload();
-          }
-          const reloadTimeMs = performance.now() - reloadStartTime;
-          
-          const fileType = isTaskFile ? 'Task' : (isLocaleFile ? 'Locale' : 'Route');
-          printHotReload(path.basename(filepath), event, reloadTimeMs, fileType);
-          printCurrentRoutes(currentRoutes);
-        } catch (err) {
-          const fileType = isTaskFile ? 'tasks' : (isLocaleFile ? 'locale' : 'routes');
-          console.error(`\n  ✗ Error hot-reloading ${fileType}:`, err);
-        }
-      });
-    }
-
-    const handleShutdown = async (signal) => {
-      console.log(`\n[bro.js] Received ${signal}. Shutting down gracefully...`);
-      await shutdown();
-      console.log('[bro.js] HTTP server closed.');
-      process.exit(0);
-    };
-
-    process.on('SIGINT', () => handleShutdown('SIGINT'));
-    process.on('SIGTERM', () => handleShutdown('SIGTERM'));
-  });
-}
-
-if (command === 'dev' || command === 'start') {
-  bootstrap();
-} else if (!['sdk', 'generate-client', 'client', 'init'].includes(command)) {
-  console.log(`\n  ${colors.bold}${colors.green}bro.js CLI${colors.reset}\n`);
-  console.log(`  ${colors.bold}Usage:${colors.reset} bro <command>\n`);
-  console.log(`  ${colors.bold}Commands:${colors.reset}`);
-  console.log(`    ${colors.cyan}dev${colors.reset}      Start the development server with hot-reload`);
-  console.log(`    ${colors.cyan}start${colors.reset}    Start the production server gracefully`);
-  console.log(`    ${colors.cyan}init${colors.reset}     Scaffold a new bro.config.js workspace`);
-  console.log(`    ${colors.cyan}sdk${colors.reset}      Generate a typed frontend client\n`);
-}
+
+import path from 'path';
+import fs from 'fs';
+import { pathToFileURL } from 'url';
+import { register } from 'tsx/esm/api';
+
+register();
+
+import { createServer } from '../src/server.js';
+import { colors, printBanner, printRoute, printHotReload } from '../src/logger.js';
+import { generateSDK } from '../src/sdk.js';
+import dotenv from 'dotenv';
+import chokidar from 'chokidar';
+
+dotenv.config();
+
+const command = process.argv[2] || 'dev';
+
+async function bootstrap() {
+  const startTime = performance.now();
+  const configPath = path.resolve(process.cwd(), 'bro.config.js');
+  let globalConfig = {};
+  
+  if (fs.existsSync(configPath)) {
+    try {
+      const configModule = await import(pathToFileURL(configPath).href);
+      globalConfig = configModule.default || configModule;
+    } catch (err) {
+      console.error('[bro.js] Error loading bro.config.js:', err);
+      process.exit(1);
+    }
+  }
+
+  const routesDir = globalConfig.routesDir || path.resolve(process.cwd(), 'api');
+  const localeDir = globalConfig.locale?.directory || path.resolve(process.cwd(), 'locale');
+  const tasksDir = globalConfig.tasksDir || path.resolve(process.cwd(), 'tasks');
+  const port = globalConfig.server?.port || process.env.PORT || 3000;
+
+  let db = null;
+  // Initialize db from globalConfig if provided (mocked here for CLI boot)
+  if (globalConfig.db && typeof globalConfig.db === 'function') {
+    db = await globalConfig.db();
+  } else {
+    db = globalConfig.db;
+  }
+
+  const { app, server, routes, reload, reloadLocale, shutdown } = await createServer(globalConfig, routesDir, db);
+  let currentRoutes = routes;
+
+  server.listen(port, () => {
+    if (command === 'dev') {
+      console.clear();
+      printBanner(port, performance.now() - startTime);
+
+      if (process.argv.includes('--ui')) {
+        import('../src/dashboard.js').then(({ startDashboard }) => {
+          startDashboard(globalConfig, currentRoutes);
+        }).catch(err => console.error('[bro.js] Error starting dashboard:', err));
+      }
+    } else if (command === 'start') {
+      console.log(`[bro.js] Server running in production on port ${port}`);
+    }
+  
+    if (command === 'dev') {
+      const printCurrentRoutes = (routesToPrint) => {
+        if (routesToPrint.length > 0) {
+          routesToPrint.forEach((r, i) => {
+            printRoute(r.method, r.path, r.auth, i === routesToPrint.length - 1);
+          });
+          console.log("");
+        } else {
+          console.log("  No routes found.\n");
+        }
+      };
+      
+      printCurrentRoutes(currentRoutes);
+
+      const localeGlob = localeDir.replace(/\\/g, '/') + '/*.{js,mjs,ts,json}';
+      const watcher = chokidar.watch([routesDir, localeGlob, tasksDir], { ignoreInitial: true });
+      
+      watcher.on('all', async (event, filepath) => {
+        const isValidFile = filepath.match(/\.(js|ts|mjs|json)$/);
+        if (!isValidFile) return;
+        const relLocale = path.relative(path.resolve(localeDir), filepath);
+        const isLocaleFile = !relLocale.startsWith('..') && !path.isAbsolute(relLocale);
+        
+        const relTask = path.relative(path.resolve(tasksDir), filepath);
+        const isTaskFile = !relTask.startsWith('..') && !path.isAbsolute(relTask);
+
+        try {
+          const reloadStartTime = performance.now();
+          if (isLocaleFile) {
+            await reloadLocale();
+          } else if (isTaskFile) {
+            // Tasks reload
+          } else {
+            currentRoutes = await reload();
+          }
+          const reloadTimeMs = performance.now() - reloadStartTime;
+          
+          const fileType = isTaskFile ? 'Task' : (isLocaleFile ? 'Locale' : 'Route');
+          printHotReload(path.basename(filepath), event, reloadTimeMs, fileType);
+          printCurrentRoutes(currentRoutes);
+        } catch (err) {
+          const fileType = isTaskFile ? 'tasks' : (isLocaleFile ? 'locale' : 'routes');
+          console.error(`\n  ✗ Error hot-reloading ${fileType}:`, err);
+        }
+      });
+    }
+
+    const handleShutdown = async (signal) => {
+      console.log(`\n[bro.js] Received ${signal}. Shutting down gracefully...`);
+      if (shutdown) await shutdown();
+      console.log('[bro.js] HTTP server closed.');
+      process.exit(0);
+    };
+
+    process.on('SIGINT', () => handleShutdown('SIGINT'));
+    process.on('SIGTERM', () => handleShutdown('SIGTERM'));
+  });
+}
+
+
+  if (command === 'test') {
+    const hasVitest = fs.existsSync(path.resolve(process.cwd(), 'node_modules', 'vitest'));
+    if (!hasVitest) {
+      console.error(colors.red + 'Vitest is not installed. Please run: npm install -D vitest' + colors.reset);
+      process.exit(1);
+    }
+
+  import('child_process').then(cp => {
+    console.log('\x1b[36m[bro.js]\x1b[0m Starting tests via vitest...');
+    cp.spawn('npx', ['vitest', ...process.argv.slice(3)], { stdio: 'inherit' });
+  });
+
+} else if (command === 'init') {
+  const configPath = path.resolve(process.cwd(), 'bro.config.js');
+  const envPath = path.resolve(process.cwd(), '.env.example');
+  if (!fs.existsSync(configPath)) {
+    fs.writeFileSync(configPath, `export default {
+  server: { port: 3000, cors: false },
+  auth: { jwtSecret: process.env.JWT_SECRET }
+};
+`);
+    console.log('[bro.js] Created bro.config.js');
+  }
+  if (!fs.existsSync(envPath)) {
+    fs.writeFileSync(envPath, 'JWT_SECRET=\n');
+    console.log('[bro.js] Created .env.example');
+  }
+} else if (command === 'doctor') {
+  console.log('[bro.js] Running doctor...');
+  const configPath = path.resolve(process.cwd(), 'bro.config.js');
+  if (!fs.existsSync(configPath)) {
+    console.error('✗ No bro.config.js found.');
+  } else {
+    import(pathToFileURL(configPath).href).then(m => {
+      const config = m.default || m;
+      if (config.server?.cors === true) console.error('✗ Permissive CORS is enabled (cors: true). Use an array of allowed origins.');
+      else console.log('✓ CORS is strict.');
+      
+      if (['dev_secret_please_change', 'bro_default_secret_key', 'your_jwt_secret_here'].includes(config.auth?.jwtSecret)) {
+        console.error('✗ Hardcoded insecure JWT secret detected.');
+      } else {
+        console.log('✓ Secrets look ok.');
+      }
+    });
+  }
+} else if (command === 'sdk' || command === 'client' || command === 'generate-client') {
+  const sdkOutPath = process.argv[3] || './client.ts';
+  const routesDir = path.resolve(process.cwd(), 'api');
+  generateSDK(routesDir, sdkOutPath).then(() => {
+    console.log(`\x1b[32m✓ SDK successfully generated at ${sdkOutPath}\x1b[0m`);
+  }).catch(err => {
+    console.error('\x1b[31m✗ Failed to generate SDK:\x1b[0m', err);
+  });
+} else if (command === 'studio') {
+  import('../src/studio.js').then(({ startStudio }) => {
+    startStudio(process.cwd());
+  }).catch(err => console.error('[bro.js] Error starting studio:', err));
+} else if (command === 'dev' || command === 'start') {
+  bootstrap();
+} else if (!['init', 'doctor'].includes(command)) {
+  console.log(`\n  ${colors.bold}${colors.green}bro.js CLI${colors.reset}\n`);
+  console.log(`  ${colors.bold}Usage:${colors.reset} bro <command>\n`);
+  console.log(`  ${colors.bold}Commands:${colors.reset}`);
+  console.log(`    ${colors.cyan}dev${colors.reset}      Start the development server with hot-reload`);
+  console.log(`    ${colors.cyan}start${colors.reset}    Start the production server gracefully`);
+  console.log(`    ${colors.cyan}init${colors.reset}     Scaffold a new bro.config.js workspace`);
+  console.log(`    ${colors.cyan}sdk${colors.reset}      Generate a typed frontend client`);
+  console.log(`    ${colors.cyan}studio${colors.reset}   Generate TS client, OpenAPI, and MSW mocks`);
+  console.log(`    ${colors.cyan}doctor${colors.reset}   Diagnose security and configuration issues`);
+  console.log(`    ${colors.cyan}test${colors.reset}     Run tests using vitest\n`);
+}