Meshtastic-Apple/.github/copilot-instructions.md

# GitHub Copilot Instructions for Meshtastic-Apple

## Project Overview

Meshtastic-Apple is a SwiftUI client for iOS, iPadOS, and macOS (via Mac Catalyst) that communicates with Meshtastic LoRa mesh radio devices over BLE, TCP, and serial transports. The app handles mesh networking, messaging, node management, mapping, and radio configuration.

## Architecture

### App Entry Point
- `Meshtastic/MeshtasticApp.swift` — `@main` `App` struct; initialises `AppState`, `Router`, `AccessoryManager`, `PersistenceController`, and Datadog observability.
- `Meshtastic/MeshtasticAppDelegate.swift` — `UIApplicationDelegate` for SiriKit intent handling (CarPlay messaging via `INSendMessageIntent` etc.).

### State & Navigation
- `Router` (`Meshtastic/Router/Router.swift`) is a `@MainActor` `ObservableObject` that owns a `NavigationState` struct and drives tab/deep-link routing.
- `NavigationState` and the per-tab enums (`MessagesNavigationState`, `MapNavigationState`, `SettingsNavigationState`) live in `Meshtastic/Router/NavigationState.swift`.
- Deep links use the `meshtastic:///` URL scheme (see README for the full table). `Router.route(url:)` dispatches them.
- `AppState` wraps `Router` and is passed as an `@EnvironmentObject` throughout the view hierarchy.

### Connectivity
- `AccessoryManager` (`Meshtastic/Accessory/Accessory Manager/`) is the central BLE/TCP/serial manager. It is split across extension files:
  - `AccessoryManager+Discovery.swift` — device scanning & connection
  - `AccessoryManager+Connect.swift` — connection lifecycle
  - `AccessoryManager+ToRadio.swift` — packets sent to the radio (including `sendWaypoint`)
  - `AccessoryManager+FromRadio.swift` — packets received from the radio
  - `AccessoryManager+Position.swift` — GPS position sharing
  - `AccessoryManager+MQTT.swift` — MQTT proxy
  - `AccessoryManager+TAK.swift` — TAK/CoT integration
- Transport protocols are in `Meshtastic/Accessory/Transports/`.

### Persistence
- Core Data is the sole persistence layer. Use `PersistenceController.shared` for the container; prefer `viewContext` for reads and a background context for writes.
- The model lives in `Meshtastic/Meshtastic.xcdatamodeld` (55+ versioned migrations — always add a new model version for schema changes).
- Query helpers: `QueryCoreData.swift` (`getNodeInfo`, etc.); update helpers: `UpdateCoreData.swift`.

### Protobufs
- The `MeshtasticProtobufs` Swift Package (`MeshtasticProtobufs/Package.swift`) wraps the protobuf-generated Swift sources.
- Regenerate with `./scripts/gen_protos.sh` whenever `protobufs/` submodule changes, then build and commit.

## Code Style

### Language & Frameworks
- **Swift only.** No Objective-C.
- **SwiftUI** for all UI. Do not use UIKit directly unless unavoidable (e.g., `UIApplicationDelegateAdaptor`).
- **SF Symbols** for all icons — never embed image assets for icons.
- **Core Data** for all persistence — do not introduce SQLite, Realm, or other persistence libraries.
- **OSLog / `Logger`** for all logging — never use `print()`. The project's SwiftLint config enforces this with a custom `disable_print` rule. Use the typed loggers defined in `Meshtastic/Extensions/Logger.swift`:
  - `Logger.admin`, `Logger.data`, `Logger.mesh`, `Logger.mqtt`, `Logger.radio`, `Logger.services`, `Logger.statistics`, `Logger.transport`, `Logger.tak`

### Platform Support
- Target the **last two major OS versions** of iOS, iPadOS, and macOS (Mac Catalyst).
- Guard iOS-only APIs with `#if !targetEnvironment(macCatalyst)` or `#if canImport(UIKit)`.

### SwiftLint
- SwiftLint is enforced on every commit via `scripts/setup-hooks.sh`. Ensure no new errors or warnings are introduced.
- Key limits (see `.swiftlint.yml`): line length 400, file length warning 3500, type body length warning 400, function body length warning 200, cyclomatic complexity warning 60.
- Disabled rules: `operator_whitespace`, `multiple_closures_with_trailing_closure`, `todo`, `trailing_whitespace`.

### Formatting Conventions
- Indent with **tabs**.
- Opening braces on the same line as the declaration.
- `// MARK: -` comments to separate logical sections within a file.
- `// MARK: FileName` or file-level copyright comment at the top of files.
- Extensions grouped by functionality in separate files (e.g., `AccessoryManager+ToRadio.swift`).
- Prefer `guard` for early exit; avoid deeply nested `if` blocks.
- Use trailing closure syntax; omit argument labels where idiomatic.

### Naming
- Types: `UpperCamelCase`, max 60 chars (warning at 60, error at 70).
- Variables/functions: `lowerCamelCase`, min 1 char, max 60 chars.
- Enum raw values that map to URL path segments use `lowerCamelCase` (e.g., `SettingsNavigationState.appSettings`).
- File names match the primary type they define.

### Concurrency
- `Router` is `@MainActor`; all property reads and method calls must be `await`-ed in async contexts and tests.
- Prefer `async/await` over callback-based APIs for new code.
- Use `Task` for fire-and-forget async work; propagate cancellation via `Task.checkCancellation()`.

## Testing

- Test target: `MeshtasticTests/`.
- Use **Swift Testing** (`import Testing`, `@Suite`, `@Test`, `#expect`, `#require`) for new tests. XCTest is used in some legacy test files.
- Tests are run via Xcode — there is no Makefile or CLI test runner.
- Ensure all existing tests pass before submitting a PR.
- Write tests for new features and bug fixes.

## Git & PR Workflow

- Branch from and target **`main`** (trunk-based development).
- Use **rebase** instead of merge to incorporate upstream changes (`git config pull.rebase true`).
- Keep branches small and focused on a single task.
- Commit messages: imperative mood subject line (e.g., `Fix crash when BLE device disconnects`). Explain *what* and *why* in the body.
- PR description must answer: what changed, why it changed, how it was tested, and include screenshots/videos when UI is affected (see `.github/pull_request_template.md`).
- Self-review code before requesting review; comment complex areas.

## Deep Links

The app registers the `meshtastic:///` URL scheme. Use `Router.route(url:)` to handle incoming URLs. When adding a new deep link:
1. Add a case to the appropriate `*NavigationState` enum in `NavigationState.swift`.
2. Update `Router`'s routing helpers.
3. Document the URL in the README.

## Adding or Updating Protobufs

1. Update the `protobufs/` git submodule.
2. Run `./scripts/gen_protos.sh`.
3. Build, test, and commit the generated changes.

## Core Data Schema Changes

1. Create a new model version in `Meshtastic.xcdatamodeld`.
2. Set it as the current version.
3. Add a migration policy if required (lightweight migration is preferred when possible).

## CI

CI is handled by Xcode Cloud via `ci_scripts/ci_pre_xcodebuild.sh`. Do not modify CI scripts without understanding the Xcode Cloud build environment.