Caprini Dev

002-deploy-bot/spec.md

SPEC-002 — Deploy bot (SFTP / FTP → hosting estático)

SPEC-002 — Deploy bot (SFTP / FTP → hosting estático)

Id: projects/002-deploy-bot/spec
Estado: borrador — especificación de producto; implementación en projects/002-deploy-bot/deploy.mjs.

Objetivo

Automatizar la publicación del artefacto Astro (dist/) en el hosting del dominio caprini.dev, cuando el proveedor solo expone FTP o SFTP (sin Git deploy ni runners). El flujo debe ser reproducible, sin secretos en el repo y observable (éxito o error registrado en AGENT_PERSISTENT_MEMORY.md).

Requisitos técnicos

  1. Variables de entorno (raíz del repo, archivo .env, ignorado por Git):
    • FTP_HOST — servidor FTP/FTPS.
    • FTP_USER — usuario.
    • FTP_PASS — contraseña (nunca commitear).
    • FTP_REMOTE_DIR — obligatoria: carpeta pública del sitio (donde debe quedar index.html), p. ej. public_html, public o /public (IONOS Webspace). Evita subir al directorio home por error.
  2. Opcionales documentados en .env.example:
    • FTP_USE_SFTP — 1 / true: modo SFTP sobre SSH (ssh2-sftp-client), p. ej. cuando el proveedor solo ofrece SFTP (IONOS Webspace). Mismas variables FTP_HOST, FTP_USER, FTP_PASS; FTP_PORT por defecto 22 en este modo.
    • FTP_PORT — puerto explícito (si no se define: 22 con SFTP, 21 con FTP).
    • FTP_SECURE — solo FTP/FTPS: true para FTPS explícito (TLS) cuando el hosting lo exige; implicit para FTPS implícito.
    • FTP_CLEAR_REMOTE — true | false: si true, vacía el destino remoto antes de subir (sitio “limpio”); si false, solo sube/sobrescribe.
  3. Comando npm: npm run deploy debe ejecutar build y, a continuación, el bot de subida.
  4. Memoria persistente: cada ejecución (éxito o fallo) debe dejar una línea en la bitácora de AGENT_PERSISTENT_MEMORY.md (proyecto 002-deploy-bot), sin incluir credenciales ni rutas sensibles.

Flujo de trabajo

PasoAcción
1npm run build — genera dist/ con Astro.
2El bot conecta por SFTP o FTP/FTPS según FTP_USE_SFTP, usa FTP_REMOTE_DIR (log de ruta remota), y según FTP_CLEAR_REMOTE limpia el destino o solo sube el contenido de dist/ (no una carpeta remota dist/).
3Confirmación visual en consola: mensaje explícito SITE ONLINE en caso de éxito; en error, mensaje claro y código de salida ≠ 0.

Criterios de aceptación

  • Sin .env válido o sin dist/, el comando falla con mensaje entendible (no stack crudo sin contexto).
  • Con credenciales y red correctas, dist/ queda publicado en el destino acordado y la consola muestra SITE ONLINE.
  • Tras cada intento, AGENT_PERSISTENT_MEMORY.md refleja éxito o fracaso en la bitácora.
  • Secretos solo en .env; existe .env.example con placeholders.

Limitaciones y extensiones

  • FTP/FTPS: basic-ftp. SFTP (SSH): ssh2-sftp-client cuando FTP_USE_SFTP=1. El contrato de npm run deploy no cambia.
  • No se versionan backups del remoto; para rollbacks, confiar en Git + nuevo deploy.

Referencias

  • Episodio narrativo: src/content/docs/system/episodes/009-el-puente-hacia-el-hosting.md.
  • Router: fila P1 en src/content/docs/system/DOC_ROUTER.md.
  • Memoria del proyecto: AGENT_PERSISTENT_MEMORY.md.