bro-framework 2.0.0 → 2.1.0

package/README.md

@@ -25,6 +25,7 @@
 
 ## Table of Contents
 
+- [Getting Started](#getting-started)
 - [The Core Experience](#the-core-experience)
 - [Deep-Dive Features](#deep-dive-features)
 - [Architecture & Request Lifecycle](#architecture--request-lifecycle)
@@ -34,6 +35,20 @@
 
 ---
 
+## Getting Started
+
+Bootstrapping a new `bro.js` project is incredibly simple. We recommend using our official scaffolding tool to set everything up instantly (with your choice of JavaScript or TypeScript):
+
+```bash
+npx create-bro-framework@latest my-api
+cd my-api
+npm run dev
+```
+
+That's it! Your zero-boilerplate backend is now running with hot-reloading enabled.
+
+---
+
 ## The Core Experience
 
 In `bro.js`, everything you need is handed to you instantly. No setup, no middleware wrangling, no manual `req/res` handling. You define your route, set your validation, and return an object. 

package/bin/bro.js

@@ -48,6 +48,13 @@ export default defineConfig({
     max: 100 // limit each IP to 100 requests per windowMs
   },
 
+  // 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 () => {
@@ -67,13 +74,6 @@ export default defineConfig({
     // return mongoose.connection; 
     // --------------------------
     return null;
-  },
-  
-  // WebSockets Setup
-  sockets: async (io, db) => {
-    io.on('connection', (socket) => {
-      console.log('Client connected:', socket.id);
-    });
   }
 });
 `;
@@ -122,10 +122,10 @@ if (command === 'init') {
 
 if (['sdk', 'generate-client', 'client'].includes(command)) {
   generateSDK().then(() => {
-    console.log(`\n  ${colors.green}✨ bro-client.js generated successfully!${colors.reset}\n`);
+    console.log(`\n  ${colors.green} bro-client.js generated successfully!${colors.reset}\n`);
     process.exit(0);
   }).catch(err => {
-    console.error(`\n  ${colors.red}❌ Error generating SDK:${colors.reset}`, err.message);
+    console.error(`\n  ${colors.red} Error generating SDK:${colors.reset}`, err.message);
     process.exit(1);
   });
 }
@@ -175,13 +175,20 @@ async function bootstrap() {
   if (globalConfig.env) {
     const envResult = globalConfig.env.safeParse(process.env);
     if (!envResult.success) {
-      console.error(`\n  ${colors.red}❌ Environment Validation Failed${colors.reset}`);
+      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 (process.env.NODE_ENV === 'production' && ['dev_secret_please_change', 'bro_default_secret_key'].includes(globalConfig.jwtSecret)) {
+    console.error(`\n  ✗ CRITICAL SECURITY ERROR: You are running in production with a default JWT secret!`);
+    console.error(`  Please set auth.jwtSecret in bro.config.js or via JWT_SECRET environment variable.`);
+    process.exit(1);
   }
 
   if (!fs.existsSync(routesDir)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bro-framework",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "The No-BS Backend Framework for Node.js",
   "repository": {
     "type": "git",

package/src/auth.js

@@ -1,31 +1,23 @@
 import jwt from 'jsonwebtoken';
 
-let secret = 'bro_default_secret_key';
-
-/**
- * Update the secret used for signing and verifying JWTs.
- * @param {string} newSecret 
- */
-export function setJwtSecret(newSecret) {
-  secret = newSecret;
-}
-
 /**
  * Signs a JWT payload.
  * @param {Object} payload - The data to embed in the token.
+ * @param {string} secret - The JWT secret key.
  * @param {jwt.SignOptions} [options] - jsonwebtoken sign options.
  * @returns {string} The signed JWT token.
  */
-export function signJwt(payload, options = { expiresIn: '1d' }) {
+export function signJwt(payload, secret, options = { expiresIn: '1d' }) {
   return jwt.sign(payload, secret, options);
 }
 
 /**
  * Verifies and decodes a JWT token.
  * @param {string} token - The JWT token to verify.
+ * @param {string} secret - The JWT secret key.
  * @returns {{ valid: boolean, payload?: any, error?: string }}
  */
-export function verifyJwt(token) {
+export function verifyJwt(token, secret) {
   try {
     const payload = jwt.verify(token, secret);
     return { valid: true, payload };

package/src/logger.js

@@ -25,17 +25,29 @@ export function formatMethod(method) {
 
 export function printBanner(port, durationMs) {
   const time = durationMs.toFixed(0);
-  const version = "1.0.0";
-  
+  const version = "2.0.1";
+  const innerWidth = 47;
+
+  const stripAnsi = (str) => str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "");
+
+  const formatLine = (content = "") => {
+    const visibleLength = stripAnsi(content).length;
+    const padding = Math.max(0, innerWidth - visibleLength);
+    return `${colors.green}│${colors.reset}${content}${" ".repeat(padding)}${colors.green}│${colors.reset}`;
+  };
+
+  const borderTop = `${colors.green}╭${"─".repeat(innerWidth)}╮${colors.reset}`;
+  const borderBottom = `${colors.green}╰${"─".repeat(innerWidth)}╯${colors.reset}`;
+
   console.log("");
-  console.log(`${colors.green}╭───────────────────────────────────────────────╮${colors.reset}`);
-  console.log(`${colors.green}│${colors.reset}                                               ${colors.green}│${colors.reset}`);
-  console.log(`${colors.green}│${colors.reset}   ${colors.bold}bro.js${colors.reset} v${version}                           ${colors.green}│${colors.reset}`);
-  console.log(`${colors.green}│${colors.reset}                                               ${colors.green}│${colors.reset}`);
-  console.log(`${colors.green}│${colors.reset}   ➜  ${colors.bold}Local:${colors.reset}   ${colors.cyan}http://localhost:${port}${colors.reset}         ${colors.green}│${colors.reset}`);
-  console.log(`${colors.green}│${colors.reset}   ➜  ${colors.bold}Ready in:${colors.reset} ${colors.yellow}${time}ms${colors.reset}                         ${colors.green}│${colors.reset}`);
-  console.log(`${colors.green}│${colors.reset}                                               ${colors.green}│${colors.reset}`);
-  console.log(`${colors.green}╰───────────────────────────────────────────────╯${colors.reset}`);
+  console.log(borderTop);
+  console.log(formatLine());
+  console.log(formatLine(`   ${colors.bold}bro.js${colors.reset} v${version}`));
+  console.log(formatLine());
+  console.log(formatLine(`   ➜  ${colors.bold}Local:${colors.reset}   ${colors.cyan}http://localhost:${port}${colors.reset}`));
+  console.log(formatLine(`   ➜  ${colors.bold}Ready in:${colors.reset} ${colors.yellow}${time}ms${colors.reset}`));
+  console.log(formatLine());
+  console.log(borderBottom);
   console.log("");
 }
 

package/src/router.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { pathToFileURL } from 'url';
+import crypto from 'crypto';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 
 /**
@@ -48,10 +49,11 @@ export function parseRouteFile(filePath, routesDir) {
   if (routePath === '/.') routePath = ''; 
   
   if (namePart !== 'index') {
-    const formattedName = namePart.replace(/\[(.*?)\]/g, ':$1');
-    routePath += `/${formattedName}`;
+    routePath += `/${namePart}`;
   }
   
+  routePath = routePath.replace(/\[(.*?)\]/g, ':$1');
+  
   if (routePath === '') routePath = '/';
 
   return { routePath, method };
@@ -68,6 +70,7 @@ export function parseRouteFile(filePath, routesDir) {
 export async function loadRoutes(app, routesDir, createHandler, openApiSpec) {
   const files = scanDir(routesDir);
   const loadedRoutes = [];
+  const routeModules = [];
   
   for (const file of files) {
     const routeInfo = parseRouteFile(file, routesDir);
@@ -77,68 +80,76 @@ export async function loadRoutes(app, routesDir, createHandler, openApiSpec) {
     
     if (typeof app[method] !== 'function') continue;
 
-    try {
-      const moduleUrl = pathToFileURL(file).href + '?update=' + Date.now();
-      const module = await import(moduleUrl);
-      const config = module.default;
-      
-      if (!config) continue;
+    const moduleUrl = pathToFileURL(file).href + '?update=' + crypto.randomUUID();
+    const module = await import(moduleUrl);
+    const config = module.default;
+    
+    if (!config) continue;
+    
+    routeModules.push({ file, routePath, method, config });
+  }
+  
+  for (const { file, routePath, method, config } of routeModules) {
+    const handler = createHandler(config);
+    app[method](routePath, handler);
+    
+    if (openApiSpec) {
+      const openApiPath = routePath.replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
+      if (!openApiSpec.paths[openApiPath]) openApiSpec.paths[openApiPath] = {};
       
-      const handler = createHandler(config);
-      app[method](routePath, handler);
+      const operation = {
+        summary: config.summary || `${method.toUpperCase()} ${routePath}`,
+        responses: { '200': { description: 'Successful response' } }
+      };
       
-      if (openApiSpec) {
-        const openApiPath = routePath.replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
-        if (!openApiSpec.paths[openApiPath]) openApiSpec.paths[openApiPath] = {};
-        
-        const operation = {
-          summary: config.summary || `${method.toUpperCase()} ${routePath}`,
-          responses: { '200': { description: 'Successful response' } }
+      const bodySchema = config.schema?.body || config.body;
+      const paramsSchema = config.schema?.params || config.params;
+      const querySchema = config.schema?.query || config.query;
+
+      if (bodySchema) {
+        operation.requestBody = {
+          content: { 'application/json': { schema: zodToJsonSchema(bodySchema) } }
         };
-        
-        if (config.body) {
-          operation.requestBody = {
-            content: { 'application/json': { schema: zodToJsonSchema(config.body) } }
-          };
-        }
-        
-        if (config.params) {
-          operation.parameters = operation.parameters || [];
-          const pSchema = zodToJsonSchema(config.params);
-          if (pSchema.properties) {
-            for (const [key, schema] of Object.entries(pSchema.properties)) {
-              operation.parameters.push({ name: key, in: 'path', required: true, schema });
-            }
+      }
+      
+      if (paramsSchema) {
+        operation.parameters = operation.parameters || [];
+        const pSchema = zodToJsonSchema(paramsSchema);
+        if (pSchema.properties) {
+          for (const [key, schema] of Object.entries(pSchema.properties)) {
+            operation.parameters.push({ name: key, in: 'path', required: true, schema });
           }
         }
+      }
 
-        if (config.query) {
-          operation.parameters = operation.parameters || [];
-          const qSchema = zodToJsonSchema(config.query);
-          if (qSchema.properties) {
-            for (const [key, schema] of Object.entries(qSchema.properties)) {
-              operation.parameters.push({ 
-                name: key, 
-                in: 'query', 
-                required: qSchema.required?.includes(key), 
-                schema 
-              });
-            }
+      if (querySchema) {
+        operation.parameters = operation.parameters || [];
+        const qSchema = zodToJsonSchema(querySchema);
+        if (qSchema.properties) {
+          for (const [key, schema] of Object.entries(qSchema.properties)) {
+            operation.parameters.push({ 
+              name: key, 
+              in: 'query', 
+              required: qSchema.required?.includes(key), 
+              schema 
+            });
           }
         }
-        
-        openApiSpec.paths[openApiPath][method.toLowerCase()] = operation;
       }
       
-      loadedRoutes.push({
-        method: method.toUpperCase(),
-        path: routePath,
-        auth: !!config.auth
-      });
+      // Auto-inject security definition if auth is true
+      if (config.auth) {
+        operation.security = [{ bearerAuth: [] }];
+      }
       
-    } catch (err) {
-      console.error(`[bro.js] Failed to load route ${file}:`, err);
+      openApiSpec.paths[openApiPath][method.toLowerCase()] = operation;
     }
+    
+    loadedRoutes.push({
+      method: method.toUpperCase(),
+      path: routePath,
+      auth: !!config.auth
+    });
   }
   
   return loadedRoutes;

package/src/sdk.js

@@ -44,7 +44,10 @@ async function request(method, path, data) {
     options.body = JSON.stringify(data);
   } else if (data && ['GET', 'DELETE'].includes(method.toUpperCase())) {
     const params = new URLSearchParams(data);
-    path += '?' + params.toString();
+    const qs = params.toString();
+    if (qs) {
+      path += '?' + qs;
+    }
   }
 
   const url = CONFIG.baseURL + path;
@@ -115,10 +118,10 @@ function generateApiObject(endpoints) {
     
     for (const [key, val] of Object.entries(node)) {
       if (val._isParam) {
-        result += `${indent}${key}: (${key}) => ({\n`;
+        result += `${indent}"${key}": (${key}) => ({\n`;
         
         for (const [m, p] of Object.entries(val._methods)) {
-          const templatedPath = p.replace(/:([a-zA-Z0-9_]+)/g, '${$1}');
+          const templatedPath = p.replace(/:([a-zA-Z0-9_]+)/g, '${encodeURIComponent($1)}');
           result += `${indent}  ${m}: (data) => request('${m}', \`${templatedPath}\`, data),\n`;
         }
         
@@ -129,7 +132,7 @@ function generateApiObject(endpoints) {
         
         result += `${indent}}),\n`;
       } else {
-        result += `${indent}${key}: {\n`;
+        result += `${indent}"${key}": {\n`;
         for (const [m, p] of Object.entries(val._methods)) {
            result += `${indent}  ${m}: (data) => request('${m}', '${p}', data),\n`;
         }

package/src/server.js

@@ -5,11 +5,9 @@ import { Server } from 'socket.io';
 import rateLimit from 'express-rate-limit';
 import multer from 'multer';
 import { apiReference } from '@scalar/express-api-reference';
-import { verifyJwt, signJwt, setJwtSecret } from './auth.js';
+import { verifyJwt, signJwt } from './auth.js';
 import { loadRoutes } from './router.js';
 
-const upload = multer();
-
 /**
  * Creates and configures the core Express server.
  * @param {Object} globalConfig - User's bro.config.js configurations.
@@ -23,7 +21,10 @@ export async function createServer(globalConfig, routesDir, db) {
   
   const corsConfig = globalConfig.server?.cors !== undefined ? globalConfig.server.cors : true;
   
-  app.use(cors(typeof corsConfig === 'object' ? corsConfig : {}));
+  if (corsConfig !== false) {
+    app.use(cors(typeof corsConfig === 'object' ? corsConfig : {}));
+  }
+  
   app.use(express.json());
   
   if (globalConfig.rateLimit) {
@@ -36,10 +37,6 @@ export async function createServer(globalConfig, routesDir, db) {
     await globalConfig.sockets(io, db);
   }
   
-  if (globalConfig.jwtSecret) {
-    setJwtSecret(globalConfig.jwtSecret);
-  }
-
   const createHandler = (routeConfig) => {
     const middlewares = [];
     
@@ -48,12 +45,23 @@ export async function createServer(globalConfig, routesDir, db) {
     }
     
     if (routeConfig.upload) {
-      middlewares.push(upload.any());
+      const routeMulterConfig = {
+        limits: globalConfig.upload?.limits || {
+          fileSize: 10 * 1024 * 1024,
+          files: 5,
+          fields: 20
+        }
+      };
+      if (typeof routeConfig.upload === 'object' && routeConfig.upload.limits) {
+        routeMulterConfig.limits = { ...routeMulterConfig.limits, ...routeConfig.upload.limits };
+      }
+      middlewares.push(multer(routeMulterConfig).any());
     }
     
     middlewares.push(async (req, res) => {
       try {
         const ctx = {
+          env: globalConfig.envData || process.env,
           db,
           io,
           body: req.body,
@@ -61,7 +69,7 @@ export async function createServer(globalConfig, routesDir, db) {
           query: req.query,
           files: req.files || req.file,
           user: null,
-          jwt: { sign: signJwt },
+          jwt: { sign: (payload, opts) => signJwt(payload, globalConfig.jwtSecret, opts || { expiresIn: globalConfig.auth?.expiresIn || '1d' }) },
           error: (status, message) => {
              const err = new Error(message);
              err.status = status;
@@ -76,7 +84,7 @@ export async function createServer(globalConfig, routesDir, db) {
           }
           
           const token = authHeader.split(' ')[1];
-          const authResult = verifyJwt(token);
+          const authResult = verifyJwt(token, globalConfig.jwtSecret);
           
           if (!authResult.valid) {
             return res.status(401).json({ error: 'Unauthorized', details: authResult.error });
@@ -143,6 +151,21 @@ export async function createServer(globalConfig, routesDir, db) {
   let openApiSpec = {
     openapi: '3.0.0',
     info: { title: 'bro.js API', version: '1.0.0' },
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT'
+        }
+      },
+      responses: {
+        BadRequest: { description: 'Bad Request', content: { 'application/json': { schema: { type: 'object', properties: { error: { type: 'string' } } } } } },
+        Unauthorized: { description: 'Unauthorized', content: { 'application/json': { schema: { type: 'object', properties: { error: { type: 'string' } } } } } },
+        NotFound: { description: 'Not Found', content: { 'application/json': { schema: { type: 'object', properties: { error: { type: 'string' } } } } } },
+        ServerError: { description: 'Internal Server Error', content: { 'application/json': { schema: { type: 'object', properties: { error: { type: 'string' } } } } } }
+      }
+    },
     paths: {}
   };
 
@@ -174,6 +197,15 @@ export async function createServer(globalConfig, routesDir, db) {
     routeStack(req, res, next);
   });
 
+  app.use((req, res) => {
+    res.status(404).json({ error: 'Not Found' });
+  });
+
+  app.use((err, req, res, next) => {
+    console.error(`[bro.js] Uncaught Error:`, err);
+    res.status(err.status || 500).json({ error: err.message || 'Internal Server Error' });
+  });
+
   const reload = async () => {
     const newRouter = express.Router();
     openApiSpec.paths = {};

package/src/tasks.js

@@ -3,29 +3,39 @@ import path from 'path';
 import { pathToFileURL } from 'url';
 import cron from 'node-cron';
 import { colors } from './logger.js';
+import { scanDir } from './router.js';
+
+let taskHandles = [];
+
+export function stopTasks() {
+  taskHandles.forEach(t => t.stop());
+  taskHandles = [];
+}
 
 export async function scanTasks(ctx) {
   const tasksDir = path.join(process.cwd(), 'tasks');
   if (!fs.existsSync(tasksDir)) return;
   
-  const files = fs.readdirSync(tasksDir).filter(f => f.endsWith('.js'));
+  stopTasks();
+
+  const files = scanDir(tasksDir);
   if (files.length === 0) return;
   
   let count = 0;
   for (const file of files) {
-    const filePath = path.join(tasksDir, file);
     try {
-      const moduleUrl = pathToFileURL(filePath).href;
+      const moduleUrl = pathToFileURL(file).href;
       const taskModule = await import(moduleUrl);
       
       if (taskModule.cron && typeof taskModule.handler === 'function') {
-        cron.schedule(taskModule.cron, async () => {
+        const task = cron.schedule(taskModule.cron, async () => {
           try {
             await taskModule.handler(ctx);
           } catch (err) {
             console.error(`\n  ${colors.red}❌ Task Error (${file}):${colors.reset}`, err);
           }
         });
+        taskHandles.push(task);
         count++;
       }
     } catch (err) {