spurline-docs 0.3.0

data/lib/spurline/tools/runner.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+require "json"
+
+module Spurline
+  module Tools
+    # Executes tool calls with permission checking, confirmation, and result wrapping.
+    # Tool results always enter the pipeline as Content objects with trust: :external.
+    class Runner
+      attr_reader :registry
+
+      def initialize(registry:, guardrails: {}, permissions: {}, secret_resolver: nil, idempotency_configs: {})
+        @registry = registry
+        @guardrails = guardrails
+        @permissions = permissions
+        @secret_resolver = secret_resolver
+        @idempotency_configs = normalize_idempotency_configs(idempotency_configs)
+      end
+
+      # ASYNC-READY: scheduler param is the async entry point
+      def execute(
+        tool_call,
+        session:,
+        scheduler: Spurline::Adapters::Scheduler::Sync.new,
+        scope: nil,
+        idempotency_ledger: nil,
+        &confirmation_handler
+      )
+        tool_name = tool_call[:name].to_s
+        registered_tool = @registry.fetch(tool_name)
+        tool_class = registered_tool.is_a?(Class) ? registered_tool : registered_tool.class
+        tool = registered_tool.is_a?(Class) ? registered_tool.new : registered_tool
+
+        permission_check!(tool_name, session)
+        confirmation_check!(tool_name, tool_class, tool_call, &confirmation_handler)
+
+        started_at = Time.now
+        args = symbolize_keys(tool_call[:arguments])
+        if tool_class.respond_to?(:validate_arguments!)
+          tool_class.validate_arguments!(args)
+        end
+        scoped_tool = tool_class.respond_to?(:scoped?) && tool_class.scoped?
+        if scoped_tool && scope.nil?
+          raise Spurline::ScopeViolationError,
+            "Tool '#{tool_name}' is scoped and requires a scope, but none was provided."
+        end
+        scope_id = scoped_tool && scope.respond_to?(:id) ? scope.id.to_s : nil
+
+        idempotency = build_idempotency_context(
+          tool_name: tool_name,
+          tool_class: tool_class,
+          args: args,
+          scoped_tool: scoped_tool,
+          scope_id: scope_id,
+          idempotency_ledger: idempotency_ledger || (session.metadata[:idempotency_ledger] ||= {})
+        )
+
+        was_cached = false
+        cache_age_ms = nil
+        raw_result = nil
+
+        if idempotency[:enabled]
+          idempotency[:ledger].cached?(idempotency[:key], ttl: idempotency[:ttl])
+          if idempotency[:ledger].conflict?(idempotency[:key], idempotency[:args_hash])
+            raise Spurline::IdempotencyKeyConflictError,
+              "Tool '#{tool_name}' generated idempotency key '#{idempotency[:key]}' " \
+              "for different arguments in the same session."
+          end
+
+          cached_result = idempotency[:ledger].fetch(idempotency[:key], ttl: idempotency[:ttl])
+          unless cached_result.nil?
+            raw_result = cached_result
+            was_cached = true
+            cache_age_ms = idempotency[:ledger].cache_age_ms(idempotency[:key])
+          end
+        end
+
+        unless was_cached
+          args = inject_secrets(tool_class, args)
+          args = inject_scope(args, scope: scope) if scoped_tool
+          raw_result = scheduler.run { tool.call(**args) }
+        end
+
+        serialized_result = was_cached ? raw_result.to_s : serialize_result(raw_result)
+        if idempotency[:enabled] && !was_cached
+          idempotency[:ledger].store!(
+            idempotency[:key],
+            result: serialized_result,
+            args_hash: idempotency[:args_hash],
+            ttl: idempotency[:ttl]
+          )
+        end
+
+        duration_ms = ((Time.now - started_at) * 1000).round
+        arguments_for_audit = args.dup
+        arguments_for_audit.delete(:_scope)
+        arguments_for_audit[:_scope_id] = scope_id if scoped_tool && scope_id
+        filtered_arguments = Audit::SecretFilter.filter(
+          arguments_for_audit,
+          tool_name: tool_name,
+          registry: @registry
+        )
+
+        session.current_turn&.record_tool_call(
+          name: tool_name,
+          arguments: filtered_arguments,
+          result: raw_result,
+          duration_ms: duration_ms,
+          scope_id: scope_id,
+          idempotency_key: idempotency[:enabled] ? idempotency[:key] : nil,
+          was_cached: idempotency[:enabled] ? was_cached : nil,
+          cache_age_ms: cache_age_ms
+        )
+
+        Security::Gates::ToolResult.wrap(
+          serialized_result,
+          tool_name: tool_name
+        )
+      rescue ArgumentError => e
+        raise unless missing_keyword_argument_error?(e)
+
+        raise Spurline::ConfigurationError.new(
+          "Tool '#{tool_name}' received invalid arguments #{tool_call[:arguments].inspect}: #{e.message}"
+        ), cause: nil
+      rescue Spurline::ConfigurationError => e
+        raise Spurline::ConfigurationError.new(
+          "Invalid tool call for '#{tool_name}' with arguments #{tool_call[:arguments].inspect}: #{e.message}"
+        ), cause: nil
+      end
+
+      private
+
+      def permission_check!(tool_name, session)
+        tool_perms = @permissions[tool_name.to_sym] || @permissions[tool_name.to_s]
+        return unless tool_perms
+
+        if tool_perms[:denied]
+          raise Spurline::PermissionDeniedError,
+            "Tool '#{tool_name}' is denied by the permission configuration. " \
+            "Check config/permissions.yml or the agent's permission settings."
+        end
+
+        if tool_perms[:allowed_users] && session.user
+          unless tool_perms[:allowed_users].include?(session.user)
+            raise Spurline::PermissionDeniedError,
+              "Tool '#{tool_name}' is not permitted for user '#{session.user}'. " \
+              "Allowed users: #{tool_perms[:allowed_users].join(", ")}."
+          end
+        end
+      end
+
+      def confirmation_check!(tool_name, tool_class, tool_call, &confirmation_handler)
+        needs_confirmation = tool_class.respond_to?(:requires_confirmation?) && tool_class.requires_confirmation?
+
+        # Also check permissions config
+        tool_perms = @permissions[tool_name.to_sym] || @permissions[tool_name.to_s]
+        needs_confirmation ||= tool_perms&.dig(:requires_confirmation)
+
+        return unless needs_confirmation
+        return unless confirmation_handler
+
+        confirmed = confirmation_handler.call(
+          tool_name: tool_name,
+          arguments: tool_call[:arguments]
+        )
+
+        unless confirmed
+          raise Spurline::PermissionDeniedError,
+            "Tool '#{tool_name}' requires confirmation, but confirmation was denied. " \
+            "The user or operator declined to execute this tool."
+        end
+      end
+
+      def symbolize_keys(hash)
+        return {} unless hash
+
+        hash.transform_keys(&:to_sym)
+      end
+
+      def inject_secrets(tool_class, args)
+        return args unless @secret_resolver
+        return args unless tool_class.respond_to?(:declared_secrets)
+
+        secrets = tool_class.declared_secrets
+        return args if secrets.empty?
+
+        injected = args.dup
+        secrets.each do |secret_def|
+          name = secret_def[:name]
+          next if injected.key?(name)
+
+          injected[name] = @secret_resolver.resolve!(name)
+        end
+        injected
+      end
+
+      def inject_scope(args, scope:)
+        args.merge(_scope: scope)
+      end
+
+      def build_idempotency_context(tool_name:, tool_class:, args:, scoped_tool:, scope_id:, idempotency_ledger:)
+        dsl_options = @idempotency_configs[tool_name.to_sym] || {}
+        config = Spurline::Tools::Idempotency::Config.from_dsl(dsl_options, tool_class: tool_class)
+        return { enabled: false } unless config.enabled?
+
+        ledger = if idempotency_ledger.is_a?(Spurline::Tools::Idempotency::Ledger)
+                   idempotency_ledger
+                 else
+                   Spurline::Tools::Idempotency::Ledger.new(idempotency_ledger || {})
+                 end
+
+        args_for_hash = args.dup
+        args_for_hash[:_scope_id] = scope_id if scoped_tool && scope_id
+
+        key_tool_name = scoped_tool && scope_id ? "#{tool_name}@#{scope_id}" : tool_name
+        key = Spurline::Tools::Idempotency::KeyComputer.compute(
+          tool_name: key_tool_name,
+          args: args_for_hash,
+          key_params: config.key_params,
+          key_fn: config.key_fn
+        )
+
+        {
+          enabled: true,
+          ttl: config.ttl,
+          key: key,
+          args_hash: Spurline::Tools::Idempotency::KeyComputer.canonical_hash(args_for_hash),
+          ledger: ledger,
+        }
+      end
+
+      def serialize_result(raw_result)
+        return raw_result if raw_result.is_a?(String)
+
+        JSON.generate(raw_result)
+      rescue JSON::GeneratorError, TypeError
+        raw_result.to_s
+      end
+
+      def missing_keyword_argument_error?(error)
+        message = error.message.to_s
+        message.include?("missing keyword") || message.include?("unknown keyword")
+      end
+
+      def normalize_idempotency_configs(raw)
+        return {} unless raw.is_a?(Hash)
+
+        raw.each_with_object({}) do |(tool_name, config), normalized|
+          next unless config.is_a?(Hash)
+
+          normalized[tool_name.to_sym] = symbolize_keys(config)
+        end
+      end
+    end
+  end
+end

data/lib/spurline/tools/scope.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Tools
+    class Scope
+      TYPES = %i[branch pr repo review_app custom].freeze
+
+      CONSTRAINT_KEYS = {
+        path: :paths,
+        branch: :branches,
+        repo: :repos,
+      }.freeze
+
+      attr_reader :id, :type, :constraints, :metadata
+
+      # Creates a new scope.
+      #
+      # @param id [String] Scope identifier (e.g., branch name, PR number)
+      # @param type [Symbol] One of TYPES
+      # @param constraints [Hash] Resource constraints
+      #   - paths: [Array<String>] Glob patterns for file paths (e.g., "src/**")
+      #   - branches: [Array<String>] Glob patterns for branch names (e.g., "feature-*")
+      #   - repos: [Array<String>] Exact repo identifiers (e.g., "org/repo")
+      # @param metadata [Hash] Arbitrary metadata
+      def initialize(id:, type: :custom, constraints: {}, metadata: {})
+        type = type.to_sym
+        validate_type!(type)
+
+        @id = id.to_s
+        @type = type
+        @constraints = normalize_constraints(constraints)
+        @metadata = deep_copy(metadata || {})
+
+        deep_freeze(@constraints)
+        deep_freeze(@metadata)
+        freeze
+      end
+
+      # Checks if a resource is within scope constraints.
+      #
+      # @param resource [String] Resource identifier to check
+      # @param type [Symbol, nil] Resource type (:path, :branch, :repo) to narrow which constraints apply
+      # @return [Boolean]
+      #
+      # Matching rules:
+      #   - Empty constraints → everything permitted (open scope)
+      #   - Glob patterns matched via File.fnmatch (supports *, **, ?, [])
+      #   - Repos matched via exact string match or prefix match (org/repo)
+      #   - When type is specified, only that constraint category is checked
+      #   - When type is nil, all constraint categories are checked (any match = permit)
+      def permits?(resource, type: nil)
+        return true if constraints.empty?
+
+        resource = resource.to_s
+
+        if type
+          category = CONSTRAINT_KEYS.fetch(type.to_sym) do
+            raise Spurline::ConfigurationError,
+              "Invalid scope resource type: #{type.inspect}. " \
+              "Must be one of: #{CONSTRAINT_KEYS.keys.map(&:inspect).join(', ')}."
+          end
+
+          return true unless constraints.key?(category)
+
+          patterns = constraints.fetch(category)
+          return false if patterns.empty?
+
+          return matches_constraint?(resource, patterns, type.to_sym)
+        end
+
+        constrained_categories = constraints.keys
+        return true if constrained_categories.empty?
+
+        constrained_categories.any? do |category|
+          patterns = constraints.fetch(category)
+          next false if patterns.empty?
+
+          match_type = CONSTRAINT_KEYS.key(category)
+          matches_constraint?(resource, patterns, match_type)
+        end
+      end
+
+      # Raises ScopeViolationError if resource is out of bounds.
+      #
+      # @param resource [String] Resource to check
+      # @param type [Symbol, nil] Resource type
+      # @raise [ScopeViolationError] with actionable message including scope id and resource
+      def enforce!(resource, type: nil)
+        return nil if permits?(resource, type: type)
+
+        raise_scope_violation!(resource, type)
+      end
+
+      # Returns a new scope with additional constraints applied (intersection).
+      # The result is always equal or narrower than self.
+      #
+      # @param additional_constraints [Hash] Constraints to intersect with current
+      # @return [Scope] New scope (narrower or equal)
+      #
+      # Intersection rules:
+      #   - If both have a category, result is the intersection of patterns
+      #   - If only parent has a category, it carries through
+      #   - If only child has a category, it's added
+      def narrow(additional_constraints)
+        additional = normalize_constraints(additional_constraints || {})
+        merged = {}
+
+        (constraints.keys | additional.keys).each do |category|
+          parent_patterns = constraints[category]
+          child_patterns = additional[category]
+
+          if parent_patterns && child_patterns
+            match_type = CONSTRAINT_KEYS.key(category)
+            merged[category] = intersect_patterns(parent_patterns, child_patterns, match_type)
+          elsif parent_patterns
+            merged[category] = deep_copy(parent_patterns)
+          elsif child_patterns
+            merged[category] = deep_copy(child_patterns)
+          end
+        end
+
+        self.class.new(id: id, type: type, constraints: merged, metadata: metadata)
+      end
+
+      # Validates that this scope is a subset of (equal or narrower than) another.
+      #
+      # @param other [Scope] Parent scope to compare against
+      # @return [Boolean]
+      #
+      # A scope is a subset if for every constraint category:
+      #   - Parent has no constraint on that category (child is free), OR
+      #   - Every child pattern matches at least one parent pattern
+      def subset_of?(other)
+        return false unless other.is_a?(self.class)
+
+        CONSTRAINT_KEYS.values.all? do |category|
+          parent_has_category = other.constraints.key?(category)
+          child_has_category = constraints.key?(category)
+
+          next true unless parent_has_category
+          next false unless child_has_category
+
+          child_patterns = constraints.fetch(category)
+          parent_patterns = other.constraints.fetch(category)
+
+          child_patterns.all? do |pattern|
+            match_type = CONSTRAINT_KEYS.key(category)
+            matches_constraint?(pattern, parent_patterns, match_type)
+          end
+        end
+      end
+
+      # Serialization
+      def to_h
+        {
+          id: id,
+          type: type,
+          constraints: deep_copy(constraints),
+          metadata: deep_copy(metadata),
+        }
+      end
+
+      def self.from_h(data)
+        hash = deep_symbolize(data || {})
+
+        new(
+          id: hash.fetch(:id),
+          type: hash.fetch(:type, :custom),
+          constraints: hash.fetch(:constraints, {}),
+          metadata: hash.fetch(:metadata, {})
+        )
+      end
+
+      private
+
+      def validate_type!(type)
+        return if TYPES.include?(type)
+
+        raise Spurline::ConfigurationError,
+          "Invalid scope type: #{type.inspect}. " \
+          "Must be one of: #{TYPES.map(&:inspect).join(', ')}."
+      end
+
+      def normalize_constraints(raw)
+        source = self.class.send(:deep_symbolize, raw || {})
+
+        source.each_with_object({}) do |(key, value), normalized|
+          unless CONSTRAINT_KEYS.value?(key)
+            raise Spurline::ConfigurationError,
+              "Invalid scope constraint category: #{key.inspect}. " \
+              "Must be one of: #{CONSTRAINT_KEYS.values.map(&:inspect).join(', ')}."
+          end
+
+          normalized[key] = Array(value).compact.map(&:to_s)
+        end
+      end
+
+      def deep_copy(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), copy|
+            copy[deep_copy(key)] = deep_copy(value)
+          end
+        when Array
+          obj.map { |value| deep_copy(value) }
+        when String
+          obj.dup
+        else
+          obj
+        end
+      end
+
+      def deep_freeze(obj)
+        case obj
+        when Hash
+          obj.each do |key, value|
+            deep_freeze(key)
+            deep_freeze(value)
+          end
+        when Array
+          obj.each { |value| deep_freeze(value) }
+        end
+
+        obj.freeze
+      end
+
+      def matches_constraint?(resource, patterns, match_type)
+        patterns.any? do |pattern|
+          case match_type
+          when :repo
+            resource == pattern || resource.start_with?("#{pattern}/")
+          when :path, :branch
+            glob_match?(pattern, resource)
+          else
+            false
+          end
+        end
+      end
+
+      def glob_match?(pattern, value)
+        if pattern.include?("**")
+          match_segments_with_double_star?(pattern.split("/"), value.split("/"))
+        else
+          File.fnmatch(pattern, value, File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH)
+        end
+      end
+
+      def match_segments_with_double_star?(pattern_segments, value_segments)
+        if pattern_segments.empty?
+          return value_segments.empty?
+        end
+
+        current = pattern_segments.first
+
+        if current == "**"
+          return true if pattern_segments.length == 1
+
+          tail = pattern_segments.drop(1)
+          (0..value_segments.length).any? do |offset|
+            match_segments_with_double_star?(tail, value_segments.drop(offset))
+          end
+        else
+          return false if value_segments.empty?
+          return false unless File.fnmatch(current, value_segments.first, File::FNM_EXTGLOB | File::FNM_DOTMATCH)
+
+          match_segments_with_double_star?(pattern_segments.drop(1), value_segments.drop(1))
+        end
+      end
+
+      def intersect_patterns(parent_patterns, child_patterns, match_type)
+        intersection = []
+
+        child_patterns.each do |child_pattern|
+          intersection << child_pattern if matches_constraint?(child_pattern, parent_patterns, match_type)
+        end
+
+        parent_patterns.each do |parent_pattern|
+          intersection << parent_pattern if matches_constraint?(parent_pattern, child_patterns, match_type)
+        end
+
+        intersection.uniq
+      end
+
+      def raise_scope_violation!(resource, type)
+        type_suffix = type ? " (resource type: #{type})" : ""
+
+        raise Spurline::ScopeViolationError,
+          "Scope '#{id}' (#{self.type}) does not permit resource '#{resource}'#{type_suffix}."
+      end
+
+      class << self
+        private
+
+        def deep_symbolize(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, item), result|
+              result[key.to_sym] = deep_symbolize(item)
+            end
+          when Array
+            value.map { |item| deep_symbolize(item) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/tools/toolkit_registry.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Tools
+    # Registry for named toolkits. Toolkits register here and are
+    # looked up by name when an agent declares `toolkits :name`.
+    #
+    # When a tool_registry is provided, registering a toolkit also
+    # registers all its owned tools into the tool registry — so they're
+    # available for standalone `tools :name` references too.
+    class ToolkitRegistry
+      def initialize(tool_registry: nil)
+        @toolkits = {}
+        @tool_registry = tool_registry
+      end
+
+      def register(name, toolkit_class)
+        name = name.to_sym
+        @toolkits[name] = toolkit_class
+        register_toolkit_tools!(toolkit_class) if @tool_registry
+      end
+
+      def fetch(name)
+        name = name.to_sym
+        @toolkits.fetch(name) do
+          raise Spurline::ToolkitNotFoundError,
+            "Toolkit :#{name} not found. Available toolkits: #{names.join(', ')}. " \
+            "Define a toolkit class inheriting from Spurline::Toolkit and declare " \
+            "`toolkit_name :#{name}`."
+        end
+      end
+
+      def registered?(name)
+        @toolkits.key?(name.to_sym)
+      end
+
+      # Returns the tool names that a toolkit expands to.
+      def expand(name)
+        fetch(name).tools
+      end
+
+      def all
+        @toolkits.dup
+      end
+
+      def names
+        @toolkits.keys
+      end
+
+      def clear!
+        @toolkits.clear
+      end
+
+      private
+
+      def register_toolkit_tools!(toolkit_class)
+        toolkit_class.tool_classes.each do |tool_name, tool_class|
+          @tool_registry.register(tool_name, tool_class) unless @tool_registry.registered?(tool_name)
+        end
+      end
+    end
+  end
+end

data/lib/spurline/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Spurline
+  VERSION = "0.3.0"
+end

data/lib/spurline.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require_relative "spurline/errors"
+
+module Spurline
+  class << self
+    def configure(&block)
+      Configuration.configure(&block)
+    end
+
+    def config
+      Configuration.config
+    end
+
+    def analyze_repo(path)
+      Cartographer::Runner.new.analyze(repo_path: path)
+    end
+
+    def credentials
+      @credentials ||= CLI::Credentials.new(project_root: Dir.pwd).read
+    end
+
+    def reset_credentials!
+      @credentials = nil
+    end
+
+    def loader
+      @loader ||= begin
+        loader = Zeitwerk::Loader.for_gem
+        loader.inflector.inflect("dsl" => "DSL")
+        loader.inflector.inflect("pii_filter" => "PIIFilter")
+        loader.inflector.inflect("cli" => "CLI")
+        loader.inflector.inflect("ci_config" => "CIConfig")
+        loader.inflector.inflect("sqlite" => "SQLite")
+        loader.inflector.inflect("open_ai" => "OpenAI")
+        loader.inflector.inflect("github" => "GitHub")
+        loader.ignore("#{__dir__}/spurline/errors.rb")
+        loader
+      end
+    end
+  end
+end
+
+Spurline.loader.setup
+
+# Auto-discover and load spur gems from the bundle.
+if defined?(Bundler)
+  Bundler.load.current_dependencies.each do |dep|
+    next unless dep.name.start_with?("spurline-") && dep.name != "spurline-core"
+
+    require dep.name
+  rescue LoadError
+    # Spur gem is in Gemfile but not loadable — skip silently.
+  end
+end