theus-cli 0.2.82 → 0.2.84

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

@@ -1,694 +0,0 @@
----
-name: patrones-kotlin-ktor
-description: Patrones de servidores Ktor — DSL de rutas, plugins, autenticación JWT, inyección de dependencias con Koin, kotlinx.serialization, WebSockets y testing con testApplication.
----
-
-# Patrones de servidor Ktor
-
-Patrones completos de Ktor para construir servidores HTTP robustos y mantenibles con corrutinas de Kotlin.
-
-## Cuándo activarla
-
-- Al construir servidores HTTP con Ktor
-- Al configurar plugins de Ktor (Auth, CORS, ContentNegotiation, StatusPages)
-- Al implementar APIs REST con Ktor
-- Al montar inyección de dependencias con Koin
-- Al escribir tests de integración de Ktor con testApplication
-- Al trabajar con WebSockets en Ktor
-
-## Estructura de la aplicación
-
-### Estructura estándar de un proyecto Ktor
-
-```text
-src/main/kotlin/
-├── com/example/
-│   ├── Application.kt           # Punto de entrada, configuración del módulo
-│   ├── plugins/
-│   │   ├── Routing.kt           # Definición de rutas
-│   │   ├── Serialization.kt     # Configuración de content negotiation
-│   │   ├── Authentication.kt    # Configuración de autenticación
-│   │   ├── StatusPages.kt       # Manejo de errores
-│   │   └── CORS.kt              # Configuración de CORS
-│   ├── routes/
-│   │   ├── UserRoutes.kt        # Endpoints /users
-│   │   ├── AuthRoutes.kt        # Endpoints /auth
-│   │   └── HealthRoutes.kt      # Endpoints /health
-│   ├── models/
-│   │   ├── User.kt              # Modelos de dominio
-│   │   └── ApiResponse.kt       # Envoltorios de respuesta
-│   ├── services/
-│   │   ├── UserService.kt       # Lógica de negocio
-│   │   └── AuthService.kt       # Lógica de autenticación
-│   ├── repositories/
-│   │   ├── UserRepository.kt    # Interfaz de acceso a datos
-│   │   └── ExposedUserRepository.kt
-│   └── di/
-│       └── AppModule.kt         # Módulos de Koin
-src/test/kotlin/
-├── com/example/
-│   ├── routes/
-│   │   └── UserRoutesTest.kt
-│   └── services/
-│       └── UserServiceTest.kt
-```
-
-### Punto de entrada de la aplicación
-
-```kotlin
-// Application.kt
-fun main() {
-    embeddedServer(Netty, port = 8080, module = Application::module).start(wait = true)
-}
-
-fun Application.module() {
-    configureSerialization()
-    configureAuthentication()
-    configureStatusPages()
-    configureCORS()
-    configureDI()
-    configureRouting()
-}
-```
-
-## DSL de rutas
-
-### Rutas básicas
-
-```kotlin
-// plugins/Routing.kt
-fun Application.configureRouting() {
-    routing {
-        userRoutes()
-        authRoutes()
-        healthRoutes()
-    }
-}
-
-// routes/UserRoutes.kt
-fun Route.userRoutes() {
-    val userService by inject<UserService>()
-
-    route("/users") {
-        get {
-            val users = userService.getAll()
-            call.respond(users)
-        }
-
-        get("/{id}") {
-            val id = call.parameters["id"]
-                ?: return@get call.respond(HttpStatusCode.BadRequest, "Falta el id")
-            val user = userService.getById(id)
-                ?: return@get call.respond(HttpStatusCode.NotFound)
-            call.respond(user)
-        }
-
-        post {
-            val request = call.receive<CreateUserRequest>()
-            val user = userService.create(request)
-            call.respond(HttpStatusCode.Created, user)
-        }
-
-        put("/{id}") {
-            val id = call.parameters["id"]
-                ?: return@put call.respond(HttpStatusCode.BadRequest, "Falta el id")
-            val request = call.receive<UpdateUserRequest>()
-            val user = userService.update(id, request)
-                ?: return@put call.respond(HttpStatusCode.NotFound)
-            call.respond(user)
-        }
-
-        delete("/{id}") {
-            val id = call.parameters["id"]
-                ?: return@delete call.respond(HttpStatusCode.BadRequest, "Falta el id")
-            val deleted = userService.delete(id)
-            if (deleted) call.respond(HttpStatusCode.NoContent)
-            else call.respond(HttpStatusCode.NotFound)
-        }
-    }
-}
-```
-
-### Organización de rutas con rutas autenticadas
-
-```kotlin
-fun Route.userRoutes() {
-    route("/users") {
-        // Rutas públicas
-        get { /* listar usuarios */ }
-        get("/{id}") { /* obtener usuario */ }
-
-        // Rutas protegidas
-        authenticate("jwt") {
-            post { /* crear usuario - requiere autenticación */ }
-            put("/{id}") { /* actualizar usuario - requiere autenticación */ }
-            delete("/{id}") { /* eliminar usuario - requiere autenticación */ }
-        }
-    }
-}
-```
-
-## Content negotiation y serialización
-
-### Configuración de kotlinx.serialization
-
-```kotlin
-// plugins/Serialization.kt
-fun Application.configureSerialization() {
-    install(ContentNegotiation) {
-        json(Json {
-            prettyPrint = true
-            isLenient = false
-            ignoreUnknownKeys = true
-            encodeDefaults = true
-            explicitNulls = false
-        })
-    }
-}
-```
-
-### Modelos serializables
-
-```kotlin
-@Serializable
-data class UserResponse(
-    val id: String,
-    val name: String,
-    val email: String,
-    val role: Role,
-    @Serializable(with = InstantSerializer::class)
-    val createdAt: Instant,
-)
-
-@Serializable
-data class CreateUserRequest(
-    val name: String,
-    val email: String,
-    val role: Role = Role.USER,
-)
-
-@Serializable
-data class ApiResponse<T>(
-    val success: Boolean,
-    val data: T? = null,
-    val error: String? = null,
-) {
-    companion object {
-        fun <T> ok(data: T): ApiResponse<T> = ApiResponse(success = true, data = data)
-        fun <T> error(message: String): ApiResponse<T> = ApiResponse(success = false, error = message)
-    }
-}
-
-@Serializable
-data class PaginatedResponse<T>(
-    val data: List<T>,
-    val total: Long,
-    val page: Int,
-    val limit: Int,
-)
-```
-
-### Serializadores personalizados
-
-```kotlin
-object InstantSerializer : KSerializer<Instant> {
-    override val descriptor = PrimitiveSerialDescriptor("Instant", PrimitiveKind.STRING)
-    override fun serialize(encoder: Encoder, value: Instant) =
-        encoder.encodeString(value.toString())
-    override fun deserialize(decoder: Decoder): Instant =
-        Instant.parse(decoder.decodeString())
-}
-```
-
-## Autenticación
-
-### Autenticación JWT
-
-```kotlin
-// plugins/Authentication.kt
-fun Application.configureAuthentication() {
-    val jwtSecret = environment.config.property("jwt.secret").getString()
-    val jwtIssuer = environment.config.property("jwt.issuer").getString()
-    val jwtAudience = environment.config.property("jwt.audience").getString()
-    val jwtRealm = environment.config.property("jwt.realm").getString()
-
-    install(Authentication) {
-        jwt("jwt") {
-            realm = jwtRealm
-            verifier(
-                JWT.require(Algorithm.HMAC256(jwtSecret))
-                    .withAudience(jwtAudience)
-                    .withIssuer(jwtIssuer)
-                    .build()
-            )
-            validate { credential ->
-                if (credential.payload.audience.contains(jwtAudience)) {
-                    JWTPrincipal(credential.payload)
-                } else {
-                    null
-                }
-            }
-            challenge { _, _ ->
-                call.respond(HttpStatusCode.Unauthorized, ApiResponse.error<Unit>("Token inválido o expirado"))
-            }
-        }
-    }
-}
-
-// Extraer el usuario del JWT
-fun ApplicationCall.userId(): String =
-    principal<JWTPrincipal>()
-        ?.payload
-        ?.getClaim("userId")
-        ?.asString()
-        ?: throw AuthenticationException("El token no contiene userId")
-```
-
-### Rutas de autenticación
-
-```kotlin
-fun Route.authRoutes() {
-    val authService by inject<AuthService>()
-
-    route("/auth") {
-        post("/login") {
-            val request = call.receive<LoginRequest>()
-            val token = authService.login(request.email, request.password)
-                ?: return@post call.respond(
-                    HttpStatusCode.Unauthorized,
-                    ApiResponse.error<Unit>("Credenciales inválidas"),
-                )
-            call.respond(ApiResponse.ok(TokenResponse(token)))
-        }
-
-        post("/register") {
-            val request = call.receive<RegisterRequest>()
-            val user = authService.register(request)
-            call.respond(HttpStatusCode.Created, ApiResponse.ok(user))
-        }
-
-        authenticate("jwt") {
-            get("/me") {
-                val userId = call.userId()
-                val user = authService.getProfile(userId)
-                call.respond(ApiResponse.ok(user))
-            }
-        }
-    }
-}
-```
-
-## Status Pages (manejo de errores)
-
-```kotlin
-// plugins/StatusPages.kt
-fun Application.configureStatusPages() {
-    install(StatusPages) {
-        exception<ContentTransformationException> { call, cause ->
-            call.respond(
-                HttpStatusCode.BadRequest,
-                ApiResponse.error<Unit>("Cuerpo de la petición inválido: ${cause.message}"),
-            )
-        }
-
-        exception<IllegalArgumentException> { call, cause ->
-            call.respond(
-                HttpStatusCode.BadRequest,
-                ApiResponse.error<Unit>(cause.message ?: "Petición incorrecta"),
-            )
-        }
-
-        exception<AuthenticationException> { call, _ ->
-            call.respond(
-                HttpStatusCode.Unauthorized,
-                ApiResponse.error<Unit>("Autenticación requerida"),
-            )
-        }
-
-        exception<AuthorizationException> { call, _ ->
-            call.respond(
-                HttpStatusCode.Forbidden,
-                ApiResponse.error<Unit>("Acceso denegado"),
-            )
-        }
-
-        exception<NotFoundException> { call, cause ->
-            call.respond(
-                HttpStatusCode.NotFound,
-                ApiResponse.error<Unit>(cause.message ?: "Recurso no encontrado"),
-            )
-        }
-
-        exception<Throwable> { call, cause ->
-            call.application.log.error("Excepción no manejada", cause)
-            call.respond(
-                HttpStatusCode.InternalServerError,
-                ApiResponse.error<Unit>("Error interno del servidor"),
-            )
-        }
-
-        status(HttpStatusCode.NotFound) { call, status ->
-            call.respond(status, ApiResponse.error<Unit>("Ruta no encontrada"))
-        }
-    }
-}
-```
-
-## Configuración de CORS
-
-```kotlin
-// plugins/CORS.kt
-fun Application.configureCORS() {
-    install(CORS) {
-        allowHost("localhost:3000")
-        allowHost("example.com", schemes = listOf("https"))
-        allowHeader(HttpHeaders.ContentType)
-        allowHeader(HttpHeaders.Authorization)
-        allowMethod(HttpMethod.Put)
-        allowMethod(HttpMethod.Delete)
-        allowMethod(HttpMethod.Patch)
-        allowCredentials = true
-        maxAgeInSeconds = 3600
-    }
-}
-```
-
-## Inyección de dependencias con Koin
-
-### Definición de módulos
-
-```kotlin
-// di/AppModule.kt
-val appModule = module {
-    // Base de datos
-    single<Database> { DatabaseFactory.create(get()) }
-
-    // Repositorios
-    single<UserRepository> { ExposedUserRepository(get()) }
-    single<OrderRepository> { ExposedOrderRepository(get()) }
-
-    // Servicios
-    single { UserService(get()) }
-    single { OrderService(get(), get()) }
-    single { AuthService(get(), get()) }
-}
-
-// Configuración de la aplicación
-fun Application.configureDI() {
-    install(Koin) {
-        modules(appModule)
-    }
-}
-```
-
-### Usar Koin en las rutas
-
-```kotlin
-fun Route.userRoutes() {
-    val userService by inject<UserService>()
-
-    route("/users") {
-        get {
-            val users = userService.getAll()
-            call.respond(ApiResponse.ok(users))
-        }
-    }
-}
-```
-
-### Koin en los tests
-
-```kotlin
-class UserServiceTest : FunSpec(), KoinTest {
-    override fun extensions() = listOf(KoinExtension(testModule))
-
-    private val testModule = module {
-        single<UserRepository> { mockk() }
-        single { UserService(get()) }
-    }
-
-    private val repository by inject<UserRepository>()
-    private val service by inject<UserService>()
-
-    init {
-        test("getUser devuelve un usuario") {
-            coEvery { repository.findById("1") } returns testUser
-            service.getById("1") shouldBe testUser
-        }
-    }
-}
-```
-
-## Validación de peticiones
-
-```kotlin
-// Validar los datos de la petición en las rutas
-fun Route.userRoutes() {
-    val userService by inject<UserService>()
-
-    post("/users") {
-        val request = call.receive<CreateUserRequest>()
-
-        // Validar
-        require(request.name.isNotBlank()) { "El nombre es obligatorio" }
-        require(request.name.length <= 100) { "El nombre debe tener 100 caracteres o menos" }
-        require(request.email.matches(Regex(".+@.+\\..+"))) { "Formato de email inválido" }
-
-        val user = userService.create(request)
-        call.respond(HttpStatusCode.Created, ApiResponse.ok(user))
-    }
-}
-
-// O usar una extensión de validación
-fun CreateUserRequest.validate() {
-    require(name.isNotBlank()) { "El nombre es obligatorio" }
-    require(name.length <= 100) { "El nombre debe tener 100 caracteres o menos" }
-    require(email.matches(Regex(".+@.+\\..+"))) { "Formato de email inválido" }
-}
-```
-
-## WebSockets
-
-```kotlin
-fun Application.configureWebSockets() {
-    install(WebSockets) {
-        pingPeriod = 15.seconds
-        timeout = 15.seconds
-        maxFrameSize = 64 * 1024 // 64 KiB — auméntalo solo si tu protocolo requiere frames más grandes
-        masking = false // Los frames servidor→cliente van sin máscara según RFC 6455; los cliente→servidor siempre los enmascara Ktor
-    }
-}
-
-fun Route.chatRoutes() {
-    val connections = Collections.synchronizedSet<Connection>(LinkedHashSet())
-
-    webSocket("/chat") {
-        val thisConnection = Connection(this)
-        connections += thisConnection
-
-        try {
-            send("¡Conectado! Usuarios en línea: ${connections.size}")
-
-            for (frame in incoming) {
-                frame as? Frame.Text ?: continue
-                val text = frame.readText()
-                val message = ChatMessage(thisConnection.name, text)
-
-                // Toma una instantánea bajo el lock para evitar ConcurrentModificationException
-                val snapshot = synchronized(connections) { connections.toList() }
-                snapshot.forEach { conn ->
-                    conn.session.send(Json.encodeToString(message))
-                }
-            }
-        } catch (e: Exception) {
-            logger.error("Error de WebSocket", e)
-        } finally {
-            connections -= thisConnection
-        }
-    }
-}
-
-data class Connection(val session: DefaultWebSocketSession) {
-    val name: String = "User-${counter.getAndIncrement()}"
-
-    companion object {
-        private val counter = AtomicInteger(0)
-    }
-}
-```
-
-## Testing con testApplication
-
-### Testeo básico de rutas
-
-```kotlin
-class UserRoutesTest : FunSpec({
-    test("GET /users devuelve la lista de usuarios") {
-        testApplication {
-            application {
-                install(Koin) { modules(testModule) }
-                configureSerialization()
-                configureRouting()
-            }
-
-            val response = client.get("/users")
-
-            response.status shouldBe HttpStatusCode.OK
-            val body = response.body<ApiResponse<List<UserResponse>>>()
-            body.success shouldBe true
-            body.data.shouldNotBeNull().shouldNotBeEmpty()
-        }
-    }
-
-    test("POST /users crea un usuario") {
-        testApplication {
-            application {
-                install(Koin) { modules(testModule) }
-                configureSerialization()
-                configureStatusPages()
-                configureRouting()
-            }
-
-            val client = createClient {
-                install(io.ktor.client.plugins.contentnegotiation.ContentNegotiation) {
-                    json()
-                }
-            }
-
-            val response = client.post("/users") {
-                contentType(ContentType.Application.Json)
-                setBody(CreateUserRequest("Alice", "alice@example.com"))
-            }
-
-            response.status shouldBe HttpStatusCode.Created
-        }
-    }
-
-    test("GET /users/{id} devuelve 404 para un id desconocido") {
-        testApplication {
-            application {
-                install(Koin) { modules(testModule) }
-                configureSerialization()
-                configureStatusPages()
-                configureRouting()
-            }
-
-            val response = client.get("/users/unknown-id")
-
-            response.status shouldBe HttpStatusCode.NotFound
-        }
-    }
-})
-```
-
-### Testear rutas autenticadas
-
-```kotlin
-class AuthenticatedRoutesTest : FunSpec({
-    test("una ruta protegida requiere JWT") {
-        testApplication {
-            application {
-                install(Koin) { modules(testModule) }
-                configureSerialization()
-                configureAuthentication()
-                configureRouting()
-            }
-
-            val response = client.post("/users") {
-                contentType(ContentType.Application.Json)
-                setBody(CreateUserRequest("Alice", "alice@example.com"))
-            }
-
-            response.status shouldBe HttpStatusCode.Unauthorized
-        }
-    }
-
-    test("una ruta protegida funciona con un JWT válido") {
-        testApplication {
-            application {
-                install(Koin) { modules(testModule) }
-                configureSerialization()
-                configureAuthentication()
-                configureRouting()
-            }
-
-            val token = generateTestJWT(userId = "test-user")
-
-            val client = createClient {
-                install(io.ktor.client.plugins.contentnegotiation.ContentNegotiation) { json() }
-            }
-
-            val response = client.post("/users") {
-                contentType(ContentType.Application.Json)
-                bearerAuth(token)
-                setBody(CreateUserRequest("Alice", "alice@example.com"))
-            }
-
-            response.status shouldBe HttpStatusCode.Created
-        }
-    }
-})
-```
-
-## Configuración
-
-### application.yaml
-
-```yaml
-ktor:
-  application:
-    modules:
-      - com.example.ApplicationKt.module
-  deployment:
-    port: 8080
-
-jwt:
-  secret: ${JWT_SECRET}
-  issuer: "https://example.com"
-  audience: "https://example.com/api"
-  realm: "example"
-
-database:
-  url: ${DATABASE_URL}
-  driver: "org.postgresql.Driver"
-  maxPoolSize: 10
-```
-
-### Leer la configuración
-
-```kotlin
-fun Application.configureDI() {
-    val dbUrl = environment.config.property("database.url").getString()
-    val dbDriver = environment.config.property("database.driver").getString()
-    val maxPoolSize = environment.config.property("database.maxPoolSize").getString().toInt()
-
-    install(Koin) {
-        modules(module {
-            single { DatabaseConfig(dbUrl, dbDriver, maxPoolSize) }
-            single { DatabaseFactory.create(get()) }
-        })
-    }
-}
-```
-
-## Referencia rápida: patrones de Ktor
-
-| Patrón | Descripción |
-|--------|-------------|
-| `route("/path") { get { } }` | Agrupación de rutas con el DSL |
-| `call.receive<T>()` | Deserializar el cuerpo de la petición |
-| `call.respond(status, body)` | Enviar respuesta con estado |
-| `call.parameters["id"]` | Leer parámetros de ruta |
-| `call.request.queryParameters["q"]` | Leer parámetros de query |
-| `install(Plugin) { }` | Instalar y configurar un plugin |
-| `authenticate("name") { }` | Proteger rutas con autenticación |
-| `by inject<T>()` | Inyección de dependencias con Koin |
-| `testApplication { }` | Testing de integración |
-
-**Recuerda**: Ktor está diseñado alrededor de las corrutinas y los DSL de Kotlin. Mantén las rutas delgadas, empuja la lógica a los servicios y usa Koin para la inyección de dependencias. Testea con `testApplication` para cobertura de integración completa.
-
-## Skills relacionadas
-
-- `patrones-kotlin-exposed`
-- `corrutinas-flows-kotlin`
-- `testing-kotlin`