here-macos CLAUDE.md

Here — AI Assistant Notes

Long-term menu bar macOS app showing your current egress country/region. Two-provider failover chain since v0.33.0: primary is ipwho.is, fallback is ip.guide (see Here/Networking/FallbackChainProvider.swift). Sequential, not racing — fallback only runs when the primary throws. The chain exists because a single hardcoded provider was a single point of failure when a user's VPN / proxy rules broke that one CDN (the v0.32.x → v0.33.0 motivation).

(Originally shipped as "IP Guide" through v0.23.x; renamed to Here at v0.24.0. Default provider switched to ipwho.is at v0.26.0 because ip.guide silently misreported VPN egresses. Failover chain added at v0.33.0; ip.guide came back as the fallback after field testing showed its accuracy on VPN egresses had improved.)

Architecture at a glance

• Entry: Here/App/HereApp.swift (SwiftUI App, settings-only scene)
• AppDelegate builds AppEnvironment + StatusBarController
• StatusBarController owns NSStatusItem + NSPopover (AppKit-managed)
• Popover content rendered with SwiftUI via NSHostingController
• All IP-lookup networking flows through IPService (actor) → an IPProvider. In production the provider is a FallbackChainProvider([IPWhoIsProvider(), IPGuideProvider()]) wired up in AppEnvironment. Emits IPState via AsyncStream. Each provider owns its own raw-response shape and a map(_:) adapter into the shared IPDataModel — swapping providers is mechanical, not a UI / cache rewrite. The chain wrapper itself conforms to IPProvider, so IPService knows nothing about failover — it just sees "one provider".
• RefreshScheduler runs the IP refresh loop on a hardcoded 5 s cadence (30 s while the display is asleep). NetworkMonitor (NWPathMonitor) fires extra immediate refreshes on becameReachable / pathChanged; lid-wake does the same. The polling loop is the safety net for everything else — at 5 s, you don't need a custom SCDynamicStore observer to catch WiFi hops or proxy toggles.
• UpdateChecker (actor) + UpdateInstaller (actor) + UpdateCoordinator (@MainActor) handle the auto-update pipeline.
  • Checker: fetches the GitHub releases atom feed (releases.atom on github.com, deliberately not the rate-limited api.github.com), parses it with XMLParser, and returns UpdateInfo (version + release page URL + a DMG URL synthesized from the Here-X.Y.Z.dmg naming convention — the atom feed doesn't enumerate release assets). See UpdateChecker.swift's header for why the atom feed replaced the JSON API at v0.33.0.
  • Coordinator: owns the daily wake-up timer, persists lastUpdateCheckAt / skippedUpdateVersion in SettingsStore, presents the "Update available" alert and the install progress NSPanel.
  • Installer: URLSession-downloads the DMG (intentionally avoids com.apple.quarantine xattr that browser downloads carry — that's how we skip the Gatekeeper "open anyway" prompt on every upgrade), hdiutil attachs it, ditto-copies Here.app to a staging dir, then writes a tiny bash relauncher that polls our PID, swaps /Applications/Here.app, and opens the new bundle. We NSApp.terminate(nil) ourselves; the script outlives us by being detached from our stdio.
• Picker (Never / Once a day / Once a week) + Check now button live in General settings.
• The popover footer's settings gear opens Settings via SwiftUI's \.openSettings env action; the right-click menu's Settings… item calls the same captured action through AppEnvironment.openSettingsAction. Don't try to open Settings via NSApp.sendAction(showSettingsWindow:) from AppKit code — for LSUIElement apps with no visible main menu it silently no-ops.
• Settings use an @Observable SettingsStore with UserDefaults-backed properties (manual didSet persistence)
• Cache at ~/Library/Application Support/Here/last_ip.json (we ship without App Sandbox — see Here/Here.entitlements for why; the in-app installer needs to spawn hdiutil and write outside the container).