bug_reports_client 0.1.0

data/db/migrate/20260723000002_create_bug_report_error_events.rb

@@ -0,0 +1,20 @@
+# Per-user log of captured 500s. When a signed-in user hits an error, an
+# event is recorded against them so the bug report form can ask "did your
+# problem relate to this error?" and thread the details into the report.
+class CreateBugReportErrorEvents < ActiveRecord::Migration[8.0]
+  def change
+    return if table_exists?(:bug_report_error_events)
+
+    create_table :bug_report_error_events do |t|
+      t.bigint :user_id, null: false
+      t.string :fingerprint, null: false
+      t.string :exception_class, null: false
+      t.string :message
+      t.datetime :occurred_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :bug_report_error_events, [ :user_id, :occurred_at ]
+  end
+end

data/db/migrate/20260723000003_add_activity_to_bug_report_error_events.rb

@@ -0,0 +1,10 @@
+# Human-readable description of what the user was doing when the error was
+# captured ("viewing invoices") - shown on the report form instead of the
+# technical exception details.
+class AddActivityToBugReportErrorEvents < ActiveRecord::Migration[8.0]
+  def change
+    return if column_exists?(:bug_report_error_events, :activity)
+
+    add_column :bug_report_error_events, :activity, :string
+  end
+end

data/lib/bug_reports_client/configuration.rb

@@ -0,0 +1,121 @@
+module BugReportsClient
+  # Holds all host-app configuration for the engine. Every setting has a
+  # sensible default (mostly environment-variable backed) so a typical host
+  # only needs to set `source` in its initializer:
+  #
+  #   BugReportsClient.configure do |config|
+  #     config.source = "myapp"
+  #   end
+  #
+  # Wording is intentionally NOT configured here - all user-facing copy lives
+  # in i18n (see config/locales/en.yml) and form fields are defined in the
+  # form schema YAML, so this class only carries behavioural settings.
+  class Configuration
+    # Connection to the bug-reports API.
+    attr_accessor :api_url, :api_key, :webhook_secret
+
+    # Identity of this app. `source` must match the ApiKey name registered on
+    # the API and a key in its repo mapping. `app_host` is the public HTTPS
+    # origin of this app, used to build the callback URL and screenshot links.
+    attr_accessor :source, :app_host, :app_name
+
+    # Where the engine is mounted, used to derive the default callback URL.
+    attr_accessor :mount_path
+    attr_writer :callback_url
+
+    # Integration with the host's controllers and user model.
+    # `authenticate_method` is the host method the engine calls to enforce
+    # login. Set it to nil when the parent_controller already authenticates
+    # globally (e.g. its own before_action :authenticate_user!, which the
+    # engine inherits) so authentication does not run twice per request.
+    attr_accessor :parent_controller, :current_user_method, :authenticate_method,
+                  :user_class, :reporter_email_method, :reporter_name_method
+
+    # Behavioural flags. `reporter_external` and `admin_check` are procs
+    # receiving the current user; `ask_severity` hides the severity picker
+    # (consumer-facing apps) and submits `default_severity` instead.
+    attr_accessor :reporter_external, :admin_check, :ask_severity,
+                  :default_severity, :screenshots_enabled, :max_screenshots,
+                  :screenshot_content_types, :max_screenshot_size
+
+    # Automatic error capture (Sentry-style 500 reporting). Opt-in per host;
+    # `error_ignore` lists extra exception class names to skip (classes Rails
+    # maps to non-5xx responses are skipped automatically), and the throttle
+    # limits how often one fingerprint is posted from this app.
+    attr_accessor :error_reporting_enabled, :error_ignore, :error_throttle_period
+
+    # Optional overrides for the form definition and GitHub issue template.
+    # When nil, the engine looks for config/bug_report_form.yml and
+    # config/bug_report_issue.md in the host app, then falls back to its own
+    # defaults.
+    attr_accessor :form_schema_path, :issue_template_path
+
+    def initialize
+      @api_url = ENV.fetch("BUG_REPORT_API_URL", "http://localhost:3002/api")
+      @api_key = ENV["BUG_REPORT_API_KEY"]
+      @webhook_secret = ENV["BUG_REPORT_WEBHOOK_SECRET"]
+      @app_host = ENV["APP_HOST"]
+      @app_name = nil
+      @source = nil
+      @mount_path = "/bug_reports"
+      @callback_url = nil
+      @parent_controller = "::ApplicationController"
+      @current_user_method = :current_user
+      @authenticate_method = :authenticate_user!
+      @user_class = "User"
+      @reporter_email_method = :email
+      @reporter_name_method = :name
+      @reporter_external = ->(_user) { false }
+      @admin_check = ->(_user) { false }
+      @ask_severity = true
+      @default_severity = "medium"
+      @screenshots_enabled = true
+      @max_screenshots = 5
+      @screenshot_content_types = %w[image/png image/jpeg image/gif image/webp]
+      @max_screenshot_size = 10 * 1024 * 1024
+      @form_schema_path = nil
+      @issue_template_path = nil
+      @error_reporting_enabled = false
+      @error_ignore = []
+      @error_throttle_period = 300
+    end
+
+    # The URL the API calls back when a report's GitHub issue is closed.
+    # Must be public HTTPS in production - the API refuses private hosts.
+    def callback_url
+      @callback_url || begin
+        raise ConfigurationError, "BugReportsClient: set config.app_host (or APP_HOST) so the callback URL can be built" if app_host.blank?
+        File.join(app_host, mount_path, "webhook")
+      end
+    end
+
+    def source!
+      raise ConfigurationError, "BugReportsClient: config.source is required (must match your API key name)" if source.blank?
+      source
+    end
+
+    # Reporter attribute readers accept either a method name (symbol) or a
+    # proc, so hosts without e.g. a `name` method can supply a lambda.
+    def reporter_email_for(user)
+      resolve(reporter_email_method, user)
+    end
+
+    def reporter_name_for(user)
+      resolve(reporter_name_method, user)
+    end
+
+    def external_reporter?(user)
+      !!reporter_external.call(user)
+    end
+
+    def admin?(user)
+      !!admin_check.call(user)
+    end
+
+    private
+
+    def resolve(method_or_proc, user)
+      method_or_proc.respond_to?(:call) ? method_or_proc.call(user) : user.public_send(method_or_proc)
+    end
+  end
+end

data/lib/bug_reports_client/engine.rb

@@ -0,0 +1,49 @@
+module BugReportsClient
+  # Wires the engine into the host app: asset paths for Propshaft, importmap
+  # pins for the Stimulus controllers, and helper exposure so host layouts can
+  # call `bug_report_alerts` directly.
+  class Engine < ::Rails::Engine
+    isolate_namespace BugReportsClient
+
+    config.generators do |g|
+      g.test_framework :test_unit
+    end
+
+    # Serve the engine's JavaScript through the host's asset pipeline.
+    initializer "bug_reports_client.assets" do |app|
+      app.config.assets.paths << root.join("app/javascript") if app.config.respond_to?(:assets)
+    end
+
+    # Merge the engine's importmap pins into the host importmap. The pins live
+    # under controllers/bug_reports_client/, which both eagerLoadControllersFrom
+    # and lazyLoadControllersFrom scan, so the Stimulus controllers register as
+    # bug-reports-client--report-type and bug-reports-client--file-limit with
+    # no host JavaScript changes.
+    initializer "bug_reports_client.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << root.join("app/javascript")
+      end
+    end
+
+    # Make engine helpers (bug_report_alerts and the badge helpers) available
+    # in host views, so layouts can render the resolved-report alerts with a
+    # single line.
+    initializer "bug_reports_client.helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        helper BugReportsClient::Engine.helpers
+        # Tag requests with the current user so captured 500s can be
+        # attributed to whoever hit them (see ErrorContext).
+        include BugReportsClient::ErrorContext
+      end
+    end
+
+    # Automatic 500 capture: subscribe to the Rails error reporter. The
+    # subscription is unconditional (and cheap) - the reporter itself checks
+    # config.error_reporting_enabled per report, so hosts can toggle the
+    # flag without a restart and tests behave predictably.
+    config.after_initialize do
+      Rails.error.subscribe(BugReportsClient::ErrorReporter.new)
+    end
+  end
+end

data/lib/bug_reports_client/error_context.rb

@@ -0,0 +1,31 @@
+module BugReportsClient
+  # Included into ActionController::Base by the engine so every request tags
+  # the Rails error-reporting context with the signed-in user's id. When an
+  # unhandled 500 is captured, the reporter reads the id back and records an
+  # ErrorEvent against that user - powering the "did your problem relate to
+  # this error?" prompt on the bug report form. Deliberately silent on any
+  # failure: attribution is best-effort and must never affect the request.
+  module ErrorContext
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :set_bug_reports_error_context
+    end
+
+    private
+
+    def set_bug_reports_error_context
+      context = { bug_reports_controller: controller_name, bug_reports_action: action_name }
+
+      method = BugReportsClient.config.current_user_method
+      if respond_to?(method, true)
+        user = send(method)
+        context[:bug_reports_user_id] = user.id if user.respond_to?(:id) && user&.id
+      end
+
+      Rails.error.set_context(**context)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/bug_reports_client/error_reporter.rb

@@ -0,0 +1,116 @@
+require "digest"
+
+module BugReportsClient
+  # Subscribes to the Rails error reporter and turns unhandled exceptions
+  # (real 500s) into error reports on the central API, which files one GitHub
+  # issue per distinct error. Sentry-style basics without the Sentry:
+  #
+  #   - Only unhandled errors are captured, and only ones Rails would answer
+  #     with a 5xx (RecordNotFound and friends map to 4xx and are skipped).
+  #   - Errors are fingerprinted by exception class + the top application
+  #     backtrace frame (line numbers stripped, so deploys that shift code
+  #     around keep the same fingerprint).
+  #   - A cache-based throttle stops an error storm flooding the API; the
+  #     API deduplicates authoritatively by fingerprint regardless.
+  #
+  # Enable per host with config.error_reporting_enabled = true.
+  class ErrorReporter
+    BACKTRACE_LINES = 20
+
+    # Called by Rails.error for every reported error. Must never raise -
+    # error reporting failing inside a failing request would mask the
+    # original problem.
+    def report(error, handled:, severity: nil, context: {}, source: nil)
+      return if handled
+      return unless BugReportsClient.config.error_reporting_enabled
+      return if ignored?(error)
+
+      fingerprint = self.class.fingerprint_for(error)
+      record_user_event(error, fingerprint, context)
+
+      return unless claim!(fingerprint)
+
+      ReportErrorJob.perform_later(
+        "fingerprint" => fingerprint,
+        "exception_class" => error.class.name,
+        "message" => error.message.to_s.truncate(2_000),
+        "backtrace" => cleaned_backtrace(error),
+        "occurred_at" => Time.current.iso8601
+      )
+    rescue StandardError => e
+      Rails.logger.error "BugReportsClient: error reporter failed: #{e.class}: #{e.message}"
+      nil
+    end
+
+    # Stable identity for "the same error": class + top application frame
+    # with the line number stripped, so unrelated code changes moving lines
+    # around do not spawn new issues.
+    def self.fingerprint_for(error)
+      frame = Rails.backtrace_cleaner.clean(error.backtrace || []).first.to_s
+      frame = frame.sub(/:\d+:in /, ":in ")
+      Digest::SHA256.hexdigest("#{error.class.name}|#{frame}")[0, 16]
+    end
+
+    private
+
+    # Skips exception classes Rails maps to non-5xx responses (RecordNotFound
+    # -> 404 etc), plus any classes the host lists in config.error_ignore.
+    def ignored?(error)
+      return true if BugReportsClient.config.error_ignore.include?(error.class.name)
+
+      status = ActionDispatch::ExceptionWrapper.rescue_responses[error.class.name]
+      status.present? && Rack::Utils.status_code(status) < 500
+    end
+
+    # One report per fingerprint per throttle period, enforced through the
+    # host's cache. A cache without unless_exist support just means more
+    # posts - the API deduplicates anyway.
+    def claim!(fingerprint)
+      Rails.cache.write(
+        "bug_reports_client:error:#{fingerprint}",
+        true,
+        unless_exist: true,
+        expires_in: BugReportsClient.config.error_throttle_period
+      )
+    end
+
+    def cleaned_backtrace(error)
+      Rails.backtrace_cleaner.clean(error.backtrace || []).first(BACKTRACE_LINES)
+    end
+
+    # Attributes the error to the signed-in user who hit it (id set by
+    # ErrorContext), so the report form can offer "did it relate to this
+    # error?". Recorded on EVERY occurrence - unlike the API post, which is
+    # throttled - and best-effort: failures are swallowed.
+    def record_user_event(error, fingerprint, context)
+      user_id = context[:bug_reports_user_id]
+      return if user_id.blank?
+
+      ErrorEvent.record!(
+        user_id: user_id,
+        fingerprint: fingerprint,
+        exception_class: error.class.name,
+        message: error.message,
+        activity: activity_from(context),
+        occurred_at: Time.current
+      )
+    rescue StandardError => e
+      Rails.logger.debug { "BugReportsClient: error event not recorded (#{e.class}: #{e.message})" }
+      nil
+    end
+
+    # Human-readable "what the user was doing" - shown to users on the report
+    # form in place of exception details. Built from the controller/action at
+    # capture time: "viewing invoices", "saving changes to players".
+    def activity_from(context)
+      controller = context[:bug_reports_controller]
+      return nil if controller.blank?
+
+      verb = I18n.t(
+        "bug_reports_client.activities.#{context[:bug_reports_action]}",
+        default: I18n.t("bug_reports_client.activities.other")
+      )
+      "#{verb} #{controller.to_s.humanize.downcase}"
+    end
+  end
+end

data/lib/bug_reports_client/form_schema.rb

@@ -0,0 +1,204 @@
+require "yaml"
+
+module BugReportsClient
+  # Loads and validates the YAML form definition that drives the report form.
+  #
+  # Resolution order for the schema file:
+  #   1. config.form_schema_path (explicit override)
+  #   2. <host app>/config/bug_report_form.yml
+  #   3. the engine's config/form_schema.yml default
+  #
+  # Schema shape - top-level keys are report types (bug/feature), each holding
+  # an ordered list of fields:
+  #
+  #   bug:
+  #     - field: steps_to_reproduce
+  #       type: textarea          # text | textarea | select | checkbox
+  #       required: true
+  #       section: reproduction   # optional - starts a new card in the form
+  #       rows: 4                 # textareas only
+  #       options: [Chrome, Safari]  # selects only
+  #       label: "How can we see this?"   # optional - falls back to i18n
+  #       placeholder: "..."              # optional - falls back to i18n
+  #       help: "..."                     # optional - falls back to i18n
+  #
+  # Answers are stored in BugReport#responses keyed by the field name. A
+  # feature field named `priority` doubles as the report's importance rating
+  # shown in list views (mirroring severity for bugs).
+  class FormSchema
+    REPORT_TYPES = %w[bug feature].freeze
+    FIELD_TYPES = %w[text textarea select checkbox].freeze
+
+    # A single form field parsed from the YAML definition.
+    Field = Struct.new(:key, :type, :required, :options, :section, :label, :placeholder, :help, :rows, keyword_init: true) do
+      def required? = !!required
+      def select? = type == "select"
+      def checkbox? = type == "checkbox"
+
+      # Wording resolution: inline schema values win, then i18n under
+      # bug_reports_client.fields.<key>.*, then a humanised fallback.
+      def label_text
+        label || I18n.t("bug_reports_client.fields.#{key}.label", default: key.humanize)
+      end
+
+      def placeholder_text
+        placeholder || I18n.t("bug_reports_client.fields.#{key}.placeholder", default: nil)
+      end
+
+      def help_text
+        help || I18n.t("bug_reports_client.fields.#{key}.help", default: nil)
+      end
+
+      def prompt_text
+        I18n.t("bug_reports_client.fields.#{key}.prompt",
+               default: I18n.t("bug_reports_client.form.select_prompt"))
+      end
+    end
+
+    class << self
+      # The active schema. Reloaded on every call in development so schema
+      # edits show up without a restart; memoised elsewhere.
+      def current
+        if Rails.env.development?
+          load_schema
+        else
+          @current ||= load_schema
+        end
+      end
+
+      def reset!
+        @current = nil
+      end
+
+      def default_path
+        Engine.root.join("config", "form_schema.yml")
+      end
+
+      private
+
+      def load_schema
+        new(resolve_path)
+      end
+
+      def resolve_path
+        explicit = BugReportsClient.config.form_schema_path
+        return Pathname.new(explicit) if explicit.present?
+
+        host_default = Rails.root.join("config", "bug_report_form.yml")
+        host_default.exist? ? host_default : default_path
+      end
+    end
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+      @fields_by_type = parse(path)
+    end
+
+    # Report types the schema defines, in file order. The form only shows the
+    # bug/feature toggle when more than one type is present.
+    def report_types
+      @fields_by_type.keys
+    end
+
+    def fields_for(report_type)
+      @fields_by_type.fetch(report_type.to_s, [])
+    end
+
+    def required_fields(report_type)
+      fields_for(report_type).select(&:required?)
+    end
+
+    # Every field key across all report types - used for strong parameters so
+    # only schema-declared answers are ever written to responses.
+    def field_keys
+      @fields_by_type.values.flatten.map(&:key).uniq
+    end
+
+    # Field keys for one report type, falling back to all keys when the type
+    # is unknown/blank. Used to scope strong parameters to the selected type
+    # so a bug submission can't smuggle in feature answers (and vice versa).
+    def field_keys_for(report_type)
+      fields = fields_for(report_type)
+      fields.any? ? fields.map(&:key).uniq : field_keys
+    end
+
+    # Fields grouped into ordered sections for rendering. Fields before any
+    # `section` marker fall into a nil section rendered without a heading.
+    def sections_for(report_type)
+      fields_for(report_type).chunk_while { |a, b| a.section == b.section }.map do |group|
+        [ group.first.section, group ]
+      end
+    end
+
+    private
+
+    def parse(path)
+      raise SchemaError, "Bug report form schema not found at #{path}" unless File.exist?(path)
+
+      raw = YAML.safe_load_file(path)
+      raise SchemaError, "#{path}: schema must be a hash of report types (bug/feature)" unless raw.is_a?(Hash)
+
+      raw.each_with_object({}) do |(report_type, fields), parsed|
+        unless REPORT_TYPES.include?(report_type.to_s)
+          raise SchemaError, "#{path}: unknown report type #{report_type.inspect} (expected one of #{REPORT_TYPES.join(', ')})"
+        end
+        raise SchemaError, "#{path}: #{report_type} must contain a list of fields" unless fields.is_a?(Array)
+
+        parsed[report_type.to_s] = fields.map { |definition| build_field(report_type, definition) }
+      end.tap do |parsed|
+        raise SchemaError, "#{path}: schema defines no report types" if parsed.empty?
+      end
+    end
+
+    def build_field(report_type, definition)
+      raise SchemaError, "#{path}: each #{report_type} field must be a hash with a `field` key" unless definition.is_a?(Hash)
+
+      key = definition["field"].to_s
+      raise SchemaError, "#{path}: #{report_type} entry missing `field` name: #{definition.inspect}" if key.blank?
+      unless key.match?(/\A[a-z][a-z0-9_]*\z/)
+        raise SchemaError, "#{path}: field name #{key.inspect} must be snake_case (letters, digits, underscores)"
+      end
+
+      type = (definition["type"] || "text").to_s
+      unless FIELD_TYPES.include?(type)
+        raise SchemaError, "#{path}: field #{key} has unknown type #{type.inspect} (expected one of #{FIELD_TYPES.join(', ')})"
+      end
+      if type == "select" && !definition["options"].is_a?(Array)
+        raise SchemaError, "#{path}: select field #{key} needs an `options` list"
+      end
+
+      Field.new(
+        key: key,
+        type: type,
+        required: definition["required"] || false,
+        options: normalise_options(key, definition["options"]),
+        section: definition["section"],
+        label: definition["label"],
+        placeholder: definition["placeholder"],
+        help: definition["help"],
+        rows: definition["rows"] || 3
+      )
+    end
+
+    # Select options may be plain strings (label doubles as the stored value)
+    # or {value:, label:} hashes when the stored value should differ from the
+    # display text. Normalised to [label, value] pairs for options_for_select.
+    def normalise_options(key, options)
+      return nil if options.nil?
+
+      options.map do |option|
+        case option
+        when String then [ option, option ]
+        when Hash
+          value = option["value"].to_s
+          raise SchemaError, "#{path}: option for #{key} missing `value`: #{option.inspect}" if value.blank?
+          [ option["label"] || value.humanize, value ]
+        else
+          raise SchemaError, "#{path}: option for #{key} must be a string or {value:, label:} hash"
+        end
+      end
+    end
+  end
+end

data/lib/bug_reports_client/main_app_routes.rb

@@ -0,0 +1,68 @@
+module BugReportsClient
+  # Included into engine views (via the engine's ApplicationController) so
+  # host layouts render unmodified inside engine pages. Isolated engines
+  # resolve route helpers against their own routes, which breaks host-only
+  # helpers (root_path, profile_path, etc) used in host layouts and navbars.
+  # This delegates any unknown *_path / *_url helper to the host app, while
+  # the engine's own helpers keep resolving first because they are real
+  # methods and never reach method_missing.
+  module MainAppRoutes
+    def method_missing(method, *args, &block)
+      if main_app_route_helper?(method)
+        main_app.public_send(method, *args)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      main_app_route_helper?(method) || super
+    end
+
+    # Active Storage URLs (blobs, attachments, variants - e.g. a user avatar
+    # in a host navbar, or image_tag on an attachment) resolve through
+    # polymorphic mappings that only exist on the HOST's route set, so route
+    # them there explicitly. image_tag goes through polymorphic_url, other
+    # callers through url_for - cover all three. Everything else keeps the
+    # normal lookup.
+    def url_for(argument = nil)
+      if MainAppRoutes.active_storage_argument?(argument)
+        main_app.polymorphic_path(argument)
+      else
+        super
+      end
+    end
+
+    def polymorphic_url(record, options = {})
+      if MainAppRoutes.active_storage_argument?(record)
+        main_app.polymorphic_url(record, options)
+      else
+        super
+      end
+    end
+
+    def polymorphic_path(record, options = {})
+      if MainAppRoutes.active_storage_argument?(record)
+        main_app.polymorphic_path(record, options)
+      else
+        super
+      end
+    end
+
+    def self.active_storage_argument?(argument)
+      return false unless defined?(ActiveStorage)
+
+      argument.is_a?(ActiveStorage::Blob) ||
+        argument.is_a?(ActiveStorage::Attachment) ||
+        argument.is_a?(ActiveStorage::Variant) ||
+        argument.is_a?(ActiveStorage::VariantWithRecord) ||
+        argument.is_a?(ActiveStorage::Preview)
+    end
+
+    private
+
+    def main_app_route_helper?(method)
+      method.to_s.end_with?("_path", "_url") && main_app.respond_to?(method)
+    end
+  end
+end

data/lib/bug_reports_client/version.rb

@@ -0,0 +1,3 @@
+module BugReportsClient
+  VERSION = "0.1.0"
+end

data/lib/bug_reports_client.rb

@@ -0,0 +1,39 @@
+# Entry point for the bug_reports_client gem. Hosts configure the engine in an
+# initializer via BugReportsClient.configure and mount BugReportsClient::Engine
+# in their routes. See README.md for the full setup guide.
+require "bug_reports_client/version"
+require "bug_reports_client/configuration"
+require "bug_reports_client/form_schema"
+require "bug_reports_client/main_app_routes"
+require "bug_reports_client/error_reporter"
+require "bug_reports_client/error_context"
+require "bug_reports_client/engine"
+
+module BugReportsClient
+  # Raised when the gem is misconfigured (missing source, API key, etc).
+  class ConfigurationError < StandardError; end
+
+  # Raised when a host's form schema file is invalid.
+  class SchemaError < StandardError; end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield(config)
+    end
+
+    # Replaces the configuration entirely. Used by tests to reset state.
+    def reset_config!
+      @config = Configuration.new
+      FormSchema.reset!
+    end
+
+    # The active form schema (host override or the engine default).
+    def form_schema
+      FormSchema.current
+    end
+  end
+end