대상: pnpm/pnpm
이슈: pnpm/pnpm#9191
풀 리퀘스트 (Pull request): pnpm/pnpm#12841
필드 랩 (Field Lab) 기록: pnpm #9191

이번 필드 테스트는 설정 상태 (setup state)에 관한 것이었으나, 단순히 "환경 변수"만의 문제는 아니었습니다.

공개된 이슈에서는 GitHub Actions에서 corepack enable을 실행한 후, pnpm setup을 수행하고, 그 이후에 글로벌 pnpm 명령어를 실행했을 때 ERR_PNPM_NO_GLOBAL_BIN_DIR 오류가 보고되었습니다.

보고된 워크플로 (workflow)는 pnpm setup이 이후의 GitHub Actions 단계 (steps)에서 글로벌 pnpm 명령어를 사용할 수 있게 만들 것이라고 예상했습니다.

하지만 실제 관찰된 동작은 달랐습니다.
pnpm setup은 셸 프로필 (shell profile)에 설정을 추가했습니다.

그러나 이후의 워크플로 단계에서는 여전히 PNPM_HOME이 설정되지 않은 상태로 나타났습니다.

그 결과 pnpm이 글로벌 바이너리 디렉토리 (global bin directory)를 찾을 수 없어 pnpm add --global 명령이 실패했습니다.

이는 경계 문제 (boundary problem)였습니다:
설정 (setup)이 무엇을 구성하며, 어떤 설정 상태가 GitHub Actions 단계의 경계를 넘어야 하는가?

필드 랩 (Field Lab) 기록

이 사례에 대한 공개 필드 랩 기록은 여기에 있습니다:
https://github.com/scarab-systems/scarab-field-lab/tree/main/field-tests/pnpm-pnpm-9191
이 기록에는 공개 이슈, 공개 풀 리퀘스트, 수정 범위 (repair scope), 검증 요약 (validation summary), 그리고 비주장 사항 (non-claims)이 포함되어 있습니다.

이 기록은 공개 링크, 상태, 검증, 그리고 주장 경계 (claim boundaries)만을 포함합니다.

SDS 소스 코드나 비공개 제품 자료는 포함하지 않습니다.
사례 기록은 오직 공개된 증거 계층 (evidence layer)일 뿐입니다.

SDS 결과

SDS는 pnpm에서 설정 상태의 지속성 경계 (setup-state persistence boundary)를 찾아냈습니다.
중요한 발견은 pnpm에 새로운 글로벌-바이너리-디렉토리 (global-bin-dir) 모델이 필요하다는 것이 아니었습니다.

GitHub Actions 사용자가 corepack enable 사용을 중단해야 한다는 것도 아니었습니다.

pnpm setup이 셸 프로필 동작을 재설계해야 한다는 것도 아니었습니다.

발견된 내용은 더 구체적이었습니다:
pnpm setup이 PNPM_HOME을 계산하고 적용할 수는 있지만, GitHub Actions의 이후 워크플로 단계들이 해당 상태를 상속받으려면 setup이 GitHub Actions의 환경 (environment) 및 경로 (path) 파일에 기록해야만 합니다.

GitHub Actions 단계는 별개의 실행 경계 (execution boundaries)이기 때문에 이 차이점이 중요합니다.

명령어는 .bashrc를 업데이트할 수 있습니다.

하지만 필요한 환경 상태 (environment state)가 GitHub Actions의 단계 간 메커니즘 (step-to-step mechanism)을 통해 유지되지 않는다면, 이후의 단계는 여전히 실패할 수 있습니다.

실패 양상 (Failure shape)

실패 양상은 로컬 셸 설정 (local shell setup)과 CI 단계 지속성 (CI step persistence) 사이의 불일치였습니다.

공개된 이슈는 합리적인 사용자 기대를 설명했습니다:
만약 GitHub Actions 워크플로 (workflow)에서 pnpm setup이 성공적으로 실행된다면, 이후의 전역 pnpm 명령어들은 전역 bin 디렉토리를 찾을 수 있어야 합니다.
이슈는 그 반대의 상황을 보여주었습니다.

설정 명령어는 PNPM_HOME과 PATH를 위한 셸 프로필 (shell-profile) 라인들을 추가했습니다.
하지만 이후 단계에서의 echo $PNPM_HOME은 설정되지 않은 상태(unset)였습니다.
그 결과 pnpm add --global @upleveled/preflight 명령이 ERR_PNPM_NO_GLOBAL_BIN_DIR 오류와 함께 실패했습니다.
이는 단순히 변수가 누락된 것이 아닙니다.
이는 실행 경계 (execution-boundary)의 불일치입니다.
설정 명령어는 한 곳에서 작업을 수행했습니다.
실패한 전역 명령어는 그 작업이 다른 곳에서도 가시적(visible)이기를 필요로 했습니다.

경계 (Boundary)

이번 필드 테스트에서의 경계는 다음과 같습니다:
GitHub Actions 설정 상태는 해당 파일들이 존재할 경우, GitHub Actions 환경 파일 (environment files)을 통해 유지되어야 합니다.

이 파일들은 셸 프로필 (shell profile)과는 다릅니다.
이들은 환경 변수 (environment variables)와 경로 항목 (path entries)을 이후 단계로 전달하기 위한 CI 러너 (CI runner)의 공개적인 메커니즘입니다.
pnpm setup의 경우, 이 명령어가 공개적인 설정 계약 (public setup contract)으로 사용되기 때문에 이러한 구분이 중요합니다.
사용자들은 보통 셸 프로필 쓰기 (shell-profile writes)와 러너 환경 파일 쓰기 (runner environment-file writes)를 구분하여 생각하지 않습니다.

사용자들은 다음과 같이 생각합니다:
"설정을 실행했다."
"다음 단계는 작동해야 한다."
만약 설정이 셸 프로필만 업데이트한다면, 로컬 셸 계약 (local-shell contract)은 충족될지 몰라도 GitHub Actions 계약 (GitHub Actions contract)은 여전히 깨져 있을 수 있습니다.

변경 사항 (What changed)

수정 사항은 제한된 범위의 설정 지속성 (setup persistence) 변경입니다.
풀 리퀘스트 (pull request)는 여기에 있습니다:
https://github.com/pnpm/pnpm/pull/12841
변경 된 공개 파일들은 다음과 같습니다:

.changeset/pnpm-setup-github-actions.md
...