@saulwade/swl-ses 1.0.0

package/habilidades/rails-experto/recursos/testing-rspec.md

@@ -0,0 +1,362 @@
+# Testing con RSpec en Rails
+
+Referencia de configuración y patrones de testing con RSpec, FactoryBot,
+Capybara y SimpleCov para Rails 7+.
+
+---
+
+## Configuración base
+
+```ruby
+# spec/rails_helper.rb
+require 'spec_helper'
+ENV['RAILS_ENV'] ||= 'test'
+require_relative '../config/environment'
+abort("Entorno no es test") if Rails.env.production?
+
+require 'rspec/rails'
+require 'capybara/rspec'
+require 'factory_bot_rails'
+
+RSpec.configure do |config|
+  config.fixture_path        = Rails.root.join('spec/fixtures')
+  config.use_transactional_fixtures = true
+  config.infer_spec_type_from_file_location!
+  config.filter_rails_from_backtrace!
+
+  config.include FactoryBot::Syntax::Methods
+  config.include Devise::Test::IntegrationHelpers, type: :request
+end
+
+# spec/spec_helper.rb
+require 'simplecov'
+SimpleCov.start 'rails' do
+  add_filter '/spec/'
+  enable_coverage :branch  # coverage de ramas, no solo líneas
+  minimum_coverage 90
+end
+
+RSpec.configure do |config|
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+  config.order = :random
+  config.warnings = true
+end
+```
+
+---
+
+## FactoryBot — factories, traits y sequences
+
+```ruby
+# spec/factories/users.rb
+FactoryBot.define do
+  factory :user do
+    sequence(:email) { |n| "usuario#{n}@ejemplo.com" }
+    nombre { "Usuario de Prueba" }
+    password { "contraseña_segura_123" }
+
+    trait :admin do
+      role { :admin }
+    end
+
+    trait :con_posts do
+      after(:create) { |user| create_list(:post, 3, author: user) }
+    end
+  end
+end
+
+# spec/factories/posts.rb
+FactoryBot.define do
+  factory :post do
+    sequence(:titulo) { |n| "Post de prueba #{n}" }
+    cuerpo { "Contenido del post de prueba" }
+    status { :publicado }
+    association :author, factory: :user
+
+    trait :borrador do
+      status { :borrador }
+    end
+
+    trait :con_comentarios do
+      after(:create) { |post| create_list(:comment, 2, post: post) }
+    end
+  end
+end
+```
+
+**Regla**: preferir `build` sobre `create` cuando el test no requiere persistencia
+— es significativamente más rápido.
+
+```ruby
+build(:post)            # objeto en memoria, sin BD
+create(:post)           # persiste en BD
+build_stubbed(:post)    # objeto stub, más rápido que build para asociaciones
+create(:post, :borrador, :con_comentarios)  # traits combinados
+```
+
+---
+
+## Tests de modelo
+
+```ruby
+# spec/models/post_spec.rb
+RSpec.describe Post, type: :model do
+  subject(:post) { build(:post) }
+
+  describe 'validaciones' do
+    it { is_expected.to validate_presence_of(:titulo) }
+    it { is_expected.to validate_length_of(:titulo).is_at_most(200) }
+    it { is_expected.to validate_presence_of(:cuerpo) }
+  end
+
+  describe 'asociaciones' do
+    it { is_expected.to belong_to(:author).class_name('User') }
+    it { is_expected.to have_many(:comments).dependent(:destroy) }
+  end
+
+  describe 'scopes' do
+    describe '.publicados' do
+      let!(:publicado) { create(:post, status: :publicado) }
+      let!(:borrador)  { create(:post, status: :borrador) }
+
+      it 'incluye solo posts publicados' do
+        expect(Post.publicados).to include(publicado)
+        expect(Post.publicados).not_to include(borrador)
+      end
+    end
+  end
+end
+```
+
+---
+
+## Request specs para APIs (mejor que controller specs)
+
+Los request specs prueban el stack completo de la request (middleware incluido).
+Son la opción recomendada para APIs REST.
+
+```ruby
+# spec/requests/posts_spec.rb
+RSpec.describe "Posts", type: :request do
+  let(:user) { create(:user) }
+
+  before { sign_in user }
+
+  describe "GET /posts" do
+    let!(:posts) { create_list(:post, 3, author: user) }
+
+    it "devuelve lista de posts con HTTP 200" do
+      get posts_path
+      expect(response).to have_http_status(:ok)
+      expect(response.body).to include(posts.first.titulo)
+    end
+  end
+
+  describe "POST /posts" do
+    context "con parámetros válidos" do
+      let(:params) { { post: attributes_for(:post) } }
+
+      it "crea el post y redirige" do
+        expect { post posts_path, params: params }
+          .to change(Post, :count).by(1)
+        expect(response).to redirect_to(Post.last)
+      end
+    end
+
+    context "con parámetros inválidos" do
+      let(:params) { { post: { titulo: "" } } }
+
+      it "no crea el post y responde 422" do
+        expect { post posts_path, params: params }
+          .not_to change(Post, :count)
+        expect(response).to have_http_status(:unprocessable_entity)
+      end
+    end
+  end
+end
+```
+
+---
+
+## System specs con Capybara + Selenium
+
+Para probar flujos con JavaScript (Turbo, Stimulus).
+
+```ruby
+# spec/system/crear_post_spec.rb
+RSpec.describe "Crear post", type: :system do
+  let(:user) { create(:user) }
+
+  before do
+    driven_by :selenium, using: :headless_chrome
+    sign_in user
+  end
+
+  it "el usuario puede crear un post y verlo en la lista" do
+    visit new_post_path
+
+    fill_in "Título", with: "Mi nuevo post"
+    fill_in "Cuerpo", with: "Contenido detallado del post"
+    click_button "Publicar"
+
+    expect(page).to have_text("Publicación creada")
+    expect(page).to have_text("Mi nuevo post")
+  end
+
+  it "muestra errores con parámetros inválidos" do
+    visit new_post_path
+    click_button "Publicar"
+
+    expect(page).to have_text("Título no puede estar en blanco")
+  end
+end
+```
+
+---
+
+## Shared examples y shared contexts
+
+```ruby
+# spec/support/shared_examples/authenticatable.rb
+RSpec.shared_examples "requiere autenticación" do
+  context "sin sesión iniciada" do
+    before { sign_out :user }
+
+    it "redirige al login" do
+      subject
+      expect(response).to redirect_to(new_user_session_path)
+    end
+  end
+end
+
+# Uso en spec
+RSpec.describe "Posts", type: :request do
+  describe "GET /posts/new" do
+    subject { get new_post_path }
+    it_behaves_like "requiere autenticación"
+  end
+end
+
+# Shared context para setup reutilizable
+RSpec.shared_context "usuario autenticado" do
+  let(:user) { create(:user) }
+  before { sign_in user }
+end
+
+RSpec.describe "Posts", type: :request do
+  include_context "usuario autenticado"
+end
+```
+
+---
+
+## Mocking con instance_double y class_double
+
+```ruby
+# instance_double verifica que los métodos existen en la clase real
+RSpec.describe Posts::CrearService do
+  let(:mailer) { instance_double(NotificacionMailer) }
+
+  before do
+    allow(NotificacionMailer).to receive(:nueva_publicacion).and_return(mailer)
+    allow(mailer).to receive(:deliver_later)
+  end
+
+  it "encola notificación al crear post exitosamente" do
+    result = described_class.call(autor: create(:user), parametros: attributes_for(:post))
+
+    expect(result.exitoso?).to be true
+    expect(NotificacionMailer).to have_received(:nueva_publicacion)
+  end
+end
+
+# class_double para stubs de métodos de clase
+let(:job) { class_double(NotificarSeguidoresJob).as_stubbed_const }
+before    { allow(job).to receive(:perform_later) }
+```
+
+---
+
+## DatabaseCleaner
+
+Necesario cuando se mezclan specs con `js: true` (que usan transacciones separadas).
+
+```ruby
+# spec/support/database_cleaner.rb
+RSpec.configure do |config|
+  config.before(:suite) do
+    DatabaseCleaner.clean_with(:truncation)
+  end
+
+  config.before(:each) do
+    DatabaseCleaner.strategy = :transaction
+  end
+
+  config.before(:each, js: true) do
+    DatabaseCleaner.strategy = :truncation
+  end
+
+  config.before(:each) { DatabaseCleaner.start }
+  config.after(:each)  { DatabaseCleaner.clean }
+end
+```
+
+---
+
+## SimpleCov con branch coverage
+
+```ruby
+# spec/spec_helper.rb (ya mostrado arriba, recordatorio)
+SimpleCov.start 'rails' do
+  add_filter '/spec/'
+  add_filter '/config/'
+  add_group  'Controllers',    'app/controllers'
+  add_group  'Models',         'app/models'
+  add_group  'Services',       'app/services'
+  add_group  'Jobs',           'app/jobs'
+  enable_coverage :branch
+  minimum_coverage 90
+end
+```
+
+Ejecutar y ver reporte:
+
+```bash
+bundle exec rspec
+open coverage/index.html
+```
+
+---
+
+## Convenciones Rubocop-RSpec
+
+```ruby
+# .rubocop.yml — sección RSpec
+RSpec:
+  Max: 250  # líneas por archivo spec
+
+RSpec/ExampleLength:
+  Max: 10   # líneas por ejemplo
+
+RSpec/MultipleExpectations:
+  Max: 3    # expects por ejemplo
+
+RSpec/NestedGroups:
+  Max: 4    # niveles de anidamiento describe/context
+```
+
+**Reglas de convención:**
+- Un `describe` por clase pública, un `context` por escenario
+- Nombrar contexts: `"cuando [condición]"`, `"con [estado]"`, `"sin [algo]"`
+- Nombrar examples: `"[sujeto] [verbo] [resultado esperado]"`
+- Preferir `let!` sobre `before { @var = ... }` para legibilidad
+
+---
+
+## Referencias externas
+
+- [RSpec Rails — documentación](https://relishapp.com/rspec/rspec-rails/docs)
+- [FactoryBot — guía](https://github.com/thoughtbot/factory_bot/blob/main/GETTING_STARTED.md)
+- [Capybara — DSL](https://github.com/teamcapybara/capybara#the-dsl)
+- [SimpleCov](https://github.com/simplecov-ruby/simplecov)
+- [Rubocop-RSpec](https://docs.rubocop.org/rubocop-rspec/)

package/habilidades/react-experto/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: react-experto
+description: React + Next.js mejores prácticas modernas. Cubre Server Components vs Client Components, data fetching patterns (RSC, React Query, SWR, Server Actions), state management (useState, Zustand, Jotai), performance (memo, lazy, Suspense, streaming) y Next.js App Router patterns.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para optimización de rendimiento React (memo, useMemo, useCallback, virtualización, code splitting) — para rendimiento cargar `react-optimizacion`."
+  - "No cargar para patrones y configuraciones específicas de Next.js (App Router avanzado, middleware, ISR, layouts anidados) — para Next.js cargar `nextjs-experto`."
+  - "No cargar para Angular, Vue o Svelte — Server Components y el modelo de composición son específicos de React."
+  - "No cargar para testing React (Testing Library, Vitest, MSW) — para testing cargar `nextjs-testing`."
+evolvable: true  # default para skill estandar
+---
+# React Experto — React 19 + Next.js 15
+
+## Cuándo NO cargar
+
+- La tarea es específicamente optimización de rendimiento React: memo, useMemo, useCallback, virtualización o code splitting — cargar `react-optimizacion`.
+- La pregunta es sobre Next.js avanzado: middleware, ISR, layouts anidados, route handlers — cargar `nextjs-experto`.
+- El framework es Angular, Vue o Svelte — Server Components y el modelo de composición RSC son específicos de React/Next.js.
+- La tarea es escribir tests React con Testing Library, Vitest o MSW — cargar `nextjs-testing`.
+
+## Principio Fundamental
+
+React moderno separa responsabilidades en dos mundos:
+- **Server Components (RSC)**: renderizan en el servidor, acceden a datos directamente, NO tienen estado ni efectos
+- **Client Components**: se ejecutan en el navegador, tienen estado, efectos e interactividad
+
+La regla de oro: **por defecto todo es Server Component**. Solo se agrega `"use client"` cuando se necesita interactividad.
+
+---
+
+## Reglas Obligatorias
+
+1. **Server Component por defecto** — solo agregar `"use client"` cuando se necesita interactividad (onClick, useState, useEffect, browser APIs).
+2. **NUNCA importar Server Component desde Client Component** — el flujo es Server -> Client (via props/children).
+3. **NUNCA fetch en useEffect cuando RSC esta disponible** — usar Server Component con fetch directo.
+4. **NUNCA useEffect para transformar datos** — usar `useMemo` para valores derivados.
+5. **NUNCA key con index en listas mutables** — usar ID estable.
+6. **Validar con Zod en Server Actions** — SIEMPRE validar server-side.
+7. **Selectores especificos en stores** — evitar re-renders suscribiendose solo al slice necesario.
+
+---
+
+## Server Components vs Client Components
+
+### Server Component (default)
+
+```tsx
+// app/usuarios/page.tsx — NO lleva "use client"
+import { db } from '@/lib/db';
+
+export default async function UsuariosPage() {
+  const usuarios = await db.usuario.findMany({ where: { activo: true } });
+  return (
+    <ul>
+      {usuarios.map(u => <li key={u.id}>{u.nombre}</li>)}
+    </ul>
+  );
+}
+```
+
+### Client Component
+
+```tsx
+"use client";
+import { useState } from 'react';
+
+export function ContadorInteractivo() {
+  const [count, setCount] = useState(0);
+  return (
+    <button onClick={() => setCount(c => c + 1)}>Clicks: {count}</button>
+  );
+}
+```
+
+### Composicion correcta: RSC envuelve Client
+
+```tsx
+// app/dashboard/page.tsx (Server Component)
+import { BotonFiltro } from '@/components/BotonFiltro'; // Client Component
+import { db } from '@/lib/db';
+
+export default async function DashboardPage() {
+  const datos = await db.reporte.findMany();
+  return <BotonFiltro datosIniciales={datos} />;
+}
+```
+
+---
+
+## Data Fetching — RSC Fetch (preferido)
+
+```tsx
+async function getDatos() {
+  const res = await fetch('https://api.ejemplo.com/datos', {
+    next: { revalidate: 60 },   // ISR: revalidar cada 60 segundos
+  });
+  if (!res.ok) throw new Error('Error al obtener datos');
+  return res.json();
+}
+```
+
+---
+
+## State Management — Cuando usar que
+
+| Herramienta | Cuando |
+|-------------|--------|
+| `useState` | Estado local de UI simple |
+| `useMemo` | Valores derivados/computados |
+| **Zustand** | Estado global ligero compartido entre componentes |
+| **Jotai** | Estado atomico con dependencias complejas |
+| **React Query** | Cache de datos del servidor en Client Components |
+
+---
+
+## Performance
+
+### React.memo — evitar re-renders innecesarios
+
+```tsx
+const TarjetaUsuario = React.memo(function TarjetaUsuario({ usuario }: Props) {
+  return <div>{usuario.nombre}</div>;
+});
+```
+
+### React.lazy + Suspense — code splitting
+
+```tsx
+const EditorRich = lazy(() => import('@/components/EditorRich'));
+
+function Pagina() {
+  return (
+    <Suspense fallback={<div>Cargando editor...</div>}>
+      <EditorRich />
+    </Suspense>
+  );
+}
+```
+
+---
+
+## Anti-patrones Criticos
+
+```tsx
+// MAL: useEffect para transformar datos
+const [filtrados, setFiltrados] = useState([]);
+useEffect(() => {
+  setFiltrados(usuarios.filter(u => u.activo));
+}, [usuarios]);
+
+// BIEN: useMemo
+const filtrados = useMemo(() => usuarios.filter(u => u.activo), [usuarios]);
+```
+
+```tsx
+// MAL: fetch en Client Component cuando podria ser RSC
+useEffect(() => {
+  fetch('/api/datos').then(r => r.json()).then(setDatos);
+}, []);
+
+// BIEN: Server Component con fetch directo
+const datos = await db.datos.findMany();
+```
+
+```tsx
+// MAL: key con index en lista mutable
+{items.map((item, index) => <Item key={index} {...item} />)}
+
+// BIEN: key con ID estable
+{items.map(item => <Item key={item.id} {...item} />)}
+```
+
+```tsx
+// MAL: componente importa librería de terceros directamente
+import { loadStripe } from '@stripe/stripe-js';
+import { Elements } from '@stripe/react-stripe-js';
+
+export function Checkout() {
+    const stripe = loadStripe(process.env.NEXT_PUBLIC_STRIPE_KEY!);
+    return <Elements stripe={stripe}>...</Elements>;
+}
+
+// BIEN: adapter hook con interfaz estable — el componente no conoce Stripe
+import { usePagos } from '@/hooks/usePagos';
+
+export function Checkout() {
+    const { iniciarSesion, estado } = usePagos();
+    return <FormularioPago onSubmit={iniciarSesion} estado={estado} />;
+}
+```
+
+Toda API de terceros (Stripe, MapBox, analytics, browser APIs complejas) debe
+envolverse en un hook adapter con interfaz estable. El componente NUNCA importa
+la librería directamente — esto permite cambiar el proveedor sin tocar la UI.
+
+---
+
+Para ejemplos completos de React Query (mutations + invalidacion), Server Actions con Zod, Zustand con immer, Jotai atomico, Next.js App Router (estructura, route handlers, metadata, streaming con Suspense), ver [recursos/patrones-y-ejemplos-completos.md](recursos/patrones-y-ejemplos-completos.md).
+
+## Gotchas / Errores comunes no obvios
+
+**Un Client Component que importa un Server Component lo convierte en Client Component silenciosamente**: si `CartaUsuario.tsx` tiene `"use client"` e importa `FotoAvatar.tsx` (Server Component), Next.js convierte `FotoAvatar` a Client Component sin advertencia. Causa: el boundary `"use client"` se propaga hacia abajo en el árbol de importaciones. Fix: para pasar Server Components a Client Components, usar el patrón `children` o `slot` — el Client Component recibe el Server Component como prop `children`, no lo importa directamente.
+
+**`useEffect` con array de dependencias vacío ejecuta dos veces en React 18 en modo desarrollo (StrictMode)**: React 18 con StrictMode monta, desmonta y vuelve a montar cada componente en desarrollo para detectar efectos no idempotentes. Una petición en `useEffect(fn, [])` puede dispararse dos veces. Causa: comportamiento intencional de StrictMode para detectar limpieza de efectos incorrecta. Fix: asegurarse de que el effect tiene función de cleanup correcta (ej: `return () => controller.abort()`); en producción solo se ejecuta una vez.
+
+**Server Action que actualiza datos sin `revalidatePath` o `revalidateTag` muestra datos obsoletos**: después de un Server Action exitoso (crear/actualizar/eliminar), el cliente sigue viendo el caché anterior del RSC. Causa: Next.js cachea agresivamente los datos del servidor; los Server Actions no invalidan el caché automáticamente. Fix: llamar `revalidatePath('/ruta/afectada')` o `revalidateTag('tag-del-dato')` al final del Server Action antes de `redirect()` o `return`.
+
+**`useState` con objeto como valor inicial no se actualiza con shallow comparison en re-renders del padre**: `useState({ nombre: '', email: '' })` inicializa el estado una sola vez — si el componente padre pasa nuevos valores como prop para reinicializar el formulario, el estado no se actualiza. Causa: `useState` solo usa el valor inicial en el primer render. Fix: usar `key` en el componente para forzar remonte cuando cambien los datos base, o usar `useEffect` con las props como dependencias para sincronizar explícitamente.

package/habilidades/react-experto/evals/evals.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "react-experto",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para react-experto — hooks, estado, patrones modernos, anti-patrones comunes.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Contador con botón — componente React mínimo y moderno.",
+      "files": [],
+      "expectations": [
+        "Usa `useState` hook.",
+        "Función component, no class component.",
+        "TypeScript con tipo explícito (o comentado si no aplica)."
+      ],
+      "tags": ["primary-flow"]
+    },
+    {
+      "id": "useeffect-deps",
+      "prompt": "Tengo `useEffect(() => { fetchData(userId); }, [])`. ¿Qué está mal?",
+      "files": [],
+      "expectations": [
+        "Falta `userId` en el array de dependencias.",
+        "La respuesta explica: stale closure — `userId` queda congelado al valor inicial.",
+        "Solución: `[userId]` como dependencia, o reconsiderar si realmente debe correr solo una vez."
+      ],
+      "grading_guidance": "Failure si no identifica el problema de dependencias.",
+      "tags": ["anti-pattern"],
+      "weight": 1.5
+    },
+    {
+      "id": "key-prop",
+      "prompt": "Renderizar lista con `items.map((item, i) => <Row key={i} ... />)` ¿Está bien?",
+      "files": [],
+      "expectations": [
+        "NO usar índice como key si la lista puede reordenar/filtrar.",
+        "Usar ID estable del item (`item.id`).",
+        "La respuesta explica por qué: React asocia estado al key; con índice se reasigna incorrectamente."
+      ],
+      "tags": ["anti-pattern"]
+    },
+    {
+      "id": "state-derivation",
+      "prompt": "Tengo `useState` para `items` y otro `useState` para `total` que es sum de items. ¿Está bien?",
+      "files": [],
+      "expectations": [
+        "NO — estado derivable no debe ser estado.",
+        "Solución: calcular `total` directamente en el render, o `useMemo` si el cálculo es costoso.",
+        "Razón: evita bugs de sincronización."
+      ],
+      "tags": ["anti-pattern"]
+    }
+  ]
+}