factorix 0.5.0

data/lib/factorix/mod_settings.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module Factorix
+  # Class for handling MOD settings
+  #
+  # MODSettings manages the settings from mod-settings.dat file, which contains
+  # three sections: startup, runtime-global, and runtime-per-user.
+  class MODSettings
+    # Valid section names
+    VALID_SECTIONS = %w[startup runtime-global runtime-per-user].freeze
+    public_constant :VALID_SECTIONS
+
+    # Represents a section in MOD settings
+    class Section
+      include Enumerable
+
+      # Initialize a new section with the given name
+      #
+      # @param name [String] The section name
+      # @raise [MODSettingsError] If the section name is invalid
+      def initialize(name)
+        unless VALID_SECTIONS.include?(name)
+          raise MODSettingsError, "Invalid MOD section name: #{name}"
+        end
+
+        @name = name
+        @settings = {}
+      end
+
+      # Get the section name
+      #
+      # @return [String] The section name
+      attr_reader :name
+
+      # Set a setting value in this section
+      #
+      # @param key [String] The setting key
+      # @param value [Object] The setting value
+      # @return [Object] The setting value
+      def []=(key, value)
+        @settings[key] = value
+      end
+
+      # Get a setting value from this section
+      #
+      # @param key [String] The setting key
+      # @return [Object, nil] The setting value or nil if not found
+      def [](key) = @settings[key]
+
+      # Iterate over all settings in this section
+      #
+      # @yield [key, value] Block to be called for each setting
+      # @yieldparam key [String] The setting key
+      # @yieldparam value [Object] The setting value
+      # @return [Enumerator] If no block is given
+      def each(&)
+        return @settings.to_enum(:each) unless block_given?
+
+        @settings.each(&)
+      end
+
+      # Check if this section has any settings
+      #
+      # @return [Boolean] True if the section has no settings
+      def empty? = @settings.empty?
+
+      # Check if a key exists in this section
+      #
+      # @param key [String] The setting key
+      # @return [Boolean] True if the key exists
+      def key?(key) = @settings.key?(key)
+      alias has_key? key?
+      alias include? key?
+
+      # Get all keys in this section
+      #
+      # @return [Array<String>] Array of all setting keys
+      def keys = @settings.keys
+
+      # Get all values in this section
+      #
+      # @return [Array<Object>] Array of all setting values
+      def values = @settings.values
+
+      # Get the number of settings in this section
+      #
+      # @return [Integer] Number of settings
+      def size = @settings.size
+      alias length size
+
+      # Fetch a setting value with optional default or block
+      #
+      # @param key [String] The setting key
+      # @param default [Object] Default value if key doesn't exist (optional)
+      # @yield [key] Block to compute default value if key doesn't exist
+      # @yieldparam key [String] The missing key
+      # @return [Object] The setting value, default, or block result
+      # @raise [KeyError] If key doesn't exist and no default/block provided
+      def fetch(key, *, &) = @settings.fetch(key, *, &)
+
+      # Convert this section to a Hash
+      #
+      # @return [Hash<String, Object>] Hash of all settings
+      def to_h = @settings.dup
+    end
+
+    # Load MOD settings from file
+    #
+    # @param path [Pathname] Path to the MOD settings file (default: runtime.mod_settings_path)
+    # @return [MODSettings] New MODSettings instance
+    def self.load(path=Application[:runtime].mod_settings_path)
+      path.open("rb") do |io|
+        game_version, sections = load_settings_from_io(io)
+        new(game_version, sections)
+      end
+    end
+
+    # Load settings from IO object
+    #
+    # @param io [IO] IO object to read from
+    # @return [Array<Factorix::GameVersion, Hash<String, Section>>] Game version and hash of sections
+    def self.load_settings_from_io(io)
+      deserializer = SerDes::Deserializer.new(io)
+
+      # 1. Read version (GameVersion)
+      game_version = deserializer.read_game_version
+
+      # 2. Skip a boolean value
+      deserializer.read_bool
+
+      # 3. Read property tree and organize into sections
+      raw_settings = deserializer.read_property_tree
+      sections = organize_into_sections(raw_settings)
+
+      # 4. Check for extra data at the end of file
+      unless deserializer.eof?
+        raise ExtraDataError, "Extra data found at the end of MOD settings file"
+      end
+
+      [game_version, sections]
+    end
+    private_class_method :load_settings_from_io
+
+    # Organize raw settings data into appropriate sections
+    #
+    # @param raw_settings [Hash] Raw settings from deserializer
+    # @return [Hash<String, Section>] Hash of sections
+    # @raise [MODSettingsError] If an invalid section name is encountered
+    def self.organize_into_sections(raw_settings)
+      sections = {}
+      process_raw_settings(raw_settings, sections)
+      ensure_all_sections_exist(sections)
+      sections
+    end
+    private_class_method :organize_into_sections
+
+    # Process raw settings and add them to their respective sections
+    #
+    # @param raw_settings [Hash] Raw settings from deserializer
+    # @param sections [Hash<String, Section>] Hash to populate with sections
+    # @return [void]
+    # @raise [MODSettingsError] If an invalid section name is encountered
+    def self.process_raw_settings(raw_settings, sections)
+      raw_settings.each do |section_name, section_settings|
+        unless VALID_SECTIONS.include?(section_name)
+          raise MODSettingsError, "Invalid MOD section name: #{section_name}"
+        end
+
+        section = sections[section_name] ||= Section.new(section_name)
+        add_settings_to_section(section, section_settings)
+      end
+    end
+    private_class_method :process_raw_settings
+
+    # Add the provided settings to the specified section
+    #
+    # @param section [Section] The section to add settings to
+    # @param section_settings [Hash] The settings to add
+    # @return [void]
+    def self.add_settings_to_section(section, section_settings)
+      section_settings.each do |key, value_hash|
+        # Extract the actual value from the {"value" => X} hash
+        section[key] = value_hash["value"]
+      end
+    end
+    private_class_method :add_settings_to_section
+
+    # Ensure all valid sections exist in the settings, creating empty ones if necessary
+    #
+    # @param sections [Hash<String, Section>] Hash to populate with sections
+    # @return [void]
+    def self.ensure_all_sections_exist(sections)
+      VALID_SECTIONS.each do |section_name|
+        sections[section_name] ||= Section.new(section_name)
+      end
+    end
+    private_class_method :ensure_all_sections_exist
+
+    # Create a new MODSettings instance
+    #
+    # @param game_version [Factorix::GameVersion] Game version
+    # @param sections [Hash<String, Section>] Hash of section name to Section objects
+    def initialize(game_version, sections)
+      @game_version = game_version
+      @sections = sections
+    end
+
+    # Get the game version
+    #
+    # @return [Factorix::GameVersion] Game version
+    attr_reader :game_version
+
+    # Get a section by name from the MOD settings
+    #
+    # @param name [String] The section name
+    # @return [Section] The section
+    # @raise [MODSettingsError] If the section name is invalid
+    # @raise [Factorix::MODSectionNotFoundError] If the section is not found
+    def [](name)
+      unless VALID_SECTIONS.include?(name)
+        raise MODSettingsError, "Invalid MOD section name: #{name}"
+      end
+
+      section = @sections[name]
+      unless section
+        raise MODSectionNotFoundError, "MOD section not found: #{name}"
+      end
+
+      section
+    end
+
+    # Iterate over all sections in the MOD settings
+    #
+    # @yield [section] Block to be called for each section
+    # @yieldparam section [Section] The section
+    # @return [Enumerator] If no block is given
+    def each_section(&)
+      return @sections.values.to_enum(:each) unless block_given?
+
+      @sections.each_value(&)
+    end
+
+    # Save MOD settings to file
+    #
+    # @param path [Pathname] Path to save the MOD settings file (default: runtime.mod_settings_path)
+    # @return [void]
+    def save(path=Application[:runtime].mod_settings_path)
+      path.open("wb") do |file|
+        serializer = SerDes::Serializer.new(file)
+
+        # 1. Write version
+        serializer.write_game_version(@game_version)
+
+        # 2. Write a boolean value (seems to be always false)
+        serializer.write_bool(false)
+
+        # 3. Write property tree
+        settings_hash = build_settings_hash
+        serializer.write_property_tree(settings_hash)
+      end
+    end
+
+    # Build settings hash for serialization
+    #
+    # @return [Hash] Hash of settings organized by section
+    private def build_settings_hash
+      result = {}
+      @sections.each do |section_name, section|
+        section_hash = {}
+        section.each do |key, value|
+          section_hash[key] = {"value" => value}
+        end
+        result[section_name] = section_hash unless section_hash.empty?
+      end
+      result
+    end
+  end
+end

data/lib/factorix/mod_state.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Factorix
+  MODState = Data.define(:enabled, :version)
+
+  # Represents the state of a MOD in a MOD list
+  #
+  # This class encapsulates the enabled/disabled state and version information
+  # for a MOD as it appears in the mod-list.json file.
+  class MODState
+    # Initialize a new MODState
+    #
+    # @param enabled [Boolean] whether the MOD is enabled
+    # @param version [Factorix::MODVersion, nil] the version of the MOD (optional)
+    # @return [void]
+    #
+    # @example Creating a MODState
+    #   state = Factorix::MODState[enabled: true]
+    #   version = Factorix::MODVersion.from_string("1.2.3")
+    #   state = Factorix::MODState[enabled: false, version: version]
+    def initialize(enabled:, version: nil) = super
+
+    # @!attribute [r] enabled
+    #   @return [Boolean] whether the MOD is enabled
+
+    # @!attribute [r] version
+    #   @return [Factorix::MODVersion, nil] the version of the MOD, or nil if the version is not specified
+
+    # Check if the MOD is enabled
+    #
+    # @return [Boolean] true if the MOD is enabled, false otherwise
+    def enabled? = enabled
+  end
+end

data/lib/factorix/mod_version.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Factorix
+  MODVersion = Data.define(:major, :minor, :patch)
+
+  # Represent a 3-component MOD version number (major.minor.patch)
+  #
+  # This class represents Factorio's MOD version format, which uses
+  # 24 bits (3 x 8-bit unsigned integers) to store version information.
+  #
+  # @see https://wiki.factorio.com/Version_string_format
+  class MODVersion
+    include Comparable
+
+    # @!attribute [r] major
+    #   @return [Integer] major version number (0-255)
+    # @!attribute [r] minor
+    #   @return [Integer] minor version number (0-255)
+    # @!attribute [r] patch
+    #   @return [Integer] patch version number (0-255)
+
+    UINT8_MAX = (2**8) - 1
+    private_constant :UINT8_MAX
+
+    class << self
+      private def validate_component(value, name)
+        raise VersionParseError, "#{name} must be an Integer, got #{value.class}" unless value.is_a?(Integer)
+        return if value.between?(0, UINT8_MAX)
+
+        raise VersionParseError, "#{name} must be between 0 and #{UINT8_MAX}, got #{value}"
+      end
+    end
+
+    # Create MODVersion from version string "X.Y.Z" or "X.Y"
+    #
+    # Accepts both 3-part (X.Y.Z) and 2-part (X.Y) version strings.
+    # For 2-part versions, patch defaults to 0.
+    #
+    # @param str [String] version string in "X.Y.Z" or "X.Y" format
+    # @return [MODVersion]
+    # @raise [VersionParseError] if string format is invalid
+    def self.from_string(str)
+      if /\A(\d+)\.(\d+)\.(\d+)\z/ =~ str
+        major = Integer($1, 10)
+        minor = Integer($2, 10)
+        patch = Integer($3, 10)
+      elsif /\A(\d+)\.(\d+)\z/ =~ str
+        major = Integer($1, 10)
+        minor = Integer($2, 10)
+        patch = 0
+      else
+        raise VersionParseError, "invalid version string: #{str.inspect}"
+      end
+
+      validate_component(major, :major)
+      validate_component(minor, :minor)
+      validate_component(patch, :patch)
+
+      new(major:, minor:, patch:)
+    end
+
+    # Create MODVersion from three integers
+    #
+    # @param major [Integer] major version number (0-255)
+    # @param minor [Integer] minor version number (0-255)
+    # @param patch [Integer] patch version number (0-255)
+    # @return [MODVersion]
+    # @raise [VersionParseError] if any component is out of range
+    def self.from_numbers(major, minor, patch)
+      validate_component(major, :major)
+      validate_component(minor, :minor)
+      validate_component(patch, :patch)
+
+      new(major:, minor:, patch:)
+    end
+
+    private_class_method :new, :[]
+
+    # Convert to string representation
+    #
+    # @return [String] Version string in format "X.Y.Z"
+    def to_s = "#{major}.#{minor}.#{patch}"
+
+    # Convert to array of integers
+    #
+    # @return [Array<Integer>] Array containing [major, minor, patch]
+    def to_a = [major, minor, patch].freeze
+
+    # Compare with another MODVersion
+    #
+    # @param other [MODVersion] Version to compare with
+    # @return [Integer, nil] -1, 0, 1 for less than, equal to, greater than; nil if not comparable
+    def <=>(other)
+      return nil unless other.is_a?(MODVersion)
+
+      to_a <=> other.to_a
+    end
+  end
+end

data/lib/factorix/portal.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Factorix
+  # High-level API wrapper for Factorio MOD Portal
+  #
+  # Provides object-oriented interface by converting API responses (Hash)
+  # to typed value objects (MODInfo, Release, etc.).
+  #
+  # @example List all MODs
+  #   portal = Factorix::Portal.new
+  #   mods = portal.list_mods(page_size: 10)
+  #   mods.each { |mod| puts "#{mod.name}: #{mod.title}" }
+  #
+  # @example Get MOD information
+  #   mod = portal.get_mod("space-exploration")
+  #   puts mod.summary
+  #
+  # @example Get full MOD details
+  #   mod = portal.get_mod_full("space-exploration")
+  #   puts mod.detail.description if mod.detail
+  #
+  # @example Download a MOD
+  #   mod = portal.get_mod_full("space-exploration")
+  #   release = mod.releases.max_by(&:released_at)  # Get latest by release date
+  #   portal.download_mod(release, Pathname("downloads/mod.zip")) if release
+  class Portal
+    # @!parse
+    #   # @return [API::MODPortalAPI]
+    #   attr_reader :mod_portal_api
+    #   # @return [API::MODDownloadAPI]
+    #   attr_reader :mod_download_api
+    #   # @return [API::MODManagementAPI]
+    #   attr_reader :mod_management_api
+    #   # @return [Dry::Logger::Dispatcher]
+    #   attr_reader :logger
+    include Import[:mod_portal_api, :mod_download_api, :mod_management_api, :logger]
+
+    # List MODs from the MOD Portal
+    #
+    # @param namelist [Array<String>] MOD names to filter (positional arguments)
+    # @param hide_deprecated [Boolean, nil] hide deprecated MODs
+    # @param page [Integer, nil] page number (1-based)
+    # @param page_size [Integer, nil] number of results per page
+    # @param sort [String, nil] sort field (name, created_at, updated_at)
+    # @param sort_order [String, nil] sort order (asc, desc)
+    # @param version [String, nil] Factorio version filter
+    # @return [Array<API::MODInfo>] array of MODInfo objects
+    def list_mods(...)
+      response = mod_portal_api.get_mods(...)
+      response[:results].map {|mod_data| API::MODInfo[**mod_data] }
+    end
+
+    # Get basic information for a specific MOD (Short API)
+    #
+    # @param name [String] MOD name
+    # @return [API::MODInfo] MODInfo object (without Detail)
+    def get_mod(name)
+      data = mod_portal_api.get_mod(name)
+      API::MODInfo[**data]
+    end
+
+    # Get full information for a specific MOD (Full API)
+    #
+    # @param name [String] MOD name
+    # @return [API::MODInfo] MODInfo object (with Detail if available)
+    def get_mod_full(name)
+      data = mod_portal_api.get_mod_full(name)
+      API::MODInfo[**data]
+    end
+
+    # Download a MOD release file
+    #
+    # @param release [API::Release] release object containing download_url and sha1
+    # @param output [Pathname] output file path
+    # @return [void]
+    # @raise [DigestMismatchError] if SHA1 verification fails
+    def download_mod(release, output)
+      # Extract path from URI::HTTPS
+      download_path = release.download_url.path
+      mod_download_api.download(download_path, output, expected_sha1: release.sha1)
+    end
+
+    # Upload a MOD file to the portal
+    #
+    # Automatically detects if this is a new MOD or update:
+    # - For new MODs: uses init_publish and includes metadata in finish_upload
+    # - For existing MODs: uses init_upload, then updates metadata via edit_details
+    #
+    # @param mod_name [String] the MOD name
+    # @param file_path [Pathname] path to MOD zip file
+    # @param metadata [Hash] optional metadata
+    # @option metadata [String] :description Markdown description
+    # @option metadata [String] :category MOD category
+    # @option metadata [String] :license License identifier
+    # @option metadata [String] :source_url Repository URL
+    # @return [void]
+    # @raise [HTTPClientError] for 4xx errors
+    # @raise [HTTPServerError] for 5xx errors
+    def upload_mod(mod_name, file_path, **metadata)
+      mod_exists = begin
+        get_mod(mod_name)
+        logger.info("Uploading new release to existing MOD", mod: mod_name)
+        true
+      rescue MODNotOnPortalError
+        logger.info("Publishing new MOD", mod: mod_name)
+        false
+      end
+
+      upload_url = mod_exists ? mod_management_api.init_upload(mod_name) : mod_management_api.init_publish(mod_name)
+
+      if mod_exists
+        # For existing MODs: upload file, then edit metadata separately
+        mod_management_api.finish_upload(mod_name, upload_url, file_path)
+        mod_management_api.edit_details(mod_name, **metadata) unless metadata.empty?
+      else
+        # For new MODs: upload file with metadata
+        mod_management_api.finish_upload(mod_name, upload_url, file_path, **metadata)
+      end
+
+      logger.info("Upload completed successfully", mod: mod_name)
+    end
+
+    # Edit MOD metadata without uploading new file
+    #
+    # @param mod_name [String] the MOD name
+    # @param metadata [Hash] metadata to update
+    # @option metadata [String] :description Markdown description
+    # @option metadata [String] :summary Brief description
+    # @option metadata [String] :title MOD title
+    # @option metadata [String] :category MOD category
+    # @option metadata [Array<String>] :tags Array of tags
+    # @option metadata [String] :license License identifier
+    # @option metadata [String] :homepage Homepage URL
+    # @option metadata [String] :source_url Repository URL
+    # @option metadata [String] :faq FAQ text
+    # @option metadata [Boolean] :deprecated Deprecation flag
+    # @return [void]
+    # @raise [MODSettingsError] if no metadata provided
+    # @raise [HTTPClientError] for 4xx errors
+    # @raise [HTTPServerError] for 5xx errors
+    def edit_mod(mod_name, **metadata)
+      raise MODSettingsError, "No metadata provided" if metadata.empty?
+
+      logger.info("Editing MOD metadata", mod: mod_name, fields: metadata.keys)
+      mod_management_api.edit_details(mod_name, **metadata)
+      logger.info("Metadata updated successfully", mod: mod_name)
+    end
+
+    # Add an image to a MOD
+    #
+    # @param mod_name [String] the MOD name
+    # @param image_file [Pathname] path to image file
+    # @return [API::Image] the uploaded image info
+    # @raise [HTTPClientError] for 4xx errors
+    # @raise [HTTPServerError] for 5xx errors
+    def add_mod_image(mod_name, image_file)
+      logger.info("Adding image to MOD", mod: mod_name, file: image_file.to_s)
+
+      # Initialize upload
+      upload_url = mod_management_api.init_image_upload(mod_name)
+
+      # Upload image
+      response_data = mod_management_api.finish_image_upload(mod_name, upload_url, image_file)
+
+      # Convert response to API::Image
+      image = API::Image[**response_data.transform_keys(&:to_sym)]
+
+      logger.info("Image added successfully", mod: mod_name, image_id: image.id)
+      image
+    end
+
+    # Edit MOD's image list
+    #
+    # @param mod_name [String] the MOD name
+    # @param image_ids [Array<String>] array of image IDs in desired order
+    # @return [void]
+    # @raise [HTTPClientError] for 4xx errors
+    # @raise [HTTPServerError] for 5xx errors
+    def edit_mod_images(mod_name, image_ids)
+      logger.info("Editing MOD images", mod: mod_name, image_count: image_ids.size)
+      mod_management_api.edit_images(mod_name, image_ids)
+      logger.info("Images updated successfully", mod: mod_name)
+    end
+  end
+end

data/lib/factorix/progress/download_handler.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Progress
+    # Download event handler for progress presenters
+    #
+    # This class listens to download events and updates a progress presenter accordingly.
+    class DownloadHandler
+      # Create a new download handler
+      #
+      # @param presenter [Presenter, PresenterAdapter] progress presenter to update
+      def initialize(presenter) = @presenter = presenter
+
+      # Handle download started event
+      #
+      # @param event [Dry::Events::Event] event with total_size payload
+      # @return [void]
+      def on_download_started(event) = @presenter.start(total: event[:total_size])
+
+      # Handle download progress event
+      #
+      # @param event [Dry::Events::Event] event with current_size payload
+      # @return [void]
+      def on_download_progress(event) = @presenter.update(event[:current_size])
+
+      # Handle download completed event
+      #
+      # @param event [Dry::Events::Event] event with total_size payload
+      # @return [void]
+      def on_download_completed(_event) = @presenter.finish
+
+      # Handle cache hit event
+      #
+      # @param event [Dry::Events::Event] event with url, output, and total_size payload
+      # @return [void]
+      def on_cache_hit(event)
+        total_size = event.payload.fetch(:total_size, 1)
+
+        # Start and complete immediately for cache hits
+        @presenter.start(total: total_size)
+        @presenter.update(total_size)
+        @presenter.finish
+      end
+    end
+  end
+end

data/lib/factorix/progress/multi_presenter.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "tty-progressbar"
+
+module Factorix
+  module Progress
+    # Multi-progress presenter implementation
+    #
+    # This class provides a multi-progress presentation interface using tty-progressbar.
+    # It manages multiple progress bars that can be updated concurrently.
+    class MultiPresenter
+      # Create a new multi-progress presenter
+      #
+      # @param title [String] title of the multi-progress presenter
+      # @param output [IO] output stream for the progress presenter
+      def initialize(title: "Progress", output: $stderr)
+        @title = title
+        @output = output
+        @multi = TTY::ProgressBar::Multi.new(@title, output: @output, style: {top: "", middle: "", bottom: ""})
+        @presenters = {}
+        @mutex = Mutex.new
+      end
+
+      # Register a new progress presenter
+      #
+      # @param name [String, Symbol] unique identifier for this progress presenter
+      # @param title [String] title for this specific progress presenter
+      # @return [PresenterAdapter] adapter wrapping the TTY::ProgressBar
+      def register(name, title:)
+        @mutex.synchronize do
+          tty_bar = @multi.register("#{title} [:bar] :percent :byte/:total_byte")
+          adapter = PresenterAdapter.new(tty_bar, @mutex)
+          @presenters[name] = adapter
+          adapter
+        end
+      end
+
+      # Get a registered presenter by name
+      #
+      # @param name [String, Symbol] the identifier used during registration
+      # @return [PresenterAdapter, nil] the presenter adapter or nil if not found
+      def [](name) = @presenters[name]
+    end
+  end
+end