@sriinnu/runic 1.2.0 → 2.11.1

package/docs/cli.md

@@ -1,156 +0,0 @@
----
-summary: "Runic CLI for fetching usage from the command line."
-read_when:
-  - "You want to call Runic data from scripts or a terminal."
-  - "Adding or modifying Helix-based CLI commands."
-  - "Aligning menubar and CLI output/behavior."
----
-
-# Runic CLI
-
-A lightweight Helix-based CLI that mirrors the menubar app’s data paths (Codex web/RPC → PTY fallback; Claude web by default with CLI fallback and OAuth debug).
-Use it when you need usage numbers in scripts, CI, or dashboards without UI.
-
-## Install
-- In the app: **Preferences → Advanced → Install CLI**. This symlinks `RunicCLI` to `/usr/local/bin/runic` and `/opt/homebrew/bin/runic`.
-- From the repo: `./bin/install-runic-cli.sh` (same symlink targets).
-- Manual: `ln -sf "/Applications/Runic.app/Contents/Helpers/RunicCLI" /usr/local/bin/runic`.
-
-### Linux install
-- Download `RunicCLI-<tag>-linux-<arch>.tar.gz` from GitHub Releases (x86_64 + aarch64).
-- Extract; run `./runic` (symlink) or `./RunicCLI`.
-
-```
-tar -xzf RunicCLI-0.14.1-linux-x86_64.tar.gz
-./runic --version
-./runic usage --format json --pretty
-```
-
-## Build
-- `./Scripts/package_app.sh` (or `./Scripts/compile_and_run.sh`) bundles `RunicCLI` into `Runic.app/Contents/Helpers/RunicCLI`.
-- Standalone: `swift build -c release --product RunicCLI` (binary at `./.build/release/RunicCLI`).
-- Dependencies: Swift 6.2+, Helix package (`https://github.com/sriinnu/Helix`).
-
-## Command
-- `runic` defaults to the `usage` command.
-  - `--format text|json` (default: text).
-- `runic cost` prints local token cost usage (Claude + Codex) without web/CLI access.
-  - `--format text|json` (default: text).
-  - `--refresh` ignores cached scans.
-- `--provider codex|claude|zai|gemini|antigravity|cursor|factory|copilot|both|all` (default: your in-app toggles; falls back to Codex).
-  - `--no-credits` (hide Codex credits in text output).
-  - `--pretty` (pretty-print JSON).
-  - `--status` (fetch provider status pages and include them in output).
-  - `--antigravity-plan-debug` (debug: print Antigravity planInfo fields to stderr).
-- `--source <auto|web|cli|oauth>` (default: `auto`).
-    - `auto` (macOS only): uses browser cookies for Codex + Claude, with CLI fallback only when cookies are missing.
-    - `web` (macOS only): web-only; no CLI fallback.
-    - `cli`: CLI-only (Codex RPC → PTY fallback; Claude PTY).
-    - `oauth`: Claude OAuth only (debug); no fallback. Not supported for Codex.
-    - Output `source` reflects the strategy actually used (`openai-web`, `web`, `oauth`, `api`, `local`, or provider CLI label).
-    - Codex web: OpenAI web dashboard (usage limits, credits remaining, code review remaining, usage breakdown).
-        - `--web-timeout <seconds>` (default: 60)
-        - `--web-debug-dump-html` (writes HTML snapshots to `/tmp` when data is missing)
-    - Claude web: claude.ai API (session + weekly usage, plus account metadata when available).
-    - Linux: `web/auto` are not supported; CLI prints an error and exits non-zero.
-- Global flags: `-h/--help`, `-V/--version`, `-v/--verbose`, `--no-color`, `--log-level <trace|verbose|debug|info|warning|error|critical>`, `--json-output`.
-
-### Cost JSON payload
-`runic cost --format json` emits an array of payloads (one per provider).
-- `provider`, `source`, `updatedAt`
-- `sessionTokens`, `sessionCostUSD`
-- `last30DaysTokens`, `last30DaysCostUSD`
-- `daily[]`: `date`, `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheCreationTokens`, `totalTokens`, `totalCost`, `modelsUsed`, `modelBreakdowns[]` (`modelName`, `cost`)
-- `totals`: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheCreationTokens`, `totalTokens`, `totalCost`
-
-## Example usage
-```
-runic                          # text, respects app toggles
-runic --provider claude        # force Claude
-runic --provider all           # query all providers (honors your logins/toggles)
-runic --format json --pretty   # machine output
-runic --format json --provider both
-runic cost                     # local cost usage (last 30 days + today)
-runic cost --provider claude --format json --pretty
-COPILOT_API_TOKEN=... runic --provider copilot --format json --pretty
-runic --status                 # include status page indicator/description
-runic --provider codex --source web --format json --pretty
-```
-
-### Sample output (text)
-```
-Codex 0.6.0 (codex-cli)
-Session: 72% left
-Resets today at 2:15 PM
-Weekly: 41% left
-Resets Fri at 9:00 AM
-Credits: 112.4 left
-
-Claude Code 2.0.58 (web)
-Session: 88% left
-Resets tomorrow at 1:00 AM
-Weekly: 63% left
-Resets Sat at 6:00 AM
-Sonnet: 95% left
-Account: user@example.com
-Plan: Pro
-```
-
-### Sample output (JSON, pretty)
-```json
-{
-  "provider": "codex",
-  "version": "0.6.0",
-  "source": "openai-web",
-  "status": { "indicator": "none", "description": "Operational", "updatedAt": "2025-12-04T17:55:00Z", "url": "https://status.openai.com/" },
-  "usage": {
-    "primary": { "usedPercent": 28, "windowMinutes": 300, "resetsAt": "2025-12-04T19:15:00Z" },
-    "secondary": { "usedPercent": 59, "windowMinutes": 10080, "resetsAt": "2025-12-05T17:00:00Z" },
-    "tertiary": null,
-    "updatedAt": "2025-12-04T18:10:22Z",
-    "identity": {
-      "providerID": "codex",
-      "accountEmail": "user@example.com",
-      "accountOrganization": null,
-      "loginMethod": "plus"
-    },
-    "accountEmail": "user@example.com",
-    "accountOrganization": null,
-    "loginMethod": "plus"
-  },
-  "credits": { "remaining": 112.4, "updatedAt": "2025-12-04T18:10:21Z" },
-  "antigravityPlanInfo": null,
-  "openaiDashboard": {
-    "signedInEmail": "user@example.com",
-    "codeReviewRemainingPercent": 100,
-    "creditEvents": [
-      { "id": "00000000-0000-0000-0000-000000000000", "date": "2025-12-04T00:00:00Z", "service": "CLI", "creditsUsed": 123.45 }
-    ],
-    "dailyBreakdown": [
-      {
-        "day": "2025-12-04",
-        "services": [{ "service": "CLI", "creditsUsed": 123.45 }],
-        "totalCreditsUsed": 123.45
-      }
-    ],
-    "updatedAt": "2025-12-04T18:10:21Z"
-  }
-}
-```
-
-## Exit codes
-- 0: success
-- 2: provider missing (binary not on PATH)
-- 3: parse/format error
-- 4: CLI timeout
-- 1: unexpected failure
-
-## Notes
-- CLI reuses menubar toggles when present (prefers `com.sriinnu.athena.runic{,.debug}` defaults), otherwise defaults to Codex only.
-- Text output uses ANSI colors when stdout is a rich TTY; disable with `--no-color` or `NO_COLOR`/`TERM=dumb`.
-- Copilot CLI queries require `COPILOT_API_TOKEN` (GitHub OAuth token).
-- Prefer Codex RPC first, then PTY fallback; Claude defaults to web with CLI fallback when cookies are missing.
-- OpenAI web requires a signed-in `chatgpt.com` session in Safari, Chrome, or Firefox. No passwords are stored; Runic reuses cookies.
-- Safari cookie import may require granting Runic Full Disk Access (System Settings → Privacy & Security → Full Disk Access).
-- The `openaiDashboard` JSON field is normally sourced from the app’s cached dashboard snapshot; `--source auto|web` refreshes it live via WebKit using a per-account cookie store.
-- Future: optional `--from-cache` flag to read the menubar app’s persisted snapshot (if/when that file lands).

package/docs/cloudkit_sync_guide.md

@@ -1,495 +0,0 @@
-# CloudKit Sync Integration Guide
-
-## Overview
-
-Runic now includes a complete iCloud CloudKit synchronization infrastructure that enables cross-device syncing of usage data, user preferences, and alert configurations. This guide explains how to enable and use the sync functionality.
-
-## Architecture
-
-The sync infrastructure consists of 6 main components:
-
-### 1. **SyncProtocol.swift** - Core Protocol Definitions
-Defines the fundamental protocols and types for synchronization:
-- `SyncEngine` - Main protocol for sync operations (sync, push, fetch, delete)
-- `SyncableRecord` - Protocol for objects that can be synchronized
-- `SyncConflictResolverProtocol` - Protocol for conflict resolution
-- `SyncObserver` - Protocol for observing sync events
-- Supporting types: `SyncOptions`, `SyncResult`, `ConflictResolutionStrategy`, `SyncError`
-
-### 2. **SyncRecord.swift** - CloudKit Record Types
-Defines three syncable record types with CloudKit conversion:
-- `UsageSnapshotSyncRecord` - Syncs usage data across devices
-- `UserPreferencesSyncRecord` - Syncs user settings and preferences
-- `AlertConfigurationSyncRecord` - Syncs alert thresholds and notification settings
-- Includes encryption helpers for sensitive data (email addresses)
-
-### 3. **iCloudSyncEngine.swift** - CloudKit Implementation
-Actor-based CloudKit sync engine with:
-- Bidirectional sync (push and fetch)
-- Offline queue for pending operations
-- Retry logic with exponential backoff
-- Device identification for conflict resolution
-- Support for incremental sync with change tokens
-
-### 4. **SyncConflictResolver.swift** - Conflict Resolution
-Implements multiple conflict resolution strategies:
-- **Last-write-wins** - Most recently modified record wins (default)
-- **Prefer local** - Always keep local version
-- **Prefer remote** - Always keep remote version
-- **Highest version** - Keep record with highest version number
-- **Merge** - Custom merge logic per record type
-- Tracks conflict statistics for diagnostics
-
-### 5. **BackgroundSyncManager.swift** - Automatic Sync
-Manages background synchronization with:
-- Configurable sync intervals (active: 5 min, background: 1 hour)
-- Lifecycle-aware sync (app launch, foreground, background)
-- Observer pattern for sync status notifications
-- Sync history and statistics tracking
-- iOS background task support
-
-### 6. **SyncUsageExample.swift** - Integration Examples
-Contains comprehensive examples of:
-- Basic setup and configuration
-- Syncing different record types
-- Manual vs automatic sync
-- Custom conflict resolution
-- Observer pattern usage
-- Error handling
-- Statistics and monitoring
-
-## CloudKit Record Types
-
-The sync engine uses three CloudKit record types that must be configured in your iCloud container:
-
-### 1. UsageSnapshot
-```
-Record Type: 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 (encrypted, optional)
-  - updatedAt: Date/Time
-  - deviceName: String
-  - platform: String
-```
-
-### 2. UserPreferences
-```
-Record Type: 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
-```
-
-### 3. AlertConfiguration
-```
-Record Type: AlertConfiguration
-Fields:
-  - version: Int64
-  - modifiedAt: Date/Time
-  - lastModifiedDeviceID: String (optional)
-  - providerID: String
-  - warningThreshold: Double
-  - criticalThreshold: Double
-  - notificationChannels: List<String>
-  - enabled: Int64 (0 or 1)
-```
-
-## Enabling CloudKit
-
-### 1. Add CloudKit Capability
-
-You need to add CloudKit capability to your app. This requires an entitlements file:
-
-**Create `Runic.entitlements`:**
-```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.ubiquity-kvstore-identifier</key>
-    <string>$(TeamIdentifierPrefix)com.yourcompany.runic</string>
-    <key>com.apple.developer.icloud-services</key>
-    <array>
-        <string>CloudKit</string>
-    </array>
-</dict>
-</plist>
-```
-
-### 2. Configure CloudKit Container
-
-1. Sign in to [Apple Developer](https://developer.apple.com)
-2. Go to Certificates, Identifiers & Profiles
-3. Select your App ID
-4. Enable iCloud capability
-5. Create or select a CloudKit container (e.g., `iCloud.com.yourcompany.runic`)
-
-### 3. Create CloudKit Schema
-
-In the CloudKit Dashboard:
-
-1. Go to [CloudKit Console](https://icloud.developer.apple.com)
-2. Select your container
-3. Create the three record types listed above
-4. Set appropriate indexes and security settings:
-   - **Security**: Set all record types to "Readable and writable by the creator"
-   - **Indexes**: Add indexes on `modifiedAt` for efficient querying
-
-### 4. Update Package.swift (Already Done)
-
-The Sync directory exclusion has been removed from Package.swift, enabling the sync infrastructure.
-
-## Integration Steps
-
-### 1. Basic Setup
-
-```swift
-import RunicCore
-
-// Initialize sync engine
-let syncEngine = iCloudSyncEngine(
-    containerIdentifier: "iCloud.com.yourcompany.runic"
-)
-
-// Create sync manager with default configuration
-let syncManager = BackgroundSyncManager(
-    syncEngine: syncEngine,
-    config: .default
-)
-
-// Start automatic background sync
-await syncManager.start()
-```
-
-### 2. Custom Configuration
-
-```swift
-let config = SyncConfiguration(
-    activeSyncInterval: 180,      // 3 minutes when app is active
-    backgroundSyncInterval: 1800, // 30 minutes in background
-    syncOnForeground: true,       // Sync when app comes to foreground
-    syncOnBackground: true,       // Sync when app goes to background
-    defaultSyncOptions: SyncOptions(
-        forceFullSync: false,
-        batchSize: 50,
-        conflictStrategy: .lastWriteWins,
-        backgroundMode: true,
-        timeout: 30.0,
-        encryptSensitiveData: true
-    )
-)
-
-let syncManager = BackgroundSyncManager(
-    syncEngine: syncEngine,
-    config: config
-)
-```
-
-### 3. Sync Usage Data
-
-```swift
-// Create usage snapshot record
-let usageRecord = UsageSnapshotSyncRecord(
-    providerID: "claude",
-    primaryUsed: 75000,
-    primaryLimit: 100000,
-    secondaryUsed: 50,
-    secondaryLimit: 100,
-    costUSD: 3.75,
-    accountEmail: "user@example.com",
-    updatedAt: Date(),
-    deviceName: "MacBook Pro",
-    platform: "macOS"
-)
-
-// Queue for high-priority sync
-await syncEngine.enqueue(usageRecord, priority: .high)
-
-// Or push immediately
-let result = await syncEngine.push(records: [usageRecord])
-```
-
-### 4. Add Sync Observer
-
-```swift
-class MySyncObserver: SyncObserver {
-    func syncDidStart() {
-        print("Sync started")
-    }
-
-    func syncDidProgress(current: Int, total: Int) {
-        let percentage = (Double(current) / Double(total)) * 100
-        print("Progress: \(Int(percentage))%")
-    }
-
-    func syncDidComplete(result: SyncResult) {
-        print("Synced \(result.pushedCount + result.fetchedCount) records")
-    }
-
-    func syncDidFail(error: SyncError) {
-        print("Sync failed: \(error.localizedDescription)")
-    }
-}
-
-let observer = MySyncObserver()
-await syncManager.addObserver(observer)
-```
-
-### 5. Manual Sync
-
-```swift
-// Perform manual sync with custom options
-let options = SyncOptions(
-    forceFullSync: true,
-    conflictStrategy: .lastWriteWins
-)
-
-let result = await syncManager.syncNow(options: options)
-
-switch result {
-case .success(let syncResult):
-    print("Pushed: \(syncResult.pushedCount)")
-    print("Fetched: \(syncResult.fetchedCount)")
-    print("Conflicts: \(syncResult.conflictsResolved)")
-
-case .failure(let error):
-    print("Sync failed: \(error)")
-}
-```
-
-### 6. Monitor Sync Statistics
-
-```swift
-let stats = await syncManager.statistics
-
-print("Total syncs: \(stats.totalSyncs)")
-print("Success rate: \(stats.successRate)%")
-print("Average duration: \(stats.averageDuration)s")
-print("Last sync: \(stats.lastSyncDate?.description ?? "Never")")
-```
-
-## Conflict Resolution
-
-### Default Strategies
-
-1. **Last-write-wins** (default) - Most recently modified record wins
-2. **Prefer local** - Always keep local version
-3. **Prefer remote** - Always keep remote version
-4. **Highest version** - Keep record with highest version number
-5. **Merge** - Custom merge logic
-
-### Custom Merge Handlers
-
-The sync engine includes smart merge handlers for each record type:
-
-**UsageSnapshot**: Prefers record with most recent usage data
-**UserPreferences**: Merges enabled providers (union of both sets)
-**AlertConfiguration**: Uses most conservative thresholds, merges notification channels
-
-You can register custom merge handlers:
-
-```swift
-let resolver = SyncConflictResolver()
-await resolver.registerDefaultMergeHandlers()
-
-// Custom merge handler for usage snapshots
-await resolver.registerMergeHandler(for: CloudKitRecordType.usageSnapshot) { local, remote in
-    guard let localUsage = local as? UsageSnapshotSyncRecord,
-          let remoteUsage = remote as? UsageSnapshotSyncRecord else {
-        return local
-    }
-
-    // Custom logic: prefer record with higher usage
-    return localUsage.primaryUsed > remoteUsage.primaryUsed ? local : remote
-}
-```
-
-## Security
-
-### Encryption
-
-Sensitive data (email addresses) is automatically encrypted using AES-GCM before syncing to CloudKit. The encryption key is stored securely in the Keychain.
-
-### Privacy
-
-- All data is stored in the user's private CloudKit database
-- Only the user can access their own data
-- CloudKit records use user authentication
-
-## Error Handling
-
-The sync engine handles common errors gracefully:
-
-```swift
-switch syncError {
-case .iCloudAccountUnavailable:
-    // User not signed in to iCloud
-
-case .networkUnavailable:
-    // Network not available - changes queued for later
-
-case .quotaExceeded:
-    // iCloud storage full
-
-case .timeout:
-    // Sync operation timed out
-
-case .conflictResolutionFailed(let details):
-    // Could not resolve conflict
-
-case .cloudKitError(let ckError):
-    // CloudKit-specific error
-
-default:
-    // Other errors
-}
-```
-
-## Testing
-
-### Prerequisites
-
-1. Sign in to iCloud on your test device/simulator
-2. Enable iCloud Drive in System Settings
-3. Ensure network connectivity
-
-### Manual Testing
-
-1. Install app on Device A
-2. Create some usage data
-3. Wait for sync or trigger manual sync
-4. Install app on Device B (same iCloud account)
-5. Verify data appears after sync
-
-### Verifying CloudKit Data
-
-1. Open CloudKit Console
-2. Select your container
-3. Go to Data > Records
-4. View synced records
-
-## Performance Considerations
-
-### Sync Intervals
-
-- **Active sync**: Every 5 minutes when app is active
-- **Background sync**: Every hour when app is in background
-- **Foreground sync**: When app comes to foreground (if last sync > 5 min ago)
-
-### Batch Sizes
-
-Default batch size is 100 records. Adjust based on your data volume:
-
-```swift
-SyncOptions(batchSize: 50)  // For smaller syncs
-```
-
-### Offline Queue
-
-Records are automatically queued when offline and synced when connection is restored.
-
-## Troubleshooting
-
-### Common Issues
-
-1. **"iCloud account unavailable"**
-   - Check Settings > Apple ID > iCloud
-   - Enable iCloud Drive
-
-2. **"Network unavailable"**
-   - Check internet connection
-   - Changes will sync when online
-
-3. **"Quota exceeded"**
-   - User needs more iCloud storage
-   - Upgrade iCloud plan
-
-4. **Records not syncing**
-   - Check CloudKit Console for errors
-   - Verify entitlements are correct
-   - Ensure container identifier matches
-
-### Debug Logging
-
-Enable detailed sync logging in DEBUG builds:
-
-```swift
-#if DEBUG
-print("Sync engine: \(syncEngine)")
-print("Pending operations: \(await syncEngine.pendingOperationCount)")
-#endif
-```
-
-## Migration Notes
-
-If you have existing local data, you'll need to:
-
-1. Create sync records from local data
-2. Push to CloudKit on first launch
-3. Set appropriate version numbers
-4. Handle conflicts carefully during initial sync
-
-## Best Practices
-
-1. **Start sync early** - Initialize sync engine at app launch
-2. **Monitor conflicts** - Check conflict statistics regularly
-3. **Handle errors gracefully** - Queue operations when offline
-4. **Use appropriate priorities** - Critical data should use `.high` priority
-5. **Test thoroughly** - Test on multiple devices with same iCloud account
-6. **Monitor quota** - Be mindful of CloudKit storage limits
-
-## Compilation Status
-
-✅ **Build Status**: Successfully compiles
-- All sync files integrated into RunicCore module
-- CloudKit imports working correctly
-- Actor isolation properly implemented
-- Strict concurrency enabled
-
-### Warnings (Non-critical)
-
-- Codable warnings on `recordType` fields (by design - these are constants)
-- Timer isolation warnings (handled with @MainActor)
-
-## Next Steps
-
-1. Create entitlements file for your app
-2. Configure CloudKit container in Developer Portal
-3. Create CloudKit schema in CloudKit Console
-4. Integrate sync manager into your app
-5. Test on multiple devices
-6. Monitor sync statistics and errors
-
-## Support
-
-For issues or questions about the sync infrastructure:
-1. Check CloudKit Console for server-side errors
-2. Review sync statistics for client-side issues
-3. Enable debug logging for detailed diagnostics
-4. Consult SyncUsageExample.swift for integration patterns
-
----
-
-**Version**: 1.0
-**Last Updated**: 2026-01-31
-**Status**: Production Ready