onair-cli 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1faf09e85aa982fd64a664e4d1f566c4aaf836cc3f196cde37ef9477a42c498f
-  data.tar.gz: 41404044b99b5624b947bc726cefb8e85910622f95ff31b2419bd12c612b56bb
+  metadata.gz: e6929334a2f930a5e7e05e43067c8442ae9b85d3dc9967c960c4ff9c0e34ebc7
+  data.tar.gz: 4f029777e9e3ee5aabc3977ad930ba2cf35d82a4c5e9c76a0995197d250ae389
 SHA512:
-  metadata.gz: 2343601742f56a59b9141dd06d597f040ca1f55eae53295dd34dad9da10127372cb544b5bf9ff6bff98fdcaf1b2d938eab0e3ea0c9309f93ebd000da9a298566
-  data.tar.gz: 4ae9c7a4348ded957fb88a922cc44d8ebebeba36f6c870303663fe922be631bed2b2ac5ea82acbfc4ac2111bffdeefc0e8ac05c60e8dbb8d9068c51a33fb1eee
+  metadata.gz: c85de1face07ebb3c04cadc6001ac5e92edff4b3632f87f1f79158f212c3063761ee6efdfdf69709bfe09251b0d0c5271dec5aaa38291b84b3cc523f705d5f3e
+  data.tar.gz: 3325a141acd7f90491a2b9c547097acbd68b1eba14d72462d518e61e564923a6c5e332263eab7403f99a751bb7278acf47a0d98d2f010492267796ad797e0538

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-11-02
+
+- Dokku: `platform: dokku` with a `host:` reads the running commit from the
+  last `git push` over SSH. A running build shows as `Pending` and a build
+  that failed after the last success as `Failed`, both without a commit. The
+  rollout line counts containers per process type, and the window in which
+  the previous containers keep serving shows as an estimate.
+- Rows drop `v<version>` when the platform numbers no releases. `--json`
+  carries `null` versions and shas there, and `pending` gains `build_id`.
+
+## [0.3.0] - 2026-10-08
+
+- Heroku: a rollout line under Deployed counts the dynos of each process type
+  running the deployed release (`web 1/3, 2 starting`) and says when every
+  dyno is up on it. With preboot on, the handoff from the previous web dynos
+  shows as an estimate. `--json` gains a `rollout` object.
+
 ## [0.2.0] - 2026-10-07
 
 - Heroku: Deployed is the release Heroku is serving, not the newest one. A

data/README.md

@@ -42,8 +42,9 @@ case.
 gem install onair-cli
 ```
 
-Requires Ruby >= 3.2. Auth reuses the Heroku CLI's token from `~/.netrc`
-(written by `heroku login`), falling back to `heroku auth:token`.
+Requires Ruby >= 3.2. On Heroku, auth reuses the Heroku CLI's token from
+`~/.netrc` (written by `heroku login`), falling back to `heroku auth:token`.
+On Dokku, it reuses your SSH setup (see [Dokku](#dokku)).
 
 ## Usage
 
@@ -72,6 +73,12 @@ the API is a faster transport, never a cache.
   author, and a delta against `origin/main`: `★ current` or
   `↓ N commits behind`. If the relationship is unknown (diverged history,
   commits unavailable), no marker is shown - silence over speculation.
+- **Rollout** - under the Deployed row, how many dynos of each process type
+  run that release: `⟳ rolling out v1234: web 1/3, 2 starting` while dynos
+  restart, `✓ rolled out` once every dyno is up on it. With preboot on, the
+  previous web dynos keep serving for about three minutes after the new ones
+  are up; that window shows as an estimate. On Dokku it counts containers,
+  and the estimate is the app's wait-to-retire after the newest build.
 - **Pending** - an in-flight build that's about to replace the deploy.
 - **Releasing** - a newer release whose release phase (e.g. migrations) is
   still running; production still serves the Deployed row until it finishes.
@@ -94,7 +101,27 @@ branch: main         # comparison branch; default: main
 ```
 
 Resolution order: CLI flags → env vars (`HEROKU_APP`, `GITHUB_REPO`) →
-`.onair.yml`.
+`.onair.yml`. `HEROKU_APP` applies only with `platform: heroku`.
+
+### Dokku
+
+```yaml
+platform: dokku
+host: my-dokku   # any SSH destination: dokku@host, or a ~/.ssh/config alias
+app: myapp
+```
+
+onair runs `ssh -o BatchMode=yes <host> <command> <app> --format json` for
+Dokku's report commands, so it needs Dokku 0.38 or newer and an `ssh` client.
+The host must log in as Dokku's `dokku` user, directly or through an alias
+with `User dokku`. Keys, addresses and users come from your SSH config;
+`BatchMode` never prompts, so the key must be loadable without a passphrase
+prompt (`ssh-add`).
+
+The deployed commit is the one the last `git push` deployed. An app deployed
+another way (`git:from-image`, `git:sync`) shows the deploy source instead
+of a commit. Dokku builds record no commit, so `Pending` and `Failed` name
+the build, and pinned detection stays silent.
 
 ### Task links (optional)
 
@@ -130,6 +157,13 @@ additively:
   },
   "pending": null,
   "release": null,
+  "rollout": {
+    "version": 1234, "complete": true,
+    "processes": [
+      { "type": "web", "up": 3, "total": 3, "waiting": {}, "previous": 0 }
+    ],
+    "overlap_until": null
+  },
   "delta": { "status": "current", "behind_by": 0 },
   "pinned": null,
   "yours": null
@@ -137,12 +171,21 @@ additively:
 ```
 
 - `delta.status` is `"current"`, `"behind"`, or `"unknown"`.
-- `pending`: `{ "sha", "started_at", "subject", "author" }` when a build is
-  in flight.
+- `pending`: `{ "sha", "build_id", "started_at", "subject", "author" }` when
+  a build is in flight. On Dokku `sha` is `null` and `build_id` names the
+  build; on Heroku `build_id` is `null`.
+- `version` is `null` on platforms that number no releases (Dokku), and a
+  Dokku `release` is a failed build with a `null` sha.
 - `release`: `{ "sha", "version", "description", "status", "started_at",
   "subject", "author" }` when a release newer than the running one is not
   live; `status` is `"pending"` (release phase running) or `"failed"`. While
   it carries a different sha, `delta.status` is never `"current"`.
+- `rollout`: dynos per process type against the running release. `up`
+  counts dynos serving it, `waiting` counts the rest of its dynos by state
+  (`starting`, `crashed`, ...), `previous` counts dynos on an older release.
+  `overlap_until` is an estimated end of the preboot handoff while it lasts,
+  otherwise `null`. `complete` is true once every dyno serves the running
+  release and no handoff remains. `null` when the dynos can't be read.
 - `pinned`: `{ "version", "description", "latest_built_sha" }` when a newer
   build succeeded but is not running.
 - `yours`: `{ "sha", "had_own_build", "subject", "author" }` when your commit
@@ -155,7 +198,7 @@ additively:
 
 ```sh
 bundle install
-bundle exec rake        # specs + rubocop
+bundle exec rake        # specs + standard
 ```
 
 The behavioral source of truth is `reference/prod-release.sh`, the

data/lib/onair/cli.rb

@@ -64,16 +64,17 @@ module Onair
       git = Git.new(fetch_allowed: config.fetch)
       adapter = Platform.build(config)
       repo = config.repo || git.origin_repo
-      report = Orchestrator.new(config: config, adapter: adapter, git: git, repo: repo).run
+      now = Time.now
+      report = Orchestrator.new(config: config, adapter: adapter, git: git, repo: repo, now: now).run
 
       if flags[:json]
         puts Renderer::Json.new(report: report, app: config.app, platform: config.platform,
-                                branch: config.branch, repo: repo, task: config.task).render
+          branch: config.branch, repo: repo, task: config.task).render
       else
         tty = $stdout.tty?
         print Renderer::Tty.new(report: report, app: config.app, platform_label: adapter.display_name,
-                                branch: config.branch, repo: repo, task: config.task,
-                                color: tty && !no_color?, hyperlinks: tty, now: Time.now).render
+          branch: config.branch, repo: repo, task: config.task,
+          color: tty && !no_color?, hyperlinks: tty, now: now).render
       end
     end
 

data/lib/onair/config.rb

@@ -8,10 +8,13 @@ module Onair
   class Config
     FILENAME = ".onair.yml"
 
-    attr_reader :platform, :app, :repo, :branch, :fetch, :task
+    attr_reader :platform, :app, :repo, :branch, :fetch, :task, :host
 
-    def initialize(platform:, app:, repo:, branch:, fetch:, task: nil)
+    # `host` is the SSH destination for SSH-driven platforms (Dokku); nil
+    # elsewhere, and only the adapter that needs it checks it.
+    def initialize(platform:, app:, repo:, branch:, fetch:, task: nil, host: nil)
       @platform = platform
+      @host = host
       @app = app
       @repo = repo
       @branch = branch
@@ -21,16 +24,19 @@ module Onair
 
     def self.resolve(flags = {}, env: ENV, dir: Dir.pwd)
       file = find_file(dir) || {}
-      app = flags[:app] || env["HEROKU_APP"] || file["app"]
+      platform = file["platform"] || "heroku"
+      # HEROKU_APP names a Heroku app, so it must not redirect another platform.
+      app = flags[:app] || ((platform == "heroku") ? env["HEROKU_APP"] : nil) || file["app"]
       raise Error, "no app configured - pass --app NAME, set HEROKU_APP, or run `onair init`" if app.nil?
 
       new(
-        platform: file["platform"] || "heroku",
+        platform: platform,
         app: app,
         repo: env["GITHUB_REPO"] || file["repo"],
         branch: file["branch"] || "main",
         fetch: !flags[:no_fetch],
-        task: TaskLink.from_config(file["task"])
+        task: TaskLink.from_config(file["task"]),
+        host: file["host"]
       )
     end
 

data/lib/onair/git.rb

@@ -91,7 +91,7 @@ module Onair
     end
 
     def opts
-      @dir ? { chdir: @dir } : {}
+      @dir ? {chdir: @dir} : {}
     end
   end
 end

data/lib/onair/orchestrator.rb

@@ -4,11 +4,12 @@ module Onair
   # Runs the platform adapter and git concurrently, lazily fetches missing
   # commits at most once, and assembles the Report.
   class Orchestrator
-    def initialize(config:, adapter:, git:, repo: nil)
+    def initialize(config:, adapter:, git:, repo: nil, now: Time.now)
       @config = config
       @adapter = adapter
       @git = git
       @repo = repo
+      @now = now
     end
 
     def run
@@ -20,7 +21,7 @@ module Onair
       needed = [snapshot.deployed&.sha, snapshot.pending&.sha, snapshot.release&.sha, remote_head].compact
       @git.fetch_once! if needed.any? { |sha| !@git.has_commit?(sha) }
 
-      Report.build(snapshot: snapshot, remote_head: remote_head, git: @git)
+      Report.build(snapshot: snapshot, remote_head: remote_head, git: @git, now: @now)
     end
 
     private

data/lib/onair/platform/base.rb

@@ -13,7 +13,7 @@ module Onair
         klass = @registry[config.platform]
         if klass.nil?
           raise Error,
-                "unknown platform #{config.platform.inspect} (available: #{@registry.keys.join(', ')})"
+            "unknown platform #{config.platform.inspect} (available: #{@registry.keys.join(", ")})"
         end
 
         klass.new(config)
@@ -29,6 +29,12 @@ module Onair
     #                     running (release phase pending or failed), or nil
     #   latest_built_sha: newest successfully built sha, or nil
     #   succeeded_shas:   recent succeeded build shas, newest first
+    #   rollout:          per process type, how many dynos run the running
+    #                     release, plus an optional estimate of when the
+    #                     previous release stops serving; nil when unknown
+    #
+    # Versions may be nil on every value, and pending/release shas may be nil
+    # when the platform's builds carry no commit; renderers drop what is absent.
     #
     # Adapters own their internal concurrency and auth. Everything above
     # (delta, pinned, mine, rendering) is platform-agnostic and must not
@@ -45,6 +51,17 @@ module Onair
       def display_name
         self.class.name.split("::").last
       end
+
+      private
+
+      # Exceptions surface via #value; without this the dying thread also
+      # prints its own backtrace to stderr.
+      def quiet_thread(&block)
+        Thread.new do
+          Thread.current.report_on_exception = false
+          block.call
+        end
+      end
     end
   end
 end

data/lib/onair/platform/dokku.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+require "time"
+
+module Onair
+  module Platform
+    # Dokku has no HTTP API, so every read is `ssh <host> <subcommand> <app>
+    # --format json`, run in parallel. Keys, users and addresses come from the
+    # user's SSH setup; the adapter only knows the destination.
+    class Dokku < Base
+      GIT_PUSH = "git-push"
+      FULL_SHA = /\A\h{40}\z/
+      # Dokku app names: lowercase letters, digits and dashes.
+      APP_NAME = /\A[a-z0-9][a-z0-9-]*\z/
+      # ps:report's JSON lists one `status-<process>.<n>` entry per container
+      # (named after its CONTAINER.<process>.<n> file), valued like
+      # "running (CID: 0123456789a)". The text output's dash form also matches.
+      CONTAINER_STATUS = /\Astatus-(?<type>.+)[.-]\d+\z/
+      SERVING_STATE = "running"
+      # After a deploy, Dokku keeps the previous containers serving for the
+      # app's wait-to-retire, 60 seconds unless configured.
+      DEFAULT_WAIT_TO_RETIRE = 60
+      RETIRE_NOTE = "retiring: previous containers may still serve"
+      # Wall-clock limit per command, matching the Heroku adapter's read timeout.
+      COMMAND_TIMEOUT = 15
+      SSH_OPTIONS = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=5",
+        "-o", "ServerAliveInterval=5", "-o", "ServerAliveCountMax=3"].freeze
+
+      def snapshot
+        validate!
+        apps_thread = quiet_thread { dokku("apps:report") }
+        git_thread = quiet_thread { optional { dokku("git:report") } }
+        builds_thread = quiet_thread { optional { dokku("builds:list") } }
+        ps_thread = quiet_thread { optional { dokku("ps:report") } }
+        checks_thread = quiet_thread { optional { dokku("checks:report") } }
+
+        deployed = deployed(apps_thread.value, git_thread.value)
+        builds = Array(builds_thread.value).grep(Hash)
+        Snapshot.new(deployed: deployed, pending: pending(builds), release: failed(builds),
+          latest_built_sha: nil, succeeded_shas: [],
+          rollout: rollout(ps_thread.value, newest(builds, "succeeded"), checks_thread.value))
+      end
+
+      private
+
+      def host
+        @config.host
+      end
+
+      def app
+        @config.app
+      end
+
+      # The host and app go on the ssh command line, so a value starting with
+      # a dash would be read as an ssh option.
+      def validate!
+        raise Error, "no host configured - add `host:` to #{Config::FILENAME}" if host.to_s.empty?
+        raise Error, "invalid Dokku host #{host.inspect}" if host.start_with?("-")
+        raise Error, "invalid Dokku app name #{app.inspect}" unless APP_NAME.match?(app)
+      end
+
+      # Dokku strips the plugin prefix from report JSON keys, so git:report's
+      # `--git-last-updated-at` arrives as `last-updated-at`.
+      # Only a git push records the pushed commit. git:report's sha is not
+      # used: it can read the repo's HEAD rather than what was deployed.
+      def deployed(apps, git)
+        source = apps["deploy-source"].to_s
+        raise Error, "nothing deployed yet for app #{app}" if source.empty?
+
+        metadata = apps["deploy-source-metadata"].to_s
+        sha = (source == GIT_PUSH && FULL_SHA.match?(metadata)) ? metadata : nil
+        Deployed.new(sha: sha, version: nil, description: "deploy source: #{source}",
+          deployed_at: unix_time(git&.dig("last-updated-at")))
+      end
+
+      # Builds carry no commit, so the sha stays unknown until the build is
+      # correlated with the CI run that pushed it.
+      def pending(builds)
+        running = builds.find { |build| status(build) == "running" }
+        running && Pending.new(sha: nil, build_id: running["id"], started_at: parse_time(running["started_at"]))
+      end
+
+      # Only a failure newer than the last success matters; older failed
+      # records were superseded and are stale.
+      def failed(builds)
+        failure = newest(builds, "failed")
+        success = newest(builds, "succeeded")
+        return nil if failure.nil? || (success && started(success) >= started(failure))
+
+        Release.new(sha: nil, version: nil, description: "build #{failure["id"]}", status: :failed,
+          started_at: parse_time(failure["finished_at"]) || started(failure))
+      end
+
+      def newest(builds, wanted)
+        builds.select { |build| status(build) == wanted && started(build) }.max_by { |build| started(build) }
+      end
+
+      # display_status turns a running record whose process died into
+      # "abandoned"; older Dokku versions only report status.
+      def status(build)
+        build["display_status"] || build["status"]
+      end
+
+      def started(build)
+        parse_time(build["started_at"])
+      end
+
+      def rollout(ps, success, checks)
+        return nil unless ps.is_a?(Hash)
+
+        containers = ps.filter_map do |key, value|
+          match = CONTAINER_STATUS.match(key)
+          match && [match[:type], value.to_s.split(" ", 2).first.to_s]
+        end
+        return nil if containers.empty?
+
+        processes = containers.group_by(&:first)
+          .sort_by { |type, _| [(type == "web") ? 0 : 1, type] }
+          .map { |type, rows| process_rollout(type, rows.map(&:last)) }
+        Rollout.new(version: nil, processes: processes, overlap_note: RETIRE_NOTE,
+          overlap_until: retire_deadline(processes, success, checks))
+      end
+
+      # ps:report lists only the current deploy's containers, so nothing is
+      # ever counted as previous.
+      def process_rollout(type, states)
+        waiting = states.reject { |state| state == SERVING_STATE }.tally
+        ProcessRollout.new(type: type, total: states.size, up: states.size - waiting.values.sum,
+          waiting: waiting, previous: 0)
+      end
+
+      def retire_deadline(processes, success, checks)
+        finished = success && parse_time(success["finished_at"])
+        return nil if finished.nil? || !processes.all?(&:complete?)
+
+        finished + wait_to_retire(checks)
+      end
+
+      def wait_to_retire(checks)
+        Integer(checks&.dig("computed-wait-to-retire"), 10)
+      rescue ArgumentError, TypeError
+        DEFAULT_WAIT_TO_RETIRE
+      end
+
+      def optional
+        yield
+      rescue Error
+        nil
+      end
+
+      # Dokku prints warnings on stderr (e.g. "Skipping unreadable build
+      # record"), so only stdout is parsed.
+      def dokku(subcommand)
+        stdout, stderr, status = run(["ssh", *SSH_OPTIONS, host, subcommand, app, "--format", "json"])
+        raise Error, "dokku #{subcommand} timed out on #{host}" if status.nil?
+        raise Error, ssh_error(subcommand, stderr, status) unless status.success?
+
+        JSON.parse(stdout)
+      rescue Errno::ENOENT
+        raise Error, "ssh not found - the Dokku platform needs an ssh client on PATH"
+      rescue JSON::ParserError
+        raise Error, "Dokku returned invalid JSON for #{subcommand}"
+      end
+
+      # Returns [stdout, stderr, status], with a nil status when the command
+      # outlived the timeout and was killed.
+      def run(argv, timeout: COMMAND_TIMEOUT)
+        Open3.popen3(*argv) do |stdin, stdout, stderr, wait|
+          stdin.close
+          out = Thread.new { stdout.read }
+          err = Thread.new { stderr.read }
+          unless wait.join(timeout)
+            begin
+              Process.kill("KILL", wait.pid)
+            rescue Errno::ESRCH
+              nil
+            end
+            return [out.value, err.value, nil]
+          end
+          [out.value, err.value, wait.value]
+        end
+      end
+
+      # ssh itself exits 255; anything else is Dokku's own exit code.
+      def ssh_error(subcommand, stderr, status)
+        line = stderr.lines.map { |text| text.sub(/\A\s*!\s*/, "").strip }.reject(&:empty?).last
+        if status.exitstatus == 255 && stderr.include?("Permission denied")
+          "SSH to #{host} was refused - load the key with `ssh-add`"
+        elsif status.exitstatus == 255
+          "could not reach #{host} over SSH#{line && ": #{line}"}"
+        else
+          "dokku #{subcommand} failed on #{host}#{line && ": #{line}"}"
+        end
+      end
+
+      def unix_time(value)
+        Time.at(Integer(value, 10)).utc
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def parse_time(value)
+        value && Time.iso8601(value)
+      rescue ArgumentError
+        nil
+      end
+
+      Platform.register("dokku", self)
+    end
+  end
+end

data/lib/onair/platform/heroku.rb

@@ -10,15 +10,25 @@ module Onair
       HOST = "api.heroku.com"
       RELEASE_WINDOW = 10
       IN_FLIGHT_STATUSES = %w[pending failed].freeze
+      ONE_OFF_TYPES = %w[run scheduler release].freeze
+      # An eco dyno asleep on the running release boots that release on wake.
+      SERVING_STATES = %w[up idle].freeze
+      # With preboot, Heroku keeps routing to the previous web dynos for about
+      # three minutes after the new ones come up.
+      PREBOOT_HANDOFF = 180
+      PREBOOT_NOTE = "preboot: previous web dynos may still serve"
 
       def snapshot
         token = resolve_token
         releases_thread = quiet_thread { releases(token) }
         builds_thread = quiet_thread { builds(token) }
+        dynos_thread = quiet_thread { dynos(token) }
         deployed, release = releases_thread.value
         pending, succeeded_shas = builds_thread.value
+        dyno_rows, preboot = dynos_thread.value
         Snapshot.new(deployed: deployed, pending: pending, release: release,
-                     latest_built_sha: succeeded_shas.first, succeeded_shas: succeeded_shas)
+          latest_built_sha: succeeded_shas.first, succeeded_shas: succeeded_shas,
+          rollout: rollout(dyno_rows, preboot, deployed.version))
       end
 
       private
@@ -27,13 +37,6 @@ module Onair
         @config.app
       end
 
-      def quiet_thread(&block)
-        Thread.new do
-          Thread.current.report_on_exception = false
-          block.call
-        end
-      end
-
       def resolve_token
         token = Auth::Netrc.token(HOST)
         token = Auth::HerokuCli.token if token.nil? || token.empty?
@@ -62,7 +65,7 @@ module Onair
 
       def deployed(row, sha)
         Deployed.new(sha: sha, version: row["version"], description: row["description"],
-                     deployed_at: parse_time(row["created_at"]))
+          deployed_at: parse_time(row["created_at"]))
       end
 
       # Only the newest release counts: an older failed one was superseded by
@@ -71,11 +74,11 @@ module Onair
         return nil if newest.equal?(running) || !IN_FLIGHT_STATUSES.include?(newest["status"])
 
         slug_id = newest.dig("slug", "id")
-        sha = slug_id == running.dig("slug", "id") ? running_sha : slug_commit(http, token, slug_id)
+        sha = (slug_id == running.dig("slug", "id")) ? running_sha : slug_commit(http, token, slug_id)
         return nil if sha.nil?
 
         Release.new(sha: sha, version: newest["version"], description: newest["description"],
-                    status: newest["status"].to_sym, started_at: parse_time(newest["created_at"]))
+          status: newest["status"].to_sym, started_at: parse_time(newest["created_at"]))
       end
 
       def slug_commit(http, token, slug_id)
@@ -96,12 +99,62 @@ module Onair
         pending_sha = pending_build&.dig("source_blob", "version")
         pending = pending_sha && Pending.new(sha: pending_sha, started_at: parse_time(pending_build["created_at"]))
         succeeded = builds.select { |build| build["status"] == "succeeded" }
-                          .filter_map { |build| build.dig("source_blob", "version") }
+          .filter_map { |build| build.dig("source_blob", "version") }
         [pending, succeeded]
       rescue Error
         [nil, []]
       end
 
+      # A failed dynos call drops the rollout and nothing else; a failed
+      # preboot lookup only drops the handoff estimate.
+      def dynos(token)
+        with_http do |http|
+          rows = get(http, token, "/apps/#{app}/dynos")
+          [rows, preboot?(http, token)]
+        end
+      rescue Error
+        [nil, false]
+      end
+
+      def preboot?(http, token)
+        get(http, token, "/apps/#{app}/features/preboot")["enabled"] == true
+      rescue Error
+        false
+      end
+
+      def rollout(rows, preboot, version)
+        return nil if rows.nil? || version.nil?
+
+        formation = rows.reject { |dyno| ONE_OFF_TYPES.include?(dyno["type"]) }
+        return nil if formation.empty?
+
+        processes = formation.group_by { |dyno| dyno["type"] }
+          .sort_by { |type, _| [(type == "web") ? 0 : 1, type] }
+          .map { |type, dynos| process_rollout(type, dynos, version) }
+        Rollout.new(version: version, processes: processes,
+          overlap_until: preboot ? preboot_handoff(formation, version) : nil, overlap_note: PREBOOT_NOTE)
+      end
+
+      def process_rollout(type, dynos, version)
+        current, previous = dynos.partition { |dyno| dyno.dig("release", "version") == version }
+        waiting = current.map { |dyno| dyno["state"] }.reject { |state| SERVING_STATES.include?(state) }.tally
+        ProcessRollout.new(type: type, total: dynos.size, up: current.size - waiting.values.sum,
+          waiting: waiting, previous: previous.size)
+      end
+
+      # Old web dynos still listed are already counted as previous; the
+      # estimate covers only the handoff the dynos list does not show.
+      def preboot_handoff(formation, version)
+        web = formation.select { |dyno| dyno["type"] == "web" }
+        return nil if web.empty?
+        return nil unless web.all? do |dyno|
+          dyno.dig("release", "version") == version && SERVING_STATES.include?(dyno["state"])
+        end
+
+        last_up = web.filter_map { |dyno| parse_time(dyno["updated_at"]) }.max
+        last_up && (last_up + PREBOOT_HANDOFF)
+      end
+
       # One connection per thread — the dependent releases → slug pair must
       # not pay a second TLS handshake.
       def with_http(&)

data/lib/onair/remote_head.rb

@@ -38,7 +38,7 @@ module Onair
 
       sha = JSON.parse(response.body).dig("object", "sha")
       sha&.match?(/\A\h{40}\z/) ? sha : nil
-    rescue StandardError
+    rescue
       nil
     end
     private_class_method :api_head

data/lib/onair/renderer/json.rb

@@ -31,6 +31,7 @@ module Onair
           deployed: deployed_payload,
           pending: pending_payload,
           release: release_payload,
+          rollout: rollout_payload,
           delta: delta_payload,
           pinned: pinned_payload,
           yours: yours_payload
@@ -59,7 +60,8 @@ module Onair
         pending = snapshot.pending
         return nil if pending.nil?
 
-        { sha: pending.sha, started_at: iso(pending.started_at) }.merge(commit_fields(pending.sha))
+        {sha: pending.sha, build_id: pending.build_id, started_at: iso(pending.started_at)}
+          .merge(commit_fields(pending.sha))
       end
 
       def release_payload
@@ -75,11 +77,26 @@ module Onair
         }.merge(commit_fields(release.sha))
       end
 
+      def rollout_payload
+        rollout = @report.rollout
+        return nil if rollout.nil?
+
+        {
+          version: rollout.version,
+          complete: rollout.complete?,
+          processes: rollout.processes.map do |process|
+            {type: process.type, up: process.up, total: process.total,
+             waiting: process.waiting, previous: process.previous}
+          end,
+          overlap_until: iso(rollout.overlap_until)
+        }
+      end
+
       def delta_payload
         case @report.delta
-        when :current then { status: "current", behind_by: 0 }
-        when Integer then { status: "behind", behind_by: @report.delta }
-        else { status: "unknown", behind_by: nil }
+        when :current then {status: "current", behind_by: 0}
+        when Integer then {status: "behind", behind_by: @report.delta}
+        else {status: "unknown", behind_by: nil}
         end
       end
 
@@ -98,19 +115,19 @@ module Onair
         mine = @report.mine
         return nil if mine.nil?
 
-        { sha: mine.sha, had_own_build: mine.had_own_build }.merge(commit_fields(mine.sha))
+        {sha: mine.sha, had_own_build: mine.had_own_build}.merge(commit_fields(mine.sha))
       end
 
       def commit_fields(sha)
         info = sha && @report.commits[sha]
-        { subject: info&.subject, author: info&.author_name, task: task_fields(info&.subject) }
+        {subject: info&.subject, author: info&.author_name, task: task_fields(info&.subject)}
       end
 
       def task_fields(subject)
         task_id = @task&.find(subject)
         return nil if task_id.nil?
 
-        { id: task_id, url: @task.url_for(task_id) }
+        {id: task_id, url: @task.url_for(task_id)}
       end
 
       def iso(time)

data/lib/onair/renderer/tty.rb

@@ -49,6 +49,12 @@ module Onair
         pending = snapshot.pending
         return [] if pending.nil?
 
+        if pending.sha.nil?
+          started = pending.started_at && "started #{age(pending.started_at)}"
+          return commitless_row("Pending:", :yellow, "build #{pending.build_id}", started,
+            paint("⟳ deploying", :yellow)) + [""]
+        end
+
         row_lines("Pending:", :yellow, pending.sha, age(pending.started_at)) + [""]
       end
 
@@ -57,28 +63,66 @@ module Onair
       def release_lines
         release = snapshot.release
         return [] if release.nil?
+        return build_failed_lines(release) if release.sha.nil?
 
-        detail = "v#{release.version}"
-        detail = "#{detail}: #{release.description}" if release.sha == snapshot.deployed&.sha
+        detail = version_label(release.version)
+        detail = [detail, release.description].compact.join(": ") if release.sha == snapshot.deployed&.sha
         label, color, note = if release.status == :failed
-                               ["Failed:", :red, "✗ release phase failed (#{detail})"]
-                             else
-                               ["Releasing:", :yellow, "⟳ release phase (#{detail})"]
-                             end
+          ["Failed:", :red, "✗ release phase failed (#{detail})"]
+        else
+          ["Releasing:", :yellow, "⟳ release phase (#{detail})"]
+        end
         row_lines(label, color, release.sha, age(release.started_at), extra: paint(note, color)) + [""]
       end
 
+      # A failed build whose commit the platform does not record.
+      def build_failed_lines(release)
+        commitless_row("Failed:", :red, release.description, age(release.started_at),
+          paint("✗ build failed", :red)) + [""]
+      end
+
       def deployed_lines
         deployed = snapshot.deployed
         if deployed&.sha
           lines = row_lines("Deployed:", :green, deployed.sha, age(deployed.deployed_at), extra: delta_text)
+          lines << rollout_line if @report.rollout
           lines << pinned_line if @report.pinned
           lines.concat(yours_lines)
           lines
         else
-          ["  #{paint("Could not resolve the running commit for v#{deployed&.version} " \
-                      "(#{deployed&.description}).", :yellow)}"]
+          subject = ["the running commit", version_label(deployed&.version)].compact.join(" for ")
+          ["  #{paint("Could not resolve #{subject} (#{deployed&.description}).", :yellow)}"]
+        end
+      end
+
+      # The dynos list can look finished while preboot still routes some
+      # traffic to the previous release, so that window gets its own line.
+      def rollout_line
+        rollout = @report.rollout
+        target = [version_label(rollout.version)].compact.map { |label| " #{label}" }.join
+        text, color = if rollout.complete?
+          ["✓ rolled out#{target}: #{process_counts(rollout)}", :dim]
+        elsif rollout.processes.all?(&:complete?)
+          ["⟳ #{rollout.overlap_note || "previous release may still serve"} for " \
+           "~#{remaining(rollout.overlap_until)} (estimate)", :yellow]
+        else
+          ["⟳ rolling out#{target}: #{process_counts(rollout)}", :yellow]
         end
+        "  #{paint(text, color)}"
+      end
+
+      def process_counts(rollout)
+        rollout.processes.map do |process|
+          parts = ["#{process.type} #{process.up}/#{process.total}"]
+          parts.concat(process.waiting.map { |state, count| "#{count} #{state}" })
+          parts << "#{process.previous} on older release" if process.previous.positive?
+          parts.join(", ")
+        end.join(" · ")
+      end
+
+      def remaining(time)
+        seconds = (time - @now).ceil.clamp(0..)
+        (seconds < 60) ? "#{seconds}s" : "#{(seconds / 60.0).ceil}m"
       end
 
       def yours_lines
@@ -98,7 +142,18 @@ module Onair
         padded = label.ljust(LABEL_WIDTH)
         first = "  #{paint(padded, color_key)}  #{paint(sha[0, 9], :bold)}  #{paint("#{age_blurb}by #{author}", :dim)}"
         first = "#{first}  #{extra}" if extra
-        [first, "  #{paint('→', :dim)} #{linkify(subject, info ? sha : nil)}"]
+        [first, "  #{paint("→", :dim)} #{linkify(subject, info ? sha : nil)}"]
+      end
+
+      # A row for a build with no commit: its name stands where the sha would,
+      # and there is no subject line to show.
+      def commitless_row(label, color_key, name, age, extra)
+        age_blurb = age ? "  #{paint("(#{age})", :dim)}" : ""
+        ["  #{paint(label.ljust(LABEL_WIDTH), color_key)}  #{paint(name, :bold)}#{age_blurb}  #{extra}"]
+      end
+
+      def version_label(version)
+        version && "v#{version}"
       end
 
       def delta_text
@@ -107,13 +162,14 @@ module Onair
           paint("★ current", :green)
         when Integer
           count = @report.delta
-          paint("↓ #{count} #{count == 1 ? 'commit' : 'commits'} behind origin/#{@branch}", :yellow)
+          paint("↓ #{count} #{(count == 1) ? "commit" : "commits"} behind origin/#{@branch}", :yellow)
         end
       end
 
       def pinned_line
         deployed = snapshot.deployed
-        "  #{paint("⏸ v#{deployed.version} (#{deployed.description}) - newer build " \
+        running = [version_label(deployed.version), "(#{deployed.description})"].compact.join(" ")
+        "  #{paint("⏸ #{running} - newer build " \
                    "#{snapshot.latest_built_sha[0, 9]} succeeded but is not running", :yellow)}"
       end
 

data/lib/onair/report.rb

@@ -10,8 +10,10 @@ module Onair
   # mine:    the local user's commit just below someone else's deployed head.
   # commits: sha => CommitInfo (or nil when absent locally) for every sha a
   #          renderer may need to describe.
-  Report = Data.define(:snapshot, :remote_head, :delta, :pinned, :mine, :commits) do
-    def self.build(snapshot:, remote_head:, git:)
+  # rollout: the snapshot's rollout, its handoff estimate dropped once `now`
+  #          has passed it, or nil when unknown.
+  Report = Data.define(:snapshot, :remote_head, :delta, :pinned, :mine, :commits, :rollout) do
+    def self.build(snapshot:, remote_head:, git:, now:)
       # Pinned is judged before the stale pending is dropped: during the
       # stale window the newest *succeeded* build is still the previous
       # deploy, which must not read as a rollback.
@@ -20,17 +22,24 @@ module Onair
       deployed_sha = snapshot.deployed&.sha
       mine = compute_mine(snapshot, git)
       commits = [deployed_sha, snapshot.pending&.sha, snapshot.release&.sha, mine&.sha]
-                .compact.uniq.to_h { |sha| [sha, git.commit_info(sha)] }
+        .compact.uniq.to_h { |sha| [sha, git.commit_info(sha)] }
       new(
         snapshot: snapshot,
         remote_head: remote_head,
         delta: compute_delta(snapshot, remote_head, git),
         pinned: pinned,
         mine: mine,
-        commits: commits
+        commits: commits,
+        rollout: live_rollout(snapshot.rollout, now)
       )
     end
 
+    def self.live_rollout(rollout, now)
+      return rollout if rollout.nil? || rollout.overlap_until.nil? || rollout.overlap_until > now
+
+      rollout.with(overlap_until: nil)
+    end
+
     # Right after a deploy finishes, the platform's builds list can still
     # report the just-released build as pending while the releases endpoint
     # already shows it running — the same commit would render as both
@@ -64,8 +73,11 @@ module Onair
       !sha.nil? && !latest.nil? && latest != sha && snapshot.pending.nil? && !release_of_other_commit?(snapshot)
     end
 
+    # A release with no known commit (a failed build on a platform whose
+    # builds carry none) says nothing about commits, so it never counts.
     def self.release_of_other_commit?(snapshot)
-      !snapshot.release.nil? && snapshot.release.sha != snapshot.deployed&.sha
+      sha = snapshot.release&.sha
+      !sha.nil? && sha != snapshot.deployed&.sha
     end
 
     # "Did my merge just ship?" — deliberately a 2-commit first-parent window
@@ -91,6 +103,6 @@ module Onair
     end
 
     private_class_method :drop_superseded_pending, :compute_delta, :pinned?, :release_of_other_commit?,
-                         :compute_mine, :identity_match?
+      :compute_mine, :identity_match?, :live_rollout
   end
 end

data/lib/onair/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Onair
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/onair.rb

@@ -9,19 +9,45 @@ module Onair
   CommitInfo = Data.define(:subject, :author_name, :author_email, :committed_at)
 
   # The release currently running in production. `sha` may be nil when the
-  # platform can't resolve the running commit; version/description still render.
+  # platform can't resolve the running commit; `version` is nil on platforms
+  # that number nothing.
   Deployed = Data.define(:sha, :version, :description, :deployed_at)
 
-  Pending = Data.define(:sha, :started_at)
+  # An in-flight build. `sha` is nil when the platform's builds carry no
+  # commit; `build_id` then names the row.
+  Pending = Data.define(:sha, :build_id, :started_at) do
+    def initialize(sha:, started_at:, build_id: nil) = super
+  end
 
   # A release newer than the running one that is not serving traffic: its
   # release phase is still running (status :pending) or it failed (:failed).
+  # A nil `sha` is a failed build whose commit the platform does not record.
   Release = Data.define(:sha, :version, :description, :status, :started_at)
 
+  # Dynos of one process type against the running release. `up` counts dynos
+  # on the running version that serve (or idle until woken); `waiting` counts
+  # the rest of them by state; `previous` counts dynos on an older release.
+  ProcessRollout = Data.define(:type, :total, :up, :waiting, :previous) do
+    def complete?
+      up == total
+    end
+  end
+
+  # How far the running release has reached its dynos. `overlap_until` is an
+  # estimate of when the previous release stops serving traffic, or nil;
+  # `overlap_note` is the platform's phrase for that window.
+  Rollout = Data.define(:version, :processes, :overlap_until, :overlap_note) do
+    def initialize(version:, processes:, overlap_until:, overlap_note: nil) = super
+
+    def complete?
+      processes.all?(&:complete?) && overlap_until.nil?
+    end
+  end
+
   # What a platform adapter returns. `latest_built_sha` is the newest
   # successfully built sha (rollback detection); `succeeded_shas` lists all
   # recent succeeded build shas, newest first ("yours had its own deploy").
-  Snapshot = Data.define(:deployed, :pending, :release, :latest_built_sha, :succeeded_shas)
+  Snapshot = Data.define(:deployed, :pending, :release, :latest_built_sha, :succeeded_shas, :rollout)
 
   Mine = Data.define(:sha, :had_own_build)
 end
@@ -37,6 +63,7 @@ require_relative "onair/auth/github_token"
 require_relative "onair/remote_head"
 require_relative "onair/platform/base"
 require_relative "onair/platform/heroku"
+require_relative "onair/platform/dokku"
 require_relative "onair/renderer/tty"
 require_relative "onair/renderer/json"
 require_relative "onair/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: onair-cli
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Eugene
@@ -31,6 +31,7 @@ files:
 - lib/onair/git.rb
 - lib/onair/orchestrator.rb
 - lib/onair/platform/base.rb
+- lib/onair/platform/dokku.rb
 - lib/onair/platform/heroku.rb
 - lib/onair/remote_head.rb
 - lib/onair/renderer/json.rb