@sriinnu/runic 1.2.0 → 2.11.1

package/docs/sync/implementation.md

@@ -1,393 +0,0 @@
-# Runic Sync Implementation Checklist
-
-## Overview
-
-This document provides step-by-step instructions for integrating the Runic iCloud sync infrastructure into your application.
-
-## Prerequisites
-
-- [ ] Xcode 15.0 or later
-- [ ] macOS 14.0+ or iOS 17.0+ deployment target
-- [ ] Active Apple Developer Program membership
-- [ ] iCloud entitlements configured
-
-## Setup Steps
-
-### 1. Enable CloudKit Capability
-
-1. Open your Xcode project
-2. Select your app target
-3. Go to "Signing & Capabilities" tab
-4. Click "+ Capability" button
-5. Add "iCloud" capability
-6. Enable "CloudKit" checkbox
-7. Select or create a CloudKit container
-
-**Container ID Format**: `iCloud.com.yourcompany.runic`
-
-### 2. Configure CloudKit Schema
-
-Log into [CloudKit Dashboard](https://icloud.developer.apple.com/dashboard)
-
-#### Create Record Types
-
-**UsageSnapshot**
-```
-Fields:
-- version (Int64)
-- modifiedAt (Date/Time)
-- lastModifiedDeviceID (String, optional)
-- providerID (String)
-- primaryUsed (Int64)
-- primaryLimit (Int64, optional)
-- secondaryUsed (Int64, optional)
-- secondaryLimit (Int64, optional)
-- costUSD (Double, optional)
-- accountEmail (String, optional) [encrypted]
-- updatedAt (Date/Time)
-- deviceName (String)
-- platform (String)
-```
-
-**UserPreferences**
-```
-Fields:
-- version (Int64)
-- modifiedAt (Date/Time)
-- lastModifiedDeviceID (String, optional)
-- refreshInterval (Double)
-- enabledProviders (List<String>)
-- notificationsEnabled (Int64) [0 or 1]
-- autoRefreshEnabled (Int64) [0 or 1]
-- theme (String)
-- displayFormat (String)
-```
-
-**AlertConfiguration**
-```
-Fields:
-- version (Int64)
-- modifiedAt (Date/Time)
-- lastModifiedDeviceID (String, optional)
-- providerID (String)
-- warningThreshold (Double)
-- criticalThreshold (Double)
-- notificationChannels (List<String>)
-- enabled (Int64) [0 or 1]
-```
-
-#### Set Permissions
-
-For all record types:
-- Database: **Private**
-- Read/Write: **Owner**
-
-### 3. Update Entitlements File
-
-Ensure your `*.entitlements` file contains:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>com.apple.developer.icloud-container-identifiers</key>
-    <array>
-        <string>iCloud.com.yourcompany.runic</string>
-    </array>
-    <key>com.apple.developer.icloud-services</key>
-    <array>
-        <string>CloudKit</string>
-    </array>
-</dict>
-</plist>
-```
-
-### 4. Initialize Sync in Your App
-
-#### AppDelegate (UIKit) or App (SwiftUI)
-
-```swift
-import RunicCore
-
-class AppDelegate: NSObject, UIApplicationDelegate {
-    var syncManager: BackgroundSyncManager?
-
-    func application(
-        _ application: UIApplication,
-        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
-    ) -> Bool {
-        Task {
-            await setupSync()
-        }
-        return true
-    }
-
-    private func setupSync() async {
-        let syncEngine = iCloudSyncEngine(
-            containerIdentifier: "iCloud.com.yourcompany.runic"
-        )
-
-        let config = SyncConfiguration(
-            activeSyncInterval: 300,
-            backgroundSyncInterval: 3600,
-            syncOnForeground: true,
-            syncOnBackground: true
-        )
-
-        syncManager = BackgroundSyncManager(
-            syncEngine: syncEngine,
-            config: config
-        )
-
-        await syncManager?.start()
-    }
-}
-```
-
-#### SwiftUI App
-
-```swift
-import SwiftUI
-import RunicCore
-
-@main
-struct RunicApp: App {
-    @StateObject private var syncCoordinator = SyncCoordinator()
-
-    var body: some Scene {
-        WindowGroup {
-            ContentView()
-                .environmentObject(syncCoordinator)
-        }
-    }
-}
-
-@MainActor
-class SyncCoordinator: ObservableObject {
-    private var syncManager: BackgroundSyncManager?
-
-    init() {
-        Task {
-            await setupSync()
-        }
-    }
-
-    private func setupSync() async {
-        let syncEngine = iCloudSyncEngine()
-        let config = SyncConfiguration.default
-
-        syncManager = BackgroundSyncManager(
-            syncEngine: syncEngine,
-            config: config
-        )
-
-        await syncManager?.start()
-    }
-
-    func manualSync() async {
-        await syncManager?.syncNow()
-    }
-}
-```
-
-### 5. Integrate with Usage Tracking
-
-#### Sync Usage Snapshots
-
-```swift
-// After fetching usage data
-func syncUsageData(usage: UsageSnapshot, provider: UsageProvider) async {
-    let syncRecord = UsageSnapshotSyncRecord(
-        providerID: provider.rawValue,
-        primaryUsed: usage.primary.used,
-        primaryLimit: usage.primary.limit,
-        secondaryUsed: usage.secondary?.used,
-        secondaryLimit: usage.secondary?.limit,
-        costUSD: usage.providerCost?.totalCostUSD,
-        accountEmail: usage.identity?.accountEmail,
-        updatedAt: usage.updatedAt,
-        deviceName: getDeviceName(),
-        platform: getPlatform()
-    )
-
-    await syncEngine.enqueue(syncRecord, priority: .normal)
-}
-```
-
-#### Sync Preferences
-
-```swift
-func syncPreferences(settings: AppSettings) async {
-    let prefsRecord = UserPreferencesSyncRecord(
-        refreshInterval: settings.refreshInterval,
-        enabledProviders: settings.enabledProviders,
-        notificationsEnabled: settings.notificationsEnabled,
-        autoRefreshEnabled: settings.autoRefreshEnabled,
-        theme: settings.theme,
-        displayFormat: settings.displayFormat
-    )
-
-    let result = await syncEngine.push(records: [prefsRecord])
-    // Handle result
-}
-```
-
-### 6. Add Sync Status UI
-
-```swift
-import SwiftUI
-
-struct SyncStatusView: View {
-    @State private var stats: SyncStatistics?
-
-    var body: some View {
-        VStack(alignment: .leading, spacing: 8) {
-            if let stats = stats {
-                Text("Last Sync: \(formattedDate(stats.lastSyncDate))")
-                Text("Success Rate: \(String(format: "%.1f%%", stats.successRate))")
-                Text("Total Syncs: \(stats.totalSyncs)")
-            }
-
-            Button("Sync Now") {
-                Task {
-                    await performManualSync()
-                }
-            }
-        }
-        .task {
-            await loadStats()
-        }
-    }
-
-    private func performManualSync() async {
-        // Trigger manual sync
-    }
-
-    private func loadStats() async {
-        // Load sync statistics
-    }
-
-    private func formattedDate(_ date: Date?) -> String {
-        guard let date = date else { return "Never" }
-        let formatter = RelativeDateTimeFormatter()
-        return formatter.localizedString(for: date, relativeTo: Date())
-    }
-}
-```
-
-## Testing
-
-### Development Testing
-
-1. Use CloudKit Development environment
-2. Test with multiple devices/simulators
-3. Verify conflict resolution
-4. Test offline scenarios
-
-### Pre-Production Checklist
-
-- [ ] Tested on physical devices (not just simulator)
-- [ ] Tested with poor network conditions
-- [ ] Tested conflict resolution with concurrent edits
-- [ ] Verified encryption of sensitive data
-- [ ] Monitored CloudKit quota usage
-- [ ] Tested background sync behavior
-- [ ] Verified sync recovery after network interruption
-
-### Production Deployment
-
-1. Deploy CloudKit schema to Production
-2. Test with TestFlight builds
-3. Monitor CloudKit Dashboard for errors
-4. Set up CloudKit usage alerts
-
-## Monitoring
-
-### CloudKit Dashboard Metrics
-
-Monitor:
-- Request rate
-- Error rate
-- Storage usage
-- Transfer bandwidth
-
-### App Analytics
-
-Track:
-- Sync success rate
-- Average sync duration
-- Conflict frequency
-- User engagement with sync features
-
-## Troubleshooting
-
-### Common Issues
-
-**Issue**: "iCloud account unavailable"
-- **Solution**: User needs to sign in to iCloud in Settings
-
-**Issue**: Sync taking too long
-- **Solution**: Reduce batch size or sync frequency
-
-**Issue**: Conflicts occurring frequently
-- **Solution**: Review conflict resolution strategy
-
-**Issue**: Storage quota exceeded
-- **Solution**: Implement data pruning or notify user
-
-### Debug Mode
-
-Enable verbose logging:
-
-```swift
-let options = SyncOptions(
-    conflictStrategy: .lastWriteWins
-    // Add logging here if needed
-)
-```
-
-## Performance Optimization
-
-### Best Practices
-
-1. **Batch Operations**: Group multiple records into single sync
-2. **Incremental Sync**: Use change tokens for efficient syncs
-3. **Selective Sync**: Only sync changed records
-4. **Compression**: Consider compressing large payloads
-5. **Caching**: Cache frequently accessed data locally
-
-### Monitoring Performance
-
-```swift
-let stats = await syncManager.statistics
-print("Average sync duration: \(stats.averageDuration)s")
-
-if stats.averageDuration > 5.0 {
-    print("⚠️ Sync performance degraded")
-    // Investigate or adjust configuration
-}
-```
-
-## Security Considerations
-
-1. **Encryption**: Sensitive fields are automatically encrypted
-2. **Keychain**: Encryption keys stored in iOS/macOS Keychain
-3. **Private Database**: All data in user's private CloudKit database
-4. **No Shared Data**: Each user's data is isolated
-
-## Support
-
-For issues or questions:
-- Check CloudKit Dashboard for errors
-- Review sync statistics
-- Enable debug logging
-- Contact support with device logs
-
-## Version History
-
-- **v1.0.0**: Initial release with CloudKit sync
-- Support for macOS and iOS
-- Three record types (Usage, Preferences, Alerts)
-- Conflict resolution with multiple strategies
-- Background sync with configurable intervals

package/docs/sync/readme.md

@@ -1,317 +0,0 @@
-# Runic iCloud Sync Infrastructure
-
-Production-ready CloudKit synchronization system for macOS/iOS usage tracking.
-
-## Overview
-
-The Runic Sync infrastructure provides seamless cross-device synchronization of usage data, user preferences, and alert configurations using Apple's CloudKit framework.
-
-## Architecture
-
-### Core Components
-
-1. **SyncProtocol.swift** - Protocol definitions and interfaces
-2. **iCloudSyncEngine.swift** - CloudKit integration implementation
-3. **SyncConflictResolver.swift** - Conflict resolution logic
-4. **SyncRecord.swift** - Data models for CloudKit records
-5. **BackgroundSyncManager.swift** - Background sync coordination
-
-## Features
-
-- ✅ **Privacy-First**: AES-GCM encryption for sensitive data
-- ✅ **Conflict Resolution**: Last-write-wins with version tracking
-- ✅ **Offline Support**: Queue-based pending sync operations
-- ✅ **Background Sync**: Automatic sync at configurable intervals
-- ✅ **Error Recovery**: Retry logic with exponential backoff
-- ✅ **Multi-Platform**: Supports macOS and iOS
-
-## CloudKit Schema
-
-### Record Types
-
-#### UsageSnapshot
-- `recordID`: String (unique identifier)
-- `version`: Int (for conflict resolution)
-- `modifiedAt`: Date (last modification timestamp)
-- `providerID`: String (AI provider identifier)
-- `primaryUsed`: Int (tokens/requests used)
-- `primaryLimit`: Int? (limit if applicable)
-- `secondaryUsed`: Int? (secondary metric)
-- `costUSD`: Double? (estimated cost)
-- `accountEmail`: String (encrypted)
-- `deviceName`: String
-- `platform`: String
-
-#### UserPreferences
-- `recordID`: String (singleton: "user-preferences")
-- `version`: Int
-- `refreshInterval`: TimeInterval
-- `enabledProviders`: [String]
-- `notificationsEnabled`: Bool
-- `autoRefreshEnabled`: Bool
-- `theme`: String
-- `displayFormat`: String
-
-#### AlertConfiguration
-- `recordID`: String
-- `providerID`: String
-- `warningThreshold`: Double (0.0-1.0)
-- `criticalThreshold`: Double (0.0-1.0)
-- `notificationChannels`: [String]
-- `enabled`: Bool
-
-## Usage
-
-### Initialize Sync Engine
-
-```swift
-import RunicCore
-
-// Initialize the sync engine
-let syncEngine = iCloudSyncEngine()
-
-// Create background sync manager
-let syncManager = BackgroundSyncManager(
-    syncEngine: syncEngine,
-    config: .default
-)
-
-// Start automatic sync
-await syncManager.start()
-```
-
-### Manual Sync
-
-```swift
-// Perform manual sync
-let result = await syncManager.syncNow()
-
-switch result {
-case .success(let syncResult):
-    print("Synced: \(syncResult.fetchedCount) fetched, \(syncResult.pushedCount) pushed")
-case .failure(let error):
-    print("Sync failed: \(error.localizedDescription)")
-}
-```
-
-### Sync Usage Data
-
-```swift
-let usageRecord = UsageSnapshotSyncRecord(
-    providerID: "claude",
-    primaryUsed: 50000,
-    primaryLimit: 100000,
-    costUSD: 2.50,
-    deviceName: "MacBook Pro",
-    platform: "macOS"
-)
-
-// Queue for sync
-await syncEngine.enqueue(usageRecord, priority: .high)
-```
-
-### Configure Sync Intervals
-
-```swift
-let config = SyncConfiguration(
-    activeSyncInterval: 300,      // 5 minutes when active
-    backgroundSyncInterval: 3600, // 1 hour in background
-    syncOnForeground: true,
-    syncOnBackground: true
-)
-
-let syncManager = BackgroundSyncManager(
-    syncEngine: syncEngine,
-    config: config
-)
-```
-
-### Observe Sync Events
-
-```swift
-class MyObserver: SyncObserver {
-    func syncDidStart() {
-        print("Sync started")
-    }
-
-    func syncDidProgress(current: Int, total: Int) {
-        print("Progress: \(current)/\(total)")
-    }
-
-    func syncDidComplete(result: SyncResult) {
-        print("Sync completed: \(result.duration)s")
-    }
-
-    func syncDidFail(error: SyncError) {
-        print("Sync failed: \(error)")
-    }
-}
-
-let observer = MyObserver()
-await syncManager.addObserver(observer)
-```
-
-## Conflict Resolution
-
-The system supports multiple conflict resolution strategies:
-
-### Last-Write-Wins (Default)
-```swift
-let options = SyncOptions(conflictStrategy: .lastWriteWins)
-```
-
-### Prefer Local
-```swift
-let options = SyncOptions(conflictStrategy: .preferLocal)
-```
-
-### Custom Merge
-```swift
-let resolver = SyncConflictResolver()
-await resolver.registerMergeHandler(for: "UsageSnapshot") { local, remote in
-    // Custom merge logic
-    return local // or merged result
-}
-```
-
-## Security
-
-### Encryption
-Sensitive fields (email addresses, tokens) are encrypted using AES-GCM before syncing:
-
-```swift
-// Automatically encrypted
-let record = UsageSnapshotSyncRecord(
-    accountEmail: "user@example.com", // Encrypted in CloudKit
-    // ...
-)
-```
-
-### Keychain Storage
-Encryption keys are stored securely in the macOS/iOS Keychain.
-
-## Error Handling
-
-### Common Errors
-
-- `iCloudAccountUnavailable`: User not signed into iCloud
-- `networkUnavailable`: No network connection (queued for retry)
-- `quotaExceeded`: iCloud storage quota exceeded
-- `conflictResolutionFailed`: Unable to resolve conflict
-
-### Retry Logic
-
-Failed syncs are automatically retried with exponential backoff:
-- Initial retry: 2 seconds
-- Second retry: 4 seconds
-- Third retry: 8 seconds
-
-## Performance
-
-### Sync Statistics
-
-```swift
-let stats = await syncManager.statistics
-
-print(stats.summary)
-// Output:
-// Sync Statistics:
-//   Total syncs: 42
-//   Successful: 40 (95.2%)
-//   Failed: 2
-//   Average duration: 1.23s
-//   Last sync: 2 minutes ago
-```
-
-### Optimization Tips
-
-1. Use appropriate sync intervals (default: 5min active, 1hr background)
-2. Batch updates before syncing
-3. Enable background sync for seamless experience
-4. Monitor sync statistics for issues
-
-## CloudKit Setup
-
-### 1. Enable CloudKit in Xcode
-
-1. Open project settings
-2. Select target → Signing & Capabilities
-3. Add "iCloud" capability
-4. Enable "CloudKit"
-
-### 2. Configure Container
-
-1. Create CloudKit container or use default
-2. Add record types via CloudKit Dashboard
-3. Set permissions to "Private" database
-
-### 3. Entitlements
-
-Ensure `entitlements` file contains:
-
-```xml
-<key>com.apple.developer.icloud-container-identifiers</key>
-<array>
-    <string>iCloud.com.yourcompany.runic</string>
-</array>
-<key>com.apple.developer.icloud-services</key>
-<array>
-    <string>CloudKit</string>
-</array>
-```
-
-## Testing
-
-### Unit Tests
-
-```swift
-import XCTest
-@testable import RunicCore
-
-class SyncTests: XCTestCase {
-    func testConflictResolution() async {
-        let resolver = SyncConflictResolver()
-
-        let local = UsageSnapshotSyncRecord(/* ... */)
-        let remote = UsageSnapshotSyncRecord(/* ... */)
-
-        let resolved = resolver.resolve(
-            local: local,
-            remote: remote,
-            strategy: .lastWriteWins
-        )
-
-        XCTAssertNotNil(resolved)
-    }
-}
-```
-
-### Integration Tests
-
-Test with CloudKit Development environment before production.
-
-## Troubleshooting
-
-### Sync Not Working
-
-1. Check iCloud account status
-2. Verify network connectivity
-3. Check CloudKit Dashboard for errors
-4. Review sync statistics
-
-### Data Not Appearing
-
-1. Ensure sync completed successfully
-2. Check conflict resolution logs
-3. Verify record types match schema
-
-### Performance Issues
-
-1. Reduce sync frequency
-2. Batch operations
-3. Check network quality
-4. Monitor CloudKit quota
-
-## License
-
-Copyright © 2026 Runic. All rights reserved.