# 機能設計書 59-Fish統合

## 概要

本ドキュメントは、GhosttyターミナルエミュレータのFishシェル統合機能の設計仕様を記載する。

### 本機能の処理概要

Fish統合機能は、FishシェルとGhosttyの連携を実現するシェルスクリプトである。プロンプトマーキング、カーソルスタイル変更、カレントディレクトリ報告、SSH統合、sudo統合など、ターミナルとシェルの高度な連携機能を提供する。Fishのイベントシステムを活用した堅牢な実装。

**業務上の目的・背景**：Fishは「friendly interactive shell」として知られ、シンタックスハイライトや自動補完など優れた対話機能を持つ。GhosttyはFishのイベントシステム（fish_prompt、fish_preexec、fish_postexec等）と連携し、セマンティックプロンプト機能やターミナル体験の向上を実現する。

**機能の利用シーン**：
- プロンプト間のジャンプ機能の利用
- Fish 4.1+でのクリックイベント対応
- SSH接続時のterminfoの自動セットアップ
- sudoコマンド実行時のTERMINFO環境変数の維持

**主要な処理内容**：
1. XDG_DATA_DIRS経由での自動シェル統合
2. fish_promptイベントでのOSC 133マーキング
3. fish_preexec/fish_postexecでのコマンド境界マーキング
4. PWD変数変更時のOSC 7報告
5. SSH統合によるterminfo自動インストール
6. sudo統合によるTERMINFO維持

**関連システム・外部連携**：Fish、SSH、sudo

**権限による制御**：特になし。全ユーザーが実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主機能 | プロンプトマーキング、カーソル変更 |

## 機能種別

シェル統合 / イベントフック

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| GHOSTTY_SHELL_FEATURES | 環境変数 | No | 有効な統合機能（カンマ区切り） | - |
| GHOSTTY_BIN_DIR | 環境変数 | No | Ghosttyバイナリのディレクトリパス | - |
| GHOSTTY_SHELL_INTEGRATION_XDG_DIR | 環境変数 | No | 統合スクリプトのXDGパス | - |
| TERMINFO | 環境変数 | No | terminfoデータベースパス | - |

### 入力データソース

- 環境変数
- Fishの設定ファイル（vendor_conf.d配下）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| OSC 133シーケンス | エスケープシーケンス | プロンプト/コマンドの境界マーカー |
| OSC 7シーケンス | エスケープシーケンス | カレントディレクトリ情報 |
| カーソルシーケンス | エスケープシーケンス | カーソルスタイル変更 |

### 出力先

- ターミナル（tty）

## 処理フロー

### 処理シーケンス

```
1. XDG_DATA_DIRS復元
   └─ GHOSTTY_SHELL_INTEGRATION_XDG_DIRをXDG_DATA_DIRSから除去
2. 対話モード確認
   └─ 非対話モードの場合は終了
3. 初回プロンプト時にセットアップ
   └─ __ghostty_setupをfish_promptイベントで実行
4. 機能フラグのチェックと関数定義
   └─ cursor機能: カーソルスタイル関数定義
   └─ path機能: fish_add_pathでPATH追加
   └─ sudo機能: sudoラッパー関数定義
   └─ ssh機能: sshラッパー関数定義
5. プロンプトマーキング設定
   └─ __ghostty_mark_prompt_start: OSC 133;A
   └─ __ghostty_mark_output_start: OSC 133;C
   └─ __ghostty_mark_output_end: OSC 133;D
6. PWD変更監視
   └─ __update_cwd_osc: OSC 7出力
```

### フローチャート

```mermaid
flowchart TD
    A[Fish起動] --> B[vendor_conf.d自動ソース]
    B --> C[XDG_DATA_DIRS復元]
    C --> D{対話モード?}
    D -->|No| E[終了]
    D -->|Yes| F[__ghostty_setup登録]
    F --> G[初回プロンプト]
    G --> H[__ghostty_setup実行]
    H --> I[機能フラグ解析]
    I --> J{cursor機能?}
    J -->|Yes| K[カーソル関数定義]
    J -->|No| L{path機能?}
    K --> L
    L -->|Yes| M[fish_add_path]
    L -->|No| N{sudo機能?}
    M --> N
    N -->|Yes| O[sudoラッパー定義]
    N -->|No| P{ssh機能?}
    O --> P
    P -->|Yes| Q[sshラッパー定義]
    P -->|No| R[プロンプトフック登録]
    Q --> R
    R --> S[fish_handle_reflow=1]
    S --> T[統合完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-59-1 | 最後にセットアップ | fish_promptイベントで他の統合より後に実行 | 常時 |
| BR-59-2 | Fish 4.1+対応 | Fish 4.1以上ではclick_events=1をOSC 133;Aに追加 | Fishバージョン4.1以上 |
| BR-59-3 | fish_vi_cursor_handle確認 | カーソル変更前にfish_vi_cursor_handle関数の有無を確認 | cursor機能有効時 |
| BR-59-4 | fish_handle_reflow | Ghosttyのresize時プロンプトクリアに対応するため1を設定 | 常時 |

### 計算ロジック

特になし

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | SSH terminfo失敗 | リモートでのticコマンド失敗 | 警告を出力し標準TERM使用 |

### リトライ仕様

リトライなし

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

該当なし

## パフォーマンス要件

シェルの起動と各コマンド実行に顕著な遅延を与えないこと

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

- sudoラッパーは--preserve-env=TERMINFOのみを追加
- SSH統合ではControlMaster/ControlPathを使用

## 備考

- Fishのビルトインpwd報告はGhosttyのallowlistに含まれていないため、独自実装が必要
- functions -eで関数を明示的に削除してクリーンアップ

---

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

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

### 推奨読解順序

#### Step 1: 全体構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ghostty-shell-integration.fish | `src/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish` | 全体構造とセットアップフロー |

**読解のコツ**: Fishスクリプトはfunctionでローカル関数を定義し、--on-eventや--on-variableでイベントハンドラを設定する。

#### Step 2: XDG復元とセットアップを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ghostty-shell-integration.fish | `src/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish` | 5-46行目: XDG復元、対話モードチェック |

**主要処理フロー**:
- **5-32行目**: ghostty_restore_xdg_data_dir関数 - XDG_DATA_DIRSからGhosttyディレクトリを除去
- **34-38行目**: ghostty_exit関数 - クリーンアップ用
- **41行目**: ghostty_restore_xdg_data_dir呼び出し
- **44行目**: 対話モードチェック

#### Step 3: 機能フラグ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ghostty-shell-integration.fish | `src/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish` | 49-203行目: __ghostty_setup関数 |

**主要処理フロー**:
- **52行目**: GHOSTTY_SHELL_FEATURESを分割
- **54-66行目**: Fishバージョン解析（Fish 4.1+検出）
- **68-73行目**: OSC 133;Aマーカー設定（click_events対応）
- **75-90行目**: cursor機能 - カーソルスタイル関数
- **92-95行目**: path機能 - fish_add_path
- **99-120行目**: sudo機能 - sudoラッパー
- **122-203行目**: ssh機能 - sshラッパー

#### Step 4: プロンプトマーキングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ghostty-shell-integration.fish | `src/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish` | 206-224行目: プロンプトマーキング |

**主要処理フロー**:
- **206-214行目**: __ghostty_mark_prompt_start - OSC 133;A出力
- **216-219行目**: __ghostty_mark_output_start - OSC 133;C出力
- **221-224行目**: __ghostty_mark_output_end - OSC 133;D;$status出力

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

```
Fish起動
    │
    ├─ vendor_conf.d/ghostty-shell-integration.fish ソース
    │      │
    │      ├─ ghostty_restore_xdg_data_dir()
    │      │      └─ XDG_DATA_DIRS復元
    │      │
    │      ├─ 対話モードチェック
    │      │
    │      └─ __ghostty_setup登録 (--on-event fish_prompt)
    │
    └─ 初回プロンプト時
           │
           └─ __ghostty_setup()
                  │
                  ├─ Fishバージョン解析
                  │
                  ├─ cursor機能
                  │      ├─ __ghostty_set_cursor_beam (--on-event fish_prompt)
                  │      └─ __ghostty_reset_cursor (--on-event fish_preexec)
                  │
                  ├─ path機能
                  │      └─ fish_add_path
                  │
                  ├─ sudo機能
                  │      └─ sudo関数定義
                  │
                  ├─ ssh機能
                  │      └─ ssh関数定義 (--wraps=ssh)
                  │
                  ├─ プロンプトマーキング
                  │      ├─ __ghostty_mark_prompt_start (fish_prompt/fish_posterror)
                  │      ├─ __ghostty_mark_output_start (fish_preexec)
                  │      └─ __ghostty_mark_output_end (fish_postexec)
                  │
                  ├─ __update_cwd_osc (--on-variable PWD)
                  │
                  └─ fish_handle_reflow = 1
```

### データフロー図

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

環境変数 ───────▶ 機能フラグ解析 ───────▶ 関数定義
(GHOSTTY_SHELL_FEATURES)

fish_prompt ─────▶ __ghostty_mark_prompt_start()
                         │
                         └──▶ OSC 133;A（click_events=1 on Fish 4.1+）

fish_preexec ────▶ __ghostty_mark_output_start()
                         │
                         └──▶ OSC 133;C

fish_postexec ───▶ __ghostty_mark_output_end()
                         │
                         └──▶ OSC 133;D;$status

$PWD変更 ────────▶ __update_cwd_osc()
                         │
                         └──▶ OSC 7;file://hostname/path
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ghostty-shell-integration.fish | `src/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish` | シェルスクリプト | メイン統合スクリプト |
