npm - @sriinnu/runic - Versions diffs - 1.2.0 → 2.11.1 - Mend

@sriinnu/runic 1.2.0 → 2.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (586) hide show

package/docs/cli-commands/quick_reference.md DELETED Viewed

@@ -1,362 +0,0 @@
-# Runic CLI Commands - Quick Reference
-Quick reference guide for all Runic CLI tracking commands.
-## Command Overview
-| Command | Purpose | Key Options |
-|---------|---------|-------------|
-| `models` | Model usage breakdown | `--provider`, `--days`, `--by-project` |
-| `projects` | Project tracking | `--list`, `--stats`, `--sort-name` |
-| `alerts` | Usage alerts | `--active`, `--history`, `--clear` |
-| `reset` | Reset timings | `--when`, `--all`, `--compact` |
-| `usage-enhanced` | Enhanced usage | `--mode`, `--compare`, `--projected` |
-## Global Options
-Available on all commands:
-- `--json`, `-j` - JSON output
-- `--pretty` - Pretty-print JSON
-- `--no-color` - Disable colors
-- `--help`, `-h` - Show help
-## Command Details
-### runic models
-Show which AI models were used and their token consumption.
-```bash
-# Basic usage
-runic models
-# Filter by provider
-runic models --provider claude
-runic models -p codex
-# Time range
-runic models --days 7
-runic models -d 30
-# Group by project
-runic models --by-project
-# JSON output
-runic models --json --pretty
-```
-**Output:** Table showing model name, provider, tokens, requests, and cost.
----
-### runic projects
-Track usage across different projects and codebases.
-```bash
-# List all projects
-runic projects
-runic projects --list
-runic projects -l
-# Show stats for specific project
-runic projects --stats my-project-id
-runic projects -s my-project-id
-# Sort options
-runic projects --sort-name     # Alphabetical
-runic projects --sort-tokens   # By usage (default)
-# Filter
-runic projects --provider claude --days 7
-```
-**Output:**
-- List mode: Table of all projects
-- Stats mode: Detailed project breakdown
----
-### runic alerts
-Manage usage threshold alerts.
-```bash
-# Show active alerts
-runic alerts
-runic alerts --active
-runic alerts -a
-# View history
-runic alerts --history
-runic alerts -h
-# Clear resolved alerts
-runic alerts --clear
-runic alerts -c
-# Filter by provider
-runic alerts --provider claude
-runic alerts -p codex
-```
-**Output:** List of alerts with severity levels.
-**Alert Levels:**
-- ✗ Critical (>90% used) - Red
-- ⚠ Warning (>75% used) - Yellow
-- ℹ Info (>50% used) - Cyan
----
-### runic reset
-Show when usage limits reset.
-```bash
-# Show all providers
-runic reset
-runic reset --all
-runic reset -a
-# Specific provider
-runic reset --when claude
-runic reset -w codex
-# Compact output
-runic reset --compact
-runic reset -c
-# JSON output
-runic reset --json --pretty
-```
-**Output:** Reset times and countdown for each provider window.
-**Status Indicators:**
-- ✓ Healthy (<50% used) - Green
-- ◐ Moderate (50-75%) - Cyan
-- ⚠ Warning (75-90%) - Yellow
-- ✗ Critical (>90%) - Red
----
-### runic usage-enhanced
-Enhanced usage display with analytics.
-```bash
-# Display modes
-runic usage-enhanced                      # Summary (default)
-runic usage-enhanced --mode summary       # Quick overview
-runic usage-enhanced --mode detailed      # Full breakdown
-runic usage-enhanced --mode breakdown     # Token types
-runic usage-enhanced --mode trending      # Historical trends
-# Options
-runic usage-enhanced --show-cost          # Include costs
-runic usage-enhanced --projected          # Show projections
-runic usage-enhanced --compare            # Compare providers
-# Time range for trending
-runic usage-enhanced --mode trending --days 30
-# Filter by provider
-runic usage-enhanced --provider claude -m detailed
-```
-**Display Modes:**
-- **summary**: Quick overview with progress bars
-- **detailed**: Full window breakdown with reset times
-- **breakdown**: Token type analysis (input/output/cache)
-- **trending**: Historical usage trends
----
-## Common Workflows
-### Daily Usage Check
-```bash
-# Quick summary
-runic usage-enhanced
-# Check for alerts
-runic alerts
-# See when limits reset
-runic reset --compact
-```
-### Weekly Analysis
-```bash
-# Last 7 days by model
-runic models --days 7 --json > models-weekly.json
-# Project breakdown
-runic projects --days 7
-# Trending analysis
-runic usage-enhanced --mode trending --days 7
-```
-### Project Tracking
-```bash
-# List all projects
-runic projects --list
-# Detailed project stats
-runic projects --stats my-project
-# Models used in project
-runic models --days 30 | grep my-project
-```
-### Cost Monitoring
-```bash
-# Enhanced usage with costs
-runic usage-enhanced --mode detailed --show-cost
-# Models by cost
-runic models --json | jq 'sort_by(.cost)'
-# Alert when high usage
-runic alerts --active
-```
-### Export for Analysis
-```bash
-# Export all data to JSON
-runic models --json --pretty > models.json
-runic projects --json --pretty > projects.json
-runic reset --json --pretty > reset-times.json
-# Trending data
-runic usage-enhanced --mode trending --days 30 --json > trends.json
-```
-## Output Formats
-### Text Output (Default)
-Colorized tables with:
-- Headers in cyan
-- High usage in red/yellow
-- Healthy usage in green
-- Progress bars for visualization
-### JSON Output
-Structured data for:
-- Scripting and automation
-- Data processing
-- Integration with other tools
-- Long-term storage
-Use `--json` for compact JSON
-Use `--json --pretty` for formatted JSON
-## Tips and Tricks
-### 1. Pipe to jq for JSON Processing
-```bash
-runic models --json | jq '.[] | select(.provider=="claude")'
-```
-### 2. Watch for Changes
-```bash
-watch -n 60 'runic alerts --active'
-```
-### 3. Create Aliases
-```bash
-alias runic-check='runic usage-enhanced && runic alerts'
-alias runic-weekly='runic models --days 7'
-```
-### 4. Combine with Other Tools
-```bash
-# Export to CSV
-runic models --json | jq -r '.[] | [.model, .tokens, .cost] | @csv'
-# Send alerts via notification
-runic alerts --active | mail -s "Usage Alerts" user@example.com
-```
-### 5. Scripting Examples
-```bash
-#!/bin/bash
-# Check if usage is critical
-ALERTS=$(runic alerts --json | jq 'map(select(.severity >= 3)) | length')
-if [ "$ALERTS" -gt 0 ]; then
-    echo "Critical usage alerts detected!"
-    runic alerts --active
-fi
-```
-## Troubleshooting
-### No data available
-- Check provider credentials
-- Verify usage logs exist
-- Try `--days` with larger value
-### Colors not working
-- Use `--no-color` flag
-- Check terminal supports ANSI codes
-- Set `TERM` environment variable
-### Slow performance
-- Reduce `--days` range
-- Use `--provider` to filter
-- Consider caching results
-### JSON parsing errors
-- Use `--pretty` for debugging
-- Validate with `jq`
-- Check command syntax
-## Environment Variables
-Set these for customization:
-```bash
-export RUNIC_NO_COLOR=1           # Disable colors
-export RUNIC_DEFAULT_DAYS=30      # Default time range
-export RUNIC_DEFAULT_FORMAT=json  # Default output format
-```
-## Exit Codes
-- `0` - Success
-- `1` - Error (invalid arguments, no data, etc.)
-## Getting Help
-```bash
-# Global help
-runic --help
-# Command-specific help
-runic models --help
-runic projects --help
-runic alerts --help
-runic reset --help
-runic usage-enhanced --help
-```
-## Version Information
-```bash
-runic --version
-```
-## Additional Resources
-- Full documentation: See README.md
-- Integration guide: See INTEGRATION_GUIDE.md
-- Source code: Sources/RunicCLI/Commands/
-- Examples: Check command help text
----
-**Last Updated:** 2026-01-31
-**Runic CLI Version:** 1.0.0

package/docs/cli-commands/readme.md DELETED Viewed

@@ -1,361 +0,0 @@
-# Runic CLI Commands
-This directory contains the new tracking commands for the Runic CLI, providing enhanced usage monitoring and analytics capabilities.
-## Commands Overview
-### 1. ModelsCommand.swift
-**Command:** `runic models`
-Shows which AI models were used across different providers, with token consumption and cost breakdown.
-**Features:**
-- Filter by provider
-- Time-based filtering (last N days)
-- JSON output support
-- Colorized table output
-- Group by project option
-**Examples:**
-```bash
-# Show all models used in the last 30 days
-runic models
-# Filter by provider
-runic models --provider claude --days 7
-# Group by project with JSON output
-runic models --by-project --json --pretty
-```
-### 2. ProjectsCommand.swift
-**Command:** `runic projects`
-Track usage across different projects and codebases.
-**Features:**
-- List all projects with summary stats
-- Detailed stats for specific projects
-- Sort by tokens or name
-- Provider filtering
-- JSON output support
-**Examples:**
-```bash
-# List all projects
-runic projects
-# Show detailed stats for a specific project
-runic projects --stats my-project-id
-# Filter by provider and time
-runic projects --provider claude --days 7 --sort-name
-```
-### 3. AlertsCommand.swift
-**Command:** `runic alerts`
-Manage usage threshold alerts to monitor token consumption.
-**Features:**
-- Show active alerts
-- View alert history
-- Clear resolved alerts
-- Provider-specific alerts
-- Severity levels (critical, warning, info)
-**Examples:**
-```bash
-# Show active alerts
-runic alerts
-# View alert history
-runic alerts --history
-# Filter by provider
-runic alerts --provider claude
-# Clear resolved alerts
-runic alerts --clear
-```
-### 4. ResetCommand.swift
-**Command:** `runic reset`
-Display when usage limits reset for different providers.
-**Features:**
-- Show reset times for all providers
-- Provider-specific reset info
-- Compact or detailed output
-- Status indicators
-- Time remaining calculations
-**Examples:**
-```bash
-# Show reset times for all providers
-runic reset
-# Show specific provider reset info
-runic reset --when claude
-# Compact output
-runic reset --compact --no-color
-```
-### 5. EnhancedUsageCommand.swift
-**Command:** `runic usage-enhanced`
-Enhanced version of the usage command with analytics and trending.
-**Features:**
-- Multiple display modes (summary, detailed, breakdown, trending)
-- Historical trending analysis
-- Cost projections
-- Provider comparison
-- Projected usage calculations
-**Examples:**
-```bash
-# Quick summary
-runic usage-enhanced --mode summary
-# Detailed breakdown with cost
-runic usage-enhanced --mode detailed --show-cost
-# Show 30-day trends
-runic usage-enhanced --mode trending --days 30
-# Compare providers
-runic usage-enhanced --compare --json
-```
-## Integration with CLIEntry.swift
-To integrate these commands into the main CLI, update `/Users/srinivaspendela/Sriinnu/AI/Runic/Sources/RunicCLI/CLIEntry.swift`:
-### Step 1: Import the Commands
-Add at the top of CLIEntry.swift:
-```swift
-// Import new command modules
-import struct Commands.ModelsCommand
-import struct Commands.ProjectsCommand
-import struct Commands.AlertsCommand
-import struct Commands.ResetCommand
-import struct Commands.EnhancedUsageCommand
-```
-### Step 2: Register Command Descriptors
-Add the descriptors to the Program initialization (around line 77):
-```swift
-let program = Program(descriptors: [
-    usageDescriptor,
-    costDescriptor,
-    insightsDescriptor,
-    // Add new commands
-    ModelsCommand.descriptor,
-    ProjectsCommand.descriptor,
-    AlertsCommand.descriptor,
-    ResetCommand.descriptor,
-    EnhancedUsageCommand.descriptor,
-])
-```
-### Step 3: Handle Command Invocations
-Add cases to the switch statement (around line 82):
-```swift
-switch invocation.descriptor.name {
-case "usage":
-    await self.runUsage(invocation)
-case "cost":
-    await self.runCost(invocation)
-case "insights":
-    await self.runInsights(invocation)
-case "models":
-    await ModelsCommand.run(invocation)
-case "projects":
-    await ProjectsCommand.run(invocation)
-case "alerts":
-    await AlertsCommand.run(invocation)
-case "reset":
-    await ResetCommand.run(invocation)
-case "usage-enhanced":
-    await EnhancedUsageCommand.run(invocation)
-default:
-    Self.exit(code: 1, message: "Unknown command")
-}
-```
-### Step 4: Update Help Text
-Update the `printHelp` function to include the new commands:
-```swift
-private static func printHelp(for command: String?) {
-    // ... existing help text ...
-    if command == "models" || command == nil {
-        print("models - Show model usage breakdown across providers")
-        print("  Options:")
-        print("    --provider, -p PROVIDER  Filter by provider")
-        print("    --days, -d DAYS          Number of days to analyze (default: 30)")
-        print("    --json, -j               Output in JSON format")
-        print("    --pretty                 Pretty-print JSON output")
-        print("    --no-color               Disable ANSI colors")
-        print("    --by-project             Group results by project")
-    }
-    if command == "projects" || command == nil {
-        print("projects - Track usage across different projects")
-        print("  Options:")
-        print("    --stats, -s PROJECT      Show stats for specific project")
-        print("    --provider, -p PROVIDER  Filter by provider")
-        print("    --days, -d DAYS          Number of days to analyze")
-        print("    --json, -j               Output in JSON format")
-        print("    --pretty                 Pretty-print JSON output")
-        print("    --sort-tokens            Sort by token usage (default)")
-        print("    --sort-name              Sort alphabetically")
-    }
-    if command == "alerts" || command == nil {
-        print("alerts - Manage usage threshold alerts")
-        print("  Options:")
-        print("    --provider, -p PROVIDER  Filter alerts by provider")
-        print("    --active, -a             Show only active alerts")
-        print("    --history, -h            Show alert history")
-        print("    --clear, -c              Clear resolved alerts")
-        print("    --json, -j               Output in JSON format")
-    }
-    if command == "reset" || command == nil {
-        print("reset - Show when usage limits reset")
-        print("  Options:")
-        print("    --when, -w PROVIDER      Show reset for specific provider")
-        print("    --all, -a                Show all providers (default)")
-        print("    --compact, -c            Show compact output")
-        print("    --json, -j               Output in JSON format")
-    }
-    if command == "usage-enhanced" || command == nil {
-        print("usage-enhanced - Enhanced usage display with analytics")
-        print("  Options:")
-        print("    --mode, -m MODE          Display mode: summary|detailed|breakdown|trending")
-        print("    --provider, -p PROVIDER  Filter by provider")
-        print("    --days, -d DAYS          Number of days for trending (default: 7)")
-        print("    --show-cost              Include cost information")
-        print("    --projected              Show projected usage")
-        print("    --compare                Compare usage across providers")
-    }
-}
-```
-## Common Features
-All commands share these common features:
-### Output Formats
-- **Text**: Human-readable, colorized output (default)
-- **JSON**: Machine-readable output with `--json` flag
-- **Pretty JSON**: Formatted JSON with `--pretty` flag
-### Color Support
-- Automatic color detection
-- Disable with `--no-color` flag
-- Color coding based on severity/usage levels:
-  - Green: Healthy/low usage
-  - Yellow: Warning/medium usage
-  - Red: Critical/high usage
-  - Cyan: Headers and highlights
-  - Magenta: Very high usage
-### Error Handling
-- Clear error messages to stderr
-- Non-zero exit codes on failure
-- Helpful error descriptions
-## File Structure
-```
-Sources/RunicCLI/Commands/
-├── README.md                    # This file
-├── ModelsCommand.swift          # Model usage breakdown (287 lines)
-├── ProjectsCommand.swift        # Project tracking (402 lines)
-├── AlertsCommand.swift          # Usage alerts (388 lines)
-├── ResetCommand.swift           # Reset timing info (364 lines)
-└── EnhancedUsageCommand.swift   # Enhanced usage display (479 lines)
-```
-## Implementation Notes
-### Design Patterns
-- **Enum-based commands**: Each command is a public enum with static methods
-- **Configuration structs**: Internal configuration parsing
-- **Helix integration**: Uses CommandSignature and CommandDescriptor
-- **Async/await**: All data loading is asynchronous
-- **Type safety**: Leverages Swift's type system
-### Dependencies
-- **RunicCore**: Core models and data fetchers
-- **Helix**: Command-line argument parsing
-- **Foundation**: Standard Swift library
-### Data Sources
-- **Live API**: Fetches current usage from provider APIs
-- **Usage Logs**: Reads historical data from local logs
-- **Aggregators**: Uses UsageLedgerAggregator for analytics
-## Testing
-### Manual Testing
-```bash
-# Build the CLI
-swift build
-# Test each command
-.build/debug/RunicCLI models
-.build/debug/RunicCLI projects --list
-.build/debug/RunicCLI alerts
-.build/debug/RunicCLI reset --all
-.build/debug/RunicCLI usage-enhanced --mode summary
-# Test JSON output
-.build/debug/RunicCLI models --json --pretty
-```
-### Integration Testing
-Test the commands work with existing CLI infrastructure:
-1. Help text display
-2. Unknown command handling
-3. Error messages
-4. Exit codes
-5. Color output
-## Future Enhancements
-Potential improvements for future versions:
-1. **Persistent Alert Storage**: Store alert history in a database
-2. **Custom Thresholds**: Allow users to set custom alert thresholds
-3. **Export Capabilities**: Export data to CSV, Excel, etc.
-4. **Visualization**: ASCII charts for trending data
-5. **Budget Tracking**: Set and track spending budgets
-6. **Notifications**: Integration with notification systems
-7. **Report Generation**: Automated usage reports
-8. **Multi-language Support**: i18n for help text and messages
-## License
-These commands are part of the Runic project and follow the same license as the main project.
-## Support
-For issues or questions:
-1. Check this README
-2. Review the command help text with `--help`
-3. Check the main Runic documentation
-4. File an issue in the project repository