# 画面設計書 5-omz plugin enable

## 概要

本ドキュメントは、Oh My Zshの`omz plugin enable`コマンドインターフェースの画面設計書です。指定されたプラグインを.zshrcに追加して有効化し、シェルセッションをリロードする機能を定義します。

### 本画面の処理概要

`omz plugin enable`コマンドは、指定されたプラグインを.zshrcファイルのplugins配列に追加し、自動的にシェルセッションをリロードしてプラグインを有効化します。複数のプラグインを同時に有効化することも可能です。

**業務上の目的・背景**：Oh My Zshのプラグイン管理において、.zshrcファイルを手動で編集することなくプラグインを有効化できる機能が必要です。手動編集はミスの原因となり、特に初心者ユーザーにとっては.zshrcの構文を理解することが困難です。本コマンドにより、安全かつ簡単にプラグインを有効化でき、即座に機能を利用開始できます。

**画面へのアクセス方法**：ターミナルで以下のコマンドを実行します。
- `omz plugin enable <plugin>` - 単一のプラグインを有効化
- `omz plugin enable <plugin1> <plugin2> ...` - 複数のプラグインを同時に有効化

**主要な操作・処理内容**：
1. 指定されたプラグインが既に有効でないことを確認
2. AWKスクリプトを使用して.zshrcのplugins配列を更新
3. 元の.zshrcを.zshrc.bckとしてバックアップ
4. 新しい.zshrcの構文チェックを実行
5. 構文エラーがあればロールバック
6. 成功した場合、シェルセッションをリロード

**画面遷移**：
- 遷移元：`omz plugin`コマンドから
- 遷移先：処理完了後、`_omz::reload`によりシェルセッションが再起動される

**権限による表示制御**：なし。ただし、.zshrcファイルへの書き込み権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてプラグインを有効化 |
| 9 | omz plugin enable | 主機能 | 指定プラグインを.zshrcに追加して有効化し、シェルをリロード |
| 17 | omz reload | 補助機能 | プラグイン有効化後にzshセッションをリスタート |

## 画面種別

設定変更（プラグイン有効化）

## URL/ルーティング

```
omz plugin enable <plugin> [...]
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| plugin | string | はい | 有効化するプラグイン名（複数指定可） |

### 出力項目

| 項目名 | 出力先 | 説明 |
|--------|--------|------|
| 成功メッセージ | 標準エラー出力（stderr） | 有効化されたプラグイン名 |
| 警告メッセージ | 標準エラー出力（stderr） | 既に有効なプラグインの通知 |
| エラーメッセージ | 標準エラー出力（stderr） | 処理失敗時のエラー |

## 表示項目

| 項目 | 説明 | 表示形式 |
|------|------|----------|
| 警告：既に有効 | プラグインが既に有効な場合の警告 | `omz plugin enable: plugin '<name>' is already enabled.` |
| 成功：有効化完了 | プラグイン有効化成功時のメッセージ | `omz plugin enable: plugins enabled: <name1>, <name2>, ...` |
| エラー：有効化失敗 | .zshrc更新失敗時のエラー | `omz plugin enable: error enabling plugins.` |
| エラー：構文エラー | .zshrcの構文チェック失敗時 | `omz plugin enable: broken syntax in '~/.zshrc'. Rolling back changes...` |

## イベント仕様

### 1-プラグイン有効化イベント

**トリガー**：`omz plugin enable <plugin> [...]`コマンドの実行

**処理フロー**：
1. 引数の存在を検証
2. 各プラグインについて、既に有効でないことを確認（`$plugins`配列をチェック）
3. 有効化対象のプラグインリスト（`$add_plugins`）を構築
4. AWKスクリプトを生成して.zshrcを更新
5. 元の.zshrcを.zshrc.bckにバックアップ
6. 新しい.zshrcの構文チェック（`zsh -n`）
7. 構文エラーがあれば.zshrc.bckからロールバック
8. 成功メッセージを表示
9. インタラクティブセッションの場合、`_omz::reload`を呼び出し

**データの流れ**：
```
ユーザー入力 → 有効化チェック → AWKスクリプト生成 → .zshrc更新 → 構文チェック → リロード
```

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| プラグイン有効化 | ~/.zshrc | UPDATE | plugins配列にプラグイン名を追加 |
| バックアップ作成 | ~/.zshrc.bck | INSERT | 元の.zshrcをバックアップ |

### テーブル別更新項目詳細

#### ~/.zshrc

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | plugins=(...) | 指定されたプラグイン名を追加 | 1行形式・複数行形式の両方に対応 |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|---------------|---------------|----------|
| 使用方法 | `Usage: omz plugin enable <plugin> [...]` | プラグイン名が指定されていない場合 |
| 警告 | `plugin '<plugin>' is already enabled.` | 既に有効なプラグインを指定した場合 |
| 成功 | `plugins enabled: <plugin1>, <plugin2>, ...` | 有効化成功時 |
| エラー | `error enabling plugins.` | .zshrc更新失敗時 |
| エラー | `broken syntax in '~/.zshrc'. Rolling back changes...` | 構文チェック失敗時 |

## 例外処理

| 例外状態 | 処理内容 | 戻り値 |
|----------|----------|--------|
| 引数なし | 使用方法を表示 | 1 |
| 全プラグインが既に有効 | 警告を表示して終了 | 1 |
| .zshrc更新失敗 | エラーメッセージを表示 | 非0 |
| 構文チェック失敗 | ロールバックしてエラーを表示 | 1 |

## 備考

- AWKスクリプトは.zshrcの`plugins=(...)`形式を解析し、1行形式と複数行形式の両方に対応
- 複数行形式の場合、既存のインデントを検出して同じインデントでプラグインを追加
- バックアップファイル（.zshrc.bck）は上書きされるため、直前のバックアップのみ保持
- 非インタラクティブセッション（スクリプト実行時など）ではリロードは実行されない
- `$ZDOTDIR`環境変数が設定されている場合、そのディレクトリの.zshrcが更新される

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | 行331で`add_plugins`配列（有効化対象リスト）を確認 |
| 1-2 | cli.zsh | `lib/cli.zsh` | 行346-389でAWKスクリプトの構造を確認 |

**読解のコツ**: AWKスクリプト内の`multi`変数は、plugins配列が複数行にまたがっているかを追跡するフラグです。`indent`変数は既存のインデントを保持します。

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

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

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

**主要処理フロー**:
1. **行325-328**: 引数チェック
2. **行330-338**: 既に有効なプラグインをスキップしながら`add_plugins`を構築
3. **行340-343**: 有効化対象がない場合は終了
4. **行345-389**: AWKスクリプトを生成
5. **行391-395**: AWKで.zshrcを更新、バックアップ作成

#### Step 3: AWKスクリプトのロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | 行347-352で1行形式のplugins配列処理を確認 |
| 3-2 | cli.zsh | `lib/cli.zsh` | 行354-360で複数行形式の開始検出を確認 |
| 3-3 | cli.zsh | `lib/cli.zsh` | 行362-372で複数行形式の終了処理とプラグイン追加を確認 |

**主要処理フロー**:
- **行347-352**: 1行形式`plugins=(... )`で`)`を`$add_plugins )`に置換
- **行354-360**: 複数行形式の開始`plugins=(`を検出し、`multi=1`フラグを設定
- **行362-372**: 閉じ括弧`)`を検出したら、その前にプラグインを適切なインデントで追加
- **行374-386**: 複数行の途中で既存のインデントを学習

#### Step 4: 構文チェックとリロードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cli.zsh | `lib/cli.zsh` | 行404-409で構文チェックとロールバックを確認 |
| 4-2 | cli.zsh | `lib/cli.zsh` | 行414-415でリロード処理を確認 |
| 4-3 | cli.zsh | `lib/cli.zsh` | 行735-743で`_omz::reload`関数を確認 |

**主要処理フロー**:
- **行405**: `zsh -n`で.zshrcの構文チェック
- **行406-408**: エラー時は.zshrc.bckから復元
- **行415**: `[[ ! -o interactive ]]`でインタラクティブセッションを判定し、リロード実行

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

```
omz plugin enable <plugin> [...]
    │
    └─ _omz::plugin::enable
           │
           ├─ 引数チェック
           │
           ├─ 既存プラグインチェック
           │      └─ $plugins配列を参照
           │
           ├─ AWKスクリプト生成
           │      ├─ 1行形式対応
           │      └─ 複数行形式対応
           │
           ├─ .zshrc更新
           │      ├─ awk実行 → .zshrc.new作成
           │      ├─ cp -f → .zshrc.bck作成
           │      └─ mv -f → .zshrc置換
           │
           ├─ 構文チェック
           │      └─ zsh -n ~/.zshrc
           │
           ├─ [エラー時] ロールバック
           │      └─ mv -f .zshrc.bck → .zshrc
           │
           └─ [成功時] リロード
                  └─ _omz::reload
                         ├─ rm $_comp_dumpfile $ZSH_COMPDUMP
                         └─ exec zsh
```

### データフロー図

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

プラグイン名 ───▶ _omz::plugin::enable
                       │
                       ▼
              既存プラグインチェック
                       │
                       ▼
                 add_plugins配列
                       │
                       ▼
                AWKスクリプト生成 ───▶ awk_script変数
                       │
                       ▼
              ~/.zshrc ───▶ awk ───▶ ~/.zshrc.new
                       │
                       ▼
              ~/.zshrc ───▶ cp ───▶ ~/.zshrc.bck
                       │
                       ▼
              ~/.zshrc.new ───▶ mv ───▶ ~/.zshrc
                       │
                       ▼
                    zsh -n ───▶ 構文チェック
                       │
              ┌────────┴────────┐
              │                 │
          [成功]            [失敗]
              │                 │
              ▼                 ▼
         成功メッセージ    ロールバック
              │                 │
              ▼                 ▼
        _omz::reload      エラーメッセージ
              │
              ▼
          exec zsh
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omz plugin enableコマンドの実装 |
| .zshrc | `~/.zshrc` または `$ZDOTDIR/.zshrc` | 設定 | plugins配列の更新対象 |
| .zshrc.bck | `~/.zshrc.bck` または `$ZDOTDIR/.zshrc.bck` | バックアップ | 元の.zshrcのバックアップ |
