spurline-test 0.3.0

data/lib/spurline/cli/generators/project.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Spurline
+  module CLI
+    module Generators
+      # Generates a new Spurline agent project scaffold.
+      # Usage: spur new my_agent
+      class Project
+        attr_reader :name, :root
+
+        def initialize(name:)
+          @name = name
+          @root = File.expand_path(name)
+        end
+
+        def generate!
+          if Dir.exist?(root)
+            $stderr.puts "Directory '#{name}' already exists."
+            exit 1
+          end
+
+          puts "Creating new Spurline project: #{name}"
+
+          create_directories!
+          create_gemfile!
+          create_rakefile!
+          create_initializer!
+          create_application_agent!
+          create_example_agent!
+          create_spec_helper!
+          create_example_agent_spec!
+          create_permissions!
+          create_gitignore!
+          create_ruby_version!
+          create_env_example!
+          create_readme!
+
+          puts ""
+          puts "Project '#{name}' created successfully!"
+          puts ""
+          puts "Next steps:"
+          puts "  cd #{name}"
+          puts "  bundle install"
+          puts "  bundle exec rspec"
+          puts ""
+        end
+
+        private
+
+        def create_directories!
+          dirs = %w[
+            app/agents
+            app/tools
+            config
+            spec
+            spec/agents
+            spec/tools
+          ]
+          dirs.each { |dir| FileUtils.mkdir_p(File.join(root, dir)) }
+        end
+
+        def create_gemfile!
+          write_file("Gemfile", <<~RUBY)
+            # frozen_string_literal: true
+
+            source "https://rubygems.org"
+
+            gem "spurline-core"
+
+            # Uncomment to add bundled spurs:
+            # gem "spurline-web-search"
+
+            group :development, :test do
+              gem "rspec"
+              # gem "webmock"   # Useful for testing tools that make HTTP calls
+            end
+          RUBY
+        end
+
+        def create_rakefile!
+          write_file("Rakefile", <<~RUBY)
+            # frozen_string_literal: true
+
+            require "rspec/core/rake_task"
+            RSpec::Core::RakeTask.new(:spec)
+            task default: :spec
+          RUBY
+        end
+
+        def create_initializer!
+          write_file("config/spurline.rb", <<~RUBY)
+            # frozen_string_literal: true
+
+            require "spurline"
+
+            Spurline.configure do |config|
+              config.default_model = :claude_sonnet
+              config.session_store = :memory
+              config.permissions_file = "config/permissions.yml"
+
+              # Durable sessions (survives process restart):
+              # config.session_store = :sqlite
+              # config.session_store_path = "tmp/spurline_sessions.db"
+              #
+              # PostgreSQL sessions (for team deployments):
+              # config.session_store = :postgres
+              # config.session_store_postgres_url = "postgresql://localhost/my_app_development"
+            end
+          RUBY
+        end
+
+        def create_application_agent!
+          write_file("app/agents/application_agent.rb", <<~RUBY)
+            # frozen_string_literal: true
+
+            require "spurline"
+
+            # The shared base class for all agents in this project.
+            # Configure defaults here -- individual agents inherit and override.
+            class ApplicationAgent < Spurline::Agent
+              use_model :claude_sonnet
+
+              guardrails do
+                max_tool_calls 10
+                injection_filter :strict
+                pii_filter :off
+              end
+
+              # Uncomment to add a default persona with date injection:
+              # persona(:default) do
+              #   system_prompt "You are a helpful assistant."
+              #   inject_date true
+              # end
+
+              # Uncomment to add lifecycle hooks:
+              # on_start  { |session| puts "Session \#{session.id} started" }
+              # on_finish { |session| puts "Session \#{session.id} finished" }
+              # on_error  { |error| $stderr.puts "Error: \#{error.message}" }
+
+              # Uncomment for memory window customization:
+              # memory :short_term, window: 20
+            end
+          RUBY
+        end
+
+        def create_example_agent!
+          write_file("app/agents/assistant_agent.rb", <<~RUBY)
+            # frozen_string_literal: true
+
+            require_relative "application_agent"
+
+            class AssistantAgent < ApplicationAgent
+              persona(:default) do
+                system_prompt "You are a helpful assistant for the #{classify(name)} project."
+                inject_date true
+              end
+
+              # Uncomment to register tools:
+              # tools :example_tool
+
+              # Uncomment to override guardrails from ApplicationAgent:
+              # guardrails do
+              #   max_tool_calls 5
+              # end
+            end
+          RUBY
+        end
+
+        def create_spec_helper!
+          write_file("spec/spec_helper.rb", <<~RUBY)
+            # frozen_string_literal: true
+
+            require_relative "../config/spurline"
+            require "spurline/testing"
+
+            # Load application files
+            Dir[File.join(__dir__, "..", "app", "**", "*.rb")].sort.each { |f| require f }
+
+            RSpec.configure do |config|
+              config.expect_with :rspec do |expectations|
+                expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+              end
+
+              config.mock_with :rspec do |mocks|
+                mocks.verify_partial_doubles = true
+              end
+
+              config.order = :random
+              Kernel.srand config.seed
+            end
+          RUBY
+        end
+
+        def create_example_agent_spec!
+          write_file("spec/agents/assistant_agent_spec.rb", <<~RUBY)
+            # frozen_string_literal: true
+
+            RSpec.describe AssistantAgent do
+              let(:agent) do
+                described_class.new.tap do |a|
+                  a.use_stub_adapter(responses: [stub_text("Hello!")])
+                end
+              end
+
+              describe "#run" do
+                it "streams a response" do
+                  chunks = []
+                  agent.run("Say hello") { |chunk| chunks << chunk }
+
+                  text = chunks.select(&:text?).map(&:text).join
+                  expect(text).to eq("Hello!")
+                end
+              end
+            end
+          RUBY
+        end
+
+        def create_permissions!
+          write_file("config/permissions.yml", <<~YAML)
+            # Tool permission configuration.
+            # See: https://github.com/dylanwilcox/spurline
+            #
+            # tools:
+            #   dangerous_tool:
+            #     denied: true
+            #   sensitive_tool:
+            #     requires_confirmation: true
+            #     allowed_users:
+            #       - admin
+            tools: {}
+          YAML
+        end
+
+        def create_gitignore!
+          write_file(".gitignore", <<~TEXT)
+            /.bundle/
+            /vendor/bundle
+            /tmp/
+            /log/
+            config/master.key
+            tmp/spurline_sessions.db
+            *.gem
+            .env
+            Gemfile.lock
+          TEXT
+        end
+
+        def create_ruby_version!
+          write_file(".ruby-version", "3.4.5\n")
+        end
+
+        def create_env_example!
+          write_file(".env.example", <<~TEXT)
+            # Spurline environment variables.
+            # Copy this file to .env and fill in your values.
+            # Never commit .env to version control.
+
+            ANTHROPIC_API_KEY=your_key_here
+
+            # Uncomment for encrypted credentials support:
+            # SPURLINE_MASTER_KEY=your_32_byte_hex_key
+          TEXT
+        end
+
+        def create_readme!
+          write_file("README.md", <<~MARKDOWN)
+            # #{classify(name)}
+
+            A [Spurline](https://github.com/dylanwilcox/spurline) agent project.
+
+            ## Setup
+
+            ```bash
+            bundle install
+            cp .env.example .env
+            # Edit .env with your ANTHROPIC_API_KEY
+            ```
+
+            ## Validate
+
+            ```bash
+            bundle exec spur check
+            ```
+
+            ## Run Tests
+
+            ```bash
+            bundle exec rspec
+            ```
+
+            ## Project Structure
+
+            ```
+            app/
+              agents/           # Agent classes (inherit from ApplicationAgent)
+              tools/            # Tool classes (inherit from Spurline::Tools::Base)
+            config/
+              spurline.rb       # Framework configuration
+              permissions.yml   # Tool permission rules
+            spec/               # RSpec test files
+            ```
+
+            ## Generators
+
+            ```bash
+            spur generate agent researcher    # Creates app/agents/researcher_agent.rb
+            spur generate tool web_scraper    # Creates app/tools/web_scraper.rb + spec
+            ```
+          MARKDOWN
+        end
+
+        def write_file(relative_path, content)
+          path = File.join(root, relative_path)
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, content)
+          puts "  create  #{relative_path}"
+        end
+
+        def classify(str)
+          str.to_s
+            .gsub(/[-_]/, " ")
+            .split(" ")
+            .map(&:capitalize)
+            .join
+        end
+      end
+    end
+  end
+end

data/lib/spurline/cli/generators/tool.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Spurline
+  module CLI
+    module Generators
+      # Generates a new tool class file.
+      # Usage: spur generate tool web_scraper
+      class Tool
+        attr_reader :name
+
+        def initialize(name:)
+          @name = name.to_s
+        end
+
+        def generate!
+          path = File.join("app", "tools", "#{snake_name}.rb")
+
+          if File.exist?(path)
+            $stderr.puts "File already exists: #{path}"
+            exit 1
+          end
+
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, tool_template)
+          puts "  create  #{path}"
+
+          spec_path = File.join("spec", "tools", "#{snake_name}_spec.rb")
+          FileUtils.mkdir_p(File.dirname(spec_path))
+          File.write(spec_path, spec_template)
+          puts "  create  #{spec_path}"
+        end
+
+        private
+
+        def tool_template
+          <<~RUBY
+            # frozen_string_literal: true
+
+            class #{class_name} < Spurline::Tools::Base
+              tool_name :#{snake_name}
+              description "TODO: Describe what #{snake_name} does"
+              parameters({
+                type: "object",
+                properties: {
+                  input: { type: "string", description: "TODO: describe input" },
+                },
+                required: %w[input],
+              })
+
+              def call(input:)
+                # TODO: Implement #{snake_name}
+                raise NotImplementedError, "#{class_name}#call not yet implemented"
+              end
+            end
+          RUBY
+        end
+
+        def spec_template
+          <<~RUBY
+            # frozen_string_literal: true
+
+            require_relative "../../app/tools/#{snake_name}"
+
+            RSpec.describe #{class_name} do
+              let(:tool) { described_class.new }
+
+              describe "#call" do
+                it "executes the tool" do
+                  # TODO: Write tests for #{snake_name}
+                  pending "implement #{class_name}#call first"
+                  result = tool.call(input: "test")
+                  expect(result).not_to be_nil
+                end
+              end
+            end
+          RUBY
+        end
+
+        def class_name
+          name.to_s
+            .gsub(/[-_]/, " ")
+            .split(" ")
+            .map(&:capitalize)
+            .join
+        end
+
+        def snake_name
+          name.to_s
+            .gsub(/([a-z])([A-Z])/, '\1_\2')
+            .gsub(/[-\s]/, "_")
+            .downcase
+        end
+      end
+    end
+  end
+end

data/lib/spurline/cli/router.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Spurline
+  module CLI
+    # Routes CLI commands to the appropriate handler.
+    # Entry point: Router.run(ARGV)
+    class Router
+      COMMANDS = {
+        "new" => :handle_new,
+        "generate" => :handle_generate,
+        "check" => :handle_check,
+        "console" => :handle_console,
+        "credentials:edit" => :handle_credentials_edit,
+        "version" => :handle_version,
+        "help" => :handle_help,
+      }.freeze
+
+      GENERATE_SUBCOMMANDS = %w[agent tool migration].freeze
+
+      def self.run(args)
+        new(args).dispatch
+      end
+
+      def initialize(args)
+        @args = args
+        @command = args.first
+        @rest = args[1..] || []
+      end
+
+      def dispatch
+        if @command.nil? || @command == "help" || @command == "--help" || @command == "-h"
+          handle_help
+        elsif @command == "version" || @command == "--version" || @command == "-v"
+          handle_version
+        elsif COMMANDS.key?(@command)
+          send(COMMANDS[@command])
+        else
+          $stderr.puts "Unknown command: #{@command}"
+          $stderr.puts "Run 'spur help' for available commands."
+          exit 1
+        end
+      end
+
+      private
+
+      def handle_new
+        project_name = @rest.first
+        unless project_name
+          $stderr.puts "Usage: spur new <project_name>"
+          exit 1
+        end
+
+        Generators::Project.new(name: project_name).generate!
+      end
+
+      def handle_generate
+        subcommand = @rest.first
+        name = @rest[1]
+
+        unless subcommand && GENERATE_SUBCOMMANDS.include?(subcommand)
+          $stderr.puts "Usage: spur generate <#{GENERATE_SUBCOMMANDS.join("|")}> <name>"
+          exit 1
+        end
+
+        unless name
+          $stderr.puts "Usage: spur generate #{subcommand} <name>"
+          exit 1
+        end
+
+        case subcommand
+        when "agent"
+          Generators::Agent.new(name: name).generate!
+        when "tool"
+          Generators::Tool.new(name: name).generate!
+        when "migration"
+          Generators::Migration.new(name: name).generate!
+        end
+      end
+
+      def handle_version
+        puts "spur #{Spurline::VERSION}"
+      end
+
+      def handle_check
+        verbose = @rest.include?("--verbose") || @rest.include?("-v")
+        results = Check.new(project_root: Dir.pwd, verbose: verbose).run!
+        failures = results.count { |result| result.status == :fail }
+        exit(failures.positive? ? 1 : 0)
+      end
+
+      def handle_console
+        verbose = @rest.include?("--verbose") || @rest.include?("-v")
+        Console.new(project_root: Dir.pwd, verbose: verbose).start!
+      end
+
+      def handle_credentials_edit
+        Credentials.new(project_root: Dir.pwd).edit!
+        puts "Saved encrypted credentials to config/credentials.enc.yml"
+      end
+
+      def handle_help
+        puts <<~HELP
+          spur — Spurline CLI
+
+          Commands:
+            spur new <project>           Create a new Spurline agent project
+            spur generate agent <name>   Generate a new agent class
+            spur generate tool <name>    Generate a new tool class
+            spur generate migration <name> Generate a SQL migration (e.g. sessions)
+            spur check                   Validate project configuration
+            spur console                 Interactive REPL with project loaded
+            spur credentials:edit        Edit encrypted credentials
+            spur version                 Show version
+            spur help                    Show this help
+
+          https://github.com/dylanwilcox/spurline
+        HELP
+      end
+    end
+  end
+end

data/lib/spurline/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "dry-configurable"
+
+module Spurline
+  class Configuration
+    extend Dry::Configurable
+
+    setting :session_store, default: :memory
+    setting :session_store_path, default: "tmp/spurline_sessions.db"
+    setting :session_store_postgres_url, default: nil
+    setting :default_model, default: :claude_sonnet
+    setting :log_level, default: :info
+    setting :audit_mode, default: :full
+    setting :audit_max_entries, default: nil
+    setting :idempotency_default_ttl, default: 86_400
+    setting :permissions_file, default: "config/permissions.yml"
+    setting :brave_api_key, default: nil
+    setting :cartographer_exclude_patterns, default: %w[
+      .git node_modules vendor tmp log coverage
+    ]
+  end
+end

data/lib/spurline/dsl/guardrails.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Spurline
+  module DSL
+    # DSL for configuring security guardrails.
+    # Registers configuration at class load time — never executes behavior.
+    # Misconfiguration raises ConfigurationError at class load time.
+    module Guardrails
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def guardrails(&block)
+          @guardrail_config ||= GuardrailConfig.new
+          @guardrail_config.instance_eval(&block)
+        end
+
+        def guardrail_config
+          own = @guardrail_config
+          if own
+            own
+          elsif superclass.respond_to?(:guardrail_config)
+            superclass.guardrail_config
+          else
+            GuardrailConfig.new
+          end
+        end
+      end
+
+      class GuardrailConfig
+        INJECTION_LEVELS = %i[strict moderate permissive].freeze
+        PII_MODES = %i[redact block warn off].freeze
+        AUDIT_MODES = %i[full errors_only off].freeze
+
+        attr_reader :settings
+
+        def initialize
+          @settings = {
+            injection_filter: :strict,
+            pii_filter: :off,
+            max_tool_calls: 10,
+            max_turns: 50,
+            audit_max_entries: nil,
+            denied_domains: [],
+            audit: :full,
+          }
+        end
+
+        def injection_filter(level)
+          validate_inclusion!(:injection_filter, level, INJECTION_LEVELS)
+          @settings[:injection_filter] = level
+        end
+
+        def pii_filter(mode)
+          validate_inclusion!(:pii_filter, mode, PII_MODES)
+          @settings[:pii_filter] = mode
+        end
+
+        def max_tool_calls(n)
+          validate_positive_integer!(:max_tool_calls, n)
+          @settings[:max_tool_calls] = n
+        end
+
+        def max_turns(n)
+          validate_positive_integer!(:max_turns, n)
+          @settings[:max_turns] = n
+        end
+
+        def audit_max_entries(n)
+          validate_positive_integer!(:audit_max_entries, n)
+          @settings[:audit_max_entries] = n
+        end
+
+        def denied_domains(domains)
+          @settings[:denied_domains] = Array(domains)
+        end
+
+        def audit(mode)
+          validate_inclusion!(:audit, mode, AUDIT_MODES)
+          @settings[:audit] = mode
+        end
+
+        def to_h
+          @settings.dup
+        end
+
+        private
+
+        def validate_inclusion!(name, value, valid_values)
+          return if valid_values.include?(value)
+
+          raise Spurline::ConfigurationError,
+            "Invalid guardrail value for #{name}: #{value.inspect}. " \
+            "Must be one of: #{valid_values.map(&:inspect).join(", ")}."
+        end
+
+        def validate_positive_integer!(name, value)
+          return if value.is_a?(Integer) && value.positive?
+
+          raise Spurline::ConfigurationError,
+            "Invalid guardrail value for #{name}: #{value.inspect}. " \
+            "Must be a positive integer."
+        end
+      end
+    end
+  end
+end