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 (ArchiveSyncPagination, ChatTypingPolicy, …) plus the SwiftData @Model classes (ChatMessage, Conversation).
  • UI/ — SwiftUI views; chat/contact lists read SwiftData through @Query (MainTabView, ChatView, ForwardMessageView); the main screen is Telegram-style: an iOS native TabView tab bar (Контакты/Звонки/Чаты/Настройки) with inline search fields above the lists, and a macOS Telegram Desktop-style split view (MainSplitView: sidebar with menu/search/list plus a chat detail pane).
  • XMPP/ — XMPPService (MAM/OMEMO/MUC), LumaCallEngine, OMEMO store, LumaOMEMO2Module (urn:xmpp:omemo:2 wire format: AES-256-CBC + HMAC payload, SCE envelope, device/bundle PEP nodes — shares the Double Ratchet sessions with the legacy module), SASLprep (RFC 4013), SCRAM-SHA-512 mechanism, SASL failure observer/messages.
  • Persistence/ — ArchiveStore (per-account SwiftData container), ArchiveMetadataRecord (durable MAM checkpoint metadata), LegacyArchiveImporter (one-time legacy JSON snapshot migration), 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.