Apporter de petites modifications à une app qui tourne sur un service local en arrière-plan (démon)

## Avant de coder, lire les documents de conception et comprendre le rôle de chaque dossier Gardez des modifications de petite taille, alignez-vous sur l'architecture que le dépôt vise actuellement, et préférez les frontières démon/API documentées au comportement hérité d'une implémentation plus ancienne en cours de remplacement. Apprenez l'organisation par rôle, et non par nom de fichier : - Le backend contient le client en ligne de commande, le démon HTTP de bouclage, les services, le stockage en base de données embarquée, la logique de cycle de vie et de récupération (reaper), les adaptateurs d'exécution et d'espace de travail, ainsi que leurs tests. - Le front-end de bureau ou web est un superviseur léger et une surface d'interface reliée au démon via un client typé généré. N'y déplacez pas la logique du démon. - Le répertoire docs contient les notes d'architecture et d'état actuelles. Lisez-les avant de modifier le comportement du cycle de vie, du client, de l'agent, du stockage ou du démon. - Un répertoire de tests distinct contient les ressources externes de tests de fumée et de bout en bout, y compris les vérifications en conteneur d'installation neuve. - Les définitions de workflow CI font référence pour ce qui doit passer. Reproduisez ces commandes en local lorsque c'est possible. Lisez dans cet ordre avant une modification non triviale : le README de démarrage rapide, l'index de la documentation, le document d'architecture (modèle mental, organisation des paquets, frontières entre cycle de vie, session et service, et règles porteuses), le document d'état (ce qui est livré aujourd'hui sur la branche principale par rapport à ce qui est encore en cours), et le document du client (la forme qu'il doit prendre). Si le dépôt contient aussi des fichiers de pointeur de compatibilité destinés à d'autres outils d'agent, traitez-les comme des redirections vers l'unique guide canonique et non comme des jeux de règles distincts. Localisez les points d'entrée par responsabilité plutôt qu'en cherchant à l'aveugle : les implémentations de commandes, les contrôleurs HTTP et les DTO, les frontières de lecture/écriture des services, le vocabulaire du domaine, les contrats de ports, les requêtes et migrations de base de données, ainsi que le code de base de données généré résident chacun dans leur propre paquet. Suivez les motifs de commandes et de tests voisins avant d'introduire un nouveau style. ## Lancer les vérifications du projet et regarder à l'écran les changements visibles Utilisez les commandes agrégées propres au dépôt plutôt que d'en inventer d'improvisées. Depuis la racine du dépôt, elles couvrent généralement : le lint (tests du backend plus une version épinglée du linter), la vérification de types du front-end, la régénération du code d'accès à la base de données à partir des requêtes et du schéma, la régénération de la spécification d'API et des types du front-end, et un exécuteur de workflow local qui valide les définitions CI (ce qui peut nécessiter un socket de conteneur). Les vérifications au niveau des composants valent encore la peine d'être exécutées directement pendant les itérations : compilation, tests, tests avec détection de concurrence (race), analyse statique (vet) et démarrage du service pour le backend ; vérification de types et compilation pour le front-end. Lorsqu'une modification est visible dans l'interface, affichez-la réellement au sein de la session à l'aide de la commande de prévisualisation du projet et regardez le résultat. Ne vous contentez pas de décrire à quoi la modification devrait ressembler. ## Recommander seulement l'app de bureau à mise à jour automatique pour l'installation Lorsqu'un projet dispose de plusieurs chemins d'installation, un seul est canonique, et les recommandations doivent y renvoyer. - La version de bureau à mise à jour automatique publiée via les releases est le chemin d'installation canonique. Orientez-y les utilisateurs en premier. - Un ancien canal de gestionnaire de paquets peut encore fonctionner tout en n'étant plus recommandé. Si une version finale a été publiée et que le paquet est gelé, il ne reçoit plus aucune mise à jour. Il ne reste une porte d'entrée que pour les utilisateurs qui ont déjà la commande dans leur PATH, où son lancement télécharge et ouvre la version canonique. - N'ajoutez pas de fonctionnalités, de documentation ni de parcours qui présentent un ancien canal gelé comme la manière prévue d'installer le produit. ## Changer seulement ce que demande la tâche et suivre le découpage actuel du code - Faites en sorte que chaque modification soit directement liée à la tâche. Évitez les nettoyages au passage, les renommages massifs, les remaniements de formatage, les abstractions spéculatives et les refactorisations architecturales, sauf si la tâche les demande explicitement. - Respectez les frontières de paquets existantes. Le code du client appelle les routes HTTP du démon via les utilitaires client partagés ; il ne doit pas ouvrir la base de données, lancer des environnements d'exécution, ni appeler directement les adaptateurs. - Gardez chaque commande dans son fichier de commande approprié et testez-la par tableau de cas, dans le style des tests de commandes voisins. - Recopiez à l'identique les DTO de requête et de réponse côté client au lieu d'importer les paquets de contrôleurs du serveur dans le code du client, sauf si cette dépendance est déjà établie dans le paquet. - Renvoyez les erreurs d'utilisation via le type d'erreur d'utilisation dédié, afin qu'un mauvais usage du client se termine avec son propre code de statut (par exemple 2), tandis que les défaillances d'exécution et du démon se terminent avec le code d'échec général (par exemple 1). - Préservez les enveloppes d'erreur de l'API et les identifiants de requête lorsque vous remontez les erreurs du démon, au lieu de les aplatir en simples chaînes de caractères. - Passez un contexte d'annulation/échéance comme premier argument de toute fonction qui effectue des entrées/sorties ou un travail bloquant. - N'ajoutez pas d'abstractions pour des cas d'usage ponctuels. N'introduisez un utilitaire que lorsqu'il supprime une duplication entre de véritables sites d'appel. - Les tests doivent couvrir le comportement visible par l'utilisateur et la frontière modifiée : le cas nominal, la validation et les arguments manquants, les enveloppes d'erreur du démon, et tout parcours de confirmation destructive. ## Ne pas modifier ni ajouter d'accès réseau au démon - L'écouteur principal du démon reste lié à l'adresse de bouclage et reste sans authentification. Ne changez pas son hôte de liaison et ne lui ajoutez pas d'authentification. - Le démon peut exécuter un second écouteur, activable à la demande, qui se lie à toutes les interfaces pour l'accès au réseau local, mais uniquement lorsqu'il est explicitement activé, uniquement derrière l'intergiciel d'authentification par mot de passe de type bearer, et uniquement pour servir l'API de l'application. Cet écouteur ne doit jamais servir les routes de contrôle réservées au bouclage telles que l'arrêt, la télémétrie et le contrôle à distance. - Lorsqu'un tel écouteur est en clair et destiné uniquement à un réseau domestique de confiance, il s'agit d'une décision délibérée et documentée, consignée dans un enregistrement de décision d'architecture. Lisez cet enregistrement avant d'y toucher. - N'ajoutez aucune autre liaison exposée au réseau. - Le client en ligne de commande reste un client léger. Ne portez pas d'ancien comportement exécuté dans le même processus qui contourne les routes HTTP du démon. ## Protéger les données enregistrées et ne pas modifier à la main le code de base de données généré - Ne stockez pas d'état dérivé ou destiné à l'affichage. Déduisez l'état à partir de faits durables (état d'activité, indicateur de terminaison, faits relatifs aux pull requests, aux vérifications et aux commentaires) au moment de la lecture par le service. - Ne considérez pas une sonde d'exécution en échec ou au résultat inconnu comme la preuve qu'une session est morte. - Ne supprimez pas de force les worktrees enregistrés qui comportent encore des modifications non validées. - Ne modifiez pas les migrations qui ont déjà été fusionnées. Ajoutez plutôt une nouvelle migration. - Ne modifiez pas à la main le code de base de données généré. Changez les requêtes ou les migrations et relancez le générateur. - Les événements de changement circulent des déclencheurs de base de données vers le journal des changements. N'ajoutez pas de chemin d'émission de changements manuel et parallèle depuis les méthodes du store, à moins que l'architecture ne change explicitement. - Surveillez la dérive entre les artefacts d'API générés et les DTO écrits à la main. Les formes de réponse des contrôleurs résident dans un unique fichier de DTO, et des tests peuvent vérifier la compatibilité de protocole entre le client et les couches HTTP. - N'ajoutez pas d'appels réseau aux tests, sauf si le paquet dispose déjà d'un motif d'intégration ou de bout en bout pour cela. Préférez les serveurs de test exécutés dans le même processus, les doublures et les dépendances injectées. - Ne validez pas l'état d'exécution local, les données du démon, les worktrees temporaires, les sorties de compilation ni les identifiants d'authentification. - Conservez tout l'état de l'application sous l'unique répertoire d'état dédié, redéfinissable via les variables d'environnement documentées. Le répertoire de données du démon, le fichier de processus en cours d'exécution, les worktrees et les données utilisateur de l'enveloppe de bureau (cache du navigateur, cookies, stockage local et de session, vidages de plantage) doivent tous se résoudre sous ce répertoire. Ne lisez ni n'écrivez jamais dans l'emplacement de données applicatives par défaut du système d'exploitation. Le point d'entrée de bureau fixe le chemin des données utilisateur de l'enveloppe sur ce répertoire ; ne supprimez pas cette redéfinition et ne vous fiez pas au chemin par défaut. ## Changer l'API dans les fichiers écrits à la main, puis régénérer sa description L'API du démon est définie d'abord par le code. La spécification OpenAPI et les types du front-end sont des artefacts générés : modifiez donc la source et régénérez, plutôt que de modifier les sorties. - Modifiez le fichier de DTO qui définit les formes de requête et de réponse. - Modifiez le registre d'opérations du constructeur de spécification, en ajoutant une entrée de nom de schéma pour tout type nouvellement nommé. - Régénérez avec la commande d'API agrégée du dépôt, qui exécute successivement la génération de la spécification puis celle des types. - Vérifiez avec les tests du paquet HTTP du serveur ; ils couvrent la dérive de la spécification et la parité entre les routes et la spécification. Ils ne couvrent pas les types générés du front-end, qu'une tâche CI de dérive distincte contrôle. - Validez la spécification générée et les types générés du front-end en même temps que les modifications de la source. La CI régénère les deux et échoue si les versions validées sont obsolètes. - Les DTO du client recopiés à la main restent une frontière manuelle délibérée et ne sont pas générés. ## Ouvrir une seule demande de modification (pull request) par sujet - Créez votre branche à partir de la branche principale, sauf si vous poursuivez explicitement une pull request existante. - Gardez un seul sujet par pull request. Si un travail distinct vous est demandé, créez une branche et une pull request distinctes. - Utilisez les préfixes de message de commit conventionnels tels que feat, fix, docs, test et chore. - Expliquez les omissions intentionnelles dans le corps de la pull request, en particulier lorsqu'une implémentation antérieure prenait en charge plus de comportements que le domaine de la réécriture actuelle. - Exécutez d'abord les tests pertinents les plus restreints, puis les commandes du dépôt et de la CI correspondant à la zone que vous avez touchée.