gem-contribute 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f6941e81cacd8ab2bb7abb6824bb54d5b04ec05789d24c792b48eb4c5125e02
+  data.tar.gz: 9a548392f2d027dbc99719d74de627940086e3858fd5c5152fa8d4ecffddb7b8
+SHA512:
+  metadata.gz: 1a4c00ea48ba2ef0245f3564d97b2bb0e6d3eb7098a79ef598a58dda95c6130630648e04351e8a5ef7f767456d938a836c647aa02c18d7b22663816a6b9d7d2e
+  data.tar.gz: 1d60a359d87cc17ba4e2c8bad1acab5f039334df63afd34055165d1a61b569e3c9c7fd57f5159d33ed0031e7634cabb93fd1b82e52f36cd4a5d0e30bfd2ef2ca

data/.github/ISSUE_TEMPLATE/workshop-issue.md

@@ -0,0 +1,29 @@
+---
+name: Workshop issue
+about: A small, scoped task suitable for a workshop attendee
+title: ''
+labels: ['good first issue', 'workshop']
+assignees: ''
+---
+
+## What
+
+One sentence describing the change.
+
+## Why
+
+One sentence on the user-facing reason this matters.
+
+## Where
+
+File or module where the work happens. Be specific — workshop time is short.
+
+## Acceptance
+
+- [ ] Specific, testable criterion 1
+- [ ] Specific, testable criterion 2
+- [ ] Test added or updated where appropriate
+
+## Hints
+
+Anything a stranger to the codebase needs to know. Link to relevant ADRs if a decision constrains the implementation.

data/.github/workflows/auto-merge-kicked-tires.yml

@@ -0,0 +1,88 @@
+name: Auto-merge KICKED_THE_TIRES.yml PRs
+
+# Triggers on PRs that touch KICKED_THE_TIRES.yml. If the PR ONLY touches
+# that file and the YAML passes the schema check, the PR is squash-merged
+# automatically. Anything else (multi-file PRs, malformed YAML, schema
+# violations) leaves the PR open for manual review.
+#
+# Security note: we use pull_request_target so the workflow itself runs
+# from the base branch (trusted) and has write permissions, but we never
+# check out the PR HEAD. The proposed YAML is fetched via the GitHub API
+# as text — it's data, not code, and is never executed.
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+    paths:
+      - 'KICKED_THE_TIRES.yml'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  validate-and-merge:
+    runs-on: ubuntu-latest
+    steps:
+      # Default checkout (no `ref:`) gets the BASE branch, not the PR HEAD.
+      # Our lint script lives there and is trusted.
+      - uses: actions/checkout@v4
+
+      - name: Confirm only KICKED_THE_TIRES.yml changed
+        id: check
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          changed=$(gh pr diff "$PR_NUMBER" --repo "$REPO" --name-only)
+          echo "Files in this PR:"
+          echo "$changed"
+
+          if [ "$changed" = "KICKED_THE_TIRES.yml" ]; then
+            echo "auto_merge=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "auto_merge=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::PR touches files beyond KICKED_THE_TIRES.yml; skipping auto-merge."
+          fi
+
+      - name: Fetch the proposed YAML content
+        if: steps.check.outputs.auto_merge == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          # Pull the file via the API rather than checking out the PR HEAD.
+          gh api "/repos/$REPO/contents/KICKED_THE_TIRES.yml?ref=$PR_HEAD_SHA" \
+            -H "Accept: application/vnd.github.raw" > KICKED_THE_TIRES.yml
+
+      - name: Validate schema
+        if: steps.check.outputs.auto_merge == 'true'
+        run: ruby script/lint-kicked-tires.rb
+
+      - name: Auto-merge
+        if: steps.check.outputs.auto_merge == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+        run: |
+          set -euo pipefail
+          gh pr comment "$PR_NUMBER" --repo "$REPO" \
+            --body "🎉 Thanks @${PR_AUTHOR} for kicking the tires! Auto-merging."
+          gh pr merge "$PR_NUMBER" --repo "$REPO" --squash --delete-branch
+
+      - name: Comment on validation failure
+        if: failure() && steps.check.outputs.auto_merge == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          gh pr comment "$PR_NUMBER" --repo "$REPO" \
+            --body "❌ Auto-merge skipped — the YAML didn't pass validation. See the [run log]($RUN_URL) for the specific error, then push a fix and the workflow will re-run."

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-28
+
+### Added
+
+- `gem-contribute scan [path]` — parse a `Gemfile.lock`, resolve each gem to its source repository, and rank GitHub-hosted projects by open `good first issue` count.
+- `gem-contribute issues <gem|all>` — list open good-first-issues for a single gem or every github.com-hosted gem in the lockfile.
+- `gem-contribute auth login|status|logout` — OAuth device-flow authentication with GitHub. Token cached at `~/.config/gem-contribute/auth.json` (mode 0600). The login flow auto-copies the one-time code to the clipboard and opens the verification URL in the browser.
+- `gem-contribute fix <gem>/<issue#>` (alias: `fork-clone-branch`) — fork the gem's repo, clone the fork to `<clone_root>/<owner>/<repo>`, create a `gem-contribute/issue-<N>` branch from the default, and add an `upstream` remote pointing at the canonical project.
+- `gem-contribute submit` — push the current branch to the user's fork and open a pre-filled GitHub compare page in the browser. The PR title and body are pre-populated from the issue (`Closes #<N>.`); the user reviews and submits via the web UI.
+- `gem-contribute config set|get|list` — persistent user configuration at `~/.config/gem-contribute/config.yml`. `clone_root` controls where `fix` puts forks.
+- `gem-contribute --refresh` — clear the disk cache before running (useful when source repositories have changed faster than the cache TTLs).
+- gem-contribute auto-injects itself into its own `scan` and `issues` results, so the tool you're using is always one of the contribution targets you can see.
+- Follows GitHub 301 redirects automatically when a repository has been renamed (e.g. `rainbow` → `ku1ik/rainbow`), so renamed projects keep their place in the rankings.
+
+### Notes
+
+- v0.1 is GitHub-only. The `HostAdapter` interface is already in place so GitLab and others can land later without disturbing the data model.
+- A Rooibos TUI on top of these commands is planned (see [issue #2](https://github.com/cdhagmann/gem-contribute/issues/2)).

data/CLAUDE.md

@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+This file is read by Claude Code when working in this repository. Treat it as the contract for how to make changes here.
+
+## Project shape
+
+`gem-contribute` is a terminal UI that reads a project's `Gemfile.lock`, surfaces open contributable issues from the gems' source repositories, and offers one-keystroke fork-clone-branch.
+
+Read `docs/design.md` and the ADRs in `docs/adr/` before making non-trivial changes. The design doc describes the architecture and the ADRs explain why specific decisions were made. If a change conflicts with an ADR, propose updating the ADR first; don't silently violate it.
+
+## Working agreement
+
+- **Decisions before code.** When uncertain about an architectural question, surface the question and the alternatives instead of picking one and writing code. The ADR pattern in `docs/adr/` is how those decisions get recorded.
+- **Small PRs.** Each change should be reviewable in one sitting. Multi-commit PRs are fine; multi-concern PRs are not.
+- **Test what's testable.** Parsers, resolvers, adapters, and `Update` functions all get tests. View tests assert colors and modifiers. System tests inject events and snapshot results. (The earlier "no TUI tests at v1" stance is obsolete; see ADR-0008.)
+- **Match existing style.** Run `bin/rubocop` before opening a PR.
+- **Don't reach across boundaries.** The TUI layer talks to the data layer only through Commands and messages. Adapters don't read config files; they receive what they need as arguments. The boundaries exist for testability and for the offline mode.
+- **Async work is always a Rooibos Command.** Don't spawn threads. Don't use `Async`. Don't shell out synchronously. If it can take longer than ~50ms, it's a Command.
+
+## What's deliberately out of scope
+
+The following are not bugs, they are design decisions. Don't "fix" them without first proposing an ADR update:
+
+- Label normalization (ADR-0005)
+- CONTRIBUTING.md parsing or summarization (ADR-0007)
+- Bundler plugin packaging (ADR-0006)
+- Direct threading or non-Rooibos async (ADR-0008)
+- PR creation from inside the TUI
+- Private repos or private gems at v1
+- A standalone `Worker` orchestrator class. Fork-clone-branch is a state machine in `Update` driven by Commands. No orchestrator.
+
+## Tooling notes
+
+- Ruby 3.2+ (Ractor support is required for Rooibos's thread-safe state)
+- `ratatui_ruby` requires a Rust toolchain to build
+- `rooibos` is the TUI framework on top of `ratatui_ruby`; pinned to `~> 0.7.0`
+- Cache lives at `~/.cache/gem-contribute/`; nuke it with `gem-contribute --refresh`
+- Auth tokens at `~/.config/gem-contribute/auth.json`, mode 0600
+- Config at `~/.config/gem-contribute/config.yml`
+
+## When proposing changes
+
+If you're adding a feature: which ADR(s) does it touch? If it doesn't touch any, do you need a new one?
+
+If you're fixing a bug: is there a regression test? If not, why not?
+
+If you're refactoring: what's the user-facing benefit? "Cleaner code" is not a benefit by itself.

data/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+Thanks for considering a contribution. This project is *about* lowering the friction to open-source contribution, so we try to walk our talk.
+
+## Quick start
+
+```
+git clone https://github.com/cdhagmann/gem-contribute
+cd gem-contribute
+bundle install
+bin/rspec               # tests should pass on a clean checkout
+bin/gem-contribute      # tool should run against this repo's own Gemfile.lock
+```
+
+## What we welcome
+
+- Bug fixes, with a regression test where reasonable
+- New host adapters (GitLab, Codeberg, sourcehut)
+- Better error messages — there's no such thing as too clear here
+- Documentation improvements, including in `docs/adr/` if you spot reasoning that's stale
+- Performance improvements with before/after numbers
+- Accessibility improvements to the TUI (color contrast, keyboard-only flows, screen-reader compatibility)
+
+## What we'd push back on
+
+- Label normalization (see [ADR-0005](docs/adr/0005-render-labels-verbatim.md))
+- Parsing CONTRIBUTING.md for structured data (see [ADR-0007](docs/adr/0007-display-contributing-verbatim.md))
+- AI-anything that summarizes, suggests, or rewrites maintainer-authored content
+- Bundler plugin packaging (see [ADR-0006](docs/adr/0006-standalone-gem-not-plugin.md)) — we'll consider it later, just not now
+
+If you have a strong case for any of the above, open an issue first and let's talk before you write code.
+
+## PR expectations
+
+- Run `bin/rubocop` and `bin/rspec` before pushing
+- Write a clear commit message; the PR description should explain *why*, not just *what*
+- New behavior gets a test
+- New decisions of any consequence get an ADR. They're short — see existing ones for the format
+
+## Code of Conduct
+
+Be kind. Assume good faith. The Ruby community deserves both. Specific incidents go to chris@example.com (placeholder — TODO: update before merging this).
+
+## AI assistance
+
+This project was built with significant AI assistance and we're not hiding that. If you use AI to help write a contribution, that's fine; what's not fine is shipping code you don't understand. The bar for review is the same regardless of how the code was authored: you can explain why every line is there, and you can defend the design choices.

data/KICKED_THE_TIRES.yml

@@ -0,0 +1,22 @@
+# People who've used gem-contribute against the sandbox issue (#5) to
+# practice the fork → clone → branch → submit loop end-to-end.
+#
+# To add yourself: append a new entry below. Anything beyond `handle` and
+# `date` is optional. `location` is reserved for a future Rooibos TUI
+# view that plots contributors on Ratatui's world-map widget; providing
+# it is opt-in. The map's geocoding script (added when that view lands)
+# turns these strings into lat/long.
+#
+# Schema:
+#   - handle: your-github-handle           # required, no leading @
+#     date: YYYY-MM-DD                     # required; the day you ran submit
+#     note: "one-line freeform message"    # optional
+#     location: "City, Region, Country"    # optional; e.g. "Asheville, NC, US"
+#                                          # or just "US" for country-level
+#
+# Use whatever precision you're comfortable with — "US" is fine.
+
+- handle: cdhagmann
+  date: 2026-04-28
+  note: "Built gem-contribute. First through the loop."
+  location: "Durham, NC, US"

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Dean Hagmann
+
+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/MAINTAINER.md

@@ -0,0 +1,92 @@
+# Maintainer notes
+
+This document is for the person who maintains the published `gem-contribute`
+gem. Most contributors will never need to read it. It captures the few
+out-of-band steps that can't be automated or committed.
+
+## OAuth App registration (one-time, required for Stage 2)
+
+`gem-contribute` authenticates users with GitHub via the OAuth 2.0 Device
+Authorization Grant. See [ADR-0004](docs/adr/0004-device-flow-auth.md) for
+why we picked device flow over Personal Access Tokens.
+
+Device flow needs only a **client ID**, no client secret. The client ID is a
+public value that ships in the source tree — there is nothing to protect.
+GitHub explicitly supports this pattern for CLI tools (see the [GitHub
+docs][gh-device-flow]).
+
+### Steps
+
+1. Sign in to the GitHub account that will own the OAuth App. For now this
+   is Chris's personal account. If the gem is later donated to a more
+   permanent home, the OAuth App migrates with it (you'd register a new App
+   under the new owner and update `CLIENT_ID` in `lib/gem_contribute/auth.rb`).
+
+2. Go to <https://github.com/settings/developers>.
+
+3. Click **"OAuth Apps"** in the left sidebar, then **"New OAuth App"**.
+
+4. Fill in the form:
+
+   | Field                          | Value                                                    |
+   |--------------------------------|----------------------------------------------------------|
+   | Application name               | `gem-contribute`                                         |
+   | Homepage URL                   | `https://github.com/cdhagmann/gem-contribute`            |
+   | Application description        | `Find and contribute to the gems in your Gemfile.lock.`  |
+   | Authorization callback URL     | `https://github.com/cdhagmann/gem-contribute`            |
+
+   The "Authorization callback URL" is a required field on the form but
+   isn't used by device flow. Pointing it at the repo URL is the
+   conventional dummy value.
+
+5. Click **"Register application"**.
+
+6. **Critical — enable Device Flow.** On the App's settings page after
+   registration, scroll down to the **"Device Flow"** section and check
+   **"Enable Device Flow"**, then click **"Update application"**. Without
+   this checkbox, the device-flow endpoints return
+   `device_flow_disabled` and the tool will not work. This step is easy to
+   miss because it's a separate save below the basic settings.
+
+7. Copy the **Client ID** from the App's settings page. It looks like
+   `Iv1.abcdef0123456789` for newer GitHub OAuth Apps or a 20-character
+   hex string for older ones. **Do not generate or copy a client secret.**
+   Device flow doesn't use one.
+
+8. Paste the Client ID back into the conversation with Claude Code, or
+   commit it directly to `lib/gem_contribute/auth.rb` as the value of the
+   `CLIENT_ID` constant. The current placeholder is a deliberate
+   sentinel that will raise at runtime.
+
+### Rate limits to know about
+
+- **50 device-code requests per hour, per OAuth App.** This is the cap on
+  *starting* a device flow, not on completing one. Workshop scale (~12
+  attendees) is comfortably under. If the tool ever sees enough adoption
+  to brush this limit, register additional OAuth Apps (and round-robin
+  client IDs) or migrate to a GitHub App with refresh-token logic.
+
+- **The user's own API rate limit** is the standard 5,000/hr authenticated.
+  No App-level cap.
+
+### Migrating the App later
+
+If `gem-contribute` moves to an org or a different maintainer:
+
+1. The new owner registers a fresh OAuth App following the steps above.
+2. Update `CLIENT_ID` in `lib/gem_contribute/auth.rb` and ship a new gem
+   release.
+3. Existing users will see one auth re-prompt the next time they invoke an
+   auth-required command, because the new client ID won't match the cached
+   token's issuer. That's acceptable — it's effectively a one-time
+   re-login event.
+
+The old OAuth App can stay registered for a transition period so users on
+older gem versions continue to work.
+
+## Cutting a release
+
+(Stub — fill in when we cut v0.1.0 to RubyGems. Notes will live here:
+gemspec metadata checks, `bundle exec rake release` flow, signing, etc.)
+
+[gh-device-flow]: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow

data/README.md

@@ -0,0 +1,89 @@
+# gem-contribute
+
+Find contributable issues in the gems your project already depends on.
+
+```
+$ gem-contribute scan
+Scanning Gemfile.lock (44 gems)...
+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
+  rspec-core       1  github.com/rspec/rspec
+  reline           1  github.com/ruby/reline
+  ...
+  gem-contribute   1  github.com/cdhagmann/gem-contribute
+```
+
+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.
+
+## Status
+
+Early. v0.1 is a CLI. A Rooibos TUI is planned (see [issue #2](https://github.com/cdhagmann/gem-contribute/issues/2)). This is being built as a workshop project for **[Blue Ridge Ruby 2026](https://blueridgeruby.com)**. Expect rough edges through the conference.
+
+## Install
+
+```
+gem install gem-contribute
+```
+
+Requires Ruby 3.2 or later.
+
+## Usage
+
+The CLI is a small set of subcommands:
+
+```
+gem-contribute scan [path]            Summarize the contributable surface of a Gemfile.lock.
+gem-contribute issues <gem|all>       List "good first issue" issues for one gem (or all).
+gem-contribute auth login             Authenticate with GitHub via OAuth device flow.
+gem-contribute fix <gem>/<issue#>     Fork the gem's repo, clone the fork, branch from main.
+gem-contribute submit                 Push the branch and open a pre-filled PR in the browser.
+gem-contribute config set <key> <val> Persist user preferences (e.g. clone_root).
+```
+
+A typical session:
+
+```sh
+$ gem-contribute auth login              # one-time; uses GitHub device flow
+$ 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
+$ cd ~/code/oss/rubocop/rubocop          # (or wherever clone_root points)
+# ... make your change, commit ...
+$ gem-contribute submit                  # push + open the PR compare page in your browser
+```
+
+The `auth login` step opens GitHub's device-flow page in your browser and copies the one-time code to your clipboard — same UX as `gh auth login`, no token paste, no client secret. Tokens cache at `~/.config/gem-contribute/auth.json` (mode 0600).
+
+## Configuration
+
+User config lives at `~/.config/gem-contribute/config.yml`. Manage it with `gem-contribute config`:
+
+```sh
+gem-contribute config set clone_root ~/Projects/oss
+gem-contribute config list
+```
+
+| Key          | Default      | Notes                                            |
+|--------------|--------------|--------------------------------------------------|
+| `clone_root` | `~/code/oss` | Where `fix` clones forks (`<root>/<owner>/<repo>`). |
+
+## Design
+
+See [`docs/design.md`](docs/design.md) for the architecture overview and [`docs/adr/`](docs/adr/) for individual decisions with their reasoning. The short version: scan first, auth lazily, abstract the source host so GitHub isn't the only option forever, render the data as the maintainer wrote it (don't normalize labels, don't summarize CONTRIBUTING).
+
+## Contributing
+
+The tool is *for* finding contributable projects, so it had better be one. See [`CONTRIBUTING.md`](CONTRIBUTING.md). Issues tagged `good first issue` are real and reviewed.
+
+If you're attending Blue Ridge Ruby 2026 and arrived here from the workshop, see [`docs/workshop.md`](docs/workshop.md) for the exercises.
+
+## Disclosure
+
+Built with substantial assistance from Claude (Anthropic). Architecture, design decisions, and code review are mine; a fair amount of the typing isn't. Decisions are documented in `docs/adr/` partly so the reasoning is auditable independent of who or what produced the diff.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/_config.yml

@@ -0,0 +1,30 @@
+title: gem-contribute
+description: Find contributable issues in the gems your project already depends on.
+url: https://cdhagmann.com
+baseurl: /gem-contribute
+theme: jekyll-theme-cayman
+markdown: kramdown
+plugins:
+  - jekyll-relative-links
+
+# Process the existing markdown files in docs/ as pages, but don't try to
+# render them as posts.
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default
+
+# Don't try to publish working notes that aren't intended as docs.
+exclude:
+  - claude-code-prompt.md
+  - prep-plan.md
+  - workshop-issues/
+
+# Make markdown links to other .md files Just Work in the rendered HTML.
+relative_links:
+  enabled: true
+  collections: true
+include:
+  - CONTRIBUTING.md
+  - CHANGELOG.md

data/docs/adr/0001-just-in-time-auth.md

@@ -0,0 +1,44 @@
+# ADR 0001: Just-in-time authentication
+
+**Status:** Accepted
+**Date:** 2026-04-27
+
+## Context
+
+`gem-contribute` reads a Gemfile.lock, resolves source URLs, and queries hosts (GitHub primarily) for issues. Issue browsing is read-only and works against public repos with no auth. Forking, cloning, and branching require auth.
+
+Two reasonable architectures:
+
+1. **Auth at startup.** Prompt for OAuth on first run; everything is authenticated thereafter.
+2. **Auth just-in-time.** Run anonymously until the user takes an action that requires auth, then prompt.
+
+## Decision
+
+Auth lazily, per host, on first action that requires it.
+
+## Reasoning
+
+The lockfile-scanning and issue-browsing parts of the tool are useful without auth. A user who runs `gem-contribute` for the first time sees:
+
+> 47 gems · 44 on github.com · 2 on gitlab.com · 1 unknown source
+> Hit Enter on a gem to browse its issues.
+
+That's value before the auth prompt. The prompt becomes "you want to fork this — let's connect your GitHub" instead of "before doing anything, please authorize this app."
+
+Per-host matters because the tool is designed to grow GitLab and Codeberg adapters. Asking for GitHub auth on launch when the user only ever interacts with GitLab gems would be backwards.
+
+## Alternatives considered
+
+- **Auth at startup.** Simpler to implement; worse UX. Rejected.
+- **PAT-only (no OAuth).** Lower setup burden for the maintainer; higher for the user. See ADR-0004.
+
+## Consequences
+
+- The host adapter must distinguish public-API methods from auth-required ones at the type level (`AuthRequired` exception).
+- The TUI needs an auth-prompt overlay that can fire mid-session.
+- The token cache is keyed by host, not global.
+- Tests must cover both authenticated and anonymous paths for every adapter method.
+
+## Implementation note (post-ADR-0008)
+
+With Rooibos as the TUI framework, the JIT auth flow is naturally expressed as a state machine in `Update`: an action that requires auth dispatches a `Command.http` against an adapter method that returns `AuthRequired`; the resulting message transitions the model into an auth-pending state; device-flow polling runs as a sequence of `Command.http` + `Command.wait` cycles; on success the model retries the original action. This is cleaner and more testable than the imperative interrupt-and-resume pattern that would have been required with bare `ratatui_ruby`. The decision in this ADR is unchanged; only the implementation gets nicer.

data/docs/adr/0002-bundler-lockfile-parser.md

@@ -0,0 +1,35 @@
+# ADR 0002: Use Bundler's lockfile parser
+
+**Status:** Accepted
+**Date:** 2026-04-27
+
+## Context
+
+We need to read `Gemfile.lock` and produce a list of gems with names, versions, and source types (rubygems / git / path).
+
+## Decision
+
+Use `Bundler::LockfileParser` from the `bundler` gem.
+
+## Reasoning
+
+Bundler is already a dependency of any project that has a Gemfile.lock, and it ships a parser that handles every edge case the lockfile format has accumulated over a decade. Writing our own parser is a guaranteed source of bugs that would mostly manifest on other people's machines, with their unusual lockfiles.
+
+The parser API is stable and documented:
+
+```ruby
+parser = Bundler::LockfileParser.new(File.read("Gemfile.lock"))
+parser.specs  # => Array of Bundler::LazySpecification
+```
+
+Each spec has `.name`, `.version`, `.source` — exactly what we need.
+
+## Alternatives considered
+
+- **Write our own line-by-line parser.** Tempting because the format looks simple, but it isn't. Plugins, git sources, path sources, platform-specific gems, and lockfile version differences all complicate it. Rejected.
+- **Regex over the file.** No.
+
+## Consequences
+
+- `bundler` is a runtime dependency. It's already on every Ruby developer's machine, but worth declaring explicitly.
+- We're coupled to Bundler's internal API. If they change `LazySpecification`, we adapt. The risk is low and the upside is large.

data/docs/adr/0003-issue-tracker-preference.md

@@ -0,0 +1,33 @@
+# ADR 0003: Prefer `bug_tracker_uri` over `source_code_uri`
+
+**Status:** Accepted
+**Date:** 2026-04-27
+
+## Context
+
+The RubyGems v1 API returns metadata for a gem including several URIs from the gemspec: `homepage_uri`, `source_code_uri`, `bug_tracker_uri`, `documentation_uri`, `changelog_uri`, etc. Most of the time `source_code_uri` and `bug_tracker_uri` point to the same GitHub repo. Sometimes they don't.
+
+A small but real fraction of gems host code on one platform and issues on another (commonly: code on GitHub Enterprise, issues on a public GitHub repo). For those gems, we want issues, not code.
+
+## Decision
+
+Prefer `bug_tracker_uri`. Fall back to `source_code_uri`. Fall back to `homepage_uri` if it points at a recognized host. Otherwise mark the gem as `:unknown` source.
+
+## Reasoning
+
+The tool is named `gem-contribute` and the primary action is "browse and respond to issues." The bug tracker is the canonical location of issues. If a maintainer set both URIs, they did so deliberately, and we should respect their choice.
+
+For gems that only set `source_code_uri`, the fallback is correct because most of the time the source repo *is* the issue tracker.
+
+The `homepage_uri` fallback is a hail-mary for gems whose maintainer never set the more specific URIs but happened to put a GitHub URL in the homepage field. In practice this catches a few percent of older gems.
+
+## Alternatives considered
+
+- **Always use `source_code_uri`.** Loses the rare-but-real case where issues live elsewhere. Rejected.
+- **Only use `bug_tracker_uri`, with no fallback.** Excludes too many gems. Rejected.
+- **Try them all and let the user pick.** Workable, but the right answer is almost always the first non-nil one in our preference order. Don't make the user choose.
+
+## Consequences
+
+- A small number of gems will have `bug_tracker_uri` pointing at something that isn't a host we have an adapter for (private Bugzilla, mailing list, etc.). Those gems become `:unknown` and aren't actionable. We surface them anyway because seeing "this gem has no contributable issue tracker" is itself useful information.
+- We may want a `--prefer-source` flag eventually for users who specifically want code-level contributions over issue triage. Not in v1.