@saulwade/swl-ses 1.0.0

package/habilidades/kotlin-testing/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: kotlin-testing
+description: >
+  Testing Kotlin con MockK, Turbine para Flow, runTest para coroutines,
+  Kover para cobertura, Robolectric y Ktor test client. Incluye testing
+  de ViewModels con StateFlow y UI testing con Compose. Cargar cuando se
+  escriban tests Kotlin, tests de ViewModel o se configure cobertura en Android.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para implementar el código Kotlin de producción — primero implementar con `kotlin-experto` o `kotlin-compose`, luego escribir tests."
+  - "No cargar para tests Java con JUnit/Mockito — Java tiene su propio ecosistema de testing; cargar `java-testing`."
+  - "No cargar para errores de compilación Kotlin o Gradle en los tests — cargar `build-errors-kotlin`."
+  - "No cargar para tests E2E de UI Android con Espresso — Espresso no está cubierto por este skill que se enfoca en unit/integration con MockK y Compose testing."
+evolvable: true  # default para skill estandar
+---
+# Kotlin Testing — MockK, Turbine y runTest
+
+## Cuándo NO cargar
+
+- El código Kotlin de producción aún no existe — primero implementar con `kotlin-experto` o `kotlin-compose`, luego escribir tests.
+- Los tests son para un proyecto Java con JUnit/Mockito — Java tiene su propio ecosistema; cargar `java-testing`.
+- Los errores son de compilación Kotlin o Gradle en los archivos de test — cargar `build-errors-kotlin`.
+- La pregunta es sobre tests E2E de UI Android con Espresso — Espresso no está cubierto por este skill.
+
+## runTest — Tests de Coroutines
+
+```kotlin
+class FacturasViewModelTest {
+
+    // TestDispatcher controla el tiempo virtual
+    private val testDispatcher = UnconfinedTestDispatcher()
+
+    @Before
+    fun setup() {
+        Dispatchers.setMain(testDispatcher)
+    }
+
+    @After
+    fun teardown() {
+        Dispatchers.resetMain()
+    }
+
+    @Test
+    fun `cargarFacturas emite Exito cuando repositorio retorna datos`() = runTest {
+        // Arrange
+        val repo = mockk<IFacturasRepository>()
+        val facturas = listOf(Factura(id = "1", folio = "F-001"))
+        every { repo.observarFacturas(any()) } returns flowOf(facturas)
+        val vm = FacturasViewModel(repo, fakeSavedStateHandle("empresaId" to "empresa-1"))
+
+        // Act + Assert con Turbine
+        vm.uiState.test {
+            skipItems(1)  // saltar Cargando inicial
+            val estado = awaitItem()
+            assertIs<FacturasUiState.Exito>(estado)
+            assertEquals(1, estado.facturas.size)
+            cancelAndConsumeRemainingEvents()
+        }
+    }
+}
+```
+
+---
+
+## Turbine — Testing de Flow
+
+```kotlin
+// Turbine envuelve un Flow y permite aserciones item por item
+@Test
+fun `observarFacturas emite lista actualizada al insertar`() = runTest {
+    val dao = FakeFacturasDao()
+
+    dao.observarTodas().test {
+        // Primera emisión — lista vacía
+        assertEquals(emptyList(), awaitItem())
+
+        // Insertar elemento
+        dao.insertar(FacturaEntity(id = "1", folio = "F-001"))
+
+        // Segunda emisión — con el elemento
+        val lista = awaitItem()
+        assertEquals(1, lista.size)
+        assertEquals("F-001", lista[0].folio)
+
+        cancelAndConsumeRemainingEvents()
+    }
+}
+
+// Verificar que Flow completa sin errores
+@Test
+fun `obtenerFacturasUnica completa sin error`() = runTest {
+    val flow = repo.obtenerFacturasUnica("empresa-1")
+    flow.test {
+        val items = awaitItem()
+        assertTrue(items.isNotEmpty())
+        awaitComplete()
+    }
+}
+
+// Verificar error en Flow
+@Test
+fun `Flow emite error cuando falla la red`() = runTest {
+    every { api.obtenerFacturas(any()) } throws IOException("sin red")
+    repo.observarFacturas("empresa-1").test {
+        awaitError().also { error ->
+            assertIs<IOException>(error)
+        }
+    }
+}
+```
+
+---
+
+## MockK — Sintaxis completa
+
+```kotlin
+// Mocks básicos
+val repo = mockk<IFacturasRepository>()
+val repo = mockk<IFacturasRepository>(relaxed = true)  // stubs automáticos para Unit
+
+// Stubs síncronos y async
+every { repo.obtenerPorId("1") } returns Factura(id = "1")
+coEvery { repo.obtenerAsync("1") } returns Factura(id = "1")
+coEvery { repo.obtenerAsync("inexistente") } returns null
+
+// Stubs de Flow
+every { repo.observarFacturas(any()) } returns flowOf(listaFacturas)
+every { repo.observarFacturas("vacio") } returns emptyFlow()
+
+// Capturar argumento
+val slot = slot<Factura>()
+coEvery { repo.guardar(capture(slot)) } returns Unit
+// Después del call:
+assertEquals("F-001", slot.captured.folio)
+
+// Verificaciones
+coVerify(exactly = 1) { repo.guardar(any()) }
+coVerify(exactly = 0) { repo.eliminar(any()) }
+
+// Verificar orden
+coVerifyOrder {
+    repo.validar(any())
+    repo.guardar(any())
+}
+
+// Spy — objeto real con algunos métodos substituidos
+val realService = FacturasService(repo)
+val spyService = spyk(realService)
+coEvery { spyService.validarFolio(any()) } returns true
+```
+
+---
+
+## Kover — Cobertura
+
+```kotlin
+// build.gradle.kts (módulo :app)
+plugins {
+    id("org.jetbrains.kotlinx.kover") version "0.8.3"
+}
+
+kover {
+    reports {
+        filters {
+            excludes {
+                classes(
+                    "*.BuildConfig",
+                    "*.databinding.*",
+                    "Hilt_*",
+                    "*_Factory"
+                )
+            }
+        }
+        verify {
+            rule {
+                minBound(80)  // 80% cobertura mínima de líneas
+            }
+        }
+    }
+}
+```
+
+```bash
+# Generar reporte
+./gradlew koverHtmlReport
+
+# Verificar umbral (falla si < 80%)
+./gradlew koverVerify
+```
+
+---
+
+## Compose UI Testing
+
+```kotlin
+class FacturasScreenTest {
+
+    @get:Rule
+    val composeRule = createComposeRule()
+
+    @Test
+    fun `pantalla muestra lista cuando estado es Exito`() {
+        val facturas = listOf(Factura(id = "1", folio = "F-001", total = 1000.0))
+        val estado = FacturasUiState.Exito(facturas)
+
+        composeRule.setContent {
+            FacturasScreen(uiState = estado, onFacturaClick = {})
+        }
+
+        composeRule.onNodeWithText("F-001").assertIsDisplayed()
+        composeRule.onNodeWithText("$1,000.00").assertIsDisplayed()
+    }
+
+    @Test
+    fun `pantalla muestra loader cuando estado es Cargando`() {
+        composeRule.setContent {
+            FacturasScreen(uiState = FacturasUiState.Cargando, onFacturaClick = {})
+        }
+
+        composeRule.onNodeWithContentDescription("Cargando").assertIsDisplayed()
+    }
+
+    @Test
+    fun `clic en factura llama al callback`() {
+        var clickedId: String? = null
+        val facturas = listOf(Factura(id = "1", folio = "F-001", total = 0.0))
+
+        composeRule.setContent {
+            FacturasScreen(
+                uiState = FacturasUiState.Exito(facturas),
+                onFacturaClick = { clickedId = it }
+            )
+        }
+
+        composeRule.onNodeWithText("F-001").performClick()
+        assertEquals("1", clickedId)
+    }
+}
+```
+
+---
+
+Para Robolectric (tests Android sin emulador), Ktor test client y el patrón
+Fake vs Mock con ejemplos de implementación, ver
+[recursos/testing-avanzado.md](recursos/testing-avanzado.md).
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**`runBlocking` en tests Android hace que los tests fallen en el thread principal de Robolectric**: usar `runBlocking` en tests con `@RunWith(RobolectricTestRunner::class)` bloquea el hilo principal que Robolectric necesita para procesar mensajes del Looper. Fix: usar `runTest` con `UnconfinedTestDispatcher` para tests de Android que necesitan el thread principal — `runTest` gestiona el dispatcher de forma compatible con Robolectric.
+
+**Turbine `awaitItem()` sin `cancelAndIgnoreRemainingEvents()` al final hace que el test se cuelgue**: si el Flow emite más items de los que el test consume con `awaitItem()`, Turbine espera que el test explícitamente cancele o finalice el Flow. Fix: siempre terminar los bloques `turbineScope { ... }` con `cancelAndIgnoreRemainingEvents()` o `awaitComplete()` según el caso.
+
+**`every { mock.suspend() } returns value` sin `coEvery` causa error de compilación**: MockK distingue entre funciones suspendidas y normales — usar `every` en una función suspendida genera un error críptico de tipo. Fix: usar siempre `coEvery { mock.suspendFn() } returns value` para mockear funciones `suspend`, y `coVerify` para verificarlas.
+
+**`Dispatchers.setMain(testDispatcher)` en `@BeforeEach` sin `resetMain()` en `@AfterEach` contamina tests subsecuentes**: el dispatcher del Main persiste entre tests porque es un estado global de coroutines. Fix: siempre parear `Dispatchers.setMain(testDispatcher)` con `Dispatchers.resetMain()` en la fase de teardown, o usar la extensión `@ExtendWith(MainDispatcherRule::class)` de Coroutines Test.
+
+## Checklist de tests Kotlin
+
+- [ ] runTest en todos los tests de coroutines (no runBlocking en tests de Android)
+- [ ] Dispatchers.setMain(testDispatcher) en @Before y resetMain() en @After
+- [ ] Turbine usado para tests de Flow (no collect + lista manual)
+- [ ] CancellationException nunca atrapada en helpers de test
+- [ ] Kover configurado con umbral mínimo 80%
+- [ ] Fakes para integración, mocks (MockK) para verificación de comportamiento

package/habilidades/kotlin-testing/recursos/testing-avanzado.md

@@ -0,0 +1,74 @@
+# Kotlin Testing — Referencia Avanzada
+
+## Robolectric — Tests Android sin Emulador
+
+```kotlin
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class FacturasNotificationTest {
+
+    @Test
+    fun `notificacion se crea con titulo correcto`() {
+        val context = ApplicationProvider.getApplicationContext<Context>()
+        val builder = FacturasNotificationBuilder(context)
+
+        val notification = builder.construir("Factura F-001 procesada")
+
+        val extras = notification.extras
+        assertEquals("Facturas", extras.getString(Notification.EXTRA_TITLE))
+        assertEquals("Factura F-001 procesada",
+            extras.getString(Notification.EXTRA_TEXT))
+    }
+}
+```
+
+---
+
+## Ktor Test Client
+
+```kotlin
+class FacturasApiTest {
+
+    @Test
+    fun `POST facturas retorna 201 con datos validos`() = testApplication {
+        application { configurarRouting() }
+
+        val client = createClient {
+            install(ContentNegotiation) { json() }
+        }
+
+        val response = client.post("/api/v1/facturas") {
+            contentType(ContentType.Application.Json)
+            setBody(CrearFacturaRequest(folio = "F-001", empresaId = "empresa-1"))
+        }
+
+        assertEquals(HttpStatusCode.Created, response.status)
+        val dto = response.body<FacturaDto>()
+        assertEquals("F-001", dto.folio)
+    }
+}
+```
+
+---
+
+## Fake vs Mock — cuándo usar cada uno
+
+```kotlin
+// Fake — implementación en memoria para tests de integración
+class FakeFacturasRepository : IFacturasRepository {
+    private val facturas = mutableListOf<Factura>()
+    private val _flow = MutableStateFlow(facturas.toList())
+
+    override fun observarFacturas(empresaId: String): StateFlow<List<Factura>> =
+        _flow.map { list -> list.filter { it.empresaId == empresaId } }
+            .stateIn(CoroutineScope(UnconfinedTestDispatcher()), Eagerly, emptyList())
+
+    override suspend fun guardar(factura: Factura) {
+        facturas.add(factura)
+        _flow.value = facturas.toList()
+    }
+}
+
+// Mock (MockK) — cuando el test verifica interacciones específicas, no estado
+// Usar mockk cuando importa CÓMO se llama algo, no solo el resultado
+```

package/habilidades/kubernetes-orquestacion/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: kubernetes-orquestacion
+description: Kubernetes en producción. Deployments, Services, Ingress, ConfigMaps, Secrets, HPA, PDB, NetworkPolicies, Helm, Kustomize. Patrones de deployment blue-green y canary. Troubleshooting común.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para Dockerfiles y containerización de la imagen — para Docker cargar `contenedores-docker`."
+  - "No cargar para Terraform, Pulumi o infraestructura como código — para IaC cargar `terraform-experto`."
+  - "No cargar para service mesh (Istio, Linkerd) en profundidad o GitOps (ArgoCD, Flux) — este skill cubre los objetos core de Kubernetes, no plataformas de nivel superior."
+  - "No cargar para cloud-specific Kubernetes (EKS, AKS, GKE) y sus integraciones IAM específicas — para cloud cargar `cloud-aws`, `azure-cloud` o `gcp-cloud`."
+evolvable: true  # default para skill estandar
+---
+# Kubernetes — Orquestación en Producción
+
+## Cuándo NO cargar
+
+- La tarea es construir la imagen Docker: Dockerfile, multi-stage build — cargar `contenedores-docker`.
+- El trabajo es Terraform o Pulumi para aprovisionar el cluster — cargar `terraform-experto`.
+- El tema es service mesh (Istio, Linkerd) o GitOps (ArgoCD, Flux) en profundidad — este skill cubre los objetos core de Kubernetes.
+- La tarea es específica de EKS/AKS/GKE: integraciones IAM, node pools, addons — cargar `cloud-aws`, `azure-cloud` o `gcp-cloud`.
+
+Kubernetes es la plataforma estándar de orquestación de containers. Este skill cubre
+los objetos principales, patrones de despliegue seguro y troubleshooting efectivo.
+
+---
+
+## Reglas Obligatorias
+
+1. **NUNCA `:latest` en producción** — usar tag de versión exacta.
+2. **`resources.requests` y `resources.limits`** en TODOS los containers.
+3. **`livenessProbe` + `readinessProbe`** en todos los pods de producción.
+4. **`startupProbe`** para apps con arranque lento (>30s).
+5. **`runAsNonRoot: true`** + `readOnlyRootFilesystem: true` en securityContext.
+6. **`maxUnavailable: 0`** en RollingUpdate para zero-downtime.
+7. **PodDisruptionBudget** OBLIGATORIO para servicios críticos.
+8. **NetworkPolicy default-deny** + permisos explícitos (zero-trust).
+9. **Secrets** gestionados con External Secrets Operator o Sealed Secrets.
+10. **NUNCA Service tipo LoadBalancer directamente** — usar Ingress.
+
+---
+
+## Deployment — Configuración Clave
+
+```yaml
+spec:
+  replicas: 3
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 1
+      maxUnavailable: 0        # Zero downtime
+  template:
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 1001
+      containers:
+        - name: api
+          image: registry.com/app:1.5.2   # NUNCA :latest
+          resources:
+            requests: { cpu: "100m", memory: "256Mi" }
+            limits:   { cpu: "500m", memory: "512Mi" }
+          livenessProbe:
+            httpGet: { path: /health/live, port: http }
+          readinessProbe:
+            httpGet: { path: /health/ready, port: http }
+```
+
+---
+
+## PodDisruptionBudget
+
+```yaml
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: api-pdb
+spec:
+  minAvailable: 2
+  selector:
+    matchLabels:
+      app: api-nomina
+```
+
+---
+
+## Deployment Strategies
+
+| Estrategia | Riesgo | Rollback | Complejidad |
+|-----------|--------|----------|-------------|
+| Rolling Update | Bajo | kubectl rollout undo | Baja |
+| Blue-Green | Muy bajo | Cambiar selector del Service | Media |
+| Canary | Mínimo | Eliminar canary deployment | Alta |
+
+**Blue-Green**: dos deployments (blue=actual, green=nueva). Cambiar el Service selector
+para switch instantáneo. Rollback = volver al selector anterior.
+
+**Canary**: deployment pequeño (1 pod de 10 = 10% tráfico) con Ingress canary annotation
+`nginx.ingress.kubernetes.io/canary-weight: "10"`.
+
+---
+
+## Helm — Comandos Esenciales
+
+```bash
+helm lint ./charts/mi-app
+helm template mi-app ./charts/mi-app -f values-prod.yaml     # Preview
+helm upgrade --install mi-app ./charts/mi-app \
+  --namespace prod --create-namespace \
+  -f values-prod.yaml --set image.tag=1.5.2 --wait --timeout 5m
+helm rollback mi-app 3 --namespace prod                      # Rollback
+```
+
+---
+
+## Troubleshooting Rápido
+
+| Síntoma | Comando | Causa común |
+|---------|---------|-------------|
+| Pod Pending | `kubectl describe pod` | Recursos insuficientes |
+| CrashLoopBackOff | `kubectl logs --previous` | Error en la app |
+| Sin tráfico | `kubectl get endpoints` | Selector no coincide |
+| Lento | `kubectl top pods` | Recursos limit muy bajo |
+
+---
+
+## Checklist de Deployment Productivo
+
+- [ ] `resources.requests` y `limits` definidos
+- [ ] `livenessProbe` y `readinessProbe` configurados
+- [ ] `startupProbe` para apps lentas
+- [ ] PodDisruptionBudget para servicios críticos
+- [ ] `runAsNonRoot: true` en securityContext
+- [ ] `readOnlyRootFilesystem: true`
+- [ ] NetworkPolicy default-deny + permisos explícitos
+- [ ] HPA con métricas reales
+- [ ] `maxUnavailable: 0` en RollingUpdate
+- [ ] `podAntiAffinity` para distribuir en nodos distintos
+- [ ] Secrets con External Secrets Operator
+- [ ] Imagen con tag exacto (nunca `latest`)
+
+Para manifiestos YAML completos (Deployment, Service, Ingress, HPA, NetworkPolicy, Helm, Blue-Green, Canary, troubleshooting), ver [recursos/manifiestos-completos.md](recursos/manifiestos-completos.md).
+
+## Gotchas / Errores comunes no obvios
+
+**`livenessProbe` con un threshold muy bajo mata pods sanos durante GC o inicialización**: si `livenessProbe` tiene `failureThreshold: 1` y `periodSeconds: 5`, una pausa de GC de 6 segundos en la JVM o Python reinicia el pod aunque la aplicación esté sana. Causa: el liveness probe no distingue entre "proceso muerto" y "proceso temporalmente ocupado". Fix: configurar `failureThreshold: 3` con `periodSeconds: 10` como mínimo, y usar `startupProbe` para aplicaciones con arranque lento — el `startupProbe` desactiva liveness/readiness hasta que la app esté lista.
+
+**`resources.limits.memory` demasiado bajo causa OOMKilled silencioso que se ve como crash**: un pod con `limits.memory: 128Mi` y una carga que requiere 130Mi es terminado por el kernel con OOM sin mensaje claro — `kubectl describe pod` muestra `OOMKilled` solo en el campo `lastState`. Causa: los límites de memoria en Kubernetes se implementan con cgroups — exceder el límite termina el proceso inmediatamente. Fix: establecer limits basados en mediciones reales con `kubectl top pods` en carga real, dejando al menos 20% de margen sobre el consumo máximo observado.
+
+**HPA con CPU como métrica no escala correctamente si los `resources.requests.cpu` no están bien calibrados**: el HPA escala cuando el CPU promedio supera el `targetCPUUtilizationPercentage` relativo a `requests.cpu`. Si `requests.cpu: "10m"` y la app usa "500m", el HPA ve 5000% de uso y escala agresivamente aunque haya capacidad. Causa: el HPA calcula utilización como `uso_actual / requests`, no sobre el nodo. Fix: calibrar `requests.cpu` al uso promedio real de la aplicación en carga normal — usar `kubectl top pods` en producción para obtener los valores correctos.
+
+**`kubectl rollout undo` revierte al deployment anterior pero no revierte ConfigMaps ni Secrets referenciados**: si el deployment v2 usa `ConfigMap v2` y se hace rollout undo al deployment v1, el pod v1 puede iniciar con el `ConfigMap v2` si los pods usan el mismo nombre de ConfigMap. Causa: el rollout undo solo cambia la especificación del Deployment, no de los recursos referenciados. Fix: versionar los ConfigMaps con el mismo tag que el deployment (`config-api-v1`, `config-api-v2`) y actualizar la referencia en el Deployment — el rollout undo revertirá a la referencia al ConfigMap correcto.