factorix 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f669f6ec36e75ef8f9720e7e09337627d56bc84453233484157643f22a55aa9
-  data.tar.gz: 2029ef6d075978429ddd533c7ba5aa68eb0c16bf77e9c1802bcbfd159844f767
+  metadata.gz: f93238fc1b419e6adf7ec45ac04331f84aba675b94cf4d4e57fd7c8555687678
+  data.tar.gz: 2e7d4ed3b5c0b4be85fd5f1012eb4a73b84b160d5f31c1ed326a5830cba41c42
 SHA512:
-  metadata.gz: f9a17f3a9a83fdf498555deac57a3d9d99b0b33d77a36c8242e5d78e8e85923ed535f4457bf5976e2e3f1b7209214c84e4eda1f9bf00425657b1c8eb471f34de
-  data.tar.gz: 0e6c5bfc9e7a09d4ff3529e976b0f7f90cba03d49d2e98ef70ae9eae07031e1c2de90e7f4235dbeb8d68b32d852afa5a674ecc76bcfb048684f9e229454c9c83
+  metadata.gz: 254733ebd3ad1b896a84c341d35a49a2d8943114d4fe0f90d0b83efae5399d9f862aedaeb0f7a68d42cdfedad9ab0dae9a4d77625646540de111e77567b74ab6
+  data.tar.gz: 733b7da2d624bbf225e9bcbd586a0aa394c593d79743456c2a9b1a8ef06daf05603f1f4091da657038f7bacfdb766061a48026084a1d72290cc3350df2e8e694

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.11.0] - 2026-03-03
+
+### Added
+
+- Add `blueprint decode` command to decode Factorio blueprint strings to JSON (#76)
+- Add `blueprint encode` command to encode JSON to Factorio blueprint strings (#76)
+
+### Changed
+
+- `mod sync` now disables enabled MODs (including expansion MODs) not listed in the save file by default (#70)
+- Add `--keep-unlisted` option to `mod sync` to preserve MODs not listed in the save file (#70)
+
 ## [0.10.0] - 2026-02-21
 
 ### Changed

data/README.md

@@ -18,6 +18,7 @@ Factorix simplifies Factorio MOD management by providing:
 - **Installation & Uninstallation**: Install MODs directly from the portal or uninstall existing MODs
 - **Save File Sync**: Synchronize MOD states and startup settings from Factorio save files
 - **Settings Management**: Export/import MOD settings in JSON format
+- **Blueprint Conversion**: Decode/encode Factorio blueprint strings to/from JSON
 - **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)

data/completion/_factorix.bash

@@ -17,7 +17,10 @@ _factorix() {
   local confirmable_opts="-y --yes"
 
   # Top-level commands
-  local commands="version man launch path download mod cache completion"
+  local commands="version man launch path download blueprint mod cache completion"
+
+  # blueprint subcommands
+  local blueprint_commands="decode encode"
 
   # mod subcommands
   local mod_commands="changelog check list show enable disable install uninstall update download upload edit search sync image settings"
@@ -66,6 +69,25 @@ _factorix() {
       fi
       return
       ;;
+    blueprint)
+      if [[ $cword -eq 2 ]]; then
+        COMPREPLY=($(compgen -W "$blueprint_commands" -- "$cur"))
+      else
+        case "${words[2]}" in
+          decode|encode)
+            if [[ "$cur" == -* ]]; then
+              COMPREPLY=($(compgen -W "$global_opts -o --output" -- "$cur"))
+            else
+              COMPREPLY=($(compgen -f -- "$cur"))
+            fi
+            ;;
+          *)
+            COMPREPLY=($(compgen -W "$global_opts" -- "$cur"))
+            ;;
+        esac
+      fi
+      return
+      ;;
     cache)
       if [[ $cword -eq 2 ]]; then
         COMPREPLY=($(compgen -W "$cache_commands" -- "$cur"))
@@ -165,7 +187,7 @@ _factorix() {
             ;;
           sync)
             if [[ "$cur" == -* ]]; then
-              COMPREPLY=($(compgen -W "$global_opts $confirmable_opts -j --jobs" -- "$cur"))
+              COMPREPLY=($(compgen -W "$global_opts $confirmable_opts -j --jobs --keep-unlisted" -- "$cur"))
             else
               COMPREPLY=($(compgen -f -X '!*.zip' -- "$cur"))
             fi

data/completion/_factorix.fish

@@ -107,14 +107,25 @@ 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 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'
+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 blueprint; 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 blueprint; 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 blueprint; 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 blueprint; 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 blueprint; 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 blueprint; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a blueprint -d 'Blueprint decode/encode 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 blueprint; 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 blueprint; 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 blueprint; 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'
+
+# blueprint subcommands
+complete -c factorix -n "__factorix_using_command blueprint" -a decode -d 'Decode a Factorio blueprint string to JSON'
+complete -c factorix -n "__factorix_using_command blueprint" -a encode -d 'Encode JSON to a Factorio blueprint string'
+
+# blueprint decode/encode options
+complete -c factorix -n "__factorix_using_subcommand blueprint decode" -s o -l output -d 'Output file path' -rF
+complete -c factorix -n "__factorix_using_subcommand blueprint decode" -rF
+complete -c factorix -n "__factorix_using_subcommand blueprint encode" -s o -l output -d 'Output file path' -rF
+complete -c factorix -n "__factorix_using_subcommand blueprint encode" -rF
 
 # launch options
 complete -c factorix -n "__factorix_using_command launch" -s w -l wait -d 'Wait for the game to finish'
@@ -228,6 +239,7 @@ complete -c factorix -n "__factorix_using_subcommand mod search" -l json -d 'Out
 # mod sync options
 complete -c factorix -n "__factorix_using_subcommand mod sync" -s y -l yes -d 'Skip confirmation prompts'
 complete -c factorix -n "__factorix_using_subcommand mod sync" -s j -l jobs -d 'Number of parallel downloads' -r
+complete -c factorix -n "__factorix_using_subcommand mod sync" -l keep-unlisted -d 'Keep MODs not listed in save file enabled'
 complete -c factorix -n "__factorix_using_subcommand mod sync" -ra '(__fish_complete_suffix .zip)'
 
 # mod changelog subcommands

data/completion/_factorix.zsh

@@ -40,6 +40,7 @@ _factorix() {
         'launch:Launch Factorio game'
         'path:Display Factorio and Factorix paths'
         'download:Download Factorio game files'
+        'blueprint:Blueprint decode/encode commands'
         'mod:MOD management commands'
         'cache:Cache management commands'
         'completion:Generate shell completion script'
@@ -62,6 +63,9 @@ _factorix() {
             $global_opts \
             '--json[Output in JSON format]'
           ;;
+        blueprint)
+          _factorix_blueprint
+          ;;
         download)
           _factorix_download
           ;;
@@ -79,6 +83,43 @@ _factorix() {
   esac
 }
 
+_factorix_blueprint() {
+  local context state state_descr line
+  typeset -A opt_args
+
+  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 -C \
+    '1:subcommand:->subcommand' \
+    '*::arg:->args'
+
+  case $state in
+    subcommand)
+      local -a subcommands
+      subcommands=(
+        'decode:Decode a Factorio blueprint string to JSON'
+        'encode:Encode JSON to a Factorio blueprint string'
+      )
+      _describe -t subcommands 'blueprint subcommand' subcommands
+      ;;
+    args)
+      case $line[1] in
+        decode|encode)
+          _arguments \
+            $global_opts \
+            '(-o --output)'{-o,--output}'[Output file path]:output file:_files' \
+            '1:input file:_files'
+          ;;
+      esac
+      ;;
+  esac
+}
+
 _factorix_completion() {
   local -a global_opts
   global_opts=(
@@ -256,6 +297,7 @@ _factorix_mod() {
             $global_opts \
             $confirmable_opts \
             '(-j --jobs)'{-j,--jobs}'[Number of parallel downloads]:jobs:' \
+            '--keep-unlisted[Keep MODs not listed in save file enabled]' \
             '1:save file:_files -g "*.zip"'
           ;;
         changelog)

data/doc/factorix.1

@@ -178,12 +178,16 @@ Disable all MOD(s) except base.
 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.
+Enabled MODs not listed in the save file are disabled by default.
 .TP
 .BR \-y ", " \-\-yes
 Skip confirmation prompts.
 .TP
 .BR \-j ", " \-\-jobs =\fIVALUE\fR
 Number of parallel downloads (default: 4).
+.TP
+.B \-\-keep\-unlisted
+Keep MODs not listed in the save file enabled.
 .SS factorix mod changelog add ENTRY
 Add an entry to MOD changelog.
 .TP

data/lib/factorix/blueprint.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "zlib"
+
+module Factorix
+  # Represents a Factorio blueprint
+  #
+  # A blueprint string has the format: version_byte + Base64(zlib(JSON))
+  # Only version byte '0' is supported.
+  class Blueprint
+    # The only supported version byte
+    SUPPORTED_VERSION = "0"
+    private_constant :SUPPORTED_VERSION
+
+    # @return [Hash] The blueprint data
+    attr_reader :data
+
+    # Decode a blueprint string into a Blueprint
+    #
+    # @param string [String] The blueprint string
+    # @return [Blueprint]
+    # @raise [UnsupportedBlueprintVersionError] if the version byte is not '0'
+    # @raise [BlueprintFormatError] if the string is not a valid blueprint
+    def self.decode(string)
+      version = string[0]
+      raise UnsupportedBlueprintVersionError, "Unsupported blueprint version: #{version.inspect}" unless version == SUPPORTED_VERSION
+
+      compressed = Base64.strict_decode64(string[1..])
+      json_string = Zlib::Inflate.inflate(compressed)
+      new(JSON.parse(json_string))
+    rescue ArgumentError => e
+      raise BlueprintFormatError, "Invalid Base64 encoding: #{e.message}"
+    rescue Zlib::Error => e
+      raise BlueprintFormatError, "Invalid zlib data: #{e.message}"
+    rescue JSON::ParserError => e
+      raise BlueprintFormatError, "Invalid JSON: #{e.message}"
+    end
+
+    # @param data [Hash] The blueprint data
+    def initialize(data)
+      @data = data
+    end
+
+    # Encode this blueprint to a blueprint string
+    #
+    # @return [String]
+    def encode
+      json_string = JSON.generate(@data)
+      compressed = Zlib::Deflate.deflate(json_string, Zlib::BEST_COMPRESSION)
+      SUPPORTED_VERSION + Base64.strict_encode64(compressed)
+    end
+
+    # Serialize this blueprint to pretty-printed JSON
+    #
+    # @return [String]
+    def to_json(*)
+      JSON.pretty_generate(@data)
+    end
+  end
+end

data/lib/factorix/cli/commands/blueprint/decode.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Factorix
+  class CLI
+    module Commands
+      module Blueprint
+        # Decode a Factorio blueprint string to JSON
+        class Decode < Base
+          desc "Decode a Factorio blueprint string to JSON"
+
+          example [
+            "                              # Decode from stdin",
+            "blueprint.txt                 # Decode from file",
+            "blueprint.txt -o decoded.json # Decode to file"
+          ]
+
+          argument :file, required: false, desc: "Path to file containing blueprint string (default: stdin)"
+          option :output, aliases: ["-o"], desc: "Output file path (default: stdout)"
+
+          # Execute the decode command
+          #
+          # @param file [String, nil] Path to file containing blueprint string
+          # @param output [String, nil] Output file path
+          # @return [void]
+          def call(file: nil, output: nil, **)
+            blueprint_string = file ? Pathname(file).read.strip : $stdin.read.strip
+            blueprint = Factorix::Blueprint.decode(blueprint_string)
+            json_string = blueprint.to_json
+
+            if output
+              Pathname(output).write(json_string)
+            else
+              out.puts json_string
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/factorix/cli/commands/blueprint/encode.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Factorix
+  class CLI
+    module Commands
+      module Blueprint
+        # Encode JSON to a Factorio blueprint string
+        class Encode < Base
+          desc "Encode JSON to a Factorio blueprint string"
+
+          example [
+            "                              # Encode from stdin",
+            "decoded.json                  # Encode from file",
+            "decoded.json -o blueprint.txt # Encode to file"
+          ]
+
+          argument :file, required: false, desc: "Path to JSON file (default: stdin)"
+          option :output, aliases: ["-o"], desc: "Output file path (default: stdout)"
+
+          # Execute the encode command
+          #
+          # @param file [String, nil] Path to JSON file
+          # @param output [String, nil] Output file path
+          # @return [void]
+          def call(file: nil, output: nil, **)
+            json_string = file ? Pathname(file).read : $stdin.read
+            blueprint = Factorix::Blueprint.new(JSON.parse(json_string))
+            blueprint_string = blueprint.encode
+
+            if output
+              Pathname(output).write(blueprint_string)
+            else
+              out.print blueprint_string
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -26,26 +26,27 @@ module Factorix
           desc "Sync MOD states and startup settings from a save file"
 
           example [
-            "save.zip           # Sync MOD(s) from save file",
-            "-j 8 save.zip      # Use 8 parallel downloads"
+            "save.zip                 # Sync MOD(s) from save file",
+            "-j 8 save.zip            # Use 8 parallel downloads",
+            "--keep-unlisted save.zip # Keep MOD(s) not in save file enabled"
           ]
 
           argument :save_file, required: true, desc: "Path to Factorio save file (.zip)"
           option :jobs, aliases: ["-j"], default: "4", desc: "Number of parallel downloads"
+          option :keep_unlisted, type: :flag, default: false, desc: "Keep MOD(s) not listed in save file enabled"
 
           # Execute the sync command
           #
           # @param save_file [String] Path to save file
           # @param jobs [Integer] Number of parallel downloads
+          # @param keep_unlisted [Boolean] Whether to keep unlisted MODs enabled
           # @return [void]
-          def call(save_file:, jobs: "4", **)
+          def call(save_file:, jobs: "4", keep_unlisted: false, **)
             jobs = Integer(jobs)
-            # Load save file
             say "Loading save file: #{save_file}", prefix: :info
             save_data = SaveFile.load(Pathname(save_file))
             say "Loaded save file (version: #{save_data.version}, MOD(s): #{save_data.mods.size})", prefix: :info
 
-            # Load current state
             mod_list = MODList.load
             presenter = Progress::Presenter.new(title: "\u{1F50D}\u{FE0E} Scanning MOD(s)", output: err)
             handler = Progress::ScanHandler.new(presenter)
@@ -54,36 +55,30 @@ module Factorix
 
             raise DirectoryNotFoundError, "MOD directory does not exist: #{runtime.mod_dir}" unless runtime.mod_dir.exist?
 
-            # Find MODs that need to be installed
+            # Plan phase (no side effects)
             mods_to_install = find_mods_to_install(save_data.mods, installed_mods)
+            install_targets = mods_to_install.any? ? plan_installation(mods_to_install, graph, jobs) : []
+            conflict_mods = find_conflict_mods(mod_list, save_data.mods, graph)
+            changes = plan_mod_list_changes(mod_list, save_data.mods)
+            unlisted_mods = keep_unlisted ? [] : find_unlisted_mods(mod_list, save_data.mods, conflict_mods)
 
-            if mods_to_install.any?
-              say "#{mods_to_install.size} MOD(s) need to be installed", prefix: :info
+            # Show combined plan and ask once
+            show_sync_plan(install_targets, conflict_mods, changes, unlisted_mods)
 
-              # Plan installation
-              install_targets = plan_installation(mods_to_install, graph, jobs)
+            return if needs_confirmation?(install_targets, conflict_mods, changes, unlisted_mods) &&
+                      !confirm?("Do you want to apply these changes?")
 
-              # Show plan
-              show_install_plan(install_targets)
-              return unless confirm?("Do you want to install these MOD(s)?")
-
-              # Execute installation
+            # Execute phase
+            if install_targets.any?
               execute_installation(install_targets, jobs)
               say "Installed #{install_targets.size} MOD(s)", prefix: :success
-            else
-              say "All MOD(s) from save file are already installed", prefix: :info
             end
 
-            # Resolve conflicts: disable existing MODs that conflict with new ones
-            resolve_conflicts(mod_list, save_data.mods, graph)
-
-            # Update mod-list.json
-            update_mod_list(mod_list, save_data.mods)
+            apply_mod_list_changes(mod_list, conflict_mods, changes, unlisted_mods)
             backup_if_exists(runtime.mod_list_path)
             mod_list.save
             say "Updated mod-list.json", prefix: :success
 
-            # Update mod-settings.dat
             update_mod_settings(save_data.startup_settings, save_data.version)
             say "Updated mod-settings.dat", prefix: :success
 
@@ -92,10 +87,8 @@ module Factorix
 
           private def find_mods_to_install(save_mods, installed_mods)
             save_mods.reject do |mod_name, _mod_state|
-              # Skip base MOD (always installed)
               next true if mod_name == "base"
 
-              # Check if MOD is installed
               mod = Factorix::MOD[name: mod_name]
               installed_mods.any? {|installed| installed.mod == mod }
             end
@@ -108,18 +101,13 @@ module Factorix
           # @param jobs [Integer] Number of parallel jobs
           # @return [Array<Hash>] Installation targets with MOD info and releases
           private def plan_installation(mods_to_install, graph, jobs)
-            # Create progress presenter for info fetching
             presenter = Progress::Presenter.new(title: "\u{1F50D}\u{FE0E} Fetching MOD info", output: err)
-
-            # Fetch info for MODs to install
             target_infos = fetch_target_mod_info(mods_to_install, jobs, presenter)
 
-            # Add to graph
             target_infos.each do |info|
               graph.add_uninstalled_mod(info[:mod_info], info[:release])
             end
 
-            # Build install targets
             build_install_targets(target_infos, runtime.mod_dir)
           end
 
@@ -155,10 +143,7 @@ module Factorix
           # @param version [MODVersion] Target version
           # @return [Hash] {mod_name:, mod_info:, release:, version:}
           private def fetch_single_mod_info(mod_name, version)
-            # Fetch full MOD info from portal
             mod_info = portal.get_mod_full(mod_name)
-
-            # Find the specific version release
             release = mod_info.releases.find {|r| r.version == version }
 
             unless release
@@ -168,100 +153,240 @@ module Factorix
             {mod_name:, mod_info:, release:, version:}
           end
 
-          # Show the installation plan
-          #
-          # @param targets [Array<Hash>] Installation targets
-          # @return [void]
-          private def show_install_plan(targets)
-            say "Planning to install #{targets.size} MOD(s):", prefix: :info
-            targets.each do |target|
-              say "  - #{target[:mod]}@#{target[:release].version}"
-            end
-          end
-
           # Execute the installation
           #
           # @param targets [Array<Hash>] Installation targets
           # @param jobs [Integer] Number of parallel jobs
           # @return [void]
           private def execute_installation(targets, jobs)
-            # Download all MODs
             download_mods(targets, jobs)
           end
 
-          # Resolve conflicts between save file MODs and existing enabled MODs
+          # Find MODs that conflict with enabled MODs from the save file
           #
           # @param mod_list [MODList] Current MOD list
           # @param save_mods [Hash<String, MODState>] MODs from save file
           # @param graph [Dependency::Graph] Dependency graph
-          # @return [void]
-          private def resolve_conflicts(mod_list, save_mods, graph)
+          # @return [Array<Hash>] Conflict entries: {mod:, conflicts_with:}
+          private def find_conflict_mods(mod_list, save_mods, graph)
+            conflicts = []
+            seen = Set.new
+
             save_mods.each do |mod_name, mod_state|
               next unless mod_state.enabled?
 
-              mod = Factorix::MOD[name: mod_name]
+              save_mod = Factorix::MOD[name: mod_name]
 
-              graph.edges_from(mod).each do |edge|
+              graph.edges_from(save_mod).each do |edge|
                 next unless edge.incompatible?
 
                 conflicting_mod = edge.to_mod
                 next unless mod_list.exist?(conflicting_mod) && mod_list.enabled?(conflicting_mod)
+                next unless seen.add?(conflicting_mod)
 
-                mod_list.disable(conflicting_mod)
-                say "Disabled #{conflicting_mod} (conflicts with #{mod} from save file)", prefix: :warn
-                logger.debug("Disabled conflicting MOD", mod_name: conflicting_mod.name, conflicts_with: mod.name)
+                conflicts << {mod: conflicting_mod, conflicts_with: save_mod}
               end
 
-              graph.edges_to(mod).each do |edge|
+              graph.edges_to(save_mod).each do |edge|
                 next unless edge.incompatible?
 
                 conflicting_mod = edge.from_mod
                 next unless mod_list.exist?(conflicting_mod) && mod_list.enabled?(conflicting_mod)
+                next unless seen.add?(conflicting_mod)
 
-                mod_list.disable(conflicting_mod)
-                say "Disabled #{conflicting_mod} (conflicts with #{mod} from save file)", prefix: :warn
-                logger.debug("Disabled conflicting MOD", mod_name: conflicting_mod.name, conflicts_with: mod.name)
+                conflicts << {mod: conflicting_mod, conflicts_with: save_mod}
               end
             end
+
+            conflicts
           end
 
-          # Update mod-list.json with MODs from save file
+          # Compute changes needed to bring mod-list.json in sync with save file
           #
           # @param mod_list [MODList] Current MOD list
           # @param save_mods [Hash<String, MODState>] MODs from save file
-          # @return [void]
-          private def update_mod_list(mod_list, save_mods)
+          # @return [Array<Hash>] Change entries: {mod:, action:, ...}
+          private def plan_mod_list_changes(mod_list, save_mods)
+            changes = []
+
             save_mods.each do |mod_name, mod_state|
               mod = Factorix::MOD[name: mod_name]
+              next if mod.base?
 
-              # base MOD: don't update version or enabled state
-              if mod.base?
-                logger.debug("Skipping base MOD (no changes allowed)", mod_name:)
-                next
+              if mod_list.exist?(mod)
+                changes.concat(plan_existing_mod_changes(mod_list, mod, mod_state))
+              else
+                # Not in list: add it (silently if disabled)
+                changes << {mod:, action: :add, to_enabled: mod_state.enabled?, to_version: mod_state.version}
               end
+            end
+
+            changes
+          end
+
+          # Plan changes for a single MOD that already exists in mod-list.json
+          #
+          # @param mod_list [MODList] Current MOD list
+          # @param mod [MOD] The MOD to plan changes for
+          # @param mod_state [MODState] MOD state from save file
+          # @return [Array<Hash>] Change entries for this MOD
+          private def plan_existing_mod_changes(mod_list, mod, mod_state)
+            current_enabled = mod_list.enabled?(mod)
+            return plan_expansion_mod_changes(mod, mod_state, current_enabled) if mod.expansion?
+
+            current_version = mod_list.version(mod)
+            to_enabled = mod_state.enabled?
+            to_version = mod_state.version
+            enabled_changed = current_enabled != to_enabled
+            version_changed = current_version && current_version != to_version
+
+            if enabled_changed
+              action = to_enabled ? :enable : :disable
+              [{mod:, action:, from_version: current_version, to_version:, from_enabled: current_enabled}]
+            elsif version_changed
+              [{mod:, action: :update, from_version: current_version, to_version:, from_enabled: current_enabled}]
+            else
+              []
+            end
+          end
+
+          # Plan enable/disable changes for an expansion MOD
+          #
+          # @param mod [MOD] The expansion MOD
+          # @param mod_state [MODState] MOD state from save file
+          # @param current_enabled [Boolean] Current enabled state in mod-list.json
+          # @return [Array<Hash>] Change entries (0 or 1 element)
+          private def plan_expansion_mod_changes(mod, mod_state, current_enabled)
+            if mod_state.enabled? && !current_enabled
+              [{mod:, action: :enable}]
+            elsif !mod_state.enabled? && current_enabled
+              [{mod:, action: :disable}]
+            else
+              []
+            end
+          end
+
+          # Find enabled MODs not listed in the save file (excluding conflict MODs)
+          #
+          # @param mod_list [MODList] Current MOD list
+          # @param save_mods [Hash<String, MODState>] MODs from save file
+          # @param conflict_mods [Array<Hash>] Already-planned conflict disables
+          # @return [Array<MOD>] MODs to disable
+          private def find_unlisted_mods(mod_list, save_mods, conflict_mods)
+            conflict_mod_set = Set.new(conflict_mods.map {|c| c[:mod] })
+
+            mod_list.each_mod.select do |mod|
+              !mod.base? &&
+                mod_list.enabled?(mod) &&
+                !save_mods.key?(mod.name) &&
+                !conflict_mod_set.include?(mod)
+            end
+          end
+
+          # Show the combined sync plan
+          #
+          # @param install_targets [Array<Hash>] MODs to install
+          # @param conflict_mods [Array<Hash>] MODs to disable due to conflicts
+          # @param changes [Array<Hash>] MOD list changes from save file
+          # @param unlisted_mods [Array<MOD>] MODs to disable as unlisted
+          # @return [void]
+          private def show_sync_plan(install_targets, conflict_mods, changes, unlisted_mods)
+            unless needs_confirmation?(install_targets, conflict_mods, changes, unlisted_mods)
+              say "Nothing to change", prefix: :info
+              return
+            end
+
+            say "Planning to sync MOD(s):", prefix: :info
 
+            if install_targets.any?
+              say "  Install:"
+              install_targets.each {|t| say "    - #{t[:mod]}@#{t[:release].version}" }
+            end
+
+            enable_changes = changes.select {|c| c[:action] == :enable }
+            if enable_changes.any?
+              say "  Enable:"
+              enable_changes.each {|c| say "    - #{c[:mod]}" }
+            end
+
+            disable_changes = changes.select {|c| c[:action] == :disable }
+            all_disables = conflict_mods.map {|c| {mod: c[:mod], reason: "(conflicts with #{c[:conflicts_with]})"} } +
+                           disable_changes.map {|c| {mod: c[:mod], reason: "(disabled in save file)"} } +
+                           unlisted_mods.map {|m| {mod: m, reason: "(not listed in save file)"} }
+            if all_disables.any?
+              say "  Disable:"
+              all_disables.each {|d| say "    - #{d[:mod]} #{d[:reason]}" }
+            end
+
+            update_changes = changes.select {|c| c[:action] == :update }
+            return if update_changes.none?
+
+            say "  Update:"
+            update_changes.each {|c| say "    - #{c[:mod]} (#{c[:from_version]} \u2192 #{c[:to_version]})" }
+          end
+
+          # Apply all mod-list.json changes
+          #
+          # @param mod_list [MODList] MOD list to modify
+          # @param conflict_mods [Array<Hash>] Conflict entries to disable
+          # @param changes [Array<Hash>] MOD list changes
+          # @param unlisted_mods [Array<MOD>] Unlisted MODs to disable
+          # @return [void]
+          private def apply_mod_list_changes(mod_list, conflict_mods, changes, unlisted_mods)
+            conflict_mods.each do |conflict|
+              mod_list.disable(conflict[:mod])
+              logger.debug("Disabled conflicting MOD", mod_name: conflict[:mod].name, conflicts_with: conflict[:conflicts_with].name)
+            end
+
+            changes.each {|change| apply_single_change(mod_list, change) }
+
+            unlisted_mods.each do |mod|
+              mod_list.disable(mod)
+              logger.debug("Disabled unlisted MOD", mod_name: mod.name)
+            end
+          end
+
+          # Apply a single change entry to mod-list.json
+          #
+          # @param mod_list [MODList] MOD list to modify
+          # @param change [Hash] Change entry from plan_mod_list_changes
+          # @return [void]
+          private def apply_single_change(mod_list, change)
+            mod = change[:mod]
+            case change[:action]
+            when :enable
+              if mod_list.exist?(mod)
+                if mod.expansion?
+                  mod_list.enable(mod)
+                else
+                  mod_list.remove(mod)
+                  mod_list.add(mod, enabled: true, version: change[:to_version])
+                end
+              else
+                mod_list.add(mod, enabled: true, version: change[:to_version])
+              end
+              logger.debug("Enabled MOD in mod-list.json", mod_name: mod.name)
+            when :disable
               if mod_list.exist?(mod)
-                # expansion MOD: only update enabled state (not version)
                 if mod.expansion?
-                  if mod_state.enabled? && !mod_list.enabled?(mod)
-                    mod_list.enable(mod)
-                    logger.debug("Enabled expansion MOD in mod-list.json", mod_name:)
-                  elsif !mod_state.enabled? && mod_list.enabled?(mod)
-                    mod_list.disable(mod)
-                    logger.debug("Disabled expansion MOD in mod-list.json", mod_name:)
-                  end
+                  mod_list.disable(mod)
                 else
-                  # Regular MOD: update both version and enabled state
-                  # Remove and re-add to update version
                   mod_list.remove(mod)
-                  mod_list.add(mod, enabled: mod_state.enabled?, version: mod_state.version)
-                  logger.debug("Updated MOD in mod-list.json", mod_name:, version: mod_state.version&.to_s, enabled: mod_state.enabled?)
+                  mod_list.add(mod, enabled: false, version: change[:to_version])
                 end
               else
-                # Add new entry (version from save file)
-                mod_list.add(mod, enabled: mod_state.enabled?, version: mod_state.version)
-                logger.debug("Added to mod-list.json", mod_name:, version: mod_state.version&.to_s)
+                mod_list.add(mod, enabled: false, version: change[:to_version])
               end
+              logger.debug("Disabled MOD in mod-list.json", mod_name: mod.name)
+            when :update
+              mod_list.remove(mod)
+              mod_list.add(mod, enabled: change[:from_enabled], version: change[:to_version])
+              logger.debug("Updated MOD in mod-list.json", mod_name: mod.name, version: change[:to_version]&.to_s)
+            when :add
+              mod_list.add(mod, enabled: change[:to_enabled], version: change[:to_version])
+              logger.debug("Added MOD to mod-list.json", mod_name: mod.name, version: change[:to_version]&.to_s, enabled: change[:to_enabled])
+            else
+              raise ArgumentError, "Unexpected change action: #{change[:action]}"
             end
           end
 
@@ -271,27 +396,37 @@ module Factorix
           # @param game_version [GameVersion] Game version from save file
           # @return [void]
           private def update_mod_settings(startup_settings, game_version)
-            # Load existing settings or create new
             mod_settings = if runtime.mod_settings_path.exist?
                              MODSettings.load(runtime.mod_settings_path)
                            else
-                             # Create new MODSettings with all sections
                              sections = MODSettings::VALID_SECTIONS.to_h {|section_name|
                                [section_name, MODSettings::Section.new(section_name)]
                              }
                              MODSettings.new(game_version, sections)
                            end
 
-            # Merge startup settings from save file
             startup_section = mod_settings["startup"]
             startup_settings.each do |key, value|
               startup_section[key] = value
             end
 
-            # Save updated settings
             backup_if_exists(runtime.mod_settings_path)
             mod_settings.save(runtime.mod_settings_path)
           end
+
+          # Check whether user-visible changes exist that require confirmation
+          #
+          # @param install_targets [Array<Hash>] MODs to install
+          # @param conflict_mods [Array<Hash>] MODs to disable due to conflicts
+          # @param changes [Array<Hash>] MOD list changes
+          # @param unlisted_mods [Array<MOD>] MODs to disable as unlisted
+          # @return [Boolean]
+          private def needs_confirmation?(install_targets, conflict_mods, changes, unlisted_mods)
+            install_targets.any? ||
+              conflict_mods.any? ||
+              changes.any? {|c| c[:action] != :add || c[:to_enabled] } ||
+              unlisted_mods.any?
+          end
         end
       end
     end

data/lib/factorix/cli.rb

@@ -13,6 +13,8 @@ module Factorix
   class CLI
     extend Dry::CLI::Registry
 
+    register "blueprint decode", Commands::Blueprint::Decode
+    register "blueprint encode", Commands::Blueprint::Encode
     register "version", Commands::Version
     register "man", Commands::Man
     register "launch", Commands::Launch

data/lib/factorix/errors.rb

@@ -71,6 +71,10 @@ module Factorix
 
   class ChangelogParseError < FileFormatError; end
 
+  # Blueprint format errors
+  class BlueprintFormatError < FileFormatError; end
+  class UnsupportedBlueprintVersionError < BlueprintFormatError; end
+
   # =====================================
   # Domain layer errors
   # =====================================

data/lib/factorix/version.rb

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

data/sig/factorix/blueprint.rbs

@@ -0,0 +1,14 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  class Blueprint
+    attr_reader data: Hash[String, untyped]
+
+    def initialize: (Hash[String, untyped] data) -> void
+    def self.decode: (String string) -> Blueprint
+    def encode: () -> String
+    def to_json: (*untyped) -> String
+  end
+end

data/sig/factorix/cli/commands/blueprint/decode.rbs

@@ -0,0 +1,15 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  class CLI
+    module Commands
+      module Blueprint
+        class Decode < Base
+          def call: (?file: String?, ?output: String?, **untyped) -> void
+        end
+      end
+    end
+  end
+end

data/sig/factorix/cli/commands/blueprint/encode.rbs

@@ -0,0 +1,15 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  class CLI
+    module Commands
+      module Blueprint
+        class Encode < Base
+          def call: (?file: String?, ?output: String?, **untyped) -> void
+        end
+      end
+    end
+  end
+end

data/sig/factorix/errors.rbs

@@ -79,6 +79,12 @@ module Factorix
   class ChangelogParseError < FileFormatError
   end
 
+  class BlueprintFormatError < FileFormatError
+  end
+
+  class UnsupportedBlueprintVersionError < BlueprintFormatError
+  end
+
   # =====================================
   # Domain layer errors
   # =====================================

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: factorix
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - OZAWA Sakuro
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-21 00:00:00.000000000 Z
+date: 2026-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -250,6 +250,7 @@ files:
 - lib/factorix/api/release.rb
 - lib/factorix/api/tag.rb
 - lib/factorix/api_credential.rb
+- lib/factorix/blueprint.rb
 - lib/factorix/cache/base.rb
 - lib/factorix/cache/entry.rb
 - lib/factorix/cache/file_system.rb
@@ -259,6 +260,8 @@ files:
 - lib/factorix/cli.rb
 - lib/factorix/cli/commands/backup_support.rb
 - lib/factorix/cli/commands/base.rb
+- lib/factorix/cli/commands/blueprint/decode.rb
+- lib/factorix/cli/commands/blueprint/encode.rb
 - lib/factorix/cli/commands/cache/evict.rb
 - lib/factorix/cli/commands/cache/stat.rb
 - lib/factorix/cli/commands/command_wrapper.rb
@@ -362,6 +365,7 @@ files:
 - sig/factorix/api/release.rbs
 - sig/factorix/api/tag.rbs
 - sig/factorix/api_credential.rbs
+- sig/factorix/blueprint.rbs
 - sig/factorix/cache/base.rbs
 - sig/factorix/cache/entry.rbs
 - sig/factorix/cache/file_system.rbs
@@ -370,6 +374,8 @@ files:
 - sig/factorix/changelog.rbs
 - sig/factorix/cli.rbs
 - sig/factorix/cli/commands/base.rbs
+- sig/factorix/cli/commands/blueprint/decode.rbs
+- sig/factorix/cli/commands/blueprint/encode.rbs
 - sig/factorix/cli/commands/cache/evict.rbs
 - sig/factorix/cli/commands/cache/stat.rbs
 - sig/factorix/cli/commands/command_wrapper.rbs