omarchy_setup/.docs/AGENTS.md

# AGENTS.md - Guía para Contribuidores y Tareas Pendientes

Este documento está destinado a los desarrolladores (humanos o agentes de IA) que trabajan en el proyecto Omarchy Setup. Contiene un resumen del estado actual, una lista de tareas pendientes y directrices para el desarrollo futuro.

## Análisis del Proyecto

El proyecto "Omarchy Setup" es un script de post-instalación para Arch Linux, diseñado con un enfoque en la modularidad y la facilidad de uso.

- **Orquestador Principal (`omarchy-setup.sh`):** Actúa como el punto de entrada. Presenta un menú interactivo al usuario, gestiona las sesiones de `sudo`, y coordina la ejecución de los diferentes módulos.
- **Módulos (`modules/`):** Cada archivo `.sh` en este directorio encapsula una funcionalidad específica (ej. instalar aplicaciones, configurar Docker, personalizar Zsh). Esta estructura facilita la adición o modificación de tareas sin afectar al resto del sistema.
- **Funciones Comunes (`modules/common.sh`):** Centraliza el código repetitivo, como las funciones de logging, la instalación de paquetes (pacman y AUR), y la creación de backups. Esto promueve la reutilización de código y la consistencia.
- **Interactividad:** El sistema está diseñado para ser interactivo, solicitando confirmación del usuario para acciones importantes, pero también soporta ejecuciones en segundo plano para tareas no interactivas.

## Tareas Pendientes y Mejoras

A continuación se detallan las tareas prioritarias para mejorar la funcionalidad y robustez del proyecto.

### 1. Implementar un Sistema de Dependencias entre Módulos

- **Objetivo:** Evitar fallos cuando un módulo requiere que otro se haya ejecutado previamente (por ejemplo, `ssh-keyring.sh` necesita que `apps.sh` instale `gnome-keyring`).
- **Acción Propuesta:**
    1.  En cada módulo, definir un array o variable que liste sus dependencias. Ejemplo en `ssh-keyring.sh`: `MODULE_DEPS=("apps")`.
    2.  En `omarchy-setup.sh`, antes de ejecutar un módulo, leer esta variable y comprobar si los módulos dependientes ya han sido ejecutados (se podría mantener un registro de módulos completados).
    3.  Si una dependencia no se ha cumplido, informar al usuario y ofrecerle ejecutarla primero.

### 2. Crear un Archivo de Configuración Central (`omarchy.conf`)

- **Objetivo:** Facilitar instalaciones desatendidas y permitir a los usuarios pre-configurar sus preferencias sin modificar los scripts.
- **Acción Propuesta:**
    1.  Crear un archivo `omarchy.conf.example` con pares clave-valor para las opciones personalizables (ej. `INSTALL_DOCKER="true"`, `ZEROTIER_NETWORK_ID="tu_id_de_red"`).
    2.  En `omarchy-setup.sh`, comprobar si existe `omarchy.conf` y cargarlo.
    3.  Modificar los módulos para que lean estas variables de configuración y actúen en consecuencia, saltándose las preguntas interactivas si la opción está definida.

### 3. Añadir Funcionalidad de Desinstalación / Reversión

- **Objetivo:** Permitir a los usuarios deshacer los cambios realizados por un módulo de forma segura.
- **Acción Propuesta:**
    1.  Para cada módulo, crear una función `uninstall_<nombre_modulo>`.
    2.  Esta función debe realizar la acción inversa a la instalación: eliminar paquetes, restaurar archivos de configuración a partir de los backups `.bak` y deshabilitar los servicios correspondientes.
    3.  Añadir una nueva opción en el menú principal para acceder a un sub-menú de desinstalación.

### 4. Implementar Verificaciones Post-Instalación

- **Objetivo:** Aumentar la fiabilidad del script confirmando que el software principal de cada módulo se ha instalado y funciona correctamente.
- **Acción Propuesta:**
    1.  Al final de cada módulo, añadir una pequeña función de `verify_<nombre_modulo>`.
    2.  Esta función debería ejecutar un comando simple para comprobar el estado del software. Ejemplos:
        - **Docker:** `docker --version` y `docker run hello-world`.
        - **Zsh:** `zsh --version` y comprobar que `oh-my-posh` está en el `$PATH`.
        - **ZeroTier:** `sudo zerotier-cli status`.
    3.  Informar al usuario si la verificación ha sido exitosa o ha fallado.

## Directrices para Futuros Desarrollos

- **Modularidad:** Toda nueva funcionalidad debe encapsularse en su propio módulo.
- **Idempotencia:** Los scripts deben poder ejecutarse múltiples veces sin causar efectos secundarios negativos. Comprueba siempre si un paquete ya está instalado o si una configuración ya existe antes de aplicarla.
- **Lenguaje y Estilo:** Todo el código y los comentarios deben estar en **español** para mantener la consistencia del proyecto.
- **Manejo de Errores:** Utiliza las funciones `log_error`, `log_warning` y `log_success` de `common.sh` para proporcionar feedback claro al usuario. Si un comando crítico falla, el script debe salir de forma controlada.
- **Seguridad:** No almacenes información sensible (contraseñas, claves de API) directamente en los scripts. Utiliza ficheros locales como `.zshrc.local` (que está en `.gitignore`) para estos casos.