a2host/AGENTS.md

8.2 KiB

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. 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/<subdominio>
  • Archivo inicial: Generar /var/www/<subdominio>/index.html de bienvenida si no existe.
  • Permisos requeridos (Mandatorio SGID 2):
    • sudo chown -R ggc:www-data /var/www/<subdominio>
    • sudo chmod -R 2775 /var/www/<subdominio> (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/<subdominio>.conf):
    • <VirtualHost *:80>
    • ServerName <subdominio>.elingejose.com
    • DocumentRoot /var/www/<subdominio>
    • <Directory /var/www/<subdominio>>: 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/<subdominio>.conf):
    • <VirtualHost *:80>
    • ServerName <subdominio>.elingejose.com
    • ProxyPreserveHost On
    • AllowEncodedSlashes NoDecode
    • ProxyPass / http://127.0.0.1:<puerto>/ nocanon
    • ProxyPassReverse / http://127.0.0.1:<puerto>/ (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/<subdominio>.conf.
  2. Habilitar sitio: sudo a2ensite <subdominio>.conf.
  3. Validar sintaxis global: sudo apache2ctl configtest.
  4. Si configtest falla:
    • Ejecutar rollback inmediato: sudo a2dissite <subdominio>.conf y eliminar el archivo .conf.
    • Si fue Modo A recién creado, limpiar /var/www/<subdominio>.
    • 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 <subdominio>.conf), borrar .conf y recargar Apache (sudo systemctl reload apache2).
  • El borrado físico de /var/www/<subdominio> 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:

# 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)

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:

<VirtualHost *:80>
    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
</VirtualHost>

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.