@shaykec/app-agent 1.0.5 → 1.0.6

package/templates/shared/ios/CachedRepository/CachedRepository.swift

@@ -0,0 +1,212 @@
+import Foundation
+import Combine
+
+/// Decorator implementing DataRepository that wraps any remote DataRepository with local caching.
+/// Provides cache-first reads, optimistic writes, and offline queue management.
+class CachedRepository: ObservableObject, DataRepository {
+    private let remoteRepository: any DataRepository
+    private let localCache: LocalCache
+    private let offlineQueue: OfflineQueue
+    private var cancellables = Set<AnyCancellable>()
+    
+    @Published var items: [Item] = []
+    @Published var categories: [Category] = []
+    @Published var favoriteItems: [Item] = []
+    
+    @Published var isOnline: Bool = true
+    @Published var pendingMutations: Int = 0
+    
+    init(wrapping remoteRepository: any DataRepository) {
+        self.remoteRepository = remoteRepository
+        self.localCache = LocalCache()
+        self.offlineQueue = OfflineQueue()
+        
+        // Load from cache immediately
+        loadFromCache()
+        
+        // Observe network status
+        observeNetworkStatus()
+        
+        // Process offline queue when online
+        processOfflineQueueWhenOnline()
+    }
+    
+    // MARK: - Network Status
+    
+    private func observeNetworkStatus() {
+        // CUSTOMIZE: Use NetworkBanner or Reachability to detect connectivity
+        // For now, assume online. Integrate with NetworkBanner module if available.
+        NotificationCenter.default.publisher(for: .networkStatusChanged)
+            .sink { [weak self] notification in
+                if let isOnline = notification.userInfo?["isOnline"] as? Bool {
+                    self?.isOnline = isOnline
+                }
+            }
+            .store(in: &cancellables)
+    }
+    
+    private func processOfflineQueueWhenOnline() {
+        $isOnline
+            .filter { $0 }
+            .sink { [weak self] _ in
+                self?.processOfflineQueue()
+            }
+            .store(in: &cancellables)
+    }
+    
+    // MARK: - Cache Management
+    
+    private func loadFromCache() {
+        items = localCache.loadItems()
+        categories = localCache.loadCategories()
+        favoriteItems = items.filter { $0.isFavorite }
+    }
+    
+    private func saveToCache() {
+        localCache.saveItems(items)
+        localCache.saveCategories(categories)
+    }
+    
+    // MARK: - DataRepository
+    
+    func loadData() {
+        // Load from cache immediately (cache-first)
+        loadFromCache()
+        
+        // Refresh from remote in background
+        if isOnline {
+            Task {
+                remoteRepository.loadData()
+                await refreshFromRemote()
+            }
+        }
+    }
+    
+    private func refreshFromRemote() async {
+        // Wait a bit for remote to load
+        try? await Task.sleep(nanoseconds: 500_000_000) // 0.5 seconds
+        
+        await MainActor.run {
+            // Update from remote (which should have updated its @Published properties)
+            // CUSTOMIZE: Access remote repository's published properties if possible
+            // For now, we'll rely on the cache being updated via add/update/delete methods
+        }
+    }
+    
+    func addItem(_ item: Item) {
+        // Optimistic write: apply to local cache immediately
+        items.insert(item, at: 0)
+        if item.isFavorite {
+            favoriteItems.insert(item, at: 0)
+        }
+        saveToCache()
+        
+        // Queue for remote sync
+        if isOnline {
+            remoteRepository.addItem(item)
+        } else {
+            offlineQueue.enqueue(.add(item))
+            pendingMutations += 1
+        }
+    }
+    
+    func updateItem(_ item: Item) {
+        // Optimistic write
+        if let index = items.firstIndex(where: { $0.id == item.id }) {
+            items[index] = item
+        }
+        favoriteItems = items.filter { $0.isFavorite }
+        saveToCache()
+        
+        // Queue for remote sync
+        if isOnline {
+            remoteRepository.updateItem(item)
+        } else {
+            offlineQueue.enqueue(.update(item))
+            pendingMutations += 1
+        }
+    }
+    
+    func deleteItem(_ item: Item) {
+        // Optimistic write
+        items.removeAll { $0.id == item.id }
+        favoriteItems.removeAll { $0.id == item.id }
+        saveToCache()
+        
+        // Queue for remote sync
+        if isOnline {
+            remoteRepository.deleteItem(item)
+        } else {
+            offlineQueue.enqueue(.delete(item.id))
+            pendingMutations += 1
+        }
+    }
+    
+    func toggleFavorite(_ item: Item) {
+        var updated = item
+        updated.isFavorite.toggle()
+        updateItem(updated)
+    }
+    
+    func searchItems(query: String) -> [Item] {
+        guard !query.isEmpty else { return items }
+        return items.filter {
+            $0.title.localizedCaseInsensitiveContains(query) ||
+            $0.subtitle.localizedCaseInsensitiveContains(query)
+        }
+    }
+    
+    func itemsByCategory(_ categoryName: String) -> [Item] {
+        items.filter { $0.category == categoryName }
+    }
+    
+    // MARK: - Offline Queue Processing
+    
+    private func processOfflineQueue() {
+        guard isOnline else { return }
+        
+        Task {
+            let mutations = offlineQueue.dequeueAll()
+            pendingMutations = mutations.count
+            
+            for mutation in mutations {
+                do {
+                    switch mutation {
+                    case .add(let item):
+                        remoteRepository.addItem(item)
+                    case .update(let item):
+                        remoteRepository.updateItem(item)
+                    case .delete(let id):
+                        // Need to reconstruct item from cache
+                        if let item = items.first(where: { $0.id == id }) {
+                            remoteRepository.deleteItem(item)
+                        }
+                    }
+                    
+                    // Small delay between mutations
+                    try await Task.sleep(nanoseconds: 100_000_000) // 0.1 seconds
+                } catch {
+                    // Re-queue failed mutation
+                    offlineQueue.enqueue(mutation)
+                }
+            }
+            
+            await MainActor.run {
+                pendingMutations = offlineQueue.count
+            }
+        }
+    }
+    
+    // MARK: - Cache Invalidation
+    
+    func invalidateCache() {
+        localCache.clear()
+        loadData()
+    }
+}
+
+// MARK: - Network Status Notification
+
+extension Notification.Name {
+    static let networkStatusChanged = Notification.Name("networkStatusChanged")
+}

package/templates/shared/ios/CachedRepository/INTEGRATION.md

@@ -0,0 +1,168 @@
+# CachedRepository Module — Integration Guide
+
+## Prerequisites
+
+### iOS
+1. **Core Data Model:**
+   - Create `CacheModel.xcdatamodeld` in your Xcode project
+   - Add entity: `CacheEntity` with attributes:
+     - `entityType` (String)
+     - `entityId` (String)
+     - `data` (Binary Data)
+     - `expiresAt` (Date)
+     - `createdAt` (Date)
+   - Set `entityType` and `entityId` as indexed attributes for performance
+
+2. **No external dependencies** — uses Core Data (built into iOS)
+
+### Android
+See `templates/shared/android/CachedRepository/INTEGRATION.md` for Android setup.
+
+## AppConfig Additions
+
+No AppConfig changes needed. CachedRepository is a wrapper, not a data source itself.
+
+## DataSourceResolver Wiring
+
+Wrap any remote DataRepository with CachedRepository:
+
+```swift
+enum DataSourceResolver {
+    static var repository: any DataRepository {
+        switch AppConfig.DataSource.active {
+        case .localStorage:
+            return LocalStorageProvider.shared
+        case .mock:
+            return MockDataProvider.shared
+        case .supabase:
+            // Wrap Supabase with caching
+            return CachedRepository(wrapping: SupabaseDataProvider.shared)
+        case .firebase:
+            // Firebase already has built-in cache — don't wrap
+            return FirebaseDataProvider.shared
+        case .customAPI:
+            // Wrap custom API provider
+            return CachedRepository(wrapping: CustomAPIProvider.shared)
+        }
+    }
+}
+```
+
+**Important:** Once DataSourceResolver is configured, app code (including tests) should use `DataSourceResolver.repository` instead of directly accessing `MockDataProvider.shared` or other providers. This ensures code works with any configured data source.
+
+## When to Use CachedRepository
+
+**Use CachedRepository when:**
+- Using Supabase (no built-in offline cache)
+- Using a custom REST API provider
+- Need offline support for any remote data source
+
+**Do NOT use CachedRepository when:**
+- Using Firebase (Firestore has built-in offline persistence)
+- Using LocalStorageProvider (already local)
+- Using MockDataProvider (in-memory only)
+
+**Note:** In app code and tests, always use `DataSourceResolver.repository` instead of directly accessing `MockDataProvider.shared` or other providers. This ensures your code works with any configured data source.
+
+## Navigation Wiring
+
+### Show Sync Status
+
+Add sync status indicator to settings or profile:
+
+```swift
+@StateObject private var cachedRepo = CachedRepository(wrapping: SupabaseDataProvider.shared)
+
+VStack {
+    if cachedRepo.isOnline {
+        Label(Strings.CachedRepository.online, systemImage: "wifi")
+            .foregroundColor(.green)
+    } else {
+        Label(Strings.CachedRepository.offline, systemImage: "wifi.slash")
+            .foregroundColor(.orange)
+    }
+    
+    if cachedRepo.pendingMutations > 0 {
+        Text(Strings.CachedRepository.pendingChangesCount(cachedRepo.pendingMutations))
+            .font(.caption)
+            .foregroundColor(.orange)
+    }
+}
+```
+
+## String Merge
+
+Add `Strings.CachedRepository` enum to the app's `Strings.swift` file. All strings are in the module's `Strings.swift`.
+
+## Test IDs
+
+| Test ID | Element |
+|---------|---------|
+| `cached_repo_online_indicator` | Online status indicator |
+| `cached_repo_offline_indicator` | Offline status indicator |
+| `cached_repo_pending_count` | Pending mutations count |
+| `cached_repo_sync_button` | Manual sync button (if added) |
+
+## Module Dependencies
+
+- **NetworkBanner** (optional) — for connectivity detection. CachedRepository listens to `.networkStatusChanged` notifications.
+- **ErrorHandling** (optional) — for displaying sync errors
+
+## Usage Notes
+
+- **Cache-First Reads:** Data loads from cache immediately, then refreshes from remote in background.
+- **Optimistic Writes:** Changes apply to local cache immediately, then sync to remote when online.
+- **Offline Queue:** Mutations are queued when offline and processed when connectivity resumes.
+- **TTL-Based Expiration:** Cache entries expire after 24 hours (configurable in `LocalCache.cacheTTL`).
+- **Last-Write-Wins:** Conflict resolution uses last write wins. CUSTOMIZE if you need more sophisticated conflict resolution.
+- **No Duplicate Caching:** Don't wrap Firebase providers — Firestore already handles offline caching.
+
+## Core Data Model Setup
+
+Create `CacheModel.xcdatamodeld`:
+
+1. In Xcode: File → New → File → Data Model → Name it "CacheModel"
+2. Add entity "CacheEntity"
+3. Add attributes:
+   - `entityType`: String (indexed)
+   - `entityId`: String (indexed)
+   - `data`: Binary Data
+   - `expiresAt`: Date
+   - `createdAt`: Date
+4. Ensure the model is added to your app target
+
+## Network Status Integration
+
+CachedRepository listens for `.networkStatusChanged` notifications. If using NetworkBanner module:
+
+```swift
+// In NetworkBanner module, post notification when status changes:
+NotificationCenter.default.post(
+    name: .networkStatusChanged,
+    object: nil,
+    userInfo: ["isOnline": isOnline]
+)
+```
+
+If not using NetworkBanner, integrate with your own connectivity detection:
+
+```swift
+import Network
+
+let monitor = NWPathMonitor()
+monitor.pathUpdateHandler = { path in
+    NotificationCenter.default.post(
+        name: .networkStatusChanged,
+        object: nil,
+        userInfo: ["isOnline": path.status == .satisfied]
+    )
+}
+let queue = DispatchQueue(label: "NetworkMonitor")
+monitor.start(queue: queue)
+```
+
+## Performance Considerations
+
+- **Cache Size:** Cache grows indefinitely. Consider implementing cache size limits or periodic cleanup.
+- **Queue Size:** Offline queue persists mutations until synced. Monitor queue size for very offline-heavy usage.
+- **Background Sync:** Queue processing happens on main thread. Consider moving to background queue for large queues.

package/templates/shared/ios/CachedRepository/LocalCache.swift

@@ -0,0 +1,191 @@
+import Foundation
+import CoreData
+
+/// Core Data-backed local cache for offline data storage.
+/// Separate from LocalStorageProvider — simpler schema, TTL-based expiration.
+class LocalCache {
+    static let shared = LocalCache()
+    
+    private let persistentContainer: NSPersistentContainer
+    private let cacheTTL: TimeInterval = 3600 * 24 // 24 hours
+    
+    private init() {
+        persistentContainer = NSPersistentContainer(name: "CacheModel")
+        
+        let description = NSPersistentStoreDescription()
+        description.shouldMigrateStoreAutomatically = true
+        description.shouldInferMappingModelAutomatically = true
+        persistentContainer.persistentStoreDescriptions = [description]
+        
+        persistentContainer.loadPersistentStores { _, error in
+            if let error = error {
+                print("LocalCache: Failed to load store: \(error.localizedDescription)")
+            }
+        }
+    }
+    
+    private var viewContext: NSManagedObjectContext {
+        persistentContainer.viewContext
+    }
+    
+    // MARK: - Items
+    
+    func loadItems() -> [Item] {
+        let request = CacheEntity.fetchRequest()
+        request.predicate = NSPredicate(format: "entityType == %@ AND expiresAt > %@", "item", Date() as NSDate)
+        
+        do {
+            let entities = try viewContext.fetch(request)
+            return entities.compactMap { entity in
+                guard let data = entity.data,
+                      let item = try? JSONDecoder().decode(Item.self, from: data) else {
+                    return nil
+                }
+                return item
+            }
+        } catch {
+            print("LocalCache: Failed to load items: \(error.localizedDescription)")
+            return []
+        }
+    }
+    
+    func saveItems(_ items: [Item]) {
+        // Delete expired items
+        deleteExpiredItems()
+        
+        // Save new items
+        for item in items {
+            let request = CacheEntity.fetchRequest()
+            request.predicate = NSPredicate(format: "entityType == %@ AND entityId == %@", "item", item.id)
+            request.fetchLimit = 1
+            
+            do {
+                let existing = try viewContext.fetch(request).first
+                let entity = existing ?? CacheEntity(context: viewContext)
+                
+                entity.entityType = "item"
+                entity.entityId = item.id
+                entity.data = try JSONEncoder().encode(item)
+                entity.expiresAt = Date().addingTimeInterval(cacheTTL)
+                entity.createdAt = Date()
+            } catch {
+                print("LocalCache: Failed to save item \(item.id): \(error.localizedDescription)")
+            }
+        }
+        
+        saveContext()
+    }
+    
+    // MARK: - Categories
+    
+    func loadCategories() -> [Category] {
+        let request = CacheEntity.fetchRequest()
+        request.predicate = NSPredicate(format: "entityType == %@ AND expiresAt > %@", "category", Date() as NSDate)
+        
+        do {
+            let entities = try viewContext.fetch(request)
+            return entities.compactMap { entity in
+                guard let data = entity.data,
+                      let category = try? JSONDecoder().decode(Category.self, from: data) else {
+                    return nil
+                }
+                return category
+            }
+        } catch {
+            print("LocalCache: Failed to load categories: \(error.localizedDescription)")
+            return []
+        }
+    }
+    
+    func saveCategories(_ categories: [Category]) {
+        // Delete expired categories
+        deleteExpiredCategories()
+        
+        // Save new categories
+        for category in categories {
+            let request = CacheEntity.fetchRequest()
+            request.predicate = NSPredicate(format: "entityType == %@ AND entityId == %@", "category", category.id)
+            request.fetchLimit = 1
+            
+            do {
+                let existing = try viewContext.fetch(request).first
+                let entity = existing ?? CacheEntity(context: viewContext)
+                
+                entity.entityType = "category"
+                entity.entityId = category.id
+                entity.data = try JSONEncoder().encode(category)
+                entity.expiresAt = Date().addingTimeInterval(cacheTTL)
+                entity.createdAt = Date()
+            } catch {
+                print("LocalCache: Failed to save category \(category.id): \(error.localizedDescription)")
+            }
+        }
+        
+        saveContext()
+    }
+    
+    // MARK: - Cleanup
+    
+    private func deleteExpiredItems() {
+        let request = CacheEntity.fetchRequest()
+        request.predicate = NSPredicate(format: "entityType == %@ AND expiresAt <= %@", "item", Date() as NSDate)
+        
+        do {
+            let expired = try viewContext.fetch(request)
+            expired.forEach { viewContext.delete($0) }
+        } catch {
+            print("LocalCache: Failed to delete expired items: \(error.localizedDescription)")
+        }
+    }
+    
+    private func deleteExpiredCategories() {
+        let request = CacheEntity.fetchRequest()
+        request.predicate = NSPredicate(format: "entityType == %@ AND expiresAt <= %@", "category", Date() as NSDate)
+        
+        do {
+            let expired = try viewContext.fetch(request)
+            expired.forEach { viewContext.delete($0) }
+        } catch {
+            print("LocalCache: Failed to delete expired categories: \(error.localizedDescription)")
+        }
+    }
+    
+    func clear() {
+        let request = CacheEntity.fetchRequest()
+        do {
+            let all = try viewContext.fetch(request)
+            all.forEach { viewContext.delete($0) }
+            saveContext()
+        } catch {
+            print("LocalCache: Failed to clear cache: \(error.localizedDescription)")
+        }
+    }
+    
+    // MARK: - Context
+    
+    private func saveContext() {
+        guard viewContext.hasChanges else { return }
+        do {
+            try viewContext.save()
+        } catch {
+            print("LocalCache: Failed to save context: \(error.localizedDescription)")
+        }
+    }
+}
+
+// MARK: - Core Data Model
+
+@objc(CacheEntity)
+class CacheEntity: NSManagedObject {
+    @NSManaged var entityType: String
+    @NSManaged var entityId: String
+    @NSManaged var data: Data?
+    @NSManaged var expiresAt: Date
+    @NSManaged var createdAt: Date
+}
+
+extension CacheEntity {
+    static func fetchRequest() -> NSFetchRequest<CacheEntity> {
+        NSFetchRequest<CacheEntity>(entityName: "CacheEntity")
+    }
+}

package/templates/shared/ios/CachedRepository/OfflineQueue.swift

@@ -0,0 +1,109 @@
+import Foundation
+
+/// Persisted mutation queue for offline operations.
+/// Stores pending mutations (add, update, delete) and processes them when connectivity resumes.
+class OfflineQueue {
+    static let shared = OfflineQueue()
+    
+    private let queueURL: URL
+    private var mutations: [Mutation] = []
+    private let maxRetries = 3
+    
+    private init() {
+        let documentsPath = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
+        queueURL = documentsPath.appendingPathComponent("offline_queue.json")
+        loadQueue()
+    }
+    
+    // MARK: - Queue Management
+    
+    func enqueue(_ mutation: Mutation) {
+        mutations.append(mutation)
+        saveQueue()
+    }
+    
+    func dequeueAll() -> [Mutation] {
+        let all = mutations
+        mutations.removeAll()
+        saveQueue()
+        return all
+    }
+    
+    var count: Int {
+        mutations.count
+    }
+    
+    // MARK: - Persistence
+    
+    private func loadQueue() {
+        guard FileManager.default.fileExists(atPath: queueURL.path),
+              let data = try? Data(contentsOf: queueURL),
+              let decoded = try? JSONDecoder().decode([Mutation].self, from: data) else {
+            mutations = []
+            return
+        }
+        mutations = decoded
+    }
+    
+    private func saveQueue() {
+        guard let data = try? JSONEncoder().encode(mutations) else { return }
+        try? data.write(to: queueURL)
+    }
+    
+    // MARK: - Retry Logic
+    
+    func markFailed(_ mutation: Mutation) {
+        // Re-queue failed mutations with retry count
+        // CUSTOMIZE: Implement exponential backoff if needed
+        enqueue(mutation)
+    }
+}
+
+// MARK: - Mutation Types
+
+enum Mutation: Codable {
+    case add(Item)
+    case update(Item)
+    case delete(String) // item ID
+    
+    enum CodingKeys: String, CodingKey {
+        case type
+        case item
+        case itemId
+    }
+    
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        let type = try container.decode(String.self, forKey: .type)
+        
+        switch type {
+        case "add":
+            let item = try container.decode(Item.self, forKey: .item)
+            self = .add(item)
+        case "update":
+            let item = try container.decode(Item.self, forKey: .item)
+            self = .update(item)
+        case "delete":
+            let itemId = try container.decode(String.self, forKey: .itemId)
+            self = .delete(itemId)
+        default:
+            throw DecodingError.dataCorruptedError(forKey: .type, in: container, debugDescription: "Unknown mutation type")
+        }
+    }
+    
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        
+        switch self {
+        case .add(let item):
+            try container.encode("add", forKey: .type)
+            try container.encode(item, forKey: .item)
+        case .update(let item):
+            try container.encode("update", forKey: .type)
+            try container.encode(item, forKey: .item)
+        case .delete(let itemId):
+            try container.encode("delete", forKey: .type)
+            try container.encode(itemId, forKey: .itemId)
+        }
+    }
+}