# 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** : ```bash cd /tmp/planif-push git add -A git commit -m "vYYYY.M.PATCH — " 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/-.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:"` 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 ` + `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/` Endpoint API : `/api/v1/repos/FroSteel/Planification/wiki/page/` (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.