theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/arquitectura-hexagonal/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: arquitectura-hexagonal
+description: Diseña, implementa y refactoriza sistemas de Puertos y Adaptadores con límites de dominio claros, inversión de dependencias y orquestación de casos de uso testeable en servicios TypeScript, Java, Kotlin y Go.
+---
+
+# Arquitectura Hexagonal
+
+La arquitectura hexagonal (Puertos y Adaptadores) mantiene la lógica de negocio independiente de frameworks, transporte y detalles de persistencia. El núcleo de la aplicación depende de puertos abstractos, y los adaptadores implementan esos puertos en los bordes.
+
+## Cuándo usarla
+
+- Al construir funcionalidades nuevas donde importan la mantenibilidad y la testeabilidad a largo plazo.
+- Al refactorizar código en capas o cargado de framework donde la lógica de dominio está mezclada con asuntos de E/S.
+- Al soportar múltiples interfaces para el mismo caso de uso (HTTP, CLI, workers de cola, tareas cron).
+- Al reemplazar infraestructura (base de datos, APIs externas, bus de mensajes) sin reescribir las reglas de negocio.
+
+Usa esta skill cuando la petición involucre límites, diseño centrado en el dominio, refactorización de servicios fuertemente acoplados o desacople de la lógica de aplicación respecto de librerías específicas.
+
+## Conceptos centrales
+
+- **Modelo de dominio**: reglas de negocio y entidades/objetos de valor. Sin imports de frameworks.
+- **Casos de uso (capa de aplicación)**: orquestan el comportamiento del dominio y los pasos del flujo de trabajo.
+- **Puertos de entrada (inbound)**: contratos que describen lo que la aplicación puede hacer (comandos/consultas/interfaces de casos de uso).
+- **Puertos de salida (outbound)**: contratos para las dependencias que la aplicación necesita (repositorios, gateways, publicadores de eventos, reloj, UUID, etc.).
+- **Adaptadores**: implementaciones de infraestructura y de entrega de los puertos (controladores HTTP, repositorios de BD, consumidores de cola, envoltorios de SDK).
+- **Raíz de composición (composition root)**: ubicación única de cableado donde los adaptadores concretos se vinculan a los casos de uso.
+
+Las interfaces de los puertos de salida suelen vivir en la capa de aplicación (o en el dominio solo cuando la abstracción es genuinamente de nivel de dominio), mientras que los adaptadores de infraestructura las implementan.
+
+La dirección de las dependencias siempre apunta hacia adentro:
+
+- Adaptadores -> aplicación/dominio
+- Aplicación -> interfaces de puertos (contratos de entrada/salida)
+- Dominio -> abstracciones exclusivas del dominio (sin dependencias de framework ni infraestructura)
+- Dominio -> nada externo
+
+## Cómo funciona
+
+### Paso 1: Modela el límite de un caso de uso
+
+Define un único caso de uso con un DTO de entrada y otro de salida claros. Mantén los detalles de transporte (el `req` de Express, el `context` de GraphQL, envoltorios de payload de jobs) fuera de este límite.
+
+### Paso 2: Define primero los puertos de salida
+
+Identifica cada efecto secundario como un puerto:
+
+- persistencia (`UserRepositoryPort`)
+- llamadas externas (`BillingGatewayPort`)
+- transversales (`LoggerPort`, `ClockPort`)
+
+Los puertos deben modelar capacidades, no tecnologías.
+
+### Paso 3: Implementa el caso de uso con orquestación pura
+
+La clase/función del caso de uso recibe los puertos por constructor/argumentos. Valida invariantes de nivel de aplicación, coordina las reglas de dominio y devuelve estructuras de datos planas.
+
+### Paso 4: Construye adaptadores en el borde
+
+- El adaptador de entrada convierte la entrada del protocolo a la entrada del caso de uso.
+- El adaptador de salida mapea los contratos de la aplicación a APIs concretas/ORM/query builders.
+- El mapeo permanece en los adaptadores, no dentro de los casos de uso.
+
+### Paso 5: Cablea todo en una raíz de composición
+
+Instancia los adaptadores y luego inyéctalos en los casos de uso. Mantén este cableado centralizado para evitar comportamientos ocultos de service locator.
+
+### Paso 6: Testea por límite
+
+- Tests unitarios de casos de uso con puertos falsos (fakes).
+- Tests de integración de adaptadores contra dependencias de infraestructura reales.
+- Tests E2E de flujos de cara al usuario a través de los adaptadores de entrada.
+
+## Diagrama de arquitectura
+
+```mermaid
+flowchart LR
+  Client["Cliente (HTTP/CLI/Worker)"] --> InboundAdapter["Adaptador de entrada"]
+  InboundAdapter -->|"llama"| UseCase["Caso de uso (capa de aplicación)"]
+  UseCase -->|"usa"| OutboundPort["Puerto de salida (interfaz)"]
+  OutboundAdapter["Adaptador de salida"] -->|"implementa"| OutboundPort
+  OutboundAdapter --> ExternalSystem["BD/API/Cola"]
+  UseCase --> DomainModel["Modelo de dominio"]
+```
+
+## Distribución de módulos sugerida
+
+Usa una organización orientada a funcionalidades (feature-first) con límites explícitos:
+
+```text
+src/
+  features/
+    orders/
+      domain/
+        Order.ts
+        OrderPolicy.ts
+      application/
+        ports/
+          inbound/
+            CreateOrder.ts
+          outbound/
+            OrderRepositoryPort.ts
+            PaymentGatewayPort.ts
+        use-cases/
+          CreateOrderUseCase.ts
+      adapters/
+        inbound/
+          http/
+            createOrderRoute.ts
+        outbound/
+          postgres/
+            PostgresOrderRepository.ts
+          stripe/
+            StripePaymentGateway.ts
+      composition/
+        ordersContainer.ts
+```
+
+## Ejemplo en TypeScript
+
+### Definición de puertos
+
+```typescript
+export interface OrderRepositoryPort {
+  save(order: Order): Promise<void>;
+  findById(orderId: string): Promise<Order | null>;
+}
+
+export interface PaymentGatewayPort {
+  authorize(input: { orderId: string; amountCents: number }): Promise<{ authorizationId: string }>;
+}
+```
+
+### Caso de uso
+
+```typescript
+type CreateOrderInput = {
+  orderId: string;
+  amountCents: number;
+};
+
+type CreateOrderOutput = {
+  orderId: string;
+  authorizationId: string;
+};
+
+export class CreateOrderUseCase {
+  constructor(
+    private readonly orderRepository: OrderRepositoryPort,
+    private readonly paymentGateway: PaymentGatewayPort
+  ) {}
+
+  async execute(input: CreateOrderInput): Promise<CreateOrderOutput> {
+    const order = Order.create({ id: input.orderId, amountCents: input.amountCents });
+
+    const auth = await this.paymentGateway.authorize({
+      orderId: order.id,
+      amountCents: order.amountCents,
+    });
+
+    // markAuthorized devuelve una nueva instancia de Order; no muta en el lugar.
+    const authorizedOrder = order.markAuthorized(auth.authorizationId);
+    await this.orderRepository.save(authorizedOrder);
+
+    return {
+      orderId: order.id,
+      authorizationId: auth.authorizationId,
+    };
+  }
+}
+```
+
+### Adaptador de salida
+
+```typescript
+export class PostgresOrderRepository implements OrderRepositoryPort {
+  constructor(private readonly db: SqlClient) {}
+
+  async save(order: Order): Promise<void> {
+    await this.db.query(
+      "insert into orders (id, amount_cents, status, authorization_id) values ($1, $2, $3, $4)",
+      [order.id, order.amountCents, order.status, order.authorizationId]
+    );
+  }
+
+  async findById(orderId: string): Promise<Order | null> {
+    const row = await this.db.oneOrNone("select * from orders where id = $1", [orderId]);
+    return row ? Order.rehydrate(row) : null;
+  }
+}
+```
+
+### Raíz de composición
+
+```typescript
+export const buildCreateOrderUseCase = (deps: { db: SqlClient; stripe: StripeClient }) => {
+  const orderRepository = new PostgresOrderRepository(deps.db);
+  const paymentGateway = new StripePaymentGateway(deps.stripe);
+
+  return new CreateOrderUseCase(orderRepository, paymentGateway);
+};
+```
+
+## Mapeo multilenguaje
+
+Usa las mismas reglas de límites en todos los ecosistemas; solo cambian la sintaxis y el estilo de cableado.
+
+- **TypeScript/JavaScript**
+  - Puertos: `application/ports/*` como interfaces/types.
+  - Casos de uso: clases/funciones con inyección por constructor/argumentos.
+  - Adaptadores: `adapters/inbound/*`, `adapters/outbound/*`.
+  - Composición: módulo factory/contenedor explícito (sin globales ocultos).
+- **Java**
+  - Paquetes: `domain`, `application.port.in`, `application.port.out`, `application.usecase`, `adapter.in`, `adapter.out`.
+  - Puertos: interfaces en `application.port.*`.
+  - Casos de uso: clases planas (el `@Service` de Spring es opcional, no obligatorio).
+  - Composición: configuración de Spring o clase de cableado manual; mantén el cableado fuera de las clases de dominio y de casos de uso.
+- **Kotlin**
+  - Los módulos/paquetes reflejan la división de Java (`domain`, `application.port`, `application.usecase`, `adapter`).
+  - Puertos: interfaces de Kotlin.
+  - Casos de uso: clases con inyección por constructor (Koin/Dagger/Spring/manual).
+  - Composición: definiciones de módulos o funciones de composición dedicadas; evita patrones de service locator.
+- **Go**
+  - Paquetes: `internal/<feature>/domain`, `application`, `ports`, `adapters/inbound`, `adapters/outbound`.
+  - Puertos: interfaces pequeñas propiedad del paquete de aplicación que las consume.
+  - Casos de uso: structs con campos de interfaz más constructores explícitos `New...`.
+  - Composición: cablea en `cmd/<app>/main.go` (o un paquete de cableado dedicado); mantén los constructores explícitos.
+
+## Antipatrones a evitar
+
+- Entidades de dominio que importan modelos de ORM, tipos de framework web o clientes de SDK.
+- Casos de uso que leen directamente de `req`, `res` o metadatos de la cola.
+- Devolver filas de la base de datos directamente desde los casos de uso sin mapeo de dominio/aplicación.
+- Permitir que los adaptadores se llamen entre sí directamente en lugar de fluir a través de los puertos del caso de uso.
+- Repartir el cableado de dependencias en muchos archivos con singletons globales ocultos.
+
+## Manual de migración
+
+1. Elige un corte vertical (un único endpoint/job) con dolor de cambio frecuente.
+2. Extrae un límite de caso de uso con tipos de entrada/salida explícitos.
+3. Introduce puertos de salida alrededor de las llamadas de infraestructura existentes.
+4. Mueve la lógica de orquestación de los controladores/servicios al caso de uso.
+5. Conserva los adaptadores antiguos, pero haz que deleguen en el nuevo caso de uso.
+6. Añade tests alrededor del nuevo límite (unitarios + integración de adaptadores).
+7. Repite corte por corte; evita reescrituras completas.
+
+### Refactorización de sistemas existentes
+
+- **Enfoque estrangulador (strangler)**: conserva los endpoints actuales y enruta un caso de uso a la vez a través de los nuevos puertos/adaptadores.
+- **Sin reescrituras big-bang**: migra por corte de funcionalidad y preserva el comportamiento con tests de caracterización.
+- **Fachada primero**: envuelve los servicios legados detrás de puertos de salida antes de reemplazar sus internos.
+- **Congelamiento de composición**: centraliza el cableado desde el inicio para que las dependencias nuevas no se filtren a las capas de dominio/casos de uso.
+- **Regla de selección de cortes**: prioriza primero los flujos de alta rotación (churn) y bajo radio de impacto.
+- **Ruta de reversión**: mantén un toggle o conmutador de ruta reversible por corte migrado hasta verificar el comportamiento en producción.
+
+## Guía de testing (mismos límites hexagonales)
+
+- **Tests de dominio**: testea entidades/objetos de valor como reglas de negocio puras (sin mocks, sin setup de framework).
+- **Tests unitarios de casos de uso**: testea la orquestación con fakes/stubs para los puertos de salida; verifica resultados de negocio e interacciones con los puertos.
+- **Tests de contrato de adaptadores de salida**: define suites de contrato compartidas a nivel de puerto y ejecútalas contra cada implementación de adaptador.
+- **Tests de adaptadores de entrada**: verifica el mapeo de protocolo (payload HTTP/CLI/cola a entrada del caso de uso, y mapeo de salida/errores de vuelta al protocolo).
+- **Tests de integración de adaptadores**: ejecuta contra infraestructura real (BD/API/cola) para serialización, comportamiento de esquema/consultas, reintentos y timeouts.
+- **Tests end-to-end**: cubre los recorridos críticos del usuario a través de adaptador de entrada -> caso de uso -> adaptador de salida.
+- **Seguridad al refactorizar**: añade tests de caracterización antes de la extracción; consérvalos hasta que el comportamiento del nuevo límite sea estable y equivalente.
+
+## Lista de verificación de buenas prácticas
+
+- Las capas de dominio y casos de uso solo importan tipos internos y puertos.
+- Cada dependencia externa está representada por un puerto de salida.
+- La validación ocurre en los límites (adaptador de entrada + invariantes del caso de uso).
+- Usa transformaciones inmutables (devuelve valores/entidades nuevos en lugar de mutar estado compartido).
+- Los errores se traducen entre límites (errores de infraestructura -> errores de aplicación/dominio).
+- La raíz de composición es explícita y fácil de auditar.
+- Los casos de uso son testeables con fakes en memoria simples para los puertos.
+- La refactorización comienza desde un corte vertical con tests que preservan el comportamiento.
+- Las particularidades de lenguaje/framework se quedan en los adaptadores, nunca en las reglas de dominio.

package/vendor/theus-arsenal/skills/arquitectura-limpia-android/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: arquitectura-limpia-android
+description: Patrones de Clean Architecture para proyectos Android y Kotlin Multiplatform — estructura
+  de módulos, reglas de dependencias, UseCases, Repositories y patrones de capa de datos con Room,
+  SQLDelight y Ktor.
+---
+
+# Arquitectura limpia en Android
+
+Patrones de Clean Architecture para proyectos Android y KMP. Cubre fronteras de módulos, inversión de dependencias, patrones UseCase/Repository y diseño de la capa de datos con Room, SQLDelight y Ktor.
+
+## Cuándo activarla
+
+- Estructurar los módulos de un proyecto Android o KMP
+- Implementar UseCases, Repositories o DataSources
+- Diseñar el flujo de datos entre capas (dominio, datos, presentación)
+- Configurar inyección de dependencias con Koin o Hilt
+- Trabajar con Room, SQLDelight o Ktor en una arquitectura por capas
+
+## Estructura de módulos
+
+### Distribución recomendada
+
+```
+proyecto/
+├── app/                  # Punto de entrada Android, cableado de DI, clase Application
+├── core/                 # Utilidades compartidas, clases base, tipos de error
+├── domain/               # UseCases, modelos de dominio, interfaces de repositorio (Kotlin puro)
+├── data/                 # Implementaciones de repositorio, DataSources, BD, red
+├── presentation/         # Pantallas, ViewModels, modelos de UI, navegación
+├── design-system/        # Componentes Compose reutilizables, tema, tipografía
+└── feature/              # Módulos de feature (opcional, para proyectos grandes)
+    ├── auth/
+    ├── settings/
+    └── profile/
+```
+
+### Reglas de dependencias
+
+```
+app → presentation, domain, data, core
+presentation → domain, design-system, core
+data → domain, core
+domain → core (o sin dependencias)
+core → (nada)
+```
+
+**Crítico**: `domain` NUNCA debe depender de `data`, `presentation` ni de ningún framework. Contiene solo Kotlin puro.
+
+## Capa de dominio
+
+### Patrón UseCase
+
+Cada UseCase representa una operación de negocio. Usa `operator fun invoke` para llamadas limpias:
+
+```kotlin
+class GetItemsByCategoryUseCase(
+    private val repository: ItemRepository
+) {
+    suspend operator fun invoke(category: String): Result<List<Item>> {
+        return repository.getItemsByCategory(category)
+    }
+}
+
+// UseCase basado en Flow para flujos reactivos
+class ObserveUserProgressUseCase(
+    private val repository: UserRepository
+) {
+    operator fun invoke(userId: String): Flow<UserProgress> {
+        return repository.observeProgress(userId)
+    }
+}
+```
+
+### Modelos de dominio
+
+Los modelos de dominio son data classes de Kotlin puro — sin anotaciones de framework:
+
+```kotlin
+data class Item(
+    val id: String,
+    val title: String,
+    val description: String,
+    val tags: List<String>,
+    val status: Status,
+    val category: String
+)
+
+enum class Status { DRAFT, ACTIVE, ARCHIVED }
+```
+
+### Interfaces de repositorio
+
+Se definen en dominio y se implementan en datos:
+
+```kotlin
+interface ItemRepository {
+    suspend fun getItemsByCategory(category: String): Result<List<Item>>
+    suspend fun saveItem(item: Item): Result<Unit>
+    fun observeItems(): Flow<List<Item>>
+}
+```
+
+## Capa de datos
+
+### Implementación del repositorio
+
+Coordina entre las fuentes de datos local y remota:
+
+```kotlin
+class ItemRepositoryImpl(
+    private val localDataSource: ItemLocalDataSource,
+    private val remoteDataSource: ItemRemoteDataSource
+) : ItemRepository {
+
+    override suspend fun getItemsByCategory(category: String): Result<List<Item>> {
+        return runCatching {
+            val remote = remoteDataSource.fetchItems(category)
+            localDataSource.insertItems(remote.map { it.toEntity() })
+            localDataSource.getItemsByCategory(category).map { it.toDomain() }
+        }
+    }
+
+    override suspend fun saveItem(item: Item): Result<Unit> {
+        return runCatching {
+            localDataSource.insertItems(listOf(item.toEntity()))
+        }
+    }
+
+    override fun observeItems(): Flow<List<Item>> {
+        return localDataSource.observeAll().map { entities ->
+            entities.map { it.toDomain() }
+        }
+    }
+}
+```
+
+### Patrón de mappers
+
+Mantén los mappers como funciones de extensión cerca de los modelos de datos:
+
+```kotlin
+// En la capa de datos
+fun ItemEntity.toDomain() = Item(
+    id = id,
+    title = title,
+    description = description,
+    tags = tags.split("|"),
+    status = Status.valueOf(status),
+    category = category
+)
+
+fun ItemDto.toEntity() = ItemEntity(
+    id = id,
+    title = title,
+    description = description,
+    tags = tags.joinToString("|"),
+    status = status,
+    category = category
+)
+```
+
+### Base de datos Room (Android)
+
+```kotlin
+@Entity(tableName = "items")
+data class ItemEntity(
+    @PrimaryKey val id: String,
+    val title: String,
+    val description: String,
+    val tags: String,
+    val status: String,
+    val category: String
+)
+
+@Dao
+interface ItemDao {
+    @Query("SELECT * FROM items WHERE category = :category")
+    suspend fun getByCategory(category: String): List<ItemEntity>
+
+    @Upsert
+    suspend fun upsert(items: List<ItemEntity>)
+
+    @Query("SELECT * FROM items")
+    fun observeAll(): Flow<List<ItemEntity>>
+}
+```
+
+### SQLDelight (KMP)
+
+```sql
+-- Item.sq
+CREATE TABLE ItemEntity (
+    id TEXT NOT NULL PRIMARY KEY,
+    title TEXT NOT NULL,
+    description TEXT NOT NULL,
+    tags TEXT NOT NULL,
+    status TEXT NOT NULL,
+    category TEXT NOT NULL
+);
+
+getByCategory:
+SELECT * FROM ItemEntity WHERE category = ?;
+
+upsert:
+INSERT OR REPLACE INTO ItemEntity (id, title, description, tags, status, category)
+VALUES (?, ?, ?, ?, ?, ?);
+
+observeAll:
+SELECT * FROM ItemEntity;
+```
+
+### Cliente de red Ktor (KMP)
+
+```kotlin
+class ItemRemoteDataSource(private val client: HttpClient) {
+
+    suspend fun fetchItems(category: String): List<ItemDto> {
+        return client.get("api/items") {
+            parameter("category", category)
+        }.body()
+    }
+}
+
+// Configuración del HttpClient con negociación de contenido
+val httpClient = HttpClient {
+    install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }
+    install(Logging) { level = LogLevel.HEADERS }
+    defaultRequest { url("https://api.example.com/") }
+}
+```
+
+## Inyección de dependencias
+
+### Koin (amigable con KMP)
+
+```kotlin
+// Módulo de dominio
+val domainModule = module {
+    factory { GetItemsByCategoryUseCase(get()) }
+    factory { ObserveUserProgressUseCase(get()) }
+}
+
+// Módulo de datos
+val dataModule = module {
+    single<ItemRepository> { ItemRepositoryImpl(get(), get()) }
+    single { ItemLocalDataSource(get()) }
+    single { ItemRemoteDataSource(get()) }
+}
+
+// Módulo de presentación
+val presentationModule = module {
+    viewModelOf(::ItemListViewModel)
+    viewModelOf(::DashboardViewModel)
+}
+```
+
+### Hilt (solo Android)
+
+```kotlin
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class RepositoryModule {
+    @Binds
+    abstract fun bindItemRepository(impl: ItemRepositoryImpl): ItemRepository
+}
+
+@HiltViewModel
+class ItemListViewModel @Inject constructor(
+    private val getItems: GetItemsByCategoryUseCase
+) : ViewModel()
+```
+
+## Manejo de errores
+
+### Patrón Result/Try
+
+Usa `Result<T>` o un sealed type propio para propagar errores:
+
+```kotlin
+sealed interface Try<out T> {
+    data class Success<T>(val value: T) : Try<T>
+    data class Failure(val error: AppError) : Try<Nothing>
+}
+
+sealed interface AppError {
+    data class Network(val message: String) : AppError
+    data class Database(val message: String) : AppError
+    data object Unauthorized : AppError
+}
+
+// En el ViewModel — mapear a estado de UI
+viewModelScope.launch {
+    when (val result = getItems(category)) {
+        is Try.Success -> _state.update { it.copy(items = result.value, isLoading = false) }
+        is Try.Failure -> _state.update { it.copy(error = result.error.toMessage(), isLoading = false) }
+    }
+}
+```
+
+## Convention plugins (Gradle)
+
+Para proyectos KMP, usa convention plugins para reducir la duplicación en los archivos de build:
+
+```kotlin
+// build-logic/src/main/kotlin/kmp-library.gradle.kts
+plugins {
+    id("org.jetbrains.kotlin.multiplatform")
+}
+
+kotlin {
+    androidTarget()
+    iosX64(); iosArm64(); iosSimulatorArm64()
+    sourceSets {
+        commonMain.dependencies { /* dependencias compartidas */ }
+        commonTest.dependencies { implementation(kotlin("test")) }
+    }
+}
+```
+
+Aplícalo en los módulos:
+
+```kotlin
+// domain/build.gradle.kts
+plugins { id("kmp-library") }
+```
+
+## Antipatrones a evitar
+
+- Importar clases del framework Android en `domain` — mantenlo Kotlin puro
+- Exponer entidades de BD o DTOs a la capa de UI — mapea siempre a modelos de dominio
+- Poner lógica de negocio en los ViewModels — extráela a UseCases
+- Usar `GlobalScope` o corrutinas sin estructura — usa `viewModelScope` o concurrencia estructurada
+- Implementaciones de repositorio infladas — divídelas en DataSources enfocados
+- Dependencias circulares entre módulos — si A depende de B, B no debe depender de A
+
+## Skills relacionadas
+
+- `patrones-compose-multiplatform` — patrones de UI.
+- `corrutinas-flows-kotlin` — patrones asíncronos.