Skip to content

Commit fccda98

Browse files
minsoo-webminsoo-web
committed
update docs
1 parent d53e062 commit fccda98

4 files changed

Lines changed: 322 additions & 23 deletions

‎README.md‎

Lines changed: 63 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -67,39 +67,77 @@ $ chromaport
6767
> Select editor: Cursor
6868
> Select themes to migrate: One Monokai, Ayu Dark
6969
> Select target app: Superset
70-
> Set as active theme? One Monokai
7170
7271
Converting 2 theme(s)...
73-
✔ One Monokai → /Users/you/.superset/app-state.json
74-
Active theme set to 'One Monokai'
75-
✔ Ayu Dark → /Users/you/.superset/app-state.json
76-
Restart Superset to apply.
72+
✔ One Monokai → ~/.config/chromaport/themes/one-monokai.json
73+
✔ Ayu Dark → ~/.config/chromaport/themes/ayu-dark.json
7774
```
7875

79-
### Options
76+
### Commands
8077

8178
```
8279
chromaport [OPTIONS] [COMMAND]
8380
8481
Commands:
85-
update Check for updates and upgrade chromaport
82+
update Check for updates and upgrade chromaport
83+
apply Apply a saved theme to additional targets
84+
create Create a custom theme from scratch
85+
presets Manage preset themes
8686
8787
Options:
88-
-e, --editor <EDITOR> Source editor [possible values: vscode, cursor]
89-
-t, --target <TARGET> Target app [possible values: superset, warp, ghostty]
90-
-y, --yes Non-interactive mode (import active theme, overwrite if exists)
91-
--activate Apply the theme to the target app's config
92-
-h, --help Print help
93-
-V, --version Print version
88+
-v, --version Print version
89+
-e, --editor <EDITOR> Source editor [possible values: vscode, cursor]
90+
-t, --target <TARGET> Target app [possible values: superset, warp, ghostty]
91+
-h, --help Print help
9492
```
9593

96-
### Non-interactive
94+
### Import themes
9795

9896
```sh
99-
# Import the active VS Code theme to Superset
100-
chromaport --editor vscode --target superset --yes
97+
# Interactive mode — select editor, themes, and target step by step
98+
chromaport
99+
100+
# Non-interactive — specify editor and target directly
101+
chromaport --editor vscode --target ghostty
102+
```
103+
104+
Theme selection includes a **TUI-based live preview** powered by ratatui, showing a real-time rendering of each theme as you browse. Use arrow keys to navigate and type to filter.
105+
106+
### Apply saved themes
107+
108+
```sh
109+
chromaport apply
110+
```
111+
112+
Re-apply a previously imported theme to additional targets. Shows which targets already have the theme applied.
113+
114+
### Create a custom theme
115+
116+
```sh
117+
chromaport create
118+
```
119+
120+
Build a theme from scratch using an **interactive color picker**:
121+
122+
1. Pick a background color
123+
2. Pick a foreground color
124+
3. Pick an accent color
125+
4. Preview and confirm
126+
127+
The color picker supports **slider mode** (arrow keys to adjust HSL values, Shift for 5x step) and **hex mode** (press `#` to type a hex code directly). A full palette is automatically derived from your 3 base colors.
128+
129+
### Preset themes
130+
131+
```sh
132+
# List available presets
133+
chromaport presets list
134+
135+
# Install presets
136+
chromaport presets install
101137
```
102138

139+
Browse and install curated preset themes from the chromaport repository.
140+
103141
## Supported editors
104142

105143
| Editor | Path |
@@ -109,24 +147,26 @@ chromaport --editor vscode --target superset --yes
109147

110148
## Supported targets
111149

112-
| Target | How it works |
113-
| -------- | --------------------------------------------------------------- |
114-
| Superset | Writes to `~/.superset/app-state.json` (quit Superset first) |
115-
| Warp | Writes to `~/.warp/themes/*.yaml` (auto-detected while running) |
150+
| Target | How it works |
151+
| -------- | --------------------------------------------------------------------------------- |
152+
| Superset | Writes to `~/.superset/chromaport-themes/` — import via Superset UI |
153+
| Warp | Symlinks to `~/.warp/themes/` — auto-detected while running |
154+
| Ghostty | Symlinks to `~/.config/ghostty/themes/` — apply via config or reload |
116155

117156
## How it works
118157

119158
1. Scans editor extension directories for `package.json` theme contributions
120159
2. Parses VS Code theme JSON (with JSONC comment stripping and `include` inheritance)
121160
3. Converts to an intermediate representation (IR)
122-
4. Writes to the selected target format
161+
4. Saves to a central theme store (`~/.config/chromaport/themes/`)
162+
5. Symlinks or writes to the selected target format
123163

124164
## Development
125165

126166
```sh
127167
cargo test
128-
cargo fmt-check
129-
cargo lint
168+
cargo fmt --check
169+
cargo clippy --all-targets
130170
```
131171

132172
## License

‎docs/brainstorms/2026-03-11-tui-screenshot-automation-brainstorm.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# TUI Screenshot Automation for README
2+
3+
**Date**: 2026-03-11
4+
**Status**: Brainstorm
5+
6+
## What We're Building
7+
8+
VHS(Charmbracelet)를 사용하여 chromaport TUI의 인터랙티브 테마 프리뷰 워크플로우를 GIF 애니메이션으로 자동 캡처하고, 이를 README 상단(로고 바로 아래)에 메인 데모로 배치한다.
9+
10+
### 범위
11+
12+
- VHS `.tape` 스크립트 작성: chromaport TUI의 테마 탐색 → 필터링 → 선택 → 라이브 프리뷰 흐름
13+
- GIF를 `assets/` 폴더에 저장
14+
- README.md 업데이트: 로고 아래에 GIF 삽입
15+
16+
### 범위 외
17+
18+
- CI/CD 자동화 (필요 시 나중에 추가)
19+
- Makefile/justfile 통합
20+
- 정적 PNG 스크린샷
21+
- 다른 워크플로우(에디터/타겟 선택 CLI 부분) 별도 캡처
22+
23+
## Why This Approach
24+
25+
### VHS를 선택한 이유
26+
27+
1. **재현성**: `.tape` 파일은 선언적 스크립트로, 동일한 결과를 반복 생성 가능
28+
2. **TUI 친화적**: ratatui/crossterm 기반 TUI의 키보드 인터랙션을 자연스럽게 시뮬레이션
29+
3. **간단한 사용법**: `vhs demo.tape` 한 줄로 GIF 생성
30+
4. **생태계**: Charmbracelet의 널리 사용되는 도구로, 잘 관리되고 문서화됨
31+
32+
### GIF를 선택한 이유
33+
34+
- TUI의 인터랙티브한 특성(테마 탐색, 필터링, 라이브 프리뷰 전환)을 정적 이미지로는 전달 불가
35+
- GitHub README에서 바로 재생 가능 (외부 링크 불필요)
36+
37+
### 로고 아래 배치를 선택한 이유
38+
39+
- 첫 방문자에게 chromaport의 핵심 가치를 즉시 시각적으로 전달
40+
- "Your favorite editor theme, everywhere" 태그라인의 실체를 바로 보여줌
41+
42+
## Key Decisions
43+
44+
1. **도구**: VHS (Charmbracelet) — `.tape` 스크립트 기반 터미널 GIF 레코딩
45+
2. **결과물 형태**: GIF 애니메이션 (단일 파일, 전체 프리뷰 흐름)
46+
3. **캡처 워크플로우**: 테마 리스트 탐색 → 필터링 → 테마 선택 → 라이브 프리뷰
47+
4. **저장 위치**: `assets/demo.gif` (또는 `assets/chromaport-demo.gif`)
48+
5. **README 배치**: 로고 이미지 바로 아래, `# chromaport` 제목 위 또는 태그라인 아래
49+
6. **자동화 수준**: 수동 실행 (`vhs demo.tape`) — YAGNI 원칙 적용
50+
51+
## Implementation Considerations
52+
53+
### VHS .tape 스크립트 구성 요소
54+
55+
```tape
56+
# 터미널 설정
57+
Set Shell "bash"
58+
Set FontSize 14
59+
Set Width 1200
60+
Set Height 600
61+
Set Theme "Catppuccin Mocha" # 또는 적절한 터미널 테마
62+
63+
# chromaport 실행 (에디터/타겟은 CLI 인자로 미리 지정)
64+
Type "chromaport --editor cursor --target ghostty"
65+
Enter
66+
Sleep 2s
67+
68+
# TUI 인터랙션: 테마 탐색
69+
Down
70+
Sleep 500ms
71+
Down
72+
Sleep 500ms
73+
Down
74+
Sleep 500ms
75+
76+
# 필터링
77+
Type "cat" # "Catppuccin" 등 필터
78+
Sleep 1s
79+
80+
# 테마 선택
81+
Enter
82+
Sleep 2s
83+
```
84+
85+
### 주의 사항
86+
87+
- chromaport 바이너리가 PATH에 있어야 함 (또는 `cargo run --` 사용)
88+
- VS Code/Cursor 테마 확장이 설치된 환경에서만 실행 가능
89+
- VHS 설치 필요: `brew install vhs`
90+
- GIF 파일 크기 관리 필요 (README 로딩 속도에 영향)
91+
92+
## Open Questions
93+
94+
_현재 열린 질문 없음 — 모든 주요 결정이 대화에서 해결됨._

‎docs/plans/2026-03-10-chore-release-workflow-trigger-cleanup-plan.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: "chore: release workflow 트리거 정리 및 태그 관행 문서화"
3+
type: chore
4+
status: active
5+
date: 2026-03-10
6+
---
7+
8+
# chore: release workflow 트리거 정리 및 태그 관행 문서화
9+
10+
Release workflow(`release.yml`)에서 불필요한 `pull_request` 트리거를 제거하고, 태그 패턴을 `v` prefix 필수로 변경하며, CLAUDE.md에 태그 관행을 문서화한다.
11+
12+
## Acceptance Criteria
13+
14+
- [x] `.github/workflows/release.yml`에서 `pull_request` 트리거 제거
15+
- [x] 태그 패턴을 `v` prefix 필수로 변경: `'v[0-9]+.[0-9]+.[0-9]+*'`
16+
- [x] `CLAUDE.md`에 태그 형식 `v{major}.{minor}.{patch}` 관행 명시
17+
18+
## Context
19+
20+
- 현재 `release.yml`은 `pull_request`와 `push.tags` 두 이벤트로 트리거됨
21+
- `pull_request` 트리거는 cargo-dist의 CI 검증용이지만, 실제로 별도 CI workflow가 있다면 불필요
22+
- 기존 모든 태그(`v0.1.0` ~ `v0.4.0`)가 `v` prefix를 사용하지만, 현재 패턴(`**[0-9]+.[0-9]+.[0-9]+*`)은 `v` 없는 태그도 매칭 가능
23+
- `CLAUDE.md`에 태그 형식이 문서화되어 있지 않아, `v` prefix 누락 위험이 있음
24+
25+
## Changes
26+
27+
### 1. `.github/workflows/release.yml` (lines 41-45)
28+
29+
**Before:**
30+
```yaml
31+
on:
32+
pull_request:
33+
push:
34+
tags:
35+
- '**[0-9]+.[0-9]+.[0-9]+*'
36+
```
37+
38+
**After:**
39+
```yaml
40+
on:
41+
push:
42+
tags:
43+
- 'v[0-9]+.[0-9]+.[0-9]+*'
44+
```
45+
46+
- `pull_request` 트리거 제거
47+
- 태그 패턴에 `v` prefix 필수화
48+
- `plan` job의 `tag`, `tag-flag`, `publishing` 출력에서 `pull_request` 분기 로직도 단순화 가능 (line 53-55)
49+
50+
### 2. `CLAUDE.md` (Conventions 섹션)
51+
52+
태그 관행 추가:
53+
```markdown
54+
- Git tag 형식: `v{major}.{minor}.{patch}` (e.g. `v0.3.0`, `v0.3.1`)
55+
```
56+
57+
## Sources
58+
59+
- `.github/workflows/release.yml:41-55` — 현재 트리거 설정 및 PR 분기 로직
60+
- `CLAUDE.md:14-16` — 현재 버전 관행 문서
61+
- 기존 태그: `v0.1.0`, `v0.2.0`, `v0.3.0`, `v0.3.1`, `v0.4.0`

‎docs/plans/2026-03-11-chore-tui-screenshot-automation-plan.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: "chore: Add TUI demo GIF to README with VHS"
3+
type: chore
4+
status: active
5+
date: 2026-03-11
6+
origin: docs/brainstorms/2026-03-11-tui-screenshot-automation-brainstorm.md
7+
---
8+
9+
# chore: Add TUI demo GIF to README with VHS
10+
11+
## Overview
12+
13+
VHS(Charmbracelet)를 사용하여 chromaport TUI의 인터랙티브 테마 프리뷰 워크플로우를 GIF로 녹화하고, README 상단(로고 아래)에 메인 데모로 배치한다.
14+
15+
## Problem Statement / Motivation
16+
17+
chromaport의 핵심 기능인 TUI 테마 프리뷰가 README에 시각적으로 표현되지 않아, 첫 방문자가 도구의 가치를 즉시 파악하기 어렵다. "Your favorite editor theme, everywhere" 태그라인의 실체를 한 눈에 보여주는 데모 GIF가 필요하다.
18+
19+
## Proposed Solution
20+
21+
1. VHS `.tape` 스크립트를 작성하여 TUI 인터랙션을 선언적으로 기술
22+
2. `vhs` 명령으로 GIF 생성 → `assets/` 저장
23+
3. README.md 로고 아래에 GIF 삽입
24+
25+
(see brainstorm: docs/brainstorms/2026-03-11-tui-screenshot-automation-brainstorm.md)
26+
27+
## Technical Considerations
28+
29+
### TTY 검증 (Critical — 먼저 확인 필수)
30+
31+
`src/interactive.rs:7-9`의 `is_tty()` 체크가 VHS pseudo-TTY에서 통과하는지 반드시 먼저 검증해야 한다. 최소한의 테이프로 smoke test 실행:
32+
33+
```tape
34+
Output assets/test.gif
35+
Type "chromaport --editor cursor --target ghostty"
36+
Enter
37+
Sleep 3s
38+
```
39+
40+
만약 실패하면 VHS가 PTY를 제공하지 않는 것이므로 `asciinema rec` + `agg`(asciinema GIF generator)로 대체한다.
41+
42+
### Post-TUI 프롬프트 회피
43+
44+
테마 선택 후 `confirm_overwrite` (`src/interactive.rs:67`), `confirm_replace_with_symlink` (`src/interactive.rs:77`), `confirm_apply_config` (`src/interactive.rs:72`) 프롬프트가 나타날 수 있다.
45+
46+
**전략**: 데모에서는 테마를 선택(Enter)하지 않고, 탐색과 프리뷰 전환만 보여준 뒤 `q`로 종료한다. 이렇게 하면 post-TUI 프롬프트가 절대 발생하지 않으며, 환경 상태에 의존하지 않는다.
47+
48+
### 필터 기능과 Exit 동작
49+
50+
`src/preview/mod.rs:138-146`: 필터가 활성화된 상태에서 `q`는 필터에 문자 추가, `Esc`는 필터 클리어. 혼란 방지를 위해 **화살표 키 탐색만** 사용하고 필터링 데모는 생략.
51+
52+
### GIF 파일 크기
53+
54+
15초 이내 녹화, 2MB 이하 유지 목표. 초과 시 `gifsicle --optimize=3`으로 후처리.
55+
56+
### 터미널 크기
57+
58+
TUI의 35%/65% 분할(`src/preview/mod.rs:75-84`)이 잘 보이려면 충분한 너비 필요. `Set Width 1200`, `Set Height 600` (px 기준) 권장.
59+
60+
## Acceptance Criteria
61+
62+
- [ ] **Phase 0**: VHS PTY smoke test 통과 (`vhs`에서 chromaport TUI가 정상 렌더링됨)
63+
- [ ] **Phase 1**: `demo.tape` 작성 — 프로젝트 루트에 위치
64+
- 터미널 설정 (크기, 폰트, 테마)
65+
- `chromaport --editor cursor --target ghostty` 실행
66+
- TUI 인터랙션: 3개 이상 테마 탐색 (Down 키), 프리뷰 전환 확인
67+
- `q`로 깔끔하게 종료
68+
- 총 녹화 시간 15초 이내
69+
- [ ] **Phase 2**: GIF 생성 및 검증
70+
- `vhs demo.tape` 실행으로 `assets/chromaport-demo.gif` 생성
71+
- 파일 크기 2MB 이하 (초과 시 gifsicle 최적화)
72+
- TUI 양쪽 패널(테마 리스트 + 프리뷰)이 선명하게 보임
73+
- [ ] **Phase 3**: README.md 업데이트
74+
- 로고 `<img>` 태그 아래에 GIF 삽입
75+
- 기존 `<p align="center">` 스타일과 일관된 HTML 태그 사용
76+
- [ ] GIF에서 최소 3개 테마 탐색 장면이 보임
77+
- [ ] GIF에서 라이브 프리뷰(컬러 팔레트 + 코드 스니펫)가 전환되는 장면이 보임
78+
- [ ] 테마를 선택(Enter)하지 않고 `q`로 종료 — post-TUI 프롬프트 없음
79+
80+
## Dependencies & Risks
81+
82+
| 항목 | 설명 | 완화 전략 |
83+
|------|------|-----------|
84+
| VHS 설치 | `brew install vhs` 필요 | 사전 설치 확인 |
85+
| PTY 호환성 | VHS pseudo-TTY에서 crossterm `IsTerminal` 통과 여부 | Phase 0 smoke test로 먼저 검증 |
86+
| 테마 의존성 | 설치된 에디터 테마에 따라 리스트가 달라짐 | 특정 테마 이름에 의존하지 않는 탐색 시나리오 (Down 키만 사용) |
87+
| Post-TUI 프롬프트 | 테마 선택 시 추가 확인 프롬프트 등장 가능 | 선택 없이 프리뷰만 보여주고 `q`로 종료 |
88+
| GIF 크기 | 고해상도 + 긴 녹화 → 대용량 | 15초 제한 + gifsicle 최적화 |
89+
90+
## Implementation Files
91+
92+
| 파일 | 작업 | 비고 |
93+
|------|------|------|
94+
| `demo.tape` (신규) | VHS 테이프 스크립트 작성 | 프로젝트 루트 |
95+
| `assets/chromaport-demo.gif` (신규) | GIF 생성 결과물 | vhs 출력 |
96+
| `README.md` | 로고 아래 GIF 이미지 태그 삽입 | 기존 `<p align="center">` 스타일 유지 |
97+
98+
## Sources & References
99+
100+
- **Origin brainstorm:** [docs/brainstorms/2026-03-11-tui-screenshot-automation-brainstorm.md](docs/brainstorms/2026-03-11-tui-screenshot-automation-brainstorm.md) — VHS 선택 이유, GIF 포맷 결정, 수동 실행 방식, README 배치 위치
101+
- TUI 구현: `src/preview/mod.rs`, `src/preview/app.rs`, `src/preview/ui.rs`
102+
- CLI 인자: `src/cli.rs`
103+
- 현재 README: `README.md` (로고 1-3줄, 제목 5줄, 태그라인 7줄)
104+
- VHS 공식 문서: https://github.com/charmbracelet/vhs

0 commit comments

Comments
 (0)