theus-cli-darwin-x64 0.2.84

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

@@ -0,0 +1,170 @@
+---
+description: Revisión integral de código React/JSX que cubre corrección de hooks, rendimiento de render, límites entre componentes de servidor/cliente, accesibilidad y seguridad específica de React. Invoca al agente revisor-react (y a revisor-typescript en paralelo cuando hay cambios TSX/JSX).
+---
+
+# Revisión de código React
+
+Este comando invoca al agente **revisor-react** para una revisión de código específica de React. Para pull requests que tocan archivos `.tsx`/`.jsx`, deben correr tanto `revisor-react` como `revisor-typescript` — cada uno es dueño de un carril distinto.
+
+## Qué hace este comando
+
+1. **Identificar cambios de React**: encuentra los archivos `.tsx`/`.jsx` modificados (y archivos `.ts`/`.js` con React) vía `git diff`
+2. **Ejecutar el lint**: corre `eslint` con `eslint-plugin-react-hooks` y `eslint-plugin-jsx-a11y`
+3. **Typecheck**: ejecuta `tsc --noEmit` o el comando de typecheck canónico del proyecto
+4. **Revisar solo los carriles de React**: reglas de hooks, límites RSC, accesibilidad, rendimiento de render, seguridad específica de React
+5. **Generar el reporte**: categoriza los hallazgos por severidad (CRÍTICO / ALTO / MEDIO)
+
+## Cuándo usarlo
+
+Usa `/revisar-react` cuando:
+
+- Un PR o commit toca archivos `.tsx`/`.jsx`
+- Después de escribir o modificar componentes de React, hooks personalizados o páginas
+- Antes de fusionar código React
+- Al auditar la accesibilidad de componentes de UI
+- Al revisar un hook nuevo por rules-of-hooks y corrección de dependencias
+- Al auditar un límite de componentes servidor/cliente en Next.js App Router
+
+Para cambios puros de `.ts`/`.js` sin imports de React, usa el agente `revisor-codigo` (revisión general) o invoca a `revisor-typescript` directamente.
+
+## Alcance frente a la revisión general y la de TypeScript
+
+| Herramienta | Alcance |
+|---|---|
+| `revisor-react` (este comando) | Reglas de hooks, JSX, RSC, a11y, seguridad específica de React, rendimiento de render |
+| `revisor-typescript` | TS/JS genérico — abuso de `any`, corrección de async, seguridad de Node |
+| `revisor-seguridad` | Auditoría de seguridad de todo el proyecto |
+| `revisor-codigo` / `/revisar-pr` | Revisión genérica de cambios sin commitear o de un PR |
+
+En un PR con TSX/JSX, invoca a `revisor-react` y a `revisor-typescript`. Sus hallazgos no se solapan por diseño.
+
+## Categorías de revisión
+
+### CRÍTICO (corrección obligatoria)
+
+- `dangerouslySetInnerHTML` con entrada sin sanitizar
+- `href`/`src` con URLs de usuario sin validar (`javascript:`, `data:`)
+- Server Action sin validación de entrada
+- Secreto en el bundle del cliente (`NEXT_PUBLIC_*`, `VITE_*`, `REACT_APP_*`)
+- `localStorage`/`sessionStorage` para tokens de sesión
+- Llamadas condicionales a hooks (viola las Rules of Hooks)
+- Mutación directa del estado
+- Hook llamado fuera de un componente o de un hook personalizado
+
+### ALTO (debería corregirse)
+
+- Dependencias faltantes en `useEffect`/`useMemo`/`useCallback` (`exhaustive-deps` deshabilitado sin justificación)
+- Effect para estado derivado
+- Effect sin limpieza (cleanup)
+- Closures obsoletos en handlers/intervalos
+- Imports exclusivos de servidor en Client Components
+- Datos sensibles filtrados vía props a Client Components
+- Server Actions sin verificación de autenticación
+- Violaciones de accesibilidad (labels faltantes, elementos interactivos no semánticos, mal uso de ARIA)
+- `key={index}` en listas dinámicas
+- Estado duplicado, cadenas de useEffect
+
+### MEDIO (a considerar)
+
+- Sobre-memoización sin una ganancia medida
+- Objeto/función nuevo inline como prop de un hijo memoizado
+- Suspense solo en la raíz de la ruta (sin revelado progresivo)
+- Listas largas sin virtualización
+- Valor de alta frecuencia vía `useContext`
+- Validación hecha a mano en formularios no triviales
+- Prop drilling de más de 3 niveles
+- Componente de más de 200 líneas
+- Componentes de clase en código nuevo
+
+## Verificaciones automatizadas que se ejecutan
+
+```bash
+# Lint (requerido para cualquier revisión con sentido)
+npx eslint . --ext .tsx,.jsx,.ts,.js
+
+# Typecheck (se omite limpiamente en proyectos solo-JS)
+npm run typecheck --if-present
+[ -f tsconfig.json ] && tsc --noEmit -p tsconfig.json
+
+# Reglas de a11y dirigidas
+npx eslint . --rule 'jsx-a11y/alt-text: error' \
+              --rule 'jsx-a11y/anchor-is-valid: error' \
+              --rule 'jsx-a11y/click-events-have-key-events: error'
+
+# Cadena de suministro
+npm audit
+```
+
+Si `eslint-plugin-react-hooks` o `eslint-plugin-jsx-a11y` no están configurados, la revisión marcará esa brecha como un problema de configuración ALTO y continuará.
+
+## Ejemplo de uso
+
+````text
+Usuario: /revisar-react
+
+Agente:
+# Reporte de revisión de código React
+
+## Archivos revisados
+- src/components/UserCard.tsx (modificado)
+- src/hooks/useUser.ts (nuevo)
+
+## Resultados del lint
+PASS: eslint limpio
+PASS: typecheck limpio
+
+## Hallazgos
+
+[CRÍTICO] dangerouslySetInnerHTML sin sanitizar
+Archivo: src/components/UserCard.tsx:42
+Problema: la biografía controlada por el usuario se renderiza como HTML crudo.
+Por qué: XSS mediante etiquetas script almacenadas en la entrada del usuario.
+Corrección: sanitizar con DOMPurify o renderizar como texto:
+```tsx
+import DOMPurify from "isomorphic-dompurify";
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(user.bio) }} />
+```
+
+[ALTO] Falta la limpieza del effect
+Archivo: src/hooks/useUser.ts:18
+Problema: llamada a `fetch` sin AbortController; es posible un setState sobre un componente desmontado.
+Corrección: añadir AbortController y limpieza:
+```ts
+useEffect(() => {
+  const ac = new AbortController();
+  fetch(`/api/users/${id}`, { signal: ac.signal })
+    .then(r => r.json())
+    .then(setUser);
+  return () => ac.abort();
+}, [id]);
+```
+
+## 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 (fusionar con cautela) |
+| FAIL: Bloquear | Hallazgos CRÍTICOS o ALTOS encontrados |
+
+## Integración con otros comandos
+
+- Ejecuta `/build-react` primero si el build está roto
+- Ejecuta `/test-react` para asegurar que los tests de componentes pasan
+- Ejecuta `/revisar-react` antes de fusionar
+- Usa `/revisar-pr` para las preocupaciones no específicas de React en el mismo PR
+
+## Relacionado
+
+- Agente: `agents/revisor-react.md`
+- Agente acompañante: `agents/revisor-typescript.md` (corre en paralelo en PRs con TSX/JSX)
+- Skills: `skills/patrones-react/`, `skills/testing-react/`, `skills/accesibilidad/`
+- Reglas: `rules/react/`

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

@@ -0,0 +1,142 @@
+---
+description: Revisión integral de código Rust — propiedad, lifetimes, manejo de errores, uso de unsafe y patrones idiomáticos. Invoca al agente revisor-rust.
+---
+
+# Revisión de código Rust
+
+Este comando invoca al agente **revisor-rust** para una revisión de código integral específica de Rust.
+
+## Qué hace este comando
+
+1. **Verificar los chequeos automáticos**: ejecutar `cargo check`, `cargo clippy -- -D warnings`, `cargo fmt --check` y `cargo test` — detenerse si alguno falla
+2. **Identificar los cambios de Rust**: encontrar los archivos `.rs` modificados con `git diff HEAD~1` (o `git diff main...HEAD` para PRs)
+3. **Ejecutar la auditoría de seguridad**: `cargo audit` si está disponible
+4. **Escaneo de seguridad**: buscar uso de unsafe, inyección de comandos, secretos hardcodeados
+5. **Revisión de propiedad**: analizar clones innecesarios, problemas de lifetimes, patrones de préstamo
+6. **Generar el informe**: categorizar los hallazgos por severidad
+
+## Cuándo usarlo
+
+Usa `/revisar-rust` cuando:
+- Acabas de escribir o modificar código Rust
+- Antes de commitear cambios de Rust
+- Al revisar pull requests con código Rust
+- Al incorporarte a un código base Rust nuevo
+- Para aprender patrones idiomáticos de Rust
+
+## Categorías de revisión
+
+### CRÍTICO (corregir sí o sí)
+- `unwrap()`/`expect()` sin control en rutas de producción
+- `unsafe` sin comentario `// SAFETY:` que documente los invariantes
+- Inyección SQL por interpolación de strings en consultas
+- Inyección de comandos por entrada sin validar en `std::process::Command`
+- Credenciales hardcodeadas
+- Use-after-free vía punteros crudos
+
+### ALTO (debería corregirse)
+- `.clone()` innecesario para contentar al borrow checker
+- Parámetro `String` donde basta `&str` o `impl AsRef<str>`
+- Bloqueo en contexto async (`std::thread::sleep`, `std::fs`)
+- Faltan bounds `Send`/`Sync` en tipos compartidos
+- Match comodín `_ =>` sobre enums críticos para el negocio
+- Funciones grandes (>50 líneas)
+
+### MEDIO (a considerar)
+- Asignaciones innecesarias en rutas calientes
+- Falta `with_capacity` cuando el tamaño se conoce
+- Advertencias de clippy suprimidas sin justificación
+- API pública sin documentación `///`
+- Considerar `#[must_use]` en tipos de retorno donde ignorar el valor es probablemente un bug
+
+## Chequeos automáticos ejecutados
+
+```bash
+# Puerta de build (debe pasar antes de revisar)
+cargo check
+
+# Lints y sugerencias
+cargo clippy -- -D warnings
+
+# Formato
+cargo fmt --check
+
+# Tests
+cargo test
+
+# Auditoría de seguridad (si está disponible)
+if command -v cargo-audit >/dev/null; then cargo audit; else echo "cargo-audit no está instalado"; fi
+```
+
+## Ejemplo de uso
+
+````text
+Usuario: /revisar-rust
+
+Agente:
+# Informe de revisión de código Rust
+
+## Archivos revisados
+- src/service/user.rs (modificado)
+- src/handler/api.rs (modificado)
+
+## Resultados del análisis estático
+- Build: exitoso
+- Clippy: sin advertencias
+- Formato: correcto
+- Tests: todos en verde
+
+## Hallazgos
+
+[CRÍTICO] unwrap sin control en ruta de producción
+Archivo: src/service/user.rs:28
+Problema: uso de `.unwrap()` sobre el resultado de una consulta a la base de datos
+```rust
+let user = db.find_by_id(id).unwrap();  // Provoca panic si el usuario no existe
+```
+Arreglo: propagar el error con contexto
+```rust
+let user = db.find_by_id(id)
+    .context("no se pudo obtener el usuario")?;
+```
+
+[ALTO] Clone innecesario
+Archivo: src/handler/api.rs:45
+Problema: se clona un String para contentar al borrow checker
+```rust
+let name = user.name.clone();
+process(&user, &name);
+```
+Arreglo: reestructurar para evitar el clone
+```rust
+let result = process_name(&user.name);
+use_user(&user, result);
+```
+
+## Resumen
+- CRÍTICO: 1
+- ALTO: 1
+- MEDIO: 0
+
+Recomendación: bloquear el merge hasta corregir el hallazgo CRÍTICO
+````
+
+## Criterios de aprobación
+
+| Estado | Condición |
+|--------|-----------|
+| Aprobar | Sin hallazgos CRÍTICOS ni ALTOS |
+| Advertencia | Solo hallazgos MEDIOS (mergear con cautela) |
+| Bloquear | Hallazgos CRÍTICOS o ALTOS presentes |
+
+## Integración con otros comandos
+
+- Usa `/test-rust` primero para asegurar que los tests pasan
+- Usa `/build-rust` si hay errores de build
+- Usa `/revisar-rust` antes de commitear
+- Usa `/revisar-codigo` para lo que no sea específico de Rust
+
+## Relacionados
+
+- Agente: `agents/revisor-rust.md`
+- Skills: `skills/patrones-rust/`, `skills/testing-rust/`

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

@@ -0,0 +1,174 @@
+---
+description: Revisión integral de código Vue.js para corrección de la Composition API, reactividad, patrones de composables, seguridad de templates, accesibilidad y rendimiento específico de Vue. Invoca al agente revisor-vue (y a revisor-typescript en paralelo cuando hay cambios en .vue/.ts).
+---
+
+# Revisión de código Vue
+
+Este comando invoca al agente **revisor-vue** para una revisión de código específica de Vue. Para pull requests que tocan archivos `.vue` o archivos `.ts`/`.js` que contienen Vue, deben ejecutarse tanto `revisor-vue` como `revisor-typescript` — cada uno cubre un carril distinto.
+
+## Qué hace este comando
+
+1. **Identificar cambios de Vue**: encuentra los archivos `.vue` modificados y los `.ts`/`.js` relacionados con Vue mediante `git diff`
+2. **Ejecutar el lint**: corre `eslint` con `eslint-plugin-vue`
+3. **Verificar tipos**: ejecuta `vue-tsc --noEmit` o el comando canónico de typecheck del proyecto
+4. **Revisar solo los carriles de Vue**: reactividad, composables, seguridad de templates, accesibilidad, rendimiento específico de Vue
+5. **Generar el informe**: clasifica los hallazgos por severidad (CRÍTICO / ALTO / MEDIO)
+
+## Cuándo usarlo
+
+Usa `/revisar-vue` cuando:
+
+- Un PR o commit toca archivos `.vue`
+- Después de escribir o modificar componentes Vue, composables o stores de Pinia
+- Antes de hacer merge de código Vue
+- Al auditar la seguridad de templates (`v-html`, bindings de URL)
+- Al revisar la corrección de un composable nuevo
+- Al auditar guards y navegación de Vue Router
+- Al revisar rutas de servidor de Nuxt o código específico de SSR
+
+Para cambios de `.ts`/`.js` puros sin imports de Vue, usa `/control-calidad` (general) o invoca directamente a `revisor-typescript`.
+
+## Alcance frente a la revisión general y la de TypeScript
+
+| Herramienta | Alcance |
+|---|---|
+| `revisor-vue` (este comando) | Reactividad, composables, seguridad de templates, a11y, rendimiento de Vue, Pinia/Router |
+| `revisor-typescript` | TS/JS genérico — abuso de `any`, corrección asíncrona, seguridad en Node |
+| `revisor-seguridad` | Auditoría de seguridad de todo el proyecto |
+| `/control-calidad` | Revisión genérica de cambios sin commitear o de un PR |
+
+En un PR con `.vue` o relacionado con Vue, invoca tanto a `revisor-vue` como a `revisor-typescript`. Sus hallazgos no se superponen por diseño.
+
+## Categorías de revisión
+
+### CRÍTICO (corrección obligatoria)
+
+- `v-html` con entrada sin sanitizar
+- `:href`/`:src` con URLs de usuario sin validar (`javascript:`, `data:`)
+- Secreto en el bundle del cliente (`VITE_*`, `runtimeConfig` `public` de Nuxt)
+- Endpoint de servidor sin validación de entrada (Nuxt Nitro)
+- `localStorage`/`sessionStorage` para tokens de sesión
+- Desestructurar props reactivas en Vue < 3.5 (rompe la reactividad)
+- Reemplazo del objeto de `reactive()` (rompe los watchers)
+- Watcher cuya fuente rastrea el objeto ref en lugar de `.value`
+
+### ALTO (debería corregirse)
+
+- Composable con efectos secundarios a nivel de módulo
+- Falta de limpieza en un composable (watcher, interval, listener)
+- `v-for` sin `:key` o con `key={index}`
+- `v-if` + `v-for` en el mismo elemento
+- Mutación de props
+- Falta de validación de props
+- Guard de ruta que retorna false sin redirección
+- `useRoute().params` desestructurado a nivel superior (snapshot)
+- `v-model` enlazado a un computed sin setter
+- Violaciones de accesibilidad (labels faltantes, elementos interactivos no semánticos)
+- Mutación directa de propiedades del store fuera de las actions
+
+### MEDIO (a considerar)
+
+- Options API en código Vue 3 nuevo
+- Componente de más de 300 líneas
+- `v-show` donde `v-if` es más apropiado (o viceversa)
+- Falta de `:max` en `<KeepAlive>`
+- Falta de `shallowRef` para datos grandes que se reemplazan
+- Validación a medida en lugar de una librería de formularios probada
+- `defineExpose` exponiendo más de lo necesario
+- `inheritAttrs` sin deshabilitar cuando se usa `v-bind="$attrs"`
+
+## Verificaciones automatizadas que se ejecutan
+
+```bash
+# Lint (requerido)
+npx eslint . --ext .vue,.ts,.js
+
+# Typecheck específico de Vue
+vue-tsc --noEmit
+
+# Reglas de seguridad específicas
+npx eslint . --rule 'vue/no-v-html: warn' \
+              --rule 'vue/no-template-target-blank: error'
+
+# Cadena de suministro
+npm audit
+```
+
+Si `eslint-plugin-vue` o `vue-tsc` no está configurado, la revisión marcará la carencia como un problema de configuración ALTO y continuará.
+
+## Ejemplo de uso
+
+````text
+Usuario: /revisar-vue
+
+Agente:
+# Informe de revisión de código Vue
+
+## Archivos revisados
+- src/components/UserCard.vue (modificado)
+- src/composables/useUser.ts (nuevo)
+- src/stores/useUserStore.ts (modificado)
+
+## Resultados del lint
+PASA: eslint limpio
+PASA: vue-tsc limpio
+
+## Hallazgos
+
+[CRÍTICO] v-html sin sanitizar
+Archivo: src/components/UserCard.vue:15
+Problema: la bio controlada por el usuario se renderiza como HTML crudo vía v-html.
+Por qué: XSS mediante etiquetas script almacenadas en la entrada del usuario.
+Corrección: sanitizar con DOMPurify o renderizar como texto:
+```vue
+<script setup>
+import DOMPurify from "dompurify";
+const safeBio = computed(() => DOMPurify.sanitize(user.bio));
+</script>
+<template>
+  <div v-html="safeBio" />
+</template>
+```
+
+[ALTO] Watcher en composable sin limpieza
+Archivo: src/composables/useUser.ts:22
+Problema: el callback de `watch` lanza el fetch sin AbortController; respuestas obsoletas pueden sobrescribir datos más nuevos.
+Corrección: usar onCleanup para abortar:
+```ts
+watch(userId, async (newId, _old, onCleanup) => {
+  const controller = new AbortController();
+  onCleanup(() => controller.abort());
+  const data = await fetch(`/api/users/${newId}`, { signal: controller.signal });
+  user.value = await data.json();
+});
+```
+
+## Resumen
+- CRÍTICO: 1
+- ALTO: 1
+- MEDIO: 0
+
+Recomendación: FALLA: bloquear el merge hasta corregir el hallazgo CRÍTICO
+````
+
+## Criterios de aprobación
+
+| Estado | Condición |
+|---|---|
+| PASA: Aprobar | Sin hallazgos CRÍTICOS ni ALTOS |
+| ADVERTENCIA: Precaución | Solo hallazgos MEDIOS (merge con cautela) |
+| FALLA: Bloquear | Se encontraron hallazgos CRÍTICOS o ALTOS |
+
+## Integración con otros comandos
+
+- Ejecuta primero el comando de build de tu proyecto si el build está roto
+- Ejecuta los tests para asegurar que los tests de componentes pasan
+- Ejecuta `/revisar-vue` antes de hacer merge de código Vue
+- Usa `/control-calidad` para los aspectos no específicos de Vue del mismo PR
+
+## Relacionado
+
+- Agente: `agents/revisor-vue.md`
+- Agente complementario: `agents/revisor-typescript.md` (ejecutar en paralelo para TS/JS relacionado con Vue)
+- Skills: `skills/patrones-vue/`
+- Reglas: `rules/vue/`

package/vendor/theus-arsenal/commands/salud-skills.md

@@ -0,0 +1,52 @@
+---
+description: Muestra el panel de salud del portafolio de skills con gráficas y analítica.
+argument-hint: [--panel <nombre> | --json]
+---
+
+# Panel de salud de skills
+
+Muestra un panel de salud completo para todas las skills del portafolio: sparklines de tasa de éxito, agrupación de patrones de fallo, enmiendas pendientes e historial de versiones.
+
+## Implementación
+
+Ejecuta la utilería de salud de skills en modo panel. El motor de Theus inyecta `THEUS_PLUGIN_ROOT` al cargar el comando; fuera de ese contexto (ejecución manual), resuélvela con `scripts/lib/resolve-theus-root.js` del arsenal, que centraliza el orden de búsqueda (variable de entorno → instalación estándar bajo `~/.theus/plugins` → fallback a `~/.theus`).
+
+```bash
+node "${THEUS_PLUGIN_ROOT}/scripts/skills-health.js" --dashboard
+```
+
+Solo un panel específico:
+
+```bash
+node "${THEUS_PLUGIN_ROOT}/scripts/skills-health.js" --dashboard --panel failures
+```
+
+Salida legible por máquina:
+
+```bash
+node "${THEUS_PLUGIN_ROOT}/scripts/skills-health.js" --dashboard --json
+```
+
+Si el script no está disponible en la instalación, no prometas el panel gráfico: genera un resumen manual leyendo el estado persistido del arsenal bajo `~/.theus/arsenal/` (métricas de skills, enmiendas y versiones, si existen) e indica que la utilería `scripts/skills-health.js` no está instalada.
+
+## Uso
+
+```
+/salud-skills                    # Vista completa del panel
+/salud-skills --panel failures   # Solo el panel de agrupación de fallos
+/salud-skills --json             # Salida JSON legible por máquina
+```
+
+## Qué hacer
+
+1. Ejecutar el script `skills-health.js` con el flag `--dashboard` (pasando los flags de `$ARGUMENTS` si los hay)
+2. Mostrar la salida al usuario
+3. Si alguna skill está en declive, resaltarla y sugerir ejecutar `/evolucionar`
+4. Si hay enmiendas pendientes, sugerir revisarlas
+
+## Paneles
+
+- **Tasa de éxito (30d)** — sparklines con la tasa de éxito diaria por skill
+- **Patrones de fallo** — causas de fallo agrupadas con gráfica de barras horizontal
+- **Enmiendas pendientes** — propuestas de enmienda a la espera de revisión
+- **Historial de versiones** — línea de tiempo de snapshots de versión por skill