|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to coding agents when working with code in this repository. |
| 4 | + |
| 5 | +# Leader Key Development Guide |
| 6 | + |
| 7 | +## Build & Test Commands |
| 8 | + |
| 9 | +- Build and run: `xcodebuild -scheme "Leader Key" -configuration Debug build` |
| 10 | +- Run all tests: `xcodebuild -scheme "Leader Key" -testPlan "TestPlan" test` |
| 11 | +- Run single test: `xcodebuild -scheme "Leader Key" -testPlan "TestPlan" -only-testing:Leader KeyTests/UserConfigTests/testInitializesWithDefaults test` |
| 12 | +- Bump version: `bin/bump` |
| 13 | +- Create release: `bin/release` |
| 14 | + |
| 15 | +## Architecture Overview |
| 16 | + |
| 17 | +Leader Key is a macOS application that provides customizable keyboard shortcuts. The core architecture consists of: |
| 18 | + |
| 19 | +**Key Components:** |
| 20 | + |
| 21 | +- `AppDelegate`: Application lifecycle, global shortcuts registration, update management |
| 22 | +- `Controller`: Central event handling, manages key sequences and window display |
| 23 | +- `UserConfig`: JSON configuration management with validation |
| 24 | +- `UserState`: Tracks navigation through key sequences |
| 25 | +- `MainWindow`: Base class for theme windows |
| 26 | + |
| 27 | +**Theme System:** |
| 28 | + |
| 29 | +- Themes inherit from `MainWindow` and implement `draw()` method |
| 30 | +- Available themes: MysteryBox, Mini, Breadcrumbs, ForTheHorde, Cheater |
| 31 | +- Each theme provides different visual representations of shortcuts |
| 32 | + |
| 33 | +**Configuration Flow:** |
| 34 | + |
| 35 | +- Config stored at `~/Library/Application Support/Leader Key/config.json` |
| 36 | +- `FileMonitor` watches for changes and triggers reload |
| 37 | +- `ConfigValidator` ensures no key conflicts |
| 38 | +- Actions support: applications, URLs, commands, folders |
| 39 | + |
| 40 | +**Testing Architecture:** |
| 41 | + |
| 42 | +- Uses XCTest with custom `TestAlertManager` for UI testing |
| 43 | +- Tests use isolated UserDefaults and temporary directories |
| 44 | +- Focus on configuration validation and state management |
| 45 | + |
| 46 | +## Code Style Guidelines |
| 47 | + |
| 48 | +- **Imports**: Group Foundation/AppKit imports first, then third-party libraries (Combine, Defaults) |
| 49 | +- **Naming**: Use descriptive camelCase for variables/functions, PascalCase for types |
| 50 | +- **Types**: Use explicit type annotations for public properties and parameters |
| 51 | +- **Error Handling**: Use appropriate error handling with do/catch blocks and alerts |
| 52 | +- **Extensions**: Create extensions for additional functionality on existing types |
| 53 | +- **State Management**: Use @Published and ObservableObject for reactive UI updates |
| 54 | +- **Testing**: Create separate test cases with descriptive names, use XCTAssert\* methods |
| 55 | +- **Access Control**: Use appropriate access modifiers (private, fileprivate, internal) |
| 56 | +- **Documentation**: Use comments for complex logic or non-obvious implementations |
| 57 | + |
| 58 | +Follow Swift idioms and default formatting (4-space indentation, spaces around operators). |
| 59 | + |
0 commit comments