bug_reports_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ddf7fc7f7b28ffe23e4a4e2965343975fc2d353887f7215e3c7de627259caa34
+  data.tar.gz: f5d7058b59536805b5c3554c7a1b34fc367a4db509fd804489bba639b153fed9
+SHA512:
+  metadata.gz: cc3d27ecbfb780ff73c4d13171d03ce10994c780303b4e50ead54a498b4c51725fe6b38cfb2dcd2d4f818baa875a3ac7286b0618ef082fd9d18bddb2865ef2aa
+  data.tar.gz: 46f0ce019b199b6a86901d4b932905666e28689ba7221e0e5d534a5a98b1a15567bb9353d2978a5f652b4accfdb2de4506391ea1b9a50b80239e14abf966a239

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 (23 July 2026)
+
+- Initial release: mountable engine with a schema-driven report form
+  (YAML-defined fields, report type cards, drag-and-drop screenshots with
+  previews), my-reports and all-reports views, submission to the companion
+  bug-reports API, signed closure webhooks (timestamped, replay-protected)
+  and dismissable resolved-report alerts.
+- Automatic error capture: unhandled 500s become deduplicated GitHub issues,
+  attributed to the user who hit them so the report form can offer
+  "did it relate to this error?".
+- Install and views generators, i18n-based wording, optional markdown issue
+  template with placeholder substitution.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 PSA Squash Tour
+
+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,281 @@
+# bug_reports_client
+
+A mountable Rails engine that adds a complete bug-and-feature reporting flow
+to your app, backed by a central [bug-reports API](../README.md) that files
+GitHub issues and calls back when they are closed.
+
+What your users get:
+
+- A polished **report form** with a bug/feature toggle, driven entirely by a
+  YAML schema you can customise per app - fields, types, required flags,
+  sections and wording.
+- **Screenshot uploads** (Active Storage, optional).
+- A **"My Reports"** page tracking the status of everything they've filed,
+  plus an admin-only "All Reports" view.
+- **Resolved alerts**: when the GitHub issue is closed, a signed webhook flips
+  the local record and the reporter sees a dismissable "your report has been
+  resolved" banner.
+
+Requirements: Rails >= 8.0, Turbo/Stimulus via importmap-rails, Tailwind CSS
+(for the default views - or copy the views and style them however you like).
+
+## Installation
+
+```ruby
+# Gemfile
+gem "bug_reports_client", github: "Professional-Squash-Association/bug-reports", glob: "client/*.gemspec"
+```
+
+```bash
+bundle install
+bin/rails g bug_reports_client:install
+bin/rails bug_reports_client:install:migrations && bin/rails db:migrate
+```
+
+The install generator creates `config/initializers/bug_reports_client.rb`,
+mounts the engine at `/bug_reports`, and copies the default form schema to
+`config/bug_report_form.yml` ready to customise. It prints the remaining
+checklist:
+
+```ruby
+# app/models/user.rb
+include BugReportsClient::Reporter
+```
+
+```erb
+<%# somewhere in your layout %>
+<%= link_to "Report a bug", bug_reports_client.new_bug_report_path %>
+<%= bug_report_alerts %>
+```
+
+Environment variables (or set the equivalents in the initializer):
+
+| Variable | Purpose |
+|---|---|
+| `BUG_REPORT_API_URL` | Base URL of the bug-reports API, e.g. `https://bugs.example.com/api` |
+| `BUG_REPORT_API_KEY` | This app's API token (Bearer auth) |
+| `BUG_REPORT_WEBHOOK_SECRET` | This app's webhook secret (HMAC verification of closure callbacks) |
+| `APP_HOST` | Public HTTPS origin of this app (callback URL + screenshot links) |
+
+On the API side, the app needs an `ApiKey` record and an entry in
+`config/repo_mapping.yml` mapping its `source` name to a GitHub repository.
+
+## Configuration
+
+Everything lives in the initializer. Only `source` is required; the rest have
+sensible defaults:
+
+```ruby
+BugReportsClient.configure do |config|
+  config.source = "myapp"                 # must match the API key name
+
+  # Host integration (defaults shown)
+  config.parent_controller = "::ApplicationController"
+  config.current_user_method = :current_user
+  config.authenticate_method = :authenticate_user!
+  config.user_class = "User"
+  config.reporter_email_method = :email   # symbol or ->(user) { ... }
+  config.reporter_name_method = :name
+
+  # Behaviour
+  config.admin_check = ->(user) { user.admin? }   # gates /bug_reports/all
+  config.reporter_external = ->(user) { false }   # shown on the GitHub issue
+  config.ask_severity = true               # false hides the picker...
+  config.default_severity = "medium"       # ...and submits this for bugs
+  config.screenshots_enabled = true        # needs publicly reachable storage
+  config.max_screenshots = 5
+
+  # Connection (default from ENV as above)
+  # config.api_url / config.api_key / config.webhook_secret / config.app_host
+  # config.callback_url                    # override the derived callback URL
+  # config.mount_path = "/bug_reports"     # if you mount somewhere else
+  # config.app_name = "My App"             # {{app_name}} in issue templates
+end
+```
+
+## Customising the form
+
+`config/bug_report_form.yml` defines the fields per report type:
+
+```yaml
+bug:
+  - field: what_happened
+    type: textarea          # text | textarea | select | checkbox
+    required: true
+    section: the_problem    # starts a new card; heading via i18n or humanised
+    rows: 4
+  - field: browser
+    type: select
+    options: [Chrome, Safari, Firefox, Other]      # or {value:, label:} pairs
+feature:
+  - field: problem
+    type: textarea
+    required: true
+```
+
+Delete the file to fall back to the engine's default schema (a
+well-rounded bug/feature form). Define only one report type and the
+bug/feature toggle disappears.
+
+Answers are stored in a JSON `responses` column, validated server-side from
+the same schema (required flags, and only schema-declared keys are permitted).
+
+### Wording
+
+All copy is i18n under the `bug_reports_client` namespace - override any
+subset in your own locale files, no view copying needed:
+
+```yaml
+en:
+  bug_reports_client:
+    new:
+      heading: "Report an issue"
+    fields:
+      what_happened:
+        label: "What happened?"
+        placeholder: "Tell us what went wrong"
+```
+
+Inline `label`/`placeholder`/`help` keys in the schema win over i18n.
+
+### GitHub issue body
+
+By default the issue body is generated from the schema: a `## <label>` section
+per answered field, a severity line for bugs, and screenshot links. To control
+it yourself, create `config/bug_report_issue.md` (the install generator drops
+an `.example` next to it) using `{{field}}` placeholders - every schema field
+key plus `{{title}}`, `{{report_type}}`, `{{severity}}`, `{{reporter_name}}`,
+`{{app_name}}` and `{{screenshots}}`.
+
+### Views
+
+The default views are plain Tailwind. To restyle:
+
+```bash
+bin/rails g bug_reports_client:views
+```
+
+copies them into `app/views/bug_reports_client/` where they shadow the
+engine's per file. The form posts a stable param contract, so you can also
+hand-write a completely custom form - anything that submits these names works:
+
+```
+bug_report[title]
+bug_report[report_type]                bug | feature
+bug_report[severity]                   low | medium | high | critical (bugs)
+bug_report[responses][<field_key>]     one per schema field
+bug_report[screenshots][]              file uploads (optional)
+```
+
+Hosts can also override just the Turbo Stream dismissal hook
+(`app/views/bug_reports_client/shared/_after_dismiss.turbo_stream.erb`) to
+update their own UI - e.g. a notification badge - when an alert is dismissed.
+
+## Styling
+
+The engine views use plain Tailwind utilities; your app compiles the CSS, so
+add the gem's views to your build:
+
+**Tailwind v3** (`config/tailwind.config.js`):
+
+```js
+const { execSync } = require('child_process');
+let bugReportsClient = '';
+try { bugReportsClient = execSync('bundle show bug_reports_client').toString().trim(); } catch (e) {}
+
+module.exports = {
+  content: [
+    './app/views/**/*.erb',
+    // ...existing globs...
+    bugReportsClient && `${bugReportsClient}/app/views/**/*.erb`,
+    bugReportsClient && `${bugReportsClient}/app/helpers/**/*.rb`,
+    bugReportsClient && `${bugReportsClient}/app/javascript/**/*.js`,
+  ].filter(Boolean),
+}
+```
+
+**Tailwind v4** (tailwindcss-rails >= 4.x): the engine ships
+`app/assets/tailwind/bug_reports_client/engine.css`; add to
+`app/assets/tailwind/application.css`:
+
+```css
+@import "../builds/tailwind/bug_reports_client";
+```
+
+## JavaScript
+
+Three Stimulus controllers ship with the engine and are pinned into your
+importmap automatically: `bug-reports-client--report-type` toggles the
+bug/feature field groups, `bug-reports-client--screenshot-dropzone` powers
+the drag-and-drop screenshot picker with thumbnail previews (the hidden file
+input stays the submission source, so custom forms can ignore it), and
+`bug-reports-client--file-limit` is a standalone file-count guard for
+hand-rolled forms. Any standard Stimulus setup that loads controllers from
+the importmap (`eagerLoadControllersFrom` / `lazyLoadControllersFrom`) picks
+them up with no changes.
+
+## Automatic error capture (Sentry-style)
+
+Opt in per host and unhandled 500s become GitHub issues, deduplicated:
+
+```ruby
+config.error_reporting_enabled = true
+config.error_ignore = []          # extra exception class names to skip
+config.error_throttle_period = 300 # seconds between posts per fingerprint
+```
+
+The engine subscribes to the Rails error reporter, so anything that would
+render a 500 is captured; exceptions Rails maps to 4xx responses
+(`RecordNotFound`, routing errors, etc) are skipped automatically. Errors
+are fingerprinted by exception class + top application frame (line numbers
+ignored, so deploys don't spawn duplicate issues), throttled through
+`Rails.cache`, and posted in a background job so failing requests are never
+slowed down. The API keeps one open issue per fingerprint, counting repeat
+occurrences; when a closed error recurs, a fresh issue is filed (a
+regression deserves new attention).
+
+Captured errors are also attributed to the signed-in user who hit them
+(stored locally in `bug_report_error_events`, pruned after 30 days). When
+that user opens the report form within 24 hours, it asks "did this happen
+alongside an error we caught?" - linking one threads the exception, time
+and fingerprint into their report, so the GitHub issue cross-references the
+automatically-filed error issue (search the repo for the fingerprint).
+Existing installs: run `bin/rails bug_reports_client:install:migrations &&
+bin/rails db:migrate` to pick up the events table.
+
+## Webhook contract
+
+The API POSTs closure callbacks to `<APP_HOST><mount_path>/webhook`, signed
+with your app's webhook secret. Preferred scheme: `X-Timestamp` plus
+`X-Signature-Timestamped: sha256=<hex>` where the HMAC-SHA256 covers
+`"<timestamp>.<body>"` - the engine rejects timestamps older than 5 minutes
+(replay protection). A legacy body-only `X-Signature` is also accepted when
+no timestamp is sent. Bodies over 1 MB are rejected outright. The engine
+verifies the signature, marks the local report closed, and returns 200. The
+callback URL must be public HTTPS.
+
+## Security notes
+
+- **Screenshots are validated server-side**: content type is sniffed from
+  the file bytes (not the client-declared type), and size/count limits apply
+  (`screenshot_content_types`, `max_screenshot_size`, `max_screenshots`).
+- **Screenshot URLs are embedded in GitHub issues** so maintainers can see
+  them - which means uploads become unauthenticated public URLs on your
+  storage service. If that's unacceptable, set `screenshots_enabled = false`
+  or serve Active Storage through expiring/signed URLs.
+- **Issue bodies contain verbatim user text.** Treat report content on the
+  receiving side (GitHub, the central API) as untrusted: user answers can
+  contain markdown, links and @mentions.
+- **The issue template path is trusted config.** `issue_template_path` (and
+  `config/bug_report_issue.md`) is read from disk verbatim - only ever point
+  it at a file you control.
+
+## Testing
+
+The engine has its own test suite with a dummy host app:
+
+```bash
+cd client
+bundle install
+bundle exec rake test
+```

data/app/assets/tailwind/bug_reports_client/engine.css

@@ -0,0 +1,7 @@
+/* Tailwind v4 hosts only (tailwindcss-rails >= 4.x engine support).
+   Tells the host's Tailwind build to scan the engine's views and JavaScript
+   for utility classes. Tailwind v3 hosts instead add the gem's paths to their
+   tailwind.config.js content globs - see the gem README. */
+@source "../../../views/bug_reports_client/**/*.erb";
+@source "../../../helpers/bug_reports_client/**/*.rb";
+@source "../../../javascript/bug_reports_client/**/*.js";

data/app/controllers/bug_reports_client/application_controller.rb

@@ -0,0 +1,35 @@
+module BugReportsClient
+  # Inherits from the host app's ApplicationController (configurable) so the
+  # engine's pages get the host layout, session handling and flash styling for
+  # free. Authentication is enforced through the configured method name, which
+  # covers both Devise hosts and bespoke session auth.
+  class ApplicationController < BugReportsClient.config.parent_controller.constantize
+    # Host layouts reference host route helpers; delegate the ones the engine
+    # doesn't define to the host app so layouts render unmodified.
+    helper BugReportsClient::MainAppRoutes
+
+    # Only enforce our own authentication when the host asks us to. Hosts that
+    # already authenticate globally (a `before_action :authenticate_user!` in
+    # their ApplicationController, which we inherit) set
+    # config.authenticate_method = nil to avoid running auth twice per request.
+    before_action :authenticate_reporter!, if: -> { BugReportsClient.config.authenticate_method.present? }
+
+    helper_method :bug_reports_current_user, :bug_reports_admin?
+
+    private
+
+    def authenticate_reporter!
+      send(BugReportsClient.config.authenticate_method)
+    end
+
+    # The signed-in user, via the host's configured accessor.
+    def bug_reports_current_user
+      send(BugReportsClient.config.current_user_method)
+    end
+
+    def bug_reports_admin?
+      user = bug_reports_current_user
+      user.present? && BugReportsClient.config.admin?(user)
+    end
+  end
+end

data/app/controllers/bug_reports_client/bug_reports_controller.rb

@@ -0,0 +1,308 @@
+module BugReportsClient
+  # Handles report submission, editing, listing and dismissal of resolved
+  # alerts. Reports are saved locally (screenshots via Active Storage), then
+  # submitted to the central bug-reports API which files a GitHub issue; the
+  # remote ID is stored so closure webhooks can find the local record.
+  class BugReportsController < ApplicationController
+    PER_PAGE = 20
+
+    before_action :set_bug_report, only: %i[edit update]
+    before_action :authorize_bug_report_access!, only: %i[edit update]
+    before_action :require_admin!, only: %i[all]
+
+    # GET /  (engine root) - the current user's reports
+    def index
+      reports = BugReport.where(user: bug_reports_current_user)
+      @bug_reports = paginate(filtered(reports).order(created_at: :desc))
+
+      @counts = status_counts(reports)
+      @type_counts = type_counts(reports)
+    end
+
+    # GET /all (admins via config.admin_check) - every report from this app
+    def all
+      @bug_reports = paginate(filtered(BugReport.includes(:user)).order(created_at: :desc))
+
+      @counts = status_counts(BugReport)
+      @type_counts = type_counts(BugReport)
+    end
+
+    # GET /new
+    def new
+      @bug_report = BugReport.new
+      @recent_error_events = recent_error_events
+    end
+
+    # GET /:id/edit - form for open (editable) and closed (read-only) reports
+    def edit
+    end
+
+    # POST /
+    # Saves the report and screenshots locally, submits to the API, then
+    # stores the returned remote ID. A failed API call rolls the local record
+    # back so users can retry without creating orphans.
+    def create
+      @bug_report = BugReport.new(bug_report_params)
+      @bug_report.user = bug_reports_current_user
+      apply_default_severity(@bug_report)
+      link_related_error(@bug_report)
+      @recent_error_events = recent_error_events
+
+      # Screenshot files are validated server-side (type sniffed, size and
+      # count checked) BEFORE anything is attached or saved.
+      unless validate_screenshots(@bug_report, submitted_screenshots)
+        render :new, status: :unprocessable_entity
+        return
+      end
+      attach_screenshots(@bug_report)
+
+      unless @bug_report.save
+        render :new, status: :unprocessable_entity
+        return
+      end
+
+      result = ApiClient.new.create_bug_report(
+        title: @bug_report.title,
+        description: DescriptionBuilder.new(@bug_report).build,
+        severity: @bug_report.severity,
+        report_type: @bug_report.report_type,
+        reporter_email: BugReportsClient.config.reporter_email_for(bug_reports_current_user),
+        reporter_name: BugReportsClient.config.reporter_name_for(bug_reports_current_user),
+        reporter_external: BugReportsClient.config.external_reporter?(bug_reports_current_user)
+      )
+
+      if result.success?
+        @bug_report.update!(remote_bug_report_id: result.data["id"])
+        redirect_to bug_reports_path, notice: t("bug_reports_client.flashes.created", type_noun: @bug_report.type_noun.capitalize)
+      else
+        # Surface the failure in the form's error box (which scrolls itself
+        # into view) rather than a top-of-page flash the user may never see.
+        @bug_report.destroy
+        @bug_report = BugReport.new
+        @bug_report.errors.add(:base, result.message)
+        render :new, status: :unprocessable_entity
+      end
+    rescue ApiClient::ApiError => e
+      @bug_report.destroy if @bug_report&.persisted?
+      @bug_report = BugReport.new
+      @bug_report.errors.add(:base, t("bug_reports_client.flashes.submit_failed"))
+      Rails.logger.error "BugReportsClient: submission failed: #{e.message}"
+      render :new, status: :unprocessable_entity
+    end
+
+    # PATCH /:id
+    # Two cases: dismissing a resolved alert (no bug_report params), or
+    # editing an open report (re-syncs the remote issue).
+    def update
+      return dismiss_bug_report if params[:bug_report].blank?
+
+      unless @bug_report.open?
+        redirect_to edit_bug_report_path(@bug_report), alert: t("bug_reports_client.flashes.only_open_editable", type_noun: @bug_report.type_noun)
+        return
+      end
+
+      # The report type is locked once submitted - the remote issue and its
+      # labels are already filed as that type.
+      @bug_report.assign_attributes(bug_report_params.except(:report_type))
+      apply_default_severity(@bug_report)
+
+      # Attaching to a persisted record writes immediately (bypassing model
+      # validations), so the new files must be validated before anything is
+      # saved or purged.
+      new_screenshots = submitted_screenshots
+      unless validate_screenshots(@bug_report, new_screenshots)
+        render :edit, status: :unprocessable_entity
+        return
+      end
+
+      if @bug_report.save
+        # New uploads replace the existing set; editing without choosing any
+        # files leaves the current screenshots alone.
+        if new_screenshots.any?
+          @bug_report.screenshots.purge
+          @bug_report.screenshots.attach(new_screenshots)
+        end
+
+        if @bug_report.remote_bug_report_id.present?
+          ApiClient.new.update_bug_report(
+            @bug_report.remote_bug_report_id,
+            title: @bug_report.title,
+            description: DescriptionBuilder.new(@bug_report).build,
+            severity: @bug_report.severity,
+            report_type: @bug_report.report_type
+          )
+        end
+
+        redirect_to edit_bug_report_path(@bug_report), notice: t("bug_reports_client.flashes.updated", type_noun: @bug_report.type_noun.capitalize)
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def set_bug_report
+      @bug_report = BugReport.find(params[:id])
+    end
+
+    def authorize_bug_report_access!
+      unless @bug_report.user_id == bug_reports_current_user.id || bug_reports_admin?
+        head :forbidden
+      end
+    end
+
+    def require_admin!
+      unless bug_reports_admin?
+        redirect_to bug_reports_path, alert: t("bug_reports_client.flashes.not_permitted")
+      end
+    end
+
+    # Only the SELECTED type's schema field keys are permitted into
+    # responses, so a tampered form can't write arbitrary data or smuggle the
+    # other type's answers in. Screenshots are permitted (silencing
+    # unpermitted-parameter noise) but excluded from mass assignment -
+    # attachment is handled explicitly below.
+    def bug_report_params
+      report_type = @bug_report&.persisted? ? @bug_report.report_type : params.dig(:bug_report, :report_type)
+
+      params.require(:bug_report).permit(
+        :title, :severity, :report_type, :related_error_event_id,
+        screenshots: [],
+        responses: BugReportsClient.form_schema.field_keys_for(report_type)
+      ).except(:screenshots, :related_error_event_id)
+    end
+
+    # Captured 500s this user hit recently, offered on the form as "did your
+    # problem relate to this error?".
+    def recent_error_events
+      ErrorEvent.where(user: bug_reports_current_user).since(24.hours.ago).recent_first.limit(5)
+    end
+
+    # If the reporter linked one of their captured errors, thread its details
+    # into the report (rendered into the GitHub issue by DescriptionBuilder,
+    # where the fingerprint cross-references the auto-filed error issue).
+    # Scoped to the current user so ids can't be guessed across accounts.
+    def link_related_error(report)
+      event_id = params.dig(:bug_report, :related_error_event_id)
+      return if event_id.blank?
+
+      event = ErrorEvent.where(user: bug_reports_current_user).find_by(id: event_id)
+      return unless event
+
+      # Full technical detail for the issue - the user only ever saw the
+      # human description.
+      details = [ event.summary ]
+      details << "while #{event.activity}" if event.activity.present?
+      report.responses = {
+        "related_error" => "#{details.join(' - ')} (fingerprint `#{event.fingerprint}`, at #{event.occurred_at.iso8601})"
+      }
+    end
+
+    # The submitted screenshot files, minus the blank entry a multiple file
+    # input always includes. An edit without new uploads therefore submits
+    # no files and existing screenshots are left untouched.
+    def submitted_screenshots
+      return [] unless BugReportsClient.config.screenshots_enabled
+
+      Array(params.dig(:bug_report, :screenshots)).reject(&:blank?)
+    end
+
+    # Consumer-facing hosts hide the severity picker; the API still requires
+    # a severity for bugs, so fill in the configured default.
+    def apply_default_severity(report)
+      return if BugReportsClient.config.ask_severity
+      report.severity = BugReportsClient.config.default_severity if report.bug?
+    end
+
+    def attach_screenshots(report)
+      files = submitted_screenshots
+      report.screenshots.attach(files) if files.any?
+    end
+
+    # Server-side screenshot validation, run before any attach: count within
+    # the limit, size within bounds, and the content type sniffed from the
+    # file bytes (Marcel) rather than trusting the client-declared type.
+    # Adds errors to the record and returns false when anything fails.
+    def validate_screenshots(report, files)
+      config = BugReportsClient.config
+      messages = []
+
+      if files.size > config.max_screenshots
+        messages << t("bug_reports_client.errors.too_many_screenshots", max: config.max_screenshots)
+      end
+
+      files.each do |file|
+        detected_type = Marcel::MimeType.for(file.tempfile, name: file.original_filename, declared_type: file.content_type)
+        unless config.screenshot_content_types.include?(detected_type)
+          messages << t("bug_reports_client.errors.screenshot_type", filename: file.original_filename)
+        end
+        if file.size > config.max_screenshot_size
+          messages << t("bug_reports_client.errors.screenshot_size", filename: file.original_filename, max_mb: config.max_screenshot_size / (1024 * 1024))
+        end
+      end
+
+      return true if messages.empty?
+
+      report.validate
+      messages.each { |message| report.errors.add(:base, message) }
+      false
+    end
+
+    # Minimal offset/limit pagination - deliberately no pagy/kaminari
+    # dependency. Sets @page/@total_pages for the shared pagination partial.
+    def paginate(scope)
+      @page = [ params[:page].to_i, 1 ].max
+      @total_pages = [ (scope.count / PER_PAGE.to_f).ceil, 1 ].max
+      @page = @total_pages if @page > @total_pages
+      scope.offset((@page - 1) * PER_PAGE).limit(PER_PAGE)
+    end
+
+    # Applies the active status and type filters to a bug reports relation.
+    def filtered(scope)
+      scope = scope.where(status: params[:status]) if params[:status].present?
+      scope = scope.where(report_type: params[:report_type]) if params[:report_type].present?
+      scope
+    end
+
+    # Status counts within the currently-selected type, so the tabs stay in
+    # sync with the type filter (and vice versa for type_counts).
+    def status_counts(scope)
+      scope = scope.where(report_type: params[:report_type]) if params[:report_type].present?
+      { all: scope.count, open: scope.open.count, closed: scope.closed.count }
+    end
+
+    def type_counts(scope)
+      scope = scope.where(status: params[:status]) if params[:status].present?
+      { all: scope.count, bug: scope.bug.count, feature: scope.feature.count }
+    end
+
+    # Dismisses a resolved-report alert. Removes the alert elements via Turbo
+    # Streams and renders the overridable _after_dismiss hook so hosts can
+    # update their own UI (e.g. a notification badge) in the same response.
+    def dismiss_bug_report
+      # Column write, not update!: dismissing must work even for reports that
+      # would no longer pass validation (e.g. after a form-schema change).
+      @bug_report.update_columns(dismissed_at: Time.current, updated_at: Time.current)
+
+      @remaining = BugReport.where(user: bug_reports_current_user).resolved_and_undismissed
+
+      respond_to do |format|
+        format.turbo_stream do
+          streams = [ turbo_stream.remove("bug_report_#{@bug_report.id}") ]
+          streams << turbo_stream.remove("bug_report_alerts") if @remaining.empty?
+          streams << render_to_string(partial: "bug_reports_client/shared/after_dismiss", formats: [ :turbo_stream ])
+
+          render turbo_stream: streams
+        end
+        format.html do
+          redirect_to fallback_root_path, notice: t("bug_reports_client.flashes.dismissed", type_noun: @bug_report.type_noun.capitalize)
+        end
+      end
+    end
+
+    # Host root if one exists, otherwise the engine's own index.
+    def fallback_root_path
+      main_app.respond_to?(:root_path) ? main_app.root_path : bug_reports_path
+    end
+  end
+end