# 機能設計書 55-Eshellターミナル

## 概要

本ドキュメントは、Doom Emacsの`term/eshell`モジュールが提供するEshellターミナル機能の設計仕様を記述する。Emacs Lispで実装されたシェル環境であるEshellに対して、カスタムプロンプト、コマンド履歴検索、ワークスペース統合、シンタックスハイライト、Fish補完など多数の拡張機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：開発作業においてターミナル操作は頻繁に発生する。Emacs内でシェル環境を提供することで、エディタとターミナル間のコンテキストスイッチを削減し、Emacsのテキスト編集機能（検索、コピー、マクロ等）をターミナル出力に対しても利用可能にする。EshellはEmacs Lispで実装されているため、Elispコードをシームレスに実行でき、クロスプラットフォームで動作する。

**機能の利用シーン**：
- プロジェクトルートでのシェルコマンド実行
- Emacsコマンドとシェルコマンドの混在実行
- 複数のターミナルセッションの管理
- コマンド履歴の検索・再利用

**主要な処理内容**：
1. カスタムプロンプト表示（Git情報、パス短縮）
2. eshell-zによるディレクトリジャンプ（z.sh互換）
3. eshell-upによる上位ディレクトリへの移動
4. fish-completionによる補完強化
5. eshell-syntax-highlightingによるコマンドハイライト
6. eshell-did-you-meanによるコマンド修正提案
7. ワークスペース（persp-mode）統合

**関連システム・外部連携**：
- eshell（Emacs組み込み）
- eshell-z（z.sh互換ディレクトリジャンプ）
- eshell-up（上位ディレクトリ移動）
- fish-completion（Fish shell補完）
- eshell-syntax-highlighting（シンタックスハイライト）
- eshell-did-you-mean（コマンド修正提案）
- persp-mode（ワークスペース管理）

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Eshellバッファ | 主画面 | コマンド入力・実行・出力表示 |

## 機能種別

ターミナルエミュレーション / シェル環境

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| command | string | No | 起動時に実行するコマンド | - |
| arg | prefix | No | 新規シェルを開くかどうか | C-u プレフィックス |

### 入力データソース

- ユーザーのキーボード入力
- eshell履歴ファイル
- z.sh互換の頻度データベース

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| コマンド出力 | string | 実行結果のテキスト |
| プロンプト | string | カスタマイズされたプロンプト表示 |
| 補完候補 | list | Tab補完の候補リスト |

### 出力先

- `*doom:eshell*`バッファ（またはワークスペース別バッファ）

## 処理フロー

### 処理シーケンス

```
1. Eshell起動（+eshell/toggle, +eshell/here等）
   └─ eshell-mode-hookを実行
2. プロンプト表示
   └─ +eshell-default-prompt-fn でカスタムプロンプト生成
3. コマンド入力
   └─ シンタックスハイライト、補完候補表示
4. コマンド実行
   └─ 出力を表示、履歴に記録
5. バッファ終了時
   └─ +eshell-cleanup-h でリソース解放
```

### フローチャート

```mermaid
flowchart TD
    A[+eshell/toggle] --> B{バッファ存在?}
    B -->|Yes| C[バッファに切り替え]
    B -->|No| D[新規バッファ作成]
    D --> E[eshell-mode有効化]
    E --> F[+eshell-init-h]
    F --> G[プロンプト表示]
    C --> G
    G --> H[コマンド入力]
    H --> I[補完/ハイライト]
    I --> J[Enter]
    J --> K[コマンド実行]
    K --> L[出力表示]
    L --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-55-01 | プロンプト形式 | パス（短縮）+ Gitブランチ + λ/# | 常時 |
| BR-55-02 | 履歴重複除去 | 重複コマンドは履歴に記録しない | eshell-hist-ignoredups t |
| BR-55-03 | 空白プレフィックス除外 | 空白で始まるコマンドは履歴に記録しない | eshell-input-filter |
| BR-55-04 | ビジュアルコマンド | tmux, htop, vim等は専用termに委譲 | eshell-visual-commands |
| BR-55-05 | 出力の読み取り専用化 | 過去の出力は編集不可 | eshell-post-command-hook |

### 計算ロジック

- パス短縮: `shrink-path-file`
- Gitブランチ取得: `git symbolic-ref -q --short HEAD`

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

本機能はデータベース操作を行わない。ファイルシステム上に履歴を保存する。

### 操作別ファイル影響一覧

| 操作 | 対象ディレクトリ | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 履歴保存 | `eshell-directory-name` | WRITE | コマンド履歴の保存 |
| z.sh DB | `eshell-z-freq-dir-hash-table-file-name` | READ/WRITE | ディレクトリ頻度データ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コマンド未発見 | 存在しないコマンドを実行 | eshell-did-you-meanで修正提案 |
| - | バッファ無効 | 存在しないバッファを参照 | user-errorを発生 |

### リトライ仕様

リトライ処理は不要。

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

トランザクション処理は不要。

## パフォーマンス要件

- プロンプト表示: 即時（Git操作を含めても100ms以内）
- Tab補完: 即時（候補取得100ms以内）
- シンタックスハイライト: リアルタイム更新

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

- 過去の出力を読み取り専用にして、意図しない編集を防止
- コマンド実行前のundo履歴を無効化

## 備考

- Windows以外ではfish-completionが利用可能
- Emacs 29以前ではpcomplete-completions-at-pointにパッチ適用

---

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

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

### 推奨読解順序

#### Step 1: 設定変数を理解する

まず、Eshellの基本設定変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/term/eshell/config.el` | 変数定義（10-51行目） |

**読解のコツ**: `+eshell-config-dir`はユーザー設定、`eshell-directory-name`はデータ保存先。

**主要処理フロー**:
1. **10-13行目**: 設定ディレクトリとデータディレクトリの定義
2. **19-23行目**: `+eshell-enable-new-shell-on-split`と`+eshell-kill-window-on-exit`
3. **26-44行目**: `+eshell-aliases`のデフォルト定義

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | autoload/eshell.el | `modules/term/eshell/autoload/eshell.el` | コマンド定義（97-158行目） |

**主要処理フロー**:
- **98-127行目**: `+eshell/toggle`でポップアップ表示
- **130-142行目**: `+eshell/here`で現在ウィンドウに表示
- **145-158行目**: `+eshell/frame`で専用フレーム表示

#### Step 3: プロンプト生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | autoload/prompts.el | `modules/term/eshell/autoload/prompts.el` | プロンプト関数（27-39行目） |

**主要処理フロー**:
- **29行目**: `shrink-path`を使用
- **31-35行目**: パスの短縮表示
- **36-37行目**: Gitブランチの表示
- **38行目**: 終了コードに応じたλ/エラー色

#### Step 4: フック処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload/eshell.el | `modules/term/eshell/autoload/eshell.el` | フック関数（293-341行目） |

**主要処理フロー**:
- **294-302行目**: `+eshell-init-h`でバッファを追跡リストに追加
- **305-329行目**: `+eshell-cleanup-h`でクリーンアップ処理
- **332-341行目**: ワークスペース統合フック

#### Step 5: パッケージ統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | config.el | `modules/term/eshell/config.el` | パッケージ設定（238-321行目） |

**主要処理フロー**:
- **238-239行目**: eshell-upコマンド
- **242-248行目**: eshell-z設定
- **251-270行目**: esh-help（eldoc統合）
- **273-285行目**: eshell-did-you-mean設定
- **288-313行目**: eshell-syntax-highlighting設定
- **316-320行目**: fish-completion設定

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

```
+eshell/toggle
    │
    ├─ +eshell--unused-buffer
    │      └─ generate-new-buffer
    │
    ├─ eshell-mode
    │      │
    │      ├─ eshell-mode-hook
    │      │      ├─ +eshell-init-h
    │      │      ├─ doom-mark-buffer-as-real-h
    │      │      ├─ electric-pair-local-mode
    │      │      └─ hide-mode-line-mode
    │      │
    │      └─ eshell-prompt-function
    │             └─ +eshell-default-prompt-fn
    │                    ├─ shrink-path-file
    │                    └─ +eshell--current-git-branch
    │
    └─ pop-to-buffer

+eshell-run-command
    │
    ├─ eshell-last-output-end
    ├─ insert (command)
    └─ eshell-send-input
```

### データフロー図

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

コマンド入力 ───▶ eshell-syntax-highlighting ───▶ ハイライト表示
     │
     ▼
Tab押下 ───▶ fish-completion/pcomplete ───▶ 補完候補
     │
     ▼
Enter押下 ───▶ eshell-send-input ───▶ コマンド実行
     │                                        │
     ▼                                        ▼
eshell-history-ring ◀─────────────── 出力表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/term/eshell/config.el` | ソース | メイン設定、パッケージ設定 |
| packages.el | `modules/term/eshell/packages.el` | 設定 | 依存パッケージ定義 |
| autoload/eshell.el | `modules/term/eshell/autoload/eshell.el` | ソース | コマンド、フック定義 |
| autoload/prompts.el | `modules/term/eshell/autoload/prompts.el` | ソース | プロンプト生成 |
| autoload/commands.el | `modules/term/eshell/autoload/commands.el` | ソース | カスタムEshellコマンド |
| autoload/evil.el | `modules/term/eshell/autoload/evil.el` | ソース | Evil統合 |
