# 機能設計書 60-Elvish統合

## 概要

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

### 本機能の処理概要

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

**業務上の目的・背景**：Elvishは静的型付けを持つ現代的なシェルであり、Goで実装されている。GhosttyはElvishのedit:before-readline、edit:after-readline、edit:after-commandフックと連携し、セマンティックプロンプト機能やターミナル体験の向上を実現する。

**機能の利用シーン**：
- プロンプト間のジャンプ機能の利用
- コマンド実行結果のステータスコード取得
- SSH接続時のterminfoの自動セットアップ
- sudoコマンド実行時のTERMINFO環境変数の維持

**主要な処理内容**：
1. XDG_DATA_DIRS復元
2. edit:before-readlineでのOSC 133;A出力
3. edit:after-readlineでのOSC 133;C出力
4. edit:after-commandでのOSC 133;D出力（ステータスコード付き）
5. after-chdirでのOSC 7報告
6. SSH統合によるterminfo自動インストール
7. sudo統合によるTERMINFO維持

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- 環境変数
- Elvishの設定ファイル（lib配下）

## 出力仕様

### 出力データ

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

### 出力先

- ターミナル（tty）

## 処理フロー

### 処理シーケンス

```
1. モジュールインポート
   └─ platform、strモジュールをuse
2. XDG_DATA_DIRS復元
   └─ GHOSTTY_SHELL_INTEGRATION_XDG_DIRを除去
3. 機能フラグ解析
   └─ GHOSTTY_SHELL_FEATURESをカンマで分割
4. ヘルパー関数定義
   └─ set-prompt-state、mark-prompt-start等
5. edit:*フックへの関数登録
   └─ edit:before-readline += mark-prompt-start~
   └─ edit:after-readline += mark-output-start~
   └─ edit:after-command += mark-output-end~
6. 機能別関数登録
   └─ cursor: beam~、reset~
   └─ path: paths追加
   └─ sudo: edit:add-var sudo~
   └─ ssh: edit:add-var ssh~
7. ディレクトリ変更監視
   └─ after-chdir += report-pwd~
```

### フローチャート

```mermaid
flowchart TD
    A[Elvish起動] --> B[lib/ghostty-integration.elv ソース]
    B --> C[モジュールインポート]
    C --> D[XDG_DATA_DIRS復元]
    D --> E[機能フラグ解析]
    E --> F[ヘルパー関数定義]
    F --> G[edit:before-readline登録]
    G --> H[edit:after-readline登録]
    H --> I[edit:after-command登録]
    I --> J{cursor機能?}
    J -->|Yes| K[beam/reset関数登録]
    J -->|No| L{path機能?}
    K --> L
    L -->|Yes| M[paths追加]
    L -->|No| N{sudo機能?}
    M --> N
    N -->|Yes| O[edit:add-var sudo~]
    N -->|No| P{ssh機能?}
    O --> P
    P -->|Yes| Q[edit:add-var ssh~]
    P -->|No| R[after-chdir登録]
    Q --> R
    R --> S[defer mark-prompt-start]
    S --> T[統合完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-60-1 | コマンド情報活用 | edit:after-commandで渡されるcmd-info構造体からエラー情報を取得 | コマンド実行後 |
| BR-60-2 | exit-status取得 | cmd-info[error][reason][exit-status]からステータスコードを取得 | エラー発生時 |
| BR-60-3 | デフォルトステータス | エラーなしの場合は0、エラーありで取得不可の場合は1 | 常時 |
| BR-60-4 | conj関数使用 | Elvishのconjでリストに要素を追加 | フック登録時 |

### 計算ロジック

特になし

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

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

### リトライ仕様

リトライなし

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

該当なし

## パフォーマンス要件

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

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

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

## 備考

- Elvishはブロック構文`{ }`を使用し、関数参照は`$func~`の形式
- deferを使用して初回プロンプト時にmark-prompt-startを実行
- os:temp-dirでSSH用の一時ディレクトリを作成

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ghostty-integration.elv | `src/shell-integration/elvish/lib/ghostty-integration.elv` | 全体構造とモジュールインポート |

**読解のコツ**: Elvishはブロック構文`{ }`内に処理を記述し、`fn name {|args| body}`で関数を定義する。変数は`$name`、関数参照は`$name~`で表す。

#### Step 2: XDG復元とフラグ解析を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ghostty-integration.elv | `src/shell-integration/elvish/lib/ghostty-integration.elv` | 1-12行目: インポートとXDG復元 |

**主要処理フロー**:
- **1-2行目**: platformとstrモジュールのインポート
- **5-9行目**: XDG_DATA_DIRS復元 - str:replaceで除去
- **12行目**: GHOSTTY_SHELL_FEATURESをカンマで分割

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ghostty-integration.elv | `src/shell-integration/elvish/lib/ghostty-integration.elv` | 14-48行目: マーキング関数 |

**主要処理フロー**:
- **15行目**: set-prompt-state - 状態管理
- **17-23行目**: mark-prompt-start - OSC 133;A出力
- **25-28行目**: mark-output-start - OSC 133;C出力
- **30-48行目**: mark-output-end - OSC 133;D出力（ステータスコード解析）

#### Step 4: 機能別処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ghostty-integration.elv | `src/shell-integration/elvish/lib/ghostty-integration.elv` | 50-184行目: 各機能の実装 |

**主要処理フロー**:
- **50-70行目**: sudo-with-terminfo - sudoラッパー
- **72-147行目**: ssh-integration - SSH統合
- **149-155行目**: deferとフック登録
- **157-167行目**: cursor機能
- **168-172行目**: path機能
- **173-175行目**: sudo機能登録
- **176-178行目**: ssh機能登録
- **181-183行目**: report-pwd、after-chdir登録

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

```
Elvish起動
    │
    └─ lib/ghostty-integration.elv ソース
           │
           ├─ use platform, str
           │
           ├─ XDG_DATA_DIRS復元
           │      └─ str:replace
           │
           ├─ 機能フラグ解析
           │      └─ str:split ',' $E:GHOSTTY_SHELL_FEATURES
           │
           ├─ ヘルパー関数定義
           │      ├─ set-prompt-state
           │      ├─ mark-prompt-start
           │      ├─ mark-output-start
           │      ├─ mark-output-end
           │      ├─ sudo-with-terminfo
           │      └─ ssh-integration
           │
           ├─ フック登録
           │      ├─ edit:before-readline += mark-prompt-start~
           │      ├─ edit:after-readline += mark-output-start~
           │      └─ edit:after-command += mark-output-end~
           │
           ├─ 機能別登録
           │      ├─ cursor: beam~/reset~
           │      ├─ path: paths追加
           │      ├─ sudo: edit:add-var sudo~
           │      └─ ssh: edit:add-var ssh~
           │
           ├─ after-chdir += report-pwd~
           │
           └─ defer { mark-prompt-start }
```

### データフロー図

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

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

edit:before-readline ▶ mark-prompt-start()
                         │
                         └──▶ OSC 133;A

edit:after-readline ──▶ mark-output-start()
                         │
                         └──▶ OSC 133;C

edit:after-command ───▶ mark-output-end()
                         │
                         ├── cmd-info[error]解析
                         │      └── exit-status取得
                         │
                         └──▶ OSC 133;D;$exit-status

after-chdir ─────────▶ report-pwd()
                         │
                         └──▶ OSC 7;kitty-shell-cwd://hostname/path
```

### 関連ファイル一覧

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