TL;DR

  • Cligram은 YAML 또는 Go로 정의한 흐름도를 터미널 크기에 맞춰 텍스트로 그리며, 실행 상태에 따라 실시간으로 다시 렌더링하는 도구임
  • 상자, 결정 노드, 라벨이 붙은 간선을 사용해 흐름도를 표현하며, 실행 상태가 바뀌어도 노드 위치는 유지됨
  • 무작위 흐름도 100개를 각각 그린 뒤 텍스트만 읽어 원래 흐름도와 의미가 일치하는지 확인하는 방식임
  • go install github.com/isacikgoz/cligram/cmd/cligram@latest로 명령줄 도구를 설치하고, go get github.com/isacikgoz/cligram으로 라이브러리를 가져올 수 있음
  • 노드 배치 고정, 화면 크기 맞춤, 스크롤 표시, 색상 팔레트, Bubble Tea 기반 터미널 사용자 인터페이스(TUI) 기능을 제공함

Cligram 소개

  • Cligram은 터미널에서 흐름도를 그리는 도구로, YAML이나 Go 코드로 정의할 수 있음
  • Mermaid와 비슷한 방식으로 상자, 결정 노드, 라벨이 붙은 간선을 텍스트로 표현하고, 터미널에 맞게 배치하며 실행 흐름에 따라 실시간으로 다시 그림
  • 무작위 흐름도 100개를 그린 다음 텍스트만으로 읽어 흐름도의 의미와 일치하는지 확인함
  • 명령줄 도구 설치 명령은 go install github.com/isacikgoz/cligram/cmd/cligram@latest이며, 라이브러리 가져오기 명령은 go get github.com/isacikgoz/cligram임

YAML로 흐름도 정의

  • 예시 흐름도는 Triage에서 Ready to ship? 결정 노드로 이동하고, 응답에 따라 Ship it 또는 Fix it으로 이어지는 릴리스 절차임
  • Fix it에서 다시 Ready to ship?으로 돌아가는 간선도 포함함
  • 노드는 텍스트, 종류(step, decision, end), 클래스, 배치 위치를 지정할 수 있으며, 배치 위치는 right of ready 또는 below a and b와 같은 표현으로 설정 가능함
  • -width를 지정하지 않으면 출력 대상 터미널의 너비에 맞춰 그림을 배치함

Go로 흐름도 정의 및 렌더링

  • cligram.New()로 다이어그램을 만들고 Node와 Edge를 사용해 노드와 간선을 정의함
  • cligram.As(cligram.Decision)으로 결정 노드를 지정하고, cligram.Class("agent")로 노드 클래스를 설정하며, cligram.Label("yes")와 같은 옵션으로 간선에 라벨을 붙임
  • d.Layout(cligram.Fit(80, 24))로 80×24 크기에 맞춰 레이아웃을 계산하고, Render에 노드 상태와 선택된 간선을 전달해 현재 실행 상태를 표시함
  • 상태 예시에서는 triage가 완료, ready가 활성 상태이며, triage에서 ready로 이동한 간선이 표시됨
  • 크기별 레이아웃은 한 번 계산한 뒤 실행이 진행될 때마다 다시 렌더링할 수 있으며, 상태가 변해도 상자는 이동하지 않음
  • 색상을 사용하려면 cligram.Plain 대신 cligram.ANSI 또는 직접 정의한 팔레트를 사용할 수 있음

추가 기능

  • 배치: cligram.At("right of x")로 노드 위치를 고정하며, 나머지 노드는 간선을 따라 배치함
  • 화면 맞춤: Fit(w, h)가 흐름도를 압축하거나, 뱀처럼 줄을 바꿔 방향을 전환하거나, 텍스트 너비를 줄여 화면에 맞춤
  • 화면에 들어오지 않는 부분은 RenderView와 Reveal로 스크롤해 표시함
  • TUI 통합: bubble 패키지는 실행 흐름을 따라가는 키보드 포커스와 하위 다이어그램을 열 수 있는 노드를 지원하는 Bubble Tea 컴포넌트임
  • go run ./examples/live로 라이브 예제를 실행할 수 있음
  • 전체 사용 안내는 AGENTS.md에 있으며, 설계 결정은 docs/design.md에 설명됨

라이선스

  • 라이선스는 MIT이며, 자세한 내용은 LICENSE에서 확인할 수 있음