swl-ses 3.3.2

package/habilidades/tailwind-experto/SKILL.md

@@ -0,0 +1,412 @@
+---
+name: tailwind-experto
+description: Tailwind CSS v4 mejores prácticas. Cubre configuración CSS-first con @theme y @custom-variant, design tokens en Tailwind, patrones de componentes, responsive con breakpoints, dark mode, plugins custom, compilación JIT y anti-patrones como utility soup y @apply abuse.
+---
+
+# Tailwind CSS v4 Experto
+
+## Cambio Fundamental en v4
+
+Tailwind v4 abandona el archivo `tailwind.config.js` en favor de **configuración
+directa en CSS**. No más archivo de configuración JavaScript — todo se define
+con `@theme` y directivas CSS nativas.
+
+```css
+/* app/globals.css — la config ahora está aquí */
+@import "tailwindcss";
+
+@theme {
+  --font-sans: 'Inter', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+
+  --color-primario: oklch(56% 0.2 250);
+  --color-primario-oscuro: oklch(46% 0.2 250);
+  --color-secundario: oklch(70% 0.15 160);
+
+  --radius-sm: 0.25rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+  --radius-xl: 1rem;
+
+  --spacing-18: 4.5rem;
+  --spacing-88: 22rem;
+}
+```
+
+---
+
+## 1. Configuración @theme
+
+### 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
+
+```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;
+}
+```
+
+---
+
+## 2. @custom-variant
+
+Define variantes personalizadas sin plugin:
+
+```css
+/* Variante para elementos con data attribute */
+@custom-variant data-activo (&[data-activo='true']);
+@custom-variant data-disabled (&[data-disabled='true']);
+@custom-variant data-error (&[data-error='true']);
+
+/* Uso en HTML */
+/* <div data-activo="true" class="data-activo:bg-marca-100 data-activo:border-marca-500"> */
+```
+
+```css
+/* Variante para grupos custom */
+@custom-variant sidebar-collapsed (.sidebar-collapsed &);
+@custom-variant print-hidden (@media print { & { display: none; } });
+
+/* Uso */
+/* <nav class="w-64 sidebar-collapsed:w-16 transition-all"> */
+```
+
+---
+
+## 3. Patrones de Componentes
+
+### Patrón: clases base + variantes
+
+```tsx
+// components/Button.tsx
+import { cva, type VariantProps } from 'class-variance-authority';
+
+const buttonVariants = cva(
+  // Clases base siempre presentes
+  'inline-flex items-center justify-center gap-2 rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-marca-500 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variante: {
+        primario: 'bg-marca-500 text-white hover:bg-marca-600 active:bg-marca-700',
+        secundario: 'bg-transparent border border-marca-500 text-marca-600 hover:bg-marca-50',
+        ghost: 'hover:bg-gray-100 text-gray-700',
+        destructivo: 'bg-error text-white hover:bg-red-700',
+      },
+      tamano: {
+        sm: 'h-8 px-3 text-sm',
+        md: 'h-10 px-4 text-base',
+        lg: 'h-12 px-6 text-lg',
+      },
+    },
+    defaultVariants: {
+      variante: 'primario',
+      tamano: 'md',
+    },
+  }
+);
+
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+export function Button({ variante, tamano, className, ...props }: ButtonProps) {
+  return (
+    <button
+      className={buttonVariants({ variante, tamano, className })}
+      {...props}
+    />
+  );
+}
+```
+
+### 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' },
+});
+```
+
+---
+
+## 4. Responsive con Breakpoints
+
+### Sistema de breakpoints (v4 por defecto)
+
+| Prefijo | Ancho mínimo | Dispositivo típico |
+|---------|-------------|-------------------|
+| `sm:`   | 640px       | Móvil grande |
+| `md:`   | 768px       | Tablet |
+| `lg:`   | 1024px      | Laptop |
+| `xl:`   | 1280px      | Desktop |
+| `2xl:`  | 1536px      | Pantalla grande |
+
+### Mobile-first (siempre)
+
+```html
+<!-- Correcto: móvil base, desktop override -->
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+
+<!-- MAL: desktop base, móvil override (requiere sobreescribir) -->
+<div class="grid grid-cols-3 max-md:grid-cols-1">
+```
+
+### Breakpoints personalizados en v4
+
+```css
+@theme {
+  --breakpoint-xs:  475px;
+  --breakpoint-3xl: 1920px;
+}
+```
+
+---
+
+## 5. Dark Mode en v4
+
+```css
+/* globals.css */
+@import "tailwindcss";
+
+/* Modo oscuro por sistema */
+@theme {
+  --color-fondo: #ffffff;
+  --color-texto: #0f172a;
+}
+
+@media (prefers-color-scheme: dark) {
+  @theme {
+    --color-fondo: #0f172a;
+    --color-texto: #f1f5f9;
+  }
+}
+```
+
+```tsx
+// Dark mode con clase manual (toggle)
+<html className={tema === 'oscuro' ? 'dark' : ''}>
+
+// En el CSS
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+```html
+<!-- Uso de variante dark -->
+<div class="bg-white dark:bg-slate-900 text-slate-900 dark:text-slate-100">
+```
+
+---
+
+## 6. Plugins Custom
+
+```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' },
+          },
+        },
+      },
+    },
+  }
+);
+```
+
+---
+
+## 7. 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)">
+```
+
+---
+
+## 8. Anti-patrones
+
+### Utility Soup — demasiadas clases en un elemento
+
+```html
+<!-- MAL: ilegible, difícil de mantener -->
+<button class="inline-flex items-center justify-center gap-2 rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white shadow-sm transition-colors hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 active:bg-blue-800 disabled:cursor-not-allowed disabled:opacity-50">
+
+<!-- BIEN: extraer componente con cva() -->
+<Button variante="primario" tamano="sm">Guardar</Button>
+```
+
+### @apply Abuse — recrear Sass con Tailwind
+
+```css
+/* MAL: el propósito de @apply es crear un nuevo .scss, no reutilizar utilidades */
+.card {
+  @apply rounded-lg border border-gray-200 bg-white p-6 shadow-sm;
+}
+.card-header {
+  @apply border-b border-gray-200 pb-4 mb-4;
+}
+
+/* BIEN: si el patrón es reutilizable, hacer componente React/Vue/Angular */
+/* Si es un patrón CSS puro, usar custom property o @layer componentes */
+@layer componentes {
+  .card {
+    border-radius: var(--radius-lg);
+    border: 1px solid var(--color-borde);
+    background: var(--color-superficie);
+    padding: var(--spacing-6);
+    box-shadow: var(--shadow-sm);
+  }
+}
+```
+
+### Clases condicionales con interpolación de string
+
+```tsx
+// MAL: Tailwind JIT no puede detectar clases dinámicas construidas con interpolación
+const color = 'azul';
+<div className={`bg-${color}-500`}> // 'bg-azul-500' no existe en el output
+
+// BIEN: objeto de mapeo completo
+const colorMap = {
+  azul:  'bg-blue-500',
+  rojo:  'bg-red-500',
+  verde: 'bg-green-500',
+} as const;
+<div className={colorMap[color]}>
+```
+
+### 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,267 @@
+---
+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).
+---
+
+# Habilidad: TDD Workflow Completo
+
+## 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 |