factorix 0.5.0

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

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "concurrent/executor/fixed_thread_pool"
+require "concurrent/future"
+
+module Factorix
+  class CLI
+    module Commands
+      module MOD
+        # Download MOD files from Factorio MOD Portal
+        class Download < Base
+          include DownloadSupport
+          # @!parse
+          #   # @return [Portal]
+          #   attr_reader :portal
+          #   # @return [Dry::Logger::Dispatcher]
+          #   attr_reader :logger
+          #   # @return [Runtime]
+          #   attr_reader :runtime
+          include Import[:portal, :logger, :runtime]
+
+          desc "Download MOD files from Factorio MOD Portal"
+
+          example [
+            "some-mod                 # Download latest version to current directory",
+            "some-mod@1.2.0           # Download specific version",
+            "-d /tmp/mods some-mod    # Download to specific directory",
+            "-r some-mod              # Include required dependencies"
+          ]
+
+          argument :mod_specs, type: :array, required: true, desc: "MOD specifications (name@version or name@latest or name)"
+          option :directory, type: :string, aliases: ["-d"], default: ".", desc: "Download directory"
+          option :jobs, type: :integer, aliases: ["-j"], default: 4, desc: "Number of parallel downloads"
+          option :recursive, type: :flag, aliases: ["-r"], default: false, desc: "Include required dependencies recursively"
+
+          # Execute the download command
+          #
+          # @param mod_specs [Array<String>] MOD specifications
+          # @param directory [String] Download directory
+          # @param jobs [Integer] Number of parallel downloads
+          # @param recursive [Boolean] Include required dependencies recursively
+          # @return [void]
+          def call(mod_specs:, directory: ".", jobs: 4, recursive: false, **)
+            download_dir = Pathname(directory).expand_path
+
+            raise DirectoryNotFoundError, "Download directory does not exist: #{download_dir}" unless download_dir.exist?
+
+            if runtime.mod_dir.exist? && download_dir.realpath == runtime.mod_dir.realpath
+              raise InvalidOperationError, "Cannot download to MOD directory. Use 'mod install' instead."
+            end
+
+            download_targets = plan_download(mod_specs, download_dir, jobs, recursive)
+
+            if download_targets.empty?
+              say "No MOD(s) to download", prefix: :info
+              return
+            end
+
+            download_mods(download_targets, jobs)
+
+            say "Downloaded #{download_targets.size} MOD(s)", prefix: :success
+          end
+
+          # Plan the download by fetching MOD info and optionally resolving dependencies
+          #
+          # @param mod_specs [Array<String>] MOD specifications
+          # @param download_dir [Pathname] Download directory
+          # @param jobs [Integer] Number of parallel jobs
+          # @param recursive [Boolean] Include dependencies
+          # @return [Array<Hash>] Download targets with MOD info and releases
+          private def plan_download(mod_specs, download_dir, jobs, recursive)
+            presenter = Progress::Presenter.new(title: "\u{1F50D}\u{FE0E} Fetching MOD info", output: $stderr)
+
+            target_infos = fetch_target_mod_info(mod_specs, jobs, presenter)
+
+            all_mod_infos = if recursive
+                              resolve_dependencies(target_infos, jobs, presenter)
+                            else
+                              target_infos.to_h {|info| [info[:mod_name], info] }
+                            end
+
+            build_download_targets(all_mod_infos, download_dir)
+          end
+
+          # Fetch MOD information for target specifications
+          #
+          # @param mod_specs [Array<String>] MOD specifications
+          # @param jobs [Integer] Number of parallel jobs
+          # @param presenter [Progress::Presenter] Progress presenter
+          # @return [Array<Hash>] Array of {mod_spec:, mod_name:, mod_info:, release:}
+          private def fetch_target_mod_info(mod_specs, jobs, presenter)
+            presenter.start
+
+            pool = Concurrent::FixedThreadPool.new(jobs)
+
+            futures = mod_specs.map {|mod_spec|
+              Concurrent::Future.execute(executor: pool) do
+                result = fetch_single_mod_info(mod_spec)
+                presenter.update
+                result
+              end
+            }
+
+            futures.map(&:value!)
+          ensure
+            pool&.shutdown
+            pool&.wait_for_termination
+          end
+
+          # Fetch information for a single MOD specification
+          #
+          # @param mod_spec [String] MOD specification (name@version or name)
+          # @return [Hash] {mod:, mod_name:, mod_info:, release:, version:}
+          private def fetch_single_mod_info(mod_spec)
+            parsed = parse_mod_spec(mod_spec)
+            mod = parsed[:mod]
+            version = parsed[:version]
+
+            mod_info = portal.get_mod_full(mod.name)
+            release = find_release(mod_info, version)
+
+            version_display = version == :latest ? "latest" : version.to_s
+            raise MODNotOnPortalError, "Release not found for #{mod}@#{version_display}" unless release
+
+            {mod:, mod_name: mod.name, mod_info:, release:, version:}
+          end
+
+          # Recursively resolve dependencies
+          #
+          # @param target_infos [Array<Hash>] Initial target MOD infos
+          # @param jobs [Integer] Number of parallel jobs
+          # @param presenter [Progress::Presenter] Progress presenter
+          # @return [Hash<String, Hash>] All MOD infos by name
+          private def resolve_dependencies(target_infos, jobs, presenter)
+            all_mod_infos = {}
+            to_process = []
+
+            target_infos.each do |info|
+              all_mod_infos[info[:mod_name]] = info
+              to_process << info[:mod_name]
+            end
+
+            processed = Set.new
+
+            until to_process.empty?
+              current_batch = to_process.shift(jobs)
+              current_batch.reject! {|mod_name| processed.include?(mod_name) }
+              break if current_batch.empty?
+
+              new_dependencies = collect_new_dependencies(current_batch, all_mod_infos, processed)
+              next if new_dependencies.empty?
+
+              presenter.increase_total(new_dependencies.size)
+              fetch_and_add_dependencies(new_dependencies, all_mod_infos, jobs, presenter)
+
+              new_dependencies.each do |dep|
+                to_process << dep[:mod_name] unless processed.include?(dep[:mod_name])
+              end
+            end
+
+            all_mod_infos
+          end
+
+          # Collect new dependencies from a batch of MODs
+          #
+          # @param batch [Array<String>] Batch of MOD names
+          # @param all_mod_infos [Hash] All MOD infos by name
+          # @param processed [Set<String>] Mark MODs as processed
+          # @return [Array<Hash>] New dependencies to fetch
+          private def collect_new_dependencies(batch, all_mod_infos, processed)
+            new_dependencies = []
+
+            batch.each do |mod_name|
+              processed.add(mod_name)
+
+              info = all_mod_infos[mod_name]
+              next unless info
+
+              deps = extract_required_dependencies(info[:release])
+              deps.each do |dep|
+                next if builtin_mod?(dep[:mod_name])
+                next if all_mod_infos.key?(dep[:mod_name])
+
+                new_dependencies << dep
+              end
+            end
+
+            new_dependencies
+          end
+
+          # Extract required dependencies from a release
+          #
+          # @param release [API::Release] Release object
+          # @return [Array<Hash>] Array of {mod_name:, version_requirement:, required_by:}
+          private def extract_required_dependencies(release)
+            info_json = release.info_json
+            return [] unless info_json
+
+            raw_deps = info_json["dependencies"] || info_json[:dependencies]
+            return [] unless raw_deps
+
+            dep_list = Dependency::List.from_strings(raw_deps)
+            dep_list.required.filter_map do |entry|
+              {mod_name: entry.mod.name, version_requirement: entry.version_requirement}
+            end
+          end
+
+          # Check if a MOD is a built-in MOD
+          #
+          # @param mod_name [String] MOD name
+          # @return [Boolean] true if built-in
+          private def builtin_mod?(mod_name) = %w[base elevated-rails quality space-age].include?(mod_name)
+
+          # Fetch and add dependencies
+          #
+          # @param dependencies [Array<Hash>] Dependencies to fetch
+          # @param all_mod_infos [Hash] Accumulator for all MOD infos
+          # @param jobs [Integer] Number of parallel jobs
+          # @param presenter [Progress::Presenter] Progress presenter
+          # @return [void]
+          private def fetch_and_add_dependencies(dependencies, all_mod_infos, jobs, presenter)
+            pool = Concurrent::FixedThreadPool.new(jobs)
+
+            futures = dependencies.map {|dep|
+              Concurrent::Future.execute(executor: pool) do
+                mod_info = portal.get_mod_full(dep[:mod_name])
+                release = find_compatible_release(mod_info, dep[:version_requirement])
+
+                unless release
+                  logger.warn("Skipping dependency #{dep[:mod_name]}: No compatible release found")
+                  presenter.update
+                  next nil
+                end
+
+                presenter.update
+
+                {mod_name: dep[:mod_name], mod_info:, release:}
+              rescue HTTPClientError => e
+                logger.warn("Skipping dependency #{dep[:mod_name]}: #{e.message}")
+                presenter.update
+                nil
+              rescue JSON::ParserError
+                logger.warn("Skipping dependency #{dep[:mod_name]}: Invalid API response")
+                presenter.update
+                nil
+              end
+            }
+
+            results = futures.filter_map(&:value!)
+            results.each {|result| all_mod_infos[result[:mod_name]] = result }
+          ensure
+            pool&.shutdown
+            pool&.wait_for_termination
+          end
+
+          # Build download targets from MOD infos
+          #
+          # @param all_mod_infos [Hash] All MOD infos by name
+          # @param download_dir [Pathname] Download directory
+          # @return [Array<Hash>] Download targets
+          private def build_download_targets(all_mod_infos, download_dir)
+            all_mod_infos.values.filter_map do |info|
+              release = info[:release]
+              validate_filename(release.file_name)
+
+              {
+                mod: Factorix::MOD[name: info[:mod_name]],
+                mod_info: info[:mod_info],
+                release:,
+                output_path: download_dir / release.file_name,
+                category: info[:mod_info].category
+              }
+            end
+          end
+
+          # Validate filename for security
+          #
+          # @param filename [String] Filename to validate
+          # @return [void]
+          # @raise [InvalidArgumentError] if filename is invalid
+          private def validate_filename(filename)
+            raise InvalidArgumentError, "Filename is empty" if filename.nil? || filename.empty?
+            raise InvalidArgumentError, "Filename contains path separators" if filename.include?(File::SEPARATOR)
+            raise InvalidArgumentError, "Filename contains path separators" if File::ALT_SEPARATOR && filename.include?(File::ALT_SEPARATOR)
+            raise InvalidArgumentError, "Filename contains parent directory reference" if filename.include?("..")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      module MOD
+        # Edit MOD metadata on Factorio MOD Portal
+        class Edit < Base
+          # @!parse
+          #   # @return [Portal]
+          #   attr_reader :portal
+          include Import[:portal]
+
+          desc "Edit MOD metadata on Factorio MOD Portal"
+
+          example [
+            'some-mod --title "New Title"         # Update MOD title',
+            "some-mod --category automation       # Update category",
+            "some-mod --deprecated                # Mark as deprecated"
+          ]
+
+          argument :mod_name, type: :string, required: true, desc: "MOD name"
+          option :description, type: :string, desc: "Markdown description"
+          option :summary, type: :string, desc: "Brief description"
+          option :title, type: :string, desc: "MOD title"
+          option :category, type: :string, desc: "MOD category"
+          option :tags, type: :array, desc: "Array of tags"
+          option :license, type: :string, desc: "License identifier"
+          option :homepage, type: :string, desc: "Homepage URL"
+          option :source_url, type: :string, desc: "Repository URL"
+          option :faq, type: :string, desc: "FAQ text"
+          option :deprecated, type: :boolean, desc: "Deprecation flag"
+
+          # Execute the edit command
+          #
+          # @param mod_name [String] the MOD name
+          # @param description [String, nil] optional description
+          # @param summary [String, nil] optional summary
+          # @param title [String, nil] optional title
+          # @param category [String, nil] optional category
+          # @param tags [Array<String>, nil] optional tags
+          # @param license [String, nil] optional license
+          # @param homepage [String, nil] optional homepage
+          # @param source_url [String, nil] optional source URL
+          # @param faq [String, nil] optional FAQ
+          # @param deprecated [Boolean, nil] optional deprecation flag
+          # @return [void]
+          def call(mod_name:, description: nil, summary: nil, title: nil, category: nil, tags: nil, license: nil, homepage: nil, source_url: nil, faq: nil, deprecated: nil, **)
+            validate_license!(license) if license
+
+            metadata = build_metadata(
+              description:,
+              summary:,
+              title:,
+              category:,
+              tags:,
+              license:,
+              homepage:,
+              source_url:,
+              faq:,
+              deprecated:
+            )
+
+            if metadata.empty?
+              say "At least one metadata option must be provided", prefix: :error
+              say "Available options: --description, --summary, --title, --category, --tags, --license, --homepage, --source-url, --faq, --deprecated"
+              raise InvalidArgumentError, "No metadata options provided"
+            end
+
+            portal.edit_mod(mod_name, **metadata)
+            say "Metadata updated successfully!", prefix: :success
+          end
+
+          # Build metadata hash from options
+          #
+          # @param description [String, nil] description
+          # @param summary [String, nil] summary
+          # @param title [String, nil] title
+          # @param category [String, nil] category
+          # @param tags [Array<String>, nil] tags
+          # @param license [String, nil] license
+          # @param homepage [String, nil] homepage
+          # @param source_url [String, nil] source URL
+          # @param faq [String, nil] FAQ
+          # @param deprecated [Boolean, nil] deprecation flag
+          # @return [Hash] metadata hash with symbol keys
+          private def build_metadata(description: nil, summary: nil, title: nil, category: nil, tags: nil, license: nil, homepage: nil, source_url: nil, faq: nil, deprecated: nil)
+            metadata = {}
+            metadata[:description] = description if description
+            metadata[:summary] = summary if summary
+            metadata[:title] = title if title
+            metadata[:category] = category if category
+            metadata[:tags] = tags if tags
+            metadata[:license] = license if license
+            metadata[:homepage] = homepage if homepage
+            metadata[:source_url] = source_url if source_url
+            metadata[:faq] = faq if faq
+            metadata[:deprecated] = deprecated unless deprecated.nil?
+            metadata
+          end
+
+          private def validate_license!(license)
+            return if API::License.valid_identifier?(license)
+
+            say "Invalid license identifier: #{license}", prefix: :error
+            say "Valid identifiers: #{API::License.identifier_values.join(", ")}"
+            say "Custom licenses: custom_<24 hex chars> (e.g., custom_0123456789abcdef01234567)"
+            raise InvalidArgumentError, "Invalid license identifier"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      module MOD
+        # Enable MODs in mod-list.json with dependency resolution
+        class Enable < Base
+          confirmable!
+          require_game_stopped!
+          backup_support!
+
+          # @!parse
+          #   # @return [Dry::Logger::Dispatcher]
+          #   attr_reader :logger
+          #   # @return [Factorix::Runtime]
+          #   attr_reader :runtime
+          include Import[:logger, :runtime]
+
+          desc "Enable MOD(s) in mod-list.json (recursively enables dependencies)"
+
+          example [
+            "some-mod         # Enable single MOD",
+            "mod-a mod-b      # Enable multiple MOD(s)"
+          ]
+
+          argument :mod_names, type: :array, required: true, desc: "MOD names to enable"
+
+          # Execute the enable command
+          #
+          # @param mod_names [Array<String>] MOD names to enable
+          # @return [void]
+          def call(mod_names:, **)
+            # Load current state (without validation to allow fixing issues)
+            mod_list = MODList.load
+            presenter = Progress::Presenter.new(title: "\u{1F50D}\u{FE0E} Scanning MOD(s)", output: $stderr)
+            handler = Progress::ScanHandler.new(presenter)
+            installed_mods = InstalledMOD.all(handler:)
+            graph = Dependency::Graph::Builder.build(installed_mods:, mod_list:)
+
+            # Convert MOD names to MOD objects
+            target_mods = mod_names.map {|name| Factorix::MOD[name:] }
+
+            # Validate target MODs exist
+            validate_target_mods_exist(target_mods, graph)
+
+            # Determine MODs to enable
+            mods_to_enable = plan_with_dependencies(target_mods, graph)
+
+            # Validate the plan (check for conflicts)
+            validate_plan(mods_to_enable, graph)
+
+            # Show plan to user
+            show_plan(mods_to_enable)
+
+            # Return early if nothing to enable
+            return if mods_to_enable.empty?
+
+            # Ask for confirmation
+            return unless confirm?("Do you want to enable these MOD(s)?")
+
+            # Execute the plan
+            execute_plan(mods_to_enable, mod_list)
+
+            # Save mod-list.json
+            backup_if_exists(runtime.mod_list_path)
+            mod_list.save
+            say "Enabled #{mods_to_enable.size} MOD(s)", prefix: :success
+            say "Saved mod-list.json", prefix: :success
+            logger.debug("Saved mod-list.json")
+          end
+
+          # Validate that all target MODs are installed
+          #
+          # @param target_mods [Array<Factorix::MOD>] MODs to validate
+          # @param graph [Factorix::Dependency::Graph] Dependency graph
+          # @return [void]
+          # @raise [MODNotFoundError] if any MOD is not installed
+          private def validate_target_mods_exist(target_mods, graph)
+            target_mods.each do |mod|
+              unless graph.node?(mod)
+                raise MODNotFoundError, "MOD '#{mod}' is not installed"
+              end
+            end
+          end
+
+          # Plan enable with automatic dependency resolution
+          #
+          # @param target_mods [Array<Factorix::MOD>] MODs to enable
+          # @param graph [Factorix::Dependency::Graph] Dependency graph
+          # @return [Array<Factorix::MOD>] MODs to enable (including dependencies)
+          # @raise [DependencyMissingError] if any dependency is not installed
+          # @raise [DependencyVersionError] if any dependency version requirement is not satisfied
+          private def plan_with_dependencies(target_mods, graph)
+            mods_to_enable = Set.new
+            to_process = target_mods.dup
+
+            while (mod = to_process.shift)
+              node = graph.node(mod)
+
+              if node.enabled?
+                logger.debug("MOD already enabled", mod_name: mod.name)
+                next
+              end
+
+              next if mods_to_enable.include?(mod)
+
+              mods_to_enable.add(mod)
+
+              graph.edges_from(mod).select(&:required?).each do |edge|
+                next if edge.to_mod.base?
+
+                dep_mod = edge.to_mod
+                dep_node = graph.node(dep_mod)
+
+                unless dep_node
+                  raise DependencyMissingError,
+                    "MOD '#{mod}' requires '#{dep_mod}' which is not installed"
+                end
+                unless edge.satisfied_by?(dep_node.version)
+                  raise DependencyVersionError,
+                    "Cannot enable #{mod}: dependency #{dep_mod} version requirement not satisfied " \
+                    "(required: #{edge.version_requirement}, installed: #{dep_node.version})"
+                end
+
+                # Add to process queue if not already enabled
+                to_process << dep_mod unless dep_node.enabled?
+              end
+            end
+
+            mods_to_enable.to_a
+          end
+
+          # Validate the enable plan
+          #
+          # Checks for conflicts with currently enabled MODs or MODs in the enable plan.
+          #
+          # @param mods_to_enable [Array<Factorix::MOD>] MODs to enable
+          # @param graph [Factorix::Dependency::Graph] Dependency graph
+          # @return [void]
+          # @raise [MODConflictError] if any conflict is detected
+          private def validate_plan(mods_to_enable, graph)
+            mods_to_enable_set = Set.new(mods_to_enable)
+
+            mods_to_enable.each do |mod|
+              # Check outgoing incompatibility edges (this MOD conflicts with others)
+              graph.edges_from(mod).select(&:incompatible?).each do |edge|
+                conflict_node = graph.node(edge.to_mod)
+
+                # Check if conflicting MOD is currently enabled
+                if conflict_node&.enabled?
+                  raise MODConflictError,
+                    "Cannot enable #{mod}: conflicts with #{edge.to_mod} which is currently enabled"
+                end
+
+                # Check if conflicting MOD is in the enable plan
+                if mods_to_enable_set.include?(edge.to_mod)
+                  raise MODConflictError,
+                    "Cannot enable #{mod}: conflicts with #{edge.to_mod} which is also being enabled"
+                end
+              end
+
+              # Check incoming incompatibility edges (other MODs conflict with this one)
+              graph.edges_to(mod).select(&:incompatible?).each do |edge|
+                conflict_node = graph.node(edge.from_mod)
+
+                # Check if conflicting MOD is currently enabled
+                if conflict_node&.enabled?
+                  raise MODConflictError,
+                    "Cannot enable #{mod}: conflicts with #{edge.from_mod} which is currently enabled"
+                end
+
+                # Check if conflicting MOD is in the enable plan
+                if mods_to_enable_set.include?(edge.from_mod)
+                  raise MODConflictError,
+                    "Cannot enable #{mod}: conflicts with #{edge.from_mod} which is also being enabled"
+                end
+              end
+            end
+          end
+
+          # Show the enable plan to user
+          #
+          # @param mods_to_enable [Array<Factorix::MOD>] MODs to enable
+          # @return [void]
+          private def show_plan(mods_to_enable)
+            if mods_to_enable.empty?
+              say "All specified MOD(s) are already enabled", prefix: :info
+              return
+            end
+
+            say "Planning to enable #{mods_to_enable.size} MOD(s):", prefix: :info
+            mods_to_enable.each do |mod|
+              say "  - #{mod}"
+            end
+          end
+
+          # Execute the enable plan
+          #
+          # @param mods_to_enable [Array<Factorix::MOD>] MODs to enable
+          # @param mod_list [Factorix::MODList] MOD list to modify
+          # @return [void]
+          private def execute_plan(mods_to_enable, mod_list)
+            return if mods_to_enable.empty?
+
+            mods_to_enable.each do |mod|
+              mod_list.enable(mod)
+              say "Enabled #{mod}", prefix: :success
+              logger.debug("Enabled MOD", mod_name: mod.name)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      module MOD
+        module Image
+          # Add an image to a MOD on Factorio MOD Portal
+          class Add < Base
+            # @!parse
+            #   # @return [Portal]
+            #   attr_reader :portal
+            include Import[:portal]
+
+            desc "Add an image to a MOD"
+
+            example [
+              "some-mod screenshot.png   # Add image to MOD"
+            ]
+
+            argument :mod_name, type: :string, required: true, desc: "MOD name"
+            argument :image_file, type: :string, required: true, desc: "Path to image file"
+
+            # Execute the add command
+            #
+            # @param mod_name [String] the MOD name
+            # @param image_file [String] path to image file
+            # @return [void]
+            def call(mod_name:, image_file:, **)
+              file_path = Pathname(image_file)
+
+              raise InvalidArgumentError, "Image file not found: #{image_file}" unless file_path.exist?
+
+              # Add image via Portal
+              image = portal.add_mod_image(mod_name, file_path)
+
+              say "Image added successfully!", prefix: :success
+              say "  ID: #{image.id}"
+              say "  Thumbnail: #{image.thumbnail}"
+              say "  Full URL: #{image.url}"
+            end
+          end
+        end
+      end
+    end
+  end
+end