# 画面設計書 4-omz plugin info

## 概要

本ドキュメントは、Oh My Zshの`omz plugin info`コマンドインターフェースの画面設計書です。指定されたプラグインのREADME.mdファイルを表示し、プラグインの詳細情報を提供する機能を定義します。

### 本画面の処理概要

`omz plugin info`コマンドは、指定されたプラグインのドキュメント（README.md）を表示するコマンドです。プラグインの機能説明、使用方法、設定オプションなどを確認できます。

**業務上の目的・背景**：Oh My Zshには多数のプラグインが存在し、各プラグインは独自の機能、エイリアス、設定オプションを持っています。ユーザーがプラグインを有効化する前にその機能を理解し、適切に設定するためには、ドキュメントへの容易なアクセスが必要です。本コマンドにより、GitHubリポジトリにアクセスすることなく、ターミナル上でプラグインのドキュメントを確認できます。

**画面へのアクセス方法**：ターミナルで以下のコマンドを実行します。
- `omz plugin info <plugin>` - 指定プラグインのREADMEを表示

**主要な操作・処理内容**：
1. プラグイン名の引数を検証
2. カスタムプラグインディレクトリ（`$ZSH_CUSTOM/plugins/`）でREADME.mdを検索
3. 見つからない場合、ビルトインプラグインディレクトリ（`$ZSH/plugins/`）で検索
4. 利用可能なツール（glow、bat、less）に応じて最適な形式で表示
5. パイプ出力時はプレーンテキストで出力

**画面遷移**：
- 遷移元：`omz plugin`コマンドから
- 遷移先：表示完了後（またはページャー終了後）、シェルプロンプトに戻る

**権限による表示制御**：なし。ファイルシステムへの読み取りアクセス権のみ必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてプラグイン情報を表示 |
| 10 | omz plugin info | 主機能 | プラグインのREADME.mdを表示する処理を実行 |

## 画面種別

詳細表示（ドキュメント表示）

## URL/ルーティング

```
omz plugin info <plugin>
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| plugin | string | はい | プラグイン名 |

### 出力項目

| 項目名 | 出力先 | 説明 |
|--------|--------|------|
| README内容 | 標準出力（stdout） | プラグインのREADME.mdの内容 |
| エラーメッセージ | 標準エラー出力（stderr） | プラグインが見つからない場合のエラー |

## 表示項目

| 項目 | 説明 | 表示形式 |
|------|------|----------|
| README.md | プラグインのドキュメント全文 | Markdown形式（glowまたはbat使用時）またはプレーンテキスト |

## イベント仕様

### 1-プラグイン情報表示イベント

**トリガー**：`omz plugin info <plugin>`コマンドの実行

**処理フロー**：
1. プラグイン名引数の存在を検証
2. `$ZSH_CUSTOM/plugins/$1/README.md`の存在を確認
3. 見つからない場合、`$ZSH/plugins/$1/README.md`の存在を確認
4. 出力先がパイプかターミナルかを判定
5. パイプ出力時：`cat`でプレーンテキスト出力
6. ターミナル出力時：利用可能なツールを優先順に試行
   - glow（Markdownレンダリング）
   - bat（シンタックスハイライト）
   - less（ページャー）
   - cat（フォールバック）

**データの流れ**：
```
ユーザー入力 → _omz::plugin::info → README.md検索 → 表示ツール選択 → stdout
```

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| プラグイン情報表示 | なし | - | データベース操作なし |

本コマンドは情報表示のみを行い、ファイルシステムやデータベースへの変更は発生しません。

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|---------------|---------------|----------|
| 使用方法 | `Usage: omz plugin info <plugin>` | プラグイン名が指定されていない場合 |
| エラー | `the '<plugin>' plugin doesn't have a README file` | プラグインは存在するがREADMEがない場合 |
| エラー | `'<plugin>' plugin not found` | プラグインが存在しない場合 |

## 例外処理

| 例外状態 | 処理内容 | 戻り値 |
|----------|----------|--------|
| 引数なし | 使用方法を表示 | 1 |
| プラグイン未発見 | エラーメッセージを表示 | 1 |
| READMEファイルなし | エラーメッセージを表示 | 1 |
| 表示ツールエラー | ツールの終了コードを返却 | ツール依存 |

## 備考

- 表示ツールの優先順位：glow > bat > less > cat
- glowはMarkdownを美しくレンダリングする専用ツール（要別途インストール）
- batはシンタックスハイライト付きでファイルを表示するツール（要別途インストール）
- パイプ出力時は常にcatが使用され、プレーンテキストで出力される
- カスタムプラグインが優先的に検索されるため、同名のビルトインを上書き可能

---

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

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

### 推奨読解順序

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

プラグイン情報表示機能で使用される主要な変数とパスを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | 行51-55で`$ZSH`と`$ZSH_CUSTOM`変数の初期化を確認 |
| 1-2 | cli.zsh | `lib/cli.zsh` | 行424-425でREADMEファイルの検索パスを確認 |

**読解のコツ**: zshでは`${+commands[name]}`でコマンドの存在チェックができます。`case 1 in ${+commands[glow]})`パターンは、glowコマンドが存在する場合（`${+commands[glow]}`が1を返す）に一致します。

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

プラグイン情報コマンドのエントリーポイントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | `_omz::plugin::info`関数（418-454行目）が処理の本体 |

**主要処理フロー**:
1. **行419-421**: 引数チェック。プラグイン名がなければ使用方法を表示
2. **行424-425**: README.mdのパスを定義（カスタム優先、ビルトインフォールバック）
3. **行426-444**: READMEファイルが見つかった場合の処理
4. **行447-451**: プラグインが存在するがREADMEがない場合のエラー
5. **行450**: プラグインが存在しない場合のエラー

#### Step 3: 表示ツール選択ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | 行427-431でパイプ出力判定を確認 |
| 3-2 | cli.zsh | `lib/cli.zsh` | 行433-442で表示ツール選択のcase文を確認 |

**主要処理フロー**:
- **行428**: `[[ ! -t 1 ]]`でパイプ出力かどうかを判定
- **行429-431**: パイプ出力時はcatで出力して終了
- **行437**: glowが利用可能な場合、`glow -p`でページャー付き表示
- **行438**: batが利用可能な場合、`bat -l md --style plain`で表示
- **行439**: lessが利用可能な場合、lessで表示
- **行440**: フォールバックとしてcatで表示

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

```
omz plugin info <plugin>
    │
    └─ omz (エントリーポイント)
           │
           └─ _omz::plugin
                  │
                  └─ _omz::plugin::info
                         │
                         ├─ [引数なし]
                         │      └─ 使用方法表示 → return 1
                         │
                         ├─ README.md検索
                         │      ├─ $ZSH_CUSTOM/plugins/$1/README.md
                         │      └─ $ZSH/plugins/$1/README.md
                         │
                         ├─ [README発見]
                         │      ├─ [パイプ出力] → cat
                         │      └─ [ターミナル出力]
                         │             ├─ glow -p (優先度1)
                         │             ├─ bat -l md (優先度2)
                         │             ├─ less (優先度3)
                         │             └─ cat (フォールバック)
                         │
                         └─ [README未発見]
                                ├─ [プラグインあり] → "doesn't have a README"
                                └─ [プラグインなし] → "not found"
```

### データフロー図

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

プラグイン名 ───▶ _omz::plugin::info
                       │
                       ▼
                 README.md検索
                       │
         ┌─────────────┴─────────────┐
         │                           │
    [発見]                      [未発見]
         │                           │
         ▼                           ▼
    出力先判定                  エラーメッセージ
         │                           │
    ┌────┴────┐                      │
    │         │                      │
 [パイプ]  [ターミナル]              │
    │         │                      │
    ▼         ▼                      │
   cat    ツール選択                 │
             │                       │
    ┌────┬───┴───┬────┐              │
    ▼    ▼       ▼    ▼              ▼
  glow  bat    less  cat          stderr
    │    │       │    │
    └────┴───────┴────┘
              │
              ▼
           stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omz plugin infoコマンドの実装 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | $ZSH、$ZSH_CUSTOM変数の定義 |
| README.md | `plugins/*/README.md` | ドキュメント | 各プラグインのドキュメント |
