Chapitre 09
L'outillage : apply, pin, doctor, export

Objectifs du chapitre

Comprendre la propriété centrale d'apply : une reconstruction qui échoue ne laisse jamais un vault à moitié configuré.
Savoir pourquoi les empreintes se calculent et ne s'écrivent pas.
Utiliser le couple doctor/export comme cycle de vie de la configuration.
Reconnaître les décisions de conception qui font qu'un outil de ce genre est fiable, ou pas.

1. La structure

L'outillage vit dans le vault, sous 90-meta/tooling/. Deux points d'entrée, un paquet Python découpé par responsabilité :

90-meta/
├── manifest.yaml           # la source de vérité
├── conventions.md          # le contrat de front-matter, lisible dans Obsidian
├── templates/  vues/
└── tooling/
    ├── bootstrap.py        # apply | pin | doctor | export
    ├── vault.py            # doctor (contenu des notes)
    ├── vaulttool/
    │   ├── manifest.py     # charger et valider
    │   ├── render.py       # manifeste → contenus de fichiers
    │   ├── plugins.py      # télécharger, vérifier, installer
    │   ├── apply.py        # écrire, avec bascule atomique
    │   ├── pin.py          # calculer versions et empreintes
    │   ├── drift.py        # comparer, et proposer l'inverse
    │   └── notes.py        # valider le front-matter
    └── tests/

Un détail qui n'en est pas un : render.py est une fonction pure. Elle prend un manifeste et rend un dictionnaire « chemin → contenu », sans toucher au disque. C'est ce qui permet de la tester sans système de fichiers, et de réutiliser sa sortie pour comparer plutôt que pour écrire.

2. `apply` — et l'atomicité

$ uv run --project 90-meta/tooling 90-meta/tooling/bootstrap.py apply
40 fichiers ecrits dans .obsidian/

Derrière cette ligne, la propriété qui fait tout l'intérêt de la commande : si quoi que ce soit échoue, le .obsidian/ précédent est intact. Un vault à moitié configuré est pire qu'un vault périmé — il ne marche plus et on ne sait pas pourquoi.

Deux mécanismes superposés l'assurent.

Vérifier tout avant d'écrire quoi que ce soit

def preparer(specs, destination, telecharger=telechargeur_http):
    """Télécharge et vérifie tous les plugins épinglés, puis écrit."""
    contenus = {}
    for spec in epingles:                      # phase 1 : rien n'est écrit
        for active in _actifs_a_installer(spec):
            donnees = telecharger(url_actif(spec, active))
            reelle = empreinte(donnees)
            if reelle != spec.sha256[active]:
                raise ChecksumError(...)       # sortie ici : destination intacte
            contenus[spec.id][active] = donnees

    for identifiant, actifs in contenus.items():   # phase 2 : que des écritures
        ...

Tout est téléchargé et vérifié en mémoire avant la première écriture. Une empreinte fausse sur le neuvième plugin annule aussi les huit premiers.

Le test qui pin cette propriété ne vérifie pas qu'une exception est levée — n'importe quel code cassé lèverait une exception. Il vérifie que le dossier de destination est resté vide :

with pytest.raises(ChecksumError, match="calendar"):
    preparer([bon, mauvais], tmp_path, faux_telechargeur(table))
assert list(tmp_path.iterdir()) == []

C'est la différence entre tester le symptôme et tester la garantie.

Basculer par renommage

La nouvelle configuration se construit dans .obsidian.new/, puis on échange :

try:
    if actuel.exists():
        actuel.rename(ancien)      # .obsidian → .obsidian.old
    neuf.rename(actuel)            # .obsidian.new → .obsidian
except OSError as exc:
    if ancien.exists() and not actuel.exists():
        ancien.rename(actuel)      # restauration
    shutil.rmtree(neuf, ignore_errors=True)
    raise
shutil.rmtree(ancien, ignore_errors=True)

Le renommage est atomique au niveau du système de fichiers : à aucun instant .obsidian/ n'est un mélange des deux versions. Et si le second renommage échoue, on remet l'ancien en place avant de propager l'erreur.

Ce cas n'est pas théorique. Sur Windows, Obsidian tient des handles ouverts dans .obsidian/, et les relâche avec un peu de retard après sa fermeture. Un apply lancé juste après avoir quitté Obsidian donne :

echec : [Errno 13] Permission denied: '.obsidian.new' -> '.obsidian'

La restauration a fonctionné, .obsidian/ était intact, aucun résidu — et la même commande trente secondes plus tard est passée. Sans le bloc de restauration, le vault serait resté sans configuration du tout.

Ce qui survit à la bascule

Trois choses sont recopiées dans la nouvelle configuration au lieu d'être régénérées :

PRESERVES = ("workspace.json", "themes", "snippets")

workspace.json parce que c'est de l'état, pas de la configuration. themes/ et snippets/ parce que ce sont tes fichiers : le manifeste ne les décrit pas, et les supprimer à chaque reconstruction serait une perte silencieuse.

3. `pin` — les empreintes ne s'écrivent pas

$ uv run --project 90-meta/tooling 90-meta/tooling/bootstrap.py pin
dataview epingle en 0.5.70
templater-obsidian epingle en 2.24.3
obsidian-git epingle en 2.38.6
quickadd epingle en 2.21.0
...

Pour chaque plugin qui n'est pas encore épinglé, pin interroge l'API GitHub pour la dernière version, télécharge les fichiers, calcule leurs empreintes, et réécrit le manifeste en place.

Trois décisions valent d'être notées :

Un plugin déjà épinglé n'est pas retouché. Relancer pin ne produit aucun changement — sinon la commande deviendrait un générateur de bruit dans l'historique git.
Écriture tout ou rien. Le manifeste est réécrit une fois, après la boucle. Si le cinquième plugin échoue, le fichier sur disque est inchangé.
Les actifs optionnels sont optionnels. styles.css n'existe pas chez tous les plugins ; son absence n'est pas une erreur, contrairement à main.js ou manifest.json.

Corollaire du premier point : pour mettre à jour un plugin, il ne suffit pas de changer le numéro de version. pin saute l'entrée puisqu'elle a déjà une version et des empreintes, et apply échouera ensuite sur une empreinte qui ne correspond plus.

La procédure est : supprimer version et sha256, puis relancer pin. Non découvrable — d'où sa présence dans le README du vault.

4. `doctor` — mesurer la dérive

$ uv run --project 90-meta/tooling 90-meta/tooling/bootstrap.py doctor
hotkeys.json : different — manifeste {'quickadd:choice:61a7…': [...]},
               vault {'quickadd:capture': [...], 'quickadd:choice:61a7…': [...]}
1 ecart(s)

La commande compare ce que render produirait avec ce qui est réellement sur disque, et sort en code 1 s'il y a au moins un écart — de quoi la mettre dans un script.

Quatre choix de conception la rendent utilisable au quotidien :

La comparaison porte sur le JSON analysé, pas sur le texte. Une différence d'indentation ou d'ordre de clés n'est pas une dérive. Sans ça, la commande hurlerait au premier passage d'Obsidian, qui réécrit les fichiers à sa façon.
L'état est hors périmètre. workspace.json n'est jamais comparé.
Les fichiers préservés sont hors périmètre. Sinon, installer un thème condamnerait doctor à sortir en erreur pour toujours.
Les plugins non gérés sont hors périmètre. C'est la règle du chapitre 8 : sans elle, le data.json d'un plugin non géré serait signalé « en trop » à chaque exécution.

Un outil de détection qui crie tout le temps ne détecte plus rien : on cesse de le lire. La valeur de doctor tient entièrement à ce qu'il puisse revenir à zéro. Chacun des quatre choix ci-dessus existe pour rendre le zéro atteignable.

5. `export` — le chemin de retour

doctor signale la dérive ; export la promeut en décision. Il lit .obsidian/ et propose le fragment de manifeste correspondant :

$ uv run --project 90-meta/tooling 90-meta/tooling/bootstrap.py export
appearance:
  theme: obsidian
  base_font_size: 16
plugins:
- id: dataview
  settings:
    enableDataviewJs: true
...
non exportable : plugins/table-editor-obsidian/data.json : réglages non gérés

Les lignes « non exportable » partent sur la sortie d'erreur. Elles matérialisent une règle simple : ce que l'outil ne sait pas exprimer, il le dit — il ne le recopie pas tel quel, et il ne le tait pas.

Sont signalés de cette façon : les réglages des plugins non gérés, les champs d'apparence qu'Obsidian écrit et que le manifeste ne connaît pas (interfaceFontFamily, translucency…), les commandes dont le raccourci a été retiré, et celles qui portent plusieurs liaisons — le manifeste ne sait en exprimer qu'une.

La propriété qui compte : le fragment doit être rechargeable

Une commande export peut sembler fonctionner tout en produisant un fragment que le manifeste refuse. C'est arrivé au vault de référence, et de trois façons à la fois : plugins était émis comme dictionnaire là où le schéma attend une liste ; un raccourci délié faisait planter la commande sur un accès à un tableau vide ; et les champs d'apparence inconnus étaient recopiés, ce qui faisait échouer le render suivant.

Trois symptômes, une seule cause : aucun test ne rejouait le fragment. Les tests vérifiaient la forme du dictionnaire produit, jamais qu'il repassait par load_manifest puis render.

Le test qui ferme les trois d'un coup est un aller-retour complet :

fragment, ignores = patch_et_ignores(racine, non_geres)
# on écrit le fragment dans un manifeste, puis on le relit et on le rend
manifeste = load_manifest(ecrire_manifeste(fragment))
rendu = render(manifeste)
assert set(rendu) == set(OBSERVE)              # mêmes fichiers
for nom in OBSERVE:
    assert json.loads(rendu[nom]) == json.loads(OBSERVE[nom])   # même contenu

Leçon généralisable : quand deux fonctions sont censées être l'inverse l'une de l'autre, le seul test qui vaut est celui qui les compose. Tester chacune séparément laisse passer exactement les incompatibilités qu'on cherche à éviter.

6. Les erreurs, et leur sortie

Toutes les commandes convergent vers un seul traitement d'erreur :

except (ManifestError, ChecksumError, DownloadError, OSError) as exc:
    print(f"echec : {exc}", file=sys.stderr)
    return 1

Ce qui suppose que toute panne prévisible se présente sous l'une de ces quatre formes. C'est un travail en soi : un manifeste absent doit lever ManifestError et non FileNotFoundError ; un YAML mal formé aussi ; une coupure réseau doit devenir DownloadError et non ConnectionResetError.

Le critère : un utilisateur ne doit jamais voir une trace d'appels Python. Une trace signifie que l'outil n'avait pas prévu le cas — et l'utilisateur, lui, ne sait pas si son vault est intact.

Récapitulatif

apply vérifie tout avant d'écrire, puis bascule par renommage avec restauration : un échec laisse le vault dans son état précédent.
PRESERVES garde workspace.json, themes/ et snippets/ d'une reconstruction à l'autre.
pin calcule les empreintes, ne retouche pas l'existant, et écrit en tout ou rien. Mettre à jour un plugin exige d'effacer version et sha256.
doctor compare du JSON analysé, ignore l'état, les fichiers préservés et les plugins non gérés — pour que le zéro reste atteignable.
export propose le fragment inverse et signale ce qu'il ne sait pas exprimer.
Deux fonctions inverses se testent en les composant, jamais séparément.

Exercices

Exercice 1 — Prédire l'état après un échec

Le manifeste déclare neuf plugins. Le réseau tombe pendant le téléchargement du sixième. Décris l'état du vault après l'échec : contenu de .obsidian/, présence de dossiers temporaires, code de sortie.

Voir la solution

.obsidian/ est strictement inchangé : la panne survient en phase 1 de preparer, où rien n'est écrit. Les cinq plugins déjà téléchargés étaient en mémoire et sont perdus, sans conséquence.

Aucun dossier temporaire ne subsiste : .obsidian.new/ avait été créé pour recevoir les plugins, et le bloc de nettoyage le supprime avant de propager l'erreur. Même s'il en restait un, l'exécution suivante commence par les effacer.

Code de sortie 1, avec un message de la forme echec : <url> : <erreur> sur la sortie d'erreur — et non une trace Python, à condition que l'erreur réseau ait bien été convertie en DownloadError.

Question subsidiaire utile : est-ce reprenable ? Non, et c'est voulu. apply retélécharge tout à chaque exécution. Un cache accélérerait et permettrait un amorçage hors ligne — c'était prévu par la spécification initiale sous la forme d'une option --from-cache, et ça n'a jamais été construit.

Exercice 2 — Un doctor qui ne revient pas à zéro

Après avoir ouvert Obsidian pour la première fois sur un vault fraîchement reconstruit, doctor signale sept écarts, dont plusieurs « en trop » : app.json, types.json, trois data.json de plugins. Comment reviens-tu à zéro, et lesquels de ces écarts ne devraient pas être là ?

Voir la solution

Revenir à zéro : lancer export, reporter les blocs proposés dans le manifeste, relancer doctor. C'est le cycle normal — Obsidian écrit de lui-même des fichiers que le manifeste ne connaissait pas encore.

Ceux qui devraient être là : app.json et types.json sont de vraies configurations, écrites par Obsidian au premier lancement. Ils rejoignent core_plugins.settings. Les data.json de plugins gérés aussi.

Ceux qui ne devraient pas y être : les data.json de plugins non gérés. S'ils apparaissent, c'est que la règle du chapitre 8 n'est pas appliquée dans doctor — et alors la commande ne pourra jamais revenir à zéro, puisque ces fichiers réapparaîtront à chaque démarrage du plugin.

Le vrai enseignement : un écart persistant n'est pas toujours une dérive de configuration, c'est parfois un défaut de l'outil de détection.

Exercice 3 — Concevoir un garde-fou

apply installe les plugins qui ont repo, version et sha256. Que se passe-t-il si le manifeste déclare un plugin avec seulement son id ? Où placerais-tu le contrôle ?

Voir la solution

Sans contrôle : l'entrée est ignorée à l'installation, mais son identifiant est quand même écrit dans community-plugins.json. Obsidian démarre, lit la liste, cherche plugins/<id>/main.js, ne le trouve pas, et affiche un plugin cassé. Le pire est que doctor retourne 0 ecart(s) : le fichier attendu par le manifeste est bien là, le fichier absent n'est attendu par personne. La commande censée détecter les problèmes certifie un vault cassé.

Où placer le contrôle : dans apply, avant tout téléchargement, avec une erreur nommant les plugins fautifs. C'est là que l'invariant a un sens : « je ne construis pas un vault que je ne peux pas rendre complet ».

Où ne pas le placer : dans load_manifest, en rendant repo obligatoire. Ce serait tentant, mais un plugin sans repo est un état légitime — c'est exactement l'état d'un plugin qu'on vient d'ajouter et que pin n'a pas encore traité. Interdire cet état casserait le flux de travail normal.

Leçon : un invariant se place là où il doit tenir, pas là où il est le plus facile à écrire.

Chapitre 09L'outillage : apply, pin, doctor, export

Objectifs du chapitre

1. La structure

2. apply — et l'atomicité

Vérifier tout avant d'écrire quoi que ce soit

Basculer par renommage

Ce qui survit à la bascule

3. pin — les empreintes ne s'écrivent pas

4. doctor — mesurer la dérive

5. export — le chemin de retour

La propriété qui compte : le fragment doit être rechargeable

6. Les erreurs, et leur sortie

Récapitulatif

Exercices

Exercice 1 — Prédire l'état après un échec

Exercice 2 — Un doctor qui ne revient pas à zéro

Exercice 3 — Concevoir un garde-fou

Chapitre 09
L'outillage : apply, pin, doctor, export

2. `apply` — et l'atomicité

3. `pin` — les empreintes ne s'écrivent pas

4. `doctor` — mesurer la dérive

5. `export` — le chemin de retour