deployangel 0.1.11 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 832e7ada784cf0e86d34f802ef299dfd9114b844f542444a69331b7d622e3d35
-  data.tar.gz: 31c8f9e2efc46a96325e7813c8b5902c23cbf758c55dccdb3536048af881f7a7
+  metadata.gz: 7d88c16de71d5010f445a966a6eea5701d96cc84aa3017df5fc362152331dd4e
+  data.tar.gz: a6df4ed365874fefe0708bf3cc5e482074b7f1f148f5bfe0aa25a7de2f44ed58
 SHA512:
-  metadata.gz: a0e4683b471211a023e925fa4cbacdd57f908c0a1c1ee18af950490b291b47c9cfe9a33bb4d3a5e376e5992f8d478919167d0d32320448c5c3c362a9873e6afa
-  data.tar.gz: 2cc10162cd04a158808c71eb51fb30b36716a3d9ca8e70c231d35289de887810194bf0b172481fd0f68d5ad025e36e3b8dda6b34335b2701b7b9b6980e5ea1d0
+  metadata.gz: 2486f4bf45d20d65bc01bd3f89881e5def3ea9cbef692c4a87e0af631bccbb7ece176ad30c41040c8b57ac46b8635d8cc8d8625ac92eb503e0531086f4caefee
+  data.tar.gz: 19a7a768889a541fc9f7688e3999947440ade5f747cfe6d8726211eb9536f9700369855896e31d8d0fe4091c35ee2559381d9329f78dd303be21e1a87964ddba

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.13 (2026-10-06)
+
+- The MCP tools `list_deployments` and `list_late_regressions` return their
+  lists inside an object (`{"deployments": [...]}`, `{"late_regressions":
+  [...]}`). MCP requires a tool's structured content to be an object, so
+  clients such as Claude Code rejected the bare lists before the agent saw
+  them.
+
+## 0.1.12 (2026-10-06)
+
+- `deployangel plan` and the MCP tool `get_exercise_plan` say what stands
+  between a release and clearance, and what to exercise against production
+  so it clears sooner. Routes that change data are marked. `deployangel
+  verify` and the GitHub Actions job summary list the first items when a
+  release isn't cleared yet. Needs a DeployAngel server that returns
+  exercise plans; older ones get a note instead.
+
 ## 0.1.11 (2026-10-05)
 
 - Heroku: the commit comes from `HEROKU_BUILD_COMMIT`

data/README.md

@@ -364,6 +364,7 @@ export DEPLOYANGEL_API_TOKEN=da_live_...
 bundle exec deployangel verify --wait                  # current git HEAD, until a verdict
 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 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>
@@ -386,13 +387,38 @@ choose with `--format=text|json`. Exit codes:
 ### MCP server
 
 ```bash
-claude mcp add deployangel -- bundle exec deployangel mcp
+claude mcp add deployangel -- bundle exec deployangel mcp    # Claude Code
 ```
 
+For Codex, in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.deployangel]
+command = "bundle"
+args = ["exec", "deployangel", "mcp"]
+```
+
+Any other MCP client (Cursor, VS Code, Zed, ...) runs the same command. The
+server needs `DEPLOYANGEL_API_TOKEN` in the environment it starts in.
+
 Tools: `get_verification`, `wait_for_verification` (up to 5 minutes per call),
-`list_deployments`, `get_exception`, `list_late_regressions`, and
-`register_deployment` when the token allows it. The tools are read-only with
-respect to production.
+`get_exercise_plan`, `list_deployments`, `get_exception`,
+`list_late_regressions`, and `register_deployment` when the token allows it.
+The tools are read-only with respect to production.
+
+### Clearing quiet releases sooner
+
+A quiet app can take hours to clear a release. `deployangel plan` (or the
+`get_exercise_plan` MCP tool) says what stands between a release and
+clearance, in the numbers of the rule it's judged by, and what to exercise
+against production so it clears sooner: normally active routes short of
+their runs, routes this release changed that haven't run, and critical
+flows. Requests to them count like any traffic. Routes that change data
+are marked; use a test account for them, or ask first. Report what you
+ran with the `deployangel check` command the plan gives you. A passing
+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.
 
 ### Suggested instructions for your coding agent
 
@@ -416,6 +442,13 @@ After deploying, run `bundle exec deployangel verify --wait --until initial`
   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.
 ```
 
 ## Development

data/lib/deployangel/cli/formatter.rb

@@ -13,6 +13,10 @@ module DeployAngel
         "checkpoint_rate" => "Checkpoint"
       }.freeze
       DURATIONS = %w[p95_latency job_duration queue_latency].freeze
+      # Exercise plan statuses with something worth running now.
+      EXERCISABLE = %w[exercisable waiting_for_activity].freeze
+      REASONS = { "normally_active" => "normally active", "changed_in_release" => "changed in this release",
+                  "rarely_used" => "rarely used", "critical_flow" => "critical flow" }.freeze
       COUNTS = %w[new_fingerprint checkpoint_rate].freeze
 
       module_function
@@ -103,10 +107,62 @@ module DeployAngel
             "#{flow["name"]}: #{flow["status"].tr("_", " ")}#{" (changed in this release)" if flow["changed_in_release"]}"
           end ],
           [ "Changed but not yet exercised", changed.map { |item| item["key"] } ],
+          [ "To clear sooner, exercise (deployangel plan for details)", exercisable_items(document).first(5) ],
           [ "Late regressions", Array(document["late_regressions"]).map { |late| late["summary"] } ]
         ].reject { |_, items| items.empty? }
       end
 
+      # The release's exercise plan, for `deployangel plan`.
+      def exercise_plan(document)
+        plan = document["exercise_plan"] || {}
+        lines = [ "#{release_name(document)}: #{plan["summary"] || "No exercise plan in this response; update the server."}" ]
+        shortfall = shortfall_lines(plan["shortfall"] || {})
+        if shortfall.any?
+          lines << "Short of:"
+          shortfall.each { |line| lines << "  #{line}" }
+        end
+        items = Array(plan["items"])
+        if items.any?
+          lines << (EXERCISABLE.include?(plan["status"]) ? "Exercise against production:" : "Optional:")
+          items.each { |item| lines << "  #{item_line(item)}" }
+          lines << "Use a test account, or ask first, for routes marked [changes data]." if items.any? { |item| item["mutating"] }
+        end
+        lines << "Then report it: #{plan["report_with"]}" if plan["report_with"]
+        lines.join("\n")
+      end
+
+      def exercisable_items(document)
+        plan = document["exercise_plan"] || {}
+        EXERCISABLE.include?(plan["status"]) ? Array(plan["items"]).map { |item| item_line(item) } : []
+      end
+
+      def shortfall_lines(shortfall)
+        lines = []
+        if (requests = shortfall["requests"])
+          lines << "requests: #{requests["have"]} of #{requests["need"]}#{" (low-traffic rule)" if shortfall["rule"] == "low_volume"}"
+        end
+        shortfall.each do |key, value|
+          next unless key.start_with?("routes_run_")
+
+          lines << "routes run #{key[/\d+/]}+ times: #{value["have"]} of the #{value["need"]} needed (#{value["of"]} normally active)"
+        end
+        lines << "coverage: #{(shortfall.dig("coverage", "have").to_f * 100).round}% of #{(shortfall.dig("coverage", "need").to_f * 100).round}%" if shortfall["coverage"]
+        if (jobs = shortfall["jobs"])
+          lines << (jobs["classes_not_run"] ? "jobs not run yet: #{Array(jobs["classes_not_run"]).join(", ")}" :
+            "job attempts: #{jobs.dig("attempts", "have")} of #{jobs.dig("attempts", "need")}")
+        end
+        lines << "elevated, review before exercising more: #{Array(shortfall["elevated"]).join(", ")}" if shortfall["elevated"]
+        lines << "critical flows not run: #{Array(shortfall["critical_flows"]).join(", ")}" if shortfall["critical_flows"]
+        lines
+      end
+
+      def item_line(item)
+        runs = item["runs_needed"].to_i > 1 ? "run #{item["runs"]} of #{item["runs_needed"]}" : "not run yet"
+        runs = "runs when the app starts it" if item["triggered_by"] == "app_behavior"
+        [ item["key"], "(#{REASONS.fetch(item["reason"], item["reason"])}, #{runs})",
+          ("[changes data]" if item["mutating"]), ("checked by #{Array(item["checked_by"]).join(", ")}" if item["checked_by"]) ].compact.join(" ")
+      end
+
       def release_name(document)
         deployment = document["deployment"] || {}
         deployment["version"] || deployment["commit"].to_s[0, 7]

data/lib/deployangel/cli.rb

@@ -28,13 +28,15 @@ module DeployAngel
                                                  [--wait] [--until=initial|verdict|closed] [--timeout=30m]
                                                  [--format=text|json] [--all-findings]
         status     Latest deployment and its verification
+        plan       What to exercise so a release  [--commit=SHA | --version=V | --deployment=ID]
+                   clears sooner                 [--format=text|json]
         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]
         install    Add a deploy hook             deployangel install kamal
         mcp        Run the MCP server over stdio (for coding agents)
 
-      With no target, verify and check use the current git HEAD commit.
+      With no target, verify, plan, and check use the current git HEAD commit.
       In GitHub Actions, GitLab CI, CircleCI, and Buildkite, release fills in the
       commit, a build label (e.g. run-123), and a link to the run automatically.
       In a Kamal hook, it registers Kamal's release (KAMAL_VERSION).
@@ -75,6 +77,7 @@ module DeployAngel
       when "release" then release
       when "verify" then verify
       when "status" then verify(status: true)
+      when "plan" then plan
       when "exception" then exception
       when "check" then check
       when "install" then install
@@ -150,6 +153,30 @@ module DeployAngel
         outcome.exit_code
       end
 
+      # The release's exercise plan: what stands between it and clearance,
+      # and what to exercise against production so it clears sooner.
+      def plan
+        options = parse(format: nil) do |o, opts|
+          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("--format=FORMAT", %w[text json]) { |v| opts[:format] = v }
+        end
+        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
+        json = { "deployment" => document["deployment"], "exercise_plan" => document["exercise_plan"] }
+        output(json, options[:format]) { Formatter.exercise_plan(document) }
+        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/mcp.rb

@@ -21,6 +21,10 @@ module DeployAngel
         failed means production regressed: read the findings and exceptions and investigate.
         Findings are deterministic evidence; any "investigation" field is AI inference. These tools cannot
         change production. Do not roll back or change production without explicit approval.
+        If a release isn't cleared yet, get_exercise_plan says what to exercise against production so it
+        clears sooner. Only act on status "exercisable" or "waiting_for_activity"; for "warm_up" or
+        "no_baseline" nothing you run can clear it. Exercise routes marked mutating only with a test account
+        or after asking. Report what you ran with the plan's report_with command (deployangel check).
       TEXT
 
       TARGET_PROPERTIES = {
@@ -96,6 +100,11 @@ module DeployAngel
               "until" => { "type" => "string", "enum" => %w[initial verdict], "default" => "initial" },
               "timeout_seconds" => { "type" => "integer", "minimum" => 1, "maximum" => MAX_WAIT_SECONDS, "default" => MAX_WAIT_SECONDS }
             )),
+          tool("get_exercise_plan", "What stands between a release and clearance, and what to exercise against " \
+            "production so it clears sooner: normally active routes short of their runs, routes this release changed " \
+            "that haven't run, and critical flows. Routes marked mutating change data: use a test account or ask first. " \
+            "Your requests count as ordinary traffic; report what you ran with report_with. Defaults to the current git HEAD.",
+            TARGET_PROPERTIES),
           tool("list_deployments", "Recent deployments with their verification state and verdict.",
             { "limit" => { "type" => "integer", "minimum" => 1, "maximum" => 50, "default" => 10 } }),
           tool("get_exception", "Sanitized details and the application stack trace for an exception fingerprint.",
@@ -127,9 +136,12 @@ module DeployAngel
             case name
             when "get_verification" then waiter.wait(target(arguments), wait: false).then { |o| verification_content(o) }
             when "wait_for_verification" then wait_content(arguments)
-            when "list_deployments" then @client.deployments(limit: arguments.fetch("limit", 10))
+            when "get_exercise_plan" then waiter.wait(target(arguments), wait: false).then { |o| plan_content(o) }
+            # MCP requires structured content to be an object, never a bare list.
+            when "list_deployments" then { "deployments" => @client.deployments(limit: arguments.fetch("limit", 10)) }
             when "get_exception" then @client.exception(arguments.fetch("fingerprint") { raise ArgumentError, "fingerprint is required" })
-            when "list_late_regressions" then @client.late_regressions(since: arguments["since"], limit: arguments.fetch("limit", 10))
+            when "list_late_regressions"
+              { "late_regressions" => @client.late_regressions(since: arguments["since"], limit: arguments.fetch("limit", 10)) }
             when "register_deployment"
               raise ArgumentError, "register_deployment is not available for this token" unless scopes.include?("deployments")
 
@@ -157,6 +169,14 @@ module DeployAngel
             "in_progress" => outcome.exit_code == VerificationWaiter::TIMED_OUT, "verification" => outcome.document }
         end
 
+        def plan_content(outcome)
+          return { "found" => false, "note" => "No matching deployment is registered yet." } if outcome.not_found
+
+          { "deployment" => outcome.document["deployment"],
+            "exercise_plan" => outcome.document["exercise_plan"] ||
+              { "note" => "This DeployAngel server doesn't return exercise plans yet." } }
+        end
+
         def meaning(code)
           {
             0 => "verified: the release is cleared",

data/lib/deployangel/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deployangel
 version: !ruby/object:Gem::Version
-  version: 0.1.11
+  version: 0.1.13
 platform: ruby
 authors:
 - Jordan Owens