factorix 0.5.0

data/lib/factorix/transfer/uploader.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "dry/events"
+require "securerandom"
+require "uri"
+
+module Factorix
+  module Transfer
+    # File uploader with automatic retry
+    #
+    # Uploads files to given URLs using HTTP multipart/form-data.
+    # Uses Transfer::HTTP for the actual upload with event-driven progress notification.
+    class Uploader
+      # MIME type mapping with default fallback
+      MIME_TYPES = Hash.new("application/octet-stream").merge!(
+        ".zip" => "application/zip",
+        ".png" => "image/png",
+        ".jpg" => "image/jpeg",
+        ".jpeg" => "image/jpeg",
+        ".gif" => "image/gif"
+      ).freeze
+      private_constant :MIME_TYPES
+
+      # @!parse
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      #   # @return [HTTP::Client]
+      #   attr_reader :client
+      include Import[:logger, client: :upload_http_client]
+      include Dry::Events::Publisher[:uploader]
+
+      register_event("upload.started")
+      register_event("upload.progress")
+      register_event("upload.completed")
+
+      # Upload a file to the given URL with optional form fields
+      #
+      # @param url [URI::HTTPS, String] URL to upload to (HTTPS only)
+      # @param file_path [Pathname] path to the file to upload
+      # @param field_name [String] form field name for the file (default: "file")
+      # @param fields [Hash<String, String>] additional form fields (e.g., metadata)
+      # @param content_type [:auto, String] MIME type (:auto detects from extension)
+      # @return [void]
+      # @raise [URLError] if the URL is not HTTPS
+      # @raise [ConfigurationError] if file doesn't exist
+      # @raise [HTTPClientError] for 4xx errors
+      # @raise [HTTPServerError] for 5xx errors
+      # @raise [HTTPError] for other HTTP errors
+      def upload(url, file_path, field_name: "file", fields: {}, content_type: :auto)
+        url = URI(url) if url.is_a?(String)
+        unless url.is_a?(URI::HTTPS)
+          logger.error("Invalid URL: must be HTTPS", url: url.to_s)
+          raise URLError, "URL must be HTTPS"
+        end
+
+        unless file_path.exist?
+          logger.error("File does not exist", path: file_path.to_s)
+          raise ConfigurationError, "File does not exist: #{file_path}"
+        end
+
+        resolved_content_type = content_type == :auto ? detect_content_type(file_path) : content_type
+        upload_file_with_progress(url, file_path, field_name, fields, resolved_content_type)
+      end
+
+      # Detect MIME type from file extension
+      #
+      # @param file_path [Pathname] file path
+      # @return [String] MIME type
+      private def detect_content_type(file_path) = MIME_TYPES[file_path.extname.downcase]
+
+      private def upload_file_with_progress(url, file_path, field_name, fields, content_type)
+        boundary = generate_boundary
+        file_size = file_path.size
+
+        publish("upload.started", total_size: file_size)
+
+        # Build multipart body parts
+        body_parts = []
+
+        # Add additional form fields first
+        fields.each do |name, value|
+          body_parts << "--#{boundary}\r\n"
+          body_parts << %[Content-Disposition: form-data; name="#{name}"\r\n]
+          body_parts << "\r\n"
+          body_parts << "#{value}\r\n"
+        end
+
+        # Add file field
+        body_parts << "--#{boundary}\r\n"
+        body_parts << %[Content-Disposition: form-data; name="#{field_name}"; filename="#{file_path.basename}"\r\n]
+        body_parts << "Content-Type: #{content_type}\r\n"
+        body_parts << "\r\n"
+
+        # Calculate total size
+        header_size = body_parts.join.bytesize
+        footer_size = "\r\n--#{boundary}--\r\n".bytesize
+        total_size = header_size + file_size + footer_size
+
+        # Build the multipart stream
+        body_stream = build_multipart_stream(body_parts, file_path, boundary)
+
+        # Wrap in progress tracking IO
+        progress_stream = ProgressIO.new(body_stream, total_size) do |uploaded|
+          publish("upload.progress", current_size: uploaded, total_size:)
+        end
+
+        # POST with the multipart stream
+        response = client.post(url, body: progress_stream, headers: {"Content-Length" => total_size.to_s}, content_type: "multipart/form-data; boundary=#{boundary}")
+
+        publish("upload.completed", total_size:)
+        response
+      end
+
+      # Generate a random boundary for multipart/form-data
+      #
+      # @return [String] boundary string
+      private def generate_boundary = "----RubyFormBoundary#{SecureRandom.hex(16)}"
+
+      # Build a multipart stream from body parts, file, and boundary
+      #
+      # @param body_parts [Array<String>] header parts
+      # @param file_path [Pathname] file to upload
+      # @param boundary [String] multipart boundary
+      # @return [IO] combined IO stream
+      private def build_multipart_stream(body_parts, file_path, boundary)
+        header = StringIO.new(body_parts.join)
+        file = file_path.open("rb")
+        footer = StringIO.new("\r\n--#{boundary}--\r\n")
+
+        CombinedIO.new(header, file, footer)
+      end
+
+      # Wrapper IO that tracks read progress
+      class ProgressIO
+        # @param io [IO] underlying IO stream
+        # @param total_size [Integer] total size in bytes
+        # @yield [Integer] current number of bytes read
+        def initialize(io, total_size, &block)
+          @io = io
+          @total_size = total_size
+          @current = 0
+          @callback = block
+        end
+
+        # Read data from underlying IO and track progress
+        #
+        # @param length [Integer, nil] number of bytes to read
+        # @param outbuf [String, nil] output buffer
+        # @return [String, nil] read data or nil at EOF
+        def read(length=nil, outbuf=nil)
+          data = @io.read(length, outbuf)
+          if data
+            @current += data.bytesize
+            @callback&.call(@current)
+          end
+          data
+        end
+
+        # Check if at end of stream
+        #
+        # @return [Boolean] true if at EOF
+        def eof? = @io.eof?
+
+        # Close underlying IO
+        #
+        # @return [void]
+        def close = @io.close
+
+        # Rewind underlying IO
+        #
+        # @return [void]
+        def rewind
+          @io.rewind
+          @current = 0
+        end
+
+        # Get current size
+        #
+        # @return [Integer] total size
+        def size = @total_size
+      end
+
+      # Combined IO that concatenates multiple IO streams
+      class CombinedIO
+        # @param ios [Array<IO>] IO streams to concatenate
+        def initialize(*ios)
+          @ios = ios
+          @index = 0
+        end
+
+        # Read from current IO, advancing to next when exhausted
+        #
+        # @param length [Integer, nil] number of bytes to read
+        # @param outbuf [String, nil] output buffer
+        # @return [String, nil] read data or nil at EOF
+        def read(length=nil, outbuf=nil)
+          return nil if @index >= @ios.size
+
+          data = @ios[@index].read(length, outbuf)
+          if data.nil? || data.empty?
+            @index += 1
+            return read(length, outbuf)
+          end
+          data
+        end
+
+        # Check if all streams are exhausted
+        #
+        # @return [Boolean] true if at EOF
+        def eof? = @index >= @ios.size
+
+        # Close all IO streams
+        #
+        # @return [void]
+        def close = @ios.each(&:close)
+
+        # Rewind all streams
+        #
+        # @return [void]
+        def rewind
+          @ios.each(&:rewind)
+          @index = 0
+        end
+
+        # Get total size of all streams
+        #
+        # @return [Integer] total size
+        def size = @ios.sum(&:size)
+      end
+    end
+  end
+end

data/lib/factorix/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Factorix
+  VERSION = "0.5.0"
+  public_constant :VERSION
+end

data/lib/factorix.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "dry/auto_inject"
+require "zeitwerk"
+require_relative "factorix/errors"
+require_relative "factorix/version"
+
+# Factorix provides a CLI for Factorio MOD management, settings synchronization,
+# and MOD Portal integration.
+module Factorix
+  loader = Zeitwerk::Loader.for_gem
+  loader.ignore("#{__dir__}/factorix/version.rb")
+  loader.ignore("#{__dir__}/factorix/errors.rb")
+  loader.inflector.inflect(
+    "api" => "API",
+    "api_credential" => "APICredential",
+    "cli" => "CLI",
+    "http" => "HTTP",
+    "info_json" => "InfoJSON",
+    "installed_mod" => "InstalledMOD",
+    "mac_os" => "MacOS",
+    "mod" => "MOD",
+    "mod_download_api" => "MODDownloadAPI",
+    "mod_info" => "MODInfo",
+    "mod_management_api" => "MODManagementAPI",
+    "mod_list" => "MODList",
+    "mod_portal_api" => "MODPortalAPI",
+    "mod_settings" => "MODSettings",
+    "mod_state" => "MODState",
+    "mod_version" => "MODVersion",
+    "mod_version_requirement" => "MODVersionRequirement",
+    "wsl" => "WSL"
+  )
+  loader.setup
+
+  Import = Dry::AutoInject(Application)
+  public_constant :Import
+end

data/sig/dry/auto_inject.rbs

@@ -0,0 +1,15 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Dry
+  module AutoInject
+    interface _Builder
+      def []: (*String dependencies) -> Module
+    end
+
+    def self.new: (untyped container) -> _Builder
+  end
+
+  def self.AutoInject: (untyped container) -> AutoInject::_Builder
+end

data/sig/dry/cli.rbs

@@ -0,0 +1,19 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Dry
+  class CLI
+    def initialize: (Class registry) -> void
+
+    def call: (?Array[String]? arguments) -> void
+  end
+
+  module CLI::Registry
+    def register: (String command_name, Class command_class, **untyped options) -> void
+  end
+
+  class CLI::Command
+    def call: (**untyped) -> void
+  end
+end

data/sig/dry/configurable.rbs

@@ -0,0 +1,13 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Dry
+  module Configurable
+    def setting: (Symbol, ?default: untyped, ?constructor: ^(untyped) -> untyped) ?{ () -> void } -> void
+
+    def config: () -> untyped
+
+    def configure: () { (untyped) -> void } -> void
+  end
+end

data/sig/dry/core/container.rbs

@@ -0,0 +1,17 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Dry
+  module Core
+    module Container
+      module Mixin
+        def register: (Symbol | String, ?memoize: bool) ?{ () -> untyped } -> void
+
+        def resolve: (Symbol | String) -> untyped
+
+        def []: (Symbol | String) -> untyped
+      end
+    end
+  end
+end

data/sig/dry/events/publisher.rbs

@@ -0,0 +1,22 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Dry
+  module Events
+    # Minimal type definition for Dry::Events::Event
+    class Event
+      def []: (Symbol key) -> untyped
+    end
+
+    module Publisher
+      def self.[]: (Symbol id) -> Module
+
+      def subscribe: (untyped listener) -> void
+
+      def publish: (String event_id, **untyped payload) -> void
+
+      def self.register_event: (String event_id) -> void
+    end
+  end
+end

data/sig/dry/logger.rbs

@@ -0,0 +1,16 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Dry
+  module Logger
+    # Minimal type definition for Dry::Logger::Dispatcher
+    class Dispatcher
+      def debug: (String message, **untyped metadata) -> void
+      def info: (String message, **untyped metadata) -> void
+      def warn: (String message, **untyped metadata) -> void
+      def error: (String message, **untyped metadata) -> void
+      def fatal: (String message, **untyped metadata) -> void
+    end
+  end
+end

data/sig/factorix/api/category.rbs

@@ -0,0 +1,15 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module API
+    class Category
+      attr_reader value: String
+      attr_reader name: String
+      attr_reader description: String
+
+      def self.for: (String value) -> Category
+    end
+  end
+end

data/sig/factorix/api/image.rbs

@@ -0,0 +1,15 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module API
+    class Image
+      attr_reader id: String
+      attr_reader thumbnail: URI::HTTPS
+      attr_reader url: URI::HTTPS
+
+      def initialize: (id: String, thumbnail: String, url: String) -> void
+    end
+  end
+end

data/sig/factorix/api/license.rbs

@@ -0,0 +1,20 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module API
+    class License
+      attr_reader id: String
+      attr_reader name: String
+      attr_reader title: String
+      attr_reader description: String
+      attr_reader url: URI::HTTPS
+
+      def self.valid_identifier?: (String value) -> bool
+      def self.identifier_values: () -> Array[String]
+
+      def initialize: (id: String, name: String, title: String, description: String, url: String) -> void
+    end
+  end
+end

data/sig/factorix/api/mod_download_api.rbs

@@ -0,0 +1,18 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module API
+    class MODDownloadAPI
+      BASE_URL: String
+
+      attr_reader downloader: Transfer::Downloader
+      attr_reader logger: Dry::Logger::Dispatcher
+
+      def initialize: (**untyped deps) -> void
+
+      def download: (String download_url, Pathname output, ?expected_sha1: String?) -> void
+    end
+  end
+end

data/sig/factorix/api/mod_info.rbs

@@ -0,0 +1,67 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module API
+    class MODInfo
+      attr_reader name: String
+      attr_reader title: String
+      attr_reader owner: String
+      attr_reader summary: String
+      attr_reader downloads_count: Integer
+      attr_reader category: Category
+      attr_reader score: Float
+      attr_reader thumbnail: URI::HTTPS?
+      attr_reader latest_release: Release?
+      attr_reader releases: Array[Release]
+      attr_reader detail: MODInfo::Detail?
+
+      def initialize: (
+        name: String,
+        title: String,
+        owner: String,
+        ?summary: String?,
+        downloads_count: Integer,
+        ?category: String?,
+        ?score: Float?,
+        ?thumbnail: String?,
+        ?latest_release: Hash[Symbol, untyped]?,
+        ?releases: Array[Hash[Symbol, untyped]]?,
+        **untyped
+      ) -> void
+
+      class Detail
+        attr_reader changelog: String
+        attr_reader created_at: Time
+        attr_reader updated_at: Time
+        attr_reader last_highlighted_at: Time?
+        attr_reader description: String
+        attr_reader source_url: URI::HTTPS?
+        attr_reader homepage: URI | String
+        attr_reader faq: String
+        attr_reader tags: Array[Tag]
+        attr_reader license: License?
+        attr_reader images: Array[Image]
+        attr_reader deprecated: bool
+
+        def initialize: (
+          ?changelog: String?,
+          created_at: String,
+          updated_at: String,
+          ?last_highlighted_at: String?,
+          ?description: String?,
+          ?source_url: String?,
+          homepage: String,
+          ?faq: String?,
+          ?tags: Array[String]?,
+          ?license: Hash[Symbol, untyped]?,
+          ?images: Array[Hash[Symbol, untyped]]?,
+          ?deprecated: bool?
+        ) -> void
+
+        def deprecated?: () -> bool
+      end
+    end
+  end
+end

data/sig/factorix/api/mod_management_api.rbs

@@ -0,0 +1,25 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module API
+    class MODManagementAPI
+      BASE_URL: String
+
+      attr_reader client: HTTP::Client
+      attr_reader uploader: Transfer::Uploader
+      attr_reader logger: Dry::Logger::Dispatcher
+
+      def initialize: (**untyped deps) -> void
+
+      def init_publish: (String mod_name) -> URI::HTTPS
+      def init_upload: (String mod_name) -> URI::HTTPS
+      def finish_upload: (String mod_name, URI::HTTPS upload_url, Pathname | String file_path, **untyped metadata) -> void
+      def edit_details: (String mod_name, **untyped metadata) -> void
+      def init_image_upload: (String mod_name) -> URI::HTTPS
+      def finish_image_upload: (String mod_name, URI::HTTPS upload_url, Pathname | String image_file) -> Hash[String, String]
+      def edit_images: (String mod_name, Array[String] image_ids) -> void
+    end
+  end
+end

data/sig/factorix/api/mod_portal_api.rbs

@@ -0,0 +1,31 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module API
+    class MODPortalAPI
+      BASE_URL: String
+
+      attr_reader logger: Dry::Logger::Dispatcher
+      attr_reader cache: Cache::FileSystem
+      attr_reader client: HTTP::Client
+
+      def get_mods: (
+                      *String namelist,
+                      ?hide_deprecated: bool?,
+                      ?page: Integer?,
+                      ?page_size: (Integer | String)?,
+                      ?sort: ("name" | "created_at" | "updated_at")?,
+                      ?sort_order: ("asc" | "desc")?,
+                      ?version: ("0.13" | "0.14" | "0.15" | "0.16" | "0.17" | "0.18" | "1.0" | "1.1" | "2.0")?
+                    ) -> Hash[String, untyped]
+
+      def get_mod: (String name) -> Hash[String, untyped]
+
+      def get_mod_full: (String name) -> Hash[String, untyped]
+
+      def on_mod_changed: (Dry::Events::Event event) -> void
+    end
+  end
+end

data/sig/factorix/api/release.rbs

@@ -0,0 +1,27 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module API
+    class Release
+      attr_reader download_url: URI::HTTPS
+      attr_reader file_name: String
+      attr_reader info_json: Hash[String, untyped]
+      attr_reader released_at: Time
+      attr_reader version: MODVersion
+      attr_reader sha1: String
+      attr_reader feature_flags: Array[String]
+
+      def initialize: (
+        download_url: String,
+        file_name: String,
+        info_json: Hash[String, untyped],
+        released_at: String,
+        version: String,
+        sha1: String,
+        ?feature_flags: Array[String]
+      ) -> void
+    end
+  end
+end

data/sig/factorix/api/tag.rbs

@@ -0,0 +1,15 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module API
+    class Tag
+      attr_reader value: String
+      attr_reader name: String
+      attr_reader description: String
+
+      def self.for: (String value) -> Tag
+    end
+  end
+end

data/sig/factorix/api.rbs

@@ -0,0 +1,8 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module API
+  end
+end

data/sig/factorix/api_credential.rbs

@@ -0,0 +1,17 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  class APICredential
+    def self.load: () -> APICredential
+
+    def api_key: () -> String
+
+    def inspect: () -> String
+
+    def to_s: () -> String
+
+    def pretty_print: (untyped pp) -> void
+  end
+end