# 機能設計書 49-アクション一覧

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「アクション一覧」機能の設計を記述する。この機能は、CLIコマンド`+list-actions`を通じて、キーバインドに設定可能なすべてのアクションを一覧表示する。

### 本機能の処理概要

**業務上の目的・背景**：Ghosttyは豊富なキーバインドアクションを提供しており、ユーザーがカスタムキーバインドを設定する際に、利用可能なアクションとその説明を確認できることが重要である。アクション一覧機能は、すべての利用可能なアクションとオプションでドキュメントを表示することで、キーバインドのカスタマイズを支援する。

**機能の利用シーン**：
- 設定ファイルでキーバインドを設定する際に利用可能なアクションを確認する
- 各アクションの説明を確認する
- CLIアクション（`+`コマンド）とは異なるキーバインドアクションを確認する

**主要な処理内容**：
1. キーバインドアクション一覧の生成
2. オプションでドキュメントの表示
3. プレーンテキスト形式での出力

**関連システム・外部連携**：
- helpgen_actions（アクション情報生成）

**権限による制御**：特になし。すべてのユーザーがアクション一覧を実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| なし | - | - | CLI専用機能のため画面関連なし |

## 機能種別

情報表示 / CLI出力

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| docs | bool | No | 各アクションのドキュメントを表示するかどうか | デフォルト: false |

### 入力データソース

- コマンドライン: `ghostty +list-actions [オプション]`
- 内蔵アクション定義

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| アクション名 | []const u8 | キーバインドに設定可能なアクション名 |
| ドキュメント | ?[]const u8 | アクションの説明（--docs指定時） |

### 出力先

- 標準出力（stdout）

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数のパース
   └─ Options構造体への値設定

2. 出力先の準備
   └─ stdoutのバッファリングライター初期化

3. アクション情報の生成
   └─ helpgen_actions.generateの呼び出し

4. 出力
   └─ プレーンテキスト形式でアクション一覧を出力
```

### フローチャート

```mermaid
flowchart TD
    A[+list-actions実行] --> B[引数パース]
    B --> C[stdout初期化]
    C --> D[helpgen_actions.generate呼び出し]
    D --> E{--docs指定?}
    E -->|Yes| F[アクション名+ドキュメント出力]
    E -->|No| G[アクション名のみ出力]
    F --> H[終了コード0]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-49-01 | CLIアクションとの区別 | このコマンドはキーバインドアクションを表示する。CLIアクション（+コマンド）は+helpで確認 | 常時 |
| BR-49-02 | ドキュメント表示 | --docsフラグで各アクションの説明を表示 | --docs指定時 |
| BR-49-03 | プレーンテキスト形式 | 出力は常にプレーンテキスト形式 | 常時 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | I/Oエラー | 標準出力への書き込み失敗 | エラーを返す |

### リトライ仕様

リトライなし。

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

トランザクションは使用しない。

## パフォーマンス要件

- 瞬時に実行完了すること（静的データの出力のみ）

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

- アクション情報は機密情報を含まない

## 備考

- キーバインドアクションはBinding.Actionに定義されている
- CLIアクション（+version, +helpなど）とは異なる

---

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

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

### 推奨読解順序

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

Options構造体とhelpgen_actionsモジュールを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | list_actions.zig | `src/cli/list_actions.zig` | Options構造体の定義（7-21行目） |
| 1-2 | Binding.zig | `src/input/Binding.zig` | Action enumの定義 |

**読解のコツ**: Optionsは非常にシンプルで、docsフラグのみを持つ。

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

run関数の処理フローを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | list_actions.zig | `src/cli/list_actions.zig` | run関数（23-51行目） |

**主要処理フロー**:
1. **30-38行目**: 引数パース
2. **40-42行目**: stdoutライター初期化
3. **43-48行目**: helpgen_actions.generate呼び出し

#### Step 3: アクション情報生成

helpgen_actionsモジュールの処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | helpgen_actions.zig | `src/input/helpgen_actions.zig` | generate関数 |

**主要処理フロー**:
- アクションの列挙とフォーマット
- ドキュメントの取得と出力

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

```
ghostty +list-actions [options]
    │
    └─ cli.list_actions.run
           │
           ├─ args.parse (Optionsへ)
           │
           ├─ stdout.writer (ライター初期化)
           │
           └─ helpgen_actions.generate
                  │
                  ├─ .plaintext (出力形式)
                  │
                  ├─ opts.docs (ドキュメント表示フラグ)
                  │
                  └─ Binding.Action (アクション定義)
```

### データフロー図

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

コマンドライン ──────▶ Options解析 ────────▶ フラグ
     │                     │
     │                     ▼
Binding.Action ───────▶ helpgen_actions.generate
     │                     │
     │                     ▼
     └──────────────▶ stdout出力
                          │
                          ├─ アクション名
                          └─ [--docs] ドキュメント
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| list_actions.zig | `src/cli/list_actions.zig` | ソース | アクション一覧コマンドの実装 |
| helpgen_actions.zig | `src/input/helpgen_actions.zig` | ソース | アクション情報生成 |
| Binding.zig | `src/input/Binding.zig` | ソース | Actionの定義 |
| args.zig | `src/cli/args.zig` | ソース | コマンドライン引数パーサー |
