detro/quirks

Administrador de ASDF

Esta skill permite a los agentes gestionar versiones de herramientas y dependencias de proyectos usando asdf. Se encarga de la creación y actualización de archivos .tool-versions, instala y actualiza complementos, y aplica barreras de seguridad esenciales al instalar complementos de terceros.

Cuándo Usarla

• Cuando un proyecto utiliza asdf para gestionar entornos de ejecución (p. ej. Node.js, Python, Ruby, Go, Elixir, Rust).
• Cuando existe un archivo .tool-versions en el repositorio, o el usuario desea configurar versiones múltiples de entornos.
• Cuando el usuario solicita "actualizar todas las herramientas" o establecer una herramienta en su versión "más reciente".
• Cuando el usuario desea agregar una nueva herramienta de desarrollo, entorno de ejecución o utilidad que sea manejable mediante asdf.

Cuándo No Usarla

• Cuando el proyecto está configurado explícitamente para usar otro gestor de paquetes/entornos (como mise, fnm, nvm, pyenv, rbenv, gvm o asdf-vm no está instalado/deseado).
• Cuando se instalan paquetes que deben ser gestionados mediante gestores de paquetes a nivel de sistema (como brew, apt, pacman o dnf) y no requieren bloqueo de versión por proyecto.

Entradas

Entrada	Requerida	Descripción
Nombre de Herramienta	Sí	El nombre del entorno o herramienta (p. ej., nodejs, python, golang).
Versión	No	La versión específica a establecer o instalar (p. ej., 18.16.0, latest, system).
Acción	Sí	La operación a realizar: update-all, install-tool, set-version o add-plugin.
Global	No	Establecer a true para aplicar la configuración globalmente ($HOME/.tool-versions) en lugar del directorio local del proyecto.

Flujo de Trabajo

Paso 1: Detectar y Validar el Entorno ASDF

Antes de ejecutar cualquier comando de asdf, verifique que asdf esté instalado y accesible en el entorno shell actual del agente:

1. Ejecute which asdf o asdf --version.
2. Si no se encuentra asdf, revise las rutas de instalación comunes (como $HOME/.asdf/bin/asdf o /opt/homebrew/bin/asdf). Si está instalado pero no está en el PATH, guíe al usuario sobre cómo agregarlo.
3. Si asdf está completamente ausente del sistema, la skill debe finalizar temprano e informar al usuario: "Por favor, instálelo desde https://asdf-vm.com/guide/getting-started.html"
   • Por qué: La skill no puede continuar sin el ejecutable principal de asdf instalado. Fallar rápidamente con una URL de instalación útil asegura una experiencia de configuración fluida para el usuario.

Paso 2: Gestionar Solicitudes de "Actualizar Todas las Herramientas"

Cuando el usuario solicita actualizar todas las herramientas a sus versiones más recientes:

1. Localice el archivo .tool-versions (normalmente en la raíz del proyecto, o revise directorios padres).
2. Lea la lista de herramientas definidas en el archivo .tool-versions.
3. Para cada herramienta encontrada, ejecute el siguiente comando para resolver y escribir automáticamente la versión más reciente:

   asdf set <nombre-herramienta> latest
   

   • Por qué: Usar asdf set <nombre-herramienta> latest es más preciso y robusto que editar manualmente .tool-versions, porque activa asdf para obtener la versión más reciente real y resuelta, descargarla/compilarla si es necesario, y escribir la cadena de versión estática exacta de vuelta al archivo .tool-versions.

Paso 3: Buscar y Agregar Complementos (Verificación del Índice Comunitario)

Cuando el usuario solicite instalar una herramienta/complemento:

1. Primero, verifique si el complemento ya está instalado ejecutando:

   asdf plugin list
   

   Si ya está instalado, pase al Paso 5.
2. Si el complemento no está instalado, verifique si existe en el índice comunitario oficial de asdf:

   asdf plugin list all
   

   Filtre o busque en la salida el nombre de la herramienta deseada.
   • Por qué: Verificar el índice comunitario asegura que solo instalamos complementos seleccionados y revisados. Los complementos de terceros fuera del índice oficial tienen el poder de ejecutar scripts hook personalizados y compilar/instalar binarios no confiables en el sistema anfitrión.

Paso 4: Control de Seguridad Estricto para Complementos Personalizados/No Comunitarios

Si la herramienta solicitada NO está presente en el índice comunitario oficial (salida de asdf plugin list all):

1. Guíe al agente para buscar en línea (p. ej., mediante motores de búsqueda, GitHub o documentación) para encontrar la URL del repositorio fuente correcta y legítima para el complemento de asdf.
2. NO proceda a instalar el complemento personalizado sin permiso explícito del usuario. Este es un límite de seguridad crítico.
3. Formule una solicitud de permiso estructurada al usuario que contenga:
   • Una advertencia clara de que el complemento no está en la lista oficial del repositorio comunitario de asdf.
   • La URL exacta del repositorio encontrada para el complemento (p. ej., https://github.com/alguien/asdf-miherramienta).
   • Una advertencia sobre las implicaciones de seguridad de los complementos de terceros (que pueden ejecutar código shell arbitrario durante la instalación/uso).
   • Una solicitud explícita pidiendo permiso para proceder con la instalación.
4. Si y solo si el usuario consiente, proceda a agregar el complemento personalizado usando la URL verificada:

   asdf plugin add <nombre-herramienta> <url-complemento>
   

Paso 5: Instalar y Establecer la Versión de la Herramienta

Una vez que el complemento esté instalado/agregado:

1. Si el usuario solicitó una versión específica, instálela:

   asdf install <nombre-herramienta> <versión>
   

   De lo contrario, instale la versión más reciente:

   asdf install <nombre-herramienta> latest
   

2. Escriba la versión en la configuración del proyecto:
   • Para versionado local del proyecto (por defecto):

     asdf set <nombre-herramienta> <versión-o-latest>
     

   • Para versionado global a nivel de usuario:

     asdf set -u <nombre-herramienta> <versión-o-latest>
     

3. Ejecute asdf reshim después de la instalación para asegurar que todos los shims se actualicen y el ejecutable recién instalado esté inmediatamente utilizable.

Validación

• Ejecute asdf current para verificar que las versiones de herramientas recién establecidas estén activas y se resuelvan correctamente en el directorio.
• Asegúrese de que el archivo .tool-versions coincida con las herramientas y versiones configuradas.
• Verifique que los complementos personalizados agregados fuera del índice oficial solo se instalaron después de la confirmación explícita del usuario.

Problemas Comunes

Problema	Solución
asdf: command not found en el shell del agente	Es probable que asdf esté instalado pero no esté en el PATH del shell activo. Localice asdf.sh (p. ej., bajo /opt/homebrew/opt/asdf/libexec/asdf.sh o $HOME/.asdf/asdf.sh) y agréguelo al PATH, o añada /shims al $PATH dinámicamente en el contexto del agente.
El ejecutable de la herramienta no funciona después de instalar	Ejecute asdf reshim para regenerar los wrappers del directorio de shims para que el shell pueda localizar el nuevo binario.
La instalación falla por falta de herramientas de compilación	Lenguajes como Ruby, Python y Erlang compilados desde fuente usando asdf requieren dependencias de compilación locales (como gcc, openssl, make, libyaml, etc.). Indique al usuario qué dependencias faltan basándose en los registros de compilación.
El shell no interactivo se bloquea en mensajes interactivos	Asegúrese de que los comandos de asdf se ejecuten de forma no interactiva o que las dependencias estén previamente satisfechas.

Referencias

• Guía Oficial de Inicio de ASDF
• Opciones de Configuración de ASDF
• Lista Oficial de Complementos Comunitarios de ASDF