🕵️‍♂️ Steward CLI

Herramienta CLI profesional para explorar, analizar y auditar la arquitectura de monorepos con PNPM y proyectos Python.

Steward es un explorador interactivo que visualiza las dependencias de tu monorepo (JavaScript/TypeScript) o ecosistema Python, detecta vulnerabilidades de seguridad y verifica versiones obsoletas en tiempo real mediante un dashboard local con modo oscuro y actualizaciones en vivo.

✨ Características Principales

📊 Visualización Interactiva

• Diagrama de flujo con ReactFlow mostrando apps, libs, herencias y catálogos
• Navegación intuitiva con zoom, pan y reorganización de nodos
• Indicadores visuales de relaciones entre paquetes (workspace, catalog)
• Modo oscuro completo para trabajar de noche 🌙

🐍 Soporte Multi-Lenguaje

• JavaScript/TypeScript: Monorepos PNPM con soporte completo de catalogs
• Python: Requirements.txt, Poetry (pyproject.toml), Pipfile y setup.py
• Detección automática del tipo de proyecto

📑 Exploración de PNPM Catalogs

• Visualización de todos los catálogos definidos en pnpm-workspace.yaml
• Detecta dependencias obsoletas ("fantasmas") no usadas por ningún paquete
• Muestra qué proyectos consumen cada catálogo

🛡️ Auditoría de Seguridad Inteligente

• PNPM: Integración con pnpm audit
• Python: Soporte para pip-audit y safety
• Modal de Reporte Detallado con mitigaciones sugeridas y agrupación de CVEs
• Indicadores visuales de severidad (Critical, High, Medium, Low)

🔍 Verificación de Versiones

• Compara versiones locales vs. últimas en NPM/PyPI
• Verificación individual o masiva de todas las dependencias
• Indicadores de versiones obsoletas con recomendaciones

🎭 Detección Automática

• Identifica proyectos E2E, apps, librerías y entornos Poetry
• Análisis de cobertura de tests (si existe coverage-summary.json)
• Detección de conflictos de versiones entre paquetes

⚡ Live Reload

• Refresca automáticamente el dashboard tras cambios en:
  • package.json
  • pnpm-workspace.yaml
  • requirements.txt
  • pyproject.toml

📦 Instalación y Uso

No necesitas configurar nada. Navega al directorio de tu monorepo (donde está pnpm-workspace.yaml, requirements.txt o pyproject.toml) y ejecuta:

Opción A: Ejecución directa (Recomendada)

Usando npx, descargarás y ejecutarás siempre la última versión sin instalar nada globalmente:

npx uor-steward-cli

Opción B: Instalación global

Si prefieres tener el comando disponible permanentemente:

npm install -g uor-steward-cli
steward

Opción C: Con opciones adicionales

# Sin abrir navegador automáticamente
npx uor-steward-cli --no-browser

# En puerto personalizado
npx uor-steward-cli --port=8080

# Combinar opciones
npx uor-steward-cli --no-browser --port=8080

🚀 Guía de Inicio Rápido

Para Monorepos PNPM

1. Navega a tu monorepo:

   cd /path/to/your/monorepo

2. Ejecuta Steward:

   npx uor-steward-cli

3. Se abrirá automáticamente tu navegador en http://localhost:13042

4. Explora:

   • Diagrama de flujo: Visualiza la arquitectura de tu monorepo
   • Sidebar derecho: Revisa tus catálogos PNPM
   • Tabla inferior: Analiza todas las dependencias consolidadas

Para Proyectos Python

1. Navega a tu proyecto Python:

   cd /path/to/your/python-project

2. Ejecuta Steward:

   npx uor-steward-cli

3. Steward detectará automáticamente tus archivos:

   • requirements.txt
   • requirements/*.txt (con herencias -r)
   • pyproject.toml (Poetry)
   • Pipfile
   • setup.py

🎨 Interfaz del Dashboard

Header

• Nombre del proyecto: Detectado automáticamente
• Tipo de proyecto: PNPM Monorepo o Python Project
• Botón de tema: Alterna entre modo claro y oscuro
• Indicador Live Reload: Muestra cuando hay cambios detectados

Diagrama de Flujo (Parte Superior)

• Nodos de Apps: 🚀 (color verde/naranja según proyecto)
• Nodos E2E: 🎭 (color morado)
• Nodos de Catálogos: 📑 (color gris con borde punteado)
• Conexiones: Líneas animadas mostrando dependencias

Tabla de Dependencias (Parte Inferior)

| Columna | Descripción | |---------|-------------| | Librería | Nombre del paquete (⚠️ indica conflictos de versión) | | Tipo | Dependency, DevDependency, Production, Development, Testing | | Consumidores | Chips coloreados mostrando qué proyectos lo usan | | Versión Local | Badge con color según tipo (catalog, workspace, normal) | | Seguridad | Se llena al ejecutar auditoría (✅ Seguro / 🚨 Vulnerable) | | Última en NPM/PyPI | Botón para verificar versión más reciente |

Botones de Acción

• 🔍 Buscar: Filtra la tabla de dependencias
• 📥 Exportar CSV: Descarga la tabla completa
• 🛡️ Auditar Seguridad: Ejecuta análisis de vulnerabilidades
• ⚡ Verificar Todas: Consulta NPM/PyPI para todas las dependencias
• ⛔ Cancelar: Detiene la verificación masiva en curso

💡 Casos de Uso

1. Detectar Dependencias Obsoletas en Catálogos

Problema: Tienes dependencias en tu pnpm-workspace.yaml que ya no usa ningún paquete.

Solución:

1. Abre Steward en tu monorepo
2. Revisa el sidebar de "PNPM Catalogs"
3. Busca chips con 👻 OBSOLETO (fondo rojo)
4. Elimina esas dependencias del YAML para mantener limpio tu catálogo

2. Auditar Vulnerabilidades

Problema: Necesitas saber si tus dependencias tienen vulnerabilidades conocidas.

Solución:

1. Haz clic en 🛡️ Auditar Seguridad
2. Steward ejecutará pnpm audit (o pip-audit para Python)
3. Las filas con vulnerabilidades se destacarán en rojo
4. Haz clic en los chips rojos para ver detalles en el modal
5. Sigue las recomendaciones de versión segura

3. Detectar Conflictos de Versiones

Problema: Múltiples versiones de la misma librería en tu monorepo.

Solución:

1. La tabla mostrará ⚠️ junto al nombre de librerías con conflictos
2. Las filas con conflicto tendrán fondo amarillo
3. Revisa las versiones en la columna "Versión Local"
4. Considera alinear todas a una sola versión o usar catálogos

4. Actualizar Dependencias

Problema: Necesitas saber cuáles de tus dependencias están desactualizadas.

Solución:

1. Haz clic en ⚡ Verificar Todas
2. Steward consultará NPM/PyPI para cada dependencia
3. Verás badges rojos/amarillos/verdes indicando:
   • 🔴 Rojo: Muy desactualizada (major version)
   • 🟡 Amarillo: Desactualizada (minor/patch)
   • 🟢 Verde: Actualizada
4. Haz clic en versiones individuales para actualizar selectivamente

🎯 Arquitectura del Proyecto

steward-cli/
├── index.js              # Entry point del CLI
├── lib/
│   ├── constants.js      # Sistema de constantes centralizadas
│   ├── extractors.js     # Lectura de archivos (PNPM, Python)
│   ├── processors.js     # Transformación de datos
│   ├── flow-generator.js # Generación de nodos ReactFlow
│   ├── html-generators.js # Construcción de HTML
│   └── server.js         # Servidor HTTP y APIs
└── public/
    ├── client.js         # Lógica del navegador
    └── styles.css        # Sistema de diseño completo

Flujo de Datos

Usuario ejecuta CLI
    ↓
index.js detecta directorio
    ↓
server.js inicia HTTP server
    ↓
detectProjectType() → PNPM o Python?
    ↓
extractors.js lee archivos
    ↓
processors.js consolida datos
    ↓
flow-generator.js crea nodos/edges
    ↓
html-generators.js construye UI
    ↓
client.js maneja interacciones

🔧 Troubleshooting

El puerto está ocupado

Problema: ⚠️ El puerto 13042 está ocupado

Solución:

# Usa un puerto diferente
npx uor-steward-cli --port=8080

# O cierra otras instancias de Steward
pkill -f steward

No detecta mi proyecto

Problema: "No se detectó un monorepo PNPM ni un proyecto Python válido"

Solución:

1. Asegúrate de estar en el directorio raíz del proyecto
2. Verifica que existe uno de estos archivos:
   • pnpm-workspace.yaml (PNPM)
   • requirements.txt (Python)
   • pyproject.toml (Python)
   • Pipfile (Python)

La auditoría no funciona

Problema: Error al ejecutar pnpm audit o pip-audit

Solución PNPM:

# Asegúrate de tener PNPM instalado
npm install -g pnpm

# Verifica que tu lockfile esté actualizado
pnpm install

Solución Python:

# Instala pip-audit
pip install pip-audit

# O usa safety como alternativa
pip install safety

Live Reload no funciona

Problema: Los cambios en archivos no se reflejan

Solución:

• Presiona F5 manualmente para refrescar
• Asegúrate de guardar los archivos después de editarlos
• En algunos sistemas, el file watcher puede tener limitaciones

🤝 Contribuir

¿Encontraste un bug? ¿Tienes una idea para mejorar Steward? ¡Las contribuciones son bienvenidas!

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/amazing-feature)
3. Commit tus cambios (git commit -m 'Add amazing feature')
4. Push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

📝 Licencia

MIT © mirrabenjamin

🙏 Agradecimientos

• ReactFlow - Por la increíble librería de diagramas
• PNPM - Por el mejor gestor de paquetes para monorepos
• Comunidad de Node.js y Python - Por las herramientas de auditoría

📚 Documentación Adicional

• Documentación de Arquitectura - Detalles técnicos de los módulos
• Guía de Desarrollo - Para contribuidores

¿Te gusta Steward? ⭐ Dale una estrella en GitHub y compártelo con tu equipo!