ixport 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81097e7e2778b75a3e0a8e036151b7cc6627c50bd929f86129a78c429083cb38
+  data.tar.gz: 5d16aede3fdae08b99f79afe2db7933b5b171ee92efa6c4998224269a5742191
+SHA512:
+  metadata.gz: d874135a600df60b6c2c98a56d41160d171a132eada93fad35de5494792afc256fc63132a905e57577653025b0b2b69404548d9fd6024613e55057a6f752126d
+  data.tar.gz: a690f23002ff143c8bc1a2906b213df52f358e6e40d6405e3a7686906de653d1d8af5d90441ff3d11b2b62c79337a367acdaba46a8ec487abeeebdf4d702b419

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Tyler Schneider
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,89 @@
+# ixport
+
+CSV import and export for Rails apps. An app registers the kinds of CSV a person can import and the fields each one maps to.
+
+## Installation
+
+Add the gem and run its install generator, which copies the migrations for its imports table and the table of rows an import refused:
+
+```ruby
+gem "ixport"
+```
+
+```bash
+bundle install
+bin/rails generate ixport:install
+bin/rails db:migrate
+```
+
+Mount the engine at the path its pages should live under:
+
+```ruby
+mount Ixport::Engine => "/data_imports"
+```
+
+## Configuration
+
+Every setting has a default that matches a Jumpstart app, so set only what differs in your app:
+
+```ruby
+Ixport.configure do |config|
+  config.authentication_method = :authenticate_user! # runs before every ixport page
+  config.current_person_method = :current_user       # returns the person who starts and views imports
+  config.current_account_method = :current_account   # returns the account an import belongs to
+  config.layout = "application"                      # the layout ixport's pages are drawn in
+  config.inline_row_limit = 1_000                    # the most rows an import may have when it runs inside the request
+end
+```
+
+## Mapped imports and importers
+
+A mapped import is a kind of CSV a person can import into one of the app's records. Register each one in an initializer with its key, its title and the name of its importer class:
+
+```ruby
+Ixport.register_import :products, title: "Products", importer: "ProductImporter"
+```
+
+An app whose registered importer class does not exist fails to boot, with a message naming the class.
+
+The engine's root page lists every registered import by its title, each linking to its upload page.
+
+An importer lists the fields a person maps the file's columns to, each with the label the person sees. It names the one field rows are matched on, and the records a row may match, which it reaches through the `person` and `account` the import is for:
+
+```ruby
+class ProductImporter < Ixport::Importer
+  field :sku, label: "SKU"
+  field :price_cents, label: "Price"
+  match_on :sku
+
+  def records
+    account.products
+  end
+end
+```
+
+Each field's key is the record's attribute name. ixport looks up every match value in the file with one query against `records`. A row whose match value matches one of those records updates it, and a row that matches nothing adds a new record built from `records`. A row whose match value is blank, or whose file has no column mapped to the match field, always adds a record.
+
+## Uploading and mapping a file
+
+From the engine's root page, a person picks a registered import and uploads a CSV for it. The upload is refused, with a message on the upload page, when the file has no header row or has more rows than `config.inline_row_limit`.
+
+After uploading, the person matches each column of the file's header row to one of the importer's fields, by its label, or skips it. Saving the mapping moves them on to the preview.
+
+The preview shows how many rows will add a record, update one or be refused, before anything is saved. It lists each row that will update a record and each refused row, by its row number in the file, with the reason the record gives for a refusal. A row is refused when the record it builds is not valid. Viewing the preview saves nothing, and the person can go back from it to change the mapping.
+
+## Running an import
+
+The person runs the import from the preview, and it runs inside the request. Each row that passes the record's validations is saved, updating the record it matches or adding a new one. Each row that fails them is refused and kept with its row number and reason, and the record it matched is left unchanged.
+
+The import's result page then shows how many rows were added and how many updated, and lists each refused row. It shows the same thing on every later visit. A finished import offers no Run button, its preview leads to its result page, and running it again adds or changes nothing.
+
+An import belongs to the person and account that uploaded it, and anyone else gets not found when they open it.
+
+## Claude Code agents
+
+ixport ships its own Claude Code agents through [the_local](https://github.com/DYB-Development/the_local). An app that lists ixport in its Gemfile and runs `bundle exec the_local install` gets them in `.claude/agents/`.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test
+
+require "the_local/rake"

data/app/controllers/ixport/application_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Ixport
+  class ApplicationController < ::ApplicationController
+    before_action { send(Ixport.configuration.authentication_method) }
+    layout -> { Ixport.configuration.layout }
+
+    private
+
+    def find_import
+      @import = Import.find_by(id: params[:import_id] || params[:id], person: ixport_person, account: ixport_account)
+      head :not_found unless @import
+    end
+
+    def ixport_person
+      send(Ixport.configuration.current_person_method)
+    end
+
+    def ixport_account
+      send(Ixport.configuration.current_account_method)
+    end
+  end
+end

data/app/controllers/ixport/imports_controller.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ixport
+  class ImportsController < ApplicationController
+    before_action :find_registration, only: %i[new create]
+    before_action :find_import, only: :show
+
+    def index
+      @registrations = Ixport.registrations.values
+    end
+
+    def new
+    end
+
+    def show
+      redirect_to import_preview_path(@import) unless @import.finished?
+    end
+
+    def create
+      import = Import.new(key: @registration.key, person: ixport_person, account: ixport_account, file: params[:file])
+      if import.save
+        redirect_to import_mapping_path(import)
+      else
+        @error = import.errors[:file].first
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def find_registration
+      @registration = Ixport.registrations[params[:key].to_s.to_sym]
+      head :not_found unless @registration
+    end
+  end
+end

data/app/controllers/ixport/mappings_controller.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Ixport
+  class MappingsController < ApplicationController
+    before_action :find_import
+
+    def show
+      @fields = @import.importer_class.fields
+    end
+
+    def update
+      @import.update!(mapping: params.require(:mapping).permit(*@import.headers.each_index.map(&:to_s)).to_h.compact_blank)
+      redirect_to import_preview_path(@import)
+    end
+  end
+end

data/app/controllers/ixport/previews_controller.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Ixport
+  class PreviewsController < ApplicationController
+    before_action :find_import
+
+    def show
+      return redirect_to import_path(@import) if @import.finished?
+
+      rows = RowWalk.new(@import, @import.importer_class.new(person: ixport_person, account: ixport_account)).rows
+      @counts = { add: 0, update: 0, refused: 0 }.merge(rows.group_by(&:outcome).transform_values(&:size))
+      @update_rows = rows.select { |row| row.outcome == :update }
+      @refused_rows = rows.select { |row| row.outcome == :refused }
+    end
+  end
+end

data/app/controllers/ixport/runs_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Ixport
+  class RunsController < ApplicationController
+    before_action :find_import
+
+    def create
+      @import.run!(@import.importer_class.new(person: ixport_person, account: ixport_account))
+      redirect_to import_path(@import)
+    end
+  end
+end

data/app/models/ixport/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ixport
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/ixport/import.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Ixport
+  class Import < ApplicationRecord
+    self.table_name = "ixport_imports"
+
+    belongs_to :person, polymorphic: true
+    belongs_to :account, polymorphic: true, optional: true
+
+    has_one_attached :file
+    has_many :refusals, -> { order(:row_number) }, class_name: "Ixport::ImportRefusal", dependent: :destroy
+
+    validate :file_has_header_row, on: :create
+    validate :file_within_inline_row_limit, on: :create
+
+    def run!(importer)
+      with_lock do
+        walk_and_save(importer) unless finished?
+      end
+    end
+
+    def finished?
+      status == "finished"
+    end
+
+    def importer_class
+      Ixport.registration(key).importer.constantize
+    end
+
+    def headers
+      CSV.parse_line(file.download) || []
+    end
+
+    private
+
+    def walk_and_save(importer)
+      rows = RowWalk.new(self, importer).rows
+      rows.each do |row|
+        if row.outcome == :refused
+          refusals.create!(row_number: row.number, reason: row.reason)
+        else
+          row.record.save!
+        end
+      end
+      update!(status: "finished", added_count: rows.count { |row| row.outcome == :add }, updated_count: rows.count { |row| row.outcome == :update })
+    end
+
+    def file_has_header_row
+      errors.add(:file, "This file has no header row.") if CSV.parse_line(incoming_file_contents).blank?
+    end
+
+    def file_within_inline_row_limit
+      limit = Ixport.configuration.inline_row_limit
+      rows = [ CSV.parse(incoming_file_contents).size - 1, 0 ].max
+      errors.add(:file, "This file has #{rows} rows, and the most an import can have is #{limit}.") if rows > limit
+    end
+
+    def incoming_file_contents
+      attachable = attachment_changes["file"]&.attachable
+      io = attachable.is_a?(Hash) ? attachable[:io] : attachable
+      return "" unless io
+
+      io.read.tap { io.rewind }.to_s
+    end
+  end
+end

data/app/models/ixport/import_refusal.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ixport
+  class ImportRefusal < ApplicationRecord
+    self.table_name = "ixport_import_refusals"
+
+    belongs_to :import
+  end
+end

data/app/models/ixport/row_walk.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Ixport
+  class RowWalk
+    Row = Struct.new(:number, :record, :outcome, :reason, keyword_init: true)
+
+    def initialize(import, importer)
+      @import = import
+      @importer = importer
+    end
+
+    def rows
+      @rows ||= data_rows.each_with_index.map { |cells, index| row_for(cells, index + 2) }
+    end
+
+    private
+
+    def row_for(cells, number)
+      values = values_of(cells)
+      existing = existing_records[values[match_field]]
+      record = existing ? existing.tap { |found| found.assign_attributes(values) } : @importer.records.new(values)
+      return Row.new(number: number, record: record, outcome: :refused, reason: record.errors.full_messages.to_sentence) unless record.valid?
+
+      Row.new(number: number, record: record, outcome: existing ? :update : :add)
+    end
+
+    def data_rows
+      @data_rows ||= CSV.parse(@import.file.download).drop(1)
+    end
+
+    def values_of(cells)
+      @import.mapping.to_h { |column, field| [ field.to_sym, cells[column.to_i] ] }
+    end
+
+    def match_field
+      @importer.class.match_field
+    end
+
+    def existing_records
+      @existing_records ||= begin
+        match_values = data_rows.map { |cells| values_of(cells)[match_field] }.compact_blank
+        @importer.records.where(match_field => match_values).index_by { |record| record.public_send(match_field).to_s }
+      end
+    end
+  end
+end

data/app/views/ixport/imports/index.html.erb

@@ -0,0 +1,10 @@
+<%= ui_page(max_width: :md) do %>
+  <h1>Imports</h1>
+  <% if @registrations.empty? %>
+    <%= ui_alert(message: "No imports are set up yet.") %>
+  <% else %>
+    <% @registrations.each do |registration| %>
+      <div data-import><%= link_to registration.title, new_import_path(key: registration.key) %></div>
+    <% end %>
+  <% end %>
+<% end %>

data/app/views/ixport/imports/new.html.erb

@@ -0,0 +1,11 @@
+<%= ui_form_page(title: @registration.title, back_url: root_path) %>
+<%= ui_page(max_width: :md) do %>
+  <% if @error.present? %>
+    <%= ui_alert(type: :error, message: tag.span(@error, data: { upload_error: true })) %>
+  <% end %>
+  <%= ui_form(action: imports_path, multipart: true) do %>
+    <%= hidden_field_tag "key", @registration.key %>
+    <%= ui_file_upload(name: "file", label: "CSV file", accept: ".csv") %>
+    <%= ui_button(label: "Upload") %>
+  <% end %>
+<% end %>

data/app/views/ixport/imports/show.html.erb

@@ -0,0 +1,20 @@
+<%= ui_show_page(title: "Import finished", back_url: root_path) %>
+<%= ui_page(max_width: :md) do %>
+  <%= ui_page_header(title: "Import finished") %>
+  <%= ui_grid(cols: { default: 1, sm: 2 }) do %>
+    <%= ui_stat_card(label: "Added", value: tag.span(@import.added_count, data: { result_count: "added" })) %>
+    <%= ui_stat_card(label: "Updated", value: tag.span(@import.updated_count, data: { result_count: "updated" })) %>
+  <% end %>
+  <% if @import.refusals.any? %>
+    <%= ui_section(title: "Refused") do %>
+      <ul>
+        <% @import.refusals.each do |refusal| %>
+          <%= tag.li(data: { refused_row: true }) do %>
+            Row <%= tag.span(refusal.row_number, data: { row_number: true }) %>
+            <%= tag.span(refusal.reason, data: { reason: true }) %>
+          <% end %>
+        <% end %>
+      </ul>
+    <% end %>
+  <% end %>
+<% end %>

data/app/views/ixport/mappings/show.html.erb

@@ -0,0 +1,12 @@
+<%= ui_form_page(title: "Match columns", back_url: root_path) %>
+<%= ui_page(max_width: :md) do %>
+  <%= ui_form(action: import_mapping_path(@import), method: :patch) do %>
+    <% @import.headers.each_with_index do |header, index| %>
+      <%= tag.div(data: { column: true }) do %>
+        <%= tag.span(header, data: { column_name: true }) %>
+        <%= ui_select(name: "mapping[#{index}]", options: @fields.map { |field| [field.label, field.key] }, include_blank: "Skip") %>
+      <% end %>
+    <% end %>
+    <%= ui_button(label: "Save mapping") %>
+  <% end %>
+<% end %>

data/app/views/ixport/previews/show.html.erb

@@ -0,0 +1,35 @@
+<%= ui_show_page(title: "Preview", back_url: import_mapping_path(@import)) %>
+<%= ui_page(max_width: :md) do %>
+  <%= ui_page_header(title: "Preview") %>
+  <%= ui_grid(cols: { default: 1, sm: 3 }) do %>
+    <%= ui_stat_card(label: "Will add", value: tag.span(@counts[:add], data: { count: "add" })) %>
+    <%= ui_stat_card(label: "Will update", value: tag.span(@counts[:update], data: { count: "update" })) %>
+    <%= ui_stat_card(label: "Will be refused", value: tag.span(@counts[:refused], data: { count: "refused" })) %>
+  <% end %>
+  <% if @update_rows.any? %>
+    <%= ui_section(title: "Will update") do %>
+      <ul>
+        <% @update_rows.each do |row| %>
+          <%= tag.li(data: { update_row: true }) do %>
+            Row <%= tag.span(row.number, data: { row_number: true }) %>
+          <% end %>
+        <% end %>
+      </ul>
+    <% end %>
+  <% end %>
+  <% if @refused_rows.any? %>
+    <%= ui_section(title: "Will be refused") do %>
+      <ul>
+        <% @refused_rows.each do |row| %>
+          <%= tag.li(data: { refused_row: true }) do %>
+            Row <%= tag.span(row.number, data: { row_number: true }) %>
+            <%= tag.span(row.reason, data: { reason: true }) %>
+          <% end %>
+        <% end %>
+      </ul>
+    <% end %>
+  <% end %>
+  <%= ui_form(action: import_run_path(@import)) do %>
+    <%= ui_button(label: "Run import") %>
+  <% end %>
+<% end %>

data/config/routes.rb

@@ -0,0 +1,8 @@
+Ixport::Engine.routes.draw do
+  root "imports#index"
+  resources :imports, only: %i[new create show] do
+    resource :mapping, only: %i[show update]
+    resource :preview, only: :show
+    resource :run, only: :create
+  end
+end

data/lib/generators/ixport/install/install_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Ixport
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs Ixport: copies the migrations for its tables."
+
+      def copy_migrations
+        migration_template "create_ixport_imports.rb.erb", "db/migrate/create_ixport_imports.rb"
+        migration_template "create_ixport_import_refusals.rb.erb", "db/migrate/create_ixport_import_refusals.rb"
+      end
+    end
+  end
+end

data/lib/generators/ixport/install/templates/create_ixport_import_refusals.rb.erb

@@ -0,0 +1,10 @@
+class CreateIxportImportRefusals < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :ixport_import_refusals do |t|
+      t.references :import, null: false, foreign_key: { to_table: :ixport_imports }
+      t.integer :row_number, null: false
+      t.text :reason, null: false
+      t.timestamps
+    end
+  end
+end

data/lib/generators/ixport/install/templates/create_ixport_imports.rb.erb

@@ -0,0 +1,14 @@
+class CreateIxportImports < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :ixport_imports do |t|
+      t.string :key, null: false
+      t.references :person, polymorphic: true, null: false
+      t.references :account, polymorphic: true, null: true
+      t.json :mapping
+      t.string :status, null: false, default: "pending"
+      t.integer :added_count, null: false, default: 0
+      t.integer :updated_count, null: false, default: 0
+      t.timestamps
+    end
+  end
+end

data/lib/ixport/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Ixport
+  class Configuration
+    attr_accessor :authentication_method, :current_person_method, :current_account_method, :layout, :inline_row_limit
+
+    def initialize
+      @authentication_method = :authenticate_user!
+      @current_person_method = :current_user
+      @current_account_method = :current_account
+      @layout = "application"
+      @inline_row_limit = 1_000
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+end

data/lib/ixport/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ixport
+  class Engine < ::Rails::Engine
+    isolate_namespace Ixport
+
+    config.after_initialize { Ixport.check_registrations! }
+  end
+end

data/lib/ixport/importer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ixport
+  class Importer
+    Field = Struct.new(:key, :label, keyword_init: true)
+
+    attr_reader :person, :account
+
+    def initialize(person:, account:)
+      @person = person
+      @account = account
+    end
+
+    def self.field(key, label:)
+      fields << Field.new(key: key.to_sym, label: label)
+    end
+
+    def self.fields
+      @fields ||= []
+    end
+
+    def self.match_on(key)
+      @match_field = key.to_sym
+    end
+
+    def self.match_field
+      @match_field
+    end
+  end
+end

data/lib/ixport/registrations.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Ixport
+  Registration = Struct.new(:key, :title, :importer, keyword_init: true)
+
+  class MissingImporter < StandardError; end
+
+  def self.register_import(key, title:, importer:)
+    registrations[key.to_sym] = Registration.new(key: key.to_sym, title: title, importer: importer.to_s)
+  end
+
+  def self.registration(key)
+    registrations.fetch(key.to_sym)
+  end
+
+  def self.registrations
+    @registrations ||= {}
+  end
+
+  def self.check_registrations!
+    registrations.each_value do |registration|
+      next if registration.importer.safe_constantize
+
+      raise MissingImporter, "Ixport import #{registration.key} names the importer #{registration.importer}, which does not exist."
+    end
+  end
+
+  def self.reset_registrations!
+    @registrations = {}
+  end
+end

data/lib/ixport/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ixport
+  VERSION = "0.1.0"
+end

data/lib/ixport.rb

@@ -0,0 +1,9 @@
+require "keystone_ui"
+require "ixport/version"
+require "ixport/configuration"
+require "ixport/registrations"
+require "ixport/importer"
+require "ixport/engine"
+
+module Ixport
+end

data/the_local/agents/ixport-develop.md

@@ -0,0 +1,104 @@
+---
+name: ixport-develop
+description: Use PROACTIVELY for setting up CSV imports in a Rails app that has ixport — registering a mapped import, writing its importer class, declaring the fields a person maps a CSV's columns to, choosing the field rows are matched on, scoping the records an import may add or update to the signed-in person or account, linking to an import's upload page, explaining the upload, column-matching, preview and result pages and their messages, explaining what running an import saves and refuses, and fixing a boot that fails with Ixport::MissingImporter — MUST BE USED instead of hand-writing a CSV upload controller, a column-mapping form, a row-matching loop, an import preview or a loop that saves imported rows.
+tools: Bash, Read, Write, Edit, Grep
+scope: CSV import and export — a mounted engine where a signed-in person sees the mapped imports the host app registers, each backed by an importer class the host writes
+---
+
+This local adds mapped imports to a Rails app that already has ixport installed by following the steps below exactly. It writes one importer class and one registration line per import, and it invents no method, option, route or file that is not listed here.
+
+## What ixport is
+
+ixport is a Rails engine that lets a signed-in person import a host app's records from CSV files. The app registers each kind of CSV a person can import, called a mapped import, and writes an importer class that names the fields the CSV's columns map to, the one field rows are matched on, and the records a row may add to or update. A person picks an import, uploads a CSV file for it, matches each of the file's columns to one of the importer's fields, sees a preview of how many rows will add a record, update one or be refused, runs the import to save those rows, and then sees how many rows were added and updated and each refused row. Fire this local when a developer wants people to load one of the app's records from a spreadsheet, wants to link to an import's upload page, asks what the upload, column-matching, preview or result pages do, asks what running an import saves, or when the app fails to boot with `Ixport::MissingImporter`.
+
+## Interface
+
+- `Ixport.register_import` — `Ixport.register_import(key, title:, importer:)` registers one mapped import under a key, with the title a person sees and the name of its importer class.
+- `Ixport::Importer` — the base class every importer inherits from.
+- `field` — `field key, label:` is called in an importer's class body and declares one field a CSV column can be mapped to, with the label a person sees.
+- `match_on` — `match_on key` is called in an importer's class body and names the one declared field a row is matched to an existing record on.
+- `records` — an instance method every importer defines, returning the Active Record relation a row may update a record from and adds a new record to.
+- `person` — returns the person the import belongs to, the one who uploaded the file, for use inside `records`.
+- `account` — returns the account the import belongs to, the one current when the file was uploaded, for use inside `records`, and is `nil` when the app has no current account.
+- `Ixport::MissingImporter` — the error raised when the app boots if a registered import names an importer class that does not exist.
+- `GET /` — the engine's root page, at the path the engine is mounted under, which lists every registered import by its title, each linking to that import's upload page.
+- `GET /imports/new` — the upload page for one import, given the import's registered key as the `key` query parameter, which shows the import's title, a CSV file field and an Upload button.
+- `POST /imports` — takes the `key` and `file` parameters, stores the uploaded file as an import belonging to the signed-in person and the current account, and redirects to that import's column-matching page.
+- `GET /imports/:import_id/mapping` — the column-matching page, titled "Match columns", which lists each column header from the file's first row beside a select of the importer's field labels and a "Skip" choice.
+- `PATCH /imports/:import_id/mapping` — saves which field each column maps to and redirects to the import's preview page.
+- `GET /imports/:import_id/preview` — the preview page, titled "Preview", which shows how many rows will add a record, update one or be refused, lists each updating row and each refused row by its row number, saves nothing, and offers a "Run import" button, and which redirects to the import's result page once the import has run.
+- `POST /imports/:import_id/run` — saves every row that adds or updates a record, records every refused row with its reason, marks the import finished, and redirects to the import's result page, and does nothing but redirect when the import has already run.
+- `GET /imports/:id` — the result page, titled "Import finished", which shows how many rows the run added and updated and lists each refused row by its row number with its reason, and which redirects to the import's preview page when the import has not run.
+
+## How to use it
+
+1. Check that ixport is installed: `bin/rails routes` lists a path served by ixport. If it does not, stop and hand the setup to the `ixport-install` local before going on.
+2. Ask the developer which of the app's records the import loads, such as products or customers. Do not pick one.
+3. Ask the developer which attributes of that record a person may import, and the label a person should see for each, such as "SKU" for `sku` or "Price" for `price_cents`. Do not decide which attributes are importable.
+4. Ask the developer which of those fields identifies an existing record, such as the SKU or the email. Do not pick the match field.
+5. Ask the developer which records a person may add to or update, such as the current account's products or the signed-in person's contacts. Do not pick the scope. An import that reaches every row of the table lets one account's file update another account's records.
+6. Write the importer class in `app/importers/`, named after the record, inheriting from `Ixport::Importer`:
+   ```ruby
+   class ProductImporter < Ixport::Importer
+     field :sku, label: "SKU"
+     field :price_cents, label: "Price"
+     match_on :sku
+
+     def records
+       account.products
+     end
+   end
+   ```
+   - Call `field` once per attribute from step 3, in the order a person should see them. The key is the record's attribute name as a symbol, and `label:` is required.
+   - Each field key must be an attribute the record can be assigned, because a row's mapped values are assigned to the record by those keys.
+   - The labels are the choices on the column-matching page, in the order the fields are declared.
+   - Call `match_on` once, with the key of a field declared with `field`, from step 4.
+   - Define `records` to return a relation of the record from step 5, built from `person` or `account`. A new record is built from this relation, so a record added through `account.products` already belongs to that account.
+   - `account` is `nil` when the app has no current account, so a `records` that calls a method on `account` fails in that case. Ask the developer whether that can happen in this app.
+   - Never define `initialize` in an importer. ixport builds the importer with the import's person and account.
+7. Ask the developer what key and title the import gets. The key is a short symbol that identifies the import, such as `:products`. The title is what a person sees on the imports page and as the heading of the upload page, such as "Products".
+8. Add the registration to the end of `config/initializers/ixport.rb`, and create the file if it does not exist:
+   ```ruby
+   Ixport.register_import :products, title: "Products", importer: "ProductImporter"
+   ```
+   Pass `importer:` the class name as a string, never the class itself, so the initializer does not load the class before the app's code is ready.
+9. Start the app. If it fails to boot with `Ixport::MissingImporter`, the message names the import key and the class name that does not exist. Fix the class name in the registration, or the class name or file name of the importer, so the two match.
+10. Visit the path the engine is mounted under while signed in. The page shows the heading "Imports" and lists each registered import by its title, in the order the imports were registered. With no import registered it shows "No imports are set up yet."
+11. When the developer wants a link to one import's upload page from the app's own pages, ask where the link goes. Build its URL with the engine's route helper and the import's registered key:
+    ```erb
+    <%= link_to "Import products", ixport.new_import_path(key: :products) %>
+    ```
+    The key must be one that is registered. An unregistered key gets a not found response.
+12. On the upload page a person chooses a CSV file and presses Upload. The upload is refused, and the upload page is shown again with status 422 and one of these messages, when:
+    - the file has no header row: "This file has no header row."
+    - the file has more data rows than the inline row limit, not counting the header row: "This file has N rows, and the most an import can have is L." The limit is set by `ixport-install`.
+13. After an upload is accepted, the person is on the "Match columns" page. Each column header from the file's first row is listed with a select of the importer's field labels. "Skip" leaves that column unmapped. Pressing "Save mapping" saves the choices and takes the person to the "Preview" page.
+14. The preview decides each data row's outcome this way:
+    - The row's value for the match field is looked up in `records`, with one query for the whole file.
+    - A row matches a record only when its value is exactly the same text as the record's match attribute written as text.
+    - A row that matches a record will update it with the row's mapped values.
+    - A row that matches nothing, a row whose match value is blank, and every row of a file with no column mapped to the match field will add a new record built from `records`.
+    - A row whose added or updated record is not valid will be refused, with the record's own validation messages as the reason.
+15. The preview page shows three counts, "Will add", "Will update" and "Will be refused". Under them it lists each row that will update a record under "Will update", and each refused row with its reason under "Will be refused", each by its row number in the file, where the header row is row 1. The refusal reasons are the record's validation messages, so tell the developer that the record's validations decide which rows are refused and what a person reads.
+16. Viewing the preview adds and changes no record. Its back link returns the person to the "Match columns" page to change the mapping.
+17. Pressing "Run import" on the preview page runs the import within the same request, with no background job:
+    - Every row's outcome is decided again by the rules in step 14, against the records as they are at that moment, so the result can differ from the preview when records changed in between.
+    - Every row that adds or updates a record is saved with `save!`, so the record's callbacks run as for any other save.
+    - Every refused row is recorded with its row number and reason, and no record is saved for it.
+    - The whole run happens in one database transaction. When any save raises, such as on a database constraint the record's validations do not cover, nothing from the run is saved and the import stays unrun. Tell the developer to cover every database constraint on the record with a validation, so a bad row is refused rather than stopping the whole run.
+    - An import runs once. A second run request for the same import, including one sent at the same time as the first, adds and changes nothing and redirects to the result page.
+18. After the run, the person is on the "Import finished" page. It shows two counts, "Added" and "Updated", and, when any row was refused, lists each refused row under "Refused" by its row number with its reason. Returning to this page later shows the same counts and refused rows. Visiting this page for an import that has not run redirects to its preview page. Once an import has run, its preview page redirects to this page, so it offers no "Run import" button.
+19. An import's column-matching, preview, run and result pages are visible only to the person who uploaded it, in the account it was uploaded in. Anyone else, and the same person in another account, gets a not found response.
+
+## Conventions
+
+- Every registration names an importer class that exists. The app refuses to boot otherwise, so never register an import before its importer class is written.
+- Each key is registered once. Registering the same key a second time replaces the first registration.
+- Every importer declares `match_on` and defines `records`.
+- `records` is always scoped to the `person` or `account` the developer chose, never left to the whole table without the developer saying so.
+- An importer inherits from `Ixport::Importer` directly and declares all of its own fields and its own match field. Neither is inherited by a class that inherits from another importer.
+- When a record's attribute is renamed or removed, update the matching `field` line and any `match_on` that names it in the same change.
+- When an importer class is renamed, update its `importer:` string in `config/initializers/ixport.rb` in the same change.
+- When an import's key is changed, update every link to its upload page in the same change.
+- Never write an upload form, a column-matching form, a preview page, a run action, a result page or a controller for them in the app. The engine serves all of them.
+- Installing ixport, mounting the engine, the tables an import and its refused rows are stored in, file storage, sign-in, how the current person and account are found, and the inline row limit are out of scope for this local and belong to `ixport-install`.

data/the_local/agents/ixport-info.md

@@ -0,0 +1,59 @@
+---
+name: ixport-info
+description: Use to learn what ixport offers — CSV import through a mounted Rails engine, the mapped imports a host app registers, the importer classes behind them, uploading a file, matching its columns, previewing which rows will add, update or be refused, running the import, its result page, and the vocabulary the install and develop locals assume.
+tools: Read
+scope: CSV import and export — a mounted engine where a signed-in person sees the mapped imports the host app registers, each backed by an importer class the host writes
+---
+
+This local explains what ixport is and routes you to the local that does the work. It makes no changes and gives no steps.
+
+## What ixport is
+
+ixport is a Rails engine for loading a host app's records from CSV files. The host app mounts it at a path of its choosing, and a signed-in person who visits that path sees the list of imports the host has set up, each shown by its title.
+
+A person picks an import, uploads a CSV file, matches each column of the file to one of the columns the import reads or skips it, and then sees a preview. The preview counts how many rows will add a record, how many will update one, and how many will be refused, and lists the rows that will update and the rows that will be refused with the reason for each. Viewing the preview saves nothing in the host app, and a Back link returns to the mapping so the person can change it.
+
+From the preview the person runs the import. The run saves every added and updated record in the host app, records each refused row with its reason, and sends the person to the import's result page, which shows how many rows were added and updated and lists each refused row. The run happens inside the request, an import runs once, and asking to run it again changes nothing. Opening the preview of a finished import sends the person to its result page instead, and opening the result page of an import that has not run sends the person to its preview.
+
+ixport refuses a file with no header row, and a file with more rows than the host's row limit, on the upload page. It has no export yet.
+
+The engine owns the screens, the access check, and its own tables of import records and refused rows, with the uploaded file stored through Active Storage. The host owns what each import means: which columns it reads, which column identifies an existing record, and which of the app's records a row is checked against and saved into. Reach for ixport when a Rails app needs people to load data from spreadsheets, rather than writing a one-off upload page per record type.
+
+The engine renders its pages with Keystone UI inside a layout the host chooses, and it runs its access check through a method the host already has.
+
+## Interface
+
+ixport declares nothing for this local to document. Its surface is split between the other two locals:
+
+- **ixport-install** owns hooking ixport into a host app: adding the gem, running its install generator, mounting the engine, and the configuration that names the host's sign-in check, current person, current account, layout and row limit.
+- **ixport-develop** owns building against ixport: registering a mapped import, writing the importer class behind it, the error raised when a registration names an importer that does not exist, and the engine's pages for listing imports, uploading a file, matching its columns, previewing the result, running the import and showing its result.
+
+## How to use it
+
+- The app does not have ixport yet, or you are changing how ixport reaches the app's sign-in, people, accounts, layout or row limit: use **ixport-install**.
+- ixport is already installed and you are adding or changing an import, changing how its rows are matched, checked or saved, linking to the engine's pages, or the app fails to boot naming a missing importer: use **ixport-develop**.
+
+## Conventions
+
+- **Mapped import** — one kind of import the host registers, made of a key, a title shown to people, and the name of its importer class.
+- **Key** — the short name a mapped import is registered and looked up by, held as a symbol.
+- **Title** — the words a person sees for the import on the engine's page.
+- **Importer** — a class the host app writes that declares the columns the import reads, each with a key and a label, names the column that identifies an existing record, and supplies the set of the app's records the rows are checked against and saved into.
+- **Match column** — the one declared column whose value decides whether a row is an existing record or a new one.
+- **Import record** — one upload by one person, stored by the engine with the key of its mapped import, the uploaded file, the mapping once it is saved, and the added and updated counts once it has run.
+- **Headers** — the first row of the uploaded file, read as the names of its columns.
+- **Mapping** — which of the importer's columns each header in the file fills, stored by the header's position in the row. A header left on "Skip" is not stored.
+- **Row limit** — the most data rows an uploaded file may have, not counting the header row. It defaults to 1,000 and the host can change it.
+- **Row number** — a row's line in the file, counting the header as row 1, so the first data row is row 2.
+- **Add** — a row whose match column value is found in no existing record, so it creates one.
+- **Update** — a row whose match column value is found in an existing record, so it changes that record.
+- **Refused** — a row whose record, new or changed, fails the host model's own validations. Its reason is that model's error messages.
+- **Preview** — the page that shows the add, update and refused counts and lists the update and refused rows by row number. It builds each row's record in memory and saves none of them.
+- **Run** — the step that saves the added and updated records and stores each refused row's number and reason. A run that raises an error saves nothing, and an import that has finished is never run a second time.
+- **Finished** — the state of an import record once it has run.
+- **Result page** — the import's own page, showing the added and updated counts and each refused row as they were stored by the run, so it shows the same thing each time it is opened.
+- **Person** — whoever is signed in and running the import. ixport reaches them through a method the host names, so the host's user model needs no particular name.
+- **Account** — the optional owner the person is working inside, such as a team or company, reached the same way. An app with no accounts runs without one.
+- **Ownership** — an import record belongs to the person and account that uploaded it, and anyone else who opens it, including the same person from another account, is answered not found.
+- **Boot check** — when the app starts, ixport checks that every registered importer class exists and refuses to boot when one does not, so a misspelled class name fails at startup rather than when someone runs the import.
+- An import is registered by the host app, never discovered: an importer class that is not registered does not appear on the page.

data/the_local/agents/ixport-install.md

@@ -0,0 +1,82 @@
+---
+name: ixport-install
+description: Use to hook ixport into a project — adding the gem, checking Active Storage is set up, running the install generator and its migrations, mounting the engine, and configuring the sign-in check, the current person method, the current account method, the layout and the inline row limit.
+tools: Bash, Read, Edit
+scope: CSV import and export — a mounted engine where a signed-in person sees the mapped imports the host app registers, each backed by an importer class the host writes
+---
+
+This local hooks ixport into a Rails app by following the steps below exactly. It invents no step, setting or file that is not listed here.
+
+## What ixport is
+
+ixport is a Rails engine that lets a signed-in person upload a CSV file, match its columns to a host app's fields, preview which rows will add, update or be refused, and then run the import to save those records into the host app. Hook it in when a Rails app needs people to load data from spreadsheets.
+
+## Interface
+
+- `gem "ixport"` — the Gemfile line that adds ixport to the app. It also brings in Keystone UI, which draws ixport's pages.
+- `bin/rails generate ixport:install` — copies two migrations into `db/migrate/`, one that creates the `ixport_imports` table and one that creates the `ixport_import_refusals` table.
+- `mount Ixport::Engine` — the line in `config/routes.rb` that serves ixport's pages under a path the app chooses.
+- `Ixport.configure` — takes a block that receives the configuration object, where the app sets any of the five settings below.
+- `config.authentication_method` — the name of the controller method run before every ixport page, as a symbol. It defaults to `:authenticate_user!`.
+- `config.current_person_method` — the name of the controller method that returns the signed-in person running imports, as a symbol. It defaults to `:current_user`.
+- `config.current_account_method` — the name of the controller method that returns the account the person is working in, as a symbol. It defaults to `:current_account`.
+- `config.layout` — the name of the host layout ixport's pages are drawn inside, as a string. It defaults to `"application"`.
+- `config.inline_row_limit` — the most data rows an uploaded file may have, not counting its header row, as an integer. A file with more is refused on the upload page with a message giving the limit and the file's row count. It defaults to `1_000`.
+
+## How to use it
+
+1. Check that the app has Keystone UI set up: the layout ixport will use has `<%= keystone_theme_attributes %>` in its `<html>` tag. If it does not, stop and hand Keystone UI's setup to the `keystone_ui-install` local before going on, because ixport's pages are drawn with Keystone UI components and its styles.
+2. Check that the app has Active Storage set up, because ixport keeps each uploaded file as an Active Storage attachment. All three must hold:
+   - `config/application.rb` loads Active Storage, either through `require "rails/all"` or through `require "active_storage/engine"`.
+   - `db/schema.rb` has the `active_storage_blobs`, `active_storage_attachments` and `active_storage_variant_records` tables.
+   - Each environment file in `config/environments/` sets `config.active_storage.service`, and `config/storage.yml` defines that service.
+
+   If any is missing, tell the developer ixport cannot accept uploads without Active Storage and ask before setting it up. Where the tables are missing, setting it up means running `bin/rails active_storage:install` and then `bin/rails db:migrate`. Ask the developer which storage service each environment should use rather than picking one.
+3. Add the gem to the app's `Gemfile`:
+   ```ruby
+   gem "ixport"
+   ```
+   Then run `bundle install`.
+4. Run the install generator:
+   ```bash
+   bin/rails generate ixport:install
+   ```
+   It writes two files and touches no other:
+   - `db/migrate/<timestamp>_create_ixport_imports.rb` creates the `ixport_imports` table with a required `key` string, a required polymorphic `person` reference, an optional polymorphic `account` reference, a `mapping` JSON column, a required `status` string defaulting to `"pending"`, required `added_count` and `updated_count` integers defaulting to `0`, and timestamps.
+   - `db/migrate/<timestamp>_create_ixport_import_refusals.rb` creates the `ixport_import_refusals` table with a required `import` reference with a foreign key to `ixport_imports`, a required `row_number` integer, a required `reason` text, and timestamps.
+5. Run the migrations:
+   ```bash
+   bin/rails db:migrate
+   ```
+6. Ask the developer which path ixport's pages should live under. There is no default path. Add the mount inside `Rails.application.routes.draw` in `config/routes.rb`, using their answer:
+   ```ruby
+   mount Ixport::Engine => "/data_imports"
+   ```
+   If the app's routes put signed-in pages inside a block such as `authenticate :user do`, ask the developer whether the mount goes inside it.
+7. Read the app's `ApplicationController` and the controller methods it gets from its sign-in setup. ixport's controllers inherit from the app's `ApplicationController`, so every method named in the next step must be callable from it.
+8. Compare the app's method and layout names with the defaults in the Interface section. Every default matches a Jumpstart app, so an app that uses all of the defaults needs no configuration. Where any name differs, or a method does not exist, ask the developer which method or layout to use rather than picking one:
+   - The sign-in check: the method that sends a person who is not signed in to sign in, such as `:authenticate_user!` or `:require_login`.
+   - The current person: the method returning the signed-in person, such as `:current_user` or `:current_member`. An import belongs to this person, and another person who opens it gets a not found response.
+   - The current account: the method returning the team or company the person works inside, such as `:current_account` or `:current_team`. An import belongs to this account too, and the same person who opens it from another account gets a not found response. Ask whether the app has accounts at all. ixport calls the named method on every page, so an app with no accounts still needs a method of that name callable from `ApplicationController`, and it returns `nil`. Ask the developer before adding one.
+   - The layout: the file in `app/views/layouts/` that ixport's pages should be drawn inside.
+   - The inline row limit: ask only if the developer wants a limit other than 1,000 rows.
+9. Write only the settings that differ from the defaults into a new initializer, `config/initializers/ixport.rb`:
+   ```ruby
+   Ixport.configure do |config|
+     config.authentication_method = :require_login
+     config.current_person_method = :current_member
+     config.current_account_method = :current_team
+     config.layout = "back_office"
+     config.inline_row_limit = 5_000
+   end
+   ```
+   The values above are examples, and each line is written only when the developer's answer differs from the default.
+10. Start the app and visit the mounted path while signed in. The page shows the heading "Imports" and the message "No imports are set up yet." Visiting it while signed out sends the browser through the app's own sign-in check.
+
+## Conventions
+
+- After installing, check that `bin/rails db:migrate:status` lists both the create-ixport-imports and the create-ixport-import-refusals migrations as up, that `bin/rails routes` lists the mount path, and that the page at that path loads as described in step 10.
+- Run the install generator once. A second run against unchanged copies reports each migration as identical and adds nothing. If a copied migration differs from the one the generator would write, the run stops with an error naming that migration, and copies nothing after it. Do not delete or edit a copied migration once it has been run.
+- When the app renames its sign-in method, its current person or account method, or the layout ixport uses, update the matching line in `config/initializers/ixport.rb` in the same change.
+- A setting given the same value as its default is left out of the initializer. Remove a line when its value goes back to the default.
+- Setting up the imports that appear on the page, and the upload, mapping, preview, run and result pages they lead to, is out of scope for this local and belongs to `ixport-develop`.

data/the_local/interface.yml

@@ -0,0 +1,55 @@
+scope: CSV import and export — a mounted engine where a signed-in person sees the mapped imports the host app registers, each backed by an importer class the host writes
+
+install:
+  - gem "ixport"
+  - bin/rails generate ixport:install
+  - mount Ixport::Engine
+  - Ixport.configure
+  - config.authentication_method
+  - config.current_person_method
+  - config.current_account_method
+  - config.layout
+  - config.inline_row_limit
+
+develop:
+  - Ixport.register_import
+  - Ixport::Importer
+  - field
+  - match_on
+  - records
+  - person
+  - account
+  - Ixport::MissingImporter
+  - GET /
+  - GET /imports/new
+  - POST /imports
+  - GET /imports/:import_id/mapping
+  - PATCH /imports/:import_id/mapping
+  - GET /imports/:import_id/preview
+  - POST /imports/:import_id/run
+  - GET /imports/:id
+
+sources:
+  - lib/ixport.rb
+  - lib/ixport/engine.rb
+  - lib/ixport/configuration.rb
+  - lib/ixport/registrations.rb
+  - lib/ixport/importer.rb
+  - lib/generators/ixport/install/install_generator.rb
+  - lib/generators/ixport/install/templates/create_ixport_imports.rb.erb
+  - config/routes.rb
+  - app/controllers/ixport/application_controller.rb
+  - app/controllers/ixport/imports_controller.rb
+  - app/views/ixport/imports/index.html.erb
+  - app/models/ixport/application_record.rb
+  - app/models/ixport/import.rb
+  - app/controllers/ixport/mappings_controller.rb
+  - app/views/ixport/imports/new.html.erb
+  - app/views/ixport/mappings/show.html.erb
+  - app/models/ixport/row_walk.rb
+  - app/controllers/ixport/previews_controller.rb
+  - app/views/ixport/previews/show.html.erb
+  - app/models/ixport/import_refusal.rb
+  - app/controllers/ixport/runs_controller.rb
+  - app/views/ixport/imports/show.html.erb
+  - lib/generators/ixport/install/templates/create_ixport_import_refusals.rb.erb

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: ixport
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tyler Schneider
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: keystone_ui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.38.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.38.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: A Rails engine that lets a person import records into a Rails app from
+  a CSV file and export them to one.
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/ixport/application_controller.rb
+- app/controllers/ixport/imports_controller.rb
+- app/controllers/ixport/mappings_controller.rb
+- app/controllers/ixport/previews_controller.rb
+- app/controllers/ixport/runs_controller.rb
+- app/models/ixport/application_record.rb
+- app/models/ixport/import.rb
+- app/models/ixport/import_refusal.rb
+- app/models/ixport/row_walk.rb
+- app/views/ixport/imports/index.html.erb
+- app/views/ixport/imports/new.html.erb
+- app/views/ixport/imports/show.html.erb
+- app/views/ixport/mappings/show.html.erb
+- app/views/ixport/previews/show.html.erb
+- config/routes.rb
+- lib/generators/ixport/install/install_generator.rb
+- lib/generators/ixport/install/templates/create_ixport_import_refusals.rb.erb
+- lib/generators/ixport/install/templates/create_ixport_imports.rb.erb
+- lib/ixport.rb
+- lib/ixport/configuration.rb
+- lib/ixport/engine.rb
+- lib/ixport/importer.rb
+- lib/ixport/registrations.rb
+- lib/ixport/version.rb
+- the_local/agents/ixport-develop.md
+- the_local/agents/ixport-info.md
+- the_local/agents/ixport-install.md
+- the_local/interface.yml
+homepage: https://github.com/DYB-Development/ixport
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/DYB-Development/ixport
+  source_code_uri: https://github.com/DYB-Development/ixport
+  changelog_uri: https://github.com/DYB-Development/ixport/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/DYB-Development/ixport/issues
+  documentation_uri: https://github.com/DYB-Development/ixport#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: CSV import and export for Rails apps.
+test_files: []