cimas 0.1.3 → 0.3.0

data/lib/cimas/cli/error.rb

@@ -0,0 +1,8 @@
+module Cimas
+  module Cli
+    # A user-facing error: bad options, refused scope, missing config.
+    # The executable prints one clean line and exits 1; anything else is
+    # an internal error and keeps its backtrace.
+    class Error < StandardError; end
+  end
+end

data/lib/cimas/cli/runner.rb

@@ -0,0 +1,239 @@
+require "thor"
+require "pathname"
+
+module Cimas
+  module Cli
+    # CLI surface only: declares options/help for each subcommand and
+    # delegates to Cimas::Cli::Command (the orchestrator, where all
+    # behavior lives). Adding a subcommand = one desc, its
+    # method_option/shared_options block, and a one-line action calling
+    # run_command. Shared flags are declared exactly once in
+    # SHARED_OPTIONS.
+    class Runner < Thor
+      package_name "cimas"
+
+      # Without this Thor 1.5 exits 0 on its own errors (unknown
+      # command, bad options) — CI would read failure as success.
+      def self.exit_on_failure?
+        true
+      end
+
+      remove_command :tree
+
+      class_option :verbose, type: :boolean, aliases: "-v",
+                             desc: "Run verbosely"
+      class_option :dry_run, type: :boolean,
+                             desc: "Skip destructive/remote operations; print what would be done instead"
+
+      SHARED_OPTIONS = {
+        repos_path: { aliases: "-r", banner: "REPOS_PATH",
+                      desc: "Repo root dir path" },
+        config_path: { aliases: "-f", banner: "CONFIG_FILE_PATH",
+                       desc: "Config file path" },
+        master_path: { aliases: "-d", banner: "CONFIG_MASTER_DIR_PATH",
+                       desc: "Config master path" },
+        groups: { aliases: "-g", banner: "GROUP1,GROUP2",
+                  desc: "Groups to update" },
+        keep_changes: { aliases: "-k", type: :boolean,
+                        desc: "Don't modify revert changes" },
+      }.freeze
+
+      # Thor option symbol → Command option key for value-carrying
+      # flags; the distinct -b/-m spellings per command map onto the
+      # command key the orchestrator reads.
+      STRING_OPTION_KEYS = {
+        push_branch: "push_to_branch",
+        commit_message: "commit_message",
+        merge_branch: "merge_branch",
+        pr_message: "pr_message",
+        pr_body: "pr_body",
+        pr_body_file: "pr_body_file",
+        assignees: "assignees",
+        reviewers: "reviewers",
+        shell_cmd: "shell_cmd",
+        cleanup_branch: "push_to_branch",
+        cleanup_branch_prefix: "cleanup_branch_prefix",
+        orphan_branch: "push_to_branch",
+        orphan_commit_message: "pr_message",
+        cleanup_only_targets: "cleanup_only_targets",
+        target_repo: "target_repo",
+      }.freeze
+
+      def self.shared_options(*names)
+        names.each { |name| method_option name, SHARED_OPTIONS.fetch(name) }
+      end
+
+      desc "setup", "Clone all repos described in the config"
+      shared_options :repos_path, :config_path
+      def setup
+        run_command("setup")
+      end
+
+      desc "pull", "Reset all repos to their configured branch and pull"
+      shared_options :repos_path, :config_path, :groups
+      def pull
+        run_command("pull")
+      end
+
+      desc "sync", "Update CI configurations for all repos described in the config"
+      shared_options :repos_path, :config_path, :master_path, :keep_changes, :groups
+      def sync
+        run_command("sync")
+      end
+
+      desc "diff", "Show diff for all repos"
+      shared_options :repos_path, :config_path, :groups
+      def diff
+        run_command("diff")
+      end
+
+      desc "push", "Push changes to the remote server (requires -g)"
+      shared_options :repos_path, :config_path, :keep_changes, :groups
+      method_option :push_branch, aliases: "-b", banner: "BRANCH",
+                                  desc: "Branch to push in all repos"
+      method_option :commit_message, aliases: "-m", banner: "MESSAGE",
+                                     desc: "Commit message"
+      method_option :force_push, type: :boolean,
+                                 desc: "Force push (with commit amend)"
+      def push
+        run_command("push")
+      end
+
+      desc "open-prs", "Open pull requests on GitHub (requires -g)"
+      shared_options :repos_path, :config_path, :groups
+      method_option :reviewers, aliases: "-w", banner: "REVIEWERS",
+                                desc: "A comma-separated list (no spaces around the comma) of GitHub handles to request a review from"
+      method_option :merge_branch, aliases: "-b", banner: "BRANCH",
+                                   desc: "PR branch to merge into target"
+      method_option :pr_message, aliases: "-m", banner: "MESSAGE",
+                                 desc: "PR title (≤256 chars; what shows on the PR list page)"
+      method_option :pr_body, banner: "BODY",
+                              desc: "Inline PR body (markdown). Mutually exclusive with --body-file."
+      method_option :pr_body_file, banner: "PATH",
+                                   desc: "Path to a file whose contents become the PR body (markdown). Preferred for any non-trivial body — shell-escape-safe and version-controllable. Mutually exclusive with --body."
+      method_option :assignees, aliases: "-a", banner: "ASSIGNMENTS",
+                                desc: "A comma-separated list (no spaces around the comma) of GitHub handles to assign to this pull request."
+      method_option :supersede_stale, type: :boolean,
+                                      desc: "When opening a PR, detect any pre-existing open PRs on the same repo whose head branch starts with 'cimas-sync-' (i.e. previous wave PRs that never merged), label them 'superseded-by-#N' (where N is the new PR number), and post a comment linking the new PR. Does NOT auto-close the old PRs — the reviewer keeps authority over the close decision. The new PR's body is prepended with a 'Supersedes #X, #Y' line. See metanorma/ci#300 Gap 4."
+      method_option :flatten_stale, type: :boolean,
+                                    desc: "Gap 4 full: like --supersede-stale, but ALSO auto-closes the superseded PRs. Implies --supersede-stale. Use when confident the new wave's content strictly supersedes the older waves' (the standard cimas-sync-* case, since every wave regenerates the same files from cimas.yml). Superseded PRs get labelled 'superseded-closed-by-#N', a comment noting auto-closure, and are closed. See metanorma/ci#300 Gap 4 full."
+      def open_prs
+        run_command("open-prs")
+      end
+
+      desc "for-each", "Run a shell command for each repo (requires -g)"
+      shared_options :repos_path, :config_path, :groups
+      method_option :shell_cmd, aliases: "-c", banner: "SHELL_CMD",
+                                desc: "Command to execute"
+      def for_each
+        run_command("for-each")
+      end
+
+      desc "cleanup-merged-prs", "Delete wave branches whose PR has merged (run after merges land; requires -g)"
+      shared_options :repos_path, :config_path, :groups
+      method_option :cleanup_branch, aliases: "-b", banner: "BRANCH",
+                                     desc: "Wave branch to clean up (same as the -b push_to_branch used in `cimas push`)"
+      def cleanup_merged_prs
+        run_command("cleanup-merged-prs")
+      end
+
+      desc "cleanup-closed-prs", "Delete wave branches whose PR was closed without merge (org-wide sweep of cimas-sync-*; requires -g)"
+      shared_options :repos_path, :config_path, :groups
+      method_option :cleanup_branch_prefix, banner: "PREFIX",
+                                            desc: "Branch-name prefix to sweep (default: cimas-sync-). All closed-not-merged PRs whose head.ref starts with this prefix have their remote branch deleted."
+      def cleanup_closed_prs
+        run_command("cleanup-closed-prs")
+      end
+
+      desc "cleanup-orphan-files", "Delete files with the Cimas auto-generated header that are no longer in cimas.yml mapping (sync's inverse; -g required with --push-after)"
+      shared_options :repos_path, :config_path, :groups
+      method_option :orphan_branch, aliases: "-b", banner: "BRANCH",
+                                    desc: "Branch to create with the orphan-file deletions (e.g. cleanup-orphans-2026-07-05). Same shape as `-b` on push."
+      method_option :orphan_commit_message, aliases: "-m", banner: "MESSAGE",
+                                            desc: "Commit message for the cleanup commit."
+      method_option :cleanup_push_after, type: :boolean,
+                                         desc: "After detecting + staging orphan deletions, commit + force-push the cleanup branch to each repo's remote. Without this flag the deletions are staged locally only (for inspection / manual push)."
+      method_option :cleanup_only_targets, banner: "PATH1,PATH2",
+                                           desc: "Narrow the sweep to specific target paths (comma-separated, no spaces). Files at other target paths are left alone even if orphaned. Use to scope a cleanup wave to one class of orphan (e.g. --only-target=.github/workflows/generate.yml for the ci#347 docker-only cleanup)."
+      def cleanup_orphan_files
+        run_command("cleanup-orphan-files")
+      end
+
+      desc "release-preflight", "Local fail-fast checks before firing a release workflow"
+      shared_options :repos_path, :config_path
+      method_option :target_repo, banner: "NAME",
+                                  desc: "Target gem repo to preflight (must be in cimas.yml)"
+      def release_preflight
+        run_command("release-preflight")
+      end
+
+      no_commands do
+        def run_command(name)
+          Cimas::Cli::Command.new(command_options).execute(name)
+        end
+
+        # Translates Thor's parsed options into the option hash
+        # Cimas::Cli::Command consumes: string keys, Pathname paths,
+        # comma-split groups. Keys absent here fall back to Command's
+        # DEFAULT_CONFIG.
+        def command_options
+          opts = options
+
+          result = path_options(opts)
+          result.merge!(string_options(opts))
+          result.merge!(flag_options(opts))
+          result["groups"] = comma_list(opts[:groups]) if opts[:groups]
+          if result["pr_body_file"]
+            result["pr_body_file"] = existing_file(result["pr_body_file"], flag: "--body-file")
+          end
+          result
+        end
+
+        def path_options(opts)
+          {
+            "repos_path" => Pathname.getwd + (opts[:repos_path] || "repos"),
+            "config_file_path" => existing_path(opts[:config_path] || "cimas.yml",
+                                                flag: "-f/--config-path"),
+            "config_master_path" => opts[:master_path] ? existing_path(opts[:master_path], flag: "-d/--master-path") : Pathname.getwd + "config",
+            "dry_run" => opts[:dry_run] == true,
+            "verbose" => opts[:verbose] == true,
+          }
+        end
+
+        def string_options(opts)
+          STRING_OPTION_KEYS.each_with_object({}) do |(thor_key, command_key), result|
+            result[command_key] = opts[thor_key] unless opts[thor_key].nil?
+          end
+        end
+
+        def flag_options(opts)
+          result = {}
+          %i[keep_changes force_push supersede_stale flatten_stale cleanup_push_after].each do |key|
+            result[key.to_s] = true if opts[key]
+          end
+          # flatten implies supersede
+          result["supersede_stale"] = true if result["flatten_stale"]
+          result
+        end
+
+        def existing_path(value, flag:)
+          path = Pathname.getwd + value
+          raise Cimas::Cli::Error, "#{flag} path is not set or does not exist: #{path}" unless path.exist?
+
+          path
+        end
+
+        def existing_file(value, flag:)
+          file = Pathname.getwd + value
+          raise Cimas::Cli::Error, "#{flag} path does not exist: #{file}" unless file.exist?
+
+          file
+        end
+
+        def comma_list(value)
+          value.split(",").map(&:strip).reject(&:empty?)
+        end
+      end
+    end
+  end
+end

data/lib/cimas/cli.rb

@@ -0,0 +1,7 @@
+module Cimas
+  module Cli
+    autoload :Command, File.expand_path("cli/command", __dir__)
+    autoload :Error, File.expand_path("cli/error", __dir__)
+    autoload :Runner, File.expand_path("cli/runner", __dir__)
+  end
+end

data/lib/cimas/github.rb

@@ -0,0 +1,47 @@
+require "octokit"
+
+module Cimas
+  # Octokit boundary: client construction, remote-to-slug mapping, and
+  # the visibility-lookup fallback policy live here; the orchestrator
+  # speaks in slugs. Pass `client:` to inject a stand-in for offline
+  # specs (production code always omits it).
+  class GitHub
+    def initialize(token: nil, client: nil)
+      @token = token
+      @client = client
+    end
+
+    def client
+      return @client if @client
+
+      if @token.nil?
+        raise "[ERROR] Please set GITHUB_TOKEN environment variable to use GitHub functions."
+      end
+      @client = Octokit::Client.new(access_token: @token)
+    end
+
+    # Maps any GitHub remote form (ssh://git@github.com/org/repo,
+    # git@github.com:org/repo.git, https://github.com/org/repo.git) to
+    # the `org/repo` slug Octokit expects.
+    def slug_for(remote)
+      match = remote.to_s.match(%r{github\.com[/:](.+?)(?:\.git)?\z})
+      unless match
+        raise "[ERROR] not a GitHub remote: #{remote.inspect} — cimas only operates on GitHub repositories."
+      end
+
+      match[1]
+    end
+
+    # True when the repo is GitHub-private. Falls back to `true` (no
+    # accidental public template picks) when the API is unreachable.
+    def fetch_visibility(slug)
+      client.repo(slug).private
+    rescue Octokit::NotFound
+      puts "[WARNING] Cannot fetch visibility for #{slug} (404); defaulting to `private` (safer)."
+      true
+    rescue StandardError => e
+      puts "[WARNING] Visibility fetch failed for #{slug}: #{e.message}; defaulting to `private` (safer)."
+      true
+    end
+  end
+end

data/lib/cimas/orphan_files.rb

@@ -0,0 +1,37 @@
+module Cimas
+  # Finds files under a repo working copy that cimas generated (they
+  # carry the generated header) but that the repo's current `files:`
+  # mapping no longer lists — `sync`'s inverse. Pure logic: no config,
+  # git, or GitHub access.
+  module OrphanFiles
+    # Bytes read per file when checking for the header — covers the
+    # two-line header plus any leading shebang or comment; shorter
+    # files read to EOF without error.
+    HEADER_READ_BYTES = 500
+
+    def self.find(repo_dir, mapped_targets, only_targets = nil)
+      orphans = []
+      Dir.glob(File.join(repo_dir, '**', '*'), File::FNM_DOTMATCH).each do |path|
+        next unless File.file?(path)
+        next if path.include?('/.git/') || path.end_with?('/.git')
+
+        head = read_head(path)
+        next unless head&.include?(Cimas::GENERATED_HEADER_MARKER)
+
+        rel_path = path.sub("#{repo_dir}/", '')
+        next if only_targets && !only_targets.include?(rel_path)
+
+        orphans << rel_path unless mapped_targets.include?(rel_path)
+      end
+      orphans
+    end
+
+    def self.read_head(path)
+      File.read(path, HEADER_READ_BYTES, encoding: 'UTF-8')
+    rescue ArgumentError, EncodingError, SystemCallError
+      # Binary, malformed encoding, or unreadable — cimas only writes
+      # text files, so these cannot be cimas-managed.
+      nil
+    end
+  end
+end

data/lib/cimas/patch.rb

@@ -0,0 +1,25 @@
+module Cimas
+  # Value object over one `patches:` entry in cimas.yml — an in-place
+  # regex find/replace applied to files already present in each target
+  # repo (unlike `files:` sync, which replaces whole files). See the
+  # Patches section of README.adoc.
+  class Patch
+    attr_reader :name, :globs, :find_regexp, :replacement, :group_names
+
+    def initialize(name, attributes)
+      @name = name
+      @globs = Array(attributes["files"])
+      @find_regexp = Regexp.new(attributes["find"])
+      @replacement = attributes["replace"]
+      @group_names = attributes["groups"] || []
+    end
+
+    def matches?(content)
+      find_regexp.match?(content)
+    end
+
+    def apply(content)
+      content.gsub(find_regexp, replacement)
+    end
+  end
+end

data/lib/cimas/release_preflight.rb

@@ -0,0 +1,140 @@
+module Cimas
+  # Local maintainer-side preflight that mirrors the GHA preflight job in
+  # `metanorma/ci/.github/workflows/rubygems-release.yml`. Runs against a
+  # single repo's workspace clone before the maintainer fires the
+  # `workflow_dispatch` to actually start the release chain. Catches the
+  # cheap, deterministic failure modes (bundle resolve, gemspec errors,
+  # missing credentials, already-published version) in ~30 sec locally,
+  # so the maintainer never commits to the 2+ hour chain on a release
+  # that was going to fail.
+  #
+  # Companion to the GHA-side preflight introduced in metanorma/ci PR #313.
+  # Both protect against the same class of failures; the GHA preflight
+  # protects every release attempt automatically, this one protects the
+  # maintainer who runs it before firing.
+  #
+  # `runner:` injects the process boundary for offline specs (production
+  # omits it and uses the default shell runner).
+  class ReleasePreflight
+    # Default process boundary: real shell + filesystem credential check.
+    class ShellRunner
+      def system!(*args)
+        system(*args)
+      end
+
+      def capture(cmd)
+        `#{cmd}`
+      end
+
+      def credentials_present?
+        File.exist?(File.expand_path("~/.gem/credentials"))
+      end
+
+      def api_key_present?
+        ENV["RUBYGEMS_API_KEY"] && !ENV["RUBYGEMS_API_KEY"].empty?
+      end
+    end
+
+    def initialize(command, runner: nil)
+      @command = command
+      @runner = runner || ShellRunner.new
+    end
+
+    def run
+      repo_name = @command.config["target_repo"]
+
+      repo = @command.repo_by_name(repo_name)
+      if repo.nil?
+        raise "[ERROR] #{repo_name} is not in cimas.yml. Run with --config-path pointing at the correct config."
+      end
+
+      repo_dir = File.join(@command.repos_path, repo_name)
+      unless File.exist?(repo_dir) && File.exist?(File.join(repo_dir, ".git"))
+        raise "[ERROR] #{repo_name} is not present in #{@command.repos_path}. Run `cimas setup` first."
+      end
+
+      puts "=== cimas release-preflight: #{repo_name} ==="
+      puts "    workspace: #{repo_dir}"
+      puts ""
+
+      failures = []
+
+      Dir.chdir(repo_dir) do
+        puts "[1/4] Fresh bundle install (Gemfile.lock removed first)..."
+        File.delete("Gemfile.lock") if File.exist?("Gemfile.lock")
+        unless @runner.system!("bundle install --jobs 4 --retry 3")
+          failures << "bundle install"
+          puts "    ✗ bundle install failed"
+        else
+          puts "    ✓ bundle install succeeded"
+        end
+        puts ""
+
+        puts "[2/4] Gem build (validates gemspec)..."
+        gemspec_file = Dir["*.gemspec"].first
+        if gemspec_file.nil?
+          puts "    ⚠️  No .gemspec file found in repo root; skipping gem build check"
+        else
+          if @runner.system!("gem build #{gemspec_file}")
+            puts "    ✓ gem build succeeded"
+            Dir["*.gem"].each { |f| File.delete(f) }
+          else
+            failures << "gem build"
+            puts "    ✗ gem build failed"
+          end
+        end
+        puts ""
+
+        puts "[3/4] Verify publish credentials available..."
+        if @runner.credentials_present?
+          puts "    ✓ ~/.gem/credentials present (API-key publish path viable)"
+        elsif @runner.api_key_present?
+          puts "    ✓ RUBYGEMS_API_KEY env var present"
+        else
+          puts "    ⚠️  No ~/.gem/credentials and no RUBYGEMS_API_KEY env var."
+          puts "        OIDC Trusted Publishing may still work in CI, but local `gem push` will fail."
+          puts "        Configure ~/.gem/credentials if you intend to publish from this machine."
+        end
+        puts ""
+
+        puts "[4/4] Version awareness..."
+        gem_spec = gemspec_file ? Gem::Specification.load(gemspec_file) : nil
+        if gem_spec
+          gem_name = gem_spec.name
+          gem_version = gem_spec.version.to_s
+          remote_list = @runner.capture(
+            "gem list --remote --exact --version \"#{gem_version}\" \"#{gem_name}\" 2>/dev/null",
+          )
+          if remote_list.include?("#{gem_name} (#{gem_version})")
+            puts "    ℹ️  #{gem_name} #{gem_version} is already on rubygems.org"
+            puts "        With next_version=skip, the idempotent guard will skip the actual gem push."
+            puts "        If you intended to ship NEW code, fire with next_version=patch (or major/minor)."
+          else
+            puts "    ✓ #{gem_name} #{gem_version} is NOT yet on rubygems — clean to publish"
+            latest_list = @runner.capture(
+              "gem list --remote --exact \"#{gem_name}\" 2>/dev/null",
+            )
+            if latest_match = latest_list.match(/#{Regexp.escape(gem_name)} \(([0-9.]+)/)
+              puts "        Latest published: #{gem_name} #{latest_match[1]}"
+            else
+              puts "        (No previous public version found.)"
+            end
+          end
+        else
+          puts "    (skipped — no gemspec to identify)"
+        end
+        puts ""
+      end
+
+      puts "=== Result ==="
+      if failures.empty?
+        puts "✓ All preflight checks passed for #{repo_name}."
+        puts "  Safe to fire: gh workflow run release.yml --repo metanorma/#{repo_name} --field next_version=patch"
+      else
+        puts "✗ Preflight FAILED for #{repo_name}: #{failures.join(', ')}"
+        puts "  Do NOT fire the release workflow until the failures above are fixed."
+        exit 1
+      end
+    end
+  end
+end

data/lib/cimas/repository.rb

@@ -0,0 +1,33 @@
+module Cimas
+  # Value object over one `repositories:` entry in cimas.yml. Always built
+  # with real attributes — unknown repo names are the caller's problem
+  # (see `Cli::Command#repo_by_name`, which returns nil for them).
+  class Repository
+    attr_reader :name, :remote, :branch, :files, :binding, :with_values
+
+    def initialize(name, attributes = {})
+      @name = name
+
+      @remote = attributes.fetch("remote", nil)
+      @branch = attributes.fetch("branch", nil)
+      # `files:` in cimas.yml is typically a Hash (`local_path: template_path`),
+      # but some entries use `files: []` (a YAML empty Array) to signal
+      # "no sync mappings — track the repo but don't touch any file."
+      # Normalise both shapes to a Hash so downstream `#files.keys` works.
+      raw_files = attributes.fetch("files", nil)
+      @files = raw_files.is_a?(Array) ? {} : (raw_files || {})
+      # Hash#dig doesn't accept a block — the `{ {} }` in the prior
+      # version was silently ignored, so absent `template: binding:`
+      # yielded `nil`. Explicit `|| {}` keeps the type stable (always a
+      # Hash); the sole consumer at `Cli::Command#sync` wraps it in an
+      # OpenStruct where nil and {} behave identically, so this is a
+      # correctness-not-behaviour fix.
+      @binding = attributes.dig("template", "binding") || {}
+      # `with:` is a per-repo top-level hash rendered into ERB templates
+      # as `with_values`. Semantically intended for reusable-workflow
+      # `with:` block inputs (per metanorma/ci#300 Gap 1) but the values
+      # are just a Hash — usable for any parametric rendering.
+      @with_values = attributes.fetch("with", {}) || {}
+    end
+  end
+end

data/lib/cimas/version.rb

@@ -1,3 +1,3 @@
 module Cimas
-  VERSION = "0.1.3"
+  VERSION = "0.3.0"
 end

data/lib/cimas/working_copy.rb

@@ -0,0 +1,136 @@
+require "git"
+require "open3"
+
+module Cimas
+  # Deep module over one repository's working copy: every git-gem call,
+  # exception rescue, and porcelain/CLI parsing the orchestrator needs
+  # lives behind ~10 domain verbs. Subcommands then read as wave prose
+  # instead of git incantations.
+  class WorkingCopy
+    def self.open(dir)
+      new(Git.open(dir))
+    end
+
+    def self.clone(remote, name, path:)
+      Git.clone(remote, name, path: path)
+    end
+
+    def initialize(git)
+      @git = git
+    end
+
+    def head_sha
+      @git.object("HEAD").sha
+    end
+
+    def remote_name
+      @git.remotes.first.to_s
+    end
+
+    # True when the working copy has any uncommitted change.
+    def drift?
+      out, = Open3.capture3("git", "-C", dir, "status", "--porcelain")
+      !out.strip.empty?
+    rescue StandardError
+      false
+    end
+
+    # checkout + reset_hard + clean: the "start from a pristine branch"
+    # preamble of sync and cleanup-orphan-files.
+    def reset_clean(branch, include_untracked: false)
+      checkout(branch)
+      @git.reset_hard(branch)
+      @git.clean(force: true, d: include_untracked)
+    end
+
+    def stage(*paths)
+      paths.each { |path| @git.add(path) }
+    end
+
+    def remove(*paths)
+      paths.each { |path| @git.remove(path) }
+    end
+
+    # True when nothing is staged or modified — push skips the
+    # commit in this case.
+    def clean?
+      status = @git.status
+      status.changed.empty? && status.added.empty? && status.deleted.empty?
+    end
+
+    def commit_all(message)
+      @git.commit_all(message)
+    end
+
+    def commit(message)
+      @git.commit(message)
+    end
+
+    # push's keep_changes=false preamble: stand on the base branch,
+    # soft-reset onto it, and discard an existing branch of the given
+    # name so it can be provisioned fresh.
+    def reset_onto(base, discard_branch: nil)
+      checkout(base)
+      @git.reset(base)
+      @git.branch(discard_branch).delete if discard_branch && @git.is_branch?(discard_branch)
+    end
+
+    # Switch to a branch; :fresh discards an existing branch of the same
+    # name first (cleanup-orphan-files' shape).
+    def switch_branch(name, fresh: false)
+      @git.branch(name).delete if fresh && @git.is_branch?(name)
+      @git.branch(name).checkout
+    end
+
+    # pull's dance: fetch origin, best-effort reset (a fresh clone may
+    # not hold the branch ref yet), checkout, pull.
+    def fetch_reset_pull(branch)
+      @git.remote("origin").fetch
+      begin
+        @git.reset_hard(branch)
+      rescue Git::Error
+        # reset can fail when the branch ref is absent on a fresh
+        # clone; checkout/pull below still applies.
+        nil
+      end
+      checkout(branch)
+      @git.pull("origin", branch)
+    end
+
+    # Returns :pushed, :behind_remote (non-force push behind the remote
+    # tip), or [:rejected, error]. The caller decides presentation.
+    # "Updates were rejected" covers both the classic git phrasing
+    # ("tip of your current branch is behind") and the modern one ("the
+    # remote contains work that you do not have locally").
+    def push(branch, force: false, remote: nil)
+      @git.push(remote || remote_name, branch, force: force)
+      :pushed
+    rescue Git::GitExecuteError, Git::FailedError => e
+      if e.message.match?(/Updates were rejected/)
+        :behind_remote
+      else
+        [:rejected, e]
+      end
+    end
+
+    def diff_patch
+      @git.diff.patch
+    end
+
+    def each_staged_change
+      @git.status.changed.each do |file, status|
+        yield(file, status.blob(:index).contents)
+      end
+    end
+
+    private
+
+    def checkout(branch)
+      @git.checkout(branch)
+    end
+
+    def dir
+      @git.dir.to_s
+    end
+  end
+end