detro/quirks

Gestionnaire ASDF

Cette compétence permet aux agents de gérer les versions des outils et les dépendances d'un projet en utilisant asdf. Elle gère la création et la mise à jour des fichiers .tool-versions, installe et met à jour les plugins, et impose des garde-fous de sécurité essentiels lors de l'installation de plugins tiers.

Quand l'utiliser

• Lorsqu'un projet utilise asdf pour gérer les environnements d'exécution (par exemple Node.js, Python, Ruby, Go, Elixir, Rust).
• Lorsqu'un fichier .tool-versions existe dans le dépôt, ou que l'utilisateur souhaite configurer un versionnement multi-exécutions.
• Lorsque l'utilisateur demande de « mettre à jour tous les outils » ou de définir un outil à sa version « la plus récente ».
• Lorsque l'utilisateur souhaite ajouter un nouvel outil de développement, un environnement d'exécution de langage ou un utilitaire gérable via asdf.

Quand ne pas l'utiliser

• Lorsque le projet est explicitement configuré pour utiliser un autre gestionnaire de paquets/exécutions (comme mise, fnm, nvm, pyenv, rbenv, gvm ou asdf-vm n'est pas installé/souhaité).
• Lors de l'installation de paquets qui devraient être gérés par des gestionnaires de paquets système (comme brew, apt, pacman ou dnf) et qui ne nécessitent pas de verrouillage de version par projet.

Entrées

Entrée	Requis	Description
Nom de l'outil	Oui	Le nom de l'exécution ou de l'outil (par exemple nodejs, python, golang).
Version	Non	La version spécifique à définir ou installer (par exemple 18.16.0, latest, system).
Action	Oui	L'opération à effectuer : update-all, install-tool, set-version ou add-plugin.
Global	Non	Définir sur true pour appliquer la configuration globalement ($HOME/.tool-versions) au lieu du répertoire local du projet.

Flux de travail

Étape 1 : Détecter et valider l'environnement ASDF

Avant d'exécuter toute commande asdf, vérifiez que asdf est installé et accessible dans l'environnement shell actuel de l'agent :

1. Exécutez which asdf ou asdf --version.
2. Si asdf n'est pas trouvé, vérifiez les chemins d'installation courants (tels que $HOME/.asdf/bin/asdf ou /opt/homebrew/bin/asdf). S'il est installé mais pas sourcé, guidez l'utilisateur sur la façon de le sourcer.
3. Si asdf est complètement absent du système, la compétence doit s'arrêter immédiatement et informer l'utilisateur : "Veuillez l'installer depuis https://asdf-vm.com/guide/getting-started.html"
   • Pourquoi : La compétence ne peut pas continuer sans l'exécutable principal asdf installé. Échouer rapidement avec une URL d'installation utile garantit une expérience de configuration fluide pour l'utilisateur.

Étape 2 : Gérer les demandes de « Mise à jour de tous les outils »

Lorsque l'utilisateur demande de mettre à jour tous les outils vers leurs dernières versions :

1. Localisez le fichier .tool-versions (généralement à la racine du projet, ou vérifiez les répertoires parents).
2. Lisez la liste des outils définis dans le fichier .tool-versions.
3. Pour chaque outil trouvé, exécutez la commande suivante pour résoudre et écrire automatiquement la dernière version :

   asdf set <nom-outil> latest
   

   • Pourquoi : Utiliser asdf set <nom-outil> latest est plus précis et robuste que de modifier manuellement .tool-versions, car cela déclenche asdf pour récupérer la version réelle, résolue et disponible la plus récente, la télécharger/compiler si nécessaire, et écrire la chaîne de version statique exacte dans le fichier .tool-versions.

Étape 3 : Rechercher et ajouter des plugins (vérification de l'index de la communauté)

Lorsque l'utilisateur demande d'installer un outil/plugin :

1. Vérifiez d'abord si le plugin est déjà installé en exécutant :

   asdf plugin list
   

   S'il est déjà installé, passez à l'Étape 5.
2. Si le plugin n'est pas installé, vérifiez s'il existe dans l'index officiel de la communauté asdf :

   asdf plugin list all
   

   Filtrez ou recherchez la sortie pour le nom de l'outil souhaité.
   • Pourquoi : Vérifier l'index de la communauté garantit que nous n'installons que des plugins organisés et révisés. Les plugins tiers en dehors de l'index officiel ont le pouvoir d'exécuter des scripts de hook personnalisés et de compiler/installer des binaires non fiables sur le système hôte.

Étape 4 : Vérification de sécurité stricte pour les plugins personnalisés/non communautaires

Si l'outil demandé n'est PAS présent dans l'index officiel de la communauté (sortie de asdf plugin list all) :

1. Guidez l'agent pour rechercher en ligne (par exemple via des moteurs de recherche, GitHub ou la documentation) afin de trouver l'URL correcte du dépôt source légitime pour le plugin asdf.
2. NE procédez PAS à l'installation du plugin personnalisé sans autorisation explicite de l'utilisateur. Il s'agit d'une frontière de sécurité critique.
3. Formulez une demande d'autorisation structurée à l'utilisateur contenant :
   • Un avertissement clair indiquant que le plugin n'est pas dans la liste officielle des dépôts communautaires asdf.
   • L'URL exacte du dépôt trouvé pour le plugin (par exemple https://github.com/someone/asdf-mytool).
   • Un avertissement concernant les implications de sécurité des plugins tiers (qui peuvent exécuter du code shell arbitraire lors de l'installation/l'utilisation).
   • Une demande explicite d'autorisation de procéder à l'installation.
4. Si et seulement si l'utilisateur consent, procédez à l'ajout du plugin personnalisé en utilisant l'URL vérifiée :

   asdf plugin add <nom-outil> <url-plugin>
   

Étape 5 : Installer et définir la version de l'outil

Une fois le plugin installé/ajouté :

1. Si l'utilisateur a demandé une version spécifique, installez-la :

   asdf install <nom-outil> <version>
   

   Sinon, installez la dernière version :

   asdf install <nom-outil> latest
   

2. Écrivez la version dans la configuration du projet :
   • Pour le versionnement local du projet (par défaut) :

     asdf set <nom-outil> <version-ou-latest>
     

   • Pour le versionnement global au niveau utilisateur :

     asdf set -u <nom-outil> <version-ou-latest>
     

3. Exécutez asdf reshim après l'installation pour garantir que tous les shims sont mis à jour et que l'exécutable nouvellement installé est immédiatement utilisable.

Validation

• Exécutez asdf current pour vérifier que les versions d'outils nouvellement définies sont actives et se résolvent correctement dans le répertoire.
• Assurez-vous que le fichier .tool-versions correspond aux outils et versions configurés.
• Vérifiez que les plugins personnalisés ajoutés en dehors de l'index officiel n'ont été installés qu'après confirmation explicite de l'utilisateur.

Pièges courants

Piège	Solution
asdf: command not found dans le shell de l'agent	asdf est probablement installé mais pas sourcé dans le shell actif. Localisez asdf.sh (par exemple sous /opt/homebrew/opt/asdf/libexec/asdf.sh ou $HOME/.asdf/asdf.sh) et sourcez-le, ou ajoutez /shims à $PATH dynamiquement dans le contexte de l'agent.
L'exécutable de l'outil ne fonctionne pas après l'installation	Exécutez asdf reshim pour régénérer les wrappers du répertoire shims afin que le shell puisse localiser le nouveau binaire.
L'installation échoue en raison d'outils de compilation manquants	Les langages comme Ruby, Python et Erlang compilés à partir des sources en utilisant asdf nécessitent des dépendances de construction locales (comme gcc, openssl, make, libyaml, etc.). Indiquez à l'utilisateur quelles dépendances manquent en vous basant sur les journaux de construction.
Le shell non interactif bloque sur les invites interactives	Assurez-vous que les commandes asdf sont exécutées de manière non interactive ou que les dépendances sont pré-satisfaites.

Références

• Guide officiel de démarrage ASDF
• Options de configuration ASDF
• Liste officielle des plugins communautaires ASDF