# 通知設計書 7-アップデート確認プロンプト

## 概要

本ドキュメントは、Oh My Zshのアップデート確認機能における確認プロンプト通知について、その設計仕様を定義するものである。

### 本通知の処理概要

Oh My Zshは、定期的に更新の確認を行い、更新が利用可能な場合にユーザーに更新の意思を確認するプロンプトを表示する機能を提供する。この通知は、更新モードがデフォルトの「prompt」に設定されている場合に表示される。

**業務上の目的・背景**：Oh My Zshの更新は新機能やバグ修正を含むが、更新により既存の設定やカスタマイズに影響が出る可能性がある。確認プロンプトを表示することで、ユーザーは更新のタイミングを自分でコントロールでき、作業の中断を最小限に抑えることができる。デフォルトの更新モードとして、ユーザーに選択権を与えるバランスの取れたアプローチを提供する。

**通知の送信タイミング**：シェル起動時にhandle_update関数が実行され、以下の条件を満たす場合に確認プロンプトが表示される：(1) 前回の更新確認から指定日数（デフォルト13日）が経過、(2) 更新が利用可能、(3) 更新モードが「prompt」、(4) ユーザーがまだ入力を開始していない。

**通知の受信者**：シェルを起動したユーザー自身。ターミナル上にテキストメッセージとして表示され、キー入力を待機する。

**通知内容の概要**：「[oh-my-zsh] Would you like to update? [Y/n]」というプロンプトがターミナルに表示され、ユーザーのキー入力を待つ。

**期待されるアクション**：受信者はY/y/Enterキーで更新を開始するか、N/nキーで更新をスキップするか選択する。

## 通知種別

ターミナル対話プロンプト

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（printf + read による対話入力） |
| 優先度 | 中 |
| リトライ | 無し |

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

現在のシェルセッションの標準出力/入力に対してプロンプトを表示し、ユーザー入力を待機する。

## 通知テンプレート

### ターミナル出力の場合

| 項目 | 内容 |
|-----|------|
| プレフィックス | `[oh-my-zsh]` |
| メッセージ | `Would you like to update? [Y/n]` |
| 入力待機 | 1文字のキー入力を待機 |

### 本文テンプレート

```
[oh-my-zsh] Would you like to update? [Y/n]
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | - | - | 添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| N/A | 固定メッセージのため変数なし | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| シェル起動 | handle_update関数実行 | update_mode=prompt かつ has_typed_input=false | 更新利用可能時に確認プロンプト表示 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| update_mode=disabled | 自動更新が無効化されている場合 |
| 更新確認間隔未満 | 前回確認から指定日数が経過していない場合 |
| 更新なし | リモートとローカルのHEADが一致する場合 |
| update_mode=auto/background-alpha | 自動更新モードの場合 |
| update_mode=reminder | リマインダーモードの場合 |
| has_typed_input=true | ユーザーが既に入力を開始している場合（リマインダーに遷移） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[シェル起動] --> B[handle_update呼び出し]
    B --> C{更新確認間隔経過?}
    C -->|No| D[終了]
    C -->|Yes| E{更新利用可能?}
    E -->|No| F[LAST_EPOCH更新]
    F --> D
    E -->|Yes| G{update_mode=prompt?}
    G -->|No| H[他モードへ分岐]
    G -->|Yes| I{入力済み?}
    I -->|Yes| J[リマインダー表示]
    I -->|No| K[確認プロンプト表示]
    K --> L[read -r -k 1]
    L --> M{入力値判定}
    M -->|Y/y/Enter| N[update_ohmyzsh実行]
    M -->|N/n| O[LAST_EPOCH更新]
    M -->|その他| P[手動更新案内表示]
    N --> D
    O --> P
    P --> D
    J --> D
```

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

### 参照テーブル一覧

本通知はデータベースを使用しない。ファイルとシェル変数で状態管理を行う。

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | - | データベース不使用 |

### 参照ファイル一覧

| ファイル | パス | 用途 |
|---------|------|------|
| .zsh-update | `$ZSH_CACHE_DIR/.zsh-update` | 最終更新確認日時（LAST_EPOCH）を保存 |

### シェル変数・zstyle一覧

| 設定名 | 用途 | デフォルト値 |
|--------|------|-------------|
| :omz:update mode | 更新モード | prompt |
| :omz:update frequency | 更新確認間隔（日数） | 13 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 入力タイムアウト | ユーザーが応答しない | 特にタイムアウトは設定されていない |
| 更新失敗 | git pull等が失敗 | エラーメッセージを表示 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 表示頻度 | 更新確認間隔（デフォルト13日）ごとに1回 |

### 配信時間帯

制限なし（シェル起動時）

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

- プロンプトは固定文字列であり、機密情報は含まれない
- ローカル対話のみであり、ネットワーク経由での送信は行われない
- 更新処理自体はgitコマンドを使用してGitHubからpullする

## 備考

- read -r -k 1 で1文字のみを読み取る
- Enterキー（改行）はY/yと同じ扱いで更新を開始
- N/n以外の入力は更新をスキップし、手動更新の案内を表示
- 更新をスキップした場合もLAST_EPOCHは更新される（次回確認まで再表示されない）

---

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

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

### 推奨読解順序

#### Step 1: 更新モード設定を理解する

デフォルトの更新モード（prompt）を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 14-20行目のzstyleによる更新モード取得とデフォルト値を確認 |

**読解のコツ**: update_mode=prompt がデフォルト値（15行目）。

#### Step 2: プロンプト表示処理を理解する

確認プロンプトの表示と入力処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 233-242行目の確認プロンプト表示と入力処理を理解 |

**主要処理フロー**:
- **235行目**: `printf "[oh-my-zsh] Would you like to update? [Y/n] "` - プロンプト表示
- **236行目**: `read -r -k 1 option` - 1文字入力待機
- **237行目**: `[[ "$option" = $'\n' ]] || echo` - 改行処理
- **238-241行目**: case文による入力判定

#### Step 3: 入力値による分岐を理解する

ユーザー入力による処理の分岐を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 238-242行目のcase文で入力値判定を理解 |

**主要処理フロー**:
- **239行目**: `[yY$'\n'])` - Y/y/Enterで更新実行
- **240行目**: `[nN])` - N/nでLAST_EPOCH更新のみ
- **241行目**: `*)` - その他で手動更新案内

#### Step 4: 手動更新案内を理解する

更新スキップ時の案内メッセージを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 241行目の手動更新案内メッセージを確認 |

**主要処理フロー**:
- **241行目**: `echo "[oh-my-zsh] You can update manually by running \`omz update\`"` - 手動更新案内

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

```
[シェル起動]
    │
    ├─ check_for_upgrade.sh 読み込み
    │      │
    │      └─ handle_update 呼び出し
    │             │
    │             ├─ .zsh-update ファイル読み込み
    │             │
    │             ├─ 更新間隔チェック
    │             │
    │             ├─ is_update_available
    │             │
    │             └─ [update_mode=prompt AND NOT has_typed_input?]
    │                    │
    │                    ├─ Yes ──▶ printf "[oh-my-zsh] Would you like to update? [Y/n] "
    │                    │          read -r -k 1 option
    │                    │          │
    │                    │          ├─ [Y/y/Enter] ──▶ update_ohmyzsh
    │                    │          │
    │                    │          ├─ [N/n] ──▶ update_last_updated_file
    │                    │          │             echo "You can update manually..."
    │                    │          │
    │                    │          └─ [その他] ──▶ echo "You can update manually..."
    │                    │
    │                    └─ No ──▶ 他のモードへ
    │
    └─ シェルプロンプト表示
```

### データフロー図

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

$ZSH_CACHE_DIR/.zsh-update ─▶ handle_update
(LAST_EPOCH)                       │
                                   │
zstyle :omz:update mode ──────────▶├─ 更新モード判定 (prompt)
                                   │
is_update_available ──────────────▶├─ 更新確認
                                   │
has_typed_input ──────────────────▶├─ 入力検出
                                   │
                                   └─ プロンプト表示 ────────▶ stdout
                                          │                   │
                                          │                   ▼
                                          │           "[oh-my-zsh] Would you like...?"
                                          │
stdin ────────────────────────────────────▶ read -r -k 1
                                          │
                                          └─ 入力判定
                                                 │
                                                 ├─ Y/y/Enter ──▶ update_ohmyzsh
                                                 │
                                                 └─ N/n/その他 ──▶ "You can update manually..."
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| check_for_upgrade.sh | `tools/check_for_upgrade.sh` | ソース | 更新確認とプロンプト表示のメインロジック |
| upgrade.sh | `tools/upgrade.sh` | ソース | 実際の更新処理を実行 |
| .zsh-update | `$ZSH_CACHE_DIR/.zsh-update` | データ | 最終更新確認日時を保存 |
