gem-contribute 0.1.0

data/docs/index.md

@@ -0,0 +1,102 @@
+---
+title: gem-contribute
+---
+
+# gem-contribute
+
+Find contributable issues in the gems your project already depends on.
+
+```sh
+$ gem install gem-contribute
+$ gem-contribute scan
+44 gems · 42 on github.com · 2 unknown source
+
+Top contributable projects (by open `good first issue` count):
+  rubocop          4  github.com/rubocop/rubocop
+  rspec            1  github.com/rspec/rspec
+  reline           1  github.com/ruby/reline
+  ...
+```
+
+The premise: the gems in your `Gemfile.lock` are the projects you have the most context on. If you depend on `sidekiq`, you have opinions about Sidekiq. That's a better starting point for open-source contribution than scanning all of GitHub for `good-first-issue` tags and hoping one looks interesting.
+
+## Quick start
+
+```sh
+gem install gem-contribute            # one-time install
+gem-contribute auth login             # one-time GitHub OAuth (device flow, no token paste)
+gem-contribute scan                   # see what's worth contributing to
+gem-contribute issues rubocop         # drill into one project's issues
+gem-contribute fix rubocop/12345      # fork, clone, branch (~/code/oss/<owner>/<repo>)
+# ... make your change, commit ...
+gem-contribute submit                 # push, then open the PR compare page in your browser
+```
+
+[Full command reference →](#commands) ・ [Configuration →](#configuration)
+
+## Status
+
+- **v0.1**: a CLI with `scan`, `issues`, `auth`, `fix`, `submit`, and `config`. GitHub-only.
+- **Planned**: a Rooibos TUI that does all of the above as a single keyboard-driven session ([issue #2](https://github.com/cdhagmann/gem-contribute/issues/2)).
+- **Workshop project**: built for [Blue Ridge Ruby 2026](https://blueridgeruby.com).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `gem-contribute scan [path]` | Parse `Gemfile.lock`, resolve each gem to its source repo, rank GitHub-hosted projects by open `good first issue` count. |
+| `gem-contribute issues <gem>` | List the open good-first-issues for one gem with number, title, and URL. |
+| `gem-contribute issues all` | Iterate every github.com gem in the lockfile; print only those with open issues. |
+| `gem-contribute auth login` | Authenticate with GitHub via OAuth device flow (no token paste, no client secret). |
+| `gem-contribute auth status` | Show whether the cached token is still valid. |
+| `gem-contribute auth logout` | Drop the cached token. |
+| `gem-contribute fix <gem>/<n>` | Fork the gem's repo, clone the fork to `<clone_root>/<owner>/<repo>`, branch from default. Alias: `fork-clone-branch`. |
+| `gem-contribute submit` | From inside a clone, push the current branch and open a pre-filled PR compare page in your browser. |
+| `gem-contribute config set <k> <v>` | Persist user preferences. |
+| `gem-contribute config list` | Show current configuration. |
+
+Global flags: `--refresh` (clear cache), `--version`, `-h/--help`.
+
+## Configuration
+
+User config lives at `~/.config/gem-contribute/config.yml`.
+
+| Key | Default | Notes |
+|---|---|---|
+| `clone_root` | `~/code/oss` | Where `fix` clones forks (`<root>/<owner>/<repo>`). |
+
+Manage with `gem-contribute config set <key> <value>` rather than editing the YAML by hand.
+
+## Authentication
+
+`gem-contribute auth login` uses GitHub's [OAuth device flow](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow). The flow:
+
+1. The CLI requests a one-time code from GitHub.
+2. Your terminal prints the code and (on macOS / Linux) copies it to your clipboard and opens [github.com/login/device](https://github.com/login/device) in your browser.
+3. You paste the code, click Authorize.
+4. The CLI's pending poll succeeds; the token is cached at `~/.config/gem-contribute/auth.json` (mode 0600).
+
+This is the same UX `gh auth login` uses. The OAuth App is `gem-contribute`, registered to the gem's maintainer; users do not need to register their own.
+
+Tokens are scoped to `public_repo` only — enough to fork, clone, and read public issues, not enough to touch private repositories. If you ever want to revoke, visit [your authorized apps](https://github.com/settings/applications) and remove `gem-contribute`.
+
+## Design
+
+For the architecture overview, see [`design.md`](design.md). For specific decisions and the reasoning behind them, see the [ADRs](adr/).
+
+The short version:
+
+- **Scan first, auth lazily.** No token needed to read public issue counts.
+- **Abstract the host.** GitHub today, GitLab and others later. The data model is host-agnostic.
+- **Render verbatim.** Don't normalize labels. Don't summarize CONTRIBUTING.md.
+- **No threads.** All async work is structured for Rooibos Commands so the TUI can wrap it without rewrites.
+
+## Contributing
+
+The tool is *for* finding contributable projects, so it had better be one. See [`CONTRIBUTING.md`](https://github.com/cdhagmann/gem-contribute/blob/main/CONTRIBUTING.md) and [open issues tagged `good first issue`](https://github.com/cdhagmann/gem-contribute/issues?q=is%3Aopen+label%3A%22good+first+issue%22).
+
+If you're attending Blue Ridge Ruby 2026 and arrived here from the workshop, see [`workshop.md`](workshop.md) for the exercises.
+
+## License
+
+MIT. See [LICENSE](https://github.com/cdhagmann/gem-contribute/blob/main/LICENSE).

data/docs/prep-plan.md

@@ -0,0 +1,165 @@
+# Pre-conference prep plan
+
+The Blue Ridge Ruby workshop is **April 30 – May 1, 2026**. This document defines what "ready" means and the order of operations to get there.
+
+This plan is meant to be executed agentically by Claude Code, with Chris reviewing at stage boundaries. Read [`CLAUDE.md`](../CLAUDE.md), [`docs/design.md`](design.md), and the [`ADRs`](adr/) before starting. They define the architecture and constraints.
+
+## Honest scope estimate
+
+The five stages below total **roughly 12–20 hours of focused work**. That's more than three weeknight evenings. The plan is structured so that **each stage produces a usefully-complete artifact** — if you run out of time, you stop at the last finished stage and the workshop still works.
+
+Minimum viable workshop = Stages 1, 2, and 4 done. Stage 3 (the TUI) can become the workshop itself if it isn't built ahead.
+
+## Order of work
+
+### Stage 1 — Data pipeline end-to-end
+
+**Goal:** A CLI script that reads `Gemfile.lock` from the current directory, resolves source URLs via RubyGems, and prints a summary table — without auth, without the TUI, without the action. Proves the data layer works.
+
+**Acceptance:**
+
+- [ ] `gem-contribute scan` (or equivalent) prints something like:
+  ```
+  47 gems · 44 on github.com · 2 on gitlab.com · 1 unknown source
+  Top contributable projects (by open `good first issue` count):
+    sidekiq           5  github.com/sidekiq/sidekiq
+    standard          3  github.com/standardrb/standard
+    ...
+  ```
+- [ ] `LockfileParser` wraps `Bundler::LockfileParser` (per ADR-0002), returns `Gem` structs
+- [ ] `Resolver` hits RubyGems v1 API anonymously, prefers `bug_tracker_uri` (per ADR-0003), falls back per the ADR
+- [ ] `HostAdapter` interface defined; `GitHubAdapter` implements the unauthenticated read methods (`issues`, `community_profile`, `file_contents`)
+- [ ] Disk caching at `~/.cache/gem-contribute/` per the design doc
+- [ ] Unit tests for the parser and resolver. VCR cassettes for the adapter. All commit-clean.
+- [ ] `bin/rspec` and `bin/rubocop` pass
+
+**Deliberately not in this stage:**
+- No auth code. Anonymous GitHub API only.
+- No TUI. CLI output via plain `puts`.
+- No fork-clone-branch. That's Stage 2.
+- No Rooibos dependency yet.
+
+**Stop here and check in with Chris.** Demo the script against `gem-contribute`'s own `Gemfile.lock`. The output should make Chris want to keep going.
+
+### Stage 2 — Auth and the action
+
+**Goal:** Add device-flow auth and the fork-clone-branch action. Still no TUI; everything is CLI flags. Proves the auth and action layers work.
+
+**Acceptance:**
+
+- [ ] `Auth` module implements the OAuth 2.0 Device Authorization Grant against `github.com` per ADR-0004
+- [ ] OAuth App client ID is a public constant in source (no secret); document the registration step in a `MAINTAINER.md` or similar
+- [ ] Token storage at `~/.config/gem-contribute/auth.json`, mode 0600
+- [ ] Polling respects `slow_down` errors and the 15-minute device-code expiry
+- [ ] `gem-contribute auth login` and `gem-contribute auth status` CLI commands work
+- [ ] `GitHubAdapter` gains `fork`, `already_forked?` methods that raise `AuthRequired` if no token
+- [ ] A `fork-clone-branch` CLI subcommand takes a `gem/issue_number` argument, performs the full sequence, prints the local path
+- [ ] Unit tests for the auth state machine (the protocol is deterministic — test it)
+- [ ] Integration test gated on `GEM_CONTRIBUTE_INTEGRATION=1` against a small friendly gem
+- [ ] **Use the tool to open one real PR** — even a typo fix in a README. The proof that the architecture works.
+
+**Deliberately not in this stage:**
+- No TUI. The workflow is multiple CLI invocations.
+- No JIT prompting. If unauthenticated, error and tell the user to run `auth login`.
+- Scope is `public_repo` only.
+
+**Stop here and check in with Chris.** Demo the full CLI flow end-to-end. If the architecture has problems, this is when they show up.
+
+### Stage 3 — TUI with Rooibos
+
+**Goal:** The full TUI per the design doc. Four fragments + auth overlay. JIT auth working through MVU state transitions. This is the v0.1 the workshop attendees see.
+
+**Acceptance:**
+
+- [ ] `rooibos` pinned to `~> 0.7.0` in the gemspec (verify the pinned version against current rubygems.org before committing)
+- [ ] `ProjectList` fragment: lists gems from the lockfile with issue counts (lazy-loaded via `Command.http`)
+- [ ] `IssueList` fragment: open issues for selected project, labels rendered verbatim per ADR-0005
+- [ ] `IssueDetail` fragment: body, labels, action keys (`f`, `c`, `o`)
+- [ ] `ContributingViewer` fragment: rendered markdown per ADR-0007
+- [ ] `AuthOverlay` fragment: device-flow prompt that fires on `:auth_required`, retries the original action on success
+- [ ] All async work goes through Rooibos Commands. No `Thread.new`, no `Async`.
+- [ ] `Update` tests for every fragment, covering at minimum each key handler and each command-result message
+- [ ] At least one snapshot test for the main flow (project list → issue list → issue detail)
+- [ ] Status bar showing rate limit remaining
+- [ ] `q` quits, `Ctrl+C` quits, `?` shows help overlay (or note help is unimplemented in the README)
+- [ ] `bin/gem-contribute` from any directory with a `Gemfile.lock` launches the TUI
+
+**Deliberately not in this stage:**
+- No label normalization (ADR-0005)
+- No CONTRIBUTING parsing (ADR-0007)
+- No private-repo support
+- No `Worker` orchestrator class — fork-clone-branch is a state machine in `Update`
+
+**Stop and check in with Chris.** This is the demo for the workshop opening.
+
+### Stage 4 — Workshop issues
+
+**Goal:** Twelve good-first-issue tickets that workshop attendees can pick from. The meta-joke: a tool for finding good first issues that itself has good first issues.
+
+**Acceptance:**
+
+- [ ] Twelve markdown files in `docs/workshop-issues/`, one per issue, using the template at `.github/ISSUE_TEMPLATE/workshop-issue.md`
+- [ ] Each issue is genuinely scoped to ~30 minutes by someone who hasn't seen the codebase
+- [ ] Each issue points at a specific file or module
+- [ ] Each issue has acceptance criteria that are testable
+- [ ] Each issue links to relevant ADRs if a decision constrains the implementation
+- [ ] Mix of difficulty: ~4 trivial (status bar tweak, empty state copy, new keybinding), ~6 moderate (new feature, small refactor, additional adapter method), ~2 stretch (rate-limit handling, accessibility pass)
+
+**Suggested topics** (pick the strongest 12, generate more if needed):
+
+- Rate-limit indicator in the status bar
+- `homepage_uri` fallback for unresolved gems
+- `r` to refresh the current view
+- CONTRIBUTING preview in the issue detail pane
+- `--version` flag
+- Better empty state when no gems have GitHub URLs
+- Highlight preferred labels (per config) in the issue list
+- `?` help overlay
+- "Authenticated as @user" indicator
+- Sort gems by issue count
+- Skip path/git source gems with a clear status line
+- Confirmation dialog before fork-clone-branch
+- `o` to open the gem's homepage in browser
+- "Last updated" warning for stale-looking gems
+
+**Deliberately not in this stage:**
+- Don't create the actual GitHub issues yet. Markdown files in the repo. Chris will create the GitHub issues himself once the repo is public, using these as the source.
+
+### Stage 5 — Workshop tutorial polish
+
+**Goal:** Polish `docs/workshop.md` so attendees can follow it end-to-end without help. Add anything attendees need that isn't already in the README.
+
+**Acceptance:**
+
+- [ ] `docs/workshop.md` covers: pre-arrival setup (Ruby version, Rust toolchain, GitHub account), repo clone, `bundle install`, first-run device flow, the workshop arc
+- [ ] Pre-reading section linking to Rooibos's "Why Rooibos" and Rails-developer guide
+- [ ] Setup troubleshooting section for common build failures (`ratatui_ruby` Rust toolchain, `rooibos` installation issues, GitHub OAuth quirks)
+- [ ] A "first PR template" — a 5-step walkthrough for an attendee who's never opened a PR, using one of the workshop issues as the example
+- [ ] README's Quick Start section mirrors the workshop setup steps so non-attendees have the same path
+
+**Deliberately not in this stage:**
+- No video or screencast. Words on a page is fine.
+- No deep Ratatui or Rooibos tutorial — link out to upstream docs.
+
+## Definition of "ready for the workshop"
+
+You're ready when, on a fresh laptop:
+
+1. `git clone … && cd gem-contribute && bundle install` succeeds
+2. `bin/gem-contribute` launches the TUI against a real `Gemfile.lock`
+3. `f` on an issue completes the fork-clone-branch flow with the device-flow prompt firing
+4. The workshop issues are visible on the public GitHub repo with the `workshop` label
+5. `docs/workshop.md` reads cleanly to someone who hasn't seen the project
+
+Anything else is a stretch goal.
+
+## What to do if you're behind schedule
+
+Cut in this order:
+
+1. **Skip Stage 5 polish.** Workshop README at minimum-viable quality is fine.
+2. **Cut Stage 4 to 6 issues instead of 12.** Quality matters more than count.
+3. **Cut Stage 3 fragments.** `ContributingViewer` is the most droppable; users can read CONTRIBUTING in their browser. `AuthOverlay` can fall back to a CLI prompt during `f` action.
+4. **If Stage 3 doesn't ship at all:** the workshop becomes "let's build the TUI together." This is honestly fine and might be a *better* workshop. Be ready to pivot the framing.
+
+Don't cut tests to save time. Tests are how this gets maintained after you're tired.

data/docs/workshop.md

@@ -0,0 +1,60 @@
+# Workshop — Blue Ridge Ruby 2026
+
+90-minute workshop, then open hacking.
+
+## Premise
+
+You depend on dozens of gems. Some of those projects need help. This tool finds the overlap. We built v0.1; you're going to make it better.
+
+## Before the workshop
+
+- Ruby 3.2+
+- A GitHub account
+- 5 minutes to clone and `bundle install`
+
+```
+git clone https://github.com/cdhagmann/gem-contribute
+cd gem-contribute
+bundle install
+bin/gem-contribute
+```
+
+If `bundle install` complains about `ratatui_ruby` building a native extension, you need a Rust toolchain. On macOS: `xcode-select --install` is usually enough. On Linux: `sudo apt install build-essential` plus `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`.
+
+If you can't get the build working, pair with someone who can. The workshop scales fine with two-person teams.
+
+## Arc
+
+**0:00 — 0:15 · Demo and tour**
+
+I run the tool against a real Gemfile.lock. We walk through what each pane does, then through the architecture (`docs/design.md`).
+
+**0:15 — 0:30 · Architecture overview**
+
+The four-stage pipeline: parse → resolve → adapt → render. Where things are, why they're separate, what an adapter looks like. The point is to give you enough mental model to know where your changes go.
+
+**0:30 — 1:00 · Exercise: build a feature**
+
+Pick one issue from `https://github.com/cdhagmann/gem-contribute/issues?q=label:workshop`. They're scoped to be doable in 30 minutes by someone who's never touched the codebase. Examples:
+
+- Add a "rate limit remaining" indicator to the status bar
+- Support `bug_tracker_uri` fallback to `homepage_uri` for older gems
+- Add a `r` keybinding that refreshes the current view
+- Show CONTRIBUTING.md preview in the issue detail pane
+
+If you finish, pick another. If you don't finish, that's fine — open a PR with what you have and we'll land it together.
+
+**1:00 — 1:30 · Show and tell, plus the contribute-the-tool flow**
+
+Anyone who wants to demo their change does. Then I run `gem-contribute` against this repo's own Gemfile.lock and we use the tool to find issues to contribute to *in our actual dependencies*.
+
+**1:30 — end of day · Open hacking**
+
+Stay if you want. Work on this tool, or — better — use it on a project you depend on. The goal of the rest of the day is at least one merged PR per attendee, somewhere. Doesn't have to be here.
+
+## Ground rules
+
+- Ask anyone, including me, anything.
+- "I don't know" is a fine answer to anything; we figure it out together.
+- If you're stuck on setup for more than 15 minutes, raise a hand.
+- This is a hack day. Imperfect contributions are the point.

data/exe/gem-contribute

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "gem_contribute"
+require "gem_contribute/cli"
+
+exit GemContribute::CLI.run(ARGV)

data/lib/gem_contribute/auth.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module GemContribute
+  # OAuth 2.0 Device Authorization Grant against github.com. See ADR-0004.
+  #
+  # Pure state-machine design:
+  #
+  #   request_device_code(client_id) → DeviceCode | raises AuthError
+  #   poll(device_code, client_id)    → Result    (status: :ok | :pending |
+  #                                                :slow_down | :expired |
+  #                                                :denied | :error)
+  #
+  # The CLI orchestrates these with sleep-based polling. The future Stage 3
+  # TUI wraps the same functions in Rooibos Command.http / Command.wait
+  # without changing the protocol. ADR-0008 stays clean because the
+  # state-transition functions don't own any I/O orchestration themselves —
+  # they're pure request/response.
+  module Auth
+    DEVICE_CODE_URL = "https://github.com/login/device/code"
+    TOKEN_URL = "https://github.com/login/oauth/access_token"
+    DEFAULT_SCOPE = "public_repo"
+
+    # OAuth App Client ID. Public by design — see ADR-0004 and MAINTAINER.md.
+    # The sentinel below is intentionally unusable; replace with the real
+    # value after walking through MAINTAINER.md's OAuth App registration.
+    CLIENT_ID = ENV.fetch("GEM_CONTRIBUTE_CLIENT_ID", "Ov23liZNcwIo17OIVUsv")
+
+    DeviceCode = Data.define(:device_code, :user_code, :verification_uri, :expires_at, :interval) do
+      def expired?(now: Time.now)
+        now >= expires_at
+      end
+
+      def with_interval(new_interval)
+        self.class.new(
+          device_code: device_code,
+          user_code: user_code,
+          verification_uri: verification_uri,
+          expires_at: expires_at,
+          interval: new_interval
+        )
+      end
+    end
+
+    # Result of one polling step.
+    #
+    # status:
+    #   :ok        — token attached
+    #   :pending   — user hasn't completed yet; poll again at the same interval
+    #   :slow_down — user hasn't completed yet; back off (caller bumps interval)
+    #   :expired   — device code is past its 15-minute window
+    #   :denied    — user actively rejected
+    #   :error     — anything else; error_message attached
+    Result = Data.define(:status, :token, :scope, :error_message)
+
+    class AuthError < GemContribute::Error
+    end
+
+    module_function
+
+    # Step 1: request a device code.
+    #
+    # @return [DeviceCode]
+    def request_device_code(client_id, scope: DEFAULT_SCOPE, http: Net::HTTP, clock: -> { Time.now })
+      check_client_id!(client_id)
+
+      response = post_form(DEVICE_CODE_URL, { client_id: client_id, scope: scope }, http: http)
+      raise AuthError, "device code request failed: HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+      body = JSON.parse(response.body)
+      raise AuthError, "device code request returned: #{body["error"]}" if body["error"]
+
+      build_device_code(body, clock: clock)
+    end
+
+    # Step 2: one polling step. Call repeatedly until status != :pending and
+    # != :slow_down.
+    #
+    # @return [Result]
+    def poll(device_code, client_id, http: Net::HTTP)
+      check_client_id!(client_id)
+
+      response = post_form(
+        TOKEN_URL,
+        {
+          client_id: client_id,
+          device_code: device_code.device_code,
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code"
+        },
+        http: http
+      )
+
+      build_result(response)
+    end
+
+    # Caller convention: device-flow errors are protocol states, not
+    # exceptions. Network / parse errors raise. Returning a Result keeps the
+    # state machine pure.
+    def build_result(response)
+      unless response.is_a?(Net::HTTPSuccess)
+        return Result.new(status: :error, token: nil, scope: nil,
+                          error_message: "HTTP #{response.code}")
+      end
+
+      body = JSON.parse(response.body)
+      classify_body(body)
+    end
+
+    def classify_body(body)
+      if body["access_token"]
+        Result.new(status: :ok, token: body["access_token"], scope: body["scope"], error_message: nil)
+      else
+        case body["error"]
+        when "authorization_pending"
+          Result.new(status: :pending, token: nil, scope: nil, error_message: nil)
+        when "slow_down"
+          Result.new(status: :slow_down, token: nil, scope: nil, error_message: nil)
+        when "expired_token"
+          Result.new(status: :expired, token: nil, scope: nil, error_message: nil)
+        when "access_denied"
+          Result.new(status: :denied, token: nil, scope: nil, error_message: nil)
+        else
+          Result.new(status: :error, token: nil, scope: nil, error_message: body["error"] || "unknown")
+        end
+      end
+    end
+
+    def check_client_id!(client_id)
+      return unless client_id.nil? || client_id.empty? || client_id == "FILL_ME_IN_FROM_MAINTAINER_MD"
+
+      raise AuthError,
+            "GemContribute::Auth::CLIENT_ID is not set. Walk through MAINTAINER.md to register " \
+            "an OAuth App, then paste the Client ID into lib/gem_contribute/auth.rb (or set " \
+            "GEM_CONTRIBUTE_CLIENT_ID in the environment for testing)."
+    end
+
+    def build_device_code(body, clock:)
+      DeviceCode.new(
+        device_code: body.fetch("device_code"),
+        user_code: body.fetch("user_code"),
+        verification_uri: body.fetch("verification_uri"),
+        expires_at: clock.call + body.fetch("expires_in"),
+        interval: body.fetch("interval")
+      )
+    end
+
+    def post_form(url, params, http:)
+      uri = URI(url)
+      http.start(uri.host, uri.port, use_ssl: true) do |conn|
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request["Accept"] = "application/json"
+        request["User-Agent"] = "gem-contribute/#{GemContribute::VERSION}"
+        request.set_form_data(params)
+        conn.request(request)
+      end
+    end
+  end
+end

data/lib/gem_contribute/cache.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+
+module GemContribute
+  # Disk cache at ~/.cache/gem-contribute/<namespace>/<key>.json.
+  #
+  # Honors XDG_CACHE_HOME so tests (and users with non-default XDG layouts)
+  # don't pollute each other.
+  #
+  # Per docs/design.md the namespaces and TTLs are:
+  #   gems    — RubyGems metadata           — 7 days
+  #   issues  — GitHub issue lists          — 5 minutes
+  #   repos   — community profile responses — 1 day
+  #   files   — file contents (CONTRIBUTING) — 1 day
+  #
+  # The cache stores `{stored_at:, payload:}` so the TTL check is local rather
+  # than dependent on filesystem mtime (which differs across platforms).
+  class Cache
+    DEFAULT_NAMESPACE_TTL = {
+      "gems" => 7 * 24 * 60 * 60,
+      "issues" => 5 * 60,
+      "repos" => 24 * 60 * 60,
+      "files" => 24 * 60 * 60
+    }.freeze
+
+    attr_reader :root
+
+    def initialize(root: Cache.default_root, ttl: DEFAULT_NAMESPACE_TTL, clock: -> { Time.now.to_i })
+      @root = root
+      @ttl = ttl
+      @clock = clock
+    end
+
+    # Look up a cached value. Returns the payload Hash or nil.
+    # Expired entries are treated as misses but left on disk; the next write
+    # overwrites them. (Aggressive deletion costs IO for no real gain.)
+    def fetch(namespace, key)
+      path = path_for(namespace, key)
+      return nil unless File.file?(path)
+
+      data = read_json(path)
+      return nil if data.nil?
+      return nil if expired?(namespace, data)
+
+      data["payload"]
+    end
+
+    # Cache a payload. Returns the payload as given.
+    def write(namespace, key, payload)
+      path = path_for(namespace, key)
+      FileUtils.mkdir_p(File.dirname(path))
+
+      tmp = "#{path}.tmp"
+      File.write(tmp, JSON.generate("stored_at" => @clock.call, "payload" => payload), encoding: "UTF-8")
+      File.rename(tmp, path)
+      payload
+    end
+
+    # Clear every namespace under the cache root. Powers `--refresh`.
+    def clear!
+      FileUtils.rm_rf(@root) if File.directory?(@root)
+    end
+
+    def self.default_root
+      base = ENV["XDG_CACHE_HOME"] || File.expand_path("~/.cache")
+      File.join(base, "gem-contribute")
+    end
+
+    private
+
+    def path_for(namespace, key)
+      File.join(@root, namespace, "#{safe_key(key)}.json")
+    end
+
+    def safe_key(key)
+      # Keys can contain slashes (`owner/repo`); hash them so we don't have to
+      # mkdir_p arbitrary trees and so collisions across namespaces stay tidy.
+      Digest::SHA256.hexdigest(key.to_s)
+    end
+
+    def read_json(path)
+      JSON.parse(File.read(path, encoding: "UTF-8"))
+    rescue JSON::ParserError, Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+      nil
+    end
+
+    def expired?(namespace, data)
+      ttl = @ttl[namespace] || @ttl[namespace.to_s]
+      return false if ttl.nil?
+
+      stored_at = data["stored_at"].to_i
+      (@clock.call - stored_at) > ttl
+    end
+  end
+end