diff --git a/AGENTS.md b/AGENTS.md index 0c72669..07c49ae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,9 +14,10 @@ ## 2. Stack technique ### Langage et dépendances -- **Python** : ≥ 3.13 (actuellement 3.14 dans `.venv/`) +- **Python** : ≥ 3.13.5 (actuellement 3.14 dans `.venv/`) - **Dépendances principales** : - `pydantic>=2.0`, `pydantic-settings`, `icalendar`, `caldav`, `slixmpp`, `pronotepy`, `feedparser`, `requests`, `httpx` + `pydantic>=2.0`, `pydantic-settings`, `icalendar`, `caldav`, `slixmpp`, `pronotepy`, + `feedparser`, `beautifulsoup4`, `requests`, `httpx`, `openai` ### Outils de développement - **Linter** : `ruff` (longueur de ligne : 100) @@ -36,6 +37,7 @@ ``` pronote_sync/ ├── config/ # Configuration et paramètres +├── errors.py # Hiérarchie canonique des erreurs du pipeline ├── models/ # Modèles de données (Pydantic v2) ├── sources/ # Connecteurs (Pronote, iCal, etc.) ├── sync/ # Logique de synchronisation @@ -110,6 +112,8 @@ pronote-sync --dry-run ### Architecture - **Injection de dépendances** : Utiliser `typing.Protocol` et une **composition root** dans `pipeline/run.py`. **Interdiction** des singletons globaux. +- **Erreurs** : Conserver une seule hiérarchie dans `pronote_sync/errors.py` ; ne pas créer de + doublon dans `pipeline/steps/errors.py`. ### Style - **Longueur de ligne** : 100 caractères maximum (configuré dans `ruff`). @@ -123,12 +127,30 @@ pronote-sync --dry-run - **Idempotence** : Deux exécutions identiques sans changement externe doivent produire le **même résultat**. - **Mode dégradé** : - Si l'IA échoue → retourner un message **sans synthèse**. - - Si `pronotepy` échoue → fallback vers le parsing **iCal**. - - Si tout échoue → lever une **erreur explicite**. + - En mode source `auto`, essayer iCal puis utiliser `pronotepy` uniquement si iCal lève une + exception. + - En mode source explicite (`ical` ou `pronotepy`), ne pas changer silencieusement de source. + - En mode `auto`, si iCal et `pronotepy` échouent → lever une erreur critique explicite. + - Une liste vide est un succès valide ; elle ne doit pas être assimilée à une panne. + +### Contrat des sources Pronote +- `PRONOTE_URL` (connexion API) et `PRONOTE_ICAL_URL` (flux iCal sensible) sont deux paramètres + distincts ; ne pas déduire l'un de l'autre. +- Le compte actuellement visé est un compte parent : utiliser + `pronotepy.ParentClient(pronote_url, username, password, ent=ent_function)`. +- Résoudre le slug `PRONOTE_ENT` vers une fonction de `pronotepy.ent` au moyen d'une liste fermée. +- Exposer séparément les cours et les devoirs dans le client ; filtrer les devoirs `pronotepy` sur + la date cible. +- Les récupérations critiques agenda/devoirs propagent une erreur expurgée ; seuls les messages et + informations non critiques peuvent se dégrader en liste vide avec warning. +- Réutiliser un téléchargement/parsing iCal pour l'agenda et les devoirs pendant un même run, sans + cache global ni persistant. ### Documentation (docstrings) - **Obligatoire** : **Toute** fonction, méthode et classe publique doit avoir une docstring. - **Format** : Utiliser le format **Sphinx/reST** (pas Google ou NumPy) pour une compatibilité native avec Sphinx. +- **Priorité** : Les blocs historiques de `GUIDE_DEV_PYTHON.md` utilisant `Args:`/`Returns:` sont + illustratifs ; le format Sphinx/reST défini ici prévaut pour le code de production. - **Contenu** : - Une ligne de résumé courte (une phrase). - Une description étendue optionnelle. @@ -157,6 +179,11 @@ def fetch_ical(url: str) -> str: ### Règles absolues - **Aucun secret en clair** : Ni dans le code, ni dans les logs, ni dans les erreurs, ni dans les fixtures. - **Masquage** : Utiliser systématiquement `redact_url()`, `redact_secrets()`, et `redact_exception()` depuis `utils/redaction.py`. +- **Chaînage d'exceptions** : Ne jamais conserver comme `__cause__` ou `__context__` une exception + externe brute susceptible de contenir un secret. Journaliser la version expurgée puis utiliser + `raise ... from None`, ou chaîner une cause elle-même expurgée. +- **Tests de non-fuite** : Vérifier les messages, les logs, `__cause__`, `__context__` et le + traceback complet avec des sentinelles distinctes pour chaque secret. ### Bonnes pratiques - **Types sécurisés** : Les mots de passe et clés API doivent utiliser `pydantic.SecretStr`. @@ -225,14 +252,17 @@ Les rôles d'agents disponibles pour ce projet sont les suivants : ## 10. Workflow de modification -1. Lire la demande, [`TODO.md`](./TODO.md), `git status` et les fichiers concernés. +1. Lire la demande, [`TODO.md`](./TODO.md), les sections pertinentes de + [`GUIDE_DEV_PYTHON.md`](./GUIDE_DEV_PYTHON.md), `git status` et les fichiers concernés. 2. Préserver les changements existants de l'utilisateur. 3. Pour une correction, reproduire d'abord le défaut avec un test automatisé lorsque c'est raisonnable. -4. Faire une modification étroite et cohérente, en respectant les conventions du projet (idempotence, mode dégradé, repli iCal/pronotepy). +4. Faire une modification étroite et cohérente, en respectant les conventions du projet + (idempotence, modes explicites stricts et repli iCal → `pronotepy` uniquement en mode `auto`). 5. Faire vérifier le comportement par `@verifier` (ruff, mypy, pytest, bandit) et les cas d'erreur, notamment : - Succès de la synchronisation Pronote → CalDAV/XMPP. - - Repli vers iCal en cas d'échec de `pronotepy`. - - Gestion des erreurs explicites. + - Repli d'iCal vers `pronotepy` en mode `auto`, sans repli dans les modes explicites. + - Distinction entre résultat vide et échec des sources. + - Gestion des erreurs explicites sans fuite dans les causes ou tracebacks. 6. Mettre à jour la documentation et les exemples dans le même changement si leur comportement public évolue. 7. Cocher dans [`TODO.md`](./TODO.md) uniquement les éléments entièrement réalisés et validés. 8. Terminer avec un *handoff* concis : fichiers modifiés, validations exécutées, limites et prochaine étape. @@ -277,7 +307,8 @@ Les rôles d'agents disponibles pour ce projet sont les suivants : Un changement est considéré comme **terminé** lorsque : -- Le cas nominal et les échecs pertinents sont testés (ex. : synchronisation réussie, repli iCal, erreurs explicites). +- Le cas nominal et les échecs pertinents sont testés (ex. : synchronisation réussie, repli + iCal → `pronotepy` en mode `auto`, modes explicites stricts, erreurs explicites). - Les outils de validation (`ruff`, `mypy`, `pytest`, `bandit`) passent sans erreur. - Aucun secret ni configuration locale n'apparaît dans le diff ou les fichiers suivis. - La documentation reste cohérente avec le code (ex. : mise à jour des exemples, des contrats ou des décisions d'architecture).