# 画面設計書 1-omz help

## 概要

本ドキュメントは、Oh My Zshの`omz help`コマンドインターフェースの画面設計書です。ユーザーがOh My Zshの利用可能なコマンド一覧とその使用方法を確認するためのヘルプ表示機能を定義します。

### 本画面の処理概要

`omz help`コマンドは、Oh My Zshのコマンドラインインターフェース（CLI）における最も基本的なナビゲーション機能を提供します。

**業務上の目的・背景**：Oh My Zshは多数のサブコマンド（plugin、theme、update等）を持つ複雑なツールです。ユーザーが利用可能な機能を素早く把握し、適切なコマンドを選択できるよう、統一されたヘルプシステムが必要です。このヘルプコマンドにより、ユーザーは初めてOh My Zshを使う場合でも、ドキュメントを別途参照することなく基本的な操作方法を理解できます。

**画面へのアクセス方法**：ターミナルで以下のコマンドを実行します。
- `omz help` - 明示的にヘルプを表示
- `omz` - 引数なしで実行した場合も自動的にヘルプを表示
- `omz <無効なコマンド>` - 存在しないサブコマンドを指定した場合もヘルプを表示

**主要な操作・処理内容**：
1. コマンド実行時に標準エラー出力へヘルプメッセージを表示
2. 利用可能なサブコマンド（help、changelog、plugin、pr、reload、shop、theme、update、version）の一覧を表示
3. 各サブコマンドの簡潔な説明を提供

**画面遷移**：
- 遷移元：なし（エントリーポイント）
- 遷移先：ヘルプ表示後、シェルプロンプトに戻る。ユーザーは表示された情報を参考に他のサブコマンドを実行可能

**権限による表示制御**：なし。すべてのユーザーが同一のヘルプ情報を参照できます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてヘルプを表示 |

## 画面種別

情報表示（ヘルプ/ガイダンス）

## URL/ルーティング

```
omz help
omz          # 引数なしの場合
omz <invalid> # 無効なコマンドの場合
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| command | string | いいえ | サブコマンド名（"help"または未指定/無効値） |

### 出力項目

| 項目名 | 出力先 | 説明 |
|--------|--------|------|
| ヘルプメッセージ | 標準エラー出力（stderr） | 利用可能なコマンド一覧と説明 |

## 表示項目

| 項目 | 説明 | 表示形式 |
|------|------|----------|
| Usage行 | コマンドの基本的な使用方法 | `Usage: omz <command> [options]` |
| Available commands | 利用可能なコマンドのセクションヘッダー | プレーンテキスト |
| help | ヘルプコマンドの説明 | `help                Print this help message` |
| changelog | チェンジログコマンドの説明 | `changelog           Print the changelog` |
| plugin | プラグイン管理コマンドの説明 | `plugin <command>    Manage plugins` |
| pr | PR管理コマンドの説明 | `pr     <command>    Manage Oh My Zsh Pull Requests` |
| reload | リロードコマンドの説明 | `reload              Reload the current zsh session` |
| shop | ショップコマンドの説明 | `shop                Open the Oh My Zsh shop` |
| theme | テーマ管理コマンドの説明 | `theme  <command>    Manage themes` |
| update | アップデートコマンドの説明 | `update              Update Oh My Zsh` |
| version | バージョン表示コマンドの説明 | `version             Show the version` |

## イベント仕様

### 1-ヘルプ表示イベント

**トリガー**：`omz help`コマンドの実行、または`omz`を引数なし/無効な引数で実行

**処理フロー**：
1. `omz`関数がコマンドライン引数を解析
2. 引数がない場合、または引数に対応する関数が存在しない場合、`_omz::help`関数を呼び出し
3. `_omz::help`関数がヒアドキュメント形式でヘルプメッセージを標準エラー出力に出力
4. 戻り値1（エラー終了）を返却

**データの流れ**：
```
ユーザー入力 → omz関数 → _omz::help関数 → stderr出力
```

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

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

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

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

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|---------------|---------------|----------|
| ヘルプ | Usage: omz <command> [options]... | コマンド実行時 |

## 例外処理

| 例外状態 | 処理内容 | 戻り値 |
|----------|----------|--------|
| 引数なし | ヘルプを表示 | 1 |
| 無効なサブコマンド | ヘルプを表示 | 1 |

## 備考

- ヘルプメッセージは標準エラー出力（stderr）に出力されるため、パイプ処理時に標準出力とは分離される
- 戻り値が1（エラー）となるのは、ヘルプ表示が「正常な処理の完了」ではなく「ユーザーへの案内」という位置づけであるため
- zsh補完システム（compdef）により、`omz`コマンドのタブ補完でもコマンド一覧が表示される

---

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

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

### 推奨読解順序

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

omz helpコマンドは単純なテキスト出力であり、複雑なデータ構造は使用しません。ただし、omzコマンド全体の構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | omzコマンドの全体構造と関数定義パターンを理解する |

**読解のコツ**: zshの関数定義は`function 関数名 { ... }`形式で行われます。`_omz::`で始まる関数名は内部関数であり、タブ補完に表示されないよう設計されています。

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

omzコマンドのメインエントリーポイントを確認します。

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

**主要処理フロー**:
1. **行3-8**: 引数チェック。引数がない場合は`_omz::help`を呼び出して終了
2. **行10-11**: 最初の引数をコマンド名として取得し、引数リストからシフト
3. **行15-18**: コマンドに対応する関数`_omz::$command`が存在するかチェック。存在しなければヘルプを表示
4. **行20**: 対応する関数を呼び出し

#### Step 3: ヘルプ表示関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | `_omz::help`関数（166-183行目）でヘルプメッセージを出力 |

**主要処理フロー**:
- **行167-182**: ヒアドキュメント（cat >&2 <<EOF...EOF）を使用して、標準エラー出力にヘルプメッセージを表示

#### Step 4: 補完システムを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cli.zsh | `lib/cli.zsh` | `_omz`関数（23-112行目）で補完定義を行う |

**主要処理フロー**:
- **行25-35**: 補完候補として表示されるコマンドリストを定義
- **行37-38**: カーソル位置が2（omzの直後）の場合、コマンド一覧を補完候補として提示
- **行115-117**: `compdef _omz omz`で補完関数を登録

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

```
omz (エントリーポイント)
    │
    ├─ [引数なし/無効な引数]
    │      └─ _omz::help
    │             └─ cat >&2 <<EOF (ヘルプ出力)
    │
    └─ [有効なサブコマンド]
           └─ _omz::$command (各サブコマンド関数)
```

### データフロー図

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

コマンドライン ───▶ omz関数 ───▶ 引数解析
     │                              │
     │                    [引数なし/無効]
     │                              │
     └─────────────────▶ _omz::help ───▶ stderr
                                          │
                                          ▼
                                    ヘルプメッセージ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omzコマンドの全機能を定義するメインファイル |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | Oh My Zsh初期化時にcli.zshを読み込む |
