Commandes Castor¶
Référence exhaustive des cibles Castor définies dans castor.php à la racine du dépôt. Toutes les commandes qualité et développement du projet passent par Castor — à l'exception de git et glab, qui s'utilisent directement.
Chaque cible ci-dessous s'invoque depuis la racine du projet :
Les cibles sans namespace s'invoquent simplement castor <nom>. Toutes les cibles qui exécutent quelque chose en PHP, Composer ou bin/console le font à l'intérieur du conteneur php via docker compose exec — vous n'avez rien à installer côté hôte.
Castor tourne sur son propre PHP, mais charge l'autoloader du projet
Le binaire castor embarque son interpréteur, et castor.php charge vendor/autoload.php pour exposer aux cibles les classes App\Castor\… (castor/src/). Conséquence pratique : la contrainte "php" de composer.json est bornée à la mineure (8.5.*) et Renovate a interdiction de la refiger au patch — une borne basse au-dessus du PHP embarqué rendrait toutes les cibles inutilisables d'un coup. Le pourquoi : Castor, l'autoloader du projet et la contrainte PHP.
Quand vendor/ est absent — checkout neuf, worktree tout juste créé — un repli PSR-4 minimal prend le relais pour le seul namespace App\Castor\, afin que les cibles de bootstrap (install, docker:up, wt:up) restent invocables.
Aucune panne silencieuse¶
Toutes les cibles décrites ci-dessous obéissent à une même règle de forme, qui explique l'allure de leurs messages :
Aucune panne ne doit être silencieuse. Une commande rend toujours la main, en disant concrètement et succinctement comment obtenir le comportement voulu.
Trois conséquences observables, qu'on retrouve dans les sections suivantes :
- une cible qui ne peut pas faire ce qu'on lui demande sort en
1et nomme la commande à jouer à la place — jamais un0de politesse, jamais une trace brute d'outil. C'est la forme du refus hôte-only, du bloc affiché quand le démarrage d'un worktree échoue, du refus dewt:claudesans conteneur vivant ; - aucune commande n'attend une réponse que personne ne peut donner — cf. Les confirmations hors terminal ;
- aucun repli, aucune dégradation n'est muet : le conteneur jetable de
wt:shellest annoncé avant d'être ouvert, et une configuration de worktree absente est dite plutôt que contournée en chemin — cf. Le projet Compose visé par les cibles de worktree.
Une exception, et une seule : castor wt:destroy
wt:destroy continue sur un .env.worktree absent, après l'avoir signalé. Refuser y interdirait le seul geste qui nettoie un worktree cassé, et laisserait derrière lui conteneurs, volumes et conf proxy. L'écart est donc assumé, pas oublié : cf. castor wt:destroy.
Les confirmations hors terminal¶
Trois cibles posent une question avant d'agir. Hors d'un terminal, la poser ferait pendre la commande indéfiniment : Castor laisse input()->isInteractive() à true même quand l'entrée standard n'est pas un terminal, et io()->confirm() attend alors une réponse que personne ne donnera — en CI, dans un hook ou sous un agent, c'est un blocage sans cause apparente.
Ces trois questions passent donc par confirm_or_explain() (castor.php), qui sort en 1 dès que personne ne peut répondre — entrée non-terminal, ou --no-interaction — au lieu d'attendre :
| Cible | Question posée | Échappatoire |
|---|---|---|
castor wt:destroy |
Détruire <worktree> ? La base Postgres du worktree sera supprimée. |
--yes / -y |
castor proxy:migrate |
Descendre ces stacks et recréer le réseau ? |
--yes |
castor image:upgrade-tools |
Mettre à jour les ARG dans le Dockerfile ? |
--apply |
Le message, ici pour castor wt:destroy 185 :
Cette commande demande une confirmation, et personne ne peut répondre.
(entrée non-terminal, ou --no-interaction)
Donne-la d'avance : castor wt:destroy 185 --yes
Trois propriétés à connaître :
- La commande proposée est complète et déjà substituée, ticket compris — dans un job CI, un hook ou un script, la ligne d'origine n'est pas sous les yeux de qui lit le message.
wt:destroyy reprend--forcequand il a été passé : sans lui, la commande proposée se heurterait à la garde « travail non sauvegardé » et il faudrait un troisième essai. - Les deux causes sont nommées ensemble.
is_interactive()rend aussifalsesous--no-interaction, où l'entrée est un terminal : n'en citer qu'une ferait deviner la mauvaise. - Ni « non », ni « oui » par défaut. Prendre le défaut sans rien dire ferait passer pour exécutée une commande qui n'a rien fait ; prendre « oui » exécuterait sans consentement une action jugée assez risquée pour demander confirmation.
Les questions de wt:up ne sont pas de cette famille : ce sont des propositions, dont le défaut « ne rien faire » est le comportement normal — elles ne font donc jamais sortir la cible.
La garde d'interactivité¶
Une question n'est posée que si Castor est en mode interactif et si l'entrée standard est un terminal (is_interactive(), castor.php) :
Les deux conditions sont nécessaires, et l'une d'elles n'est pas celle qu'on croit : Castor laisse input()->isInteractive() à true même quand stdin n'est pas un terminal. Un io()->confirm() posé sur cette seule foi bloque indéfiniment — la commande n'échoue pas, elle pend, et rien n'indique pourquoi. stream_isatty() seul ne suffirait pas non plus : il ignorerait --no-interaction, dont dépend tout appel programmatique d'une cible qui pose des questions.
Le critère porte sur l'entrée standard, jamais sur la sortie
castor wt:up 215 | cat ne redirige que stdout : stdin reste le terminal, donc la question est posée, et on peut y répondre. Ce qui pend sans cette garde, c'est l'entrée non-terminal.
| Contexte | isInteractive() |
stream_isatty(STDIN) |
Question posée ? |
|---|---|---|---|
Un terminal — castor wt:up 215 \| cat compris |
true |
true |
oui |
Entrée non-terminal : < /dev/null, un job CI, un hook, une session d'agent |
true |
false |
non |
castor wt:up 215 -n (--no-interaction) |
false |
— | non |
La garde est commune à toutes les questions du projet, mais ce qu'elle déclenche dépend de la question :
| Famille | Hors interactif |
|---|---|
Les trois propositions du contrôle du point de départ de wt:up |
Aucune question, aucune action. L'écart constaté est rapporté par une ligne ! du bloc = ~ + !. |
| Les trois confirmations ci-dessus | Sortie en 1, avec la commande complète à retaper. |
Stack Docker¶
Toutes les cibles qui pilotent le cycle de vie des conteneurs Docker vivent dans le namespace docker: — pour ne pas confondre castor docker:build (image PHP), castor tailwind:build (CSS) et castor docs:build (site mkdocs).
castor docker:up¶
Démarre la stack Docker en dev — FrankenPHP, Postgres et mkdocs — plus la stack mutualisée kirexo-shared (proxy sortant, Redis, RabbitMQ, Typesense, Gotenberg, Mailpit) que se partagent tous les worktrees. Les backing services dédiés au projet ne reviennent qu'en profil full (cf. castor wt:up --profile et Profils de ressources et mutualisation).
| Option | Type | Défaut | Effet |
|---|---|---|---|
--build |
flag | false |
Reconstruit les images avant de démarrer. |
--no-wait |
flag | --wait actif par défaut |
Ne pas attendre que les healthchecks soient verts avant de rendre la main. |
La cible exécute d'abord le préalable d'infrastructure commun (cf. Préalable commun aux cibles qui démarrent une stack) : sans lui, le up échoue sur network kirexo-egress declared as external, but could not be found — ou son équivalent pour kirexo-proxy. Sur un poste existant, le premier passage après la mise à jour du dépôt recrée les deux projets singletons : cf. l'encadré de cette même section.
La stack ne publie aucun port : elle est servie par le proxy hôte, qui route le dépôt principal comme un worktree nommé main. Les URL affichées en fin de cible sont donc :
| Service | URL |
|---|---|
| Application | https://app.main.localhost — https://localhost y redirige en 308 |
| Documentation (mkdocs live-reload) | https://docs.main.localhost |
| Mailpit | https://mailpit.main.localhost |
Sans worktree, castor docker:up rend toujours quelque chose
Le dépôt principal n'est pas un worktree et n'a donc jamais de castor wt:up. Sa conf de site est écrite par castor proxy:up, qui doit avoir été joué une fois sur le poste. Un développeur qui n'utilise pas les worktrees garde donc exactement le même geste qu'avant — seules les URL changent. Le raisonnement est dans Le dépôt principal est un worktree nommé main.
Cette cible est aussi ce qui pose les alias réseau php-main et docs-main
Le proxy vise ces alias, rendus par php-${WT:-main} et docs-${WT:-main} (compose.override.yaml). Des conteneurs démarrés avant le renommage des URLs portent encore les anciens alias : le TLS est valide, le routage aussi, et l'application rend 502. Un castor docker:up recrée les conteneurs et rétablit les alias — cf. Migrer un poste existant vers les URLs app..
L'accès direct à PostgreSQL, RabbitMQ et Typesense depuis l'hôte n'existe plus
Aucun de ces services ne publie de port. Pour un client SQL ou l'UI RabbitMQ, passer par docker compose exec (ou un tunnel ponctuel côté hôte) — jamais en réintroduisant un bloc ports:, qui rouvrirait la surface que ce dispositif ferme et rendrait à nouveau deux stacks incompatibles.
castor docker:down¶
Arrête la stack Docker, sans supprimer les volumes. Vos données (Postgres, Redis, etc.) sont préservées.
Le projet Compose mutualisé kirexo-shared — dont le proxy sortant egress-proxy — n'est pas arrêté : il est partagé par tous les worktrees. La cible le rappelle en fin de sortie.
castor docker:logs¶
Affiche les logs des conteneurs en continu (docker compose logs -f --tail=200). Sans argument, suit tous les services ; passez un nom de service pour filtrer.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
service |
string | '' |
Nom du service Docker Compose à suivre. Vide = tous les services. |
castor docker:sh¶
Ouvre un shell bash interactif dans le conteneur php (docker compose exec php bash).
castor docker:build¶
Reconstruit les images Docker avec --pull pour récupérer les dernières bases. Deux projets sont construits, dans cet ordre : le projet mutualisé kirexo-shared (image du proxy sortant, infra/egress/Dockerfile) puis la stack du worktree.
Le stage frankenphp_dev n'est pas reconstruit ici
L'image de développement est construite à partir de l'image publiée kirexo-dev. Une modification du Dockerfile (retrait d'un paquet, bump d'outil) n'a aucun effet tant que cette image n'est pas republiée puis le conteneur recréé — cf. Garder mon image de dev à jour.
castor docker:check-prod-image¶
Vérifie trois choses dans l'image de production (stage frankenphp_prod) :
- elle n'embarque aucun outillage IA de développement :
.agents,.mcp.json,AGENTS.md,CLAUDE.md,mate/,infra/mcp/,.claude/, ni exécutableclaudedans lePATH; - elle n'embarque pas les sources du site vitrine (
site/) ni de la documentation (docs/) ; - elle contient les assets compilés obligatoires :
public/assets/manifest.jsonetpublic/assets/importmap.json; - elle charge les extensions PHP obligatoires :
pcntl(listeprod_image_required_extensions,infra/image/check-prod-image.lib.sh), nécessaire à l'arrêt propre du worker Messenger — cf.pcntldans le stage prod.
La cible encapsule infra/image/check-prod-image.sh, le script que le job CI docker:build-prod exécute avant le push — cf. Garde-fou de l'image prod avant push de docker:build-prod.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--image |
string | '' |
Référence d'une image locale déjà construite à contrôler. Vide = construit d'abord le stage frankenphp_prod sous le tag kirexo-prod:check-local. |
Sans --image, la cible lance docker build --target frankenphp_prod --tag kirexo-prod:check-local . depuis le poste. C'est le cas qui couvre .agents/ : non versionné, ce dossier est absent d'un checkout CI mais présent sur le poste, et seul .dockerignore l'écarte du contexte de build. Un build en échec interrompt la cible.
Le script inspecte l'image avec docker run --pull never : une référence absente en local n'est pas tirée du registry, elle sort en 2.
Le tag kirexo-prod:check-local produit par cette cible est réutilisable tel quel par castor docker:smoke-prod-image --image=kirexo-prod:check-local, qui démarre alors l'image sans la reconstruire.
Terminal hôte uniquement
Le socket Docker n'est pas monté dans le conteneur de dev. Lancée dans le conteneur, la cible refuse de tourner et sort en 1 avec le message « terminal hôte » standard.
| Code de sortie | Signification |
|---|---|
0 |
Image conforme. Le script affiche ✓ Image conforme : aucun chemin interdit (9 chemins + exécutable claude contrôlés), 2 assets compilés présents, 1 extension(s) PHP requise(s) chargée(s)., puis la cible affiche Image de production conforme. |
1 |
Au moins un manquement (chemin interdit présent, chemin obligatoire absent, exécutable claude trouvé, extension PHP obligatoire absente — tous listés), ou cible lancée dans le conteneur. Le script conclut par Image NON CONFORME — N manquement(s). Vérifier .dockerignore et le stage frankenphp_prod du Dockerfile. |
2 |
Inspection impossible : image absente en local, docker run en échec, sonde incomplète. |
Le code de sortie du script est propagé tel quel.
castor docker:smoke-prod-image¶
Démarre l'image de production (stage frankenphp_prod) dans une stack prod éphémère et vérifie par HTTP qu'elle est servable. Là où castor docker:check-prod-image ne contrôle que des fichiers, cette cible fait tourner l'application avec la configuration de production (APP_ENV=prod, when@prod chargé).
La stack empile compose.yaml + compose.prod.yaml, complets, plus la surcharge infra/image/compose.smoke.yaml. Elle donne aux services php et worker la référence locale passée au script (pull_policy: never), sans redémarrage automatique (restart: "no") : un crash au boot fait échouer le démarrage au lieu de boucler jusqu'au timeout. Sans cette surcharge sur worker, l'ancre d'image de compose.prod.yaml lui ferait tirer une autre version depuis le registry. Aucun port n'est publié : les requêtes HTTP partent de l'intérieur du conteneur php vers https://localhost. Les secrets (APP_SECRET, CADDY_MERCURE_JWT_SECRET, CLAUDE_API_KEY_CIPHER_KEY, mot de passe admin) sont générés pour l'exécution et jetés avec elle.
Le script exporte aussi les cinq variables d'exécution obligatoires de compose.prod.yaml, sans quoi l'interpolation les lirait dans le .env de développement du dépôt :
| Variable | Valeur exportée |
|---|---|
KIREXO_RESERVED_DOMAINS |
localhost |
DEFAULT_URI |
https://localhost |
MAILER_DSN |
null://null (aucun e-mail réel) |
MAILER_FROM_ADDRESS |
noreply@example.org |
MERCURE_PUBLIC_URL |
https://localhost/.well-known/mercure |
La cible encapsule infra/image/smoke-prod-image.sh, le script que le job CI docker:build-prod exécute après le garde-fou de fichiers et avant le push de l'image — cf. Smoke test HTTP de l'image prod avant push de docker:build-prod.
Douze contrôles, dans cet ordre (identifiants de smoke_expected_checks, infra/image/smoke-prod-image.lib.sh) :
| # | Contrôle | Libellé affiché |
|---|---|---|
| 1 | stack-up |
Stack prod démarrée (healthchecks) — docker compose up --wait, puis attente du serveur HTTP (voir ci-dessous) |
| 2 | migrations |
Migrations Doctrine jouées |
| 3 | seed |
Seed SQL (admin, carnet, article publié) |
| 4 | home |
GET / → 200 |
| 5 | admin-login-page |
GET /admin/login → 200 |
| 6 | asset-css |
Asset CSS référencé par / → 200 — premier href="/assets/….css" de la page d'accueil |
| 7 | admin-login |
Connexion admin (CSRF + Origin) — POST /admin/login_check en 302 vers une page autre que /admin/login |
| 8 | settings-page |
GET /admin/reglages authentifié → 200 |
| 9 | analyze-button-off |
Bouton d'analyse désactivé sans clé — sur /admin/articles/{id} |
| 10 | apikey-save |
Enregistrement de la clé API factice — message Clé API Claude enregistrée. affiché |
| 11 | apikey-cipher |
Clé stockée chiffrée en base — colonne encrypted_claude_api_key non vide et ne contenant pas la clé saisie |
| 12 | analyze-button-on |
Bouton « Analyser la conformité » présent et actif |
Le contrôle stack-up ne se contente pas des healthchecks : celui du service php sonde l'admin Caddy (:2019), prête avant que FrankenPHP, en mode worker, n'ouvre les ports 80/443. Une fois docker compose up --wait réussi, le script envoie donc un GET / toutes les 2 secondes jusqu'à obtenir une réponse HTTP, quel qu'en soit le statut. Deux motifs d'échec possibles : docker compose up --wait en échec, ou serveur HTTP muet après N s (curl exit X) quand le délai KIREXO_SMOKE_HTTP_TIMEOUT est dépassé. Les contrôles suivants ne sont exécutés que si stack-up est vert.
Les contrôles anonymes (4 à 6) sont tous exécutés même si l'un échoue ; la chaîne authentifiée (7 à 12) s'arrête au premier échec. Un contrôle qui n'a pas pu s'exécuter est affiché non exécuté et compte comme un échec : le verdict n'est vert que si les douze contrôles le sont.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--image |
string | '' |
Référence d'une image locale déjà construite à démarrer, jamais tirée du registry. Vide = construit d'abord le stage frankenphp_prod sous le tag kirexo-prod:check-local. |
Sans --image, la cible lance docker build --target frankenphp_prod --tag kirexo-prod:check-local . depuis le poste, comme docker:check-prod-image ; un build en échec interrompt la cible. Enchaîner les deux contrôles sans reconstruire :
| Variable d'environnement | Défaut | Effet |
|---|---|---|
KIREXO_SMOKE_WAIT_TIMEOUT |
300 |
Délai, en secondes, accordé à docker compose up --wait pour que les healthchecks de la stack passent au vert. Au-delà, le contrôle stack-up échoue. |
KIREXO_SMOKE_HTTP_TIMEOUT |
120 |
Délai, en secondes, accordé au serveur HTTP pour répondre à GET / une fois les healthchecks verts. Au-delà, le contrôle stack-up échoue avec serveur HTTP muet après N s. |
Durée indicative : 1 à 2 minutes. La cible ne pose aucun timeout de son côté : le script va toujours jusqu'à son démontage.
Terminal hôte uniquement
Le socket Docker n'est pas monté dans le conteneur de dev. Lancée dans le conteneur, la cible refuse de tourner, sans lancer de build, et sort en 1 avec le message « terminal hôte » standard, qui rappelle que la CI rejoue ce smoke test dans le job docker:build-prod.
Stack toujours démontée, stack de dev intacte. Le projet Compose est propre à l'exécution — kirexo-smoke-local-<pid> sur un poste, kirexo-smoke-<id du job> en CI —, avec son réseau et ses volumes. À la sortie, succès, échec ou interruption (Ctrl-C), un docker compose down -v --remove-orphans le supprime ; l'image testée, elle, est conservée. La stack de dev et celles des worktrees ne sont pas touchées. Si le démontage lui-même échoue, un avertissement invite à vérifier docker compose ls -a et docker volume ls.
Diagnostic avant démontage. En cas d'échec après le démarrage de la stack, le script affiche, avant de la démonter : docker compose ps -a, les 100 dernières lignes de chaque fichier de var/log du conteneur php, le stderr des commandes en échec, puis docker compose logs des services php (300 lignes) et database (50 lignes).
Une fois les préconditions passées (celles qui sortent en 2), le script se termine toujours, après le démontage, par la ligne Durée du smoke test : N s.
| Code de sortie | Signification |
|---|---|
0 |
Image servable. Le script affiche ✓ Image servable : 12 contrôles verts., puis la cible affiche Image de production servable. |
1 |
Image non servable : au moins un contrôle en échec ou non exécuté (stack qui ne démarre pas, timeout, réponse HTTP inattendue…). Le script conclut par Image NON SERVABLE — N contrôle(s) en échec ou non exécuté(s). Également : cible lancée dans le conteneur. |
2 |
Usage invalide, Docker ou plugin docker compose indisponible, ou image absente en local — elle n'est jamais tirée du registry. |
Le code de sortie du script est propagé tel quel.
Remplace la vérification manuelle du critère 4 de #260
Ce smoke test remplace entièrement la vérification manuelle qui validait, sur l'image prod, l'enregistrement d'une clé API chiffrée et l'activation du bouton d'analyse (critère 4 du ticket #260). Il n'y a plus de script jetable à rejouer côté hôte : la même vérification est versionnée et rejouée par la CI.
castor docker:test-install¶
Joue le bundle d'installation install/ de bout en bout, comme une personne qui installe Kirexo : compose.yaml et .env.example rendus par le script de la pipeline, .env renseigné sans jamais éditer compose.yaml, aucun Castor dans la stack. Là où castor docker:smoke-prod-image démarre l'image dans la stack du dépôt (compose.yaml + compose.prod.yaml), cette cible démarre le bundle et le parcourt jusqu'à la diffusion d'un article sur un site public, puis relève l'empreinte mémoire de la stack.
La cible encapsule infra/image/install-e2e.sh (fonctions pures dans infra/image/install-e2e.lib.sh), le script que le job CI docker:test-install exécute sur tag, avant la publication du bundle — cf. Job docker:test-install. Procédure pas à pas : Jouer le test d'installation du bundle en local.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--image |
string | '' |
Référence d'une image prod locale déjà construite. Vide = construit d'abord le stage frankenphp_prod sous le tag kirexo-prod:check-local. |
--keep |
flag | false |
Ne démonte pas la stack en fin de test, succès comme échec. La commande de nettoyage est affichée (plus, sans --edge, une commande curl vers le site public). |
--edge |
string | '' |
Entrée HTTP testée. Vide = scénario complet derrière un proxy existant (infra/image/install-e2e.sh). traefik = configuration Traefik de la page « Installer Kirexo derrière un reverse proxy », derrière un vrai Traefik (infra/image/install-e2e-traefik.sh, cf. Le script infra/image/install-e2e-traefik.sh). Toute autre valeur : --edge=<valeur> inconnu : valeurs admises « traefik » ou vide. et sortie en 2, avant tout build. |
castor docker:test-install
castor docker:test-install --image=kirexo-prod:check-local
castor docker:test-install --keep
castor docker:test-install --edge=traefik
Ce que fait la cible¶
- Option
--edge, puis garde hôte. Une valeur de--edgeautre que vide outraefiksort en2. Lancée dans le conteneur, elle sort en1avec le message « terminal hôte » standard, qui rappelle que la CI rejoue ce test dans les jobsdocker:test-installetdocker:test-install-traefik, sur tag uniquement. - Image. Sans
--image,docker build --target frankenphp_prod --tag kirexo-prod:check-local ., commecastor docker:check-prod-image; un build en échec interrompt la cible. - Rendu du bundle.
sh infra/release/publish-bundle.sh render 0.0.0 var/install-e2e-bundle— le script du jobrelease:bundle-render, avec la même substitution deKIREXO_VERSION. Le dossier est supprimé puis recréé à chaque exécution.0.0.0est une version sentinelle : semver valide, jamais publiée (la première release est0.0.1). - Nom d'image. Lu dans le bundle rendu par
docker compose … config --images, les variables obligatoires étant remplies par des valeurs factices le temps de la lecture. Aucune imagekirexo-proddans le bundle : sortie en2. - Tag local.
docker tag <image> registry.gitlab.com/shaurifr/kirexo/kirexo-prod:0.0.0: le bundle tourne sans modification sur l'image locale. - Test.
sh infra/image/install-e2e.sh --bundle-dir var/install-e2e-bundle --version 0.0.0 [--keep], sans--pullni--expected-digest; avec--edge=traefik,sh infra/image/install-e2e-traefik.sh --bundle-dir var/install-e2e-bundle --version 0.0.0 [--keep]. Les variablesINSTALL_E2E_*du shell de l'hôte sont transmises au script. Ni TTY, ni timeout côté cible : le script va toujours jusqu'à son démontage.
En succès, la cible conclut par Bundle d'installation conforme. Empreinte : var/install-e2e/footprint.md, ou, avec --edge=traefik, par Bundle conforme derrière Traefik (routage, HTTPS reconnu, connexion, flux temps réel, domaines de site).
Le script infra/image/install-e2e.sh¶
sh infra/image/install-e2e.sh --bundle-dir DIR --version VERSION [--expected-digest SHA] [--pull] [--keep]
Exit : 0 = installation conforme · 1 = au moins un contrôle en échec · 2 = usage invalide ou environnement inexploitable
| Option | Effet |
|---|---|
--bundle-dir DIR |
Bundle rendu : compose.yaml et .env.example produits par publish-bundle.sh render. Jamais modifié : il est copié dans var/install-e2e/bundle/. |
--version VERSION |
Version attendue, celle de l'image construite. Doit respecter MAJEUR.MINEUR.CORRECTIF, sinon sortie en 2. |
--expected-digest SHA |
Digest de l'index multi-architecture construit par la pipeline. Absent : le contrôle est annoncé non applicable. |
--pull |
Tire les images depuis les registries, sans authentification. Sans lui, l'image kirexo-prod du bundle doit exister localement ; les images tierces absentes sont tirées. |
--keep |
Ne démonte pas la stack ; la commande de nettoyage est affichée. |
Variables d'environnement, toutes facultatives :
| Variable | Défaut | Effet |
|---|---|---|
INSTALL_E2E_HTTP_PORT |
18080 |
KIREXO_HTTP_PORT du .env rendu. |
INSTALL_E2E_HTTPS_PORT |
18443 |
KIREXO_HTTPS_PORT du .env rendu. Évite le conflit avec un 443 local. |
INSTALL_E2E_APP_DOMAIN |
app.kirexo.test |
KIREXO_DOMAIN du .env rendu. |
INSTALL_E2E_SITE_DOMAIN |
blog.exemple.test |
Domaine du site public, distinct du domaine de l'application. |
INSTALL_E2E_WORKER_REPLICAS |
2 |
KIREXO_WORKER_REPLICAS du .env rendu. L'étape S15 exige 2 instances : toute autre valeur la fait échouer, ce qui sert à provoquer un échec du harnais. |
INSTALL_E2E_TIMEOUT |
300 |
Délai, en secondes, passé à docker compose up --wait-timeout. |
INSTALL_E2E_POLL_TIMEOUT |
90 |
Délai, en secondes, des attentes : e-mail, diffusion de l'article, premier battement du worker, verrou du planificateur. |
INSTALL_E2E_SETTLE_DELAY |
30 |
Stabilisation, en secondes, avant la mesure d'empreinte (S16). |
.test est un domaine de premier niveau réservé : aucun des noms utilisés n'est résolu à l'extérieur.
La stack jouée¶
| Élément | Valeur |
|---|---|
| Projet Compose | kirexo-install-e2e (-p prime sur le name: kirexo du bundle) : aucune collision avec la stack de dev, celles des worktrees ou celle du smoke test. |
| Fichiers Compose | var/install-e2e/bundle/compose.yaml (copie du bundle), puis infra/image/install-e2e.compose.yaml. |
| Surcharge de test | infra/image/install-e2e.compose.yaml ajoute un seul service, mailpit (axllent/mailpit:latest, restart: "no"), sans port publié ni depends_on sur les services du bundle. |
| Fichier d'environnement | --env-file var/install-e2e/.env, rendu à l'étape S2 (droits 600). |
| Environnement du shell | Les variables interpolées par compose.yaml sont retirées de l'environnement de docker compose, où elles primeraient sur le .env : un TZ exporté par le shell de l'hôte fausserait le contrôle du fuseau. |
| Requêtes HTTP | curl exécuté dans le conteneur php (docker compose exec -T php curl …), avec --connect-to ::127.0.0.1:80 : tout nom d'hôte, domaine applicatif comme domaine de site, est envoyé au serveur du conteneur. Les liens absolus reçus par e-mail se suivent donc tels quels, sans réécriture. Les POST portent l'en-tête Origin: http://app.kirexo.test. |
| Boîte de capture | API de Mailpit lue par PHP, depuis le conteneur php, sur http://mailpit:8025 (réseau du projet). |
Le .env rendu à l'étape S2 part de .env.example et ne pose que ces valeurs (une ligne commentée #CLE= est décommentée) :
| Groupe | Variables posées |
|---|---|
| Domaine | KIREXO_DOMAIN=app.kirexo.test, DEFAULT_URI=http://app.kirexo.test |
| Entrée HTTP, scénario C (derrière un proxy existant), sans TLS | SERVER_NAME=:80, KIREXO_BIND_ADDRESS (127.0.0.1 en local, vide sous un démon Docker distant tcp://…), KIREXO_HTTP_PORT, KIREXO_HTTPS_PORT, TRUSTED_PROXIES=127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 |
| Isolation | KIREXO_EDGE_NETWORK=kirexo-install-e2e_edge — le nom du réseau de bord est fixe, -p ne le préfixe pas |
| Secrets, générés à chaque exécution | APP_SECRET, POSTGRES_PASSWORD, RABBITMQ_PASSWORD, CADDY_MERCURE_JWT_SECRET en hexadécimal (32 octets) ; CLAUDE_API_KEY_CIPHER_KEY en base64 de 32 octets |
MAILER_DSN=smtp://mailpit:1025, MAILER_FROM_ADDRESS=noreply@kirexo.example.org |
|
| Exploitation | TZ=Europe/Paris, KIREXO_WORKER_REPLICAS (jamais --scale) |
Volontairement non touchées : TRUSTED_HOSTS (reste non définie), RUN_MIGRATIONS (le défaut 1 du bundle est ce qui est testé), KIREXO_RESERVED_DOMAINS (dérivée de KIREXO_DOMAIN), KIREXO_VERSION (celle du bundle publié).
Les étapes¶
Chaque étape imprime ses contrôles, une ligne par contrôle : ✓ conforme, ✗ en échec, – non applicable (annoncé, jamais tu). Le test s'arrête au premier ✗.
| # | Étape | Contrôles | Ce que l'étape établit |
|---|---|---|---|
| S0 | Préconditions | docker et le plugin docker compose v2 présents ; compose.yaml et .env.example dans --bundle-dir. Sinon sortie en 2. |
L'environnement permet de jouer le bundle. |
| S1 | Version du .env.example publié |
KIREXO_VERSION présente, semver, et strictement égale à --version. |
Le .env.example publié épingle la version construite, jamais latest. |
| S2 | Rendu du .env |
Valeurs du tableau ci-dessus, puis docker compose config --quiet accepté (sinon sortie en 2, sans afficher le .env). |
Le bundle se configure par .env seul, compose.yaml restant intact. |
| S3 | Images du bundle | Toute image …/kirexo-prod:* du bundle vaut exactement …/kirexo-prod:<version>, et au moins une est présente. Images tierces ignorées. |
compose.yaml épingle l'image par KIREXO_VERSION. |
| S4 | Pull anonyme | Avec --pull : docker logout du registry, docker compose pull (échec : sortie en 2), puis digest tiré égal à --expected-digest. Sans --pull : – pull non demandé : image locale (contrôle non applicable en local), – digest de build non fourni : contrôle non applicable en local, et l'image doit exister localement (sinon sortie en 2). |
L'image se tire sans authentification, et c'est l'index construit par la pipeline qui est tiré. |
| S5 | Démarrage | docker compose up -d --wait --wait-timeout <INSTALL_E2E_TIMEOUT> (échec : sortie en 2), puis GET /login jusqu'à une réponse HTTP, 120 s au plus : la sonde de santé de php vise l'admin Caddy, prête avant le serveur HTTP. |
La stack démarre sur ses healthchecks et sert du HTTP. |
| S6 | Migrations | doctrine:migrations:up-to-date en succès ; logs du worker sans trace d'exécution de migration. |
Le schéma est appliqué automatiquement au démarrage, par l'application seule. |
| S7 | Diagnostic app:install:check |
Rejoué jusqu'au code 0, INSTALL_E2E_POLL_TIMEOUT au plus : le premier battement du worker arrive après up --wait. |
Diagnostic vert sur une installation neuve : domaines, SMTP, worker, migrations, secrets, assets — cf. app:install:check. |
| S7a | Fuseau horaire | date_default_timezone_get() vaut Europe/Paris dans php et dans chaque instance du worker. |
TZ du .env s'applique aux deux services. |
| S8 | Premier administrateur | app:user:create admin@app.kirexo.test Admin --role=both, mot de passe transmis sur l'entrée standard (exec -T) : ✓ Utilisateur créé. Même commande rejouée : refus Un compte existe déjà avec cet email. |
Le premier compte se crée par une commande docker, sans compte par défaut ; le rejeu est refusé. |
| S8a | Mot de passe oublié | POST /login/reset redirige vers /login/reset/check-email ; l'e-mail reçu contient un lien /login/reset/… dont l'hôte est app.kirexo.test (un lien vers localhost est un ✗) ; le lien rend 200 avec le formulaire de nouveau mot de passe ; son envoi redirige vers /login. |
L'e-mail est rendu par le worker, hors requête HTTP : son lien vient de DEFAULT_URI, et il fonctionne. |
| S9 | Connexion administrateur | GET /login en 200 ; connexion par /admin/login avec le nouveau mot de passe ; GET /admin en 200. |
Pages servies sur le domaine applicatif ; la réinitialisation a bien pris effet. |
| S10 | Assets | Première feuille /assets/….css et premier module /assets/….js référencés par /login : 200, Content-Type text/css / javascript, corps non vide. |
Styles et JavaScript servis par l'image. |
| S10a | Clé API Claude | Clé factice sk-ant-kirexo-test-factice-<hex> enregistrée dans /admin/reglages, message Clé API Claude enregistrée. ; colonne encrypted_claude_api_key de la table setting non vide et sans la clé en clair. La clé n'est jamais imprimée. |
La clé API s'enregistre chiffrée. |
| S11 | Invitation | Invitation de redaction@app.kirexo.test (rôle user) depuis /admin/invitations/inviter ; lien /invitation/… reçu sur app.kirexo.test ; lien en 200, acceptation (prénom, mot de passe), connexion de l'invité, GET /u en 200. |
Le transport async est consommé par le worker ; l'invitation aboutit à un compte utilisable. |
| S12 | Site public | Plugin web activé côté instance (/admin/plugins) puis côté compte (/u/reglages/plugins), ou – s'il l'est déjà ; domaine blog.exemple.test rattaché au carnet par défaut ; GET / sur ce domaine en 200, sans l'article. |
Un site public est servi sur un domaine distinct de l'application. |
| S13 | Article publié | Création depuis /u/carnets/{id}/articles/nouveau, PATCH /u/articles/{id}/autosave en 200 avec "status":"saved", POST /u/articles/{id}/publier redirigé. |
Le parcours d'écriture fonctionne sur l'image de production. |
| S14 | Article diffusé | GET / sur blog.exemple.test rejoué jusqu'à contenir le titre (INSTALL_E2E_POLL_TIMEOUT au plus) ; GET / sur inconnu.exemple.test en 404 ; app:install:check rejoué, vert. |
Le worker diffuse l'article (transport plugin_web) ; un hôte inconnu reçoit un 404 sans TRUSTED_HOSTS ; le diagnostic reste vert avec un domaine de site mappé. |
| S15 | Workers et verrou du planificateur | Exactement 2 instances worker en cours d'exécution ; dans les logs de chacune, Consuming messages from transports "scheduler_default, plugin_web, async" ; ZRANGE kirexo_scheduler_default dans Redis = 2 membres dont __write__ ; PTTL du verrou strictement positif. |
Deux workers consomment les trois transports et partagent le verrou : un seul détenteur. |
| S16 | Empreinte | Après INSTALL_E2E_SETTLE_DELAY secondes : docker stats --no-stream des conteneurs du projet, taille de l'image, espace disque des volumes du projet (docker system df -v), architecture du démon. Écrit et affiche var/install-e2e/footprint.md. |
Empreinte mesurée sur une stack chaude (un article publié, deux workers). |
| S17 | Verdict | Sentinelle END, puis décompte des lignes. |
✓ Installation conforme : N contrôles verts. ou Installation NON CONFORME — N contrôle(s) en échec. |
Répertoire de travail var/install-e2e/¶
Recréé vide à chaque exécution (var/ est ignoré par git) :
| Chemin | Contenu |
|---|---|
bundle/compose.yaml, bundle/.env.example |
Copie du bundle joué. |
.env |
.env rendu, avec les secrets du run. Droits 600, jamais affiché, jamais publié en artifact CI. |
results.txt |
Lignes ✓ / ✗ / – accumulées, plus END si la séquence est allée à son terme. |
logs/stderr.log |
Sortie d'erreur des commandes. |
logs/compose.log |
docker compose logs de tous les services, écrit en cas d'échec. |
footprint.md |
Relevé d'empreinte, prêt à coller dans install/README.md (étape S16). |
Le bundle rendu par la cible Castor vit à côté, dans var/install-e2e-bundle/, puisque le script recrée var/install-e2e/.
Diagnostic et démontage¶
- Diagnostic avant démontage. Dès que la stack a été lancée (S5 et au-delà), une sortie non nulle affiche
docker compose ps -a, le stderr des commandes en échec, puisdocker compose logs --no-color --tail 300de tous les services, worker et Mailpit compris. - Démontage garanti. À la sortie — succès, échec ou Ctrl-C —,
docker compose -p kirexo-install-e2e … down -v --remove-orphanssupprime conteneurs, réseaux et volumes du projet. Un second Ctrl-C pendant le démontage ne l'interrompt pas. Si le démontage échoue, un avertissement invite à vérifierdocker compose ls -a,docker volume lsetdocker network ls. --keep. Le démontage est sauté ; la commandedown -vcomplète est affichée, ainsi qu'une commandecurl --connect-tovers le site public.- Durée. Une fois la précondition S0 passée, le script se termine toujours par
Durée du test d'installation : N s.
| Code de sortie | Signification |
|---|---|
0 |
Installation conforme : aucune ligne ✗ et sentinelle END atteinte. |
1 |
Au moins un contrôle en échec — le verdict nomme leur nombre. Également : cible lancée dans le conteneur. |
2 |
Usage invalide ou environnement inexploitable : option manquante, version non semver, Docker ou docker compose absent, bundle incomplet, .env refusé par docker compose config, pull en échec, image locale absente, up --wait en échec, serveur HTTP muet, ou aucune image kirexo-prod dans le bundle rendu (cible Castor). |
130 |
Interruption (Ctrl-C), après démontage. |
Le code de sortie du script est propagé tel quel par la cible.
Limites¶
- Ports publiés non sondés. Toutes les requêtes partent de l'intérieur du conteneur
php: le test prouve ce que sert l'application, pas queKIREXO_BIND_ADDRESSetKIREXO_HTTP_PORTsont joignables depuis l'hôte. En local,--keeppermet de le constater à la main. - Pas de TLS. Le scénario C est joué en HTTP clair : ni l'émission de certificat (A1, A2) ni Traefik (B) ne sont exercés par ce script. Traefik l'est par
--edge=traefik(ci-dessous). - Tâches périodiques non déclenchées. Leur première échéance tombe hors de la fenêtre du test : S15 prouve le partage du verrou par deux workers, pas une exécution périodique.
- Analyse IA non jouée. Elle exigerait une vraie clé et un appel sortant à l'API Anthropic : S10a s'arrête à l'enregistrement chiffré de la clé.
- Tags laissés sur l'hôte. Le démontage ne supprime aucune image :
kirexo-prod:check-local(si la cible l'a construite) etregistry.gitlab.com/shaurifr/kirexo/kirexo-prod:0.0.0restent présents. - Architecture. En local, le test joue l'image construite pour l'architecture du poste ; la mesure de référence est celle de la CI, en amd64.
Le script infra/image/install-e2e-traefik.sh¶
Lancé par --edge=traefik, et par le job CI docker:test-install-traefik avec --pull. Il joue le bundle comme un tiers qui a déjà un Traefik : le .env reçoit exactement les lignes de la section Traefik de Installer Kirexo derrière un reverse proxy, et un vrai Traefik est démarré devant Kirexo. POSIX sh strict, comme install-e2e.sh.
sh infra/image/install-e2e-traefik.sh --bundle-dir DIR --version VERSION [--pull] [--keep]
Exit : 0 = configuration conforme · 1 = au moins un contrôle en échec · 2 = usage invalide ou environnement inexploitable
Mêmes options que install-e2e.sh, sans --expected-digest. Variables d'environnement, toutes facultatives :
| Variable | Défaut | Effet |
|---|---|---|
INSTALL_E2E_TRAEFIK_HTTP_PORT |
18180 |
KIREXO_HTTP_PORT du .env rendu. |
INSTALL_E2E_TRAEFIK_HTTPS_PORT |
18543 |
KIREXO_HTTPS_PORT du .env rendu. |
INSTALL_E2E_TIMEOUT |
300 |
Délai, en secondes, passé à docker compose up --wait-timeout. |
| Élément | Valeur |
|---|---|
| Projet Compose | kirexo-install-e2e-traefik : aucune collision avec kirexo-install-e2e ni les autres stacks. |
| Fichiers Compose | var/install-e2e-traefik/bundle/compose.yaml (copie du bundle), puis infra/image/install-e2e-traefik.compose.yaml, qui ajoute un seul service, traefik (traefik:v3.7.13@sha256:24841fe2de7304c149343d877d2923b4c8800a38ba015dea9174c23b20e344a0, restart: "no") : fournisseur Docker avec exposedbydefault=false, points d'entrée web (:80) et websecure (:443), résolveur letsencrypt dont l'autorité de certification (https://127.0.0.1:1/directory) est volontairement injoignable, socket Docker en lecture seule, aucun port publié. Traefik sert donc son certificat par défaut, auto-signé. |
| Réseau de Traefik | kirexo-install-e2e-traefik-edge, créé par le script avant up s'il n'existe pas, supprimé au démontage s'il l'a créé. |
| Domaines | app.kirexo.test (application), blog.exemple.test (site, dans la règle), inconnu.exemple.test (hors règle). |
| Requêtes HTTP | curl -k exécuté dans le conteneur php, avec --connect-to ::traefik:443 : tout nom d'hôte est envoyé à Traefik sur le réseau partagé. |
Lignes posées dans le .env rendu, en plus des secrets générés, de MAILER_DSN=null://null, MAILER_FROM_ADDRESS et TZ=Europe/Paris :
| Variable | Valeur |
|---|---|
KIREXO_DOMAIN |
app.kirexo.test |
SERVER_NAME |
:80 |
KIREXO_BIND_ADDRESS |
127.0.0.1 en local, vide sous un démon Docker distant tcp://… |
KIREXO_HTTP_PORT, KIREXO_HTTPS_PORT |
INSTALL_E2E_TRAEFIK_HTTP_PORT, INSTALL_E2E_TRAEFIK_HTTPS_PORT |
TRUSTED_PROXIES |
127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 |
KIREXO_TRAEFIK_ENABLE |
true |
KIREXO_EDGE_EXTERNAL |
true |
KIREXO_EDGE_NETWORK |
kirexo-install-e2e-traefik-edge |
KIREXO_TRAEFIK_ENTRYPOINTS |
websecure |
KIREXO_TRAEFIK_CERTRESOLVER |
letsencrypt |
KIREXO_TRAEFIK_RULE |
règle qui couvre le domaine de l'application et le domaine de site, ci-dessous |
Étapes : S0 préconditions, S1 rendu du .env (puis docker compose config --quiet), S2 pull (avec --pull), création du réseau et up -d --wait, puis les contrôles T1 routage, T3 connexion, T2 HTTPS reconnu, T4 flux temps réel, T5 domaines de site, et T6 verdict. Le contenu de chaque contrôle est décrit dans Job docker:test-install-traefik.
Répertoire de travail : var/install-e2e-traefik/ (bundle/, .env en 600 jamais publié, results.txt, logs/stderr.log, logs/compose.log écrit en cas d'échec). Diagnostic avant démontage et --keep se comportent comme pour install-e2e.sh ; la commande de nettoyage affichée par --keep supprime aussi le réseau de Traefik. Le script se termine par Durée du test derrière Traefik : N s.
Terminal hôte uniquement
Le socket Docker n'est pas monté dans le conteneur de dev. Lancée dans le conteneur, la cible refuse de tourner, sans lancer de build, et sort en 1 avec le message « terminal hôte » standard.
Proxy hôte¶
Le proxy Caddy hôte est le seul point d'entrée de tout l'environnement de développement : un conteneur unique, publié sur 127.0.0.1:80 et 127.0.0.1:443, qui route par nom d'hôte vers la stack de chaque worktree. Il vit dans son propre projet Compose (infra/proxy/compose.proxy.yaml, projet kirexo-proxy), pas dans celui d'un worktree : c'est un singleton partagé par tous les checkouts.
Le pourquoi (nommage <service>.<worktree>.localhost, longueur des noms, CA unique, cloisonnement) est dans Routage des worktrees : DNS, TLS et cloisonnement réseau.
| Cible | Où elle tourne | Effet |
|---|---|---|
proxy:up |
hôte uniquement | Crée le réseau, écrit les confs, démarre le conteneur. |
proxy:reload |
hôte uniquement | Valide puis applique la configuration. |
proxy:down |
hôte uniquement | Arrête le conteneur, conserve les volumes. |
proxy:migrate |
hôte uniquement | Recrée le réseau kirexo-proxy avec une plage d'allocation dynamique bornée. Idempotent. |
proxy:status |
hôte uniquement | Diagnostic, lecture seule. |
cert:trust |
hôte uniquement | Installe la CA du proxy dans le trust store de l'OS. |
Toutes ces cibles pilotent Docker (et, pour proxy:up et proxy:migrate, iptables) : lancées depuis le conteneur php, elles refusent de tourner avec un message explicite, comme les cibles docker:*.
castor proxy:up¶
Démarre le proxy hôte. Idempotent — relançable à volonté.
Comme kirexo-shared, le projet kirexo-proxy est un singleton ancré sur le dépôt principal : toutes les étapes ci-dessous s'exécutent depuis lui, et le -f du docker compose porte un chemin absolu. L'ancrage vaut aussi pour les source de infra/proxy/proxy.lib.sh, dont dérive le dossier de gabarits : à moitié ancrée, la cible écrirait 01-main.caddy et 00-fallback.caddy depuis deux exemplaires différents du dépôt, dans le même dossier ~/.kirexo/proxy/sites.
Six étapes :
bash infra/proxy/proxy-net.sh— crée le réseau externekirexo-proxy(--internal, sous-réseau dédié, plage d'allocation dynamique bornée, nom de bridge figé) s'il n'existe pas, et pose la règleDOCKER-USERde cloisonnement inter-worktrees. Le script refuse de continuer si un réseau homonyme existe sans êtreinternal: il rendrait une route Internet au conteneur de l'agent, sans aucun signal. Un réseau existant dont l'IPAM n'exclut pasKIREXO_PROXY_IPest signalé (avertissement, pas d'échec) avec son remède,castor proxy:migrate.- Écrit la conf de site du dépôt principal (
01-main.caddy), systématiquement. Elle est rendue depuis le même gabarit que celle d'un worktree (infra/proxy/site.caddy.tpl) avec le nom figéKIREXO_PROXY_MAIN_WT: elle sert doncapp.main.localhost,docs.main.localhostetmailpit.main.localhost. - Régénère le fichier de repli (
00-fallback.caddy), systématiquement lui aussi, en préservant le worktree par défaut qu'il désignait déjà —mains'il n'existait pas encore. La désignation, qui porte le routage des domaines de site, n'est donc jamais volée au worktree qui la détient ; seul le contenu suit le dépôt. Écrire ce fichier uniquement lorsqu'il était absent gelait le gabarit sur les postes existants : une correction du dépôt ne les atteignait jamais. Le repli déclare le joker*.localhost, un bloc explicite pourapp.demo.localhost(le site de démonstration, trop long pour le joker) et la redirection308dehttps://localhostvershttps://app.<worktree par défaut>.localhost. docker compose -f <dépôt principal>/infra/proxy/compose.proxy.yaml -p kirexo-proxy up -d [--wait]. Le chemin absolu n'est pas cosmétique : le bind./Caddyfileest un bind de fichier, et c'est ce-fqui décide du répertoire depuis lequel il est résolu, pour toute la vie du conteneur.bash infra/proxy/proxy-net.sh --verify-caddy-ip— contrôle l'adresse réellement obtenue par le conteneurcaddy-proxy, que leupait réussi ou échoué. Sortie1de la cible si elle diffère de172.31.1.2.castor proxy:reload— inconditionnel.caddy reloadest un no-op quand la configuration est inchangée, donc l'appeler à chaque fois ne coûte rien. Un échec de rechargement n'échoue pas la cible : elle avertit que la conf régénérée n'est pas appliquée et rappellecastor proxy:reload.
Puis la cible affiche les URL servies, et rappelle castor cert:trust tant que var/caddy-root.crt est absent.
Pourquoi les étapes 3 et 6 vont ensemble
Les fichiers de conf sont montés dans le proxy, et up -d est un no-op sur un conteneur déjà en marche : sans le rechargement de l'étape 6, une conf régénérée à l'étape 3 resterait sans effet jusqu'à une action de l'utilisateur. Le repli, lui, n'était autrefois écrit que s'il était absent : une évolution du gabarit n'atteignait alors que les postes n'ayant jamais démarré le proxy. Les deux propriétés ensemble — régénération systématique, rechargement systématique — sont la condition pour qu'un changement du repli atteigne un poste existant, correctif comme retour en arrière.
Cette cible ne suffit pas à migrer un poste installé avant le renommage des URLs
Les étapes 2 et 3 réécrivent la conf du proxy, donc les noms servis. Elles ne touchent ni aux alias réseau des conteneurs (php-main, docs-main, posés par castor docker:up), ni au domaine du site de démonstration (porté par les fixtures). Un poste qui n'a fait que proxy:up obtient un TLS valide et un 502. La séquence complète est dans Migrer un poste existant vers les URLs app..
Aucune étape de cette cible ne touche au magasin de certificats : il n'y a jamais de castor cert:trust à rejouer après un proxy:up.
L'adresse demandée dans Compose ne prouve rien : seule l'adresse obtenue compte
La règle DOCKER-USER s'adosse à une adresse, pas à un conteneur : « tout flux NEW sur le bridge dont la source n'est pas 172.31.1.2 est jeté ». Si un autre conteneur a raflé .2 avant le proxy, deux issues, toutes deux mauvaises :
- Docker refuse d'attacher le Caddy et rend
Address already in use, qui ne nomme pas l'occupant ; - le Caddy démarre sur une autre adresse : la stack répond, le routage fonctionne, et la règle protège désormais l'occupant en jetant le trafic du proxy. Cas silencieux, donc pire.
D'où l'étape 5, et son diagnostic : elle nomme l'occupant de 172.31.1.2 et rappelle que le cloisonnement est alors inversé. Si personne n'occupe l'adresse, elle le dit aussi — l'IPAM est hors de cause et la réponse est dans la sortie du up. Le raisonnement est dans Pourquoi la plage dynamique du réseau du proxy est bornée.
Un réseau kirexo-proxy créé avant ce contrôle doit être recréé
docker network create ne modifie pas un réseau en place : la plage d'allocation dynamique (--ip-range) ne peut pas être ajoutée après coup. Un réseau créé sans elle alloue les adresses à partir du bas du subnet, soit .2 — celle du Caddy. proxy-net.sh le signale sans échouer (échouer casserait chaque castor docker:up d'un poste existant), et le contrôle dur reste l'étape 5.
Recréer le réseau demande de détacher tout ce qui y est attaché : c'est le travail de castor proxy:migrate, qui descend les stacks attachées, supprime le réseau, le recrée borné et relance le proxy.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--no-wait |
flag | --wait actif par défaut |
Ne pas attendre que le healthcheck du proxy soit vert. |
up -d ne relit pas les confs d'un conteneur déjà démarré
Les étapes 2 et 3 réécrivent des fichiers montés dans le proxy, mais up -d est un no-op sur un conteneur en marche. C'est l'étape 6 qui applique la nouvelle configuration : il n'y a rien à enchaîner à la main après un proxy:up. Le seul cas où castor proxy:reload reste à jouer est celui où l'étape 6 a échoué — la cible le dit alors explicitement.
Sans sudo, le cloisonnement n'est pas posé — et ce n'est pas une erreur
proxy-net.sh sort en 0 avec un avertissement quand sudo n'est pas disponible. C'est un mode dégradé supporté : un exit 1 transformerait chaque castor docker:up d'un poste sans droits d'administration en échec dur. L'invariant de confinement C10 passe alors en ⚠ WARN sans jamais bloquer de session. Détail : Ce que la règle DOCKER-USER garantit, et ce qu'elle ne garantit pas.
castor proxy:reload¶
Applique la configuration après ajout ou retrait d'un worktree. Deux commandes, dans cet ordre :
caddy validate --config /etc/caddy/Caddyfiledans le conteneur ;caddy reload --config /etc/caddy/Caddyfile.
La validation précède l'application : une conf cassée (adresse de site dupliquée, par exemple) ferait tomber le routage de tous les worktrees d'un coup. Le reload passe par l'API admin, il est gracieux et no-op quand la configuration est inchangée — donc appelable à chaque fois sans effet de bord.
castor proxy:down¶
Arrête le proxy hôte. docker compose … down, sans -v.
Ne jamais ajouter -v : le volume porte la CA
Le volume caddy_proxy_data contient la racine de la CA locale, valable 10 ans et installée dans le trust store de chaque poste. Le supprimer casse le TLS de tous les worktrees jusqu'à un nouveau castor cert:trust — sur chaque machine. C'est la raison pour laquelle cette cible existe plutôt qu'un docker compose down joué à la main.
castor proxy:migrate¶
Recrée le réseau kirexo-proxy quand il a été créé sans plage d'allocation dynamique bornée — l'état de tout poste dont le réseau date d'avant l'introduction de KIREXO_PROXY_IP_RANGE. Idempotente, relançable à volonté. Hôte uniquement.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--yes |
flag | false |
Descend les stacks attachées sans demander confirmation. Obligatoire hors d'un terminal, où la cible sort en 1 plutôt que d'attendre — cf. Les confirmations hors terminal. |
Trois chemins selon l'état constaté :
| État du réseau | Ce que fait la cible |
|---|---|
| Absent | Enchaîne sur castor proxy:up, qui le crée borné. C'est aussi l'état que laisse une migration interrompue entre la suppression et la recréation : relancer la cible termine le travail au lieu de déclarer la situation saine. |
| Conforme | Rien. Message de succès, sortie 0. Le verdict vient de bash infra/proxy/proxy-net.sh --check-ipam — muet, sortie 0 si l'IPAM protège KIREXO_PROXY_IP, 1 sinon — et jamais d'une seconde définition de la conformité écrite côté Castor. Ce mode rend 0 sur un réseau absent lui aussi, faute de quoi juger ; c'est sans effet ici, ce cas étant traité avant. |
| Non conforme | Plan, confirmation, puis la séquence ci-dessous. |
La séquence, dans cet ordre :
- Inventaire des conteneurs attachés (
docker ps --filter network=kirexo-proxy) et de leur projet Compose. Un conteneur arrêté est détaché du réseau : il n'entre pas dans l'inventaire et ne bloque pas la suppression. - Arrêt immédiat si l'un d'eux n'appartient à aucun projet Compose — voir l'encadré ci-dessous.
- Plan affiché : les projets qui vont être descendus. Confirmation, sautée avec
--yes; hors terminal, sortie en1aveccastor proxy:migrate --yesà retaper. Répondre non laisse le réseau non conforme, et rien n'a été touché. castor proxy:down— le proxy est descendu par sa cible dédiée, la seule à garantir l'absence de-vsur le volume qui porte la CA.docker compose -p <projet> downpour chaque autre projet attaché. Jamais-v: les volumes nommés sont conservés, bases des worktrees comprises.docker network rm kirexo-proxy.castor proxy:up, qui recrée le réseau viaproxy-net.sh— donc borné — puis contrôle l'adresse réellement obtenue par le Caddy.
Les stacks descendues ne sont pas remontées
La cible s'arrête au proxy. Remontez chaque worktree par castor wt:up <ticket> (castor wt:list les donne) et le dépôt principal par castor docker:up.
Y compris les worktrees qui n'étaient qu'arrêtés : leurs conteneurs référencent un identifiant de réseau qui n'existe plus, et seul un wt:up les recrée.
Un conteneur hors projet Compose arrête la cible avant toute destruction
Un conteneur lancé à la main (docker run) ne porte pas d'étiquette com.docker.compose.project : la cible ne saurait ni le descendre ni le remonter, et le docker network rm échouerait plus loin — à un point où le proxy et toutes les stacks seraient déjà descendus. Elle sort donc en 1 en le nommant, avant le premier down. Arrêtez-le à la main (docker stop …), puis relancez.
Un docker network rm refusé ne laisse pas la machine sans proxy
Si quelque chose est encore attaché au moment de la suppression, la cible nomme ce qui reste, relance proxy:up sur le réseau non migré — pour ne pas laisser le poste sans point d'entrée — et sort en 1.
castor proxy:status¶
Diagnostic du proxy, en lecture seule. C'est l'outil de première intention quand une URL en .localhost ne répond pas. Il affiche :
| Section | Contenu |
|---|---|
| Conteneur | Sortie de docker compose ps du projet kirexo-proxy. |
| Sites chargés | Worktree par défaut (celui qui sert les domaines de site) et liste des worktrees routés. Le marqueur inscrit dans 00-fallback.caddy et le défaut effectif sont affichés tous les deux dès qu'ils divergent, sous deux formulations distinctes : Les trois états du worktree par défaut. Le repli et la conf du dépôt principal ne sont pas listés : ce ne sont pas des worktrees. |
| Cloisonnement | Présence de la règle DOCKER-USER, et valeur de net.bridge.bridge-nf-call-iptables — sans ce sysctl à 1, la règle est inopérante alors même qu'elle est présente. |
Résolution *.localhost |
Verdict de getent ahosts sur un nom de sonde. En cas d'échec, la ligne /etc/hosts à ajouter est imprimée. |
Un curl qui ne résout pas n'est pas une panne du proxy
Sur un hôte sans systemd-resolved, les navigateurs résolvent les noms en .localhost nativement, mais pas curl. C'est le seul cas où une configuration système reste nécessaire, et la cible ne la pose pas elle-même : écrire dans /etc/hosts est une action système, hors mandat de l'outillage du dépôt.
Les trois états du worktree par défaut¶
La section « Sites chargés » compare deux valeurs (proxy_status(), castor.php) :
- le marqueur, lu tel quel dans le commentaire
# kirexo-default-worktree:de00-fallback.caddy(proxy_default_wt,infra/proxy/proxy.lib.sh) ; - le défaut effectif, celui que consomment
castor proxy:upetcastor wt:up: le worktree du marqueur si sa conf de site existe, sinon le dépôt principal (KIREXO_PROXY_MAIN_WT) si01-main.caddyexiste, sinon-(proxy_effective_default_wt,infra/proxy/proxy.lib.sh).
Trois états, deux formulations pour la divergence :
| État | Ce que la commande imprime |
|---|---|
| Marqueur = effectif | Une seule ligne, worktree par défaut : <nom>. Aucune ligne routage effectif. Un - s'y affiche tel quel quand rien n'est servi (ni conf de worktree, ni 01-main.caddy). |
Marqueur -, effectif non vide |
worktree par défaut : aucun worktree désigné, puis une ligne routage effectif : <effectif> (sa conf de site existe) et le remède castor proxy:up. Aucune mention PÉRIMÉ : un marqueur - ne désigne rien, il ne peut donc pas être périmé — le dire enverrait chercher un worktree disparu qui n'a jamais existé. |
| Marqueur désignant un worktree sans conf de site | worktree par défaut : <marqueur> (PÉRIMÉ — aucune conf de site), puis routage effectif : <effectif> — relance castor proxy:up pour aligner le fichier. |
worktree par défaut : ticket-215 (PÉRIMÉ — aucune conf de site)
routage effectif : main — relance `castor proxy:up` pour aligner le fichier
sites : ticket-185
Dès qu'une ligne routage effectif apparaît, c'est elle qui fait foi
Quelle que soit la formulation de la ligne du marqueur — (PÉRIMÉ — aucune conf de site) ou aucun worktree désigné —, le nom porté par routage effectif est celui que le proxy applique : c'est lui qui sert app.demo.localhost et qui reçoit la redirection 308 de https://localhost. Le marqueur, lui, décrit seulement l'état du fichier sur le disque, et castor proxy:up le réaligne.
Le second état n'est donc pas moins actionnable que le premier : routage effectif y est tout aussi présent, et la commande reste en lecture seule dans les trois cas.
castor cert:trust¶
Extrait la CA racine du proxy dans var/caddy-root.crt et l'installe dans le trust store de l'OS. Hôte uniquement.
| Étape | Détail |
|---|---|
| Garde-fou | Si le conteneur caddy-proxy n'est pas démarré, la cible sort en 1 avec castor proxy:up comme remède — plutôt qu'une erreur docker compose cp cryptique. |
| Extraction | docker compose cp caddy-proxy:/data/caddy/pki/authorities/local/root.crt → var/caddy-root.crt. |
| Installation | Linux : copie dans /usr/local/share/ca-certificates/caddy-local-root.crt + update-ca-certificates. macOS : security add-trusted-cert dans le trousseau système. Windows : certutil -addstore ROOT. Tout autre OS : avertissement et installation manuelle. |
| Firefox | Trust store séparé — la cible rappelle les deux options (import manuel, ou security.enterprise_roots.enabled). |
Trois propriétés qui distinguent cette cible de ce qu'elle faisait avant :
- Elle cible la CA du proxy, plus celle du FrankenPHP de la stack. Ce dernier continue d'émettre son certificat interne — les tests E2E, qui tournent dans le conteneur, en dépendent — mais plus personne n'a besoin de lui faire confiance : il n'est plus joignable directement depuis l'hôte.
- Aucune visite préalable n'est nécessaire. La CA existe dès le premier démarrage du proxy : tous les blocs déclarent
tls internal, provisionné au chargement de la configuration. - Le geste est unique. Seule la racine est installée, et elle vaut 10 ans : elle couvre tous les worktrees, présents et futurs. Sur Linux, elle écrase l'ancienne racine FrankenPHP ; sur macOS et Windows, le retrait manuel est décrit dans Installer la CA du proxy de développement.
Worktrees¶
Un worktree git = une stack complète et isolée : projet Compose kirexo-<worktree>, réseau dédié, image taguée, base de données propre et trois URLs. Le namespace wt: porte son cycle de vie. Les cibles sont définies dans castor/worktree.php, leurs fonctions partagées dans infra/worktree/wt.lib.sh.
| Cible | Où elle tourne | Effet |
|---|---|---|
wt:up |
hôte uniquement | Crée ou démarre le worktree d'un ticket, et réconcilie sa stack. Idempotent. |
wt:shell (alias wt:bash) |
hôte uniquement | Ouvre un shell bash dans le conteneur php du worktree du répertoire courant, même si sa stack est cassée. Démarre la stack si elle ne répond pas ; refuse si la configuration du worktree manque ; signale une sortie réseau morte sans empêcher l'ouverture. Sans argument. |
wt:claude |
hôte uniquement | Lance Claude Code dans le conteneur php du worktree du répertoire courant, en lui transmettant ses tokens tels quels, précédés de --permission-mode bypassPermissions — sauf si la ligne porte déjà un mode. Mêmes démarrage automatique, refus et avertissement de sortie réseau que wt:shell. Sans argument. |
wt:list |
hôte uniquement | Inventaire des worktrees liés. Lecture seule. |
wt:destroy |
hôte uniquement | Détruit la stack, la conf proxy et le worktree git, après avoir re-parenté les conteneurs singletons montés depuis ce répertoire. Supprime la base. |
wt:gc |
hôte uniquement | Propose les worktrees mergés depuis plus de N jours. N'exécute rien. |
Les six cibles pilotent Docker et git : lancées depuis le conteneur, elles refusent de tourner et impriment la commande à jouer côté hôte — à la racine du dépôt principal pour wt:up, wt:destroy, wt:list et wt:gc, depuis le répertoire de ce worktree pour wt:shell et wt:claude, qui n'ont pas d'argument pour désigner leur cible —, ainsi que ce qui reste faisable de l'intérieur : castor doctor, castor doctrine:migrate, castor fixtures:load, castor all.
L'argument ticket accepte trois formes équivalentes : 185, #185 et ticket-185, normalisées en ticket-185. Huit noms sont refusés, avant toute création, pour trois motifs distincts (KIREXO_PROXY_RESERVED_WT, infra/proxy/proxy.lib.sh) : demo est le seul à provoquer une collision d'adresse de site — il produirait app.demo.localhost, déjà déclarée en dur dans le repli, donc un duplicate site address qui ferait tomber le rechargement de tous les worktrees ; app, mailpit, localhost et www relèvent d'une ambiguïté de lecture ou de routage, sans qu'aucune adresse ne soit dupliquée ; shared et proxy d'une collision de nom de projet Compose avec les stacks singletons kirexo-shared et kirexo-proxy, pas de routage. main est refusé par un autre chemin : wt_normalize_name et proxy_write_site l'écartent comme nom de worktree utilisateur, alors qu'il reste valide comme worktree par défaut. Motif nom par nom : wt:up refuse le nom que je lui donne. Le nom doit par ailleurs être un label DNS strict — minuscules, chiffres et tirets, 32 caractères maximum.
Il est obligatoire pour wt:up et wt:destroy, et absent partout ailleurs : wt:list et wt:gc portent sur l'ensemble des worktrees, tandis que wt:shell et wt:claude visent celui du répertoire courant, cf. Le worktree visé.
wt:shell et wt:claude ne créent donc aucun worktree : on ne peut pas être dans le répertoire d'un worktree qui n'existe pas. Elles lancent en revanche wt:up d'elles-mêmes quand la stack du worktree courant ne répond pas — mais jamais quand c'est sa configuration qui manque, cas où elles sortent en 1. Conditions, annonces et échappatoire : Le démarrage automatique de la stack.
Les variables d'un worktree vivent dans .env.worktree, jamais dans .env.local
Docker Compose ne lit qu'un seul dotenv (.env) ; la cascade .env.local est une mécanique Symfony. Une variable de worktree posée dans .env.local serait silencieusement sans effet sur la stack. Le fichier est généré et réconcilié par wt:up, gitignoré : Variables de worktree.
Castor lit .env.worktree même sans vendor/
castor.php publie COMPOSE_PROJECT_NAME, KIREXO_NETWORK et KIREXO_IMAGE_TAG à partir de .env.worktree, normalement via Symfony Dotenv. Ce parseur vit dans vendor/, absent d'un worktree neuf ou dont l'installation Composer a échoué : la lecture retombe alors sur wt_dump_env (infra/worktree/env.lib.sh), en Bash pur, plutôt que sur un tableau vide (worktree_env_fallback(), castor.php).
Ce n'est pas un détail d'implémentation : sans ce repli, Compose retombait sur le basename du répertoire comme nom de projet. Les commandes n'échouaient pas — elles s'adressaient silencieusement à une autre stack, ou à aucune, au moment précis où l'on venait réparer.
Le nom du projet ne dépend plus de cette lecture : les cibles wt:* le passent en -p, calculé à partir du worktree résolu (cf. Le projet Compose visé par les cibles de worktree). Les autres clés, elles, viennent toujours du fichier — le repli reste donc nécessaire.
Le parcours complet — créer, travailler, détruire — est dans Créer et détruire un worktree ; la marche à suivre quand la stack refuse de monter est dans Réparer un worktree dont la stack ne démarre plus.
Le projet Compose visé par les cibles de worktree¶
Toutes les commandes Compose de portée worktree portent un -p kirexo-<worktree> explicite — wt_compose() et wt_exec_interactive() (castor/worktree.php), le nom étant calculé par ComposeProject::expected() (castor/src/Worktree/ComposeProject.php). La stack visée est donc une fonction du worktree résolu, jamais de l'environnement : elle reste juste même quand .env.worktree a disparu, cas où Compose retombait auparavant sur le COMPOSE_PROJECT_NAME ambiant, c'est-à-dire sur une autre stack ou sur aucune, sans un mot. La stack mutualisée suit la même règle avec -p kirexo-shared.
Ce -p prime sur COMPOSE_PROJECT_NAME (cf. la précédence rappelée dans Les 16 clés du contrat). Une valeur éditée à la main dans .env.worktree n'est donc plus honorée par les cibles wt:* — elle est contrôlée, et l'écart est dit. Le verdict est rendu par ComposeProject::verdict(), à partir de l'existence du fichier et de la valeur déclarée :
| Verdict | Constat | Ce que font les cibles |
|---|---|---|
Ok |
le fichier déclare kirexo-<worktree> |
rien |
Missing |
fichier absent, ou clé COMPOSE_PROJECT_NAME absente ou vide — les deux cas ont la même conséquence et le même remède |
wt:shell et wt:claude sortent en 1 ; wt:destroy avertit et continue ; wt:list marque la ligne |
Divergent |
le fichier déclare un autre nom | avertissement nommant les deux valeurs, puis la commande continue — le -p a déjà tranché |
Sur Missing, ce n'est pas le seul nom de projet qui manque : le worktree n'a alors ni KIREXO_NETWORK, ni KIREXO_IMAGE_TAG, ni son port Xdebug, ni son vhost RabbitMQ. Le -p protège la commande en cours, il ne répare rien — d'où un message, plutôt qu'une réparation muette. Remède unique : castor wt:up <ticket>, qui régénère le fichier entier.
Sur Divergent, l'avertissement nomme la valeur retenue :
/…/kirexo-worktrees/ticket-185/.env.worktree déclare un autre projet Compose que celui attendu :
déclaré : kirexo-autre
attendu : kirexo-ticket-185 ← c'est celui qui est utilisé
Pour aligner le fichier : castor wt:up ticket-185
Les lignes docker compose à recopier portent le -p, elles aussi
Deux blocs de diagnostic donnent une commande Compose à rejouer à la main, et toutes deux désignent le projet explicitement — sans quoi la ligne collée viserait le projet déduit du basename du répertoire, c'est-à-dire pas la stack dont on parle :
- le remède de l'étape des dépendances de
wt:upporte en plus les fichiers empilés (-f compose.yaml -f compose.override.yaml -f compose.worktree.yaml, pluscompose.full.yamlen profilfull) : ils créent le conteneur, et sanscompose.worktree.yaml— que Compose n'auto-découvre jamais — il perdrait le bind du git common dir ; - le
psdu bloc dewt:upen échec de démarrage n'a besoin que du-p: il énumère les conteneurs d'un projet, il n'en crée aucun.
castor wt:up¶
Crée ou démarre le worktree d'un ticket et réconcilie sa stack, applique les migrations, charge les fixtures si la base est vierge, puis affiche les trois URLs. Idempotent : relançable à volonté. Avant toute création, elle regarde d'où on la lance et propose — dans un terminal seulement — de partir d'un main à jour : Le contrôle du point de départ. C'est aussi la cible que wt:shell et wt:claude lancent d'elles-mêmes quand la stack du worktree courant ne répond pas — Le démarrage automatique de la stack.
| Argument / option | Type | Défaut | Effet |
|---|---|---|---|
ticket |
string | (obligatoire) | Identifiant du ticket (185) ou nom complet du worktree (ticket-185). |
--profile |
light | full |
valeur mémorisée, sinon light |
Profil de ressources. Mémorisé dans COMPOSE_PROFILES (.env.worktree) et réutilisé quand l'option est omise — sans quoi un second wt:up ferait retomber une stack full en light. |
--from |
string | main |
Branche du worktree, deux rôles : point de départ quand la branche est créée, et arbitrage quand plusieurs branches correspondent au ticket. Sans effet si le worktree existe déjà. |
--fixtures |
flag | false |
Recharge les fixtures même si la base est déjà peuplée. Destructif : doctrine:fixtures:load sans --append purge la base. |
--no-build |
flag | false |
Ne reconstruit pas l'image, même si le Dockerfile a divergé ; la divergence est alors signalée. |
castor wt:up 185
castor wt:up 212 --from=185-editeur-de-blocs --profile=full
castor wt:up 202 --from=202-fix-chromium-pin # arbitrage entre branches homonymes du ticket
Ce que COMPOSE_PROFILES discrimine
Le profil n'empile pas des fichiers Compose différents — light et full chargent les mêmes — c'est la valeur de COMPOSE_PROFILES publiée dans l'environnement qui active les services portant profiles: ["full"] (redis, rabbitmq, typesense et gotenberg dans compose.override.yaml). compose.full.yaml s'y ajoute quand il existe, pour ce que l'activation seule ne suffit pas à obtenir : rattacher ces quatre services au réseau du worktree, rétablir leur politique de redémarrage, redéclarer un mailer dédié (absent de compose.yaml), et !override les networks et depends_on de php — sans quoi son attache au réseau des services mutualisés survivrait à la fusion, et un nom comme redis rendrait deux adresses. Le raisonnement (ce que light mutualise, ce que full coûte) est dans Profils de ressources et mutualisation.
Les deux rôles de --from¶
--from désigne une branche, dans deux situations distinctes, et n'a aucun effet sur un worktree qui existe déjà :
| Situation | Effet de --from |
|---|---|
Aucune branche <numéro>-* n'existe |
Point de départ : git worktree add -b <worktree> … <from>. |
Plusieurs branches <numéro>-* correspondent au ticket |
Arbitrage : la valeur passée est retenue si elle figure parmi les candidates. |
| Une seule branche correspond | Aucun — elle est réutilisée telle quelle. |
Deux propriétés à connaître :
--fromchoisit la branche, jamais la façon de l'attacher. Le mode (local/remote) reste déduit de l'endroit où la branche existe : une branche désignée qui n'existe que suroriginest suivie (--track), jamais recréée depuismain— sinon le worktree ne contiendrait aucun des commits poussés. La décision est portée parcastor/src/Worktree/BranchResolver.php.- L'arbitrage ne s'applique qu'en cas d'ambiguïté. Un
--fromqui écraserait la résolution quelle que soit sa valeur créerait un worktree sur une branche arbitraire, en silence. Corollaire : une valeur absente de la liste des candidates ne tranche rien, et le message d'erreur le dit explicitement (--from=… n'est PAS dans cette liste) plutôt que de répéter à l'identique l'erreur d'ambiguïté.
Le contrôle du point de départ précède la séquence ci-dessous — et même le titre Worktree <nom>, puisqu'il peut rendre la main. Puis, dans cet ordre :
- Worktree git — créé dans
<parent du dépôt principal>/kirexo-worktrees/<worktree>s'il est absent, avecgit worktree add --lock. S'il existe : rien, ni checkout, ni pull, ni rebase. La branche est le nom du worktree, sauf si une branche<numéro>-*existe déjà en local ou surorigin, auquel cas elle est réutilisée (une branche distante est suivie, pas recréée). Plusieurs candidates : arrêt avec la liste, sauf si--fromen désigne une. Aucun appel à l'API GitLab — la cible fonctionne hors ligne. - Proxy hôte —
castor proxy:up, idempotent. - Préalable d'infrastructure — le préalable commun, qui crée notamment le réseau externe
kirexo-egress. Sans lui, aucune stack de worktree ne démarre. Le vhost RabbitMQ du worktree est créé et autorisé dans la foulée : après le démarrage du broker mutualisé, et avant celui de la stack, dont le worker Messenger se connecte immédiatement. L'opération est idempotente et non bloquante — un broker injoignable est signalé (!), il n'interrompt paswt:up. - Réconciliation —
.env.worktree, lienvar/claudevers l'espace partagé, whitelist locale du worktree, conf proxy, image,.claude/settings.local.json(voir le tableau ci-dessous). Le lien est posé après l'écriture de.env.worktree(qui publieKIREXO_SHARED_CLAUDE_DIR) et avant leup, dont le bind exige un chemin hôte existant. - Dépendances Composer —
docker compose run --rm --no-deps php composer installdans un conteneur jetable, quandvendor/autoload_runtime.phpest absent ou plus ancien quecomposer.lock. Sur un worktree sansvendor/, l'installation est précédée d'une amorce devendor/copiée depuis le dépôt principal. La position est contrainte : après la construction de l'image (le conteneur jetable tourne dessus) et avant leup --wait, FrankenPHP exigeantvendor/autoload_runtime.phpdès son premier tour de boucle — l'installation ne peut donc pas passer par le conteneur de service. - Démarrage —
docker compose up -d --wait --remove-orphanssur le projet du worktree. En cas d'échec, la cible sort en1avec un remède plutôt qu'une trace Compose : voir Ce quewt:upaffiche quand le démarrage échoue. - Gateway du réseau —
WT_GATEWAY_IPrelevée sur le réseau réel ; si elle a changé, le seul servicephpest recréé pour appliquerextra_hosts(figé à la création du conteneur). - Assets front —
bin/console importmap:installetbin/console tailwind:builddans le conteneur de service (exec), la stack étant debout à ce stade. Déclenchés quandassets/vendor/ouvar/tailwind/app.built.csssont absents ou plus anciens que leur source (importmap.php,assets/styles/app.css), et systématiquement quand l'étape 5 a réellement installé quelque chose — uncomposer.lockqui bouge fait bouger les versions d'importmap.php. - Données —
infra/worktree/bootstrap-data.shdans le conteneurphp: migrations toujours, fixtures uniquement si la base est vierge ou sur--fixtures. Voir Quand les fixtures sont chargées. - Sortie — les trois URLs
https://app.<worktree>.localhost,https://mailpit.<worktree>.localhost,https://docs.<worktree>.localhost(wt_urls,infra/worktree/wt.lib.sh).
Un échec de l'étape 5 arrête wt:up
vendor/ est gitignoré : il est absent d'un worktree neuf, et le vendor/ construit par le Dockerfile est masqué par le bind .:/app. Sans installation préalable, le up --wait rend container kirexo-<worktree>-php-1 exited (1) et la cause — require_once(/app/vendor/autoload_runtime.php): Failed to open stream — n'apparaît que dans les journaux du conteneur, après cinq crashs de FrankenPHP.
La cible sort donc en 1 à l'étape 5, en affichant d'abord la sortie de Composer (qui porte la cause réelle), puis les deux causes fréquentes — domaine manquant dans l'allowlist du proxy sortant, composer.lock divergent de composer.json — et la commande à rejouer à la main.
Chaque élément réconcilié produit une ligne de rapport, avec un préfixe stable :
| Préfixe | Sens |
|---|---|
= |
Inchangé. |
~ |
Réconcilié : l'élément existait et a été remis à l'état attendu. |
+ |
Créé. |
! |
Divergence signalée, non corrigée — action manuelle attendue. |
| Élément | Ce que wt:up fait, et ne fait pas |
|---|---|
.env.worktree |
Réconcilié clé par clé sur les 16 clés du contrat. XDEBUG_CLIENT_PORT et REDIS_DB_INDEX déjà alloués sont réutilisés, les lignes hors contrat sont préservées. |
var/claude partagé |
Le dossier du dépôt principal est créé s'il manque (le bind Compose exige que le chemin hôte existe, sinon Docker y pose un dossier root), puis var/claude du worktree devient un lien vers lui. Un lien qui pointait ailleurs est refait ; un var/claude local non vide est conservé et signalé (!) — un worktree ouvert avant ce partage y a du travail en cours. |
| Whitelist locale | <worktree>/infra/firewall/whitelist.local.txt copiée du .dist si absente, avant le démarrage. Si un répertoire root-owned occupe déjà la place, la divergence est signalée (!) — aucune commande privilégiée n'est exécutée. |
| Conf proxy | Écrite dans ~/.kirexo/proxy/sites/<worktree>.caddy ; castor proxy:reload seulement si elle a changé. Le worktree prend la place de worktree par défaut du proxy tant qu'aucun worktree réel n'y est désigné — trois cas, ci-dessous. Un worktree réellement servi n'est jamais évincé. |
| Image | kirexo-dev-local:<worktree> reconstruite si absente ou plus ancienne que le Dockerfile ou compose.override.yaml. |
Amorce de vendor/ |
vendor/ copié depuis le dépôt principal (+) avant l'installation, uniquement quand le worktree n'en a aucun. Optimisation best-effort : un échec est signalé et n'interrompt jamais la cible. Rien n'est affiché quand le worktree a déjà un vendor/. Détail : L'amorce de vendor/. |
| Dépendances Composer | composer install dans un conteneur jetable si vendor/autoload_runtime.php est absent (+) ou plus ancien que composer.lock (~). Sinon =. La mesure est une antériorité de mtime, pas une cohérence : un vendor/ issu d'un autre lock passerait ce test. Échec → arrêt de la cible. |
| Assets front | importmap:install et tailwind:build (~) quand assets/vendor/ ou var/tailwind/app.built.css sont périmés au regard d'importmap.php et d'assets/styles/app.css, ou quand une installation Composer vient d'avoir lieu. Leur absence ne casse pas le démarrage, seulement le rendu. |
.claude/settings.local.json |
Généré depuis .claude/settings.local.json.tpl s'il est absent (+), aligné s'il existe (~) : permissions.defaultMode retiré s'il vaut bypassPermissions — valeur que Claude Code ignore, cf. Le mode de permission est posé sur la ligne de commande —, skipDangerousModePermissionPrompt posé à true, tout le reste du JSON préservé (écriture atomique). Un defaultMode valant plan ou acceptEdits est un choix du développeur : il n'est pas touché. Rien à changer → =. Un contenu inattendu (JSON invalide, tableau JSON non vide) ou une écriture impossible sont signalés (!), le fichier est laissé tel quel. Opt-out : KIREXO_CLAUDE_BYPASS. |
| Base de données | Migrations toujours appliquées. Fixtures uniquement sur base vierge ou --fixtures — cf. Quand les fixtures sont chargées. |
| Branche | Aucune action. Une branche différente ou un HEAD détaché sont signalés, jamais corrigés. |
Au second appel sur une stack inchangée, toutes les lignes valent =.
Les trois cas où wt:up reprend le rôle de worktree par défaut
La condition porte sur le worktree par défaut effectif — proxy_effective_default_wt (infra/proxy/proxy.lib.sh), et non sur le marqueur brut inscrit dans 00-fallback.caddy (wt_reconcile_proxy, castor/worktree.php). Elle est vraie dans trois cas :
- la valeur courante est
-: aucun worktree n'est désigné ; - elle désigne le dépôt principal, c'est-à-dire le défaut que
castor proxy:upvient de poser ; - elle désigne un worktree sans conf de site — un marqueur périmé.
proxy_effective_default_wtle rabat alors sur le dépôt principal si01-main.caddyexiste, sur-sinon : dans les deux cas, on retombe sur l'un des deux points précédents.
Le troisième cas est le seul à ne pas se lire dans le fichier : castor proxy:up préserve le marqueur par conception, il survit donc à toutes les relances pendant que le repli route vers un upstream que plus personne ne porte. Sans ce rabattement, wt:up rapporterait = sur la ligne « worktree par défaut » et laisserait la panne en place indéfiniment. C'est l'état d'un poste installé avant le renommage des URLs de développement, dont le marqueur porte l'ancien nom du dépôt principal (local).
Le prédicat porte sur l'existence du fichier de site, jamais sur un nom particulier : local étant redevenu un nom de worktree valide, un worktree qui le porte réellement — et dont la conf existe — garde la désignation.
compose.worktree.yaml doit être empilé explicitement
Ce fichier monte le git common dir et le var/claude du dépôt principal dans le conteneur (tous deux au même chemin absolu, en écriture) et injecte WT, KIREXO_GIT_COMMON_DIR et KIREXO_SHARED_CLAUDE_DIR. Docker Compose n'auto-découvre que compose.yaml et compose.override.yaml : celui-ci n'est jamais chargé tout seul, et c'est ce qui garantit qu'en l'absence de .env.worktree, la stack du dépôt principal démarre à l'identique.
Le partage n'est donc pas entre cibles wt:* et le reste, mais entre les cibles qui empilent le contexte du worktree — wt:up et image:refresh, qui lisent .env.worktree et ajoutent les -f correspondants — et celles qui s'en remettent à l'auto-découverte de Compose. castor docker:up est de la seconde famille : lancé depuis le répertoire d'un worktree, il démarre bien sa stack (le nom de projet vient de .env.worktree) mais sans ce montage. La stack monte parfaitement, et plus aucune commande git ne fonctionne dans le conteneur — sans le moindre message. Remède : castor wt:up <ticket>.
Branche antérieure à la mise en place des worktrees
Un worktree porte les fichiers de sa branche. Si compose.worktree.yaml en est absent, wt:up s'arrête et réclame un rebase — sans jamais le faire lui-même. Démarrer une telle stack la priverait du montage git et du confinement réseau, silencieusement.
La base proposée est mesurée, jamais supposée : la cible parcourt les références connues du dépôt (refs/heads et refs/remotes/origin, origin/main et main essayées en premier) et nomme la première qui porte réellement le fichier. Nommer origin/main en dur enverrait dans le mur tant que le lot qui a créé le fichier n'y est pas mergé. Si aucune référence ne le porte, la cible le dit et renvoie vers un git fetch. Marche à suivre : Mon worktree démarre sans alias ni confinement.
Le contrôle du point de départ¶
Avant le titre et avant toute création, wt:up regarde d'où on le lance et sur quoi il va partir (wt_check_start_point(), castor/worktree.php ; la décision est tirée par castor/src/Worktree/StartPoint.php, sans aucune I/O). Le worktree naît de la ref locale main — pas de la branche courante : c'est cette ref, et l'endroit d'où la commande part, que le contrôle donne à voir.
À ne pas confondre avec --from
--from désigne la branche de départ du worktree créé. Ici, « point de départ » est celui de la personne qui tape la commande : son répertoire courant, et l'état du dépôt principal.
Quatre cas mutuellement exclusifs, évalués dans cet ordre — trois donnent lieu à une proposition :
D'où wt:up est lancé |
Ce qui est proposé | Réponse « oui » | Réponse « non » |
|---|---|---|---|
| Un arbre de travail lié (un worktree) | Aller d'abord dans le dépôt principal ? | La main est rendue avec la commande à rejouer là-bas — cd <dépôt principal> && castor wt:up <ticket> <options>, options reprises telles quelles — et la cible sort en 0 : c'est un choix, pas un échec. |
wt:up continue, sans un mot sur main. |
L'arbre principal, hors de main |
Basculer le dépôt principal sur main ? |
git switch main, tenté pour de vrai. |
On continue, sans contrôle de fraîcheur. |
L'arbre principal, sur main, en retard sur origin/main |
Mettre main à jour maintenant ? |
git merge --ff-only origin/main. |
On continue. |
| Hors du dépôt | (rien) | — | — |
Cinq propriétés à connaître :
- Rien n'est jamais imposé. Un refus de git n'interrompt pas
wt:up: ne pas pouvoir basculer n'empêche pas de créer un worktree,git worktree addpartant de la refmainet non deHEAD. La sortie de git est alors affichée telle quelle — elle nomme les fichiers en cause — et les remèdes sont donnés dans l'ordre de leur fréquence sur ce dépôt : travail en cours (git stash, ou un commit) · un chemininfra/qui refuse d'être réécrit parce qu'une stack du dépôt principal le monte en lecture seule (castor docker:downd'abord) · branches divergentes (git pull --rebase, à jouer à la main). - La question de l'arbre lié n'est pas de pure forme. Depuis un worktree, c'est le
castor.phpde sa branche qui s'exécute : la stack produite sera la même, la mécanique qui la produit, pas forcément. - La fraîcheur ne se teste que sur
main.git merge --ff-onlys'applique à la branche courante : le jouer ailleurs avaleraitorigin/maindans une branche de travail. Une bascule réussie enchaîne donc sur la question de la fraîcheur — c'est le seul enchaînement possible, et il n'y a jamais plus de deux questions. - Un seul appel réseau,
git fetch --quiet origin main, joué uniquement depuis l'arbre principal surmainet annoncé par une ligne… git fetch origin main. Sans lui, la comparaison porterait sur une ref distante périmée. Hors ligne, sans remote, sansorigin/main, ou sur un remote qui réclamerait une identité (GIT_TERMINAL_PROMPT=0: git échoue au lieu d'ouvrir un prompt), le retard devient indéterminable et le contrôle se tait plutôt que de supposer. Un retard mesuré à zéro et un retard non mesurable ne se confondent donc pas. - Toutes les opérations git portent
-C <dépôt principal>, jamais le répertoire courant : depuis un arbre lié, unswitchou unmergetoucherait la branche du ticket sur lequel quelqu'un travaille.
Le contrôle se dégrade en silence là où il ne peut rien affirmer : l'appartenance au dépôt se mesure sur <dépôt principal>/.git, donc un --separate-git-dir ou un dépôt nu le font conclure « hors du dépôt », et rien n'est proposé.
Hors interactif : aucune question, aucune action¶
Aucune des trois questions n'est posée si Castor n'est pas en mode interactif, ou si l'entrée standard n'est pas un terminal — la garde est commune à tout le projet, elle est décrite dans La garde d'interactivité.
Ces trois questions sont des propositions : hors interactif, elles ne font donc pas sortir la cible, contrairement aux confirmations. Un écart constaté sur l'arbre principal est simplement rapporté dans le bloc = ~ + ! avec le préfixe ! — ! dépôt principal (sur <branche>, pas sur main), ! dépôt principal (HEAD détaché, pas sur main), ! main (N commit(s) de retard sur origin/main). Le cas de l'arbre lié reste muet, son défaut étant « continue ».
Le wt:up déclenché par wt:shell et wt:claude passe --no-interaction (wt_auto_up()) : il part toujours d'un arbre lié, et poser la question du déplacement à quelqu'un qui vient de taper wt:shell serait hostile. La garde stream_isatty() n'y suffirait pas — dans un vrai terminal, le sous-process hérite du tty de l'appelant.
L'amorce de vendor/ sur un worktree neuf¶
Avant l'installation des dépendances (étape 5), wt:up amorce vendor/ par une copie de celui du dépôt principal : Composer n'a plus qu'à ajuster ce qui diffère, au lieu de tout retélécharger à travers le proxy sortant. La décision est prise par wt_seed_vendor() (castor/worktree.php), à partir de castor/src/Worktree/VendorSeed.php et castor/src/Worktree/VendorSeedVerdict.php.
Deux propriétés cadrent tout le reste :
- c'est une optimisation, jamais une garantie —
composer installest joué systématiquement derrière, et c'est lui seul qui fait foi sur la correspondance entrevendor/etcomposer.lock; - elle n'interrompt jamais
wt:up— tout échec de copie est signalé par un avertissement, puis l'installation complète prend le relais.
L'amorce n'a lieu que quand une installation va suivre : si le contrôle de fraîcheur rend = dépendances (vendor/ plus récent que composer.lock), rien n'est copié et rien n'est affiché.
| Situation | Ce que wt:up affiche |
|---|---|
Le worktree n'a pas de vendor/ et le dépôt principal porte un vendor/autoload.php |
Amorce de vendor/ depuis le dépôt principal… avant la copie, puis + amorce vendor (vendor/ amorcé depuis le dépôt principal) |
Le dépôt principal n'a pas de vendor/autoload.php |
= amorce vendor (pas d'amorce : le dépôt principal n'a pas de vendor/autoload.php) — la ligne annonce une installation complète, donc une attente |
Le worktree a déjà un vendor/ |
Rien. C'est le cas nominal d'un wt:up rejoué ; un vendor/ en place n'est jamais écrasé. |
La ligne d'attente de l'installation Composer (Installation en cours (plusieurs minutes sur un worktree neuf) — sortie affichée en cas d'échec.) est inchangée : elle borne le pire cas, pas celui d'une amorce réussie.
Quatre avertissements possibles. Tous laissent composer install faire l'intégralité du travail, et aucun n'appelle une action de votre part :
| Avertissement | Cause |
|---|---|
Le vendor/ du dépôt principal a bougé pendant la copie — amorce abandonnée, composer install fera le travail. |
Le vendor/ source a été modifié pendant la copie — typiquement un castor install joué en parallèle dans le dépôt principal. |
Amorce de vendor/ impossible : <sortie de cp> — composer install fera tout le travail (plus long). |
La copie a échoué : disque plein, permissions. La sortie de cp est reprise telle quelle quand elle n'est pas vide. |
Amorce de vendor/ abandonnée : sentinelle de fraîcheur non supprimable — composer install fera le travail. |
La copie n'a pas pu être préparée pour l'installation qui suit ; elle est jetée plutôt que publiée dans un état qui fausserait le contrôle de fraîcheur du prochain wt:up. |
Amorce de vendor/ non publiée (un autre wt:up l'a peut-être devancée) — composer install fera le travail. |
La publication de la copie a échoué, le worktree ayant reçu un vendor/ entre-temps. |
Trois limites connues :
- la source doit être au repos — un
castor installen cours dans le dépôt principal pendant la copie est détecté dans le cas courant (avertissement ci-dessus), sans que la détection soit exhaustive ; - deux
castor wt:upsimultanés sur le même worktree ne sont pas un mode supporté ; deuxwt:upsur des worktrees différents, si ; - une interruption brutale peut laisser un résidu — un répertoire
vendor.seed-tmp.*à la racine du worktree, gitignoré et sans effet sur la stack, mais qui occupe de l'espace disque. Suppression manuelle.
macOS : copie sans copy-on-write, rien à configurer
L'option --reflink=auto — qui rend la copie quasi instantanée et sans coût disque sur un système de fichiers copy-on-write (btrfs, xfs) — est une extension GNU coreutils. Elle n'est passée que si le cp du poste la connaît, ce qui est mesuré sur cp --version. Sur macOS, la copie a lieu sans copy-on-write : le comportement est identique, seul le coût change. Aucune variable d'environnement, aucune option de la cible.
Le raisonnement — pourquoi copier plutôt que partager, et pourquoi l'amorce ne bloque jamais — est dans Amorcer vendor/ plutôt que le retélécharger.
Quand les fixtures sont chargées¶
La décision est prise dans le conteneur, par infra/worktree/bootstrap-data.sh, et porte sur l'état des données — pas sur celui du stockage :
| Situation | Migrations | Fixtures |
|---|---|---|
Base vierge : doctrine_migration_versions absente ou vide, mesuré avant le migrate |
appliquées | chargées |
| Base déjà migrée | appliquées (no-op si à jour) | ignorées — · fixtures ignorées (base déjà peuplée …) |
castor wt:up <ticket> --fixtures |
appliquées | rechargées, base purgée |
| Fraîcheur indéterminée (sonde en échec pour une autre raison qu'une table absente) | appliquées | ignorées, avec un avertissement sur stderr et le remède |
Volume de la base nommé par version majeure de PostgreSQL
Le volume de la base de dev s'appelle database_pg18_data (compose.yaml), monté sur /var/lib/postgresql. PostgreSQL 18 refuse un volume qui contient les données d'une autre majeure : la montée de version se fait donc par un nouveau nom de volume. Au premier castor wt:up après le passage de 16 à 18, la base est neuve, donc vierge au sens du tableau ci-dessus : migrations et fixtures sont rejouées, les données saisies dans l'ancienne base ne sont pas reprises. Dans le dépôt principal, castor docker:up démarre lui aussi sur une base vide : rejouez castor doctrine:migrate puis castor fixtures:load. L'ancien volume …_database_data reste orphelin, down -v ne le voit plus : relevez son nom avec docker volume ls --filter name=database_data et supprimez-le à la main, côté hôte (docker volume rm kirexo-<worktree>_database_data pour un worktree).
Le verdict fresh / populated / unknown est rendu par bootstrap_db_verdict (infra/worktree/bootstrap.lib.sh) à partir du code retour et de la sortie de la sonde. Trois verdicts et non deux : seule l'absence de la table des migrations (SQLSTATE[42P01]) vaut « vierge ». Une connexion refusée rend unknown, et un unknown ne purge jamais.
Ce critère a changé — l'ancien perdait les fixtures d'un worktree neuf
La fraîcheur se mesurait auparavant côté hôte, sur l'existence du volume de la base (alors kirexo-<worktree>_database_data), avant le up. Or ce up crée le volume puis échoue sur php : au passage suivant, le volume existait, wt:up annonçait « fixtures ignorées (base existante) » sur une base vide, et plus rien ne les rechargeait jamais.
Conséquence pratique du nouveau critère : un worktree dont le premier wt:up a échoué reçoit bien ses fixtures au passage suivant, sans --fixtures. Le garde-fou reste entier — une base déjà migrée n'est jamais purgée d'office.
Ce que wt:up affiche quand le démarrage échoue¶
L'échec du up --wait ne rend plus la trace brute de Castor (la ligne de commande Compose intégrale et ses variables d'environnement) mais un bloc d'erreur qui nomme la porte de secours, puis sort en 1 :
La stack du worktree ticket-185 n'est pas montée.
Le conteneur `php` reste debout tant qu'il peut, même quand FrankenPHP
abandonne : entre dedans et répare depuis le worktree, sans terminal hôte —
cd <chemin du worktree> && castor wt:shell
Une fois dedans : `castor doctor`, puis `castor supervisor:frankenphp-restart`.
Journaux : <chemin du worktree>/var/log/supervisor/
Conteneur volontairement debout ? <chemin du worktree>/var/run/supervisor/maintenance
État des conteneurs : cd <chemin du worktree> && docker compose -p kirexo-<worktree> ps
La sortie de Compose reste affichée en direct au-dessus : le bloc s'y ajoute, il ne la remplace pas. Le cd fait partie de la commande de secours et n'est pas un préambule qu'on pourrait sauter — wt:shell n'accepte pas de ticket. Le message est rendu par wt_fail_up() (castor/worktree.php). La recette complète est dans Réparer un worktree dont la stack ne démarre plus.
castor wt:shell¶
Ouvre un shell bash dans le conteneur php du worktree du répertoire courant — y compris quand sa stack est cassée. Hôte uniquement.
Aucun argument. Castor refuse lui-même le moindre token positionnel : No arguments expected for "wt:shell" command, got "215".
cd <chemin du worktree>
castor wt:shell # le worktree du répertoire courant, ou de n'importe lequel de ses sous-dossiers
castor wt:bash # alias : même cible, même repli
On n'entre plus dans un worktree depuis le dépôt principal
La forme castor wt:shell <ticket> a existé et n'existe plus : la cible visait alors le worktree nommé, depuis n'importe où. C'est une capacité en moins, et son remplaçant est un cd. Le worktree est désormais résolu par le seul répertoire courant (Le worktree visé) ; lancée d'ailleurs, la commande s'arrête en listant les worktrees réels avec leur chemin, prêt à coller.
Ce que la suppression ferme, en revanche : une typo de numéro ne crée plus rien. Elle créait auparavant un worktree entier — branche, base, site proxy, vhost — puisque wt:up était lancé sur le nom passé.
wt:bash est un alias, pas une seconde cible
wt:bash est déclaré dans l'attribut #[AsTask(aliases: ['wt:bash'])] de wt_shell() (castor/worktree.php) : les deux noms exécutent le même code. L'alias hérite donc de tout ce qui suit, repli en conteneur jetable compris. Deux implémentations quasi-homonymes auraient donné deux modes de panne différents pour un même geste. Seul écart visible : le message affiché hors d'un worktree nomme wt:shell, la cible réelle, même si vous avez tapé wt:bash.
Deux chemins, choisis par une sonde — et, entre les deux, une tentative de démarrage :
Sonde docker compose exec -T php true |
Chemin retenu | Ce que vous obtenez |
|---|---|---|
| Réussit | docker compose exec php bash |
Le conteneur de service du worktree, avec tous ses services liés. |
Échoue, puis réussit après un wt:up automatique |
docker compose exec php bash |
Idem : la stack a été démarrée en chemin. |
Échoue encore après ce wt:up |
docker compose run --rm --no-deps php bash |
Un conteneur jetable, même image et même code (le bind .:/app du worktree). Les services liés — base, broker, cache — sont absents. |
Le worktree, lui, existe forcément : on est dedans. Deux contrôles précèdent néanmoins la sonde, et tous deux sortent en 1 sans rien tenter :
- Incohérence de chemin — un
.env.worktreequi annonce unWTdont le chemin attendu n'existe pas, après un déplacement du worktree ou un changement deKIREXO_WORKTREES_DIR. La cible nomme le chemin attendu et renvoie verscastor wt:list. - Configuration absente — verdict
Missingsur le projet Compose du worktree, cf. l'encadré ci-dessous.
Le déclencheur du wt:up automatique, la règle de la tentative unique et l'échappatoire KIREXO_WT_NO_AUTO_UP=1 sont décrits dans Le démarrage automatique de la stack.
Sur le premier chemin du tableau — et sur lui seul, cf. La sonde de sortie réseau à l'ouverture — la cible sonde la sortie réseau du conteneur avant d'ouvrir le shell, et affiche un avertissement si elle est morte. Elle ouvre le shell dans tous les cas.
L'auto-démarrage ne couvre pas une configuration absente : la cible refuse
Avant toute sonde, wt:shell contrôle le COMPOSE_PROJECT_NAME du worktree (Le projet Compose visé par les cibles de worktree). Sur verdict Missing — .env.worktree absent, ou sans cette clé — elle sort en 1 :
La configuration du worktree ticket-185 est absente ou incomplète.
Fichier attendu : /…/kirexo-worktrees/ticket-185/.env.worktree
Régénère-le : castor wt:up ticket-185
Aucun wt:up n'est tenté, et ce n'est pas un oubli : « la stack ne répond pas » et « le worktree n'a plus de configuration » sont deux états distincts. Dans le second, wt:up ne démarrerait pas, il provisionnerait — branche, base, conf proxy, vhost —, ce qui n'appartient pas aux chemins automatiques. Le refus est donc bruyant et porte la commande, plutôt que d'ouvrir un shell dans un worktree privé de son réseau, de son tag d'image et de son port Xdebug, où la panne réapparaîtrait plus loin sous un symptôme sans rapport.
Trois propriétés qui la distinguent de castor docker:sh :
- Le répertoire courant est la contrainte, plus un défaut. Il n'y a pas d'argument pour viser un autre worktree : on entre dans un worktree en étant dedans. En échange, la résolution remonte l'arborescence, les trois fichiers Compose sont empilés avec l'environnement de
.env.worktree, et le projet est désigné par un-pexplicite (wt_compose()) — la commande vise donc le bon projet depuis n'importe quel sous-dossier, là oùdocker:shs'en remet à l'auto-découverte de Compose. - Elle n'exige ni conteneur vivant, ni stack démarrée.
docker:shest unexec: sans conteneur, il n'y a rien à faire. C'est précisément le geste qui échoue quand la stack est morte. - Elle survit à un
vendor/absent, comme toutes les cibleswt:*depuis le repli de lecture de.env.worktree.
Le repli est annoncé par un avertissement — sans quoi on croirait parler à sa stack :
Le conteneur php du worktree ticket-185 ne répond toujours pas.
Ouverture d'un conteneur JETABLE, même image et même code.
Tu peux réparer (composer install, cache:clear, …).
Mais les services liés sont absents, et rien n'y survit hors du worktree.
« Toujours » n'est pas une tournure de style : il n'est écrit que si une tentative de démarrage a réellement eu lieu. Sous KIREXO_WT_NO_AUTO_UP=1, rien n'a été tenté et la première ligne devient Le conteneur php du worktree ticket-185 ne répond pas (démarrage automatique désactivé).
La sonde est un exec, pas un compose ps
Le test de vitalité est docker compose exec -T php true : il réussit exactement quand l'exec interactif réussira. compose ps --status=running --quiet php compterait aussi les conteneurs éphémères <projet>-php-run-<hash> que run --rm laisse derrière lui quand on l'interrompt — le shell s'ouvrirait alors dans le conteneur jetable de la fois précédente, sur la mauvaise stack, sans un mot.
Sortir du shell sur un code non nul n'est pas une erreur
La cible tolère l'échec de la commande finale : quitter par Ctrl-D après une commande en erreur ne produit aucune trace Castor par-dessus. C'est une cible de secours, on en sort souvent en erreur.
Le shell obtenu a l'édition de ligne
Flèches, rappel de l'historique et collage fonctionnent parce que la cible attache le terminal de l'appelant au conteneur — le paramètre $tty de wt_compose() (castor/worktree.php), passé à true sur les deux chemins. Le PTY que Castor pose par défaut n'y suffirait pas : le détail du mécanisme, et le cas où le TTY n'est pas posé, sont dans Le TTY des cibles interactives.
Elle ne joue pas elle-même le préalable commun
wt:shell ouvre un shell : ni kirexo-shared, ni le réseau kirexo-egress ne sont créés par la cible. Ils le sont en revanche par le wt:up qu'elle lance quand la stack ne répond pas, et avant le démarrage de celle-ci — un wt:up qui échoue sur son up --wait a donc déjà exécuté le préalable.
Le chemin run --rm peut encore échouer sur network kirexo-egress declared as external, but could not be found dans deux cas : sous KIREXO_WT_NO_AUTO_UP=1, ou quand le wt:up automatique s'est arrêté avant son étape de préalable — en pratique compose.worktree.yaml absent de la branche du worktree, les autres arrêts précoces supposant un nom saisi à la main. C'est alors castor wt:up <ticket> qu'il faut jouer d'abord.
castor wt:claude¶
Lance Claude Code dans le conteneur php du worktree du répertoire courant — docker compose exec php claude …. Hôte uniquement.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
| (tous les tokens) | list | [] |
Transmis tels quels à claude, dans leur ordre d'origine. Aucun n'est consommé par la cible (#[AsRawTokens]). |
cd <chemin du worktree>
castor wt:claude # session neuve dans le worktree du répertoire courant
castor wt:claude --resume # exécute exactement : claude --resume
castor wt:claude -p "résume la spec en cours"
Le binaire claude vit dans l'image de développement (@anthropic-ai/claude-code, cf. Node et Claude Code) et démarre dans /app, le répertoire de travail du conteneur. Comme l'espace utilisateur de Claude Code est commun à tous les worktrees, un --resume lancé dans un worktree liste aussi les conversations démarrées dans les autres : Pourquoi l'espace Claude est commun à tous les worktrees.
Le mode de permission est posé sur la ligne de commande¶
La cible préfixe --permission-mode bypassPermissions aux tokens reçus (ClaudeBypassFlag::args(), castor/src/Worktree/ClaudeBypassFlag.php). Un castor wt:claude --resume exécute donc :
La ligne de commande est la seule source du mode dans ce dispositif. Claude Code refuse d'accorder bypassPermissions quand le mode vient d'un fichier que le dépôt contrôle : un permissions.defaultMode posé dans .claude/settings.json (projectSettings) ou .claude/settings.local.json (localSettings) est ignoré — « only policy/user/flag settings may grant bypass mode (projectSettings and localSettings are repo-controllable) » —, et ce refus ne s'affiche pas dans l'interface, il part dans le journal interne. Des trois sources encore légitimes — politique machine /etc/claude-code/managed-settings.json, réglages utilisateur $CLAUDE_CONFIG_DIR/settings.json, ligne de commande —, seule la troisième est praticable ici : le settings.json utilisateur est monté :ro dans le conteneur (invariant de confinement C5) et la politique machine imposerait de reconstruire l'image. Le raisonnement : Qui a le droit d'accorder le mode bypassPermissions.
Le flag s'efface devant un mode déclaré sur la ligne de commande (ClaudeBypassFlag::declaresMode()), ce qui laisse castor wt:claude --permission-mode plan obéi — et évite les deux --permission-mode sur la même ligne, qui font sortir claude en erreur :
| Ligne tapée | Ce qui est exécuté |
|---|---|
castor wt:claude |
claude --permission-mode bypassPermissions |
castor wt:claude --permission-mode plan |
claude --permission-mode plan — rien n'est injecté |
castor wt:claude --permission-mode=plan |
claude --permission-mode=plan — la forme accolée est reconnue |
castor wt:claude --dangerously-skip-permissions |
inchangé : le mode est déjà déclaré |
castor wt:claude --allow-dangerously-skip-permissions |
inchangé : l'option autorise le bypass sans l'activer, injecter le mode par-dessus donnerait exactement ce qu'elle refuse |
castor wt:claude -p "explique --permission-mode" |
claude --permission-mode bypassPermissions -p "explique --permission-mode" — la reconnaissance porte sur le token exact (ou son préfixe --option=), jamais sur le contenu d'un prompt |
La cible publie aussi son constat dans la session : KIREXO_CLAUDE_BYPASS_ACTIVE en -e de l'exec, à 1 si la ligne finale ouvre bien en bypass, 0 sinon. Elle est calculée sur la ligne complète, injection comprise (ClaudeBypassFlag::declaresBypass()) : un --dangerously-skip-permissions passé à la main n'injecte rien et publie pourtant 1. Unique consommateur : le gate de confinement du hook SessionStart, qui ne s'arme qu'en bypassPermissions.
Opt-out — KIREXO_CLAUDE_BYPASS=0, ou le marqueur ~/.kirexo/no-claude-bypass : aucun flag n'est posé, et wt:up n'écrit pas non plus le consentement dans .claude/settings.local.json. Le mode que vous déclarez vous-même sur la ligne de commande, lui, n'est jamais retiré — et le constat reste fidèle à ce qui s'ouvre, donc KIREXO_CLAUDE_BYPASS_ACTIVE=1 dans ce cas, 0 sinon. Détail : KIREXO_CLAUDE_BYPASS.
Le dialogue d'avertissement, et pourquoi il ne revient pas à chaque session
Le flag seul ouvre sur l'écran « WARNING: Claude Code running in Bypass Permissions mode / Yes, I accept », qui attend une validation au clavier. Le même flag accompagné de skipDangerousModePermissionPrompt: true ouvre directement la session : la garde de ce dialogue accepte, elle, un réglage local — là où celle du mode le refuse. C'est ce consentement, et plus le mode, que wt:up écrit dans .claude/settings.local.json (cf. le tableau de réconciliation).
Il ne peut pas vivre ailleurs : Claude Code l'écrit spontanément dans le settings.json des réglages utilisateur, précisément le fichier monté :ro dans le conteneur. L'écriture y échouerait à chaque session, et le dialogue reviendrait à chaque ouverture.
Un premier token en forme de ticket est refusé¶
Il n'y a aucune contrainte de position : tous les tokens partent à claude sans filtrage, donc castor wt:claude --resume est la forme normale.
C'est précisément ce qui rendrait l'ancienne forme silencieuse. Un premier token 215 lancerait claude 215, c'est-à-dire une session sur le prompt « 215 » : ni une panne, ni quelque chose qu'on rattache spontanément à la commande qu'on vient de taper. wt:shell est protégée par Castor lui-même (« No arguments expected ») ; #[AsRawTokens] accepte tout, alors la cible refuse elle-même un premier token de la forme 215, #215 ou ticket-215 (TicketToken::looksLikeWorktree(), castor/src/Worktree/TicketToken.php) :
`castor wt:claude` ne prend plus de ticket : elle vise le worktree du répertoire courant.
Reçu en premier : « 215 », qui partirait à `claude` comme PROMPT.
Depuis le worktree : castor wt:claude
Depuis ailleurs : cd <chemin du worktree> && castor wt:claude
Vraiment ce prompt : castor wt:claude -p 215
Inventaire : castor wt:list
C'est un refus de forme, pas une devinette de cible : celle-ci est déjà décidée par le répertoire courant, et rien d'autre. Un faux positif coûte donc un message et une échappatoire (-p), jamais une action — à la différence d'une reconnaissance de forme qui aurait servi à choisir le worktree, laquelle aurait envoyé la session ailleurs en silence. La liste des formes reconnues est volontairement étroite : --resume, -p, un chemin ou une phrase n'en font pas partie.
« Tel quel » vaut pour les options de claude, pas pour les options globales de Castor
Les options globales de Castor appartiennent à l'application, pas à la commande : elles sont traitées avant d'atteindre claude. Trois d'entre elles ont été mesurées sur cette cible.
| Option | Ce qui se passe réellement |
|---|---|
--help, -h |
Affiche l'aide de Castor pour wt:claude. claude --help n'est jamais atteint. |
-v, -vv, -vvv |
Consommée par Castor (verbosité) et retransmise à claude. |
-q |
Idem : consommée par Castor (mode silencieux) et retransmise. |
Pour l'aide de Claude Code, passez par le shell : castor wt:shell puis claude --help.
Ce que la cible garantit¶
- Le mode de permission est décidé par la ligne de commande, la vôtre ou celle que la cible complète — aucun fichier du dépôt ne peut plus l'accorder, cf. Le mode de permission est posé sur la ligne de commande.
- Le code de sortie est propagé tel quel (
wt_exec_interactive()), donccastor wt:claude -p "…"reste chaînable dans un script, un hook ou la CI. Un0de politesse rendrait ces usages inexploitables. - L'interactivité vient du TTY, pas du PTY que Castor active par défaut : c'est
withTty()— posé parwt_exec_interactive()(castor/worktree.php) — qui rattache le terminal de l'appelant au process et rend l'édition de ligne à la sessionclaudedistante. Ce TTY reste conditionnel àProcess::isTtySupported(), sans quoiProcess::setTty()lèveraitTTY mode requires /dev/tty to be read/writedès que STDOUT n'est pas un terminal — donc dansout=$(castor wt:claude -p "…")ou dans un pipe, c'est-à-dire exactement là où la chaînabilité est promise. Mécanisme complet : Le TTY des cibles interactives. - La sortie réseau est sondée avant l'
exec, et une sortie morte est annoncée là où elle est encore lisible : passé l'exec, l'écran appartient à Claude Code. L'avertissement n'interrompt jamais le lancement — cf. La sonde de sortie réseau à l'ouverture. - La sélection à la souris reste au terminal, alors que Claude Code met celui-ci en mode souris (
\e[?1000h) pour rendre son interface cliquable. La cible poseCLAUDE_CODE_DISABLE_MOUSE_CLICKSen-ede sondocker compose exec(wt_claude(),castor/worktree.php) : la portée est la session lancée, et elle seule. Sans elle, le terminal transmet les clics à l'agent au lieu de sélectionner, et une commande affichée dans la conversation doit être retapée à la main. La molette, donc le défilement de l'interface, est conservée — cf. Espace Claude et jeton GitLab (dev local).
Pas de repli en conteneur jetable¶
Contrairement à wt:shell, wt:claude exige un conteneur php vivant : elle fait un exec, et sans conteneur il n'y a personne à qui parler. La même sonde est employée — docker compose exec -T php true, jamais un compose ps, qui compterait aussi les conteneurs éphémères <projet>-php-run-<hash> laissés par un run --rm interrompu.
Elle n'exige pas pour autant que la stack soit déjà démarrée : quand la sonde échoue, un castor wt:up est lancé sur le worktree courant et la sonde rejouée, cf. Le démarrage automatique de la stack. Ce n'est qu'après cette tentative que la cible sort en 1, en nommant les deux issues :
Le conteneur php du worktree ticket-215 ne répond pas.
Le démarrage automatique a échoué — relance : castor wt:up ticket-215
Stack cassée ? castor wt:shell (conteneur jetable, depuis ce répertoire)
La deuxième ligne dit ce qui s'est passé, et change donc quand rien n'a été tenté : sous KIREXO_WT_NO_AUTO_UP=1, elle devient Démarrage automatique désactivé (KIREXO_WT_NO_AUTO_UP=1) — lance : castor wt:up ticket-215. La troisième est toujours citée parce qu'elle couvre l'autre cas : wt:up remonte une stack simplement arrêtée, mais échoue précisément quand elle est cassée — c'est alors wt:shell et son conteneur jetable qui donnent une porte d'entrée. Elle se joue depuis ce répertoire : on y est déjà, c'est ce qui a permis de résoudre le worktree. Parcours complet : Réparer un worktree dont la stack ne démarre plus.
Le répertoire du worktree, lui, ne peut pas manquer : la cible n'y serait pas. Restent les deux gardes qui précèdent toute sonde, identiques à celles de wt:shell, messages compris :
- un chemin attendu qui n'existe plus — worktree déplacé, ou
KIREXO_WORKTREES_DIRchangé depuis sa création : la cible s'arrête avec le chemin en cause etcastor wt:listcomme point de reprise ; - une configuration absente (verdict
Missing) : sortie en1aveccastor wt:up <ticket>, sans démarrage automatique — cf. Le projet Compose visé par les cibles de worktree.
Le démarrage automatique de la stack¶
wt:shell (alias wt:bash) et wt:claude sont les deux cibles par lesquelles on entre dans un worktree. Aucune des deux n'exige que sa stack tourne : quand le conteneur php ne répond pas, elles lancent castor wt:up elles-mêmes sur le worktree courant, une seule fois, et l'annoncent avant de partir. wt:up est idempotent et réconciliateur — le relancer sur un worktree sain ne détruit rien.
Un seul déclencheur (wt_ensure_stack(), castor/worktree.php) :
| Constat | Ce qui est lancé | Message |
|---|---|---|
Le conteneur php ne répond pas à la sonde docker compose exec -T php true |
castor wt:up <worktree courant>, qui remonte la stack |
La stack du worktree ticket-215 ne répond pas — démarrage automatique. |
L'annonce nomme la commande jouée, ce qu'elle fait — « il réconcilie la stack, applique les migrations et attend le healthcheck. Compte une minute. » — et l'échappatoire. Elle n'est pas cosmétique : un outil qui prend une minute sans rien dire passe pour bloqué. La sortie de wt:up reste ensuite affichée en direct, rapport de réconciliation = ~ + ! et diagnostic d'échec compris.
Ce déclencheur ne couvre que la stack. Un worktree dont .env.worktree a disparu est écarté avant la sonde : les deux cibles sortent alors en 1 en nommant castor wt:up <ticket>, sans rien tenter. « La stack ne répond pas » et « le worktree n'a plus de configuration » sont deux états distincts — dans le second, wt:up provisionnerait au lieu de démarrer. Détail : Le projet Compose visé par les cibles de worktree.
Il n'y a plus de création automatique de worktree. Elle est devenue inatteignable : ces deux cibles visent le worktree du répertoire courant, on ne peut donc pas être dans le dossier d'un worktree qui n'existe pas. Créer un worktree passe par castor wt:up <ticket>, joué à la main — et lui seul accepte --profile, --from, --fixtures et --no-build.
Une seule tentative, volontairement : si la stack ne répond toujours pas après ce wt:up, c'est qu'elle est cassée, et boucler ne ferait que retarder le diagnostic. Chaque cible retombe alors sur le comportement qu'elle a toujours eu :
| Cible | Repli |
|---|---|
wt:shell |
Conteneur jetable — cf. castor wt:shell. C'est sa raison d'être. |
wt:claude |
Sortie en 1 avec les deux issues — cf. Pas de repli en conteneur jetable. |
Désactiver l'auto-démarrage : KIREXO_WT_NO_AUTO_UP=1¶
KIREXO_WT_NO_AUTO_UP=1 castor wt:shell # repli jetable immédiat, sans tentative
KIREXO_WT_NO_AUTO_UP=1 castor wt:claude # échec immédiat si la stack ne répond pas
À 1, aucun démarrage automatique : les deux cibles s'en tiennent à la sonde, et les messages le disent plutôt que de laisser croire à une tentative — ne répond pas (démarrage automatique désactivé) pour wt:shell, Démarrage automatique désactivé (KIREXO_WT_NO_AUTO_UP=1) pour wt:claude. Toute autre valeur, variable absente comprise, laisse l'auto-démarrage actif (wt_auto_up_enabled(), castor/worktree.php). Elle est documentée avec les autres variables hôte dans Variables hôte du cycle de vie des worktrees.
Le cas d'usage principal est la réparation : sur une stack dont on sait déjà qu'elle est cassée, la tentative de démarrage va échouer et coûter le temps d'un build et d'un up --wait. Cf. Réparer un worktree dont la stack ne démarre plus.
Pourquoi une variable d'environnement et non une option
wt:claude transmet ses tokens bruts à claude : #[AsRawTokens] rend la ligne de commande entière, sans qu'aucun token soit consommé par la cible. Une option Castor propre — --no-auto-up — y entrerait donc en collision avec les options de Claude Code, et obligerait à trancher entre les deux. La variable d'environnement laisse la ligne de commande intacte.
wt:up reste le geste explicite
Rien n'oblige à passer par l'auto-démarrage : castor wt:up <ticket> garde ses options — --profile, --from, --fixtures, --no-build — qu'aucune des deux cibles ne sait transmettre. Un premier démarrage en profil full, ou une création sur une branche précise, passe donc toujours par un wt:up joué à la main.
La sonde de sortie réseau à l'ouverture¶
wt:shell (alias wt:bash) et wt:claude mesurent la sortie réseau du worktree avant de rendre la main au programme interactif. Une sortie morte produit un avertissement, jamais un refus : le lancement se poursuit dans tous les cas. Le pourquoi de cet arbitrage est dans Avertir à l'ouverture, sans jamais bloquer.
La sonde est jouée après le démarrage automatique — elle a besoin d'un conteneur vivant — et avant l'exec :
| Cible | Sonde jouée | Sonde non jouée |
|---|---|---|
wt:claude |
sur le chemin nominal, une fois la stack confirmée vivante | quand la cible sort en 1 avant l'exec : chemin introuvable, configuration absente, stack toujours muette après le wt:up automatique |
wt:shell |
sur le chemin nominal (docker compose exec php bash) |
sur le repli en conteneur jetable (run --rm --no-deps), où les services liés sont absents : l'absence de sortie réseau y est attendue, la signaler serait un faux positif |
Ce qui est mesuré, textuellement — un curl muet, sans corps, borné à 6 s, vers le domaine de l'allowlist commun aux sondes du dépôt (egress_probe_url(), castor/firewall.php) :
Succès : rien n'est affiché, et la cible enchaîne. Échec : le bloc d'avertissement ci-dessous, puis la cible enchaîne quand même.
Pas de sortie réseau depuis ce worktree.
Sonde : https://packagist.org, injoignable depuis le conteneur php.
Le réseau `kirexo-egress` est `internal: true` : sans `egress-proxy`, il n'y a
AUCUNE route sortante. Ce qui va s'ouvrir ici n'en aura donc pas non plus, et
l'erreur que tu y liras ressemblera à une panne de réseau quelconque : elle ne
désignera pas cette cause.
egress-proxy a redémarré 1029 fois — il ne tient pas en vie.
Remède, depuis le dépôt principal :
docker compose -p kirexo-shared -f compose.shared.yaml up -d --force-recreate egress-proxy
Le message est neutre vis-à-vis de l'appelant : les deux cibles affichent le même texte, qui ne promet donc rien sur ce qui va s'ouvrir — un bash n'échoue pas sur un appel d'API.
La sonde part du conteneur, jamais de l'hôte
Les deux cibles sont hôte-only, mais la commande, elle, est exécutée dans le conteneur php. C'est là que vit http_proxy=http://egress-proxy:3128 (ancre x-proxy-env de compose.override.yaml), et egress-proxy n'est résolvable que sur le réseau Docker. La même ligne lancée depuis l'hôte emprunterait la route normale de l'hôte et réussirait toujours, egress-proxy mort compris : elle mesurerait l'hôte en croyant mesurer la session. Même piège, non gardé, sur castor firewall:status.
Le compteur de redémarrages est affiché uniquement quand il a pu être lu et qu'il est non nul — un proxy qui redémarre en boucle est un diagnostic à lui seul. Il est obtenu côté hôte, en désignant le conteneur par ses labels Compose (com.docker.compose.project=kirexo-shared, com.docker.compose.service=egress-proxy) puis en l'inspectant :
Lecture impossible : la ligne est simplement absente. Elle ne devient jamais « 0 redémarrage » — un compteur non lu et un compteur nul ne disent pas la même chose.
Deux limites à connaître :
- Une seule sonde, pas trois. Elle répond à « reste-t-il une route ? », pas à « la politique est-elle appliquée ? ». Qualifier la politique demande le couple domaine autorisé qui passe / domaine refusé qui échoue, plus l'absence de route directe : c'est le travail des trois sondes de
castor firewall:status, pas d'un chemin de lancement. - Aucune réparation n'est tentée. Le remède affiché est hôte-only et vise un autre projet Compose (
kirexo-shared) : cf. Diagnostiquer un blocage réseau sortant. Il résout la grande majorité des cas, pas tous — un conteneur au fichier pid verrouillé demande unrm -sf, décrit à l'étape 9 du même guide.
Coût à l'ouverture
Environ 90 ms quand la sortie réseau est saine — invisible. Quand elle est morte, jusqu'à 6 s (--max-time) plus deux appels docker pour le compteur : l'attente est alors le prix du diagnostic, dans la seule situation où l'on voulait être ralenti.
Le worktree visé¶
wt:shell (alias wt:bash) et wt:claude n'ont pas d'argument : le worktree est celui du répertoire courant, et rien ne permet d'en viser un autre. La résolution est faite par wt_current_worktree() (castor/worktree.php) :
| Situation | Résultat |
|---|---|
| Répertoire dans un worktree | La valeur de WT lue dans le .env.worktree du worktree. La recherche remonte l'arborescence (32 niveaux au plus) : la commande marche donc depuis …/ticket-215/src, pas seulement depuis la racine du worktree. |
| Répertoire hors worktree — dépôt principal compris | Arrêt en 1, avec la liste des worktrees réels et leur chemin (bloc ci-dessous). Le dépôt principal n'a pas de .env.worktree : ce n'est pas un worktree, et il n'a pas de conteneur de worktree à viser. |
| Worktree annoncé mais chemin introuvable | Arrêt en 1 : le .env.worktree porte un WT dont le chemin attendu n'existe pas — worktree déplacé à la main, ou KIREXO_WORKTREES_DIR changé depuis sa création. Le message nomme le chemin attendu et renvoie vers castor wt:list. |
Le deuxième cas est le seul message que voit quelqu'un qui lance la commande depuis le dépôt principal — l'endroit d'où elle fonctionnait avant. Il porte donc le remplaçant, prêt à coller, plutôt qu'un constat (wt_fail_no_current_worktree()) :
`castor wt:shell` s'exécute DEPUIS le répertoire d'un worktree.
Le répertoire courant n'en est pas un (le dépôt principal non plus).
Où aller :
cd /…/kirexo-worktrees/ticket-215 && castor wt:shell
cd /…/kirexo-worktrees/ticket-231 && castor wt:shell
Détail des stacks : castor wt:list
Quand aucun worktree n'existe — ou hors dépôt git, où la liste ne peut pas être établie —, l'énumération laisse place à la forme générale cd <chemin du worktree> && castor wt:shell, suivie de castor wt:list pour l'inventaire et de castor wt:up 215 pour la création.
Pourquoi le répertoire, et rien d'autre
C'est le geste réel : on ne pilote pas un worktree depuis nulle part, on entre dans son dossier. Le ticket y répétait une information que le répertoire portait déjà — et depuis que ces deux cibles lancent wt:up d'elles-mêmes, une typo de numéro ne se rattrapait plus : elle créait un worktree entier, en silence.
La contrepartie est assumée : entrer dans un worktree depuis le dépôt principal, ou depuis un autre worktree, n'est plus possible. Le remplaçant est un cd, que le message d'erreur donne prêt à coller.
Le TTY des cibles interactives¶
wt:shell (alias wt:bash) et wt:claude sont les deux cibles qui rendent la main à un programme interactif — un bash, une session Claude Code. Toutes deux rattachent le terminal de l'appelant au process Docker par withTty() : c'est ce rattachement, et lui seul, qui rend l'édition de ligne au programme distant.
| Mode | Ce que le process reçoit | Ce que fait le terminal de l'appelant |
|---|---|---|
PTY — actif par défaut dans Castor (Context::$pty) |
un pseudo-terminal créé pour le process | Il reste en mode canonique : il garde l'édition de ligne pour lui et ne transmet la frappe qu'à la validation. |
TTY — withTty(), explicite |
ses trois descripteurs branchés sur le /dev/tty de l'appelant |
Un vrai terminal est sur stdin : le client Docker le bascule alors en mode raw, et chaque touche part telle quelle vers le programme distant. |
Le PTY par défaut fait donc tourner le process, mais il ne suffit pas à l'interactivité. En mode canonique, une flèche n'atteint jamais le bash du conteneur : elle s'imprime brute (^[[D), et un collage arrive encadré de ses marqueurs de bracketed paste (^[[200~ … ^[[201~), ce qui rend la ligne inexécutable. Le TTY est une condition de l'interactivité, pas un confort.
Le passage en mode raw vient du client Docker, pas de symfony/process
symfony/process n'exécute aucun stty : en mode TTY, il se contente de brancher les trois descripteurs du process sur /dev/tty (vendor/symfony/process/Pipes/UnixPipes.php). C'est ensuite docker compose exec, voyant un vrai terminal sur son entrée, qui met celui-ci en mode raw. Sans TTY, il n'a rien à basculer — d'où le symptôme.
Pourquoi ce TTY reste conditionnel¶
Les deux cibles ne le posent que si Process::isTtySupported() est vrai (wt_compose() et wt_exec_interactive(), castor/worktree.php). Cette méthode exige que STDOUT soit un terminal et que /dev/tty soit accessible en écriture ; sans la garde, Process::setTty() lèverait TTY mode requires /dev/tty to be read/write dans un pipe, une substitution de commande, un hook Claude Code ou un job CI. La commande y tourne donc en PTY seul, sans édition de ligne — ce qui est sans conséquence quand personne ne tape.
Pourquoi le drapeau est opt-in¶
Dans wt_compose(), le TTY est un paramètre $tty qui vaut false par défaut : un process en TTY écrit directement sur /dev/tty, sa sortie ne transitant plus par un tuyau lisible via getOutput(). Les appels qui inspectent la sortie — la sonde exec -T php true, config --services, ps -a --format json — doivent donc rester sans TTY. Seul wt_shell() passe true, pour ses deux chemins : conteneur de service et conteneur jetable.
castor wt:list¶
Inventaire des worktrees liés — le dépôt principal n'est pas listé, ce n'est pas un worktree.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--no-stats |
flag | false |
Saute la collecte docker stats (plus rapide ; colonne RAM vide). |
--no-fetch |
flag | false |
N'exécute pas git fetch origin main avant le calcul de « mergée ». |
| Colonne | Contenu |
|---|---|
ticket |
Nom du worktree, suffixé * s'il est le worktree par défaut du proxy — celui qui sert app.demo.localhost et les domaines de site. Le * suit le défaut effectif, pas le marqueur du repli : un marqueur périmé ne fait donc jamais porter l'étoile à un worktree que le proxy ne sert pas. castor proxy:status est la cible qui montre l'écart entre les deux. |
branche |
Branche checkoutée, ou (détaché). |
état |
up (n/n, m healthy), partiel (n/m), ou arrêté — suffixé d'un ? quand le dénombrement n'est pas fiable, et d'un ⚠ quand la configuration du worktree n'est pas celle attendue (encadrés ci-dessous ; les deux marqueurs se cumulent). n compte les services vivants, m les services déclarés par les fichiers Compose du worktree, profil appliqué. arrêté dès qu'aucun service attendu ne tourne, quel que soit le nombre de conteneurs exited restants ; les URLs sont alors masquées. |
URLs |
Les trois URLs, ou — si la stack est arrêtée. |
âge |
Ancienneté des métadonnées git du worktree (pas de son répertoire, dont le mtime bouge à chaque wt:up), ou ⚠ répertoire absent. |
RAM |
Somme des MemUsage des conteneurs du projet, issue d'un seul docker stats global. |
mergée ? |
oui (il y a 12 j), oui, squash (…), non, ou ? quand l'information n'a pas pu être obtenue. |
core ? |
Coredumps de profondeur 1 dans le worktree : nombre et volume cumulé, ou —. |
Le suffixe ? de la colonne état : dénombrement partiel
Le dénominateur vient de docker compose config --services, c'est-à-dire des services attendus. Il ne peut pas venir de docker compose ps, qui ne rend que les conteneurs vivants : un service mort quitterait alors le numérateur et le dénominateur du même geste, et l'état vaudrait up (n/n) quoi qu'il arrive.
config --services échoue dès qu'une variable requise manque à l'appel — cas typique d'un .env.worktree antérieur à l'ajout de cette variable, comme KIREXO_SHARED_CLAUDE_DIR. Le total se replie alors sur les conteneurs qui existent encore (docker compose ps -a), qui le bornent par le bas : un service dont le conteneur a été supprimé y manque, et up (2/2) peut décrire une stack amputée.
Ce doute est affiché plutôt que passé sous silence : l'état porte un ? final (up (2/2) ?, partiel (2/3) ?) et un pied de tableau nomme les worktrees concernés avec le remède — castor wt:up <ticket>, qui réconcilie le .env.worktree.
Les conteneurs éphémères laissés par un docker compose run --rm interrompu (<projet>-php-run-<hash>) sont exclus des deux ensembles : ils portent le nom du service réel et feraient compter un php fantôme, vivant, à la place du vrai.
Le marqueur ⚠ de la colonne état : l'état affiché n'est pas mesurable
Il signale un worktree dont le projet Compose déclaré n'est pas celui attendu (verdict Missing ou Divergent, cf. Le projet Compose visé par les cibles de worktree). C'est ici qu'il faut le dire : wt:list est la commande d'inventaire, celle où l'on vient regarder. L'état ment de deux façons, et aucune n'est visible sans le marqueur :
.env.worktreeabsent — aucun service déclaré, aucun conteneur : la ligne affichearrêté ⚠, sans quoi elle serait indiscernable d'un worktree sain à l'arrêt ;- nom de projet divergent — la sonde interroge
kirexo-<worktree>(le-pdes cibleswt:*) pendant que la stack tourne sous le nom déclaré : la ligne affichearrêté ⚠pour une stack bien vivante.
Ni l'un ni l'autre n'est corrigeable par wt:list, qui est en lecture seule. Un pied de tableau nomme donc les worktrees concernés et donne le remède, différent dans les deux cas — régénérer le fichier suffit quand il manque, alors qu'un nom divergent laisse en plus une stack vivante sous un autre projet, que wt:up ne ramassera pas :
⚠ ticket-185 : .env.worktree absent ou incomplet — l'état affiché n'est pas fiable. Régénère : castor wt:up ticket-185
⚠ ticket-231 : projet Compose déclaré kirexo-autre, attendu kirexo-ticket-231 — la stack tourne peut-être sous le nom déclaré.
Vérifie : docker compose -p kirexo-autre ps · aligne : castor wt:up ticket-231
Un projet Compose kirexo-* sans worktree correspondant est un résidu : il est listé sous le tableau avec sa commande de nettoyage, jamais supprimé automatiquement — un projet inconnu peut appartenir à autre chose.
castor wt:destroy¶
Détruit un worktree et tout ce qui lui appartient.
| Argument / option | Type | Défaut | Effet |
|---|---|---|---|
ticket |
string | (obligatoire) | Identifiant du ticket ou nom complet du worktree. |
--force |
flag | false |
Détruit malgré des modifications non commitées ou des commits non poussés. Passe aussi --force à git worktree remove. |
--yes, -y |
flag | false |
Ne demande pas de confirmation. Obligatoire hors d'un terminal, où la cible sort en 1 plutôt que d'attendre — cf. Les confirmations hors terminal. |
Ordre des opérations — il est dicté par « ne jamais détruire l'information nécessaire au nettoyage avant d'avoir nettoyé » :
- Garde-fous de perte de travail :
git status --porcelainnon vide, ou commits non poussés → arrêt, sortie1, avec le décompte et la mention de--force. Sautés avec--force. - Confirmation interactive, qui rappelle que la base Postgres sera supprimée. Sautée avec
--yes. Hors terminal, la cible sort en1en donnantcastor wt:destroy <ticket>[ --force] --yes. - Si la commande tourne depuis le worktree visé — lui-même ou un sous-répertoire : relance depuis le dépôt principal, puis sortie immédiate avec le code de l'enfant. Encadré ci-dessous.
- Contrôle du projet Compose du worktree — avertissement, jamais un refus : encadré ci-dessous.
docker compose down -v --remove-orphans. En cas d'échec : arrêt immédiat, sortie1, worktree et.env.worktreeconservés — sans eux, plus rien ne permet de retrouver conteneurs, réseau et volumes.- Retrait de la conf proxy +
castor proxy:reload. Si le worktree était le worktree par défaut, le repli retombe seul surmain. - Suppression du vhost RabbitMQ du worktree, dans le broker mutualisé que
down -vne touche pas. - Re-parentage des projets Compose singletons —
kirexo-sharedetkirexo-proxy— dont des conteneurs référencent le répertoire visé : encadré ci-dessous. L'étape a lieu avant le retrait du worktree, jamais après. - Résolution du chemin de la conf proxy pour le contrôle de l'étape 12 — avant que le worktree ne disparaisse : le chemin est rendu par
proxy_site_file(infra/proxy/proxy.lib.sh), une lib sourcée depuis le checkout courant. git worktree unlockpuisgit worktree remove, puisgit worktree prune.docker image rm kirexo-dev-local:<worktree>— untag, jamais--force, jamaisdocker image prune.- Vérification des résidus : conteneurs, volumes, réseau, conf proxy, répertoire du worktree.
À partir de l'étape 6, les échecs sont accumulés et rapportés en fin de course avec une sortie 1 : chaque étape est idempotente, relancer la commande reprend là où il faut.
Les étapes 8 à 12 s'exécutent depuis le dépôt principal, jamais depuis le worktree : leur répertoire de travail est ancré explicitement, faute de quoi elles hériteraient d'un répertoire supprimé entre-temps.
Détruire un worktree depuis son propre dossier : la commande se relance seule
C'est le geste courant — on finit un ticket, on est dans son répertoire, on range. git worktree remove efface le répertoire entier, fichiers ignorés compris, donc vendor/ : le processus supprimerait les fichiers dont il dépend pour finir de s'exécuter. La cible détecte le cas et relance la destruction depuis le dépôt principal, avec la confirmation déjà donnée (--yes) et --force s'il avait été passé, puis s'efface — elle n'affiche plus rien après le relais.
La ligne qui l'annonce, avant toute destruction :
Deux conséquences visibles :
- le code de sortie est celui de la destruction, plus celui d'un épilogue qui s'effondre. Avant ce relais, la commande affichait ses coches puis un
Failed to open streampointant survendor/, avec une sortie non nulle sur une destruction pourtant réussie ; - la sortie est imbriquée dans une section Castor —
[1] castor wt:destroy … success after 12s— au lieu de s'afficher en flux direct : elle provient d'un sous-processus. C'est le fonctionnement normal, pas un défaut d'affichage.
Lancée depuis le dépôt principal, ou depuis n'importe quel autre répertoire, la cible ne se relance pas et affiche sa sortie directement. Le pourquoi est dans Ne jamais supprimer le vendor/ dont on dépend.
Une sentinelle d'environnement interne interdit la récursion du relais : cf. KIREXO_WT_DESTROY_REEXEC, à ne jamais poser à la main.
Configuration absente ou divergente : la cible avertit, puis détruit quand même
C'est la seule cible qui continue sur un verdict Missing (Le projet Compose visé par les cibles de worktree). Refuser interdirait le geste même qui nettoie un worktree cassé et laisserait derrière lui conteneurs, volumes et conf proxy ; le -p explicite garantit par ailleurs que c'est bien la stack du worktree visé qui est détruite.
| Verdict | Ce que dit l'avertissement | Ce qui est détruit |
|---|---|---|
Missing |
le fichier est absent ou incomplet ; la destruction continue et vise kirexo-<worktree>, le projet attendu ; si la stack avait été démarrée sous un autre nom, contrôler après coup avec docker compose ls et castor wt:list |
tout, sous le projet attendu |
Divergent |
la stack tourne probablement sous le nom déclaré, que la destruction ne vise pas ; la commande complémentaire docker compose -p <déclaré> down -v est donnée, à jouer depuis le worktree |
le projet attendu seulement |
Sur Divergent, la ligne de succès le dit : ✓ projet kirexo-<worktree> détruit — vérifie <déclaré> à la main (cf. ci-dessus), au lieu de ✓ stack détruite (conteneurs, réseau, volumes). Un down -v sur un projet inexistant sort en 0 — une coche inconditionnelle rapporterait un succès jamais mesuré, et contredirait l'avertissement imprimé trois lignes plus haut.
Le re-parentage des projets singletons¶
Les deux projets Compose partagés par tout le poste — kirexo-shared (compose.shared.yaml) et kirexo-proxy (infra/proxy/compose.proxy.yaml) — sont créés une seule fois, et Compose fige leurs bind mounts en chemins absolus résolus depuis le répertoire de lancement : détruire ce répertoire laisse des conteneurs qui pointent sur un chemin disparu, où Docker recrée des dossiers vides root-owned au démarrage suivant. Le raisonnement complet est dans Un singleton est parenté sur le répertoire qui l'a créé.
Les cibles Castor ne créent plus ces projets que depuis le dépôt principal, que wt:destroy ne peut pas détruire. Cette étape conserve donc deux usages : les conteneurs créés avant cet ancrage, et ceux qu'un docker compose up lancé à la main depuis un worktree crée encore.
L'étape 8 énumère les conteneurs de ces deux projets — arrêtés compris (docker ps -aq --filter label=com.docker.compose.project=<projet>) —, inspecte chacun séparément, et lit deux signaux distincts qui ne déclenchent pas la même chose (SingletonParentage, castor/src/Worktree/SingletonParentage.php) :
| Signal lu | Prédicat | Traitement |
|---|---|---|
Un bind mount dont la source est sous le répertoire du worktree (.Mounts[] de type bind) |
hasBindInside() |
Le service est recréé depuis le dépôt principal : docker compose -p <projet> -f <fichier> up -d --force-recreate --wait --wait-timeout 90 <service>. |
Le seul label com.docker.compose.project.working_dir pointant sous ce répertoire |
hasWorkingDirInside() |
Le service est signalé, jamais touché. |
L'asymétrie est volontaire : un bind dont la source disparaît est une panne immédiate et certaine, tandis que Compose pose le label working_dir sur tous les conteneurs du projet. Recréer sur ce second signal couperait les stacks de tous les autres worktrees pour réparer celui qu'on détruit.
Les lignes affichées, dans l'ordre :
⟳ kirexo-shared : egress-proxy monté(s) depuis ce worktree — recréation depuis le dépôt principal
✓ vérifié : plus aucun montage sur le worktree, service(s) en marche
ℹ kirexo-shared : redis, rabbitmq, typesense a/ont été lancé(s) depuis ce worktree, sans bind dessus — laissé(s) tel(s) quel(s)
Cinq propriétés à connaître :
- un recensement impossible n'est pas un recensement vide. Si le
docker psd'un projet échoue, la cible ne conclut pas au silence : elle avertit (Impossible de lister les conteneurs de <projet> — Docker répond-il ?, suivi deLe parentage de ce projet sur le worktree n'a PAS été vérifié.) et compte un échec. Même traitement pour un conteneur qui disparaît entre lepset l'inspect: il est nommé, jamais ignoré ; - la coche est rendue par l'effet, pas par le code de sortie du
up. Chaque service recréé est ré-inspecté : plus aucun bind sur le worktree, projet désormais rattaché au dépôt principal, conteneurRunninget pasRestarting— un conteneur en boucle de redémarrage estRunning: trueentre deux morts ; - un échec fait sortir
wt:destroyen1. Le re-parentage alimente les échecs accumulés : la commande ne peut plus finir sur « ✓ Worktree détruit » après avoir laissé un singleton cassé. L'avertissement nomme les services restants, reprend la sortie de Docker et donne la commande exacte à rejouer depuis le dépôt principal ; - la recréation d'
egress-proxycoupe les tunnels CONNECT en cours dans tous les worktrees : le conteneur neuf obtient une autre adresse surkirexo-egress. Uncomposer installou un téléchargement en cours pendant la destruction échoue et doit être relancé ; - pour
kirexo-shared, l'allowlist est régénérée avant leup(bash infra/egress/render-allowlist.sh, depuis le dépôt principal). Son échec interrompt la recréation et est remonté : sans le fichier généré, Squid repartirait en boucle.
Les services seulement signalés restent dans un état imparfait, et c'est assumé : leur label working_dir continue de désigner un répertoire disparu. Une seule conséquence pratique, jusqu'à leur prochaine recréation — un docker compose -p <projet> ps lancé sans -f depuis un autre répertoire reste en erreur. Les passer par -f compose.shared.yaml (ou -f infra/proxy/compose.proxy.yaml) fonctionne, et castor docker:up les recrée normalement.
Jamais de down -v sur kirexo-proxy pour « repartir propre »
Le volume caddy_proxy_data porte la CA racine locale, émise pour dix ans. La détruire invaliderait tous les certificats servis et obligerait à rejouer castor cert:trust sur chaque poste. Le remède d'un singleton cassé est toujours une recréation de service (up -d --force-recreate), jamais une descente de projet avec ses volumes — c'est aussi pour cette raison que castor proxy:down n'emporte pas les volumes.
La base de données du worktree est supprimée
down -v emporte les volumes du projet — dont kirexo-<worktree>_database_pg18_data. Il n'y a pas de sauvegarde. Un ancien volume kirexo-<worktree>_database_data (PostgreSQL 16), qui n'est plus déclaré par compose.yaml, n'est pas emporté : docker volume rm à la main.
Ce que la cible ne supprime pas, volontairement :
- la branche git, locale comme distante — c'est du travail, pas un artefact ;
- les couches de l'image : seul le tag propre au worktree est retiré, les couches sont dédupliquées par digest et référencées par les autres tags ;
- le proxy hôte (
castor proxy:downest un geste séparé) et la stack mutualiséekirexo-shared: les descendre couperait la sortie réseau de tous les autres worktrees. La cible peut en revanche recréer certains de leurs services quand ils étaient montés depuis le worktree détruit — cf. Le re-parentage des projets singletons ; - les volumes hors projet —
down -vne touche que ceux du worktree, et aucun volume des deux projets singletons n'est jamais détruit.
castor wt:gc¶
Propose les worktrees dont la branche est mergée depuis plus de N jours. N'exécute aucune suppression, ne pose aucune question, et sort en 0 même avec des candidats — seule une erreur technique donne un code différent.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--days |
int | 7 |
Ancienneté minimale du merge, en jours. |
--no-fetch |
flag | false |
N'exécute pas git fetch origin main (mode hors ligne). |
La cible affiche un tableau ticket | branche | mergée, puis les commandes castor wt:destroy … à copier — une par candidat.
Deux propriétés de la détection de « mergée » :
- le squash-merge est couvert. Une MR squashée produit un commit dont la branche n'est pas ancêtre de
origin/main:git merge-base --is-ancestorrépond « non ». Un second chemin interroge alorsglabsur les MRs mergées de cette branche. Sans lui, aucun worktree ne serait jamais proposé dès qu'une MR est squashée. glaben échec rend?, jamais « non mergée ». Hors ligne ou jeton expiré, l'information est déclarée indisponible et le worktree n'est pas proposé. Les worktrees mergés dont la date est illisible sont listés à part, en avertissement.
Sortie réseau¶
Le conteneur n'a aucune route vers l'extérieur : sa seule sortie est le proxy egress-proxy (Squid, CONNECT-only), qui n'ouvre un tunnel que vers les domaines d'une allowlist par nom. Le pourquoi est dans Pourquoi la sortie réseau passe par un proxy à allowlist ; les recettes sont dans Ouvrir un domaine et Diagnostiquer un blocage réseau sortant.
| Cible | Où elle tourne | Effet |
|---|---|---|
firewall:status |
hôte et conteneur | Lecture seule. |
firewall:reload |
hôte uniquement | Écrit l'allowlist et recharge le proxy. |
firewall:whitelist-add |
hôte uniquement | Écrit dans la whitelist locale, puis recharge. |
firewall:whitelist-remove |
hôte uniquement | Idem, en retrait. |
La restriction hôte-only des trois cibles d'écriture est la moitié « procédurale » du double verrou de l'invariant C4 ; l'autre moitié est le montage :ro de infra/firewall/ dans le conteneur.
Les quatre cibles visent les fichiers du dépôt principal
Lancées depuis un worktree, elles lisent et écrivent <dépôt principal>/infra/firewall/, jamais les fichiers du checkout courant, et rendent l'allowlist par l'exemplaire de infra/egress/render-allowlist.sh du dépôt principal. La racine est résolue par le helper kirexo_main_repo() (castor.php), qui délègue à wt_main_repo (infra/worktree/wt.lib.sh) et retombe sur le répertoire du task runner si la racine rendue ne porte pas de castor.php.
Conséquence directe : la whitelist locale est commune à tous les worktrees. Le pourquoi est dans Une seule whitelist, celle du dépôt principal.
Depuis un conteneur, cet ancrage est inopérant : le dépôt principal n'y est pas monté et kirexo_main_repo() rend /app, le checkout courant. Seule firewall:status s'exécute depuis le conteneur, et elle signale le cas (voir ci-dessous).
castor firewall:status¶
Affiche les whitelists depuis lesquelles l'allowlist du proxy est rendue, en indiquant d'où elles sont lues, et sonde la sortie réseau réelle. Aucune garde d'exécution : c'est la capacité de lecture volontairement laissée à l'agent, pour qu'il puisse comprendre un blocage et demander une ouverture plutôt que chercher à la contourner.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--no-probe |
flag | false (les sondes tournent) |
N'exécute pas les trois sondes réseau — affichage des whitelists seul. |
Sortie :
- Un tableau
Origine | Domaine(baseline=infra/firewall/baseline-domains.txt,local=infra/firewall/whitelist.local.txt) et le total. - La ligne
Lu dans <dossier>— le dossier réellement lu, jamais supposé. Sur l'hôte, c'est toujours<dépôt principal>/infra/firewall; depuis un conteneur, c'est/app/infra/firewall. -
Depuis un conteneur de worktree uniquement, un avertissement de trois lignes :
⚠️ Worktree : cette whitelist n'est PAS celle que le proxy applique. La chaîne qui alimente le proxy part du dépôt principal, non monté ici. Mesure de vérité : les sondes ci-dessous.La dernière ligne devient
relance sans --no-probe pour exécuter les sondesquand les sondes sont désactivées. Le discriminant est le type de.git— un fichier dans un worktree, un dossier dans le dépôt principal — et non la simple présence du conteneur : dans la cellule du dépôt principal,/appest le dépôt principal et il n'y a rien à signaler. -
Un avertissement listant les lignes de la whitelist locale rejetées pour forme invalide, s'il y en a.
- Les valeurs effectives de
HTTPS_PROXYetNO_PROXY, plus le rappel que la résolution DNS des noms externes échoue par conception depuis le conteneur. - Trois sondes
curl(8 s maximum chacune), affichéesOK/KO:
| Sonde | Résultat attendu | Ce qu'elle prouve |
|---|---|---|
https://packagist.org via le proxy |
succès | Un domaine de l'allowlist est joignable. |
https://example.com via le proxy |
échec (403 au CONNECT) |
Un domaine hors allowlist est refusé. |
https://packagist.org avec --noproxy '*' |
échec | Il n'existe aucune route directe — pas seulement une règle qui refuse. |
Exit 0 même quand une sonde est KO : c'est un outil de lecture, pas un gate. Le gate est castor confinement:check.
Depuis un terminal hôte, les trois verdicts ne mesurent pas le proxy
Les sondes s'exécutent là où tourne Castor, et cette cible n'a aucune garde hôte/conteneur — c'est délibéré, c'est la capacité de lecture laissée à l'agent depuis sa cellule. Lancée depuis l'hôte, elle sort donc par la route normale de l'hôte : packagist.org passe, example.com passe aussi, et aucune des trois lignes ne dit quoi que ce soit de la politique appliquée par egress-proxy — y compris proxy mort. L'affichage des whitelists, lui, reste exact : il lit des fichiers.
Rien ne le signale à l'écran aujourd'hui : c'est une dette connue. Pour mesurer la sortie réelle, jouez la cible depuis le conteneur (castor wt:shell puis castor firewall:status), ou fiez-vous à l'avertissement de wt:shell/wt:claude, qui sonde par un exec et mesure donc bien la cellule.
La cible ne lit pas ce que Squid applique
Elle lit les fichiers depuis lesquels l'allowlist est rendue, jamais la politique chargée dans le conteneur. Un egress-proxy créé avant l'ancrage des singletons sur le dépôt principal peut encore monter les fichiers d'un autre répertoire : le tableau serait alors juste, et la politique appliquée différente. Seules les sondes mesurent la sortie réelle, d'où leur activation par défaut. Pour confronter les deux, cf. Comparer l'allowlist du dépôt et celle que le proxy applique.
castor firewall:reload¶
Régénère infra/egress/generated/allowlist.conf depuis infra/firewall/baseline-domains.txt + infra/firewall/whitelist.local.txt, puis la recharge à chaud dans le proxy. Hôte uniquement — depuis le conteneur, la cible sort en erreur et renvoie vers castor firewall:status. Les trois chemins sont ceux du dépôt principal, y compris lancée depuis un worktree.
Trois étapes :
bash infra/egress/render-allowlist.sh— valide chaque ligne (une ligne invalide est ignorée avec un avertissement, jamais fatale), dédoublonne les domaines couverts par un parent, trie, et écrit chaque entrée sous la forme.<domaine>parmktemp+mvatomique. Sort en erreur si l'allowlist produite serait vide.squid -k reconfiguresur le serviceegress-proxydu projetkirexo-shared. Squid parse la configuration puis s'envoie unSIGHUP: le processus n'est pas redémarré et les tunnels TLS en cours ne sont pas coupés.- Vérification par l'effet — le fichier généré est confronté à celui que le conteneur porte réellement (
exec egress-proxy cat /etc/squid/generated/allowlist.conf). En cas d'écart, la cible sort en1avec le remède.
« Le proxy n'applique PAS cette allowlist » : un conteneur hérité
L'écart de l'étape 3 signale un egress-proxy qui monte les fichiers d'un autre répertoire que celui d'où le rendu vient d'avoir lieu. Depuis l'ancrage des singletons sur le dépôt principal, la cible ne peut plus le produire elle-même : le message ne devrait apparaître que sur un conteneur créé avant. Le remède affiché est la recréation du service :
Il coupe brièvement la sortie réseau de tous les worktrees — et lancé depuis le dépôt principal, il est définitif : la contrainte ne se déplace plus vers un autre répertoire.
castor firewall:whitelist-add¶
Ajoute un domaine à la whitelist locale (infra/firewall/whitelist.local.txt, gitignored) puis appelle firewall:reload. Hôte uniquement : le fichier est monté :ro dans le conteneur. Le fichier écrit est celui du dépôt principal — donc celui que le proxy lit — même lancée depuis un worktree, et l'ajout vaut pour tous les worktrees du poste.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
domain |
string | — (obligatoire) | Domaine à autoriser, sans schéma ni chemin (ex. raw.githubusercontent.com). |
Étapes :
- Validation — regex FQDN partagée avec
castor/src/Firewall/FirewallWhitelist.php: pas d'URL, pas de wildcard, pas d'IP littérale, pas de single-label. Message d'erreur actionnable et exit1si invalide. - Dédoublonnage baseline — si le domaine y figure déjà, directement ou comme sous-domaine d'une entrée existante, la cible n'écrit rien et l'annonce.
- Dédoublonnage local — idem contre les entrées déjà présentes dans le fichier local.
- Append — ajoute la ligne en fin de fichier, commentaires et lignes existantes préservés.
- Reload — appelle
firewall:reload.
castor firewall:whitelist-remove¶
Retire un domaine de infra/firewall/whitelist.local.txt puis recharge l'allowlist. Hôte uniquement. Même ancrage que whitelist-add : le fichier visé est celui du dépôt principal, et le retrait vaut pour tout le poste. Ne touche pas à la baseline versionnée — pour ça, éditer infra/firewall/baseline-domains.txt à la main et commiter.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
domain |
string | — (obligatoire) | Domaine à retirer du fichier local. |
Le fichier est réécrit en conservant commentaires et lignes vides à l'identique. Si la ligne n'existe pas, la cible affiche une note et n'exécute pas le rechargement.
Préalable commun aux cibles qui démarrent une stack¶
castor docker:up, castor docs:build, castor image:refresh et castor wt:up exécutent tous le même préalable, factorisé dans un helper unique de castor.php (fonction shared_stack_up(), sans #[AsTask] — ce n'est pas une cible invocable). Il est idempotent de bout en bout.
Toutes ses étapes d'infrastructure s'exécutent depuis le dépôt principal, quel que soit le checkout d'où part la cible : c'est le répertoire de lancement que Compose fige dans les conteneurs du projet singleton kirexo-shared. Seule l'étape « espace Claude » y échappe, ses chemins visant $HOME et non le dépôt.
| Étape | Effet | Mode de panne évité |
|---|---|---|
| Espace Claude commun + jeton GitLab | Cf. castor claude:space. |
Docker crée des dossiers root-owned dans $HOME à la place des binds. |
| Réseau du proxy hôte | bash infra/proxy/proxy-net.sh, qui crée kirexo-proxy (--internal) s'il manque. Le conteneur du proxy, lui, reste démarré par castor proxy:up : le préalable ne garantit que l'existence du réseau. |
network kirexo-proxy declared as external, but could not be found. |
| Whitelist locale | Crée <dépôt principal>/infra/firewall/whitelist.local.txt depuis le modèle .dist si absente — c'est celle que le rendu de l'étape suivante lira. Celle d'un worktree est créée par castor wt:up pour servir de substrat au bind :ro de l'invariant C4, pas pour alimenter le proxy. |
Le dev ne sait pas où écrire ; le bind :ro n'a pas de fichier stable. |
| Rendu de l'allowlist | bash infra/egress/render-allowlist.sh, l'exemplaire du dépôt principal — le script résout ses fichiers depuis son propre emplacement, c'est donc lui qui décide de la source et de la destination. |
Squid refuse de parser sa configuration → conteneur unhealthy, --wait bloqué. |
Démarrage de kirexo-shared |
docker compose -p kirexo-shared -f <dépôt principal>/compose.shared.yaml up -d --wait, ce qui crée le réseau externe kirexo-egress. Le chemin absolu du -f est ce qui fixe le parentage des conteneurs. |
network kirexo-egress declared as external, but could not be found ; singleton parenté sur un répertoire destructible. |
Le premier docker:up après la mise à jour recrée les deux singletons
Leur parentage change : kirexo-shared et kirexo-proxy sont donc recréés au premier passage sur un poste existant. Deux effets à attendre, le temps du up --wait :
- coupure brève de la sortie réseau — les tunnels
CONNECTen cours sont perdus dans tous les worktrees, uncomposer installou un téléchargement en cours échoue et doit être relancé ; - coupure brève des services mutualisés et du proxy hôte — Redis, RabbitMQ, Typesense, Gotenberg, Mailpit, et le point d'entrée web
*.localhost.
Tant qu'un worktree tourne encore l'ancien castor.php, un ping-pong de recréation est possible : chaque cible réancre les singletons sur son propre parentage, et le suivant les réancre à l'inverse. Le remède est de mettre tous les worktrees à jour ; il n'y a rien d'autre à jouer.
Un docker compose up lancé à la main ne traverse aucune cible Castor
Le préalable n'est joué que par les quatre cibles ci-dessus. Un démarrage direct par docker compose up l'ignore, et la stack revient sans réseau kirexo-egress, donc sans sortie réseau — panne silencieuse. Les lignes exactes à rejouer sont dans Diagnostiquer un blocage réseau sortant.
Dépendances applicatives¶
castor install¶
Installe les dépendances applicatives dans le conteneur php, en enchaînant trois étapes :
composer install --no-interaction— paquets PHP dansvendor/.bin/console importmap:install— assets JavaScript gérés par Symfony Asset Mapper.bin/console tailwind:build— compilation du CSS Tailwind verspublic/.
À lancer après chaque git pull qui modifie composer.lock, importmap.php ou les sources Tailwind (assets/styles/).
castor reinstall¶
Supprime composer.lock et vendor/, puis résout les dépendances depuis le composer.json courant (équivalent d'un composer update complet) et réinstalle l'importmap. Utile quand le lock est désynchronisé des contraintes, typiquement après une montée de version de PHP ou Symfony.
Opération destructive sur le lock
composer.lock est supprimé puis régénéré : les versions résolues peuvent changer. À utiliser en connaissance de cause.
castor tailwind:build¶
Compile le CSS Tailwind de assets/styles/app.css vers public/. La cible install l'appelle déjà en fin de parcours ; utilisez cette cible directement pour recompiler après avoir modifié vos styles.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--watch |
flag | false |
Recompile en continu dès qu'un fichier source change. |
castor php¶
Lance une commande php dans le conteneur php. Pratique pour inspecter la version ou exécuter un script ponctuel.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
arg |
string | --version |
Arguments passés à php. |
castor console¶
Lance une commande Symfony Console dans le conteneur php.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
arg |
string | list |
Commande Symfony Console à exécuter. |
castor composer¶
Lance une commande Composer dans le conteneur php.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
arg |
string | list |
Commande Composer à exécuter. |
castor mate¶
Lance Symfony AI Mate (vendor/bin/mate) dans le conteneur php. Le composant est une dépendance de développement — il sert aux agents IA de développement, jamais à l'application en production.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
arg |
string | '' |
Arguments passés à vendor/bin/mate. Vide = aide de l'outil. |
castor cache:clear¶
Vide le cache Symfony de l'environnement courant (bin/console cache:clear). À appeler après un changement de configuration ou de service pour forcer la reconstruction du conteneur de services.
Qualité¶
castor cs:fix¶
Applique PHP-CS-Fixer sur le code PHP.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--dry-run |
flag | false |
Affiche le diff sans modifier les fichiers. |
castor phpstan¶
Lance PHPStan en analyse statique.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--level |
int | 8 |
Niveau de sévérité PHPStan. |
castor lint¶
Vérifie la syntaxe et la cohérence du projet en enchaînant quatre sous-étapes :
bin/console lint:twig templates/— syntaxe des templates Twig.bin/console lint:yaml config/— validité des fichiers YAML de configuration.bin/console lint:container— cohérence du conteneur de services Symfony.castor lint:shell—shellchecksur les scripts deinfra/, les hooks Claude et la mécanique des skills.
castor lint:shell¶
Lance shellcheck --severity=warning --shell=bash sur cinq globs, définis dans castor.php :
| Glob | Ce qu'il couvre |
|---|---|
.claude/hooks/*.sh |
Hooks Claude Code (stop-checklist.sh, guard-delegation.sh, session-dashboard.sh, …). |
.claude/hooks/lib/*.sh |
Sous-scripts sourcés par les hooks (checklist-common.sh, checklist-container.sh, checklist-host.sh, …). |
.claude/skills/*/bin/*.sh |
Mécanique shell des skills projet — chaque skill a son bin/ autonome. |
infra/*.sh |
Scripts d'infrastructure posés à la racine de infra/. |
infra/*/*.sh |
Scripts d'infrastructure par domaine : claude-space/, confinement/, coredump/, egress/, healthcheck/, image/, lib/, mcp/, motd/, proxy/, supervisor/, worktree/. |
Un bug syntaxique silencieux dans un hook ne remonte qu'au prochain déclenchement (logs des hooks peu visibles) — shellcheck statique le détecte avant exécution.
Le glob PHP n'est pas récursif
D'où les deux globs infra/*.sh et infra/*/*.sh : un script posé à la racine de infra/ serait sinon ignoré en local alors que le job CI quality:shellcheck, lui, fait un find récursif — vert en local, rouge en CI. Symétriquement, un script placé à un troisième niveau — un sous-dossier d'un domaine de infra/ — échapperait à cette cible : le job CI le rattraperait, pas elle.
Si shellcheck est absent du conteneur (image antérieure à l'ajout dans Dockerfile), la cible échoue avec un message actionnable demandant de relancer castor docker:build.
Inclus dans castor lint
Cette cible est la 4ᵉ sous-étape de castor lint. L'invocation directe n'a d'intérêt que pour débugger un problème spécifique aux scripts shell, sans rejouer les linters Twig/YAML/conteneur.
castor ts:check¶
Vérifie le typage TypeScript des sources front (tsc --noEmit -p tsconfig.json). La version de TypeScript n'est jamais résolue en latest : elle est lue dans devDependencies.typescript de package.json et injectée dans npx -p, faute de quoi le pin du projet serait ignoré. Le projet n'a ni node_modules/ ni yarn.lock — les dépendances front passent par Asset Mapper.
Deux chemins d'exécution selon le côté :
| Côté | Exécution |
|---|---|
Conteneur php |
Directement, avec le node embarqué dans l'image (cf. Node et Claude Code). |
| Hôte | Conteneur node:22-alpine éphémère, cache npm persisté dans le volume nommé kirexo_npm_cache. Rien à installer sur le poste. |
Inclus dans castor all
Elle est enchaînée par castor all, entre lint et doctrine:schema:validate. Elle n'est pas dans castor qa, qui s'arrête au périmètre PHP.
castor composer:validate¶
Vérifie la cohérence de composer.json et de composer.lock : composer validate --strict --no-check-publish. Aucun argument.
Les deux options sont celles du job CI build:vendor (.gitlab/ci/quality.yml), au --no-interaction près :
| Option | Effet |
|---|---|
--strict |
Transforme en erreurs les avertissements que la sortie par défaut laisse passer : clé dupliquée dans composer.json, dépendance abandonnée, composer.lock désynchronisé. Sans elle, composer validate rend « valid, but with a few warnings » et sort en 0. |
--no-check-publish |
Ignore les champs de publication (name, description, license) — le projet n'est pas un package Composer publié. |
Cible légère, comme castor audit : seuls composer.json et composer.lock sont lus, ni la stack ni vendor/ ne sont nécessaires. Depuis l'hôte, où Composer n'est pas installé, elle passe par un conteneur composer:2 éphémère qui monte le dépôt ; rien n'est écrit dans le projet, donc aucun souci d'appartenance de fichiers. Implémentation : castor.php.
Première étape de castor all
castor all la joue en 1/9, avant cs:fix : c'est le contrôle le plus rapide de la liste (deux fichiers lus) et le plus fondamental — un composer.json incohérent rend la suite sans objet. Elle n'est pas dans castor qa. Le pendant CI est décrit dans Cache Composer (build:vendor).
Jamais plus permissive que la CI
Une cible locale plus tolérante que son homologue CI ne prévient de rien : elle passe au vert sur ce qui fera échouer le pipeline, et déplace la découverte du défaut après le push. Cas vécu le 2026-09-20 — une résolution de conflit de rebase avait laissé symfony/phpunit-bridge deux fois dans composer.json : composer validate nu sortait en 0, et la pipeline de la MR de clôture a échoué là-dessus, sur rien d'autre.
castor audit¶
Audit des vulnérabilités connues des dépendances Composer : composer audit --locked. À lancer avant chaque push.
Cible légère : --locked ne lit que composer.lock et interroge l'API Packagist — ni la stack, ni vendor/ ne sont nécessaires. Depuis l'hôte, elle passe par un conteneur composer:2 éphémère qui monte le dépôt ; rien n'est écrit dans le projet, donc aucun souci d'appartenance de fichiers.
Doctrine¶
castor doctrine:schema:validate¶
Vérifie que le schéma BDD est synchronisé avec les entités Doctrine. Cette cible est l'un des garde-fous de CLAUDE.md — elle doit passer en permanence.
castor doctrine:migrate¶
Applique les migrations Doctrine en attente, en mode --all-or-nothing (une seule transaction, rollback total en cas d'échec).
castor doctrine:diff¶
Génère une migration Doctrine à partir du diff entre les entités et le schéma BDD courant.
castor fixtures:load¶
Charge les fixtures DoctrineFixturesBundle en base de données. Sans --append, la base est purgée puis rechargée depuis zéro (comportement par défaut).
| Option | Type | Défaut | Effet |
|---|---|---|---|
--append |
flag | false |
Ajoute les fixtures sans vider la base au préalable. |
Données supprimées
Sans --append, toutes les données existantes sont effacées. À réserver à l'environnement de développement.
Pas nécessaire avant les tests
tests/bootstrap.php exécute déjà database:create, migrations:migrate puis fixtures:load au démarrage de PHPUnit — castor test:unit, castor test:e2e et castor test:coverage partent toujours d'une base fixturée à neuf. La cible reste utile pour rejouer les fixtures sur la base de dev (repeuplement manuel lors d'une exploration locale). Détail dans Exécuter les tests — Préparation automatique de la BDD.
Tests¶
castor test:unit¶
Lance PHPUnit sur les suites unit et integration.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--filter |
string | '' |
Filtre PHPUnit pour ne lancer qu'un test précis. |
castor test:e2e¶
Lance PHPUnit sur la suite e2e (tests Panther, pages uniquement).
| Option | Type | Défaut | Effet |
|---|---|---|---|
--filter |
string | '' |
Filtre PHPUnit. |
castor test:coverage¶
Lance PHPUnit avec un rapport de couverture. Suites unit + integration par défaut. Le rapport est textuel dans le terminal ; avec --html, un rapport HTML est généré dans var/coverage/.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--with-e2e |
flag | false |
Inclut la suite e2e (Panther) dans le run de couverture. Vérifie d'abord que la stack est up et que le conteneur php est healthy — sinon exit 1 avec un message explicite. |
--html |
flag | false |
Génère un rapport HTML dans var/coverage/ au lieu du rapport textuel. |
castor test:bash¶
Lance bats sur les tests des libs Bash du projet (tests/Bash/, parcouru en --recursive). Ces libs ne contiennent que des fonctions pures — elles produisent du texte à partir de texte — donc aucun privilège n'est requis pour les tester.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--filter |
string | '' |
Motif bats, pour ne lancer qu'un test ou un groupe. |
bats absent du conteneur
Le binaire vient du Dockerfile. Si l'image n'a pas été reconstruite depuis son ajout, la cible bascule sur une éventuelle installation npm globale (/home/app/.npm-global/bin/bats) ; à défaut, elle échoue avec les deux remèdes plutôt qu'un bats: not found.
castor test:path-coverage¶
Couverture lignes + branches (--path-coverage de PHPUnit) d'un fichier de production, en local. À lancer en fin de développement sur chaque fichier modifié ou créé — c'est la colonne « Branches » qui compte, pas « Paths », qui mesure les combinaisons de chemins.
C'est le seul contrôle de branches du projet : la CI ne porte qu'un gate de lignes (cf. Pipeline GitLab CI). Le seuil est ≥ 80 %, et non 100 % : certaines branches sont structurellement inatteignables — l'UnhandledMatchError d'un match exhaustif sur enum, par exemple — ce qui plafonne mécaniquement le ratio. Source de vérité du seuil : .claude/skills/_shared/tests-couverture-quota.md.
| Argument / option | Type | Défaut | Effet |
|---|---|---|---|
file |
string | (obligatoire) | Fichier de production dont le rapport est restreint (--coverage-filter). Fichier introuvable = sortie 1. |
--filter |
string | '' |
Filtre PHPUnit. Omis, la cible avertit : sans lui, toute la suite tourne sous pathCoverage et sature la mémoire. |
Le run est borné à memory_limit=2G — jamais -1, qui produit un Bus error et un coredump — et couvre les suites unit et integration. Le rapport est écrit dans var/path-coverage.txt puis affiché : le printer PHPUnit du projet avale la sortie de couverture sur la sortie standard, elle ne peut donc pas y être lue directement.
La mémoire est saturée par le volume de tests, pas par le périmètre du rapport
Xdebug collecte les chemins de tout le code exécuté ; --coverage-filter ne restreint que l'affichage. C'est donc --filter, qui restreint les tests joués, qui tient la mémoire.
Messenger¶
castor messenger:consume¶
Lance un worker Messenger ponctuel dans le conteneur php avec une limite de temps de 3 600 secondes (bin/console messenger:consume $transport --time-limit=3600). En production, le redémarrage est géré par la restart policy Docker — ne pas relancer manuellement.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
transport |
string | async |
Nom du transport Messenger à consommer. |
Refus si le worker supervisé tourne déjà
En développement, un worker Messenger tourne en permanence dans le conteneur php, sous le supervisor (transports plugin_web et async). Cette cible refuse alors de démarrer (exit 1) : deux consommateurs sur les mêmes transports traiteraient chaque message deux fois — un e-mail envoyé en double, un cache de site invalidé deux fois — sans qu'aucune trace ne l'explique.
Le contrôle (supervisor.sh status messenger) vaut depuis l'hôte comme depuis le conteneur : lancée depuis l'hôte, la cible aboutit dans le même conteneur php et produirait exactement la même double consommation. Le message d'erreur pointe vers castor supervisor:worker-restart et vers var/log/supervisor/messenger.log.
Pour un worker ad hoc, arrêter d'abord le worker supervisé : infra/supervisor/supervisor.sh stop messenger. Détail dans Relancer FrankenPHP ou le worker Messenger.
Raccourcis¶
castor qa¶
Enchaîne cs:fix → phpstan → lint → doctrine:schema:validate dans l'ordre imposé par CLAUDE.md. À lancer avant toute délégation au reviewer.
castor test¶
Enchaîne test:unit → test:bash → test:e2e.
castor all¶
Checklist applicative complète avant clôture, à lancer depuis l'intérieur du conteneur php : enchaîne composer:validate → cs:fix → phpstan → lint → ts:check → doctrine:schema:validate → test:unit → test:bash → test:e2e, soit neuf étapes numérotées n/9 à l'écran. Aligné avec la checklist documentée dans CLAUDE.md (ordre choisi pour que chaque étape travaille sur du code stabilisé par la précédente).
composer:validate ouvre la liste : c'est le contrôle le plus rapide (deux fichiers lus, ni stack ni vendor/) et le plus fondamental. En fin de liste, il ferait payer huit étapes avant d'apprendre que composer.lock est désynchronisé.
C'est l'équivalent de la checklist dynamique affichée par le hook stop-checklist.sh quand Claude clôture une tâche côté conteneur (.claude/hooks/lib/checklist-container.sh). Pour le pendant côté hôte (infrastructure), voir castor host:check.
castor host:check¶
Checklist côté hôte : valide les fichiers d'infrastructure que le conteneur n'est pas censé modifier (ou ne peut pas — verrous Claude). Refuse l'exécution depuis l'intérieur du conteneur. Quatre sous-étapes :
lint:shell—shellchecksurinfra/,.claude/hooks/et.claude/skills/*/bin/. Identique à la sous-étape 4 decastor lint, ré-exécutée ici parce que ces scripts sont la cible privilégiée d'édition hôte.docker compose config -q— valide la fusioncompose.yaml+compose.override.yaml. Exit non nul si typo, référence cassée ou type incorrect.hadolintsurDockerfile—docker run --rm -i hadolint/hadolint:latest hadolint --no-color --failure-threshold error - < Dockerfile. Seuls les niveauxerror/fatalfont échouer la cible ; leswarningetinfo(notammentDL4006hérité dedunglas/symfony-docker) sont remontés à l'écran sans bloquer. L'image hadolint est pullée au premier appel (~3 s), instantanée ensuite.- HEAD HTTP sur les URLs construites depuis les
ARG *_VERSIONdu Dockerfile — Castor et glab uniquement. Node n'est plus sondé : il passe parapk(paquet Alpinenodejs), et un paquet ou une version absente fait échouerapk addau build lui-même — pas besoin de pré-check réseau. Les URLs sont reconstruites parToolsUpgrader::buildDockerfileUrls()(castor/src/Image/ToolsUpgrader.php, testée unitairement) pour garantir qu'on probe exactement les URLs utilisées par lesRUN curl …du Dockerfile. Codes acceptés :200,301,302(les Releases GitHub/GitLab redirigent en HEAD). Les requêtes sont lancées en parallèle via background jobs bash, timeout 5 s par URL. Modèle de panne adressé : une release upstream supprimée, déplacée ou renommée — le prochaindocker buildtéléchargerait une page d'erreur HTML, lesha256sum -crejetterait silencieusement le fichier corrompu, message cryptique. Le check attrape la rupture avant le rebuild.
C'est l'équivalent de la checklist dynamique affichée par le hook stop-checklist.sh quand Claude clôture une tâche côté hôte (.claude/hooks/lib/checklist-host.sh).
Depuis le conteneur
Lancée depuis l'intérieur, la cible exit 1 avec un message qui pointe vers castor all (la checklist applicative). La raison : host:check valide des fichiers d'infrastructure (Dockerfile, compose*.yaml, scripts infra/) typiquement édités depuis l'hôte. Passer la checklist hôte depuis le conteneur donnerait l'illusion d'avoir validé quelque chose qui n'a pas été testé dans le bon environnement.
Diagnostic¶
castor doctor¶
Vérifie l'environnement de développement et imprime une matrice OK/KO ligne par ligne. À utiliser à l'onboarding (un nouveau développeur veut savoir si son setup est complet) ou pour un diagnostic rapide quand un test E2E échoue ou que la stack semble lente.
Aucun argument. Le code de sortie est 0 si tous les checks passent, 1 dès qu'au moins un check échoue.
Cible unique, sensible au contexte : elle ne diagnostique pas la même chose des deux côtés, et bascule seule selon qu'elle tourne sur l'hôte ou dans le conteneur php. Les deux diagnostics regardent des objets différents — binaires hôte et conteneurs démarrés d'un côté, services internes et sortie réseau de l'autre — mais c'est une seule question posée de deux endroits, à laquelle une seule commande répond.
Depuis l'hôte¶
- Binaires hôte requis : présence de
docker,jq,glabetgitdans lePATH. - Plugin Docker Compose v2 :
docker compose versiondoit répondre. - État de chaque service de la stack (
php,database,redis,rabbitmq,typesense,gotenberg,mailer,docs) : le service doit être présent, sonStatedoit êtrerunninget sonHealthdoit êtrehealthy(les services sans healthcheck remontent une chaîne vide pourHealthet sont tolérés). - Worker Messenger vivant dans le conteneur
php:docker compose exec -T php /app/infra/supervisor/supervisor.sh status messenger. Le worker n'est pas un service Compose — il vit sous le supervisor dans le conteneurphp— donc sa disparition serait autrement invisible du diagnostic hôte. Exécuté uniquement siphpestrunning. - Migrations Doctrine à jour :
bin/console doctrine:migrations:up-to-datedoit passer. Ce check n'est exécuté que si le servicephpestrunning— sinon il serait systématiquement KO sans information utile.
En cas d'échec, la cible affiche avant l'erreur finale la remédiation hôte du moment : castor wt:up <ticket> si la variable WT est définie, castor docker:up sinon. Elle n'est jamais écrite en dur — elle vient de host_action_hint() (castor.php), partagée avec le bloc « Remédiations » du diagnostic interne. C'est précisément ce qui garantit qu'elle désigne toujours une cible existante : la fonction suit les renommages de cibles, là où une chaîne en dur proposerait une commande morte au pire moment — celui où l'on cherche déjà pourquoi rien ne marche.
Depuis le conteneur php¶
Les checks, dans l'ordre :
- Sortie réseau via le proxy (allowlist respectée) — rejoue les trois sondes de
castor firewall:status: un domaine de l'allowlist passe, un domaine hors allowlist est refusé, et aucune route directe ne subsiste hors proxy. Il n'y a nidnsmasq, niipset, ni sudoers à interroger dans le conteneur : la politique vit dans le proxy, sur le projet mutualisé — on mesure donc l'effet. La troisième sonde est la seule à distinguer « une règle refuse » de « il n'y a pas de route ». - Binaires
castor,glab,node,npm,claudedisponibles — résolus dans lePATHviaSymfony\Component\Process\ExecutableFinder. Détecte unimage:upgrade-toolscassé, un rebuild incomplet ou unPATHcorrompu. whitelist.local.txtparsable (si le fichier existe) — chaque ligne non commentée est confrontée àFirewallWhitelist::readLocalRejected(). Les lignes rejetées sont listées explicitement dans le rapport. Le fichier examiné est celui du checkout courant : lancé depuis le conteneur d'un worktree, ce check porte donc sur un fichier que le proxy ne lit pas, et — contrairement àcastor firewall:status— il ne le signale pas. Dette connue ; en cas de doute sur l'allowlist réellement appliquée, s'en remettre aux sondes du check 1.- FrankenPHP répond sur
http://127.0.0.1—curl -fsIavec timeout 5 s. - Supervisor
frankenphpactif et Supervisormessengeractif — code de retour deinfra/supervisor/supervisor.sh status <programme>. Deux lignes distinctes, jamais une seule : un FrankenPHP mort et un worker mort ont des symptômes sans rapport (502 d'un côté, e-mails et publications muets de l'autre) et des remèdes distincts. C'est aussi le seul endroit où le worker est surveillé : le healthcheck Docker du servicephpl'ignore volontairement, pour qu'un worker mort ne rende pas le conteneurunhealthyet ne casse pas le préflight detest:e2e. - Transports Messenger joignables (
plugin_web,async) —bin/console messenger:stats plugin_web async. Distingue « worker mort » de « broker injoignable » : les deux se manifestent par des e-mails qui ne partent pas et des articles publiés absents de leur site public, mais l'un se répare dans le conteneur et l'autre depuis l'hôte (RabbitMQ est un service de la stack). - Résolution intra-stack —
getent hostspourdatabase,redis,rabbitmq,typesense,gotenberg,mailer. Un KO ici pointe typiquement une stack partiellement recréée, pas un problème de proxy (cf. Diagnostiquer un blocage réseau sortant). - Migrations Doctrine à jour —
bin/console doctrine:migrations:up-to-date, exécuté uniquement sidatabaserépond (sinon faux négatif).
Bloc « Remédiations » (variante conteneur)¶
Quand au moins un check échoue, un bloc est affiché après le tableau. Chaque ligne KO porte un remède et un scope : in (réparable depuis le conteneur) ou host (seul un terminal hôte le peut). Les commandes sont dédoublonnées.
Remédiations :
• dans le conteneur : castor supervisor:worker-restart
• action hôte requise : castor image:refresh
• action hôte requise : castor docker:up
(terminal HÔTE, hors conteneur — Démarre la stack du dépôt principal depuis un terminal hôte (idempotent).)
| Check KO | Scope | Remédiation affichée |
|---|---|---|
| Sortie réseau via le proxy | host |
(le proxy vit dans le projet mutualisé kirexo-shared) |
| Binaire embarqué manquant | host |
castor image:refresh |
whitelist.local.txt parsable |
host |
castor firewall:whitelist-remove <domaine> |
FrankenPHP répond sur 127.0.0.1 |
in |
castor supervisor:frankenphp-restart |
Supervisor frankenphp actif |
in |
castor supervisor:frankenphp-restart |
Supervisor messenger actif |
in |
castor supervisor:worker-restart |
| Transports Messenger joignables | host |
(RabbitMQ est un service de la stack) |
| Résolution intra-stack | host |
(action hôte) |
| Migrations Doctrine | in |
castor doctrine:migrate |
Le scope n'est pas décoratif : afficher in sur une cible hôte-only enverrait l'agent lancer une commande qui refuse de tourner. C'est le cas de firewall:whitelist-remove, hôte-only parce que les whitelists sont montées :ro dans le conteneur (invariant C4).
Le proxy sortant n'est pas dans la matrice hôte
Côté hôte, castor doctor inspecte la stack du worktree ; le proxy vit dans le projet kirexo-shared. Pour son état : castor firewall:status, ou docker compose -p kirexo-shared -f compose.shared.yaml ps.
Monitoring¶
castor monitor¶
Lance Ember (TUI alexandredaubois/ember) branché sur l'admin API Caddy interne (http://php:2019) du service FrankenPHP, pour visualiser en temps réel :
- les métriques serveur : requêtes/s, latences (TTFB, P50 → P99), status codes, TLS, workers/threads/queue/mémoire FrankenPHP ;
- le hub Mercure : abonnements (API
/.well-known/mercure/subscriptions) et compteursmercure_*de/metrics.
Le conteneur Ember est jetable (--rm) et rejoint le réseau Docker kirexo — l'admin API :2019 n'est jamais publiée publiquement. Quitter avec q.
Aucun argument. Cible hôte uniquement : refuse l'exécution dans le conteneur php (socket Docker non monté). Nécessite la stack up et le service php healthy (preflight, sinon exit 1).
Moniteur live, pas de la supervision prod
Ember n'historise rien et ne déclenche aucune alerte. Pour de la supervision durable (historique, seuils, alertes), il faudrait Prometheus + Grafana — hors périmètre. Détail dans Monitorer le serveur et Mercure avec Ember.
Supervision des process long-running¶
Dans le conteneur php, FrankenPHP et le worker Messenger sont pilotés par un supervisor maison en Bash (infra/supervisor/supervisor.sh) : chaque programme a sa boucle, son PID file (var/run/supervisor/) et son journal (var/log/supervisor/). Le supervisor garantit une seule boucle par programme. Les deux cibles ci-dessous en recyclent un seul à la fois, jamais les deux.
Quand les deux boucles ont abandonné, le conteneur ne sort pas : il bascule en mode maintenance pour rester joignable et réparable, healthcheck rouge. Le détail est dans Worktrees — Mode maintenance.
Ces gestes sont répartis en trois namespaces, selon ce qu'ils pilotent
Relancer un process, rafraîchir l'image, ouvrir un domaine : ces gestes ont longtemps partagé un namespace unique, nommé d'après l'environnement de développement plutôt que d'après leur objet. Ils sont classés selon ce qu'ils pilotent réellement, ce qui rend le côté d'exécution lisible dans le nom. Table d'entrée par intention :
| Ce que vous voulez faire | Cible | Où elle tourne |
|---|---|---|
| Relancer FrankenPHP seul | supervisor:frankenphp-restart |
conteneur |
| Recycler le worker Messenger seul | supervisor:worker-restart |
conteneur |
| Savoir si un outil figé a une version plus récente | image:check-tools |
hôte |
Appliquer ces bumps dans le Dockerfile |
image:upgrade-tools |
hôte |
| Tirer l'image publiée et recréer le conteneur | image:refresh |
hôte |
| Diagnostiquer l'environnement | castor doctor, qui bascule seul selon le contexte |
hôte et conteneur |
| Démarrer une stack | docker:up ou wt:up |
hôte |
| Réinstaller les dépendances applicatives | install |
conteneur |
| Recharger l'allowlist du proxy sortant | firewall:reload |
hôte |
| Ouvrir ou fermer un domaine | firewall:whitelist-add / -remove |
hôte |
| Lire l'allowlist et sonder la sortie réseau | firewall:status |
hôte et conteneur — mais les sondes ne mesurent le proxy que depuis le conteneur |
Il n'existe aucune cible d'amorçage séparée : composer install, importmap:install et tailwind:build sont joués en avant-plan par docker:up et wt:up, où un échec se voit tout de suite au lieu d'attendre la lecture d'un marqueur. castor install reste le rattrapage manuel.
castor supervisor:frankenphp-restart¶
Relance le programme FrankenPHP supervisé dans le conteneur php, après un bail-out (la boucle abandonne au bout de MAX_CRASHES = 5 crashs consécutifs sans stabilisation) ou un kill manuel. Ne touche jamais au worker Messenger : les deux programmes ont des boucles, des PID files et des journaux séparés. Restreinte à l'intérieur du conteneur php — depuis l'hôte, l'unité de manipulation est le conteneur entier (castor docker:up / docker:down).
Étapes effectuées par la cible :
- Garde anti-redémarrage rapproché — si FrankenPHP a démarré il y a moins de 30 secondes (epoch lu dans
var/run/supervisor/frankenphp.started_at), la cible refuse et sort en1. Voir l'encadré ci-dessous.--forceoutrepasse. - Redémarrage sous verrou —
infra/supervisor/supervisor.sh restart frankenphp, c'est-à-direstoppuisspawn, sans qu'une autre relance puisse s'intercaler. Le verrou estvar/run/supervisor/supervisor.lock, et la relance automatique du healthcheck l'attend aussi.stoparrête toutes les bouclesfrankenphpdécouvertes, par/procet par le PID file :SIGTERMà toutes, puisSIGKILLà la boucle et à ses enfants après le délai de grâce.spawnen relance une seule. Résultat : une seule boucle et un seulfrankenphp runpar programme, même si le PID file avait disparu. Le journal restevar/log/supervisor/frankenphp.log, lisible à l'identique depuis l'hôte et depuis le conteneur (/appest bind-monté sur la racine du dépôt).
| Option | Type | Défaut | Effet |
|---|---|---|---|
--force |
flag | false |
Outrepasse la garde des 30 secondes. |
Aucun pkill — et pourquoi
Les versions antérieures tuaient par motif de ligne de commande (pkill -f frankenphp-supervisor.sh, pkill -f 'frankenphp run'). Ce n'est plus le cas, et ce serait aujourd'hui dangereux : le script frankenphp-supervisor.sh n'existe plus, et un pkill -f supervisor.sh emporterait aussi la boucle du worker Messenger. Le supervisor découvre ses boucles par /proc (ligne de commande exacte supervisor.sh start <programme> et même KIREXO_WORKSPACE), complété par le PID file, et n'agit que sous verrou. Il ne tue jamais par motif. Détail : Worktrees — Supervision des process long-running.
Refus à moins de 30 secondes du dernier démarrage
Deux redémarrages rapprochés font échouer le module Mercure de Caddy sur provision http.handlers.mercure.bolt: invalid transport: timeout : le lock du fichier bolt est encore tenu par le process précédent. FrankenPHP boucle alors sur le crash, la boucle abandonne au bail-out, et l'application reste à 000 — pour un geste censé la réparer. D'où le refus explicite :
FrankenPHP a démarré il y a 8 s — trop récent pour un redémarrage.
Le hub Mercure tient encore le lock du transport bolt : relancer maintenant provoque
un crash-loop (`invalid transport: timeout`) qui laisse l'application à 000.
Aucune garde équivalente n'existe côté worker : le lock bolt est tenu par le module Mercure de Caddy, jamais par un process PHP CLI.
Pour vérifier la relance : tail -f var/log/supervisor/frankenphp.log, ou castor doctor depuis le conteneur (qui teste la réponse HTTP sur 127.0.0.1 et l'état de la boucle). Un bail-out se lit dans le journal sous la forme 5 crashs consécutifs sans stabilisation — abandon de CE programme (les autres continuent)., suivi de la cible de relance à jouer.
Quand l'utiliser
Symptôme typique : castor doctor, lancé depuis le conteneur, rapporte « FrankenPHP répond sur http://127.0.0.1 ✗ KO » ou « Supervisor frankenphp actif ✗ KO » alors que la sortie réseau et les services Compose sont sains. Inspecter var/log/supervisor/frankenphp.log pour confirmer un bail-out, corriger la cause (Caddyfile, code PHP qui boucle au boot) puis relancer cette cible. Recette complète : Relancer FrankenPHP ou le worker Messenger.
castor supervisor:worker-restart¶
Recycle le worker Messenger supervisé dans le conteneur php (transports plugin_web et async). Restreinte à l'intérieur du conteneur php. Ne touche jamais à FrankenPHP — aucun signal, aucun pkill.
Deux modes :
- Gracieux (défaut) —
bin/console messenger:stop-workerspose un drapeau daté dans le poolcache.messenger.restart_workers_signal, adossé àcache.app= Redis (config/packages/cache.yaml), donc partagé entre le process CLI et le worker. Celui-ci termine son message en cours, sort en0, et la boucle le relance aprèsCLEAN_DELAY(1 s). Le succès est prouvé par le changement du PID dansvar/run/supervisor/messenger.child.pid— pas par le code de retour demessenger:stop-workers, qui réussit même si personne n'écoute. Patience : 30 s. --hard—infra/supervisor/supervisor.sh restart messenger: la boucle reçoitSIGTERM, escalade enSIGKILLaprès le délai de grâce, puis est relancée.
Si le PID n'a pas changé au bout de 30 s (Redis injoignable, handler bloqué), la cible affiche un warning puis escalade automatiquement vers --hard plutôt que de rendre un succès mensonger.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--hard |
flag | false |
Saute le chemin gracieux : arrête la boucle et le process, puis relance. |
Pourquoi un drapeau Redis plutôt qu'un SIGTERM
SIGTERM est le signal natif de messenger:consume (stop_worker_on_signals vaut [SIGTERM, SIGINT]), mais l'arrêt « après le message en cours » qu'il déclenche exige ext-pcntl, absente de l'image (seul posix y est présent). Un SIGTERM tue donc le worker immédiatement, au milieu de son message. Ce n'est pas une perte : le message non acké est redélivré par RabbitMQ, la garantie at-least-once est préservée. C'est néanmoins la raison d'être du chemin gracieux, qui n'utilise aucun signal.
Les redémarrages rapprochés sont sûrs
Contrairement à frankenphp-restart, cette cible n'a aucune garde de délai : le lock du transport bolt de Mercure est tenu par le module Mercure de Caddy, jamais par un process PHP CLI. Trois worker-restart d'affilée n'ont aucun effet sur l'application servie.
Image de développement¶
Le namespace image: pilote l'image kirexo-dev : détection du drift des outils figés dans le Dockerfile, application des bumps, et rafraîchissement du conteneur local. Son inventaire (outillage embarqué, versions, autocomplétion) est dans Référence de l'image de développement ; la recette est dans Garder mon image de dev à jour.
Les trois cibles sont hôte-only. Deux raisons cumulées : elles écrivent dans le Dockerfile (ou pilotent Docker), et les API qu'elles interrogent — hub.docker.com, les CDN d'assets de release — ne sont pas dans l'allowlist du proxy sortant.
castor image:check-tools¶
Alias lisible de castor image:upgrade-tools --check — vérifie si une nouvelle version d'un outil figé dans le Dockerfile (Castor, glab, Claude Code, Node) ou un tag plus récent de l'image de base FrankenPHP est disponible, sans rien modifier. Exit 2 si drift (ARG outil ou image de base), exit 0 sinon. Découvrable directement par castor list (l'option --check de upgrade-tools ne l'est pas), ce qui en fait une cible utilisable telle quelle en CI pour notifier qu'un bump est dispo.
Équivalence stricte
castor image:check-tools appelle simplement image_upgrade_tools(apply: false, check: true). Aucune différence de comportement avec castor image:upgrade-tools --check — c'est uniquement une question de découvrabilité.
Drift image de base FrankenPHP — bump manuel
Le tag de l'image de base est porté par une instruction FROM dunglas/frankenphp:<tag>, pas par un ARG. upgrade-tools ne sait manipuler que les ARG ; un tag plus récent est donc signalé en warning (non bloquant en --apply, compté dans l'exit 2 de --check) et le développeur édite la ligne FROM à la main après lecture du changelog upstream. Surveiller cette image couvre aussi indirectement les paquets système et install-php-extensions livrés via la base — un bump de la base entraîne implicitement leur mise à jour. La sélection du tag candidat est isolée dans ToolsUpgrader::selectFrankenphpCandidate() (castor/src/Image/ToolsUpgrader.php, testable unitairement) : tuples (franken-major, php-major, php-minor) strictement supérieurs au courant, à l'exclusion des « régressions PHP » (un bump franken-major qui dégraderait la majeure PHP).
castor image:upgrade-tools¶
Vérifie les dernières versions disponibles des outils CLI figés dans le Dockerfile (Castor, glab, Claude Code, Node) et met à jour les ARG correspondants — version et SHA-256 associé pour les outils distribués en binaire vérifié (CASTOR_SHA256, GLAB_SHA256). Node (via apk) et Claude Code (via npm) n'ont pas de SHA-256 managé. Affiche un tableau diff ARG | Actuel | Dernier | Δ (↑ si une mise à jour est disponible, = si à jour) puis applique en place via une regex sur Dockerfile — commentaires et structure sont préservés. Met aussi à jour les versions affichées dans docs/reference/image-dev.md, dont le chemin est codé en dur dans la cible.
Surveille en complément un drift sur l'image de base FrankenPHP du Dockerfile (instruction FROM dunglas/frankenphp:<tag>) — signalé en warning, jamais appliqué automatiquement (le bump cible une instruction FROM, hors mécanisme ARG géré par ToolsUpgrader). Le développeur lit le changelog upstream puis édite la ligne à la main. Couvre indirectement les paquets apk et install-php-extensions livrés via la base.
Sources interrogées :
| Outil | API |
|---|---|
| Castor | https://api.github.com/repos/jolicode/castor/releases/latest (version) + https://github.com/jolicode/castor/releases/download/${tag}/castor.linux-amd64.phar (binaire pour calculer le SHA-256). |
| glab | https://gitlab.com/api/v4/projects/gitlab-org%2Fcli/releases?per_page=1 (version) + tarball GitLab (SHA-256). |
| Claude Code | https://registry.npmjs.org/@anthropic-ai/claude-code/latest (SHA non managé — npm valide nativement dist.integrity SRI). |
| Node | Version du paquet nodejs lue dans l'APKINDEX de la branche Alpine ciblée par NODE_ALPINE_BRANCH : https://dl-cdn.alpinelinux.org/alpine/${NODE_ALPINE_BRANCH}/{main,community}/x86_64/APKINDEX.tar.gz (cf. latest_node_alpine_version() dans castor/image.php). Pas de SHA-256 — l'intégrité vient de l'index apk signé. On suit le rythme de packaging d'Alpine, plus les releases Node upstream. |
| Image base FrankenPHP | https://hub.docker.com/v2/repositories/dunglas/frankenphp/tags/?page_size=100&name=php8. (Docker Hub API publique). Filtré côté serveur sur le pattern php8. pour éviter les 13k+ tags. Sélection du candidat déléguée à ToolsUpgrader::selectFrankenphpCandidate() (logique pure, testable). |
La cible est restreinte à l'hôte : elle réécrit les ARG du Dockerfile et interroge deux hôtes que l'allowlist du proxy sortant ne couvre pas — hub.docker.com pour le tag de l'image de base, et dl-cdn.alpinelinux.org pour l'APKINDEX qui donne la version de Node. Lancée depuis l'intérieur, elle exit avec un message explicite (assert_outside_container('image:upgrade-tools')). Lancée depuis l'hôte, elle utilise le réseau de la machine — sans contrainte d'allowlist.
Le téléchargement des binaires de Castor et glab, lui, ne motive plus cette restriction : GitHub redirige ses assets de release vers release-assets.githubusercontent.com, désormais dans la baseline (il est nécessaire au binaire Tailwind d'un worktree neuf), et les assets GitLab sont servis depuis gitlab.com. C'est le seul hôte d'assets GitHub ouvert : les autres qu'il a pu servir selon les périodes ne le sont pas.
Le paquet Alpine chromium n'est pas géré
CHROMIUM_VERSION ne fait pas partie des ARG managés, et le dépôt community/ d'Alpine ne conserve qu'une seule version par branche : le pin devient introuvable au premier bump amont, ce qui casse la construction de l'image dev. Le symptôme est un échec apk sur la version épinglée ; le remède est d'y écrire la version courante à la main.
La liste exacte des ARG gérés est définie par ToolsUpgrader::TOOLS dans castor/src/Image/ToolsUpgrader.php (versions : CASTOR_VERSION, GLAB_VERSION, CLAUDE_CODE_VERSION, NODE_VERSION) et ToolsUpgrader::SHA_TOOLS (SHA associés : CASTOR_SHA256, GLAB_SHA256). Le SHA est recalculé uniquement si la version change — un même tag republie au même hash chez ces fournisseurs. Node (via apk) et Claude Code (via npm) ne figurent pas dans SHA_TOOLS : leur intégrité est vérifiée respectivement par l'index apk signé et par le dist.integrity SRI du registre npm.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--check |
flag | false |
Mode CI : exit 2 si au moins une mise à jour est disponible (ARG outil ou drift image base FrankenPHP), exit 0 sinon. N'écrit rien dans le Dockerfile et ne demande pas de confirmation. |
--apply |
flag | false |
Skippe la confirmation et applique directement les mises à jour. Obligatoire hors d'un terminal, où la cible sort en 1 plutôt que d'attendre — cf. Les confirmations hors terminal. |
Sans option, la cible est interactive : elle affiche le diff et demande une confirmation avant d'écrire le Dockerfile. Hors d'un terminal — job CI, hook, session d'agent —, elle sort en 1 en donnant castor image:upgrade-tools --apply : elle n'attend pas une réponse que personne ne peut donner.
# Diff + confirmation interactive
castor image:upgrade-tools
# CI : exit 2 si drift détecté (utilisable pour générer une notification)
castor image:upgrade-tools --check
# Application non interactive (script, automatisation)
castor image:upgrade-tools --apply
Pattern d'usage typique¶
castor image:check-tools # détecter le drift (exit 2 si maj dispo)
castor image:upgrade-tools --apply # appliquer les bumps dans le Dockerfile
castor docker:build # rebuilder l'image avec les nouvelles versions
git commit Dockerfile # versionner les nouveaux ARG
Versions figées par design
Les versions de Castor, glab, Claude Code et Node (révision Alpine -rN comprise pour Node) sont volontairement figées dans le Dockerfile pour garantir un environnement reproductible. La cible image:upgrade-tools est l'outil officiel pour faire évoluer ces versions sans aller chercher manuellement le numéro courant sur GitHub, GitLab, npm ou l'index Alpine — et sans risquer un mismatch version/SHA-256 pour les binaires vérifiés. Voir Référence de l'image de développement pour la liste des ARG concernés et les versions courantes.
castor image:refresh¶
Rafraîchit l'image de développement du poste et recrée le service php dessus. Hôte uniquement : la cible pilote Docker (pull, stop, rmi, up --build), gestes qui n'ont aucun sens depuis l'intérieur du conteneur qu'ils visent.
Aucun argument. La cible va au bout toute seule : aucun geste manuel dans l'IDE n'est requis.
| Étape | Effet |
|---|---|
0/4 |
Le préalable commun — remonte le projet mutualisé kirexo-shared, qui crée le réseau externe kirexo-egress. Sans lui, le conteneur revient sans aucune sortie réseau, en panne silencieuse. |
1/4 |
docker pull de la base registry.gitlab.com/shaurifr/kirexo/kirexo-dev:php8.5-alpine — l'artefact republié par la CI. |
2/4 |
docker compose -p <projet> stop php. Le nom de projet vient de compose_project_name(), jamais d'un littéral : -p a précédence sur COMPOSE_PROJECT_NAME, et un nom en dur ferait viser la stack du dépôt principal depuis n'importe quel worktree. |
3/4 |
Nettoyage opportuniste d'une image surcouche jb-… héritée de l'ancien mode d'ouverture du projet dans le conteneur, où l'IDE construisait sa propre image. Résolue par docker inspect puis DevImage::resolveImageToRemove() (castor/src/Image/DevImage.php). docker rmi -f, en tolérant l'échec. Sur un poste qui n'a jamais connu ce mode, l'étape ne trouve rien et l'annonce. |
4/4 |
docker compose -p <projet> [-f …] up -d --build --wait php — l'overlay local (dockerfile_inline de compose.override.yaml) est reconstruit par-dessus la base fraîchement tirée, et le conteneur recréé. En présence d'un .env.worktree, la cible empile les fichiers Compose du worktree et publie ses variables dans l'environnement du process (cf. l'encadré compose.worktree.yaml doit être empilé explicitement). |
Plus de « Rebuild and Restart Container »
PhpStorm ouvre le code nativement et n'utilise le conteneur que comme interpréteur distant : il ne construit plus aucune image. L'étape 3/4 ne subsiste donc que pour désencombrer un poste venant de l'ancien mode d'ouverture du projet dans le conteneur — une surcouche jb-<hash>-uid pèse plusieurs gigaoctets et masquerait la base fraîchement tirée. L'IDE se reconnecte seul au conteneur au prochain run.
La procédure complète, avec la vérification, est dans Garder mon image de dev à jour.
Confinement¶
castor confinement:check¶
Vérifie les invariants de confinement C1…C10 (plus le volet hôte C2h) par leur effet : chaque ligne du contrat est confrontée à une observation (requête HTTP hors whitelist, tentative d'écriture, lecture de /proc/self/mountinfo, id -u, …), jamais à la présence d'un fichier, d'un script ou d'un process. Le contrat est défini dans .claude/skills/_shared/confinement.md ; la logique de décision vit dans infra/confinement/check.lib.sh et les sondes dans infra/confinement/check.sh.
La cible (castor/confinement.php) n'est qu'un point d'entrée : elle exécute le script Bash dans le conteneur php (docker compose exec -T php depuis l'hôte, appel direct depuis l'intérieur) et propage son code de sortie tel quel. Le script reste appelable directement, sans Castor ni PHP — c'est ce que fait le hook session-dashboard.sh (cf. Hooks Claude Code).
| Option | Type | Défaut | Effet |
|---|---|---|---|
--profile |
string | container |
Sous-ensemble d'invariants exécutés. Valeurs acceptées : container, ci, host. Toute autre valeur sort en 2. Le profil host porte la seule sonde C2h et ne délègue pas au conteneur : demandé depuis l'intérieur, il sort en 2 avec la commande à rejouer depuis un terminal hôte. |
--format |
string | text |
text = tableau aligné + verdict lisible. json = une ligne {"verdict":…,"ko":[…],"pending":[…],"warn":[…],"summary":"…"}, destinée au gate SessionStart et aux scripts. |
castor confinement:check
castor confinement:check --profile=ci
castor confinement:check --profile=host # terminal hôte uniquement
castor confinement:check --format=json
Codes de sortie¶
| Code | Signification |
|---|---|
0 |
Aucun invariant bloquant en échec (verdict PASS). Les lignes PENDING, WARN, N/A et SKIP ne changent rien au code de sortie. |
1 |
Au moins un invariant bloquant en échec (verdict FAIL). Toutes les sondes du profil ont été exécutées malgré tout — le parcours ne s'arrête pas au premier échec, pour que le diagnostic soit complet en une passe. |
2 |
Usage invalide : profil ou format inconnu, profil container demandé hors du conteneur, ou profil host demandé depuis l'intérieur du conteneur. |
Ce que couvre chaque profil¶
| Profil | Invariants exécutés | Invariants ignorés |
|---|---|---|
container (défaut) |
C1 à C10 : montages hôte, socket Docker, sortie réseau, whitelists du proxy sortant, fichiers de l'espace Claude, sudo, non-root, worktrees voisins, compose.yaml / compose.prod.yaml, cloisonnement inter-worktrees. |
C2h, hôte-only : rendu · SKIP avec sa raison. |
ci |
C1 (montages hôte), C7 (non-root) et C9 (compose.yaml / compose.prod.yaml) — bloquants. C2 (socket Docker) est exécuté, mais son constat est rendu ⚠ WARN avec sa raison (cf. C2 en profil ci). |
Sortie réseau (C3), whitelists (C4), espace Claude (C5), sudo (C6), worktrees (C8), cloisonnement (C10) — rendus · SKIP avec leur raison affichée (réseau ouvert par conception dans un job CI, aucun montage hôte de whitelist ni d'espace Claude, aucun sudoers dans l'image, pas de worktree pair, aucun réseau partagé). C2h est · SKIP de la même façon. |
host |
C2h seul — volet hôte de C2, de sévérité blocking. |
Tout le reste : le contrat C1…C10 décrit le conteneur de l'agent, le mesurer depuis le poste de travail rendrait un rouge sans signification. |
La répartition n'est écrite nulle part dans les cibles : elle vient de la colonne « profils » du contrat rendu par confinement_contract() (infra/confinement/check.lib.sh), la même table qui porte les sévérités.
C2h — le volet hôte, et pourquoi il a son propre profil¶
C2h demande : dans le périmètre Kirexo, quel autre conteneur monte le socket Docker, et le seul qui a une raison de le faire — autoheal — est-il épinglé par digest et isolé sur son réseau ? Sa sonde repose sur docker ps et docker inspect, donc sur le socket Docker que C2 interdit précisément dans le conteneur de l'agent : elle ne peut vivre que du côté hôte.
D'où le profil dédié, et trois conséquences visibles dans le rapport :
- en
containeret enci, la ligne rend· SKIPavec sa raison (hôte-only : exigerait le socket Docker que C2 interdit ici) — elle reste affichée, une ligne qui disparaît d'un rapport n'est plus jamais réclamée ; - un
SKIPne fait jamais virer unblockingau rouge : le verdict du profilcontainerest inchangé ; dockerabsent du poste rend– N/A, et la stack mutualisée éteinte aussi (il n'y a alors rien à mesurer).
Le filtre name=^kirexo fait partie de la sonde : sans lui, un Portainer ou un Traefik personnel du poste ferait virer C2h au rouge pour une raison étrangère à ce que l'invariant mesure — et la sonde finirait « corrigée » en étant désarmée.
C2 en profil ci — le socket du runner¶
L'exécuteur docker du runner GitLab monte /var/run/docker.sock dans le conteneur de build : c'est ainsi que les jobs docker:build-* atteignent le démon. Ce socket appartient à l'infrastructure du runner, pas au dépôt — et le conteneur de l'agent, celui que C2 décrit, n'existe pas dans un job CI. Son exposition ne dit donc rien du confinement de l'agent.
La sonde est exécutée quand même, et son constat est rendu ⚠ WARN avec le détail complet — par exemple socket Docker présent : /var/run/docker.sock — monté par l'exécuteur du runner GitLab, hors du périmètre de l'agent. Visible dans le rapport, sans compter dans le verdict.
Deux points qui font partie de la décision, et non d'un aménagement de circonstance :
- l'exposition n'est pas masquée en
· SKIP— unSKIPmuet est exactement le mode de panne que ce contrat élimine ; - la sévérité de
C2au contrat resteblocking: en profilcontainer, un socket joignable est un✗ KOdur, qui fait sortir la commande en1et arme le gateSessionStart.
Le raisonnement complet est dans le contrat lui-même (.claude/skills/_shared/confinement.md, section « C2 en profil ci — le socket du runner ») ; l'implémentation de la sonde vit dans infra/confinement/check.sh.
C3 — un proxy injoignable rend ✗ KO¶
C3 (« Sortie réseau fermée par défaut ») agrège trois volets, le pire l'emportant : une règle refuse-t-elle un domaine hors allowlist, reste-t-il une route directe vers l'extérieur, et — troisième volet — le proxy sortant répond-il encore.
Ce troisième volet est décidé par confinement_classify_proxy (infra/confinement/check.lib.sh), à partir de deux mesures : le code de sortie de la sonde vers CONFINEMENT_ALLOWED_PROBE et celui de la sonde vers CONFINEMENT_PROXY_PROBE.
| Domaine autorisé | Proxy | Volet |
|---|---|---|
| joignable | non déterminant | ✓ OK |
| injoignable | répond (exit 0, quel que soit le code HTTP) |
⚠ WARN — l'allowlist ou le domaine distant sont en cause |
| injoignable | ne répond pas (exit 6, 7, 28, …) |
✗ KO — il n'y a plus aucune sortie réseau |
Seul le code de sortie de curl est lu, jamais le statut HTTP : Squid est CONNECT-only, une requête HTTP directe sur son port ne peut produire qu'une erreur HTTP (400 sur la requête que la sonde envoie), et cette erreur est précisément la preuve qu'il répond.
Les mesures brutes des quatre sondes partent dans le détail de la ligne. Quand le volet vire au rouge, le détail porte en plus le remède, hôte-only :
✗ KO … · proxy http://egress-proxy:3128 → exit 6 / http 000 · PROXY INJOIGNABLE
(http://egress-proxy:3128 → exit 6) : plus aucune sortie réseau — si l'hôte vient de
démarrer, laisse ~10 s au proxy (start_period) ; sinon, depuis un terminal HÔTE,
`castor docker:up`
C3 étant de sévérité blocking, ce ✗ KO fait sortir la commande en 1 et arme le gate SessionStart : aucune session Claude Code ne travaille tant que la sortie réseau n'est pas revenue. Le raisonnement est dans le contrat (.claude/skills/_shared/confinement.md, section « C3 — "la politique tient" ne dit rien de "la sortie existe" ») ; les gestes de réparation sont dans Diagnostiquer un blocage réseau sortant.
C10 — quels voisins sont sondés¶
C10 (« Cloisonnement inter-worktrees ») sonde les worktrees pairs, jamais le worktree courant. La liste des cibles est produite par la fonction pure confinement_peer_aliases (infra/confinement/check.lib.sh), à partir de deux entrées seulement : la sortie de git worktree list --porcelain et la variable WT, identité du worktree courant (main quand elle est absente, c'est-à-dire dans le dépôt principal).
| Entrée du porcelain | Alias sondé |
|---|---|
la première — le dépôt principal, que git worktree list liste toujours en tête |
php-main |
| les suivantes | php-<dernier segment du chemin> |
celle dont le nom vaut WT |
aucun : c'est le conteneur courant, il est exclu |
L'alias suit donc l'identité du worktree — celle dont Compose dérive php-${WT:-main} (compose.override.yaml, compose.full.yaml) — et non le nom du dossier. Deux conséquences directes : le dépôt principal, dont le dossier ne s'appelle pas main, est bien couvert ; et le conteneur ne se sonde plus lui-même, ce que l'ancienne comparaison de chemins ne pouvait pas empêcher (le porcelain rend des chemins hôte, jamais comparables au /app que voit le conteneur).
Le nom du worktree principal vit en neuf exemplaires
Ce défaut main est recopié neuf fois, dans sept fichiers : infra/confinement/check.lib.sh (la référence, lue par confinement_peer_aliases), infra/confinement/check.sh, KIREXO_PROXY_MAIN_WT, les deux alias Compose de compose.override.yaml (php- et docs-), celui de compose.full.yaml, le repli de .claude/hooks/lib/session-dir.sh, et — sous la forme du nom d'hôte applicatif complet — les deux écritures de KIREXO_RESERVED_DOMAINS, dans .env et dans le repli :- de compose.override.yaml. S'ils divergent, la sonde interroge un alias qui n'existe pas : le dépôt principal cesse d'être sondé, sans qu'aucun test ne rougisse. Les deux dernières ont un mode de panne différent et plus grave — 404 sur toute l'application au lieu d'un 502. Les cas de tests/Bash/confinement/peer_aliases.bats comparent ces sources entre elles, en les extrayant de leurs fichiers plutôt qu'en recopiant la valeur. Inventaire complet, fichier par fichier : Les neuf copies du nom du dépôt principal.
Chaque cible retenue est résolue par getent hosts <alias>, puis interrogée par curl --head en https — avec --insecure, puisqu'on mesure une atteignabilité et non une identité — et par un repli en http si la première sonde ne rend rien. La mesure brute part dans le détail de la ligne, adresse comprise :
C10 Cloisonnement inter-worktrees ⚠ WARN php-main → resolve 0 (172.31.1.4) / http 403 ; php-ticket-220 → resolve 0 (172.31.1.9) / http 403
Sans aucun pair, la ligne rend – N/A (« aucun worktree pair »). Un voisin qui répond — quel que soit le code HTTP, 403 compris — est atteignable : la sonde rend ko, que la sévérité advisory déclasse en ⚠ WARN.
Un ⚠ WARN sur C10 est un résultat normal, et il est vrai
Tant que les conteneurs php partagent le réseau du proxy hôte, les pairs se répondent : C10 avertit en permanence, et à juste titre. Ce n'est pas un défaut de la sonde, et l'éteindre suppose de refermer le réseau, pas de réécrire la mesure. Le raisonnement est dans .claude/skills/_shared/confinement.md, section « Le ⚠ WARN de C10 est normal, et il est VRAI » ; le pourquoi de la sévérité est discuté dans Pourquoi C10 est advisory et non blocking.
Statuts affichés¶
| Glyphe | Signification |
|---|---|
✓ OK |
Invariant tenu, mesuré. |
✗ KO |
Invariant violé. Compte dans le verdict uniquement pour une ligne de sévérité blocking. |
⧗ PENDING (lot N) |
Invariant pas encore tenu ; le lot N doit le livrer. Non bloquant. Affiché quel que soit le résultat de la sonde, dont la valeur brute part dans le détail. Aucune ligne du contrat ne porte cette sévérité — c'est le seul endroit du projet où un numéro de lot est fonctionnel : il rend la dette imputable. |
⚠ WARN |
Garantie observable mais non exigible depuis le conteneur (sévérité advisory), ou sévérité inconnue. Non bloquant. |
– N/A |
Rien à mesurer (ex. aucun worktree pair déclaré). |
· SKIP |
Invariant hors du profil demandé, ou sonde impossible. La raison est toujours affichée. |
Variables d'environnement¶
Toutes optionnelles, destinées au smoke test de la commande elle-même (vérifier qu'elle sait virer au rouge) et non à l'usage courant.
| Variable | Défaut | Effet |
|---|---|---|
CONFINEMENT_DENIED_PROBE |
example.com |
Domaine attendu bloqué. Le pointer sur un domaine de l'allowlist (packagist.org) est le moyen de provoquer un KO réel sans toucher à l'allowlist elle-même. |
CONFINEMENT_ALLOWED_PROBE |
packagist.org |
Domaine attendu joignable. S'il ne l'est pas, la ligne passe en WARN (réseau ou whitelist HS) sans infirmer le confinement. |
CONFINEMENT_CURL_TIMEOUT |
4 |
Timeout, en secondes, de chaque sonde réseau. |
CONFINEMENT_PROXY_PROBE |
http://egress-proxy:3128 |
URL du proxy sortant sondée par le troisième volet de C3 (cf. C3 — un proxy injoignable rend ✗ KO). La sonde la vise sans repasser par le proxy (--noproxy '*') et ne lit que le code de sortie de curl, jamais le statut HTTP. La surcharger seule ne fait pas virer la ligne au rouge : le volet ne rend ✗ KO que si CONFINEMENT_ALLOWED_PROBE est aussi injoignable. |
CONFINEMENT_PEER_TIMEOUT |
1 |
Timeout, en secondes, de chaque sonde vers un worktree voisin — au plus deux sondes par cible (https, puis repli http). C'est ce réglage, et non le plafond, qui tient le budget du gate : cf. l'encadré ci-dessous. |
CONFINEMENT_PEER_MAX |
3 |
Nombre maximum de worktrees voisins sondés. Plafond volontaire : sur un poste à dix worktrees, le contrat dépasserait le fail-close du gate SessionStart (timeout 25, cf. Hooks Claude Code) quelle que soit la durée unitaire. Les cibles écartées sont annoncées dans le détail de la ligne (+N pair(s) non sondé(s)). La valeur 0 désactive le sondage et le nomme : · SKIP avec le nombre de pairs non mesurés. |
Budget de temps du gate, et pourquoi c'est le timeout qui a bougé
Le gate SessionStart coupe le contrôle à timeout 25 (.claude/hooks/session-dashboard.sh) et un dépassement vaut verdict=unavailable — donc fail-closed : plus aucune session Claude Code ne démarre. Deux postes dominent ce budget : C3, avec ses quatre sondes réseau (4 × CONFINEMENT_CURL_TIMEOUT = 16 s), et C10, avec CONFINEMENT_PEER_MAX × 2 × CONFINEMENT_PEER_TIMEOUT.
Le coût de C10 est maximal quand l'invariant est tenu : la règle DOCKER-USER est en -j DROP et le DNS du réseau partagé continue de résoudre, si bien que chaque pair injoignable consomme le timeout plein, deux fois (https puis http). Ce n'est pas un pire cas hypothétique, c'est le cas nominal d'un poste bien configuré. À CONFINEMENT_PEER_TIMEOUT=2, cela ferait 2 × 2 × 3 = 12 s pour C10, soit 28 s avec C3 : au-delà du fail-close. Autrement dit, le contrat pouvait s'auto-bloquer précisément là où le cloisonnement fonctionne. Aujourd'hui le ⚠ WARN masque ce coût — un voisin qui répond 403 le fait en millisecondes.
D'où le timeout à 1 s : C10 plafonne à 6 s, le contrat à ~22 s, avec 3 s de marge. Rogner le nombre de cibles aurait payé en couverture ce qu'on gagne en temps ; c'est donc la durée unitaire qui baisse, pas le plafond.
L'inégalité est verrouillée par un test (tests/Bash/confinement/probe_c10.bats, cas « le budget du pire cas reste sous le fail-close du gate SessionStart ») : il lit les quatre valeurs dans infra/confinement/check.sh et .claude/hooks/session-dashboard.sh au lieu de les recopier. Un lot qui remonterait un réglage le fait rougir avant que le gate ne devienne unavailable.
Chaque profil se mesure d'un seul côté
Le profil container se mesure dans le conteneur php : le script lancé directement depuis l'hôte sort en 2 avec un message qui renvoie vers cette cible Castor, qui délègue au conteneur. Le profil host fait l'inverse — il ne délègue jamais, puisque sa sonde a besoin du socket Docker. Le hook session-dashboard.sh, lui, détecte le contexte et n'arme jamais son gate sur une session ouverte côté hôte.
Volontairement hors de castor all
confinement:check n'est branchée ni dans castor all ni dans castor doctor. Un confinement rouge n'a aucun rapport avec la qualité du code produit : l'exigence est portée par le gate SessionStart et par le job CI quality:confinement. Décision explicite, cf. Modèle de menace et contrat de confinement.
Definition of Done¶
Trois cibles jouent les sondes qui prouvent la Definition of Done d'une étape. Les sondes elles-mêmes sont des scripts Bash versionnés dans infra/dod/ ; la façade Castor (castor/dod.php) résout le script depuis son propre fichier (__DIR__, pas le répertoire courant) et propage son code de sortie tel quel.
Hôte uniquement, et jamais en intégration continue
Ces sondes pilotent Docker, créent et détruisent des worktrees, et recréent des conteneurs de la stack mutualisée. Lancées depuis le conteneur, elles sortent en 1 en nommant le terminal hôte, comme les autres cibles refusées à l'intérieur. Aucune n'est branchée dans castor all, castor host:check ni dans un job GitLab : il n'y a ni Docker-in-Docker, ni worktrees en CI. Le pourquoi de ce choix est dans Une preuve non versionnée n'est pas une preuve.
Aucune des trois ne coche quoi que ce soit dans Étapes/étape<n>.md : elles rendent un verdict par case, à reporter à la main avec sa preuve.
castor dod:check¶
Joue les cases de la Definition of Done vérifiables depuis l'hôte : confinement, worktrees parallèles, proxy, TLS, mails, destruction sans résidu. Sonde : infra/dod/check.sh.
Cette cible crée et détruit des worktrees
Un run nominal crée deux worktrees de test (dod-a et dod-b par défaut), démarre leurs stacks, ajoute puis retire un domaine de infra/firewall/whitelist.local.txt, et détruit ce qu'il a créé. Il l'annonce et demande confirmation avant d'agir — hors terminal, ou sans --yes, il s'arrête sans rien modifier. --skip-lifecycle est le seul mode non destructeur.
La sonde ne touche jamais un worktree qu'elle n'a pas créé : si --wt-a désigne un worktree préexistant, elle l'utilise en lecture et saute la case de destruction.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--skip-lifecycle |
flag | false |
Ne crée ni ne détruit aucun worktree. Ne joue que ce qui est vérifiable sur la stack en place — cases 10, 11, 12, 21 et 22 de la DoD de l'étape 10. |
--keep |
flag | false |
Ne détruit pas les worktrees créés. La case 20 (destruction sans résidu) devient alors SKIP, et castor dod:clean fait le ménage ensuite. |
--prod-smoke |
flag | false |
Joue en plus la case 30 : build de l'image de production (~5 à 10 min). |
--wt-a |
string | dod-a |
Nom du worktree de test A. Un nom, jamais un chemin : une valeur contenant / ou .. est refusée en 2. |
--wt-b |
string | dod-b |
Nom du worktree de test B, même garde de forme. |
--from |
string | branche courante du dépôt principal | Branche de départ des worktrees de test. |
--probe-domain |
string | example.org |
Domaine hors allowlist utilisé par la case 8 (sortie réseau bloquée). |
--yes, -y |
flag | false |
Ne demande aucune confirmation. |
castor dod:check --skip-lifecycle # non destructeur : stack en place uniquement
castor dod:check # run complet, avec confirmation
castor dod:check --keep -y # garde dod-a / dod-b pour inspection
castor dod:check --from=240-infra-dod --prod-smoke
Une option à valeur n'est transmise à la sonde que si elle a été donnée : --wt-a= vide n'écrase pas le défaut du script.
Ce que la sortie contient¶
Chaque case rend un verdict sur une ligne [NN] <statut>, suivi de sa preuve indentée — une case sans preuve n'est pas une preuve.
| Statut | Signification |
|---|---|
OK |
La case est vérifiée, la preuve est la ligne qui suit. |
KO |
La case est en échec. Reprise dans le bloc « À corriger » du récapitulatif. |
SKIP |
Non jouée dans ce run, avec sa raison (--skip-lifecycle, --keep, --prod-smoke non demandé…). |
MANUEL |
Hors de portée d'un script — deux IDE ou deux sessions Claude ouvertes en même temps (cases 16, 17 et le volet IDE de la case 22). La manipulation exacte est affichée, et la part automatisable jouée quand elle existe. |
La cible sort en 0 quand aucune case n'est KO ; SKIP et MANUEL ne changent pas le code de sortie. La sortie complète est aussi journalisée sous var/dod/check-<horodatage>.log — sous var/, donc gitignoré : ce journal porte des chemins de $HOME, des noms de conteneurs et l'inventaire des worktrees.
Deux verdicts qui ne se devinent pas¶
- La case 30 rend un
KOexplicite.infra/dod/prod-smoke.sha été perdu avecvar/claude: la sonde le dit dans ces termes (« a été PERDU avecvar/claude— la case 30 n'est plus rejouable ») et affiche le chemin attendu, plutôt que de rendre un « script introuvable » qu'on prendrait pour un défaut d'installation. - Une branche de départ trop ancienne désarme le cycle de vie. La sonde vérifie, avant toute création, que
--fromportecompose.worktree.yaml. Si ce n'est pas le cas — c'est encore le cas demaintant que l'étape n'est pas mergée —, elle bascule d'elle-même en--skip-lifecycleet le dit : sans cette garde pré-vol,wt:uprefuserait les worktrees après les avoir créés, laissant deux dossiers orphelins et plusieurs cases rouges sans rapport avec ce qu'elles testent.
castor dod:tls¶
Prouve que chaque URL de dev répond en HTTPS sans avertissement de certificat, sur deux worktrees servis en parallèle. Sonde : infra/dod/tls.sh. Elle ne modifie rien — ni configuration, ni certificat, ni worktree.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
| (tous les tokens) | list | [] |
Noms de worktrees à sonder, transmis tels quels (#[AsRawTokens]). Dédupliqués. Sans argument, la sonde prend le worktree par défaut du proxy. |
Ce que la sonde mesure, pour chaque URL rendue par wt_urls() (infra/worktree/wt.lib.sh) :
- le SAN servi — un
DNS:*.localhostsignale un repli sur le joker, donc un avertissement à venir ; unDNS:<nom exact>prouve que Caddy a émis sa feuille ; - le
ssl_verify_resultdecurl, sans jamais-k: l'option masquerait exactement ce qui est mesuré ; - le magasin de certificats de Caddy, qui dit ce qui a été émis plutôt que ce qui est servi ;
- l'absence de nom d'un seul label dans les configurations générées, y compris le retrait de
mailpit.localhost; - le marqueur de worktree par défaut et les alias réseau du dépôt principal — les deux survivent à un renommage sans rien casser de visible et rendent
502sous un TLS parfait.
Un seul worktree ne ferme pas la case
La case 15 de la DoD porte sur six URLs, c'est-à-dire deux worktrees servis en parallèle. Appelée avec un seul nom, la cible le dit et rend la commande à rejouer avec un second. Le dernier contrôle n'appartient qu'à un humain : ouvrir l'URL dans un navigateur, aucun avertissement attendu.
Sortie 0 si aucun KO. La sonde refuse par ailleurs de mesurer depuis un checkout qui ne porte pas le renommage app.<wt>.localhost (garde_checkout_porte_le_lot(), infra/dod/lib.sh) : lancée depuis un checkout antérieur, elle rendrait une volée de rouges sur un poste parfaitement migré.
castor dod:clean¶
Détruit les worktrees de test laissés par dod:check --keep ou par un run interrompu. Sonde : infra/dod/cleanup.sh. Idempotente : un worktree déjà propre rend · <nom> : rien à nettoyer.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
| (tous les tokens) | list | dod-a dod-b |
Noms de worktrees à nettoyer, transmis tels quels (#[AsRawTokens]). |
Garde de portée : dod-* uniquement
Cette cible enchaîne wt:destroy --yes --force, rm -rf, docker compose down -v et git branch -D sans demander. Elle refuse donc tout nom qui n'est pas de la forme dod-<…>, et tout nom contenant / ou .. — dod-a/../.. matcherait le préfixe et désignerait le répertoire parent du dépôt. Pour un autre worktree, c'est la cible qui l'annonce : castor wt:destroy.
L'ordre est wt:destroy d'abord, repli git ensuite — jamais l'inverse. wt:destroy sort en 1 sans rien supprimer quand docker compose down -v échoue ; c'est le bon comportement, mais il laisse le worktree git derrière lui quand wt:up a échoué avant d'écrire .env.worktree. La cible finit par un contrôle par l'effet : worktree, dossier, branche, conf proxy, conteneurs et volumes sont re-sondés un par un, et ce qui reste est listé.
Espace Claude et jeton GitLab¶
castor claude:space¶
Prépare ~/.kirexo/ côté hôte : l'espace utilisateur de Claude Code commun à l'hôte et à tous les worktrees (CLAUDE_CONFIG_DIR) et le jeton GitLab dédié au projet. La cible (castor/claude-space.php) n'est qu'un point d'entrée : toute la logique vit dans infra/claude-space/bootstrap.sh et sa lib pure infra/claude-space/bootstrap.lib.sh (testée en bats). Le rapport du script est relayé tel quel.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--full |
flag | false |
Copie ~/.claude.json intégralement dans l'espace dédié, sans en retirer les clés mcpServers ni projects. Par défaut, ces deux clés sont filtrées (serveurs MCP personnels et chemins de tous les autres dépôts de l'hôte). |
Ce que la cible garantit après son passage :
| Chemin | Mode | Contenu |
|---|---|---|
~/.kirexo/ |
700 |
Racine des artefacts Kirexo hors dépôt. |
~/.kirexo/claude/ |
700 |
Espace utilisateur de Claude Code, monté sur /home/app/.claude-kirexo dans le conteneur php. |
~/.kirexo/secrets/ |
700 |
Dossier des secrets du projet, monté en lecture seule sur /run/secrets dans le conteneur php. Ne contient que le jeton. |
~/.kirexo/secrets/gitlab-token |
600 |
Jeton GitLab dédié, au format dotenv. Créé en gabarit (aucune valeur) s'il n'existe pas. Chemin côté conteneur : /run/secrets/gitlab-token. |
~/.kirexo/env.sh |
600 |
À sourcer côté hôte (. ~/.kirexo/env.sh) : exporte CLAUDE_CONFIG_DIR et charge le jeton. Régénéré à chaque passage — seul artefact dont le script est propriétaire. |
~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/CLAUDE.md |
— | Créés s'ils sont absents ({} pour les deux premiers, vide pour le troisième). Ce sont les sources de binds de fichiers : sans eux, Docker crée des répertoires root:root à leur place et Claude Code part en erreur au démarrage. |
La sortie est une ligne OK ou ACTION par élément traité, suivie d'un résumé du nombre d'actions appliquées.
Hôte-only
La cible refuse de tourner depuis l'intérieur d'un conteneur : elle écrit dans le $HOME de l'hôte, qui n'y existe pas. Lancée dedans, elle sort en erreur avec le rappel castor claude:space à jouer depuis un terminal hôte. Le script sous-jacent applique la même garde (/.dockerenv ou KIREXO_INSIDE_CONTAINER).
Idempotente — aucune cible existante n'est écrasée
Deux exécutions consécutives produisent le même état et le même rapport. Le seeding (.claude.json, plugins/, agents/, commands/, skills/) n'a lieu que si la source existe et que la cible est absente. Seul env.sh est réécrit à chaque passage.
Migration du jeton depuis ~/.kirexo/gitlab-token¶
Le jeton vivait auparavant en ~/.kirexo/gitlab-token, monté par un bind de fichier. Il vit désormais dans le dossier ~/.kirexo/secrets, monté en entier — cf. Ce qui se propage à chaud, et ce qui ne se propage pas. Le chemin côté conteneur, /run/secrets/gitlab-token, est inchangé.
La cible traite l'ancien emplacement au passage, avant de créer le moindre gabarit :
| État côté hôte | Comportement | Rapport |
|---|---|---|
Seul ~/.kirexo/gitlab-token existe, fichier régulier |
Déplacé (mv, mode 600 conservé) vers ~/.kirexo/secrets/gitlab-token |
ACTION — migration signalée |
| Les deux fichiers existent | Aucun n'est touché : impossible de deviner lequel fait foi, et écraser un secret est irréversible | ACTION — invite à garder le bon et supprimer l'autre |
~/.kirexo/gitlab-token existe mais n'est pas un fichier régulier (répertoire posé par Docker quand la source du bind manquait) |
Aucune migration tentée | ACTION — invite à le retirer côté hôte (sudo rmdir) |
| L'ancien emplacement n'existe pas | Rien à faire ; le gabarit est créé au nouvel emplacement s'il manque | — |
Aucune de ces situations n'écrase un jeton renseigné, et aucune ne recrée un gabarit par-dessus une valeur existante. La logique vit dans infra/claude-space/bootstrap.sh, l'ancien chemin dans cs_legacy_token_file() de infra/claude-space/bootstrap.lib.sh — fonction transitoire, destinée à disparaître quand plus aucun poste ne peut être dans cet état.
Codes de sortie¶
| Code | Signification |
|---|---|
0 |
État conforme — y compris si le jeton GitLab est encore un gabarit non renseigné. Un démarrage de stack ne doit jamais être bloqué sur ce motif ; le rapport signale l'état en ACTION et renvoie vers Créer et faire tourner le jeton GitLab de Kirexo. |
1 |
Contexte invalide (exécution dans un conteneur), option inconnue, ou erreur d'écriture. |
Appel automatique au démarrage de la stack¶
L'appel manuel n'est pas le chemin nominal : le helper claude_space_ensure() (castor/claude-space.php) joue le bootstrap en mode discret en première étape du préalable commun, donc avant tout docker compose up de docker:up, docs:build, image:refresh et wt:up. Sans cette précaution, un poste neuf se retrouve avec des répertoires root:root créés par Docker à la place des binds de fichiers manquants : CLAUDE_CONFIG_DIR pointe un dossier vide, l'entrée env_file: ${HOME}/.kirexo/secrets/gitlab-token désigne un répertoire, et la réparation exige sudo.
Le helper est un no-op silencieux dans le conteneur, et il est appelé sans tolérance à l'échec : un bootstrap qui échoue interrompt le up, plutôt que de laisser Docker produire l'état à réparer à la main.
L'appel manuel garde donc deux usages : préparer ~/.kirexo sans rien démarrer (typiquement pour renseigner le gabarit du jeton avant le premier castor docker:up), et couvrir tout démarrage qui ne traverse aucune cible Castor — un docker compose up joué à la main, par exemple.
Un seul site d'appel
Le helper n'est appelé qu'une fois, depuis le préalable commun — pas depuis chaque cible. C'est précisément la duplication qui avait créé un trou : câblé dans docker:up seul, il était absent de tout poste démarrant autrement.
Documentation¶
castor docs:build¶
Construit le site de documentation statique dans ./site, avec --strict (toute erreur mkdocs devient fatale). Utilise l'image custom définie dans mkdocs/Dockerfile — qui ajoute deux plugins par-dessus squidfunk/mkdocs-material :
git-revision-date-localized— affiche la date de dernière modification de chaque page (lue dans l'historique git).social— génère automatiquement les images Open Graph de partage pour chaque page (mkdocs-material[imaging]+ Pillow + CairoSVG).
La cible enchaîne trois étapes : le préalable commun, docker compose build docs (idempotent — ne reconstruit que si mkdocs/Dockerfile change) puis docker compose run --rm docs build --strict.
Le préalable est nécessaire pour deux raisons distinctes : run crée les réseaux du projet (dont kirexo-egress et kirexo-proxy, tous deux déclarés external), et le plugin social télécharge ses polices au build — sans proxy sortant joignable, le --strict casse.
Depuis l'intérieur du conteneur php
Lancée depuis l'intérieur, la cible refuse de tourner (elle pilote Docker côté hôte) et le message d'erreur suggère curl -sIf http://docs-int:8000/ pour valider rapidement que le service mkdocs en live-reload répond, sans rebuild. Le strict mode (validation des liens et des snippets pymdownx.snippets) reste réservé à l'hôte.
docs-int et jamais le nom de service nu docs : celui-ci est attaché à trois réseaux et rendrait trois adresses, dont une injoignable — la sonde échouerait alors environ une fois sur trois (cf. Un service sur deux réseaux rend deux adresses). Depuis l'hôte, la documentation est servie sur https://docs.main.localhost (ou https://docs.<worktree>.localhost).
Site vitrine¶
Le site vitrine de Kirexo est un site statique, distinct de l'application et de cette documentation. Ses sources sont écrites à la main, sans moteur de gabarits, dans site/ à la racine du dépôt. Les parties variables y sont délimitées par des marqueurs kirexo:*, remplis au build.
Les cibles site:* sont déclarées dans castor/site.php, qui ne fait que l'I/O de console. Toute la logique vit dans les classes de castor/src/Site/ (namespace App\Castor\Site).
castor site:build¶
Construit le site vitrine dans var/site-build/, prêt à déployer. Dans l'ordre, la cible :
- copie
site/, saufsite/data/; - copie les assets du design system depuis le dépôt (cf. Arborescence de
var/site-build/) ; - remplace les marqueurs
kirexo:*de chaque page.html(version, date, mémoire, hébergeur, statuts) ; - valide
site/data/statuts.jsoncontre les plugins réellement déclarés dansconfig/bundles.php; - calcule l'empreinte sha256 du script anti-flash et écrit
_headerset.htaccess.
castor site:build # hébergeur : SITE_DEPLOY_PROVIDER, sinon deploybase
castor site:build --provider=ovh # hébergeur imposé
SITE_DEPLOY_PROVIDER=ovh castor site:build
| Option | Type | Défaut | Effet |
|---|---|---|---|
--provider |
string | '' |
Hébergeur cité dans le marqueur kirexo:hebergeur : deploybase ou ovh. Vide : valeur de la variable SITE_DEPLOY_PROVIDER si elle est non vide, sinon deploybase (SiteBuilder::DEFAULT_PROVIDER). Toute autre valeur fait échouer le build. |
La liste des fournisseurs admis est celle des clés de SiteBuilder::HOSTING_PROVIDERS (castor/src/Site/SiteBuilder.php), et le défaut celui de SiteBuilder::DEFAULT_PROVIDER. Ces deux constantes sont la seule définition de ces valeurs dans le dépôt. La résolution est faite par SiteDeployGuard::resolveProvider(), la même que pour castor site:deploy.
Où la lancer. Sur l'hôte, dans le conteneur php ou en CI, indifféremment : la cible est en PHP natif, sans Docker, sans réseau et sans dépendance de vendor/. Elle fonctionne donc aussi sur un checkout sans composer install, grâce au repli d'autoload limité à App\Castor\ décrit en tête de page. La racine du dépôt est déduite de l'emplacement de castor/site.php.
Sortie.
| Situation | Effet |
|---|---|
| Succès | Site construit dans var/site-build/ : N page(s), version X, hébergeur Y, CSP sha256-…., sortie 0. |
site/data/release.json absent |
Le build réussit avec la version dev, sans date, et l'annonce par une note : site/data/release.json absent : version « dev », sans date (le fichier est écrit par castor site:refresh au moment d'un tag). |
Échec attendu (SiteBuildException) |
Message d'erreur qui nomme la cause, le fichier (et la ligne quand elle existe) et le remède, sortie 1. Liste complète : Échecs et remèdes. |
| Toute autre exception | Remonte telle quelle : c'est un bug, pas un cas prévu. |
Rien n'est écrit tant que tout n'est pas validé. Préconditions, fournisseur, assets, données et rendu des pages sont vérifiés en mémoire avant que var/site-build/ ne soit vidé. Un build qui échoue sur une donnée laisse donc intact le build précédent. Le dossier de sortie est toujours <racine>/var/site-build : il n'est pas paramétrable, ce qui empêche tout effacement hors de ce dossier.
Les marqueurs kirexo:*¶
Un marqueur est une paire de commentaires HTML qui encadre une valeur. La forme est stricte, avec une espace de chaque côté :
<nom> suit le motif [a-z][a-z0-9-]*. Le contenu entre les deux commentaires est remplacé sans ajout de saut de ligne : un marqueur peut donc vivre au milieu d'un <p>. Les commentaires eux-mêmes sont conservés dans le HTML produit : le rendu est idempotent et la provenance de chaque valeur reste lisible dans la page servie.
| Marqueur | Valeur insérée | Source |
|---|---|---|
kirexo:version |
Version de release, échappée en HTML. dev si site/data/release.json est absent. |
site/data/release.json |
kirexo:date |
, publiée le <time datetime="2026-10-02">2 octobre 2026</time> (le premier du mois s'écrit 1er). Chaîne vide si release.json est absent. |
site/data/release.json |
kirexo:memoire |
Un serveur avec N Go de mémoire suffit., où N est la ligne **Total mémoire** (en Mio) du bloc kirexo:empreinte, divisée par 1024 et arrondie à l'entier supérieur, minimum 1 (428 Mio → 1 Go, 1025 Mio → 2 Go). |
install/README.md |
kirexo:hebergeur |
Fragment HTML des mentions de l'hébergeur : TwanIT (service deploybase, Pays-Bas) pour deploybase, OVH SAS pour ovh. |
SiteBuilder::HOSTING_PROVIDERS, selon --provider |
kirexo:statuts |
Une ligne <tr> par entrée, dans l'ordre du fichier (cf. ci-dessous). Chaîne vide si la liste est vide. |
site/data/statuts.json |
Le pied de page de site/index.html accole les deux paires de version et de date, sans espace entre elles :
<p>Version <!-- kirexo:version:debut -->dev<!-- kirexo:version:fin --><!-- kirexo:date:debut --><!-- kirexo:date:fin --></p>
Ce qui donne « Version 0.0.2, publiée le 2 octobre 2026 », ou « Version dev » sans release.json.
Règles de validation, appliquées à chaque page .html de site/ (récursivement, hors data/) :
- un même marqueur peut apparaître plusieurs fois dans une page ;
- un marqueur connu absent d'une page n'est pas une erreur : chaque page ne porte que ceux dont elle a besoin ;
- tout commentaire qui commence par
<!-- kirexo:est traité comme un marqueur. S'il ne respecte pas la forme exacte, il est mal formé ; - les marqueurs ne s'imbriquent pas ; une
finsansdebutcorrespondant, ou undebutjamais fermé, est orphelin ; - un nom absent du tableau ci-dessus est inconnu.
La ligne <tr> produite pour une entrée de statuts.json (castor/src/Site/StatutsRenderer.php) :
<tr><th scope="row">Publier ses articles sur son propre site web</th><td><span class="status status--disponible"><span class="dot" aria-hidden="true"></span>Disponible</span></td><td>Chaque auteur dispose d'un site public pour ses textes, sur l'adresse de son choix.</td></tr>
La classe status--<etat> porte la valeur brute du champ etat. La pastille .dot est décorative (aria-hidden="true") : le libellé textuel est toujours présent, l'information ne passe jamais par la seule couleur. Les libellés sont définis dans StatutsRenderer::LABELS.
Contrat de site/data/release.json¶
Fichier facultatif, objet JSON à deux clés :
| Clé | Forme attendue |
|---|---|
version |
Version sémantique stricte X.Y.Z, validée par App\Castor\Release\SemanticVersion (castor/src/Release/SemanticVersion.php) : sans préfixe v, sans zéro de tête. |
date |
Date AAAA-MM-JJ qui existe au calendrier (2026-13-01 et 2026-02-30 sont refusées). |
Absent, le build retombe sur la version dev sans date et l'annonce. Présent mais non conforme, le build échoue. Le message propose de régénérer le fichier avec castor site:refresh --name=<X.Y.Z> (cf. castor site:refresh), la cible qui l'écrit au moment d'une release. Le supprimer redonne la version dev.
Contrat de site/data/statuts.json¶
Source versionnée et tenue à la main du tableau « Où en est-on ». C'est une liste JSON d'objets, affichés dans l'ordre du fichier :
[
{
"fonction": "Publier ses articles sur son propre site web",
"etat": "disponible",
"detail": "Chaque auteur dispose d'un site public pour ses textes, sur l'adresse de son choix.",
"plugin": "Web"
}
]
| Champ | Obligatoire | Forme attendue |
|---|---|---|
fonction |
oui | Chaîne non vide (après suppression des espaces), en langage courant. |
etat |
oui | Une des quatre valeurs du tableau ci-dessous. |
detail |
oui | Chaîne non vide, en langage courant. |
plugin |
non | Chaîne non vide : le <Nom> du dossier src/Plugin/<Nom>/ d'un plugin livré, par exemple "Web". |
Aucun autre champ n'est admis.
etat |
Libellé affiché |
|---|---|
disponible |
Disponible |
en-cours |
En cours |
prevu |
Prévu |
pas-prevu |
Pas prévu |
Croisement avec les plugins livrés (castor/src/Site/StatutsValidator.php). Un plugin est livré quand un bundle déclaré dans config/bundles.php se résout, par le préfixe le plus long de autoload.psr-4 dans composer.json, vers un dossier src/Plugin/<Nom>/. L'environnement du bundle (all, dev…) est ignoré. Aujourd'hui, seul Web est livré (Kirexo\Plugin\Web\KirexoPluginWebBundle). Trois règles en découlent :
- chaque plugin livré a au moins une entrée
"plugin": "<Nom>"d'étatdisponible. Le site ne peut pas taire un plugin livré ; - une entrée ne cite en
pluginqu'un plugin livré. Le site ne peut pas annoncer comme disponible une extension qui n'existe pas : tant qu'elle n'est pas livrée, son entrée existe sans champplugin; - un même
pluginn'est cité que par une seule entrée.
Arborescence de var/site-build/¶
var/site-build/
├── index.html pages .html de site/, marqueurs remplacés
├── … autres fichiers de site/ (hors data/), copiés tels quels
├── assets/
│ ├── styles/
│ │ ├── kirexo-ds.css ← assets/styles/kirexo-ds.css
│ │ └── fonts.css ← assets/styles/fonts.css
│ ├── fonts/
│ │ └── *.woff2 ← assets/fonts/*.woff2
│ └── js/
│ └── theme.js ← assets/js/theme.js
├── favicon/ ← public/favicon/* (fichiers du premier niveau)
├── _headers en-têtes HTTP, format du CDN deploybase
└── .htaccess mêmes en-têtes, directives Apache (repli OVH)
La correspondance source → destination est la constante SiteBuilder::DESIGN_SYSTEM_ASSETS. Ces assets ne sont pas dupliqués dans git : ils sont copiés depuis le dépôt à chaque build. La copie conserve la relation styles/ ↔ ../fonts/ qu'exigent les url(../fonts/…) de fonts.css. Le favicon est copié à la racine du build, et pas sous assets/, parce que public/favicon/site.webmanifest référence ses icônes en chemins absolus /favicon/….
Les dossiers site/assets/ et site/favicon/ sont réservés à ces copies : leur présence dans les sources fait échouer le build.
var/site-build/ est couvert par la ligne /var/ de .gitignore et n'est jamais commité.
Les en-têtes HTTP : _headers et .htaccess¶
Les deux fichiers portent les mêmes en-têtes (castor/src/Site/HeadersWriter.php) :
| En-tête | Valeur | Portée |
|---|---|---|
Content-Security-Policy |
default-src 'self'; script-src 'self' 'sha256-…'; style-src 'self'; img-src 'self' data:; font-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none' |
toutes les réponses |
Referrer-Policy |
strict-origin-when-cross-origin |
toutes les réponses |
X-Content-Type-Options |
nosniff |
toutes les réponses |
Cache-Control |
public, max-age=31536000, immutable |
_headers : chemins /assets/fonts/*, /favicon/*, /images/* ; .htaccess : extensions woff2, png, jpg/jpeg, webp, avif, svg, ico |
Le .htaccess ajoute ErrorDocument 404 /404.html et s'ouvre sur le commentaire # Généré par castor site:build — ne pas éditer (DC9).. Les deux fichiers sont régénérés à chaque build : toute modification à la main est perdue.
L'empreinte sha256-… est calculée au build, jamais écrite à la main. C'est le condensat sha256, encodé en base64, du contenu exact (espaces et sauts de ligne compris) du seul <script> inline des pages : le script anti-flash, recopié de templates/base.html.twig. Il en découle trois contraintes sur les sources de site/ :
- chaque page
.htmlporte exactement un<script>inline (les<script src="…">ne comptent pas) ; - ce script est identique octet pour octet sur toutes les pages, indentation comprise, car la CSP ne porte qu'une empreinte ;
style-src 'self'interdit les attributsstyle="…", etscript-srcsans'unsafe-inline'interdit les gestionnaireson*="…".
Échecs et remèdes¶
Chaque échec sort en 1 avec le message cité, adapté au fichier, à la ligne et aux valeurs en cause.
Préconditions et fournisseur
| Message (extrait) | Cause | Remède |
|---|---|---|
site/ introuvable dans <racine> : lancer la cible depuis la racine du dépôt. |
Pas de dossier site/ à la racine déduite. |
Vérifier le checkout : site/ est versionné. |
site/assets/ est réservé aux assets du design system copiés au build : renommer ce dossier. (idem site/favicon/) |
Dossier réservé présent dans les sources. | Renommer le dossier et ses références. |
site/<chemin> : lien symbolique refusé — le build ne copie que des fichiers réels du dépôt. |
Lien symbolique sous site/. |
Le remplacer par un fichier réel. |
Fournisseur d'hébergement inconnu : « x » (attendus : deploybase, ovh). Corriger --provider ou la variable SITE_DEPLOY_PROVIDER. |
Valeur de --provider ou de SITE_DEPLOY_PROVIDER hors liste. |
Passer deploybase ou ovh. |
Asset du design system introuvable : <chemin>. Le site le copie depuis le dépôt (DC4) : restaurer le fichier, ou corriger SiteBuilder::DESIGN_SYSTEM_ASSETS. |
Un fichier source de l'arborescence ci-dessus manque (ou un motif ne trouve aucun fichier). | Restaurer le fichier, ou mettre à jour la constante s'il a été déplacé. |
site/data/release.json
Tous les messages ont la forme site/data/release.json invalide : <cause>. Le régénérer avec castor site:refresh --name=<X.Y.Z>. Remède commun : corriger le fichier selon le contrat, ou le supprimer.
| Cause affichée | Situation |
|---|---|
| message de l'analyseur JSON | JSON invalide. |
un objet {"version", "date"} est attendu |
Le fichier contient une liste ou une valeur scalaire. |
version « v1 » non conforme (attendu X.Y.Z) |
version absente ou non semver stricte. |
date « 2026-13-01 » invalide (attendu AAAA-MM-JJ) |
date absente, mal formée ou inexistante au calendrier. |
Mémoire (install/README.md)
| Message (extrait) | Remède |
|---|---|
install/README.md introuvable. |
Restaurer le fichier. |
install/README.md : bloc kirexo:empreinte introuvable (…). Le rétablir, ou rejouer castor docker:test-install (terminal hôte), qui le réécrit. |
Rejouer castor docker:test-install depuis l'hôte. |
install/README.md : ligne « **Total mémoire** » introuvable dans le bloc kirexo:empreinte. Rejouer castor docker:test-install (terminal hôte) pour régénérer le relevé. |
Idem. |
install/README.md : total mémoire « 0 Mio » invalide (attendu : un nombre de Mio strictement positif). |
Idem. |
site/data/statuts.json et plugins livrés
| Message (extrait) | Remède |
|---|---|
site/data/statuts.json introuvable : créer le fichier (liste d'entrées {fonction, etat, detail, plugin?}). |
Créer le fichier selon le contrat. |
site/data/statuts.json : JSON invalide (…). |
Corriger la syntaxe JSON. |
site/data/statuts.json : une liste d'entrées est attendue au premier niveau. |
Envelopper les entrées dans [ … ]. |
site/data/statuts.json, entrée 3 : un objet {fonction, etat, detail, plugin?} est attendu. |
Remplacer l'entrée par un objet. |
site/data/statuts.json, entrée 3 : champ inconnu « statut » (champs admis : fonction, etat, detail, plugin). |
Renommer ou retirer le champ. |
site/data/statuts.json, entrée 3 : champ « detail » manquant ou vide. |
Renseigner le champ (fonction, etat ou detail). |
site/data/statuts.json, entrée 3 : état « bientot » inconnu (attendus : disponible, en-cours, prevu, pas-prevu). |
Utiliser une des quatre valeurs. |
site/data/statuts.json, entrée 3 : champ « plugin » vide (…). |
Retirer le champ, ou y mettre le nom du dossier src/Plugin/<Nom>/. |
site/data/statuts.json : plugin « Web » cité par les entrées 1 et 5 — une seule entrée par plugin. |
Fusionner les deux entrées. |
site/data/statuts.json, entrée 4 : plugin « Telegram » inconnu — aucun bundle de config/bundles.php ne vit sous src/Plugin/Telegram/. Retirer le champ « plugin » tant que l'extension n'est pas livrée. |
Retirer le champ plugin de l'entrée. |
Le plugin livré « Web » (config/bundles.php) n'a pas d'entrée d'état « disponible » dans site/data/statuts.json. Ajouter : {"fonction": "…", "etat": "disponible", "detail": "…", "plugin": "Web"}. |
Ajouter l'entrée suggérée, ou passer l'entrée existante en disponible. |
config/bundles.php introuvable : lancer la cible depuis la racine du dépôt. (idem composer.json) |
Vérifier le checkout. |
config/bundles.php ne renvoie pas un tableau. |
Rétablir le return [ … ]; du fichier. |
composer.json : clé autoload.psr-4 absente ou invalide. |
Rétablir la section autoload.psr-4. |
Marqueurs (le chemin de page est relatif à site/)
| Message (extrait) | Remède |
|---|---|
index.html, ligne 42 : marqueur mal formé « <!-- kirexo:version --> » (forme attendue : <!-- kirexo:<nom>:debut --> … <!-- kirexo:<nom>:fin -->). |
Rétablir la forme exacte, espaces compris. |
index.html, ligne 48 : « kirexo:date:debut » ouvert avant la fin de « kirexo:version » (ligne 42) — les marqueurs ne s'imbriquent pas. |
Fermer la première paire avant d'ouvrir la suivante. |
index.html, ligne 50 : marqueur orphelin « kirexo:version:fin » sans début. |
Ajouter le debut manquant, ou retirer la fin. |
index.html, ligne 42 : marqueur orphelin « kirexo:version:debut » sans « <!-- kirexo:version:fin --> ». |
Ajouter la fin manquante. |
index.html, ligne 42 : marqueur inconnu « kirexo:foo » (connus : version, date, memoire, hebergeur, statuts). Corriger le nom dans site/index.html. |
Utiliser un nom connu. |
Script anti-flash et CSP
| Message (extrait) | Remède |
|---|---|
Aucune page HTML dans le build. |
Ajouter au moins une page .html dans site/. |
404.html : script anti-flash absent — chaque page porte dans son <head> le script inline de templates/base.html.twig:17-33. |
Recopier le script anti-flash dans le <head> de la page. |
index.html : 2 scripts inline — la CSP n'autorise que le script anti-flash ; déplacer le reste dans un fichier .js. |
Déplacer le script supplémentaire dans un fichier .js chargé par src. |
index.html et 404.html n'ont pas le même script anti-flash — la CSP ne porte qu'une empreinte ; recopier le même bloc à l'identique. |
Recopier le même bloc, octet pour octet, dans toutes les pages. |
Écriture (après validation, phase de copie)
| Message (extrait) | Remède |
|---|---|
Création impossible du dossier <chemin>. |
Vérifier les droits sur var/. |
Copie impossible : <source> → <cible>. |
Vérifier les droits de lecture de la source et d'écriture sur var/site-build/. |
Écriture impossible : <chemin>. |
Vérifier les droits d'écriture sur var/site-build/. |
castor site:check¶
Vérifie le site construit dans var/site-build/. La cible enchaîne quatre contrôles, toujours dans cet ordre :
| # | Contrôle | Outil | Ce qui échoue |
|---|---|---|---|
| 1 | HTML valide | html-validate, configuré par infra/site/htmlvalidate.json |
Toute erreur ou tout avertissement (--max-warnings 0) sur une page .html du build, recherche récursive. |
| 2 | Liens internes et ancres | LinkChecker (castor/src/Site/LinkChecker.php) |
Fichier introuvable, chemin qui sort du site, ancre absente de la page visée, schéma interdit (javascript:, file:…). |
| 3 | Étapes d'installation identiques | InstallCommandsConsistency (castor/src/Site/InstallCommandsConsistency.php) |
Titre d'étape ou ligne de commande qui diffère, manque ou est en trop entre site/installer.html, docs/tutorials/installer-kirexo-chez-soi.md et install/README.md ; nombre d'étapes ou de commandes différent de 4 et 5 ; fichier ou section introuvable ; lien « Aller plus loin » absent. Détail : Quatre étapes d'installation. |
| 4 | Accessibilité, en thème clair puis en thème sombre | @axe-core/cli, avec le Chromium et le chromedriver de l'image kirexo-dev |
Au moins une violation des règles WCAG 2.1 A et AA (tags axe wcag2a, wcag2aa, wcag21a, wcag21aa). Les résultats incomplete (à revoir à la main) ne comptent pas. |
Le contrôle n° 3 lit les sources du dépôt, pas var/site-build/ : il ne dépend pas du build et ne peut pas produire de code 2. Il passe avant l'audit axe pour que son résultat soit écrit même si axe s'interrompt.
La cible n'a pas d'option. Elle n'est pas incluse dans castor all.
Prérequis. Le build doit exister : la cible lit var/site-build/ et ne le construit pas. Si var/site-build/index.html est absent, elle sort en 2 avec var/site-build/ absent ou incomplet : lancer castor site:build d'abord.
Où la lancer. Chromium, chromedriver et Node n'existent que dans le conteneur php. Lancée depuis l'hôte, la cible se relance dans le conteneur par docker compose exec -T php castor site:check et sort avec le code du conteneur, tel quel.
Codes de sortie et rapport¶
| Code | Signification |
|---|---|
0 |
Conforme : les quatre contrôles passent, l'audit axe dans les deux thèmes. |
1 |
Au moins un contrôle est en échec. Les quatre contrôles sont quand même exécutés, pour que le rapport soit complet. |
2 |
Contrôle impossible : build absent, package.json illisible ou paquet absent de ses devDependencies, serveur local injoignable, thème non appliqué par Chromium, @axe-core/cli sorti avec un code autre que 0 ou 1, ou sortie axe illisible. La cible s'arrête à la première erreur de ce type. |
Le code est fiable aussi depuis l'hôte : la cible peut servir de garde dans un script ou un job CI.
Rapport conforme :
site:check — var/site-build (5 pages)
✓ HTML valide (html-validate)
✓ Liens internes et ancres : aucun lien cassé
✓ Étapes d'installation identiques : site/installer.html, docs/tutorials/installer-kirexo-chez-soi.md et install/README.md
✓ axe WCAG 2.1 A+AA, thème clair : 0 violation
✓ axe WCAG 2.1 A+AA, thème sombre : 0 violation
[OK] Site conforme : HTML valide, liens internes intacts, étapes d'installation identiques, zéro violation axe WCAG 2.1 A+AA en clair et en sombre.
En échec, chaque contrôle rouge est suivi de son détail, et la cible conclut par Site NON CONFORME — {n} contrôle(s) en échec. Détail axe : var/site-check/.
| Contrôle en échec | Détail affiché sous la ligne ✗ |
|---|---|
| HTML | La sortie complète de html-validate (formateur stylish). Le code de sortie de l'outil ne distingue pas un HTML invalide d'un outil en panne : les deux donnent un ✗. |
| Liens | Une ligne par problème : {page} → {valeur brute} : {motif}, par exemple index.html → #heberger : ancre #heberger introuvable dans index.html. |
| Étapes d'installation | Une ligne par problème, dans l'ordre décrit sous Quatre étapes d'installation. |
| axe | Une ligne par violation : {page} · {règle} ({impact}) · {aide} · {n} nœud(s) : {cibles}. Seules les trois premières cibles sont citées, suivies de … s'il y en a plus. |
Le JSON brut d'axe est écrit à chaque passe dans var/site-check/axe-light.json et var/site-check/axe-dark.json, un résultat par page. Ces fichiers ne sont pas versionnés (/var/ est dans .gitignore).
Quatre étapes d'installation¶
La procédure d'installation de l'auto-hébergeur existe en trois copies : le tutoriel mkdocs, qui fait foi, la page du site et le README livré dans le bundle. Le contrôle n° 3 (castor/src/Site/InstallCommandsConsistency.php) exige que leurs quatre étapes soient identiques. Le pourquoi de ces trois copies : Trois copies d'une même procédure.
Fichiers comparés, lus sous la racine du dépôt :
| Fichier | Constante | Ce qui est lu |
|---|---|---|
docs/tutorials/installer-kirexo-chez-soi.md |
InstallCommandsConsistency::TUTORIAL |
La section ## Installer en quatre étapes (référence). |
site/installer.html |
InstallCommandsConsistency::SITE_PAGE |
La page source, pas sa version construite. |
install/README.md |
SiteBuilder::INSTALL_README |
La section ## Installer en quatre étapes. |
Extraction dans les deux fichiers Markdown. La lecture se fait ligne à ligne, sans parseur Markdown :
- la section commence à la première ligne qui vaut exactement
## Installer en quatre étapes(espaces de fin ignorés) ; - elle s'arrête à la première ligne suivante qui commence par
##hors bloc de code, ou à la fin du document. Un intertitre###ne l'arrête pas, ni un##placé dans un bloc de code ; - un titre d'étape est une ligne hors bloc de la forme
### N. Titre. Le préfixeN.est retiré ; une ligne### Titresans numéro est ignorée ; - une commande est une ligne non vide d'un bloc de code clôturé (
```ou~~~, trois caractères ou plus, indentation et chaîne d'info admises). Un bloc non fermé court jusqu'à la fin de la section. Tous les blocs de la section comptent ; - le code en ligne (
`…`) est ignoré, comme tout ce qui précède ou suit la section : les commandes citées après les quatre étapes (vérification, dépannage…) ne sont pas contrôlées.
Extraction dans la page. La page est analysée par le parseur HTML natif de PHP (\Dom\HTMLDocument) :
- les titres sont le texte des
h3enfants directs deslideol.steps. La numérotation vient de la liste, d'où l'absence de préfixeN.dans la page ; - les commandes sont les lignes non vides de chaque
pre > code, dans l'ordre du document. Les entités HTML sont décodées ("donne"). Un<code>hors<pre>est ignoré.
Normalisation, appliquée à chaque titre et à chaque commande avant comparaison : espaces insécables convertis en espaces, suites de blancs réduites à une espace, blancs de début et de fin retirés. Rien d'autre n'est assoupli.
Comparaison. Le tutoriel est la référence. La page, puis le README, lui sont comparés rang par rang : d'abord les titres, ensuite les commandes. C'est une égalité stricte, jamais une recherche de sous-chaîne : docker compose up -d et docker compose up -d --wait sont deux commandes différentes. Deux commandes permutées produisent donc deux problèmes.
Verrous anti-vacuité. Chaque source doit contenir exactement EXPECTED_STEPS titres (4) et EXPECTED_COMMANDS lignes de commande (5). Sans ce verrou, trois copies vidées de concert seraient « identiques ». Changer la procédure impose de modifier ces constantes, délibérément.
Problèmes signalés, dans cet ordre :
| Message | Cause | Remède |
|---|---|---|
{fichier} introuvable. |
L'un des trois fichiers manque. Aucun autre contrôle n'est alors fait. | Restaurer le fichier. |
{fichier} : section « ## Installer en quatre étapes » introuvable. |
L'intertitre manque ou a changé dans le tutoriel ou le README. Les comparaisons de ce fichier sont sautées. | Rétablir l'intertitre exact. |
site/installer.html : <pre> sans <code> — ce bloc échappe au contrôle. |
Un <pre> de la page ne contient pas de <code> : ses lignes ne seraient pas comparées. |
Placer la commande dans <pre class="cmd"><code>…</code></pre>. |
{fichier} : {n} étape(s), 4 attendues. |
Verrou anti-vacuité sur les titres. | Aligner la copie sur le tutoriel, ou mettre à jour EXPECTED_STEPS si la procédure a changé. |
{fichier} : {n} commande(s), 5 attendues. |
Verrou anti-vacuité sur les commandes. | Aligner la copie sur le tutoriel, ou mettre à jour EXPECTED_COMMANDS si la procédure a changé. |
étape {i} : titre « {valeur} » dans {fichier}, « {référence} » dans docs/tutorials/installer-kirexo-chez-soi.md |
Titre différent au rang i. (absent) signale un rang qui n'existe que d'un côté. |
Recopier le titre du tutoriel. |
commande {i} : « {valeur} » dans {fichier}, « {référence} » dans docs/tutorials/installer-kirexo-chez-soi.md |
Commande différente au rang i, même convention (absent). |
Recopier la commande du tutoriel. |
site/installer.html : lien vers https://doc.kirexo.app/tutorials/installer-kirexo-chez-soi/ absent — le bloc « Aller plus loin » doit viser docs/tutorials/installer-kirexo-chez-soi.md. |
Aucun a[href] de la page ne vaut exactement l'URL publiée du tutoriel, barre finale comprise. |
Rétablir le lien du bloc « Aller plus loin ». |
L'URL attendue est InstallCommandsConsistency::DOC_BASE_URL (https://doc.kirexo.app/, le site_url de mkdocs.yml) suivie du chemin du tutoriel sans docs/ ni .md.
Le remède est toujours le même sens de propagation : le tutoriel fait foi, on aligne la page et le README sur lui. On ne corrige jamais le tutoriel pour faire passer le contrôle, sauf si c'est lui qui doit changer.
Exemple d'échec, après le retrait d'une commande de la page et l'altération d'une autre (extrait) :
✗ Étapes d'installation : 4 problème(s)
site/installer.html : 4 commande(s), 5 attendues.
commande 3 : « docker compose up -d » dans site/installer.html, « cp .env.example .env » dans docs/tutorials/installer-kirexo-chez-soi.md
commande 4 : « docker compose exec php bin/console app:user:create VOTRE_EMAIL VOTRE_PRENOM --role=both » dans site/installer.html, « docker compose up -d --wait » dans docs/tutorials/installer-kirexo-chez-soi.md
commande 5 : « (absent) » dans site/installer.html, « docker compose exec php bin/console app:user:create VOTRE_EMAIL VOTRE_PRENOM --role=both » dans docs/tutorials/installer-kirexo-chez-soi.md
Une commande retirée décale toutes les suivantes : chaque rang à partir du retrait est signalé, et le dernier apparaît (absent).
Où le contrôle tourne.
| Point d'exécution | Quand | Ce qu'il apporte |
|---|---|---|
castor site:check, donc le job CI quality:site-check |
Chaque MR et chaque push sur main, sans filtre changes: |
Seul garde-fou qui voit une MR limitée à docs/**, que test:unit ne lance pas. |
tests/Unit/Castor/Site/InstallCommandsRepositoryConsistencyTest.php, sur les vrais fichiers du dépôt |
castor all et test:unit |
Fait entrer le contrôle dans castor all, qui n'inclut pas site:check. |
Le couple tutoriel ↔ README est aussi vérifié par tests/Bash/install/install-doc.bats. Ce recouvrement est volontaire : le bats ne tourne que sur les MR dont les changes: le déclenchent.
Liens internes et ancres¶
Attributs lus dans chaque page, dans l'ordre du document : href de a, area et link ; src de script, img, source et iframe ; chaque URL candidate de srcset sur img et source.
| Valeur | Traitement |
|---|---|
Commence par //, ou schéma http:, https:, mailto:, tel:, data: |
Ignorée : les liens externes ne sont pas contrôlés. |
Tout autre schéma (javascript:, file:…) |
Problème schéma « … » interdit. |
Chemin vide (#ancre seule) |
Vise la page elle-même. |
Chemin qui commence par / |
Résolu depuis la racine du build. |
| Autre chemin | Résolu depuis le dossier de la page. La query (?…) est retirée et le chemin est décodé (%20…). |
Chemin qui finit par / ou qui désigne un dossier |
Vise index.html dans ce dossier. |
.. qui sort de la racine du build |
Problème chemin hors du site. |
| Cible inexistante | Problème fichier introuvable. |
Une ancre n'est contrôlée que si la cible est une page .html : la page doit contenir un élément dont l'id vaut exactement le fragment décodé. # et #top sont toujours valides (haut de page), sauf si un id="top" existe : c'est alors lui qui compte.
Accessibilité : serveur local et thèmes¶
Les pages sont servies par un serveur php -S lancé sur un port libre de 127.0.0.1, le temps de la commande, puis arrêté dans tous les cas. Il est nécessaire parce que 404.html utilise des chemins absolus (/assets/…, /favicon/…) que file:// ne résout pas. Il n'écoute que sur le loopback.
Thème sombre. Les pages sont auditées telles qu'elles sont déployées, sans modification. Pour le thème sombre, Chromium reçoit le drapeau force-dark-mode, qui émule prefers-color-scheme: dark. Sur un profil neuf, le script anti-flash est en mode « système » : il en déduit data-theme="dark" sur <html>. Le thème clair ne reçoit aucun drapeau. Le drapeau retenu est consigné dans le docblock de AccessibilityChecker::chromeArguments() (castor/src/Site/AccessibilityChecker.php). Le drapeau WebContentsForceDark n'est pas utilisé : il inverse les couleurs de la page, et les contrastes mesurés seraient faux.
Sonde de thème, en échec fermé. Avant chaque passe axe, la cible exécute chromium --headless=new … --dump-dom sur index.html avec les mêmes drapeaux, et lit l'attribut data-theme de <html> dans le DOM obtenu. S'il ne vaut pas le thème attendu, la cible sort en 2 :
Arguments Chromium communs aux deux thèmes : no-sandbox, disable-dev-shm-usage, disable-gpu et no-proxy-server. Le site ne charge que des ressources de même origine : aucune requête ne passe par le proxy.
Dépendances npm¶
Les deux outils sont déclarés dans les devDependencies de package.json. Ils sont exécutés par npx --yes -p {paquet}@{contrainte}, avec la contrainte lue dans package.json (comme pour castor ts:check). Le projet n'a ni node_modules/ ni lockfile.
| Paquet | Contrainte actuelle (package.json) |
Commande exécutée |
|---|---|---|
html-validate |
^11.16.1 |
html-validate --config infra/site/htmlvalidate.json --formatter stylish --max-warnings 0 var/site-build |
@axe-core/cli |
^4.13.0 |
axe --tags wcag2a,wcag2aa,wcag21a,wcag21aa --chrome-path /usr/bin/chromium --chromedriver-path /usr/bin/chromedriver --chrome-options … --stdout {url…} |
@axe-core/cli dépend du paquet npm chromedriver, dont l'installation télécharge un binaire depuis un domaine que le proxy de dev bloque. La cible passe donc à npx les variables CHROMEDRIVER_SKIP_DOWNLOAD=true et SE_OFFLINE=true, et indique le chromedriver de l'image par --chromedriver-path. Ces variables sont posées par la cible (AccessibilityChecker::ENVIRONMENT) : rien à configurer.
Le premier lancement demande à npx de télécharger les paquets depuis registry.npmjs.org.
infra/site/htmlvalidate.json étend les presets html-validate:recommended et html-validate:document. La règle require-sri n'exige un attribut integrity que sur les ressources crossorigin : le site ne charge que des assets locaux. Le fichier vit hors de site/ pour ne pas être copié dans le build, donc déployé.
castor site:deploy¶
Publie le site construit (var/site-build/ par défaut) chez deploybase, par son API d'upload, ou sur l'hébergement OVH, par lftp en FTPS. Le déploiement réel ne tourne qu'en CI (job release:site-deploy) ; ailleurs, seul --dry-run est accepté. La configuration manuelle (clé, variables, DNS) est décrite dans Publier le site vitrine.
castor site:deploy --dry-run # simulation, aucun appel réseau
castor site:deploy --dry-run --provider=ovh
castor site:deploy --expect-version="$CI_COMMIT_TAG" # forme utilisée par le job CI
| Option | Type | Défaut | Effet |
|---|---|---|---|
--provider |
string | '' |
deploybase ou ovh. Vide : variable SITE_DEPLOY_PROVIDER si elle est non vide, sinon deploybase (SiteBuilder::DEFAULT_PROVIDER). |
--dry-run |
bool | false |
Exécute les contrôles locaux, liste les fichiers et l'état des variables, sans rien envoyer. |
--expect-version |
string | '' |
Version attendue dans le build et sur la page publiée. Vide : voir la résolution ci-dessous. |
--dir |
string | var/site-build |
Dossier construit à publier. |
La logique de décision vit dans App\Castor\Site\SiteDeployGuard (castor/src/Site/SiteDeployGuard.php) ; la cible déclarée dans castor/site.php ne fait que l'I/O. Contrôles et appels réseau sont portés par infra/site/deploy.sh, ses fonctions pures par infra/site/deploy.lib.sh.
Résolution du fournisseur et de la version¶
| Valeur | Ordre de priorité | Si rien n'est exploitable |
|---|---|---|
| Fournisseur | --provider > SITE_DEPLOY_PROVIDER > SiteBuilder::DEFAULT_PROVIDER. Une valeur vide est ignorée. |
Toujours résolu. Une valeur hors des clés de SiteBuilder::HOSTING_PROVIDERS sort en 2 avec Fournisseur d'hébergement inconnu : « x » (attendus : deploybase, ovh). Corriger --provider ou la variable SITE_DEPLOY_PROVIDER. |
| Version attendue | --expect-version > CI_COMMIT_TAG s'il est semver (X.Y.Z) > clé version de site/data/release.json. La valeur dev est ignorée. |
Avec --dry-run : simulation sans contrôle de version. Sans --dry-run : sortie 2, impossible de vérifier la publication sans version attendue. |
castor site:build résout son fournisseur par la même méthode (SiteDeployGuard::resolveProvider()) : l'hébergeur cité dans les mentions légales est toujours celui qui reçoit le déploiement.
Garde de contexte¶
| Contexte | Sans --dry-run |
Avec --dry-run |
|---|---|---|
Conteneur de dev (KIREXO_INSIDE_CONTAINER=1) |
Refus, sortie 3 : la sortie réseau y passe par le proxy d'allowlist. |
Exécuté dans le conteneur. |
| Hôte (Castor hors de tout conteneur) | Refus, sortie 3 : la cible s'exécuterait dans le conteneur de dev. |
Relancé dans le conteneur par docker compose exec -T php. |
Job CI (autre conteneur, sans KIREXO_INSIDE_CONTAINER) |
Exécuté. | Exécuté. |
La garde repose sur KIREXO_INSIDE_CONTAINER, injectée uniquement dans le conteneur de dev, et non sur la seule détection de conteneur, qui est aussi vraie dans un job CI en exécuteur Docker (/.dockerenv). infra/site/deploy.sh redouble la garde : lancé directement avec KIREXO_INSIDE_CONTAINER=1 et sans --dry-run, il sort lui aussi en 3.
Contrôles avant tout envoi¶
Le script vérifie, dans cet ordre, et échoue avant le premier octet réseau :
- les arguments (
--providerest obligatoire au niveau du script, la cible le fournit toujours) ; - la garde de contexte ;
- la présence du dossier, de
index.htmlet du fichier d'en-têtes du fournisseur (_headerspour deploybase,.htaccesspour ovh) ; - si une version est attendue : elle est semver, et le marqueur
kirexo:versiondeindex.htmlporte exactement cette valeur ; - les variables requises, nommées sans leur valeur ;
- les outils :
curl,jq,sha256sum,stat,find,seq, pluslftppour ovh ; - pour ovh :
OVH_FTP_REMOTE_DIRn'est ni vide, ni/, ni., ni.., et ne contient pas de segment..(garde demirror --delete).
| Fournisseur | Variables requises | Fichier envoyé | Fichier exclu |
|---|---|---|---|
deploybase |
DEPLOYBASE_API_KEY, DEPLOYBASE_PROJECT_ID |
_headers |
.htaccess |
ovh |
OVH_FTP_HOST, OVH_FTP_USER, OVH_FTP_PASSWORD |
.htaccess |
_headers |
Les fichiers cachés sont inclus. Variables facultatives du script : Site vitrine.
--dry-run¶
Exécute les contrôles 1 à 7 puis imprime le fournisseur, chaque fichier qui serait envoyé avec sa taille, le total, le fichier exclu, l'état ✓/✗ de chaque variable requise et l'URL de vérification. Aucun appel à curl ni à lftp. S'il manque des variables, il les liste toutes et sort en 2, avec la mention attendu dans le conteneur de dev, où les secrets n'existent pas.
Déroulé d'un déploiement deploybase¶
API https://api.deploybase.eu, préfixe /api/v1, en-tête Authorization: Bearer dbk_….
- Manifeste :
{"branch", "label", "files": [{"path", "size", "hash"}]}, avecbranch=DEPLOYBASE_BRANCH(mainpar défaut),label=kirexo X.Y.Z, la taille en octets et le sha256 de chaque fichier. - Ouverture de session :
POST /projects/{id}/uploads, en-têteIdempotency-Key: kirexo-site-<CI_JOB_ID>. Réponse201attendue, avecupload_id,deployment_idet la listemissing. Les entrées demissing(chemins ou hashes sha256) sont traduites en chemins du manifeste ; une entrée inconnue est une erreur. - Envoi des seuls fichiers manquants :
PUT /uploads/{upload_id}/files/{chemin encodé}, corps brut, en-têteX-Upload-Hash, 3 tentatives. Réponse204attendue. - Finalisation :
POST /uploads/{upload_id}/finalize, réponse200. - Attente :
GET /deployments/{id}toutes les 3 s jusqu'àdeployed, borné parSITE_DEPLOY_POLL_TIMEOUT.failedoucancelled: échec, avec la catégorie d'erreur. - Promotion :
POST /projects/{id}/promoteavec{"deployment_id"}, réponse200dontlive_deployment_iddoit valoir l'identifiant déployé. L'appel est systématique ; il purge aussi le cache CDN.
Déroulé d'un déploiement OVH¶
lftp mirror --reverse --delete --no-perms --exclude-glob _headers vers OVH_FTP_REMOTE_DIR, en FTPS explicite imposé (ftp:ssl-force true, ftp:ssl-protect-data true, ssl:verify-certificate yes). Ce qui n'est plus dans le build est supprimé du serveur. OVH_FTP_USER et OVH_FTP_HOST doivent tenir dans [A-Za-z0-9._@-], les chemins dans [A-Za-z0-9._@/-], sinon sortie 2.
Vérification après publication¶
Commune aux deux fournisseurs, dès qu'une version est attendue. Le script lit SITE_PUBLIC_URL (https://www.kirexo.app/) avec Cache-Control: no-cache, au plus SITE_DEPLOY_VERIFY_ATTEMPTS fois (10) à SITE_DEPLOY_VERIFY_DELAY secondes d'intervalle (6), et attend que le marqueur kirexo:version porte la version attendue. C'est la seule preuve que le domaine public sert le build : une promotion réussie ne l'atteste pas. Échec : www.kirexo.app ne sert pas X.Y.Z (lu : « … ») après N tentatives., sortie 1.
Secrets¶
Le jeton deploybase est écrit dans un fichier d'en-têtes temporaire (droits 600, supprimé à la sortie) passé par curl --header @fichier. Le mot de passe FTP passe par la variable LFTP_PASSWORD et open --env-password. Aucun des deux n'apparaît en argument de processus ni en sortie ; une réponse d'API n'est affichée qu'en cas d'échec.
Codes de sortie¶
Le code du script est propagé tel quel par la cible.
| Code | Signification |
|---|---|
0 |
Succès, ou --dry-run sans anomalie. |
1 |
Échec du déploiement : réponse d'API en erreur, statut failed ou cancelled, délai d'attente dépassé, promotion incohérente, lftp en échec, ou version absente de la page publiée après toutes les tentatives. |
2 |
Usage invalide ou prérequis absent : argument, fournisseur inconnu, dossier, index.html ou fichier d'en-têtes absent, variable manquante, outil manquant, répertoire distant dangereux, version du build différente de la version attendue, version attendue introuvable. |
3 |
Refus de contexte : conteneur de dev ou hôte, sans --dry-run. |
Remèdes par symptôme : Publier le site vitrine › Dépannage.
castor site:refresh¶
Écrit la partie fixe du site vitrine pour une release : valide site/data/statuts.json, puis écrit site/data/release.json, lu par castor site:build pour les marqueurs kirexo:version et kirexo:date. Rendu déterministe, sans LLM. La cible est appelée par prepare.sh, le script du skill /creer-tag (cf. Créer un tag de release), juste après castor changelog:prepare.
castor site:refresh --name=0.2.0 # date UTC du jour
castor site:refresh --name=0.2.0 --date=2026-10-03
| Option | Type | Défaut | Effet |
|---|---|---|---|
--name |
string | '' |
Obligatoire. Version de la release, semver stricte (MAJEUR.MINEUR.CORRECTIF, sans zéro de tête ni préfixe v). Vide : erreur --name est obligatoire (ex. --name=0.0.2)., sortie 1. L'option ne s'appelle pas --version, option globale de Symfony Console interceptée par Castor. |
--date |
string | date UTC du jour | Date de la release, au format AAAA-MM-JJ, et date réelle du calendrier (2026-02-30 est refusée). |
Effets, dans l'ordre.
- Validation de
site/data/statuts.jsonparStatutsValidator::validateProject(), la même que celle desite:build(cf. Échecs et remèdes). - Validation de la version et de la date par
App\Castor\Site\SiteRefresher(castor/src/Site/SiteRefresher.php). - Écriture de
site/data/release.json(SiteBuilder::RELEASE_FILE).
Si l'une des validations échoue, rien n'est écrit. Le contenu produit est toujours le même pour les mêmes options : clés dans cet ordre, indentation de 4 espaces, retour à la ligne final. Relancer la cible avec les mêmes options est donc sans effet sur le fichier.
| Situation | Effet |
|---|---|
| Succès | site/data/release.json : version 0.2.0, date 2026-10-03 ; N statut(s) valide(s)., sortie 0. |
--name vide |
--name est obligatoire (ex. --name=0.0.2)., sortie 1. |
| Statuts invalides | Message de la SiteBuildException (cause, fichier, remède), sortie 1. |
Version non semver stricte (v1.0.0, 01.0.0, dev…) |
« … » n'est pas une version sémantique MAJEUR.MINEUR.CORRECTIF (ex. 0.0.1)., sortie 1. |
Date invalide (2026-02-30, 02/10/2026…) |
Date de release invalide : « … » (attendu AAAA-MM-JJ, date réelle)., sortie 1. |
La cible est en PHP natif, sans Docker, sans Git et sans réseau.
castor site:context¶
Imprime, en lecture seule, le contexte compact de rédaction du site pour la release en cours : niveau et budget, section de CHANGELOG.md de la version, fichiers de site/, diff depuis le tag semver précédent et statuts. Sa sortie est lue par Claude à l'étape « Mettre à jour le site » du skill /creer-tag (cf. Créer un tag de release). Le rendu vit dans App\Castor\Site\SiteContext (castor/src/Site/SiteContext.php) ; la cible lit Git et les fichiers.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--bump |
string | patch |
Niveau de la release : patch, minor ou major. Toute autre valeur lève InvalidArgumentException : --bump attend patch, minor ou major, reçu : « … ». |
Données lues.
| Donnée | Source |
|---|---|
| Version | Clé version de site/data/release.json, écrit par castor site:refresh. |
| Section de changelog | Bloc ## [<version>] de CHANGELOG.md, jusqu'à la section suivante exclue. |
| Statuts | StatutsValidator::validateProject(), comme site:refresh. |
| Tag de référence | Plus haute version semver parmi les tags Git locaux, version courante exclue. Les tags horodatés YYYYMMDDHHMM et les tags annexes sont ignorés. Si ce tag ne contient pas site/, il n'y a pas de référence. |
| Fichiers | git ls-files --cached --others --exclude-standard -- site/ (fichiers non suivis compris, fichiers ignorés exclus), hors site/data/. |
Maquette (major seulement) |
Première ligne de var/claude/release-<version>/maquette-validee.txt qui est une URL https://…. |
Structure de la sortie. Six blocs, séparés par une ligne vide, dans cet ordre :
=== Contexte de rédaction du site — release <version> (<niveau>) ===
Budget : <phrase du niveau>
Partie fixe déjà à jour : site/data/release.json (version, date) ; mémoire et statuts rendus par site:build. Ne jamais éditer site/data/ ni le contenu des marqueurs kirexo:* (version, date, memoire, hebergeur, statuts).
Dépassement : si une nouveauté visible dépasse ce budget (nouveau canal, nouvelle extension), le proposer au mainteneur et ne rien écrire avant sa décision.
Maquette : <URL>
--- CHANGELOG [<version>] ---
<section de CHANGELOG.md>
--- Fichiers de site/ (hors data/) ---
<chemin> (<n> lignes) — marqueurs : <nom>, <nom>
<chemin> (binaire)
--- Diff de site/ depuis <tag> (hors data/) ---
<git diff --stat>
<git diff, 200 lignes au plus>
… <n> ligne(s) tronquée(s) — voir : git diff <tag> -- site/ ':(exclude)site/data/'
--- Statuts (site/data/statuts.json) ---
- <fonction> — <libellé> (<etat>) (plugin <plugin>) : <detail>
Vérification : bash .claude/skills/creer-tag/bin/site-diff-check.sh <niveau>
| Bloc | Détail |
|---|---|
| En-tête | La ligne Maquette : n'existe qu'en major. Sans URL valide, elle vaut ABSENTE — faire valider une maquette Artifact avant toute écriture dans site/. |
| Fichiers | Chemins relatifs à site/, triés. Le nombre de lignes est donné pour les extensions html, css, js, svg, txt, json et xml ; tout autre fichier est marqué (binaire). Les marqueurs kirexo:* sont listés pour les seules pages .html, dans l'ordre d'apparition et sans doublon ; la mention est omise si la page n'en a aucun. |
| Diff | Sans tag de référence, le bloc devient --- Diff de site/ --- suivi de Aucun tag semver de référence : pas de diff (première publication du site). Sans changement : Aucun changement de site/ depuis <tag>. Le patch est tronqué à SiteContext::DIFF_MAX_LINES (200) lignes ; la ligne … tronquée(s) n'apparaît qu'au-delà. |
| Statuts | Une ligne par entrée, dans l'ordre du fichier. Le libellé vient de StatutsRenderer::LABELS (disponible → « Disponible », en-cours → « En cours », prevu → « Prévu », pas-prevu → « Pas prévu »). Le suffixe (plugin <plugin>) est omis quand plugin vaut null. |
Phrase de budget de la ligne Budget :, selon le niveau (seuils SiteContext::PATCH_MAX_LINES et SiteContext::MINOR_MAX_LINES) :
| Niveau | Phrase |
|---|---|
patch |
mini-modification : corriger uniquement ce que le changelog a rendu faux (aucune écriture si rien n'est devenu faux). Aucun fichier ajouté ou supprimé, ≤ 30 lignes modifiées. |
minor |
petites modifications : blocs mis à jour ou ajoutés, mise en page inchangée. Aucun fichier HTML ajouté ou supprimé, ≤ 300 lignes modifiées. |
major |
quasi nouveau site, sans seuil de lignes. Maquette Artifact validée par le mainteneur AVANT toute écriture dans site/, URL dans var/claude/release-<version>/maquette-validee.txt. |
Ces deux seuils sont dupliqués dans .claude/skills/creer-tag/bin/site-diff-check.lib.sh (SITE_DC_PATCH_MAX_LINES, SITE_DC_MINOR_MAX_LINES), le garde-fou qui les applique. Le test tests/Unit/Castor/Site/SiteBudgetConsistencyTest.php vérifie leur égalité.
Codes de sortie.
| Situation | Effet |
|---|---|
| Succès | Contexte imprimé, sortie 0. |
site/data/release.json absent ou sans version |
site/data/release.json absent — lance prepare.sh (site:refresh) d'abord., sortie 1. |
Section absente de CHANGELOG.md |
Aucune section [<version>] dans CHANGELOG.md, sortie 1. |
| Statuts invalides | Message de la SiteBuildException, sortie 1. |
--bump invalide |
InvalidArgumentException (cf. tableau des options). |
Intégration continue¶
castor ci:local¶
Valide — et, au besoin, exécute — la pipeline GitLab CI en local, via gitlab-ci-local. À lancer après tout changement dans .gitlab-ci.yml ou .gitlab/ci/, avant de pousser, pour attraper une erreur de configuration (include cassé, !reference invalide, needs orphelin, rules incohérentes) sans consommer un cycle de pipeline distante.
| Argument | Type | Défaut | Effet |
|---|---|---|---|
job |
string | '' |
Nom d'un job GitLab CI à exécuter. Vide = --list-all : valide la config et liste tous les jobs sans rien exécuter (rapide, sans Docker). |
# Validation + liste de tous les jobs (rapide, sans exécution ni Docker)
castor ci:local
# Exécution d'un job précis (nécessite le socket Docker → hôte uniquement)
castor ci:local quality:phpstan
Sans argument, la cible lance gitlab-ci-local --list-all. Le flag --list-all (et non --list) est délibéré : --list ne montre que les jobs actifs dans le contexte git courant ; sur une branche hors MR, main ou tag, toutes les rules sont fausses et la table ressort vide. --list-all liste tous les jobs, indépendamment des rules, ce qui valide la structure complète de la pipeline.
Ce que la validation vérifie réellement : le parsing de la config, la fusion des include / !reference / needs et la validation du schéma JSON de .gitlab-ci.yml. C'est là tout son intérêt — elle attrape les includes cassés, les !reference invalides et les erreurs de structure sans exécuter le moindre job.
Dans les deux modes, la cible ajoute :
--ignore-schema-paths '#/properties/release/properties/assets/properties/links/items/additionalProperties'
Le schéma JSON embarqué par gitlab-ci-local est une copie ancienne de celui de l'éditeur GitLab : pour un lien de release:assets:links, il ne connaît que la clé filepath, dépréciée, et rejette direct_asset_path, que release:create utilise pour ses permaliens (cf. Assets de release et permaliens). GitLab, lui, transmet cette clé à l'outil de release, qui la gère. L'exception porte sur ce seul chemin — les clés supplémentaires d'un lien de release — : tout autre écart au schéma reste bloquant.
Avec un nom de job, la cible exécute réellement ce job : gitlab-ci-local lance alors des conteneurs Docker « frères » (Docker-out-of-Docker). Le socket Docker est monté (/var/run/docker.sock) et le projet est monté au même chemin que sur l'hôte ($cwd:$cwd) pour que les bind-mounts des jobs frères pointent vers des chemins hôte valides. Cette variante nécessite donc un terminal hôte (cf. avertissement ci-dessous).
Dans les deux cas, la cible utilise un conteneur éphémère node:22 (Debian) — pas la variante node:22-alpine : Alpine n'embarque ni git ni bash, que gitlab-ci-local appelle en interne (sinon erreur spawn git ENOENT / spawn bash ENOENT).
Prérequis : les fichiers d'include doivent être suivis par git
gitlab-ci-local ne lit que les fichiers suivis par git. Un nouveau fichier d'include (ex. un nouveau .gitlab/ci/*.yml) ou une nouvelle version de la config doit être git addé (au minimum dans l'index, pas forcément commité) avant de lancer castor ci:local — sinon l'outil échoue sur Local include file cannot be found. Réflexe à avoir dès qu'on ajoute un include et qu'on veut le valider localement.
Cible HÔTE uniquement pour exécuter un job
castor ci:local <job> refuse de tourner dans le conteneur php : le socket Docker n'y est pas monté, gitlab-ci-local ne pourrait pas lancer les conteneurs de jobs. Lancée depuis l'intérieur avec un nom de job, elle exit avec un message explicite. La validation seule (castor ci:local sans argument) fonctionne en revanche depuis le conteneur comme depuis l'hôte — elle n'a pas besoin de Docker.
Dossier .gitlab-ci-local/ généré
gitlab-ci-local crée un répertoire .gitlab-ci-local/ à la racine du dépôt (état, artifacts et logs locaux des runs). Il est gitignoré — aucune action requise.
Garde-fou de config, pas un substitut à la pipeline réelle
gitlab-ci-local ne reproduit pas parfaitement l'environnement de GitLab.com. Ne fonctionnent pas comme en réel : les services:, les variables secrètes (GITLAB_TOKEN…), certaines variables prédéfinies, et les jobs pages / release: / registry / schedule. C'est un outil de validation de la configuration (structure, includes, !reference, needs, rules) — la vérité reste la pipeline distante, qui doit passer avant merge (cf. Pipeline GitLab CI).
Cibles ci:* appelées par les jobs GitLab¶
Cinq cibles minces enveloppent l'API GitLab v4 pour le compte de la pipeline. Elles remplacent les heredocs jq + curl qui vivaient auparavant dans les jobs, et toute leur logique HTTP est portée par App\Ci\GitlabApiClient (src/Ci/GitlabApiClient.php), testée unitairement. Elles ne sont pas destinées à un usage manuel.
Chacune lit trois variables d'environnement de job — CI_API_V4_URL, CI_PROJECT_ID, GITLAB_TOKEN — et coupe le job avec un message explicite si l'une manque.
| Cible | Effet | Code de sortie |
|---|---|---|
ci:open-issue |
Crée une issue. Options : --title, --description ou --description-file (prioritaire), --labels (CSV). Écrit le JSON du résultat sur la sortie standard. |
0 |
ci:open-mr |
Crée une merge request (squash + suppression de la branche source). Options : --source-branch et --title requis, --target-branch (défaut main), --description / --description-file, --labels. |
0, 1 si un requis manque |
ci:check-open-issue |
Vérifie qu'aucune issue ouverte ne porte tous les labels donnés (--labels). |
0 si aucune, 1 sinon |
ci:check-open-mr |
Vérifie qu'aucune MR ouverte ne porte tous les labels donnés et le préfixe de branche source donné (--labels, --source-branch-prefix). |
0 si aucune, 1 sinon |
ci:check-tag |
Vérifie qu'un tag n'existe pas déjà côté GitLab. Argument : le nom du tag (ex. castor ci:check-tag 0.0.1). Pré-check de castor tag:create. Message si le tag existe : Le tag "0.0.1" existe déjà — abandon (choisis une version supérieure). |
0 si libre, 1 s'il existe ou en cas d'erreur API |
Le sens des codes de sortie est fail-safe, pas fail-fast
Les trois cibles check-* sortent en 1 quand ce qu'elles cherchent existe — et ci:check-tag en fait autant sur une erreur d'API. C'est délibéré : ces cibles gardent des jobs qui créent des objets (issue de sécurité, MR de bump, tag de release). En cas de doute, ne rien créer coûte un cycle de pipeline ; créer un doublon pollue le suivi du projet.
Prérequis d'image : castor doit être dans l'image du job
Ces cibles sont invoquées par des jobs qui tournent sur kirexo-base. Le binaire Castor est donc installé dès le stage frankenphp_base du Dockerfile — s'il n'était posé qu'au stage de développement, kirexo-base ne l'embarquerait pas et les jobs échoueraient sur un castor: not found.
Release / Tag¶
castor changelog:prepare¶
Génère et insère dans CHANGELOG.md une section de release à partir des commits d'une plage Git. La génération est strictement déterministe (aucun LLM) : les sujets de commits sont lus via git log --no-merges --format=%s, classés par rubrique selon leur préfixe Conventional Commits, puis rendus en Markdown. Toute la logique de formatage vit dans la classe pure App\Castor\Changelog\ChangelogGenerator (castor/src/Changelog/ChangelogGenerator.php) ; la cible (castor/changelog.php) ne fait que l'I/O.
La nouvelle section est insérée en tête de l'historique versionné, juste sous l'introduction, avant la première section ## [...] existante. La correspondance préfixe → rubrique est documentée dans Convention du CHANGELOG.md.
| Option | Type | Défaut | Effet |
|---|---|---|---|
--from |
string | borne de la release précédente | Borne basse de la plage. Vide = plus haute version semver parmi les tags Git locaux ; s'il n'en existe aucune (section 0.0.1 uniquement), le dernier ancien tag horodaté YYYYMMDDHHMM par date de création ; s'il n'y a ni l'un ni l'autre, part du début de l'historique. Les tags annexes (etape4-*…) ne sont jamais retenus. |
--to |
string | HEAD |
Borne haute de la plage. |
--name |
string | patch suivante | Version utilisée dans le titre ## [<name>]. Fournie, elle doit être une version semver stricte (MAJEUR.MINEUR.CORRECTIF, sans zéro de tête) : sinon la cible lève une InvalidArgumentException. Vide = patch suivante de la plus haute version semver des tags locaux, ou 0.0.1 s'il n'en existe aucune — le même défaut que le job CI tag:create. |
--date |
string | date UTC du jour | Date du titre (YYYY-MM-DD). Une version semver n'encode aucune date : sans valeur, la date UTC du jour est utilisée. |
--print |
flag | false |
Affiche la section générée sur la sortie standard sans toucher à CHANGELOG.md. Le contrôle de section en double n'est pas appliqué. |
# Insère la section pour HEAD depuis la version précédente, nom = patch suivante
castor changelog:prepare
# Prévisualise sans écrire
castor changelog:prepare --print
# Impose une version (cas du skill /creer-tag : le commit taggé porte déjà sa section)
castor changelog:prepare --name 0.1.0
# Plage explicite
castor changelog:prepare --from 0.0.1 --to HEAD
Comportements particuliers :
| Situation | Effet |
|---|---|
| La plage ne contient aucun commit | Warning Aucun commit dans la plage … — rien à générer., rien n'est écrit, sortie 0. |
Une section ## [<name>] existe déjà dans CHANGELOG.md (hors --print) |
Erreur Une section [<name>] existe déjà dans CHANGELOG.md — rien n'est écrit., sortie 1. Protège d'une double exécution et d'une collision avec un titre historique. |
C'est le moteur du skill /creer-tag, qui l'appelle avec --name pour que la section soit écrite avant la pose du tag. Le skill enchaîne ensuite sur castor site:refresh, puis sur castor site:context pour la rédaction du site vitrine : ces deux cibles sont décrites avec les autres cibles site:*.
castor tag:next-version¶
Affiche la prochaine version sémantique de release, calculée à partir des tags Git locaux. Sortie : la version seule, sur une ligne, sans autre texte — elle est capturée telle quelle par le script prepare.sh du skill /creer-tag. Le calcul vit dans la classe pure App\Castor\Release\ReleaseTagResolver (castor/src/Release/ReleaseTagResolver.php), la version et son incrément dans App\Castor\Release\SemanticVersion et App\Castor\Release\ReleaseBump (castor/src/Release/).
| Option | Type | Défaut | Effet |
|---|---|---|---|
--bump |
string | patch |
Niveau d'incrément : patch (x.y.z → x.y.(z+1)), minor (→ x.(y+1).0) ou major (→ (x+1).0.0). Toute autre valeur lève InvalidArgumentException : --bump attend patch, minor ou major, reçu : « … ». |
Règles de calcul :
- seuls les tags de la forme
^[0-9]+\.[0-9]+\.[0-9]+$sont candidats, et parmi eux seuls ceux qui sont semver stricts (un01.0.0poussé à la main est ignoré) ; - les anciens tags horodatés
YYYYMMDDHHMMet les tags annexes (etape4-*,v*…) sont ignorés ; - la dernière version est le maximum par comparaison numérique des trois composantes (
0.10.0>0.9.0,0.0.10>0.0.9) ; - s'il n'existe aucune version semver, la sortie est
0.0.1quel que soit--bump.
castor tag:next-version # ex. 0.0.4 si la dernière version est 0.0.3
castor tag:next-version --bump=minor # ex. 0.1.0
castor tag:next-version --bump=major # ex. 1.0.0
Aucun effet réseau
La cible ne fait pas de git fetch --tags : elle lit git tag --list tel quel. Si les tags locaux sont en retard sur le serveur, la version affichée peut être déjà prise — prepare.sh rafraîchit les tags avant de l'appeler, et le job CI tag:create revérifie la monotonie côté serveur.
castor tag:create¶
Déclenche la pipeline GitLab de création d'un tag de release : exécute glab ci run --branch main --variables "CREATE_TAG:true". Le tag, une version sémantique MAJEUR.MINEUR.CORRECTIF, est posé côté serveur GitLab par le job CI tag:create, qui enchaîne ensuite build des images, déploiement de la doc et création de la release. Simple raccourci autour de la « Méthode B (CLI glab) » documentée dans Créer un tag de release.
C'est une action à effet remote (elle déclenche une pipeline distante) : à lancer manuellement par le mainteneur. Contrairement aux autres cibles, elle s'appuie sur le binaire hôte glab (pas de wrap docker compose) et nécessite un glab authentifié (glab auth status).
| Option | Type | Défaut | Effet |
|---|---|---|---|
--name |
string | '' |
Impose la version via la variable CI TAG_NAME. Doit être semver stricte (MAJEUR.MINEUR.CORRECTIF, sans zéro de tête ni préfixe v) et, côté job CI, strictement supérieure à la dernière version. Sans valeur, le job CI pose la patch suivante de la dernière version semver, ou 0.0.1 s'il n'en existe aucune. Utilisé par le skill /creer-tag pour que le commit taggé contienne déjà sa section de CHANGELOG.md. |
--force |
flag | false |
Ajoute --variables "FORCE_TAG:true" : outrepasse le garde-fou « pipeline verte sur le dernier commit de main » du job tag:create. Affiche un warning. |
Avec --name, une forme invalide (1.2, v0.1.0, 01.0.0, 1.2.3-rc1, ancien format horodaté…) lève une InvalidArgumentException avant de consommer une pipeline. La monotonie n'est pas vérifiée localement, les tags locaux pouvant être en retard sur le serveur : c'est le job CI qui fait foi (cf. Ce que fait tag:create).
Effet remote
castor tag:create déclenche une pipeline distante et, in fine, crée un tag de release. À réserver au mainteneur, jamais automatisé sans intervention. Le détail du garde-fou FORCE_TAG et de la chaîne de jobs déclenchée est dans Créer un tag de release.
Ordre recommandé avant une clôture de tâche¶
Deux séquences distinctes selon où tu codes — le hook stop-checklist.sh détecte automatiquement le contexte (KIREXO_INSIDE_CONTAINER=1 ou /.dockerenv) et affiche la checklist correspondante, en sourçant .claude/hooks/lib/checklist-container.sh ou .claude/hooks/lib/checklist-host.sh. Détail des hooks : Hooks Claude Code.
Côté conteneur — checklist applicative¶
Aligné avec CLAUDE.md :
castor composer:validate # cohérence composer.json ↔ composer.lock : deux fichiers lus → le plus rapide
castor cs:fix # style : peut modifier les fichiers → avant les autres vérifs PHP
castor phpstan # analyse statique : sur du code stabilisé par cs:fix
castor lint # Twig, YAML, conteneur Symfony, shellcheck
castor ts:check # typage TypeScript
castor doctrine:schema:validate # schéma BDD : dépend du conteneur
castor test:unit # tests unitaires + intégration : rapides
castor test:bash # fonctions pures des libs Bash (allowlist.lib.sh, …) via bats
castor test:e2e # tests E2E Panther : les plus lents, en dernier
Raccourci équivalent : castor all.
Chaque étape élimine une classe de problèmes pour que la suivante travaille sur du code propre. Inverser cs:fix et phpstan invaliderait le résultat de PHPStan dès que le fixer modifie un fichier.
Côté hôte — checklist d'infrastructure¶
castor lint:shell # shellcheck sur infra/, .claude/hooks/ et .claude/skills/*/bin/
docker compose config -q # validation des compose*.yaml empilés
docker run --rm -i hadolint/hadolint:latest hadolint --no-color --failure-threshold error - < Dockerfile
# + HEAD HTTP sur les URLs construites depuis les ARG *_VERSION du Dockerfile
Raccourci équivalent : castor host:check.
La checklist hôte est volontairement plus courte : seuls les fichiers d'infrastructure (Dockerfile, compose*.yaml, scripts infra/) sont validés. Pas de check de vitalité applicative — l'app ne tourne pas forcément sur l'hôte (stack peut être down, c'est attendu).