onair-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e4350eed5352315ed4c6591c3ae03bdfb6648986d844a749051fed27506427b9
+  data.tar.gz: 9193566d1ea45893c68ff3d10340d80b6c1845a9e5f71eb21ece94df935e4a22
+SHA512:
+  metadata.gz: a72e23588254686e5154cf43fc8253a67fd16b524f67e1d75fcd3088281af2ba23272045a14f0f6517007ab1f9d4a7c790425fa8c33d4f21834219d414ddb999
+  data.tar.gz: f95b6452f90d13d024f8a4d432ea2bddb39b805149a6918cc78b4274e02aa0a965246c6758d20acb71531fc69b44def03d496afa3ea41e7bea0cd2998848ec5d

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0]
+
+- Initial release: Heroku adapter with netrc auth, full behavior parity with
+  the reference bash script, TTY renderer with ANSI colors and OSC 8 links.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Eugene
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,158 @@
+<p align="center">
+  <img src="logo.svg" alt="onair" width="460">
+</p>
+
+<div align="center">
+
+### See what's on air — which commit is actually running in production.
+
+[![Gem Version](https://img.shields.io/gem/v/onair-cli)](https://rubygems.org/gems/onair-cli)
+[![CI](https://github.com/amberpixels/onair-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/amberpixels/onair-cli/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE.txt)
+
+</div>
+
+---
+
+<p align="center">
+  <img src="assets/demo.svg"
+       alt="onair report: a pending build, the deployed release one commit behind origin/main, and your commit absorbed by the current deploy"
+       width="760">
+</p>
+
+`onair` answers one question fast and truthfully. The deployed commit comes
+from the running release's *slug*, never from "newest build" — after a
+rollback those differ, and the whole point of this tool is to not lie in that
+case.
+
+## Principles
+
+1. **Truth over convenience.** What's *running*, not what was built last.
+2. **Zero runtime dependencies.** Ruby stdlib only.
+3. **Read-only.** Never deploys, never rolls back, never writes to git except
+   an explicit lazy `git fetch`.
+4. **Platform-agnostic core.** Heroku is the first adapter, not the
+   architecture.
+5. **Degrade gracefully.** Offline, missing commits, no color support — every
+   failure mode renders something useful, never a stack trace.
+
+## Installation
+
+```sh
+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`.
+
+## Usage
+
+```
+onair              # status report for the current repo
+onair init         # write .onair.yml; --justfile appends a `prod` recipe
+onair --json       # machine-readable status
+onair --app NAME   # override the app for one invocation
+onair --no-fetch   # never fetch git objects from the remote
+```
+
+Exit codes: `0` success, `1` operational error. Color is disabled when stdout
+is not a TTY or `NO_COLOR` is set.
+
+### Speed
+
+The remote head of `origin/<branch>` is resolved through the GitHub API
+(~0.4s) when a token is ambient — `GH_TOKEN`, `GITHUB_TOKEN`, or a logged-in
+`gh` CLI — with `git ls-remote` always racing alongside as the fallback
+(no token, non-GitHub remote, API failure). Both report the live remote ref;
+the API is a faster transport, never a cache.
+
+### What the report shows
+
+- **Deployed** — the commit the running release was built from, its age,
+  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.
+- **Pending** — an in-flight build that's about to replace the deploy.
+- **⏸ pinned** — a newer build succeeded but is *not* what's running
+  (rollback / pinned release).
+- **Yours** — when someone else's commit is deployed but yours sits just
+  below it: your merge made it to prod, absorbed by a later deploy.
+
+## Configuration
+
+`.onair.yml` (searched upward from the working directory to the git root):
+
+```yaml
+platform: heroku
+app: acme-prod
+repo: acme/widgets   # for PR/commit links; default: inferred from origin
+branch: main         # comparison branch; default: main
+```
+
+Resolution order: CLI flags → env vars (`HEROKU_APP`, `GITHUB_REPO`) →
+`.onair.yml`.
+
+### Task links (optional)
+
+If your commit subjects carry task ids (Jira, Linear, Notion, anything), tell
+onair how to recognize and link them:
+
+```yaml
+task:
+  pattern: 'ABC-\d+'                              # any Ruby regex
+  url: 'https://acme.atlassian.net/browse/{task}' # {task} = the matched id
+```
+
+Matched ids in commit subjects become clickable terminal hyperlinks (the text
+stays identical), and `--json` gains a `task` object (`{ "id", "url" }`) per
+commit. No `task:` section — no behavior, nothing to opt out of.
+
+## JSON schema
+
+`onair --json` emits one object; the schema is a public API and only changes
+additively:
+
+```json
+{
+  "app": "acme-prod",
+  "platform": "heroku",
+  "branch": "main",
+  "repo": "acme/widgets",
+  "remote_head": "<sha>",
+  "deployed": {
+    "sha": "<sha>", "version": 1234, "description": "Deploy a1b2c3d4",
+    "deployed_at": "2026-06-12T10:00:00Z", "subject": "Fix the thing (#1234)",
+    "author": "Eugene", "task": null
+  },
+  "pending": null,
+  "delta": { "status": "current", "behind_by": 0 },
+  "pinned": null,
+  "yours": null
+}
+```
+
+- `delta.status` is `"current"`, `"behind"`, or `"unknown"`.
+- `pending`: `{ "sha", "started_at", "subject", "author" }` when a build is
+  in flight.
+- `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
+  sits just below the deployed head.
+- `subject`/`author` are `null` when the commit isn't in the local repo.
+- `task`: `{ "id", "url" }` when a `task:` matcher is configured and the
+  subject contains a match, otherwise `null`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake        # specs + rubocop
+```
+
+The behavioral source of truth is `reference/prod-release.sh`, the
+battle-tested bash script this gem was extracted from. The behavior spec in
+`spec/onair/report_spec.rb` ports its rules one by one.
+
+## License
+
+MIT

data/exe/onair

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "onair"
+
+exit Onair::CLI.run(ARGV)

data/lib/onair/auth/github_token.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Onair
+  module Auth
+    # Ambient GitHub token for the fast remote-head lookup: env vars first
+    # (free), then the gh CLI (~50ms Go binary boot). Never prompts.
+    module GithubToken
+      def self.token(env: ENV)
+        env_token = env["GH_TOKEN"] || env["GITHUB_TOKEN"]
+        return env_token unless env_token.to_s.empty?
+
+        cli_token
+      end
+
+      def self.cli_token
+        stdout, _stderr, status = Open3.capture3("gh", "auth", "token")
+        return nil unless status.success?
+
+        token = stdout.strip
+        token.empty? ? nil : token
+      rescue SystemCallError
+        nil
+      end
+      private_class_method :cli_token
+    end
+  end
+end

data/lib/onair/auth/heroku_cli.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Onair
+  module Auth
+    # Fallback when ~/.netrc yields nothing: boot the Heroku CLI. Slow
+    # (1-2s of Node startup) — that's why netrc is tried first.
+    module HerokuCli
+      def self.token
+        stdout, _stderr, status = Open3.capture3("heroku", "auth:token")
+        return nil unless status.success?
+
+        token = stdout.strip
+        token.empty? ? nil : token
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/onair/auth/netrc.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Onair
+  module Auth
+    # Minimal ~/.netrc reader — just enough to pull the token the Heroku CLI
+    # stores under `machine api.heroku.com`. Handles both same-line and
+    # multi-line entry styles (the format is whitespace-token based).
+    module Netrc
+      def self.token(host, path: File.join(Dir.home, ".netrc"))
+        return nil unless File.readable?(path)
+
+        tokens = File.read(path).split(/\s+/)
+        tokens.each_with_index do |word, index|
+          return password_after(tokens, index + 2) if word == "machine" && tokens[index + 1] == host
+        end
+        nil
+      end
+
+      def self.password_after(tokens, start)
+        tokens[start..].each_slice(2) do |key, value|
+          return nil if ["machine", "default", nil].include?(key)
+          return value if key == "password"
+        end
+        nil
+      end
+      private_class_method :password_after
+    end
+  end
+end

data/lib/onair/cli.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Onair
+  # Errors are rescued here and printed as a single friendly line — no
+  # backtraces (--debug re-raises). Returns the process exit code.
+  class CLI
+    def self.run(argv)
+      new.run(argv)
+    end
+
+    def run(argv)
+      flags, command = parse(argv)
+      case command
+      when nil then status(flags)
+      when "init" then init(flags)
+      else raise Error, "unknown command: #{command} (try `onair --help`)"
+      end
+      0
+    rescue OptionParser::ParseError => e
+      warn_error(e.message)
+      1
+    rescue Error => e
+      raise if flags&.[](:debug)
+
+      warn_error(e.message)
+      1
+    end
+
+    private
+
+    def parse(argv)
+      flags = {}
+      parser = OptionParser.new do |opts|
+        opts.banner = <<~BANNER
+          Usage: onair [command] [options]
+
+          Commands:
+              (none)           status report for the configured app
+              init             write .onair.yml for this repo
+
+          Options:
+        BANNER
+        opts.on("--app NAME", "override the app for this invocation") { |value| flags[:app] = value }
+        opts.on("--json", "machine-readable status") { flags[:json] = true }
+        opts.on("--no-fetch", "never fetch git objects from the remote") { flags[:no_fetch] = true }
+        opts.on("--justfile", "with init: append a `prod` recipe to the justfile") { flags[:justfile] = true }
+        opts.on("--debug", "re-raise errors with backtraces") { flags[:debug] = true }
+        opts.on("--version", "print version") do
+          puts VERSION
+          exit 0
+        end
+        opts.on("-h", "--help", "print this help") do
+          puts opts
+          exit 0
+        end
+      end
+      [flags, parser.parse(argv).first]
+    end
+
+    def status(flags)
+      config = Config.resolve(flags)
+      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
+
+      if flags[:json]
+        puts Renderer::Json.new(report: report, app: config.app, platform: config.platform,
+                                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
+      end
+    end
+
+    def init(flags)
+      path = File.join(Dir.pwd, Config::FILENAME)
+      raise Error, "#{Config::FILENAME} already exists" if File.exist?(path)
+
+      app = flags[:app] || ENV.fetch("HEROKU_APP", nil)
+      raise Error, "pass --app NAME to seed the config" if app.nil?
+
+      git = Git.new
+      lines = ["platform: heroku", "app: #{app}"]
+      repo = git.origin_repo
+      lines << "repo: #{repo}" if repo
+      lines << "branch: main"
+      File.write(path, "#{lines.join("\n")}\n")
+      puts "wrote #{Config::FILENAME}"
+      append_justfile if flags[:justfile]
+    end
+
+    def append_justfile
+      path = %w[justfile Justfile .justfile].find { |name| File.exist?(name) } || "justfile"
+      existing = File.exist?(path) ? File.read(path) : ""
+      raise Error, "#{path} already has a `prod` recipe" if existing.match?(/^prod:/)
+
+      recipe = "prod:\n    @onair\n"
+      content = existing.empty? ? recipe : "#{existing.chomp}\n\n#{recipe}"
+      File.write(path, content)
+      puts "added `prod` recipe to #{path}"
+    end
+
+    def warn_error(message)
+      if $stderr.tty? && !no_color?
+        warn "\n  \e[1;33merror: #{message}\e[0m"
+      else
+        warn "\n  error: #{message}"
+      end
+    end
+
+    def no_color?
+      !ENV["NO_COLOR"].to_s.empty?
+    end
+  end
+end

data/lib/onair/config.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Onair
+  # Resolution order: CLI flags → env vars → .onair.yml (searched upward
+  # from cwd to the git root) → error with a hint to run `onair init`.
+  class Config
+    FILENAME = ".onair.yml"
+
+    attr_reader :platform, :app, :repo, :branch, :fetch, :task
+
+    def initialize(platform:, app:, repo:, branch:, fetch:, task: nil)
+      @platform = platform
+      @app = app
+      @repo = repo
+      @branch = branch
+      @fetch = fetch
+      @task = task
+    end
+
+    def self.resolve(flags = {}, env: ENV, dir: Dir.pwd)
+      file = find_file(dir) || {}
+      app = flags[:app] || env["HEROKU_APP"] || 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",
+        app: app,
+        repo: env["GITHUB_REPO"] || file["repo"],
+        branch: file["branch"] || "main",
+        fetch: !flags[:no_fetch],
+        task: TaskLink.from_config(file["task"])
+      )
+    end
+
+    def self.find_file(start)
+      dir = File.expand_path(start)
+      loop do
+        path = File.join(dir, FILENAME)
+        return YAML.safe_load_file(path) || {} if File.file?(path)
+        return nil if File.exist?(File.join(dir, ".git"))
+
+        parent = File.dirname(dir)
+        return nil if parent == dir
+
+        dir = parent
+      end
+    end
+  end
+end

data/lib/onair/git.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Onair
+  # The only place that shells out to git. Everything else takes an instance
+  # as a dependency — this is the seam unit tests fake. All methods degrade
+  # to nil/false/[] on failure; they never raise.
+  class Git
+    Identity = Data.define(:name, :email)
+
+    def initialize(fetch_allowed: true, dir: nil)
+      @fetch_allowed = fetch_allowed
+      @dir = dir
+      @fetched = false
+    end
+
+    # Tip of origin/<branch> straight from the remote — accurate without a
+    # pull. Falls back to the local origin/<branch> ref when offline.
+    def remote_head(branch)
+      out = capture("ls-remote", "origin", "refs/heads/#{branch}")
+      sha = out.to_s[/\A\h+/]
+      return sha unless sha.nil? || sha.empty?
+
+      capture("rev-parse", "origin/#{branch}")&.strip
+    end
+
+    def has_commit?(sha)
+      success?("cat-file", "-e", "#{sha}^{commit}")
+    end
+
+    # Best-effort, at most once per process, skipped under --no-fetch. The
+    # commit may still be absent afterward (force-pushed away); callers
+    # degrade via the "(commit not found)" fallback.
+    def fetch_once!
+      return if @fetched || !@fetch_allowed
+
+      @fetched = true
+      success?("fetch", "--quiet", "origin")
+    end
+
+    def commit_info(sha)
+      out = capture("log", "-1", "--format=%s%x09%an%x09%ae%x09%ct", sha)
+      return nil if out.nil?
+
+      subject, name, email, epoch = out.chomp.split("\t", 4)
+      CommitInfo.new(subject:, author_name: name, author_email: email, committed_at: Time.at(epoch.to_i))
+    end
+
+    def ancestor?(ancestor_sha, descendant_sha)
+      success?("merge-base", "--is-ancestor", ancestor_sha, descendant_sha)
+    end
+
+    def count_between(from_sha, to_sha)
+      capture("rev-list", "--count", "#{from_sha}..#{to_sha}")&.strip&.to_i
+    end
+
+    # The <count> first-parent commits just below the given head (head itself
+    # excluded), as [sha, author_name, author_email] tuples.
+    def first_parent_below(sha, count)
+      out = capture("log", "--first-parent", "--skip=1", "-#{count}", "--format=%H%x09%an%x09%ae", sha)
+      return [] if out.nil?
+
+      out.lines.map { |line| line.chomp.split("\t", 3) }
+    end
+
+    def identity
+      Identity.new(name: capture("config", "user.name")&.strip, email: capture("config", "user.email")&.strip)
+    end
+
+    # "owner/name" parsed from the origin remote, or nil.
+    def origin_repo
+      url = capture("remote", "get-url", "origin")&.strip
+      url&.match(%r{github\.com[:/](?<repo>[^/]+/[^/\s]+?)(?:\.git)?/?\z})&.[](:repo)
+    end
+
+    private
+
+    def capture(*)
+      stdout, _stderr, status = Open3.capture3("git", *, **opts)
+      status.success? ? stdout : nil
+    rescue SystemCallError
+      nil
+    end
+
+    def success?(*)
+      _stdout, _stderr, status = Open3.capture3("git", *, **opts)
+      status.success?
+    rescue SystemCallError
+      false
+    end
+
+    def opts
+      @dir ? { chdir: @dir } : {}
+    end
+  end
+end

data/lib/onair/orchestrator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+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)
+      @config = config
+      @adapter = adapter
+      @git = git
+      @repo = repo
+    end
+
+    def run
+      snapshot_thread = quiet_thread { @adapter.snapshot }
+      head_thread = quiet_thread { RemoteHead.resolve(git: @git, branch: @config.branch, repo: @repo) }
+      snapshot = snapshot_thread.value
+      remote_head = head_thread.value
+
+      needed = [snapshot.deployed&.sha, snapshot.pending&.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)
+    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

data/lib/onair/platform/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Onair
+  module Platform
+    @registry = {}
+
+    class << self
+      def register(name, klass)
+        @registry[name] = klass
+      end
+
+      def build(config)
+        klass = @registry[config.platform]
+        if klass.nil?
+          raise Error,
+                "unknown platform #{config.platform.inspect} (available: #{@registry.keys.join(', ')})"
+        end
+
+        klass.new(config)
+      end
+    end
+
+    # Adapter contract: implement #snapshot returning a Snapshot.
+    #
+    #   deployed:         the release CURRENTLY RUNNING (nil sha only if
+    #                     truly unresolvable)
+    #   pending:          newest in-flight build, or nil
+    #   latest_built_sha: newest successfully built sha, or nil
+    #   succeeded_shas:   recent succeeded build shas, newest first
+    #
+    # Adapters own their internal concurrency and auth. Everything above
+    # (delta, pinned, mine, rendering) is platform-agnostic and must not
+    # reference any specific platform.
+    class Base
+      def initialize(config)
+        @config = config
+      end
+
+      def snapshot
+        raise NotImplementedError
+      end
+
+      def display_name
+        self.class.name.split("::").last
+      end
+    end
+  end
+end

data/lib/onair/platform/heroku.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "time"
+
+module Onair
+  module Platform
+    class Heroku < Base
+      HOST = "api.heroku.com"
+
+      def snapshot
+        token = resolve_token
+        release_thread = quiet_thread { deployed(token) }
+        builds_thread = quiet_thread { builds(token) }
+        deployed = release_thread.value
+        pending, succeeded_shas = builds_thread.value
+        Snapshot.new(deployed: deployed, pending: pending,
+                     latest_built_sha: succeeded_shas.first, succeeded_shas: succeeded_shas)
+      end
+
+      private
+
+      def app
+        @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?
+        raise Error, "no Heroku credentials found — run `heroku login`" if token.nil? || token.empty?
+
+        token
+      end
+
+      # The slug records the commit the running release was built from — the
+      # only reliable source after a rollback, when the builds list still
+      # shows the newer (no-longer-running) build on top.
+      def deployed(token)
+        with_http do |http|
+          release = get(http, token, "/apps/#{app}/releases", range: "version ..; order=desc, max=1").first
+          raise Error, "no releases found for app #{app}" if release.nil?
+
+          Deployed.new(
+            sha: slug_commit(http, token, release.dig("slug", "id")),
+            version: release["version"],
+            description: release["description"],
+            deployed_at: parse_time(release["created_at"])
+          )
+        end
+      end
+
+      def slug_commit(http, token, slug_id)
+        return nil if slug_id.nil?
+
+        get(http, token, "/apps/#{app}/slugs/#{slug_id}")["commit"]
+      rescue Error
+        nil
+      end
+
+      # A failed builds call degrades to "no pending, nothing built" rather
+      # than killing the whole report; a failed releases call is fatal.
+      def builds(token)
+        builds = with_http do |http|
+          get(http, token, "/apps/#{app}/builds", range: "created_at ..; order=desc, max=10")
+        end
+        pending_build = builds.find { |build| build["status"] == "pending" }
+        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") }
+        [pending, succeeded]
+      rescue Error
+        [nil, []]
+      end
+
+      # One connection per thread — the dependent releases → slug pair must
+      # not pay a second TLS handshake.
+      def with_http(&)
+        Net::HTTP.start(HOST, 443, use_ssl: true, open_timeout: 5, read_timeout: 15, &)
+      rescue Net::OpenTimeout, SocketError, SystemCallError, OpenSSL::SSL::SSLError => e
+        raise Error, "Heroku API request failed: #{e.message}"
+      end
+
+      def get(http, token, path, range: nil)
+        request = Net::HTTP::Get.new(path)
+        request["Authorization"] = "Bearer #{token}"
+        request["Accept"] = "application/vnd.heroku+json; version=3"
+        if range
+          request["Range"] = range
+          # Net::HTTP won't auto-decompress a response to a ranged request,
+          # but its default Accept-Encoding still invites gzip — ask for an
+          # uncompressed body instead. (Heroku's Range is pagination, not bytes.)
+          request["Accept-Encoding"] = "identity"
+        end
+        response = http.request(request)
+        raise Error, error_message(response, path) unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise Error, "Heroku API returned invalid JSON for #{path}"
+      rescue Net::OpenTimeout, Net::ReadTimeout, SocketError, SystemCallError, OpenSSL::SSL::SSLError => e
+        raise Error, "Heroku API request failed: #{e.message}"
+      end
+
+      def error_message(response, path)
+        case response.code.to_i
+        when 401 then "Heroku rejected the token (401) — run `heroku login`"
+        when 404 then "Heroku app not found: #{app}"
+        else "Heroku API returned #{response.code} for #{path}"
+        end
+      end
+
+      def parse_time(value)
+        value && Time.iso8601(value)
+      rescue ArgumentError
+        nil
+      end
+
+      Platform.register("heroku", self)
+    end
+  end
+end

data/lib/onair/remote_head.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Onair
+  # Resolves the tip of origin/<branch>. `git ls-remote` over SSH costs ~2s
+  # in handshakes; the GitHub API answers the same question in ~0.4s when a
+  # token is ambient. Both report the live remote ref — this is a faster
+  # transport, never a cache. The ls-remote thread always starts so a failed
+  # API attempt costs nothing extra.
+  module RemoteHead
+    API_HOST = "api.github.com"
+
+    def self.resolve(git:, branch:, repo:)
+      ls_remote = Thread.new do
+        Thread.current.report_on_exception = false
+        git.remote_head(branch)
+      end
+      api_head(repo, branch) || ls_remote.value
+    end
+
+    # Any failure (no repo, no token, 404, timeout, rate limit, offline)
+    # falls back to ls-remote — this path must never break the report.
+    def self.api_head(repo, branch)
+      return nil if repo.nil?
+
+      token = Auth::GithubToken.token
+      return nil if token.nil?
+
+      response = Net::HTTP.start(API_HOST, 443, use_ssl: true, open_timeout: 2, read_timeout: 3) do |http|
+        request = Net::HTTP::Get.new("/repos/#{repo}/git/ref/heads/#{branch}")
+        request["Authorization"] = "Bearer #{token}"
+        request["Accept"] = "application/vnd.github+json"
+        http.request(request)
+      end
+      return nil unless response.is_a?(Net::HTTPSuccess)
+
+      sha = JSON.parse(response.body).dig("object", "sha")
+      sha&.match?(/\A\h{40}\z/) ? sha : nil
+    rescue StandardError
+      nil
+    end
+    private_class_method :api_head
+  end
+end

data/lib/onair/renderer/json.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Onair
+  module Renderer
+    # Machine-readable status. The schema is a public API documented in the
+    # README — additive changes only.
+    class Json
+      def initialize(report:, app:, platform:, branch:, repo:, task: nil)
+        @report = report
+        @app = app
+        @platform = platform
+        @branch = branch
+        @repo = repo
+        @task = task
+      end
+
+      def render
+        ::JSON.generate(payload)
+      end
+
+      def payload
+        {
+          app: @app,
+          platform: @platform,
+          branch: @branch,
+          repo: @repo,
+          remote_head: @report.remote_head,
+          deployed: deployed_payload,
+          pending: pending_payload,
+          delta: delta_payload,
+          pinned: pinned_payload,
+          yours: yours_payload
+        }
+      end
+
+      private
+
+      def snapshot
+        @report.snapshot
+      end
+
+      def deployed_payload
+        deployed = snapshot.deployed
+        return nil if deployed.nil?
+
+        {
+          sha: deployed.sha,
+          version: deployed.version,
+          description: deployed.description,
+          deployed_at: iso(deployed.deployed_at)
+        }.merge(commit_fields(deployed.sha))
+      end
+
+      def pending_payload
+        pending = snapshot.pending
+        return nil if pending.nil?
+
+        { sha: pending.sha, started_at: iso(pending.started_at) }.merge(commit_fields(pending.sha))
+      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 }
+        end
+      end
+
+      def pinned_payload
+        return nil unless @report.pinned
+
+        deployed = snapshot.deployed
+        {
+          version: deployed.version,
+          description: deployed.description,
+          latest_built_sha: snapshot.latest_built_sha
+        }
+      end
+
+      def yours_payload
+        mine = @report.mine
+        return nil if mine.nil?
+
+        { 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) }
+      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) }
+      end
+
+      def iso(time)
+        time&.utc&.iso8601
+      end
+    end
+  end
+end

data/lib/onair/renderer/tty.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Onair
+  module Renderer
+    # Pure function of Report + flags: no IO, snapshot-testable.
+    class Tty
+      COLORS = {
+        bold: "\e[1m",
+        green: "\e[0;32m",
+        yellow: "\e[1;33m",
+        dim: "\e[2m",
+        purple: "\e[38;5;176m",
+        cyan: "\e[0;36m",
+        reset: "\e[0m"
+      }.freeze
+
+      NOT_FOUND_SUBJECT = "(commit not found in local git)"
+
+      def initialize(report:, app:, platform_label:, branch:, repo:, color:, hyperlinks:, now:, task: nil)
+        @report = report
+        @app = app
+        @platform_label = platform_label
+        @branch = branch
+        @repo = repo
+        @color = color
+        @hyperlinks = hyperlinks
+        @now = now
+        @task = task
+      end
+
+      def render
+        lines = ["", "  #{code(:purple)}#{@platform_label} #{code(:bold)}#{@app}#{code(:reset)}", ""]
+        lines.concat(pending_lines)
+        lines.concat(deployed_lines)
+        lines << ""
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      def snapshot
+        @report.snapshot
+      end
+
+      def pending_lines
+        pending = snapshot.pending
+        return [] if pending.nil?
+
+        row_lines("Pending: ", :yellow, pending.sha, age(pending.started_at)) + [""]
+      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 << 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)}"]
+        end
+      end
+
+      def yours_lines
+        mine = @report.mine
+        return [] if mine.nil?
+
+        note = mine.had_own_build ? "✓ released, then absorbed by current" : "✓ absorbed by current deploy"
+        committed_at = @report.commits[mine.sha]&.committed_at
+        [""] + row_lines("Yours:   ", :cyan, mine.sha, age(committed_at), extra: paint(note, :cyan))
+      end
+
+      def row_lines(label, color_key, sha, age, extra: nil)
+        info = @report.commits[sha]
+        subject = info&.subject || NOT_FOUND_SUBJECT
+        author = info&.author_name || "?"
+        age_blurb = age ? "(#{age}) " : ""
+        first = "  #{paint(label, 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)}"]
+      end
+
+      def delta_text
+        case @report.delta
+        when :current
+          paint("★ current", :green)
+        when Integer
+          count = @report.delta
+          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 " \
+                   "#{snapshot.latest_built_sha[0, 9]} succeeded but is not running", :yellow)}"
+      end
+
+      # Subjects ending in " (#1234)" (merge convention) strip the suffix and
+      # link to the PR; otherwise link the commit. Commits absent from the
+      # local repo (sha == nil here) skip linking entirely.
+      def linkify(subject, sha)
+        if @repo && (match = subject.match(/\A(?<base>.*) \(#(?<pr>\d+)\)\z/))
+          "#{tasked(match[:base])} • #{link("https://github.com/#{@repo}/pull/#{match[:pr]}", "↗ ##{match[:pr]}")}"
+        elsif @repo && sha
+          "#{tasked(subject)} • #{link("https://github.com/#{@repo}/commit/#{sha}", "↗ #{sha[0, 9]}")}"
+        else
+          tasked(subject)
+        end
+      end
+
+      # Configured task ids stay visually identical — they just become clickable.
+      def tasked(text)
+        return text unless @task && @hyperlinks
+
+        text.gsub(@task.pattern) { |task_id| link(@task.url_for(task_id), task_id) }
+      end
+
+      def link(url, text)
+        @hyperlinks ? "\e]8;;#{url}\a#{text}\e]8;;\a" : text
+      end
+
+      def age(time)
+        return nil if time.nil?
+
+        seconds = (@now - time).to_i.clamp(0..)
+        if seconds < 60 then "#{seconds}s ago"
+        elsif seconds < 3600 then "#{seconds / 60}m ago"
+        elsif seconds < 86_400 then "#{seconds / 3600}h ago"
+        else "#{seconds / 86_400}d ago"
+        end
+      end
+
+      def paint(text, key)
+        @color ? "#{COLORS[key]}#{text}#{COLORS[:reset]}" : text
+      end
+
+      def code(key)
+        @color ? COLORS[key] : ""
+      end
+    end
+  end
+end

data/lib/onair/report.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Onair
+  # What renderers consume. Pure domain logic — all IO goes through the
+  # injected git wrapper; render output must be derivable from this alone.
+  #
+  # delta:   :current, Integer (commits behind), or nil (diverged/unknown —
+  #          silence over speculation).
+  # pinned:  a newer build succeeded but is not what's running.
+  # 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:)
+      # 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.
+      pinned = pinned?(snapshot)
+      snapshot = drop_stale_pending(snapshot)
+      deployed_sha = snapshot.deployed&.sha
+      mine = compute_mine(snapshot, git)
+      commits = [deployed_sha, snapshot.pending&.sha, mine&.sha].compact.uniq
+                                                                .to_h { |sha| [sha, git.commit_info(sha)] }
+      new(
+        snapshot: snapshot,
+        remote_head: remote_head,
+        delta: compute_delta(deployed_sha, remote_head, git),
+        pinned: pinned,
+        mine: mine,
+        commits: commits
+      )
+    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
+    # Pending and Deployed. A build that is already on air isn't pending.
+    def self.drop_stale_pending(snapshot)
+      return snapshot unless snapshot.pending && snapshot.pending.sha == snapshot.deployed&.sha
+
+      snapshot.with(pending: nil)
+    end
+
+    def self.compute_delta(sha, head, git)
+      return nil if sha.nil? || head.nil?
+      return :current if sha == head
+      return nil unless git.has_commit?(sha) && git.has_commit?(head)
+      return nil unless git.ancestor?(sha, head)
+
+      count = git.count_between(sha, head)
+      count&.positive? ? count : nil
+    end
+
+    def self.pinned?(snapshot)
+      sha = snapshot.deployed&.sha
+      latest = snapshot.latest_built_sha
+      !sha.nil? && !latest.nil? && latest != sha && snapshot.pending.nil?
+    end
+
+    # "Did my merge just ship?" — deliberately a 2-commit first-parent window
+    # below the deployed head, not a history search.
+    def self.compute_mine(snapshot, git)
+      sha = snapshot.deployed&.sha
+      return nil if sha.nil? || !git.has_commit?(sha)
+
+      identity = git.identity
+      info = git.commit_info(sha)
+      return nil if info.nil? || identity_match?(identity, info.author_name, info.author_email)
+
+      mine_sha, = git.first_parent_below(sha, 2).find { |_, name, email| identity_match?(identity, name, email) }
+      return nil if mine_sha.nil?
+
+      Mine.new(sha: mine_sha, had_own_build: snapshot.succeeded_shas.include?(mine_sha))
+    end
+
+    # Squash merges keep the author's name but may swap the email — match either.
+    def self.identity_match?(identity, name, email)
+      (!identity.email.to_s.empty? && email == identity.email) ||
+        (!identity.name.to_s.empty? && name == identity.name)
+    end
+
+    private_class_method :drop_stale_pending, :compute_delta, :pinned?, :compute_mine, :identity_match?
+  end
+end

data/lib/onair/task_link.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Onair
+  # Optional, tracker-agnostic task linking. Configured entirely by the user:
+  #
+  #   task:
+  #     pattern: 'ABC-\d+'
+  #     url: 'https://acme.atlassian.net/browse/{task}'
+  #
+  # Any regex match in a commit subject becomes a link to the templated URL
+  # ({task} is replaced with the matched text). No config — no behavior.
+  TaskLink = Data.define(:pattern, :url_template) do
+    def self.from_config(section)
+      return nil if section.nil?
+
+      pattern = section["pattern"].to_s
+      url = section["url"].to_s
+      raise Error, "task config needs both `pattern` and `url`" if pattern.empty? || url.empty?
+      raise Error, "task.url must contain the {task} placeholder" unless url.include?("{task}")
+
+      new(pattern: Regexp.new(pattern), url_template: url)
+    rescue RegexpError => e
+      raise Error, "invalid task.pattern: #{e.message}"
+    end
+
+    def find(subject)
+      subject&.[](pattern)
+    end
+
+    def url_for(task_id)
+      url_template.gsub("{task}", task_id)
+    end
+  end
+end

data/lib/onair/version.rb

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

data/lib/onair.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "onair/version"
+
+module Onair
+  class Error < StandardError
+  end
+
+  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.
+  Deployed = Data.define(:sha, :version, :description, :deployed_at)
+
+  Pending = Data.define(:sha, :started_at)
+
+  # 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, :latest_built_sha, :succeeded_shas)
+
+  Mine = Data.define(:sha, :had_own_build)
+end
+
+require_relative "onair/task_link"
+require_relative "onair/config"
+require_relative "onair/git"
+require_relative "onair/report"
+require_relative "onair/orchestrator"
+require_relative "onair/auth/netrc"
+require_relative "onair/auth/heroku_cli"
+require_relative "onair/auth/github_token"
+require_relative "onair/remote_head"
+require_relative "onair/platform/base"
+require_relative "onair/platform/heroku"
+require_relative "onair/renderer/tty"
+require_relative "onair/renderer/json"
+require_relative "onair/cli"

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: onair-cli
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eugene
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Reports which commit is actually running in production and where it sits
+  relative to origin/main. Truthful after rollbacks, fast, zero runtime dependencies.
+email:
+- amber.pixels.io@gmail.com
+executables:
+- onair
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/onair
+- lib/onair.rb
+- lib/onair/auth/github_token.rb
+- lib/onair/auth/heroku_cli.rb
+- lib/onair/auth/netrc.rb
+- lib/onair/cli.rb
+- lib/onair/config.rb
+- lib/onair/git.rb
+- lib/onair/orchestrator.rb
+- lib/onair/platform/base.rb
+- lib/onair/platform/heroku.rb
+- lib/onair/remote_head.rb
+- lib/onair/renderer/json.rb
+- lib/onair/renderer/tty.rb
+- lib/onair/report.rb
+- lib/onair/task_link.rb
+- lib/onair/version.rb
+homepage: https://github.com/amberpixels/onair-cli
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/amberpixels/onair-cli
+  changelog_uri: https://github.com/amberpixels/onair-cli/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.15
+specification_version: 4
+summary: See what's on air in production.
+test_files: []