deployangel 0.1.0

data/lib/deployangel/capistrano/tasks.rake

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Loaded by `require "deployangel/capistrano"`. Settings (config/deploy.rb):
+#
+#   set :deployangel_api_token, ENV["DEPLOYANGEL_API_TOKEN"]  # a "CI deploys" token
+#   set :deployangel_version, -> { fetch(:release_timestamp) } # label; nil to use the commit
+#   set :deployangel_wait, false       # or "initial" / "verdict" to wait after deploying
+#   set :deployangel_wait_timeout, "15m"
+#   set :deployangel_url, nil          # defaults to https://api.deployangel.com
+#   set :deployangel_register, true    # false to turn the integration off (e.g. per stage)
+
+namespace :load do
+  task :defaults do
+    set :deployangel_register, true
+    set :deployangel_api_token, -> { ENV["DEPLOYANGEL_API_TOKEN"] }
+    set :deployangel_version, -> { fetch(:release_timestamp) }
+    set :deployangel_wait, false
+    set :deployangel_wait_timeout, "15m"
+    set :deployangel_url, -> { ENV["DEPLOYANGEL_URL"] }
+  end
+end
+
+namespace :deployangel do
+  desc "Register this release with DeployAngel so it gets a verdict"
+  task :register do
+    next unless fetch(:deployangel_register)
+
+    run_locally do
+      outcome, message = DeployAngel::Capistrano::Steps.register(token: fetch(:deployangel_api_token),
+        commit: fetch(:current_revision), version: fetch(:deployangel_version), endpoint: fetch(:deployangel_url))
+      outcome == :ok ? info(message) : warn(message)
+    end
+  end
+
+  desc "Wait for DeployAngel's verdict on this release (set :deployangel_wait to enable)"
+  task :verify do
+    mode = fetch(:deployangel_wait)
+    next unless fetch(:deployangel_register) && mode
+
+    run_locally do
+      outcome, message = DeployAngel::Capistrano::Steps.verify(token: fetch(:deployangel_api_token),
+        commit: fetch(:current_revision), until_mode: mode.to_s, timeout: fetch(:deployangel_wait_timeout),
+        endpoint: fetch(:deployangel_url))
+      case outcome
+      when :ok then info(message)
+      when :warn then warn(message)
+      else raise message
+      end
+    end
+  end
+end
+
+after "deploy:published", "deployangel:register"
+after "deploy:finished", "deployangel:verify"

data/lib/deployangel/capistrano.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Capistrano integration. Add to the Capfile:
+#
+#   require "deployangel/capistrano"
+#
+# After each deploy is published, the release is registered with
+# DeployAngel from the machine running `cap`, which needs a "CI deploys"
+# token in DEPLOYANGEL_API_TOKEN. See lib/deployangel/capistrano/tasks.rake
+# for the settings.
+require_relative "capistrano/steps"
+
+load File.expand_path("capistrano/tasks.rake", __dir__)

data/lib/deployangel/ci_environment.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "core/release"
+
+module DeployAngel
+  # Recognizes common CI systems from their environment variables so
+  # `deployangel release` needs no arguments there: the commit, a build
+  # label, the provider, and a link back to the run. Inside a Kamal hook,
+  # the release is Kamal's, linked to the CI run when Kamal runs in CI.
+  class CiEnvironment < Struct.new(:provider, :commit, :version, :source_url)
+    def self.detect(env = ENV)
+      ci = detect_ci(env)
+      return ci unless present?(env["KAMAL_VERSION"])
+
+      release = Release.kamal(env["KAMAL_VERSION"])
+      new("kamal", release.commit, release.version, ci&.source_url)
+    end
+
+    def self.detect_ci(env)
+      if env["GITHUB_ACTIONS"] == "true"
+        run_url = "#{env["GITHUB_SERVER_URL"]}/#{env["GITHUB_REPOSITORY"]}/actions/runs/#{env["GITHUB_RUN_ID"]}" if env["GITHUB_RUN_ID"]
+        new("github_actions", env["GITHUB_SHA"], label("run", env["GITHUB_RUN_NUMBER"]), run_url)
+      elsif env["GITLAB_CI"] == "true"
+        new("gitlab_ci", env["CI_COMMIT_SHA"], label("pipeline", env["CI_PIPELINE_IID"]), env["CI_PIPELINE_URL"])
+      elsif env["CIRCLECI"] == "true"
+        new("circleci", env["CIRCLE_SHA1"], label("build", env["CIRCLE_BUILD_NUM"]), env["CIRCLE_BUILD_URL"])
+      elsif env["BUILDKITE"] == "true"
+        new("buildkite", env["BUILDKITE_COMMIT"], label("build", env["BUILDKITE_BUILD_NUMBER"]), env["BUILDKITE_BUILD_URL"])
+      end
+    end
+
+    def self.label(prefix, number)
+      "#{prefix}-#{number}" unless number.to_s.strip.empty?
+    end
+
+    def self.present?(value)
+      !value.to_s.strip.empty?
+    end
+
+    # Only https links are kept; the cloud rejects anything else.
+    def source_url
+      url = self[:source_url].to_s
+      url.start_with?("https://") ? url : nil
+    end
+  end
+end

data/lib/deployangel/cli/formatter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  class CLI
+    # Plain-text rendering of the verdict document for people. Everything
+    # shown comes from the document; nothing is inferred here.
+    module Formatter
+      LABELS = {
+        "http_5xx_rate" => "HTTP 5xx rate", "route_5xx_rate" => "Route 5xx rate", "p95_latency" => "p95 latency",
+        "job_failure_rate" => "Job failure rate", "job_duration" => "Job duration p95", "queue_latency" => "Queue latency p95",
+        "new_fingerprint" => "New exception", "fingerprint_amplification" => "Exception amplification",
+        "missing_recurring_job" => "Recurring job", "first_use_failure" => "First-use failure", "external_check" => "External check",
+        "checkpoint_rate" => "Checkpoint"
+      }.freeze
+      DURATIONS = %w[p95_latency job_duration queue_latency].freeze
+      COUNTS = %w[new_fingerprint checkpoint_rate].freeze
+
+      module_function
+
+      def verification(document)
+        v = document["verification"] || {}
+        clearance = document["clearance"] || {}
+        lines = [ clearance["statement"] || document["summary"] ]
+        lines << [ "State: #{v["state"]}", ("Verdict: #{v["verdict"]}" if v["verdict"]),
+                   ("Confidence: #{v["confidence"]}" if v["confidence"]),
+                   ("Coverage: #{(v["coverage"] * 100).round}%" if v["coverage"]) ].compact.join(" · ")
+        if (check = v["initial_check"]) && v["verdict"].nil?
+          lines << "Initial check: #{check["result"].tr("_", " ")}. Not cleared yet."
+        end
+        lines << "Expected clearance: #{v["expected_clearance_at"]}" if v["expected_clearance_at"] && v["verdict"].nil?
+        if (source = document.dig("deployment", "promoted_from"))
+          outcome = { "verified" => "cleared", "failed" => "failed", "inconclusive" => "not cleared" }.fetch(source["verdict"], "still verifying")
+          lines << "Promoted from #{source["environment"]} #{source["version"] || source["commit"].to_s[0, 7]} (#{outcome})"
+        end
+
+        findings = Array(document["findings"])
+        problems = findings.select { |f| %w[failing warning].include?(f["status"]) }
+        if problems.any?
+          lines << "Findings:"
+          problems.each { |f| lines << "  #{f["status"].ljust(8)} #{finding_line(f)}" }
+        end
+        gathering = findings.count { |f| f["status"] == "insufficient_data" }
+        lines << "#{gathering} signal#{"s" unless gathering == 1} still gathering data (--format=json for details)" if gathering.positive?
+        section(lines, "New exceptions", Array(document["exceptions"])) do |e|
+          "#{e["exception_class"]} in #{e["top_frame"]} (#{e["count"]}x)#{" #{e["sources"].keys.join(", ")}" if e["sources"].is_a?(Hash) && e["sources"].any?}"
+        end
+        unless v["verdict"] == "failed"
+          section(lines, "Missing evidence", Array(clearance["missing_evidence"])) { |item| item }
+        end
+        section(lines, "Not observable", Array(clearance["not_observable"])) { |item| "#{item["label"]} (#{item["reason"]})" }
+        section(lines, "Still watching", Array(clearance["still_watching"])) { |e| "#{e["job_class"]} (expected by #{e["expected_by"]})" }
+        section(lines, "Critical flows", Array(document["critical_flows"])) do |flow|
+          "#{flow["name"]}: #{flow["status"].tr("_", " ")}#{" (changed in this release)" if flow["changed_in_release"]}"
+        end
+        changed = Array(document["rare_items_pending"]).select { |item| item["changed_in_release"] == "changed" }
+        section(lines, "Changed but not yet exercised", changed) { |item| item["key"] }
+        section(lines, "Late regressions", Array(document["late_regressions"])) { |late| late["summary"] }
+        lines << document["dashboard_url"] if document["dashboard_url"]
+        lines.compact.join("\n")
+      end
+
+      def exception(details)
+        [ "#{details["exception_class"]}: #{details["message"]}",
+          "Fingerprint #{details["fingerprint"]} · first seen #{details["first_seen_at"]} (#{details["first_seen_release"]})",
+          "#{details["occurrences_last_24h"]} occurrences in the last 24 hours",
+          *Array(details["backtrace"]).map { |frame| "  #{frame}" } ].join("\n")
+      end
+
+      def finding_line(finding)
+        label = "#{LABELS.fetch(finding["signal"], finding["signal"])} on #{finding["scope"]}"
+        if COUNTS.include?(finding["signal"])
+          "#{label}: #{finding["observed_value"].to_i} occurrences"
+        elsif finding["baseline_value"].nil? && finding["observed_value"].nil?
+          "#{label}: #{finding["threshold"]}"
+        else
+          "#{label}: #{value(finding, finding["baseline_value"])} -> #{value(finding, finding["observed_value"])}" \
+            "#{" (#{finding["observed_n"]} samples)" if finding["observed_n"]}"
+        end
+      end
+
+      def section(lines, title, items)
+        return if items.empty?
+
+        lines << "#{title}:"
+        items.each { |item| lines << "  #{yield(item)}" }
+      end
+
+      def value(finding, raw)
+        return "n/a" if raw.nil?
+        return raw.to_i.to_s if COUNTS.include?(finding["signal"])
+
+        DURATIONS.include?(finding["signal"]) ? "#{raw.to_f.round} ms" : "#{(raw.to_f * 100).round(2)}%"
+      end
+    end
+  end
+end

data/lib/deployangel/cli.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "optparse"
+
+require_relative "version"
+require_relative "configuration"
+require_relative "client"
+require_relative "ci_environment"
+require_relative "verification_waiter"
+require_relative "cli/formatter"
+
+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
+
+    HELP = <<~TEXT
+      Usage: deployangel <command> [options]
+
+        release    Register a deployment        [--commit=SHA] [--version=V] [--kind=code]
+                                                 [--provider=P] [--url=RUN_URL]
+        verify     Report or wait for a verdict  [--commit=SHA | --version=V | --deployment=ID]
+                                                 [--wait] [--until=initial|verdict|closed] [--timeout=30m]
+                                                 [--format=text|json] [--all-findings]
+        status     Latest deployment and its verification
+        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.
+      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).
+      Environment: DEPLOYANGEL_API_TOKEN (required), DEPLOYANGEL_URL (default #{Configuration::DEFAULT_ENDPOINT})
+
+      Exit codes: 0 verified, 1 failed, 2 inconclusive, 3 still in progress / timed out,
+                  4 deployment not found, 5 usage, auth, or network error,
+                  6 initial check: no problems so far (NOT cleared), 7 initial check: warnings (NOT cleared)
+    TEXT
+
+    # Registers each Kamal deploy. It runs where `kamal deploy` runs, and
+    # never fails a deploy that has already shipped.
+    KAMAL_HOOK = <<~SH
+      #!/bin/sh
+      # Registers each deploy with DeployAngel, which then verifies it in
+      # production. Needs a "CI deploys" token in DEPLOYANGEL_API_TOKEN where
+      # you run `kamal deploy`. Added by `deployangel install kamal`.
+      bundle exec deployangel release || true
+    SH
+
+    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)
+      @root = root
+      @argv = argv.dup
+      @env = env
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @client = client
+      @sleeper = sleeper
+      @clock = clock
+      @git_head = git_head
+    end
+
+    def run
+      command = @argv.shift
+      case command
+      when "release" then release
+      when "verify" then verify
+      when "status" then verify(status: true)
+      when "exception" then exception
+      when "check" then check
+      when "install" then install
+      when "mcp" then mcp
+      when "version", "--version", "-v" then @stdout.puts(DeployAngel::VERSION) || 0
+      when nil, "help", "--help", "-h" then @stdout.puts(HELP) || 0
+      else usage_error("unknown command: #{command}")
+      end
+    rescue OptionParser::ParseError => e
+      usage_error(e.message)
+    rescue Client::Unauthorized => e
+      @stderr.puts("deployangel: #{e.message}")
+      USAGE_ERROR
+    rescue Client::NotFound => e
+      @stderr.puts("deployangel: #{e.message}")
+      VerificationWaiter::NOT_FOUND
+    rescue Client::Error => e
+      @stderr.puts("deployangel: #{e.message}")
+      USAGE_ERROR
+    end
+
+    private
+      def release
+        options = parse(commit: nil, version: nil, kind: nil, provider: nil, source_url: nil) do |o, opts|
+          o.on("--commit=SHA") { |v| opts[:commit] = v }
+          o.on("--version=VERSION") { |v| opts[:version] = v }
+          o.on("--kind=KIND") { |v| opts[:kind] = v }
+          o.on("--provider=PROVIDER") { |v| opts[:provider] = v }
+          o.on("--url=URL") { |v| opts[:source_url] = v }
+        end
+        # Explicit options win, then the CI system, then git.
+        if (ci = CiEnvironment.detect(@env))
+          options[:commit] ||= ci.commit
+          options[:version] ||= ci.version
+          options[:provider] ||= ci.provider
+          options[:source_url] ||= ci.source_url
+        end
+        options[:commit] ||= git_head
+        return usage_error("release needs --commit or --version (no git repository or CI commit found)") unless options[:commit] || options[:version]
+
+        deployment = client.register_deployment(**options)
+        @stdout.puts("Registered deployment #{deployment["id"]} (#{deployment["version"] || deployment["commit"]}), verification #{deployment["state"]}")
+        0
+      end
+
+      def verify(status: false)
+        options = parse(until_mode: "verdict", timeout: 1800, wait: false, format: nil, all_findings: false) 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("--wait") { opts[:wait] = true }
+          o.on("--until=MODE", VerificationWaiter::UNTIL_MODES) { |v| opts[:until_mode] = v }
+          o.on("--timeout=DURATION") { |v| opts[:timeout] = parse_duration(v) }
+          o.on("--format=FORMAT", %w[text json]) { |v| opts[:format] = v }
+          o.on("--all-findings") { opts[:all_findings] = true }
+        end
+        target = status ? { latest: true } : target_from(options)
+        return usage_error("no target: pass --commit, --version, or --deployment, or run inside a git repository") unless target
+
+        waiter = VerificationWaiter.new(client: client, sleeper: @sleeper, clock: @clock,
+          on_progress: ->(message) { @stderr.puts(message) if options[:wait] })
+        outcome = waiter.wait(target, until_mode: options[:until_mode], timeout: options[:timeout], wait: options[:wait])
+        if outcome.not_found
+          @stderr.puts("deployangel: no deployment found for #{target.values.first}")
+          return outcome.exit_code
+        end
+
+        document = options[:all_findings] ? client.verification(outcome.document.dig("deployment", "id"), all_findings: true) : outcome.document
+        output(document, options[:format]) { Formatter.verification(document) }
+        @stderr.puts("deployangel: timed out; verification is still in progress") if outcome.timed_out
+        outcome.exit_code
+      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]
+        details = client.exception(fingerprint)
+        output(details, format) { Formatter.exception(details) }
+        0
+      end
+
+      def check
+        options = parse(name: nil, status: nil, covers: [], details_url: nil) do |o, opts|
+          o.on("--name=NAME") { |v| opts[:name] = v }
+          o.on("--status=STATUS", %w[pass fail]) { |v| opts[:status] = v }
+          o.on("--covers=LIST") { |v| opts[:covers] = v.split(",").map(&:strip) }
+          o.on("--details-url=URL") { |v| opts[:details_url] = v }
+          o.on("--commit=SHA") { |v| opts[:commit] = v }
+          o.on("--deployment=ID") { |v| opts[:deployment_id] = v }
+        end
+        return usage_error("check needs --name and --status=pass|fail") unless options[:name] && options[:status]
+
+        commit = options[:commit] || (git_head || CiEnvironment.detect(@env)&.commit unless options[:deployment_id])
+        reference = options[:deployment_id] || (commit && "commit:#{commit}")
+        return usage_error("check needs --deployment or --commit, or a git repository") unless reference
+
+        result = client.report_check(reference, name: options[:name], status: options[:status],
+          covers: options[:covers], details_url: options[:details_url])
+        @stdout.puts("Recorded #{options[:status]} check \"#{options[:name]}\" for deployment #{result["deployment_id"]}")
+        0
+      end
+
+      # Writes .kamal/hooks/post-deploy, or says what to add to a hook that
+      # already exists, rather than overwriting it.
+      def install
+        target = @argv.shift
+        return usage_error("install needs a target: deployangel install kamal") unless target == "kamal"
+
+        relative = File.join(".kamal", "hooks", "post-deploy")
+        path = File.join(@root, relative)
+        if File.exist?(path)
+          if File.read(path).include?("deployangel release")
+            @stdout.puts("#{relative} already registers deploys with DeployAngel.")
+          else
+            @stdout.puts("#{relative} already exists. Add this line to it:", "", "  bundle exec deployangel release || true")
+          end
+          return 0
+        end
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, KAMAL_HOOK)
+        File.chmod(0o755, path)
+        @stdout.puts("Created #{relative}. Each `kamal deploy` now registers its release with DeployAngel.",
+          "Set DEPLOYANGEL_API_TOKEN (a \"CI deploys\" token) wherever you run kamal deploy.")
+        0
+      end
+
+      def mcp
+        require_relative "mcp"
+        MCP::Server.new(client: client, input: @stdin, output: @stdout, error_output: @stderr,
+          sleeper: @sleeper, clock: @clock, git_head: method(:git_head)).run
+        0
+      end
+
+      def parse(defaults)
+        options = defaults.dup
+        OptionParser.new { |o| yield(o, options) }.parse!(@argv)
+        options
+      end
+
+      def target_from(options)
+        return { deployment_id: options[:deployment_id] } if options[:deployment_id]
+        return { version: options[:version] } if options[:version]
+
+        commit = options[:commit] || git_head || CiEnvironment.detect(@env)&.commit
+        { commit: commit.downcase } if commit
+      end
+
+      def output(document, format = nil)
+        format ||= @stdout.tty? ? "text" : "json"
+        @stdout.puts(format == "json" ? JSON.pretty_generate(document) : yield)
+      end
+
+      def parse_duration(value)
+        match = value.to_s.match(/\A(\d+)(s|m|h)?\z/) or raise OptionParser::InvalidArgument, "--timeout=#{value}"
+        match[1].to_i * { nil => 1, "s" => 1, "m" => 60, "h" => 3600 }.fetch(match[2])
+      end
+
+      def git_head
+        return @git_head if @git_head
+        return nil if @git_head == false
+
+        output, status = Open3.capture2("git", "rev-parse", "HEAD", err: File::NULL)
+        status.success? ? output.strip : nil
+      rescue SystemCallError
+        nil
+      end
+
+      def client
+        @client ||= Client.new(token: @env["DEPLOYANGEL_API_TOKEN"],
+          endpoint: @env["DEPLOYANGEL_URL"] || Configuration::DEFAULT_ENDPOINT)
+      end
+
+      def usage_error(message)
+        @stderr.puts("deployangel: #{message}")
+        @stderr.puts("Run `deployangel help` for usage.")
+        USAGE_ERROR
+      end
+  end
+end

data/lib/deployangel/client.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module DeployAngel
+  # Read and registration API client for the CLI and MCP server.
+  # Unlike the agent's Transport, errors raise, because a person or coding
+  # agent is waiting on the answer.
+  class Client
+    class Error < StandardError
+      attr_reader :status
+
+      def initialize(message, status: nil)
+        super(message)
+        @status = status
+      end
+    end
+    class NotFound < Error; end
+    class Unauthorized < Error; end
+
+    attr_reader :endpoint
+
+    def initialize(token:, endpoint: Configuration::DEFAULT_ENDPOINT, timeout: 15)
+      raise Unauthorized, "DEPLOYANGEL_API_TOKEN is not set" if token.to_s.empty?
+
+      @token = token
+      @endpoint = endpoint.to_s.chomp("/")
+      @timeout = timeout
+    end
+
+    def token_info = get("/api/v1/token")
+    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)}")
+    def late_regressions(**filters) = get("/api/v1/late_regressions", filters.compact)["late_regressions"]
+
+    def verification(deployment_id, all_findings: false)
+      get("/api/v1/deployments/#{deployment_id}/verification", all_findings ? { findings: "all" } : {})
+    end
+
+    def register_deployment(commit: nil, version: nil, kind: nil, provider: nil, source_url: nil)
+      post("/api/v1/deployments", { commit: commit, version: version, kind: kind, provider: provider, source_url: source_url }.compact)
+    end
+
+    def report_check(deployment_ref, name:, status:, covers: [], details_url: nil)
+      post("/api/v1/deployments/#{URI.encode_www_form_component(deployment_ref)}/checks",
+        { name: name, status: status, covers: covers, details_url: details_url }.compact)
+    end
+
+    private
+      def get(path, params = {})
+        uri = URI("#{@endpoint}#{path}")
+        uri.query = URI.encode_www_form(params) if params.any?
+        request(Net::HTTP::Get.new(uri))
+      end
+
+      def post(path, body)
+        request = Net::HTTP::Post.new(URI("#{@endpoint}#{path}"))
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+        request(request)
+      end
+
+      def request(request)
+        request["Authorization"] = "Bearer #{@token}"
+        request["Accept"] = "application/json"
+        request["User-Agent"] = "deployangel-cli/#{DeployAngel::VERSION}"
+        uri = request.uri
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+          open_timeout: @timeout, read_timeout: @timeout) { |http| http.request(request) }
+        handle(response)
+      rescue Error
+        raise
+      rescue StandardError => e
+        raise Error, "could not reach #{@endpoint}: #{e.class}: #{e.message}"
+      end
+
+      def handle(response)
+        body = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+        case response.code.to_i
+        when 200..299 then body
+        when 404 then raise NotFound.new(body["error"] || "not found", status: 404)
+        when 401, 403 then raise Unauthorized.new(body["error"] || "unauthorized", status: response.code.to_i)
+        else raise Error.new(body["error"] || "HTTP #{response.code}", status: response.code.to_i)
+        end
+      rescue JSON::ParserError
+        raise Error.new("unexpected response (HTTP #{response.code})", status: response.code.to_i)
+      end
+  end
+end

data/lib/deployangel/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module DeployAngel
+  # Settings come from environment variables by default and can be
+  # overridden in code with DeployAngel.configure.
+  class Configuration
+    TRUE_VALUES = %w[1 true yes on].freeze
+    DEFAULT_ENDPOINT = "https://api.deployangel.com"
+
+    attr_accessor :token, :endpoint, :enabled, :environments, :release_version, :revision,
+      :flush_interval, :open_timeout, :read_timeout, :max_queued_payloads, :max_routes, :logger,
+      :file_digests, :critical_flows
+
+    def initialize(env = ENV)
+      @token = env["DEPLOYANGEL_TOKEN"]
+      @endpoint = env["DEPLOYANGEL_URL"] || DEFAULT_ENDPOINT
+      @enabled = parse_boolean(env["DEPLOYANGEL_ENABLED"])
+      @environments = %w[production]
+      @release_version = env["DEPLOYANGEL_RELEASE_VERSION"]
+      @revision = env["DEPLOYANGEL_REVISION"]
+      @flush_interval = 60
+      @open_timeout = 2
+      @read_timeout = 5
+      @max_queued_payloads = 10
+      @max_routes = 100
+      @logger = Logger.new($stderr, level: Logger::WARN, progname: "deployangel")
+      @file_digests = parse_boolean(env["DEPLOYANGEL_FILE_DIGESTS"]) != false
+      @critical_flows = {}
+    end
+
+    # Reports only with a token. By default only in the listed
+    # environments; DEPLOYANGEL_ENABLED forces it on or off.
+    def active?(environment)
+      return false if token.to_s.empty? || endpoint.to_s.empty?
+      return enabled unless enabled.nil?
+
+      environments.include?(environment.to_s)
+    end
+
+    private
+      def parse_boolean(value)
+        return nil if value.nil? || value.strip.empty?
+
+        TRUE_VALUES.include?(value.strip.downcase)
+      end
+  end
+end