# Wizards e Tools — Visao Geral

v2.31.0+: o Wizard CLI agora roda pre-flight antes de qualquer pergunta e limita o fluxo interativo a 5 perguntas no maximo (greenfield Dockerfile-only = 2 perguntas, <60s).

O Runner oferece duas ferramentas auxiliares pra ajudar voce a chegar no primeiro deploy. Use a tabela abaixo pra escolher qual aplica ao seu caso.

# Comparacao rapida

# Casos de uso comuns

# Cenario 1: comecando do zero (repo cru, sem Docker)

Recomendado: Wizard CLI roda pre-flight e, se o repo nao tem Dockerfile nem docker-compose, exibe um template mínimo pra voce adicionar antes de rodar de novo (ver Cenario 5 abaixo).

# Cenario 2: tenho um Dockerfile + .env, quero auto-detectar

Recomendado: Wizard CLI. Detecta EXPOSE (port), FROM (image), variaveis em .env (com classificacao automatica de secrets como *_PASSWORD, *_TOKEN, etc).

runner wizard --path /caminho/repo
# Pre-preenche tudo que conseguiu detectar, voce so confirma

# Cenario 3: tenho docker-compose com multiplos services

Recomendado: Migrar docker-compose pro runner (v2.26.0+) — runner wizard --from-compose gera N .deploy.yml (um por service), com merge de overrides via -f base.yml -f prod.yml e wizard-answers.yml pra suportar runner reconcile quando o compose mudar upstream.

# Cenario 4a: automacao/CI/IA gerando manifestos (v2.18.0+)

Recomendado: `runner wizard --answers `. JSON com respostas substitui prompts interativos. Detection roda primeiro, answers sobrescrevem.

runner wizard --path . --answers answers.json --dry-run --json

Permite IA/script gerar .deploy.yml em uma chamada, sem TTY. Schema completo na referencia do wizard CLI.

# Cenario 4: ja tenho `.deploy.yml`, so preciso encriptar secrets

Recomendado: Secrets Web Tool. Tool no navegador que gera .runner/secrets.enc 100% client-side (Web Crypto API). Util quando:

• Voce nao quer instalar runner so pra criar uma ckey
• Quer auditar o codigo de criptografia (Ctrl+U)
• Quer rotacionar a ckey periodicamente

# Cenario 5: `runner add` falhou com `no_deploy_yml`

Automatico (v2.31.0+): o CLI roda pre-flight antes de qualquer pergunta. Se o repo nao tem Dockerfile nem docker-compose, exibe bail com template minimo e instrucoes:

$ runner add --repo user/repo --branch main
[runner] Cloning shallow...
Error: preflight_no_docker: repo nao tem Dockerfile nem docker-compose.yml.
       Adicione um Dockerfile minimo e rode novamente:

         FROM nginx:1
         EXPOSE 80
         COPY . /usr/share/nginx/html/

       Documentacao: https://docs.runner.ccs.systems/getting-started

Em pipe/non-TTY/--json, falha direto sem travar em prompt.

# Compatibilidade entre ferramentas

As duas geram arquivos com formato identico ao que o Runner ja decifra/lê em producao:

• .deploy.yml — schema v1.0 (mesmo do runner add/runner deploy)
• .runner/secrets.enc — AES-256-GCM com chave SHA-256(ckey), layout [12 bytes nonce][N bytes ciphertext]

Voce pode misturar: por exemplo, gerar .deploy.yml pelo Wizard CLI e depois re-encriptar .env pelo Secrets Web Tool, commitar ambos no repo, e o runner add --ckey "<sua-ckey>" no servidor restaura tudo automaticamente.

# Fluxo recomendado pra primeiro deploy

1) runner wizard --path /caminho/repo
   |
   +- Repo tem Dockerfile/compose? Sim => detecta tudo, poucas perguntas
   +- Nao => bail com template minimo (adicione Dockerfile e rode de novo)
                |
                +- Resultado: .deploy.yml gerado (e .runner/secrets.enc, se --ckey)

2) git add .deploy.yml [.runner/secrets.enc]
   git commit -m "chore: add runner config"
   git push

3) No servidor com runner instalado:
   runner add --repo user/repo --branch main [--ckey "<ckey>"]

# Ver tambem

• `runner wizard` (CLI) — referencia completa do subcomando
• Secrets Web Tool — encripta .env 100% client-side
• Wizard — pre-flight + signals — como o wizard decide quais perguntas fazer
• Secrets lifecycle — visao geral da arquitetura mkey/ckey