document-haness/scripts/terminal-evidence

Terminal Evidence Renderer

실제 명령 출력 원문을 보존한 뒤, 그 원문을 terminal UI 형태의 SVG로 렌더링한다.

Evidence rule

SVG가 정본이 아니다. 실행한 명령의 raw output과 metadata가 정본이고 SVG는 문서에 넣기 위한 표현이다.

command execution
  ├── raw/<name>.txt      # stdout/stderr 원문
  ├── meta/<name>.json    # command, cwd, executedAt, exitCode, revision
  └── terminal/<name>.svg # raw에서 생성

시각화 단계에서는 Authorization Bearer, Cookie, token/password/client_secret/API key 형태의 값을 [REDACTED]로 치환한다. 그래도 raw 파일에 secret이 들어간 채 보관하면 안 된다. 명령 자체를 secret이 출력되지 않도록 구성하고, raw 저장 전에도 검사한다.

Render

python3 /shared/Tech-Log-Document/tools/terminal-evidence/render_terminal.py \
  evidence/raw/gradle-test.txt \
  evidence/terminal/gradle-test.svg \
  --command './gradlew test' \
  --cwd '/shared/codebase/my-project' \
  --exit-code 0 \
  --executed-at '2026-08-28T15:00:00+09:00'

Capture pattern

Agent가 명령을 실제로 실행할 때 stdout/stderr, exit code, 실행 시간, cwd를 함께 기록한다. 실패 명령도 Evidence가 될 수 있으므로 exit code를 버리지 않는다.

예시 shell pattern:

set +e
executed_at=$(date --iso-8601=seconds)
pwd_value=$(pwd)
./gradlew test > evidence/raw/gradle-test.txt 2>&1
exit_code=$?
set -e

그 뒤 metadata JSON을 쓰고 renderer를 호출한다. command에 credential을 직접 넣지 않는다.

Tests

python3 -m unittest discover -s tests -v