metria

Imported from yurirxmos/metria (AGENTS.md). Install upstream with npx skills add yurirxmos/metria. Copyright stays with the author.

Agent Instructions

• All repository text must be en-us, including Swift comments, UI strings, commit messages, and documentation; do not add Portuguese text.
• All user-facing strings must use the repository's i18n mechanism and be added to the relevant localization catalog with translations when UI changes are made.
• The native macOS app is a Swift Package executable targeting macOS 13+, with the application entrypoint in apps/macos-native/Sources/Metria/MetriaApp.swift.
• The app is a menu-bar AppKit application whose dashboard, settings, and floating notch surface are SwiftUI views coordinated by AppDelegate.
• The floating surface is a "side notch": NotchGeometry anchors it flush against the right screen edge, hanging from just below the menu bar (visibleFrame, not the physical notch's safeAreaInsets); it stays edge-tight as a compact provider rail while idle and shows the hovered provider's card to the left.
• Run swift build from the repository root for the required verification.
• The native core usage and refresh logic lives in the MetriaCore library target (apps/macos-native/Sources/MetriaCore).
• The package manifest explicitly lists the source file and copies provider logos from Assets/; update Package.swift when adding or moving bundled assets.
• Usage credentials are read from macOS Keychain and local OpenCode/Codex files; do not commit credentials, generated .build/ output, or local configuration.
• Provider selection, display mode, and notch opacity (applied only while expanded) are persisted through UserDefaults; preserve these keys when changing settings behavior.
• swift build passing is not sufficient to know a new file compiles for release: native release archives are built via apps/macos-native/scripts/package-macos.sh, which uses xcodebuild against the checked-in Metria.xcodeproj, not SwiftPM. Any new file added under apps/macos-native/Sources/ must also be added to the Xcode project (xcodegen generate --spec apps/macos-native/project.yml, then commit the regenerated Metria.xcodeproj) or xcodebuild will fail to find its types while swift build stays green.
• Before pushing a release tag, dry-run bash apps/macos-native/scripts/package-macos.sh locally (needs Xcode 26+) and inspect the resulting dist/Metria.app (codesign --verify --deep --strict, plutil -p Contents/Info.plist). It exercises the exact build the release CI runs, far faster than round-tripping through Actions.
• Custom Info.plist keys (Sparkle's SUFeedURL, SUPublicEDKey, etc.) must be written with PlistBuddy on the built app in package-macos.sh, not passed as INFOPLIST_KEY_* build settings to xcodebuild — Xcode's GENERATE_INFOPLIST_FILE only maps a fixed set of well-known Apple keys and silently drops anything else, so the build succeeds with the update feed URL missing entirely.
• Sparkle's generate_appcast refuses two architecture archives sharing one bundle version, so Intel and Apple Silicon each get their own appcast feed (appcast-intel.xml / appcast-apple-silicon.xml), matching each build's SUFeedURL. Builds through v0.1.10 still hardcode a single unified appcast.xml — keep publishing that legacy filename (mirroring the Intel feed) or those installs can never discover a newer version.
• generate_appcast --ed-key-file - accepts a piped private key without error but does not actually sign the feed. Sign the generated file explicitly afterward with sign_update --ed-key-file - and confirm a sparkle-signatures block landed in it before publishing.
• After a new macos-v* release publishes successfully, keep only the 3 most recent version releases public and draft the rest with gh release edit <tag> --draft — never delete them. The git tag and release assets stay intact; drafting just removes the entry from the public /releases page and makes its assets require repo write access to download. Never draft the macos-latest channel release itself: its URL is hardcoded into every installed build's SUFeedURL, and hiding it breaks Check for Updates for everyone, not just old installs.
• gh release edit <tag> --draft=false (re-publishing a draft) resets that release's published_at to the current time, which can make GitHub hand the "Latest" badge to an old release just because it was touched most recently — not to whichever tag is actually newest. If you ever un-draft an older release, immediately run gh release edit <newest-tag> --latest and confirm with gh release list that the right tag is still marked Latest.
• The GitHub web UI always shows drafts to anyone with repo write access, interleaved with real releases with no clear separation — that view is not what an actual end user sees. Verify the public release list with an unauthenticated request instead: curl -s https://api.github.com/repos/<owner>/<repo>/releases (no token) returns only non-draft releases, which is the ground truth for what end users can find and download.
• Native macOS releases use macos-v* tags in this repository.
• This repository holds the native macOS app and the companion PWA only. The Electron app for Windows and Linux lives in yurirxmos/metria-win-linux. Do not re-add it here.
• Sources/MetriaCore is duplicated in that repository because the pairing derivations must stay byte-identical across them: one phone pairs with either desktop app. Changing a derivation here without changing it there breaks pairing, so treat any edit to PairingSecret.swift or UsageSnapshot.swift as a change to both repositories.