wreck-it

wreck-it: Arruina tu aplicación antes de que lo hagan tus usuarios

WRECK abajo significa npx @miyanishar/wreck-it. La CLI realiza el trabajo determinista (configuración, descubrimiento, barridos, fuzzing, velocidad de página, carga, hallazgos, puntuación, informe, pruebas). Tú controlas el navegador a través de Playwright MCP, ejecutas los perfiles de usuario (personas), juzgas qué es un error y lo rastreas hasta el código.

Solo informa. No corrijas errores durante una ejecución a menos que el usuario lo pida después del informe.

Reglas (siempre)

• Solo local. La CLI rechaza objetivos no locales. Pasa --i-own-this solo cuando el usuario diga que es dueño de uno remoto.
• Solo datos falsos. Cuentas de prueba, nombres falsos, nunca datos personales o de pago reales. Nombra lo que crees wreck-it … y regístralo: WRECK run created "<qué>" --by <persona> (el informe lo lista para limpieza).
• Pregunta antes de escribir. El preflight safety.ask lista las preguntas: una base de datos alojada (a menudo de producción), claves de Stripe activas, correo electrónico sin bandeja de entrada legible, llamadas a IA/SMS de pago. Pregúntalas todas en un mensaje antes del pase de usuario normal y registra cada "sí" en .wreck-it/config.json (allowRemoteDb, testEmail, allowSideEffects). Si la base de datos es de producción, ofrece detenerte para que puedan apuntar la aplicación a un proyecto de desarrollo.
• Dinero y mensajes. Paga solo con claves de prueba de Stripe (tarjeta 4242 4242 4242 4242); con claves reales detente en el paso de pago. Dispara acciones de IA/SMS/correo electrónico como máximo 2–3 veces por flujo a menos que esté permitido. fuzz y load omiten esos endpoints por sí mismos.
• Correo electrónico. Regístrate con direcciones de WRECK email new, nunca de example.com. Con una bandeja de entrada local lee el enlace tú mismo (WRECK email read --to <dirección>); de lo contrario, pídele al usuario el enlace o marca la verificación como "omitida: no hay bandeja de entrada legible".
• Mantén viva la sesión compartida. Nunca cierres sesión, elimines ni cambies la contraseña de la cuenta cuya sesión guardada usan otras etapas: en Supabase y muchas aplicaciones, cerrar sesión termina todas las sesiones de ese usuario. Prueba el cierre de sesión y la eliminación al final, con una cuenta desechable.

Ejecución enfocada (una característica)

Cuando el usuario nombre una característica o flujo ("prueba el checkout", "/wreck focus signup"), prueba solo eso, en minutos:

1. WRECK run init --focus "<característica>", WRECK discover, WRECK setup --dry-run y WRECK preflight --wait 5, manejados como en la etapa 1. Inicia sesión (etapa 2) solo si la característica lo necesita. Haz las preguntas de safety.ask solo si la característica escribe datos.
2. Delimítalo. Desde discovery.json y el código, lista las páginas y rutas de API de la característica (ej. /cart, /checkout, /api/cart, /api/orders). Dile al usuario el alcance en una línea.
3. Pruébalo (salta las personas y etapas que no apliquen; márcalas como skipped):
   • Recorre la característica como un usuario normal, luego como un principiante apresurado en un teléfono (doble clic, formatos incorrectos, retroceder a medio flujo). Revisa las filas de la lista de verificación de la habilidad explore que apliquen (totales, persistencia, eliminaciones, mensajes de error).
   • WRECK sweep --record --only <páginas…> y WRECK fuzz --record --only <rutas de api…>.
   • La habilidad chaos: entradas hostiles, dobles envíos, fallos de navegación y red, solo en los formularios de esta característica.
   • WRECK perf --record <páginas…> si la característica tiene sus propias páginas.
4. Reproduce y rastrea cada hallazgo (etapa 9), luego WRECK report && WRECK gen-tests. El informe está etiquetado como ejecución enfocada: di "puntuación de característica", no "preparación".

Pipeline

Marca las etapas con WRECK run stage <etapa> running|done|skipped|failed. Los hallazgos se guardan sobre la marcha.

1. Configuración y preflight

WRECK run init               # --fresh descarta los hallazgos de una ejecución anterior
WRECK discover
WRECK setup --dry-run        # qué está instalado, qué falta
WRECK preflight --wait 5

• Si setup --dry-run lista algo para instalar, muéstralo y pregunta una vez; si dice que sí, ejecuta WRECK setup. Si agregó servidores MCP, las herramientas del navegador aparecen solo después de que el usuario reinicie el agente: dilo y ofrece una ejecución solo con CLI mientras tanto.
• Un mensaje de herramienta del navegador que diga "Browser … is not installed": WRECK setup --skip playwright-mcp devtools-mcp, luego reintenta.
• Preflight con código de salida 4 (aplicación no accesible): ofrece iniciar devScript en segundo plano, luego WRECK preflight --wait 60. Código de salida 3 (objetivo rechazado): detente y explica.
• No hay .wreck-it/config.json: crea {"baseUrl": "http://localhost:3000"} (usa el puerto real).
• Ejecución solo con CLI (sin herramientas de navegador): sweep --record, fuzz --record, perf --record, etapa 7 y el informe; marca personas, normal, explore, chaos como skipped y explica por qué. Nunca finjas que hiciste clics en la aplicación.

2. Inicio de sesión

• Google, GitHub, SSO, inicio de sesión alojado, magic links, 2FA (discovery.json auth.sso está configurado, o no hay campo de contraseña): dile al usuario "Se abrirá una ventana del navegador. Inicia sesión como tu usuario de prueba; se cerrará sola una vez que hayas iniciado sesión." Ejecuta WRECK login (espera hasta 10 minutos; usa un tiempo de espera largo). Su salida debería decir check: valid. Para verificaciones de dos usuarios, pide WRECK login --label second; para verificaciones de cuenta nueva, --label fresh, o márcalas como skipped.
• Correo electrónico y contraseña: crea una cuenta de prueba (o usa la del usuario) y agrega "accounts": [{"label": "main", "email": "…", "password": "…"}] a la configuración.
• A partir de entonces: sweep, fuzz y perf inician sesión solos. En el navegador, llama a browser_set_storage_state con {"filename": ".wreck-it/auth/<etiqueta>.json"} antes de visitar páginas que requieran inicio de sesión. Los hallazgos registrados con sesión iniciada obtienen "auth": "<etiqueta>" y pasos que comienzan después del inicio de sesión.
• Si el preflight o WRECK login --check dice expired, pídele al usuario que ejecute login nuevamente.

3. Personas

Usa la habilidad wreck-personas.

4–5. Usuario normal, luego personas

Usa la habilidad wreck-explore. En Claude Code con el plugin, ejecuta hasta 3 personas en paralelo como subagentes wreck-persona, un navegador cada uno (wreck-browser-1..3); no uses un navegador tú mismo mientras tanto y espera a que terminen todos antes de la etapa 6. Otros agentes: una persona tras otra.

6. Caos

Usa la habilidad wreck-chaos (barrido, fuzzing de API, entradas hostiles, dobles envíos, navegación, fallos de red, manipulación de sesión, teclado).

7. Velocidad de página y carga

Usa la habilidad wreck-load.

8. Seguridad

No está en v1: WRECK run stage security skipped.

9. Reproducir, luego rastrear

WRECK finding list: reproduce cada hallazgo ? en un contexto nuevo y establece reproduced: true si vuelve a aparecer (los hallazgos no reproducidos no puntúan). Luego usa la habilidad wreck-trace en cada hallazgo reproducido sin un source.

10. Informe

Antes de generar el informe, verifica que cada hallazgo de navegador reproducido tenga una captura de pantalla que muestre el fallo real. Revisa también los hallazgos de los barridos CLI; sigue la guía de capturas de pantalla en references/recording-findings.md. Verifica que los archivos de imagen guardados existan y resuelve cualquier advertencia de captura faltante. Los hallazgos solo de API o de carga pueden usar evidencia de solicitud/métrica en su lugar; di cuándo una captura de pantalla no es aplicable o no se pudo capturar.

Genera el informe y las pruebas después de la última actualización de hallazgos. Si cambias un hallazgo después, regenera ambos antes de presentar los resultados. Lee references/regression-tests.md: inspecciona las advertencias de especificaciones preservadas y reconcilia esas pruebas con los hallazgos actualizados; la regeneración mantiene intencionadamente las ediciones del agente y los fixtures. Ejecuta las especificaciones compatibles contra la aplicación con errores y verifica que los fallos lleguen a las aserciones previstas. Divulga omisiones, fallos de configuración, tiempos de espera o pruebas no verificadas en el informe; donde exista una copia corregida, verifica también las mismas especificaciones contra ella.

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

Mientras exploras (etapas 4–6)

• Graba los errores exactamente como en references/recording-findings.md: WRECK finding add, pasos estructurados, objetivos de rol/etiqueta, aserciones que describan el comportamiento correcto, luego reproduce en un contexto nuevo y establece reproduced: true.
• Después de cada navegación, ejecuta el script de rarezas (WRECK oddity-script, una vez) mediante browser_evaluate, y verifica browser_console_messages y browser_network_requests (4xx/5xx). También busca lo que los scripts no pueden juzgar: diseño roto, estados vacíos sin orientación, cargadores infinitos, botones muertos, fechas o precios inconsistentes. Registra los reales como oddity.
• Registra la cobertura: WRECK run visit <ruta> --persona <nombre>.

Mensaje final

Breve: la puntuación y la banda, el hallazgo "arregla esto primero" con su archivo:línea, conteos por severidad, etapas incompletas, las rutas .wreck-it/report.html, .wreck-it/report.md, tests/wreck-it/, y npx playwright test tests/wreck-it. Ofrece corregir los hallazgos principales; espera una respuesta afirmativa.

Al presentar un error, adjunta su captura de pantalla relevante junto al ID del hallazgo y la explicación. Usa la función de adjuntar imágenes del chat o una imagen Markdown con la ruta real del archivo guardado; una ruta de informe por sí sola no muestra la evidencia. Presenta los hallazgos principales en el chat con sus capturas y mantén el conjunto completo en los informes. Si una imagen no está disponible o no es aplicable, explica por qué y enlaza la solicitud, el rastreo o las métricas en su lugar. Resuelve las rutas almacenadas shots/... relativas a .wreck-it/.

Usa esta forma para cada hallazgo de navegador que incluyas en el chat (reemplaza el ejemplo con el hallazgo real y la ruta de imagen absoluta verificada):

**WR-007 — El subtotal del carrito ignora la cantidad** (`lib/cart.ts:19`)
Tres artículos de $79.99 deberían sumar $239.97; la página muestra $79.99.
![WR-007: cantidad 3 con un subtotal incorrecto](/ruta/absoluta/del/proyecto/.wreck-it/shots/WR-007-carrito.png)

Antes de enviar, abre cada imagen que planees presentar y describe el estado y los valores que realmente muestra. Verifica que cada hallazgo de navegador que presentes tenga una imagen adjunta o incrustada. Una lista de nombres de archivo o una declaración de que las capturas están guardadas no es un adjunto. Mantén la respuesta concisa presentando menos hallazgos, con su evidencia, y enlazando el informe completo; deja los hallazgos de navegador restantes en ese informe en lugar de agregar una lista sin ilustraciones en el chat.