factorix 0.5.0

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      # Mixin for commands that backup files before writing
+      #
+      # This module provides:
+      # - --backup-extension option to specify backup file extension
+      # - backup_if_exists method to backup a file before overwriting
+      #
+      # Prepend this module to commands that modify mod-list.json or mod-settings.dat
+      module BackupSupport
+        # Hook called when this module is prepended to a class
+        # @param base [Class] the class prepending this module
+        def self.prepended(base)
+          base.class_eval do
+            option :backup_extension, type: :string, default: ".bak", desc: "Backup file extension"
+          end
+        end
+
+        # Default backup extension
+        DEFAULT_BACKUP_EXTENSION = ".bak"
+        private_constant :DEFAULT_BACKUP_EXTENSION
+
+        # Store the --backup-extension option for use in backup_if_exists
+        # @param options [Hash] command options
+        def call(**options)
+          @backup_extension = options[:backup_extension] || DEFAULT_BACKUP_EXTENSION
+          super
+        end
+
+        # Backup existing file if it exists
+        #
+        # @param path [Pathname] File path to backup
+        # @return [void]
+        private def backup_if_exists(path)
+          return unless path.exist?
+
+          backup_path = Pathname("#{path}#{@backup_extension}")
+          path.rename(backup_path)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require "tint_me"
+
+module Factorix
+  class CLI
+    module Commands
+      # Base class for all CLI commands
+      #
+      # This class provides common functionality for all commands:
+      # - Common options (--config-path, --log-level, --quiet)
+      # - Common helper methods (say, quiet?)
+      # - Pre-call setup and error handling (via CommandWrapper prepended module)
+      #
+      # All command classes should inherit from this base class instead of
+      # directly from Dry::CLI::Command.
+      #
+      # @example Define a command
+      #   class MyCommand < Base
+      #     desc "My command description"
+      #
+      #     def call(**)
+      #       say "Hello, world!"
+      #     end
+      #   end
+      class Base < Dry::CLI::Command
+        # Emoji prefix mapping for common message types
+        EMOJI_PREFIXES = {
+          success: "\u{2713}",       # CHECK MARK
+          info: "\u{2139}",          # INFORMATION SOURCE
+          warn: "\u{26A0}\u{FE0E}",  # WARNING SIGN (text presentation)
+          error: "\u{2717}",         # BALLOT X
+          fatal: "\u{2620}\u{FE0E}"  # SKULL AND CROSSBONES (text presentation)
+        }.freeze
+        private_constant :EMOJI_PREFIXES
+
+        # Plain style (no-op) for default output
+        PLAIN = TIntMe::Style[]
+        private_constant :PLAIN
+
+        # Color styles for message prefixes
+        STYLES = {
+          success: TIntMe[:green],
+          info: TIntMe[:cyan],
+          warn: TIntMe[:magenta],
+          error: TIntMe[:red],
+          fatal: TIntMe[:red, :bold]
+        }.freeze
+        private_constant :STYLES
+
+        # Prepend CommandWrapper to each command class that inherits from Base
+        def self.inherited(subclass)
+          super
+          subclass.prepend CommandWrapper
+        end
+
+        # Require that the game is not running when this command executes
+        # @return [void]
+        def self.require_game_stopped! = prepend RequiresGameStopped
+
+        # Enable confirmation prompts with --yes option
+        # @return [void]
+        def self.confirmable! = prepend Confirmable
+
+        # Enable backup support for file modifications
+        # @return [void]
+        def self.backup_support! = prepend BackupSupport
+
+        # Common options available to all commands
+        option :config_path, type: :string, aliases: ["-c"], desc: "Path to configuration file"
+        option :log_level, type: :string, values: %w[debug info warn error fatal], desc: "Set log level"
+        option :quiet, type: :flag, default: false, aliases: ["-q"], desc: "Suppress non-essential output"
+
+        private def say(message, prefix: "")
+          return if quiet?
+
+          resolved_prefix = EMOJI_PREFIXES.fetch(prefix) { prefix.to_s }
+          output = resolved_prefix.empty? ? message : "#{resolved_prefix} #{message}"
+          style = STYLES.fetch(prefix, PLAIN)
+          puts style[output]
+        end
+
+        private def quiet?
+          @quiet == true
+        end
+      end
+    end
+  end
+end

data/lib/factorix/cli/commands/cache/evict.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      module Cache
+        # Evict cache entries
+        #
+        # This command removes cache entries based on the specified criteria.
+        # At least one of --all, --expired, or --older-than must be specified.
+        #
+        # @example
+        #   $ factorix cache evict --expired
+        #   $ factorix cache evict api --all
+        #   $ factorix cache evict download --older-than 7d
+        class Evict < Base
+          # @!parse
+          #   # @return [Dry::Logger::Dispatcher]
+          #   attr_reader :logger
+          include Import[:logger]
+          include Formatting
+
+          # Valid cache names for the caches argument
+          VALID_CACHES = %w[download api info_json].freeze
+          private_constant :VALID_CACHES
+
+          desc "Evict cache entries"
+
+          example [
+            "--expired              # Remove expired entries from all caches",
+            "api --all              # Remove all entries from api cache",
+            "download --older-than 7d  # Remove entries older than 7 days"
+          ]
+
+          argument :caches, type: :array, required: false, values: VALID_CACHES, desc: "Cache names"
+
+          option :all, type: :flag, default: false, desc: "Remove all entries"
+          option :expired, type: :flag, default: false, desc: "Remove expired entries only"
+          option :older_than, type: :string, default: nil, desc: "Remove entries older than AGE (e.g., 30s, 5m, 2h, 7d)"
+
+          # Execute the cache evict command
+          #
+          # @param caches [Array<String>, nil] cache names to evict
+          # @param all [Boolean] remove all entries
+          # @param expired [Boolean] remove expired entries only
+          # @param older_than [String, nil] remove entries older than this age
+          # @return [void]
+          def call(caches: nil, all: false, expired: false, older_than: nil, **)
+            validate_options!(all, expired, older_than)
+
+            @now = Time.now
+            @older_than_seconds = parse_age(older_than) if older_than
+
+            cache_names = resolve_cache_names(caches)
+            results = cache_names.to_h {|name| [name, evict_cache(name, all:, expired:)] }
+
+            output_results(results)
+          end
+
+          # Validate that exactly one eviction option is specified
+          #
+          # @param all [Boolean] --all option
+          # @param expired [Boolean] --expired option
+          # @param older_than [String, nil] --older-than option
+          # @return [void]
+          # @raise [InvalidArgumentError] if options are invalid
+          private def validate_options!(all, expired, older_than)
+            options_count = [all, expired, older_than].count {|opt| opt }
+
+            raise InvalidArgumentError, "One of --all, --expired, or --older-than must be specified" if options_count == 0
+            raise InvalidArgumentError, "Only one of --all, --expired, or --older-than can be specified" if options_count > 1
+          end
+
+          # Parse age string into seconds
+          #
+          # @param age [String] age string (e.g., "30s", "5m", "2h", "7d")
+          # @return [Integer] age in seconds
+          # @raise [InvalidArgumentError] if age format is invalid
+          DURATION_MULTIPLIERS = {"s" => 1, "m" => 60, "h" => 3600, "d" => 86400}.freeze
+          private_constant :DURATION_MULTIPLIERS
+
+          private def parse_age(age)
+            match = age.match(/\A(\d+)([smhd])\z/)
+            raise InvalidArgumentError, "Invalid age format: #{age}. Use format like 30s, 5m, 2h, 7d" unless match
+
+            value = Integer(match[1])
+            unit = match[2]
+
+            value * DURATION_MULTIPLIERS.fetch(unit)
+          end
+
+          # Resolve cache names from argument or return all
+          #
+          # @param caches [Array<String>, nil] cache names from argument
+          # @return [Array<Symbol>] resolved cache names
+          # @raise [InvalidArgumentError] if unknown cache name specified
+          private def resolve_cache_names(caches)
+            all_caches = Application.config.cache.values.keys
+
+            return all_caches if caches.nil? || caches.empty?
+
+            caches.map do |name|
+              sym = name.to_sym
+              raise InvalidArgumentError, "Unknown cache: #{name}. Valid caches: #{all_caches.join(", ")}" unless all_caches.include?(sym)
+
+              sym
+            end
+          end
+
+          # Evict entries from a single cache
+          #
+          # @param name [Symbol] cache name
+          # @param all [Boolean] remove all entries
+          # @param expired [Boolean] remove expired entries only
+          # @return [Hash] eviction result with :count and :size
+          private def evict_cache(name, all:, expired:)
+            config = Application.config.cache.public_send(name)
+            cache_dir = config.dir
+            ttl = config.ttl
+
+            return {count: 0, size: 0} unless cache_dir.exist?
+
+            count = 0
+            size = 0
+
+            cache_dir.glob("**/*").each do |path|
+              next unless path.file?
+              next if path.extname == ".lock"
+
+              next unless should_evict?(path, ttl, all:, expired:)
+
+              size += path.size
+              path.delete
+              count += 1
+              logger.debug("Evicted cache entry", path: path.to_s)
+            end
+
+            logger.info("Evicted cache entries", cache: name, count:, size:)
+            {count:, size:}
+          end
+
+          # Determine if a cache entry should be evicted
+          #
+          # @param path [Pathname] path to cache entry
+          # @param ttl [Integer, nil] cache TTL
+          # @param all [Boolean] remove all entries
+          # @param expired [Boolean] remove expired entries only
+          # @return [Boolean] true if entry should be evicted
+          private def should_evict?(path, ttl, all:, expired:)
+            return true if all
+
+            age_seconds = @now - path.mtime
+
+            if expired
+              return false if ttl.nil? # No TTL means never expires
+
+              age_seconds > ttl
+            else
+              # --older-than
+              age_seconds > @older_than_seconds
+            end
+          end
+
+          # Output eviction results
+          #
+          # @param results [Hash] results for each cache
+          # @return [void]
+          private def output_results(results)
+            # Calculate max width for alignment
+            max_name_width = results.keys.map {|k| k.to_s.length }.max
+
+            results.each do |name, data|
+              say "%-#{max_name_width}s: %3d entries removed (%s)" % [name, data[:count], format_size(data[:size])], prefix: :info
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/factorix/cli/commands/cache/stat.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Factorix
+  class CLI
+    module Commands
+      module Cache
+        # Display cache statistics
+        #
+        # This command outputs statistics for all cache stores
+        # in a human-readable or JSON format.
+        #
+        # @example
+        #   $ factorix cache stat
+        #   download:
+        #     Directory:      ~/.cache/factorix/download
+        #     TTL:            unlimited
+        #     Entries:        42 / 42 (100.0% valid)
+        #     ...
+        class Stat < Base
+          # @!parse
+          #   # @return [Dry::Logger::Dispatcher]
+          #   attr_reader :logger
+          include Import[:logger]
+          include Formatting
+
+          desc "Display cache statistics"
+
+          example [
+            "        # Display statistics in text format",
+            "--json  # Display statistics in JSON format"
+          ]
+
+          option :json, type: :flag, default: false, desc: "Output in JSON format"
+
+          # Execute the cache stat command
+          #
+          # @param json [Boolean] output in JSON format
+          # @return [void]
+          def call(json:, **)
+            logger.debug("Collecting cache statistics")
+
+            @now = Time.now
+            cache_names = Application.config.cache.values.keys
+            stats = cache_names.to_h {|name| [name, collect_stats(name)] }
+
+            if json
+              puts JSON.pretty_generate(stats)
+            else
+              output_text(stats)
+            end
+          end
+
+          private def collect_stats(name)
+            config = Application.config.cache.public_send(name)
+            cache_dir = config.dir
+
+            entries = scan_entries(cache_dir, config.ttl)
+
+            {
+              directory: cache_dir.to_s,
+              ttl: config.ttl,
+              max_file_size: config.max_file_size,
+              compression_threshold: config.compression_threshold,
+              entries: build_entry_stats(entries),
+              size: build_size_stats(entries),
+              age: build_age_stats(entries),
+              stale_locks: count_stale_locks(cache_dir)
+            }
+          end
+
+          # Scan cache directory and collect entry information
+          #
+          # @param cache_dir [Pathname] cache directory path
+          # @param ttl [Integer, nil] time-to-live in seconds
+          # @return [Array<Hash>] array of entry info hashes
+          private def scan_entries(cache_dir, ttl)
+            return [] unless cache_dir.exist?
+
+            entries = []
+            cache_dir.glob("**/*").each do |path|
+              next unless path.file?
+              next if path.extname == ".lock"
+
+              age_seconds = @now - path.mtime
+              expired = ttl ? age_seconds > ttl : false
+
+              entries << {size: path.size, age: age_seconds, expired:}
+            end
+            entries
+          end
+
+          # Build entry count statistics
+          #
+          # @param entries [Array<Hash>] entry info array
+          # @return [Hash] entry statistics
+          private def build_entry_stats(entries)
+            total = entries.size
+            valid = entries.count {|e| !e[:expired] }
+            expired = total - valid
+
+            {total:, valid:, expired:}
+          end
+
+          # Build size statistics
+          #
+          # @param entries [Array<Hash>] entry info array
+          # @return [Hash] size statistics
+          private def build_size_stats(entries)
+            return {total: 0, avg: 0, min: 0, max: 0} if entries.empty?
+
+            sizes = entries.map {|e| e[:size] }
+            {total: sizes.sum, avg: sizes.sum / sizes.size, min: sizes.min, max: sizes.max}
+          end
+
+          # Build age statistics
+          #
+          # @param entries [Array<Hash>] entry info array
+          # @return [Hash] age statistics
+          private def build_age_stats(entries)
+            return {oldest: nil, newest: nil, avg: nil} if entries.empty?
+
+            ages = entries.map {|e| e[:age] }
+            {oldest: ages.max, newest: ages.min, avg: ages.sum / ages.size}
+          end
+
+          # Count stale lock files
+          #
+          # @param cache_dir [Pathname] cache directory path
+          # @return [Integer] number of stale lock files
+          private def count_stale_locks(cache_dir)
+            return 0 unless cache_dir.exist?
+
+            lock_lifetime = Factorix::Cache::FileSystem::LOCK_FILE_LIFETIME
+            cache_dir.glob("**/*.lock").count {|path| @now - path.mtime > lock_lifetime }
+          end
+
+          # Output statistics in text format (ccache-style)
+          #
+          # @param stats [Hash] statistics for all caches
+          # @return [void]
+          private def output_text(stats)
+            stats.each_with_index do |(name, data), index|
+              puts if index > 0
+              puts "#{name}:"
+              output_cache_stats(data)
+            end
+          end
+
+          # Output statistics for a single cache
+          #
+          # @param data [Hash] cache statistics
+          # @return [void]
+          private def output_cache_stats(data)
+            puts "  Directory:      #{data[:directory]}"
+            puts "  TTL:            #{format_ttl(data[:ttl])}"
+            puts "  Max file size:  #{format_size(data[:max_file_size])}"
+            puts "  Compression:    #{format_compression(data[:compression_threshold])}"
+
+            entries = data[:entries]
+            valid_pct = entries[:total] > 0 ? (Float(entries[:valid]) / entries[:total] * 100) : 0.0
+            puts "  Entries:        #{entries[:valid]} / #{entries[:total]} (#{"%.1f" % valid_pct}% valid)"
+
+            size = data[:size]
+            puts "  Size:           #{format_size(size[:total])} (avg #{format_size(size[:avg])})"
+
+            age = data[:age]
+            if age[:oldest]
+              puts "  Age:            #{format_duration(age[:newest])} - #{format_duration(age[:oldest])} (avg #{format_duration(age[:avg])})"
+            else
+              puts "  Age:            -"
+            end
+
+            puts "  Stale locks:    #{data[:stale_locks]}"
+          end
+
+          # Format TTL value for display
+          #
+          # @param ttl [Integer, nil] TTL in seconds
+          # @return [String] formatted TTL
+          private def format_ttl(ttl)
+            ttl.nil? ? "unlimited" : format_duration(ttl)
+          end
+
+          # Format compression threshold for display
+          #
+          # @param threshold [Integer, nil] compression threshold in bytes
+          # @return [String] formatted compression setting
+          private def format_compression(threshold)
+            case threshold
+            when nil then "disabled"
+            when 0 then "enabled (always)"
+            else "enabled (>= #{format_size(threshold)})"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Factorix
+  class CLI
+    module Commands
+      # Module that wraps command execution to perform setup and error handling
+      #
+      # This module is prepended to Base to ensure configuration loading, log level
+      # setup, and consistent error handling happen for every command execution.
+      module CommandWrapper
+        # Performs setup before command execution, then calls the command's implementation
+        # Catches exceptions and displays user-friendly error messages
+        #
+        # @param options [Hash] command options including :config_path and :log_level
+        def call(**options)
+          @quiet = options[:quiet]
+
+          load_config!(options[:config_path])
+          log_level!(options[:log_level]) if options[:log_level]
+
+          super
+        rescue Error => e
+          # Expected errors (validation failures, missing dependencies, etc.)
+          log = Application[:logger]
+          log.warn(e.message)
+          log.debug(e)
+          say "Error: #{e.message}", prefix: :error unless @quiet
+          raise # Re-raise for exe/factorix to handle exit code
+        rescue => e
+          # Unexpected errors (bugs, system failures, etc.)
+          log = Application[:logger]
+          log.error(e)
+          say "Unexpected error: #{e.message}", prefix: :error unless @quiet
+          raise # Re-raise for exe/factorix to handle exit code
+        end
+
+        private def load_config!(explicit_path)
+          path = resolve_config_path(explicit_path)
+          return unless path
+
+          Application.load_config(path)
+        end
+
+        # Resolves which config path to use
+        # @param explicit_path [String, nil] path specified via --config-path
+        # @return [Pathname, nil] path to load, or nil if none should be loaded
+        private def resolve_config_path(explicit_path)
+          return Pathname(explicit_path) if explicit_path
+          return Pathname(ENV.fetch("FACTORIX_CONFIG")) if ENV["FACTORIX_CONFIG"]
+
+          default_path = Application[:runtime].factorix_config_path
+          default_path.exist? ? default_path : nil
+        end
+
+        # Sets the application logger's level
+        # @param level [String] log level (debug, info, warn, error, fatal)
+        private def log_level!(level)
+          logger = Application[:logger]
+          level_constant = Logger.const_get(level.upcase)
+
+          # Change only the File backend (first backend) level
+          # Dispatcher is always set to DEBUG to allow all messages through
+          file_backend = logger.backends.first
+          file_backend.level = level_constant if file_backend.respond_to?(:level=)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      # Generate shell completion script for factorix
+      #
+      # This command outputs a shell completion script that can be evaluated
+      # to enable command-line completion for factorix.
+      #
+      # @example Enable completion (auto-detect shell)
+      #   eval "$(factorix completion)"
+      # @example Enable completion for specific shell
+      #   eval "$(factorix completion zsh)"
+      class Completion < Base
+        # Directory containing completion scripts
+        COMPLETION_DIR = Pathname(__dir__).join("../../../../completion").freeze
+        private_constant :COMPLETION_DIR
+
+        # Supported shells and their script filenames
+        SUPPORTED_SHELLS = {
+          "bash" => "_factorix.bash",
+          "fish" => "_factorix.fish",
+          "zsh" => "_factorix.zsh"
+        }.freeze
+        private_constant :SUPPORTED_SHELLS
+
+        desc "Generate shell completion script"
+
+        argument :shell,
+          type: :string,
+          required: false,
+          values: SUPPORTED_SHELLS.keys,
+          desc: "Shell type. Defaults to current shell from $SHELL"
+
+        example [
+          "            # Output completion script for current shell",
+          "bash        # Output bash completion script",
+          "fish        # Output fish completion script",
+          "zsh         # Output zsh completion script"
+        ]
+
+        # Execute the completion command
+        #
+        # @param shell [String, nil] Shell type (zsh, bash, fish)
+        # @return [void]
+        # @raise [InvalidArgumentError] if shell type cannot be detected or is unsupported
+        # @raise [ConfigurationError] if completion script not found
+        def call(shell: nil, **)
+          shell_type = shell || detect_shell
+          validate_shell!(shell_type)
+
+          script_path = COMPLETION_DIR / SUPPORTED_SHELLS[shell_type]
+          raise ConfigurationError, "#{shell_type.capitalize} completion script not found" unless script_path.exist?
+
+          puts script_path.read
+        end
+
+        # Detect shell type from SHELL environment variable
+        #
+        # @return [String] Detected shell type
+        private def detect_shell
+          shell_path = ENV.fetch("SHELL", "")
+          shell_name = File.basename(shell_path)
+
+          return shell_name if SUPPORTED_SHELLS.key?(shell_name)
+
+          raise InvalidArgumentError, "Cannot detect shell type from SHELL=#{shell_path}. Please specify: #{SUPPORTED_SHELLS.keys.join(", ")}"
+        end
+
+        # Validate shell type
+        #
+        # @param shell [String] Shell type to validate
+        # @raise [InvalidArgumentError] If shell type is not supported
+        private def validate_shell!(shell)
+          return if SUPPORTED_SHELLS.key?(shell)
+
+          raise InvalidArgumentError, "Unsupported shell: #{shell}. Supported shells: #{SUPPORTED_SHELLS.keys.join(", ")}"
+        end
+      end
+    end
+  end
+end