@saulwade/swl-ses 1.0.0

package/habilidades/tailwind-experto/recursos/referencia-completa.md

@@ -0,0 +1,184 @@
+# Referencia Completa — Tailwind CSS v4
+
+## Tokens de Color Completos
+
+```css
+@theme {
+  /* Sistema de colores semántico */
+  --color-fondo: #ffffff;
+  --color-superficie: #f8fafc;
+  --color-borde: #e2e8f0;
+  --color-texto: #0f172a;
+  --color-texto-muted: #64748b;
+
+  /* Paleta de marca */
+  --color-marca-50:  oklch(97% 0.01 250);
+  --color-marca-100: oklch(93% 0.03 250);
+  --color-marca-200: oklch(86% 0.06 250);
+  --color-marca-300: oklch(77% 0.10 250);
+  --color-marca-400: oklch(67% 0.15 250);
+  --color-marca-500: oklch(56% 0.20 250);
+  --color-marca-600: oklch(46% 0.20 250);
+  --color-marca-700: oklch(38% 0.18 250);
+  --color-marca-800: oklch(30% 0.14 250);
+  --color-marca-900: oklch(22% 0.10 250);
+
+  /* Estados */
+  --color-exito:    oklch(65% 0.20 145);
+  --color-error:    oklch(58% 0.24  27);
+  --color-advertencia: oklch(78% 0.18  80);
+  --color-info:     oklch(62% 0.20 250);
+}
+```
+
+## Tipografía y Escalas Fluidas
+
+```css
+@theme {
+  /* Escala tipográfica fluida */
+  --text-xs:   clamp(0.70rem, 0.5vw + 0.5rem, 0.75rem);
+  --text-sm:   clamp(0.85rem, 0.8vw + 0.5rem, 0.875rem);
+  --text-base: clamp(1rem,    1vw  + 0.5rem, 1rem);
+  --text-lg:   clamp(1.1rem,  1.5vw + 0.5rem, 1.125rem);
+  --text-xl:   clamp(1.2rem,  2vw  + 0.5rem, 1.25rem);
+  --text-2xl:  clamp(1.4rem,  3vw  + 0.5rem, 1.5rem);
+  --text-4xl:  clamp(2rem,    5vw  + 0.5rem, 2.25rem);
+
+  /* Line heights */
+  --leading-tight:   1.25;
+  --leading-snug:    1.375;
+  --leading-normal:  1.5;
+  --leading-relaxed: 1.625;
+}
+```
+
+---
+
+## Patrón: Composición de Layouts
+
+```tsx
+// Layout de dos columnas con sidebar
+function DashboardLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="flex min-h-screen bg-fondo">
+      <aside className="w-64 shrink-0 border-r border-borde bg-superficie">
+        <NavSidebar />
+      </aside>
+      <main className="flex-1 overflow-auto p-6">
+        {children}
+      </main>
+    </div>
+  );
+}
+```
+
+## Patrón: Tarjeta con Variantes
+
+```tsx
+const cardVariants = cva('rounded-lg border bg-superficie', {
+  variants: {
+    elevacion: {
+      none: 'shadow-none',
+      sm:   'shadow-sm',
+      md:   'shadow-md',
+      lg:   'shadow-lg ring-1 ring-black/5',
+    },
+    padding: {
+      none: 'p-0',
+      sm:   'p-4',
+      md:   'p-6',
+      lg:   'p-8',
+    },
+  },
+  defaultVariants: { elevacion: 'sm', padding: 'md' },
+});
+```
+
+---
+
+## Plugin Custom Completo
+
+```typescript
+// plugins/animation-plugin.ts
+import plugin from 'tailwindcss/plugin';
+
+export const animacionesPlugin = plugin(
+  ({ addUtilities, addComponents, theme }) => {
+    // Utilidades de animación custom
+    addUtilities({
+      '.animate-fade-in': {
+        animation: 'fadeIn 0.3s ease-in-out',
+      },
+      '.animate-slide-up': {
+        animation: 'slideUp 0.4s ease-out',
+      },
+    });
+
+    // Componente de badge
+    addComponents({
+      '.badge': {
+        display: 'inline-flex',
+        alignItems: 'center',
+        padding: `${theme('spacing.1')} ${theme('spacing.2')}`,
+        borderRadius: theme('borderRadius.full'),
+        fontSize: theme('fontSize.xs'),
+        fontWeight: '500',
+      },
+    });
+  },
+  {
+    // Keyframes del plugin
+    theme: {
+      extend: {
+        keyframes: {
+          fadeIn: {
+            from: { opacity: '0' },
+            to: { opacity: '1' },
+          },
+          slideUp: {
+            from: { transform: 'translateY(10px)', opacity: '0' },
+            to: { transform: 'translateY(0)', opacity: '1' },
+          },
+        },
+      },
+    },
+  }
+);
+```
+
+---
+
+## Compilación JIT y Purging
+
+Tailwind v4 usa JIT por defecto. Solo genera las clases que realmente usas:
+
+```css
+/* globals.css */
+@import "tailwindcss";
+
+/* Tailwind escanea automáticamente archivos .tsx, .ts, .jsx, .js, .html */
+/* Para archivos especiales, agregar fuentes adicionales: */
+@source "../node_modules/mi-libreria-ui/dist/**/*.js";
+```
+
+### Valores arbitrarios (escape hatch)
+
+```html
+<!-- Valor exacto que no está en el sistema -->
+<div class="top-[117px] w-[calc(100%-2rem)] bg-[#1da1f2]">
+
+<!-- Variable CSS arbitraria -->
+<div class="text-(--color-personalizado)">
+```
+
+---
+
+## Anti-patrón: Olvidar el Orden de Variantes
+
+```html
+<!-- MAL: dark: debe aplicarse DESPUÉS del estado base en la misma propiedad -->
+<div class="dark:bg-gray-900 bg-white hover:dark:bg-gray-800 hover:bg-gray-50">
+
+<!-- BIEN: agrupar por propiedad, modificadores al final -->
+<div class="bg-white dark:bg-gray-900 hover:bg-gray-50 dark:hover:bg-gray-800">
+```

package/habilidades/tdd-workflow/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: tdd-workflow
+description: Flujo completo de Test-Driven Development. Ciclo RED (el test falla) → GREEN (implementación mínima) → REFACTOR (limpieza). Incluye cobertura mínima obligatoria, tests de frontera, factories, fixtures y estrategias para diferentes tipos de código (APIs, services, componentes Angular).
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para escribir tests de regresión sobre código legacy sin suite existente — en código legacy sin tests, comenzar con caracterización de comportamiento actual antes del ciclo TDD."
+  - "No cargar para pruebas de carga o performance testing — para benchmarks y load testing cargar `performance-baseline`."
+  - "No cargar para configurar pipelines de CI/CD o runners de tests en GitHub Actions / GitLab CI — para configuración de CI cargar el skill de cloud correspondiente."
+  - "No cargar para pruebas de seguridad o fuzzing automático — para testing de seguridad cargar `threat-model-lite` y usar herramientas especializadas (Bandit, OWASP ZAP)."
+---
+# Habilidad: TDD Workflow Completo
+
+## Cuándo NO cargar
+
+- La tarea es añadir tests a código legacy sin suite existente: comenzar con tests de caracterización del comportamiento actual antes del ciclo TDD.
+- La tarea es pruebas de carga o benchmarks: cargar `performance-baseline`.
+- La tarea es configurar CI/CD pipelines: cargar el skill de cloud correspondiente.
+- La tarea es fuzzing o testing de seguridad: cargar `threat-model-lite` y usar herramientas especializadas.
+
+## Propósito
+
+TDD no es "escribir tests después" ni "escribir tests antes por costumbre". Es
+un método de diseño donde los tests guían la API pública del código antes de
+que exista la implementación. El resultado es código que hace exactamente lo
+que los tests exigen — ni más, ni menos.
+
+## Cuándo activar
+
+- CONTEXT.md o PLAN.md indica que la fase requiere TDD
+- Se implementa lógica de negocio crítica (cálculos, validaciones, permisos)
+- El usuario pide explícitamente TDD
+- Se trabaja en un módulo con historial de bugs
+
+---
+
+## El ciclo fundamental RED → GREEN → REFACTOR
+
+### Fase RED — El test debe fallar por la razón correcta
+
+**Paso 1**: Escribir el test que describe el comportamiento esperado.
+
+```python
+# RED: Este test falla porque calcular_descuento no existe todavía
+def test_descuento_cliente_premium_es_15_porciento():
+    cliente = ClienteFactory(tipo="premium")
+    resultado = calcular_descuento(cliente, monto=100.0)
+    assert resultado == 15.0
+```
+
+**Verificar que el test falla BIEN**:
+- Falla con `NameError` o `ImportError` si la función no existe: CORRECTO
+- Falla con `AssertionError` si el comportamiento es incorrecto: CORRECTO
+- Falla con `TypeError` si la firma es incorrecta: CORRECTO
+- Pasa sin que exista implementación: SEÑAL DE ALARMA — el test no prueba nada
+
+**NUNCA avanzar a GREEN si el test pasa en RED.**
+
+### Fase GREEN — Implementación mínima
+
+**Regla de oro**: Implementar solo lo que hace pasar el test. Nada más.
+
+```python
+# GREEN: Implementación mínima que hace pasar el test
+def calcular_descuento(cliente: Cliente, monto: float) -> float:
+    if cliente.tipo == "premium":
+        return monto * 0.15
+    return 0.0
+```
+
+**Anti-patrón GREEN**: implementar todos los casos de una vez sin tests que los
+exijan. Si no hay un test para clientes "gold", no implementes el descuento gold.
+
+**Verificar**: `pytest -v test_descuentos.py` pasa con el test nuevo.
+
+### Fase REFACTOR — Limpieza sin cambiar comportamiento
+
+**Qué refactorizar en esta fase**:
+- Nombres de variables o funciones poco claros
+- Duplicación de lógica (si ya existe en otro test)
+- Magic numbers que deberían ser constantes
+- Estructura de código que anticipa el próximo test
+
+```python
+# REFACTOR: Extraer constante y mejorar legibilidad
+DESCUENTO_POR_TIPO = {
+    "premium": 0.15,
+    "gold": 0.20,
+    "standard": 0.0,
+}
+
+def calcular_descuento(cliente: Cliente, monto: float) -> float:
+    tasa = DESCUENTO_POR_TIPO.get(cliente.tipo, 0.0)
+    return monto * tasa
+```
+
+**Verificar**: todos los tests siguen pasando después del refactor.
+
+---
+
+## Tests de frontera (boundary tests)
+
+Para toda función que procesa datos, escribir tests de:
+
+| Tipo de frontera | Ejemplo |
+|----------------|---------|
+| Valor cero | `monto=0.0` |
+| Valor negativo | `monto=-100.0` |
+| Valor máximo | `monto=999_999_999.99` |
+| String vacío | `nombre=""` |
+| None / null | `cliente=None` |
+| Lista vacía | `items=[]` |
+| Un solo elemento | `items=[item]` |
+| Muchos elementos | `items=lista_de_10000` |
+| Valor fuera de dominio | `tipo="inexistente"` |
+| Caracteres especiales | `nombre="<script>alert(1)</script>"` |
+
+---
+
+## Factories y Fixtures
+
+### Factories (para datos de test)
+
+Las factories crean objetos con valores válidos por defecto. Los tests solo
+sobreescriben lo que importa para ese test específico.
+
+**Python con factory_boy**:
+```python
+import factory
+from myapp.models import Cliente, Pedido
+
+class ClienteFactory(factory.Factory):
+    class Meta:
+        model = Cliente
+
+    id = factory.Sequence(lambda n: f"cliente-{n}")
+    nombre = factory.Faker("name", locale="es_MX")
+    email = factory.Faker("email")
+    tipo = "standard"  # default explícito
+    activo = True
+
+# Uso en test
+def test_descuento_premium():
+    # Solo especificar lo que importa para este test
+    cliente = ClienteFactory(tipo="premium")
+    assert calcular_descuento(cliente, 100.0) == 15.0
+```
+
+**TypeScript con factory functions**:
+```typescript
+// factories/user.factory.ts
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: 'user-1',
+  name: 'Test User',
+  email: 'test@example.com',
+  role: 'standard',
+  active: true,
+  ...overrides,
+});
+
+// Uso en test
+it('should show admin panel for admin users', () => {
+  const user = createUser({ role: 'admin' });
+  // ...
+});
+```
+
+### Fixtures (para estado persistente)
+
+```python
+# conftest.py
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession
+
+@pytest.fixture
+async def db_session():
+    """Sesión de BD en transacción que hace rollback al terminar."""
+    async with AsyncSessionLocal() as session:
+        async with session.begin():
+            yield session
+            await session.rollback()
+
+@pytest.fixture
+async def cliente_premium(db_session: AsyncSession):
+    """Cliente premium persistido en BD de test."""
+    cliente = ClienteFactory.build(tipo="premium")
+    db_session.add(cliente)
+    await db_session.flush()
+    return cliente
+```
+
+---
+
+## TDD por tipo de código
+
+### Services (lógica de negocio)
+
+```python
+# Orden de tests para un service nuevo:
+# 1. Caso feliz principal
+# 2. Validaciones de input inválido
+# 3. Casos de borde del dominio
+# 4. Interacciones con dependencias (mocks)
+
+@pytest.mark.asyncio
+async def test_crear_pedido_valida_stock_disponible():
+    producto = ProductoFactory(stock=5)
+    with pytest.raises(StockInsuficienteError):
+        await PedidoService.crear(producto_id=producto.id, cantidad=10)
+```
+
+### Endpoints FastAPI
+
+```python
+# Usar TestClient de FastAPI
+from fastapi.testclient import TestClient
+
+def test_endpoint_requiere_autenticacion():
+    response = client.get("/api/v1/pedidos")
+    assert response.status_code == 401
+
+def test_endpoint_retorna_solo_pedidos_del_usuario(cliente_autenticado):
+    pedido_propio = PedidoFactory(usuario_id=cliente_autenticado.id)
+    pedido_ajeno = PedidoFactory(usuario_id="otro-usuario")
+
+    response = cliente_autenticado.get("/api/v1/pedidos")
+    ids = [p["id"] for p in response.json()["items"]]
+
+    assert pedido_propio.id in ids
+    assert pedido_ajeno.id not in ids  # IDOR check
+```
+
+### Componentes Angular
+
+```typescript
+// Usar TestBed + ComponentHarness
+describe('PedidosComponent', () => {
+  it('should display empty state when no orders exist', async () => {
+    const mockService = { getPedidos: () => of({ items: [], total: 0 }) };
+    await TestBed.configureTestingModule({
+      providers: [{ provide: PedidosService, useValue: mockService }]
+    }).compileComponents();
+
+    const fixture = TestBed.createComponent(PedidosComponent);
+    fixture.detectChanges();
+
+    const emptyState = fixture.nativeElement.querySelector('[data-testid="empty-state"]');
+    expect(emptyState).toBeTruthy();
+  });
+});
+```
+
+---
+
+## Cobertura mínima obligatoria
+
+| Tipo de módulo | Cobertura mínima |
+|---------------|-----------------|
+| Services (lógica crítica) | 90% |
+| Endpoints (API) | 85% |
+| Utilities / helpers | 95% |
+| Componentes Angular | 75% |
+| Modelos ORM | 70% |
+
+**Verificar** con reporte de cobertura antes de marcar tarea como completada:
+```bash
+pytest --cov=src/services --cov-fail-under=90
+```
+
+---
+
+## Anti-patrones TDD a evitar
+
+| Anti-patrón | Descripción | Solución |
+|-------------|-------------|---------|
+| Test del mock | El test solo verifica que se llamó el mock, no el comportamiento real | Testear el efecto observable |
+| Test omnibus | Un solo test que verifica 10 cosas a la vez | Un test, un comportamiento |
+| Test frágil | Falla si cambias nombres internos sin cambiar comportamiento | Testear comportamiento, no implementación |
+| Fixture global | Un fixture que modifica estado global compartido entre tests | Fixtures con scope limitado, rollback |
+| Skip como solución | `@pytest.mark.skip` para tests que fallan | Arreglar el bug o eliminar el test |
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**El ciclo TDD se rompe cuando el test en fase RED pasa sin implementación porque la función ya existe con otro nombre en el módulo y Python la importa silenciosamente desde un namespace diferente**: escribir `from app.services import calcular_descuento` en el test cuando `calcular_descuento` ya existe en `app.utils` (importada en `__init__.py`) hace que el test pase en RED sin error, invalidando el ciclo. Causa: los imports con `from app.services import *` en `__init__.py` pueden re-exportar funciones de submódulos, haciendo que el test encuentre una implementación inesperada. Fix: verificar con `python -c "from app.services import calcular_descuento; print(calcular_descuento.__module__)"` que el símbolo viene del módulo correcto. Usar imports explícitos en los tests (`from app.services.descuentos import calcular_descuento`) en lugar de imports de paquete.
+
+**`pytest.mark.asyncio` con `asyncio_mode = "auto"` en `pytest.ini` hace que fixtures síncronos que retornan coroutines sean llamados sin `await`, causando que el fixture entregue un objeto coroutine en lugar del valor esperado**: un fixture `def cliente_premium(db_session)` que retorna `ClienteFactory.build(tipo="premium")` funciona, pero si accidentalmente se define como `async def cliente_premium(db_session)` y se usa en un test síncrono, pytest lo trata como fixture síncrono y el test recibe el objeto coroutine. Causa: la mezcla de fixtures `async def` y `def` en el mismo `conftest.py` con `asyncio_mode = "auto"` puede crear comportamientos inesperados dependiendo de la versión de `pytest-asyncio`. Fix: en proyectos async, definir TODOS los fixtures relevantes como `async def` explícitamente y verificar que el test use `@pytest.mark.asyncio` o tenga el modo auto configurado correctamente.
+
+**La fase REFACTOR del ciclo TDD en componentes Angular introduce regresiones silenciosas cuando se extrae lógica a un `computed()` pero el template sigue usando la función directa que ahora devuelve `undefined`**: refactorizar `getTotal()` como método del componente hacia `total = computed(() => ...)` y olvidar actualizar el template de `{{ getTotal() }}` a `{{ total() }}` no genera error de compilación con Angular 17+; el template simplemente muestra `undefined`. Causa: Angular no verifica en tiempo de compilación que los métodos referenciados en templates existen en la clase si el template usa la sintaxis de interpolación sin type-checking estricto. Fix: activar `strictTemplates: true` en `tsconfig.app.json` para que el compilador de Angular valide que todas las referencias en templates corresponden a miembros públicos del componente. Ejecutar `ng build` antes de considerar el REFACTOR completo.
+
+**`db_session.rollback()` en el fixture de pytest-asyncio no deshace los datos insertados por `db.flush()` dentro de la función testeada cuando la sesión usa `autocommit=True` implícito por configuración del engine**: algunos proyectos configuran `AsyncEngine` con `isolation_level="AUTOCOMMIT"` para compatibilidad con operaciones DDL; en ese contexto, cada `flush()` hace commit inmediatamente y el `rollback()` del fixture no puede deshacer esos cambios. Causa: `AUTOCOMMIT` en PostgreSQL significa que no hay transacción activa que se pueda revertir. Fix: verificar que el engine de tests NO use `isolation_level="AUTOCOMMIT"` (la configuración debe ser solo para el engine de migraciones Alembic, no para el de la app). Para tests que necesitan AUTOCOMMIT por alguna razón, usar una BD de test separada que se trunca con `TRUNCATE ... RESTART IDENTITY CASCADE` en el teardown del fixture.