# Wizards e Tools — Visao Geral

O Runner oferece tres 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 Web ou Wizard CLI — qualquer um funciona. O CLI vai detectar arquivos automaticamente se voce os adicionar (Dockerfile, etc); o Web vai te perguntar tudo manualmente.

# 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: Wizard CLI — pergunta qual service e o app principal e marca redis/postgres/mysql como assets (que precisam ser deployados separadamente).

# 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: o CLI ja te oferece o wizard quando detecta perfil cru (E):

$ runner add --repo user/repo --branch main
[runner] Cloning shallow...
⚠ Repositorio sem perfil de deploy detectado.
? Executar wizard interativo agora? [Y/n]

Aceita -> wizard guia a configuracao -> runner add continua. Recusa -> falha com mensagem instrutiva. Em pipe/non-TTY/JSON, falha direto sem travar em prompt.

# Compatibilidade entre ferramentas

Todas as tres 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 Web e depois 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) Repo do projeto: tem Dockerfile? Tem docker-compose?
   |
   +- Sim => Wizard CLI (detecta tudo)
   +- Nao => Wizard Web (formulario manual)
                |
                +- Resultado: .deploy.yml gerado
                       |
                       +- Tem secrets sensitive (DB_PASSWORD, JWT_SECRET, etc)?
                              |
                              +- Sim => Secrets Web Tool (encripta)
                              +- Nao => commita .deploy.yml direto

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
• Wizard Web — formulario interativo no navegador
• Secrets Web Tool — encripta .env 100% client-side
• Generator de .deploy.yml — geracao automatica nao-interativa (perfis A-D, usado internamente pelo runner add)
• Secrets e Encriptacao — visao geral da arquitetura mkey/ckey