ruby-repo-kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2909f2324f7d85ad154aa579190c1a6163b2245b742e96075ba7f8ba45c0eb73
+  data.tar.gz: e67253ccb000a0c816a0fca22aaf9ae1e0984ca16344f4d1f814fe7df0f96ab0
+SHA512:
+  metadata.gz: 2e008180735fbb712e1860ad300104fbecfa27c6d8e677e16487660bd976b3c6318a7778ac0fae1593a4f3b56fb783e622494aaf09ba9ea8310bc19c1905c24e
+  data.tar.gz: 5cb158be5ed9a2153ca460026b8184d88f7bd50b9fd6be22039badc17cd71f8d9d0a48485ad7d82b5b55a19c9565ef2d2b0ea81e1adcb34330b60ca62848c632

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-05
+
+### Added
+
+- Generate focused Ruby CLI projects with tests, linting, documentation and release workflows.
+- Share release preparation, recovery, artifact verification and isolated package checks through a development gem.
+- Validate repository contracts and plan, verify or apply the initial GitHub maintenance policy.
+
+[Unreleased]: https://github.com/hvpaiva/ruby-repo-kit/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/hvpaiva/ruby-repo-kit/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Highlander Paiva
+
+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,174 @@
+# Ruby Repo Kit
+
+Versioned maintenance tools and a focused generator for Ruby CLI repositories.
+Create a project once; share release, packaging, repository checks and lint
+configuration through a development dependency.
+
+Ruby Repo Kit is in initial development. [Current status](docs/STATUS.md) records
+the local, hosted CI and publication gates separately. A configured release
+workflow or a passing local test does not prove that RubyGems OIDC publication
+has succeeded. The dedicated ruby-repo-canary must pass its acceptance gates
+before Slipway or Rich-RI adopt the toolkit.
+
+Requires Ruby 3.4 or newer. GitHub operations additionally require Git, the
+authenticated GitHub CLI, and the relevant repository permissions. Releases use
+signed commits and tags and require working Git signing configuration.
+
+## Bootstrap from source
+
+The toolkit develops and packages itself without depending on a published copy
+of its own gem:
+
+    bundle install
+    bundle exec rake check
+    bundle exec ruby-repo-kit --help
+    bundle exec rake build
+
+The build command prints the artifact path. Install that artifact with
+gem install --local PATH_TO_ARTIFACT to exercise its installed executable and
+templates. Development dependencies are installed by Bundler; installation of the
+toolkit artifact is a separate validation step.
+
+After a version has actually been published, it can also be installed from
+RubyGems with gem install ruby-repo-kit.
+
+## Create a CLI
+
+    ruby-repo-kit new useful-cli --repository your-account/useful-cli --author "Your Name" --email you@example.com
+
+Use --directory PATH to select another destination, including a path containing
+spaces. Its parent directory must exist. Existing destinations, including
+dangling symlinks, are rejected. Existing parent symlinks are resolved and the
+command reports the canonical destination.
+
+Generation creates files only: no Git repository, dependency installation,
+GitHub resources or publication. The initial CLI prints text and provides help,
+version, defined exit statuses and broken-pipe handling. The scaffold includes
+tests, coverage, packaging, a shared lint preset, contribution documents,
+dependency updates, CI and a release workflow.
+
+Then enter the generated directory and run:
+
+    bin/setup
+    bundle exec rake check
+    bundle exec rake audit
+
+Commit the resulting Gemfile.lock. The configured toolkit version must be
+available to dependency resolution. Before its first publication, a locally
+installed toolkit artifact can support a local canary; hosted CI needs an
+accessible distribution of that version.
+
+## Adopt the shared tools
+
+A consumer declares ruby-repo-kit in its Gemfile development/test group. Its
+runtime gemspec must not depend on the toolkit. Existing projects need a reviewed
+integration; the generator does not overwrite or migrate them.
+
+The integration consists of:
+
+- .ruby-repo.yml with project identity, release paths, commands and required checks.
+- A Rakefile that installs RubyRepoKit::RakeTasks for that project.
+- .rubocop.yml inheriting ruby-repo-kit's config/rubocop.yml.
+- Optional thin executable wrappers such as bin/release.
+- Project-owned CI and release workflow files.
+
+Inspect the [architecture and configuration contract](docs/ARCHITECTURE.md) for
+the Ruby API, ownership boundaries and configuration example.
+
+## Check a repository
+
+    bundle exec ruby-repo-kit doctor
+    bundle exec rake check
+    bundle exec rake audit
+
+Doctor validates the local maintenance contract: required files, package
+metadata, version consistency, package manifest, development dependency and
+shared lint configuration. It does not certify code quality, run the full test
+suite, or verify hosted settings.
+
+The repository's check task combines lint, tests with coverage, structural checks
+and installed-package smoke tests. The separate audit task updates the
+vulnerability database and needs network access. Individual shared entry points
+include repo:check, package:check, lint:commits and audit.
+
+## Prepare and publish a release
+
+Start with the prospective version in a configured repository:
+
+    bundle exec ruby-repo-kit release 0.2.0 --dry-run
+
+This inspects repository policy and release state and fetches Git refs. It does
+not edit source files or change GitHub release state. Local main must match
+origin/main, and the release needs a nonempty Unreleased changelog section.
+
+To prepare the release:
+
+    bundle exec ruby-repo-kit release 0.2.0
+
+This creates or resumes the release branch, updates version/changelog/lockfile,
+runs generation and checks, makes a signed commit, pushes the branch and opens
+or reuses a pull request. It is a write operation even without --push.
+
+After reviewing the release:
+
+    bundle exec ruby-repo-kit release 0.2.0 --push
+
+The additional --push option waits for checks, merges the exact release PR head,
+signs and pushes a tag for the merge commit, and follows the hosted release run.
+Use --branch hotfix/MAJOR.MINOR to target a maintenance branch for that version.
+The --dry-run and --push options are mutually exclusive.
+
+Rerunning the same version inspects existing PRs, tags and workflow runs before
+continuing. Existing release tags are never moved. If RubyGems publication
+succeeded but GitHub release creation failed, recovery reports the narrower
+GitHub retry; it does not silently publish the gem again.
+
+The hosted workflow builds and tests one gem artifact. Subsequent attestation,
+RubyGems publishing and GitHub release creation use that artifact and verify its
+SHA-256 digest. Publication uses the configured release environment and RubyGems
+Trusted Publishing. The publisher must be configured separately on RubyGems;
+GitHub policy setup does not register it.
+
+The workflow's manual dry_run option rehearses build/verification without
+publication. A matching version tag can publish once the external configuration
+is in place. See [the acceptance plan](docs/PLAN.md) for the initial canary sequence.
+
+## Inspect and configure GitHub
+
+    bundle exec ruby-repo-kit github plan
+    bundle exec ruby-repo-kit github verify
+    bundle exec ruby-repo-kit github apply
+
+Plan and verify read the configured repository. Apply reads its current state,
+then applies the planned changes and verifies the result. It changes repository
+settings; review a plan before choosing to apply it.
+
+The initial policy is for personal repositories: signed commits, PR-based merge
+commits, named required checks, protected release tags, a release environment
+restricted to version tags, dependency/security settings, and the skip-changelog
+label. It does not require another person's approval. Existing reviewer/timer
+environment protections and unmanaged rules are preserved where supported;
+unknown protections or unreadable settings stop reconciliation. Additional
+deployment branch policies in the managed release environment are removed.
+Administrator access and availability of these GitHub features are prerequisites.
+
+## Update without copying scripts
+
+    bundle update ruby-repo-kit
+    bundle exec rake check
+
+Review and commit the dependency/lockfile change. Shared operations and the
+inherited lint preset then use the new version. Templates affect newly generated
+projects; updating the dependency does not rewrite existing application code,
+tests, documentation or local workflow YAML. Integration changes are explicit
+reviewed edits. During the initial 0.x series, review release notes for each update.
+
+## Contributing and license
+
+See [contributing](CONTRIBUTING.md), [security](SECURITY.md),
+[conduct](CODE_OF_CONDUCT.md), [decisions](docs/DECISIONS.md) and the
+[implementation plan](docs/PLAN.md).
+
+MIT, Copyright (c) 2026 Highlander Paiva. Release tooling incorporates code adapted
+from Highlander Paiva's Slipway and Rich-RI projects under the same MIT license.
+See [LICENSE.txt](LICENSE.txt).

data/config/rubocop.yml

@@ -0,0 +1,55 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+
+inherit_mode:
+  merge:
+    - Exclude
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+  Exclude:
+    - vendor/**/*
+    - tmp/**/*
+    - pkg/**/*
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - test/**/*
+    - Rakefile
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Max: 35
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+Metrics/AbcSize:
+  Max: 46
+
+Metrics/CyclomaticComplexity:
+  Max: 18
+
+Metrics/PerceivedComplexity:
+  Max: 18
+
+Metrics/ClassLength:
+  Max: 180
+
+Minitest/MultipleAssertions:
+  Max: 12
+
+# Validation methods raise detailed errors on failure and return true on success.
+Naming/PredicateMethod:
+  AllowedMethods:
+    - verify!
+    - check

data/exe/ruby-repo-kit

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

data/lib/ruby_repo_kit/checks/commits.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RubyRepoKit
+  # A read-only Conventional Commits policy for commits and pull request metadata.
+  class Commits
+    TYPES = %w[feat fix docs test refactor chore ci].freeze
+    SUBJECT = /\A(?:#{TYPES.join('|')})(?:\([a-z0-9]+(?:-[a-z0-9]+)*\))?!?: (?:\[security\] )?[a-z][^\r\n]*\z/
+    UNFINISHED = /\A(?:fixup!|squash!|amend!|wip\b)|\A\w+(?:\([^)]*\))?!?:\s*wip\b/i
+    REVERT = /\A(?:Revert|Reapply) "(?<subject>.+)"\z/
+    BOT_ADDRESS = /\A(?:noreply@anthropic\.com|cursoragent@cursor\.com|(?:aider|noreply)@aider\.chat|
+                   \d+\+(?:Copilot|[\w-]+\[bot\])@users\.noreply\.github\.com)\z/ix
+    TOOL_TRAILER = /^(?:Generated-(?:by|with)|Assisted-by|Claude-Session):.*\b
+                    (?:claude|anthropic|copilot|cursor|codex|chatgpt|gpt-|gemini|assistant)\b/ix
+
+    def initialize(project:, commands: nil)
+      @commands = commands || Commands.new(project: project)
+    end
+
+    def check(range: nil, title: ENV.fetch("PR_TITLE", nil), body: ENV.fetch("PR_BODY", nil))
+      range ||= default_range
+      validate_range(range)
+      output = @commands.call(["git", "log", "--no-show-signature", "--reverse", "-z",
+                               "--format=%h%x1f%p%x1f%B", range, "--"])
+      problems = commit_problems(output)
+      problems << "Pull request title is not a Conventional Commit" if title && !valid_subject?(title.strip)
+      problems << "Pull request body contains a tool attribution trailer" if body && attribution?(body)
+      raise Error, "Commit policy failed:\n#{problems.join("\n")}" unless problems.empty?
+
+      true
+    end
+
+    private
+
+    def default_range
+      refs = @commands.call(["git", "for-each-ref", "--format=%(refname)", "refs/remotes/origin/main"])
+      refs.lines.map(&:strip).include?("refs/remotes/origin/main") ? "origin/main..HEAD" : "HEAD"
+    end
+
+    def validate_range(range)
+      references = range.is_a?(String) ? range.split(/\.\.\.?/, -1) : []
+      valid = references.length.between?(1, 2) && references.all? do |reference|
+        reference.match?(%r{\A[A-Za-z0-9][A-Za-z0-9._/-]*\z}) &&
+          !reference.include?("..") && !reference.include?("//") && !reference.end_with?("/") &&
+          reference.split("/").none? { |part| part.start_with?(".") || part.end_with?(".", ".lock") }
+      end
+      raise Error, "Expected a commit reference or REF..REF range" unless valid
+    end
+
+    def commit_problems(output)
+      output.dup.force_encoding(Encoding::UTF_8).scrub.split("\0").flat_map do |record|
+        sha, parents, message = record.split("\x1f", 3)
+        raise Error, "Git returned an unreadable commit record" unless sha && parents && message
+
+        problems = []
+        if parents.split.length < 2 && !valid_subject?(message.lines.first.to_s.chomp)
+          problems << "#{sha}: subject is not a Conventional Commit"
+        end
+        problems << "#{sha}: message contains a tool attribution trailer" if attribution?(message)
+        problems
+      end
+    end
+
+    def valid_subject?(subject)
+      return false if UNFINISHED.match?(subject)
+
+      # git can nest Revert/Reapply subjects; iteration avoids recursive stack growth.
+      while (reverted = REVERT.match(subject))
+        subject = reverted[:subject]
+      end
+      !UNFINISHED.match?(subject) && SUBJECT.match?(subject)
+    end
+
+    def attribution?(text)
+      text.each_line.any? do |line|
+        address = line.match(/^Co-Authored-By:[^<\n]*<(?<address>[^>\n]+)>/i)
+        if address
+          BOT_ADDRESS.match?(address[:address].strip)
+        else
+          TOOL_TRAILER.match?(line) || line.match?(/^\W*Generated with \[?Claude/i)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_repo_kit/checks.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "psych"
+require "rbconfig"
+require_relative "specification"
+
+module RubyRepoKit
+  # Local structural checks. Evaluating a gemspec/Gemfile is trusted project code;
+  # a child interpreter avoids loading consumer constants into the toolkit process.
+  class Checks
+    TOOLKIT_NAME = "ruby-repo-kit"
+    PRESET = "config/rubocop.yml"
+    GEMFILE_SCRIPT = <<~RUBY
+      require "json"
+      require "bundler"
+      definition = Bundler::Dsl.evaluate("Gemfile", nil, {})
+      puts JSON.generate(definition.dependencies.map(&:name))
+    RUBY
+
+    def initialize(project:)
+      @project = project
+    end
+
+    def run
+      [@project.gemspec, @project.version_file, @project.changelog, "Gemfile", "Rakefile"].each do |file|
+        require_file(file)
+      end
+      specification = Specification.load(project: @project)
+      metadata(specification)
+      manifest(specification)
+      development_dependency(specification)
+      rubocop_preset unless @project.name == TOOLKIT_NAME
+      true
+    rescue Errno::ENOENT, Errno::EACCES, Psych::Exception => e
+      raise Error, "Project checks failed: #{e.message}"
+    end
+
+    private
+
+    def require_file(file)
+      path = @project.path(file)
+      raise Error, "Required project file is missing: #{file}" unless File.file?(path)
+
+      path
+    end
+
+    def metadata(specification)
+      unless specification.name == @project.name
+        raise Error, "Gemspec name differs from project configuration (expected #{@project.name})"
+      end
+
+      text = File.read(@project.path(@project.version_file))
+      versions = text.scan(/^\s*VERSION\s*=\s*(["'])([^"'\n]+)\1(?:\.freeze)?\s*(?:#.*)?$/).map(&:last)
+      unless versions.length == 1 && Gem::Version.correct?(versions.first)
+        raise Error, "#{@project.version_file} must contain one literal VERSION assignment"
+      end
+      return if Gem::Version.new(versions.first) == specification.version
+
+      raise Error, "Gemspec version differs from #{@project.version_file}"
+    end
+
+    def manifest(specification)
+      files = specification.files
+      raise Error, "Gemspec files must be a list of relative paths" unless files.is_a?(Array) && files.all?(String)
+
+      files.each { |file| require_file(file) }
+      unless files.include?(@project.version_file) && files.any? { |file| file.start_with?("lib/") }
+        raise Error, "Gem manifest must include its lib files and #{@project.version_file}"
+      end
+
+      specification.executables.each do |executable|
+        relative = File.join(specification.bindir, executable)
+        require_file(relative)
+        raise Error, "Gem manifest does not include executable #{relative}" unless files.include?(relative)
+      end
+    end
+
+    def development_dependency(specification)
+      return if @project.name == TOOLKIT_NAME
+      if specification.runtime_dependencies.any? { |dependency| dependency.name == TOOLKIT_NAME }
+        raise Error, "#{TOOLKIT_NAME} belongs in the consumer Gemfile, never its runtime dependencies"
+      end
+      return if gemfile_dependencies.include?(TOOLKIT_NAME)
+
+      raise Error, "Declare #{TOOLKIT_NAME} in the consumer Gemfile"
+    end
+
+    def gemfile_dependencies
+      environment = ENV.keys.grep(/\ABUNDL/).to_h { |key| [key, nil] }
+      environment["RUBYOPT"] = nil
+      environment["RUBYLIB"] = nil
+      output, error, status = Open3.capture3(environment, RbConfig.ruby, "-e", GEMFILE_SCRIPT, chdir: @project.root)
+      raise Error, "Cannot inspect project Gemfile: #{error.strip}" unless status.success?
+
+      JSON.parse(output)
+    rescue JSON::ParserError
+      raise Error, "The Gemfile inspector returned invalid JSON (check output from the Gemfile)"
+    end
+
+    def rubocop_preset
+      path = @project.path(".rubocop.yml")
+      return unless File.exist?(path)
+
+      configuration = Psych.safe_load_file(path, permitted_classes: [], aliases: true)
+      inherited = configuration.is_a?(Hash) && configuration["inherit_gem"]
+      presets = inherited.is_a?(Hash) && inherited[TOOLKIT_NAME]
+      return if Array(presets).include?(PRESET)
+
+      raise Error, ".rubocop.yml must inherit #{TOOLKIT_NAME}/#{PRESET}; local overrides remain allowed"
+    end
+  end
+end

data/lib/ruby_repo_kit/cli.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../ruby_repo_kit"
+
+module RubyRepoKit
+  class CLI
+    HELP = <<~TEXT
+      Usage: ruby-repo-kit COMMAND [OPTIONS]
+
+      new NAME       Generate a Ruby CLI in a new directory
+      doctor         Check this project's local maintenance contract
+      release X.Y.Z  Prepare or resume a release (--dry-run, --push, --branch)
+      github plan    Show repository-policy changes without applying them
+      github verify  Verify repository policy without writes
+      github apply   Explicitly apply the repository's policy
+
+      --help         Show this help
+      --version      Show the toolkit version
+
+      Project commands read .ruby-repo.yml in the current directory.
+    TEXT
+
+    def self.run(argv, root: Dir.pwd, out: $stdout, err: $stderr)
+      new(root: root, out: out, err: err).run(argv.dup)
+    end
+
+    def initialize(root:, out:, err:)
+      @root = root
+      @out = out
+      @err = err
+    end
+
+    def run(argv)
+      command = argv.shift
+      case command
+      when nil, "--help", "-h" then @out.puts HELP
+      when "--version" then @out.puts "ruby-repo-kit #{VERSION}"
+      when "new" then generate(argv)
+      when "doctor" then doctor(argv)
+      when "release" then release(argv)
+      when "github" then github(argv)
+      else raise OptionParser::InvalidArgument, "unknown command #{command.inspect}"
+      end
+      0
+    rescue OptionParser::ParseError => e
+      @err.puts "ruby-repo-kit: #{e.message}"
+      2
+    rescue Error => e
+      @err.puts "ruby-repo-kit: #{e.message}"
+      1
+    rescue Errno::EPIPE
+      0
+    end
+
+    private
+
+    def project
+      @project ||= Project.load(root: @root)
+    end
+
+    def generate(argv)
+      require_relative "scaffold"
+      settings = {}
+      parser = OptionParser.new do |options|
+        options.on("--repository OWNER/NAME") { |value| settings[:repository] = value }
+        options.on("--directory PATH") { |value| settings[:destination] = File.expand_path(value, @root) }
+        options.on("--author NAME") { |value| settings[:author] = value }
+        options.on("--email ADDRESS") { |value| settings[:email] = value }
+      end
+      name = one_argument(parser.parse(argv), "new requires one gem name")
+      %i[repository author email].each do |key|
+        raise OptionParser::MissingArgument, "--#{key}" unless settings.key?(key)
+      end
+      settings[:destination] ||= File.join(@root, name)
+      destination = Scaffold.new(name: name, **settings).generate
+      @out.puts "Created #{destination}. Run bin/setup there to install development dependencies."
+    end
+
+    def doctor(argv)
+      require_relative "checks"
+      raise OptionParser::InvalidArgument, "doctor takes no arguments" unless argv.empty?
+
+      Checks.new(project: project).run
+      @out.puts "Local maintenance contract verified for #{project.name}."
+    end
+
+    def release(argv)
+      require_relative "release"
+      settings = { dry_run: false, push: false, branch: "main" }
+      parser = OptionParser.new do |options|
+        options.on("--dry-run") { settings[:dry_run] = true }
+        options.on("--push") { settings[:push] = true }
+        options.on("--branch NAME") { |value| settings[:branch] = value }
+      end
+      version = one_argument(parser.parse(argv), "release requires one X.Y.Z version")
+      if settings[:dry_run] && settings[:push]
+        raise OptionParser::InvalidArgument, "--dry-run and --push are mutually exclusive"
+      end
+
+      Release::Workflow.new(version, project: project, out: @out, **settings).run
+    end
+
+    def github(argv)
+      require_relative "github"
+      action = one_argument(argv, "github requires plan, verify or apply")
+      unless %w[plan verify apply].include?(action)
+        raise OptionParser::InvalidArgument, "unknown github action #{action.inspect}"
+      end
+
+      configuration = GitHub::Configuration.new(project: project, out: @out)
+      case action
+      when "plan"
+        pending = configuration.plan
+        pending.each { |change| @out.puts "#{change.verb} #{change.path}: #{change.description}" }
+        @out.puts "No repository-policy changes required." if pending.empty?
+      when "verify" then configuration.verify!
+      when "apply" then configuration.apply!
+      end
+    end
+
+    def one_argument(argv, message)
+      raise OptionParser::InvalidArgument, message unless argv.length == 1
+
+      argv.first
+    end
+  end
+end

data/lib/ruby_repo_kit/commands.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "English"
+require "json"
+require "open3"
+
+module RubyRepoKit
+  # All commands run in the consumer checkout and are passed as argv, never shell text.
+  class Commands
+    def initialize(project:, runner: nil, out: $stdout)
+      @project = project
+      @runner = runner || method(:execute)
+      @out = out
+    end
+
+    def call(argv, stream: false)
+      command = argv.dup
+      command += ["--repo", @project.repository] if command.first == "gh" && %w[pr run release].include?(command[1])
+      @out.puts "==> #{command.join(' ')}"
+      output, status = @runner.call(command, stream: stream)
+      raise Error, "#{command.join(' ')} failed.\n#{output}" unless status.success?
+
+      output
+    end
+
+    def json(argv)
+      JSON.parse(call(argv))
+    rescue JSON::ParserError => e
+      raise Error, "Command returned invalid JSON: #{e.message}"
+    end
+
+    private
+
+    def execute(argv, stream: false)
+      return Open3.capture2e(*argv, chdir: @project.root) unless stream
+
+      system(*argv, chdir: @project.root)
+      ["", $CHILD_STATUS]
+    rescue Errno::ENOENT => e
+      raise Error, "Required command is unavailable: #{e.message}"
+    end
+  end
+end