@sriinnu/runic 1.0.0

package/docs/antigravity.md

@@ -0,0 +1,75 @@
+---
+summary: "Antigravity provider notes: local LSP probing, port discovery, quota parsing, and UI mapping."
+read_when:
+  - Adding or modifying the Antigravity provider
+  - Debugging Antigravity port detection or quota parsing
+  - Adjusting Antigravity menu labels or model mapping
+---
+
+# Antigravity provider
+
+Antigravity is a local-only provider. We talk directly to the Antigravity language server running on the same machine.
+
+## Data sources + fallback order
+
+1) **Process detection**
+   - Command: `ps -ax -o pid=,command=`.
+   - Match process name: `language_server_macos` plus Antigravity markers:
+     - `--app_data_dir antigravity` OR path contains `/antigravity/`.
+   - Extract CLI flags:
+     - `--csrf_token <token>` (required).
+     - `--extension_server_port <port>` (HTTP fallback).
+
+2) **Port discovery**
+   - Command: `lsof -nP -iTCP -sTCP:LISTEN -p <pid>`.
+   - All listening ports are probed.
+
+3) **Connect port probe (HTTPS)**
+   - `POST https://127.0.0.1:<port>/exa.language_server_pb.LanguageServerService/GetUnleashData`
+   - Headers:
+     - `X-Codeium-Csrf-Token: <token>`
+     - `Connect-Protocol-Version: 1`
+   - First 200 OK response selects the connect port.
+
+4) **Quota fetch**
+   - Primary:
+     - `POST https://127.0.0.1:<connectPort>/exa.language_server_pb.LanguageServerService/GetUserStatus`
+   - Fallback:
+     - `POST https://127.0.0.1:<connectPort>/exa.language_server_pb.LanguageServerService/GetCommandModelConfigs`
+   - If HTTPS fails, retry over HTTP on `extension_server_port`.
+
+## Request body (summary)
+- Minimal metadata payload:
+  - `ideName: antigravity`
+  - `extensionName: antigravity`
+  - `locale: en`
+  - `ideVersion: unknown`
+
+## Parsing and model mapping
+- Source fields:
+  - `userStatus.cascadeModelConfigData.clientModelConfigs[].quotaInfo.remainingFraction`
+  - `userStatus.cascadeModelConfigData.clientModelConfigs[].quotaInfo.resetTime`
+- Mapping priority:
+  1) Claude (label contains `claude` but not `thinking`)
+  2) Gemini Pro Low (label contains `pro` + `low`)
+  3) Gemini Flash (label contains `gemini` + `flash`)
+  4) Fallback: lowest remaining percent
+- `resetTime` parsing:
+  - ISO-8601 preferred; numeric epoch seconds as fallback.
+- Identity:
+  - `accountEmail` and `planName` only from `GetUserStatus`.
+
+## UI mapping
+- Provider metadata:
+  - Display: `Antigravity`
+  - Labels: `Claude` (primary), `Gemini Pro` (secondary), `Gemini Flash` (tertiary)
+- Status badge: Google Workspace incidents for the Gemini product.
+
+## Constraints
+- Internal protocol; fields may change.
+- Requires `lsof` for port detection.
+- Local HTTPS uses a self-signed cert; the probe allows insecure TLS.
+
+## Key files
+- `Sources/RunicCore/Providers/Antigravity/AntigravityStatusProbe.swift`
+- `Sources/Runic/Providers/Antigravity/AntigravityProviderImplementation.swift`

package/docs/architecture.md

@@ -0,0 +1,32 @@
+---
+summary: "Architecture overview: modules, entry points, and data flow."
+read_when:
+  - Reviewing architecture before feature work
+  - Refactoring app structure, app lifecycle, or module boundaries
+---
+
+# Architecture overview
+
+## Modules
+- `Sources/RunicCore`: fetch + parse (Codex RPC, PTY runner, Claude probes, OpenAI web scraping, status polling).
+- `Sources/Runic`: state + UI (UsageStore, SettingsStore, StatusItemController, menus, icon rendering).
+- `Sources/RunicWidget`: WidgetKit extension wired to the shared snapshot.
+- `Sources/RunicCLI`: bundled CLI for `runic` usage/status output.
+- `Sources/RunicMacros`: SwiftSyntax macros for provider registration.
+- `Sources/RunicMacroSupport`: shared macro support used by app/core/CLI targets.
+- `Sources/RunicClaudeWatchdog`: helper process for stable Claude CLI PTY sessions.
+- `Sources/RunicClaudeWebProbe`: CLI helper to diagnose Claude web fetches.
+
+## Entry points
+- `RunicApp`: SwiftUI keepalive + Settings scene.
+- `AppDelegate`: wires status controller, Sparkle updater, notifications.
+
+## Data flow
+- Background refresh → `UsageFetcher`/provider probes → `UsageStore` → menu/icon/widgets.
+- Settings toggles feed `SettingsStore` → `UsageStore` refresh cadence + feature flags.
+
+## Concurrency & platform
+- Swift 6 strict concurrency enabled; prefer Sendable state and explicit MainActor hops.
+- macOS 14+ targeting; avoid deprecated APIs when refactoring.
+
+See also: `docs/providers.md`, `docs/refresh-loop.md`, `docs/ui.md`.

package/docs/claude.md

@@ -0,0 +1,93 @@
+---
+summary: "Claude provider data sources: OAuth API, web API (cookies), CLI PTY, and local cost usage."
+read_when:
+  - Debugging Claude usage/status parsing
+  - Updating Claude OAuth/web endpoints or cookie import
+  - Adjusting Claude CLI PTY automation
+  - Reviewing local cost usage scanning
+---
+
+# Claude provider
+
+Claude supports three usage data paths plus local cost usage. Source selection is automatic unless debug override is set.
+
+## Data sources + selection order
+
+### Default selection (debug menu disabled)
+1) OAuth API (if Claude CLI credentials include `user:profile` scope).
+2) Web API (browser cookies, `sessionKey`), if OAuth missing.
+3) CLI PTY (`claude`), if no OAuth and no web session.
+
+### Debug selection (debug menu enabled)
+- The Debug pane can force OAuth / Web / CLI.
+- Web extras are internal-only (not exposed in the Providers pane).
+
+## OAuth API (preferred)
+- Credentials:
+  - Keychain service: `Claude Code-credentials` (primary on macOS).
+  - File fallback: `~/.claude/.credentials.json`.
+- Requires `user:profile` scope (CLI tokens with only `user:inference` cannot call usage).
+- Endpoint:
+  - `GET https://api.anthropic.com/api/oauth/usage`
+- Headers:
+  - `Authorization: Bearer <access_token>`
+  - `anthropic-beta: oauth-2025-04-20`
+- Mapping:
+  - `five_hour` → session window.
+  - `seven_day` → weekly window.
+  - `seven_day_sonnet` / `seven_day_opus` → model-specific weekly window.
+  - `extra_usage` → Extra usage cost (monthly spend/limit).
+- Plan inference: `rate_limit_tier` from credentials maps to Max/Pro/Team/Enterprise.
+
+## Web API (cookies)
+- Cookie source order:
+  1) Safari: `~/Library/Cookies/Cookies.binarycookies`
+  2) Chrome/Chromium forks: `~/Library/Application Support/Google/Chrome/*/Cookies`
+  3) Firefox: `~/Library/Application Support/Firefox/Profiles/*/cookies.sqlite`
+- Domain: `claude.ai`.
+- Cookie name required:
+  - `sessionKey` (value prefix `sk-ant-...`).
+- API calls (all include `Cookie: sessionKey=<value>`):
+  - `GET https://claude.ai/api/organizations` → org UUID.
+  - `GET https://claude.ai/api/organizations/{orgId}/usage` → session/weekly/opus.
+  - `GET https://claude.ai/api/organizations/{orgId}/overage_spend_limit` → Extra usage spend/limit.
+  - `GET https://claude.ai/api/account` → email + plan hints.
+- Outputs:
+  - Session + weekly + model-specific percent used.
+  - Extra usage spend/limit (if enabled).
+  - Account email + inferred plan.
+
+## CLI PTY (fallback)
+- Runs `claude` in a persistent PTY session (`ClaudeCLISession`).
+- Command flow:
+  1) Start CLI with `--allowed-tools ""` (no tools).
+  2) Auto-respond to first-run prompts (trust files, workspace, telemetry).
+  3) Send `/usage`, wait for rendered panel; send Enter retries if needed.
+  4) Optionally send `/status` to extract identity fields.
+- Parsing (`ClaudeStatusProbe`):
+  - Strips ANSI, locates "Current session" + "Current week" headers.
+  - Extracts percent left/used and reset text near those headers.
+  - Parses `Account:` and `Org:` lines when present.
+  - Surfaces CLI errors (e.g. token expired) directly.
+
+## Cost usage (local log scan)
+- Source roots:
+  - `$CLAUDE_CONFIG_DIR` (comma-separated), each root uses `<root>/projects`.
+  - Fallback roots:
+    - `~/.config/claude/projects`
+    - `~/.claude/projects`
+- Files: `**/*.jsonl` under the project roots.
+- Parsing:
+  - Lines with `type: "assistant"` and `message.usage`.
+  - Uses per-model token counts (input, cache read/create, output).
+  - Deduplicates streaming chunks by `message.id + requestId` (usage is cumulative per chunk).
+- Cache:
+  - `~/Library/Caches/Runic/cost-usage/claude-v1.json`
+
+## Key files
+- OAuth: `Sources/RunicCore/Providers/Claude/ClaudeOAuth/*`
+- Web API: `Sources/RunicCore/Providers/Claude/ClaudeWeb/ClaudeWebAPIFetcher.swift`
+- CLI PTY: `Sources/RunicCore/Providers/Claude/ClaudeStatusProbe.swift`,
+  `Sources/RunicCore/Providers/Claude/ClaudeCLISession.swift`
+- Cost usage: `Sources/RunicCore/CostUsageFetcher.swift`,
+  `Sources/RunicCore/Vendored/CostUsage/*`

package/docs/cli-commands/integration_guide.md

@@ -0,0 +1,371 @@
+# Integration Guide for New Runic CLI Commands
+
+This guide provides step-by-step instructions for integrating the new tracking commands into the Runic CLI.
+
+## Prerequisites
+
+Before integrating, ensure you have:
+- All command files in `/Sources/RunicCLI/Commands/`
+- Existing CLI infrastructure in `/Sources/RunicCLI/CLIEntry.swift`
+- Helix framework dependency configured
+- RunicCore module available
+
+## Integration Steps
+
+### 1. Update CLIEntry.swift
+
+Open `/Sources/RunicCLI/CLIEntry.swift` and make the following changes:
+
+#### A. Add Command Signatures
+
+After the existing `insightsSignature` definition (around line 57), add:
+
+```swift
+// Models command signature
+let modelsSignature = CommandSignature(
+    options: [
+        OptionDefinition(label: "provider", names: [.long("provider"), .short("p")],
+                        help: "Filter by provider (claude, codex, gemini, etc.)"),
+        OptionDefinition(label: "days", names: [.long("days"), .short("d")],
+                        help: "Number of days to analyze (default: 30)"),
+        OptionDefinition(label: "format", names: [.long("format")],
+                        help: "Output format: text | json"),
+    ],
+    flags: [
+        FlagDefinition(label: "json", names: [.long("json"), .short("j")],
+                      help: "Output in JSON format"),
+        FlagDefinition(label: "pretty", names: [.long("pretty")],
+                      help: "Pretty-print JSON output"),
+        FlagDefinition(label: "noColor", names: [.long("no-color")],
+                      help: "Disable ANSI color codes"),
+        FlagDefinition(label: "groupByProject", names: [.long("by-project")],
+                      help: "Group results by project"),
+    ])
+
+// Projects command signature
+let projectsSignature = CommandSignature(
+    options: [
+        OptionDefinition(label: "stats", names: [.long("stats"), .short("s")],
+                        help: "Show detailed stats for a specific project ID"),
+        OptionDefinition(label: "provider", names: [.long("provider"), .short("p")],
+                        help: "Filter by provider"),
+        OptionDefinition(label: "days", names: [.long("days"), .short("d")],
+                        help: "Number of days to analyze (default: 30)"),
+        OptionDefinition(label: "format", names: [.long("format")],
+                        help: "Output format: text | json"),
+    ],
+    flags: [
+        FlagDefinition(label: "list", names: [.long("list"), .short("l")],
+                      help: "List all projects (default behavior)"),
+        FlagDefinition(label: "json", names: [.long("json"), .short("j")],
+                      help: "Output in JSON format"),
+        FlagDefinition(label: "pretty", names: [.long("pretty")],
+                      help: "Pretty-print JSON output"),
+        FlagDefinition(label: "noColor", names: [.long("no-color")],
+                      help: "Disable ANSI color codes"),
+        FlagDefinition(label: "sortByName", names: [.long("sort-name")],
+                      help: "Sort projects alphabetically by name"),
+    ])
+
+// Alerts command signature
+let alertsSignature = CommandSignature(
+    options: [
+        OptionDefinition(label: "provider", names: [.long("provider"), .short("p")],
+                        help: "Filter alerts by provider"),
+        OptionDefinition(label: "format", names: [.long("format")],
+                        help: "Output format: text | json"),
+    ],
+    flags: [
+        FlagDefinition(label: "active", names: [.long("active"), .short("a")],
+                      help: "Show only active alerts (default)"),
+        FlagDefinition(label: "history", names: [.long("history"), .short("h")],
+                      help: "Show alert history"),
+        FlagDefinition(label: "clear", names: [.long("clear"), .short("c")],
+                      help: "Clear resolved alerts from history"),
+        FlagDefinition(label: "json", names: [.long("json"), .short("j")],
+                      help: "Output in JSON format"),
+        FlagDefinition(label: "pretty", names: [.long("pretty")],
+                      help: "Pretty-print JSON output"),
+        FlagDefinition(label: "noColor", names: [.long("no-color")],
+                      help: "Disable ANSI color codes"),
+    ])
+
+// Reset command signature
+let resetSignature = CommandSignature(
+    options: [
+        OptionDefinition(label: "when", names: [.long("when"), .short("w")],
+                        help: "Show reset timing for specific provider"),
+        OptionDefinition(label: "format", names: [.long("format")],
+                        help: "Output format: text | json"),
+    ],
+    flags: [
+        FlagDefinition(label: "all", names: [.long("all"), .short("a")],
+                      help: "Show all providers (default)"),
+        FlagDefinition(label: "json", names: [.long("json"), .short("j")],
+                      help: "Output in JSON format"),
+        FlagDefinition(label: "pretty", names: [.long("pretty")],
+                      help: "Pretty-print JSON output"),
+        FlagDefinition(label: "noColor", names: [.long("no-color")],
+                      help: "Disable ANSI color codes"),
+        FlagDefinition(label: "compact", names: [.long("compact"), .short("c")],
+                      help: "Show compact output"),
+    ])
+
+// Enhanced usage command signature
+let usageEnhancedSignature = CommandSignature(
+    options: [
+        OptionDefinition(label: "provider", names: [.long("provider"), .short("p")],
+                        help: "Filter by provider"),
+        OptionDefinition(label: "mode", names: [.long("mode"), .short("m")],
+                        help: "Display mode: summary | detailed | breakdown | trending"),
+        OptionDefinition(label: "days", names: [.long("days"), .short("d")],
+                        help: "Number of days for trending (default: 7)"),
+        OptionDefinition(label: "format", names: [.long("format")],
+                        help: "Output format: text | json"),
+    ],
+    flags: [
+        FlagDefinition(label: "json", names: [.long("json"), .short("j")],
+                      help: "Output in JSON format"),
+        FlagDefinition(label: "pretty", names: [.long("pretty")],
+                      help: "Pretty-print JSON output"),
+        FlagDefinition(label: "noColor", names: [.long("no-color")],
+                      help: "Disable ANSI color codes"),
+        FlagDefinition(label: "showCost", names: [.long("show-cost")],
+                      help: "Include cost information"),
+        FlagDefinition(label: "showProjected", names: [.long("projected")],
+                      help: "Show projected usage at current rate"),
+        FlagDefinition(label: "compare", names: [.long("compare")],
+                      help: "Compare usage across providers"),
+    ])
+```
+
+#### B. Create Command Descriptors
+
+After the descriptors (around line 75), add:
+
+```swift
+let modelsDescriptor = CommandDescriptor(
+    name: "models",
+    abstract: "Show model usage breakdown across providers",
+    discussion: nil,
+    signature: modelsSignature)
+
+let projectsDescriptor = CommandDescriptor(
+    name: "projects",
+    abstract: "Track usage across different projects",
+    discussion: nil,
+    signature: projectsSignature)
+
+let alertsDescriptor = CommandDescriptor(
+    name: "alerts",
+    abstract: "Manage usage threshold alerts",
+    discussion: nil,
+    signature: alertsSignature)
+
+let resetDescriptor = CommandDescriptor(
+    name: "reset",
+    abstract: "Show when usage limits reset",
+    discussion: nil,
+    signature: resetSignature)
+
+let usageEnhancedDescriptor = CommandDescriptor(
+    name: "usage-enhanced",
+    abstract: "Enhanced usage display with analytics",
+    discussion: nil,
+    signature: usageEnhancedSignature)
+```
+
+#### C. Update Program Initialization
+
+Replace line 77 with:
+
+```swift
+let program = Program(descriptors: [
+    usageDescriptor,
+    costDescriptor,
+    insightsDescriptor,
+    modelsDescriptor,
+    projectsDescriptor,
+    alertsDescriptor,
+    resetDescriptor,
+    usageEnhancedDescriptor,
+])
+```
+
+#### D. Add Command Handlers
+
+In the switch statement (around line 82), update to:
+
+```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 self.runModels(invocation)
+case "projects":
+    await self.runProjects(invocation)
+case "alerts":
+    await self.runAlerts(invocation)
+case "reset":
+    await self.runReset(invocation)
+case "usage-enhanced":
+    await self.runUsageEnhanced(invocation)
+default:
+    Self.exit(code: 1, message: "Unknown command")
+}
+```
+
+#### E. Implement Command Methods
+
+Add these methods after the existing command methods (after `runInsights`):
+
+```swift
+// MARK: - New Commands
+
+private static func runModels(_ invocation: CommandInvocation) async {
+    await ModelsCommand.run(invocation)
+}
+
+private static func runProjects(_ invocation: CommandInvocation) async {
+    await ProjectsCommand.run(invocation)
+}
+
+private static func runAlerts(_ invocation: CommandInvocation) async {
+    await AlertsCommand.run(invocation)
+}
+
+private static func runReset(_ invocation: CommandInvocation) async {
+    await ResetCommand.run(invocation)
+}
+
+private static func runUsageEnhanced(_ invocation: CommandInvocation) async {
+    await EnhancedUsageCommand.run(invocation)
+}
+```
+
+### 2. Build and Test
+
+#### Build the CLI
+```bash
+cd /Users/srinivaspendela/Sriinnu/AI/Runic
+swift build --target RunicCLI
+```
+
+#### Test Commands
+```bash
+# Test help
+.build/debug/RunicCLI --help
+
+# Test each command
+.build/debug/RunicCLI models
+.build/debug/RunicCLI projects
+.build/debug/RunicCLI alerts
+.build/debug/RunicCLI reset
+.build/debug/RunicCLI usage-enhanced
+
+# Test with options
+.build/debug/RunicCLI models --provider claude --json --pretty
+.build/debug/RunicCLI projects --list
+.build/debug/RunicCLI alerts --active
+.build/debug/RunicCLI reset --compact
+.build/debug/RunicCLI usage-enhanced --mode trending --days 30
+```
+
+### 3. Troubleshooting
+
+#### Common Issues
+
+**Issue: "Unknown command" error**
+- Verify the command descriptor is added to the Program initialization
+- Check the case statement includes the command name
+
+**Issue: Compilation errors**
+- Ensure all command files are in the correct directory
+- Verify imports are correct
+- Check that RunicCore exports required types
+
+**Issue: "No such module" errors**
+- Verify Package.swift includes all dependencies
+- Run `swift package clean && swift build`
+
+**Issue: Color output not working**
+- Check terminal supports ANSI colors
+- Use `--no-color` flag to disable colors
+
+### 4. Optional: Add to Package.swift
+
+If you want to build the commands as a separate module (optional):
+
+```swift
+.target(
+    name: "RunicCLICommands",
+    dependencies: [
+        "RunicCore",
+        .product(name: "Helix", package: "Helix"),
+    ],
+    path: "Sources/RunicCLI/Commands",
+    swiftSettings: [
+        .enableUpcomingFeature("StrictConcurrency"),
+    ]),
+```
+
+Then update RunicCLI target:
+```swift
+.executableTarget(
+    name: "RunicCLI",
+    dependencies: [
+        "RunicCore",
+        "RunicCLICommands",  // Add this
+        .product(name: "Helix", package: "Helix"),
+    ],
+    // ...
+```
+
+### 5. Documentation
+
+Update the main README or CLI documentation to include:
+- List of new commands
+- Usage examples
+- Feature descriptions
+- Sample output
+
+## Verification Checklist
+
+- [ ] All command files are in `/Sources/RunicCLI/Commands/`
+- [ ] CLIEntry.swift has been updated
+- [ ] Code compiles without errors
+- [ ] All commands respond to `--help`
+- [ ] Commands produce correct output
+- [ ] JSON output is valid
+- [ ] Color output works in terminal
+- [ ] Error messages are clear
+- [ ] Exit codes are correct
+
+## Next Steps
+
+1. **Testing**: Write unit tests for each command
+2. **Documentation**: Add detailed user documentation
+3. **Examples**: Create example scripts showing common workflows
+4. **Integration**: Consider CI/CD integration for automated testing
+5. **Performance**: Profile command execution times
+6. **Features**: Implement additional features as needed
+
+## Support
+
+For questions or issues:
+1. Check the README.md in this directory
+2. Review command source code
+3. Check existing CLI patterns in CLIEntry.swift
+4. Consult Helix documentation for argument parsing
+
+## Notes
+
+- All commands use async/await for data fetching
+- Commands are designed to be composable (output can be piped)
+- JSON output is suitable for scripting and automation
+- Error handling follows CLI best practices
+- Color codes are compatible with most terminal emulators