browser_review_gate 0.1.0

data/lib/browser_review_gate/saved_report.rb

@@ -0,0 +1,26 @@
+require "fileutils"
+require "json"
+
+module BrowserReviewGate
+  # Results of a browser run made before the PR exists, kept inside the git directory for one commit.
+  # They are published once a PR for that commit is opened.
+  class SavedReport
+    def initialize(sha:, shell: Shell.new)
+      @sha = sha
+      @shell = shell
+    end
+
+    def path
+      @path ||= @shell.call("git", "rev-parse", "--git-path", "browser-verification/#{@sha}.json").strip
+    end
+
+    def exist? = File.exist?(path)
+    def read = JSON.parse(File.read(path))
+    def delete = FileUtils.rm_f(path)
+
+    def write(data)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.pretty_generate(data))
+    end
+  end
+end

data/lib/browser_review_gate/shell.rb

@@ -0,0 +1,15 @@
+require "open3"
+
+module BrowserReviewGate
+  # Runs a command and returns its stdout; raises Error with stderr when it fails.
+  class Shell
+    def call(*argv, stdin_data: nil)
+      stdout, stderr, status = Open3.capture3(*argv, stdin_data: stdin_data)
+      return stdout if status.success?
+
+      raise Error, "#{argv.join(" ")} failed: #{stderr.strip}"
+    rescue Errno::ENOENT
+      raise Error, "#{argv.first} is not installed"
+    end
+  end
+end

data/lib/browser_review_gate/status.rb

@@ -0,0 +1,40 @@
+module BrowserReviewGate
+  # What an agent needs to know before a browser run: the decision for the PR head and the next step.
+  class Status
+    def initialize(github:, config: Config.new, shell: Shell.new)
+      @github = github
+      @config = config
+      @shell = shell
+    end
+
+    def to_h(number = nil)
+      local_sha = @shell.call("git", "rev-parse", "HEAD").strip
+      saved = SavedReport.new(sha: local_sha, shell: @shell).exist?
+      number ||= @github.pull_request_number_for_branch
+      return { "pull_request" => nil, "local_head" => local_sha, "saved_run" => saved, "next" => saved ? "open_pull_request" : "run_and_save", "app" => @config.app } unless number
+
+      pull_request = @github.pull_request(number)
+      comments = @github.comments(number)
+      head_sha = pull_request.fetch("head").fetch("sha")
+      assessment = Assessment.latest(comments)
+      assessment = nil unless assessment&.for?(head_sha)
+      verified = pull_request.fetch("labels").any? { |label| label["name"] == @config.label } && !Report.latest_passing(comments).nil?
+
+      { "pull_request" => number, "pr_head" => head_sha, "local_head" => local_sha,
+        "decision" => assessment&.decision, "reason" => assessment&.reason, "verified" => verified,
+        "saved_run" => saved, "next" => next_step(assessment, verified, saved, head_sha == local_sha),
+        "app" => @config.app }
+    end
+
+    private
+
+    def next_step(assessment, verified, saved, on_pr_head)
+      return "nothing" if verified || (assessment && !assessment.required?)
+      return "check_out_pr_head" unless on_pr_head
+      return "publish_saved" if saved
+      return "request_assessment" unless assessment
+
+      "run_and_publish"
+    end
+  end
+end

data/lib/browser_review_gate/templates/agents_block.md.erb

@@ -0,0 +1,5 @@
+<!-- browser_review_gate:start -->
+## Browser verification before human review
+
+A PR that changes browser-visible behavior needs a browser run before a human reviews it; CI takes back reviewer requests until one is published. When asked to run `<%= command %>` (with or without a PR number), or to verify a branch or PR in the browser, read `<%= playbook_path %>` and follow it exactly. Right after opening a PR with `gh pr create`, run `browser-review-gate publish` if `browser-review-gate status` says `publish_saved`.
+<!-- browser_review_gate:end -->

data/lib/browser_review_gate/templates/claude_skill.md.erb

@@ -0,0 +1,10 @@
+---
+name: browser-pr-verification
+description: Use when a branch or an open pull request needs browser verification before human review - before the PR is opened, or after the PR comment asks for it.
+argument-hint: "[PR number] [optional reviewer]"
+---
+<!-- browser_review_gate:managed <%= BrowserReviewGate::VERSION %> -->
+
+# Verify a PR in the browser
+
+Read `<%= playbook_path %>` and follow it exactly. The arguments are: `$ARGUMENTS` (a PR number, optionally followed by a reviewer login; empty means the current branch).

data/lib/browser_review_gate/templates/config.yml.erb

@@ -0,0 +1,24 @@
+# Settings for browser_review_gate. Every key is optional.
+
+# How an AI coding agent starts and reaches the app for a browser run.
+start_command:<%= start_command ? " #{start_command.inspect}" : "" %>
+url:<%= url ? " #{url.inspect}" : "" %>
+# How to sign in locally, e.g. "use the seed account from db/seeds.rb". No real credentials here.
+sign_in:
+
+# Workflow file name under .github/workflows, used to request an assessment by hand.
+workflow: <%= workflow %>
+
+# PRs that are never gated.
+skip_authors:
+  - "dependabot[bot]"
+  - "github-actions[bot]"
+skip_branch_prefixes: []
+
+# A PR that only touches these paths cannot change browser behavior; no model call is made.
+ignore_paths:
+  - "docs/**"
+  - "test/**"
+  - "spec/**"
+  - "**/*.md"
+  - ".github/**"

data/lib/browser_review_gate/templates/cursor_command.md.erb

@@ -0,0 +1,4 @@
+<!-- browser_review_gate:managed <%= BrowserReviewGate::VERSION %> -->
+# Verify a PR in the browser
+
+Read `<%= playbook_path %>` and follow it exactly. Whatever follows this command is the argument: a PR number, optionally followed by a reviewer login. No argument means the current branch.

data/lib/browser_review_gate/templates/playbook.md.erb

@@ -0,0 +1,48 @@
+<!-- browser_review_gate:managed <%= BrowserReviewGate::VERSION %> — re-run `browser-review-gate install` to update. -->
+# Browser verification before human review
+
+A pull request that changes what a person sees or does in a browser must be exercised in a browser before a human reviews it. CI decides whether a PR needs that and writes the decision in one "Browser verification" comment. Until a passing run is published, reviewer requests on such a PR are taken back.
+
+This file is the playbook for the AI coding agent that does the run. The person starts it with `<%= command %> NUMBER` for an open PR, or `<%= command %>` on a branch that has no PR yet.
+
+## Steps
+
+1. Run `browser-review-gate status` (add `--pr NUMBER` when a number was given). It prints JSON; follow `next`:
+   - `nothing`: no run is needed, or the PR is already verified. Say that review can be requested.
+   - `check_out_pr_head`: check out the PR head with a clean worktree, then start again.
+   - `request_assessment`: run `browser-review-gate request-assessment NUMBER`, wait about a minute, then start again.
+   - `publish_saved`: a run saved for this commit exists. Run `browser-review-gate publish` and stop; nothing runs again.
+   - `open_pull_request`: a run is saved and waits for the PR. Tell the person to open it.
+   - `run_and_publish` or `run_and_save`: continue with step 2.
+2. Read the diff against the base branch and the earlier report in the PR, if any. List the scenarios for the browser-visible behavior that changed. Do not re-run behavior an earlier passing case still covers.
+3. Start the app and open it in a browser tool. `app` in the status output says how: start command, URL, sign-in hint. Use local test data and do not destroy existing data. If the app, the data, or a browser tool is missing, report the blocker. Reading code and running unit tests does not replace a browser run.
+4. Run every scenario end to end. After key actions check the page state, console errors, and failed requests. Record what you observed. A skipped or blocked scenario is not a pass.
+5. Write the report as JSON outside the repository (see the shape below). Set `coverage_complete` to true only when every scenario from step 2 ran.
+6. Publish or save, from the checkout that was tested, with everything committed and pushed:
+   - PR exists: `browser-review-gate publish --report PATH` (add `--pr NUMBER` when the branch has several). It posts the cases with their outcomes. Only a complete all-pass report adds the `<%= label %>` label.
+   - No PR yet: `browser-review-gate save --report PATH`. The run is published when the PR for this commit is opened. A new commit makes it stale.
+7. Check the command result and the PR. A non-zero exit can still mean a report was posted: a failing or incomplete report is visible in the PR and review stays closed.
+8. Request a reviewer only when the person named one and only after the run passed. Otherwise say that review can be requested.
+
+## Report shape
+
+```json
+{
+  "tested_sha": "<full commit SHA that was tested>",
+  "coverage_complete": true,
+  "cases": [
+    { "id": "BROWSER-1", "name": "The changed interaction completes", "result": "pass", "details": "What was observed." }
+  ],
+  "excluded": [
+    { "name": "Sign-in through an external provider", "reason": "Needs a real provider account; covered by integration tests." }
+  ]
+}
+```
+
+`result` is `pass` or `fail`. `excluded` is optional: list a scenario there only when the person decided it stays outside the local run. Never exclude a scenario on your own to make the run complete. Keep customer and real company names out of the report.
+
+## Rules
+
+- Run the awkward path in the browser, or mark coverage incomplete and leave review closed. Do not declare a run done from tests and code reading.
+- Keep the report file and browser artifacts outside the repository. The publisher refuses a checkout with modified or untracked files and lists them.
+- After an unrelated commit, do not run everything again: use the PR comment and the earlier report to pick only what is new.

data/lib/browser_review_gate/templates/workflow.yml.erb

@@ -0,0 +1,64 @@
+# browser_review_gate:managed <%= BrowserReviewGate::VERSION %> — re-run `browser-review-gate install` to update.
+#
+# Decides whether a PR needs a browser run and keeps human review requests behind it.
+# A tool-free model call proposes the decision; the gem validates it and does every write.
+# pull_request_target runs this file from the base branch. PR code is never checked out or
+# executed; the diff is read through the API as data.
+#
+# Setup: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY secret. Settings: .github/browser-review-gate.yml
+# A PR opened before this workflow existed is assessed on its next event; dispatch with pr_number
+# to assess it now.
+
+name: Browser review gate
+
+on:
+  pull_request_target:
+    types: [opened, reopened, synchronize, review_requested]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "Pull request to assess"
+        type: number
+        required: true
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: browser-review-gate-${{ github.event.pull_request.number || inputs.pr_number }}
+  cancel-in-progress: false
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout base branch
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+<% if ruby_version -%>
+          ruby-version: "<%= ruby_version %>"
+<% end -%>
+          bundler-cache: false
+
+      - name: Install browser_review_gate
+        run: |
+          <%= install_command %>
+
+      # PR text is never interpolated into the shell: only the number reaches it.
+      - name: Assess the change and keep review requests behind browser verification
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          PR_NUMBER: ${{ github.event.pull_request.number || inputs.pr_number }}
+        run: browser-review-gate ci "$PR_NUMBER"

data/lib/browser_review_gate/version.rb

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

data/lib/browser_review_gate.rb

@@ -0,0 +1,38 @@
+require_relative "browser_review_gate/version"
+
+# Keeps human review of a pull request behind a browser run of its browser-visible changes.
+#
+# CI side (`browser-review-gate ci`): decide whether the PR needs a browser run, record the decision in
+# one PR comment, and remove reviewer requests until a passing run is published.
+# Local side (`save`, `publish`, `status`, `hook`): an AI coding agent runs the scenarios in a browser
+# and publishes what it observed.
+module BrowserReviewGate
+  Error = Class.new(StandardError)
+
+  # URL-safe Base64 without padding, for the data kept in PR comment markers. Uses nothing outside the
+  # core, so the executable also runs from a plain copy of this directory.
+  module Marker
+    def self.encode(text) = [ text ].pack("m0").tr("+/", "-_").delete("=")
+
+    def self.decode(payload)
+      padded = payload.tr("-_", "+/")
+      "#{padded}#{"=" * ((4 - padded.length % 4) % 4)}".unpack1("m0")
+    end
+  end
+
+  autoload :Assessment, File.join(__dir__, "browser_review_gate/assessment")
+  autoload :Assessor, File.join(__dir__, "browser_review_gate/assessor")
+  autoload :CLI, File.join(__dir__, "browser_review_gate/cli")
+  autoload :Config, File.join(__dir__, "browser_review_gate/config")
+  autoload :Gate, File.join(__dir__, "browser_review_gate/gate")
+  autoload :GitHub, File.join(__dir__, "browser_review_gate/github")
+  autoload :Hook, File.join(__dir__, "browser_review_gate/hook")
+  autoload :Installer, File.join(__dir__, "browser_review_gate/installer")
+  autoload :Markdown, File.join(__dir__, "browser_review_gate/markdown")
+  autoload :ModelClient, File.join(__dir__, "browser_review_gate/model_client")
+  autoload :Publisher, File.join(__dir__, "browser_review_gate/publisher")
+  autoload :Report, File.join(__dir__, "browser_review_gate/report")
+  autoload :SavedReport, File.join(__dir__, "browser_review_gate/saved_report")
+  autoload :Shell, File.join(__dir__, "browser_review_gate/shell")
+  autoload :Status, File.join(__dir__, "browser_review_gate/status")
+end

data/lib/generators/browser_review_gate/install/install_generator.rb

@@ -0,0 +1,22 @@
+require "rails/generators"
+require "browser_review_gate"
+
+module BrowserReviewGate
+  module Generators
+    # bin/rails generate browser_review_gate:install
+    class InstallGenerator < Rails::Generators::Base
+      desc "Set up the browser review gate: CI workflow, settings, playbook, and AI agent entry points."
+
+      class_option :agents, type: :array, desc: "claude, cursor, codex (default: detected from the project)"
+      class_option :gem_source, type: :string, desc: "How CI gets the gem: rubygems (default), git:URL[#REF] or path:DIR"
+      class_option :workflow, type: :string, desc: "Workflow file name under .github/workflows"
+
+      def install
+        BrowserReviewGate::Installer.new(
+          root: destination_root, agents: options[:agents], gem_source: options[:gem_source],
+          workflow: options[:workflow], force: options[:force], dry_run: options[:pretend]
+        ).install
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: browser_review_gate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- JetRockets
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: CI decides whether a pull request needs a browser run and takes back
+  reviewer requests until an AI coding agent (Claude Code, Cursor, Codex) has exercised
+  the change in a browser and published what it observed. One command sets a project
+  up.
+executables:
+- browser-review-gate
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/browser-review-gate
+- lib/browser_review_gate.rb
+- lib/browser_review_gate/assessment.rb
+- lib/browser_review_gate/assessor.rb
+- lib/browser_review_gate/cli.rb
+- lib/browser_review_gate/config.rb
+- lib/browser_review_gate/gate.rb
+- lib/browser_review_gate/github.rb
+- lib/browser_review_gate/hook.rb
+- lib/browser_review_gate/installer.rb
+- lib/browser_review_gate/markdown.rb
+- lib/browser_review_gate/model_client.rb
+- lib/browser_review_gate/publisher.rb
+- lib/browser_review_gate/report.rb
+- lib/browser_review_gate/saved_report.rb
+- lib/browser_review_gate/shell.rb
+- lib/browser_review_gate/status.rb
+- lib/browser_review_gate/templates/agents_block.md.erb
+- lib/browser_review_gate/templates/claude_skill.md.erb
+- lib/browser_review_gate/templates/config.yml.erb
+- lib/browser_review_gate/templates/cursor_command.md.erb
+- lib/browser_review_gate/templates/playbook.md.erb
+- lib/browser_review_gate/templates/workflow.yml.erb
+- lib/browser_review_gate/version.rb
+- lib/generators/browser_review_gate/install/install_generator.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Keeps human review of a pull request behind a browser run of its browser-visible
+  changes.
+test_files: []