@seip/blue-bird 0.1.0

package/.env_example

@@ -0,0 +1,12 @@
+DEBUG=true
+DESCRIPTION_META="Example description meta"
+KEYWORDS_META="Example keywords meta"
+TITLE_META="Blue Bird"
+AUTHOR_META="Blue Bird"
+DESCRIPTION="Description project"
+TITLE="Blue Bird"
+VERSION="1.0.0"
+LANGMETA="en"
+HOST="http://localhost"
+PORT=3001
+STATIC_PATH="frontend/public"

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andres Paiva
+
+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,81 @@
+<div align="center">
+  <img src="https://seip25.github.io/Blue-bird/blue-bird.png" alt="Blue Bird Logo" width="120" />
+  <h1>Blue Bird Framework</h1>
+  <p><strong>The Future of Express & React Development</strong></p>
+
+  [![npm version](https://img.shields.io/npm/v/@seip/blue-bird.svg)](https://www.npmjs.com/package/@seip/blue-bird)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+</div>
+
+<hr />
+
+## 🌟 Introduction / Introducción
+
+**Blue Bird** is a powerful, opinionated structure based on **Express** and **React**. It's designed to help developers build fast, scalable applications with hydrated components (Islands or Full views) and everything pre-configured.
+
+**Blue Bird** es una estructura potente basada en **Express** y **React**. Está diseñada para ayudar a los desarrolladores a construir aplicaciones rápidas y escalables con componentes hidratados (Islas o vistas completas) y todo pre-configurado.
+
+<hr />
+
+## 🚀 Key Features / Características Clave
+
+- ⚡ **All-In-One**: Express, React, Vite, JWT Auth, and Validations ready to go.
+- 💎 **Flexible**: Extensible via standard Express `.use()` middleware.
+- 🏝️ **Island Architecture**: Hydrate only what you need with React.
+- 🔐 **Secure**: Integrated JWT authentication and multi-language validation.
+- 📁 **Uploads**: Easy file handling with Multer-based helpers.
+
+<hr />
+
+## 🛠️ Quick Start / Inicio Rápido
+
+### 1. Installation / Instalación
+```bash
+npm install @seip/blue-bird
+```
+
+### 2. Initialize / Inicializar
+```bash
+npx blue-bird
+```
+*This copies the base structure: `backend`, `frontend`, and `.env`.*
+*Esto copia la estructura base: `backend`, `frontend` y `.env`.*
+
+### 3. Setup React
+```bash
+npm run react
+```
+*Configures React, React Router, and Vite automatically.*
+*Configura React, React Router y Vite automáticamente.*
+
+### 4. Development / Desarrollo
+```bash
+# Start Backend (Express)
+npm run dev
+
+# Start Frontend (Vite)
+npm run vite:dev
+```
+
+<hr />
+
+## 📖 Documentation / Documentación
+
+Check out our full documentation for detailed API reference and examples:
+
+- 🇺🇸 [English Documentation](https://seip25.github.io/Blue-bird/en.html)
+- 🇪🇸 [Documentación en Español](https://seip25.github.io/Blue-bird/index.html)
+
+<hr />
+
+## 📄 License / Licencia
+
+Distributed under the **MIT License**. See `LICENSE` for more information.
+
+Distribuido bajo la **Licencia MIT**. Mira `LICENSE` para más información.
+
+<hr />
+
+<div align="center">
+  <p>Made with ❤️ by <strong>Seip25</strong></p>
+</div>

package/backend/index.js

@@ -0,0 +1,13 @@
+import App from "@seip/blue-bird/core/app.js";
+import routerUsers from "./routes/app.js";
+
+const app = new App({
+    routes: [routerUsers],
+    cors: [],
+    middlewares: [],
+    port: 3000,
+    host: "http://localhost"
+})
+
+
+app.run()

package/backend/routes/app.js

@@ -0,0 +1,41 @@
+import Router from "@seip/blue-bird/core/router.js"
+import Validator from "@seip/blue-bird/core/validate.js"
+import Template from "@seip/blue-bird/core/template.js"
+
+
+const routerUsers = new Router("/")
+
+routerUsers.get("/users", (req, res) => {
+    const users = [
+        {
+            name: "John Doe",
+            email: "john.doe@example.com",
+        },
+        {
+            name: "Jane Doe2",
+            email: "jane.doe2@example.com",
+        },
+    ]
+    res.json(users)
+})
+
+const loginSchema = {
+    email: { required: true, email: true },
+    password: { required: true, min: 6 }
+};
+
+const loginValidator = new Validator(loginSchema, 'es');
+
+routerUsers.post('/login', loginValidator.middleware(), (req, res) => {
+    res.json({ message: 'Login successful' });
+});
+
+
+routerUsers.get("*", (req, res) => {
+    const response = Template.renderReact(res, "App", { title: "Example title" });
+    return response;
+
+})
+
+
+export default routerUsers

package/core/app.js

@@ -0,0 +1,150 @@
+import express from "express"
+import cors from "cors"
+import path from "path"
+import chalk from "chalk"
+import cookieParser from "cookie-parser"
+import Config from "./config.js"
+import Logger from "./logger.js"
+
+const __dirname = Config.dirname()
+const props = Config.props()
+
+/**
+ * Main Application class to manage Express server, routes, and middlewares.
+ */
+class App {
+    /**
+     * Initializes the App instance with the provided options.
+     * @param {Object} [options] - Configuration options for the application.
+     * @param {Array<{path: string, router: import('express').Router}>} [options.routes=[]] - Array of route objects containing path and router components.
+     * @param {Object} [options.cors={}] - CORS configuration options.
+     * @param {Array<Function>} [options.middlewares=[]] - Array of middleware functions to be applied.
+     * @param {number|string} [options.port=3000] - Server port.
+     * @param {string} [options.host="http://localhost"] - Server host URL.
+     * @param {boolean} [options.logger=true] - Whether to enable the request logger.
+     * @param {boolean} [options.notFound=true] - Whether to enable the default 404 handler.
+     * @param {boolean} [options.json=true] - Whether to enable JSON body parsing.
+     * @param {boolean} [options.urlencoded=true] - Whether to enable URL-encoded body parsing.
+     * @param {Object} [options.static={path: null, options: {}}] - Static file configuration.
+     * @param {boolean} [options.cookieParser=true] - Whether to enable cookie parsing.
+     */
+    constructor(options = {
+        routes: [],
+        cors: {},
+        middlewares: [],
+        port: null,
+        host: null,
+        logger: true,
+        notFound: true,
+        json: true,
+        urlencoded: true,
+        static: {
+            path: null,
+            options: {}
+        },
+        cookieParser: true,
+
+    }) {
+        this.app = express()
+        this.routes = options.routes || []
+        this.cors = options.cors || {}
+        this.middlewares = options.middlewares || []
+        this.port = options.port || props.port
+        this.host = options.host || props.host
+        this.logger = options.logger || true
+        this.notFound = options.notFound || true
+        this.json = options.json || true
+        this.urlencoded = options.urlencoded || true
+        this.static = options.static || props.static
+        this.cookieParser = options.cookieParser || true
+        this.dispatch()
+
+    }
+
+    /**
+     * Registers a custom middleware or module in the Express application.
+     * @param {Function|import('express').Router} record - The middleware function or Express router to register.
+     */
+    use(record) {
+        this.app.use(record)
+    }
+
+    /**
+     * Bootstraps the application by configuring global middlewares and routes.
+     * Sets up JSON parsing, URL encoding, CORS, and custom middlewares.
+     */
+    dispatch() {
+        if (this.json) this.app.use(express.json())
+        if (this.urlencoded) this.app.use(express.urlencoded({ extended: true }))
+        if (this.cookieParser) this.app.use(cookieParser())
+        if (this.static.path) this.app.use(express.static(path.join(__dirname, this.static.path), this.static.options))
+        this.app.use(cors(this.cors))
+        this.middlewares.map(middleware => {
+            this.app.use(middleware)
+        })
+        if (this.logger) this.middlewareLogger()
+        this.app.use((req, res, next) => {
+            res.setHeader('X-Powered-By', 'Blue Bird');
+            next();
+        });
+        this.dispatchRoutes()
+
+        if (this.notFound) this.notFoundDefault()
+    }
+
+
+    /**
+     * Middleware that logs incoming HTTP requests to the console and to a log file.
+     */
+    middlewareLogger() {
+        this.app.use((req, res, next) => {
+            const method = req.method
+            const url = req.url
+            const params = Object.keys(req.params).length > 0 ? ` ${JSON.stringify(req.params)}` : ""
+            const ip = req.ip
+            const now = new Date().toISOString()
+            const time = `${now.split("T")[0]} ${now.split("T")[1].split(".")[0]}`
+            let message = ` ${time} -${ip} -[${method}] ${url} ${params}`
+            const logger = new Logger()
+            logger.info(message)
+            if (props.debug) {
+                message = `${chalk.bold.green(time)} - ${chalk.bold.cyan(ip)} -[${chalk.bold.red(method)}] ${chalk.bold.blue(url)} ${chalk.bold.yellow(params)}`
+                console.log(message)
+            }
+            next()
+        })
+    }
+
+    /**
+     * Iterates through the stored routes and attaches them to the Express application instance.
+     */
+    dispatchRoutes() {
+        this.routes.map(route => {
+            this.app.use(route.path, route.router)
+        })
+    }
+    /**
+     * Default 404 handler for unmatched routes.
+     * Returns a JSON response with a "Not Found" message.
+     */
+    notFoundDefault() {
+        this.app.use((req, res) => {
+            return res.status(404).json({ message: "Not Found" })
+        });
+    }
+    /**
+     * Starts the HTTP server and begins listening for incoming connections.
+     */
+    run() {
+        this.app.listen(this.port, () => {
+            console.log(
+                chalk.bold.blue('Blue Bird Server Online\n') +
+                chalk.bold.cyan('Host: ') + chalk.green(`${this.host}:${this.port}`) + '\n' +
+                chalk.gray('────────────────────────────────')
+            );
+        });
+    }
+}
+
+export default App
+

package/core/auth.js

@@ -0,0 +1,59 @@
+import jwt from "jsonwebtoken";
+
+/**
+ * Auth class to handle JWT generation, verification and protection.
+ */
+class Auth {
+    /**
+     * Generates a JWT token.
+     * @param {Object} payload - The data to store in the token.
+     * @param {string} [secret=process.env.JWT_SECRET] - The secret key.
+     * @param {string|number} [expiresIn='24h'] - Expiration time.
+     * @returns {string} The generated token.
+     */
+    static generateToken(payload, secret = process.env.JWT_SECRET || 'blue-bird-secret', expiresIn = '24h') {
+        return jwt.sign(payload, secret, { expiresIn });
+    }
+
+    /**
+     * Verifies a JWT token.
+     * @param {string} token - The token to verify.
+     * @param {string} [secret=process.env.JWT_SECRET] - The secret key.
+     * @returns {Object|null} The decoded payload or null if invalid.
+     */
+    static verifyToken(token, secret = process.env.JWT_SECRET || 'blue-bird-secret') {
+        try {
+            return jwt.verify(token, secret);
+        } catch (error) {
+            return null;
+        }
+    }
+
+    /**
+     * Middleware to protect routes. Checks for token in Cookies or Authorization header.
+     * @param {Object} options - Options for protection.
+     * @param {string} [options.redirect] - URL to redirect if not authenticated (for web routes).
+     * @returns {Function} Express middleware.
+     */
+    static protect(options = { redirect: null }) {
+        return (req, res, next) => {
+            const token = req.cookies?.token || req.headers.authorization?.split(" ")[1];
+
+            if (!token) {
+                if (options.redirect) return res.redirect(options.redirect);
+                return res.status(401).json({ message: "Unauthorized: No token provided" });
+            }
+
+            const decoded = this.verifyToken(token);
+            if (!decoded) {
+                if (options.redirect) return res.redirect(options.redirect);
+                return res.status(401).json({ message: "Unauthorized: Invalid token" });
+            }
+
+            req.user = decoded;
+            next();
+        };
+    }
+}
+
+export default Auth;

package/core/cli/init.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+
+class ProjectInit {
+    constructor() {
+        this.appDir = process.cwd();
+        this.sourceDir = path.resolve(import.meta.dirname, "../../");
+    }
+
+    async run() {
+        console.log(chalk.cyan("Starting Blue Bird project initialization..."));
+
+        const itemsToCopy = [
+            "backend",
+            "frontend",
+            ".env_example"
+        ];
+
+        try {
+            itemsToCopy.forEach(item => {
+                const src = path.join(this.sourceDir, item);
+                const dest = path.join(this.appDir, item);
+
+                if (fs.existsSync(src)) {
+                    if (!fs.existsSync(dest)) {
+                        this.copyRecursive(src, dest);
+                        console.log(chalk.green(`✓ Copied ${item} to root.`));
+                    } else {
+                        console.log(chalk.yellow(`! ${item} already exists, skipping.`));
+                    }
+                } else {
+                    console.warn(chalk.red(`✗ Source ${item} not found in ${this.sourceDir}`));
+                }
+            });
+
+            const envPath = path.join(this.appDir, ".env");
+            const envExamplePath = path.join(this.appDir, ".env_example");
+            if (fs.existsSync(envExamplePath) && !fs.existsSync(envPath)) {
+                fs.copyFileSync(envExamplePath, envPath);
+                console.log(chalk.green("✓ Created .env from .env_example."));
+            }
+
+            this.updatePackageJson();
+
+            console.log(chalk.blue("\nBlue Bird initialization completed!"));
+            console.log(chalk.white("Next steps:"));
+            console.log(chalk.bold("  npm install"));
+            console.log(chalk.bold("  npm run react"));
+            console.log(chalk.bold("  npm run dev"));
+
+        } catch (error) {
+            console.error(chalk.red("Error during initialization:"), error.message);
+        }
+    }
+
+    updatePackageJson() {
+        const pkgPath = path.join(this.appDir, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            pkg.scripts = pkg.scripts || {};
+
+            const scriptsToAdd = {
+                "dev": "node --watch --env-file=.env backend/index.js",
+                "start": "node --env-file=.env backend/index.js",
+                "react": "blue-bird react",
+                "init": "blue-bird"
+            };
+
+            let updated = false;
+            for (const [key, value] of Object.entries(scriptsToAdd)) {
+                if (!pkg.scripts[key]) {
+                    pkg.scripts[key] = value;
+                    updated = true;
+                }
+            }
+
+            if (updated) {
+                fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+                console.log(chalk.green("✓ Updated package.json scripts."));
+            }
+        }
+    }
+
+    copyRecursive(src, dest) {
+        const stats = fs.statSync(src);
+        const isDirectory = stats.isDirectory();
+
+        if (isDirectory) {
+            if (!fs.existsSync(dest)) {
+                fs.mkdirSync(dest, { recursive: true });
+            }
+            fs.readdirSync(src).forEach(childItemName => {
+                this.copyRecursive(path.join(src, childItemName), path.join(dest, childItemName));
+            });
+        } else {
+            fs.copyFileSync(src, dest);
+        }
+    }
+}
+
+const initializer = new ProjectInit();
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === "react") {
+    // Dynamically import ReactScaffold to avoid circular dependencies if any, 
+    // or just run it if it's separate.
+    import("./react.js");
+} else {
+    initializer.run();
+}
+