Add Ledger: a menu-bar app for Cursor spend#103
Open
kyleve wants to merge 12 commits into
Open
Conversation
The model layer for a new Ledger menu-bar app: fetches current-cycle Cursor spend from the Admin API (POST /teams/spend, Basic auth) and reduces it to the signed-in team member via a single observable LoadState. The Admin API key lives in the Keychain (KeychainStore); only the email + refresh interval persist as JSON (LedgerConfigStore). Restores the .macOS(.v26) platform and a LedgerCore product/target in Package.swift. Groundwork for the Ledger app (next commit); builds via swift build.
The native-macOS shell over LedgerCore: an NSStatusItem whose title shows the current-cycle spend (updated via an Observations loop) toggling an NSPopover that renders the LoadState, plus a System-Settings-style sidebar (General + Account panes) where the email and Keychain-stored Admin API key are set. Wires the Ledger app target (.mac, LSUIElement), the hostless LedgerCoreTests bundle, the Ledger / Ledger-macOS-Tests schemes, and restores the test-macos CI job. Verified: swiftformat --lint, tuist generate, and tuist test Ledger-macOS-Tests all pass (30 tests).
Adds README.md + AGENTS.md for Ledger/Ledger and Ledger/LedgerCore, and restores the native-macOS references in the root AGENTS.md (deployment row, the two-platform CI-scheme note, directory-layout mention, and the macOS test command). CLAUDE.md files regenerated via ./sync-agents (gitignored).
The Admin API (/teams/spend) only sees team accounts, so an individual account can't use it. Re-point the data layer at the same undocumented endpoints the cursor.com dashboard itself calls: - GET /api/usage-summary — current cycle dates, plan, and live usage-based spend (individualUsage.onDemand.used). - POST /api/dashboard/get-monthly-invoice — per-month billed totals, summed across the year for a year-to-date figure (the original yearly ask, now feasible). Auth is the WorkOS session cookie, value "<userId>::<jwt>". SessionToken derives the userId from the JWT sub (a bare JWT 401s). CursorLocalTokenSource auto-detects it read-only from the local Cursor app's state.vscdb; a pasted token in the Keychain overrides it. Drops the email + Admin API key UI. Verified against a live account (usage-summary + invoices) and via Ledger-macOS-Tests (26 tests); swiftformat --lint clean.
The status item was icon-only until the first fetch, making it easy to lose among other menu-bar items. Show the current-cycle amount as the title always, with a "$—" placeholder while loading, so it's a wider, findable target.
Opening the menu-bar popover fired a network fetch every time, which is too frequent. Rely on the periodic 15-minute refresh loop (which drives both the title and the popover) plus the explicit Refresh button; opening now just shows the latest fetched state.
Host a SwiftUI MenuBarLabel in the status item (via a click-through NSHostingView, so the button still toggles the popover) instead of setting a plain NSButton title, and give both it and the popover's headline amount .contentTransition(.numericText()) so digit changes roll over. The hosted label observes the session directly, replacing the manual Observations title loop.
A variable-length NSStatusItem doesn't auto-size to a hosted SwiftUI view, so only the leading icon was visible and the amount was clipped. MenuBarLabel now reports its rendered width (fixedSize + onGeometryChange) and the app delegate sets the item's length to match.
Adds an included-usage progress bar (usage-summary totalPercentUsed) with Cursor's own status messages, and a top-models-this-cycle breakdown from get-aggregated-usage-events. The per-model figure measures compute differently from the billed on-demand headline (they don't reconcile), so models are shown as usage *shares*, not dollars. The aggregated fetch is best-effort — a failure logs and yields no models rather than failing the whole load.
A script to run Ledger standalone without Xcode: regenerates the project, builds the Release configuration via xcodebuild (ad-hoc signed, so no Apple Developer account needed), installs to /Applications (quitting any running copy first), and launches it. --no-open skips the launch.
quit is asynchronous, so poll until the installed binary has actually exited (force-killing as a fallback) before rm/cp — making repeated runs race-free.
Silences the 'No App Category is set' build warning by tagging Ledger as a developer-tools app in its Info.plist.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A new native-macOS menu bar app, Ledger, that shows your current-cycle Cursor spend at a glance (with a year-to-date total in the popover). Building it also restores the native-macOS build infrastructure that was removed with Foreman (#68) — the
.macOSplatform, a.macapp target + hostless macOS test bundle, the platform-scoped CI scheme, and thetest-macosjob.Menu-bar title shows the live cycle-to-date amount (a
$—placeholder until the first fetch); clicking opens a popover with this cycle's spend + date range, year-to-date, included-usage used/limit, and plan tier.Data source
Works for individual accounts by calling the same undocumented endpoints the
cursor.com/dashboard/usagepage uses (the team Admin API only sees team accounts):GET /api/usage-summary— current cycle dates, plan, and live usage-based spend (individualUsage.onDemand.used).POST /api/dashboard/get-monthly-invoice— per-month billed totals, summed across the year for the YTD figure.Auth is zero-config: it auto-detects your Cursor session (read-only, from the local app's
state.vscdb→cursorAuth/accessToken) and builds the requiredWorkosCursorSessionToken=<userId>::<jwt>cookie, derivinguserIdfrom the JWTsub(a bare JWT 401s). Settings › Account has an optional paste-a-token override (stored in the Keychain) for when auto-detect fails or the session expires.Structure
Ledger/LedgerCore(macOS-only SPM library) —LedgerServices(@MainActor @Observableroot with a singleLoadState),SessionToken/CursorLocalTokenSource,DashboardProvider/CursorDashboardAPI,UsageSummary/MonthlyInvoice/SpendSnapshot,KeychainStore, andLoginItemController(launch-at-login, restored from Foreman).Ledger/Ledger(.mac,LSUIElement) — the AppKitNSStatusItem+NSPopovershell (title driven by anObservationsloop, deliberately notMenuBarExtra), a System-Settings-style sidebar, and the thinLedgerSessionfacade..macOS(.v26)+LedgerCoreinPackage.swift;Ledger/LedgerCoreTeststargets,Ledger/Ledger-macOS-Testsschemes inProject.swift; thetest-macosCI job; rootAGENTS.md+ per-moduleREADME.md/AGENTS.md.Notes / caveats
$figures reflect included-compute value, not money owed.Verification
./swiftformat --lint— cleantuist generate --no-open— cleantuist test Ledger-macOS-Tests— 26 tests pass (incl. a real SQLite round-trip for the token reader and the JWT→cookie derivation)tuist build Stuff-iOS-Tests— iOS scheme unaffected