# 機能設計書 61-Nushell統合

## 概要

本ドキュメントは、GhosttyターミナルエミュレータにおけるNushellシェル統合機能の設計を記述する。

### 本機能の処理概要

Nushell統合機能は、Ghosttyターミナルエミュレータとモダンシェルであるnushellとの連携を実現する機能である。SSH接続時のTERMINFO自動インストール、sudo実行時のTERMINFO環境変数保持などの機能を提供する。

**業務上の目的・背景**：NushellはRustで書かれたモダンなシェルであり、構造化データを扱えることが特徴である。GhosttyがNushellをサポートすることで、Nushellユーザーがリモートサーバーへのssh接続時にxterm-ghostty terminfoを自動的にインストールしたり、sudo実行時にターミナル環境を正しく保持できるようになる。これにより、Nushellユーザーの利便性が向上する。

**機能の利用シーン**：
- Nushellをデフォルトシェルとして使用しているユーザーがGhosttyを起動した際
- SSHでリモートサーバーに接続し、ghostty固有のターミナル機能を利用したい場合
- sudo権限でコマンドを実行する際にターミナル情報を正しく継承したい場合

**主要な処理内容**：
1. Ghosttyシェル統合モジュール(`ghostty`)の自動読み込み
2. SSHコマンドのラッピングによるterminfo自動インストール機能
3. sudoコマンドのラッピングによるTERMINFO環境変数保持
4. XDG_DATA_DIRSの整理処理
5. 機能フラグ(`GHOSTTY_SHELL_FEATURES`)による選択的機能有効化

**関連システム・外部連携**：
- SSH: リモートホストへの接続とterminfo自動配布
- sudo: 権限昇格時の環境変数保持
- Ghostty ssh-cache CLI: terminfoキャッシュ管理

**権限による制御**：sudo実行時の権限昇格処理では、-eや--editオプション（sudoedit）が指定された場合はTERMINFO環境変数の保持をスキップする。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はバックグラウンドで動作し、特定の画面UIは持たない |

## 機能種別

シェル連携処理 / 環境設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| GHOSTTY_SHELL_FEATURES | 環境変数 | No | カンマ区切りの機能フラグ | "ssh-env", "ssh-terminfo", "sudo" |
| GHOSTTY_BIN_DIR | 環境変数 | No | Ghosttyバイナリのディレクトリパス | 有効なパス |
| GHOSTTY_SHELL_INTEGRATION_XDG_DIR | 環境変数 | No | シェル統合用XDGディレクトリ | 有効なパス |

### 入力データソース

- 環境変数: GHOSTTY_SHELL_FEATURES、GHOSTTY_BIN_DIR、GHOSTTY_SHELL_INTEGRATION_XDG_DIR
- コマンドライン引数: ssh、sudoコマンドへ渡される引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| TERM | 環境変数 | SSH接続先での$TERM値（xterm-ghosttyまたはxterm-256color） |
| COLORTERM | 環境変数 | SSH接続先へ送信されるカラーサポート情報 |
| TERMINFO | 環境変数 | sudo実行時に保持されるterminfoパス |

### 出力先

- 環境変数への設定
- リモートホストへのterminfoインストール
- ssh-cacheへのホスト情報登録

## 処理フロー

### 処理シーケンス

```
1. Ghosttyシェル統合の初期化
   └─ ghostty.nuモジュールが自動ロードされる

2. ssh コマンド実行時
   └─ ssh機能フラグ確認 (ssh-env, ssh-terminfo)
   └─ ssh-env: TERM=xterm-256colorを設定
   └─ ssh-terminfo: ホストキャッシュ確認
       └─ キャッシュあり: TERM=xterm-ghostty使用
       └─ キャッシュなし: terminfoをリモートにインストール
           └─ 成功: キャッシュに追加
           └─ 失敗: xterm-256colorにフォールバック

3. sudo コマンド実行時
   └─ sudo機能フラグ確認
   └─ sudoedit以外: --preserve-env=TERMINFOを追加
   └─ 元のsudoコマンドを実行

4. XDG_DATA_DIRSクリーンアップ
   └─ GHOSTTY_SHELL_INTEGRATION_XDG_DIRをXDG_DATA_DIRSから削除
   └─ 環境変数を非表示化
```

### フローチャート

```mermaid
flowchart TD
    A[Ghostty起動] --> B[ghostty.nuロード]
    B --> C{コマンド実行}
    C -->|ssh| D[has_feature ssh-env?]
    C -->|sudo| E[has_feature sudo?]
    C -->|other| F[通常実行]

    D -->|Yes| G[TERM=xterm-256color設定]
    D -->|No| H{has_feature ssh-terminfo?}
    G --> H

    H -->|Yes| I[ssh-cacheチェック]
    H -->|No| J[SSHコマンド実行]

    I -->|cached| K[TERM=xterm-ghostty]
    I -->|not cached| L[terminfo転送試行]
    L -->|success| M[キャッシュ追加]
    L -->|fail| N[TERM=xterm-256color]
    M --> K
    K --> J
    N --> J

    E -->|Yes| O{sudoedit?}
    E -->|No| P[sudo実行]
    O -->|No| Q[--preserve-env=TERMINFO追加]
    O -->|Yes| P
    Q --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-61-01 | SSH環境設定 | ssh-env機能有効時、TERMをxterm-256colorに設定しCOLORTERM=truecolorを送信 | GHOSTTY_SHELL_FEATURESにssh-envが含まれる |
| BR-61-02 | terminfoキャッシュ | ssh-terminfo機能有効時、ホストごとのterminfoインストール状態をキャッシュ | GHOSTTY_SHELL_FEATURESにssh-terminfoが含まれる |
| BR-61-03 | sudo環境保持 | sudo機能有効時、sudoedit以外でTERMINFO環境変数を保持 | GHOSTTY_SHELL_FEATURESにsudoが含まれる |

### 計算ロジック

該当なし

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | infocmp失敗 | ローカルのinfocmpコマンドが失敗 | xterm-256colorにフォールバック |
| - | terminfo転送失敗 | リモートホストへのticコマンド実行失敗 | xterm-256colorにフォールバック |
| - | ssh-cache失敗 | キャッシュの読み書きに失敗 | 処理を継続、次回再試行 |

### リトライ仕様

terminfoインストールが失敗した場合、次回のSSH接続時に再試行される。

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

該当なし

## パフォーマンス要件

- SSH接続時のterminfoキャッシュ確認は即座に完了すること
- terminfoの転送は初回接続時のみ発生し、以降はキャッシュされること

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

- sudo実行時のTERMINFO保持は、sudoeditモードでは無効化される
- SSH接続時のコントロールソケットは一時ディレクトリに作成され、適切なパーミッションで保護される

## 備考

- Nushellのモジュールシステムを使用しているため、`use ghostty`でモジュールを明示的にロードすることも可能
- 機能フラグはGhosttyの設定ファイルで`shell-integration-features`オプションにより制御される

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

Nushell統合は主にシェルスクリプトで構成されており、特別なデータ構造の定義はない。代わりに環境変数を通じてデータをやり取りする。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ghostty.nu | `src/shell-integration/nushell/vendor/autoload/ghostty.nu` | モジュール全体の構造を把握 |

**読解のコツ**: Nushellの構文はRustに似ており、パイプ演算子(`|`)でデータを連鎖的に処理する。`def`でコマンド定義、`export`でモジュール外部への公開を行う。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ghostty.nu | `src/shell-integration/nushell/vendor/autoload/ghostty.nu` | モジュール定義とエクスポート |

**主要処理フロー**:
1. **1-2行目**: モジュール定義開始
2. **3-5行目**: has_feature関数の定義（機能フラグチェック）
3. **8-80行目**: sshコマンドラッパー定義
4. **83-101行目**: sudoコマンドラッパー定義
5. **104-110行目**: XDG_DATA_DIRSクリーンアップ処理

#### Step 3: SSH機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ghostty.nu | `src/shell-integration/nushell/vendor/autoload/ghostty.nu` | ssh関数（8-80行目） |

**主要処理フロー**:
- **13-19行目**: ssh-env機能によるTERM設定
- **22-73行目**: ssh-terminfo機能によるterminfoインストール
- **34行目**: ssh-cacheコマンドによるキャッシュ確認
- **59-63行目**: リモートへのterminfoインストール

#### Step 4: sudo機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ghostty.nu | `src/shell-integration/nushell/vendor/autoload/ghostty.nu` | sudo関数（83-101行目） |

**主要処理フロー**:
- **88-91行目**: sudoオプションの抽出
- **94-96行目**: sudoedit判定
- **96行目**: --preserve-env=TERMINFOの追加

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

```
ghostty.nu (シェル統合モジュール)
    │
    ├─ ghostty has_feature [feature]
    │      └─ GHOSTTY_SHELL_FEATURES環境変数を解析
    │
    ├─ ghostty ssh [...args]
    │      ├─ ssh -G (設定取得)
    │      ├─ ghostty +ssh-cache (キャッシュ確認)
    │      ├─ infocmp (terminfo取得)
    │      └─ ssh (terminfoインストール & 接続)
    │
    └─ ghostty sudo [...args]
           └─ sudo --preserve-env=TERMINFO (TERMINFO保持)
```

### データフロー図

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

GHOSTTY_SHELL_FEATURES ───▶ has_feature関数 ───▶ 機能有効/無効判定
                                │
ssh引数 ─────────────────────▶ ssh関数
                                ├── ssh-cacheチェック ───▶ TERM環境変数
                                ├── infocmp実行 ─────────▶ terminfo取得
                                └── リモートtic実行 ────▶ terminfoインストール
                                                              │
                                                              ▼
                                                    ssh-cache更新

sudo引数 ────────────────────▶ sudo関数
                                └── オプション解析 ──────▶ 修正済みsudo実行
                                                              │
                                                              ▼
                                                    TERMINFO保持
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ghostty.nu | `src/shell-integration/nushell/vendor/autoload/ghostty.nu` | ソース | Nushellシェル統合メインモジュール |
| ssh_cache.zig | `src/cli/ssh_cache.zig` | ソース | ssh-cacheコマンド実装（Zig） |
| Config.zig | `src/config/Config.zig` | ソース | shell-integration-features設定 |
