oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-mobile/variants/flutter/stack.yaml

@@ -0,0 +1,21 @@
+# yaml-language-server: $schema=../stack.schema.json
+language: flutter
+framework: flutter
+ui: material3
+state: riverpod
+navigation: gorouter
+http_client: dio
+local_storage: drift
+response_cache: drift-offline-repo
+structure: lib/core/features/shared
+source: variant
+
+verify:
+  detect: pubspec.yaml
+  syntax:
+    cmd: "dart analyze"
+    skip_if_missing: dart
+  tests:
+    cmd: "flutter test"
+    pass_signal: "All tests passed"
+    skip_if_missing: flutter

package/skills/oma-mobile/variants/flutter/tech-stack.md

@@ -0,0 +1,201 @@
+# Mobile Agent - Tech Stack Reference (Flutter)
+
+Starter reference for the selected platform. Preserve existing project choices. The caching implementation below applies only when caching is required; do not add it for an unrelated screen or widget change.
+
+## Framework + State Management
+
+- **Language**: Dart 3.10+
+- **UI Framework**: Flutter 3.44+
+- **UI Toolkit**: Material Design 3 (Android) + iOS HIG adaptations via `CupertinoAdaptiveTheme` or `Platform.isIOS` guards
+- **State Management**: Riverpod 3.x with `@riverpod` code generation (`AsyncNotifier`, `Notifier`, `StreamNotifier`)
+- **Concurrency**: Dart async/await, `Stream`, `StreamController`, structured cancellation via `ref.onDispose`
+- **Minimum SDK**: Flutter 3.44 / Dart 3.10 / Android API 24 / iOS 16
+
+Riverpod 3.x with `@riverpod` codegen replaces manual `StateNotifierProvider` and hand-written provider constants. The code generator emits typed, cancellation-safe notifier subclasses at build time (`AsyncNotifier` for `Future` builds, `StreamNotifier` for `Stream` builds). Riverpod 3 drops the generated `FooRef` typedefs — provider and notifier build signatures take the unified `Ref` type. Provider state is disposed automatically when the last listener is removed; side-effectful providers use `ref.onDispose` to cancel in-flight requests.
+
+## HTTP / API Client: Dio with Interceptors
+
+| Component | Package |
+|-----------|---------|
+| HTTP transport | `dio` |
+| Auth interceptor | custom `AuthInterceptor` (injects Bearer token) |
+| Retry interceptor | custom `RetryInterceptor` (exponential back-off) |
+| Logging interceptor | `pretty_dio_logger` (debug builds only) |
+
+Dio is the **transport layer only**. Interceptors handle cross-cutting concerns (auth injection, retry, logging) — they must never cache or interpret domain objects. All Dio interceptors operate on raw `RequestOptions` / `Response` bytes. Domain-level caching belongs exclusively at the Repository layer (see below).
+
+```
+Presentation (Riverpod provider)
+  |  calls
+  v
+Repository (data layer)  ──reads/writes──►  Local Cache (Drift table)
+  |  on miss / revalidate
+  v
+RemoteDataSource  (Dio)  ──HTTP──►  Backend REST API
+```
+
+## Response Cache: Offline-First Repository (Drift)
+
+When response caching is required, implement it at the Repository (data) layer, using a Drift database table as the local cache. The cache stores **decoded domain entities** — never raw HTTP bytes or JSON strings. The Dio client and its interceptors are never cache-aware.
+
+**Placement rule — Repository layer, not transport.** Do **not** add a Dio cache interceptor (e.g. `dio_http_cache`, `dio_cache_interceptor`) as the system of record for domain reads. Such interceptors operate on raw bytes, making them invisible to the domain and untestable at the business-logic level. Cache the typed result *after* decoding instead.
+
+```
+View (Flutter Widget)
+  |  watches
+  v
+Riverpod StreamNotifier  (features/<feature>/presentation/)
+  |  calls
+  v
+Repository interface    (features/<feature>/domain/)
+  |  reads/writes (stale-while-revalidate)
+  +──────────────────►  Drift table (local cache of decoded entities)
+  |  on miss / revalidate
+  v
+RemoteDataSource / Dio  (features/<feature>/data/)
+  |  HTTP
+  v
+Backend REST API
+```
+
+**Mandatory rules:**
+
+1. Every read operation goes through the Repository, which queries Drift first and returns a `Stream` (or `Future`) of cached entities. The Repository then triggers a background network revalidation and upserts the result back into Drift — the stream re-emits automatically.
+2. Cache **key** = logical operation ID + a stable hash of its parameters (e.g., `"todos"`, `"todo:$id"`). Never key on URLs or raw path strings.
+3. Apply a **stale-while-revalidate** policy: emit the locally-cached rows immediately (instant render), then fetch from the network, upsert into Drift, and let the stream re-emit the fresh rows. Store an explicit `cachedAt` timestamp column; check it against a per-resource TTL before deciding to revalidate.
+4. Any **write** (create / update / delete) must upsert or delete the affected Drift rows after a successful network response, so the next stream emission reflects the change immediately without a separate read round-trip.
+5. Drift is for transient **server-owned** data caches (and optionally durable user-owned data). **Secrets** (tokens, credentials) still belong in `flutter_secure_storage`. Do not use the cache table as a system of record for user-authored drafts — use a separate Drift table with a different retention policy.
+
+See `snippets.md §3` for the canonical offline-first repository and `snippets.md §4` for the Riverpod `StreamNotifier` consuming it.
+
+## Local Storage
+
+| Library | Purpose |
+|---------|---------|
+| `drift` | Durable structured persistence (system-of-record user data **and** the offline response cache table) |
+| `flutter_secure_storage` | Tokens, credentials, and secrets |
+| `shared_preferences` | Lightweight key-value preferences (theme, locale, flags) |
+| `hive` / `hive_flutter` | Lightweight alternative to Drift for simple caches where SQL is unnecessary |
+
+**Drift vs Hive for the cache table:** Drift is the default because it provides SQL queries, type-safe DAOs, and Dart `Stream`s that auto-emit on row changes — exactly what the stale-while-revalidate pattern needs. Use Hive when the cached type is a simple flat object and you want to avoid the Drift codegen dependency. Either way, the Repository interface is unchanged; only the impl swaps out. This stack uses Drift (`response_cache: drift-offline-repo`).
+
+## Testing
+
+| Layer | Framework |
+|-------|-----------|
+| Unit (domain + repository) | `flutter_test` + `mocktail` |
+| Widget | `flutter_test` (`WidgetTester`) |
+| Integration | `integration_test` package |
+| E2E | Maestro (`maestro test`) |
+
+Mock the `Repository` **interface** (abstract class), not the concrete implementation or Dio. `mocktail` stubs are preferred over hand-written fakes for brevity, but both are acceptable. Never mock Drift internals — test the real Drift DB in-memory (`NativeDatabase.memory()`) for repository-layer tests.
+
+Run tests with `flutter test` (unit + widget) and `flutter test integration_test/` (integration). Maestro `.yaml` flow files live in `maestro/` at the project root; see `snippets.md §11` for a runnable launch → add → assert flow.
+
+## Project Layout
+
+```
+my_app/
+  pubspec.yaml                            # deps + build_runner config
+  pubspec.lock
+  build.yaml                              # build_runner options (riverpod_generator, drift)
+  maestro/                                # Maestro E2E flow files
+    todos_flow.yaml
+  lib/
+    main.dart                             # runApp entry; ProviderScope at root
+    core/
+      di/
+        providers.dart                    # App-wide singleton providers (Dio, DB, SecureStorage)
+      network/
+        dio_client.dart                   # Dio factory + AuthInterceptor + RetryInterceptor (all in one file; see §5)
+      database/
+        app_database.dart                 # Drift @DriftDatabase definition
+        app_database.g.dart               # generated
+      router/
+        app_router.dart                   # GoRouter typed routes
+        app_router.g.dart                 # generated (go_router_builder)
+      theme/
+        app_theme.dart
+    features/
+      todos/
+        domain/
+          todo.dart                       # Domain entity (freezed or plain Dart)
+          todo_repository.dart            # Abstract repository interface
+        data/
+          dtos/
+            todo_dto.dart                 # JSON <-> entity mapping
+          local/
+            todos_dao.dart                # Drift DAO for todos cache table
+            todos_dao.g.dart              # generated
+          remote/
+            todos_remote_data_source.dart # Dio calls
+          todo_repository_impl.dart       # Offline-first impl; cache + remote
+        presentation/
+          providers/
+            todos_provider.dart           # @riverpod StreamNotifier
+            todos_provider.g.dart         # generated
+          screens/
+            todos_screen.dart
+            todo_detail_screen.dart
+          widgets/
+            todo_list_item.dart
+    shared/
+      widgets/
+        loading_indicator.dart
+        empty_state.dart
+        error_view.dart
+  test/
+    features/
+      todos/
+        todo_repository_impl_test.dart    # in-memory Drift DB
+        todos_provider_test.dart          # mocked repository interface
+        todos_screen_test.dart            # WidgetTester
+  integration_test/
+    todos_integration_test.dart
+```
+
+## Architecture Pattern
+
+```
+todos_screen.dart  (ConsumerWidget)
+  |  ref.watch(todosProvider)
+  v
+todosProvider  (@riverpod StreamNotifier<List<Todo>>)
+  |  ref.watch(todoRepositoryProvider)
+  v
+TodoRepository  (abstract interface in domain/)
+  |  watchAll() · findById(id) · create(title) · toggle(id) · delete(id)
+  |  implemented by TodoRepositoryImpl (data/)
+  |
+  +──── TodosDao (Drift)  ◄──────── local cache of decoded Todo entities
+  |       Stream<List<TodosTableData>> watchAll()
+  |       Future<TodosTableData?> findById(int id)
+  |       Future<void> replaceAll(List<TodosTableCompanion>)   // mirrors full server list
+  |       Future<void> upsertOne(TodosTableCompanion)
+  |       Future<void> deleteById(int id)
+  |
+  +──── TodosRemoteDataSource (Dio)
+          Future<List<TodoDto>> fetchAll()
+          Future<TodoDto> fetchById(int id)
+          Future<TodoDto> create(String title)
+          Future<TodoDto> toggle(int id)
+          Future<void> delete(int id)
+```
+
+Each `features/<name>/` folder is a vertical slice owning its domain, data, and presentation sub-layers. `shared/` holds stateless reusable widgets with no feature knowledge. `core/` holds app-wide infrastructure (Dio, Drift DB, GoRouter, DI providers).
+
+The `@riverpod` notifier calls the repository directly — there is no use-case/interactor layer in this stack. Add a `usecases/` class only when a single user action coordinates multiple repositories or carries non-trivial orchestration logic; a straight pass-through to one repository method does not warrant one.
+
+<!-- oma-docs:ignore-start -->
+**Sanctioned layering exception (Drift).** `core/database/app_database.dart` imports the feature DAOs (e.g. `features/todos/data/local/todos_dao.dart`) to register them on `@DriftDatabase(daos: [...])`. This is a `core → features` upward import, the reverse of the normal dependency direction. It is the single allowed exception: Drift requires the database class to reference its tables and DAOs for code generation. No other `core` code may import from `features/`.
+<!-- oma-docs:ignore-end -->
+
+## Navigation: GoRouter with Typed Routes
+
+<!-- oma-docs:ignore-start -->
+`go_router` 17.x with `go_router_builder` (typed route classes generated at build time via `build_runner`) is the navigation layer. Define route classes annotated with `@TypedGoRoute`; the generator emits `.g.dart` files with `push()` / `go()` helpers. `go_router_builder` is a dev-only builder — the `@TypedGoRoute` annotation and `GoRouteData` base class are imported from `package:go_router/go_router.dart`, never from `go_router_builder`.
+<!-- oma-docs:ignore-end -->
+
+Route guards (auth checks, onboarding redirects) are handled by `GoRouter.redirect` callbacks, not inside screens. Deep links are declared in `GoRoute.path` and handled by the platform-level `AndroidManifest.xml` / `Info.plist` intent filters.
+
+See `snippets.md §2` for the typed GoRouter setup.

package/skills/oma-mobile/variants/kotlin-android/api-template.kt

@@ -0,0 +1,182 @@
+/**
+ * API Repository Template for Mobile Agent (Kotlin Android Native)
+ *
+ * This file wraps the generated `TodosApi` produced by the OpenAPI Generator Gradle
+ * plugin (`generatorName = "kotlin"`, `library = "jvm-ktor"`) from the committed
+ * server contract (`{api_spec}`). It is the **only** place that calls the backend
+ * API — never assemble URL paths or JSON bodies by hand for endpoints covered by
+ * the OpenAPI spec.
+ *
+ * Dependencies (all generated into app/build/generated/openapi at `openApiGenerate`):
+ *   - `…generated.api.TodosApi`              — one class per OpenAPI tag (`DefaultApi` when untagged)
+ *   - `…generated.model.*`                   — kotlinx-serialization DTOs
+ *   - `…generated.infrastructure.HttpResponse<T>` — `success`, `status`, `body()`, raw `response`
+ *
+ * Transport: the generated client talks to a Ktor `HttpClient`. Ktor is an
+ * engine-agnostic API layer; the app injects the OkHttp engine (`ktor-client-okhttp`)
+ * through Hilt and tests inject `MockEngine` (`ktor-client-mock`). This file never
+ * references either engine.
+ *
+ * Caching: when caching is required, it is MANDATORY at this Repository layer via a
+ * Room table of DECODED models (see snippets.md §8) — never an OkHttp `Cache` or a
+ * Ktor `HttpCache` plugin. Reads emit cached rows then revalidate; writes upsert or
+ * delete the affected rows after the server confirms.
+ *
+ * File layout (split into real files in production):
+ *   api-client/src/main/kotlin/<pkg>/client/
+ *     ApiJson.kt                   <- shared Json codec (BigDecimal contextual serializer)
+ *   app/src/main/java/<pkg>/
+ *     di/NetworkModule.kt          <- Ktor client + OkHttp engine → TodosApi (Hilt)
+ *     di/DatabaseModule.kt         <- Room database + DAO providers
+ *     data/ApiFailure.kt           <- typed failures surfaced to view models
+ *     data/TodoRepository.kt       <- this file
+ *     data/cache/TodoCache.kt      <- Room entity + DAO for the response cache
+ */
+
+// ---------------------------------------------------------------------------
+// app/src/main/java/com/example/app/data/TodoRepository.kt
+// ---------------------------------------------------------------------------
+
+package com.example.app.data
+
+import com.example.app.data.cache.TodoCacheDao
+import com.example.app.data.cache.TodoCacheRow
+import com.example.generated.api.TodosApi
+import com.example.generated.infrastructure.HttpResponse
+import com.example.generated.model.CreateTodoRequest
+import com.example.generated.model.Todo
+import io.ktor.client.statement.bodyAsText
+import java.io.IOException
+import javax.inject.Inject
+import javax.inject.Singleton
+import kotlin.time.Duration.Companion.minutes
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.onStart
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
+
+/** Typed failures surfaced by [TodoRepository]. View models map these to user text. */
+sealed class ApiFailure(message: String) : Exception(message) {
+    class NotFound : ApiFailure("The requested todo was not found.")
+    class Conflict(val detail: String) : ApiFailure(detail.ifBlank { "A todo with that title already exists." })
+    class Unauthorized : ApiFailure("Session expired.")
+    class Server(val status: Int) : ApiFailure("Unexpected server response: HTTP $status.")
+    class Network(cause: Throwable) : ApiFailure(cause.message ?: "Network error") {
+        init { initCause(cause) }
+    }
+}
+
+/**
+ * Interface seam the view models depend on, so the cached [TodoRepository] is
+ * swappable for a fake in unit tests (no mocking library required).
+ */
+interface TodoDataSource {
+    fun observeTodos(): Flow<List<Todo>>
+    suspend fun createTodo(title: String): Todo
+    suspend fun toggleTodo(id: String): Todo
+    suspend fun deleteTodo(id: String)
+}
+
+/**
+ * CRUD repository for the `/todos` resource.
+ *
+ * Depends on the generated [TodosApi] (constructed in `di/NetworkModule.kt` with the
+ * OkHttp engine) and a Room [TodoCacheDao]. Inject through Hilt; never instantiate
+ * in composables.
+ *
+ * Caching contract:
+ *   - Reads emit DECODED cached rows first, then revalidate when older than [ttl].
+ *   - Writes upsert/delete the affected rows after success so Room re-emits.
+ */
+@Singleton
+class TodoRepository @Inject constructor(
+    private val api: TodosApi,
+    private val dao: TodoCacheDao,
+    private val json: Json,
+    private val clock: () -> Long = System::currentTimeMillis,
+) : TodoDataSource {
+
+    private val ttl = 5.minutes.inWholeMilliseconds
+
+    // -- List (stale-while-revalidate) ---------------------------------------
+
+    /**
+     * Emits the cached list immediately (if present), then the freshly fetched
+     * list once revalidation upserts into Room. With a warm cache a network
+     * failure keeps the stale rows and is swallowed; with an empty cache the
+     * failure propagates to the collector.
+     */
+    override fun observeTodos(): Flow<List<Todo>> = dao.observeAll()
+        .map { rows -> rows.map { it.toModel() } }
+        .onStart { revalidateIfStale() }
+
+    private suspend fun revalidateIfStale() {
+        val oldest = dao.oldestFetchedAt()
+        if (oldest != null && clock() - oldest < ttl) return
+        try {
+            val fresh = call { api.listTodos() }
+            dao.replaceAll(fresh.map { it.toRow(clock()) })
+        } catch (failure: ApiFailure) {
+            if (oldest == null) throw failure
+        }
+    }
+
+    // -- Create ------------------------------------------------------------------
+
+    override suspend fun createTodo(title: String): Todo {
+        val created = call { api.createTodo(CreateTodoRequest(title = title)) }
+        dao.upsert(created.toRow(clock()))
+        return created
+    }
+
+    // -- Toggle ------------------------------------------------------------------
+
+    override suspend fun toggleTodo(id: String): Todo {
+        val updated = call { api.toggleTodo(id) }
+        dao.upsert(updated.toRow(clock()))
+        return updated
+    }
+
+    // -- Delete ------------------------------------------------------------------
+
+    override suspend fun deleteTodo(id: String) {
+        call { api.deleteTodo(id) }
+        dao.delete(id)
+    }
+
+    // -- Generated-response unwrapping ---------------------------------------------
+
+    /**
+     * Unwraps the generated [HttpResponse]: non-2xx becomes a typed [ApiFailure],
+     * transport `IOException` becomes [ApiFailure.Network], cancellation is rethrown.
+     * `expectSuccess = false` is set on the client so Ktor never throws on status.
+     */
+    private suspend fun <T> call(request: suspend () -> HttpResponse<T>): T {
+        val response = try {
+            request()
+        } catch (cancelled: CancellationException) {
+            throw cancelled
+        } catch (io: IOException) {
+            throw ApiFailure.Network(io)
+        }
+        if (!response.success) {
+            val detail = runCatching {
+                json.parseToJsonElement(response.response.bodyAsText())
+                    .jsonObject["detail"]?.jsonPrimitive?.content
+            }.getOrNull().orEmpty()
+            throw when (response.status) {
+                401 -> ApiFailure.Unauthorized()
+                404 -> ApiFailure.NotFound()
+                409 -> ApiFailure.Conflict(detail)
+                else -> ApiFailure.Server(response.status)
+            }
+        }
+        return response.body()
+    }
+}
+
+private fun TodoCacheRow.toModel() = Todo(id = id, title = title, completed = completed)
+private fun Todo.toRow(now: Long) = TodoCacheRow(id = id, title = title, completed = completed, fetchedAt = now)