igniter-extensions 0.5.2

data/lib/igniter/extensions/contracts/creator/wizard.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Creator
+        class Wizard
+          PROFILE_EXAMPLES = {
+            feature_node: ["examples/contracts/build_your_own_pack.rb"],
+            diagnostic_bundle: ["examples/contracts/debug.rb", "examples/contracts/debug_pack_authoring.rb"],
+            operational_adapter: ["examples/contracts/build_effect_executor_pack.rb", "examples/contracts/journal.rb"],
+            bundle_pack: ["examples/contracts/compose_your_own_packs.rb", "examples/contracts/commerce.rb"]
+          }.freeze
+
+          attr_reader :name, :kind, :namespace, :profile, :capabilities, :scope, :root, :mode, :pack, :target_profile
+
+          def initialize(name: nil, kind: nil, namespace: "MyCompany::IgniterPacks", profile: nil, capabilities: nil,
+                         scope: nil, root: nil, mode: :skip_existing, pack: nil, target_profile: nil)
+            @name = normalize_name(name)
+            @kind = kind&.to_sym
+            @namespace = normalize_namespace(namespace)
+            @profile = profile&.to_sym
+            @capabilities = Array(capabilities).map(&:to_sym).uniq.freeze
+            @scope = scope&.to_sym
+            @root = root&.to_s
+            @mode = mode.to_sym
+            @pack = pack
+            @target_profile = target_profile
+            freeze
+          end
+
+          def apply(**updates)
+            self.class.new(
+              name: updates.fetch(:name, name),
+              kind: updates.fetch(:kind, kind),
+              namespace: updates.fetch(:namespace, namespace),
+              profile: updates.fetch(:profile, profile),
+              capabilities: updates.fetch(:capabilities, capabilities),
+              scope: updates.fetch(:scope, scope),
+              root: updates.fetch(:root, root),
+              mode: updates.fetch(:mode, mode),
+              pack: updates.fetch(:pack, pack),
+              target_profile: updates.fetch(:target_profile, target_profile)
+            )
+          end
+
+          def authoring_profile
+            return nil unless profile || kind || !capabilities.empty?
+
+            Profile.build(
+              profile: profile,
+              kind: kind,
+              capabilities: capabilities
+            )
+          end
+
+          def target_scope
+            return nil unless scope
+
+            Scope.build(scope)
+          end
+
+          def ready_for_workflow?
+            !name.nil? && !authoring_profile.nil? && !target_scope.nil?
+          end
+
+          def ready_for_writer?
+            ready_for_workflow? && !effective_root.nil?
+          end
+
+          def effective_root
+            return root unless root.nil? || root.empty?
+            return nil unless scope
+
+            suggested_root
+          end
+
+          def suggested_root
+            case scope
+            when :standalone_gem
+              name ? "./#{name}" : "./my_pack"
+            when :app_local, :monorepo_package
+              "."
+            end
+          end
+
+          def pending_decisions
+            decisions = []
+            unless name
+              decisions << {
+                key: :name,
+                prompt: "Choose a short pack name",
+                options: [],
+                hints: ["pick the public noun you want pack users to reach for"]
+              }
+            end
+
+            unless authoring_profile
+              decisions << {
+                key: :profile,
+                prompt: "Choose an authoring profile or provide capabilities",
+                options: profile_options,
+                hints: ["feature packs add graph semantics; operational packs add effect/executor behavior; bundles compose packs without semantic mutation"]
+              }
+            end
+
+            unless target_scope
+              decisions << {
+                key: :scope,
+                prompt: "Choose the target scope for the pack",
+                options: scope_options,
+                hints: branching_hints
+              }
+            end
+
+            if ready_for_workflow? && root.nil?
+              decisions << {
+                key: :root,
+                prompt: "Choose the filesystem root for generated files",
+                options: [suggested_root].compact,
+                hints: ["default root follows the chosen scope; override it only if the host repo layout needs it"]
+              }
+            end
+
+            decisions
+          end
+
+          def current_decision
+            pending_decisions.first
+          end
+
+          def recommended_packs
+            return { runtime: [], development: [] } unless authoring_profile
+
+            {
+              runtime: authoring_profile.runtime_dependency_hints,
+              development: authoring_profile.development_dependency_hints
+            }
+          end
+
+          def recommended_examples
+            return [] unless authoring_profile
+
+            PROFILE_EXAMPLES.fetch(authoring_profile.name, PROFILE_EXAMPLES.fetch(fallback_profile_name, []))
+          end
+
+          def branching_hints
+            return [] unless authoring_profile
+
+            hints = []
+            case authoring_profile.kind
+            when :operational
+              hints << "operational adapters usually want dev-time help from Igniter::Extensions::Contracts::JournalPack"
+              hints << "prefer standalone_gem when the adapter will be reused across hosts"
+            when :bundle
+              if authoring_profile.capability?(:diagnostic)
+                hints << "diagnostic bundles usually compose Igniter::Extensions::Contracts::ExecutionReportPack and Igniter::Extensions::Contracts::ProvenancePack"
+                hints << "keep DebugPack as a development helper unless the bundle truly needs a runtime-facing debug surface"
+              else
+                hints << "bundle packs should stay thin and explicit about which packs they compose"
+              end
+            when :feature
+              hints << "feature node packs often start app-local before being promoted into a monorepo package or gem"
+            end
+
+            hints.concat(authoring_profile.development_hints)
+            hints.uniq
+          end
+
+          def workflow
+            unless ready_for_workflow?
+              raise ArgumentError, "creator wizard is missing decisions: #{pending_decisions.map do |decision|
+                decision.fetch(:key)
+              end.join(", ")}"
+            end
+
+            CreatorPack.workflow(
+              name: name,
+              kind: kind,
+              namespace: namespace,
+              profile: profile,
+              capabilities: capabilities,
+              scope: scope,
+              pack: pack,
+              target_profile: target_profile
+            )
+          end
+
+          def writer
+            raise ArgumentError, "creator wizard needs a root before writing scaffold files" unless ready_for_writer?
+
+            workflow.writer(root: effective_root, mode: mode)
+          end
+
+          def to_h
+            {
+              name: name,
+              kind: kind,
+              namespace: namespace,
+              profile: profile,
+              capabilities: capabilities,
+              scope: scope,
+              root: root,
+              suggested_root: suggested_root,
+              effective_root: effective_root,
+              mode: mode,
+              ready_for_workflow: ready_for_workflow?,
+              ready_for_writer: ready_for_writer?,
+              authoring_profile: authoring_profile&.to_h,
+              target_scope: target_scope&.to_h,
+              recommended_packs: recommended_packs,
+              recommended_examples: recommended_examples,
+              branching_hints: branching_hints,
+              pending_decisions: pending_decisions
+            }
+          end
+
+          private
+
+          def fallback_profile_name
+            case authoring_profile&.kind
+            when :operational
+              :operational_adapter
+            when :bundle
+              authoring_profile&.capability?(:diagnostic) ? :diagnostic_bundle : :bundle_pack
+            else
+              :feature_node
+            end
+          end
+
+          def profile_options
+            Profile.available.map do |available_profile|
+              built = Profile.build(profile: available_profile)
+              {
+                key: available_profile,
+                kind: built.kind,
+                summary: built.summary,
+                capabilities: built.capabilities
+              }
+            end
+          end
+
+          def scope_options
+            Scope.available.map do |available_scope|
+              built = Scope.build(available_scope)
+              {
+                key: available_scope,
+                root: built.root,
+                summary: built.packaging_hints.first
+              }
+            end
+          end
+
+          def normalize_name(value)
+            return nil if value.nil?
+
+            normalized = value.to_s.strip.gsub(/_pack\z/, "").downcase
+            normalized.empty? ? nil : normalized
+          end
+
+          def normalize_namespace(value)
+            normalized = value.to_s.strip
+            normalized.empty? ? "MyCompany::IgniterPacks" : normalized
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/creator/workflow.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require_relative "workflow_step"
+require_relative "writer"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Creator
+        class Workflow
+          attr_reader :report
+
+          def initialize(report:)
+            @report = report
+            freeze
+          end
+
+          def scaffold
+            report.scaffold
+          end
+
+          def audit
+            report.audit
+          end
+
+          def profile
+            scaffold.profile
+          end
+
+          def scope
+            scaffold.scope
+          end
+
+          def recommended_packs
+            {
+              runtime: profile.runtime_dependency_hints,
+              development: profile.development_dependency_hints
+            }
+          end
+
+          def stages
+            [
+              design_stage,
+              scaffold_stage,
+              implementation_stage,
+              validation_stage,
+              packaging_stage
+            ]
+          end
+
+          def current_stage
+            stages.find { |stage| !stage.complete? } || stages.last
+          end
+
+          def ready_for_packaging?
+            packaging_stage.status == :ready
+          end
+
+          def writer(root:, mode: :skip_existing)
+            Writer.new(workflow: self, root: root, mode: mode)
+          end
+
+          def to_h
+            {
+              scaffold: scaffold.to_h,
+              report: report.to_h,
+              recommended_packs: recommended_packs,
+              current_stage: current_stage.to_h,
+              ready_for_packaging: ready_for_packaging?,
+              stages: stages.map(&:to_h)
+            }
+          end
+
+          private
+
+          def design_stage
+            hints = []
+            hints << "runtime pack recommendations: #{profile.runtime_dependency_hints.join(", ")}" unless profile.runtime_dependency_hints.empty?
+            hints << "development pack recommendations: #{profile.development_dependency_hints.join(", ")}" unless profile.development_dependency_hints.empty?
+
+            WorkflowStep.new(
+              key: :select_profile,
+              status: :complete,
+              title: "Select Authoring Profile",
+              summary: "#{profile.name} -> #{profile.summary}; target scope #{scope.name}",
+              hints: hints
+            )
+          end
+
+          def scaffold_stage
+            WorkflowStep.new(
+              key: :generate_scaffold,
+              status: :complete,
+              title: "Generate Scaffold",
+              summary: "generated #{scaffold.files.size} files rooted at #{scaffold.pack_file_path}",
+              hints: scaffold.files.keys
+            )
+          end
+
+          def implementation_stage
+            if audit&.ok?
+              WorkflowStep.new(
+                key: :implement_pack,
+                status: :complete,
+                title: "Implement Pack",
+                summary: "#{scaffold.pack_constant} satisfies the current install/finalize seam checks"
+              )
+            elsif audit
+              WorkflowStep.new(
+                key: :implement_pack,
+                status: :needs_attention,
+                title: "Implement Pack",
+                summary: "fill the missing pack seams in #{scaffold.pack_file_path}",
+                hints: implementation_hints
+              )
+            else
+              WorkflowStep.new(
+                key: :implement_pack,
+                status: :ready,
+                title: "Implement Pack",
+                summary: "fill in #{scaffold.pack_file_path} and keep the pack on public contracts only",
+                hints: report.next_steps
+              )
+            end
+          end
+
+          def validation_stage
+            if audit&.ok?
+              WorkflowStep.new(
+                key: :validate_pack,
+                status: :complete,
+                title: "Validate Pack",
+                summary: "audit passed; the pack finalizes cleanly against the current contracts profile"
+              )
+            elsif audit
+              WorkflowStep.new(
+                key: :validate_pack,
+                status: :needs_attention,
+                title: "Validate Pack",
+                summary: "audit_pack found missing seams before finalize",
+                hints: [audit.explain]
+              )
+            else
+              WorkflowStep.new(
+                key: :validate_pack,
+                status: :ready,
+                title: "Validate Pack",
+                summary: "run audit_pack once the implementation is in place",
+                hints: ["Igniter::Extensions::Contracts.audit_pack(#{scaffold.pack_constant}, environment)"]
+              )
+            end
+          end
+
+          def packaging_stage
+            if audit&.ok?
+              WorkflowStep.new(
+                key: :package_pack,
+                status: :ready,
+                title: "Package Pack",
+                summary: "the pack is ready for #{scope.name} packaging review",
+                hints: scope.packaging_hints
+              )
+            else
+              WorkflowStep.new(
+                key: :package_pack,
+                status: :pending,
+                title: "Package Pack",
+                summary: "finish implementation and validation before packaging for #{scope.name}",
+                hints: scope.packaging_hints
+              )
+            end
+          end
+
+          def implementation_hints
+            hints = []
+            hints << "define node kinds: #{audit.missing_node_definitions.join(", ")}" unless audit.missing_node_definitions.empty?
+            hints << "register DSL keywords: #{audit.missing_dsl_keywords.join(", ")}" unless audit.missing_dsl_keywords.empty?
+            hints << "register runtime handlers: #{audit.missing_runtime_handlers.join(", ")}" unless audit.missing_runtime_handlers.empty?
+            audit.missing_registry_contracts.each do |registry, keys|
+              hints << "register #{registry}: #{keys.join(", ")}"
+            end
+            hints << "resolve finalize error: #{audit.finalize_error}" if audit.finalize_error
+            hints
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/creator/workflow_step.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Creator
+        class WorkflowStep
+          VALID_STATUSES = %i[complete ready needs_attention pending].freeze
+
+          attr_reader :key, :status, :title, :summary, :hints
+
+          def initialize(key:, status:, title:, summary:, hints: [])
+            @key = key.to_sym
+            @status = normalize_status(status)
+            @title = title
+            @summary = summary
+            @hints = Array(hints).map(&:to_s).uniq.freeze
+            freeze
+          end
+
+          def complete?
+            status == :complete
+          end
+
+          def actionable?
+            %i[ready needs_attention].include?(status)
+          end
+
+          def to_h
+            {
+              key: key,
+              status: status,
+              title: title,
+              summary: summary,
+              hints: hints
+            }
+          end
+
+          private
+
+          def normalize_status(status)
+            value = status.to_sym
+            return value if VALID_STATUSES.include?(value)
+
+            raise ArgumentError, "unsupported creator workflow step status #{status.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/creator/write_result.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Creator
+        class WriteResult
+          attr_reader :root, :mode, :steps
+
+          def initialize(root:, mode:, steps:)
+            @root = root
+            @mode = mode.to_sym
+            @steps = steps.freeze
+            freeze
+          end
+
+          def files_written
+            steps.count { |step| step.kind == :file && %i[written unchanged].include?(step.status) }
+          end
+
+          def files_skipped
+            steps.count { |step| step.kind == :file && step.status == :skipped }
+          end
+
+          def directories_created
+            steps.count { |step| step.kind == :directory && step.status == :created }
+          end
+
+          def success?
+            steps.none?(&:actionable?)
+          end
+
+          def to_h
+            {
+              root: root,
+              mode: mode,
+              files_written: files_written,
+              files_skipped: files_skipped,
+              directories_created: directories_created,
+              success: success?,
+              steps: steps.map(&:to_h)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/creator/write_step.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Creator
+        class WriteStep
+          VALID_KINDS = %i[directory file].freeze
+          VALID_STATUSES = %i[pending created written skipped unchanged].freeze
+
+          attr_reader :kind, :relative_path, :absolute_path, :status, :reason
+
+          def initialize(kind:, relative_path:, absolute_path:, status:, reason: nil)
+            @kind = normalize_kind(kind)
+            @relative_path = relative_path.to_s
+            @absolute_path = absolute_path.to_s
+            @status = normalize_status(status)
+            @reason = reason
+            freeze
+          end
+
+          def actionable?
+            status == :pending
+          end
+
+          def written?
+            %i[created written unchanged].include?(status)
+          end
+
+          def skipped?
+            status == :skipped
+          end
+
+          def to_h
+            {
+              kind: kind,
+              relative_path: relative_path,
+              absolute_path: absolute_path,
+              status: status,
+              reason: reason
+            }
+          end
+
+          private
+
+          def normalize_kind(kind)
+            value = kind.to_sym
+            return value if VALID_KINDS.include?(value)
+
+            raise ArgumentError, "unsupported creator write step kind #{kind.inspect}"
+          end
+
+          def normalize_status(status)
+            value = status.to_sym
+            return value if VALID_STATUSES.include?(value)
+
+            raise ArgumentError, "unsupported creator write step status #{status.inspect}"
+          end
+        end
+      end
+    end
+  end
+end