# 画面設計書 3-omz plugin list

## 概要

本ドキュメントは、Oh My Zshの`omz plugin list`コマンドインターフェースの画面設計書です。利用可能なプラグインおよび有効化されているプラグインの一覧を表示する機能を定義します。

### 本画面の処理概要

`omz plugin list`コマンドは、Oh My Zshで利用可能なすべてのプラグイン、または現在有効化されているプラグインの一覧を表示します。プラグインはビルトイン（標準同梱）とカスタム（ユーザー追加）に分類されて表示されます。

**業務上の目的・背景**：Oh My Zshには300以上のビルトインプラグインが存在し、ユーザーは独自のカスタムプラグインを追加することも可能です。この大量のプラグインを効率的に管理するためには、利用可能なプラグインの把握と、現在有効化されているプラグインの確認が不可欠です。本コマンドにより、ユーザーはプラグインの探索、選択、管理を容易に行えます。

**画面へのアクセス方法**：ターミナルで以下のコマンドを実行します。
- `omz plugin list` - すべての利用可能なプラグインを一覧表示
- `omz plugin list --enabled` - 現在有効化されているプラグインのみを一覧表示

**主要な操作・処理内容**：
1. `$ZSH_CUSTOM/plugins/`ディレクトリからカスタムプラグインを検索
2. `$ZSH/plugins/`ディレクトリからビルトインプラグインを検索
3. `--enabled`オプション指定時は`$plugins`配列から有効プラグインをフィルタリング
4. カスタムプラグインとビルトインプラグインを分類して表示
5. パイプ出力時は1行1プラグイン形式で出力

**画面遷移**：
- 遷移元：`omz plugin`コマンドから
- 遷移先：表示完了後、シェルプロンプトに戻る

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてプラグイン一覧を表示 |
| 11 | omz plugin list | 主機能 | 利用可能なプラグイン一覧を表示（--enabledで有効プラグインのみ） |

## 画面種別

一覧表示

## URL/ルーティング

```
omz plugin list [--enabled]
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 | デフォルト |
|--------|-----|------|------|-----------|
| --enabled | flag | いいえ | 有効プラグインのみ表示 | false（全プラグイン表示） |

### 出力項目

| 項目名 | 出力先 | 説明 |
|--------|--------|------|
| プラグイン一覧 | 標準出力（stdout） | カテゴリ別のプラグイン名リスト |

## 表示項目

| 項目 | 説明 | 表示形式 |
|------|------|----------|
| Custom plugins | カスタムプラグインのセクションヘッダー | 太字・下線（`%U%BCustom plugins%b%u:`） |
| カスタムプラグイン名 | $ZSH_CUSTOM/plugins/配下のプラグイン | 複数列表示（print -lac） |
| Built-in plugins | ビルトインプラグインのセクションヘッダー | 太字・下線（`%U%BBuilt-in plugins%b%u:`） |
| ビルトインプラグイン名 | $ZSH/plugins/配下のプラグイン | 複数列表示（print -lac） |

## イベント仕様

### 1-プラグイン一覧表示イベント

**トリガー**：`omz plugin list [--enabled]`コマンドの実行

**処理フロー**：
1. `--enabled`オプションの有無を確認
2. `--enabled`指定時：`$plugins`配列をループし、カスタム/ビルトインを分類
3. `--enabled`未指定時：ディレクトリをグロブでスキャンしてプラグイン名を取得
4. 出力先がパイプかターミナルかを判定（`[[ ! -t 1 ]]`）
5. パイプ出力時：1行1プラグイン形式で出力
6. ターミナル出力時：カテゴリ別にヘッダー付きで複数列表示

**データの流れ**：
```
ユーザー入力 → _omz::plugin::list → ディレクトリスキャン → 分類・整形 → stdout
```

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

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

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

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

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|---------------|---------------|----------|
| ヘッダー | Custom plugins: | カスタムプラグインが存在する場合 |
| ヘッダー | Built-in plugins: | ビルトインプラグインが存在する場合 |

## 例外処理

| 例外状態 | 処理内容 | 戻り値 |
|----------|----------|--------|
| プラグインが見つからない | 空の出力 | 0 |
| ディレクトリアクセスエラー | シェルのデフォルトエラー処理 | 非0 |

## 備考

- プラグイン名は`print -lac`で複数列表示されるため、ターミナル幅に応じて列数が自動調整される
- `--enabled`オプションは有効プラグインのみをフィルタリングするため、無効化されたプラグインは表示されない
- パイプ出力時はエスケープ処理（`${(q-)...}`）されたプラグイン名が1行ずつ出力される
- プラグインの検出は`.plugin.zsh`ファイルまたは`_`で始まる補完ファイルの存在で判定される

---

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

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

### 推奨読解順序

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

プラグイン一覧機能で使用される主要なデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | 行457で`custom_plugins`と`builtin_plugins`の配列宣言を確認 |
| 1-2 | oh-my-zsh.sh | `oh-my-zsh.sh` | `$plugins`配列（ユーザー定義）と`$ZSH`、`$ZSH_CUSTOM`変数を確認 |

**読解のコツ**: zshの`(-/N:t)`は、ディレクトリのみ（`-/`）、存在しなくてもエラーなし（`N`）、末尾のパス要素のみ取得（`:t`）を意味するグロブ修飾子です。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | `_omz::plugin`関数（205-226行目）でサブコマンドルーティングを確認 |
| 2-2 | cli.zsh | `lib/cli.zsh` | `_omz::plugin::list`関数（456-491行目）がlist処理の本体 |

**主要処理フロー**:
1. **行206**: サブコマンドが指定されていない、または対応する関数がない場合はヘルプを表示
2. **行222-225**: サブコマンド関数を動的に呼び出し（`$0::$command "$@"`）

#### Step 3: プラグイン一覧ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | 行460-468で`--enabled`オプション処理を確認 |
| 3-2 | cli.zsh | `lib/cli.zsh` | 行469-472で全プラグイン取得処理を確認 |
| 3-3 | cli.zsh | `lib/cli.zsh` | 行474-490で出力処理を確認 |

**主要処理フロー**:
- **行460**: `--enabled`オプションが指定されているかチェック
- **行461-468**: `$plugins`配列をループし、カスタム/ビルトインを分類
- **行469-472**: ディレクトリグロブでプラグイン名を取得
- **行474-478**: パイプ出力時は`print -l`で1行ずつ出力
- **行480-490**: ターミナル出力時はカテゴリ別ヘッダー付きで`print -lac`

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

```
omz plugin list [--enabled]
    │
    └─ omz (エントリーポイント)
           │
           └─ _omz::plugin
                  │
                  └─ _omz::plugin::list
                         │
                         ├─ [--enabled指定時]
                         │      └─ $plugins配列ループ
                         │             ├─ $ZSH_CUSTOM/plugins/$plugin 存在確認
                         │             └─ $ZSH/plugins/$plugin 存在確認
                         │
                         └─ [--enabled未指定時]
                                └─ ディレクトリグロブ
                                       ├─ $ZSH_CUSTOM/plugins/*(-/N:t)
                                       └─ $ZSH/plugins/*(-/N:t)
```

### データフロー図

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

--enabled オプション ──▶ _omz::plugin::list
                               │
                               ├─ [--enabled]
                               │      │
                               │      ▼
                               │  $plugins配列 ───▶ 分類
                               │
                               └─ [なし]
                                      │
                                      ▼
                               ディレクトリスキャン ───▶ 分類
                                                          │
                                                          ▼
                                                   custom_plugins
                                                   builtin_plugins
                                                          │
                                 [パイプ]                 │              [ターミナル]
                                    │                    │                    │
                                    ▼                    ▼                    ▼
                              print -l             出力判定           print -P / print -lac
                                    │                                        │
                                    └──────────────▶ stdout ◀────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omz plugin listコマンドの実装 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | $ZSH、$ZSH_CUSTOM変数の定義と$plugins配列の利用 |
| .zshrc | `~/.zshrc` | 設定 | $plugins配列のユーザー定義 |
