theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/commands/revisar-codigo.md

@@ -0,0 +1,289 @@
+---
+description: Revisión de código — cambios locales sin commitear o PR de GitHub (pasa el número/URL del PR para el modo PR)
+argument-hint: [numero-pr | url-pr | vacío para revisión local]
+---
+
+# Revisión de código
+
+Parte de la serie de flujos PRP (planificar → implementar → revisar).
+
+**Entrada**: $ARGUMENTS
+
+---
+
+## Selección de modo
+
+Si `$ARGUMENTS` contiene un número de PR, una URL de PR o `--pr`:
+→ Salta al **Modo revisión de PR** más abajo.
+
+En caso contrario:
+→ Usa el **Modo revisión local**.
+
+---
+
+## Modo revisión local
+
+Revisión integral de seguridad y calidad de los cambios sin commitear.
+
+### Fase 1 — RECOPILAR
+
+```bash
+git diff --name-only HEAD
+```
+
+Si no hay archivos modificados, detente: "No hay nada que revisar."
+
+### Fase 2 — REVISAR
+
+Lee cada archivo modificado completo. Verifica:
+
+**Problemas de seguridad (CRÍTICO):**
+- Credenciales, claves de API o tokens hardcodeados
+- Vulnerabilidades de inyección SQL
+- Vulnerabilidades XSS
+- Falta de validación de entradas
+- Dependencias inseguras
+- Riesgos de path traversal
+
+**Calidad de código (ALTO):**
+- Funciones de más de 50 líneas
+- Archivos de más de 800 líneas
+- Anidamiento de más de 4 niveles
+- Manejo de errores ausente
+- Sentencias `console.log`
+- Comentarios TODO/FIXME
+- Falta de JSDoc en APIs públicas
+
+**Buenas prácticas (MEDIO):**
+- Patrones de mutación (preferir inmutabilidad)
+- Uso de emojis en código/comentarios
+- Falta de tests para código nuevo
+- Problemas de accesibilidad (a11y)
+
+### Fase 3 — REPORTAR
+
+Genera un informe con:
+- Severidad: CRÍTICO, ALTO, MEDIO, BAJO
+- Ubicación del archivo y números de línea
+- Descripción del problema
+- Corrección sugerida
+
+Bloquea el commit si se encuentran problemas CRÍTICOS o ALTOS.
+Nunca apruebes código con vulnerabilidades de seguridad.
+
+---
+
+## Modo revisión de PR
+
+Revisión integral de un PR de GitHub — obtiene el diff, lee los archivos completos, ejecuta la validación y publica la revisión.
+
+### Fase 1 — OBTENER
+
+Analiza la entrada para determinar el PR:
+
+| Entrada | Acción |
+|---|---|
+| Número (p. ej. `42`) | Usar como número de PR |
+| URL (`github.com/.../pull/42`) | Extraer el número de PR |
+| Nombre de rama | Buscar el PR con `gh pr list --head <rama>` |
+
+```bash
+gh pr view <NUMERO> --json number,title,body,author,baseRefName,headRefName,changedFiles,additions,deletions
+gh pr diff <NUMERO>
+```
+
+Si el PR no existe, detente con un error. Guarda los metadatos del PR para las fases siguientes.
+
+### Fase 2 — CONTEXTO
+
+Construye el contexto de la revisión:
+
+1. **Reglas del proyecto** — Lee `THEUS.md`, `.theus/docs/` y cualquier guía de contribución
+2. **Artefactos de planificación** — Revisa `.theus/prds/`, `.theus/plans/`, `.theus/reviews/` y el árbol PRP `.theus/prp/{prds,plans,reports,reviews}/` en busca de contexto relacionado con este PR
+3. **Intención del PR** — Extrae de la descripción del PR los objetivos, issues vinculados y planes de prueba
+4. **Archivos modificados** — Lista todos los archivos modificados y clasifícalos por tipo (código fuente, tests, configuración, documentación)
+
+### Fase 3 — REVISAR
+
+Lee cada archivo modificado **completo** (no solo los fragmentos del diff — necesitas el contexto circundante).
+
+Para revisiones de PR, obtén el contenido completo de los archivos en la revisión head del PR:
+```bash
+gh pr diff <NUMERO> --name-only | while IFS= read -r file; do
+  gh api "repos/{owner}/{repo}/contents/$file?ref=<rama-head>" --jq '.content' | base64 -d
+done
+```
+
+Aplica la lista de verificación de revisión en 7 categorías:
+
+| Categoría | Qué verificar |
+|---|---|
+| **Corrección** | Errores de lógica, off-by-one, manejo de nulos, casos límite, condiciones de carrera |
+| **Seguridad de tipos** | Tipos incompatibles, casts inseguros, uso de `any`, genéricos faltantes |
+| **Conformidad con patrones** | Coherencia con las convenciones del proyecto (nombres, estructura de archivos, manejo de errores, imports) |
+| **Seguridad** | Inyección, brechas de autenticación, exposición de secretos, SSRF, path traversal, XSS |
+| **Rendimiento** | Consultas N+1, índices faltantes, bucles sin cota, fugas de memoria, payloads grandes |
+| **Completitud** | Tests faltantes, manejo de errores ausente, migraciones incompletas, documentación faltante |
+| **Mantenibilidad** | Código muerto, números mágicos, anidamiento profundo, nombres poco claros, tipos ausentes |
+
+Asigna severidad a cada hallazgo:
+
+| Severidad | Significado | Acción |
+|---|---|---|
+| **CRÍTICO** | Vulnerabilidad de seguridad o riesgo de pérdida de datos | Debe corregirse antes del merge |
+| **ALTO** | Bug o error de lógica con alta probabilidad de causar problemas | Debería corregirse antes del merge |
+| **MEDIO** | Problema de calidad de código o buena práctica ausente | Corrección recomendada |
+| **BAJO** | Detalle de estilo o sugerencia menor | Opcional |
+
+### Fase 4 — VALIDAR
+
+Ejecuta los comandos de validación disponibles:
+
+Detecta el tipo de proyecto por sus archivos de configuración (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.) y ejecuta los comandos que apliquen:
+
+**Node.js / TypeScript** (tiene `package.json`):
+```bash
+npm run typecheck 2>/dev/null || npx tsc --noEmit 2>/dev/null  # Verificación de tipos
+npm run lint                                                    # Lint
+npm test                                                        # Tests
+npm run build                                                   # Build
+```
+
+**Rust** (tiene `Cargo.toml`):
+```bash
+cargo clippy -- -D warnings  # Lint
+cargo test                   # Tests
+cargo build                  # Build
+```
+
+**Go** (tiene `go.mod`):
+```bash
+go vet ./...    # Lint
+go test ./...   # Tests
+go build ./...  # Build
+```
+
+**Python** (tiene `pyproject.toml` / `setup.py`):
+```bash
+pytest  # Tests
+```
+
+Ejecuta solo los comandos que correspondan al tipo de proyecto detectado. Registra el resultado (pasó/falló) de cada uno.
+
+### Fase 5 — DECIDIR
+
+Forma una recomendación en base a los hallazgos:
+
+| Condición | Decisión |
+|---|---|
+| Cero problemas CRÍTICOS/ALTOS y la validación pasa | **APROBAR** |
+| Solo problemas MEDIOS/BAJOS y la validación pasa | **APROBAR** con comentarios |
+| Cualquier problema ALTO o fallo de validación | **SOLICITAR CAMBIOS** |
+| Cualquier problema CRÍTICO | **BLOQUEAR** — debe corregirse antes del merge |
+
+Casos especiales:
+- PR en borrador (draft) → Usa siempre **COMENTAR** (nunca aprobar/bloquear)
+- Solo cambios de docs/configuración → Revisión más ligera, enfocada en corrección
+- Flag explícito `--approve` o `--request-changes` → Sobrescribe la decisión (pero reporta igualmente todos los hallazgos)
+
+### Fase 6 — REPORTAR
+
+Crea el artefacto de revisión en `.theus/reviews/pr-<NUMERO>-review.md`, salvo que el repositorio ya use `.theus/prp/reviews/` para esta línea de trabajo:
+
+```markdown
+# Revisión de PR: #<NUMERO> — <TITULO>
+
+**Revisado**: <fecha>
+**Autor**: <autor>
+**Rama**: <head> → <base>
+**Decisión**: APROBAR | SOLICITAR CAMBIOS | BLOQUEAR
+
+## Resumen
+<evaluación general en 1-2 oraciones>
+
+## Hallazgos
+
+### CRÍTICO
+<hallazgos o "Ninguno">
+
+### ALTO
+<hallazgos o "Ninguno">
+
+### MEDIO
+<hallazgos o "Ninguno">
+
+### BAJO
+<hallazgos o "Ninguno">
+
+## Resultados de validación
+
+| Verificación | Resultado |
+|---|---|
+| Verificación de tipos | Pasa / Falla / Omitida |
+| Lint | Pasa / Falla / Omitida |
+| Tests | Pasa / Falla / Omitida |
+| Build | Pasa / Falla / Omitida |
+
+## Archivos revisados
+<lista de archivos con tipo de cambio: Agregado/Modificado/Eliminado>
+```
+
+### Fase 7 — PUBLICAR
+
+Publica la revisión en GitHub:
+
+```bash
+# Si APROBAR
+gh pr review <NUMERO> --approve --body "<resumen de la revisión>"
+
+# Si SOLICITAR CAMBIOS
+gh pr review <NUMERO> --request-changes --body "<resumen con las correcciones requeridas>"
+
+# Si solo COMENTAR (PR en borrador o informativo)
+gh pr review <NUMERO> --comment --body "<resumen>"
+```
+
+Para comentarios en línea sobre líneas específicas, usa la API de comentarios de revisión de GitHub:
+```bash
+gh api "repos/{owner}/{repo}/pulls/<NUMERO>/comments" \
+  -f body="<comentario>" \
+  -f path="<archivo>" \
+  -F line=<numero-de-linea> \
+  -f side="RIGHT" \
+  -f commit_id="$(gh pr view <NUMERO> --json headRefOid --jq .headRefOid)"
+```
+
+Alternativamente, publica una sola revisión con varios comentarios en línea a la vez:
+```bash
+gh api "repos/{owner}/{repo}/pulls/<NUMERO>/reviews" \
+  -f event="COMMENT" \
+  -f body="<resumen general>" \
+  --input comments.json  # [{"path": "archivo", "line": N, "body": "comentario"}, ...]
+```
+
+### Fase 8 — SALIDA
+
+Reporta al usuario:
+
+```
+PR #<NUMERO>: <TITULO>
+Decisión: <APROBAR|SOLICITAR_CAMBIOS|BLOQUEAR>
+
+Problemas: <n_criticos> críticos, <n_altos> altos, <n_medios> medios, <n_bajos> bajos
+Validación: <n_pasadas>/<n_total> verificaciones pasadas
+
+Artefactos:
+  Revisión: .theus/reviews/pr-<NUMERO>-review.md
+  GitHub: <URL del PR>
+
+Próximos pasos:
+  - <sugerencias contextuales según la decisión>
+```
+
+---
+
+## Casos límite
+
+- **Sin CLI `gh`**: recurre a la revisión solo local (lee el diff, omite la publicación en GitHub). Avisa al usuario.
+- **Ramas divergentes**: sugiere `git fetch origin && git rebase origin/<base>` antes de revisar.
+- **PRs grandes (>50 archivos)**: advierte sobre el alcance de la revisión. Prioriza los cambios de código fuente, luego tests, luego configuración/docs.

package/vendor/theus-arsenal/commands/revisar-cpp.md

@@ -0,0 +1,132 @@
+---
+description: Revisión integral de código C++ orientada a seguridad de memoria, C++ moderno, concurrencia y seguridad. Invoca al agente revisor-cpp.
+---
+
+# Revisión de código C++
+
+Este comando invoca al agente **revisor-cpp** para una revisión integral específica de C++.
+
+## Qué hace este comando
+
+1. **Identifica cambios de C++**: encuentra archivos `.cpp`, `.hpp`, `.cc`, `.h` modificados vía `git diff`
+2. **Ejecuta análisis estático**: corre `clang-tidy` y `cppcheck`
+3. **Escaneo de seguridad de memoria**: busca new/delete crudos, desbordamientos de buffer, use-after-free
+4. **Revisión de concurrencia**: analiza seguridad entre hilos, uso de mutex, condiciones de carrera
+5. **Chequeo de C++ moderno**: verifica que el código siga las convenciones y buenas prácticas de C++17/20
+6. **Genera un informe**: categoriza los hallazgos por severidad
+
+## Cuándo usarlo
+
+Usa `/revisar-cpp` cuando:
+- Acabas de escribir o modificar código C++
+- Antes de hacer commit de cambios en C++
+- Al revisar pull requests con código C++
+- Al incorporarte a un código base C++ nuevo
+- Para buscar problemas de seguridad de memoria
+
+## Categorías de revisión
+
+### CRÍTICO (obligatorio corregir)
+- `new`/`delete` crudos sin RAII
+- Desbordamientos de buffer y use-after-free
+- Condiciones de carrera sin sincronización
+- Inyección de comandos vía `system()`
+- Lecturas de variables sin inicializar
+- Desreferencias de punteros nulos
+
+### ALTO (debería corregirse)
+- Violaciones de la Regla de los Cinco
+- Falta de `std::lock_guard` / `std::scoped_lock`
+- Hilos desacoplados (detached) sin gestión de ciclo de vida
+- Casts estilo C en lugar de `static_cast`/`dynamic_cast`
+- Falta de corrección de `const`
+
+### MEDIO (a considerar)
+- Copias innecesarias (paso por valor en lugar de `const&`)
+- Falta de `reserve()` en contenedores de tamaño conocido
+- `using namespace std;` en cabeceras
+- Falta de `[[nodiscard]]` en valores de retorno importantes
+- Metaprogramación de plantillas excesivamente compleja
+
+## Chequeos automáticos ejecutados
+
+```bash
+# Análisis estático
+clang-tidy --checks='*,-llvmlibc-*' src/*.cpp -- -std=c++17
+
+# Análisis adicional
+cppcheck --enable=all --suppress=missingIncludeSystem src/
+
+# Build con warnings
+cmake --build build -- -Wall -Wextra -Wpedantic
+```
+
+## Ejemplo de uso
+
+```text
+Usuario: /revisar-cpp
+
+Agente:
+# Informe de revisión de código C++
+
+## Archivos revisados
+- src/handler/user.cpp (modificado)
+- src/service/auth.cpp (modificado)
+
+## Resultados del análisis estático
+✓ clang-tidy: 2 warnings
+✓ cppcheck: sin hallazgos
+
+## Hallazgos
+
+[CRÍTICO] Fuga de memoria
+Archivo: src/service/auth.cpp:45
+Problema: `new` crudo sin su `delete` correspondiente
+```cpp
+auto* session = new Session(userId);  // ¡Fuga de memoria!
+cache[userId] = session;
+```
+Arreglo: usar `std::unique_ptr`
+```cpp
+auto session = std::make_unique<Session>(userId);
+cache[userId] = std::move(session);
+```
+
+[ALTO] Falta referencia const
+Archivo: src/handler/user.cpp:28
+Problema: objeto grande pasado por valor
+```cpp
+void processUser(User user) {  // Copia innecesaria
+```
+Arreglo: pasar por referencia const
+```cpp
+void processUser(const User& user) {
+```
+
+## Resumen
+- CRÍTICO: 1
+- ALTO: 1
+- MEDIO: 0
+
+Recomendación: FAIL: Bloquear el merge hasta corregir el hallazgo CRÍTICO
+```
+
+## Criterios de aprobación
+
+| Estado | Condición |
+|--------|-----------|
+| PASS: Aprobar | Sin hallazgos CRÍTICOS ni ALTOS |
+| WARNING: Advertencia | Solo hallazgos MEDIOS (merge con cautela) |
+| FAIL: Bloquear | Hay hallazgos CRÍTICOS o ALTOS |
+
+## Integración con otros comandos
+
+- Usa `/test-cpp` primero para asegurar que los tests pasan
+- Usa `/build-cpp` si aparecen errores de build
+- Usa `/revisar-cpp` antes de hacer commit
+- Usa `/revisar-codigo` para aspectos no específicos de C++
+
+## Relacionados
+
+- Agente: `agents/revisor-cpp.md`
+- Skills: `skills/estandares-cpp/`, `skills/testing-cpp/`

package/vendor/theus-arsenal/commands/revisar-fastapi.md

@@ -0,0 +1,39 @@
+---
+description: Revisa una aplicación FastAPI en arquitectura, corrección async, inyección de dependencias, esquemas Pydantic, seguridad, rendimiento y testabilidad.
+---
+
+# Revisión FastAPI
+
+Invoca al agente `revisor-fastapi` para una revisión enfocada de FastAPI.
+
+## Uso
+
+```text
+/revisar-fastapi [archivo-o-directorio]
+```
+
+## Áreas de revisión
+
+- Factoría de la app, límites de routers, middleware y manejadores de excepciones.
+- Separación de esquemas Pydantic de petición y de respuesta.
+- Inyección de dependencias para sesiones de base de datos, autenticación, paginación y configuración.
+- Patrones async de base de datos y de HTTP externo.
+- CORS, autenticación, límites de tasa, logging y manejo de secretos.
+- Metadatos OpenAPI y modelos de respuesta documentados.
+- Configuración del cliente de tests y overrides de dependencias.
+
+## Salida esperada
+
+```text
+[SEVERIDAD] Título corto del problema
+Archivo: ruta/al/archivo.py:42
+Problema: Qué está mal y por qué importa.
+Arreglo: Cambio concreto a realizar.
+```
+
+## Relacionados
+
+- Agente: `revisor-fastapi`
+- Skill: `patrones-fastapi`
+- Comando: `/revisar-python`
+- Skill: `revision-seguridad`

package/vendor/theus-arsenal/commands/revisar-flutter.md

@@ -0,0 +1,115 @@
+---
+description: Revisa código Flutter/Dart en patrones idiomáticos, buenas prácticas de widgets, gestión de estado, rendimiento, accesibilidad y seguridad. Invoca al agente revisor-flutter.
+---
+
+# Revisión de código Flutter
+
+Este comando invoca al agente **revisor-flutter** para revisar cambios de código Flutter/Dart.
+
+## Qué hace este comando
+
+1. **Reunir contexto**: revisa `git diff --staged` y `git diff`
+2. **Inspeccionar el proyecto**: revisa `pubspec.yaml`, `analysis_options.yaml` y la solución de gestión de estado
+3. **Pre-escaneo de seguridad**: busca secretos hardcodeados y problemas de seguridad críticos
+4. **Revisión completa**: aplica la lista de verificación completa
+5. **Informar hallazgos**: emite los problemas agrupados por severidad con guía de arreglo
+
+## Requisitos previos
+
+Antes de ejecutar `/revisar-flutter`, asegúrate de que:
+1. **El build pasa** — ejecuta primero `/build-flutter`; una revisión sobre código roto queda incompleta
+2. **Los tests pasan** — ejecuta `/test-flutter` para confirmar que no hay regresiones
+3. **No hay conflictos de merge** — resuelve todos los conflictos para que el diff refleje solo cambios intencionales
+4. **`flutter analyze` está limpio** — corrige los warnings del analizador antes de revisar
+
+## Cuándo usarlo
+
+Usa `/revisar-flutter` cuando:
+- Antes de enviar un PR con cambios de Flutter/Dart (después de que build y tests pasen)
+- Tras implementar una funcionalidad nueva, para detectar problemas temprano
+- Al revisar código Flutter de otra persona
+- Para auditar un widget, un componente de gestión de estado o una clase de servicio
+- Antes de un lanzamiento a producción
+
+## Áreas de revisión
+
+| Área | Severidad |
+|------|-----------|
+| Secretos hardcodeados, HTTP en texto plano | CRÍTICA |
+| Violaciones de arquitectura, antipatrones de gestión de estado | CRÍTICA |
+| Problemas de rebuild de widgets, fugas de recursos | ALTA |
+| Falta de `dispose()`, `BuildContext` después de un await | ALTA |
+| Null safety de Dart, estados de error/carga ausentes | ALTA |
+| Propagación de const, composición de widgets | ALTA |
+| Rendimiento: trabajo costoso dentro de `build()` | ALTA |
+| Accesibilidad, etiquetas semánticas | MEDIA |
+| Tests ausentes para transiciones de estado | ALTA |
+| Cadenas hardcodeadas (l10n) | MEDIA |
+| Higiene de dependencias de pub | BAJA |
+
+## Sesión de ejemplo
+
+````text
+Usuario: /revisar-flutter
+
+Agente:
+# Revisión de código Flutter
+
+## Contexto
+
+Archivos cambiados:
+- lib/features/auth/presentation/login_page.dart
+- lib/features/auth/data/auth_repository_impl.dart
+
+Gestión de estado: Riverpod (detectado en pubspec.yaml)
+Arquitectura: feature-first
+
+## Pre-escaneo de seguridad
+
+✓ No se detectaron secretos hardcodeados
+✓ No hay llamadas HTTP en texto plano
+
+## Hallazgos de la revisión
+
+[ALTA] BuildContext usado tras un gap async sin verificar mounted
+Archivo: lib/features/auth/presentation/login_page.dart:67
+Problema: `context.go('/home')` se llama después de `await auth.login(...)` sin verificar `mounted`.
+Arreglo: Agregar `if (!context.mounted) return;` antes de cualquier navegación posterior a un await (Flutter 3.7+).
+
+[ALTA] Estado de error de AsyncValue no manejado
+Archivo: lib/features/auth/presentation/login_page.dart:42
+Problema: `ref.watch(authProvider)` cubre loading/data pero no tiene rama `error`.
+Arreglo: Agregar el caso de error al switch o al `when()` para mostrar un mensaje de error al usuario.
+
+[MEDIA] Cadena hardcodeada sin localizar
+Archivo: lib/features/auth/presentation/login_page.dart:89
+Problema: `Text('Login')` — cadena visible al usuario que no usa el sistema de localización.
+Arreglo: Usar el accesor de l10n del proyecto: `Text(context.l10n.loginButton)`.
+
+## Resumen de la revisión
+
+| Severidad | Cantidad | Estado  |
+|-----------|----------|---------|
+| CRÍTICA   | 0        | pasa    |
+| ALTA      | 2        | bloquea |
+| MEDIA     | 1        | info    |
+| BAJA      | 0        | nota    |
+
+Veredicto: BLOQUEAR — los problemas de severidad ALTA deben corregirse antes del merge.
+````
+
+## Criterios de aprobación
+
+- **Aprobar**: sin problemas CRÍTICOS ni ALTOS
+- **Bloquear**: cualquier problema CRÍTICO o ALTO debe corregirse antes del merge
+
+## Comandos relacionados
+
+- `/build-flutter` — Corregir errores de build primero
+- `/test-flutter` — Ejecutar los tests antes de revisar
+- `/revisar-codigo` — Revisión de código general (independiente del lenguaje)
+
+## Relacionados
+
+- Agente: `agents/revisor-flutter.md`
+- Skill: `skills/revision-codigo-flutter-dart/`