igniter 0.5.0 → 0.5.2

data/packages/igniter-web/lib/igniter/web/composition_finding.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Web
+    CompositionFinding = Struct.new(:severity, :code, :message, :suggestions, keyword_init: true) do
+      def to_h
+        {
+          severity: severity,
+          code: code,
+          message: message,
+          suggestions: suggestions || []
+        }
+      end
+    end
+  end
+end

data/packages/igniter-web/lib/igniter/web/composition_policy.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Web
+    class CompositionPolicy
+      def findings_for(screen, preset: CompositionPreset.default)
+        findings = []
+        findings.concat(preset_findings(screen, preset))
+        findings.concat(intent_findings(screen))
+        findings.concat(action_findings(screen))
+        findings
+      end
+
+      private
+
+      def preset_findings(screen, preset)
+        return [] unless preset.policy_hints[:requires_action]
+        return [] if screen.elements.any? { |element| element.kind == :action }
+
+        [finding(
+          :error,
+          :missing_preset_action,
+          "#{screen.name} uses #{preset.name} but has no action.",
+          ["add an action", "choose a less action-oriented preset"]
+        )]
+      end
+
+      def intent_findings(screen)
+        case screen.intent
+        when :human_decision
+          return [] if screen.elements.any? { |element| element.kind == :action }
+
+          [finding(
+            :error,
+            :missing_primary_action,
+            "#{screen.name} declares human decision intent but has no action.",
+            ["add an action", "mark the screen read-only"]
+          )]
+        when :collect_input
+          return [] if screen.elements.any? { |element| element.kind == :ask }
+
+          [finding(
+            :error,
+            :missing_input,
+            "#{screen.name} declares input collection intent but has no input.",
+            ["add ask :field_name", "use a different intent"]
+          )]
+        when :live_process
+          live_kinds = %i[stream chat need]
+          return [] if screen.elements.any? { |element| live_kinds.include?(element.kind) }
+
+          [finding(
+            :warning,
+            :missing_live_surface,
+            "#{screen.name} declares live process intent but has no stream, chat, or live need.",
+            ["add stream :events", "add chat with: Agent", "add need :progress"]
+          )]
+        else
+          []
+        end
+      end
+
+      def action_findings(screen)
+        screen.elements.filter_map do |element|
+          next unless element.kind == :action
+          next unless element.options.fetch(:destructive, false)
+          next if element.options[:confirm]
+
+          finding(
+            :warning,
+            :missing_confirmation,
+            "#{screen.name}.#{element.name} is destructive but has no confirmation metadata.",
+            ["add confirm: \"...\""]
+          )
+        end
+      end
+
+      def finding(severity, code, message, suggestions)
+        CompositionFinding.new(
+          severity: severity,
+          code: code,
+          message: message,
+          suggestions: suggestions
+        )
+      end
+    end
+  end
+end

data/packages/igniter-web/lib/igniter/web/composition_preset.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Web
+    class CompositionPreset
+      DEFAULT_ZONE_ORDER = %i[summary main aside footer].freeze
+
+      PRESETS = {
+        decision_workspace: {
+          intent: :human_decision,
+          zone_order: DEFAULT_ZONE_ORDER,
+          preferred_zones: {
+            subject: :summary,
+            show: :main,
+            compare: :main,
+            chat: :aside,
+            actor: :aside,
+            action: :footer
+          },
+          policy_hints: {
+            requires_action: true,
+            prefers_aside_companion: true
+          }
+        },
+        operator_console: {
+          intent: :live_process,
+          zone_order: %i[summary main aside footer],
+          preferred_zones: {
+            subject: :summary,
+            need: :summary,
+            stream: :main,
+            show: :main,
+            compare: :main,
+            chat: :aside,
+            actor: :aside,
+            action: :footer
+          },
+          policy_hints: {
+            prefers_live_surface: true,
+            supports_agent_companion: true
+          }
+        },
+        wizard_operator_surface: {
+          intent: :guided_process,
+          zone_order: %i[summary main footer aside],
+          preferred_zones: {
+            subject: :summary,
+            ask: :main,
+            show: :main,
+            compare: :main,
+            stream: :aside,
+            chat: :aside,
+            actor: :aside,
+            action: :footer
+          },
+          policy_hints: {
+            step_first: true,
+            prefers_footer_actions: true
+          }
+        },
+        live_process: {
+          intent: :live_process,
+          zone_order: DEFAULT_ZONE_ORDER,
+          preferred_zones: {
+            subject: :summary,
+            need: :summary,
+            stream: :main,
+            show: :main,
+            chat: :aside,
+            actor: :aside,
+            action: :footer
+          },
+          policy_hints: {
+            prefers_live_surface: true
+          }
+        }
+      }.freeze
+
+      class << self
+        def fetch(name)
+          key = (name || :default).to_sym
+          return default if key == :default
+
+          config = PRESETS.fetch(key) do
+            raise ArgumentError, "unknown composition preset: #{name.inspect}"
+          end
+
+          new(name: key, **config)
+        end
+
+        def default
+          new(
+            name: :default,
+            intent: nil,
+            zone_order: DEFAULT_ZONE_ORDER,
+            preferred_zones: {},
+            policy_hints: {}
+          )
+        end
+
+        def names
+          PRESETS.keys
+        end
+      end
+
+      attr_reader :name, :intent, :zone_order, :preferred_zones, :policy_hints
+
+      def initialize(name:, intent:, zone_order:, preferred_zones:, policy_hints:)
+        @name = name.to_sym
+        @intent = intent&.to_sym
+        @zone_order = zone_order.map(&:to_sym).freeze
+        @preferred_zones = preferred_zones.transform_keys(&:to_sym).transform_values(&:to_sym).freeze
+        @policy_hints = policy_hints.freeze
+      end
+
+      def preferred_zone_for(kind)
+        preferred_zones[kind.to_sym]
+      end
+
+      def to_h
+        {
+          name: name,
+          intent: intent,
+          zone_order: zone_order,
+          preferred_zones: preferred_zones,
+          policy_hints: policy_hints
+        }.compact
+      end
+    end
+  end
+end

data/packages/igniter-web/lib/igniter/web/composition_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Web
+    class CompositionResult
+      attr_reader :screen, :graph, :findings
+
+      def initialize(screen:, graph:, findings: [])
+        @screen = screen
+        @graph = graph
+        @findings = findings.freeze
+      end
+
+      def success?
+        findings.none? { |finding| finding.severity == :error }
+      end
+
+      def to_h
+        {
+          screen: screen.to_h,
+          graph: graph.to_h,
+          findings: findings.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/packages/igniter-web/lib/igniter/web/flow_interaction_adapter.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Web
+    class FlowInteractionAdapter
+      EMPTY_INTERACTIONS = {
+        pending_inputs: [],
+        pending_actions: [],
+        streams: [],
+        chats: []
+      }.freeze
+
+      attr_reader :interactions, :current_step, :metadata
+
+      def self.pending_state(source, current_step: nil, metadata: {})
+        new(source, current_step: current_step, metadata: metadata).pending_state
+      end
+
+      def initialize(source, current_step: nil, metadata: {})
+        @interactions = normalize_interactions(source)
+        @current_step = current_step&.to_sym
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def pending_state
+        {
+          pending_inputs: pending_inputs,
+          pending_actions: pending_actions
+        }
+      end
+
+      def pending_inputs
+        interactions.fetch(:pending_inputs).map { |entry| pending_input(entry) }.freeze
+      end
+
+      def pending_actions
+        interactions.fetch(:pending_actions).map { |entry| pending_action(entry) }.freeze
+      end
+
+      private
+
+      def normalize_interactions(source)
+        raw = if source.respond_to?(:interactions)
+                source.interactions
+              elsif source.respond_to?(:to_h) && source.to_h.key?(:interactions)
+                source.to_h.fetch(:interactions)
+              else
+                source
+              end
+
+        EMPTY_INTERACTIONS.merge(raw || {}).transform_values { |entries| Array(entries).map(&:dup).freeze }.freeze
+      end
+
+      def pending_input(entry)
+        {
+          name: entry.fetch(:name),
+          input_type: entry.fetch(:input_type, :text),
+          required: entry.fetch(:required, true),
+          target: pending_input_target(entry),
+          schema: entry.fetch(:schema, {}),
+          metadata: adapter_metadata(entry)
+        }
+      end
+
+      def pending_action(entry)
+        {
+          name: entry.fetch(:name),
+          action_type: entry.fetch(:action_type, :command),
+          target: action_target(entry[:target]),
+          payload_schema: entry.fetch(:payload_schema, {}),
+          metadata: adapter_metadata(entry)
+        }
+      end
+
+      def pending_input_target(entry)
+        current_step || simple_symbol(entry[:target]) || entry.dig(:source, :screen)
+      end
+
+      def action_target(value)
+        return nil if value.nil?
+        return value.fetch(:name).to_s if value.is_a?(Hash) && value.key?(:name)
+
+        value.to_s
+      end
+
+      def simple_symbol(value)
+        return value if value.is_a?(Symbol)
+        return value.to_sym if value.is_a?(String) && value.match?(/\A[a-z_][a-zA-Z0-9_]*\z/)
+
+        nil
+      end
+
+      def adapter_metadata(entry)
+        metadata.merge(
+          source: entry[:source],
+          role: entry[:role],
+          purpose: entry[:purpose],
+          web_interaction: entry
+        ).compact
+      end
+    end
+  end
+end

data/packages/igniter-web/lib/igniter/web/flow_surface_projection.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Web
+    class FlowSurfaceProjection
+      attr_reader :surface, :declaration, :feature, :metadata
+
+      def self.project(surface, declaration:, feature: nil, metadata: {})
+        new(surface: surface, declaration: declaration, feature: feature, metadata: metadata).to_h
+      end
+
+      def initialize(surface:, declaration:, feature: nil, metadata: {})
+        @surface = normalize_surface(surface)
+        @declaration = normalize_hash(declaration)
+        @feature = feature.nil? ? nil : normalize_hash(feature)
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def to_h
+        {
+          status: status,
+          surface: surface_identity,
+          flow: flow_identity,
+          feature: feature_identity,
+          pending_inputs: comparison(:pending_inputs),
+          pending_actions: comparison(:pending_actions),
+          relationships: relationships,
+          metadata: metadata.dup
+        }.compact
+      end
+
+      private
+
+      def normalize_surface(value)
+        return value.to_h if value.respond_to?(:to_h)
+
+        normalize_hash(value)
+      end
+
+      def normalize_hash(value)
+        value.to_h.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+      end
+
+      def surface_identity
+        {
+          name: surface[:name],
+          path: surface[:path]
+        }.compact
+      end
+
+      def flow_identity
+        {
+          name: declaration[:name],
+          initial_status: declaration[:initial_status],
+          current_step: declaration[:current_step],
+          purpose: declaration[:purpose]
+        }.compact
+      end
+
+      def feature_identity
+        return nil if feature.nil?
+
+        {
+          name: feature[:name],
+          flows: Array(feature[:flows]),
+          surfaces: Array(feature[:surfaces])
+        }
+      end
+
+      def comparison(kind)
+        surface_names = names_from(surface_interactions(kind))
+        declaration_names = names_from(Array(declaration[kind]))
+
+        {
+          surface: surface_names,
+          declaration: declaration_names,
+          matched: surface_names & declaration_names,
+          missing_in_surface: declaration_names - surface_names,
+          extra_in_surface: surface_names - declaration_names
+        }
+      end
+
+      def surface_interactions(kind)
+        interactions = normalize_hash(surface.fetch(:interactions, {}))
+        Array(interactions[kind])
+      end
+
+      def names_from(entries)
+        entries.map do |entry|
+          source = entry.respond_to?(:to_h) ? entry.to_h : entry
+          source.fetch(:name).to_sym
+        end
+      end
+
+      def relationships
+        {
+          declaration_references_surface: references?(declaration[:surfaces], surface[:name]),
+          feature_references_surface: feature && references?(feature[:surfaces], surface[:name]),
+          feature_references_flow: feature && references?(feature[:flows], declaration[:name])
+        }.compact
+      end
+
+      def references?(entries, name)
+        return false if name.nil?
+
+        Array(entries).map(&:to_sym).include?(name.to_sym)
+      end
+
+      def status
+        input_comparison = comparison(:pending_inputs)
+        action_comparison = comparison(:pending_actions)
+        aligned = input_comparison.fetch(:missing_in_surface).empty? &&
+                  action_comparison.fetch(:missing_in_surface).empty? &&
+                  relationships.fetch(:declaration_references_surface, false)
+
+        aligned ? :aligned : :attention
+      end
+    end
+  end
+end

data/packages/igniter-web/lib/igniter/web/interaction_target.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Web
+    class InteractionTarget
+      class << self
+        def contract(name)
+          new(kind: :contract, name: name)
+        end
+
+        def service(name)
+          new(kind: :service, name: name)
+        end
+
+        def projection(name)
+          new(kind: :projection, name: name)
+        end
+      end
+
+      attr_reader :kind, :name, :metadata
+
+      def initialize(kind:, name:, metadata: {})
+        @kind = kind.to_sym
+        @name = name.to_s
+        @metadata = metadata.freeze
+      end
+
+      def to_h
+        {
+          kind: kind,
+          name: name,
+          metadata: metadata
+        }
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        [kind, name, metadata].hash
+      end
+
+      def to_s
+        "#{kind}:#{name}"
+      end
+    end
+  end
+end

data/packages/igniter-web/lib/igniter/web/mount_context.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Web
+    class MountContext
+      attr_reader :mount, :application, :env
+
+      def initialize(mount:, application: nil, env: {})
+        @mount = mount
+        @application = application
+        @env = env.freeze
+      end
+
+      def name
+        mount.name
+      end
+
+      def path
+        mount.path
+      end
+
+      def metadata
+        mount.metadata
+      end
+
+      def route(suffix = "")
+        normalized_suffix = normalize_suffix(suffix)
+        return path if normalized_suffix == "/"
+        return normalized_suffix if path == "/"
+
+        "#{path}#{normalized_suffix}"
+      end
+
+      def manifest
+        application&.manifest
+      end
+
+      def layout
+        application&.layout
+      end
+
+      def service(name)
+        application&.service(name)
+      end
+
+      def interface(name)
+        application&.interface(name)
+      end
+
+      def mount_registration
+        return nil unless application.respond_to?(:mount?)
+        return nil unless application.mount?(name)
+
+        application.mount(name)
+      end
+
+      def capabilities
+        mount_registration&.capabilities || []
+      end
+
+      def to_h
+        {
+          mount: mount.to_h,
+          application: manifest&.to_h,
+          metadata: metadata,
+          capabilities: capabilities,
+          path: path
+        }.compact
+      end
+
+      private
+
+      def normalize_suffix(value)
+        suffix = value.to_s
+        suffix = "/#{suffix}" unless suffix.start_with?("/")
+        suffix
+      end
+    end
+  end
+end