crucible 0.1.2

data/lib/crucible/configuration.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Crucible
+  # Configuration for the Crucible server
+  #
+  # Supports both programmatic configuration and YAML config files.
+  #
+  # @example Programmatic configuration
+  #   config = Crucible::Configuration.new(headless: false, timeout: 60)
+  #   config.viewport_width = 1920
+  #
+  # @example From YAML file
+  #   config = Crucible::Configuration.from_file("~/.config/crucible/config.yml")
+  #
+  class Configuration
+    DEFAULT_CONFIG_PATHS = [
+      '~/.config/crucible/config.yml',
+      '~/.crucible.yml',
+      '.crucible.yml'
+    ].freeze
+
+    DEFAULTS = {
+      headless: true,
+      viewport_width: 1280,
+      viewport_height: 720,
+      chrome_path: nil,
+      timeout: 30,
+      error_level: :warn,
+      screenshot_format: :png,
+      content_format: :html,
+      # Stealth settings
+      stealth_enabled: true,
+      stealth_profile: :moderate,
+      stealth_locale: 'en-US,en',
+      # Mode settings
+      mode: nil,
+      log_file: nil
+    }.freeze
+
+    VALID_ERROR_LEVELS = %i[debug info warn error].freeze
+    VALID_SCREENSHOT_FORMATS = %i[png jpeg base64].freeze
+    VALID_CONTENT_FORMATS = %i[html text].freeze
+    VALID_STEALTH_PROFILES = %i[minimal moderate maximum].freeze
+
+    attr_accessor(*DEFAULTS.keys, :modes)
+
+    # Load configuration from a YAML file
+    # @param path [String] path to the YAML config file
+    # @return [Configuration]
+    def self.from_file(path)
+      expanded_path = File.expand_path(path)
+      raise Error, "Config file not found: #{expanded_path}" unless File.exist?(expanded_path)
+
+      yaml = YAML.safe_load_file(expanded_path, symbolize_names: true)
+      from_yaml_hash(yaml)
+    end
+
+    # Load configuration from default locations
+    # @return [Configuration] config from first found file, or defaults
+    def self.from_defaults
+      DEFAULT_CONFIG_PATHS.each do |path|
+        expanded = File.expand_path(path)
+        return from_file(expanded) if File.exist?(expanded)
+      end
+
+      new
+    end
+
+    # Create configuration from a parsed YAML hash
+    # @param yaml [Hash] parsed YAML configuration
+    # @return [Configuration]
+    def self.from_yaml_hash(yaml)
+      options = {}
+
+      # Browser settings
+      if yaml[:browser]
+        options[:headless] = yaml[:browser][:headless] if yaml[:browser].key?(:headless)
+        if yaml[:browser][:window_size].is_a?(Array)
+          options[:viewport_width] = yaml[:browser][:window_size][0]
+          options[:viewport_height] = yaml[:browser][:window_size][1]
+        end
+        options[:chrome_path] = yaml[:browser][:chrome_path] if yaml[:browser][:chrome_path]
+        options[:timeout] = yaml[:browser][:timeout] if yaml[:browser][:timeout]
+      end
+
+      # Stealth settings
+      if yaml[:stealth]
+        options[:stealth_enabled] = yaml[:stealth][:enabled] if yaml[:stealth].key?(:enabled)
+        options[:stealth_profile] = yaml[:stealth][:profile]&.to_sym if yaml[:stealth][:profile]
+        options[:stealth_locale] = yaml[:stealth][:locale] if yaml[:stealth][:locale]
+      end
+
+      # Server settings
+      if yaml[:server]
+        options[:error_level] = yaml[:server][:log_level]&.to_sym if yaml[:server][:log_level]
+        options[:log_file] = yaml[:server][:logfile] if yaml[:server][:logfile]
+      end
+
+      config = new(options)
+
+      # Store modes for runtime switching
+      config.modes = yaml[:modes] if yaml[:modes]
+
+      config
+    end
+
+    # @param options [Hash] configuration options
+    def initialize(options = {})
+      DEFAULTS.each do |key, default|
+        value = options.fetch(key, default)
+        # Symbolize string keys for enums
+        value = value.to_sym if value.is_a?(String) && enum_key?(key)
+        instance_variable_set(:"@#{key}", value)
+      end
+      @modes = {}
+    end
+
+    # Creates a new Configuration with merged options
+    # @param options [Hash] options to merge
+    # @return [Configuration]
+    def merge(options)
+      self.class.new(to_h.merge(options))
+    end
+
+    # Converts configuration to a hash
+    # @return [Hash]
+    def to_h
+      DEFAULTS.keys.to_h { |k| [k, instance_variable_get(:"@#{k}")] }
+    end
+
+    # Returns options suitable for Ferrum::Browser.new
+    # @return [Hash]
+    def browser_options
+      opts = {
+        headless: headless,
+        window_size: [viewport_width, viewport_height],
+        timeout: timeout,
+        process_timeout: timeout * 2
+      }
+      opts[:browser_path] = chrome_path if chrome_path
+      opts
+    end
+
+    # Creates a Stealth instance based on configuration
+    # @return [Stealth]
+    def stealth
+      Stealth.new(
+        profile: stealth_profile,
+        enabled: stealth_enabled,
+        locale: stealth_locale
+      )
+    end
+
+    # Apply a named mode from the modes configuration
+    # @param mode_name [String, Symbol] the mode to apply
+    # @return [Configuration] self with mode settings applied
+    def apply_mode(mode_name)
+      mode_name = mode_name.to_sym
+      return self unless modes && modes[mode_name]
+
+      mode_config = modes[mode_name]
+
+      self.stealth_profile = mode_config[:stealth_profile]&.to_sym if mode_config[:stealth_profile]
+      self.screenshot_format = mode_config[:screenshot_format]&.to_sym if mode_config[:screenshot_format]
+      self.timeout = mode_config[:wait_timeout] / 1000 if mode_config[:wait_timeout]
+
+      @mode = mode_name
+      self
+    end
+
+    # Get list of available mode names
+    # @return [Array<Symbol>]
+    def available_modes
+      modes&.keys || []
+    end
+
+    # Validates the configuration
+    # @raise [Error] if configuration is invalid
+    def validate!
+      raise Error, 'Timeout must be positive' unless timeout.positive?
+      raise Error, 'Viewport width must be positive' unless viewport_width.positive?
+      raise Error, 'Viewport height must be positive' unless viewport_height.positive?
+
+      unless VALID_ERROR_LEVELS.include?(error_level)
+        raise Error, "Invalid error_level: #{error_level}. Must be one of: #{VALID_ERROR_LEVELS.join(', ')}"
+      end
+
+      unless VALID_SCREENSHOT_FORMATS.include?(screenshot_format)
+        raise Error,
+              "Invalid screenshot_format: #{screenshot_format}. Must be one of: #{VALID_SCREENSHOT_FORMATS.join(', ')}"
+      end
+
+      unless VALID_CONTENT_FORMATS.include?(content_format)
+        raise Error, "Invalid content_format: #{content_format}. Must be one of: #{VALID_CONTENT_FORMATS.join(', ')}"
+      end
+
+      unless VALID_STEALTH_PROFILES.include?(stealth_profile)
+        raise Error, "Invalid stealth_profile: #{stealth_profile}. Must be one of: #{VALID_STEALTH_PROFILES.join(', ')}"
+      end
+
+      true
+    end
+
+    private
+
+    def enum_key?(key)
+      %i[error_level screenshot_format content_format stealth_profile].include?(key)
+    end
+  end
+end

data/lib/crucible/server.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'mcp'
+
+module Crucible
+  # MCP Server for browser automation
+  #
+  # Provides browser automation tools via the Model Context Protocol.
+  # Uses stdio transport for communication with AI agents.
+  #
+  # @example
+  #   config = Crucible::Configuration.new(headless: true)
+  #   server = Crucible::Server.new(config)
+  #   server.run
+  #
+  class Server
+    # @param config [Configuration, Hash] server configuration
+    def initialize(config)
+      @config = config.is_a?(Configuration) ? config : Configuration.new(config)
+      @config.validate!
+      @session_manager = SessionManager.new(@config)
+      @running = false
+    end
+
+    # Starts the MCP server (blocking)
+    def run
+      @running = true
+      setup_signal_handlers
+
+      server = create_mcp_server
+      transport = MCP::Server::Transports::StdioTransport.new(server)
+
+      log(:info, "Crucible server starting (headless: #{@config.headless})")
+      transport.open
+    rescue Interrupt
+      log(:info, 'Shutting down...')
+    ensure
+      shutdown
+    end
+
+    # Gracefully shuts down the server
+    def shutdown
+      return unless @running
+
+      @running = false
+      @session_manager.close_all
+      log(:info, 'Server stopped')
+    end
+
+    private
+
+    def create_mcp_server
+      MCP::Server.new(
+        name: 'crucible',
+        version: VERSION,
+        instructions: instructions_text,
+        tools: Tools.all(@session_manager, @config)
+      )
+    end
+
+    def instructions_text
+      <<~INSTRUCTIONS
+        Browser automation server powered by Ferrum and headless Chrome.
+
+        ## Sessions
+        Use the `session` parameter to manage multiple independent browser instances.
+        Default session is "default". Sessions persist until explicitly closed.
+
+        ## Common Workflows
+
+        ### Basic Navigation
+        1. navigate(url: "https://example.com")
+        2. wait_for(selector: ".content")
+        3. get_content(format: "text")
+
+        ### Form Interaction
+        1. navigate(url: "https://example.com/login")
+        2. type(selector: "#email", text: "user@example.com")
+        3. type(selector: "#password", text: "secret")
+        4. click(selector: "button[type=submit]")
+
+        ### Screenshots & PDFs
+        - screenshot() - viewport screenshot
+        - screenshot(full_page: true) - full page
+        - screenshot(selector: ".element") - specific element
+        - pdf(format: "A4", landscape: true)
+
+        ### JavaScript Execution
+        - evaluate(expression: "document.title")
+        - evaluate(expression: "window.scrollTo(0, 0)")
+
+        ## Session Management
+        - list_sessions() - see all active sessions
+        - close_session(session: "name") - close specific session
+        - close_session(all: true) - close all sessions
+      INSTRUCTIONS
+    end
+
+    def setup_signal_handlers
+      %w[INT TERM].each do |signal|
+        Signal.trap(signal) do
+          # Can't call complex code (mutex) from trap context
+          # Just raise Interrupt to let the main thread handle cleanup
+          Thread.main.raise(Interrupt)
+        end
+      end
+    end
+
+    def log(level, message)
+      return if should_suppress_log?(level)
+
+      timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S')
+      warn "[#{timestamp}] [#{level.upcase}] #{message}"
+    end
+
+    def should_suppress_log?(level)
+      levels = %i[debug info warn error]
+      current_level_index = levels.index(@config.error_level) || 2
+      message_level_index = levels.index(level) || 0
+      message_level_index < current_level_index
+    end
+  end
+end

data/lib/crucible/session_manager.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'ferrum'
+
+module Crucible
+  # Manages multiple named browser sessions
+  #
+  # Thread-safe session management with lazy browser initialization.
+  # Each session maintains its own Ferrum::Browser instance.
+  # Supports per-session stealth mode settings.
+  #
+  # @example
+  #   manager = SessionManager.new(config)
+  #   page = manager.page("my-session")
+  #   page.go_to("https://example.com")
+  #   manager.close("my-session")
+  #
+  class SessionManager
+    # Session metadata
+    SessionInfo = Struct.new(:browser, :stealth, :stealth_enabled, keyword_init: true)
+
+    # @param config [Configuration] the server configuration
+    def initialize(config)
+      @config = config
+      @sessions = {}
+      @mutex = Mutex.new
+    end
+
+    # Gets or creates a session by name, returning the browser
+    # @param name [String] session name (default: "default")
+    # @return [Ferrum::Browser]
+    def get_or_create(name = 'default')
+      @mutex.synchronize do
+        @sessions[name] ||= create_session
+        @sessions[name].browser
+      end
+    end
+
+    # Gets an existing session by name
+    # @param name [String] session name
+    # @return [Ferrum::Browser]
+    # @raise [SessionNotFoundError] if session doesn't exist
+    def get(name)
+      info = @mutex.synchronize { @sessions[name] }
+      raise SessionNotFoundError, "Session '#{name}' not found. Use get_or_create or navigate first." unless info
+
+      info.browser
+    end
+
+    # Convenience method to get the page for a session
+    # @param name [String] session name (default: "default")
+    # @return [Ferrum::Page]
+    def page(name = 'default')
+      browser = get_or_create(name)
+      browser.page || browser.create_page
+    end
+
+    # Creates a new named session
+    # @param name [String] session name
+    # @return [Ferrum::Browser]
+    # @raise [Error] if session already exists
+    def create(name)
+      @mutex.synchronize do
+        raise Error, "Session '#{name}' already exists" if @sessions.key?(name)
+
+        @sessions[name] = create_session
+        @sessions[name].browser
+      end
+    end
+
+    # Closes a session and quits its browser
+    # @param name [String] session name
+    # @return [Boolean] true if session was closed, false if not found
+    def close(name)
+      info = @mutex.synchronize { @sessions.delete(name) }
+      return false unless info
+
+      info.browser.quit
+      true
+    rescue Ferrum::Error
+      # Browser may already be dead
+      true
+    end
+
+    # Closes all sessions
+    def close_all
+      sessions = @mutex.synchronize do
+        result = @sessions.values
+        @sessions.clear
+        result
+      end
+
+      sessions.each do |info|
+        info.browser.quit
+      rescue Ferrum::Error
+        # Ignore errors during shutdown
+      end
+    end
+
+    # Lists all active session names
+    # @return [Array<String>]
+    def list
+      @mutex.synchronize { @sessions.keys.dup }
+    end
+
+    # Checks if a session exists
+    # @param name [String] session name
+    # @return [Boolean]
+    def exists?(name)
+      @mutex.synchronize { @sessions.key?(name) }
+    end
+
+    # Returns the count of active sessions
+    # @return [Integer]
+    def count
+      @mutex.synchronize { @sessions.size }
+    end
+
+    # Enable stealth mode for a session
+    # @param name [String] session name
+    # @param profile [Symbol] stealth profile (:minimal, :moderate, :maximum)
+    # @return [Boolean] true if stealth was enabled
+    def enable_stealth(name, profile: nil)
+      info = @mutex.synchronize { @sessions[name] }
+      raise SessionNotFoundError, "Session '#{name}' not found" unless info
+
+      profile ||= @config.stealth_profile
+      stealth = Stealth.new(profile: profile, enabled: true, locale: @config.stealth_locale)
+
+      # Apply stealth to the browser
+      stealth.apply(info.browser)
+
+      # Update session metadata
+      @mutex.synchronize do
+        @sessions[name] = SessionInfo.new(
+          browser: info.browser,
+          stealth: stealth,
+          stealth_enabled: true
+        )
+      end
+
+      true
+    end
+
+    # Disable stealth mode for a session
+    # Note: This won't undo already-applied evasions, but prevents new ones
+    # @param name [String] session name
+    # @return [Boolean] true if stealth was disabled
+    def disable_stealth(name)
+      info = @mutex.synchronize { @sessions[name] }
+      raise SessionNotFoundError, "Session '#{name}' not found" unless info
+
+      @mutex.synchronize do
+        @sessions[name] = SessionInfo.new(
+          browser: info.browser,
+          stealth: info.stealth,
+          stealth_enabled: false
+        )
+      end
+
+      true
+    end
+
+    # Check if stealth is enabled for a session
+    # @param name [String] session name
+    # @return [Boolean]
+    def stealth_enabled?(name)
+      info = @mutex.synchronize { @sessions[name] }
+      return false unless info
+
+      info.stealth_enabled
+    end
+
+    # Get stealth info for a session
+    # @param name [String] session name
+    # @return [Hash] stealth status and profile
+    def stealth_info(name)
+      info = @mutex.synchronize { @sessions[name] }
+      raise SessionNotFoundError, "Session '#{name}' not found" unless info
+
+      {
+        enabled: info.stealth_enabled,
+        profile: info.stealth&.profile&.to_s
+      }
+    end
+
+    private
+
+    def create_session
+      browser = create_browser
+      stealth = @config.stealth
+
+      # Apply stealth if enabled in config
+      stealth.apply(browser) if @config.stealth_enabled
+
+      SessionInfo.new(
+        browser: browser,
+        stealth: stealth,
+        stealth_enabled: @config.stealth_enabled
+      )
+    rescue Ferrum::Error => e
+      raise BrowserError, "Failed to create browser: #{e.message}"
+    end
+
+    def create_browser
+      Ferrum::Browser.new(@config.browser_options)
+    end
+  end
+end

data/lib/crucible/stealth/evasions/chrome_app.js

@@ -0,0 +1,75 @@
+/**
+ * Evasion: chrome.app
+ * Mock the chrome.app object that exists in headed Chrome.
+ */
+(function() {
+  'use strict';
+
+  if (!window.chrome) {
+    Object.defineProperty(window, 'chrome', {
+      writable: true,
+      enumerable: true,
+      configurable: false,
+      value: {}
+    });
+  }
+
+  if ('app' in window.chrome) {
+    return; // Already exists
+  }
+
+  const makeError = {
+    ErrorInInvocation: fn => {
+      const err = new TypeError(`Error in invocation of app.${fn}()`);
+      return err;
+    }
+  };
+
+  const STATIC_DATA = {
+    isInstalled: false,
+    InstallState: {
+      DISABLED: 'disabled',
+      INSTALLED: 'installed',
+      NOT_INSTALLED: 'not_installed'
+    },
+    RunningState: {
+      CANNOT_RUN: 'cannot_run',
+      READY_TO_RUN: 'ready_to_run',
+      RUNNING: 'running'
+    }
+  };
+
+  window.chrome.app = {
+    ...STATIC_DATA,
+
+    get isInstalled() {
+      return false;
+    },
+
+    getDetails: function getDetails() {
+      if (arguments.length) {
+        throw makeError.ErrorInInvocation('getDetails');
+      }
+      return null;
+    },
+
+    getIsInstalled: function getIsInstalled() {
+      if (arguments.length) {
+        throw makeError.ErrorInInvocation('getIsInstalled');
+      }
+      return false;
+    },
+
+    runningState: function runningState() {
+      if (arguments.length) {
+        throw makeError.ErrorInInvocation('runningState');
+      }
+      return 'cannot_run';
+    }
+  };
+
+  // Patch toString for native appearance
+  if (window._stealthUtils) {
+    window._stealthUtils.patchToStringNested(window.chrome.app);
+  }
+})();

data/lib/crucible/stealth/evasions/chrome_csi.js

@@ -0,0 +1,33 @@
+/**
+ * Evasion: chrome.csi
+ * Mock the chrome.csi function that exists in headed Chrome.
+ */
+(function() {
+  'use strict';
+
+  if (!window.chrome) {
+    Object.defineProperty(window, 'chrome', {
+      writable: true,
+      enumerable: true,
+      configurable: false,
+      value: {}
+    });
+  }
+
+  if ('csi' in window.chrome) {
+    return; // Already exists
+  }
+
+  window.chrome.csi = function csi() {
+    return {
+      onloadT: Date.now(),
+      startE: Date.now(),
+      pageT: Math.random() * 1000 + 100,
+      tran: 15
+    };
+  };
+
+  if (window._stealthUtils) {
+    window._stealthUtils.patchToString(window.chrome.csi);
+  }
+})();

data/lib/crucible/stealth/evasions/chrome_load_times.js

@@ -0,0 +1,44 @@
+/**
+ * Evasion: chrome.loadTimes
+ * Mock the chrome.loadTimes function that exists in headed Chrome.
+ */
+(function() {
+  'use strict';
+
+  if (!window.chrome) {
+    Object.defineProperty(window, 'chrome', {
+      writable: true,
+      enumerable: true,
+      configurable: false,
+      value: {}
+    });
+  }
+
+  if ('loadTimes' in window.chrome) {
+    return; // Already exists
+  }
+
+  window.chrome.loadTimes = function loadTimes() {
+    const now = Date.now() / 1000;
+    const rand = Math.random();
+    return {
+      commitLoadTime: now - rand,
+      connectionInfo: 'http/1.1',
+      finishDocumentLoadTime: now - rand + 0.1,
+      finishLoadTime: now - rand + 0.2,
+      firstPaintAfterLoadTime: 0,
+      firstPaintTime: now - rand + 0.05,
+      navigationType: 'Other',
+      npnNegotiatedProtocol: 'unknown',
+      requestTime: now - rand - 0.1,
+      startLoadTime: now - rand,
+      wasAlternateProtocolAvailable: false,
+      wasFetchedViaSpdy: false,
+      wasNpnNegotiated: false
+    };
+  };
+
+  if (window._stealthUtils) {
+    window._stealthUtils.patchToString(window.chrome.loadTimes);
+  }
+})();