🇬🇧 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
Orkeonplus treize opt-ins — quatorze paquets, la liste que poussepublish.yml— gardés par la portescripts/check-package-closure.pyet poussés vers NuGet.org par Trusted Publishing. Le nommage du scripting est fixé par l'ADR-007 : la bibliothèque de commandes estOrkeon.Cli.Commands.Scripting, l'outilorkeonOrkeon.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 ombrellesOrkeonetOrkeon.Tools, le paquet de contenuOrkeon.Templates, plus les wrappersOrkeon.Rag.Onnx.Package,Orkeon.Tools.Embeddings.Local.Package,Orkeon.Interop.AgentFramework.Package,Orkeon.Hosting.Aspire.Package,Orkeon.Scripting.PackageetOrkeon.Cli.TerminalGui.Package, qui packent les assemblies opt-in avec une dépendance nuspec sur l'ombrelleOrkeon— et, pourOrkeon.Scripting, surOrkeon.Tools,Orkeon.Tools.Embeddings.LocaletOrkeon.Constants.Cliaussi, pourOrkeon.Cli.TerminalGuisurOrkeon.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 toolorkeon(src/scripting/Orkeon.Scripting.Cli), l'analyseur (src/analyzers/Orkeon.Compliance.Vfs),Orkeon.Constants.ClietOrkeon.Cli.Abstractions, qui ne dépendent d'aucune autre assembly Orkeon. Les projets de bibliothèques embarqués sont eux-mêmesIsPackable=falseet leur arborescence source, leurs namespaces et leur gel PublicAPI par assembly sont intouchés ; les projets opt-in réels gardent desProjectReferencenormales, 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 danslib/. CommePrivateAssets="all"empêche aussi lesPackageReferenceexternes 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é parpublish.ymljuste 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épendanceOrkeon.*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 viascripts/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.ymlpousseOrkeonen 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 :--prereleaseré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ès1.0.0— car1.0.0-dev.<n>tomberait sous la release.Une version dev vit jusqu'au merge vert suivant. Un
PackageReferencequi 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 manifestedotnet tool, unpackages.lock.jsonen mode verrouillé. Utilisez une version flottante (*-*, etdotnet restore --force-evaluatepour 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 PowerShellscripts/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.ymletapt-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.shou.ps1sans version, un run manuel derelease.yml<version>.local.202610080430<horodatage>est la date de commit du commit construit,AAAAMMJJHHMMen 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 tagv*, les mêmes scripts répondent la version du tag.dotnet buildn'est pas concerné : les assemblies d'un build ordinaire portent la version des props.Une fois le flux déclaré comme source,
--prereleaseet 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, sonnuget.configgarde 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
.debquerelease.ymlconstruit, 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 binaireorkeon-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.debet 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 :
- crée la prerelease
apt-devsi elle manque (jamais « latest » ; son tag, posé sur le commit du premier build, ne bouge jamais) ; - 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 ; - 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é ;
- pousse
dev/sur la brancheapt; - 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.
- 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). - Exporter le certificat public, remplacer
installers/apt/orkeon-archive-keyring.asc, changerinstallers/apt/keyring.version, et mettre à jour le SHA-256 du trousseau dansSECURITY.md,SECURITY.fr.mdet les deux pages d'installation (la garde de la CI vérifie leur accord). - La Release suivante publie le nouvel
orkeon-archive-keyring; les utilisateurs le reçoivent parapt upgrade. Une prolongation s'arrête là ; lancerapt-maintenance.ymlen moderesignsi l'index doit être signé de nouveau avant le tag suivant. - Pour une rotation seulement, une Release plus tard : le mainteneur remplace
APT_SIGNING_KEYpar 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)
- Lancer
apt-maintenance.ymlen modeyank, depuis un tag, en nommant<paquet>=<version>[/<arch>]. - Vérifier que l'
InReleasedu canal sur la brancheaptporte uneDateplus récente et ne liste plus la version ; après unapt update,apt-cache policy orkeonne la montre plus. - 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é
- Publier le certificat de révocation (gardé hors ligne depuis la création de la clé) dans
SECURITY.md,SECURITY.fr.mdet les pages d'installation. - Geler la publication : aucun tag, aucun lancement d'
apt-maintenance.yml, jusqu'à ce que la nouvelle clé soit en place. - 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
publishdesrc/etexamples/élague les grammaires tree-sitter qu'Orkeon ne charge jamais (31 bibliothèques natives → 26, sur win-x64), viasrc/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(tagv*) : le garde tag/version etscripts/check-release-readiness.py(section CHANGELOG coupée, PublicAPI livrée), un build Release et les tests unitaires + rapides,dotnet pack Orkeon.slnpiloté parIsPackable, le gatescripts/check-package-closure.pysur 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,Orkeonen premier) vers NuGet.org. Son jobpublish-devpacke en plus chaque push vert surmain, pour GitHub Packages seulement (voir Canal dev plus haut).ci.ymlvalide (build + tests) et ne package rien ;release.ymlconstruit 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, workflowpublish.yml) permet ĂNuGet/logind'Ă©changer le jeton OIDC du job contre une clĂ© Ă©phĂ©mère ; les Ă©tapes sont conditionnĂ©es Ă la variable de dĂ©pĂ´tNUGET_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 leLINEUPdecheck-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.ymlrefuse un tag qui ne correspond pas Ă la version desrc/Directory.Build.props: un tag qui re-pack une version de props inchangĂ©e ferait sauter chaque push par--skip-duplicateet 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.ymlchaque*.nupkgd'un tag (les builds du canal dev ne sont pas attestés),release.ymlchaque archive,.debet MSI. L'imageghcr.io/orkeon/orkeonquerelease.ymlpousse sur GHCR n'est pas attestée. Tous deux génèrent un SBOM CycloneDX deOrkeon.slnjuste après le build (outil dotnetCycloneDX, 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 dansSHA256SUMSpourrelease.yml, un artefact de run nommésbompourpublish.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.slnhorsexamples/commite unpackages.lock.jsonà côté de lui (Directory.Build.targets), et la CI restaure en mode verrouillé (RestoreLockedModesous la variableCI), 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 voiebuild-test-net11(un autre SDK, pour voir ce qu'il résout) et toute restauration avec un identifiant de runtime — ledotnet publish -rpar RID depackage-installers.sh/.ps1et deDockerfile.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èlesdotnet newne 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 tagv*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).