Script de configuração do primeiro dia que se verifica sozinho: bootstrap, doctor e smoke test

Objetivo

Uma pessoa recém-chegada ao projeto, ou um agente, executa um único comando após clonar o repositório e termina com um ambiente funcional ou com uma lista precisa do que falta e de como corrigir. Ao executar o comando de novo, ele informa que não há nada a fazer.

Pré-requisitos

Uma lista do que o projeto precisa: runtimes e suas versões, gerenciadores de pacotes, bibliotecas do sistema, serviços (banco de dados, cache), credenciais e a origem delas, e, para cada item, uma verificação que comprove que ele está presente. O padrão "Scripts To Rule Them All", do GitHub, fornece a divisão que esta metodologia segue: script/bootstrap serve exclusivamente para satisfazer as dependências do projeto, script/setup coloca o projeto em seu estado inicial após um clone, script/update roda após um pull e script/test executa a suíte de testes. O comando doctor do Homebrew, descrito em sua manpage como uma verificação do sistema em busca de possíveis problemas, com saída diferente de zero caso encontre algum, é o modelo para a metade de verificação.

Passos

1. Escreva primeiro o script doctor: uma verificação somente leitura que imprime uma linha por requisito com PASS, FAIL ou WARN, o valor encontrado, o valor esperado e o comando de correção. Ele não altera nada e termina com status diferente de zero diante de qualquer FAIL.
2. Escreva o bootstrap como uma sequência de passos idempotentes, cada um protegido pela verificação correspondente do doctor: instale apenas o que falta, obtenha as versões do manifesto de versões do repositório e ignore o que já está correto.
3. Termine o bootstrap executando o doctor e, depois, um smoke test: o alvo de teste mais rápido, o --help do binário compilado ou uma requisição ao endpoint de saúde local. O status de saída do script é o do smoke test.
4. Torne todos os passos não interativos; prompts bloqueiam agentes e o CI. Leia as credenciais de variáveis de ambiente ou de um arquivo documentado e relate a ausência delas como um FAIL com um link, não como um prompt.
5. Imprima o que foi feito e quanto tempo levou, e grave o mesmo em um arquivo de log que uma execução com falha possa anexar a um relatório de bug.
6. Execute o bootstrap em uma máquina ou um contêiner limpo no CI, de forma agendada; um script de configuração que só os recém-chegados executam se deteriora entre um recém-chegado e outro.
7. Trate a falha de cada recém-chegado como um bug no doctor: se nenhuma verificação a detectou, adicione a verificação antes de corrigir o ambiente.

Resultado esperado

As falhas de configuração passam a ser específicas ("PostgreSQL 16 esperado, 14 encontrado; execute o comando de atualização indicado") em vez de um stack trace vindo do primeiro comando que precisou da peça ausente.

Limites e base de verificação

O custo é a cobertura de plataformas: cada sistema operacional suportado exige que suas verificações e correções sejam mantidas. O script não consegue verificar o que não consegue observar (uma VPN, uma permissão concedida em outro lugar); só consegue constatar que uma sondagem falhou. Este é um protocolo proposto; não se afirma nenhum resultado de adoção nem de tempo.