# 機能設計書 11-omz plugin list

## 概要

本ドキュメントは、Oh My Zshの`omz plugin list`コマンドの機能設計について記載する。このコマンドはOh My Zshで利用可能なプラグイン一覧を表示する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Oh My Zshには300以上のビルトインプラグインが存在し、さらにユーザーがカスタムプラグインを追加することも可能である。ユーザーが利用可能なプラグインを把握し、適切なプラグインを選択・有効化するために、プラグイン一覧を確認する機能が必要となる。本機能は、ビルトインプラグインとカスタムプラグインの両方を一覧表示し、ユーザーのプラグイン管理を支援する。

**機能の利用シーン**：
- 新規にOh My Zshを導入したユーザーが利用可能なプラグインを探索する場合
- 現在有効化されているプラグインを確認したい場合（`--enabled`オプション使用）
- プラグインの有効化（`omz plugin enable`）前に、プラグイン名を確認する場合
- シェルスクリプト等でプラグイン一覧を取得してパイプ処理する場合

**主要な処理内容**：
1. `--enabled`オプションの有無を判定し、表示対象を決定する
2. `$ZSH_CUSTOM/plugins/`ディレクトリからカスタムプラグインを収集する
3. `$ZSH/plugins/`ディレクトリからビルトインプラグインを収集する
4. 標準出力がTTYかパイプかを判定し、出力形式を決定する
5. TTYの場合はカテゴリ別にフォーマットして表示、パイプの場合は1行1プラグインで出力する

**関連システム・外部連携**：特になし。ローカルファイルシステムのみを参照する。

**権限による制御**：特になし。プラグインディレクトリへの読み取り権限があれば実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | omz plugin list | 主画面 | 利用可能なプラグイン一覧を表示（--enabledで有効プラグインのみ） |

## 機能種別

データ参照・一覧表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --enabled | フラグ | No | 有効化済みプラグインのみを表示 | 値は不要（フラグの存在のみ判定） |

### 入力データソース

- `$ZSH_CUSTOM/plugins/`ディレクトリ: カスタムプラグインの格納場所
- `$ZSH/plugins/`ディレクトリ: ビルトインプラグインの格納場所
- `$plugins`配列: 現在有効化されているプラグインのリスト（`--enabled`オプション時のみ使用）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| custom_plugins | 配列 | カスタムプラグイン名の一覧 |
| builtin_plugins | 配列 | ビルトインプラグイン名の一覧 |

### 出力先

- 標準出力（ターミナル）: カテゴリ別にフォーマットされた表示
- 標準出力（パイプ）: 1行1プラグイン形式での出力

### 出力形式

**TTY出力時**:
```
Custom plugins:
plugin1  plugin2  plugin3

Built-in plugins:
git  docker  npm  ...
```

**パイプ出力時**:
```
plugin1
plugin2
plugin3
...
```

## 処理フロー

### 処理シーケンス

```
1. オプション解析
   └─ $1が"--enabled"かどうかを判定

2. プラグイン収集（--enabledの場合）
   ├─ $plugins配列をイテレート
   ├─ 各プラグインがカスタムかビルトインか判定
   └─ それぞれの配列に振り分け

3. プラグイン収集（通常の場合）
   ├─ $ZSH_CUSTOM/plugins/*からカスタムプラグインを取得
   └─ $ZSH/plugins/*からビルトインプラグインを取得

4. 出力先判定
   └─ [ ! -t 1 ] でTTYかパイプかを判定

5. 出力
   ├─ パイプ: print -l で1行1プラグイン出力
   └─ TTY: カテゴリヘッダー付きでカラム形式出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{--enabled オプション?}
    B -->|Yes| C[$plugins配列をイテレート]
    C --> D{各プラグインの所在確認}
    D -->|$ZSH_CUSTOM| E[custom_pluginsに追加]
    D -->|$ZSH| F[builtin_pluginsに追加]
    B -->|No| G[ディレクトリからプラグイン一覧取得]
    G --> H[custom_plugins: $ZSH_CUSTOM/plugins/*]
    G --> I[builtin_plugins: $ZSH/plugins/*]
    E --> J{出力先はTTY?}
    F --> J
    H --> J
    I --> J
    J -->|No| K[1行1プラグインで出力]
    J -->|Yes| L{カスタムプラグインあり?}
    L -->|Yes| M[Custom plugins:ヘッダー出力]
    M --> N[カスタムプラグインをカラム出力]
    L -->|No| O{ビルトインプラグインあり?}
    N --> O
    O -->|Yes| P[Built-in plugins:ヘッダー出力]
    P --> Q[ビルトインプラグインをカラム出力]
    O -->|No| R[終了]
    Q --> R
    K --> R
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | プラグイン検出ルール | ディレクトリ内に`_*`または`*.plugin.zsh`ファイルが存在するディレクトリをプラグインとして認識 | 常時 |
| BR-02 | カスタム優先ルール | `--enabled`時、同名プラグインはカスタムを優先して表示 | --enabledオプション使用時 |
| BR-03 | 出力形式切り替え | パイプ処理時は機械可読形式（1行1プラグイン）で出力 | stdout が非TTYの場合 |

### 計算ロジック

特になし。

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

本機能ではデータベース操作は行わない。ファイルシステムのみを参照する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ディレクトリ不在 | $ZSH_CUSTOMまたは$ZSHディレクトリが存在しない | 空の配列として処理（エラーにならない） |

### リトライ仕様

リトライは行わない。

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

該当なし（データベース操作なし）。

## パフォーマンス要件

- 通常の環境（300プラグイン程度）では1秒以内に応答すること
- ディレクトリ走査にはzshのglob機能を使用し、高速に処理する

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

- プラグインディレクトリの読み取り権限のみを使用
- ファイルの内容は読み取らず、ディレクトリ名のみを取得
- 出力時にシェルエスケープ（`${(q-)}`）を行い、特殊文字を含むプラグイン名も安全に表示

## 備考

- `print -lac`オプションにより、ターミナル幅に応じて自動的にカラム数が調整される
- カスタムプラグインとビルトインプラグインは別セクションとして表示され、識別が容易

---

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

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

### 推奨読解順序

#### Step 1: 関数の全体構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | `_omz::plugin::list`関数の定義位置（456-491行目）を確認 |

**読解のコツ**: zshの配列操作記法に注目。`(-/N:t)`はディレクトリのみ（`-/`）、エラー無視（`N`）、末尾部分（`:t`）を意味する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | omz関数（3-21行目）からのコマンドディスパッチを確認 |
| 2-2 | cli.zsh | `lib/cli.zsh` | _omz::plugin関数（205-226行目）からのサブコマンドディスパッチを確認 |

**主要処理フロー**:
1. **3-21行目**: `omz`関数がコマンドライン引数を解析し、`_omz::$command`を呼び出す
2. **205-226行目**: `_omz::plugin`関数が`list`サブコマンドを受け取り、`_omz::plugin::list`を呼び出す

#### Step 3: プラグイン一覧取得処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | `_omz::plugin::list`関数（456-491行目）の実装詳細 |

**主要処理フロー**:
- **457行目**: ローカル変数の宣言
- **460-468行目**: `--enabled`オプション時の処理（$plugins配列からの収集）
- **469-472行目**: 通常時の処理（ディレクトリからの収集）
- **474-478行目**: パイプ出力時の処理（`print -l`で1行1プラグイン）
- **480-490行目**: TTY出力時の処理（カテゴリ別表示）

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

```
omz (3-21行目)
    │
    └─ _omz::plugin (205-226行目)
           │
           └─ _omz::plugin::list (456-491行目)
                  │
                  ├─ [--enabledの場合] $plugins配列をイテレート
                  │
                  └─ [通常の場合] glob展開でディレクトリ一覧取得
```

### データフロー図

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

コマンドライン引数   ───▶ オプション解析                ───▶ 出力先判定
      │                        │                              │
      └─ --enabled        $plugins配列 or                     ├─ TTY: カテゴリ別表示
                          ディレクトリglob展開                │
                               │                              └─ パイプ: 1行1プラグイン
                               ▼
                     custom_plugins配列
                     builtin_plugins配列
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omzコマンドのCLI実装。_omz::plugin::list関数を含む |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | $plugins配列の初期化とプラグイン読み込みを行うメインスクリプト |
