sdd-es 2.0.0 → 2.5.0

package/skills/vercel-deploy/INTEGRATION.md

@@ -0,0 +1,328 @@
+# Integración: vercel-deploy con sdd.implementar
+
+Guía para integrar el skill **vercel-deploy** en el flujo de `/sdd.implementar`.
+
+## Overview
+
+El skill **vercel-deploy** se invoca automáticamente al final del flujo `/sdd.implementar` cuando `deploy.plataforma: vercel` está configurado.
+
+```
+/sdd.implementar
+  ├─ Paso 1: Análisis & planning
+  ├─ Paso 2: Desarrollo iterativo
+  ├─ Paso 3: Testing
+  ├─ Paso 4: Revisión de código
+  └─ Paso 5: DEPLOY → [vercel-deploy skill] ← AQUÍ
+                    ↓
+                Gate humano: "¿Despliego en Vercel?" [sí/no/después]
+                    ↓ sí
+                [Ejecutar 6 pasos de deploy]
+```
+
+## Requisitos previos
+
+### 1. Variable de entorno: VERCEL_TOKEN
+
+El skill requiere `VERCEL_TOKEN` configurado. Dos opciones:
+
+**Opción A: Exportar en el shell (sesión actual)**
+```bash
+export VERCEL_TOKEN="vercel_xxx_abc123..."
+```
+
+**Opción B: Persistente en `.env.local` (recomendado)**
+```bash
+echo 'VERCEL_TOKEN=vercel_xxx_abc123...' >> .env.local
+```
+
+Obtener el token:
+1. Ve a https://vercel.com/account/tokens
+2. Crea un nuevo token con scope **full**
+3. Cópialo y guárdalo
+
+### 2. (Opcional) VERCEL_PROJECT_ID
+
+Si el proyecto ya existe en Vercel:
+```bash
+export VERCEL_PROJECT_ID="prj_xyz123..."
+# O en .env.local:
+echo 'VERCEL_PROJECT_ID=prj_xyz123...' >> .env.local
+```
+
+Obtener project ID:
+1. Ve a https://vercel.com/dashboard
+2. Abre tu proyecto
+3. Ve a Settings > General
+4. Copia el **Project ID**
+
+## Configuración en sdd.implementar
+
+En el archivo `/sdd.implementar.md` (o similar), añade:
+
+### Sección de configuración
+```yaml
+---
+deploy:
+  plataforma: vercel        # ← Activa invocación automática del skill
+  framework: auto           # ← Auto-detect (next, react, vue, astro, etc.)
+  environment: production   # ← O 'staging'
+---
+```
+
+### Gate humano antes de deploy
+Justo antes de invocar el skill:
+
+```markdown
+## ¿Estamos listos para producción?
+
+Checklist final:
+- [ ] Tests pasando localmente
+- [ ] Cambios committeados
+- [ ] Sin secretos en código
+- [ ] Health check en staging (opcional)
+
+**¿Despliego en Vercel?**
+
+[sí] → Ejecutar vercel-deploy
+[no] → Saltar deploy
+[después] → Recordarme luego
+```
+
+### Invocación del skill
+```bash
+# Automática (recomendada)
+/sdd.implementar
+  # ... pasos 1-4 ...
+  # PASO 5: Deploy
+  if [ deploy.plataforma == "vercel" ]; then
+    vercel-deploy  # ← Invoca el skill
+  fi
+
+# O manual en cualquier momento:
+/sdd.desplegar
+/sdd.desplegar --environment staging
+```
+
+## Flujo esperado
+
+### Ejecución exitosa
+```
+🚀 DESPLIEGUE A VERCEL
+
+  ✅ Pre-checks completados
+     ✓ VERCEL_TOKEN presente
+     ✓ Rama limpia
+     ✓ Sin secretos
+     ✓ Tests verdes
+
+  ✅ vercel.json: detectado framework nextjs
+
+  ✅ Build local exitoso
+  ✅ Deploy a Vercel enviado
+     URL: https://mi-proyecto.vercel.app
+
+  ✅ Health check: HTTP 200 OK
+  
+  Tu app está en vivo: https://mi-proyecto.vercel.app
+  Tiempo total: 3m 42s
+
+Próximos pasos:
+  • Comparte URL: https://mi-proyecto.vercel.app
+  • Ejecuta /sdd.snapshot para actualizar estado
+  • Monitorea por 15 minutos
+```
+
+### Fallo y rollback automático
+```
+🚀 DESPLIEGUE A VERCEL
+
+  ✅ Pre-checks completados
+  ✅ Build local exitoso
+  ✅ Deploy a Vercel enviado
+  
+  ⚠️  Health check: HTTP 502 (3 reintentos fallidos)
+  
+  🔄 Ejecutando rollback...
+  ✅ Rollback completado — versión anterior está en vivo
+
+❌ ACCIÓN REQUERIDA:
+  • Revisa los logs en https://vercel.com/dashboard
+  • Diagnostica el error (env vars, memoria, etc.)
+  • Corrije y ejecuta /sdd.desplegar nuevamente
+```
+
+### Fallo en pre-checks
+```
+🔍 PASO 1: Pre-checks
+
+❌ Error: VERCEL_TOKEN no configurado
+
+Instrucciones para generar:
+  1. Ve a https://vercel.com/account/tokens
+  2. Crea un nuevo token con scope 'full'
+  3. Guárdalo:
+     export VERCEL_TOKEN='vercel_xxx_...'
+     # O en .env.local:
+     echo 'VERCEL_TOKEN=vercel_xxx_...' >> .env.local
+```
+
+## Ejemplo: sdd.implementar.md con vercel-deploy
+
+```markdown
+# sdd.implementar
+
+Implementar y desplegar una feature.
+
+---
+
+## Configuración
+
+deploy:
+  plataforma: vercel
+  framework: nextjs
+  environment: production
+
+---
+
+## Paso 1: Análisis
+
+...
+
+## Paso 2: Desarrollo
+
+...
+
+## Paso 3: Testing
+
+...
+
+## Paso 4: Code Review
+
+...
+
+## Paso 5: Deploy
+
+El siguiente paso despliega tu code a Vercel **solo si todo está OK**.
+
+### ¿Estamos listos?
+
+- [ ] Tests pasando
+- [ ] Cambios committeados
+- [ ] Sin secretos en código
+
+**¿Despliego en Vercel?**
+
+```bash
+# Sí → ejecutar skill
+/sdd.desplegar
+
+# No → saltar por ahora
+# Nota: Puedes desplegar manualmente luego con /sdd.desplegar
+```
+
+---
+
+## ✨ Checklist post-deploy
+
+- [ ] Health check verde (HTTP 200)
+- [ ] Compartir URL con testers
+- [ ] Monitorear por 15 minutos
+- [ ] Ejecutar `/sdd.snapshot` para actualizar estado
+```
+
+## Archivos generados post-deploy
+
+Después de un deploy exitoso, el skill crea/actualiza:
+
+### `.sdd/estado.json`
+Metadatos del último despliegue:
+```json
+{
+  "ultimo_despliegue": {
+    "timestamp": "2026-06-13T14:30:00Z",
+    "url": "https://mi-proyecto.vercel.app",
+    "status": "OK",
+    "health_check": "200 OK",
+    "framework": "nextjs"
+  }
+}
+```
+
+### `vercel.json` (auto-generado si no existe)
+Configuración de build y output:
+```json
+{
+  "buildCommand": "npm run build",
+  "outputDirectory": ".next",
+  "framework": "nextjs"
+}
+```
+
+## Troubleshooting
+
+### Error: "VERCEL_TOKEN no configurado"
+
+**Solución:**
+```bash
+export VERCEL_TOKEN="vercel_xxx_abc123..."
+# O:
+echo 'VERCEL_TOKEN=vercel_xxx_abc123...' >> .env.local
+source .env.local
+```
+
+### Error: "Tests fallando"
+
+**Solución:**
+1. Ejecuta tests localmente: `npm test`
+2. Arregla los fallos
+3. Commit: `git add . && git commit -m "Fix tests"`
+4. Reintenta: `/sdd.desplegar`
+
+### Error: "Health check fallando (HTTP 502)"
+
+**Causas posibles:**
+- Aplicación tarda en iniciar (cold start)
+- Variable de entorno faltante en Vercel
+- Servidor no está escuchando en puerto correcto
+
+**Solución:**
+1. Revisa logs en https://vercel.com/dashboard
+2. Configura env vars en Vercel si es necesario
+3. Reintenta el deploy
+
+### Error: "Cambios sin stagear"
+
+**Solución:**
+```bash
+git add .
+git commit -m "Descripción de cambios"
+/sdd.desplegar
+```
+
+## Variables de entorno en Vercel
+
+Si tu aplicación necesita secrets o env vars:
+
+1. Ve a Vercel Dashboard → Settings → Environment Variables
+2. Añade cada variable: `KEY=value`
+3. Las variables están disponibles en build time y runtime
+
+Ejemplo:
+```
+DATABASE_URL=postgres://...
+API_KEY=sk_xxx_...
+NODE_ENV=production
+```
+
+## Monitoreo post-deploy
+
+Después de desplegar, el skill propone:
+
+1. **Compartir URL** con testers y stakeholders
+2. **Monitorear por 15 minutos** usando `/sdd.canary`
+3. **Actualizar estado del producto** con `/sdd.snapshot`
+4. **En caso de issues**: `/sdd.revertir` para rollback manual
+
+---
+
+Para más detalles, ver [SKILL.md](./SKILL.md).

package/skills/vercel-deploy/MANIFEST.md

@@ -0,0 +1,310 @@
+# MANIFEST: Skill vercel-deploy
+
+**Despliegue automático en Vercel con 6 pasos atómicos, health checks y rollback automático.**
+
+Versión: 1.0.0  
+Fecha: 2026-06-13  
+Estado: ✅ Listo para usar
+
+---
+
+## 📦 Contenido del paquete
+
+### Documentación (6 archivos)
+
+| Archivo | Tipo | Tamaño | Propósito |
+|---------|------|--------|----------|
+| **SKILL.md** | Especificación | ~10 KB | Documento maestro: flujo de 6 pasos con código ejecutable |
+| **README.md** | Quick start | ~2 KB | Guía rápida para empezar inmediatamente |
+| **CHECKLIST.md** | Pre-requisitos | ~5 KB | 8 secciones de validación antes de desplegar |
+| **INTEGRATION.md** | Integración | ~8 KB | Cómo conectar con `/sdd.implementar` |
+| **INDEX.md** | Navegación | ~6 KB | Mapa de documentos y rutas de lectura |
+| **FLOW.txt** | Diagrama visual | ~15 KB | Flujo visual ASCII de toda la ejecución |
+
+### Ejecutables (1 archivo)
+
+| Archivo | Tipo | Tamaño | Propósito |
+|---------|------|--------|----------|
+| **deploy.sh** | Script Bash | ~8 KB | Implementación funcional de los 6 pasos |
+
+### Configuración (2 archivos)
+
+| Archivo | Tipo | Tamaño | Propósito |
+|---------|------|--------|----------|
+| **skill.yaml** | Metadata YAML | ~10 KB | Metadatos del skill para registración en SDD |
+| **estado.json.example** | Ejemplo JSON | ~15 KB | Ejemplo de salida: `.sdd/estado.json` generado |
+
+### Navegación (1 archivo)
+
+| Archivo | Tipo | Propósito |
+|---------|------|----------|
+| **MANIFEST.md** | Resumen | Este archivo: índice de contenidos |
+
+---
+
+## 🚀 Inicio rápido
+
+### 1. Verificar requisitos (1 min)
+```bash
+cd c:\Users\usuario\sdd-lite\sdd-lite\skills\vercel-deploy
+grep -l "VERCEL_TOKEN\|npm\|git\|curl" README.md
+```
+
+### 2. Leer documentación (5-10 min)
+```bash
+# Empezar con el README
+cat README.md
+
+# Luego revisar el checklist
+cat CHECKLIST.md
+```
+
+### 3. Configurar VERCEL_TOKEN (2 min)
+```bash
+export VERCEL_TOKEN="vercel_xxx_abc123..."
+# O persistente:
+echo 'VERCEL_TOKEN=vercel_xxx_abc123...' >> .env.local
+```
+
+### 4. Ejecutar el skill (3-4 min)
+```bash
+# Opción A: Script directo
+bash ./skills/vercel-deploy/deploy.sh
+
+# Opción B: Integrado en /sdd.desplegar
+/sdd.desplegar
+```
+
+---
+
+## 📖 Rutas de lectura según tu perfil
+
+### "Quiero desplegar YA" (10 min total)
+1. [README.md](./README.md) — Setup y commands
+2. [CHECKLIST.md](./CHECKLIST.md) — Validar prerequisites
+3. Ejecutar: `bash deploy.sh`
+
+### "Soy arquitecto/DevOps" (30 min total)
+1. [SKILL.md](./SKILL.md) — Especificación completa
+2. [deploy.sh](./deploy.sh) — Revisión de código
+3. [skill.yaml](./skill.yaml) — Metadata y configuración
+4. [FLOW.txt](./FLOW.txt) — Diagrama de flujo
+
+### "Voy a integrar en /sdd.implementar" (25 min total)
+1. [INTEGRATION.md](./INTEGRATION.md) — Cómo conectar
+2. [CHECKLIST.md](./CHECKLIST.md) — Qué validar
+3. [skill.yaml](./skill.yaml) — Configuración YAML
+4. [SKILL.md](./SKILL.md) — Detalles completos
+
+### "Solo necesito un diagrama visual" (5 min)
+1. [FLOW.txt](./FLOW.txt) — Flujo completo
+2. [INDEX.md](./INDEX.md) — Relaciones entre documentos
+
+---
+
+## 🎯 Características principales
+
+✅ **Flujo atómico** — 6 pasos secuenciales bloqueantes  
+✅ **Pre-checks** — Valida VERCEL_TOKEN, rama limpia, sin secretos, tests verdes  
+✅ **Auto-configuración** — Detecta framework (next, react, vue, astro, python)  
+✅ **Health checks** — 3 reintentos automáticos con backoff exponencial  
+✅ **Rollback automático** — Revertir a deploy anterior si falla health check  
+✅ **Observabilidad** — `.sdd/estado.json` con metadatos completos  
+✅ **Seguridad** — Detección de secretos, VERCEL_TOKEN nunca se loguea  
+✅ **Idempotencia** — Ejecutar 2x produce el mismo resultado  
+✅ **UX** — Output visual con emojis, colores, pasos numerados  
+✅ **Documentación** — 9 archivos (docs + ejecutables + ejemplos)
+
+---
+
+## 📋 Flujo de 6 pasos (TL;DR)
+
+```
+1. PRE-CHECKS → Valida VERCEL_TOKEN, rama, secretos, tests
+2. CONFIGURACIÓN → Detecta framework, auto-genera vercel.json
+3. BUILD & DEPLOY → npm run build + vercel deploy --prod
+4. HEALTH CHECK → Verifica HTTP 200 (retry 3x, backoff 5s)
+5. ROLLBACK → Si falla, revertir a deploy anterior (automático)
+6. REGISTRAR → Guardar en .sdd/estado.json
+```
+
+---
+
+## 🔧 Requisitos previos
+
+### Obligatorios
+- ✅ Bash (4+)
+- ✅ Git (2+)
+- ✅ Node.js (18+) con npm
+- ✅ Vercel CLI (`npm install -g vercel`)
+- ✅ curl (7+)
+- ✅ VERCEL_TOKEN (generar en vercel.com/account/tokens)
+
+### Opcionales
+- 🟡 VERCEL_PROJECT_ID (si ya existe en Vercel)
+- 🟡 Notificaciones (Slack, email)
+
+---
+
+## 📊 Estadísticas
+
+| Métrica | Valor |
+|---------|-------|
+| Total de archivos | 9 |
+| Líneas de documentación | ~2,500 |
+| Líneas de código (deploy.sh) | ~250 |
+| Líneas de metadata (skill.yaml) | ~300 |
+| Pasos del flujo | 6 |
+| Pre-checks | 4 |
+| Health check retries | 3 |
+| Documentos para diferentes perfiles | 4 |
+| Duración típica | 3-4 minutos |
+
+---
+
+## ✨ Diferenciadores vs Bolt/v0
+
+| Aspecto | vercel-deploy | Bolt/v0 |
+|--------|---------------|---------|
+| **Pre-deploy checks** | ✅ Sí (4 validaciones) | ❌ No |
+| **Secretos en código** | ✅ Detecta y bloquea | ❌ Puede estar oculto |
+| **Tests** | ✅ Valida antes de deploy | ❌ Después del deploy |
+| **Health check** | ✅ 3 reintentos automáticos | ❌ Manual o inexistente |
+| **Rollback** | ✅ Automático si falla | ❌ Manual |
+| **Observabilidad** | ✅ .sdd/estado.json completo | ❌ Logs en Vercel |
+| **Framework detection** | ✅ Automático | ❌ Manual |
+| **Atomicidad** | ✅ Todo o nada | ❌ Estados intermedios |
+
+---
+
+## 🔐 Seguridad
+
+- ✅ VERCEL_TOKEN nunca se imprime en logs
+- ✅ Grep de secretos comunes (API_KEY, SECRET, password) en src/
+- ✅ Fuerza .env.local en .gitignore
+- ✅ No permite deploy si hay cambios sin stagear
+- ✅ Valida rama limpia ante de proceder
+
+---
+
+## 📌 Cómo se genera .sdd/estado.json
+
+Después de un deploy exitoso, el script crea:
+
+```json
+{
+  "ultimo_despliegue": {
+    "timestamp": "2026-06-13T14:30:00Z",
+    "url": "https://proyecto.vercel.app",
+    "status": "OK",
+    "health_check": "200 OK",
+    "framework": "nextjs"
+  }
+}
+```
+
+Ver ejemplo completo en [estado.json.example](./estado.json.example).
+
+---
+
+## 🔗 Integración con flujos SDD
+
+```yaml
+# En tu sdd.implementar.md:
+deploy:
+  plataforma: vercel
+  framework: auto
+  environment: production
+  skill: vercel-deploy
+```
+
+Gate humano antes de ejecutar:
+```
+¿Despliego en Vercel? [sí/no/después]
+```
+
+---
+
+## 📞 Troubleshooting rápido
+
+| Problema | Solución |
+|----------|----------|
+| VERCEL_TOKEN ausente | Generar en vercel.com/account/tokens |
+| Tests fallando | Ejecutar `/sdd.implementar` nuevamente |
+| Health check 502/503 | Reintenta automáticamente (3x); si persiste, rollback |
+| Build falla | Revisar `npm run build` localmente |
+| Cambios sin stagear | `git add . && git commit` |
+| Secretos en código | Mueve a .env.local |
+
+Ver [CHECKLIST.md](./CHECKLIST.md) para validación completa.
+
+---
+
+## 🎓 Ejemplos de uso
+
+### Uso simple
+```bash
+export VERCEL_TOKEN="vercel_xxx_..."
+bash ./skills/vercel-deploy/deploy.sh
+```
+
+### Integrado en /sdd.implementar
+```bash
+/sdd.implementar
+# ... pasos 1-4 ...
+# PASO 5: Deploy
+# ¿Despliego en Vercel? [sí]
+# → Ejecuta vercel-deploy automáticamente
+```
+
+### Con diferentes ambientes
+```bash
+/sdd.desplegar --environment staging
+/sdd.desplegar --environment production
+```
+
+---
+
+## 📝 Versionamiento
+
+| Versión | Fecha | Cambios |
+|---------|-------|---------|
+| 1.0.0 | 2026-06-13 | Release inicial |
+
+---
+
+## 📚 Referencias
+
+- Vercel Docs: https://vercel.com/docs
+- Vercel API: https://vercel.com/docs/api
+- Vercel CLI: https://vercel.com/cli
+- Deployment best practices: https://vercel.com/docs/concepts/deployments
+
+---
+
+## ✅ Checklist de instalación
+
+- [ ] Descargado en `sdd-lite/skills/vercel-deploy/`
+- [ ] VERCEL_TOKEN generado y guardado
+- [ ] Leer README.md (2 min)
+- [ ] Revisar CHECKLIST.md (5 min)
+- [ ] Ejecutar deploy.sh (3-4 min)
+- [ ] Verificar URL en vivo
+- [ ] Guardar estado en .sdd/estado.json
+
+---
+
+## 🎯 Próximos pasos
+
+1. **Ahora**: Leer [README.md](./README.md)
+2. **Luego**: Revisar [CHECKLIST.md](./CHECKLIST.md)
+3. **Ejecutar**: `bash ./skills/vercel-deploy/deploy.sh`
+4. **Integrar**: En `/sdd.implementar` con [INTEGRATION.md](./INTEGRATION.md)
+5. **Monitorear**: Post-deploy con `/sdd.canary`
+
+---
+
+**Estado:** ✅ Listo para usar  
+**Mantenedor:** SDD Team  
+**Soporte:** Referir a documentación interna  
+

package/skills/vercel-deploy/README.md

@@ -0,0 +1,65 @@
+# Skill: vercel-deploy
+
+Despliegue automático en Vercel con pre-checks, health checks y rollback automático.
+
+## Uso rápido
+
+```bash
+# Generar VERCEL_TOKEN
+export VERCEL_TOKEN="xxx_your_token_xxx"
+
+# Desplegar (automáticamente en /sdd.implementar)
+/sdd.desplegar
+```
+
+## Flujo
+
+1. **Pre-checks**: Validar VERCEL_TOKEN, rama limpia, sin secretos, tests verdes
+2. **vercel.json**: Auto-generar si no existe (detecta framework automáticamente)
+3. **Build & Deploy**: Compilar localmente y enviar a Vercel
+4. **Health Check**: Verificar que la URL responde HTTP 200 (3 reintentos con backoff)
+5. **Rollback**: Revertir a deploy anterior si health check falla
+6. **Log**: Guardar metadatos en `.sdd/estado.json` para auditoría
+
+## Obtener VERCEL_TOKEN
+
+1. Ve a https://vercel.com/account/tokens
+2. Crea un nuevo token con scope **full**
+3. Guárdalo en el entorno:
+   ```bash
+   export VERCEL_TOKEN="vercel_xxx_..."
+   ```
+   O en `.env.local`:
+   ```
+   VERCEL_TOKEN=vercel_xxx_...
+   ```
+
+## Errores comunes
+
+| Error | Solución |
+|-------|----------|
+| VERCEL_TOKEN ausente | Ejecutar `export VERCEL_TOKEN="..."` |
+| Tests fallando | Ejecutar `/sdd.implementar` nuevamente |
+| Health check fallando | Revisar logs de Vercel; revisar env vars |
+| Cambios sin stagear | Ejecutar `git add . && git commit` |
+
+## Próximos pasos post-deploy
+
+- Compartir URL con testers: https://mi-proyecto.vercel.app
+- Monitorear anomalías (15 minutos)
+- Ejecutar `/sdd.snapshot` para actualizar estado del producto
+- Si hay issues: `/sdd.revertir` para rollback manual
+
+## Invocación
+
+**Automática**: PASO final de `/sdd.implementar` (con confirmación humana)
+
+**Manual**: 
+```bash
+/sdd.desplegar
+/sdd.desplegar --environment staging
+```
+
+---
+
+Para detalles completos del flujo de 6 pasos, ver [SKILL.md](./SKILL.md).