# 機能設計書 36-ファイル操作

## 概要

本ドキュメントは、Nushellにおけるファイル操作機能（cp, mv, rm, touch, open, save）の設計を記述する。これらのコマンドはファイルのコピー、移動、削除、作成、読み書きを提供する。

### 本機能の処理概要

**業務上の目的・背景**：
ファイル操作はシェルの核心的な機能であり、データの管理、バックアップ、ファイルの整理など日常的なタスクに不可欠である。Nushellはこれらの操作に対して、構造化データの自動変換や進捗表示など、従来のシェルを超えた機能を提供する。

**機能の利用シーン**：
- ファイルやディレクトリのバックアップ（cp）
- ファイルの移動やリネーム（mv）
- 不要ファイルの削除（rm）
- 空ファイルやタイムスタンプの更新（touch）
- 様々な形式のファイル読み込み（open）
- データのファイル出力（save）

**主要な処理内容**：
1. `cp`: ファイル/ディレクトリをコピーする
2. `mv`: ファイル/ディレクトリを移動またはリネームする
3. `rm`: ファイル/ディレクトリを削除する（ゴミ箱対応）
4. `touch`: ファイルを作成またはタイムスタンプを更新する
5. `open`: ファイルを開いて構造化データに変換する
6. `save`: データをファイルに保存する

**関連システム・外部連携**：
- uu_cp, uu_mv, uu_touch（uutils/coreutils）
- trash クレート（ゴミ箱機能）
- 各種フォーマット変換コマンド（from json, to json等）

**権限による制御**：
- ファイルシステムの権限に従う
- rm -t（トラッシュ）はプラットフォーム対応が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 参照画面 | コマンド入力・結果表示 |

## 機能種別

ファイルシステム操作 / データ入出力

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| paths (cp/mv) | GlobPattern/String | Yes | コピー/移動元と先 | 最低2つのパス |
| paths (rm) | GlobPattern/String | Yes | 削除対象 | 1つ以上のパス |
| files (touch) | GlobPattern/Filepath | Yes | 作成/更新対象 | 1つ以上のパス |
| files (open) | GlobPattern/String | Yes | 開くファイル | 1つ以上のパス |
| filename (save) | Filepath | Yes | 保存先ファイル | 有効なパス |

### 入力データソース

- cp/mv/rm/touch: コマンドライン引数
- open: コマンドライン引数またはパイプライン入力（ファイル名）
- save: パイプライン入力（保存するデータ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| cp/mv/rm 出力 | Nothing | 出力なし（-vでメッセージ） |
| touch 出力 | Nothing | 出力なし |
| open 出力 | Any | ファイル内容（形式に応じて変換） |
| save 出力 | Nothing | 出力なし |

### 出力先

- cp/mv/rm/touch/save: ファイルシステム
- open: パイプライン出力

## 処理フロー

### 処理シーケンス

```
[open]
1. ファイルパスの取得
   └─ 引数またはパイプライン入力から
2. glob展開
   └─ パターンにマッチするファイルを取得
3. ファイルの読み込み
   └─ バイトストリームとして読み込み
4. 拡張子に基づく変換
   └─ from {ext} コマンドがあれば自動実行
5. 結果の返却

[save]
1. 保存データの取得
   └─ パイプラインからデータを受け取り
2. ファイルパスの取得と検証
   └─ 既存ファイルの上書き確認
3. 拡張子に基づく変換
   └─ to {ext} コマンドがあれば自動実行
4. ファイルへの書き込み
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{コマンド種別}
    B -->|open| C[ファイルパス取得]
    C --> D[ファイル読み込み]
    D --> E{拡張子に対応するfromコマンド?}
    E -->|Yes| F[変換実行]
    E -->|No| G[生データ返却]
    F --> H[変換結果返却]
    B -->|save| I[保存データ取得]
    I --> J[ファイルパス取得]
    J --> K{既存ファイル?}
    K -->|Yes| L{--force?}
    L -->|No| M[エラー返却]
    L -->|Yes| N[上書き準備]
    K -->|No| O[新規作成準備]
    N --> P{拡張子に対応するtoコマンド?}
    O --> P
    P -->|Yes| Q[変換実行]
    P -->|No| R[生データ書き込み]
    Q --> S[ファイル書き込み]
    R --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-36-1 | 再帰コピー | cp -rでディレクトリを再帰コピー | ディレクトリ指定時 |
| BR-36-2 | ゴミ箱移動 | rm -tでゴミ箱に移動 | プラットフォーム対応時 |
| BR-36-3 | 自動変換（open） | 拡張子に応じてfrom {ext}を実行 | 対応コマンド存在時 |
| BR-36-4 | 自動変換（save） | 拡張子に応じてto {ext}を実行 | 対応コマンド存在時 |
| BR-36-5 | 上書き確認 | save時は-fで強制上書き | 既存ファイル時 |
| BR-36-6 | 属性保存 | cp --preserveで属性を保存 | 指定時 |

### 計算ロジック

特になし

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

### 操作別データベース影響一覧

該当なし（ファイルシステム操作のみ）
※ただしopenはSQLiteデータベースを自動検出して読み込み可能

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FileNotFound | IOエラー | 指定ファイルが存在しない | 正しいパスを指定 |
| PermissionDenied | IOエラー | アクセス権限がない | 権限を確認 |
| IsADirectory | IOエラー | ファイルを期待したがディレクトリ | ファイルを指定 |
| GenericError | 一般エラー | 保存先が既に存在 | -fオプションを使用 |
| GenericError | 一般エラー | 入力と出力が同じファイル | collectを挟む |

### リトライ仕様

該当なし

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

該当なし（ファイルシステム操作はトランザクションをサポートしない）

## パフォーマンス要件

- save -p で進捗バーを表示
- cp -p で進捗バーを表示
- 大容量ファイルはストリーミング処理

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

- ファイルシステムの権限モデルに従う
- rm --permanent で完全削除（復元不可）
- 環境に応じたゴミ箱機能の利用

## 備考

- cp, mv, touchはuutils/coreutilsの実装を使用
- trash-supportフィーチャーでゴミ箱機能を有効化
- openはSQLiteデータベースを自動検出
- saveはカスタムValue型のsaveメソッドを呼び出し可能

---

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

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

### 推奨読解順序

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

ファイル操作の設定オプションを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ucp.rs | `crates/nu-command/src/filesystem/ucp.rs` | uu_cp::Optionsの構成 |
| 1-2 | save.rs | `crates/nu-command/src/filesystem/save.rs` | ファイル書き込みオプション |

**読解のコツ**: uutils/coreutilsの設定オプションをNushellのフラグにマッピングしている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ucp.rs | `crates/nu-command/src/filesystem/ucp.rs` | UCpコマンドの実装 |
| 2-2 | umv.rs | `crates/nu-command/src/filesystem/umv.rs` | UMvコマンドの実装 |
| 2-3 | rm.rs | `crates/nu-command/src/filesystem/rm.rs` | Rmコマンドの実装 |
| 2-4 | utouch.rs | `crates/nu-command/src/filesystem/utouch.rs` | UTouchコマンドの実装 |
| 2-5 | open.rs | `crates/nu-command/src/filesystem/open.rs` | Openコマンドの実装 |
| 2-6 | save.rs | `crates/nu-command/src/filesystem/save.rs` | Saveコマンドの実装 |

**主要処理フロー**:
1. **115-308行目 (ucp.rs)**: run関数でuu_cp::copyを呼び出し
2. **81-227行目 (umv.rs)**: run関数でuu_mv::mvを呼び出し
3. **106-494行目 (rm.rs)**: rm関数でファイル削除/ゴミ箱移動
4. **64-268行目 (open.rs)**: run関数でファイル読み込みと変換
5. **59-260行目 (save.rs)**: run関数でデータ保存と変換

#### Step 3: 自動変換ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | open.rs | `crates/nu-command/src/filesystem/open.rs` | 拡張子からコンバータを探す（207-213行目） |
| 3-2 | save.rs | `crates/nu-command/src/filesystem/save.rs` | 拡張子からコンバータを探す（357-377行目） |

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

```
Open::run()
    │
    ├─ call.rest() [ファイルパス取得]
    │
    ├─ glob_from() [glob展開]
    │
    ├─ std::fs::File::open()
    │
    ├─ engine_state.find_decl() [from {ext}検索]
    │      │
    │      └─ [存在する] → eval_call()
    │
    └─ PipelineData::ByteStream [生データ返却]

Save::run()
    │
    ├─ call.req() [ファイルパス取得]
    │
    ├─ engine_state.find_decl() [to {ext}検索]
    │      │
    │      └─ [存在する] → decl.run()
    │
    ├─ value_to_bytes() [データ変換]
    │
    └─ file.write_all() [ファイル書き込み]
```

### データフロー図

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

ファイルパス ────▶ Open::run() ────────▶ 構造化データ
    │                  │
    │                  ├─ ファイル読み込み
    │                  │
    │                  └─ from {ext} 変換

データ ─────────▶ Save::run() ────────▶ ファイル
    │                  │
ファイルパス ──────────┤
                       ├─ to {ext} 変換
                       │
                       └─ ファイル書き込み
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ucp.rs | `crates/nu-command/src/filesystem/ucp.rs` | ソース | cp コマンド実装 |
| umv.rs | `crates/nu-command/src/filesystem/umv.rs` | ソース | mv コマンド実装 |
| rm.rs | `crates/nu-command/src/filesystem/rm.rs` | ソース | rm コマンド実装 |
| utouch.rs | `crates/nu-command/src/filesystem/utouch.rs` | ソース | touch コマンド実装 |
| open.rs | `crates/nu-command/src/filesystem/open.rs` | ソース | open コマンド実装 |
| save.rs | `crates/nu-command/src/filesystem/save.rs` | ソース | save コマンド実装 |
| mod.rs | `crates/nu-command/src/filesystem/mod.rs` | ソース | filesystemモジュール定義 |
| util.rs | `crates/nu-command/src/filesystem/util.rs` | ソース | 共通ユーティリティ |
