deployangel 0.1.23 → 0.1.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2635666118ec2250b5414245e3ea0aa1026d30e4369788e2c82bf6e6b0a52f71
-  data.tar.gz: 0fac6aa9bf419e2ad7a93a289902c94fa94a6d0b42c1418d7370afbaf90501cd
+  metadata.gz: 05e4cde0e2b605e294d51c73f25af3a2b5d9496c6a8e0b3270c358a9a5b9e4ec
+  data.tar.gz: 722541542ff63d2cb8eedb0020a974a71ecf4eaaff3338e50e1002bc88e7ebbd
 SHA512:
-  metadata.gz: 41f77d3e77fae4bccf35c82570582e01501246314c540d6bf6d227cdcd15e033237d62d9b0b2769e80766f53293982b4e8fe07e644ced1e99d93ca13a57b93f2
-  data.tar.gz: 674cb4c4972c88d861375904572c1048f247f041400c52b8d5380f44b3ff76d8b6f473362b404bedcf2377e1b6811cf96eea39f5cb9934b07271ddd627376afa
+  metadata.gz: c9674f14d5c5f09540e2fe9a102fd1e16571c6492214a47b70a155bb6c70c98af1e333c58734b8eca2079aab323aca6090a47bf8b964111a59e6734dcee316d3
+  data.tar.gz: 71fad66b1e6f4d36b1794e8f403b05524a0b151a2b4232067e39f3f7341c80d6673b28362215bdf2250ef179640124249c397ec366c85556a9eae5f9d87ce10a

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.25 (2026-10-10)
+
+- `verify` prints what a clearance doesn't cover right under it: app-wide
+  signals without enough data, critical flows and changed items not run
+  since the deploy, and latency that rose but stayed within limits (from
+  the verdict document's new `clearance.scope`). The coding-agent
+  instructions `install agents` writes now say to report it too.
+
+## 0.1.24 (2026-10-10)
+
+- `deployangel doctor` checks the setup: the agent in the bundle, the
+  schedules in this checkout's files, and how production will know the
+  release; then, with a token, what DeployAngel has seen (processes
+  reporting and their releases, what the agent reported, and setup
+  problems with fixes). Only errors fail it. Run where the app runs, it
+  uses the agent's `DEPLOYANGEL_TOKEN` and shows the release that process
+  reports. Needs a DeployAngel server with `GET /api/v1/setup`.
+
 ## 0.1.23 (2026-10-09)
 
 - GoodJob's cron (`config.good_job.cron`, or `GOOD_JOB_CRON`) is read from

data/README.md

@@ -441,8 +441,20 @@ bundle exec deployangel exercise --url=https://example.com  # send the plan's re
 bundle exec deployangel release --commit=$SHA          # register a deploy (manual or CI)
 bundle exec deployangel check --name="smoke: signup" --status=pass --covers=registration
 bundle exec deployangel exception <fingerprint>
+bundle exec deployangel doctor                         # check the setup
 ```
 
+`deployangel doctor` checks this checkout (the agent in the bundle, the
+schedules in its files, how production will know the release) and, with a
+token, what DeployAngel has seen of the app: which processes report and the
+release each runs, the routes, job classes, and scheduled jobs the agent
+reported, and setup problems with what to do about each. Only errors (a
+rejected token, an unreachable server, no agent in the bundle) exit 5;
+warnings exit 0, so it's safe in CI. It reads `DEPLOYANGEL_API_TOKEN`, or
+`DEPLOYANGEL_TOKEN` where the app runs, so
+`heroku run bundle exec deployangel doctor` also shows the release that
+process reports.
+
 Output is text on a terminal and JSON (the verdict document) when piped, or
 choose with `--format=text|json`. Exit codes:
 
@@ -533,7 +545,8 @@ verdict: call the `wait_for_verification` MCP tool with the commit and
 `until: "initial"`, calling again while it's in progress, or run
 `bundle exec deployangel verify --commit=<sha> --wait --until=initial`.
 
-- Exit 0 / verified: the release is cleared. Report the clearance line and
+- Exit 0 / verified: the release is cleared. Report the clearance line, what
+  it says it doesn't cover ("Not assessed", "Not run since the deploy"), and
   anything DeployAngel is still watching, then move on.
 - Exit 6: no problems so far, but NOT cleared. Report "no problems so far, not
   yet cleared" and the expected clearance time. DeployAngel keeps verifying and

data/lib/deployangel/cli/formatter.rb

@@ -70,7 +70,9 @@ module DeployAngel
 
       def notes(document)
         v = document["verification"] || {}
-        notes = []
+        # What a clearance doesn't cover, right under it (servers from
+        # 2026-10-10 send it).
+        notes = Array(document.dig("clearance", "scope", "lines"))
         if (check = v["initial_check"]) && v["verdict"].nil?
           notes << "Initial check: #{check["result"].tr("_", " ")}. Not cleared yet."
         end

data/lib/deployangel/cli.rb

@@ -12,13 +12,14 @@ require_relative "ci_environment"
 require_relative "verification_waiter"
 require_relative "cli/formatter"
 require_relative "exerciser"
+require_relative "doctor"
 
 module DeployAngel
   # `deployangel` command for developers, CI, and coding agents.
   # Runs without booting Rails.
   class CLI
     USAGE_ERROR = 5
-    COMMANDS = %w[release verify status plan exercise exception check install mcp version help].freeze
+    COMMANDS = %w[release verify status plan exercise exception check install doctor mcp version help].freeze
 
     HELP = <<~TEXT
       Usage: deployangel <command> [options]
@@ -39,6 +40,8 @@ module DeployAngel
         install    Add a Kamal deploy hook,       deployangel install kamal
                    bake the commit into an image, deployangel install docker
                    or set up coding agents        deployangel install agents
+        doctor     Check the setup: this checkout  [--format=text|json]
+                   and what DeployAngel has seen
         mcp        Run the MCP server over stdio (for coding agents)
 
       With no target, verify, plan, and check use the current git HEAD commit.
@@ -88,7 +91,8 @@ module DeployAngel
       `until: "initial"`, calling again while it's in progress, or run
       `bundle exec deployangel verify --commit=<sha> --wait --until=initial`.
 
-      - Exit 0 / verified: the release is cleared. Report the clearance line and
+      - Exit 0 / verified: the release is cleared. Report the clearance line, what
+        it says it doesn't cover ("Not assessed", "Not run since the deploy"), and
         anything DeployAngel is still watching, then move on.
       - Exit 6: no problems so far, but NOT cleared. Report "no problems so far, not
         yet cleared" and the expected clearance time. DeployAngel keeps verifying and
@@ -148,6 +152,7 @@ module DeployAngel
       when "exception" then exception
       when "check" then check
       when "install" then install
+      when "doctor" then doctor
       when "mcp" then mcp
       when "version", "--version", "-v" then @stdout.puts(DeployAngel::VERSION) || 0
       when nil, "help", "--help", "-h" then @stdout.puts(HELP) || 0
@@ -323,6 +328,36 @@ module DeployAngel
         0
       end
 
+      # What this checkout will report and what DeployAngel has seen of the
+      # app. Warnings are advice, so only errors (a rejected token, an
+      # unreachable server, no agent in the bundle) fail it.
+      def doctor
+        format = parse(format: nil) { |o, opts| o.on("--format=FORMAT", %w[text json]) { |v| opts[:format] = v } }[:format]
+        doctor = Doctor.new(root: @root, client: doctor_client, env: @env)
+        output(doctor.to_h, format) { doctor_text(doctor.checks) }
+        doctor.failed? ? USAGE_ERROR : 0
+      end
+
+      DOCTOR_MARKS = { ok: "✓", warn: "!", error: "✗", info: "·" }.freeze
+
+      def doctor_text(checks)
+        lines = [ "DeployAngel doctor" ]
+        checks.each do |check|
+          lines << "  #{DOCTOR_MARKS.fetch(check.status)} #{check.message}"
+          lines << "      #{check.fix}" if check.fix
+        end
+        lines.join("\n")
+      end
+
+      # Either token works: the setup endpoint answers any of the app's. The
+      # agent's own token is for running it where the app runs.
+      def doctor_client
+        return @client if @client
+
+        token = [ @env["DEPLOYANGEL_API_TOKEN"], @env["DEPLOYANGEL_TOKEN"] ].find { |value| !value.to_s.empty? } or return
+        Client.new(token: token, endpoint: @env["DEPLOYANGEL_URL"] || Configuration::DEFAULT_ENDPOINT)
+      end
+
       def install
         case (target = @argv.shift)
         when "kamal" then install_kamal

data/lib/deployangel/client.rb

@@ -31,6 +31,7 @@ module DeployAngel
     end
 
     def token_info = get("/api/v1/token")
+    def setup = get("/api/v1/setup")
     def latest_deployment = get("/api/v1/deployments/latest")
     def deployments(**filters) = get("/api/v1/deployments", filters.compact)["deployments"]
     def exception(fingerprint) = get("/api/v1/exceptions/#{URI.encode_www_form_component(fingerprint)}")

data/lib/deployangel/doctor.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "configuration"
+require_relative "metadata"
+require_relative "rails/metadata"
+require_relative "core/release"
+
+module DeployAngel
+  # `deployangel doctor`: what this checkout will report, and what
+  # DeployAngel has seen of the app so far (GET /api/v1/setup), as checks
+  # with what to do about each. It runs without booting the app, so it
+  # reads only the schedules kept in files.
+  class Doctor
+    # status is ok, warn, error, or info. Only errors fail the command.
+    Check = Struct.new(:status, :message, :fix, keyword_init: true) do
+      def to_h = { "status" => status.to_s, "message" => message, "fix" => fix }.compact
+    end
+
+    SOURCES = { "solid_queue" => "Solid Queue", "sidekiq_cron" => "sidekiq-cron", "sidekiq_scheduler" => "sidekiq-scheduler",
+                "whenever" => "whenever", "good_job" => "GoodJob", "config" => "agent config" }.freeze
+    TOKEN_HELP = "Set DEPLOYANGEL_API_TOKEN (a \"CLI & coding agents\" token from the app's Settings) or DEPLOYANGEL_TOKEN " \
+                 "(the app's agent token), then run this again."
+    MAX_HOSTS = 5
+
+    attr_reader :setup
+
+    # client is nil when no token is set; the local checks still run.
+    def initialize(root:, client:, env: {})
+      @root = root
+      @client = client
+      @env = env
+    end
+
+    def checks
+      @checks ||= begin
+        @setup, server = server_checks
+        [ *agent_checks, here_check, schedule_check, *server, release_check, *comparison_checks ].compact
+      end
+    end
+
+    def failed?
+      checks.any? { |check| check.status == :error }
+    end
+
+    def to_h
+      { "checks" => checks.map(&:to_h), "setup" => setup }
+    end
+
+    private
+      def agent_checks
+        lock = read("Gemfile.lock") or return []
+        version = lock[/^    deployangel \(([^)]+)\)/, 1]
+        return [ Check.new(status: :ok, message: "Agent: deployangel #{version} in Gemfile.lock") ] if version
+
+        [ Check.new(status: :error, message: "The agent isn't in the bundle", fix: "Add gem \"deployangel\" to the Gemfile and run bundle install.") ]
+      end
+
+      def schedule_check
+        counts = local_schedules.group_by { |schedule| schedule["source"] }.map { |source, list| "#{SOURCES.fetch(source, source)} #{list.size}" }
+        later = [ ("GoodJob's cron" if read("Gemfile.lock").to_s.include?(" good_job (")), "config.recurring_jobs" ].compact
+        note = "#{later.join(" and ")} #{later.one? ? "is" : "are"} read when the app runs."
+        if counts.any?
+          Check.new(status: :ok, message: "#{count(local_schedules.size, "scheduled job")} in this checkout (#{counts.join(", ")}). #{note}")
+        else
+          Check.new(status: :info, message: "No scheduled jobs in this checkout's schedule files. #{note}")
+        end
+      end
+
+      # The token's app and what DeployAngel has seen of it.
+      def server_checks
+        return [ nil, [ Check.new(status: :warn, message: "No token, so only this checkout was checked", fix: TOKEN_HELP) ] ] unless @client
+
+        setup = @client.setup
+        checks = [ app_check(setup), agent_check(setup), metadata_check(setup), *gap_checks(setup), progress_check(setup) ]
+        [ setup, checks.compact ]
+      rescue Client::Unauthorized => e
+        [ nil, [ Check.new(status: :error, message: "DeployAngel rejected the token (#{e.message})", fix: TOKEN_HELP) ] ]
+      rescue Client::NotFound
+        [ nil, [ Check.new(status: :warn, message: "This DeployAngel server doesn't support doctor yet; only this checkout was checked") ] ]
+      rescue Client::Error => e
+        [ nil, [ Check.new(status: :error, message: "Couldn't reach DeployAngel: #{e.message}") ] ]
+      end
+
+      def app_check(setup)
+        app = setup["app"] || {}
+        Check.new(status: :ok, message: "App: #{app["name"]} (#{app["environment"]})")
+      end
+
+      def agent_check(setup)
+        agent = setup["agent"] || {}
+        processes = Array(agent["processes"])
+        if agent["reporting"]
+          releases = processes.map { |process| process["release"] }.uniq
+          release = releases.compact.one? && releases.size == 1 ? ", release #{releases.first}" : ""
+          from = processes.any? ? " from #{hosts(processes)}" : ""
+          Check.new(status: :ok, message: "Agent reporting#{from}#{release}")
+        elsif agent["last_received_at"]
+          Check.new(status: :warn, message: "The agent last reported #{time(agent["last_received_at"])}, and nothing since",
+            fix: "Check the app is running, and that DEPLOYANGEL_TOKEN is still set on its processes.")
+        else
+          Check.new(status: :warn, message: "The agent hasn't reported yet",
+            fix: "Deploy with DEPLOYANGEL_TOKEN set to the app's agent token (Settings, Tokens: \"Deployed application\").")
+        end
+      end
+
+      def metadata_check(setup)
+        metadata = setup["metadata"] or return
+        jobs = Array(setup["scheduled_jobs"])
+        problems = jobs.select { |job| %w[overdue failed].include?(job["status"]) }
+        problem_text = problems.any? ? ", #{problems.size} needing attention (#{problems.first(3).map { |job| "#{job["label"]} #{job["status"]}" }.join(", ")})" : ""
+        Check.new(status: problems.any? ? :warn : :ok,
+          message: "Reported: #{count(metadata["routes"], "route")}, #{count(metadata["job_classes"], "job class", "job classes")}, " \
+                   "#{count(metadata["schedules"], "scheduled job")}#{problem_text}",
+          fix: ("See them on the app page, under Scheduled jobs." if problems.any?))
+      end
+
+      def gap_checks(setup)
+        Array(setup["gaps"]).map { |gap| Check.new(status: :warn, message: gap["title"], fix: gap["fix"]) }
+      end
+
+      def progress_check(setup)
+        deployments = setup["deployments"] || {}
+        latest = deployments["latest"]
+        message = if setup["warm_up_ends_at"]
+          "Learning what's normal for this app until #{time(setup["warm_up_ends_at"])}; deploys before then are checked, not cleared"
+        elsif latest
+          "#{count(deployments["count"], "deploy")} so far; the latest, #{latest["label"]}, is #{latest["verdict"] || latest["state"]}"
+        elsif setup.dig("agent", "last_received_at")
+          "No deploys yet: your next deploy gets the first verdict"
+        end
+        message && Check.new(status: :info, message: message)
+      end
+
+      # Run where the app runs (`heroku run`, a container shell), the release
+      # this process would report. On a developer machine it would only be
+      # the checkout's git HEAD, which says nothing about production, so
+      # it's left out there.
+      def here_check
+        release = Release.resolve(config: Configuration.new(@env), env: @env, root: @root)
+        if release.unknown?
+          return unless where_the_app_runs?
+
+          Check.new(status: :warn, message: "Here, the agent can't tell which release is running",
+            fix: "Set DEPLOYANGEL_REVISION to the deployed commit, or see https://deployangel.com/docs#containers.")
+        elsif release.source != "git_head"
+          Check.new(status: :ok, message: "Here, the agent would report release #{release.version || release.commit} (from #{release.source})")
+        end
+      rescue StandardError
+        nil
+      end
+
+      def where_the_app_runs?
+        !@env["DEPLOYANGEL_TOKEN"].to_s.empty? && @env["DEPLOYANGEL_API_TOKEN"].to_s.empty?
+      end
+
+      # How production will know the release, judged from what's reporting
+      # once anything is, and from this checkout's deploy files before then.
+      def release_check
+        return if Array(setup&.dig("agent", "processes")).any?
+
+        if file?("config/deploy.yml")
+          Check.new(status: :ok, message: "Kamal deploys: the agent reads the release from KAMAL_VERSION")
+        elsif file?("render.yaml")
+          Check.new(status: :ok, message: "Render deploys: the agent reads the commit from RENDER_GIT_COMMIT")
+        elsif read(".do/app.yaml").to_s.include?("DEPLOYANGEL_REVISION")
+          Check.new(status: :ok, message: "The DigitalOcean app spec passes the commit in DEPLOYANGEL_REVISION")
+        elsif (dockerfile = read("Dockerfile"))
+          if dockerfile.include?("DEPLOYANGEL_REVISION")
+            Check.new(status: :ok, message: "The Dockerfile passes the commit in DEPLOYANGEL_REVISION")
+          else
+            # Platforms can pass it another way, so this is advice until the
+            # agent reports: then the release it names settles it.
+            Check.new(status: :info, message: "The Dockerfile doesn't set DEPLOYANGEL_REVISION; unless your platform passes the commit, " \
+              "releases won't be named by commit",
+              fix: "Run `deployangel install docker`, then build with --build-arg GIT_SHA=$(git rev-parse HEAD).")
+          end
+        elsif file?("Capfile")
+          Check.new(status: :ok, message: "Capistrano deploys: the agent reads the REVISION file Capistrano writes")
+        elsif file?("Procfile") || file?("app.json")
+          Check.new(status: :info, message: "On Heroku, turn on dyno metadata so the agent knows the commit",
+            fix: "heroku labs:enable runtime-dyno-metadata && heroku labs:enable runtime-dyno-build-metadata")
+        end
+      end
+
+      # Schedules in this checkout that the running agent hasn't reported:
+      # not deployed yet, or an agent too old to read them.
+      def comparison_checks
+        reported = setup&.dig("metadata", "schedules") or return []
+        return [] unless local_schedules.size > reported
+
+        [ Check.new(status: :warn, message: "This checkout declares #{count(local_schedules.size, "scheduled job")}; the running agent reported #{reported}",
+          fix: "Deploy this code, or update the agent: whenever schedules need deployangel 0.1.22 or later, GoodJob's 0.1.23.") ]
+      end
+
+      def local_schedules
+        @local_schedules ||= begin
+          config = Configuration.new({})
+          metadata = if file?("config/application.rb")
+            Rails::Metadata.new(app: nil, config: config, root: @root, environment: "production")
+          else
+            DeployAngel::Metadata.new(config: config, root: @root, environment: "production")
+          end
+          metadata.schedules
+        rescue StandardError, ScriptError
+          []
+        end
+      end
+
+      def hosts(processes)
+        names = processes.map { |process| process["processes"].to_i > 1 ? "#{process["host"]} ×#{process["processes"]}" : process["host"] }
+        total = processes.sum { |process| process["processes"].to_i }
+        listed = names.first(MAX_HOSTS).join(", ")
+        listed += ", and others" if names.size > MAX_HOSTS
+        "#{count(total, "process", "processes")} (#{listed})"
+      end
+
+      def time(iso)
+        Time.iso8601(iso).utc.strftime("%b %-d, %H:%M UTC")
+      rescue ArgumentError, TypeError
+        iso.to_s
+      end
+
+      def count(number, singular, plural = "#{singular}s")
+        "#{number.to_i} #{number.to_i == 1 ? singular : plural}"
+      end
+
+      def file?(relative) = File.file?(File.join(@root, relative))
+
+      def read(relative)
+        path = File.join(@root, relative)
+        File.read(path) if File.file?(path)
+      rescue SystemCallError
+        nil
+      end
+  end
+end

data/lib/deployangel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeployAngel
-  VERSION = "0.1.23"
+  VERSION = "0.1.25"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deployangel
 version: !ruby/object:Gem::Version
-  version: 0.1.23
+  version: 0.1.25
 platform: ruby
 authors:
 - Jordan Owens
@@ -46,6 +46,7 @@ files:
 - lib/deployangel/core/redaction.rb
 - lib/deployangel/core/release.rb
 - lib/deployangel/core/transport.rb
+- lib/deployangel/doctor.rb
 - lib/deployangel/exerciser.rb
 - lib/deployangel/fork_hook.rb
 - lib/deployangel/mcp.rb