@sriinnu/runic 1.0.0

package/Sources/Runic/Controllers/StatusItemController.swift

@@ -0,0 +1,360 @@
+import AppKit
+import RunicCore
+import Observation
+import QuartzCore
+import SwiftUI
+
+/// **StatusItemController** - Manages macOS menubar status item and dropdown menu
+///
+/// **Purpose:**
+/// Coordinates the menubar icon, animations, menu construction, and user interactions.
+/// Acts as the bridge between AppKit (NSStatusItem) and SwiftUI (menu cards).
+///
+/// **Responsibilities:**
+/// - Create and manage NSStatusItem in menubar
+/// - Coordinate icon rendering via IconRenderer
+/// - Build rich NSMenu with embedded SwiftUI views
+/// - Handle animation lifecycle (60 FPS during pings)
+/// - Schedule background "ping" operations when menu opens
+/// - Manage keyboard shortcuts and user actions
+///
+/// **Architecture Pattern:**
+/// This file is split across 4 files via extensions:
+/// - `StatusItemController.swift` - Core setup (318 lines)
+/// - `StatusItemController+Menu.swift` - Menu construction (1878 lines)
+/// - `StatusItemController+Actions.swift` - User actions (200 lines)
+/// - `StatusItemController+Animation.swift` - Animation system (469 lines)
+///
+/// **Performance:**
+/// - **60 FPS cap** during active pings (PerformanceConstants.menubarFPS)
+/// - **Auto-stop animations** when data loaded or error encountered
+/// - **1.2s delay** before background ping when menu opens (reduce perceived lag)
+///
+/// **Dependencies:**
+/// - `UsageStore` - Data source
+/// - `SettingsStore` - User preferences
+/// - `IconRenderer` - Icon generation
+/// - `MenuCardView` - SwiftUI menu content
+///
+/// **Usage:**
+/// ```swift
+/// let controller = StatusItemController(
+///     store: usageStore,
+///     settings: settingsStore,
+///     account: accountInfo,
+///     updater: updater,
+///     preferencesSelection: selection
+/// )
+/// ```
+
+// MARK: - Status item controller (AppKit-hosted icons, SwiftUI popovers)
+
+@MainActor
+protocol StatusItemControlling: AnyObject {
+    func openMenuFromShortcut()
+}
+
+@MainActor
+final class StatusItemController: NSObject, NSMenuDelegate, StatusItemControlling {
+    typealias Factory = (UsageStore, SettingsStore, AccountInfo, UpdaterProviding, PreferencesSelection)
+        -> StatusItemControlling
+    static let defaultFactory: Factory = { store, settings, account, updater, selection in
+        StatusItemController(
+            store: store,
+            settings: settings,
+            account: account,
+            updater: updater,
+            preferencesSelection: selection)
+    }
+
+    static var factory: Factory = StatusItemController.defaultFactory
+
+    let store: UsageStore
+    let settings: SettingsStore
+    let account: AccountInfo
+    let updater: UpdaterProviding
+    var statusItem: NSStatusItem
+    var statusItems: [UsageProvider: NSStatusItem] = [:]
+    var lastMenuProvider: UsageProvider?
+    var menuProviders: [ObjectIdentifier: UsageProvider] = [:]
+    var menuContentVersion: Int = 0
+    var menuVersions: [ObjectIdentifier: Int] = [:]
+    var mergedMenu: NSMenu?
+    var providerMenus: [UsageProvider: NSMenu] = [:]
+    var fallbackMenu: NSMenu?
+    var openMenus: [ObjectIdentifier: NSMenu] = [:]
+    var menuPingTasks: [ObjectIdentifier: Task<Void, Never>] = [:]
+    var blinkTask: Task<Void, Never>?
+    var loginTask: Task<Void, Never>? {
+        didSet { self.refreshMenusForLoginStateChange() }
+    }
+
+    var creditsPurchaseWindow: OpenAICreditsPurchaseWindowController?
+
+    var activeLoginProvider: UsageProvider? {
+        didSet {
+            if oldValue != self.activeLoginProvider {
+                self.refreshMenusForLoginStateChange()
+            }
+        }
+    }
+
+    var blinkStates: [UsageProvider: BlinkState] = [:]
+    var blinkAmounts: [UsageProvider: CGFloat] = [:]
+    var wiggleAmounts: [UsageProvider: CGFloat] = [:]
+    var tiltAmounts: [UsageProvider: CGFloat] = [:]
+    var blinkForceUntil: Date?
+    var loginPhase: LoginPhase = .idle {
+        didSet {
+            if oldValue != self.loginPhase {
+                self.refreshMenusForLoginStateChange()
+            }
+        }
+    }
+
+    let preferencesSelection: PreferencesSelection
+    var animationDriver: DisplayLinkDriver?
+    var animationPhase: Double = 0
+    var animationPattern: LoadingPattern = .knightRider
+    let loginLogger = RunicLog.logger("login")
+    var selectedMenuProvider: UsageProvider? {
+        get { self.settings.selectedMenuProvider }
+        set { self.settings.selectedMenuProvider = newValue }
+    }
+
+    struct BlinkState {
+        var nextBlink: Date
+        var blinkStart: Date?
+        var pendingSecondStart: Date?
+        var effect: MotionEffect = .blink
+
+        static func randomDelay() -> TimeInterval {
+            Double.random(in: 3...12)
+        }
+    }
+
+    enum MotionEffect {
+        case blink
+        case wiggle
+        case tilt
+    }
+
+    enum LoginPhase {
+        case idle
+        case requesting
+        case waitingBrowser
+    }
+
+    init(
+        store: UsageStore,
+        settings: SettingsStore,
+        account: AccountInfo,
+        updater: UpdaterProviding,
+        preferencesSelection: PreferencesSelection)
+    {
+        self.store = store
+        self.settings = settings
+        self.account = account
+        self.updater = updater
+        self.preferencesSelection = preferencesSelection
+        let bar = NSStatusBar.system
+        let item = bar.statusItem(withLength: NSStatusItem.variableLength)
+        // Ensure the icon is rendered at 1:1 without resampling (crisper edges for template images).
+        item.button?.imageScaling = .scaleNone
+        self.statusItem = item
+        for provider in UsageProvider.allCases {
+            let providerItem = bar.statusItem(withLength: NSStatusItem.variableLength)
+            // Ensure the icon is rendered at 1:1 without resampling (crisper edges for template images).
+            providerItem.button?.imageScaling = .scaleNone
+            self.statusItems[provider] = providerItem
+        }
+        super.init()
+        self.wireBindings()
+        self.updateIcons()
+        self.updateVisibility()
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(self.handleDebugReplayNotification(_:)),
+            name: .runicDebugReplayAllAnimations,
+            object: nil)
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(self.handleDebugBlinkNotification),
+            name: .runicDebugBlinkNow,
+            object: nil)
+    }
+
+    private func wireBindings() {
+        self.observeStoreChanges()
+        self.observeDebugForceAnimation()
+        self.observeSettingsChanges()
+        self.observeUpdaterChanges()
+    }
+
+    private func observeStoreChanges() {
+        withObservationTracking {
+            _ = self.store.menuObservationToken
+        } onChange: { [weak self] in
+            Task { @MainActor [weak self] in
+                guard let self else { return }
+                self.observeStoreChanges()
+                self.invalidateMenus()
+                self.updateIcons()
+                self.updateBlinkingState()
+            }
+        }
+    }
+
+    private func observeDebugForceAnimation() {
+        withObservationTracking {
+            _ = self.store.debugForceAnimation
+        } onChange: { [weak self] in
+            Task { @MainActor [weak self] in
+                guard let self else { return }
+                self.observeDebugForceAnimation()
+                self.updateVisibility()
+                self.updateBlinkingState()
+            }
+        }
+    }
+
+    private func observeSettingsChanges() {
+        withObservationTracking {
+            _ = self.settings.menuObservationToken
+        } onChange: { [weak self] in
+            Task { @MainActor [weak self] in
+                guard let self else { return }
+                self.observeSettingsChanges()
+                self.invalidateMenus()
+                self.updateVisibility()
+                self.updateIcons()
+            }
+        }
+    }
+
+    private func observeUpdaterChanges() {
+        withObservationTracking {
+            _ = self.updater.updateStatus.isUpdateReady
+        } onChange: { [weak self] in
+            Task { @MainActor [weak self] in
+                guard let self else { return }
+                self.observeUpdaterChanges()
+                self.invalidateMenus()
+            }
+        }
+    }
+
+    private func invalidateMenus() {
+        self.menuContentVersion &+= 1
+        self.refreshOpenMenusIfNeeded()
+        Task { @MainActor in
+            // AppKit can ignore menu mutations while tracking; retry on the next run loop.
+            await Task.yield()
+            self.refreshOpenMenusIfNeeded()
+        }
+    }
+
+    private func updateIcons() {
+        if self.shouldMergeIcons {
+            self.applyIcon(phase: nil)
+            self.attachMenus()
+        } else {
+            UsageProvider.allCases.forEach { self.applyIcon(for: $0, phase: nil) }
+            self.attachMenus(fallback: self.fallbackProvider)
+        }
+        self.updateAnimationState()
+        self.updateBlinkingState()
+    }
+
+    private func updateVisibility() {
+        let anyEnabled = !self.store.enabledProviders().isEmpty
+        let force = self.store.debugForceAnimation
+        if self.shouldMergeIcons {
+            self.statusItem.isVisible = anyEnabled || force
+            for item in self.statusItems.values {
+                item.isVisible = false
+            }
+            self.attachMenus()
+        } else {
+            self.statusItem.isVisible = false
+            let fallback = self.fallbackProvider
+            for provider in UsageProvider.allCases {
+                let item = self.statusItems[provider]
+                let isEnabled = self.isEnabled(provider)
+                item?.isVisible = isEnabled || fallback == provider || force
+            }
+            self.attachMenus(fallback: fallback)
+        }
+        self.updateAnimationState()
+        self.updateBlinkingState()
+    }
+
+    var fallbackProvider: UsageProvider? {
+        self.store.enabledProviders().isEmpty ? .codex : nil
+    }
+
+    func isEnabled(_ provider: UsageProvider) -> Bool {
+        self.store.isEnabled(provider)
+    }
+
+    private func refreshMenusForLoginStateChange() {
+        self.invalidateMenus()
+        if self.shouldMergeIcons {
+            self.attachMenus()
+        } else {
+            self.attachMenus(fallback: self.fallbackProvider)
+        }
+    }
+
+    private func attachMenus() {
+        if self.mergedMenu == nil {
+            self.mergedMenu = self.makeMenu()
+        }
+        self.statusItem.menu = self.mergedMenu
+    }
+
+    private func attachMenus(fallback: UsageProvider? = nil) {
+        for provider in UsageProvider.allCases {
+            guard let item = self.statusItems[provider] else { continue }
+            if self.isEnabled(provider) {
+                if self.providerMenus[provider] == nil {
+                    self.providerMenus[provider] = self.makeMenu(for: provider)
+                }
+                item.menu = self.providerMenus[provider]
+            } else if fallback == provider {
+                if self.fallbackMenu == nil {
+                    self.fallbackMenu = self.makeMenu(for: nil)
+                }
+                item.menu = self.fallbackMenu
+            } else {
+                item.menu = nil
+            }
+        }
+    }
+
+    func isVisible(_ provider: UsageProvider) -> Bool {
+        self.store.debugForceAnimation || self.isEnabled(provider) || self.fallbackProvider == provider
+    }
+
+    var shouldMergeIcons: Bool {
+        self.settings.mergeIcons && self.store.enabledProviders().count > 1
+    }
+
+    func switchAccountSubtitle(for target: UsageProvider) -> String? {
+        guard self.loginTask != nil, let provider = self.activeLoginProvider, provider == target else { return nil }
+        let base: String
+        switch self.loginPhase {
+        case .idle: return nil
+        case .requesting: base = "Requesting login…"
+        case .waitingBrowser: base = "Waiting in browser…"
+        }
+        let prefix = ProviderDescriptorRegistry.descriptor(for: provider).metadata.displayName
+        return "\(prefix): \(base)"
+    }
+
+    deinit {
+        self.blinkTask?.cancel()
+        self.loginTask?.cancel()
+        NotificationCenter.default.removeObserver(self)
+    }
+}

package/Sources/Runic/Core/BudgetNotificationManager.swift

@@ -0,0 +1,80 @@
+import Foundation
+import RunicCore
+
+/// Monitors spend forecasts and posts macOS notifications when projected costs breach budget limits.
+@MainActor
+final class BudgetNotificationManager {
+    static let shared = BudgetNotificationManager()
+
+    private let logger = RunicLog.logger("budget-notifications")
+
+    /// UserDefaults key prefix for tracking which breaches have already been notified.
+    private static let notifiedKeyPrefix = "budgetBreachNotified-"
+
+    /// The calendar month key used to scope notifications (e.g. "2026-03").
+    /// Notifications reset each month so users are re-notified in new billing cycles.
+    private var currentMonthKey: String {
+        let formatter = DateFormatter()
+        formatter.locale = Locale(identifier: "en_US_POSIX")
+        formatter.timeZone = TimeZone.current
+        formatter.dateFormat = "yyyy-MM"
+        return formatter.string(from: Date())
+    }
+
+    private init() {}
+
+    /// Check all spend forecasts and post notifications for newly detected breaches.
+    ///
+    /// - Parameters:
+    ///   - forecasts: Per-provider arrays of project-level spend forecasts.
+    ///   - settings: The settings store, used to check if budget notifications are enabled.
+    func checkAndNotify(
+        forecasts: [UsageProvider: [UsageLedgerSpendForecast]],
+        settings: SettingsStore)
+    {
+        guard settings.budgetNotificationsEnabled else { return }
+
+        let monthKey = self.currentMonthKey
+        for (provider, providerForecasts) in forecasts {
+            for forecast in providerForecasts {
+                guard forecast.budgetWillBreach else { continue }
+                guard let budgetLimit = forecast.budgetLimitUSD, budgetLimit > 0 else { continue }
+
+                let projectKey = forecast.projectKey ?? forecast.projectID ?? "global"
+                let notificationKey = Self.notifiedKeyPrefix + "\(monthKey)-\(provider.rawValue)-\(projectKey)"
+
+                // Skip if already notified this month for this project
+                if UserDefaults.standard.bool(forKey: notificationKey) {
+                    continue
+                }
+
+                let projectName = forecast.projectName
+                    ?? forecast.projectID
+                    ?? ProviderDescriptorRegistry.descriptor(for: provider).metadata.displayName
+
+                let overshoot = forecast.projected30DayCostUSD - budgetLimit
+                let limitStr = UsageFormatter.usdString(budgetLimit)
+                let overshootStr = UsageFormatter.usdString(max(0, overshoot))
+
+                let title = "Budget Alert: \(projectName)"
+                let body = "Projected to exceed \(limitStr) limit by \(overshootStr) this month"
+
+                self.logger.info("posting budget breach notification",
+                    metadata: [
+                        "provider": provider.rawValue,
+                        "project": projectKey,
+                        "limit": limitStr,
+                        "projected": UsageFormatter.usdString(forecast.projected30DayCostUSD),
+                    ])
+
+                AppNotifications.shared.post(
+                    idPrefix: "budget-\(provider.rawValue)-\(projectKey)",
+                    title: title,
+                    body: body)
+
+                // Mark as notified for this month
+                UserDefaults.standard.set(true, forKey: notificationKey)
+            }
+        }
+    }
+}

package/Sources/Runic/Core/Login/ClaudeLoginRunner.swift

@@ -0,0 +1,103 @@
+import RunicCore
+import Darwin
+import Foundation
+
+struct ClaudeLoginRunner {
+    enum Phase: Sendable {
+        case requesting
+        case waitingBrowser
+    }
+
+    struct Result {
+        enum Outcome {
+            case success
+            case timedOut
+            case failed(status: Int32)
+            case missingBinary
+            case launchFailed(String)
+        }
+
+        let outcome: Outcome
+        let output: String
+        let authLink: String?
+    }
+
+    static func run(timeout: TimeInterval = 120, onPhaseChange: @escaping @Sendable (Phase) -> Void) async -> Result {
+        await Task(priority: .userInitiated) {
+            onPhaseChange(.requesting)
+            do {
+                let runResult = try self.runPTY(timeout: timeout, onPhaseChange: onPhaseChange)
+                let link = self.firstLink(in: runResult.output)
+                if let link {
+                    return Result(outcome: .success, output: runResult.output, authLink: link)
+                }
+                return Result(outcome: .timedOut, output: runResult.output, authLink: nil)
+            } catch LoginError.binaryNotFound {
+                return Result(outcome: .missingBinary, output: "", authLink: nil)
+            } catch let LoginError.timedOut(text) {
+                return Result(outcome: .timedOut, output: text, authLink: self.firstLink(in: text))
+            } catch let LoginError.failed(status, text) {
+                return Result(outcome: .failed(status: status), output: text, authLink: self.firstLink(in: text))
+            } catch {
+                return Result(outcome: .launchFailed(error.localizedDescription), output: "", authLink: nil)
+            }
+        }.value
+    }
+
+    // MARK: - PTY runner
+
+    private enum LoginError: Error {
+        case binaryNotFound
+        case timedOut(text: String)
+        case failed(status: Int32, text: String)
+        case launchFailed(String)
+    }
+
+    private struct PTYRunResult {
+        let output: String
+    }
+
+    private static func runPTY(
+        timeout: TimeInterval,
+        onPhaseChange: @escaping @Sendable (Phase) -> Void) throws -> PTYRunResult
+    {
+        let runner = TTYCommandRunner()
+        var options = TTYCommandRunner.Options(rows: 50, cols: 160, timeout: timeout)
+        options.extraArgs = ["/login"]
+        options.stopOnURL = false // keep running until CLI confirms
+        options.stopOnSubstrings = ["Successfully logged in", "Login successful", "Logged in successfully"]
+        options.sendEnterEvery = 1.0
+        options.settleAfterStop = 0.35
+        do {
+            let result = try runner.run(
+                binary: "claude",
+                send: "",
+                options: options,
+                onURLDetected: { onPhaseChange(.waitingBrowser) })
+            return PTYRunResult(output: result.text)
+        } catch TTYCommandRunner.Error.binaryNotFound {
+            throw LoginError.binaryNotFound
+        } catch TTYCommandRunner.Error.timedOut {
+            throw LoginError.timedOut(text: "")
+        } catch let TTYCommandRunner.Error.launchFailed(msg) {
+            throw LoginError.launchFailed(msg)
+        } catch {
+            throw LoginError.launchFailed(error.localizedDescription)
+        }
+    }
+
+    private static func firstLink(in text: String) -> String? {
+        let pattern = #"https?://[A-Za-z0-9._~:/?#\[\]@!$&'()*+,;=%-]+"#
+        guard let regex = try? NSRegularExpression(pattern: pattern) else { return nil }
+        let nsRange = NSRange(text.startIndex..<text.endIndex, in: text)
+        guard let match = regex.firstMatch(in: text, options: [], range: nsRange),
+              let range = Range(match.range, in: text) else { return nil }
+        var url = String(text[range])
+        while let last = url.unicodeScalars.last,
+              CharacterSet(charactersIn: ".,;:)]}>\"'").contains(last)
+        {
+            url.unicodeScalars.removeLast()
+        }
+        return url
+    }
+}

package/Sources/Runic/Core/Login/CodexLoginRunner.swift

@@ -0,0 +1,154 @@
+import RunicCore
+import Darwin
+import Foundation
+
+struct CodexLoginRunner {
+    struct Result {
+        enum Outcome {
+            case success
+            case timedOut
+            case failed(status: Int32)
+            case missingBinary
+            case launchFailed(String)
+        }
+
+        let outcome: Outcome
+        let output: String
+    }
+
+    static func run(timeout: TimeInterval = 120) async -> Result {
+        await Task(priority: .userInitiated) {
+            var env = ProcessInfo.processInfo.environment
+            env["PATH"] = PathBuilder.effectivePATH(
+                purposes: [.rpc, .tty, .nodeTooling],
+                env: env,
+                loginPATH: LoginShellPathCache.shared.current)
+
+            guard let executable = BinaryLocator.resolveCodexBinary(
+                env: env,
+                loginPATH: LoginShellPathCache.shared.current)
+            else {
+                return Result(outcome: .missingBinary, output: "")
+            }
+
+            let process = Process()
+            process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+            process.arguments = [executable, "login"]
+            process.environment = env
+
+            let stdout = Pipe()
+            let stderr = Pipe()
+            process.standardOutput = stdout
+            process.standardError = stderr
+
+            var processGroup: pid_t?
+            do {
+                try process.run()
+                processGroup = self.attachProcessGroup(process)
+            } catch {
+                return Result(outcome: .launchFailed(error.localizedDescription), output: "")
+            }
+
+            let timedOut = await self.wait(for: process, timeout: timeout)
+            if timedOut {
+                self.terminate(process, processGroup: processGroup)
+            }
+
+            let output = await self.combinedOutput(stdout: stdout, stderr: stderr)
+            if timedOut {
+                return Result(outcome: .timedOut, output: output)
+            }
+
+            let status = process.terminationStatus
+            if status == 0 {
+                return Result(outcome: .success, output: output)
+            }
+            return Result(outcome: .failed(status: status), output: output)
+        }.value
+    }
+
+    private static func wait(for process: Process, timeout: TimeInterval) async -> Bool {
+        await withTaskGroup(of: Bool.self) { group -> Bool in
+            group.addTask {
+                process.waitUntilExit()
+                return false
+            }
+            group.addTask {
+                let nanos = UInt64(max(0, timeout) * 1_000_000_000)
+                try? await Task.sleep(nanoseconds: nanos)
+                return true
+            }
+            let result = await group.next() ?? false
+            group.cancelAll()
+            return result
+        }
+    }
+
+    private static func terminate(_ process: Process, processGroup: pid_t?) {
+        if let pgid = processGroup {
+            kill(-pgid, SIGTERM)
+        }
+        if process.isRunning {
+            process.terminate()
+        }
+
+        let deadline = Date().addingTimeInterval(2.0)
+        while process.isRunning, Date() < deadline {
+            usleep(100_000)
+        }
+
+        if process.isRunning {
+            if let pgid = processGroup {
+                kill(-pgid, SIGKILL)
+            }
+            kill(process.processIdentifier, SIGKILL)
+        }
+    }
+
+    private static func attachProcessGroup(_ process: Process) -> pid_t? {
+        let pid = process.processIdentifier
+        return setpgid(pid, pid) == 0 ? pid : nil
+    }
+
+    private static func combinedOutput(stdout: Pipe, stderr: Pipe) async -> String {
+        async let out = self.readToEnd(stdout)
+        async let err = self.readToEnd(stderr)
+        let stdoutText = await out
+        let stderrText = await err
+
+        let merged: String = if !stdoutText.isEmpty, !stderrText.isEmpty {
+            [stdoutText, stderrText].joined(separator: "\n")
+        } else {
+            stdoutText + stderrText
+        }
+        let trimmed = merged.trimmingCharacters(in: .whitespacesAndNewlines)
+        let limited = trimmed.prefix(4000)
+        return limited.isEmpty ? "No output captured." : String(limited)
+    }
+
+    private static func readToEnd(_ pipe: Pipe, timeout: TimeInterval = 3.0) async -> String {
+        await withTaskGroup(of: String?.self) { group -> String in
+            group.addTask {
+                if #available(macOS 13.0, *) {
+                    if let data = try? pipe.fileHandleForReading.readToEnd() { return self.decode(data) }
+                }
+                let data = pipe.fileHandleForReading.readDataToEndOfFile()
+                return Self.decode(data)
+            }
+            group.addTask {
+                let nanos = UInt64(max(0, timeout) * 1_000_000_000)
+                try? await Task.sleep(nanoseconds: nanos)
+                return nil
+            }
+            let result = await group.next()
+            group.cancelAll()
+            if let result, let text = result { return text }
+            return ""
+        }
+    }
+
+    private static func decode(_ data: Data) -> String {
+        guard let text = String(data: data, encoding: .utf8) else { return "" }
+        return text
+    }
+}