brainzlab 0.1.10 → 0.1.12

data/lib/brainzlab/devtools/assets/devtools.js

@@ -4,6 +4,46 @@
 (function() {
   'use strict';
 
+  // ============================================
+  // DARK MODE SUPPORT
+  // ============================================
+  // Sync with brainzlab-theme localStorage key (used across all BrainzLab products)
+  function initDarkMode() {
+    const theme = localStorage.getItem('brainzlab-theme');
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+
+    if (theme === 'dark' || (!theme && prefersDark)) {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  }
+
+  // Listen for theme changes from other windows/tabs
+  function setupThemeListener() {
+    window.addEventListener('storage', function(e) {
+      if (e.key === 'brainzlab-theme') {
+        initDarkMode();
+      }
+    });
+
+    // Also listen for system preference changes
+    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function(e) {
+      // Only react if no explicit theme is set
+      if (!localStorage.getItem('brainzlab-theme')) {
+        if (e.matches) {
+          document.documentElement.classList.add('dark');
+        } else {
+          document.documentElement.classList.remove('dark');
+        }
+      }
+    });
+  }
+
+  // Initialize dark mode immediately
+  initDarkMode();
+  setupThemeListener();
+
   // Load Stimulus if not available
   let stimulusApp = null;
   let StimulusController = null;
@@ -31,7 +71,7 @@
   // Stimulus Controller Definition
   const DevtoolsController = {
     static: {
-      targets: ['panel', 'tab', 'pane', 'toast']
+      targets: ['panel', 'tab', 'pane', 'toast', 'restoreBtn']
     },
 
     // Lifecycle
@@ -46,10 +86,32 @@
 
     // Actions
     togglePanel() {
+      // Don't toggle if minimized - use restorePanel instead
+      if (this.element.classList.contains('minimized')) {
+        return;
+      }
       this.element.classList.toggle('collapsed');
       this.saveState();
     },
 
+    minimizePanel(event) {
+      if (event) {
+        event.stopPropagation();
+        event.preventDefault();
+      }
+      this.element.classList.add('minimized');
+      this.saveState();
+    },
+
+    restorePanel(event) {
+      if (event) {
+        event.stopPropagation();
+        event.preventDefault();
+      }
+      this.element.classList.remove('minimized');
+      this.saveState();
+    },
+
     switchTab(event) {
       event.stopPropagation();
       const tabName = event.currentTarget.dataset.tab;
@@ -242,6 +304,7 @@ Controller: ${controllerName || 'unknown'}#${actionName || 'unknown'}
         const activeTab = this.element.querySelector('[data-devtools-target="tab"].active');
         sessionStorage.setItem('brainz-devtools-state', JSON.stringify({
           collapsed: this.element.classList.contains('collapsed'),
+          minimized: this.element.classList.contains('minimized'),
           activeTab: activeTab?.dataset.tab || 'request'
         }));
       } catch (e) { /* ignore */ }
@@ -250,7 +313,11 @@ Controller: ${controllerName || 'unknown'}#${actionName || 'unknown'}
     loadState() {
       try {
         const state = JSON.parse(sessionStorage.getItem('brainz-devtools-state'));
-        if (state?.collapsed) this.element.classList.add('collapsed');
+        if (state?.minimized) {
+          this.element.classList.add('minimized');
+        } else if (state?.collapsed) {
+          this.element.classList.add('collapsed');
+        }
         if (state?.activeTab) {
           const tab = this.element.querySelector(`[data-tab="${state.activeTab}"]`);
           if (tab) tab.click();
@@ -263,9 +330,14 @@ Controller: ${controllerName || 'unknown'}#${actionName || 'unknown'}
       this._keyHandler = (e) => {
         if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key === 'B') {
           e.preventDefault();
-          this.togglePanel();
+          // If minimized, restore first
+          if (this.element.classList.contains('minimized')) {
+            this.restorePanel();
+          } else {
+            this.togglePanel();
+          }
         }
-        if (e.key === 'Escape' && !this.element.classList.contains('collapsed')) {
+        if (e.key === 'Escape' && !this.element.classList.contains('collapsed') && !this.element.classList.contains('minimized')) {
           this.togglePanel();
         }
       };
@@ -289,11 +361,13 @@ Controller: ${controllerName || 'unknown'}#${actionName || 'unknown'}
 
     // Register the devtools controller
     app.register('devtools', class extends Controller {
-      static targets = ['tab', 'pane'];
+      static targets = ['tab', 'pane', 'restoreBtn'];
 
       connect() { DevtoolsController.connect.call(this); }
       disconnect() { DevtoolsController.disconnect.call(this); }
       togglePanel() { DevtoolsController.togglePanel.call(this); }
+      minimizePanel(e) { DevtoolsController.minimizePanel.call(this, e); }
+      restorePanel(e) { DevtoolsController.restorePanel.call(this, e); }
       switchTab(e) { DevtoolsController.switchTab.call(this, e); }
       copyToAi(e) { DevtoolsController.copyToAi.call(this, e); }
       copySql(e) { DevtoolsController.copySql.call(this, e); }

data/lib/brainzlab/devtools/assets/templates/debug_panel.html.erb

@@ -97,6 +97,12 @@
         <path d="M2 4l4 4 4-4" stroke="currentColor" stroke-width="1.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
       </svg>
     </span>
+
+    <button class="brainz-debug-minimize" data-action="click->devtools#minimizePanel" title="Minimize panel">
+      <svg width="12" height="12" viewBox="0 0 12 12">
+        <path d="M2 6h8" stroke="currentColor" stroke-width="1.5" fill="none" stroke-linecap="round"/>
+      </svg>
+    </button>
   </div>
 
   <!-- Tabs -->
@@ -494,6 +500,11 @@
       </div>
     </div>
   </div>
+
+  <!-- Floating Restore Button (visible when minimized) -->
+  <button class="brainz-debug-restore" data-devtools-target="restoreBtn" data-action="click->devtools#restorePanel" title="Restore BrainzLab DevTools (Ctrl+Shift+B)">
+    <img src="<%= asset_url('logo.svg') %>" alt="BrainzLab" width="20" height="20">
+  </button>
 </div>
 
 <link rel="stylesheet" href="<%= asset_url('devtools.css') %>">

data/lib/brainzlab/errors.rb

@@ -0,0 +1,490 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  # Base error class for all BrainzLab SDK errors.
+  # Provides structured error information including hints and documentation links.
+  #
+  # @example Raising a structured error
+  #   raise BrainzLab::Error.new(
+  #     "Operation failed",
+  #     hint: "Check your network connection",
+  #     docs_url: "https://docs.brainzlab.io/troubleshooting",
+  #     code: "operation_failed"
+  #   )
+  #
+  # @example Catching and inspecting errors
+  #   begin
+  #     BrainzLab::Vault.get("secret")
+  #   rescue BrainzLab::Error => e
+  #     puts e.message    # What went wrong
+  #     puts e.hint       # How to fix it
+  #     puts e.docs_url   # Where to learn more
+  #     puts e.code       # Machine-readable code
+  #   end
+  #
+  class Error < StandardError
+    # @return [String, nil] A helpful hint on how to resolve the error
+    attr_reader :hint
+
+    # @return [String, nil] URL to relevant documentation
+    attr_reader :docs_url
+
+    # @return [String, nil] Machine-readable error code for programmatic handling
+    attr_reader :code
+
+    # @return [Hash, nil] Additional context about the error
+    attr_reader :context
+
+    DOCS_BASE_URL = 'https://docs.brainzlab.io'
+
+    # Initialize a new BrainzLab error.
+    #
+    # @param message [String] The error message describing what went wrong
+    # @param hint [String, nil] A helpful hint on how to resolve the error
+    # @param docs_url [String, nil] URL to relevant documentation
+    # @param code [String, nil] Machine-readable error code
+    # @param context [Hash, nil] Additional context about the error
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil)
+      @message = message
+      @hint = hint
+      @docs_url = docs_url
+      @code = code
+      @context = context
+      super(message)
+    end
+
+    # Format the error as a detailed string with hints and documentation links.
+    #
+    # @return [String] Formatted error message
+    def to_s
+      super
+    end
+
+    # Return a detailed formatted version of the error with hints and documentation links.
+    # Use this method when you want the full structured output.
+    #
+    # @return [String] Detailed formatted error message
+    def detailed_message(highlight: false, **_kwargs)
+      # Get the base message without class name duplication
+      base_msg = @message || super
+
+      parts = ["#{self.class.name}: #{base_msg}"]
+
+      parts << "" << "Hint: #{hint}" if hint
+      parts << "Docs: #{docs_url}" if docs_url
+      parts << "Code: #{code}" if code
+
+      if context && !context.empty?
+        parts << "" << "Context:"
+        context.each do |key, value|
+          parts << "  #{key}: #{value}"
+        end
+      end
+
+      parts.join("\n")
+    end
+
+    # Inspect the error for debugging
+    #
+    # @return [String] Inspection output
+    def inspect
+      "#<#{self.class.name}: #{message}#{" (#{code})" if code}>"
+    end
+
+    # Return a hash representation of the error for logging/serialization.
+    #
+    # @return [Hash] Error details as a hash
+    def to_h
+      {
+        error_class: self.class.name,
+        message: message,
+        hint: hint,
+        docs_url: docs_url,
+        code: code,
+        context: context
+      }.compact
+    end
+
+    # Alias for to_h
+    def as_json
+      to_h
+    end
+  end
+
+  # Raised when the SDK is misconfigured or required configuration is missing.
+  #
+  # @example Missing API key
+  #   raise BrainzLab::ConfigurationError.new(
+  #     "API key is required",
+  #     hint: "Set BRAINZLAB_SECRET_KEY environment variable or configure via BrainzLab.configure",
+  #     code: "missing_api_key"
+  #   )
+  #
+  class ConfigurationError < Error
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil)
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/configuration"
+      code ||= 'configuration_error'
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context)
+    end
+  end
+
+  # Raised when authentication fails due to invalid or expired credentials.
+  #
+  # @example Invalid API key
+  #   raise BrainzLab::AuthenticationError.new(
+  #     "Invalid API key",
+  #     hint: "Check that your API key is correct and has not expired",
+  #     code: "invalid_api_key"
+  #   )
+  #
+  class AuthenticationError < Error
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil)
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/authentication"
+      code ||= 'authentication_error'
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context)
+    end
+  end
+
+  # Raised when a connection to BrainzLab services cannot be established.
+  #
+  # @example Connection timeout
+  #   raise BrainzLab::ConnectionError.new(
+  #     "Connection timed out",
+  #     hint: "Check your network connection and firewall settings",
+  #     code: "connection_timeout"
+  #   )
+  #
+  class ConnectionError < Error
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil)
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/troubleshooting#connection-issues"
+      code ||= 'connection_error'
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context)
+    end
+  end
+
+  # Raised when the rate limit for API requests has been exceeded.
+  #
+  # @example Rate limit exceeded
+  #   raise BrainzLab::RateLimitError.new(
+  #     "Rate limit exceeded",
+  #     hint: "Wait before retrying or consider upgrading your plan",
+  #     code: "rate_limit_exceeded",
+  #     context: { retry_after: 60, limit: 1000, remaining: 0 }
+  #   )
+  #
+  class RateLimitError < Error
+    # @return [Integer, nil] Seconds to wait before retrying
+    attr_reader :retry_after
+
+    # @return [Integer, nil] The rate limit ceiling
+    attr_reader :limit
+
+    # @return [Integer, nil] Remaining requests in the current window
+    attr_reader :remaining
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, retry_after: nil, limit: nil, remaining: nil)
+      @retry_after = retry_after
+      @limit = limit
+      @remaining = remaining
+
+      hint ||= retry_after ? "Wait #{retry_after} seconds before retrying" : 'Reduce request frequency or upgrade your plan'
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/rate-limits"
+      code ||= 'rate_limit_exceeded'
+
+      context ||= {}
+      context[:retry_after] = retry_after if retry_after
+      context[:limit] = limit if limit
+      context[:remaining] = remaining if remaining
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Raised when request parameters or data fail validation.
+  #
+  # @example Invalid parameter
+  #   raise BrainzLab::ValidationError.new(
+  #     "Invalid email format",
+  #     hint: "Provide a valid email address (e.g., user@example.com)",
+  #     code: "invalid_email",
+  #     context: { field: "email", value: "invalid" }
+  #   )
+  #
+  class ValidationError < Error
+    # @return [String, nil] The field that failed validation
+    attr_reader :field
+
+    # @return [Array<Hash>, nil] List of validation errors for multiple fields
+    attr_reader :errors
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, field: nil, errors: nil)
+      @field = field
+      @errors = errors
+
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/api-reference"
+      code ||= 'validation_error'
+
+      context ||= {}
+      context[:field] = field if field
+      context[:errors] = errors if errors
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Raised when a requested resource is not found.
+  #
+  # @example Resource not found
+  #   raise BrainzLab::NotFoundError.new(
+  #     "Secret 'database_url' not found",
+  #     hint: "Verify the secret name and environment",
+  #     code: "secret_not_found"
+  #   )
+  #
+  class NotFoundError < Error
+    # @return [String, nil] The type of resource that was not found
+    attr_reader :resource_type
+
+    # @return [String, nil] The identifier of the resource that was not found
+    attr_reader :resource_id
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, resource_type: nil, resource_id: nil)
+      @resource_type = resource_type
+      @resource_id = resource_id
+
+      code ||= 'not_found'
+
+      context ||= {}
+      context[:resource_type] = resource_type if resource_type
+      context[:resource_id] = resource_id if resource_id
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Raised when a server-side error occurs.
+  #
+  # @example Server error
+  #   raise BrainzLab::ServerError.new(
+  #     "Internal server error",
+  #     hint: "This is a temporary issue. Please retry your request.",
+  #     code: "internal_server_error"
+  #   )
+  #
+  class ServerError < Error
+    # @return [Integer, nil] HTTP status code from the server
+    attr_reader :status_code
+
+    # @return [String, nil] Request ID for support reference
+    attr_reader :request_id
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, status_code: nil, request_id: nil)
+      @status_code = status_code
+      @request_id = request_id
+
+      hint ||= 'This is a temporary issue. Please retry your request. If the problem persists, contact support.'
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/troubleshooting#server-errors"
+      code ||= 'server_error'
+
+      context ||= {}
+      context[:status_code] = status_code if status_code
+      context[:request_id] = request_id if request_id
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Raised when an operation times out.
+  #
+  # @example Request timeout
+  #   raise BrainzLab::TimeoutError.new(
+  #     "Request timed out after 30 seconds",
+  #     hint: "The operation took too long. Try again or increase timeout settings.",
+  #     code: "request_timeout"
+  #   )
+  #
+  class TimeoutError < Error
+    # @return [Integer, nil] Timeout duration in seconds
+    attr_reader :timeout_seconds
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, timeout_seconds: nil)
+      @timeout_seconds = timeout_seconds
+
+      hint ||= 'The operation took too long. Try again or increase timeout settings.'
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/configuration#timeouts"
+      code ||= 'timeout'
+
+      context ||= {}
+      context[:timeout_seconds] = timeout_seconds if timeout_seconds
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Raised when a service is temporarily unavailable.
+  #
+  # @example Service unavailable
+  #   raise BrainzLab::ServiceUnavailableError.new(
+  #     "Vault service is currently unavailable",
+  #     hint: "The service is undergoing maintenance. Please try again later.",
+  #     code: "vault_unavailable"
+  #   )
+  #
+  class ServiceUnavailableError < Error
+    # @return [String, nil] The name of the unavailable service
+    attr_reader :service_name
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, service_name: nil)
+      @service_name = service_name
+
+      hint ||= 'The service is temporarily unavailable. Please try again later.'
+      docs_url ||= "#{DOCS_BASE_URL}/status"
+      code ||= 'service_unavailable'
+
+      context ||= {}
+      context[:service_name] = service_name if service_name
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Helper module for wrapping low-level errors into structured BrainzLab errors
+  module ErrorHandler
+    module_function
+
+    # Wrap a standard error into a structured BrainzLab error.
+    #
+    # @param error [StandardError] The original error
+    # @param service [String] The service name (e.g., 'Vault', 'Cortex')
+    # @param operation [String] The operation being performed
+    # @return [BrainzLab::Error] A structured BrainzLab error
+    def wrap(error, service:, operation:)
+      case error
+      when Net::OpenTimeout, Net::ReadTimeout, Timeout::Error
+        TimeoutError.new(
+          "#{service} #{operation} timed out: #{error.message}",
+          hint: 'Check your network connection or increase timeout settings.',
+          code: "#{service.downcase}_timeout",
+          context: { service: service, operation: operation }
+        )
+      when Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH
+        ConnectionError.new(
+          "Unable to connect to #{service}: #{error.message}",
+          hint: 'Check that the service is running and accessible.',
+          code: "#{service.downcase}_connection_failed",
+          context: { service: service, operation: operation }
+        )
+      when SocketError
+        ConnectionError.new(
+          "DNS resolution failed for #{service}: #{error.message}",
+          hint: 'Check your network connection and DNS settings.',
+          code: "#{service.downcase}_dns_error",
+          context: { service: service, operation: operation }
+        )
+      when JSON::ParserError
+        ServerError.new(
+          "Invalid response from #{service}: #{error.message}",
+          hint: 'The server returned an unexpected response format.',
+          code: "#{service.downcase}_invalid_response",
+          context: { service: service, operation: operation }
+        )
+      when OpenSSL::SSL::SSLError
+        ConnectionError.new(
+          "SSL error connecting to #{service}: #{error.message}",
+          hint: 'Check SSL certificates and ensure the connection is secure.',
+          code: "#{service.downcase}_ssl_error",
+          context: { service: service, operation: operation }
+        )
+      else
+        Error.new(
+          "#{service} #{operation} failed: #{error.message}",
+          hint: 'An unexpected error occurred. Check the logs for more details.',
+          code: "#{service.downcase}_error",
+          context: { service: service, operation: operation, original_error: error.class.name }
+        )
+      end
+    end
+
+    # Convert an HTTP response to a structured error.
+    #
+    # @param response [Net::HTTPResponse] The HTTP response
+    # @param service [String] The service name
+    # @param operation [String] The operation being performed
+    # @return [BrainzLab::Error] A structured BrainzLab error
+    def from_response(response, service:, operation:)
+      status_code = response.code.to_i
+      body = parse_response_body(response)
+      message = body[:message] || body[:error] || "HTTP #{status_code}"
+      request_id = response['X-Request-Id']
+
+      case status_code
+      when 400
+        ValidationError.new(
+          message,
+          hint: body[:hint] || 'Check the request parameters.',
+          code: body[:code] || 'bad_request',
+          context: { service: service, operation: operation, status_code: status_code }
+        )
+      when 401
+        AuthenticationError.new(
+          message,
+          hint: body[:hint] || "Verify your #{service} API key is correct and active.",
+          code: body[:code] || 'unauthorized',
+          context: { service: service, operation: operation }
+        )
+      when 403
+        AuthenticationError.new(
+          message,
+          hint: body[:hint] || 'Your API key does not have permission for this operation.',
+          code: body[:code] || 'forbidden',
+          context: { service: service, operation: operation }
+        )
+      when 404
+        NotFoundError.new(
+          message,
+          hint: body[:hint] || 'The requested resource does not exist.',
+          code: body[:code] || 'not_found',
+          context: { service: service, operation: operation }
+        )
+      when 422
+        ValidationError.new(
+          message,
+          hint: body[:hint] || 'The request was well-formed but contained invalid data.',
+          code: body[:code] || 'unprocessable_entity',
+          errors: body[:errors],
+          context: { service: service, operation: operation, status_code: status_code }
+        )
+      when 429
+        RateLimitError.new(
+          message,
+          retry_after: response['Retry-After']&.to_i,
+          limit: response['X-RateLimit-Limit']&.to_i,
+          remaining: response['X-RateLimit-Remaining']&.to_i,
+          context: { service: service, operation: operation }
+        )
+      when 500..599
+        ServerError.new(
+          message,
+          hint: body[:hint] || 'A server error occurred. Please retry your request.',
+          code: body[:code] || "server_error_#{status_code}",
+          status_code: status_code,
+          request_id: request_id,
+          context: { service: service, operation: operation }
+        )
+      else
+        Error.new(
+          message,
+          hint: body[:hint],
+          code: body[:code] || "http_#{status_code}",
+          context: { service: service, operation: operation, status_code: status_code }
+        )
+      end
+    end
+
+    def parse_response_body(response)
+      JSON.parse(response.body, symbolize_names: true)
+    rescue JSON::ParserError, TypeError
+      {}
+    end
+  end
+end

data/lib/brainzlab/nerve/client.rb

@@ -208,7 +208,27 @@ module BrainzLab
       end
 
       def log_error(operation, error)
-        BrainzLab.debug_log("[Nerve::Client] #{operation} failed: #{error.message}")
+        structured_error = ErrorHandler.wrap(error, service: 'Nerve', operation: operation)
+        BrainzLab.debug_log("[Nerve::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Nerve', 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)
+
+        structured_error = ErrorHandler.from_response(response, service: 'Nerve', operation: operation)
+        BrainzLab.debug_log("[Nerve::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Nerve', operation: operation })
+        end
+
+        structured_error
       end
     end
   end