kettle-family 1.2.61 → 1.2.62

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbffd07749dbf6833f322d540408a7d0390c3f4dea85b46c779d63efd5908a09
-  data.tar.gz: 336f72600d1916d3ae0614f34e685f68dd908613dbe74440e99a65ade5125897
+  metadata.gz: 04321f7c14998edb27e9dd4f88d54e999bed1bdf8397678f3b3fa6d883b4c17c
+  data.tar.gz: 13af696225888e53942d50400bf35f68244591a24033d7e1398339f7e0e878a6
 SHA512:
-  metadata.gz: 6f63a9f141f1d8cd600fdee06fc5a19fde59a9bdf539f3c407145bb1a5e31fb2b22892899e34bded713dac4a706a6253f06ef6bd101844b276ff615ddb6cb23d
-  data.tar.gz: c9960c504314fb1a01685b6712051f4ab54e9263aebc9dbe7c6f072f3779d054aa972ef7c0a06962671765af4e7de5274f235895528cb67a31e1fa38ed1d1080
+  metadata.gz: bcf9301368288f9914849fb8cad0f5963b6d9ef984be6cca2b0e169fc2e66655ba6ffc70c5970f88a2e800fbcbcc5f46df812e150cf0b0e4a86454f013489353
+  data.tar.gz: 76cd17c2e40a09672ec728c103c3e6ee8273a97073ac85fb64f5d38cd1a9576309d41036d260e77a5eb4454435bfda99093f76f94aa9caa8f5a27d4f16bda299

data/CHANGELOG.md

@@ -30,6 +30,17 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.2.62] - 2026-08-26
+
+- TAG: [v1.2.62][1.2.62t]
+- COVERAGE: 93.36% -- 5318/5696 lines in 33 files
+- BRANCH COVERAGE: 76.20% -- 2142/2811 branches in 33 files
+- 29.78% documented
+
+### Added
+
+- Add --no-cleanup to preserve failed template output and autostashes for debugging while keeping cleanup enabled by default.
+
 ## [1.2.61] - 2026-08-26
 
 - TAG: [v1.2.61][1.2.61t]
@@ -2196,7 +2207,9 @@ Please file a bug if you notice a violation of semantic versioning.
 - Fixed CI load failures on engines without compatible `pty` support by falling back to Open3 for interactive release commands.
 - Fixed Ruby 3.2 version-bump support by loading Prism lazily and wiring the Prism gem only for MRI versions that need it.
 
-[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.2.61...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.2.62...HEAD
+[1.2.62]: https://github.com/kettle-dev/kettle-family/compare/v1.2.61...v1.2.62
+[1.2.62t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.2.62
 [1.2.61]: https://github.com/kettle-dev/kettle-family/compare/v1.2.60...v1.2.61
 [1.2.61t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.2.61
 [1.2.60]: https://github.com/kettle-dev/kettle-family/compare/v1.2.59...v1.2.60

data/README.md

@@ -570,6 +570,7 @@ overridden with `--jobs`.
 kettle-family template
 kettle-family template --execute --jobs 4
 kettle-family template --execute --only kettle-family
+kettle-family template --execute --no-cleanup
 ```
 
 Templating uses `kettle-jem --events` as the default child interface, so
@@ -578,6 +579,12 @@ family report. Each member line includes a scheduled family-step counter and a
 per-member elapsed timer. Child `kettle-jem` events can still add progress marks,
 but only completed family steps advance the counter. Progress marks include:
 
+Executed template runs clean up failed member output and restore autostashes by
+default. Use `--no-cleanup` when debugging a failed template: the failed
+member's generated files and autostash are left in place for inspection, while
+successful or unreached members are restored normally. A successful run always
+restores its autostashes regardless of this option.
+
 | Mark | Meaning |
 |------|---------|
 | `>` | A phase or command step started. |
@@ -864,7 +871,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-5.676-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-5.696-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-family/blob/main/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/lib/kettle/family/cli.rb

@@ -177,6 +177,7 @@ module Kettle
             commit: !options.key?(:commit) || options[:commit],
             allow_dirty: truthy_option?(:allow_dirty),
             autostash: !options.key?(:autostash) || options[:autostash],
+            template_cleanup: true,
             target_version: nil,
             reset_target: nil,
             bup_args: [],
@@ -383,6 +384,15 @@ module Kettle
         command_name "template"
         usage "[options]"
         description "Plan or execute kettle-jem templating per member."
+
+        option :no_cleanup, long: "--no-cleanup", desc: "Preserve failed template output and autostashes for debugging" do
+          options[:template_cleanup] = false
+        end
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family("template", template_cleanup: options.fetch(:template_cleanup, true))
+        end
       end
 
       class GhaShaPins < WorkflowCommand
@@ -821,6 +831,7 @@ module Kettle
           commit: options[:commit],
           allow_dirty: options[:allow_dirty],
           autostash: options[:autostash],
+          template_cleanup: options[:template_cleanup],
           publish: options[:publish],
           push: options[:push],
           tag: options[:tag],

data/lib/kettle/family/version.rb

@@ -5,7 +5,7 @@ module Kettle
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = "1.2.61"
+      VERSION = "1.2.62"
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

data/lib/kettle/family/workflow.rb

@@ -105,7 +105,7 @@ module Kettle
       REGISTRY_WAIT_ATTEMPTS = 15
       REGISTRY_WAIT_INTERVAL_SECONDS = 15
 
-      def initialize(command:, config:, members:, family_members: nil, execute: false, accept: true, commit: true, allow_dirty: false, autostash: true, publish: false, push: false, tag: false, start_step: nil, skip_steps: nil, fast_recovery: nil, fast_recovery_members: nil, skip_ci: false, skip_changelog: false, local_ci: false, continue_ci_failures: false, ci_workflows: nil, skip_bundle_audit: false, skip_remotes: nil, required_remotes: nil, auto_dependency_floors: nil, gha_sha_pins_upgrade: "patch", gha_sha_pins_check: false, gha_sha_pins_ttl_days: nil, env_overrides: {}, debug: false, verbose: false, gem_signing_password: nil, secrets_provider: nil, jobs: nil, progress_io: nil, reset_target: nil, bup_args: [], bex_args: [], start_member: nil, start_branch: nil, **options)
+      def initialize(command:, config:, members:, family_members: nil, execute: false, accept: true, commit: true, allow_dirty: false, autostash: true, template_cleanup: true, publish: false, push: false, tag: false, start_step: nil, skip_steps: nil, fast_recovery: nil, fast_recovery_members: nil, skip_ci: false, skip_changelog: false, local_ci: false, continue_ci_failures: false, ci_workflows: nil, skip_bundle_audit: false, skip_remotes: nil, required_remotes: nil, auto_dependency_floors: nil, gha_sha_pins_upgrade: "patch", gha_sha_pins_check: false, gha_sha_pins_ttl_days: nil, env_overrides: {}, debug: false, verbose: false, gem_signing_password: nil, secrets_provider: nil, jobs: nil, progress_io: nil, reset_target: nil, bup_args: [], bex_args: [], start_member: nil, start_branch: nil, **options)
         @command = command
         @config = config
         @members = members
@@ -115,6 +115,7 @@ module Kettle
         @commit = commit
         @allow_dirty = allow_dirty
         @autostash = autostash
+        @template_cleanup = template_cleanup
         @publish = publish
         @push = push
         @tag = tag
@@ -202,7 +203,7 @@ module Kettle
         execute && release_command_delegates_secrets_to_kettle_release?
       end
 
-      attr_reader :command, :config, :members, :family_members, :execute, :accept, :commit, :allow_dirty, :autostash, :publish, :push, :tag, :start_step, :skip_steps, :fast_recovery, :fast_recovery_members, :skip_ci, :skip_changelog, :local_ci, :continue_ci_failures, :ci_workflows, :skip_bundle_audit, :skip_remotes, :required_remotes, :auto_dependency_floors, :gha_sha_pins_upgrade, :gha_sha_pins_check, :gha_sha_pins_ttl_days, :env_overrides, :debug, :verbose, :jobs, :progress_io, :reset_target, :bup_args, :bex_args, :start_member, :start_branch
+      attr_reader :command, :config, :members, :family_members, :execute, :accept, :commit, :allow_dirty, :autostash, :template_cleanup, :publish, :push, :tag, :start_step, :skip_steps, :fast_recovery, :fast_recovery_members, :skip_ci, :skip_changelog, :local_ci, :continue_ci_failures, :ci_workflows, :skip_bundle_audit, :skip_remotes, :required_remotes, :auto_dependency_floors, :gha_sha_pins_upgrade, :gha_sha_pins_check, :gha_sha_pins_ttl_days, :env_overrides, :debug, :verbose, :jobs, :progress_io, :reset_target, :bup_args, :bex_args, :start_member, :start_branch
 
       def template_with_worktree_sync_results
         runner = command_runner
@@ -214,7 +215,11 @@ module Kettle
 
         sync_results, stashes = template_worktree_sync_results(runner: runner)
         unless sync_results.all?(&:ok?)
-          return checkout_preflight + sync_results + restore_template_autostashes(stashes, runner: runner)
+          return checkout_preflight + sync_results + restore_template_autostashes(
+            stashes,
+            runner: runner,
+            preserve_members: template_cleanup ? [] : failed_template_members(sync_results)
+          )
         end
 
         workflow_results = branch_checkout_dirty_preflight_results
@@ -228,8 +233,18 @@ module Kettle
           end
         end
 
-        rollback_results = rollback_failed_template_worktrees(stashes, workflow_results, runner: runner)
-        checkout_preflight + sync_results + workflow_results + rollback_results + restore_template_autostashes(stashes, runner: runner)
+        failed_members = failed_template_members(workflow_results)
+        rollback_results = if template_cleanup
+          rollback_failed_template_worktrees(stashes, workflow_results, runner: runner)
+        else
+          []
+        end
+        restore_results = restore_template_autostashes(
+          stashes,
+          runner: runner,
+          preserve_members: template_cleanup ? [] : failed_members
+        )
+        checkout_preflight + sync_results + workflow_results + rollback_results + restore_results
       end
 
       def template_worktree_sync_results(runner:)
@@ -268,27 +283,33 @@ module Kettle
         [results, stashes]
       end
 
-      def restore_template_autostashes(stashes, runner:)
+      def restore_template_autostashes(stashes, runner:, preserve_members: [])
+        preserve_members = Array(preserve_members).map(&:to_s)
         stashes.reverse_each.map do |stash|
+          member = stash.fetch(:member)
+          if preserve_members.include?(member.name.to_s)
+            next template_autostash_preserved_result(member: member, ref: stash.fetch(:ref))
+          end
+
           restore = runner.call(
-            member: stash.fetch(:member),
+            member: member,
             phase: "template_autostash_restore",
             command: ["git", "stash", "pop", stash.fetch(:ref)]
           )
           next restore if restore.ok?
 
-          if template_generated_lockfile_restore_refusal?(stash.fetch(:member), restore)
+          if template_generated_lockfile_restore_refusal?(member, restore)
             next runner.call(
-              member: stash.fetch(:member),
+              member: member,
               phase: "template_autostash_generated_lockfile_recovery",
               command: template_generated_lockfile_restore_command(stash)
             )
           end
 
-          next restore if !template_generated_lockfile_only_conflict?(stash.fetch(:member))
+          next restore if !template_generated_lockfile_only_conflict?(member)
 
           runner.call(
-            member: stash.fetch(:member),
+            member: member,
             phase: "template_autostash_generated_lockfile_recovery",
             command: [
               "sh", "-lc",
@@ -308,6 +329,26 @@ module Kettle
         end
       end
 
+      def failed_template_members(results)
+        results.reject(&:ok?).filter_map(&:member_name).uniq
+      end
+
+      def template_autostash_preserved_result(member:, ref:)
+        CommandResult.new(
+          member.name,
+          "template_autostash_preserved",
+          ["internal", "template-autostash-preserved"],
+          member.root,
+          0,
+          true,
+          "preserved failed template output and autostash #{ref} for debugging",
+          "",
+          0.0,
+          true,
+          "template cleanup disabled"
+        )
+      end
+
       def template_generated_lockfile_restore_refusal?(member, restore)
         output = [restore.stdout, restore.stderr].compact.join("\n")
         return false unless output.include?("would be overwritten by merge")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-family
 version: !ruby/object:Gem::Version
-  version: 1.2.61
+  version: 1.2.62
 platform: ruby
 authors:
 - Peter H. Boling
@@ -441,10 +441,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-family.galtzo.com
-  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v1.2.61
-  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.2.61/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v1.2.62
+  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.2.62/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-family/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.2.61
+  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.2.62
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-family/wiki
   news_uri: https://www.railsbling.com/tags/kettle-family