# 機能設計書 63-omz_termsupport_precmd

## 概要

本ドキュメントは、Oh My Zshのターミナルサポート機能における`omz_termsupport_precmd`関数の設計を記載する。この関数は、zshのprecmdフック（プロンプト表示前に実行）として登録され、ターミナルのタイトルをアイドル状態（コマンド未実行時）の表示に設定する。

### 本機能の処理概要

**業務上の目的・背景**：ターミナルでコマンドを実行していない待機状態（プロンプト表示中）では、ユーザーが現在の作業コンテキストを把握できるようにタイトルを設定することが重要である。この機能は、プロンプトが表示されるたびに、現在のディレクトリやユーザー情報をターミナルタイトルに自動的に反映し、複数ターミナルでの作業時の識別を容易にする。

**機能の利用シーン**：
- コマンド実行完了後、プロンプトが再表示される際
- シェル起動直後、最初のプロンプトが表示される際
- ディレクトリ移動後、新しいプロンプトが表示される際

**主要な処理内容**：
1. 自動タイトル設定が有効かどうかを確認する
2. title関数を呼び出してアイドル状態のタイトルを設定する

**関連システム・外部連携**：
- title関数（機能No.62）を呼び出し
- zshのprecmdフックシステム（add-zsh-hook）

**権限による制御**：`DISABLE_AUTO_TITLE`環境変数がtrueの場合、この機能は無効化される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLIコマンドのため関連画面なし |

## 機能種別

フック処理 / ターミナル制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | precmdフックとして引数なしで呼び出される | - |

### 入力データソース

- 環境変数: `$DISABLE_AUTO_TITLE`
- シェル変数: `$ZSH_THEME_TERM_TAB_TITLE_IDLE`, `$ZSH_THEME_TERM_TITLE_IDLE`

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | integer | 常に0 |
| 副作用 | - | title関数経由でターミナルタイトルを設定 |

### 出力先

- ターミナルエミュレータ（title関数経由）

## 処理フロー

### 処理シーケンス

```
1. DISABLE_AUTO_TITLEチェック
   └─ trueなら即座にreturn 0
2. title関数呼び出し
   └─ $ZSH_THEME_TERM_TAB_TITLE_IDLE と $ZSH_THEME_TERM_TITLE_IDLE を引数に渡す
```

### フローチャート

```mermaid
flowchart TD
    A[omz_termsupport_precmd開始] --> B{DISABLE_AUTO_TITLE == true?}
    B -->|Yes| C[return 0]
    B -->|No| D[title関数呼び出し]
    D --> E[タブタイトル: %15<..<%~%<<]
    D --> F[ウィンドウタイトル: %n@%m:%~]
    E --> G[終了]
    F --> G
    C --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 自動タイトル無効化 | DISABLE_AUTO_TITLEがtrueの場合、タイトル設定を行わない | 環境変数設定時 |
| BR-02 | タブタイトル形式 | 15文字に左側切り詰めた現在ディレクトリパス | 常時 |
| BR-03 | ウィンドウタイトル形式 | ユーザー名@ホスト名:現在ディレクトリ | 常時（Apple Terminal除く） |
| BR-04 | Apple Terminal特例 | Apple Terminalではウィンドウタイトルにディレクトリを含めない | TERM_PROGRAM == Apple_Terminal |

### 計算ロジック

**タブタイトルフォーマット**:
```
%15<..<%~%<<
```
- `%15<..`: 15文字を超える場合、左側を".."で切り詰め
- `%~`: 現在ディレクトリ（$HOMEは~で置換）
- `%<<`: 切り詰め終了

**ウィンドウタイトルフォーマット**:
```
%n@%m:%~
```
- `%n`: ユーザー名
- `%m`: ホスト名（短縮形）
- `%~`: 現在ディレクトリ

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

該当なし（データベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | エラーは発生しない設計 | - |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- プロンプト表示のたびに実行されるため、数ミリ秒以内で完了すること
- ユーザー体感に影響しないレベルの高速性が必要

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

- ホスト名やパス情報がターミナルタイトルに表示されるため、画面共有時などに注意が必要

## 備考

- Emacs内（vterm除く）およびSSH接続時は、omz_termsupport_cwdと同様に条件付きで動作
- テーマによってZSH_THEME_TERM_TAB_TITLE_IDLEやZSH_THEME_TERM_TITLE_IDLEをカスタマイズ可能

---

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

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

### 推奨読解順序

#### Step 1: デフォルトタイトル変数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | termsupport.zsh | `lib/termsupport.zsh` | 41-46行目のデフォルトタイトル変数定義 |

**主要処理フロー**:
- **41行目**: `ZSH_THEME_TERM_TAB_TITLE_IDLE="%15<..<%~%<<"` - 15文字に切り詰めたPWD
- **42行目**: `ZSH_THEME_TERM_TITLE_IDLE="%n@%m:%~"` - ユーザー@ホスト:パス
- **44-46行目**: Apple Terminalの特別処理（ディレクトリはOSC 7で表示するため除外）

**読解のコツ**:
- `%15<..`はzshのプロンプト展開で、15文字を超える場合に左側を切り詰める
- `%~`は$HOMEを~に置換した現在ディレクトリ
- `%n`はユーザー名、`%m`はホスト名の短縮形

#### Step 2: omz_termsupport_precmd関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | termsupport.zsh | `lib/termsupport.zsh` | 48-52行目のomz_termsupport_precmd関数 |

**主要処理フロー**:
- **49-50行目**: `[[ "${DISABLE_AUTO_TITLE:-}" != true ]] || return 0` - 自動タイトルが無効なら早期return
- **51行目**: `title "$ZSH_THEME_TERM_TAB_TITLE_IDLE" "$ZSH_THEME_TERM_TITLE_IDLE"` - title関数呼び出し

#### Step 3: フック登録を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | termsupport.zsh | `lib/termsupport.zsh` | 105-110行目のフック登録処理 |

**主要処理フロー**:
- **105行目**: `autoload -Uz add-zsh-hook` - add-zsh-hook関数をロード
- **107-109行目**: Emacs外またはvterm内の場合のみフックを登録
- **108行目**: `add-zsh-hook precmd omz_termsupport_precmd` - precmdフックに登録

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

```
zshプロンプト表示
    │
    └─ precmdフック実行
           │
           └─ omz_termsupport_precmd()
                  │
                  ├─ DISABLE_AUTO_TITLEチェック
                  │
                  └─ title()
                         │
                         └─ エスケープシーケンス出力
```

### データフロー図

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

$ZSH_THEME_TERM_TAB_TITLE_IDLE
  "%15<..<%~%<<" ──────────────▶                                ┌─ タブタイトル
                                  omz_termsupport_precmd()      │   "~/Work/project"
$ZSH_THEME_TERM_TITLE_IDLE       title()呼び出し ──────────────▶│
  "%n@%m:%~" ──────────────────▶                                └─ ウィンドウタイトル
                                                                    "user@host:~/Work/project"
$DISABLE_AUTO_TITLE ───────────▶  有効/無効判定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| termsupport.zsh | `lib/termsupport.zsh` | ソース | omz_termsupport_precmd関数およびターミナルサポートのメイン実装 |
