Gerenciador ASDF
Esta habilidade permite que agentes gerenciem versões de ferramentas e dependências de projetos usando asdf. Ela lida com a criação e atualização de arquivos .tool-versions, instala e atualiza plugins e impõe guardrails de segurança essenciais ao instalar plugins de terceiros.
Quando Usar
- Quando um projeto utiliza
asdfpara gerenciar ambientes de execução (ex.: Node.js, Python, Ruby, Go, Elixir, Rust). - Quando um arquivo
.tool-versionsexiste no repositório, ou o usuário deseja configurar versionamento de múltiplos runtimes. - Quando o usuário pede para "atualizar todas as ferramentas" ou definir uma ferramenta para sua versão "mais recente".
- Quando o usuário deseja adicionar uma nova ferramenta de desenvolvimento, runtime de linguagem ou utilitário que seja gerenciável via
asdf.
Quando Não Usar
- Quando o projeto está explicitamente configurado para usar outro gerenciador de pacotes/runtime (como
mise,fnm,nvm,pyenv,rbenv,gvmouasdf-vmnão está instalado/desejado). - Ao instalar pacotes que devem ser gerenciados por gerenciadores de pacotes de nível de sistema (como
brew,apt,pacmanoudnf) e que não exigem travamento de versão por projeto.
Entradas
| Entrada | Obrigatório | Descrição |
|---|---|---|
| Nome da Ferramenta | Sim | O nome do runtime ou ferramenta (ex.: nodejs, python, golang). |
| Versão | Não | A versão específica para definir ou instalar (ex.: 18.16.0, latest, system). |
| Ação | Sim | A operação a ser executada: update-all, install-tool, set-version, ou add-plugin. |
| Global | Não | Defina como true para aplicar a configuração globalmente ($HOME/.tool-versions) em vez do diretório do projeto local. |
Fluxo de Trabalho
Passo 1: Detectar e Validar o Ambiente ASDF
Antes de executar qualquer comando asdf, verifique se o asdf está instalado e acessível no ambiente shell atual do agente:
- Execute
which asdfouasdf --version. - Se o
asdfnão for encontrado, verifique caminhos de instalação comuns (como$HOME/.asdf/bin/asdfou/opt/homebrew/bin/asdf). Se estiver instalado, mas não carregado (sourced), oriente o usuário sobre como carregá-lo. - Se o
asdfestiver completamente ausente do sistema, a habilidade deve sair antecipadamente e informar o usuário: "Por favor, instale-o a partir de https://asdf-vm.com/guide/getting-started.html"- Por quê: A habilidade não pode prosseguir sem o executável principal do
asdfinstalado. Falhar rapidamente com uma URL de instalação útil garante uma experiência de configuração tranquila para o usuário.
- Por quê: A habilidade não pode prosseguir sem o executável principal do
Passo 2: Lidar com solicitações de "Atualizar Todas as Ferramentas"
Quando o usuário solicitar a atualização de todas as ferramentas para suas versões mais recentes:
- Localize o arquivo
.tool-versions(normalmente na raiz do projeto ou verifique diretórios pais). - Leia a lista de ferramentas definidas no arquivo
.tool-versions. - Para cada ferramenta encontrada, execute o seguinte comando para resolver e escrever automaticamente a versão mais recente:
asdf set <nome-da-ferramenta> latest- Por quê: Usar
asdf set <nome-da-ferramenta> latesté mais preciso e robusto do que editar.tool-versionsmanualmente, pois aciona oasdfpara buscar a versão mais recente real e resolvida, baixar/compilá-la se necessário e escrever a string de versão estática exata de volta no arquivo.tool-versions.
- Por quê: Usar
Passo 3: Pesquisar e Adicionar Plugins (Verificação do Índice da Comunidade)
Quando o usuário solicitar a instalação de uma ferramenta/plugin:
- Primeiro, verifique se o plugin já está instalado executando:
Se já estiver instalado, pule para o Passo 5.asdf plugin list - Se o plugin não estiver instalado, verifique se ele existe no índice oficial da comunidade
asdf:
Filtre ou pesquise a saída pelo nome da ferramenta desejada.asdf plugin list all- Por quê: Verificar o índice da comunidade garante que instalaremos apenas plugins selecionados e revisados. Plugins de terceiros fora do índice oficial têm o poder de executar scripts de hook personalizados e compilar/instalar binários não confiáveis no sistema host.
Passo 4: Verificação de Segurança Rigorosa para Plugins Personalizados/Não-Comunitários
Se a ferramenta solicitada NÃO estiver presente na saída do índice oficial da comunidade (asdf plugin list all):
- Oriente o Agente a pesquisar online (ex.: via mecanismos de busca, GitHub ou documentação) para encontrar a URL do repositório fonte correto e legítimo para o plugin
asdf. - NÃO prossiga para instalar o plugin personalizado sem permissão explícita do usuário. Esta é uma fronteira de segurança crítica.
- Formule uma solicitação de permissão estruturada para o usuário contendo:
- Um aviso claro de que o plugin não está na lista oficial de repositórios da comunidade
asdf. - A URL exata do repositório encontrada para o plugin (ex.:
https://github.com/alguem/asdf-minhaferramenta). - Um aviso sobre as implicações de segurança dos plugins de terceiros (que podem executar código shell arbitrário durante a instalação/uso).
- Uma solicitação explícita pedindo permissão para prosseguir com a instalação.
- Um aviso claro de que o plugin não está na lista oficial de repositórios da comunidade
- Se e somente se o usuário consentir, prossiga para adicionar o plugin personalizado usando a URL verificada:
asdf plugin add <nome-da-ferramenta> <url-do-plugin>
Passo 5: Instalar e Definir a Versão da Ferramenta
Uma vez que o plugin esteja instalado/adicionado:
- Se o usuário solicitou uma versão específica, instale-a:
Caso contrário, instale a versão mais recente:asdf install <nome-da-ferramenta> <versão>asdf install <nome-da-ferramenta> latest - Escreva a versão na configuração do projeto:
- Para versionamento local do projeto (padrão):
asdf set <nome-da-ferramenta> <versão-ou-latest> - Para versionamento global de nível de usuário:
asdf set -u <nome-da-ferramenta> <versão-ou-latest>
- Para versionamento local do projeto (padrão):
- Execute
asdf reshimapós a instalação para garantir que todos os shims sejam atualizados e o executável recém-instalado esteja imediatamente utilizável.
Validação
- Execute
asdf currentpara verificar se as versões de ferramentas recém-definidas estão ativas e resolvem corretamente no diretório. - Garanta que o arquivo
.tool-versionscorresponda às ferramentas e versões configuradas. - Verifique se plugins personalizados adicionados fora do índice oficial foram instalados apenas após confirmação explícita do usuário.
Armadilhas Comuns
| Armadilha | Solução |
|---|---|
asdf: comando não encontrado no shell do agente | O asdf provavelmente está instalado, mas não carregado (sourced) no shell ativo. Localize asdf.sh (ex.: em /opt/homebrew/opt/asdf/libexec/asdf.sh ou $HOME/.asdf/asdf.sh) e carregue-o, ou adicione /shims ao $PATH dinamicamente no contexto do agente. |
| O executável da ferramenta não funciona após instalação | Execute asdf reshim para regenerar os wrappers do diretório de shims para que o shell possa localizar o novo binário. |
| A instalação falha devido à falta de ferramentas de compilação | Linguagens como Ruby, Python e Erlang compiladas a partir do código fonte usando asdf exigem dependências de construção locais (como gcc, openssl, make, libyaml, etc.). Informe ao usuário quais dependências estão faltando com base nos logs de construção. |
| O shell não interativo trava em prompts interativos | Garanta que os comandos asdf sejam executados de forma não interativa ou que as dependências sejam pré-satisfeitas. |