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

package/skills/oma-mobile/variants/react-native/stack.yaml

@@ -0,0 +1,22 @@
+# yaml-language-server: $schema=../stack.schema.json
+language: react-native
+framework: react-native
+ui: react-native
+state: zustand
+navigation: react-navigation
+http_client: axios
+data_fetching: tanstack-query
+local_storage: mmkv
+response_cache: tanstack-query
+structure: src/api,src/features/<feature>/{model,ui,queries.ts,mutations.ts},src/shared,src/navigation,src/store,e2e
+source: variant
+
+verify:
+  detect: package.json
+  syntax:
+    cmd: "npx tsc --noEmit"
+    skip_if_missing: npx
+  tests:
+    cmd: "npx jest --ci"
+    pass_signal: "Tests:"
+    skip_if_missing: npx

package/skills/oma-mobile/variants/react-native/tech-stack.md

@@ -0,0 +1,192 @@
+# Mobile Agent - Tech Stack Reference (React Native)
+
+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: React Native + TypeScript
+
+- **Language**: TypeScript (strict mode; `"strict": true` in `tsconfig.json`)
+- **UI Framework**: React Native 0.86 with React 19 (core components); Expo is the recommended toolchain for new projects (managed or bare workflow)
+- **Architecture**: New Architecture (Fabric + TurboModules) — default since RN 0.76 and the only mode from 0.82 onward
+- **Minimum OS**: iOS 16.0 / Android API 26 (Oreo)
+- **Tooling**: Metro bundler, Expo CLI or React Native CLI, React Native DevTools for dev debugging
+
+React Native renders to native UI components — not a WebView or canvas. Expo adds a curated native module layer, OTA updates, and a first-class build service (EAS Build), which removes native toolchain friction for most projects. Bare workflow gives full native access when Expo modules do not cover a capability.
+
+## State Management: Zustand
+
+Client/UI state is managed with **Zustand**. Zustand is a minimal, hook-first store with no boilerplate and no context wrapping required. Redux Toolkit (RTK) is the heavier alternative for teams that need time-travel debugging, a stricter action/reducer discipline, or RTK Query integration.
+
+| Concern | Tool |
+|---------|------|
+| Client / UI state | Zustand |
+| Server state + caching | TanStack Query (see Response Cache section) |
+| Heavy team state / RTK Query | Redux Toolkit (alternative) |
+
+Zustand stores live in `src/store/`. Keep stores small and feature-scoped — one store per feature domain is preferred over a single monolithic store.
+
+## HTTP Transport: Axios
+
+<!-- oma-docs:ignore-start -->
+Network calls are made through a **singleton Axios instance** configured in `src/api/client.ts`. The instance wires request interceptors for bearer-token injection and response interceptors for 401 handling / token refresh. Retry logic (exponential back-off) is attached via `axios-retry`.
+<!-- oma-docs:ignore-end -->
+
+**Transport vs. server-state distinction.** Axios is a transport concern only — it sends and receives bytes. It knows nothing about caching, stale data, or background revalidation. TanStack Query (below) owns those concerns. React components never import the Axios instance directly; they consume typed hooks built on TanStack Query.
+
+```
+axios instance (transport)
+  └── used by: src/api/*.ts  (typed data functions)
+        └── consumed by: TanStack Query hooks (useQuery / useMutation)
+              └── consumed by: Screens / components
+```
+
+See `snippets.md §3` for the canonical Axios instance and auth interceptor.
+
+## Response Cache: TanStack Query (@tanstack/react-query)
+
+**When response caching is required, keep it at the data-fetching layer.** TanStack Query owns the repository-layer cache: it caches **decoded JavaScript objects** (not raw response bytes), provides stale-while-revalidate out of the box, and centralizes invalidation so the data-fetching layer is the single source of caching truth.
+
+```
+Screen / Component
+  |  renders from
+  v
+useQuery / useMutation hook    (src/features/<feature>/queries.ts / mutations.ts)
+  |  on miss / revalidate
+  +──────────────────────►  QueryClient in-memory cache  (decoded JS objects)
+  |                          + MMKV persister (survives restarts)
+  |  on cache miss
+  v
+src/api/<resource>.ts          (typed axios functions — transport only)
+  |  HTTP via axios instance
+  v
+Backend REST API
+```
+
+**Mandatory rules:**
+
+1. Every read is wrapped in a `useQuery` call with **explicit `staleTime` and `gcTime`** — no implicit infinite TTL. `staleTime` controls when a cached entry is considered stale and triggers a background revalidation; `gcTime` (formerly `cacheTime`) controls when an unused entry is garbage-collected from memory. For offline-first, `gcTime` **must stay `>=` the persister's `maxAge`** (default 24h) or the persisted cache is discarded before it can be restored on the next launch.
+2. Query keys include the validated account/tenant identity: `[account, accountId, operation, ...params]`, for example `['account', accountId, 'todos', 'list']`. **Never key on URLs** (they conflate transport with cache identity and break under proxy/versioning changes).
+3. Every mutation (`useMutation`) **must call `queryClient.invalidateQueries({ queryKey })`** for all affected query keys on `onSuccess`. Optimistic updates are optional but, when used, must pair a `rollback` in `onError`.
+4. When offline persistence is required: `@tanstack/react-query-persist-client` (the `PersistQueryClientProvider`) + `@tanstack/query-sync-storage-persister` driving a custom MMKV persister (`react-native-mmkv`) so the query cache survives app restarts. Wire `onlineManager` to `@react-native-community/netinfo` so paused mutations resume and stale queries refetch when connectivity returns.
+<!-- oma-docs:ignore-start -->
+5. Create one `QueryClient` per authenticated session (`src/api/queryClient.ts`), with an account-scoped disk key. On account change/logout, unmount the provider, cancel queries, clear memory and the previous account disk cache, and replace the client. Block delayed writes and mutations from retired sessions; never create per-component clients.
+<!-- oma-docs:ignore-end -->
+6. Network calls are isolated in `src/api/` typed functions (axios). **Screens and components never call axios directly** — this is the repository seam. Components consume hooks; hooks consume the api layer.
+7. The query cache is for **transient, server-owned data**. Durable non-secret user-owned data belongs in MMKV; secrets (the access token) live only in memory in a Zustand `authStore` hydrated from `react-native-keychain` — never in plain-text MMKV. TanStack Query is never a system of record.
+
+See `snippets.md §2` for QueryClient + MMKV persister setup, `snippets.md §5` for `queries.ts` / `mutations.ts`, and `snippets.md §9` for the cache rules recap.
+
+## Local Storage
+
+| Layer | Library | Purpose |
+|-------|---------|---------|
+| Fast KV (non-secret) | `react-native-mmkv` | User preferences, offline flags, TanStack Query persistence |
+| Secrets / tokens | `expo-secure-store` or `react-native-keychain` | Auth tokens, API keys |
+| Query cache persistence | MMKV persister (`@tanstack/query-sync-storage-persister` + `@tanstack/react-query-persist-client`) | Offline-first server-state survival across restarts |
+
+**MMKV** is a C++-backed key-value store (the same one WeChat uses) that is 30× faster than `AsyncStorage` on both platforms. Use it for all non-secret durable state. Use `expo-secure-store` (Expo projects) or `react-native-keychain` (bare RN) for anything that must live in the platform secure enclave (iOS Keychain / Android Keystore).
+
+<!-- oma-docs:ignore-start -->
+Never store secrets in MMKV — it stores plain text unless an `encryptionKey` is passed. The access token lives in an in-memory Zustand `authStore` (`src/store/authStore.ts`) that is hydrated from the Keychain at app start; the axios request interceptor reads it synchronously via `useAuthStore.getState().accessToken`, and a 401 clears both the Keychain and the store. See `snippets.md §10`.
+<!-- oma-docs:ignore-end -->
+
+## Testing
+
+| Layer | Framework |
+|-------|-----------|
+| Unit (domain logic, stores) | Jest |
+| Component / screen | `@testing-library/react-native` |
+| E2E / critical flows | Maestro |
+
+Components under test are wrapped in a `QueryClientProvider` with a fresh `QueryClient` (no retries, zero stale time) so tests do not make real network calls. The `src/api/` module is mocked at the Jest module boundary — tests assert on hook behavior, not axios internals.
+
+Run tests with `npx jest --ci`. Maestro flow files live in `e2e/` and exercise critical user journeys (login, create-todo, toggle, delete) via `maestro test e2e/`.
+
+## Project Layout
+
+Feature-sliced structure with a clean api / feature / shared separation:
+
+```
+src/
+  api/
+    client.ts               # Axios singleton instance + interceptors
+    queryClient.ts          # QueryClient creation + MMKV persister setup
+    todos.ts                # Typed axios functions for /todos resource
+    auth.ts                 # Typed axios functions for /auth resource
+  features/
+    todos/
+      model/
+        todo.ts             # TypeScript types / interfaces for the domain
+      ui/
+        TodosScreen.tsx     # Screen consuming useQuery / useMutation hooks
+        TodoItem.tsx        # Presentational component
+      queries.ts            # useTodosQuery, useTodoDetailQuery (useQuery wrappers)
+      mutations.ts          # useCreateTodo, useToggleTodo, useDeleteTodo (useMutation)
+    auth/
+      model/
+        auth.ts
+      ui/
+        LoginScreen.tsx
+      queries.ts
+      mutations.ts
+  navigation/
+    RootNavigator.tsx       # Stack + Tab navigator composition
+    types.ts                # Typed RootStackParamList, TabParamList
+  shared/
+    components/
+      LoadingView.tsx
+      ErrorView.tsx
+      EmptyStateView.tsx
+    hooks/
+      useNetworkStatus.ts   # NetInfo wrapper for offline detection
+    utils/
+      storage.ts            # MMKV instance export
+  store/
+    authStore.ts            # Zustand store for auth session (token, user)
+    uiStore.ts              # Zustand store for global UI flags
+  App.tsx                   # Root component — providers, NavigationContainer
+e2e/
+  todos.yaml                # Maestro E2E flow for todos feature
+  auth.yaml                 # Maestro E2E flow for login
+```
+
+## Architecture Pattern
+
+```
+Screen / Component  (src/features/<feature>/ui/)
+  |  calls (React hook)
+  v
+useQuery / useMutation hook  (src/features/<feature>/queries.ts, mutations.ts)
+  |  reads from in-memory + MMKV-persisted cache (stale-while-revalidate)
+  +──────────────────────────────────►  QueryClient cache  (decoded JS objects)
+  |  on cache miss or revalidation
+  v
+src/api/<resource>.ts  (typed axios functions — transport only)
+  |  HTTP via singleton axios instance with auth interceptor
+  v
+Backend REST API
+```
+
+Each `features/<name>/` folder is a vertical slice owning its types, UI components, and data hooks. `shared/` contains stateless, reusable components and utilities with no feature knowledge. The `api/` layer is the only place that touches axios and the network.
+
+## Navigation: React Navigation v7 (native-stack)
+
+Use **`@react-navigation/native-stack`** (backed by `react-native-screens` native primitives) for push navigation — it is measurably faster than the JS-animated `@react-navigation/stack`. Tab navigation uses `@react-navigation/bottom-tabs`.
+
+<!-- oma-docs:ignore-start -->
+Route param lists are **fully typed** in `src/navigation/types.ts` with a `RootStackParamList`. Screen components receive `NativeStackScreenProps<RootStackParamList, 'ScreenName'>` as props, giving compile-time checked navigation calls.
+<!-- oma-docs:ignore-end -->
+
+```typescript
+// src/navigation/types.ts
+export type RootStackParamList = {
+  TodoList: undefined;
+  TodoDetail: { id: string };
+  Login: undefined;
+};
+```
+
+<!-- oma-docs:ignore-start -->
+Pass `<NavigationContainer>` and navigator composition to `src/navigation/RootNavigator.tsx`; never embed navigation logic inside screen components.
+<!-- oma-docs:ignore-end -->
+
+See `snippets.md §7` for the typed navigator setup and `snippets.md §6` for a screen consuming typed route params.

package/skills/oma-mobile/variants/stack.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Mobile Stack Manifest",
+  "description": "Per-variant stack declaration and verify contract consumed by `oma verify agent mobile` and agent structured lookup.",
+  "type": "object",
+  "required": ["language"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "language": {
+      "type": "string",
+      "enum": ["swift", "kotlin", "flutter", "react-native"],
+      "description": "Primary implementation language of the variant."
+    },
+    "framework": {
+      "type": "string",
+      "description": "Primary UI framework (e.g., swiftui, flutter, react-native)."
+    },
+    "ui": {
+      "type": "string",
+      "description": "UI toolkit or paradigm (e.g., swiftui, material3, react-native)."
+    },
+    "state": {
+      "type": "string",
+      "description": "State-management approach (e.g., observation, riverpod, zustand)."
+    },
+    "navigation": {
+      "type": "string",
+      "description": "Navigation/router library (e.g., navigationstack, gorouter, react-navigation)."
+    },
+    "http_client": {
+      "type": "string",
+      "description": "HTTP transport client (e.g., urlsession, dio, axios)."
+    },
+    "data_fetching": {
+      "type": "string",
+      "description": "Server-state / data-fetching layer where distinct from the raw HTTP client (e.g., tanstack-query)."
+    },
+    "local_storage": {
+      "type": "string",
+      "description": "Durable on-device persistence (e.g., swiftdata, drift, mmkv)."
+    },
+    "api_generator": {
+      "type": "string",
+      "description": "API client generator used (e.g., swift-openapi-generator)."
+    },
+    "api_spec": {
+      "type": "string",
+      "description": "Relative path to the OpenAPI document consumed by the generator (e.g., Core/Networking/openapi.yaml)."
+    },
+    "response_cache": {
+      "type": "string",
+      "description": "Repository-layer response cache library used to memoize decoded API models (e.g., hyperoslo-cache)."
+    },
+    "structure": {
+      "type": "string",
+      "description": "Top-level module layout (e.g., App/Core/Features/Shared)."
+    },
+    "source": {
+      "type": "string",
+      "enum": ["variant", "migrated", "user", "detected"],
+      "description": "Origin marker. `variant` = shipped with repo, `migrated` = produced by legacy migration, `user` = hand-customized, `detected` = generated by the stack-set workflow from codebase detection."
+    },
+    "verify": {
+      "$ref": "../../_shared/core/stack-verify.schema.json#/definitions/verify"
+    }
+  },
+  "additionalProperties": true
+}

package/skills/oma-mobile/variants/swift-ios/api-template.swift

@@ -0,0 +1,165 @@
+/**
+ * API Service Template for Mobile Agent (Swift iOS Native)
+ *
+ * This file wraps the generated `Client` produced by `swift-openapi-generator`
+ * from `Core/Networking/openapi.yaml`. It is the **only** place that calls the
+ * backend API — never construct `URLRequest` or decode `Data` manually for
+ * endpoints that exist in the OpenAPI spec.
+ *
+ * Dependencies (all auto-generated at `swift build` time):
+ *   - `Client`       — generated root type; one instance per app
+ *   - `Operations`   — one namespace per operation (e.g., `Operations.listTodos`)
+ *   - `Components`   — shared schema types (e.g., `Components.Schemas.Todo`)
+ *
+ * Caching: read-through is MANDATORY at this Repository layer via a
+ * `ResponseCache` actor over `hyperoslo/Cache` (see Core/Cache/ResponseCache.swift
+ * and snippets.md §10). It caches DECODED models — never `HTTPBody`. Reads use
+ * stale-while-revalidate; writes invalidate the affected keys.
+ *
+ * File layout (split into real files in production):
+ *   Core/Networking/
+ *     openapi.yaml                      <- vendored OpenAPI spec (source of truth)
+ *     openapi-generator-config.yaml     <- generator config (types + client, public)
+ *     APIClient.swift                   <- URLSession transport + auth middleware wiring
+ *     TodoService.swift                 <- this file
+ *   Core/Cache/
+ *     ResponseCache.swift               <- actor wrapping hyperoslo/Cache Storage
+ */
+
+// ---------------------------------------------------------------------------
+// Core/Networking/TodoService.swift
+// ---------------------------------------------------------------------------
+
+import Foundation
+import OpenAPIRuntime
+
+/// Typed errors surfaced by `TodoService`.
+public enum TodoServiceError: Error, LocalizedError {
+    case notFound
+    case conflict
+    case undocumented(statusCode: Int)
+
+    public var errorDescription: String? {
+        switch self {
+        case .notFound:          return "The requested todo was not found."
+        case .conflict:          return "A todo with that title already exists."
+        case .undocumented(let code): return "Unexpected server response: HTTP \(code)."
+        }
+    }
+}
+
+/// Protocol seam the view models depend on, so the cached `TodoService` is
+/// swappable for a protocol-based mock in tests (no third-party mock lib).
+public protocol TodoProviding: Sendable {
+    func todosStream() -> AsyncThrowingStream<[Components.Schemas.Todo], Error>
+    func createTodo(title: String) async throws -> Components.Schemas.Todo
+    func toggleTodo(id: String) async throws -> Components.Schemas.Todo
+    func deleteTodo(id: String) async throws
+}
+
+/// CRUD service for the `/todos` resource.
+///
+/// Depends on `Client` (generated from `Core/Networking/openapi.yaml`) and a
+/// `ResponseCache` (Core/Cache/ResponseCache.swift, an actor over `hyperoslo/Cache`).
+/// Inject via `AppDependencies` at app startup; never instantiate directly in views.
+///
+/// Caching contract:
+///   - Reads cache DECODED models (never `HTTPBody`) and serve stale-while-revalidate.
+///   - Writes invalidate the affected cache keys so the next read repopulates.
+public final class TodoService: TodoProviding {
+    private let client: Client
+    private let cache: ResponseCache<[Components.Schemas.Todo]>
+
+    /// Cache key for the list endpoint. Key on `operationID` + params, never URLs.
+    private static let listKey = "listTodos"
+
+    public init(client: Client, cache: ResponseCache<[Components.Schemas.Todo]>) {
+        self.client = client
+        self.cache = cache
+    }
+
+    // MARK: - List (stale-while-revalidate)
+
+    /// Yields the cached list first (if present), then the freshly-fetched list.
+    /// The view model iterates with `for try await` and updates state per yield.
+    /// On a network failure with a warm cache, the stale value stands and the
+    /// error is swallowed; with no cache, the error surfaces to the caller.
+    public func todosStream() -> AsyncThrowingStream<[Components.Schemas.Todo], Error> {
+        AsyncThrowingStream { continuation in
+            let task = Task {
+                let cached = await cache.value(forKey: Self.listKey)
+                if let cached { continuation.yield(cached) }
+                do {
+                    let fresh = try await fetchTodos()
+                    await cache.store(fresh, forKey: Self.listKey)
+                    continuation.yield(fresh)
+                    continuation.finish()
+                } catch {
+                    cached == nil ? continuation.finish(throwing: error)
+                                  : continuation.finish()
+                }
+            }
+            continuation.onTermination = { _ in task.cancel() }
+        }
+    }
+
+    private func fetchTodos() async throws -> [Components.Schemas.Todo] {
+        let response = try await client.listTodos(.init())
+        switch response {
+        case .ok(let ok):
+            return try ok.body.json
+        case .undocumented(let statusCode, _):
+            throw TodoServiceError.undocumented(statusCode: statusCode)
+        }
+    }
+
+    // MARK: - Create
+
+    /// Creates a new todo with the given title, then invalidates the list cache.
+    public func createTodo(title: String) async throws -> Components.Schemas.Todo {
+        let body = Components.Schemas.CreateTodoRequest(title: title)
+        let response = try await client.createTodo(.init(body: .json(body)))
+        switch response {
+        case .created(let created):
+            await cache.invalidate(Self.listKey)
+            return try created.body.json
+        case .conflict:
+            throw TodoServiceError.conflict
+        case .undocumented(let statusCode, _):
+            throw TodoServiceError.undocumented(statusCode: statusCode)
+        }
+    }
+
+    // MARK: - Toggle
+
+    /// Toggles the `completed` flag on the todo with the given ID, then invalidates
+    /// the list cache.
+    public func toggleTodo(id: String) async throws -> Components.Schemas.Todo {
+        let response = try await client.toggleTodo(.init(path: .init(id: id)))
+        switch response {
+        case .ok(let ok):
+            await cache.invalidate(Self.listKey)
+            return try ok.body.json
+        case .notFound:
+            throw TodoServiceError.notFound
+        case .undocumented(let statusCode, _):
+            throw TodoServiceError.undocumented(statusCode: statusCode)
+        }
+    }
+
+    // MARK: - Delete
+
+    /// Permanently deletes the todo with the given ID, then invalidates the list cache.
+    public func deleteTodo(id: String) async throws {
+        let response = try await client.deleteTodo(.init(path: .init(id: id)))
+        switch response {
+        case .noContent:
+            await cache.invalidate(Self.listKey)
+            return
+        case .notFound:
+            throw TodoServiceError.notFound
+        case .undocumented(let statusCode, _):
+            throw TodoServiceError.undocumented(statusCode: statusCode)
+        }
+    }
+}