create-fluxstack 1.0.1 → 1.0.3

package/examples/hybrid-env-strategy.ts

@@ -0,0 +1,212 @@
+/**
+ * Estratégia Híbrida: Env Fixado + Env Dinâmico
+ * Use o melhor de cada abordagem conforme necessário
+ */
+
+import { env } from '@/core/utils/env-runtime'
+
+// ========================================
+// CONFIGURAÇÕES FIXADAS (Build-time)
+// ========================================
+// Use para valores que nunca mudam ou precisam de máxima performance
+
+// App metadata - fixado é OK
+const APP_NAME = process.env.FLUXSTACK_APP_NAME || 'FluxStack'
+const APP_VERSION = process.env.FLUXSTACK_APP_VERSION || '1.0.0'
+
+// Feature flags - fixado é OK  
+const ENABLE_SWAGGER = process.env.ENABLE_SWAGGER !== 'false'
+const ENABLE_CORS = process.env.ENABLE_CORS !== 'false'
+
+// Build configuration - fixado é ideal
+const BUILD_TARGET = process.env.BUILD_TARGET || 'bun'
+const CLIENT_OUTDIR = process.env.CLIENT_OUTDIR || 'dist/client'
+
+// ========================================  
+// CONFIGURAÇÕES DINÂMICAS (Runtime)
+// ========================================
+// Use para valores que precisam mudar em diferentes deploys
+
+// Server config - deve ser dinâmico
+const getServerConfig = () => ({
+  port: env.num('PORT', 3000),           // 🔄 Dinâmico
+  host: env.get('HOST', 'localhost'),    // 🔄 Dinâmico
+  apiPrefix: env.get('API_PREFIX', '/api')
+})
+
+// Database - deve ser dinâmico
+const getDatabaseConfig = () => ({
+  url: env.get('DATABASE_URL'),          // 🔄 Dinâmico
+  maxConnections: env.num('DB_MAX_CONNECTIONS', 10),
+  ssl: env.bool('DB_SSL', env.get('NODE_ENV') === 'production')
+})
+
+// Secrets - deve ser dinâmico
+const getSecrets = () => ({
+  jwtSecret: env.get('JWT_SECRET'),      // 🔄 Dinâmico
+  apiKey: env.get('API_KEY'),
+  encryptionKey: env.get('ENCRYPTION_KEY')
+})
+
+// Environment specific - dinâmico
+const getEnvironmentConfig = () => ({
+  nodeEnv: env.get('NODE_ENV', 'development'),  // 🔄 Dinâmico
+  logLevel: env.get('LOG_LEVEL', 'info'),
+  debug: env.bool('DEBUG', false)
+})
+
+// ========================================
+// CONFIGURAÇÃO HÍBRIDA
+// ========================================
+
+export const hybridConfig = {
+  // Fixado no build (performance máxima)
+  app: {
+    name: APP_NAME,                    // ⚡ Fixado
+    version: APP_VERSION,              // ⚡ Fixado
+    enableSwagger: ENABLE_SWAGGER,     // ⚡ Fixado
+    enableCors: ENABLE_CORS           // ⚡ Fixado
+  },
+
+  build: {
+    target: BUILD_TARGET,              // ⚡ Fixado
+    clientOutDir: CLIENT_OUTDIR        // ⚡ Fixado
+  },
+
+  // Dinâmico no runtime (flexibilidade máxima)
+  runtime: {
+    server: getServerConfig(),         // 🔄 Dinâmico
+    database: getDatabaseConfig(),     // 🔄 Dinâmico
+    secrets: getSecrets(),             // 🔄 Dinâmico
+    environment: getEnvironmentConfig() // 🔄 Dinâmico
+  }
+}
+
+// ========================================
+// EXEMPLO DE USO PRÁTICO
+// ========================================
+
+export function createHybridServer() {
+  console.log(`🚀 Starting ${hybridConfig.app.name} v${hybridConfig.app.version}`)
+  
+  const { server, database, environment } = hybridConfig.runtime
+  
+  console.log(`📊 Environment: ${environment.nodeEnv}`)
+  console.log(`🌐 Server: ${server.host}:${server.port}`)
+  console.log(`💾 Database: ${database.url ? '✅ Connected' : '❌ Not configured'}`)
+  
+  // Configuração do FluxStack
+  const config = {
+    // Valores fixados (build-time) - performance máxima
+    app: hybridConfig.app,
+    build: hybridConfig.build,
+    
+    // Valores dinâmicos (runtime) - flexibilidade máxima
+    server: {
+      port: server.port,        // 🔄 Pode mudar sem rebuild
+      host: server.host,        // 🔄 Pode mudar sem rebuild
+      apiPrefix: server.apiPrefix,
+      cors: {
+        origins: env.array('CORS_ORIGINS', ['*']),
+        enabled: hybridConfig.app.enableCors  // ⚡ Fixado no build
+      }
+    },
+    
+    logging: {
+      level: environment.logLevel,  // 🔄 Pode mudar sem rebuild
+      debug: environment.debug
+    }
+  }
+  
+  return config
+}
+
+// ========================================
+// OTIMIZAÇÃO POR AMBIENTE
+// ========================================
+
+export function createOptimizedConfig() {
+  const nodeEnv = env.get('NODE_ENV', 'development')
+  
+  switch (nodeEnv) {
+    case 'development':
+      return {
+        // Development: tudo dinâmico para flexibilidade
+        port: env.num('PORT', 3000),           // 🔄
+        debug: env.bool('DEBUG', true),        // 🔄
+        logLevel: env.get('LOG_LEVEL', 'debug'), // 🔄
+        hotReload: env.bool('HOT_RELOAD', true)  // 🔄
+      }
+      
+    case 'production':
+      return {
+        // Production: mix de fixado e dinâmico
+        appName: APP_NAME,                     // ⚡ Fixado (performance)
+        version: APP_VERSION,                  // ⚡ Fixado (performance)
+        port: env.num('PORT', 3000),           // 🔄 Dinâmico (deploy)
+        dbUrl: env.get('DATABASE_URL'),        // 🔄 Dinâmico (deploy)
+        logLevel: env.get('LOG_LEVEL', 'warn') // 🔄 Dinâmico (ops)
+      }
+      
+    default:
+      return createHybridServer()
+  }
+}
+
+// ========================================
+// PERFORMANCE COMPARISON
+// ========================================
+
+export const performanceComparison = {
+  // ⚡ ULTRA RÁPIDO - Fixado no build
+  fixedConfig: {
+    port: 3000,                    // Literal number
+    dbUrl: "postgres://...",       // Literal string  
+    debug: false                   // Literal boolean
+  },
+  
+  // 🔄 LIGEIRAMENTE MAIS LENTO - Dinâmico
+  dynamicConfig: {
+    port: env.num('PORT', 3000),           // Function call
+    dbUrl: env.get('DATABASE_URL'),        // Function call
+    debug: env.bool('DEBUG', false)        // Function call
+  }
+}
+
+// ========================================
+// MIGRAÇÃO GRADUAL
+// ========================================
+
+export const migrationStrategy = {
+  // Passo 1: Identifique configurações críticas
+  critical: {
+    // Use dinâmico para configs que DEVEM mudar
+    port: env.num('PORT', 3000),
+    dbUrl: env.get('DATABASE_URL'),
+    secrets: env.get('JWT_SECRET')
+  },
+  
+  // Passo 2: Mantenha fixado o que não precisa mudar
+  static: {
+    appName: process.env.APP_NAME || 'MyApp',
+    version: process.env.APP_VERSION || '1.0.0',
+    features: process.env.FEATURES?.split(',') || []
+  },
+  
+  // Passo 3: Migre gradualmente conforme necessário
+  gradually: {
+    // Comece com fixado...
+    logLevel: process.env.LOG_LEVEL || 'info',
+    
+    // ...depois mude para dinâmico quando precisar
+    // logLevel: env.get('LOG_LEVEL', 'info')
+  }
+}
+
+export default {
+  hybridConfig,
+  createHybridServer,
+  createOptimizedConfig,
+  performanceComparison,
+  migrationStrategy
+}

package/examples/simplified-env-usage.ts

@@ -0,0 +1,251 @@
+/**
+ * Exemplos da API simplificada de Environment Variables
+ * Mais elegante, intuitiva e com menos código
+ */
+
+import { env, createNamespace, validate, helpers } from '../core/utils/env-runtime-v2'
+
+// ========================================
+// 1. CASTING AUTOMÁTICO INTELIGENTE
+// ========================================
+
+// ✅ NOVO - API super simples com casting automático
+const config = {
+  port: env.get('PORT', 3000),              // -> number (baseado no default)
+  debug: env.get('DEBUG', false),           // -> boolean (baseado no default)
+  origins: env.get('CORS_ORIGINS', ['*']),  // -> string[] (baseado no default)
+  host: env.get('HOST', 'localhost'),       // -> string (baseado no default)
+  dbUrl: env.get('DATABASE_URL'),           // -> string | undefined
+  retries: env.get('MAX_RETRIES', 3),       // -> number
+  features: env.get('FEATURES', ['api'])    // -> string[]
+}
+
+// ❌ ANTES - API verbosa com métodos específicos
+const oldConfig = {
+  port: env.num('PORT', 3000),
+  debug: env.bool('DEBUG', false),
+  origins: env.array('CORS_ORIGINS', ['*']),
+  host: env.get('HOST', 'localhost'),
+  dbUrl: env.get('DATABASE_URL'),
+  retries: env.num('MAX_RETRIES', 3),
+  features: env.array('FEATURES', ['api'])
+}
+
+// ========================================
+// 2. ACESSO DIRETO COMO PROPRIEDADES
+// ========================================
+
+console.log(`🚀 Starting on ${env.HOST}:${env.PORT}`)           // Direto!
+console.log(`📊 Environment: ${env.NODE_ENV}`)                  // Direto!  
+console.log(`🐛 Debug mode: ${env.DEBUG}`)                      // Direto!
+console.log(`📋 Swagger: ${env.ENABLE_SWAGGER}`)                // Direto!
+console.log(`💾 Database: ${env.DATABASE_URL || 'not configured'}`) // Direto!
+
+// Todos com tipos corretos automaticamente!
+
+// ========================================
+// 3. CONFIGURAÇÃO DE SERVIDOR SIMPLIFICADA
+// ========================================
+
+export function createSimpleServer() {
+  return {
+    // Casting automático baseado no tipo do default
+    server: {
+      port: env.get('PORT', 3000),           // number
+      host: env.get('HOST', 'localhost'),    // string
+      timeout: env.get('TIMEOUT', 30000),    // number
+      keepAlive: env.get('KEEP_ALIVE', true) // boolean
+    },
+    
+    // Ou acesso direto
+    database: {
+      url: env.DATABASE_URL,          // string
+      ssl: env.DB_SSL,               // boolean 
+      port: env.DB_PORT,             // number
+      maxConnections: env.get('DB_MAX_CONNECTIONS', 10) // number
+    },
+    
+    cors: {
+      origins: env.CORS_ORIGINS,              // string[]
+      credentials: env.get('CORS_CREDENTIALS', false), // boolean
+      maxAge: env.get('CORS_MAX_AGE', 86400)  // number
+    }
+  }
+}
+
+// ========================================
+// 4. NAMESPACES PARA ORGANIZAÇÃO
+// ========================================
+
+// Criar namespaces especializados
+const db = createNamespace('DATABASE_')
+const redis = createNamespace('REDIS_')
+const smtp = createNamespace('SMTP_')
+
+const databaseConfig = {
+  url: db.get('URL'),                    // DATABASE_URL
+  host: db.get('HOST', 'localhost'),     // DATABASE_HOST  
+  port: db.get('PORT', 5432),           // DATABASE_PORT (number)
+  ssl: db.get('SSL', false),            // DATABASE_SSL (boolean)
+  poolSize: db.get('POOL_SIZE', 10),    // DATABASE_POOL_SIZE (number)
+  timeout: db.get('TIMEOUT', 30000)     // DATABASE_TIMEOUT (number)
+}
+
+const redisConfig = {
+  url: redis.get('URL'),                // REDIS_URL
+  host: redis.get('HOST', 'localhost'), // REDIS_HOST
+  port: redis.get('PORT', 6379),       // REDIS_PORT (number)
+  password: redis.get('PASSWORD')       // REDIS_PASSWORD
+}
+
+// ========================================
+// 5. CONFIGURAÇÃO CONDICIONAL ELEGANTE  
+// ========================================
+
+export function createConditionalConfig() {
+  const config: any = {
+    app: {
+      name: env.FLUXSTACK_APP_NAME,     // 'FluxStack'
+      version: env.FLUXSTACK_APP_VERSION // '1.0.0'
+    },
+    
+    server: {
+      port: env.PORT,                   // 3000
+      host: env.HOST                    // 'localhost'
+    }
+  }
+  
+  // Adicionar database se configurado
+  if (env.has('DATABASE_URL')) {
+    config.database = {
+      url: env.DATABASE_URL,
+      ssl: env.get('DB_SSL', env.NODE_ENV === 'production') // smart default
+    }
+  }
+  
+  // Features opcionais
+  if (env.ENABLE_MONITORING) {
+    config.monitoring = {
+      metrics: env.ENABLE_METRICS,
+      interval: env.get('METRICS_INTERVAL', 30000)
+    }
+  }
+  
+  return config
+}
+
+// ========================================
+// 6. VALIDAÇÃO SIMPLIFICADA
+// ========================================
+
+export function validateEnvironment() {
+  // Vars obrigatórias
+  validate.require(['NODE_ENV'])
+  
+  // Produção precisa de mais vars
+  if (helpers.isProduction()) {
+    validate.require(['DATABASE_URL', 'JWT_SECRET'])
+  }
+  
+  // Validar valores específicos
+  validate.oneOf('NODE_ENV', ['development', 'production', 'test'])
+  validate.oneOf('LOG_LEVEL', ['debug', 'info', 'warn', 'error'])
+}
+
+// ========================================
+// 7. HELPERS ÚTEIS
+// ========================================
+
+export function printConfiguration() {
+  console.log('🔧 Configuration loaded:')
+  console.log(`   Environment: ${env.NODE_ENV}`)
+  console.log(`   Server: ${helpers.getServerUrl()}`)
+  console.log(`   Client: ${helpers.getClientUrl()}`) 
+  console.log(`   Database: ${helpers.getDatabaseUrl() || 'not configured'}`)
+  console.log(`   Debug: ${env.DEBUG ? 'enabled' : 'disabled'}`)
+  console.log(`   Swagger: ${env.ENABLE_SWAGGER ? 'enabled' : 'disabled'}`)
+}
+
+// ========================================
+// 8. FLUXSTACK INTEGRATION SIMPLIFICADA
+// ========================================
+
+import { FluxStackFramework } from '../core/framework/server'
+
+export function createSimpleFluxStack() {
+  validateEnvironment()
+  
+  const app = new FluxStackFramework({
+    app: {
+      name: env.FLUXSTACK_APP_NAME,        // Direto!
+      version: env.FLUXSTACK_APP_VERSION   // Direto!
+    },
+    
+    server: {
+      port: env.PORT,                      // Direto! (number)
+      host: env.HOST,                      // Direto! (string)
+      apiPrefix: env.API_PREFIX,           // Direto! (string)
+      cors: {
+        origins: env.CORS_ORIGINS,         // Direto! (string[])
+        credentials: env.get('CORS_CREDENTIALS', false) // boolean
+      }
+    },
+    
+    client: {
+      port: env.VITE_PORT,                 // Direto! (number)
+      proxy: {
+        target: helpers.getServerUrl()     // Helper!
+      }
+    }
+  })
+  
+  // Plugins condicionais
+  if (env.ENABLE_SWAGGER) {
+    console.log('📋 Swagger enabled')
+    // app.use(swaggerPlugin)  
+  }
+  
+  if (env.ENABLE_MONITORING) {
+    console.log('📊 Monitoring enabled')
+    // app.use(monitoringPlugin)
+  }
+  
+  return app
+}
+
+// ========================================  
+// 9. COMPARAÇÃO ANTES vs DEPOIS
+// ========================================
+
+// ❌ ANTES - Verboso
+const beforeConfig = {
+  port: env.num('PORT', 3000),
+  debug: env.bool('DEBUG', false),
+  origins: env.array('CORS_ORIGINS', ['*']),
+  retries: env.num('MAX_RETRIES', 3),
+  timeout: env.num('TIMEOUT', 30000)
+}
+
+// ✅ DEPOIS - Limpo e elegante  
+const afterConfig = {
+  port: env.get('PORT', 3000),        // casting automático
+  debug: env.get('DEBUG', false),     // casting automático
+  origins: env.get('CORS_ORIGINS', ['*']), // casting automático
+  retries: env.get('MAX_RETRIES', 3), // casting automático
+  timeout: env.get('TIMEOUT', 30000)  // casting automático
+}
+
+// Ou ainda mais simples com propriedades diretas:
+const simpleConfig = {
+  port: env.PORT,           // Direto da propriedade
+  debug: env.DEBUG,         // Direto da propriedade
+  origins: env.CORS_ORIGINS // Direto da propriedade
+}
+
+export default {
+  createSimpleServer,
+  createConditionalConfig,
+  validateEnvironment,
+  printConfiguration,
+  createSimpleFluxStack
+}

package/flux-cli.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env bun
+
+/**
+ * FluxStack CLI - Comando nativo `flux`
+ * Permite criar projetos sem dependências externas ou configurações manuais
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+
+interface CreateProjectOptions {
+  name: string;
+  template?: 'basic' | 'minimal' | 'full';
+}
+
+async function createProject(options: CreateProjectOptions) {
+  const { name, template = 'basic' } = options;
+  const projectPath = path.resolve(name);
+  
+  console.log(`🚀 Creating FluxStack project: ${name}`);
+  console.log(`📋 Template: ${template}`);
+  console.log(`📁 Location: ${projectPath}`);
+  console.log();
+  
+  // Check if directory exists
+  try {
+    await fs.access(projectPath);
+    console.error(`❌ Directory "${name}" already exists`);
+    process.exit(1);
+  } catch (error: any) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+  
+  // Create project directory
+  await fs.mkdir(projectPath, { recursive: true });
+  
+  // Copy template
+  const templatePath = path.resolve(__dirname, 'templates', template);
+  await copyDirectory(templatePath, projectPath);
+  
+  // Process placeholders
+  await processTemplateFiles(projectPath, {
+    PROJECT_NAME: name,
+    PROJECT_DESCRIPTION: `A FluxStack application named ${name}`
+  });
+  
+  console.log('✅ Project structure created!');
+  console.log('📦 Installing dependencies...');
+  
+  // Install dependencies
+  await installDependencies(projectPath);
+  
+  console.log();
+  console.log('🎉 Project created successfully!');
+  console.log();
+  console.log('Next steps:');
+  console.log(`  cd ${name}`);
+  console.log('  bun run dev');
+  console.log();
+  console.log('Happy coding! 🚀');
+}
+
+async function copyDirectory(src: string, dest: string, exclude: string[] = ['node_modules', '.git', 'dist']) {
+  await fs.mkdir(dest, { recursive: true });
+  
+  try {
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      if (exclude.includes(entry.name)) continue;
+      
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      
+      if (entry.isDirectory()) {
+        await copyDirectory(srcPath, destPath, exclude);
+      } else {
+        const content = await fs.readFile(srcPath, 'utf-8');
+        await fs.writeFile(destPath, content, 'utf-8');
+      }
+    }
+  } catch (error) {
+    console.error(`❌ Template not found at: ${src}`);
+    console.error('Make sure you have the templates directory in your FluxStack installation.');
+    process.exit(1);
+  }
+}
+
+async function processTemplateFiles(
+  projectPath: string, 
+  replacements: Record<string, string>
+) {
+  const files = await getAllFiles(projectPath);
+  
+  for (const file of files) {
+    // Skip binary files
+    if (isBinaryFile(file)) continue;
+    
+    let content = await fs.readFile(file, 'utf-8');
+    
+    // Replace placeholders
+    for (const [key, value] of Object.entries(replacements)) {
+      const regex = new RegExp(`{{${key}}}`, 'g');
+      content = content.replace(regex, value);
+    }
+    
+    await fs.writeFile(file, content, 'utf-8');
+  }
+}
+
+async function getAllFiles(dirPath: string): Promise<string[]> {
+  const files: string[] = [];
+  const items = await fs.readdir(dirPath, { withFileTypes: true });
+  
+  for (const item of items) {
+    const fullPath = path.join(dirPath, item.name);
+    
+    if (item.isDirectory()) {
+      files.push(...await getAllFiles(fullPath));
+    } else {
+      files.push(fullPath);
+    }
+  }
+  
+  return files;
+}
+
+function isBinaryFile(filePath: string): boolean {
+  const binaryExtensions = ['.png', '.jpg', '.jpeg', '.gif', '.ico', '.svg', '.woff', '.woff2', '.ttf', '.eot'];
+  const ext = path.extname(filePath).toLowerCase();
+  return binaryExtensions.includes(ext);
+}
+
+async function installDependencies(projectPath: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const install = spawn('bun', ['install'], {
+      cwd: projectPath,
+      stdio: 'inherit'
+    });
+    
+    install.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Dependencies installation failed with code ${code}`));
+      }
+    });
+    
+    install.on('error', reject);
+  });
+}
+
+function showHelp() {
+  console.log(`
+🚀 FluxStack CLI
+
+Usage:
+  flux create <project-name>              Create a new FluxStack project
+  flux create <project-name> --template   Specify template (basic, minimal, full)
+  flux --help                             Show this help
+
+Examples:
+  flux create my-app                      Create basic project
+  flux create my-blog --template basic    Create with basic template
+  flux create my-api --template minimal   Create minimal project
+
+Templates:
+  basic     Full-featured app with frontend and backend (default)
+  minimal   Just the backend API
+  full      Everything + advanced features
+
+Get started in seconds! 🔥
+`);
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === '--help' || command === 'help') {
+  showHelp();
+  process.exit(0);
+}
+
+if (command === 'create') {
+  const projectName = args[1];
+  
+  if (!projectName) {
+    console.error('❌ Please provide a project name');
+    console.error('Usage: flux create <project-name>');
+    process.exit(1);
+  }
+  
+  // Validate project name
+  if (!/^[a-zA-Z0-9-_]+$/.test(projectName)) {
+    console.error('❌ Project name can only contain letters, numbers, hyphens, and underscores');
+    process.exit(1);
+  }
+  
+  const templateIndex = args.indexOf('--template');
+  const template = templateIndex !== -1 ? args[templateIndex + 1] as 'basic' | 'minimal' | 'full' : 'basic';
+  
+  createProject({ name: projectName, template }).catch(error => {
+    console.error('❌ Error creating project:', error.message);
+    process.exit(1);
+  });
+} else {
+  console.error(`❌ Unknown command: ${command}`);
+  console.error('Run "flux --help" for available commands');
+  process.exit(1);
+}