@sriinnu/runic 1.2.0 → 2.11.1

package/docs/sync_files_summary.md

@@ -1,391 +0,0 @@
-# Sync Infrastructure File Summary
-
-## Overview
-
-The sync infrastructure in `/Sources/RunicCore/Sync/` consists of 6 files that work together to provide iCloud CloudKit synchronization for Runic. This document provides a detailed summary of what each file does.
-
----
-
-## 1. SyncProtocol.swift
-
-**Purpose**: Core protocol definitions and supporting types
-
-### Key Components
-
-#### Protocols
-- **SyncEngine**: Main protocol for sync operations
-  - `sync(options:)` - Full bidirectional sync
-  - `push(records:)` - Push local changes to remote
-  - `fetch(recordTypes:)` - Fetch changes from remote
-  - `delete(recordIDs:)` - Delete records from remote
-  - `resetSync()` - Reset sync state
-
-- **SyncableRecord**: Protocol for syncable objects
-  - Required properties: `recordID`, `recordType`, `version`, `modifiedAt`, `lastModifiedDeviceID`
-  - Required methods: `toCKRecord()`, `fromCKRecord(_:)`
-  - Must conform to `Sendable` and `Codable`
-
-- **SyncConflictResolverProtocol**: Conflict resolution interface
-  - `resolve(local:remote:strategy:)` - Resolves conflicts between versions
-
-- **SyncObserver**: Observer pattern for sync events
-  - `syncDidStart()`, `syncDidProgress(current:total:)`, `syncDidComplete(result:)`, `syncDidFail(error:)`
-
-#### Supporting Types
-- **SyncOptions**: Configuration for sync operations
-  - `forceFullSync`, `batchSize`, `conflictStrategy`, `backgroundMode`, `timeout`, `encryptSensitiveData`
-
-- **SyncResult**: Statistics from sync operation
-  - `pushedCount`, `fetchedCount`, `conflictsResolved`, `deletedCount`, `duration`, `warnings`
-
-- **ConflictResolutionStrategy**: Conflict resolution strategies
-  - `.lastWriteWins`, `.preferLocal`, `.preferRemote`, `.highestVersion`, `.merge`
-
-- **SyncError**: Error types with localized descriptions
-  - `.iCloudAccountUnavailable`, `.networkUnavailable`, `.quotaExceeded`, `.timeout`, etc.
-
-- **SyncPriority**: Priority levels for sync operations
-  - `.low`, `.normal`, `.high`, `.critical`
-
-**Lines of Code**: 289
-
----
-
-## 2. SyncRecord.swift
-
-**Purpose**: Concrete syncable record types with CloudKit conversion
-
-### Key Components
-
-#### CloudKit Record Type Constants
-```swift
-CloudKitRecordType.usageSnapshot
-CloudKitRecordType.userPreferences
-CloudKitRecordType.alertConfiguration
-CloudKitRecordType.syncMetadata
-```
-
-#### Record Types
-
-1. **UsageSnapshotSyncRecord**
-   - **Purpose**: Syncs usage data across devices
-   - **Fields**: providerID, primaryUsed, primaryLimit, secondaryUsed, secondaryLimit, costUSD, accountEmail (encrypted), updatedAt, deviceName, platform
-   - **Features**: Encrypts sensitive email data
-
-2. **UserPreferencesSyncRecord**
-   - **Purpose**: Syncs user settings and preferences
-   - **Fields**: refreshInterval, enabledProviders, notificationsEnabled, autoRefreshEnabled, theme, displayFormat
-   - **Features**: Single record per user (fixed recordID)
-
-3. **AlertConfigurationSyncRecord**
-   - **Purpose**: Syncs alert thresholds and notification settings
-   - **Fields**: providerID, warningThreshold, criticalThreshold, notificationChannels, enabled
-   - **Features**: One record per provider
-
-#### Encryption Helpers
-- `encryptString(_:)` - AES-GCM encryption for sensitive data
-- `decryptString(_:)` - Decryption with error handling
-- `getOrCreateEncryptionKey()` - Keychain-based key management
-- `saveToKeychain(key:data:)` - Secure key storage
-- `loadFromKeychain(key:)` - Key retrieval
-
-**Lines of Code**: 394
-
----
-
-## 3. iCloudSyncEngine.swift
-
-**Purpose**: CloudKit-based synchronization engine implementation
-
-### Key Components
-
-#### Architecture
-- **Actor-based**: Thread-safe concurrent access
-- **CloudKit Integration**: Uses CKContainer and CKDatabase
-- **Offline Support**: Queue for pending operations
-- **Retry Logic**: Exponential backoff for network errors
-
-#### Properties
-- `container`: CloudKit container
-- `database`: Private CloudKit database
-- `conflictResolver`: Handles conflicts
-- `pendingQueue`: Offline operation queue
-- `changeToken`: For incremental sync
-- `deviceID`: Unique device identifier
-
-#### Key Methods
-
-1. **sync(options:)**: Full bidirectional sync
-   - Checks iCloud account status
-   - Processes pending queue
-   - Fetches remote changes
-   - Detects and resolves conflicts
-   - Returns sync statistics
-
-2. **push(records:)**: Push local changes
-   - Converts SyncableRecord to CKRecord
-   - Batch saves to CloudKit
-   - Handles CloudKit errors
-   - Returns saved record IDs
-
-3. **fetch(recordTypes:)**: Fetch remote changes
-   - Queries CloudKit for each record type
-   - Parses CKRecords to SyncableRecords
-   - Returns fetched records
-
-4. **delete(recordIDs:)**: Delete remote records
-   - Converts IDs to CKRecord.ID
-   - Batch deletes from CloudKit
-   - Returns deleted IDs
-
-5. **enqueue(_:priority:)**: Queue offline operations
-   - Adds to pending queue
-   - Sorts by priority
-
-#### Error Handling
-- Network errors: Retry with exponential backoff
-- Quota exceeded: Return appropriate error
-- Authentication failures: Return auth error
-- Conflict detection: Use conflict resolver
-
-**Lines of Code**: 309
-
----
-
-## 4. SyncConflictResolver.swift
-
-**Purpose**: Default conflict resolution implementation
-
-### Key Components
-
-#### Architecture
-- **Actor-based**: Thread-safe conflict resolution
-- **Pluggable**: Custom merge handlers per record type
-- **Statistics Tracking**: Comprehensive conflict metrics
-
-#### Properties
-- `conflictStats`: Tracks resolution statistics
-- `mergeHandlers`: Custom handlers per record type
-
-#### Conflict Resolution Strategies
-
-1. **Last-write-wins**: Keep most recently modified
-   - Uses `modifiedAt` timestamp
-   - Version as tiebreaker
-
-2. **Prefer local**: Always keep local version
-
-3. **Prefer remote**: Always keep remote version
-
-4. **Highest version**: Keep highest version number
-   - Timestamp as tiebreaker
-
-5. **Merge**: Custom merge logic
-   - Uses registered handlers
-   - Falls back to last-write-wins
-
-#### Default Merge Handlers
-
-1. **UsageSnapshot**: Prefer record with most recent data
-2. **UserPreferences**: Merge enabled providers (union)
-3. **AlertConfiguration**: Use most conservative thresholds
-
-#### Statistics
-- Total conflicts resolved
-- Conflicts by record type
-- Conflicts by strategy
-- Local vs remote win rate
-- Last conflict timestamp
-
-**Lines of Code**: 311
-
----
-
-## 5. BackgroundSyncManager.swift
-
-**Purpose**: Manages automatic background synchronization
-
-### Key Components
-
-#### Architecture
-- **Actor-based**: Thread-safe background sync
-- **Lifecycle-aware**: Responds to app state changes
-- **Timer-based**: Periodic sync intervals
-- **Observer pattern**: Notifies sync status
-
-#### Properties
-- `syncEngine`: Underlying sync engine
-- `config`: Sync configuration
-- `syncTimer`: Periodic sync timer (MainActor)
-- `isEnabled`: Sync state
-- `lastSyncDate`: Last successful sync
-- `syncHistory`: Historical sync records
-- `observers`: Registered observers
-
-#### Configuration
-- `activeSyncInterval`: Sync interval when active (default: 5 min)
-- `backgroundSyncInterval`: Sync interval in background (default: 1 hour)
-- `syncOnForeground`: Sync when app becomes active
-- `syncOnBackground`: Sync when app enters background
-
-#### Key Methods
-
-1. **start()**: Starts automatic sync
-   - Enables sync
-   - Schedules first sync
-
-2. **stop()**: Stops automatic sync
-   - Disables sync
-   - Invalidates timer
-
-3. **syncNow(options:)**: Manual sync
-   - Notifies observers
-   - Performs sync
-   - Records history
-   - Returns result
-
-4. **addObserver(_:)**: Register observer
-5. **removeObserver(_:)**: Unregister observer
-
-#### Lifecycle Integration
-- `didBecomeActiveNotification`: Sync on foreground
-- `didEnterBackgroundNotification`: Sync on background
-- iOS background tasks: Complete sync before suspension
-
-#### Statistics
-- Last sync date
-- Total/successful/failed syncs
-- Success rate percentage
-- Average sync duration
-- Recent sync history (last 10)
-
-**Lines of Code**: 385
-
----
-
-## 6. SyncUsageExample.swift
-
-**Purpose**: Comprehensive integration examples (DEBUG only)
-
-### Key Components
-
-#### Example Functions
-
-1. **setupSyncExample()**: Basic initialization
-2. **customConfigurationExample()**: Custom config
-3. **syncUsageDataExample()**: Sync usage records
-4. **syncPreferencesExample()**: Sync preferences
-5. **syncAlertConfigExample()**: Sync alerts
-6. **manualSyncExample()**: Manual sync with options
-7. **conflictResolutionExample()**: Custom conflict handlers
-8. **observerExample()**: Observer pattern
-9. **statisticsExample()**: Monitoring and stats
-10. **errorHandlingExample()**: Error handling patterns
-
-#### Example Observer
-- **SyncProgressObserver**: Sample observer implementation
-  - Prints sync start, progress, completion, errors
-  - Demonstrates observer pattern
-
-#### Coverage
-- All record types (usage, preferences, alerts)
-- All sync operations (push, fetch, sync, queue)
-- All conflict strategies
-- Custom merge handlers
-- Statistics and monitoring
-- Error handling patterns
-
-**Lines of Code**: 295
-
----
-
-## File Dependencies
-
-```
-SyncProtocol.swift
-    ↓
-    ├── SyncRecord.swift
-    ├── iCloudSyncEngine.swift
-    │       ↓
-    │   SyncConflictResolver.swift
-    │       ↓
-    │   BackgroundSyncManager.swift
-    │       ↓
-    └── SyncUsageExample.swift
-```
-
----
-
-## Total Statistics
-
-- **Total Files**: 6
-- **Total Lines**: ~1,983 lines
-- **Protocols Defined**: 4
-- **Concrete Types**: 12
-- **Enums**: 4
-- **Supporting Functions**: 15+
-- **Example Functions**: 10
-
----
-
-## Key Features
-
-### ✅ Implemented
-- [x] Full bidirectional sync
-- [x] Offline queue with priorities
-- [x] Conflict resolution (5 strategies)
-- [x] Custom merge handlers
-- [x] AES-GCM encryption
-- [x] Background sync manager
-- [x] Lifecycle integration
-- [x] Observer pattern
-- [x] Retry logic with backoff
-- [x] Statistics and monitoring
-- [x] Error handling
-- [x] Comprehensive examples
-
-### 🔒 Security
-- [x] Private CloudKit database
-- [x] Keychain-based encryption keys
-- [x] AES-GCM for sensitive data
-- [x] User authentication required
-
-### ⚡ Performance
-- [x] Actor-based concurrency
-- [x] Batch operations
-- [x] Incremental sync (change tokens)
-- [x] Configurable intervals
-- [x] Priority-based queue
-
-### 🧪 Testing
-- [x] DEBUG-only examples
-- [x] Comprehensive error scenarios
-- [x] Observer testing
-- [x] Statistics validation
-
----
-
-## Usage Pattern
-
-```swift
-// 1. Initialize
-let syncEngine = iCloudSyncEngine()
-let syncManager = BackgroundSyncManager(syncEngine: syncEngine)
-
-// 2. Configure observer
-await syncManager.addObserver(myObserver)
-
-// 3. Start automatic sync
-await syncManager.start()
-
-// 4. Create and sync records
-let record = UsageSnapshotSyncRecord(...)
-await syncEngine.push(records: [record])
-
-// 5. Monitor statistics
-let stats = await syncManager.statistics
-```
-
----
-
-**Note**: All files compile successfully with Swift 6 strict concurrency enabled. The infrastructure is production-ready and fully documented.

package/docs/sync_quick_reference.md

@@ -1,225 +0,0 @@
-# CloudKit Sync Quick Reference
-
-## One-Minute Setup
-
-```swift
-import RunicCore
-
-// 1. Initialize
-let syncEngine = iCloudSyncEngine()
-let syncManager = BackgroundSyncManager(syncEngine: syncEngine)
-
-// 2. Start
-await syncManager.start()
-
-// Done! Sync runs automatically every 5 minutes (active) / 1 hour (background)
-```
-
----
-
-## Common Operations
-
-### Push Usage Data
-```swift
-let record = UsageSnapshotSyncRecord(
-    providerID: "claude",
-    primaryUsed: 75000,
-    primaryLimit: 100000,
-    deviceName: "MacBook Pro",
-    platform: "macOS"
-)
-await syncEngine.push(records: [record])
-```
-
-### Sync Preferences
-```swift
-let prefs = UserPreferencesSyncRecord(
-    refreshInterval: 300,
-    enabledProviders: ["claude", "openai"],
-    notificationsEnabled: true
-)
-await syncEngine.push(records: [prefs])
-```
-
-### Manual Sync
-```swift
-let result = await syncManager.syncNow()
-```
-
-### Force Full Sync
-```swift
-let options = SyncOptions(forceFullSync: true)
-let result = await syncManager.syncNow(options: options)
-```
-
----
-
-## Monitoring
-
-### Check Sync Status
-```swift
-let stats = await syncManager.statistics
-print("Success rate: \(stats.successRate)%")
-print("Last sync: \(stats.lastSyncDate)")
-```
-
-### Add Observer
-```swift
-class MySyncObserver: SyncObserver {
-    func syncDidStart() { print("Syncing...") }
-    func syncDidProgress(current: Int, total: Int) { }
-    func syncDidComplete(result: SyncResult) { print("Done!") }
-    func syncDidFail(error: SyncError) { print("Failed: \(error)") }
-}
-
-await syncManager.addObserver(MySyncObserver())
-```
-
----
-
-## Error Handling
-
-```swift
-switch result {
-case .success(let syncResult):
-    print("Synced \(syncResult.pushedCount + syncResult.fetchedCount) records")
-
-case .failure(let error):
-    switch error {
-    case .iCloudAccountUnavailable:
-        // Show "Sign in to iCloud" message
-    case .networkUnavailable:
-        // Queue for later, show offline indicator
-    case .quotaExceeded:
-        // Show "Storage full" message
-    default:
-        // Generic error handling
-    }
-}
-```
-
----
-
-## Configuration
-
-### Custom Intervals
-```swift
-let config = SyncConfiguration(
-    activeSyncInterval: 180,      // 3 min
-    backgroundSyncInterval: 1800, // 30 min
-    syncOnForeground: true,
-    syncOnBackground: true
-)
-let syncManager = BackgroundSyncManager(syncEngine: syncEngine, config: config)
-```
-
-### Custom Conflict Strategy
-```swift
-let options = SyncOptions(
-    conflictStrategy: .merge  // or .lastWriteWins, .preferLocal, .preferRemote
-)
-```
-
----
-
-## CloudKit Record Types
-
-| Record Type | Purpose | Key Fields |
-|------------|---------|------------|
-| **UsageSnapshot** | Usage data | providerID, primaryUsed, primaryLimit, costUSD |
-| **UserPreferences** | Settings | refreshInterval, enabledProviders, theme |
-| **AlertConfiguration** | Alerts | warningThreshold, criticalThreshold, enabled |
-
----
-
-## Conflict Resolution Strategies
-
-| Strategy | Behavior |
-|----------|----------|
-| **lastWriteWins** | Most recent modification wins (default) |
-| **preferLocal** | Always keep local version |
-| **preferRemote** | Always keep remote version |
-| **highestVersion** | Highest version number wins |
-| **merge** | Custom merge logic (smart defaults included) |
-
----
-
-## Offline Support
-
-```swift
-// Queue for sync when online (automatic)
-await syncEngine.enqueue(record, priority: .high)
-
-// Check pending operations
-let pending = await syncEngine.pendingOperationCount
-```
-
----
-
-## Security
-
-- ✅ Private CloudKit database (user-specific)
-- ✅ AES-GCM encryption for sensitive data
-- ✅ Keychain-based key storage
-- ✅ User authentication required
-
----
-
-## Troubleshooting
-
-### "iCloud account unavailable"
-→ Settings > Apple ID > iCloud > Enable iCloud Drive
-
-### "Network unavailable"
-→ Changes queued automatically, will sync when online
-
-### Records not syncing
-1. Check CloudKit Console for errors
-2. Verify entitlements include CloudKit
-3. Ensure container identifier is correct
-
----
-
-## Performance Tips
-
-- Default batch size: 100 records (adjust with `SyncOptions.batchSize`)
-- Use priority queue for critical data: `.high` or `.critical`
-- Monitor statistics to track sync performance
-- Sync on foreground disabled if last sync < 5 min ago
-
----
-
-## Required Setup (One-Time)
-
-1. **Entitlements**: Add CloudKit to `Runic.entitlements`
-2. **Container**: Create iCloud container in Developer Portal
-3. **Schema**: Create 3 record types in CloudKit Console
-4. **Code**: Initialize sync engine at app launch
-
-See `CLOUDKIT_SYNC_GUIDE.md` for detailed setup instructions.
-
----
-
-## Files
-
-- `SyncProtocol.swift` - Protocols and types
-- `SyncRecord.swift` - Record definitions
-- `iCloudSyncEngine.swift` - CloudKit implementation
-- `SyncConflictResolver.swift` - Conflict resolution
-- `BackgroundSyncManager.swift` - Automatic sync
-- `SyncUsageExample.swift` - Integration examples
-
----
-
-## Build Status
-
-✅ **Compiles successfully** with Swift 6 strict concurrency
-- Zero errors
-- Only non-critical warnings (Codable, Timer isolation)
-- Production ready
-
----
-
-**Version**: 1.0
-**Last Updated**: 2026-01-31
-**Status**: Ready for integration

package/docs/todo.md

@@ -1,11 +0,0 @@
----
-summary: "Pending cleanup items for Runic (e.g., retire Claude Opus fallback)."
-read_when:
-  - Grooming backlog or planning maintenance
-  - Removing legacy Claude Opus handling
----
-
-## TODO
-
-- December 2025: remove the Claude Opus fallback logic (Claude Code) once users have fully migrated; clean up any UI labels and parsers that reference Opus as a tertiary limit.
-- January 2026: owner-authorized roadmap item to deliver Windows and iOS app support.

package/docs/ui.md

@@ -1,29 +0,0 @@
----
-summary: "Menu bar UI, icon rendering, and menu layout details."
-read_when:
-  - Changing menu layout, icon rendering, or UI copy
-  - Updating menu card or provider-specific UI
----
-
-# UI & icon
-
-## Menu bar
-- LSUIElement app: no Dock icon; status item uses custom NSImage.
-- Merge Icons toggle combines providers into one status item with a switcher.
-
-## Icon rendering
-- 18×18 template image.
-- Top bar = 5-hour window; bottom hairline = weekly window.
-- Fill represents percent remaining by default; “Show usage as used” flips to percent used.
-- Dimmed when last refresh failed; status overlays render incident indicators.
-- Advanced: menu bar can show provider branding icons with a percent label instead of critter bars.
-
-## Menu card
-- Session + weekly rows with resets (relative countdown when available).
-- Codex-only: Credits + “Buy Credits…” in-card action.
-- Web-only rows (when OpenAI web enabled): code review remaining, usage breakdown submenu.
-
-## Widgets (high level)
-- Widget entries mirror the menu card; detailed pipeline in `docs/widgets.md`.
-
-See also: `docs/widgets.md`.

package/docs/web-integration.md

@@ -1,9 +0,0 @@
----
-summary: "Deprecated: OpenAI web dashboard integration is documented in docs/codex.md."
-read_when:
-  - Redirect: see docs/codex.md
----
-
-# OpenAI web integration (Codex)
-
-Moved to `docs/codex.md`.