Canaux, publication et mises à jour

Statut : canaux, publication et client de mise à jour dans le jeu. Décision de l'auteur (2026-10-10) : les zips sont envoyés à la main sur le serveur du site (prism.am, prism-admin release add), qui publie une liste publique releases.json ; les joueurs mettent à jour depuis le jeu, contre ce flux du site, jamais contre GitHub (le dépôt est privé : pas de jeton dans le client). Le flux signé (vérifié côté client, voir plus bas : la signature minisign des zips), Velopack, OVH et la signature Authenticode des exécutables restent des phases ultérieures (docs/etude-mises-a-jour.md, branche docs/autoupdate-study) ; ce qui suit décrit ce qui existe.

Deux canaux, deux installations

Le fichier channel est lu une seule fois, au démarrage (apps/desktop/src/app/install.rs, appelé par startup.rs). Il tient en un mot (stable ou pbe, casse et espaces ignorés). Absent : stable, sans message. Illisible, trop long ou mot inconnu : stable et une ligne dans la console (PRISM: … is not usable). Le canal n'est jamais compilé : c'est ce qui permet de promouvoir les mêmes octets d'exécutable de PBE vers stable.

Les deux canaux tournent côte à côte. Une seconde instance du même canal ne démarre pas : elle ramène la fenêtre de la première au premier plan (recherche des fenêtres visibles dont le titre est celui du canal, dans un prism.exe), ou, si aucune fenêtre n'existe encore, affiche « Prism est déjà lancé » puis quitte. --write-ts-packages, --check-library, --scan-library, --bench-gameplay et les --smoke-* ne prennent jamais ce verrou.

Les variables PRISM_MODS_DIR et PRISM_SKINS_DIR fonctionnent comme avant. Réglages → À propos affiche le canal et la version (Cargo.toml, la même pour les zips PBE et stable d'un même build).

Profil WebView2 hors du dossier de l'exécutable

Avant, WebView2 écrivait prism.exe.WebView2 à côté de l'exe : un outil qui remplace le dossier de l'exe aurait effacé les réglages. Il est maintenant dans <données>\webview2 (app/profile.rs). Au premier lancement, un ancien prism.exe.WebView2 est copié (jamais déplacé) vers <données>\webview2 :

• seulement si la cible n'existe pas (une cible présente gagne toujours, même vide) ; idempotent ;
• copie dans webview2.copying puis renommage : une copie interrompue ne laisse pas un faux profil ;
• les fichiers verrou du navigateur (lockfile, LOCK) sont ignorés, tout autre fichier illisible est journalisé (PRISM: profile file … not copied) et ignoré ; le reste est copié ;
• une variable WEBVIEW2_USER_DATA_FOLDER déjà définie est respectée (rien n'est migré).

Conséquence : supprimer le dossier de données remet maintenant aussi les réglages à zéro (avant, ils survivaient). Les diagnostics (--smoke-*, --bench-gameplay) gardent leur profil jetable dans le dossier temporaire.

Couper une release avec la CI GitHub (écartée pour l'instant)

Cette voie existe (.github/workflows/release.yml, jamais exécuté) mais n'est pas celle retenue : voir « Couper une release et la publier sur le site (sans CI : la voie retenue) ».

Tout passe par .github/workflows/release.yml (déclenché à la main : Actions → release → Run workflow, ou par un tag v*). Le workflow ne se lance jamais seul sur un push.

1. Changer la version du workspace (Cargo.toml) si c'est une nouvelle version ; fusionner dans la branche à publier.
2. PBE : lancer le workflow avec channel = pbe. Il construit, vérifie, empaquette Prism-<version>-pbe.<n>-windows-x64.zip (channel = pbe), et publie la release v<version>-pbe.<n> en prerelease avec SHA256SUMS.txt (case « draft » pour la créer en brouillon).
3. Tester ce zip (décompresser, lancer prism.exe, pastille PBE et dossier PrismNG-PBE).
4. Promouvoir sans recompiler (le chemin normal vers stable) :

gh release download v0.1.0-pbe.3 --pattern "Prism-*-pbe.3-windows-x64.zip" --dir dist
.\tools\promote.ps1 -Zip dist\Prism-0.1.0-pbe.3-windows-x64.zip -OutDir dist\stable
gh release create v0.1.0 dist\stable\Prism-0.1.0-windows-x64.zip dist\stable\SHA256SUMS.txt --title "Prism v0.1.0" --notes-file dist\stable\NOTES.md

promote.ps1 refuse un zip qui n'est pas pbe, vérifie que prism.exe correspond au SHA-256 de RELEASE.txt, écrit channel = stable, met RELEASE.txt à jour (promoted-from), reconstruit le zip Prism-<version>-windows-x64.zip, contrôle que le SHA-256 de prism.exe est inchangé et écrit SHA256SUMS.txt. Écrire soi-même NOTES.md (ou utiliser --generate-notes). Le workflow accepte aussi channel = stable (reconstruction complète), à réserver au tout premier zip ou à un cas d'urgence.

Le zip contient : prism.exe, channel, RELEASE.txt (version, canal, commit, date, SHA-256 de l'exe), LISEZMOI.txt, mods\, skins\, themes\. Un zip stable garde son nom historique ; un zip PBE porte -pbe.<n>. En local : .\tools\package.ps1 [-Channel pbe] [-Label pbe.3] [-SkipBuild]. Essai local rapide (non publié, jamais une release) : .\tools\package.ps1 -FastLocal -Channel pbe -Label localtest<sha> -Build local-test-<sha> -NoSign compile en LTO thin et 16 unités de codegen ; RELEASE.txt porte alors « NOT a release build ». Refusé avec -Seq, une signature ou -SkipBuild.

Ce que le workflow vérifie (volontairement peu)

Compilation release verrouillée (--locked, runtime statique) puis : bun run check et les tests TypeScript purs (src/lib, src/menu, src/theme : parité des langues, réglages, menus, thèmes) ; cargo test --release -p themes -p skin -p modding (le contenu livré : thèmes, skins, mods) ; les paquets TypeScript commités doivent être ceux qu'écrit l'exe qu'on vient de construire. Les tests du crate desktop ne tournent pas là : ils recompileraient toute l'application en profil de test, presque aussi long que la compilation. La suite complète et les smokes (GPU, WebView2) restent dans le flux de l'intégrateur. Le workflow n'a encore jamais tourné : première exécution à surveiller.

Coût (estimation)

Dépôt privé, plan gratuit : 2 000 minutes par mois, les minutes Windows comptent double (facteur 2 du barème GitHub). Une compilation à froid sur windows-latest : 25 à 40 min [estimation, non mesurée] ; avec le cache cargo : 8 à 15 min [estimation]. Une release PBE coûterait donc de l'ordre de 20 à 80 minutes décomptées à froid, 16 à 30 avec cache : le plan gratuit n'en offre qu'une trentaine par mois à froid. Raisons de ne pas lancer le workflow à chaque fusion.

Le client de mise à jour (Réglages → À propos → Mises à jour)

Tout est dans le crate crates/updater (aucune dépendance nouvelle : ureq, ring déjà dans l'arbre) ; l'hôte (apps/desktop/src/app/updates.rs) route les commandes de la page et les états (updateState). Chaque étape tourne sur un fil à elle, jamais sur le fil de la fenêtre, jamais pendant une partie, un aperçu ou un replay (un téléchargement en cours s'arrête quand une partie démarre ; le fichier partiel est gardé et repris).

Réglages (visibles, Réglages → À propos) : updateCheck (activé par défaut : il ne fait que lire la liste), updateChannel (vide = le canal de cette installation, stable ou pbe), updateFeedUrl (vide = le site ; PRISM_UPDATE_FEED l'emporte). Aucun n'est exporté (.pvsettings.json). L'adresse du flux doit être en https (http seulement pour localhost/127.0.0.1), et toute adresse suivie (paquet, redirection) doit avoir le même schéma, le même hôte et le même port que le flux ; 3 redirections au plus, suivies par le client lui-même. Un site injoignable ou pas encore déployé donne seulement « Mises à jour indisponibles ».

Pas de boucle (garanties)

Cause trouvée (bug signalé en direct : le jeu « se mettait à jour en boucle » et affichait une erreur d'administrateur) : un paquet téléchargé puis non installé restait dans update-staging/ et chaque lancement tentait de l'appliquer (launch_check → « appliquer le paquet prêt » → échec d'accès → au lancement suivant, de nouveau), l'échec d'un déplacement de fichier n'étant en outre pas distingué de « dossier non inscriptible » ; et un build de développement (identité inconnue) pouvait télécharger et installer. Aucune trace n'en subsistait dans l'état local au moment de l'enquête (un seul contrôle enregistré dans update-check.json, aucun update-staging ni update-state.json) : la cause est établie par lecture du code, pas par un journal. Corrigé ainsi :

• Une seule chose automatique : lire la liste (≤ 1 fois par jour ; la tentative est écrite avant la requête, donc un échec compte aussi ; une horloge mal réglée ne la rend jamais horaire).
• Télécharger et installer ne démarrent que sur clic. Le lancement n'installe plus jamais rien ; le paquet prêt attend le clic.
• Une tentative échouée est mémorisée par identité de release (canal + seq + SHA-256) dans update-check.json (dossier de données, seul fichier écrit là) avec sa raison et un retry_after de 24 h : après un redémarrage, la release est montrée « échouée, raison, pas reproposée avant … » et rien ne la retente seul. Le bouton Réessayer (le clic) efface la mémoire et retente.
• Un build d'identité inconnue (développement, ou absent de la liste) ne télécharge ni n'installe jamais : il voit l'annonce et l'adresse de la page de téléchargement à copier.
• Contrôle préalable avant le moindre octet téléchargé (et avant l'installation) : le dossier de prism.exe doit accepter un fichier créé, écrit, renommé (l'opération de l'installation) et supprimé, et prism.exe ne doit pas être en lecture seule. Échec = « Le dossier d'installation n'est pas modifiable… » (en/fr/zh), aucun téléchargement, la vraie erreur système dans « Détails » (repliés). Les erreurs sont reconnues par code brut (5 accès refusé, 19, 32 violation de partage, 33, 1314, 740 élévation requise), jamais par leur texte, qui est dans la langue de Windows.
• Nettoyage (au démarrage et avant un contrôle, sans toucher aux données) : extraction inachevée, paquet déjà installé, partiels de plus de 7 jours, marqueur « version à l'essai » obsolète, sondes, jeton périmé. Une installation qui échoue jette son paquet.
• Relance : --after-update <pid> <jeton> ; le jeton est à usage unique (update-relaunch, lu puis supprimé, 2 minutes), sans jeton valide le marqueur est ignoré ; chaîne plafonnée à 1 : un processus relancé ne relance pas avant d'avoir montré son interface ; si la relance échoue, message sans erreur système (« redémarrez Prism »).

Le flux releases.json (contrat du site)

Par version : channel, seq, build, publishedAt (ou date), url (relative au site ou absolue), sha256, size, notesMd (ou notes), notesEnMd, commit, semver, builtFromBuild, withdrawn / status: "withdrawn", signature (facultatif, voir plus bas). Les champs inconnus sont ignorés ; une entrée inutilisable est écartée seule. L'ordre d'un canal est seq, jamais build (libellé libre, jamais analysé). Même seq que l'installé : rien à faire. Un « dernier » plus ancien que l'installé (retiré) : jamais de rétrogradation. Un autre canal : sa dernière version est toujours proposée, avec l'avertissement que le dossier de données change (PrismNG ↔ PrismNG-PBE : le channel du paquet déplace l'installation).

Quelle version est installée

Le seq est attribué par l'outil du site après la construction du zip : le zip ne peut pas toujours le porter. Le jeu le déduit, de la source la plus sûre à la moins sûre :

1. son propre enregistrement (update-state.json, à côté de l'exe), écrit quand ce client a installé la version, avec le SHA-256 de l'exe installé : il ne compte que tant que l'exe en cours a ce hash (un zip décompressé à la main par-dessus l'invalide) ;
2. seq: dans RELEASE.txt si le paquetage l'a reçu (package.ps1 -Seq N) ; ignoré si la liste connaît ce seq avec un autre commit ;
3. le commit de RELEASE.txt contre celui de la liste (préfixe, 7 à 40 hexadécimaux ; plusieurs correspondances : celle dont le build est l'étiquette du paquetage, sinon le plus petit seq) ;
4. l'étiquette (label: = pbe.3) égale à un build.

Rien ne correspond : « Non reconnue » : la dernière version est annoncée seulement (adresse de la page de téléchargement), jamais téléchargée ni installée. L'état est « Version non reconnue » (jamais « À jour », qui serait trompeur) avec une bulle d'une ligne, la dernière version du canal (sinon de l'autre), l'adresse copiable et le bouton « Ouvrir la page de téléchargement » (l'hôte ouvre l'adresse du flux, la page n'en nomme jamais une) ; flux injoignable : « Mises à jour indisponibles » ; build reconnu et à jour : « Prism est à jour ». Pour que le jeu se reconnaisse toujours, publier avec --commit (celui de RELEASE.txt) ou donner -Seq au paquetage (voir la procédure plus bas).

Signature minisign (la clé Prism)

Chaque release est signée par l'auteur avec minisign : la signature porte sur le zip lui-même (mode pré-haché BLAKE2b de minisign), avec un commentaire de confiance qui lie l'identité de la version : channel=pbe seq=1 build=v0.1.0-pbe.1 sha256=<SHA-256 du zip> (couvert par la signature globale : on ne peut pas le remplacer). Le fichier <zip>.minisig est publié à côté du zip (convention : <url du zip>.minisig, servi par /files/<canal>/). Aucun champ de flux, aucun changement du site.

Le client vérifie après le téléchargement et avant de décompresser quoi que ce soit (crates/updater/src/signature.rs, crate minisign-verify, MIT) : le .minisig (4 Ko au plus, mêmes règles https/hôte/redirections que le zip) doit être valide sous une clé de TRUSTED_KEYS sur le fichier téléchargé, et son commentaire de confiance doit dire cette version : canal, seq, SHA-256 du fichier et build de l'entrée du flux (une signature authentique d'une autre version, ancien seq ou autre canal, est donc refusée : pas de rejeu). Absent, illisible, tronqué, d'une autre clé, fichier modifié ou mauvaise identité : refus, le zip est supprimé, rien n'arrive dans update-staging/files, l'interface dit pourquoi. Avec une clé embarquée il n'y a pas de repli vers « non signée » ; TRUSTED_KEYS vide (un fork) donne seulement « Non signée ». Réglages → À propos affiche « Signée par la clé Prism <id> » une fois vérifiée.

• Clé publique (committée : keys/minisign.pub et TRUSTED_KEYS, un test vérifie qu'elles sont identiques) : RWQsLoM1lFYu6qNoyW3uT2vS6gUZyMSqTvUNBjiTwREhRivuky4jwd/B, identifiant EA2E569435832E2C.
• Clé secrète : C:\Users\<vous>\.ssh\prism-minisign.key (variable PRISM_SIGNING_KEY pour un autre chemin) ; ACL réduite au seul utilisateur (icacls /inheritance:r), jamais dans un dépôt, jamais copiée sur le serveur, jamais affichée. Sans mot de passe, délibérément : un mot de passe empêcherait les workers de signer ; le compromis est que quiconque lit ce fichier signe en votre nom. Sauvegardez ce fichier hors ligne (clé USB) : le perdre = plus aucune mise à jour valide pour les copies déjà installées (elles ne font confiance qu'à cette clé) ; il faudrait réinstaller à la main une version qui en embarque une autre.
• Rotation : TRUSTED_KEYS est une liste. Publier d'abord une version (signée par l'ancienne clé) qui embarque aussi la nouvelle, puis signer avec la nouvelle, puis retirer l'ancienne d'une version suivante.
• Signer : .\tools\sign-release.ps1 -Zip <zip> -Channel pbe -Seq 1 -Build v0.1.0-pbe.1 (aussi appelé par package.ps1 quand -Seq est donné et que la clé existe ; -NoSign pour s'en passer) : outil crates/updater/examples/release_sign.rs (keygen, sign, verify), puis vérification indépendante avec le crate minisign contre keys/minisign.pub. Un zip repaqueté par promote.ps1 change de hash : le re-signer (autre seq, autre canal).
• Publier : envoyer le zip ET <zip>.minisig dans le dossier des versions du serveur (même dossier, data/releases/<canal>/), voir « Couper une release ».

Installation, sauvegarde, retour arrière

Un prism.exe en cours se renomme sous Windows (il ne s'écrase ni ne se supprime ; prouvé par un test avec une copie d'un programme système en cours d'exécution). Tout reste à côté de l'exe, jamais dans le dossier de données (sauf update-check.json, l'heure de la dernière vérification) :

update-staging/download/…zip.partial   le zip pendant le téléchargement (repris)
update-staging/files/…                 le paquet décompressé (règles d'archive du téléchargeur : ni `..`, ni chemin absolu, ni lien) et contrôlé
update-staging/ready.json              écrit en dernier : le paquet est complet
update-backup/<seq>/files/…            chaque fichier remplacé, tel qu'il était (les deux dernières sauvegardes sont gardées)
update-backup/<seq>/manifest.json      remplacés / ajoutés
update-state.json                      version installée, compteur de lancements, dernier retour arrière

Le paquet doit contenir prism.exe (en-tête MZ) et un fichier channel égal au canal annoncé ; les noms update-* sont réservés. Politique des dossiers livrés (mods\, skins\, themes\) : un fichier du paquet remplace le même chemin (le contenu livré suit le jeu) et l'ancien est gardé dans update-backup/<seq>/ s'il diffère ; tout ce que le paquet ne contient pas n'est jamais touché ni supprimé (dossiers et fichiers ajoutés par le joueur) ; un fichier livré qu'une version supprime reste (le retirer demande le manifeste de hachage de la phase suivante). Les modifications sur place d'un fichier livré sont donc écrasées mais sauvegardées.

Au lancement, avant la fenêtre : le compteur de lancements d'une version fraîchement installée augmente ; l'interface prête (ready) le remet à zéro. Deux lancements de suite sans atteindre l'interface : au troisième, les fichiers sont remis (les fichiers fautifs vont dans update-backup/<seq>/failed/), l'ancienne version redémarre et Réglages → À propos le dit. Une installation interrompue (coupure, processus tué) est annulée au lancement suivant (le manifeste est écrit avant le premier déplacement). Le nouveau processus attend la fin de l'ancien (--after-update <pid>) avant de prendre le verrou d'instance et le profil WebView2. Limite : le garde-fou tourne dans le nouvel exe ; un exe qui ne se charge même pas ne peut pas se remettre lui-même (restaurer update-backup/<seq>/files/prism.exe). Le programme suppose que l'exe s'appelle prism.exe et que son dossier est inscriptible (pas dans Program Files : sinon « dossier non inscriptible »).

Vérifier et réparer l'installation (Réglages → À propos → Mises à jour)

Le bouton « Vérifier l'installation » compare les fichiers livrés de l'installation à la liste signée de sa release (FILES.sha256, écrite par tools/package.ps1 en dernier, dans le zip, donc couverte par la signature minisign ; promote.ps1 la régénère quand il réécrit channel / RELEASE.txt). Il ne touche à rien : il lit, compte et affiche les écarts (manquant, modifié, illisible). Les mods, skins, thèmes, le dossier de données et tout fichier hors de la liste ne sont jamais lus, signalés ni supprimés.

• Aucune liste (installation antérieure à cette fonction) : le jeu le dit et ne propose pas de réparation. Une mise à jour ajoute la liste.
• Liste abîmée : même message ; une mise à jour en écrit une nouvelle.
• Réparer télécharge la release installée depuis le site (préflight d'accès, vérification du hachage et de la signature comme pour une mise à jour), l'extrait dans update-staging/repair/ et ne remet que les fichiers voulus. Un fichier manquant est toujours remis. Un fichier modifié n'est remis que si la case « Restaurer aussi les fichiers que j'ai modifiés » est cochée (décochée par défaut, à chaque réparation). Les versions remplacées vont dans update-backup/repair-<ms>/, pas supprimées.
• La réparation ne touche ni l'installation enregistrée, ni le paquet en attente, ni l'état de retour arrière. Si prism.exe a été remplacé, le jeu demande de le redémarrer.
• Limites, à connaître : la liste locale fait foi pour la vérification (quelqu'un qui modifie la liste peut masquer un écart) ; la réparation, elle, utilise la liste du paquet signé. La réparation est refusée pendant une partie et pour un build inconnu (une version de développement n'en a pas).

Quoi de neuf après une mise à jour

Après une mise à jour (ou un premier lancement), le jeu montre une fois les notes des versions que le joueur n'a pas encore vues, lues dans le journal installé à côté de prism.exe (CHANGELOG.md, ou CHANGELOG.fr.md en français). Aucun réseau. Décision et lecture du journal : crates/updater/src/whats_new.rs ; hôte, fenêtre et marqueur : apps/desktop/src/app/whats_new.rs.

• Ordre : le journal est du plus récent au plus ancien ; on affiche les sections des versions plus récentes que la dernière version vue, dans cet ordre. Une version absente du journal n'affiche que la version qui tourne ; une rétrogradation n'affiche rien.
• Premier lancement : rien n'est affiché, la version est seulement mémorisée dans whats-new.json (dossier de données). Une version déjà vue n'est jamais réaffichée.
• La version n'est mémorisée qu'une fois la fenêtre affichée ; un arrêt brutal avant l'affichage la redonne au lancement suivant.
• Jamais pendant une partie, un aperçu, un replay, un entraînement ou une édition de skin : la fenêtre attend, par pas de 2 s, que l'état redevienne libre. Le menu n'est jamais bloqué.
• Après un retour arrière (rolled_back dans update-state.json), rien n'est affiché.
• Mise à jour à la main (zip recopié) sans update-state.json ni whats-new.json : traitée comme un premier lancement, donc silencieuse. Le jeu ne peut pas distinguer ce cas d'une installation neuve.
• Réglage : Réglages → À propos → Mises à jour, « Afficher les nouveautés » (activé par défaut). Le lien « Quoi de neuf » affiche à tout moment les notes de la version installée, sans rien mémoriser.
• Textes : français et anglais depuis le journal correspondant ; le chinois et le coréen affichent les textes anglais de l'interface et du journal.

Couper une release et la publier sur le site (sans CI : la voie retenue)

1. .\tools\package.ps1 -Channel pbe -Label pbe.4 [-Seq N] (le seq ne sert qu'à la reconnaissance : release next-seq du site, si l'outil l'offre). RELEASE.txt porte la version, le canal, l'étiquette, le seq s'il est donné, le commit, la date et le SHA-256 de l'exe.
2. Envoyer le zip sur le serveur ; prism-admin release add --channel pbe --build "PBE 0004" --zip … --commit <commit de RELEASE.txt> --notes …. Le jeu des joueurs voit la version à leur prochain lancement (la fenêtre s'ouvre), ou au prochain contrôle quotidien, ou par « Rechercher ».
3. Promouvoir sans recompiler : .\tools\promote.ps1 -Zip <zip pbe> produit le zip stable (le seq: du PBE y est retiré : le site attribue celui de stable), puis le publier de la même façon avec --channel stable. Retirer une version : prism-admin release withdraw (elle disparaît de la liste ; un client qui l'avait vue ne la télécharge plus).

.github/workflows/release.yml reste dans le dépôt mais la décision de l'auteur est de ne pas utiliser la CI GitHub pour l'instant.

Ce qui n'est pas prouvé

Testé : tout le crate contre un vrai serveur HTTP local (flux, zip, hash faux, signature minisign valide / d'une autre clé / fichier modifié / commentaire de rejeu (autre seq, canal, build) / absente / tronquée / trop grande, version retirée, téléchargement coupé puis repris, zip-slip, même seq, changement de canal, redirections vers un autre hôte), l'installation, le retour arrière, et le renommage d'un exécutable en cours. Non prouvé, seul un vrai passage sur le site le montre : le TLS et les en-têtes réels du site (Range, Content-Range, redirections de Caddy), la reconnaissance d'une version publiée avec les vrais champs, le redémarrage réel (nouveau processus, mutex, WebView2) et l'application au lancement. Aucun prism.exe n'a été lancé pour ce travail.

Suite

1. Sauvegarder la clé secrète minisign hors ligne ; décider de la rotation.
2. Manifeste de hachage des dossiers livrés, « Dupliquer pour personnaliser », pierres tombales (retirer un fichier livré).
3. Signature des exécutables (le crochet PRISM_SIGN_CERT existe, il manque le certificat), deltas, déploiement progressif. L'installeur Windows (amorce WebView2 comprise) existe : docs/installateur.md (il installe dans un dossier inscriptible, ce que l'updater ci-dessus exige, et se répare ou se met à jour par-dessus une installation mise à jour dans le jeu).