52 lines
1.7 KiB
Markdown
52 lines
1.7 KiB
Markdown
# Terminal Evidence Renderer
|
|
|
|
실제 명령 출력 원문을 보존한 뒤, 그 원문을 terminal UI 형태의 SVG로 렌더링한다.
|
|
|
|
## Evidence rule
|
|
|
|
`SVG`가 정본이 아니다. **실행한 명령의 raw output과 metadata가 정본**이고 SVG는 문서에 넣기 위한 표현이다.
|
|
|
|
```text
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
python3 -m unittest discover -s tests -v
|
|
```
|