tui-validate

TUI の検証

概要

このスキルは、出力をキャプチャし、LLM を審判として用いた意味的な検証によって、ターミナルユーザーインターフェース（TUI）アプリケーションを検証します。高精細なターミナルのスクリーンショットには、Charmbracelet の freeze を活用し、構造化された検証基準を提供します。

理念：脆弱な文字列一致を使うのではなく、このスキルでは意味的な理解を用いて、TUI の出力が「正しく見える」ことを検証します。レイアウト、コンテンツの有無、視覚的な階層を確認し、軽微な書式の変更では失敗しないようにします。

使用する場面

• 変更後に TUI の描画を検証する
• UI コンポーネントが正しく表示されることを確認する
• ターミナルアプリケーションの視覚的なリグレッションテスト
• 特定の操作後の TUI の状態を検証する
• 検証付きでドキュメント用のスクリーンショットを作成する

前提条件

必須：

• freeze CLI ツールがインストールされていること（brew install charmbracelet/tap/freeze）
• インタラクティブな TUI のキャプチャに使用する tmux（任意。実行中のアプリケーション用）

確認：

# Check freeze is installed
freeze --version

# Check tmux is installed (for interactive capture)
tmux -V

パラメーター

• target（必須）：検証する対象。次のいずれかです。

  • file:<path> - 検証する ANSI 出力ファイル
  • command:<cmd> - 実行して出力をキャプチャするコマンド
  • tmux:<session> - キャプチャする実行中の tmux セッション
  • buffer:<text> - 検証するテキスト／ANSI の生データ

• criteria（必須）：検証基準。次のいずれかを指定できます。

  • 定義済みの基準名（組み込みの基準を参照）
  • 確認対象を記述したカスタム基準文字列

• output_format（任意、デフォルト："svg"）：スクリーンショット形式

  • svg - ドキュメントに最適なベクター形式
  • png - 視覚的な差分の確認に最適なラスター形式
  • text - 最も高速なテキストのみの抽出

• save_screenshot（任意、デフォルト：false）：スクリーンショットを保存するかどうか

  • true の場合、カレントディレクトリに {target_name}.{format} として保存します

• judge_mode（任意、デフォルト："semantic"）：検証方法

  • semantic - 意味とレイアウトに基づいて LLM が判定します
  • strict - コンテンツが完全に存在するかも確認します
  • visual - PNG が必要で、視覚的な外観を確認します

組み込みの基準

ralph-header

Ralph TUI のヘッダーコンポーネントを検証します。

• [iter N] または [iter N/M] 形式の反復カウンター
• MM:SS 形式の経過時間
• 絵文字と名前を含むハットのインジケーター
• モードインジケーター（▶ auto または ⏸ paused）
• 任意のスクロールモードインジケーター [SCROLL]
• 任意のアイドルカウントダウン idle: Ns

ralph-footer

Ralph TUI のフッターコンポーネントを検証します。

• アクティビティインジケーター（◉ active、◯ idle、または ■ done）
• 最後のイベントトピックの表示
• 検索モードが有効な場合の表示

ralph-full

Ralph TUI のレイアウト全体を検証します。

• 上部のヘッダーセクション（3 行）
• ターミナルコンテンツ領域（高さは可変）
• 下部のフッターセクション（3 行）
• 適切な視覚的階層と境界線

tui-basic

一般的な TUI の検証：

• 表示可能なコンテンツがある（空白ではない）
• 描画上の問題や文字化けがない
• ターミナルの寸法が適切である

実行フロー

1. キャプチャフェーズ

対象の種類に応じて TUI の出力をキャプチャします。

ファイルを対象とする場合：

freeze {file_path} -o /tmp/tui-capture.{format}

コマンドを対象とする場合：

freeze --execute "{command}" -o /tmp/tui-capture.{format}

tmux を対象とする場合：

tmux capture-pane -pet {session} | freeze -o /tmp/tui-capture.{format}

バッファーを対象とする場合：

echo "{buffer}" | freeze -o /tmp/tui-capture.{format}

制約：

• キャプチャを試みる前に、freeze がインストールされていることを必ず確認してください
• キャプチャに失敗した場合は適切に対処し、エラーを報告してください
• 出力形式に適した freeze フラグを必ず使用してください
• 一貫した描画のために --theme base16 を使用することを推奨します
• --width と --height を使って適切な寸法を設定することを推奨します

2. 抽出フェーズ

LLM による分析用にコンテンツを抽出します。

テキスト／意味的な検証の場合：

• 形式が text の場合、キャプチャしたテキストをそのまま使用します
• 形式が svg または png の場合、コンテンツ分析用にテキスト版もキャプチャします

視覚的な検証の場合：

• PNG 形式が必要です
• ビジョン機能を使って画像を直接分析します

制約：

• judge_mode が visual の場合、視覚表現とテキスト表現の両方を必ず抽出してください
• 関連する場合は、色の検証のために ANSI エスケープシーケンスを必ず保持してください

3. 検証フェーズ

適切な基準を用いて、LLM を判定役として検証します。

意味的検証プロンプトのテンプレート：

Analyze this terminal UI output and determine if it meets the following criteria:

CRITERIA:
{criteria_description}

TERMINAL OUTPUT:
{captured_text}

Evaluate each criterion and provide:
1. PASS or FAIL for each requirement
2. Brief explanation for any failures
3. Overall verdict: PASS or FAIL

Be lenient on exact formatting but strict on:
- Required content presence
- Logical layout and hierarchy
- No rendering errors or artifacts

視覚的検証プロンプトのテンプレート（画像付き）：

Examine this terminal screenshot and validate:

CRITERIA:
{criteria_description}

Check for:
1. Visual hierarchy and layout
2. Color coding correctness
3. No rendering artifacts or broken characters
4. Proper alignment and spacing

Verdict: PASS or FAIL with explanation

制約：

• 明確な PASS または FAIL の判定を必ず返してください
• 失敗時は具体的なフィードバックを必ず提供してください
• 空白や書式の違いについては、必ず寛容に判定してください
• 内容の有無と意味的な正確さについては、必ず厳密に判定してください
• PASS の場合も、警告があれば記載することを推奨します

4. 報告フェーズ

検証結果を報告します。

PASS の場合：

✅ TUI Validation PASSED

Criteria: {criteria_name}
Target: {target}
Mode: {judge_mode}

All requirements satisfied.
{optional_notes}

FAIL の場合：

❌ TUI Validation FAILED

Criteria: {criteria_name}
Target: {target}
Mode: {judge_mode}

Issues found:
- {issue_1}
- {issue_2}

Screenshot saved: {path_if_saved}

制約：

• 明確な判定を必ず提示してください
• 失敗時は具体的な問題点を必ず列挙してください
• スクリーンショットが保存されている場合は、そのパスを必ず提示してください
• よくある問題に対する修正方法の提案を推奨します

例

例 1：ファイルから Ralph ヘッダーを検証する

入力：

/tui-validate file:test_output.txt criteria:ralph-header

手順：

1. ANSI 出力を含む test_output.txt を読み取ります
2. freeze でキャプチャします：freeze test_output.txt -o /tmp/capture.svg
3. テキストコンテンツを抽出します
4. LLM を判定役として、ralph-header の基準を適用します
5. 詳細とともに PASS/FAIL を報告します

例 2：tmux のライブ TUI を検証する

入力：

/tui-validate tmux:ralph-session criteria:ralph-full save_screenshot:true

手順：

1. tmux ペインをキャプチャします：tmux capture-pane -pet ralph-session | freeze -o ralph-session.svg
2. テキストもキャプチャします：tmux capture-pane -pet ralph-session > /tmp/text.txt
3. ralph-full の基準を適用し、ヘッダー、コンテンツ、フッターを確認します
4. スクリーンショットを ralph-session.svg に保存します
5. 検証結果を報告します

例 3：カスタム基準で検証する

入力：

/tui-validate command:"cargo run --example tui_demo" criteria:"Shows a bordered box with 'Hello World' text centered inside" output_format:png judge_mode:visual

手順：

1. コマンドを実行してキャプチャします：freeze --execute "cargo run --example tui_demo" -o /tmp/capture.png
2. ビジョンモデルを使って PNG を分析します
3. 枠線付きのボックスと中央揃えのテキストを確認します
4. 視覚的検証の結果を報告します

例 4：テキストをすばやく検証する

入力：

/tui-validate buffer:"[iter 3/10] 04:32 | 🔨 Builder | ▶ auto" criteria:ralph-header output_format:text

手順：

1. テキストモードでバッファーを使う場合、freeze は不要なので、テキストを直接分析します
2. イテレーション形式、経過時間、帽子、モードインジケーターを確認します
3. 検証結果を報告します

基準の定義

ralph-header（完全な定義）

name: ralph-header
description: Ralph TUI header component validation
requirements:
  - name: iteration_counter
    description: Shows iteration in [iter N] or [iter N/M] format
    required: true
    pattern: '\[iter \d+(/\d+)?\]'

  - name: elapsed_time
    description: Shows elapsed time in MM:SS format
    required: true
    pattern: '\d{2}:\d{2}'

  - name: hat_indicator
    description: Shows current hat with emoji prefix
    required: true
    examples: ["🔨 Builder", "📋 Planner", "🎯 Executor"]

  - name: mode_indicator
    description: Shows loop mode status
    required: true
    values: ["▶ auto", "⏸ paused"]

  - name: scroll_indicator
    description: Shows [SCROLL] when in scroll mode
    required: false
    pattern: '\[SCROLL\]'

  - name: idle_countdown
    description: Shows idle timeout when present
    required: false
    pattern: 'idle: \d+s'

ralph-footer（完全な定義）

name: ralph-footer
description: Ralph TUI footer component validation
requirements:
  - name: activity_indicator
    description: Shows current activity state
    required: true
    values: ["◉ active", "◯ idle", "■ done"]

  - name: event_topic
    description: Shows last event topic
    required: false
    examples: ["task.start", "build.done", "loop.terminate"]

  - name: search_display
    description: Shows search query and match count when searching
    required: false
    pattern: 'Search: .+ \d+/\d+'

ralph-full（完全な定義）

name: ralph-full
description: Complete Ralph TUI layout validation
requirements:
  - name: header_section
    description: Header at top with iteration, time, hat, and mode
    required: true
    references: ralph-header

  - name: content_section
    description: Main terminal content area
    required: true
    checks:
      - Has visible content or is ready for content
      - Properly bounded between header and footer

  - name: footer_section
    description: Footer at bottom with activity status
    required: true
    references: ralph-footer

  - name: visual_hierarchy
    description: Clear visual separation between sections
    required: true
    checks:
      - Borders or spacing between sections
      - Consistent width across sections

トラブルシューティング

freeze が見つからない

# macOS
brew install charmbracelet/tap/freeze

# Linux (via Go)
go install github.com/charmbracelet/freeze@latest

# Verify installation
freeze --version

tmux のキャプチャに失敗する

• tmux セッションが存在することを確認します：tmux list-sessions
• ペイン番号を確認します：tmux list-panes -t {session}
• 特定のペインをキャプチャしてみます：tmux capture-pane -pet {session}:{pane}

キャプチャ画像のレンダリングに乱れがある

• freeze のターミナルエミュレーター設定を変更してみます
• 一貫した色にするには、--theme フラグを使います
• ターミナルのサイズが TUI の想定と一致していることを確認します

LLM の判定が厳しすぎる／寛容すぎる

• 基準がより具体的になるように調整します
• 正確な一致が必要な場合は、strict モードを使います
• レイアウトや要素の有無を確認する場合は、semantic モードを使います

テストとの統合

このスキルはテストスイートに統合できます。

// In tests/tui_validation.rs
#[test]
#[ignore] // Run with: cargo test -- --ignored
fn validate_header_rendering() {
    // 1. Render header to buffer
    let output = render_header_to_string(&test_state);

    // 2. Save to temp file
    std::fs::write("/tmp/header_test.txt", &output).unwrap();

    // 3. Run tui-validate skill (via CLI or programmatic)
    // /tui-validate file:/tmp/header_test.txt criteria:ralph-header

    // 4. Assert validation passed
}

ベストプラクティス

1. レイアウトの確認には意味的検証を使います - 軽微な書式の違いで失敗しないようにします
2. 内容の要件には厳密な検証を使います - 重要な情報が含まれていることを確認します
3. 失敗時はスクリーンショットを保存します - デバッグに役立ちます
4. さまざまなターミナルサイズでテストします - TUI はサイズに応じて表示を調整できる必要があります
5. ユニットテストと組み合わせます - 統合・視覚的検証にはこれを、ロジックにはユニットテストを使います