WatchOsm/AGENTS.md

AGENTS.md — WatchOsm

Application Wear OS 5 qui suit la navigation initiée par OsmAnd+ (Android). Documentation d'architecture : documentation/architecture.md + diagrammes PlantUML dans documentation/puml/.

Langues

• Commentaires, messages de commit, documentation : français.
• Identifiants de code en anglais (conventions Kotlin/Android classiques).

Build et vérification — chaîne validée le 07/10/2026

Toutes les commandes suivantes sont vertes sur cette machine :

./gradlew :wear:assembleDebug        # APK debug
./gradlew :wear:testDebugUnitTest    # 11 tests unitaires (parseur)
./gradlew :wear:lint                 # lint Android
java -jar /tmp/opencode/plantuml.jar -checkonly documentation/puml/*.puml

• Toolchain : Gradle wrapper 8.11.1, AGP 8.9.2, Kotlin 2.1.20 (+ plugin org.jetbrains.kotlin.plugin.compose ; ne PAS ajouter composeOptions.kotlinCompilerExtensionVersion, compilateur Compose intégré au plugin Kotlin 2.x).
• Android SDK : installé dans ~/Android/Sdk (cmdline-tools, platforms;android-35, build-tools;35.0.0). local.properties (non versionné) pointe dessus. Si le SDK manque : voir l'historique git, les étapes sdkmanager sont dans le commit d'initialisation.
• JDK complet requis : le JDK système est une JRE sans javac, ce qui fait échouer Gradle 8.11 sur les tâches Java. ~/.gradle/gradle.properties (hors dépôt) définit org.gradle.java.home=/home/aston/tools/jdk-21.0.12.1+1. Si ce chemin disparaît, télécharger Temurin 21 via https://api.adoptium.net/v3/binary/latest/21/ga/linux/x64/jdk/hotspot/normal/eclipse.
• Épinglages à ne pas bouger sans raisons :
  • AGP < 8.9.2 → son lint plante (UAST vs Kotlin 2.1, KaCallableMemberCall). Ne pas revenir à 8.7.x.
  • Wear Compose 1.6.2 : la 1.7.x exige AGP 9.1 + compileSdk 37.
  • core-ktx / lifecycle / compose-bom : versions inférieures aux dernières car les suivantes demandent compileSdk ≥ 36. Monter compileSdk/AGP est un chantier à part entière (AGP 9 change le DSL).
• lint { disable += "RememberInComposition" } dans wear/build.gradle.kts : détecteur en crash avec cette paire AGP/Kotlin, laisser tel quel.

Diagrammes UML

• Sources uniquement en PlantUML (.puml) dans documentation/puml/.
• PlantUML n'est pas installé ; pour valider la syntaxe localement : java -jar /tmp/opencode/plantuml.jar -checkonly documentation/puml/*.puml (le jar, téléchargé dans /tmp/opencode/, n'est pas versionné ; le retirer si absent, il se re-télécharge depuis https://github.com/plantuml/plantuml/releases).
• Toute évolution d'architecture met à jour les diagrammes dans le même commit.

Structure

• Module unique wear/ (application montre autonome). Le module phone/ (compagnon Android : listener renforcé + API AIDL OsmAnd + Data Layer) est prévu en phase 2, pas encore créé.
• Package : fr.barteam.watchosm.
• Le pont vers OsmAnd repose sur le bridging des notifications vers la montre ; le parseur de texte (OsmAndNotificationParser) est le seul point fragile face aux mises à jour d'OsmAnd — toute régression de format se corrige là, avec un test dans OsmAndNotificationParserTest.