# 機能設計書 111-コマンドライン実行

## 概要

Windows Terminal上で`wt.exe`のコマンドラインを動的に実行する機能（ExecuteCommandline アクション）の設計書である。

### 本機能の処理概要

本機能は、ターミナルの実行中にコマンドパレットやキーバインドから`wt.exe`形式のコマンドラインを入力・実行し、新しいタブの作成やペインの分割などの操作をプログラム的に行うことを可能にする。

**業務上の目的・背景**：Windows Terminalの操作を自動化・効率化するため、GUIメニューからの操作だけでなく、コマンドラインの文字列を直接入力して任意のアクションを実行できる仕組みが必要である。特にパワーユーザーがコマンドパレットのコマンドラインモードを使って素早く複雑な操作を行うシーンで活用される。

**機能の利用シーン**：コマンドパレットをコマンドラインモード（`>`プレフィクス）で開き、`new-tab -p "PowerShell"`や`split-pane -H`などのwtコマンドライン文字列を入力して実行する場面で使用される。また、設定ファイルのキーバインドに`wt`コマンドラインを直接記述して実行することも可能。

**主要な処理内容**：
1. ExecuteCommandlineArgs からコマンドライン文字列を取得する
2. AppCommandlineArgs を使用してコマンドライン文字列を解析する
3. 解析結果をActionAndArgsのリスト（スタートアップアクション）に変換する
4. ProcessStartupActions を呼び出して変換されたアクションを順次実行する

**関連システム・外部連携**：AppCommandlineArgs（コマンドライン引数パーサー）と連携し、`new-tab`、`split-pane`、`focus-tab`等のサブコマンドを解析する。

**権限による制御**：特に権限による制御はないが、昇格（管理者権限）が必要なコマンドの場合はUACプロンプトが表示される場合がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleExecuteCommandlineによりWTコマンドラインを実行 |
| 10 | CommandPalette（コマンドパレット） | 補助画面 | コマンドラインモードでWTコマンドを実行 |

## 機能種別

コマンド実行処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Commandline | String | Yes | wt.exe形式のコマンドライン文字列 | 空でないこと。AppCommandlineArgsで解析可能なこと |

### 入力データソース

- コマンドパレットのコマンドラインモードからのユーザー入力
- settings.json のキーバインド設定で定義されたExecuteCommandlineアクション

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| actions | std::vector<ActionAndArgs> | コマンドラインから変換されたアクションリスト |
| Handled | bool | アクションが正常に処理されたかどうか |

### 出力先

TerminalPage内でProcessStartupActionsを通じて各アクションが実行される（タブ作成、ペイン分割等）。

## 処理フロー

### 処理シーケンス

```
1. _HandleExecuteCommandline が呼び出される
   └─ ActionEventArgs から ExecuteCommandlineArgs を取得
2. ExecuteCommandlineArgs の Commandline プロパティを取得
   └─ wt.exe 形式のコマンドライン文字列
3. ConvertExecuteCommandlineToActions を呼び出す
   └─ AppCommandlineArgs を生成し、ParseArgs でコマンドラインを解析
4. 解析結果が空でなければアクションリストを取得
   └─ GetStartupActions() でアクションリストを取得
5. ProcessStartupActions で各アクションを順次実行
   └─ 新しいタブ作成、ペイン分割等のアクションが実行される
```

### フローチャート

```mermaid
flowchart TD
    A[_HandleExecuteCommandline 呼び出し] --> B{ExecuteCommandlineArgs取得成功?}
    B -->|No| Z[終了（未処理）]
    B -->|Yes| C[ConvertExecuteCommandlineToActions呼び出し]
    C --> D[AppCommandlineArgs.ParseArgs でコマンドライン解析]
    D --> E{解析結果が空でない?}
    E -->|No| Z
    E -->|Yes| F[Handled = true に設定]
    F --> G[ProcessStartupActions でアクション実行]
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-111-01 | コマンドライン形式 | wt.exe の引数形式に従うコマンドラインのみ受け付ける | 常時 |
| BR-111-02 | 解析失敗時の動作 | コマンドラインの解析に失敗した場合、アクションは実行されず Handled=false となる | 解析失敗時 |
| BR-111-03 | 複数サブコマンド | セミコロンで区切られた複数のサブコマンドを順次実行可能 | 複数コマンド指定時 |

### 計算ロジック

特になし。

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

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 解析エラー | コマンドライン文字列が不正な場合 | ParseArgs が 0 以外を返し、アクションリストが空になる。Handled=false のままとなる |
| - | 型変換エラー | ActionArgs が ExecuteCommandlineArgs にキャストできない場合 | try_as が nullptr を返し、処理をスキップ |

### リトライ仕様

リトライは行わない。

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

トランザクション管理は不要（メモリ内処理のみ）。

## パフォーマンス要件

コマンドラインの解析は同期的に行われるため、即座に完了する必要がある。ProcessStartupActionsは非同期コルーチンとして実行される。

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

- コマンドラインの入力はユーザーが直接行うため、外部からの入力インジェクションリスクは低い
- 昇格が必要な操作の場合はOSのUACによって保護される

## 備考

- ExecuteCommandlineArgs は ActionArgs.idl で定義されており、Commandline プロパティを持つ
- コマンドパレットのコマンドラインモードからの利用が主な想定ユースケース

---

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

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

### 推奨読解順序

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

ExecuteCommandlineArgs のデータ構造を把握することが出発点となる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | **317-321行目**: ExecuteCommandlineArgs の IDL 定義。Commandline プロパティ（String型）を持つ |
| 1-2 | ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | **911行目**: ACTION_ARGS_STRUCT マクロによる ExecuteCommandlineArgs の C++ 実装 |

**読解のコツ**: ACTION_ARGS_STRUCT マクロは、IActionArgs インターフェースの標準的な実装（FromJson, ToJson, Equals, Copy, Hash, GenerateName）を自動生成する。マクロ展開を追わなくても、IDL で定義されたプロパティが主要なデータ構造である。

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

アクションハンドラが処理の起点となる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | **755-767行目**: _HandleExecuteCommandline メソッド。ExecuteCommandlineArgs を受け取り、ConvertExecuteCommandlineToActions を呼び出す |

**主要処理フロー**:
1. **758行目**: actionArgs から ExecuteCommandlineArgs への try_as キャスト
2. **760行目**: ConvertExecuteCommandlineToActions でコマンドライン文字列をアクションリストに変換
3. **763行目**: 変換成功時に Handled = true を設定
4. **764行目**: ProcessStartupActions でアクションを実行

#### Step 3: コマンドライン変換処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | **4211-4218行目**: ConvertExecuteCommandlineToActions メソッド。AppCommandlineArgs を使用してコマンドラインを解析し、アクションリストを返す |
| 3-2 | AppCommandlineArgs.h | `src/cascadia/TerminalApp/AppCommandlineArgs.h` | コマンドライン引数の解析クラス。ParseArgs と GetStartupActions が主要メソッド |

**主要処理フロー**:
- **4213行目**: AppCommandlineArgs インスタンスを生成
- **4214行目**: ParseArgs でコマンドラインを解析（戻り値 0 が成功）
- **4216行目**: GetStartupActions() でアクションリストを取得して返す

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

```
TerminalPage::_HandleExecuteCommandline (AppActionHandlers.cpp:755)
    |
    +-- ExecuteCommandlineArgs::try_as (型キャスト)
    |
    +-- TerminalPage::ConvertExecuteCommandlineToActions (TerminalPage.cpp:4211)
    |       |
    |       +-- AppCommandlineArgs::ParseArgs (引数解析)
    |       |
    |       +-- AppCommandlineArgs::GetStartupActions (アクションリスト取得)
    |
    +-- TerminalPage::ProcessStartupActions (アクション実行)
```

### データフロー図

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

コマンドライン文字列 ───> AppCommandlineArgs::ParseArgs ───> ActionAndArgs リスト
(例: "new-tab -p PS")      (コマンドライン解析)              (NewTabArgs 等)
                                    |
                                    v
                           ProcessStartupActions
                           (各アクションを順次実行)  ───> タブ作成、ペイン分割等
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | ソース | ExecuteCommandlineArgs の IDL 定義 |
| ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | ソース | ExecuteCommandlineArgs の C++ 実装 |
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleExecuteCommandline ハンドラ |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース | ConvertExecuteCommandlineToActions の実装 |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ソース | ConvertExecuteCommandlineToActions の宣言 |
| AppCommandlineArgs.h | `src/cascadia/TerminalApp/AppCommandlineArgs.h` | ソース | コマンドライン引数パーサー |
| AppCommandlineArgs.cpp | `src/cascadia/TerminalApp/AppCommandlineArgs.cpp` | ソース | コマンドライン引数パーサーの実装 |
| AllShortcutActions.h | `src/cascadia/TerminalSettingsModel/AllShortcutActions.h` | ソース | ExecuteCommandline アクションの登録 |
