kettle-dev 1.0.27 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5262ffaac8801d10dc7399ed6f111a5878e135d79cc48a155b386c92c86eab24
-  data.tar.gz: 6a7415eb0b8e4da2d4a4a63eb10515209a2db42f4f82d1e822edd7754861a077
+  metadata.gz: 0a5adcf9f057ec385ca20f8441e9cf7cf45a3c28916146dc828342cc280a7275
+  data.tar.gz: 9c85ede6e630a006c83d26db02f2938be131fb227b3aa76e1e8f531f616edf3a
 SHA512:
-  metadata.gz: dbaa7553ea88a2a702975b5650abb04f7a9f16892b8ea4d8b54353fa8036b15fc88c81ae560819ce8d1f45c2744b69d832e3a19a20ebbb3859044aa8f8d8b221
-  data.tar.gz: f4a3e941cf43f6f4221f1ef65601114ccf864588aca25e20ef9b1691b101c840eb43ee86dd383ab360e0b4e5da58aa863d039e1e0861e49b48562dea0cd6770f
+  metadata.gz: ae3e344c567670c9817d9724bddbe08f926564e906843ae02bb95110bb2fce3ae3769511a5106e73bcb0abf93c2a1a64cf876c5d82bd6052adaa6046cd5eeecb
+  data.tar.gz: 9ccad75834eb783f912660a214416e3fd53d8229955a69026c013fbcb4ddfd6b43bc211ace28e7a0e7dec08f41a2c3463e862515f7fae0e9059111c49c478d74

data/.simplecov

@@ -8,4 +8,9 @@ SimpleCov.start do
   track_files "lib/**/*.rb"
   track_files "lib/**/*.rake"
   track_files "exe/*.rb"
+
+  # Version *is* tested (see spec/kettle/dev/version_spec.rb).
+  # Due to early loading, the Version class can't be tracked by SimpleCov.
+  # So we disable coverage here.
+  add_filter "lib/kettle/dev/version.rb"
 end

data/.simplecov.example

@@ -0,0 +1,11 @@
+require "kettle/soup/cover/config"
+
+# Minimum coverage thresholds are set by kettle-soup-cover.
+# It is controlled by ENV variables, which are set in .envrc and loaded via `direnv allow`
+# If the values for minimum coverage need to change, they should be changed both there,
+#   and in 2 places in .github/workflows/coverage.yml.
+SimpleCov.start do
+  track_files "lib/**/*.rb"
+  track_files "lib/**/*.rake"
+  track_files "exe/*.rb"
+end

data/Appraisals

@@ -26,6 +26,8 @@ appraise "unlocked_deps" do
   eval_gemfile "modular/style.gemfile"
   eval_gemfile "modular/optional.gemfile"
   eval_gemfile "modular/recording/r3/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 # Used for head (nightly) releases of ruby, truffleruby, and jruby.
@@ -38,6 +40,8 @@ appraise "head" do
   gem "stringio", ">= 3.0"
   gem "benchmark", "~> 0.4", ">= 0.4.1"
   eval_gemfile "modular/recording/r3/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 # Used for current releases of ruby, truffleruby, and jruby.
@@ -47,6 +51,8 @@ appraise "current" do
   gem "mutex_m", ">= 0.2"
   gem "stringio", ">= 3.0"
   eval_gemfile "modular/recording/r3/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 appraise "ruby-2-3" do
@@ -55,16 +61,22 @@ appraise "ruby-2-3" do
   # /opt/hostedtoolcache/Ruby/2.3.8/x64/lib/ruby/gems/2.3.0/gems/erb-2.2.2/lib/erb.rb:670:in `prepare_trim_mode': undefined method `match?' for "-":String (NoMethodError)
   # spec.add_development_dependency("erb", ">= 2.2")                                  # ruby >= 2.3.0, not SemVer, old rubies get dropped in a patch.
   eval_gemfile "modular/recording/r2.3/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 appraise "ruby-2-4" do
   gem "erb"
   eval_gemfile "modular/recording/r2.4/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 appraise "ruby-2-5" do
   gem "erb"
   eval_gemfile "modular/recording/r2.5/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 appraise "ruby-2-6" do
@@ -72,6 +84,8 @@ appraise "ruby-2-6" do
   gem "mutex_m", "~> 0.2"
   gem "stringio", "~> 3.0"
   eval_gemfile "modular/recording/r2.5/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 appraise "ruby-2-7" do
@@ -79,6 +93,8 @@ appraise "ruby-2-7" do
   gem "mutex_m", "~> 0.2"
   gem "stringio", "~> 3.0"
   eval_gemfile "modular/recording/r2.5/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 appraise "ruby-3-0" do
@@ -86,6 +102,8 @@ appraise "ruby-3-0" do
   gem "mutex_m", "~> 0.2"
   gem "stringio", "~> 3.0"
   eval_gemfile "modular/recording/r3/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 appraise "ruby-3-1" do
@@ -95,6 +113,8 @@ appraise "ruby-3-1" do
   gem "mutex_m", "~> 0.2"
   gem "stringio", "~> 3.0"
   eval_gemfile "modular/recording/r3/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 appraise "ruby-3-2" do
@@ -104,6 +124,8 @@ appraise "ruby-3-2" do
   gem "mutex_m", "~> 0.2"
   gem "stringio", "~> 3.0"
   eval_gemfile "modular/recording/r3/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 appraise "ruby-3-3" do
@@ -111,6 +133,8 @@ appraise "ruby-3-3" do
   gem "erb"
   gem "mutex_m", "~> 0.2"
   gem "stringio", "~> 3.0"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 # Only run security audit on the latest version of Ruby
@@ -118,6 +142,8 @@ appraise "audit" do
   gem "erb"
   gem "mutex_m", "~> 0.2"
   gem "stringio", "~> 3.0"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 # Only run coverage on the latest version of Ruby
@@ -128,6 +154,8 @@ appraise "coverage" do
   eval_gemfile "modular/coverage.gemfile"
   eval_gemfile "modular/optional.gemfile"
   eval_gemfile "modular/recording/r3/recording.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end
 
 # Only run linter on the latest version of Ruby (but, in support of oldest supported Ruby version)
@@ -136,4 +164,6 @@ appraise "style" do
   gem "mutex_m", "~> 0.2"
   gem "stringio", "~> 3.0"
   eval_gemfile "modular/style.gemfile"
+  # Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+  #  eval_gemfile "modular/injected.gemfile"
 end

data/CHANGELOG.md

@@ -24,6 +24,31 @@ Please file a bug if you notice a violation of semantic versioning.
 ### Fixed
 ### Security
 
+## [1.1.1] - 2025-09-02
+- TAG: [v1.1.1][1.1.1t]
+- COVERAGE: 97.04% -- 2655/2736 lines in 21 files
+- BRANCH COVERAGE: 82.21% -- 1109/1349 branches in 21 files
+- 76.81% documented
+### Added
+- .simplecov.example - keeps it generic
+- improved documentation on automatic release script
+- .gitlab-ci.yml documentation
+### Fixed
+- reduce extra leading whitespace in info table column 2
+
+## [1.1.0] - 2025-09-02
+- TAG: [v1.1.0][1.1.0t]
+- COVERAGE: 97.03% -- 2649/2730 lines in 21 files
+- BRANCH COVERAGE: 82.16% -- 1105/1345 branches in 21 files
+- 76.81% documented
+### Added
+- exe/kettle-dev-setup - bootstrap templating in any RubyGem
+### Removed
+- all runtime deps
+  - dependencies haven't really changed; will be injected into the gemspec of the including gem
+  - **almost** a breaking change; but this gem re-templates other gems
+  - so non-breaking via re-templating.
+
 ## [1.0.27] - 2025-09-01
 - TAG: [v1.0.27][1.0.27t]
 - COVERAGE: 97.77% -- 2629/2689 lines in 22 files
@@ -403,7 +428,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.0.27...HEAD
+[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.1...HEAD
+[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
+[1.1.0t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.0
 [1.0.27]: https://github.com/kettle-rb/kettle-dev/compare/v1.0.26...v1.0.27
 [1.0.27t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.0.27
 [1.0.26]: https://github.com/kettle-rb/kettle-dev/compare/v1.0.25...v1.0.26

data/CONTRIBUTING.md

@@ -146,7 +146,9 @@ NOTE: To build without signing the gem set `SKIP_GEM_SIGNING` to any value in th
 
 #### Automated process
 
-Run `bundle exec kettle-release`.
+1. Update version.rb to contian the correct version-to-be-released.
+2. Run `bundle exec kettle-changelog`.
+3. Run `bundle exec kettle-release`.
 
 #### Manual process
 

data/Gemfile

@@ -36,3 +36,6 @@ eval_gemfile "gemfiles/modular/documentation.gemfile"
 
 # Optional
 eval_gemfile "gemfiles/modular/optional.gemfile"
+
+# Dependencies injected by the kettle-dev-setup script & kettle:dev:install rake task
+# eval_gemfile "gemfiles/modular/injected.gemfile"

data/README.md

@@ -21,25 +21,35 @@ OTOH, if `ci_badges.map(&:color).all? { it == "green"}` 👇️ send money so I
 
 ## 🌻 Synopsis
 
-This gem integrates tightly with [kettle-test](https://github.com/kettle-rb/kettle-test).
+Run the one-time project bootstrapper:
 
-```ruby
-require "kettle/test/rspec"
+```console
+kettle-dev-setup
 ```
 
-Then, add to your `Rakefile`:
+This gem integrates tightly with [kettle-test](https://github.com/kettle-rb/kettle-test).
+
+Add this to your `spec/spec_helper.rb`:
 
 ```ruby
-require "kettle/dev"
+require "kettle/test/rspec"
 ```
 
-Then run:
+Now you have many powerful development and testing tools at your disposal, all fully [documented](#-configuration) and tested.
+
+If you need to top-up an old setup to get the latest goodies, just re-template:
 
 ```console
 bundle exec rake kettle:dev:install
 ```
 
-Now you have many powerful development and testing tools at your disposal, all fully [documented](#-configuration) and tested.
+Making sure to review the changes, and retain overwritten bits that matter.
+
+Later, when ready to release:
+```console
+bin/kettle-changelog
+bin/kettle-release
+```
 
 ## 💡 Info you can shake a stick at
 
@@ -171,7 +181,15 @@ Add to your `Rakefile`:
 require "kettle/dev"
 ```
 
-Then run:
+Then run the one-time project bootstrapper:
+
+```console
+kettle-dev-setup
+```
+
+After bootstrapping you may want to update the template.
+
+Invoke the rake task directly:
 
 ```console
 bundle exec rake kettle:dev:install
@@ -732,7 +750,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.689-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.736-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.689-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.736-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.0.27 - 2025-09-01
+# kettle-dev Rakefile v1.1.1 - 2025-09-02
 # Ruby 2.3 (Safe Navigation) or higher required
 #
 # MIT License (see License.txt)

data/exe/kettle-dev-setup

@@ -0,0 +1,302 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# vim: set syntax=ruby
+
+# kettle-dev-setup: initialize a target gem repo to use kettle-dev tooling.
+# This script is installed into PATH when the kettle-dev gem is installed.
+# It is designed to be run from inside the target gem's repository working
+# directory. It will not assume kettle-dev is already a dependency.
+
+require "fileutils"
+require "shellwords"
+require "open3"
+require "optparse"
+require "rubygems"
+
+# Ensure output is flushed promptly even if we exit early
+$stdout.sync = true
+$stderr.sync = true
+
+script_basename = File.basename(__FILE__)
+running_as_script = File.basename($PROGRAM_NAME)
+
+begin
+  require "kettle/dev"
+  puts "== #{script_basename} v#{Kettle::Dev::Version::VERSION} begin =="
+rescue StandardError => e
+  # Requiring kettle/dev should generally work since this script ships with the gem.
+  # But if autoloads try to pull optional deps, we should still proceed as most
+  # of this script does not rely on those parts.
+  warn("[kettle-dev-setup] Warning: could not fully load kettle/dev (#{e.class}: #{e.message}). Proceeding with limited features.")
+end
+
+module Kettle
+  module Dev
+    class SetupCLI
+      def initialize(argv)
+        debug("initialize(argv=#{argv.inspect})")
+        @argv = argv
+        @passthrough = []
+        @options = {}
+        parse!
+      end
+
+      def run!
+        debug("run!")
+        say("Starting kettle-dev setup…")
+        prechecks!
+        ensure_dev_deps!
+        ensure_bin_setup!
+        ensure_rakefile!
+        run_bin_setup!
+        run_bundle_binstubs!
+        commit_bootstrap_changes!
+        run_kettle_install!
+        say("kettle-dev setup complete.")
+      end
+
+      private
+
+      def debug(msg)
+        return unless ENV.fetch("DEBUG", "false").casecmp("true").zero?
+        $stderr.puts("[kettle-dev-setup] DEBUG: #{msg}")
+      end
+
+      def parse!
+        debug("parse! argv_before=#{@argv.inspect}")
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: kettle-dev-setup [options]"
+          # Map CLI flags to environment-style assignments for Rake (key=value)
+          opts.on("--allowed=VAL", "Pass through to kettle:dev:install") { |v| @passthrough << "allowed=#{v}" }
+          opts.on("--force", "Pass through to kettle:dev:install") { @passthrough << "force=true" }
+          opts.on("--hook_templates=VAL", "Pass through to kettle:dev:install") { |v| @passthrough << "hook_templates=#{v}" }
+          opts.on("-h", "--help", "Show help") do
+            puts opts
+            exit(0)
+          end
+        end
+        begin
+          parser.parse!(@argv)
+        rescue OptionParser::ParseError => e
+          warn("[kettle-dev-setup] #{e.class}: #{e.message}")
+          puts parser
+          exit(2)
+        end
+        # Any remaining args pass through as-is
+        @passthrough.concat(@argv)
+        debug("parse! argv_after=#{@argv.inspect} passthrough=#{@passthrough.inspect}")
+      end
+
+      def say(msg)
+        puts "[kettle-dev-setup] #{msg}"
+      end
+
+      def abort!(msg)
+        debug("abort!(msg=#{msg.inspect})")
+        raise SystemExit, "[kettle-dev-setup] ERROR: #{msg}"
+      end
+
+      def sh!(cmd, env: {})
+        debug("sh!(cmd=#{cmd.inspect}, env_keys=#{env.keys.inspect})")
+        say("exec: #{cmd}")
+        stdout_str, stderr_str, status = Open3.capture3(env, cmd)
+        $stdout.print(stdout_str) unless stdout_str.empty?
+        $stderr.print(stderr_str) unless stderr_str.empty?
+        abort!("Command failed: #{cmd}") unless status.success?
+      end
+
+      # 1. Prechecks
+      def prechecks!
+        debug("prechecks!")
+        abort!("Not inside a git repository (missing .git).") unless Dir.exist?(".git")
+
+        # 1a. git clean
+        begin
+          # Use GitAdapter if available; otherwise shell out
+          if defined?(Kettle::Dev::GitAdapter)
+            ga = Kettle::Dev::GitAdapter.new
+            dirty = !ga.clean?
+          else
+            stdout, _stderr, _status = Open3.capture3("git status --porcelain")
+            dirty = !stdout.strip.empty?
+          end
+          abort!("Git working tree is not clean. Please commit/stash changes and try again.") if dirty
+        rescue StandardError
+          # Fallback if anything goes wrong: be conservative and require clean tree via shell
+          stdout, _stderr, _status = Open3.capture3("git status --porcelain")
+          abort!("Git working tree is not clean. Please commit/stash changes and try again.") unless stdout.strip.empty?
+        end
+
+        # 1b. target is a gem (has *.gemspec)
+        gemspecs = Dir["*.gemspec"]
+        abort!("No gemspec found in current directory.") if gemspecs.empty?
+        @gemspec_path = gemspecs.first
+
+        # 1c. target uses bundler (Gemfile)
+        abort!("No Gemfile found; bundler is required.") unless File.exist?("Gemfile")
+      end
+
+      # 3. Sync dev dependencies from this gem's example gemspec into target gemspec
+      def ensure_dev_deps!
+        debug("ensure_dev_deps!")
+        source_example = installed_path("kettle-dev.gemspec.example")
+        abort!("Internal error: kettle-dev.gemspec.example not found within the installed gem.") unless source_example && File.exist?(source_example)
+
+        example = File.read(source_example)
+        example = example.gsub("{KETTLE|DEV|GEM}", "kettle-dev")
+
+        wanted_lines = example.each_line.map(&:rstrip).select do |line|
+          line =~ /add_development_dependency\s*\(/
+        end
+
+        return if wanted_lines.empty?
+
+        target = File.read(@gemspec_path)
+
+        # Build a map from gem name to the desired line
+        wanted = {}
+        wanted_lines.each do |line|
+          if (m = line.match(/add_development_dependency\s*\(\s*["']([^"']+)["']/))
+            wanted[m[1]] = line
+          end
+        end
+
+        modified = target.dup
+        wanted.each do |gem_name, desired_line|
+          # Replace existing add_development_dependency for this gem, else append near the end
+          if modified.match?(/add_development_dependency\s*\(\s*["']#{Regexp.escape(gem_name)}["']/)
+            modified = modified.gsub(/^[^\n]*add_development_dependency\s*\(\s*["']#{Regexp.escape(gem_name)}["'][^\n]*\)$/) do |_|
+              desired_line
+            end
+          elsif (idx = modified.rindex(/\nend\s*\z/))
+            # Insert before the last end, if present, otherwise append
+            before = modified[0...idx]
+            after = modified[idx..-1]
+            insertion = "\n  #{desired_line.strip}\n"
+            modified = before + insertion + after
+          else
+            modified << "\n#{desired_line}\n"
+          end
+        end
+
+        if modified != target
+          File.write(@gemspec_path, modified)
+          say("Updated development dependencies in #{@gemspec_path}.")
+        else
+          say("Development dependencies already up to date.")
+        end
+      end
+
+      # 4. Ensure bin/setup present (copy from gem if missing)
+      def ensure_bin_setup!
+        debug("ensure_bin_setup!")
+        target = File.join("bin", "setup")
+        return say("bin/setup present.") if File.exist?(target)
+
+        source = installed_path(File.join("bin", "setup"))
+        abort!("Internal error: source bin/setup not found within installed gem.") unless source && File.exist?(source)
+        FileUtils.mkdir_p("bin")
+        FileUtils.cp(source, target)
+        FileUtils.chmod("+x", target)
+        say("Copied bin/setup.")
+      end
+
+      # 5. Ensure Rakefile matches example (replace or create)
+      def ensure_rakefile!
+        debug("ensure_rakefile!")
+        source = installed_path("Rakefile.example")
+        abort!("Internal error: Rakefile.example not found within installed gem.") unless source && File.exist?(source)
+
+        content = File.read(source)
+        if File.exist?("Rakefile")
+          say("Replacing existing Rakefile with kettle-dev Rakefile.example.")
+        else
+          say("Creating Rakefile from kettle-dev Rakefile.example.")
+        end
+        File.write("Rakefile", content)
+      end
+
+      # 6. Run bin/setup
+      def run_bin_setup!
+        debug("run_bin_setup!")
+        sh!(Shellwords.join([File.join("bin", "setup")]))
+      end
+
+      # 7. Run bundle binstubs --all
+      def run_bundle_binstubs!
+        debug("run_bundle_binstubs!")
+        sh!("bundle exec bundle binstubs --all")
+      end
+
+      # 8. Stage and commit any changes made by the setup before install
+      def commit_bootstrap_changes!
+        debug("commit_bootstrap_changes!")
+        # Only operate if we are inside a git repo (prechecked earlier), and if dirty
+        dirty = begin
+          if defined?(Kettle::Dev::GitAdapter)
+            !Kettle::Dev::GitAdapter.new.clean?
+          else
+            out, _st = Open3.capture2("git", "status", "--porcelain")
+            !out.strip.empty?
+          end
+        rescue StandardError
+          out, _st = Open3.capture2("git", "status", "--porcelain")
+          !out.strip.empty?
+        end
+        unless dirty
+          say("No changes to commit from template bootstrap.")
+          return
+        end
+        # Stage all changes
+        sh!(Shellwords.join(["git", "add", "-A"]))
+        # Compose commit message exactly as required
+        script_name = File.basename(__FILE__)
+        msg = "🎨 Template bootstrap by #{script_name} v#{Kettle::Dev::Version::VERSION}"
+        # Commit; allow empty to be false (we already detected dirty)
+        sh!(Shellwords.join(["git", "commit", "-m", msg]))
+        say("Committed template bootstrap changes.")
+      end
+
+      # 9. Run rake kettle:dev:install with passthrough args
+      def run_kettle_install!
+        debug("run_kettle_install! passthrough=#{@passthrough.inspect}")
+        cmd = ["bin/rake", "kettle:dev:install"] + @passthrough
+        sh!(Shellwords.join(cmd))
+      end
+
+      # Locate files shipped with this gem installation. Handles execution under a checkout as well.
+      def installed_path(rel)
+        debug("installed_path(rel=#{rel.inspect})")
+        # Prefer real gem installation location
+        if defined?(Gem) && (spec = Gem.loaded_specs["kettle-dev"])
+          path = File.join(spec.full_gem_path, rel)
+          return path if File.exist?(path)
+        end
+        # Fallback: relative to this file (useful when running from repo)
+        here = File.expand_path(File.join(__dir__, "..")) # move from exe/ to project root
+        path = File.join(here, rel)
+        return path if File.exist?(path)
+        nil
+      end
+    end
+  end
+end
+
+if running_as_script == script_basename
+  begin
+    puts "== Kettle::Dev::SetupCLI.new => run! =="
+    Kettle::Dev::SetupCLI.new(ARGV).run!
+  rescue SystemExit => e
+    warn(e.message)
+    exit(e.status || 1)
+  rescue Exception => e
+    warn("[kettle-dev-setup] FATAL: #{e.class}: #{e.message}")
+    if ENV.fetch("DEBUG", "false").casecmp("true").zero?
+      warn(e.backtrace.join("\n"))
+    end
+    exit(1)
+  end
+else
+  puts "== #{script_basename} v#{Kettle::Dev::Version::VERSION} fin (#{running_as_script}) == (#{script_basename}) =="
+end