Guía de contribución — Shell Sentinel
Este resumen sintetiza las políticas internas que rigen la colaboración en Shell Sentinel: estructura del proyecto, estándares de documentación y mantenimiento de la experiencia web. Cualquier contribución debe seguir estas pautas para proteger la coherencia del producto.
Principios generales
- Aplicación orientada a terminal con sesiones SSH/SFTP persistentes y un asistente IA conversacional.
- Ecosistema en Python 3.12, TUI con Textual 8.2.8, Strands Agents 1.61.1 con Strands Agents Tools 0.8.9, transportes MCP sobre
mcp2.x y herramientas MCP como Firecrawl. - Dependencias gestionadas con
pyproject.tomly lockfiles pip-tools (make lock,make install). - El trabajo diario se apoya en
make install,make format,make lint,make testymake run. - CI en GitHub Actions (lint + tests en Python 3.12) en cada pull request vía
.github/workflows/ci.yml.
Configuración y contenido
- Toda configuración vive en
conf/(evita hardcodear valores en el código). - Nuevas cadenas deben añadirse en
conf/locales/y utilizar_("clave")al referenciarlas. - El manual de usuario debe mantenerse en EN/ES/DE siempre que cambie un flujo.
- Documenta los proveedores personalizados en la guía técnica correspondiente y enlázalos desde la web.
Plugins y extensibilidad
- Los plugins se cargan desde
plugins/; cada uno debe registrar comandos, traducciones y documentación local. - No mezcles la documentación específica de un plugin con los manuales generales.
- Respetar los prompts sistema y evitar duplicar conexiones SSH/SFTP fuera de las tools oficiales.
Política de documentación web
- La web en
website/es parte integral del producto y debe reflejar cada cambio funcional o narrativo. - Cuando se actualicen manuales, comandos o proveedores, sincroniza el contenido del sitio (secciones, tarjetas, enlaces y traducciones).
- Los manuales en línea usan las páginas HTML de
website/manuals/; duplica cambios relevantes desdedocs/.
Suite de pruebas
make testejecuta las pruebas unitarias más la capa end-to-end offline (tests/e2e/offline, marcadore2e_offline): la app Textual real,AgentRuntimeystrands.Agentcontra un servidor SSH/SFTP en proceso con un modelo con guion, así que no necesita claves y corre en CI. También arranca servidores MCP reales (un servidorstdiocon guion y endpoints HTTP locales) para comprobar las llamadas a tools, los diagnósticos de arranque y la limpieza de procesos.make test-e2eejecuta solo esa capa.make test-e2e-live(tests/e2e/live, marcadore2e) ejecuta escenarios de operador contra los proveedores reales; requiereRUN_E2E=1másOPENAI_API_KEY,MISTRAL_API_KEYy/oGEMINI_API_KEY, limita las llamadas al modelo por prueba y nunca corre en CI. Sus escenarios MCP ejecutan el servidor real de Firecrawl y necesitanFIRECRAWL_API_KEYy Node.js (npx).make test-mistralconserva las pruebas PoC de Mistral (marcadormistral, requiereMISTRAL_API_KEY); están marcadas comoe2epara quemake testnunca consuma tokens.
Flujo recomendado
- Activar entorno virtual (
python3.12 -m venv .venv, luegosource .venv/bin/activate). - Instalar dependencias (
make install). - Tras cambios:
make format,make lint,make test(obligatorio antes de abrir PR); añademake test-e2e-livesi tocas la TUI, el runtime del agente o un proveedor. - Validar la TUI con
make runy la web conmake website-serve.
Consulta el portal interno de políticas para mayor detalle. Tras cada contribución, verifica que web, manuales y repositorio permanezcan coherentes.