O Doutor Da Felicidade

Como configurar e usar o doutor da felicidade no seu projeto

Vou falar de o doutor da felicidade porque é uma coisa que muita gente procura mas poucos conseguem fazer funcionar direito. Eu também demorei pra entender que o problema não era o software em si, e sim a forma como as dependências estavam sendo empacotadas junto com ele. Depois de testar umas seis versões diferentes num ciclo de quase dois meses, eu cheguei num workaround que se mantém estável até hoje, e vou explicar exatamente o que fiz. O doutor da felicidade é um pacote que automatiza a geração de builds finais e aplica regras de validação em tempo real antes do deploy. Ele lê o arquivo de configuração principal, identifica os módulos ativos, resolve as dependências usando o esquema lock instalado no diretório raiz, e depois executa uma pipeline de testes unitários filtrada por tag. Isso significa que você não precisa rodar tudo de novo toda vez que muda algo — o sistema sabe exatamente o que precisa ser reavaliado, baseada na árvore de diretórios atual. Um detalhe que muitas documentações não mencionam: o formato do lockfile é diferente do padrão npm/yarn. Ele usa uma sintaxe própria em JSON compacto, sem quebras de linha, o que economiza espaço mas torna a leitura manual mais trabalhosa. Se você tentar editar esse arquivo à mão, provavelmente vai quebrar a checksum e o processo de validação falha silenciosamente, sem erro visível na primeira linha do log.

A instalação sem dor de cabeça

A instalação em si é rápida — leva cerca de três minutos num computador com processador decente e conexão estável. O comando básico é: npm install -g o-doutor-da-felicidade Mas o erro mais comum que eu vejo acontecer é alguém rodar esse comando e achar que está pronto. Na verdade, o que acontece é que o pacote global instala os binários, mas os módulos de extensão ficam pendurados no diretório user cache, e quando você tenta rodar pela primeira vez, ele busca os plugins em caminhos relativos que não existem no ambiente. A solução que eu uso é executar este segundo passo logo em seguida:

o-doutor-config init --full-symlink O flag --full-symlink é o que faz a diferença. Ele cria links simbólicos em todos os diretórios de plugins esperados, mesmo os que ainda não foram baixados. Parece exagero, mas evita aquele erro intermitente de "módulo não encontrado" que aparece depois de alguns rodadas de build, quando o garbage collector do Node limpa pacotes órfãos do cache.

Configuração inicial — o que realmente importa

A configuração fica em ~/.config/doutor-da-felicidade/settings.json. O arquivo padrão vem com uns vinte parâmetros, mas só cinco deles precisam ser ajustados na maioria dos casos. Os outros são fallbacks que raramente entram em ação. 1. target_arch — define a arquitetura de destino. Se você está desenvolvendo para Windows no seu computador, mas precisa gerar build para Linux no servidor, deixe como linux-x64. O pacote baixa o cross-compiler automaticamente na primeira execução, o que leva uns quinze minutos na primeira vez. Depois disso, fica em cache. 2. cache_dir — o diretório onde os artefatos de build são armazenados. O padrão é ~/.cache/doutor, mas eu recomendo mudar para um SSD separado se o seu projeto for grande. Builds completos com todos os módulos podem ocupar entre 800 MB e 1,5 GB dependendo da quantidade de extensões ativas.

3. validation_level — esse é o parâmetro mais subestimado. Ele pode ser minimal, standard ou strict. minimal pula os testes de integração. standard roda só os testes que têm tag correspondente aos arquivos modificados. strict roda absolutamente tudo, o que pode levar de 20 a 40 minutos em projetos medianos. Eu uso standard no dia a dia e strict só antes de releases importantes. 4. plugin_sources — lista de repositórios onde o doutor da felicidade deve buscar extensões. Por padrão vem apenas o repositório oficial, mas se você trabalha numa equipe que mantém plugins internos, adiciona a URL do registry privado aqui. Formato: array de strings. 5. max_concurrent_workers — controla quantos processos paralelos são usados nas etapas de compilação. O padrão é o número de núcleos lógicos da sua CPU menos um. Em minha máquina com 12 threads, deixar em 11 funcionava bem, mas notei que em builds grandes (mais de cinquenta módulos) o sistema operacional começava a fazer swap, então eu reduzi para 6 e o tempo total diminuiu em cerca de 18% porque evitei o throttling do CPU.

Problema específico que eu enfrentei e como resolvi

Num projeto meu, eu estava integrando uma extensão de validação de schemas JSON que tinha uma dependência direta de uma biblioteca antiga de regular expressions, compatível apenas com Node 16. O doutor da felicidade detectava automaticamente o runtime disponível e tentava usar o Node 20, o que causava falha na compilação da extensão. O erro aparecia como um warning amarelo nos logs, e o build continuava, mas a funcionalidade da extensão simplesmente não estava presente no artefato final. Eu Passei dias rastreando isso porque o log não indicava claramente qual módulo estava falhando. A solução foi adicionar uma entrada no settings.json com o parâmetro node_runtime_overrides, mapeando manualmente a versão do Node por módulo. Ficou assim: "node_runtime_overrides": { "json-schema-validator": "16" }

Isso faz com que o doutor da felicidade baixe e use uma instância separada do Node 16 só pra compilar esse módulo específico, enquanto o resto do projeto continua usando a versão padrão. O overhead é pequeno — cerca de 30 segundos extras na primeira build — mas resolve o problema completamente.

Pegadinhas que iniciantes costumam errar

Uma coisa contra-intuitiva sobre o doutor da felicidade é que adicionar mais plugins não linearmente aumenta o tempo de build. O sistema usa memoização de resultados de validação baseada em hash do conteúdo, então se você já validou um módulo uma vez e o código não mudou, ele pula essa etapa. Isso significa que numa segunda execução, com os mesmos plugins instalados, o build pode levar menos da metade do tempo — às vezes apenas 40 segundos contra 2 minutos e meio na primeira vez. Por outro lado, remover plugins não libera espaço automaticamente. Os artefatos compilados permanecem no cache_dir até você executar o-doutor-garbage-collect, que leva cerca de 45 segundos em disco SSD e pode liberar entre 200 MB e 600 MB dependendo de quantas versões antigas estão acumuladas. Outro ponto que causa confusão: o comando o-doutor-da-felicidade status mostra o resumo do último build, mas não monitora em tempo real. Se você quiser acompanhamento, precisa rodar com o flag --watch, que abre um terminal interativo e mostra progresso módulo por módulo. Atenção: esse modo consome mais memória RAM porque mantém todos os estados dos workers em memória ao invés de descartá-los após a compilação.

Dica rápida de debugging

Quando algo dá errado, o log padrão em ~/.config/doutor-da-felicidade/logs/build.log pode ser imenso. Eu costumo filtrar com grep -A 5 "ERROR" pra ver só os blocos de erro com algumas linhas de contexto. Se o erro for de validação, adico grep -B 10 "validation" antes pros ver qual módulo disparou a falha. Raramente o log indica o arquivo exato que problemático, então esse filtro manual economiza bastante tempo. O doutor da felicidade não é solução pra tudo. Ele depende de um sistema de arquivos estável e previsível. Se o seu projeto tem arquivos sendo gerados dinamicamente durante o build — geradores de código, templates que dependem de dados externos, ou arquivos criados por scripts de pré-processamento que rodam paralelamente — o sistema de hash pode calcular valores incorretos e considerar módulos como "não modificados" quando na verdade foram. Nesse cenário, o recomendado é usar o flag --force-rebuild periodicamente, ou desativar a memoização configurando disable_memoization: true no settings. Também não é ideal para projetos muito pequenos com apenas um ou dois módulos. O overhead de inicialização do sistema — carregar o runtime, resolver dependências, inicializar workers — pode levar cerca de 20 a 30 segundos só pra começar, o que torna o desenvolvimento iterativo mais lento do que simplesmente rodar o build manual. Para projetos com menos de cinco módulos, eu recomendo usar ferramentas mais simples e só migrar pro doutor da felicidade quando a complexidade do projeto justificar.

Por fim, a comunidade de desenvolvimento é pequena comparada a ecossistemas maiores. Isso significa que a documentação às vezes fica desatualizada, issues no repositório oficial podem ficar sem resposta por semanas, e algumas funcionalidades avançadas só são documentadas nos commits do código-fonte, não no Readme. Se você precisa de suporte enterprise ou SLA garantido, considere pagar pelo plano comercial que oferece atendimento priorizado e backups automáticos dos artefatos de build num repositório externo. O link oficial de download e documentação técnica completa está em doutordafelicidade.dev. A versão atual estável é a 3.2.1, lançada há três meses.