Planification/CLAUDE.md

CLAUDE.md — Workflow de développement Planification

À lire avant toute modification. Ce fichier décrit le processus complet que Claude doit suivre quand Quentin demande une modification de l'extension.

---

Stack du projet

• Type : extension navigateur Manifest V3 (Chrome / Edge / Firefox 140+)
• Fonction : viewer du planning des techniciens DGNSI dans EasyVista
• Cible utilisateurs : techniciens DGNSI (Canton de Vaud)
• Auteur : Quentin Rouiller (email dans la mémoire Claude user_role.md)
• Repo Gitea : https://gitea.netaplaid.ch/FroSteel/Planification
• Config runtime : chrome.storage.local["admin_config"] (persiste entre updates)

Structure du repo

src/                 # Sources de l'extension (chargées par le navigateur)
├── manifest.json    # Manifest V3 — version YYYY.M.PATCH
├── background.js    # Service worker
├── viewer.{html,js,css}
└── icons/

Autres/              # Méta + build
├── build.sh         # Génère dist/{chromium,firefox}/, .zip, .xpi, met à jour firefox-updates.json
├── CHANGELOG.md     # Synchronisé avec le CHANGELOG.md à la racine
├── README.md        # Synchronisé avec le README.md à la racine
└── LICENSE

Builds/              # Artefacts distribués (Chromium/, Firefox/, .zip, .xpi)
dist/                # Sortie de build (gitignoré)
firefox-updates.json # Manifest d'auto-update Firefox (servi via update_url)
CLAUDE.md            # Ce fichier
CHANGELOG.md         # Source de vérité du changelog (lu par AMO + GitHub-style)
README.md            # Source de vérité du README

NB : le repo Gitea utilise un layout flat à la racine pour le code source historique (build.sh, README.md, CHANGELOG.md, LICENSE, firefox-updates.json à la racine, et src/ pour le code). En local, le dossier Autres/ contient une copie de ces fichiers — tu peux éditer l'un ou l'autre, mais quand tu pousses sur Gitea c'est la racine qui doit être mise à jour.

---

Workflow standard d'une demande de modification

Quand Quentin demande une nouvelle fonctionnalité ou un bugfix :

Phase 1 — Code + build local (toi seul, pas encore de push)

1. Comprendre la demande, poser des questions si nécessaire avant d'écrire du code.
2. Coder les modifications dans src/ (jamais directement dans dist/ ou Builds/).
3. Bumper la version : incrémenter le 3e chiffre dans src/manifest.json (ex: 2026.5.41 → 2026.5.42). Bump majeur (2e chiffre) seulement pour les refontes ; année (1er chiffre) au passage à 2027.
4. Mettre à jour le CHANGELOG (Autres/CHANGELOG.md ET la copie racine CHANGELOG.md) en ajoutant une nouvelle entrée en haut.
5. Mettre à jour le README (Autres/README.md ET racine README.md) si la nouvelle version touche aux fonctionnalités principales.
6. Builder : ./Autres/build.sh — ça produit dist/chromium/, dist/firefox/, le .zip et le .xpi avec la nouvelle version.
7. Annoncer à Quentin : "v2026.5.X buildée, recharge l'extension dans ton navigateur et teste". Décrire brièvement ce qui a changé visuellement.
8. Attendre son retour. Tant qu'il n'a pas dit "OK", ne pas pousser sur Gitea. Si correction demandée, retourner à l'étape 2.

Phase 2 — Push sur Gitea (uniquement après validation explicite)

Quand Quentin dit "OK push" / "valide" / équivalent :

1. Préparer un clone Gitea à jour dans /tmp/planif-push/ (clone si pas présent, sinon git fetch origin && git reset --hard origin/main).

2. Synchroniser :

   • rsync -a --delete /Users/quentin/Documents/Planning/src/ /tmp/planif-push/src/
   • Copier les versions racine de CHANGELOG.md, README.md, LICENSE, build.sh (les versions racine sur Gitea, pas celles de Autres/)

3. Régénérer firefox-updates.json à la racine du repo : ajouter l'entrée de la nouvelle version en haut de la liste updates (les anciennes entrées restent — Firefox prend la version la plus haute parmi celles listées). Le update_link pointe vers la release Gitea : https://gitea.netaplaid.ch/FroSteel/Planification/releases/download/vYYYY.M.PATCH/planification-vYYYY.M.PATCH-firefox.xpi. Le update_hash est calculé après signature AMO (cf. Phase 3).

   Le repo Gitea est public, donc l'URL fixe update_url = https://gitea.netaplaid.ch/FroSteel/Planification/raw/branch/main/firefox-updates.json est accessible sans auth → Firefox peut le fetcher directement. build.sh maintient automatiquement ce JSON à chaque build (ajoute / met à jour l'entrée de la version courante).

4. Commit + push :

   cd /tmp/planif-push
   git add -A
   git commit -m "vYYYY.M.PATCH — <description courte>"
   git push origin main
   git tag -a vYYYY.M.PATCH -m "vYYYY.M.PATCH"
   git push origin vYYYY.M.PATCH
   

5. Créer la release Gitea via l'API (POST /repos/FroSteel/Planification/releases) avec :

   • tag_name: vYYYY.M.PATCH
   • name: vYYYY.M.PATCH
   • body: extrait du CHANGELOG (la section de cette version)

6. Uploader les binaires comme assets de la release :

   • dist/planification-vYYYY.M.PATCH-chromium.zip
   • dist/planification-vYYYY.M.PATCH-firefox.xpi (NON signé pour le moment)

7. Mettre à jour le wiki Gitea :

   • Page Versions : ajouter une entrée détaillée en haut (dérivée du CHANGELOG)
   • Page Utilisation : si le changement modifie l'UX (ajout d'un bouton, d'une section admin, d'un comportement) → documenter
   • Page Architecture : si nouvelles fonctions clés / nouvelle config persistée → documenter

Phase 3 — Signature Firefox (manuel, fait par Quentin)

L'addon planification-dgnsi@netaplaid.ch est déjà enregistré sur AMO en mode "On your own" (Unlisted, self-distributed). Pour chaque nouvelle version, la procédure est :

1. Quentin va sur https://addons.mozilla.org/developers/
2. Trouve l'addon Planification dans la liste → "Téléverser une nouvelle version" (pas "Submit a New Add-on" — l'addon existe déjà)
3. Upload le .xpi non signé qui se trouve sur la release Gitea (ou en local)
4. Mozilla valide + signe (généralement instantané pour une nouvelle version d'un addon existant) → Quentin télécharge le .xpi signé
5. Quentin revient vers Claude avec le chemin du .xpi signé (typiquement /Users/quentin/Downloads/<hash>-<version>.xpi)

Claude fait alors :

1. Vérifier que META-INF/mozilla.rsa + META-INF/cose.sig sont présents
2. Calculer le sha256 du .xpi signé
3. Copier le .xpi signé dans dist/ et Builds/ (archive locale)
4. Remplacer l'asset .xpi de la release Gitea (delete + upload)
5. Mettre à jour firefox-updates.json : "update_hash": "sha256:<hash>" pour cette version
6. Commit + push le JSON mis à jour

À partir de ce moment, l'auto-update Firefox déclenche : tous les techs DGNSI déjà installés en version précédente passent à la nouvelle dans les 24h via le mécanisme natif update_url de Firefox, sans aucune action de leur part.

⚠️ Chrome/Edge ne sont PAS concernés par AMO. Les techs sur Chrome restent sur la version installée jusqu'à ce qu'ils rechargent manuellement le .zip (chrome://extensions → Recharger). Pas d'auto-update natif pour les extensions chargées en "non empaquetées".

---

Token Gitea

⚠️ Le token API Gitea ne doit JAMAIS apparaître dans ce fichier ni dans le repo Gitea. Il est stocké uniquement dans la mémoire Claude locale (~/.claude/projects/-Users-quentin-Documents-Planning/memory/gitea_token.md, hors repo). Si Claude perd la mémoire (nouvelle session non héritée), demander à Quentin de redonner le token.

Header API à utiliser : Authorization: token <TOKEN> + User-Agent: curl/8.4.0 (le User-Agent évite que Cloudflare bloque les requêtes Python urllib).

---

Règles importantes

• Ne jamais hardcoder dans src/ : groupe EV, équipe, domaines, absences récurrentes. Tout passe par admin_config. Les seuls hardcodes acceptables sont les filets de sécurité (DEFAULT_GROUP_ID, DEFAULT_EV_ORIGINS pour le 1er install). Cf. v2026.5.41 pour la migration complète.
• Ne jamais pousser sur Gitea sans validation explicite de Quentin.
• Toujours bumper la version avant un push qui modifie le code.
• Toujours mettre à jour le CHANGELOG avant un push.
• Tags non touchés sur Gitea : v1.0.0-v3.3.0, v4.1.x-v4.3.0, v5.0.0, v2026.5.27-v2026.5.32 (ceux-là pointent vers du code reconstitué historique, ne jamais les bouger).
• Force-push uniquement si Quentin le demande explicitement.
• L'email de l'auteur ne doit apparaître nulle part dans src/ ni dans les fichiers Markdown du repo (CLAUDE.md, README.md inclus). Il est stocké uniquement en mémoire Claude (user_role.md / gitea_token.md) et exposé obfusqué (entités HTML) sur la page wiki Contact.

---

Pages wiki Gitea

Page	Contenu	Quand mettre à jour
Home	Pitch, contexte, démarrage rapide	Rarement
Utilisation	Guide complet pour l'utilisateur	À chaque changement UX
Versions	Historique détaillé des versions	À chaque release
Architecture	Doc technique (fonctions, config, structure)	À chaque ajout d'helper / changement structurel
Contact	Email obfusqué + lien Issue Gitea	Rarement

URL de base wiki : https://gitea.netaplaid.ch/FroSteel/Planification/wiki/<NOM> Endpoint API : /api/v1/repos/FroSteel/Planification/wiki/page/<NOM> (PATCH avec content_base64).

---

Pour résumer ton rôle, Claude

Quentin demande une modif → tu codes → tu builds → il teste → il valide → tu push tout (Gitea + wiki + firefox-updates.json). Plus tard il revient avec le .xpi signé d'AMO → tu mets à jour la release et le update_hash du JSON.

Si tu hésites sur quoi faire à un moment, demande. Ne suppose pas.