gem-contribute 0.2.0 → 0.3.0

data/docs/adr/README.md

@@ -11,11 +11,15 @@ Format: [Michael Nygard's template](https://github.com/joelparkerhenderson/archi
 - [0003 — Prefer `bug_tracker_uri` over `source_code_uri`](0003-issue-tracker-preference.md)
 - [0004 — Use OAuth Device Flow, not PATs](0004-device-flow-auth.md)
 - [0005 — Render labels verbatim](0005-render-labels-verbatim.md)
-- [0006 — Ship as a standalone gem, not a Bundler plugin](0006-standalone-gem-not-plugin.md)
+- [0006 — Ship as a standalone gem, not a Bundler plugin](0006-standalone-gem-not-plugin.md) — Bundler-plugin decision reversed by 0014; standalone-gem decision stands
 - [0007 — Show CONTRIBUTING; don't parse it](0007-display-contributing-verbatim.md)
-- [0008 — Use Rooibos for the TUI layer](0008-rooibos-tui-framework.md) — superseded by 0010
+- [0008 — Use Rooibos for the TUI layer](0008-rooibos-tui-framework.md) — superseded by 0010, substance restored by 0013
 - [0009 — Top-level namespace is `GemContribute`](0009-top-level-namespace.md)
-- [0010 — Use Charm-Ruby (bubbletea + lipgloss) for the TUI layer](0010-charm-ruby-tui-framework.md)
+- [0010 — Use Charm-Ruby (bubbletea + lipgloss) for the TUI layer](0010-charm-ruby-tui-framework.md) — superseded by 0013
+- [0011 — HostAdapter owns host verbs; Operations compose them; CLI verbs compose Operations](0011-host-adapter-owns-host-verbs.md)
+- [0012 — Output-free service objects, dry-monads Result contract, three-interface architecture](0012-output-free-service-objects-three-interface-architecture.md) — packaging amended by 0014; service-layer contract stands
+- [0013 — Revert TUI framework to Rooibos](0013-revert-to-rooibos.md) — supersedes 0010, restores 0008's substance
+- [0014 — Ship Bundler and RubyGems plugins as v1 interfaces](0014-ship-bundler-and-rubygems-plugins.md) — amends 0006 and 0012
 
 ## When to add an ADR
 

data/docs/design-interface-layer.md

@@ -0,0 +1,295 @@
+# Interface Layer Design
+
+This document describes the multi-interface architecture introduced by [ADR-0012](adr/0012-output-free-service-objects-three-interface-architecture.md). It is the reference for all work that touches the boundary between service objects and the three output vectors: CLI, TUI, and gem plugin. Read it before changing anything in `lib/gem_contribute/cli/` or `lib/gem_contribute/operations/`.
+
+For the broader system architecture — parsers, resolvers, the host adapter interface, caching — see [`design.md`](design.md).
+
+## The problem with the current boundary
+
+`Operations::Fork` and `Operations::Clone` accept `stdout:` and print progress during `call`:
+
+```ruby
+def call(adapter:, project:)
+  @stdout.puts "Forking #{project.owner}/#{project.repo}..."
+  fork = adapter.fork(project)
+  @stdout.puts fork.reused ? "  Reusing existing fork." : "  Forked → ..."
+  Result.new(...)
+end
+```
+
+This works for a single CLI, but breaks across three interfaces:
+
+- The **TUI** has no output stream. Progress is model state rendered by `View`, not a string printed to stdout. There is no clean way to route `@stdout.puts` into a Rooibos model update.
+- The **gem plugin** needs to own its own output formatting and cannot share stdout injection with the CLI.
+- **Tests** must assert on stdout side effects instead of return values, coupling test setup to I/O concerns.
+
+The same problem appears in `Workflow#build_adapter`, which returns `nil` and prints to stderr on failure — two concerns collapsed into one method.
+
+## Target architecture
+
+Three interface layers share one service layer. The service layer produces no output. Each interface layer translates `Result` values into the output appropriate for its medium.
+
+```
+                          Service Layer
+    ┌────────────────────────────────────────────────────┐
+    │  Operations::Fork    Operations::Clone             │
+    │  Operations::FixPipeline    Resolver               │
+    │  HostAdapter         Auth          Git             │
+    │                                                    │
+    │  Returns Success(Result) | Failure(reason)         │
+    │  No stdout. No stderr. No exceptions across layers.│
+    └───────────────┬───────────────────┬────────────────┘
+                    │                   │                │
+                    ▼                   ▼                ▼
+        ┌───────────────┐   ┌───────────────┐   ┌──────────────┐
+        │  CLI Pipeline │   │  TUI Pipeline │   │  gem plugin  │
+        │               │   │               │   │  Pipeline    │
+        │  Output::     │   │  Commands +   │   │              │
+        │  Standard     │   │  Update       │   │  reuses CLI  │
+        │  tty-spinner  │   │               │   │  pipeline    │
+        │  tty-prompt   │   │               │   │              │
+        └───────────────┘   └───────────────┘   └──────────────┘
+```
+
+The three interface pipelines are entirely separate. A change to CLI output formatting has zero effect on the TUI. A new service object needs no knowledge of any interface.
+
+## Service layer
+
+### Result types
+
+Every operation returns a `dry-monads` `Result`:
+
+- `Success(value)` on the happy path — `value` is a `Data` struct.
+- `Failure(reason)` for expected failure conditions — `reason` is a symbol or tagged tuple.
+
+```ruby
+Success(Operations::Fork::Result.new(clone_url:, fork_url:, upstream_url:, viewer:, reused:))
+
+Failure(:unauthenticated)
+Failure(:adapter_error, "rate limit exceeded")
+```
+
+Typed exceptions (`AuthRequired`, `AdapterError`) are not used as cross-layer signals. They may be raised and rescued within a single operation but do not propagate to callers.
+
+### No I/O
+
+Operations accept no `stdout:` or `stderr:` parameter. The `# rubocop:disable Metrics/ParameterLists` suppressions in the current `CLI::Fork` and `CLI::Fix` initializers are a symptom of this pattern — the extra `stdout:` and `stderr:` parameters inflate every constructor. `dry-initializer` replaces the verbose initializer pattern and the suppressions go away:
+
+```ruby
+class Operations::Fork
+  extend Dry::Initializer
+  # No stdout:. No stderr:. Pure computation.
+end
+```
+
+### Multi-step pipelines
+
+The `fix` flow (fork → clone → branch → announce) is a `dry-operation` pipeline. Each step receives a shared context, enriches it, and returns `Success(enriched)` or `Failure(reason)`. Failure at any step short-circuits the chain — no early returns, no nil checks.
+
+```ruby
+class Operations::FixPipeline
+  include Dry::Operation
+
+  def call(adapter:, project:, issue:, viewer:)
+    fork_result  = step Operations::Fork.new.call(adapter:, project:)
+    clone_result = step Operations::Clone.new.call(adapter:, project:, fork_result:)
+    branch_name  = step Operations::Branch.new.call(path: clone_result.path, issue:)
+    step Operations::Announce.new.call(adapter:, project:, issue:, viewer:, was_resuming: clone_result.reused)
+    Success({ fork: fork_result, clone: clone_result, branch: branch_name })
+  end
+end
+```
+
+Both the CLI and TUI call `FixPipeline` rather than wiring the steps themselves.
+
+### `Workflow#build_adapter`
+
+Currently returns `nil` and prints to stderr. Under the new contract:
+
+```ruby
+def build_adapter
+  token = @store.token_for("github.com")
+  return Failure(:unauthenticated) if token.nil?
+
+  Success(@adapter_factory.call(token: token))
+end
+```
+
+Callers pattern-match on the result; no output side effect in the mixin.
+
+## CLI pipeline
+
+### `Output::Standard`
+
+All CLI verbs use `Output::Standard` instead of raw `@stdout`/`@stderr`. It wraps both streams and exposes a semantic interface:
+
+```ruby
+module GemContribute
+  module Output
+    class Standard
+      def initialize(out: $stdout, err: $stderr)
+        @out = out
+        @err = err
+      end
+
+      def info(message)     = @out.puts(message)
+      def warn(message)     = @err.puts("warning: #{message}")
+      def error(message)    = @err.puts(message)
+      def progress(message) # tty-spinner in interactive terminals;
+                            # falls back to info when stdout is not a TTY
+    end
+
+    class Null
+      def info(_) = nil
+      def warn(_) = nil
+      def error(_) = nil
+      def progress(_) = nil
+    end
+  end
+end
+```
+
+`#progress` is the one method that behaves differently from a plain `puts`. Long operations (fork, clone) show a spinner in interactive terminals. `tty-spinner` detects non-TTY environments automatically and falls back to a plain line — no caller checks `$stdout.tty?`.
+
+### Interactive prompts
+
+`Init` is the one command that reads input. Its current `stdout.print` + injected `@gets` lambda is replaced by `tty-prompt`:
+
+```ruby
+prompt = TTY::Prompt.new(input: @input, output: @output)
+chosen  = prompt.ask("Where should I clone repos?", default: DEFAULT_SUGGESTION)
+proceed = prompt.yes?("Authenticate with GitHub now?")
+```
+
+`TTY::Prompt.new(input:, output:)` provides the same test injection story the current `gets:` lambda provides, with proper default-value display, Y/n handling, and non-TTY fallback built in.
+
+### How CLI verbs change
+
+CLI verbs print around service calls. The operation returns a `Result`; the verb interprets it:
+
+```ruby
+def execute(adapter, project, flags)
+  @output.progress("Forking #{project.owner}/#{project.repo}...")
+
+  case @fork_op.call(adapter: adapter, project: project)
+  in Success(fork_result)
+    @output.info(fork_result.reused ? "  Reusing existing fork." : "  Forked.")
+    continue_with(fork_result, flags)
+  in Failure(:unauthenticated)
+    @output.error("Not authenticated. Run `gem-contribute auth login` first.")
+    1
+  in Failure(:adapter_error, message)
+    @output.error(message)
+    1
+  end
+end
+```
+
+The `with_workflow_rescues` wrapper in `Workflow` is retired — pattern matching on `Result` replaces it.
+
+## TUI pipeline
+
+The TUI never uses an `Output` object. A Rooibos Command wraps the service call, runs it off-thread, and returns a message to `Update`:
+
+```ruby
+def fix_command(adapter:, project:, issue:, viewer:)
+  -> {
+    result = Operations::FixPipeline.new.call(
+      adapter: adapter, project: project, issue: issue, viewer: viewer
+    )
+    { type: :fix_completed, result: result }
+  }
+end
+```
+
+`Update` pattern-matches on the message:
+
+```ruby
+def update(msg, model)
+  case msg
+  in { type: :fix_completed, result: Success({ fork:, clone:, branch: }) }
+    model.with(local_path: clone.path, branch_name: branch, status: :done)
+  in { type: :fix_completed, result: Failure(:unauthenticated) }
+    [model.with(pending_action: :fix), AuthOverlay.start_command]
+  in { type: :fix_completed, result: Failure(:adapter_error, message) }
+    model.with(error: message)
+  end
+end
+```
+
+The service object returns a `Result`; the Command wraps it in a typed message; `Update` renders it as model state. No output object, no stdout, no cross-layer exceptions.
+
+## Plugin pipelines
+
+Per [ADR-0014](adr/0014-ship-bundler-and-rubygems-plugins.md), v1 ships three entry points in a single `gem-contribute` gem: the standalone `gem-contribute` binary, a Bundler plugin (`bundle contribute`), and a RubyGems plugin (`gem contribute`). Both plugins are CLI-only; the TUI is a property of the standalone binary.
+
+- **Bundler plugin** — `plugins.rb` at the gem root, per Bundler convention. Registers a `bundle contribute` command and delegates to the same dispatch table the standalone CLI uses.
+- **RubyGems plugin** — `rubygems_plugin.rb`, per RubyGems convention. Registers a `Gem::Command` subclass for `gem contribute` and delegates the same way.
+
+Both plugin entry points MUST NOT require Rooibos or `ratatui_ruby`. The TUI gets loaded only by the standalone-binary entry point, which keeps plugin install lightweight and plugin invocations fast.
+
+When `dry-cli` is added (alongside the plugin shims), it replaces the hand-rolled `COMMANDS` dispatch in `cli.rb` with declarative command registration. All three entry points register the same underlying commands against their respective hosts — the commands themselves do not change.
+
+The plugin work is deferred until the service layer and CLI pipeline are clean (this document's Phases 1 and 2) and the TUI lands ([ROADMAP](ROADMAP.md) Phase 3).
+
+## New dependencies
+
+| Gem | Role | Phase |
+|---|---|---|
+| `dry-monads` | `Success`/`Failure` Result types | 1 |
+| `dry-operation` | Multi-step pipeline composition for `fix` | 1 |
+| `dry-initializer` | Clean option declarations; removes rubocop suppressions | 1 |
+| `tty-spinner` | Spinner in `Output::Standard#progress` | 2 |
+| `tty-prompt` | Interactive prompts in `Init` | 2 |
+| `dry-cli` | Command registration across all three entry points | 4/5 (with plugin shims) |
+
+Pin all new dependencies to a minor version (`~> x.y`). Bump deliberately; record significant bumps in an ADR note.
+
+## Migration sequence
+
+### Phase 1 — Service layer
+
+1. Add `dry-monads`, `dry-operation`, `dry-initializer` to the gemspec.
+2. Remove `stdout:` from `Operations::Fork` and `Operations::Clone`. Add `reused:` to `Clone::Result`.
+3. Convert both operations to return `Success(Result)` | `Failure(reason)`.
+4. Convert `Workflow#build_adapter` to return `Success(adapter)` | `Failure(:unauthenticated)`.
+5. Build `Operations::FixPipeline` using `dry-operation`.
+6. Replace long initializers in `CLI::Fork` and `CLI::Fix` with `dry-initializer` option declarations.
+7. Update all callers to pattern-match on `Result`. Retire `with_workflow_rescues`.
+
+### Phase 2 — CLI pipeline
+
+1. Introduce `Output::Standard` and `Output::Null`.
+2. Replace raw `@stdout`/`@stderr` in all CLI verbs with `@output`.
+3. Add `tty-spinner` for `Output::Standard#progress`.
+4. Replace `Init`'s `stdout.print` + `@gets` with `tty-prompt`.
+
+### Phases 4 and 5 — Bundler and RubyGems plugins
+
+Per ADR-0014 and the [ROADMAP](ROADMAP.md), the gem-plugin work is split into two ROADMAP phases (one per plugin) and lives within the `gem-contribute` gem rather than as separate `bundler-contribute` / `rubygems-contribute` gems.
+
+1. Add `dry-cli`. Replace the `COMMANDS` dispatch in `cli.rb` with `dry-cli` command registration so multiple entry points can hang off it.
+2. Add `plugins.rb` at the gem root (Bundler plugin entry point). Register a `bundle contribute` command that dispatches into the same registration table.
+3. Add `rubygems_plugin.rb` (RubyGems plugin entry point). Register a `Gem::Command` subclass that does the same.
+4. Smoke-test both plugin install paths in CI.
+
+Each ADR-0012 phase is independently releasable. Phase 1 has no user-visible behaviour change. Phase 2 changes the look of progress output and prompts. The plugin phases add new entry points.
+
+## Testing strategy
+
+**Service layer:** pure function in, `Result` out. Every operation gets unit tests that assert on `Success`/`Failure` values directly. No stdout assertion. No mock needed for output. VCR cassettes for adapter-touching operations; committed to the repo.
+
+**CLI pipeline:** inject `Output::Null` for tests that don't assert on output; inject a capturing double for tests that do. Assert on captured calls to `#info`/`#error`/`#progress`, not on raw stdout strings.
+
+**TUI pipeline:** the Command closure is a plain lambda — call it directly and assert on the returned message hash. `Update` is a pure function — call it with a message and assert on the returned model. Rooibos's snapshot test helpers (per ADR-0008/0013) supplement this for full-flow scenarios.
+
+**gem plugin:** thin entry-point tests only. The CLI pipeline tests cover the behaviour.
+
+## What doesn't change
+
+- The `HostAdapter` interface and `GitHubAdapter` implementation.
+- `Resolver`, `LockfileParser`, `TokenStore`, `Cache` — already output-free.
+- The Auth flow shape. `CLI::Auth` keeps its existing structure; `Workflow#build_adapter`'s change is internal wiring.
+- Caching strategy and TTLs.
+- The Rooibos framework choice (ADR-0013, which superseded ADR-0010).
+- ADR-0005 (render labels verbatim), ADR-0007 (show CONTRIBUTING), ADR-0009 (namespace). None of these touch the interface boundary.

data/docs/design.md

@@ -61,19 +61,42 @@ The `host` is parsed from the URL: `github.com`, `gitlab.com`, `codeberg.org`, o
 ### `HostAdapter` (interface) and `GitHubAdapter` (implementation)
 
 Input: a `Project` plus, for some methods, an auth token.
-Output: issues, CONTRIBUTING content, fork results.
+Output: issues, CONTRIBUTING content, fork results, host-specific URLs.
 
 ```ruby
-def issues(project, labels:)              # public, no auth needed
-def community_profile(project)            # public, no auth needed
-def file_contents(project, path)          # public, no auth needed
-def fork(project)                         # auth required
-def already_forked?(project)              # auth required
+# Reads — no auth
+def issues(project, labels:)
+def issue(project, number)
+def issue_comments(project, number)
+def community_profile(project)
+def file_contents(project, path)
+def search_issues(query)
+
+# Writes — auth required
+def fork(project)                         # idempotent, blocks until ready; → ForkResult
+def comment(project, issue:, body:)
+def pull_request_url(upstream, head_owner:, head_branch:, title:, body:)
+
+# Identity / URL helpers
+def viewer_login                          # auth required
+def clone_url(owner, repo)                # pure templating, no network
+def repo_url(owner, repo)                 # pure templating, no network
 ```
 
 `GitHubAdapter` checks for a cached token before any auth-required call. If there's no token, it raises `AuthRequired` with the host name. The TUI catches this through its message machinery and triggers the device flow. See [ADR-0001](adr/0001-just-in-time-auth.md).
 
-Adding a new host (GitLab, Codeberg) means writing a new adapter that conforms to the interface. The TUI doesn't change.
+`fork` is idempotent and blocking: if the viewer already owns the fork it returns `reused: true` without a POST; otherwise it POSTs and polls the host until the new fork is reachable. Higher layers don't see the polling. PR creation is not an API call — the adapter's `pull_request_url` returns a host-specific compare/MR URL that gets opened in the browser, so the user reviews the PR text before submitting. See [ADR-0011](adr/0011-host-adapter-owns-host-verbs.md).
+
+Adding a new host (GitLab, Codeberg) means writing a new adapter that conforms to the interface — including its own `clone_url` / `repo_url` / `pull_request_url` templates and its own readiness model for `fork`. Operations and CLI don't change.
+
+### `Operations::Fork` and `Operations::Clone`
+
+Two thin primitives sitting between the adapter and the CLI verbs. They're the bootstrap step `fix` and `fork` share:
+
+- `Operations::Fork` calls `adapter.fork(project)` and packages the result with the upstream URL for summary output.
+- `Operations::Clone` clones the fork into `<root>/<owner>/<repo>` (reusing an existing clone if one is there) and adds an `upstream` remote pointing at `adapter.clone_url(upstream)`.
+
+The "reuse if `.git` exists" rule and the upstream-remote convention are gem-contribute policy on top of git, not git primitives — that's why they live here rather than in the `Git` wrapper. See [ADR-0011](adr/0011-host-adapter-owns-host-verbs.md).
 
 ### `Auth`
 
@@ -225,7 +248,7 @@ The Rooibos snapshot tooling normalizes dynamic content (timestamps, paths in `~
 
 ## Roadmap (non-promises)
 
-**v0.1 (workshop):** GitHub-only, JIT auth, fork-clone-branch working, four primary fragments, Rooibos throughout, snapshot tests for the main flows.
+**v0.1 (workshop):** GitHub-only, JIT auth, `fix` working, four primary fragments, Rooibos throughout, snapshot tests for the main flows.
 
 **v0.2:** Better empty states, rate-limit display in the status bar, `r` keybinding to refresh the current view, keyboard help overlay (an additional fragment).
 

data/docs/index.md

@@ -50,7 +50,7 @@ gem-contribute submit                 # push, then open the PR compare page in y
 | `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 fix <gem>/<n>` | Fork the gem's repo, clone the fork to `<clone_root>/<owner>/<repo>`, branch from default. |
 | `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. |

data/docs/prep-plan.md

@@ -36,14 +36,14 @@ Minimum viable workshop = Stages 1, 2, and 4 done. Stage 3 (the TUI) can become
 **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 `fix` action. 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.
+**Goal:** Add device-flow auth and the `fix` action. Still no TUI; everything is CLI flags. Proves the auth and action layers work.
 
 **Acceptance:**
 
@@ -53,7 +53,7 @@ Minimum viable workshop = Stages 1, 2, and 4 done. Stage 3 (the TUI) can become
 - [ ] 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
+- [ ] A `fix` 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.
@@ -88,7 +88,7 @@ Minimum viable workshop = Stages 1, 2, and 4 done. Stage 3 (the TUI) can become
 - 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`
+- No `Worker` orchestrator class — `fix` is a state machine in `Update`
 
 **Stop and check in with Chris.** This is the demo for the workshop opening.
 
@@ -118,7 +118,7 @@ Minimum viable workshop = Stages 1, 2, and 4 done. Stage 3 (the TUI) can become
 - "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
+- Confirmation dialog before `fix`
 - `o` to open the gem's homepage in browser
 - "Last updated" warning for stale-looking gems
 
@@ -147,7 +147,7 @@ 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
+3. `f` on an issue completes the `fix` 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
 

data/lib/gem_contribute/cli/auth.rb

@@ -10,6 +10,8 @@ module GemContribute
     #             validate it by hitting /user)
     #   logout  — drop the cached token for github.com
     class Auth
+      include PlatformTools
+
       USAGE = <<~USAGE
         Usage: gem-contribute auth <subcommand>
 
@@ -21,11 +23,11 @@ module GemContribute
 
       DEFAULT_HOST = "github.com"
 
-      def initialize(stdout: $stdout, stderr: $stderr, store: TokenStore.new,
+      def initialize(stdout: $stdout, stderr: $stderr, output: nil,
+                     store: TokenStore.new,
                      sleeper: ->(s) { Kernel.sleep(s) },
                      browser_opener: nil, clipper: nil)
-        @stdout = stdout
-        @stderr = stderr
+        @output = output || Output::Standard.new(out: stdout, err: stderr)
         @store = store
         @sleeper = sleeper
         @browser_opener = browser_opener || method(:default_browser_opener)
@@ -38,11 +40,11 @@ module GemContribute
         when "status" then status
         when "logout" then logout
         when nil, "help", "-h", "--help"
-          @stdout.puts USAGE
+          @output.info(USAGE)
           0
         else
-          @stderr.puts "gem-contribute: unknown auth subcommand"
-          @stderr.puts USAGE
+          @output.error("gem-contribute: unknown auth subcommand")
+          @output.error(USAGE)
           2
         end
       end
@@ -55,20 +57,20 @@ module GemContribute
         result = poll_loop(device_code)
         persist_or_report(result)
       rescue GemContribute::Auth::AuthError => e
-        @stderr.puts "auth login failed: #{e.message}"
+        @output.error("auth login failed: #{e.message}")
         1
       end
 
       def prompt_user(device_code)
         copied = @clipper.call(device_code.user_code)
         code_suffix = copied ? " (copied to clipboard)" : ""
-        @stdout.puts "Your one-time code#{code_suffix}: #{device_code.user_code}"
+        @output.info("Your one-time code#{code_suffix}: #{device_code.user_code}")
 
         opened = @browser_opener.call(device_code.verification_uri)
         url_prefix = opened ? "Browser opened to" : "Visit"
-        @stdout.puts "#{url_prefix}: #{device_code.verification_uri}"
+        @output.info("#{url_prefix}: #{device_code.verification_uri}")
 
-        @stdout.puts "Waiting for you to authorize..."
+        @output.progress("Waiting for you to authorize...")
       end
 
       def poll_loop(device_code)
@@ -92,16 +94,16 @@ module GemContribute
         case result.status
         when :ok
           @store.store(DEFAULT_HOST, access_token: result.token, scope: result.scope)
-          @stdout.puts "Authenticated. Token saved to #{TokenStore.default_path} (mode 0600)."
+          @output.info("Authenticated. Token saved to #{TokenStore.default_path} (mode 0600).")
           0
         when :expired
-          @stderr.puts "Device code expired. Run `gem-contribute auth login` again."
+          @output.error("Device code expired. Run `gem-contribute auth login` again.")
           1
         when :denied
-          @stderr.puts "Authorization denied."
+          @output.error("Authorization denied.")
           1
         else
-          @stderr.puts "auth login failed: #{result.error_message}"
+          @output.error("auth login failed: #{result.error_message}")
           1
         end
       end
@@ -109,7 +111,7 @@ module GemContribute
       def status
         entry = @store.entry_for(DEFAULT_HOST)
         if entry.nil?
-          @stdout.puts "Not authenticated. Run `gem-contribute auth login`."
+          @output.info("Not authenticated. Run `gem-contribute auth login`.")
           return 1
         end
 
@@ -119,46 +121,22 @@ module GemContribute
       def verify_and_print(entry)
         adapter = HostAdapters::GitHubAdapter.new(token: entry["access_token"])
         login_name = adapter.viewer_login
-        @stdout.puts "Authenticated as @#{login_name} on #{DEFAULT_HOST} (scope: #{entry["scope"] || "unknown"})"
+        @output.info("Authenticated as @#{login_name} on #{DEFAULT_HOST} (scope: #{entry["scope"] || "unknown"})")
         0
       rescue GemContribute::AuthRequired, GemContribute::AdapterError => e
-        @stderr.puts "Token cached for #{DEFAULT_HOST} but verification failed: #{e.message}"
-        @stderr.puts "Run `gem-contribute auth login` to refresh."
+        @output.error("Token cached for #{DEFAULT_HOST} but verification failed: #{e.message}")
+        @output.error("Run `gem-contribute auth login` to refresh.")
         1
       end
 
       def logout
         if @store.delete(DEFAULT_HOST)
-          @stdout.puts "Logged out of #{DEFAULT_HOST}."
+          @output.info("Logged out of #{DEFAULT_HOST}.")
         else
-          @stdout.puts "No cached token for #{DEFAULT_HOST}."
+          @output.info("No cached token for #{DEFAULT_HOST}.")
         end
         0
       end
-
-      def default_browser_opener(uri)
-        cmd = case RbConfig::CONFIG["host_os"]
-              when /darwin/           then "open"
-              when /linux/            then "xdg-open"
-              when /mswin|mingw|cygwin/ then "start"
-              end
-        cmd && Kernel.system(cmd, uri)
-      rescue StandardError
-        false
-      end
-
-      def default_clipper(text)
-        case RbConfig::CONFIG["host_os"]
-        when /darwin/
-          IO.popen("pbcopy", "w") { |p| p.write(text) }
-          true
-        when /linux/
-          IO.popen(["xclip", "-selection", "clipboard"], "w") { |p| p.write(text) }
-          true
-        end
-      rescue StandardError
-        false
-      end
     end
   end
 end