@saulwade/swl-ses 1.0.0

package/habilidades/deprecacion-migracion/recursos/implementaciones-completas.md

@@ -0,0 +1,220 @@
+# Deprecación y Migración — Implementaciones Completas
+
+## Feature Flags para Migraciones Graduales
+
+```python
+# feature_flags.py — flags para migrar gradualmente
+from enum import Enum
+
+
+class FeatureFlag(str, Enum):
+    MOTOR_BUSQUEDA_OPENSEARCH = "motor_busqueda_opensearch"
+    API_V2_RESPUESTA = "api_v2_respuesta"
+    SESIONES_POSTGRES = "sesiones_postgres"
+
+
+class ServicioFeatureFlags:
+    """Lee feature flags desde la base de datos con caché local."""
+
+    def esta_activo(self, flag: FeatureFlag, contexto: dict | None = None) -> bool:
+        configuracion = self._obtener_config(flag)
+
+        if not configuracion.activo:
+            return False
+
+        if configuracion.porcentaje_rollout < 100:
+            if contexto and "usuario_id" in contexto:
+                hash_usuario = hash(contexto["usuario_id"] + flag.value) % 100
+                return hash_usuario < configuracion.porcentaje_rollout
+
+        return True
+
+
+# Uso en servicio de búsqueda
+class ServicioBusqueda:
+    def __init__(self, flags: ServicioFeatureFlags):
+        self.flags = flags
+        self.es_cliente = ElasticSearchCliente()
+        self.os_cliente = OpenSearchCliente()
+
+    def buscar(self, query: str, usuario_id: str) -> list[Resultado]:
+        if self.flags.esta_activo(
+            FeatureFlag.MOTOR_BUSQUEDA_OPENSEARCH,
+            contexto={"usuario_id": usuario_id},
+        ):
+            return self.os_cliente.buscar(query)
+        else:
+            return self.es_cliente.buscar(query)
+```
+
+---
+
+## Patrón Strangler Fig — Migración de Monolito a Microservicios
+
+```
+Antes:
+  Cliente -> [Monolito] -> BD monolito
+
+Proceso (reemplazar módulo por módulo):
+  Paso 1: Cliente -> [Proxy/API Gateway] -> [Monolito]
+  Paso 2: Cliente -> [Proxy] -> { [Monolito], [Nuevo Servicio Pagos] }
+  Paso 3: Cliente -> [Proxy] -> { [Monolito sin pagos], [Servicio Pagos] }
+  ...
+  Final:  Cliente -> [API Gateway] -> { [Svc Pedidos], [Svc Pagos], [Svc Usuarios] }
+```
+
+```python
+# proxy_router.py — Strangler Fig con feature flags
+class ProxyEstrangulador:
+    """
+    Enruta peticiones al monolito o al nuevo servicio según el feature flag.
+    Permite migración gradual sin cambios en el cliente.
+    """
+
+    def __init__(
+        self,
+        monolito_url: str,
+        flags: ServicioFeatureFlags,
+    ):
+        self.monolito_url = monolito_url
+        self.flags = flags
+        self.servicios_nuevos: dict[str, str] = {}
+
+    def registrar_servicio(self, patron_ruta: str, url_servicio: str) -> None:
+        self.servicios_nuevos[patron_ruta] = url_servicio
+
+    async def enrutar(self, request: Request) -> Response:
+        ruta = request.url.path
+
+        for patron, url_servicio in self.servicios_nuevos.items():
+            if ruta.startswith(patron):
+                flag_nombre = f"nuevo_servicio_{patron.strip('/').replace('/', '_')}"
+                usuario_id = request.headers.get("X-User-ID")
+
+                if self.flags.esta_activo(
+                    FeatureFlag(flag_nombre),
+                    contexto={"usuario_id": usuario_id},
+                ):
+                    return await self._proxy(request, url_servicio)
+
+        return await self._proxy(request, self.monolito_url)
+
+    async def _proxy(self, request: Request, destino_url: str) -> Response:
+        async with httpx.AsyncClient() as cliente:
+            respuesta = await cliente.request(
+                method=request.method,
+                url=f"{destino_url}{request.url.path}",
+                headers=dict(request.headers),
+                content=await request.body(),
+                timeout=30.0,
+            )
+        return Response(
+            content=respuesta.content,
+            status_code=respuesta.status_code,
+            headers=dict(respuesta.headers),
+        )
+```
+
+---
+
+## Guía de Migración — Plantilla para Usuarios
+
+```markdown
+# Guía de Migración: v1 -> v2 del Endpoint de Usuarios
+
+## Resumen
+El endpoint `/v1/usuarios` será eliminado el **2026-09-01**.
+Esta guía explica cómo migrar a `/v2/usuarios`.
+
+## Qué cambió?
+
+| Aspecto | v1 | v2 |
+|---------|----|----|
+| Campo nombre | `nombre_completo` (string) | `nombre` + `apellidos` (strings separados) |
+| Dirección | Objeto plano | Objeto anidado con `calle`, `ciudad`, `cp` |
+| Fechas | `"2024-01-15T10:00:00"` (sin TZ) | `"2024-01-15T10:00:00-06:00"` (con TZ) |
+
+## Antes (v1)
+```json
+GET /v1/usuarios/abc123
+{
+  "id": "abc123",
+  "nombre_completo": "Ana García López",
+  "direccion": "Insurgentes Sur 123, CDMX, 06600"
+}
+```
+
+## Después (v2)
+```json
+GET /v2/usuarios/abc123
+{
+  "id": "abc123",
+  "nombre": "Ana",
+  "apellidos": "García López",
+  "direccion": {
+    "calle": "Insurgentes Sur 123",
+    "ciudad": "Ciudad de México",
+    "cp": "06600"
+  }
+}
+```
+
+## Script de Migración (TypeScript)
+```typescript
+function adaptarUsuarioV1aV2(v1: UsuarioV1): UsuarioV2 {
+  const [nombre, ...apellidosParts] = v1.nombre_completo.split(" ");
+  return {
+    id: v1.id,
+    nombre,
+    apellidos: apellidosParts.join(" "),
+    direccion: parsearDireccion(v1.direccion),
+  };
+}
+```
+
+## Línea de Tiempo
+- **2026-03-01**: v2 disponible en staging
+- **2026-04-01**: v2 disponible en producción
+- **2026-06-01**: v1 retorna header `Deprecation: true`
+- **2026-09-01**: v1 eliminado (retorna 410 Gone)
+```
+
+---
+
+## Gestión de Breaking Changes en APIs Públicas
+
+```python
+# Detectar clientes que aún usan endpoints deprecados
+class MonitorDeprecados:
+    def registrar_uso(
+        self,
+        endpoint: str,
+        version: str,
+        cliente_id: str,
+        user_agent: str,
+    ) -> None:
+        db.execute("""
+            INSERT INTO uso_endpoints_deprecados
+                (endpoint, version, cliente_id, user_agent, timestamp)
+            VALUES (:ep, :v, :cid, :ua, now())
+            ON CONFLICT (endpoint, version, cliente_id)
+            DO UPDATE SET
+                ultimo_uso = now(),
+                total_llamadas = uso_endpoints_deprecados.total_llamadas + 1
+        """, {"ep": endpoint, "v": version, "cid": cliente_id, "ua": user_agent})
+
+    def clientes_activos_deprecados(
+        self, endpoint: str, dias: int = 30
+    ) -> list[dict]:
+        return db.execute("""
+            SELECT
+                cliente_id,
+                MAX(ultimo_uso) AS ultimo_uso,
+                SUM(total_llamadas) AS llamadas_totales
+            FROM uso_endpoints_deprecados
+            WHERE endpoint = :ep
+              AND ultimo_uso > now() - INTERVAL ':dias days'
+            GROUP BY cliente_id
+            ORDER BY llamadas_totales DESC
+        """, {"ep": endpoint, "dias": dias}).fetchall()
+```

package/habilidades/design-tokens/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: design-tokens
+description: Design tokens y sistemas de diseño. Cubre definición de tokens (color, tipografía, espaciado, sombras, bordes), formatos (JSON, YAML, CSS custom properties), tokens semánticos vs primitivos, theming (light/dark/brand), transformación con Style Dictionary, integración con Tailwind/CSS-in-JS/Angular Material y versionado.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para implementar componentes UI concretos (botones, formularios, cards) — para componentes cargar `angular-moderno`, `react-experto` o el skill del framework."
+  - "No cargar para configuración de Tailwind CSS sin sistema de tokens — para Tailwind sin design system cargar `tailwind-experto`."
+  - "No cargar para diseño responsivo (breakpoints, container queries, layout adaptativo) — para responsivo cargar `diseno-responsivo`."
+  - "No cargar para accesibilidad de color (contraste, daltonismo) — los tokens definen los colores, pero la validación de accesibilidad corresponde a `accesibilidad-a11y`."
+---
+# Design Tokens y Sistemas de Diseño
+
+## Cuándo NO cargar
+
+- La tarea es implementar componentes UI concretos (botones, inputs, cards): cargar el skill del framework (`angular-moderno`, `react-experto`).
+- La configuración es de Tailwind CSS sin un sistema de tokens formal: cargar `tailwind-experto`.
+- El trabajo es diseño responsivo (breakpoints, layout, container queries): cargar `diseno-responsivo`.
+- La validación es de accesibilidad de color (ratios de contraste WCAG): cargar `accesibilidad-a11y`.
+
+## Qué es un Design Token
+
+Un design token es la unidad mínima de una decisión de diseño: un par nombre-valor
+con semántica explícita. No es `#3b82f6` — es `color.marca.primario = #3b82f6`.
+
+**Por qué importan**:
+- Una sola fuente de verdad para diseñadores y desarrolladores
+- Los cambios de tema afectan todos los consumidores automáticamente
+- Los tokens semánticos aíslan los cambios de implementación
+
+---
+
+## Tipos de Tokens — Regla Fundamental
+
+### Primitivos (base)
+
+Valores crudos sin semántica de uso: `color.azul.500 = #3b82f6`, `espacio.4 = 16px`.
+
+### Semánticos (decisión de uso)
+
+Referencian primitivos y comunican propósito: `color.marca.primario = {color.azul.600}`.
+
+**REGLA**: Los componentes SIEMPRE usan tokens semánticos, NUNCA primitivos directamente.
+
+```css
+/* MAL */
+color: #3b82f6;
+
+/* BIEN */
+color: var(--color-marca-primario);
+```
+
+---
+
+## Formato de Tokens
+
+- **JSON**: formato W3C Design Tokens (estándar emergente) con `$value`, `$type`, `$description`.
+- **YAML**: legible para humanos, bueno para edición manual.
+- **CSS Custom Properties**: output generado automáticamente para web.
+
+```css
+:root {
+  --color-marca-primario: var(--color-azul-500);
+  --color-texto-primario: var(--color-gris-900);
+  --espacio-componente-padding-md: var(--espacio-4);
+}
+```
+
+---
+
+## Theming: Light / Dark / Brand
+
+- Tokens semánticos se sobreescriben por tema, primitivos no cambian.
+- Usar `[data-tema="oscuro"]` para selector CSS del tema oscuro.
+- Respetar `prefers-color-scheme: dark` con `:root:not([data-tema])`.
+- Multi-tenant: sobreescribir `color.marca.*` por empresa.
+
+---
+
+## Transformación con Style Dictionary
+
+- SIEMPRE generar tokens desde código, no mantener archivos manuales.
+- Configurar platforms: `css`, `js` (con TypeScript declarations), `android`, `ios-swift`.
+- Scripts: `tokens:build`, `tokens:watch`, `tokens:build:claro`, `tokens:build:oscuro`.
+
+---
+
+## Integraciones con Frameworks
+
+### Tailwind CSS v4
+
+Referenciar CSS vars generados en `@theme`:
+```css
+@theme {
+  --color-primario: var(--color-marca-primario);
+  --font-sans: var(--fuente-sans);
+}
+```
+
+### Angular Material
+
+Definir paleta desde tokens primitivos, usar en `define-light-theme`.
+
+### CSS-in-JS
+
+Objeto de tema que referencia CSS custom properties.
+
+---
+
+## Versionado de Tokens
+
+```
+MAYOR: Eliminar o renombrar tokens (breaking change)
+MENOR: Agregar tokens, cambiar valores existentes
+PARCHE: Correcciones de metadata sin cambio de valor
+```
+
+- SIEMPRE mantener CHANGELOG de tokens.
+- Tokens deprecated: marcar con `"$deprecated": true` + mensaje de migración.
+- NUNCA renombrar sin período de transición (alias del viejo al nuevo).
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Corrección |
+|-------------|------------|
+| Primitivos directamente en componentes | Usar tokens semánticos |
+| Tokens de un solo uso | No crear — usar valor directo |
+| Sin documentación del propósito | `$description` en cada token |
+| Cambiar primitivo sin evaluar cascada | Revisar todos los semánticos que lo referencian |
+| Tokens en Figma que no existen en código | Sincronizar con Style Dictionary |
+| Versionar sin CHANGELOG | Mantener changelog de tokens |
+
+---
+
+## Checklist
+
+- [ ] Tokens primitivos definidos (color, espacio, tipografía, sombras, bordes)
+- [ ] Tokens semánticos para cada decisión de uso
+- [ ] Componentes usan semánticos, nunca primitivos
+- [ ] Temas light/dark funcionan con `prefers-color-scheme`
+- [ ] Style Dictionary configurado y genera automáticamente
+- [ ] CHANGELOG de tokens actualizado
+- [ ] Tokens deprecated marcados con `$deprecated`
+
+Para definiciones completas de tokens, temas, configuración de Style Dictionary e integraciones, ver [recursos/tokens-y-configuracion.md](recursos/tokens-y-configuracion.md).
+
+## Gotchas / Errores comunes no obvios
+
+**Style Dictionary genera los archivos CSS pero los tokens semánticos no resuelven los primitivos en runtime**: Style Dictionary resuelve las referencias `{color.azul.500}` en tiempo de build y genera variables CSS con el valor literal. Si el token semántico se define como `var(--color-azul-500)` en lugar de que Style Dictionary lo resuelva, el valor literal no se embebe y depende de que ambas variables estén declaradas en el mismo scope CSS. Causa: confundir la resolución en build-time de Style Dictionary con la referencia en runtime de CSS custom properties. Fix: en Style Dictionary, usar la sintaxis de referencia `{color.azul.500}` (llaves, sin `var()`) para que el build resuelva el valor. Las `var()` solo aparecen en el CSS generado cuando se configura explícitamente la plataforma `css/variables`.
+
+**Cambiar un token primitivo de valor afecta componentes que deberían estar aislados por el token semántico**: si un componente usa directamente `var(--color-azul-500)` en lugar de `var(--color-marca-primario)`, cambiar el valor del primitivo cambia ese componente aunque el primitivo sea de "base" y no debería afectar la interfaz. Causa: la regla "componentes solo usan semánticos" se rompe gradualmente cuando los desarrolladores toman atajos. Fix: establecer un lint de CSS que detecte el uso directo de tokens primitivos en componentes: buscar `var(--color-azul-` o `var(--espacio-` en archivos de componentes y rechazar en CI.
+
+**El tema oscuro no aplica cuando el usuario tiene `prefers-color-scheme: dark` pero el sistema tiene `[data-tema="claro"]` forzado**: la prioridad de CSS hace que `[data-tema="claro"]` en el `<html>` gane sobre `@media (prefers-color-scheme: dark)` porque el selector de atributo tiene mayor especificidad. Causa: el override explícito del tema en el atributo HTML tiene precedencia sobre la media query del sistema operativo. Fix: es el comportamiento correcto cuando el usuario eligió explícitamente el tema en la app. Pero si el sistema no tiene selector de tema en `<html>`, agregar `:root:not([data-tema])` al selector de dark mode para que solo aplique cuando no hay tema forzado.
+
+**Los tokens deprecated con `"$deprecated": true` siguen siendo usados por componentes porque el equipo de diseño los eliminó en Figma pero no en código**: el `$deprecated: true` es solo metadata en el JSON de tokens — no causa error en build ni lint. Los componentes siguen usando el token viejo sin ninguna advertencia visible. Causa: la deprecación de tokens es declarativa pero no hay enforcement automático. Fix: agregar un paso en el pipeline de Style Dictionary que genera una lista de tokens deprecated y un script de lint que verifica si algún archivo CSS/TS los referencia. Sin enforcement, los tokens deprecated nunca se eliminan.