factorix 0.5.0

data/lib/factorix/progress/presenter.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "tty-progressbar"
+
+module Factorix
+  module Progress
+    # Progress presenter implementation
+    #
+    # This class provides a simple progress presentation interface using tty-progressbar.
+    class Presenter
+      # Create a new progress presenter
+      #
+      # @param title [String] title of the progress presenter
+      # @param output [IO] output stream for the progress presenter
+      def initialize(title: "Progress", output: $stderr)
+        @title = title
+        @output = output
+        @tty_bar = nil
+      end
+
+      # Start the progress presentation with a specific total
+      #
+      # @param total [Integer] total size/count for progress tracking
+      # @param format [String] progress presenter format string (default: generic format)
+      # @return [void]
+      def start(total: nil, format: nil)
+        format ||= total.nil? ? "#{@title} [:bar] :current" : "#{@title} [:bar] :percent :current/:total"
+        @tty_bar = TTY::ProgressBar.new(
+          format,
+          total:,
+          output: @output,
+          frequency: 1, # Always update (important for testing with StringIO)
+          force: true   # Force output even when not a TTY
+        )
+      end
+
+      # Update the progress presenter to a specific value
+      #
+      # @param current [Integer] current progress value
+      # @return [void]
+      def update(current=nil)
+        if current
+          @tty_bar&.current = current
+        else
+          # For indeterminate progress, just advance
+          @tty_bar&.advance
+        end
+      end
+
+      # Increase the total count dynamically
+      #
+      # @param increment [Integer] amount to add to current total
+      # @return [void]
+      def increase_total(increment)
+        return unless @tty_bar
+
+        current_total = @tty_bar.total || 0
+        @tty_bar.update(total: current_total + increment)
+      end
+
+      # Mark the progress presenter as finished
+      #
+      # @return [void]
+      def finish = @tty_bar&.finish
+    end
+  end
+end

data/lib/factorix/progress/presenter_adapter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Progress
+    # Adapter to make TTY::ProgressBar compatible with Presenter interface
+    #
+    # This adapter wraps a TTY::ProgressBar instance and provides the same
+    # interface as Progress::Presenter, allowing them to be used interchangeably.
+    class PresenterAdapter
+      # Create a new presenter adapter
+      #
+      # @param tty_bar [TTY::ProgressBar] the progress bar to adapt
+      # @param mutex [Mutex] mutex for thread-safe operations
+      def initialize(tty_bar, mutex)
+        @tty_bar = tty_bar
+        @mutex = mutex
+        @started = false
+      end
+
+      # Start the progress presentation
+      #
+      # @param total [Integer] total size/count for progress tracking
+      # @param format [String, nil] format string (ignored, already set in TTY::ProgressBar)
+      # @return [void]
+      def start(total:, format: nil)
+        _ = format # Acknowledge unused parameter
+        @mutex.synchronize do
+          @tty_bar.update(total:) if total
+          @tty_bar.start unless @started
+          @started = true
+        end
+      end
+
+      # Update the progress to a specific value
+      #
+      # @param current [Integer] current progress value
+      # @return [void]
+      def update(current) = @mutex.synchronize { @tty_bar.current = current }
+
+      # Mark the progress as finished
+      #
+      # @return [void]
+      def finish = @mutex.synchronize { @tty_bar.finish }
+    end
+  end
+end

data/lib/factorix/progress/scan_handler.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Progress
+    # Scan event handler for progress presenters
+    #
+    # This class listens to scan events and updates a progress presenter accordingly.
+    class ScanHandler
+      # Create a new scan handler
+      #
+      # @param presenter [Presenter, PresenterAdapter] progress presenter to update
+      def initialize(presenter) = @presenter = presenter
+
+      # Handle scan started event
+      #
+      # @param event [Dry::Events::Event] event with total payload
+      # @return [void]
+      def on_scan_started(event) = @presenter.start(total: event[:total])
+
+      # Handle scan progress event
+      #
+      # @param event [Dry::Events::Event] event with current payload
+      # @return [void]
+      def on_scan_progress(event) = @presenter.update(event[:current])
+
+      # Handle scan completed event
+      #
+      # @param event [Dry::Events::Event] event with total payload
+      # @return [void]
+      def on_scan_completed(_event) = @presenter.finish
+    end
+  end
+end

data/lib/factorix/progress/upload_handler.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Progress
+    # Upload event handler for progress presenters
+    #
+    # This class listens to upload events and updates a progress presenter accordingly.
+    class UploadHandler
+      # Create a new upload handler
+      #
+      # @param presenter [Presenter, PresenterAdapter] progress presenter to update
+      def initialize(presenter) = @presenter = presenter
+
+      # Handle upload started event
+      #
+      # @param event [Dry::Events::Event] event with total_size payload
+      # @return [void]
+      def on_upload_started(event) = @presenter.start(total: event[:total_size], format: "Uploading [:bar] :percent :byte/:total_byte")
+
+      # Handle upload progress event
+      #
+      # @param event [Dry::Events::Event] event with current_size payload
+      # @return [void]
+      def on_upload_progress(event) = @presenter.update(event[:current_size])
+
+      # Handle upload completed event
+      #
+      # @param event [Dry::Events::Event] event with total_size payload
+      # @return [void]
+      def on_upload_completed(_event) = @presenter.finish
+    end
+  end
+end

data/lib/factorix/runtime/base.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Factorix
+  class Runtime
+    # Abstract base class for platform-specific runtime environments
+    #
+    # This class defines the interface that all platform-specific runtime
+    # implementations must provide. It provides common implementations for
+    # derived paths and XDG Base Directory specification support.
+    class Base
+      prepend UserConfigurable
+
+      # Hook called when Base is subclassed
+      #
+      # Automatically prepends UserConfigurable to all subclasses to ensure
+      # configuration support is available across all platform implementations.
+      #
+      # @param subclass [Class] the subclass being created
+      # @return [void]
+      def self.inherited(subclass)
+        super
+        subclass.prepend(UserConfigurable)
+      end
+
+      # Get the Factorio executable path
+      #
+      # Returns the path to the Factorio executable file.
+      # The exact location varies by platform and installation method (Steam, GOG, etc.).
+      #
+      # @return [Pathname] the Factorio executable path
+      # @raise [NotImplementedError] if not implemented by the platform
+      def executable_path = raise NotImplementedError, "#{self.class}#executable_path is not implemented"
+
+      # Get the Factorio user directory path
+      #
+      # This directory contains user-specific Factorio data including mods,
+      # saves, configuration files, and player data.
+      #
+      # @return [Pathname] the Factorio user directory
+      # @raise [NotImplementedError] if not implemented by the platform
+      def user_dir = raise NotImplementedError, "#{self.class}#user_dir is not implemented"
+
+      # Get the Factorio data directory path
+      #
+      # This directory contains the base game data and built-in expansion MODs.
+      # Each MOD (base, space-age, etc.) has its own subdirectory with info.json.
+      #
+      # @return [Pathname] the Factorio data directory
+      # @raise [NotImplementedError] if not implemented by the platform
+      def data_dir = raise NotImplementedError, "#{self.class}#data_dir is not implemented"
+
+      # Get the MOD directory path of Factorio
+      #
+      # This directory contains all installed MODs and MOD configuration files
+      # such as mod-list.json and mod-settings.dat.
+      #
+      # @return [Pathname] the MOD directory of Factorio
+      def mod_dir = user_dir + "mods"
+
+      # Get the save directory path of Factorio
+      #
+      # This directory contains all save game files.
+      #
+      # @return [Pathname] the save directory of Factorio
+      def save_dir = user_dir + "saves"
+
+      # Get the script-output directory path of Factorio
+      #
+      # This directory contains output files generated by Factorio Lua scripts.
+      #
+      # @return [Pathname] the script-output directory of Factorio
+      def script_output_dir = user_dir + "script-output"
+
+      # Get the path of the mod-list.json file
+      #
+      # This file contains the list of installed MODs and their enabled/disabled states.
+      #
+      # @return [Pathname] the path of the mod-list.json file
+      def mod_list_path = mod_dir + "mod-list.json"
+
+      # Get the path of the mod-settings.dat file
+      #
+      # This file contains the MOD settings for startup, runtime-global, and runtime-per-user.
+      #
+      # @return [Pathname] the path of the mod-settings.dat file
+      def mod_settings_path = mod_dir + "mod-settings.dat"
+
+      # Get the path of the player-data.json file
+      #
+      # This file contains player-specific data including authentication credentials,
+      # preferences, and game statistics.
+      #
+      # @return [Pathname] the path of the player-data.json file
+      def player_data_path = user_dir + "player-data.json"
+
+      # Get the path of the current Factorio log file
+      #
+      # This file contains the log output from the current Factorio session.
+      #
+      # @return [Pathname] the path of the current log file
+      def current_log_path = user_dir + "factorio-current.log"
+
+      # Get the path of the previous Factorio log file
+      #
+      # This file contains the log output from the previous Factorio session.
+      #
+      # @return [Pathname] the path of the previous log file
+      def previous_log_path = user_dir + "factorio-previous.log"
+
+      # Get the XDG cache home directory
+      #
+      # Returns the base directory for user-specific cache data according to
+      # the XDG Base Directory Specification. On platforms that don't follow
+      # XDG conventions, this returns the platform-appropriate equivalent.
+      #
+      # @return [Pathname] the XDG cache home directory
+      def xdg_cache_home_dir = Pathname(ENV.fetch("XDG_CACHE_HOME") { default_cache_home_dir })
+
+      # Get the XDG config home directory
+      #
+      # Returns the base directory for user-specific configuration files according to
+      # the XDG Base Directory Specification. On platforms that don't follow
+      # XDG conventions, this returns the platform-appropriate equivalent.
+      #
+      # @return [Pathname] the XDG config home directory
+      def xdg_config_home_dir = Pathname(ENV.fetch("XDG_CONFIG_HOME") { default_config_home_dir })
+
+      # Get the XDG data home directory
+      #
+      # Returns the base directory for user-specific data files according to
+      # the XDG Base Directory Specification. On platforms that don't follow
+      # XDG conventions, this returns the platform-appropriate equivalent.
+      #
+      # @return [Pathname] the XDG data home directory
+      def xdg_data_home_dir = Pathname(ENV.fetch("XDG_DATA_HOME") { default_data_home_dir })
+
+      # Get the XDG state home directory
+      #
+      # Returns the base directory for user-specific state files (logs, history, etc.)
+      # according to the XDG Base Directory Specification. On platforms that don't follow
+      # XDG conventions, this returns the platform-appropriate equivalent.
+      #
+      # @return [Pathname] the XDG state home directory
+      def xdg_state_home_dir = Pathname(ENV.fetch("XDG_STATE_HOME") { default_state_home_dir })
+
+      # Get the Factorix cache directory
+      #
+      # Returns the directory where Factorix stores its cache data.
+      #
+      # @return [Pathname] the Factorix cache directory
+      def factorix_cache_dir = xdg_cache_home_dir / "factorix"
+
+      # Get the Factorix configuration file path
+      #
+      # Returns the path to the Factorix configuration file.
+      #
+      # @return [Pathname] the Factorix configuration file path
+      def factorix_config_path = xdg_config_home_dir / "factorix" / "config.rb"
+
+      # Get the Factorix log file path
+      #
+      # Returns the path to the Factorix log file.
+      #
+      # @return [Pathname] the Factorix log file path
+      def factorix_log_path = xdg_state_home_dir / "factorix" / "factorix.log"
+
+      # Get the Factorio lock file path
+      #
+      # The lock file is created by Factorio when the game is running
+      # and is used to detect if the game is already running.
+      #
+      # @return [Pathname] the lock file path
+      def lock_path = user_dir / ".lock"
+
+      # Check if Factorio is currently running
+      #
+      # Because the game becomes daemonized on launch, we cannot use the process ID
+      # or process groups to check if the game is running. Instead, we check the
+      # existence of the lock file.
+      #
+      # @return [Boolean] true if the game is running, false otherwise
+      def running? = lock_path.exist?
+
+      # Launch Factorio with the specified options
+      #
+      # @param args [Array<String>] command-line arguments to pass to Factorio
+      # @param async [Boolean] whether to launch asynchronously (default: true)
+      # @return [void]
+      # @raise [RuntimeError] if the game is already running
+      def launch(*, async: true)
+        if async
+          spawn([executable_path.to_s, "factorio"], *, out: IO::NULL)
+        else
+          system([executable_path.to_s, "factorio"], *)
+        end
+      end
+
+      # Get the default cache home directory for this platform
+      #
+      # This method should be overridden by platform-specific subclasses
+      # to provide appropriate defaults.
+      #
+      # @return [Pathname] the default cache home directory
+      private def default_cache_home_dir = Pathname(Dir.home) + ".cache"
+
+      # Get the default config home directory for this platform
+      #
+      # This method should be overridden by platform-specific subclasses
+      # to provide appropriate defaults.
+      #
+      # @return [Pathname] the default config home directory
+      private def default_config_home_dir = Pathname(Dir.home) + ".config"
+
+      # Get the default data home directory for this platform
+      #
+      # This method should be overridden by platform-specific subclasses
+      # to provide appropriate defaults.
+      #
+      # @return [Pathname] the default data home directory
+      private def default_data_home_dir = Pathname(Dir.home) + ".local/share"
+
+      # Get the default state home directory for this platform
+      #
+      # This method should be overridden by platform-specific subclasses
+      # to provide appropriate defaults.
+      #
+      # @return [Pathname] the default state home directory
+      private def default_state_home_dir = Pathname(Dir.home) + ".local/state"
+    end
+  end
+end

data/lib/factorix/runtime/linux.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Factorix
+  class Runtime
+    # Linux runtime environment
+    #
+    # Provides default paths for Steam installation on Linux.
+    # Users with non-Steam installations (standalone, Flatpak, Snap, etc.)
+    # should configure paths via the configuration file.
+    # See Runtime::UserConfigurable for configuration instructions.
+    class Linux < Base
+      # Get the Factorio executable path
+      #
+      # Returns the default Steam installation path on Linux.
+      #
+      # @return [Pathname] the Factorio executable path
+      def executable_path = Pathname(Dir.home) + ".steam/steam/steamapps/common/Factorio/bin/x64/factorio"
+
+      # Get the Factorio user directory path
+      #
+      # @return [Pathname] the Factorio user directory
+      def user_dir = Pathname(Dir.home) + ".factorio"
+
+      # Get the Factorio data directory path
+      #
+      # This directory contains the base game data and built-in expansion MODs.
+      #
+      # @return [Pathname] the Factorio data directory
+      def data_dir = Pathname(Dir.home) + ".steam/steam/steamapps/common/Factorio/data"
+    end
+  end
+end

data/lib/factorix/runtime/mac_os.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Factorix
+  class Runtime
+    # macOS runtime environment
+    #
+    # This implementation assumes Factorio is installed via Steam.
+    # For other installation methods (GOG, itch.io, standalone), users should
+    # configure the installation path in the Factorix configuration file.
+    class MacOS < Base
+      # Get the Factorio executable path
+      #
+      # Returns the default Steam installation path on macOS.
+      #
+      # @return [Pathname] the Factorio executable path
+      def executable_path = Pathname(Dir.home) + "Library/Application Support/Steam/steamapps/common/Factorio/factorio.app/Contents/MacOS/factorio"
+
+      # Get the Factorio user directory path
+      #
+      # @return [Pathname] the Factorio user directory
+      def user_dir = Pathname(Dir.home) + "Library/Application Support/factorio"
+
+      # Get the Factorio data directory path
+      #
+      # This directory contains the base game data and built-in expansion MODs.
+      #
+      # @return [Pathname] the Factorio data directory
+      def data_dir = Pathname(Dir.home) + "Library/Application Support/Steam/steamapps/common/Factorio/factorio.app/Contents/data"
+
+      # Get the Factorix log file path
+      #
+      # Returns the path to the Factorix log file using macOS convention.
+      #
+      # @return [Pathname] the Factorix log file path
+      def factorix_log_path = Pathname(Dir.home) + "Library/Logs/factorix/factorix.log"
+
+      # Get the default cache home directory for macOS
+      #
+      # @return [Pathname] the default cache home directory
+      private def default_cache_home_dir = Pathname(Dir.home) + "Library/Caches"
+
+      # Get the default config home directory for macOS
+      #
+      # @return [Pathname] the default config home directory
+      private def default_config_home_dir = Pathname(Dir.home) + "Library/Application Support"
+
+      # Get the default data home directory for macOS
+      #
+      # @return [Pathname] the default data home directory
+      private def default_data_home_dir = Pathname(Dir.home) + "Library/Application Support"
+    end
+  end
+end

data/lib/factorix/runtime/user_configurable.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Factorix
+  class Runtime
+    # Provides user-configurable path overrides for Runtime
+    #
+    # This module is prepended to Runtime::Base to allow users to override
+    # auto-detected paths via configuration. When a configured path is available,
+    # it is used instead of platform-specific auto-detection.
+    #
+    # Configuration is done via Application.config:
+    #
+    # @example Configure paths in config file
+    #   Factorix::Application.configure do |config|
+    #     config.runtime.executable_path = "/opt/factorio/bin/x64/factorio"
+    #     config.runtime.user_dir = "/home/user/.factorio"
+    #   end
+    #
+    # All path resolution decisions are logged at DEBUG level.
+    module UserConfigurable
+      # Get the Factorio executable path
+      #
+      # Returns the configured executable path if available, otherwise falls back
+      # to platform-specific auto-detection.
+      #
+      # @return [Pathname] the Factorio executable path
+      # @raise [ConfigurationError] if auto-detection is not supported and no configuration is provided
+      def executable_path = configurable_path(:executable_path, example_path: "/path/to/factorio") { super }
+
+      # Get the Factorio user directory path
+      #
+      # Returns the configured user_dir if available, otherwise falls back
+      # to platform-specific auto-detection.
+      #
+      # @return [Pathname] the Factorio user directory
+      # @raise [ConfigurationError] if auto-detection is not supported and no configuration is provided
+      def user_dir = configurable_path(:user_dir, example_path: "/path/to/factorio/user/dir") { super }
+
+      # Get the Factorio data directory path
+      #
+      # Returns the configured data_dir if available, otherwise falls back
+      # to platform-specific auto-detection.
+      #
+      # @return [Pathname] the Factorio data directory
+      # @raise [ConfigurationError] if auto-detection is not supported and no configuration is provided
+      def data_dir = configurable_path(:data_dir, example_path: "/path/to/factorio/data") { super }
+
+      private def configurable_path(name, example_path:)
+        if (configured = Application.config.runtime.public_send(name))
+          Application[:logger].debug("Using configured #{name}", path: configured.to_s)
+          configured
+        else
+          Application[:logger].debug("No configuration for #{name}, using auto-detection")
+          yield.tap {|path| Application[:logger].debug("Auto-detected #{name}", path: path.to_s) }
+        end
+      rescue NotImplementedError => e
+        Application[:logger].error("Auto-detection failed and no configuration provided", error: e.message)
+        raise ConfigurationError, <<~MESSAGE
+          #{name} not configured and auto-detection is not supported for this platform.
+          Please configure it in #{Application[:runtime].factorix_config_path}:
+
+            Factorix::Application.configure do |config|
+              config.runtime.#{name} = "#{example_path}"
+            end
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/factorix/runtime/windows.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Factorix
+  class Runtime
+    # Windows runtime environment
+    #
+    # This implementation uses Windows environment variables (APPDATA, LOCALAPPDATA)
+    # to locate Factorio directories. It assumes Factorio is installed via Steam.
+    # For other installation methods (GOG, itch.io, standalone), users should
+    # configure the installation path in the Factorix configuration file.
+    class Windows < Base
+      # Initialize Windows runtime environment
+      #
+      # @param path [WindowsPath] the path provider (for dependency injection)
+      def initialize(path: WindowsPath.new)
+        super()
+        @path = path
+      end
+
+      # Get the Factorio executable path
+      #
+      # Returns the default Steam installation path on Windows.
+      #
+      # @return [Pathname] the Factorio executable path
+      def executable_path = path.program_files_x86.join("Steam/steamapps/common/Factorio/bin/x64/factorio.exe")
+
+      # Get the Factorio user directory path
+      #
+      # @return [Pathname] the Factorio user directory
+      def user_dir = path.app_data.join("Factorio")
+
+      # Get the Factorio data directory path
+      #
+      # This directory contains the base game data and built-in expansion MODs.
+      #
+      # @return [Pathname] the Factorio data directory
+      def data_dir = path.program_files_x86.join("Steam/steamapps/common/Factorio/data")
+
+      private attr_reader :path
+
+      # Get the default cache home directory for Windows
+      #
+      # @return [Pathname] the default cache home directory
+      private def default_cache_home_dir = path.local_app_data
+
+      # Get the default config home directory for Windows
+      #
+      # @return [Pathname] the default config home directory
+      private def default_config_home_dir = path.app_data
+
+      # Get the default data home directory for Windows
+      #
+      # @return [Pathname] the default data home directory
+      private def default_data_home_dir = path.local_app_data
+
+      # Windows-specific path provider
+      class WindowsPath
+        # Get the Program Files (x86) directory path
+        #
+        # @return [Pathname] the Program Files (x86) directory
+        def program_files_x86 = Pathname(convert_separator(ENV.fetch("ProgramFiles(x86)")))
+
+        # Get the AppData directory path
+        #
+        # @return [Pathname] the AppData directory
+        def app_data = Pathname(convert_separator(ENV.fetch("APPDATA")))
+
+        # Get the Local AppData directory path
+        #
+        # @return [Pathname] the Local AppData directory
+        def local_app_data = Pathname(convert_separator(ENV.fetch("LOCALAPPDATA")))
+
+        # Convert Windows path separators to forward slashes for aesthetics and consistency
+        #
+        # While Ruby accepts both separators, normalizing to forward slashes prevents
+        # mixing backslashes and forward slashes when concatenating paths with Pathname#+,
+        # which improves readability.
+        #
+        # @param path_string [String] the path string with backslashes
+        # @return [String] the path string with forward slashes
+        private def convert_separator(path_string) = path_string.tr(File::ALT_SEPARATOR, File::SEPARATOR)
+      end
+    end
+  end
+end