75 lines
3.6 KiB
Markdown
75 lines
3.6 KiB
Markdown
# 🧬 ADN Tools (Núcleo Autónomo)
|
|
|
|
## Resumen Ejecutivo
|
|
`tools/adn` es el motor de ejecución y automatización del sistema **ADN (Artificial DNA)**. Implementa la lógica necesaria para garantizar la "Armonía Integral" de la infraestructura mediante validación proactiva, gestión de eventos y protocolos de ejecución autónomos. Actúa como el puente técnico entre las especificaciones declarativas (hebras `.md`) y la realidad operativa del servidor.
|
|
|
|
---
|
|
|
|
## 🔍 Análisis Estructural
|
|
|
|
### Arquitectura
|
|
El proyecto sigue un patrón **Modular y Dirigido por Eventos**:
|
|
- **Entry Point**: `tools/adn.rb` centraliza la interfaz de línea de comandos (CLI).
|
|
- **Bus de Eventos**: `ADN::Eventos` (Singleton) gestiona la comunicación desacoplada entre componentes.
|
|
- **Motor de Triggers**: `ADN::Triggers` (Singleton) orquestra acciones automáticas basadas en la configuración de `adn/triggers.yml`.
|
|
- **Estrategia de Subcomandos**: Cada funcionalidad mayor reside en su propio archivo `subcomando_*.rb`, facilitando la extensibilidad.
|
|
|
|
### Archivos Críticos
|
|
1. **`adn.rb`**: El orquestador principal. Si este falla, se pierde la interfaz de gestión.
|
|
2. **`adn/eventos.rb`**: El "sistema nervioso". Permite que un cambio en una bitácora dispare validaciones o backups.
|
|
3. **`adn/validador.rb`**: El "guardián" de la calidad. Protege la integridad de las bitácoras y fichas de nodos.
|
|
4. **`adn/triggers.rb`**: Implementa la lógica de reacción del sistema.
|
|
|
|
---
|
|
|
|
## ⚙️ Configuración y Tecnologías
|
|
|
|
### Stack Tecnológico
|
|
- **Lenguaje**: Ruby (Enfoque en scripting robusto y legible).
|
|
- **Configuración**: YAML (`adn/triggers.yml` y `tools/adn/config.yml`).
|
|
- **Logging**: JSON estructurado para integración con sistemas de monitoreo externos.
|
|
- **Hooks**: Integración con Git mediante `tools/adn/hooks/pre-commit`.
|
|
|
|
### Comandos Esenciales
|
|
```bash
|
|
# Validar cumplimiento de bitácoras
|
|
./tools/adn/run validador
|
|
|
|
# Ejecutar backup seguro de un nodo
|
|
./tools/adn/run backup <nombre-nodo>
|
|
|
|
# Ver salud del sistema
|
|
./tools/adn/run salud --json
|
|
```
|
|
|
|
---
|
|
|
|
## 🧠 Contexto para IA (Directivas)
|
|
|
|
### Convenciones Proyectuales
|
|
- **Singleton**: Los motores centrales (Eventos, Triggers, Logger) deben accederse siempre mediante su instancia única.
|
|
- **Bitácora-First**: Ninguna acción operativa debe ejecutarse sin antes registrarse en la bitácora del día actual.
|
|
- **Seguridad**: Nunca exponer secretos en `stdout`. Usar `ns8-candados run` para inyección de entorno.
|
|
|
|
### Áreas Delicadas / Deuda Técnica
|
|
- ⚠️ **Sincronización Batch**: El sistema de triggers utiliza `stubs` para muchas acciones de la Fase 2 que aún deben desarrollarse.
|
|
- ⚠️ **Modo Watch**: El validador en tiempo real (basado en `listen`) es una tarea pendiente de la Fase 1.
|
|
- ⚠️ **Métricas**: La extracción de telemetría desde las bitácoras es incipiente y requiere mayor robustez en el parser.
|
|
|
|
---
|
|
|
|
## 🚀 Próximos Pasos
|
|
|
|
### Tareas Prioritarias
|
|
1. **Implementar Triggers**: Desarrollar la lógica real para las 14 acciones definidas en `adn/triggers.yml`.
|
|
2. **Refinar `backup`**: Añadir soporte para protocolos XEN y Rclone dentro del subcomando unificado.
|
|
3. **Dashboard de Salud**: Desarrollar la vista visual de `./tools/adn/run salud --dashboard`.
|
|
|
|
### Preguntas para el Desarrollador
|
|
- ¿Cómo se deben manejar las colisiones de eventos si dos triggers disparan acciones contradictorias?
|
|
- ¿Es necesario persistir el estado del bus de eventos o es puramente efímero?
|
|
- ¿Qué nivel de criticidad tiene el fallo de un trigger en la operación general?
|
|
|
|
---
|
|
*Documentación generada automáticamente siguiendo el estándar `docs/prompt/documentacion.md`.*
|