brainzlab 0.1.10 → 0.1.12

data/lib/brainzlab/debug.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  # Debug module for SDK operation logging
+  #
+  # Provides pretty-printed debug output for all SDK operations when debug mode is enabled.
+  # Includes timing information and request/response details.
+  #
+  # @example Enable debug mode
+  #   BrainzLab.configure do |config|
+  #     config.debug = true
+  #   end
+  #
+  # @example Use custom logger
+  #   BrainzLab.configure do |config|
+  #     config.debug = true
+  #     config.logger = Logger.new(STDOUT)
+  #   end
+  #
+  # @example Manual debug logging
+  #   BrainzLab::Debug.log("Custom message", level: :info)
+  #
+  module Debug
+    COLORS = {
+      reset: "\e[0m",
+      bold: "\e[1m",
+      dim: "\e[2m",
+      red: "\e[31m",
+      green: "\e[32m",
+      yellow: "\e[33m",
+      blue: "\e[34m",
+      magenta: "\e[35m",
+      cyan: "\e[36m",
+      white: "\e[37m",
+      gray: "\e[90m"
+    }.freeze
+
+    LEVEL_COLORS = {
+      debug: :gray,
+      info: :cyan,
+      warn: :yellow,
+      error: :red,
+      fatal: :red
+    }.freeze
+
+    LEVEL_LABELS = {
+      debug: 'DEBUG',
+      info: 'INFO',
+      warn: 'WARN',
+      error: 'ERROR',
+      fatal: 'FATAL'
+    }.freeze
+
+    class << self
+      # Log a debug message if debug mode is enabled
+      #
+      # @param message [String] The message to log
+      # @param level [Symbol] Log level (:debug, :info, :warn, :error, :fatal)
+      # @param data [Hash] Optional additional data to include
+      # @return [void]
+      def log(message, level: :info, **data)
+        return unless enabled?
+
+        output = format_message(message, level: level, **data)
+        write_output(output, level: level)
+      end
+
+      # Log an outgoing request
+      #
+      # @param service [String, Symbol] The service name (e.g., :recall, :reflex)
+      # @param method [String] HTTP method
+      # @param path [String] Request path
+      # @param data [Hash] Request payload summary
+      # @return [void]
+      def log_request(service, method, path, data: nil)
+        return unless enabled?
+
+        data_summary = summarize_data(data) if data
+        message = data_summary ? "#{method} #{path} #{data_summary}" : "#{method} #{path}"
+
+        output = format_arrow_message(:out, service, message)
+        write_output(output, level: :info)
+      end
+
+      # Log an incoming response
+      #
+      # @param service [String, Symbol] The service name
+      # @param status [Integer] HTTP status code
+      # @param duration_ms [Float] Request duration in milliseconds
+      # @param error [String, nil] Error message if request failed
+      # @return [void]
+      def log_response(service, status, duration_ms, error: nil)
+        return unless enabled?
+
+        status_text = status_message(status)
+        duration_text = format_duration(duration_ms)
+
+        message = if error
+                    "#{status} #{status_text} (#{duration_text}) - #{error}"
+                  else
+                    "#{status} #{status_text} (#{duration_text})"
+                  end
+
+        level = status >= 400 ? :error : :info
+        output = format_arrow_message(:in, service, message, level: level)
+        write_output(output, level: level)
+      end
+
+      # Log an SDK operation with timing
+      #
+      # @param service [String, Symbol] The service name
+      # @param operation [String] Operation description
+      # @param data [Hash] Operation data
+      # @return [void]
+      def log_operation(service, operation, **data)
+        return unless enabled?
+
+        data_summary = data.empty? ? '' : " (#{format_data_inline(data)})"
+        message = "#{operation}#{data_summary}"
+
+        output = format_arrow_message(:out, service, message)
+        write_output(output, level: :info)
+      end
+
+      # Measure and log execution time of a block
+      #
+      # @param service [String, Symbol] The service name
+      # @param operation [String] Operation description
+      # @yield Block to measure
+      # @return [Object] Result of the block
+      def measure(service, operation)
+        return yield unless enabled?
+
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        log_operation(service, operation)
+
+        result = yield
+
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+        log("#{operation} completed", level: :debug, duration_ms: duration_ms, service: service.to_s)
+
+        result
+      rescue StandardError => e
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+        log("#{operation} failed: #{e.message}", level: :error, duration_ms: duration_ms, service: service.to_s)
+        raise
+      end
+
+      # Check if debug mode is enabled
+      #
+      # @return [Boolean]
+      def enabled?
+        BrainzLab.configuration.debug?
+      end
+
+      # Check if colorized output should be used
+      #
+      # @return [Boolean]
+      def colorize?
+        return false unless enabled?
+        return @colorize if defined?(@colorize)
+
+        @colorize = $stdout.tty?
+      end
+
+      # Reset colorize detection (useful for testing)
+      def reset_colorize!
+        remove_instance_variable(:@colorize) if defined?(@colorize)
+      end
+
+      private
+
+      def format_message(message, level:, **data)
+        timestamp = format_timestamp
+        prefix = colorize("[BrainzLab]", :bold, :blue)
+        level_badge = format_level(level)
+        data_str = data.empty? ? '' : " #{format_data(data)}"
+
+        "#{prefix} #{timestamp} #{level_badge} #{message}#{data_str}"
+      end
+
+      def format_arrow_message(direction, service, message, level: :info)
+        timestamp = format_timestamp
+        prefix = colorize("[BrainzLab]", :bold, :blue)
+        arrow = direction == :out ? colorize("->", :cyan) : colorize("<-", :green)
+        service_name = colorize(service.to_s.capitalize, :magenta)
+
+        "#{prefix} #{timestamp} #{arrow} #{service_name} #{message}"
+      end
+
+      def format_timestamp
+        time = Time.now.strftime('%H:%M:%S')
+        colorize(time, :dim)
+      end
+
+      def format_level(level)
+        label = LEVEL_LABELS[level] || level.to_s.upcase
+        color = LEVEL_COLORS[level] || :white
+        colorize("[#{label}]", color)
+      end
+
+      def format_duration(ms)
+        if ms < 1
+          colorize("#{(ms * 1000).round(0)}us", :green)
+        elsif ms < 100
+          colorize("#{ms.round(1)}ms", :green)
+        elsif ms < 1000
+          colorize("#{ms.round(0)}ms", :yellow)
+        else
+          colorize("#{(ms / 1000.0).round(2)}s", :red)
+        end
+      end
+
+      def format_data(data)
+        pairs = data.map { |k, v| "#{k}: #{format_value(v)}" }
+        colorize("(#{pairs.join(', ')})", :dim)
+      end
+
+      def format_data_inline(data)
+        data.map { |k, v| "#{k}: #{format_value(v)}" }.join(', ')
+      end
+
+      def format_value(value)
+        case value
+        when String
+          value.length > 50 ? "#{value[0..47]}..." : value
+        when Hash
+          "{#{value.keys.join(', ')}}"
+        when Array
+          "[#{value.length} items]"
+        else
+          value.to_s
+        end
+      end
+
+      def summarize_data(data)
+        return nil unless data.is_a?(Hash)
+
+        summary_parts = []
+        summary_parts << "\"#{truncate(data[:message] || data['message'], 30)}\"" if data[:message] || data['message']
+
+        other_keys = data.keys.reject { |k| %i[message timestamp level].include?(k.to_sym) }
+        if other_keys.any?
+          key_summary = other_keys.take(3).map { |k| "#{k}: #{format_value(data[k])}" }.join(', ')
+          key_summary += ", ..." if other_keys.length > 3
+          summary_parts << "(#{key_summary})"
+        end
+
+        summary_parts.join(' ')
+      end
+
+      def truncate(str, length)
+        return '' unless str
+
+        str = str.to_s
+        str.length > length ? "#{str[0..length - 4]}..." : str
+      end
+
+      def status_message(status)
+        case status
+        when 200 then 'OK'
+        when 201 then 'Created'
+        when 204 then 'No Content'
+        when 400 then 'Bad Request'
+        when 401 then 'Unauthorized'
+        when 403 then 'Forbidden'
+        when 404 then 'Not Found'
+        when 422 then 'Unprocessable Entity'
+        when 429 then 'Too Many Requests'
+        when 500 then 'Internal Server Error'
+        when 502 then 'Bad Gateway'
+        when 503 then 'Service Unavailable'
+        else ''
+        end
+      end
+
+      def colorize(text, *colors)
+        return text unless colorize?
+
+        color_codes = colors.map { |c| COLORS[c] }.compact.join
+        "#{color_codes}#{text}#{COLORS[:reset]}"
+      end
+
+      def write_output(output, level:)
+        config = BrainzLab.configuration
+
+        if config.logger
+          case level
+          when :debug then config.logger.debug(strip_colors(output))
+          when :info then config.logger.info(strip_colors(output))
+          when :warn then config.logger.warn(strip_colors(output))
+          when :error, :fatal then config.logger.error(strip_colors(output))
+          else config.logger.info(strip_colors(output))
+          end
+        else
+          $stderr.puts output
+        end
+      end
+
+      def strip_colors(text)
+        text.gsub(/\e\[\d+m/, '')
+      end
+    end
+  end
+end

data/lib/brainzlab/dendrite/client.rb

@@ -223,7 +223,27 @@ module BrainzLab
       end
 
       def log_error(operation, error)
-        BrainzLab.debug_log("[Dendrite::Client] #{operation} failed: #{error.message}")
+        structured_error = ErrorHandler.wrap(error, service: 'Dendrite', operation: operation)
+        BrainzLab.debug_log("[Dendrite::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Dendrite', operation: operation })
+        end
+      end
+
+      def handle_response_error(response, operation)
+        return if response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPCreated) || response.is_a?(Net::HTTPNoContent) || response.is_a?(Net::HTTPAccepted)
+
+        structured_error = ErrorHandler.from_response(response, service: 'Dendrite', operation: operation)
+        BrainzLab.debug_log("[Dendrite::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Dendrite', operation: operation })
+        end
+
+        structured_error
       end
     end
   end

data/lib/brainzlab/development/logger.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module BrainzLab
+  module Development
+    # Pretty-prints development mode events to stdout
+    class Logger
+      # ANSI color codes
+      COLORS = {
+        reset: "\e[0m",
+        bold: "\e[1m",
+        dim: "\e[2m",
+        # Services
+        recall: "\e[36m",     # Cyan
+        reflex: "\e[31m",     # Red
+        pulse: "\e[33m",      # Yellow
+        flux: "\e[35m",       # Magenta
+        signal: "\e[32m",     # Green
+        vault: "\e[34m",      # Blue
+        vision: "\e[95m",     # Light magenta
+        cortex: "\e[96m",     # Light cyan
+        beacon: "\e[92m",     # Light green
+        nerve: "\e[93m",      # Light yellow
+        dendrite: "\e[94m",   # Light blue
+        sentinel: "\e[91m",   # Light red
+        synapse: "\e[97m",    # White
+        # Log levels
+        debug: "\e[37m",      # Gray
+        info: "\e[32m",       # Green
+        warn: "\e[33m",       # Yellow
+        error: "\e[31m",      # Red
+        fatal: "\e[35m"       # Magenta
+      }.freeze
+
+      def initialize(output: $stdout, colors: nil)
+        @output = output
+        @colors = colors.nil? ? tty? : colors
+      end
+
+      # Log an event to stdout in a readable format
+      # @param service [Symbol] :recall, :reflex, :pulse, etc.
+      # @param event_type [String] type of event
+      # @param payload [Hash] event data
+      def log(service:, event_type:, payload:)
+        timestamp = Time.now.strftime('%H:%M:%S.%L')
+        service_color = COLORS[service] || COLORS[:reset]
+
+        # Build the log line
+        parts = []
+        parts << colorize("[#{timestamp}]", :dim)
+        parts << colorize("[#{service.to_s.upcase}]", service_color, bold: true)
+        parts << colorize(event_type, :bold)
+
+        # Add message or name depending on event type
+        message = extract_message(payload, event_type)
+        parts << message if message
+
+        # Print the main line
+        @output.puts parts.join(' ')
+
+        # Print additional details indented
+        print_details(payload, event_type)
+      end
+
+      private
+
+      def tty?
+        @output.respond_to?(:tty?) && @output.tty?
+      end
+
+      def colorize(text, color, bold: false)
+        return text unless @colors
+
+        color_code = color.is_a?(Symbol) ? COLORS[color] : color
+        prefix = bold ? "#{COLORS[:bold]}#{color_code}" : color_code.to_s
+        "#{prefix}#{text}#{COLORS[:reset]}"
+      end
+
+      def extract_message(payload, event_type)
+        case event_type
+        when 'log'
+          level = payload[:level]&.to_sym
+          level_color = COLORS[level] || COLORS[:info]
+          msg = "#{colorize("[#{level&.upcase}]", level_color)} #{payload[:message]}"
+          msg
+        when 'error'
+          "#{payload[:error_class]}: #{payload[:message]}"
+        when 'trace'
+          duration = payload[:duration_ms] ? "(#{payload[:duration_ms]}ms)" : ''
+          "#{payload[:name]} #{duration}"
+        when 'metric'
+          "#{payload[:name]} = #{payload[:value]}"
+        when 'span'
+          duration = payload[:duration_ms] ? "(#{payload[:duration_ms]}ms)" : ''
+          "#{payload[:name]} #{duration}"
+        else
+          payload[:message] || payload[:name]
+        end
+      end
+
+      def print_details(payload, event_type)
+        details = extract_details(payload, event_type)
+        return if details.empty?
+
+        details.each do |key, value|
+          formatted_value = format_value(value)
+          @output.puts "  #{colorize(key.to_s, :dim)}: #{formatted_value}"
+        end
+      end
+
+      def extract_details(payload, event_type)
+        # Fields to exclude from details (already shown in main line)
+        excluded = %i[timestamp message level name kind]
+
+        case event_type
+        when 'log'
+          payload.except(*excluded, :environment, :service, :host)
+        when 'error'
+          payload.slice(:error_class, :environment, :request_id, :user, :tags).compact
+        when 'trace'
+          payload.slice(:request_method, :request_path, :status, :db_ms, :view_ms, :spans).compact
+        when 'metric'
+          payload.slice(:kind, :tags).compact
+        else
+          payload.except(*excluded)
+        end
+      end
+
+      def format_value(value)
+        case value
+        when Hash
+          if value.size <= 3
+            value.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
+          else
+            "\n    #{JSON.pretty_generate(value).gsub("\n", "\n    ")}"
+          end
+        when Array
+          if value.size <= 3 && value.all? { |v| v.is_a?(String) || v.is_a?(Numeric) }
+            value.inspect
+          else
+            "\n    #{JSON.pretty_generate(value).gsub("\n", "\n    ")}"
+          end
+        else
+          value.inspect
+        end
+      end
+    end
+  end
+end

data/lib/brainzlab/development/store.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'sqlite3'
+require 'json'
+require 'fileutils'
+
+module BrainzLab
+  module Development
+    # SQLite-backed store for development mode events
+    class Store
+      DEFAULT_PATH = 'tmp/brainzlab.sqlite3'
+
+      def initialize(config)
+        @config = config
+        @db_path = config.development_db_path || DEFAULT_PATH
+        @db = nil
+        ensure_database!
+      end
+
+      # Insert an event into the store
+      # @param service [Symbol] :recall, :reflex, :pulse, etc.
+      # @param event_type [String] type of event
+      # @param payload [Hash] event data
+      def insert(service:, event_type:, payload:)
+        db.execute(
+          'INSERT INTO events (service, event_type, payload, created_at) VALUES (?, ?, ?, ?)',
+          [service.to_s, event_type.to_s, JSON.generate(payload), Time.now.utc.iso8601(3)]
+        )
+      end
+
+      # Query events from the store
+      # @param service [Symbol, nil] filter by service
+      # @param event_type [String, nil] filter by event type
+      # @param since [Time, nil] filter events after this time
+      # @param limit [Integer] max number of events to return
+      # @return [Array<Hash>] matching events
+      def query(service: nil, event_type: nil, since: nil, limit: 100)
+        conditions = []
+        params = []
+
+        if service
+          conditions << 'service = ?'
+          params << service.to_s
+        end
+
+        if event_type
+          conditions << 'event_type = ?'
+          params << event_type.to_s
+        end
+
+        if since
+          conditions << 'created_at >= ?'
+          params << since.utc.iso8601(3)
+        end
+
+        where_clause = conditions.empty? ? '' : "WHERE #{conditions.join(' AND ')}"
+        params << limit
+
+        sql = "SELECT id, service, event_type, payload, created_at FROM events #{where_clause} ORDER BY created_at DESC LIMIT ?"
+
+        db.execute(sql, params).map do |row|
+          {
+            id: row[0],
+            service: row[1].to_sym,
+            event_type: row[2],
+            payload: JSON.parse(row[3], symbolize_names: true),
+            created_at: Time.parse(row[4])
+          }
+        end
+      end
+
+      # Get event counts by service
+      def stats
+        results = db.execute('SELECT service, COUNT(*) as count FROM events GROUP BY service')
+        results.to_h { |row| [row[0].to_sym, row[1]] }
+      end
+
+      # Clear all events
+      def clear!
+        db.execute('DELETE FROM events')
+      end
+
+      # Close the database connection
+      def close
+        @db&.close
+        @db = nil
+      end
+
+      private
+
+      def db
+        @db ||= begin
+          SQLite3::Database.new(@db_path).tap do |database|
+            database.results_as_hash = false
+          end
+        end
+      end
+
+      def ensure_database!
+        # Ensure the directory exists
+        FileUtils.mkdir_p(File.dirname(@db_path))
+
+        # Create the events table if it doesn't exist
+        db.execute(<<~SQL)
+          CREATE TABLE IF NOT EXISTS events (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            service TEXT NOT NULL,
+            event_type TEXT NOT NULL,
+            payload TEXT NOT NULL,
+            created_at TEXT NOT NULL
+          )
+        SQL
+
+        # Create indexes for common queries
+        db.execute('CREATE INDEX IF NOT EXISTS idx_events_service ON events(service)')
+        db.execute('CREATE INDEX IF NOT EXISTS idx_events_event_type ON events(event_type)')
+        db.execute('CREATE INDEX IF NOT EXISTS idx_events_created_at ON events(created_at)')
+      end
+    end
+  end
+end

data/lib/brainzlab/development.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative 'development/store'
+require_relative 'development/logger'
+
+module BrainzLab
+  # Development mode support for offline SDK usage
+  # Logs all events to stdout and stores them locally in SQLite
+  module Development
+    class << self
+      # Check if development mode is enabled
+      def enabled?
+        BrainzLab.configuration.mode == :development
+      end
+
+      # Get the store instance
+      def store
+        @store ||= Store.new(BrainzLab.configuration)
+      end
+
+      # Get the development logger
+      def logger
+        @logger ||= Logger.new(output: BrainzLab.configuration.development_log_output || $stdout)
+      end
+
+      # Record an event from any service
+      # @param service [Symbol] :recall, :reflex, :pulse, etc.
+      # @param event_type [String] type of event (log, error, trace, metric, etc.)
+      # @param payload [Hash] event data
+      def record(service:, event_type:, payload:)
+        return unless enabled?
+
+        # Log to stdout
+        logger.log(service: service, event_type: event_type, payload: payload)
+
+        # Store in SQLite
+        store.insert(service: service, event_type: event_type, payload: payload)
+      end
+
+      # Query stored events
+      # @param service [Symbol, nil] filter by service
+      # @param event_type [String, nil] filter by event type
+      # @param since [Time, nil] filter events after this time
+      # @param limit [Integer] max number of events to return (default: 100)
+      # @return [Array<Hash>] matching events
+      def events(service: nil, event_type: nil, since: nil, limit: 100)
+        return [] unless enabled?
+
+        store.query(service: service, event_type: event_type, since: since, limit: limit)
+      end
+
+      # Clear all stored events
+      def clear!
+        store.clear! if enabled?
+      end
+
+      # Reset the development module (for testing)
+      def reset!
+        @store&.close
+        @store = nil
+        @logger = nil
+      end
+
+      # Get event counts by service
+      def stats
+        return {} unless enabled?
+
+        store.stats
+      end
+    end
+  end
+end