@saulwade/swl-ses 1.0.0

package/habilidades/php-patrones/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: php-patrones
+description: >
+  Patrones Laravel modernos: Action classes, Service classes, DTOs readonly,
+  Pipeline, Repository con interfaces, Enums, Value Objects y Feature Flags.
+  Cargar cuando se diseñe arquitectura Laravel o se refactoricen controllers.
+version: "1.0.0"
+herramientasPermitidas: [Read, Glob, Grep]
+exclusiones:
+  - "No cargar para implementar controllers, modelos Eloquent o Jobs concretos — para implementación cargar `php-experto`."
+  - "No cargar para escribir tests PHPUnit o Pest — para testing cargar `php-testing`."
+  - "No cargar para errores de Composer o extensiones PHP — para build errors cargar `build-errors-php`."
+  - "No cargar para patrones de diseño genéricos sin contexto Laravel — este skill cubre Action classes, Service classes y Value Objects en el contexto del ecosistema Laravel."
+evolvable: true  # default para skill estandar
+---
+# PHP Patrones — Arquitectura Laravel Moderna
+
+Los controladores de Laravel son puntos de entrada HTTP, no contenedores de
+lógica de negocio. Este skill cubre los patrones que mantienen el código
+organizado, testeable y mantenible a medida que la aplicación crece.
+
+## Cuándo cargar este skill
+
+Invoca `Skill("php-patrones")` cuando:
+
+- Se refactorice un controller con más de 50 líneas de lógica
+- Se diseñe la arquitectura de un módulo nuevo
+- Se implemente un flujo con múltiples pasos secuenciales
+- Se requieran DTOs tipados para transferir datos entre capas
+- Se evalúen feature flags con Laravel Pennant
+
+## Cuándo NO cargar
+
+- La pregunta es sobre implementar controllers, modelos Eloquent o Jobs concretos — para implementación cargar `php-experto`.
+- La tarea es escribir tests PHPUnit o Pest — cargar `php-testing`.
+- Los errores son de Composer o extensiones PHP — cargar `build-errors-php`.
+- La discusión es sobre patrones GoF genéricos sin contexto Laravel — este skill cubre Action classes, Service classes y Value Objects en el ecosistema Laravel.
+
+## Conceptos clave
+
+### Action Classes — una clase, una operación
+
+Una Action encapsula una operación de negocio específica. Es testeable de forma
+aislada, reutilizable desde controllers, jobs y commands, y su nombre documenta
+exactamente lo que hace.
+
+### Pipeline Pattern
+
+El Pipeline de Laravel permite encadenar operaciones sobre un objeto de forma
+funcional. Cada etapa (pipe) recibe el objeto, lo transforma y lo pasa al siguiente.
+Ideal para flujos con validaciones, transformaciones y efectos secundarios.
+
+### DTOs con readonly
+
+Los Data Transfer Objects con `readonly` en PHP 8.1+ son inmutables por definición.
+Eliminan setters, garantizan que los datos no cambian después de construirse y
+self-documentan la estructura de datos que fluye entre capas.
+
+## Reglas obligatorias
+
+### Actions: una responsabilidad, un método público `ejecutar()`
+
+```php
+// MAL — Service con multiples responsabilidades mezcladas
+class PedidoService {
+    public function crear(array $datos): Pedido { ... }
+    public function cancelar(Pedido $pedido): void { ... }
+    public function calcularDescuento(Pedido $pedido): float { ... }
+    public function enviarNotificacion(Pedido $pedido): void { ... }
+}
+
+// BIEN — Actions separadas y cohesivas
+class CrearPedidoAction {
+    public function ejecutar(CrearPedidoDTO $dto): Pedido { ... }
+}
+class CancelarPedidoAction {
+    public function ejecutar(Pedido $pedido, string $motivo): void { ... }
+}
+```
+
+### DTOs readonly para datos de entrada
+
+```php
+// MAL — array anonimo sin tipado
+public function ejecutar(array $datos): Pedido
+{
+    $nombre = $datos['nombre'] ?? null; // sin autocomplete, sin tipos
+}
+
+// BIEN — DTO readonly tipado
+readonly class CrearPedidoDTO
+{
+    public function __construct(
+        public string  $nombre,
+        public float   $total,
+        public ?string $cuponDescuento,
+        public array   $items,
+    ) {}
+
+    public static function desdeRequest(StorePedidoRequest $request): self
+    {
+        return new self(
+            nombre:          $request->validated('nombre'),
+            total:           0.0, // calculado luego
+            cuponDescuento:  $request->validated('cupon'),
+            items:           $request->validated('items'),
+        );
+    }
+}
+```
+
+### Repository con interface para abstraer el ORM
+
+```php
+interface PedidoRepositoryInterface
+{
+    public function encontrarPorId(int $id): ?Pedido;
+    public function listarPendientes(): Collection;
+    public function guardar(Pedido $pedido): Pedido;
+}
+
+class EloquentPedidoRepository implements PedidoRepositoryInterface
+{
+    public function encontrarPorId(int $id): ?Pedido
+    {
+        return Pedido::with(['items', 'cliente'])->find($id);
+    }
+    // ...
+}
+
+// Binding en AppServiceProvider
+$this->app->bind(PedidoRepositoryInterface::class, EloquentPedidoRepository::class);
+```
+
+**Por qué**: Permite swapear la implementación (ej: agregar cache) sin tocar
+la lógica de negocio. Facilita mocking en tests.
+
+## Patrones recomendados
+
+### Pipeline para flujos multi-etapa
+
+```php
+class ProcesarPedidoAction
+{
+    public function ejecutar(Pedido $pedido): Pedido
+    {
+        return app(Pipeline::class)
+            ->send($pedido)
+            ->through([
+                ValidarStockPipe::class,
+                AplicarDescuentoPipe::class,
+                CalcularEnvioPipe::class,
+                ReservarInventarioPipe::class,
+            ])
+            ->thenReturn();
+    }
+}
+
+class ValidarStockPipe
+{
+    public function handle(Pedido $pedido, Closure $next): Pedido
+    {
+        foreach ($pedido->items as $item) {
+            throw_unless($item->producto->tieneStock($item->cantidad),
+                new StockInsuficienteException($item->producto));
+        }
+        return $next($pedido);
+    }
+}
+```
+
+### Enum casting en modelos
+
+```php
+// Definir el enum (PHP 8.1+)
+enum EstatusPedido: string
+{
+    case Pendiente  = 'pendiente';
+    case Pagado     = 'pagado';
+    case Cancelado  = 'cancelado';
+
+    public function puedeTransicionarA(self $nuevo): bool
+    {
+        return match($this) {
+            self::Pendiente => in_array($nuevo, [self::Pagado, self::Cancelado]),
+            default         => false,
+        };
+    }
+}
+
+// Castear en el modelo
+class Pedido extends Model
+{
+    protected $casts = [
+        'estatus' => EstatusPedido::class,
+    ];
+}
+
+// Uso con tipado fuerte
+if ($pedido->estatus->puedeTransicionarA(EstatusPedido::Cancelado)) {
+    $pedido->update(['estatus' => EstatusPedido::Cancelado]);
+}
+```
+
+### Laravel Pennant para feature flags
+
+```php
+// Definir el flag en AppServiceProvider
+Feature::define('nuevo-checkout', fn (User $user) =>
+    $user->created_at->isAfter(now()->subDays(30))
+);
+
+// Verificar en el codigo
+if (Feature::active('nuevo-checkout')) {
+    return new NuevoCheckoutAction();
+}
+
+// En Blade
+@feature('nuevo-checkout')
+    <x-nuevo-checkout />
+@endfeature
+```
+
+### Value Objects para conceptos del dominio
+
+```php
+readonly class Dinero
+{
+    public function __construct(
+        public readonly float  $monto,
+        public readonly string $moneda = 'MXN',
+    ) {
+        if ($monto < 0) {
+            throw new \InvalidArgumentException("El monto no puede ser negativo");
+        }
+    }
+
+    public function sumar(self $otro): self
+    {
+        if ($this->moneda !== $otro->moneda) {
+            throw new MonedaIncompatibleException();
+        }
+        return new self($this->monto + $otro->monto, $this->moneda);
+    }
+
+    public function __toString(): string
+    {
+        return number_format($this->monto, 2) . ' ' . $this->moneda;
+    }
+}
+```
+
+## Anti-patrones conocidos
+
+### Fat Controllers — NUNCA más de 10 líneas de lógica por método
+
+Un controller que hace queries, calcula totales, envía emails y retorna respuesta
+es imposible de testear y mantener. Delegar a Actions o Services.
+
+### Model Callbacks para lógica compleja
+
+```php
+// MAL — logica oculta en boot() del modelo
+protected static function boot(): void
+{
+    static::created(function (Pedido $pedido) {
+        // envia email, actualiza inventario, crea factura...
+    });
+}
+
+// BIEN — logica explicita en un Event Listener o Action
+// El caller sabe que estas cosas suceden porque las ve en el codigo
+```
+
+### Helpers globales para lógica de negocio
+
+Los `helpers.php` globales son difíciles de testear y crean acoplamiento implícito.
+Usar classes estaticas o inyectables en su lugar.
+
+## Checklist de verificación
+
+- [ ] Controllers delegan a Actions o Services (< 15 líneas por método)
+- [ ] DTOs readonly para datos de entrada tipados
+- [ ] Enums en lugar de strings mágicos para estados
+- [ ] Repository interface si la lógica de acceso a datos es compleja
+- [ ] Pipeline para flujos con más de 3 pasos secuenciales
+- [ ] Feature flags para funcionalidades en desarrollo progresivo
+
+## Referencias
+
+- [Laravel Service Container](https://laravel.com/docs/container)
+- [PHP 8.1 Enums](https://www.php.net/manual/es/language.enumerations.php)
+- [Laravel Pennant](https://laravel.com/docs/pennant)
+
+## Gotchas / Errores comunes no obvios
+
+**Action class que lanza excepción en lugar de retornar `Result` o DTO rompe el flujo de la pipeline**: si una Action usa `throw new ValidationException(...)` internamente pero la pipeline espera un valor de retorno tipado, el calling code necesita un `try/catch` duplicado en cada lugar. Fix: definir la Action con retorno `Result<T>` o con un DTO de respuesta que incluya el estado de éxito/fallo — reservar las excepciones solo para errores inesperados.
+
+**Pipeline de Laravel que modifica `$passable` por referencia en lugar de retornar el nuevo valor no funciona con `Closure::class`**: si un pipe en la pipeline modifica el objeto pasado en lugar de retornar el resultado del `$next($passable)`, los pipes subsecuentes reciben el objeto original sin las modificaciones. Fix: siempre retornar `$next($passable)` desde cada pipe — la pipeline de Laravel es un chain de decorators, no una lista de efectos secundarios.
+
+**DTO `readonly` con propiedades de tipo objeto mutable no es realmente inmutable**: `readonly class FacturaDto { public function __construct(public readonly array $items) {} }` — `$dto->items` no puede reasignarse, pero si `$items` contiene objetos mutables, esos objetos pueden modificarse. Fix: usar `array_map` para crear copias de los objetos contenidos, o usar colecciones inmutables con tipos `readonly` anidados.
+
+**Feature flag con `Pennant::for($usuario)->active('flag')` no funciona en un Job sin el usuario en contexto**: dentro de un Job, el usuario autenticado no está disponible automáticamente — `Pennant::for(Auth::user())` retorna null si no se pasó el usuario explícitamente al job. Fix: pasar el usuario como propiedad del job en el constructor y usar `Pennant::for($this->usuario)->active('flag')` dentro del job.
+
+---
+*Skill creado con swl:crear-skill el 2026-03-31. Versión 1.0.0.*

package/habilidades/php-testing/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: php-testing
+description: >
+  Testing PHP con PHPUnit y Pest: factories, feature tests Laravel, Mockery,
+  HTTP tests, Job/Event faking y Dusk. Cargar cuando se escriban tests PHP,
+  se configuren factories o se establezca cobertura de código.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para implementar el código Laravel de producción — primero implementar con `php-experto`, luego escribir tests."
+  - "No cargar para diseñar patrones Laravel — para diseño cargar `php-patrones`."
+  - "No cargar para errores de Composer o extensiones PHP — para build errors cargar `build-errors-php`."
+  - "No cargar para tests de carga o rendimiento en PHP — JMeter, k6 y Gatling no están cubiertos en este skill."
+evolvable: true  # default para skill estandar
+---
+# PHP Testing — PHPUnit, Pest y Laravel Testing
+
+Laravel incluye una suite de testing completa sobre PHPUnit. Pest es una capa
+expresiva encima de PHPUnit que reduce boilerplate. Este skill cubre la escritura
+de tests idiomáticos para aplicaciones Laravel: feature tests, unit tests,
+factories, fakes y pruebas de browser con Dusk.
+
+## Cuándo cargar este skill
+
+Invoca `Skill("php-testing")` cuando:
+
+- Se escriban tests unitarios o de feature en Laravel
+- Se creen o modifiquen factories de Eloquent
+- Se configuren thresholds de cobertura de código
+- Se prueben Jobs, Events, Mail o Notifications
+- Se implementen browser tests con Laravel Dusk
+
+## Cuándo NO cargar
+
+- El código Laravel de producción aún no existe — primero implementar con `php-experto`, luego escribir tests.
+- La pregunta es sobre diseñar patrones Laravel (Action classes, DTOs) — cargar `php-patrones`.
+- Los errores son de Composer o extensiones PHP en los tests — cargar `build-errors-php`.
+- La pregunta es sobre tests de carga o rendimiento — JMeter, k6 y Gatling no están cubiertos en este skill.
+
+## Conceptos clave
+
+### PHPUnit vs Pest
+
+PHPUnit usa clases que extienden `TestCase`. Pest usa funciones globales `it()`,
+`test()` y `describe()` con una API fluida. Pest compila a PHPUnit internamente
+— no son incompatibles, pueden coexistir.
+
+### RefreshDatabase vs DatabaseTransactions
+
+`RefreshDatabase` recrea el schema completo antes de cada test (lento, aislado).
+`DatabaseTransactions` envuelve cada test en una transacción que se revierte
+(rápido, pero no funciona con tests que usan múltiples conexiones o transacciones
+anidadas reales).
+
+### Factories con estados
+
+Las factories generan modelos con valores por defecto. Los `states` sobreescriben
+atributos para escenarios específicos sin duplicar la factory base.
+
+## Reglas obligatorias
+
+### SIEMPRE usar factories — nunca crear modelos manualmente en tests
+
+```php
+// MAL — fragil, se rompe si el schema cambia
+$usuario = Usuario::create([
+    'nombre' => 'Juan',
+    'email'  => 'juan@test.com',
+    'password' => bcrypt('secret'),
+    'rol' => 'admin',
+    // olvidaste 3 campos NOT NULL con defaults
+]);
+
+// BIEN — factory maneja defaults, solo sobreescribir lo relevante al test
+$usuario = Usuario::factory()->create(['rol' => 'admin']);
+```
+
+### NUNCA usar sleep() en tests — mockear el tiempo con Carbon::setTestNow()
+
+```php
+// MAL
+$token = Token::factory()->create();
+sleep(3601); // esperar que expire
+$this->assertFalse($token->esValido());
+
+// BIEN
+$token = Token::factory()->create();
+Carbon::setTestNow(now()->addHour()->addSecond());
+$this->assertFalse($token->esValido());
+Carbon::setTestNow(); // limpiar en tearDown
+```
+
+### Usar fakes ANTES de ejecutar la acción — nunca después
+
+```php
+// MAL — el job ya se despacho antes de poner el fake
+$this->post('/pedidos', $datos);
+Queue::fake(); // tarde, no capturo el dispatch
+
+// BIEN
+Queue::fake();
+$this->post('/pedidos', $datos);
+Queue::assertPushed(ProcesarPedido::class);
+```
+
+## Patrones recomendados
+
+### Pest — sintaxis moderna y expresiva
+
+```php
+// Pest con datasets (parametrizado)
+it('rechaza emails invalidos', function (string $email) {
+    $response = $this->postJson('/api/registro', ['email' => $email]);
+    $response->assertUnprocessable();
+})->with([
+    'sin arroba'   => ['nombre-sin-arroba'],
+    'sin dominio'  => ['nombre@'],
+    'solo espacio' => [' '],
+]);
+
+// Pest con beforeEach
+beforeEach(function () {
+    $this->usuario = Usuario::factory()->create();
+    $this->actingAs($this->usuario, 'sanctum');
+});
+
+test('puede ver sus pedidos', function () {
+    $pedidos = Pedido::factory(3)->create(['usuario_id' => $this->usuario->id]);
+    $this->getJson('/api/pedidos')
+        ->assertOk()
+        ->assertJsonCount(3, 'data');
+});
+```
+
+### Factory States para escenarios específicos
+
+```php
+class PedidoFactory extends Factory
+{
+    public function definition(): array
+    {
+        return [
+            'estatus'    => 'pendiente',
+            'total'      => $this->faker->randomFloat(2, 10, 1000),
+            'usuario_id' => Usuario::factory(),
+        ];
+    }
+
+    public function pagado(): static
+    {
+        return $this->state(fn (array $attrs) => [
+            'estatus'    => 'pagado',
+            'pagado_en'  => now(),
+        ]);
+    }
+
+    public function cancelado(): static
+    {
+        return $this->state(['estatus' => 'cancelado']);
+    }
+}
+
+// Uso en tests
+$pedidoPagado = Pedido::factory()->pagado()->create();
+$lote = Pedido::factory(5)->pagado()->create(['usuario_id' => $usuario->id]);
+```
+
+### Feature tests con assertJson y assertDatabaseHas
+
+```php
+test('crea un producto correctamente', function () {
+    $admin = Usuario::factory()->admin()->create();
+
+    $response = $this->actingAs($admin, 'sanctum')
+        ->postJson('/api/productos', [
+            'nombre'     => 'Laptop Pro',
+            'precio'     => 25000.00,
+            'categoria'  => 'electronica',
+        ]);
+
+    $response
+        ->assertCreated()
+        ->assertJsonStructure(['data' => ['id', 'nombre', 'precio']])
+        ->assertJsonPath('data.nombre', 'Laptop Pro');
+
+    $this->assertDatabaseHas('productos', [
+        'nombre' => 'Laptop Pro',
+        'precio' => 25000.00,
+    ]);
+});
+```
+
+### Mockery para dependencias externas
+
+```php
+test('maneja error del servicio de pago', function () {
+    $mockPago = Mockery::mock(ServicioPago::class);
+    $mockPago->shouldReceive('cobrar')
+        ->once()
+        ->andThrow(new PagoRechazadoException('Fondos insuficientes'));
+
+    $this->app->instance(ServicioPago::class, $mockPago);
+
+    $response = $this->postJson('/api/checkout', ['pedido_id' => 1]);
+    $response->assertUnprocessable()
+        ->assertJsonPath('errors.0.code', 'PAGO_RECHAZADO');
+});
+```
+
+### Event y Job Faking
+
+```php
+test('despacha job al crear pedido', function () {
+    Queue::fake();
+    Mail::fake();
+
+    $response = $this->actingAs($this->usuario, 'sanctum')
+        ->postJson('/api/pedidos', $this->datosPedido);
+
+    $response->assertCreated();
+    Queue::assertPushed(ProcesarPedido::class, fn ($job) =>
+        $job->pedido->id === $response->json('data.id')
+    );
+    Mail::assertQueued(ConfirmacionPedidoMail::class);
+});
+```
+
+## Anti-patrones conocidos
+
+### Tests que dependen del orden de ejecución
+
+Cada test debe ser completamente independiente. Usar `RefreshDatabase` o
+`DatabaseTransactions`. NUNCA depender de datos creados en otro test.
+
+### assertSee con texto que puede cambiar por i18n
+
+```php
+// MAL — fragil si cambia la traduccion
+$response->assertSee('El correo electronico ya esta en uso');
+
+// BIEN — verificar la estructura y el codigo de error
+$response->assertJsonPath('errors.0.code', 'EMAIL_DUPLICADO');
+```
+
+### Factory::recycle para evitar crear modelos innecesarios
+
+```php
+// Cuando multiples modelos deben compartir el mismo usuario
+$usuario = Usuario::factory()->create();
+$pedidos = Pedido::factory(3)->recycle($usuario)->create();
+// Los 3 pedidos apuntan al mismo usuario, no se crean 3 usuarios
+```
+
+## Checklist de verificación
+
+- [ ] Factories usadas en lugar de `Model::create()` manual en tests
+- [ ] `RefreshDatabase` o `DatabaseTransactions` en cada clase de test
+- [ ] Fakes configurados ANTES de ejecutar la acción (Queue::fake, Mail::fake)
+- [ ] Sin `sleep()` en tests — usar Carbon::setTestNow()
+- [ ] Tests de feature cubren happy path Y casos de error
+- [ ] Cobertura >= 80% en módulos de lógica de negocio
+
+## Referencias
+
+- [Laravel Testing](https://laravel.com/docs/testing)
+- [Pest PHP](https://pestphp.com/docs)
+- [Mockery](https://docs.mockery.io)
+
+## Gotchas / Errores comunes no obvios
+
+**`RefreshDatabase` recrea las migraciones en cada test de la suite completa, haciendo la suite lenta**: usar `RefreshDatabase` en todas las clases de test puede duplicar el tiempo de la suite en proyectos con muchas migraciones. Fix: usar `DatabaseTransactions` para tests que no necesitan un estado limpio absoluto — rollbackea cada test sin recrear el schema. Usar `RefreshDatabase` solo cuando el test modifica el schema o necesita seeds específicos.
+
+**Factory `->create()` en un test de unit (no de feature) hace queries reales a la BD**: las factories de Eloquent usan `Model::create()` que ejecuta SQL — en un test unitario sin base de datos, esto lanza `PDOException`. Fix: usar `->make()` en lugar de `->create()` para tests unitarios que solo necesitan el objeto en memoria, o configurar SQLite en memoria en el `phpunit.xml` para tests que requieren BD.
+
+**`Event::fake()` en un test de feature que usa `ShouldQueue` no verifica que el listener fue encolado**: `Event::fake()` intercepta el evento pero no verifica que el listener fue despachado a la queue. Causa: `Event::fake()` reemplaza el sistema de eventos completo. Fix: usar `Queue::fake()` junto con `Event::fake()` si se necesita verificar que el listener fue encolado, y usar `Queue::assertPushed(MiListener::class)`.
+
+**`assertDatabaseHas` verifica la presencia de una fila pero no que sea exactamente la correcta**: `assertDatabaseHas('facturas', ['monto' => 100])` pasa si hay al menos una factura con monto=100, incluso si el test debería haber creado una específica. Fix: agregar columnas adicionales al assert para identificar la fila específica (ej: `['id' => $factura->id, 'monto' => 100]`), o usar `assertDatabaseCount` para verificar que exactamente N filas coinciden.
+
+---
+*Skill creado con swl:crear-skill el 2026-03-31. Versión 1.0.0.*