@coralai/sps-cli 0.42.0 → 0.43.0

package/skills/kotlin/references/testing.md

@@ -0,0 +1,219 @@
+# Kotlin — Testing
+
+JUnit 5, Kotest, MockK, turbine for Flow. For TDD, see `coding-standards/references/tdd.md`.
+
+## Runner choice — JUnit 5 is the default
+
+Fine for most projects. Kotest is a Kotlin-first alternative with extra styles (BehaviorSpec, FunSpec) — pick one per project and be consistent.
+
+```kotlin
+// JUnit 5
+import org.junit.jupiter.api.Test
+import kotlin.test.assertEquals
+
+class UserServiceTest {
+    @Test
+    fun `creates user with generated id`() {
+        val svc = UserService(InMemoryUserRepo())
+        val u = svc.create("a@x.com")
+        assertEquals("a@x.com", u.email)
+    }
+}
+```
+
+Backtick-quoted function names are standard Kotlin test style — they read as behaviour statements.
+
+## Assertions
+
+- `kotlin.test.*` for cross-platform (`assertEquals`, `assertTrue`, `assertFailsWith`).
+- `AssertJ` (Java) for rich fluent asserts.
+- `Kotest assertions` (`shouldBe`, `shouldHaveSize`) if you've adopted Kotest.
+
+```kotlin
+// kotlin.test
+assertEquals(5, add(2, 3))
+assertFailsWith<ValidationError> { validate(bad) }
+
+// AssertJ
+assertThat(users).hasSize(3).extracting("email").contains("a@x.com")
+
+// Kotest
+user.name shouldBe "A"
+users shouldHaveSize 3
+```
+
+Pick one assertion library per project. Mixing creates friction.
+
+## Parameterized tests
+
+```kotlin
+@ParameterizedTest
+@CsvSource("1,2,3", "0,0,0", "-1,1,0")
+fun `add`(a: Int, b: Int, expected: Int) {
+    assertEquals(expected, add(a, b))
+}
+
+@ParameterizedTest
+@MethodSource("cases")
+fun `login cases`(c: LoginCase) { ... }
+
+companion object {
+    @JvmStatic
+    fun cases() = listOf(
+        LoginCase("a@x.com", "pw", true),
+        LoginCase("", "pw", false),
+    )
+}
+```
+
+Kotest syntax is lighter:
+```kotlin
+"add" - {
+    withData(
+        nameFn = { "${it.a} + ${it.b}" },
+        Triple(1, 2, 3), Triple(0, 0, 0)
+    ) { (a, b, want) -> add(a, b) shouldBe want }
+}
+```
+
+## Mocking — MockK
+
+MockK is Kotlin-idiomatic (final classes work out of the box; Mockito needs extra config).
+
+```kotlin
+import io.mockk.*
+
+val repo = mockk<UserRepository>()
+every { repo.find("u1") } returns User("u1", "a@x.com")
+every { repo.find(not("u1")) } returns null
+
+val svc = UserService(repo)
+assertEquals("a@x.com", svc.getEmail("u1"))
+
+verify(exactly = 1) { repo.find("u1") }
+```
+
+Coroutine mocks:
+```kotlin
+val svc = mockk<UserService>()
+coEvery { svc.fetch("u1") } returns User("u1", "a@x.com")
+coVerify { svc.fetch("u1") }
+```
+
+`relaxed = true` makes all unconfigured calls return defaults. Use sparingly — silent defaults mask bugs.
+
+## Prefer fakes over mocks
+
+```kotlin
+class InMemoryUserRepo : UserRepository {
+    private val users = mutableMapOf<String, User>()
+    override fun find(id: String) = users[id]
+    override fun save(u: User) { users[u.id] = u }
+}
+```
+
+Reuse across tests; reset in `@BeforeEach`. More code up front; much less friction when the interface grows.
+
+## Coroutine tests — `runTest`
+
+```kotlin
+import kotlinx.coroutines.test.runTest
+
+@Test
+fun fetches() = runTest {
+    val svc = UserService(fakeRepo)
+    val u = svc.fetchUser("u1")             // no real delay
+    assertEquals("u1", u.id)
+}
+```
+
+`runTest` virtualizes time. `delay(1.hours)` completes instantly. `advanceTimeBy(...)` controls the scheduler.
+
+## `Flow` tests — turbine
+
+```kotlin
+import app.cash.turbine.test
+
+@Test
+fun `flow emits expected values`() = runTest {
+    viewModel.state.test {
+        assertEquals(State.Loading, awaitItem())
+        viewModel.load()
+        assertEquals(State.Success(user), awaitItem())
+        cancelAndIgnoreRemainingEvents()
+    }
+}
+```
+
+Don't test Flows by collecting into a list in an uncontrolled scope — tests become flaky.
+
+## Integration tests
+
+- **JVM backend**: real DB via Testcontainers; real HTTP via Ktor client or `MockWebServer`.
+- **Android**: instrumented tests (`androidx.test`), or local-JVM Robolectric for fast feedback.
+
+```kotlin
+@Test
+fun `loads user from real db`() = runTest {
+    Testcontainers.start("postgres:16")
+    val repo = JdbcUserRepository(dataSource)
+    repo.save(User("u1", "a@x.com"))
+    assertEquals("a@x.com", repo.find("u1")?.email)
+}
+```
+
+Keep integration tests in a separate source set (`src/integrationTest/`) with its own Gradle task — `./gradlew integrationTest`.
+
+## Android UI tests
+
+- **Jetpack Compose**: `createComposeRule()`, `onNodeWithText(...).performClick()`.
+- **Views**: Espresso.
+
+```kotlin
+@get:Rule
+val compose = createComposeRule()
+
+@Test
+fun `shows user name`() {
+    compose.setContent { UserCard(user = sampleUser) }
+    compose.onNodeWithText("Alice").assertIsDisplayed()
+}
+```
+
+## Code coverage
+
+JaCoCo for JVM / Android. See `coding-standards/references/tdd.md` for target numbers.
+
+```kotlin
+// build.gradle.kts
+plugins { jacoco }
+tasks.test { finalizedBy(tasks.jacocoTestReport) }
+```
+
+## Property tests — Kotest property API
+
+```kotlin
+import io.kotest.property.*
+import io.kotest.property.arbitrary.*
+
+"sort is idempotent" - {
+    checkAll(Arb.list(Arb.int())) { xs ->
+        xs.sorted() shouldBe xs.sorted().sorted()
+    }
+}
+```
+
+Great for parsers, serializers, invariants.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `Thread.sleep` in coroutine tests | `delay` + `runTest` |
+| `runBlocking` in tests of suspend functions | `runTest` virtualizes time |
+| Over-mocking (10 mocks for 20 LOC) | Use a fake |
+| `verify { ... }` counts that duplicate the mock setup | Assert observable behaviour instead |
+| Snapshot tests for flaky output (time, UUID) | Inject fakes / fixed values |
+| Tests that depend on coroutine ordering | Use `runTest` scheduler primitives, not real threads |
+| Real network in unit tests | Fake the HTTP client or use `MockWebServer` |
+| Test name like `test1`, `test2` | Describe behaviour: \`\`add combines positives\`\` |

package/skills/mobile/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: mobile
+description: Mobile end skill — architecture, offline-first, state, performance, lifecycle. Platform-neutral (iOS / Android / cross-platform). Pair with a language skill (`swift` / `kotlin` / `typescript`) and `coding-standards`.
+origin: original
+---
+
+# Mobile
+
+Native and cross-platform mobile app architecture. **Platform-neutral**; load with a language skill for syntax and a framework perspective.
+
+## When to load
+
+- Native iOS (Swift + UIKit / SwiftUI) or Android (Kotlin + Jetpack Compose / Views)
+- Cross-platform: React Native, Flutter, Kotlin Multiplatform, .NET MAUI
+- Hybrid: Capacitor, Cordova
+- Topics: lifecycle, offline, state, navigation, platform APIs, app size, battery
+
+## Core principles
+
+1. **Lifecycle is the tax.** Your app gets suspended, killed, restored — design for it, don't pretend it's a desktop.
+2. **Offline is the default.** The network is bad, intermittent, or absent. Degrade gracefully.
+3. **Screens are ephemeral; state persists.** Recreate UI from state on re-entry.
+4. **One source of truth per piece of data.** Caches reconcile with server truth; UIs reflect the cache.
+5. **Trim aggressively.** Every 1 MB costs downloads and disk. Every dep adds attack surface and supply risk.
+6. **Respect the user's battery and data.** Background work is a privilege; schedule wisely.
+7. **Accessibility is platform-native.** Use TalkBack / VoiceOver primitives, not custom read-aloud.
+8. **Test on a low-end device with slow network.** "Works on latest iPhone" is not a release signal.
+
+## How to use references
+
+| Reference | When to load |
+|---|---|
+| [`references/architecture.md`](references/architecture.md) | MVVM / MVI / TCA / clean architecture, DI, module boundaries |
+| [`references/state-and-data.md`](references/state-and-data.md) | Local store, sync, offline-first, optimistic updates, reactive streams |
+| [`references/navigation.md`](references/navigation.md) | Stack, tab, modal, deep links, universal links, back-stack |
+| [`references/performance.md`](references/performance.md) | Startup, frame rate, memory, battery, app size |
+| [`references/platform.md`](references/platform.md) | Permissions, notifications, background tasks, biometrics, crypto / keychain |
+
+## Forbidden patterns (auto-reject)
+
+- Blocking the UI thread (network, disk, JSON parse) in the request path
+- Storing secrets / tokens in `UserDefaults` / `SharedPreferences` — use Keychain / Keystore
+- `Thread.sleep` / `Thread.sleep(...)` in UI code
+- Manual lifecycle handling in modern frameworks (use `ViewModel` / `StateObject` / scoped observers)
+- Global mutable singletons for business data
+- Hard-coded base URLs in release builds
+- Silent swallow of network errors (no indicator, no retry)
+- Unbounded in-memory caches (OOM kills)
+- Hitting `/me` on every screen (fetch once, cache, invalidate on write)
+- "Reload the world" after any change (no delta / optimistic update)

package/skills/mobile/references/architecture.md

@@ -0,0 +1,204 @@
+# Mobile — Architecture
+
+MVVM, MVI, TCA, clean architecture. Platform-neutral.
+
+## The shapes
+
+| Pattern | Idea | Good for |
+|---|---|---|
+| **MVVM** | View ← binds → ViewModel → Model | SwiftUI, Jetpack Compose, most modern apps |
+| **MVI** | View → Intent → Reducer → State → View | Deterministic, testable flows; complex screens |
+| **TCA** (iOS) | Redux-like, dependency-injected | Teams that want explicit wiring everywhere |
+| **Clean / Onion** | Layers; domain in the middle | Large apps with multiple teams |
+
+Most apps today land on MVVM + unidirectional data flow. MVI is MVVM with explicit state / intent naming. Pick one per project.
+
+## Layering (clean-ish)
+
+```
+┌──────────────────────────────────────────┐
+│  UI (screens, components)                 │   — platform-specific
+├──────────────────────────────────────────┤
+│  Presentation (ViewModels / Stores)      │   — state + actions
+├──────────────────────────────────────────┤
+│  Domain (entities, use cases)             │   — pure, platform-free
+├──────────────────────────────────────────┤
+│  Data (repositories + sources: API, DB)  │   — infrastructure
+└──────────────────────────────────────────┘
+```
+
+- **UI** calls into the ViewModel; ViewModel calls into use cases / repos.
+- **Domain** has no Android / iOS imports. Shareable across platforms.
+- **Data** implements the interfaces the Domain declares.
+
+Like `backend/layering.md`: dependency flows inward. Don't let `Context` / `UIApplication` leak into domain code.
+
+## ViewModel — owner of screen state
+
+```
+ViewModel:
+    state: observable<ScreenState>
+
+    onIntent(Intent):
+        match intent:
+            case .load:    state = .loading; launch { fetchUser() }
+            case .retry:   state = .loading; launch { fetchUser() }
+            case .select(id): navigator.push(Detail(id))
+```
+
+Responsibilities:
+- Own the screen's state
+- Talk to use cases / repos
+- Translate user input into state changes
+- Survive configuration changes (rotation, dark mode) — framework handles if you use the right scope
+
+NOT responsibilities:
+- Drawing pixels
+- Navigating directly (use a navigator / router)
+- Accessing platform APIs directly (get them via DI)
+
+## Unidirectional data flow
+
+```
+  User action ────▶ Intent ────▶ ViewModel ────▶ State
+         ▲                                        │
+         └────────────────────────────────────────┘
+                        View observes
+```
+
+- Views are a function of state. Don't mutate state inside views.
+- Intents are explicit. Don't let the view call arbitrary business logic.
+- State changes are traceable (log the intent) for debugging.
+
+## Dependency injection
+
+Every non-trivial app uses DI. Options vary by platform:
+
+| Platform | Common choices |
+|---|---|
+| Android | Hilt, Koin, manual constructor injection |
+| iOS | Swinject, @Environment, manual |
+| Cross-platform (KMP / RN) | Manual / small DI libs |
+
+Prefer constructor injection; simpler, testable.
+
+Anti-pattern: service locator / global accessor. They hide deps and make testing painful.
+
+## Modularization
+
+As the app grows, split by feature (not by layer):
+
+```
+app/
+├── feature-auth/
+│   ├── domain/    presentation/    data/
+├── feature-orders/
+│   ├── domain/    presentation/    data/
+├── feature-profile/
+├── shared/
+│   ├── ui/        network/        persistence/
+└── app-shell/              # wires features together, navigation root
+```
+
+Benefits:
+- Parallel team work.
+- Faster incremental builds.
+- Forces clean interfaces between features.
+
+Over-modularization before the app needs it is friction. Start single-module; split when team size or build time hurts.
+
+## Use cases
+
+A use case is one screen's intent: `GetUserProfile`, `PlaceOrder`, `LogOut`.
+
+```
+class PlaceOrder(
+    val orderRepo: OrderRepository,
+    val paymentGateway: PaymentGateway,
+    val analytics: Analytics,
+) {
+    suspend fun invoke(cmd: PlaceOrderCommand): Result<OrderId> {
+        val order = Order.create(cmd)                   // domain rule
+        orderRepo.save(order)
+        paymentGateway.authorize(order.total)
+        analytics.track("order_placed", order.id)
+        return Result.success(order.id)
+    }
+}
+```
+
+Small, one method, testable. Don't force every screen to go through a use case — if it's just loading data, call the repo from the ViewModel.
+
+## Repository — hides the data sources
+
+```
+interface UserRepository {
+    suspend fun get(id: String): User                    // hits cache, falls back to API
+    suspend fun refresh(id: String): User                // forces network
+    fun observe(id: String): Flow<User>                  // reactive stream
+}
+```
+
+Inside:
+- Local store (Room / SwiftData / Realm / SQLite).
+- Remote source (HTTP client).
+- Reconciliation logic (cache + network).
+
+Consumers don't know or care. That's the point.
+
+## Error surfacing
+
+Domain errors → enum / sealed type that the ViewModel maps to UI state.
+
+```
+sealed class OrderError {
+    object InsufficientFunds : OrderError()
+    object OutOfStock        : OrderError()
+    data class Network(val cause: Throwable) : OrderError()
+    data class Unknown(val cause: Throwable) : OrderError()
+}
+
+state = State.Error(OrderError.InsufficientFunds)
+// UI: show a dialog with specific copy + action
+```
+
+Never show a raw exception message to the user. Map to something actionable.
+
+## Coroutine / async scoping
+
+- Android: `viewModelScope`, `lifecycleScope`.
+- iOS Swift: `Task`, tied to view lifecycle or `@StateObject`.
+- React Native: effects tied to component lifecycle; clean up on unmount.
+- Flutter: `dispose()` on `StatefulWidget`; `Stream` subscriptions cancelled.
+
+Don't start work that outlives the scope. Leaked background tasks cause crashes, stale state, wasted battery.
+
+## Feature flags
+
+Every mobile release is "all or nothing" for some hours. Feature flags let you ship code dark and flip when ready.
+
+- Client flag service (LaunchDarkly, ConfigCat, home-grown).
+- Defaults that are safe if the service is unreachable (offline start).
+- Short-lived; clean up flags once fully rolled out.
+
+## Telemetry hooks
+
+- App open, session start/end
+- Screen viewed (one event per meaningful screen; don't inflate)
+- Intent triggered (for key flows — signup, checkout)
+- Error happened (with anonymous context; never PII)
+
+Ship to a pipeline (Firebase Analytics, Segment, MixPanel, self-hosted) with a schema you control.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Business logic in view files | Move to ViewModel / use case |
+| ViewModel holds a `Context` / `UIViewController` reference | Leaks UI into presentation; refactor |
+| Singleton "service" with mutable business data | DI via constructor; scope to a request or screen |
+| Navigation logic scattered across screens | Navigator / router at app level |
+| Each screen fetches `/me` on start | Cache; fetch once, invalidate on logout / update |
+| Data layer throws raw SQL exceptions to the UI | Repository maps to domain errors |
+| Feature modules depending on each other arbitrarily | Feature modules depend on `shared/`; never on siblings |
+| "Reactive Everywhere" — observable every primitive | Use streams for state that changes; keep static state static |

package/skills/mobile/references/navigation.md

@@ -0,0 +1,158 @@
+# Mobile — Navigation
+
+Stack, tabs, modals, deep links, universal / app links.
+
+## Core model
+
+Mobile navigation is a stack (usually multiple, one per tab). The user always has:
+- A clear back action (system or in-app).
+- An understanding of where they are (title, breadcrumb, tab highlight).
+- A way to exit / cancel a flow.
+
+## Stack
+
+```
+Root ─▶ List ─▶ Detail ─▶ Edit ─▶ Confirmation
+                  ▲
+                  └── back returns here, not to List
+```
+
+Rules:
+- **Keep stacks shallow.** 4+ levels usually means you should bring the user back to a root or use a modal.
+- **Clear the stack after destructive flows** (signup complete, logout, delete-account).
+- **Don't insert navigation into the middle** (teleports jarring to users).
+
+## Tabs
+
+Top-level categories — don't abuse. Rule of thumb: 3–5 tabs max.
+
+- Each tab has its own stack.
+- Switching tabs preserves per-tab state (position in list, scroll).
+- Re-selecting the active tab scrolls to top (standard iOS / Android behavior).
+
+## Modals
+
+Use for tasks that are:
+- Focused (one clear goal).
+- Interruptible (user can cancel).
+- Temporary (they don't want to return here later).
+
+```
+[ Close ]    Edit profile              [ Save ]
+```
+
+Don't use modals for content the user needs to return to. A profile page isn't a modal; editing the profile is.
+
+Bottom sheets / partial modals are modals too. Same rules.
+
+## Deep links
+
+Every route should be addressable by URL.
+
+```
+myapp://orders/123
+https://example.com/orders/123
+```
+
+- **Custom scheme** (`myapp://`) — older; still used for some flows.
+- **Universal links (iOS) / App links (Android)** — modern; open the app if installed, fall back to web otherwise. Required for secure flows.
+
+Setup is fiddly:
+- iOS: `apple-app-site-association` file, `associatedDomains` entitlement.
+- Android: intent filters + Digital Asset Links.
+
+Test with scanner tools (`branch.io` validator, `assetlinks.google.com/tools`).
+
+## Back-stack hydration
+
+When the user lands via a deep link, the back stack should reflect the path they'd have if they navigated manually.
+
+```
+Link: /orders/123/items/7
+
+# ❌ back pops out of the app
+[ items/7 ]
+
+# ✅ back goes to the logical parent
+[ root ] ─▶ [ orders ] ─▶ [ order 123 ] ─▶ [ item 7 ]
+```
+
+Build the stack when resolving the link; don't leave the user stuck.
+
+## Navigation state is your state
+
+Declarative navigation (Compose Navigation, SwiftUI `NavigationStack`, React Navigation) treats the route as a data structure. Restore on cold start by persisting and rehydrating.
+
+```
+state = [ Home, Orders, Order(id=123) ]
+// on process death, serialize; on cold start, rehydrate
+```
+
+Imperative navigation (push/pop calls) is harder to persist. Prefer declarative in new apps.
+
+## Passing data between screens
+
+Options, in order of preference:
+
+1. **Route params** (IDs only). `order/123`. Serializable, deep-linkable.
+2. **Shared ViewModel / store**. The source of truth lives in one place.
+3. **Nav callbacks** (for single-screen outcomes: "picker returns a country"). Keep narrow.
+4. **Serialized object in the route** — last resort; breaks if the model changes.
+
+Don't pass live objects / closures across screens; the framework can't restore them after process death.
+
+## Tabs + deep links
+
+Deep link lands on a tab and a stack within that tab:
+
+```
+/profile/settings    ─▶  tab=Profile, stack=[Profile, Settings]
+/cart                ─▶  tab=Cart, stack=[Cart]
+```
+
+Set the tab, then restore the stack, in one atomic transition.
+
+## Transitions
+
+- **Native** where available (push / pop, modal present). Users recognize the motion.
+- **Custom** only for brand moments. Custom transitions are slow to build and often feel off on other devices.
+- Respect `prefers-reduced-motion` — reduce or skip animations.
+
+## Bottom navigation vs. side drawer
+
+- **Bottom nav** (mobile-native, iOS tabs / Android BottomNavigationView): 3–5 top-level items, always visible.
+- **Side drawer** (hamburger): de-emphasized items, usable with one hand awkward, often hurts discoverability.
+
+Bottom nav by default. Drawer for overflow or very large navigation sets.
+
+## Back button (Android) and gestures
+
+- **Android hardware/system back**: must work everywhere. Never block.
+- **iOS swipe-back**: enabled by default on navigation stacks; don't disable without reason.
+- **Android predictive back** (13+): opt in via `BackInvokedCallback` to show a preview.
+
+Handle in-flow back (dismiss modal, close keyboard, confirm-before-exit for unsaved data).
+
+## Sign-out / session expiry
+
+On logout or token revocation:
+1. Clear secure storage (tokens, keys, cached user).
+2. Wipe in-memory state.
+3. Reset navigation to the auth / onboarding root.
+4. Cancel any in-flight requests / subscriptions.
+
+Skipping step 3 leaves the user on a logged-in screen with no data — confusing.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Deep link lands on a screen with no back stack | Hydrate the full path |
+| Complex data serialized into the URL | Pass an ID; fetch from source |
+| 8-tab bottom nav | Consolidate; use "More" or search |
+| Modal pushing another modal pushing another | Rethink the flow |
+| Blocking system back | Always respond; ask if truly destructive |
+| Navigation in `useEffect` during render | Navigate on user action or in route loader |
+| Different bottom nav per screen | Confusing; top-level navigation should be stable |
+| Losing form state on rotation / background | Persist draft to local store |
+| "Back" that goes forward (resets to root) | Match user expectation of "previous" |