igniter 0.5.0 → 0.5.2

data/packages/igniter-hub/README.md

@@ -0,0 +1,25 @@
+# igniter-hub
+
+Local capsule catalog discovery for Igniter.
+
+Status: first POC slice, not stable API.
+
+## Owns
+
+- local capsule catalog loading
+- bundle metadata for install candidates
+- capability summaries for applications
+- enough metadata for an app UI to present installable capsules
+
+## Does Not Own
+
+- remote download
+- trust/signatures
+- applying bundles
+- running installed capsules
+
+Applications should use `igniter-application` transfer verification, intake,
+apply, and receipt APIs to install a selected bundle.
+
+Companion uses this split as the first proof: `igniter-hub` lists a local
+horoscope capsule, while the app installs it through the transfer pipeline.

data/packages/igniter-hub/lib/igniter/hub/catalog_entry.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Hub
+    CatalogEntry = Struct.new(
+      :name, :title, :version, :description, :bundle_path, :capabilities, :metadata,
+      keyword_init: true
+    ) do
+      def initialize(name:, bundle_path:, title: nil, version: "0.1.0", description: nil, capabilities: [], metadata: {})
+        super(
+          name: name.to_sym,
+          title: title || name.to_s.tr("_", " "),
+          version: version.to_s,
+          description: description,
+          bundle_path: File.expand_path(bundle_path.to_s),
+          capabilities: Array(capabilities).map(&:to_sym).freeze,
+          metadata: metadata.transform_keys(&:to_sym).freeze
+        )
+        freeze
+      end
+
+      def to_h
+        {
+          name: name,
+          title: title,
+          version: version,
+          description: description,
+          bundle_path: bundle_path,
+          capabilities: capabilities,
+          metadata: metadata
+        }.compact
+      end
+    end
+  end
+end

data/packages/igniter-hub/lib/igniter/hub/local_catalog.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Hub
+    class LocalCatalog
+      attr_reader :path, :entries
+
+      def self.load(path)
+        payload = JSON.parse(File.read(path), symbolize_names: true)
+        root = File.dirname(File.expand_path(path.to_s))
+        entries = Array(payload.fetch(:entries, [])).map do |entry|
+          build_entry(entry, root: root)
+        end
+        new(path: path, entries: entries)
+      end
+
+      def self.build_entry(entry, root:)
+        CatalogEntry.new(
+          name: entry.fetch(:name),
+          title: entry[:title],
+          version: entry.fetch(:version, "0.1.0"),
+          description: entry[:description],
+          bundle_path: File.expand_path(entry.fetch(:bundle_path), root),
+          capabilities: entry.fetch(:capabilities, []),
+          metadata: entry.fetch(:metadata, {})
+        )
+      end
+
+      def initialize(path:, entries:)
+        @path = File.expand_path(path.to_s)
+        @entries = entries.freeze
+        freeze
+      end
+
+      def names
+        entries.map(&:name).sort
+      end
+
+      def fetch(name)
+        entries.find { |entry| entry.name == name.to_sym } || raise(KeyError, "unknown hub capsule #{name.inspect}")
+      end
+
+      def to_h
+        {
+          path: path,
+          entries: entries.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/packages/igniter-hub/lib/igniter/hub.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "hub/catalog_entry"
+require_relative "hub/local_catalog"
+
+module Igniter
+  module Hub
+    class << self
+      def local_catalog(path)
+        LocalCatalog.load(path)
+      end
+    end
+  end
+end

data/packages/igniter-hub/lib/igniter-hub.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "igniter/hub"

data/packages/igniter-mcp-adapter/README.md

@@ -0,0 +1,65 @@
+# igniter-mcp-adapter
+
+Thin MCP adapter package over Igniter's tooling-facing contracts surfaces.
+
+This package exists to keep transport and server concerns separate from the
+tooling semantics that live in `igniter-extensions`.
+
+## Purpose
+
+- expose the stabilized MCP-oriented tool catalog
+- delegate tool invocation to `Igniter::Extensions::Contracts::McpPack`
+- keep transport/runtime concerns out of `igniter-extensions`
+
+## What This Package Should Not Do
+
+- define new creator or debug semantics
+- reach into `igniter-contracts` internals directly
+- become a second source of truth for tool behavior
+
+## Public Surface
+
+```ruby
+require "igniter-mcp-adapter"
+
+catalog = Igniter::MCP::Adapter.tool_catalog
+result = Igniter::MCP::Adapter.invoke(:creator_session_start, name: :delivery)
+```
+
+Transport-ready server wrapper:
+
+```ruby
+tool = Igniter::MCP::Adapter::Server.tool(:creator_session_apply)
+
+response = Igniter::MCP::Adapter::Server.call(
+  :creator_session_start,
+  arguments: { name: "delivery", capabilities: %w[effect executor] }
+)
+```
+
+JSON-RPC stdio host entrypoint:
+
+```ruby
+host = Igniter::MCP::Adapter::Host.new
+host.serve
+```
+
+The package also ships an executable:
+
+```bash
+igniter-mcp-adapter
+```
+
+## Boundary
+
+`igniter-mcp-adapter` depends on `igniter-extensions` only. The semantic source
+of truth remains:
+
+- `Igniter::Extensions::Contracts.mcp_tools`
+- `Igniter::Extensions::Contracts.mcp_call(...)`
+- `Igniter::Extensions::Contracts.mcp_creator_session(...)`
+
+## Docs
+
+- [Igniter Dev](../../docs/dev/README.md)
+- [MCP Adapter Package](../../docs/dev/mcp-adapter-package-spec.md)

data/packages/igniter-mcp-adapter/exe/igniter-mcp-adapter

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "igniter-mcp-adapter"
+
+Igniter::MCP::Adapter::Host.new.serve

data/packages/igniter-mcp-adapter/lib/igniter/mcp/adapter/host.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Igniter
+  module MCP
+    module Adapter
+      class Host
+        JSONRPC_VERSION = "2.0"
+        PROTOCOL_VERSION = "2024-11-05"
+
+        attr_reader :target
+
+        def initialize(target: nil)
+          @target = target || default_target
+        end
+
+        def serve(input: $stdin, output: $stdout)
+          loop do
+            message = read_message(input)
+            break unless message
+
+            response = handle_message(message)
+            write_message(output, response) if response
+          end
+        end
+
+        def handle_message(message)
+          payload = symbolize_keys(message)
+          method = payload.fetch(:method)
+          id = payload[:id]
+
+          case method
+          when "initialize"
+            success(id, {
+                      protocolVersion: PROTOCOL_VERSION,
+                      serverInfo: {
+                        name: "igniter-mcp-adapter",
+                        version: adapter_version
+                      },
+                      capabilities: {
+                        tools: {
+                          listChanged: false
+                        }
+                      }
+                    })
+          when "notifications/initialized"
+            nil
+          when "ping"
+            success(id, {})
+          when "tools/list"
+            success(id, { tools: Server.tools })
+          when "tools/call"
+            params = payload.fetch(:params, {})
+            validate_tool_call!(params)
+            result = Server.call(
+              params.fetch(:name),
+              target: target,
+              arguments: params.fetch(:arguments, {})
+            )
+            success(id, result.slice(:content, :structuredContent, :isError, :meta))
+          else
+            error(id, -32_601, "Method not found: #{method}")
+          end
+        rescue KeyError => e
+          error(id, -32_602, "Invalid params: #{e.message}")
+        rescue ArgumentError => e
+          error(id, -32_602, "Invalid params: #{e.message}")
+        rescue StandardError => e
+          error(id, -32_603, "#{e.class}: #{e.message}")
+        end
+
+        def read_message(input)
+          headers = {}
+
+          loop do
+            line = input.gets
+            return nil unless line
+
+            stripped = line.strip
+            break if stripped.empty?
+
+            key, value = line.split(":", 2)
+            headers[key.downcase] = value.to_s.strip
+          end
+
+          length = Integer(headers.fetch("content-length"))
+          body = input.read(length)
+          return nil unless body
+
+          JSON.parse(body, symbolize_names: true)
+        end
+
+        def write_message(output, payload)
+          body = JSON.generate(payload)
+          output.write("Content-Length: #{body.bytesize}\r\n\r\n#{body}")
+          output.flush if output.respond_to?(:flush)
+          payload
+        end
+
+        private
+
+        def default_target
+          Igniter::Extensions::Contracts.with(Igniter::Extensions::Contracts::McpPack)
+        end
+
+        def validate_tool_call!(params)
+          tool_name = params.fetch(:name)
+          arguments = symbolize_keys(params.fetch(:arguments, {}))
+          schema = Server.tool(tool_name).fetch(:inputSchema)
+
+          validate_required_keys!(schema, arguments)
+          validate_unknown_keys!(schema, arguments)
+          validate_argument_values!(schema, arguments)
+        end
+
+        def validate_required_keys!(schema, arguments)
+          required = Array(schema[:required]).map(&:to_sym)
+          missing = required.reject { |key| arguments.key?(key) }
+          return if missing.empty?
+
+          raise ArgumentError, "missing required arguments: #{missing.join(", ")}"
+        end
+
+        def validate_unknown_keys!(schema, arguments)
+          return unless schema[:additionalProperties] == false
+
+          allowed = schema.fetch(:properties).keys.map(&:to_sym)
+          unknown = arguments.keys.reject { |key| allowed.include?(key) }
+          return if unknown.empty?
+
+          raise ArgumentError, "unknown arguments: #{unknown.join(", ")}"
+        end
+
+        def validate_argument_values!(schema, arguments)
+          properties = schema.fetch(:properties)
+
+          arguments.each do |key, value|
+            argument_schema = properties[key.to_s]
+            next unless argument_schema
+
+            validate_argument_type!(key, argument_schema, value)
+            validate_argument_enum!(key, argument_schema, value)
+          end
+        end
+
+        def validate_argument_type!(key, schema, value)
+          any_of = schema[:anyOf]
+          return if any_of&.any? { |candidate| valid_type?(candidate[:type], value) }
+          return unless schema.key?(:type)
+          return if valid_type?(schema[:type], value)
+
+          raise ArgumentError, "argument #{key} expected #{schema[:type]}"
+        end
+
+        def validate_argument_enum!(key, schema, value)
+          enum = schema[:enum]
+          return if enum.nil? || enum.empty?
+
+          comparable =
+            case value
+            when Symbol
+              value.to_s
+            else
+              value
+            end
+
+          return if enum.include?(comparable)
+
+          raise ArgumentError, "argument #{key} must be one of: #{enum.join(", ")}"
+        end
+
+        def valid_type?(type, value)
+          case type
+          when "string"
+            value.is_a?(String) || value.is_a?(Symbol)
+          when "array"
+            value.is_a?(Array)
+          when "object"
+            value.is_a?(Hash)
+          else
+            true
+          end
+        end
+
+        def adapter_version
+          Gem.loaded_specs["igniter-mcp-adapter"]&.version&.to_s ||
+            Gem.loaded_specs["igniter-extensions"]&.version&.to_s ||
+            "0.0.0"
+        end
+
+        def success(id, result)
+          {
+            jsonrpc: JSONRPC_VERSION,
+            id: id,
+            result: result
+          }
+        end
+
+        def error(id, code, message)
+          {
+            jsonrpc: JSONRPC_VERSION,
+            id: id,
+            error: {
+              code: code,
+              message: message
+            }
+          }
+        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/packages/igniter-mcp-adapter/lib/igniter/mcp/adapter/server.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Igniter
+  module MCP
+    module Adapter
+      module Server
+        module_function
+
+        def tools
+          Adapter.tool_catalog.map { |tool| transport_tool(tool) }
+        end
+
+        def tool(name)
+          transport_tool(Adapter.tool_definition(name))
+        end
+
+        def call(name, arguments: {}, target: nil, &block)
+          result = Adapter.invoke(
+            name,
+            target: target,
+            **symbolize_keys(arguments),
+            &block
+          )
+
+          transport_result(result)
+        rescue StandardError => e
+          error_result(name, e)
+        end
+
+        def transport_tool(tool)
+          {
+            name: tool.fetch(:name).to_s,
+            description: tool.fetch(:summary),
+            inputSchema: input_schema(tool),
+            annotations: {
+              title: tool.fetch(:name).to_s,
+              readOnlyHint: !tool.fetch(:mutating),
+              idempotentHint: !tool.fetch(:mutating)
+            }
+          }
+        end
+
+        def input_schema(tool)
+          arguments = tool.fetch(:arguments)
+          required_arguments = arguments.select { |argument| argument.fetch(:required) }
+
+          {
+            type: "object",
+            properties: arguments.to_h do |argument|
+              [argument.fetch(:name).to_s, argument_schema(argument)]
+            end,
+            required: required_arguments.map { |argument| argument.fetch(:name).to_s },
+            additionalProperties: false
+          }
+        end
+
+        def argument_schema(argument)
+          schema = {
+            description: argument.fetch(:summary)
+          }
+
+          case argument.fetch(:type).to_sym
+          when :string
+            schema[:type] = "string"
+          when :symbol
+            schema[:type] = "string"
+          when :symbol_array
+            schema[:type] = "array"
+            schema[:items] = { type: "string" }
+          when :map, :session_state, :compiled_graph
+            schema[:type] = "object"
+          when :pack_reference
+            schema[:anyOf] = [
+              { type: "string" },
+              { type: "object" }
+            ]
+          else
+            schema[:type] = "object"
+          end
+
+          argument_enum = argument[:enum] || []
+          schema[:enum] = argument_enum.map(&:to_s) unless argument_enum.empty?
+
+          default = argument[:default]
+          schema[:default] = default.is_a?(Symbol) ? default.to_s : default unless default.nil?
+
+          schema
+        end
+
+        def transport_result(result)
+          payload = result.to_h
+          structured = payload.fetch(:payload)
+
+          {
+            tool: payload.fetch(:tool_name).to_s,
+            isError: false,
+            structuredContent: structured,
+            content: [
+              {
+                type: "text",
+                text: JSON.generate(structured)
+              }
+            ],
+            meta: {
+              mutating: payload.fetch(:mutating)
+            }
+          }
+        end
+
+        def error_result(name, error)
+          message = "#{error.class}: #{error.message}"
+
+          {
+            tool: name.to_s,
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: message
+              }
+            ],
+            structuredContent: {
+              error: {
+                class: error.class.name,
+                message: error.message
+              }
+            }
+          }
+        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/packages/igniter-mcp-adapter/lib/igniter/mcp/adapter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "igniter/extensions/contracts"
+
+module Igniter
+  module MCP
+    module Adapter
+      module_function
+
+      def tool_catalog
+        Igniter::Extensions::Contracts.mcp_tools
+      end
+
+      def tool_names
+        tool_catalog.map { |tool| tool.fetch(:name) }
+      end
+
+      def tool_definition(tool_name)
+        tool_catalog.find { |tool| tool.fetch(:name) == tool_name.to_sym } ||
+          raise(ArgumentError, "unknown MCP adapter tool #{tool_name.inspect}")
+      end
+
+      def invoke(tool_name, target: nil, **arguments, &block)
+        Igniter::Extensions::Contracts.mcp_call(
+          tool_name,
+          target: target,
+          **arguments,
+          &block
+        )
+      end
+
+      def creator_session(target: nil, **arguments)
+        Igniter::Extensions::Contracts.mcp_creator_session(
+          target: target,
+          **arguments
+        )
+      end
+    end
+  end
+end

data/packages/igniter-mcp-adapter/lib/igniter-mcp-adapter.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "igniter/mcp/adapter"
+require_relative "igniter/mcp/adapter/server"
+require_relative "igniter/mcp/adapter/host"