Fix/typescript typing issues

.kiro/specs/fluxstack-architecture-optimization/requirements.md

@@ -0,0 +1,127 @@
+# Requirements Document
+
+## Introduction
+
+Esta especificação define melhorias na arquitetura do FluxStack para otimizar a organização do código, performance, developer experience e manutenibilidade. O objetivo é evoluir o framework mantendo sua simplicidade e poder, mas corrigindo inconsistências estruturais e adicionando funcionalidades que faltam para um framework de produção robusto.
+
+## Requirements
+
+### Requirement 1: Reorganização da Estrutura de Pastas
+
+**User Story:** Como desenvolvedor usando FluxStack, eu quero uma estrutura de pastas mais consistente e intuitiva, para que eu possa navegar e organizar meu código de forma mais eficiente.
+
+#### Acceptance Criteria
+
+1. WHEN eu examino a estrutura do projeto THEN eu devo ver uma organização clara entre framework core, aplicação do usuário, e configurações
+2. WHEN eu procuro por arquivos relacionados THEN eles devem estar agrupados logicamente na mesma pasta ou subpasta
+3. WHEN eu adiciono novos plugins ou funcionalidades THEN deve haver um local claro e consistente para colocá-los
+4. WHEN eu trabalho com tipos compartilhados THEN deve haver uma estrutura clara que evite imports circulares
+5. WHEN eu examino a pasta core THEN ela deve estar organizada por funcionalidade (server, client, build, cli, etc.)
+
+### Requirement 2: Sistema de Build Otimizado
+
+**User Story:** Como desenvolvedor, eu quero um sistema de build mais robusto e rápido, para que eu possa ter builds confiáveis tanto em desenvolvimento quanto em produção.
+
+#### Acceptance Criteria
+
+1. WHEN eu executo `bun run build` THEN o processo deve ser otimizado e reportar progresso claramente
+2. WHEN o build falha THEN eu devo receber mensagens de erro claras e acionáveis
+3. WHEN eu faço build de produção THEN os assets devem ser otimizados (minificação, tree-shaking, etc.)
+4. WHEN eu uso build incremental THEN apenas os arquivos modificados devem ser reprocessados
+5. WHEN eu configuro diferentes targets THEN o build deve se adaptar automaticamente (Node.js, Bun, Docker)
+
+### Requirement 3: Sistema de Logging Aprimorado
+
+**User Story:** Como desenvolvedor, eu quero um sistema de logging mais estruturado e configurável, para que eu possa debugar problemas e monitorar a aplicação eficientemente.
+
+#### Acceptance Criteria
+
+1. WHEN a aplicação roda THEN os logs devem ter formato consistente com timestamps, níveis e contexto
+2. WHEN eu configuro LOG_LEVEL THEN apenas logs do nível especificado ou superior devem aparecer
+3. WHEN ocorre um erro THEN o log deve incluir stack trace, contexto da requisição e metadata relevante
+4. WHEN eu uso diferentes ambientes THEN o formato de log deve se adaptar (desenvolvimento vs produção)
+5. WHEN eu quero logs estruturados THEN deve haver suporte para JSON logging para ferramentas de monitoramento
+
+### Requirement 4: Error Handling Unificado
+
+**User Story:** Como desenvolvedor, eu quero um sistema de tratamento de erros consistente entre frontend e backend, para que eu possa lidar com erros de forma previsível e user-friendly.
+
+#### Acceptance Criteria
+
+1. WHEN ocorre um erro no backend THEN ele deve ser formatado de forma consistente com códigos de erro padronizados
+2. WHEN o frontend recebe um erro THEN ele deve ser tratado de forma consistente com mensagens user-friendly
+3. WHEN há erro de validação THEN as mensagens devem ser específicas e acionáveis
+4. WHEN ocorre erro de rede THEN deve haver retry automático e fallbacks apropriados
+5. WHEN há erro não tratado THEN deve ser logado adequadamente e não quebrar a aplicação
+
+### Requirement 5: Plugin System Aprimorado
+
+**User Story:** Como desenvolvedor, eu quero um sistema de plugins mais poderoso e flexível, para que eu possa estender o FluxStack facilmente com funcionalidades customizadas.
+
+#### Acceptance Criteria
+
+1. WHEN eu crio um plugin THEN deve haver uma API clara para hooks de lifecycle (onRequest, onResponse, onError, etc.)
+2. WHEN eu instalo um plugin THEN ele deve poder modificar configurações, adicionar rotas e middleware
+3. WHEN plugins interagem THEN deve haver um sistema de prioridades e dependências
+4. WHEN eu desenvolvo plugins THEN deve haver TypeScript support completo com tipos inferidos
+5. WHEN eu distribuo plugins THEN deve haver um sistema de descoberta e instalação simples
+
+### Requirement 6: Development Experience Melhorado
+
+**User Story:** Como desenvolvedor, eu quero uma experiência de desenvolvimento mais fluida e produtiva, para que eu possa focar na lógica de negócio ao invés de configurações.
+
+#### Acceptance Criteria
+
+1. WHEN eu inicio o desenvolvimento THEN o setup deve ser instantâneo com feedback claro do status
+2. WHEN eu faço mudanças no código THEN o hot reload deve ser rápido e confiável
+3. WHEN ocorrem erros THEN eles devem ser exibidos de forma clara no terminal e browser
+4. WHEN eu uso o CLI THEN os comandos devem ter help contextual e validação de parâmetros
+5. WHEN eu trabalho com APIs THEN deve haver ferramentas de debugging e inspeção integradas
+
+### Requirement 7: Performance Monitoring
+
+**User Story:** Como desenvolvedor, eu quero ferramentas de monitoramento de performance integradas, para que eu possa identificar e otimizar gargalos na aplicação.
+
+#### Acceptance Criteria
+
+1. WHEN a aplicação roda THEN deve coletar métricas básicas (response time, memory usage, etc.)
+2. WHEN eu acesso endpoints THEN deve haver logging de performance com timing detalhado
+3. WHEN há problemas de performance THEN deve haver alertas e sugestões de otimização
+4. WHEN eu uso em produção THEN deve haver dashboard básico de métricas
+5. WHEN integro com ferramentas externas THEN deve haver exporters para Prometheus, DataDog, etc.
+
+### Requirement 8: Gerenciamento de Estado Global
+
+**User Story:** Como desenvolvedor frontend, eu quero um padrão claro para gerenciamento de estado global, para que eu possa compartilhar estado entre componentes de forma eficiente.
+
+#### Acceptance Criteria
+
+1. WHEN eu preciso de estado global THEN deve haver uma solução integrada e type-safe
+2. WHEN o estado muda THEN os componentes devem re-renderizar automaticamente
+3. WHEN eu uso estado assíncrono THEN deve haver suporte para loading states e error handling
+4. WHEN eu persisto estado THEN deve haver integração com localStorage/sessionStorage
+5. WHEN eu debugo estado THEN deve haver ferramentas de inspeção integradas
+
+### Requirement 9: Configuração Avançada
+
+**User Story:** Como desenvolvedor, eu quero um sistema de configuração mais flexível e poderoso, para que eu possa customizar o comportamento do framework para diferentes cenários.
+
+#### Acceptance Criteria
+
+1. WHEN eu configuro o framework THEN deve haver validação de configuração com mensagens claras
+2. WHEN eu uso diferentes ambientes THEN as configurações devem ser carregadas automaticamente
+3. WHEN eu override configurações THEN deve haver precedência clara (env vars > config file > defaults)
+4. WHEN eu adiciono configurações customizadas THEN elas devem ser type-safe e documentadas
+5. WHEN eu valido configurações THEN deve haver schema validation com error reporting detalhado
+
+### Requirement 10: Tooling e Utilitários
+
+**User Story:** Como desenvolvedor, eu quero ferramentas e utilitários integrados que facilitem tarefas comuns de desenvolvimento, para que eu possa ser mais produtivo.
+
+#### Acceptance Criteria
+
+1. WHEN eu preciso gerar código THEN deve haver generators para controllers, routes, components, etc.
+2. WHEN eu faço deploy THEN deve haver comandos integrados para diferentes plataformas
+3. WHEN eu analiso o projeto THEN deve haver ferramentas de análise de bundle size e dependencies
+4. WHEN eu migro versões THEN deve haver scripts de migração automática
+5. WHEN eu trabalho em equipe THEN deve haver ferramentas de linting e formatting configuradas