ask-solid_errors 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5fc53842cb442db8d1ca3b2545515ad9d4763bcdeec8dc93c375f3901c2b12f
+  data.tar.gz: 9f024d03059f3c96864991ef633d9d98ef86808c569d5c21094804f3a6d420c5
+SHA512:
+  metadata.gz: 7f48fdce7fe85b1b43f74d9c6720e159541984a1f9ce8cf4855cfa9fecbf97302d12d5c355bab1110d850ea674b1537ee59bbbde7f6eaf7fe760f8cac12c1431
+  data.tar.gz: 34bd2e2cbcb8ba7049c09de62c5bd60c4fd9ad858b79afe1aa647af0cfe1f158765b7cb86189e46e47bf9b14e7d2b04567e07d54e5183c56232e1cf1f1ad44af

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,26 @@
+# ask-solid_errors
+
+SolidErrors — error tracking stored in your Rails database
+
+## Installation
+
+```ruby
+gem "ask-solid_errors"
+```
+
+## Usage
+
+```ruby
+client = Ask::SolidErrors.client
+# ... use the client according to its API
+```
+
+## Development
+
+```bash
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/solid_errors/client.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Ask
+  module SolidErrors
+    # Returns a client proxy for querying SolidErrors.
+    #
+    # No authentication is needed — SolidErrors runs in the same database as the
+    # Rails app. The proxy delegates to +SolidErrors::Error+ and
+    # +SolidErrors::Occurrence+ models, returning +ActiveRecord::Relation+
+    # objects that can be further chained by the agent.
+    #
+    # @example
+    #   Ask::SolidErrors.recent(limit: 5)
+    #   Ask::SolidErrors.unresolved
+    #   Ask::SolidErrors.by_class("ActiveRecord::RecordNotFound")
+    #
+    # @return [ClientProxy] a proxy wrapping +SolidErrors::Error+
+    # @raise [LoadError] if the +solid_errors+ gem is not installed
+    def self.client
+      ensure_solid_errors_loaded!
+      ClientProxy.new
+    end
+
+    # Convenience — return the most recently recorded errors.
+    #
+    # @param limit [Integer] number of errors to return (default: 10)
+    # @return [ActiveRecord::Relation<SolidErrors::Error>]
+    def self.recent(limit: 10)
+      client.recent(limit: limit)
+    end
+
+    # Convenience — find a single error by its primary key.
+    #
+    # @param id [Integer, String] error record ID
+    # @return [SolidErrors::Error]
+    # @raise [ActiveRecord::RecordNotFound] if the record does not exist
+    def self.find(id)
+      client.find(id)
+    end
+
+    # Convenience — return all unresolved errors.
+    #
+    # @return [ActiveRecord::Relation<SolidErrors::Error>]
+    def self.unresolved
+      client.unresolved
+    end
+
+    # Convenience — return all resolved errors.
+    #
+    # @return [ActiveRecord::Relation<SolidErrors::Error>]
+    def self.resolved
+      client.resolved
+    end
+
+    # Convenience — filter errors by exception class name.
+    #
+    # @param klass [String] exception class name (e.g. "ActiveRecord::RecordNotFound")
+    # @return [ActiveRecord::Relation<SolidErrors::Error>]
+    def self.by_class(klass)
+      client.where(exception_class: klass)
+    end
+
+    # Convenience — filter errors by severity level.
+    #
+    # @param severity [String] severity level ("error", "warning", "info")
+    # @return [ActiveRecord::Relation<SolidErrors::Error>]
+    def self.by_severity(severity)
+      client.where(severity: severity)
+    end
+
+    # Convenience — search errors whose message contains the given text.
+    #
+    # @param query [String] search text
+    # @return [ActiveRecord::Relation<SolidErrors::Error>]
+    def self.search(query)
+      client.where("message LIKE ?", "%#{client.sanitize_sql_like(query)}%")
+    end
+
+    # Convenience — return the occurrence count for an error.
+    #
+    # @param error [SolidErrors::Error, Integer] error record or its ID
+    # @return [Integer]
+    def self.occurrence_count(error)
+      client.occurrence_count(error)
+    end
+
+    # Wraps +SolidErrors::Error+ and delegates query methods to it while
+    # providing a clean interface for AI agents.
+    class ClientProxy < BasicObject
+      def initialize
+        @model = ::SolidErrors::Error
+      end
+
+      # Delegate all known query methods to the SolidErrors model.
+      def method_missing(name, ...)
+        @model.public_send(name, ...)
+      rescue ::ActiveRecord::NoDatabaseError => e
+        ::Kernel.raise e, "SolidErrors database is not configured. " \
+                          "Run `bin/rails solid_errors:install:migrations db:migrate` first."
+      rescue ::ActiveRecord::StatementInvalid => e
+        if e.message.include?("solid_errors")
+          ::Kernel.raise e, "SolidErrors table does not exist. " \
+                            "Run `bin/rails solid_errors:install:migrations db:migrate` first."
+        else
+          ::Kernel.raise e
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @model.respond_to?(name, include_private) || super
+      end
+
+      # Return the most recent errors.
+      def recent(limit: 10)
+        @model.order(created_at: :desc).limit(limit)
+      end
+
+      # Return all unresolved errors.
+      def unresolved
+        @model.unresolved.order(created_at: :desc)
+      end
+
+      # Return all resolved errors.
+      def resolved
+        @model.resolved.order(created_at: :desc)
+      end
+
+      # Return the occurrence count for an error.
+      def occurrence_count(error)
+        error = @model.find(error) unless error.is_a?(::ActiveRecord::Base)
+        error.occurrences.count
+      end
+    end
+
+    # Raise +LoadError+ with a clear message when the +solid_errors+ gem
+    # is not available.
+    def self.ensure_solid_errors_loaded!
+      return if defined?(::SolidErrors)
+
+      raise ::LoadError, "The `solid_errors` gem is not installed. " \
+                         "Add `gem 'solid_errors'` to your Gemfile and run `bundle install`."
+    end
+  end
+end

data/lib/ask/solid_errors/context.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Ask
+  module SolidErrors
+    # Human-readable description of the SolidErrors service context.
+    DESCRIPTION = "SolidErrors — error tracking stored in your Rails database"
+
+    # Gem name for the SolidErrors tracker.
+    GEM_NAME = "solid_errors"
+
+    # Quick-start Ruby code snippet for agents to copy-paste.
+    QUICK_START = <<~RUBY
+      errors = Ask::SolidErrors.recent(limit: 10)
+      errors.map { |e| { id: e.id, class: e.exception_class, message: e.message.truncate(200) } }
+
+      # Or get full details:
+      error = Ask::SolidErrors.find(id)
+      error.backtrace
+      error.context
+
+      # Or work with occurrences:
+      error = Ask::SolidErrors.find(id)
+      error.occurrences.each do |occ|
+        puts occ.parsed_backtrace
+      end
+    RUBY
+  end
+end

data/lib/ask/solid_errors/error_guide.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Ask
+  module SolidErrors
+    # Structured error knowledge for AI agents working with SolidErrors.
+    #
+    # Provides human-readable guidance for common Rails exception classes,
+    # error severity levels, and database-related issues encountered when
+    # querying SolidErrors records.
+    module Errors
+      # Common Rails exception classes and actionable guidance.
+      EXCEPTIONS = {
+        "ActiveRecord::RecordNotFound" => {
+          message: "A record was not found by its primary key or finder.",
+          action: "Check that the ID exists in the database. The record may have been deleted."
+        },
+        "ActiveRecord::RecordInvalid" => {
+          message: "A record failed validation.",
+          action: "Inspect the record's errors to see which validations failed."
+        },
+        "ActiveRecord::RecordNotSaved" => {
+          message: "A record could not be saved due to base errors or callbacks.",
+          action: "Check for before_save/before_create callbacks that return false."
+        },
+        "ActiveRecord::RecordNotDestroyed" => {
+          message: "A record could not be destroyed due to before_destroy callbacks.",
+          action: "Check for before_destroy callbacks that return false."
+        },
+        "ActiveRecord::StatementInvalid" => {
+          message: "An SQL statement failed to execute.",
+          action: "Check the SQL statement and database schema. The query may reference a missing column or table."
+        },
+        "ActiveRecord::ConnectionNotEstablished" => {
+          message: "No database connection is available.",
+          action: "Check database configuration and that the database server is running."
+        },
+        "ActiveRecord::Migration::PendingMigrationError" => {
+          message: "There are pending database migrations.",
+          action: "Run `bin/rails db:migrate` to apply pending migrations."
+        },
+        "ActiveRecord::NoDatabaseError" => {
+          message: "The database does not exist.",
+          action: "Run `bin/rails db:create` to create the database."
+        },
+        "ActiveRecord::Deadlocked" => {
+          message: "A database deadlock was detected.",
+          action: "Retry the transaction. Ensure consistent lock ordering in concurrent operations."
+        },
+        "ActiveRecord::LockWaitTimeout" => {
+          message: "A database lock wait timeout expired.",
+          action: "Reduce contention on the locked resource or increase the lock timeout."
+        },
+        "ActionController::RoutingError" => {
+          message: "No route matches the requested URL.",
+          action: "Check the URL and your routes file. Run `bin/rails routes` to see available routes."
+        },
+        "ActionController::ParameterMissing" => {
+          message: "A required parameter was not provided.",
+          action: "Check the required parameters for the action and ensure they are included in the request."
+        },
+        "ActionController::InvalidAuthenticityToken" => {
+          message: "The CSRF authenticity token is invalid.",
+          action: "Ensure forms include the CSRF token. This can happen after a session expires."
+        },
+        "ActiveSupport::MessageVerifier::InvalidSignature" => {
+          message: "A signed message has an invalid signature.",
+          action: "The data may have been tampered with, or the secret key base has changed since signing."
+        },
+        "Net::ReadTimeout" => {
+          message: "An external HTTP request timed out while reading the response.",
+          action: "Check the external service availability and response time. Consider increasing the timeout."
+        },
+        "Net::OpenTimeout" => {
+          message: "An external HTTP connection timed out.",
+          action: "Check network connectivity and that the external service is reachable."
+        },
+        "SystemExit" => {
+          message: "The process was asked to exit by calling exit or abort.",
+          action: "This may be intentional (e.g., abort in a callback). Check the exit code."
+        },
+        "SignalException" => {
+          message: "The process received a signal (e.g., SIGTERM, SIGINT).",
+          action: "The process was interrupted externally. This is expected during deploys or shutdowns."
+        },
+        "NoMemoryError" => {
+          message: "The system ran out of memory.",
+          action: "Reduce memory usage or increase available memory. Check for memory leaks."
+        }
+      }.freeze
+
+      # Error severity levels used by SolidErrors and how to respond.
+      SEVERITIES = {
+        "error" => {
+          description: "🔥 An actual error occurred that requires investigation.",
+          action: "Prioritize review. Check the backtrace and context for the root cause."
+        },
+        "warning" => {
+          description: "⚠️  An unexpected condition occurred but the request completed.",
+          action: "Review when convenient. May indicate an edge case or degraded experience."
+        },
+        "info" => {
+          description: "ℹ️  An informational event was logged.",
+          action: "No immediate action needed. Useful for auditing and debugging."
+        }
+      }.freeze
+
+      # Database-related guidance for SolidErrors configuration.
+      DATABASE = {
+        table_name: "solid_errors",
+        occurrences_table_name: "solid_errors_occurrences",
+        migration_instructions: "Run `bin/rails solid_errors:install:migrations` then `bin/rails db:migrate`",
+        table_structure: {
+          "solid_errors" => [
+            "exception_class (text) — the exception class name (e.g. ActiveRecord::RecordNotFound)",
+            "message (text) — the exception message",
+            "severity (text) — error, warning, or info",
+            "source (text, nullable) — source of the error",
+            "resolved_at (datetime, nullable) — when the error was resolved",
+            "fingerprint (string, unique) — SHA256 hash for deduplication"
+          ],
+          "solid_errors_occurrences" => [
+            "error_id (integer) — FK to solid_errors.id",
+            "backtrace (text) — the exception backtrace",
+            "context (json) — structured context data from the error"
+          ]
+        }
+      }.freeze
+
+      # Look up guidance for a Rails exception class name.
+      #
+      # @param exception_class [String] The exception class name (e.g. "ActiveRecord::RecordNotFound")
+      # @return [Hash, nil] A hash with +:message+ and +:action+ keys, or nil if unknown
+      def self.for(exception_class)
+        EXCEPTIONS[exception_class]
+      end
+
+      # Describe a severity level.
+      #
+      # @param severity [String] severity level ("error", "warning", "info")
+      # @return [Hash, nil] Description of the severity, or nil if unknown
+      def self.severity_description(severity)
+        SEVERITIES[severity.to_s]
+      end
+    end
+  end
+end

data/lib/ask/solid_errors/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module SolidErrors
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask-solid_errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "ask/solid_errors/version"
+require_relative "ask/solid_errors/context"
+require_relative "ask/solid_errors/client"
+require_relative "ask/solid_errors/error_guide"

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: ask-solid_errors
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: ask-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: Error context for agents via SolidErrors for the ask-rb ecosystem.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ask-solid_errors.rb
+- lib/ask/solid_errors/client.rb
+- lib/ask/solid_errors/context.rb
+- lib/ask/solid_errors/error_guide.rb
+- lib/ask/solid_errors/version.rb
+homepage: https://github.com/ask-rb/ask-solid_errors
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: SolidErrors — error tracking stored in your Rails database
+test_files: []