wizard

O que wizard faz?

Um wizard é um script bash que guia um humano, passo a passo, por um procedimento manual tedioso de fazer à mão e tedioso de reexplicar a uma IA toda vez. Ele abre cada URL, diz exatamente o que clicar e copiar, captura os valores, escreve onde pertencem (.env, segredos do GitHub), confirma em cada estágio e mostra quantos estágios faltam. Pode configurar serviços de terceiros, executar uma migração única ou mover o projeto de um estado para outro.

A UX agradável já está resolvida por template.sh: progresso etapa por etapa, portões de confirmação, abertura de URL multiplataforma (incluindo WSL), entrada oculta para segredos, upserts idempotentes em .env, gravações em gh secret/gh variable e um resumo final. Seu trabalho é apenas escopar o procedimento e escrever suas etapas. A biblioteca acima do marcador STAGES é idêntica em todo wizard; essa consistência é o ponto: nunca edite manualmente.

Um wizard é efêmero por padrão: construído para uma execução, salvo em um caminho scratch/ ou scripts/, deletado quando o trabalho termina. Faça commit somente quando o usuário quiser um caminho de configuração repetível que deve viver no repositório.

Processo

1. Escopar o procedimento

Descubra cada etapa manual que o humano deve realizar e cada valor que será capturado ao longo do caminho. Leia o repositório primeiro, não pergunte frio:

• Para configuração: .env, .env.example, .env.*, README, docker-compose*, config do framework e .github/workflows/* (cada referência a secrets.* / vars.* é um valor que o wizard deve produzir).
• Para uma migração ou transição: o estado atual, o estado alvo e as ações irreversíveis entre eles.

Depois mostre ao usuário a lista ordenada de etapas e os valores que cada uma produz, e confirme: eles podem adicionar, remover ou reordenar.

Concluído quando: cada etapa está nomeada em ordem, e para cada valor capturado você sabe (a) onde o humano o obtém, (b) onde é escrito (.env, um segredo do GitHub, ambos, ou nenhum lugar; algumas etapas são apenas ações), e (c) se é secreto (entrada oculta) ou público.

2. Mapear a jornada de cada etapa

Para cada etapa, escreva o caminho preciso que um humano segue: qual URL abrir, o que fazer lá, onde um valor é mostrado, qual variável ele preenche: por exemplo, "Dashboard → Desenvolvedores → Chaves de API → Revelar chave de teste → copiar". Onde você não souber a interface atual ou o comando exato, diga isso e pergunte ao usuário ou verifique a documentação: nunca invente etapas que podem não existir.

Concluído quando: cada etapa traça instruções concretas que um estranho poderia seguir.

3. Escrever o wizard

Copie template.sh para o caminho alvo. Substitua a etapa de exemplo por uma stage por passo, em ordem de dependência. Use as funções auxiliares da biblioteca: stage, say/step, open_url, ask/ask_secret, write_env, set_secret/set_var, pause/confirm. Defina TOTAL_STAGES com o número de etapas que você escreveu.

Mantenha o padrão que o template define: abra a URL antes de perguntar pelo valor, use ask_secret para qualquer coisa secreta, write_env para todo valor persistido, set_secret apenas para os valores que o CI realmente precisa, e confirm antes de qualquer ação irreversível. Cada stage limpa a tela para que apenas a etapa atual seja visível: mantenha uma etapa focada em uma única tarefa para que nada que o humano precise role para fora. Não toque na biblioteca acima do marcador.

4. Verificar e entregar

• bash -n <script>; execute shellcheck se disponível.
• chmod +x <script>.
• Não execute o script de ponta a ponta você mesmo: ele abre navegadores e bloqueia em entrada humana. Em vez disso, trace-o estaticamente: verifique se cada valor da etapa 1 é capturado e chega onde a etapa 1 disse, e se cada set_secret corresponde exatamente a uma referência secrets.* no CI.
• Diga ao usuário como executá-lo. Se for um caminho de configuração repetível, faça commit e adicione um link no README para que a próxima pessoa execute o script em vez de perguntar a uma IA.