plutonium 0.60.5 → 0.61.0

data/lib/plutonium/wizard/field_importer.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Resolves a step's `using:` option (§2.4) — importing a field surface from a
+    # **model (ActiveRecord class)** instead of re-declaring it.
+    #
+    # `using:` targets a model only. A `Plutonium::Resource::Definition` carries no
+    # link to its model (it's an empty class the controller binds at request time),
+    # so the only reliable direction is **model → definition**: the importer
+    # auto-resolves `"#{Model}Definition"` to overlay input styling, best-effort.
+    #
+    # The imported surface is:
+    #   - **attribute_schema** ({name => type}) — the field universe is
+    #     `Model.attribute_names` (filtered by selectors); types are
+    #     `Model.attribute_types[name].type`.
+    #   - **inputs** ({name => {options:, block:}}) — overlaid from the resolved
+    #     `<Model>Definition`'s `field`/`input` config (`as:`, options, labels),
+    #     sliced to the imported names. No definition → empty input config.
+    #   - **form_layout** — the resolved `<Model>Definition`'s `defined_form_layout`,
+    #     filtered to the imported fields, **plus a trailing ungrouped section** for
+    #     imported fields not named in any explicit section (skipped when
+    #     `layout: false`).
+    #   - **validate_fn** — runs a transient `Model.new(slice).valid?` and keeps
+    #     errors only on the imported fields **plus `:base`** (skipped when
+    #     `validate: false`).
+    #
+    # Validation is *run-and-filtered* rather than cloned: AR validators can't be
+    # cloned cleanly. Filtering to imported fields + `:base` is what prevents a
+    # partial model reporting presence errors for columns this step never collects.
+    module FieldImporter
+      # The validator kinds the form pipeline reads for field metadata (required
+      # marker, maxlength/minlength, min/max, pattern, auto-choices). Other kinds
+      # (uniqueness, custom EachValidators) carry no form meaning, so we skip them
+      # — and replaying a custom kind through `validates` would raise.
+      FORM_VALIDATOR_KINDS = %i[presence length numericality format inclusion].freeze
+
+      # The resolved import surface for one `using:` declaration.
+      Spec = Struct.new(:attribute_schema, :inputs, :form_layout, :validate_fn, :form_validators) do
+        # Run the imported validation over a staged data slice, returning a hash of
+        # {attribute => [messages]} for the imported fields + :base. Empty when
+        # `validate: false`.
+        def validate(data_slice)
+          validate_fn ? validate_fn.call(data_slice) : {}
+        end
+      end
+
+      class << self
+        # @param using [Class] an ActiveRecord model class
+        # @param opts [Hash] fields:/only:/except:/validate:/layout:/validation_context:
+        # @return [Spec]
+        def resolve(using:, opts:)
+          model = model!(using)
+          opts ||= {}
+          only = normalize(opts[:fields] || opts[:only])
+          except = normalize(opts[:except]) || []
+          do_validate = opts.fetch(:validate, true)
+          do_layout = opts.fetch(:layout, true)
+          context = opts[:validation_context]
+
+          names = select(model.attribute_names.map(&:to_sym), only:, except:)
+          definition = "#{model.name}Definition".safe_constantize
+
+          schema = names.index_with { |n| record_type(model, n) }
+
+          validate_fn = build_validate(do_validate) do |slice|
+            record = model.new(string_slice(slice, names))
+            run_and_filter(record, names, context)
+          end
+
+          Spec.new(
+            attribute_schema: schema,
+            inputs: inputs_for(definition, names),
+            form_layout: do_layout ? layout_for(definition, names) : nil,
+            validate_fn:,
+            form_validators: form_validators_for(model, names)
+          )
+        end
+
+        private
+
+        # The imported fields' form-relevant validators, as raw `[[name], options]`
+        # pairs replayable through `validates` onto the typed data class — so the
+        # form pipeline surfaces imported required/length/etc. the same as inline
+        # `validates`. Kept SEPARATE from `validate_fn`: the runner validates
+        # imported fields through the transient model, so these must not feed it.
+        def form_validators_for(model, names)
+          names.flat_map do |name|
+            model.validators_on(name).filter_map do |validator|
+              next unless FORM_VALIDATOR_KINDS.include?(validator.kind)
+              [[name], {validator.kind => validator.options.presence || true}]
+            end
+          end
+        end
+
+        # `using:` accepts a model class only. Anything else is a programming error.
+        def model!(using)
+          unless using.is_a?(Class) && using < ActiveRecord::Base
+            raise ArgumentError,
+              "using: expects a model class (an ActiveRecord::Base subclass), got #{using.inspect}"
+          end
+          using
+        end
+
+        def normalize(value)
+          return nil if value.nil?
+          Array(value).map(&:to_sym).presence
+        end
+
+        # `names & only` preserves source order while restricting to the selection.
+        def select(names, only:, except:)
+          names = names.select { |n| only.include?(n) } if only
+          names - except
+        end
+
+        def record_type(model, name)
+          # AR enum columns are integer-backed, but forms submit the string enum
+          # *key* ("active"), not the integer. Importing the raw :integer type would
+          # cast the key to 0. Keep enum fields as :string so the key round-trips —
+          # the author's `Model.new(field: data.field)` then lets AR map key → int,
+          # and the review summary shows the key, not a meaningless integer.
+          return :string if model.defined_enums.key?(name.to_s)
+          model.attribute_types[name.to_s]&.type || :string
+        end
+
+        def string_slice(slice, names)
+          slice = (slice || {}).stringify_keys
+          slice.slice(*names.map(&:to_s))
+        end
+
+        def build_validate(do_validate, &block)
+          do_validate ? block : nil
+        end
+
+        # Run `valid?` (with the optional context) and keep only the errors on the
+        # imported fields + :base.
+        def run_and_filter(obj, names, context)
+          context ? obj.valid?(context) : obj.valid?
+          keep = names + [:base]
+          obj.errors.group_by_attribute.slice(*keep)
+        end
+
+        # Build an input config for every imported name (so each gets rendered),
+        # overlaying styling from the resolved `<Model>Definition` where present. A
+        # definition's `field` and `input` declarations both render on the form;
+        # merge them per name (input wins on conflicting options, matching the
+        # resource form pipeline). No definition → each name maps to an empty config.
+        def inputs_for(definition, names)
+          fields = definition&.defined_fields || {}
+          inputs = definition&.defined_inputs || {}
+          names.index_with { |n| overlay_field_input(fields[n], inputs[n]) }
+        end
+
+        def overlay_field_input(field, input)
+          field ||= {}
+          input ||= {}
+          options = (field[:options] || {}).merge(input[:options] || {})
+          block = input[:block] || field[:block]
+          {options: options.presence, block:}.compact
+        end
+
+        # Inherit the resolved definition's form_layout, filtered to the imported
+        # fields. Mirrors the canonical `resolve_form_sections` leftover handling
+        # (form_layout.rb): each imported field is claimed by the first explicit
+        # section that lists it; imported fields no section names fall into a
+        # trailing **ungrouped** section, so none silently disappears.
+        def layout_for(definition, names)
+          return nil unless definition
+          layout = definition.defined_form_layout
+          return nil unless layout
+
+          # First-section-wins ownership among imported fields (shared with the
+          # canonical resolver). The ASSEMBLY below differs deliberately: an
+          # imported layout drops explicit sections that resolve to zero imported
+          # fields, and only synthesizes a trailing ungrouped section when there
+          # are leftovers — so it can't share the full `resolve_sections`.
+          owner, leftovers = Plutonium::Definition::FormLayout.assign_ownership(layout, names)
+
+          resolved = layout.filter_map do |section|
+            fields =
+              if section.ungrouped?
+                leftovers
+              else
+                section.fields.map(&:to_sym).select { |f| owner[f] == section.key }
+              end
+            # Drop explicit sections that resolve to zero imported fields; keep an
+            # explicit ungrouped section as the leftover home even when empty-listed.
+            next if fields.empty? && !section.ungrouped?
+            Plutonium::Definition::FormLayout::ResolvedSection.new(section, fields)
+          end
+
+          # No explicit ungrouped section, but leftover imported fields exist →
+          # synthesize a trailing ungrouped section so nothing disappears.
+          if leftovers.any? && layout.none?(&:ungrouped?)
+            ungrouped = Plutonium::Definition::FormLayout::Section.new(
+              key: Plutonium::Definition::FormLayout::UNGROUPED_KEY,
+              fields: [].freeze,
+              options: {}.freeze
+            )
+            resolved.push(Plutonium::Definition::FormLayout::ResolvedSection.new(ungrouped, leftovers))
+          end
+
+          resolved
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/gate.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Controller concern that gates access behind a **one-time wizard** (§9).
+    #
+    # +ensure_wizard_completed(WizardClass)+ installs a +before_action+ that
+    # recomputes the wizard's +instance_key+ (from its +concurrency_key+ — resolved
+    # against the host controller's identity context, with the tenant folded in,
+    # §4.4) and checks whether a retained +completed+ row exists at that key. If
+    # not, it stashes the intended destination and redirects into the wizard's
+    # entry step; once the wizard's own finalize retains the completion marker, the
+    # gate lets the user through and the controller bounces back to the stashed
+    # destination (PRG, wired in {Controller}).
+    #
+    #   class DashboardController < AdminPortal::PlutoniumController
+    #     include Plutonium::Wizard::Gate
+    #     ensure_wizard_completed OnboardingWizard
+    #   end
+    #
+    # Only **one-time** wizards (a +concurrency_key+ plus +one_time+) are gateable —
+    # they are the only ones with a durable retained marker. Gating any other
+    # wizard raises a clear error at install time.
+    #
+    # The instance_key recomputation MUST match the runner/driving digest exactly
+    # (both go through {Plutonium::Wizard.compute_instance_key}), or the gate would
+    # never see the completion the wizard recorded.
+    module Gate
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Install the gating +before_action+. Extra options (e.g. +only:/except:+)
+        # are forwarded to +before_action+.
+        #
+        # +anchor:+ tells the gate how to resolve an ANCHORED wizard's anchor in
+        # THIS controller's context (a symbol method name or a proc evaluated on the
+        # controller) — required to recompute an anchor-keyed wizard's instance_key.
+        # A `via:`-anchored wizard whose anchor method the controller exposes is
+        # resolved automatically, so this is only needed when the anchor isn't in
+        # scope (e.g. a `with:`-anchored wizard, or gating from another portal).
+        def ensure_wizard_completed(wizard_class, anchor: nil, **before_action_opts)
+          unless wizard_class.one_time?
+            raise ArgumentError,
+              "#{wizard_class.name} is not a one-time wizard (needs a " \
+              "`concurrency_key` + `one_time`); only one-time wizards are gateable (§9)."
+          end
+
+          before_action(**before_action_opts) do
+            enforce_wizard_completion!(wizard_class, anchor)
+          end
+        end
+      end
+
+      private
+
+      # The before_action body: pass through when completed, else stash + redirect.
+      def enforce_wizard_completion!(wizard_class, anchor_resolver = nil)
+        return if wizard_completed?(wizard_class, anchor_resolver)
+
+        session[:return_to] ||= request.fullpath
+        redirect_to wizard_entry_path(wizard_class)
+      end
+
+      def wizard_completed?(wizard_class, anchor_resolver = nil)
+        wizard_gate_store.completed?(instance_key: wizard_gate_instance_key(wizard_class, anchor_resolver))
+      end
+
+      # Recompute the wizard's instance_key on the host controller (§9). The
+      # identity context (`current_user`, `current_scoped_entity`, `anchor`, custom
+      # host methods) is read from this controller; a referenced method that's
+      # missing raises a clear error via {compute_instance_key}.
+      def wizard_gate_instance_key(wizard_class, anchor_resolver = nil)
+        Plutonium::Wizard.compute_instance_key(
+          wizard_class: wizard_class,
+          current_user: current_user,
+          current_scoped_entity: wizard_gate_scoped_entity,
+          anchor: wizard_gate_anchor(wizard_class, anchor_resolver),
+          wizard_token: nil
+        )
+      end
+
+      # Resolve an anchored wizard's anchor in this controller's context, so an
+      # anchor-keyed wizard's `instance_key` recomputes to the SAME digest the run
+      # used (§9). Order: an explicit `anchor:` resolver wins; otherwise a
+      # `via:`-anchored wizard whose anchor method the controller exposes is
+      # resolved automatically (the same method the wizard uses); otherwise nil — a
+      # non-anchored wizard, or an anchor that can't be reached here. The latter is a
+      # misconfiguration for an anchor-keyed wizard, so raise rather than mis-key.
+      def wizard_gate_anchor(wizard_class, anchor_resolver)
+        return resolve_gate_anchor(anchor_resolver) if anchor_resolver
+        return nil unless wizard_class.anchored?
+
+        via = wizard_class.anchor_via
+        return send(via) if via && respond_to?(via, true)
+
+        # Couldn't auto-resolve the anchor. When the wizard relies on the IMPLIED
+        # anchor key, the anchor is DEFINITELY part of the identity, so a nil would
+        # silently mis-key (the gate would loop forever) — raise instead. For an
+        # explicit key we can't tell whether it references the anchor, so leave it
+        # nil (best-effort, same contract as any host-method the key may reference).
+        if wizard_class.implied_anchor_key?
+          raise ArgumentError,
+            "#{wizard_class.name} is anchored and keyed by its anchor, but #{self.class} " \
+            "can't resolve it#{" (no `#{via}` here)" if via}. Pass `anchor:` to " \
+            "`ensure_wizard_completed` (a method name or proc)."
+        end
+        nil
+      end
+
+      # Evaluate an explicit `anchor:` resolver: a proc runs in the controller
+      # context, a symbol is sent to the controller.
+      def resolve_gate_anchor(resolver)
+        resolver.respond_to?(:call) ? instance_exec(&resolver) : send(resolver)
+      end
+
+      # The tenant folded into the gate's key recomputation (§4.4) — the portal
+      # scoping entity when the host portal is entity-scoped, else nil. Mirrors the
+      # driving layer's `resolved_wizard_scope`. `current_user`/`scoped_to_entity?`
+      # are private on portal controllers, so call them directly (a `respond_to?`
+      # check would be false for private methods and silently mis-key).
+      def wizard_gate_scoped_entity
+        return unless scoped_to_entity?
+
+        current_scoped_entity
+      end
+
+      def wizard_gate_store
+        Plutonium::Wizard::Store::ActiveRecord.new
+      end
+
+      # The entry URL for the wizard (§5.3): the bare LAUNCH route `register_wizard`
+      # drew, resolved from THIS portal's route set by the wizard's `wizard_class`
+      # route default — so the actual `at:`/`as:` used at registration is honored
+      # (re-deriving a slug from the class name breaks whenever they differ, e.g.
+      # `register_wizard W, at: "onboarding"`). The launch action resolves/mints the
+      # run and PRGs to its current (resumed) step, so no `:step` is needed here. The
+      # tenant scope path segment is threaded for an entity-scoped portal (the route
+      # requires it). Override for a custom mount.
+      def wizard_entry_path(wizard_class)
+        route_set = wizard_gate_route_set
+        name = Plutonium::Wizard::RouteResolution.route_name(route_set, wizard_class, action: "launch")
+        unless name
+          raise ArgumentError,
+            "#{self.class} gates #{wizard_class.name} but no `register_wizard` launch " \
+            "route for it was found in #{(route_set === Rails.application.routes) ? "the application" : "this portal"}. " \
+            "Register it with `register_wizard #{wizard_class.name}, at: \"…\"`, or override " \
+            "`wizard_entry_path` for a custom mount."
+        end
+
+        route_set.url_helpers.public_send(:"#{name}_path", **wizard_gate_scope_param)
+      end
+
+      # The route set the gated wizard is mounted in — the host portal's engine
+      # routes (it's registered alongside the portal's resources). Override if the
+      # gate lives outside the wizard's portal.
+      def wizard_gate_route_set
+        current_engine.routes
+      end
+
+      # The tenant scope path segment for an entity-scoped portal, threaded from the
+      # current request so the entry URL stays inside the tenant. The route's param
+      # key is the engine's own `scoped_entity_param_key` (honors a custom
+      # `param_key:`); empty for a non-scoped portal.
+      def wizard_gate_scope_param
+        return {} unless scoped_to_entity?
+
+        {scoped_entity_param_key => params[scoped_entity_param_key]}
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/instance_key.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Plutonium
+  module Wizard
+    # Computes the deterministic identity digest a wizard session row is keyed by
+    # (§4). There are two builders, mirroring the two identity axes:
+    #
+    # - {.concurrency} — a wizard with a `concurrency_key`. The digest is over the
+    #   wizard name and the serialized key value(s) (which already include the
+    #   folded tenant, §4.4). The keyed row IS the lock — two launches with the
+    #   same key collapse to one digest, so the second resumes the first.
+    # - {.tokened} — a wizard without a `concurrency_key`. The digest is over the
+    #   wizard name and the per-launch `wizard_token`, so every launch is a fresh,
+    #   independent (repeatable) run.
+    #
+    # The two recipes MUST stay byte-identical between the place that creates rows
+    # (runner/driving) and the place that recomputes the key (the gate), or
+    # one-time gating silently breaks.
+    module InstanceKey
+      # Keyed (concurrency_key) identity.
+      #
+      # @param wizard_name [String] the wizard class name
+      # @param key_values [Object, Array] the concurrency_key value(s); arrays are
+      #   serialized element-wise then joined. The tenant is expected to already be
+      #   folded in by the caller (§4.4).
+      # @return [String] a hex SHA256 digest
+      def self.concurrency(wizard_name, key_values)
+        digest("concurrency", wizard_name, serialize(key_values))
+      end
+
+      # Tokened (no concurrency_key) identity.
+      #
+      # @param wizard_name [String] the wizard class name
+      # @param token [String] the per-launch wizard token
+      # @return [String] a hex SHA256 digest
+      def self.tokened(wizard_name, token)
+        digest("tokened", wizard_name, token.to_s)
+      end
+
+      # Serialize a key value into a STRUCTURED, unambiguous form for the digest:
+      #   - Array → each element serialized, kept as a nested array
+      #   - AR record / GlobalID-able → its GlobalID string
+      #   - nil → nil (a nil tenant folds to a stable, distinct blank)
+      #   - scalar → to_s
+      #
+      # Structure (not a flat join) is the point: the digest hashes the JSON of the
+      # nested form, so `["a", "b"]` and the scalar `"a|b"` serialize to distinct
+      # JSON (`["a","b"]` vs `"a|b"`) and can never collide. A separator-joined form
+      # would make a key element containing the separator indistinguishable from a
+      # structural boundary (two distinct runs collapsing to one row — cross-run
+      # data exposure / one-time gating satisfied by the wrong run).
+      #
+      # @param value [Object]
+      # @return [Object] a JSON-serializable structure (String / nested Array / nil)
+      def self.serialize(value)
+        case value
+        when Array
+          value.map { |v| serialize(v) }
+        when nil
+          nil
+        when String, Symbol, Numeric, true, false
+          value.to_s
+        else
+          if value.respond_to?(:to_global_id)
+            value.to_global_id.to_s
+          else
+            value.to_s
+          end
+        end
+      end
+
+      # Hash the JSON of [salt, *parts]. JSON makes the boundaries between parts (and
+      # between nested array elements) unambiguous; the salt (the app secret) makes
+      # the digest a MAC over otherwise-public identifiers (wizard name + key GIDs),
+      # so it can't be recomputed off-app to probe another run's existence/state.
+      def self.digest(*parts)
+        Digest::SHA256.hexdigest(JSON.generate([salt, *parts]))
+      end
+      private_class_method :digest
+
+      # A stable, app-specific salt. Falls back to a constant when no Rails app /
+      # secret is configured (e.g. isolated unit contexts) so the digest is still
+      # deterministic — the MAC property simply degrades to the unsalted form there.
+      def self.salt
+        if defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+          ::Rails.application.secret_key_base.to_s
+        else
+          "plutonium-wizard"
+        end
+      end
+      private_class_method :salt
+    end
+  end
+end

data/lib/plutonium/wizard/lazy_persisted.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Lazy view over a wizard run's persisted records (§2.2 / §4.5).
+    #
+    # The stored state only holds GIDs ({ "step_key" => [gid, ...] }); resolving
+    # them back into live records costs a `GlobalID::Locator.locate` per GID. Most
+    # requests (a GET render, a `back`, any step whose `condition:`/render never
+    # reads `persisted`) don't need those records at all, so we resolve LAZILY:
+    #
+    # - `persisted[:key]` returns the memoized live records when the key was SET
+    #   this request (records created via the `persist` macro in `on_submit`) — no
+    #   locate.
+    # - Otherwise it locates the GIDs stored under that key ONCE, memoizes the
+    #   result, and returns it. A request that never reads `persisted` issues zero
+    #   locate queries.
+    #
+    # `gid_source` is the `{ "step_key" => [gids] }` hash the runner injects from
+    # the stored state. Writes (`persisted[k] = records`) memoize live records
+    # directly and shadow any stored GIDs for that key.
+    class LazyPersisted
+      def initialize(gid_source = {})
+        @gid_source = gid_source || {}
+        @memo = {}
+      end
+
+      # Live records for a step key. Memoized records (set this request) are
+      # returned as-is; otherwise the key's stored GIDs are located once.
+      def [](key)
+        key = key.to_sym
+        return @memo[key] if @memo.key?(key)
+
+        @memo[key] = locate(@gid_source[key.to_s] || @gid_source[key])
+      end
+
+      # Memoize live records for a key directly (the runner's post-`on_submit`
+      # set, or an author assigning into `persisted`). No locate on later reads.
+      def []=(key, records)
+        @memo[key.to_sym] = Array(records)
+      end
+
+      # Whether this key has records available — either set this request or stored
+      # as GIDs. Does NOT trigger a locate.
+      def key?(key)
+        key = key.to_sym
+        @memo.key?(key) || @gid_source.key?(key.to_s) || @gid_source.key?(key)
+      end
+      alias_method :has_key?, :key?
+
+      # Resolve every known key to its located records (forces locates). Used where
+      # the full map is genuinely needed.
+      def to_h
+        keys.each_with_object({}) { |key, acc| acc[key] = self[key] }
+      end
+
+      # All known step keys (memoized + stored), as symbols, without locating.
+      def keys
+        (@memo.keys + @gid_source.keys.map(&:to_sym)).uniq
+      end
+
+      private
+
+      # Batch-resolve a key's GIDs in ONE query per model class (vs one locate per
+      # GID — an N+1 for a multi-record step). `ignore_missing: true` drops GIDs
+      # whose record no longer exists (e.g. swept/destroyed), matching the old
+      # per-GID `filter_map` that dropped nils; unparseable/invalid GIDs are dropped
+      # too, and input order is preserved.
+      def locate(gids)
+        gids = Array(gids)
+        return [] if gids.empty?
+
+        GlobalID::Locator.locate_many(gids, ignore_missing: true)
+      end
+    end
+  end
+end