@coralai/sps-cli 0.55.13 → 0.56.0

package/skills/kotlin/SKILL.md

@@ -1,47 +0,0 @@
----
-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

@@ -1,240 +0,0 @@
-# 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

@@ -1,268 +0,0 @@
-# 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 |