spurline-docs 0.3.0

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

data/lib/spurline/cli/credentials.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "openssl"
+require "securerandom"
+require "shellwords"
+require "tempfile"
+require "yaml"
+
+module Spurline
+  module CLI
+    class Credentials
+      DEFAULT_TEMPLATE = <<~YAML
+        # Spurline credentials - encrypted at rest.
+        # Edit with: spur credentials:edit
+        #
+        anthropic_api_key: ""
+        # brave_api_key: ""
+      YAML
+
+      IV_BYTES = 12
+      AUTH_TAG_BYTES = 16
+      KEY_BYTES = 32
+
+      def initialize(project_root:)
+        @project_root = File.expand_path(project_root)
+      end
+
+      def edit!
+        ensure_master_key!
+        plaintext = File.file?(credentials_path) ? decrypt_existing_credentials : project_template
+
+        Tempfile.create(["spurline-credentials", ".yml"]) do |file|
+          path = file.path
+          File.write(path, plaintext)
+          open_editor!(file.path)
+          edited = File.read(path)
+          parse_yaml(edited)
+          encrypt_and_write(edited)
+        end
+      end
+
+      def read
+        return {} unless File.file?(credentials_path)
+
+        parse_yaml(decrypt_existing_credentials)
+      end
+
+      def master_key
+        @master_key ||= resolve_master_key
+      end
+
+      private
+
+      attr_reader :project_root
+
+      def project_template
+        template_path = File.join(project_root, "config", "credentials.template.yml")
+        File.file?(template_path) ? File.read(template_path) : DEFAULT_TEMPLATE
+      end
+
+      def credentials_path
+        File.join(project_root, "config", "credentials.enc.yml")
+      end
+
+      def master_key_path
+        File.join(project_root, "config", "master.key")
+      end
+
+      def ensure_master_key!
+        return if master_key
+
+        generate_master_key!
+        @master_key = resolve_master_key
+      end
+
+      def generate_master_key!
+        FileUtils.mkdir_p(File.dirname(master_key_path))
+        hex_key = SecureRandom.random_bytes(KEY_BYTES).unpack1("H*")
+        File.write(master_key_path, "#{hex_key}\n")
+        File.chmod(0o600, master_key_path)
+      end
+
+      def resolve_master_key
+        hex = ENV.fetch("SPURLINE_MASTER_KEY", nil)
+        hex = read_master_key_file if hex.nil? || hex.strip.empty?
+        return nil if hex.nil? || hex.strip.empty?
+
+        decode_hex_key(hex)
+      end
+
+      def read_master_key_file
+        return nil unless File.file?(master_key_path)
+
+        File.read(master_key_path)
+      end
+
+      def decode_hex_key(hex)
+        stripped = hex.to_s.strip
+        unless stripped.match?(/\A[0-9a-fA-F]{#{KEY_BYTES * 2}}\z/)
+          raise Spurline::CredentialsMissingKeyError,
+            "Master key must be #{KEY_BYTES * 2} hex characters"
+        end
+
+        [stripped].pack("H*")
+      end
+
+      def decrypt_existing_credentials
+        key = master_key
+        unless key
+          raise Spurline::CredentialsMissingKeyError,
+            "Missing master key. Set SPURLINE_MASTER_KEY or create config/master.key"
+        end
+
+        payload = File.binread(credentials_path)
+        decrypt(payload, key)
+      end
+
+      def encrypt_and_write(plaintext)
+        key = master_key
+        unless key
+          raise Spurline::CredentialsMissingKeyError,
+            "Missing master key. Set SPURLINE_MASTER_KEY or create config/master.key"
+        end
+
+        payload = encrypt(plaintext, key)
+        FileUtils.mkdir_p(File.dirname(credentials_path))
+        File.binwrite(credentials_path, payload)
+      end
+
+      def encrypt(plaintext, key)
+        cipher = OpenSSL::Cipher.new("aes-256-gcm")
+        cipher.encrypt
+        cipher.key = key
+        iv = SecureRandom.random_bytes(IV_BYTES)
+        cipher.iv = iv
+        ciphertext = cipher.update(plaintext) + cipher.final
+        tag = cipher.auth_tag
+        iv + tag + ciphertext
+      end
+
+      def decrypt(payload, key)
+        unless payload && payload.bytesize >= (IV_BYTES + AUTH_TAG_BYTES)
+          raise Spurline::CredentialsDecryptionError, "Encrypted credentials file is invalid"
+        end
+
+        iv = payload.byteslice(0, IV_BYTES)
+        tag = payload.byteslice(IV_BYTES, AUTH_TAG_BYTES)
+        ciphertext = payload.byteslice(IV_BYTES + AUTH_TAG_BYTES, payload.bytesize)
+
+        cipher = OpenSSL::Cipher.new("aes-256-gcm")
+        cipher.decrypt
+        cipher.key = key
+        cipher.iv = iv
+        cipher.auth_tag = tag
+        cipher.update(ciphertext) + cipher.final
+      rescue OpenSSL::Cipher::CipherError
+        raise Spurline::CredentialsDecryptionError, "Could not decrypt credentials with provided master key"
+      end
+
+      def open_editor!(path)
+        editor = ENV.fetch("EDITOR", "vi")
+        command = Shellwords.split(editor)
+        ok = system(*command, path)
+        return if ok
+
+        raise Spurline::ConfigurationError, "EDITOR command failed: #{editor}"
+      end
+
+      def parse_yaml(content)
+        parsed = YAML.safe_load(content, aliases: false)
+        return {} if parsed.nil?
+        return parsed.transform_keys(&:to_s) if parsed.is_a?(Hash)
+
+        raise Spurline::ConfigurationError, "Credentials YAML must contain a mapping"
+      rescue Psych::SyntaxError => e
+        raise Spurline::ConfigurationError, "Invalid credentials YAML: #{e.message}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Spurline
+  module CLI
+    module Generators
+      # Generates a new agent class file.
+      # Usage: spur generate agent research
+      class Agent
+        attr_reader :name
+
+        def initialize(name:)
+          @name = name.to_s
+        end
+
+        def generate!
+          verify_project_structure!
+
+          path = File.join("app", "agents", "#{snake_name}_agent.rb")
+
+          if File.exist?(path)
+            $stderr.puts "File already exists: #{path}"
+            exit 1
+          end
+
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, agent_template)
+          puts "  create  #{path}"
+
+          generate_spec_file!
+        end
+
+        private
+
+        def verify_project_structure!
+          unless Dir.exist?("app/agents")
+            $stderr.puts "No app/agents directory found. " \
+                         "Run this from a Spurline project root, or run 'spur new' first."
+            exit 1
+          end
+
+          unless File.exist?(File.join("app", "agents", "application_agent.rb"))
+            $stderr.puts "No application_agent.rb found. Run 'spur new' first."
+            exit 1
+          end
+        end
+
+        def agent_template
+          <<~RUBY
+            # frozen_string_literal: true
+
+            require_relative "application_agent"
+
+            class #{class_name}Agent < ApplicationAgent
+              persona(:default) do
+                system_prompt "You are a #{name.tr("_", " ")} agent."
+              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 generate_spec_file!
+          spec_path = File.join("spec", "agents", "#{snake_name}_agent_spec.rb")
+          if File.exist?(spec_path)
+            puts "  skip    #{spec_path} (already exists)"
+            return
+          end
+
+          FileUtils.mkdir_p(File.dirname(spec_path))
+          File.write(spec_path, spec_template)
+          puts "  create  #{spec_path}"
+        end
+
+        def spec_template
+          <<~RUBY
+            # frozen_string_literal: true
+
+            RSpec.describe #{class_name}Agent do
+              let(:agent) do
+                described_class.new.tap do |a|
+                  a.use_stub_adapter(responses: [stub_text("Test response")])
+                end
+              end
+
+              describe "#run" do
+                it "streams a response" do
+                  chunks = []
+                  agent.run("Test input") { |chunk| chunks << chunk }
+                  text = chunks.select(&:text?).map(&:text).join
+                  expect(text).not_to be_empty
+                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/generators/migration.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Spurline
+  module CLI
+    module Generators
+      # Generates built-in SQL migrations.
+      # Usage: spur generate migration sessions
+      class Migration
+        MIGRATIONS = { "sessions" => :sessions_migration_sql }.freeze
+
+        attr_reader :name
+
+        def initialize(name:)
+          @name = name.to_s
+        end
+
+        def generate!
+          unless MIGRATIONS.key?(name)
+            $stderr.puts "Unknown migration: #{name}. Available: #{MIGRATIONS.keys.join(", ")}"
+            exit 1
+          end
+
+          if Dir.glob(File.join("db", "migrations", "*_create_spurline_#{name}.sql")).any?
+            $stderr.puts "Migration for #{name} already exists."
+            exit 1
+          end
+
+          timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+          filename = "#{timestamp}_create_spurline_#{name}.sql"
+          path = File.join("db", "migrations", filename)
+
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, send(MIGRATIONS[name]))
+          puts "  create  #{path}"
+        end
+
+        private
+
+        def sessions_migration_sql
+          <<~SQL
+            CREATE TABLE IF NOT EXISTS spurline_sessions (
+              id TEXT PRIMARY KEY,
+              state TEXT NOT NULL,
+              agent_class TEXT,
+              created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+              updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+              data JSONB NOT NULL
+            );
+
+            CREATE INDEX IF NOT EXISTS idx_spurline_sessions_state
+              ON spurline_sessions(state);
+
+            CREATE INDEX IF NOT EXISTS idx_spurline_sessions_agent_class
+              ON spurline_sessions(agent_class);
+          SQL
+        end
+      end
+    end
+  end
+end