# 通知設計書 30-ヘルプ・使用方法表示

## 概要

本ドキュメントは、Tailwind CSSのCLIツール（`@tailwindcss-cli`および`@tailwindcss-upgrade`）において、`help`コマンド実行時またはコマンドが不正な場合に、バージョン情報・使用方法・オプション一覧を表示する通知の設計を定義する。

### 本通知の処理概要

CLIツールの`help`関数を呼び出し、ターミナル幅に応じてフォーマットされたヘルプ情報（ヘッダー、無効なコマンド名、使用方法、オプション一覧）を`process.stdout.write`経由で標準出力に表示する通知処理である。`@tailwindcss-cli`と`@tailwindcss-upgrade`の両方のパッケージに同一インターフェースの`help`関数が実装されている。

**業務上の目的・背景**：CLIツールの利用者がコマンドの使い方を把握できるよう、わかりやすいヘルプ情報を提供することが本通知の目的である。バージョン情報の表示により、問題報告時のバージョン特定が容易になる。ターミナル幅に応じたワードラップにより、狭いターミナルでも読みやすい表示を実現する。無効なコマンドが指定された場合は、そのコマンド名を表示して正しい使い方を案内する。

**通知の送信タイミング**：以下の3つのケースで表示される。(1) `--help`（`-h`）フラグが指定された場合、(2) CLIに未知のサブコマンドが指定された場合（`@tailwindcss-cli`のみ）、(3) ターミナルがTTYでかつ引数なしで`tailwindcss`が実行された場合。

**通知の受信者**：CLIツールを実行した開発者。`process.stdout`に出力されるため、ターミナルに直接表示される。

**通知内容の概要**：ヘッダー行（Tailwind CSSロゴとバージョン情報）、無効なコマンド名（該当する場合）、`Usage:`セクション（コマンドの使用例）、`Options:`セクション（オプション一覧と説明文）の4つのセクションで構成される。picocolorsライブラリによるANSI色コード装飾が施される。

**期待されるアクション**：開発者は表示されたヘルプ情報を参照し、正しいコマンドとオプションを指定してCLIツールを再実行する。

## 通知種別

stdout出力（`process.stdout.write`）。CLIのヘルプ表示として標準出力に表示される。

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（process.stdout.write） |
| 優先度 | 低（情報提供目的） |
| リトライ | 無 |

### 送信先決定ロジック

CLIのメインエントリーポイントで以下の条件判定により`help`関数が呼び出される：

**@tailwindcss-cli（index.ts）**：
1. 未知のサブコマンドが指定された場合（20-27行目）：`invalid`パラメータ付きでhelp呼び出し、`process.exit(1)`
2. `--help`フラグまたはTTYで引数なしの場合（39-45行目）：通常のhelp呼び出し、`process.exit(0)`

**@tailwindcss-upgrade（index.ts）**：
1. `--help`フラグが指定された場合（35-41行目）：通常のhelp呼び出し、`process.exit(0)`

## 通知テンプレート

### メール通知の場合

本通知はメール送信ではなく、stdout出力である。

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | N/A |
| 送信元名称 | N/A |
| 件名 | N/A |
| 形式 | テキスト（stdout出力、ANSI色コード付き） |

### 本文テンプレート

```
≈ tailwindcss v{version}

Invalid command: {command}    ← 無効なコマンドが指定された場合のみ

Usage:
  tailwindcss [--input input.css] [--output output.css] [--watch] [options...]

Options:
  -i, --input ··········· Input file
  -o, --output ·········· Output file
  -w, --watch ··········· Watch for changes and rebuild as needed
  -m, --minify ·········· Optimize and minify the output
      --cwd ············· The current working directory [default: `.`]
      --optimize ········ Optimize the output without minifying
  -h, --help ··········· Display usage information
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | N/A | N/A | 添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| invalid | 無効なコマンド名 | CLI引数の最初のpositional引数 | No |
| usage | 使用方法の文字列配列 | 呼び出し元が指定 | No |
| options | オプション定義オブジェクト | Arg型のオプション定義 | No |
| version | Tailwind CSSのバージョン番号 | `tailwindcss/package.json`から取得 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | `--help`フラグ指定 | `flags['--help'] === true` | ヘルプフラグによるヘルプ表示 |
| CLI実行 | 未知のサブコマンド指定（@tailwindcss-cliのみ） | `flags._[0]`が存在する | 無効なコマンドのヘルプ表示 |
| CLI実行 | 引数なしのTTY実行（@tailwindcss-cliのみ） | `process.stdout.isTTY && process.argv[2] === undefined` | 引数なし実行時のヘルプ表示 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 有効なコマンドとオプションが指定されている | buildコマンド等の有効な実行が行われる場合はヘルプは表示されない |
| パイプ出力の場合 | `process.stdout.isTTY`がfalseの場合、引数なしでもヘルプは表示されない（@tailwindcss-cli） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A["CLI起動"] --> B["args()でフラグ解析"]
    B --> C{"未知のサブコマンド?"}
    C -->|"Yes（@tailwindcss-cliのみ）"| D["help({invalid, usage, options})"]
    D --> E["process.exit(1)"]
    C -->|"No"| F{"--helpフラグ or TTY引数なし?"}
    F -->|"Yes"| G["help({usage, options})"]
    G --> H["process.exit(0)"]
    F -->|"No"| I["通常のビルド/アップグレード処理"]
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | N/A | データベースは使用しない |

### テーブル別参照項目詳細

本通知ではデータベースを参照しない。`tailwindcss/package.json`のバージョン情報をファイルシステムから読み取る。

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| N/A | N/A | データベース更新なし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 特定のエラーケースなし | ヘルプ表示自体はエラーにならない | N/A |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | N/A |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし。CLI実行時に即座に表示される。

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

バージョン情報とコマンドオプションのみが表示され、個人情報やシークレットは含まれない。

## 備考

- `@tailwindcss-cli`と`@tailwindcss-upgrade`の`help`関数は同一のインターフェースを持つが、別々のファイルに実装されている。
- ヘッダーのバージョン情報は`tailwindcss/package.json`から動的に取得される（renderer.ts:96-101行目）。`globalThis.__tw_version`が設定されている場合はそちらが優先される。
- ターミナル幅（`process.stdout.columns`）に応じて、オプションの説明文とusage例がワードラップされる。
- オプション表示では、aliasの最大長に基づいてインデントが調整され、全オプションが視覚的に整列される。
- 無効なコマンドが指定された場合は`process.exit(1)`（異常終了）、ヘルプ要求の場合は`process.exit(0)`（正常終了）で終了する。
- picocolorsライブラリを使用して、ヘッダーを青色、オプション名を青色、説明文間のドットをグレーでdim表示するなど、視覚的な装飾が施される。

---

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

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

### 推奨読解順序

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

`Arg`型（オプション定義）とCLIフラグの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | args.ts (cli) | `packages/@tailwindcss-cli/src/utils/args.ts` | 4-12行目の`Arg`型定義。`--{name}: { type, description, alias?, default?, values? }`の形式 |

**読解のコツ**: `Arg`型はCLIオプションの定義に使用され、`help`関数への入力パラメータとしても機能する。`alias`は`-i`のような短縮形、`values`はオプションの選択肢を定義する。

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

CLIのメインエントリーポイントでのhelp呼び出し判定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts (cli) | `packages/@tailwindcss-cli/src/index.ts` | 20-27行目: 未知コマンド判定+help呼び出し+exit(1) |
| 2-2 | index.ts (cli) | `packages/@tailwindcss-cli/src/index.ts` | 39-45行目: --help/TTY判定+help呼び出し+exit(0) |
| 2-3 | index.ts (upgrade) | `packages/@tailwindcss-upgrade/src/index.ts` | 35-41行目: --help判定+help呼び出し+exit(0) |

**主要処理フロー**:
1. **cli/index.ts 12-15行目**: `args()`でCLI引数をパース
2. **cli/index.ts 16行目**: `flags._[0]`で最初のpositional引数を取得
3. **cli/index.ts 20-27行目**: 未知コマンドの場合、invalidパラメータ付きでhelp呼び出し
4. **cli/index.ts 39-45行目**: --helpまたはTTY引数なしの場合、通常help呼び出し

#### Step 3: help関数の実装を理解する

`help`関数の各セクション（ヘッダー、usage、options）のレンダリングロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | help/index.ts (cli) | `packages/@tailwindcss-cli/src/commands/help/index.ts` | 5-174行目のhelp関数全体。ヘッダー(18行目)、invalid表示(21-24行目)、usage表示(27-93行目)、options表示(96-172行目)の4セクション |

**主要処理フロー**:
- **15行目**: `process.stdout.columns`でターミナル幅を取得
- **18行目**: `println(header())`でヘッダー行を出力
- **21-24行目**: invalidパラメータがある場合に無効コマンド名を表示
- **27-93行目**: usageセクション。コマンドとオプションを分離し、ターミナル幅に応じてワードラップ
- **96-172行目**: optionsセクション。aliasの最大長を計算し、ドットで間隔を空けて説明文を表示

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

`header()`, `wordWrap()`, `println()`, `indent()`等のユーティリティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | renderer.ts (cli) | `packages/@tailwindcss-cli/src/utils/renderer.ts` | 11-13行目: `header()`関数。バージョン付きのヘッダー文字列を生成 |
| 4-2 | renderer.ts (cli) | `packages/@tailwindcss-cli/src/utils/renderer.ts` | 43-67行目: `wordWrap(text, width)`関数。テキストを指定幅でワードラップ |
| 4-3 | renderer.ts (cli) | `packages/@tailwindcss-cli/src/utils/renderer.ts` | 92-94行目: `println(value)`関数。stdout.writeで出力 |

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

```
CLI エントリーポイント (index.ts)
    |
    +-- args({...options, ...sharedOptions}) (index.ts:12)
    |
    +-- [未知コマンドの場合]
    |      +-- help({invalid, usage, options}) (index.ts:21-25)
    |      +-- process.exit(1) (index.ts:26)
    |
    +-- [--helpまたはTTY引数なし]
           +-- help({usage, options}) (index.ts:40-43)
           |      |
           |      +-- println(header()) (help/index.ts:18)
           |      |      +-- getVersion() (renderer.ts:96)
           |      |
           |      +-- [invalid表示] (help/index.ts:21-24)
           |      |
           |      +-- [usageセクション] (help/index.ts:27-93)
           |      |      +-- wordWrap(options, width) (renderer.ts:43)
           |      |      +-- println(indent(...)) (renderer.ts:82, 92)
           |      |
           |      +-- [optionsセクション] (help/index.ts:96-172)
           |             +-- wordWrap(description, availableWidth) (renderer.ts:43)
           |             +-- println(indent(...)) (renderer.ts:82, 92)
           |
           +-- process.exit(0) (index.ts:44)
```

### データフロー図

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

CLI引数                   args()で解析              process.stdout.write()
  --help              ───> flags解析          ───>   ヘッダー行
  {command}                help()呼び出し            Invalid command: {command}
                           header()生成              Usage: tailwindcss [options...]
Arg型                      wordWrap()               Options:
オプション定義      ───>   ターミナル幅適応   ───>     -i, --input ··· Input file
                           indent()/println()         ...

process.stdout.columns    フォーマット計算
(ターミナル幅)      ───>   ワードラップ幅算出
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts (cli) | `packages/@tailwindcss-cli/src/index.ts` | ソース | CLIのメインエントリーポイント。help呼び出し判定 |
| index.ts (upgrade) | `packages/@tailwindcss-upgrade/src/index.ts` | ソース | upgradeツールのエントリーポイント。help呼び出し判定 |
| help/index.ts (cli) | `packages/@tailwindcss-cli/src/commands/help/index.ts` | ソース | CLI版help関数の実装（全174行） |
| help/index.ts (upgrade) | `packages/@tailwindcss-upgrade/src/commands/help/index.ts` | ソース | upgrade版help関数の実装（全170行） |
| renderer.ts (cli) | `packages/@tailwindcss-cli/src/utils/renderer.ts` | ソース | header(), wordWrap(), println(), indent()等のユーティリティ関数 |
| args.ts (cli) | `packages/@tailwindcss-cli/src/utils/args.ts` | ソース | Arg型定義とCLI引数パーサー |
