# AGENTS.md — Protocolo Operativo y Arquitectura de a2host Guía para agentes de IA que trabajan en este repositorio. El documento rector de requerimientos del sistema se encuentra en [`a2host.md`](a2host.md). Consultarlo ante cualquier duda sobre el alcance funcional. --- ## Snapshot del Proyecto & Restricciones de Hardware - **Propósito:** Panel web ligero para gestionar dinámicamente subdominios de `elingejose.com` en Apache2 sobre un VPS Ubuntu. - **Límite Crítico de Memoria:** El VPS tiene solo **1 GB de RAM**. El panel corre bajo PM2 con tope estricto de memoria (`max_memory_restart: '120M'`) en el puerto `3005`. - **Prohibición de Procesos Pesados:** Prohibido usar Docker, Nginx, frameworks SSR pesados (Next.js/Nuxt) o compiladores en caliente (`ts-node`) en producción. Frontend servido estáticamente (HTML/CSS/JS o Tailwind CDN sin build pesado). - **Servidor Web:** Apache2 nativo (`/etc/apache2/sites-available/` y `/etc/apache2/sites-enabled/`). Módulos activos requeridos: `proxy`, `proxy_http`, `rewrite`, `headers`. - **DNS:** Ya existe wildcard `*.elingejose.com` apuntando a la IP del VPS (`201.32.134.58`). El backend gestiona únicamente el filesystem local y la configuración de Apache2. - **Usuarios del Sistema:** Proceso Node/PM2 corre bajo usuario `ggc` (con `sudo` sin contraseña en `/etc/sudoers.d/ggc`). Apache2 corre bajo `www-data:www-data`. --- ## Divergencia Crítica: Entorno Local vs VPS - ⚠️ **La máquina de desarrollo local (laptop) NO tiene instalado Apache2.** - Si el código invoca `sudo a2ensite` o `sudo apache2ctl` directamente sin abstracción, los tests y la ejecución local fallarán de inmediato. - **Arquitectura de Drivers Requerida:** Todo acceso a Apache y sistema de archivos debe encapsularse en un servicio (ej. `ApacheService` / `SystemManager`) que admita modo simulado (`MOCK_APACHE=true` o cuando no exista binario `apache2ctl`). - En modo mock: - Rutas redirigidas a `./.tmp/apache2/sites-available/` y `./.tmp/apache2/sites-enabled/`. - Raíz web redirigida a `./.tmp/www/`. - Comandos `a2ensite`, `a2dissite`, `apache2ctl` y `systemctl reload` simulados mediante manipulación de symlinks y validación sintáctica básica en memoria/disco. --- ## Comandos Clave | Tarea | Comando | | --- | --- | | Instalar dependencias | `npm install` | | Dev server local (modo mock) | `MOCK_APACHE=true npm run dev` (o `npm start`) | | Correr suite de tests | `npm test` (pruebas con runner nativo `node --test` o Vitest/Jest ligero) | | Test unitario individual | `npm test -- --grep "SubdomainValidation"` (o equivalente del runner) | | Lint / Validación estática | `npm run lint` | | Arranque en producción (VPS) | `pm2 start ecosystem.config.js --env production` | | Guardar estado PM2 | `pm2 save` | | Monitorizar recursos en VPS | `pm2 monit` o `pm2 logs a2host` | Flujo habitual de verificación antes de finalizar cambios: `npm test` → `npm run lint` (debe pasar al 100% sin requerir `sudo` ni binarios de Apache en local). --- ## Reglas de Arquitectura y Modos de Subdominio ### 1. Validación Estricta de Entrada (Anti-Inyección) - **Regex de subdominio:** Exclusivamente `^[a-z0-9-]+$` (máximo 63 caracteres). Prohibido aceptar caracteres especiales, barras o espacios para evitar command injection y path traversal. - **Ejecución de procesos:** Usar siempre `child_process.execFile` o `child_process.spawn` con arrays de argumentos (`['a2ensite', `${subdomain}.conf`]`). **PROHIBIDO** concatenar cadenas con `child_process.exec()`. ### 2. Modo A — Proyecto Web Estático / PHP (Carpeta) - **Directorio:** `/var/www/` - **Archivo inicial:** Generar `/var/www//index.html` de bienvenida si no existe. - **Permisos requeridos (Mandatorio SGID `2`):** - `sudo chown -R ggc:www-data /var/www/` - `sudo chmod -R 2775 /var/www/` *(El bit `2775` asegura que nuevos ficheros creados por `ggc` vía Git/SFTP hereden el grupo `www-data` para que Apache pueda leerlos sin usar sudo).* - **VirtualHost canónico (`/etc/apache2/sites-available/.conf`):** - `` - `ServerName .elingejose.com` - `DocumentRoot /var/www/` - `>`: `Options -Indexes +FollowSymLinks`, `AllowOverride All`, `Require all granted`. ### 3. Modo B — Proxy Inverso por Puerto (Node.js, Python, etc.) - **Rango de puerto válido:** `1024 - 65535`. - **Puertos Reservados (Bloqueo Estricto):** `[22, 80, 443, 3000, 3005, 3306, 5101, 5432]` (incluye Gitea en 3000 y el propio panel en 3005). Tampoco puede reutilizar un puerto ya asignado en otro VirtualHost activo. - **VirtualHost canónico (`/etc/apache2/sites-available/.conf`):** - `` - `ServerName .elingejose.com` - `ProxyPreserveHost On` - `AllowEncodedSlashes NoDecode` - `ProxyPass / http://127.0.0.1:/ nocanon` - `ProxyPassReverse / http://127.0.0.1:/` *(Nota: Usar siempre `127.0.0.1`, nunca `localhost`, para evitar retrasos de resolución IPv6).* ### 4. Protocolo de Validación y Rollback Atómico Al crear o modificar cualquier subdominio: 1. Escribir `/etc/apache2/sites-available/.conf`. 2. Habilitar sitio: `sudo a2ensite .conf`. 3. Validar sintaxis global: `sudo apache2ctl configtest`. 4. **Si `configtest` falla:** - Ejecutar rollback inmediato: `sudo a2dissite .conf` y eliminar el archivo `.conf`. - Si fue Modo A recién creado, limpiar `/var/www/`. - **NUNCA ejecutar `reload` si la sintaxis no es correcta.** - Devolver HTTP 422 con el error exacto retornado por Apache. 5. **Si `configtest` devuelve `Syntax OK`:** - Ejecutar `sudo systemctl reload apache2`. - Devolver HTTP 201 / respuesta exitosa. ### 5. Sitios Protegidos e Inmutabilidad - **Sitios protegidos:** `000-default.conf`, `default-ssl.conf`, `git.conf` (definidos en `PROTECTED_SITES`). - La API debe rechazar con `403 Forbidden` cualquier intento de desactivar, editar o eliminar estos archivos. ### 6. Eliminación Segura - Deshabilitar (`sudo a2dissite .conf`), borrar `.conf` y recargar Apache (`sudo systemctl reload apache2`). - El borrado físico de `/var/www/` solo se ejecuta si el usuario marca explícitamente un checkbox (`deleteFiles: true`). Si es `false`, la carpeta física se preserva intacta. --- ## Configuración y Variables de Entorno (`.env`) Variables obligatorias a documentar en `.env.example`: ```ini # Red y Proceso PORT=3005 NODE_ENV=development BASE_DOMAIN=elingejose.com # Rutas del Sistema WEB_ROOT=/var/www APACHE_SITES_AVAILABLE=/etc/apache2/sites-available APACHE_SITES_ENABLED=/etc/apache2/sites-enabled SYSTEM_USER=ggc # Autenticación Básica del Panel ADMIN_USER=admin ADMIN_PASS=cambiar_password_segura SESSION_SECRET=minimo_32_caracteres_aleatorios_para_cookies_o_jwt # Restricciones PROTECTED_SITES=000-default.conf,default-ssl.conf,git.conf RESERVED_PORTS=22,80,443,3000,3005,3306,5101,5432 # Modo de Operación MOCK_APACHE=false ``` --- ## Configuración PM2 (`ecosystem.config.js`) ```javascript module.exports = { apps: [{ name: 'a2host', script: './src/index.js', instances: 1, autorestart: true, watch: false, max_memory_restart: '120M', env_production: { NODE_ENV: 'production', PORT: 3005, MOCK_APACHE: 'false' } }] }; ``` --- ## VirtualHost del Panel (`panel.elingejose.com`) Plantilla de Apache para exponer la aplicación: ```apache ServerName panel.elingejose.com ProxyPreserveHost On AllowEncodedSlashes NoDecode ProxyPass / http://127.0.0.1:3005/ nocanon ProxyPassReverse / http://127.0.0.1:3005/ ErrorLog ${APACHE_LOG_DIR}/panel_error.log CustomLog ${APACHE_LOG_DIR}/panel_access.log combined ``` --- ## Recursos y Skills en el Repositorio - Skills especializadas disponibles en `.agents/skills/`: - `scrum-multi-agent-orchestration`: Orquestación y contratos entre agentes. - `security-audit` / `web-security-testing`: Auditoría de inyecciones y validaciones. - `modern-ui-design-system` / `responsive-mobile-first`: Pautas visuales y accesibilidad. - No modificar directamente carpetas bajo `.agents/skills/` salvo instrucción explícita del usuario.