mad-pro-cli 1.0.0

package/templates/mad-skills/references/modularization.md

@@ -0,0 +1,70 @@
+# Modularization Strategy in Modern Android
+
+Modularization involves breaking your application into smaller, independent parts.
+
+```mermaid
+graph BT
+    App[":app (Shell)"] --> FeatureA[":feature:home"]
+    App --> FeatureB[":feature:profile"]
+    FeatureA --> CoreUI[":core:ui"]
+    FeatureB --> CoreUI
+    FeatureA --> Domain[":core:domain"]
+    FeatureB --> Domain
+    Domain --> Data[":core:data"]
+    Data --> Network[":core:network"]
+    Data --> Database[":core:database"]
+```
+
+## 1. Why Modularize?
+
+- **Faster Build Times**: Gradle can compile independent modules in parallel.
+- **Improved Reusability**: Share code between different apps or target platforms.
+- **Strict Separation of Concerns**: Enforce boundaries between different layers and features.
+- **Team Scalability**: Large teams can work on different modules without merge conflicts.
+
+## 2. Recommended Structures
+
+### Layer-based Modularization
+
+Divide the app by architectural layers:
+
+- `:core`: Common utilities, themes, and base classes.
+- `:data`: Repositories and data sources (Room, Retrofit).
+- `:domain`: Use Cases and business logic.
+- `:ui`: Standardized UI components (Design System).
+
+### Feature-based Modularization
+
+Divide the app by user-facing features:
+
+- `:feature:auth`
+- `:feature:profile`
+- `:feature:home`
+
+**The Goal**: A balanced approach where features depend on core/data/domain modules but NOT on each other.
+
+## 3. Dependency Management: Version Catalogs
+
+Use `libs.versions.toml` to manage all dependencies in one place.
+
+```toml
+[versions]
+compose = "1.5.0"
+hilt = "2.48"
+
+[libraries]
+compose-ui = { group = "androidx.compose.ui", name = "ui", version.ref = "compose" }
+hilt-android = { group = "google.dagger", name = "hilt-android", version.ref = "hilt" }
+
+[plugins]
+android-application = { id = "com.android.application", version = "8.1.0" }
+```
+
+## 4. Navigation in Multi-module Apps
+
+- **Feature-to-Feature**: Use high-level feature interfaces or deep links to navigate between modules without creating circular dependencies.
+- **Coordinator Pattern**: Use a dedicated navigation module or the `:app` module to coordinate flows between features.
+
+## 5. Internal Visibility
+
+Use the `internal` modifier to hide implementation details within a module. Only expose what is absolutely necessary (usually interfaces or data classes).

package/templates/mad-skills/references/multiplatform.md

@@ -0,0 +1,55 @@
+# KMP and Compose Multiplatform
+
+Kotlin Multiplatform (KMP) allows you to share code between Android, iOS, Web, and Desktop while keeping the native performance and look of each platform.
+
+## 1. Code Sharing Strategy
+
+The most common approach in MAD is sharing the **Data** and **Domain** layers:
+
+- **Shared (`:commonMain`)**: Business logic, Use Cases, Repositories, and API definitions.
+- **Android (`:androidMain`)**: Android-specific implementations (e.g., Room, Biometrics).
+- **iOS (`:iosMain`)**: iOS-specific implementations (e.g., Keychain, CoreData).
+
+## 2. Compose Multiplatform (CMP)
+
+Compose Multiplatform extends Jetpack Compose to other platforms. You can share not just the logic, but the **UI** as well.
+
+### Standard Module Structure
+
+```text
+shared/
+  commonMain/  <- Shared UI and Logic
+  androidMain/ <- Android specific UI/Logic
+  iosMain/     <- iOS specific UI/Logic
+  desktopMain/ <- Desktop specific UI/Logic
+```
+
+## 3. Libraries for KMP
+
+Use multiplatform-ready libraries to maximize code sharing:
+
+- **Networking**: Ktor
+- **Database**: SQLDelight or Room (KMP support)
+- **Dependency Injection**: Koin
+- **Serialization**: Kotlinx.serialization
+- **Concurrency**: Kotlin Coroutines
+
+## 4. Platform-Specific Implementation: `expect/actual`
+
+When you need to access platform APIs (like the Camera or UUIDs), use the `expect/actual` pattern:
+
+```kotlin
+// In commonMain
+expect fun getDeviceName(): String
+
+// In androidMain
+actual fun getDeviceName(): String = "Android ${Build.MODEL}"
+
+// In iosMain
+actual fun getDeviceName(): String = UIDevice.currentDevice.name
+```
+
+## 5. Integration with iOS
+
+- **SwiftUI Integration**: You can host a Compose Multiplatform view inside a SwiftUI `UIViewControllerRepresentable`.
+- **SKIE**: Use the SKIE library to improve the Swift/Kotlin compatibility layer (e.g., making Flows and Sealed Classes easier to use in Swift).

package/templates/mad-skills/references/navigation.md

@@ -0,0 +1,48 @@
+# Navigation in Jetpack Compose
+
+Modern Compose navigation is type-safe and integrated with the ViewModel lifecycle.
+
+## Type-Safe Navigation (Compose 2.8.0+)
+
+1. **Define Routes as Classes/Objects**: Annotated with `@Serializable`.
+2. **Setup NavHost**: Use the class/object instances directly.
+
+### Example Configuration
+
+```kotlin
+@Serializable
+object Home
+
+@Serializable
+data class Profile(val userId: String)
+
+@Composable
+fun AppNavigation(navController: NavHostController) {
+    NavHost(navController = navController, startDestination = Home) {
+        composable<Home> {
+            HomeScreen(onNavigateToProfile = { id ->
+                navController.navigate(Profile(id))
+            })
+        }
+        composable<Profile> { backStackEntry ->
+            val profile: Profile = backStackEntry.toRoute()
+            ProfileScreen(userId = profile.userId)
+        }
+    }
+}
+```
+
+## 2. Best Practices
+
+- **Screen Composable**: The direct child of a `composable<Route>` should be a "Screen" level composable that takes the ViewModel.
+- **Navigating from VM**: Use a `NavigationManager` or a `SideEffect` (Channel/SharedFlow) to trigger navigation from the ViewModel, rather than passing the `NavController` into the ViewModel.
+- **Single Top Bar**: Usually, a single top bar in the parent `Scaffold` is easier to manage, using `navController.currentBackStackEntryAsState()` to update the title.
+
+## 3. Deep Linking
+
+- Routes defined as classes handle deep links naturally with the same parameters.
+- Define `deepLinks` within the `composable` builder if specific URI patterns are needed.
+
+## 4. Pro Tip
+
+Avoid hardcoded strings for routes. Always use the new Kotlin Serialization-based navigation for compile-time safety.

package/templates/mad-skills/references/network_data.md

@@ -0,0 +1,87 @@
+# Network Data Best Practices in Jetpack Compose
+
+Handling network requests efficiently and safely is crucial for a responsive user experience.
+
+## 1. Networking Engines
+
+### Retrofit (Standard)
+
+The industry standard for type-safe REST clients on Android.
+
+**Setup with Serialization:**
+
+```kotlin
+val retrofit = Retrofit.Builder()
+    .baseUrl("https://api.example.com/")
+    .addConverterFactory(Json.asConverterFactory("application/json".toMediaType()))
+    .build()
+```
+
+### Ktor Client (Kotlin-First)
+
+A multiplatform-ready asynchronous client for HTTP requests.
+
+```kotlin
+val client = HttpClient(Android) {
+    install(ContentNegotiation) {
+        json()
+    }
+}
+```
+
+## 2. JSON Serialization
+
+Use **KotlinX Serialization** instead of GSON or Moshi for better Kotlin integration and performance.
+
+```kotlin
+@Serializable
+data class User(val id: Int, val name: String)
+```
+
+## 3. Handling API Responses
+
+### The Result Wrapper Pattern
+
+Avoid throwing exceptions in the data layer. Use a `Result` or a custom `Resource` wrapper.
+
+```kotlin
+sealed class NetworkResult<out T> {
+    data class Success<out T>(val data: T) : NetworkResult<T>()
+    data class Error(val exception: Exception) : NetworkResult<Nothing>()
+    object Loading : NetworkResult<Nothing>()
+}
+```
+
+### Flow Integration
+
+Expose network calls as a `Flow` to the ViewModel.
+
+```kotlin
+fun getUser(userId: String): Flow<NetworkResult<User>> = flow {
+    emit(NetworkResult.Loading)
+    try {
+        val user = apiService.getUser(userId)
+        emit(NetworkResult.Success(user))
+    } catch (e: Exception) {
+        emit(NetworkResult.Error(e))
+    }
+}
+```
+
+## 4. Caching and Offline Support
+
+- **Repository as Source of Truth**: The UI should only ever observe the local database (Room). The Repository is responsible for syncing the network data into the database.
+- **OkHttp Cache**: Use `Cache-Control` headers for simple GET request caching.
+
+## 5. Error Handling & Connectivity
+
+- **Retry Logic**: Implement exponential backoff for transient errors.
+- **Connectivity Monitoring**: Use `ConnectivityManager` to observe network changes and notify the user when they are offline.
+- **User-Friendly Messages**: Never show raw stack traces or "SocketTimeoutException" to the user. Map them to human-readable strings.
+
+## 6. Best Practices
+
+- **Timeout Configuration**: Set reasonable connection and read timeouts.
+- **Logging**: Use `HttpLoggingInterceptor` (OkHttp) or `Logging` feature (Ktor) only in debug builds.
+- **Security**: Use HTTPS for all traffic. Sanitize sensitive data in logs.
+- **Efficiency**: Use `Gzip` compression if supported by the server.

package/templates/mad-skills/references/observability.md

@@ -0,0 +1,46 @@
+# Observability and App Health
+
+An app isn't finished when it's released. You need to observe how it behaves in the real world to fix bugs and improve the user experience.
+
+## 1. Crash Reporting: Firebase Crashlytics
+
+The industry standard for catching and analyzing crashes.
+
+- **Custom Keys**: Add state information to help reproduce crashes.
+- **Custom Logs**: Log non-fatal exceptions to understand unexpected flows.
+- **User IDs**: Associate crashes with a user ID (anonymized) for better support.
+
+```kotlin
+Firebase.crashlytics.setCustomKey("payment_method", "credit_card")
+Firebase.crashlytics.log("Started checkout flow")
+```
+
+## 2. Remote Configuration
+
+Change the behavior or appearance of your app without a new release.
+
+- **Feature Toggles**: Safely roll out new features to a percentage of users.
+- **Emergency Fixes**: Disable a broken feature instantly.
+- **A/B Testing**: Compare two versions of a screen to see which performs better.
+
+## 3. Performance Monitoring
+
+Tracks the performance of specific parts of your app.
+
+- **Trace Duration**: Measure how long a specific task takes (e.g., Image processing).
+- **Network Performance**: Automatically monitor the latency and success rate of your API calls.
+- **Frame Drop Tracking**: Identify screens where the UI is lagging.
+
+## 4. User Analytics
+
+Understand how users navigate your app.
+
+- **Screen Tracking**: Monitor which screens are most popular.
+- **Conversion Funnels**: Track where users drop off in a multi-step process (e.g., Sign-up).
+- **Custom Events**: Track specific actions like "Added to cart" or "Shared content".
+
+## 5. Privacy and Ethics
+
+- **Anonymization**: Never send Personally Identifiable Information (PII).
+- **Opt-out**: Provide users with the ability to disable tracking.
+- **Data Minimization**: Only collect the data you actually need to improve the app.

package/templates/mad-skills/references/performance.md

@@ -0,0 +1,51 @@
+# Performance Optimization in Jetpack Compose
+
+Compose is fast, but improper patterns can lead to unnecessary recompositions and UI lag.
+
+## The Three Phases of Compose
+
+1. **Composition**: What to show (running composable functions).
+2. **Layout**: Where to show it (measuring and placing).
+3. **Drawing**: How to draw it (rendering pixels).
+
+**Rule**: Always defer state reads to the latest possible phase.
+
+## Optimization Techniques
+
+### 1. Stable Types
+
+State classes should ideally be stable. Use the `@Stable` or `@Immutable` annotations if the compiler cannot infer stability (e.g., for classes in modules without Compose enabled).
+
+- Avoid `List` (unstable); use `ImmutableList` (from Kotlin collections immutable) or a wrapper class.
+
+### 2. `derivedStateOf`
+
+Use `derivedStateOf` when you have state that depends on other state, and that input state changes more frequently than you need to update the UI.
+*Example: Scrolling position to show a "Back to Top" button.*
+
+```kotlin
+val showButton by remember {
+    derivedStateOf { listState.firstVisibleItemIndex > 5 }
+}
+```
+
+### 3. Deferring State Reads
+
+Use lambda-based modifiers when reading state that changes frequently (like scroll or animation values).
+
+```kotlin
+// GOOD: Read happens only during Draw phase
+Box(Modifier.graphicsLayer { alpha = scrollState.value / 100f })
+
+// BAD: Causes recomposition every scroll change
+Box(Modifier.alpha(scrollState.value / 100f))
+```
+
+### 4. `remember` computations
+
+Expensive operations (like sorting a list or parsing a date) should be wrapped in `remember(key)`.
+
+## 4. Tools
+
+- **Layout Inspector**: Use the "Recomposition Counts" feature to identify hot spots.
+- **Strong Skipping Mode**: Enabled by default in newer Compose versions, but still requires stable data types to work perfectly.

package/templates/mad-skills/references/security.md

@@ -0,0 +1,67 @@
+# Security Best Practices in Jetpack Compose
+
+Ensuring your Android application is secure involves protecting data at rest, in transit, and during interaction.
+
+## Secure Storage
+
+Avoid storing sensitive information (tokens, PII) in plain `SharedPreferences` or `DataStore`.
+
+1. **EncryptedSharedPreferences**: Use the Security library to encrypt key-value pairs.
+2. **Encrypted DataStore**: Use `okio` based encryption or a custom wrapper for `DataStore<Preferences>`.
+
+```kotlin
+val masterKey = MasterKey.Builder(context)
+    .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+    .build()
+
+val sharedPreferences = EncryptedSharedPreferences.create(
+    context,
+    "secret_shared_prefs",
+    masterKey,
+    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+)
+```
+
+## Biometric Authentication
+
+Use `BiometricPrompt` for sensitive actions (e.g., payments or revealing secrets). Integration with Compose requires handling the fragment-based callback.
+
+- **Always verify**: Ensure the device supports biometrics before showing the prompt.
+- **CryptoObject**: Link the biometric scan to a `Cipher` or `Signature` for maximum security.
+
+## Permissions
+
+Modern Android (API 33+) requires granular permissions.
+
+- **Accompanist Permissions**: Use libraries like `com.google.accompanist:accompanist-permissions` for a better Compose experience.
+- **Explain why**: Always provide a clear rationale to the user *before* requesting a dangerous permission.
+
+```kotlin
+val permissionState = rememberPermissionState(android.Manifest.permission.CAMERA)
+if (permissionState.status.isGranted) {
+    Text("Camera permission granted")
+} else {
+    Button(onClick = { permissionState.launchPermissionRequest() }) {
+        Text("Request permission")
+    }
+}
+```
+
+## Root Detection & Play Integrity
+
+Protect your app from running on compromised devices.
+
+- **Play Integrity API**: Use Google's official API to verify that you are talking to a genuine app binary running on a genuine Android device.
+- **Root Checks**: Use libraries like `RootBeer` for basic local checks, but rely on server-side validation for critical flows.
+
+## Network Security
+
+- **SSL Pinning**: Use OkHttp's `CertificatePinner` to prevent MiTM attacks.
+- **Network Security Config**: Define a `network_security_config.xml` to enforce HTTPS and disable cleartext traffic.
+
+## Best Practices
+
+- **Hide sensitive content in task switcher**: Use `FLAG_SECURE` in the relevant activity or window.
+- **Input Sanitization**: Always sanitize user input before sending it to a backend or a database.
+- **Hardcoded Secrets**: Never store API keys or secrets in your source code. Use `local.properties` or environment variables with the Secrets Gradle Plugin.

package/templates/mad-skills/references/solid_principles.md

@@ -0,0 +1,61 @@
+# SOLID Principles in Modern Android
+
+SOLID is an acronym for five design principles intended to make software designs more understandable, flexible, and maintainable.
+
+## 1. Single Responsibility Principle (SRP)
+
+> **"A class should have one, and only one, reason to change."**
+
+- **Android Example**: Don't put data fetching logic inside a Composable or a ViewModel.
+- **Improved**: Use a Repository for data fetching and a Use Case for business logic. The Composable should only be responsible for rendering the UI.
+
+## 2. Open/Closed Principle (OCP)
+
+> **"Software entities should be open for extension, but closed for modification."**
+
+- **Android Example**: Use **Slot APIs** in Jetpack Compose.
+- **Improved**: Instead of a giant `MyButton` with 20 parameters, accept a `content: @Composable () -> Unit` lambda. This allows the button to be extended with any content without modifying the `MyButton` code.
+
+## 3. Liskov Substitution Principle (LSP)
+
+> **"Objects in a program should be replaceable with instances of their subtypes without altering the correctness of that program."**
+
+- **Android Example**: If you have a `BaseRepository`, any implementation (e.g., `ProdRepo`, `MockRepo`) should behave predictably according to the interface contract.
+- **Avoid**: Throwing `NotImplementedError` in a subclass for a method that is part of the parent's contract.
+
+## 4. Interface Segregation Principle (ISP)
+
+> **"Many client-specific interfaces are better than one general-purpose interface."**
+
+- **Android Example**: Instead of one massive `Actions` interface for a screen, split it into smaller ones like `AuthActions`, `ProfileActions`.
+- **Improved**: Prevents a class from being forced to implement methods it doesn't need.
+
+## 5. Dependency Inversion Principle (DIP)
+
+> **"Depend upon abstractions, not concretions."**
+
+- **Android Example**: A ViewModel should depend on a `UserRepository` interface, not the `UserRepositoryImpl` class.
+- **Implementation**:
+  - Higher-level modules should not depend on lower-level modules. Both should depend on abstractions.
+  - Abstractions should not depend on details. Details should depend on abstractions.
+
+## Implementation Pattern (DIP)
+
+```kotlin
+// Abstraction (Domain Layer)
+interface WeatherRepository {
+    suspend fun getCurrentWeather(): Weather
+}
+
+// Low-level detail (Data Layer)
+class OpenWeatherRepo : WeatherRepository {
+    override suspend fun getCurrentWeather() = // ...
+}
+
+// High-level module (UI Layer)
+class WeatherViewModel @Inject constructor(
+    private val repository: WeatherRepository // Depends on abstraction
+) : ViewModel() {
+    // ...
+}
+```

package/templates/mad-skills/references/state_management.md

@@ -0,0 +1,46 @@
+# State Management in Jetpack Compose
+
+Effective state management is crucial for creating responsive and predictable UIs.
+
+## Core Rules
+
+1. **Prefer ViewModels**: Business logic and state should reside in a `ViewModel` to survive configuration changes.
+2. **Use `StateFlow`**: Represent UI state as a single `StateFlow<UiState>` in the ViewModel.
+3. **Immutability**: UI state objects must be immutable. Use `data class` with `copy()`.
+4. **State Hoisting**: Composables should accept state and emit events (lambdas).
+
+## 2. Patterns
+
+### The UiState Pattern
+
+```kotlin
+data class UserProfileUiState(
+    val username: String = "",
+    val isLoading: Boolean = false,
+    val errorMessage: String? = null
+)
+```
+
+### ViewModel Implementation
+
+```kotlin
+class UserProfileViewModel : ViewModel() {
+    private val _uiState = MutableStateFlow(UserProfileUiState())
+    val uiState: StateFlow<UserProfileUiState> = _uiState.asStateFlow()
+
+    fun onUsernameChanged(newName: String) {
+        _uiState.update { it.copy(username = newName) }
+    }
+}
+```
+
+## 3. Side Effects
+
+- **`LaunchedEffect`**: For actions triggered by state changes (e.g., showing a Snackbar).
+- **`SideEffect`**: For actions that must run after every successful recomposition.
+- **`rememberUpdatedState`**: To capture the latest value in a long-running effect without restarting it.
+
+## 4. Avoid
+
+- Avoid `MutableState` inside ViewModels; use `MutableStateFlow` instead for better integration with multi-platform or other layers.
+- Never pass a `ViewModel` deeper than the "Screen" level composable.

package/templates/mad-skills/references/testing.md

@@ -0,0 +1,48 @@
+# Testing in Jetpack Compose
+
+Compose testing is semantic-based, meaning it focuses on what the user sees and interacts with, rather than internal implementation details.
+
+## Rule of Selection
+
+1. **`hasText`** / **`hasContentDescription`**: Best for accessibility.
+2. **`hasTestTag`**: Use only as a last resort for unique identification of complex nodes.
+
+## 2. Setup
+
+```kotlin
+class MyComposeTest {
+    @get:Rule
+    val composeTestRule = createComposeRule()
+
+    @Test
+    fun loginFlow_showsErrorOnEmptyPassword() {
+        composeTestRule.setContent {
+            AppTheme {
+                LoginScreen(...)
+            }
+        }
+
+        // Action
+        composeTestRule.onNodeWithText("Login").performClick()
+
+        // Assertion
+        composeTestRule.onNodeWithText("Password cannot be empty").assertIsDisplayed()
+    }
+}
+
+## 3. Best Practices
+
+- **Avoid `Thread.sleep`**: The `ComposeTestRule` automatically waits for the UI to be idle (IdlingResources).
+- **Semantics**: Use `Modifier.semantics { contentDescription = "..." }` to make your UI testable and accessible at the same time.
+- **Isolate Screenshots**: Use `captureToImage()` for visual regression testing.
+- **Hilt Testing**: Use `@HiltAndroidTest` for integration tests that require a real ViewModel/Repository.
+
+## 4. Verification Checklist
+
+- Assert visibility with `assertIsDisplayed()`.
+- Assert existence with `assertExists()`.
+- Assert interactive state with `assertIsEnabled()` or `assertIsSelected()`.
+
+## 5. Pro Tip
+
+Use the `DeviceConfigurationOverride` APIs to test your UI against different screen sizes, font scales, and locales within a single test file.

package/templates/mad-skills/references/theming.md

@@ -0,0 +1,52 @@
+# Theming in Jetpack Compose
+
+Jetpack Compose uses Material 3 (M3) as its default design system.
+
+## Material Theme Structure
+
+A standard M3 theme consists of:
+
+1. **`ColorScheme`**: Dynamic vs Static colors.
+2. **`Typography`**: Standardized text styles (Headline, Body, Label).
+3. **`Shapes`**: Corner radiuses for components.
+
+## Implementation Pattern
+
+```kotlin
+@Composable
+fun AppTheme(
+    darkTheme: Boolean = isSystemInDarkTheme(),
+    dynamicColor: Boolean = true,
+    content: @Composable () -> Unit
+) {
+    val colorScheme = when {
+        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
+            val context = LocalContext.current
+            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
+        }
+        darkTheme -> DarkColorScheme
+        else -> LightColorScheme
+    }
+
+    MaterialTheme(
+        colorScheme = colorScheme,
+        typography = Typography,
+        content = content
+    )
+}
+```
+
+## 3. Best Practices
+
+- **Use Theme Tokens**: Never hardcode hex values like `Color(0xFF00FF00)`. Always use `MaterialTheme.colorScheme.primary`.
+- **Text Styles**: Use `MaterialTheme.typography.bodyLarge` instead of modifying `fontSize` and `fontWeight` manually.
+- **Local Providers**: Create your own `CompositionLocal` if you need to pass custom theme attributes (e.g., custom spacing or extra semantic colors) that aren't in M3.
+
+## 4. Visual Hierarchy
+
+- Use `Surface` to automatically handle background colors and content color nesting (providing correct contrast).
+- Use `Elevated` vs `Filled` vs `Outlined` components to signify importance.
+
+## 5. Dark Mode Support
+
+- Always verify your theme in both light and dark modes. Use `@Preview` with `uiMode = UI_MODE_NIGHT_YES`.