shell

셸은 최소한으로 쓴다

이 저장소는 Windows에서 개발한다. 기본 셸이 Windows PowerShell 5.1이면 콘솔 인코딩이 cp949이고 > 는 UTF-16으로, Set-Content -Encoding UTF8 은 BOM을 붙여 쓴다. 아래 규칙은 그걸로 실제로 시간을 날린 사례에서 나왔다.

에디터 터미널을 PowerShell 7로 바꿨어도 에이전트가 쓰는 셸은 5.1일 수 있다. 둘은 다른 프로세스이고, 에이전트 셸은 터미널 프로필 설정을 읽지 않는다. 확인은 이렇게 한다.

$PSVersionTable.PSVersion.ToString()

5.1이 나오면 npm run doctor 가 원인과 조치를 알려준다. 대개 PowerShell 7이 MSIX(Store)로 깔려서 PATH에 0바이트 별칭만 있는 경우다.

그래도 아래 규칙은 버전과 무관하게 지킨다. 7에서 안 깨지는 것도 있지만, 매번 버전을 확인하고 방법을 고르는 것보다 항상 안전한 방법을 쓰는 편이 빠르다. 셸이 무엇인지 모르는 상태에서도 성립해야 한다.

파일은 셸로 만들거나 고치지 않는다

편집 도구를 쓴다. Set-Content, Out-File, echo >, sed, awk 로 소스나 문서를 건드리지 않는다.

Set-Content -Encoding UTF8 은 UTF-8 BOM을 붙인다. BOM이 붙은 .mjs 는 shebang이 깨져서 SyntaxError: Invalid or unexpected token 이 나는데, 원인을 찾는 데 시간이 걸린다. npm run validate 가 BOM을 검사하지만 애초에 만들지 않는 게 낫다.

인라인 스크립트를 셸에 넣지 않는다

node -e "..." 안에 따옴표, $, *, 백틱이 들어가면 PowerShell이 먼저 해석해서 망가진다. SELECT COUNT(*) 의 * 가 와일드카드로 잡히는 식이다.

대신 이 순서로 고른다.

1. npm run 스크립트 — npm run bgg -- stats 처럼 이미 있는 것
2. node tools/<도구>.mjs <커맨드> — 저장소의 CLI
3. 그래도 필요하면 스크립트 파일을 만들어서 실행한다

한 번 쓰고 버릴 검증 코드는 저장소 루트의 scratch/ 에 둔다. gitignore 대상이고 npm run validate 도 건너뛰므로, 반쯤 쓴 스크립트를 남겨둬도 테스트가 깨지지 않는다.

projects/ 아래에 두지 않는다. projects/<슬러그>/ 는 게임 하나가 들어가는 자리이고 도구들이 슬러그로 그걸 찾는다. 검증 스크립트를 거기 두면 게임 프로젝트인 척 하는 폴더가 생기고, 실제로 시험용 룰셋과 아트와 일회용 스크립트가 한 폴더에 뒤섞였다.

긴 텍스트를 인자로 넘기지 않는다

여러 줄이거나 따옴표가 들어간 텍스트는 명령줄 인자로 넘기지 않는다. 파일로 넘긴다.

PowerShell은 네이티브 명령에 인자를 넘길 때 문자열을 다시 파싱한다. 안에 따옴표가 있으면 거기서 인자가 쪼개진다. 히어스트링(@'...'@)으로 감싸도 결과는 같다. 셸이 문자열을 만드는 단계가 아니라 exe에 넘기는 단계에서 깨지기 때문이다.

실측해보면 이렇다. PowerShell 안에서는 멀쩡한 문자열 하나인데 exe가 받을 때는 넷이 된다.

$msg = @'
fix: 규칙이 스스로 모순되던 것을 고침

- bgs-ruleset 이 "표에는 인원별 열을 둔다"고 강하게 말하던 것을 고쳤다
'@
node -e "process.argv.slice(1).forEach((a,i)=>console.log('['+i+'] '+JSON.stringify(a)))" "$msg"

# [0] "fix: 규칙이 스스로 모순되던 것을 고침\n\n- bgs-ruleset 이 표에는"
# [1] "인원별"
# [2] "열을"
# [3] "둔다고 강하게 말하던 것을 고쳤다"