sdd-es 2.0.0 → 2.5.0

package/skills/vercel-deploy/FLOW.txt

@@ -0,0 +1,334 @@
+================================================================================
+                    SKILL: VERCEL-DEPLOY - FLUJO VISUAL
+================================================================================
+
+                              PUNTO DE ENTRADA
+                                    │
+                                    ▼
+                    ┌──────────────────────────────┐
+                    │   /sdd.desplegar             │
+                    │   O paso 5 de /sdd.implementar│
+                    │   O invocación manual         │
+                    └──────────────────┬────────────┘
+                                       │
+                                       ▼
+
+================================================================================
+                            PASO 1: PRE-CHECKS
+================================================================================
+
+        ┌─────────────────────────────────────────────────────────┐
+        │  Validaciones preliminares (bloquean si fallan)          │
+        └─────────────────────────────────────────────────────────┘
+                │
+        ┌───────┴───────┬──────────┬──────────┐
+        ▼               ▼          ▼          ▼
+    ╔════════╗   ╔══════════╗  ╔═══════╗  ╔═════════╗
+    ║ Check ║   ║ Rama     ║  ║  Sin  ║  ║ Tests  ║
+    ║TOKEN  ║   ║ Limpia   ║  ║Secretos║  ║ Verdes  ║
+    ╚════════╝   ╚══════════╝  ╚═══════╝  ╚═════════╝
+        │            │           │          │
+        ✓ OK        ✓ OK       ✓ OK       ✓ OK
+        │            │           │          │
+        └────────────┴───────────┴──────────┘
+                     │
+           ✅ TODO OK → Continuar
+           ❌ ALGO FALLA → BLOQUEA (exit 1)
+                     │
+                     ▼
+
+================================================================================
+                      PASO 2: AUTO-GENERAR VERCEL.JSON
+================================================================================
+
+        ┌─────────────────────────────────────────────────┐
+        │ Detectar framework y auto-generar configuración  │
+        └─────────────────────────────────────────────────┘
+                         │
+          ┌──────────────┴──────────────┐
+          ▼                             ▼
+    ┌──────────────────────┐   ┌─────────────────────┐
+    │ ¿Existe vercel.json? │   │ ¿Existe package.json│
+    └──────────────────────┘   └─────────────────────┘
+          │                             │
+      SÍ  │ NO                      SÍ  │ NO
+          ▼  │                          ▼  │
+       ✓ Skip │                    ┌────────────┐
+             │                     │ Detectar   │
+             ▼                     │ Framework  │
+    ┌─────────────────┐            └────────────┘
+    │ Auto-generar:   │               │
+    │ • buildCommand  │      ┌────────┼────────┬──────────┬─────────┐
+    │ • outputDir     │      ▼        ▼        ▼          ▼         ▼
+    │ • framework     │    next     react    vue       astro    python
+    └─────────────────┘     │        │        │          │         │
+             │              │        │        │          │         │
+             ▼              ▼        ▼        ▼          ▼         ▼
+         ✅ LISTO       ✓ Conf   ✓ Conf  ✓ Conf    ✓ Conf   ✓ Conf
+                         │        │        │          │         │
+                         └────────┴────────┴──────────┴─────────┘
+                                     │
+                                     ▼
+
+================================================================================
+                          PASO 3: BUILD Y DEPLOY
+================================================================================
+
+        ┌──────────────────────────────────────┐
+        │ Compilar localmente y enviar a Vercel│
+        └──────────────────────────────────────┘
+                │
+        ┌───────┴───────┐
+        ▼               ▼
+    ┌────────┐      ┌──────────────┐
+    │ Build  │      │ Deploy a     │
+    │Local   │      │ Vercel       │
+    │npm run │      │ --prod       │
+    │build   │      │              │
+    └────────┘      └──────────────┘
+        │                   │
+        ▼                   ▼
+    ✓ OK o          ✓ OK → URL capturada
+    ✗ FALLA              o
+                    ✗ FALLA → ERROR (exit 1)
+        │
+    ✗ ERROR          URL: https://proyecto.vercel.app
+      (exit 1)       │
+                     ▼
+
+================================================================================
+                        PASO 4: HEALTH CHECK
+================================================================================
+
+                    ┌──────────────────┐
+                    │ ¿URL responde?   │
+                    │ HTTP 200?        │
+                    └──────────────────┘
+                            │
+                    Intento 1 de 3
+                            │
+                    ┌───────┴────────┐
+                    ▼                ▼
+                 ✓ 200              ✗ No 200
+                 OK                 (502, 503, timeout)
+                 │                      │
+                 ▼                      ▼
+            ✅ ÉXITO           Esperar 5s (backoff)
+            (Ir a PASO 5)      │
+                            Intento 2 de 3
+                               │
+                        ┌──────┴────────┐
+                        ▼              ▼
+                    ✓ 200            ✗ No 200
+                     OK              Esperar 5s
+                     │                   │
+                     ▼               Intento 3 de 3
+                ✅ ÉXITO                │
+                                    ┌───┴────────┐
+                                    ▼            ▼
+                                ✓ 200        ✗ No 200
+                                 OK          (final)
+                                 │               │
+                                 ▼               ▼
+                            ✅ ÉXITO        ❌ FALLA
+                                            (Ir a PASO 5)
+
+================================================================================
+                        PASO 5: ROLLBACK (CONDICIONAL)
+================================================================================
+
+        ┌────────────────────────────┐
+        │ ¿Necesita rollback?        │
+        │ (Health check falló)       │
+        └────────────────────────────┘
+                │
+        ┌───────┴───────┐
+        ▼               ▼
+    ✓ Sí           ✗ No
+    Rollback       (Health OK)
+        │               │
+        ▼               │
+    ┌────────┐      ┌─────────────┐
+    │ Revert │      │ Skip rollback│
+    │ a prev │      │ (normal)    │
+    │deploy  │      └─────────────┘
+    └────────┘              │
+        │                   │
+        ▼                   ▼
+    ✓ OK             ✅ CONTINUAR
+    │                │
+    ├─────────────┬──┘
+    │             │
+    ▼             ▼
+
+================================================================================
+                        PASO 6: REGISTRAR RESULTADO
+================================================================================
+
+        ┌──────────────────────────────┐
+        │ Guardar metadatos del deploy │
+        └──────────────────────────────┘
+                     │
+        ┌────────────┴──────────────┐
+        ▼                           ▼
+    ┌────────────────┐       ┌────────────────┐
+    │ .sdd/estado.json│      │ Log en stdout  │
+    │                │       │                │
+    │ • timestamp    │       │ • Éxito        │
+    │ • URL          │       │ • Tiempo total │
+    │ • status       │       │ • Próximos     │
+    │ • health_check │       │   pasos        │
+    │ • framework    │       └────────────────┘
+    └────────────────┘             │
+            │                       │
+            └───────────┬───────────┘
+                        │
+                        ▼
+                ✅ COMPLETADO
+
+================================================================================
+                         ENTRADA VS SALIDA
+================================================================================
+
+INPUT:
+  • VERCEL_TOKEN (requerido)
+  • VERCEL_PROJECT_ID (opcional)
+  • framework (auto-detectado)
+  • environment (production | staging)
+
+OUTPUT:
+  • deploy_url: "https://proyecto.vercel.app"
+  • health_check: "200 OK" o "FAILED"
+  • timestamp: "2026-06-13T14:30:00Z"
+  • .sdd/estado.json: archivo con metadatos completos
+
+ERROR OUTPUT:
+  • Mensaje de error claro
+  • Instrucciones de remediar
+  • Exit code: 1
+
+================================================================================
+                         MANEJO DE ERRORES
+================================================================================
+
+   PUNTO DE FALLA              ACCIÓN
+   ────────────────────────────────────────────────────────
+   PASO 1: Pre-checks          ❌ BLOQUEA → Usuario debe arreglar
+           │
+           ├─ VERCEL_TOKEN        Instrucciones para generar
+           ├─ Rama limpia         git add . && git commit
+           ├─ Sin secretos        Mueve a .env.local
+           └─ Tests OK            /sdd.implementar
+
+   PASO 3: Build/Deploy        ❌ BLOQUEA → Usuario debe arreglar
+           │
+           ├─ Build falla         npm run build (debug)
+           └─ Deploy falla        Revisa Vercel API
+
+   PASO 4: Health Check        🔄 REINTENTOS AUTOMÁTICOS (3x)
+           │                      ↓
+           └─ Persiste            PASO 5: Rollback automático
+
+   PASO 5: Rollback            ❌ CONTACTA DEVOPS
+                                  (nunca debería fallar)
+
+================================================================================
+                         DIAGRAMA SECUENCIAL
+================================================================================
+
+   PASO 1           PASO 2           PASO 3           PASO 4         PASO 5/6
+   ──────────────────────────────────────────────────────────────────────────
+   Pre-checks   Configuración   Build & Deploy   Health Check   Rollback/Log
+      │              │              │                │              │
+      ├─ Token        ├─ Detect      ├─ Build         ├─ Try 1        ├─ Needed?
+      │              │              │               │              │
+      ├─ Rama        ├─ vercel.json ├─ Deploy        ├─ Try 2        ├─ Revert
+      │              │              │               │              │
+      ├─ Secretos    └─ Ready        └─ Capturar URL  ├─ Try 3        ├─ Log
+      │                                              │              │
+      └─ Tests                                       └─ HTTP 200?    └─ Done
+         │                                               │
+         ▼                                               ▼
+      ✅ OK                                         ✅ OK o ❌ FALLA
+      │                                                  │
+      └──────────────────────────────────────────────────┘
+              Todos los pasos ejecutados
+                      │
+                      ▼
+           🚀 DESPLIEGUE COMPLETADO
+                      │
+                      ▼
+        Mostrar URL, próximos pasos
+        Guardar estado en .sdd/estado.json
+
+================================================================================
+                    FLUJO DE DECISIÓN (IF/THEN)
+================================================================================
+
+SI    VERCEL_TOKEN presente?           NO → ERROR: Generar token
+SÍ    │
+      └─→ SI rama limpia?              NO → ERROR: Commit cambios
+         SÍ    │
+              └─→ SI sin secretos?      NO → ERROR: Mueve secretos
+                 SÍ    │
+                      └─→ SI tests OK?  NO → ERROR: Arregla tests
+                         SÍ    │
+                              └─→ PASO 2: Configuración
+                                        │
+                                        └─→ PASO 3: Deploy
+                                                   │
+                                                   └─→ PASO 4: Health Check
+                                                              │
+                                                    SI OK?   NO?
+                                                    │        └─→ Reintenta (3x)
+                                                    │           │
+                                                    │           SI persiste?
+                                                    │           └─→ PASO 5: Rollback
+                                                    │
+                                                    └─→ PASO 6: Registrar
+                                                               │
+                                                               ▼
+                                                    ✅ COMPLETADO
+
+================================================================================
+                         LÍNEA DE TIEMPO
+================================================================================
+
+00:00  Inicio (/sdd.desplegar)
+       │
+00:05  PASO 1: Pre-checks (timeout: 60s)
+       │
+00:30  PASO 2: Configuración (timeout: 30s)
+       │
+00:35  PASO 3: Build (timeout: 900s/15 min)
+       │      Build local: ~60-120s
+       │      Deploy a Vercel: ~60-90s
+       │
+02:45  PASO 4: Health Check (timeout: 60s)
+       │      Intento 1: ~5s
+       │      Si falla: espera 5s
+       │      Intento 2: ~5s
+       │      Si falla: espera 5s
+       │      Intento 3: ~5s
+       │
+03:00  PASO 5: Rollback (timeout: 300s/si necesario)
+       │      Si health check falló: ~30s
+       │      Si OK: skip
+       │
+03:15  PASO 6: Registrar (timeout: 10s)
+       │
+       ▼
+  FIN TOTAL: ~3-4 minutos (típico)
+  MAX:       ~30 minutos (si hay problemas)
+
+================================================================================
+                              COLORES DE ESTADO
+================================================================================
+
+  🟢 ✅ Verde     → OK, continuar
+  🔴 ❌ Rojo      → Error, bloquea
+  🟡 ⚠️  Amarillo → Advertencia
+  🔵 ℹ️  Azul     → Información
+  🟣 🔄 Púrpura  → En progreso/Reintentando
+
+================================================================================

package/skills/vercel-deploy/INDEX.md

@@ -0,0 +1,276 @@
+# Skill: vercel-deploy
+
+**Despliegue automático en Vercel con pre-checks, health checks y rollback automático.**
+
+Cierra el ciclo idea→producción sin salir del flujo. Diferenciador vs Bolt/v0: verificación independiente **PRE-deploy**, no post-deploy.
+
+---
+
+## 📋 Archivos en este directorio
+
+### `SKILL.md` ⭐ (Principal)
+**Documento maestro** con la especificación completa del skill.
+
+Contenido:
+- Propósito y visión
+- Entrada requerida (VERCEL_TOKEN, variables de entorno)
+- Flujo detallado de 6 pasos (código Bash ejecutable)
+  - PASO 1: Pre-checks (bloquea si hay issues)
+  - PASO 2: Auto-generar vercel.json
+  - PASO 3: Build y deploy a Vercel
+  - PASO 4: Health check con retry y backoff
+  - PASO 5: Rollback automático si falla
+  - PASO 6: Registrar resultado en `.sdd/estado.json`
+- Output visual para el usuario
+- Tabla de manejo de errores
+- Notas de implementación (atomicidad, idempotencia, seguridad)
+
+**Leer esto primero para entender qué hace el skill.**
+
+---
+
+### `deploy.sh` (Ejecutable)
+**Script Bash funcional** que implementa los 6 pasos.
+
+Características:
+- Colores y emojis en el output
+- Manejo robusto de errores
+- Funciones modulares para cada paso
+- Exit codes correctos
+- Logging a `.sdd/estado.json`
+
+Uso:
+```bash
+bash ./skills/vercel-deploy/deploy.sh
+# O si tiene permisos de ejecución:
+./skills/vercel-deploy/deploy.sh
+```
+
+**Para testing y ejecución real del flujo.**
+
+---
+
+### `README.md` (Inicio rápido)
+**Guía de usuario con setup mínimo.**
+
+Contenido:
+- Uso rápido (copy-paste commands)
+- Cómo obtener VERCEL_TOKEN
+- Tabla de errores comunes
+- Próximos pasos post-deploy
+- Invocación (automática vs manual)
+
+**Para usuarios que quieren empezar rápido.**
+
+---
+
+### `CHECKLIST.md` (Pre-requisitos)
+**Checklist interactivo** antes de desplegar.
+
+Contenido:
+- 8 secciones: autenticación, código, seguridad, tests, vercel config, dependencias, comunicación, contingencia
+- Comandos para verificar cada condición
+- Acciones remediales si algo falla
+- Checklist de una línea (copy-paste)
+- Tabla "estado final: all systems go"
+
+**Para verificar que todo está ready antes de desplegar.**
+
+---
+
+### `INTEGRATION.md` (Integración con sdd.implementar)
+**Guía para conectar vercel-deploy en el flujo `/sdd.implementar`.**
+
+Contenido:
+- Overview del flujo (dónde se invoca)
+- Requisitos previos (VERCEL_TOKEN, VERCEL_PROJECT_ID)
+- Configuración en sdd.implementar (YAML frontmatter)
+- Gate humano ("¿Despliego?")
+- Flujo esperado (éxito, fallo, rollback)
+- Ejemplo completo de sdd.implementar.md
+- Archivos generados (.sdd/estado.json, vercel.json)
+- Troubleshooting por escenario
+- Variables de entorno en Vercel Dashboard
+- Monitoreo post-deploy
+
+**Para integrar el skill en tu workflow SDD.**
+
+---
+
+### `INDEX.md` (Este archivo)
+**Mapa de navegación** de toda la documentación.
+
+Contenido:
+- Descripción de cada archivo
+- Qué leer según tu caso de uso
+- Relaciones entre documentos
+
+**Para orientarte en la estructura.**
+
+---
+
+## 🎯 Qué leer según tu caso de uso
+
+### "Quiero desplegar ahora mismo"
+1. Lee [README.md](./README.md) (2 min)
+2. Lee [CHECKLIST.md](./CHECKLIST.md) (5 min)
+3. Ejecuta: `bash ./skills/vercel-deploy/deploy.sh`
+
+### "Quiero entender qué hace el skill"
+1. Lee [SKILL.md](./SKILL.md) (10 min)
+2. Analiza [deploy.sh](./deploy.sh) (5 min)
+3. Revisa ejemplos en [README.md](./README.md)
+
+### "Quiero integrarlo en mi /sdd.implementar"
+1. Lee [INTEGRATION.md](./INTEGRATION.md) (15 min)
+2. Copia la sección YAML del ejemplo
+3. Añade el gate humano en tu workflow
+4. Configura VERCEL_TOKEN
+
+### "Algo falló y necesito troubleshoot"
+1. Consulta tabla de errores en [README.md](./README.md)
+2. Más detalles en [SKILL.md](./SKILL.md) → "Manejo de errores"
+3. Si es de integración, ve a [INTEGRATION.md](./INTEGRATION.md) → "Troubleshooting"
+
+### "Quiero ver el código ejecutable"
+1. Revisa [deploy.sh](./deploy.sh)
+2. Lee comentarios alineados con [SKILL.md](./SKILL.md)
+3. Test localmente con variables mock
+
+---
+
+## ⚡ Flujo de 6 pasos (resumen)
+
+```
+PASO 1: Pre-checks
+  ✓ VERCEL_TOKEN presente
+  ✓ Rama limpia (git)
+  ✓ Sin secretos en src/
+  ✓ Tests verdes
+  ↓ (bloquea si algo falla)
+
+PASO 2: Configuración
+  ✓ Detectar framework (next, react, vue, astro, python...)
+  ✓ Auto-generar vercel.json si no existe
+  ↓
+
+PASO 3: Deploy
+  ✓ Build local: npm run build
+  ✓ Enviar a Vercel: vercel deploy --prod
+  ✓ Capturar URL de salida
+  ↓
+
+PASO 4: Health Check
+  ✓ Retry 3 veces: curl -s $DEPLOY_URL
+  ✓ Esperar backoff si falla (5s entre intentos)
+  ✓ Si HTTP 200: ✅ éxito
+  ↓ (si no, ir a PASO 5)
+
+PASO 5: Rollback
+  ✓ Si health check falla: vercel rollback --prod
+  ✓ Revertir a deploy anterior
+  ✓ Loguear y notificar usuario
+  ↓
+
+PASO 6: Registrar
+  ✓ Guardar metadatos en .sdd/estado.json
+  ✓ Timestamp, URL, status, health_check, framework
+  ✓ Disponible para auditoría y monitoreo
+```
+
+---
+
+## 📦 Input del skill
+
+```env
+# Requerido
+VERCEL_TOKEN=vercel_xxx_abc123...
+
+# Opcional pero recomendado
+VERCEL_PROJECT_ID=prj_xyz123...
+
+# Auto-detectado
+framework=nextjs  # O react, vue, astro, python, etc.
+```
+
+## 📤 Output del skill
+
+```
+🚀 DESPLIEGUE A VERCEL — COMPLETADO
+
+  ✅ Pre-checks completados
+  ✅ Build exitoso
+  ✅ Vercel deployment: https://mi-proyecto.vercel.app
+  ✅ Health check: HTTP 200
+  
+  Tu app está en vivo: https://mi-proyecto.vercel.app
+  Tiempo total: 3m 42s
+
+Próximos pasos:
+  • Comparte la URL
+  • Monitorea por 15 minutos
+  • Ejecuta /sdd.snapshot
+```
+
+---
+
+## 🔐 Seguridad
+
+- ✅ VERCEL_TOKEN nunca se loguea en stdout
+- ✅ Secretos detectados pre-deploy (grep en src/)
+- ✅ .env.local en .gitignore
+- ✅ Credenciales en variables de entorno, no en código
+- ✅ Atomicidad: o todo se despliega o se revierte
+
+---
+
+## 📚 Relaciones entre documentos
+
+```
+INDEX.md (Tú estás aquí)
+  ├─ README.md ← Empezar aquí
+  ├─ CHECKLIST.md ← Antes de desplegar
+  ├─ SKILL.md ← Entender el flujo
+  │   └─ deploy.sh ← Implementación
+  ├─ INTEGRATION.md ← Conectar con sdd.implementar
+  └─ Este mismo archivo
+```
+
+---
+
+## 💡 Tips
+
+1. **Siempre verifica el checklist antes de desplegar** → Lee [CHECKLIST.md](./CHECKLIST.md)
+
+2. **Si algo falla, revisa logs en Vercel Dashboard** → https://vercel.com/dashboard
+
+3. **VERCEL_TOKEN va en .env.local** (nunca en git):
+   ```bash
+   echo 'VERCEL_TOKEN=vercel_xxx_...' >> .env.local
+   ```
+
+4. **El skill es idempotente** → Ejecutar dos veces produce el mismo resultado
+
+5. **Health check reintenta 3 veces automáticamente** → Maneja cold starts
+
+6. **Rollback es automático si health check falla** → Protección contra deployments rotos
+
+---
+
+## 🚀 Próximos pasos
+
+| Quiero... | Ir a... |
+|-----------|---------|
+| Desplegar ahora | [README.md](./README.md) |
+| Entender el flujo | [SKILL.md](./SKILL.md) |
+| Verificar prerequisites | [CHECKLIST.md](./CHECKLIST.md) |
+| Integrar en /sdd.implementar | [INTEGRATION.md](./INTEGRATION.md) |
+| Ver código ejecutable | [deploy.sh](./deploy.sh) |
+
+---
+
+**Versión:** 1.0  
+**Última actualización:** 2026-06-13  
+**Framework:** Bash + Vercel CLI  
+**Estado:** ✅ Listo para usar
+