@seip/blue-bird 0.6.0

package/core/validate.js

@@ -0,0 +1,380 @@
+import xss from "xss";
+
+const messages_default = {
+  es: {
+    required: (f) => `El campo ${f} es obligatorio`,
+    min: (f, n) => `El campo ${f} debe tener al menos ${n} caracteres`,
+    max: (f, n) => `El campo ${f} no puede tener más de ${n} caracteres`,
+    email: (f) => `El campo ${f} debe ser un email válido`,
+    number: (f) => `El campo ${f} debe ser numérico`,
+    alpha: (f) => `El campo ${f} solo puede contener letras`,
+    alphanumeric: (f) => `El campo ${f} solo puede contener letras y números`,
+    boolean: (f) => `El campo ${f} debe ser verdadero o falso`,
+    date: (f) => `El campo ${f} debe ser una fecha válida`,
+    url: (f) => `El campo ${f} debe ser una URL válida`,
+    in: (f, v) => `El campo ${f} debe ser uno de: ${v.join(", ")}`,
+    equals: (f, v) => `El campo ${f} debe ser igual a ${v}`,
+    password: () => `La contraseña debe tener mayúsculas, minúsculas y números`,
+    pattern: (f) => `El campo ${f} no cumple el patrón requerido`,
+  },
+  en: {
+    required: (f) => `${f} is required`,
+    min: (f, n) => `${f} must be at least ${n} characters`,
+    max: (f, n) => `${f} must be at most ${n} characters`,
+    email: (f) => `${f} must be a valid email`,
+    number: (f) => `${f} must be numeric`,
+    alpha: (f) => `${f} must contain only letters`,
+    alphanumeric: (f) => `${f} must contain only letters and numbers`,
+    boolean: (f) => `${f} must be true or false`,
+    date: (f) => `${f} must be a valid date`,
+    url: (f) => `${f} must be a valid URL`,
+    in: (f, v) => `${f} must be one of: ${v.join(", ")}`,
+    equals: (f, v) => `${f} must equal ${v}`,
+    password: () => `Password must contain uppercase, lowercase and numbers`,
+    pattern: (f) => `${f} does not match the required pattern`,
+  },
+  pt: {
+    required: (f) => `O campo ${f} é obrigatório`,
+    min: (f, n) => `O campo ${f} deve ter pelo menos ${n} caracteres`,
+    max: (f, n) => `O campo ${f} não pode ter mais de ${n} caracteres`,
+    email: (f) => `O campo ${f} deve ser um email válido`,
+    number: (f) => `O campo ${f} deve ser numérico`,
+    alpha: (f) => `O campo ${f} só pode conter letras`,
+    alphanumeric: (f) => `O campo ${f} só pode conter letras e números`,
+    boolean: (f) => `O campo ${f} deve ser verdadeiro ou falso`,
+    date: (f) => `O campo ${f} deve ser uma data válida`,
+    url: (f) => `O campo ${f} deve ser uma URL válida`,
+    in: (f, v) => `O campo ${f} deve ser um de: ${v.join(", ")}`,
+    equals: (f, v) => `O campo ${f} deve ser igual a ${v}`,
+    password: () => `A senha deve conter maiúsculas, minúsculas e números`,
+    pattern: (f) => `O campo ${f} não corresponde ao padrão exigido`,
+  },
+  br: {
+    required: (f) => `O campo ${f} é obrigatório`,
+    min: (f, n) => `O campo ${f} deve ter pelo menos ${n} caracteres`,
+    max: (f, n) => `O campo ${f} não pode ter mais de ${n} caracteres`,
+    email: (f) => `O campo ${f} deve ser um email válido`,
+    number: (f) => `O campo ${f} deve ser numérico`,
+    alpha: (f) => `O campo ${f} só pode conter letras`,
+    alphanumeric: (f) => `O campo ${f} só pode conter letras e números`,
+    boolean: (f) => `O campo ${f} deve ser verdadeiro ou falso`,
+    date: (f) => `O campo ${f} deve ser uma data válida`,
+    url: (f) => `O campo ${f} deve ser uma URL válida`,
+    in: (f, v) => `O campo ${f} deve ser um de: ${v.join(", ")}`,
+    equals: (f, v) => `O campo ${f} deve ser igual a ${v}`,
+    password: () => `A senha deve conter maiúsculas, minúsculas e números`,
+    pattern: (f) => `O campo ${f} não corresponde ao padrão exigido`,
+  },
+  fr: {
+    required: (f) => `Le champ ${f} est obligatoire`,
+    min: (f, n) => `Le champ ${f} doit contenir au moins ${n} caractères`,
+    max: (f, n) => `Le champ ${f} ne peut pas contenir plus de ${n} caractères`,
+    email: (f) => `Le champ ${f} doit être un email valide`,
+    number: (f) => `Le champ ${f} doit être numérique`,
+    alpha: (f) => `Le champ ${f} ne peut contenir que des lettres`,
+    alphanumeric: (f) =>
+      `Le champ ${f} ne peut contenir que des lettres et des chiffres`,
+    boolean: (f) => `Le champ ${f} doit être vrai ou faux`,
+    date: (f) => `Le champ ${f} doit être une date valide`,
+    url: (f) => `Le champ ${f} doit être une URL valide`,
+    in: (f, v) => `Le champ ${f} doit être l'un de: ${v.join(", ")}`,
+    equals: (f, v) => `Le champ ${f} doit être égal à ${v}`,
+    password: () =>
+      `Le mot de passe doit contenir des majuscules, des minuscules et des chiffres`,
+    pattern: (f) => `Le champ ${f} ne correspond pas au modèle requis`,
+  },
+};
+
+const validators = {
+  isEmpty: (value) => value === undefined || value === null || value === "",
+  isEmail: (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
+  isNumeric: (value) => !isNaN(value) && !isNaN(parseFloat(value)),
+  isAlpha: (value) => /^[a-zA-Z]+$/.test(value),
+  isAlphanumeric: (value) => /^[a-zA-Z0-9]+$/.test(value),
+  isBoolean: (value) =>
+    value === true || value === false || value === "true" || value === "false",
+  isISO8601: (value) => !isNaN(Date.parse(value)),
+  isURL: (value) => {
+    try {
+      new URL(value);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  isLength: (value, { min, max }) => {
+    const len = String(value).length;
+    if (min !== undefined && len < min) return false;
+    if (max !== undefined && len > max) return false;
+    return true;
+  },
+  isIn: (value, values) => values.includes(value),
+  equals: (value, comparison) => value === comparison,
+  matches: (value, pattern) => pattern.test(value),
+};
+
+/**
+ * Comprehensive Validator class for handling multi-language data validation.
+ */
+class Validator {
+  /**
+   * Initializes the Validator instance with a schema and optional language settings.
+   * @param {Object} schema - Validation rules for each field (e.g., { email: { required: true, email: true } }).
+   * @param {string} [lang_default=null] - Default language for error messages (e.g., "en", "es").
+   * @param {Object} [messages=null] - Custom message overrides for validation rules.
+   * @example
+   * const loginSchema = {
+   *     email: { required: true, email: true },
+   *     password: { required: true, min: 6 }
+   * };
+   * const loginValidator = new Validator(loginSchema, 'es');
+   */
+  constructor(schema, lang_default = null, messages = null) {
+    this.schema = schema;
+    this.lang_default = lang_default;
+    this.messages = messages ? messages : messages_default;
+  }
+
+  /**
+   * Validates the request body against the defined schema.
+   * @param {import('express').Request} req - The Express request object containing the body to validate.
+   * @returns {Promise<{success: boolean, error: boolean, errors: Array<{field: string, message: string}>, message: Array<string>, html: Array<string>}>} Validation results.
+   * @example
+   * const loginSchema = {
+   *     email: { required: true, email: true },
+   *     password: { required: true, min: 6 }
+   * };
+   * const loginValidator = new Validator(loginSchema, 'es');
+   * const result = await loginValidator.validate(req);
+   */
+  async validate(req) {
+    let lang =
+      req?.body?.lang ||
+      req?.query?.lang ||
+      req?.params?.lang ||
+      req?.cookies?.lang ||
+      req?.headers["accept-language"]?.split(",")[0]?.split("-")[0] ||
+      req?.session?.lang ||
+      this.lang_default ||
+      "es";
+    const msg = this.messages[lang] || this.messages.es;
+    const errors = [];
+    const messages = [];
+    const body = req.body || {};
+
+    for (const [field, config] of Object.entries(this.schema)) {
+      let value = body[field];
+
+      if (config.xss !== false && typeof value === "string") {
+        body[field] = xss(value);
+        value = body[field];
+      }
+
+      if (config.required && validators.isEmpty(value)) {
+        messages.push(config.messages?.required || msg.required(field));
+        errors.push({
+          field: field,
+          message: config.messages?.required || msg.required(field),
+        });
+        continue;
+      }
+
+      if (!validators.isEmpty(value)) {
+        if (
+          config.min !== undefined &&
+          !validators.isLength(value, { min: config.min })
+        ) {
+          messages.push(config.messages?.min || msg.min(field, config.min));
+          errors.push({
+            field: field,
+            message: config.messages?.min || msg.min(field, config.min),
+          });
+        }
+        if (
+          config.max !== undefined &&
+          !validators.isLength(value, { max: config.max })
+        ) {
+          messages.push(config.messages?.max || msg.max(field, config.max));
+          errors.push({
+            field: field,
+            message: config.messages?.max || msg.max(field, config.max),
+          });
+        }
+        if (config.email && !validators.isEmail(value)) {
+          messages.push(config.messages?.email || msg.email(field));
+          errors.push({
+            field: field,
+            message: config.messages?.email || msg.email(field),
+          });
+        }
+        if (config.number && !validators.isNumeric(value)) {
+          messages.push(config.messages?.number || msg.number(field));
+          errors.push({
+            field: field,
+            message: config.messages?.number || msg.number(field),
+          });
+        }
+        if (config.alpha && !validators.isAlpha(value)) {
+          messages.push(config.messages?.alpha || msg.alpha(field));
+          errors.push({
+            field: field,
+            message: config.messages?.alpha || msg.alpha(field),
+          });
+        }
+        if (config.alphanumeric && !validators.isAlphanumeric(value)) {
+          messages.push(
+            config.messages?.alphanumeric || msg.alphanumeric(field),
+          );
+          errors.push({
+            field: field,
+            message: config.messages?.alphanumeric || msg.alphanumeric(field),
+          });
+        }
+        if (config.boolean && !validators.isBoolean(value)) {
+          messages.push(config.messages?.boolean || msg.boolean(field));
+          errors.push({
+            field: field,
+            message: config.messages?.boolean || msg.boolean(field),
+          });
+        }
+        if (config.date && !validators.isISO8601(value)) {
+          messages.push(config.messages?.date || msg.date(field));
+          errors.push({
+            field: field,
+            message: config.messages?.date || msg.date(field),
+          });
+        }
+        if (config.url && !validators.isURL(value)) {
+          messages.push(config.messages?.url || msg.url(field));
+          errors.push({
+            field: field,
+            message: config.messages?.url || msg.url(field),
+          });
+        }
+        if (config.in && !validators.isIn(value, config.in)) {
+          messages.push(config.messages?.in || msg.in(field, config.in));
+          errors.push({
+            field: field,
+            message: config.messages?.in || msg.in(field, config.in),
+          });
+        }
+        if (
+          config.equals !== undefined &&
+          !validators.equals(value, config.equals)
+        ) {
+          messages.push(
+            config.messages?.equals || msg.equals(field, config.equals),
+          );
+          errors.push({
+            field: field,
+            message:
+              config.messages?.equals || msg.equals(field, config.equals),
+          });
+        }
+        if (
+          config.password &&
+          !validators.matches(value, /^(?=.*[A-Z])(?=.*[a-z])(?=.*\d).{6,}$/)
+        ) {
+          messages.push(config.messages?.password || msg.password(field));
+          errors.push({
+            field: field,
+            message: config.messages?.password || msg.password(field),
+          });
+        }
+        if (config.pattern && !validators.matches(value, config.pattern)) {
+          messages.push(config.messages?.pattern || msg.pattern(field));
+          errors.push({
+            field: field,
+            message: config.messages?.pattern || msg.pattern(field),
+          });
+        }
+      }
+    }
+
+    if (errors.length > 0 || messages.length > 0) {
+      return {
+        success: false,
+        error: true,
+        errors: errors,
+        message: messages,
+      };
+    }
+
+    return { success: true, error: false, errors: [], message: [], html: [] };
+  }
+
+  /**
+   * Express middleware for automated validation of the request body.
+   * Returns a 400 Bad Request response with validation results if errors occur.
+   * @returns {Function} Express middleware function (req, res, next).
+   * @example
+   *
+   * 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' });
+   * });
+   */
+  middleware() {
+    return async (req, res, next) => {
+      const result = await this.validate(req);
+      if (!result.success) {
+        return res.status(400).json(result);
+      }
+      next();
+    };
+  }
+
+  /**
+   * Express middleware for explicitly sanitizing request data against XSS.
+   * Can be used on specific routes where HTML input is not expected.
+   * @returns {Function} Express middleware function.
+   */
+  static xssMiddleware() {
+    return (req, res, next) => {
+      if (req.body && typeof req.body === "object") {
+        Validator.mutateSanitized(req.body);
+      }
+      if (req.query && typeof req.query === "object") {
+        Validator.mutateSanitized(req.query);
+      }
+      if (req.params && typeof req.params === "object") {
+        Validator.mutateSanitized(req.params);
+      }
+      next();
+    };
+  }
+
+  static mutateSanitized(obj) {
+    for (const key in obj) {
+      if (typeof obj[key] === "string") {
+        obj[key] = xss(obj[key]);
+      } else if (typeof obj[key] === "object" && obj[key] !== null) {
+        Validator.mutateSanitized(obj[key]);
+      }
+    }
+  }
+
+  static sanitizeObject(obj) {
+    if (typeof obj === "string") return xss(obj);
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) => Validator.sanitizeObject(item));
+    }
+
+    if (typeof obj === "object" && obj !== null) {
+      const sanitized = {};
+      for (const key in obj) {
+        sanitized[key] = Validator.sanitizeObject(obj[key]);
+      }
+      return sanitized;
+    }
+
+    return obj;
+  }
+}
+
+export default Validator;

package/docker/Dockerfile

@@ -0,0 +1,25 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Blue Bird Framework — Production Dockerfile
+# Node.js 24-alpine for lightweight, production-ready environment
+# ─────────────────────────────────────────────────────────────────────────────
+FROM node:24.7.0-alpine3.21
+
+# Set environment variables
+ENV NODE_ENV=production
+
+WORKDIR /app
+
+# Copy package files first (layer cache optimization)
+COPY package*.json ./
+
+# Install production dependencies
+RUN npm ci --omit=dev
+
+# Copy project source
+COPY . .
+
+# Expose the application port
+EXPOSE 3000
+
+# Start the application
+CMD ["npm", "start"]

package/docker-compose.yml

@@ -0,0 +1,70 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Blue Bird Framework — Docker Compose
+#
+# DEVELOPMENT / DATABASE ONLY:
+#   npx blue-bird docker start mysql   → Only MySQL container
+#
+# PRODUCTION:
+#   npx blue-bird docker start prod    → MySQL + Node.js app container
+#   npx blue-bird docker stop          → Stop all containers
+#
+# Multi-project VPS support:
+#   Each project uses TITLE (or sanitised TITLE) to name
+#   containers and networks uniquely.
+# ─────────────────────────────────────────────────────────────────────────────
+
+services:
+  # ── Node.js App (Production only) ─────────────────────────────────────────
+  app:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile
+    container_name: ${TITLE:-bluebird}-app
+    restart: unless-stopped
+    ports:
+      - "${PORT:-3000}:3000"
+    volumes:
+      - .:/app
+      - /app/node_modules
+    env_file:
+      - .env
+    environment:
+      - NODE_ENV=production
+      - DEBUG=false
+      - DATABASE_URL=mysql://root:${DB_PASSWORD:-root}@mysql:3306/${DB_NAME:-blue_bird}
+    depends_on:
+      mysql:
+        condition: service_healthy
+    networks:
+      - bluebird_net
+    profiles:
+      - prod
+
+  # ── MySQL Database ─────────────────────────────────────────────────────────
+  mysql:
+    image: mysql:8.0
+    container_name: ${TITLE:-bluebird}-mysql
+    restart: unless-stopped
+    environment:
+      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD:-root}
+      MYSQL_DATABASE: ${DB_NAME:-blue_bird}
+    ports:
+      - "${DB_PORT:-3306}:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${DB_PASSWORD:-root}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    networks:
+      - bluebird_net
+
+volumes:
+  mysql_data:
+
+networks:
+  bluebird_net:
+    name: ${TITLE:-bluebird}_network
+    driver: bridge

package/frontend/public/js/spa.js

@@ -0,0 +1,183 @@
+/**
+ * blueBird-SPA Navigation Engine
+ * Provides Single Page Application behavior for Twig and React.
+ */
+(function () {
+    const CONTENT_ID = 'blueBird-spa-content';
+    const TIMEOUT_MS = 5000;
+
+    /**
+     * Navigates to a new page using SPA logic.
+     * 
+     * @param {string} url - The target URL
+     * @param {boolean} [push=true] - Whether to push to browser history
+     * @returns {Promise<void>}
+     */
+    async function navigate(url, push = true) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+        try {
+            let requestUrl = url;
+
+            const separator = requestUrl.includes('?') ? '&' : '?';
+            const response = await fetch(`${requestUrl}${separator}source=frontend`, {
+                signal: controller.signal,
+                headers: {
+                    'X-blueBird-SPA': 'true',
+                    'Accept': 'application/json'
+                }
+            });
+
+            clearTimeout(timeoutId);
+
+            if (response.status === 401 || response.status === 403) {
+                window.location.href = url;
+                return;
+            }
+
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+
+            const data = await response.json();
+
+            if (data.meta) {
+                document.title = data.meta.title || document.title;
+                ['description', 'keywords', 'author'].forEach(name => {
+                    const el = document.querySelector(`meta[name="${name}"]`);
+                    if (el && data.meta[name]) el.setAttribute("content", data.meta[name]);
+                });
+            }
+
+            if (data.css && Array.isArray(data.css)) {
+                data.css.forEach(href => {
+                    if (!document.head.querySelector(`link[href="${href}"]`)) {
+                        const link = document.createElement('link');
+                        link.rel = 'stylesheet';
+                        link.href = href;
+                        document.head.appendChild(link);
+                    }
+                });
+            }
+
+            const container = document.getElementById(CONTENT_ID);
+            if (container) {
+                container.innerHTML = data.body;
+
+                const partialScripts = container.querySelectorAll('script');
+                const partialLinks = container.querySelectorAll('link[rel="stylesheet"]');
+
+                partialLinks.forEach(link => {
+                    if (!document.head.querySelector(`link[href="${link.href}"]`)) {
+                        document.head.appendChild(link.cloneNode(true));
+                    }
+                    link.remove();
+                });
+
+                partialScripts.forEach(oldScript => {
+                    const newScript = document.createElement('script');
+                    Array.from(oldScript.attributes).forEach(attr => newScript.setAttribute(attr.name, attr.value));
+                    newScript.textContent = oldScript.textContent;
+
+                    if (oldScript.src) {
+                        const existing = document.head.querySelector(`script[src="${oldScript.src}"]`);
+                        if (existing && (oldScript.hasAttribute('data-spa-reload') || oldScript.src.includes('source=frontend'))) {
+                            existing.remove();
+                        }
+                        if (!document.head.querySelector(`script[src="${oldScript.src}"]`)) {
+                            document.head.appendChild(newScript);
+                        }
+                    } else {
+                        const content = oldScript.textContent.trim();
+                        if (content) {
+                            Array.from(document.head.querySelectorAll('script:not([src])'))
+                                .filter(s => s.textContent.trim() === content)
+                                .forEach(s => s.remove());
+                            document.head.appendChild(newScript);
+                        }
+                    }
+                    oldScript.remove();
+                });
+
+                if (!url.includes('set-lang=true')) {
+                    const hash = url.split('#')[1];
+                    if (hash) {
+                        const element = document.getElementById(hash);
+                        if (element) {
+                            element.scrollIntoView({ behavior: 'smooth' });
+                        }
+                    } else {
+                        window.scrollTo({ top: 0, behavior: 'smooth' });
+                    }
+                }
+            }
+
+            if (push) {
+                let finalUrl = response.url || url;
+                try {
+                    const urlObj = new URL(finalUrl);
+                    const hasSetLang = urlObj.searchParams.has('set-lang');
+                    urlObj.searchParams.delete('source');
+                    urlObj.searchParams.delete('set-lang');
+                    if (hasSetLang) {
+                        urlObj.searchParams.delete('lang');
+                    }
+                    finalUrl = urlObj.pathname + urlObj.search + urlObj.hash;
+                } catch (e) {
+                    finalUrl = finalUrl.replace(/[?&]source=frontend/, '').replace(/[?&]set-lang=true/, '');
+                }
+                window.history.pushState({ url: finalUrl }, data.meta?.title || '', finalUrl);
+            }
+
+            document.dispatchEvent(new CustomEvent('blueBird:navigation', {
+                detail: { url, data }
+            }));
+            document.dispatchEvent(new CustomEvent('blueBird:content-loaded', {
+                detail: { url, data }
+            }));
+
+        } catch (error) {
+            if (error.name === 'AbortError') {
+                console.warn('SPA Navigation timeout, redirecting...');
+            } else {
+                console.error('SPA Navigation failed:', error);
+            }
+            window.location.href = url;
+        }
+    }
+
+    window.blueBirdNav = { navigate };
+
+    function initSPA() {
+        document.addEventListener('click', (e) => {
+            const link = e.target.closest('a');
+
+            if (link &&
+                link.href &&
+                link.href.startsWith(window.location.origin) &&
+                !link.hasAttribute('download') &&
+                !link.hasAttribute('data-no-spa') &&
+                link.target !== '_blank' &&
+                !e.ctrlKey && !e.metaKey && !e.shiftKey) {
+
+                e.preventDefault();
+                navigate(link.href);
+            }
+        });
+
+        window.addEventListener('popstate', (e) => {
+            if (e.state && e.state.url) {
+                navigate(e.state.url, false);
+            } else {
+                window.location.reload();
+            }
+        });
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', initSPA);
+    } else {
+        initSPA();
+    }
+})();