deployangel 0.1.19 → 0.1.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf16d5f1c1214f77e3b72e911693d7e52efd852da3dcaa21308957d8789bbb63
-  data.tar.gz: 6957cf6b461965450428d49b7d12631bcd2431e7a71bdfd9d995de9b63bd8f0a
+  metadata.gz: 2a115a5a35d86c5edce65dad1cdf3947833416ea66f47c69da18b85de3047153
+  data.tar.gz: ec954e62605c6452d3e374896085343cb6a12910e0b821794342a2e0a6dc0426
 SHA512:
-  metadata.gz: f8eb73de68335aec60421c1e550c4983e1a1ffd0e93e27726ce75028d13245a4cc41ec3ea9193d4dbadb48a30eb6953e1bd41cac7837634cefea05bb9b2820f8
-  data.tar.gz: 2c910d0882a1c2bed0b0e4bf24dc8b238121702d1d77ae760d74e207050757795b60d054a7f5fa3a6a0b113ee10d736da344ed49db29dfb3f9f6cf76f1a9f766
+  metadata.gz: 4c18ca61ecff8936bdfa7f4a5900fd27b96c2a787094e504593fae78f62eaee3c7d4ea11e74811b619313c1a726bce8e4644f5a6319c687450ff81629acdd2a5
+  data.tar.gz: 2754b3cc315c626df0dc57de4723721caa668f69b7b523a0ca4eaecaf4f84e2f2ec7f9f40f366be34f9a1989ff3c9b4650f1d02dc81b976218d2b3daf5e3968c

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.21 (2026-10-09)
+
+- `deployangel exercise` stops requesting a page after its first 404, 405,
+  or 410, since a route table can list pages an app doesn't serve, and sends
+  that page's share to the pages that answered.
+
+## 0.1.20 (2026-10-09)
+
+- `deployangel exercise --url=<production URL>` sends a release's exercise
+  plan's read-only requests (GET routes without path parameters, at most
+  200, about 5 a second) so a quiet release can clear sooner, then records
+  what it sent on the release, which lists it as exercised from your side.
+  It skips and names routes that change data or need a path parameter.
+  `--dry-run` shows what it would send.
+- The agent instructions `deployangel install agents` writes now tell the
+  agent to run `deployangel exercise` when a release isn't cleared yet.
+
 ## 0.1.19 (2026-10-09)
 
 - `deployangel install agents` sets up Claude Code, Cursor, and Codex in a

data/README.md

@@ -392,6 +392,7 @@ bundle exec deployangel verify --wait                  # current git HEAD, until
 bundle exec deployangel verify --wait --until=initial  # return at the 15-minute initial check
 bundle exec deployangel status                         # latest deployment
 bundle exec deployangel plan                           # what to exercise so a release clears sooner
+bundle exec deployangel exercise --url=https://example.com  # send the plan's read-only requests
 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>
@@ -464,16 +465,28 @@ check labels what it covered; only the requests themselves count as
 evidence. A release deployed during an app's first 24 hours can't clear,
 so its plan lists nothing.
 
+`deployangel exercise --url=<production URL>` does the read-only part for
+you, from wherever it runs: it requests the plan's GET routes that have no
+path parameters, spreading any request shortfall across them (at most 200
+requests, about 5 a second, as `DeployAngel-Exercise`), then records what it
+sent on the release, where the page lists it under "Exercised from your
+side". It skips and names routes that change data or need a path
+parameter, and stops requesting a page after its first 404, sending its
+share to the pages that answered. A "CLI & coding agents" token can run
+it. `--dry-run` shows what it would send.
+
 ### Suggested instructions for your coding agent
 
 `deployangel install agents` adds instructions like these. To add them
 yourself, put this in your `CLAUDE.md` or `AGENTS.md`:
 
 ```markdown
-## Production verification
+## Production verification (DeployAngel)
 
-After deploying, run `bundle exec deployangel verify --wait --until initial`
-(or call the `wait_for_verification` MCP tool with `until: "initial"`).
+After deploying, or pushing a commit that deploys, wait for DeployAngel's
+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
   anything DeployAngel is still watching, then move on.
@@ -483,17 +496,16 @@ After deploying, run `bundle exec deployangel verify --wait --until initial`
 - Exit 7: warnings at the initial check. Report them and review the findings.
   The release is NOT cleared.
 - Exit 2 / inconclusive: the release is NOT verified. Do not claim success.
-- Exit 1 / failed: read the findings and exceptions, investigate the likely
-  cause, and propose a fix. Do not roll back or change production without
-  explicit approval.
+- Exit 1 / failed: read the findings and exceptions (`get_exception`),
+  investigate the likely cause, and propose a fix. Do not roll back or change
+  production without explicit approval.
 - Exit 3: still verifying; run the command again.
-- Not cleared yet and you can reach production: run
-  `bundle exec deployangel plan --format=json` (or `get_exercise_plan`). If
-  its status is "exercisable" or "waiting_for_activity", exercise the listed
-  items against production: read-only routes freely, routes marked mutating
-  only with a test account or after asking. Then run its `report_with`
-  command and wait again. If the status is "warm_up", don't exercise
-  anything: the release can't clear until DeployAngel has a day of history.
+- Not cleared yet: call `get_exercise_plan` (or `bundle exec deployangel plan`).
+  If its status is "exercisable" or "waiting_for_activity", run
+  `bundle exec deployangel exercise --url=<production URL>`: it sends the
+  plan's read-only requests and records them on the release. Offer to
+  exercise what it skips: routes that change data only with a test account
+  or after asking. If the status is "warm_up", nothing run can clear it.
 ```
 
 ## Development

data/lib/deployangel/cli.rb

@@ -11,13 +11,14 @@ require_relative "client"
 require_relative "ci_environment"
 require_relative "verification_waiter"
 require_relative "cli/formatter"
+require_relative "exerciser"
 
 module DeployAngel
   # `deployangel` command for developers, CI, and coding agents.
   # Runs without booting Rails.
   class CLI
     USAGE_ERROR = 5
-    COMMANDS = %w[release verify status exception check install mcp version help].freeze
+    COMMANDS = %w[release verify status plan exercise exception check install mcp version help].freeze
 
     HELP = <<~TEXT
       Usage: deployangel <command> [options]
@@ -30,6 +31,8 @@ module DeployAngel
         status     Latest deployment and its verification
         plan       What to exercise so a release  [--commit=SHA | --version=V | --deployment=ID]
                    clears sooner                 [--format=text|json]
+        exercise   Send the plan's read-only      --url=PRODUCTION_URL [--commit=SHA | --version=V | --deployment=ID]
+                   requests to production        [--max-requests=200] [--dry-run]
         exception  Details for a fingerprint     deployangel exception FINGERPRINT
         check      Report a smoke test result    --name=NAME --status=pass|fail [--covers=a,b]
                                                  [--commit=SHA | --deployment=ID] [--details-url=URL]
@@ -98,10 +101,11 @@ module DeployAngel
         production without explicit approval.
       - Exit 3: still verifying; run the command again.
       - Not cleared yet: call `get_exercise_plan` (or `bundle exec deployangel plan`).
-        If its status is "exercisable" or "waiting_for_activity", say what it lists
-        and offer to exercise it: read-only routes freely, routes marked mutating
-        only with a test account or after asking. If the status is "warm_up",
-        nothing run can clear it.
+        If its status is "exercisable" or "waiting_for_activity", run
+        `bundle exec deployangel exercise --url=<production URL>`: it sends the
+        plan's read-only requests and records them on the release. Offer to
+        exercise what it skips: routes that change data only with a test account
+        or after asking. If the status is "warm_up", nothing run can clear it.
       #{AGENTS_END}
     MARKDOWN
 
@@ -119,7 +123,7 @@ module DeployAngel
     DOCKERFILE
 
     def initialize(argv, env: ENV, stdin: $stdin, stdout: $stdout, stderr: $stderr, client: nil,
-                   sleeper: ->(seconds) { sleep(seconds) }, clock: -> { Time.now }, git_head: nil, root: Dir.pwd)
+                   sleeper: ->(seconds) { sleep(seconds) }, clock: -> { Time.now }, git_head: nil, root: Dir.pwd, requester: nil)
       @root = root
       @argv = argv.dup
       @env = env
@@ -130,6 +134,7 @@ module DeployAngel
       @sleeper = sleeper
       @clock = clock
       @git_head = git_head
+      @requester = requester
     end
 
     def run
@@ -139,6 +144,7 @@ module DeployAngel
       when "verify" then verify
       when "status" then verify(status: true)
       when "plan" then plan
+      when "exercise" then exercise
       when "exception" then exception
       when "check" then check
       when "install" then install
@@ -238,6 +244,56 @@ module DeployAngel
         0
       end
 
+      # Sends the plan's read-only requests from here, then records what it
+      # sent on the release (spec §16, Exercise records).
+      def exercise
+        options = parse(max_requests: Exerciser::MAX_REQUESTS, dry_run: false) do |o, opts|
+          o.on("--url=URL") { |v| opts[:url] = v }
+          o.on("--commit=SHA") { |v| opts[:commit] = v }
+          o.on("--version=VERSION") { |v| opts[:version] = v }
+          o.on("--deployment=ID") { |v| opts[:deployment_id] = v }
+          o.on("--max-requests=N", Integer) { |v| opts[:max_requests] = v }
+          o.on("--dry-run") { opts[:dry_run] = true }
+        end
+        return usage_error("exercise needs --url, the app's production URL, like https://example.com") unless options[:url].to_s.match?(%r{\Ahttps?://[^/\s]+})
+
+        target = target_from(options)
+        return usage_error("no target: pass --commit, --version, or --deployment, or run inside a git repository") unless target
+
+        outcome = VerificationWaiter.new(client: client, sleeper: @sleeper, clock: @clock).wait(target, wait: false)
+        if outcome.not_found
+          @stderr.puts("deployangel: no deployment found for #{target.values.first}")
+          return outcome.exit_code
+        end
+
+        document = outcome.document
+        plan = document["exercise_plan"] || {}
+        unless %w[exercisable waiting_for_activity].include?(plan["status"])
+          @stdout.puts("Nothing to exercise. #{plan["summary"]}".rstrip)
+          return 0
+        end
+
+        exerciser = Exerciser.new(base_url: options[:url], max_requests: options[:max_requests].clamp(1, Exerciser::MAX_REQUESTS),
+          sleeper: @sleeper, requester: @requester)
+        if options[:dry_run]
+          targets, skipped = exerciser.plan(plan)
+          @stdout.puts("Would send #{targets.sum(&:count)} requests:", *targets.map { |t| "  #{exerciser.url_for(t.path)} ×#{t.count}" })
+          @stdout.puts("Skipped:", *skipped.map { |s| "  #{s["key"]} (#{s["reason"]})" }) if skipped.any?
+          return 0
+        end
+
+        result = exerciser.run(plan)
+        @stdout.puts("Sent #{result.sent} requests to #{options[:url]}:",
+          *result.routes.map { |r| "  #{r["key"]} ×#{r["requests"]}: #{r["statuses"].map { |kind, n| "#{n} #{kind}" }.join(", ")}" })
+        @stdout.puts("Skipped:", *result.skipped.map { |s| "  #{s["key"]} (#{s["reason"]})" }) if result.skipped.any?
+        @stdout.puts("Stopped early: #{options[:url]} isn't answering.") if result.unreachable
+        if result.routes.any?
+          client.record_exercise(document.dig("deployment", "id"), routes: result.routes, skipped: result.skipped, ran_at: @clock.call.utc.iso8601)
+          @stdout.puts("Recorded on the release. Wait for the verdict with: deployangel verify --wait")
+        end
+        result.unreachable ? USAGE_ERROR : 0
+      end
+
       def exception
         fingerprint = @argv.shift or return usage_error("exception needs a FINGERPRINT")
         format = parse(format: nil) { |o, opts| o.on("--format=FORMAT", %w[text json]) { |v| opts[:format] = v } }[:format]

data/lib/deployangel/client.rb

@@ -49,6 +49,12 @@ module DeployAngel
         { name: name, status: status, covers: covers, details_url: details_url }.compact)
     end
 
+    # What `deployangel exercise` sent (spec §16, Exercise records). A
+    # "CLI & coding agents" token may record one: it only labels the release.
+    def record_exercise(deployment_id, routes:, skipped:, ran_at:)
+      post("/api/v1/deployments/#{deployment_id}/exercises", { routes: routes, skipped: skipped, ran_at: ran_at })
+    end
+
     private
       def get(path, params = {})
         uri = URI("#{@endpoint}#{path}")

data/lib/deployangel/exerciser.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module DeployAngel
+  # `deployangel exercise`: sends a release's exercise plan's read-only
+  # requests to production from the customer's side, then records what it
+  # sent, so the release page says which routes were exercised that way.
+  # Only GET routes with no path parameters and not marked as changing data;
+  # the rest are skipped and named, for the agent or a smoke test with a test
+  # account. The requests count like any traffic through the app's agent.
+  class Exerciser
+    MAX_REQUESTS = 200
+    INTERVAL = 0.2 # about 5 requests a second
+    TIMEOUT = 10
+    # Stop when the app isn't answering, rather than send the rest into it.
+    MAX_CONSECUTIVE_ERRORS = 5
+    # A route table can list pages an app doesn't serve, like the edit page
+    # of a resource that has none. One answer like this is enough to know.
+    NOT_SERVED = [ 404, 405, 410 ].freeze
+    # Rails' :id and *path, Django's <int:pk>, FastAPI's {id}.
+    PARAMETER = /\/[:*{<]/
+
+    Target = Struct.new(:key, :path, :count)
+    Result = Struct.new(:routes, :skipped, :sent, :unreachable, keyword_init: true)
+
+    def initialize(base_url:, max_requests: MAX_REQUESTS, sleeper: ->(seconds) { sleep(seconds) }, requester: nil)
+      @base = URI(base_url)
+      @max_requests = max_requests
+      @sleeper = sleeper
+      @requester = requester || method(:get)
+    end
+
+    # What would be sent: [targets, skipped].
+    def plan(exercise_plan)
+      skipped = []
+      targets = []
+      Array(exercise_plan["items"]).each do |item|
+        next unless item["kind"] == "route"
+
+        method, path = item["key"].to_s.split(" ", 2)
+        reason =
+          if item["mutating"] || method != "GET" then "changes data"
+          elsif path.nil? || path.match?(PARAMETER) then "needs a path parameter"
+          end
+        next skipped << { "key" => item["key"], "reason" => reason } if reason
+
+        needed = item["runs_needed"] ? item["runs_needed"].to_i - item["runs"].to_i : 1
+        targets << Target.new(item["key"], path, [ needed, 1 ].max)
+      end
+      spread_shortfall(targets, exercise_plan.dig("shortfall", "requests"))
+      cap(targets)
+      [ targets, skipped ]
+    end
+
+    # A route whose first request says it isn't served gets no more; its
+    # share goes to the routes that answered.
+    def run(exercise_plan)
+      targets, skipped = plan(exercise_plan)
+      @statuses = Hash.new { |hash, key| hash[key] = Hash.new(0) }
+      @sent = 0
+      @errors_in_a_row = 0
+      leftover = 0
+      answered = []
+      targets.each do |target|
+        target.count.times do |i|
+          break if unreachable?
+
+          status = send_request(target)
+          if i.zero? && NOT_SERVED.include?(status)
+            leftover += target.count - 1
+            break
+          end
+        end
+        answered << target if @statuses[target.key].keys.intersect?(%w[2xx 3xx])
+      end
+      leftover.times { |i| send_request(answered[i % answered.size]) unless unreachable? } if answered.any?
+
+      routes = targets.filter_map do |target|
+        statuses = @statuses.fetch(target.key, nil) or next
+        { "key" => target.key, "requests" => statuses.values.sum, "statuses" => statuses.to_h }
+      end
+      Result.new(routes: routes, skipped: skipped, sent: @sent, unreachable: unreachable?)
+    end
+
+    def url_for(path)
+      uri = @base.dup
+      uri.path = "#{@base.path.chomp("/")}#{path}"
+      uri.query = nil
+      uri.to_s
+    end
+
+    private
+      def send_request(target)
+        @sleeper.call(INTERVAL) if @sent.positive?
+        status = @requester.call(url_for(target.path))
+        @sent += 1
+        kind = status ? "#{status / 100}xx" : "error"
+        @statuses[target.key][kind] += 1
+        @errors_in_a_row = kind == "error" ? @errors_in_a_row + 1 : 0
+        status
+      end
+
+      def unreachable?
+        @errors_in_a_row >= MAX_CONSECUTIVE_ERRORS
+      end
+
+      # Requests the release is short of overall, spread across the routes,
+      # or sent to the home page when the plan names no route to send them to.
+      def spread_shortfall(targets, requests)
+        return unless requests
+
+        extra = requests["need"].to_i - requests["have"].to_i - targets.sum(&:count)
+        return unless extra.positive?
+
+        targets << Target.new("GET /", "/", 0) if targets.empty?
+        extra.times { |i| targets[i % targets.size].count += 1 }
+      end
+
+      def cap(targets)
+        targets.max_by(&:count).count -= 1 while targets.sum(&:count) > @max_requests
+      end
+
+      # The status code, or nil when there was no answer. Redirects aren't
+      # followed: the request already reached the app.
+      def get(url)
+        uri = URI(url)
+        request = Net::HTTP::Get.new(uri)
+        request["User-Agent"] = "DeployAngel-Exercise/#{DeployAngel::VERSION} (+https://www.deployangel.com/docs#exercise)"
+        request["Accept"] = "text/html,application/json;q=0.9,*/*;q=0.8"
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+          http.request(request).code.to_i
+        end
+      rescue StandardError
+        nil
+      end
+  end
+end

data/lib/deployangel/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deployangel
 version: !ruby/object:Gem::Version
-  version: 0.1.19
+  version: 0.1.21
 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/exerciser.rb
 - lib/deployangel/fork_hook.rb
 - lib/deployangel/mcp.rb
 - lib/deployangel/metadata.rb