open-loam 0.1.0

data/lib/generators/loam/install/templates/admin/dictionaries_edit.html.erb

@@ -0,0 +1,45 @@
+<h1>Dictionary: <code><%%= @dictionary.key %></code></h1>
+
+<%%= render "form" %>
+
+<h2>Entries</h2>
+<p>Ordered by position; an inactive entry stops being offered but keeps existing values readable.</p>
+
+<table>
+  <thead>
+    <tr><th>Pos</th><th>Value</th><th>Label</th><th>Color</th><th>Icon</th><th>Default</th><th>Active</th><th></th></tr>
+  </thead>
+  <tbody>
+    <%% @dictionary.entries.ordered.each do |entry| %>
+      <tr>
+        <%%= form_with model: entry, scope: :dictionary_entry, url: admin_dictionary_entry_path(@dictionary, entry) do |f| %>
+          <td><%%= f.number_field :position, style: "width:4rem" %></td>
+          <td><%%= f.text_field :value %></td>
+          <td><%%= f.text_field :label %></td>
+          <td><%%= f.text_field :color, placeholder: "#a00", style: "width:6rem" %></td>
+          <td><%%= f.text_field :icon, style: "width:6rem" %></td>
+          <td><%%= f.check_box :is_default %></td>
+          <td><%%= f.check_box :active %></td>
+          <td>
+            <%%= f.submit "Save" %>
+            <%%= button_to "Delete", admin_dictionary_entry_path(@dictionary, entry), method: :delete, form: { style: "display:inline" } %>
+          </td>
+        <%% end %>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>
+
+<h3>Add entry</h3>
+<%%= form_with model: @entry, scope: :dictionary_entry, url: admin_dictionary_entries_path(@dictionary) do |f| %>
+  <p><%%= f.label :value %> <%%= f.text_field :value %>
+     <%%= f.label :label %> <%%= f.text_field :label %>
+     <%%= f.label :position %> <%%= f.number_field :position, value: 0, style: "width:4rem" %></p>
+  <p><%%= f.label :color %> <%%= f.text_field :color, placeholder: "#a00" %>
+     <%%= f.label :icon %> <%%= f.text_field :icon %>
+     <%%= f.label :is_default %> <%%= f.check_box :is_default %>
+     <%%= f.label :active %> <%%= f.check_box :active, checked: true %></p>
+  <%%= f.submit "Add entry" %>
+<%% end %>
+
+<p><%%= link_to "Back to dictionaries", admin_dictionaries_path %></p>

data/lib/generators/loam/install/templates/admin/dictionaries_form.html.erb

@@ -0,0 +1,10 @@
+<%%# Loam::Dictionary is namespaced, so pin the URL + param scope. %>
+<%%= form_with model: @dictionary, scope: :dictionary,
+      url: (@dictionary.persisted? ? admin_dictionary_path(@dictionary) : admin_dictionaries_path) do |f| %>
+  <%% if @dictionary.errors.any? %>
+    <ul><%% @dictionary.errors.full_messages.each do |m| %><li><%%= m %></li><%% end %></ul>
+  <%% end %>
+  <p><%%= f.label :key, "Key (code, e.g. damage_severity)" %><br><%%= f.text_field :key %></p>
+  <p><%%= f.label :name %><br><%%= f.text_field :name %></p>
+  <%%= f.submit %>
+<%% end %>

data/lib/generators/loam/install/templates/admin/dictionaries_index.html.erb

@@ -0,0 +1,21 @@
+<h1>Dictionaries</h1>
+
+<p>Managed lookup lists for this tenant — curate the values here, then use one as
+a "dictionary" custom-field type. <%%= link_to "New dictionary", new_admin_dictionary_path %></p>
+
+<table>
+  <thead><tr><th>Key</th><th>Name</th><th>Entries</th><th></th></tr></thead>
+  <tbody>
+    <%% @dictionaries.each do |dictionary| %>
+      <tr>
+        <td><code><%%= dictionary.key %></code></td>
+        <td><%%= dictionary.name %></td>
+        <td><%%= dictionary.entries.count %></td>
+        <td>
+          <%%= link_to "Edit", edit_admin_dictionary_path(dictionary) %>
+          <%%= button_to "Delete", admin_dictionary_path(dictionary), method: :delete, form: { style: "display:inline" } %>
+        </td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>

data/lib/generators/loam/install/templates/admin/dictionaries_new.html.erb

@@ -0,0 +1,5 @@
+<h1>New dictionary</h1>
+
+<%%= render "form" %>
+
+<p><%%= link_to "Back", admin_dictionaries_path %></p>

data/lib/generators/loam/install/templates/admin/dictionary_entries_controller.rb

@@ -0,0 +1,47 @@
+module Admin
+  # Entries of a Loam::Dictionary — manager-only, nested under a dictionary.
+  # Add / edit (value, label, color, icon, position, default, active) / delete;
+  # reordering is by editing `position`.
+  class DictionaryEntriesController < BaseController
+    before_action { require_role!(:manager) }
+    before_action :set_dictionary
+    before_action :set_entry, only: %i[update destroy]
+
+    def create
+      @entry = @dictionary.entries.new(entry_params)
+      if @entry.save
+        redirect_to edit_admin_dictionary_path(@dictionary), notice: "Entry added."
+      else
+        @dictionary_errors = @entry.errors.full_messages
+        redirect_to edit_admin_dictionary_path(@dictionary), alert: @dictionary_errors.join(", ")
+      end
+    end
+
+    def update
+      if @entry.update(entry_params)
+        redirect_to edit_admin_dictionary_path(@dictionary), notice: "Entry updated."
+      else
+        redirect_to edit_admin_dictionary_path(@dictionary), alert: @entry.errors.full_messages.join(", ")
+      end
+    end
+
+    def destroy
+      @entry.destroy!
+      redirect_to edit_admin_dictionary_path(@dictionary), notice: "Entry removed."
+    end
+
+    private
+
+    def set_dictionary
+      @dictionary = Loam::Dictionary.find(params[:dictionary_id])
+    end
+
+    def set_entry
+      @entry = @dictionary.entries.find(params[:id])
+    end
+
+    def entry_params
+      params.require(:dictionary_entry).permit(:value, :label, :color, :icon, :position, :is_default, :active)
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/event_deliveries_controller.rb

@@ -0,0 +1,23 @@
+module Admin
+  # Durable event deliveries (Loam::EventDelivery) — the dead-letter view.
+  # Manager-only. Lists deliveries parked as `dead` (handler removed, or retries
+  # exhausted) and lets an operator requeue one after fixing the handler. Pending
+  # deliveries drain on their own; a small sample is shown for visibility.
+  class EventDeliveriesController < BaseController
+    before_action { require_role!(:manager) }
+
+    def index
+      @dead = Loam::EventDelivery.dead.order(updated_at: :desc).limit(200)
+      @pending = Loam::EventDelivery.pending.order(Arel.sql("next_attempt_at IS NULL DESC, next_attempt_at ASC")).limit(50)
+    end
+
+    # Re-arm one delivery: back to pending with a clean slate, and nudge a job.
+    # The sweep would eventually pick it up anyway; this is the "try now" button.
+    def redeliver
+      delivery = Loam::EventDelivery.find(params[:id])
+      delivery.update!(status: "pending", attempts: 0, next_attempt_at: nil, last_error: nil)
+      Loam::EventDeliveryJob.perform_later(delivery.tenant_id, delivery.id)
+      redirect_to admin_event_deliveries_path, notice: "Delivery requeued."
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/event_deliveries_index.html.erb

@@ -0,0 +1,49 @@
+<h1>Event deliveries</h1>
+
+<p>Durable subscribers (<code>Loam::DurableEvents</code>). Delivery is at-least-once
+with retry; a delivery that exhausts its retries — or whose subscriber was removed —
+is parked here as <strong>dead</strong> for you to fix and requeue.</p>
+
+<h2>Dead-letter (<%%= @dead.size %>)</h2>
+<%% if @dead.any? %>
+  <table>
+    <thead>
+      <tr><th>Subscriber</th><th>Event</th><th>Attempts</th><th>Last error</th><th>When</th><th></th></tr>
+    </thead>
+    <tbody>
+      <%% @dead.each do |d| %>
+        <tr>
+          <td><code><%%= d.subscriber_key %></code></td>
+          <td><code><%%= d.event_name %></code></td>
+          <td><%%= d.attempts %></td>
+          <td><small><%%= d.last_error %></small></td>
+          <td><%%= d.updated_at.strftime("%Y-%m-%d %H:%M UTC") %></td>
+          <td><%%= button_to "Requeue", redeliver_admin_event_delivery_path(d), form: { style: "display:inline" } %></td>
+        </tr>
+      <%% end %>
+    </tbody>
+  </table>
+<%% else %>
+  <p>No dead deliveries. 🎉</p>
+<%% end %>
+
+<h2>Pending (next <%%= @pending.size %>)</h2>
+<%% if @pending.any? %>
+  <table>
+    <thead>
+      <tr><th>Subscriber</th><th>Event</th><th>Attempts</th><th>Next attempt</th></tr>
+    </thead>
+    <tbody>
+      <%% @pending.each do |d| %>
+        <tr>
+          <td><code><%%= d.subscriber_key %></code></td>
+          <td><code><%%= d.event_name %></code></td>
+          <td><%%= d.attempts %></td>
+          <td><%%= d.next_attempt_at ? d.next_attempt_at.strftime("%Y-%m-%d %H:%M UTC") : "now" %></td>
+        </tr>
+      <%% end %>
+    </tbody>
+  </table>
+<%% else %>
+  <p>Nothing pending.</p>
+<%% end %>

data/lib/generators/loam/install/templates/admin/events_controller.rb

@@ -0,0 +1,42 @@
+module Admin
+  # Server-Sent Events: a per-tenant push stream (Loam::EventStream) so the admin
+  # updates live instead of polling. Authentication runs in the normal
+  # before_action chain (set_loam_context) BEFORE any stream write — so an
+  # unauthenticated request redirects to login the ordinary way, since no headers
+  # have been committed yet. Once the loop starts writing, the response is
+  # committed and there is no going back; that ordering is the whole safety of a
+  # Live action.
+  class EventsController < BaseController
+    include ActionController::Live
+
+    HEARTBEAT_SECONDS = 20
+
+    def stream
+      response.headers["Content-Type"] = "text/event-stream"
+      response.headers["Cache-Control"] = "no-cache"
+      handle = nil # so the ensure never raises NameError if subscribe below does
+      queue = Queue.new
+
+      # Subscribe as the FIRST thing in the begin whose ensure unsubscribes: a
+      # leaked AS::Notifications subscriber would fire on every future event in
+      # the process, holding this dead stream's queue forever.
+      handle = Loam::EventStream.broadcaster.subscribe(tenant: current_tenant, actor: current_actor) do |sse|
+        queue << sse
+      end
+
+      loop do
+        # A heartbeat comment both keeps the connection alive AND detects a dead
+        # client: writing to a closed socket raises IOError → the loop exits →
+        # ensure runs and the subscription is dropped.
+        message = queue.pop(timeout: HEARTBEAT_SECONDS)
+        response.stream.write(message || ": heartbeat\n\n")
+      end
+    rescue IOError, ActionController::Live::ClientDisconnected
+      # The client went away — nothing to do but clean up in `ensure`.
+    ensure
+      Loam::EventStream.broadcaster.unsubscribe(handle)
+      response.stream.close
+      Loam::Current.reset
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/features_controller.rb

@@ -0,0 +1,35 @@
+module Admin
+  # Feature flags (Loam::Features). Structural and privileged, so manager-only,
+  # like Settings. Everything routes through Loam::Features; the admin toggles
+  # the CURRENT tenant's override, and Reset drops it back to the declared /
+  # global state. Global (app-wide) flips are a deploy concern, not this screen.
+  class FeaturesController < BaseController
+    before_action { require_role!(:manager) }
+
+    def index
+      @flags = Loam::Features.declared.map do |name|
+        {
+          name: name,
+          on: Loam::Features.on?(name),
+          overridden: Loam::Features.overridden?(name),
+          description: Loam::Features.description(name)
+        }
+      end
+    end
+
+    def enable
+      Loam::Features.enable(params[:name])
+      redirect_to admin_features_path, notice: "#{params[:name]} enabled for this tenant."
+    end
+
+    def disable
+      Loam::Features.disable(params[:name])
+      redirect_to admin_features_path, notice: "#{params[:name]} disabled for this tenant."
+    end
+
+    def reset
+      Loam::Features.reset(params[:name])
+      redirect_to admin_features_path, notice: "#{params[:name]} reset to the default."
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/features_index.html.erb

@@ -0,0 +1,37 @@
+<h1>Features</h1>
+
+<p>Feature flags turn a capability on or off for <strong><%%= current_tenant.name %></strong>,
+independent of who is signed in. Toggling sets an override for this tenant;
+Reset drops it back to the default.</p>
+
+<table>
+  <thead>
+    <tr>
+      <th>Flag</th>
+      <th>State</th>
+      <th>Source</th>
+      <th>Description</th>
+      <th></th>
+    </tr>
+  </thead>
+  <tbody>
+    <%% @flags.each do |flag| %>
+      <tr>
+        <td><%%= flag[:name] %></td>
+        <td><%%= flag[:on] ? "on" : "off" %></td>
+        <td><%%= flag[:overridden] ? "override" : "default" %></td>
+        <td><%%= flag[:description] %></td>
+        <td>
+          <%% if flag[:on] %>
+            <%%= button_to "Disable", admin_disable_feature_path(name: flag[:name]), form: { style: "display:inline" } %>
+          <%% else %>
+            <%%= button_to "Enable", admin_enable_feature_path(name: flag[:name]), form: { style: "display:inline" } %>
+          <%% end %>
+          <%% if flag[:overridden] %>
+            <%%= button_to "Reset", admin_features_path(name: flag[:name]), method: :delete, form: { style: "display:inline" } %>
+          <%% end %>
+        </td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>

data/lib/generators/loam/install/templates/admin/field_definitions_controller.rb

@@ -0,0 +1,52 @@
+module Admin
+  # Manages Loam::FieldDefinition records: the "migration-free field" screen.
+  # Structural, not per-entity — gated on the manager role rather than a
+  # generated entity policy, since a field definition applies to a whole
+  # entity_type, not one record.
+  class FieldDefinitionsController < BaseController
+    before_action { require_role!(:manager) }
+    before_action :set_record, only: %i[destroy]
+
+    def index
+      @entity_type = params[:entity_type]
+      @records = Loam::FieldDefinition.order(:entity_type, :name)
+      @records = @records.where(entity_type: @entity_type) if @entity_type.present?
+    end
+
+    def new
+      @record = Loam::FieldDefinition.new(entity_type: params[:entity_type])
+    end
+
+    def create
+      @record = Loam::FieldDefinition.new(permitted_params)
+      @record.writable_roles = parse_roles(params.dig(:field_definition, :writable_roles))
+      @record.readable_roles = parse_roles(params.dig(:field_definition, :readable_roles))
+
+      if @record.save
+        redirect_to admin_field_definitions_path(entity_type: @record.entity_type)
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      entity_type = @record.entity_type
+      @record.destroy!
+      redirect_to admin_field_definitions_path(entity_type: entity_type)
+    end
+
+    private
+
+    def set_record
+      @record = Loam::FieldDefinition.find(params[:id])
+    end
+
+    def permitted_params
+      params.require(:field_definition).permit(:entity_type, :name, :field_type, :dictionary_key)
+    end
+
+    def parse_roles(raw)
+      raw.to_s.split(",").map(&:strip).reject(&:blank?)
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/field_definitions_index.html.erb

@@ -0,0 +1,30 @@
+<h1>Field definitions<%%= " — #{@entity_type}" if @entity_type.present? %></h1>
+
+<p>Add a field to an entity with no migration and no deploy.</p>
+
+<%%= link_to "New field definition", new_admin_field_definition_path(entity_type: @entity_type) %>
+
+<table>
+  <thead>
+    <tr>
+      <th>Entity type</th>
+      <th>Name</th>
+      <th>Field type</th>
+      <th>Writable by</th>
+      <th>Readable by</th>
+      <th></th>
+    </tr>
+  </thead>
+  <tbody>
+    <%% @records.each do |record| %>
+      <tr>
+        <td><%%= record.entity_type %></td>
+        <td><%%= record.name %></td>
+        <td><%%= record.field_type %></td>
+        <td><%%= record.writable_roles.presence&.join(", ") || "any member" %></td>
+        <td><%%= record.readable_roles.presence&.join(", ") || "any member" %></td>
+        <td><%%= button_to "Delete", admin_field_definition_path(record), method: :delete, form: { style: "display:inline" }, data: { turbo_confirm: "Delete this field? Existing data under this key becomes inaccessible." } %></td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>

data/lib/generators/loam/install/templates/admin/field_definitions_new.html.erb

@@ -0,0 +1,39 @@
+<h1>New field definition</h1>
+
+<%%= form_with model: @record, url: admin_field_definitions_path do |f| %>
+  <%% if @record.errors.any? %>
+    <ul>
+      <%% @record.errors.full_messages.each do |message| %>
+        <li><%%= message %></li>
+      <%% end %>
+    </ul>
+  <%% end %>
+
+  <p>
+    <%%= f.label :entity_type %><br>
+    <%%= f.text_field :entity_type %>
+  </p>
+  <p>
+    <%%= f.label :name %><br>
+    <%%= f.text_field :name %>
+  </p>
+  <p>
+    <%%= f.label :field_type %><br>
+    <%%= f.select :field_type, Loam::FieldDefinition::FIELD_TYPES %>
+  </p>
+  <p>
+    <%%= f.label :dictionary_key, "Dictionary key (only for a 'dictionary' field type)" %><br>
+    <%%= f.select :dictionary_key, Loam::Dictionary.order(:key).pluck(:key), include_blank: true %>
+  </p>
+  <p>
+    <%%= f.label :writable_roles, "Writable by (comma-separated roles, blank = any member)" %><br>
+    <%%= f.text_field :writable_roles %>
+  </p>
+  <p>
+    <%%= f.label :readable_roles, "Readable by (comma-separated roles, blank = any member)" %><br>
+    <%%= f.text_field :readable_roles %>
+    <small>Restricts who can see, filter, and sort by this field.</small>
+  </p>
+
+  <%%= f.submit "Create field definition" %>
+<%% end %>

data/lib/generators/loam/install/templates/admin/history_controller.rb

@@ -0,0 +1,38 @@
+module Admin
+  # A record's change history (Loam::AuditRecord) with one-click Undo (L-704).
+  # Undo applies the inverse of a change and records ITSELF as an audit, so
+  # undoing an "undo" entry is redo — no separate redo action. Reading needs read
+  # on the record; undoing needs update (the same gate as editing it).
+  class HistoryController < BaseController
+    before_action :set_target
+
+    def index
+      authorize!(policy_for(@record), :read?)
+      @audits = Loam::AuditRecord
+                .where(auditable_type: @record.class.name, auditable_id: @record.id)
+                .order(id: :desc).limit(100)
+    end
+
+    def undo
+      authorize!(policy_for(@record), :update?)
+      audit = Loam::AuditRecord.find(params[:id])
+      Loam::Undo.undo(audit, policy: policy_for(@record))
+      redirect_to admin_history_path(type: @record.class.name, record_id: @record.id), notice: "Change undone."
+    rescue Loam::Undo::NotUndoableError => error
+      redirect_to admin_history_path(type: @record.class.name, record_id: @record.id), alert: error.message
+    end
+
+    private
+
+    # The target record, looked up through its OWN default scope (tenancy holds;
+    # a soft-deleted row is still reachable to restore). The type is whitelisted
+    # to a Loam::TenantRecord — never a bare constantize of a param.
+    def set_target
+      klass = params[:type].to_s.safe_constantize
+      raise Loam::NotAuthorizedError unless klass.is_a?(Class) && klass < Loam::TenantRecord
+
+      scope = klass.respond_to?(:with_deleted) ? klass.with_deleted : klass.all
+      @record = scope.find(params[:record_id])
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/history_index.html.erb

@@ -0,0 +1,35 @@
+<h1>History: <%%= @record.class.model_name.human %> #<%%= @record.id %></h1>
+
+<p><%%= link_to "← Back", [:admin, @record] %></p>
+
+<p>Undo applies the inverse of a change and is itself recorded — so undoing an
+<code>undo</code> row is redo. Only the most recent field change can be undone
+(undo walks back one step at a time); encrypted fields and the workflow state are
+never reverted here.</p>
+
+<table>
+  <thead>
+    <tr><th>When</th><th>Action</th><th>By</th><th>Changes</th><th></th></tr>
+  </thead>
+  <tbody>
+    <%% @audits.each do |audit| %>
+      <tr>
+        <td><%%= audit.created_at.strftime("%Y-%m-%d %H:%M") %></td>
+        <td><code><%%= audit.action %></code></td>
+        <td><%%= audit.actor&.name || "—" %></td>
+        <td>
+          <%% (audit.changeset || {}).each do |field, values| %>
+            <div><code><%%= field %></code>:
+              <%%= values.is_a?(Array) ? "#{values.first.inspect} → #{values.last.inspect}" : values %></div>
+          <%% end %>
+        </td>
+        <td>
+          <%% if Loam::Undo.undoable?(audit) %>
+            <%%= button_to "Undo", admin_undo_history_path(id: audit.id, type: @record.class.name, record_id: @record.id),
+                          form: { style: "display:inline" } %>
+          <%% end %>
+        </td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>

data/lib/generators/loam/install/templates/admin/imports_controller.rb

@@ -0,0 +1,75 @@
+module Admin
+  # Generic CSV importer, scoped by entity_type — manager-only (a privileged bulk
+  # mutation). Flow: new (upload) → preview (map columns) → create (dry-run
+  # summary, or a backgrounded run reporting live progress). The mapping only
+  # offers fields the manager may write (Loam::Import.allowed_targets); a crafted
+  # target is refused by the engine.
+  class ImportsController < BaseController
+    before_action { require_role!(:manager) }
+    before_action :set_model, only: %i[preview create]
+
+    def new
+      @entity_type = params[:entity_type]
+    end
+
+    # Parse the uploaded file, show the mapping form + a few sample rows.
+    def preview
+      @csv = read_upload
+      preview = Loam::Import.preview(@csv)
+      @headers = preview[:headers]
+      @sample = preview[:rows]
+      @targets = Loam::Import.allowed_targets(@model, current_actor).to_a.sort
+    rescue Loam::Error => error
+      redirect_to new_admin_import_path(entity_type: @entity_type), alert: error.message
+    end
+
+    def create
+      @csv = params[:csv].to_s
+      mapping = params[:mapping].to_unsafe_h.reject { |_h, target| target.blank? }
+      match_key = params[:match_key].presence
+
+      if params[:commit] == "Dry run"
+        run_dry(mapping, match_key)
+      else
+        ImportJob.perform_later(entity_type: @entity_type, csv: @csv, mapping: mapping,
+                                match_key: match_key, tenant_id: current_tenant.id, actor_id: current_actor.id)
+        redirect_to admin_progress_jobs_path, notice: "Import started — watch it progress under Tasks."
+      end
+    rescue Loam::Error => error
+      redirect_to new_admin_import_path(entity_type: @entity_type), alert: error.message
+    end
+
+    # The failed rows as a fix-and-re-upload CSV.
+    def download_errors
+      @entity_type = params[:entity_type]
+      model = Loam::Import.allowed_model(@entity_type)
+      csv = params[:csv].to_s
+      mapping = params[:mapping].to_unsafe_h.reject { |_h, target| target.blank? }
+      result = Loam::Import.run(csv, model: model, mapping: mapping, actor: current_actor,
+                                match_key: params[:match_key].presence, dry_run: true)
+      send_data Loam::Import.error_csv(result, csv),
+                filename: "#{@entity_type.underscore}-import-errors.csv", type: "text/csv"
+    end
+
+    private
+
+    def set_model
+      @entity_type = params[:entity_type]
+      @model = Loam::Import.allowed_model(@entity_type)
+    end
+
+    def run_dry(mapping, match_key)
+      @result = Loam::Import.run(@csv, model: @model, mapping: mapping, actor: current_actor,
+                                 match_key: match_key, dry_run: true)
+      @headers = Loam::Import.preview(@csv)[:headers]
+      render :summary
+    end
+
+    def read_upload
+      file = params[:file]
+      raise Loam::Error, "choose a CSV file to upload" if file.blank?
+
+      file.read.force_encoding("UTF-8")
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/imports_new.html.erb

@@ -0,0 +1,10 @@
+<h1>Import <%%= @entity_type %></h1>
+
+<p>Upload a CSV, map its columns to fields, then dry-run or import. Rows that
+fail validation are skipped and reported (with a downloadable error file).</p>
+
+<%%= form_with url: preview_admin_imports_path, method: :post, multipart: true do %>
+  <%%= hidden_field_tag :entity_type, @entity_type %>
+  <p><%%= file_field_tag :file, accept: ".csv" %></p>
+  <%%= submit_tag "Upload & map" %>
+<%% end %>

data/lib/generators/loam/install/templates/admin/imports_preview.html.erb

@@ -0,0 +1,32 @@
+<h1>Map columns — <%%= @entity_type %></h1>
+
+<%%= form_with url: admin_imports_path, method: :post do %>
+  <%%= hidden_field_tag :entity_type, @entity_type %>
+  <%%= hidden_field_tag :csv, @csv %>
+
+  <table>
+    <thead><tr><th>CSV column</th><th>Maps to field</th><th>Sample</th></tr></thead>
+    <tbody>
+      <%% @headers.each_with_index do |header, i| %>
+        <tr>
+          <td><%%= header %></td>
+          <td>
+            <%%= select_tag "mapping[#{header}]",
+                  options_for_select([["— skip —", ""]] + @targets.map { |t| [t, t] }, @targets.include?(header) ? header : "") %>
+          </td>
+          <td><%%= @sample.map { |r| r[i] }.compact.first %></td>
+        </tr>
+      <%% end %>
+    </tbody>
+  </table>
+
+  <p>
+    <%%= label_tag :match_key, "Update existing rows matching (blank = create only)" %>
+    <%%= select_tag :match_key, options_for_select([["— create only —", ""]] + @targets.map { |t| [t, t] }) %>
+  </p>
+
+  <p>
+    <%%= submit_tag "Dry run" %>
+    <%%= submit_tag "Import" %>
+  </p>
+<%% end %>