Table of Contents

🇬🇧 English version

Matrice de publication NuGet

Ce fichier est la source de vérité unique pour les projets publiés sur NuGet, afin que les workflows (ci.yml validation, publish.yml pack + push sur tag et canal dev sur main au vert, release.yml installateurs) ne divergent pas.

Statut. La distribution est un paquet Orkeon plus treize opt-ins — quatorze paquets, la liste que pousse publish.yml — gardés par la porte scripts/check-package-closure.py et poussés vers NuGet.org par Trusted Publishing. Le nommage du scripting est fixé par l'ADR-007 : la bibliothèque de commandes est Orkeon.Cli.Commands.Scripting, l'outil orkeon Orkeon.Scripting.Cli.

Le lineup NuGet.org

Un paquet installe le framework entier ; tout le reste du lineup est un opt-in tenu à part uniquement pour ce qu'il imposerait à chaque consommateur (poids des dépendances, natifs, un amont en pré-release).

PackageId Pourquoi
Orkeon Le paquet ombrelle — les treize assemblies de la fermeture du cœur (Orkeon.Domain, Orkeon.Application, Orkeon.Infrastructure, Orkeon.Constants.{Llm,FileSystem,Configuration,Protocol}, Orkeon.Tools.Abstractions, Orkeon.Analysis.Abstractions, Orkeon.Rag.Abstractions, Orkeon.Analysis, Orkeon.Rag, Orkeon.Plugins) embarquées dans un seul nupkg. Une installation = le framework complet : agents, crews, six modes d'orchestration, 16 fournisseurs LLM, 6 stores mémoire, RAG, RaggableTree. Le découpage Clean Architecture reste une discipline d'arborescence source, pas un contrat de distribution.
Orkeon.Tools Les neuf familles d'outils intégrés (Analysis, Code, Data, Drive, Email, EventHub, FileSystem, Rag, Web) dans un seul nupkg. Séparé d'Orkeon uniquement pour le poids des dépendances : les outils Data tirent des drivers de bases de données, des bibliothèques PDF et tableur, les outils e-mail MailKit et MimeKit — des dépendances dont un consommateur qui ne s'en sert jamais ne devrait pas hériter. Dépend d'Orkeon.
Orkeon.Rag.Onnx, Orkeon.Rag.Onnx.Model Paire opt-in du reranker cross-encoder ONNX (runtime + poids int8 embarqués) — poussés ensemble ; charge native onnxruntime. Orkeon.Rag.Onnx dépend d'Orkeon ; Orkeon.Rag.Onnx.Model n'a aucune dépendance (ressources embarquées seulement) et se référence à côté de lui.
Orkeon.Tools.Embeddings.Local Embeddings locaux sur la machine (BGE-micro-v2 ONNX). Reste hors de l'ombrelle parce qu'il porte une dépendance SmartComponents en pré-release, d'un amont archivé — l'inclure dans Orkeon imposerait cette pré-release à chaque consommateur. Dépend d'Orkeon.
Orkeon.Constants.Cli Le vocabulaire CLI partagé : les noms d'options qu'acceptent les runners (RunOptionNames), leurs codes de sortie (RunExitCodes) et les clés d'état de session (SessionStateKeys), pour un outil qui pilote orkeon run. Un satellite sans dépendance (ADR-009), packé directement depuis son projet ; Orkeon.Scripting en dépend au lieu de l'embarquer.
Orkeon.Scripting Exécute un crew.ork.ts dans une application .NET, sans démarrer de processus : services.AddOrkeonScripting() puis ICrewScriptRunner.RunAsync(path), les chemins relatifs résolus contre le répertoire de travail du processus — voir Orkeon.Hosting. Embarque Orkeon.Scripting (l'hôte Jint, le pilote du bundler esbuild, les typings du DSL en ressource embarquée), Orkeon.Hosting (l'amorçage de runner que partagent orkeon run et orkeon-host). Séparé d'Orkeon parce que l'hôte de runner compose toutes les familles d'outils intégrées : il dépend d'Orkeon, d'Orkeon.Tools, d'Orkeon.Tools.Embeddings.Local et d'Orkeon.Constants.Cli (donc de leurs pilotes de bases de données, de MailKit et de la pré-release SmartComponents), plus Jint, Microsoft.Extensions.Hosting et CommandLineParser. esbuild n'est pas livré, comme pour le tool.
Orkeon.Scripting.Cli Le tool dotnet orkeon (PackAsTool ; le PackageId est la commande d'installation — ADR-007). Publiable sur NuGet.org : les natifs onnxruntime iOS/Android qu'un tool CLI ne peut jamais charger sont exclus, dans chaque paquet tool : environ 187 Mo avec les natifs de chaque runtime de bureau (win, linux, osx), sous la limite de 250 Mo de nuget.org.
Orkeon.Compliance.Vfs L'analyseur Roslyn qui refuse System.IO direct dans votre propre code (règles ORKVFS001–ORKVFS007, analyzers/dotnet/cs, DevelopmentDependency). Autonome par conception : il ne dépend de rien d'Orkeon et fonctionne dans n'importe quel projet C# — ajoutez le PackageReference, compilez, et chaque appel File.*/Directory.* devient un diagnostic.
Orkeon.Interop.AgentFramework Le pont vers Microsoft Agent Framework, dans les deux sens : un crew Orkeon comme AIAgent MAF (CrewAgent), un AIAgent MAF comme cerveau (WithAgentFrameworkAgent) ou comme outil (WithAgentFrameworkTool) d'un agent Orkeon. Séparé de Orkeon parce que la dépendance Microsoft.Agents.AI.Abstractions est un choix du consommateur. Dépend de Orkeon.
Orkeon.Hosting.Aspire L'intégration d'hébergement .NET Aspire : AddOrkeonHost (le démon orkeon-host) et AddOrkeonCrewRun (un orkeon run) comme ressources d'AppHost, WithOrkeonModel / WithOrkeonSetting pour l'environnement ORKEON_, export OTLP câblé pour que le dashboard lise le run. Séparé de Orkeon parce que Aspire.Hosting est un choix de l'AppHost. Dépend de Orkeon.
Orkeon.Cli.Abstractions Les contrats des runners interactifs et des registres de commandes (IConsoleAdapter, le registre de commandes, les options de runner). Aucune dépendance Orkeon : deux abstractions Microsoft.Extensions seulement, packé directement depuis son projet.
Orkeon.Cli.TerminalGui La console Terminal.Gui v2 en panneaux (REPL + panneau de logs) sur laquelle s'appuient des applications terminal. Séparé d'Orkeon pour sa dépendance Terminal.Gui. Dépend d'Orkeon (qui porte l'Orkeon.Constants.Configuration qu'il lit) et d'Orkeon.Cli.Abstractions.
Orkeon.Templates Les modèles dotnet new : orkeon-host (un hôte générique qui exécute une crew dans son propre processus, sur le modèle du démon orkeon-host), orkeon-plugin (un IOrkeonPlugin, un outil et son plugin.json) et orkeon-tool (une classe ToolBase). PackageType=Template : aucun assembly, aucune dépendance. Un projet généré référence Orkeon (et Orkeon.Scripting pour l'hôte) à la version du paquet de modèles, écrite en clair dans son fichier projet.

Comment les projets d'empaquetage sont construits

  • Les nupkgs du lineup sortent de projets d'empaquetage dĂ©diĂ©s sous src/packaging/ — neuf au total : les ombrelles Orkeon et Orkeon.Tools, le paquet de contenu Orkeon.Templates, plus les wrappers Orkeon.Rag.Onnx.Package, Orkeon.Tools.Embeddings.Local.Package, Orkeon.Interop.AgentFramework.Package, Orkeon.Hosting.Aspire.Package, Orkeon.Scripting.Package et Orkeon.Cli.TerminalGui.Package, qui packent les assemblies opt-in avec une dĂ©pendance nuspec sur l'ombrelle Orkeon — et, pour Orkeon.Scripting, sur Orkeon.Tools, Orkeon.Tools.Embeddings.Local et Orkeon.Constants.Cli aussi, pour Orkeon.Cli.TerminalGui sur Orkeon.Cli.Abstractions. Une dĂ©pendance sur un wrapper s'Ă©crit en rĂ©fĂ©rençant le projet qu'il enveloppe, dont le nom de restauration est l'identifiant public (celui du wrapper est <id>.Package) ; la porte de clĂ´ture accepte exactement cette rĂ©fĂ©rence. Les autres paquets du lineup sont packĂ©s directement depuis leur propre projet : Orkeon.Rag.Onnx.Model (src/rag/), le tool orkeon (src/scripting/Orkeon.Scripting.Cli), l'analyseur (src/analyzers/Orkeon.Compliance.Vfs), Orkeon.Constants.Cli et Orkeon.Cli.Abstractions, qui ne dĂ©pendent d'aucune autre assembly Orkeon. Les projets de bibliothèques embarquĂ©s sont eux-mĂŞmes IsPackable=false et leur arborescence source, leurs namespaces et leur gel PublicAPI par assembly sont intouchĂ©s ; les projets opt-in rĂ©els gardent des ProjectReference normales, les consommateurs in-repo ne voient donc aucune diffĂ©rence — seuls les wrappers portent le motif d'embarquement ci-dessous.
  • Chaque projet d'empaquetage rĂ©fĂ©rence son ou ses projets embarquĂ©s avec PrivateAssets="all" (ce qui les tient hors de la liste de dĂ©pendances du nuspec) et packe leurs DLL+XML dans lib/. Comme PrivateAssets="all" empĂŞche aussi les PackageReference externes des projets embarquĂ©s de remonter dans le nuspec, l'union de ces rĂ©fĂ©rences est re-dĂ©clarĂ©e Ă  la main dans le csproj d'empaquetage.
  • scripts/check-package-closure.py (lancĂ© par publish.yml juste après le pack, sur le tag comme sur le canal dev) fait Ă©chouer le workflow si (1) un paquet du lineup dĂ©clare une dĂ©pendance Orkeon.* hors du lineup — la classe d'incident NU1101 —, (2) les externes re-dĂ©clarĂ©s d'une ombrelle dĂ©rivent de ce que ses projets embarquĂ©s exigent rĂ©ellement, ou (3) une assembly atteinte transitivement par une assembly embarquĂ©e n'est livrĂ©e nulle part dans le lineup. Sa moitiĂ© « source » (sans nupkg) tourne aussi sur chaque pull request via scripts/check-doc-claims.py, qui Ă©choue en plus quand un projet packable n'est ni dans le lineup ni rĂ©servĂ© Ă  GitHub Packages, ou quand l'une des copies manuscrites du lineup diverge.
  • publish.yml pousse Orkeon en premier : les autres paquets du lineup en dĂ©pendent et NuGet n'ordonne pas les pushes ; pousser un dĂ©pendant d'abord exposerait un paquet dont la restauration Ă©choue.

Paquets abandonnés

Les projets suivants ne sont pas packés sous leur propre id (IsPackable=false) : Orkeon.Domain, Orkeon.Application, Orkeon.Infrastructure, les satellites Orkeon.Constants.{Llm,FileSystem,Configuration,Protocol}, Orkeon.Analysis, Orkeon.Analysis.Abstractions, Orkeon.Rag, Orkeon.Rag.Abstractions, Orkeon.Tools.Abstractions et les neuf projets Orkeon.Tools.<famille>, Orkeon.Cli, Orkeon.Cli.Commands.Scripting, Orkeon.Hosting, Orkeon.Plugins. Ceux qu'embarquent les ombrelles Orkeon et Orkeon.Tools sont toujours livrés — dans le nupkg de l'ombrelle, pas sous leur propre identifiant (Orkeon.Plugins est la treizième assembly d'Orkeon) ; Orkeon.Hosting est livré dans le paquet Orkeon.Scripting, l'opt-in qui porte la couche scripting.

Migration : le code source et les namespaces sont inchangés, le code consommateur compile donc tel quel — seule l'installation change. Désinstallez les paquets par couche et dotnet add package Orkeon (ajoutez Orkeon.Tools si vous utilisiez un paquet Orkeon.Tools.<famille> autre qu'Embeddings.Local).

État de NuGet.org

Le préfixe Orkeon (l'id nu et Orkeon.*) est réservé sur nuget.org au compte propriétaire arion-orkeon. Les paquets par couche Orkeon.Domain, Orkeon.Application et Orkeon.Infrastructure sont non listés, pas supprimés : un consommateur qui en épingle un restaure encore. Un paquet tout juste poussé n'est téléchargeable qu'une fois validé par NuGet.org ; --skip-duplicate rend un nouveau push sans effet.

Publiés sur GitHub Packages

publish.yml (tag v*) packe Orkeon.sln et pousse chaque projet packable vers GitHub Packages (nuget.pkg.github.com/Orkeon) avec --skip-duplicate. Soit le lineup NuGet.org ci-dessus plus les paquets build-time et runners qui restent hors de NuGet.org : Orkeon.ConsoleApp et Orkeon.Generators :

PackageId Commande tool Projet source
Orkeon.ConsoleApp orkeon-repl src/apps/Orkeon.ConsoleApp

L'autre tool dotnet, Orkeon.Scripting.Cli (commande orkeon), fait partie du lineup NuGet.org ci-dessus.

Canal dev : le dernier main, entre deux tags

Dès que ci.yml passe au vert sur un push vers main, le job publish-dev de publish.yml packe les mêmes projets en <X.Y.Z>-<pre>.dev.<n>, n étant le numéro de ce run de CI — <X.Y.Z>-<pre>.dev.412 est donc le commit validé par le run de CI n° 412 — et les pousse uniquement sur GitHub Packages : jamais sur NuGet.org, qui sait masquer une version mais jamais la supprimer. scripts/prune-dev-packages.sh supprime ensuite les builds dev plus anciens : le feed contient chaque version taggée plus le dernier main au vert, rien entre les deux. Une version taggée n'est jamais supprimée ; une version ni taggée ni build dev est signalée, pas supprimée — le même script les retire lors d'un passage ponctuel et relu (--include-untagged, à blanc d'abord).

  • En SemVer, <X.Y.Z>-<pre>.dev.<n> est au-dessus de <version> et sous la prĂ©-version suivante : --prerelease rĂ©sout donc le build dev. Quand la version des props n'a pas de suffixe (une release stable), les builds dev passent au patch suivant — 1.0.1-dev.<n> après 1.0.0 — car 1.0.0-dev.<n> tomberait sous la release.

  • Une version dev vit jusqu'au merge vert suivant. Un PackageReference qui en Ă©pingle une se restaure encore — NuGet lit la version comme un minimum et prend le build suivant, avec l'avertissement NU1603 (une erreur si les avertissements sont traitĂ©s en erreurs) — mais les Ă©pinglages exacts cassent : un manifeste dotnet tool, un packages.lock.json en mode verrouillĂ©. Utilisez une version flottante (*-*, et dotnet restore --force-evaluate pour passer Ă  la plus rĂ©cente) pour suivre le canal ; Ă©pinglez une version taggĂ©e pour tout usage durable.

  • Un build dev n'est pas une release : ni attestation, ni SBOM, rien sur NuGet.org.

  • Deux formes hors tag, un seul calcul. scripts/resolve-version.sh (et son jumeau PowerShell scripts/resolve-version.ps1) nomme tout build qui n'est pas une release :

    Forme D'oĂą elle vient Exemple
    <X.Y.Z>-<pre>.dev.<n> la CI seule — publish.yml et apt-dev.yml, n étant le numéro du run de CI <X.Y.Z>-<pre>.dev.412
    <version des props>.local.<horodatage> un build fait depuis un clone — scripts/package-installers.sh ou .ps1 sans version, un run manuel de release.yml <version>.local.202610080430

    <horodatage> est la date de commit du commit construit, AAAAMMJJHHMM en UTC : elle ordonne deux builds locaux, et un clone superficiel donne la même. Les changements non commis ne la déplacent pas. SemVer classe un build local au-dessus de tous les builds dev de la même version des props et sous la suivante : un poste installé depuis les sources ne passe jamais pour un build plus ancien. Sur le commit que désigne un tag v*, les mêmes scripts répondent la version du tag. dotnet build n'est pas concerné : les assemblies d'un build ordinaire portent la version des props.

  • Une fois le flux dĂ©clarĂ© comme source, --prerelease et les versions flottantes rĂ©solvent les builds dev de tous les paquets Orkeon, ceux de NuGet.org compris ; --version Ă©pingle une release.

  • GitHub Packages exige un jeton mĂŞme pour un dĂ©pĂ´t public : un personal access token (classic) avec read:packages. Lancez les commandes hors d'un clone de ce dĂ©pĂ´t — dans un clone, son nuget.config garde nuget.org comme unique source et vous obtiendriez le dernier tag Ă  la place.

Pas à pas — le jeton, les deux shells, la vérification de ce qui tourne, le retour aux releases : Suivre main : le canal dev.

dotnet nuget add source https://nuget.pkg.github.com/Orkeon/index.json \
  --name orkeon-github \
  --username <votre-utilisateur-github> \
  --password <PAT-avec-read:packages> --store-password-in-clear-text

dotnet tool install -g Orkeon.Scripting.Cli   # déjà installé : dotnet tool update, mêmes arguments
# dans un projet : <PackageReference Include="Orkeon" Version="*-*" />

Archives d'installation (release.yml)

Sur un tag v*, release.yml construit tous les artefacts d'installation, smoke-teste chaque canal d'onboarding sur un vrai runner (zip CLI Windows, service Windows, paquet Debian, tarball macOS), et seulement ensuite les attache à la GitHub Release. Le pipeline est installers → {smoke-windows, smoke-windows-service, smoke-deb, smoke-macos, msi} → release → {verify-published, apt-publish → verify-apt} (les deux derniers sont décrits dans Le dépôt apt) ; derrière ces mêmes cinq jobs, docker-image pousse l'image conteneur ghcr.io/orkeon/orkeon sur GHCR (un seul tag multi-plateforme, linux/amd64 et linux/arm64, vérifié une fois poussé) en parallèle de release, de sorte qu'un smoke rouge ne déplace ni la Release ni le tag :latest. workflow_dispatch exécute la même chose sans la publication (pas de tag, donc pas de Release à alimenter). Un tag portant un segment de pré-version (v<version>-<pre>) est publié comme prerelease, et ne devient donc jamais la release latest du dépôt ; un v<version> nu, si. Le CLI orkeon exécute les exemples (orkeon run crew.yaml exécute les crews YAML de examples/ ; orkeon run script.ork.ts exécute le DSL de scripting).

Artefact Produit par Contenu Runtime
orkeon-<version>-<rid>.tar.gz / .zip package-installers.sh (--app-set full par défaut) tous les launchers — orkeon, orkeon-slim, orkeon-repl, orkeon-host — + un esbuild partagé + l'arbre deploy/ (unité systemd, script d'enregistrement SCM, Dockerfile.host) mixte : orkeon-slim est framework-dependent, tous les autres launchers (orkeon, orkeon-repl, orkeon-host) sont self-contained
orkeon-cli-<version>-win-x64.zip package-installers.sh --app-set cli --rids win-x64 le CLI orkeon + install.cmd et install.ps1 self-contained
orkeon_<version>_amd64.deb / orkeon_<version>_arm64.deb package-deb.sh --arch amd64\|arm64 (réutilise les arbres de staging linux-x64 et linux-arm64 — un publish, deux paquets par architecture) le CLI orkeon en /usr/bin/orkeon + le REPL en /usr/bin/orkeon-repl (il utilise l'unique esbuild de /usr/lib/orkeon) self-contained ; Depends uniquement sur des bibliothèques système (libicu78 jusqu'à libicu70, libssl3t64 \| libssl3, libc6 (>= 2.34)…, donc Debian 12/13 et Ubuntu 22.04 à 26.04), jamais sur dotnet-runtime-* ; Recommends: orkeon-archive-keyring ; livre ses md5sums (dpkg -V orkeon) ; identique à l'octet près entre deux builds du même commit (SOURCE_DATE_EPOCH)
orkeon-archive-keyring_<YYYY.MM.DD>_all.deb package-keyring-deb.sh, une fois par version du trousseau (une date, comme 2026.10.04, tirée de installers/apt/keyring.version) ; les Releases suivantes rattachent les octets déjà publiés, jamais une reconstruction /usr/share/keyrings/orkeon-archive-keyring.gpg, la clé publique du dépôt apt —
orkeon-<version>-win-x64.msi build-msi.ps1 (WiX, portée per-user), moissonnant le zip CLI extrait le CLI orkeon, même publish élagué que le zip self-contained
orkeon-cli-<version>-osx-arm64.tar.gz / -osx-x64.tar.gz package-installers.sh --app-set cli --rids osx-arm64 osx-x64 (cross-publiés depuis le runner ubuntu) le seul CLI orkeon + install.sh (le canal macOS reste CLI seul) self-contained
orkeon-typings-<version>.tar.gz le job installers, étape Package the editor typings : orkeon typings exécuté sur l'orkeon de l'arbre de staging linux-x64, empaqueté de façon reproductible (noms triés, la date du commit en mtime, pas d'en-tête gzip) un dossier de même nom contenant orkeon.d.ts (le DSL .ork.ts) et orkeon-cli.d.ts (les commandes *.cmd.ts), pour qu'un projet de scripts puisse figer et comparer les typings d'une release (Réglage de l'éditeur) —
SHA256SUMS les scripts d'empaquetage du job installers (package-deb.sh rafraîchit sa propre ligne) une ligne par artefact ci-dessus sauf le MSI, plus le SBOM (orkeon-<version>.sbom.cdx.json) et l'archive des typings —
orkeon-host-<version>-win-x64.msi build-msi-service.ps1 (WiX, portée per-machine), moissonnant le zip complet extrait le seul publish self-contained orkeon-host, enregistré comme service Orkeon sous NT SERVICE\Orkeon (pas de CLI, pas de wrapper, pas de deploy/ — le paquet enregistre déclarativement) self-contained
SHA256SUMS.msi build-msi.ps1 puis build-msi-service.ps1, dans l'ordre, dans le job msi les deux MSI —

Le host de service

orkeon-host est livré dans l'archive complète (--app-set full), self-contained : un daemon supervisé par systemd ou le SCM Windows ne doit pas dépendre d'un runtime que quelqu'un peut mettre à jour sous ses pieds. Ce n'est pas un dotnet tool — il s'installe en service, il ne s'invoque pas depuis un shell. Sous Windows il est aussi livré comme MSI per-machine dédié (orkeon-host-<version>-win-x64.msi), produit distinct du MSI per-user du CLI : les deux coexistent, et le paquet enregistre le service déclarativement — même compte, mêmes chemins, même politique de redémarrage que le canal script.

Ses artefacts de déploiement vivent dans deploy/ et sont livrés dans l'archive complète aux côtés du daemon : une unité systemd (Type=notify, redémarrage sur échec — les erreurs de configuration sortent en 78 et ne bouclent pas —, durcie), un script PowerShell qui l'enregistre auprès du SCM, et un Dockerfile. Aucun des trois ne porte de secret — le jeton du bot et les clés d'API sont nommés par variable d'environnement dans la configuration et fournis par la machine, donc une unité ou une couche d'image peut être lue par n'importe qui sans rien divulguer.

Ce qu'il faut sur le poste. Aucun artefact de ce tableau n'a besoin de .NET lĂ  oĂą sa colonne Runtime dit self-contained ; ce que ceux de Windows attendent de Windows n'est pas dans cette colonne :

Artefact Sur le poste
orkeon-cli-<version>-win-x64.zip, orkeon-<version>-win-x64.zip rien à installer, aucun réglage à changer : install.cmd lance install.ps1 sur Windows PowerShell 5.1, celui que Windows livre, sous une politique d'exécution qui ne vaut que pour cette commande. install.ps1 est écrit pour 5.1 et pour PowerShell 7, et smoke-windows installe le zip du CLI sous l'un et sous l'autre. Windows peut demander de confirmer un fichier téléchargé par un navigateur (Unblock-File sur le zip l'évite) ; une politique imposée par stratégie de groupe l'emporte sur le lanceur — là, seul un script signé tourne
orkeon-<version>-win-x64.msi rien à installer. Non signé : SmartScreen annonce un éditeur inconnu et demande avant de le lancer
orkeon-host-<version>-win-x64.msi les droits d'administrateur (per-machine). Non signé non plus : même écran SmartScreen, et une invite d'élévation sans éditeur

Les étapes que suit un lecteur sont dans Avant de commencer.

Deux fichiers de sommes plutôt qu'un : le job ubuntu installers écrit SHA256SUMS avant que le MSI n'existe — il est construit plus tard, sur windows-latest. Chaque fichier de sommes est produit par le job qui a produit l'artefact qu'il couvre.

Smokes bloquants. smoke-windows (runner windows-latest) installe orkeon-cli-*-win-x64.zip et déroule la chaîne d'onboarding dessus ; smoke-deb (image ubuntu-latest standard pour amd64, un runner ubuntu-24.04-arm pour arm64 — chaque entrée refuse un runner de l'autre architecture) installe le .deb via apt, vérifie que dpkg -V orkeon n'affiche rien, déroule la même chaîne, puis retire le paquet — le smoke de l'archive linux-x64 tourne sur l'entrée amd64 ; smoke-macos (runner macos-latest, Apple Silicon) extrait l'archive osx-arm64, l'installe via install.sh et déroule la même chaîne avant de désinstaller ; le job msi déroule sa propre chaîne msiexec /i /qn → orkeon doctor --json → msiexec /x /qn, en vérifiant que le répertoire d'installation, l'entrée ARP et l'entrée de PATH utilisateur apparaissent puis disparaissent. smoke-windows-service installe le canal service du zip win-x64 complet — compte virtuel, --working-dir prouvé par un chemin de crew relatif, configuration refusée qui s'arrête sans boucler et atterrit dans le journal d'événements — et le job msi smoke le MSI service de la même façon, plus une réinstallation silencieuse de lui-même. Chacun vérifie aussi les notices de ce qu'il a installé : la licence, THIRD-PARTY-NOTICES.md et un licenses/<pack>/ par runtime .NET qu'une application embarque, les runtimes étant lus dans la charge utile elle-même (chaque *.runtimeconfig.json), pas dans une liste. Et chacun affirme le canal que nomme son installation — zip, msi, msi-host, deb ou tarball : le fichier INSTALL-CHANNEL que chaque emballage écrit à la racine de ce qu'il installe, relu par orkeon --version --verbose (dans le fichier lui-même pour le MSI service, qui n'embarque pas de CLI). Tous installent depuis les artefacts de job, jamais depuis la Release : une charge utile cassée est donc attrapée avant toute publication — le job release les a tous en needs.

Après publication. release.yml appelle release-verify.yml dans son job verify-published, juste après le job release du même run (et on peut le lancer à la demande pour un tag donné). Un déclencheur release: published ne partirait jamais : une Release créée avec le GITHUB_TOKEN du workflow ne lance aucun autre workflow. Il télécharge les assets depuis la page de la Release, vérifie que chaque asset publié a exactement une ligne dans SHA256SUMS ou SHA256SUMS.msi et que chaque ligne nomme un asset publié, contrôle chaque empreinte sans en sauter aucune, et rejoue dessus les smokes d'onboarding des deux .deb (amd64, et arm64 sur un runner ARM) et de l'archive osx-arm64 — ce qui attrape un asset qu'un envoi, un remplacement ou une altération aurait rendu différent de ce que les smokes ci-dessus ont installé. Les deux jobs de smoke extraient le tag : les smokes rejoués sont ceux du tag lui-même, et une Release plus ancienne se voit demander ce que ses propres smokes lui demandaient, pas ce que ceux de main demandent aujourd'hui. Lancé à la main sur les deux premières Releases à installeurs, il échoue par construction : elles précèdent la règle de nommage ci-dessous, et n'ont pas de paquet arm64.

smoke-macos est aussi le seul endroit où l'histoire Gatekeeper / signature est éprouvée : une bibliothèque native non signée, en quarantaine ou malformée (libtree-sitter*.dylib, onnxruntime, le binaire esbuild) est tuée au chargement, donc l'échec se produit là plutôt que dans le terminal d'un utilisateur.

Le nom du fichier .deb porte la version du tag (orkeon_<version>_amd64.deb), tandis que le champ Version: du paquet remplace - par ~ (<X.Y.Z>-<pre> devient <X.Y.Z>~<pre>) pour qu'une pré-version se classe avant sa version finale au sens de dpkg. Les deux divergent à dessein : GitHub réécrit ~ dans le nom d'un asset envoyé, et apt lit le nom du fichier dans son index, jamais dans le paquet. Aucun nom d'asset ne porte de caractère hors de [A-Za-z0-9._-] — scripts/check-release-assets.sh fait échouer sinon le job installers, et le job release avant publication — et SHA256SUMS liste donc chaque asset sous le nom avec lequel il est publié. (Les deux premières Releases à installeurs précèdent la règle : leur .deb a été publié avec . à la place de ~ alors que leur SHA256SUMS le nomme avec ~.)

Le ProductVersion du MSI, lui, perd carrément le suffixe : Windows Installer ne porte que trois champs numériques, donc build-msi.ps1 tronque <X.Y.Z>-<pre> en <X.Y.Z> pour la propriété que <MajorUpgrade> compare réellement. Rien n'est perdu en silence — la version complète survit dans le nom du .msi (orkeon-<version>-win-x64.msi) et dans la propriété ARPCOMMENTS affichée dans « Applications installées ».

Le CLI orkeon est distribué via huit canaux :

Canal Artefact Runtime Public
Tool dotnet NuGet Orkeon.Scripting.Cli (PackAsTool, commande orkeon) requiert le SDK .NET 10 (dotnet tool install) développeurs .NET. Fait partie du lineup NuGet.org ; les natifs onnxruntime iOS/Android sont exclus, ce qui le garde à environ 187 Mo avec chaque runtime de bureau, sous la limite de 250 Mo
Zip Windows + install.cmd orkeon-cli-<version>-win-x64.zip self-contained onboarding Windows — le canal recommandé
MSI Windows (per-user) orkeon-<version>-win-x64.msi self-contained Windows, installation au double-clic et entrée « Applications installées ». Un canal à la fois : le MSI refuse de s'installer par-dessus une install zip
Dépôt apt Debian / Ubuntu les paquets .deb ci-dessous, indexés sur la branche apt (canaux stable, rc, dev) self-contained Debian / Ubuntu, amd64 et arm64 — le canal recommandé : apt install, apt upgrade. Voir Le dépôt apt
Paquet Debian orkeon_<version>_amd64.deb / _arm64.deb self-contained Debian / Ubuntu sans le dépôt (une version, sans mise à jour). Livre le REPL orkeon-repl à côté du CLI
Archive macOS + install.sh orkeon-cli-<version>-osx-arm64.tar.gz / -osx-x64.tar.gz self-contained onboarding macOS aujourd'hui ; install.sh retire l'attribut de quarantaine Gatekeeper et re-signe en ad-hoc les Mach-O que codesign -v rejette
Homebrew les mêmes archives osx, via installers/homebrew/orkeon.rb self-contained macOS, une fois le tap créé — pas encore publié, voir ci-dessous
Archive d'installation multi-apps launchers orkeon / orkeon-slim orkeon self-contained, orkeon-slim framework-dependent devs voulant aussi le REPL ou l'hĂ´te de service

Homebrew — formule dans le repo, tap pas encore créé. installers/homebrew/orkeon.rb est une formule binaire : elle télécharge l'archive osx correspondant à l'architecture de la machine (on_arm / on_intel), installe la charge utile sous le libexec du Cellar, et écrit un wrapper bin/orkeon qui pointe ORKEON_ESBUILD_PATH vers l'esbuild embarqué — le même contrat que wrapper.sh.tmpl. Son bloc test do exécute orkeon doctor plutôt que orkeon --version : doctor lance aussi l'esbuild embarqué et vérifie que les bibliothèques natives sont en place, et un LLM non configuré n'y est qu'un avertissement.

version et les deux couples url / sha256 sont générés, jamais édités à la main : scripts/update-homebrew-formula.sh --release <tag> (ou --sums <fichier>) réécrit les cinq valeurs depuis le SHA256SUMS d'une release, de façon idempotente. Le fichier du dépôt est un gabarit : il porte la version fictive 0.0.0 et les empreintes littérales PLACEHOLDER_SHA256_ARM64 / PLACEHOLDER_SHA256_X64 tant que les sommes d'une release n'y sont pas écrites : une installation accidentelle échoue à la vérification plutôt que de récupérer quoi que ce soit de non vérifié.

Publier le dépôt Orkeon/homebrew-tap et y pousser la formule est une action de release, pas de CI : brew tap orkeon/tap && brew install orkeon ne résout pas avant cela. La soumission à homebrew-core et un installeur .pkg restent hors périmètre tant que le projet n'est pas signé.

Le dépôt apt

Les utilisateurs Debian et Ubuntu ajoutent une source, puis gèrent Orkeon avec apt — le côté utilisateur est dans Installer avec apt. Le dépôt vit dans ce dépôt GitHub, en deux moitiés :

  • Les paquets restent des assets de Release — les .deb que release.yml construit, smoke-teste et atteste dĂ©jĂ . Rien n'est copiĂ© ailleurs.
  • L'index signĂ© vit sur la branche orpheline apt : un rĂ©pertoire par canal (InRelease, Release, Release.gpg, Packages, Packages.gz, by-hash/SHA256/…), plus le trousseau binaire orkeon-archive-keyring.gpg Ă  sa racine pour la première mise en place. Seuls les workflows y poussent, un commit par publication ; un ruleset interdit sa suppression et tout force-push. Elle ne contient aucun .deb et ne pèse que quelques kilo-octets.

La source porte URIs: https://github.com/Orkeon/orkeon/ et Suites: raw/apt/<canal>/ — un dépôt « plat ». apt lit l'index à …/raw/apt/<canal>/, que GitHub redirige vers raw.githubusercontent.com, et résout le Filename: de chaque paquet — releases/download/<tag>/<asset> — contre la même racine : le téléchargement aboutit sur l'asset de la Release. La contrepartie est la limite de débit de GitHub sur les accès anonymes à raw (429) : apt update n'en fait qu'un avertissement, un build Docker réessaie.

Canal Répertoire Reçoit
stable stable/ chaque tag v* sans segment de pré-version — le même test qui fixe prerelease: sur la Release. Versions finales seulement : une release candidate n'y entre jamais
rc rc/ chaque tag v* : tout paquet de stable est donc aussi dans rc
dev dev/ le paquet orkeon de chaque push vert sur main, en version <X.Y.Z>~<pre>.dev.<n> ; ses assets sont sur l'unique prerelease à tag fixe apt-dev ; seuls les trois derniers builds sont gardés. Jamais publié sur NuGet.org, jamais attesté comme une release

Le fichier Release de chaque canal garde Origin: Orkeon et Label: Orkeon pour toujours (un changement obligerait chaque machine à le confirmer), fixe Suite: au chemin de la source sans son / final et ne porte pas de Codename (sinon apt avertit « Conflicting distribution »), déclare Architectures: amd64 arm64 et Acquire-By-Hash: yes, ne liste que des empreintes SHA-256, porte une Date strictement croissante (apt ignore un InRelease plus ancien que celui qu'il a) et pas de Valid-Until. L'index est produit par apt-ftparchive ; les fichiers by-hash sont élagués par les scripts de publication, qui gardent au moins trois générations.

Historique et immuabilité. Un canal liste toutes les versions encore attachées à une Release : apt install orkeon=<version> peut donc toujours revenir en arrière — sauf dev, qui garde ses trois derniers builds. Une stanza publiée ne change jamais d'empreinte pour un même paquet, une même version et une même architecture : le générateur refuse. release.yml ne réécrit jamais les assets d'un tag publié — il crée la Release en brouillon, y attache les assets, puis la publie, et les Releases sont immuables — car un asset renvoyé ferait échouer chaque machine en « Hash Sum mismatch ».

La chaîne sur un tag. release publie la Release ; apt-publish (environnement GitHub apt-signing, le seul endroit qui détient la sous-clé de signature, dans les secrets APT_SIGNING_KEY et APT_SIGNING_PASSPHRASE, déployable depuis les tags v*, et depuis main pour le seul canal dev) ajoute les nouveaux paquets à rc — et à stable pour une version finale —, signe l'index et pousse la branche apt ; verify-apt rejoue ensuite mot pour mot le bloc d'installation du guide, dans des conteneurs neufs Debian 12 et 13 et Ubuntu 22.04, 24.04 et 26.04, en amd64 et arm64 : installation, montée depuis la version précédente, désinstallation dans l'ordre documenté. Il réessaie tant que raw sert encore l'index précédent. Un contrôle hebdomadaire compare l'index aux assets, l'échéance de la clé au seuil de 180 jours, et vérifie la disponibilité de raw.

La chaîne dev est apt-dev.yml, lancé par chaque exécution de la CI qui passe sur un push vers main (la garde du job publish-dev de publish.yml). Il publie le jeu CLI pour linux-x64 et linux-arm64 seulement, assemble les deux .deb avec package-deb.sh --arch, et n'appelle jamais dotnet pack, publish.yml ni un flux NuGet. La version est celle de publish-dev, avec ~ pour - dans le champ Debian : <X.Y.Z>~<pre>.dev.<numéro de la CI>, asset orkeon_<X.Y.Z>-<pre>.dev.<n>_<arch>.deb. Ensuite, dans l'environnement apt-signing, scripts/apt/publish-dev.sh :

  1. crée la prerelease apt-dev si elle manque (jamais « latest » ; son tag, posé sur le commit du premier build, ne bouge jamais) ;
  2. reconstruit dev/ à partir de celui publié, en ajoutant le nouveau build et en retirant tout build qui n'est pas parmi les trois plus récents, et le signe — un build déjà indexé, ou plus ancien que les trois gardés, ne publie rien ;
  3. attache les deux paquets sous leurs noms uniques, avant que l'index puisse les citer ; un asset qu'un index cite déjà n'est jamais remplacé ;
  4. pousse dev/ sur la branche apt ;
  5. supprime les assets des builds que l'index poussé ne liste pas — jamais avant.

Le paquet du trousseau est attaché une fois à apt-dev, puis ses octets sont réutilisés. workflow_dispatch avec publish laissé à false construit les deux paquets et ne publie rien ; avec publish: true, depuis main, il publie la dernière exécution verte de la CI sur main. apt-dev doit exister avant que les Releases deviennent immuables : l'immuabilité ne lie que les Releases créées après elle, et un apt-dev immuable ne pourrait plus retirer d'anciens builds. Ses règles sont prouvées sans réseau par scripts/apt/test-publish-dev.sh dans la CI, et apt-index.yml fait monter de vrais clients apt d'un build dev à un plus récent.

La maintenance hors tag passe par apt-maintenance.yml (workflow_dispatch, lancé depuis un tag pour que la règle de l'environnement l'admette), avec les mêmes scripts, le même environnement et le même groupe de concurrence qu'apt-publish : resign signe de nouveau les deux canaux avec une Date plus récente ; yank <paquet>=<version>[/<arch>] retire une stanza et signe de nouveau ; seed <tag>… indexe des assets publiés avant que le dépôt existe.

Procédure : prolonger ou faire tourner la sous-clé de signature

La sous-clé est valable deux ans et se prolonge au moins six mois avant son échéance — la CI échoue sous 180 jours. Une clé expirée casse apt update sur toutes les machines, sans repli.

  1. Sur la machine hors ligne, prolonger la sous-clé (gpg --quick-set-expire <empreinte primaire> 2y <empreinte sous-clé>) — ou, pour une rotation, en ajouter une nouvelle (gpg --quick-add-key <empreinte primaire> ed25519 sign 2y).
  2. Exporter le certificat public, remplacer installers/apt/orkeon-archive-keyring.asc, changer installers/apt/keyring.version, et mettre à jour le SHA-256 du trousseau dans SECURITY.md, SECURITY.fr.md et les deux pages d'installation (la garde de la CI vérifie leur accord).
  3. La Release suivante publie le nouvel orkeon-archive-keyring ; les utilisateurs le reçoivent par apt upgrade. Une prolongation s'arrête là ; lancer apt-maintenance.yml en mode resign si l'index doit être signé de nouveau avant le tag suivant.
  4. Pour une rotation seulement, une Release plus tard : le mainteneur remplace APT_SIGNING_KEY par la nouvelle sous-clé, exportée seule (gpg --export-secret-subkeys <empreinte sous-clé>!). L'ancienne sous-clé expire, ou est révoquée.

Procédure : retirer une version (yank)

  1. Lancer apt-maintenance.yml en mode yank, depuis un tag, en nommant <paquet>=<version>[/<arch>].
  2. Vérifier que l'InRelease du canal sur la branche apt porte une Date plus récente et ne liste plus la version ; après un apt update, apt-cache policy orkeon ne la montre plus.
  3. Seulement ensuite, et seulement si besoin, supprimer l'asset de sa Release. Toute purge d'assets de Release commence par cette procédure — un asset indexé qui disparaît devient un 404 pour chaque utilisateur.

Procédure : révoquer la clé

  1. Publier le certificat de révocation (gardé hors ligne depuis la création de la clé) dans SECURITY.md, SECURITY.fr.md et les pages d'installation.
  2. Geler la publication : aucun tag, aucun lancement d'apt-maintenance.yml, jusqu'à ce que la nouvelle clé soit en place.
  3. Créer une nouvelle clé et un nouveau trousseau, publier leur empreinte et leur SHA-256 comme dans la procédure de prolongation, et signer l'index avec la nouvelle sous-clé. Les utilisateurs doivent télécharger eux-mêmes la nouvelle clé (les premières lignes du bloc d'installation) — le seul cas où ils doivent agir.

Procédure : la clé a expiré

Les utilisateurs voient EXPKEYSIG à chaque apt update, et le canal ne se met plus à jour. Prolonger la sous-clé (procédure ci-dessus, étape 1), publier le certificat et une nouvelle version d'orkeon-archive-keyring, puis lancer apt-maintenance.yml en mode resign. Une machine dont le trousseau est antérieur à la prolongation ne peut pas vérifier le nouvel index : elle réinstalle le trousseau par les premières lignes du bloc d'installation, ou installe le nouvel orkeon-archive-keyring_<YYYY.MM.DD>_all.deb téléchargé depuis sa Release (sudo apt install ./orkeon-archive-keyring_<YYYY.MM.DD>_all.deb).

Toutes les variantes sont construites depuis le même csproj src/scripting/Orkeon.Scripting.Cli et partagent l'unique esbuild embarqué. Les autres launchers CLI restent framework-dependent — install.sh et install.ps1 détectent ce cas et affichent les commandes d'installation du runtime plutôt que d'échouer au premier lancement.

Charge utile du publish. Chaque publish de src/ et examples/ élague les grammaires tree-sitter qu'Orkeon ne charge jamais (31 bibliothèques natives → 26, sur win-x64), via src/Directory.Build.targets. Désactivation : -p:OrkeonPruneTreeSitterGrammars=false. Chaque artefact du tableau ci-dessus porte la charge élaguée, MSI compris — ce qui garde aussi stables ses GUID de composants WiX d'une mise à jour à l'autre.

Build-time / interne (pas des paquets autonomes)

PackageId Note
Orkeon.Generators Source generator — consommé au build. GitHub Packages uniquement.
Orkeon.Host IsPackable=false — livré uniquement comme binaire orkeon-host dans les archives de release.

Câblage de la publication

  • Tout le packaging et le push NuGet vivent dans publish.yml (tag v*) : le garde tag/version et scripts/check-release-readiness.py (section CHANGELOG coupĂ©e, PublicAPI livrĂ©e), un build Release et les tests unitaires + rapides, dotnet pack Orkeon.sln pilotĂ© par IsPackable, le gate scripts/check-package-closure.py sur les artefacts packĂ©s, un push de tout vers GitHub Packages avec --skip-duplicate (rĂ©-exĂ©cutions idempotentes), puis le lineup NuGet.org (le tableau ci-dessus, Orkeon en premier) vers NuGet.org. Son job publish-dev packe en plus chaque push vert sur main, pour GitHub Packages seulement (voir Canal dev plus haut). ci.yml valide (build + tests) et ne package rien ; release.yml construit les archives d'installation et l'image conteneur, sans packaging NuGet.
  • L'authentification NuGet.org est le Trusted Publishing (OIDC) — aucune clĂ© API longue durĂ©e. Une politique nuget.org (dĂ©pĂ´t Orkeon/orkeon, workflow publish.yml) permet Ă  NuGet/login d'Ă©changer le jeton OIDC du job contre une clĂ© Ă©phĂ©mère ; les Ă©tapes sont conditionnĂ©es Ă  la variable de dĂ©pĂ´t NUGET_USER (le profil nuget.org propriĂ©taire de la politique). Les deux sont en place et Ă©prouvĂ©es — les pushes des paquets par couche sont passĂ©s par ce chemin ; si la variable venait Ă  disparaĂ®tre, les Ă©tapes Ă©mettraient un avertissement et ne feraient rien plutĂ´t que de faire Ă©chouer le tag. Étendre le lineup NuGet.org est une dĂ©cision de mainteneur consignĂ©e d'abord dans cette matrice (et reflĂ©tĂ©e dans le LINEUP de check-package-closure.py, la boucle de push du workflow, les arguments du gate de fermeture et le processus de release de CONTRIBUTING — check-doc-claims.py Ă©choue dès qu'une copie diverge), jamais une retouche de workflow en passant.
  • publish.yml refuse un tag qui ne correspond pas Ă  la version de src/Directory.Build.props : un tag qui re-pack une version de props inchangĂ©e ferait sauter chaque push par --skip-duplicate et ne publierait rien.
  • Provenance et SBOM. Les deux workflows attestent ce qu'ils publient avec actions/attest-build-provenance (SLSA v1, signĂ© via l'instance publique de Sigstore et inscrit dans son journal de transparence) : publish.yml chaque *.nupkg d'un tag (les builds du canal dev ne sont pas attestĂ©s), release.yml chaque archive, .deb et MSI. L'image ghcr.io/orkeon/orkeon que release.yml pousse sur GHCR n'est pas attestĂ©e. Tous deux gĂ©nèrent un SBOM CycloneDX de Orkeon.sln juste après le build (outil dotnet CycloneDX, version Ă©pinglĂ©e, aucune action tierce) — orkeon-<version>.sbom.cdx.json — et le couvrent par la mĂŞme attestation : un asset de release Ă  cĂ´tĂ© des archives et une ligne dans SHA256SUMS pour release.yml, un artefact de run nommĂ© sbom pour publish.yml. Comment vĂ©rifier tout cela, et pourquoi un tĂ©lĂ©chargement nuget.org doit d'abord perdre sa signature repository, est dans VĂ©rifier ce que vous installez.
  • Graphes de dĂ©pendances verrouillĂ©s. Les paquets sont construits Ă  partir de graphes de dĂ©pendances verrouillĂ©s : chaque projet de Orkeon.sln hors examples/ commite un packages.lock.json Ă  cĂ´tĂ© de lui (Directory.Build.targets), et la CI restaure en mode verrouillĂ© (RestoreLockedMode sous la variable CI), si bien qu'une restauration qui rĂ©soudrait autrement un paquet transitif Ă©choue au lieu de dĂ©river. Deux restaurations restent volontairement dĂ©verrouillĂ©es : la voie build-test-net11 (un autre SDK, pour voir ce qu'il rĂ©sout) et toute restauration avec un identifiant de runtime — le dotnet publish -r par RID de package-installers.sh/.ps1 et de Dockerfile.runners (le fichier de verrouillage commitĂ© enregistre le graphe sans RID) : une telle restauration Ă©crit son propre fichier de verrouillage dans le dossier intermĂ©diaire du projet et ne réécrit jamais celui qui est commitĂ©. Le contenu des modèles dotnet new ne livre aucun fichier de verrouillage.
  • La version provient de src/Directory.Build.props, la source de vĂ©ritĂ© unique : aucun projet ne la surcharge, et le garde-fou de tag du workflow de publication refuse tout tag v* qui la contredit. Le canal dev en dĂ©rive son <X.Y.Z>-<pre>.dev.<n>, un build fait depuis un clone son <version>.local.<horodatage> (voir Canal dev plus haut).