@sriinnu/runic 2.0.0 → 2.11.2

package/docs/workflows/phase1-cli-testing-report.md

@@ -1,313 +0,0 @@
-# RunicCLI Phase 1 Testing - Final Report
-
-## Executive Summary
-
-Testing of the RunicCLI executable has been completed. The build succeeds, and most Phase 1 enhancements are properly implemented. However, there are 2 critical issues preventing full functionality.
-
-**Build Status**: ✅ PASS (1.29s)
-**Overall Test Status**: 🟡 PARTIAL PASS (6/8 commands working)
-
----
-
-## Detailed Test Results
-
-### ✅ Test 1: Build Command
-```bash
-swift build -c release --product RunicCLI
-```
-**Result**: SUCCESS
-- Build completed in 1.29 seconds
-- Warnings about disabled files (expected, not blocking)
-
-### ✅ Test 2: Usage Command (Text Format)
-```bash
-.build/release/RunicCLI usage
-```
-**Result**: SUCCESS
-- Displays usage for all providers
-- Color-coded progress bars
-- Shows session/weekly usage percentages
-- Provider errors are expected (missing credentials)
-
-### ❌ Test 3: Usage Command (JSON Format)
-```bash
-.build/release/RunicCLI usage --format=json
-```
-**Result**: FAILURE
-**Error**: `Helix.HelixError error 3`
-
-**Root Cause**: The `runUsage` function in CLIEntry.swift (lines 102-170) doesn't properly implement JSON encoding. It tries to parse text output as JSON instead of encoding structured data.
-
-**Code Location**: `/Users/srinivaspendela/Sriinnu/AI/Runic/Sources/RunicCLI/CLIEntry.swift:158-169`
-
-**Fix Required**: Replace text concatenation with proper Encodable struct and JSONEncoder
-
-### ⚠️ Test 4: Insights - Projects View with Budget
-```bash
-.build/release/RunicCLI insights --view projects --budget --json
-```
-**Result**: COMMAND WORKS (No data available)
-- Command parsing: ✅ PASS
-- Budget flag recognition: ✅ PASS  
-- JSON flag recognition: ✅ PASS
-- Output: "No insights available." (expected when no log data exists)
-
-**Note**: This is correct behavior. The command works, but requires historical usage log data to display results.
-
-### ⚠️ Test 5: Insights - Hourly Granularity
-```bash
-.build/release/RunicCLI insights --view daily --granularity hourly --json
-```
-**Result**: COMMAND WORKS (No data available)
-- Command parsing: ✅ PASS
-- Granularity flag: ✅ PASS
-- Hourly aggregation logic: ✅ IMPLEMENTED (lines 272-274 in CLIEntry.swift)
-- Output: "No insights available." (expected)
-
-**Code**: 
-```swift
-if let granularity = granularityArg, granularity == "hourly" {
-    let summaries = UsageLedgerAggregator.hourlySummaries(entries: entries, timeZone: timeZone)
-    Self.renderInsightsOutput(summaries, isJson: isJson, isPretty: isPretty)
-}
-```
-
-### ⚠️ Test 6: Insights - Comparative View
-```bash
-.build/release/RunicCLI insights --view comparative --json
-```
-**Result**: COMMAND WORKS (No data available)
-- Comparative view: ✅ IMPLEMENTED (lines 296-298 in CLIEntry.swift)
-- Model cost comparison: ✅ IMPLEMENTED (lines 406-437)
-- Cost-per-token ranking: ✅ IMPLEMENTED
-- Output: "No insights available." (expected)
-
-**Implementation**:
-```swift
-case "comparative":
-    let comparisons = Self.modelCostComparison(entries: entries)
-    Self.renderInsightsOutput(comparisons, isJson: isJson, isPretty: isPretty)
-```
-
-### ⚠️ Test 7: Insights - Efficiency Metrics
-```bash
-.build/release/RunicCLI insights --view efficiency --json
-```
-**Result**: COMMAND WORKS (No data available)
-- Efficiency view: ✅ IMPLEMENTED (lines 299-301 in CLIEntry.swift)
-- Efficiency metrics calculation: ✅ IMPLEMENTED (lines 441-469)
-- Metrics include: tokens/request, cost/request, cache hit rate
-- Output: "No insights available." (expected)
-
-**Implementation**:
-```swift
-case "efficiency":
-    let efficiencies = Self.modelEfficiencyMetrics(entries: entries)
-    Self.renderInsightsOutput(efficiencies, isJson: isJson, isPretty: isPretty)
-```
-
-**Metrics Calculated**:
-- Tokens per request
-- Cost per request
-- Cache hit rate
-- Total cost
-
-### ❌ Test 8: Alerts Command
-```bash
-.build/release/RunicCLI alerts list --format=json
-```
-**Result**: COMMAND NOT AVAILABLE
-
-**Root Cause**: 
-1. AlertsCommand.swift is disabled (renamed to .disabled extension)
-2. Command is not registered in CLIEntry.swift's Program descriptor (line 81)
-
-**Files**:
-- Implementation exists: `/Users/srinivaspendela/Sriinnu/AI/Runic/Sources/RunicCLI/Commands/AlertsCommand.swift.disabled`
-- Full implementation complete (513 lines)
-- Supports: list, add, test, remove, enable, disable subcommands
-
----
-
-## Feature Implementation Status
-
-### ✅ Fully Implemented Features
-
-1. **Insights Command Framework**
-   - Daily view with hourly granularity support
-   - Session view
-   - Blocks view
-   - Models view  
-   - Projects view
-   - Comparative view (NEW in Phase 1)
-   - Efficiency view (NEW in Phase 1)
-
-2. **Budget Tracking** (NEW in Phase 1)
-   - --budget flag support
-   - Project budget enrichment
-   - Budget status (ok, warning, critical)
-   - Month-to-date tracking
-
-3. **Comparative Analysis** (NEW in Phase 1)
-   - Model cost-per-token comparison
-   - Automatic ranking
-   - Total cost and token tracking
-   - Request count metrics
-
-4. **Efficiency Metrics** (NEW in Phase 1)
-   - Tokens per request
-   - Cost per request
-   - Cache hit rate calculation
-   - Per-model efficiency tracking
-
-5. **JSON Output**
-   - Works for all insights views
-   - Pretty-print support
-   - ISO8601 date formatting
-   - Proper encoding of all data types
-
-6. **Git Integration**
-   - --with-commits flag
-   - Links usage entries to git commits
-   - 5-minute window matching
-   - Commit SHA and message display
-
-### ❌ Broken Features
-
-1. **Usage Command JSON Output**
-   - Text output works perfectly
-   - JSON output throws Helix error
-   - Root cause: improper JSON encoding implementation
-
-2. **Alerts Command**
-   - Fully implemented but disabled
-   - Not registered in CLI entry point
-   - All subcommands coded and ready
-
-### ⚠️ Requires Test Data
-
-All insights views work correctly but require historical log data:
-- Daily/hourly summaries
-- Session summaries
-- Block summaries
-- Model summaries
-- Project summaries
-- Comparative analysis
-- Efficiency metrics
-
----
-
-## Code Quality Assessment
-
-### ✅ Well-Implemented
-
-1. **Modular Design**: Clean separation between command parsing and execution
-2. **Error Handling**: Proper error messages for missing data
-3. **Type Safety**: Strong typing with Encodable protocols
-4. **Code Organization**: Clear structure with MARK comments
-5. **Configurability**: Extensive flag and option support
-
-### ⚠️ Areas for Improvement
-
-1. **Usage JSON Output**: Needs proper JSONEncoder implementation
-2. **Disabled Files**: Should be removed or properly excluded
-3. **Test Coverage**: No automated tests found
-4. **Documentation**: In-code documentation is good, but external docs missing
-
----
-
-## Critical Issues
-
-### Issue #1: Usage Command JSON Output
-**Severity**: HIGH
-**Impact**: Users cannot export usage data as JSON
-**File**: `Sources/RunicCLI/CLIEntry.swift:102-170`
-
-**Current Implementation**:
-```swift
-// Lines 158-169: Tries to parse text as JSON (WRONG)
-if isPretty && isJson {
-    if let data = output.data(using: .utf8),
-       let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
-       // ... this fails because output is text, not JSON
-```
-
-**Required Fix**:
-- Create Encodable struct for usage data
-- Use JSONEncoder to encode the struct
-- Remove text-to-JSON conversion attempt
-
-### Issue #2: Alerts Command Disabled
-**Severity**: MEDIUM
-**Impact**: Alert management functionality unavailable
-**Files**: 
-- `Sources/RunicCLI/Commands/AlertsCommand.swift.disabled`
-- `Sources/RunicCLI/CLIEntry.swift`
-
-**Required Fix**:
-1. Rename `AlertsCommand.swift.disabled` to `AlertsCommand.swift`
-2. Import AlertsCommand in CLIEntry.swift
-3. Add alerts descriptor to Program (line 81)
-4. Add case for "alerts" in switch statement (line 85)
-
----
-
-## Recommendations
-
-### Immediate (Before Production)
-1. ✅ Fix usage command JSON output
-2. ✅ Enable and register alerts command
-3. ✅ Test all commands with real usage data
-
-### Short-term
-1. Add automated integration tests
-2. Create user documentation
-3. Add JSON schema validation
-4. Handle empty data gracefully (return [] instead of error)
-
-### Long-term
-1. Add comprehensive error logging
-2. Performance optimization for large datasets
-3. Add data export formats (CSV, etc.)
-4. Implement caching for expensive operations
-
----
-
-## Test Environment
-
-- **Working Directory**: `/Users/srinivaspendela/Sriinnu/AI/Runic`
-- **Build Tool**: Swift Package Manager
-- **Build Configuration**: Release
-- **Platform**: macOS (Darwin 24.6.0)
-- **Build Time**: 1.29 seconds
-
----
-
-## Conclusion
-
-**Phase 1 CLI Enhancements Implementation: 75% Complete**
-
-**Working (6/8)**:
-- ✅ Insights command with all views
-- ✅ Budget tracking integration  
-- ✅ Hourly granularity support
-- ✅ Comparative analysis
-- ✅ Efficiency metrics
-- ✅ Git commit linking
-
-**Broken (2/8)**:
-- ❌ Usage command JSON output
-- ❌ Alerts command (disabled)
-
-**Key Achievements**:
-- All new Phase 1 features are properly implemented in the insights command
-- JSON encoding works correctly for all insights views
-- Command parsing and flag handling works perfectly
-- Code structure is clean and maintainable
-
-**Blocking Issues**:
-- Usage command cannot export JSON (Helix error)
-- Alerts functionality is completely unavailable
-
-**Recommendation**: Fix the two critical issues before considering Phase 1 complete. The core functionality is solid, but these bugs prevent full usability.
-

package/docs/workflows/quick_reference.md

@@ -1,228 +0,0 @@
-# Runic Quick Reference
-
-**For developers who want to get productive fast.**
-
----
-
-## 🚀 Quick Start
-
-```bash
-# Clone and build
-git clone <repo-url>
-cd Runic
-RUNIC_SIGNING=adhoc ./Scripts/compile_and_run.sh
-
-# Run tests
-swift test
-
-# Package app
-./Scripts/package_app.sh
-```
-
----
-
-## 📁 Where Is Everything?
-
-| What | Where |
-|------|-------|
-| **State management** | `Core/Stores/UsageStore.swift` |
-| **Menubar icon** | `Core/Rendering/IconRenderer.swift` |
-| **Menu UI** | `Views/Menu/MenuCardView.swift` |
-| **Settings UI** | `Views/Preferences/Preferences*Pane.swift` |
-| **Animations** | `Controllers/StatusItemController+Animation.swift` |
-| **Performance config** | `Utilities/PerformanceConstants.swift` |
-| **Provider code** | `Providers/{ProviderName}/` |
-
----
-
-## 🔧 Common Tasks
-
-### Adding a New Provider
-
-1. Create folder: `Providers/ProviderName/`
-2. Add files:
-   - `ProviderNameProviderImplementation.swift`
-   - `ProviderNameLoginFlow.swift`
-3. Add icon: `Resources/ProviderIcon-providername.svg`
-4. Register: `RunicCore/Providers/Providers.swift`
-
-### Adjusting UI Spacing
-
-```swift
-// Menu cards
-MenuCardMetrics.sectionSpacing = 8
-MenuCardMetrics.lineSpacing = 4
-
-// Preferences
-PreferencesLayoutMetrics.paneHorizontal = 35
-PreferencesLayoutMetrics.paneVertical = 25
-```
-
-### Tuning Performance
-
-Edit `Utilities/PerformanceConstants.swift`:
-```swift
-static let menubarFPS = 60              // Animation frame rate
-static let iconCacheSize = 64           // Icon cache size
-static let staleDuration = Duration.seconds(300)  // 5 min stale
-```
-
-### Finding Code
-
-```bash
-# Search for function/class
-grep -r "functionName" Sources/
-
-# Find files by name
-find Sources/ -name "*Store*"
-
-# Search with line numbers
-grep -rn "MARK:" Sources/Runic/
-```
-
----
-
-## 🎨 UI Layout
-
-### Menubar Icon
-- **Size:** 18×18pt (36×36px @2x)
-- **Renderer:** `IconRenderer.swift`
-- **Shows:** Usage bars, stale indicator, provider status
-
-### Menu Cards
-- **Width:** Auto (SwiftUI)
-- **Padding:** 12pt horizontal
-- **Spacing:** 8pt between sections, 4pt between lines
-
-### Preferences Window
-- **Size:** 500×400pt
-- **Tabs:** About, General, Providers, Advanced, Help, Debug
-
----
-
-## ⚡ Performance Guidelines
-
-### Do's ✅
-- Use O(1) lookups (Dictionary, Set)
-- Cache expensive operations
-- Stop animations when not needed
-- Use cookies before API calls
-
-### Don'ts ❌
-- Never block main thread
-- Avoid O(n) operations on large datasets
-- Don't leak tokens (always cache first)
-- No magic numbers (use constants)
-
----
-
-## 🐛 Debugging
-
-### Check Logs
-```bash
-# App logs
-log stream --predicate 'process == "Runic"' --level debug
-
-# Build errors
-swift build 2>&1 | grep error
-```
-
-### Common Issues
-
-| Problem | Solution |
-|---------|----------|
-| **Stale binary** | `pkill -x Runic && ./Scripts/compile_and_run.sh` |
-| **Build fails** | `rm -rf .build && swift build` |
-| **Icon not updating** | Clear cache in Debug preferences |
-| **Menu not showing** | Check `StatusItemController+Menu.swift` |
-
----
-
-## 📊 Code Statistics
-
-| Metric | Value |
-|--------|-------|
-| **Total files** | ~119 |
-| **Total lines** | ~30,000 |
-| **Avg file size** | ~250 lines |
-| **Largest file** | UsageStore.swift (2089 lines) |
-| **Providers** | 11 (Claude, Codex, Cursor, etc.) |
-
----
-
-## 🔗 Key Files Quick Links
-
-### Core (Business Logic)
-- [UsageStore.swift](Sources/Runic/Core/Stores/UsageStore.swift) - Main state (2089 lines)
-- [IconRenderer.swift](Sources/Runic/Core/Rendering/IconRenderer.swift) - Icon generation (882 lines)
-- [PerformanceConstants.swift](Sources/Runic/Utilities/PerformanceConstants.swift) - Config (50 lines)
-
-### UI (SwiftUI)
-- [MenuCardView.swift](Sources/Runic/Views/Menu/MenuCardView.swift) - Menu UI (1093 lines)
-- [PreferencesView.swift](Sources/Runic/Views/Preferences/PreferencesView.swift) - Settings (200 lines)
-
-### Controllers (AppKit)
-- [StatusItemController.swift](Sources/Runic/Controllers/StatusItemController.swift) - Menubar (318 lines)
-- [StatusItemController+Menu.swift](Sources/Runic/Controllers/StatusItemController+Menu.swift) - Menu builder (1878 lines)
-- [StatusItemController+Animation.swift](Sources/Runic/Controllers/StatusItemController+Animation.swift) - Animations (469 lines)
-
----
-
-## 🎯 Terminology
-
-| Term | Meaning |
-|------|---------|
-| **Ping** | Fetch latest usage data from provider |
-| **Snapshot** | Point-in-time usage data |
-| **Stale** | Data older than 5 minutes |
-| **Provider** | AI service (Claude, Codex, etc.) |
-| **Status item** | macOS menubar icon |
-| **Template image** | Image that adapts to menubar theme |
-
----
-
-## 🔑 Keyboard Shortcuts
-
-| Shortcut | Action |
-|----------|--------|
-| `⌘⇧R` | Open Runic menu |
-| `⌘,` | Preferences |
-| `⌘Q` | Quit |
-
----
-
-## 📚 Documentation Files
-
-| File | Purpose |
-|------|---------|
-| **README.md** | Project overview |
-| **AGENTS.md** | AI agent guidelines |
-| **FOLDER_STRUCTURE.md** | Code organization guide |
-| **RECENT_IMPROVEMENTS.md** | Latest changes |
-| **QUICK_REFERENCE.md** | This file |
-| **PLAN.md** | Development roadmap |
-| **CHANGELOG.md** | Version history |
-
----
-
-## 💡 Pro Tips
-
-1. **Use folder structure** - Files are organized logically (see FOLDER_STRUCTURE.md)
-2. **Read file headers** - Key files have comprehensive documentation
-3. **Check PerformanceConstants** - All tuning knobs in one place
-4. **Follow AGENTS.md** - Guidelines for consistent development
-5. **Always rebuild** - Use `compile_and_run.sh` after changes
-
----
-
-## 🆘 Getting Help
-
-1. **Read docs** - Start with README.md, then FOLDER_STRUCTURE.md
-2. **Check AGENTS.md** - Development guidelines and patterns
-3. **Search code** - Use grep/find to locate examples
-4. **Check git log** - See how features were implemented
-5. **Ask maintainers** - Open an issue or discussion
-
----
-
-**Updated:** 2026-01-16 | **Version:** v0.16.1 | **Build:** 49

package/docs/workflows/readme.md

@@ -1,59 +0,0 @@
-# Runic Documentation & Workflows
-
-This folder contains comprehensive documentation and workflow guides for the Runic project.
-
-## 📚 Documentation Files
-
-### Quick References
-- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Fast lookup guide for developers
-  - Common tasks (adding providers, tuning performance)
-  - Where to find everything
-  - Debugging tips and pro tips
-
-### Architecture & Structure
-- **[FOLDER_STRUCTURE.md](FOLDER_STRUCTURE.md)** - Complete code organization guide
-  - Detailed folder structure with descriptions
-  - Design principles and naming conventions
-  - Code comment guidelines
-  - File reference tables
-
-### Workflows & Best Practices
-- **[PERFORMANCE_OPTIMIZATIONS.md](PERFORMANCE_OPTIMIZATIONS.md)** - Performance tuning guide
-  - Zero token leakage policy
-  - Animation performance (60 FPS)
-  - Caching strategies
-  - Single ping approach
-
-### Change History
-- **[RECENT_IMPROVEMENTS.md](RECENT_IMPROVEMENTS.md)** - Latest updates and changes
-  - Recent feature additions
-  - UI/UX refinements
-  - Code organization improvements
-  - Build history
-
----
-
-## 🎯 Getting Started
-
-**New to Runic?** Start here:
-1. Read [QUICK_REFERENCE.md](QUICK_REFERENCE.md) for common tasks
-2. Check [FOLDER_STRUCTURE.md](FOLDER_STRUCTURE.md) to understand the codebase
-3. Review [PERFORMANCE_OPTIMIZATIONS.md](PERFORMANCE_OPTIMIZATIONS.md) for best practices
-
-**Working on a feature?**
-- Use [FOLDER_STRUCTURE.md](FOLDER_STRUCTURE.md) to find relevant files
-- Follow guidelines in [PERFORMANCE_OPTIMIZATIONS.md](PERFORMANCE_OPTIMIZATIONS.md)
-- Check [RECENT_IMPROVEMENTS.md](RECENT_IMPROVEMENTS.md) for latest patterns
-
----
-
-## 📖 Additional Documentation
-
-For more documentation, see the main `docs/` folder:
-- **API documentation** - Provider-specific API docs
-- **Architecture guides** - System design documents
-- **Release guides** - Build and release processes
-
----
-
-**Last Updated:** 2026-01-17