android-sdd 1.0.0

package/skills/Dependency Injection/Hilt/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: hilt
+description: >
+  Hilt dependency injection setup and patterns for Android.
+  Load this skill when setting up Hilt, defining modules, injecting into
+  Android components, scoping dependencies, or providing third-party libraries.
+---
+
+# Hilt
+
+## Overview
+Hilt is Android's recommended DI framework built on top of Dagger. It reduces Dagger boilerplate by providing standard components and scopes for Android classes. Hilt generates DI code at compile time — no reflection, no runtime overhead.
+
+---
+
+## Core Principles
+
+- **One scope per lifetime** — match dependency scope to its actual lifetime
+- Never inject into constructors of Android framework classes — use `@Inject` on fields or use Hilt entry points
+- Prefer **constructor injection** over field injection everywhere possible
+- Modules provide dependencies the constructor can't — third-party libs, interfaces, context-dependent types
+- **`@Singleton`** is application-scoped — use sparingly, only for truly shared state
+
+---
+
+## Setup
+
+```toml
+[versions]
+hilt = "2.51.1"
+
+[libraries]
+hilt-android         = { module = "com.google.dagger:hilt-android", version.ref = "hilt" }
+hilt-compiler        = { module = "com.google.dagger:hilt-compiler", version.ref = "hilt" }
+hilt-navigation-compose = { module = "androidx.hilt:hilt-navigation-compose", version = "1.2.0" }
+
+[plugins]
+hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
+```
+
+```kotlin
+// build.gradle.kts (root)
+plugins {
+    alias(libs.plugins.hilt) apply false
+}
+
+// build.gradle.kts (app)
+plugins {
+    alias(libs.plugins.hilt)
+    alias(libs.plugins.ksp)
+}
+
+dependencies {
+    implementation(libs.hilt.android)
+    ksp(libs.hilt.compiler)
+    implementation(libs.hilt.navigation.compose)
+}
+```
+
+```kotlin
+// ✅ Application class — required
+@HiltAndroidApp
+class MyApplication : Application()
+```
+
+---
+
+## Constructor Injection
+
+```kotlin
+// ✅ Preferred — inject via constructor
+class UserRepository @Inject constructor(
+    private val userDao: UserDao,
+    private val userApi: UserApi,
+    private val mapper: UserMapper
+) {
+    // Hilt provides all dependencies automatically
+}
+
+class UserMapper @Inject constructor() {
+    fun toDomain(entity: UserEntity): User = TODO()
+}
+
+// ✅ ViewModel — use @HiltViewModel
+@HiltViewModel
+class UserListViewModel @Inject constructor(
+    private val repository: UserRepository,
+    private val savedStateHandle: SavedStateHandle
+) : ViewModel()
+```
+
+---
+
+## Hilt Modules
+
+```kotlin
+// ✅ @Module + @InstallIn — provides dependencies Hilt can't construct automatically
+
+// Singleton module — app-scoped dependencies
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+
+    @Provides
+    @Singleton
+    fun provideOkHttpClient(): OkHttpClient =
+        OkHttpClient.Builder()
+            .connectTimeout(30, TimeUnit.SECONDS)
+            .build()
+
+    @Provides
+    @Singleton
+    fun provideRetrofit(okHttpClient: OkHttpClient): Retrofit =
+        Retrofit.Builder()
+            .baseUrl("https://api.example.com/")
+            .client(okHttpClient)
+            .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
+            .build()
+
+    @Provides
+    @Singleton
+    fun provideUserApi(retrofit: Retrofit): UserApi =
+        retrofit.create(UserApi::class.java)
+}
+
+@Module
+@InstallIn(SingletonComponent::class)
+object DatabaseModule {
+
+    @Provides
+    @Singleton
+    fun provideDatabase(@ApplicationContext context: Context): AppDatabase =
+        Room.databaseBuilder(context, AppDatabase::class.java, "app_db")
+            .addMigrations(MIGRATION_1_2)
+            .build()
+
+    @Provides
+    fun provideUserDao(database: AppDatabase): UserDao = database.userDao()
+
+    @Provides
+    fun provideOrderDao(database: AppDatabase): OrderDao = database.orderDao()
+}
+```
+
+---
+
+## Binding Interfaces
+
+```kotlin
+// ✅ Bind interface to implementation
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class RepositoryModule {
+
+    @Binds
+    @Singleton
+    abstract fun bindUserRepository(
+        impl: UserRepositoryImpl
+    ): UserRepository
+
+    @Binds
+    abstract fun bindAnalytics(
+        impl: FirebaseAnalyticsImpl
+    ): Analytics
+}
+
+// ✅ @Binds is more efficient than @Provides for interface binding
+// Use @Provides only when you need to call a constructor or factory
+```
+
+---
+
+## Scopes
+
+```kotlin
+// ✅ Scope reference
+@Singleton           // lives as long as Application
+@ActivityRetainedScoped  // lives as long as ViewModel (survives rotation)
+@ActivityScoped      // lives as long as Activity
+@FragmentScoped      // lives as long as Fragment
+@ViewScoped          // lives as long as View
+@ServiceScoped       // lives as long as Service
+
+// ✅ Example — screen-level scope
+@Module
+@InstallIn(ActivityRetainedComponent::class)
+object CartModule {
+
+    @Provides
+    @ActivityRetainedScoped
+    fun provideCart(): ShoppingCart = ShoppingCart()
+}
+```
+
+---
+
+## Qualifiers
+
+```kotlin
+// ✅ Distinguish multiple bindings of the same type
+@Qualifier
+@Retention(AnnotationRetention.BINARY)
+annotation class AuthInterceptorOkHttpClient
+
+@Qualifier
+@Retention(AnnotationRetention.BINARY)
+annotation class LoggingInterceptorOkHttpClient
+
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+
+    @Provides
+    @Singleton
+    @AuthInterceptorOkHttpClient
+    fun provideAuthOkHttpClient(authInterceptor: AuthInterceptor): OkHttpClient =
+        OkHttpClient.Builder()
+            .addInterceptor(authInterceptor)
+            .build()
+
+    @Provides
+    @Singleton
+    @LoggingInterceptorOkHttpClient
+    fun provideLoggingOkHttpClient(): OkHttpClient =
+        OkHttpClient.Builder()
+            .addInterceptor(HttpLoggingInterceptor())
+            .build()
+}
+
+// ✅ Using qualifier at injection site
+class UserRepository @Inject constructor(
+    @AuthInterceptorOkHttpClient private val okHttpClient: OkHttpClient
+)
+```
+
+---
+
+## Injecting Into Android Components
+
+```kotlin
+// ✅ Activity
+@AndroidEntryPoint
+class MainActivity : ComponentActivity() {
+    // Field injection (only when constructor injection is impossible)
+    @Inject lateinit var analytics: Analytics
+}
+
+// ✅ Fragment
+@AndroidEntryPoint
+class UserFragment : Fragment() {
+    private val viewModel: UserViewModel by viewModels()
+}
+
+// ✅ Compose — hiltViewModel()
+@Composable
+fun UserScreen(
+    viewModel: UserViewModel = hiltViewModel()
+) { ... }
+
+// ✅ WorkManager
+@HiltWorker
+class SyncWorker @AssistedInject constructor(
+    @Assisted context: Context,
+    @Assisted params: WorkerParameters,
+    private val syncEngine: SyncEngine
+) : CoroutineWorker(context, params) {
+    override suspend fun doWork(): Result = TODO()
+}
+```
+
+---
+
+## Entry Points (Non-Hilt Classes)
+
+```kotlin
+// ✅ Access Hilt graph from non-Hilt class (e.g., ContentProvider, custom View)
+@EntryPoint
+@InstallIn(SingletonComponent::class)
+interface UserRepositoryEntryPoint {
+    fun userRepository(): UserRepository
+}
+
+// Usage
+val entryPoint = EntryPointAccessors.fromApplication(
+    context.applicationContext,
+    UserRepositoryEntryPoint::class.java
+)
+val repository = entryPoint.userRepository()
+```
+
+---
+
+## Testing with Hilt
+
+```kotlin
+// ✅ Replace module in tests
+@HiltAndroidTest
+class UserRepositoryTest {
+
+    @get:Rule
+    val hiltRule = HiltAndroidRule(this)
+
+    @Inject
+    lateinit var repository: UserRepository
+
+    @Before
+    fun setUp() { hiltRule.inject() }
+
+    @Test
+    fun testGetUsers() { TODO() }
+}
+
+// ✅ Replace a binding for tests
+@UninstallModules(NetworkModule::class)
+@HiltAndroidTest
+class FakeNetworkTest {
+
+    @Module
+    @InstallIn(SingletonComponent::class)
+    object FakeNetworkModule {
+        @Provides
+        fun provideUserApi(): UserApi = FakeUserApi()
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Field injection (`@Inject lateinit var`) in non-Android classes — use constructor injection
+- `@Singleton` on everything — wastes memory, creates hidden shared state
+- Putting business logic in Hilt modules — modules only provide/bind, no logic
+- Injecting `Context` directly — use `@ApplicationContext` or `@ActivityContext`
+- Using `ServiceLocator` pattern alongside Hilt — pick one
+- Circular dependencies — redesign with interfaces or lazy injection
+
+---
+
+## Related Skills
+- `dagger` — Dagger internals when Hilt isn't sufficient
+- `koin` — alternative DI framework
+- `annotation-processing` — KSP setup for Hilt code generation
+- `viewmodel` — @HiltViewModel pattern
+- `workmanager` — @HiltWorker setup

package/skills/Dependency Injection/Koin/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: koin
+description: >
+  Koin dependency injection setup and patterns for Android and KMP.
+  Load this skill when working on a project that uses Koin, setting up
+  modules, injecting into Android components, or using Koin in KMP projects.
+---
+
+# Koin
+
+## Overview
+Koin is a lightweight DI framework for Kotlin. Unlike Dagger/Hilt, Koin is a service locator at runtime — no code generation, no annotation processing. It's simpler to set up and KMP-compatible. The tradeoff is runtime resolution errors instead of compile-time errors.
+
+---
+
+## Core Principles
+
+- Koin resolves dependencies at **runtime** — errors surface at app start, not compile time
+- Prefer Hilt for pure Android projects — Koin shines in **KMP** where Hilt isn't available
+- Define dependencies in **modules** — one module per feature or layer
+- Use `single` for singletons, `factory` for new instances, `viewModel` for ViewModels
+- Always run `checkModules()` in tests — catches missing bindings before production
+
+---
+
+## Setup
+
+```toml
+[versions]
+koin = "3.5.6"
+koin-compose = "3.5.6"
+
+[libraries]
+koin-android        = { module = "io.insert-koin:koin-android", version.ref = "koin" }
+koin-compose        = { module = "io.insert-koin:koin-androidx-compose", version.ref = "koin-compose" }
+koin-core           = { module = "io.insert-koin:koin-core", version.ref = "koin" }  # KMP
+koin-test           = { module = "io.insert-koin:koin-test", version.ref = "koin" }
+```
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation(libs.koin.android)
+    implementation(libs.koin.compose)
+    testImplementation(libs.koin.test)
+}
+```
+
+---
+
+## Koin Application Setup
+
+```kotlin
+// ✅ Initialize in Application
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        startKoin {
+            androidLogger(Level.DEBUG)
+            androidContext(this@MyApplication)
+            modules(
+                networkModule,
+                databaseModule,
+                repositoryModule,
+                viewModelModule
+            )
+        }
+    }
+}
+```
+
+---
+
+## Defining Modules
+
+```kotlin
+// ✅ Network module
+val networkModule = module {
+
+    single {
+        OkHttpClient.Builder()
+            .connectTimeout(30, TimeUnit.SECONDS)
+            .build()
+    }
+
+    single {
+        Retrofit.Builder()
+            .baseUrl("https://api.example.com/")
+            .client(get())  // get() resolves OkHttpClient
+            .addConverterFactory(Json.asConverterFactory("application/json".toMediaType()))
+            .build()
+    }
+
+    single<UserApi> { get<Retrofit>().create(UserApi::class.java) }
+}
+
+// ✅ Database module
+val databaseModule = module {
+
+    single {
+        Room.databaseBuilder(androidContext(), AppDatabase::class.java, "app_db")
+            .addMigrations(MIGRATION_1_2)
+            .build()
+    }
+
+    single { get<AppDatabase>().userDao() }
+    single { get<AppDatabase>().orderDao() }
+}
+
+// ✅ Repository module
+val repositoryModule = module {
+    single<UserRepository> { UserRepositoryImpl(get(), get(), get()) }
+    single { UserMapper() }
+}
+
+// ✅ ViewModel module
+val viewModelModule = module {
+    viewModel { UserListViewModel(get()) }
+    viewModel { parameters -> UserDetailViewModel(get(), parameters.get()) }
+}
+```
+
+---
+
+## Scopes
+
+```kotlin
+// single     — one instance for the entire app lifetime
+// factory    — new instance every time it's requested
+// scoped     — one instance per defined scope lifetime
+
+val sessionModule = module {
+
+    // ✅ Scoped to a session
+    scope<UserSession> {
+        scoped { CartRepository(get()) }
+        scoped { CheckoutViewModel(get()) }
+    }
+}
+
+// ✅ Create and close scope
+val scope = getKoin().createScope("session_1", named<UserSession>())
+val cart = scope.get<CartRepository>()
+scope.close()  // releases scoped instances
+```
+
+---
+
+## Injection in Android Components
+
+```kotlin
+// ✅ Activity / Fragment — by inject()
+class UserFragment : Fragment() {
+    private val viewModel: UserListViewModel by viewModel()
+    private val repository: UserRepository by inject()
+}
+
+// ✅ Compose — koinViewModel()
+@Composable
+fun UserScreen(
+    viewModel: UserListViewModel = koinViewModel()
+) { ... }
+
+// ✅ ViewModel with parameters
+@Composable
+fun UserDetailScreen(userId: String) {
+    val viewModel: UserDetailViewModel = koinViewModel(
+        parameters = { parametersOf(userId) }
+    )
+}
+```
+
+---
+
+## Qualifiers
+
+```kotlin
+// ✅ Named bindings — distinguish same type
+val networkModule = module {
+    single(named("auth")) {
+        OkHttpClient.Builder()
+            .addInterceptor(get<AuthInterceptor>())
+            .build()
+    }
+    single(named("logging")) {
+        OkHttpClient.Builder()
+            .addInterceptor(HttpLoggingInterceptor())
+            .build()
+    }
+}
+
+// ✅ Inject with qualifier
+class UserRepository(
+    private val client: OkHttpClient = get(named("auth"))
+)
+```
+
+---
+
+## KMP Setup (commonMain)
+
+```kotlin
+// ✅ Koin works in commonMain — no Android dependency
+// commonMain
+val sharedModule = module {
+    single { UserRepository(get(), get()) }
+    single { UserMapper() }
+    single { HttpClient { /* Ktor config */ } }
+}
+
+// androidMain
+val androidModule = module {
+    single { AndroidLogger() }
+    viewModel { UserListViewModel(get()) }
+}
+
+// iosMain — use Koin in Swift via KMP
+// val iosModule = module { ... }
+```
+
+---
+
+## Testing
+
+```kotlin
+// ✅ checkModules — verify all bindings resolve
+class KoinModuleTest : KoinTest {
+
+    @Test
+    fun verifyKoinModules() {
+        checkModules {
+            modules(networkModule, databaseModule, repositoryModule, viewModelModule)
+        }
+    }
+}
+
+// ✅ Override bindings in tests
+@Test
+fun testWithFakeDependency() {
+    startKoin {
+        modules(
+            module {
+                single<UserRepository> { FakeUserRepository() }
+                viewModel { UserListViewModel(get()) }
+            }
+        )
+    }
+    // test...
+    stopKoin()
+}
+```
+
+---
+
+## Koin vs Hilt
+
+| | Koin | Hilt |
+|--|------|------|
+| Error detection | Runtime | Compile-time |
+| Setup complexity | Low | Medium |
+| KMP support | ✅ Yes | ❌ No |
+| Code generation | ❌ No | ✅ Yes |
+| Android integration | Good | Excellent |
+| Recommended for | KMP, simple apps | Android-only |
+
+---
+
+## Anti-Patterns
+
+- Not calling `checkModules()` in tests — runtime errors reach production
+- Using `inject()` (lazy) when `get()` (eager) is needed for initialization order
+- Defining all bindings in one giant module — split by feature/layer
+- Using `single` for everything — `factory` for stateless dependencies
+- Not closing scopes — memory leaks for scoped dependencies
+
+---
+
+## Related Skills
+- `hilt` — preferred DI for Android-only projects
+- `dagger` — compile-time DI underlying Hilt
+- `kmp` — Koin in multiplatform projects
+- `viewmodel` — ViewModel injection with Koin