Aller au contenu

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 :

castor <namespace>:<nom> [options]

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 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:destroy y reprend --force quand 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 aussi false sous --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) :

input()->isInteractive() && \defined('STDIN') && \stream_isatty(\STDIN)

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.
castor docker:up --build

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:down

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:logs
castor docker:logs php
castor docker:logs database

castor docker:sh

Ouvre un shell bash interactif dans le conteneur php (docker compose exec php bash).

castor docker:sh

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.

castor docker:build

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écutable claude dans le PATH ;
  • 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.json et public/assets/importmap.json ;
  • elle charge les extensions PHP obligatoires : pcntl (liste prod_image_required_extensions, infra/image/check-prod-image.lib.sh), nécessaire à l'arrêt propre du worker Messenger — cf. pcntl dans 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.
castor docker:check-prod-image
castor docker:check-prod-image --image=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.
castor docker:smoke-prod-image
castor docker:smoke-prod-image --image=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 :

castor docker:check-prod-image
castor docker:smoke-prod-image --image=kirexo-prod:check-local
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

  1. Option --edge, puis garde hôte. Une valeur de --edge autre que vide ou traefik sort en 2. Lancée dans le conteneur, elle sort en 1 avec le message « terminal hôte » standard, qui rappelle que la CI rejoue ce test dans les jobs docker:test-install et docker:test-install-traefik, sur tag uniquement.
  2. Image. Sans --image, docker build --target frankenphp_prod --tag kirexo-prod:check-local ., comme castor docker:check-prod-image ; un build en échec interrompt la cible.
  3. Rendu du bundle. sh infra/release/publish-bundle.sh render 0.0.0 var/install-e2e-bundle — le script du job release:bundle-render, avec la même substitution de KIREXO_VERSION. Le dossier est supprimé puis recréé à chaque exécution. 0.0.0 est une version sentinelle : semver valide, jamais publiée (la première release est 0.0.1).
  4. 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 image kirexo-prod dans le bundle : sortie en 2.
  5. Tag local. docker tag <image> registry.gitlab.com/shaurifr/kirexo/kirexo-prod:0.0.0 : le bundle tourne sans modification sur l'image locale.
  6. Test. sh infra/image/install-e2e.sh --bundle-dir var/install-e2e-bundle --version 0.0.0 [--keep], sans --pull ni --expected-digest ; avec --edge=traefik, sh infra/image/install-e2e-traefik.sh --bundle-dir var/install-e2e-bundle --version 0.0.0 [--keep]. Les variables INSTALL_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
E-mail 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, puis docker compose logs --no-color --tail 300 de 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-orphans supprime 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érifier docker compose ls -a, docker volume ls et docker network ls.
  • --keep. Le démontage est sauté ; la commande down -v complète est affichée, ainsi qu'une commande curl --connect-to vers 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 que KIREXO_BIND_ADDRESS et KIREXO_HTTP_PORT sont joignables depuis l'hôte. En local, --keep permet 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) et registry.gitlab.com/shaurifr/kirexo/kirexo-prod:0.0.0 restent 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
KIREXO_TRAEFIK_RULE='Host(`app.kirexo.test`) || Host(`blog.exemple.test`)'

É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 :

  1. bash infra/proxy/proxy-net.sh — crée le réseau externe kirexo-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ègle DOCKER-USER de cloisonnement inter-worktrees. Le script refuse de continuer si un réseau homonyme existe sans être internal : il rendrait une route Internet au conteneur de l'agent, sans aucun signal. Un réseau existant dont l'IPAM n'exclut pas KIREXO_PROXY_IP est signalé (avertissement, pas d'échec) avec son remède, castor proxy:migrate.
  2. É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 donc app.main.localhost, docs.main.localhost et mailpit.main.localhost.
  3. 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à — main s'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 pour app.demo.localhost (le site de démonstration, trop long pour le joker) et la redirection 308 de https://localhost vers https://app.<worktree par défaut>.localhost.
  4. 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 ./Caddyfile est un bind de fichier, et c'est ce -f qui décide du répertoire depuis lequel il est résolu, pour toute la vie du conteneur.
  5. bash infra/proxy/proxy-net.sh --verify-caddy-ip — contrôle l'adresse réellement obtenue par le conteneur caddy-proxy, que le up ait réussi ou échoué. Sortie 1 de la cible si elle diffère de 172.31.1.2.
  6. castor proxy:reload — inconditionnel. caddy reload est 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 rappelle castor 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.

castor proxy:migrate
Option Type Défaut Effet
--no-wait flag --wait actif par défaut Ne pas attendre que le healthcheck du proxy soit vert.
castor proxy:up

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 :

  1. caddy validate --config /etc/caddy/Caddyfile dans le conteneur ;
  2. 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:reload

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:down

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 :

  1. 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.
  2. Arrêt immédiat si l'un d'eux n'appartient à aucun projet Compose — voir l'encadré ci-dessous.
  3. Plan affiché : les projets qui vont être descendus. Confirmation, sautée avec --yes ; hors terminal, sortie en 1 avec castor proxy:migrate --yes à retaper. Répondre non laisse le réseau non conforme, et rien n'a été touché.
  4. castor proxy:down — le proxy est descendu par sa cible dédiée, la seule à garantir l'absence de -v sur le volume qui porte la CA.
  5. docker compose -p <projet> down pour chaque autre projet attaché. Jamais -v : les volumes nommés sont conservés, bases des worktrees comprises.
  6. docker network rm kirexo-proxy.
  7. castor proxy:up, qui recrée le réseau via proxy-net.sh — donc borné — puis contrôle l'adresse réellement obtenue par le Caddy.
castor proxy:migrate
castor proxy:migrate --yes

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.
castor proxy:status

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: de 00-fallback.caddy (proxy_default_wt, infra/proxy/proxy.lib.sh) ;
  • le défaut effectif, celui que consomment castor proxy:up et castor wt:up : le worktree du marqueur si sa conf de site existe, sinon le dépôt principal (KIREXO_PROXY_MAIN_WT) si 01-main.caddy existe, 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).
castor cert:trust

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:up porte en plus les fichiers empilés (-f compose.yaml -f compose.override.yaml -f compose.worktree.yaml, plus compose.full.yaml en profil full) : ils créent le conteneur, et sans compose.worktree.yaml — que Compose n'auto-découvre jamais — il perdrait le bind du git common dir ;
  • le ps du bloc de wt:up en é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 :

  • --from choisit 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 sur origin est suivie (--track), jamais recréée depuis main — sinon le worktree ne contiendrait aucun des commits poussés. La décision est portée par castor/src/Worktree/BranchResolver.php.
  • L'arbitrage ne s'applique qu'en cas d'ambiguïté. Un --from qui é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 :

  1. Worktree git — créé dans <parent du dépôt principal>/kirexo-worktrees/<worktree> s'il est absent, avec git 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 sur origin, auquel cas elle est réutilisée (une branche distante est suivie, pas recréée). Plusieurs candidates : arrêt avec la liste, sauf si --from en désigne une. Aucun appel à l'API GitLab — la cible fonctionne hors ligne.
  2. Proxy hôte — castor proxy:up, idempotent.
  3. 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 pas wt:up.
  4. Réconciliation — .env.worktree, lien var/claude vers 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 publie KIREXO_SHARED_CLAUDE_DIR) et avant le up, dont le bind exige un chemin hôte existant.
  5. Dépendances Composer — docker compose run --rm --no-deps php composer install dans un conteneur jetable, quand vendor/autoload_runtime.php est absent ou plus ancien que composer.lock. Sur un worktree sans vendor/, l'installation est précédée d'une amorce de vendor/ 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 le up --wait, FrankenPHP exigeant vendor/autoload_runtime.php dès son premier tour de boucle — l'installation ne peut donc pas passer par le conteneur de service.
  6. Démarrage — docker compose up -d --wait --remove-orphans sur le projet du worktree. En cas d'échec, la cible sort en 1 avec un remède plutôt qu'une trace Compose : voir Ce que wt:up affiche quand le démarrage échoue.
  7. Gateway du réseau — WT_GATEWAY_IP relevée sur le réseau réel ; si elle a changé, le seul service php est recréé pour appliquer extra_hosts (figé à la création du conteneur).
  8. Assets front — bin/console importmap:install et bin/console tailwind:build dans le conteneur de service (exec), la stack étant debout à ce stade. Déclenchés quand assets/vendor/ ou var/tailwind/app.built.css sont 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 — un composer.lock qui bouge fait bouger les versions d'importmap.php.
  9. Données — infra/worktree/bootstrap-data.sh dans le conteneur php : migrations toujours, fixtures uniquement si la base est vierge ou sur --fixtures. Voir Quand les fixtures sont chargées.
  10. 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:up vient de poser ;
  • elle désigne un worktree sans conf de site — un marqueur périmé. proxy_effective_default_wt le rabat alors sur le dépôt principal si 01-main.caddy existe, 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 add partant de la ref main et non de HEAD. 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 chemin infra/ qui refuse d'être réécrit parce qu'une stack du dépôt principal le monte en lecture seule (castor docker:down d'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.php de 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-only s'applique à la branche courante : le jouer ailleurs avalerait origin/main dans 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 sur main et annoncé par une ligne … git fetch origin main. Sans lui, la comparaison porterait sur une ref distante périmée. Hors ligne, sans remote, sans origin/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é, un switch ou un merge toucherait 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 install est joué systématiquement derrière, et c'est lui seul qui fait foi sur la correspondance entre vendor/ et composer.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 install en 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:up simultanés sur le même worktree ne sont pas un mode supporté ; deux wt:up sur 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 :

  1. Incohérence de chemin — un .env.worktree qui annonce un WT dont le chemin attendu n'existe pas, après un déplacement du worktree ou un changement de KIREXO_WORKTREES_DIR. La cible nomme le chemin attendu et renvoie vers castor wt:list.
  2. Configuration absente — verdict Missing sur 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 -p explicite (wt_compose()) — la commande vise donc le bon projet depuis n'importe quel sous-dossier, là où docker:sh s'en remet à l'auto-découverte de Compose.
  • Elle n'exige ni conteneur vivant, ni stack démarrée. docker:sh est un exec : 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 cibles wt:* 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 :

claude --permission-mode bypassPermissions --resume

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()), donc castor wt:claude -p "…" reste chaînable dans un script, un hook ou la CI. Un 0 de politesse rendrait ces usages inexploitables.
  • L'interactivité vient du TTY, pas du PTY que Castor active par défaut : c'est withTty() — posé par wt_exec_interactive() (castor/worktree.php) — qui rattache le terminal de l'appelant au process et rend l'édition de ligne à la session claude distante. Ce TTY reste conditionnel à Process::isTtySupported(), sans quoi Process::setTty() lèverait TTY mode requires /dev/tty to be read/write dès que STDOUT n'est pas un terminal — donc dans out=$(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 pose CLAUDE_CODE_DISABLE_MOUSE_CLICKS en -e de son docker 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_DIR changé depuis sa création : la cible s'arrête avec le chemin en cause et castor wt:list comme point de reprise ;
  • une configuration absente (verdict Missing) : sortie en 1 avec castor 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) :

docker compose exec -T php curl -sS -o /dev/null --max-time 6 https://packagist.org

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 :

docker inspect -f '{{.RestartCount}}' <conteneur egress-proxy>

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 un rm -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 —.
castor wt:list
castor wt:list --no-stats --no-fetch

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.worktree absent — aucun service déclaré, aucun conteneur : la ligne affiche arrêté ⚠, sans quoi elle serait indiscernable d'un worktree sain à l'arrêt ;
  • nom de projet divergent — la sonde interroge kirexo-<worktree> (le -p des cibles wt:*) pendant que la stack tourne sous le nom déclaré : la ligne affiche arrê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é » :

  1. Garde-fous de perte de travail : git status --porcelain non vide, ou commits non poussés → arrêt, sortie 1, avec le décompte et la mention de --force. Sautés avec --force.
  2. Confirmation interactive, qui rappelle que la base Postgres sera supprimée. Sautée avec --yes. Hors terminal, la cible sort en 1 en donnant castor wt:destroy <ticket>[ --force] --yes.
  3. 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.
  4. Contrôle du projet Compose du worktree — avertissement, jamais un refus : encadré ci-dessous.
  5. docker compose down -v --remove-orphans. En cas d'échec : arrêt immédiat, sortie 1, worktree et .env.worktree conservés — sans eux, plus rien ne permet de retrouver conteneurs, réseau et volumes.
  6. Retrait de la conf proxy + castor proxy:reload. Si le worktree était le worktree par défaut, le repli retombe seul sur main.
  7. Suppression du vhost RabbitMQ du worktree, dans le broker mutualisé que down -v ne touche pas.
  8. Re-parentage des projets Compose singletons — kirexo-shared et kirexo-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.
  9. 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.
  10. git worktree unlock puis git worktree remove, puis git worktree prune.
  11. docker image rm kirexo-dev-local:<worktree> — untag, jamais --force, jamais docker image prune.
  12. 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 :

  ⟳ relance depuis /home/…/kirexo — ce worktree porte le vendor de la commande

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 stream pointant sur vendor/, 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 ps d'un projet échoue, la cible ne conclut pas au silence : elle avertit (Impossible de lister les conteneurs de <projet> — Docker répond-il ?, suivi de Le 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 le ps et 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, conteneur Running et pas Restarting — un conteneur en boucle de redémarrage est Running: true entre deux morts ;
  • un échec fait sortir wt:destroy en 1. 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-proxy coupe les tunnels CONNECT en cours dans tous les worktrees : le conteneur neuf obtient une autre adresse sur kirexo-egress. Un composer install ou 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 le up (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:down est un geste séparé) et la stack mutualisée kirexo-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 -v ne 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).
castor wt:gc
castor wt:gc --days=0 --no-fetch

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-ancestor répond « non ». Un second chemin interroge alors glab sur les MRs mergées de cette branche. Sans lui, aucun worktree ne serait jamais proposé dès qu'une MR est squashée.
  • glab en é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 :

  1. Un tableau Origine | Domaine (baseline = infra/firewall/baseline-domains.txt, local = infra/firewall/whitelist.local.txt) et le total.
  2. 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.
  3. 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 sondes quand 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, /app est le dépôt principal et il n'y a rien à signaler.

  4. Un avertissement listant les lignes de la whitelist locale rejetées pour forme invalide, s'il y en a.

  5. Les valeurs effectives de HTTPS_PROXY et NO_PROXY, plus le rappel que la résolution DNS des noms externes échoue par conception depuis le conteneur.
  6. Trois sondes curl (8 s maximum chacune), affichées OK / 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:status
castor firewall:status --no-probe

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 :

  1. 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> par mktemp + mv atomique. Sort en erreur si l'allowlist produite serait vide.
  2. squid -k reconfigure sur le service egress-proxy du projet kirexo-shared. Squid parse la configuration puis s'envoie un SIGHUP : le processus n'est pas redémarré et les tunnels TLS en cours ne sont pas coupés.
  3. 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 en 1 avec le remède.
castor firewall:reload

« 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 :

docker compose -p kirexo-shared -f compose.shared.yaml up -d --force-recreate egress-proxy

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 :

  1. 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 exit 1 si invalide.
  2. 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.
  3. Dédoublonnage local — idem contre les entrées déjà présentes dans le fichier local.
  4. Append — ajoute la ligne en fin de fichier, commentaires et lignes existantes préservés.
  5. Reload — appelle firewall:reload.
castor firewall:whitelist-add raw.githubusercontent.com

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.

castor firewall:whitelist-remove raw.githubusercontent.com

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 CONNECT en cours sont perdus dans tous les worktrees, un composer install ou 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 :

  1. composer install --no-interaction — paquets PHP dans vendor/.
  2. bin/console importmap:install — assets JavaScript gérés par Symfony Asset Mapper.
  3. bin/console tailwind:build — compilation du CSS Tailwind vers public/.

À lancer après chaque git pull qui modifie composer.lock, importmap.php ou les sources Tailwind (assets/styles/).

castor install

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.

castor reinstall

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 tailwind:build
castor tailwind:build --watch

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 php "--version"
castor php "-r 'echo PHP_INT_MAX;'"

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 console "debug:router"
castor console "cache:clear"

castor composer

Lance une commande Composer dans le conteneur php.

Argument Type Défaut Effet
arg string list Commande Composer à exécuter.
castor composer "require symfony/mailer"
castor composer "update symfony/*"

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 mate
castor mate "list"

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.

castor cache:clear

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 cs:fix
castor cs:fix --dry-run

castor phpstan

Lance PHPStan en analyse statique.

Option Type Défaut Effet
--level int 8 Niveau de sévérité PHPStan.
castor phpstan
castor phpstan --level=9

castor lint

Vérifie la syntaxe et la cohérence du projet en enchaînant quatre sous-étapes :

  1. bin/console lint:twig templates/ — syntaxe des templates Twig.
  2. bin/console lint:yaml config/ — validité des fichiers YAML de configuration.
  3. bin/console lint:container — cohérence du conteneur de services Symfony.
  4. castor lint:shell — shellcheck sur les scripts de infra/, les hooks Claude et la mécanique des skills.
castor lint

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.

castor lint:shell

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.
castor ts:check

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.

castor composer:validate

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.

castor audit

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:schema:validate

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:migrate

castor doctrine:diff

Génère une migration Doctrine à partir du diff entre les entités et le schéma BDD courant.

castor doctrine:diff

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.
castor fixtures:load
castor fixtures:load --append

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:unit
castor test:unit --filter=ArticlePublishedHandlerTest

castor test:e2e

Lance PHPUnit sur la suite e2e (tests Panther, pages uniquement).

Option Type Défaut Effet
--filter string '' Filtre PHPUnit.
castor test:e2e

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:coverage
castor test:coverage --with-e2e
castor test:coverage --html

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.
castor test:bash
castor test:bash --filter supervisor_log_dir

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.

castor test:path-coverage src/Twig/Components/EmailFirstLogin.php --filter=EmailFirstLoginTest

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.
castor messenger:consume
castor messenger:consume async

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 qa

castor test

Enchaîne test:unit → test:bash → test:e2e.

castor test

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é.

castor all

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 :

  1. lint:shell — shellcheck sur infra/, .claude/hooks/ et .claude/skills/*/bin/. Identique à la sous-étape 4 de castor lint, ré-exécutée ici parce que ces scripts sont la cible privilégiée d'édition hôte.
  2. docker compose config -q — valide la fusion compose.yaml + compose.override.yaml. Exit non nul si typo, référence cassée ou type incorrect.
  3. hadolint sur Dockerfile — docker run --rm -i hadolint/hadolint:latest hadolint --no-color --failure-threshold error - < Dockerfile. Seuls les niveaux error / fatal font échouer la cible ; les warning et info (notamment DL4006 hérité de dunglas/symfony-docker) sont remontés à l'écran sans bloquer. L'image hadolint est pullée au premier appel (~3 s), instantanée ensuite.
  4. HEAD HTTP sur les URLs construites depuis les ARG *_VERSION du Dockerfile — Castor et glab uniquement. Node n'est plus sondé : il passe par apk (paquet Alpine nodejs), et un paquet ou une version absente fait échouer apk add au build lui-même — pas besoin de pré-check réseau. Les URLs sont reconstruites par ToolsUpgrader::buildDockerfileUrls() (castor/src/Image/ToolsUpgrader.php, testée unitairement) pour garantir qu'on probe exactement les URLs utilisées par les RUN 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 prochain docker build téléchargerait une page d'erreur HTML, le sha256sum -c rejetterait silencieusement le fichier corrompu, message cryptique. Le check attrape la rupture avant le rebuild.
castor host:check

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.

castor doctor

Depuis l'hôte

  1. Binaires hôte requis : présence de docker, jq, glab et git dans le PATH.
  2. Plugin Docker Compose v2 : docker compose version doit répondre.
  3. État de chaque service de la stack (php, database, redis, rabbitmq, typesense, gotenberg, mailer, docs) : le service doit être présent, son State doit être running et son Health doit être healthy (les services sans healthcheck remontent une chaîne vide pour Health et sont tolérés).
  4. 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 conteneur php — donc sa disparition serait autrement invisible du diagnostic hôte. Exécuté uniquement si php est running.
  5. Migrations Doctrine à jour : bin/console doctrine:migrations:up-to-date doit passer. Ce check n'est exécuté que si le service php est running — 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 :

  1. 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 ni dnsmasq, ni ipset, 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 ».
  2. Binaires castor, glab, node, npm, claude disponibles — résolus dans le PATH via Symfony\Component\Process\ExecutableFinder. Détecte un image:upgrade-tools cassé, un rebuild incomplet ou un PATH corrompu.
  3. whitelist.local.txt parsable (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.
  4. FrankenPHP répond sur http://127.0.0.1 — curl -fsI avec timeout 5 s.
  5. Supervisor frankenphp actif et Supervisor messenger actif — code de retour de infra/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 service php l'ignore volontairement, pour qu'un worker mort ne rende pas le conteneur unhealthy et ne casse pas le préflight de test:e2e.
  6. 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).
  7. Résolution intra-stack — getent hosts pour database, 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).
  8. Migrations Doctrine à jour — bin/console doctrine:migrations:up-to-date, exécuté uniquement si database ré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 compteurs mercure_* 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).

castor monitor

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 :

  1. 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 en 1. Voir l'encadré ci-dessous. --force outrepasse.
  2. Redémarrage sous verrou — infra/supervisor/supervisor.sh restart frankenphp, c'est-à-dire stop puis spawn, sans qu'une autre relance puisse s'intercaler. Le verrou est var/run/supervisor/supervisor.lock, et la relance automatique du healthcheck l'attend aussi. stop arrête toutes les boucles frankenphp découvertes, par /proc et par le PID file : SIGTERM à toutes, puis SIGKILL à la boucle et à ses enfants après le délai de grâce. spawn en relance une seule. Résultat : une seule boucle et un seul frankenphp run par programme, même si le PID file avait disparu. Le journal reste var/log/supervisor/frankenphp.log, lisible à l'identique depuis l'hôte et depuis le conteneur (/app est bind-monté sur la racine du dépôt).
Option Type Défaut Effet
--force flag false Outrepasse la garde des 30 secondes.
castor supervisor:frankenphp-restart
castor supervisor:frankenphp-restart --force

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 :

  1. Gracieux (défaut) — bin/console messenger:stop-workers pose un drapeau daté dans le pool cache.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 en 0, et la boucle le relance après CLEAN_DELAY (1 s). Le succès est prouvé par le changement du PID dans var/run/supervisor/messenger.child.pid — pas par le code de retour de messenger:stop-workers, qui réussit même si personne n'écoute. Patience : 30 s.
  2. --hard — infra/supervisor/supervisor.sh restart messenger : la boucle reçoit SIGTERM, escalade en SIGKILL aprè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.
castor supervisor:worker-restart
castor supervisor:worker-restart --hard

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.

castor image:check-tools

É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).
castor image:refresh

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 container et en ci, la ligne rend · SKIP avec 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 SKIP ne fait jamais virer un blocking au rouge : le verdict du profil container est inchangé ;
  • docker absent 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 — un SKIP muet est exactement le mode de panne que ce contrat élimine ;
  • la sévérité de C2 au contrat reste blocking : en profil container, un socket joignable est un ✗ KO dur, qui fait sortir la commande en 1 et arme le gate SessionStart.

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 KO explicite. infra/dod/prod-smoke.sh a été perdu avec var/claude : la sonde le dit dans ces termes (« a été PERDU avec var/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 --from porte compose.worktree.yaml. Si ce n'est pas le cas — c'est encore le cas de main tant que l'étape n'est pas mergée —, elle bascule d'elle-même en --skip-lifecycle et le dit : sans cette garde pré-vol, wt:up refuserait 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.
castor dod:tls ticket-215 ticket-220

Ce que la sonde mesure, pour chaque URL rendue par wt_urls() (infra/worktree/wt.lib.sh) :

  • le SAN servi — un DNS:*.localhost signale un repli sur le joker, donc un avertissement à venir ; un DNS:<nom exact> prouve que Caddy a émis sa feuille ;
  • le ssl_verify_result de curl, 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 502 sous 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]).
castor dod:clean              # dod-a et dod-b
castor dod:clean dod-a        # un seul

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).
castor claude:space
castor claude:space --full

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.

castor docs:build

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 :

  1. copie site/, sauf site/data/ ;
  2. copie les assets du design system depuis le dépôt (cf. Arborescence de var/site-build/) ;
  3. remplace les marqueurs kirexo:* de chaque page .html (version, date, mémoire, hébergeur, statuts) ;
  4. valide site/data/statuts.json contre les plugins réellement déclarés dans config/bundles.php ;
  5. calcule l'empreinte sha256 du script anti-flash et écrit _headers et .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é :

<!-- kirexo:<nom>:debut -->valeur remplacée au build<!-- kirexo:<nom>:fin -->

<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 fin sans debut correspondant, ou un debut jamais 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&apos;un site public pour ses textes, sur l&apos;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 :

{"version": "0.0.2", "date": "2026-10-02"}
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'état disponible. Le site ne peut pas taire un plugin livré ;
  • une entrée ne cite en plugin qu'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 champ plugin ;
  • un même plugin n'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 .html porte 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 attributs style="…", et script-src sans 'unsafe-inline' interdit les gestionnaires on*="…".

É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.

castor site:build && castor site:check

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éfixe N. est retiré ; une ligne ### Titre sans 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 h3 enfants directs des li de ol.steps. La numérotation vient de la liste, d'où l'absence de préfixe N. 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 (&quot; 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 :

Thème dark non appliqué par Chromium (data-theme lu : absent) — l'audit axe serait trompeur.

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 :

  1. les arguments (--provider est obligatoire au niveau du script, la cible le fournit toujours) ;
  2. la garde de contexte ;
  3. la présence du dossier, de index.html et du fichier d'en-têtes du fournisseur (_headers pour deploybase, .htaccess pour ovh) ;
  4. si une version est attendue : elle est semver, et le marqueur kirexo:version de index.html porte exactement cette valeur ;
  5. les variables requises, nommées sans leur valeur ;
  6. les outils : curl, jq, sha256sum, stat, find, seq, plus lftp pour ovh ;
  7. pour ovh : OVH_FTP_REMOTE_DIR n'est ni vide, ni /, ni ., ni .., et ne contient pas de segment .. (garde de mirror --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_….

  1. Manifeste : {"branch", "label", "files": [{"path", "size", "hash"}]}, avec branch = DEPLOYBASE_BRANCH (main par défaut), label = kirexo X.Y.Z, la taille en octets et le sha256 de chaque fichier.
  2. Ouverture de session : POST /projects/{id}/uploads, en-tête Idempotency-Key: kirexo-site-<CI_JOB_ID>. Réponse 201 attendue, avec upload_id, deployment_id et la liste missing. Les entrées de missing (chemins ou hashes sha256) sont traduites en chemins du manifeste ; une entrée inconnue est une erreur.
  3. Envoi des seuls fichiers manquants : PUT /uploads/{upload_id}/files/{chemin encodé}, corps brut, en-tête X-Upload-Hash, 3 tentatives. Réponse 204 attendue.
  4. Finalisation : POST /uploads/{upload_id}/finalize, réponse 200.
  5. Attente : GET /deployments/{id} toutes les 3 s jusqu'à deployed, borné par SITE_DEPLOY_POLL_TIMEOUT. failed ou cancelled : échec, avec la catégorie d'erreur.
  6. Promotion : POST /projects/{id}/promote avec {"deployment_id"}, réponse 200 dont live_deployment_id doit 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.

  1. Validation de site/data/statuts.json par StatutsValidator::validateProject(), la même que celle de site:build (cf. Échecs et remèdes).
  2. Validation de la version et de la date par App\Castor\Site\SiteRefresher (castor/src/Site/SiteRefresher.php).
  3. É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.

{
    "version": "0.2.0",
    "date": "2026-10-03"
}
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.

castor site:context --bump=minor
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 (un 01.0.0 poussé à la main est ignoré) ;
  • les anciens tags horodatés YYYYMMDDHHMM et 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.1 quel 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.
castor tag:create
castor tag:create --name 0.1.0
castor tag:create --force

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).