igniter-extensions 0.5.2

data/lib/igniter/extensions/contracts/mcp/tool_definition.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Mcp
+        class ToolDefinition
+          attr_reader :name, :summary, :mutating, :target, :arguments
+
+          def initialize(name:, summary:, mutating: false, target: nil, arguments: [])
+            @name = name.to_sym
+            @summary = summary
+            @mutating = mutating == true
+            @target = target&.to_sym
+            @arguments = arguments.freeze
+            freeze
+          end
+
+          def to_h
+            payload = {
+              name: name,
+              summary: summary,
+              mutating: mutating,
+              arguments: arguments.map(&:to_h)
+            }
+            payload[:target] = target if target
+            payload
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/mcp/tool_result.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Mcp
+        class ToolResult
+          attr_reader :tool_name, :payload, :mutating
+
+          def initialize(tool_name:, payload:, mutating:)
+            @tool_name = tool_name.to_sym
+            @payload = payload
+            @mutating = mutating == true
+            freeze
+          end
+
+          def to_h
+            {
+              tool_name: tool_name,
+              mutating: mutating,
+              payload: payload
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/mcp_pack.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require_relative "mcp/tool_definition"
+require_relative "mcp/tool_argument"
+require_relative "mcp/tool_result"
+require_relative "mcp/creator_session"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module McpPack
+        module_function
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_mcp,
+            requires_packs: [DebugPack, CreatorPack],
+            metadata: { category: :tooling }
+          )
+        end
+
+        def install_into(kernel)
+          kernel
+        end
+
+        def tools
+          @tools ||= [
+            Mcp::ToolDefinition.new(
+              name: :inspect_profile,
+              summary: "Return a structured profile snapshot.",
+              target: :profile_or_environment
+            ),
+            Mcp::ToolDefinition.new(
+              name: :inspect_pack,
+              summary: "Return a structured installed-pack snapshot.",
+              target: :profile_or_environment,
+              arguments: [
+                Mcp::ToolArgument.new(name: :pack, type: :pack_reference,
+                                      summary: "Installed pack name or pack module.", required: true)
+              ]
+            ),
+            Mcp::ToolDefinition.new(
+              name: :audit_pack,
+              summary: "Audit a custom pack against creator/debug quality seams.",
+              target: :optional_profile_or_environment,
+              arguments: [
+                Mcp::ToolArgument.new(name: :pack, type: :pack_reference, summary: "Custom pack module to audit.",
+                                      required: true)
+              ]
+            ),
+            Mcp::ToolDefinition.new(
+              name: :debug_report,
+              summary: "Compile or execute and return a structured debug report.",
+              target: :environment,
+              arguments: [
+                Mcp::ToolArgument.new(name: :inputs, type: :map,
+                                      summary: "Runtime inputs used for execution when a graph is available."),
+                Mcp::ToolArgument.new(name: :compiled_graph, type: :compiled_graph,
+                                      summary: "Previously compiled graph to execute instead of compiling a block.")
+              ]
+            ),
+            Mcp::ToolDefinition.new(
+              name: :creator_wizard,
+              summary: "Build a stateful creator wizard payload.",
+              target: :optional_profile_or_environment,
+              arguments: creator_arguments(include_scope: true, include_root: true)
+            ),
+            Mcp::ToolDefinition.new(
+              name: :creator_session_start,
+              summary: "Create a serialized creator session payload.",
+              target: :optional_profile_or_environment,
+              arguments: creator_arguments(include_scope: true, include_root: true)
+            ),
+            Mcp::ToolDefinition.new(
+              name: :creator_session_apply,
+              summary: "Apply updates to a serialized creator session payload.",
+              target: :optional_profile_or_environment,
+              arguments: [
+                Mcp::ToolArgument.new(name: :session, type: :session_state,
+                                      summary: "Previously serialized creator session payload.", required: true),
+                Mcp::ToolArgument.new(name: :updates, type: :map,
+                                      summary: "Partial wizard updates to merge into the session.", required: true)
+              ]
+            ),
+            Mcp::ToolDefinition.new(
+              name: :creator_session_workflow,
+              summary: "Build workflow payload from a serialized creator session.",
+              target: :optional_profile_or_environment,
+              arguments: [
+                Mcp::ToolArgument.new(name: :session, type: :session_state,
+                                      summary: "Previously serialized creator session payload.", required: true)
+              ]
+            ),
+            Mcp::ToolDefinition.new(
+              name: :creator_session_write_plan,
+              summary: "Build writer plan payload from a serialized creator session.",
+              target: :optional_profile_or_environment,
+              arguments: [
+                Mcp::ToolArgument.new(name: :session, type: :session_state,
+                                      summary: "Previously serialized creator session payload.", required: true)
+              ]
+            ),
+            Mcp::ToolDefinition.new(
+              name: :creator_session_write,
+              summary: "Write scaffold files from a serialized creator session.",
+              mutating: true,
+              target: :optional_profile_or_environment,
+              arguments: [
+                Mcp::ToolArgument.new(name: :session, type: :session_state,
+                                      summary: "Previously serialized creator session payload.", required: true)
+              ]
+            ),
+            Mcp::ToolDefinition.new(
+              name: :creator_workflow,
+              summary: "Build a creator workflow payload.",
+              target: :optional_profile_or_environment,
+              arguments: creator_arguments(include_scope: true)
+            ),
+            Mcp::ToolDefinition.new(
+              name: :creator_write_plan,
+              summary: "Build a creator writer plan payload.",
+              target: :optional_profile_or_environment,
+              arguments: creator_arguments(include_scope: true, include_root: true, require_name: true,
+                                           require_root: true)
+            ),
+            Mcp::ToolDefinition.new(
+              name: :creator_write,
+              summary: "Write a creator scaffold to disk.",
+              mutating: true,
+              target: :optional_profile_or_environment,
+              arguments: creator_arguments(include_scope: true, include_root: true, require_name: true,
+                                           require_root: true)
+            )
+          ].freeze
+        end
+
+        def tool_catalog
+          tools.map(&:to_h)
+        end
+
+        def call(tool_name, target: nil, **arguments, &block)
+          definition = tool_definition(tool_name)
+          payload = dispatch(definition.name, target: target, **arguments, &block)
+          Mcp::ToolResult.new(
+            tool_name: definition.name,
+            payload: payload,
+            mutating: definition.mutating
+          )
+        end
+
+        def tool_definition(tool_name)
+          tools.find { |definition| definition.name == tool_name.to_sym } ||
+            raise(ArgumentError, "unknown MCP tool #{tool_name.inspect}")
+        end
+
+        def dispatch(tool_name, target: nil, **arguments, &block)
+          case tool_name.to_sym
+          when :inspect_profile
+            profile_from(target).then { |profile| DebugPack.profile_snapshot(profile).to_h }
+          when :inspect_pack
+            profile = profile_from(target)
+            DebugPack.pack_snapshot(arguments.fetch(:pack), profile: profile).to_h
+          when :audit_pack
+            DebugPack.audit(arguments.fetch(:pack), profile: profile_from(target, optional: true)).to_h
+          when :debug_report
+            environment = environment_from(target)
+            DebugPack.report(
+              environment,
+              inputs: arguments[:inputs],
+              compiled_graph: arguments[:compiled_graph],
+              &block
+            ).to_h
+          when :creator_wizard
+            CreatorPack.wizard(
+              name: arguments[:name],
+              kind: arguments[:kind],
+              namespace: arguments.fetch(:namespace, "MyCompany::IgniterPacks"),
+              profile: arguments[:profile],
+              capabilities: arguments[:capabilities],
+              scope: arguments[:scope],
+              root: arguments[:root],
+              mode: arguments.fetch(:mode, :skip_existing),
+              pack: arguments[:pack],
+              target_profile: profile_from(target, optional: true)
+            ).to_h
+          when :creator_session_start
+            creator_session_from(arguments, target: target).to_h
+          when :creator_session_apply
+            session = session_from(arguments.fetch(:session) { arguments.fetch("session") }, target: target)
+            session.apply(**symbolize_keys(arguments.fetch(:updates) { arguments.fetch("updates") })).to_h
+          when :creator_session_workflow
+            session_from(arguments.fetch(:session) { arguments.fetch("session") }, target: target).workflow_payload
+          when :creator_session_write_plan
+            session_from(arguments.fetch(:session) { arguments.fetch("session") }, target: target).write_plan_payload
+          when :creator_session_write
+            session_from(arguments.fetch(:session) { arguments.fetch("session") }, target: target).write_payload
+          when :creator_workflow
+            CreatorPack.workflow(
+              name: arguments.fetch(:name),
+              kind: arguments[:kind],
+              namespace: arguments.fetch(:namespace, "MyCompany::IgniterPacks"),
+              profile: arguments[:profile],
+              capabilities: arguments[:capabilities],
+              scope: arguments.fetch(:scope, :monorepo_package),
+              pack: arguments[:pack],
+              target_profile: profile_from(target, optional: true)
+            ).to_h
+          when :creator_write_plan
+            CreatorPack.writer(
+              name: arguments.fetch(:name),
+              kind: arguments[:kind],
+              namespace: arguments.fetch(:namespace, "MyCompany::IgniterPacks"),
+              profile: arguments[:profile],
+              capabilities: arguments[:capabilities],
+              scope: arguments.fetch(:scope, :monorepo_package),
+              pack: arguments[:pack],
+              target_profile: profile_from(target, optional: true),
+              root: arguments.fetch(:root),
+              mode: arguments.fetch(:mode, :skip_existing)
+            ).plan.to_h
+          when :creator_write
+            CreatorPack.write(
+              name: arguments.fetch(:name),
+              kind: arguments[:kind],
+              namespace: arguments.fetch(:namespace, "MyCompany::IgniterPacks"),
+              profile: arguments[:profile],
+              capabilities: arguments[:capabilities],
+              scope: arguments.fetch(:scope, :monorepo_package),
+              pack: arguments[:pack],
+              target_profile: profile_from(target, optional: true),
+              root: arguments.fetch(:root),
+              mode: arguments.fetch(:mode, :skip_existing)
+            ).to_h
+          else
+            raise ArgumentError, "unsupported MCP tool #{tool_name.inspect}"
+          end
+        end
+
+        def profile_from(target, optional: false)
+          profile =
+            case target
+            when nil
+              nil
+            else
+              target.respond_to?(:profile) ? target.profile : target
+            end
+
+          return profile if optional || profile
+
+          raise ArgumentError, "McpPack tool requires an environment or profile target"
+        end
+
+        def environment_from(target)
+          return target if target.respond_to?(:profile) && target.respond_to?(:execute)
+
+          raise ArgumentError, "McpPack debug_report requires an environment target"
+        end
+
+        def creator_arguments(include_scope: false, include_root: false, require_name: false, require_root: false)
+          arguments = [
+            Mcp::ToolArgument.new(name: :name, type: :string, summary: "Pack name without the trailing _pack suffix.",
+                                  required: require_name),
+            Mcp::ToolArgument.new(name: :kind, type: :symbol, summary: "Explicit pack kind when not inferred.",
+                                  enum: %i[feature operational bundle]),
+            Mcp::ToolArgument.new(name: :namespace, type: :string,
+                                  summary: "Ruby namespace for generated pack constants.", default: "MyCompany::IgniterPacks"),
+            Mcp::ToolArgument.new(name: :profile, type: :symbol, summary: "Named creator profile.",
+                                  enum: CreatorPack.available_profiles),
+            Mcp::ToolArgument.new(name: :capabilities, type: :symbol_array,
+                                  summary: "Capabilities used to infer or refine the profile."),
+            Mcp::ToolArgument.new(name: :pack, type: :pack_reference,
+                                  summary: "Custom pack module for audit-aware creator flows."),
+            Mcp::ToolArgument.new(name: :mode, type: :symbol, summary: "Writer behavior when files already exist.",
+                                  default: :skip_existing, enum: %i[skip_existing overwrite])
+          ]
+          if include_scope
+            arguments << Mcp::ToolArgument.new(name: :scope, type: :symbol, summary: "Target packaging scope.",
+                                               required: false, enum: CreatorPack.available_scopes)
+          end
+          if include_root
+            arguments << Mcp::ToolArgument.new(name: :root, type: :string,
+                                               summary: "Filesystem root for generated files.", required: require_root)
+          end
+          if include_scope && require_root
+            arguments.find { |argument| argument.name == :scope }&.tap do |argument|
+              arguments[arguments.index(argument)] = Mcp::ToolArgument.new(
+                name: :scope,
+                type: :symbol,
+                summary: "Target packaging scope.",
+                required: true,
+                enum: CreatorPack.available_scopes
+              )
+            end
+          end
+          arguments
+        end
+
+        def creator_session_from(arguments, target:)
+          Mcp::CreatorSession.new(
+            name: arguments[:name],
+            kind: arguments[:kind],
+            namespace: arguments.fetch(:namespace, "MyCompany::IgniterPacks"),
+            profile: arguments[:profile],
+            capabilities: arguments[:capabilities],
+            scope: arguments[:scope],
+            root: arguments[:root],
+            mode: arguments.fetch(:mode, :skip_existing),
+            pack: arguments[:pack],
+            target_profile: profile_from(target, optional: true)
+          )
+        end
+
+        def session_from(payload, target:)
+          Mcp::CreatorSession.from_h(
+            symbolize_keys(payload),
+            target_profile: profile_from(target, optional: true)
+          )
+        end
+
+        def symbolize_keys(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[key.respond_to?(:to_sym) ? key.to_sym : key] = symbolize_keys(nested)
+            end
+          when Array
+            value.map { |item| symbolize_keys(item) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/provenance/builder.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Provenance
+        class Builder
+          def self.build(output_name, result)
+            new(result).build(output_name)
+          end
+
+          def initialize(result)
+            @result = result
+            @compiled_graph = result.compiled_graph
+            @operations = @compiled_graph.operations.reject(&:output?).each_with_object({}) do |operation, memo|
+              memo[operation.name] = operation
+            end
+          end
+
+          def build(output_name)
+            output_name = output_name.to_sym
+
+            raise Igniter::Contracts::Error, "execution result does not carry a compiled graph" unless @compiled_graph
+
+            unless output_names.include?(output_name)
+              raise Igniter::Contracts::Error,
+                    "no output named '#{output_name}' in compiled graph"
+            end
+
+            source_operation = @operations.fetch(output_name) do
+              raise Igniter::Contracts::Error,
+                    "source node '#{output_name}' for output '#{output_name}' not found in compiled graph"
+            end
+
+            Lineage.new(build_trace(source_operation, {}))
+          end
+
+          private
+
+          def output_names
+            @output_names ||= @compiled_graph.operations.select(&:output?).map(&:name)
+          end
+
+          def build_trace(operation, memo)
+            return memo[operation.name] if memo.key?(operation.name)
+
+            memo[operation.name] = nil
+
+            contributing = dependency_names_for(operation).each_with_object({}) do |dependency_name, acc|
+              dependency_operation = @operations[dependency_name]
+              next unless dependency_operation
+
+              acc[dependency_name] = build_trace(dependency_operation, memo)
+            end
+
+            trace = NodeTrace.new(
+              name: operation.name,
+              kind: operation.kind,
+              value: resolved_value_for(operation),
+              contributing: contributing
+            )
+
+            memo[operation.name] = trace
+          end
+
+          def dependency_names_for(operation)
+            names = []
+            names.concat(Array(operation.attributes[:depends_on])) if operation.attribute?(:depends_on)
+            names << operation.attributes[:from] if operation.attribute?(:from)
+            names.map(&:to_sym).uniq
+          end
+
+          def resolved_value_for(operation)
+            @result.state.fetch(operation.name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/provenance/lineage.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Provenance
+        class Lineage
+          attr_reader :trace
+
+          def initialize(trace)
+            @trace = trace
+            freeze
+          end
+
+          def output_name
+            trace.name
+          end
+
+          def value
+            trace.value
+          end
+
+          def contributing_inputs
+            trace.contributing_inputs
+          end
+
+          def sensitive_to?(input_name)
+            trace.sensitive_to?(input_name)
+          end
+
+          def path_to(input_name)
+            trace.path_to(input_name)
+          end
+
+          def explain
+            TextFormatter.format(trace)
+          end
+
+          alias to_s explain
+
+          def to_h
+            serialize(trace)
+          end
+
+          private
+
+          def serialize(trace)
+            {
+              node: trace.name,
+              kind: trace.kind,
+              value: trace.value,
+              contributing: trace.contributing.transform_values { |dependency| serialize(dependency) }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/provenance/node_trace.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Provenance
+        class NodeTrace
+          attr_reader :name, :kind, :value, :contributing
+
+          def initialize(name:, kind:, value:, contributing: {})
+            @name = name.to_sym
+            @kind = kind.to_sym
+            @value = value
+            @contributing = contributing.freeze
+            freeze
+          end
+
+          def input?
+            kind == :input
+          end
+
+          def leaf?
+            contributing.empty?
+          end
+
+          def contributing_inputs
+            return { name => value } if input?
+
+            contributing.each_value.with_object({}) do |trace, memo|
+              memo.merge!(trace.contributing_inputs)
+            end
+          end
+
+          def sensitive_to?(input_name)
+            contributing_inputs.key?(input_name.to_sym)
+          end
+
+          def path_to(input_name)
+            target = input_name.to_sym
+            return [name] if name == target
+
+            contributing.each_value do |trace|
+              path = trace.path_to(target)
+              return [name] + path if path
+            end
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/provenance/text_formatter.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Provenance
+        module TextFormatter
+          VALUE_MAX_LENGTH = 60
+
+          module_function
+
+          def format(trace)
+            lines = []
+            render(trace, lines, prefix: "", is_root: true, is_last: true)
+            lines.join("\n")
+          end
+
+          def render(trace, lines, prefix:, is_root:, is_last:)
+            if is_root
+              connector = ""
+              child_padding = ""
+            elsif is_last
+              connector = "└─ "
+              child_padding = "   "
+            else
+              connector = "├─ "
+              child_padding = "│  "
+            end
+
+            child_prefix = prefix + child_padding
+            lines << "#{prefix}#{connector}#{trace.name} = #{format_value(trace.value)}  [#{trace.kind}]"
+
+            dependencies = trace.contributing.values
+            dependencies.each_with_index do |dependency, index|
+              render(
+                dependency,
+                lines,
+                prefix: child_prefix,
+                is_root: false,
+                is_last: index == dependencies.length - 1
+              )
+            end
+          end
+
+          def format_value(value)
+            rendered = case value
+                       when nil then "nil"
+                       when String, Symbol then value.inspect
+                       when Hash then "{#{value.map { |key, entry| "#{key}: #{entry.inspect}" }.join(", ")}}"
+                       when Array then "[#{value.map(&:inspect).join(", ")}]"
+                       else value.inspect
+                       end
+
+            return rendered if rendered.length <= VALUE_MAX_LENGTH
+
+            "#{rendered[0, VALUE_MAX_LENGTH - 3]}..."
+          end
+        end
+      end
+    end
+  end
+end