Livrer

Ce parcours sert à livrer une nouvelle version, du projet entier ou d'un seul module, puis à la publier sur le canal public. Vous y venez quand une version est prête et que vous voulez que l'agent déroule la livraison à votre place.

Ce que vous demandez à l'agent

💬 Vous demandez à l’agent

« Prépare la livraison du module site en patch et montre-moi le plan. »

→ L’agent appelleeffortless_release_plan

• bump = patch
• stack = site

💬 Vous demandez à l’agent

« Quel serait le tag si on livrait le projet entier en mineur ? »

→ L’agent appelleeffortless_release_plan

• bump = minor

💬 Vous demandez à l’agent

« Configure la livraison du module site : build avec pnpm build, artefacts dans dist/*.zip. »

→ L’agent appelleeffortless_release_delivery_set

• stack = site
• build_command = pnpm build
• artifacts = dist/*.zip

💬 Vous demandez à l’agent

« Active le tag et la mise à jour de la documentation dans la configuration de release. »

→ L’agent appelleeffortless_release_config_set

• tag = true
• update_docs = true

💬 Vous demandez à l’agent

« Déclare acme/site-dev comme dépôt interne et acme/site comme dépôt public pour le module site. »

→ L’agent appelleeffortless_release_channels_set

• stack = site
• internal = acme/site-dev
• public = acme/site

💬 Vous demandez à l’agent

« Livre le module site : incrémente la version, commit et push, tag, build et artefacts. »

→ L’agent appelleeffortless_release_apply

• steps = bump_version,git_flow,tag_release,delivery
• stack = site

(l'agent vous demande votre accord avant)

💬 Vous demandez à l’agent

« Publie en public la version site-v1.4.1 déjà livrée en interne. »

→ L’agent appelleeffortless_release_promote

• stack = site
• tag = site-v1.4.1
• confirm = site-v1.4.1

(l'agent vous demande votre accord avant)

💬 Vous demandez à l’agent

« Montre-moi l'historique des livraisons. »

→ L’agent appelleeffortless_deliveries

Ce que fait l'agent

Planifier une livraison

1. effortless_release_plan calcule le plan sans rien écrire : version courante et version cible, tag, dépôt, branche, fichiers de version. bump vaut patch (défaut), minor ou major. stack vise un module ; sans stack, le plan porte sur le projet entier.
2. Le tag dépend de la cible : vX.Y.Z pour le projet entier ou pour un module qui a son propre dépôt, <module>-vX.Y.Z pour un module qui vit dans le dépôt du projet.

Configurer la livraison

1. effortless_release_config_show lit la configuration de release effective.
2. effortless_release_config_set règle trois options : git_flow (étape de commit et de push), tag (création du tag) et update_docs (mise à jour de la documentation). Il en faut au moins une.
3. effortless_release_delivery_set enregistre, pour un module (ou default), la commande de build (build_command) et les artefacts à envoyer (artifacts, en globs séparés par des virgules). Sans artifacts, ceux déjà enregistrés sont conservés. Un module non déclaré est refusé.

Exécuter la livraison

Cette étape agit pour de vrai : écriture des fichiers de version, commit, push, tag, release GitHub, build. L'agent ne l'exécute qu'après votre accord explicite.

1. effortless_release_apply reçoit steps (parmi bump_version, git_flow, tag_release, update_docs, delivery), bump et, pour un module, stack.
2. Les étapes se jouent toujours dans cet ordre. Une étape en échec arrête la chaîne : les suivantes sont rapportées « non jouée ». Une étape que le moteur ne peut pas faire (par exemple sans gh) est rapportée « à faire à la main », avec ce qu'il reste à faire.
3. Incrémenter la version vérifie tous les fichiers de version avant d'en écrire un seul. Commit et push ne fusionne sur la branche principale que par avance rapide. Tag et release GitHub refuse de poser un tag sur des fichiers non commités : le tag désignerait le commit d'avant, sans la nouvelle version.
4. L'agent relit le résultat étape par étape et vous le résume.

Déclarer les canaux interne et public

1. effortless_release_channels_set règle les deux dépôts de release d'une cible (stack, ou default pour le projet entier) : internal (vide = le dépôt d'origine) et public (vide = pas de canal public). Un paramètre absent reste inchangé. Un dépôt s'écrit owner/nom.

Publier en public

La publication publique promeut une version déjà livrée en interne, telle quelle : même tag, mêmes artefacts, aucun nouveau bump. Elle est irréversible. L'agent ne la lance qu'après votre accord explicite.

1. effortless_release_promote reçoit tag (le tag déjà livré en interne), stack pour un module, et confirm, qui doit redonner exactement le même tag.
2. Le moteur télécharge la release interne, la republie sur le dépôt public et inscrit la publication au journal.

Relire l'historique

1. effortless_deliveries rend le journal des livraisons, la plus récente d'abord : date, canal, module, tag, version, dépôt, issue. Il rend aussi les canaux de chaque cible. Il ne demande pas de réseau.

Ce que vous obtenez

• Les fichiers de version à la nouvelle valeur, un commit, un tag annoté et, si le dépôt est sur GitHub et que gh est disponible, une release avec ses artefacts.
• Chaque livraison, réussie ou arrêtée, et chaque publication, s'inscrit dans .effortless/deliveries.json, versionné avec le projet.
• Dans l'app, l'écran Livraison montre le même plan, la même configuration, les canaux et l'Historique des livraisons.

Quand l'agent est refusé

Situation	Ce que dit le refus	Ce qu'il faut faire
Le projet est en mode semi-auto	release_apply rend un message « outil d'exécution désactivé » (marqué gated) ; release_promote est refusé avec release:gated	Passer le projet en mode full, puis redemander la livraison.
Le module n'existe pas	release:unknownModule (plan, exécution, canaux) ; deploiement:stackUnknown pour la configuration de livraison	Passer l'identifiant d'un module déclaré, ou default / aucun stack pour le projet entier.
Aucune étape sélectionnée	deploiement:noStepSelected	Choisir au moins une étape valide dans steps (les identifiants inconnus sont ignorés).
Une étape échoue pendant l'exécution	deploiement:applyStopped, avec le détail de l'étape en échec	Corriger la cause nommée dans le détail, puis relancer. Les étapes déjà faites ne sont pas annulées.
Tag demandé alors que des fichiers ne sont pas commités	Étape tag_release en échec : « Tag … non posé »	Rejouer avec l'étape git_flow, ou commiter d'abord.
release_config_set sans aucune option	deploiement:configNoField	Passer au moins git_flow, tag ou update_docs.
Livraison sans module précisé	deploiement:stackRequired	Passer stack ; effortless_stack_list nomme celles déclarées.
Dépôt mal écrit	release:repoInvalid	Écrire le dépôt owner/nom, ou une valeur vide pour retirer le canal.
Aucun dépôt public déclaré	release:noPublicChannel	Le déclarer avec effortless_release_channels_set.
confirm différent du tag	release:confirmMismatch	Redonner exactement le tag, après votre accord explicite.
La version n'a pas été livrée en interne	release:notInternal	Livrer d'abord la version en interne (étape « Tag et release GitHub »).
La version est déjà publique	release:alreadyPublic	Rien à faire. Pour une nouvelle version, la livrer d'abord en interne.
gh absent ou en échec pendant une publication	release:ghMissing ou release:ghFailed	Installer gh et vous y connecter, puis rejouer.