spurline-deploy 0.3.0

data/lib/spurline/channels/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Channels
+    # Abstract interface for channel adapters. Each channel parses events from
+    # a specific external source and resolves session affinity.
+    #
+    # Subclasses must implement:
+    #   #channel_name   - Symbol identifying this channel
+    #   #route(payload) - Parse payload, resolve session, return Event or nil
+    #   #supported_events - Array of event type symbols this channel handles
+    class Base
+      # Symbol identifying this channel (e.g., :github, :slack).
+      def channel_name
+        raise NotImplementedError, "#{self.class.name} must implement #channel_name"
+      end
+
+      # Parses a raw payload hash and returns a routed Event, or nil if the
+      # payload is not recognized or not relevant.
+      #
+      # @param payload [Hash] The raw event payload (e.g., parsed webhook JSON)
+      # @param headers [Hash] Optional HTTP headers for signature verification
+      # @return [Spurline::Channels::Event, nil]
+      # ASYNC-READY:
+      def route(payload, headers: {})
+        raise NotImplementedError, "#{self.class.name} must implement #route"
+      end
+
+      # Returns the event types this channel can handle.
+      # @return [Array<Symbol>]
+      def supported_events
+        raise NotImplementedError, "#{self.class.name} must implement #supported_events"
+      end
+
+      # Whether this channel handles the given event type.
+      def handles?(event_type)
+        supported_events.include?(event_type.to_sym)
+      end
+    end
+  end
+end

data/lib/spurline/channels/event.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Spurline
+  module Channels
+    # Immutable value object representing an external event routed through a channel.
+    # Events are the universal internal representation regardless of which channel
+    # produced them. Frozen on creation.
+    #
+    # Attributes:
+    #   channel     - Symbol identifying the source channel (e.g., :github)
+    #   event_type  - Symbol for the event kind (e.g., :issue_comment, :pr_review)
+    #   payload     - Hash of parsed event data (channel-specific)
+    #   trust       - Symbol trust level (default :external)
+    #   session_id  - String session ID if routing resolved, nil otherwise
+    #   received_at - Time the event was received
+    class Event
+      attr_reader :channel, :event_type, :payload, :trust, :session_id, :received_at
+
+      def initialize(channel:, event_type:, payload:, trust: :external, session_id: nil, received_at: nil)
+        validate_channel!(channel)
+        validate_event_type!(event_type)
+        validate_payload!(payload)
+        validate_trust!(trust)
+
+        @channel = channel.to_sym
+        @event_type = event_type.to_sym
+        @payload = deep_freeze(payload)
+        @trust = trust.to_sym
+        @session_id = session_id&.to_s&.freeze
+        @received_at = (received_at || Time.now).freeze
+        freeze
+      end
+
+      # Whether this event was matched to a specific session.
+      def routed?
+        !@session_id.nil?
+      end
+
+      # Serializes the event to a plain hash suitable for JSON serialization.
+      def to_h
+        {
+          channel: @channel,
+          event_type: @event_type,
+          payload: unfreeze_hash(@payload),
+          trust: @trust,
+          session_id: @session_id,
+          received_at: @received_at.iso8601(6),
+        }
+      end
+
+      # Reconstructs an Event from a hash (e.g., from JSON deserialization).
+      def self.from_h(hash)
+        h = symbolize_keys(hash)
+        new(
+          channel: h[:channel],
+          event_type: h[:event_type],
+          payload: symbolize_keys(h[:payload] || {}),
+          trust: h[:trust] || :external,
+          session_id: h[:session_id],
+          received_at: h[:received_at] ? Time.parse(h[:received_at].to_s) : nil
+        )
+      end
+
+      def ==(other)
+        other.is_a?(Event) &&
+          channel == other.channel &&
+          event_type == other.event_type &&
+          payload == other.payload &&
+          trust == other.trust &&
+          session_id == other.session_id
+      end
+
+      def inspect
+        "#<Spurline::Channels::Event channel=#{channel} type=#{event_type} " \
+          "session=#{session_id || 'unrouted'} trust=#{trust}>"
+      end
+
+      private
+
+      def validate_channel!(channel)
+        raise ArgumentError, "channel must be a Symbol or String" unless channel.respond_to?(:to_sym)
+      end
+
+      def validate_event_type!(event_type)
+        raise ArgumentError, "event_type must be a Symbol or String" unless event_type.respond_to?(:to_sym)
+      end
+
+      def validate_payload!(payload)
+        raise ArgumentError, "payload must be a Hash, got #{payload.class}" unless payload.is_a?(Hash)
+      end
+
+      def validate_trust!(trust)
+        level = trust.to_sym
+        unless Spurline::Security::Content::TRUST_LEVELS.include?(level)
+          raise Spurline::ConfigurationError,
+            "Invalid trust level for channel event: #{trust.inspect}. " \
+            "Must be one of: #{Spurline::Security::Content::TRUST_LEVELS.inspect}."
+        end
+      end
+
+      def deep_freeze(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.freeze] = deep_freeze(v) }.freeze
+        when Array
+          obj.map { |v| deep_freeze(v) }.freeze
+        when String
+          obj.dup.freeze
+        else
+          obj.freeze
+        end
+      end
+
+      def unfreeze_hash(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k] = unfreeze_hash(v) }
+        when Array
+          obj.map { |v| unfreeze_hash(v) }
+        else
+          obj
+        end
+      end
+
+      def self.symbolize_keys(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(k, v), h|
+          h[k.to_sym] = v.is_a?(Hash) ? symbolize_keys(v) : v
+        end
+      end
+    end
+  end
+end

data/lib/spurline/channels/github.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Channels
+    # GitHub webhook channel. Parses issue_comment, pull_request_review_comment,
+    # and pull_request_review events. Routes to sessions whose metadata contains
+    # a matching channel_context.
+    #
+    # Session affinity is resolved by matching:
+    #   session.metadata[:channel_context] == { channel: :github, identifier: "owner/repo#123" }
+    #
+    # All GitHub webhook data enters at trust level :external.
+    class GitHub < Base
+      SUPPORTED_EVENTS = %i[
+        issue_comment
+        pull_request_review_comment
+        pull_request_review
+      ].freeze
+
+      # Maps GitHub webhook X-GitHub-Event header values to internal event types.
+      EVENT_MAP = {
+        "issue_comment" => :issue_comment,
+        "pull_request_review_comment" => :pull_request_review_comment,
+        "pull_request_review" => :pull_request_review,
+      }.freeze
+
+      attr_reader :store
+
+      def initialize(store:)
+        @store = store
+      end
+
+      def channel_name
+        :github
+      end
+
+      def supported_events
+        SUPPORTED_EVENTS
+      end
+
+      # Parses a GitHub webhook payload and routes to a matching session.
+      #
+      # @param payload [Hash] Parsed JSON body of the webhook
+      # @param headers [Hash] HTTP headers, expects "X-GitHub-Event" key
+      # @return [Spurline::Channels::Event, nil]
+      # ASYNC-READY:
+      def route(payload, headers: {})
+        event_header = headers["X-GitHub-Event"] || headers["x-github-event"]
+        return nil unless event_header
+
+        event_type = EVENT_MAP[event_header]
+        return nil unless event_type
+
+        action = payload_value(payload, :action)
+        return nil unless actionable?(event_type, action)
+
+        parsed = parse_event(event_type, payload)
+        return nil unless parsed
+
+        identifier = build_identifier(parsed)
+        session_id = find_session_by_context(identifier)
+
+        Event.new(
+          channel: :github,
+          event_type: event_type,
+          payload: parsed,
+          trust: :external,
+          session_id: session_id,
+          received_at: Time.now
+        )
+      end
+
+      private
+
+      # Determines if the action is one we care about.
+      def actionable?(event_type, action)
+        case event_type
+        when :issue_comment
+          %w[created edited].include?(action)
+        when :pull_request_review_comment
+          %w[created edited].include?(action)
+        when :pull_request_review
+          %w[submitted edited].include?(action)
+        else
+          false
+        end
+      end
+
+      # Extracts relevant fields from the webhook payload.
+      def parse_event(event_type, payload)
+        case event_type
+        when :issue_comment
+          parse_issue_comment(payload)
+        when :pull_request_review_comment
+          parse_pr_review_comment(payload)
+        when :pull_request_review
+          parse_pr_review(payload)
+        end
+      end
+
+      def parse_issue_comment(payload)
+        comment = payload_value(payload, :comment) || {}
+        issue = payload_value(payload, :issue) || {}
+        repo = payload_value(payload, :repository) || {}
+        pr = payload_value(issue, :pull_request)
+
+        # Only handle comments on pull requests, not issues
+        return nil unless pr
+
+        {
+          action: payload_value(payload, :action),
+          body: payload_value(comment, :body),
+          author: dig_value(comment, :user, :login),
+          pr_number: payload_value(issue, :number),
+          repo_full_name: payload_value(repo, :full_name),
+          comment_id: payload_value(comment, :id),
+          html_url: payload_value(comment, :html_url),
+        }
+      end
+
+      def parse_pr_review_comment(payload)
+        comment = payload_value(payload, :comment) || {}
+        pr = payload_value(payload, :pull_request) || {}
+        repo = payload_value(payload, :repository) || {}
+
+        {
+          action: payload_value(payload, :action),
+          body: payload_value(comment, :body),
+          author: dig_value(comment, :user, :login),
+          pr_number: payload_value(pr, :number),
+          repo_full_name: payload_value(repo, :full_name),
+          comment_id: payload_value(comment, :id),
+          path: payload_value(comment, :path),
+          diff_hunk: payload_value(comment, :diff_hunk),
+          html_url: payload_value(comment, :html_url),
+        }
+      end
+
+      def parse_pr_review(payload)
+        review = payload_value(payload, :review) || {}
+        pr = payload_value(payload, :pull_request) || {}
+        repo = payload_value(payload, :repository) || {}
+
+        {
+          action: payload_value(payload, :action),
+          body: payload_value(review, :body),
+          author: dig_value(review, :user, :login),
+          state: payload_value(review, :state),
+          pr_number: payload_value(pr, :number),
+          repo_full_name: payload_value(repo, :full_name),
+          review_id: payload_value(review, :id),
+          html_url: payload_value(review, :html_url),
+        }
+      end
+
+      # Builds the channel_context identifier string: "owner/repo#pr_number"
+      def build_identifier(parsed)
+        repo = parsed[:repo_full_name]
+        pr = parsed[:pr_number]
+        return nil unless repo && pr
+
+        "#{repo}##{pr}"
+      end
+
+      # Searches the session store for a suspended session with matching channel_context.
+      def find_session_by_context(identifier)
+        return nil unless identifier
+        return nil unless @store.respond_to?(:ids)
+
+        @store.ids.each do |id|
+          session = @store.load(id)
+          next unless session
+          next unless session.state == :suspended
+
+          context = session.metadata[:channel_context]
+          next unless context.is_a?(Hash)
+          next unless context[:channel]&.to_sym == :github
+          next unless context[:identifier] == identifier
+
+          return session.id
+        end
+
+        nil
+      end
+
+      # Safe hash value access supporting both symbol and string keys.
+      def payload_value(hash, key)
+        return nil unless hash.is_a?(Hash)
+
+        hash[key] || hash[key.to_s]
+      end
+
+      # Safe nested hash access.
+      def dig_value(hash, *keys)
+        result = hash
+        keys.each do |key|
+          return nil unless result.is_a?(Hash)
+
+          result = result[key] || result[key.to_s]
+        end
+        result
+      end
+    end
+  end
+end

data/lib/spurline/channels/router.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Spurline
+  module Channels
+    # Central dispatcher for channel events. Accepts raw payloads, identifies
+    # the correct channel, calls route, and optionally resumes suspended sessions.
+    #
+    # The router is transport-agnostic -- it processes parsed payloads, not HTTP
+    # requests. Webhook endpoints (Rack middleware, Rails controllers) are the
+    # caller's responsibility.
+    #
+    # Usage:
+    #   store = Spurline::Session::Store::Memory.new
+    #   github = Spurline::Channels::GitHub.new(store: store)
+    #   router = Spurline::Channels::Router.new(store: store, channels: [github])
+    #
+    #   event = router.dispatch(channel_name: :github, payload: webhook_body, headers: headers)
+    #   if event&.routed?
+    #     agent = MyAgent.new(session_id: event.session_id)
+    #     agent.resume { |chunk| ... }
+    #   end
+    #
+    class Router
+      attr_reader :store
+
+      def initialize(store:, channels: [])
+        @store = store
+        @channels = {}
+        channels.each { |ch| register(ch) }
+      end
+
+      # Registers a channel adapter.
+      def register(channel)
+        unless channel.respond_to?(:channel_name) && channel.respond_to?(:route)
+          raise ArgumentError,
+            "Channel must implement #channel_name and #route. Got #{channel.class.name}."
+        end
+
+        @channels[channel.channel_name.to_sym] = channel
+      end
+
+      # Returns all registered channel names.
+      def channel_names
+        @channels.keys
+      end
+
+      # Returns a registered channel by name, or nil.
+      def channel_for(name)
+        @channels[name.to_sym]
+      end
+
+      # Dispatches a payload to the named channel and returns the resulting Event.
+      #
+      # If the event maps to a suspended session, the router calls
+      # Suspension.resume! to transition the session back to :running.
+      # The caller is then responsible for instantiating the agent and
+      # calling agent.resume.
+      #
+      # @param channel_name [Symbol] The channel to dispatch to
+      # @param payload [Hash] The parsed event payload
+      # @param headers [Hash] Optional HTTP headers
+      # @return [Spurline::Channels::Event, nil]
+      # ASYNC-READY:
+      def dispatch(channel_name:, payload:, headers: {})
+        channel = @channels[channel_name.to_sym]
+        return nil unless channel
+
+        event = channel.route(payload, headers: headers)
+        return nil unless event
+
+        resume_if_suspended!(event) if event.routed?
+
+        event
+      end
+
+      # Wraps an event's payload as a Content object via Gates::ToolResult.
+      # Use this when feeding the event payload into the context pipeline.
+      def wrap_payload(event)
+        text = event.payload.is_a?(Hash) ? JSON.generate(event.payload) : event.payload.to_s
+        Security::Gates::ToolResult.wrap(
+          text,
+          tool_name: "channel:#{event.channel}"
+        )
+      end
+
+      private
+
+      def resume_if_suspended!(event)
+        session = @store.load(event.session_id)
+        return unless session
+        return unless session.state == :suspended
+
+        Session::Suspension.resume!(session)
+      rescue Spurline::InvalidResumeError
+        # Session is not actually suspended -- the channel's routing may be stale.
+        # Swallow the error; the caller can inspect the event and decide.
+        nil
+      end
+    end
+  end
+end

data/lib/spurline/cli/check.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Spurline
+  module CLI
+    class Check
+      CHECKERS = [
+        Checks::ProjectStructure,
+        Checks::Permissions,
+        Checks::AgentLoadability,
+        Checks::AdapterResolution,
+        Checks::Credentials,
+        Checks::SessionStore,
+      ].freeze
+
+      def initialize(project_root:, verbose: false)
+        @project_root = File.expand_path(project_root)
+        @verbose = verbose
+      end
+
+      def run!
+        results = run_checks
+        print_report(results)
+        results
+      end
+
+      private
+
+      attr_reader :project_root, :verbose
+
+      def run_checks
+        CHECKERS.flat_map do |checker_class|
+          checker_class.new(project_root: project_root).run
+        rescue StandardError => e
+          [Checks::CheckResult.new(
+            status: :fail,
+            name: checker_name(checker_class),
+            message: "#{e.class}: #{e.message}"
+          )]
+        end
+      end
+
+      def print_report(results)
+        puts "spur check"
+        puts
+
+        results.each do |result|
+          label = status_label(result.status)
+          line = "  #{label.ljust(5)} #{result.name}"
+          if show_message?(result) && result.message && !result.message.empty?
+            line << " - #{result.message}"
+          end
+          puts line
+        end
+
+        puts
+        passes = results.count { |result| result.status == :pass }
+        failures = results.count { |result| result.status == :fail }
+        warnings = results.count { |result| result.status == :warn }
+
+        puts "#{passes} passed, #{failures} failed, #{warnings} #{warnings == 1 ? "warning" : "warnings"}"
+      end
+
+      def show_message?(result)
+        verbose || result.status != :pass
+      end
+
+      def status_label(status)
+        case status
+        when :pass
+          "ok"
+        when :warn
+          "WARN"
+        when :fail
+          "FAIL"
+        else
+          status.to_s.upcase
+        end
+      end
+
+      def checker_name(checker_class)
+        checker_class.name.split("::").last
+          .gsub(/([a-z])([A-Z])/, '\1_\2')
+          .downcase
+          .to_sym
+      end
+    end
+  end
+end

data/lib/spurline/cli/checks/adapter_resolution.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Spurline
+  module CLI
+    module Checks
+      class AdapterResolution < Base
+        def run
+          load_framework!
+          files = agent_files
+
+          if files.empty?
+            return [fail(:adapter_resolution, message: "No agent files found under app/agents")]
+          end
+
+          files.each { |file| require file }
+          agents = resolve_agent_classes
+
+          if agents.empty?
+            return [fail(:adapter_resolution, message: "No Spurline::Agent subclasses found in app/agents")]
+          end
+
+          unresolved = []
+
+          agents.each do |agent_class|
+            model_name = agent_class.model_config && agent_class.model_config[:name]
+            if model_name.nil?
+              unresolved << "#{agent_class.name} has no model configuration"
+              next
+            end
+
+            begin
+              agent_class.adapter_registry.resolve(model_name)
+            rescue Spurline::AdapterNotFoundError => e
+              unresolved << "#{agent_class.name}: #{e.message}"
+            end
+          end
+
+          if unresolved.empty?
+            [pass(:adapter_resolution)]
+          else
+            [fail(:adapter_resolution, message: unresolved.join("; "))]
+          end
+        rescue LoadError, NameError, SyntaxError => e
+          [fail(:adapter_resolution, message: "#{e.class}: #{e.message}")]
+        end
+
+        private
+
+        def load_framework!
+          initializer = File.join(project_root, "config", "spurline.rb")
+          if File.file?(initializer)
+            require initializer
+          else
+            require "spurline"
+          end
+        end
+
+        def agent_files
+          files = Dir[File.join(project_root, "app", "agents", "**", "*.rb")]
+          files.sort_by do |path|
+            [File.basename(path) == "application_agent.rb" ? 0 : 1, path]
+          end
+        end
+
+        def resolve_agent_classes
+          agents_root = File.join(project_root, "app", "agents")
+
+          ObjectSpace.each_object(Class).select do |klass|
+            next false unless klass < Spurline::Agent
+            next false unless klass.name
+
+            source_path = Object.const_source_location(klass.name)&.first
+            next false unless source_path
+
+            File.expand_path(source_path).start_with?(File.expand_path(agents_root))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/cli/checks/agent_loadability.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Spurline
+  module CLI
+    module Checks
+      class AgentLoadability < Base
+        def run
+          load_framework!
+          files = agent_files
+
+          if files.empty?
+            return [fail(:agent_loadability, message: "No agent files found under app/agents")]
+          end
+
+          files.each { |file| require file }
+          [pass(:agent_loadability)]
+        rescue LoadError, NameError, SyntaxError => e
+          [fail(:agent_loadability, message: "#{e.class}: #{e.message}")]
+        end
+
+        private
+
+        def load_framework!
+          initializer = File.join(project_root, "config", "spurline.rb")
+          if File.file?(initializer)
+            require initializer
+          else
+            require "spurline"
+          end
+        end
+
+        def agent_files
+          files = Dir[File.join(project_root, "app", "agents", "**", "*.rb")]
+          files.sort_by do |path|
+            [File.basename(path) == "application_agent.rb" ? 0 : 1, path]
+          end
+        end
+      end
+    end
+  end
+end