factorix 0.5.0

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Factorix
+  class CLI
+    module Commands
+      # Display Factorio and Factorix paths
+      #
+      # This command outputs all paths managed by the runtime environment.
+      #
+      # @example
+      #   $ factorix path
+      #   executable_path     /path/to/factorio
+      #   user_dir            /path/to/user
+      #   ...
+      class Path < Base
+        # Mapping from path type keys to runtime method names
+        PATH_TYPES = {
+          "executable_path" => :executable_path,
+          "data_dir" => :data_dir,
+          "user_dir" => :user_dir,
+          "mod_dir" => :mod_dir,
+          "save_dir" => :save_dir,
+          "script_output_dir" => :script_output_dir,
+          "mod_list_path" => :mod_list_path,
+          "mod_settings_path" => :mod_settings_path,
+          "player_data_path" => :player_data_path,
+          "lock_path" => :lock_path,
+          "current_log_path" => :current_log_path,
+          "previous_log_path" => :previous_log_path,
+          "factorix_cache_dir" => :factorix_cache_dir,
+          "factorix_config_path" => :factorix_config_path,
+          "factorix_log_path" => :factorix_log_path
+        }.freeze
+        private_constant :PATH_TYPES
+
+        # @!parse
+        #   # @return [Runtime::Base]
+        #   attr_reader :runtime
+        #   # @return [Dry::Logger::Dispatcher]
+        #   attr_reader :logger
+        include Import[:runtime, :logger]
+
+        desc "Display Factorio and Factorix paths"
+
+        example [
+          "         # Display paths in table format",
+          "--json   # Display paths in JSON format"
+        ]
+
+        option :json, type: :flag, default: false, desc: "Output in JSON format"
+
+        # Execute the path command
+        #
+        # @param json [Boolean] output in JSON format
+        # @return [void]
+        def call(json:, **)
+          logger.debug("Displaying all paths")
+
+          result = PATH_TYPES.transform_values {|method_name| runtime.public_send(method_name).to_s }
+
+          if json
+            puts JSON.pretty_generate(result)
+          else
+            output_table(result)
+          end
+        end
+
+        private def output_table(result)
+          key_width = result.keys.map(&:length).max
+          result.each do |key, value|
+            puts "%-#{key_width}s  %s" % [key, value]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      # Mixin for commands that require the game to be stopped
+      #
+      # This module provides automatic validation that the game is not running
+      # before executing commands that modify MOD installation state or
+      # mod-list.json/mod-settings.dat files.
+      #
+      # Prepend this module in commands that should not run while the game is active
+      # (e.g., install, uninstall, enable, disable)
+      module RequiresGameStopped
+        # Wrapper for command call that checks game state
+        # @param options [Hash] command options passed to the original call method
+        # @return [void]
+        def call(**options)
+          check_game_stopped
+          super
+        end
+
+        private def check_game_stopped
+          return unless runtime.running?
+
+          logger.error("Operation blocked: game is running")
+          raise GameRunningError, "Cannot perform this operation while Factorio is running. Please stop the game and try again."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      # Display Factorix version
+      #
+      # This command outputs the current version of the Factorix gem.
+      #
+      # @example
+      #   $ factorix version
+      #   0.1.0
+      class Version < Base
+        desc "Display Factorix version"
+
+        # Execute the version command
+        #
+        # Outputs the current version of the Factorix gem to stdout.
+        #
+        # @return [void]
+        def call(**) = puts VERSION
+      end
+    end
+  end
+end

data/lib/factorix/cli.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+module Factorix
+  # Command-line interface for Factorix
+  #
+  # This class serves as the registry for all CLI commands using dry-cli.
+  # Commands are registered with their names and mapped to command classes.
+  #
+  # @example Running the CLI
+  #   Dry::CLI.new(Factorix::CLI).call
+  class CLI
+    extend Dry::CLI::Registry
+
+    register "version", Commands::Version
+    register "man", Commands::Man
+    register "launch", Commands::Launch
+    register "path", Commands::Path
+    register "completion", Commands::Completion
+    register "mod check", Commands::MOD::Check
+    register "mod list", Commands::MOD::List
+    register "mod show", Commands::MOD::Show
+    register "mod enable", Commands::MOD::Enable
+    register "mod disable", Commands::MOD::Disable
+    register "mod install", Commands::MOD::Install
+    register "mod uninstall", Commands::MOD::Uninstall
+    register "mod update", Commands::MOD::Update
+    register "mod download", Commands::MOD::Download
+    register "mod upload", Commands::MOD::Upload
+    register "mod edit", Commands::MOD::Edit
+    register "mod search", Commands::MOD::Search
+    register "mod sync", Commands::MOD::Sync
+    register "mod image list", Commands::MOD::Image::List
+    register "mod image add", Commands::MOD::Image::Add
+    register "mod image edit", Commands::MOD::Image::Edit
+    register "mod settings dump", Commands::MOD::Settings::Dump
+    register "mod settings restore", Commands::MOD::Settings::Restore
+    register "cache stat", Commands::Cache::Stat
+    register "cache evict", Commands::Cache::Evict
+  end
+end

data/lib/factorix/dependency/edge.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Dependency
+    Edge = Data.define(:from_mod, :to_mod, :type, :version_requirement)
+
+    # Represents a dependency edge in the dependency graph
+    #
+    # Each edge represents a dependency relationship from one MOD (dependent)
+    # to another MOD (dependency). The edge type indicates the nature of the
+    # relationship (required, optional, incompatible, etc.).
+    class Edge
+      # @!attribute [r] from_mod
+      #   @return [Factorix::MOD] MOD object (the dependent)
+      # @!attribute [r] to_mod
+      #   @return [Factorix::MOD] MOD object (the dependency)
+      # @!attribute [r] type
+      #   @return [Symbol] dependency type
+      # @!attribute [r] version_requirement
+      #   @return [MODVersionRequirement, nil] version requirement
+
+      # Dependency types (from Factorix::Dependency::Entry)
+      REQUIRED = Entry::REQUIRED
+      public_constant :REQUIRED
+      OPTIONAL = Entry::OPTIONAL
+      public_constant :OPTIONAL
+      HIDDEN_OPTIONAL = Entry::HIDDEN_OPTIONAL
+      public_constant :HIDDEN_OPTIONAL
+      INCOMPATIBLE = Entry::INCOMPATIBLE
+      public_constant :INCOMPATIBLE
+      LOAD_NEUTRAL = Entry::LOAD_NEUTRAL
+      public_constant :LOAD_NEUTRAL
+
+      # @param from_mod [Factorix::MOD] The dependent MOD
+      # @param to_mod [Factorix::MOD] The dependency MOD
+      # @param type [Symbol] The dependency type (:required, :optional, :hidden, :incompatible, :load_neutral)
+      # @param version_requirement [MODVersionRequirement, nil] Version requirement (optional)
+      def initialize(from_mod:, to_mod:, type:, version_requirement: nil) = super
+
+      # Check if this is a required dependency
+      #
+      # @return [Boolean]
+      def required? = type == REQUIRED
+
+      # Check if this is an optional dependency
+      #
+      # @return [Boolean]
+      def optional? = type == OPTIONAL || type == HIDDEN_OPTIONAL
+
+      # Check if this is a hidden optional dependency
+      #
+      # @return [Boolean]
+      def hidden_optional? = type == HIDDEN_OPTIONAL
+
+      # Check if this is an incompatibility relationship
+      #
+      # @return [Boolean]
+      def incompatible? = type == INCOMPATIBLE
+
+      # Check if this is a load-neutral dependency
+      #
+      # @return [Boolean]
+      def load_neutral? = type == LOAD_NEUTRAL
+
+      # Check if the given version satisfies this edge's version requirement
+      #
+      # @param version [Factorix::MODVersion] The version to check
+      # @return [Boolean] true if satisfied or no requirement exists
+      def satisfied_by?(version)
+        return true unless version_requirement
+
+        version_requirement.satisfied_by?(version)
+      end
+
+      # String representation of the edge
+      #
+      # @return [String]
+      def to_s
+        requirement_str = version_requirement ? " #{version_requirement}" : ""
+        "#{from_mod} --[#{type}#{requirement_str}]--> #{to_mod}"
+      end
+
+      # Detailed inspection string
+      #
+      # @return [String]
+      def inspect = "#<#{self.class.name} #{self}>"
+    end
+  end
+end

data/lib/factorix/dependency/entry.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Dependency
+    # Define Entry as an immutable data class
+    Entry = Data.define(:mod, :type, :version_requirement)
+
+    # Represents a single MOD dependency
+    #
+    # This class encapsulates a MOD dependency with its type (required, optional, etc.)
+    # and optional version requirement.
+    #
+    # @example Creating dependencies
+    #   # Required dependency on base MOD
+    #   base_mod = MOD[name: "base"]
+    #   dep1 = Dependency::Entry[mod: base_mod, type: :required, version_requirement: nil]
+    #
+    #   # Optional dependency with version requirement
+    #   some_mod = MOD[name: "some-mod"]
+    #   requirement = MODVersionRequirement[operator: ">=", version: MODVersion.from_string("1.2.0")]
+    #   dep2 = Dependency::Entry[mod: some_mod, type: :optional, version_requirement: requirement]
+    #
+    #   # Incompatible MOD
+    #   bad_mod = MOD[name: "bad-mod"]
+    #   dep3 = Dependency::Entry[mod: bad_mod, type: :incompatible, version_requirement: nil]
+    class Entry
+      # @!attribute [r] mod
+      #   @return [MOD] The dependent MOD
+      # @!attribute [r] type
+      #   @return [Symbol] Type of dependency (:required, :optional, :hidden, :incompatible, :load_neutral)
+      # @!attribute [r] version_requirement
+      #   @return [MODVersionRequirement, nil] Version requirement (nil if no requirement)
+
+      # Dependency type constants
+      REQUIRED = :required
+      public_constant :REQUIRED
+      OPTIONAL = :optional
+      public_constant :OPTIONAL
+      HIDDEN_OPTIONAL = :hidden
+      public_constant :HIDDEN_OPTIONAL
+      INCOMPATIBLE = :incompatible
+      public_constant :INCOMPATIBLE
+      LOAD_NEUTRAL = :load_neutral
+      public_constant :LOAD_NEUTRAL
+
+      VALID_TYPES = [REQUIRED, OPTIONAL, HIDDEN_OPTIONAL, INCOMPATIBLE, LOAD_NEUTRAL].freeze
+      private_constant :VALID_TYPES
+
+      # Create a new Entry
+      #
+      # @param mod [MOD] The dependent MOD
+      # @param type [Symbol] Type of dependency (:required, :optional, :hidden, :incompatible, :load_neutral)
+      # @param version_requirement [MODVersionRequirement, nil] Version requirement (nil if no requirement)
+      # @return [Entry]
+      # @raise [ArgumentError] if mod is not a MOD instance
+      # @raise [ArgumentError] if type is not valid
+      # @raise [ArgumentError] if version_requirement is not nil or MODVersionRequirement
+      def initialize(mod:, type:, version_requirement: nil)
+        unless mod.is_a?(MOD)
+          raise ArgumentError, "mod must be a MOD instance, got #{mod.class}"
+        end
+
+        unless VALID_TYPES.include?(type)
+          raise ArgumentError, "Invalid dependency type: #{type}. Must be one of: #{VALID_TYPES.join(", ")}"
+        end
+
+        if version_requirement && !version_requirement.is_a?(MODVersionRequirement)
+          raise ArgumentError, "version_requirement must be a MODVersionRequirement or nil, got #{version_requirement.class}"
+        end
+
+        super
+      end
+
+      # Check if this is a required dependency
+      #
+      # @return [Boolean] true if dependency is required
+      def required? = type == REQUIRED
+
+      # Check if this is an optional dependency (including hidden optional)
+      #
+      # @return [Boolean] true if dependency is optional or hidden optional
+      def optional? = type == OPTIONAL || type == HIDDEN_OPTIONAL
+
+      # Check if this is an incompatible (conflicting) dependency
+      #
+      # @return [Boolean] true if dependency is incompatible
+      def incompatible? = type == INCOMPATIBLE
+
+      # Check if this dependency does not affect load order
+      #
+      # @return [Boolean] true if dependency is load-neutral
+      def load_neutral? = type == LOAD_NEUTRAL
+
+      # Check if a given version satisfies this dependency's version requirement
+      #
+      # @param version [MODVersion] Version to check
+      # @return [Boolean] true if version requirement is satisfied, or true if no requirement exists
+      def satisfied_by?(version)
+        return true unless version_requirement
+
+        version_requirement.satisfied_by?(version)
+      end
+
+      # Return string representation of the dependency
+      #
+      # @return [String] String representation (e.g., "? some-mod >= 1.2.0")
+      def to_s
+        result = case type
+                 when REQUIRED then ""
+                 when OPTIONAL then "? "
+                 when HIDDEN_OPTIONAL then "(?) "
+                 when INCOMPATIBLE then "! "
+                 when LOAD_NEUTRAL then "~ "
+                 else
+                   raise ArgumentError, "Unexpected dependency type: #{type}"
+                 end
+
+        result += mod.name
+        result += " #{version_requirement}" if version_requirement
+        result
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Dependency
+    class Graph
+      # Builds a dependency graph from installed MODs and MOD list
+      #
+      # The Builder constructs a Graph by:
+      # 1. Creating nodes for all installed MODs
+      # 2. Setting enabled state from mod-list.json
+      # 3. Creating edges from dependency information in info.json
+      class Builder
+        # Build a dependency graph from current state
+        #
+        # @param installed_mods [Array<Factorix::InstalledMOD>] Installed MODs from MOD directory
+        # @param mod_list [Factorix::MODList] MOD list from mod-list.json
+        # @return [Factorix::Dependency::Graph] The constructed graph
+        def self.build(installed_mods:, mod_list:) = new(installed_mods:, mod_list:).build
+
+        # @param installed_mods [Array<Factorix::InstalledMOD>] Installed MODs
+        # @param mod_list [Factorix::MODList] MOD list
+        def initialize(installed_mods:, mod_list:)
+          @installed_mods = installed_mods
+          @mod_list = mod_list
+        end
+
+        # Build the graph
+        #
+        # @return [Factorix::Dependency::Graph] The constructed graph
+        def build
+          graph = Graph.new
+
+          unique_mods = @installed_mods.map(&:mod)
+          unique_mods.uniq!
+
+          unique_mods.each do |mod|
+            add_node_for_mod(graph, mod)
+          end
+
+          # Only active versions contribute edges
+          active_versions = graph.nodes.to_h {|node| [node.mod, node.version] }
+
+          @installed_mods.each do |installed_mod|
+            next unless active_versions[installed_mod.mod] == installed_mod.version
+
+            add_edges_for_dependencies(graph, installed_mod)
+          end
+
+          graph
+        end
+
+        private def add_node_for_mod(graph, mod)
+          version = select_version_for_mod(mod)
+          enabled = mod_enabled?(mod)
+
+          node = Node.new(mod:, version:, enabled:, installed: true)
+          graph.add_node(node)
+        end
+
+        # Select which version to use for a MOD
+        #
+        # @param mod [Factorix::MOD] The MOD
+        # @return [Factorix::MODVersion] The selected version
+        private def select_version_for_mod(mod)
+          if @mod_list.exist?(mod)
+            specified_version = @mod_list.version(mod)
+            if specified_version
+              installed_with_version = @installed_mods.find {|im| im.mod == mod && im.version == specified_version }
+              return specified_version if installed_with_version
+            end
+          end
+
+          versions_for_mod = @installed_mods.select {|im| im.mod == mod }
+          versions_for_mod.max_by(&:version).version
+        end
+
+        # Add edges for a MOD's dependencies
+        #
+        # @param graph [Factorix::Dependency::Graph] The graph to add to
+        # @param installed_mod [Factorix::InstalledMOD] The installed MOD
+        # @return [void]
+        private def add_edges_for_dependencies(graph, installed_mod)
+          from_mod = installed_mod.mod
+          dependencies = installed_mod.info.dependencies || []
+
+          dependencies.each do |dependency|
+            # Skip only base MOD (always available and cannot be disabled)
+            # 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)
+            graph.add_edge(edge)
+          end
+        end
+
+        # Check if a MOD is enabled in the MOD list
+        #
+        # @param mod [Factorix::MOD] The MOD to check
+        # @return [Boolean] true if enabled, false otherwise
+        private def mod_enabled?(mod)
+          return false unless @mod_list.exist?(mod)
+
+          @mod_list.enabled?(mod)
+        end
+      end
+    end
+  end
+end