theus-cli 0.2.83 → 0.2.84

package/vendor/theus-arsenal/skills/patrones-despliegue/SKILL.md

@@ -1,426 +0,0 @@
----
-name: patrones-despliegue
-description: Flujos de despliegue, patrones de pipelines CI/CD, contenedores con Docker, health checks, estrategias de rollback y checklists de preparación para producción en aplicaciones web.
----
-
-# Patrones de despliegue
-
-Flujos de despliegue a producción y buenas prácticas de CI/CD.
-
-## Cuándo activarla
-
-- Al configurar pipelines de CI/CD
-- Al dockerizar una aplicación
-- Al planificar la estrategia de despliegue (blue-green, canary, rolling)
-- Al implementar health checks y probes de readiness
-- Al preparar un lanzamiento a producción
-- Al configurar ajustes específicos por entorno
-
-## Estrategias de despliegue
-
-### Despliegue rolling (por defecto)
-
-Reemplaza las instancias gradualmente — la versión vieja y la nueva corren simultáneamente durante el rollout.
-
-```
-Instancia 1: v1 → v2  (se actualiza primero)
-Instancia 2: v1        (sigue corriendo v1)
-Instancia 3: v1        (sigue corriendo v1)
-
-Instancia 1: v2
-Instancia 2: v1 → v2  (se actualiza segunda)
-Instancia 3: v1
-
-Instancia 1: v2
-Instancia 2: v2
-Instancia 3: v1 → v2  (se actualiza al final)
-```
-
-**Ventajas:** cero downtime, rollout gradual
-**Desventajas:** dos versiones corren a la vez — requiere cambios retrocompatibles
-**Úsalo cuando:** despliegues estándar, cambios retrocompatibles
-
-### Despliegue blue-green
-
-Corre dos entornos idénticos. Cambia el tráfico de forma atómica.
-
-```
-Blue  (v1) ← tráfico
-Green (v2)   ocioso, corriendo la versión nueva
-
-# Tras la verificación:
-Blue  (v1)   ocioso (pasa a ser respaldo)
-Green (v2) ← tráfico
-```
-
-**Ventajas:** rollback instantáneo (vuelves a blue), corte limpio
-**Desventajas:** requiere 2x de infraestructura durante el despliegue
-**Úsalo cuando:** servicios críticos, tolerancia cero a incidencias
-
-### Despliegue canary
-
-Dirige primero un pequeño porcentaje del tráfico a la versión nueva.
-
-```
-v1: 95% del tráfico
-v2:  5% del tráfico  (canary)
-
-# Si las métricas se ven bien:
-v1: 50% del tráfico
-v2: 50% del tráfico
-
-# Final:
-v2: 100% del tráfico
-```
-
-**Ventajas:** detecta problemas con tráfico real antes del rollout completo
-**Desventajas:** requiere infraestructura de partición de tráfico y monitoreo
-**Úsalo cuando:** servicios de alto tráfico, cambios riesgosos, feature flags
-
-## Docker
-
-### Dockerfile multietapa (Node.js)
-
-```dockerfile
-# Etapa 1: instalar dependencias
-FROM node:22-alpine AS deps
-WORKDIR /app
-COPY package.json package-lock.json ./
-RUN npm ci --production=false
-
-# Etapa 2: build
-FROM node:22-alpine AS builder
-WORKDIR /app
-COPY --from=deps /app/node_modules ./node_modules
-COPY . .
-RUN npm run build
-RUN npm prune --production
-
-# Etapa 3: imagen de producción
-FROM node:22-alpine AS runner
-WORKDIR /app
-
-RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
-USER appuser
-
-COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
-COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
-COPY --from=builder --chown=appuser:appgroup /app/package.json ./
-
-ENV NODE_ENV=production
-EXPOSE 3000
-
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
-
-CMD ["node", "dist/server.js"]
-```
-
-### Dockerfile multietapa (Go)
-
-```dockerfile
-FROM golang:1.22-alpine AS builder
-WORKDIR /app
-COPY go.mod go.sum ./
-RUN go mod download
-COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server ./cmd/server
-
-FROM alpine:3.19 AS runner
-RUN apk --no-cache add ca-certificates
-RUN adduser -D -u 1001 appuser
-USER appuser
-
-COPY --from=builder /server /server
-
-EXPOSE 8080
-HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:8080/health || exit 1
-CMD ["/server"]
-```
-
-### Dockerfile multietapa (Python/Django)
-
-```dockerfile
-FROM python:3.12-slim AS builder
-WORKDIR /app
-RUN pip install --no-cache-dir uv
-COPY requirements.txt .
-RUN uv pip install --system --no-cache -r requirements.txt
-
-FROM python:3.12-slim AS runner
-WORKDIR /app
-
-RUN useradd -r -u 1001 appuser
-USER appuser
-
-COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
-COPY --from=builder /usr/local/bin /usr/local/bin
-COPY . .
-
-ENV PYTHONUNBUFFERED=1
-EXPOSE 8000
-
-HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/')" || exit 1
-CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "4"]
-```
-
-### Buenas prácticas de Docker
-
-```
-# Prácticas BUENAS
-- Usa tags de versión específicos (node:22-alpine, no node:latest)
-- Builds multietapa para minimizar el tamaño de la imagen
-- Corre como usuario no-root
-- Copia primero los archivos de dependencias (caché de capas)
-- Usa .dockerignore para excluir node_modules, .git, tests
-- Agrega la instrucción HEALTHCHECK
-- Define límites de recursos en docker-compose o k8s
-
-# Prácticas MALAS
-- Correr como root
-- Usar tags :latest
-- Copiar el repo entero en una sola capa COPY
-- Instalar dependencias de dev en la imagen de producción
-- Guardar secretos en la imagen (usa variables de entorno o un gestor de secretos)
-```
-
-## Pipeline de CI/CD
-
-### GitHub Actions (pipeline estándar)
-
-```yaml
-name: CI/CD
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-      - run: npm ci
-      - run: npm run lint
-      - run: npm run typecheck
-      - run: npm test -- --coverage
-      - uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: coverage
-          path: coverage/
-
-  build:
-    needs: test
-    runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/main'
-    steps:
-      - uses: actions/checkout@v4
-      - uses: docker/setup-buildx-action@v3
-      - uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - uses: docker/build-push-action@v5
-        with:
-          push: true
-          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/main'
-    environment: production
-    steps:
-      - name: Deploy a producción
-        run: |
-          # Comando de despliegue específico de la plataforma
-          # Railway: railway up
-          # Vercel: vercel --prod
-          # K8s: kubectl set image deployment/app app=ghcr.io/${{ github.repository }}:${{ github.sha }}
-          echo "Desplegando ${{ github.sha }}"
-```
-
-### Etapas del pipeline
-
-```
-PR abierto:
-  lint → typecheck → tests unitarios → tests de integración → deploy de preview
-
-Merge a main:
-  lint → typecheck → tests unitarios → tests de integración → build de imagen → deploy a staging → smoke tests → deploy a producción
-```
-
-## Health checks
-
-### Endpoint de health check
-
-```typescript
-// Health check simple
-app.get("/health", (req, res) => {
-  res.status(200).json({ status: "ok" });
-});
-
-// Health check detallado (para monitoreo interno)
-app.get("/health/detailed", async (req, res) => {
-  const checks = {
-    database: await checkDatabase(),
-    redis: await checkRedis(),
-    externalApi: await checkExternalApi(),
-  };
-
-  const allHealthy = Object.values(checks).every(c => c.status === "ok");
-
-  res.status(allHealthy ? 200 : 503).json({
-    status: allHealthy ? "ok" : "degraded",
-    timestamp: new Date().toISOString(),
-    version: process.env.APP_VERSION || "unknown",
-    uptime: process.uptime(),
-    checks,
-  });
-});
-
-async function checkDatabase(): Promise<HealthCheck> {
-  try {
-    await db.query("SELECT 1");
-    return { status: "ok", latency_ms: 2 };
-  } catch (err) {
-    return { status: "error", message: "Base de datos inaccesible" };
-  }
-}
-```
-
-### Probes de Kubernetes
-
-```yaml
-livenessProbe:
-  httpGet:
-    path: /health
-    port: 3000
-  initialDelaySeconds: 10
-  periodSeconds: 30
-  failureThreshold: 3
-
-readinessProbe:
-  httpGet:
-    path: /health
-    port: 3000
-  initialDelaySeconds: 5
-  periodSeconds: 10
-  failureThreshold: 2
-
-startupProbe:
-  httpGet:
-    path: /health
-    port: 3000
-  initialDelaySeconds: 0
-  periodSeconds: 5
-  failureThreshold: 30    # 30 * 5s = 150s de arranque máximo
-```
-
-## Configuración de entornos
-
-### Patrón Twelve-Factor App
-
-```bash
-# Toda la configuración por variables de entorno — nunca en el código
-DATABASE_URL=postgres://user:pass@host:5432/db
-REDIS_URL=redis://host:6379/0
-API_KEY=${API_KEY}           # inyectada por el gestor de secretos
-LOG_LEVEL=info
-PORT=3000
-
-# Comportamiento específico por entorno
-NODE_ENV=production          # o staging, development
-APP_ENV=production           # entorno explícito de la app
-```
-
-### Validación de configuración
-
-```typescript
-import { z } from "zod";
-
-const envSchema = z.object({
-  NODE_ENV: z.enum(["development", "staging", "production"]),
-  PORT: z.coerce.number().default(3000),
-  DATABASE_URL: z.string().url(),
-  REDIS_URL: z.string().url(),
-  JWT_SECRET: z.string().min(32),
-  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
-});
-
-// Validar al arrancar — falla rápido si la configuración está mal
-export const env = envSchema.parse(process.env);
-```
-
-## Estrategia de rollback
-
-### Rollback instantáneo
-
-```bash
-# Docker/Kubernetes: apuntar a la imagen anterior
-kubectl rollout undo deployment/app
-
-# Vercel: promover el despliegue anterior
-vercel rollback
-
-# Railway: redesplegar el commit anterior
-railway up --commit <sha-anterior>
-
-# Base de datos: revertir la migración (si es reversible)
-npx prisma migrate resolve --rolled-back <nombre-de-migracion>
-```
-
-### Checklist de rollback
-
-- [ ] La imagen/artefacto anterior está disponible y etiquetada
-- [ ] Las migraciones de BD son retrocompatibles (sin cambios destructivos)
-- [ ] Los feature flags pueden desactivar funcionalidades nuevas sin deploy
-- [ ] Alertas de monitoreo configuradas para picos en la tasa de errores
-- [ ] Rollback probado en staging antes del lanzamiento a producción
-
-## Checklist de preparación para producción
-
-Antes de cualquier despliegue a producción:
-
-### Aplicación
-- [ ] Todos los tests pasan (unitarios, integración, E2E)
-- [ ] Sin secretos hardcodeados en el código ni en archivos de configuración
-- [ ] El manejo de errores cubre todos los casos límite
-- [ ] Los logs son estructurados (JSON) y no contienen PII
-- [ ] El endpoint de health check devuelve un estado con significado
-
-### Infraestructura
-- [ ] La imagen Docker se construye de forma reproducible (versiones fijadas)
-- [ ] Variables de entorno documentadas y validadas al arranque
-- [ ] Límites de recursos definidos (CPU, memoria)
-- [ ] Escalado horizontal configurado (mín/máx de instancias)
-- [ ] SSL/TLS habilitado en todos los endpoints
-
-### Monitoreo
-- [ ] Métricas de la aplicación exportadas (tasa de peticiones, latencia, errores)
-- [ ] Alertas configuradas para tasa de errores > umbral
-- [ ] Agregación de logs configurada (logs estructurados, buscables)
-- [ ] Monitoreo de uptime sobre el endpoint de salud
-
-### Seguridad
-- [ ] Dependencias escaneadas en busca de CVEs
-- [ ] CORS configurado solo para los orígenes permitidos
-- [ ] Rate limiting habilitado en los endpoints públicos
-- [ ] Autenticación y autorización verificadas
-- [ ] Cabeceras de seguridad configuradas (CSP, HSTS, X-Frame-Options)
-
-### Operaciones
-- [ ] Plan de rollback documentado y probado
-- [ ] Migración de BD probada contra datos de tamaño de producción
-- [ ] Runbook para los escenarios de fallo comunes
-- [ ] Rotación de guardia y ruta de escalamiento definidas