npm - @seip/blue-bird - Versions diffs - 0.6.0 - Mend

@seip/blue-bird 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/.env_example +38 -0
package/AGENTS.md +276 -0
package/LICENSE +21 -0
package/README.md +311 -0
package/backend/index.js +21 -0
package/backend/routes/api.js +53 -0
package/backend/routes/frontend.js +29 -0
package/core/app.js +397 -0
package/core/auth.js +180 -0
package/core/cache.js +72 -0
package/core/cli/docker.js +319 -0
package/core/cli/init.js +130 -0
package/core/cli/route.js +43 -0
package/core/cli/swagger.js +40 -0
package/core/config.js +52 -0
package/core/debug.js +249 -0
package/core/logger.js +100 -0
package/core/middleware.js +27 -0
package/core/router.js +148 -0
package/core/seo.js +113 -0
package/core/swagger.js +40 -0
package/core/template.js +254 -0
package/core/upload.js +77 -0
package/core/validate.js +380 -0
package/docker/Dockerfile +25 -0
package/docker-compose.yml +70 -0
package/frontend/public/favicon.ico +0 -0
package/frontend/public/js/spa.js +183 -0
package/frontend/public/js/tailwind.js +8 -0
package/frontend/templates/about.html +101 -0
package/frontend/templates/index.html +140 -0
package/package.json +59 -0

package/core/debug.js ADDED Viewed

@@ -0,0 +1,249 @@
+import Router from "./router.js";
+/**
+ * Advanced Debug module for Blue Bird.
+ * Provides metrics history, route statistics and live monitoring.
+ */
+class Debug {
+    constructor() {
+        this.router = new Router("/debug");
+        this.limit = 50;
+        this.initStore();
+        this.registerRoutes();
+    }
+    initStore() {
+        if (!global.__bluebird_debug_store__) {
+            global.__bluebird_debug_store__ = {
+                requests: [],
+                routes: {},
+                errors4xx: 0,
+                errors5xx: 0
+            };
+        }
+    }
+    static shouldTrack(req) {
+        const url = req.originalUrl || "";
+        if (url.startsWith("/debug")) return false;
+        if (/\.(json|css|js|map|png|jpg|jpeg|gif|svg|ico|webp)$/i.test(url)) {
+            return false;
+        }
+        if (req.method === "OPTIONS") return false;
+        return true;
+    }
+    static middlewareMetrics(app) {
+        app.use((req, res, next) => {
+            if (!Debug.shouldTrack(req)) return next();
+            const start = process.hrtime();
+            res.on("finish", () => {
+                const diff = process.hrtime(start);
+                const responseTime = diff[0] * 1e3 + diff[1] / 1e6;
+                const memory = process.memoryUsage();
+                const ramUsedMB = memory.rss / 1024 / 1024;
+                const cpuUsage = process.cpuUsage();
+                const cpuUsedMS = (cpuUsage.user + cpuUsage.system) / 1000;
+                const record = {
+                    method: req.method,
+                    url: req.originalUrl,
+                    status: res.statusCode,
+                    responseTime: Number(responseTime.toFixed(2)),
+                    ramUsedMB: Number(ramUsedMB.toFixed(2)),
+                    cpuUsedMS: Number(cpuUsedMS.toFixed(2)),
+                    date: new Date().toISOString()
+                };
+                const store = global.__bluebird_debug_store__;
+                store.requests.unshift(record);
+                if (store.requests.length > 50) store.requests.pop();
+                const routeKey = `${req.method} ${req.route?.path || req.path}`;
+                if (!store.routes[routeKey]) {
+                    store.routes[routeKey] = {
+                        count: 0,
+                        totalTime: 0
+                    };
+                }
+                store.routes[routeKey].count += 1;
+                store.routes[routeKey].totalTime += record.responseTime;
+                if (record.status >= 400 && record.status < 500) store.errors4xx++;
+                if (record.status >= 500) store.errors5xx++;
+            });
+            next();
+        });
+    }
+    registerRoutes() {
+        this.router.get("/", (req, res) => {
+            const store = global.__bluebird_debug_store__;
+            if (req.query.fetch === "true") {
+                return res.json(store);
+            }
+            if (req.query.reset === "true") {
+                global.__bluebird_debug_store__ = {
+                    requests: [],
+                    routes: {},
+                    errors4xx: 0,
+                    errors5xx: 0
+                };
+                return res.json({ ok: true });
+            }
+            res.send(`
+<!DOCTYPE html>
+<html>
+<head>
+<script src="https://cdn.tailwindcss.com"></script>
+<title>Blue Bird Debug</title>
+</head>
+<body class="bg-gray-100 text-gray-800 p-10">
+<div class="max-w-7xl mx-auto">
+<div class="flex justify-between items-center mb-8">
+<h1 class="text-3xl font-bold text-blue-600">Blue Bird Debug Panel</h1>
+<button onclick="resetData()" class="bg-red-500 hover:bg-red-600 text-white px-4 py-2 rounded-lg shadow">
+Reset
+</button>
+</div>
+<div class="grid grid-cols-3 gap-6 mb-8">
+<div class="bg-white p-6 rounded-xl shadow">
+<h3 class="text-gray-500 text-sm">Total Requests</h3>
+<p id="totalReq" class="text-2xl font-bold">0</p>
+</div>
+<div class="bg-yellow-100 p-6 rounded-xl shadow">
+<h3 class="text-yellow-600 text-sm">4xx Errors</h3>
+<p id="err4" class="text-2xl font-bold text-yellow-700">0</p>
+</div>
+<div class="bg-red-100 p-6 rounded-xl shadow">
+<h3 class="text-red-600 text-sm">5xx Errors</h3>
+<p id="err5" class="text-2xl font-bold text-red-700">0</p>
+</div>
+</div>
+<div class="grid grid-cols-2 gap-10">
+<div class="bg-white p-6 rounded-xl shadow">
+<h2 class="text-lg font-semibold mb-4">Route Stats</h2>
+<table class="table-fixed w-full text-sm">
+<thead>
+<tr class="border-b">
+<th class="text-left w-1/2 py-2">Route</th>
+<th class="text-left w-1/4">Hits</th>
+<th class="text-left w-1/4">Avg Time</th>
+</tr>
+</thead>
+<tbody id="routesBody"></tbody>
+</table>
+</div>
+<div class="bg-white p-6 rounded-xl shadow">
+<h2 class="text-lg font-semibold mb-4">Last Requests</h2>
+<table class="table-fixed w-full text-sm">
+<thead>
+<tr class="border-b">
+<th class="text-left w-1/2 py-2">URL</th>
+<th class="text-left w-1/6">Method</th>
+<th class="text-left w-1/6">Status</th>
+<th class="text-left w-1/6">Time</th>
+</tr>
+</thead>
+<tbody id="historyBody"></tbody>
+</table>
+</div>
+</div>
+</div>
+<script>
+async function loadData() {
+    const res = await fetch('/debug?fetch=true');
+    const data = await res.json();
+    document.getElementById("totalReq").innerText = data.requests.length;
+    document.getElementById("err4").innerText = data.errors4xx;
+    document.getElementById("err5").innerText = data.errors5xx;
+    const routesBody = document.getElementById("routesBody");
+    const historyBody = document.getElementById("historyBody");
+    routesBody.innerHTML = "";
+    historyBody.innerHTML = "";
+    Object.entries(data.routes).forEach(([key, value]) => {
+        const avg = (value.totalTime / value.count).toFixed(2);
+        let color = "";
+        if (avg > 500) color = "text-red-600 font-semibold";
+        else if (avg > 200) color = "text-yellow-600";
+        routesBody.innerHTML += \`
+        <tr class="border-b">
+            <td class="py-1 truncate">\${key}</td>
+            <td>\${value.count}</td>
+            <td class="\${color}">\${avg} ms</td>
+        </tr>\`;
+    });
+    data.requests.forEach(r => {
+        historyBody.innerHTML += \`
+        <tr class="border-b text-xs">
+            <td class="truncate">\${r.url}</td>
+            <td>\${r.method}</td>
+            <td>\${r.status}</td>
+            <td>\${r.responseTime} ms</td>
+        </tr>\`;
+    });
+}
+async function resetData() {
+    await fetch('/debug?reset=true');
+    loadData();
+}
+loadData();
+setInterval(loadData, 3000);
+</script>
+</body>
+</html>
+            `);
+        });
+    }
+    getRouter() {
+        return {
+            path: this.router.getPath(),
+            router: this.router.getRouter()
+        };
+    }
+}
+export default Debug;

package/core/logger.js ADDED Viewed

@@ -0,0 +1,100 @@
+import fs from "node:fs";
+import path from "node:path";
+import Config from "./config.js"
+const __dirname = Config.dirname()
+/**
+ * Logger class for managing application logs by creating dated folders and log files.
+ */
+class Logger {
+    /**
+     * Initializes the Logger instance and ensures the logs directory exists.
+     */
+    constructor() {
+        this.folder = path.join(__dirname, "logs");
+        this._currentDay = null;
+        this._currentDayFolder = null;
+        if (!fs.existsSync(this.folder)) {
+            fs.mkdirSync(this.folder, { recursive: true });
+        }
+    }
+    /**
+     * Ensures and returns the path to the log folder for the current day.
+     * Caches the folder path for the current day to avoid repeated fs checks.
+     * @returns {string} The absolute path to the current day's log folder.
+     */
+    nowFolder() {
+        const today = this.now();
+        if (this._currentDay === today && this._currentDayFolder) {
+            return this._currentDayFolder;
+        }
+        const folder = path.join(this.folder, today);
+        if (!fs.existsSync(folder)) {
+            fs.mkdirSync(folder, { recursive: true });
+        }
+        this._currentDay = today;
+        this._currentDayFolder = folder;
+        return folder;
+    }
+    /**
+     * Gets the current date formatted as YYYY-MM-DD.
+     * @returns {string} The formatted date string.
+     */
+    now() {
+        return new Date().toISOString().split("T")[0];
+    }
+    /**
+     * Appends an informational message to the info.log file (non-blocking).
+     * @param {string} message - The message to log.
+     */
+    info(message) {
+        const logFile = path.join(this.nowFolder(), 'info.log');
+        fs.appendFile(logFile, `${message}\n`, (err) => {
+            if (err) console.error('Logger write error:', err.message);
+        });
+    }
+    /**
+     * Appends an error message to the error.log file (non-blocking).
+     * @param {string} message - The error message to log.
+     */
+    error(message) {
+        const logFile = path.join(this.nowFolder(), 'error.log');
+        fs.appendFile(logFile, `${message}\n`, (err) => {
+            if (err) console.error('Logger write error:', err.message);
+        });
+    }
+    /**
+     * Appends a warning message to the warn.log file (non-blocking).
+     * @param {string} message - The warning message to log.
+     */
+    warning(message) {
+        const logFile = path.join(this.nowFolder(), 'warn.log');
+        fs.appendFile(logFile, `${message}\n`, (err) => {
+            if (err) console.error('Logger write error:', err.message);
+        });
+    }
+    /**
+     * Appends a debug message to the debug.log file (non-blocking).
+     * @param {string} message - The debug message to log.
+     */
+    debug(message) {
+        const logFile = path.join(this.nowFolder(), 'debug.log');
+        fs.appendFile(logFile, `${message}\n`, (err) => {
+            if (err) console.error('Logger write error:', err.message);
+        });
+    }
+}
+export default Logger;

package/core/middleware.js ADDED Viewed

@@ -0,0 +1,27 @@
+import Auth from "./auth.js";
+/**
+ * Common middlewares for the Blue Bird framework.
+ */
+const Middleware = {
+    /**
+     * Authentication protection middleware.
+     * @type {Function}
+     */
+    auth: Auth.protect(),
+    /**
+     * Web authentication protection middleware (redirects to home if fails).
+     * @type {Function}
+     */
+    webAuth: Auth.protect({ redirect: "/" }),
+    /**
+     * Logging middleware (can be extended).
+     */
+    logger: (req, res, next) => {
+        next();
+    }
+};
+export default Middleware;

package/core/router.js ADDED Viewed

@@ -0,0 +1,148 @@
+import express from "express";
+import Config from "./config.js";
+import SEO from "./seo.js";
+const props = Config.props();
+/**
+ * Router wrapper class for handling Express routing logic.
+ * When created with { seo: true }, all GET routes registered on this router
+ * are automatically included in the generated sitemap.xml and robots.txt.
+ */
+class Router {
+  /**
+   * Creates a new Router instance.
+   * @param {string} [path="/"] - The base path for this router.
+   * @param {Object} [options={}] - Router configuration options.
+   * @param {boolean} [options.seo=false] - When true, GET routes on this router are included in sitemap/robots.txt.
+   * @param {string[]} [options.languages=[]] - Language prefixes for SEO route generation (e.g., ["en", "es"]).
+   * @example
+   * const router = new Router("/", { seo: true, languages: ["en", "es"] });
+   * router.get("/", (req, res) => {
+   *     Template.render(res, "index", { metaTags: { titleMeta: "Home" } });
+   * });
+   */
+  constructor(path = "/", options = {}) {
+    this.router = express.Router();
+    this.path = path;
+    this._seo = options.seo ?? false;
+    this._languages = options.languages || [];
+  }
+  /**
+   * Registers a middleware on this router.
+   * @param {...Function} middleware - Middleware functions.
+   * @example
+   * router.use(Auth.protect());
+   * router.use(App.helmet());
+   */
+  use(...middleware) {
+    this.router.use(...middleware);
+  }
+  /**
+   * Registers a GET route handler.
+   * If this router was created with { seo: true }, the route path is automatically
+   * registered for sitemap.xml and robots.txt generation.
+   * @param {string} path - The relative path for the GET route.
+   * @param {...Function} callback - One or more handler functions (middlewares and controller).
+   * @example
+   * router.get("/about", (req, res) => {
+   *     Template.render(res, "about", {
+   *         metaTags: { titleMeta: "About Us" }
+   *     });
+   * });
+   */
+  get(path, ...callback) {
+    if (path === "/*" || path === "*") {
+      path = /.*/;
+    }
+    if (this._seo && typeof path === "string") {
+      const fullPath = this.path === "/" ? path : `${this.path}${path}`;
+      const normalizedPath = fullPath === "//" ? "/" : fullPath.replace(/\/+/g, "/");
+      SEO.addRoute(normalizedPath, this._languages);
+    }
+    this.router.get(path, callback);
+  }
+  /**
+   * Registers a POST route handler.
+   * @param {string} path - The relative path for the POST route.
+   * @param {...Function} callback - One or more handler functions (middlewares and controller).
+   * @example
+   * router.post("/users", (req, res) => {
+   *     res.json({ message: "User created successfully" })
+   * })
+   */
+  post(path, ...callback) {
+    if (path === "/*" || path === "*") {
+      path = /.*/;
+    }
+    this.router.post(path, callback);
+  }
+  /**
+   * Registers a PUT route handler.
+   * @param {string} path - The relative path for the PUT route.
+   * @param {...Function} callback - One or more handler functions (middlewares and controller).
+   * @example
+   * router.put("/users/:id", (req, res) => {
+   *     res.json({ message: "User updated successfully" })
+   * })
+   */
+  put(path, ...callback) {
+    this.router.put(path, callback);
+  }
+  /**
+   * Registers a DELETE route handler.
+   * @param {string} path - The relative path for the DELETE route.
+   * @param {...Function} callback - One or more handler functions (middlewares and controller).
+   * @example
+   * router.delete("/users/:id", (req, res) => {
+   *     res.json({ message: "User deleted successfully" })
+   * })
+   */
+  delete(path, ...callback) {
+    this.router.delete(path, callback);
+  }
+  /**
+   * Registers a PATCH route handler.
+   * @param {string} path - The relative path for the PATCH route.
+   * @param {...Function} callback - One or more handler functions (middlewares and controller).
+   * @example
+   * router.patch("/users/:id", (req, res) => {
+   *     res.json({ message: "User patched successfully" })
+   * })
+   */
+  patch(path, ...callback) {
+    this.router.patch(path, callback);
+  }
+  /**
+   * Registers an OPTIONS route handler.
+   * @param {string} path - The relative path for the OPTIONS route.
+   * @param {...Function} callback - One or more handler functions (middlewares and controller).
+   */
+  options(path, ...callback) {
+    this.router.options(path, callback);
+  }
+  /**
+   * Returns the underlying Express router instance.
+   * @returns {import('express').Router}
+   */
+  getRouter() {
+    return this.router;
+  }
+  /**
+   * Returns the base path associated with this router.
+   * @returns {string}
+   */
+  getPath() {
+    return this.path;
+  }
+}
+export default Router;

package/core/seo.js ADDED Viewed

@@ -0,0 +1,113 @@
+import Config from "./config.js";
+const props = Config.props();
+/** @type {Array<{path: string, languages: string[]}>} */
+const _seoRoutes = [];
+/**
+ * SEO utility class for generating sitemaps and robots.txt files.
+ * Routes are automatically registered from Router instances created with { seo: true }.
+ */
+class SEO {
+  /**
+   * Registers a route path for sitemap generation.
+   * Called internally by Router when seo option is enabled.
+   * @static
+   * @param {string} routePath - The route path to register.
+   * @param {string[]} [languages=[]] - Language prefixes for this route.
+   */
+  static addRoute(routePath, languages = []) {
+    const exists = _seoRoutes.find(r => r.path === routePath);
+    if (!exists) {
+      _seoRoutes.push({ path: routePath, languages });
+    }
+  }
+  /**
+   * Returns all registered SEO routes.
+   * @static
+   * @returns {Array<{path: string, languages: string[]}>}
+   */
+  static getRoutes() {
+    return _seoRoutes;
+  }
+  /**
+   * Clears all registered SEO routes.
+   * @static
+   */
+  static clearRoutes() {
+    _seoRoutes.length = 0;
+  }
+  /**
+   * Generates a sitemap.xml string from all registered SEO routes.
+   * @static
+   * @returns {string} The generated XML sitemap.
+   */
+  static generateSitemap() {
+    const host = (props.appUrl || `${props.host}:${props.port}`).replace(/\/$/, "");
+    const date = new Date().toISOString().split("T")[0];
+    let xml = '<?xml version="1.0" encoding="UTF-8"?>';
+    xml +=
+      '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">';
+    _seoRoutes.forEach((route) => {
+      xml += `
+        <url>
+            <loc>${host}${route.path}</loc>
+            <lastmod>${date}</lastmod>
+            <priority>${route.path === "/" ? "1.0" : "0.8"}</priority>
+        </url>`;
+      if (route.languages && route.languages.length > 0) {
+        route.languages.forEach((lang) => {
+          const langPath = `/${lang}${route.path === "/" ? "" : route.path}`;
+          xml += `
+        <url>
+            <loc>${host}${langPath}</loc>
+            <lastmod>${date}</lastmod>
+            <priority>1</priority>
+        </url>`;
+        });
+      }
+    });
+    xml += "\n</urlset>";
+    return xml.trim();
+  }
+  /**
+   * Generates a robots.txt string.
+   * @static
+   * @returns {string} The generated robots.txt content.
+   */
+  static generateRobots() {
+    const host = (props.appUrl || "http://localhost").replace(/\/$/, "");
+    return `User-agent: *
+Allow: /
+Sitemap: ${host}/sitemap.xml
+`;
+  }
+  /**
+   * Registers /sitemap.xml and /robots.txt routes on the given Express router.
+   * @static
+   * @param {import('express').Router} expressRouter - The Express router instance.
+   */
+  static registerEndpoints(expressRouter) {
+    expressRouter.get("/sitemap.xml", (req, res) => {
+      res.header("Content-Type", "application/xml");
+      res.send(SEO.generateSitemap());
+    });
+    expressRouter.get("/robots.txt", (req, res) => {
+      res.header("Content-Type", "text/plain");
+      res.send(SEO.generateRobots());
+    });
+  }
+}
+export default SEO;

package/core/swagger.js ADDED Viewed

@@ -0,0 +1,40 @@
+import { execSync } from "node:child_process";
+class SwaggerCli {
+    install() {
+        const dependencies = this.checkDependencies();
+        if (dependencies.missingDependencies.length > 0) {
+            console.log("Installing dependencies...");
+            console.log(`Installing swagger-jsdoc...`);
+            execSync(`npm install swagger-jsdoc@6.2.8`, { stdio: "inherit" });
+            console.log(`Installing swagger-ui-express...`);
+            execSync(`npm install swagger-ui-express@5.0.1`, { stdio: "inherit" });
+        }
+    }
+    checkDependencies() {
+        const dependencies = [
+            "swagger-jsdoc",
+            "swagger-ui-express"
+        ];
+        const missingDependencies = [];
+        dependencies.forEach(dependency => {
+            if (!this.checkDependency(dependency)) {
+                missingDependencies.push(dependency);
+            }
+        });
+        return {
+            missingDependencies
+        };
+    }
+    checkDependency(dependency) {
+        try {
+            require.resolve(dependency);
+            return true;
+        } catch (error) {
+            return false;
+        }
+    }
+}
+const swaggerExecutor = new SwaggerCli();
+swaggerExecutor.install();