spurline-dashboard 0.3.0

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/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 |
+|----|------|---|-------|------|
+| #3782 | 10:23 PM | 🔵 | Spurline session and state machine architecture analyzed for suspended sessions feature | ~700 |
+</claude-mem-context>

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

data/lib/spurline/dsl/hooks.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Spurline
+  module DSL
+    # DSL for registering lifecycle event hooks.
+    # Registers configuration at class load time — never executes behavior.
+    module Hooks
+      HOOK_TYPES = %i[
+        on_start
+        on_turn_start
+        on_tool_call
+        on_turn_end
+        on_suspend
+        on_resume
+        on_finish
+        on_error
+        on_child_spawn
+        on_child_complete
+        on_child_error
+      ].freeze
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        HOOK_TYPES.each do |hook_type|
+          define_method(hook_type) do |&block|
+            @hooks ||= {}
+            @hooks[hook_type] ||= []
+            @hooks[hook_type] << block
+          end
+        end
+
+        def hooks_config
+          own = @hooks || {}
+          if superclass.respond_to?(:hooks_config)
+            inherited = superclass.hooks_config
+            merged = inherited.dup
+            own.each do |type, blocks|
+              merged[type] = (merged[type] || []) + blocks
+            end
+            merged
+          else
+            own
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/dsl/memory.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Spurline
+  module DSL
+    # DSL for configuring agent memory stores.
+    # Registers configuration at class load time — never executes behavior.
+    module Memory
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def memory(type, **options)
+          @memory_config ||= {}
+          @memory_config[type.to_sym] = options
+        end
+
+        # Shorthand for toggling episodic memory recording.
+        #
+        #   episodic false
+        #   episodic true
+        #
+        def episodic(enabled = true)
+          @memory_config ||= {}
+          @memory_config[:episodic] = { enabled: !!enabled }
+        end
+
+        def memory_config
+          own = @memory_config || {}
+          if superclass.respond_to?(:memory_config)
+            superclass.memory_config.merge(own)
+          else
+            own
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/dsl/model.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Spurline
+  module DSL
+    # DSL for configuring which LLM model an agent uses.
+    # Registers configuration at class load time — never executes behavior.
+    module Model
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def use_model(name, **options)
+          @model_config = { name: name.to_sym, **options }
+        end
+
+        def model_config
+          @model_config || (superclass.respond_to?(:model_config) ? superclass.model_config : nil)
+        end
+      end
+    end
+  end
+end

data/lib/spurline/dsl/persona.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Spurline
+  module DSL
+    # DSL for defining agent personas (system prompts).
+    # Registers configuration at class load time — never executes behavior.
+    module Persona
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def persona(name = :default, &block)
+          @persona_configs ||= {}
+          config = PersonaConfig.new
+          config.instance_eval(&block)
+          @persona_configs[name.to_sym] = config
+        end
+
+        def persona_configs
+          own = @persona_configs || {}
+          inherited = if superclass.respond_to?(:persona_configs)
+            superclass.persona_configs
+          else
+            {}
+          end
+          inherited.merge(own)
+        end
+      end
+
+      # Internal config object for persona DSL blocks.
+      class PersonaConfig
+        attr_reader :system_prompt_text
+
+        def initialize
+          @system_prompt_text = ""
+          @_inject_date = false
+          @_inject_user_context = false
+          @_inject_agent_context = false
+        end
+
+        def system_prompt(text)
+          @system_prompt_text = text
+        end
+
+        # DSL setters (used inside persona blocks)
+        def inject_date(val = true)
+          @_inject_date = val
+        end
+
+        def inject_user_context(val = true)
+          @_inject_user_context = val
+        end
+
+        def inject_agent_context(val = true)
+          @_inject_agent_context = val
+        end
+
+        # Predicate readers (used when compiling persona config)
+        def date_injected?
+          @_inject_date
+        end
+
+        def user_context_injected?
+          @_inject_user_context
+        end
+
+        def agent_context_injected?
+          @_inject_agent_context
+        end
+      end
+    end
+  end
+end

data/lib/spurline/dsl/suspend_until.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../lifecycle/suspension_boundary"
+
+module Spurline
+  module DSL
+    module SuspendUntil
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Declares a suspension condition for this agent class.
+        #
+        # Usage:
+        #   suspend_until :tool_calls, count: 3
+        #   suspend_until :custom, &block
+        def suspend_until(type = nil, **options, &block)
+          @suspension_config = { type: type, options: options, block: block }
+        end
+
+        def suspension_config
+          @suspension_config || superclass_suspension_config
+        end
+
+        # Builds a SuspensionCheck from the declarative config.
+        def build_suspension_check
+          config = suspension_config
+          return Lifecycle::SuspensionCheck.none unless config
+
+          case config[:type]
+          when :tool_calls
+            Lifecycle::SuspensionCheck.after_tool_calls(config[:options][:count])
+          when :custom
+            Lifecycle::SuspensionCheck.new(&config[:block])
+          else
+            Lifecycle::SuspensionCheck.none
+          end
+        end
+
+        private
+
+        def superclass_suspension_config
+          if superclass.respond_to?(:suspension_config)
+            superclass.suspension_config
+          else
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/dsl/tools.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+require "pathname"
+
+module Spurline
+  module DSL
+    # DSL for declaring which tools an agent can use.
+    # Registers configuration at class load time — never executes behavior.
+    #
+    # Supports per-tool config overrides:
+    #   tools :web_search, file_delete: { requires_confirmation: true, timeout: 30 }
+    module Tools
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        IDEMPOTENCY_OPTION_KEYS = %i[
+          idempotent
+          idempotency_key
+          idempotency_ttl
+          idempotency_key_fn
+        ].freeze
+
+        def tools(*tool_names, **tool_configs)
+          @tool_config ||= { names: [], configs: {} }
+          tool_names.each { |name| @tool_config[:names] << name.to_sym }
+          tool_configs.each do |name, config|
+            @tool_config[:names] << name.to_sym
+            existing = @tool_config[:configs][name.to_sym]
+            @tool_config[:configs][name.to_sym] = existing ? existing.merge(config) : config
+          end
+        end
+
+        # Include one or more toolkits by name. Toolkit expansion is deferred
+        # until tool_config is accessed, so toolkits can be registered after
+        # agent classes are defined (supports any boot order).
+        #
+        #   toolkits :git, :linear
+        #   toolkits :provisioning, provisioning: { scoped: true }
+        #
+        def toolkits(*toolkit_names, **overrides)
+          @pending_toolkits ||= []
+          @pending_toolkits << { names: toolkit_names.map(&:to_sym), overrides: overrides }
+        end
+
+        def tool_config
+          expand_pending_toolkits!
+          own = @tool_config || { names: [], configs: {} }
+          if superclass.respond_to?(:tool_config)
+            inherited = superclass.tool_config
+            {
+              names: (inherited[:names] + own[:names]).uniq,
+              configs: inherited[:configs].merge(own[:configs]),
+            }
+          else
+            own
+          end
+        end
+
+        # Returns per-tool configuration for a specific tool.
+        def tool_config_for(tool_name)
+          tool_config[:configs][tool_name.to_sym] || {}
+        end
+
+        # Effective per-tool idempotency options from DSL config.
+        def idempotency_config
+          tool_config[:configs].each_with_object({}) do |(tool_name, config), result|
+            next unless config.is_a?(Hash)
+
+            options = symbolize_hash(config).slice(*IDEMPOTENCY_OPTION_KEYS)
+            next if options.empty?
+
+            result[tool_name.to_sym] = options
+          end
+        end
+
+        # Effective permissions applied by Tools::Runner.
+        # Merge order: spur defaults -> agent inline config -> YAML overrides.
+        def permissions_config
+          merged = {}
+          deep_merge_permissions!(merged, spur_default_permissions)
+          deep_merge_permissions!(merged, inline_tool_permissions)
+          deep_merge_permissions!(merged, yaml_permissions)
+          merged
+        end
+
+        private
+
+        def expand_pending_toolkits!
+          return unless instance_variable_defined?(:@pending_toolkits) && @pending_toolkits&.any?
+
+          pending = @pending_toolkits
+          @pending_toolkits = nil
+
+          pending.each do |ref|
+            ref[:names].each do |tk_name|
+              toolkit = self.toolkit_registry.fetch(tk_name)
+
+              # Toolkits own their tools — register them into the agent's tool registry.
+              toolkit.tool_classes.each do |tool_name, tool_class|
+                self.tool_registry.register(tool_name, tool_class) unless self.tool_registry.registered?(tool_name)
+              end
+
+              tool_names = toolkit.tools
+              shared = toolkit.shared_config
+
+              if shared.empty? && ref[:overrides].empty?
+                tools(*tool_names)
+              else
+                tool_configs = {}
+                tool_names.each do |tool_name|
+                  merged = shared.dup
+                  merged.merge!(ref[:overrides][tk_name] || {})
+                  tool_configs[tool_name] = merged unless merged.empty?
+                end
+                tools(*tool_names, **tool_configs)
+              end
+            end
+          end
+        end
+
+        def spur_default_permissions
+          return {} unless defined?(Spurline::Spur)
+
+          Spurline::Spur.registry.each_with_object({}) do |(_name, info), result|
+            next unless info.is_a?(Hash)
+
+            defaults = symbolize_hash(info[:permissions] || info["permissions"])
+            next if defaults.empty?
+
+            tools = info[:tools] || info["tools"] || []
+            tools.each do |tool_name|
+              result[tool_name.to_sym] ||= {}
+              result[tool_name.to_sym].merge!(defaults)
+            end
+          end
+        end
+
+        def inline_tool_permissions
+          tool_config[:configs].each_with_object({}) do |(tool_name, config), result|
+            result[tool_name.to_sym] = symbolize_hash(config)
+          end
+        end
+
+        def yaml_permissions
+          path = resolve_permissions_path
+          Spurline::Tools::Permissions.load_file(path)
+        end
+
+        def resolve_permissions_path
+          configured = Spurline.config.permissions_file
+          return nil if configured.nil? || configured.to_s.strip.empty?
+          return configured if Pathname.new(configured).absolute?
+
+          File.expand_path(configured.to_s, Dir.pwd)
+        end
+
+        def deep_merge_permissions!(base, incoming)
+          incoming.each do |tool_name, tool_config_hash|
+            key = tool_name.to_sym
+            base[key] ||= {}
+            base[key].merge!(symbolize_hash(tool_config_hash))
+          end
+        end
+
+        def symbolize_hash(value)
+          return {} unless value.is_a?(Hash)
+
+          value.each_with_object({}) do |(k, v), result|
+            result[k.to_sym] = v
+          end
+        end
+      end
+    end
+  end
+end