create-cmp-cli 0.8.0 → 0.9.0

package/template/composeApp/src/androidDebug/kotlin/com/example/app/inspector/CrashRecorder.kt

@@ -0,0 +1,99 @@
+package __PACKAGE__.inspector
+
+import android.content.Context
+import android.util.Log
+import java.io.File
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonArray
+import kotlinx.serialization.json.buildJsonObject
+
+/**
+ * Debug-only crash capture: [install] sets a process-wide
+ * [Thread.UncaughtExceptionHandler] that persists crash JSON to
+ * `filesDir/inspector/crashes/` (bounded to the last [MAX_CRASHES]) so a crash survives the
+ * process death that follows it — an in-memory ring buffer would not.
+ *
+ * MUST NEVER SWALLOW THE CRASH: after persisting, it always hands off to whatever handler was
+ * installed before it (chained, not replaced) so system crash dialogs, `System.exit`, and any
+ * other crash-reporting tool still behave exactly as if this class did not exist.
+ */
+object CrashRecorder {
+
+    private const val TAG = "CmpInspector"
+    private const val MAX_CRASHES = 20
+
+    fun install(context: Context) {
+        val crashDir = File(context.filesDir, "inspector/crashes").apply { mkdirs() }
+        val previous = Thread.getDefaultUncaughtExceptionHandler()
+        Thread.setDefaultUncaughtExceptionHandler { thread, throwable ->
+            try {
+                persist(crashDir, throwable)
+            } catch (t: Throwable) {
+                // Persisting the crash record must never itself crash the crash handler.
+                Log.w(TAG, "failed to persist crash record", t)
+            } finally {
+                if (previous != null) {
+                    previous.uncaughtException(thread, throwable)
+                } else {
+                    // No previous handler installed: fall back to the JVM's own default so the
+                    // process still dies the normal way instead of hanging.
+                    Runtime.getRuntime().exit(10)
+                }
+            }
+        }
+    }
+
+    private fun persist(crashDir: File, throwable: Throwable) {
+        val doc = buildJsonObject {
+            put("timestamp", JsonPrimitive(isoNow()))
+            put("exception", JsonPrimitive(throwable::class.qualifiedName ?: throwable.javaClass.name))
+            put("message", throwable.message?.let { JsonPrimitive(it) } ?: JsonNull)
+            put("frames", buildJsonArray {
+                throwable.stackTrace.forEach { el ->
+                    add(buildJsonObject {
+                        put("className", JsonPrimitive(el.className))
+                        put("methodName", JsonPrimitive(el.methodName))
+                        put("fileName", el.fileName?.let { JsonPrimitive(it) } ?: JsonNull)
+                        put("lineNumber", JsonPrimitive(el.lineNumber))
+                    })
+                }
+            })
+        }
+        File(crashDir, "crash-${System.currentTimeMillis()}.json")
+            .writeText(Json.encodeToString(JsonElement.serializer(), doc))
+        prune(crashDir)
+    }
+
+    /** Keep only the most recent [MAX_CRASHES] crash files (current boot + previous ones). */
+    private fun prune(crashDir: File) {
+        val files = crashDir.listFiles { f -> f.isFile && f.name.endsWith(".json") } ?: return
+        if (files.size <= MAX_CRASHES) return
+        files.sortedBy { it.lastModified() }
+            .take(files.size - MAX_CRASHES)
+            .forEach { it.delete() }
+    }
+
+    /**
+     * Every persisted crash's raw JSON text, newest first — spans the current boot AND any
+     * previous ones ([install] never clears the directory, only [prune] bounds it).
+     */
+    fun readAll(context: Context): List<String> {
+        val crashDir = File(context.filesDir, "inspector/crashes")
+        val files = crashDir.listFiles { f -> f.isFile && f.name.endsWith(".json") } ?: return emptyList()
+        return files.sortedByDescending { it.lastModified() }
+            .mapNotNull { runCatching { it.readText() }.getOrNull() }
+    }
+
+    private fun isoNow(): String {
+        val fmt = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US)
+        fmt.timeZone = TimeZone.getTimeZone("UTC")
+        return fmt.format(Date())
+    }
+}

package/template/composeApp/src/androidDebug/kotlin/com/example/app/inspector/DbInspector.kt

@@ -0,0 +1,144 @@
+package __PACKAGE__.inspector
+
+// >>> cmp:feature room
+import __PACKAGE__.data.local.AppDatabase
+import androidx.room.useReaderConnection
+import kotlinx.coroutines.runBlocking
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonArray
+import kotlinx.serialization.json.buildJsonObject
+import org.koin.core.context.GlobalContext
+// <<< cmp:feature room
+
+/**
+ * `GET /inspect/db` (schema: tables via `sqlite_master`) and `GET /inspect/db?table=<name>&limit=<n>`
+ * (rows). Read-only, off the main thread. 404 when this project's local-database feature is off
+ * (there is nothing to query) — see the `room`-gated implementation below for the real path.
+ */
+object DbInspector {
+
+    // >>> cmp:feature room
+    // Reads go through the project's Room database (a Koin single). Injection-safe by
+    // construction: a requested `table` is only ever used in a query after it is proven to be
+    // a real name returned by `sqlite_master` in THIS call — the raw wire value never reaches
+    // SQL beyond that validated identifier.
+    //
+    // This project's Room config uses the KMP driver architecture (BundledSQLiteDriver, see
+    // data/local/DatabaseBuilder.kt), not the legacy Android-only SupportSQLiteDatabase — so
+    // reads go through Room 2.8's public `useReaderConnection { transactor -> ... }` whose
+    // receiver is a pooled connection exposing `usePrepared(sql) { stmt -> ... }` (the
+    // statement is created and closed by Room; binds are 1-based, column reads 0-based).
+    private const val DEFAULT_ROW_LIMIT = 50
+    private const val MAX_ROW_LIMIT = 500
+    private val VALID_IDENTIFIER = Regex("^[A-Za-z_][A-Za-z0-9_]*$")
+    private val prettyJson = Json { prettyPrint = true }
+
+    private fun appDatabaseOrNull(): AppDatabase? =
+        try {
+            // GlobalContext.getOrNull() IS the Koin instance (or null before startKoin).
+            GlobalContext.getOrNull()?.getOrNull<AppDatabase>()
+        } catch (t: Throwable) {
+            null
+        }
+
+    fun schema(): Pair<Int, String> {
+        val db = appDatabaseOrNull()
+            ?: return 503 to errorJson("database not available yet (Room not initialised — is Koin started?).")
+        return try {
+            val tables = runBlocking {
+                db.useReaderConnection { connection ->
+                    connection.usePrepared(
+                        "SELECT name, sql FROM sqlite_master WHERE type = 'table' " +
+                            "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'room_%' ORDER BY name"
+                    ) { stmt ->
+                        val out = mutableListOf<Pair<String, String?>>()
+                        while (stmt.step()) {
+                            out += stmt.getText(0) to (if (stmt.isNull(1)) null else stmt.getText(1))
+                        }
+                        out
+                    }
+                }
+            }
+            200 to prettyJson.encodeToString(JsonElement.serializer(), buildJsonObject {
+                put("tables", buildJsonArray {
+                    tables.forEach { (name, sql) ->
+                        add(buildJsonObject {
+                            put("name", JsonPrimitive(name))
+                            put("sql", sql?.let { JsonPrimitive(it) } ?: JsonNull)
+                        })
+                    }
+                })
+            })
+        } catch (t: Throwable) {
+            500 to errorJson("failed to read schema: ${t.message}")
+        }
+    }
+
+    /** Row page for one table: columns + stringified values, capped. */
+    private class TableRows(val columns: List<String>, val rows: List<JsonElement>)
+
+    fun rows(table: String, limitParam: String?): Pair<Int, String> {
+        if (!VALID_IDENTIFIER.matches(table)) {
+            return 400 to errorJson("invalid table name '$table' — expected a plain SQL identifier.")
+        }
+        val db = appDatabaseOrNull()
+            ?: return 503 to errorJson("database not available yet (Room not initialised — is Koin started?).")
+        val limit = (limitParam?.toIntOrNull() ?: DEFAULT_ROW_LIMIT).coerceIn(1, MAX_ROW_LIMIT)
+        return try {
+            val result: TableRows? = runBlocking {
+                db.useReaderConnection { connection ->
+                    // STRICT validation: `table` is only used in the row query below once THIS
+                    // check proves it is a real sqlite_master identifier — never the raw wire value.
+                    val exists = connection.usePrepared(
+                        "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?"
+                    ) { stmt ->
+                        stmt.bindText(1, table)
+                        stmt.step()
+                    }
+                    if (!exists) return@useReaderConnection null
+
+                    connection.usePrepared("SELECT * FROM \"$table\" LIMIT ?") { stmt ->
+                        stmt.bindLong(1, limit.toLong())
+                        val colCount = stmt.getColumnCount()
+                        val columns = (0 until colCount).map { stmt.getColumnName(it) }
+                        val rows = mutableListOf<JsonElement>()
+                        while (stmt.step()) {
+                            rows += buildJsonObject {
+                                for (i in 0 until colCount) {
+                                    put(columns[i], if (stmt.isNull(i)) JsonNull else JsonPrimitive(stmt.getText(i)))
+                                }
+                            }
+                        }
+                        TableRows(columns, rows)
+                    }
+                }
+            }
+            if (result == null) {
+                return 404 to errorJson("unknown table '$table' — not present in sqlite_master.")
+            }
+            200 to prettyJson.encodeToString(JsonElement.serializer(), buildJsonObject {
+                put("table", JsonPrimitive(table))
+                put("columns", buildJsonArray { result.columns.forEach { add(JsonPrimitive(it)) } })
+                put("rows", buildJsonArray { result.rows.forEach { add(it) } })
+                put("rowCount", JsonPrimitive(result.rows.size))
+            })
+        } catch (t: Throwable) {
+            500 to errorJson("failed to read table '$table': ${t.message}")
+        }
+    }
+
+    private fun errorJson(message: String): String =
+        """{"error":${JsonPrimitive(message)}}"""
+    // <<< cmp:feature room
+    // >>> cmp:feature !room
+    private const val DISABLED_MESSAGE =
+        "the 'room' feature is disabled in this project — /inspect/db is unavailable."
+
+    fun schema(): Pair<Int, String> = 404 to """{"error":"$DISABLED_MESSAGE"}"""
+
+    fun rows(table: String, limitParam: String?): Pair<Int, String> = schema()
+    // <<< cmp:feature !room
+}

package/template/composeApp/src/androidDebug/kotlin/com/example/app/inspector/InspectorHttpServer.kt

@@ -1,5 +1,6 @@
 package __PACKAGE__.inspector
 
+import android.content.Context
 import android.graphics.Bitmap
 import android.graphics.Canvas
 import android.os.Handler
@@ -14,6 +15,7 @@ import java.io.InputStreamReader
 import java.net.InetAddress
 import java.net.ServerSocket
 import java.net.Socket
+import java.net.URLDecoder
 import java.nio.charset.StandardCharsets
 import java.util.concurrent.CountDownLatch
 import java.util.concurrent.TimeUnit
@@ -43,6 +45,15 @@ import kotlin.math.roundToInt
  *                                  pair to the root view → {"tapped":true,"x":…,"y":…}.
  *   GET  /inspect/remote         → the self-contained remote-control HTML page (same-origin,
  *                                  zero CORS): live screenshot + click-to-tap in a browser.
+ *   GET  /inspect/nav            → { currentRoute, backStack } — best-effort, reported by the
+ *                                  common `NavInspectionHook` seam; empty snapshot before the
+ *                                  first navigation event (see [NavInspector]).
+ *   GET  /inspect/crashes        → { crashes: [...] } — persisted crash JSON (current boot +
+ *                                  previous ones), newest first (see [CrashRecorder]).
+ *   GET  /inspect/db             → schema: { tables:[{name,sql}] } via `sqlite_master`.
+ *   GET  /inspect/db?table=<n>&limit=<n> → rows for one table (read-only, bounded; see
+ *                                  [DbInspector]). 404 (or empty schema) when the project's
+ *                                  `room` feature is off.
  *
  * Single-threaded accept loop on a daemon thread = one client at a time = bounded by design.
  * Failure to bind logs a warning and gives up — the inspector must never crash or block
@@ -67,9 +78,14 @@ object InspectorHttpServer {
 
     @Volatile private var started = false
 
-    fun start(appId: String) {
+    // Set once in [start]; read from the HTTP thread only (crashes/db routes). applicationContext
+    // is safe to hold — it never leaks an Activity.
+    @Volatile private var appContext: Context? = null
+
+    fun start(appId: String, context: Context) {
         if (started) return
         started = true
+        appContext = context.applicationContext
         val thread = Thread({ serve(appId) }, "cmp-inspector-http")
         thread.isDaemon = true
         thread.start()
@@ -114,7 +130,9 @@ object InspectorHttpServer {
         }
         val parts = requestLine.split(" ")
         val method = parts.getOrNull(0) ?: ""
-        val path = (parts.getOrNull(1) ?: "").substringBefore('?')
+        val rawTarget = parts.getOrNull(1) ?: ""
+        val path = rawTarget.substringBefore('?')
+        val query = rawTarget.substringAfter('?', "")
 
         when {
             method == "GET" && path == "/inspect/health" ->
@@ -129,6 +147,12 @@ object InspectorHttpServer {
                 writeResponse(client, 200, RemoteControlPage.html(appId).toByteArray(StandardCharsets.UTF_8), HTML_TYPE)
             method == "POST" && path == "/inspect/tap" ->
                 tapResponse(readBody(reader, contentLength)).let { (s, b) -> writeJson(client, s, b) }
+            method == "GET" && path == "/inspect/nav" ->
+                writeJson(client, 200, navJson())
+            method == "GET" && path == "/inspect/crashes" ->
+                writeJson(client, 200, crashesJson())
+            method == "GET" && path == "/inspect/db" ->
+                dbResponse(query).let { (s, b) -> writeJson(client, s, b) }
             method != "GET" && method != "POST" ->
                 writeJson(client, 405, errorJson("method not allowed"))
             else ->
@@ -183,6 +207,49 @@ object InspectorHttpServer {
         }
     }
 
+    /** { currentRoute, backStack } from [NavInspector] — best-effort, never blocks. */
+    private fun navJson(): String {
+        val snapshot = NavInspector.current()
+        val currentRouteJson = snapshot.currentRoute?.let { JsonPrimitive(it).toString() } ?: "null"
+        val backStackJson = snapshot.backStack.joinToString(",") { JsonPrimitive(it).toString() }
+        return """{"currentRoute":$currentRouteJson,"backStack":[$backStackJson]}"""
+    }
+
+    /** { crashes:[...] } — each element is a persisted crash JSON document, verbatim. */
+    private fun crashesJson(): String {
+        val ctx = appContext ?: return """{"crashes":[]}"""
+        val crashes = CrashRecorder.readAll(ctx)
+        return """{"crashes":[${crashes.joinToString(",")}]}"""
+    }
+
+    /** GET /inspect/db dispatch: no `table` → schema, else → rows for that table. */
+    private fun dbResponse(query: String): Pair<Int, String> {
+        val params = parseQuery(query)
+        val table = params["table"]
+        return if (table == null) DbInspector.schema() else DbInspector.rows(table, params["limit"])
+    }
+
+    /** Minimal `a=b&c=d` query-string parser (URL-decoded values). Last value wins on repeats. */
+    private fun parseQuery(query: String): Map<String, String> {
+        if (query.isEmpty()) return emptyMap()
+        val out = mutableMapOf<String, String>()
+        for (pair in query.split("&")) {
+            if (pair.isEmpty()) continue
+            val eq = pair.indexOf('=')
+            val key = if (eq >= 0) pair.substring(0, eq) else pair
+            val value = if (eq >= 0) pair.substring(eq + 1) else ""
+            out[urlDecode(key)] = urlDecode(value)
+        }
+        return out
+    }
+
+    private fun urlDecode(s: String): String =
+        try {
+            URLDecoder.decode(s, "UTF-8")
+        } catch (t: Throwable) {
+            s
+        }
+
     /**
      * PNG of the current Compose root. The Bitmap is rendered on the MAIN thread (views are
      * not thread-safe); PNG compression — tens of ms for a full screen — happens back on the

package/template/composeApp/src/androidDebug/kotlin/com/example/app/inspector/InspectorInit.kt

@@ -3,14 +3,18 @@ package __PACKAGE__.inspector
 import android.app.Application
 
 /**
- * DEBUG variant: install the Compose root registry (must happen BEFORE any Activity so the
- * `onViewCreatedCallback` hook catches every root), then start the loopback-only inspection
- * server on 127.0.0.1:9500. Reach it from the host via `adb forward tcp:9500 tcp:9500`.
+ * DEBUG variant: install the Compose root registry and the nav-inspection listener (both must
+ * happen BEFORE any Activity — the registry so `onViewCreatedCallback` catches every root, the
+ * nav listener so the first `AppNavHost` composition is observed), chain in the crash recorder,
+ * then start the loopback-only inspection server on 127.0.0.1:9500. Reach it from the host via
+ * `adb forward tcp:9500 tcp:9500`.
  *
  * The release source set carries a same-signature no-op twin — the compiler picks the variant
  * body, so release builds contain no inspector code at all (structural absence, not a flag).
  */
 fun Application.startInspector() {
     ComposeRootRegistry.install()
-    InspectorHttpServer.start(appId = packageName)
+    NavInspector.install()
+    CrashRecorder.install(this)
+    InspectorHttpServer.start(appId = packageName, context = this)
 }

package/template/composeApp/src/androidDebug/kotlin/com/example/app/inspector/NavInspector.kt

@@ -0,0 +1,31 @@
+package __PACKAGE__.inspector
+
+import __PACKAGE__.presentation.navigation.NavInspectionHook
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Debug-only sink for [NavInspectionHook]: [install] registers a listener that stores the
+ * latest route/back-stack snapshot the common `AppNavHost` reports, so `GET /inspect/nav` can
+ * read it synchronously from the HTTP thread without touching Compose state directly.
+ *
+ * Best-effort by design: until the first navigation event fires (cold start, before
+ * `AppNavHost` has composed at least once), [current] reports an empty snapshot rather than
+ * blocking or erroring — mirrors the tree/screenshot routes' "not ready yet, retry" posture,
+ * just without the 503 (an empty nav snapshot is a valid, if uninteresting, answer).
+ */
+object NavInspector {
+
+    data class Snapshot(val currentRoute: String?, val backStack: List<String>)
+
+    private val EMPTY = Snapshot(currentRoute = null, backStack = emptyList())
+    private val state = AtomicReference(EMPTY)
+
+    /** Must run before the first Activity's setContent — same timing rule as [ComposeRootRegistry]. */
+    fun install() {
+        NavInspectionHook.listener = { current, backStack ->
+            state.set(Snapshot(current, backStack))
+        }
+    }
+
+    fun current(): Snapshot = state.get()
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/data/AppResultCatching.kt

@@ -0,0 +1,32 @@
+package __PACKAGE__.data
+
+import __PACKAGE__.domain.model.DomainError
+import __PACKAGE__.domain.result.AppResult
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * The data layer's ONLY exception-catching mechanism (`specs/app-base.spec.md` ARCH-08).
+ * Repository implementations wrap their I/O in this instead of writing `try`/`catch` —
+ * it is the single translation point where infrastructure exceptions become typed
+ * [DomainError] values, and it enforces the one non-negotiable rule of coroutine error
+ * handling:
+ *
+ * **`CancellationException` is ALWAYS rethrown, never mapped.** Swallowing it breaks
+ * structured concurrency — a cancelled screen would render an error state instead of
+ * simply stopping. The conformance gate scans for exactly this guard.
+ *
+ * [mapError] classifies everything else into your [DomainError] vocabulary; the default
+ * files anything unclassified under [DomainError.Unexpected] with the cause preserved
+ * for logging (never for display).
+ */
+suspend fun <T> suspendRunCatching(
+    mapError: (Throwable) -> DomainError = { DomainError.Unexpected(it) },
+    block: suspend () -> T,
+): AppResult<T> =
+    try {
+        AppResult.Success(block())
+    } catch (e: CancellationException) {
+        throw e // never mapped: cancellation is not a failure state
+    } catch (e: Throwable) {
+        AppResult.Failure(mapError(e))
+    }

package/template/composeApp/src/commonMain/kotlin/com/example/app/data/remote/ItemRepositoryImpl.kt

@@ -1,7 +1,9 @@
 package __PACKAGE__.data.remote
 
+import __PACKAGE__.data.suspendRunCatching
 import __PACKAGE__.domain.model.Item
 import __PACKAGE__.domain.repository.ItemRepository
+import __PACKAGE__.domain.result.AppResult
 import kotlinx.coroutines.delay
 
 // Example data source for the `home` feature. This is intentionally dependency-light
@@ -9,10 +11,15 @@ import kotlinx.coroutines.delay
 //
 // Real apps swap this for a Firestore/Ktor source and add a Room cache (see data/local).
 // The Clean Architecture seam is the ItemRepository interface in the domain layer.
+//
+// The repository is the ONLY exception-translation point: I/O runs inside
+// suspendRunCatching (data/AppResultCatching.kt), which maps infrastructure exceptions
+// to typed DomainError values and ALWAYS rethrows CancellationException. Pass a mapError
+// lambda to classify your real source's exceptions (IOException -> Network, etc).
 class ItemRepositoryImpl : ItemRepository {
-    override suspend fun getItems(): List<Item> {
+    override suspend fun getItems(): AppResult<List<Item>> = suspendRunCatching {
         delay(300) // simulate I/O
-        return listOf(
+        listOf(
             Item("1", "Welcome to __APP_NAME__", "Your Compose Multiplatform app is wired end-to-end."),
             Item("2", "Clean Architecture", "presentation → domain → data, with Koin DI."),
             Item("3", "Edge-to-edge, pre-solved", "BaseScreen owns the window insets for you."),

package/template/composeApp/src/commonMain/kotlin/com/example/app/domain/model/DomainError.kt

@@ -0,0 +1,21 @@
+package __PACKAGE__.domain.model
+
+/**
+ * The typed failure vocabulary of the domain layer — every failure a repository can report
+ * is one of these KINDS. No user-facing message strings live here: mapping a kind to copy
+ * is the presentation layer's job (see the exemplar ViewModel's `toUserMessage()`), so the
+ * domain stays translatable and UI-copy changes never touch this layer.
+ *
+ * Extend with the kinds YOUR sources can actually produce (e.g. `Unauthorized`, `Conflict`)
+ * — the data layer's `suspendRunCatching` mapper is the single place they are assigned.
+ */
+sealed interface DomainError {
+    /** The source was unreachable — connectivity, DNS, timeouts. */
+    data object Network : DomainError
+
+    /** The requested entity does not exist at the source. */
+    data object NotFound : DomainError
+
+    /** Anything not yet classified. Carries the cause for logging — never for display. */
+    data class Unexpected(val cause: Throwable? = null) : DomainError
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/domain/repository/ItemRepository.kt

@@ -1,8 +1,11 @@
 package __PACKAGE__.domain.repository
 
 import __PACKAGE__.domain.model.Item
+import __PACKAGE__.domain.result.AppResult
 
 // Domain-facing contract. Presentation depends on THIS, never on a concrete data source.
+// One-shot operations return AppResult — they never throw (ARCH-06): failures cross the
+// boundary as typed DomainError values, translated inside the data implementation.
 interface ItemRepository {
-    suspend fun getItems(): List<Item>
+    suspend fun getItems(): AppResult<List<Item>>
 }

package/template/composeApp/src/commonMain/kotlin/com/example/app/domain/result/AppResult.kt

@@ -0,0 +1,23 @@
+package __PACKAGE__.domain.result
+
+import __PACKAGE__.domain.model.DomainError
+
+/**
+ * The typed result that crosses the data → domain → presentation boundary. One-shot
+ * repository operations return `AppResult<T>`, never throw (`specs/app-base.spec.md`
+ * ARCH-06) — so a ViewModel exhaustively `when`s over Success/Failure instead of
+ * catching exceptions (ARCH-07).
+ *
+ * Deliberately our own type rather than `kotlin.Result`: the stdlib Result carries an
+ * untyped Throwable, which would put raw exceptions right back on the boundary this
+ * type exists to keep them off. A [Failure] carries a typed [DomainError] kind instead
+ * (the same call Now in Android makes with its own Result).
+ *
+ * Cancellation is NOT a result: `CancellationException` propagates (structured
+ * concurrency), enforced at the single translation point — `suspendRunCatching` in
+ * `data/AppResultCatching.kt` (ARCH-08).
+ */
+sealed interface AppResult<out T> {
+    data class Success<out T>(val value: T) : AppResult<T>
+    data class Failure(val error: DomainError) : AppResult<Nothing>
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/domain/usecase/GetItemsUseCase.kt

@@ -2,11 +2,14 @@ package __PACKAGE__.domain.usecase
 
 import __PACKAGE__.domain.model.Item
 import __PACKAGE__.domain.repository.ItemRepository
+import __PACKAGE__.domain.result.AppResult
 
 // A use case is a single business action. ViewModels depend on use cases, not repositories
 // directly, so business rules stay testable and out of the presentation layer.
+// The typed result passes through untouched — a use case may combine or transform results,
+// but it never unwraps them into exceptions.
 class GetItemsUseCase(
     private val repository: ItemRepository,
 ) {
-    suspend operator fun invoke(): List<Item> = repository.getItems()
+    suspend operator fun invoke(): AppResult<List<Item>> = repository.getItems()
 }