E6: client-side product telemetry foundation

composeApp/build.gradle.kts

@@ -18,6 +18,7 @@ kotlin {
         androidMain.dependencies {
             implementation(libs.androidx.compose.ui.tooling.preview)
             implementation(libs.androidx.activity.compose)
+            implementation(libs.androidx.lifecycle.process)
 
             implementation(libs.core.splashscreen)
 

composeApp/src/androidMain/kotlin/zed/rainxch/githubstore/app/GithubStoreApp.kt

@@ -4,12 +4,17 @@ import android.app.Application
 import android.app.NotificationChannel
 import android.app.NotificationManager
 import android.os.Build
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleEventObserver
+import androidx.lifecycle.ProcessLifecycleOwner
 import co.touchlab.kermit.Logger
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.withTimeoutOrNull
 import org.koin.android.ext.android.get
 import org.koin.android.ext.koin.androidContext
 import zed.rainxch.core.data.local.db.dao.ExternalLinkDao
@@ -22,13 +27,18 @@ import zed.rainxch.core.domain.repository.ExternalImportRepository
 import zed.rainxch.core.domain.repository.InstalledAppsRepository
 import zed.rainxch.core.domain.repository.TweaksRepository
 import zed.rainxch.core.domain.system.PackageMonitor
+import zed.rainxch.core.domain.telemetry.ProductTelemetry
+import zed.rainxch.core.domain.telemetry.ProductTelemetryEvents
+import zed.rainxch.core.domain.telemetry.ProductTelemetryProps
 import zed.rainxch.githubstore.app.di.initKoin
+import kotlin.time.TimeSource
 
 class GithubStoreApp : Application() {
     private var packageEventReceiver: PackageEventReceiver? = null
     private val appScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
 
     override fun onCreate() {
+        ColdStart.markStart()
         super.onCreate()
 
         initKoin {
@@ -40,10 +50,84 @@ class GithubStoreApp : Application() {
         startDownloadNotificationObserver()
         scheduleBackgroundUpdateChecks()
         registerSelfAsInstalledApp()
+        installCrashTelemetryHandler()
+        installSessionDurationObserver()
+        fireAppLaunched()
         scheduleInitialExternalScan()
         scheduleSigningSeedSync()
     }
 
+    private fun installSessionDurationObserver() {
+        // Per-foreground session — set on ON_START, consumed on ON_STOP.
+        // Distinct from ColdStart so each backgrounding reports its own
+        // duration rather than monotonically-growing process uptime.
+        var foregroundStart: TimeSource.Monotonic.ValueTimeMark? = null
+        ProcessLifecycleOwner.get().lifecycle.addObserver(
+            LifecycleEventObserver { _, event ->
+                when (event) {
+                    Lifecycle.Event.ON_START -> {
+                        foregroundStart = TimeSource.Monotonic.markNow()
+                    }
+
+                    Lifecycle.Event.ON_STOP -> {
+                        val seconds = foregroundStart?.elapsedNow()?.inWholeSeconds
+                        foregroundStart = null
+                        val telemetry = get<ProductTelemetry>()
+                        if (seconds != null) {
+                            telemetry.fire(
+                                name = ProductTelemetryEvents.SESSION_DURATION,
+                                props = mapOf(ProductTelemetryProps.SECONDS to seconds.toString()),
+                            )
+                        }
+                        // Off-main bounded flush — ON_STOP runs on the main
+                        // thread, never block it on the network.
+                        appScope.launch {
+                            withTimeoutOrNull(2_000) { telemetry.flush() }
+                        }
+                    }
+
+                    else -> {
+                        Unit
+                    }
+                }
+            },
+        )
+    }
+
+    private fun installCrashTelemetryHandler() {
+        val previous = Thread.getDefaultUncaughtExceptionHandler()
+        Thread.setDefaultUncaughtExceptionHandler { thread, throwable ->
+            runCatching {
+                val telemetry = get<ProductTelemetry>()
+                telemetry.fire(
+                    name = ProductTelemetryEvents.CRASH,
+                    props =
+                        mapOf(
+                            ProductTelemetryProps.CATEGORY to categorizeCrash(throwable),
+                            ProductTelemetryProps.PLATFORM to "android",
+                        ),
+                )
+                runBlocking { withTimeoutOrNull(500) { telemetry.flush() } }
+            }
+            // When `previous` is null we still need to surface the crash —
+            // delegate to the thread's group so the JVM's default printout
+            // and exit behaviour kicks in instead of swallowing silently.
+            if (previous != null) {
+                previous.uncaughtException(thread, throwable)
+            } else {
+                thread.threadGroup?.uncaughtException(thread, throwable)
+            }
+        }
+    }
+
+    private fun fireAppLaunched() {
+        // platform + appVersion ride along on the event's top-level
+        // columns (set by ProductTelemetryImpl). The backend's PropsSchema
+        // allows no props on app_launched and silently strips anything
+        // we put here, so we don't.
+        get<ProductTelemetry>().fire(name = ProductTelemetryEvents.APP_LAUNCHED)
+    }
+
     private fun scheduleInitialExternalScan() {
         appScope.launch {
             runCatching {

composeApp/src/commonMain/kotlin/zed/rainxch/githubstore/Main.kt

@@ -7,10 +7,18 @@ import androidx.compose.runtime.getValue
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.navigation.compose.currentBackStackEntryAsState
 import androidx.navigation.compose.rememberNavController
+import org.koin.compose.koinInject
 import org.koin.compose.viewmodel.koinViewModel
+import zed.rainxch.core.domain.getPlatform
+import zed.rainxch.core.domain.model.Platform
+import zed.rainxch.core.domain.telemetry.ProductTelemetry
+import zed.rainxch.core.domain.telemetry.ProductTelemetryEvents
+import zed.rainxch.core.domain.telemetry.ProductTelemetryProps
+import zed.rainxch.core.domain.telemetry.TelemetryBuckets
 import zed.rainxch.core.presentation.theme.GithubStoreTheme
 import zed.rainxch.core.presentation.utils.ApplyAndroidSystemBars
 import zed.rainxch.core.presentation.utils.ObserveAsEvents
+import zed.rainxch.githubstore.app.ColdStart
 import zed.rainxch.githubstore.app.components.RateLimitDialog
 import zed.rainxch.githubstore.app.components.SessionExpiredDialog
 import zed.rainxch.githubstore.app.deeplink.DeepLinkDestination
@@ -25,10 +33,24 @@ import zed.rainxch.githubstore.app.navigation.getCurrentScreen
 fun App(deepLinkUri: String? = null) {
     val viewModel: MainViewModel = koinViewModel()
     val state by viewModel.state.collectAsStateWithLifecycle()
+    val productTelemetry: ProductTelemetry = koinInject()
 
     val navController = rememberNavController()
     val currentScreen = navController.currentBackStackEntryAsState().value.getCurrentScreen()
 
+    LaunchedEffect(Unit) {
+        ColdStart.consumeIfFirst()?.let { ms ->
+            productTelemetry.fire(
+                name = ProductTelemetryEvents.COLD_START_MS,
+                props =
+                    mapOf(
+                        ProductTelemetryProps.PLATFORM to platformSlug(),
+                        ProductTelemetryProps.BUCKET to TelemetryBuckets.durationMs(ms),
+                    ),
+            )
+        }
+    }
+
     LaunchedEffect(deepLinkUri) {
         deepLinkUri?.let { uri ->
             when (val destination = DeepLinkParser.parse(uri)) {
@@ -120,3 +142,11 @@ fun App(deepLinkUri: String? = null) {
         )
     }
 }
+
+private fun platformSlug(): String =
+    when (getPlatform()) {
+        Platform.ANDROID -> "android"
+        Platform.MACOS -> "macos"
+        Platform.WINDOWS -> "windows"
+        Platform.LINUX -> "linux"
+    }

composeApp/src/commonMain/kotlin/zed/rainxch/githubstore/app/ColdStart.kt

@@ -0,0 +1,22 @@
+package zed.rainxch.githubstore.app
+
+import kotlin.time.TimeSource
+
+object ColdStart {
+    private var mark: TimeSource.Monotonic.ValueTimeMark? = null
+    private var consumed: Boolean = false
+
+    fun markStart() {
+        if (mark == null) mark = TimeSource.Monotonic.markNow()
+    }
+
+    // Returns elapsed ms on the first call after [markStart], null thereafter.
+    // Single-process, single-shot — App composable consumes once on first frame.
+    fun consumeIfFirst(): Long? {
+        if (consumed) return null
+        consumed = true
+        return mark?.elapsedNow()?.inWholeMilliseconds
+    }
+
+    fun elapsedSeconds(): Long? = mark?.elapsedNow()?.inWholeSeconds
+}

composeApp/src/commonMain/kotlin/zed/rainxch/githubstore/app/CrashCategory.kt

@@ -0,0 +1,10 @@
+package zed.rainxch.githubstore.app
+
+fun categorizeCrash(throwable: Throwable): String =
+    when {
+        throwable is OutOfMemoryError -> "other"
+        throwable.message?.contains("DataStore", ignoreCase = true) == true -> "data_loss"
+        throwable.message?.contains("install", ignoreCase = true) == true -> "install_fail"
+        throwable.message?.contains("version", ignoreCase = true) == true -> "version_detect"
+        else -> "other"
+    }

composeApp/src/commonMain/kotlin/zed/rainxch/githubstore/app/di/ViewModelsModule.kt

@@ -9,6 +9,7 @@ import zed.rainxch.auth.presentation.AuthenticationViewModel
 import zed.rainxch.details.presentation.DetailsViewModel
 import zed.rainxch.devprofile.presentation.DeveloperProfileViewModel
 import zed.rainxch.favourites.presentation.FavouritesViewModel
+import zed.rainxch.home.presentation.HomeConsentGateViewModel
 import zed.rainxch.home.presentation.HomeViewModel
 import zed.rainxch.profile.presentation.ProfileViewModel
 import zed.rainxch.recentlyviewed.presentation.RecentlyViewedViewModel
@@ -31,6 +32,7 @@ val viewModelsModule =
                 ownerParam = params.get(1),
                 repoParam = params.get(2),
                 isComingFromUpdate = params.get(3),
+                from = params.get(4),
                 detailsRepository = get(),
                 downloader = get(),
                 installer = get(),
@@ -51,11 +53,13 @@ val viewModelsModule =
                 downloadOrchestrator = get(),
                 telemetryRepository = get(),
                 externalImportRepository = get(),
+                productTelemetry = get(),
             )
         }
         viewModelOf(::DeveloperProfileViewModel)
         viewModelOf(::FavouritesViewModel)
         viewModelOf(::HomeViewModel)
+        viewModelOf(::HomeConsentGateViewModel)
         viewModelOf(::RecentlyViewedViewModel)
         viewModelOf(::SearchViewModel)
         viewModelOf(::ProfileViewModel)

composeApp/src/commonMain/kotlin/zed/rainxch/githubstore/app/navigation/AppNavigation.kt

@@ -90,6 +90,7 @@ fun AppNavigation(
                             navController.navigate(
                                 GithubStoreGraph.DetailsScreen(
                                     repositoryId = repoId,
+                                    from = DetailsFrom.Category,
                                 ),
                             )
                         },
@@ -112,6 +113,7 @@ fun AppNavigation(
                             navController.navigate(
                                 GithubStoreGraph.DetailsScreen(
                                     repositoryId = repoId,
+                                    from = DetailsFrom.Search,
                                 ),
                             )
                         },
@@ -120,6 +122,7 @@ fun AppNavigation(
                                 GithubStoreGraph.DetailsScreen(
                                     owner = owner,
                                     repo = repo,
+                                    from = DetailsFrom.Link,
                                 ),
                             )
                         },
@@ -143,6 +146,7 @@ fun AppNavigation(
                             navController.navigate(
                                 GithubStoreGraph.DetailsScreen(
                                     repositoryId = repoId,
+                                    from = DetailsFrom.Link,
                                 ),
                             )
                         },
@@ -160,6 +164,7 @@ fun AppNavigation(
                                     args.owner,
                                     args.repo,
                                     args.isComingFromUpdate,
+                                    args.from.slug,
                                 )
                             },
                     )
@@ -175,6 +180,7 @@ fun AppNavigation(
                             navController.navigate(
                                 GithubStoreGraph.DetailsScreen(
                                     repositoryId = repoId,
+                                    from = DetailsFrom.Link,
                                 ),
                             )
                         },
@@ -203,7 +209,12 @@ fun AppNavigation(
                             navController.navigateUp()
                         },
                         onNavigateToDetails = {
-                            navController.navigate(GithubStoreGraph.DetailsScreen(it))
+                            navController.navigate(
+                                GithubStoreGraph.DetailsScreen(
+                                    repositoryId = it,
+                                    from = DetailsFrom.Library,
+                                ),
+                            )
                         },
                         onNavigateToDeveloperProfile = { username ->
                             navController.navigate(
@@ -224,6 +235,7 @@ fun AppNavigation(
                             navController.navigate(
                                 GithubStoreGraph.DetailsScreen(
                                     repositoryId = repoId,
+                                    from = DetailsFrom.Library,
                                 ),
                             )
                         },
@@ -277,6 +289,7 @@ fun AppNavigation(
                             navController.navigate(
                                 GithubStoreGraph.DetailsScreen(
                                     repositoryId = repoId,
+                                    from = DetailsFrom.Library,
                                 ),
                             )
                         },
@@ -323,6 +336,7 @@ fun AppNavigation(
                                 GithubStoreGraph.DetailsScreen(
                                     repositoryId = repoId,
                                     isComingFromUpdate = true,
+                                    from = DetailsFrom.Library,
                                 ),
                             )
                         },
@@ -344,6 +358,7 @@ fun AppNavigation(
                                 GithubStoreGraph.DetailsScreen(
                                     repositoryId = repoId,
                                     isComingFromUpdate = true,
+                                    from = DetailsFrom.Library,
                                 ),
                             )
                         },

composeApp/src/commonMain/kotlin/zed/rainxch/githubstore/app/navigation/GithubStoreGraph.kt

@@ -2,6 +2,18 @@ package zed.rainxch.githubstore.app.navigation
 
 import kotlinx.serialization.Serializable
 
+// E6 telemetry: where a Details nav originated. Closed set so the
+// FROM prop on DETAILS_VIEWED can never carry an arbitrary string.
+@Serializable
+enum class DetailsFrom(
+    val slug: String,
+) {
+    Search("search"),
+    Category("category"),
+    Library("library"),
+    Link("link"),
+}
+
 @Serializable
 sealed interface GithubStoreGraph {
     @Serializable
@@ -19,6 +31,9 @@ sealed interface GithubStoreGraph {
         val owner: String = "",
         val repo: String = "",
         val isComingFromUpdate: Boolean = false,
+        // Drives the FROM prop on DETAILS_VIEWED. Typed so callers
+        // can't accidentally introduce off-allowlist values.
+        val from: DetailsFrom = DetailsFrom.Link,
     ) : GithubStoreGraph
 
     @Serializable