theus-cli 0.2.82 → 0.2.84

package/vendor/theus-arsenal/skills/patrones-kotlin/SKILL.md

@@ -1,717 +0,0 @@
----
-name: patrones-kotlin
-description: Patrones idiomáticos de Kotlin para aplicaciones robustas y mantenibles — null safety, inmutabilidad, sealed classes, corrutinas y Flow, funciones de extensión, builders DSL y Gradle Kotlin DSL.
----
-
-# Patrones de desarrollo en Kotlin
-
-Patrones idiomáticos de Kotlin y buenas prácticas para construir aplicaciones robustas, eficientes y mantenibles.
-
-## Cuándo usarla
-
-- Al escribir código Kotlin nuevo
-- Al revisar código Kotlin
-- Al refactorizar código Kotlin existente
-- Al diseñar módulos o librerías en Kotlin
-- Al configurar builds con Gradle Kotlin DSL
-
-## Cómo funciona
-
-Esta skill impone convenciones idiomáticas de Kotlin en siete áreas clave: null safety mediante el sistema de tipos y los operadores de llamada segura, inmutabilidad con `val` y `copy()` en data classes, sealed classes e interfaces para jerarquías de tipos exhaustivas, concurrencia estructurada con corrutinas y `Flow`, funciones de extensión para añadir comportamiento sin herencia, builders DSL con seguridad de tipos usando `@DslMarker` y lambdas con receptor, y Gradle Kotlin DSL para la configuración del build.
-
-## Ejemplos
-
-**Null safety con el operador Elvis:**
-```kotlin
-fun getUserEmail(userId: String): String {
-    val user = userRepository.findById(userId)
-    return user?.email ?: "desconocido@example.com"
-}
-```
-
-**Sealed class para resultados exhaustivos:**
-```kotlin
-sealed class Result<out T> {
-    data class Success<T>(val data: T) : Result<T>()
-    data class Failure(val error: AppError) : Result<Nothing>()
-    data object Loading : Result<Nothing>()
-}
-```
-
-**Concurrencia estructurada con async/await:**
-```kotlin
-suspend fun fetchUserWithPosts(userId: String): UserProfile =
-    coroutineScope {
-        val user = async { userService.getUser(userId) }
-        val posts = async { postService.getUserPosts(userId) }
-        UserProfile(user = user.await(), posts = posts.await())
-    }
-```
-
-## Principios fundamentales
-
-### 1. Null safety
-
-El sistema de tipos de Kotlin distingue tipos anulables y no anulables. Aprovéchalo al máximo.
-
-```kotlin
-// Bien: tipos no anulables por defecto
-fun getUser(id: String): User {
-    return userRepository.findById(id)
-        ?: throw UserNotFoundException("Usuario $id no encontrado")
-}
-
-// Bien: llamadas seguras y operador Elvis
-fun getUserEmail(userId: String): String {
-    val user = userRepository.findById(userId)
-    return user?.email ?: "desconocido@example.com"
-}
-
-// Mal: desempaquetado forzado de tipos anulables
-fun getUserEmail(userId: String): String {
-    val user = userRepository.findById(userId)
-    return user!!.email // Lanza NPE si es null
-}
-```
-
-### 2. Inmutabilidad por defecto
-
-Prefiere `val` sobre `var` y colecciones inmutables sobre mutables.
-
-```kotlin
-// Bien: datos inmutables
-data class User(
-    val id: String,
-    val name: String,
-    val email: String,
-)
-
-// Bien: transformar con copy()
-fun updateEmail(user: User, newEmail: String): User =
-    user.copy(email = newEmail)
-
-// Bien: colecciones inmutables
-val users: List<User> = listOf(user1, user2)
-val filtered = users.filter { it.email.isNotBlank() }
-
-// Mal: estado mutable
-var currentUser: User? = null // Evita el estado global mutable
-val mutableUsers = mutableListOf<User>() // Evítalo salvo que sea realmente necesario
-```
-
-### 3. Cuerpos de expresión y funciones de una sola expresión
-
-Usa cuerpos de expresión para funciones concisas y legibles.
-
-```kotlin
-// Bien: cuerpo de expresión
-fun isAdult(age: Int): Boolean = age >= 18
-
-fun formatFullName(first: String, last: String): String =
-    "$first $last".trim()
-
-fun User.displayName(): String =
-    name.ifBlank { email.substringBefore('@') }
-
-// Bien: when como expresión
-fun statusMessage(code: Int): String = when (code) {
-    200 -> "OK"
-    404 -> "No encontrado"
-    500 -> "Error interno del servidor"
-    else -> "Estado desconocido: $code"
-}
-
-// Mal: cuerpo de bloque innecesario
-fun isAdult(age: Int): Boolean {
-    return age >= 18
-}
-```
-
-### 4. Data classes para objetos de valor
-
-Usa data classes para tipos cuyo propósito principal es contener datos.
-
-```kotlin
-// Bien: data class con copy, equals, hashCode, toString
-data class CreateUserRequest(
-    val name: String,
-    val email: String,
-    val role: Role = Role.USER,
-)
-
-// Bien: value class para seguridad de tipos (cero coste en tiempo de ejecución)
-@JvmInline
-value class UserId(val value: String) {
-    init {
-        require(value.isNotBlank()) { "UserId no puede estar en blanco" }
-    }
-}
-
-@JvmInline
-value class Email(val value: String) {
-    init {
-        require('@' in value) { "Email inválido: $value" }
-    }
-}
-
-fun getUser(id: UserId): User = userRepository.findById(id)
-```
-
-## Sealed classes e interfaces
-
-### Modelar jerarquías restringidas
-
-```kotlin
-// Bien: sealed class para when exhaustivo
-sealed class Result<out T> {
-    data class Success<T>(val data: T) : Result<T>()
-    data class Failure(val error: AppError) : Result<Nothing>()
-    data object Loading : Result<Nothing>()
-}
-
-fun <T> Result<T>.getOrNull(): T? = when (this) {
-    is Result.Success -> data
-    is Result.Failure -> null
-    is Result.Loading -> null
-}
-
-fun <T> Result<T>.getOrThrow(): T = when (this) {
-    is Result.Success -> data
-    is Result.Failure -> throw error.toException()
-    is Result.Loading -> throw IllegalStateException("Aún cargando")
-}
-```
-
-### Sealed interfaces para respuestas de API
-
-```kotlin
-sealed interface ApiError {
-    val message: String
-
-    data class NotFound(override val message: String) : ApiError
-    data class Unauthorized(override val message: String) : ApiError
-    data class Validation(
-        override val message: String,
-        val field: String,
-    ) : ApiError
-    data class Internal(
-        override val message: String,
-        val cause: Throwable? = null,
-    ) : ApiError
-}
-
-fun ApiError.toStatusCode(): Int = when (this) {
-    is ApiError.NotFound -> 404
-    is ApiError.Unauthorized -> 401
-    is ApiError.Validation -> 422
-    is ApiError.Internal -> 500
-}
-```
-
-## Funciones de ámbito (scope functions)
-
-### Cuándo usar cada una
-
-```kotlin
-// let: transformar un valor anulable o un resultado con ámbito
-val length: Int? = name?.let { it.trim().length }
-
-// apply: configurar un objeto (devuelve el objeto)
-val user = User().apply {
-    name = "Alice"
-    email = "alice@example.com"
-}
-
-// also: efectos secundarios (devuelve el objeto)
-val user = createUser(request).also { logger.info("Usuario creado: ${it.id}") }
-
-// run: ejecutar un bloque con receptor (devuelve el resultado)
-val result = connection.run {
-    prepareStatement(sql)
-    executeQuery()
-}
-
-// with: forma no-extensión de run
-val csv = with(StringBuilder()) {
-    appendLine("name,email")
-    users.forEach { appendLine("${it.name},${it.email}") }
-    toString()
-}
-```
-
-### Antipatrones
-
-```kotlin
-// Mal: anidar funciones de ámbito
-user?.let { u ->
-    u.address?.let { addr ->
-        addr.city?.let { city ->
-            println(city) // Difícil de leer
-        }
-    }
-}
-
-// Bien: encadenar llamadas seguras
-val city = user?.address?.city
-city?.let { println(it) }
-```
-
-## Funciones de extensión
-
-### Añadir funcionalidad sin herencia
-
-```kotlin
-// Bien: extensiones específicas del dominio
-fun String.toSlug(): String =
-    lowercase()
-        .replace(Regex("[^a-z0-9\\s-]"), "")
-        .replace(Regex("\\s+"), "-")
-        .trim('-')
-
-fun Instant.toLocalDate(zone: ZoneId = ZoneId.systemDefault()): LocalDate =
-    atZone(zone).toLocalDate()
-
-// Bien: extensiones de colecciones
-fun <T> List<T>.second(): T = this[1]
-
-fun <T> List<T>.secondOrNull(): T? = getOrNull(1)
-
-// Bien: extensiones con ámbito acotado (sin contaminar el espacio de nombres global)
-class UserService {
-    private fun User.isActive(): Boolean =
-        status == Status.ACTIVE && lastLogin.isAfter(Instant.now().minus(30, ChronoUnit.DAYS))
-
-    fun getActiveUsers(): List<User> = userRepository.findAll().filter { it.isActive() }
-}
-```
-
-## Corrutinas
-
-### Concurrencia estructurada
-
-```kotlin
-// Bien: concurrencia estructurada con coroutineScope
-suspend fun fetchUserWithPosts(userId: String): UserProfile =
-    coroutineScope {
-        val userDeferred = async { userService.getUser(userId) }
-        val postsDeferred = async { postService.getUserPosts(userId) }
-
-        UserProfile(
-            user = userDeferred.await(),
-            posts = postsDeferred.await(),
-        )
-    }
-
-// Bien: supervisorScope cuando los hijos pueden fallar de forma independiente
-suspend fun fetchDashboard(userId: String): Dashboard =
-    supervisorScope {
-        val user = async { userService.getUser(userId) }
-        val notifications = async { notificationService.getRecent(userId) }
-        val recommendations = async { recommendationService.getFor(userId) }
-
-        Dashboard(
-            user = user.await(),
-            notifications = try {
-                notifications.await()
-            } catch (e: CancellationException) {
-                throw e
-            } catch (e: Exception) {
-                emptyList()
-            },
-            recommendations = try {
-                recommendations.await()
-            } catch (e: CancellationException) {
-                throw e
-            } catch (e: Exception) {
-                emptyList()
-            },
-        )
-    }
-```
-
-### Flow para streams reactivos
-
-```kotlin
-// Bien: flow frío con manejo de errores adecuado
-fun observeUsers(): Flow<List<User>> = flow {
-    while (currentCoroutineContext().isActive) {
-        val users = userRepository.findAll()
-        emit(users)
-        delay(5.seconds)
-    }
-}.catch { e ->
-    logger.error("Error observando usuarios", e)
-    emit(emptyList())
-}
-
-// Bien: operadores de Flow
-fun searchUsers(query: Flow<String>): Flow<List<User>> =
-    query
-        .debounce(300.milliseconds)
-        .distinctUntilChanged()
-        .filter { it.length >= 2 }
-        .mapLatest { q -> userRepository.search(q) }
-        .catch { emit(emptyList()) }
-```
-
-### Cancelación y limpieza
-
-```kotlin
-// Bien: respetar la cancelación
-suspend fun processItems(items: List<Item>) {
-    items.forEach { item ->
-        ensureActive() // Comprueba la cancelación antes de trabajo costoso
-        processItem(item)
-    }
-}
-
-// Bien: limpieza con try/finally
-suspend fun acquireAndProcess() {
-    val resource = acquireResource()
-    try {
-        resource.process()
-    } finally {
-        withContext(NonCancellable) {
-            resource.release() // Libera siempre, incluso ante cancelación
-        }
-    }
-}
-```
-
-## Delegación
-
-### Delegación de propiedades
-
-```kotlin
-// Inicialización perezosa
-val expensiveData: List<User> by lazy {
-    userRepository.findAll()
-}
-
-// Propiedad observable
-var name: String by Delegates.observable("inicial") { _, old, new ->
-    logger.info("Nombre cambiado de '$old' a '$new'")
-}
-
-// Propiedades respaldadas por un mapa
-class Config(private val map: Map<String, Any?>) {
-    val host: String by map
-    val port: Int by map
-    val debug: Boolean by map
-}
-
-val config = Config(mapOf("host" to "localhost", "port" to 8080, "debug" to true))
-```
-
-### Delegación de interfaces
-
-```kotlin
-// Bien: delegar la implementación de una interfaz
-class LoggingUserRepository(
-    private val delegate: UserRepository,
-    private val logger: Logger,
-) : UserRepository by delegate {
-    // Sobrescribe solo lo que necesita logging
-    override suspend fun findById(id: String): User? {
-        logger.info("Buscando usuario por id: $id")
-        return delegate.findById(id).also {
-            logger.info("Usuario encontrado: ${it?.name ?: "null"}")
-        }
-    }
-}
-```
-
-## Builders DSL
-
-### Builders con seguridad de tipos
-
-```kotlin
-// Bien: DSL con @DslMarker
-@DslMarker
-annotation class HtmlDsl
-
-@HtmlDsl
-class HTML {
-    private val children = mutableListOf<Element>()
-
-    fun head(init: Head.() -> Unit) {
-        children += Head().apply(init)
-    }
-
-    fun body(init: Body.() -> Unit) {
-        children += Body().apply(init)
-    }
-
-    override fun toString(): String = children.joinToString("\n")
-}
-
-fun html(init: HTML.() -> Unit): HTML = HTML().apply(init)
-
-// Uso
-val page = html {
-    head { title("Mi página") }
-    body {
-        h1("Bienvenido")
-        p("¡Hola, mundo!")
-    }
-}
-```
-
-### DSL de configuración
-
-```kotlin
-data class ServerConfig(
-    val host: String = "0.0.0.0",
-    val port: Int = 8080,
-    val ssl: SslConfig? = null,
-    val database: DatabaseConfig? = null,
-)
-
-data class SslConfig(val certPath: String, val keyPath: String)
-data class DatabaseConfig(val url: String, val maxPoolSize: Int = 10)
-
-class ServerConfigBuilder {
-    var host: String = "0.0.0.0"
-    var port: Int = 8080
-    private var ssl: SslConfig? = null
-    private var database: DatabaseConfig? = null
-
-    fun ssl(certPath: String, keyPath: String) {
-        ssl = SslConfig(certPath, keyPath)
-    }
-
-    fun database(url: String, maxPoolSize: Int = 10) {
-        database = DatabaseConfig(url, maxPoolSize)
-    }
-
-    fun build(): ServerConfig = ServerConfig(host, port, ssl, database)
-}
-
-fun serverConfig(init: ServerConfigBuilder.() -> Unit): ServerConfig =
-    ServerConfigBuilder().apply(init).build()
-
-// Uso
-val config = serverConfig {
-    host = "0.0.0.0"
-    port = 443
-    ssl("/certs/cert.pem", "/certs/key.pem")
-    database("jdbc:postgresql://localhost:5432/mydb", maxPoolSize = 20)
-}
-```
-
-## Sequences para evaluación perezosa
-
-```kotlin
-// Bien: usa sequences en colecciones grandes con varias operaciones encadenadas
-val result = users.asSequence()
-    .filter { it.isActive }
-    .map { it.email }
-    .filter { it.endsWith("@empresa.com") }
-    .take(10)
-    .toList()
-
-// Bien: generar secuencias infinitas
-val fibonacci: Sequence<Long> = sequence {
-    var a = 0L
-    var b = 1L
-    while (true) {
-        yield(a)
-        val next = a + b
-        a = b
-        b = next
-    }
-}
-
-val first20 = fibonacci.take(20).toList()
-```
-
-## Gradle Kotlin DSL
-
-### Configuración de build.gradle.kts
-
-```kotlin
-// Consulta las últimas versiones: https://kotlinlang.org/docs/releases.html
-plugins {
-    kotlin("jvm") version "2.3.10"
-    kotlin("plugin.serialization") version "2.3.10"
-    id("io.ktor.plugin") version "3.4.0"
-    id("org.jetbrains.kotlinx.kover") version "0.9.7"
-    id("io.gitlab.arturbosch.detekt") version "1.23.8"
-}
-
-group = "com.example"
-version = "1.0.0"
-
-kotlin {
-    jvmToolchain(21)
-}
-
-dependencies {
-    // Ktor
-    implementation("io.ktor:ktor-server-core:3.4.0")
-    implementation("io.ktor:ktor-server-netty:3.4.0")
-    implementation("io.ktor:ktor-server-content-negotiation:3.4.0")
-    implementation("io.ktor:ktor-serialization-kotlinx-json:3.4.0")
-
-    // Exposed
-    implementation("org.jetbrains.exposed:exposed-core:1.0.0")
-    implementation("org.jetbrains.exposed:exposed-dao:1.0.0")
-    implementation("org.jetbrains.exposed:exposed-jdbc:1.0.0")
-    implementation("org.jetbrains.exposed:exposed-kotlin-datetime:1.0.0")
-
-    // Koin
-    implementation("io.insert-koin:koin-ktor:4.2.0")
-
-    // Corrutinas
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
-
-    // Testing
-    testImplementation("io.kotest:kotest-runner-junit5:6.1.4")
-    testImplementation("io.kotest:kotest-assertions-core:6.1.4")
-    testImplementation("io.kotest:kotest-property:6.1.4")
-    testImplementation("io.mockk:mockk:1.14.9")
-    testImplementation("io.ktor:ktor-server-test-host:3.4.0")
-    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2")
-}
-
-tasks.withType<Test> {
-    useJUnitPlatform()
-}
-
-detekt {
-    config.setFrom(files("config/detekt/detekt.yml"))
-    buildUponDefaultConfig = true
-}
-```
-
-## Patrones de manejo de errores
-
-### Tipo Result para operaciones de dominio
-
-```kotlin
-// Bien: usa el Result de Kotlin o una sealed class propia
-suspend fun createUser(request: CreateUserRequest): Result<User> = runCatching {
-    require(request.name.isNotBlank()) { "El nombre no puede estar en blanco" }
-    require('@' in request.email) { "Formato de email inválido" }
-
-    val user = User(
-        id = UserId(UUID.randomUUID().toString()),
-        name = request.name,
-        email = Email(request.email),
-    )
-    userRepository.save(user)
-    user
-}
-
-// Bien: encadenar resultados
-val displayName = createUser(request)
-    .map { it.name }
-    .getOrElse { "Desconocido" }
-```
-
-### require, check, error
-
-```kotlin
-// Bien: precondiciones con mensajes claros
-fun withdraw(account: Account, amount: Money): Account {
-    require(amount.value > 0) { "El importe debe ser positivo: $amount" }
-    check(account.balance >= amount) { "Saldo insuficiente: ${account.balance} < $amount" }
-
-    return account.copy(balance = account.balance - amount)
-}
-```
-
-## Operaciones sobre colecciones
-
-### Procesamiento idiomático de colecciones
-
-```kotlin
-// Bien: operaciones encadenadas
-val activeAdminEmails: List<String> = users
-    .filter { it.role == Role.ADMIN && it.isActive }
-    .sortedBy { it.name }
-    .map { it.email }
-
-// Bien: agrupación y agregación
-val usersByRole: Map<Role, List<User>> = users.groupBy { it.role }
-
-val oldestByRole: Map<Role, User?> = users.groupBy { it.role }
-    .mapValues { (_, users) -> users.minByOrNull { it.createdAt } }
-
-// Bien: associate para crear mapas
-val usersById: Map<UserId, User> = users.associateBy { it.id }
-
-// Bien: partition para dividir
-val (active, inactive) = users.partition { it.isActive }
-```
-
-## Referencia rápida: idiomas de Kotlin
-
-| Idioma | Descripción |
-|-------|-------------|
-| `val` sobre `var` | Prefiere variables inmutables |
-| `data class` | Para objetos de valor con equals/hashCode/copy |
-| `sealed class/interface` | Para jerarquías de tipos restringidas |
-| `value class` | Para envoltorios con seguridad de tipos y coste cero |
-| `when` como expresión | Coincidencia de patrones exhaustiva |
-| Llamada segura `?.` | Acceso a miembros seguro ante null |
-| Elvis `?:` | Valor por defecto para anulables |
-| `let`/`apply`/`also`/`run`/`with` | Funciones de ámbito para código limpio |
-| Funciones de extensión | Añadir comportamiento sin herencia |
-| `copy()` | Actualizaciones inmutables en data classes |
-| `require`/`check` | Aserciones de precondiciones |
-| Corrutinas `async`/`await` | Ejecución concurrente estructurada |
-| `Flow` | Streams reactivos fríos |
-| `sequence` | Evaluación perezosa |
-| Delegación `by` | Reutilizar implementación sin herencia |
-
-## Antipatrones a evitar
-
-```kotlin
-// Mal: desempaquetado forzado de tipos anulables
-val name = user!!.name
-
-// Mal: fuga de platform types desde Java
-fun getLength(s: String) = s.length // Seguro
-fun getLength(s: String?) = s?.length ?: 0 // Maneja nulls provenientes de Java
-
-// Mal: data classes mutables
-data class MutableUser(var name: String, var email: String)
-
-// Mal: usar excepciones para control de flujo
-try {
-    val user = findUser(id)
-} catch (e: NotFoundException) {
-    // No uses excepciones para casos esperados
-}
-
-// Bien: usa retorno anulable o Result
-val user: User? = findUserOrNull(id)
-
-// Mal: ignorar el ámbito de las corrutinas
-GlobalScope.launch { /* Evita GlobalScope */ }
-
-// Bien: usa concurrencia estructurada
-coroutineScope {
-    launch { /* Correctamente acotado */ }
-}
-
-// Mal: funciones de ámbito profundamente anidadas
-user?.let { u ->
-    u.address?.let { a ->
-        a.city?.let { c -> process(c) }
-    }
-}
-
-// Bien: cadena directa segura ante null
-user?.address?.city?.let { process(it) }
-```
-
-**Recuerda**: el código Kotlin debe ser conciso pero legible. Aprovecha el sistema de tipos para la seguridad, prefiere la inmutabilidad y usa corrutinas para la concurrencia. Ante la duda, deja que el compilador te ayude.
-
-## Skills relacionadas
-
-- `testing-kotlin` — patrones de testing con Kotest, MockK y Kover
-- `corrutinas-flows-kotlin` — corrutinas y Flow en profundidad
-- `patrones-kotlin-ktor` — patrones de servidor con Ktor
-- `patrones-kotlin-exposed` — acceso a datos con Exposed