@sriinnu/runic 1.0.0

package/docs/widgets.md

@@ -0,0 +1,85 @@
+---
+summary: "WidgetKit snapshot pipeline + visibility troubleshooting for Runic widgets."
+read_when:
+  - Modifying WidgetKit extension behavior or snapshot format
+  - Debugging widget update timing
+  - Widget gallery shows no Runic widgets
+---
+
+# Widgets
+
+## Snapshot pipeline
+- `WidgetSnapshotStore` writes compact JSON snapshots to the app-group container.
+- Widgets read the snapshot and render usage/credits/history states.
+
+## Extension
+- `Sources/RunicWidget` contains timeline + views.
+- Keep data shape in sync with `WidgetSnapshot` in the main app.
+
+## Visibility troubleshooting (macOS 14+)
+When widgets do not appear in the gallery at all, the issue is almost always
+registration, signing, or daemon caching (not SwiftUI code).
+
+### 1) Verify the extension bundle exists where macOS expects it
+```
+APP="/Applications/Runic.app"
+WAPPEX="$APP/Contents/PlugIns/RunicWidget.appex"
+
+ls -la "$WAPPEX" "$WAPPEX/Contents" "$WAPPEX/Contents/MacOS"
+```
+
+### 2) PlugInKit registration (pkd)
+```
+pluginkit -m -p com.apple.widgetkit-extension -v | grep -i runic || true
+pluginkit -m -p com.apple.widgetkit-extension -i com.sriinnu.athena.runic.widget -vv
+```
+Notes:
+- `+` = elected to use, `-` = ignored (PlugInKit elections).
+- If missing or ignored, force-add and re-elect:
+```
+pluginkit -a "$WAPPEX"
+pluginkit -e use -p com.apple.widgetkit-extension -i com.sriinnu.athena.runic.widget
+```
+- Check for duplicates (old installs or version precedence):
+```
+pluginkit -m -D -p com.apple.widgetkit-extension -i com.sriinnu.athena.runic.widget -vv
+```
+If multiple paths appear, delete older installs and bump `CFBundleVersion`.
+
+### 3) Code signing + Gatekeeper assessment
+Widgets are loaded by system daemons. Any signing failure can hide the widget.
+```
+codesign --verify --deep --strict --verbose=4 /Applications/Runic.app
+codesign --verify --strict --verbose=4 "$WAPPEX"
+codesign --verify --strict --verbose=4 "$WAPPEX/Contents/MacOS/RunicWidget"
+spctl --assess --type execute --verbose=4 /Applications/Runic.app
+```
+
+### 4) Restart the right daemons (NotificationCenter alone is not enough)
+```
+killall -9 pkd || true
+sudo killall -9 chronod || true
+killall Dock NotificationCenter || true
+```
+
+### 5) Watch logs while opening the widget gallery
+```
+log stream --style compact --predicate '(process == "pkd" OR process == "chronod" OR subsystem CONTAINS "PlugInKit" OR subsystem CONTAINS "WidgetKit")'
+```
+
+### 6) Packaging sanity checks
+- Widget bundle id should be `com.sriinnu.athena.runic.widget`.
+- `NSExtensionPointIdentifier` must be `com.apple.widgetkit-extension`.
+- Bundle folder name should match: `RunicWidget.appex`.
+
+Optional: re-seed LaunchServices (rarely helps, but low risk):
+```
+/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -seed
+```
+
+## Common post-visibility issue: stale data
+If the widget appears but always shows preview data:
+- App writes snapshot to fallback path while widget reads app-group container.
+- Validate that both app and widget resolve the same app-group container.
+
+See also: `docs/ui.md`, `docs/packaging.md`.

package/docs/workflows/error-handling-improvements.md

@@ -0,0 +1,434 @@
+# Error Handling Improvements
+
+This document describes the comprehensive error handling improvements made to the Runic application.
+
+## Overview
+
+We've implemented a structured error messaging system across both Swift (macOS) and TypeScript (React Native) codebases that provides:
+
+1. **Structured error messages** with actionable guidance
+2. **Error codes** for support and debugging
+3. **Automatic retry** with exponential backoff
+4. **User-friendly error displays** in the UI
+
+## Error Code System
+
+### Categories
+
+Error codes follow a hierarchical structure: `CATEGORY_NNN`
+
+| Category | Range | Description |
+|----------|-------|-------------|
+| NET | 001-099 | Network errors (connection, timeout, DNS) |
+| AUTH | 001-099 | Authentication errors (invalid token, expired, OAuth) |
+| API | 001-099 | API errors (4xx/5xx responses) |
+| RATE | 001-099 | Rate limiting and quota errors |
+| PARSE | 001-099 | Data parsing errors |
+| CLI | 001-099 | CLI tool errors |
+| STORE | 001-099 | Storage errors |
+| SYNC | 001-099 | Sync operation errors |
+| CONFIG | 001-099 | Configuration errors |
+
+### Common Error Codes
+
+- `NET_001`: Network connection failed
+- `NET_003`: Request timeout
+- `AUTH_001`: Authentication failed
+- `AUTH_003`: API token expired
+- `API_001`: Generic API error
+- `API_003`: Server error (5xx)
+- `RATE_001`: Rate limit exceeded
+- `PARSE_001`: JSON parsing failed
+
+## Error Message Structure
+
+Every error message includes:
+
+```swift
+struct RunicErrorMessage {
+    let title: String           // "Unable to sync with Claude API"
+    let reason: String          // "Network connection lost"
+    let steps: [String]         // ["Check internet", "Verify endpoint", ...]
+    let code: RunicErrorCode    // NET_001
+    let retryable: Bool         // true
+    let providerName: String?   // "Claude"
+}
+```
+
+## Usage Examples
+
+### Swift (macOS)
+
+#### Creating Error Messages
+
+```swift
+// Network error
+let error = ErrorMessageBuilder.networkError(
+    provider: "Claude",
+    reason: "Connection timeout after 30 seconds"
+)
+
+// Authentication error
+let error = ErrorMessageBuilder.authenticationError(
+    provider: "Codex",
+    reason: "API token has expired",
+    expired: true
+)
+
+// Rate limit error
+let error = ErrorMessageBuilder.rateLimitError(
+    provider: "OpenAI",
+    retryAfter: Date().addingTimeInterval(3600)
+)
+
+// API error with status code
+let error = ErrorMessageBuilder.apiError(
+    provider: "MiniMax",
+    statusCode: 503,
+    details: "Service temporarily unavailable"
+)
+```
+
+#### Using Error Messages in Enums
+
+```swift
+public enum ClaudeUsageError: LocalizedError {
+    case networkError(RunicErrorMessage)
+    case parseFailed(RunicErrorMessage)
+
+    public var errorDescription: String? {
+        switch self {
+        case .networkError(let msg), .parseFailed(let msg):
+            return msg.compactDescription
+        }
+    }
+
+    public var errorMessage: RunicErrorMessage {
+        switch self {
+        case .networkError(let msg), .parseFailed(let msg):
+            return msg
+        }
+    }
+}
+```
+
+#### Retry with Exponential Backoff
+
+```swift
+import RunicCore
+
+// Use default retry strategy (3 attempts, 1s-8s)
+let data = try await RetryStrategy.default.execute(
+    operation: {
+        try await fetchProviderData()
+    },
+    onRetry: { attempt, delay in
+        print("Retry attempt \(attempt) after \(delay)s")
+    }
+)
+
+// Use aggressive retry strategy (5 attempts, 2s-16s)
+let data = try await RetryStrategy.aggressive.execute {
+    try await fetchProviderData()
+}
+
+// Custom retry strategy
+let strategy = RetryStrategy(
+    maxAttempts: 4,
+    baseDelay: 2.0,
+    maxDelay: 10.0,
+    useJitter: true
+)
+```
+
+#### Displaying Errors in UI
+
+```swift
+import SwiftUI
+
+// Full error display with retry
+ErrorDisplayView(
+    error: errorMessage,
+    onRetry: {
+        Task { await refreshData() }
+    },
+    onDismiss: {
+        clearError()
+    }
+)
+
+// Compact error display
+CompactErrorView(
+    error: errorMessage,
+    onRetry: {
+        Task { await refreshData() }
+    }
+)
+```
+
+### TypeScript (React Native)
+
+#### Creating Error Messages
+
+```typescript
+import { ErrorMessageBuilder } from '@/utils';
+
+// Network error
+const error = ErrorMessageBuilder.networkError({
+  provider: 'Claude',
+  reason: 'Connection timeout',
+  timeout: true,
+});
+
+// Authentication error
+const error = ErrorMessageBuilder.authenticationError({
+  provider: 'Codex',
+  reason: 'Invalid API token',
+  expired: false,
+});
+
+// Rate limit error
+const error = ErrorMessageBuilder.rateLimitError({
+  provider: 'OpenAI',
+  retryAfter: new Date(Date.now() + 3600000),
+});
+
+// API error
+const error = ErrorMessageBuilder.apiError({
+  provider: 'MiniMax',
+  statusCode: 503,
+  details: 'Service unavailable',
+});
+```
+
+#### Using Retry with Async Operations
+
+```typescript
+import { retryWithBackoff, RetryStrategy } from '@/utils';
+
+// Basic retry with default strategy
+const data = await retryWithBackoff(
+  async () => await fetchProviderData(provider),
+  {
+    onRetry: (attempt, delay) => {
+      console.log(`Retry ${attempt} after ${delay}ms`);
+    },
+  }
+);
+
+// Aggressive retry strategy
+const data = await retryWithBackoff(
+  async () => await fetchProviderData(provider),
+  RetryStrategy.aggressive()
+);
+
+// Custom retry logic
+const data = await retryWithBackoff(
+  async () => await fetchProviderData(provider),
+  {
+    maxAttempts: 5,
+    baseDelay: 2000,
+    maxDelay: 16000,
+    shouldRetry: (error) => {
+      // Custom retry logic
+      return error instanceof ApiError && error.isRetryable;
+    },
+  }
+);
+```
+
+#### Displaying Errors in React Native
+
+```tsx
+import { ErrorDisplay, CompactErrorDisplay } from '@/components';
+
+// Full error display
+<ErrorDisplay
+  error={errorMessage}
+  onRetry={handleRetry}
+  onDismiss={handleDismiss}
+  defaultExpanded={false}
+/>
+
+// Compact inline error
+<CompactErrorDisplay
+  error={errorMessage}
+  onRetry={handleRetry}
+/>
+```
+
+## Before and After Examples
+
+### Example 1: Network Error
+
+**Before:**
+```swift
+throw URLError(.timedOut)
+// UI shows: "The request timed out."
+```
+
+**After:**
+```swift
+throw ClaudeUsageError.networkError(
+    ErrorMessageBuilder.networkError(
+        provider: "Claude",
+        reason: "Request timed out after 30 seconds",
+        timeout: true
+    )
+)
+
+// UI shows:
+// Title: "Unable to sync with Claude API"
+// Reason: "Request timed out after 30 seconds"
+// Next Steps:
+// 1. Check your internet connection
+// 2. Verify the API endpoint is accessible
+// 3. Try again in a few moments
+// 4. Check if your firewall is blocking the connection
+// Error Code: NET_003
+// [Retry Button]
+```
+
+### Example 2: Authentication Error
+
+**Before:**
+```typescript
+throw new Error('Invalid API token or unauthorized');
+// UI shows: "Invalid API token or unauthorized"
+```
+
+**After:**
+```typescript
+throw new ApiError(
+  'Authentication failed',
+  401,
+  'openai',
+  ErrorMessageBuilder.authenticationError({
+    provider: 'OpenAI',
+    reason: 'API token has expired',
+    expired: true,
+  })
+);
+
+// UI shows:
+// Title: "Authentication failed for OpenAI"
+// Reason: "API token has expired"
+// Next Steps:
+// 1. Refresh your authentication token
+// 2. Verify your API credentials are correct
+// 3. Check if your API key is active
+// 4. Contact OpenAI support if the issue persists
+// Error Code: AUTH_003
+```
+
+### Example 3: Rate Limit Error
+
+**Before:**
+```swift
+// UI shows: "Rate limit exceeded"
+```
+
+**After:**
+```swift
+throw UsageError.rateLimitError(
+    ErrorMessageBuilder.rateLimitError(
+        provider: "Anthropic",
+        retryAfter: Date().addingTimeInterval(1800)
+    )
+)
+
+// UI shows:
+// Title: "Rate limit exceeded"
+// Reason: "Anthropic API rate limit exceeded"
+// Next Steps:
+// 1. Rate limit resets at 3:30 PM
+// 2. Reduce your request frequency
+// 3. Check your Anthropic plan limits
+// 4. Consider upgrading your plan for higher limits
+// Error Code: RATE_001
+// [Retry Button]
+```
+
+## Integration Checklist
+
+### For New Provider Implementations
+
+- [ ] Define provider-specific error enum with `RunicErrorMessage`
+- [ ] Use `ErrorMessageBuilder` for all error cases
+- [ ] Implement retry logic for transient errors
+- [ ] Add error display in provider UI
+- [ ] Test all error scenarios
+
+### For Existing Code Updates
+
+- [ ] Replace generic errors with structured error messages
+- [ ] Add error codes to all error paths
+- [ ] Implement retry for network/API calls
+- [ ] Update UI to show detailed error information
+- [ ] Add unit tests for error handling
+
+## Files Modified/Created
+
+### Swift (macOS)
+
+**Created:**
+- `Sources/RunicCore/Errors/RunicErrorCode.swift` - Error code definitions
+- `Sources/RunicCore/Errors/RunicErrorMessage.swift` - Error message structures
+- `Sources/RunicCore/Utilities/RetryStrategy.swift` - Retry with exponential backoff
+- `Sources/Runic/Views/Menu/ErrorDisplayView.swift` - Error UI components
+
+**Modified:**
+- `Sources/RunicCore/UsageFetcher.swift` - Updated error handling
+- `Sources/RunicCore/Providers/Claude/ClaudeUsageFetcher.swift` - Improved errors
+- `Sources/RunicCore/Providers/MiniMax/MiniMaxUsageFetcher.swift` - Improved errors
+- `Sources/RunicCore/Providers/Groq/GroqUsageFetcher.swift` - Improved errors
+
+### TypeScript (React Native)
+
+**Created:**
+- `runic-cross-platform/src/utils/ErrorCodes.ts` - Error code enum
+- `runic-cross-platform/src/utils/ErrorMessages.ts` - Error message builders
+- `runic-cross-platform/src/utils/retry.ts` - Retry utilities
+- `runic-cross-platform/src/components/ErrorDisplay.tsx` - Error UI components
+
+**Modified:**
+- `runic-cross-platform/src/services/ApiClient.ts` - Enhanced error handling
+- `runic-cross-platform/src/services/SyncService.ts` - Added retry logic
+- `runic-cross-platform/src/utils/index.ts` - Export new utilities
+- `runic-cross-platform/src/components/index.ts` - Export new components
+
+## Summary Statistics
+
+### Error Messages Improved
+
+- **Total error types updated**: 15+
+- **Providers with improved errors**: 5 (Claude, Codex, MiniMax, Groq, Copilot)
+- **Error codes defined**: 30+
+- **New UI components**: 4 (2 Swift, 2 TypeScript)
+
+### Before vs After
+
+| Aspect | Before | After |
+|--------|--------|-------|
+| Error specificity | Generic "failed" messages | Specific reason with context |
+| Actionability | No guidance | 3-5 specific steps |
+| Debugging | No error codes | Unique error codes |
+| Retry capability | Manual only | Automatic with backoff |
+| User experience | Confusing | Clear and helpful |
+
+## Testing Recommendations
+
+1. **Network errors**: Disconnect internet and test sync
+2. **Authentication errors**: Use invalid API tokens
+3. **Rate limits**: Trigger rate limits and verify retry logic
+4. **Parsing errors**: Send malformed API responses
+5. **Retry logic**: Verify exponential backoff timing
+6. **UI display**: Check error display on different screen sizes
+
+## Future Improvements
+
+- [ ] Add telemetry for error tracking
+- [ ] Implement error recovery suggestions based on error patterns
+- [ ] Add localization support for error messages
+- [ ] Create error analytics dashboard
+- [ ] Add automated error reporting to support