bulkrax 9.3.4 → 9.4.0

data/app/controllers/concerns/bulkrax/importer_file_handler.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Bulkrax
+  # rubocop:disable Metrics/ModuleLength
+  module ImporterFileHandler
+    extend ActiveSupport::Concern
+
+    private
+
+    # Resolves files for validation from either a server-side file path, pre-uploaded Hyrax files, or direct upload params
+    # @return [Array<(Array<File>, nil)>] on success, a tuple of [files, nil]
+    # @return [Array<(nil, Hash)>] on error, a tuple of [nil, error_response]
+    def resolve_validation_files
+      if import_via_file_path?
+        return [nil, StepperResponseFormatter.error(message: I18n.t('bulkrax.importer.guided_import.validation.file_path_not_exist'))] unless File.exist?(import_file_path)
+
+        [[File.open(import_file_path)], nil]
+      elsif params[:uploaded_files].present?
+        resolve_hyrax_uploaded_files
+      else
+        files = params[:importer]&.[](:parser_fields)&.[](:files) || []
+        files = [files] unless files.is_a?(Array)
+        [files.compact, nil]
+      end
+    end
+
+    # Loads files from Hyrax::UploadedFile IDs (used by chunked upload flow).
+    # Scoped to current_user to prevent accessing another user's uploads.
+    def resolve_hyrax_uploaded_files
+      uploads = uploaded_files_scope
+      return [nil, StepperResponseFormatter.error(message: 'No uploaded files found for the given IDs')] if uploads.empty?
+
+      files = uploads.filter_map do |u|
+        path = u.file&.path
+        next nil unless path && File.exist?(path)
+        File.open(path)
+      end
+      [files, nil]
+    rescue StandardError => e
+      Rails.logger.error("Bulkrax: error loading Hyrax uploaded files: #{e.class}: #{e.message}")
+      Rails.logger.debug { e.full_message }
+      [nil, StepperResponseFormatter.error(message: 'Failed to load uploaded files')]
+    end
+
+    def uploaded_files_scope
+      return [] unless defined?(::Hyrax)
+
+      base = Hyrax::UploadedFile.where(id: params[:uploaded_files])
+      if respond_to?(:current_user) && current_user.present?
+        base.where(user_id: current_user.id)
+      else
+        base.none
+      end
+    end
+
+    def resolve_create_files
+      if params[:uploaded_files].present?
+        uploads = uploaded_files_scope
+        uploads.filter_map do |u|
+          path = u.file&.path
+          next nil unless path && File.exist?(path)
+          File.open(path)
+        end
+      else
+        extract_uploaded_files
+      end
+    end
+
+    def extract_uploaded_files
+      files_param = params[:importer]&.[](:parser_fields)&.[](:files)
+      return [] if files_param.blank?
+
+      files_param.is_a?(Array) ? files_param.compact : [files_param].compact
+    end
+
+    # Scans the given files for a CSV and a ZIP by file extension
+    # @param files [Array<File, ActionDispatch::Http::UploadedFile>] the resolved files to search
+    # @return [Array<(File, nil), (nil, File), (File, File), (nil, nil)>] a tuple of [csv_file, zip_file]; either may be nil
+    def select_csv_and_zip(files)
+      csv_file = files.find { |f| filename_for(f)&.end_with?('.csv') }
+      zip_file = files.find { |f| filename_for(f)&.end_with?('.zip') }
+      [csv_file, zip_file]
+    end
+
+    # Returns a filename from any file-like object (ActionDispatch upload, File, or Tempfile)
+    def filename_for(file)
+      if file.respond_to?(:original_filename)
+        file.original_filename
+      elsif file.respond_to?(:path)
+        file.path
+      end
+    end
+
+    # Opens a ZIP and extracts the CSV content into a StringIO while the archive is open
+    # @param zip_file [File] the ZIP file to search
+    # @return [Array<(StringIO, nil)>] on success, a tuple of [csv_file, nil]
+    # @return [Array<(nil, Hash)>] on error, a tuple of [nil, error_response]
+    def extract_csv_from_zip(zip_file)
+      csv_file = nil
+      error = nil
+      Zip::File.open(zip_file.path) do |zip|
+        result = locate_csv_entry_in_zip(zip)
+        if result.is_a?(Hash) && result[:messages]
+          error = result
+        elsif result
+          csv_file = StringIO.new(result.get_input_stream.read)
+        end
+      end
+      [csv_file, error]
+    end
+
+    # Finds a CSV entry in a ZIP by traversing directory levels, preferring the shallowest
+    # @param zip [Zip::File] the open ZIP archive to search
+    # @return [Zip::Entry] the CSV entry on success
+    # @return [Hash] an error response hash if no CSV is found or multiple CSVs are ambiguous
+    def locate_csv_entry_in_zip(zip)
+      csv_entries = group_entries_by_directory_level(zip)
+
+      return StepperResponseFormatter.error(message: I18n.t('bulkrax.importer.guided_import.validation.no_csv_in_zip')) if csv_entries.empty?
+
+      csv_by_depth = get_directory_depth_for_each_csv(csv_entries)
+      csvs_at_level = determine_csvs_at_shallowest_level(csv_by_depth)
+
+      csvs_by_directory = csvs_at_level.group_by { |entry| File.dirname(entry.name) }
+      csvs_by_directory.each do |_dir, csvs|
+        return StepperResponseFormatter.error(message: I18n.t('bulkrax.importer.guided_import.validation.multiple_csv_same_dir')) if csvs.count > 1
+      end
+
+      return StepperResponseFormatter.error(message: I18n.t('bulkrax.importer.guided_import.validation.multiple_csv_same_level')) if csvs_at_level.size > 1
+
+      csvs_at_level.first
+    end
+
+    def group_entries_by_directory_level(zip)
+      zip.select { |entry| entry.name.end_with?('.csv') && !entry.directory? }
+    end
+
+    def get_directory_depth_for_each_csv(entries)
+      entries.group_by { |entry| entry.name.count('/') }
+    end
+
+    def determine_csvs_at_shallowest_level(csv_by_depth)
+      shallowest_depth = csv_by_depth.keys.min
+      csv_by_depth[shallowest_depth]
+    end
+
+    # Persists uploaded file(s) and/or cloud files onto the importer record.
+    # @param file [ActionDispatch::Http::UploadedFile, nil] a directly uploaded file
+    # @param cloud_files [Hash, nil] cloud file paths from browse-everything
+    # @param uploads [ActiveRecord::Relation, Array, nil] Hyrax::UploadedFile records
+    def files_for_import(file, cloud_files, uploads)
+      return if file.blank? && cloud_files.blank? && uploads.blank?
+
+      @importer[:parser_fields]['import_file_path'] = @importer.parser.write_import_file(file) if file.present?
+      if cloud_files.present?
+        @importer[:parser_fields]['cloud_file_paths'] = cloud_files
+        # For BagIt, there will only be one bag, so we get the file_path back and set import_file_path
+        # For CSV, we expect only file uploads, so we won't get the file_path back
+        # and we expect the import_file_path to be set already
+        target = @importer.parser.retrieve_cloud_files(cloud_files, @importer)
+        @importer[:parser_fields]['import_file_path'] = target if target.present?
+      end
+
+      if uploads.present?
+        uploads.each do |upload|
+          @importer[:parser_fields]['import_file_path'] = @importer.parser.write_import_file(upload.file.file)
+        end
+      end
+
+      @importer.save
+    end
+
+    def write_files(files)
+      csv_file, zip_file = select_csv_and_zip(files)
+
+      csv_path = write_file_if_present(csv_file)
+      zip_path = write_file_if_present(zip_file)
+
+      return unless csv_path || zip_path
+
+      # Determine import_file_path: prefer CSV, fallback to ZIP
+      @importer.parser_fields['import_file_path'] = csv_path || zip_path
+      @importer.parser_fields['attachments_zip_path'] = zip_path if zip_path && csv_path
+
+      @importer.save
+    rescue StandardError => e
+      Rails.logger.error("Bulkrax::ImporterFileHandler#write_files failed: #{e.message}")
+      raise
+    end
+
+    def write_file_if_present(file)
+      return nil unless file
+
+      if file.respond_to?(:original_filename)
+        @importer.parser.write_import_file(file)
+      else
+        dest_path = File.join(@importer.parser.path_for_import, File.basename(file.path))
+        FileUtils.cp(file.path, dest_path)
+        dest_path
+      end
+    end
+
+    def close_file_handles(files)
+      return unless files.is_a?(Array)
+      files.each { |f| f.close if f.respond_to?(:close) }
+    end
+
+    def import_via_file_path?
+      import_file_path.present?
+    end
+
+    def import_file_path
+      @file_path ||= params[:importer]&.[](:parser_fields)&.[](:import_file_path)
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/app/factories/bulkrax/object_factory.rb

@@ -70,14 +70,15 @@ module Bulkrax
       properties.reject { |prop| Bulkrax.reserved_properties.include?(prop) }
     end
 
-    def self.field_multi_value?(field:, model:)
+    #  Unused admin set included to support flexible contexts in the Valkyrie version
+    def self.field_multi_value?(field:, model:, admin_set_id: nil) # rubocop:disable Lint/UnusedMethodArgument
       return false unless field_supported?(field: field, model: model)
       return false unless model.singleton_methods.include?(:properties)
 
       model&.properties&.[](field)&.[]("multiple")
     end
 
-    def self.field_supported?(field:, model:)
+    def self.field_supported?(field:, model:, admin_set_id: nil) # rubocop:disable Lint/UnusedMethodArgument
       model.method_defined?(field) && model.properties[field].present?
     end
 

data/app/factories/bulkrax/valkyrie_object_factory.rb

@@ -120,11 +120,11 @@ module Bulkrax
       save!(resource: resource, user: user)
     end
 
-    def self.field_multi_value?(field:, model:)
-      return false unless field_supported?(field: field, model: model)
+    def self.field_multi_value?(field:, model:, admin_set_id: nil)
+      return false unless field_supported?(field: field, model: model, admin_set_id: admin_set_id)
 
       if model.respond_to?(:schema)
-        schema = model.new.singleton_class.schema || model.schema
+        schema = cached_schema_for(klass: model, admin_set_id: admin_set_id)
         dry_type = schema.key(field.to_sym)
         return true if dry_type.respond_to?(:primitive) && dry_type.primitive == Array
 
@@ -134,9 +134,9 @@ module Bulkrax
       end
     end
 
-    def self.field_supported?(field:, model:)
+    def self.field_supported?(field:, model:, admin_set_id: nil)
       if model.respond_to?(:schema)
-        schema_properties(model).include?(field)
+        schema_properties(klass: model, admin_set_id: admin_set_id).include?(field)
       else
         # We *might* have a Fedora object, so we need to consider that approach as
         # well.
@@ -272,17 +272,34 @@ module Bulkrax
     # rubocop:enable Metrics/ParameterLists
 
     ##
-    # Retrieve properties from M3 model
-    # @param klass the model
+    # Retrieve schema property names for a model, respecting admin set contexts
+    # when using flexible metadata. Delegates context resolution to Hyrax so
+    # Bulkrax does not need to know about HYRAX_FLEXIBLE or contexts.
+    #
+    # @param klass [Class] the model class
+    # @param admin_set_id [String, nil] admin set used to resolve contexts
     # @return [Array<String>]
-    def self.schema_properties(klass)
-      @schema_properties_map ||= {}
-
-      klass_key = klass.name
-      schema = klass.new.singleton_class.schema || klass.schema
-      @schema_properties_map[klass_key] = schema.map { |k| k.name.to_s } unless @schema_properties_map.key?(klass_key)
+    def self.schema_properties(klass:, admin_set_id: nil)
+      cached_schema_for(klass: klass, admin_set_id: admin_set_id).map { |k| k.name.to_s }
+    end
 
-      @schema_properties_map[klass_key]
+    ##
+    # Returns the schema for a model, memoized per (klass, admin_set_id) pair.
+    # Delegates to +Hyrax.schema_for+ when available so that context-gated
+    # properties are included without Bulkrax knowing about flexibility internals.
+    #
+    # @param klass [Class]
+    # @param admin_set_id [String, nil]
+    # @return [Dry::Types::Hash]
+    def self.cached_schema_for(klass:, admin_set_id: nil)
+      @cached_schema_map ||= {}
+      key = [klass.name, admin_set_id].compact.join('|')
+      @cached_schema_map[key] ||=
+        if admin_set_id.present? && defined?(Hyrax) && Hyrax.respond_to?(:schema_for)
+          Hyrax.schema_for(klass: klass, admin_set_id: admin_set_id)
+        else
+          klass.new.singleton_class.schema || klass.schema
+        end
     end
 
     def self.ordered_file_sets_for(object)
@@ -457,7 +474,9 @@ module Bulkrax
     # TODO What do we return when the calculated form fails?
     # @raise [StandardError] when there was a failure calling the translation.
     def perform_transaction_for(object:, attrs:)
-      form = Hyrax::Forms::ResourceForm.for(object).prepopulate!
+      admin_set_id = attrs[:admin_set_id] || attrs['admin_set_id'] ||
+                     attributes[:admin_set_id] || attributes['admin_set_id']
+      form = Hyrax::Forms::ResourceForm.for(resource: object, admin_set_id: admin_set_id).prepopulate!
 
       # TODO: Handle validations
       form.validate(attrs)
@@ -474,13 +493,15 @@ module Bulkrax
     end
 
     ##
-    # We accept attributes based on the model schema
+    # We accept attributes based on the model schema. Passes the admin set ID
+    # so that context-restricted properties are included in the permitted list.
     #
     # @return [Array<Symbols>]
     def permitted_attributes
       @permitted_attributes ||= (
         base_permitted_attributes + if klass.respond_to?(:schema)
-                                      Bulkrax::ValkyrieObjectFactory.schema_properties(klass)
+                                      admin_set_id = attributes[:admin_set_id] || attributes['admin_set_id']
+                                      Bulkrax::ValkyrieObjectFactory.schema_properties(klass: klass, admin_set_id: admin_set_id)
                                     else
                                       klass.properties.keys.map(&:to_sym)
                                     end
@@ -590,6 +611,29 @@ module Bulkrax
                    .symbolize_keys
 
       attrs[:title] = [] if attrs[:title].blank?
+      attrs = convert_based_near_to_attributes(attrs)
+      attrs
+    end
+
+    # Hyrax's ResourceForm strips the plain `based_near` key during validation
+    # (BasedNearFieldBehavior#deserialize calls params.except('based_near')).
+    # Values must be passed as `based_near_attributes` — a numbered hash of
+    # { "0" => { "id" => uri, "_destroy" => "false" } } — so the populator
+    # can set them. Hyrax accepts any valid URI; note that only GeoNames URIs
+    # will resolve to a display label via LocationService.
+    def convert_based_near_to_attributes(attrs)
+      values = Array.wrap(attrs.delete(:based_near)).reject(&:blank?)
+      return attrs if values.empty?
+
+      invalid = values.reject { |v| v.to_s.match?(::URI::DEFAULT_PARSER.make_regexp) }
+      if invalid.any?
+        raise ::StandardError, "Invalid value(s) for location (based_near): #{invalid.join(', ')}. " \
+                               "Values must be valid URIs (e.g. http://sws.geonames.org/5128581/)."
+      end
+
+      attrs[:based_near_attributes] = values.each_with_index.to_h do |uri, i|
+        [i.to_s, { "id" => uri.to_s, "_destroy" => "false" }]
+      end
       attrs
     end
   end

data/app/jobs/bulkrax/export_work_job.rb

@@ -18,12 +18,10 @@ module Bulkrax
       else
         if entry.failed?
           ExporterRun.increment_counter(:failed_records, args[1])
-          ExporterRun.decrement_counter(:enqueued_records, args[1]) unless exporter_run.reload.enqueued_records <= 0
-          raise entry.reload.current_status.error_class.constantize
         else
           ExporterRun.increment_counter(:processed_records, args[1])
-          ExporterRun.decrement_counter(:enqueued_records, args[1]) unless exporter_run.reload.enqueued_records <= 0
         end
+        ExporterRun.decrement_counter(:enqueued_records, args[1]) unless exporter_run.reload.enqueued_records <= 0
         # rubocop:enable Rails/SkipsModelValidations
       end
       return entry if exporter_run.reload.enqueued_records.positive?

data/app/jobs/bulkrax/importer_job.rb

@@ -27,10 +27,17 @@ module Bulkrax
     end
 
     def unzip_imported_file(parser)
-      return unless parser.file? && parser.zip?
-
-      parser.unzip(parser.parser_fields['import_file_path'])
-      parser.remove_spaces_from_filenames
+      return unless parser.file?
+      if parser.zip?
+        # we have a zip file, and we need to unzip it before we can import the files
+        parser.unzip(parser.parser_fields['import_file_path'])
+        parser.remove_spaces_from_filenames
+      elsif parser.zip_file?(parser.parser_fields['attachments_zip_path'])
+        # we have a separate csv and zip file. We need to unzip the zip file, and move the csv file to the unzip location before we can import the files
+        parser.unzip(parser.parser_fields['attachments_zip_path'])
+        parser.copy_file(parser.parser_fields['import_file_path'])
+        parser.remove_spaces_from_filenames
+      end
     end
 
     def update_current_run_counters(importer)

data/app/models/bulkrax/csv_entry.rb

@@ -45,7 +45,12 @@ module Bulkrax
         encoding: 'utf-8'
       }.merge(csv_read_data_options)
 
-      results = CSV.read(path, **options)
+      results = if path.respond_to?(:read)
+                  path.rewind if path.respond_to?(:rewind)
+                  CSV.parse(path.read, **options)
+                else
+                  CSV.read(path, **options)
+                end
       csv_wrapper_class.new(results)
     end
 
@@ -83,9 +88,10 @@ module Bulkrax
       # model has to be separated so that it doesn't get mistranslated by to_h
       raw_data = data.to_h
       raw_data[:model] = data[:model] if data[:model].present?
-      # If the collection field mapping is not 'collection', add 'collection' - the parser needs it
-      # TODO: change to :parents
-      raw_data[:parents] = raw_data[parent_field(parser).to_sym] if raw_data.keys.include?(parent_field(parser).to_sym) && parent_field(parser) != 'parents'
+      # If the parents/children field mapping uses a custom column name, alias it to the standard key
+      # so downstream code can find it regardless of what the CSV column is named.
+      raw_data[:parents] = raw_data[parser.related_parents_raw_mapping.to_sym] if parser.related_parents_raw_mapping.present? && raw_data.key?(parser.related_parents_raw_mapping.to_sym) && parser.related_parents_raw_mapping != 'parents'
+      raw_data[:children] = raw_data[parser.related_children_raw_mapping.to_sym] if parser.related_children_raw_mapping.present? && raw_data.key?(parser.related_children_raw_mapping.to_sym) && parser.related_children_raw_mapping != 'children'
       return raw_data
     end
 
@@ -416,18 +422,32 @@ module Bulkrax
       self.collection_ids
     end
 
-    # If only filename is given, construct the path (/files/my_file)
+    # If only filename is given, construct the path (/files/my_file).
+    # If file contains a path separator (e.g. attachments/cat_scan.jpg), resolve relative to the CSV's directory.
     def path_to_file(file)
-      # return if we already have the full file path
       return file if File.exist?(file)
+
+      # Relative path: resolve from CSV's directory (allows arbitrary subdirectory names, not just "files")
+      return resolve_relative_file_path(file) if file.include?('/')
+
+      # Bare filename: use legacy files/ directory for backward compatibility and round-tripping
       path = importerexporter.parser.path_to_files
+      raise "Could not determine path to files directory. Ensure the import package contains a zip or a valid import_file_path." if path.nil?
+
       f = File.join(path, file)
       return f if File.exist?(f)
-      raise "File #{f} does not exist"
+      raise "File not found: #{f}. Check the file column in your CSV and ensure the file exists in the import package or path_to_files directory."
     end
 
     private
 
+    def resolve_relative_file_path(file)
+      base = File.dirname(importerexporter.parser.import_file_path)
+      candidate = File.join(base, file)
+      return candidate if File.exist?(candidate)
+      raise "File not found: #{candidate}. Check the file path in your CSV and ensure the file exists in the import package or directory."
+    end
+
     def map_file_sets(file_sets)
       # rubocop:disable Rails/Presence
       file_sets.map { |fs| filename(fs).to_s if filename(fs).present? }.compact

data/app/models/bulkrax/entry.rb

@@ -93,6 +93,10 @@ module Bulkrax
       parser.related_parents_parsed_mapping
     end
 
+    def self.child_field(parser)
+      parser.related_children_parsed_mapping
+    end
+
     def build
       return if type.nil?
       self.save if self.new_record? # must be saved for statuses

data/app/models/bulkrax/importer.rb

@@ -169,6 +169,30 @@ module Bulkrax
       import_file_path if original_file?
     end
 
+    # Returns all available original files (CSV and ZIP if present)
+    # @return [Array<Hash>] Array of hashes with :path and :name keys
+    def original_files
+      files = []
+
+      if import_file_path && File.exist?(import_file_path)
+        files << {
+          path: import_file_path,
+          name: File.basename(import_file_path),
+          type: :csv
+        }
+      end
+
+      if parser_fields['attachments_zip_path'] && File.exist?(parser_fields['attachments_zip_path'])
+        files << {
+          path: parser_fields['attachments_zip_path'],
+          name: File.basename(parser_fields['attachments_zip_path']),
+          type: :zip
+        }
+      end
+
+      files
+    end
+
     def replace_files
       self.parser_fields['replace_files']
     end
@@ -241,8 +265,14 @@ module Bulkrax
     #   [['Single Metadata File for all works', 'single'], ['Multiple Files, one per Work', 'multi']]
     # end
 
-    # If the import data is zipped, unzip it to this path
     def importer_unzip_path(mkdir: false)
+      entry = parser_fields&.[]('import_file_path')
+      if entry.is_a?(String) && entry.end_with?('.zip') && File.file?(entry) && parser_fields["file_style"] != I18n.t('bulkrax.importer.xml.file_style.server_path')
+        unzip_dir = File.dirname(entry)
+        FileUtils.mkdir_p(unzip_dir) if mkdir
+        return unzip_dir
+      end
+
       @importer_unzip_path ||= File.join(parser.base_path, "import_#{path_string}")
       return @importer_unzip_path if Dir.exist?(@importer_unzip_path) || mkdir == true
 

data/app/models/concerns/bulkrax/has_matchers.rb

@@ -131,7 +131,7 @@ module Bulkrax
       return false if excluded?(field)
       return true if supported_bulkrax_fields.include?(field)
 
-      Bulkrax.object_factory.field_supported?(field: field, model: factory_class)
+      Bulkrax.object_factory.field_supported?(field: field, model: factory_class, admin_set_id: importerexporter.try(:admin_set_id))
     end
 
     def supported_bulkrax_fields
@@ -145,7 +145,7 @@ module Bulkrax
       return true if fields_that_are_always_singular.include?(field.to_s)
       return false if fields_that_are_always_multiple.include?(field.to_s)
 
-      Bulkrax.object_factory.field_multi_value?(field: field, model: factory_class)
+      Bulkrax.object_factory.field_multi_value?(field: field, model: factory_class, admin_set_id: importerexporter.try(:admin_set_id))
     end
 
     def fields_that_are_always_multiple

data/app/models/concerns/bulkrax/importer_exporter_behavior.rb

@@ -51,15 +51,16 @@ module Bulkrax
     # Is this a zip file?
     def zip?
       filename = parser_fields&.[]('import_file_path')
-      return false unless filename
-      return false unless File.file?(filename)
+      return false unless filename && File.file?(filename)
+      zip_file?(filename)
+    end
 
-      returning_value = false
+    def zip_file?(filename)
+      return false unless filename && File.file?(filename)
       File.open(filename) do |file|
         mime_type = ::Marcel::MimeType.for(name: file)
-        returning_value = mime_type.include?('application/zip') || mime_type.include?('application/gzip')
+        mime_type.include?('application/zip') || mime_type.include?('application/gzip')
       end
-      returning_value
     end
   end
 end

data/app/parsers/bulkrax/application_parser.rb

@@ -12,7 +12,7 @@ module Bulkrax
              :seen, :increment_counters, :parser_fields, :user, :keys_without_numbers,
              :key_without_numbers, :status, :set_status_info, :status_info, :status_at,
              :exporter_export_path, :exporter_export_zip_path, :importer_unzip_path, :validate_only,
-             :zip?, :file?, :remove_and_rerun,
+             :zip?, :file?, :remove_and_rerun, :zip_file?,
              to: :importerexporter
 
     # @todo Convert to `class_attribute :parser_fiels, default: {}`
@@ -434,14 +434,40 @@ module Bulkrax
       return untar(file_to_unzip) if file_to_unzip.end_with?('.tar.gz')
 
       Zip::File.open(file_to_unzip) do |zip_file|
+        real_entries = zip_file.reject { |e| macos_junk_entry?(e.name) }
+        top_level_dirs = real_entries.map { |e| e.name.split('/').first }.uniq
+        strip_prefix = top_level_dirs.size == 1 ? "#{top_level_dirs.first}/" : nil
+
+        dest_dir = importer_unzip_path(mkdir: true)
         zip_file.each do |entry|
-          entry_path = File.join(importer_unzip_path(mkdir: true), entry.name)
-          FileUtils.mkdir_p(File.dirname(entry_path))
-          zip_file.extract(entry, entry_path) unless File.exist?(entry_path)
+          next unless entry.file?
+          next if macos_junk_entry?(entry.name)
+          name = strip_prefix ? entry.name.delete_prefix(strip_prefix) : entry.name
+          next if name.empty?
+          dest_path = File.join(dest_dir, name)
+          FileUtils.mkdir_p(File.dirname(dest_path))
+          unless File.exist?(dest_path)
+            # rubyzip 2.x: extract(entry, absolute_dest_path)
+            # rubyzip 3.x: extract(entry, relative_name, destination_directory: dir)
+            if zip_file.method(:extract).arity == 2
+              zip_file.extract(entry, dest_path)
+            else
+              zip_file.extract(entry, name, destination_directory: dest_dir)
+            end
+          end
         end
       end
     end
 
+    def macos_junk_entry?(name)
+      name.start_with?('__MACOSX/') || name.split('/').any? { |part| part == '.DS_Store' || part.start_with?('._') }
+    end
+
+    def copy_file(file_to_copy)
+      destination = File.join(importer_unzip_path(mkdir: true), File.basename(file_to_copy))
+      FileUtils.cp(file_to_copy, destination)
+    end
+
     def untar(file_to_untar)
       Dir.mkdir(importer_unzip_path(mkdir: true)) unless File.directory?(importer_unzip_path(mkdir: true))
       command = "tar -xzf #{Shellwords.escape(file_to_untar)} -C #{Shellwords.escape(importer_unzip_path)}"
@@ -452,7 +478,7 @@ module Bulkrax
     # File names referenced in CSVs have spaces replaced with underscores
     # @see Bulkrax::CsvParser#file_paths
     def remove_spaces_from_filenames
-      files = Dir.glob(File.join(importer_unzip_path, 'files', '*'))
+      files = Dir.glob(File.join(importer_unzip_path, 'files', '*')).uniq
       files_with_spaces = files.select { |f| f.split('/').last.match?(' ') }
       return if files_with_spaces.blank?