bro-framework 1.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Med Yassine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+<p align="center">
+  <h1 align="center">bro.js</h1>
+  <p align="center">
+    <strong>The zero-boilerplate Node.js framework that actually has your back.</strong>
+  </p>
+  <p align="center">
+    <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT">
+    <img src="https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg?style=flat-square" alt="Node.js: >= 18">
+    <img src="https://img.shields.io/badge/Architecture-Pure%20ESM-orange.svg?style=flat-square" alt="Architecture: Pure ESM">
+    <img src="https://img.shields.io/badge/Validation-Zod-3068b7.svg?style=flat-square" alt="Validation: Zod">
+    <img src="https://img.shields.io/badge/Realtime-Socket.io-black.svg?style=flat-square" alt="Realtime: Socket.io">
+    <img src="https://img.shields.io/badge/Engine-Express-eeeeee.svg?style=flat-square" alt="Engine: Express">
+  </p>
+  <p align="center">
+    <a href="https://brojs.yessindevs.me">Documentation Website</a>
+  </p>
+</p>
+
+---
+
+> "NestJS wants four decorators, three modules, and an existential crisis just to handle a GET request. Express makes you write the same 40 lines of CORS, JSON parsing, and auth middleware for every project. bro.js gives you file routing, auto-validation, JWT auth, WebSockets, and live docs out of the box. Be honest: you just want to return an object."
+
+---
+
+## Table of Contents
+
+- [The Core Experience](#the-core-experience)
+- [Deep-Dive Features](#deep-dive-features)
+- [Architecture & Request Lifecycle](#architecture--request-lifecycle)
+- [Tech Stack Breakdown](#tech-stack-breakdown)
+- [CLI Reference](#cli-reference)
+- [Author & License](#author--license)
+
+---
+
+## 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. 
+
+`routes/posts/[id].post.js`:
+
+```javascript
+import { defineRoute, z } from 'bro-framework';
+
+export default defineRoute({
+  auth: true,
+  params: z.object({
+    id: z.string().uuid()
+  }),
+  body: z.object({
+    title: z.string().min(5),
+    content: z.string()
+  }),
+  handler: async ({ body, params, user, db, io }) => {
+    // 1. Data is already validated. user is already authenticated.
+    
+    // 2. Perform database operation using the injected Mongoose context
+    const post = await db.collection('posts').updateOne(
+      { _id: params.id },
+      { $set: { ...body, authorId: user.id } }
+    );
+    
+    // 3. Broadcast to all clients instantly using injected Socket.io
+    io.emit('post_updated', { postId: params.id, title: body.title });
+    
+    // 4. Return an object. bro.js handles the 200 JSON response.
+    return {
+      success: true,
+      updated: post.modifiedCount
+    };
+  }
+});
+```
+
+---
+
+## Deep-Dive Features
+
+### File-Based Routing
+Create a `.js` file in the `routes/` directory, and it automatically becomes an endpoint. We use Next.js-style bracket syntax for dynamic parameters. A file named `routes/users/[id].get.js` translates natively to a `GET /users/:id` Express route under the hood.
+
+### Bouncer-Grade Validation
+Powered by Zod. Attach a schema to `body`, `query`, or `params` in your route definition. If the client sends malformed data, `bro.js` automatically rejects the request with a structured `400 Bad Request` JSON payload *before* your handler ever executes. You never have to manually validate inputs again.
+
+### Zero-Config JWTs
+Add `auth: true` to your route config. `bro.js` will intercept the request, extract the `Authorization: Bearer <token>` header, verify the signature using your `jwtSecret`, and inject the decoded payload directly into `ctx.user`.
+
+### Context Injection
+Stop importing singleton database connections and socket instances into every file. Define your `db` and `sockets` setup once in `bro.config.js`. `bro.js` orchestrates the initialization and injects both instances directly into the `ctx` object for every request handler.
+
+### Zero-YAML Live Documentation
+If you've ever hand-written OpenAPI YAML, you know the pain. `bro.js` parses your Zod schemas and automatically serves a stunning, interactive [Scalar](https://scalar.com/) API playground at `/docs`. It's highly secure: by default, these internal docs are disabled in production mode.
+
+### The Frontend SDK Generator
+Tired of writing frontend `fetch` wrappers? Run `bro sdk`. The CLI will parse your backend routes and compile a `bro-client.js` file for your frontend. It features built-in token management, request stringification, and type-safe deep tree traversal (e.g., `api.users.id("123").post(data)`).
+
+### Background Task Scheduler
+Don't spin up a separate worker server. Drop a JavaScript file anywhere in the `tasks/` folder, export a cron string (e.g., `"0 0 * * *"`), and an async handler. `bro.js` natively schedules it as a background worker with full access to your injected database and WebSocket contexts.
+
+### Zero-Boilerplate File Uploads
+Add `upload: true` to a route. `bro.js` automatically hooks into `multer`, parses the `multipart/form-data` payload in memory, and injects the files directly into `ctx.files`.
+
+---
+
+## Architecture & Request Lifecycle
+
+```text
+       [ Incoming HTTP Request ]
+                  │
+                  ▼
+         ( Express Engine )
+                  │
+                  ▼
+     [ CORS / JSON Pre-flight ]
+                  │
+                  ▼
+          ( Dev Logger )
+                  │
+                  ▼
+      [ Auth Guard (JWT Check) ] ──(Fail)──> 401 Unauthorized
+                  │
+                  ▼
+     [ Zod Bouncer Validation ] ───(Fail)──> 400 Bad Request
+                  │
+                  ▼
+         ( Route Handler )
+      ╭─────────────────────╮
+      │ Injects:            │
+      │ - ctx.body / params │
+      │ - ctx.user          │
+      │ - ctx.db            │
+      │ - ctx.io            │
+      │ - ctx.files         │
+      ╰─────────────────────╯
+                  │
+                  ▼
+      [ Auto JSON Formatter ] ─────(Fail)──> 500 Internal Error
+                  │
+                  ▼
+      [ Client JSON Response ]
+```
+
+---
+
+## Tech Stack Breakdown
+
+| Layer | Technology | Purpose |
+| :--- | :--- | :--- |
+| **Engine** | Node.js (Express) | High-performance, battle-tested HTTP abstraction layer. |
+| **Validation** | Zod | Bouncer-grade, strictly typed schema validation for payloads. |
+| **Authentication** | jsonwebtoken | Stateless, scalable security for protecting endpoints. |
+| **Realtime** | Socket.io | Bi-directional, event-driven WebSocket communication. |
+| **API Reference** | Scalar | Auto-generated, interactive Swagger/OpenAPI documentation. |
+| **Task Scheduler** | node-cron | Reliable internal background task orchestration. |
+| **File Parsing** | multer | Zero-boilerplate `multipart/form-data` file extraction. |
+
+---
+
+## CLI Reference
+
+| Command | Description |
+| :--- | :--- |
+| `bro dev` | Development server featuring instant boot, visual CLI banner, and `chokidar`-powered hot module remapping. |
+| `bro start` &nbsp; | Production runner locked down for security. Zero watcher overhead, suppressed internal logs, and isolated API docs. |
+| `bro init` | Automated workspace scaffolder. Generates configuration files and forcefully ensures your `package.json` respects `"type": "module"`. |
+| `bro sdk` | Route parser and browser client compiler. Generates your frontend SDK in one hit. |
+
+---
+
+## Author & License
+
+- **Author**: Yessin (@medyass1ne)
+- **License**: MIT

package/bin/bro.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+
+import path from 'path';
+import fs from 'fs';
+import { pathToFileURL } from 'url';
+import { createServer } from '../src/server.js';
+import { colors, printBanner, printRoute, printHotReload } from '../src/logger.js';
+import { scanTasks } from '../src/tasks.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.js';
+
+export default defineConfig({
+  // Server Settings
+  server: {
+    port: 5000,
+    cors: true // Set to true to allow all, or pass a CORS options object
+  },
+
+  // Authentication Settings
+  auth: {
+    jwtSecret: 'dev_secret_please_change',
+    expiresIn: '7d'
+  },
+  
+  // 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
+  },
+
+  // 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;
+  },
+  
+  // WebSockets Setup
+  sockets: async (io, db) => {
+    io.on('connection', (socket) => {
+      console.log('Client connected:', socket.id);
+    });
+  }
+});
+`;
+
+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-client.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);
+    }
+  }
+
+  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 { app, server, routes: initialRoutes, reload, io } = 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}`);
+    }
+    
+    await scanTasks({ db, io });
+    
+    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 watcher = chokidar.watch(routesDir, { ignoreInitial: true });
+      
+      watcher.on('all', async (event, filepath) => {
+        if (!filepath.endsWith('.js')) return;
+        
+        try {
+          const reloadStartTime = performance.now();
+          currentRoutes = await reload();
+          const reloadTimeMs = performance.now() - reloadStartTime;
+          
+          printHotReload(path.basename(filepath), event, reloadTimeMs);
+          printCurrentRoutes(currentRoutes);
+        } catch (err) {
+          console.error(`\n  ✗ Error hot-reloading routes:`, err);
+        }
+      });
+    }
+  });
+}
+
+if (command === 'dev' || command === 'start') {
+  bootstrap();
+} else {
+  console.log(`Usage: bro dev | bro start | bro init`);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "bro-framework",
+  "version": "1.2.3",
+  "description": "The No-BS Backend Framework for Node.js",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "bro": "./bin/bro.js"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "dependencies": {
+    "@scalar/express-api-reference": "^0.10.18",
+    "chokidar": "^5.0.0",
+    "cors": "^2.8.6",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.1",
+    "express-rate-limit": "^8.7.0",
+    "jsonwebtoken": "^9.0.2",
+    "multer": "^2.3.0",
+    "node-cron": "^4.6.0",
+    "socket.io": "^4.8.3",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.25.2"
+  }
+}

package/src/auth.js

@@ -0,0 +1,41 @@
+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 {jwt.SignOptions} [options] - jsonwebtoken sign options.
+ * @returns {string} The signed JWT token.
+ */
+export function signJwt(payload, options = { expiresIn: '1d' }) {
+  return jwt.sign(payload, secret, options);
+}
+
+/**
+ * Verifies and decodes a JWT token.
+ * @param {string} token - The JWT token to verify.
+ * @returns {{ valid: boolean, payload?: any, error?: string }}
+ */
+export function verifyJwt(token) {
+  try {
+    const payload = jwt.verify(token, secret);
+    return { valid: true, payload };
+  } catch (error) {
+    let message = 'Invalid token';
+    if (error.name === 'TokenExpiredError') {
+      message = 'Token has expired';
+    } else if (error.name === 'JsonWebTokenError') {
+      message = 'Signature verification failed';
+    }
+    return { valid: false, error: message };
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,51 @@
+import { ZodType } from 'zod';
+
+export interface BroContext {
+  body?: any;
+  params?: any;
+  query?: any;
+  user?: any;
+  db?: any;
+  io?: any;
+  files?: any[];
+  error?: any;
+}
+
+export interface RouteConfig {
+  auth?: boolean;
+  upload?: boolean;
+  body?: ZodType<any, any, any>;
+  params?: ZodType<any, any, any>;
+  query?: ZodType<any, any, any>;
+  rateLimit?: {
+    windowMs: number;
+    max: number;
+  };
+  summary?: string;
+  handler: (ctx: BroContext) => Promise<any> | any;
+}
+
+export function defineRoute(config: RouteConfig): RouteConfig;
+
+export interface BroConfig {
+  env?: ZodType<any, any, any>;
+  server?: {
+    port?: number;
+    cors?: boolean | object;
+  };
+  auth?: {
+    jwtSecret?: string;
+    expiresIn?: string | number;
+  };
+  docs?: boolean | { auth?: { user: string; pass: string } };
+  rateLimit?: {
+    windowMs: number;
+    max: number;
+  };
+  db?: () => Promise<any> | any;
+  sockets?: (io: any, db: any) => Promise<void> | void;
+}
+
+export function defineConfig(config: BroConfig): BroConfig;
+
+export { z } from 'zod';

package/src/index.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+/**
+ * Defines a route configuration for bro.js.
+ * @param {Object} config - The route configuration.
+ * @param {Function} config.handler - The route handler function receiving ctx.
+ * @param {boolean} [config.auth] - Whether the route requires authentication.
+ * @param {import('zod').ZodType} [config.params] - Zod schema for route parameters.
+ * @param {import('zod').ZodType} [config.body] - Zod schema for request body.
+ * @param {import('zod').ZodType} [config.query] - Zod schema for query parameters.
+ * @returns {Object} The unchanged config object.
+ */
+export function defineRoute(config) {
+  return config;
+}
+
+/**
+ * Defines the global framework configuration.
+ * @param {Object} config - The global configuration.
+ * @param {string} [config.jwtSecret] - Secret key for JWT signing/verification.
+ * @param {number} [config.port] - Server port to listen on.
+ * @returns {Object} The unchanged config object.
+ */
+export function defineConfig(config) {
+  return config;
+}
+
+export { z };

package/src/logger.js

@@ -0,0 +1,54 @@
+export const colors = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m"
+};
+
+export function formatMethod(method) {
+  const m = method.toUpperCase().padEnd(6);
+  switch(method.toUpperCase()) {
+    case 'GET': return `${colors.green}${colors.bold}${m}${colors.reset}`;
+    case 'POST': return `${colors.blue}${colors.bold}${m}${colors.reset}`;
+    case 'PUT': return `${colors.yellow}${colors.bold}${m}${colors.reset}`;
+    case 'DELETE': return `${colors.red}${colors.bold}${m}${colors.reset}`;
+    case 'PATCH': return `${colors.magenta}${colors.bold}${m}${colors.reset}`;
+    default: return `${colors.white}${colors.bold}${m}${colors.reset}`;
+  }
+}
+
+export function printBanner(port, durationMs) {
+  const time = durationMs.toFixed(0);
+  const version = "1.0.0";
+  
+  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("");
+}
+
+export function printRoute(method, routePath, hasAuth, isLast = false) {
+  const branch = isLast ? "╰──" : "├──";
+  const coloredMethod = formatMethod(method);
+  const authIcon = hasAuth ? " 🔒" : "";
+  
+  console.log(`  ${colors.dim}${branch}${colors.reset} ${coloredMethod} ${routePath}${authIcon}`);
+}
+
+export function printHotReload(fileName, event, reloadTimeMs) {
+  const time = typeof reloadTimeMs === 'number' ? reloadTimeMs.toFixed(0) : reloadTimeMs;
+  console.log(`\n  ${colors.cyan}Route updated:${colors.reset} ${colors.bold}${fileName}${colors.reset} ${colors.dim}(${event})${colors.reset}`);
+  console.log(`  ${colors.dim}Remapped in ${time}ms${colors.reset}\n`);
+}

package/src/router.js

@@ -0,0 +1,145 @@
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+/**
+ * Recursively scans a directory for .js files.
+ * @param {string} dir - The base directory to scan.
+ * @param {string[]} [fileList] - Internal accumulator for recursion.
+ * @returns {string[]} Array of absolute file paths.
+ */
+export function scanDir(dir, fileList = []) {
+  if (!fs.existsSync(dir)) return fileList;
+  
+  const files = fs.readdirSync(dir);
+  
+  for (const file of files) {
+    const filePath = path.join(dir, file);
+    if (fs.statSync(filePath).isDirectory()) {
+      scanDir(filePath, fileList);
+    } else if (filePath.endsWith('.js')) {
+      fileList.push(filePath);
+    }
+  }
+  
+  return fileList;
+}
+
+/**
+ * Converts a file path to an Express route path.
+ * Example: routes/users/[id].get.js -> { routePath: '/users/:id', method: 'get' }
+ * @param {string} filePath - Absolute path to the route file.
+ * @param {string} routesDir - The root routes directory.
+ * @returns {{ routePath: string, method: string } | null}
+ */
+export function parseRouteFile(filePath, routesDir) {
+  const relativePath = path.relative(routesDir, filePath);
+  
+  const parsed = path.parse(relativePath);
+  const parts = parsed.name.split('.');
+  
+  if (parts.length < 2) return null; 
+  
+  const method = parts.pop().toLowerCase();
+  const namePart = parts.join('.');
+  
+  let routePath = '/' + path.dirname(relativePath).replace(/\\/g, '/');
+  if (routePath === '/.') routePath = ''; 
+  
+  if (namePart !== 'index') {
+    const formattedName = namePart.replace(/\[(.*?)\]/g, ':$1');
+    routePath += `/${formattedName}`;
+  }
+  
+  if (routePath === '') routePath = '/';
+
+  return { routePath, method };
+}
+
+/**
+ * Loads and maps all route files into the Express application.
+ * @param {import('express').Application} app - The Express app instance.
+ * @param {string} routesDir - Path to the user's routes folder.
+ * @param {Function} createHandler - Core wrapper function for route logic.
+ * @param {Object} [openApiSpec] - Optional OpenAPI Spec object to build.
+ * @returns {Promise<Array>} Array of loaded route objects.
+ */
+export async function loadRoutes(app, routesDir, createHandler, openApiSpec) {
+  const files = scanDir(routesDir);
+  const loadedRoutes = [];
+  
+  for (const file of files) {
+    const routeInfo = parseRouteFile(file, routesDir);
+    if (!routeInfo) continue;
+    
+    const { routePath, method } = routeInfo;
+    
+    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 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 operation = {
+          summary: config.summary || `${method.toUpperCase()} ${routePath}`,
+          responses: { '200': { description: 'Successful response' } }
+        };
+        
+        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 (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 
+              });
+            }
+          }
+        }
+        
+        openApiSpec.paths[openApiPath][method.toLowerCase()] = operation;
+      }
+      
+      loadedRoutes.push({
+        method: method.toUpperCase(),
+        path: routePath,
+        auth: !!config.auth
+      });
+      
+    } catch (err) {
+      console.error(`[bro.js] Failed to load route ${file}:`, err);
+    }
+  }
+  
+  return loadedRoutes;
+}

package/src/sdk.js

@@ -0,0 +1,149 @@
+import fs from 'fs';
+import path from 'path';
+import { parseRouteFile, scanDir } from './router.js';
+
+export async function generateSDK() {
+  const routesDir = path.join(process.cwd(), 'routes');
+  if (!fs.existsSync(routesDir)) {
+    throw new Error(`Routes directory not found at ${routesDir}`);
+  }
+
+  const files = scanDir(routesDir);
+  const endpoints = [];
+
+  for (const file of files) {
+    const routeInfo = parseRouteFile(file, routesDir);
+    if (routeInfo) {
+      endpoints.push(routeInfo);
+    }
+  }
+
+  const code = `// Auto-generated by bro.js
+const CONFIG = {
+  baseURL: 'http://localhost:5000',
+  tokenKey: 'bro_token'
+};
+
+async function request(method, path, data) {
+  const headers = {};
+  
+  if (typeof localStorage !== 'undefined') {
+    const token = localStorage.getItem(CONFIG.tokenKey);
+    if (token) {
+      headers['Authorization'] = \`Bearer \${token}\`;
+    }
+  }
+
+  const options = {
+    method: method.toUpperCase(),
+    headers
+  };
+
+  if (data && ['POST', 'PUT', 'PATCH'].includes(method.toUpperCase())) {
+    headers['Content-Type'] = 'application/json';
+    options.body = JSON.stringify(data);
+  } else if (data && ['GET', 'DELETE'].includes(method.toUpperCase())) {
+    const params = new URLSearchParams(data);
+    path += '?' + params.toString();
+  }
+
+  const url = CONFIG.baseURL + path;
+  const response = await fetch(url, options);
+  
+  if (!response.ok) {
+    let errMessage = response.statusText;
+    try {
+      const errData = await response.json();
+      errMessage = errData.error || errData.message || errMessage;
+    } catch (e) {}
+    throw new Error(\`HTTP \${response.status}: \${errMessage}\`);
+  }
+
+  return response.json();
+}
+
+export const api = {
+${generateApiObject(endpoints)}
+};
+
+export function setBaseURL(url) {
+  CONFIG.baseURL = url;
+}
+
+export function setTokenKey(key) {
+  CONFIG.tokenKey = key;
+}
+`;
+
+  fs.writeFileSync(path.join(process.cwd(), 'bro-sdk.js'), code, 'utf-8');
+}
+
+function generateApiObject(endpoints) {
+  const tree = {};
+  
+  for (const { routePath, method } of endpoints) {
+    const parts = routePath.split('/').filter(Boolean);
+    
+    let current = tree;
+    let pathAcc = '';
+    
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const isParam = part.startsWith(':');
+      const name = isParam ? part.slice(1) : part;
+      pathAcc += '/' + part;
+      
+      if (!current[name]) {
+        current[name] = { _isParam: isParam, _methods: {}, _children: {}, _path: pathAcc };
+      }
+      
+      if (i === parts.length - 1) {
+        current[name]._methods[method.toLowerCase()] = pathAcc;
+      }
+      
+      current = current[name]._children;
+    }
+    
+    if (parts.length === 0) {
+      if (!tree['root']) tree['root'] = { _isParam: false, _methods: {}, _children: {}, _path: '/' };
+      tree['root']._methods[method.toLowerCase()] = '/';
+    }
+  }
+
+  function renderTree(node, indent = '  ') {
+    let result = '';
+    
+    for (const [key, val] of Object.entries(node)) {
+      if (val._isParam) {
+        result += `${indent}${key}: (${key}) => ({\n`;
+        
+        for (const [m, p] of Object.entries(val._methods)) {
+          const templatedPath = p.replace(/:([a-zA-Z0-9_]+)/g, '${$1}');
+          result += `${indent}  ${m}: (data) => request('${m}', \`${templatedPath}\`, data),\n`;
+        }
+        
+        const childrenStr = renderTree(val._children, indent + '  ');
+        if (childrenStr) {
+          result += childrenStr;
+        }
+        
+        result += `${indent}}),\n`;
+      } else {
+        result += `${indent}${key}: {\n`;
+        for (const [m, p] of Object.entries(val._methods)) {
+           result += `${indent}  ${m}: (data) => request('${m}', '${p}', data),\n`;
+        }
+        
+        const childrenStr = renderTree(val._children, indent + '  ');
+        if (childrenStr) {
+          result += childrenStr;
+        }
+        
+        result += `${indent}},\n`;
+      }
+    }
+    return result;
+  }
+
+  return renderTree(tree);
+}

package/src/server.js

@@ -0,0 +1,188 @@
+import express from 'express';
+import cors from 'cors';
+import http from 'node:http';
+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 { loadRoutes } from './router.js';
+
+const upload = multer();
+
+/**
+ * Creates and configures the core Express server.
+ * @param {Object} globalConfig - User's bro.config.js configurations.
+ * @param {string} routesDir - Path to the target routes directory.
+ * @param {any} db - Initialized database instance.
+ * @returns {Promise<{ app: import('express').Application, server: http.Server, routes: Array, reload: Function, io: import('socket.io').Server }>}
+ */
+export async function createServer(globalConfig, routesDir, db) {
+  const app = express();
+  const server = http.createServer(app);
+  
+  const corsConfig = globalConfig.server?.cors !== undefined ? globalConfig.server.cors : true;
+  
+  app.use(cors(typeof corsConfig === 'object' ? corsConfig : {}));
+  app.use(express.json());
+  
+  if (globalConfig.rateLimit) {
+    app.use(rateLimit(globalConfig.rateLimit));
+  }
+  
+  const io = new Server(server, { cors: typeof corsConfig === 'object' ? corsConfig : undefined });
+  
+  if (globalConfig.sockets) {
+    await globalConfig.sockets(io, db);
+  }
+  
+  if (globalConfig.jwtSecret) {
+    setJwtSecret(globalConfig.jwtSecret);
+  }
+
+  const createHandler = (routeConfig) => {
+    const middlewares = [];
+    
+    if (routeConfig.rateLimit) {
+      middlewares.push(rateLimit(routeConfig.rateLimit));
+    }
+    
+    if (routeConfig.upload) {
+      middlewares.push(upload.any());
+    }
+    
+    middlewares.push(async (req, res) => {
+      try {
+        const ctx = {
+          db,
+          io,
+          body: req.body,
+          params: req.params,
+          query: req.query,
+          files: req.files || req.file,
+          user: null,
+          jwt: { sign: signJwt },
+          error: (status, message) => {
+             const err = new Error(message);
+             err.status = status;
+             throw err;
+          }
+        };
+
+        if (routeConfig.auth) {
+          const authHeader = req.headers.authorization;
+          if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            return res.status(401).json({ error: 'Unauthorized', details: 'Missing or invalid Bearer token' });
+          }
+          
+          const token = authHeader.split(' ')[1];
+          const authResult = verifyJwt(token);
+          
+          if (!authResult.valid) {
+            return res.status(401).json({ error: 'Unauthorized', details: authResult.error });
+          }
+          
+          ctx.user = authResult.payload;
+        }
+
+        if (routeConfig.params) {
+          const result = routeConfig.params.safeParse(req.params);
+          if (!result.success) {
+            return res.status(400).json({ error: 'Invalid URL Parameters', details: result.error.flatten() });
+          }
+          ctx.params = result.data;
+        }
+        
+        if (routeConfig.body) {
+          const result = routeConfig.body.safeParse(req.body);
+          if (!result.success) {
+            return res.status(400).json({ error: 'Invalid Request Body', details: result.error.flatten() });
+          }
+          ctx.body = result.data;
+        }
+
+        if (routeConfig.query) {
+           const result = routeConfig.query.safeParse(req.query);
+           if (!result.success) {
+             return res.status(400).json({ error: 'Invalid Query Parameters', details: result.error.flatten() });
+           }
+           ctx.query = result.data;
+        }
+
+        if (typeof routeConfig.handler !== 'function') {
+           throw new Error('Route "handler" is missing or is not a function');
+        }
+
+        const responseData = await routeConfig.handler(ctx);
+        
+        if (!res.headersSent) {
+           res.status(200).json(responseData);
+        }
+
+      } catch (err) {
+        const status = err.status || 500;
+        const message = status === 500 ? 'Internal Server Error' : err.message;
+        
+        if (status === 500) {
+          console.error(`[bro.js] Execution Error in route:`);
+          console.error(err.stack);
+        }
+        
+        if (!res.headersSent) {
+          res.status(status).json({ 
+            error: message, 
+            ...(status !== 500 && err.details ? { details: err.details } : {}) 
+          });
+        }
+      }
+    });
+    
+    return middlewares;
+  };
+
+  let openApiSpec = {
+    openapi: '3.0.0',
+    info: { title: 'bro.js API', version: '1.0.0' },
+    paths: {}
+  };
+
+  const shouldMountDocs = globalConfig.docs !== false && (globalConfig.docs === true || typeof globalConfig.docs === 'object' || process.env.NODE_ENV !== 'production');
+
+  if (shouldMountDocs) {
+    const docsAuthMiddleware = (req, res, next) => {
+      if (typeof globalConfig.docs === 'object' && globalConfig.docs.auth) {
+        const b64auth = (req.headers.authorization || '').split(' ')[1] || '';
+        const [user, pass] = Buffer.from(b64auth, 'base64').toString().split(':');
+        
+        if (user === globalConfig.docs.auth.user && pass === globalConfig.docs.auth.pass) {
+          return next();
+        }
+        
+        res.set('WWW-Authenticate', 'Basic realm="bro.js API Docs"');
+        return res.status(401).send('Authentication required.');
+      }
+      next();
+    };
+
+    app.get('/docs/json', docsAuthMiddleware, (req, res) => res.json(openApiSpec));
+    app.use('/docs', docsAuthMiddleware, apiReference({ spec: { url: '/docs/json' } }));
+  }
+
+  let routeStack = express.Router();
+  
+  app.use((req, res, next) => {
+    routeStack(req, res, next);
+  });
+
+  const reload = async () => {
+    const newRouter = express.Router();
+    openApiSpec.paths = {};
+    const routes = await loadRoutes(newRouter, routesDir, createHandler, openApiSpec);
+    routeStack = newRouter;
+    return routes;
+  };
+
+  const initialRoutes = await reload();
+
+  return { app, server, routes: initialRoutes, reload, io };
+}

package/src/tasks.js

@@ -0,0 +1,39 @@
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import cron from 'node-cron';
+import { colors } from './logger.js';
+
+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'));
+  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 taskModule = await import(moduleUrl);
+      
+      if (taskModule.cron && typeof taskModule.handler === 'function') {
+        cron.schedule(taskModule.cron, async () => {
+          try {
+            await taskModule.handler(ctx);
+          } catch (err) {
+            console.error(`\n  ${colors.red}❌ Task Error (${file}):${colors.reset}`, err);
+          }
+        });
+        count++;
+      }
+    } catch (err) {
+      console.error(`\n  ${colors.red}❌ Failed to load task ${file}:${colors.reset}`, err);
+    }
+  }
+  
+  if (count > 0) {
+    console.log(`  ${colors.dim}├──${colors.reset} ${colors.cyan}Scheduled ${count} background task(s)${colors.reset}`);
+  }
+}