# 機能設計書 6-omzコマンド

## 概要

本ドキュメントは、Oh My Zsh（以下OMZ）の統合CLIインターフェース「omzコマンド」に関する機能設計書である。omz help, omz update, omz plugin, omz theme等のサブコマンドを提供する。

### 本機能の処理概要

本機能は、OMZの各種管理機能にアクセスするための統一されたコマンドラインインターフェースを提供する。サブコマンド形式で様々な操作を実行できる。

**業務上の目的・背景**：OMZの管理操作（更新、プラグイン管理、テーマ管理等）を統一されたインターフェースで提供することで、ユーザーの学習コストを低減し、操作性を向上させる。従来は各機能が個別のスクリプトとして提供されていたが、omzコマンドに統合することで一貫したユーザー体験を実現。

**機能の利用シーン**：OMZのメンテナンス作業時にユーザーが明示的に実行する。シェル起動時には実行されない。

**主要な処理内容**：
1. サブコマンドのパース
2. 対応する内部関数の呼び出し
3. 補完機能の提供
4. ヘルプメッセージの表示

**関連システム・外部連携**：Git（update, version等）、GitHub API（pr test）、ブラウザ（shop）

**権限による制御**：特になし。一部のサブコマンドは.zshrcへの書き込み権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | omz help | 主機能 | omzコマンドの統合CLIインターフェースを通じてヘルプを表示 |
| 2 | omz changelog | 主機能 | omzコマンドの統合CLIインターフェースを通じてチェンジログを表示 |
| 3 | omz plugin list | 主機能 | プラグイン一覧を表示 |
| 4 | omz plugin info | 主機能 | プラグイン情報を表示 |
| 5 | omz plugin enable | 主機能 | プラグインを有効化 |
| 6 | omz plugin disable | 主機能 | プラグインを無効化 |
| 7 | omz plugin load | 主機能 | プラグインを動的ロード |
| 8 | omz theme list | 主機能 | テーマ一覧を表示 |
| 9 | omz theme use | 主機能 | テーマを一時適用 |
| 10 | omz theme set | 主機能 | テーマを永続設定 |
| 11 | omz pr test | 主機能 | PRテストを実行 |
| 12 | omz pr clean | 主機能 | PRブランチを削除 |
| 13 | omz update | 主機能 | アップデートを実行 |
| 14 | omz reload | 主機能 | リロードを実行 |
| 15 | omz version | 主機能 | バージョンを表示 |
| 16 | omz shop | 主機能 | ショップを開く |

## 機能種別

CLI / 管理機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| command | 文字列 | Yes | サブコマンド名 | 有効なサブコマンドであること |
| subcommand | 文字列 | No | サブコマンドのサブコマンド | コマンドにより異なる |
| options | 文字列 | No | オプション引数 | コマンドにより異なる |

### 入力データソース

- コマンドライン引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| stdout | テキスト | コマンド実行結果、ヘルプメッセージ等 |
| stderr | テキスト | エラーメッセージ、ログ |
| 戻り値 | 整数 | 0: 成功、1: エラー |

### 出力先

- 標準出力/標準エラー出力
- .zshrc（plugin enable/disable, theme set時）

## 処理フロー

### 処理シーケンス

```
1. 引数チェック
   └─ 引数がない場合はヘルプを表示してreturn 1

2. サブコマンド特定
   └─ $1をサブコマンドとして取得
   └─ 対応する内部関数が存在するか確認

3. 内部関数呼び出し
   └─ _omz::$commandの形式で関数呼び出し
   └─ 残りの引数を渡す

4. 結果返却
   └─ 内部関数の戻り値をそのまま返却
```

### フローチャート

```mermaid
flowchart TD
    A[omz実行] --> B{引数あり?}
    B -->|No| C[_omz::help呼び出し]
    C --> D[return 1]
    B -->|Yes| E[command=$1を取得]
    E --> F{_omz::$command存在?}
    F -->|No| G[_omz::help呼び出し]
    G --> D
    F -->|Yes| H[_omz::$command実行]
    H --> I[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | サブコマンド必須 | 引数なしの場合はヘルプを表示して終了 | 常時 |
| BR-02 | 内部関数命名規則 | 内部関数は`_omz::`プレフィックスを持つ | 常時 |
| BR-03 | 不明コマンド処理 | 存在しないサブコマンドはヘルプを表示 | 常時 |
| BR-04 | 補完関数登録 | compdefが利用可能な場合のみ補完関数を登録 | インタラクティブシェル時 |

### 計算ロジック

**サブコマンド関数存在確認**:
```zsh
(( ${+functions[_omz::$command]} ))
```

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 引数なしエラー | omzコマンドのみで実行 | ヘルプを表示してreturn 1 |
| 1 | 不明コマンドエラー | 存在しないサブコマンド指定 | ヘルプを表示してreturn 1 |

### リトライ仕様

リトライは行わない。

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

本機能はトランザクションを使用しない。

## パフォーマンス要件

特になし。対話的に使用されるコマンドのため、即時応答が期待される。

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

- `omz pr test`は実行前にセキュリティ警告を表示
- .zshrc編集時は構文チェックとバックアップを実施

## 備考

- omzコマンドはlib/cli.zshで定義される
- サブコマンドの補完機能が提供される
- 内部関数は`_`プレフィックスにより補完候補に表示されない

---

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

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

### 推奨読解順序

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

omzコマンドのアーキテクチャを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | omz関数と_omz::*内部関数の関係 |

**読解のコツ**:
- `omz`がメインエントリーポイント
- `_omz::*`が各サブコマンドの実装
- `_omz`（アンダースコア1つ）は補完関数

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

omz関数の実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | 3-21行目のomz関数 |

**主要処理フロー**:
- **4行目**: `setopt localoptions noksharrays` - オプション設定
- **5-8行目**: 引数チェック、なければヘルプ表示
- **10-11行目**: コマンド取得とshift
- **15-18行目**: 内部関数存在確認、なければヘルプ表示
- **20行目**: `_omz::$command "$@"` - 内部関数呼び出し

#### Step 3: 補完関数を理解する

補完機能の実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | 23-112行目の_omz補完関数 |

**主要処理フロー**:
- **25-35行目**: トップレベルコマンドの定義
- **37-56行目**: 第2レベル補完（plugin, pr, theme）
- **57-84行目**: 第3レベル補完（plugin操作、テーマ選択）
- **85-109行目**: 第4レベル以降（複数プラグイン指定）
- **115-117行目**: compdef登録

#### Step 4: ユーティリティ関数を理解する

共通ユーティリティ関数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cli.zsh | `lib/cli.zsh` | 119-162行目のユーティリティ関数 |

**主要処理フロー**:
- **121-135行目**: `_omz::confirm` - 確認プロンプト
- **137-162行目**: `_omz::log` - ログ出力（info, warn, error, debug, prompt）

#### Step 5: helpコマンドを理解する

ヘルプ表示の実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | cli.zsh | `lib/cli.zsh` | 166-183行目の_omz::help関数 |

**主要処理フロー**:
- ヒアドキュメントで使用可能なコマンド一覧を出力

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

```
omz (メインエントリーポイント)
    │
    ├─ _omz::help - ヘルプ表示
    │
    ├─ _omz::changelog - チェンジログ表示
    │      └─ tools/changelog.sh
    │
    ├─ _omz::plugin - プラグイン管理
    │      ├─ _omz::plugin::disable
    │      ├─ _omz::plugin::enable
    │      ├─ _omz::plugin::info
    │      ├─ _omz::plugin::list
    │      └─ _omz::plugin::load
    │
    ├─ _omz::pr - PR管理
    │      ├─ _omz::pr::clean
    │      └─ _omz::pr::test
    │
    ├─ _omz::reload - リロード
    │
    ├─ _omz::shop - ショップを開く
    │      └─ open_command
    │
    ├─ _omz::theme - テーマ管理
    │      ├─ _omz::theme::list
    │      ├─ _omz::theme::set
    │      └─ _omz::theme::use
    │
    ├─ _omz::update - 更新
    │      └─ tools/upgrade.sh
    │
    └─ _omz::version - バージョン表示

_omz (補完関数)
    └─ compdef _omz omz
```

### データフロー図

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

コマンドライン引数
  │
  ├─ omz             ───▶ _omz::help ───────────────────▶ ヘルプメッセージ
  │
  ├─ omz help        ───▶ _omz::help ───────────────────▶ ヘルプメッセージ
  │
  ├─ omz plugin ...  ───▶ _omz::plugin ─────────────────▶ プラグイン操作結果
  │
  ├─ omz theme ...   ───▶ _omz::theme ──────────────────▶ テーマ操作結果
  │
  ├─ omz update      ───▶ _omz::update ─────────────────▶ 更新結果
  │
  └─ omz version     ───▶ _omz::version ────────────────▶ バージョン情報
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omzコマンドのメイン実装 |
| upgrade.sh | `tools/upgrade.sh` | ソース | omz update用の更新スクリプト |
| changelog.sh | `tools/changelog.sh` | ソース | omz changelog用のスクリプト |
| .zshrc | `~/.zshrc` | 設定 | plugin enable/disable, theme set時に編集 |
