factorix 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1d6b99d769a238f64676cfd19aef4d0f8852d2dc38df210eb753a8bc202f67f
-  data.tar.gz: c51b472d2eb47e7d0d39c4789112da30faf5fbf7e225da330d19e989bce86f43
+  metadata.gz: 3cc75b1211b8487fb9f93c19751c2086415385d32356282dfd3d71ef4158fdd1
+  data.tar.gz: 8d55640b9704c518ec15660cf17604b6f89b96356bee3044e5e663d28afebca0
 SHA512:
-  metadata.gz: 0e9bf68578d26f4b08e77028b1da59ff8d972f807822be5fa19ca1eb951e89412a3314a3db5fde1fcd821f399ee6c9e4e8c28e37d2d0c5e3d000046c5e663d2f
-  data.tar.gz: 81222393a0ab0a6b6e2cbbccac52dec243d4806ef688a1240a01367142094e368175caba564d4842ebd627ebdef98e322f8217b14a3424e8e20c7bbeddc248a4
+  metadata.gz: 638164922741c6f7225125b1c1f676c21adc5253e7ab1e40a99c0c6baef3f1e3d554097a254cf3cc4cb0ffc4e055c9153c4a37132222216ea00097cbf24f044c
+  data.tar.gz: dfc7c5bce1df717c321f2189d78486a0443d640e7c32571dd0038b07f34c7be5da68b72e5aa12c9ed1de59ca55531b37937a4cc9194d15aea88ff6a834d6cd95

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.8.0] - 2026-02-03
+
+### Added
+
+- Add `download` command to download Factorio game files from the official Download API (#51)
+  - Supports alpha, expansion, demo, and headless builds
+  - Auto-detects platform (Windows, Linux, macOS, WSL)
+  - Resolves latest version from stable/experimental channels
+- Add `head` method to HTTP client and decorators (`Client`, `RetryDecorator`, `CacheDecorator`)
+
 ## [0.7.0] - 2026-01-24
 
 ### Added

data/README.md

@@ -20,6 +20,7 @@ Factorix simplifies Factorio MOD management by providing:
 - **Settings Management**: Export/import MOD settings in JSON format
 - **MOD Portal Integration**: Upload new MODs or update existing ones, edit metadata
 - **Game Control**: Launch Factorio from the command line
+- **Game Download**: Download Factorio game files (alpha, expansion, demo, headless)
 - **Cross-platform Support**: Works on Windows, Linux, macOS, and WSL
 
 ## Requirements
@@ -38,6 +39,8 @@ export FACTORIO_API_KEY=your_api_key_here
 
 API key is not required for downloading, installing, or managing local MODs.
 
+For downloading the game itself (`factorix download`), service credentials are required. These are automatically loaded from `player-data.json` if you have logged into Factorio, or you can set `FACTORIO_USERNAME` and `FACTORIO_TOKEN` environment variables.
+
 ## Configuration
 
 ### Path Configuration

data/completion/_factorix.bash

@@ -17,7 +17,7 @@ _factorix() {
   local confirmable_opts="-y --yes"
 
   # Top-level commands
-  local commands="version man launch path mod cache completion"
+  local commands="version man launch path download mod cache completion"
 
   # mod subcommands
   local mod_commands="check list show enable disable install uninstall update download upload edit search sync image settings"
@@ -52,6 +52,20 @@ _factorix() {
       fi
       return
       ;;
+    download)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=($(compgen -W "$global_opts -b --build -p --platform -c --channel -d --directory -o --output" -- "$cur"))
+      elif [[ "$prev" == "--build" ]] || [[ "$prev" == "-b" ]]; then
+        COMPREPLY=($(compgen -W "alpha expansion demo headless" -- "$cur"))
+      elif [[ "$prev" == "--platform" ]] || [[ "$prev" == "-p" ]]; then
+        COMPREPLY=($(compgen -W "win64 win64-manual osx linux64" -- "$cur"))
+      elif [[ "$prev" == "--channel" ]] || [[ "$prev" == "-c" ]]; then
+        COMPREPLY=($(compgen -W "stable experimental" -- "$cur"))
+      elif [[ "$prev" == "--directory" ]] || [[ "$prev" == "-d" ]]; then
+        COMPREPLY=($(compgen -d -- "$cur"))
+      fi
+      return
+      ;;
     cache)
       if [[ $cword -eq 2 ]]; then
         COMPREPLY=($(compgen -W "$cache_commands" -- "$cur"))

data/completion/_factorix.fish

@@ -73,13 +73,14 @@ complete -c factorix -l log-level -d 'Set log level' -xa 'debug info warn error
 complete -c factorix -s q -l quiet -d 'Suppress non-essential output'
 
 # Top-level commands
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a version -d 'Display Factorix version'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a man -d 'Display the Factorix manual page'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a launch -d 'Launch Factorio game'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a path -d 'Display Factorio and Factorix paths'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a mod -d 'MOD management commands'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a cache -d 'Cache management commands'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a completion -d 'Generate shell completion script'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a version -d 'Display Factorix version'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a man -d 'Display the Factorix manual page'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a launch -d 'Launch Factorio game'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a path -d 'Display Factorio and Factorix paths'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a download -d 'Download Factorio game files'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a mod -d 'MOD management commands'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a cache -d 'Cache management commands'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a completion -d 'Generate shell completion script'
 
 # launch options
 complete -c factorix -n "__factorix_using_command launch" -s w -l wait -d 'Wait for the game to finish'
@@ -90,6 +91,13 @@ complete -c factorix -n "__factorix_using_command path" -l json -d 'Output in JS
 # completion shell argument
 complete -c factorix -n "__factorix_using_command completion" -a 'zsh bash fish' -d 'Shell type'
 
+# download options
+complete -c factorix -n "__factorix_using_command download" -s b -l build -d 'Build type' -xa 'alpha expansion demo headless'
+complete -c factorix -n "__factorix_using_command download" -s p -l platform -d 'Platform' -xa 'win64 win64-manual osx linux64'
+complete -c factorix -n "__factorix_using_command download" -s c -l channel -d 'Release channel' -xa 'stable experimental'
+complete -c factorix -n "__factorix_using_command download" -s d -l directory -d 'Download directory' -ra '(__fish_complete_directories)'
+complete -c factorix -n "__factorix_using_command download" -s o -l output -d 'Output filename' -r
+
 # cache subcommands
 complete -c factorix -n "__factorix_using_command cache" -a stat -d 'Display cache statistics'
 complete -c factorix -n "__factorix_using_command cache" -a evict -d 'Evict cache entries'

data/completion/_factorix.zsh

@@ -39,6 +39,7 @@ _factorix() {
         'man:Display the Factorix manual page'
         'launch:Launch Factorio game'
         'path:Display Factorio and Factorix paths'
+        'download:Download Factorio game files'
         'mod:MOD management commands'
         'cache:Cache management commands'
         'completion:Generate shell completion script'
@@ -61,6 +62,9 @@ _factorix() {
             $global_opts \
             '--json[Output in JSON format]'
           ;;
+        download)
+          _factorix_download
+          ;;
         completion)
           _factorix_completion
           ;;
@@ -88,6 +92,24 @@ _factorix_completion() {
     '1:shell:(zsh bash fish)'
 }
 
+_factorix_download() {
+  local -a global_opts
+  global_opts=(
+    '(-c --config-path)'{-c,--config-path}'[Path to configuration file]:config file:_files'
+    '--log-level[Set log level]:level:(debug info warn error fatal)'
+    '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+  )
+
+  _arguments \
+    $global_opts \
+    '(-b --build)'{-b,--build}'[Build type]:build:(alpha expansion demo headless)' \
+    '(-p --platform)'{-p,--platform}'[Platform]:platform:(win64 win64-manual osx linux64)' \
+    '(-c --channel)'{-c,--channel}'[Release channel]:channel:(stable experimental)' \
+    '(-d --directory)'{-d,--directory}'[Download directory]:directory:_files -/' \
+    '(-o --output)'{-o,--output}'[Output filename]:filename:' \
+    '1:version:'
+}
+
 _factorix_mod() {
   local context state state_descr line
   typeset -A opt_args

data/lib/factorix/api/game_download_api.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Factorix
+  module API
+    # API client for downloading Factorio game files
+    #
+    # Corresponds to: https://wiki.factorio.com/Download_API
+    class GameDownloadAPI
+      # @!parse
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      #   # @return [HTTP::Client]
+      #   attr_reader :client
+      include Import[:logger, client: :api_http_client]
+
+      # Base URL for game downloads
+      DOWNLOAD_BASE_URL = "https://www.factorio.com"
+      private_constant :DOWNLOAD_BASE_URL
+
+      # Base URL for API endpoints
+      API_BASE_URL = "https://factorio.com"
+      private_constant :API_BASE_URL
+
+      # Valid build types
+      BUILDS = %w[alpha expansion demo headless].freeze
+      public_constant :BUILDS
+
+      # Valid platforms
+      PLATFORMS = %w[win64 win64-manual osx linux64].freeze
+      public_constant :PLATFORMS
+
+      # Valid release channels
+      CHANNELS = %w[stable experimental].freeze
+      public_constant :CHANNELS
+
+      # Initialize with thread-safe credential loading
+      #
+      # @param args [Hash] dependency injection arguments
+      def initialize(...)
+        super
+        @service_credential_mutex = Mutex.new
+      end
+
+      # Fetch latest release information
+      #
+      # @return [Hash{Symbol => Hash}] Hash containing stable and experimental release info
+      # @example Response format
+      #   {
+      #     stable: { alpha: "2.0.28", expansion: "2.0.28", headless: "2.0.28" },
+      #     experimental: { alpha: "2.0.29", expansion: "2.0.29", headless: "2.0.29" }
+      #   }
+      def latest_releases
+        logger.debug "Fetching latest releases"
+        uri = URI.join(API_BASE_URL, "/api/latest-releases")
+        response = client.get(uri)
+        JSON.parse((+response.body).force_encoding(Encoding::UTF_8), symbolize_names: true)
+      end
+
+      # Get the latest version for a specific channel and build
+      #
+      # @param channel [String] Release channel (stable, experimental)
+      # @param build [String] Build type (alpha, expansion, demo, headless)
+      # @return [String, nil] Version string or nil if not available
+      def latest_version(channel:, build:)
+        releases = latest_releases
+        releases.dig(channel.to_sym, build.to_sym)
+      end
+
+      # Resolve the download filename by making a HEAD request
+      #
+      # @param version [String] Game version (e.g., "2.0.28")
+      # @param build [String] Build type (alpha, expansion, demo, headless)
+      # @param platform [String] Platform (win64, win64-manual, osx, linux64)
+      # @return [String] Filename extracted from final redirect URL
+      # @raise [ArgumentError] if build or platform is invalid
+      def resolve_filename(version:, build:, platform:)
+        validate_build!(build)
+        validate_platform!(platform)
+
+        uri = build_download_uri(version, build, platform)
+        response = client.head(uri)
+        File.basename(response.uri.path)
+      end
+
+      # Download the game to the specified output path
+      #
+      # @param version [String] Game version (e.g., "2.0.28")
+      # @param build [String] Build type (alpha, expansion, demo, headless)
+      # @param platform [String] Platform (win64, win64-manual, osx, linux64)
+      # @param output [Pathname] Output file path
+      # @param handler [Object, nil] Event handler for download progress (optional)
+      # @return [void]
+      # @raise [ArgumentError] if build or platform is invalid
+      def download(version:, build:, platform:, output:, handler: nil)
+        validate_build!(build)
+        validate_platform!(platform)
+
+        uri = build_download_uri(version, build, platform)
+        downloader = Container[:downloader]
+        downloader.subscribe(handler) if handler
+        begin
+          downloader.download(uri, output)
+        ensure
+          downloader.unsubscribe(handler) if handler
+        end
+      end
+
+      # Build the download URI with authentication
+      #
+      # @param version [String] Game version
+      # @param build [String] Build type
+      # @param platform [String] Platform
+      # @return [URI::HTTPS] Complete download URI with credentials
+      private def build_download_uri(version, build, platform)
+        path = "/get-download/#{version}/#{build}/#{platform}"
+        uri = URI.join(DOWNLOAD_BASE_URL, path)
+        params = {username: service_credential.username, token: service_credential.token}
+        uri.query = URI.encode_www_form(params)
+        uri
+      end
+
+      private def service_credential
+        return @service_credential if defined?(@service_credential)
+
+        @service_credential_mutex.synchronize do
+          @service_credential ||= Container[:service_credential]
+        end
+      end
+
+      # Validate build type
+      #
+      # @param build [String] Build type to validate
+      # @raise [ArgumentError] if build type is invalid
+      private def validate_build!(build)
+        return if BUILDS.include?(build)
+
+        raise ArgumentError, "Invalid build type: #{build}. Valid types: #{BUILDS.join(", ")}"
+      end
+
+      # Validate platform
+      #
+      # @param platform [String] Platform to validate
+      # @raise [ArgumentError] if platform is invalid
+      private def validate_platform!(platform)
+        return if PLATFORMS.include?(platform)
+
+        raise ArgumentError, "Invalid platform: #{platform}. Valid platforms: #{PLATFORMS.join(", ")}"
+      end
+    end
+  end
+end

data/lib/factorix/api/mod_info.rb

@@ -152,7 +152,7 @@ module Factorix
 
         # Filter detail_fields to only include keys that Detail.new accepts
         # Exclude deprecated fields like github_path
-        detail = Detail.new(**detail_fields.slice(*DETAIL_ALLOWED_KEYS)) if all_required_detail_fields?(detail_fields)
+        detail = Detail[**detail_fields.slice(*DETAIL_ALLOWED_KEYS)] if all_required_detail_fields?(detail_fields)
 
         super(name:, title:, owner:, summary:, downloads_count:, category:, score:, thumbnail:, latest_release:, releases:, detail:)
       end

data/lib/factorix/cache/file_system.rb

@@ -273,11 +273,11 @@ module Factorix
 
           logical_key = JSON.parse(metadata_path.read)["logical_key"]
           age = Time.now - path.mtime
-          entry = Entry.new(
+          entry = Entry[
             size: path.size,
             age:,
             expired: @ttl ? age > @ttl : false
-          )
+          ]
 
           yield logical_key, entry
         end

data/lib/factorix/cache/redis.rb

@@ -223,11 +223,11 @@ module Factorix
             logical_key = logical_key_from_data_key(data_k)
             meta = @redis.hgetall(meta_key(logical_key))
 
-            entry = Entry.new(
+            entry = Entry[
               size: meta["size"] ? Integer(meta["size"], 10) : 0,
               age: meta["created_at"] ? Time.now.to_i - Integer(meta["created_at"], 10) : 0,
               expired: false # Redis handles expiry natively
-            )
+            ]
 
             yield logical_key, entry
           end

data/lib/factorix/cache/s3.rb

@@ -360,11 +360,11 @@ module Factorix
         age = Time.now - obj.last_modified
         expired = check_expired_from_head_response(resp)
 
-        entry = Entry.new(
+        entry = Entry[
           size: obj.size,
           age:,
           expired:
-        )
+        ]
 
         [logical_key, entry]
       rescue Aws::S3::Errors::NotFound

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      # Download Factorio game files from the official download API
+      class Download < Base
+        # @!parse
+        #   # @return [Dry::Logger::Dispatcher]
+        #   attr_reader :logger
+        #   # @return [Runtime]
+        #   attr_reader :runtime
+        #   # @return [API::GameDownloadAPI]
+        #   attr_reader :game_download_api
+        include Import[:logger, :runtime, :game_download_api]
+
+        # Platform mapping from Runtime to API platform identifier
+        PLATFORM_MAP = {
+          "MacOS" => "osx",
+          "Linux" => "linux64",
+          "Windows" => "win64",
+          "WSL" => "win64"
+        }.freeze
+        private_constant :PLATFORM_MAP
+
+        desc "Download Factorio game files"
+
+        argument :version, required: false, default: "latest", desc: "Version (e.g., 2.0.73, latest)"
+
+        option :build, aliases: ["-b"], default: "alpha", values: API::GameDownloadAPI::BUILDS, desc: "Build type"
+        option :platform, aliases: ["-p"], values: API::GameDownloadAPI::PLATFORMS, desc: "Platform (default: auto-detect)"
+        option :channel, aliases: ["-c"], default: "stable", values: API::GameDownloadAPI::CHANNELS, desc: "Release channel"
+        option :directory, aliases: ["-d"], default: ".", desc: "Download directory"
+        option :output, aliases: ["-o"], desc: "Output filename (default: from server)"
+
+        example [
+          "                           # Download latest stable version (auto-detect platform)",
+          "2.0.73                     # Download specific version",
+          "--build expansion          # Download expansion build",
+          "--build headless -p linux64 # Download headless server for Linux",
+          "--channel experimental     # Download experimental release",
+          "-o factorio-server.tar.xz  # Specify output filename"
+        ]
+
+        # Execute the download command
+        #
+        # @param version [String] Version to download
+        # @param build [String] Build type
+        # @param platform [String, nil] Platform (nil for auto-detect)
+        # @param channel [String] Release channel
+        # @param directory [String] Download directory
+        # @param output [String, nil] Output filename
+        # @return [void]
+        def call(version: "latest", build: "alpha", platform: nil, channel: "stable", directory: ".", output: nil, **)
+          platform ||= detect_platform
+          resolved_version = resolve_version(version, channel, build)
+
+          download_dir = Pathname(directory).expand_path
+          raise DirectoryNotFoundError, "Download directory does not exist: #{download_dir}" unless download_dir.exist?
+
+          filename = output || resolve_filename(resolved_version, build, platform)
+          output_path = download_dir / filename
+
+          say "Downloading Factorio #{resolved_version} (#{build}/#{platform})...", prefix: :info
+
+          download_game(resolved_version, build, platform, output_path)
+
+          say "Downloaded to #{output_path}", prefix: :success
+        end
+
+        # Detect platform from Runtime
+        #
+        # @return [String] Platform identifier
+        private def detect_platform
+          runtime_class = runtime.class.name.split("::").last
+          platform = PLATFORM_MAP[runtime_class]
+          raise UnsupportedPlatformError, "Cannot auto-detect platform for #{runtime_class}" unless platform
+
+          logger.debug("Auto-detected platform", platform:)
+          platform
+        end
+
+        # Minimum supported major version
+        MINIMUM_MAJOR_VERSION = 2
+        private_constant :MINIMUM_MAJOR_VERSION
+
+        # Resolve version, handling "latest" by fetching from API
+        #
+        # @param version [String] Version or "latest"
+        # @param channel [String] Release channel
+        # @param build [String] Build type
+        # @return [String] Resolved version
+        # @raise [InvalidArgumentError] if version is invalid or < 2.0
+        private def resolve_version(version, channel, build)
+          resolved = if version == "latest"
+                       v = game_download_api.latest_version(channel:, build:)
+                       raise InvalidArgumentError, "No #{channel} version available for #{build}" unless v
+
+                       logger.debug("Resolved latest version", channel:, build:, version: v)
+                       v
+                     else
+                       version
+                     end
+
+          validate_version!(resolved)
+          resolved
+        end
+
+        # Validate version format and minimum version requirement
+        #
+        # @param version [String] Version string
+        # @return [void]
+        # @raise [InvalidArgumentError] if version is invalid or < 2.0
+        private def validate_version!(version)
+          game_version = GameVersion.from_string(version)
+
+          return if game_version.major >= MINIMUM_MAJOR_VERSION
+
+          raise InvalidArgumentError, "Version #{version} is not supported. Minimum version is #{MINIMUM_MAJOR_VERSION}.0.0"
+        rescue VersionParseError => e
+          raise InvalidArgumentError, "Invalid version format: #{e.message}"
+        end
+
+        # Resolve filename by making HEAD request
+        #
+        # @param version [String] Version
+        # @param build [String] Build type
+        # @param platform [String] Platform
+        # @return [String] Filename
+        private def resolve_filename(version, build, platform)
+          game_download_api.resolve_filename(version:, build:, platform:)
+        end
+
+        # Download the game with progress tracking
+        #
+        # @param version [String] Version
+        # @param build [String] Build type
+        # @param platform [String] Platform
+        # @param output_path [Pathname] Output file path
+        # @return [void]
+        private def download_game(version, build, platform, output_path)
+          presenter = Progress::Presenter.new(title: output_path.basename.to_s, output: err)
+          handler = Progress::DownloadHandler.new(presenter)
+
+          game_download_api.download(version:, build:, platform:, output: output_path, handler:)
+        end
+      end
+    end
+  end
+end

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

@@ -147,7 +147,7 @@ module Factorix
               enabled = mod_list.exist?(mod) && mod_list.enabled?(mod)
               error = error_map[mod.name]
 
-              MODInfo.new(name: mod.name, version: display_version, enabled:, error:, latest_version: nil)
+              MODInfo[name: mod.name, version: display_version, enabled:, error:, latest_version: nil]
             }
           end
 
@@ -256,13 +256,13 @@ module Factorix
           private def fetch_latest_version_for_mod(info)
             portal_info = mod_portal_api.get_mod(info.name)
             latest = portal_info[:releases]&.map {|r| MODVersion.from_string(r[:version]) }&.max
-            MODInfo.new(
+            MODInfo[
               name: info.name,
               version: info.version,
               enabled: info.enabled,
               error: info.error,
               latest_version: latest
-            )
+            ]
           rescue MODNotOnPortalError
             logger.debug("MOD not found on portal", mod: info.name)
             info

data/lib/factorix/cli.rb

@@ -17,6 +17,7 @@ module Factorix
     register "man", Commands::Man
     register "launch", Commands::Launch
     register "path", Commands::Path
+    register "download", Commands::Download
     register "completion", Commands::Completion
     register "mod check", Commands::MOD::Check
     register "mod list", Commands::MOD::List

data/lib/factorix/container.rb

@@ -136,6 +136,11 @@ module Factorix
       API::MODDownloadAPI.new
     end
 
+    # Register Game Download API client
+    register(:game_download_api, memoize: true) do
+      API::GameDownloadAPI.new
+    end
+
     # Register API credential (for MOD upload/management)
     register(:api_credential, memoize: true) { APICredential.load }
 

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

@@ -53,7 +53,7 @@ module Factorix
           version = select_version_for_mod(mod)
           enabled = mod_enabled?(mod)
 
-          node = Node.new(mod:, version:, enabled:, installed: true)
+          node = Node[mod:, version:, enabled:, installed: true]
           graph.add_node(node)
         end
 
@@ -88,7 +88,7 @@ module Factorix
             # 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)
+            edge = Edge[from_mod:, to_mod: dependency.mod, type: dependency.type, version_requirement: dependency.version_requirement]
             graph.add_edge(edge)
           end
         end

data/lib/factorix/dependency/graph.rb

@@ -75,7 +75,7 @@ module Factorix
           return
         end
 
-        node = Node.new(mod:, version: release.version, enabled: false, installed: false, operation:)
+        node = Node[mod:, version: release.version, enabled: false, installed: false, operation:]
         add_node(node)
 
         dependencies = release.info_json[:dependencies] || []
@@ -85,7 +85,7 @@ module Factorix
           dependency = parser.parse(dep_string)
           next if dependency.mod.base?
 
-          edge = Edge.new(from_mod: mod, to_mod: dependency.mod, type: dependency.type, version_requirement: dependency.version_requirement)
+          edge = Edge[from_mod: mod, to_mod: dependency.mod, type: dependency.type, version_requirement: dependency.version_requirement]
 
           add_edge(edge)
         end

data/lib/factorix/dependency/validation_result.rb

@@ -81,7 +81,7 @@ module Factorix
       # @param mod [Factorix::MOD, nil] Related MOD
       # @param dependency [Factorix::MOD, nil] Dependency MOD
       # @return [void]
-      def add_error(type:, message:, mod: nil, dependency: nil) = @errors << Error.new(type:, message:, mod:, dependency:)
+      def add_error(type:, message:, mod: nil, dependency: nil) = @errors << Error[type:, message:, mod:, dependency:]
 
       # Add a warning
       #
@@ -89,7 +89,7 @@ module Factorix
       # @param message [String] Warning message
       # @param mod [Factorix::MOD, nil] Related MOD
       # @return [void]
-      def add_warning(type:, message:, mod: nil) = @warnings << Warning.new(type:, message:, mod:)
+      def add_warning(type:, message:, mod: nil) = @warnings << Warning[type:, message:, mod:]
 
       # Add a suggestion
       #
@@ -97,7 +97,7 @@ module Factorix
       # @param mod [Factorix::MOD] Related MOD
       # @param version [Factorix::MODVersion] Suggested version
       # @return [void]
-      def add_suggestion(message:, mod:, version:) = @suggestions << Suggestion.new(message:, mod:, version:)
+      def add_suggestion(message:, mod:, version:) = @suggestions << Suggestion[message:, mod:, version:]
 
       # Get all errors
       #

data/lib/factorix/http/cache_decorator.rb

@@ -56,7 +56,7 @@ module Factorix
         if cached_body
           logger.debug("Cache hit", uri: uri.to_s)
           publish("cache.hit", url: uri.to_s)
-          return CachedResponse.new(cached_body)
+          return CachedResponse.new(cached_body, uri:)
         end
 
         logger.debug("Cache miss", uri: uri.to_s)
@@ -68,7 +68,7 @@ module Factorix
           cached_body = cache.read(cache_key)
           if cached_body
             publish("cache.hit", url: uri.to_s)
-            return CachedResponse.new(cached_body)
+            return CachedResponse.new(cached_body, uri:)
           end
 
           response = client.get(uri, headers:)
@@ -94,6 +94,13 @@ module Factorix
       # @return [Response] response object
       def post(uri, body:, headers: {}, content_type: nil) = client.post(uri, body:, headers:, content_type:)
 
+      # Execute a HEAD request (never cached)
+      #
+      # @param uri [URI::HTTPS] target URI
+      # @param headers [Hash<String, String>] request headers
+      # @return [Response] response object
+      def head(uri, headers: {}) = client.head(uri, headers:)
+
       private def with_temporary_file
         temp_file = Tempfile.new("http_cache")
         yield temp_file

data/lib/factorix/http/cached_response.rb

@@ -12,12 +12,15 @@ module Factorix
       attr_reader :body
       attr_reader :code
       attr_reader :headers
+      attr_reader :uri
 
       # @param body [String] cached response body
-      def initialize(body)
+      # @param uri [URI, nil] original request URI (not stored in cache, always nil)
+      def initialize(body, uri: nil)
         @body = body
         @code = 200
         @headers = {"content-type" => ["application/octet-stream"]}
+        @uri = uri
       end
 
       # Always returns true for cached responses

data/lib/factorix/http/client.rb

@@ -58,6 +58,13 @@ module Factorix
       # @return [Response] response object
       def get(uri, headers: {}, &) = request(:get, uri, headers:, &)
 
+      # Execute a HEAD request
+      #
+      # @param uri [URI::HTTPS] target URI
+      # @param headers [Hash<String, String>] request headers
+      # @return [Response] response object
+      def head(uri, headers: {}) = request(:head, uri, headers:)
+
       # Execute a POST request
       #
       # @param uri [URI::HTTPS] target URI
@@ -86,18 +93,20 @@ module Factorix
         result
       end
 
-      private def handle_response(response, _method, _uri, redirect_count, &block)
+      private def handle_response(response, method, uri, redirect_count, &block)
         case response
         when Net::HTTPSuccess, Net::HTTPPartialContent
           yield(response) if block
-          Response.new(response)
+          Response.new(response, uri:)
 
         when Net::HTTPRedirection
           location = response["Location"]
           redirect_url = URI(location)
           logger.info("Following redirect", location: mask_credentials(redirect_url))
 
-          perform_request(:get, redirect_url, redirect_count: redirect_count + 1, headers: {}, body: nil, &block)
+          # HEAD stays HEAD, others become GET (standard redirect behavior)
+          redirect_method = method == :head ? :head : :get
+          perform_request(redirect_method, redirect_url, redirect_count: redirect_count + 1, headers: {}, body: nil, &block)
 
         when Net::HTTPNotFound
           api_error, api_message = parse_api_error(response)
@@ -139,6 +148,7 @@ module Factorix
       private def build_request(method, uri, headers:, body:)
         request = case method
                   when :get then Net::HTTP::Get.new(uri)
+                  when :head then Net::HTTP::Head.new(uri)
                   when :post then Net::HTTP::Post.new(uri)
                   when :put then Net::HTTP::Put.new(uri)
                   when :delete then Net::HTTP::Delete.new(uri)

data/lib/factorix/http/response.rb

@@ -8,13 +8,16 @@ module Factorix
       attr_reader :body
       attr_reader :headers
       attr_reader :raw_response
+      attr_reader :uri
 
       # @param net_http_response [Net::HTTPResponse] Raw Net::HTTP response
-      def initialize(net_http_response)
+      # @param uri [URI, nil] Final URI after following redirects
+      def initialize(net_http_response, uri: nil)
         @code = Integer(net_http_response.code, 10)
         @body = net_http_response.body
         @headers = net_http_response.to_hash
         @raw_response = net_http_response
+        @uri = uri
       end
 
       # Check if response is successful (2xx)

data/lib/factorix/http/retry_decorator.rb

@@ -54,6 +54,17 @@ module Factorix
           client.post(uri, body:, headers:, content_type:)
         end
       end
+
+      # Execute a HEAD request with retry
+      #
+      # @param uri [URI::HTTPS] target URI
+      # @param headers [Hash<String, String>] request headers
+      # @return [Response] response object
+      def head(uri, headers: {})
+        retry_strategy.with_retry do
+          client.head(uri, headers:)
+        end
+      end
     end
   end
 end

data/lib/factorix/save_file.rb

@@ -49,7 +49,7 @@ module Factorix
           parse_startup_settings(deserializer)
         end
 
-        SaveFile.new(version: @version, mods: @mods, startup_settings: @startup_settings)
+        SaveFile[version: @version, mods: @mods, startup_settings: @startup_settings]
       end
 
       private def open_level_file
@@ -143,7 +143,7 @@ module Factorix
           _crc = deserializer.read_u32
 
           # All MODs in save file are enabled
-          @mods[name] = MODState.new(enabled: true, version:)
+          @mods[name] = MODState[enabled: true, version:]
         end
       end
 

data/lib/factorix/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Factorix
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
   public_constant :VERSION
 end

data/lib/factorix.rb

@@ -129,6 +129,7 @@ module Factorix
     "installed_mod" => "InstalledMOD",
     "mac_os" => "MacOS",
     "mod" => "MOD",
+    "game_download_api" => "GameDownloadAPI",
     "mod_download_api" => "MODDownloadAPI",
     "mod_info" => "MODInfo",
     "mod_management_api" => "MODManagementAPI",

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: factorix
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - OZAWA Sakuro
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-24 00:00:00.000000000 Z
+date: 2026-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -226,6 +226,7 @@ files:
 - lib/factorix.rb
 - lib/factorix/api.rb
 - lib/factorix/api/category.rb
+- lib/factorix/api/game_download_api.rb
 - lib/factorix/api/image.rb
 - lib/factorix/api/license.rb
 - lib/factorix/api/mod_download_api.rb
@@ -248,6 +249,7 @@ files:
 - lib/factorix/cli/commands/command_wrapper.rb
 - lib/factorix/cli/commands/completion.rb
 - lib/factorix/cli/commands/confirmable.rb
+- lib/factorix/cli/commands/download.rb
 - lib/factorix/cli/commands/download_support.rb
 - lib/factorix/cli/commands/launch.rb
 - lib/factorix/cli/commands/man.rb