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
2026-09-29 22:08:00 +02:00
1 parent dd885db625
commit cf892315e6
@@ -2418,7 +2418,7 @@ Apply a stack update `dist export` produced - the write half of `version check`.

 **SYNOPSIS**

- `wikitool dist upgrade <source> [--dry-run] [--keep-local] [--take-release <path>]... [--prune] [--pre]`
+- `wikitool dist upgrade (<source> | --latest [--expect <version>]) [--dry-run] [--keep-local] [--take-release <path>]... [--prune] [--pre]`

 **PROPERTIES**

@@ -2426,23 +2426,30 @@ Apply a stack update `dist export` produced - the write half of `version check`.
 - idempotent: no
 - atomic: Yes for every refusal - nothing is written. Once writing starts it is a plain sequential file copy with no partial-state cleanup: an interruption mid-copy (killed process, disk full) can leave the tree part-old, part-new
 - budget: counted
- network: no
+- network: yes

 **EXAMPLES**

 - `tools/wikitool dist upgrade ../chemenu-7.1.0.tar.gz --dry-run`
 - `tools/wikitool dist upgrade ../chemenu-7.1.0.tar.gz`
 - `tools/wikitool dist upgrade ../chemenu-7.1.0.tar.gz --take-release tools/README.md`
+- `tools/wikitool dist upgrade --latest --expect 8.0.0 --dry-run`

 **EXIT STATUS**

 - 0    success
 - 0    The source's version equals the installed one - a no-op success
+- 1    Both `<source>` and `--latest`, or neither; or `--expect` without `--latest`
 - 1    Local `VERSION` missing, or no local `.wikitool-release.json` with a `files` block
 - 1    `.wikitool-kb.json` is missing
 - 1    A migration is already outstanding against the *installed* machinery
 - 1    The working tree is dirty
 - 1    `<source>` does not exist, fails its `.sha256`, or does not unpack to exactly one top-level directory
+- 1    `--latest`: the release feed cannot be reached, or answers with something that is not a release
+- 1    `--latest --expect`: the feed's latest release is another version than the one expected; nothing was downloaded
+- 1    `--latest`: the release publishes no archive or no `.sha256` under the expected name; nothing was downloaded
+- 1    `--latest`: an asset download fails, or the archive fails its `.sha256`
+- 1    `--latest`: the downloaded archive's `VERSION` is not the version the feed announced
 - 1    The source carries no `VERSION`, `.wikitool-release.json` or `files` block
 - 1    The source's version is older than the installed one, or a pre-release without `--pre`
 - 1    A `--take-release` path this run does not classify as locally changed - the one refusal a `--dry-run` also raises
@@ -2450,11 +2457,17 @@ Apply a stack update `dist export` produced - the write half of `version check`.

 **ON FAILURE**

+- Both `<source>` and `--latest`, or neither; or `--expect` without `--latest` -> Not transient - name exactly one source, and pass `--expect` only with `--latest`
 - Local `VERSION` missing, or no local `.wikitool-release.json` with a `files` block -> Not transient - fix the named precondition and retry. A checkout with shared git history takes stack updates with `wikitool upstream merge` instead
 - `.wikitool-kb.json` is missing -> Run `wikitool migrate baseline <version>`, then retry
 - A migration is already outstanding against the *installed* machinery -> Finish it first - `wikitool migrate status` names it - then retry
 - The working tree is dirty -> Commit or stash first, then retry
 - `<source>` does not exist, fails its `.sha256`, or does not unpack to exactly one top-level directory -> Fix the path or re-download the release archive, then retry
+- `--latest`: the release feed cannot be reached, or answers with something that is not a release -> Transient - retry once; then report the URL from the message, or take the release page's archive by hand and pass it as `<source>`
+- `--latest --expect`: the feed's latest release is another version than the one expected; nothing was downloaded -> Not transient - read `wikitool version notes` for the version the message names, then either expect that one or stop
+- `--latest`: the release publishes no archive or no `.sha256` under the expected name; nothing was downloaded -> Not transient - the message lists the assets present and the release page; report it there rather than upgrading without the checksum
+- `--latest`: an asset download fails, or the archive fails its `.sha256` -> Retry once; if it fails again, report the exact message - do not fall back to an unchecked archive
+- `--latest`: the downloaded archive's `VERSION` is not the version the feed announced -> Not transient - an inconsistent release; report it against the release page
 - The source carries no `VERSION`, `.wikitool-release.json` or `files` block -> Point `<source>` at a distribution export, then retry
 - The source's version is older than the installed one, or a pre-release without `--pre` -> Not transient - choose another source, or pass `--pre` for a pre-release
 - A `--take-release` path this run does not classify as locally changed - the one refusal a `--dry-run` also raises -> Correct it against the locally-changed list the refusal prints, then retry
@@ -2466,7 +2479,9 @@ Apply a stack update `dist export` produced - the write half of `version check`.

 **NOTES**

- Never downloads anything: `<source>` is an already-fetched export directory or `.tar.gz` release archive. An archive is verified against a sibling `.sha256` if one is present (a missing one is a WARN, not a block) and must unpack to exactly one top-level directory - the shape `.gitea/workflows/release.yml` packs.
+- Exactly one of `<source>` and `--latest` names the release. `<source>` is an already-fetched export directory or `.tar.gz` release archive and touches no network: the archive is verified against a sibling `.sha256` if one is present (a missing one is a WARN, not a block) and must unpack to exactly one top-level directory - the shape `.gitea/workflows/release.yml` packs.
+- `--latest` asks the release feed (`update_url` of the local stamp, overridable with `$WIKITOOL_UPDATE_URL`; `$WIKITOOL_UPDATE_TOKEN` is sent along) which release is latest, checks that version - `--expect`, a downgrade, a pre-release without `--pre`, already installed - before any download, then downloads the archive and its `.sha256` into a scratch directory removed on every exit. The checksum is mandatory here (a release without one, or an archive that fails it, is an error, not a WARN) and the archive's own `VERSION` must equal the feed's version. The asset URLs are the feed's own `browser_download_url` values, and the token reaches an asset download only if it is on the feed's origin. The checksum protects against transfer errors, not against a feed that is itself compromised - authenticity is the trust in the feed's host.
+- `--expect <version>` (only with `--latest`) pins the release the feed may announce: a different latest version is refused before anything is downloaded. Pass the version `wikitool version notes` was read for, in the dry run and in the real run alike.
 - The write set is exactly the *new* `.wikitool-release.json`'s `files` block, minus what an export re-seeds from a blank template every time (`kb/log.md`, `raw/.gitkeep`) or seeds once and the instance owns from then on (`.wikitool-kb.json`, `CHANGES.md`), plus the stamp itself, always rewritten.
 - Every candidate path is classified against the *local* `.wikitool-release.json`'s recorded digest: unchanged is overwritten silently, absent from the old stamp is created, and locally modified or locally deleted is **never** silently overwritten.
 - Locally changed files abort the run with the full list; the abort text names the three answers with the command line filled in, and none of them is the default.
@@ -2478,13 +2493,14 @@ Apply a stack update `dist export` produced - the write half of `version check`.
 - Reports, but does not block on, a crossed compatibility boundary.
 - The local preconditions - `VERSION`, the release stamp, `.wikitool-kb.json`, no outstanding migration, a clean working tree - are checked before the source is read. Not being a git repository at all is a WARN, not a refusal.
 - Never touches git - no commit, no push.
- `--dry-run` classifies and reports without writing; a pre-release (`-beta.N`) source needs `--pre`.
+- `--dry-run` classifies and reports without writing; a pre-release (`-beta.N`) source needs `--pre`. With `--latest` it still downloads and verifies the archive - that is the only way to classify - and removes it again.
 - An interrupted write is not resumed automatically: compare the tree against the printed classification and finish or revert by hand.
 - The closing report names `instructions/upgrade-instance.md`, which carries the order for everything after the swap and resumes at `instructions sync`.

 **SEE ALSO**

 - `wikitool version check` - finds out whether an update exists
+- `wikitool version notes` - the notes of the release `--expect` should name
 - `instructions/upgrade-instance.md` - the order after the swap
 - `INSTALL.md` § "Version und Updates" - which release, whether to take it, where the tarball comes from
 - `wikitool upstream merge` - the update path for a checkout with shared git history
@@ -2571,8 +2587,8 @@ Ask the origin's release feed whether a newer stack exists.
 **NOTES**

 - Asks the release feed for its latest release and compares it with `VERSION`: `state` is `current`, `update`, `migration` (the step crosses a compatibility boundary) or `ahead`.
- The only command whose whole job is the network call - `version notes` reaches the same feed too, but only as a fallback on a distributed instance.
- Never reached implicitly from another command, needs no key, and times out after `--timeout` seconds (default 10).
+- The only command whose whole job is the network call - `version notes` reaches the same feed too, but only as a fallback on a distributed instance, and `dist upgrade --latest` asks it which release to download.
+- Never reached implicitly from another command (`dist upgrade` asks only when passed `--latest`), needs no key, and times out after `--timeout` seconds (default 10).
 - The feed is `--url`, else `$WIKITOOL_UPDATE_URL`, else the release stamp's, else the built-in origin. `$WIKITOOL_UPDATE_TOKEN` is only needed if that feed is not readable anonymously.
 - For `update` or `migration` it prints that applying the release is a separate, manual step (`INSTALL.md` § "Eine Instanz aktualisieren").
 - Read-only; exempt from the Iteration Budget Gate.