browser_review_gate 0.2.2 → 0.3.0

data/lib/browser_review_gate/cli.rb

@@ -11,7 +11,9 @@ module BrowserReviewGate
         eject policy|playbook                     copy a built-in text into the project to rewrite it there
 
       For an AI coding agent, from the checkout that was tested
-        status [--pr NUMBER]                      what the PR needs and what to do next, as JSON
+        verify [--pr NUMBER] [--environment NAME] [--report PATH] [--no-request] [--json]
+                                                  what to run, and with --report publish (or save) the finished run
+        status [--pr NUMBER] [--environment NAME] what the PR needs and what to do next, as JSON
         publish [--pr NUMBER] [--report PATH]     publish observed results (default: the saved run)
         save --report PATH                        keep results until the PR for this commit is opened
         request-assessment NUMBER                 ask CI to assess a PR that has no decision yet
@@ -21,11 +23,13 @@ module BrowserReviewGate
         ci NUMBER                                 assess the PR and take back premature reviewer requests
 
       For the team
-        stats [--days N]                          what the gate did on PRs of the last N days (default 30)
+        doctor [--json]                           check the setup and say what to fix
+        stats [--days N] [--json]                 what the gate did on PRs of the last N days (default 30)
     TEXT
 
-    # `github`, `config` and `model` are replaced in tests.
-    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, github: nil, config: nil, model: nil)
+    # `github`, `config`, `model` and `shell` are replaced in tests.
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, github: nil, config: nil, model: nil, shell: nil)
+      @shell = shell
       @argv = argv.dup
       @github = github
       @config = config
@@ -42,6 +46,8 @@ module BrowserReviewGate
       when "install" then install
       when "eject" then eject
       when "status" then status
+      when "verify" then verify
+      when "doctor" then doctor
       when "publish" then publish
       when "save" then save
       when "request-assessment" then request_assessment
@@ -58,7 +64,10 @@ module BrowserReviewGate
 
     private
 
-    def config = @config ||= Config.load(root)
+    # Local commands read the settings from the default branch when it has them; see Config.load_trusted.
+    def config = @config ||= trusted_config.first
+    def settings_source = @config ? trusted_config.last : nil
+    def trusted_config = @trusted_config ||= (@config ? [ @config, "given" ] : Config.load_trusted(root))
 
     # Settings and rules live at the top of the repository, wherever the command is run from.
     def root
@@ -74,6 +83,9 @@ module BrowserReviewGate
         parser.on("--pr NUMBER", Integer) { |value| parsed[:pr] = value } if flags.include?(:pr)
         parser.on("--report PATH") { |value| parsed[:report] = value } if flags.include?(:report)
         parser.on("--days N", Integer) { |value| parsed[:days] = value } if flags.include?(:days)
+        parser.on("--environment NAME") { |value| parsed[:environment] = value } if flags.include?(:environment)
+        parser.on("--json") { parsed[:json] = true } if flags.include?(:json)
+        parser.on("--no-request") { parsed[:no_request] = true } if flags.include?(:no_request)
         parser.on("--agents LIST", Array) { |value| parsed[:agents] = value } if flags.include?(:install)
         parser.on("--gem-source SOURCE") { |value| parsed[:gem_source] = value } if flags.include?(:install)
         parser.on("--workflow NAME") { |value| parsed[:workflow] = value } if flags.include?(:install)
@@ -101,10 +113,32 @@ module BrowserReviewGate
     end
 
     def status
-      @stdout.puts JSON.pretty_generate(Status.new(github: github, config: config, prompts: Prompts.new(root)).to_h(options(:pr)[:pr]))
+      parsed = options(:pr, :environment)
+      result = Status.new(github: github, config: config, prompts: Prompts.new(root)).to_h(parsed[:pr], environment: parsed[:environment])
+      @stdout.puts JSON.pretty_generate(result.merge("settings_source" => trusted_config.last))
       0
     end
 
+    def verify
+      parsed = options(:pr, :environment, :report, :json, :no_request)
+      outcome, result = Verify.new(github: github, config: config, prompts: Prompts.new(root), shell: @shell || Shell.new)
+        .run(number: parsed[:pr], environment: parsed[:environment], report: parsed[:report], request: !parsed[:no_request])
+      message = Verify.describe(outcome, result)
+      if parsed[:json]
+        @stdout.puts JSON.pretty_generate(result.merge("outcome" => outcome, "message" => message, "settings_source" => trusted_config.last))
+      else
+        @stdout.puts message
+      end
+      Verify.exit_status(outcome)
+    end
+
+    def doctor
+      json = options(:json)[:json]
+      checks = Doctor.new(root: root, github: @github).checks
+      @stdout.puts(json ? Doctor.json(checks) : Doctor.text(checks))
+      checks.any? { |check| check.status == "FAIL" } ? 1 : 0
+    end
+
     def publish
       parsed = options(:pr, :report)
       if Publisher.new(github: github, number: parsed[:pr], report_path: parsed[:report], config: config).publish
@@ -130,25 +164,16 @@ module BrowserReviewGate
     end
 
     def stats
-      days = options(:days).fetch(:days, 30)
+      parsed = options(:days, :json)
+      days = parsed.fetch(:days, 30)
       raise Error, "--days must be a positive number" unless days.positive?
 
-      counts = Stats.new(github: github, config: config).to_h(since: (Time.now.utc - days * 86_400).strftime("%Y-%m-%d"))
-      @stdout.puts "Pull requests touched in the last #{days} days: #{counts["pull_requests"]}",
-        "  assessed by the gate:           #{counts["assessed"]}",
-        "  needed a browser run:           #{counts["required"]}",
-        "    verified by a published run:  #{counts["verified"]}",
-        "    waived:                       #{counts["waived"]}",
-        "    open and still owing a run:   #{counts["owed"]}",
-        "    a run found a failing case:   #{counts["found_a_failure"]}"
+      result = Stats.new(github: github, config: config).to_h(since: (Time.now.utc - days * 86_400).strftime("%Y-%m-%d"))
+      @stdout.puts(parsed[:json] ? JSON.pretty_generate(result) : Stats.text(result, days))
       0
     end
 
-    # Version 0.1.1 installed a `--before` hook that held commands back. It is gone; a project that
-    # still has the entry gets a silent no-op until the installer removes it.
     def hook
-      return 0 if @argv.delete("--before")
-
       agent = @argv.shift
       message = Hook.new(publisher_factory: -> { Publisher.new(github: github, config: config) }).after(@stdin.read)
       output = Hook.render(message, agent)

data/lib/browser_review_gate/config.rb

@@ -1,9 +1,18 @@
+require "uri"
 require "yaml"
 
 module BrowserReviewGate
   # Project settings from .github/browser-review-gate.yml. Every key is optional.
+  #
+  # Some settings are enforced by this gem (it refuses a report or keeps review closed); others are
+  # instructions the agent receives through `status` and `verify`. `ENFORCED` and `AGENT` say which.
   class Config
     PATH = ".github/browser-review-gate.yml"
+    NAME_PATTERN = /\A[a-z][a-z0-9_-]{0,31}\z/
+    EVIDENCE_MODES = %w[never on_failure always].freeze
+    MAX_SCENARIOS = 30
+    MAX_MATRIX_CASES = 24
+
     DEFAULTS = {
       "label" => "browser-verified",
       # A person other than the author adds this label to let review proceed without a browser run.
@@ -16,19 +25,45 @@ module BrowserReviewGate
       "provider" => nil,
       "model" => nil,
       "claude_command" => nil,
-      # How an agent starts and reaches the app for a browser run.
-      "start_command" => nil,
-      "url" => nil,
-      "sign_in" => nil,
+      "environments" => nil,
+      "verification" => nil,
+      "evidence" => nil,
+      "scenarios" => nil,
+      "gate" => nil,
       "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/**" ]
     }.freeze
 
+    SECTIONS = {
+      "verification" => { "environment" => nil, "fail_on_console_errors" => false, "fail_on_network_errors" => false },
+      "evidence" => { "screenshots" => "never", "trace" => "never", "console_logs" => false, "network_logs" => false,
+                      "retention_days" => 14, "link_hosts" => [] },
+      "scenarios" => { "max_count" => 12, "reuse_passing" => true, "mandatory" => [], "matrix" => {} },
+      "gate" => { "require_evidence" => false, "block_on_failure" => true }
+    }.freeze
+
+    ENVIRONMENT_KEYS = %w[url healthcheck start_command sign_in].freeze
+    MANDATORY_KEYS = %w[id name why paths matrix].freeze
+
     def self.load(root = Dir.pwd)
       path = File.join(root, PATH)
-      new(File.exist?(path) ? YAML.safe_load_file(path) : {})
+      parse(File.exist?(path) ? File.read(path) : "")
+    end
+
+    # Settings as the default branch has them, for local commands run on a PR branch: a pull request
+    # must not point the agent at another URL or loosen the policy for its own run. Falls back to the
+    # checkout when the default branch has no settings yet. Returns [config, source].
+    def self.load_trusted(root = Dir.pwd, shell: Shell.new)
+      text = shell.call("git", "-C", root, "show", "origin/HEAD:#{PATH}")
+      [ parse(text), "origin/HEAD" ]
+    rescue Error
+      [ load(root), "working tree" ]
+    end
+
+    def self.parse(text)
+      new(text.to_s.strip.empty? ? {} : YAML.safe_load(text))
     rescue Psych::Exception => error
       raise Error, "#{PATH} is not valid YAML: #{error.message}"
     end
@@ -36,15 +71,34 @@ module BrowserReviewGate
     def initialize(data = {})
       data = {} unless data.is_a?(Hash)
       unknown = data.keys - DEFAULTS.keys
+      moved = unknown & %w[url start_command sign_in]
+      raise Error, "#{PATH}: #{moved.join(", ")} moved under environments.local in 0.3.0" if moved.any?
       raise Error, "#{PATH} has unknown keys: #{unknown.join(", ")}" if unknown.any?
 
       @data = DEFAULTS.merge(data.compact)
+      @sections = SECTIONS.to_h { |name, defaults| [ name, section(name, defaults) ] }
+      @environments = read_environments
+      validate
     end
 
-    DEFAULTS.each_key { |key| define_method(key) { @data[key] } }
+    (DEFAULTS.keys - %w[environments verification evidence scenarios gate]).each do |key|
+      define_method(key) { @data[key] }
+    end
+
+    attr_reader :environments
+
+    def verification = @sections["verification"]
+    def evidence = @sections["evidence"]
+    def scenarios = @sections["scenarios"]
+    def gate = @sections["gate"]
+
+    # The environment a run uses: the one named, the configured default, or the only one there is.
+    def environment(name = nil)
+      name ||= verification["environment"] || (environments.size == 1 ? environments.keys.first : nil)
+      return if name.nil?
+      raise Error, "Unknown environment #{name.inspect}; #{PATH} defines: #{environments.keys.join(", ")}" unless environments.key?(name)
 
-    def app
-      { "start_command" => start_command, "url" => url, "sign_in" => sign_in }.compact
+      environments.fetch(name).merge("name" => name)
     end
 
     def skip?(author:, branch:)
@@ -52,12 +106,171 @@ module BrowserReviewGate
     end
 
     # "dir/**" means everything under dir; other patterns are globs where "**/" spans directories.
-    def ignored?(path)
-      ignore_paths.any? do |pattern|
+    def ignored?(path) = Config.match?(ignore_paths, path)
+
+    def self.match?(patterns, path)
+      patterns.any? do |pattern|
         next path.start_with?(pattern.delete_suffix("**")) if pattern.end_with?("/**")
 
         File.fnmatch?(pattern, path, File::FNM_PATHNAME | File::FNM_DOTMATCH)
       end
     end
+
+    # Mandatory scenarios that apply to a change touching `paths`, expanded over the matrix where asked.
+    # They are added by this code, not proposed by the model, so a PR cannot talk its way out of them.
+    def mandatory_scenarios(paths)
+      scenarios["mandatory"].select { |entry| entry["paths"].nil? || paths.any? { |path| Config.match?(entry["paths"], path) } }
+        .flat_map { |entry| expand(entry) }
+    end
+
+    # What the settings ask of a run, split by who makes sure it happens.
+    def policy
+      {
+        "enforced" => {
+          "fail_on_console_errors" => verification["fail_on_console_errors"],
+          "fail_on_network_errors" => verification["fail_on_network_errors"],
+          "require_evidence" => gate["require_evidence"],
+          "block_on_failure" => gate["block_on_failure"],
+          "reuse_passing" => scenarios["reuse_passing"],
+          "max_scenarios" => scenarios["max_count"]
+        },
+        "agent" => {
+          "screenshots" => evidence["screenshots"], "trace" => evidence["trace"],
+          "console_logs" => evidence["console_logs"], "network_logs" => evidence["network_logs"]
+        }
+      }
+    end
+
+    private
+
+    def section(name, defaults)
+      value = @data[name] || {}
+      raise Error, "#{PATH}: #{name} must be a mapping" unless value.is_a?(Hash)
+
+      unknown = value.keys - defaults.keys
+      raise Error, "#{PATH}: #{name} has unknown keys: #{unknown.join(", ")}" if unknown.any?
+
+      defaults.merge(value.compact)
+    end
+
+    def read_environments
+      listed = @data["environments"]
+      return {} unless listed
+      raise Error, "#{PATH}: environments must be a mapping of names to settings" unless listed.is_a?(Hash)
+
+      listed.to_h do |name, settings|
+        raise Error, "#{PATH}: environment name #{name.inspect} must be lowercase letters, digits, - or _" unless name.is_a?(String) && NAME_PATTERN.match?(name)
+        raise Error, "#{PATH}: environments.#{name} must be a mapping" unless settings.is_a?(Hash)
+
+        unknown = settings.keys - ENVIRONMENT_KEYS
+        raise Error, "#{PATH}: environments.#{name} has unknown keys: #{unknown.join(", ")}" if unknown.any?
+
+        [ name, settings.compact ]
+      end
+    end
+
+    def validate
+      environments.each do |name, settings|
+        url = settings["url"]
+        raise Error, "#{PATH}: environments.#{name}.url must be an http(s) URL" unless url.nil? || Config.http_url?(url)
+
+        check = settings["healthcheck"]
+        unless check.nil? || (check.is_a?(String) && (check.start_with?("/") || Config.http_url?(check)))
+          raise Error, "#{PATH}: environments.#{name}.healthcheck must be a path starting with / or an http(s) URL"
+        end
+      end
+      environment # the configured default must exist
+      validate_flags
+      validate_evidence
+      validate_scenarios
+    end
+
+    def validate_flags
+      { "verification" => %w[fail_on_console_errors fail_on_network_errors], "evidence" => %w[console_logs network_logs],
+        "scenarios" => %w[reuse_passing], "gate" => %w[require_evidence block_on_failure] }.each do |name, keys|
+        keys.each do |key|
+          raise Error, "#{PATH}: #{name}.#{key} must be true or false" unless [ true, false ].include?(@sections[name][key])
+        end
+      end
+    end
+
+    def validate_evidence
+      %w[screenshots trace].each do |key|
+        next if EVIDENCE_MODES.include?(evidence[key])
+
+        raise Error, "#{PATH}: evidence.#{key} must be one of #{EVIDENCE_MODES.join(", ")}"
+      end
+      days = evidence["retention_days"]
+      raise Error, "#{PATH}: evidence.retention_days must be a whole number from 1 to 365" unless days.is_a?(Integer) && days.between?(1, 365)
+
+      hosts = evidence["link_hosts"]
+      return if hosts.is_a?(Array) && hosts.all? { |host| host.is_a?(String) && host.match?(/\A[a-z0-9.-]+\z/) }
+
+      raise Error, "#{PATH}: evidence.link_hosts must be a list of host names"
+    end
+
+    def validate_scenarios
+      count = scenarios["max_count"]
+      raise Error, "#{PATH}: scenarios.max_count must be a whole number from 1 to #{MAX_SCENARIOS}" unless count.is_a?(Integer) && count.between?(1, MAX_SCENARIOS)
+
+      validate_matrix
+      mandatory = scenarios["mandatory"]
+      raise Error, "#{PATH}: scenarios.mandatory must be a list" unless mandatory.is_a?(Array)
+
+      mandatory.each_with_index { |entry, index| validate_mandatory(entry, index + 1) }
+      ids = mandatory_scenarios_all.map { |scenario| scenario["id"] }
+      raise Error, "#{PATH}: scenarios.mandatory ids must be unique after the matrix is applied" unless ids.uniq.size == ids.size
+
+      expanded = mandatory.count { |entry| entry["matrix"] } * matrix_combinations.size
+      raise Error, "#{PATH}: the matrix makes #{expanded} mandatory cases; keep it at #{MAX_MATRIX_CASES} or fewer" if expanded > MAX_MATRIX_CASES
+    end
+
+    def validate_matrix
+      matrix = scenarios["matrix"]
+      valid = matrix.is_a?(Hash) && matrix.all? do |name, values|
+        NAME_PATTERN.match?(name.to_s) && values.is_a?(Array) && values.any? && values.all? { |value| NAME_PATTERN.match?(value.to_s) }
+      end
+      raise Error, "#{PATH}: scenarios.matrix maps a dimension (e.g. role) to a list of short lowercase values" unless valid
+    end
+
+    def validate_mandatory(entry, position)
+      raise Error, "#{PATH}: scenarios.mandatory #{position} must be a mapping" unless entry.is_a?(Hash)
+
+      unknown = entry.keys - MANDATORY_KEYS
+      raise Error, "#{PATH}: scenarios.mandatory #{position} has unknown keys: #{unknown.join(", ")}" if unknown.any?
+      raise Error, "#{PATH}: scenarios.mandatory #{position} id must use letters, digits, dots, underscores or hyphens" unless entry["id"].is_a?(String) && Report::CASE_ID_PATTERN.match?(entry["id"])
+      raise Error, "#{PATH}: scenarios.mandatory #{position} needs a name" unless entry["name"].is_a?(String) && !entry["name"].strip.empty?
+      raise Error, "#{PATH}: scenarios.mandatory #{position} paths must be a list of globs" unless entry["paths"].nil? || (entry["paths"].is_a?(Array) && entry["paths"].all?(String))
+      raise Error, "#{PATH}: scenarios.mandatory #{position} matrix must be true or false" unless [ nil, true, false ].include?(entry["matrix"])
+    end
+
+    def mandatory_scenarios_all = scenarios["mandatory"].flat_map { |entry| expand(entry) }
+
+    # Every combination of the matrix dimensions, e.g. [{"role"=>"admin","viewport"=>"mobile"}, ...].
+    def matrix_combinations
+      matrix = scenarios["matrix"]
+      return [ {} ] if matrix.empty?
+
+      matrix.values.first.product(*matrix.values.drop(1)).map { |values| matrix.keys.zip(values).to_h }
+    end
+
+    def expand(entry)
+      base = { "id" => entry["id"], "name" => entry["name"].split.join(" "), "priority" => "critical", "category" => "mandatory",
+               "why" => entry["why"] || "Required by the project settings for the areas this change touches." }
+      return [ base ] unless entry["matrix"]
+
+      matrix_combinations.map do |combination|
+        suffix = combination.values.join(".")
+        details = combination.map { |dimension, value| "#{dimension} #{value}" }.join(", ")
+        base.merge("id" => "#{entry["id"]}.#{suffix}", "name" => "#{base["name"]} (#{details})", "matrix" => combination)
+      end
+    end
+
+    def self.http_url?(value)
+      uri = URI.parse(value.to_s)
+      %w[http https].include?(uri.scheme) && !uri.host.to_s.empty? && uri.userinfo.nil?
+    rescue URI::InvalidURIError
+      false
+    end
   end
 end

data/lib/browser_review_gate/doctor.rb

@@ -0,0 +1,216 @@
+require "json"
+require "stringio"
+
+module BrowserReviewGate
+  # Checks a project's setup and says what to fix. A check that cannot be verified from here is SKIP,
+  # never PASS. Nothing secret is printed: secrets are checked by name only.
+  class Doctor
+    Check = Struct.new(:name, :status, :message, :fix) do
+      def to_h = { "name" => name, "status" => status, "message" => message, "fix" => fix }.compact
+    end
+
+    SECRETS = %w[CLAUDE_CODE_OAUTH_TOKEN ANTHROPIC_API_KEY OPENAI_API_KEY GEMINI_API_KEY].freeze
+    BROWSER_TOOLS = { "playwright" => "Playwright", "chrome-devtools" => "Chrome DevTools MCP", "browsermcp" => "Browser MCP",
+                      "puppeteer" => "Puppeteer" }.freeze
+    AGENT_FILES = {
+      "claude" => [ ".claude/skills/browser-pr-verification/SKILL.md", ".claude/settings.json" ],
+      "cursor" => [ ".cursor/commands/browser-pr-verification.md", ".cursor/hooks.json" ],
+      "codex" => [ "AGENTS.md", ".codex/hooks.json" ]
+    }.freeze
+
+    # `probe` takes a URL and says whether something answers there.
+    def initialize(root:, shell: Shell.new, github: nil, probe: nil, config_loader: nil)
+      @root = root
+      @shell = shell
+      @github = github
+      @probe = probe || Status.method(:answers?)
+      @config_loader = config_loader || -> { Config.load(root) }
+    end
+
+    def checks
+      @checks = []
+      ruby
+      gem_executable
+      repository
+      config = configuration
+      gh_ready = github_cli
+      repository_access if gh_ready
+      environments(config) if config
+      agents(config)
+      browser_tools
+      workflow(config) if config
+      required_check(config) if config && gh_ready
+      provider_secrets(config) if config && gh_ready
+      @checks
+    end
+
+    def self.text(checks)
+      width = checks.map { |check| check.name.length }.max.to_i
+      lines = checks.map do |check|
+        line = "#{check.status.ljust(4)}  #{check.name.ljust(width)}  #{check.message}"
+        check.fix ? "#{line}\n#{" " * (width + 8)}fix: #{check.fix}" : line
+      end
+      counts = %w[PASS WARN FAIL SKIP].map { |status| "#{checks.count { |check| check.status == status }} #{status}" }
+      (lines + [ "", counts.join(", ") ]).join("\n")
+    end
+
+    def self.json(checks) = JSON.pretty_generate("checks" => checks.map(&:to_h), "ok" => checks.none? { |check| check.status == "FAIL" })
+
+    private
+
+    def add(name, status, message, fix = nil) = @checks << Check.new(name, status, message, fix)
+    def exist?(path) = File.exist?(File.join(@root, path))
+    def read(path) = exist?(path) ? File.read(File.join(@root, path)) : ""
+
+    def run(*argv)
+      @shell.call(*argv)
+    rescue Error
+      nil
+    end
+
+    def ruby
+      return add("ruby", "PASS", "Ruby #{RUBY_VERSION}") if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.2")
+
+      add("ruby", "FAIL", "Ruby #{RUBY_VERSION} is older than 3.2", "Use Ruby 3.2 or newer")
+    end
+
+    def gem_executable
+      found = ENV["PATH"].to_s.split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, "browser-review-gate")) }
+      return add("gem", "PASS", "browser_review_gate #{VERSION} runs; a browser-review-gate executable is on PATH") if found
+
+      add("gem", "WARN", "browser_review_gate #{VERSION} runs, but browser-review-gate is not on PATH",
+        "bundle add browser_review_gate --group development, or run it with bundle exec")
+    end
+
+    def repository
+      top = run("git", "rev-parse", "--show-toplevel")
+      return add("repository", "PASS", "git repository at #{top.strip}") if top
+
+      add("repository", "FAIL", "not inside a git repository", "Run from the project checkout")
+    end
+
+    def configuration
+      config = @config_loader.call
+      add("settings", exist?(Config::PATH) ? "PASS" : "WARN", exist?(Config::PATH) ? "#{Config::PATH} is valid" : "#{Config::PATH} is missing; defaults apply",
+        exist?(Config::PATH) ? nil : "browser-review-gate install")
+      config
+    rescue Error => error
+      add("settings", "FAIL", error.message, "Fix #{Config::PATH}")
+      nil
+    end
+
+    def github_cli
+      unless run("gh", "--version")
+        add("gh", "FAIL", "the GitHub CLI is not installed", "Install gh: https://cli.github.com")
+        return false
+      end
+      unless run("gh", "auth", "status")
+        add("gh", "FAIL", "the GitHub CLI is not signed in", "gh auth login")
+        return false
+      end
+
+      add("gh", "PASS", "installed and signed in")
+      true
+    end
+
+    def repository_access
+      github = @github || GitHub.new(shell: @shell)
+      name = github.repository
+      push = run("gh", "api", "repos/#{name}", "--jq", ".permissions.push").to_s.strip
+      return add("repository access", "PASS", "#{name}: you can push, so your reports count") if push == "true"
+      return add("repository access", "WARN", "#{name}: you cannot push; reports you publish are ignored", "Ask for write access") if push == "false"
+
+      add("repository access", "SKIP", "#{name}: permissions could not be read")
+    rescue Error => error
+      add("repository access", "FAIL", error.message.lines.first.to_s.strip, "Check that the repository has a GitHub remote")
+    end
+
+    def environments(config)
+      return add("environments", "WARN", "no environment is configured", "Add environments.local.url in #{Config::PATH}") if config.environments.empty?
+
+      config.environments.each do |name, settings|
+        next add("environment #{name}", "WARN", "no url", "Set environments.#{name}.url") unless settings["url"]
+
+        url = Status.healthcheck_url(settings.merge("name" => name))
+        if @probe.call(url)
+          add("environment #{name}", "PASS", "answers at #{url}")
+        else
+          add("environment #{name}", "WARN", "does not answer at #{url}",
+            settings["start_command"] ? "Start it with #{settings["start_command"]} before a run" : "Make it reachable from where the agent runs")
+        end
+      end
+    end
+
+    def agents(config)
+      installer = Installer.new(root: @root, log: StringIO.new)
+      installer.detect_agents.each do |agent|
+        entry, hooks = AGENT_FILES.fetch(agent)
+        wired = agent == "codex" ? read(entry).include?("browser_review_gate:start") : exist?(entry)
+        hooked = read(hooks).include?("browser-review-gate hook #{agent}")
+        if wired && hooked
+          add("agent #{agent}", "PASS", "instructions and post-command hook installed")
+        else
+          add("agent #{agent}", "WARN", [ wired ? nil : "#{entry} missing", hooked ? nil : "hook missing in #{hooks}" ].compact.join("; "),
+            "browser-review-gate install --agents #{agent}")
+        end
+      end
+      add("playbook", exist?(Installer::PLAYBOOK) ? "PASS" : "WARN", exist?(Installer::PLAYBOOK) ? Installer::PLAYBOOK : "#{Installer::PLAYBOOK} missing",
+        exist?(Installer::PLAYBOOK) ? nil : "browser-review-gate install")
+      rules = Prompts.new(@root).rules
+      add("project rules", rules ? "PASS" : "WARN", rules ? "#{Prompts::RULES} has rules" : "#{Prompts::RULES} has no rules yet",
+        rules ? nil : "Describe what this application always checks")
+      config
+    end
+
+    # Only what the project's own files show. A tool configured elsewhere cannot be seen from here.
+    def browser_tools
+      files = [ ".mcp.json", ".cursor/mcp.json", ".codex/config.toml", ".claude/settings.json", "package.json" ]
+      text = files.map { |path| read(path) }.join("\n").downcase
+      found = BROWSER_TOOLS.select { |key, _label| text.include?(key) }.values
+      return add("browser tool", "PASS", "configured in the project: #{found.join(", ")}") if found.any?
+
+      add("browser tool", "SKIP", "none found in the project's files; one may be configured per user",
+        "Give the agent a browser tool, e.g. Playwright MCP or Chrome DevTools MCP")
+    end
+
+    def workflow(config)
+      path = ".github/workflows/#{config.workflow}"
+      return add("workflow", "FAIL", "#{path} is missing", "browser-review-gate install") unless exist?(path)
+
+      version = read(path)[/browser_review_gate:managed (\S+)/, 1]
+      return add("workflow", "PASS", "#{path} (#{version})") if version == VERSION
+      return add("workflow", "SKIP", "#{path} was not written by the installer; cannot tell its version") unless version
+
+      add("workflow", "WARN", "#{path} was written by #{version}; this is #{VERSION}", "browser-review-gate install")
+    end
+
+    def required_check(config)
+      github = @github || GitHub.new(shell: @shell)
+      branch = run("gh", "api", "repos/#{github.repository}", "--jq", ".default_branch").to_s.strip
+      return add("required check", "SKIP", "the default branch could not be read") if branch.empty?
+
+      contexts = run("gh", "api", "repos/#{github.repository}/branches/#{branch}/protection/required_status_checks", "--jq", ".contexts[]")
+      return add("required check", "SKIP", "branch protection of #{branch} could not be read (needs admin access, or none is set)",
+        "To block merging, make #{config.status_context} a required status check") unless contexts
+      return add("required check", "PASS", "#{config.status_context} is required on #{branch}") if contexts.lines.map(&:strip).include?(config.status_context)
+
+      add("required check", "WARN", "#{config.status_context} is not required on #{branch}; the gate does not block merging",
+        "Make #{config.status_context} a required status check")
+    rescue Error
+      add("required check", "SKIP", "could not be checked")
+    end
+
+    def provider_secrets(config)
+      names = run("gh", "secret", "list", "--json", "name", "--jq", ".[].name")
+      return add("model credentials", "SKIP", "repository secrets could not be listed (needs admin access)") unless names
+
+      present = names.lines.map(&:strip) & SECRETS
+      return add("model credentials", "FAIL", "no model secret in the repository", "Add one of #{SECRETS.join(", ")}") if present.empty?
+      if config.provider.to_s.match?(/\A(openai|gemini)\z/) && config.model.nil?
+        return add("model credentials", "FAIL", "#{config.provider} needs `model`", "Set model in #{Config::PATH}")
+      end
+
+      add("model credentials", "PASS", "secret present: #{present.join(", ")}")
+    end
+  end
+end