moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-lang-kotlin/SKILL.md

@@ -1,13 +1,15 @@
 ---
-name: moai-lang-kotlin
-description: Kotlin 2.0+ development specialist covering Ktor, coroutines, Compose Multiplatform, and Kotlin-idiomatic patterns. Use when building Kotlin server apps, Android apps, or multiplatform projects.
-version: 1.0.0
-category: language
-tags: kotlin, ktor, coroutines, compose, android, multiplatform
-context7-libraries: /ktorio/ktor, /jetbrains/compose-multiplatform, /jetbrains/exposed
-related-skills: moai-lang-java, moai-lang-swift
-updated: 2025-12-07
-status: active
+name: "moai-lang-kotlin"
+description: "Kotlin 2.0+ development specialist covering Ktor, coroutines, Compose Multiplatform, and Kotlin-idiomatic patterns. Use when building Kotlin server apps, Android apps, or multiplatform projects."
+version: 1.1.0
+category: "language"
+modularized: false
+user-invocable: false
+tags: ['kotlin', 'ktor', 'coroutines', 'compose', 'android', 'multiplatform']
+context7-libraries: "/ktorio/ktor, /jetbrains/compose-multiplatform, /jetbrains/exposed"
+related-skills: "moai-lang-java, moai-lang-swift"
+updated: 2026-01-11
+status: "active"
 ---
 
 ## Quick Reference (30 seconds)
@@ -17,6 +19,7 @@ Kotlin 2.0+ Expert - K2 compiler, coroutines, Ktor, Compose Multiplatform with C
 Auto-Triggers: Kotlin files (`.kt`, `.kts`), Gradle Kotlin DSL (`build.gradle.kts`, `settings.gradle.kts`)
 
 Core Capabilities:
+
 - Kotlin 2.0: K2 compiler, coroutines, Flow, sealed classes, value classes
 - Ktor 3.0: Async HTTP server/client, WebSocket, JWT authentication
 - Exposed 0.55: Kotlin SQL framework with coroutines support
@@ -30,191 +33,29 @@ Core Capabilities:
 
 ### Kotlin 2.0 Features
 
-Coroutines and Flow:
-```kotlin
-// Structured concurrency with async/await
-suspend fun fetchUserWithOrders(userId: Long): UserWithOrders = coroutineScope {
-    val userDeferred = async { userRepository.findById(userId) }
-    val ordersDeferred = async { orderRepository.findByUserId(userId) }
-    UserWithOrders(userDeferred.await(), ordersDeferred.await())
-}
-
-// Flow for reactive streams
-fun observeUsers(): Flow<User> = flow {
-    while (true) {
-        emit(userRepository.findLatest())
-        delay(1000)
-    }
-}.flowOn(Dispatchers.IO)
-```
-
-Sealed Classes and Value Classes:
-```kotlin
-sealed interface Result<out T> {
-    data class Success<T>(val data: T) : Result<T>
-    data class Error(val exception: Throwable) : Result<Nothing>
-    data object Loading : Result<Nothing>
-}
-
-@JvmInline
-value class UserId(val value: Long) {
-    init { require(value > 0) { "UserId must be positive" } }
-}
-
-@JvmInline
-value class Email(val value: String) {
-    init { require(value.contains("@")) { "Invalid email format" } }
-}
-```
+Coroutines and Flow: Use coroutineScope with async for parallel operations. Create deferred values with async, then call await on each to get results. Combine results into data classes. For reactive streams, create flow blocks with emit calls inside while loops. Use delay for intervals and flowOn to specify dispatcher.
+
+Sealed Classes and Value Classes: Define sealed interface with generic type parameter. Create data class implementations for success and data object for stateless cases like Loading. Use @JvmInline annotation with value class wrapping a primitive. Add init blocks with require for validation.
 
 ### Ktor 3.0 Server
 
-Application Setup:
-```kotlin
-fun main() {
-    embeddedServer(Netty, port = 8080, host = "0.0.0.0") {
-        configureKoin()
-        configureSecurity()
-        configureRouting()
-        configureContentNegotiation()
-    }.start(wait = true)
-}
-
-fun Application.configureKoin() {
-    install(Koin) { modules(appModule) }
-}
-
-val appModule = module {
-    single<Database> { DatabaseFactory.create() }
-    single<UserRepository> { UserRepositoryImpl(get()) }
-    single<UserService> { UserServiceImpl(get()) }
-}
-
-fun Application.configureSecurity() {
-    install(Authentication) {
-        jwt("auth-jwt") {
-            realm = "User API"
-            verifier(JwtConfig.verifier)
-            validate { credential ->
-                if (credential.payload.audience.contains("api"))
-                    JWTPrincipal(credential.payload) else null
-            }
-        }
-    }
-}
-
-fun Application.configureContentNegotiation() {
-    install(ContentNegotiation) {
-        json(Json { prettyPrint = true; ignoreUnknownKeys = true })
-    }
-}
-```
-
-Routing with Authentication:
-```kotlin
-fun Application.configureRouting() {
-    val userService by inject<UserService>()
-
-    routing {
-        route("/api/v1") {
-            post("/auth/register") {
-                val request = call.receive<CreateUserRequest>()
-                val user = userService.create(request)
-                call.respond(HttpStatusCode.Created, user.toDto())
-            }
-
-            authenticate("auth-jwt") {
-                route("/users") {
-                    get {
-                        val page = call.parameters["page"]?.toIntOrNull() ?: 0
-                        val size = call.parameters["size"]?.toIntOrNull() ?: 20
-                        call.respond(userService.findAll(page, size).map { it.toDto() })
-                    }
-
-                    get("/{id}") {
-                        val id = call.parameters["id"]?.toLongOrNull()
-                            ?: return@get call.respond(HttpStatusCode.BadRequest)
-                        userService.findById(id)?.let { call.respond(it.toDto()) }
-                            ?: call.respond(HttpStatusCode.NotFound)
-                    }
-                }
-            }
-        }
-    }
-}
-```
+Application Setup: Call embeddedServer with Netty, port, and host parameters. Inside the lambda, call configuration functions for Koin, security, routing, and content negotiation. Call start with wait equals true.
+
+For Koin configuration, install Koin plugin and define modules with single declarations for singletons. For security, install Authentication plugin and configure JWT with realm, verifier, and validate callback. For content negotiation, install ContentNegotiation with json configuration.
+
+Routing with Authentication: Define routing function on Application. Inside routing block, use route for path prefixes. Create unauthenticated endpoints with post and call.receive for request body. Use authenticate block with verifier name for protected routes. Inside route blocks, define get endpoints with call.parameters for path/query params. Use call.respond with status code and response body.
 
 ### Exposed SQL Framework
 
-Table and Entity:
-```kotlin
-object Users : LongIdTable("users") {
-    val name = varchar("name", 100)
-    val email = varchar("email", 255).uniqueIndex()
-    val passwordHash = varchar("password_hash", 255)
-    val status = enumerationByName<UserStatus>("status", 20)
-    val createdAt = timestamp("created_at").defaultExpression(CurrentTimestamp())
-}
-
-class UserEntity(id: EntityID<Long>) : LongEntity(id) {
-    companion object : LongEntityClass<UserEntity>(Users)
-    var name by Users.name
-    var email by Users.email
-    var passwordHash by Users.passwordHash
-    var status by Users.status
-    var createdAt by Users.createdAt
-
-    fun toModel() = User(id.value, name, email, passwordHash, status, createdAt)
-}
-```
-
-Repository with Coroutines:
-```kotlin
-class UserRepositoryImpl(private val database: Database) : UserRepository {
-    override suspend fun findById(id: Long): User? = dbQuery {
-        UserEntity.findById(id)?.toModel()
-    }
-
-    override suspend fun save(user: User): User = dbQuery {
-        UserEntity.new {
-            name = user.name
-            email = user.email
-            passwordHash = user.passwordHash
-            status = user.status
-        }.toModel()
-    }
-
-    private suspend fun <T> dbQuery(block: suspend () -> T): T =
-        newSuspendedTransaction(Dispatchers.IO, database) { block() }
-}
-```
+Table and Entity: Define object extending LongIdTable with table name. Declare columns with varchar, enumerationByName, and timestamp functions. Use uniqueIndex() and defaultExpression for defaults.
+
+Create entity class extending LongEntity with companion object extending LongEntityClass. Declare properties with by syntax using table column references. Create toModel function to map entity to domain model.
+
+Repository with Coroutines: Create repository implementation taking Database parameter. Implement suspend functions wrapping Exposed operations in dbQuery helper. Use findById for single entity lookup. Use Entity.new for inserts. Define private dbQuery function using newSuspendedTransaction with IO dispatcher.
 
 ### Spring Boot with Kotlin
 
-WebFlux Controller:
-```kotlin
-@RestController
-@RequestMapping("/api/users")
-class UserController(private val userService: UserService) {
-
-    @GetMapping
-    suspend fun listUsers(
-        @RequestParam(defaultValue = "0") page: Int,
-        @RequestParam(defaultValue = "20") size: Int
-    ): Flow<UserDto> = userService.findAll(page, size).map { it.toDto() }
-
-    @GetMapping("/{id}")
-    suspend fun getUser(@PathVariable id: Long): ResponseEntity<UserDto> =
-        userService.findById(id)?.let { ResponseEntity.ok(it.toDto()) }
-            ?: ResponseEntity.notFound().build()
-
-    @PostMapping
-    suspend fun createUser(@Valid @RequestBody request: CreateUserRequest): ResponseEntity<UserDto> {
-        val user = userService.create(request)
-        return ResponseEntity.created(URI.create("/api/users/${user.id}")).body(user.toDto())
-    }
-}
-```
+WebFlux Controller: Annotate class with @RestController and @RequestMapping. Create suspend functions for endpoints with @GetMapping and @PostMapping. Return Flow for collections using map to convert entities. Return ResponseEntity with status codes. Use @Valid for request validation.
 
 ---
 
@@ -222,98 +63,24 @@ class UserController(private val userService: UserService) {
 
 ### Compose Multiplatform
 
-Shared UI Component:
-```kotlin
-@Composable
-fun UserListScreen(viewModel: UserListViewModel, onUserClick: (Long) -> Unit) {
-    val uiState by viewModel.uiState.collectAsState()
-
-    when (val state = uiState) {
-        is UiState.Loading -> LoadingIndicator()
-        is UiState.Success -> UserList(state.users, onUserClick)
-        is UiState.Error -> ErrorMessage(state.message, onRetry = viewModel::retry)
-    }
-}
-
-@Composable
-fun UserCard(user: User, onClick: () -> Unit) {
-    Card(
-        modifier = Modifier.fillMaxWidth().clickable(onClick = onClick),
-        elevation = CardDefaults.cardElevation(4.dp)
-    ) {
-        Row(modifier = Modifier.padding(16.dp)) {
-            AsyncImage(model = user.avatarUrl, contentDescription = user.name,
-                modifier = Modifier.size(48.dp).clip(CircleShape))
-            Spacer(Modifier.width(16.dp))
-            Column {
-                Text(user.name, style = MaterialTheme.typography.titleMedium)
-                Text(user.email, style = MaterialTheme.typography.bodySmall)
-            }
-        }
-    }
-}
-```
-
-### Testing with MockK
+Shared UI Component: Create @Composable function taking ViewModel and callback parameters. Collect uiState as state with collectAsState. Use when expression on sealed state to show different composables for Loading, Success, and Error.
 
-```kotlin
-class UserServiceTest {
-    private val userRepository = mockk<UserRepository>()
-    private val userService = UserService(userRepository)
+For list items, create Card composables with Modifier.fillMaxWidth and clickable. Use Row with padding, AsyncImage for avatars with CircleShape clip, and Column for text content with MaterialTheme.typography.
 
-    @Test
-    fun `should fetch user concurrently`() = runTest {
-        val testUser = User(1L, "John", "john@example.com")
-        coEvery { userRepository.findById(1L) } coAnswers { delay(100); testUser }
-
-        val result = userService.findById(1L)
-        assertThat(result).isEqualTo(testUser)
-    }
-
-    @Test
-    fun `should handle Flow emissions`() = runTest {
-        val users = listOf(User(1L, "John", "john@example.com"))
-        coEvery { userRepository.findAllAsFlow() } returns users.asFlow()
+### Testing with MockK
 
-        userService.streamUsers().toList().also { result ->
-            assertThat(result).hasSize(1)
-        }
-    }
-}
-```
+Create test class with mockk for dependencies. Initialize service with mock in declaration. Use @Test with runTest for coroutine tests. Use coEvery with coAnswers for async mocking with delay. Use assertThat for assertions. For Flow testing, use toList to collect emissions and assert on size and content.
 
 ### Gradle Build Configuration
 
-```kotlin
-plugins {
-    kotlin("jvm") version "2.0.20"
-    kotlin("plugin.serialization") version "2.0.20"
-    id("io.ktor.plugin") version "3.0.0"
-}
-
-kotlin { jvmToolchain(21) }
-
-dependencies {
-    implementation("io.ktor:ktor-server-core-jvm")
-    implementation("io.ktor:ktor-server-netty-jvm")
-    implementation("io.ktor:ktor-server-content-negotiation-jvm")
-    implementation("io.ktor:ktor-server-auth-jwt-jvm")
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
-    implementation("org.jetbrains.exposed:exposed-core:0.55.0")
-    implementation("org.jetbrains.exposed:exposed-dao:0.55.0")
-    implementation("org.postgresql:postgresql:42.7.3")
-
-    testImplementation("io.mockk:mockk:1.13.12")
-    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.9.0")
-    testImplementation("app.cash.turbine:turbine:1.1.0")
-}
-```
+Use plugins block with kotlin("jvm") and kotlin("plugin.serialization") with version strings. Add id for ktor.plugin. Configure kotlin block with jvmToolchain. In dependencies block, add ktor server modules, kotlinx coroutines, exposed modules, and postgresql driver. Add test dependencies for mockk, coroutines-test, and turbine.
 
 ---
 
 ## Context7 Integration
 
 Library mappings for latest documentation:
+
 - `/ktorio/ktor` - Ktor 3.0 server/client documentation
 - `/jetbrains/exposed` - Exposed SQL framework
 - `/JetBrains/kotlin` - Kotlin 2.0 language reference
@@ -321,20 +88,14 @@ Library mappings for latest documentation:
 - `/jetbrains/compose-multiplatform` - Compose Multiplatform
 - `/arrow-kt/arrow` - Arrow functional programming
 
-Usage:
-```python
-docs = await mcp__context7__get_library_docs(
-    context7CompatibleLibraryID="/ktorio/ktor",
-    topic="routing authentication jwt",
-    tokens=8000
-)
-```
+Usage: Call mcp__context7__get_library_docs with context7CompatibleLibraryID, topic string for specific areas, and tokens parameter for response size.
 
 ---
 
 ## When to Use Kotlin
 
 Use Kotlin When:
+
 - Developing Android applications (official language)
 - Building modern server applications with Ktor
 - Preferring concise, expressive syntax
@@ -343,6 +104,7 @@ Use Kotlin When:
 - Full Java interoperability required
 
 Consider Alternatives When:
+
 - Legacy Java codebase requiring minimal changes
 - Big data pipelines (prefer Scala with Spark)
 
@@ -360,23 +122,24 @@ Consider Alternatives When:
 
 ## Troubleshooting
 
-K2 Compiler: Add `kotlin.experimental.tryK2=true` to gradle.properties; clear `.gradle` for rebuild
+K2 Compiler: Add kotlin.experimental.tryK2=true to gradle.properties. Clear .gradle directory for full rebuild.
 
-Coroutines: Avoid `runBlocking` in suspend contexts; use `Dispatchers.IO` for blocking operations
+Coroutines: Avoid runBlocking in suspend contexts. Use Dispatchers.IO for blocking operations.
 
-Ktor: Ensure `ContentNegotiation` installed; check JWT verifier configuration; verify routing hierarchy
+Ktor: Ensure ContentNegotiation is installed. Check JWT verifier configuration. Verify routing hierarchy.
 
-Exposed: Ensure all DB operations in transaction; be aware of entity loading outside transaction
+Exposed: Ensure all DB operations run within transaction context. Be aware of lazy entity loading outside transactions.
 
 ---
 
 ## Advanced Documentation
 
 For comprehensive reference materials:
+
 - [reference.md](reference.md) - Complete ecosystem, Context7 mappings, testing patterns, performance
 - [examples.md](examples.md) - Production-ready code examples, Ktor, Compose, Android patterns
 
 ---
 
-Last Updated: 2025-12-07
-Status: Production Ready (v1.0.0)
+Last Updated: 2026-01-11
+Status: Production Ready (v1.1.0)