plutonium 0.60.5 → 0.61.0

data/lib/plutonium/wizard/base.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Plutonium
+  module Wizard
+    # Author-facing base class for wizards (§2). A wizard declares ordered `step`s
+    # (with their own field surface, branching `condition:`, and optional per-step
+    # `on_submit`/`on_rollback`), an optional terminal `review` step, and commits
+    # at the end via `execute`.
+    #
+    # This class is pure object behaviour — declaring the DSL, exposing the
+    # ordered steps, the union `data` snapshot, and the `anchor`/`fail!`
+    # accessors. HTTP/runner/store wiring lives elsewhere.
+    #
+    # @example
+    #   class CompanyOnboardingWizard < Plutonium::Wizard::Base
+    #     step :company do
+    #       attribute :name, :string
+    #       input :name
+    #       validates :name, presence: true
+    #     end
+    #     review label: "Review"
+    #
+    #     def execute
+    #       succeed(Company.create!(name: data.name))
+    #     end
+    #   end
+    class Base
+      include ActiveModel::Model
+      include Plutonium::Definition::Presentable
+      include DSL
+
+      attr_reader :data_attributes
+      attr_accessor :view_context
+      attr_writer :anchor, :scope, :token
+
+      # Identity/concurrency context (§4.5), supplied by the runner/driving layer
+      # so `concurrency_key` resolvers and the tenancy fold can reach them.
+      # `wizard_token` is the per-run id (the identity for guest/repeatable runs,
+      # available inside `concurrency_key`) — NOT a pre-auth principal that
+      # survives login.
+      attr_accessor :current_user, :current_scoped_entity, :wizard_token
+
+      # The runner reuses a single wizard instance across a request, reassigning
+      # `data_attributes` between reads, so invalidate the memoized `data` snapshot
+      # whenever the staged attributes change. Only rebuild when the value actually
+      # CHANGES: the runner calls this on every `visible_path` (via `sync_data`),
+      # and an unconditional reset would discard a `data` snapshot the view layer
+      # has since mutated — e.g. validation errors `seed_errors!` added before the
+      # form reads them back (they'd silently vanish).
+      def data_attributes=(attrs)
+        return if @data && attrs == @data_attributes
+        @data_attributes = attrs
+        @data = nil
+      end
+
+      def initialize(view_context: nil, **)
+        @view_context = view_context
+        @data_attributes = {}
+        super()
+      end
+
+      class << self
+        # Per-step data spec ({step_key => {schema:, options:, structured:}}), used
+        # to build the step-keyed `data` container (§2.6). Each step contributes its
+        # OWN schema/options/structured — no cross-step union, so two steps may share
+        # a field name without colliding. `using:` imports are already composed into
+        # each step's `attribute_schema`.
+        def data_steps_spec
+          steps.reject(&:review?).each_with_object({}) do |step, acc|
+            acc[step.key.to_sym] = {
+              schema: step.attribute_schema,
+              options: step.attribute_options,
+              structured: step_structured_schema(step),
+              validations: step.validations + step.imported_form_validators
+            }
+          end
+        end
+
+        # The per-step typed sub-object classes ({step_key => Class}), built once
+        # per wizard class from {data_steps_spec} and reused for every `data`
+        # snapshot (the container is cheap to instantiate; the classes aren't).
+        def data_step_classes
+          @data_step_classes ||= data_steps_spec.transform_values do |spec|
+            Data.class_for(spec[:schema], options: spec[:options], structured: spec[:structured], validations: spec[:validations])
+          end
+        end
+
+        # Per-step typed classes carrying ONLY the step's INLINE `validates` (no
+        # imported form validators — those are validated separately via the
+        # transient model, so folding them in here would double-report). Built once
+        # per wizard class and reused by the runner's inline validation, which
+        # otherwise recompiles an equivalent anonymous class on every `validate`
+        # call (and `validate` runs many times per render). `{step_key => Class}`,
+        # omitting steps with no inline validations.
+        def inline_validation_classes
+          @inline_validation_classes ||= steps.reject(&:review?).each_with_object({}) do |step, acc|
+            next if step.validations.blank?
+            acc[step.key.to_sym] = Data.class_for(step.attribute_schema, validations: step.validations)
+          end
+        end
+
+        private
+
+        # One step's structured collections, as {name => [sub-field names]}, so
+        # `data.<step>.<name>` exposes typed sub-objects (§2.6 / §7.2).
+        def step_structured_schema(step)
+          step.structured_inputs.each_with_object({}) do |(name, entry), acc|
+            acc[name.to_sym] = structured_sub_fields(entry)
+          end
+        end
+
+        # Resolve the declared sub-field names of a structured_input entry by
+        # evaluating its block (or `using:` holder) against a FieldsDefinition.
+        def structured_sub_fields(entry)
+          options = entry[:options] || {}
+          return Array(options[:fields]).map(&:to_sym) if options[:fields]
+
+          holder =
+            if options[:using]
+              options[:using].is_a?(Class) ? options[:using].new : options[:using]
+            else
+              h = Plutonium::Definition::StructuredInputs::FieldsDefinition.new
+              entry[:block]&.call(h)
+              h
+            end
+          holder.defined_inputs.keys.map(&:to_sym)
+        end
+      end
+
+      # The step-keyed `data` snapshot (§2.6), reconstituted from the nested staged
+      # `data_attributes` ({step_key => {field => value}}). Addressed as
+      # `data.<step>.<field>`; `data[:step]` for dynamic access.
+      def data
+        @data ||= Data::Container.new(self.class.data_step_classes, data_attributes)
+      end
+
+      # The record this wizard was launched against (§3). Raises when the wizard
+      # was not declared `anchored` — never returns nil.
+      def anchor
+        unless self.class.anchored?
+          raise NotAnchoredError, "#{self.class} is not declared `anchored`"
+        end
+        @anchor
+      end
+
+      # Resolve this wizard's concurrency_key VALUE(S) in the wizard context
+      # (§4.2), with the tenant ALWAYS folded in (§4.4). Returns nil when no
+      # `concurrency_key` is declared (→ tokened identity). The returned value is
+      # an array `[*key_values, tenant_gid]`; {InstanceKey.concurrency} serializes
+      # it. The tenant is appended even when nil so the digest is stable.
+      def concurrency_key_value
+        resolver = self.class.concurrency_key_resolver
+        return nil unless resolver
+
+        key = instance_exec(&resolver)
+        [*Array.wrap(key), current_scoped_entity]
+      end
+
+      # The `{ "step_key" => [gids] }` source the runner injects from the stored
+      # state, backing the lazy `persisted` view. Reassigning it resets the memo.
+      def persisted_gid_source=(source)
+        @persisted = LazyPersisted.new(source)
+      end
+
+      # Records the per-step `on_submit`/`persist` macro registers (§2.2), as a
+      # LAZY view over the stored GIDs: a key is located on first read and
+      # memoized, so a request that never reads `persisted` issues zero locates
+      # (§4.5). Records set this request (the `persist` macro) are live already.
+      def persisted
+        @persisted ||= LazyPersisted.new
+      end
+
+      # The at-end commit hook (§2.3). Authors override it.
+      def execute
+        raise NotImplementedError, "#{self.class} must implement #execute"
+      end
+
+      # Entry authorization (§5.2/§6.5). Authors override it; false → 403. Default
+      # allow — resource-mounted surfaces additionally gate via the action policy.
+      def authorize? = true
+
+      private
+
+      # Raise a StepError from `on_submit`/`execute` (§6.1).
+      #
+      #   fail!("message")        → base (form-level) error
+      #   fail!(:field, "message") → field-level error
+      def fail!(attribute_or_message, message = nil)
+        if message.nil?
+          raise StepError.new(attribute_or_message, attribute: :base)
+        else
+          raise StepError.new(message, attribute: attribute_or_message)
+        end
+      end
+
+      # @return [Plutonium::Interaction::Outcome::Success]
+      def succeed(value = nil)
+        Plutonium::Interaction::Outcome::Success.new(value)
+      end
+      alias_method :success, :succeed
+
+      # @return [Plutonium::Interaction::Outcome::Failure]
+      def failed(errors = nil, attribute = :base)
+        case errors
+        when Hash
+          errors.each { |attr, error| self.errors.add(attr, error) }
+        else
+          Array(errors).each { |error| self.errors.add(attribute, error) }
+        end
+        Plutonium::Interaction::Outcome::Failure.new
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/base_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Convenience base for a standalone wizard controller that needs NO custom auth
+    # base: a plain `ActionController::Base` plus the wizard module. Use it when you
+    # want to drop in your own controller without an auth concern:
+    #
+    #   class WizardsController < Plutonium::Wizard::BaseController; end
+    #
+    # For an AUTHENTICATED standalone wizard, don't use this — inherit your own
+    # authenticated base and `include Plutonium::Wizard::Controller` instead, so the
+    # controller carries `current_user`:
+    #
+    #   class WizardsController < ApplicationController
+    #     include Plutonium::Wizard::Controller
+    #     include Plutonium::Auth::Rodauth(:user)
+    #   end
+    #
+    # The module is the mechanism; this class is only sugar.
+    class BaseController < ActionController::Base
+      # A bare `ActionController::Base` host normally inherits forgery protection
+      # from the app's `default_protect_from_forgery`, but make it explicit here so
+      # a standalone wizard mount is CSRF-protected regardless of app config (the
+      # wizard `update` is a state-changing POST).
+      protect_from_forgery with: :exception
+
+      include Plutonium::Wizard::Controller
+    end
+  end
+end

data/lib/plutonium/wizard/configuration.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Configuration for the Plutonium wizard subsystem.
+    #
+    # Exposed via {Plutonium::Configuration#wizards}.
+    class Configuration
+      # @return [Boolean] whether the wizard subsystem (and its migrations) is enabled
+      attr_accessor :enabled
+
+      # @return [ActiveSupport::Duration] how long completed/abandoned sessions are kept
+      attr_accessor :cleanup_after
+
+      # @return [Symbol] which database wizard tables live in
+      attr_accessor :database
+
+      # @return [Boolean] encrypt every wizard's staged `data` at rest by default.
+      #   Off by default because it needs ActiveRecord encryption keys configured;
+      #   a wizard may still opt in (`encrypt_data`) or out (`encrypt_data false`)
+      #   individually regardless of this default.
+      attr_accessor :encrypt_data
+
+      # @return [Symbol, nil] the storage backend used to SERVER-SIDE-stage a plain
+      #   (non-direct-upload) wizard attachment field — `:active_storage` or
+      #   `:shrine`. `nil` auto-detects (active_shrine loaded → `:shrine`, else
+      #   `:active_storage`). A field may override with `input …, backend:`. Only
+      #   relevant when a file rides the step POST; direct-upload fields already
+      #   arrive as a token and ignore this.
+      attr_accessor :attachment_backend
+
+      # Initialize a new wizard Configuration instance with default values.
+      def initialize
+        @enabled = false
+        @cleanup_after = 14.days
+        @database = :primary
+        @encrypt_data = false
+        @attachment_backend = nil
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/controller.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # The standalone portal-hosted controller concern for portal-level wizards
+    # registered with `register_wizard` (§5.2). It is mixed into a portal-
+    # namespaced controller (see {Plutonium::Routing::WizardRegistration}), so it
+    # inherits the portal's auth, tenant scoping entity, layout, and Phlex
+    # rendering exactly like a resource controller.
+    #
+    # All runner-driving logic lives in {Plutonium::Wizard::Driving} (shared with
+    # the resource-mounted {Plutonium::Resource::Controllers::WizardActions}). This
+    # concern only adapts that logic to the standalone surface: the `show`/`update`
+    # actions, the wizard class carried as a route default, no anchor (portal-level
+    # wizards are non-anchored — anchored wizards mount on the resource controller),
+    # and the per-step URL built from the named route helper `register_wizard` draws.
+    #
+    # Identity (§4): a guest (`anonymous`) run's per-run id lives in the Rails
+    # session, namespaced per wizard (no cookie, no TTL); it is cleared on
+    # completion and auto-cleared on login/logout (Rodauth `reset_session`). An
+    # authenticated repeatable run carries its per-run id in the URL `:token`
+    # segment, guarded by owner-scoping; neither crosses the auth boundary
+    # mid-flow (§4.5).
+    module Controller
+      extend ActiveSupport::Concern
+      # The complete include surface for a standalone wizard controller: the
+      # Plutonium rendering/scoping stack PLUS the wizard driving. Including this
+      # one module yields a fully renderable wizard controller, so the synthesizer
+      # and any app override (`class WizardsController < MyAuthBase; include
+      # Plutonium::Wizard::Controller; end`) both get everything. Re-including Core
+      # on a host that already has it (a portal controller) is a harmless no-op.
+      include Plutonium::Core::Controller
+      include Plutonium::Wizard::Driving
+
+      included do
+        helper_method :current_user
+      end
+
+      class_methods do
+        # The gem's shared partials (`plutonium/_flash`, …) are looked up by a
+        # "plutonium" view prefix, which normally comes from inheriting a controller
+        # whose `controller_path` is "plutonium" (the app's `PlutoniumController`). A
+        # bare host (a main-app / public wizard rooted in `ActionController::Base`)
+        # has no such ancestor, so contribute the prefix here — making the module
+        # self-sufficient and the "main-app can be bare" path actually work.
+        def _prefixes
+          @_wizard_view_prefixes ||= (super | ["plutonium"])
+        end
+      end
+
+      # GET the bare mount — resolve/mint the run and redirect to its step.
+      def launch
+        wizard_launch
+      end
+
+      # GET .../:step — render the current step.
+      def show
+        wizard_show
+      end
+
+      # POST .../:step — advance / back / cancel.
+      def update
+        wizard_update
+      end
+
+      private
+
+      # Identity for a standalone wizard host. Defers to the host's own auth
+      # concern when present — a portal controller's `Rodauth(:account)`, or an
+      # app-defined `::WizardsController`'s — and is `nil` on a bare host (a public
+      # mount, or a misconfigured authenticated main-app wizard with no auth
+      # controller). An `anonymous` wizard never consults this; a non-anonymous
+      # wizard on a bare host resolves `nil` and is rejected by
+      # `require_wizard_authentication!`.
+      def current_user
+        defined?(super) ? super : nil
+      end
+
+      # The wizard class is carried as a route default (see WizardRegistration),
+      # so it is a server-set path parameter. Resolve it through an ALLOWLIST of
+      # the loaded wizard classes rather than `constantize`-ing the raw value:
+      # every standalone wizard route is drawn by handing `register_wizard` the
+      # class object, so by the time its route matches the class is loaded and
+      # registered as a `Base` descendant. Matching by name can therefore only
+      # ever return an actual wizard — it never triggers resolution of an
+      # arbitrary constant (the `constantize`-on-params code-execution surface).
+      def current_wizard_class
+        @current_wizard_class ||= begin
+          name = params.fetch(:wizard_class).to_s
+          Plutonium::Wizard::Base.descendants.find { |klass| klass.name == name } ||
+            raise(Plutonium::Wizard::UnknownWizardError, "unknown wizard #{name.inspect}")
+        end
+      end
+
+      # Portal-level wizards are either non-anchored or CONTEXT-anchored
+      # (`anchored via: :method`, §3). A `with:`-only (TYPE) anchor mounts on the
+      # resource controller instead (see {WizardActions}), where the anchor is
+      # resolved through the scoped, policy-gated `resource_record!` — never an
+      # unscoped `find_by`, which would be a cross-tenant IDOR.
+      #
+      # For a CONTEXT anchor we call the declared method on this controller; a nil
+      # result is a programming error (the wizard declared itself anchored).
+      def resolved_wizard_anchor
+        klass = current_wizard_class
+        return nil unless klass.anchored_via?
+
+        record = send(klass.anchor_via)
+        if record.nil?
+          raise Plutonium::Wizard::NotAnchoredError,
+            "#{klass.name} resolves its anchor via `#{klass.anchor_via}`, which returned nil"
+        end
+        assert_anchor_type!(klass, record)
+        record
+      end
+
+      # When a CONTEXT anchor also declares `with:` types, type-assert the result.
+      def assert_anchor_type!(klass, record)
+        types = klass.anchor_types
+        return if types.nil?
+        return if types.any? { |t| record.is_a?(t) }
+
+        raise Plutonium::Wizard::NotAnchoredError,
+          "#{klass.name} anchor resolved to #{record.class} but expects one of " \
+          "#{types.join(", ")}"
+      end
+
+      # Build the GET URL for a given step of this wizard, preserving the
+      # `:token` segment. Built through the named route helper that
+      # `register_wizard` draws (resolved from the current engine's route set by
+      # the wizard class, so `at:`/`as:` overrides are honored) — never
+      # string-surgery on `request.path`, so the URL is always a same-host,
+      # route-validated path.
+      def wizard_step_url(step_key)
+        url_options = {step: step_key}
+        token = wizard_url_token
+        url_options[:token] = token if token.present?
+        # An entity-scoped portal's wizard routes carry the scope path segment
+        # (e.g. `:organization_scoped`); thread it through from the request so the
+        # generated URL stays inside the tenant.
+        if scoped_to_entity?
+          url_options[scoped_entity_param_key] = params[scoped_entity_param_key]
+        end
+        current_engine.routes.url_helpers.public_send(wizard_step_url_helper, **url_options)
+      end
+
+      # The `<name>_wizard_path` helper for this wizard's standalone mount. Found
+      # by the GET route `register_wizard` draws (named `:"#{helper}_wizard"`,
+      # carrying the `wizard_class` route default) so the lookup tracks the actual
+      # `at:`/`as:` used at registration rather than re-deriving a slug.
+      def wizard_step_url_helper
+        @wizard_step_url_helper ||= begin
+          name = Plutonium::Wizard::RouteResolution.route_name(
+            current_engine.routes, current_wizard_class, action: "show"
+          )
+          raise "no register_wizard route found for #{current_wizard_class.name}" unless name
+
+          :"#{name}_path"
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/data.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Builds the wizard's typed `data` snapshot (§2.6). `data` is **step-keyed**: a
+    # container exposing one typed sub-object per step, so fields are addressed as
+    # `data.<step>.<field>` (e.g. `data.identity.name`, `data.profile.tier`). Each
+    # step sub-object is backed by ActiveModel::Attributes — scalar values are cast
+    # to their declared types and uncollected fields read as `nil`. Step namespacing
+    # means two steps may declare the same field name without colliding.
+    #
+    # `structured_input ..., repeat:` collections (which declare no scalar types —
+    # their sub-fields come from `input` declarations) are exposed on their step's
+    # sub-object as arrays of typed sub-objects responding to the declared sub-field
+    # names (`data.members.invites.first.email`).
+    module Data
+      # A read-only row inside a structured collection. Responds to each declared
+      # sub-field; values are exposed as-is (string-typed, since structured inputs
+      # carry no scalar type declarations).
+      class StructuredRow
+        def initialize(fields, values)
+          @values = values
+          fields.each do |field|
+            define_singleton_method(field) { @values[field.to_s] }
+          end
+        end
+
+        def [](key) = @values[key.to_s]
+
+        def to_h = @values.dup
+      end
+
+      # @param schema [Hash{Symbol=>Symbol}] scalar attribute name => type
+      # @param options [Hash{Symbol=>Hash}] scalar attribute name => options (default:, etc.)
+      # @param structured [Hash{Symbol=>Array<Symbol>}] structured name => sub-field names
+      # @param validations [Array<[Array, Hash]>] inline `validates` declarations
+      #   ([args, options]) replayed onto the class so the form pipeline can infer
+      #   required markers via `validators_on` (§7). The class is never `.valid?`'d
+      #   in the form path — validation runs through the runner — so this only
+      #   feeds introspection.
+      def self.class_for(schema, options: {}, structured: {}, validations: [])
+        Class.new do
+          include ActiveModel::Model
+          include ActiveModel::Attributes
+
+          # Anonymous classes have no name, which breaks label/error translation
+          # lookups (`human_attribute_name` / `errors.full_messages` call
+          # `model_name`). Supply a stable one so the form/display pipelines can
+          # humanize attribute labels.
+          def self.model_name = ActiveModel::Name.new(self, nil, "Wizard")
+
+          schema.each do |name, type|
+            attribute(name, Plutonium::Wizard.safe_attribute_type(type), **(options[name] || {}))
+          end
+
+          validations.each { |args, opts| validates(*args, **opts) }
+
+          structured.each do |name, fields|
+            # Backed by a plain accessor (not an ActiveModel attribute) so the raw
+            # array survives without coercion, then wrapped on read.
+            attr_writer name
+            define_method(name) do
+              rows = Array(instance_variable_get(:"@#{name}"))
+              rows.map do |row|
+                values = row.respond_to?(:to_h) ? row.to_h.transform_keys(&:to_s) : {}
+                StructuredRow.new(fields, values)
+              end
+            end
+          end
+
+          # Accept the union of scalar + structured keys, ignoring unknown keys.
+          define_method(:initialize) do |attrs = {}|
+            attrs = (attrs || {}).symbolize_keys
+            scalar = attrs.slice(*schema.keys)
+            super(scalar)
+            structured.each_key do |name|
+              instance_variable_set(:"@#{name}", attrs[name] || [])
+            end
+          end
+
+          # Typed plain-hash view: cast scalars + structured rows as hashes.
+          define_method(:to_h) do
+            h = {}
+            schema.each_key { |name| h[name] = public_send(name) }
+            structured.each_key { |name| h[name] = public_send(name).map(&:to_h) }
+            h
+          end
+        end
+      end
+
+      # The step-keyed `data` snapshot — a thin dispatcher over the per-step typed
+      # sub-objects (§2.6). `data.identity` (via method_missing) or `data[:identity]`
+      # returns the step's typed sub-object, built lazily from its nested data slice
+      # and memoized; an unknown step key returns nil. `to_h` gives the nested
+      # `{step => {field => value}}` view.
+      #
+      # A plain object (not a generated class) so it isn't rebuilt every time the
+      # runner reassigns `data_attributes`; the per-step typed classes are built
+      # once per wizard class and passed in.
+      class Container
+        # @param step_classes [Hash{Symbol=>Class}] step key => typed sub-object class
+        # @param attrs [Hash] nested staged data ({step_key => {field => value}})
+        def initialize(step_classes, attrs = {})
+          @step_classes = step_classes
+          @attrs = (attrs || {}).transform_keys(&:to_sym)
+          @objects = {}
+        end
+
+        # The typed sub-object for a step (lazy + memoized); nil for an unknown step.
+        def [](key)
+          key = key.to_sym
+          return nil unless @step_classes.key?(key)
+          @objects[key] ||= @step_classes[key].new(@attrs[key] || {})
+        end
+
+        # The declared step keys, in order.
+        def step_keys = @step_classes.keys
+
+        # Nested typed hash: {step_key => {field => value}}.
+        def to_h = @step_classes.keys.index_with { |key| self[key].to_h }
+
+        def respond_to_missing?(name, include_private = false)
+          @step_classes.key?(name.to_sym) || super
+        end
+
+        # `data.identity` → the identity step's typed sub-object.
+        def method_missing(name, *args)
+          return self[name] if args.empty? && @step_classes.key?(name.to_sym)
+          super
+        end
+      end
+    end
+  end
+end