# 機能設計書 105-シェル統合対応

## 概要

本ドキュメントは、Windows Terminal のシェル統合機能について記述する。シェルからのOSCエスケープシーケンスを受信し、コマンドの検出、作業ディレクトリの追跡、スクロールバーマークとの連携を行う機能を設計レベルで詳述する。

### 本機能の処理概要

**業務上の目的・背景**：モダンなターミナルエミュレータでは、シェルと連携してコマンドの開始/終了位置を把握し、出力のセマンティックな理解を可能にすることが求められる。シェル統合により、コマンドの選択、出力のコピー、エラー検出、クイックフィックスなどの高度な機能が実現される。

**機能の利用シーン**：bash/zsh/PowerShell等のシェルがプロンプト表示時やコマンド実行時にOSCシーケンスを送信し、ターミナルがコマンド行をマークとして認識する。ユーザーはCtrl+Shift+Up/Downでコマンド間を移動したり、コマンド出力を選択したりできる。

**主要な処理内容**：
1. OSC 133 (FinalTerm) シーケンスによるプロンプト/コマンド/出力領域の検出
2. OSC 7 / OSC 9;9 による作業ディレクトリ(CWD)の追跡
3. コマンド実行結果(終了コード)の記録
4. スクロールバーマークとの連携（コマンド成功/失敗のマーク表示）
5. シェル統合情報を活用した上位機能(SelectCommand, SelectOutput, QuickFix等)の基盤提供

**関連システム・外部連携**：VTパーサー(StateMachine)からのOSCディスパッチ、TerminalApiを通じたマーク管理。

**権限による制御**：特段の権限制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | TermControl（ターミナル表示） | 補助機能 | OSCシーケンスによるコマンド検出・作業ディレクトリ追跡 |

## 機能種別

VTシーケンス処理 / 状態管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| OSC 133 ; A | VTシーケンス | No | プロンプト開始マーク | - |
| OSC 133 ; B | VTシーケンス | No | コマンド入力開始マーク | - |
| OSC 133 ; C | VTシーケンス | No | コマンド実行開始マーク | - |
| OSC 133 ; D ; exitCode | VTシーケンス | No | コマンド終了マーク(終了コード付き) | - |
| OSC 7 ; URI | VTシーケンス | No | 作業ディレクトリ設定 | 有効なURI |
| OSC 9 ; 9 ; path | VTシーケンス | No | 作業ディレクトリ設定(ConEmu互換) | 有効なパス |

### 入力データソース

- シェルプロセスからの標準出力(VTシーケンス埋め込み)

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| scrollbarMarks | vector<ScrollMark> | コマンド位置のマークリスト |
| workingDirectory | wstring | 現在の作業ディレクトリ |
| commandHistory | - | コマンド検出に基づく履歴情報 |

### 出力先

- Terminal内部状態（TextBuffer上のマーク情報）
- スクロールバーUIのマーク表示
- サジェスチョン/クイックフィックス機能への情報提供

## 処理フロー

### 処理シーケンス

```
1. OSC 133;A 受信（プロンプト開始）
   └─ 現在行にプロンプトマークを設定

2. OSC 133;B 受信（コマンド入力開始）
   └─ コマンド入力領域の開始位置を記録

3. OSC 133;C 受信（コマンド実行開始）
   └─ コマンド出力領域の開始位置を記録

4. OSC 133;D;exitCode 受信（コマンド終了）
   └─ 終了コードを記録しマークの色を設定
      └─ 成功(0): 緑色マーク
      └─ 失敗(非0): 赤色マーク

5. OSC 7 / OSC 9;9 受信（作業ディレクトリ変更）
   └─ 内部CWD状態を更新
```

### フローチャート

```mermaid
flowchart TD
    A[VTシーケンス受信] --> B{シーケンス種別}
    B -->|OSC 133;A| C[プロンプト開始マーク]
    B -->|OSC 133;B| D[コマンド入力開始]
    B -->|OSC 133;C| E[コマンド実行開始]
    B -->|OSC 133;D| F[コマンド終了+終了コード]
    B -->|OSC 7/9;9| G[CWD更新]
    F --> H{終了コード}
    H -->|0| I[成功マーク]
    H -->|非0| J[失敗マーク]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-105-1 | FinalTermプロトコル | OSC 133シーケンスはFinalTermプロトコルに準拠 | 常時 |
| BR-105-2 | CWDプロトコル | OSC 7はfile://形式のURIでCWDを受信 | OSC 7受信時 |
| BR-105-3 | マーク色 | 終了コード0は成功(緑)、非0は失敗(赤)としてマーク | OSC 133;D受信時 |

### 計算ロジック

特殊な計算ロジックはない。

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

本機能はデータベースを使用しない。TextBuffer上のマーク情報として管理される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 不正シーケンス | 不正なOSC 133パラメータ | 無視して処理を継続 |

### リトライ仕様

リトライは不要。

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

該当なし。

## パフォーマンス要件

- OSCシーケンスの処理はVTパーサーのインライン処理であり、低レイテンシが求められる

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

- OSC 7で受信するURIはfile://スキーム以外を無視すべき
- 悪意のあるプログラムがOSCシーケンスを送信してCWDを偽装する可能性がある

## 備考

- シェル側の設定が必要（bash: PROMPT_COMMAND設定、PowerShell: PSReadLineモジュール等）
- Terminal.hppのGetWorkingDirectory()メソッドでCWDを取得可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Terminal.hpp | `src/cascadia/TerminalCore/Terminal.hpp` | Terminal クラスのシェル統合関連メンバ（GetWorkingDirectory等） |

**読解のコツ**: Terminal.hppの100行目付近にGetWorkingDirectoryメソッドが宣言されている。シェル統合はITerminalApiインターフェースを通じて実装される。

#### Step 2: APIレイヤーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TerminalApi.cpp | `src/cascadia/TerminalCore/TerminalApi.cpp` | OSCシーケンスのハンドラ実装 |

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

```
StateMachine (VTパーサー)
    |
    +-- AdaptDispatch (VTアダプター)
    |       +-- ITerminalApi::SetWorkingDirectory  ... OSC 7/9;9
    |       +-- ITerminalApi::MarkPrompt            ... OSC 133;A
    |       +-- ITerminalApi::MarkCommandStart      ... OSC 133;B
    |       +-- ITerminalApi::MarkOutputStart       ... OSC 133;C
    |       +-- ITerminalApi::MarkCommandFinish     ... OSC 133;D
    |
    +-- Terminal (ITerminalApi実装)
            +-- TextBuffer::AddMark                 ... マーク追加
            +-- _workingDirectory更新               ... CWD設定
```

### データフロー図

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

シェルプロセス              Terminal                       UI/機能
  OSC 133;A ---------> MarkPrompt ----------------> スクロールバーマーク
  OSC 133;B ---------> MarkCommandStart ----------> コマンド範囲記録
  OSC 133;C ---------> MarkOutputStart -----------> 出力範囲記録
  OSC 133;D;code ----> MarkCommandFinish ---------> 成功/失敗マーク
  OSC 7;URI ---------> SetWorkingDirectory -------> CWD状態更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Terminal.hpp | `src/cascadia/TerminalCore/Terminal.hpp` | ソース(ヘッダ) | Terminalクラスの宣言 |
| TerminalApi.cpp | `src/cascadia/TerminalCore/TerminalApi.cpp` | ソース(実装) | ITerminalApi実装 |
| ITerminalApi.hpp | `src/terminal/adapter/ITerminalApi.hpp` | ソース(ヘッダ) | ターミナルAPIインターフェース |
| AdaptDispatch.cpp | `src/terminal/adapter/adaptDispatch.cpp` | ソース(実装) | VTシーケンスディスパッチャ |
