create-fluxstack 1.1.0 → 1.4.0

package/core/utils/env.ts

@@ -0,0 +1,306 @@
+/**
+ * ⚡ FluxStack Unified Environment Loader
+ *
+ * Single source of truth for environment variables with:
+ * - Automatic type casting
+ * - Build-safe dynamic access (prevents Bun inlining)
+ * - Simple, intuitive API
+ * - TypeScript type inference
+ *
+ * @example
+ * ```ts
+ * import { env } from '@/core/utils/env'
+ *
+ * const port = env.PORT                    // number (3000)
+ * const debug = env.DEBUG                  // boolean (false)
+ * const origins = env.CORS_ORIGINS         // string[] (['*'])
+ *
+ * // Custom vars with smart casting
+ * const timeout = env.get('TIMEOUT', 5000)        // number
+ * const enabled = env.get('FEATURE_X', false)     // boolean
+ * const tags = env.get('TAGS', ['api'])           // string[]
+ * ```
+ */
+
+/**
+ * Smart environment loader with dynamic access
+ * Uses Bun.env (runtime) → process.env (fallback) → eval (last resort)
+ */
+class EnvLoader {
+  private cache = new Map<string, any>()
+  private accessor: () => Record<string, string | undefined>
+
+  constructor() {
+    this.accessor = this.createAccessor()
+  }
+
+  /**
+   * Create dynamic accessor to prevent build-time inlining
+   */
+  private createAccessor(): () => Record<string, string | undefined> {
+    const global = globalThis as any
+
+    return () => {
+      // Try Bun.env first (most reliable in Bun)
+      if (global['Bun']?.['env']) {
+        return global['Bun']['env']
+      }
+
+      // Fallback to process.env
+      if (global['process']?.['env']) {
+        return global['process']['env']
+      }
+
+      // Last resort: eval to bypass static analysis
+      try {
+        const proc = eval('typeof process !== "undefined" ? process : null')
+        return proc?.env || {}
+      } catch {
+        return {}
+      }
+    }
+  }
+
+  /**
+   * Get environment variable with automatic type casting
+   * Type is inferred from defaultValue
+   */
+  get<T>(key: string, defaultValue?: T): T {
+    // Check cache first
+    const cacheKey = `${key}:${typeof defaultValue}`
+    if (this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey)
+    }
+
+    const env = this.accessor()
+    const value = env[key]
+
+    if (!value || value === '') {
+      this.cache.set(cacheKey, defaultValue as T)
+      return defaultValue as T
+    }
+
+    // Auto-detect type from defaultValue
+    let result: any = value
+
+    if (typeof defaultValue === 'number') {
+      const parsed = Number(value)
+      result = isNaN(parsed) ? defaultValue : parsed
+    } else if (typeof defaultValue === 'boolean') {
+      result = ['true', '1', 'yes', 'on'].includes(value.toLowerCase())
+    } else if (Array.isArray(defaultValue)) {
+      result = value.split(',').map(v => v.trim()).filter(Boolean)
+    } else if (typeof defaultValue === 'object' && defaultValue !== null) {
+      try {
+        result = JSON.parse(value)
+      } catch {
+        result = defaultValue
+      }
+    }
+
+    this.cache.set(cacheKey, result)
+    return result as T
+  }
+
+  /**
+   * Check if environment variable exists and has a value
+   */
+  has(key: string): boolean {
+    const env = this.accessor()
+    const value = env[key]
+    return value !== undefined && value !== ''
+  }
+
+  /**
+   * Get all environment variables
+   */
+  all(): Record<string, string> {
+    const env = this.accessor()
+    const result: Record<string, string> = {}
+
+    for (const [key, value] of Object.entries(env)) {
+      if (value !== undefined && value !== '') {
+        result[key] = value
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Require specific environment variables (throws if missing)
+   */
+  require(keys: string[]): void {
+    const missing = keys.filter(key => !this.has(key))
+    if (missing.length > 0) {
+      throw new Error(
+        `Missing required environment variables: ${missing.join(', ')}\n` +
+        `Please set them in your .env file or environment.`
+      )
+    }
+  }
+
+  /**
+   * Validate environment variable value
+   */
+  validate(key: string, validValues: string[]): void {
+    const value = this.get(key, '')
+    if (value && !validValues.includes(value)) {
+      throw new Error(
+        `Invalid value for ${key}: "${value}"\n` +
+        `Valid values are: ${validValues.join(', ')}`
+      )
+    }
+  }
+
+  /**
+   * Clear cache (useful for testing)
+   */
+  clearCache(): void {
+    this.cache.clear()
+  }
+}
+
+// Singleton instance
+const loader = new EnvLoader()
+
+/**
+ * Unified environment variables API
+ */
+export const env = {
+  /**
+   * Get environment variable with smart type casting
+   * @example env.get('PORT', 3000) → number
+   */
+  get: <T>(key: string, defaultValue?: T): T => loader.get(key, defaultValue),
+
+  /**
+   * Check if environment variable exists
+   */
+  has: (key: string): boolean => loader.has(key),
+
+  /**
+   * Get all environment variables
+   */
+  all: (): Record<string, string> => loader.all(),
+
+  /**
+   * Require environment variables (throws if missing)
+   */
+  require: (keys: string[]): void => loader.require(keys),
+
+  /**
+   * Validate environment variable value
+   */
+  validate: (key: string, validValues: string[]): void => loader.validate(key, validValues),
+
+  /**
+   * Clear cache (for testing)
+   */
+  clearCache: (): void => loader.clearCache(),
+
+  // Common environment variables with smart defaults
+  get NODE_ENV() { return this.get('NODE_ENV', 'development') as 'development' | 'production' | 'test' },
+  get PORT() { return this.get('PORT', 3000) },
+  get HOST() { return this.get('HOST', 'localhost') },
+  get DEBUG() { return this.get('DEBUG', false) },
+  get LOG_LEVEL() { return this.get('LOG_LEVEL', 'info') as 'debug' | 'info' | 'warn' | 'error' },
+  get LOG_FORMAT() { return this.get('LOG_FORMAT', 'pretty') as 'json' | 'pretty' },
+
+  // API
+  get API_PREFIX() { return this.get('API_PREFIX', '/api') },
+  get VITE_PORT() { return this.get('VITE_PORT', 5173) },
+
+  // CORS
+  get CORS_ORIGINS() { return this.get('CORS_ORIGINS', ['*']) },
+  get CORS_METHODS() { return this.get('CORS_METHODS', ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']) },
+  get CORS_HEADERS() { return this.get('CORS_HEADERS', ['Content-Type', 'Authorization']) },
+  get CORS_CREDENTIALS() { return this.get('CORS_CREDENTIALS', false) },
+  get CORS_MAX_AGE() { return this.get('CORS_MAX_AGE', 86400) },
+
+  // App
+  get FLUXSTACK_APP_NAME() { return this.get('FLUXSTACK_APP_NAME', 'FluxStack') },
+  get FLUXSTACK_APP_VERSION() { return this.get('FLUXSTACK_APP_VERSION', '1.0.0') },
+
+  // Features
+  get ENABLE_MONITORING() { return this.get('ENABLE_MONITORING', false) },
+  get ENABLE_SWAGGER() { return this.get('ENABLE_SWAGGER', true) },
+  get ENABLE_METRICS() { return this.get('ENABLE_METRICS', false) },
+
+  // Database
+  get DATABASE_URL() { return this.get('DATABASE_URL', '') },
+  get DB_HOST() { return this.get('DB_HOST', 'localhost') },
+  get DB_PORT() { return this.get('DB_PORT', 5432) },
+  get DB_NAME() { return this.get('DB_NAME', '') },
+  get DB_USER() { return this.get('DB_USER', '') },
+  get DB_PASSWORD() { return this.get('DB_PASSWORD', '') },
+  get DB_SSL() { return this.get('DB_SSL', false) },
+
+  // Auth
+  get JWT_SECRET() { return this.get('JWT_SECRET', '') },
+  get JWT_EXPIRES_IN() { return this.get('JWT_EXPIRES_IN', '24h') },
+  get JWT_ALGORITHM() { return this.get('JWT_ALGORITHM', 'HS256') },
+
+  // Email
+  get SMTP_HOST() { return this.get('SMTP_HOST', '') },
+  get SMTP_PORT() { return this.get('SMTP_PORT', 587) },
+  get SMTP_USER() { return this.get('SMTP_USER', '') },
+  get SMTP_PASSWORD() { return this.get('SMTP_PASSWORD', '') },
+  get SMTP_SECURE() { return this.get('SMTP_SECURE', false) },
+}
+
+/**
+ * Environment helpers
+ */
+export const helpers = {
+  isDevelopment: (): boolean => env.NODE_ENV === 'development',
+  isProduction: (): boolean => env.NODE_ENV === 'production',
+  isTest: (): boolean => env.NODE_ENV === 'test',
+
+  getServerUrl: (): string => `http://${env.HOST}:${env.PORT}`,
+  getClientUrl: (): string => `http://${env.HOST}:${env.VITE_PORT}`,
+
+  getDatabaseUrl: (): string | null => {
+    if (env.DATABASE_URL) return env.DATABASE_URL
+
+    const { DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD } = env
+    if (DB_HOST && DB_NAME) {
+      const auth = DB_USER ? `${DB_USER}:${DB_PASSWORD}@` : ''
+      return `postgres://${auth}${DB_HOST}:${DB_PORT}/${DB_NAME}`
+    }
+
+    return null
+  }
+}
+
+/**
+ * Create namespaced environment access
+ * @example
+ * const db = createNamespace('DATABASE_')
+ * db.get('URL') // reads DATABASE_URL
+ */
+export function createNamespace(prefix: string) {
+  return {
+    get: <T>(key: string, defaultValue?: T): T =>
+      env.get(`${prefix}${key}`, defaultValue),
+
+    has: (key: string): boolean =>
+      env.has(`${prefix}${key}`),
+
+    all: (): Record<string, string> => {
+      const allEnv = env.all()
+      const namespaced: Record<string, string> = {}
+
+      for (const [key, value] of Object.entries(allEnv)) {
+        if (key.startsWith(prefix)) {
+          namespaced[key.slice(prefix.length)] = value
+        }
+      }
+
+      return namespaced
+    }
+  }
+}
+
+// Default export
+export default env

package/core/utils/helpers.ts

@@ -87,20 +87,20 @@ export const throttle = <T extends (...args: any[]) => any>(
 }
 
 export const isProduction = (): boolean => {
-  // Import here to avoid circular dependency  
-  const { env } = require('./env-runtime-v2')
+  // Import here to avoid circular dependency
+  const { env } = require('./env')
   return env.NODE_ENV === 'production'
 }
 
 export const isDevelopment = (): boolean => {
   // Import here to avoid circular dependency
-  const { env } = require('./env-runtime-v2')
+  const { env } = require('./env')
   return env.NODE_ENV === 'development' || !env.NODE_ENV
 }
 
 export const isTest = (): boolean => {
   // Import here to avoid circular dependency
-  const { env } = require('./env-runtime-v2')
+  const { env } = require('./env')
   return env.NODE_ENV === 'test'
 }
 

package/core/utils/logger/colors.ts

@@ -0,0 +1,114 @@
+/**
+ * FluxStack Logger - Color Management
+ * Generates unique colors for each module
+ */
+
+import chalk from 'chalk'
+
+// Cache for module colors
+const moduleColors = new Map<string, chalk.Chalk>()
+
+/**
+ * Pre-defined colors for common modules
+ */
+const COMMON_MODULE_COLORS: Record<string, string> = {
+  api: '#4CAF50',      // Green
+  db: '#2196F3',       // Blue
+  auth: '#FF9800',     // Orange
+  user: '#9C27B0',     // Purple
+  config: '#00BCD4',   // Cyan
+  utils: '#607D8B',    // Blue Gray
+  routes: '#E91E63',   // Pink
+  controllers: '#3F51B5', // Indigo
+  models: '#009688',   // Teal
+  services: '#FF5722', // Deep Orange
+  plugins: '#673AB7',  // Deep Purple
+  middleware: '#795548', // Brown
+  live: '#00E676',     // Green Accent
+  websocket: '#00B0FF', // Light Blue Accent
+  build: '#FFC107',    // Amber
+  cli: '#CDDC39'       // Lime
+}
+
+/**
+ * Symbols for different log levels
+ */
+export const LOG_SYMBOLS = {
+  error: chalk.red('✖'),
+  warn: chalk.yellow('⚠'),
+  info: chalk.blue('ℹ'),
+  debug: chalk.magenta('⬤'),
+  default: chalk.gray('•')
+} as const
+
+/**
+ * Colors for different log levels
+ */
+export const LEVEL_COLORS = {
+  error: chalk.bold.red,
+  warn: chalk.bold.yellow,
+  info: chalk.bold.blue,
+  debug: chalk.bold.magenta,
+  default: chalk.bold.gray
+} as const
+
+/**
+ * Generate a unique color for a module based on its name
+ */
+export function getColorForModule(moduleName: string): chalk.Chalk {
+  // Check cache first
+  if (moduleColors.has(moduleName)) {
+    return moduleColors.get(moduleName)!
+  }
+
+  // Check if module name contains a common module keyword
+  for (const [key, hexColor] of Object.entries(COMMON_MODULE_COLORS)) {
+    if (moduleName.toLowerCase().includes(key)) {
+      const color = chalk.hex(hexColor)
+      moduleColors.set(moduleName, color)
+      return color
+    }
+  }
+
+  // Generate color from module name hash
+  let hash = 0
+  for (let i = 0; i < moduleName.length; i++) {
+    hash = moduleName.charCodeAt(i) + ((hash << 5) - hash)
+  }
+
+  // Generate pleasant color using HSL
+  const h = Math.abs(hash) % 360
+  const s = 65 + (Math.abs(hash) % 20) // Saturation 65-85%
+  const l = 45 + (Math.abs(hash) % 15) // Lightness 45-60%
+
+  const hexColor = hslToHex(h, s, l)
+  const color = chalk.hex(hexColor)
+
+  moduleColors.set(moduleName, color)
+  return color
+}
+
+/**
+ * Convert HSL to Hex color
+ */
+function hslToHex(h: number, s: number, l: number): string {
+  s /= 100
+  l /= 100
+
+  const k = (n: number) => (n + h / 30) % 12
+  const a = s * Math.min(l, 1 - l)
+  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)))
+
+  const r = Math.round(255 * f(0))
+  const g = Math.round(255 * f(8))
+  const b = Math.round(255 * f(4))
+
+  return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`
+}
+
+/**
+ * Clear color cache (useful for testing)
+ */
+export function clearColorCache(): void {
+  moduleColors.clear()
+}

package/core/utils/logger/config.ts

@@ -0,0 +1,35 @@
+/**
+ * FluxStack Logger Configuration
+ * Re-export from declarative config
+ */
+
+import { loggerConfig } from '@/config/logger.config'
+
+export interface LoggerConfig {
+  level: 'debug' | 'info' | 'warn' | 'error'
+  dateFormat: string
+  logToFile: boolean
+  maxSize: string
+  maxFiles: string
+  objectDepth: number
+  enableColors: boolean
+  enableStackTrace: boolean
+}
+
+/**
+ * Get logger configuration from declarative config
+ */
+export function getLoggerConfig(): LoggerConfig {
+  return {
+    level: loggerConfig.level,
+    dateFormat: loggerConfig.dateFormat,
+    logToFile: loggerConfig.logToFile,
+    maxSize: loggerConfig.maxSize,
+    maxFiles: loggerConfig.maxFiles,
+    objectDepth: loggerConfig.objectDepth,
+    enableColors: loggerConfig.enableColors,
+    enableStackTrace: loggerConfig.enableStackTrace
+  }
+}
+
+export const LOGGER_CONFIG = getLoggerConfig()

package/core/utils/logger/formatter.ts

@@ -0,0 +1,82 @@
+/**
+ * FluxStack Logger - Message Formatter
+ * Formats log messages with proper object inspection
+ */
+
+import { inspect } from 'util'
+import { LOGGER_CONFIG } from './config'
+
+/**
+ * Format a log message with proper object inspection
+ */
+export function formatMessage(message: unknown, args: unknown[] = []): string {
+  const inspectOptions = {
+    depth: LOGGER_CONFIG.objectDepth,
+    colors: LOGGER_CONFIG.enableColors,
+    compact: false,
+    breakLength: 100
+  }
+
+  // Format the main message
+  let formattedMessage: string
+
+  if (typeof message === 'string') {
+    formattedMessage = message
+  } else if (message instanceof Error) {
+    // Special handling for Error objects
+    formattedMessage = `${message.name}: ${message.message}\n${message.stack || ''}`
+  } else if (typeof message === 'object' && message !== null) {
+    // Use util.inspect for better object formatting
+    formattedMessage = inspect(message, inspectOptions)
+  } else {
+    formattedMessage = String(message)
+  }
+
+  // Format additional arguments (skip undefined values)
+  if (args.length > 0) {
+    const formattedArgs = args
+      .filter(arg => arg !== undefined) // Skip undefined values
+      .map(arg => {
+        if (typeof arg === 'object' && arg !== null) {
+          return inspect(arg, inspectOptions)
+        }
+        return String(arg)
+      })
+      .join(' ')
+
+    // Only add formatted args if there are any after filtering
+    if (formattedArgs.length > 0) {
+      return `${formattedMessage} ${formattedArgs}`
+    }
+  }
+
+  return formattedMessage
+}
+
+/**
+ * Format a section title
+ */
+export function formatSection(title: string): string {
+  return `=== ${title.toUpperCase()} ===`
+}
+
+/**
+ * Format an important message
+ */
+export function formatImportant(title: string): string {
+  return `■ ${title.toUpperCase()} ■`
+}
+
+/**
+ * Format operation start
+ */
+export function formatOperationStart(operation: string): string {
+  return `▶ INICIANDO: ${operation}`
+}
+
+/**
+ * Format operation success
+ */
+export function formatOperationSuccess(operation: string): string {
+  return `✓ CONCLUÍDO: ${operation}`
+}

package/core/utils/logger/group-logger.ts

@@ -0,0 +1,101 @@
+/**
+ * FluxStack Logger - Grouped/Collapsible Logs
+ * Creates beautiful grouped console output
+ */
+
+import chalk from 'chalk'
+
+export interface GroupOptions {
+  title: string
+  icon?: string
+  collapsed?: boolean
+  color?: 'cyan' | 'green' | 'yellow' | 'blue' | 'magenta' | 'gray'
+}
+
+/**
+ * Start a log group (collapsible in browsers, indented in terminal)
+ */
+export function startGroup(options: GroupOptions): void {
+  const { title, icon = '📦', collapsed = false, color = 'cyan' } = options
+
+  // Check if we're in a browser-like environment (has console.group)
+  if (typeof console.groupCollapsed === 'function' && typeof console.group === 'function') {
+    const coloredTitle = chalk[color].bold(`${icon} ${title}`)
+
+    if (collapsed) {
+      console.groupCollapsed(coloredTitle)
+    } else {
+      console.group(coloredTitle)
+    }
+  } else {
+    // Terminal fallback - use box drawing
+    const coloredTitle = chalk[color].bold(`${icon} ${title}`)
+    console.log('\n' + coloredTitle)
+    console.log(chalk.gray('─'.repeat(Math.min(title.length + 4, 60))))
+  }
+}
+
+/**
+ * End a log group
+ */
+export function endGroup(): void {
+  if (typeof console.groupEnd === 'function') {
+    console.groupEnd()
+  } else {
+    // Terminal fallback - just add spacing
+    console.log('')
+  }
+}
+
+/**
+ * Log within a group
+ */
+export function logInGroup(message: string, icon?: string): void {
+  const prefix = icon ? `${icon} ` : '  '
+  console.log(chalk.gray(prefix) + message)
+}
+
+/**
+ * Helper: Auto-group function that handles start/end automatically
+ */
+export async function withGroup<T>(
+  options: GroupOptions,
+  callback: () => T | Promise<T>
+): Promise<T> {
+  startGroup(options)
+  try {
+    const result = await callback()
+    return result
+  } finally {
+    endGroup()
+  }
+}
+
+/**
+ * Helper: Create a summary line for groups
+ */
+export function groupSummary(count: number, itemName: string, icon: string = '✓'): void {
+  // itemName should already include proper pluralization
+  const message = `${icon} ${count} ${itemName}`
+  console.log(chalk.green.bold(message))
+}
+
+/**
+ * Create a boxed section for important info
+ */
+export function logBox(title: string, content: string[], options: { color?: 'cyan' | 'green' | 'yellow' } = {}): void {
+  const { color = 'cyan' } = options
+  const maxWidth = Math.max(title.length, ...content.map(c => c.length)) + 4
+
+  console.log('')
+  console.log(chalk[color]('┌' + '─'.repeat(maxWidth) + '┐'))
+  console.log(chalk[color]('│ ') + chalk.bold(title.padEnd(maxWidth - 2)) + chalk[color](' │'))
+  console.log(chalk[color]('├' + '─'.repeat(maxWidth) + '┤'))
+
+  for (const line of content) {
+    console.log(chalk[color]('│ ') + line.padEnd(maxWidth - 2) + chalk[color](' │'))
+  }
+
+  console.log(chalk[color]('└' + '─'.repeat(maxWidth) + '┘'))
+  console.log('')
+}