rufio 0.9.0

data/README.md

@@ -0,0 +1,631 @@
+# rufio
+
+Ruby製のターミナルベースファイルマネージャー
+
+**日本語** | [English](./README_EN.md)
+
+## 概要
+
+rufioは、Yaziにインスパイアされたターミナル上で動作するファイルマネージャーです。Rubyで実装されており、プラグインサポートを備えています。軽量で高速な操作性を提供し、ファイルの閲覧・管理・検索機能を備えています。
+
+## 特徴
+
+- **軽量でシンプル**: Rubyで書かれた軽量なファイルマネージャー
+- **直感的な操作**: Vimライクなキーバインド
+- **プラグインシステム**: 拡張可能なプラグインアーキテクチャ
+- **コマンドモード**: Tab補完とフローティングウィンドウを備えた強力なコマンドシステム
+- **ファイルプレビュー**: テキストファイルの内容をその場で確認
+- **ファイル選択・操作**: 複数ファイルの選択、移動、コピー、削除が可能
+- **ベースディレクトリ操作**: 起動ディレクトリへの一括ファイル移動・コピー
+- **リアルタイムフィルター**: sキーでファイル名の絞り込み表示
+- **高度な検索機能**: fzfとrgaを使った強力な検索
+- **マルチプラットフォーム**: macOS、Linux、Windowsで動作
+- **外部エディタ連携**: お気に入りのエディタでファイルを開く
+- **ヘルスチェック**: システム依存関係の確認機能
+
+## インストール
+
+```bash
+gem install rufio
+```
+
+または、Gemfileに追加してください:
+
+```ruby
+gem 'rufio'
+```
+
+## 使い方
+
+### 基本的な起動方法
+
+```bash
+rufio           # カレントディレクトリで起動
+rufio /path/to  # 指定したディレクトリで起動
+```
+
+### ヘルスチェック
+
+```bash
+rufio -c                # システム依存関係をチェック
+rufio --check-health    # 上記と同じ
+rufio --help           # ヘルプメッセージを表示
+```
+
+### キーバインド一覧
+
+#### 基本ナビゲーション
+
+| キー          | 機能                               |
+| ------------- | ---------------------------------- |
+| `j`           | 下に移動                           |
+| `k`           | 上に移動                           |
+| `h`           | 親ディレクトリに移動               |
+| `l` / `Enter` | ディレクトリに入る・ファイルを選択 |
+
+#### 高速ナビゲーション
+
+| キー | 機能               |
+| ---- | ------------------ |
+| `g`  | リストの先頭に移動 |
+| `G`  | リストの末尾に移動 |
+
+#### ファイル操作
+
+| キー | 機能                                               |
+| ---- | -------------------------------------------------- |
+| `o`  | 選択中のファイルを外部エディタで開く               |
+| `e`  | 現在のディレクトリをファイルエクスプローラーで開く |
+| `r`  | ディレクトリ内容を更新                             |
+| `a`  | 新しいファイルを作成                               |
+| `A`  | 新しいディレクトリを作成                           |
+
+#### ファイル選択・操作
+
+| キー    | 機能                                                 |
+| ------- | ---------------------------------------------------- |
+| `Space` | ファイル・ディレクトリを選択・選択解除（複数選択可） |
+| `m`     | 選択したアイテムをベースディレクトリに移動           |
+| `p`     | 選択したアイテムをベースディレクトリにコピー         |
+| `x`     | 選択したアイテムを削除                               |
+
+#### リアルタイムフィルター機能
+
+| キー        | 機能                                       |
+| ----------- | ------------------------------------------ |
+| `f`         | フィルターモード開始・再編集               |
+| 文字入力    | ファイル名で絞り込み（フィルターモード中） |
+| `Enter`     | フィルター維持で通常モードに戻る           |
+| `ESC`       | フィルターをクリアして通常モードに戻る     |
+| `Backspace` | 文字削除（フィルターモード中）             |
+
+#### 検索機能
+
+| キー | 機能                                      |
+| ---- | ----------------------------------------- |
+| `s`  | fzfによるファイル名検索（プレビュー付き） |
+| `F`  | rgaによるファイル内容検索                 |
+
+#### ブックマーク機能
+
+| キー      | 機能                         |
+| --------- | ---------------------------- |
+| `b`       | ブックマークメニューを表示   |
+| `1`-`9`   | 対応する番号のブックマークに移動 |
+
+#### zoxide連携機能
+
+| キー | 機能                               |
+| ---- | ---------------------------------- |
+| `z`  | zoxide履歴からディレクトリを選択移動 |
+
+#### コマンドモード
+
+| キー   | 機能                                     |
+| ------ | ---------------------------------------- |
+| `:`    | コマンドモードを起動                     |
+| `Tab`  | コマンド補完（コマンドモード中）         |
+| `Enter`| コマンドを実行（コマンドモード中）       |
+| `ESC`  | コマンドモードをキャンセル（コマンドモード中） |
+
+#### システム操作
+
+| キー | 機能         |
+| ---- | ------------ |
+| `q`  | rufioを終了 |
+
+### ファイル選択・操作機能の詳細
+
+#### ファイル・ディレクトリ選択 (`Space`)
+
+- **選択・選択解除**: `Space`キーでファイルやディレクトリを選択・選択解除
+- **複数選択**: 複数のファイルやディレクトリを同時に選択可能
+- **視覚的表示**: 選択されたアイテムは✓マークと緑色の背景で表示
+- **選択状態の表示**: 画面上部2行目に選択中のアイテム数が表示
+
+#### ベースディレクトリ操作
+
+rufio起動時のディレクトリが**ベースディレクトリ**として設定され、選択したファイルの移動・コピー先となります。
+
+| 操作     | キー | 機能                                     |
+| -------- | ---- | ---------------------------------------- |
+| **移動** | `m`  | 選択したアイテムをベースディレクトリに移動 |
+| **コピー** | `p`  | 選択したアイテムをベースディレクトリにコピー |
+| **削除** | `x`  | 選択したアイテムを削除                   |
+
+#### 削除操作の詳細
+
+- **フローティングダイアログ確認**: モダンなフローティングウィンドウで明確な選択肢を表示
+- **視覚的フィードバック**: 赤い枠線と警告色で注意を引く
+- **安全な操作**: 削除前のダブルチェック
+- **包括的エラーハンドリング**: 削除失敗時の詳細なエラーメッセージ
+- **リアルタイム結果表示**: フローティングダイアログで成功/失敗数を表示
+- **ファイルシステム検証**: 成功報告前に実際の削除を確認
+- **デバッグサポート**: BENIYA_DEBUG=1でオプションのデバッグログ出力
+
+#### 操作の流れ
+
+```
+1. Space → ファイル・ディレクトリを選択（複数選択可）
+2. 操作キーを選択:
+   - m → ベースディレクトリに移動
+   - p → ベースディレクトリにコピー
+   - x → 削除
+3. フローティングダイアログ → Y/Nで確認、ESCでキャンセル
+4. 結果表示 → フローティングウィンドウで操作結果を確認
+```
+
+#### 安全機能
+
+- **フローティング確認ダイアログ**: 確認用のモダンなフローティングウィンドウインターフェース
+- **視覚警告システム**: 危険な操作時の赤い枠線と警告色
+- **重複チェック**: 同名ファイルがある場合は自動でスキップ
+- **エラーハンドリング**: 権限不足などのエラーに適切に対応
+- **操作ログ**: フローティングダイアログで処理結果を詳細表示
+- **削除後検証**: ファイルシステムから実際に削除されたことを確認
+
+### フィルター機能の詳細
+
+#### リアルタイムフィルター (`f`)
+
+- **フィルター開始**: `f`キーを押してフィルターモードに入る
+- **文字入力による絞り込み**: 日本語・英数字・記号に対応
+- **リアルタイム更新**: 文字を入力するたびに表示が更新される
+- **フィルター維持**: `Enter`キーでフィルターを保持したまま通常操作に戻る
+- **フィルタークリア**: `ESC`キーでフィルターをクリアして通常表示に戻る
+- **再編集**: フィルター適用中に`f`キーで再編集モード
+- **文字削除**: `Backspace`で文字削除、全削除時は自動でフィルタークリア
+
+#### 使用例
+
+```
+1. f → フィルターモード開始
+2. ".rb" → Rubyファイルのみ表示
+3. Enter → フィルター維持で通常操作
+4. j/k → フィルター結果内をナビゲーション
+5. f → フィルター再編集
+6. ESC → フィルタークリア
+```
+
+### 検索機能の詳細
+
+#### ファイル名検索 (`s`)
+
+- `fzf`を使用したインタラクティブなファイル名検索
+- リアルタイムプレビュー表示
+- 選択したファイルは自動で外部エディタで開かれる
+
+#### ファイル内容検索 (`F`)
+
+- `rga`（ripgrep-all）を使用した高度なファイル内容検索
+- PDF、Word文書、画像内テキストなども検索対象
+- 検索結果をfzfで絞り込み、該当行にジャンプしてファイルを開く
+
+### ブックマーク機能の詳細
+
+#### ブックマーク操作 (`b`)
+
+- **ブックマーク追加**: `[A]` - 現在のディレクトリをブックマークに追加
+- **ブックマーク一覧**: `[L]` - 登録済みブックマークの一覧表示
+- **ブックマーク削除**: `[R]` - ブックマークを削除
+- **番号ジャンプ**: `1-9` - 対応する番号のブックマークに直接移動
+
+#### 高速ナビゲーション (`1`-`9`)
+
+- ブックマークメニューを経由せず、数字キーでブックマークに直接ジャンプ
+- 最大9個のブックマークをサポート
+- ブックマーク情報は画面上部に表示
+
+#### ブックマークの永続化
+
+- ブックマーク情報は `~/.config/rufio/bookmarks.json` に自動保存
+- rufio再起動後もブックマーク情報が保持される
+- JSONファイルを直接編集することも可能
+
+### zoxide連携機能の詳細
+
+#### zoxide履歴移動 (`z`)
+
+- **スマート履歴**: zoxideが記録したディレクトリ移動履歴を表示
+- **フリークエンシー順**: よく使用するディレクトリほど上位に表示
+- **インタラクティブ選択**: フローティングウィンドウで履歴を選択
+- **高速ナビゲーション**: 数字キーで直接ディレクトリを選択
+- **パス省略表示**: ホームディレクトリを`~`で表示し見やすく
+
+#### 使用例
+
+```
+1. z → zoxide履歴メニューを表示
+2. 1-20 → 表示された番号でディレクトリを選択
+3. ESC → キャンセルして元の画面に戻る
+```
+
+#### zoxideについて
+
+[zoxide](https://github.com/ajeetdsouza/zoxide)は、ディレクトリ移動履歴を学習するスマートなcdコマンドです。
+
+```bash
+# zoxideのインストール
+# macOS (Homebrew)
+brew install zoxide
+
+# Ubuntu/Debian
+apt install zoxide
+
+# その他のインストール方法は公式ドキュメントを参照
+# https://github.com/ajeetdsouza/zoxide#installation
+```
+
+#### 動作要件
+
+- zoxideがシステムにインストールされている必要があります
+- zoxideが無効な場合は適切なメッセージが表示されます
+- 履歴が空の場合も適切にハンドリングされます
+
+### コマンドモードの詳細
+
+#### コマンドモードの起動 (`:`)
+
+- `:`キーを押してコマンドモードを起動
+- 画面最下部にコマンド入力欄が表示される
+- プラグインが提供するコマンドを実行できる
+
+#### Tab補完機能
+
+- **インテリジェントな補完**: コマンド名の一部を入力して`Tab`キーを押すと自動補完
+- **複数候補の処理**: 複数のコマンドが一致する場合は共通プレフィックスまで補完
+- **単一候補の自動完成**: 一つだけマッチする場合は完全に補完される
+- **リアルタイム更新**: 入力内容に応じて候補が動的に変化
+
+#### フローティングウィンドウでの結果表示
+
+- **視覚的フィードバック**: コマンド実行結果をモダンなフローティングウィンドウで表示
+- **色分けされた結果**:
+  - **緑色のボーダー**: コマンドが正常に実行された場合
+  - **赤色のボーダー**: エラーまたは警告が発生した場合
+- **中央配置**: 画面中央に自動的に配置され視認性が高い
+- **自動サイズ調整**: 結果の内容に応じてウィンドウサイズが自動調整
+- **簡単に閉じる**: 任意のキーを押すとウィンドウを閉じて通常操作に戻る
+
+#### 使用例
+
+```
+1. : → コマンドモードを起動
+2. "he" → コマンド名の一部を入力
+3. Tab → 補完（"hello", "help", "health"などが候補）
+4. Enter → コマンドを実行
+5. フローティングウィンドウで結果を確認
+6. 任意のキーを押してウィンドウを閉じる
+```
+
+#### 利用可能なコマンド
+
+コマンドはプラグインによって提供されます。プラグインシステムの詳細については後述の「プラグインシステム」セクションを参照してください。
+
+### 必要な外部ツール
+
+検索機能・履歴機能を使用するには、以下のツールが必要です:
+
+```bash
+# macOS (Homebrew)
+brew install fzf rga zoxide
+
+# Ubuntu/Debian
+apt install fzf zoxide
+# rgaは別途インストールが必要: https://github.com/phiresky/ripgrep-all
+
+# その他のLinuxディストリビューション
+# パッケージマネージャーまたは手動インストールが必要
+```
+
+#### 各ツールの用途
+
+- **fzf**: ファイル名検索機能（`s`キー）
+- **rga**: ファイル内容検索機能（`F`キー）  
+- **zoxide**: ディレクトリ履歴移動機能（`z`キー）
+
+## 設定
+
+### 色設定（カスタマイズ）
+
+rufioではファイルタイプや UI 要素の色をカスタマイズできます。HSLカラーモデルによる直感的な色指定をサポートしています。
+
+#### サポートされる色形式
+
+```ruby
+# HSL（色相・彩度・明度）- 推奨形式
+{hsl: [220, 80, 60]}  # 色相220度、彩度80%、明度60%
+
+# RGB（赤・緑・青）
+{rgb: [100, 150, 200]}
+
+# HEX（16進数）
+{hex: "#6496c8"}
+
+# 従来のシンボル
+:blue, :red, :green, :yellow, :cyan, :magenta, :white, :black
+
+# ANSIカラーコード
+"34" または 34
+```
+
+#### 設定例
+
+```ruby
+# ~/.config/rufio/config.rb
+COLORS = {
+  # HSLでの色指定（直感的で調整しやすい）
+  directory: {hsl: [220, 80, 60]},    # 青系でディレクトリ
+  file: {hsl: [0, 0, 90]},            # 薄いグレーで通常ファイル
+  executable: {hsl: [120, 70, 50]},   # 緑系で実行ファイル
+  selected: {hsl: [50, 90, 70]},      # 黄色で選択項目
+  preview: {hsl: [180, 60, 65]},      # シアンでプレビュー
+
+  # 他の形式も併用可能
+  # directory: :blue,                 # シンボル
+  # file: {rgb: [200, 200, 200]},     # RGB
+  # executable: {hex: "#00aa00"},     # HEX
+}
+```
+
+#### HSLカラーモデルについて
+
+- **色相（Hue）**: 0-360度（0=赤、120=緑、240=青）
+- **彩度（Saturation）**: 0-100%（0=グレー、100=鮮やか）
+- **明度（Lightness）**: 0-100%（0=黒、50=標準、100=白）
+
+#### 設定可能な項目
+
+- `directory`: ディレクトリの色
+- `file`: 通常ファイルの色
+- `executable`: 実行可能ファイルの色
+- `selected`: 選択中の項目の色
+- `preview`: プレビューパネルの色
+
+## プラグインシステム
+
+rufioは拡張可能なプラグインシステムを備えており、独自の機能を簡単に追加できます。
+
+### プラグインの配置場所
+
+#### 1. 本体同梱プラグイン
+```
+lib/rufio/plugins/*.rb
+```
+rufioに標準で含まれるプラグイン。外部gem依存なしの基本機能を提供。
+
+#### 2. ユーザープラグイン
+```
+~/.rufio/plugins/*.rb
+```
+ユーザーが自由に追加できるプラグイン。GitHub GistやrawURLから取得可能。
+
+### プラグインの作成方法
+
+#### シンプルなプラグイン例
+
+```ruby
+# ~/.rufio/plugins/hello.rb
+module Rufio
+  module Plugins
+    class Hello < Plugin
+      def name
+        'Hello'
+      end
+
+      def description
+        'シンプルな挨拶プラグイン'
+      end
+
+      def commands
+        {
+          hello: method(:say_hello)
+        }
+      end
+
+      private
+
+      def say_hello
+        "Hello from rufio!"
+      end
+    end
+  end
+end
+```
+
+**プラグインの使い方:**
+
+1. rufioを起動
+2. `:`キーでコマンドモードを起動
+3. `hello`と入力（または`he`と入力してTabキーで補完）
+4. Enterキーで実行
+5. フローティングウィンドウに"Hello from rufio!"が表示される
+
+#### 外部gemに依存するプラグイン例
+
+```ruby
+# ~/.rufio/plugins/ai_helper.rb
+module Rufio
+  module Plugins
+    class AiHelper < Plugin
+      requires 'anthropic'  # 依存gem宣言
+
+      def name
+        'AiHelper'
+      end
+
+      def description
+        'Claude APIを使ったAIアシスタント'
+      end
+
+      def commands
+        {
+          ai: method(:ask_ai)
+        }
+      end
+
+      def initialize
+        super  # 依存チェック実行
+        @client = Anthropic::Client.new(
+          api_key: ENV['ANTHROPIC_API_KEY']
+        )
+      end
+
+      private
+
+      def ask_ai
+        response = @client.messages.create(
+          model: "claude-3-5-sonnet-20241022",
+          max_tokens: 1024,
+          messages: [{role: "user", content: "Hello, Claude!"}]
+        )
+        response.content.first.text
+      end
+    end
+  end
+end
+```
+
+**プラグインの使い方:**
+
+1. 依存gemをインストール: `gem install anthropic`
+2. 環境変数を設定: `export ANTHROPIC_API_KEY=your_api_key`
+3. rufioを起動
+4. `:`キーでコマンドモードを起動
+5. `ai`と入力してEnterキーで実行
+6. フローティングウィンドウにClaude APIからの応答が表示される
+
+### プラグインの管理
+
+#### プラグインの有効/無効設定
+
+`~/.rufio/config.yml`でプラグインの有効/無効を制御できます：
+
+```yaml
+plugins:
+  fileoperations:
+    enabled: true
+  ai_helper:
+    enabled: true
+  my_custom:
+    enabled: false
+```
+
+#### デフォルト動作
+
+- `config.yml`が存在しない → 全プラグイン有効
+- プラグインの設定がない → 有効とみなす
+- `enabled: false`が明示的に設定されている → 無効
+
+### プラグインの配布方法
+
+#### GitHub Gistで共有
+
+```bash
+# プラグイン作者
+1. GitHub Gistに.rbファイルをアップロード
+2. Raw URLをユーザーに共有
+
+# ユーザー
+$ mkdir -p ~/.rufio/plugins
+$ curl -o ~/.rufio/plugins/my_plugin.rb [RAW_URL]
+$ rufio
+✓ my_plugin 読み込み完了
+```
+
+#### GitHubリポジトリで共有
+
+```bash
+# プラグイン作者
+rufio-plugins/
+  ├── plugin1.rb
+  └── plugin2.rb
+
+# ユーザー
+$ curl -o ~/.rufio/plugins/plugin1.rb https://raw.githubusercontent.com/user/rufio-plugins/main/plugin1.rb
+```
+
+### プラグインの主要機能
+
+#### 必須メソッド
+
+- `name`: プラグイン名（必須）
+- `description`: プラグインの説明（オプション、デフォルト: ""）
+- `version`: プラグインのバージョン（オプション、デフォルト: "1.0.0"）
+- `commands`: コマンド定義（オプション、デフォルト: {}）
+
+#### 依存gem管理
+
+- `requires 'gem_name'`: 依存gemを宣言
+- 依存gemが不足している場合、警告を表示してプラグインを無効化
+- rufio本体は正常に起動継続
+
+#### 自動登録機能
+
+- `Plugin`クラスを継承すると自動的に`PluginManager`に登録
+- 複雑な登録処理は不要
+
+## 開発
+
+### 必要な環境
+
+- Ruby 2.7.0以上
+- io-console, pastel, tty-cursor, tty-screen gems
+
+### 開発版の実行
+
+```bash
+git clone https://github.com/masisz/rufio
+cd rufio
+bundle install
+./exe/rufio
+```
+
+### テスト実行
+
+```bash
+bundle exec rake test
+```
+
+## 対応プラットフォーム
+
+- **macOS**: ネイティブサポート
+- **Linux**: ネイティブサポート
+- **Windows**: 基本機能をサポート
+
+## ライセンス
+
+MIT License
+
+## 貢献
+
+バグ報告や機能リクエストは[GitHub Issues](https://github.com/masisz/rufio/issues)でお願いします。
+
+プルリクエストも歓迎です！
+
+### 開発ガイドライン
+
+1. 既存のコードスタイルと規約に従う
+2. 新機能にはテストを追加する
+3. 必要に応じてドキュメントを更新する
+4. 可能であれば複数のプラットフォームでテストする