rufio 1.0.2 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6a5acef1da176c0bfb0c96f4dacc64e6ab519095b9e282a0c2558ca2594cd34
-  data.tar.gz: 5be4e0fe22abcd6d866842ab61436605e940d38d5c3b43f477fc3afea0323413
+  metadata.gz: 431baab2112b7382ee6b9aeb19a17f7cbc0133adc8d76e349ac614827908234b
+  data.tar.gz: ffe6479dc44a44869dbd56a67af086cfda84164cacb6b3b8334e0d691f24a706
 SHA512:
-  metadata.gz: 40f7a8c8dc30211dd09ec1c047c2ca52f4f9854020e41e6a56d56d531f84e87dbf920c7f01df213d9d67c4085edf634e7e6b2c924b0b3a8fcb2da3ab56765d54
-  data.tar.gz: bc5b4458b71cdd85287f141ea8c8fff2cc66a6ba6a972cca558f1bf6bbd81c6a74a0e46fd1acaf413f2771e4170752fab4bb10838c45791d40c61e76c43c0f89
+  metadata.gz: 92038826f2b9ba53ba7c2e329c835ba92f99e9678151805faadbdc23f32f7fe6b4bcb4cb8394855ef1ddb01a96ce1abc4ee12ffbf0f1b71672b2148ba7692daa
+  data.tar.gz: e7dfbeba635500c59b6fbd2c3b17efdd4b17c24c6bcac9af7d95bb6ebc7ef38b59ce55be6206dd42ceb49b2531728a21cd8c1876a44189371be6f3621ac7c2fc

data/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to rufio will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.4] - 2026-10-25
+
+### Changed
+- Replace directory-based Help with a floating menu containing Controls, Modes, and Scripts sections. Switch sections with 1/2/3 or Tab, scroll with j/k, and close with ESC while preserving the current mode, directory, and preview focus
+- Show mode shortcuts as `[L] Logs`, `[J] Jobs`, and `[?] Help` in the bottom bar
+
+### Fixed
+- Show `ESC: Back to files` below the file name in Preview mode
+- Preserve the original return directory when entering Logs repeatedly and prevent overlapping Help and Logs states
+- Keep mouse interactions inside the floating Help window from affecting the underlying file list
+
+## [1.0.3] - 2026-10-23
+
+### Security
+- **Fix shell command injection via file names**: `FileOpener` interpolated file paths into shell strings and only quoted them when they contained spaces or quotes, so opening a file named like `a;touch pwned` or containing `$(...)` / backticks could execute arbitrary commands. Commands are now executed in array form without a shell (`system(*argv)`), paths starting with `-` are prefixed with `./`, and the Windows default-app launch uses `rundll32 url.dll,FileProtocolHandler` instead of `cmd /c start` (avoids `%VAR%` / `&` expansion). Removed `quote_shell_argument`
+- **rga option injection**: A `--` separator is now passed before the search query so queries such as `--pre=cmd` are not interpreted as rga options
+- **Command logs are now written with `0600` permissions**, since command output may contain secrets
+
+### Removed
+- `TestUISnapshot` and its `test/snapshots/` fixtures (tests were failing independent of code changes)
+
+### Fixed
+- **Windows: Sluggish key handling**: The main loop processed only one input byte per frame and then slept ~33ms, so key repeat could not keep up. Now up to 32 queued inputs are processed per frame with a single redraw, and the Windows frame interval is ~8ms
+- **Windows: Input queue wait**: Uses `Queue#pop(timeout:)` on Ruby 3.2+ instead of 1ms `sleep` polling (inaccurate under the ~15ms Windows timer resolution)
+- **Windows: Arrow keys misread as ESC**: The wait for escape sequence follow-up bytes was extended from 5ms to 25ms to tolerate ConPTY byte delays
+
 ## [1.0.0] - 2026-04-28
 
 ### Added

data/README.md

@@ -2,34 +2,26 @@
 
 **Runtime Unified Flow I/O Operator**
 
-A TUI file manager that executes and coordinates tools and scripts from files.
-Supports Ruby/Python/PowerShell and integrates your development workflow in one place.
+A terminal file manager that keeps your everyday script workflow close at hand.
+Find files, run Ruby, Python, or PowerShell scripts in the current directory, and check jobs and logs.
+Add your own actions in Ruby.
 
 [日本語](./README_ja.md) | **English**
 
-## Concept
+## What Makes rufio Different
 
-rufio is not just a file manager. It's a **tool runtime execution environment**.
+rufio brings finding files, running scripts, and checking results together in one interface.
 
-```
-┌─────────────────────────────────────────────────────────┐
-│                        rufio                            │
-│         Runtime Unified Flow I/O Operator               │
-├─────────────────────────────────────────────────────────┤
-│  Files ──→ Scripts ──→ Tools ──→ Output                 │
-│    ↑                                   │                │
-│    └───────────── Feedback ────────────┘                │
-└─────────────────────────────────────────────────────────┘
-```
-
-- **File Operations**: Traditional file manager functionality
-- **Script Execution**: Run Ruby/Python/PowerShell scripts in file context
-- **Tool Integration**: Seamless integration with external tools (git, fzf, rga, etc.)
-- **Unified I/O**: Manage all input/output in a single flow
+- **Run scripts where your files are**: Register your script directories, then press `:`, type `@` + part of a script name, press `Tab`, and hit `Enter`. Run Ruby, Python, or PowerShell scripts in the directory you are browsing
+- **Follow jobs and execution logs**: Keep browsing while scripts run in the background. Press `J` to check jobs and `L` to view execution logs
+- **Add your own actions in Ruby**: Define custom commands with a small Ruby DSL in `~/.config/rufio/commands.rb`. `~/.rufio/commands.rb` is also supported
+- **Use installed tools without extra configuration**: Search file names with fzf, search contents with rga, highlight previews with bat, and navigate directory history with zoxide
+- **Windows support**: Run PowerShell scripts with keyboard input handling adapted to Windows terminals
+- **Trace behavior in the source**: The implementation is primarily Ruby, so you can inspect and change the parts you need. Security design is documented in [SECURITY.md](./SECURITY.md)
 
 ## Features
 
-### As a Tool Runtime
+### For Script Workflows
 
 - **Multi-language Script Support**: Ruby, Python, PowerShell
 - **Script Path Management**: Register and manage multiple script directories

data/README_ja.md

@@ -2,36 +2,26 @@
 
 **Runtime Unified Flow I/O Operator**
 
-ファイルを起点に、ツールとスクリプトを実行・連携させるTUIファイルマネージャー。
-Ruby/Python/PowerShellに対応し、開発ワークフローを一箇所に統合します。
-
-A TUI file manager as a unified runtime environment for tools and scripts.
+日々のスクリプト作業を手元にまとめるターミナルファイラ。
+ファイルを探し、その場所で Ruby・Python・PowerShell を実行し、ジョブとログを確認できます。
+自分用の操作は Ruby で追加できます。
 
 **日本語** | [English](./README.md)
 
-## コンセプト
-
-rufioは単なるファイルマネージャーではありません。**ツールランタイム実行環境**です。
+## rufioならではの点
 
-```
-┌─────────────────────────────────────────────────────────┐
-│                        rufio                            │
-│         Runtime Unified Flow I/O Operator               │
-├─────────────────────────────────────────────────────────┤
-│  Files ──→ Scripts ──→ Tools ──→ Output                 │
-│    ↑                                   │                │
-│    └───────────── Feedback ────────────┘                │
-└─────────────────────────────────────────────────────────┘
-```
+rufio は、ファイルを探すところからスクリプトの実行、結果の確認までを一つの画面にまとめます。
 
-- **ファイル操作**: 従来のファイルマネージャー機能
-- **スクリプト実行**: Ruby/Python/PowerShellスクリプトをファイルコンテキストで実行
-- **ツール連携**: 外部ツール（git, fzf, rga等）とのシームレスな統合
-- **統一I/O**: すべての入出力を単一のフローで管理
+- **ファイルのある場所からスクリプトを実行**: スクリプトのディレクトリを登録し、`:` → `@` + スクリプト名の一部 → `Tab` → `Enter` で呼び出せます。Ruby・Python・PowerShell を、いま開いているディレクトリで実行できます
+- **ジョブとログで実行結果を追える**: バックグラウンドで実行しながらファイル操作を続け、`J` でジョブ、`L` で実行ログを確認できます
+- **自分用の操作を Ruby で追加**: `~/.config/rufio/commands.rb` に小さな Ruby DSL で独自コマンドを定義できます。`~/.rufio/commands.rb` にも対応しています
+- **インストール済みのツールと追加設定なしで連携**: fzf でファイル名検索、rga で内容検索、bat でプレビューのシンタックスハイライト、zoxide でディレクトリ履歴から移動できます
+- **Windows にも対応**: PowerShell スクリプトの実行に対応し、Windows のターミナルに合わせたキー入力処理を備えています
+- **挙動をソースで追いやすい**: Ruby を中心とした実装で、必要な処理を自分で確認・修正できます。セキュリティに関する設計は [SECURITY.md](./SECURITY.md) にまとめています
 
 ## 特徴
 
-### ツールランタイムとして
+### スクリプト作業のために
 
 - **マルチ言語スクリプト対応**: Ruby, Python, PowerShell
 - **スクリプトパス管理**: 複数のスクリプトディレクトリを登録・管理

data/SECURITY.md

@@ -0,0 +1,95 @@
+# Security Policy / セキュリティポリシー
+
+[English](#english) | [日本語](#日本語)
+
+## English
+
+### Supported versions
+
+Only the latest released version receives security fixes. Please upgrade with `gem update rufio` before reporting.
+
+### Reporting a vulnerability
+
+Please **do not open a public issue** for security problems.
+
+- Use GitHub's private reporting: [Security → Report a vulnerability](https://github.com/masisz/rufio/security/advisories/new)
+- Or email masisz.1567@gmail.com
+
+Include the rufio version, OS, steps to reproduce, and the impact you expect. This is a personal project, so responses are best-effort, but reports are taken seriously and fixes are noted in [CHANGELOG.md](./CHANGELOG.md) under `Security`.
+
+### Threat model
+
+rufio is a local TUI tool run by you, on files you can already access.
+
+**In scope** (treated as vulnerabilities):
+- Names or contents of files, directories, archives, or tool output causing unintended command execution (e.g. shell metacharacters in file names)
+- Escape sequences in file contents or names that manipulate the terminal in harmful ways
+- Unsafe handling of paths that lets an operation affect files outside what the user selected
+- Secrets exposed through logs or temporary files
+
+**Out of scope** (by design):
+- Commands you type yourself in command mode (`:`, `!`) — they are executed as shell commands
+- Code in your own configuration: `~/.rufio/commands.rb` and `~/.config/rufio/commands.rb` are **evaluated as Ruby**. Keep them writable only by you
+- Scripts you register under script paths — they run with your privileges
+- Vulnerabilities in external tools (fzf, rga, bat, zoxide, editors)
+
+### Design practices
+
+- Files and scripts are launched in array form (`system(*argv)`), never through a shell string; paths beginning with `-` are prefixed with `./`
+- Search queries are passed to rga after `--`
+- YAML is loaded with `YAML.safe_load`
+- Command execution logs are written with `0600` permissions
+- Runtime dependencies are limited to `io-console`, `pastel`, `tty-cursor`, `tty-screen`
+- Gems are published from tagged commits via RubyGems Trusted Publishing (no long-lived API key); CI runs the test suite before publishing
+
+### Known limitations
+
+- Text previews only detect binary files (by control-character ratio); terminal escape sequences inside otherwise-textual files are not explicitly stripped. Avoid previewing untrusted files in a terminal you do not trust
+- The optional native extension under `lib_zig` is not shipped in the gem and has not been independently audited
+
+---
+
+## 日本語
+
+### サポート対象バージョン
+
+セキュリティ修正は最新のリリースにのみ行います。報告の前に `gem update rufio` で更新してください。
+
+### 脆弱性の報告
+
+セキュリティ上の問題は**公開Issueに書かない**でください。
+
+- GitHubの非公開報告: [Security → Report a vulnerability](https://github.com/masisz/rufio/security/advisories/new)
+- またはメール: masisz.1567@gmail.com
+
+rufioのバージョン、OS、再現手順、想定される影響を添えてください。個人プロジェクトのため対応はベストエフォートですが、報告は真剣に扱い、修正は [CHANGELOG.md](./CHANGELOG.md) の `Security` に記載します。
+
+### 脅威モデル
+
+rufioは、あなた自身がアクセスできるファイルに対して、ローカルで実行するTUIツールです。
+
+**対象（脆弱性として扱う）**:
+- ファイル名・ディレクトリ名・アーカイブ・ツール出力の内容によって、意図しないコマンドが実行されること（例: ファイル名中のシェルメタ文字）
+- ファイル内容や名前に含まれるエスケープシーケンスによる、有害なターミナル操作
+- パスの扱いの不備により、ユーザーが選択した範囲外のファイルに操作が及ぶこと
+- ログや一時ファイルを通じた機密情報の漏えい
+
+**対象外（設計上の仕様）**:
+- コマンドモード（`:`、`!`）で自分で入力したコマンド — シェルコマンドとして実行されます
+- 自分の設定ファイル内のコード — `~/.rufio/commands.rb` と `~/.config/rufio/commands.rb` は**Rubyとして評価**されます。書き込み権限は自分だけにしてください
+- スクリプトパスに登録したスクリプト — あなたの権限で実行されます
+- 外部ツール（fzf、rga、bat、zoxide、エディタ）自体の脆弱性
+
+### 設計上の方針
+
+- ファイルやスクリプトは配列形式（`system(*argv)`）で起動し、シェル文字列を介しません。`-` で始まるパスには `./` を付与します
+- rga には `--` を挟んで検索語を渡します
+- YAML は `YAML.safe_load` で読み込みます
+- コマンド実行ログは `0600` で保存します
+- 実行時依存gemは `io-console`、`pastel`、`tty-cursor`、`tty-screen` のみです
+- gemはタグ付きコミットからRubyGemsのTrusted Publishingで公開します（長期APIキーなし）。公開前にCIでテストを実行します
+
+### 既知の制約
+
+- テキストのプレビューはバイナリ判定（制御文字の比率）のみで、テキストとして扱われるファイル内のエスケープシーケンスは明示的に除去していません。信頼できないファイルを、信頼できないターミナルでプレビューするのは避けてください
+- `lib_zig` のネイティブ拡張（任意機能）はgemに同梱しておらず、第三者による監査も受けていません

data/lib/rufio/command_logger.rb

@@ -30,7 +30,8 @@ module Rufio
       # ディレクトリが存在しない場合は作成（バックグラウンドスレッドでの実行時の競合を防ぐ）
       FileUtils.mkdir_p(@log_dir) unless Dir.exist?(@log_dir)
 
-      File.write(filepath, content)
+      # コマンド出力に機密情報が含まれ得るため、所有者のみ読み書き可能にする
+      File.write(filepath, content, perm: 0o600)
     end
 
     # ログファイル一覧を取得（新しい順）

data/lib/rufio/file_opener.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'shellwords'
+
 module Rufio
   class FileOpener
     def initialize
@@ -43,26 +45,26 @@ module Rufio
     end
 
     def execute_command(application, file_path)
-      quoted_path = quote_shell_argument(file_path)
+      path = safe_path(file_path)
 
       case RbConfig::CONFIG['host_os']
       when /mswin|mingw|cygwin/
-        # Windows
-        system("start \"\" \"#{file_path}\"")
+        # Windows: cmd.exe を経由せず（%VAR% や & の展開を避ける）既定アプリで開く
+        run_command(['rundll32', 'url.dll,FileProtocolHandler', path])
       when /darwin/
         # macOS
         if application == 'open'
-          system("open #{quoted_path}")
+          run_command(['open', path])
         else
           # VSCodeなど特定のアプリケーション
-          system("#{application} #{quoted_path}")
+          run_command([*application_argv(application), path])
         end
       else
         # Linux/Unix
         if application == 'open'
-          system("xdg-open #{quoted_path}")
+          run_command(['xdg-open', path])
         else
-          system("#{application} #{quoted_path}")
+          run_command([*application_argv(application), path])
         end
       end
     rescue StandardError => e
@@ -71,37 +73,39 @@ module Rufio
     end
 
     def execute_command_with_line(application, file_path, line_number)
-      quoted_path = quote_shell_argument(file_path)
+      path = safe_path(file_path)
+      line = line_number.to_i
+      app = application_argv(application)
 
       case RbConfig::CONFIG['host_os']
       when /mswin|mingw|cygwin/
         # Windows
         if application.include?('code')
-          system("#{application} --goto #{quoted_path}:#{line_number}")
+          run_command([*app, '--goto', "#{path}:#{line}"])
         else
-          system("start \"\" \"#{file_path}\"")
+          run_command(['rundll32', 'url.dll,FileProtocolHandler', path])
         end
       when /darwin/
         # macOS
         if application == 'open'
-          system("open #{quoted_path}")
+          run_command(['open', path])
         elsif application.include?('code')
-          system("#{application} --goto #{quoted_path}:#{line_number}")
+          run_command([*app, '--goto', "#{path}:#{line}"])
         elsif application.include?('vim') || application.include?('nvim')
-          system("#{application} +#{line_number} #{quoted_path}")
+          run_command([*app, "+#{line}", path])
         else
-          system("#{application} #{quoted_path}")
+          run_command([*app, path])
         end
       else
         # Linux/Unix
         if application == 'open'
-          system("xdg-open #{quoted_path}")
+          run_command(['xdg-open', path])
         elsif application.include?('code')
-          system("#{application} --goto #{quoted_path}:#{line_number}")
+          run_command([*app, '--goto', "#{path}:#{line}"])
         elsif application.include?('vim') || application.include?('nvim')
-          system("#{application} +#{line_number} #{quoted_path}")
+          run_command([*app, "+#{line}", path])
         else
-          system("#{application} #{quoted_path}")
+          run_command([*app, path])
         end
       end
     rescue StandardError => e
@@ -109,27 +113,39 @@ module Rufio
       false
     end
 
-    def quote_shell_argument(argument)
-      if argument.include?(' ') || argument.include?("'") || argument.include?('"')
-        '"' + argument.gsub('"', '\"') + '"'
+    # シェルを介さず配列形式で実行する（ファイル名経由のコマンドインジェクション防止）
+    def run_command(argv)
+      system(*argv)
+    end
+
+    # 設定のアプリケーション指定（例: "code -r"）を引数配列に分解する
+    def application_argv(application)
+      if RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/
+        # Windows のパスはバックスラッシュを含むため POSIX 分割は使わない
+        File.exist?(application) ? [application] : application.split
       else
-        argument
+        Shellwords.split(application)
       end
     end
 
+    # '-' で始まるパスがオプションとして解釈されないようにする
+    def safe_path(path)
+      path.start_with?('-') ? File.join('.', path) : path
+    end
+
     def execute_explorer_command(directory_path)
-      quoted_path = quote_shell_argument(directory_path)
+      path = safe_path(directory_path)
 
       case RbConfig::CONFIG['host_os']
       when /mswin|mingw|cygwin/
         # Windows
-        system("explorer #{quoted_path}")
+        run_command(['explorer', path])
       when /darwin/
         # macOS
-        system("open #{quoted_path}")
+        run_command(['open', path])
       else
         # Linux/Unix
-        system("xdg-open #{quoted_path}")
+        run_command(['xdg-open', path])
       end
     rescue StandardError => e
       warn "Failed to open directory: #{e.message}"

data/lib/rufio/help_menu.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative 'text_utils'
+require_relative 'dialog_renderer'
+require_relative 'config_loader'
+
+module Rufio
+  # メインループを止めずに表示するヘルプメニュー。
+  class HelpMenu
+    SECTIONS = %w[Controls Modes Scripts].freeze
+    attr_reader :scroll_offset
+
+    def initialize
+      @active = false
+      @section_index = 0
+      @scroll_offset = 0
+      @max_scroll = 0
+    end
+
+    def open
+      @active = true
+      @section_index = 0
+      @scroll_offset = 0
+    end
+
+    def active?
+      @active
+    end
+
+    def section
+      SECTIONS[@section_index]
+    end
+
+    def handle_key(key)
+      case key
+      when "\e", 'q', '?' then @active = false
+      when '1', '2', '3' then select_section(key.to_i - 1)
+      when "\t", 'l' then select_section((@section_index + 1) % SECTIONS.length)
+      when 'h', "\e[Z" then select_section((@section_index - 1) % SECTIONS.length)
+      when 'j' then @scroll_offset = [@scroll_offset + 1, @max_scroll].min
+      when 'k' then @scroll_offset = [@scroll_offset - 1, 0].max
+      when "\x04" then @scroll_offset = [@scroll_offset + @page_size.to_i, @max_scroll].min
+      when "\x15" then @scroll_offset = [@scroll_offset - @page_size.to_i, 0].max
+      when 'g' then @scroll_offset = 0
+      when 'G' then @scroll_offset = @max_scroll
+      end
+      true
+    end
+
+    def content
+      case section
+      when 'Controls'
+        [
+          'Navigation',
+          "#{key(:move_down)}/#{key(:move_up)} or arrows: Move down/up",
+          "#{key(:navigate_parent)}/#{key(:navigate_enter)}: Parent / enter directory",
+          'Enter: Open file preview | ESC: Back to file list',
+          'Preview: j/k scroll, Ctrl+D/U page down/up',
+          "#{key(:top)}/#{key(:bottom)}: First / last entry",
+          "#{key(:open_file)}: Open in external editor",
+          "#{key(:refresh)}: Refresh directory",
+          '', 'Selection and file operations',
+          "#{key(:select)}: Select / unselect file",
+          "#{key(:copy_selected)}/#{key(:move_selected)}/#{key(:delete_selected)}: Copy / move / delete selected files",
+          "#{key(:rename)}/#{key(:delete)}: Rename / delete current file",
+          "#{key(:create_file)}/#{key(:create_dir)}: Create file / directory",
+          '', 'Search and bookmarks',
+          "#{key(:filter)}: Filter | Enter: Apply | ESC: Clear",
+          "#{key(:fzf_search)}: Filename search (fzf)",
+          "#{key(:rga_search)}: Content search (rga)",
+          "#{key(:add_bookmark)}/#{key(:bookmark_menu)}: Add / manage bookmarks",
+          'Tab / Shift+Tab: Next / previous bookmark',
+          "1-9: Jump to bookmark | #{key(:start_dir)}: Start directory",
+          "#{key(:zoxide)}: Directory history (zoxide)",
+          "#{key(:quit)}: Quit (with confirmation)"
+        ]
+      when 'Modes'
+        [
+          'Files', 'Browse directories, select files and view previews.',
+          '', "[#{key(:log_viewer)}] Logs",
+          'Browse command logs. Enter opens a preview.',
+          'ESC: Leave preview; ESC again: Return to Files.',
+          '', "[#{key(:job_mode)}] Jobs",
+          'View background commands and their status.',
+          'Space: View log | x: Cancel job | ESC: Back',
+          '', "[#{key(:help)}] Help",
+          'This floating menu keeps your current mode and directory.',
+          '1/2/3 or Tab: Select section | ESC: Close',
+          '', "[#{key(:command_mode)}] Command",
+          'Type a command, then Enter to run it.',
+          'Tab: Complete | Up/Down: History | ESC: Cancel',
+          ':!git status: Run a shell command',
+          ':@hello.rb: Run a script in the current directory'
+        ]
+      when 'Scripts'
+        [
+          '1. Personal scripts',
+          'Place scripts in ~/.config/rufio/scripts/',
+          'Example: ~/.config/rufio/scripts/hello.rb',
+          'Press : and type hello, then Enter (:hello).',
+          '', '2. Additional script folders',
+          'List folders in ~/.config/rufio/script_paths.yml:',
+          '- ~/.config/rufio/scripts', '- ~/my-scripts',
+          'Folders are searched in order. First matching name wins.',
+          '', '3. Project scripts',
+          'Place hello.rb or hello.sh in the directory you browse.',
+          'Run it with :@hello.rb or :@hello.sh.',
+          'Project search paths: ./rufio.yml, script_paths list.',
+          '', '4. Run and monitor',
+          'Tab completes script names. Up/Down recalls commands.',
+          "#{key(:job_mode)}: Background jobs | #{key(:log_viewer)}: Execution logs",
+          'Supported: Ruby, shell, Python and other script types.'
+        ]
+      end
+    end
+
+    def draw(screen)
+      width = [screen.width, 78].min
+      height = [screen.height, 26].min
+      return if width < 8 || height < 8
+
+      @page_size = height - 7
+      lines = content.flat_map { |line| line.empty? ? [''] : TextUtils.wrap_preview_lines([line], width - 4) }
+      @max_scroll = [lines.length - @page_size, 0].max
+      @scroll_offset = [@scroll_offset, @max_scroll].min
+      tabs = SECTIONS.each_with_index.map do |name, index|
+        index == @section_index ? "[#{index + 1}:#{name}]" : " #{index + 1}:#{name} "
+      end.join(' ')
+      visible = [TextUtils.truncate_to_width(tabs, width - 2), '']
+      visible.concat(lines.slice(@scroll_offset, @page_size) || [])
+      visible << '' while visible.length < height - 5
+      visible << TextUtils.truncate_to_width('ESC: Close | Tab: Menu | j/k: Scroll', width - 2)
+      screen.enable_overlay
+      screen.clear_overlay
+      title = "Help - #{section} (#{@scroll_offset + 1}/#{@max_scroll + 1})"
+      DialogRenderer.new.draw_floating_window_to_overlay(
+        screen, (screen.width - width) / 2, (screen.height - height) / 2,
+        width, height, TextUtils.truncate_to_width(title, width - 2), visible,
+        border_color: "\e[36m", title_color: "\e[1;36m"
+      )
+    end
+
+    private
+
+    def select_section(index)
+      @section_index = index
+      @scroll_offset = 0
+    end
+
+    def key(action)
+      value = ConfigLoader.keybinds[action]
+      value == ' ' ? 'Space' : value.to_s
+    end
+  end
+end

data/lib/rufio/keybind_handler.rb

@@ -130,6 +130,10 @@ module Rufio
     def handle_key(key)
       return false unless @directory_listing
 
+      if @key_map[key] == :help && !@filter_manager.filter_mode
+        return show_help_dialog
+      end
+
       # ジョブモード中の特別処理
       if @job_mode.active?
         return handle_job_mode_key(key)
@@ -217,6 +221,9 @@ module Rufio
     # ヘルプモードに入る
     def enter_help_mode
       return false unless @directory_listing
+      return true if @in_help_mode
+
+      exit_log_viewer_mode if @in_log_viewer_mode
 
       # 現在のディレクトリを保存
       @pre_help_directory = @directory_listing.current_path
@@ -264,6 +271,9 @@ module Rufio
     # ログビューワモードに入る
     def enter_log_viewer_mode
       return false unless @directory_listing
+      return true if @in_log_viewer_mode
+
+      exit_help_mode if @in_help_mode
 
       # 現在のディレクトリを保存
       @pre_log_viewer_directory = @directory_listing.current_path
@@ -488,7 +498,7 @@ module Rufio
       when :zoxide          then show_zoxide_menu
       when :start_dir       then goto_start_directory
       when :job_mode        then enter_job_mode
-      when :help            then enter_help_mode
+      when :help            then show_help_dialog
       when :log_viewer      then enter_log_viewer_mode
       when :command_mode    then activate_command_mode
       when :quit            then exit_request

data/lib/rufio/search_controller.rb

@@ -57,7 +57,8 @@ module Rufio
       search_results = nil
       Dir.chdir(current_path) do
         escaped_query = Shellwords.escape(search_query)
-        search_results = `rga --line-number --with-filename #{escaped_query} . 2>/dev/null`
+        # "--" で検索語がオプション（--pre=コマンド 等）として解釈されるのを防ぐ
+        search_results = `rga --line-number --with-filename -- #{escaped_query} . 2>/dev/null`
       end
 
       if search_results.empty?

data/lib/rufio/terminal_ui.rb

@@ -2,6 +2,7 @@
 
 require 'io/console'
 require_relative 'text_utils'
+require_relative 'help_menu'
 
 module Rufio
   class TerminalUI
@@ -51,6 +52,7 @@ module Rufio
       @input_queue = nil
       @input_thread = nil
       @command_mode_active = false
+      @help_menu = HelpMenu.new
       @command_input = ""
       @command_mode = CommandMode.new
       @dialog_renderer = DialogRenderer.new
@@ -237,7 +239,8 @@ module Rufio
     # Windows: IO.select を使わずキューから取得（5ms タイムアウト）。
     def read_next_input_byte
       if windows?
-        b = windows_queue_pop_with_timeout(0.005)
+        # ConPTY ではバイト到着が遅れることがあるため 5ms では ESC 単体と誤判定する
+        b = windows_queue_pop_with_timeout(0.025)
         b.nil? ? nil : b.chr(Encoding::BINARY)
       else
         STDIN.read_nonblock(1) rescue nil
@@ -280,7 +283,15 @@ module Rufio
     end
 
     # Windows 専用: @input_queue からタイムアウト付きで Integer バイトを取り出す。
+    # Ruby 3.2+ は Queue#pop(timeout:) で正確に待機する（sleep ポーリングは
+    # Windows のタイマー分解能 約15ms により遅延する）。それ以前はポーリング。
+    QUEUE_POP_TIMEOUT_SUPPORTED = Queue.instance_method(:pop).parameters.any? { |_, n| n == :timeout }
+
     def windows_queue_pop_with_timeout(timeout_sec)
+      if QUEUE_POP_TIMEOUT_SUPPORTED
+        return @input_queue.pop(timeout: timeout_sec)
+      end
+
       deadline = Time.now + timeout_sec
       loop do
         begin
@@ -344,10 +355,13 @@ module Rufio
     # ゲームループパターンのmain_loop（CPU最適化版：フレームスキップ対応）
     # UPDATE → DRAW → RENDER → SLEEP のサイクル
     # 変更がない場合は描画をスキップしてCPU使用率を削減
+    MAX_INPUTS_PER_FRAME = 32
+
     def main_loop
       # CPU最適化: 固定FPSをやめて、イベントドリブンに変更
       # 最小スリープ時間（入力チェック間隔）
-      min_sleep_interval = 0.0333  # 30FPS（約33.33ms/フレーム）
+      # Windows は入力をキュー経由で受けるため、入力遅延を抑えるよう短めにする
+      min_sleep_interval = windows? ? 0.008 : 0.0333  # Windows: 約8ms / Unix: 30FPS
       check_interval = 0.1  # バックグラウンドタスクのチェック間隔
 
       # Phase 3: Screen/Rendererを初期化
@@ -402,7 +416,14 @@ module Rufio
 
         # UPDATE phase - ノンブロッキング入力処理
         # 入力があった場合は再描画が必要
-        had_input = handle_input_nonblocking
+        # 1フレームで溜まった入力をまとめて処理し、再描画は1回だけにする
+        # （1フレーム1キーだとキーリピートに追いつけず操作がもたつく）
+        had_input = false
+        MAX_INPUTS_PER_FRAME.times do
+          break unless handle_input_nonblocking
+          had_input = true
+          break unless @running
+        end
         needs_redraw = true if had_input
 
         # バックグラウンドコマンドの完了チェック（0.1秒ごと）
@@ -475,8 +496,10 @@ module Rufio
             draw_screen_to_buffer(@screen, nil, current_fps)
           end
 
-          # コマンドモードがアクティブな場合はオーバーレイにダイアログを描画
-          if @command_mode_active
+          # ヘルプまたはコマンドモードのダイアログをオーバーレイに描画
+          if help_dialog_active?
+            @help_menu.draw(@screen)
+          elsif @command_mode_active
             # 前回のオーバーレイ残留を防ぐためクリアしてから描画
             @screen.clear_overlay if @screen.overlay_enabled?
             draw_command_mode_to_overlay
@@ -579,7 +602,13 @@ module Rufio
           when 'B' then 'j'  # Down arrow
           when 'C' then 'l'  # Right arrow
           when 'D' then 'h'  # Left arrow
-          when 'Z' then handle_shift_tab; return true  # Shift+Tab
+          when 'Z'
+            if help_dialog_active?
+              handle_help_input("\e[Z")
+            else
+              handle_shift_tab
+            end
+            return true  # Shift+Tab
           else
             # 未知の CSI シーケンス（\e[27;1u 等）: 残りバイトを読み捨てて
             # パイプを汚染しないようにする
@@ -591,6 +620,8 @@ module Rufio
         end
       end
 
+      return handle_help_input(input) if help_dialog_active?
+
       # TabキーはFilesモードの時のみブックマーク循環移動（ジョブモード中は無効）
       if input == "\t" && @tab_mode_manager.current_mode == :files && !@in_job_mode
         handle_tab_key
@@ -673,6 +704,12 @@ module Rufio
     # @param row [Integer]  クリック行（1-indexed）
     # @param press [Boolean] true=押下, false=解放
     def handle_mouse_event(btn, col, row, press)
+      if help_dialog_active?
+        handle_help_input('k') if btn == 64
+        handle_help_input('j') if btn == 65
+        return
+      end
+
       case btn
       when 0  # 左クリック（押下のみ処理）
         handle_mouse_left_click(col, row) if press
@@ -765,12 +802,7 @@ module Rufio
           @keybind_handler.send(:exit_job_mode)
         end
       when :help
-        # ヘルプモードに入る
-        unless @keybind_handler.help_mode?
-          @keybind_handler.send(:exit_log_viewer_mode) if @keybind_handler.log_viewer_mode?
-          @keybind_handler.send(:exit_job_mode) if @keybind_handler.in_job_mode?
-          @keybind_handler.send(:enter_help_mode)
-        end
+        show_help_dialog
       when :logs
         # ログビューワモードに入る
         unless @keybind_handler.log_viewer_mode?
@@ -1172,61 +1204,19 @@ module Rufio
     # Screen と Renderer のアクセサ（他のクラスから利用可能に）
     attr_reader :screen, :renderer
 
-    # ヘルプダイアログを表示
+    # ヘルプは非同期オーバーレイとして表示し、元のモードを保持する。
     def show_help_dialog
-      content_lines = [
-        '',
-        "rufio v#{VERSION}",
-        '',
-        'Key Bindings:',
-        '',
-        'j/k      - Move up/down',
-        'h/l      - Navigate back/enter',
-        'g/G      - Go to top/bottom',
-        'o        - Open file',
-        'f        - Filter files',
-        's        - Search with fzf',
-        'F        - Content search (rga)',
-        'a/A      - Create file/directory',
-        'm/c/x    - Move/Copy/Delete',
-        'b        - Add bookmark',
-        'z        - Zoxide navigation',
-        '0        - Go to start directory',
-        '1-9      - Go to bookmark',
-        'J        - Job mode',
-        ':        - Command mode',
-        'q        - Quit',
-        ''
-      ]
-
-      # お知らせ情報を追加
-      require_relative 'info_notice'
-      info_notice = InfoNotice.new
-      all_notices = Dir.glob(File.join(info_notice.info_dir, '*.txt'))
-
-      if !all_notices.empty?
-        content_lines << 'Recent Updates:'
-        content_lines << ''
-        all_notices.take(3).each do |file|
-          title = info_notice.extract_title(file)
-          content_lines << "  • #{title}"
-        end
-        content_lines << ''
-      end
-
-      content_lines << 'Press any key to continue...'
+      @help_menu.open
+      true
+    end
 
-      width = 60
-      height = [content_lines.length + 4, @screen_height - 4].min
+    def help_dialog_active?
+      @help_menu.active?
+    end
 
-      # オーバーレイダイアログを表示
-      show_overlay_dialog('rufio - Help', content_lines, {
-        width: width,
-        height: height,
-        border_color: "\e[36m",    # Cyan
-        title_color: "\e[1;36m",   # Bold cyan
-        content_color: "\e[37m"    # White
-      })
+    def handle_help_input(input)
+      @help_menu.handle_key(input)
+      true
     end
 
     # 未知の CSI シーケンス（\e[X...）の残りバイトを終端アルファベットまで読み捨てる。

data/lib/rufio/ui_renderer.rb

@@ -401,6 +401,10 @@ module Rufio
           header += ' ' * remaining_space if remaining_space > 0
           screen.put_string(content_x, line_num, header)
 
+        elsif i == 1 && @keybind_handler&.preview_focused?
+          hint = TextUtils.truncate_to_width(' ESC: Back to files', safe_width)
+          screen.put_string(content_x, line_num, hint + ' ' * (safe_width - TextUtils.display_width(hint)))
+
         elsif i >= 2 && highlighted_wrapped_lines
           # シンタックスハイライト付きコンテンツ
           scroll_offset = @keybind_handler&.preview_scroll_offset || 0
@@ -583,7 +587,7 @@ module Rufio
 
       modes.each_with_index do |mode, index|
         key = keys[mode]
-        label = key ? " #{key}:#{labels[mode]} " : " #{labels[mode]} "
+        label = key ? " [#{key}] #{labels[mode]} " : " #{labels[mode]} "
 
         if mode == current_mode
           label.each_char do |char|

data/lib/rufio/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rufio
-  VERSION = '1.0.2'
+  VERSION = '1.0.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rufio
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.4
 platform: ruby
 authors:
 - masisz
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-12 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: io-console
@@ -121,6 +121,7 @@ files:
 - README.md
 - README_ja.md
 - Rakefile
+- SECURITY.md
 - bin/rufio
 - docs/CHANGELOG_v0.10.0.md
 - docs/CHANGELOG_v0.20.0.md
@@ -175,6 +176,7 @@ files:
 - lib/rufio/file_preview.rb
 - lib/rufio/filter_manager.rb
 - lib/rufio/health_checker.rb
+- lib/rufio/help_menu.rb
 - lib/rufio/info_notice.rb
 - lib/rufio/interpreter_resolver.rb
 - lib/rufio/job_manager.rb