factorix 0.5.0

data/doc/factorix.1

@@ -0,0 +1,377 @@
+.\" Generated by Claude Code
+.TH FACTORIX 1 "November 2025" "Factorix 0.1.0" "User Commands"
+.SH NAME
+factorix \- Factorio MOD manager CLI tool
+.SH SYNOPSIS
+.B factorix
+.RI [ command ]
+.RI [ subcommand ]
+.RI [ options ]
+.RI [ arguments ]
+.SH DESCRIPTION
+.B factorix
+is a command-line tool for managing Factorio MODs. It provides functionality
+for discovering, installing, updating, and managing MODs from the Factorio
+MOD Portal, as well as managing MOD settings and game launch.
+.SH GLOBAL OPTIONS
+The following options are available for all commands:
+.TP
+.BR \-c ", " \-\-config\-path =\fIVALUE\fR
+Path to configuration file.
+.TP
+.BR \-\-log\-level =\fIVALUE\fR
+Set log level: debug, info, warn, error, fatal.
+.TP
+.BR \-q ", " \-\-quiet
+Suppress non-essential output.
+.TP
+.BR \-h ", " \-\-help
+Print help information.
+.SH COMMANDS
+.SS factorix version
+Display Factorix version.
+.SS factorix man
+Display this manual page using the system's man command.
+.SS factorix path
+Display Factorio and Factorix paths.
+.TP
+.B \-\-json
+Output in JSON format.
+.SS factorix launch
+Launch Factorio game.
+.TP
+.BR \-w ", " \-\-wait
+Wait for the game to finish.
+.PP
+Arguments after
+.B \-\-
+are passed directly to Factorio.
+.SS factorix completion [SHELL]
+Generate shell completion script. Output should be evaluated to enable completion.
+.TP
+.B SHELL
+Shell type: zsh, bash, fish. If omitted, detects from SHELL environment variable.
+.PP
+.RS
+eval "$(factorix completion)"        # auto-detect
+.br
+eval "$(factorix completion zsh)"    # zsh
+.br
+eval "$(factorix completion bash)"   # bash
+.br
+factorix completion fish | source    # fish
+.RE
+.SS factorix cache stat
+Display cache statistics.
+.TP
+.B \-\-json
+Output in JSON format.
+.SS factorix cache evict [CACHES]
+Evict cache entries. CACHES can be: download, api, info_json.
+.TP
+.B \-\-all
+Remove all entries.
+.TP
+.B \-\-expired
+Remove expired entries only.
+.TP
+.BR \-\-older\-than =\fIAGE\fR
+Remove entries older than AGE (e.g., 30s, 5m, 2h, 7d).
+.SH MOD COMMANDS
+.SS factorix mod list
+List installed MOD(s).
+.TP
+.B \-\-enabled
+Show only enabled MOD(s).
+.TP
+.B \-\-disabled
+Show only disabled MOD(s).
+.TP
+.B \-\-errors
+Show only MOD(s) with dependency errors.
+.TP
+.B \-\-outdated
+Show only MOD(s) with available updates.
+.TP
+.B \-\-json
+Output in JSON format.
+.SS factorix mod search [MOD_NAMES]
+Search MOD(s) on Factorio MOD Portal.
+.TP
+.BR \-\-[no\-]hide\-deprecated
+Hide deprecated MOD(s) (default: true).
+.TP
+.BR \-\-page =\fIVALUE\fR
+Page number (default: 1).
+.TP
+.BR \-\-page\-size =\fIVALUE\fR
+Results per page (max 500, default: 25).
+.TP
+.BR \-\-sort =\fIVALUE\fR
+Sort field: name, created_at, updated_at.
+.TP
+.BR \-\-sort\-order =\fIVALUE\fR
+Sort order: asc, desc.
+.TP
+.BR \-\-version =\fIVALUE\fR
+Filter by Factorio version.
+.TP
+.B \-\-json
+Output in JSON format.
+.SS factorix mod show MOD_NAME
+Show MOD details from Factorio MOD Portal.
+.PP
+Displays title, summary, version, author, category, license, Factorio version,
+downloads count, links (portal, source, homepage), dependencies, and
+incompatibilities. Shows installation status if the MOD is locally installed.
+.SS factorix mod install MOD_SPECS
+Install MOD(s) from Factorio MOD Portal. Downloads to MOD directory and enables.
+.PP
+MOD_SPECS format: name, name@version, or name@latest.
+.TP
+.BR \-y ", " \-\-yes
+Skip confirmation prompts.
+.TP
+.BR \-j ", " \-\-jobs =\fIVALUE\fR
+Number of parallel downloads (default: 4).
+.SS factorix mod uninstall [MOD_SPECS]
+Uninstall MOD(s) from MOD directory.
+.TP
+.BR \-y ", " \-\-yes
+Skip confirmation prompts.
+.TP
+.B \-\-all
+Uninstall all MOD(s).
+.SS factorix mod update [MOD_NAMES]
+Update MOD(s) to their latest versions. Updates all if no names specified.
+.TP
+.BR \-y ", " \-\-yes
+Skip confirmation prompts.
+.TP
+.BR \-j ", " \-\-jobs =\fIVALUE\fR
+Number of parallel downloads (default: 4).
+.SS factorix mod download MOD_SPECS
+Download MOD files from Factorio MOD Portal without installing.
+.TP
+.BR \-d ", " \-\-directory =\fIVALUE\fR
+Download directory (default: current directory).
+.TP
+.BR \-j ", " \-\-jobs =\fIVALUE\fR
+Number of parallel downloads (default: 4).
+.TP
+.BR \-r ", " \-\-recursive
+Include required dependencies recursively.
+.SS factorix mod enable MOD_NAMES
+Enable MOD(s) in mod-list.json. Recursively enables dependencies.
+.TP
+.BR \-y ", " \-\-yes
+Skip confirmation prompts.
+.SS factorix mod disable [MOD_NAMES]
+Disable MOD(s) in mod-list.json. Recursively disables dependent MOD(s).
+.TP
+.BR \-y ", " \-\-yes
+Skip confirmation prompts.
+.TP
+.B \-\-all
+Disable all MOD(s) except base.
+.SS factorix mod check
+Validate MOD dependencies. Reports missing, disabled, or incompatible dependencies.
+.SS factorix mod sync SAVE_FILE
+Sync MOD states and startup settings from a save file.
+.TP
+.BR \-y ", " \-\-yes
+Skip confirmation prompts.
+.TP
+.BR \-j ", " \-\-jobs =\fIVALUE\fR
+Number of parallel downloads (default: 4).
+.SH MOD PORTAL COMMANDS
+These commands interact with the Factorio MOD Portal and require authentication.
+.SS factorix mod upload FILE
+Upload MOD to Factorio MOD Portal. Handles both new MODs and updates.
+.TP
+.BR \-\-description =\fIVALUE\fR
+Markdown description.
+.TP
+.BR \-\-category =\fIVALUE\fR
+MOD category.
+.TP
+.BR \-\-license =\fIVALUE\fR
+License identifier.
+.TP
+.BR \-\-source\-url =\fIVALUE\fR
+Repository URL.
+.SS factorix mod edit MOD_NAME
+Edit MOD metadata on Factorio MOD Portal.
+.TP
+.BR \-\-title =\fIVALUE\fR
+MOD title.
+.TP
+.BR \-\-summary =\fIVALUE\fR
+Brief description.
+.TP
+.BR \-\-description =\fIVALUE\fR
+Markdown description.
+.TP
+.BR \-\-category =\fIVALUE\fR
+MOD category.
+.TP
+.BR \-\-tags =\fIVALUE1,VALUE2,..\fR
+Array of tags.
+.TP
+.BR \-\-license =\fIVALUE\fR
+License identifier.
+.TP
+.BR \-\-homepage =\fIVALUE\fR
+Homepage URL.
+.TP
+.BR \-\-source\-url =\fIVALUE\fR
+Repository URL.
+.TP
+.BR \-\-faq =\fIVALUE\fR
+FAQ text.
+.TP
+.BR \-\-[no\-]deprecated
+Deprecation flag.
+.SS factorix mod image list MOD_NAME
+List images for a MOD.
+.TP
+.B \-\-json
+Output in JSON format.
+.SS factorix mod image add MOD_NAME IMAGE_FILE
+Add an image to a MOD.
+.SS factorix mod image edit MOD_NAME IMAGE_IDS
+Edit MOD's image list. Reorder or remove images by specifying IDs in desired order.
+.SH SETTINGS COMMANDS
+.SS factorix mod settings dump [SETTINGS_FILE]
+Dump MOD settings to JSON format.
+.TP
+.BR \-o ", " \-\-output =\fIVALUE\fR
+Output file path (default: stdout).
+.SS factorix mod settings restore [SETTINGS_FILE]
+Restore MOD settings from JSON format.
+.TP
+.BR \-i ", " \-\-input =\fIVALUE\fR
+Input file path (default: stdin).
+.TP
+.BR \-\-backup\-extension =\fIVALUE\fR
+Backup file extension (default: .bak).
+.SH AUTHENTICATION
+.SS Service Credentials (for MOD downloads)
+Service credentials (username and token) are read from player-data.json
+in the Factorio user data directory. These are automatically saved when
+you log in to Factorio.
+.PP
+Alternatively, you can set environment variables:
+.TP
+.B FACTORIO_USERNAME
+Factorio service username.
+.TP
+.B FACTORIO_TOKEN
+Factorio service token.
+.SS API Key (for MOD Portal management)
+API key is required for upload, edit, and image operations.
+Set the following environment variable:
+.TP
+.B FACTORIO_API_KEY
+API key obtained from Factorio MOD Portal.
+.SH ENVIRONMENT
+.TP
+.B FACTORIX_CONFIG
+Path to configuration file. Overrides the default location.
+.SH FILES
+The paths below are XDG Base Directory defaults for Linux/WSL.
+On macOS and Windows, these locations differ according to platform conventions.
+Use
+.B factorix path
+to see actual paths for your system.
+.TP
+.I ~/.config/factorix/config.rb
+User configuration file (Ruby DSL).
+.TP
+.I ~/.cache/factorix/
+Cache directory for API responses and downloads.
+.TP
+.I ~/.local/state/factorix/
+Log files.
+.SH EXAMPLES
+Enable shell completion for bash or zsh:
+.PP
+.RS
+eval "$(factorix completion)"
+.RE
+.PP
+Enable shell completion for fish:
+.PP
+.RS
+factorix completion fish | source
+.RE
+.PP
+List all installed MODs:
+.PP
+.RS
+factorix mod list
+.RE
+.PP
+Search for MODs on the portal:
+.PP
+.RS
+factorix mod search logistic
+.RE
+.PP
+Install a MOD with dependencies:
+.PP
+.RS
+factorix mod install some-mod
+.RE
+.PP
+Install a specific version:
+.PP
+.RS
+factorix mod install some-mod@1.2.0
+.RE
+.PP
+Update all installed MODs:
+.PP
+.RS
+factorix mod update
+.RE
+.PP
+Sync MODs from a save file:
+.PP
+.RS
+factorix mod sync ~/factorio/saves/my-save.zip
+.RE
+.PP
+Launch Factorio with custom arguments:
+.PP
+.RS
+factorix launch -- --benchmark save.zip
+.RE
+.PP
+Export MOD settings:
+.PP
+.RS
+factorix mod settings dump -o settings.json
+.RE
+.SH EXIT STATUS
+.TP
+.B 0
+Success.
+.TP
+.B 1
+Expected error (e.g., MOD not found, validation failure).
+.TP
+.B 2
+Unexpected error (e.g., network failure, internal error).
+.SH SEE ALSO
+.UR https://github.com/sakuro/factorix
+Factorix on GitHub
+.UE
+.PP
+.UR https://wiki.factorio.com/Mod_portal_API
+Factorio MOD Portal API
+.UE
+.SH AUTHOR
+OZAWA Sakuro
+.SH COPYRIGHT
+MIT License

data/exe/factorix

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/factorix"
+require "dry/cli"
+require "zip"
+
+# Suppress warnings about invalid dates in ZIP files
+Zip.warn_invalid_date = false
+
+begin
+  Dry::CLI.new(Factorix::CLI).call
+  exit 0
+rescue Factorix::Error
+  # Expected errors are already logged and displayed by CommandWrapper
+  exit 1
+rescue
+  # Unexpected errors are already logged and displayed by CommandWrapper
+  exit 2
+end

data/lib/factorix/api/category.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Factorix
+  module API
+    Category = Data.define(:value, :name, :description)
+
+    # Category object from MOD Portal API
+    #
+    # Represents a MOD category with value, name, and description.
+    # Uses flyweight pattern - same category value returns same instance.
+    #
+    # @see https://wiki.factorio.com/Mod_details_API#Category
+    class Category
+      # @!attribute [r] value
+      #   @return [String] category value (e.g., "content", "utilities", "" for no category)
+      # @!attribute [r] name
+      #   @return [String] human-readable category name (e.g., "Content", "Utilities")
+      # @!attribute [r] description
+      #   @return [String] category description
+
+      # Predefined category instances
+      NO_CATEGORY = new(value: "", name: "No category", description: "Unassigned category")
+      private_constant :NO_CATEGORY
+      CONTENT = new(value: "content", name: "Content", description: "Mods introducing new content into the game")
+      private_constant :CONTENT
+      OVERHAUL = new(value: "overhaul", name: "Overhaul", description: "Large total conversion mods")
+      private_constant :OVERHAUL
+      TWEAKS = new(value: "tweaks", name: "Tweaks", description: "Small changes concerning balance, gameplay, or graphics")
+      private_constant :TWEAKS
+      UTILITIES = new(value: "utilities", name: "Utilities", description: "Providing the player with new tools or adjusting the game interface")
+      private_constant :UTILITIES
+      SCENARIOS = new(value: "scenarios", name: "Scenarios", description: "Scenarios, maps, and puzzles")
+      private_constant :SCENARIOS
+      MOD_PACKS = new(value: "mod-packs", name: "Mod packs", description: "Collections of mods with tweaks to make them work together")
+      private_constant :MOD_PACKS
+      LOCALIZATIONS = new(value: "localizations", name: "Localizations", description: "Translations for other mods")
+      private_constant :LOCALIZATIONS
+      INTERNAL = new(value: "internal", name: "Internal", description: "Lua libraries for use by other mods")
+      private_constant :INTERNAL
+
+      # Lookup table for flyweight pattern
+      CATEGORIES = {
+        "" => NO_CATEGORY,
+        "no-category" => NO_CATEGORY,
+        "content" => CONTENT,
+        "overhaul" => OVERHAUL,
+        "tweaks" => TWEAKS,
+        "utilities" => UTILITIES,
+        "scenarios" => SCENARIOS,
+        "mod-packs" => MOD_PACKS,
+        "localizations" => LOCALIZATIONS,
+        "internal" => INTERNAL
+      }.freeze
+      private_constant :CATEGORIES
+
+      # Get Category instance for the given value
+      #
+      # Returns predefined instance for known categories (flyweight pattern).
+      # Raises an error for unknown category values.
+      #
+      # @param value [String] category value
+      # @return [Category] Category instance
+      # @raise [KeyError] if category value is unknown
+      def self.for(value) = CATEGORIES.fetch(value.to_s)
+
+      private_class_method :new, :[]
+    end
+  end
+end

data/lib/factorix/api/image.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Factorix
+  module API
+    Image = Data.define(:id, :thumbnail, :url)
+
+    # Image object from MOD Portal API
+    #
+    # Represents a MOD screenshot or image
+    #
+    # @see https://wiki.factorio.com/Mod_portal_API
+    class Image
+      # @!attribute [r] id
+      #   @return [String] image ID
+      # @!attribute [r] thumbnail
+      #   @return [URI::HTTPS] thumbnail URL
+      # @!attribute [r] url
+      #   @return [URI::HTTPS] full-size image URL
+
+      # Create Image from API response hash
+      #
+      # @param id [String] image ID
+      # @param thumbnail [String] thumbnail URL
+      # @param url [String] full-size image URL
+      # @return [Image] new Image instance
+      def initialize(id:, thumbnail:, url:)
+        thumbnail = URI(thumbnail)
+        url = URI(url)
+        super
+      end
+    end
+  end
+end

data/lib/factorix/api/license.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Factorix
+  module API
+    License = Data.define(:id, :name, :title, :description, :url)
+
+    # License object from MOD Portal API
+    #
+    # Represents a MOD license information.
+    # Also provides valid license identifiers for edit_details API.
+    #
+    # @see https://wiki.factorio.com/Mod_portal_API
+    # @see https://wiki.factorio.com/Mod_details_API
+    class License
+      # @!attribute [r] id
+      #   @return [String] license ID
+      # @!attribute [r] name
+      #   @return [String] license name
+      # @!attribute [r] title
+      #   @return [String] license title
+      # @!attribute [r] description
+      #   @return [String] license description (long text)
+      # @!attribute [r] url
+      #   @return [URI::HTTPS] license URL
+
+      # Valid license identifiers for edit_details API
+      # Custom licenses (custom_$ID) are not included
+      IDENTIFIERS = {
+        "default_mit" => "MIT",
+        "default_gnugplv3" => "GNU GPLv3",
+        "default_gnulgplv3" => "GNU LGPLv3",
+        "default_mozilla2" => "Mozilla Public License 2.0",
+        "default_apache2" => "Apache License 2.0",
+        "default_unlicense" => "The Unlicense"
+      }.freeze
+      private_constant :IDENTIFIERS
+
+      # Pattern for custom license identifiers (custom_ + 24 lowercase hex chars)
+      CUSTOM_LICENSE_PATTERN = /\Acustom_[0-9a-f]{24}\z/
+      private_constant :CUSTOM_LICENSE_PATTERN
+
+      # Check if the given value is a valid license identifier
+      #
+      # @param value [String] license identifier
+      # @return [Boolean] true if valid (standard or custom license)
+      def self.valid_identifier?(value)
+        IDENTIFIERS.key?(value) || CUSTOM_LICENSE_PATTERN.match?(value)
+      end
+
+      # List all valid license identifier values
+      #
+      # @return [Array<String>] array of license identifiers
+      def self.identifier_values = IDENTIFIERS.keys
+
+      # Create License from API response hash
+      #
+      # @param id [String] license ID
+      # @param name [String] license name
+      # @param title [String] license title
+      # @param description [String] license description
+      # @param url [String] license URL
+      # @return [License] new License instance
+      def initialize(id:, name:, title:, description:, url:)
+        url = URI(url)
+        super
+      end
+    end
+  end
+end

data/lib/factorix/api/mod_download_api.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Factorix
+  module API
+    # API client for downloading MOD files with service authentication
+    #
+    # Requires username and token authentication via ServiceCredential.
+    class MODDownloadAPI
+      # NOTE: service_credential is NOT imported to avoid early evaluation errors
+      # when FACTORIO_USERNAME/FACTORIO_TOKEN environment variables are not set.
+      # It's resolved lazily via reader method instead.
+      # @!parse
+      #   # @return [Transfer::Downloader]
+      #   attr_reader :downloader
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      include Import[:downloader, :logger]
+
+      BASE_URL = "https://mods.factorio.com"
+      private_constant :BASE_URL
+
+      # Initialize with thread-safe credential loading
+      #
+      # @param args [Hash] dependency injection arguments
+      def initialize(...)
+        super
+        @service_credential_mutex = Mutex.new
+      end
+
+      # Download a MOD file to the specified output path
+      #
+      # @param download_url [String] relative download URL from API response (e.g., "/download/mod-name/...")
+      # @param output [Pathname] output file path
+      # @param expected_sha1 [String, nil] expected SHA1 digest for verification (optional)
+      # @return [void]
+      # @raise [ArgumentError] if download_url is not a relative path starting with "/"
+      # @raise [DigestMismatchError] if SHA1 verification fails
+      def download(download_url, output, expected_sha1: nil)
+        unless download_url.start_with?("/")
+          logger.error("Invalid download_url", url: download_url)
+          raise ArgumentError, "download_url must be a relative path starting with '/'"
+        end
+
+        uri = build_download_uri(download_url)
+        downloader.download(uri, output, expected_sha1:)
+      end
+
+      private def service_credential
+        return @service_credential if defined?(@service_credential)
+
+        @service_credential_mutex.synchronize do
+          @service_credential ||= Application[:service_credential]
+        end
+      end
+
+      private def build_download_uri(download_url)
+        uri = URI.join(BASE_URL, download_url)
+        params = {username: service_credential.username, token: service_credential.token}
+        uri.query = URI.encode_www_form(params)
+        uri
+      end
+    end
+  end
+end