octo-agent 0.11.2

data/lib/octo/utils/browser_detector.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Octo
+  module Utils
+    # Detects a running browser (Chrome/Edge) that has remote debugging enabled.
+    #
+    # Detection strategy:
+    #
+    #   1. Scan known UserData directories for DevToolsActivePort file.
+    #      This file contains the exact port + WS path — most reliable.
+    #      Returns { mode: :ws_endpoint, value: "ws://127.0.0.1:PORT/PATH" }
+    #
+    #   2. Verify the port is actually reachable via TCP probe.
+    #
+    #   3. Nothing found or port unreachable → returns nil (browser not running).
+    #
+    # Supported environments: WSL, Linux, macOS.
+    module BrowserDetector
+
+      # Detect a running debuggable browser.
+      # Scans for DevToolsActivePort file across all platforms (macOS/Linux/WSL).
+      # Returns the detected WebSocket endpoint only if the port is reachable.
+      # @return [Hash] { mode: :ws_endpoint, value: String, status: :ok|:not_found }
+      def self.detect
+        os = EnvironmentDetector.os_type
+        Octo::Logger.debug("[BrowserDetector] Starting browser detection (OS: #{os})...")
+        
+        detected = detect_via_active_port_file
+        
+        unless detected
+          Octo::Logger.warn("[BrowserDetector] ✗ No reachable browser found")
+          return { status: :not_found }
+        end
+        
+        Octo::Logger.info("[BrowserDetector] ✓ Browser detected and reachable: #{detected[:mode]} → #{detected[:value]}")
+        detected.merge(status: :ok)
+      end
+
+      # -----------------------------------------------------------------------
+      # DevToolsActivePort file scan
+      # -----------------------------------------------------------------------
+
+      # @return [Hash, nil]
+      def self.detect_via_active_port_file
+        Octo::Logger.debug("[BrowserDetector] Scanning UserData directories for DevToolsActivePort...")
+        
+        dirs = user_data_dirs
+        Octo::Logger.debug("[BrowserDetector] Candidate directories: #{dirs.size} found")
+        
+        dirs.each do |dir|
+          port_file = File.join(dir, "DevToolsActivePort")
+          next unless File.exist?(port_file)
+
+          Octo::Logger.debug("[BrowserDetector] Found DevToolsActivePort: #{port_file}")
+          
+          ws = parse_active_port_file(port_file)
+          unless ws
+            Octo::Logger.debug("[BrowserDetector] ✗ Failed to parse #{port_file}")
+            next
+          end
+          
+          Octo::Logger.debug("[BrowserDetector] Parsed WS endpoint: #{ws}")
+          
+          # ⭐️ Verify port BEFORE returning — skip stale files
+          candidate = { mode: :ws_endpoint, value: ws }
+          if verify_port(candidate)
+            Octo::Logger.debug("[BrowserDetector] ✓ Port is reachable, using this endpoint")
+            return candidate
+          else
+            Octo::Logger.debug("[BrowserDetector] ✗ Port not reachable, trying next directory...")
+          end
+        end
+        
+        Octo::Logger.debug("[BrowserDetector] No reachable browser found")
+        nil
+      end
+
+      # Verify that the detected browser port is actually reachable.
+      # Extracts port from ws:// URL and attempts TCP connection.
+      # @param detected [Hash] { mode: :ws_endpoint, value: String }
+      # @return [Boolean] true if port is open and reachable
+      def self.verify_port(detected)
+        return false unless detected
+
+        port = case detected[:mode]
+        when :ws_endpoint
+          # ws://127.0.0.1:9222/devtools/...
+          detected[:value][/ws:\/\/127\.0\.0\.1:(\d+)/, 1]&.to_i
+        end
+
+        return false unless port && port > 0
+
+        reachable = tcp_open?("127.0.0.1", port)
+        Octo::Logger.debug("[BrowserDetector] Port #{port} reachable: #{reachable}")
+        reachable
+      end
+
+      # -----------------------------------------------------------------------
+      # UserData directory candidates per OS
+      # -----------------------------------------------------------------------
+
+      # Returns ordered list of candidate UserData dirs to check.
+      # @return [Array<String>]
+      def self.user_data_dirs
+        os = EnvironmentDetector.os_type
+        Octo::Logger.debug("[BrowserDetector] Detected OS: #{os}")
+        
+        case os
+        when :wsl   then wsl_user_data_dirs
+        when :linux then linux_user_data_dirs
+        when :macos then macos_user_data_dirs
+        else
+          Octo::Logger.warn("[BrowserDetector] Unknown OS type: #{os}")
+          []
+        end
+      end
+
+      # WSL: Chrome/Edge run on Windows side — resolve via LOCALAPPDATA.
+      private_class_method def self.wsl_user_data_dirs
+        appdata = Utils::Encoding.cmd_to_utf8(
+          `powershell.exe -NoProfile -Command '$env:LOCALAPPDATA' 2>/dev/null`
+        ).strip.tr("\r\n", "")
+        return [] if appdata.empty?
+
+        win_paths = [
+          "#{appdata}\\Microsoft\\Edge\\User Data",
+          "#{appdata}\\Google\\Chrome\\User Data",
+          "#{appdata}\\Google\\Chrome Beta\\User Data",
+          "#{appdata}\\Google\\Chrome SxS\\User Data",
+        ]
+
+        win_paths.filter_map do |win_path|
+          linux_path = Utils::Encoding.cmd_to_utf8(
+            `wslpath '#{win_path}' 2>/dev/null`, source_encoding: "UTF-8"
+          ).strip
+          linux_path.empty? ? nil : linux_path
+        end
+      end
+
+      # Linux: standard XDG config paths for Chrome and Edge.
+      private_class_method def self.linux_user_data_dirs
+        config_home = ENV["XDG_CONFIG_HOME"] || File.join(Dir.home, ".config")
+        [
+          File.join(config_home, "microsoft-edge"),
+          File.join(config_home, "google-chrome"),
+          File.join(config_home, "google-chrome-beta"),
+          File.join(config_home, "google-chrome-unstable"),
+        ]
+      end
+
+      # macOS: Application Support paths for Chrome and Edge.
+      private_class_method def self.macos_user_data_dirs
+        base = File.join(Dir.home, "Library", "Application Support")
+        [
+          File.join(base, "Microsoft Edge"),
+          File.join(base, "Google", "Chrome"),
+          File.join(base, "Google", "Chrome Beta"),
+          File.join(base, "Google", "Chrome Canary"),
+        ]
+      end
+
+      # -----------------------------------------------------------------------
+      # Helpers
+      # -----------------------------------------------------------------------
+
+      # Parse DevToolsActivePort file.
+      # Format: first line = port number, second line = WS path
+      # @return [String, nil] ws://127.0.0.1:PORT/PATH or nil on parse error
+      private_class_method def self.parse_active_port_file(path)
+        lines = File.read(path, encoding: "utf-8").split("\n").map(&:strip).reject(&:empty?)
+        return nil unless lines.size >= 2
+
+        port = lines[0].to_i
+        ws_path = lines[1]
+        return nil if port <= 0 || port > 65_535 || ws_path.empty?
+
+        "ws://127.0.0.1:#{port}#{ws_path}"
+      rescue StandardError
+        nil
+      end
+
+      # Probe TCP port with a short timeout to verify port is actually reachable.
+      # @param host [String] hostname
+      # @param port [Integer] port number
+      # @return [Boolean] true if port is open and reachable
+      private_class_method def self.tcp_open?(host, port)
+        Socket.tcp(host, port, connect_timeout: 0.5) { true }
+      rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError, Errno::EHOSTUNREACH
+        false
+      end
+    end
+  end
+end

data/lib/octo/utils/encoding.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Octo
+  module Utils
+    # Centralised UTF-8 encoding helpers used throughout the codebase.
+    #
+    # Three distinct use-cases exist:
+    #
+    #   1. to_utf8       – binary/unknown bytes → valid UTF-8 String.
+    #                      Used when reading shell output, HTTP response bodies,
+    #                      or any raw byte stream that is *expected* to be UTF-8
+    #                      but arrives with ASCII-8BIT (binary) encoding.
+    #                      Strategy: force_encoding("UTF-8") then scrub invalid
+    #                      sequences with U+FFFD so multibyte characters (CJK,
+    #                      emoji, …) are preserved as-is.
+    #
+    #   2. sanitize_utf8 – UTF-8 String → clean UTF-8 String.
+    #                      Used for UI rendering (terminal output, screen
+    #                      buffers) where the string is already nominally UTF-8
+    #                      but may still contain isolated invalid bytes.
+    #                      Strategy: encode UTF-8→UTF-8 replacing invalid /
+    #                      undefined codepoints with an empty string so the
+    #                      rendered output never contains replacement characters.
+    #
+    #   3. safe_check    – any String → ASCII-safe UTF-8 String for regex.
+    #                      Used only for security pattern matching (terminal/Security).
+    #                      Multibyte bytes are replaced with '?' so that Ruby's
+    #                      regex engine operates on a plain ASCII-compatible
+    #                      string without raising Encoding errors.
+    #
+    module Encoding
+      # Convert a binary (or unknown-encoding) byte string to a valid UTF-8
+      # String.  Multibyte sequences that are already valid UTF-8 (e.g. CJK
+      # characters) are preserved unchanged; only genuinely invalid byte
+      # sequences are replaced with U+FFFD (the Unicode replacement character).
+      #
+      # @param data [String, nil] raw bytes, typically from a pipe or HTTP body
+      # @return [String] valid UTF-8 string
+      def self.to_utf8(data)
+        return "" if data.nil? || data.empty?
+
+        data.dup.force_encoding("UTF-8").scrub("\u{FFFD}")
+      end
+
+      # Clean an already-UTF-8 string by removing (not replacing) any invalid
+      # or undefined byte sequences.  Suitable for terminal / UI rendering where
+      # replacement characters would appear as visual noise.
+      #
+      # @param str [String, nil] nominally UTF-8 string
+      # @return [String] clean UTF-8 string (invalid bytes silently dropped)
+      def self.sanitize_utf8(str)
+        return "" if str.nil? || str.empty?
+
+        str.encode("UTF-8", "UTF-8", invalid: :replace, undef: :replace, replace: "")
+      end
+
+      # Convert raw shell command output to valid UTF-8.
+      # Handles two common cases:
+      #   - Windows commands (e.g. powershell.exe) that output GBK/CP936 bytes
+      #   - Unix commands that output UTF-8 or ASCII bytes with ASCII-8BIT encoding
+      #
+      # Strategy: try GBK decode first (superset of ASCII, covers Chinese Windows);
+      # if that fails fall back to UTF-8 scrub.
+      #
+      # @param data [String, nil] raw bytes from backtick / IO.popen
+      # @param source_encoding [String] hint for source encoding (default: "GBK")
+      # @return [String] valid UTF-8 string
+      def self.cmd_to_utf8(data, source_encoding: "GBK")
+        return "" if data.nil? || data.empty?
+
+        data.dup
+            .force_encoding(source_encoding)
+            .encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+      rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+        to_utf8(data)
+      end
+
+      # Return an ASCII-safe UTF-8 copy of *str* suitable for security regex
+      # pattern matching.  Any byte that is not valid in the source encoding, or
+      # that cannot be represented in UTF-8, is replaced with '?'.  The
+      # original string is never mutated.
+      #
+      # @param str [String, nil]
+      # @return [String] UTF-8 string safe for regex matching
+      def self.safe_check(str)
+        return "" if str.nil? || str.empty?
+
+        str.encode("UTF-8", invalid: :replace, undef: :replace, replace: "?")
+      end
+    end
+  end
+end

data/lib/octo/utils/environment_detector.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Octo
+  module Utils
+    # Detects the current operating system environment and desktop path.
+    module EnvironmentDetector
+      # Detect OS type.
+      # @return [Symbol] :wsl, :linux, :macos, or :unknown
+      def self.os_type
+        return @os_type if defined?(@os_type)
+
+        @os_type = if wsl?
+          :wsl
+        elsif RUBY_PLATFORM.include?("darwin")
+          :macos
+        elsif RUBY_PLATFORM.include?("linux")
+          :linux
+        else
+          :unknown
+        end
+      end
+
+      # Open a file with the OS-default application.
+      # On WSL, uses "cmd.exe /c start" instead of explorer.exe so the opened
+      # window receives foreground focus even when called from a background
+      # thread (e.g. WEBrick request handler).
+      # @param path [String] Linux-side file path
+      # @return [Boolean, nil] true/false from system(), or nil on unsupported OS
+      def self.open_file(path)
+        case os_type
+        when :macos then system("open", path)
+        when :linux then system("xdg-open", path)
+        when :wsl
+          win_path = linux_to_win_path(path)
+          system("cmd.exe", "/c", "start", "", win_path)
+        end
+      end
+
+      # Convert a Windows-style path to a WSL/Linux-side path.
+      # e.g. "C:/Users/foo/file.txt" → "/mnt/c/Users/foo/file.txt"
+      # Returns the original path unchanged on non-WSL or if already a Linux path.
+      # @param path [String]
+      # @return [String]
+      def self.win_to_linux_path(path)
+        return path unless os_type == :wsl && path.match?(/\A[A-Za-z]:[\/\\]/)
+
+        drive = path[0].downcase
+        rest  = path[2..].gsub("\\", "/")
+        "/mnt/#{drive}#{rest}"
+      end
+
+      # Convert a Linux-side path to a Windows-style path via wslpath.
+      # e.g. "/mnt/c/Users/foo/file.txt" → "C:\Users\foo\file.txt"
+      # Returns the original path unchanged on non-WSL.
+      # @param path [String]
+      # @return [String]
+      def self.linux_to_win_path(path)
+        return path unless os_type == :wsl
+
+        Octo::Utils::Encoding.cmd_to_utf8(
+          `wslpath -w '#{path.gsub("'", "'\''")}'`,
+          source_encoding: "UTF-8"
+        ).strip
+      end
+
+      # Human-readable OS label for injection into session context.
+      def self.os_label
+        case os_type
+        when :wsl    then "WSL/Windows"
+        when :macos  then "macOS"
+        when :linux  then "Linux"
+        else              "Unknown"
+        end
+      end
+
+      # Detect the desktop directory path for the current environment.
+      # @return [String, nil] absolute path to desktop, or nil if not found
+      def self.desktop_path
+        return @desktop_path if defined?(@desktop_path)
+
+        @desktop_path = case os_type
+        when :wsl
+          wsl_desktop_path
+        when :macos
+          macos_desktop_path
+        when :linux
+          linux_desktop_path
+        else
+          fallback_desktop_path
+        end
+      end
+
+      def self.wsl?
+        File.exist?("/proc/version") &&
+          File.read("/proc/version").downcase.include?("microsoft")
+      rescue
+        false
+      end
+
+      private_class_method def self.wsl_desktop_path
+        if Utils::Encoding.cmd_to_utf8(`which powershell.exe 2>/dev/null`).strip.empty?
+          return fallback_desktop_path
+        end
+
+        # powershell.exe on Chinese Windows outputs GBK bytes; decode explicitly
+        win_path = Utils::Encoding.cmd_to_utf8(
+          `powershell.exe -NoProfile -Command '[Environment]::GetFolderPath("Desktop")' 2>/dev/null`
+        ).strip.tr("\r\n", "")
+        return fallback_desktop_path if win_path.empty?
+
+        # wslpath output is UTF-8 (Linux side)
+        linux_path = Utils::Encoding.cmd_to_utf8(`wslpath '#{win_path}' 2>/dev/null`, source_encoding: "UTF-8").strip
+        return linux_path if !linux_path.empty? && Dir.exist?(linux_path)
+
+        fallback_desktop_path
+      end
+
+      private_class_method def self.linux_desktop_path
+        path = Utils::Encoding.cmd_to_utf8(`xdg-user-dir DESKTOP 2>/dev/null`, source_encoding: "UTF-8").strip
+        return path if !path.empty? && path != Dir.home && Dir.exist?(path)
+
+        fallback_desktop_path
+      end
+
+      private_class_method def self.macos_desktop_path
+        path = Utils::Encoding.cmd_to_utf8(`osascript -e 'POSIX path of (path to desktop)' 2>/dev/null`, source_encoding: "UTF-8").strip.chomp("/")
+        return path if !path.empty? && Dir.exist?(path)
+
+        fallback_desktop_path
+      end
+
+      private_class_method def self.fallback_desktop_path
+        [
+          File.join(Dir.home, "Desktop"),
+          File.join(Dir.home, "桌面"),
+        ].find { |p| Dir.exist?(p) }
+      end
+    end
+  end
+end

data/lib/octo/utils/file_ignore_helper.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Octo
+  module Utils
+    # Helper module for file ignoring functionality shared between tools
+    module FileIgnoreHelper
+      # Default patterns to ignore when .gitignore is not available
+      DEFAULT_IGNORED_PATTERNS = [
+        'node_modules',
+        'vendor/bundle',
+        '.git',
+        '.svn',
+        'tmp',
+        'log',
+        'coverage',
+        'dist',
+        'build',
+        '.bundle',
+        '.sass-cache',
+        '.DS_Store',
+        '*.log'
+      ].freeze
+
+      # Config file patterns that should always be searchable/visible
+      CONFIG_FILE_PATTERNS = [
+        /\.env/,
+        /\.ya?ml$/,
+        /\.json$/,
+        /\.toml$/,
+        /\.ini$/,
+        /\.conf$/,
+        /\.config$/,
+      ].freeze
+
+      # Find .gitignore file in the search path or parent directories
+      # Only searches within the search path and up to the current working directory
+      def self.find_gitignore(path)
+        search_path = File.directory?(path) ? path : File.dirname(path)
+
+        # Look for .gitignore in current and parent directories
+        current = File.expand_path(search_path)
+        cwd = File.expand_path(Dir.pwd) # intentional: gitignore boundary uses process cwd as fallback
+        root = File.expand_path('/')
+
+        # Limit search: only go up to current working directory
+        # This prevents finding .gitignore files from unrelated parent directories
+        # when searching in temporary directories (like /tmp in tests)
+        search_limit = if current.start_with?(cwd)
+                        cwd
+                      else
+                        current
+                      end
+
+        loop do
+          gitignore = File.join(current, '.gitignore')
+          return gitignore if File.exist?(gitignore)
+
+          # Stop if we've reached the search limit or root
+          break if current == search_limit || current == root
+          current = File.dirname(current)
+        end
+
+        nil
+      end
+
+      # Directories that are always ignored regardless of .gitignore rules
+      ALWAYS_IGNORED_DIRS = ['.git', '.svn', '.hg'].freeze
+
+      # Check if file should be ignored based on .gitignore or default patterns
+      def self.should_ignore_file?(file, base_path, gitignore)
+        # Always calculate path relative to base_path for consistency
+        # Expand both paths to handle symlinks and relative paths correctly
+        expanded_file = File.expand_path(file)
+        expanded_base = File.expand_path(base_path)
+
+        # For files, use the directory as base
+        expanded_base = File.dirname(expanded_base) if File.file?(expanded_base)
+
+        # Calculate relative path
+        if expanded_file.start_with?(expanded_base)
+          relative_path = expanded_file[(expanded_base.length + 1)..-1] || File.basename(expanded_file)
+        else
+          # File is outside base path - use just the filename
+          relative_path = File.basename(expanded_file)
+        end
+
+        # Clean up relative path
+        relative_path = relative_path.sub(/^\.\//, '') if relative_path
+
+        # Always ignore version control directories regardless of .gitignore rules
+        return true if ALWAYS_IGNORED_DIRS.any? do |dir|
+          relative_path.start_with?("#{dir}/") || relative_path == dir
+        end
+
+        if gitignore
+          # Use .gitignore rules
+          gitignore.ignored?(relative_path)
+        else
+          # Use default ignore patterns - only match against relative path components
+          DEFAULT_IGNORED_PATTERNS.any? do |pattern|
+            if pattern.include?('*')
+              File.fnmatch(pattern, relative_path, File::FNM_PATHNAME | File::FNM_DOTMATCH)
+            else
+              # Match pattern as a path component (not substring of absolute path)
+              relative_path.start_with?("#{pattern}/") ||
+              relative_path.include?("/#{pattern}/") ||
+              relative_path == pattern ||
+              File.basename(relative_path) == pattern
+            end
+          end
+        end
+      end
+
+      # Check if file is a config file (should not be ignored even if in .gitignore)
+      def self.is_config_file?(file)
+        CONFIG_FILE_PATTERNS.any? { |pattern| file.match?(pattern) }
+      end
+
+      # Walk a directory tree, pruning ignored directories early.
+      # Yields each non-ignored file path. Supports nested .gitignore files.
+      # @param skipped [Hash, nil] If provided, increments :ignored for each gitignore-skipped entry.
+      def self.walk_files(base_path, gitignore: nil, skipped: nil, &block)
+        return enum_for(:walk_files, base_path, gitignore: gitignore, skipped: skipped) unless block_given?
+
+        root_gitignore = gitignore || begin
+          gi_path = find_gitignore(base_path)
+          gi_path ? Octo::GitignoreParser.new(gi_path) : nil
+        end
+
+        _walk_recursive(base_path, base_path, root_gitignore, skipped, &block)
+      end
+
+      def self._walk_recursive(dir, base_path, gitignore, skipped, &block)
+        child_gitignore_path = File.join(dir, ".gitignore")
+        if dir != base_path && File.exist?(child_gitignore_path)
+          gitignore ||= Octo::GitignoreParser.new(nil)
+          relative_dir = dir[(base_path.length + 1)..]
+          gitignore.merge!(child_gitignore_path, prefix: relative_dir)
+        end
+
+        begin
+          entries = Dir.children(dir)
+        rescue Errno::EACCES, Errno::ENOENT
+          return
+        end
+
+        entries.sort.each do |name|
+          full = File.join(dir, name)
+          relative = full[(base_path.length + 1)..]
+
+          if File.directory?(full)
+            next if ALWAYS_IGNORED_DIRS.include?(name)
+            if gitignore&.ignored?("#{relative}/") || should_ignore_file?(full, base_path, gitignore)
+              next
+            end
+            _walk_recursive(full, base_path, gitignore, skipped, &block)
+          else
+            if !is_config_file?(full) && should_ignore_file?(full, base_path, gitignore)
+              skipped[:ignored] += 1 if skipped
+              next
+            end
+            yield full
+          end
+        end
+      end
+      private_class_method :_walk_recursive
+
+    end
+  end
+end