If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kmikiy/SpotMenu shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 3w ago
• 4 active contributors
• MIT licensed
• CI configured
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kmikiy/SpotMenu repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kmikiy/SpotMenu.

What it runs against: a local clone of kmikiy/SpotMenu — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kmikiy/SpotMenu | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 48 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kmikiy/SpotMenu. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kmikiy/SpotMenu.git
#   cd SpotMenu
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kmikiy/SpotMenu and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kmikiy/SpotMenu(\\.git)?\\b" \\
  && ok "origin remote is kmikiy/SpotMenu" \\
  || miss "origin remote is not kmikiy/SpotMenu (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 48 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~18d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kmikiy/SpotMenu"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

SpotMenu is a native macOS menu bar application that displays your currently playing Spotify or Apple Music track with playback controls, built entirely in Swift and SwiftUI. It solves the problem of fragmented music player visibility by providing persistent, minimal access to track info and playback controls without leaving the menu bar, with support for global keyboard shortcuts and track liking via Spotify Web API. Modular feature-based architecture: SpotMenu/App/ contains entry points (AppDelegate.swift, SpotMenuApp.swift, UpdaterManager.swift), SpotMenu/Playback/ isolates music player logic (AppleMusicController.swift, SpotifyController.swift, PlaybackModel.swift, PlaybackView.swift) and authentication (SpotifyAuthManager.swift, SpotifyLoginView.swift). A separate website/ directory uses Astro for documentation/marketing. Assets live in SpotMenu/Assets.xcassets/ with separate icon sets for Spotify and Apple Music.

macOS users who frequently switch between Spotify and Apple Music and want quick access to playback controls and track info from the menu bar without opening the full music app. Developers contributing are typically Swift/SwiftUI enthusiasts interested in menu bar utilities and music player integrations.

Actively maintained but early-to-mid stage: the codebase is well-structured with proper Xcode project organization and includes CI/CD via GitHub Actions (deploy.yml), auto-updates via Sparkle, and Homebrew packaging. However, the small file count and limited visible test infrastructure suggest it's a focused utility rather than a battle-tested framework. Production-ready for end users but still undergoing active feature development.

Single maintainer (kmikiy) poses long-term sustainability risk. The codebase depends on external music player APIs (Spotify Web API, Apple Music scripting) which can change without notice. macOS version requirements (13+) mean compatibility work is needed annually. No visible test suite in the file list (no Tests/ directory) creates regression risk for refactors.

Recent activity includes Sparkle-based auto-updates (Sparkle/appcast.xml configured) and active CI/CD pipeline setup in .github/workflows/deploy.yml. The codebase appears to support both music players simultaneously with auto-detection logic. No visible open PRs or issue data in the file list, but the README indicates ongoing feature refinement around preferences, keyboard shortcuts, and player customization.

git clone https://github.com/kmikiy/SpotMenu.git && cd SpotMenu && open SpotMenu.xcodeproj — then build with Xcode (requires macOS 13+ and Xcode 15+). No external package manager setup needed beyond Swift Package Manager resolution (already cached in .xcworkspace/xcshareddata/swiftpm/Package.resolved).

Daily commands: Open SpotMenu.xcodeproj in Xcode 15+, select the SpotMenu scheme (SpotMenu.xcodeproj/xcshareddata/xcschemes/SpotMenu.xcscheme), and press Cmd+R to build and run. The app will launch as a menu bar application; no separate dev server needed.

• SpotMenu/App/SpotMenuApp.swift: Entry point for the SwiftUI app and menu bar initialization
• SpotMenu/Playback/PlaybackModel.swift: Core state management for current track, player selection, and playback status
• SpotMenu/Playback/SpotifyController.swift: Handles Spotify playback control, track fetching, and Web API integration for liking
• SpotMenu/Playback/AppleMusicController.swift: Manages Apple Music playback via system events and AppleScript-style control
• SpotMenu/Playback/PlaybackView.swift: SwiftUI view rendering the menu bar display and playback controls overlay
• SpotMenu/Playback/SpotifyAuthManager.swift: OAuth 2.0 authentication and token management for Spotify Web API access
• SpotMenu/App/UpdaterManager.swift: Integrates Sparkle framework for automatic app updates and version checking
• Sparkle/appcast.xml: Sparkle feed configuration that delivers update metadata to installed copies

Playback logic: edit SpotMenu/Playback/SpotifyController.swift or AppleMusicController.swift to change how tracks are fetched/controlled. UI appearance: SpotMenu/Playback/PlaybackView.swift and SliderView.swift control the menu bar overlay and controls. App lifecycle: SpotMenu/App/SpotMenuApp.swift and AppDelegate.swift handle startup and menu bar setup. Preferences: search for preferences-related code in Playback/ (likely in PlaybackModel.swift). Icons & assets: modify or add files in SpotMenu/Assets.xcassets/.

Spotify authentication: Requires a valid Redirect URI (com.github.kmikiy.spotmenu://callback) registered in the Spotify Developer Dashboard; missing this breaks track liking. Apple Music: Control via system events may differ across macOS versions; test on target OS (13+). Keychain storage: Spotify tokens are likely stored in macOS Keychain; ensure code signing is correct or Keychain access will fail. Menu bar quirks: NSStatusBar behavior differs on Apple Silicon vs Intel; test both. No test suite visible: changes to PlaybackModel.swift or controller logic lack automated regression checks.

• AppKit NSStatusBar — NSStatusBar is the macOS framework used to place SpotMenu in the menu bar; understanding its lifecycle, button behavior, and view positioning is essential for modifying the menu bar UI.
• OAuth 2.0 Authorization Code Flow — SpotifyAuthManager implements OAuth 2.0 to obtain user credentials for the Spotify Web API; understanding token exchange, refresh, and scope requests is critical for debugging authentication issues.
• REST API + Polling for State Sync — SpotifyController likely polls the Spotify Web API at intervals to fetch current playback state; understanding polling trade-offs (latency vs. rate limits) helps optimize refresh frequency.
• Custom URL Schemes (Deep Linking) — The Spotify redirect URI (com.github.kmikiy.spotmenu://callback) is a custom URL scheme; macOS routes this back to the app for OAuth token delivery. Essential for understanding the auth redirect flow.
• SwiftUI State Management (@Published, @ObservedObject) — PlaybackModel.swift uses Combine framework patterns to propagate playback changes to UI views; mastery of @Published properties and ObservedObject binding is needed for any UI modifications.
• Sparkle Auto-Update Framework — UpdaterManager.swift integrates Sparkle, which fetches appcast.xml to check for new versions; understanding versioning, delta updates, and security keys prevents deployment issues.
• AppleScript / System Events for Apple Music Control — AppleMusicController.swift likely uses AppleScript or NSAppleScript to control Music.app (no native API); understanding AppleScript syntax and event handling is needed for adding or fixing Apple Music features.

• Paw/Paw — Native macOS menu bar client for music streaming; similar UX and feature set (playback controls, track display) as a direct alternative.
• Spotify/spotify-web-api-js — Official Spotify Web API JavaScript SDK; relevant for understanding the Spotify API calls made by SpotifyAuthManager and SpotifyController.
• sparkle-project/Sparkle — The official Sparkle auto-update framework repository; essential reference for configuring appcast.xml and debugging update delivery.
• apple/swift-system — Swift system libraries for low-level macOS APIs; relevant for menu bar and event handling in AppDelegate and status bar integration.
• jordanbaird/Ice — Another popular macOS menu bar customization utility; shows alternative approaches to menu bar app architecture and preferences handling in Swift.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for SpotifyAuthManager.swift and SpotifyController.swift

The Spotify authentication and playback control logic is critical for core functionality but has no visible test coverage. SpotifyAuthManager handles token management and SpotifyController manages API interactions—both are prime candidates for unit tests to prevent regressions and make contributions safer.

• [ ] Create SpotMenu/Playback/Tests/SpotifyAuthManagerTests.swift with tests for token refresh, storage, and expiration
• [ ] Create SpotMenu/Playback/Tests/SpotifyControllerTests.swift with mock API responses for playback state, track info, and control commands
• [ ] Add test target to SpotMenu.xcodeproj targeting these test files
• [ ] Add GitHub Actions workflow .github/workflows/test.yml to run tests on PR

Extract PlaybackModel.swift into separate domain models (Track, PlaybackState, PlayerSource)

PlaybackModel.swift likely contains multiple responsibilities (data models, state management, business logic). This creates a maintenance burden and makes testing harder. Splitting into focused models improves code organization and reusability across Spotify and Apple Music controllers.

• [ ] Create SpotMenu/Playback/Models/Track.swift containing TrackModel struct with artist, title, album art properties
• [ ] Create SpotMenu/Playback/Models/PlaybackState.swift with enum (playing, paused, stopped) and duration tracking
• [ ] Create SpotMenu/Playback/Models/PlayerSource.swift with enum for source selection (spotify, appleMusic)
• [ ] Refactor PlaybackModel.swift to use these new models and remove duplicated property definitions
• [ ] Update SpotifyController.swift and AppleMusicController.swift imports to reference new model files

Add comprehensive keyboard shortcut configuration documentation in README

The repo has ShortcutPreferencesView.swift and KeyboardShortcuts+Names.swift indicating rich shortcut functionality, but the README only mentions 'Global hotkeys for playback control' without listing available shortcuts or how to customize them. This is a quick win that reduces support burden.

• [ ] Add 'Keyboard Shortcuts' section to README.md after the Features section
• [ ] Reference SpotMenu/Preferences/KeyboardShortcuts+Names.swift to list default shortcuts (e.g., play/pause, next, previous, like)
• [ ] Add screenshot or table showing the Shortcuts preferences pane from PreferencesView.swift
• [ ] Document how users can customize shortcuts via Preferences window
• [ ] Add troubleshooting note about macOS permissions for global hotkeys

• Add unit tests for SpotMenu/Playback/PlaybackModel.swift state transitions (currently no Tests/ directory visible) to verify track updates, player switching, and playback state changes are atomic.
• Document the Spotify OAuth 2.0 flow in a CONTRIBUTING.md file with concrete steps to set up a local test app on developer.spotify.com, since the README assumes familiarity with Spotify's dashboard.
• Implement keyboard shortcut binding UI in the preferences (likely missing from Playback/PlaybackView.swift) so users can visually see and rebind hotkeys instead of editing config files.

SpotMenu demonstrates a reasonably secure posture as a macOS native application with modern Swift/SwiftUI. The primary security concerns are: (1) dependency management practices for the website component with loose version constraints and unvetted third-party libraries, (2) lack of visible secure credential handling for Spotify API integration, and (3) absence of visible security configuration in the Astro setup. The Swift codebase itself appears sound with no obvious injection vulnerabilities, hardcoded secrets, or misconfigurations visible in the provided file structure. The application's use of native macOS APIs (Keychain for storage) and AppKit/SwiftUI is generally more secure than web-based alternatives. Recommended improvements: pin and audit dependencies, implement secure OAuth token storage, add security headers to the website, and document security practices in the repository.

• Medium · Outdated Astro Framework Version — website/package.json - astro dependency. The website uses Astro version ^5.16.11. While this is a relatively recent version, the caret (^) dependency constraint allows for automatic minor and patch updates that could introduce breaking changes or security issues without explicit review. Fix: Pin to a specific version (e.g., '5.16.11' without ^) or use a more conservative constraint (~5.16.0) to control updates. Regularly audit and test dependency updates.
• Medium · Unvetted Third-Party Dependencies in Website — website/package.json - multiple dependencies. The website package.json contains multiple third-party dependencies (canvas-confetti, @radix-ui/, @astrojs/, lucide-react) without documented security audit records. canvas-confetti in particular is not a security-critical package but adds external attack surface. Fix: Regularly run 'npm audit' and 'npm outdated'. Consider using npm's automated security scanning. Pin security-critical dependencies and review updates before applying.
• Low · React Security Configuration Not Visible — website/astro.config.mjs (content not provided), website/package.json. While React ^19.2.3 and react-dom ^19.2.3 are modern versions with security patches, the codebase doesn't show explicit security configuration for React (e.g., no visible Content Security Policy headers, XSS protection mechanisms in Astro config). Fix: Configure Astro with appropriate security headers (CSP, X-Frame-Options, etc.). Validate and sanitize any user input in React components. Use React's built-in protection against XSS.
• Low · No Visible Secrets Management for macOS App — SpotMenu/Playback/SpotifyAuthManager.swift, SpotMenu/Playback/SpotifyController.swift. The SpotMenu application integrates with Spotify Web API (visible from SpotifyAuthManager.swift and SpotifyController.swift). No .env files or secure credential storage patterns are visible in the provided structure, though this may exist but not be shown. Fix: Ensure Spotify API credentials and OAuth tokens are stored securely using macOS Keychain, not hardcoded or stored in plaintext. Use secure, time-limited tokens with proper scope restrictions.
• Low · Potential Information Disclosure via Public Repository — .github/workflows/deploy.yml. The repository is public with a deploy workflow (.github/workflows/deploy.yml). While this is common for open-source projects, ensure no secrets are exposed in CI/CD configurations or build artifacts. Fix: Audit the deploy workflow to ensure secrets are stored only in GitHub Secrets, never hardcoded. Ensure code signing certificates for macOS distribution are handled securely.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.