factorix 0.5.0

data/lib/factorix/runtime/wsl.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Factorix
+  class Runtime
+    # WSL (Windows Subsystem for Linux) runtime environment
+    #
+    # This implementation inherits from Windows and converts Windows paths
+    # to WSL paths. It retrieves Windows environment variables via PowerShell
+    # in a single batch operation and converts paths using native Ruby code.
+    class WSL < Windows
+      # Initialize WSL runtime environment
+      #
+      # @param path [WSLPath] the path provider (for dependency injection)
+      def initialize(path: WSLPath.new) = super
+
+      # WSL-specific path provider
+      #
+      # This class fetches Windows environment variables via PowerShell in one batch operation and converts Windows paths to WSL paths.
+      class WSLPath
+        # Default WSL mount root for Windows drives
+        MOUNT_ROOT = "/mnt"
+        private_constant :MOUNT_ROOT
+
+        # PowerShell script to fetch Windows environment variables
+        POWERSHELL_SCRIPT = <<~POWERSHELL
+          [pscustomobject]@{
+            "ProgramFiles(x86)" = ${Env:ProgramFiles(x86)};
+            "APPDATA"           = ${Env:APPDATA};
+            "LOCALAPPDATA"      = ${Env:LOCALAPPDATA}
+          } | ConvertTo-Json -Compress
+        POWERSHELL
+        private_constant :POWERSHELL_SCRIPT
+
+        POWERSHELL_FALLBACK_PATHS = %w[
+          /mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe
+          /mnt/c/Windows/system32/WindowsPowerShell/v1.0/powershell.exe
+        ].freeze
+        private_constant :POWERSHELL_FALLBACK_PATHS
+
+        # Initialize the path provider
+        #
+        # Sets up the mutex for thread-safe lazy initialization
+        def initialize
+          @mutex = Mutex.new
+        end
+
+        # Get the Program Files (x86) directory path (WSL-converted)
+        #
+        # @return [Pathname] the Program Files (x86) directory
+        def program_files_x86 = @program_files_x86 ||= Pathname(convert_windows_to_wsl(windows_paths["ProgramFiles(x86)"]))
+
+        # Get the AppData directory path (WSL-converted)
+        #
+        # @return [Pathname] the AppData directory
+        def app_data = @app_data ||= Pathname(convert_windows_to_wsl(windows_paths["APPDATA"]))
+
+        # Get the Local AppData directory path (WSL-converted)
+        #
+        # @return [Pathname] the Local AppData directory
+        def local_app_data = @local_app_data ||= Pathname(convert_windows_to_wsl(windows_paths["LOCALAPPDATA"]))
+
+        # Fetch and cache all Windows environment variables
+        #
+        # @return [Hash] the environment variables as a hash
+        private def windows_paths
+          return @windows_paths if @windows_paths
+
+          @mutex.synchronize do
+            @windows_paths ||= fetch_windows_paths_via_powershell
+          end
+        end
+
+        # Fetch Windows environment variables via PowerShell
+        #
+        # @return [Hash] the environment variables as a hash
+        # @raise [PlatformError] if PowerShell execution fails
+        private def fetch_windows_paths_via_powershell
+          ps = find_powershell_exe
+
+          stdout, status = Open3.capture2(ps, "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", POWERSHELL_SCRIPT)
+
+          raise PlatformError, "PowerShell execution failed: #{status}" unless status.success?
+
+          JSON.parse(stdout.encode("UTF-8", invalid: :replace, undef: :replace))
+        end
+
+        # Convert Windows path to WSL path
+        #
+        # @param windows_path [String] Windows-style path to convert
+        # @return [String] equivalent WSL path
+        # @raise [PlatformError] if the path format is invalid
+        private def convert_windows_to_wsl(windows_path)
+          raise PlatformError, "Invalid Windows path: #{windows_path}" unless windows_path =~ %r{\A([A-Za-z]):[\\/]?(.*)\z}
+
+          drive = $1.downcase
+          path = $2.tr("\\", "/")
+          result = "#{MOUNT_ROOT}/#{drive}/#{path}"
+          # Normalize: collapse multiple slashes and remove trailing slash
+          result.squeeze("/").delete_suffix("/")
+        end
+
+        # Find powershell.exe executable
+        #
+        # @return [String] path to powershell.exe
+        # @raise [PlatformError] if powershell.exe is not found
+        private def find_powershell_exe
+          return "powershell.exe" if system("which", "powershell.exe", out: File::NULL, err: File::NULL)
+
+          POWERSHELL_FALLBACK_PATHS.find {|path| File.exist?(path) } ||
+            raise(PlatformError, "powershell.exe not found in PATH or default locations")
+        end
+      end
+    end
+  end
+end

data/lib/factorix/runtime.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Factorix
+  # Factorio runtime environment abstraction
+  #
+  # This class provides a factory method to detect the current platform
+  # and return the appropriate runtime environment instance.
+  class Runtime
+    # Detect the current platform and return the appropriate runtime
+    #
+    # @return [Runtime::Base] the runtime environment for the current platform
+    # @raise [UnsupportedPlatformError] if the platform is not supported
+    def self.detect
+      case RUBY_PLATFORM
+      when /darwin/
+        MacOS.new
+      when /mingw|mswin/
+        Windows.new
+      when /linux/
+        wsl? ? WSL.new : Linux.new
+      else
+        raise UnsupportedPlatformError, "Platform is not supported: #{RUBY_PLATFORM}"
+      end
+    end
+
+    # Check if running on WSL
+    #
+    # @return [Boolean] true if running on WSL, false otherwise
+    def self.wsl? = File.exist?("/proc/version") && /microsoft/i.match?(File.read("/proc/version"))
+    private_class_method :wsl?
+  end
+end

data/lib/factorix/save_file.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "zip"
+require "zlib"
+
+module Factorix
+  SaveFile = Data.define(:version, :mods, :startup_settings)
+
+  # Data structure for Factorio save file information
+  #
+  # SaveFile provides functionality to extract MOD information and startup settings
+  # from Factorio save files (.zip format containing level.dat0 or level-init.dat).
+  class SaveFile
+    # @!attribute [r] version
+    #   @return [Factorix::GameVersion] Game version from the save file
+    # @!attribute [r] mods
+    #   @return [Hash<String, Factorix::MODState>] Hash of MOD name to MODState
+    # @!attribute [r] startup_settings
+    #   @return [Factorix::MODSettings::Section] Startup settings section
+
+    # Level file names to search for, in priority order
+    LEVEL_FILE_NAMES = %w[level.dat0 level-init.dat].freeze
+    private_constant :LEVEL_FILE_NAMES
+
+    # Load a save file and extract MOD information and settings
+    #
+    # @param path [Pathname] Path to the save file (.zip)
+    # @return [SaveFile] Extracted save file data
+    # @raise [FileFormatError] If save file or level file not found
+    # @raise [Factorix::Error] If save file format is invalid
+    def self.load(path) = Parser.new(path).parse
+
+    # Internal parser for save files
+    class Parser
+      # Initialize a new Parser instance
+      #
+      # @param path [Pathname] Path to the save file
+      def initialize(path) = @path = path
+
+      # Parse the save file and return extracted data
+      #
+      # @return [SaveFile] Extracted save file data
+      # @raise [FileFormatError] If save file or level file not found
+      def parse
+        open_level_file do |stream|
+          deserializer = SerDes::Deserializer.new(stream)
+          parse_save_header(deserializer)
+          skip_unknown_bytes(deserializer)
+          parse_startup_settings(deserializer)
+        end
+
+        SaveFile.new(version: @version, mods: @mods, startup_settings: @startup_settings)
+      end
+
+      private def open_level_file
+        Zip::File.open(@path) do |zip_file|
+          LEVEL_FILE_NAMES.each do |file_name|
+            entry = find_level_entry(zip_file, file_name)
+            next unless entry
+
+            stream = entry.get_input_stream
+            return yield decompress_if_needed(stream)
+          end
+
+          raise FileFormatError, "level.dat0 or level-init.dat not found in #{@path}"
+        end
+      end
+
+      # Find a level file entry in the zip file
+      #
+      # @param zip_file [Zip::File] The zip file
+      # @param file_name [String] The level file name to search for
+      # @return [Zip::Entry, nil] The entry if found, nil otherwise
+      private def find_level_entry(zip_file, file_name) = zip_file.glob("*/#{file_name}").first
+
+      # Decompress stream if it's zlib compressed
+      #
+      # @param stream [IO] The input stream
+      # @return [IO] Decompressed stream or original stream
+      private def decompress_if_needed(stream)
+        # Read CMF (Compression Method and Flags) byte
+        cmf = stream.read(1)
+        return StringIO.new("") if cmf.nil?
+
+        stream.rewind
+
+        # CMF = 0x78 indicates zlib compression (DEFLATE with 32K window)
+        if cmf.unpack1("C") == 0x78
+          StringIO.new(Zlib::Inflate.inflate(stream.read))
+        else
+          stream
+        end
+      end
+
+      # Parse save header to extract game version and MOD list
+      #
+      # @param deserializer [Factorix::SerDes::Deserializer] The deserializer
+      # @return [void]
+      private def parse_save_header(deserializer)
+        # Read game version
+        @version = deserializer.read_game_version
+
+        # Skip 1 byte after version
+        deserializer.read_u8
+
+        # Skip fields we don't need
+        deserializer.read_str  # campaign
+        deserializer.read_str  # level_name
+        deserializer.read_str  # base_mod
+        deserializer.read_u8   # difficulty
+        deserializer.read_bool # finished
+        deserializer.read_bool # player_won
+        deserializer.read_str  # next_level
+        deserializer.read_bool # can_continue
+        deserializer.read_bool # finished_but_continuing
+        deserializer.read_bool # saving_replay
+        deserializer.read_bool # allow_non_admin_debug_options
+        deserializer.read_mod_version # loaded_from (MODVersion, not GameVersion)
+        deserializer.read_u16 # loaded_from_build
+        deserializer.read_u8 # allowed_commands
+
+        # Additional fields before the MOD list
+        # These fields' purposes are not yet fully understood
+        deserializer.read_bool  # Unknown boolean field
+        deserializer.read_u32   # Unknown u32 field
+        deserializer.read_bool  # Unknown boolean field
+
+        # Read MOD list
+        parse_mods(deserializer)
+      end
+
+      # Parse MOD list from save header
+      #
+      # @param deserializer [Factorix::SerDes::Deserializer] The deserializer
+      # @return [void]
+      private def parse_mods(deserializer)
+        mods_count = deserializer.read_optim_u32
+        @mods = {}
+
+        mods_count.times do
+          name = deserializer.read_str
+          version = deserializer.read_mod_version
+          _crc = deserializer.read_u32
+
+          # All MODs in save file are enabled
+          @mods[name] = MODState.new(enabled: true, version:)
+        end
+      end
+
+      # Skip unknown 4 bytes after MOD list
+      #
+      # @param deserializer [Factorix::SerDes::Deserializer] The deserializer
+      # @return [void]
+      private def skip_unknown_bytes(deserializer) = deserializer.read_bytes(4)
+
+      # Parse startup settings from save file
+      #
+      # @param deserializer [Factorix::SerDes::Deserializer] The deserializer
+      # @return [void]
+      private def parse_startup_settings(deserializer)
+        raw_settings = deserializer.read_property_tree
+
+        # Create a new Section and populate it
+        @startup_settings = MODSettings::Section.new("startup")
+
+        return unless raw_settings.is_a?(Hash)
+
+        raw_settings.each do |key, value_hash|
+          # Extract the actual value from the {"value" => X} hash
+          next unless value_hash.is_a?(Hash)
+
+          @startup_settings[key] = value_hash["value"]
+        end
+      end
+    end
+    private_constant :Parser
+  end
+end

data/lib/factorix/ser_des/deserializer.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Factorix
+  module SerDes
+    # Deserialize data from binary format
+    #
+    # This class provides methods to deserialize various data types from Factorio's
+    # binary file format, following the specifications documented in the Factorio wiki.
+    class Deserializer
+      # @!parse
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      include Import[:logger]
+
+      # Create a new Deserializer instance
+      #
+      # @param stream [IO] An IO-like object that responds to #read
+      # @param logger [Dry::Logger::Dispatcher] optional logger
+      # @raise [ArgumentError] If the stream doesn't respond to #read
+      def initialize(stream, logger: nil)
+        super(logger:)
+        raise ArgumentError, "can't read from the given argument" unless stream.respond_to?(:read)
+
+        @stream = stream
+        logger.debug "Initializing Deserializer"
+      end
+
+      # Read raw bytes from the stream
+      #
+      # @param length [Integer] Number of bytes to read
+      # @raise [Factorix::InvalidLengthError] If length is nil or negative
+      # @raise [EOFError] If end of file is reached before reading length bytes
+      # @return [String] Binary data read
+      def read_bytes(length)
+        raise InvalidLengthError, "nil length" if length.nil?
+        raise InvalidLengthError, "negative length #{length}" if length.negative?
+        return +"" if length.zero?
+
+        bytes = @stream.read(length)
+        if bytes.nil? || bytes.size < length
+          logger.debug("Unexpected EOF", requested_bytes: length)
+          raise EOFError
+        end
+
+        bytes
+      end
+
+      # Read an unsigned 8-bit integer
+      #
+      # @return [Integer] 8-bit unsigned integer
+      def read_u8 = read_bytes(1).unpack1("C")
+
+      # Read an unsigned 16-bit integer
+      #
+      # @return [Integer] 16-bit unsigned integer
+      def read_u16 = read_bytes(2).unpack1("v")
+
+      # Read an unsigned 32-bit integer
+      #
+      # @return [Integer] 32-bit unsigned integer
+      def read_u32 = read_bytes(4).unpack1("V")
+
+      # Read a space-optimized 16-bit unsigned integer
+      #
+      # @see https://wiki.factorio.com/Data_types#Space_Optimized
+      # @return [Integer] 16-bit unsigned integer
+      def read_optim_u16
+        byte = read_u8
+        byte == 0xFF ? read_u16 : byte
+      end
+
+      # Read a space-optimized 32-bit unsigned integer
+      #
+      # @see https://wiki.factorio.com/Data_types#Space_Optimized
+      # @return [Integer] 32-bit unsigned integer
+      def read_optim_u32
+        byte = read_u8
+        byte == 0xFF ? read_u32 : byte
+      end
+
+      # Read a tuple of 16-bit unsigned integers
+      #
+      # @param length [Integer] Number of integers to read
+      # @return [Array<Integer>] Array of 16-bit unsigned integers
+      def read_u16_tuple(length) = Array.new(length) { read_u16 }
+
+      # Read a boolean value
+      #
+      # @return [Boolean] Boolean value
+      def read_bool = read_u8 != 0
+
+      # Read a string
+      #
+      # @return [String] String read
+      def read_str
+        length = read_optim_u32
+        read_bytes(length).force_encoding(Encoding::UTF_8)
+      end
+
+      # Read a string property
+      #
+      # @see https://wiki.factorio.com/Property_tree#String
+      # @return [String] String property
+      def read_str_property = read_bool ? "" : read_str
+
+      # Read a double-precision floating point number
+      #
+      # @see https://wiki.factorio.com/Property_tree#Number
+      # @return [Float] Double-precision floating point number
+      def read_double = read_bytes(8).unpack1("d")
+
+      # Read a GameVersion object
+      #
+      # @return [GameVersion] GameVersion object
+      def read_game_version = GameVersion.from_numbers(read_u16, read_u16, read_u16, read_u16)
+
+      # Read a MODVersion object
+      #
+      # @return [MODVersion] MODVersion object
+      def read_mod_version = MODVersion.from_numbers(read_optim_u16, read_optim_u16, read_optim_u16)
+
+      # Read a signed long integer (8 bytes)
+      #
+      # @return [Integer] Signed long integer
+      def read_long = read_bytes(8).unpack1("q<")
+
+      # Read an unsigned long integer (8 bytes)
+      #
+      # @return [Integer] Unsigned long integer
+      def read_unsigned_long = read_bytes(8).unpack1("Q<")
+
+      # Read a dictionary
+      #
+      # @see https://wiki.factorio.com/Property_tree#Dictionary
+      # @return [Hash] Dictionary of key-value pairs
+      def read_dictionary
+        length = read_u32
+        logger.debug("Reading dictionary", length:)
+        length.times.each_with_object({}) do |_i, dict|
+          key = read_str_property
+          dict[key] = read_property_tree
+        end
+      end
+
+      # Read a list
+      # This type is identical to dictionary
+      #
+      # @see https://wiki.factorio.com/Property_tree#List
+      alias read_list read_dictionary
+
+      # Read a property tree
+      #
+      # @raise [Factorix::UnknownPropertyType] If the property type is not supported
+      # @return [Object] Object read
+      def read_property_tree
+        type = read_u8
+        _any_type_flag = read_bool
+        logger.debug("Reading property tree", type:)
+
+        case type
+        when 0
+          # Handle type 0 - None (null value)
+          #
+          # @see https://wiki.factorio.com/Property_tree
+          nil
+        when 1
+          read_bool
+        when 2
+          read_double
+        when 3
+          read_str_property
+        when 4
+          read_list
+        when 5
+          read_dictionary
+        when 6
+          # Handle type 6 - Signed integer
+          #
+          # @see https://wiki.factorio.com/Property_tree
+          SignedInteger.new(read_long)
+        when 7
+          # Handle type 7 - Unsigned integer
+          #
+          # @see https://wiki.factorio.com/Property_tree
+          UnsignedInteger.new(read_unsigned_long)
+        else
+          logger.debug("Unknown property type", type:)
+          raise UnknownPropertyType, "Unknown property type: #{type}"
+        end
+      end
+
+      # Check if the stream is at EOF
+      #
+      # @return [Boolean] True if at end of file, false otherwise
+      def eof? = @stream.eof?
+    end
+  end
+end