wreck-it

wreck-it: Arruine seu aplicativo antes que seus usuários o façam

WRECK abaixo significa npx @miyanishar/wreck-it. O CLI faz o trabalho determinístico (configuração, descoberta, varreduras, fuzzing, velocidade de página, carga, descobertas, pontuação, relatório, testes). Você dirige o navegador através do Playwright MCP, interpreta as personas, julga o que é um bug e o rastreia até o código.

Relatório apenas. Não corrija bugs durante uma execução a menos que o usuário peça após o relatório.

Regras (sempre)

• Apenas local. O CLI recusa alvos não locais. Passe --i-own-this apenas quando o usuário disser que possui um remoto.
• Apenas dados falsos. Contas de teste, nomes falsos, nunca dados pessoais ou de pagamento reais. Nomeie o que criar como wreck-it … e registre: WRECK run created "<o que>" --by <persona> (o relatório lista para limpeza).
• Pergunte antes de escrever. O safety.ask do preflight lista as perguntas: um banco de dados hospedado (geralmente produção), chaves Stripe ao vivo, e-mail sem caixa de entrada legível, chamadas de AI/SMS pagas. Faça todas em uma mensagem antes da passagem de usuário normal e registre cada "sim" em .wreck-it/config.json (allowRemoteDb, testEmail, allowSideEffects). Se o banco de dados for de produção, ofereça parar para que eles apontem o app para um projeto de desenvolvimento.
• Dinheiro e mensagens. Pague apenas com chaves de teste Stripe (cartão 4242 4242 4242 4242); com chaves ao vivo pare na etapa de pagamento. Acione ações de AI/SMS/e-mail no máximo 2–3 vezes por fluxo, a menos que permitido. fuzz e load pulam esses endpoints automaticamente.
• E-mail. Cadastre-se com endereços de WRECK email new, nunca example.com. Com uma caixa de entrada local, leia o link você mesmo (WRECK email read --to <endereço>); caso contrário, peça ao usuário ou marque a verificação como "pulada: sem caixa de entrada legível".
• Mantenha o login compartilhado ativo. Nunca faça logout, exclua ou altere a senha da conta cuja sessão salva outros estágios usam: no Supabase e em muitos apps, fazer logout encerra todas as sessões daquele usuário. Teste logout e exclusão por último, com uma conta descartável.

Execução focada (um recurso)

Quando o usuário nomear um recurso ou fluxo ("teste o checkout", "/wreck focus signup"), teste apenas isso, em minutos:

1. WRECK run init --focus "<recurso>", WRECK discover, WRECK setup --dry-run e WRECK preflight --wait 5, tratados como no estágio 1. Faça login (estágio 2) apenas se o recurso precisar. Faça perguntas safety.ask apenas se o recurso escrever dados.
2. Escopo. A partir de discovery.json e do código, liste as páginas e rotas de API do recurso (ex.: /cart, /checkout, /api/cart, /api/orders). Diga ao usuário o escopo em uma linha.
3. Teste-o (pule personas e estágios que não se aplicam; marque-os como skipped):
   • Percorra o recurso como um usuário normal, depois como um iniciante apressado em um telefone (cliques duplos, formatos errados, voltar no meio do fluxo). Verifique as linhas da checklist da skill explore que se aplicam (totais, persistência, exclusões, mensagens de erro).
   • WRECK sweep --record --only <páginas…> e WRECK fuzz --record --only <rotas de api…>.
   • As entradas hostis da skill chaos, envios duplicados, falhas de navegação e rede, apenas nos formulários deste recurso.
   • WRECK perf --record <páginas…> se o recurso tiver suas próprias páginas.
4. Reproduza e rastreie cada descoberta (estágio 9), então WRECK report && WRECK gen-tests. O relatório é rotulado como execução focada: diga "pontuação do recurso", não "prontidão".

Pipeline

Marque estágios com WRECK run stage <estágio> running|done|skipped|failed. As descobertas são salvas conforme você avança.

1. Configuração e preflight

WRECK run init               # --fresh descarta descobertas de uma execução anterior
WRECK discover
WRECK setup --dry-run        # o que está instalado, o que falta
WRECK preflight --wait 5

• Se setup --dry-run listar algo para instalar, mostre e pergunte uma vez; se sim, execute WRECK setup. Se adicionou servidores MCP, as ferramentas do navegador aparecerão apenas após o usuário reiniciar o agente: diga isso e ofereça uma execução apenas com CLI enquanto isso.
• Uma ferramenta de navegador dizendo "Browser … is not installed": WRECK setup --skip playwright-mcp devtools-mcp, depois tente novamente.
• Preflight saída 4 (app não acessível): ofereça iniciar devScript em segundo plano, depois WRECK preflight --wait 60. Saída 3 (alvo recusado): pare e explique.
• Sem .wreck-it/config.json: crie {"baseUrl": "http://localhost:3000"} (use a porta real).
• Execução apenas com CLI (sem ferramentas de navegador): sweep --record, fuzz --record, perf --record, estágio 7 e o relatório; marque personas, normal, explore, chaos como pulados e diga o motivo. Nunca finja que clicou pelo aplicativo.

2. Fazendo login

• Google, GitHub, SSO, login hospedado, magic links, 2FA (discovery.json auth.sso está definido, ou não há campo de senha): diga ao usuário "Uma janela do navegador será aberta. Faça login como seu usuário de teste; ela se fechará sozinha quando você terminar." Execute WRECK login (aguarda até 10 minutos; use um timeout longo). Sua saída deve dizer check: valid. Para verificações com dois usuários, peça WRECK login --label second; para verificações de conta nova --label fresh, ou marque-as como puladas.
• E-mail e senha: cadastre uma conta de teste (ou use a do usuário) e adicione "accounts": [{"label": "main", "email": "…", "password": "…"}] ao config.
• A partir daí: sweep, fuzz e perf fazem login sozinhos. No navegador, chame browser_set_storage_state com {"filename": ".wreck-it/auth/<label>.json"} antes de visitar páginas que exigem login. Descobertas registradas enquanto logado recebem "auth": "<label>" e etapas que começam após o login.
• Se preflight ou WRECK login --check disser expired, peça ao usuário para executar login novamente.

3. Personas

Use a skill wreck-personas.

4–5. Usuário normal, depois personas

Use a skill wreck-explore. No Claude Code com o plugin, execute até 3 personas em paralelo como subagentes wreck-persona, um navegador cada (wreck-browser-1..3); não use um navegador você mesmo enquanto isso e aguarde todos antes do estágio 6. Outros agentes: uma persona após a outra.

6. Caos

Use a skill wreck-chaos (varredura, fuzz de API, entradas hostis, envios duplicados, navegação, falhas de rede, adulteração de sessão, teclado).

7. Velocidade de página e carga

Use a skill wreck-load.

8. Segurança

Não está na v1: WRECK run stage security skipped.

9. Reproduzir, depois rastrear

WRECK finding list: reproduza cada descoberta ? em um contexto novo e defina reproduced: true se ela aparecer novamente (descobertas não reproduzidas não pontuam). Em seguida, use a skill wreck-trace em cada descoberta reproduzida sem source.

10. Relatório

Antes de gerar o relatório, verifique cada descoberta de navegador reproduzida para uma captura de tela que mostre a falha real. Revise também descobertas de varreduras CLI; siga a orientação de captura de tela em references/recording-findings.md. Verifique se os arquivos de imagem salvos existem e resolva quaisquer avisos de captura de tela ausente. Descobertas apenas de API ou carga podem usar evidências de requisição/métrica; diga quando uma captura de tela não é aplicável ou não pôde ser capturada.

Gere o relatório e os testes após a última atualização de descoberta. Se você alterar uma descoberta depois, regenere ambos antes de apresentar os resultados. Leia references/regression-tests.md: inspecione avisos de especificação preservada e reconcilie esses testes com as descobertas atualizadas; a regeneração mantém deliberadamente edições do agente e fixtures. Execute as especificações suportadas contra o aplicativo com bugs e verifique se as falhas atingem as asserções pretendidas. Divulgue pulos, falhas de configuração, timeouts ou testes não verificados no relatório; onde existir uma cópia corrigida, verifique as mesmas especificações contra ela também.

WRECK report && WRECK gen-tests && WRECK run stage report done

Enquanto explora (estágios 4–6)

• Registre bugs exatamente como em references/recording-findings.md: WRECK finding add, etapas estruturadas, alvos de função/rótulo, asserções que descrevem o comportamento correto, depois reproduza em um contexto novo e defina reproduced: true.
• Após cada navegação, execute o script de anomalia (WRECK oddity-script, uma vez) via browser_evaluate e verifique browser_console_messages e browser_network_requests (4xx/5xx). Também procure o que scripts não podem julgar: layout quebrado, estados vazios sem orientação, spinners infinitos, botões mortos, datas ou preços inconsistentes. Registre os reais como oddity.
• Registre cobertura: WRECK run visit <rota> --persona <nome>.

Mensagem final

Resumida: a pontuação e a faixa, a descoberta "corrija isto primeiro" com seu file:line, contagens por gravidade, estágios incompletos, os caminhos .wreck-it/report.html, .wreck-it/report.md, tests/wreck-it/, e npx playwright test tests/wreck-it. Ofereça para corrigir as principais descobertas; aguarde um sim.

Ao apresentar um bug, anexe sua captura de tela relevante ao lado do ID da descoberta e explicação. Use o suporte de anexo de imagem do chat ou uma imagem Markdown com o caminho real do arquivo salvo; apenas um caminho de relatório não mostra a evidência. Apresente as principais descobertas no chat com suas capturas de tela e mantenha o conjunto completo nos relatórios. Se uma imagem não estiver disponível ou não for aplicável, diga o porquê e vincule a requisição, o rastreamento ou as métricas. Resolva caminhos shots/... armazenados relativos a .wreck-it/.

Use esta forma para cada descoberta de navegador que você incluir no chat (substitua o exemplo pela descoberta real e caminho absoluto de imagem verificado):

**WR-007 — Subtotal do carrinho ignora quantidade** (`lib/cart.ts:19`)
Três itens de $79.99 devem totalizar $239.97; a página mostra $79.99.
![WR-007: quantidade 3 com subtotal incorreto](/caminho/absoluto/do/projeto/.wreck-it/shots/WR-007-cart.png)

Antes de enviar, abra cada imagem que planeja apresentar e descreva o estado e os valores que ela realmente mostra. Verifique se cada descoberta de navegador que você apresenta tem um anexo de imagem ou incorporação de imagem. Uma lista de nomes de arquivos de imagem ou uma declaração de que as capturas de tela estão salvas não é um anexo. Mantenha a resposta concisa apresentando menos descobertas, com suas evidências, e vinculando o relatório completo; deixe as descobertas de navegador restantes nesse relatório em vez de adicionar uma lista não ilustrada no chat.