# 機能設計書 89-アップデート確認

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるアップデート確認機能の設計仕様を記載する。

### 本機能の処理概要

アップデート確認機能は、新しいバージョンのGhosttyが利用可能かどうかを確認し、ユーザーに通知する機能である。macOSではSparkleフレームワークを使用して自動更新を管理する。

**業務上の目的・背景**：
ユーザーが常に最新バージョンのGhosttyを使用できるようにすることで、新機能やバグ修正、セキュリティパッチを確実に適用できるようにする。

**機能の利用シーン**：
- メニューから「アップデートを確認」を選択した場合
- キーバインドから`check_for_updates`アクションを実行した場合
- 自動更新設定による定期的なチェック

**主要な処理内容**：
1. キーバインドアクション`check_for_updates`を受け取る
2. Sparkle（macOS）を通じて更新サーバーに問い合わせ
3. 新しいバージョンが利用可能な場合、アップデートポップオーバーを表示
4. ユーザーの選択に応じてダウンロード・インストールを実行

**関連システム・外部連携**：
- Sparkleフレームワーク（macOS）
- 更新サーバー（appcast.xml）

**権限による制御**：
特に権限による制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 遷移元 | アップデート通知オーバーレイ表示 |
| 12 | アップデートポップオーバー | 主画面 | アップデート確認、ダウンロード、インストール進行状況表示 |

## 機能種別

システム連携 / ユーザー通知

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | - | - | パラメータなしのアクション | - |

### 入力データソース

- キーバインドアクション
- メニュー操作
- 自動更新タイマー

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 更新情報 | UpdateViewModel | 新バージョンの情報 |
| ダウンロード進捗 | Float | ダウンロード進捗率 |

### 出力先

アップデートポップオーバーUI

## 処理フロー

### 処理シーケンス

```
1. アクション受信
   └─ check_for_updatesアクション
2. 状態確認
   ├─ idle: 更新チェック開始
   └─ その他: 既存の状態をキャンセルして再チェック
3. Sparkle呼び出し
   └─ updater.checkForUpdates()
4. サーバー応答処理
   ├─ 更新あり: アップデート情報表示
   └─ 更新なし: アイドル状態に戻る
5. ユーザー操作
   ├─ ダウンロード: ダウンロード開始
   ├─ インストール: アプリ再起動
   └─ キャンセル: アイドル状態に戻る
```

### フローチャート

```mermaid
flowchart TD
    A[check_for_updates] --> B{macOS環境?}
    B -->|No| C[何もしない]
    B -->|Yes| D{現在の状態}
    D -->|idle| E[updater.checkForUpdates]
    D -->|その他| F[既存状態キャンセル]
    F --> G[100ms待機]
    G --> E
    E --> H{更新あり?}
    H -->|No| I[アイドル状態]
    H -->|Yes| J[アップデート情報表示]
    J --> K{ユーザー選択}
    K -->|ダウンロード| L[ダウンロード開始]
    K -->|後で| I
    L --> M[ダウンロード進捗表示]
    M --> N{ダウンロード完了?}
    N -->|No| M
    N -->|Yes| O[インストール準備]
    O --> P{インストール?}
    P -->|Yes| Q[アプリ再起動・インストール]
    P -->|No| I
    C --> R[終了]
    I --> R
    Q --> R
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-89-01 | macOS限定 | 本機能はmacOSでのみ実装 | 常時 |
| BR-89-02 | Sparkle使用 | SPUUpdaterを使用して更新を管理 | macOS |
| BR-89-03 | 状態管理 | UpdateViewModelで状態を管理 | 常時 |
| BR-89-04 | 自動更新設定 | auto-updates設定で動作を制御 | 常時 |

### 計算ロジック

auto-updates設定:
- `off`: 自動チェックなし（手動のみ）
- `check`: 自動チェックのみ（ダウンロードは手動）
- `download`: 自動ダウンロードまで

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | エラー状態 | Sparkle初期化失敗 | エラー状態でリトライオプション表示 |
| - | エラー状態 | ネットワークエラー | エラー状態でリトライオプション表示 |
| - | エラー状態 | ダウンロード失敗 | エラー状態でリトライオプション表示 |

### リトライ仕様

エラー発生時はリトライオプションを表示し、ユーザーが手動でリトライ可能。

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

該当なし。

## パフォーマンス要件

- 更新チェックは非同期で実行
- ダウンロードはバックグラウンドで実行可能

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

- Sparkleは署名検証を行い、改ざんされた更新を拒否
- HTTPS経由での更新サーバーへのアクセス

## 備考

- GTK（Linux）環境では本機能は未実装
- コマンドパレットでもGTKではフィルタされる

---

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

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

### 推奨読解順序

#### Step 1: アクション定義を理解する

まず、アクションの定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Binding.zig | `src/input/Binding.zig` | check_for_updates アクション定義（821-824行目） |
| 1-2 | action.zig | `src/apprt/action.zig` | check_for_updates アクション定義（302行目） |

**読解のコツ**: `check_for_updates`はmacOSのみ実装されており、GTKではフィルタされる。

#### Step 2: macOS実装を理解する

macOS（Swift）での更新コントローラー実装。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | UpdateController.swift | `macos/Sources/Features/Update/UpdateController.swift` | Sparkle連携 |

**主要処理フロー**:
- **10-17行目**: UpdateControllerクラス定義、SPUUpdater保持
- **24-36行目**: init - Sparkle初期化
- **46-61行目**: startUpdater - 更新機能開始
- **63-89行目**: installUpdate - 強制インストール処理
- **91-111行目**: checkForUpdates - 更新チェック実行

#### Step 3: App.zigでのアクション処理を理解する

Zigコードでのアクションディスパッチ。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | App.zig | `src/App.zig` | check_for_updatesのperformAction呼び出し（451行目） |

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

```
キーバインドアクション / メニュー
    │
    └─ check_for_updates
           │
           ▼
    App.zig
           │
           └─ rt_app.performAction(.app, .check_for_updates)
                  │
                  ▼
           [macOS環境のみ]
                  │
                  ▼
           UpdateController.swift
                  │
                  └─ checkForUpdates()
                         │
                         ▼
                  SPUUpdater (Sparkle)
                         │
                         ▼
                  更新サーバー (appcast.xml)
                         │
                         ▼
                  UpdateViewModel 状態更新
                         │
                         ▼
                  アップデートポップオーバー表示
```

### データフロー図

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

キーバインド ───▶ アクション判定 ───▶ プラットフォーム判定
                                              │
                                              ▼
                                    [macOS環境のみ]
                                              │
                                              ▼
                                    UpdateController
                                              │
                                              ▼
                                    Sparkle SPUUpdater
                                              │
                                              ▼
                                    更新サーバー問い合わせ
                                              │
                                              ▼
                                    UpdateViewModel更新
                                              │
                                              ▼
                                    アップデートポップオーバー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Binding.zig | `src/input/Binding.zig` | ソース | check_for_updatesアクション定義 |
| action.zig | `src/apprt/action.zig` | ソース | apprレベルのアクション定義 |
| App.zig | `src/App.zig` | ソース | アクション処理のディスパッチ |
| UpdateController.swift | `macos/Sources/Features/Update/UpdateController.swift` | ソース | Sparkle連携コントローラー |
| UpdateDriver.swift | `macos/Sources/Features/Update/UpdateDriver.swift` | ソース | SparkleのUserDriver実装 |
| UpdateDelegate.swift | `macos/Sources/Features/Update/UpdateDelegate.swift` | ソース | Sparkleデリゲート |
| UpdateViewModel.swift | `macos/Sources/Features/Update/UpdateViewModel.swift` | ソース | 更新状態管理 |
| AppDelegate.swift | `macos/Sources/App/macOS/AppDelegate.swift` | ソース | アプリデリゲートでの更新起動 |
| command_palette.zig | `src/apprt/gtk/class/command_palette.zig` | ソース | GTKでのフィルタリング |
