mirror of
https://github.com/home-assistant/iOS.git
synced 2026-06-20 01:35:23 -05:00
1221c6f317
## Summary Updates the AI agent instruction files so that AI coding assistants prefer **Swift Concurrency** (`async/await`, `Task`, actors, structured concurrency) for new asynchronous code and **avoid introducing new PromiseKit usage**. PromiseKit remains a legacy dependency in parts of `HomeAssistantAPI` (`HAAPI.swift`), so the guidance also tells agents not to assume a full migration and to convert PromiseKit to `async/await` where practical when they touch that code. Files updated: - `AGENTS.md` — added a **Concurrency** subsection under Common Patterns and a note in the Networking section. - `.github/copilot-instructions.md` — added a **Concurrency** subsection under Swift Conventions and clarified the existing PromiseKit/HAKit notes. (`CLAUDE.md` is a symlink to this file, so it's covered too.) - `.cursorrules` — added a concurrency key rule and a code-style bullet. These are documentation-only changes to AI agent guidance; no app code is affected. ## Screenshots N/A — documentation/instruction files only, no user-facing change. ## Link to pull request in Documentation repository Documentation: home-assistant/companion.home-assistant# ## Any other notes No-op for the build/tests — only Markdown instruction files for AI agents changed. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
55 lines
2.1 KiB
Plaintext
55 lines
2.1 KiB
Plaintext
# Cursor AI Rules for Home Assistant iOS
|
|
|
|
See [AGENTS.md](AGENTS.md) for the full AI agent reference.
|
|
|
|
## Quick Reference
|
|
|
|
### Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
bundle install
|
|
bundle exec pod install --repo-update
|
|
|
|
# Fix lint issues (run before committing)
|
|
bundle exec fastlane autocorrect
|
|
|
|
# Check lint without fixing
|
|
bundle exec fastlane lint
|
|
|
|
# Run tests
|
|
bundle exec fastlane test
|
|
```
|
|
|
|
### Key Rules
|
|
|
|
1. **Dependency Injection**: This project uses the "World" pattern (Point-Free). A global `Current` variable (`AppEnvironment`) holds all dependencies. Never assign to `Current.*` outside test code.
|
|
2. **Localization**: Add strings to `Sources/App/Resources/en.lproj/Localizable.strings`. SwiftGen generates type-safe `L10n` accessors on build.
|
|
3. **SF Symbols**: Use `SFSafeSymbols` (`Image(systemSymbol: .house)`) not string-based APIs.
|
|
4. **CocoaPods only**: No Swift Package Manager. Dependencies via `Podfile`.
|
|
5. **Workspace**: Always use `HomeAssistant.xcworkspace`.
|
|
6. **Concurrency**: Prefer Swift Concurrency (`async/await`, `Task`, actors) for new async code. Do not introduce new **PromiseKit** code — it's a legacy dependency being phased out (some of `HomeAssistantAPI` still uses it). Migrate PromiseKit to `async/await` where practical when you touch it.
|
|
|
|
### Architecture
|
|
|
|
- The app is a companion to the Home Assistant web UI displayed in a `WKWebView`
|
|
- Native features: notifications, sensors, location, widgets, CarPlay, Apple Watch
|
|
- Platforms: iOS, watchOS, macOS (Catalyst), CarPlay
|
|
- Shared code in `Sources/Shared/`, platform-specific in `Sources/App/`, `Sources/Watch/`, etc.
|
|
|
|
### Code Style
|
|
|
|
- Max line width: 120 characters
|
|
- Wrap arguments/parameters: `before-first`
|
|
- `self` only in initializers
|
|
- No `force_cast` or `force_try`
|
|
- Use `guard` for early returns
|
|
- SwiftUI preferred for new UI, `@MainActor` on view models
|
|
- Prefer `async/await` over PromiseKit for asynchronous code
|
|
|
|
### Testing
|
|
|
|
- Mock dependencies by overriding `Current.*` in test setup
|
|
- Tests in `Tests/` directory mirror source structure
|
|
- Use `Sources/SharedTesting/` for shared test utilities
|