agent_ferrum 0.1.0

data/lib/agent_ferrum/content/accessibility_tree.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module AgentFerrum
+  module Content
+    class AccessibilityTree
+      INTERACTIVE_ROLES = %w[
+        button link textbox checkbox radio combobox
+        menuitem tab slider spinbutton searchbox switch
+        option listbox menu menubar
+      ].freeze
+
+      attr_reader :refs, :nodes
+
+      def initialize(browser)
+        @browser = browser
+        @refs = {}
+        @nodes = []
+        extract!
+      end
+
+      def to_s
+        @nodes.map { |n| format_node(n) }.join("\n")
+      end
+
+      private
+
+      def extract!
+        result = @browser.ferrum.page.command("Accessibility.getFullAXTree")
+        ax_nodes = result["nodes"]
+
+        ref_counter = 0
+        ax_nodes.each do |ax_node|
+          role = ax_node.dig("role", "value")
+          next unless INTERACTIVE_ROLES.include?(role)
+          next if ignored?(ax_node)
+
+          ref_counter += 1
+          ref = "@e#{ref_counter}"
+
+          node_info = {
+            ref:             ref,
+            role:            role,
+            name:            ax_node.dig("name", "value") || "",
+            value:           ax_node.dig("value", "value"),
+            description:     ax_node.dig("description", "value"),
+            backend_node_id: ax_node["backendDOMNodeId"],
+            properties:      extract_properties(ax_node)
+          }
+
+          @refs[ref] = node_info
+          @nodes << node_info
+        end
+      end
+
+      def ignored?(ax_node)
+        ignored = ax_node["ignored"]
+        case ignored
+        when Hash then ignored["value"] == true
+        when true then true
+        else false
+        end
+      end
+
+      def extract_properties(ax_node)
+        props = {}
+        (ax_node["properties"] || []).each do |prop|
+          name = prop["name"]
+          value = prop.dig("value", "value")
+          props[name] = value if %w[disabled required checked selected readonly].include?(name)
+        end
+        props
+      end
+
+      def format_node(node)
+        parts = ["#{node[:ref]}: [#{node[:role]}] \"#{node[:name]}\""]
+        parts << "value=\"#{node[:value]}\"" if node[:value]
+        parts << node[:properties].map { |k, v| "#{k}=#{v}" }.join(" ") if node[:properties]&.any?
+        parts.join(" ")
+      end
+    end
+  end
+end

data/lib/agent_ferrum/content/markdown_converter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "reverse_markdown"
+
+module AgentFerrum
+  module Content
+    class MarkdownConverter
+      def initialize(html)
+        @html = html
+      end
+
+      def convert
+        md = ReverseMarkdown.convert(@html,
+          unknown_tags:    :bypass,
+          github_flavored: true)
+        compact(md)
+      end
+
+      private
+
+      def compact(markdown)
+        markdown
+          .gsub(/\n{3,}/, "\n\n")
+          .gsub(/^[ \t]+$/, "")
+          .gsub(/\[([^\]]*)\]\(\s*\)/, '\1')
+          .gsub(/!\[\]\([^)]*\)/, "")
+          .gsub(/\s+\n/, "\n")
+          .strip
+      end
+    end
+  end
+end

data/lib/agent_ferrum/content/snapshot.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module AgentFerrum
+  module Content
+    class Snapshot
+      attr_reader :accessibility, :markdown_content, :url, :title, :refs
+
+      def initialize(browser)
+        @url = browser.current_url
+        @title = browser.title
+
+        filtered_html = VisibilityFilter.new(browser).filtered_html
+        @accessibility = AccessibilityTree.new(browser)
+        @refs = @accessibility.refs
+        @markdown_content = MarkdownConverter.new(filtered_html).convert
+      end
+
+      def markdown
+        @markdown_content
+      end
+
+      def accessibility_tree
+        @accessibility.to_s
+      end
+
+      def to_s
+        <<~SNAPSHOT
+          # #{@title}
+          URL: #{@url}
+
+          ## Interactive Elements
+          #{@accessibility}
+
+          ## Page Content
+          #{@markdown_content}
+        SNAPSHOT
+      end
+
+      def estimated_tokens
+        to_s.length / 4
+      end
+    end
+  end
+end

data/lib/agent_ferrum/content/visibility_filter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module AgentFerrum
+  module Content
+    class VisibilityFilter
+      FILTER_SCRIPT = <<~JS
+        (() => {
+          const clone = document.body.cloneNode(true);
+          ['script','style','noscript','svg','path','meta','link',
+           'template','iframe'].forEach(tag => {
+            clone.querySelectorAll(tag).forEach(el => el.remove());
+          });
+          clone.querySelectorAll('[aria-hidden="true"]').forEach(el => el.remove());
+          clone.querySelectorAll('[hidden]').forEach(el => el.remove());
+          return clone.innerHTML;
+        })()
+      JS
+
+      def initialize(browser)
+        @browser = browser
+      end
+
+      def filtered_html
+        raw_html = @browser.ferrum.evaluate(FILTER_SCRIPT)
+        post_process(raw_html)
+      end
+
+      private
+
+      def post_process(html)
+        doc = Nokogiri::HTML::DocumentFragment.parse(html)
+        doc.xpath("//comment()").remove
+        doc.traverse do |node|
+          next unless node.element?
+
+          %w[style class data-testid data-cy onclick onload onerror].each { |attr| node.delete(attr) }
+        end
+        doc.to_html
+      end
+    end
+  end
+end

data/lib/agent_ferrum/downloads.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module AgentFerrum
+  class Downloads
+    def initialize(browser)
+      @browser = browser
+      @download_path = nil
+    end
+
+    def download_path=(path)
+      @download_path = File.expand_path(path)
+      FileUtils.mkdir_p(@download_path)
+      @browser.ferrum.page.command("Browser.setDownloadBehavior",
+        behavior:     "allow",
+        downloadPath: @download_path)
+    end
+
+    attr_reader :download_path
+
+    def wait(timeout: 30, filename: nil)
+      raise AgentFerrum::Error, "Download path not set. Set download_path first." unless @download_path
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+      loop do
+        match = find_completed_download(filename)
+        return match if match && File.mtime(match) > (Time.now - timeout)
+
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise Waiter::TimeoutError, "Download timeout (#{timeout}s)" if remaining <= 0
+
+        sleep 0.5
+      end
+    end
+
+    private
+
+    def find_completed_download(filename)
+      files = Dir.glob(File.join(@download_path, "*"))
+                 .reject { |f| f.end_with?(".crdownload", ".tmp") }
+                 .select { |f| File.file?(f) }
+
+      if filename
+        files.find { |f| File.basename(f) == filename }
+      else
+        files.max_by { |f| File.mtime(f) }
+      end
+    end
+  end
+end

data/lib/agent_ferrum/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module AgentFerrum
+  class Error < StandardError; end
+
+  class RefNotFoundError < Error
+    def initialize(ref)
+      super("Element ref '#{ref}' not found. Call browser.snapshot to refresh refs.")
+    end
+  end
+
+  class ElementNotFoundError < Error
+    def initialize(selector)
+      super("No element matches '#{selector}'. Check the selector or call snapshot to see available elements.")
+    end
+  end
+
+  class NavigationError < Error; end
+  class StealthError < Error; end
+end

data/lib/agent_ferrum/node.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module AgentFerrum
+  class Node
+    MAX_RETRIES = 3
+
+    def initialize(ferrum_node)
+      @node = ferrum_node
+    end
+
+    def click
+      with_retry { @node.click }
+    end
+
+    def fill(value)
+      with_retry do
+        @node.focus
+        @node.type(value)
+      end
+    end
+
+    def select(value)
+      with_retry { @node.select(value) }
+    end
+
+    def hover
+      with_retry { @node.hover }
+    end
+
+    def focus
+      with_retry { @node.focus }
+    end
+
+    def text
+      @node.text
+    end
+
+    def value
+      @node.value
+    end
+
+    def [](attr)
+      @node[attr]
+    end
+
+    private
+
+    def with_retry
+      attempts = 0
+      begin
+        attempts += 1
+        yield
+      rescue Ferrum::NodeMovingError, Ferrum::CoordinatesNotFoundError
+        raise if attempts >= MAX_RETRIES
+
+        sleep 0.1
+        retry
+      end
+    end
+  end
+end

data/lib/agent_ferrum/stealth/manager.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AgentFerrum
+  module Stealth
+    class Manager
+      SCRIPTS_DIR = File.join(__dir__, "scripts")
+
+      def apply(page, profile)
+        scripts = Profiles.scripts_for(profile)
+        scripts.each do |script_name|
+          js = load_script(script_name)
+          page.command("Page.addScriptToEvaluateOnNewDocument", source: js)
+        end
+
+        # Override user-agent at CDP level if included in the profile
+        return unless scripts.include?("user_agent")
+
+        current_ua = page.command("Runtime.evaluate", expression: "navigator.userAgent").dig("result", "value") || ""
+        return unless current_ua.include?("HeadlessChrome")
+
+        clean_ua = current_ua.gsub("HeadlessChrome", "Chrome")
+        page.command("Network.setUserAgentOverride", userAgent: clean_ua)
+      end
+
+      private
+
+      def load_script(name)
+        utils = File.read(File.join(SCRIPTS_DIR, "utils.js"))
+        script = File.read(File.join(SCRIPTS_DIR, "#{name}.js"))
+        "#{utils}\n#{script}"
+      end
+    end
+  end
+end

data/lib/agent_ferrum/stealth/profiles.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module AgentFerrum
+  module Stealth
+    module Profiles
+      PROFILES = {
+        minimal:  %w[webdriver],
+        moderate: %w[webdriver navigator_vendor chrome_runtime user_agent],
+        maximum:  %w[webdriver navigator_vendor navigator_plugins chrome_runtime
+                     webgl_vendor iframe_content_window user_agent]
+      }.freeze
+
+      def self.scripts_for(profile)
+        PROFILES.fetch(profile) do
+          raise StealthError, "Unknown stealth profile: #{profile}. Valid: #{PROFILES.keys.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/agent_ferrum/stealth/scripts/chrome_runtime.js

@@ -0,0 +1,34 @@
+// Add window.chrome.runtime to pass detection checks
+if (!window.chrome) {
+  window.chrome = {};
+}
+if (!window.chrome.runtime) {
+  window.chrome.runtime = {
+    connect: function() {},
+    sendMessage: function() {},
+    id: undefined
+  };
+}
+// Also ensure chrome.csi and chrome.loadTimes exist
+if (!window.chrome.csi) {
+  window.chrome.csi = function() { return {}; };
+}
+if (!window.chrome.loadTimes) {
+  window.chrome.loadTimes = function() {
+    return {
+      commitLoadTime: Date.now() / 1000,
+      connectionInfo: 'http/1.1',
+      finishDocumentLoadTime: Date.now() / 1000 + 0.1,
+      finishLoadTime: Date.now() / 1000 + 0.2,
+      firstPaintAfterLoadTime: 0,
+      firstPaintTime: Date.now() / 1000 + 0.05,
+      navigationType: 'Other',
+      npnNegotiatedProtocol: 'http/1.1',
+      requestTime: Date.now() / 1000 - 0.5,
+      startLoadTime: Date.now() / 1000 - 0.4,
+      wasAlternateProtocolAvailable: false,
+      wasFetchedViaSpdy: false,
+      wasNpnNegotiated: false
+    };
+  };
+}

data/lib/agent_ferrum/stealth/scripts/iframe_content_window.js

@@ -0,0 +1,22 @@
+// Fix iframe contentWindow detection
+try {
+  const originalContentWindow = Object.getOwnPropertyDescriptor(HTMLIFrameElement.prototype, 'contentWindow');
+  Object.defineProperty(HTMLIFrameElement.prototype, 'contentWindow', {
+    get: function() {
+      const result = originalContentWindow.get.call(this);
+      if (result === null) {
+        return result;
+      }
+      // Ensure the contentWindow has the expected chrome property
+      try {
+        if (!result.chrome) {
+          result.chrome = window.chrome;
+        }
+      } catch (e) {
+        // Cross-origin frame, ignore
+      }
+      return result;
+    },
+    configurable: true
+  });
+} catch (e) {}

data/lib/agent_ferrum/stealth/scripts/navigator_plugins.js

@@ -0,0 +1,64 @@
+// Simulate realistic browser plugins
+const mockPlugins = [
+  {
+    name: 'Chrome PDF Plugin',
+    description: 'Portable Document Format',
+    filename: 'internal-pdf-viewer',
+    mimeTypes: [{ type: 'application/x-google-chrome-pdf', suffixes: 'pdf', description: 'Portable Document Format' }]
+  },
+  {
+    name: 'Chrome PDF Viewer',
+    description: '',
+    filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai',
+    mimeTypes: [{ type: 'application/pdf', suffixes: 'pdf', description: '' }]
+  },
+  {
+    name: 'Native Client',
+    description: '',
+    filename: 'internal-nacl-plugin',
+    mimeTypes: [
+      { type: 'application/x-nacl', suffixes: '', description: 'Native Client Executable' },
+      { type: 'application/x-pnacl', suffixes: '', description: 'Portable Native Client Executable' }
+    ]
+  }
+];
+
+const createMimeType = (mt, plugin) => {
+  const mimeType = Object.create(MimeType.prototype);
+  overrideGetter(mimeType, 'type', mt.type);
+  overrideGetter(mimeType, 'suffixes', mt.suffixes);
+  overrideGetter(mimeType, 'description', mt.description);
+  overrideGetter(mimeType, 'enabledPlugin', plugin);
+  return mimeType;
+};
+
+const createPlugin = (p) => {
+  const plugin = Object.create(Plugin.prototype);
+  overrideGetter(plugin, 'name', p.name);
+  overrideGetter(plugin, 'description', p.description);
+  overrideGetter(plugin, 'filename', p.filename);
+  overrideGetter(plugin, 'length', p.mimeTypes.length);
+  p.mimeTypes.forEach((mt, i) => {
+    const mimeType = createMimeType(mt, plugin);
+    plugin[i] = mimeType;
+    plugin[mt.type] = mimeType;
+  });
+  plugin[Symbol.iterator] = function* () {
+    for (let i = 0; i < this.length; i++) yield this[i];
+  };
+  return plugin;
+};
+
+try {
+  const plugins = mockPlugins.map(createPlugin);
+  const pluginArray = Object.create(PluginArray.prototype);
+  plugins.forEach((p, i) => {
+    pluginArray[i] = p;
+    pluginArray[p.name] = p;
+  });
+  overrideGetter(pluginArray, 'length', plugins.length);
+  pluginArray[Symbol.iterator] = function* () {
+    for (let i = 0; i < this.length; i++) yield this[i];
+  };
+  overrideGetter(navigator, 'plugins', pluginArray);
+} catch (e) {}

data/lib/agent_ferrum/stealth/scripts/navigator_vendor.js

@@ -0,0 +1,4 @@
+// Spoof navigator.vendor and navigator.platform
+overrideGetter(navigator, 'vendor', 'Google Inc.');
+overrideGetter(navigator, 'platform', 'Win32');
+overrideGetter(navigator, 'maxTouchPoints', 0);

data/lib/agent_ferrum/stealth/scripts/user_agent.js

@@ -0,0 +1,12 @@
+// Clean HeadlessChrome from user agent string
+const ua = navigator.userAgent;
+if (ua.includes('HeadlessChrome')) {
+  const cleanUA = ua.replace('HeadlessChrome', 'Chrome');
+  overrideGetter(navigator, 'userAgent', cleanUA);
+
+  // Also fix appVersion
+  const appVersion = navigator.appVersion;
+  if (appVersion.includes('HeadlessChrome')) {
+    overrideGetter(navigator, 'appVersion', appVersion.replace('HeadlessChrome', 'Chrome'));
+  }
+}

data/lib/agent_ferrum/stealth/scripts/utils.js

@@ -0,0 +1,24 @@
+// Stealth utility helpers
+const makeNativeToString = (fn, name = '') => {
+  const handler = {
+    apply: function(target, ctx, args) {
+      if (ctx === Function.prototype.toString) {
+        return `function toString() { [native code] }`;
+      }
+      return `function ${name || fn.name || ''}() { [native code] }`;
+    }
+  };
+  const proxy = new Proxy(Function.prototype.toString, handler);
+  try {
+    Function.prototype.toString = proxy;
+  } catch (e) {}
+};
+
+const overrideGetter = (obj, prop, value) => {
+  try {
+    Object.defineProperty(obj, prop, {
+      get: () => value,
+      configurable: true
+    });
+  } catch (e) {}
+};

data/lib/agent_ferrum/stealth/scripts/webdriver.js

@@ -0,0 +1,16 @@
+// Remove navigator.webdriver flag
+Object.defineProperty(navigator, 'webdriver', {
+  get: () => false,
+  configurable: true
+});
+
+// Also handle the permissions API check
+if (navigator.permissions) {
+  const originalQuery = navigator.permissions.query;
+  navigator.permissions.query = (parameters) => {
+    if (parameters.name === 'notifications') {
+      return Promise.resolve({ state: Notification.permission });
+    }
+    return originalQuery.call(navigator.permissions, parameters);
+  };
+}

data/lib/agent_ferrum/stealth/scripts/webgl_vendor.js

@@ -0,0 +1,27 @@
+// Override WebGL vendor/renderer to hide headless indicators
+const getParameter = WebGLRenderingContext.prototype.getParameter;
+WebGLRenderingContext.prototype.getParameter = function(parameter) {
+  // UNMASKED_VENDOR_WEBGL
+  if (parameter === 37445) {
+    return 'Intel Inc.';
+  }
+  // UNMASKED_RENDERER_WEBGL
+  if (parameter === 37446) {
+    return 'Intel Iris OpenGL Engine';
+  }
+  return getParameter.call(this, parameter);
+};
+
+// Also handle WebGL2
+if (typeof WebGL2RenderingContext !== 'undefined') {
+  const getParameter2 = WebGL2RenderingContext.prototype.getParameter;
+  WebGL2RenderingContext.prototype.getParameter = function(parameter) {
+    if (parameter === 37445) {
+      return 'Intel Inc.';
+    }
+    if (parameter === 37446) {
+      return 'Intel Iris OpenGL Engine';
+    }
+    return getParameter2.call(this, parameter);
+  };
+}

data/lib/agent_ferrum/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentFerrum
+  VERSION = "0.1.0"
+end

data/lib/agent_ferrum/waiter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AgentFerrum
+  class Waiter
+    def initialize(browser, default_timeout:, default_interval:)
+      @browser = browser
+      @default_timeout = default_timeout
+      @default_interval = default_interval
+    end
+
+    def call(css: nil, xpath: nil, text: nil, timeout: nil, interval: nil, &)
+      timeout ||= @default_timeout
+      interval ||= @default_interval
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+      loop do
+        result = check_condition(css:, xpath:, text:, &)
+        return result if result
+
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise Waiter::TimeoutError, build_message(css:, xpath:, text:, timeout:) if remaining <= 0
+
+        sleep [interval, remaining].min
+      end
+    end
+
+    class TimeoutError < AgentFerrum::Error; end
+
+    private
+
+    def check_condition(css:, xpath:, text:, &block)
+      if block
+        block.call(@browser)
+      elsif css
+        @browser.ferrum.at_css(css)
+      elsif xpath
+        @browser.ferrum.at_xpath(xpath)
+      elsif text
+        @browser.ferrum.at_xpath("//*[contains(text(), '#{escape_xpath(text)}')]")
+      end
+    rescue Ferrum::NodeNotFoundError
+      nil
+    end
+
+    def escape_xpath(str)
+      str.gsub("'", "\\\\'")
+    end
+
+    def build_message(css:, xpath:, text:, timeout:)
+      target = css || xpath || text || "block condition"
+      "Timeout (#{timeout}s) waiting for: #{target}"
+    end
+  end
+end