@seip/blue-bird 0.6.0

package/core/cache.js

@@ -0,0 +1,72 @@
+const CACHE = {};
+
+setInterval(() => {
+    const now = Date.now();
+    for (const key in CACHE) {
+        if (CACHE[key].expiry <= now) {
+            delete CACHE[key];
+        }
+    }
+}, 300000).unref();
+/**
+ * Simple in-memory Cache class to provide middleware for Express routes.
+ * Caches JSON responses based on the request URL.
+ */
+class Cache {
+  /**
+   * Middleware to cache responses.
+   * @param {number} [seconds=60] - Number of seconds to cache the response.
+   * @returns {Function} Express middleware function.
+   * @example
+   * router.get("/stats", Cache.middleware(120), (req, res) => {
+   *     res.json({ ok: true });
+   * });
+   */
+  static middleware(seconds = 60) {
+    return (req, res, next) => {
+      const key = req.originalUrl;
+
+      if (CACHE[key] && CACHE[key].expiry > Date.now()) {
+        const cached = CACHE[key];
+        if (cached.type === "json") {
+          return res.json(cached.data);
+        } else {
+          res.type("text/html");
+          return res.send(cached.data);
+        }
+      }
+
+      const originalJson = res.json.bind(res);
+      const originalSend = res.send.bind(res);
+      let cachedInRequest = false;
+
+      res.json = (body) => {
+        if (!cachedInRequest) {
+          CACHE[key] = {
+            type: "json",
+            data: body,
+            expiry: Date.now() + seconds * 1000,
+          };
+          cachedInRequest = true;
+        }
+        return originalJson(body);
+      };
+
+      res.send = (body) => {
+        if (!cachedInRequest && typeof body === "string") {
+          CACHE[key] = {
+            type: "html",
+            data: body,
+            expiry: Date.now() + seconds * 1000,
+          };
+          cachedInRequest = true;
+        }
+        return originalSend(body);
+      };
+
+      next();
+    };
+  }
+}
+
+export default Cache;

package/core/cli/docker.js

@@ -0,0 +1,319 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import chalk from "chalk";
+
+/**
+ * Parses the .env file to retrieve project configurations.
+ * @returns {Object} Local environment variables dictionary.
+ */
+function getEnvVars() {
+  const env = { ...process.env };
+  const envPath = path.join(process.cwd(), ".env");
+  if (fs.existsSync(envPath)) {
+    const content = fs.readFileSync(envPath, "utf-8");
+    content.split(/\r?\n/).forEach(line => {
+      line = line.trim();
+      if (line && !line.startsWith("#") && line.includes("=")) {
+        const idx = line.indexOf("=");
+        const key = line.substring(0, idx).trim();
+        const value = line.substring(idx + 1).trim().replace(/^['"]|['"]$/g, "");
+        env[key] = value;
+      }
+    });
+  }
+  return env;
+}
+
+/**
+ * Spawns a child process and inherits standard IO for interactive terminal sessions.
+ * @param {string} command - The binary to execute.
+ * @param {string[]} args - Argument list.
+ * @returns {Promise<number>} Exit code of the process.
+ */
+function runCmd(command, args) {
+  return new Promise((resolve) => {
+    const proc = spawn(command, args, { stdio: "inherit", env: process.env });
+    proc.on("close", (code) => {
+      resolve(code || 0);
+    });
+  });
+}
+
+/**
+ * Confirms that a docker-compose.yml file is present in the workspace directory.
+ */
+function checkComposeFile() {
+  if (!fs.existsSync("docker-compose.yml")) {
+    console.error(chalk.red("Error: docker-compose.yml not found in the current directory."));
+    process.exit(1);
+  }
+}
+
+/**
+ * Handles the 'start' CLI command.
+ * @param {string} service - Service to boot up.
+ */
+async function startCommand(service) {
+  checkComposeFile();
+
+  if (service === "mysql" || service === "--mysql" || service === "dev") {
+    console.log(chalk.cyan("Starting MySQL container (dev mode)..."));
+    const code = await runCmd("docker", ["compose", "up", "-d", "mysql"]);
+    if (code === 0) {
+      console.log(chalk.green("MySQL started. Run your app locally with: npm run dev"));
+      console.log(chalk.blue("To also run the app in Docker (production), use: npx blue-bird docker start prod"));
+    } else {
+      console.error(chalk.red("Error starting MySQL."));
+      process.exit(1);
+    }
+  } else if (service === "prod" || service === "app" || service === "--app" || !service) {
+    console.log(chalk.cyan("Starting production stack (MySQL + Node.js app)..."));
+    const code = await runCmd("docker", ["compose", "--profile", "prod", "up", "-d"]);
+    if (code === 0) {
+      console.log(chalk.green("Production stack started."));
+      console.log(chalk.blue("View logs with: npx blue-bird docker logs"));
+    } else {
+      console.error(chalk.red("Error starting production stack."));
+      process.exit(1);
+    }
+  } else {
+    console.error(chalk.red(`Unknown service '${service}'. Use: mysql (or --mysql), prod (or --app), or no arguments for both.`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Handles the 'stop' CLI command.
+ * @param {string} service - Service to stop.
+ */
+async function stopCommand(service) {
+  checkComposeFile();
+
+  if (!service || service === "all") {
+    console.log(chalk.cyan("Stopping all Blue Bird containers..."));
+    await runCmd("docker", ["compose", "--profile", "prod", "down"]);
+    console.log(chalk.green("All containers stopped."));
+  } else if (service === "mysql" || service === "--mysql") {
+    console.log(chalk.cyan("Stopping MySQL..."));
+    await runCmd("docker", ["compose", "stop", "mysql"]);
+    await runCmd("docker", ["compose", "rm", "-f", "mysql"]);
+    console.log(chalk.green("MySQL stopped."));
+  } else if (service === "app" || service === "--app") {
+    console.log(chalk.cyan("Stopping Node.js app container..."));
+    await runCmd("docker", ["compose", "--profile", "prod", "stop", "app"]);
+    await runCmd("docker", ["compose", "--profile", "prod", "rm", "-f", "app"]);
+    console.log(chalk.green("App container stopped."));
+  } else {
+    console.error(chalk.red(`Unknown service '${service}'. Use: all (default), mysql, app.`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Handles the 'build' CLI command.
+ * @param {string[]} options - Build configuration options.
+ */
+async function buildCommand(options = []) {
+  checkComposeFile();
+  console.log(chalk.cyan("Building Blue Bird app Docker image..."));
+  const cmdArgs = ["compose", "--profile", "prod", "build"];
+  if (options.includes("--no-cache") || options.includes("-n")) {
+    cmdArgs.push("--no-cache");
+  }
+  cmdArgs.push("app");
+
+  const code = await runCmd("docker", cmdArgs);
+  if (code === 0) {
+    console.log(chalk.green("Image built successfully. Start with: npx blue-bird docker start prod"));
+  } else {
+    console.error(chalk.red("Build error."));
+    process.exit(1);
+  }
+}
+
+/**
+ * Handles the 'ps' CLI command.
+ */
+async function psCommand() {
+  checkComposeFile();
+  console.log(chalk.cyan("Active Blue Bird Containers:"));
+  await runCmd("docker", ["compose", "--profile", "prod", "ps"]);
+}
+
+/**
+ * Handles the 'logs' CLI command.
+ * @param {string} service - Service to pull logs from.
+ * @param {string} followOpt - Flag for active log tailing.
+ */
+async function logsCommand(service, followOpt) {
+  checkComposeFile();
+  const follow = followOpt !== "--no-follow";
+  const targetService = service === "mysql" ? "mysql" : "app";
+
+  const cmdArgs = ["compose"];
+  if (targetService === "app") {
+    cmdArgs.push("--profile", "prod");
+  }
+  cmdArgs.push("logs", "--tail=100");
+  if (follow) {
+    cmdArgs.push("-f");
+  }
+  cmdArgs.push(targetService);
+
+  await runCmd("docker", cmdArgs);
+}
+
+/**
+ * Handles interactive shell connections into the MySQL container.
+ * @param {string} userOpt - DB username.
+ * @param {string} passOpt - DB password.
+ * @param {string} dbOpt - DB database name.
+ * @param {boolean} rootOpt - Flag for overriding database credentials to connect as root.
+ */
+async function mysqlCommand(userOpt, passOpt, dbOpt, rootOpt) {
+  checkComposeFile();
+  const env = getEnvVars();
+
+  let dbUser = userOpt;
+  let dbPass = passOpt;
+  let dbName = dbOpt;
+
+  if (rootOpt) {
+    dbUser = "root";
+    dbPass = env.DB_PASSWORD || "root";
+  } else {
+    dbUser = dbUser || env.DB_USER || "root";
+    dbPass = dbPass || env.DB_PASSWORD || "root";
+  }
+  dbName = dbName || env.DB_NAME || "blue_bird";
+
+  const cmdArgs = ["compose", "exec", "mysql", "mysql", `-u${dbUser}`];
+  if (dbPass) {
+    cmdArgs.push(`-p${dbPass}`);
+  }
+  if (dbName) {
+    cmdArgs.push(dbName);
+  }
+
+  const targetDb = dbName ? ` (database: {dbName})` : "";
+  console.log(chalk.cyan(`Connecting to MySQL shell in container as '${dbUser}'${targetDb}...`));
+
+  const code = await runCmd("docker", cmdArgs);
+  if (code !== 0) {
+    console.error(chalk.yellow("Make sure the MySQL container is running: npx blue-bird docker start mysql"));
+    process.exit(1);
+  }
+}
+
+/**
+ * Handles cleaning up and pruning unused Docker resources.
+ * @param {boolean} forceOpt - Force cleaning without user confirmation.
+ * @param {boolean} allOpt - Clean all unused resources.
+ */
+async function pruneCommand(forceOpt, allOpt) {
+  if (!forceOpt) {
+    console.log(chalk.yellow("Clean unused volumes, dangling images, and BuildKit cache? (Press enter to confirm, Ctrl+C to cancel)"));
+    await new Promise((resolve) => process.stdin.once("data", resolve));
+  }
+
+  console.log(chalk.cyan("1/3 Cleaning orphaned Docker volumes..."));
+  await runCmd("docker", ["volume", "prune", "-f"]);
+
+  console.log(chalk.cyan("2/3 Cleaning unused Docker images..."));
+  const imgArgs = ["image", "prune"];
+  if (allOpt) {
+    imgArgs.push("-a");
+  }
+  imgArgs.push("-f");
+  await runCmd("docker", imgArgs);
+
+  console.log(chalk.cyan("3/3 Cleaning BuildKit build cache..."));
+  await runCmd("docker", ["builder", "prune", "-a", "-f"]);
+
+  console.log(chalk.green("\nDocker cleanup completed successfully! Current disk usage:"));
+  await runCmd("docker", ["system", "df"]);
+}
+
+/**
+ * Entry point for Blue Bird CLI Docker subcommands.
+ */
+async function main() {
+  const env = getEnvVars();
+  let projectName = env.BLUEBIRD_PROJECT_NAME;
+  if (!projectName && env.TITLE) {
+    projectName = env.TITLE.toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/-+/g, "-");
+  }
+  if (!projectName) {
+    const pkgPath = path.join(process.cwd(), "package.json");
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        if (pkg.name) {
+          projectName = pkg.name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/-+/g, "-");
+        }
+      } catch {}
+    }
+  }
+  if (!projectName) {
+    projectName = "bluebird";
+  }
+  process.env.BLUEBIRD_PROJECT_NAME = projectName;
+  process.env.TITLE = projectName;
+
+  const args = process.argv.slice(3);
+  const command = args[0];
+
+  if (!command) {
+    await psCommand();
+    return;
+  }
+
+  switch (command) {
+    case "start":
+      await startCommand(args[1]);
+      break;
+    case "stop":
+      await stopCommand(args[1]);
+      break;
+    case "build":
+      await buildCommand(args.slice(1));
+      break;
+    case "ps":
+    case "status":
+      await psCommand();
+      break;
+    case "logs":
+      await logsCommand(args[1], args[2]);
+      break;
+    case "mysql":
+    case "db": {
+      let user, password, db, root = false;
+      for (let i = 1; i < args.length; i++) {
+        if (args[i] === "-u" || args[i] === "--user") user = args[++i];
+        else if (args[i] === "-p" || args[i] === "--password") password = args[++i];
+        else if (args[i] === "-d" || args[i] === "--db") db = args[++i];
+        else if (args[i] === "--root") root = true;
+      }
+      await mysqlCommand(user, password, db, root);
+      break;
+    }
+    case "df":
+    case "disk":
+      console.log(chalk.cyan("📊 Docker Disk Usage:"));
+      await runCmd("docker", ["system", "df"]);
+      break;
+    case "prune":
+    case "clean": {
+      const force = args.includes("-f") || args.includes("--force");
+      const all = args.includes("-a") || args.includes("--all");
+      await pruneCommand(force, all);
+      break;
+    }
+    default:
+      console.log(chalk.yellow(`Unknown docker command: ${command}`));
+      console.log("Available commands: start, stop, build, ps, logs, mysql/db, df/disk, prune/clean");
+  }
+}
+
+main();

package/core/cli/init.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+
+/**
+ * Initializes a new Blue Bird project by copying the base structure.
+ */
+class ProjectInit {
+    constructor() {
+        this.appDir = process.cwd();
+        this.sourceDir = path.resolve(import.meta.dirname, "../../");
+    }
+
+    /**
+     * Runs the project initialization process.
+     */
+    async run() {
+        console.log(chalk.cyan("Starting Blue Bird project initialization..."));
+
+        const itemsToCopy = [
+            "backend",
+            "frontend",
+            "docker",
+            "docker-compose.yml",
+            ".env_example",
+            "AGENTS.md"
+        ];
+
+        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 dev"));
+
+        } catch (error) {
+            console.error(chalk.red("Error during initialization:"), error.message);
+        }
+    }
+
+    /**
+     * Updates the user's package.json with Blue Bird scripts.
+     */
+    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",
+                "init": "blue-bird",
+                "route": "blue-bird route",
+                "swagger-install": "blue-bird swagger-install",
+                "docker": "blue-bird docker"
+            };
+
+            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."));
+            }
+        }
+    }
+
+    /**
+     * Copies a file or directory recursively.
+     * @param {string} src - Source path.
+     * @param {string} dest - Destination path.
+     */
+    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 === "route") import("./route.js");
+else if (command === "swagger-install") import("./swagger.js");
+else if (command === "docker") import("./docker.js");
+else initializer.run();

package/core/cli/route.js

@@ -0,0 +1,43 @@
+import path from 'path';
+import fs from 'fs';
+import Config from "../config.js";
+
+const __dirname = Config.dirname();
+
+class RouteCLI {
+  /**
+   * Create route 
+   */
+    create() {
+        let nameRoute = process.argv[2];
+        if (!nameRoute) {
+            console.log("Please provide a route name. Usage: npm run route <route-name>");
+            return;
+        }
+        nameRoute =nameRoute.charAt(0).toUpperCase() + nameRoute.slice(1);
+        const folder= path.join(__dirname, 'backend/routes');
+        if (!fs.existsSync(folder)){
+            fs.mkdirSync(folder, { recursive: true });
+        }
+        const filePath = path.join(folder, `${nameRoute}.js`);
+        if (fs.existsSync(filePath)) {
+            console.log(`Route ${nameRoute} already exists.`);
+            return;
+        }
+        const content =`import Router from "@seip/blue-bird/core/router.js" 
+
+const router${nameRoute} = new Router("/${nameRoute.toLowerCase()}");
+
+router${nameRoute}.get("/", (req, res) => {
+    res.json({ message: "Hello from ${nameRoute} route!" });
+});
+
+export default router${nameRoute};
+        `;
+        fs.writeFileSync(filePath, content);
+        console.log(`Route ${nameRoute} created successfully at ${filePath}`);
+    }
+}
+
+const routeCLI = new RouteCLI();
+routeCLI.create()

package/core/cli/swagger.js

@@ -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();

package/core/config.js

@@ -0,0 +1,52 @@
+import path from "path";
+
+let _cachedProps = null;
+
+/**
+ * Configuration class to manage application-wide settings and environment variables.
+ */
+class Config {
+  /**
+   * Returns the base directory of the application.
+   * @returns {string} The current working directory.
+   */
+  static dirname() {
+    return process.cwd();
+  }
+
+  /**
+   * Retrieves application properties from environment variables or default values.
+   * Results are cached after first call for performance.
+   * @returns {{debug: boolean, descriptionMeta: string, keywordsMeta: string, titleMeta: string, authorMeta: string, description: string, title: string, version: string, langMeta: string, host: string, appUrl: string, port: number, static: {path: string, options: Object}}} The configuration properties object.
+   * @example
+   * const props = Config.props();
+   * console.log(props);
+   */
+  static props() {
+    if (_cachedProps) return _cachedProps;
+
+    const portRaw = parseInt(process.env.PORT);
+
+    _cachedProps = {
+      debug: process.env.DEBUG === "true",
+      descriptionMeta: process.env.DESCRIPTION_META || "",
+      keywordsMeta: process.env.KEYWORDS_META || "",
+      titleMeta: process.env.TITLE_META || "",
+      authorMeta: process.env.AUTHOR_META || "",
+      description: process.env.DESCRIPTION || "",
+      title: process.env.TITLE || "",
+      version: process.env.VERSION || "1.0.0",
+      langMeta: process.env.LANGMETA || "en",
+      host: process.env.HOST || "http://localhost",
+      appUrl: process.env.APP_URL || process.env.HOST || "http://localhost",
+      port: Number.isNaN(portRaw) ? 3000 : portRaw,
+      jwtSecret: process.env.JWT_SECRET,
+      static: {
+        path: process.env.STATIC_PATH || "frontend/public",
+        options: {},
+      },
+    };
+    return _cachedProps;
+  }
+}
+export default Config;