Le manifeste de preuve, ligne à ligne
Le manifeste du projet serre tient en 18 lignes de YAML. Voici sa syntaxe réelle, ce que le moteur en fait, et une exécution relue.
L’article précédent expliquait pourquoi chaque projet a sa page de preuve.
Celui-ci ouvre le capot : un manifeste, c’est un petit fichier YAML qui déclare
d’où viennent les preuves d’un projet, et que le moteur exécute à chaque
construction du site. Le docstring du moteur (store/noyau/preuves.py) le dit
sans détour : « pour qu’une preuve ne puisse pas mentir par oubli ». Et :
« Un fichier de manifeste n’est jamais recopié à la main dans une page. »
Le fichier, en entier
Celui du projet serre, store/projets/serre/preuve.yml, fait 18 lignes :
projet: serre
commandes:
- titre: Bus activés dans config.txt
commande: grep -E 'dtparam|dtoverlay' /boot/firmware/config.txt
- titre: Nœuds I2C et SPI
commande: ls /dev/i2c-* /dev/spidev* 2>/dev/null
- titre: Sondes 1-Wire
commande: cat /sys/bus/w1/devices/w1_bus_master1/w1_master_slaves 2>/dev/null || echo "aucune sonde"
compteurs:
- titre: Mesures de démonstration en base
base: /var/lib/serre/serre.db
sql: select count(*) from mesures
captures:
- image: ressources/serre-24h.png
titre: Le tableau de bord que le kit produit (données de démonstration)
limites:
- "Aucun capteur n'est branché : les bus sont activés, mais vides."
- La pompe et le débitmètre ne sont pas encore installés.
Quatre sections ici. Le moteur en accepte six : tests, commandes,
compteurs, fichiers, captures, limites. Le manifeste du guide
d’auto-hébergement (store/projets/guide-pi/preuve.yml) utilise les six.
Détail vérifié dans le code : la clé projet: n’est jamais lue par le moteur —
c’est le chemin du fichier (store/projets/<slug>/preuve.yml) qui le lie au
projet. La clé est déclarative, pas fonctionnelle.
La syntaxe, section par section
commandes — un titre et une commande shell. Le moteur l’exécute avec
un délai maximal de 60 s, depuis la racine de la couche
(~/Documents/Athena). Il concatène stdout et stderr, puis ne garde que les
12 dernières lignes et 1 200 derniers caractères (_couper). Le verdict est le
code de retour : 0 = OK, sinon le code est affiché tel quel.
compteurs — un titre, une base SQLite, une requête sql. La base est
ouverte en lecture seule (URI mode=ro) : le manifeste ne peut pas écrire
dans la base qu’il mesure. Seule la première ligne du résultat est affichée.
captures — une image et un titre, ou juste un chemin en texte simple.
Le moteur vérifie que l’image existe ; la page l’affiche en galerie.
limites — du texte libre, rendu dans un bloc à part en bas de page.
Piège YAML réel : une limite contenant un deux-points non protégé est lue
comme un dictionnaire. Le moteur la remet à plat (_aplatir_limite) plutôt
que d’afficher du JSON — d’où les guillemets sur la première limite ci-dessus.
tests (absents ici) — un fichier et une commande. Le nombre de tests
affiché ne sort pas de la commande : il est compté dans le source par une
regex (def test_…). Le chiffre vient du fichier, le verdict OK/KO vient de
l’exécution. Supprimer un test fait baisser le chiffre, même si la commande
réussit encore.
fichiers (absents ici) — une liste de chemins. Le moteur affiche la
taille et les 12 premiers caractères hexadécimaux du SHA-256. Un fichier livré
qui change d’empreinte se voit.
Les chemins relatifs commençant par ressources/ ou assets/ sont résolus
depuis store/ ; tous les autres depuis la racine de la couche (_résoudre).
Deux gardes, pas une
Le moteur distingue deux moments, et c’est important :
- Avant construction,
contrôle()vérifie que chaque fichier de test, fichier livré, capture et base déclarés existent. Chaque manque devient une erreur dansstore/outils/site.py, et la construction sort en échec. Un manifeste qui pointe vers un fichier supprimé bloque le site. - Pendant la collecte, une commande qui échoue ne bloque rien :
collecter()n’échoue jamais, l’erreur est affichée dans la page. Une preuve d’échec reste une preuve.
La date affichée (« recalculé le ») est celle du jour de la collecte, pas une date écrite à la main.
Exécution relue le 2026-11-21
J’ai exécuté collecter('serre') ce matin. Trois résultats méritent d’être
montrés tels quels.
Nœuds I2C et SPI — un échec affiché, pas caché
commande
ls /dev/i2c-* /dev/spidev* 2>/dev/nullsortie
/dev/spidev0.0
/dev/spidev0.1
code de retour 2Le SPI est là, l’I2C non : le module i2c-dev n’est pas chargé (lsmod ne le
liste pas), donc /dev/i2c-1 n’existe pas et ls sort en code 2. La page de
preuve affiche ce code au lieu de le masquer. C’est exactement le contrat.
La commande 1-Wire, elle, réussit — et retourne 00-1bd000000000,
00-9bd000000000, 00-5bd000000000. Ces ROMs de famille 0x00 sont des
fantômes d’un bus flottant, pas des sondes (documenté dans HARDWARE.md).
Le bloc limites le déclare : « Aucun capteur n’est branché ». La commande
prouve que le bus répond ; la limite dit ce qu’il ne prouve pas.
Le compteur, lui, a retourné 120 mesures de démonstration dans
/var/lib/serre/serre.db, et contrôle('serre') n’a signalé aucun problème.
Les chiffres de cet article sont un instantané daté. La page preuve, elle, est recalculée à chaque construction du site — c’est toute la différence entre un article et une preuve.
Ce que ça ne résout pas
Le manifeste choisit ce qui est mesuré. Je pourrais en écrire un qui ne mesure que ce qui m’arrange ; c’est pour ça qu’il est public, dans le dépôt, et que chaque commande est visible sur la page. On peut lire ce qui est mesuré, et surtout ce qui ne l’est pas.
Dernier point, vérifié : les commandes du manifeste serre sont toutes en
lecture seule (grep, ls, cat, select). Un manifeste s’exécute avec les
permissions de celui qui construit le site — il doit rester inoffensif. C’est
une règle d’écriture, pas une garantie du moteur.