# 画面設計書 8-Nuコマンドビュー

## 概要

本ドキュメントは、Nushell Exploreにおける Nuコマンドビュー画面の設計仕様を定義する。Nuコマンドビューは、Nuコマンドの実行結果をストリーミング表示する画面である。

### 本画面の処理概要

Nuコマンドビューは、レコードビューから`:nu <command>`で呼び出される画面である。指定されたNushellコマンドをバックグラウンドスレッドで実行し、結果をストリーミングでリアルタイム表示する。大量のデータを処理するコマンドでも、結果が生成されるたびに画面を更新する。

**業務上の目的・背景**：
大量のデータを処理するコマンドや、時間のかかる処理を実行する際、全ての結果が揃うまで待つのは非効率である。Nuコマンドビューは、バックグラウンドでコマンドを実行し、結果が生成されるたびにリアルタイムで表示を更新する。これにより、処理の進捗を確認しながら、途中結果を閲覧できる。

**画面へのアクセス方法**：
- レコードビューで `:nu <command>` を入力
- 例: `:nu where size > 1mb`
- 例: `:nu sort-by name`

**主要な操作・処理内容**：
1. コマンドをバックグラウンドスレッドで実行
2. 結果をチャネル経由でストリーミング受信
3. ローディングスピナー表示（実行中）
4. 結果が到着次第RecordViewに追加表示
5. auto_tailで新しい行を自動追従

**画面遷移**：
- レコードビュー（画面No.4） → :nu cmd → Nuコマンドビュー
- Nuコマンドビュー → 操作 → レコードビュー
- Nuコマンドビュー → プレビュー表示 → プレビュー（画面No.6）

**権限による表示制御**：
- 特になし。全ユーザーが同一の機能を利用可能

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | シェル実行環境 | 主機能 | Nuコマンドのバックグラウンド実行 |
| 71 | 探索モード | 主機能 | 実行結果のストリーミング表示・ローディング状態管理 |
| 69 | テーブル表示 | 補助機能 | 実行結果のRecordView/Preview形式での表示 |

## 画面種別

TUI（Terminal User Interface）ストリーミングビューア

## URL/ルーティング

N/A（CLI/TUIアプリケーションのためURL概念なし）

## 入出力項目

| 項目名 | 型 | 入力/出力 | 説明 |
|--------|-----|----------|------|
| コマンド文字列 | String | 入力 | 実行するNushellコマンド |
| 入力値 | Option<Value> | 入力 | パイプライン入力データ |
| ストリームメッセージ | StreamMessage | 処理 | バックグラウンドからの結果通知 |
| 表示状態 | ViewState | 処理 | Loading/Records/Preview/Empty/Error |

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| ローディングスピナー | 実行中を示すアニメーション | Unicode spinner (⠋⠙⠹...) |
| ステータスメッセージ | 実行状態・行数 | "Running: ..." / "Streaming: X rows" |
| 結果ビュー | RecordViewまたはPreview | 結果データの表示 |
| エラーメッセージ | エラー詳細 | エラー文字列 |

## イベント仕様

### 1-バックグラウンド実行開始

1. NuCmd::spawn でバックグラウンドスレッドを起動
2. stream_command関数でコマンドを実行
3. 結果をチャネルで送信
4. ViewStateをLoadingに設定

### 2-ストリームメッセージ受信（update関数）

**StreamMessage::Columns:**
- カラム名を保存

**StreamMessage::Rows:**
- 行データを蓄積
- RecordViewを更新/作成

**StreamMessage::IsRecord:**
- is_recordフラグをtrue

**StreamMessage::SimpleValue:**
- Previewビューを作成

**StreamMessage::Done:**
- stream_doneをtrue
- ポーリング終了

**StreamMessage::Error:**
- ViewStateをErrorに設定

### 3-キー入力（handle_input）

RecordViewまたはPreviewの状態に応じて、それぞれのhandle_inputに委譲

### 4-ビュー終了

RecordViewまたはPreviewのexit関数を呼び出し、値を返却

## データベース更新仕様

N/A（データベース操作なし）

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|----------|
| RUNNING | 情報 | {spinner} Running: {command} | コマンド実行中 |
| STREAMING | 情報 | {spinner} Streaming: X rows | ストリーミング中 |
| ROWS | 情報 | X rows | 完了後 |
| PREVIEW | 情報 | Preview | Previewビュー時 |
| NO_OUTPUT | 情報 | No output | 出力なし時 |
| ERROR | エラー | {エラー詳細} | エラー発生時 |

## 例外処理

| 例外状態 | 対応処理 |
|---------|---------|
| コマンド実行エラー | StreamMessage::Errorでエラーメッセージ送信、ViewStateをErrorに |
| ByteStream読み取りエラー | 同上 |
| チャネル切断 | stream_doneをtrueに設定 |

## 備考

- バックグラウンドスレッドでコマンドを実行（thread::spawn）
- mpsc::channelでメインスレッドと通信
- バッチサイズ1で行を送信（BATCH_SIZE = 1）
- auto_tailモードで新規行を自動追従
- スピナーアニメーション: ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏

---

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

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

### 推奨読解順序

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

Nuコマンドビューで扱う主要なデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | nu.rs | `crates/nu-explore/src/explore/commands/nu.rs` | NuView構造体（291-304行） |
| 1-2 | nu.rs | `crates/nu-explore/src/explore/commands/nu.rs` | ViewState列挙型（277-288行） |
| 1-3 | nu.rs | `crates/nu-explore/src/explore/commands/nu.rs` | StreamMessage列挙型（102-115行） |

**読解のコツ**: NuViewはViewStateで表示状態を管理し、receiverでバックグラウンドと通信

#### Step 2: コマンド実行を理解する

バックグラウンド実行の処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | nu.rs | `crates/nu-explore/src/explore/commands/nu.rs` | NuCmd::spawn関数（54-99行） |
| 2-2 | nu.rs | `crates/nu-explore/src/explore/commands/nu.rs` | stream_command関数（118-181行） |

**主要処理フロー**:
1. **54-99行**: `spawn` - バックグラウンドスレッド起動
2. **73-82行**: thread::spawnでstream_commandを実行
3. **118-181行**: コマンド実行と結果送信

#### Step 3: ストリーミング処理を理解する

メッセージ受信と表示更新を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | nu.rs | `crates/nu-explore/src/explore/commands/nu.rs` | process_messages関数（308-380行） |
| 3-2 | nu.rs | `crates/nu-explore/src/explore/commands/nu.rs` | update_record_view関数（383-417行） |

**主要処理フロー**:
- **308-380行**: チャネルからメッセージを受信し処理
- **383-417行**: RecordViewを作成/更新

#### Step 4: View実装を理解する

画面描画と入力処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | nu.rs | `crates/nu-explore/src/explore/commands/nu.rs` | View for NuView実装（433-548行） |

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

```
:nu コマンド
    |
    +-- NuCmd::spawn()                   [nu.rs:54]
            |
            +-- thread::spawn()          [nu.rs:73]
            |       +-- stream_command() [nu.rs:118]
            |               +-- run_command_with_value()
            |               +-- stream_values() [nu.rs:184]
            |
            +-- NuView::new()

NuView::update()                         [nu.rs:480]
    |
    +-- process_messages()               [nu.rs:308]
    |       +-- receiver.try_recv()
    |       +-- StreamMessage処理
    |
    +-- update_record_view()             [nu.rs:383]
            +-- RecordView::new() or 更新

NuView::draw()                           [nu.rs:434]
    |
    +-- ViewState判定
    |       +-- Loading → スピナー表示
    |       +-- Records → RecordView.draw()
    |       +-- Preview → Preview.draw()
    |       +-- Error → ステータスバーにエラー
```

### データフロー図

```
[バックグラウンド]              [メイン]                    [出力]

thread::spawn()
    |
stream_command() ─────────────▶ mpsc::channel
    │                               │
    ├─ Columns ─────────────────────┼──▶ columns保存
    ├─ Rows ────────────────────────┼──▶ rows追加
    ├─ IsRecord ────────────────────┼──▶ is_record = true
    ├─ SimpleValue ─────────────────┼──▶ Preview作成
    ├─ Done ────────────────────────┼──▶ stream_done = true
    └─ Error ───────────────────────┼──▶ ViewState::Error
                                    │
                              process_messages()
                                    │
                                    ▼
                              update_record_view()
                                    │
                                    ▼
                              RecordView ─────────────▶ TUI画面描画
                              or Preview
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nu.rs | `crates/nu-explore/src/explore/commands/nu.rs` | ソース | Nuコマンドビューのコア実装 |
| record/mod.rs | `crates/nu-explore/src/explore/views/record/mod.rs` | ソース | 結果表示用RecordView |
| preview.rs | `crates/nu-explore/src/explore/views/preview.rs` | ソース | 単純値表示用Preview |
| command.rs | `crates/nu-explore/src/explore/nu_common/command.rs` | ソース | run_command_with_value関数 |
| report.rs | `crates/nu-explore/src/explore/pager/report.rs` | ソース | ステータスレポート |
