# 機能設計書 54-プロセス管理

## 概要

本ドキュメントは、Nushellにおけるプロセス管理機能の設計仕様を記載する。この機能は、システムで実行中のプロセス一覧を取得するpsコマンドと、プロセスを終了するkillコマンドを提供する。

### 本機能の処理概要

プロセス管理機能は、オペレーティングシステム上で実行されているプロセスの情報取得と制御を行う。

**業務上の目的・背景**：システム管理、デバッグ、リソース監視において、実行中プロセスの把握とその制御は基本的な操作である。従来のps/killコマンドをNushellの構造化データと統合し、フィルタリング・ソート・パイプライン処理を可能にする。

**機能の利用シーン**：
- CPU/メモリ使用量の高いプロセスの特定
- 特定の名前を持つプロセスの検索・終了
- プロセスツリーの確認（親プロセスID参照）
- 暴走プロセスの強制終了
- スクリプトからのプロセス管理自動化

**主要な処理内容**：
1. nu_systemクレートを使用したプロセス情報収集
2. プロセス情報のテーブル形式での出力
3. PIDを指定したプロセス終了シグナル送信

**関連システム・外部連携**：
- オペレーティングシステムのプロセス管理機能
- Linux: /proc ファイルシステム（procfsクレート）
- macOS: sysinfo
- Windows: Windows API

**権限による制御**：
- 他ユーザーのプロセス終了には管理者権限が必要
- プロセス情報取得は一般ユーザーでも可能（一部制限あり）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI専用コマンド |

## 機能種別

システム情報取得 / システム制御

## 入力仕様

### 入力パラメータ

#### ps

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --long, -l | Switch | No | 詳細情報を表示 | - |

#### kill

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pid | Int (rest) | Yes | 終了するプロセスID | 1つ以上 |
| --force, -f | Switch | No | 強制終了（SIGKILL相当） | - |
| --quiet, -q | Switch | No | 出力を抑制 | - |
| --signal, -s | Int | No (Unix only) | 送信するシグナル番号 | デフォルト15 (SIGTERM) |

### 入力データソース

コマンドライン引数、パイプライン（killでPID取得）

## 出力仕様

### 出力データ

#### ps

| 項目名 | 型 | 説明 |
|--------|-----|------|
| pid | Int | プロセスID |
| ppid | Int | 親プロセスID |
| name | String | プロセス名 |
| status | String | プロセス状態（Unix only） |
| cpu | Float | CPU使用率 |
| mem | Filesize | メモリ使用量 |
| virtual | Filesize | 仮想メモリサイズ |
| command | String | コマンドライン（--long時） |
| start_time | Date | 開始時刻（--long時） |
| user_id/user | Int/String | ユーザーID/名（--long時、OS依存） |
| priority | Int | 優先度（--long時） |
| process_threads | Int | スレッド数（--long時、Linux/macOS） |
| cwd | String | カレントディレクトリ（--long時） |

#### kill

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (出力) | Nothing/String | 成功時はNothing、失敗時はエラーメッセージ |

### 出力先

パイプライン出力

## 処理フロー

### 処理シーケンス（ps）

```
1. オプション解析
   └─ --longフラグの確認
2. プロセス情報収集
   └─ nu_system::collect_proc()でプロセス一覧取得
3. レコード構築
   └─ 各プロセスの情報をRecordに格納
4. 結果返却
   └─ テーブルとしてPipelineDataを返却
```

### 処理シーケンス（kill）

```
1. 引数解析
   └─ PIDリスト、フラグ、シグナル番号の取得
2. バリデーション
   └─ PIDが1つ以上、force/signalの排他確認
3. killコマンド構築
   └─ nu_system::build_kill_command()で外部コマンド構築
4. コマンド実行
   └─ 子プロセスとして実行
5. 結果処理
   └─ 成功/失敗に応じた出力
```

### フローチャート

```mermaid
flowchart TD
    A[ps実行] --> B[collect_proc呼び出し]
    B --> C[プロセスリスト取得]
    C --> D{--long?}
    D -->|Yes| E[詳細情報追加]
    D -->|No| F[基本情報のみ]
    E --> G[テーブル出力]
    F --> G

    H[kill実行] --> I{PID指定あり?}
    I -->|No| J[MissingParameterエラー]
    I -->|Yes| K{force && signal?}
    K -->|Yes| L[IncompatibleParametersエラー]
    K -->|No| M[killコマンド構築]
    M --> N[コマンド実行]
    N --> O{成功?}
    O -->|Yes| P[Nothing返却]
    O -->|No| Q[エラーメッセージ返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | CPU使用率サンプリング | 100msのサンプリング間隔 | ps実行時 |
| BR-02 | force/signal排他 | --forceと--signalは同時指定不可 | Unix環境でのkill |
| BR-03 | デフォルトシグナル | シグナル未指定時はSIGTERM(15) | kill実行時 |
| BR-04 | quiet出力抑制 | --quiet時はstdin/stdout/stderrをnull | kill実行時 |

### 計算ロジック

特になし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| MissingParameter | 引数エラー | killでPID未指定 | PIDを指定 |
| IncompatibleParameters | 引数エラー | force+signal同時指定 | どちらか一方のみ指定 |
| GenericError | 実行エラー | プロセス終了失敗 | 権限確認、PID存在確認 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- psコマンドはCPU使用率取得のため100msのサンプリング時間が必要
- --longオプション使用時は追加情報取得のため若干遅延する可能性

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

- 他ユーザーのプロセス終了には適切な権限が必要
- シグナル送信は悪用可能なため、スクリプトでの使用時は注意

## 備考

- Windowsではステータス情報が非表示
- プラットフォームによって取得可能な詳細情報が異なる

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ps.rs | `crates/nu-command/src/system/ps.rs` | psコマンドの出力レコード構造 |

**読解のコツ**:
- **90-104行目**: 基本レコード構造（pid, ppid, name, status, cpu, mem, virtual）
- **106-188行目**: --long時の追加フィールド（OS別実装）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ps.rs | `crates/nu-command/src/system/ps.rs` | run_ps()メソッド |
| 2-2 | kill.rs | `crates/nu-command/src/platform/kill.rs` | run()メソッド |

**主要処理フロー（ps.rs）**:
- **80-84行目**: run_ps()の開始、--longフラグ確認
- **89行目**: nu_system::collect_proc()でプロセス収集

**主要処理フロー（kill.rs）**:
- **52-56行目**: 引数解析（PID、force、signal、quiet）
- **58-63行目**: PID未指定チェック
- **65-86行目**: force/signal排他チェック（Unix）
- **88-93行目**: build_kill_command()でコマンド構築
- **101-117行目**: コマンド実行と結果処理

#### Step 3: プラットフォーム別実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ps.rs | `crates/nu-command/src/system/ps.rs` | OS別の詳細情報取得 |

**OS別実装ポイント**:
- **108-136行目**: Linux固有（procfs使用、start_time、user_id、priority等）
- **137-176行目**: Windows固有（start_time、user、user_sid等）
- **177-187行目**: macOS固有（start_time、user_id、priority、task_thread_num）

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

```
ps コマンド
    │
    └─ run_ps()
           │
           ├─ nu_system::collect_proc()
           │      └─ プラットフォーム別のプロセス情報収集
           │
           └─ Record構築
                  ├─ 基本情報（pid, ppid, name, cpu, mem）
                  └─ 詳細情報（--long時、OS依存）

kill コマンド
    │
    └─ run()
           │
           ├─ バリデーション
           │      ├─ PID存在確認
           │      └─ force/signal排他確認
           │
           ├─ nu_system::build_kill_command()
           │      └─ 外部killコマンド構築
           │
           └─ Command::output()
                  └─ 外部プロセス実行
```

### データフロー図

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

(なし / --long) ────────▶ nu_system::collect_proc() ───▶ Table (プロセス一覧)
                         Record構築

PID (複数可) ───────────▶ build_kill_command() ────────▶ Nothing / Error
force / signal ─────────▶ 外部killコマンド実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ps.rs | `crates/nu-command/src/system/ps.rs` | ソース | psコマンドの実装 |
| kill.rs | `crates/nu-command/src/platform/kill.rs` | ソース | killコマンドの実装 |
| nu-system | `crates/nu-system/` | クレート | プロセス情報収集ライブラリ |
