# 通知設計書 9-check_for_updates（アップデート通知）

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるアップデート確認・通知機能の設計について記述する。

### 本通知の処理概要

check_for_updates通知は、新しいバージョンのGhosttyが利用可能であることをユーザーに通知する機能である。macOSではSparkleフレームワークを使用して、自動更新チェックと手動更新チェックの両方をサポートする。

**業務上の目的・背景**：セキュリティ修正やバグ修正、新機能を含む最新バージョンをユーザーに提供するため、アップデートの存在を通知する。ユーザーは通知を受けて、任意のタイミングでアップデートを適用できる。

**通知の送信タイミング**：
- 自動チェック：アプリケーション起動時、またはSparkleのスケジュールに従って定期的に
- 手動チェック：ユーザーがメニューから「Check for Updates」を選択した時

**通知の受信者**：Ghosttyを使用しているmacOSユーザー。

**通知内容の概要**：新しいバージョンが利用可能であること、バージョン番号、リリースノート（オプション）。

**期待されるアクション**：ユーザーはアップデートをダウンロード・インストールするか、後で確認することを選択できる。

## 通知種別

ネイティブアップデートダイアログ（Sparkle）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（バックグラウンドでチェック） |
| 優先度 | 通常 |
| リトライ | Sparkleフレームワークが自動的にリトライを管理 |

### 送信先決定ロジック

macOSアプリケーション全体に対して通知が表示される。

## 通知テンプレート

### アップデート通知の場合

| 項目 | 内容 |
|-----|------|
| タイトル | A new version of Ghostty is available! |
| 本文 | 新バージョンの情報、リリースノート |
| ボタン | Install Update / Later / Skip This Version |

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| currentVersion | String | 必須 | 現在のバージョン |
| newVersion | String | 必須 | 新しいバージョン |
| releaseNotes | String | オプション | リリースノート |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ユーザー操作 | メニューから「Check for Updates」選択 | macOS版 | 手動チェック |
| 自動チェック | アプリ起動時/定期チェック | auto-update != off | Sparkleスケジュール |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| Linux/GTK版 | この機能はmacOS版のみで利用可能 |
| auto-update = off | 自動チェックが無効化されている（手動チェックは可能） |
| SUEnableAutomaticChecks = false | Info.plistで自動チェックが無効化 |
| ネットワーク未接続 | アップデートサーバーに接続できない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[トリガー] --> B{手動/自動?}
    B -->|手動| C[checkForUpdates呼び出し]
    B -->|自動| D{auto-update設定}
    D -->|off| E[チェックしない]
    D -->|check| F[バックグラウンドでチェック]
    D -->|download| G[チェック + 自動ダウンロード]
    C --> H[SPUUpdater.checkForUpdates]
    F --> H
    G --> H
    H --> I{新バージョンあり?}
    I -->|あり| J[UpdateViewModel状態更新]
    I -->|なし| K[処理終了]
    J --> L[アップデートダイアログ表示]
    L --> M{ユーザー選択}
    M -->|Install| N[ダウンロード&インストール]
    M -->|Later| O[後で通知]
    M -->|Skip| P[このバージョンをスキップ]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（ローカルアプリケーション機能）

### 更新テーブル一覧

該当なし（ユーザー設定はUserDefaultsに保存）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ネットワークエラー | アップデートサーバーに接続できない | エラーダイアログ表示、リトライオプション |
| パースエラー | アップデート情報のパースに失敗 | エラーダイアログ表示 |
| ダウンロードエラー | アップデートファイルのダウンロードに失敗 | エラーダイアログ表示、リトライオプション |
| インストールエラー | アップデートのインストールに失敗 | エラーダイアログ表示 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | Sparkleフレームワークが管理 |
| リトライ間隔 | Sparkleフレームワークが管理 |
| リトライ対象エラー | ネットワークエラー |

## 配信設定

### 自動チェック間隔

| 項目 | 内容 |
|-----|------|
| デフォルト間隔 | Sparkleのデフォルト（約24時間） |
| 設定可能 | ユーザー設定（UserDefaults）で変更可能 |

### リリースチャンネル

| チャンネル | 説明 |
|-----------|------|
| stable | 安定版リリース（例：1.0.0） |
| tip | プレリリース版（mainブランチの各コミット） |

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

- アップデートチェックは標準的なネットワークプロトコルを使用し、明示的なトラッキング情報を送信しない
- アップデートファイルはコード署名で検証される
- ダウンロードはHTTPS経由で行われる

## 備考

- macOS版のみで利用可能
- Sparkle 2.9.0フレームワークを使用
- auto-update設定で動作を制御可能（off/check/download）
- auto-update-channel設定でリリースチャンネルを指定可能
- インストール中はアプリケーション終了確認をスキップ
- GTK/Linux版ではパッケージマネージャーによる更新を推奨

---

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

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

### 推奨読解順序

#### Step 1: 設定を理解する

アップデート関連の設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Config.zig | `src/config/Config.zig` | auto-update設定（行3709-3732）を確認 |
| 1-2 | Config.zig | `src/config/Config.zig` | auto-update-channel設定（行3734-3754）を確認 |
| 1-3 | Config.zig | `src/config/Config.zig` | AutoUpdate enum（行9441-9445）を確認 |

**読解のコツ**: auto-updateはoff/check/downloadの3値。nullの場合はSparkleのデフォルト動作。auto-update-channelはstable/tipの2値で、デフォルトは現在のビルドのリリースチャンネルに一致。

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

check_for_updatesアクションの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | action.zig | `src/apprt/action.zig` | check_for_updatesアクション定義（行302）を確認 |
| 2-2 | Binding.zig | `src/input/Binding.zig` | check_for_updatesバインディング（行821-824）を確認 |
| 2-3 | command.zig | `src/input/command.zig` | コマンドパレットでの定義（行654-658）を確認 |

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

macOSでのSparkle連携を追跡する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | UpdateController.swift | `macos/Sources/Features/Update/UpdateController.swift` | UpdateController実装を確認 |
| 3-2 | AppDelegate.swift | `macos/Sources/App/macOS/AppDelegate.swift` | updateController初期化（行135）を確認 |
| 3-3 | AppDelegate.swift | `macos/Sources/App/macOS/AppDelegate.swift` | checkForUpdates関数（行1072-1075）を確認 |
| 3-4 | AppDelegate.swift | `macos/Sources/App/macOS/AppDelegate.swift` | auto-update設定同期（行874-894）を確認 |

**読解のコツ**: UpdateControllerはSparkleのSPUUpdaterをラップし、シンプルなインターフェースを提供。viewModelでUI状態を管理。checkForUpdates()は現在の状態を確認し、idleならすぐにチェック、それ以外なら状態をキャンセルしてからチェック。

#### Step 4: GTK/Linux での非対応を確認

GTK版では未実装であることを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | application.zig | `src/apprt/gtk/class/application.zig` | check_for_updates未実装（行775-780）を確認 |
| 4-2 | command_palette.zig | `src/apprt/gtk/class/command_palette.zig` | GTKでの非サポート（行214）を確認 |

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

```
check_for_updatesトリガー
    |
    ├─ 手動: メニューから「Check for Updates」選択
    |       |
    |       v
    |   AppDelegate.checkForUpdates() (AppDelegate.swift:1072)
    |       |
    |       v
    |   UpdateController.checkForUpdates() (UpdateController.swift:94)
    |
    └─ 自動: アプリ起動時/定期チェック
            |
            v
        UpdateController.startUpdater() (UpdateController.swift:46)
            |
            v
        SPUUpdater.start()
            |
            v
        (Sparkleスケジュールに従って自動チェック)
            |
            v
        SPUUpdater.checkForUpdates() または checkForUpdatesInBackground()
            |
            v
        アップデートサーバーへHTTPリクエスト
            |
            v
        UpdateDriver/UpdateViewModel で状態管理
            |
            v
        アップデートダイアログ表示（新バージョンがある場合）
```

### データフロー図

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

ユーザー操作/自動  ───▶  UpdateController            ───▶  SPUUpdater
                              |
                              v
                         アップデートサーバー
                              |
                              v
                         バージョン比較
                              |
        ┌─────────────────────┴─────────────────────┐
        |                                           |
        v                                           v
    新バージョンなし                            新バージョンあり
        |                                           |
        v                                           v
    処理終了                                    UpdateViewModel更新
                                                    |
                                                    v
                                                ダイアログ表示
                                                    |
                                                    v
                                                ユーザー選択
                                                    |
                        ┌───────────────────────────┼───────────────────────────┐
                        |                           |                           |
                        v                           v                           v
                    Install                       Later                       Skip
                        |
                        v
                    ダウンロード
                        |
                        v
                    インストール
                        |
                        v
                    アプリ再起動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Config.zig | `src/config/Config.zig` | ソース | auto-update、auto-update-channel設定 |
| action.zig | `src/apprt/action.zig` | ソース | check_for_updatesアクション定義 |
| Binding.zig | `src/input/Binding.zig` | ソース | キーバインディング定義 |
| command.zig | `src/input/command.zig` | ソース | コマンドパレット定義 |
| App.zig | `src/App.zig` | ソース | アクション実行（行451） |
| UpdateController.swift | `macos/Sources/Features/Update/UpdateController.swift` | ソース | Sparkle連携 |
| AppDelegate.swift | `macos/Sources/App/macOS/AppDelegate.swift` | ソース | macOSアプリデリゲート |
| application.zig | `src/apprt/gtk/class/application.zig` | ソース | GTK版（未実装） |
| Package.resolved | `macos/Ghostty.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved` | 依存関係 | Sparkle 2.9.0 |
