@saulwade/swl-ses 1.0.0

package/comandos/swl/mapear-codebase.md

@@ -0,0 +1,312 @@
+---
+name: swl:mapear-codebase
+description: Analiza el codebase actual en profundidad. Produce un reporte arquitectónico completo en .planning/research/ARQUITECTURA.md con árbol de directorios, tecnologías detectadas, puntos de entrada, dependencias y deuda técnica observable.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+---
+
+# /swl:mapear-codebase — Análisis arquitectónico del codebase
+
+Eres un arquitecto de software senior con visión sistémica. Tu tarea es analizar el codebase existente de forma exhaustiva, sin suponer nada, leyendo el código real. El resultado debe ser un documento que permita a cualquier ingeniero entrar al proyecto sin conocerlo previamente.
+
+## Paso 0 — Carga de habilidades
+
+Carga la habilidad de análisis antes de comenzar:
+
+```
+Skill("mapear-codebase")
+```
+
+Si no existe en el proyecto, busca alternativas como `Skill("codebase-mapper")` o `Skill("systematic-debugging")`. Documenta qué habilidad cargaste.
+
+## Paso 1 — Verificación del entorno
+
+1. Confirma el directorio de trabajo actual con `pwd` o equivalente.
+2. Verifica si existe `.planning/` — si no existe, créalo junto con `.planning/research/`.
+3. Lee `CLAUDE.md` si existe — contiene convenciones importantes del proyecto.
+4. Lee `README.md` o `README.rst` si existe — da contexto rápido del proyecto.
+5. Lee `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, o cualquier manifiesto de dependencias en la raíz.
+
+## Paso 2 — Árbol de directorios
+
+Genera el árbol de directorios del proyecto excluyendo:
+- `node_modules/`, `.venv/`, `venv/`, `__pycache__/`, `.git/`
+- `dist/`, `build/`, `target/`, `*.egg-info/`
+- Archivos binarios y de media
+
+Usa este comando como base y adapta según el sistema operativo detectado:
+
+```bash
+find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' \
+  -not -path '*/__pycache__/*' -not -path '*/.venv/*' \
+  | sort | head -300
+```
+
+Si el proyecto tiene más de 300 archivos, muestra solo directorios hasta 3 niveles de profundidad y lista archivos clave por directorio.
+
+## Paso 3 — Detección de tecnologías
+
+Detecta y documenta:
+
+### Lenguajes de programación
+- Identifica los lenguajes presentes contando extensiones de archivo
+- Determina el lenguaje principal (el que tiene más archivos de código fuente)
+- Detecta versiones especificadas en manifiestos de configuración
+
+### Frameworks y librerías principales
+- Backend: FastAPI, Django, Flask, Express, NestJS, Spring, etc.
+- Frontend: Angular, React, Vue, Svelte, etc.
+- ORM/Base de datos: SQLAlchemy, Prisma, TypeORM, Django ORM, etc.
+- Testing: pytest, Jest, Cypress, etc.
+
+### Infraestructura y configuración
+- Archivos Docker/docker-compose
+- Archivos de CI/CD (.github/workflows/, .gitlab-ci.yml, etc.)
+- Variables de entorno (.env.example, .env.template)
+- Archivos de configuración de despliegue
+
+### Base de datos
+- Tipo de BD (PostgreSQL, MySQL, SQLite, MongoDB, etc.)
+- Archivos de migración (alembic/, migrations/, etc.)
+- Esquemas o modelos existentes
+
+### Verificación de tipos de archivo con Magika (opcional)
+
+Si `magika` está disponible (`magika --version 2>/dev/null`), ejecutar análisis
+de tipos de archivo para detectar inconsistencias:
+
+```bash
+# Detectar archivos con extensión incorrecta o sin extensión
+magika -r . --json 2>/dev/null | python3 -c "
+import json, sys
+for line in sys.stdin:
+    r = json.loads(line)
+    path, label = r.get('path',''), r.get('output',{}).get('label','')
+    ext = path.rsplit('.',1)[-1] if '.' in path else ''
+    # Reportar discrepancias significativas
+    if label == 'python' and ext not in ('py','pyw','pyi'):
+        print(f'  DISCREPANCIA: {path} → detectado como Python (extensión: .{ext})')
+    elif label == 'javascript' and ext not in ('js','mjs','cjs'):
+        print(f'  DISCREPANCIA: {path} → detectado como JavaScript (extensión: .{ext})')
+" 2>/dev/null || true
+```
+
+Si Magika no está instalada, omitir este paso silenciosamente y documentar
+en el reporte: "Magika no disponible — detección por extensión solamente."
+
+Instalar con: `pip install magika` para habilitar detección avanzada.
+
+## Paso 4 — Puntos de entrada
+
+Identifica y documenta TODOS los puntos de entrada al sistema:
+
+1. **Punto de entrada principal**: el archivo que arranca la aplicación (main.py, index.ts, app.py, server.js, Program.cs, etc.)
+2. **Puntos de entrada de API**: archivos de rutas/routers (búscalos con Grep en patrones como `@router`, `app.get`, `@Controller`, `Route::`, etc.)
+3. **Puntos de entrada de workers/crons**: scripts de tareas programadas
+4. **Puntos de entrada de CLI**: comandos disponibles si hay interfaz de línea de comandos
+5. **Puntos de entrada de tests**: cómo se ejecutan los tests (comando, directorio)
+
+Para cada punto de entrada, documenta:
+- Ruta del archivo
+- Propósito
+- Comando para ejecutarlo (si aplica)
+
+## Paso 5 — Análisis de módulos y capas
+
+Identifica la arquitectura de capas del sistema. Detecta patrones como:
+
+- **MVC / MTV**: modelos, vistas, controladores o templates
+- **Hexagonal / Clean Architecture**: dominio, aplicación, infraestructura, interfaz
+- **Feature-based**: módulos agrupados por funcionalidad
+- **Monolito vs microservicios**: si hay múltiples servicios, documentar cómo se comunican
+
+Para cada módulo o carpeta de primer nivel relevante:
+- Nombre y propósito
+- Archivos principales que contiene
+- Dependencias con otros módulos (usa Grep para importaciones cruzadas)
+
+## Paso 6 — Inventario de dependencias externas
+
+Extrae y clasifica las dependencias del manifiesto:
+
+| Dependencia | Versión | Categoría | Propósito detectado |
+|-------------|---------|-----------|---------------------|
+| ... | ... | producción/desarrollo/peer | ... |
+
+Clasifica en:
+- **Críticas**: sin estas el sistema no arranca
+- **Importantes**: funcionalidades principales
+- **Utilitarias**: helpers, formatters, loggers
+- **Desarrollo**: solo para tests y tooling
+
+## Paso 7 — Deuda técnica observable
+
+Sin leer cada archivo en detalle, busca señales de deuda técnica usando Grep:
+
+```
+# Buscar TODOs y FIXMEs
+Grep(pattern="TODO|FIXME|HACK|XXX|DEPRECATED", output_mode="content")
+
+# Buscar dependencias con versión fija pero potencialmente desactualizada
+# Buscar comentarios que sugieren workarounds
+Grep(pattern="workaround|hotfix|temporal|parche", output_mode="content", -i=true)
+```
+
+Documenta:
+- Número de TODOs/FIXMEs encontrados
+- Archivos con mayor concentración de deuda
+- Patrones problemáticos observados (sin profundizar)
+
+## Paso 8 — Riesgos arquitectónicos rápidos
+
+Basándote en lo observado, identifica:
+
+1. **Acoplamiento alto**: módulos que importan de muchos otros módulos
+2. **God files**: archivos de más de 500 líneas (usa `find` + `wc -l`)
+3. **Ausencia de tests**: directorios sin archivos de test
+4. **Configuración hardcodeada**: IPs, URLs, credenciales en código fuente
+5. **Dependencias sin lockfile**: package-lock.json, poetry.lock, Pipfile.lock
+
+Para detectar archivos grandes:
+```bash
+find . -name "*.py" -o -name "*.ts" -o -name "*.js" | \
+  xargs wc -l 2>/dev/null | sort -rn | head -20
+```
+
+## Paso 9 — Generación del reporte ARQUITECTURA.md
+
+Crea o sobreescribe `.planning/research/ARQUITECTURA.md` con la siguiente estructura:
+
+```markdown
+# Arquitectura del codebase — [Nombre del proyecto]
+
+**Fecha de análisis**: [fecha actual]
+**Analizado por**: swl:mapear-codebase
+**Directorio analizado**: [ruta absoluta]
+
+## Resumen ejecutivo
+[3-5 oraciones describiendo el sistema: qué hace, qué tecnologías usa, qué tamaño tiene]
+
+## Árbol de directorios
+[árbol generado en Paso 2]
+
+## Stack tecnológico
+[tabla de tecnologías detectadas en Paso 3]
+
+## Puntos de entrada
+[lista del Paso 4]
+
+## Arquitectura de módulos
+[análisis del Paso 5]
+
+## Dependencias externas
+[tabla del Paso 6]
+
+## Deuda técnica observable
+[hallazgos del Paso 7]
+
+## Riesgos arquitectónicos
+[hallazgos del Paso 8]
+
+## Recomendaciones inmediatas
+[máximo 5 acciones concretas, ordenadas por impacto]
+```
+
+## Paso 10 — Generación de STACK.md
+
+Crea o sobreescribe `.planning/research/STACK.md` con la evaluación del stack detectado:
+
+```markdown
+# Stack tecnológico — [Nombre del proyecto]
+
+**Fecha de análisis**: [fecha actual]
+**Analizado por**: swl:mapear-codebase
+
+## Stack detectado
+
+| Capa | Tecnología | Versión | Fuente de detección |
+|------|-----------|---------|---------------------|
+| Lenguaje principal | [detectado] | [versión] | [manifiesto] |
+| Framework backend | [detectado] | [versión] | [manifiesto] |
+| Framework frontend | [detectado] | [versión] | [manifiesto] |
+| Base de datos | [detectado] | [versión] | [config/migraciones] |
+| ORM | [detectado] | [versión] | [manifiesto] |
+| Testing | [detectado] | [versión] | [manifiesto] |
+| CI/CD | [detectado] | — | [archivos de config] |
+| Contenedores | [detectado] | — | [Dockerfile/compose] |
+
+## Dependencias de producción
+
+[Tabla del Paso 6 filtrada a dependencias de producción, ordenadas por criticidad]
+
+## Dependencias de desarrollo
+
+[Tabla del Paso 6 filtrada a dependencias dev/test]
+
+## Observaciones
+
+[Notas sobre versiones desactualizadas, incompatibilidades potenciales, o dependencias sin lockfile]
+```
+
+## Paso 11 — Generación de TRAMPAS.md
+
+Crea o sobreescribe `.planning/research/TRAMPAS.md` con la deuda técnica y anti-patrones encontrados:
+
+```markdown
+# Trampas y deuda técnica — [Nombre del proyecto]
+
+**Fecha de análisis**: [fecha actual]
+**Analizado por**: swl:mapear-codebase
+
+## TODOs y FIXMEs
+
+| Archivo | Línea | Tipo | Contenido |
+|---------|-------|------|-----------|
+[Resultados del Paso 7, hasta 50 entradas más relevantes]
+
+**Total**: [N] TODOs, [N] FIXMEs, [N] HACKs
+
+## Archivos grandes (>500 líneas)
+
+| Archivo | Líneas | Riesgo |
+|---------|--------|--------|
+[Resultados del Paso 8, archivos que exceden 500 líneas]
+
+## Anti-patrones detectados
+
+[Hallazgos del análisis: N+1 queries, eval/exec, credenciales hardcodeadas, imports circulares, etc.]
+
+## Dependencias con vulnerabilidades conocidas
+
+[Si pip-audit o npm audit están disponibles, ejecutar y reportar. Si no, indicar: "Ejecutar `/swl:auditar-deps` para un análisis completo."]
+
+## Recomendaciones priorizadas
+
+1. [Acción más urgente — seguridad o estabilidad]
+2. [Segunda acción — deuda técnica de alto impacto]
+3. [Tercera acción — mejoras de mantenibilidad]
+```
+
+## Paso 12 — Reporte al usuario
+
+Al terminar, reporta en la conversación:
+
+1. Archivos generados con rutas absolutas:
+   - `.planning/research/ARQUITECTURA.md`
+   - `.planning/research/STACK.md`
+   - `.planning/research/TRAMPAS.md`
+2. Resumen de 5 puntos clave encontrados
+3. El riesgo más crítico detectado (si hay alguno)
+4. Tiempo estimado de lectura total: "Los reportes suman X líneas — ~Y minutos de lectura"
+5. Próximo paso recomendado:
+   - Si el proyecto no tiene `.planning/PROYECTO.md` con datos reales → sugerir `/swl:adoptar-proyecto`
+   - Si ya tiene `.planning/` completo → sugerir `/swl:discutir-fase 1`
+
+## Reglas de comportamiento
+
+- NUNCA modifiques archivos de código fuente durante el análisis — solo lectura.
+- Si un directorio es muy grande (>1000 archivos), muestra estructura y muestreo, no lista completa.
+- Si encuentras credenciales hardcodeadas, documéntalas en el reporte como riesgo CRÍTICO sin mostrar los valores en la conversación.
+- Los reportes deben ser útiles para alguien que nunca vio el proyecto.
+- Si el codebase está vacío o tiene menos de 5 archivos, documenta eso claramente y sugiere `/swl:nuevo-proyecto`.
+- Todos los archivos generados van en `.planning/research/` para no contaminar el código fuente.
+- Si `.planning/research/` no existe, crearlo antes de escribir.

package/comandos/swl/mcp-status.md

@@ -0,0 +1,175 @@
+---
+name: swl:mcp-status
+description: >
+  Health check de servidores MCP, descubrimiento dinamico de herramientas y
+  gestion de conexiones MCP configuradas en swl-ses.
+version: 1.0.0
+tipo: comando
+---
+
+# /swl:mcp-status — Estado y descubrimiento MCP
+
+Reporta el estado de todos los servidores MCP configurados en `.claude/settings.json`,
+lista sus herramientas disponibles y guarda un snapshot para referencia futura.
+
+## Subcomandos disponibles
+
+### Status (health check)
+
+Muestra si cada servidor responde correctamente y cuantas herramientas expone:
+
+```bash
+python scripts/mcp-orchestrator.py status
+```
+
+Salida esperada:
+```
+Estado de servidores MCP:
+--------------------------------------------------------------------
+  code-review-graph            OK    5 tools   1203ms  [stdio]
+
+  Total: 1 servidores, 1 activos, 5 herramientas disponibles
+```
+
+Con traza registrada en `.planning/traces/`:
+```bash
+python scripts/mcp-orchestrator.py status --trace
+```
+
+### Discover (inventario completo)
+
+Lista todas las herramientas de todos los servidores con sus descripciones:
+
+```bash
+python scripts/mcp-orchestrator.py discover
+```
+
+Para un servidor especifico (via pool-manager):
+```bash
+python scripts/mcp-pool-manager.py list-tools code-review-graph
+```
+
+### Find-tool (busqueda de herramientas)
+
+Busca herramientas por nombre o descripcion en todos los servidores activos:
+
+```bash
+python scripts/mcp-orchestrator.py find-tool "review"
+python scripts/mcp-orchestrator.py find-tool "blast radius"
+```
+
+### Summary (ultimo snapshot sin reconectar)
+
+Muestra el ultimo estado guardado sin iniciar conexiones nuevas:
+
+```bash
+python scripts/mcp-orchestrator.py summary
+```
+
+Util en contextos donde no se quiere esperar la reconexion.
+
+### Ping
+
+Verifica conectividad y tiempo de respuesta de un servidor especifico:
+
+```bash
+python scripts/mcp-pool-manager.py ping
+python scripts/mcp-pool-manager.py ping code-review-graph
+```
+
+### Call-tool (llamada directa a herramienta)
+
+Llama una herramienta MCP directamente desde CLI para pruebas:
+
+```bash
+python scripts/mcp-pool-manager.py call-tool code-review-graph <herramienta> '{"arg": "valor"}'
+```
+
+## Salida JSON
+
+Todos los subcomandos aceptan `--json` para salida estructurada:
+
+```bash
+python scripts/mcp-orchestrator.py status --json
+python scripts/mcp-orchestrator.py discover --json | python -m json.tool
+python scripts/mcp-pool-manager.py list-tools --json
+```
+
+## Trazabilidad
+
+Las llamadas MCP pueden instrumentarse con `mcp-telemetry.py`:
+
+```bash
+# Ver trazas de hoy
+python scripts/mcp-telemetry.py report
+
+# Estadisticas de los ultimos 7 dias por servidor/herramienta
+python scripts/mcp-telemetry.py stats --days 7
+
+# Salida JSON para procesamiento
+python scripts/mcp-telemetry.py stats --json
+```
+
+Las trazas se guardan en formato OTLP-lite en `.planning/traces/mcp-YYYY-MM-DD.jsonl`,
+compatible con el sistema de trazabilidad de `telemetria-agentes.js`.
+
+## Uso desde otro script (importacion)
+
+`mcp-telemetry.py` expone `MCPTelemetrySession` para instrumentar sesiones MCP
+desde otros scripts de swl-ses:
+
+```python
+import sys
+sys.path.insert(0, 'scripts')
+from mcp_telemetry import MCPTelemetrySession
+from pathlib import Path
+
+cwd = Path('.')
+server_cfg = {'command': 'python', 'args': ['-m', 'mi_server']}
+
+async def ejemplo():
+    async with MCPTelemetrySession(cwd, 'mi-server', server_cfg) as sess:
+        tools = await sess.list_tools()
+        result = await sess.call_tool('mi_herramienta', {'arg': 'valor'})
+        # La traza se registra automaticamente en .planning/traces/
+```
+
+## Archivos del modulo mcp-swl
+
+| Archivo | Proposito |
+|---------|-----------|
+| `scripts/mcp-pool-manager.py` | Gestor de conexiones — CLI para list-servers, list-tools, ping, call-tool |
+| `scripts/mcp-telemetry.py` | Trazabilidad OTLP-lite — registra y reporta llamadas MCP |
+| `scripts/mcp-orchestrator.py` | Orquestador multi-servidor — status, discover, find-tool, summary |
+| `comandos/swl/mcp-status.md` | Esta documentacion |
+
+## Configuracion de servidores MCP
+
+Los servidores se leen de la clave `mcpServers` en:
+1. `.claude/settings.local.json` (maxima prioridad, no versionado)
+2. `.claude/settings.json` (proyecto, versionado)
+3. `mcp-servers.json` (alternativa independiente)
+
+Formato de configuracion:
+```json
+{
+  "mcpServers": {
+    "mi-server": {
+      "command": "npx",
+      "args": ["-y", "@mcp/mi-server"],
+      "env": { "MI_VAR": "valor" }
+    },
+    "server-http": {
+      "url": "http://localhost:8931/sse"
+    }
+  }
+}
+```
+
+## Cuando usar este comando
+
+- Al iniciar una sesion de trabajo: verificar que los servers MCP esten activos
+- Antes de `/swl:revisar-impacto`: validar que `code-review-graph` responde
+- Al agregar un nuevo MCP server: descubrir sus herramientas con `discover`
+- En debugging: llamar herramientas directamente con `call-tool`
+- En reporting: generar snapshots para documentacion o metricas