kettle-dev 1.1.1 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a5adcf9f057ec385ca20f8441e9cf7cf45a3c28916146dc828342cc280a7275
-  data.tar.gz: 9c85ede6e630a006c83d26db02f2938be131fb227b3aa76e1e8f531f616edf3a
+  metadata.gz: c3eb6a72bd85bbfde7317e4001bed71b6f06c23e8094ec3d7028135ea787cb8a
+  data.tar.gz: f8a6c719e95549c12739aead51912b68e49713cf1c12a2aa134a61404d82825c
 SHA512:
-  metadata.gz: ae3e344c567670c9817d9724bddbe08f926564e906843ae02bb95110bb2fce3ae3769511a5106e73bcb0abf93c2a1a64cf876c5d82bd6052adaa6046cd5eeecb
-  data.tar.gz: 9ccad75834eb783f912660a214416e3fd53d8229955a69026c013fbcb4ddfd6b43bc211ace28e7a0e7dec08f41a2c3463e862515f7fae0e9059111c49c478d74
+  metadata.gz: fe84cb073f601bc8b2c0e50979d229d81d5fa45b3f64455837d17b624fbd2ac3d75c2180b1d87df306e4d7b6efbda20a9d5c94926783fc06091b3b21f61aa368
+  data.tar.gz: 3a0b31c5be00d77c9b8c9073413caa80a9023f1291b5dd7c98c2a323e712e0756904bdb70fd00e319ca28021e44bdcf16f5506c9e25e18b8aa8c006f0102d254

checksums.yaml.gz.sig

@@ -1,3 +1,2 @@
-�kj��~�Y��/���
-�E���RO7VO$����<a>q��o_o�LM�h|���$Z%������H���{��/��?,�z��
-"�}1����m�B�$��1�W��Eہ�li�D6��̛0��;&m��]�D�તO�����B=s�_E)�)�Ro�� I��VtaaĪ�Y���ӝT�jR;]`��4Ю��(y��h"\8sØ�۸�{;��a
+\\o��ְ{vnq��Ѱ��ޙfl�P{���Q��J��Qj+`&3���=�Fw��7�Ӯ�(`���jMYl�q14����M�s�2�����)�9��|�<7S^[�D�Z�I,V�� z���ņ��d���[�H���h�������ҷﮀLo��_P�lj0��d!8!�Z�Bk�>�+�o���X�<4�!u�ֺx����<�:|��egoFx{��R���ԓ����a+�:�c�ӃoK�-8�+�T3��𑰤�s�8�yD�C����q�@p�X��2��Zq$eG��
+���� 8Q��D�k�Q��T����k���0���p�:����ޜ}�Z��yi_|[�Х�*'

data/.gitignore

@@ -16,6 +16,7 @@ Appraisal.*.gemfile.lock
 /coverage/
 /spec/reports/
 /results/
+.output.txt
 
 # Documentation
 /.yardoc/

data/.gitlab-ci.yml.example

@@ -1,3 +1,17 @@
+# You can override the included template(s) by including variable overrides
+# SAST customization: https://docs.gitlab.com/ee/user/application_security/sast/#customizing-the-sast-settings
+# Secret Detection customization: https://docs.gitlab.com/ee/user/application_security/secret_detection/#customizing-settings
+# Dependency Scanning customization: https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#customizing-the-dependency-scanning-settings
+# Container Scanning customization: https://docs.gitlab.com/ee/user/application_security/container_scanning/#customizing-the-container-scanning-settings
+# Note that environment variables can be set in several places
+# See https://docs.gitlab.com/ee/ci/variables/#cicd-variable-precedence
+#stages:
+#  - test
+#sast:
+#  stage: test
+#include:
+#  - template: Security/SAST.gitlab-ci.yml
+
 default:
   image: ruby
 

data/.rubocop.yml

@@ -14,3 +14,6 @@ RSpec/ExampleLength:
 
 RSpec/MultipleExpectations:
   Enabled: false
+
+RSpec/NestedGroups:
+  Enabled: false

data/CHANGELOG.md

@@ -24,6 +24,36 @@ Please file a bug if you notice a violation of semantic versioning.
 ### Fixed
 ### Security
 
+## [1.1.3] - 2025-09-02
+- TAG: [v1.1.3][1.1.3t]
+- COVERAGE: 97.14% -- 2857/2941 lines in 22 files
+- BRANCH COVERAGE: 82.29% -- 1194/1451 branches in 22 files
+- 76.22% documented
+### Changed
+- URL for migrating repo to CodeBerg:
+  - https://codeberg.org/repo/migrate
+### Fixed
+- Stop double defining DEBUGGING constant
+
+## [1.1.2] - 2025-09-02
+- TAG: [v1.1.2][1.1.2t]
+- COVERAGE: 97.14% -- 2858/2942 lines in 22 files
+- BRANCH COVERAGE: 82.29% -- 1194/1451 branches in 22 files
+- 76.76% documented
+### Added
+- .gitlab-ci.yml documentation (in example)
+- kettle-dvcs script for setting up DVCS, and checking status of remotes
+  - https://railsbling.com/posts/dvcs/put_the_d_in_dvcs/
+- kettle-dvcs --status: prefix "ahead by N" with ✅️ when N==0, and 🔴 when N>0
+- kettle-dvcs --status: also prints a Local status section comparing local HEAD to origin/<branch>, and keeps origin visible via that section
+- Document kettle-dvcs CLI in README (usage, options, examples)
+- RBS types for Kettle::Dev::DvcsCLI and inline YARD docs on CLI
+- Specs for DvcsCLI covering remote normalization, fetch outcomes, and README updates
+### Changed
+- major spec refactoring
+### Fixed
+- (linting) rspec-pending_for 0.0.17+ (example gemspec)
+
 ## [1.1.1] - 2025-09-02
 - TAG: [v1.1.1][1.1.1t]
 - COVERAGE: 97.04% -- 2655/2736 lines in 21 files
@@ -428,7 +458,11 @@ Please file a bug if you notice a violation of semantic versioning.
   - Selecting will run the selected workflow via `act`
   - This may move to its own gem in the future.
 
-[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.1...HEAD
+[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.3...HEAD
+[1.1.3]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.2...v1.1.3
+[1.1.3t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.3
+[1.1.2]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.1...v1.1.2
+[1.1.2t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.2
 [1.1.1]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.0...v1.1.1
 [1.1.1t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.1
 [1.1.0]: https://github.com/kettle-rb/kettle-dev/compare/v1.0.27...v1.1.0

data/CONTRIBUTING.md

@@ -89,9 +89,10 @@ bundle exec rake test
 
 ### Spec organization (required)
 
-- For each class or module under `lib/`, keep all of its unit tests in a single spec file under `spec/` that mirrors the path and file name (e.g., specs for `lib/kettle/dev/release_cli.rb` live in `spec/kettle/dev/release_cli_spec.rb`).
-- Do not create ad-hoc "_more" or split spec files for the same class/module. Consolidate all unit tests into the main spec file for that class/module.
-- Only integration scenarios that intentionally span multiple classes belong in `spec/integration/`.
+- One spec file per class/module. For each class or module under `lib/`, keep all of its unit tests in a single spec file under `spec/` that mirrors the path and file name exactly: `lib/kettle/dev/release_cli.rb` -> `spec/kettle/dev/release_cli_spec.rb`.
+- Never add a second spec file for the same class/module. Examples of disallowed names: `*_more_spec.rb`, `*_extra_spec.rb`, `*_status_spec.rb`, or any other suffix that still targets the same class. If you find yourself wanting a second file, merge those examples into the canonical spec file for that class/module.
+- Exception: Integration specs that intentionally span multiple classes. Place these under `spec/integration/` (or a clearly named integration folder), and do not directly mirror a single class. Name them after the scenario, not a class.
+- Migration note: If a duplicate spec file exists, move all examples into the canonical file and delete the duplicate. Do not leave stubs or empty files behind.
 
 ## Lint It
 

data/README.md

@@ -77,6 +77,51 @@ Compatible with MRI Ruby 2.3+, and concordant releases of JRuby, and TruffleRuby
 
 ### Federated DVCS
 
+#### kettle-dvcs (normalize multi-forge remotes)
+
+- Script: `exe/kettle-dvcs` (install binstubs for convenience: `bundle binstubs kettle-dev --path bin`)
+- Purpose: Normalize git remotes across GitHub, GitLab, and Codeberg, and create an `all` remote that pushes to all and fetches only from your chosen origin.
+- Assumptions: org and repo names are identical across forges.
+
+Usage:
+
+```console
+kettle-dvcs [options] [ORG] [REPO]
+```
+
+Options:
+- `--origin [github|gitlab|codeberg]` Which forge to use as `origin` (default: github)
+- `--protocol [ssh|https]` URL style (default: ssh)
+- `--github-name NAME` Remote name for GitHub when not origin (default: gh)
+- `--gitlab-name NAME` Remote name for GitLab (default: gl)
+- `--codeberg-name NAME` Remote name for Codeberg (default: cb)
+- `--force` Non-interactive; accept defaults, and do not prompt for ORG/REPO
+
+Examples:
+- Default, interactive (infers ORG/REPO from an existing remote when possible):
+  ```console
+  kettle-dvcs
+  ```
+- Non-interactive with explicit org/repo:
+  ```console
+  kettle-dvcs --force my-org my-repo
+  ```
+- Use GitLab as origin and HTTPS URLs:
+  ```console
+  kettle-dvcs --origin gitlab --protocol https my-org my-repo
+  ```
+
+What it does:
+- Ensures remotes exist and have consistent URLs for each forge.
+- Renames existing remotes when their URL already matches the desired target but their name does not (e.g., `gitlab` -> `gl`).
+- Creates/refreshes an `all` remote that:
+  - fetches only from your chosen `origin` forge.
+  - has pushurls configured for all three forges so `git push all <branch>` updates all mirrors.
+- Prints `git remote -v` at the end.
+- Attempts to `git fetch` each forge remote to check availability:
+  - If all succeed, the README’s federated DVCS summary line has “(Coming soon!)” removed.
+  - If any fail, the script prints import links to help you create a mirror on that forge.
+
 <details>
   <summary>Find this repo on other forges (Coming soon!)</summary>
 
@@ -750,7 +795,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]:https://gitmoji.dev
 [📌gitmoji-img]:https://img.shields.io/badge/gitmoji_commits-%20😜%20😍-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.736-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.941-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/README.md.example

@@ -505,7 +505,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]:https://gitmoji.dev
 [📌gitmoji-img]:https://img.shields.io/badge/gitmoji_commits-%20😜%20😍-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.736-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.941-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/Rakefile.example

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# kettle-dev Rakefile v1.1.1 - 2025-09-02
+# kettle-dev Rakefile v1.1.3 - 2025-09-02
 # Ruby 2.3 (Safe Navigation) or higher required
 #
 # MIT License (see License.txt)

data/exe/kettle-dvcs

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# vim: set syntax=ruby
+
+# kettle-dvcs: Normalize git remotes across GitHub, GitLab, and Codeberg
+# - Aligns/creates remotes for the three forges and an 'all' remote
+# - Attempts fetch from each forge and updates README federation summary
+
+# Immediate, unbuffered output
+$stdout.sync = true
+$stderr.sync = true
+
+# Depending library or project must be using bundler
+require "bundler/setup"
+
+script_basename = File.basename(__FILE__)
+
+begin
+  require "kettle/dev"
+  puts "== #{script_basename} v#{Kettle::Dev::Version::VERSION} =="
+rescue LoadError => e
+  warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
+  warn("Hint: Ensure the host project has kettle-dev as a dependency and run bundle install.")
+  exit(1)
+end
+
+# Always execute when this file is loaded (e.g., via a Bundler binstub).
+# Do not guard with __FILE__ == $PROGRAM_NAME because binstubs use Kernel.load.
+if ARGV.include?("-h") || ARGV.include?("--help")
+  puts <<~USAGE
+    Usage: kettle-dvcs [options] [ORG] [REPO]
+
+    Normalizes git remotes across GitHub, GitLab, and Codeberg.
+
+    Options:
+      --origin [github|gitlab|codeberg]   Choose origin forge (default: github)
+      --protocol [ssh|https]              URL scheme (default: ssh)
+      --github-name NAME                  Remote name for GitHub when not origin (default: gh)
+      --gitlab-name NAME                  Remote name for GitLab (default: gl)
+      --codeberg-name NAME                Remote name for Codeberg (default: cb)
+      --status                            Fetch remotes; show ahead/behind vs origin/main
+      --force                             Non-interactive; accept defaults
+
+    Behavior:
+      - Ensures remotes exist and have consistent URLs
+      - Creates an 'all' remote that fetches from origin only and pushes to all three
+      - Prints `git remote -v`
+      - Fetches each forge to detect availability and updates README accordingly
+
+    Environment:
+      KETTLE_DEV_DISABLE_GIT_GEM=true     # force CLI git backend even if 'git' gem present
+      DEBUG=true                           # print backtraces on errors
+  USAGE
+  exit 0
+end
+
+begin
+  # Pass ARGV through; DvcsCLI does option parsing
+  exit(Kettle::Dev::DvcsCLI.new(ARGV).run!)
+rescue LoadError => e
+  warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
+  warn(e.backtrace.join("\n")) if ENV["DEBUG"]
+  exit(1)
+rescue SystemExit => e
+  warn("#{script_basename}: exited (status=#{e.status}, msg=#{e.message})") if e.status != 0
+  raise
+rescue StandardError => e
+  warn("#{script_basename}: unexpected error: #{e.class}: #{e.message}")
+  warn(e.backtrace.join("\n"))
+  exit(1)
+end

data/kettle-dev.gemspec.example

@@ -130,7 +130,7 @@ Gem::Specification.new do |spec|
   # Testing
   spec.add_development_dependency("appraisal2", "~> 3.0")                           # ruby >= 1.8.7, for testing against multiple versions of dependencies
   spec.add_development_dependency("kettle-test", "~> 1.0")                          # ruby >= 2.3
-  spec.add_development_dependency("rspec-pending_for")                                # ruby >= 2.3, used to skip specs on incompatible Rubies
+  spec.add_development_dependency("rspec-pending_for", "~> 0.0", ">= 0.0.17")       # ruby >= 2.3, used to skip specs on incompatible Rubies
 
   # Releasing
   spec.add_development_dependency("ruby-progressbar", "~> 1.13")                    # ruby >= 0

data/lib/kettle/dev/dvcs_cli.rb

@@ -0,0 +1,396 @@
+require "optparse"
+
+module Kettle
+  module Dev
+    # CLI to normalize git remotes across GitHub, GitLab, and Codeberg.
+    # - Defaults: origin=github, protocol=ssh, gitlab remote name=gl, codeberg remote name=cb
+    # - Creates/aligns remotes and an 'all' remote that pulls only from origin, pushes to all
+    #
+    # Usage:
+    #   kettle-dvcs [options] [ORG] [REPO]
+    #
+    # Options:
+    #   --origin [github|gitlab|codeberg]   Choose which forge is origin (default: github)
+    #   --protocol [ssh|https]              Use git+ssh or HTTPS URLs (default: ssh)
+    #   --gitlab-name NAME                  Remote name for GitLab (default: gl)
+    #   --codeberg-name NAME                Remote name for Codeberg (default: cb)
+    #   --force                             Accept defaults; non-interactive
+    #
+    # Behavior:
+    # - Aligns or creates remotes for github, gitlab, and codeberg with consistent org/repo and protocol
+    # - Renames existing remotes to match chosen naming scheme when URLs already match
+    # - Creates an "all" remote that fetches from origin only and pushes to all three forges
+    # - Attempts to fetch from each forge to determine availability and updates README federation summary
+    #
+    # @example Non-interactive run with defaults (origin: github, protocol: ssh)
+    #   kettle-dvcs --force my-org my-repo
+    #
+    # @example Use GitLab as origin and HTTPS URLs
+    #   kettle-dvcs --origin gitlab --protocol https my-org my-repo
+    class DvcsCLI
+      DEFAULTS = {
+        origin: "github",
+        protocol: "ssh",
+        gh_name: "gh",
+        gl_name: "gl",
+        cb_name: "cb",
+        force: false,
+        status: false,
+      }.freeze
+      FORGE_MIGRATION_TOOLS = {
+        github: "https://github.com/new/import",
+        gitlab: "https://gitlab.com/projects/new#import_project",
+        codeberg: "https://codeberg.org/repo/migrate",
+      }.freeze
+
+      # Create the CLI with argv-like arguments
+      # @param argv [Array<String>] the command-line arguments (without program name)
+      def initialize(argv)
+        @argv = argv
+        @opts = DEFAULTS.dup
+      end
+
+      # Execute the CLI command.
+      # Aligns remotes, configures the `all` remote, prints remotes, attempts fetches,
+      # and updates README federation status accordingly.
+      # @return [Integer] exit status code (0 on success; may abort with non-zero)
+      def run!
+        parse!
+        git = ensure_git_adapter!
+
+        if @opts[:status]
+          # Status mode: no working tree mutation beyond fetch. Don't require clean tree.
+          _, _ = resolve_org_repo(git)
+          names = remote_names
+          branch = detect_default_branch!(git)
+          say("Fetching all remotes for status...")
+          # Fetch origin first to ensure origin/<branch> is up to date
+          git.fetch(names[:origin]) if names[:origin]
+          %i[github gitlab codeberg].each do |forge|
+            r = names[forge]
+            next unless r && r != names[:origin]
+            git.fetch(r)
+          end
+          show_status!(git, names, branch)
+          show_local_vs_origin!(git, branch)
+          return 0
+        end
+
+        abort!("Working tree is not clean; commit or stash changes before proceeding") unless git.clean?
+
+        org, repo = resolve_org_repo(git)
+
+        names = remote_names
+        urls = forge_urls(org, repo)
+
+        # Ensure remotes exist and have desired names/urls
+        ensure_remote_alignment!(git, names[:origin], urls[@opts[:origin].to_sym])
+        ensure_remote_alignment!(git, names[:github], urls[:github]) if names[:github] && names[:github] != names[:origin]
+        ensure_remote_alignment!(git, names[:gitlab], urls[:gitlab]) if names[:gitlab]
+        ensure_remote_alignment!(git, names[:codeberg], urls[:codeberg]) if names[:codeberg]
+
+        # Configure "all" remote: fetch only from origin, push to all three
+        configure_all_remote!(git, names, urls)
+
+        say("Remotes normalized. Origin: #{names[:origin]} (#{urls[@opts[:origin].to_sym]})")
+        show_remotes!(git)
+        fetch_results = attempt_fetches!(git, names)
+        update_readme_federation_status!(org, repo, fetch_results)
+        0
+      end
+
+      private
+
+      # Determine default branch to compare against. Prefer 'main', fallback to 'master'.
+      # Uses origin to check existence.
+      def detect_default_branch!(git)
+        _out, ok = git.capture(["rev-parse", "--verify", "origin/main"])
+        return "main" if ok
+        _out2, ok2 = git.capture(["rev-parse", "--verify", "origin/master"])
+        return "master" if ok2
+        # Default to main if neither verifies
+        "main"
+      end
+
+      # Show ahead/behind status for each configured forge remote relative to origin/<branch>
+      def show_status!(git, names, branch)
+        base = "origin/#{branch}"
+        say("\nRemote status relative to #{base}:")
+        existing = Array(git.remotes)
+        {
+          github: names[:github],
+          gitlab: names[:gitlab],
+          codeberg: names[:codeberg],
+        }.each do |forge, remote|
+          next unless remote
+          next if remote == names[:origin]
+          next unless existing.include?(remote)
+          ref = "#{remote}/#{branch}"
+          out, ok = git.capture(["rev-list", "--left-right", "--count", "#{base}...#{ref}"])
+          if ok && !out.to_s.strip.empty?
+            parts = out.strip.split(/\s+/)
+            left = parts[0].to_i
+            right = parts[1].to_i
+            # left = commits only in base (origin) => remote is behind by left
+            # right = commits only in remote => remote is ahead by right
+            if left.zero? && right.zero?
+              say("  - #{forge} (#{remote}): in sync")
+            else
+              ahead_emoji = right.zero? ? "✅️" : "🔴"
+              say("  - #{forge} (#{remote}): #{ahead_emoji} ahead by #{right}, behind by #{left}")
+            end
+          else
+            say("  - #{forge} (#{remote}): no data (branch missing?)")
+          end
+        end
+      end
+
+      # Show local working copy status relative to origin/<branch>
+      def show_local_vs_origin!(git, branch)
+        base = "origin/#{branch}"
+        # Compare local HEAD to origin/<branch>
+        out, ok = git.capture(["rev-list", "--left-right", "--count", "HEAD...#{base}"])
+        say("\nLocal status relative to #{base}:")
+        if ok && !out.to_s.strip.empty?
+          parts = out.strip.split(/\s+/)
+          left = parts[0].to_i
+          right = parts[1].to_i
+          # left = commits only in HEAD => local ahead by left
+          # right = commits only in origin => local behind by right
+          if left.zero? && right.zero?
+            say("  - local (HEAD): in sync")
+          else
+            ahead_emoji = left.zero? ? "✅️" : "🔴"
+            say("  - local (HEAD): #{ahead_emoji} ahead by #{left}, behind by #{right}")
+          end
+        else
+          say("  - local (HEAD): no data (branch missing?)")
+        end
+      end
+
+      def parse!
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: kettle-dvcs [options] [ORG] [REPO]"
+          o.on("--origin NAME", %w[github gitlab codeberg], "Choose origin forge (default: github)") { |v| @opts[:origin] = v }
+          o.on("--protocol NAME", %w[ssh https], "Protocol (default: ssh)") { |v| @opts[:protocol] = v }
+          o.on("--github-name NAME", "Remote name for GitHub when not origin (default: gh)") { |v| @opts[:gh_name] = v }
+          o.on("--gitlab-name NAME", "Remote name for GitLab (default: gl)") { |v| @opts[:gl_name] = v }
+          o.on("--codeberg-name NAME", "Remote name for Codeberg (default: cb)") { |v| @opts[:cb_name] = v }
+          o.on("--status", "Fetch remotes and show ahead/behind relative to origin/main") { @opts[:status] = true }
+          o.on("--force", "Accept defaults; non-interactive") { @opts[:force] = true }
+          o.on("-h", "--help", "Show help") {
+            puts o
+            Kettle::Dev::ExitAdapter.exit(0)
+          }
+        end
+        rest = parser.parse(@argv)
+        @opts[:org] = rest[0] if rest[0]
+        @opts[:repo] = rest[1] if rest[1]
+
+        unless %w[github gitlab codeberg].include?(@opts[:origin])
+          abort!("Invalid origin: #{@opts[:origin]}")
+        end
+      end
+
+      def ensure_git_adapter!
+        unless defined?(Kettle::Dev::GitAdapter)
+          abort!("Kettle::Dev::GitAdapter is required and not available")
+        end
+        Kettle::Dev::GitAdapter.new
+      end
+
+      def remote_names
+        {
+          origin: "origin",
+          github: (@opts[:origin] == "github") ? "origin" : @opts[:gh_name],
+          gitlab: (@opts[:origin] == "gitlab") ? "origin" : @opts[:gl_name],
+          codeberg: (@opts[:origin] == "codeberg") ? "origin" : @opts[:cb_name],
+          all: "all",
+        }
+      end
+
+      def forge_urls(org, repo)
+        case @opts[:protocol]
+        when "ssh"
+          {
+            github: "git@github.com:#{org}/#{repo}.git",
+            gitlab: "git@gitlab.com:#{org}/#{repo}.git",
+            codeberg: "git@codeberg.org:#{org}/#{repo}.git",
+          }
+        else # https
+          {
+            github: "https://github.com/#{org}/#{repo}.git",
+            gitlab: "https://gitlab.com/#{org}/#{repo}.git",
+            codeberg: "https://codeberg.org/#{org}/#{repo}.git",
+          }
+        end
+      end
+
+      def resolve_org_repo(git)
+        org = @opts[:org]
+        repo = @opts[:repo]
+        if org && repo
+          return [org, repo]
+        end
+        # Try to infer from any existing remote url
+        urls = git.remotes_with_urls
+        sample = urls["origin"] || urls.values.first
+        if sample && sample =~ %r{[:/](?<org>[^/]+)/(?<repo>[^/]+?)(?:\.git)?$}
+          org ||= Regexp.last_match(:org)
+          repo ||= Regexp.last_match(:repo)
+        end
+        if !org || !repo
+          if @opts[:force]
+            abort!("ORG and REPO could not be inferred; supply them or ensure an existing remote URL")
+          else
+            org = prompt("Organization name", default: org)
+            repo = prompt("Repository name", default: repo)
+          end
+        end
+        [org, repo]
+      end
+
+      def prompt(label, default: nil)
+        return default if @opts[:force]
+        print("#{label}#{default ? " [#{default}]" : ""}: ")
+        ans = $stdin.gets&.strip
+        ans = nil if ans == ""
+        ans || default || abort!("#{label} is required")
+      end
+
+      def ensure_remote_alignment!(git, name, url)
+        # Validate URL presence to avoid passing nil to Open3
+        abort!("Internal error: URL for remote '#{name}' is empty") if url.nil? || url.to_s.strip.empty?
+        # We need remote management capabilities via capture to avoid adding adapter methods right now.
+        # Fails if GitAdapter is not present as required.
+        existing = git.remotes
+        if existing.include?(name)
+          current = git.remote_url(name)
+          if current != url
+            sh_git!(git, ["remote", "set-url", name, url])
+          end
+        else
+          # Check if any remote already points to this URL under a different name; rename it
+          urls = git.remotes_with_urls
+          if (pair = urls.find { |_n, u| u == url })
+            old = pair[0]
+            sh_git!(git, ["remote", "rename", old, name]) unless old == name
+          else
+            sh_git!(git, ["remote", "add", name, url])
+          end
+        end
+      end
+
+      def configure_all_remote!(git, names, urls)
+        all = names[:all]
+        # Remove existing 'all' to recreate cleanly
+        if git.remotes.include?(all)
+          sh_git!(git, ["remote", "remove", all])
+        end
+        # Create with origin fetch URL; we will add multiple pushurls
+        origin_url = urls[@opts[:origin].to_sym]
+        sh_git!(git, ["remote", "add", all, origin_url])
+        # Ensure fetch only from origin (set fetch refspec to match origin's default)
+        # We'll reset fetch to +refs/heads/*:refs/remotes/all/* from origin remote
+        # Simpler: disable fetch by clearing fetch then add one matching origin
+        sh_git!(git, ["config", "--unset-all", "remote.#{all}.fetch"]) # ignore failure
+        # Emulate origin default fetch
+        sh_git!(git, ["config", "--add", "remote.#{all}.fetch", "+refs/heads/*:refs/remotes/#{all}/*"])
+        # Configure push to all forges
+        %i[github gitlab codeberg].each do |forge|
+          sh_git!(git, ["config", "--add", "remote.#{all}.pushurl", forge_urls_entry(forge, urls)])
+        end
+      end
+
+      def forge_urls_entry(forge, urls)
+        urls[forge]
+      end
+
+      def sh_git!(git, args)
+        # Ensure no nil sneaks into the argv to Open3 (TypeError avoidance)
+        if args.any? { |a| a.nil? || (a.respond_to?(:strip) && a.strip.empty?) }
+          abort!("Internal error: Attempted to run 'git #{args.inspect}' with an empty argument")
+        end
+        out, ok = git.capture(args)
+        unless ok
+          abort!("git #{args.join(" ")} failed: #{out}")
+        end
+        out
+      end
+
+      def show_remotes!(git)
+        out, ok = git.capture(["remote", "-v"])
+        if ok && !out.to_s.strip.empty?
+          say("\nCurrent remotes (git remote -v):")
+          puts out
+        else
+          # Fallback: print the fetch URLs mapping
+          say("\nCurrent remotes (name => fetch URL):")
+          git.remotes_with_urls.each do |name, url|
+            puts "  #{name}\t#{url} (fetch)"
+          end
+        end
+      end
+
+      # Try fetching from each configured forge remote. Returns a hash of forge=>boolean
+      def attempt_fetches!(git, names)
+        results = {}
+        {
+          github: names[:github],
+          gitlab: names[:gitlab],
+          codeberg: names[:codeberg],
+        }.each do |forge, remote_name|
+          next unless remote_name
+          ok = git.fetch(remote_name)
+          results[forge] = !!ok
+          say("Fetched from #{forge} (remote: #{remote_name}) => #{ok ? "OK" : "FAILED"}")
+        end
+        results
+      end
+
+      # Update README federation disclosure based on fetch results
+      def update_readme_federation_status!(org, repo, results)
+        readme_path = File.join(Dir.pwd, "README.md")
+        return unless File.exist?(readme_path)
+        content = File.read(readme_path)
+        # Determine if all succeeded
+        forges = [:github, :gitlab, :codeberg]
+        all_ok = forges.all? { |f| results[f] }
+        new_content = content.dup
+        summary_line_with_cs = /<summary>Find this repo on other forges \(Coming soon!\)<\/summary>/
+        summary_line_no_cs = "<summary>Find this repo on other forges</summary>"
+        if all_ok
+          new_content.gsub!(summary_line_with_cs, summary_line_no_cs)
+        else
+          # Ensure the line contains (Coming soon!) so readers know it's partial
+          unless content =~ summary_line_with_cs
+            new_content.gsub!("<summary>Find this repo on other forges</summary>", "<summary>Find this repo on other forges (Coming soon!)</summary>")
+          end
+        end
+        if new_content != content
+          File.write(readme_path, new_content)
+          say("Updated README federation summary to reflect current forge status")
+        end
+        # Print import links for any failed forge
+        unless all_ok
+          say("\nSome forges are not yet available. Use these import links to create mirrors:")
+          [:github, :gitlab, :codeberg].each do |forge|
+            next if results[forge]
+            say("  - #{forge.capitalize} import: #{FORGE_MIGRATION_TOOLS[forge]}")
+          end
+        end
+      rescue StandardError => e
+        warn("Failed to update README federation status: #{e.message}")
+      end
+
+      def say(msg)
+        puts msg
+      end
+
+      def abort!(msg)
+        warn(msg)
+        Kettle::Dev::ExitAdapter.exit(1)
+      end
+    end
+  end
+end

data/lib/kettle/dev/version.rb

@@ -6,7 +6,7 @@ module Kettle
     module Version
       # The gem version.
       # @return [String]
-      VERSION = "1.1.1"
+      VERSION = "1.1.3"
 
       module_function
 

data/lib/kettle/dev.rb

@@ -15,6 +15,7 @@ module Kettle
     autoload :CIHelpers, "kettle/dev/ci_helpers"
     autoload :CIMonitor, "kettle/dev/ci_monitor"
     autoload :CommitMsg, "kettle/dev/commit_msg"
+    autoload :DvcsCLI, "kettle/dev/dvcs_cli"
     autoload :ExitAdapter, "kettle/dev/exit_adapter"
     autoload :GemSpecReader, "kettle/dev/gem_spec_reader"
     autoload :GitAdapter, "kettle/dev/git_adapter"
@@ -37,10 +38,9 @@ module Kettle
     class Error < StandardError; end
 
     # Whether debug logging is enabled for kettle-dev internals.
+    # KETTLE_DEV_DEBUG overrides DEBUG.
     # @return [Boolean]
-    DEBUGGING = ENV.fetch("DEBUG", "false").casecmp("true").zero?
-    # Backwards-compat for kettle-dev specific debug variable
-    DEBUGGING ||= ENV.fetch("KETTLE_DEV_DEBUG", "false").casecmp("true").zero?
+    DEBUGGING = ENV.fetch("KETTLE_DEV_DEBUG", ENV.fetch("DEBUG", "false")).casecmp("true").zero?
     # Whether we are running on CI.
     # @return [Boolean]
     IS_CI = ENV.fetch("CI", "false").casecmp("true") == 0

data/sig/kettle/dev/dvcscli.rbs

@@ -0,0 +1,8 @@
+module Kettle
+  module Dev
+    class DvcsCLI
+      def initialize: (Array[String] argv) -> void
+      def run!: () -> Integer
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.1.3
 platform: ruby
 authors:
 - Peter H. Boling
@@ -198,6 +198,7 @@ executables:
 - kettle-changelog
 - kettle-commit-msg
 - kettle-dev-setup
+- kettle-dvcs
 - kettle-readme-backers
 - kettle-release
 extensions: []
@@ -277,6 +278,7 @@ files:
 - exe/kettle-changelog
 - exe/kettle-commit-msg
 - exe/kettle-dev-setup
+- exe/kettle-dvcs
 - exe/kettle-readme-backers
 - exe/kettle-release
 - gemfiles/modular/coverage.gemfile
@@ -293,6 +295,7 @@ files:
 - lib/kettle/dev/ci_helpers.rb
 - lib/kettle/dev/ci_monitor.rb
 - lib/kettle/dev/commit_msg.rb
+- lib/kettle/dev/dvcs_cli.rb
 - lib/kettle/dev/exit_adapter.rb
 - lib/kettle/dev/gem_spec_reader.rb
 - lib/kettle/dev/git_adapter.rb
@@ -324,6 +327,7 @@ files:
 - sig/kettle/dev/ci_helpers.rbs
 - sig/kettle/dev/ci_monitor.rbs
 - sig/kettle/dev/commit_msg.rbs
+- sig/kettle/dev/dvcscli.rbs
 - sig/kettle/dev/exit_adapter.rbs
 - sig/kettle/dev/gem_spec_reader.rbs
 - sig/kettle/dev/git_adapter.rbs
@@ -343,10 +347,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://kettle-dev.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/kettle-dev/tree/v1.1.1
-  changelog_uri: https://github.com/kettle-rb/kettle-dev/blob/v1.1.1/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/kettle-dev/tree/v1.1.3
+  changelog_uri: https://github.com/kettle-rb/kettle-dev/blob/v1.1.3/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.1.1
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.1.3
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/kettle-dev/wiki
   news_uri: https://www.railsbling.com/tags/kettle-dev