@seip/blue-bird 0.6.0

package/.env_example

@@ -0,0 +1,38 @@
+# Server and Application Configuration
+DEBUG=false
+PORT=3000
+HOST="localhost"
+APP_URL="http://localhost"
+STATIC_PATH="frontend/public"
+VERSION="1.0.0"
+BLUEBIRD_PROJECT_NAME="bluebird"
+
+#Docker /Swagger config
+TITLE="Blue-Bird"
+DESCRIPTION="Description project"
+
+# HTML Meta / SEO Configuration
+TITLE_META="Blue Bird"
+DESCRIPTION_META="Example description meta"
+KEYWORDS_META="Example keywords meta"
+AUTHOR_META="Blue Bird"
+LANGMETA="en"
+
+# Security Configuration
+JWT_SECRET="JWT_SECRET"
+
+# Database Configuration (Used only for local development outside Docker)
+# SQLite (Default)
+DATABASE_URL="file:./dev.db"
+
+# MySQL (Uncomment to use MySQL locally or DEV)
+# DATABASE_URL="mysql://root:root@localhost:3306/blue_bird"
+
+# PostgreSQL (Uncomment to use PostgreSQL locally or DEV)
+# DATABASE_URL="postgresql://root:root@localhost:5432/blue_bird?schema=public"
+
+# Database / Docker Configuration
+DB_NAME="blue_bird"
+DB_USER="root"
+DB_PASSWORD="root"
+DB_PORT=3306

package/AGENTS.md

@@ -0,0 +1,276 @@
+# Blue Bird Framework - AI Agent Guide
+
+This document serves as the primary manual for any AI Agent interacting with the codebase. It details the architecture of Blue Bird, its internal modules, and how features should be written or modified.
+
+## 1. Core Architecture
+
+Blue Bird is a framework built on **Express** for backend and **HTML/Tailwind CSS/JS** for frontend rendering. It saves developers from repetitive configuration, validation, security, JWT authentication, HTML rendering with caching, and automatic HTML minification and compression out of the box.
+
+- **Backend (`backend/`)**: Initializes the server using `App` from `core/app.js` and invokes routing from `backend/routes/`.
+- **Frontend (`frontend/`)**: Static HTML views (`.html`) and static assets. Static files go in `frontend/public/`.
+- **Core (`core/`)**: The framework core. Contains wrapper classes such as `Router`, `Validator`, `Template`, `Auth`, `Cache`, etc. **DO NOT MODIFY** the core unless explicitly requested, as it could break other apps.
+
+## 2. Routing (Router)
+
+Do not use Express' native router (`express.Router()`). Always use Blue Bird's `Router` wrapper.
+
+```javascript
+import Router from "@seip/blue-bird/core/router.js";
+
+const routerApi = new Router("/api");
+
+routerApi.get("/users", (req, res) => {
+  res.json({ users: [] });
+});
+
+export default routerApi;
+```
+
+**For the Frontend (HTML Rendering / SEO):**
+Blue Bird renders HTML templates directly using its `Template` class.
+
+```javascript
+import Router from "@seip/blue-bird/core/router.js";
+import Template from "@seip/blue-bird/core/template.js";
+
+const router = new Router("/", { seo: true });
+
+router.get("/", (req, res) => {
+  return Template.render(res, "index", {
+    metaTags: {
+      titleMeta: "Home",
+      descriptionMeta: "Welcome to my site",
+    },
+  });
+});
+
+router.get("/about", (req, res) => {
+  return Template.render(res, "about", {
+    metaTags: {
+      titleMeta: "About Us",
+      descriptionMeta: "Learn more about us",
+    },
+  });
+});
+```
+
+**SEO (Sitemap & Robots.txt):**
+When a `Router` is created with `{ seo: true }`, all `GET` routes registered on it are automatically included in the generated `/sitemap.xml` and `/robots.txt`.
+
+```javascript
+const router = new Router("/", { seo: true });
+```
+
+- **Automatic Sitemap:** Dynamic `sitemap.xml` with all routes from `seo: true` routers.
+- **Robots.txt:** Auto-served pointing to the generated sitemap.
+
+## 3. HTML View Rendering (Template)
+
+The `Template` class renders HTML files directly from the `frontend/` directory. It resolves placeholders in the HTML files (using double curly braces `{{variable}}`) populated by the options, metaTags, and application configurations.
+
+### Standard Placeholders
+
+The renderer automatically replaces the following standard tags:
+
+- `{{lang}}` or `{{langHtml}}`: Active language code (defaults to `"en"`).
+- `{{title}}` or `{{titleMeta}}`: Page title.
+- `{{canonicalUrl}}`: Canonical page link.
+- `{{description}}` or `{{descriptionMeta}}`: Meta description text.
+- `{{keywords}}` or `{{keywordsMeta}}`: Meta keywords.
+- `{{author}}` or `{{authorMeta}}`: Meta author.
+- `{{classBody}}`: CSS class for the body wrapper.
+- `{{headOptions}}`: SEO Open Graph, Twitter cards, and hot reload scripts.
+- `{{linkStyles}}`: Dynamic stylesheet `<link>` tags.
+- `{{scriptsHead}}`: Script tags loaded in the `<head>`.
+- `{{scriptsBody}}`: Script tags loaded in the `<body>`.
+
+Additionally, any top-level key inside `options` or `metaTags` (e.g. `{{username}}`) will be dynamically replaced in the HTML template string.
+
+### Basic Rendering
+
+```javascript
+import Template from "@seip/blue-bird/core/template.js";
+
+router.get("/", (req, res) => {
+  return Template.render(res, "index", {
+    metaTags: {
+      titleMeta: "Home",
+      descriptionMeta: "Welcome",
+      keywordsMeta: "home, welcome",
+      authorMeta: "Blue Bird",
+    },
+  });
+});
+```
+
+### Caching and Minification Options
+
+```javascript
+Template.render(res, "index", {
+  cache: 60 /** Cache TTL in seconds. Default: 60 (only active when DEBUG=false) */,
+  minify: true /** Automatically compress whitespace and remove comments. Default: true */,
+  cacheKey: "home" /** Optional custom cache key */,
+  metaTags: { titleMeta: "Home" },
+});
+```
+
+**Cache behavior:**
+
+- `DEBUG=true` → Cache is always bypassed (reads from disk every time).
+- `DEBUG=false` + `cache` > 0 → Output HTML is cached in memory for the specified duration in seconds.
+- `DEBUG=false` + `cache: false` (or 0) → Bypasses caching entirely.
+
+### Cache Management
+
+```javascript
+import Template from "@seip/blue-bird/core/template.js";
+
+Template.clearCache();
+Template.clearCache("home");
+Template.getCacheKeys();
+```
+
+### Hot Reload (Development)
+
+When `DEBUG=true` in `.env`, Blue Bird automatically:
+
+1. Injects a hot-reload script into every rendered template.
+2. Watches `frontend/` for `.html`, `.css`, and `.js` file changes.
+3. Notifies connected browsers via Server-Sent Events (SSE) to reload.
+4. Clears the template cache on file changes.
+
+No configuration needed — it works automatically in debug mode.
+
+## 4. Data Validation (Validator)
+
+Incoming request data must be validated using `core/validate.js`, which automatically returns HTTP 400 JSON responses on error.
+
+```javascript
+import Validator from "@seip/blue-bird/core/validate.js";
+
+const userSchema = {
+  email: { required: true, email: true },
+  password: { required: true, min: 8 },
+  bio: { required: false },
+};
+
+const postSchema = {
+  contentHtml: { required: true, xss: false },
+};
+
+const validateUser = new Validator(userSchema, "en");
+
+routerApi.post("/users", validateUser.middleware(), (req, res) => {
+  res.json({ success: true });
+});
+```
+
+## 5. Authentication (Auth)
+
+The system includes built-in JWT handling with AES-256-GCM encryption. The framework handles tokens via Cookies or the `Authorization` header.
+
+### Protecting Routes
+
+Use `Auth.protect()` as a middleware to secure routes.
+
+```javascript
+import Auth from "@seip/blue-bird/core/auth.js";
+
+router.get("/profile", Auth.protect(), (req, res) => {
+  res.json({ user: req.user });
+});
+
+router.get("/dashboard", Auth.protect({ redirect: "/login" }), (req, res) => {
+  Template.render(res, "dashboard");
+});
+
+router.get(
+  "/admin",
+  Auth.protect({
+    cookieKey: "admin_session",
+    key: "admin",
+  }),
+  (req, res) => {
+    res.json({ admin: req.admin });
+  },
+);
+```
+
+### Login and Logout
+
+The `Auth` class provides helpers to handle session management via cookies.
+
+```javascript
+router.post("/login", async (req, res) => {
+  const user = { id: 1, name: "John" };
+  await Auth.login(res, user);
+  res.json({ message: "Logged in" });
+});
+
+router.post("/logout", async (req, res) => {
+  await Auth.logout(res);
+  res.json({ message: "Logged out" });
+});
+
+await Auth.login(res, user, "my_session", {
+  expiresIn: "7d",
+  cookie: { httpOnly: true, secure: true },
+});
+```
+
+## 6. Performance Caching (Cache)
+
+If a route involves heavy processing or database queries, utilize the `Cache` middleware. It automatically caches both REST API JSON payloads (overriding `res.json`) and HTML/EJS rendered views (overriding `res.send`).
+
+```javascript
+import Cache from "@seip/blue-bird/core/cache.js";
+
+router.get("/stats", Cache.middleware(60), (req, res) => {
+  res.json({ ok: true });
+});
+
+router.get("/dashboard", Cache.middleware(120), (req, res) => {
+  Template.render(res, "dashboard");
+});
+```
+
+## 7. Security (Helmet)
+
+Helmet is **not applied globally** by default. Apply it per-router where needed:
+
+```javascript
+import App from "@seip/blue-bird/core/app.js";
+
+const webRouter = new Router("/web");
+webRouter.use(App.helmet());
+webRouter.use(App.helmet({ contentSecurityPolicy: false }));
+```
+
+## 8. Docker Compose CLI
+
+Blue Bird features a built-in Docker Compose CLI wrapper to deploy and manage containerized development databases and production stacks.
+
+```bash
+# Manage containers using blue-bird CLI
+npx blue-bird docker start          # Starts production app + mysql database
+npx blue-bird docker start mysql    # Starts MySQL container only (useful for local development)
+npx blue-bird docker stop           # Stops all running containers
+npx blue-bird docker build          # Builds/rebuilds application image
+npx blue-bird docker ps             # Shows status of active containers
+npx blue-bird docker logs           # Tails Node.js app container logs
+npx blue-bird docker mysql          # Runs interactive MySQL client terminal inside the container
+npx blue-bird docker prune          # Cleans unused volumes, dangling images, and BuildKit caches
+```
+
+The container names and virtual networks are namespaced by the `TITLE` environment variable parsed from `.env` to prevent resource collisions on VPS hosts.
+
+## 9. AI Development Guidelines
+
+1. **Frontend**: Use static HTML templates inside `frontend/` (e.g. `.html` files). Standard static files belong in `frontend/public/`.
+2. **JSON Responses**: API endpoints should return standardized responses formatted as `{ message: "..." }` or `{ data: ... }`.
+3. **Magic Imports**: Stick to pure relative imports or well-configured aliases (imports natively resolve from `@seip/blue-bird/...` or relative directories like `../../`).
+4. **SEO**: Create routers with `{ seo: true }` to auto-include routes in sitemap.xml and robots.txt.
+5. **Caching & Minification**: Cache pages using `Template.render` options or route-level `Cache.middleware()`. All HTML outputs are automatically minified.
+6. **No inline comments**: Only use JSDoc for documentation.
+
+_This file can be retrieved by intelligent agents reading its absolute physical path during reasoning._

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,311 @@
+# Blue Bird Framework
+
+**High-Performance Express Framework — Built for Speed, Caching, and Visual Excellence**
+
+![Blue Bird Logo](https://seip25.github.io/Blue-bird/blue-bird.png)
+
+[![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)
+
+---
+
+## 🌟 Introduction / Introducción
+
+**Blue Bird** is a powerful, opinionated framework built on **Express**. It's designed to help developers build fast, scalable applications and APIs with everything pre-configured: data validation, security middlewares, GCM-encrypted JWT authentication, raw HTML template rendering with fast in-memory caching, automatic HTML minification, SEO management, hot-reload, and CLI/Docker developer workflows out of the box.
+
+**Blue Bird** es un framework potente basado en **Express**. Está diseñado para ayudar a los desarrolladores a construir aplicaciones rápidas, APIs escalables y todo pre-configurado: validación de datos, middlewares de seguridad, autenticación JWT encriptada con GCM, renderizado de plantillas HTML crudo con caché ultra rápida en memoria, minificación HTML automática, gestión de SEO, hot-reload y flujos de trabajo con Docker y CLI integrados.
+
+---
+
+## 🚀 Key Features / Características Clave
+
+- ⚡ **All-In-One**: Pre-configured Express server with JSON, URL encoding, Cookies, and CORS.
+- 🚀 **Fast Rendering**: Raw HTML template rendering (`Template.render`) with in-memory caching (configurable TTL).
+- 🧹 **Automatic Minification**: Compresses whitespace and strips HTML comments automatically in production.
+- 🔐 **Premium Security**: AES-256-GCM encrypted JWT cookie auth, secure route filters, and built-in Helmet configurator.
+- 📁 **File Uploads**: Easy Multer-based single/multiple file storage handling.
+- 🔄 **SSE Hot Reload**: Automated browser hot-reloading in development (`DEBUG=true`) on file changes.
+- 🐳 **Docker & PM2 Devops**: Pre-built Docker Compose/Dockerfile templates and CLI tools for zero-config dev and VPS production.
+
+---
+
+## 🛠️ Quick Start / Inicio Rápido
+
+### 1. Installation / Instalación
+
+```bash
+npm install @seip/blue-bird
+```
+
+### 2. Initialize Project / Inicializar
+
+```bash
+npx blue-bird
+```
+
+_This copies the base structure: `backend`, `frontend`, `docker`, `docker-compose.yml`, `AGENTS.md`, and `.env`._
+
+### 3. Run Development Server / Modo Desarrollo
+
+```bash
+npm run dev
+```
+
+---
+
+## 📁 Project Structure / Estructura del Proyecto
+
+```
+project/
+├── backend/
+│   ├── routes/              # Express route files
+│   │   ├── api.js           # REST API routes
+│   │   └── frontend.js      # Frontend HTML template routes
+│   └── index.js             # App startup and initialization
+├── frontend/
+│   ├── templates/           # Raw HTML template pages (.html)
+│   │   ├── index.html
+│   │   └── about.html
+│   └── public/              # Static assets (css, js, img, fonts)
+│       └── js/
+│           └── tailwind.js  # Local Tailwind compiler
+├── docker/
+│   └── Dockerfile           # Optimized production multi-stage build file
+├── docker-compose.yml       # Dev/Prod container configurations
+├── AGENTS.md                # AI coding assistant guidebook
+└── .env                     # App configuration (git-ignored)
+```
+
+---
+
+## 📖 Core Modules Documentation / Documentación de Módulos
+
+### 1. Routing & SEO (`Router`)
+
+Do not use Express' native router. Always use Blue Bird's wrapper class:
+
+```javascript
+import Router from "@seip/blue-bird/core/router.js";
+
+const routerApi = new Router("/api");
+routerApi.get("/users", (req, res) => {
+  res.json({ users: [] });
+});
+export default routerApi;
+```
+
+**For the Frontend (HTML Rendering / SEO):**
+Instantiate a router with `{ seo: true }`. All registered GET routes are automatically added to the dynamic sitemap at `/sitemap.xml` and `/robots.txt`.
+
+```javascript
+const router = new Router("/", { seo: true });
+router.get("/", (req, res) => {
+  return Template.render(res, "index", {
+    metaTags: {
+      titleMeta: "Home",
+      descriptionMeta: "Welcome to Blue Bird Framework",
+    },
+  });
+});
+```
+
+---
+
+### 2. HTML Template Rendering (`Template`)
+
+Renders raw HTML files from `frontend/templates/`. Replaces double-curly placeholders `{{variable}}` with matching values from options, metaTags, or system env.
+
+#### Standard Placeholders
+
+- `{{lang}}`: Selected/active language code.
+- `{{title}}` or `{{titleMeta}}`: Page HTML title.
+- `{{canonicalUrl}}`: Canonical page URL for crawlers.
+- `{{description}}`: Meta description.
+- `{{keywords}}`: Meta keywords.
+- `{{author}}`: Meta author.
+
+```javascript
+import Template from "@seip/blue-bird/core/template.js";
+
+router.get("/about", (req, res) => {
+  return Template.render(res, "about", {
+    cache: 60, // Cache TTL in seconds (only when DEBUG=false)
+    minify: true, // Automatically minifies whitespace and strips comments
+    metaTags: {
+      titleMeta: "About Us",
+      descriptionMeta: "Learn more about us",
+    },
+  });
+});
+```
+
+#### Cache Controls
+
+- `DEBUG=true` -> Cache is always bypassed.
+- `DEBUG=false` -> Cached in-memory for TTL duration.
+- Programmatic management:
+  ```javascript
+  Template.clearCache(); // Clear all cache
+  Template.clearCache("about"); // Clear specific cache key
+  Template.getCacheKeys(); // Returns active cache keys
+  ```
+
+---
+
+### 3. Data Validation (`Validator`)
+
+Validates request payloads using a JSON schema. Returns structured `400 Bad Request` payloads automatically on schema failures.
+
+```javascript
+import Validator from "@seip/blue-bird/core/validate.js";
+
+const userSchema = {
+  email: { required: true, email: true },
+  password: { required: true, min: 8 },
+  bio: { required: false },
+};
+
+const validateUser = new Validator(userSchema, "en");
+
+routerApi.post("/users", validateUser.middleware(), (req, res) => {
+  res.json({ success: true });
+});
+```
+
+---
+
+### 4. JWT Authentication (`Auth`)
+
+Secure user sessions using stateless AES-256-GCM encrypted JWTs stored in secure HTTP-Only cookies.
+
+#### Protecting Routes
+
+```javascript
+import Auth from "@seip/blue-bird/core/auth.js";
+
+// Secure API endpoint (returns 401 on failure)
+router.get("/profile", Auth.protect(), (req, res) => {
+  res.json({ user: req.user });
+});
+
+// Secure web page (redirects to /login on failure)
+router.get("/dashboard", Auth.protect({ redirect: "/login" }), (req, res) => {
+  Template.render(res, "dashboard");
+});
+```
+
+#### Authentication Sessions
+
+```javascript
+router.post("/login", async (req, res) => {
+  const user = { id: 1, name: "John Doe" };
+  await Auth.login(res, user);
+  res.json({ message: "Logged in successfully" });
+});
+
+router.post("/logout", async (req, res) => {
+  await Auth.logout(res);
+  res.json({ message: "Logged out" });
+});
+```
+
+---
+
+### 5. Performance Cache Middleware (`Cache`)
+
+Applies caching at the route handler level. Automatically caches JSON payloads (`res.json`) and rendered outputs (`res.send`).
+
+```javascript
+import Cache from "@seip/blue-bird/core/cache.js";
+
+// Cache endpoint for 60 seconds
+router.get("/stats", Cache.middleware(60), (req, res) => {
+  res.json({ usersOnline: 42 });
+});
+```
+
+---
+
+### 6. Security Headers (`Helmet`)
+
+Apply security headers per-router. Preserves the framework's custom powered-by header by default:
+
+```javascript
+import App from "@seip/blue-bird/core/app.js";
+
+const webRouter = new Router("/web");
+webRouter.use(App.helmet());
+```
+
+---
+
+## 🐳 Docker CLI Workflow
+
+Blue Bird comes with a built-in Docker CLI wrapper that handles both local development database bootstrapping and full-stack VPS production deployments.
+
+### Commands Syntax:
+
+```bash
+npx blue-bird docker <command> [options]
+```
+
+### Supported Actions:
+
+- **`npx blue-bird docker start`**: Boots the production stack (Node.js App + MySQL).
+- **`npx blue-bird docker start mysql`**: Boots the MySQL container only (great for local HTTP development).
+- **`npx blue-bird docker stop`**: Stops all active containers.
+- **`npx blue-bird docker build [--no-cache]`**: Builds or updates the Node.js production image.
+- **`npx blue-bird docker ps`**: Lists running project containers and ports.
+- **`npx blue-bird docker logs [app|mysql]`**: Tails logs for the specified container.
+- **`npx blue-bird docker db`**: Connects into the container's interactive MySQL shell using credentials from `.env`.
+- **`npx blue-bird docker prune`**: Safely clears orphaned volumes, dangling build caches, and images.
+
+---
+
+## 🚀 Production Deployment Options
+
+You can deploy Blue Bird applications to production using two main workflows:
+
+### A. Docker Container Stack (Recommended)
+
+1. Configure `.env` with production keys,DEBUG=false and your custom `TITLE`.
+2. Build the production image:
+   ```bash
+   npx blue-bird docker build
+   ```
+3. Run the container cluster:
+   ```bash
+   npx blue-bird docker start prod
+   ```
+
+### B. Standard PM2 / Node.js Runtime
+
+To deploy in a standard Linux environment using PM2 process manager:
+
+1. Install PM2 globally:
+   ```bash
+   npm install pm2 -g
+   ```
+2. Start the application under PM2:
+   ```bash
+   pm2 start backend/index.js --name "bluebird-app"
+   ```
+3. Monitor status:
+   ```bash
+   pm2 status
+   pm2 logs
+   ```
+
+---
+
+## 📄 License / Licencia
+
+Distributed under the **MIT License**. See `LICENSE` for more information.
+
+Distribuido bajo la **Licencia MIT**. Mira `LICENSE` para más información.
+
+---
+
+<div align="center">
+  <p>Made with ❤️ by <strong>Seip25</strong></p>
+</div>

package/backend/index.js

@@ -0,0 +1,21 @@
+import App from "@seip/blue-bird/core/app.js";
+import routerApiExample from "./routes/api.js";
+import routerFrontendExample from "./routes/frontend.js";
+
+/**
+ * Main entry point for the Blue Bird application.
+ * Initializes the App instance with routes, configuration, and starts the server.
+ */
+const app = new App({
+  routes: [routerApiExample, routerFrontendExample],
+
+  cors: [],
+
+  middlewares: [],
+
+  host: "http://localhost",
+
+  port: process.env.PORT,
+});
+
+app.run();