2025/AGENTS.md

# AGENTS.md

## Présentation du projet

Ce projet contient les sources de mon blog.
Il s'agit d'un site statique généré avec Hugo, dont la version peut être vérifiée avec la commande `hugo version`.

## Instructions générales

### Interactions avec l'utilisateur

- L'utilisateur préfère être vouvoyé
- Répondre à l'utilisateur en français, quelle que soit la langue utilisée ailleurs
- Si une demande prête à confusion, demander une clarification à l'utilisateur plutôt que d'essayer de deviner
- L'utilisateur préfère considérer l'agent comme une entité féminine
- L'agent est un expert du développement web et maitrise toute technologie afférente
- L'utilisateur préfère qu'on s'adresse à lui avec un ton bienveillant, en utilisant un vocabulaire soutenu, approprié au contexte
- L'autisme de l'utilisateur doit être pris en compte au cours des échanges
- L'utilisateur peut parfois perdre patience : la discussion doit être désamorcée rapidement par une solution que l'agent mettra en place, testera et modifiera jusqu'à ce qu'elle produise le résultat escompté

### Git

- Ne jamais faire de `git push` automatiquement, sauf si demandé explicitement
- Les commits doivent être atomiques
- Les commits sont écrits en français
- Aucun commit ne doit être effectué sans demande explicite de l'utilisateur

### Code

- Le code doit être architecturé, propre, clair, concis, minimaliste
  - Préférer la création de plusieurs petits fichiers pour éviter le code monolithique
  - Ne pas implémenter de fonctionnalités non demandées
  - Respecter les principes DRY, KISS et SOLID
  - Si une librairie existe pour accomplir une tâche donnée, exploiter cette librairie
    - S'assurer de sa popularité et de son activité récente
- Le code doit être écrit en anglais mais documenté en français, lisible par un humain
  - Documenter clairement toutes les fonctions et méthodes
  - Choisir des noms de variables appropriées et compréhensibles, tout en restant courts
- La gestion des erreurs est considérée comme dangereuse
  - On ne doit jamais utiliser de fallbacks
  - On ne doit jamais utiliser de structures de type `try/catch`
- Le code est écrit pour être spécifique à mon site
  - Je suis l'unique utilisateur des outils créés
  - Le code doit être compris de tous, mais pas adaptable à tous

### Outils en console

- S'assurer de l'harmonisation des entrées/sorties
  - Toujours utiliser le français dans les interactions avec l'utilisateur

### Python

- Accéder à l'environnement virtuel via la commande `source .venv/bin/activate`
- Renseigner les dépendances dans le fichier `requirements.txt`

### Javascript

- Mettre à jour régulièrement les dépendances
- Auditer régulièrement les dépendances avec `npm audit`

### CSS

- Le thème de base est nommé `42` (`themes/42`) (référence à H2G2, mais aussi parce que je l'ai créé à l'occasion de mon anniversaire)
- Je n'utilise aucun framework connu ; je fais du CSS "vanilla"
- Nous ne supporterons jamais de thème clair
- Il fait usage de variables CSS définies dans `themes/42/assets/css/variables`
- L'agent peut créer de nouvelles variables, à condition de respecter les conventions de nommage des autres variables
- Ce thème de base peut être hérité par d'autres thèmes
  - Le thème par défaut est actuellement `themes/default`
  - Un thème hérité n'est censé devoir surcharger que les variables qualifiées "d'esthétique" (telles que les couleurs ou les effets visuels), par opposition aux variables qualifiées de "structurelles" (telles que les marges ou le positionnement)
- Le CSS doit rester le plus simple possible
  - On ne doit pas exploiter d'effets visuels complexes tels que les agrandissements, les shifts, les apparitions ou disparitions progressives, etc.
- Le code CSS doit respecter les règles d'accessibilité pour le contenu, notamment :
  - Taille des polices
  - Contrastes entre le texte et le fond de son container
- On doit créer le moins de classes possibles, et préférer styliser les balises HTML directement
- On peut utiliser la notation imbriquée (_nested_) par mesure de lisibilité

## Instructions relatives aux articles

- Ne pas utiliser les apostrophes et les guillemets typographique dans le markdown

### Structure du contenu

- Tout le contenu publié réside dans le dossier `content/`
- Un dossier contenant un fichier `index.md` est un _bundle_
- Tous les _articles_ sont des bundles
- Si un dossier ne contient pas de fichier `index.md`, c'est une section
- Une section ne contenant _que_ des bundles est une section-feuille, autrement appelée _thématique_
- Un bundle peut contenir :
  - Un ou plusieurs dossiers `images`, `diagrams`, `sounds`, `videos`, contenant les _pièces jointes_ du bundle
  - Un dossier `data`, pouvant notamment contenir des _métadonnées_ associées aux pièces jointes

### Sections de premier niveau

#### Collections (`content/collections/`)

- Les premiers dossiers, enfants directs de `content/collections/`, désigne une marque proposant des objets que je collecte ; ce sont les _dossiers de marque_
  - `content/collections/lego` contient ma collection d'objets LEGO.
- Chaque dossier de marque peut contenir un ou plusieurs _dossiers de thèmes_
  - `content/collections/lego/jurassic-world` contient ma collection d'objets LEGO sur le thème de _Jurassic World_
- Chaque dossier de thème contient un ou plusieurs bundes d'objets de collection, chacun représentant un et un seul objet

#### Critiques (`content/critiques/`)

- Contient mes critiques de _médias_ (liste non exhaustive, pouvant évoluer avec le temps) :
  - `content/critiques/films` pour mes critiques de films
  - `content/critiques/series` pour mes critiques de séries TV
  - `content/critiques/jeux-video` pour mes critiques de jeux-vidéo
  - `content/critiques/livres` pour mes critiques de livres
- Chaque _média_ contient directement un ou plusieurs bundles représentant l'oeuvre critiquée
- Le titre original est utilisé, pas le titre français

#### Intérêts (`content/interets/`)

- Articles de fond sur des sujets qui m'intéressent
- Ce dossier contient un sous-dossier par thématique principale
  - `astronomie`
  - `microscopie`
  - `informatique`
  - etc.
- Chaque thématique contient une arborescence structurée en année, mois, jour et bundles
  - Exemple : Si l'on découpe le chemin physique `content/interets/electronique/2025/10/21/pilotage-d-un-switch-usb-par-le-wifi`, on sait qu'on est dans le bundle `pilotage-d-un-switch-usb-par-le-wifi`, publié le 21/10/2025 dans la section électronique

##### Liens intéressants (`content/interets/liens-interessants`)

- Cette section a le même usage que l'application `Shaarli` : je m'en sers pour partager avec mes lecteurs mes trouvailles sur Internet
- J'ajoute un lien avec la commande `node tools/add_link.js  "<url>"`, qui produit le bundle correspondant, récupère le titre et la description du site distant, ainsi qu'une capture d'écran placée dans le dossier `images/` du bundle créé
- Si une description est trouvée, elle est ajoutée dans le corps du fichier `index.md` généré par le script
- Je peux éventuellement ajouter un commentaire personnel dans le corps du fichier `index.md`, mais ce n'est pas systématique

### Pièces jointes

- Un bundle peut contenir une ou plusieurs pièces jointes, selon leur type parmi (liste non exhaustive et pouvant évoluer avec le temps) :
  - `images`
  - `videos`
  - `sounds`
  - `diagrams`
- Chaque pièce jointe peut être accompagnée de métadonnées placées dans le dossier `data` du bundle
  - Par exemple, l'image `{chemin du bundle}/images/1.png` peut avoir un fichier de métadonnées placé dans `{chemin du bundle}/data/images/1.yaml`

### Métadonnées

- Un fichier de métadonnées d'une pièce jointe à un bundle est nécessairement au format yaml, doté des attributs suivants :
  - `title` : Titre du document (utilisé par l'attribut HTML `title`)
  - `description` : Description libre ajoutée au document (affiché dans une balise `figcaption` par exemple)
  - `attribution` : Si le fichier n'a pas été créé par l'utilisateur
  - `prompt` : Si le fichier a été généré par l'Intelligence Artificielle, cet attribut doit contenir le prompt utilisé pour le générer
- Aucun attribut de ce fichier n'est requis ; ils peuvent rester vides ou être précédés par le caractère `#`
- Le fichier de métadonnées n'est pas requis ; s'il existe, il peut être vide

### Frontmatter

- Tout fichier `index.md` doit avoir un frontmatter contenant au moins les attributs suivants :
  - `title` : Titre que je donne à mon article
  - `date` : Si possible avec l'heure, mais la majorité de mes articles actuels ne contiennent que la date
- Le frontmatter peut contenir d'autres attributs optionnels, autres que les taxonomies :
  - `cover` : Chemin vers l'image illustrant l'article. Cette image doit être stockée dans le dossier `{chemin du bundle}/images/`. Elle sera utilisée pour générer la vignette de l'article, et affichée en en-tête de l'article. Je la désigne par _cover_, _image de couverture_, ou _image d'en-tête_
  - `dossier` : Plusieurs bundles partageant une même valeur pour l'attribut `dossier` seront regroupés dans un _dossier virtuel_ tout en résidant physiquement dans leurs dossiers _physiques_ respectifs
    - Exemple : `dossier: [ "Exploitation de mes données météo" ]`
    - Cet attribut devrait être complété par un attribut `weight`
      - Par exemple :

      ```json
      dossier: [ "Exploitation de mes données météo" ]
      weight: 10
      ```

    - `links` : Peut contenir un ou plusieurs objets indiquant des liens associés au bundle. Par exemple :

    ```json
    links:
    - name: Page d'origine
      url: https://openbadgefactory.com/obv3/credentials/f421c3c8ae974fa2191b3482b05f37b4e1bc8c4b
      lang: fr
    ```

        - Les attributs `name` (titre du document) et `url` sont requis
        - L'attribut `lang` ne doit être renseigné **que** si l'on connait avec certitude la langue du document distant
- Le frontmatter doit être séparé du corps de l'article par une ligne vide

### Markdown

- Lorsque l'utilisateur demande à être aidé pour la rédaction de ses articles, employer un ton neutre, utiliser un vocabulaire approprié au sujet traité
- Rester neutre, objectif, factuel
- Présenter des sources vérifiables lors de toute affirmation portant sur un concept-clé, sous la forme de liens markdown vers :
  - la Wikipédia en français (ou à défaut, en anglais)
  - une ou plusieurs études scientifiques, si approprié
- Corriger l'attribut `date` du frontmatter lorsqu'il est renseigné mais incomplet, pour indiquer la date et l'heure courante, dans un format supporté par Hugo. Ne jamais ajouter l'attribut s'il n'existe pas déjà.
- Les sections démarrent toujours au deuxième niveau dans le corps du markdown (`##`)
- Ne jamais ajouter de numérotation aux sections
- Ne jamais utiliser de caractères comme les emojis dans les sections
- Ne jamais ajouter d'émojis dans le corps de l'article
- Ne jamais supprimer les émojis existant

## Outils

- Les outils sont placés dans le dossier `tools/`
- Les librairies créées sur mesure devront être placée dans `tools/lib/`, éventuellement dans un sous-dossier pour architecturer correctement le code

### Ajout d'un LEGO à ma collection (`tools/add_lego.js`)

- Ce script exploite l'API du site Rebrickable pour me permettre de récupérer des images et informations à propos d'un set LEGO donné et ajoute ou modifie le bundle correspondant

### Ajout d'un lien intéressant (`tools/add_link.js`)

- Prend en entrée un URL et crée un nouveau bundle en peuplant l'attribut `links` du frontmatter et en fournissant une image d'en-tête

### Ajout de la météo (`tools/add_weather.js`)

- Ajoute les informations sur la météo à un bundle (ou tous les bundles)
- Ces informations sont tirées de mon serveur InfluxDB2, ou d'au moins une source externe si ces données ne sont pas disponibles

### Vérification des liens

#### Externes (`tools/check_external_links.js`)

- Vérifie la disponibilité des sites liés partout dans `content/` (code HTTP 200 ou autre)
- On cherche les liens dans les fichiers markdown (incluant le frontmatter) et les fichiers `*.yaml`
- On ignore les URL placés dans des blocs de code mono ou multilignes
- La vérification enrichie repose sur Playwright et le Chromium embarqué par la librairie `playwright`
  - La variable `externalLinks.usePlaywright` de `tools/config/config.json` doit être positionnée à `true` pour activer cette vérification
  - L'attribut `externalLinks.playwrightExecutablePath` doit rester vide ou à `null` afin de laisser Playwright utiliser son propre navigateur, compatible avec la configuration `nix-ld` déclarée dans `/etc/nixos/nix-ld-libraries.nix`
  - Si `externalLinks.playwrightExecutablePath` est renseigné, il doit impérativement pointer vers un binaire existant : dans le cas contraire, le script se termine en erreur et interrompt le déploiement

#### Internes (`tools/check_internal_links.js`)

- Vérifie les liens morts internes
- Pas besoin de lancer Hugo : il suffit de chercher tous les liens sans `://` dans `content/`
- On cherche les liens dans les fichiers markdown (excluant le frontmatter) et les fichiers `*.yaml`
- On ignore les URL placés dans des blocs de code mono ou multilignes
- L'URL est de la forme `/{section ou bundle}` : on cherche l'existence du dossier `content/{section ou bundle}`, et la présence d'un fichier `index.md` ou `_index.md` dans ce dossier, s'il existe. Si un tel fichier existe : le lien est valide.

### Diagrammes mermaid (`tools/generate_mermaid_diagrams.js`)

- Cherche des fichiers `*.mermaid` dans un dossier `diagrams` des bundles
- Pour chaque fichier `*.mermaid` trouvé, on lance l'exécutable de `mermaid` sur ce fichier pour produire l'image correspondante dans le dossier `images/` du bundle
- Les images produites doivent être au format `.png` ou `.jpeg`
- Voir `content/interets/electronique/2025/10/21/pilotage-d-un-switch-usb-par-le-wifi`

### Génération de métadonnées (`tools/generate_metadata_files.js`)

- Génère automatiquement les fichiers de métadonnées pour toute pièce jointe du dernier bundle créé et les place dans le dossier `data/` du bundle

### Générateur de statistiques (`tools/generate_stats.js`)

- Génère diverses statistiques intéressantes
- Les statistiques sont présentées dans le bundle `content/stats`

### Synchro Wikipédia (`tools/sync_wiki_metadata.js`)

- Ce script est utile aux critiques de médias
- Il cherche sur la Wikipédia/Wikidata des informations relatives aux oeuvres critiquées

## Déploiement

- Tout le déploiement du site est confié au script `deploy.sh`.
- Certains scripts sont exécutés avant le déploiement. S'ils modifient des fichiers dans `content/`, leur exécution doit stopper le déploiement et informer l'utilisateur que des fichiers ont été modifiés
  - Exploiter `set -euo pipefail` pour éviter les blocs `if` à chaque script