theus-cli 0.2.82 → 0.2.84

package/vendor/theus-arsenal/skills/testing-perl/SKILL.md

@@ -1,479 +0,0 @@
----
-name: testing-perl
-description: Patrones de testing en Perl con Test2::V0, Test::More, el runner prove, mocking, cobertura con Devel::Cover y metodología TDD.
----
-
-# Patrones de testing en Perl
-
-Estrategias de testing integrales para aplicaciones Perl usando Test2::V0, Test::More, prove y metodología TDD.
-
-## Cuándo usarla
-
-- Al escribir código Perl nuevo (sigue TDD: rojo, verde, refactor).
-- Al diseñar suites de tests para módulos o aplicaciones Perl.
-- Al revisar la cobertura de tests de código Perl.
-- Al montar infraestructura de testing para Perl.
-- Al migrar tests de Test::More a Test2::V0.
-- Al depurar tests Perl que fallan.
-
-## Flujo TDD
-
-Sigue siempre el ciclo ROJO-VERDE-REFACTOR.
-
-```perl
-# Paso 1: ROJO — escribir un test que falle
-# t/unit/calculator.t
-use v5.36;
-use Test2::V0;
-
-use lib 'lib';
-use Calculator;
-
-subtest 'suma' => sub {
-    my $calc = Calculator->new;
-    is($calc->add(2, 3), 5, 'suma dos números');
-    is($calc->add(-1, 1), 0, 'maneja negativos');
-};
-
-done_testing;
-
-# Paso 2: VERDE — escribir la implementación mínima
-# lib/Calculator.pm
-package Calculator;
-use v5.36;
-use Moo;
-
-sub add($self, $a, $b) {
-    return $a + $b;
-}
-
-1;
-
-# Paso 3: REFACTOR — mejorar mientras los tests siguen en verde
-# Ejecutar: prove -lv t/unit/calculator.t
-```
-
-## Fundamentos de Test::More
-
-El módulo estándar de testing de Perl — muy usado, viene en el core.
-
-### Aserciones básicas
-
-```perl
-use v5.36;
-use Test::More;
-
-# Plan por adelantado o done_testing
-# plan tests => 5;  # Plan fijo (opcional)
-
-# Igualdad
-is($result, 42, 'devuelve el valor correcto');
-isnt($result, 0, 'distinto de cero');
-
-# Booleanos
-ok($user->is_active, 'el usuario está activo');
-ok(!$user->is_banned, 'el usuario no está bloqueado');
-
-# Comparación profunda
-is_deeply(
-    $got,
-    { name => 'Alice', roles => ['admin'] },
-    'devuelve la estructura esperada'
-);
-
-# Coincidencia de patrones
-like($error, qr/not found/i, 'el error menciona "not found"');
-unlike($output, qr/password/, 'la salida oculta la contraseña');
-
-# Comprobación de tipo
-isa_ok($obj, 'MyApp::User');
-can_ok($obj, 'save', 'delete');
-
-done_testing;
-```
-
-### SKIP y TODO
-
-```perl
-use v5.36;
-use Test::More;
-
-# Omitir tests condicionalmente
-SKIP: {
-    skip 'Sin base de datos configurada', 2 unless $ENV{TEST_DB};
-
-    my $db = connect_db();
-    ok($db->ping, 'la base de datos responde');
-    is($db->version, '15', 'versión correcta de PostgreSQL');
-}
-
-# Marcar fallos esperados
-TODO: {
-    local $TODO = 'La caché aún no está implementada';
-    is($cache->get('key'), 'value', 'la caché devuelve el valor');
-}
-
-done_testing;
-```
-
-## Test2::V0, el framework moderno
-
-Test2::V0 es el reemplazo moderno de Test::More — aserciones más ricas, mejores diagnósticos y extensible.
-
-### ¿Por qué Test2?
-
-- Comparación profunda superior con builders de hash/array.
-- Mejor salida de diagnóstico ante fallos.
-- Subtests con un scoping más limpio.
-- Extensible vía plugins Test2::Tools::*.
-- Retrocompatible con tests de Test::More.
-
-### Comparación profunda con builders
-
-```perl
-use v5.36;
-use Test2::V0;
-
-# Builder de hash — comprobar estructura parcial
-is(
-    $user->to_hash,
-    hash {
-        field name  => 'Alice';
-        field email => match(qr/\@example\.com$/);
-        field age   => validator(sub { $_ >= 18 });
-        # Ignorar el resto de campos
-        etc();
-    },
-    'el usuario tiene los campos esperados'
-);
-
-# Builder de array
-is(
-    $result,
-    array {
-        item 'first';
-        item match(qr/^second/);
-        item DNE();  # Does Not Exist — verificar que no hay elementos extra
-    },
-    'el resultado coincide con la lista esperada'
-);
-
-# Bag — comparación independiente del orden
-is(
-    $tags,
-    bag {
-        item 'perl';
-        item 'testing';
-        item 'tdd';
-    },
-    'tiene todas las etiquetas requeridas sin importar el orden'
-);
-```
-
-### Subtests
-
-```perl
-use v5.36;
-use Test2::V0;
-
-subtest 'Creación de usuario' => sub {
-    my $user = User->new(name => 'Alice', email => 'alice@example.com');
-    ok($user, 'objeto usuario creado');
-    is($user->name, 'Alice', 'el nombre está asignado');
-    is($user->email, 'alice@example.com', 'el correo está asignado');
-};
-
-subtest 'Validación de usuario' => sub {
-    my $warnings = warns {
-        User->new(name => '', email => 'bad');
-    };
-    ok($warnings, 'advierte ante datos inválidos');
-};
-
-done_testing;
-```
-
-### Testing de excepciones con Test2
-
-```perl
-use v5.36;
-use Test2::V0;
-
-# Comprobar que el código muere
-like(
-    dies { divide(10, 0) },
-    qr/División por cero/,
-    'muere al dividir por cero'
-);
-
-# Comprobar que el código sobrevive
-ok(lives { divide(10, 2) }, 'la división tiene éxito') or note($@);
-
-# Patrón combinado
-subtest 'manejo de errores' => sub {
-    ok(lives { parse_config('valid.json') }, 'la config válida se parsea');
-    like(
-        dies { parse_config('missing.json') },
-        qr/Cannot open/,
-        'el archivo ausente muere con mensaje'
-    );
-};
-
-done_testing;
-```
-
-## Organización de tests y prove
-
-### Estructura de directorios
-
-```text
-t/
-├── 00-load.t              # Verificar que los módulos compilan
-├── 01-basic.t             # Funcionalidad central
-├── unit/
-│   ├── config.t           # Tests unitarios por módulo
-│   ├── user.t
-│   └── util.t
-├── integration/
-│   ├── database.t
-│   └── api.t
-├── lib/
-│   └── TestHelper.pm      # Utilidades de test compartidas
-└── fixtures/
-    ├── config.json        # Archivos de datos de prueba
-    └── users.csv
-```
-
-### Comandos de prove
-
-```bash
-# Ejecutar todos los tests
-prove -l t/
-
-# Salida detallada
-prove -lv t/
-
-# Ejecutar un test concreto
-prove -lv t/unit/user.t
-
-# Búsqueda recursiva
-prove -lr t/
-
-# Ejecución en paralelo (8 jobs)
-prove -lr -j8 t/
-
-# Ejecutar solo los tests que fallaron en la última corrida
-prove -l --state=failed t/
-
-# Salida con color y cronómetro
-prove -l --color --timer t/
-
-# Salida TAP para CI
-prove -l --formatter TAP::Formatter::JUnit t/ > results.xml
-```
-
-### Configuración .proverc
-
-```text
--l
---color
---timer
--r
--j4
---state=save
-```
-
-## Fixtures y setup/teardown
-
-### Aislamiento por subtest
-
-```perl
-use v5.36;
-use Test2::V0;
-use File::Temp qw(tempdir);
-use Path::Tiny;
-
-subtest 'procesamiento de archivos' => sub {
-    # Setup
-    my $dir = tempdir(CLEANUP => 1);
-    my $file = path($dir, 'input.txt');
-    $file->spew_utf8("linea1\nlinea2\nlinea3\n");
-
-    # Test
-    my $result = process_file("$file");
-    is($result->{line_count}, 3, 'cuenta las líneas');
-
-    # El teardown ocurre automáticamente (CLEANUP => 1)
-};
-```
-
-### Helpers de test compartidos
-
-Coloca los helpers reutilizables en `t/lib/TestHelper.pm` y cárgalos con `use lib 't/lib'`. Exporta funciones factoría como `create_test_db()`, `create_temp_dir()` y `fixture_path()` vía `Exporter`.
-
-## Mocking
-
-### Test::MockModule
-
-```perl
-use v5.36;
-use Test2::V0;
-use Test::MockModule;
-
-subtest 'mock de una API externa' => sub {
-    my $mock = Test::MockModule->new('MyApp::API');
-
-    # Bien: el mock devuelve datos controlados
-    $mock->mock(fetch_user => sub ($self, $id) {
-        return { id => $id, name => 'Usuario Mock', email => 'mock@test.com' };
-    });
-
-    my $api = MyApp::API->new;
-    my $user = $api->fetch_user(42);
-    is($user->{name}, 'Usuario Mock', 'devuelve el usuario mockeado');
-
-    # Verificar el número de llamadas
-    my $call_count = 0;
-    $mock->mock(fetch_user => sub { $call_count++; return {} });
-    $api->fetch_user(1);
-    $api->fetch_user(2);
-    is($call_count, 2, 'fetch_user se llamó dos veces');
-
-    # El mock se restaura automáticamente cuando $mock sale de scope
-};
-
-# Mal: monkey-patching sin restauración
-# *MyApp::API::fetch_user = sub { ... };  # NUNCA — se filtra entre tests
-```
-
-Para objetos mock ligeros, usa `Test::MockObject` para crear dobles de prueba inyectables con `->mock()` y verifica las llamadas con `->called_ok()`.
-
-## Cobertura con Devel::Cover
-
-### Ejecutar la cobertura
-
-```bash
-# Informe básico de cobertura
-cover -test
-
-# O paso a paso
-perl -MDevel::Cover -Ilib t/unit/user.t
-cover
-
-# Informe HTML
-cover -report html
-open cover_db/coverage.html
-
-# Umbrales específicos
-cover -test -report text | grep 'Total'
-
-# Amigable con CI: fallar por debajo del umbral
-cover -test && cover -report text -select '^lib/' \
-  | perl -ne 'if (/Total.*?(\d+\.\d+)/) { exit 1 if $1 < 80 }'
-```
-
-### Testing de integración
-
-Usa SQLite en memoria para los tests de base de datos y mockea HTTP::Tiny para los tests de API.
-
-```perl
-use v5.36;
-use Test2::V0;
-use DBI;
-
-subtest 'integración con base de datos' => sub {
-    my $dbh = DBI->connect('dbi:SQLite:dbname=:memory:', '', '', {
-        RaiseError => 1,
-    });
-    $dbh->do('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
-
-    $dbh->prepare('INSERT INTO users (name) VALUES (?)')->execute('Alice');
-    my $row = $dbh->selectrow_hashref('SELECT * FROM users WHERE name = ?', undef, 'Alice');
-    is($row->{name}, 'Alice', 'usuario insertado y recuperado');
-};
-
-done_testing;
-```
-
-## Buenas prácticas
-
-### SÍ
-
-- **Sigue TDD**: escribe los tests antes de la implementación (rojo-verde-refactor).
-- **Usa Test2::V0**: aserciones modernas, mejores diagnósticos.
-- **Usa subtests**: agrupa aserciones relacionadas, aísla el estado.
-- **Mockea las dependencias externas**: red, base de datos, sistema de archivos.
-- **Usa `prove -l`**: incluye siempre lib/ en `@INC`.
-- **Nombra los tests con claridad**: `'el login con contraseña inválida falla'`.
-- **Prueba los casos límite**: strings vacíos, undef, cero, valores frontera.
-- **Apunta a 80 %+ de cobertura**: céntrate en las rutas de lógica de negocio.
-- **Mantén los tests rápidos**: mockea la E/S, usa bases de datos en memoria.
-
-### NO
-
-- **No pruebes la implementación**: prueba el comportamiento y la salida, no las tripas.
-- **No compartas estado entre subtests**: cada subtest debe ser independiente.
-- **No omitas `done_testing`**: garantiza que todos los tests planificados corrieron.
-- **No sobre-mockees**: mockea solo las fronteras, no el código bajo prueba.
-- **No uses `Test::More` en proyectos nuevos**: prefiere Test2::V0.
-- **No ignores los fallos de tests**: todos deben pasar antes del merge.
-- **No pruebes los módulos de CPAN**: confía en que las librerías funcionan.
-- **No escribas tests frágiles**: evita coincidencias de string demasiado específicas.
-
-## Referencia rápida
-
-| Tarea | Comando / patrón |
-|---|---|
-| Ejecutar todos los tests | `prove -lr t/` |
-| Ejecutar un test en detalle | `prove -lv t/unit/user.t` |
-| Corrida en paralelo | `prove -lr -j8 t/` |
-| Informe de cobertura | `cover -test && cover -report html` |
-| Probar igualdad | `is($got, $expected, 'etiqueta')` |
-| Comparación profunda | `is($got, hash { field k => 'v'; etc() }, 'etiqueta')` |
-| Probar una excepción | `like(dies { ... }, qr/msg/, 'etiqueta')` |
-| Probar que no hay excepción | `ok(lives { ... }, 'etiqueta')` |
-| Mockear un método | `Test::MockModule->new('Pkg')->mock(m => sub { ... })` |
-| Omitir tests | `SKIP: { skip 'motivo', $count unless $cond; ... }` |
-| Tests TODO | `TODO: { local $TODO = 'motivo'; ... }` |
-
-## Errores comunes
-
-### Olvidar `done_testing`
-
-```perl
-# Mal: el archivo de test corre pero no verifica que todo se ejecutó
-use Test2::V0;
-is(1, 1, 'funciona');
-# Falta done_testing — bugs silenciosos si se salta código de test
-
-# Bien: termina siempre con done_testing
-use Test2::V0;
-is(1, 1, 'funciona');
-done_testing;
-```
-
-### Olvidar el flag `-l`
-
-```bash
-# Mal: no se encuentran los módulos de lib/
-prove t/unit/user.t
-# Can't locate MyApp/User.pm in @INC
-
-# Bien: incluir lib/ en @INC
-prove -l t/unit/user.t
-```
-
-### Sobre-mockear
-
-Mockea la *dependencia*, no el código bajo prueba. Si tu test solo verifica que un mock devuelve lo que le dijiste, no prueba nada.
-
-### Contaminación entre tests
-
-Usa variables `my` dentro de los subtests — nunca `our` — para evitar que el estado se filtre entre tests.
-
-**Recuerda**: los tests son tu red de seguridad. Mantenlos rápidos, enfocados e independientes. Usa Test2::V0 para proyectos nuevos, prove para ejecutarlos y Devel::Cover para rendir cuentas.
-
-## Skills relacionadas
-
-- `patrones-perl`
-- `seguridad-perl`

package/vendor/theus-arsenal/skills/testing-protocolos-di-swift/SKILL.md

@@ -1,196 +0,0 @@
----
-name: testing-protocolos-di-swift
-description: Inyección de dependencias basada en protocolos para código Swift testeable — mocks de
-  sistema de archivos, red y APIs externas mediante protocolos pequeños y enfocados, con Swift Testing.
----
-
-# Inyección de dependencias por protocolos para testing en Swift
-
-Patrones para hacer testeable el código Swift abstrayendo las dependencias externas (sistema de archivos, red, iCloud) detrás de protocolos pequeños y enfocados. Permite tests deterministas sin I/O real.
-
-## Cuándo usarla
-
-- Al escribir código Swift que accede al sistema de archivos, la red o APIs externas.
-- Cuando necesitas probar rutas de manejo de errores sin provocar fallos reales.
-- Al construir módulos que funcionan en varios entornos (app, tests, previews de SwiftUI).
-- Al diseñar arquitectura testeable con concurrencia de Swift (actores, Sendable).
-
-## Patrón central
-
-### 1. Define protocolos pequeños y enfocados
-
-Cada protocolo cubre exactamente una preocupación externa.
-
-```swift
-// Acceso al sistema de archivos
-public protocol FileSystemProviding: Sendable {
-    func containerURL(for purpose: Purpose) -> URL?
-}
-
-// Operaciones de lectura/escritura de archivos
-public protocol FileAccessorProviding: Sendable {
-    func read(from url: URL) throws -> Data
-    func write(_ data: Data, to url: URL) throws
-    func fileExists(at url: URL) -> Bool
-}
-
-// Almacenamiento de bookmarks (p. ej., para apps con sandbox)
-public protocol BookmarkStorageProviding: Sendable {
-    func saveBookmark(_ data: Data, for key: String) throws
-    func loadBookmark(for key: String) throws -> Data?
-}
-```
-
-### 2. Crea las implementaciones por defecto (producción)
-
-```swift
-public struct DefaultFileSystemProvider: FileSystemProviding {
-    public init() {}
-
-    public func containerURL(for purpose: Purpose) -> URL? {
-        FileManager.default.url(forUbiquityContainerIdentifier: nil)
-    }
-}
-
-public struct DefaultFileAccessor: FileAccessorProviding {
-    public init() {}
-
-    public func read(from url: URL) throws -> Data {
-        try Data(contentsOf: url)
-    }
-
-    public func write(_ data: Data, to url: URL) throws {
-        try data.write(to: url, options: .atomic)
-    }
-
-    public func fileExists(at url: URL) -> Bool {
-        FileManager.default.fileExists(atPath: url.path)
-    }
-}
-```
-
-### 3. Crea implementaciones mock para los tests
-
-```swift
-public final class MockFileAccessor: FileAccessorProviding, @unchecked Sendable {
-    public var files: [URL: Data] = [:]
-    public var readError: Error?
-    public var writeError: Error?
-
-    public init() {}
-
-    public func read(from url: URL) throws -> Data {
-        if let error = readError { throw error }
-        guard let data = files[url] else {
-            throw CocoaError(.fileReadNoSuchFile)
-        }
-        return data
-    }
-
-    public func write(_ data: Data, to url: URL) throws {
-        if let error = writeError { throw error }
-        files[url] = data
-    }
-
-    public func fileExists(at url: URL) -> Bool {
-        files[url] != nil
-    }
-}
-```
-
-### 4. Inyecta las dependencias con parámetros por defecto
-
-El código de producción usa los defaults; los tests inyectan mocks.
-
-```swift
-public actor SyncManager {
-    private let fileSystem: FileSystemProviding
-    private let fileAccessor: FileAccessorProviding
-
-    public init(
-        fileSystem: FileSystemProviding = DefaultFileSystemProvider(),
-        fileAccessor: FileAccessorProviding = DefaultFileAccessor()
-    ) {
-        self.fileSystem = fileSystem
-        self.fileAccessor = fileAccessor
-    }
-
-    public func sync() async throws {
-        guard let containerURL = fileSystem.containerURL(for: .sync) else {
-            throw SyncError.containerNotAvailable
-        }
-        let data = try fileAccessor.read(
-            from: containerURL.appendingPathComponent("data.json")
-        )
-        // Procesar los datos...
-    }
-}
-```
-
-### 5. Escribe los tests con Swift Testing
-
-```swift
-import Testing
-
-@Test("El sync manager maneja un contenedor ausente")
-func testMissingContainer() async {
-    let mockFileSystem = MockFileSystemProvider(containerURL: nil)
-    let manager = SyncManager(fileSystem: mockFileSystem)
-
-    await #expect(throws: SyncError.containerNotAvailable) {
-        try await manager.sync()
-    }
-}
-
-@Test("El sync manager lee los datos correctamente")
-func testReadData() async throws {
-    let mockFileAccessor = MockFileAccessor()
-    mockFileAccessor.files[testURL] = testData
-
-    let manager = SyncManager(fileAccessor: mockFileAccessor)
-    let result = try await manager.loadData()
-
-    #expect(result == expectedData)
-}
-
-@Test("El sync manager maneja errores de lectura con gracia")
-func testReadError() async {
-    let mockFileAccessor = MockFileAccessor()
-    mockFileAccessor.readError = CocoaError(.fileReadCorruptFile)
-
-    let manager = SyncManager(fileAccessor: mockFileAccessor)
-
-    await #expect(throws: SyncError.self) {
-        try await manager.sync()
-    }
-}
-```
-
-## Buenas prácticas
-
-- **Responsabilidad única**: cada protocolo debe cubrir una sola preocupación — no crees "protocolos dios" con muchos métodos.
-- **Conformance a Sendable**: obligatoria cuando los protocolos cruzan fronteras de actor.
-- **Parámetros por defecto**: deja que producción use las implementaciones reales por defecto; solo los tests especifican mocks.
-- **Simulación de errores**: diseña los mocks con propiedades de error configurables para probar las rutas de fallo.
-- **Solo mockea las fronteras**: mockea dependencias externas (sistema de archivos, red, APIs), no tipos internos.
-
-## Antipatrones a evitar
-
-- Crear un único protocolo grande que cubra todo el acceso externo.
-- Mockear tipos internos que no tienen dependencias externas.
-- Usar condicionales `#if DEBUG` en lugar de inyección de dependencias real.
-- Olvidar la conformance a `Sendable` cuando se usa con actores.
-- Sobreingeniería: si un tipo no tiene dependencias externas, no necesita un protocolo.
-
-## Cuándo aplicarla
-
-- Cualquier código Swift que toque el sistema de archivos, la red o APIs externas.
-- Tests de rutas de error difíciles de provocar en entornos reales.
-- Módulos que deben funcionar en contextos de app, tests y previews de SwiftUI.
-- Apps con concurrencia de Swift (actores, concurrencia estructurada) que necesitan arquitectura testeable.
-
-## Skills relacionadas
-
-- `patrones-swiftui`
-- `concurrencia-swift-6-2`
-- `persistencia-actores-swift`