Luma/AGENTS.md

Repository Guidelines

Luma is an XMPP client for iOS, iPadOS, macOS, and watchOS, built with SwiftUI and the Martin / MartinOMEMO libraries. The Xcode project is generated from project.yml by XcodeGen — never edit Luma.xcodeproj directly.

Project Structure

• Sources/App/ — iOS/macOS app entry point (LumaApp.swift).
• Sources/Shared/ — shared code:
  • Models/ — value types and pure policy enums (ChatMessage, ArchiveSyncPagination, ChatTypingPolicy, …).
  • UI/ — SwiftUI views and components.
  • XMPP/ — XMPPService (MAM/OMEMO/MUC), LumaCallEngine, OMEMO store.
  • Persistence/ — ChatArchive (JSON snapshot), preferences.
  • Services/, Security/ — media, notifications, credentials.
• Sources/Watch/ — single-target watchOS app.
• Tests/ — XCTest unit tests.
• Resources/, Config/, Brand/, Docs/ — assets, plists/entitlements, icons, architecture/security docs.

Build, Test & Development

• make project — regenerate Luma.xcodeproj from project.yml (requires brew install xcodegen).
• make open — regenerate and open Xcode.
• make verify — run Scripts/verify.sh: grep-based structural invariants plus an optional simulator build.
• make clean — remove the generated project and DerivedData.
• xcodebuild test -project Luma.xcodeproj -scheme Luma \ -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max' — build and run the test suite.

Coding Style

• Swift 5.9; 4-space indentation (set in project.yml).
• UI-facing state is @MainActor (AppModel, XMPPService); keep heavy work (OMEMO decryption, media, persistence) off the main actor.
• Prefer small, pure value types and unit-testable policy enums over inline branching.
• UI strings are Russian; identifiers and code comments are English.
• No formatter/linter; Scripts/verify.sh is the guard — keep its greps in sync when you change constants or symbols.

Testing

• XCTest with @testable import Luma; one file per model/policy (e.g., ArchiveSyncPaginationTests.swift), methods named test....
• Unit-test pure logic (policies, pagination, checkpoints); network/UI flows are verified manually.
• When a policy constant changes, update the matching Tests/* assertions and the Scripts/verify.sh guard in the same commit.

Commit & Pull Request

• Short, imperative, English subject lines (see git log: "mam fixes", "fix errors and warnings").
• CI (.github/workflows/ios.yml) runs xcodebuild test on push to main/develop and on PRs to main; PRs must keep it green.
• Update README.md / Docs/* whenever behaviour or architecture changes.