# 帳票設計書 7-list-actions

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータの `list-actions` コマンドが出力するキーバインドアクション一覧の設計書です。

### 本帳票の処理概要

`list-actions` コマンドは、キーバインドに割り当て可能なアクションの一覧を標準出力に表示するCLIリストです。CLIアクション（+コマンド）ではなく、キーバインド設定で使用するアクションを一覧表示します。

**業務上の目的・背景**：ユーザーがキーバインド設定で使用できるアクションを確認し、カスタムキーバインドを設定する際の参考にします。`--docs`オプションでアクションの詳細説明も確認できます。

**帳票の利用シーン**：
- キーバインド設定で使用可能なアクションの確認
- アクションの詳細説明の確認
- 設定ファイル作成時の参考
- Ghosttyの機能把握

**主要な出力内容**：
1. アクション名
2. アクションの説明（--docs指定時）

**帳票の出力タイミング**：`ghostty +list-actions` コマンド実行時

**帳票の利用者**：エンドユーザー、パワーユーザー、システム管理者

## 帳票種別

CLIリスト（テキスト形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI | `ghostty +list-actions` | コマンド実行 |
| - | CLI | `ghostty +list-actions --docs` | ドキュメント付き出力 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（stdout） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（標準出力） |
| 出力方法 | 標準出力への表示 |
| 文字コード | UTF-8 |

### 端末出力固有設定

| 項目 | 内容 |
|-----|------|
| ハイパーリンク | 無 |
| カラー出力 | 無 |
| インタラクティブ | 無 |

## 帳票レイアウト

### レイアウト概要

#### 通常出力モード
```
┌─────────────────────────────────────┐
│  アクション名1                        │
│  アクション名2                        │
│  ...                                │
└─────────────────────────────────────┘
```

#### ドキュメント付き出力モード（--docs）
```
┌─────────────────────────────────────┐
│  アクション名1                        │
│    説明文1                           │
│                                     │
│  アクション名2                        │
│    説明文2                           │
│  ...                                │
└─────────────────────────────────────┘
```

### ヘッダー部

ヘッダーはありません。

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | アクション名 | キーバインドアクション名 | Binding.Action enum | "{action_name}" |
| 2 | 説明文 | アクションの説明 | helpgen_actions | インデント付き（--docs時） |

### フッター部

フッターはありません。

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| --docs | ドキュメント付き出力 | No |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | アクション定義順 | 定義順 |

### 改ページ条件

改ページなし（連続出力）

## データベース参照仕様

### 参照テーブル一覧

データベース参照はありません。

### データ取得元詳細

| 取得元 | 用途 | 取得方法 |
|-------|------|---------|
| helpgen_actions | アクション定義とドキュメント | コンパイル時生成 |
| Binding.Action | アクション一覧 | enum定義 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| なし | - | - | 計算処理なし |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[オプション解析]
    B --> C[stdoutライター初期化]
    C --> D[helpgen_actions.generate呼び出し]
    D --> E[各アクションを出力]
    E --> F{--docs指定?}
    F -->|Yes| G[説明文も出力]
    F -->|No| H[アクション名のみ]
    G --> I{全アクション処理完了?}
    H --> I
    I -->|No| E
    I -->|Yes| J[終了コード0を返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 出力失敗 | stdoutへの書き込みエラー | なし（エラー返却） | プロセス終了 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数十アクション |
| 目標出力時間 | 即時（1秒未満） |
| 同時出力数上限 | N/A |

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

- 静的なアクション定義のみを参照
- ファイルシステムアクセスなし
- 機密情報なし

## 備考

- CLIアクション（`+help`で表示されるもの）とは異なる
- キーバインドアクションは設定ファイルの`keybind`で使用

---

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

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

### 推奨読解順序

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

アクション定義の構造を理解します。

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

**読解のコツ**: Binding.Actionはキーバインドで使用可能なアクションを定義するenumです。

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

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

**主要処理フロー**:
1. **31-38行目**: オプション解析
2. **40-43行目**: stdoutライター初期化
3. **43-48行目**: helpgen_actions.generate呼び出し

#### Step 3: アクション生成を理解する

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

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

```
ghostty (main)
    │
    └─ Action.run (ghostty.zig:99)
           │
           └─ list_actions.run (list_actions.zig:30)
                  │
                  ├─ args.parse (オプション解析)
                  │
                  └─ helpgen_actions.generate
                         │
                         ├─ Binding.Action enum走査
                         │
                         └─ stdout出力
```

### データフロー図

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

--docsオプション ───▶ list_actions.run()
                           │
                           ▼
               helpgen_actions.generate()
                           │
    ┌──────────────────────┼──────────────────────┐
    ▼                      ▼                      ▼
Action enum           docs flag             stdout
(コンパイル時)        (オプション)
    │                      │                      │
    └──────────▶ アクション一覧 ◀──────────────────┘
                           │
                           ▼
                       stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| list_actions.zig | `src/cli/list_actions.zig` | ソース | メイン処理 |
| ghostty.zig | `src/cli/ghostty.zig` | ソース | Actionディスパッチャー |
| args.zig | `src/cli/args.zig` | ソース | 引数解析ユーティリティ |
| helpgen_actions.zig | `src/input/helpgen_actions.zig` | ソース | アクション出力生成 |
| Binding.zig | `src/input/Binding.zig` | ソース | キーバインドアクション定義 |
