# 機能設計書 57-Bash統合

## 概要

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

### 本機能の処理概要

Bash統合機能は、BashシェルとGhosttyの連携を実現するシェルスクリプトである。プロンプトマーキング、カーソルスタイル変更、ウィンドウタイトル更新、SSH統合、sudo統合など、ターミナルとシェルの高度な連携機能を提供する。

**業務上の目的・背景**：現代のターミナルエミュレータは、単なる文字入出力だけでなく、シェルとの深い連携による高度な機能を提供する。Ghosttyはシェル統合によりOSC 133（セマンティックプロンプト）を活用したプロンプトジャンプ、コマンド完了通知、SSH接続時のterminfo自動インストールなど、生産性を向上させる機能を実現する。

**機能の利用シーン**：
- プロンプト間のジャンプ機能の利用
- コマンド実行時間の計測と通知
- SSH接続時のterminfoの自動セットアップ
- sudoコマンド実行時のTERMINFO環境変数の維持

**主要な処理内容**：
1. 自動シェル統合時のBash起動シーケンス再構築
2. OSC 133によるプロンプトマーキング（precmd/preexec）
3. カーソルスタイルの動的変更
4. ウィンドウタイトルの動的更新
5. SSH統合によるterminfo自動インストール
6. sudo統合によるTERMINFO維持

**関連システム・外部連携**：Bash 4.4以上（推奨）、bash-preexec（4.4未満用）、SSH、sudo

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- 環境変数
- Bashの起動設定ファイル

## 出力仕様

### 出力データ

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

### 出力先

- ターミナル（tty）

## 処理フロー

### 処理シーケンス

```
1. 対話モード確認
   └─ 非対話モードの場合は即座にreturn
2. GHOSTTY_BASH_INJECT処理（自動統合時）
   └─ POSIXモード解除、起動ファイルのソース
3. 機能フラグのチェックと関数定義
   └─ path機能: PATHにGhosttyバイナリを追加
   └─ sudo機能: sudoラッパー関数を定義
   └─ ssh機能: sshラッパー関数を定義
4. precmd/preexec関数の定義
   └─ __ghostty_precmd: プロンプト表示前処理
   └─ __ghostty_preexec: コマンド実行前処理
5. フック登録
   └─ Bash 4.4+: PROMPT_COMMAND + PS0使用
   └─ Bash 4.4未満: bash-preexecライブラリ使用
```

### フローチャート

```mermaid
flowchart TD
    A[シェル起動] --> B{対話モード?}
    B -->|No| C[終了]
    B -->|Yes| D{GHOSTTY_BASH_INJECT?}
    D -->|Yes| E[起動シーケンス再構築]
    E --> F[POSIXモード解除]
    F --> G[起動ファイルソース]
    D -->|No| H[機能フラグチェック]
    G --> H
    H --> I{path機能?}
    I -->|Yes| J[PATH追加]
    I -->|No| K{sudo機能?}
    J --> K
    K -->|Yes| L[sudoラッパー定義]
    K -->|No| M{ssh機能?}
    L --> M
    M -->|Yes| N[sshラッパー定義]
    M -->|No| O[precmd/preexec定義]
    N --> O
    O --> P{Bash 4.4+?}
    P -->|Yes| Q[PROMPT_COMMAND + PS0]
    P -->|No| R[bash-preexecソース]
    Q --> S[統合完了]
    R --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-57-1 | 対話モード限定 | 非対話モードではシェル統合を実行しない | 常時 |
| BR-57-2 | Bashバージョン分岐 | 4.4以上は組み込み機能、未満はbash-preexec使用 | 常時 |
| BR-57-3 | OSC 133マーキング | プロンプト開始にA、入力終了にB、コマンド開始にC、コマンド終了にDを出力 | 常時 |
| BR-57-4 | マルチラインプロンプト | 複数行プロンプトでは各行にセカンダリマーカー（k=s）を付与 | プロンプトに改行含む場合 |

### 計算ロジック

特になし

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 起動ファイル不存在 | .bashrc等が存在しない | スキップして続行 |
| - | SSH terminfo失敗 | リモートでのticコマンド失敗 | 警告を出力し標準TERM使用 |

### リトライ仕様

リトライなし

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

該当なし

## パフォーマンス要件

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

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

- sudoラッパーは--preserve-env=TERMINFOのみを追加し、他の環境変数は保持しない
- SSH統合ではControlMaster/ControlPathを使用してセッションを再利用

## 備考

- GPLv3ライセンス（Kittyの統合スクリプトをベースとしている）
- Bash 5.3以上では関数置換（function substitution）を使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ghostty.bash | `src/shell-integration/bash/ghostty.bash` | 全体構造と機能フラグ処理 |

**読解のコツ**: Bashスクリプトは上から順に実行される。対話モードチェック（19行目）から始まり、GHOSTTY_BASH_INJECT処理、機能フラグ処理、フック登録の順で進む。

#### Step 2: 起動シーケンス再構築を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ghostty.bash | `src/shell-integration/bash/ghostty.bash` | 23-80行目: GHOSTTY_BASH_INJECT処理 |

**主要処理フロー**:
- **26-27行目**: フラグ保存とGHOSTTY_BASH_INJECT解除
- **37-38行目**: POSIXモード解除
- **48-75行目**: ログイン/非ログインシェルの起動ファイルソース

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ghostty.bash | `src/shell-integration/bash/ghostty.bash` | 82-185行目: 各機能の実装 |

**主要処理フロー**:
- **83-87行目**: path機能 - PATHへのGHOSTTY_BIN_DIR追加
- **90-115行目**: sudo機能 - TERMINFOを維持するsudoラッパー
- **118-185行目**: ssh機能 - terminfo自動インストール

#### Step 4: プロンプトフックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ghostty.bash | `src/shell-integration/bash/ghostty.bash` | 192-307行目: precmd/preexec実装 |

**主要処理フロー**:
- **192-243行目**: __ghostty_precmd - OSC 133 A/B/Dの出力
- **245-259行目**: __ghostty_preexec - OSC 133 C出力、タイトル更新
- **261-307行目**: フック登録（Bashバージョン分岐）

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

```
Bashシェル起動
    │
    ├─ ghostty.bash ソース
    │      │
    │      ├─ 対話モードチェック
    │      │
    │      ├─ GHOSTTY_BASH_INJECT処理
    │      │      └─ 起動ファイルソース（.bashrc等）
    │      │
    │      ├─ 機能フラグ処理
    │      │      ├─ path機能 ─ PATH追加
    │      │      ├─ sudo機能 ─ sudoラッパー定義
    │      │      └─ ssh機能 ─ sshラッパー定義
    │      │
    │      └─ フック登録
    │             │
    │             ├─ (Bash 4.4+) PROMPT_COMMAND + PS0
    │             │      ├─ __ghostty_hook ─ precmd呼び出し
    │             │      └─ __ghostty_preexec_hook ─ preexec呼び出し
    │             │
    │             └─ (Bash 4.4未満) bash-preexec.sh
    │                    ├─ precmd_functions += __ghostty_precmd
    │                    └─ preexec_functions += __ghostty_preexec
    │
    └─ プロンプト表示/コマンド実行ごとにフック実行
```

### データフロー図

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

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

プロンプト表示 ──▶ __ghostty_precmd()
                         │
                         ├──▶ OSC 133;D （前コマンド終了）
                         ├──▶ PS1修正 （OSC 133;A/B追加）
                         ├──▶ OSC 7 （CWD報告）
                         └──▶ OSC 2 （タイトル: PWD）

コマンド実行 ────▶ __ghostty_preexec()
                         │
                         ├──▶ PS1復元
                         ├──▶ OSC 2 （タイトル: コマンド）
                         └──▶ OSC 133;C （コマンド開始）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ghostty.bash | `src/shell-integration/bash/ghostty.bash` | シェルスクリプト | メイン統合スクリプト |
| bash-preexec.sh | `src/shell-integration/bash/bash-preexec.sh` | シェルスクリプト | Bash 4.4未満用フックライブラリ |
