perchfall-rails 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 66ca38a327877a7cbae38ccda37e0c621fd3bb6b1aa2076c4d36fcf6fa849ab4
+  data.tar.gz: daad94c0e0867f968b13bcf6b54b6e850df851b61f884a0c74cfe70524ea3cf2
+SHA512:
+  metadata.gz: 5285413f55fd9d32c236e17b13c0d54904cebb9f3e7ce4bb0eefcbc1fcc11845c868004b5289a71bf92e33bea0a435e8cad8525baa626070807215e97508497f
+  data.tar.gz: 268ac26f7a97ad1d1c081a27d87bbec73762a5685f1b16797fd0278c3261707f5df323ae5cede4517ed655b7866c2e0e85b70d6ec908c87e00e3f57a6e83c250

data/.nvmrc

@@ -0,0 +1 @@
+22

data/.ruby-version

@@ -0,0 +1 @@
+4.0.2

data/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-05-05
+
+### Added
+
+- `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1) and `CONTRIBUTING.md`.
+- README badges (CI, Gem Version, License) and a "Why perchfall-rails" section.
+- Gemspec metadata: `bug_tracker_uri`, `rubygems_mfa_required`, and a `post_install_message` pointing at `bin/rails perchfall_rails:install:playwright`.
+
+### Changed
+
+- LICENSE copyright holder standardized to Flagrant LLC, matching the rest of the perchfall family.
+
+## [0.2.0] - 2026-05-05
+
+### Added
+
+- `RegexpSerializer` and `IgnoreRuleSerializer` — custom `ActiveJob::Serializers::ObjectSerializer` subclasses registered at engine boot via `config.to_prepare`. `RunJob` now supports `perform_later` with `ignore:`; callers no longer need to choose between async execution and ignore rules. `RegexpSerializer` applies to any job that passes a `Regexp` argument. See [ADR 0002](docs/adr/0002-ignore-rule-serializer.md).
+
+## [0.1.0] - 2026-05-04
+
+### Added
+
+- Mountable Rails engine under the `Perchfall::Rails` namespace. Mount at any path with `mount Perchfall::Rails::Engine, at: "/perchfall"`.
+- `SyntheticRun` ActiveRecord model persisting every check result with status (`ok`, `failed`, or `error`), HTTP status, duration, denormalized error counts, and the full raw report as JSON.
+- `RunJob` ActiveJob subclass that runs a Perchfall check and persists the result. Supports `url:`, `scenario_name:`, and `ignore:` (via `perform_now` only — `IgnoreRule` objects are not ActiveJob-serializable). Failed runs persist an error record and re-raise so the queue adapter can retry.
+- Dashboard with a paginated, filterable index (filter by status or URL) and a detail view showing network and console errors.
+- Configuration API via `Perchfall::Rails.configure`: `base_controller` (default: `"ApplicationController"`) and `queue_name` (default: `:synthetic`).
+- Production boot warning when `base_controller` is still `ApplicationController`.
+- `rails generate perchfall:rails:install` generator that creates `config/initializers/perchfall_rails.rb` and prints setup instructions.
+- `perchfall_rails:install:playwright` Rake task to install the Playwright npm package and Chromium browser binary.
+- `perchfall_rails:check` Rake task to verify Node, the Playwright package, and the Chromium binary are all present and usable.
+- Tailwind CSS integration: semantic token names (`primary`, `muted`, `subtle`, `error`, `border-subtle`, `neutral-0/150/900`) in all views. Tailwind v4 hosts import `perchfall_rails/engine` to scan the engine's views automatically; Tailwind v3 hosts add the engine view path to their `content` configuration.
+- Runtime dependencies: `perchfall ~> 0.4`, `pagy ~> 43.0`, Rails `>= 8.0`.
+
+[Unreleased]: https://github.com/beflagrant/perchfall-rails/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/beflagrant/perchfall-rails/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/beflagrant/perchfall-rails/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/beflagrant/perchfall-rails/releases/tag/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening a GitHub issue. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to perchfall-rails
+
+Thank you for your interest in contributing. All skill levels are welcome — whether this is your first open source contribution or your hundredth.
+
+## Before you start
+
+**Open an issue first.** Before writing any code, please open a GitHub issue describing what you want to do and why. This saves everyone time: it avoids duplicate work, surfaces design concerns early, and gives us a chance to agree on scope before you invest effort in an implementation.
+
+The exception is typos and documentation fixes, which can go straight to a PR.
+
+## Proposing a significant change
+
+For anything that changes behavior, adds a new concept, or touches security — please propose it as a GitHub Discussion before opening an issue or PR. Structure your proposal like an ADR:
+
+- **Context** — what problem are you solving, and why does it matter?
+- **Options considered** — what alternatives did you weigh?
+- **Decision** — what are you proposing, and why?
+- **Consequences** — what does this make easier or harder?
+
+You can look at the existing ADRs in [docs/adr/](docs/adr/) for examples of this format. Discussion lets the proposal get feedback before any code is written, and the thread becomes useful context for the eventual PR.
+
+## Submitting a pull request
+
+- Tests are required. If you're adding behavior, cover it. If you're fixing a bug, add a test that would have caught it.
+- Rubocop must pass. Run `bundle exec rubocop` before pushing.
+- Keep commits focused. One logical change per commit is easier to review and revert if needed.
+- Update the CHANGELOG under `[Unreleased]` following the existing format.
+
+## Running the suite
+
+```sh
+bin/setup
+bundle exec rake          # runs the test suite and rubocop
+```
+
+The test suite uses a dummy Rails app under `test/dummy` and does not require Node, Playwright, or a browser.
+
+## Code of conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold it.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flagrant LLC
+
+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,228 @@
+# perchfall-rails
+
+[![CI](https://github.com/beflagrant/perchfall-rails/actions/workflows/ci.yml/badge.svg)](https://github.com/beflagrant/perchfall-rails/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/perchfall-rails.svg)](https://badge.fury.io/rb/perchfall-rails)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A mountable Rails engine that adds a synthetic monitoring dashboard and background job pipeline to any Rails application, powered by the [perchfall](https://github.com/beflagrant/perchfall) gem.
+
+## Why perchfall-rails
+
+[perchfall](https://github.com/beflagrant/perchfall) gives you a `Report` value object — what a real Chromium browser saw at a URL. It deliberately doesn't impose a database schema or a job queue; you bring your own.
+
+perchfall-rails is the batteries-included path for Rails apps:
+
+- **Schema and persistence** — a `SyntheticRun` ActiveRecord model that stores every check, with denormalized error counts and the full report JSON for later inspection.
+- **Background job** — a `Perchfall::Rails::RunJob` ActiveJob subclass you can `perform_later` (including with `ignore:` rules), with sensible retry behavior.
+- **Dashboard** — paginated, filterable index of runs and a detail view that surfaces every network and console error.
+- **Auth-agnostic** — point `base_controller` at any controller in your app and inherit its authentication.
+
+If you only need the Ruby API, use perchfall directly. If you want a Rails-idiomatic place for synthetic results to live, mount this.
+
+## Requirements
+
+- Ruby >= 3.3
+- Rails >= 8.0
+- Node.js >= 18 (required by perchfall for Playwright)
+- [pagy](https://github.com/ddnexus/pagy) ~> 43.0 (bundled as a dependency — no separate install needed)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "perchfall-rails"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+### Node.js and Playwright
+
+The engine requires Node.js and the Playwright npm package with a Chromium browser binary. After bundling:
+
+```sh
+bin/rails perchfall_rails:install:playwright
+```
+
+This runs `npm install playwright` and `npx playwright install chromium`. Verify the full environment with:
+
+```sh
+bin/rails perchfall_rails:check
+```
+
+### Initializer
+
+Generate the configuration initializer:
+
+```sh
+bin/rails generate perchfall:rails:install
+```
+
+This creates `config/initializers/perchfall_rails.rb` and prints the remaining setup steps.
+
+### Migrations
+
+Install and run the engine migrations:
+
+```sh
+bin/rails perchfall_rails:install:migrations
+bin/rails db:migrate
+```
+
+### Routes
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+mount Perchfall::Rails::Engine, at: "/perchfall"
+```
+
+The dashboard will be available at `/perchfall/synthetic_runs`.
+
+## Configuration
+
+Create an initializer at `config/initializers/perchfall_rails.rb`:
+
+```ruby
+Perchfall::Rails.configure do |config|
+  # Required in production: set this to a controller that enforces authentication.
+  # The engine will log a warning at boot if this is still ApplicationController
+  # in a production environment.
+  config.base_controller = "AuthenticatedController"
+
+  # ActiveJob queue name for synthetic run jobs. Defaults to :synthetic.
+  config.queue_name = :synthetic
+end
+```
+
+## Authentication
+
+The engine has no built-in authentication. Set `base_controller` to a controller that enforces whatever authentication your application uses:
+
+```ruby
+# config/initializers/perchfall_rails.rb
+Perchfall::Rails.configure do |config|
+  config.base_controller = "Admin::BaseController"
+end
+```
+
+`base_controller` must inherit from `ActionController::Base`. The engine views use `csrf_meta_tags`, `csp_meta_tag`, and `stylesheet_link_tag`, none of which are available on `ActionController::API` controllers.
+
+## Enqueueing checks
+
+Enqueue a synthetic run from anywhere in your application:
+
+```ruby
+Perchfall::Rails::RunJob.perform_later(url: "https://example.com")
+```
+
+To suppress known-noisy errors, pass `ignore:` rules:
+
+```ruby
+rule = Perchfall::IgnoreRule.new(
+  pattern: "chrome-error://",
+  type:    "*",
+  target:  :console
+)
+Perchfall::Rails::RunJob.perform_later(
+  url:           "https://example.com",
+  scenario_name: "homepage",
+  ignore:        [rule]
+)
+```
+
+**Retry behavior:** When a run fails with a `Perchfall::Errors::Error`, the job persists an error record and then re-raises the exception so the queue adapter can retry normally. Each retry attempt that also fails will create an additional error record. If you want to cap error records at one per enqueued job, configure `discard_on` in a subclass or use your queue adapter's retry settings:
+
+```ruby
+class MyRunJob < Perchfall::Rails::RunJob
+  discard_on Perchfall::Errors::Error
+end
+```
+
+## Tailwind CSS
+
+The engine views use semantic Tailwind token names. Add the following to your Tailwind configuration to define the required tokens:
+
+**Tailwind v4**:
+
+`tailwindcss-rails` automatically generates a bridge file at `app/assets/builds/tailwind/perchfall_rails.css` when the engine is bundled. Import it from your Tailwind CSS entry point, then define the required tokens. Replace the example values with your application's actual colors:
+
+```css
+@import "tailwindcss";
+@import "../builds/tailwind/perchfall_rails";
+
+@theme {
+  --color-primary: #2563eb;
+  --color-muted: #6b7280;
+  --color-subtle: #9ca3af;
+  --color-error: #ef4444;
+  --color-border-subtle: #e5e7eb;
+
+  --color-neutral-0: #ffffff;
+  --color-neutral-150: #e5e7eb;
+  --color-neutral-900: #111827;
+}
+```
+
+The `../builds/tailwind/perchfall_rails` path assumes your CSS entry point is in `app/assets/tailwind/` or `app/assets/stylesheets/`. Adjust if your layout differs.
+
+**Tailwind v3** (`tailwind.config.js`):
+
+Add the engine's views to your content paths and define the required tokens. Replace the example values with your application's actual colors:
+
+```js
+const { execSync } = require("child_process");
+const enginePath = execSync("bundle show perchfall-rails").toString().trim();
+
+module.exports = {
+  content: [
+    // ... your existing content paths
+    `${enginePath}/app/views/**/*.html.erb`,
+  ],
+  theme: {
+    extend: {
+      colors: {
+        primary: "#2563eb",
+        muted: "#6b7280",
+        subtle: "#9ca3af",
+        error: "#ef4444",
+        neutral: {
+          0: "#ffffff",
+          150: "#e5e7eb",
+          900: "#111827",
+        },
+      },
+      borderColor: {
+        subtle: "#e5e7eb",
+      },
+    },
+  },
+}
+```
+
+If your application does not use Tailwind, the views render unstyled but functional.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run `rake test` to run the tests.
+
+```sh
+bin/setup
+bundle exec rake test
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/beflagrant/perchfall-rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/beflagrant/perchfall-rails/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the perchfall-rails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/beflagrant/perchfall-rails/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

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

@@ -0,0 +1 @@
+@source "../../../views/**/*.html.erb";

data/app/controllers/perchfall/rails/synthetic_runs_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Rails
+    class SyntheticRunsController < Perchfall::Rails.configuration.base_controller.constantize
+      include ::Pagy::Method
+
+      def index
+        runs = SyntheticRun.recent
+        runs = runs.for_status(params[:status]) if SyntheticRun::STATUSES.include?(params[:status])
+        runs = runs.for_url(params[:url])       if params[:url].present?
+        @pagy, @runs = pagy(:offset, runs)
+      end
+
+      def show
+        @run = SyntheticRun.find(params[:id])
+      rescue ActiveRecord::RecordNotFound
+        head :not_found
+      end
+    end
+  end
+end

data/app/jobs/perchfall/rails/run_job.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Rails
+    class RunJob < ActiveJob::Base
+      queue_as { Perchfall::Rails.configuration.queue_name }
+
+      # NOTE: ignore: cannot be used with perform_later — IgnoreRule objects are not
+      # ActiveJob-serializable. Use perform_now when passing ignore rules.
+      def perform(url:, scenario_name: nil, ignore: [], client: nil)
+        client ||= Perchfall::Client.new
+        report = client.run(url: url, scenario_name: scenario_name, ignore: ignore)
+        SyntheticRun::Persist.call(report, url: url, scenario_name: scenario_name)
+      rescue Perchfall::Errors::PageLoadError => e
+        SyntheticRun.create!(
+          url: url,
+          scenario_name: scenario_name,
+          status: "error",
+          raw_report: e.report.to_h
+        )
+        raise
+      rescue Perchfall::Errors::Error => e
+        SyntheticRun.create!(
+          url: url,
+          scenario_name: scenario_name,
+          status: "error",
+          raw_report: { "error" => e.message }
+        )
+        raise
+      end
+    end
+  end
+end

data/app/models/perchfall/rails/synthetic_run.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Rails
+    class SyntheticRun < ActiveRecord::Base
+      self.table_name = "synthetic_runs"
+
+      STATUSES = %w[ok failed error].freeze
+
+      validates :url,    presence: true
+      validates :status, presence: true, inclusion: { in: STATUSES }
+
+      scope :recent,     -> { order(created_at: :desc) }
+      scope :failures,   -> { where(status: %w[failed error]) }
+      scope :for_url,    ->(url)    { where(url: url) }
+      scope :for_status, ->(status) { where(status: status) }
+
+      def ok?     = status == "ok"
+      def failed? = !ok?
+
+      def network_errors         = raw_report["network_errors"] || []
+      def console_errors         = raw_report["console_errors"] || []
+      def ignored_network_errors = raw_report["ignored_network_errors"] || []
+      def ignored_console_errors = raw_report["ignored_console_errors"] || []
+    end
+  end
+end

data/app/serializers/perchfall/rails/ignore_rule_serializer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Rails
+    class IgnoreRuleSerializer < ActiveJob::Serializers::ObjectSerializer
+      def klass
+        Perchfall::IgnoreRule
+      end
+
+      def serialize(rule)
+        super(
+          "pattern" => ActiveJob::Arguments.serialize_argument(rule.pattern),
+          "type" => ActiveJob::Arguments.serialize_argument(rule.type),
+          "target" => ActiveJob::Arguments.serialize_argument(rule.target)
+        )
+      end
+
+      def deserialize(hash)
+        Perchfall::IgnoreRule.new(
+          pattern: ActiveJob::Arguments.deserialize([hash["pattern"]]).first,
+          type: ActiveJob::Arguments.deserialize([hash["type"]]).first,
+          target: ActiveJob::Arguments.deserialize([hash["target"]]).first
+        )
+      end
+    end
+  end
+end

data/app/serializers/perchfall/rails/regexp_serializer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Rails
+    class RegexpSerializer < ActiveJob::Serializers::ObjectSerializer
+      def klass
+        Regexp
+      end
+
+      def serialize(regexp)
+        super("source" => regexp.source, "options" => regexp.options)
+      end
+
+      def deserialize(hash)
+        Regexp.new(hash["source"], hash["options"])
+      end
+    end
+  end
+end

data/app/services/perchfall/rails/synthetic_run/persist.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Rails
+    class SyntheticRun
+      class Persist
+        def self.call(report, url:, scenario_name: nil)
+          new(report, url: url, scenario_name: scenario_name).call
+        end
+
+        def initialize(report, url:, scenario_name:)
+          @report        = report
+          @url           = url
+          @scenario_name = scenario_name
+        end
+
+        def call
+          SyntheticRun.create!(
+            url: @url,
+            scenario_name: @scenario_name,
+            status: map_status,
+            http_status: @report.http_status,
+            duration_ms: @report.duration_ms,
+            network_error_count: @report.network_errors.size,
+            console_error_count: @report.console_errors.size,
+            raw_report: @report.to_h
+          )
+        end
+
+        private
+
+        def map_status
+          return "error"  if @report.status == "error"
+          return "failed" if @report.network_errors.any? || @report.console_errors.any?
+
+          "ok"
+        end
+      end
+    end
+  end
+end

data/app/views/layouts/perchfall/rails/application.html.erb

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Perchfall</title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <%= stylesheet_link_tag :app %>
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/app/views/perchfall/rails/synthetic_runs/_console_error_card.html.erb

@@ -0,0 +1,14 @@
+<div class="p-8 border border-solid border-neutral-150 rounded-2xl bg-neutral-0 flex flex-col gap-4">
+  <h3 class="text-3xl font-extrabold leading-[120%] <%= heading_color %>">
+    <%= title %> <span class="text-2xl font-semibold <%= count_color %>">(<%= count %>)</span>
+  </h3>
+  <% errors.each_with_index do |err, i| %>
+    <div class="flex flex-col gap-1 <%= 'opacity-60' if dimmed %>">
+      <span class="text-xl font-normal text-neutral-900 break-all"><%= err["text"] %></span>
+      <span class="text-sm font-normal text-muted"><%= err["type"] %> &mdash; <%= err["location"] %></span>
+    </div>
+    <% unless i == errors.size - 1 %>
+      <hr class="border-subtle">
+    <% end %>
+  <% end %>
+</div>

data/app/views/perchfall/rails/synthetic_runs/_network_error_card.html.erb

@@ -0,0 +1,14 @@
+<div class="p-8 border border-solid border-neutral-150 rounded-2xl bg-neutral-0 flex flex-col gap-4">
+  <h3 class="text-3xl font-extrabold leading-[120%] <%= heading_color %>">
+    <%= title %> <span class="text-2xl font-semibold <%= count_color %>">(<%= count %>)</span>
+  </h3>
+  <% errors.each_with_index do |err, i| %>
+    <div class="flex flex-col gap-1 <%= 'opacity-60' if dimmed %>">
+      <span class="text-xl font-normal text-neutral-900 break-all"><%= err["url"] %></span>
+      <span class="text-sm font-normal text-muted"><%= err["method"] %> &mdash; <%= err["failure"] %></span>
+    </div>
+    <% unless i == errors.size - 1 %>
+      <hr class="border-subtle">
+    <% end %>
+  <% end %>
+</div>

data/app/views/perchfall/rails/synthetic_runs/index.html.erb

@@ -0,0 +1,63 @@
+<div class="flex flex-col gap-6 w-full">
+  <div class="flex flex-col md:flex-row items-start md:items-center self-stretch justify-between gap-4">
+    <h2 class="text-5xl font-extrabold leading-[120%] text-primary">Synthetic Runs</h2>
+
+    <%= form_with url: synthetic_runs_path, method: :get, class: "flex flex-row gap-3 items-center" do |f| %>
+      <%= f.select :status,
+            Perchfall::Rails::SyntheticRun::STATUSES.map { |status| [status.capitalize, status] },
+            { include_blank: "All statuses", selected: params[:status] },
+            class: "text-sm font-medium text-muted border border-neutral-150 rounded-lg px-3 py-2 bg-neutral-0" %>
+      <%= f.text_field :url,
+            placeholder: "Filter by URL",
+            value: params[:url],
+            class: "text-sm text-neutral-900 border border-neutral-150 rounded-lg px-3 py-2 bg-neutral-0 w-64" %>
+      <%= f.submit "Filter",
+            class: "text-sm font-semibold text-primary border border-neutral-150 rounded-lg px-4 py-2 bg-neutral-0 cursor-pointer" %>
+    <% end %>
+  </div>
+
+  <div class="p-8 border border-solid border-neutral-150 rounded-2xl bg-neutral-0 flex flex-col gap-6">
+    <div class="grid grid-cols-[2fr_1fr_1fr_1fr_1fr_1fr] gap-4 items-center">
+      <span class="text-lg font-semibold leading-[140%] text-muted">URL / Scenario</span>
+      <span class="text-lg font-semibold leading-[140%] text-muted">Status</span>
+      <span class="text-lg font-semibold leading-[140%] text-muted text-right">HTTP</span>
+      <span class="text-lg font-semibold leading-[140%] text-muted text-right">Duration</span>
+      <span class="text-lg font-semibold leading-[140%] text-muted text-right">Net errs</span>
+      <span class="text-lg font-semibold leading-[140%] text-muted text-right">When</span>
+    </div>
+
+    <hr class="border-subtle">
+
+    <% if @runs.none? %>
+      <p class="text-xl font-normal text-muted">No runs found.</p>
+    <% end %>
+
+    <% @runs.each_with_index do |run, i| %>
+      <div class="grid grid-cols-[2fr_1fr_1fr_1fr_1fr_1fr] gap-4 items-center">
+        <div class="flex flex-col gap-0.5">
+          <%= link_to synthetic_run_path(run), class: "text-xl font-normal leading-[140%] text-primary underline truncate" do %>
+            <%= run.scenario_name || run.url %>
+          <% end %>
+          <% if run.scenario_name.present? %>
+            <span class="text-sm font-normal text-muted"><%= run.url %></span>
+          <% end %>
+        </div>
+
+        <span class="<%= run.ok? ? 'text-primary' : 'text-error' %> text-xl font-semibold leading-[140%]">
+          <%= run.status.capitalize %>
+        </span>
+
+        <span class="text-xl font-normal leading-[140%] text-neutral-900 text-right"><%= run.http_status || "—" %></span>
+        <span class="text-xl font-normal leading-[140%] text-neutral-900 text-right"><%= run.duration_ms ? "#{run.duration_ms}ms" : "—" %></span>
+        <span class="text-xl font-normal leading-[140%] text-neutral-900 text-right"><%= run.network_error_count %></span>
+        <span class="text-xl font-normal leading-[140%] text-muted text-right"><%= time_ago_in_words(run.created_at) %> ago</span>
+      </div>
+
+      <% unless i == @runs.size - 1 %>
+        <hr class="border-subtle">
+      <% end %>
+    <% end %>
+  </div>
+
+  <%== @pagy.series_nav %>
+</div>

data/app/views/perchfall/rails/synthetic_runs/show.html.erb

@@ -0,0 +1,104 @@
+<div class="flex flex-col gap-6 w-full">
+  <div class="flex flex-row items-center gap-4">
+    <%= link_to synthetic_runs_path, class: "text-muted hover:text-primary text-lg w-full" do %>
+      &larr; All runs
+    <% end %>
+  </div>
+  <div class="flex flex-row items-center gap-4">
+    <h2 class="text-5xl font-extrabold leading-[120%] text-primary w-full">
+      <%= @run.scenario_name.presence || @run.url %>
+    </h2>
+  </div>
+
+  <div class="flex flex-col md:flex-row gap-4 self-stretch items-start">
+    <%# Summary card %>
+    <div class="p-8 border border-solid border-neutral-150 rounded-2xl bg-neutral-0 flex flex-col gap-6 flex-1">
+      <h3 class="text-3xl font-extrabold leading-[120%] text-primary">Summary</h3>
+
+      <dl class="flex flex-col gap-4">
+        <div class="grid grid-cols-2 gap-4">
+          <dt class="text-lg font-semibold text-muted">Status</dt>
+          <dd class="text-xl font-semibold <%= @run.ok? ? 'text-primary' : 'text-error' %>">
+            <%= @run.status.capitalize %>
+          </dd>
+        </div>
+        <hr class="border-subtle">
+        <div class="grid grid-cols-2 gap-4">
+          <dt class="text-lg font-semibold text-muted">Scenario</dt>
+          <dd class="text-xl font-normal text-neutral-900 break-all"><%= @run.scenario_name %></dd>
+        </div>
+        <hr class="border-subtle">
+        <% if @run.scenario_name.present? %>
+          <div class="grid grid-cols-2 gap-4">
+            <dt class="text-lg font-semibold text-muted">URL</dt>
+            <dd class="text-xl font-normal text-neutral-900"><%= @run.url %></dd>
+          </div>
+          <hr class="border-subtle">
+        <% end %>
+        <div class="grid grid-cols-2 gap-4">
+          <dt class="text-lg font-semibold text-muted">HTTP status</dt>
+          <dd class="text-xl font-normal text-neutral-900"><%= @run.http_status || "—" %></dd>
+        </div>
+        <hr class="border-subtle">
+        <div class="grid grid-cols-2 gap-4">
+          <dt class="text-lg font-semibold text-muted">Duration</dt>
+          <dd class="text-xl font-normal text-neutral-900"><%= @run.duration_ms ? "#{@run.duration_ms}ms" : "—" %></dd>
+        </div>
+        <hr class="border-subtle">
+        <div class="grid grid-cols-2 gap-4">
+          <dt class="text-lg font-semibold text-muted">Run at</dt>
+          <dd class="text-xl font-normal text-neutral-900"><%= @run.created_at.strftime("%b %-d, %Y at %H:%M UTC") %></dd>
+        </div>
+      </dl>
+    </div>
+
+    <div class="flex flex-col gap-4 flex-1">
+      <% if @run.network_errors.any? %>
+        <%= render "network_error_card",
+              errors:        @run.network_errors,
+              title:         "Network Errors",
+              count:         @run.network_error_count,
+              heading_color: "text-primary",
+              count_color:   "text-error",
+              dimmed:        false %>
+      <% end %>
+
+      <% if @run.console_errors.any? %>
+        <%= render "console_error_card",
+              errors:        @run.console_errors,
+              title:         "Console Errors",
+              count:         @run.console_error_count,
+              heading_color: "text-primary",
+              count_color:   "text-error",
+              dimmed:        false %>
+      <% end %>
+
+      <% if @run.network_errors.none? && @run.console_errors.none? %>
+        <div class="p-8 border border-solid border-neutral-150 rounded-2xl bg-neutral-0 flex flex-col gap-2">
+          <h3 class="text-3xl font-extrabold leading-[120%] text-primary">No errors</h3>
+          <p class="text-xl font-normal text-muted">This run completed cleanly.</p>
+        </div>
+      <% end %>
+
+      <% if @run.ignored_network_errors.any? %>
+        <%= render "network_error_card",
+              errors:        @run.ignored_network_errors,
+              title:         "Ignored Network Errors",
+              count:         @run.ignored_network_errors.size,
+              heading_color: "text-muted",
+              count_color:   "text-subtle",
+              dimmed:        true %>
+      <% end %>
+
+      <% if @run.ignored_console_errors.any? %>
+        <%= render "console_error_card",
+              errors:        @run.ignored_console_errors,
+              title:         "Ignored Console Errors",
+              count:         @run.ignored_console_errors.size,
+              heading_color: "text-muted",
+              count_color:   "text-subtle",
+              dimmed:        true %>
+      <% end %>
+    </div>
+  </div>
+</div>

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Perchfall::Rails::Engine.routes.draw do
+  resources :synthetic_runs, only: %i[index show]
+end

data/db/migrate/20260315235045_create_synthetic_runs.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateSyntheticRuns < ActiveRecord::Migration[8.0]
+  def change
+    create_table :synthetic_runs do |t|
+      t.string  :url, null: false
+      t.string  :scenario_name
+      t.string  :status, null: false
+      t.integer :http_status
+      t.integer :duration_ms
+      t.integer :network_error_count,  null: false, default: 0
+      t.integer :console_error_count,  null: false, default: 0
+      t.json    :raw_report,           null: false, default: {}
+      t.timestamps
+    end
+
+    add_index :synthetic_runs, :status
+    add_index :synthetic_runs, %i[url created_at]
+  end
+end

data/lib/generators/perchfall/rails/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Rails
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/perchfall_rails.rb"
+      end
+
+      def show_instructions
+        say ""
+        say "Next steps:", :green
+        say "  1. Mount the engine in config/routes.rb:"
+        say '       mount Perchfall::Rails::Engine, at: "/perchfall"'
+        say "  2. Install and run the engine migrations:"
+        say "       bin/rails perchfall_rails:install:migrations"
+        say "       bin/rails db:migrate"
+        say "  3. Install Node.js dependencies:"
+        say "       bin/rails perchfall_rails:install:playwright"
+        say "  4. Set base_controller in the generated initializer before deploying to production."
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/perchfall/rails/templates/initializer.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+Perchfall::Rails.configure do |config|
+  # Set this to a controller that enforces authentication before deploying to production.
+  # Must inherit from ActionController::Base (not ActionController::API).
+  # The engine logs a warning at boot if this is still ApplicationController in production.
+  config.base_controller = "ApplicationController"
+
+  # ActiveJob queue name for synthetic run jobs. Defaults to :synthetic.
+  # config.queue_name = :synthetic
+end

data/lib/perchfall/rails/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Rails
+    class Configuration
+      attr_accessor :base_controller, :queue_name
+
+      def initialize
+        @base_controller = "ApplicationController"
+        @queue_name = :synthetic
+      end
+    end
+
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    def self.configure
+      yield configuration
+    end
+  end
+end

data/lib/perchfall/rails/engine.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace Perchfall::Rails
+
+      config.after_initialize do
+        if ::Rails.env.production? &&
+           Perchfall::Rails.configuration.base_controller == "ApplicationController"
+          ::Rails.logger.warn(
+            "[perchfall-rails] base_controller is still ApplicationController. " \
+            "The synthetic runs dashboard is publicly accessible. " \
+            "Set config.base_controller to a controller that enforces authentication."
+          )
+        end
+      end
+
+      config.to_prepare do
+        ActiveJob::Serializers.add_serializers(
+          Perchfall::Rails::RegexpSerializer,
+          Perchfall::Rails::IgnoreRuleSerializer
+        )
+      end
+
+      initializer "perchfall.node_path" do
+        local_node_modules = ::Rails.root.join("node_modules").to_s
+        existing = ENV["NODE_PATH"].to_s
+        ENV["NODE_PATH"] = [local_node_modules, existing].reject(&:empty?).join(":")
+      end
+    end
+  end
+end

data/lib/perchfall/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Rails
+    VERSION = "0.2.1"
+  end
+end

data/lib/perchfall/rails.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "pagy"
+require "perchfall"
+require_relative "rails/version"
+require_relative "rails/configuration"
+require_relative "rails/engine"
+
+module Perchfall
+  module Rails
+  end
+end

data/lib/tasks/perchfall/rails.rake

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+namespace :perchfall_rails do
+  namespace :install do
+    desc "Install Node.js dependencies required by Perchfall (playwright npm package + Chromium)"
+    task :playwright do
+      system("npm install playwright") || abort("FAIL npm install playwright failed")
+      system("npx playwright install chromium") || abort("FAIL npx playwright install chromium failed")
+      puts "\nPlaywright and Chromium installed successfully."
+    end
+  end
+
+  desc "Check that Node and the playwright npm package are installed and usable"
+  task check: :environment do
+    # 1. Node
+    node_result = Perchfall::CommandRunner.new.call(["node", "--version"])
+    if node_result.success?
+      puts "node:       #{node_result.stdout.strip}"
+    else
+      abort "FAIL node not found or not executable"
+    end
+
+    # 2. playwright npm package resolvable from project node_modules
+    local_node_modules = Rails.root.join("node_modules").to_s
+    resolve_result = Perchfall::CommandRunner.new.call(
+      ["node", "-e", "require('playwright'); console.log(require('playwright/package.json').version)"]
+    )
+    if resolve_result.success?
+      puts "playwright: #{resolve_result.stdout.strip} (#{local_node_modules})"
+    else
+      warn resolve_result.stderr.strip
+      abort "FAIL playwright npm package not found — run: rails perchfall_rails:install:playwright"
+    end
+
+    # 3. Chromium browser binary present
+    chromium_result = Perchfall::CommandRunner.new.call(
+      ["node", "-e", <<~JS]
+        const { chromium } = require('playwright');
+        chromium.launch({ headless: true })
+          .then(b => { console.log('chromium ok'); b.close(); })
+          .catch(e => { process.stderr.write(e.message + '\\n'); process.exit(1); });
+      JS
+    )
+    if chromium_result.success?
+      puts "chromium:   #{chromium_result.stdout.strip}"
+    else
+      warn chromium_result.stderr.strip
+      abort "FAIL chromium browser not launchable — run: rails perchfall_rails:install:playwright"
+    end
+
+    puts "\nAll checks passed. Perchfall/Playwright is ready."
+  end
+end

data/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "playwright": "^1.58.2"
+  }
+}

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: perchfall-rails
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Yossef Mendelssohn
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pagy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '43.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '43.0'
+- !ruby/object:Gem::Dependency
+  name: perchfall
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Mountable Rails engine that provides a background job pipeline, ActiveRecord
+  model, controller, and views for running and reviewing Perchfall synthetic browser
+  checks.
+email:
+- ymendel@pobox.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".nvmrc"
+- ".ruby-version"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/tailwind/perchfall_rails/engine.css
+- app/controllers/perchfall/rails/synthetic_runs_controller.rb
+- app/jobs/perchfall/rails/run_job.rb
+- app/models/perchfall/rails/synthetic_run.rb
+- app/serializers/perchfall/rails/ignore_rule_serializer.rb
+- app/serializers/perchfall/rails/regexp_serializer.rb
+- app/services/perchfall/rails/synthetic_run/persist.rb
+- app/views/layouts/perchfall/rails/application.html.erb
+- app/views/perchfall/rails/synthetic_runs/_console_error_card.html.erb
+- app/views/perchfall/rails/synthetic_runs/_network_error_card.html.erb
+- app/views/perchfall/rails/synthetic_runs/index.html.erb
+- app/views/perchfall/rails/synthetic_runs/show.html.erb
+- config/routes.rb
+- db/migrate/20260315235045_create_synthetic_runs.rb
+- lib/generators/perchfall/rails/install_generator.rb
+- lib/generators/perchfall/rails/templates/initializer.rb
+- lib/perchfall/rails.rb
+- lib/perchfall/rails/configuration.rb
+- lib/perchfall/rails/engine.rb
+- lib/perchfall/rails/version.rb
+- lib/tasks/perchfall/rails.rake
+- package.json
+homepage: https://github.com/beflagrant/perchfall-rails
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/beflagrant/perchfall-rails
+  source_code_uri: https://github.com/beflagrant/perchfall-rails
+  changelog_uri: https://github.com/beflagrant/perchfall-rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/beflagrant/perchfall-rails/issues
+  rubygems_mfa_required: 'true'
+post_install_message: |
+  perchfall-rails is installed. To finish setup:
+
+    bin/rails generate perchfall:rails:install
+    bin/rails perchfall_rails:install:playwright
+    bin/rails perchfall_rails:install:migrations
+    bin/rails db:migrate
+
+  Then mount the engine in config/routes.rb:
+
+    mount Perchfall::Rails::Engine, at: "/perchfall"
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Rails engine for integrating Perchfall synthetic monitoring
+test_files: []