@coralai/sps-cli 0.41.2 → 0.43.0

package/skills/kotlin/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: kotlin
+description: Kotlin language skill — idioms, null safety, coroutines, testing. Covers JVM backend and Android. Pair with `backend` / `mobile` end skills and `coding-standards` for cross-language principles.
+origin: original
+---
+
+# Kotlin
+
+Null safety, coroutines, expressive stdlib. Used for JVM backend (Ktor, Spring) and Android. **Language-focused**.
+
+## When to load
+
+- Project primary language is Kotlin (JVM / Android / Multiplatform)
+- Reviewing Kotlin code
+- Coroutines / Flow / async design
+- Interop with Java (calling Java APIs, exposing Kotlin to Java)
+
+## Core principles
+
+1. **Nullability in the type system.** `String?` and `String` are different types; a `NullPointerException` in pure Kotlin code is almost always a mistake.
+2. **`val` by default, `var` only when mutation is required.**
+3. **Data classes for value objects.** `copy`, `equals`, `hashCode`, `toString` for free.
+4. **Prefer expressions over statements.** `if`, `when`, `try` all return values.
+5. **Sealed hierarchies over type codes.** Use `sealed class` / `sealed interface` + `when` with exhaustiveness.
+6. **Coroutines for async.** Never `Thread.sleep` or `.get()` on a `Future` in a coroutine.
+7. **No Java collections when Kotlin collections exist.** `List<T>` (Kotlin) is read-only; `MutableList<T>` is mutable.
+8. **`let` / `run` / `apply` / `also` / `with` — know the difference, don't chain all five.**
+
+## How to use references
+
+| Reference | When to load |
+|---|---|
+| [`references/idioms.md`](references/idioms.md) | Data classes, sealed classes, scope functions, extension fns, null safety |
+| [`references/coroutines.md`](references/coroutines.md) | `suspend`, `CoroutineScope`, structured concurrency, `Flow`, dispatchers |
+| [`references/testing.md`](references/testing.md) | JUnit 5, Kotest, MockK, turbine for Flow |
+
+## Forbidden patterns (auto-reject)
+
+- `!!` (force-unwrap) without a comment justifying it's definitely non-null
+- `lateinit var` for anything that isn't initialized by a framework (DI, test setup)
+- `runBlocking` in library or backend request-path code
+- `GlobalScope` — always use a structured `CoroutineScope`
+- `Thread.sleep` inside a `suspend` function
+- `println` for logging in production code
+- Returning Kotlin `List<T>` from an API that Java callers will treat as mutable (or vice versa)
+- `Object` singletons holding mutable state
+- `runCatching { }.getOrNull()` swallowing errors silently

package/skills/kotlin/references/coroutines.md

@@ -0,0 +1,240 @@
+# Kotlin — Coroutines
+
+`suspend`, scopes, dispatchers, `Flow`, cancellation. Structured concurrency is the model.
+
+## `suspend` functions
+
+A `suspend fun` is a function that can pause (free its thread) and resume later.
+
+```kotlin
+suspend fun fetchUser(id: String): User {
+    val raw = httpClient.get("/users/$id")
+    return User.fromJson(raw)
+}
+```
+
+Call from another `suspend` function or from a `CoroutineScope.launch { ... }`. You can't call them from a regular function without `runBlocking` (for main / tests only).
+
+## Structured concurrency
+
+Every coroutine runs in a `CoroutineScope`. When the scope is cancelled, all its children are cancelled. No orphan work.
+
+```kotlin
+coroutineScope {
+    val user = async { fetchUser(id) }
+    val prefs = async { fetchPrefs(id) }
+    render(user.await(), prefs.await())
+    // if either throws, the other is cancelled and the exception bubbles
+}
+```
+
+Rule: **no `GlobalScope.launch`, no bare `launch` at top level.** Attach every coroutine to a scope with a known lifecycle.
+
+## Dispatchers
+
+| Dispatcher | Use |
+|---|---|
+| `Dispatchers.Default` | CPU-bound work (limited to # of cores) |
+| `Dispatchers.IO` | Blocking I/O (file, network, blocking JDBC) |
+| `Dispatchers.Main` | UI thread (Android, JavaFX) |
+| `Dispatchers.Unconfined` | Rarely needed; tests and hacks |
+
+```kotlin
+suspend fun readFile(path: String): String =
+    withContext(Dispatchers.IO) { File(path).readText() }
+```
+
+Only switch dispatchers at boundaries. Don't spray `withContext(IO)` inside tight logic.
+
+## `coroutineScope` vs. `supervisorScope`
+
+```kotlin
+// coroutineScope: one failure cancels siblings (default)
+coroutineScope {
+    launch { critical1() }
+    launch { critical2() }
+}
+
+// supervisorScope: failures isolated
+supervisorScope {
+    launch { optional1() }   // if this fails, optional2 still runs
+    launch { optional2() }
+}
+```
+
+Default to `coroutineScope`. Use `supervisorScope` for independent tasks where one failure shouldn't kill the rest (e.g., background refreshes).
+
+## Cancellation
+
+Cancellation is cooperative. A coroutine is cancelled when:
+- Its scope is cancelled.
+- A structured sibling throws (in `coroutineScope`).
+- `cancel()` is called on its `Job`.
+
+`suspend` functions check cancellation at suspension points. CPU-heavy loops must opt in:
+
+```kotlin
+repeat(1_000_000) {
+    doWork()
+    yield()                   // or ensureActive()
+}
+```
+
+Handle `CancellationException`:
+```kotlin
+try {
+    doWork()
+} catch (e: CancellationException) {
+    // clean up, then RETHROW — don't swallow
+    throw e
+} catch (e: Exception) {
+    log.error("failed", e)
+}
+```
+
+**Swallowing `CancellationException` breaks the scope contract.** Always re-throw.
+
+## `async` / `await`
+
+For parallel computations that return values.
+
+```kotlin
+val (u, o) = coroutineScope {
+    val userD  = async { getUser(id) }
+    val ordsD  = async { getOrders(id) }
+    userD.await() to ordsD.await()
+}
+```
+
+Don't use `async { ... }.await()` back-to-back when you could just call the `suspend` function. That's sequential work dressed up as parallel.
+
+## Timeouts
+
+```kotlin
+withTimeout(5.seconds) {
+    slowOp()
+}                           // throws TimeoutCancellationException on timeout
+
+withTimeoutOrNull(5.seconds) {
+    slowOp()
+}                           // returns null on timeout
+```
+
+## `Flow` — asynchronous streams
+
+`Flow` is a cold async sequence. It doesn't run until collected.
+
+```kotlin
+fun tick(interval: Duration): Flow<Int> = flow {
+    var i = 0
+    while (currentCoroutineContext().isActive) {
+        emit(i++)
+        delay(interval)
+    }
+}
+
+scope.launch {
+    tick(1.seconds)
+        .map { it * 2 }
+        .filter { it > 10 }
+        .take(5)
+        .collect { println(it) }
+}
+```
+
+Operators (`map`, `filter`, etc.) return new Flows; `collect` is the terminal.
+
+### Cold vs. hot
+
+- **Cold** (`flow { }`, `flowOf`): starts fresh per collector.
+- **Hot** (`SharedFlow`, `StateFlow`): shared; values emitted regardless of collectors.
+
+Use `StateFlow` for "current value of X" (UI state). Use `SharedFlow` for events (broadcast). Use plain `Flow` for request/response.
+
+### Backpressure
+
+```kotlin
+flow.buffer(100)              // buffered producer
+flow.conflate()               // keep only latest
+flow.collectLatest { ... }    // cancel prior collector when new value arrives
+```
+
+## Channels
+
+One-shot or producer/consumer.
+
+```kotlin
+val channel = Channel<Job>(capacity = 100)
+launch {
+    for (job in channel) { process(job) }
+}
+channel.send(job)
+channel.close()
+```
+
+For most use cases, `Flow` is enough. Use `Channel` when you need direct send/receive semantics.
+
+## Exception handling
+
+Exceptions propagate up the structured-concurrency tree. The parent coroutine sees them at `.await()` or when children complete.
+
+```kotlin
+try {
+    coroutineScope {
+        launch { throwSomething() }
+    }
+} catch (e: SomeError) {
+    // caught here
+}
+```
+
+Install a `CoroutineExceptionHandler` on a `CoroutineScope` for top-level handlers (Android ViewModel, server main). Don't scatter try/catch inside coroutines.
+
+## `runBlocking` — only for `main` and tests
+
+Bridges blocking and suspending worlds. Inside a request handler or a library, `runBlocking` deadlocks threads. Don't.
+
+```kotlin
+fun main() = runBlocking {
+    myApp()
+}
+
+@Test fun test() = runBlocking {
+    assertEquals(5, add(2, 3))
+}
+```
+
+For tests, prefer `runTest` (from `kotlinx-coroutines-test`) — it virtualizes time.
+
+## `runTest` — deterministic async tests
+
+```kotlin
+@Test
+fun fetches() = runTest {
+    val result = fetchUser("u1")     // no real delay; virtual scheduler
+    assertEquals("u1", result.id)
+    advanceTimeBy(5.seconds)         // control time
+}
+```
+
+## Android-specific coroutine scopes
+
+- `viewModelScope` — cancels on `ViewModel.onCleared()`
+- `lifecycleScope` — cancels on lifecycle destroy
+- `repeatOnLifecycle(STARTED) { flow.collect { ... } }` — cancels on stop, resumes on start
+
+Never use `GlobalScope` or raw `Job()` from within a component with a defined lifecycle.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `GlobalScope.launch` | Attach to a scope with a known lifecycle |
+| `runBlocking` in request path / library code | Make the function `suspend` |
+| Swallowing `CancellationException` | Rethrow; scope relies on it |
+| `withContext(IO) { ... }` wrapping every line | Switch at I/O boundary only |
+| `async { x() }.await()` with no other work in parallel | Just call `x()` as a suspend fun |
+| `Thread.sleep` in `suspend fun` | Use `delay` |
+| `while (true) { doWork() }` with no yield | Add `yield()` / `ensureActive()` for cancellation |
+| `StateFlow` for events (drops duplicates) | Use `SharedFlow` for events |
+| Long-running Flow in `collect { ... }` on UI thread that blocks | `flowOn(Dispatchers.IO)` upstream |

package/skills/kotlin/references/idioms.md

@@ -0,0 +1,268 @@
+# Kotlin — Idioms
+
+Null safety, data classes, sealed classes, scope functions, extension functions.
+
+## `val` / `var` / `const val`
+
+```kotlin
+val name = "A"              // immutable reference
+var count = 0               // mutable
+const val MAX = 10          // compile-time constant (top-level or in `object`)
+```
+
+`val` by default. Reach for `var` only when you reassign.
+
+## Nullable types
+
+```kotlin
+var name: String? = null
+name.length                 // ❌ compile error
+name?.length                // Int? — null if name is null
+name!!.length               // throws NPE if null — avoid
+name ?: "unknown"           // Elvis: use default if null
+
+if (name != null) {
+    name.length             // smart-cast to String
+}
+```
+
+`!!` is a code smell. Every `!!` should have a comment saying why the value is guaranteed non-null there (and, ideally, a test that checks it).
+
+## Type inference
+
+```kotlin
+val n = 10                          // Int
+val s = "hi"                        // String
+val users: List<User> = fetch()     // annotate when intent is ambiguous
+```
+
+Annotate public API return types for clarity; let locals infer.
+
+## Data classes
+
+```kotlin
+data class User(val id: String, val email: String, val active: Boolean)
+
+val u = User("u1", "a@x.com", true)
+val updated = u.copy(email = "b@x.com")
+u == User("u1", "a@x.com", true)     // true — structural equality
+```
+
+Data classes give you `equals`, `hashCode`, `toString`, `copy`, destructuring for free.
+
+Don't use data classes for types with behaviour or invariants. If you need a factory or a validation step, make it a regular class with a private constructor + `companion object` factory.
+
+## Sealed classes — the Kotlin discriminated union
+
+```kotlin
+sealed class Result<out T> {
+    data class Ok<T>(val value: T) : Result<T>()
+    data class Err(val error: String) : Result<Nothing>()
+}
+
+fun handle(r: Result<User>) = when (r) {
+    is Result.Ok  -> use(r.value)
+    is Result.Err -> log(r.error)
+    // `when` is exhaustive — no else needed
+}
+```
+
+`sealed` limits subclasses to the same file (Kotlin < 1.5) or same module (1.5+).
+
+## `when` — the superior switch
+
+```kotlin
+val label = when (status) {
+    Status.Active   -> "active"
+    Status.Pending  -> "pending"
+    Status.Banned   -> "banned"
+}
+
+// Smart patterns
+val x = when {
+    n < 0       -> "neg"
+    n == 0      -> "zero"
+    n in 1..10  -> "small"
+    else        -> "big"
+}
+
+// With is + smart-cast
+when (v) {
+    is String -> v.length      // v: String
+    is Int    -> v + 1          // v: Int
+}
+```
+
+Exhaustive `when` over `sealed` / `enum` → no `else` required; the compiler forces you to update every branch when you add a case.
+
+## Scope functions — `let` / `run` / `apply` / `also` / `with`
+
+```kotlin
+user?.let { send(it) }                          // null-safe "do something with it"
+val formatted = user.run { "$name <$email>" }   // use members inside
+val req = Request().apply { url = x; timeout = 5 } // configure, return self
+list.also { log("about to sort: $it") }.sort()   // side effect, return self
+```
+
+| | Receiver | Returns |
+|---|---|---|
+| `let` | `it` | lambda result |
+| `run` | `this` | lambda result |
+| `apply` | `this` | receiver |
+| `also` | `it` | receiver |
+| `with(x)` | `this` | lambda result |
+
+Quick guide:
+- **Side effect, keep value** → `also`
+- **Configure a builder** → `apply`
+- **Null-safe transformation** → `let`
+- **Computation using members** → `run`
+
+Don't chain three+ scope functions — it gets confusing fast.
+
+## Extension functions
+
+Add methods to existing types without inheriting.
+
+```kotlin
+fun String.toSlug(): String = lowercase().replace(" ", "-")
+
+"Hello World".toSlug()      // "hello-world"
+```
+
+Rules:
+- Can't access private members; no reflection shortcuts.
+- Dispatch is static (by declared type, not runtime type) — don't use to "override" methods.
+- Place in a file named for the extended type (`StringExt.kt`) or feature (`Slug.kt`).
+
+## Destructuring
+
+```kotlin
+val (id, email) = user                   // positional, for data classes
+val (key, value) = map.entries.first()
+
+for ((i, x) in list.withIndex()) { ... }
+```
+
+Don't destructure too-far-apart fields; order becomes a secret convention.
+
+## Default & named arguments
+
+```kotlin
+fun send(to: String, subject: String, body: String = "", priority: Int = 0) { ... }
+
+send(to = "a@x.com", subject = "hi")
+send("a@x.com", "hi", priority = 1)
+```
+
+Prefer named args at call sites with 3+ params. Defaults obviate overload explosions.
+
+## Single-expression functions
+
+```kotlin
+fun double(x: Int) = x * 2
+fun greet(name: String): String = "hi $name"
+```
+
+Keep for functions that really fit on one line. Force explicit return type on public API.
+
+## Collection API
+
+```kotlin
+// Read-only vs mutable
+val immutable: List<Int> = listOf(1, 2, 3)
+val mutable: MutableList<Int> = mutableListOf(1, 2, 3)
+
+// Transformations
+users.filter { it.active }.map { it.email }
+users.groupBy { it.role }
+users.associateBy { it.id }          // Map<id, user>
+users.sortedBy { it.name }
+users.partition { it.active }        // Pair<active, inactive>
+
+// Aggregations
+users.count { it.active }
+users.sumOf { it.balance }
+users.maxByOrNull { it.age }
+```
+
+Chain 2–3 ops. Beyond that, break into named intermediate values or pull into a function.
+
+`asSequence()` for lazy evaluation over large collections:
+```kotlin
+users.asSequence().filter { ... }.map { ... }.take(10).toList()
+```
+
+## Ranges
+
+```kotlin
+1..10          // IntRange (inclusive)
+1 until 10     // IntRange 1..9 (exclusive upper)
+10 downTo 1    // reversed
+1..10 step 2   // 1, 3, 5, 7, 9
+```
+
+Prefer ranges over manual `for (i = ...; i < ...; i++)` — clearer intent.
+
+## String templates
+
+```kotlin
+val msg = "Hello $name, you have ${messages.size} messages"
+val raw = """
+    Multi-line
+    ${expression}
+    """.trimIndent()
+```
+
+No need for format strings in most cases.
+
+## Object expressions & declarations
+
+```kotlin
+// Singleton
+object Config {
+    val url = "https://api.example.com"
+}
+Config.url
+
+// Anonymous object
+val listener = object : Listener {
+    override fun onEvent(e: Event) { ... }
+}
+```
+
+Use `object` for singletons and one-off anonymous impls. Avoid `object` for mutable state — it's a global and hard to test.
+
+## `companion object`
+
+```kotlin
+class User private constructor(val id: String) {
+    companion object {
+        fun create(email: String): User = User(generateId(email))
+    }
+}
+
+User.create("a@x.com")
+```
+
+Factory methods, constants, static-like helpers live here.
+
+## Java interop essentials
+
+- `@JvmStatic` on `companion object` members to expose them as static methods to Java
+- `@JvmField` to expose a `val` / `var` as a Java field
+- `@JvmOverloads` to generate overloads for default params
+- Platform types (`String!`) — values from Java with unknown nullability; treat as non-null by convention OR check.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `!!` used as "I promise this isn't null" | Restructure so the type proves it; or check and handle |
+| `lateinit` in application code | Use `by lazy { ... }` or pass via constructor |
+| `Unit`-returning function ending with `return Unit` | Implicit; remove |
+| `if-else` chain where `when` is clearer | Use `when` |
+| `var x: List<T> = mutableListOf()` — type vs reality mismatch | Pick one: `val x: MutableList<T>` or use `+` for new lists |
+| Data class used for behaviour-heavy type | Regular class; keep data classes for values |
+| Extension functions that hide bugs (subtle override attempts) | Extension dispatch is static; don't rely on polymorphism |
+| `companion object` holding request-scoped state | Request scope belongs on a request-scoped object |