# 機能設計書 70-tmux

## 概要

本ドキュメントは、space-vimにおけるtmux連携機能の設計について記載する。vim-tmux-navigatorプラグインによるtmuxとVim間のシームレスなウィンドウナビゲーション機能を提供する。

### 本機能の処理概要

tmux連携機能は、tmux内でVimを使用する際に、tmuxペインとVimウィンドウ間をシームレスに移動できる機能を提供する。同じキーバインディング（Ctrl+hjkl）でtmuxペインとVimウィンドウの両方を移動でき、統一されたワークフローを実現する。

**業務上の目的・背景**：tmuxは多くの開発者に愛用されるターミナルマルチプレクサである。しかし、tmux内でVimを使用する場合、tmuxペイン間の移動とVimウィンドウ間の移動で異なるキーバインディングを使い分ける必要があり、煩雑である。vim-tmux-navigatorは、この問題を解決し、シームレスなナビゲーション体験を提供する。

**機能の利用シーン**：
- tmux内でVimと他のターミナルペインを並べて作業する場合
- Vimの分割ウィンドウとtmuxペインを頻繁に行き来する場合
- 統一されたキーバインディングでウィンドウ管理を行いたい場合
- tmuxセッション・ウィンドウ・バッファを検索したい場合

**主要な処理内容**：
1. Ctrl+h/j/k/l でVimウィンドウ/tmuxペイン間を移動
2. Ctrl+\ で前のペインに移動
3. ctrlp-tmux.vim によるtmuxセッション検索（unite有効時）
4. vim-tmuxifyによるtmux操作支援

**関連システム・外部連携**：
- christoomey/vim-tmux-navigator プラグイン
- lucidstack/ctrlp-tmux.vim プラグイン（unite有効時）
- jebaum/vim-tmuxify プラグイン
- tmux（外部ツール）
- space-vimの+tools/tmuxレイヤーとして提供

**権限による制御**：特になし。すべてのユーザーが利用可能。tmux環境でのみ動作。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Vimウィンドウ | 主画面 | Vimウィンドウとtmuxペイン間のナビゲーション |

## 機能種別

ウィンドウナビゲーション / 外部ツール連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:spacevim.tmux | Number | Yes | tmux環境フラグ（自動検出） | 0または1 |

### 入力データソース

- キーボード入力（Ctrl+h/j/k/l等）
- tmux環境情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ウィンドウ/ペイン移動 | 動作 | カーソルが移動先のウィンドウ/ペインにフォーカス |

### 出力先

Vimウィンドウまたはtmuxペイン

## 処理フロー

### 処理シーケンス

```
1. ナビゲーションキー押下
   └─ Ctrl+h/j/k/l

2. 移動方向の判定
   └─ h:左, j:下, k:上, l:右

3. Vimウィンドウ境界チェック
   └─ 移動方向にVimウィンドウがあるか確認

4. 移動先決定
   └─ Vimウィンドウあり: Vimウィンドウ間移動
   └─ Vimウィンドウなし: tmuxペイン移動コマンド実行

5. フォーカス移動
   └─ 移動先にカーソルがフォーカス
```

### フローチャート

```mermaid
flowchart TD
    A[Ctrl+hjkl押下] --> B{方向判定}
    B -->|h| C[左方向]
    B -->|j| D[下方向]
    B -->|k| E[上方向]
    B -->|l| F[右方向]
    C --> G{Vimウィンドウあり?}
    D --> G
    E --> G
    F --> G
    G -->|Yes| H[Vimウィンドウ移動]
    G -->|No| I[tmuxペイン移動]
    H --> J[完了]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | tmux環境検出 | g:spacevim.tmuxフラグに基づいてtmux環境を判定 | 常時 |
| BR-02 | シームレス移動 | Vimウィンドウ境界を超えるとtmuxペインに自動移動 | ナビゲーションキー押下時 |
| BR-03 | xterm-keys修正 | tmux環境でのCtrl+矢印キー対応 | screen系ターミナル使用時 |

### 計算ロジック

特になし（ウィンドウ管理のみ）

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | tmux非実行 | tmux外で実行された場合 | vim-tmux-navigatorは通常のウィンドウ移動として動作 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

即時実行（遅延なし）

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

特になし

## 備考

- tmux環境外ではvim-tmux-navigatorは通常のVimウィンドウ移動として動作
- ctrlp-tmux.vimはuniteレイヤーが有効な場合のみ利用可能
- tmuxのxterm-keysオプションが有効であることを推奨

---

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

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

### 推奨読解順序

#### Step 1: プラグイン登録を理解する

tmuxレイヤーのプラグイン登録を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+tools/tmux/packages.vim` | tmux関連プラグインの登録を確認 |

**読解のコツ**: 一部のプラグインはtmux環境（g:spacevim.tmux）でのみ有効化される。

**主要処理フロー**:
1. **1行目**: `MP 'christoomey/vim-tmux-navigator'` - シームレスナビゲーション（常時ロード）
2. **2-7行目**: tmux環境依存のプラグイン
   - **2行目**: `if g:spacevim.tmux` - tmux環境チェック
   - **3-4行目**: `if spacevim#load('unite')` - uniteレイヤー有効時
   - **4行目**: `MP 'lucidstack/ctrlp-tmux.vim'` - CtrlPでtmux検索
   - **6行目**: `MP 'jebaum/vim-tmuxify'` - tmux操作支援

#### Step 2: 設定内容を理解する

tmux連携の設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.vim | `layers/+tools/tmux/config.vim` | tmux設定とキーマッピングを確認 |

**主要処理フロー**:
- **1-13行目**: tmux環境依存の設定（g:spacevim.tmux）
  - **2-3行目**: uniteレイヤー有効チェック
  - **4行目**: `<Leader>mw` - CtrlP tmux window
  - **5行目**: `<Leader>mf` - CtrlP tmux buffer
  - **6行目**: `<Leader>mm` - CtrlP tmux session
  - **7行目**: `<Leader>md` - CtrlP tmux command
  - **8行目**: `<Leader>mi` - CtrlP tmux command interactively
- **17-26行目**: xterm-keys対応
  - **18行目**: `if &term =~ '^screen'` - screenターミナル判定
  - **20-25行目**: 矢印キー/Home/Endのエスケープシーケンス設定

#### Step 3: tmux環境の検出方法を確認する

g:spacevim.tmux変数の設定方法を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | spacevim.vim | `core/autoload/spacevim.vim` | tmux環境検出の実装を確認 |

**読解のコツ**: $TMUX環境変数の存在によりtmux環境を検出する。

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

```
space-vim起動
    │
    └─ spacevim#bootstrap()
           │
           ├─ g:spacevim.tmux 環境検出
           │      └─ $TMUX 環境変数チェック
           │
           └─ +tools/tmux レイヤー読み込み
                  │
                  ├─ packages.vim
                  │      ├─ MP 'christoomey/vim-tmux-navigator' (常時)
                  │      │
                  │      └─ if g:spacevim.tmux
                  │             ├─ ctrlp-tmux.vim (unite有効時)
                  │             └─ vim-tmuxify
                  │
                  └─ config.vim
                         │
                         ├─ if g:spacevim.tmux
                         │      └─ CtrlP tmux キーマッピング
                         │             ├─ <Leader>mw
                         │             ├─ <Leader>mf
                         │             ├─ <Leader>mm
                         │             ├─ <Leader>md
                         │             └─ <Leader>mi
                         │
                         └─ xterm-keys 対応
                                └─ 矢印キー等のエスケープシーケンス

Ctrl+hjkl 押下時
    │
    └─ vim-tmux-navigator
           │
           ├─ Vimウィンドウ境界チェック
           │
           ├─ Vimウィンドウあり: :wincmd {h,j,k,l}
           │
           └─ Vimウィンドウなし: tmux select-pane
```

### データフロー図

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

Ctrl+h/j/k/l             vim-tmux-navigator              ウィンドウ/ペイン
           ───▶          プラグイン処理      ───▶        フォーカス移動
                              │
                              ▼
                         Vimウィンドウ境界判定
                              │
                    ┌─────────┴─────────┐
                    │                   │
               Vimウィンドウ       tmuxペイン
               :wincmd            select-pane

<Leader>m*               ctrlp-tmux.vim                  tmux操作
           ───▶          プラグイン処理      ───▶        セッション/ウィンドウ/
                                                         バッファ選択
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+tools/tmux/packages.vim` | 設定 | プラグイン登録 |
| config.vim | `layers/+tools/tmux/config.vim` | 設定 | 設定とキーマッピング |
| LAYERS.md | `layers/LAYERS.md` | ドキュメント | レイヤー一覧 |
| vim-tmux-navigator | 外部プラグイン（christoomey/vim-tmux-navigator） | プラグイン | シームレスナビゲーション |
| ctrlp-tmux.vim | 外部プラグイン（lucidstack/ctrlp-tmux.vim） | プラグイン | CtrlPでtmux検索 |
| vim-tmuxify | 外部プラグイン（jebaum/vim-tmuxify） | プラグイン | tmux操作支援 |
