spurline-core 0.3.0

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/CLAUDE.md

@@ -0,0 +1,11 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 21, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #3661 | 7:57 PM | 🔵 | Code quality review confirmed Plans 01-02 are production-ready with zero issues | ~791 |
+</claude-mem-context>

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

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Spurline
+  module CLI
+    module Checks
+      CheckResult = Data.define(:status, :name, :message)
+
+      class Base
+        def initialize(project_root:)
+          @project_root = File.expand_path(project_root)
+        end
+
+        def run
+          raise NotImplementedError
+        end
+
+        private
+
+        attr_reader :project_root
+
+        def pass(name, message: nil)
+          CheckResult.new(status: :pass, name: name, message: message)
+        end
+
+        def fail(name, message:)
+          CheckResult.new(status: :fail, name: name, message: message)
+        end
+
+        def warn(name, message:)
+          CheckResult.new(status: :warn, name: name, message: message)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Spurline
+  module CLI
+    module Checks
+      class Credentials < Base
+        WARNING_MESSAGE = "ANTHROPIC_API_KEY not set; agents using :claude_sonnet will fail at runtime"
+
+        def run
+          env_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
+          return [pass(:credentials)] if present_key?(env_key)
+
+          credentials_path = File.join(project_root, "config", "credentials.enc.yml")
+          unless File.file?(credentials_path)
+            return [warn(:credentials, message: WARNING_MESSAGE)]
+          end
+
+          manager = Spurline::CLI::Credentials.new(project_root: project_root)
+          unless manager.master_key
+            return [warn(:credentials, message: "#{WARNING_MESSAGE}; master key not found")]
+          end
+
+          credentials = manager.read
+          if present_key?(credentials["anthropic_api_key"])
+            [pass(:credentials)]
+          else
+            [warn(:credentials, message: "#{WARNING_MESSAGE}; encrypted anthropic_api_key is blank")]
+          end
+        rescue Spurline::CredentialsMissingKeyError => e
+          [warn(:credentials, message: "#{WARNING_MESSAGE}; #{e.message}")]
+        rescue StandardError => e
+          [fail(:credentials, message: "#{e.class}: #{e.message}")]
+        end
+
+        private
+
+        def present_key?(value)
+          value && !value.strip.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Spurline
+  module CLI
+    module Checks
+      class Permissions < Base
+        def run
+          path = File.join(project_root, "config", "permissions.yml")
+
+          unless File.file?(path)
+            return [fail(:permissions, message: "Missing config/permissions.yml")]
+          end
+
+          Spurline::Tools::Permissions.load_file(path)
+          [pass(:permissions)]
+        rescue StandardError => e
+          [fail(:permissions, message: "#{e.class}: #{e.message}")]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Spurline
+  module CLI
+    module Checks
+      class ProjectStructure < Base
+        REQUIRED_DIRECTORIES = %w[app/agents app/tools config].freeze
+        REQUIRED_FILES = %w[Gemfile].freeze
+        RECOMMENDED_FILES = %w[config/spurline.rb config/permissions.yml .env.example].freeze
+
+        def run
+          missing = []
+          results = []
+
+          REQUIRED_DIRECTORIES.each do |directory|
+            path = File.join(project_root, directory)
+            missing << directory unless Dir.exist?(path)
+          end
+
+          REQUIRED_FILES.each do |file|
+            path = File.join(project_root, file)
+            missing << file unless File.file?(path)
+          end
+
+          if missing.empty?
+            results << pass(:project_structure)
+          else
+            results << fail(
+              :project_structure,
+              message: "Missing required paths: #{missing.join(", ")}. " \
+                       "Run 'spur new <project>' to create a project scaffold."
+            )
+            return results
+          end
+
+          RECOMMENDED_FILES.each do |file|
+            path = File.join(project_root, file)
+            next if File.file?(path)
+
+            results << warn(:"missing_#{file.tr('/.', '_')}", message: "Recommended file missing: #{file}")
+          end
+
+          results
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Spurline
+  module CLI
+    module Checks
+      class SessionStore < Base
+        def run
+          load_framework!
+
+          case Spurline.config.session_store
+          when nil, :memory
+            [pass(:session_store)]
+          when :sqlite
+            validate_sqlite_store
+          when :postgres
+            validate_postgres_store
+          else
+            [pass(:session_store, message: "Custom session store configured; skipped built-in validation")]
+          end
+        rescue StandardError => e
+          [fail(:session_store, 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 validate_sqlite_store
+          require "sqlite3"
+
+          path = Spurline.config.session_store_path
+          return [pass(:session_store)] if path == ":memory:"
+
+          expanded = File.expand_path(path, project_root)
+          parent = File.dirname(expanded)
+
+          if writable_path?(parent)
+            [pass(:session_store)]
+          else
+            [fail(:session_store, message: "Session store directory is not writable: #{parent}")]
+          end
+        rescue LoadError
+          [fail(:session_store, message: "sqlite3 gem is not available for :sqlite session store")]
+        end
+
+        def validate_postgres_store
+          url = Spurline.config.session_store_postgres_url
+          return [fail(:session_store, message: "session_store_postgres_url is not configured")] unless url && !url.strip.empty?
+
+          require "pg"
+
+          conn = PG.connect(url)
+          conn.exec("SELECT 1")
+          conn.close
+          [pass(:session_store)]
+        rescue LoadError
+          [fail(:session_store, message: "pg gem is not available for :postgres session store")]
+        rescue StandardError => e
+          if defined?(PG::Error) && e.is_a?(PG::Error)
+            [fail(:session_store, message: "Cannot connect to PostgreSQL: #{e.message}")]
+          else
+            raise
+          end
+        end
+
+        def writable_path?(path)
+          if Dir.exist?(path)
+            return File.writable?(path)
+          end
+
+          nearest_existing_ancestor(path).then do |ancestor|
+            ancestor && File.writable?(ancestor)
+          end
+        end
+
+        def nearest_existing_ancestor(path)
+          current = File.expand_path(path)
+          loop do
+            return current if Dir.exist?(current)
+
+            parent = File.dirname(current)
+            return nil if parent == current
+
+            current = parent
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/cli/console.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Spurline
+  module CLI
+    class Console
+      def initialize(project_root:, verbose: false)
+        @project_root = File.expand_path(project_root)
+        @verbose = verbose
+      end
+
+      def start!
+        ensure_project!
+
+        begin
+          load_project!
+        rescue StandardError => e
+          $stderr.puts "Project load error: #{e.class}: #{e.message}"
+        end
+
+        run_check! if verbose
+        start_repl!
+      end
+
+      private
+
+      attr_reader :project_root, :verbose
+
+      def ensure_project!
+        agents_dir = File.join(project_root, "app", "agents")
+        return if Dir.exist?(agents_dir)
+
+        $stderr.puts "No app/agents directory found. Run this command from a Spurline project root."
+        exit 1
+      end
+
+      def load_project!
+        initializer = File.join(project_root, "config", "spurline.rb")
+        if File.file?(initializer)
+          require initializer
+        else
+          require "spurline"
+        end
+
+        app_files.each { |file| require file }
+      end
+
+      def app_files
+        files = Dir[File.join(project_root, "app", "**", "*.rb")]
+        files.sort_by do |path|
+          [File.basename(path) == "application_agent.rb" ? 0 : 1, path]
+        end
+      end
+
+      def run_check!
+        Check.new(project_root: project_root).run!
+      rescue StandardError => e
+        $stderr.puts "Check error: #{e.class}: #{e.message}"
+      end
+
+      def start_repl!
+        require "irb"
+
+        puts "Spurline console v#{Spurline::VERSION}"
+        puts "Type 'exit' to quit."
+        original_argv = ARGV.dup
+        ARGV.replace([])
+        Dir.chdir(project_root) { IRB.start }
+      ensure
+        ARGV.replace(original_argv) if original_argv
+      end
+    end
+  end
+end