factorix 0.6.0 → 0.8.0

data/lib/factorix/cli/commands/download.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      # Download Factorio game files from the official download API
+      class Download < Base
+        # @!parse
+        #   # @return [Dry::Logger::Dispatcher]
+        #   attr_reader :logger
+        #   # @return [Runtime]
+        #   attr_reader :runtime
+        #   # @return [API::GameDownloadAPI]
+        #   attr_reader :game_download_api
+        include Import[:logger, :runtime, :game_download_api]
+
+        # Platform mapping from Runtime to API platform identifier
+        PLATFORM_MAP = {
+          "MacOS" => "osx",
+          "Linux" => "linux64",
+          "Windows" => "win64",
+          "WSL" => "win64"
+        }.freeze
+        private_constant :PLATFORM_MAP
+
+        desc "Download Factorio game files"
+
+        argument :version, required: false, default: "latest", desc: "Version (e.g., 2.0.73, latest)"
+
+        option :build, aliases: ["-b"], default: "alpha", values: API::GameDownloadAPI::BUILDS, desc: "Build type"
+        option :platform, aliases: ["-p"], values: API::GameDownloadAPI::PLATFORMS, desc: "Platform (default: auto-detect)"
+        option :channel, aliases: ["-c"], default: "stable", values: API::GameDownloadAPI::CHANNELS, desc: "Release channel"
+        option :directory, aliases: ["-d"], default: ".", desc: "Download directory"
+        option :output, aliases: ["-o"], desc: "Output filename (default: from server)"
+
+        example [
+          "                           # Download latest stable version (auto-detect platform)",
+          "2.0.73                     # Download specific version",
+          "--build expansion          # Download expansion build",
+          "--build headless -p linux64 # Download headless server for Linux",
+          "--channel experimental     # Download experimental release",
+          "-o factorio-server.tar.xz  # Specify output filename"
+        ]
+
+        # Execute the download command
+        #
+        # @param version [String] Version to download
+        # @param build [String] Build type
+        # @param platform [String, nil] Platform (nil for auto-detect)
+        # @param channel [String] Release channel
+        # @param directory [String] Download directory
+        # @param output [String, nil] Output filename
+        # @return [void]
+        def call(version: "latest", build: "alpha", platform: nil, channel: "stable", directory: ".", output: nil, **)
+          platform ||= detect_platform
+          resolved_version = resolve_version(version, channel, build)
+
+          download_dir = Pathname(directory).expand_path
+          raise DirectoryNotFoundError, "Download directory does not exist: #{download_dir}" unless download_dir.exist?
+
+          filename = output || resolve_filename(resolved_version, build, platform)
+          output_path = download_dir / filename
+
+          say "Downloading Factorio #{resolved_version} (#{build}/#{platform})...", prefix: :info
+
+          download_game(resolved_version, build, platform, output_path)
+
+          say "Downloaded to #{output_path}", prefix: :success
+        end
+
+        # Detect platform from Runtime
+        #
+        # @return [String] Platform identifier
+        private def detect_platform
+          runtime_class = runtime.class.name.split("::").last
+          platform = PLATFORM_MAP[runtime_class]
+          raise UnsupportedPlatformError, "Cannot auto-detect platform for #{runtime_class}" unless platform
+
+          logger.debug("Auto-detected platform", platform:)
+          platform
+        end
+
+        # Minimum supported major version
+        MINIMUM_MAJOR_VERSION = 2
+        private_constant :MINIMUM_MAJOR_VERSION
+
+        # Resolve version, handling "latest" by fetching from API
+        #
+        # @param version [String] Version or "latest"
+        # @param channel [String] Release channel
+        # @param build [String] Build type
+        # @return [String] Resolved version
+        # @raise [InvalidArgumentError] if version is invalid or < 2.0
+        private def resolve_version(version, channel, build)
+          resolved = if version == "latest"
+                       v = game_download_api.latest_version(channel:, build:)
+                       raise InvalidArgumentError, "No #{channel} version available for #{build}" unless v
+
+                       logger.debug("Resolved latest version", channel:, build:, version: v)
+                       v
+                     else
+                       version
+                     end
+
+          validate_version!(resolved)
+          resolved
+        end
+
+        # Validate version format and minimum version requirement
+        #
+        # @param version [String] Version string
+        # @return [void]
+        # @raise [InvalidArgumentError] if version is invalid or < 2.0
+        private def validate_version!(version)
+          game_version = GameVersion.from_string(version)
+
+          return if game_version.major >= MINIMUM_MAJOR_VERSION
+
+          raise InvalidArgumentError, "Version #{version} is not supported. Minimum version is #{MINIMUM_MAJOR_VERSION}.0.0"
+        rescue VersionParseError => e
+          raise InvalidArgumentError, "Invalid version format: #{e.message}"
+        end
+
+        # Resolve filename by making HEAD request
+        #
+        # @param version [String] Version
+        # @param build [String] Build type
+        # @param platform [String] Platform
+        # @return [String] Filename
+        private def resolve_filename(version, build, platform)
+          game_download_api.resolve_filename(version:, build:, platform:)
+        end
+
+        # Download the game with progress tracking
+        #
+        # @param version [String] Version
+        # @param build [String] Build type
+        # @param platform [String] Platform
+        # @param output_path [Pathname] Output file path
+        # @return [void]
+        private def download_game(version, build, platform, output_path)
+          presenter = Progress::Presenter.new(title: output_path.basename.to_s, output: err)
+          handler = Progress::DownloadHandler.new(presenter)
+
+          game_download_api.download(version:, build:, platform:, output: output_path, handler:)
+        end
+      end
+    end
+  end
+end

data/lib/factorix/cli/commands/download_support.rb

@@ -97,18 +97,13 @@ module Factorix
 
           futures = targets.map {|target|
             Concurrent::Future.execute(executor: pool) do
-              thread_portal = Container[:portal]
-              thread_downloader = thread_portal.mod_download_api.downloader
-
               presenter = multi_presenter.register(
                 target[:mod].name,
                 title: target[:release].file_name
               )
               handler = Progress::DownloadHandler.new(presenter)
 
-              thread_downloader.subscribe(handler)
-              thread_portal.download_mod(target[:release], target[:output_path])
-              thread_downloader.unsubscribe(handler)
+              portal.download_mod(target[:release], target[:output_path], handler:)
             end
           }
 

data/lib/factorix/cli/commands/mod/download.rb

@@ -10,14 +10,13 @@ module Factorix
         # Download MOD files from Factorio MOD Portal
         class Download < Base
           include DownloadSupport
+          include PortalSupport
           # @!parse
-          #   # @return [Portal]
-          #   attr_reader :portal
           #   # @return [Dry::Logger::Dispatcher]
           #   attr_reader :logger
           #   # @return [Runtime]
           #   attr_reader :runtime
-          include Import[:portal, :logger, :runtime]
+          include Import[:logger, :runtime]
 
           desc "Download MOD files from Factorio MOD Portal"
 

data/lib/factorix/cli/commands/mod/edit.rb

@@ -6,10 +6,7 @@ module Factorix
       module MOD
         # Edit MOD metadata on Factorio MOD Portal
         class Edit < Base
-          # @!parse
-          #   # @return [Portal]
-          #   attr_reader :portal
-          include Import[:portal]
+          include PortalSupport
 
           desc "Edit MOD metadata on Factorio MOD Portal"
 

data/lib/factorix/cli/commands/mod/image/add.rb

@@ -7,10 +7,7 @@ module Factorix
         module Image
           # Add an image to a MOD on Factorio MOD Portal
           class Add < Base
-            # @!parse
-            #   # @return [Portal]
-            #   attr_reader :portal
-            include Import[:portal]
+            include PortalSupport
 
             desc "Add an image to a MOD"
 

data/lib/factorix/cli/commands/mod/image/edit.rb

@@ -7,10 +7,7 @@ module Factorix
         module Image
           # Edit MOD's image list on Factorio MOD Portal
           class Edit < Base
-            # @!parse
-            #   # @return [Portal]
-            #   attr_reader :portal
-            include Import[:portal]
+            include PortalSupport
 
             desc "Edit MOD's image list (reorder/remove images)"
 

data/lib/factorix/cli/commands/mod/image/list.rb

@@ -7,10 +7,7 @@ module Factorix
         module Image
           # List images for a MOD on Factorio MOD Portal
           class List < Base
-            # @!parse
-            #   # @return [Portal]
-            #   attr_reader :portal
-            include Import[:portal]
+            include PortalSupport
 
             desc "List images for a MOD"
 

data/lib/factorix/cli/commands/mod/install.rb

@@ -14,15 +14,14 @@ module Factorix
           backup_support!
 
           include DownloadSupport
+          include PortalSupport
 
           # @!parse
-          #   # @return [Portal]
-          #   attr_reader :portal
           #   # @return [Dry::Logger::Dispatcher]
           #   attr_reader :logger
           #   # @return [Factorix::Runtime]
           #   attr_reader :runtime
-          include Import[:portal, :logger, :runtime]
+          include Import[:logger, :runtime]
 
           desc "Install MOD(s) from Factorio MOD Portal (downloads to MOD directory and enables)"
 

data/lib/factorix/cli/commands/mod/list.rb

@@ -147,7 +147,7 @@ module Factorix
               enabled = mod_list.exist?(mod) && mod_list.enabled?(mod)
               error = error_map[mod.name]
 
-              MODInfo.new(name: mod.name, version: display_version, enabled:, error:, latest_version: nil)
+              MODInfo[name: mod.name, version: display_version, enabled:, error:, latest_version: nil]
             }
           end
 
@@ -256,13 +256,13 @@ module Factorix
           private def fetch_latest_version_for_mod(info)
             portal_info = mod_portal_api.get_mod(info.name)
             latest = portal_info[:releases]&.map {|r| MODVersion.from_string(r[:version]) }&.max
-            MODInfo.new(
+            MODInfo[
               name: info.name,
               version: info.version,
               enabled: info.enabled,
               error: info.error,
               latest_version: latest
-            )
+            ]
           rescue MODNotOnPortalError
             logger.debug("MOD not found on portal", mod: info.name)
             info

data/lib/factorix/cli/commands/mod/search.rb

@@ -8,12 +8,11 @@ module Factorix
       module MOD
         # Search MODs on Factorio MOD Portal
         class Search < Base
+          include PortalSupport
           # @!parse
-          #   # @return [Portal]
-          #   attr_reader :portal
           #   # @return [Runtime]
           #   attr_reader :runtime
-          include Import[:portal, :runtime]
+          include Import[:runtime]
 
           desc "Search MOD(s) on Factorio MOD Portal"
 

data/lib/factorix/cli/commands/mod/show.rb

@@ -20,11 +20,10 @@ module Factorix
           INCOMPATIBLE_MOD_STYLE = TIntMe[:red]
           private_constant :INCOMPATIBLE_MOD_STYLE
           # @!parse
-          #   # @return [Portal]
-          #   attr_reader :portal
           #   # @return [Runtime]
           #   attr_reader :runtime
-          include Import[:portal, :runtime]
+          include Import[:runtime]
+          include PortalSupport
 
           desc "Show MOD details from Factorio MOD Portal"
 

data/lib/factorix/cli/commands/mod/sync.rb

@@ -14,15 +14,14 @@ module Factorix
           backup_support!
 
           include DownloadSupport
+          include PortalSupport
 
           # @!parse
-          #   # @return [Portal]
-          #   attr_reader :portal
           #   # @return [Dry::Logger::Dispatcher]
           #   attr_reader :logger
           #   # @return [Factorix::Runtime]
           #   attr_reader :runtime
-          include Import[:portal, :logger, :runtime]
+          include Import[:logger, :runtime]
 
           desc "Sync MOD states and startup settings from a save file"
 

data/lib/factorix/cli/commands/mod/update.rb

@@ -13,14 +13,14 @@ module Factorix
           require_game_stopped!
           backup_support!
 
+          include PortalSupport
+          include DownloadSupport
           # @!parse
-          #   # @return [Portal]
-          #   attr_reader :portal
           #   # @return [Dry::Logger::Dispatcher]
           #   attr_reader :logger
           #   # @return [Factorix::Runtime]
           #   attr_reader :runtime
-          include Import[:portal, :logger, :runtime]
+          include Import[:logger, :runtime]
 
           desc "Update MOD(s) to their latest versions"
 
@@ -141,7 +141,7 @@ module Factorix
               mod:,
               mod_info:,
               current_version:,
-              latest_release:,
+              release: latest_release,
               output_path: runtime.mod_dir / latest_release.file_name
             }
           rescue MODNotOnPortalError
@@ -156,7 +156,7 @@ module Factorix
           private def show_plan(targets)
             say "Planning to update #{targets.size} MOD(s):", prefix: :info
             targets.each do |target|
-              say "  - #{target[:mod]}: #{target[:current_version]} -> #{target[:latest_release].version}"
+              say "  - #{target[:mod]}: #{target[:current_version]} -> #{target[:release].version}"
             end
           end
 
@@ -176,46 +176,13 @@ module Factorix
                 current_enabled = mod_list.enabled?(mod)
                 mod_list.remove(mod)
                 mod_list.add(mod, enabled: current_enabled)
-                say "Updated #{mod} to #{target[:latest_release].version}", prefix: :success
+                say "Updated #{mod} to #{target[:release].version}", prefix: :success
               else
                 mod_list.add(mod, enabled: true)
                 say "Added #{mod} to mod-list.json", prefix: :success
               end
             end
           end
-
-          # Download MODs in parallel
-          #
-          # @param targets [Array<Hash>] Update targets
-          # @param jobs [Integer] Number of parallel jobs
-          # @return [void]
-          private def download_mods(targets, jobs)
-            multi_presenter = Progress::MultiPresenter.new(title: "\u{1F4E5}\u{FE0E} Downloads", output: err)
-
-            pool = Concurrent::FixedThreadPool.new(jobs)
-
-            futures = targets.map {|target|
-              Concurrent::Future.execute(executor: pool) do
-                thread_portal = Container[:portal]
-                thread_downloader = thread_portal.mod_download_api.downloader
-
-                presenter = multi_presenter.register(
-                  target[:mod].name,
-                  title: target[:latest_release].file_name
-                )
-                handler = Progress::DownloadHandler.new(presenter)
-
-                thread_downloader.subscribe(handler)
-                thread_portal.download_mod(target[:latest_release], target[:output_path])
-                thread_downloader.unsubscribe(handler)
-              end
-            }
-
-            futures.each(&:wait!)
-          ensure
-            pool&.shutdown
-            pool&.wait_for_termination
-          end
         end
       end
     end

data/lib/factorix/cli/commands/mod/upload.rb

@@ -6,10 +6,7 @@ module Factorix
       module MOD
         # Upload MOD to Factorio MOD Portal (handles both new and update)
         class Upload < Base
-          # @!parse
-          #   # @return [Portal]
-          #   attr_reader :portal
-          include Import[:portal]
+          include PortalSupport
 
           desc "Upload MOD to Factorio MOD Portal (handles both new and update)"
 

data/lib/factorix/cli/commands/portal_support.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      # Provides lazy Portal resolution for CLI commands
+      #
+      # This module defers Portal dependency resolution until first use,
+      # allowing configuration to be loaded before cache backends are resolved.
+      #
+      # @example
+      #   class Show < Base
+      #     include PortalSupport
+      #
+      #     def call(mod_name:, **)
+      #       mod_info = portal.get_mod(mod_name)
+      #     end
+      #   end
+      module PortalSupport
+        # Lazily resolve Portal from Container
+        #
+        # @return [Portal] the portal instance
+        private def portal = @portal ||= Container[:portal]
+      end
+    end
+  end
+end

data/lib/factorix/cli.rb

@@ -17,6 +17,7 @@ module Factorix
     register "man", Commands::Man
     register "launch", Commands::Launch
     register "path", Commands::Path
+    register "download", Commands::Download
     register "completion", Commands::Completion
     register "mod check", Commands::MOD::Check
     register "mod list", Commands::MOD::List

data/lib/factorix/container.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "dry/core"
+require "dry/inflector"
 require "dry/logger"
 
 module Factorix
@@ -13,12 +14,28 @@ module Factorix
   class Container
     extend Dry::Core::Container::Mixin
 
-    # Some items are registered with memoize: false to support independent event handlers
+    INFLECTOR = Dry::Inflector.new do |inflections|
+      inflections.uncountable("redis")
+    end
+    private_constant :INFLECTOR
+
+    # Build a cache instance from configuration.
+    #
+    # @param cache_type [Symbol] cache type (:download, :api, :info_json)
+    # @param config [Dry::Configurable::Config] cache configuration
+    # @return [Cache::Base] cache instance
+    def self.build_cache(cache_type, config)
+      backend = config.backend
+      backend_config = config.public_send(backend).to_h
+      backend_class = Cache.const_get(INFLECTOR.classify(backend.to_s))
+      backend_class.new(cache_type:, ttl: config.ttl, **backend_config)
+    end
+    private_class_method :build_cache
+
+    # :downloader is registered with memoize: false to support independent event handlers
     # for each parallel download task (e.g., progress tracking).
-    # Items registered with memoize: false:
-    # - :downloader (event handlers for progress tracking)
-    # - :mod_download_api (contains :downloader)
-    # - :portal (contains :mod_download_api)
+    # MODDownloadAPI resolves :downloader lazily per download call, allowing
+    # :mod_download_api and :portal to be safely memoized.
 
     # Register runtime detector
     register(:runtime, memoize: true) do
@@ -48,20 +65,17 @@ module Factorix
 
     # Register download cache
     register(:download_cache, memoize: true) do
-      c = Factorix.config.cache.download
-      Cache::FileSystem.new(c.dir, **c.to_h.except(:dir))
+      build_cache(:download, Factorix.config.cache.download)
     end
 
     # Register API cache (with compression for JSON responses)
     register(:api_cache, memoize: true) do
-      c = Factorix.config.cache.api
-      Cache::FileSystem.new(c.dir, **c.to_h.except(:dir))
+      build_cache(:api, Factorix.config.cache.api)
     end
 
     # Register info.json cache (for MOD metadata from ZIP files)
     register(:info_json_cache, memoize: true) do
-      c = Factorix.config.cache.info_json
-      Cache::FileSystem.new(c.dir, **c.to_h.except(:dir))
+      build_cache(:info_json, Factorix.config.cache.info_json)
     end
 
     # Register base HTTP client
@@ -118,10 +132,15 @@ module Factorix
     end
 
     # Register MOD Download API client
-    register(:mod_download_api, memoize: false) do
+    register(:mod_download_api, memoize: true) do
       API::MODDownloadAPI.new
     end
 
+    # Register Game Download API client
+    register(:game_download_api, memoize: true) do
+      API::GameDownloadAPI.new
+    end
+
     # Register API credential (for MOD upload/management)
     register(:api_credential, memoize: true) { APICredential.load }
 
@@ -134,7 +153,7 @@ module Factorix
     end
 
     # Register portal (high-level API wrapper)
-    register(:portal, memoize: false) do
+    register(:portal, memoize: true) do
       Portal.new
     end
   end

data/lib/factorix/dependency/graph/builder.rb

@@ -53,7 +53,7 @@ module Factorix
           version = select_version_for_mod(mod)
           enabled = mod_enabled?(mod)
 
-          node = Node.new(mod:, version:, enabled:, installed: true)
+          node = Node[mod:, version:, enabled:, installed: true]
           graph.add_node(node)
         end
 
@@ -88,7 +88,7 @@ module Factorix
             # Expansion MODs can be disabled, so they must be validated
             next if dependency.mod.base?
 
-            edge = Edge.new(from_mod:, to_mod: dependency.mod, type: dependency.type, version_requirement: dependency.version_requirement)
+            edge = Edge[from_mod:, to_mod: dependency.mod, type: dependency.type, version_requirement: dependency.version_requirement]
             graph.add_edge(edge)
           end
         end

data/lib/factorix/dependency/graph.rb

@@ -75,7 +75,7 @@ module Factorix
           return
         end
 
-        node = Node.new(mod:, version: release.version, enabled: false, installed: false, operation:)
+        node = Node[mod:, version: release.version, enabled: false, installed: false, operation:]
         add_node(node)
 
         dependencies = release.info_json[:dependencies] || []
@@ -85,7 +85,7 @@ module Factorix
           dependency = parser.parse(dep_string)
           next if dependency.mod.base?
 
-          edge = Edge.new(from_mod: mod, to_mod: dependency.mod, type: dependency.type, version_requirement: dependency.version_requirement)
+          edge = Edge[from_mod: mod, to_mod: dependency.mod, type: dependency.type, version_requirement: dependency.version_requirement]
 
           add_edge(edge)
         end

data/lib/factorix/dependency/validation_result.rb

@@ -81,7 +81,7 @@ module Factorix
       # @param mod [Factorix::MOD, nil] Related MOD
       # @param dependency [Factorix::MOD, nil] Dependency MOD
       # @return [void]
-      def add_error(type:, message:, mod: nil, dependency: nil) = @errors << Error.new(type:, message:, mod:, dependency:)
+      def add_error(type:, message:, mod: nil, dependency: nil) = @errors << Error[type:, message:, mod:, dependency:]
 
       # Add a warning
       #
@@ -89,7 +89,7 @@ module Factorix
       # @param message [String] Warning message
       # @param mod [Factorix::MOD, nil] Related MOD
       # @return [void]
-      def add_warning(type:, message:, mod: nil) = @warnings << Warning.new(type:, message:, mod:)
+      def add_warning(type:, message:, mod: nil) = @warnings << Warning[type:, message:, mod:]
 
       # Add a suggestion
       #
@@ -97,7 +97,7 @@ module Factorix
       # @param mod [Factorix::MOD] Related MOD
       # @param version [Factorix::MODVersion] Suggested version
       # @return [void]
-      def add_suggestion(message:, mod:, version:) = @suggestions << Suggestion.new(message:, mod:, version:)
+      def add_suggestion(message:, mod:, version:) = @suggestions << Suggestion[message:, mod:, version:]
 
       # Get all errors
       #

data/lib/factorix/errors.rb

@@ -48,6 +48,9 @@ module Factorix
   class HTTPNotFoundError < HTTPClientError; end
   class HTTPServerError < HTTPError; end
 
+  # Cache lock timeout errors
+  class LockTimeoutError < InfrastructureError; end
+
   # Digest verification errors
   class DigestMismatchError < InfrastructureError; end