webspresso 0.0.99 → 0.0.101

package/core/auth/user-agent.js

@@ -0,0 +1,161 @@
+/**
+ * Webspresso Zero-Dependency User-Agent & Device Parser
+ * Extracts browser, operating system, and device category from User-Agent header
+ * @module core/auth/user-agent
+ */
+
+'use strict';
+
+/**
+ * @typedef {Object} DeviceInfo
+ * @property {string} browser - Browser name with major version (e.g. 'Chrome 128', 'Safari 17')
+ * @property {string} os - Operating system name (e.g. 'macOS 14', 'Windows 11', 'iOS 17')
+ * @property {'desktop'|'mobile'|'tablet'|'bot'|'unknown'} device - Device category
+ * @property {boolean} isMobile
+ * @property {boolean} isTablet
+ * @property {boolean} isDesktop
+ * @property {boolean} isBot
+ */
+
+/**
+ * Extract client IP address handling proxies
+ * @param {Object} req - Express / Node.js HTTP request
+ * @returns {string}
+ */
+function getClientIp(req) {
+  if (!req) return '127.0.0.1';
+
+  const forwarded = req.headers?.['x-forwarded-for'];
+  if (forwarded) {
+    const ips = typeof forwarded === 'string' ? forwarded.split(',') : forwarded;
+    const first = Array.isArray(ips) ? ips[0] : ips;
+    if (first) return first.trim();
+  }
+
+  return req.headers?.['x-real-ip'] ||
+    req.ip ||
+    req.connection?.remoteAddress ||
+    req.socket?.remoteAddress ||
+    '127.0.0.1';
+}
+
+/**
+ * Parse raw User-Agent header string into structured device info
+ * Zero external dependencies — pure regex extraction
+ * 
+ * @param {string} [userAgent='']
+ * @returns {DeviceInfo}
+ */
+function parseUserAgent(userAgent = '') {
+  const ua = String(userAgent || '').trim();
+
+  if (!ua) {
+    return {
+      browser: 'Unknown',
+      os: 'Unknown',
+      device: 'unknown',
+      isMobile: false,
+      isTablet: false,
+      isDesktop: false,
+      isBot: false,
+    };
+  }
+
+  // 1. Detect Bots / Crawlers
+  const botPattern = /googlebot|bingbot|yandex|baiduspider|duckduckbot|slurp|twitterbot|facebookexternalhit|rogerbot|linkedinbot|embedly|quora link preview|showyoubot|outbrain|pinterest\/|slackbot|vkshare|w3c_validator|whatsapp|curl|wget|postman/i;
+  const isBot = botPattern.test(ua);
+
+  // 2. Detect Operating System
+  let os = 'Unknown';
+  if (/iPad/i.test(ua)) {
+    const match = ua.match(/OS ([\d_\.]+)/i);
+    os = match ? `iPadOS ${match[1].replace(/_/g, '.')}` : 'iPadOS';
+  } else if (/iPhone|iPod/i.test(ua)) {
+    const match = ua.match(/OS ([\d_\.]+)/i);
+    os = match ? `iOS ${match[1].replace(/_/g, '.')}` : 'iOS';
+  } else if (/Android/i.test(ua)) {
+    const match = ua.match(/Android (\d+(\.\d+)?)/i);
+    os = match ? `Android ${match[1]}` : 'Android';
+  } else if (/Macintosh|Mac OS X/i.test(ua)) {
+    const match = ua.match(/Mac OS X ([\d_\.]+)/i);
+    if (match) {
+      const ver = match[1].replace(/_/g, '.');
+      os = `macOS ${ver}`;
+    } else {
+      os = 'macOS';
+    }
+  } else if (/Windows/i.test(ua)) {
+    if (/Windows NT 10\.0/i.test(ua)) os = 'Windows 10/11';
+    else if (/Windows NT 6\.3/i.test(ua)) os = 'Windows 8.1';
+    else if (/Windows NT 6\.2/i.test(ua)) os = 'Windows 8';
+    else if (/Windows NT 6\.1/i.test(ua)) os = 'Windows 7';
+    else os = 'Windows';
+  } else if (/CrOS/i.test(ua)) {
+    os = 'ChromeOS';
+  } else if (/Linux/i.test(ua)) {
+    if (/Ubuntu/i.test(ua)) os = 'Ubuntu Linux';
+    else if (/Fedora/i.test(ua)) os = 'Fedora Linux';
+    else os = 'Linux';
+  }
+
+  // 3. Detect Browser
+  let browser = 'Unknown';
+  if (/Edg(e|A|iOS)?\/(\d+)/i.test(ua)) {
+    const match = ua.match(/Edg(e|A|iOS)?\/(\d+)/i);
+    browser = `Edge ${match ? match[2] : ''}`.trim();
+  } else if (/OPR\/(\d+)/i.test(ua)) {
+    const match = ua.match(/OPR\/(\d+)/i);
+    browser = `Opera ${match ? match[1] : ''}`.trim();
+  } else if (/SamsungBrowser\/(\d+)/i.test(ua)) {
+    const match = ua.match(/SamsungBrowser\/(\d+)/i);
+    browser = `Samsung Internet ${match ? match[1] : ''}`.trim();
+  } else if (/Brave\/(\d+)/i.test(ua)) {
+    const match = ua.match(/Brave\/(\d+)/i);
+    browser = `Brave ${match ? match[1] : ''}`.trim();
+  } else if (/Vivaldi\/(\d+)/i.test(ua)) {
+    const match = ua.match(/Vivaldi\/(\d+)/i);
+    browser = `Vivaldi ${match ? match[1] : ''}`.trim();
+  } else if (/Chrome\/(\d+)/i.test(ua) && !/Chromium/i.test(ua)) {
+    const match = ua.match(/Chrome\/(\d+)/i);
+    browser = `Chrome ${match ? match[1] : ''}`.trim();
+  } else if (/Firefox\/(\d+)/i.test(ua) || /FxiOS\/(\d+)/i.test(ua)) {
+    const match = ua.match(/(?:Firefox|FxiOS)\/(\d+)/i);
+    browser = `Firefox ${match ? match[1] : ''}`.trim();
+  } else if (/Safari/i.test(ua) && /Version\/(\d+)/i.test(ua)) {
+    const match = ua.match(/Version\/(\d+)/i);
+    browser = `Safari ${match ? match[1] : ''}`.trim();
+  } else if (/Safari/i.test(ua) && !/Chrome/i.test(ua)) {
+    browser = 'Safari';
+  } else if (/MSIE (\d+)/i.test(ua) || (/Trident/i.test(ua) && /rv:(\d+)/i.test(ua))) {
+    browser = 'Internet Explorer';
+  } else if (isBot) {
+    const botNameMatch = ua.match(/(googlebot|bingbot|duckduckbot|slurp|twitterbot|slackbot|curl|wget)/i);
+    browser = botNameMatch ? botNameMatch[1] : 'Bot';
+  }
+
+  // 4. Detect Device Category
+  const isTablet = /iPad|tablet/i.test(ua) || (/android/i.test(ua) && !/mobile/i.test(ua));
+  const isMobile = !isTablet && /mobile|iphone|ipod|android|blackberry|opera mini|windows phone/i.test(ua);
+  const isDesktop = !isTablet && !isMobile && !isBot;
+
+  let device = 'unknown';
+  if (isBot) device = 'bot';
+  else if (isTablet) device = 'tablet';
+  else if (isMobile) device = 'mobile';
+  else if (isDesktop) device = 'desktop';
+
+  return {
+    browser,
+    os,
+    device,
+    isMobile,
+    isTablet,
+    isDesktop,
+    isBot,
+  };
+}
+
+module.exports = {
+  getClientIp,
+  parseUserAgent,
+};

package/core/commands/define-command.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * Webspresso - Custom Command Definition
+ * Inspired by Django BaseCommand & AdonisJS Ace CLI
+ * @module core/commands/define-command
+ */
+
+/**
+ * Define a custom CLI management command
+ * @param {Object} definition
+ * @param {string} definition.name - Command identifier (e.g. 'users:sync' or 'send-invoices')
+ * @param {string} [definition.description] - Human-readable command description
+ * @param {Array<{flags: string, description?: string, defaultValue?: any}>} [definition.options] - CLI flags
+ * @param {Function} definition.handle - Execution function receiving ({ db, queue, services, mailer, events, logger, args, flags })
+ * @returns {Object} Validated command specification
+ */
+function defineCommand(definition) {
+  if (!definition || typeof definition !== 'object') {
+    throw new TypeError('defineCommand requires a configuration object');
+  }
+  if (!definition.name || typeof definition.name !== 'string' || !definition.name.trim()) {
+    throw new TypeError('Command definition must specify a non-empty string "name"');
+  }
+  const handleFn = definition.handle || definition.run;
+  if (typeof handleFn !== 'function') {
+    throw new TypeError(`Command "${definition.name}" must provide an executable "handle" function`);
+  }
+
+  const options = Array.isArray(definition.options)
+    ? definition.options.map((opt) => ({
+        flags: String(opt.flags || opt.name || '').trim(),
+        description: opt.description || '',
+        defaultValue: opt.defaultValue !== undefined ? opt.defaultValue : opt.default,
+      })).filter((opt) => opt.flags.length > 0)
+    : [];
+
+  return {
+    name: definition.name.trim(),
+    description: definition.description || '',
+    options,
+    handle: handleFn,
+  };
+}
+
+module.exports = {
+  defineCommand,
+};

package/core/commands/index.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/**
+ * Webspresso - Management Commands Core Module
+ * @module core/commands
+ */
+
+const { defineCommand } = require('./define-command');
+const { createCommandRegistry, findCommandFiles, deriveCommandName } = require('./registry');
+const { executeCommand } = require('./runner');
+
+module.exports = {
+  defineCommand,
+  createCommandRegistry,
+  findCommandFiles,
+  deriveCommandName,
+  executeCommand,
+};

package/core/commands/registry.js

@@ -0,0 +1,156 @@
+'use strict';
+
+/**
+ * Webspresso - Command Registry & Auto-Discovery
+ * Scans commands/ directory and registers custom management commands
+ * @module core/commands/registry
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { defineCommand } = require('./define-command');
+
+/**
+ * Recursively find command files in directory
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function findCommandFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...findCommandFiles(fullPath));
+    } else if (
+      entry.isFile() &&
+      entry.name.endsWith('.js') &&
+      !entry.name.startsWith('_') &&
+      !entry.name.endsWith('.test.js') &&
+      !entry.name.endsWith('.spec.js')
+    ) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Derive command name from relative path
+ * e.g. "users/prune.js" -> "users:prune", "send-invoices.js" -> "send-invoices"
+ * @param {string} relPath
+ * @returns {string}
+ */
+function deriveCommandName(relPath) {
+  const withoutExt = relPath.replace(/\.js$/, '');
+  const segments = withoutExt.split(/[\\/]/).filter(Boolean);
+  return segments.join(':');
+}
+
+/**
+ * Create a CommandRegistry instance
+ * @param {Object} [options]
+ * @param {string} [options.commandsDir] - Root directory for commands (default: ./commands)
+ * @param {boolean} [options.autoLoad=true] - Whether to discover files immediately
+ * @returns {Object} CommandRegistry
+ */
+function createCommandRegistry(options = {}) {
+  const commandsDir = options.commandsDir
+    ? path.resolve(process.cwd(), options.commandsDir)
+    : path.resolve(process.cwd(), 'commands');
+
+  /** @type {Map<string, Object>} */
+  const commands = new Map();
+
+  function register(cmdDef) {
+    if (!cmdDef || typeof cmdDef !== 'object') {
+      throw new TypeError('Invalid command definition object');
+    }
+    const def = typeof cmdDef.handle === 'function' && defIsNormalized(cmdDef)
+      ? cmdDef
+      : defineCommand(cmdDef);
+
+    commands.set(def.name, def);
+    return def;
+  }
+
+  function defIsNormalized(obj) {
+    return typeof obj.name === 'string' && typeof obj.handle === 'function' && Array.isArray(obj.options);
+  }
+
+  function load() {
+    commands.clear();
+    const files = findCommandFiles(commandsDir);
+
+    for (const file of files) {
+      try {
+        delete require.cache[require.resolve(file)];
+        const exported = require(file);
+        const rel = path.relative(commandsDir, file);
+        const derivedName = deriveCommandName(rel);
+
+        let cmdDef = null;
+
+        if (typeof exported === 'function') {
+          cmdDef = defineCommand({
+            name: derivedName,
+            handle: exported,
+          });
+        } else if (exported && typeof exported === 'object') {
+          // Check if exported is an ES default or CJS module
+          const target = exported.default || exported;
+          const name = target.name || derivedName;
+          const handle = target.handle || target.run;
+
+          if (typeof handle === 'function') {
+            cmdDef = defineCommand({
+              name,
+              description: target.description || '',
+              options: target.options || [],
+              handle,
+            });
+          }
+        }
+
+        if (cmdDef) {
+          commands.set(cmdDef.name, cmdDef);
+        }
+      } catch (err) {
+        console.warn(`[commands] Failed to load command from "${file}":`, err.message);
+      }
+    }
+  }
+
+  if (options.autoLoad !== false) {
+    load();
+  }
+
+  return {
+    register,
+    reload: load,
+    has(name) {
+      return commands.has(name);
+    },
+    get(name) {
+      return commands.get(name) || null;
+    },
+    list() {
+      return Array.from(commands.values());
+    },
+    names() {
+      return Array.from(commands.keys());
+    },
+    get commandsDir() {
+      return commandsDir;
+    },
+  };
+}
+
+module.exports = {
+  createCommandRegistry,
+  findCommandFiles,
+  deriveCommandName,
+};

package/core/commands/runner.js

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * Webspresso - Command Runner & Execution Engine
+ * Injects framework services, database, queue, mailer, events and manages execution lifecycle
+ * @module core/commands/runner
+ */
+
+/**
+ * Execute a command definition with dependency injection
+ * @param {Object} commandDef - Command specification returned by defineCommand
+ * @param {Object} [executionOptions]
+ * @param {Array<string>} [executionOptions.args] - Positional CLI arguments
+ * @param {Object} [executionOptions.flags] - Named flags / options
+ * @param {Object} [executionOptions.db] - Knex / ORM database instance
+ * @param {Object} [executionOptions.queue] - Background job queue dispatcher
+ * @param {Object} [executionOptions.services] - Service registry or caller
+ * @param {Object} [executionOptions.mailer] - Mailer service
+ * @param {Object} [executionOptions.events] - Application event dispatcher
+ * @param {Object} [executionOptions.logger] - Logger instance (default: console)
+ * @returns {Promise<{ success: boolean, result?: any, error?: Error, durationMs: number }>}
+ */
+async function executeCommand(commandDef, executionOptions = {}) {
+  if (!commandDef || typeof commandDef !== 'object') {
+    throw new TypeError('executeCommand requires a command definition');
+  }
+
+  const handleFn = commandDef.handle || commandDef.run;
+  if (typeof handleFn !== 'function') {
+    throw new TypeError(`Command "${commandDef.name || 'anonymous'}" has no executable handle function`);
+  }
+
+  const {
+    args = [],
+    flags = {},
+    db = null,
+    queue = null,
+    services = null,
+    mailer = null,
+    events = null,
+    logger = console,
+  } = executionOptions;
+
+  const start = Date.now();
+  const context = {
+    db,
+    queue,
+    services,
+    mailer,
+    events,
+    logger,
+    args: Array.isArray(args) ? args : [],
+    flags: flags && typeof flags === 'object' ? flags : {},
+  };
+
+  try {
+    const result = await handleFn(context);
+    const durationMs = Date.now() - start;
+    return {
+      success: true,
+      result,
+      durationMs,
+    };
+  } catch (error) {
+    const durationMs = Date.now() - start;
+    return {
+      success: false,
+      error,
+      durationMs,
+    };
+  }
+}
+
+module.exports = {
+  executeCommand,
+};

package/core/compression/compressible.js

@@ -8,7 +8,7 @@
 const COMPRESSIBLE_TYPE_REGEX = /^(?:text\/[a-z0-9.+_-]+|application\/(?:javascript|x-javascript|json|ld\+json|manifest\+json|graphql\+json|geo\+json|xml|atom\+xml|rss\+xml|xhtml\+xml|x-yaml|yaml|vnd\.api\+json|schema\+json|hal\+json)|image\/svg\+xml)$/i;
 
 // Regex patterns for already-compressed or non-compressible types
-const INCOMPRESSIBLE_TYPE_REGEX = /^(?:image\/(?:jpeg|png|gif|webp|avif|heic|heif)|video\/[a-z0-9.+_-]+|audio\/[a-z0-9.+_-]+|application\/(?:zip|gzip|x-gzip|x-bzip2|x-compress|x-7z-compressed|x-rar-compressed|pdf|wasm|octet-stream))$/i;
+const INCOMPRESSIBLE_TYPE_REGEX = /^(?:text\/event-stream|image\/(?:jpeg|png|gif|webp|avif|heic|heif)|video\/[a-z0-9.+_-]+|audio\/[a-z0-9.+_-]+|application\/(?:zip|gzip|x-gzip|x-bzip2|x-compress|x-7z-compressed|x-rar-compressed|pdf|wasm|octet-stream))$/i;
 
 const compressibleCache = new Map();
 const MAX_MIME_CACHE_SIZE = 256;