# 機能設計書 43-バージョン表示

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「バージョン表示」機能の設計を記述する。この機能は、CLIコマンド`+version`または`--version`を通じて、Ghosttyのバージョン情報およびビルド構成の詳細を表示する。

### 本機能の処理概要

**業務上の目的・背景**：ソフトウェアのバージョン情報は、トラブルシューティング、バグレポート、互換性確認において不可欠である。バージョン表示機能は、ユーザーや開発者がGhosttyの正確なバージョン、ビルド構成、依存ライブラリのバージョンを即座に確認できるようにすることで、サポートやデバッグを効率化する。

**機能の利用シーン**：
- バグレポート作成時にバージョン情報を確認する
- 特定の機能が利用可能なバージョンかどうかを確認する
- ビルド構成（使用しているレンダラー、フォントエンジンなど）を確認する
- 更新後に正しいバージョンがインストールされたことを確認する

**主要な処理内容**：
1. バージョン文字列の取得と表示
2. リリースチャンネル情報の表示
3. ビルド構成情報（Zigバージョン、ビルドモード、ランタイム等）の表示
4. プラットフォーム固有情報（GTKバージョン、libadwaita等）の表示
5. TTY検出によるハイパーリンク付き出力（GitHub commitリンク）

**関連システム・外部連携**：
- ビルド時に埋め込まれた定数（build_options、build_config）
- プラットフォーム固有のランタイム情報取得API

**権限による制御**：特になし。すべてのユーザーがバージョン表示を実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | About画面 | 主機能 | バージョン情報の表示（macOS） |

## 機能種別

情報表示 / CLI出力

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | コマンドライン引数なし | - |

### 入力データソース

- コマンドライン: `ghostty +version` または `ghostty --version`
- ビルド時定数: `build_config`, `build_options`

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| version | []const u8 | バージョン文字列（例: "1.0.0"） |
| channel | ReleaseChannel | リリースチャンネル（stable/dev等） |
| zig_version | []const u8 | Zigコンパイラのバージョン |
| build_mode | std.builtin.Mode | ビルドモード（Debug/ReleaseSafe等） |
| app_runtime | AppRuntime | アプリケーションランタイム（gtk/macos等） |
| font_engine | FontBackend | フォントエンジン |
| renderer | RendererType | レンダラータイプ（Metal/OpenGL等） |
| libxev | Backend | I/Oバックエンド |
| gtk_version | Version | GTKバージョン（ビルド時/ランタイム） |
| adw_version | Version | libadwaitaバージョン（ビルド時/ランタイム） |
| kernel_version | ?[]const u8 | カーネルバージョン（Linux） |
| desktop_env | DesktopEnvironment | デスクトップ環境（Linux） |

### 出力先

- 標準出力（stdout）

## 処理フロー

### 処理シーケンス

```
1. TTY検出
   └─ 標準出力がTTYかどうかを判定

2. バージョンヘッダー出力
   └─ TTYの場合はOSC8ハイパーリンク付きでGitHubコミットリンクを出力

3. 基本バージョン情報出力
   └─ バージョン文字列、リリースチャンネル

4. ビルド構成情報出力
   └─ Zigバージョン、ビルドモード、アプリランタイム、フォントエンジン、レンダラー、libxev

5. プラットフォーム固有情報出力（GTKの場合）
   └─ カーネルバージョン、デスクトップ環境、GTKバージョン、libadwaitaバージョン
   └─ X11/Wayland対応状況

6. バッファフラッシュ
   └─ 出力バッファを確実に書き出し
```

### フローチャート

```mermaid
flowchart TD
    A[+version実行] --> B{TTY?}
    B -->|Yes| C[OSC8リンク付きヘッダー出力]
    B -->|No| D[プレーンヘッダー出力]
    C --> E[バージョン情報出力]
    D --> E
    E --> F[ビルド構成出力]
    F --> G{GTKランタイム?}
    G -->|Yes| H[Linux固有情報出力]
    G -->|No| I[出力完了]
    H --> J[GTK/libadwaitaバージョン出力]
    J --> K[X11/Wayland状態出力]
    K --> I
    I --> L[バッファフラッシュ]
    L --> M[終了コード0で終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-43-01 | TTYハイパーリンク | TTY出力時のみOSC8形式のハイパーリンクを付加 | stdout.isTty() == true |
| BR-43-02 | プラットフォーム分岐 | GTKランタイム時のみLinux固有情報を出力 | app_runtime == .gtk |
| BR-43-03 | 正常終了 | バージョン表示は常に終了コード0で終了 | 常時 |

### 計算ロジック

特になし。

## データベース操作仕様

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | I/Oエラー | 標準出力への書き込み失敗 | エラーを返す |

### リトライ仕様

リトライなし。

## トランザクション仕様

トランザクションは使用しない。

## パフォーマンス要件

- 瞬時に実行完了すること（ほぼ静的データの出力のみ）

## セキュリティ考慮事項

- バージョン情報は機密情報を含まない
- ビルドハッシュはオープンソースリポジトリへのリンクに使用

## 備考

- ビルド時にコミットハッシュが埋め込まれている場合、GitHubへのリンクが生成される
- カーネルバージョン取得に失敗した場合は「Kernel information unavailable」と表示

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

ビルド時定数とバージョン関連の型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | build_config.zig | `src/build_config.zig` | version_string、release_channelの定義 |
| 1-2 | version.zig | `src/cli/version.zig` | Options構造体（空、オプションなし） |

**読解のコツ**: `build_options`と`build_config`はビルド時に生成される定数を含む。`@import("build_options")`で参照される。

#### Step 2: エントリーポイントを理解する

CLIコマンドのエントリーポイントとrun関数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | version.zig | `src/cli/version.zig` | run関数の全体構造（17-76行目） |

**主要処理フロー**:
1. **18-23行目**: バッファとstdoutライターの初期化
2. **25-30行目**: TTY検出とOSC8リンク出力
3. **31行目**: バージョンヘッダー出力
4. **34-44行目**: バージョン情報とビルド構成出力
5. **45-71行目**: GTK固有情報の出力

#### Step 3: プラットフォーム固有処理

GTKランタイム時の追加情報出力を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | version.zig | `src/cli/version.zig` | GTK情報出力部分（45-71行目） |
| 3-2 | gtk_version.zig | `src/apprt/gtk/gtk_version.zig` | GTKバージョン取得 |
| 3-3 | adw_version.zig | `src/apprt/gtk/adw_version.zig` | libadwaitaバージョン取得 |

**主要処理フロー**:
- **47-49行目**: カーネルバージョン取得と出力
- **51行目**: デスクトップ環境の検出
- **52-57行目**: GTKバージョン（ビルド時とランタイム）
- **58-63行目**: X11/Waylandの有効/無効状態

### プログラム呼び出し階層図

```
ghostty +version
    │
    └─ cli.version.run
           │
           ├─ stdout.isTty (TTY検出)
           │
           ├─ build_config.version (バージョン定数)
           │      ├─ version_string
           │      ├─ release_channel
           │      └─ build (コミットハッシュ)
           │
           ├─ builtin (Zigビルド情報)
           │      ├─ zig_version_string
           │      └─ mode
           │
           └─ [GTKのみ]
                  ├─ internal_os.getKernelInfo
                  ├─ internal_os.desktopEnvironment
                  ├─ gtk_version (ビルド時/ランタイム)
                  └─ adw_version (ビルド時/ランタイム)
```

### データフロー図

```
[入力]                    [処理]                         [出力]

コマンドライン ──────▶ run関数 ─────────────────▶ 標準出力
(+version)                │
                          │
ビルド時定数 ────────▶ 情報収集
 ├─ build_config          │
 └─ build_options         │
                          │
ランタイム情報 ──────▶ 情報収集
 ├─ GTKバージョン         │
 ├─ カーネル情報          │
 └─ デスクトップ環境      │
                          ▼
                    フォーマット出力 ────────▶ stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| version.zig | `src/cli/version.zig` | ソース | バージョン表示コマンドの実装 |
| build_config.zig | `src/build_config.zig` | ソース | ビルド時設定定数 |
| gtk_version.zig | `src/apprt/gtk/gtk_version.zig` | ソース | GTKバージョン取得 |
| adw_version.zig | `src/apprt/gtk/adw_version.zig` | ソース | libadwaitaバージョン取得 |
| main.zig | `src/os/main.zig` | ソース | OS情報取得（カーネル、デスクトップ環境） |
| ghostty.zig | `src/cli/ghostty.zig` | ソース | CLIアクションの定義 |
