Ferramentas de DX, Health Endpoint & Scripts
Ferramentas de DX & Endpoint de Saúde
Section titled “Ferramentas de DX & Endpoint de Saúde”Estado actual
Section titled “Estado actual”ship:all é o comando padrão de publicação (ship é seu alias): valida main limpo, busca o remoto e recusa divergência antes de alterar produção; falha no planejamento interrompe o fluxo. deploy:web impede publicações simultâneas no checkout, prepara um pacote temporário com o frontend aprovado e as Functions compiladas, e só confirma sucesso quando /api/deployment devolve o SHA completo esperado, sem cache. O pacote é removido ao terminar; o cache do frontend permanece reutilizável. Sondas HTTP têm timeout.
check:changed valida commits do ramo desde o ancestral de origin/main, alterações locais e arquivos novos: tipos dos projetos afetados, Biome nos arquivos tocados e testes relacionados com contratos de filesystem/subprocessos. Mudanças de infraestrutura/configuração/DB ou remoções usam testes completos; o comando não emite aprovação de publicação. check mantém a validação obrigatória, com cache separado para web, API e email-relay seguindo imports transitivos e configurações herdadas; uma regra compartilhada revalida cada consumidor. Quando o hash global de conteúdo, ambiente e artefatos coincide com a aprovação ainda válida, o check reaproveita o grafo já verificado sem reconstruí-lo; alteração de mesmo tamanho e timestamp também invalida pelo conteúdo. A validade das etapas e da suíte completa não é renovada. Check e publicação resumem tempos, execução e reaproveitamento.
test:web cobre src, test:api cobre functions/tests e test:tooling cobre scripts e o contrato de deploy web. O contrato de traduções indexa as referências entre aspas em uma passagem, mantendo a busca exata, os plurais e as exceções existentes. O Knip limita as entradas explícitas de testes às pastas ativas, pois esse tipo de glob ignora o .gitignore; checkouts auxiliares ficam fora e um teste executa a CLI real para preservar a detecção de exports mortos. Domínios evoluem com services/ para regras, api/ para integrações/cache, hooks/ para interface e tipos no domínio. Billing separa Xero/QuickBooks, scheduling separa a gravação da revisão de cancelamento, e payroll possui a lógica de transferências. Contratos impedem dependências de UI nos serviços já separados (billing, scheduling, payroll e banking), sem migração em massa dos demais módulos.
Esta seção descreve as otimizações de Developer Experience (DX) implementadas para acelerar o desenvolvimento local, auditar a infraestrutura e prevenir commits com erros.
⚡ 1. Execução Concorrente Única (npm run dev:all)
Section titled “⚡ 1. Execução Concorrente Única (npm run dev:all)”Para eliminar a necessidade de abrir múltiplos terminais manualmente durante o desenvolvimento:
npm run dev:all- Funcionamento: O
concurrentlyinicia simultaneamente o backend serverless Cloudflare (wrangler pages devna porta8788) e o frontend React (vitena porta3000), exibindo logs coloridos e isolados com encerramento automático das portas ao pressionarCtrl+C.
🩺 2. Endpoint de Diagnóstico da Infraestrutura (/api/health)
Section titled “🩺 2. Endpoint de Diagnóstico da Infraestrutura (/api/health)”O endpoint /api/health é público: só devolve status e latência por pilar (D1, IA, WhatsApp), sem nomear binding, modelo ou se o token da Meta existe. healthy em WhatsApp significa token da Meta configurado; degraded, que falta. O D1 em falha pode incluir details: "Database unreachable" — isso não é um segredo.
{ "status": "healthy", "timestamp": "2026-09-15T12:00:00.000Z", "totalLatencyMs": 14, "services": { "database": { "status": "healthy", "latencyMs": 4 }, "ai": { "status": "healthy", "latencyMs": 1 }, "whatsapp": { "status": "healthy", "latencyMs": 1 } }}🛡️ 3. Pre-commit Hook & Gerador de Migrações SQL
Section titled “🛡️ 3. Pre-commit Hook & Gerador de Migrações SQL”A. Pre-commit Git Hook (.githooks/pre-commit)
Section titled “A. Pre-commit Git Hook (.githooks/pre-commit)”Valida instantaneamente o estilo de código com Biome nos arquivos modificados antes de confirmar qualquer commit, impedindo que código fora de padrão alcance o repositório.
B. Gerador de Migrações (npm run db:migrate:new)
Section titled “B. Gerador de Migrações (npm run db:migrate:new)”Cria arquivos de migração com numeração e nome padronizados:
npm run db:migrate:new add_client_tagsAPI dos veículos. /api/car/overview exige ADMIN/MANAGER, consulta da meia-noite de Londres até a próxima (inclusive em dias de mudança de horário) e exibe horas de Londres. Os testes cobrem uma visita cuja data UTC é a véspera e excluem a meia-noite do dia seguinte. Os testes JVM Android usam org.json real apenas na dependência de teste, porque o parser do SDK é um stub nesse ambiente.
🔍 4. Pipeline de Integridade e Qualidade (npm run check)
Section titled “🔍 4. Pipeline de Integridade e Qualidade (npm run check)”Antes do push e do deploy, o comando corre as etapas cuja entrada mudou. Na última hora, uma etapa com a mesma entrada não repete; para testes idênticos, o recibo vale até 24 horas, sempre limitado pela idade da última suíte completa. Cada etapa tem o seu próprio horário de execução: reaproveitá-la não renova a validade. O check informa o tempo de cada etapa para identificar gargalos. Mudança cirúrgica: depois de uma suíte completa aprovada, o Vitest compara hashes dos arquivos com a última entrada validada (inclui alterações ainda sem commit) e executa os testes afetados pelo grafo transitivo de imports. Leitores de arquivos entram também: quando a leitura tem caminho estático, uma mudança nesse arquivo/diretório aciona o leitor; leitura dinâmica, subprocesso ou import calculado permanece na seleção conservadora. O schema compartilhado do D1 não obriga todos os testes de backend a rodarem numa edição de UI. Um erro nunca avança o snapshot. Sem baseline válido, com arquivos removidos, dependências/configuração/DB alterados ou depois de 24 horas desde a última suíte completa, todos os testes rodam. Arquivos novos entram na seleção por imports e nas verificações conservadoras de leitura de arquivos/subprocessos, sem forçar a suíte inteira só por terem sido criados. npm run test continua completo e check:full força tudo. A validade da baseline completa não é renovada por execuções parciais. O Vitest usa até quatro workers em threads (limitado à metade das CPUs) e conserva o isolamento entre arquivos; evita iniciar um processo Node por arquivo, sem excluir testes. O recibo guarda NODE_ENV, VITE_* e npm_config_*, por isso o push e o deploy:web partilham-no; o resto do ambiente da shell não o invalida. O deploy:web espera o /api/boot responder 401, como já espera o HTML novo. Tipos, lint, formatação, código morto, testes e auditoria correm juntos; o build do bundle corre depois. A auditoria segue o lockfile e o manifesto de instalação do npm (node_modules/.package-lock.json), não cada ficheiro dentro de node_modules. O build segue o app cliente: código em functions/ ou email-relay/, migrações em db/, testes e documentação não o reconstróem. A documentação e os arquivos Android/iOS correm os testes, porque há contratos que os leem. O typecheck usa aprovações independentes por projeto e caches incrementais separados para app, Functions, email-relay e chat-redirect em node_modules/.cache/, sem emitir JavaScript. npm run check:full força todas as etapas. No meio de uma tarefa, o que se corre é o typecheck do projeto tocado, o Biome nos ficheiros tocados e o vitest dos testes que os cobrem.
npm run check- TypeScript (
npm run typecheck): Validação estrita de tipos para o frontend (src/) e backend Cloudflare (functions/). - Biome Linter (
npm run lint): Auditoria de qualidade de código, padrões de acessibilidade (a11y) e regras de navegação. - Deadcode Scanner (
npm run deadcode): Detecção de arquivos, dependências e exportações não utilizadas viaknip. - Vitest (
npm run test): Execução da suíte completa de testes unitários e de integração, sem seleção incremental.
🚀 5. Scripts Desacoplados e Pipeline Unificado (npm run ship:all)
Section titled “🚀 5. Scripts Desacoplados e Pipeline Unificado (npm run ship:all)”Para acelerar drasticamente o ciclo de feedback e eliminar esperas durante o desenvolvimento e publicação:
Comandos Granulares de Desenvolvimento
Section titled “Comandos Granulares de Desenvolvimento”npm run typecheck:web: Validação incremental rápida de tipos TypeScript apenas no frontend SPA (src/).npm run typecheck:api: Validação incremental de tipos nos endpoints (functions/).npm run typecheck:email/typecheck:redirect: Validação incremental dos Workers correspondentes.npm run check:changed: Feedback de desenvolvimento para a mudança atual, sem substituir o gate de publicação.npm run test:web: Executa apenas a suíte de testes de interface e componentes web (src/, ~582 arquivos em ~40s).npm run test:api: Executa a suíte de endpoints de backend e contratos de API (functions/etests/, ~629 arquivos).
Pipeline de Publicação Contínua (npm run ship:all)
Section titled “Pipeline de Publicação Contínua (npm run ship:all)”Comando padrão para publicar o necessário (npm run ship é um alias):
- Exige main limpo, busca origin/main e tags e recusa divergência antes de qualquer alteração remota. Verifica se há migrações D1 ou Workers pendentes (
check-backend-deploy.mjs). - Se houver pendências de backend, executa
deploy:backendautomaticamente (com auto-confirmação não interativa de migrações D1). - Envia os commits para o GitHub (
git push origin main). - Publica o pacote de assets e Functions (
deploy:web) e confirma HTML, SHA da API e autenticação no domínio, com sondas limitadas por timeout. - Mostra tempo de backend, push, web e total;
checkmostra etapas executadas e reaproveitadas.