@sriinnu/runic 1.0.0

package/Tests/RunicTests/UsageLedgerInsightsAdvisorTests.swift

@@ -0,0 +1,83 @@
+import Foundation
+import Testing
+
+@testable import RunicCore
+
+@Suite
+struct UsageLedgerInsightsAdvisorTests {
+    @Test
+    func reliabilityScoreDropsWhenErrorsExist() {
+        let now = Date()
+        let daily = UsageLedgerDailySummary(
+            provider: .codex,
+            projectID: nil,
+            dayStart: now,
+            dayKey: "2026-02-21",
+            totals: UsageLedgerTotals(
+                inputTokens: 1_000,
+                outputTokens: 500,
+                cacheCreationTokens: 100,
+                cacheReadTokens: 200,
+                costUSD: 2.5),
+            modelsUsed: ["gpt-5"])
+
+        let scoreWithoutErrors = UsageLedgerInsightsAdvisor.reliabilityScore(
+            provider: .codex,
+            daily: daily,
+            activeBlock: nil,
+            modelBreakdown: [],
+            projectBreakdown: [],
+            providerError: nil,
+            ledgerError: nil)
+        let scoreWithErrors = UsageLedgerInsightsAdvisor.reliabilityScore(
+            provider: .codex,
+            daily: daily,
+            activeBlock: nil,
+            modelBreakdown: [],
+            projectBreakdown: [],
+            providerError: "fetch failed",
+            ledgerError: "parse failed")
+
+        #expect(scoreWithoutErrors != nil)
+        #expect(scoreWithErrors != nil)
+        #expect((scoreWithErrors?.score ?? 0) < (scoreWithoutErrors?.score ?? 100))
+    }
+
+    @Test
+    func routingRecommendationFindsSavingsBetweenModels() {
+        let expensive = UsageLedgerModelSummary(
+            provider: .codex,
+            projectID: "proj-a",
+            projectName: "Project A",
+            model: "gpt-5",
+            entryCount: 20,
+            totals: UsageLedgerTotals(
+                inputTokens: 30_000,
+                outputTokens: 20_000,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+                costUSD: 12.0))
+
+        let cheaper = UsageLedgerModelSummary(
+            provider: .codex,
+            projectID: "proj-a",
+            projectName: "Project A",
+            model: "gpt-5-mini",
+            entryCount: 30,
+            totals: UsageLedgerTotals(
+                inputTokens: 40_000,
+                outputTokens: 20_000,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+                costUSD: 3.0))
+
+        let recommendation = UsageLedgerInsightsAdvisor.routingRecommendation(
+            modelBreakdown: [expensive, cheaper],
+            shiftPercent: 0.20)
+
+        #expect(recommendation != nil)
+        #expect((recommendation?.estimatedSavingsUSD ?? 0) > 0)
+        #expect(recommendation?.fromModel == "gpt-5")
+        #expect(recommendation?.toModel == "gpt-5-mini")
+    }
+}

package/Tests/RunicTests/UsageLedgerProjectNameTests.swift

@@ -0,0 +1,170 @@
+import Foundation
+import Testing
+
+@testable import RunicCore
+
+@Suite
+struct UsageLedgerProjectNameTests {
+    @Test
+    func projectSummariesPreferNonEmptyProjectName() {
+        let now = Date()
+        let entries = [
+            UsageLedgerEntry(
+                provider: .codex,
+                timestamp: now,
+                sessionID: "s1",
+                projectID: "proj-123",
+                projectName: "   ",
+                model: "gpt-5",
+                inputTokens: 10,
+                outputTokens: 5,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+                costUSD: 0.01,
+                requestID: "r1",
+                messageID: nil,
+                version: nil,
+                source: .codexLog),
+            UsageLedgerEntry(
+                provider: .codex,
+                timestamp: now.addingTimeInterval(1),
+                sessionID: "s1",
+                projectID: "proj-123",
+                projectName: "Core Platform",
+                model: "gpt-5",
+                inputTokens: 20,
+                outputTokens: 10,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+                costUSD: 0.03,
+                requestID: "r2",
+                messageID: nil,
+                version: nil,
+                source: .codexLog),
+        ]
+
+        let projectSummary = UsageLedgerAggregator.projectSummaries(entries: entries).first
+        #expect(projectSummary?.projectID == "proj-123")
+        #expect(projectSummary?.projectName == "Core Platform")
+
+        let modelSummary = UsageLedgerAggregator.modelSummaries(entries: entries, groupByProject: true).first
+        #expect(modelSummary?.projectID == "proj-123")
+        #expect(modelSummary?.projectName == "Core Platform")
+    }
+
+    @Test
+    func projectSummariesGroupByInferredNameWhenProjectIDIsMissing() {
+        let now = Date()
+        let entries = [
+            UsageLedgerEntry(
+                provider: .codex,
+                timestamp: now,
+                sessionID: "s1",
+                projectID: nil,
+                projectName: "Alpha Workspace",
+                model: "gpt-5",
+                inputTokens: 50,
+                outputTokens: 10,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+                costUSD: 0.10,
+                requestID: "ra",
+                messageID: nil,
+                version: nil,
+                source: .codexLog),
+            UsageLedgerEntry(
+                provider: .codex,
+                timestamp: now.addingTimeInterval(5),
+                sessionID: "s2",
+                projectID: nil,
+                projectName: "Beta Workspace",
+                model: "gpt-5",
+                inputTokens: 40,
+                outputTokens: 15,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+                costUSD: 0.12,
+                requestID: "rb",
+                messageID: nil,
+                version: nil,
+                source: .codexLog),
+        ]
+
+        let summaries = UsageLedgerAggregator.projectSummaries(entries: entries)
+        #expect(summaries.count == 2)
+        let names = Set(summaries.map(\.projectName).compactMap { $0 })
+        #expect(names.contains("Alpha Workspace"))
+        #expect(names.contains("Beta Workspace"))
+    }
+
+    @Test
+    func projectSummariesInferProjectNameFromPathLikeIdentifier() {
+        let now = Date()
+        let entries = [
+            UsageLedgerEntry(
+                provider: .codex,
+                timestamp: now,
+                sessionID: "s1",
+                projectID: "/Users/me/workspace/Runic-App",
+                projectName: nil,
+                model: "gpt-5",
+                inputTokens: 100,
+                outputTokens: 30,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+                costUSD: 0.30,
+                requestID: "r-path",
+                messageID: nil,
+                version: nil,
+                source: .codexLog),
+        ]
+
+        let summary = UsageLedgerAggregator.projectSummaries(entries: entries).first
+        #expect(summary != nil)
+        #expect(summary?.projectKey != nil)
+        #expect(summary?.projectNameSource == .inferredFromPath)
+        #expect(summary?.displayProjectName == "Runic-App")
+    }
+
+    @Test
+    func projectDisplayNameFallsBackToReadableIdentifier() {
+        let summary = UsageLedgerProjectSummary(
+            provider: .codex,
+            projectID: "runic-core",
+            projectName: nil,
+            projectNameConfidence: .low,
+            projectNameSource: .projectID,
+            projectNameProvenance: "entry.projectID",
+            entryCount: 1,
+            totals: UsageLedgerTotals(
+                inputTokens: 1,
+                outputTokens: 1,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+                costUSD: nil),
+            modelsUsed: [])
+
+        #expect(summary.displayProjectName == "runic-core")
+    }
+
+    @Test
+    func projectDisplayNameKeepsOpaqueIdentifiersHidden() {
+        let summary = UsageLedgerProjectSummary(
+            provider: .codex,
+            projectID: "8f189f6bb4e9fa93a9a4bf5cf97a0b4d",
+            projectName: nil,
+            projectNameConfidence: .low,
+            projectNameSource: .projectID,
+            projectNameProvenance: "entry.projectID",
+            entryCount: 1,
+            totals: UsageLedgerTotals(
+                inputTokens: 1,
+                outputTokens: 1,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+                costUSD: nil),
+            modelsUsed: [])
+
+        #expect(summary.displayProjectName == "Unknown project")
+    }
+}

package/Tests/RunicTests/UsagePaceTests.swift

@@ -0,0 +1,77 @@
+import RunicCore
+import Foundation
+import Testing
+
+@Suite
+struct UsagePaceTests {
+    @Test
+    func weeklyPace_computesDeltaAndEta() {
+        let now = Date(timeIntervalSince1970: 0)
+        let window = RateWindow(
+            usedPercent: 50,
+            windowMinutes: 10080,
+            resetsAt: now.addingTimeInterval(4 * 24 * 3600),
+            resetDescription: nil)
+
+        let pace = UsagePace.weekly(window: window, now: now)
+
+        #expect(pace != nil)
+        guard let pace else { return }
+        #expect(abs(pace.expectedUsedPercent - 42.857) < 0.01)
+        #expect(abs(pace.deltaPercent - 7.143) < 0.01)
+        #expect(pace.stage == .ahead)
+        #expect(pace.willLastToReset == false)
+        #expect(pace.etaSeconds != nil)
+        #expect(abs((pace.etaSeconds ?? 0) - (3 * 24 * 3600)) < 1)
+    }
+
+    @Test
+    func weeklyPace_marksLastsToResetWhenUsageIsLow() {
+        let now = Date(timeIntervalSince1970: 0)
+        let window = RateWindow(
+            usedPercent: 5,
+            windowMinutes: 10080,
+            resetsAt: now.addingTimeInterval(4 * 24 * 3600),
+            resetDescription: nil)
+
+        let pace = UsagePace.weekly(window: window, now: now)
+
+        #expect(pace != nil)
+        guard let pace else { return }
+        #expect(pace.willLastToReset == true)
+        #expect(pace.etaSeconds == nil)
+        #expect(pace.stage == .farBehind)
+    }
+
+    @Test
+    func weeklyPace_hidesWhenResetMissingOrOutsideWindow() {
+        let now = Date(timeIntervalSince1970: 0)
+        let missing = RateWindow(
+            usedPercent: 10,
+            windowMinutes: 10080,
+            resetsAt: nil,
+            resetDescription: nil)
+        let tooFar = RateWindow(
+            usedPercent: 10,
+            windowMinutes: 10080,
+            resetsAt: now.addingTimeInterval(9 * 24 * 3600),
+            resetDescription: nil)
+
+        #expect(UsagePace.weekly(window: missing, now: now) == nil)
+        #expect(UsagePace.weekly(window: tooFar, now: now) == nil)
+    }
+
+    @Test
+    func weeklyPace_hidesWhenUsageExistsButNoElapsed() {
+        let now = Date(timeIntervalSince1970: 0)
+        let window = RateWindow(
+            usedPercent: 12,
+            windowMinutes: 10080,
+            resetsAt: now.addingTimeInterval(7 * 24 * 3600),
+            resetDescription: nil)
+
+        let pace = UsagePace.weekly(window: window, now: now)
+
+        #expect(pace == nil)
+    }
+}

package/Tests/RunicTests/UsagePaceTextTests.swift

@@ -0,0 +1,109 @@
+import RunicCore
+import Foundation
+import Testing
+@testable import Runic
+
+@Suite
+struct UsagePaceTextTests {
+    @Test
+    func weeklyPaceText_includesEtaWhenRunningOutBeforeReset() {
+        let now = Date(timeIntervalSince1970: 0)
+        let window = RateWindow(
+            usedPercent: 50,
+            windowMinutes: 10080,
+            resetsAt: now.addingTimeInterval(4 * 24 * 3600),
+            resetDescription: nil)
+
+        let text = UsagePaceText.weekly(provider: .codex, window: window, now: now)
+
+        #expect(text == "Pace: Ahead (+7%) · Runs out in 3d")
+    }
+
+    @Test
+    func weeklyPaceText_showsResetSafeWhenPaceIsSlow() {
+        let now = Date(timeIntervalSince1970: 0)
+        let window = RateWindow(
+            usedPercent: 10,
+            windowMinutes: 10080,
+            resetsAt: now.addingTimeInterval(4 * 24 * 3600),
+            resetDescription: nil)
+
+        let text = UsagePaceText.weekly(provider: .codex, window: window, now: now)
+
+        #expect(text == "Pace: Behind (-33%) · Lasts to reset")
+    }
+
+    @Test
+    func weeklyPaceText_hidesWhenResetIsMissing() {
+        let now = Date(timeIntervalSince1970: 0)
+        let window = RateWindow(
+            usedPercent: 10,
+            windowMinutes: 10080,
+            resetsAt: nil,
+            resetDescription: nil)
+
+        let text = UsagePaceText.weekly(provider: .codex, window: window, now: now)
+
+        #expect(text == nil)
+    }
+
+    @Test
+    func weeklyPaceText_hidesWhenResetIsInPastOrTooFar() {
+        let now = Date(timeIntervalSince1970: 0)
+        let pastWindow = RateWindow(
+            usedPercent: 10,
+            windowMinutes: 10080,
+            resetsAt: now.addingTimeInterval(-60),
+            resetDescription: nil)
+        let farFutureWindow = RateWindow(
+            usedPercent: 10,
+            windowMinutes: 10080,
+            resetsAt: now.addingTimeInterval(9 * 24 * 3600),
+            resetDescription: nil)
+
+        #expect(UsagePaceText.weekly(provider: .codex, window: pastWindow, now: now) == nil)
+        #expect(UsagePaceText.weekly(provider: .codex, window: farFutureWindow, now: now) == nil)
+    }
+
+    @Test
+    func weeklyPaceText_hidesWhenNoElapsedButUsageExists() {
+        let now = Date(timeIntervalSince1970: 0)
+        let window = RateWindow(
+            usedPercent: 5,
+            windowMinutes: 10080,
+            resetsAt: now.addingTimeInterval(7 * 24 * 3600),
+            resetDescription: nil)
+
+        let text = UsagePaceText.weekly(provider: .codex, window: window, now: now)
+
+        #expect(text == nil)
+    }
+
+    @Test
+    func weeklyPaceText_hidesWhenTooEarlyInWindow() {
+        let now = Date(timeIntervalSince1970: 0)
+        let window = RateWindow(
+            usedPercent: 40,
+            windowMinutes: 10080,
+            resetsAt: now.addingTimeInterval((7 * 24 * 3600) - (60 * 60)),
+            resetDescription: nil)
+
+        let text = UsagePaceText.weekly(provider: .codex, window: window, now: now)
+
+        #expect(text == nil)
+    }
+
+    @Test
+    func weeklyPaceText_hidesWhenUsageIsDepleted() {
+        let now = Date(timeIntervalSince1970: 0)
+        let window = RateWindow(
+            usedPercent: 100,
+            windowMinutes: 10080,
+            resetsAt: now.addingTimeInterval(2 * 24 * 3600),
+            resetDescription: nil)
+
+        let text = UsagePaceText.weekly(provider: .codex, window: window, now: now)
+
+        #expect(text == nil)
+    }
+}

package/Tests/RunicTests/UsagePolicyEngineTests.swift

@@ -0,0 +1,91 @@
+import Testing
+
+@testable import RunicCore
+
+@Suite
+struct UsagePolicyEngineTests {
+    @Test
+    func returnsNoneWhenNoRulesMatch() {
+        let context = UsagePolicyContext(
+            provider: .codex,
+            observedSpendUSD: 45,
+            projectedSpendUSD: 70,
+            budgetLimitUSD: 100,
+            anomalySeverity: .elevated)
+        let rules = [
+            UsagePolicyRule(
+                id: "hard-stop-over-budget",
+                name: "Hard stop after budget breach",
+                condition: .actualBudgetOverrun,
+                action: .hardStop),
+            UsagePolicyRule(
+                id: "critical-anomaly-soft-limit",
+                name: "Soft limit only on critical anomaly",
+                condition: .anomalySeverityAtLeast(.critical),
+                action: .softLimit),
+        ]
+
+        let decision = UsagePolicyEngine.evaluate(context: context, rules: rules)
+        #expect(decision.action == .none)
+        #expect(decision.matches.isEmpty)
+        #expect(decision.shouldThrottle == false)
+        #expect(decision.shouldBlock == false)
+    }
+
+    @Test
+    func selectsStrongestActionAcrossMatchedRules() {
+        let context = UsagePolicyContext(
+            provider: .codex,
+            observedSpendUSD: 120,
+            projectedSpendUSD: 170,
+            budgetLimitUSD: 100,
+            anomalySeverity: .critical)
+        let rules = [
+            UsagePolicyRule(
+                id: "warn-projected-20",
+                name: "Warn at projected +20%",
+                condition: .projectedBudgetOverrun(minimumPercent: 0.20),
+                action: .warn),
+            UsagePolicyRule(
+                id: "soft-anomaly-high",
+                name: "Soft limit on high anomaly",
+                condition: .anomalySeverityAtLeast(.high),
+                action: .softLimit),
+            UsagePolicyRule(
+                id: "stop-actual-overrun",
+                name: "Hard stop once actually over budget",
+                condition: .actualBudgetOverrun,
+                action: .hardStop),
+        ]
+
+        let decision = UsagePolicyEngine.evaluate(context: context, rules: rules)
+        #expect(decision.action == .hardStop)
+        #expect(decision.shouldThrottle == true)
+        #expect(decision.shouldBlock == true)
+        #expect(decision.matches.count == 3)
+        #expect(decision.matches.contains { $0.ruleID == "warn-projected-20" })
+        #expect(decision.matches.contains { $0.ruleID == "soft-anomaly-high" })
+        #expect(decision.matches.contains { $0.ruleID == "stop-actual-overrun" })
+    }
+
+    @Test
+    func projectedOverrunConditionRespectsThreshold() {
+        let context = UsagePolicyContext(
+            provider: .codex,
+            observedSpendUSD: 80,
+            projectedSpendUSD: 112,
+            budgetLimitUSD: 100,
+            anomalySeverity: nil)
+        let rules = [
+            UsagePolicyRule(
+                id: "warn-projected-20",
+                name: "Warn at projected +20%",
+                condition: .projectedBudgetOverrun(minimumPercent: 0.20),
+                action: .warn),
+        ]
+
+        let decision = UsagePolicyEngine.evaluate(context: context, rules: rules)
+        #expect(decision.action == .none)
+        #expect(decision.matches.isEmpty)
+    }
+}

package/Tests/RunicTests/WidgetSnapshotTests.swift

@@ -0,0 +1,45 @@
+import Foundation
+import Testing
+
+@testable import RunicCore
+
+@Suite
+struct WidgetSnapshotTests {
+    @Test
+    func widgetSnapshotRoundTrip() throws {
+        let entry = WidgetSnapshot.ProviderEntry(
+            provider: .codex,
+            updatedAt: Date(),
+            primary: RateWindow(usedPercent: 10, windowMinutes: nil, resetsAt: nil, resetDescription: nil),
+            secondary: RateWindow(usedPercent: 20, windowMinutes: nil, resetsAt: nil, resetDescription: nil),
+            tertiary: nil,
+            creditsRemaining: 123.4,
+            codeReviewRemainingPercent: 80,
+            tokenUsage: WidgetSnapshot.TokenUsageSummary(
+                sessionCostUSD: 12.3,
+                sessionTokens: 1200,
+                last30DaysCostUSD: 456.7,
+                last30DaysTokens: 9800),
+            dailyUsage: [
+                WidgetSnapshot.DailyUsagePoint(dayKey: "2025-12-20", totalTokens: 1200, costUSD: 12.3),
+            ])
+
+        let snapshot = WidgetSnapshot(
+            entries: [entry],
+            enabledProviders: [.codex, .claude],
+            generatedAt: Date())
+
+        let encoder = JSONEncoder()
+        encoder.dateEncodingStrategy = .iso8601
+        let data = try encoder.encode(snapshot)
+
+        let decoder = JSONDecoder()
+        decoder.dateDecodingStrategy = .iso8601
+        let decoded = try decoder.decode(WidgetSnapshot.self, from: data)
+
+        #expect(decoded.entries.count == 1)
+        #expect(decoded.entries.first?.provider == .codex)
+        #expect(decoded.entries.first?.tokenUsage?.sessionTokens == 1200)
+        #expect(decoded.enabledProviders == [.codex, .claude])
+    }
+}

package/Tests/RunicTests/ZaiProviderTests.swift

@@ -0,0 +1,61 @@
+import Foundation
+import Testing
+@testable import RunicCore
+
+@Suite
+struct ZaiSettingsReaderTests {
+    @Test
+    func apiTokenReadsFromEnvironment() {
+        let token = ZaiSettingsReader.apiToken(environment: ["Z_AI_API_KEY": "abc123"])
+        #expect(token == "abc123")
+    }
+
+    @Test
+    func apiTokenStripsQuotes() {
+        let token = ZaiSettingsReader.apiToken(environment: ["Z_AI_API_KEY": "\"token-xyz\""])
+        #expect(token == "token-xyz")
+    }
+}
+
+@Suite
+struct ZaiUsageSnapshotTests {
+    @Test
+    func mapsUsageSnapshotWindows() {
+        let reset = Date(timeIntervalSince1970: 123)
+        let tokenLimit = ZaiLimitEntry(
+            type: .tokensLimit,
+            unit: .hours,
+            number: 5,
+            usage: 100,
+            currentValue: 20,
+            remaining: 80,
+            percentage: 25,
+            usageDetails: [],
+            nextResetTime: reset)
+        let timeLimit = ZaiLimitEntry(
+            type: .timeLimit,
+            unit: .days,
+            number: 30,
+            usage: 200,
+            currentValue: 40,
+            remaining: 160,
+            percentage: 50,
+            usageDetails: [],
+            nextResetTime: nil)
+        let snapshot = ZaiUsageSnapshot(
+            tokenLimit: tokenLimit,
+            timeLimit: timeLimit,
+            planName: nil,
+            updatedAt: reset)
+
+        let usage = snapshot.toUsageSnapshot()
+
+        #expect(usage.primary.usedPercent == 20)
+        #expect(usage.primary.windowMinutes == 300)
+        #expect(usage.primary.resetsAt == reset)
+        #expect(usage.primary.resetDescription == "5 hours window")
+        #expect(usage.secondary?.usedPercent == 20)
+        #expect(usage.secondary?.resetDescription == "30 days window")
+        #expect(usage.zaiUsage?.tokenLimit?.usage == 100)
+    }
+}

package/Tests/RunicTests/ZaiTokenStoreTestSupport.swift

@@ -0,0 +1,6 @@
+@testable import Runic
+
+struct NoopZaiTokenStore: ZaiTokenStoring {
+    func loadToken() throws -> String? { nil }
+    func storeToken(_: String?) throws {}
+}

package/TestsLinux/PlatformGatingTests.swift

@@ -0,0 +1,46 @@
+import RunicCore
+import Testing
+
+@Suite
+struct PlatformGatingTests {
+    @Test
+    func claudeWebFetcher_isNotSupportedOnLinux() async {
+        #if os(Linux)
+        let error = await #expect(throws: ClaudeWebAPIFetcher.FetchError.self) {
+            _ = try await ClaudeWebAPIFetcher.fetchUsage()
+        }
+        let isExpectedError = error.map { thrown in
+            if case .notSupportedOnThisPlatform = thrown { return true }
+            return false
+        } ?? false
+        #expect(isExpectedError)
+        #else
+        #expect(Bool(true))
+        #endif
+    }
+
+    @Test
+    func claudeWebFetcher_hasSessionKey_isFalseOnLinux() {
+        #if os(Linux)
+        #expect(ClaudeWebAPIFetcher.hasSessionKey() == false)
+        #else
+        #expect(Bool(true))
+        #endif
+    }
+
+    @Test
+    func claudeWebFetcher_sessionKeyInfo_throwsOnLinux() {
+        #if os(Linux)
+        let error = #expect(throws: ClaudeWebAPIFetcher.FetchError.self) {
+            _ = try ClaudeWebAPIFetcher.sessionKeyInfo()
+        }
+        let isExpectedError = error.map { thrown in
+            if case .notSupportedOnThisPlatform = thrown { return true }
+            return false
+        } ?? false
+        #expect(isExpectedError)
+        #else
+        #expect(Bool(true))
+        #endif
+    }
+}