# AGENTS.md

## Objet du projet

Ce dépôt contient l’add-on Home Assistant `arkteos-proxy-addon`.

Son rôle est de maintenir une connexion TCP unique vers une PAC Arkteos et de
mettre ce flux à disposition de plusieurs clients TCP.

Gitea est le dépôt principal de développement interne via `origin` :

- https://gitea.i-host.fr/raph666/arkteos-proxy-addon

GitHub est le miroir public via `github` et l’URL de distribution de l’add-on :

- https://github.com/raph666/arkteos-proxy-addon

Les fichiers publics destinés aux utilisateurs, notamment `README.md`,
`config.yaml` et `repository.yaml`, doivent utiliser l’URL GitHub, sauf demande
contraire. L’URL Gitea reste réservée à la documentation interne.

## Architecture

Le proxy comporte deux côtés distincts :

- côté PAC :
  - connexion sortante vers `pac_host:pac_port` ;
  - port par défaut : `9641` ;
- côté clients :
  - écoute sur `0.0.0.0:proxy_port` ;
  - port par défaut : `9641`.

Le proxy distribue les données reçues de la PAC vers tous les clients connectés.

Le proxy peut aussi relayer les données envoyées par les clients vers la PAC
lorsque cette fonctionnalité est explicitement activée.

## Contraintes importantes

### Connexion PAC unique

La PAC ne doit avoir qu’une seule connexion TCP active.

Ne jamais ajouter une seconde connexion concurrente vers la PAC.

Tous les clients Home Assistant, outils de diagnostic ou autres consommateurs
doivent passer par le proxy.

### Compatibilité protocolaire

Ne pas inventer de protocole, checksum ou validation non observée.

Ne modifier ni le contenu ni l’ordre des octets transmis sans preuve issue :

- d’une capture réelle ;
- du comportement actuel ;
- ou d’une documentation fiable.

### Keepalive

Le proxy envoie actuellement un octet nul toutes les 300 secondes.

Le rôle exact de ce keepalive côté PAC n’est pas confirmé.

Ne pas modifier :

- sa valeur ;
- sa fréquence ;
- son activation ;

sans test préalable et justification documentée.

### Écritures vers la PAC

Le proxy peut fonctionner en mode bidirectionnel.

Les données envoyées par les clients peuvent atteindre la PAC si le mode
d’écriture est activé.

Règles :

- lecture seule par défaut ;
- aucune écriture client ne doit être autorisée implicitement ;
- toute option d’écriture doit être explicite ;
- les écritures vers la PAC doivent être sérialisées ;
- utiliser `writer.drain()` après une écriture ;
- ne jamais journaliser les données brutes envoyées par un client ;
- ne jamais exposer le port du proxy sur Internet ;
- aucune authentification réseau ne doit être supposée si elle n’existe pas.

## Sécurité

Ne jamais ajouter au dépôt :

- mot de passe ;
- token ;
- clé API ;
- secret Home Assistant ;
- clé privée ;
- adresse IP personnelle inutile ;
- flow Node-RED contenant des identifiants réels ;
- contenu issu d’un autre projet sans rapport avec Arkteos.

Les exemples doivent utiliser des valeurs neutres :

- `192.168.1.100`
- `PAC_IP`
- `CHANGEME`
- `example.local`

Ne jamais afficher une valeur sensible dans les rapports ou les logs.

## Fichiers principaux

Vérifier en priorité :

- `config.yaml`
- `repository.yaml`
- `Dockerfile`
- `run.sh`
- `arkteos_proxy.py`
- `README.md`
- `CHANGELOG.md`
- `.gitignore`
- `AGENTS.md`

Le point d’entrée réel doit toujours être confirmé depuis `run.sh` et le
Dockerfile.

## Règles de modification

Avant toute modification :

1. afficher l’état Git ;
2. inspecter le code existant ;
3. distinguer les faits observés des hypothèses ;
4. présenter le plan si la modification touche le réseau ou le protocole.

Ne jamais :

- supprimer une fonction utile sans accord ;
- modifier un port par défaut sans demande ;
- modifier le protocole silencieusement ;
- remplacer une logique existante par une implémentation supposée ;
- modifier plusieurs sujets sans rapport dans le même changement ;
- réécrire l’historique Git sans accord explicite ;
- utiliser `git push --force` ;
- créer un commit, un tag ou un push sans demande explicite.

## Style Python

- utiliser `asyncio` lorsque pertinent ;
- gérer explicitement les déconnexions ;
- fermer proprement les writers ;
- utiliser `await writer.wait_closed()` lorsque possible ;
- annuler proprement les tâches ;
- éviter les tâches asyncio résiduelles après arrêt ;
- journaliser les exceptions réseau sans arrêter définitivement le proxy ;
- temporiser les boucles de reconnexion ;
- éviter les variables globales mutables non protégées ;
- utiliser un verrou dédié pour les écritures vers la PAC ;
- ne pas réutiliser le verrou de la liste des clients pour les écritures réseau.

## Journalisation

Les logs doivent indiquer clairement :

- connexion à la PAC ;
- déconnexion de la PAC ;
- tentative de reconnexion ;
- connexion d’un client ;
- déconnexion d’un client ;
- mode lecture seule ou bidirectionnel ;
- erreur réseau utile au diagnostic.

Ne pas journaliser :

- secrets ;
- mots de passe ;
- contenu brut des commandes clients ;
- flux binaires complets en fonctionnement normal.

Les logs fréquents doivent éviter de saturer le journal Home Assistant.

## Tests

Toute modification fonctionnelle doit être accompagnée de tests lorsque
possible.

Tester au minimum les zones concernées :

- connexion à la PAC ;
- reconnexion après coupure ;
- connexion et déconnexion des clients ;
- distribution PAC vers plusieurs clients ;
- blocage des écritures en mode lecture seule ;
- relais client vers PAC en mode autorisé ;
- sérialisation des écritures concurrentes ;
- keepalive ;
- fermeture propre ;
- absence de vraie connexion à une PAC pendant les tests.

Les tests doivent utiliser des mocks, des serveurs asyncio locaux ou des writers
simulés.

## Validations obligatoires

Avant de proposer un commit :

```bash
python3 -m compileall .
bash -n run.sh
```

Valider les fichiers YAML :

```bash
python3 - <<'PY'
from pathlib import Path
import yaml

for filename in ("config.yaml", "repository.yaml"):
    with Path(filename).open(encoding="utf-8") as file:
        data = yaml.safe_load(file)

    if not isinstance(data, dict):
        raise SystemExit(f"ERREUR : {filename}")

    print(f"OK YAML : {filename}")
PY
```

S’il existe des tests :

```bash
python3 -m pytest -v
```

Toujours exécuter :

```bash
git diff --check
git status --short
```

## Versionnement

La version de l’add-on est définie dans `config.yaml`.

Avant une release :

- vérifier la cohérence avec `CHANGELOG.md` ;
- vérifier la documentation ;
- vérifier que les tests passent ;
- vérifier l’absence de secret ;
- vérifier les URLs Gitea et GitHub ;
- créer le commit avant le tag ;
- créer un tag au format `vX.Y.Z`.

Ne jamais déplacer ou recréer un tag déjà publié.

## Workflow Git

Dépôt principal :

```bash
git pull
git push
```

Ces commandes doivent utiliser Gitea via `origin`.

Miroir GitHub :

```bash
git push github main
git push github --tags
```

Les remotes attendus sont :

- `origin` → Gitea ;
- `github` → GitHub.

Ne jamais inverser ces rôles sans demande explicite.

## Documentation

Toute modification fonctionnelle doit être reflétée dans :

- `README.md` ;
- `CHANGELOG.md` ;
- `config.yaml` si une option est ajoutée ou modifiée.

La documentation doit décrire le comportement réel du code.

Ne jamais présenter le proxy comme strictement passif si les clients peuvent
écrire vers la PAC.

## Rapport attendu après modification

À la fin d’une tâche, indiquer :

- fichiers modifiés ;
- fichiers ajoutés ;
- comportement modifié ;
- validations exécutées ;
- résultats des tests ;
- avertissements restants ;
- confirmation de l’absence de commit, push ou tag si cela n’était pas demandé.