mxrb 0.1.0

data/lib/mxrb/official_marketplace/lifecycle.rb

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+module Mxrb
+  module OfficialMarketplace
+    # Immutable preview whose mutation is guarded by explicit apply and blockers.
+    class LifecyclePlan
+      attr_reader :action, :name, :installed_version, :target_version, :changes, :blockers
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(action:, name:, installed_version:, target_version:, changes:, blockers:, &operation)
+        @action = action
+        @name = name
+        @installed_version = installed_version
+        @target_version = target_version
+        @changes = changes.freeze
+        @blockers = blockers.freeze
+        @operation = operation
+        @applied = false
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def safe? = blockers.empty?
+      def applied? = @applied
+
+      def apply!
+        raise MarketplaceError, 'Marketplace lifecycle plan was already applied' if applied?
+        raise MarketplaceError, "Marketplace lifecycle plan is blocked: #{blockers.join('; ')}" unless safe?
+
+        @operation.call
+        @applied = true
+        self
+      end
+    end
+
+    # Read-only view of a module package used to compare update boundaries.
+    class ModulePackageInventory
+      attr_reader :name, :version, :module_id, :unit_ids, :files
+
+      def initialize(name:, version:, module_id:, unit_ids:, files:)
+        @name = name
+        @version = version
+        @module_id = module_id
+        @unit_ids = unit_ids.freeze
+        @files = files.freeze
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def self.read(path)
+        Dir.mktmpdir('mxrb-marketplace-inspect-') do |temporary|
+          Zip::File.open(path) do |archive|
+            reader = ModulePackageReader.new(archive)
+            descriptor = reader.descriptor
+            source_path = reader.extract_project(descriptor, temporary)
+            staged = reader.stage_files(descriptor.files, temporary)
+            source = IO::MprFile.open(source_path, readonly: true)
+            module_unit = find_module(source, descriptor.name)
+            raise MarketplaceError, "module #{descriptor.name.inspect} is absent from package MPR" unless module_unit
+
+            ids = subtree_ids(source, module_unit.fetch('UnitID'))
+            files = staged.transform_values { Digest::SHA256.file(_1).hexdigest }
+            return new(
+              name: descriptor.name, version: descriptor.version,
+              module_id: module_unit.fetch('UnitID'), unit_ids: ids, files:
+            )
+          ensure
+            source&.close
+          end
+        end
+      rescue Zip::Error, REXML::ParseException => e
+        raise MarketplaceError, "invalid Mendix module package: #{e.message}"
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      def self.find_module(mpr, name)
+        mpr.units_by_containment('Modules').find { mpr.parse_contents(_1)['Name'] == name }
+      end
+
+      def self.subtree_ids(mpr, root_id)
+        ids = [root_id]
+        loop do
+          children = mpr.all_units.filter_map do |unit|
+            unit.fetch('UnitID') if ids.include?(unit['ContainerID']) && !ids.include?(unit.fetch('UnitID'))
+          end
+          break if children.empty?
+
+          ids.concat(children)
+        end
+        ids
+      end
+    end
+
+    # Transactional lifecycle for modules already recorded in marketplace.lock.json.
+    class Lifecycle # rubocop:disable Metrics/ClassLength
+      def initialize(target:, mpr:, installer:)
+        @target = File.expand_path(target)
+        @mpr = mpr && File.expand_path(mpr)
+        @installer = installer
+      end
+
+      def installed(identifier)
+        pair = packages.find do |name, entry|
+          name.casecmp(identifier.to_s).zero? || entry['content_id'].to_s == identifier.to_s
+        end
+        raise MarketplaceError, "Marketplace package #{identifier.inspect} is not installed" unless pair
+        raise MarketplaceError, "Marketplace package #{pair.first.inspect} is not an imported module" \
+          unless pair.last['kind'] == 'module'
+
+        pair
+      end
+
+      def mpr_path(entry)
+        path = safe_path(entry.fetch('destination'))
+        raise MarketplaceError, 'selected MPR does not match the Marketplace lock' if @mpr && @mpr != path
+
+        path
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def plan_remove(identifier)
+        name, entry = installed(identifier)
+        mpr = mpr_path(entry)
+        ids = target_unit_ids(mpr, entry)
+        inventory = cached_inventory(entry)
+        shared = shared_files(name)
+        blockers = base_blockers(entry, inventory, ids)
+        blockers << "locked module name does not match cached package #{inventory.name}" if inventory.name != name
+        blockers.concat(external_reference_blockers(mpr, ids))
+        blockers.concat(modified_asset_blockers(inventory, name))
+        removable = inventory.files.keys - shared
+        changes = ["delete #{ids.size} MPR units", "delete #{removable.size} package assets",
+                   'delete cached package and lock entry']
+        LifecyclePlan.new(
+          action: :remove, name:, installed_version: entry['version'], target_version: nil,
+          changes:, blockers:
+        ) { apply_remove(name, entry, mpr, ids, removable) }
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def plan_update(identifier, archive, package)
+        name, entry = installed(identifier)
+        mpr = mpr_path(entry)
+        current_ids = target_unit_ids(mpr, entry)
+        current = cached_inventory(entry)
+        replacement = ModulePackageInventory.read(archive)
+        missing_ids = current_ids - replacement.unit_ids
+        blockers = base_blockers(entry, current, current_ids)
+        blockers << "replacement module name changed from #{name} to #{replacement.name}" if replacement.name != name
+        blockers << 'replacement module identity changed' if replacement.module_id != entry['module_id']
+        blockers << "downloaded package version #{replacement.version} does not match #{package.version}" \
+          unless package_version_matches?(replacement.version, package.version)
+        blockers << "version #{package.version} is already installed" if package.version.to_s == entry['version'].to_s
+        blockers.concat(external_reference_blockers(mpr, missing_ids))
+        blockers.concat(modified_asset_blockers(current, name))
+        obsolete = current.files.keys - replacement.files.keys - shared_files(name)
+        changes = ["replace #{current_ids.size} MPR units with #{replacement.unit_ids.size}",
+                   "install #{replacement.files.size} package assets",
+                   "delete #{obsolete.size} obsolete package assets", 'replace cache and lock metadata']
+        LifecyclePlan.new(
+          action: :update, name:, installed_version: entry['version'], target_version: package.version,
+          changes:, blockers:
+        ) { apply_update(entry, mpr, current_ids, obsolete, archive, package, replacement) }
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      private
+
+      def packages = OfficialMarketplace.lock(@target).fetch('packages')
+
+      def safe_path(relative)
+        path = File.expand_path(File.join(@target, relative.to_s))
+        prefix = "#{@target}#{File::SEPARATOR}"
+        raise MarketplaceError, "path is outside marketplace target: #{path}" unless path.start_with?(prefix)
+
+        path
+      end
+
+      def cached_inventory(entry)
+        archive = safe_path(entry.fetch('archive'))
+        raise MarketplaceError, "cached Marketplace package is missing: #{archive}" unless File.file?(archive)
+
+        ModulePackageInventory.read(archive)
+      end
+
+      def target_unit_ids(mpr_path, entry)
+        raise MarketplaceError, "MPR not found: #{mpr_path}" unless File.file?(mpr_path)
+
+        mpr = IO::MprFile.open(mpr_path, readonly: true)
+        root = mpr.unit(entry.fetch('module_id'))
+        raise MarketplaceError, "module #{entry.fetch('module_id')} is absent from target MPR" unless root
+
+        ModulePackageInventory.subtree_ids(mpr, root.fetch('UnitID'))
+      ensure
+        mpr&.close
+      end
+
+      def base_blockers(entry, inventory, ids)
+        blockers = []
+        blockers << 'locked module identity does not match cached package' if inventory.module_id != entry['module_id']
+        blockers << 'locked unit count does not match target module tree' if entry['units'].to_i != ids.size
+        blockers
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def external_reference_blockers(mpr_path, ids)
+        return [] if ids.empty?
+
+        id_set = ids.map(&:downcase)
+        mpr = IO::MprFile.open(mpr_path, readonly: true)
+        mpr.all_units.filter_map do |unit|
+          next if id_set.include?(unit.fetch('UnitID').downcase)
+
+          document = mpr.parse_contents(unit)
+          matches = id_set.select { JSON.generate(document).downcase.include?(_1) }
+          next if matches.empty?
+
+          "#{document['Name'] || document['$Type'] || unit.fetch('UnitID')} references " \
+            "#{matches.size} unit(s) scheduled for removal"
+        end
+      ensure
+        mpr&.close
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      def modified_asset_blockers(inventory, owner_name)
+        shared = shared_files(owner_name)
+        inventory.files.filter_map do |relative, expected|
+          next if shared.include?(relative)
+
+          path = safe_path(relative)
+          actual = Digest::SHA256.file(path).hexdigest if File.file?(path) && !File.symlink?(path)
+          "package asset changed or missing: #{relative}" unless actual == expected
+        end
+      end
+
+      def shared_files(name)
+        packages.filter_map do |other_name, entry|
+          Array(entry['files']) unless other_name == name
+        end.flatten.uniq
+      end
+
+      def package_version_matches?(manifest_version, official_version)
+        value = manifest_version.to_s
+        value.empty? || value == 'unknown' || value == official_version.to_s
+      end
+
+      def apply_remove(name, entry, mpr, ids, files)
+        paths = lifecycle_paths(entry, mpr, files)
+        with_rollback(paths) do
+          delete_units(mpr, ids)
+          restore_assets(entry, files)
+          remove_atlas_variables if name == 'Atlas_Core'
+          FileUtils.rm_f(safe_path(entry.fetch('archive')))
+          delete_asset_backups(entry)
+          delete_lock_entry(name)
+        end
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
+      def apply_update(entry, mpr, ids, obsolete, archive, package, replacement)
+        new_cache = cache_path(replacement)
+        files = (Array(entry['files']) + replacement.files.keys).uniq
+        paths = lifecycle_paths(entry, mpr, files) + [new_cache]
+        with_rollback(paths.uniq) do
+          delete_units(mpr, ids)
+          @installer.send(:import_module, archive, package, mpr)
+          restore_assets(entry, obsolete)
+          delete_asset_backups(entry, obsolete)
+          old_cache = safe_path(entry.fetch('archive'))
+          FileUtils.rm_f(old_cache) unless old_cache == new_cache
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
+
+      def delete_units(mpr_path, ids)
+        mpr = IO::MprFile.open(mpr_path)
+        mpr.transaction { ids.reverse_each { mpr.delete_unit(_1) } }
+      ensure
+        mpr&.close
+      end
+
+      def lifecycle_paths(entry, mpr, files)
+        contents = File.join(File.dirname(mpr), 'mprcontents')
+        lock = File.join(@target, '.mxrb', 'marketplace.lock.json')
+        custom = File.join(@target, 'theme', 'web', 'custom-variables.scss')
+        originals = File.join(@target, '.mxrb', 'marketplace-originals')
+        [mpr, contents, lock, custom, originals, safe_path(entry.fetch('archive'))] + files.map { safe_path(_1) }
+      end
+
+      def cache_path(inventory)
+        version = inventory.version.to_s.gsub(/[^A-Za-z0-9_.-]/, '_')
+        File.join(@target, '.mxrb', 'marketplace', "#{inventory.name}-#{version}.mpk")
+      end
+
+      def with_rollback(paths)
+        Dir.mktmpdir('mxrb-marketplace-rollback-') do |temporary|
+          snapshots = []
+          paths.uniq.each_with_index { |path, index| snapshots << snapshot(path, temporary, index) }
+          yield
+        rescue StandardError
+          snapshots.reverse_each { restore_snapshot(_1) }
+          raise
+        end
+      end
+
+      def snapshot(path, temporary, index)
+        backup = File.join(temporary, index.to_s)
+        type = snapshot_type(path)
+        FileUtils.cp_r(path, backup) if type == :directory
+        FileUtils.cp(path, backup) if type == :file
+        [path, backup, type]
+      end
+
+      def snapshot_type(path)
+        return :directory if File.directory?(path)
+        return :file if File.file?(path)
+
+        :missing
+      end
+
+      def restore_snapshot(snapshot)
+        path, backup, type = snapshot
+        FileUtils.rm_rf(path) if File.directory?(path)
+        FileUtils.rm_f(path) if File.file?(path)
+        return if type == :missing
+
+        FileUtils.mkdir_p(File.dirname(path))
+        type == :directory ? FileUtils.cp_r(backup, path) : FileUtils.cp(backup, path)
+      end
+
+      def delete_lock_entry(name)
+        path = File.join(@target, '.mxrb', 'marketplace.lock.json')
+        lock = OfficialMarketplace.lock(@target)
+        lock.fetch('packages').delete(name)
+        @installer.send(:write_lock_atomically, path, lock)
+      end
+
+      def restore_assets(entry, files) # rubocop:disable Metrics/MethodLength
+        originals = entry.fetch('asset_originals', {})
+        files.each do |relative|
+          destination = safe_path(relative)
+          backup = originals[relative]
+          if backup && File.file?(safe_path(backup))
+            FileUtils.mkdir_p(File.dirname(destination))
+            FileUtils.cp(safe_path(backup), destination)
+          else
+            FileUtils.rm_f(destination)
+          end
+        end
+      end
+
+      def delete_asset_backups(entry, files = nil)
+        originals = entry.fetch('asset_originals', {})
+        selected = files ? originals.slice(*files) : originals
+        selected.each_value { FileUtils.rm_f(safe_path(_1)) if _1 }
+      end
+
+      def remove_atlas_variables
+        path = File.join(@target, 'theme', 'web', 'custom-variables.scss')
+        return unless File.file?(path)
+
+        lines = File.readlines(path).reject { _1.strip == Installer::ATLAS_VARIABLES_IMPORT }
+        File.write(path, lines.join)
+      end
+    end
+  end
+end

data/lib/mxrb/official_marketplace/module_package_importer.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'rexml/document'
+require 'tmpdir'
+require 'zip'
+
+module Mxrb
+  module OfficialMarketplace
+    # Parses and safely stages a Mendix module package archive.
+    class ModulePackageReader
+      Descriptor = Data.define(:name, :version, :model_version, :project_file, :files)
+
+      def initialize(archive)
+        @archive = archive
+      end
+
+      def descriptor
+        package_xml = @archive.find_entry('package.xml')
+        raise MarketplaceError, 'package.xml is missing' unless package_xml
+
+        document = REXML::Document.new(package_xml.get_input_stream.read)
+        build_descriptor(document, parse_manifest)
+      end
+
+      def extract_project(descriptor, temporary)
+        entry = @archive.find_entry(descriptor.project_file)
+        raise MarketplaceError, "package project not found: #{descriptor.project_file}" unless entry
+
+        copy_entry(entry, File.join(temporary, 'source.mpr'))
+      end
+
+      def stage_files(files, temporary)
+        root = File.join(temporary, 'assets')
+        files.to_h do |relative|
+          entry = @archive.find_entry(relative) || @archive.find_entry(relative.tr('/', '\\'))
+          raise MarketplaceError, "declared package file is missing: #{relative}" unless entry&.file?
+
+          [relative, copy_entry(entry, File.join(root, relative))]
+        end
+      end
+
+      private
+
+      # Package metadata is intentionally validated as one boundary.
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def build_descriptor(document, manifest)
+        module_element = element(document, 'module')
+        project_element = element(document, 'projectFile')
+        raise MarketplaceError, 'package does not contain a Mendix module' unless module_element
+        raise MarketplaceError, 'package does not declare project.mpr' unless project_element
+
+        name = valid_module_name(module_element.attributes['name'])
+        validate_package_type!(manifest.dig('package', 'type'))
+        Descriptor.new(
+          name, manifest.dig('package', 'version') || 'unknown', manifest['model-version'],
+          safe_relative_path(project_element.attributes['path']),
+          elements(document, 'file').map { safe_relative_path(_1.attributes['path']) }.uniq
+        )
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      def valid_module_name(value)
+        name = value.to_s
+        return name if name.match?(/\A[A-Za-z][A-Za-z0-9_]*\z/)
+
+        raise MarketplaceError, "invalid module name #{name.inspect}"
+      end
+
+      def validate_package_type!(value)
+        package_type = value.to_s
+        return if package_type.empty? || package_type.casecmp('Module').zero?
+
+        raise MarketplaceError, "unsupported marketplace package type #{package_type.inspect}"
+      end
+
+      def parse_manifest
+        entry = @archive.find_entry('manifest.json')
+        entry ? JSON.parse(entry.get_input_stream.read) : {}
+      rescue JSON::ParserError => e
+        raise MarketplaceError, "invalid module manifest: #{e.message}"
+      end
+
+      def elements(document, name)
+        found = []
+        document.root&.each_recursive { found << _1 if _1.is_a?(REXML::Element) && _1.name == name }
+        found
+      end
+
+      def element(document, name) = elements(document, name).first
+
+      def safe_relative_path(value)
+        path = value.to_s.tr('\\', '/')
+        parts = path.split('/')
+        unsafe = path.empty? || path.start_with?('/') || parts.include?('..') || parts.include?('')
+        raise MarketplaceError, "unsafe package path #{value.inspect}" if unsafe
+        raise MarketplaceError, "protected package path #{value.inspect}" if protected_path?(parts)
+
+        parts.join('/')
+      end
+
+      def protected_path?(parts)
+        %w[.git .mxrb mprcontents].include?(parts.first.downcase) ||
+          parts.last.downcase.end_with?('.mpr') && parts.length > 1
+      end
+
+      def copy_entry(entry, destination)
+        FileUtils.mkdir_p(File.dirname(destination))
+        File.open(destination, 'wb') { ::IO.copy_stream(entry.get_input_stream, _1) }
+        destination
+      end
+    end
+
+    # Installs declared package files with rollback support.
+    class ModulePackageAssets
+      def initialize(target_root, temporary)
+        @target_root = target_root
+        @backup_root = File.join(temporary, 'backups')
+        @changes = []
+      end
+
+      def install(staged_files, protected_files = [])
+        staged_files.each do |relative, source|
+          install_file(relative, source) unless protected_files.include?(relative)
+        end
+      end
+
+      def rollback
+        @changes.reverse_each do |destination, backup|
+          backup ? FileUtils.cp(backup, destination) : FileUtils.rm_f(destination)
+        end
+      end
+
+      private
+
+      def install_file(relative, source)
+        destination = safe_destination(relative)
+        raise MarketplaceError, "asset destination is a symbolic link: #{relative}" if File.symlink?(destination)
+        raise MarketplaceError, "asset destination is a directory: #{relative}" if File.directory?(destination)
+
+        backup = backup_file(relative, destination)
+        @changes << [destination, backup]
+        FileUtils.mkdir_p(File.dirname(destination))
+        FileUtils.cp(source, destination)
+      end
+
+      def safe_destination(relative)
+        destination = File.expand_path(File.join(@target_root, relative))
+        prefix = "#{@target_root}#{File::SEPARATOR}"
+        raise MarketplaceError, "unsafe asset destination: #{relative}" unless destination.start_with?(prefix)
+
+        destination
+      end
+
+      def backup_file(relative, destination)
+        return unless File.file?(destination)
+
+        backup = File.join(@backup_root, relative)
+        FileUtils.mkdir_p(File.dirname(backup))
+        FileUtils.cp(destination, backup)
+        backup
+      end
+    end
+
+    # Imports a Mendix module package directly into an MPR without Studio Pro.
+    class ModulePackageImporter # rubocop:disable Metrics/ClassLength
+      Result = Data.define(
+        :module_name, :package_version, :module_id, :units, :files,
+        :source_version, :target_version
+      )
+
+      def initialize(package_path, mpr_path, target_root: nil, allow_model_upgrade: false,
+                     protected_files: [])
+        @package_path = File.expand_path(package_path)
+        @mpr_path = File.expand_path(mpr_path)
+        @target_root = File.expand_path(target_root || File.dirname(@mpr_path))
+        @allow_model_upgrade = allow_model_upgrade
+        @protected_files = protected_files
+      end
+
+      def import!
+        validate_inputs!
+        Dir.mktmpdir('mxrb-module-import-') do |temporary|
+          Zip::File.open(@package_path) { import_archive(_1, temporary) }
+        end
+      rescue Zip::Error, REXML::ParseException => e
+        raise MarketplaceError, "invalid Mendix module package: #{e.message}"
+      end
+
+      private
+
+      def import_archive(archive, temporary)
+        reader = ModulePackageReader.new(archive)
+        descriptor = reader.descriptor
+        source_path = reader.extract_project(descriptor, temporary)
+        staged_files = reader.stage_files(descriptor.files, temporary)
+        import_project(source_path, descriptor, staged_files, temporary)
+      end
+
+      def validate_inputs!
+        raise MarketplaceError, "package not found: #{@package_path}" unless File.file?(@package_path)
+        raise MarketplaceError, "MPR not found: #{@mpr_path}" unless File.file?(@mpr_path)
+        raise MarketplaceError, "target root not found: #{@target_root}" unless File.directory?(@target_root)
+      end
+
+      def import_project(source_path, descriptor, staged_files, temporary) # rubocop:disable Metrics/MethodLength
+        source = IO::MprFile.open(source_path, readonly: true)
+        target = IO::MprFile.open(@mpr_path)
+        assets = ModulePackageAssets.new(@target_root, temporary)
+        imported_ids = []
+        import_transaction(source, target, descriptor, staged_files, assets, imported_ids)
+        import_result(source, target, descriptor, staged_files, imported_ids)
+      rescue StandardError
+        assets&.rollback
+        cleanup_v2_units(target, imported_ids)
+        raise
+      ensure
+        source&.close
+        target&.close
+      end
+
+      # rubocop:disable Metrics/ParameterLists
+      def import_transaction(source, target, descriptor, staged_files, assets, imported_ids)
+        validate_versions!(source, target, descriptor)
+        module_unit, units = package_units(source, descriptor.name)
+        validate_target!(target, descriptor.name, units)
+        target.transaction do
+          imported_ids.concat(insert_units(source, target, module_unit, units))
+          assets.install(staged_files, @protected_files)
+        end
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def insert_units(source, target, module_unit, units)
+        units.map do |unit|
+          container = unit == module_unit ? target.root_unit.fetch('UnitID') : unit.fetch('ContainerID')
+          target.insert_unit(
+            container_uuid: container, containment_name: unit.fetch('ContainmentName'),
+            contents_doc: source.parse_contents(unit)
+          )
+        end
+      end
+
+      def import_result(source, target, descriptor, staged_files, imported_ids)
+        Result.new(
+          descriptor.name, descriptor.version, imported_ids.first, imported_ids.size,
+          staged_files.keys, source.mendix_version, target.mendix_version
+        )
+      end
+
+      def validate_versions!(source, target, descriptor)
+        package_version = descriptor.model_version.to_s
+        if !package_version.empty? && package_version != source.mendix_version
+          raise MarketplaceError,
+                "module manifest version #{package_version} does not match package MPR #{source.mendix_version}"
+        end
+        return if source.mendix_version == target.mendix_version
+        return if @allow_model_upgrade && forward_version?(source.mendix_version, target.mendix_version)
+
+        raise MarketplaceError,
+              "module uses Mendix #{source.mendix_version}, target uses #{target.mendix_version}; " \
+              'pure-Ruby import requires matching model versions'
+      end
+
+      def forward_version?(source, target)
+        Gem::Version.new(numeric_version(target)) >= Gem::Version.new(numeric_version(source))
+      end
+
+      def numeric_version(value)
+        value.to_s[/\A\d+(?:\.\d+){0,3}/] || '0'
+      end
+
+      def package_units(source, module_name) # rubocop:disable Metrics/MethodLength
+        module_unit = find_module_unit(source, module_name)
+        raise MarketplaceError, "module #{module_name.inspect} is absent from package MPR" unless module_unit
+
+        units = [module_unit]
+        loop do
+          ids = units.map { _1.fetch('UnitID') }
+          children = source.all_units.select do |unit|
+            ids.include?(unit['ContainerID']) && !ids.include?(unit['UnitID'])
+          end
+          break if children.empty?
+
+          units.concat(children)
+        end
+        [module_unit, units]
+      end
+
+      def find_module_unit(source, module_name)
+        source.units_by_containment('Modules').find do |unit|
+          document = source.parse_contents(unit)
+          %w[Projects$ModuleImpl Projects$Module].include?(document['$Type']) &&
+            document['Name'] == module_name
+        end
+      end
+
+      def validate_target!(target, module_name, units)
+        duplicate = target.units_by_containment('Modules').any? do |unit|
+          target.parse_contents(unit)['Name'] == module_name
+        end
+        raise MarketplaceError, "module #{module_name} already exists in target MPR" if duplicate
+
+        existing_ids = target.all_units.to_h { [_1.fetch('UnitID'), true] }
+        collision = units.find { existing_ids[_1.fetch('UnitID')] }
+        return unless collision
+
+        raise MarketplaceError, "module unit ID already exists: #{collision.fetch('UnitID')}"
+      end
+
+      def cleanup_v2_units(target, ids)
+        return unless target&.format_version == :v2
+
+        Array(ids).each { FileUtils.rm_f(target.content_path('UnitID' => _1)) }
+      end
+    end
+  end
+end