android-sdd 1.0.0

package/skills/Meta Skills/Migration Strategy/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: migration-strategy
+description: >
+  Migration strategy for Android apps — database, API, and data format migrations.
+  Load this skill when planning Room database schema migrations, handling
+  API version changes, migrating SharedPreferences to DataStore,
+  or designing backward-compatible data format changes.
+---
+
+# Migration Strategy
+
+## Overview
+Migration strategy covers how the app evolves its data contracts without breaking existing users. This includes Room schema migrations (adding columns, renaming tables), API version transitions (v1 → v2 endpoints), and storage format migrations (SharedPreferences → DataStore, plain → encrypted). Each type requires a different approach.
+
+---
+
+## Core Principles
+
+- **Never break existing users** — migrations must be backward-compatible or provide a clear upgrade path
+- **Migrations are one-way** — don't design rollback unless specifically required
+- **Test migrations** — always test the upgrade path from the previous version
+- **Data loss is unacceptable** — destructive migration (`fallbackToDestructiveMigration`) is only for dev/cache data
+- **Incremental** — migrate one version at a time; never skip versions
+
+---
+
+## Room Database Migration
+
+```kotlin
+// ✅ Version 1 → Version 2: Add column
+val MIGRATION_1_2 = object : Migration(1, 2) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        database.execSQL(
+            "ALTER TABLE users ADD COLUMN is_verified INTEGER NOT NULL DEFAULT 0"
+        )
+    }
+}
+
+// ✅ Version 2 → Version 3: Add new table
+val MIGRATION_2_3 = object : Migration(2, 3) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        database.execSQL("""
+            CREATE TABLE IF NOT EXISTS `user_sessions` (
+                `id` TEXT NOT NULL,
+                `user_id` TEXT NOT NULL,
+                `token` TEXT NOT NULL,
+                `expires_at` INTEGER NOT NULL,
+                PRIMARY KEY(`id`),
+                FOREIGN KEY(`user_id`) REFERENCES `users`(`id`) ON DELETE CASCADE
+            )
+        """.trimIndent())
+        database.execSQL("CREATE INDEX IF NOT EXISTS `index_user_sessions_user_id` ON `user_sessions` (`user_id`)")
+    }
+}
+
+// ✅ Version 3 → Version 4: Rename column (SQLite doesn't support RENAME COLUMN before API 29)
+val MIGRATION_3_4 = object : Migration(3, 4) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        // SQLite < 3.25 workaround: create new table, copy, drop old
+        database.execSQL("""
+            CREATE TABLE `users_new` (
+                `id` TEXT NOT NULL,
+                `full_name` TEXT NOT NULL,
+                `email` TEXT NOT NULL,
+                `role` TEXT NOT NULL,
+                `is_active` INTEGER NOT NULL,
+                `is_verified` INTEGER NOT NULL DEFAULT 0,
+                `created_at` INTEGER NOT NULL,
+                `updated_at` INTEGER NOT NULL,
+                PRIMARY KEY(`id`)
+            )
+        """.trimIndent())
+        database.execSQL("""
+            INSERT INTO `users_new`
+            SELECT `id`, `name`, `email`, `role`, `is_active`, `is_verified`, `created_at`, `updated_at`
+            FROM `users`
+        """.trimIndent())
+        database.execSQL("DROP TABLE `users`")
+        database.execSQL("ALTER TABLE `users_new` RENAME TO `users`")
+    }
+}
+
+// ✅ Register all migrations
+@Database(entities = [...], version = 4)
+abstract class AppDatabase : RoomDatabase() {
+    companion object {
+        fun build(context: Context): AppDatabase =
+            Room.databaseBuilder(context, AppDatabase::class.java, "app.db")
+                .addMigrations(MIGRATION_1_2, MIGRATION_2_3, MIGRATION_3_4)
+                .build()
+    }
+}
+```
+
+---
+
+## Auto Migration (Room 2.4+)
+
+```kotlin
+// ✅ Simple migrations can use @AutoMigration
+@Database(
+    entities = [UserEntity::class],
+    version = 5,
+    autoMigrations = [
+        AutoMigration(from = 4, to = 5)  // adds new columns with defaults automatically
+    ]
+)
+abstract class AppDatabase : RoomDatabase()
+
+// ✅ AutoMigration with spec for rename/delete
+@RenameColumn(tableName = "users", fromColumnName = "name", toColumnName = "full_name")
+class Migration4To5Spec : AutoMigrationSpec
+
+@Database(
+    version = 5,
+    autoMigrations = [
+        AutoMigration(from = 4, to = 5, spec = Migration4To5Spec::class)
+    ]
+)
+abstract class AppDatabase : RoomDatabase()
+```
+
+---
+
+## Testing Migrations
+
+```kotlin
+// ✅ Always test migration path
+@RunWith(AndroidJUnit4::class)
+class MigrationTest {
+
+    @get:Rule
+    val helper = MigrationTestHelper(
+        InstrumentationRegistry.getInstrumentation(),
+        AppDatabase::class.java
+    )
+
+    @Test
+    fun migrate1To2() {
+        // Create v1 database with test data
+        helper.createDatabase("test.db", 1).apply {
+            execSQL("INSERT INTO users VALUES ('1', 'Ali', 'ali@test.com', 'member', 1, 1000, 1000)")
+            close()
+        }
+
+        // Run migration
+        val db = helper.runMigrationsAndValidate("test.db", 2, true, MIGRATION_1_2)
+
+        // Verify data intact + new column has default
+        val cursor = db.query("SELECT * FROM users WHERE id = '1'")
+        cursor.moveToFirst()
+        assertThat(cursor.getInt(cursor.getColumnIndex("is_verified"))).isEqualTo(0)
+        cursor.close()
+    }
+}
+```
+
+---
+
+## SharedPreferences → DataStore Migration
+
+```kotlin
+// ✅ One-time migration from SharedPreferences to DataStore
+class PreferencesMigration @Inject constructor(
+    @ApplicationContext private val context: Context
+) {
+    private val legacyPrefs = context.getSharedPreferences("app_prefs", Context.MODE_PRIVATE)
+    private val migrationKey = "prefs_migrated_v1"
+
+    suspend fun migrateIfNeeded(dataStore: DataStore<Preferences>) {
+        if (legacyPrefs.getBoolean(migrationKey, false)) return
+
+        dataStore.edit { prefs ->
+            // Copy all keys from SharedPreferences to DataStore
+            legacyPrefs.getString("auth_token", null)?.let {
+                prefs[stringPreferencesKey("auth_token")] = it
+            }
+            legacyPrefs.getBoolean("notifications_enabled", true).let {
+                prefs[booleanPreferencesKey("notifications_enabled")] = it
+            }
+            legacyPrefs.getString("selected_language", "en")?.let {
+                prefs[stringPreferencesKey("selected_language")] = it
+            }
+        }
+
+        // Mark migration complete
+        legacyPrefs.edit { putBoolean(migrationKey, true) }
+
+        // Optionally clear old prefs
+        legacyPrefs.edit { clear() }
+    }
+}
+
+// ✅ Run at app startup — before DataStore is used
+class App : Application() {
+    @Inject lateinit var preferencesMigration: PreferencesMigration
+    @Inject lateinit var dataStore: DataStore<Preferences>
+
+    override fun onCreate() {
+        super.onCreate()
+        // Run migration in background
+        applicationScope.launch {
+            preferencesMigration.migrateIfNeeded(dataStore)
+        }
+    }
+}
+```
+
+---
+
+## API Version Migration
+
+```kotlin
+// ✅ Support multiple API versions via versioned endpoints
+interface UserApiService {
+    @GET("v2/users/{id}")
+    suspend fun getUser(@Path("id") id: String): UserDtoV2
+
+    // Keep v1 for gradual migration
+    @GET("v1/users/{id}")
+    suspend fun getUserLegacy(@Path("id") id: String): UserDtoV1
+}
+
+// ✅ Repository handles version negotiation
+class UserRepositoryImpl @Inject constructor(
+    private val api: UserApiService,
+    private val featureFlags: FeatureFlags
+) : UserRepository {
+
+    override suspend fun getUser(id: String): Result<User> = runCatching {
+        if (featureFlags.isApiV2Enabled) {
+            api.getUser(id).toDomain()
+        } else {
+            api.getUserLegacy(id).toDomain()
+        }
+    }
+}
+```
+
+---
+
+## Data Format Migration
+
+```kotlin
+// ✅ Version-tagged serialized data
+@Serializable
+data class StoredData(
+    val version: Int = CURRENT_VERSION,
+    val payload: JsonElement
+) {
+    companion object {
+        const val CURRENT_VERSION = 2
+
+        fun migrate(stored: StoredData): StoredData = when (stored.version) {
+            1 -> migrateV1ToV2(stored)
+            CURRENT_VERSION -> stored
+            else -> throw IllegalStateException("Unknown version: ${stored.version}")
+        }
+
+        private fun migrateV1ToV2(stored: StoredData): StoredData {
+            val v1 = Json.decodeFromJsonElement<DataV1>(stored.payload)
+            val v2 = DataV2(
+                id = v1.id,
+                fullName = "${v1.firstName} ${v1.lastName}",  // merge fields
+                email = v1.email
+            )
+            return StoredData(version = 2, payload = Json.encodeToJsonElement(v2))
+        }
+    }
+}
+```
+
+---
+
+## Migration Checklist
+
+```
+Before releasing a migration:
+  ✅ New @Entity version incremented in @Database
+  ✅ Migration object written and tested
+  ✅ Migration registered in Room.databaseBuilder
+  ✅ MigrationTest written and passing
+  ✅ Tested on device upgrading from previous version
+  ✅ No data loss for existing users
+  ✅ fallbackToDestructiveMigration NOT used (unless cache-only DB)
+```
+
+---
+
+## Anti-Patterns
+
+- `fallbackToDestructiveMigration()` for user data — wipes all data on missing migration
+- Skipping migration versions — always chain migrations 1→2→3, never jump 1→3
+- Not testing migration path — migration bugs only appear on upgrade, not fresh install
+- Modifying old migrations — never change a released migration; add a new one
+- Storing migration state in the migrated DB — if migration fails, the state check fails too
+
+---
+
+## Related Skills
+- `room` — Room database setup
+- `dao` — DAO patterns affected by migrations
+- `entity-design` — entity changes that trigger migrations
+- `datastore` — DataStore as migration target from SharedPreferences
+- `gradle` — build versioning that tracks DB version

package/skills/Meta Skills/User Friendly Errors/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: user-friendly-errors
+description: >
+  Displaying user-friendly error messages in Android Compose UI.
+  Load this skill when designing error states in composables,
+  writing error string resources, building reusable error components,
+  or deciding between inline errors, snackbars, and full error screens.
+---
+
+# User Friendly Errors
+
+## Overview
+User-friendly errors translate technical failures into clear, actionable messages. The goal is to tell the user what happened, why it matters, and what they can do. Error display varies by context: inline field errors, snackbars for transient failures, and full error screens for blocking failures.
+
+---
+
+## Core Principles
+
+- **Clear language** — no technical jargon; no stack traces shown to users
+- **Actionable** — tell the user what to do, not just what went wrong
+- **Contextual** — field-level errors inline; screen-level errors as states; transient as snackbars
+- **Consistent** — same error type always looks the same across screens
+- **Honest** — don't overpromise; "Try again" only when retry might work
+
+---
+
+## Error Display Decision
+
+```
+Error type           → Display method
+─────────────────────────────────────────────────────
+Form validation      → Inline below field
+Transient (network)  → Snackbar with action
+Blocking (load fail) → Full error state in screen
+Permission denied    → Inline message, no retry
+Session expired      → Navigate to login
+Critical (corrupt)   → Dialog, then navigate away
+```
+
+---
+
+## Error String Resources
+
+```xml
+<!-- res/values/strings_errors.xml -->
+<resources>
+    <!-- Network -->
+    <string name="error_no_connection">No internet connection. Please check your network.</string>
+    <string name="error_timeout">Request timed out. Please try again.</string>
+    <string name="error_server">Server error. Please try again later.</string>
+    <string name="error_session_expired">Your session has expired. Please log in again.</string>
+    <string name="error_no_permission">You don\'t have permission to do this.</string>
+    <string name="error_not_found">The item you\'re looking for doesn\'t exist.</string>
+    <string name="error_rate_limited">Too many requests. Please wait a moment and try again.</string>
+
+    <!-- Data -->
+    <string name="error_item_not_found">Item not found.</string>
+    <string name="error_conflict">"%1$s" already exists.</string>
+    <string name="error_invalid_state">This action isn\'t available right now.</string>
+
+    <!-- Storage -->
+    <string name="error_disk_full">Your device storage is full. Free up space and try again.</string>
+    <string name="error_data_corrupted">Some data was corrupted. Please reinstall the app.</string>
+
+    <!-- Generic -->
+    <string name="error_unexpected">Something went wrong. Please try again.</string>
+    <string name="error_retry">Try Again</string>
+    <string name="error_dismiss">Dismiss</string>
+</resources>
+```
+
+---
+
+## Reusable Error Components
+
+```kotlin
+// ✅ Full-screen error state
+@Composable
+fun FullScreenError(
+    message: String,
+    onRetry: (() -> Unit)? = null,
+    modifier: Modifier = Modifier
+) {
+    Column(
+        modifier = modifier
+            .fillMaxSize()
+            .padding(horizontal = 32.dp),
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.Center
+    ) {
+        Icon(
+            imageVector = Icons.Outlined.ErrorOutline,
+            contentDescription = null,
+            modifier = Modifier.size(64.dp),
+            tint = MaterialTheme.colorScheme.error
+        )
+        Spacer(Modifier.height(16.dp))
+        Text(
+            text = message,
+            style = MaterialTheme.typography.bodyLarge,
+            textAlign = TextAlign.Center,
+            color = MaterialTheme.colorScheme.onSurface
+        )
+        if (onRetry != null) {
+            Spacer(Modifier.height(24.dp))
+            Button(onClick = onRetry) {
+                Text(stringResource(R.string.error_retry))
+            }
+        }
+    }
+}
+
+// ✅ Inline error — below a field
+@Composable
+fun FieldError(
+    message: String,
+    modifier: Modifier = Modifier
+) {
+    Text(
+        text = message,
+        style = MaterialTheme.typography.bodySmall,
+        color = MaterialTheme.colorScheme.error,
+        modifier = modifier.padding(start = 16.dp, top = 4.dp)
+    )
+}
+
+// ✅ Error banner — non-blocking top/bottom banner
+@Composable
+fun ErrorBanner(
+    message: String,
+    onDismiss: (() -> Unit)? = null,
+    modifier: Modifier = Modifier
+) {
+    Surface(
+        modifier = modifier.fillMaxWidth(),
+        color = MaterialTheme.colorScheme.errorContainer,
+        tonalElevation = 2.dp
+    ) {
+        Row(
+            modifier = Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+            Icon(
+                imageVector = Icons.Outlined.Warning,
+                contentDescription = null,
+                tint = MaterialTheme.colorScheme.onErrorContainer,
+                modifier = Modifier.size(20.dp)
+            )
+            Spacer(Modifier.width(12.dp))
+            Text(
+                text = message,
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onErrorContainer,
+                modifier = Modifier.weight(1f)
+            )
+            if (onDismiss != null) {
+                IconButton(onClick = onDismiss, modifier = Modifier.size(24.dp)) {
+                    Icon(Icons.Default.Close, contentDescription = stringResource(R.string.error_dismiss))
+                }
+            }
+        }
+    }
+}
+```
+
+---
+
+## Snackbar Error Pattern
+
+```kotlin
+// ✅ Transient error via snackbar
+@Composable
+fun ProductScreen(
+    viewModel: ProductViewModel = hiltViewModel()
+) {
+    val snackbarHostState = remember { SnackbarHostState() }
+    val context = LocalContext.current
+
+    // Collect one-time error events
+    LaunchedEffect(Unit) {
+        viewModel.events.collect { event ->
+            when (event) {
+                is ProductEvent.ShowError -> {
+                    val result = snackbarHostState.showSnackbar(
+                        message = event.message,
+                        actionLabel = if (event.canRetry) context.getString(R.string.error_retry) else null,
+                        duration = SnackbarDuration.Long
+                    )
+                    if (result == SnackbarResult.ActionPerformed && event.canRetry) {
+                        viewModel.onRetry()
+                    }
+                }
+            }
+        }
+    }
+
+    Scaffold(snackbarHost = { SnackbarHost(snackbarHostState) }) { padding ->
+        ProductContent(modifier = Modifier.padding(padding))
+    }
+}
+```
+
+---
+
+## Form Validation Errors
+
+```kotlin
+// ✅ Inline validation errors on form fields
+@Composable
+fun EmailField(
+    value: String,
+    error: String?,
+    onValueChange: (String) -> Unit,
+    modifier: Modifier = Modifier
+) {
+    Column(modifier = modifier) {
+        OutlinedTextField(
+            value = value,
+            onValueChange = onValueChange,
+            label = { Text("Email") },
+            isError = error != null,
+            supportingText = {
+                if (error != null) {
+                    Text(
+                        text = error,
+                        color = MaterialTheme.colorScheme.error
+                    )
+                }
+            },
+            keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Email),
+            singleLine = true,
+            modifier = Modifier.fillMaxWidth()
+        )
+    }
+}
+
+// ✅ UiState with per-field errors
+data class RegistrationUiState(
+    val email: String = "",
+    val password: String = "",
+    val isLoading: Boolean = false,
+    val emailError: String? = null,
+    val passwordError: String? = null,
+    val generalError: String? = null
+)
+```
+
+---
+
+## AppError → User Message Mapping
+
+```kotlin
+// ✅ Centralized mapping — use string resources
+@Composable
+fun AppError.toMessage(): String = when (this) {
+    is AppError.Network.NoConnection  -> stringResource(R.string.error_no_connection)
+    is AppError.Network.Timeout       -> stringResource(R.string.error_timeout)
+    is AppError.Network.Unauthorized  -> stringResource(R.string.error_session_expired)
+    is AppError.Network.Forbidden     -> stringResource(R.string.error_no_permission)
+    is AppError.Network.NotFound      -> stringResource(R.string.error_not_found)
+    is AppError.Network.ServerError   -> stringResource(R.string.error_server)
+    is AppError.Network.RateLimited   -> stringResource(R.string.error_rate_limited)
+    is AppError.Data.NotFound         -> stringResource(R.string.error_item_not_found)
+    is AppError.Data.Conflict         -> stringResource(R.string.error_conflict, field)
+    is AppError.Data.Validation       -> errors.values.first()
+    is AppError.Data.InvalidState     -> reason
+    is AppError.Storage.DiskFull      -> stringResource(R.string.error_disk_full)
+    is AppError.Storage.Corrupted     -> stringResource(R.string.error_data_corrupted)
+    is AppError.Storage.Unknown,
+    is AppError.Unexpected            -> stringResource(R.string.error_unexpected)
+    else                              -> stringResource(R.string.error_unexpected)
+}
+
+// ✅ Non-composable mapping (for ViewModel)
+fun AppError.toMessageResId(): Int = when (this) {
+    is AppError.Network.NoConnection -> R.string.error_no_connection
+    is AppError.Network.Timeout      -> R.string.error_timeout
+    is AppError.Network.Unauthorized -> R.string.error_session_expired
+    // ...
+    else                             -> R.string.error_unexpected
+}
+```
+
+---
+
+## Screen-Level Error Handling Pattern
+
+```kotlin
+// ✅ Composable that handles all UiState cases including error
+@Composable
+fun ProductListScreen(
+    viewModel: ProductListViewModel = hiltViewModel()
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    when (val s = state) {
+        is ProductListUiState.Loading -> {
+            LoadingIndicator(modifier = Modifier.fillMaxSize())
+        }
+        is ProductListUiState.Success -> {
+            ProductList(
+                products = s.products,
+                onProductClick = viewModel::onProductClick
+            )
+        }
+        is ProductListUiState.Error -> {
+            FullScreenError(
+                message = s.message,
+                onRetry = if (s.canRetry) viewModel::loadProducts else null
+            )
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Showing raw exception messages (`e.message`) to users — technical and unhelpful
+- Same snackbar for every error — `Unauthorized` needs login redirect, not a snackbar
+- Error messages without action — "Error occurred" with no retry button frustrates users
+- Hardcoding error strings in code — use string resources for localization
+- Generic "Something went wrong" for every error — obscures actionable information
+
+---
+
+## Related Skills
+- `domain-error-model` — typed errors being displayed
+- `error-handling` — how errors reach the UI
+- `failure-strategy` — which display method to use per error
+- `state-management` — modeling error state in UiState
+- `compose` — Compose fundamentals for error composables
+- `material3` — error colors and components from Material 3