asdf 매니저

asdf 매니저은(는) 무엇을 하나요?

이 스킬은 에이전트가 asdf를 사용하여 프로젝트 도구 버전과 의존성을 관리할 수 있게 합니다. .tool-versions 파일을 생성 및 업데이트하고, 플러그인을 설치 및 업데이트하며, 서드파티 플러그인 설치 시 필수 보안 가드레일을 적용합니다.

사용 시기

• 프로젝트에서 asdf를 사용하여 런타임 환경(Node.js, Python, Ruby, Go, Elixir, Rust 등)을 관리할 때
• 리포지토리에 .tool-versions 파일이 존재하거나, 사용자가 멀티 런타임 버전 관리를 설정하려고 할 때
• 사용자가 "모든 도구 업데이트" 또는 특정 도구를 "최신" 버전으로 설정하라고 요청할 때
• asdf로 관리할 수 있는 새로운 개발 도구, 언어 런타임, 또는 유틸리티를 추가하려고 할 때

사용하지 말아야 할 시기

• 프로젝트가 명시적으로 다른 패키지/런타임 매니저(mise, fnm, nvm, pyenv, rbenv, gvm 또는 asdf-vm이 설치/사용되지 않음)를 사용하도록 설정된 경우
• 시스템 수준 패키지 매니저(brew, apt, pacman, dnf)로 관리해야 하고 프로젝트별 버전 잠금이 필요하지 않은 패키지를 설치할 때

입력값

입력값	필수	설명
도구 이름	예	런타임 또는 도구 이름 (예: nodejs, python, golang).
버전	아니오	설정하거나 설치할 특정 버전 (예: 18.16.0, latest, system).
작업	예	수행할 작업: update-all, install-tool, set-version 또는 add-plugin.
전역	아니오	true로 설정하면 로컬 프로젝트 디렉토리 대신 전역($HOME/.tool-versions)에 설정을 적용합니다.

워크플로우

1단계: ASDF 환경 감지 및 검증

asdf 명령을 실행하기 전에 에이전트의 현재 셸 환경에 asdf가 설치되어 있고 접근 가능한지 확인하세요:

1. which asdf 또는 asdf --version을 실행합니다.
2. asdf를 찾을 수 없는 경우, 일반적인 설치 경로($HOME/.asdf/bin/asdf 또는 /opt/homebrew/bin/asdf)를 확인합니다. 설치되어 있지만 소싱되지 않은 경우, 사용자에게 소싱 방법을 안내합니다.
3. 시스템에 asdf가 완전히 없는 경우, 스킬은 조기에 종료하고 사용자에게 알려야 합니다: "https://asdf-vm.com/guide/getting-started.html 에서 설치해주세요."
   • 이유: asdf 코어 실행 파일이 설치되지 않으면 스킬이 진행될 수 없습니다. 도움이 되는 설치 URL과 함께 빠르게 실패 처리하면 사용자 설정 경험이 원활해집니다.

2단계: "모든 도구 업데이트" 요청 처리

사용자가 모든 도구를 최신 버전으로 업데이트하도록 요청한 경우:

1. .tool-versions 파일을 찾습니다(일반적으로 프로젝트 루트에 있거나 상위 디렉토리를 확인합니다).
2. .tool-versions 파일에 정의된 도구 목록을 읽습니다.
3. 각 도구에 대해 다음 명령을 실행하여 최신 버전을 자동으로 확인하고 작성합니다:

   asdf set <tool-name> latest
   

   • 이유: asdf set <tool-name> latest를 사용하는 것이 .tool-versions를 수동으로 편집하는 것보다 더 정확하고 견고합니다. 이 명령은 asdf가 실제 확인 가능한 최신 버전을 가져오고, 필요시 다운로드/컴파일한 후, 정확한 정적 버전 문자열을 .tool-versions 파일에 다시 쓰도록 합니다.

3단계: 플러그인 검색 및 추가 (커뮤니티 인덱스 확인)

사용자가 도구/플러그인 설치를 요청한 경우:

1. 먼저 다음 명령으로 플러그인이 이미 설치되어 있는지 확인합니다:

   asdf plugin list
   

   이미 설치되어 있으면 5단계로 건너뜁니다.
2. 플러그인이 설치되어 있지 않으면, 공식 asdf 커뮤니티 인덱스에 존재하는지 확인합니다:

   asdf plugin list all
   

   출력에서 원하는 도구 이름을 필터링하거나 검색합니다.
   • 이유: 커뮤니티 인덱스를 확인하면 큐레이션되고 검토된 플러그인만 설치할 수 있습니다. 공식 인덱스 외부의 서드파티 플러그인은 호스트 시스템에서 커스텀 훅 스크립트를 실행하고 신뢰할 수 없는 바이너리를 컴파일/설치할 수 있는 권한을 갖습니다.

4단계: 커스텀/비커뮤니티 플러그인에 대한 엄격한 보안 검사

요청한 도구가 공식 커뮤니티 인덱스(asdf plugin list all 출력)에 없는 경우:

1. 에이전트가 온라인 검색(검색 엔진, GitHub, 문서 등)을 통해 asdf 플러그인의 올바른 합법적인 소스 리포지토리 URL을 찾도록 안내합니다.
2. 사용자의 명시적 허가 없이 커스텀 플러그인을 설치하지 마십시오. 이는 중요한 보안 경계입니다.
3. 사용자에게 구조화된 권한 요청을 작성하여 다음을 포함합니다:
   • 플러그인이 공식 asdf 커뮤니티 리포지토리 목록에 없음을 명확히 경고.
   • 찾은 플러그인의 정확한 리포지토리 URL (예: https://github.com/someone/asdf-mytool).
   • 서드파티 플러그인의 보안 영향에 대한 경고 (설치/사용 중 임의의 셸 코드를 실행할 수 있음).
   • 설치를 진행할지 묻는 명시적 프롬프트.
4. 사용자가 동의한 경우에만 확인된 URL을 사용하여 커스텀 플러그인 추가를 진행합니다:

   asdf plugin add <tool-name> <plugin-url>
   

5단계: 도구 버전 설치 및 설정

플러그인이 설치/추가되면:

1. 사용자가 특정 버전을 요청한 경우 설치합니다:

   asdf install <tool-name> <version>
   

   그렇지 않으면 최신 버전을 설치합니다:

   asdf install <tool-name> latest
   

2. 프로젝트 설정에 버전을 기록합니다:
   • 로컬 프로젝트 버전 관리 (기본값):

     asdf set <tool-name> <version-or-latest>
     

   • 전역 사용자 수준 버전 관리:

     asdf set -u <tool-name> <version-or-latest>
     

3. 설치 후 asdf reshim을 실행하여 모든 심이 업데이트되고 새로 설치된 실행 파일을 즉시 사용할 수 있도록 합니다.

검증

• asdf current를 실행하여 새로 설정된 도구 버전이 활성화되고 해당 디렉토리에서 올바르게 확인되는지 확인합니다.
• .tool-versions 파일이 구성된 도구와 버전과 일치하는지 확인합니다.
• 공식 인덱스 외부에 추가된 커스텀 플러그인이 사용자의 명시적 확인 후에만 설치되었는지 확인합니다.

일반적인 문제

문제	해결 방법
에이전트 셸에서 asdf: command not found	asdf가 설치되었지만 활성 셸에 소싱되지 않은 것입니다. asdf.sh (예: /opt/homebrew/opt/asdf/libexec/asdf.sh 또는 $HOME/.asdf/asdf.sh)를 찾아 소싱하거나, 에이전트 컨텍스트에서 /shims를 $PATH에 동적으로 추가합니다.
설치 후 도구 실행 파일이 실행되지 않음	asdf reshim을 실행하여 심 디렉토리 래퍼를 재생성하면 셸이 새 바이너리를 찾을 수 있습니다.
컴파일 도구 누락으로 설치 실패	Ruby, Python, Erlang 등의 언어는 asdf로 소스에서 컴파일할 때 gcc, openssl, make, libyaml 등의 로컬 빌드 의존성이 필요합니다. 빌드 로그를 기반으로 누락된 의존성을 사용자에게 알려줍니다.
비대화형 셸이 대화형 프롬프트에서 멈춤	asdf 명령을 비대화형으로 실행하거나 의존성을 미리 충족시켜야 합니다.

참고 자료

• ASDF 공식 시작 가이드
• ASDF 설정 옵션
• ASDF 공식 커뮤니티 플러그인 목록