feat: dist upgrade --latest downloads and verifies the release from the feed, --expect pins the version (#161)

Files changed:
- CHANGES.md
- INSTALL.md
- VERSION
- instructions/upgrade-instance.md
- tools/CONTRACT.md
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/version_cmd.py
- tools/chemenu/tests/test_cli.py
- tools/chemenu/tests/test_dist_upgrade.py
- tools/chemenu/version.py

INSTALL.md

@@ -152,12 +152,14 @@ tools/wikitool version         # was läuft hier, und woher kommt es
 tools/wikitool version check   # gibt es ein neueres Release?
 ```
 
-`version check` und `version notes` sind die einzigen Befehle, die ins Netz gehen, und beide
-fragen denselben Release-Feed der Ursprungs-Instanz (`$WIKITOOL_UPDATE_URL` überschreibt; sonst
-der Wert aus dem Stamp). `version check` ist dafür da; `version notes` greift nur dann darauf
-zurück, wenn die lokale `CHANGES.md` den Eintrag nicht hat - auf einer Instanz also immer, siehe
-unten - und sagt vorher auf stderr, welche URL es fragt. Ein nicht erreichbarer Feed wird als
-Fehler gemeldet - **nie** als „aktuell" und nie als „keine Notes".
+`version check`, `version notes` und `dist upgrade --latest` sind die einzigen Befehle, die
+ins Netz gehen, und alle drei fragen denselben Release-Feed der Ursprungs-Instanz
+(`$WIKITOOL_UPDATE_URL` überschreibt; sonst der Wert aus dem Stamp). `version check` ist dafür da;
+`version notes` greift nur dann darauf zurück, wenn die lokale `CHANGES.md` den Eintrag nicht
+hat - auf einer Instanz also immer, siehe unten - und sagt vorher auf stderr, welche URL es
+fragt; `dist upgrade` fragt den Feed nur, wenn `--latest` dasteht, und lädt dann auch das Release
+herunter (siehe „Eine Instanz aktualisieren"). Ein nicht erreichbarer Feed wird als Fehler
+gemeldet - **nie** als „aktuell" und nie als „keine Notes".
 
 **Was die Versionsnummer aussagt:** kompatibel ist, was in der *linkesten von Null
 verschiedenen Stelle* übereinstimmt. `0.1.3 → 0.1.4` ist ein sicheres Update, `0.1.3 → 0.2.0`
@@ -203,9 +205,32 @@ Agent-Sitzung ausgeführt wird; eine zweite Fassung derselben Schrittfolge an di
 genau die Kopie, die irgendwann auseinanderläuft. Wer den Lauf selbst fahren will, liest dieselbe
 Datei.
 
-Was dieses Dokument beiträgt, ist die Entscheidung *davor* - welches Release, ob überhaupt, woher
-der Tarball kommt (§ „Version und Updates" und Weg A oben) - und der eine Sonderfall, den die
-Instruktion nicht abdecken kann, weil es sie dort noch nicht gibt:
+Was dieses Dokument beiträgt, ist die Entscheidung *davor* - welches Release, ob überhaupt, und
+wem die Instanz als Quelle vertraut - und zwei Sonderfälle, die die Instruktion nicht abdecken
+kann, weil es sie dort noch nicht gibt.
+
+**Das Release kommt mit einem Befehl.** `tools/wikitool dist upgrade --latest --expect <version>`
+fragt den Release-Feed, lädt Tarball und `.sha256` in ein Arbeitsverzeichnis, prüft den Tarball
+gegen die Summe und wendet ihn an; das Arbeitsverzeichnis verschwindet bei jedem Ausgang wieder,
+auch bei `--dry-run`. `<version>` ist die, die `version notes` gedruckt hat: der Feed kennt nur
+sein *neuestes* Release, und `--expect` verweigert den Lauf **vor** dem Download, wenn inzwischen
+ein neueres erschienen ist, statt es ungelesen einzuspielen. Beides zusammen entscheidet vor dem
+Download über „schon aktuell", Downgrade und Vor-Release (`-beta.N` braucht `--pre`); fehlt dem
+Release der Tarball oder die Summe, bricht der Befehl vor dem ersten Download ab und nennt die
+Release-Seite. Wer offline arbeitet oder einen Tarball vom Betreiber bekommen hat, gibt statt
+`--latest` weiter die Datei an (`dist upgrade <tarball>`).
+
+**Was die Prüfsumme leistet - und was nicht.** Die `.sha256` liegt beim selben Feed wie der
+Tarball. Sie schützt vor einer beschädigten Übertragung, nicht vor einem Feed, der selbst
+kompromittiert ist: die Echtheit eines Releases beruht auf dem Vertrauen in den Host, dessen
+Feed die Instanz fragt (`update_url` im Stamp). Es gibt keinen https-Zwang; wer einen
+`http://`-Feed konfiguriert, tut das bewusst. `$WIKITOOL_UPDATE_TOKEN` geht nur an Downloads
+auf demselben Host wie der Feed.
+
+**Beim ersten Sprung auf ein Release, das `--latest` kennt, gibt es die Option in der Instanz
+noch nicht** - die Instruktion, die dort steht, gehört zum Release, das die Instanz verlässt.
+Dann den Tarball einmal von Hand holen (Weg A oben), prüfen und `dist upgrade <tarball>` geben;
+ab dem Release danach trägt die Instanz `--latest` selbst.
 
 **Beim ersten Sprung auf `4.5.0` oder höher gibt es `dist upgrade` in der Instanz noch nicht** -
 es kam erst mit `4.5.0`. Dann das Werkzeug aus dem entpackten *neuen* Tarball verwenden, gegen die
@@ -233,9 +258,9 @@ sind. Einer Instanz, die älter ist als `.wikitool-kb.json`, fehlt die Datei gan
 **Fallstricke.** Eine Instanz ohne lokale `.wikitool-release.json` (oder eine ohne `files`-Block,
 aus der Zeit vor `4.5.0`) hat für `dist upgrade` keine Basis, gegen die es eine lokale Änderung
 erkennen könnte, und verweigert den Tausch - dafür gibt es heute keine Reparatur.
-Der Befehl lädt selbst nichts herunter: `<tarball-oder-verzeichnis>` muss vorher aus Weg A
-geholt werden, und ein Tarball muss genau ein Top-Level-Verzeichnis enthalten - die Form, in der
-`.gitea/workflows/release.yml` es baut.
+Mit `<tarball-oder-verzeichnis>` lädt der Befehl selbst nichts herunter; die Datei muss vorher
+aus Weg A geholt werden. Nur `--latest` lädt, und ein Tarball muss in beiden Fällen genau ein
+Top-Level-Verzeichnis enthalten - die Form, in der `.gitea/workflows/release.yml` es baut.
 
 Vor `4.5.0` stand hier ein rein manueller Ablauf (Maschinerie von Hand kopieren, `kb/CONTRACT.md`
 eingeschlossen, sha256-Vergleich von Hand). `dist upgrade` ersetzt genau diesen Teil; wer ihn