Contributing

기여/작업 규칙 (pytmux)

이 디렉토리(scripts/pytmux)에서 작업할 때 따르는 규칙이다.

커밋 규칙 (필수)

1. 의미 있는 변경마다 커밋한다. 하나의 논리적 변경(기능 추가, 버그 수정, 문서 변경, 리네임 등)이 완성되면 그 단위로 커밋한다. 여러 무관한 변경을 한 커밋에 섞지 않는다.

2. 커밋 메시지에 무엇을 했는지 상세히 기입한다. 다음을 포함한다:

   • 한 줄 요약(맨 윗줄). 가능하면 [scripts/pytmux] <영역>: <요약> 형식.
   • 변경의 배경/이유, 구체적으로 추가·수정·삭제한 내용, 영향받는 파일 목록.

권장 절차 예시

# 1) 변경 파일 스테이징
git add docs/FOO.md

# 2) 상세 메시지(요약 + 본문)를 담아 커밋
git commit

# 3) 원격에 푸시 (해당하면)
git push

코드/문서 규칙

• 설계 변경은 먼저 docs/DESIGN.md 에 반영한 뒤 구현한다.
• 진입점은 pytmux.py(얇은 진입점), 구현은 pytmuxlib/ 패키지.
• 의존성은 requirements.txt 에 명시한다.

보안 규칙

새 코드는 다음 보안 규칙을 지킨다.

• 민감 파일은 ipc.open_private(0600) 로 연다 — 화면 내용·토큰·캡처 등이 담기는 영속/로그 파일을 open(...,"w") 로 만들면 umask(0644)로 다른 로컬 사용자가 읽을 수 있다.
• 서버 첫 메시지 핸들러는 인증을 전제한다 — handle_client 의 토큰(F1)·피어 UID(F2) 검증을 우회하는 새 진입점을 만들지 않는다. 새 control/cmd 액션도 같은 신뢰 경계 안.
• 클라이언트는 서버 데이터를 실행하지 않는다 — 서버에서 받은 메시지를 _run_command/ 셸/eval 로 흘리지 않는다(표시 전용). 명령은 로컬 설정·사용자 입력에서만.
• 외부 명령은 argv 리스트로 실행한다(shell=True/os.system 금지). 셸 실행이 의도된 기능(popup/pipe/run-shell)이면 접근 통제로 보호하고 그 사실을 주석에 남긴다.
• 클라 입력 필드는 검증한다 — 치수는 protocol.clamp_dim, base64/JSON 디코드는 예외 가드로 감싼다.

스크린샷 (이미지 생성)

docs/image/ 의 스크린샷 SVG 는 수작업 캡처가 아니라 scripts/gen_screenshots.py 가 실 클라이언트를 헤드리스로 운전해 SVG 로 생성한다(docs/image/*.svg). 사용법은 그 스크립트의 docstring 참고.

• UI(테두리색·상태줄·팝업·탭바 등)나 매뉴얼 장면을 바꿨으면 커밋 전에 재생성한다:

  python3 scripts/gen_screenshots.py            # 결정적 장면 33개 전체 재생성 → docs/image/*.svg
  python3 scripts/gen_screenshots.py 14-info    # 이름 매칭 장면만
  python3 scripts/gen_screenshots.py claude-suite  # 라이브 Claude 컷 4개(11/12/13/22, 실 API 호출)

  (Windows 박스에선 python3 대신 py — 예 py scripts/gen_screenshots.py.)
• 저장 직후 _redact_svg 가 (1) 계정 PII(이메일·환영 배너 이름) 마스킹, (2) 한글 등 와이드 문자 자간 보정(Rich textLength 버그 교정)을 자동 적용한다 — 별도 작업 불필요.
• 시계·호스트명 등 환경값은 실제값이 박혀 그 부분만 diff 가 날 수 있다(무해).

테스트

• 변경 후 커밋 전에 헤드리스 테스트를 돌린다: python3 tests/run.py (Windows 박스에선 py tests/run.py). 화면/터미널 없이 전체 동작 검증, 종료 코드 0 = 통과.
• 동작을 바꾸거나 버그를 고치면 tests/ 에 회귀 테스트를 추가한다. 화면 검증은 harness.pane_text() 나 app.view._cells/render_line 의 텍스트 비교로 한다.