kettle-family 1.3.7 → 1.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec4f59e4397fe55738de3f0e3e482a2053d3c771716e9d94de40478f76ba80ae
-  data.tar.gz: 7ea569f07fa6cc8cc46cf5351cf93441ece85870c80ab51aed2458e0ce66346a
+  metadata.gz: f74d2fca80b37d1577e7212df092067958426dc780d1e07594b545d057a7321e
+  data.tar.gz: 23f68c9dd77d68828708ecfea9d64c87af8b12182689e9c9c15e0dfddc6648d5
 SHA512:
-  metadata.gz: 9dac940565396b2209bd67e957af7f2e015318d70572c05cca684e8de26c43d75755a142727d994baa5fbd646ce674fa7ab6c84bdb913ca9c6685824fd3beca6
-  data.tar.gz: 53c75a31e0896365a67c7b0ec46a45830d1e71abe37843dc715ee7f086f39166fbf39c36620efc0760d00848a6ce11238da0ee81cf84cfa6ced5e192e13178e4
+  metadata.gz: 327d0135be9e3ee4fb1abea1794d3acf2e714f791b3e83063bb6290a5466ada57b0d49b969f85cbde18050499c34bb57a2334cd7b2a98857f411fe4b015147d9
+  data.tar.gz: 21892de4191d48f57e7b9183d6a45bbb7d6ef5b3ba1b1a3a4922ba42b39da09ddb0f3d8ba30d3e6c86730a86c876023e405b1d93617896f369916245b6b45718

data/CHANGELOG.md

@@ -30,6 +30,39 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.3.9] - 2026-10-10
+
+- TAG: [v1.3.9][1.3.9t]
+- COVERAGE: 93.43% -- 7068/7565 lines in 43 files
+- BRANCH COVERAGE: 77.95% -- 2832/3633 branches in 43 files
+- 35.42% documented
+
+### Added
+
+- New `clean-blockers` command uninstalls locally installed gems, from any family, whose unreleased versions are pinned by members’ lockfiles. Unlike `clean-unreleased`, which can only remove a family sibling newer than its latest release, it removes cross-family offenders: a kettle-dev member blocked by unreleased StructuredMerge gems, or vice versa.
+
+- Add clean-installed: the deterministic inverse of install. Uninstalls each selected member's current source version (plus configured install local_dependencies, which install also covers) when that version is unreleased, including cached .gem files. The other two cleanups cannot see this pollution class: clean-unreleased derives candidates from release state and can miss versions it judges released, and clean-blockers only sees lockfile pins, so an installed-but-unpinned gem (observed: commonmarker-merge 7.1.10) survives and then breaks gem activation with a dangling exact pin once the rest of its series is removed. Release state comes from the same ReleaseStateCheck clean-unreleased uses; members at a released source version are left alone. Also extracts MemberLoader from LocalInstall so install and clean-installed construct members identically.
+
+- Add a release-mode pre-clean to bup, bupb, and update-bundler: before a registry-only re-resolution, installed gems whose versions no registry publishes are removed, including cross-family gems named in member lockfiles. Previously the release-mode update only detected such pins after the fact (PublishedVersionCheck) and its advice to re-run the update was circular, because bundler resolves against the local gem dir and >= floors always re-pin the installed unreleased version. Removal up front turns that opaque post-update failure into a resolved-before-it-mattered cleanup. Fails open when the registry is unreachable: a network blip never removes gems. Also adds the standalone clean-installed command, the deterministic inverse of install, which uninstalls each member's unreleased source version (plus install local_dependencies) including cached .gem files.
+
+### Changed
+
+- [kc] kettle-jem/prepare: updated 2 project files:
+  - dependencies (2)
+
+- [kc] kettle-jem/template: updated 3 project files:
+  - code and tests (1)
+  - documentation (1)
+  - other (1)
+
+### Fixed
+
+- Add a structured CommandResult#diagnostics channel carrying complete, machine-readable findings. stdout is a human summary truncated to its last 20 lines, so a JSON consumer parsing it to decide what to act on silently acted on an incomplete set: a real cross-family release reported 28 unpublished lockfile pins and the JSON carried only 20, losing 8 gems. PublishedVersionCheck now emits each pin as gem, version, remote, member, and lockfile data alongside its message.
+
+- clean-blockers (and clean-unreleased, sharing GemUninstallSupport): two uninstall bugs fixed. The batched gem uninstall now retries once with --ignore-dependencies when RubyGems aborts on a dependent outside the batch (Gem::DependencyRemovalException), re-batching only what survived the abort; the dependency refusal previously left a partial cleanup reported as failure. And the cleanup now removes the cached .gem files as well as the installed specifications -- gem uninstall leaves cache/<name>-<version>.gem behind, and the next bundle install was reinstalling the same unreleased versions from that cache without touching the network, so the cleanup did not hold.
+
+- release: stop handing member kettle-release children the family-root dev bundle via BUNDLE_GEMFILE in release mode. That bundle resolves the family's own members, which are unreleased while any member is being released, so the child's kettle-release died booting (observed: "Could not find kettle-family-1.3.9 ... in locally installed gems" for every member). In release mode the child now resolves kettle-release from its own released dependency; local release tooling (KETTLE_DEV_DEV set) still pins the local kettle-dev bundle.
+
 ## [1.3.7] - 2026-10-09
 
 - TAG: [v1.3.7][1.3.7t]
@@ -2931,7 +2964,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.3.7...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.3.9...HEAD
+[1.3.9]: https://github.com/kettle-dev/kettle-family/compare/v1.3.7...v1.3.9
+[1.3.9t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.9
 [1.3.7]: https://github.com/kettle-dev/kettle-family/compare/v1.3.6...v1.3.7
 [1.3.7t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.7
 [1.3.6]: https://github.com/kettle-dev/kettle-family/compare/v1.3.5...v1.3.6

data/README.md

@@ -1192,7 +1192,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-7.231-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-7.565-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/blocker_cleanup.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "kettle/dev/lockfile_reset"
+
+module Kettle
+  module Family
+    # Removes locally installed gem versions that block a command, including gems
+    # belonging to OTHER families.
+    #
+    # Why this exists alongside +UnreleasedGemCleanup+ (`clean-unreleased`): that
+    # command derives candidates from family members' release state, so it can
+    # only ever remove a member of its own family whose installed version exceeds
+    # the latest release. The gems that actually block a release are usually
+    # cross-family, and each family is blocked by the other's legitimately
+    # installed development versions. Measured live:
+    #
+    #   kettle-dev        28 pins   ast-crispr 7.1.10, ast-merge, tree_haver, ...
+    #   kettle-drift      22 pins   (all structuredmerge gems)
+    #   kettle-family     28 pins   (all structuredmerge gems)
+    #   kettle-changelog   2 pins   nomono 1.1.7, token-resolver 2.0.13
+    #   kettle-jem         3 pins   kettle-test 2.0.24, nomono, token-resolver
+    #   smorg-rb           3 pins   (all kettle-dev gems)
+    #
+    # Neither family's `clean-unreleased` can see the other's offenders, which is
+    # what forced the kettle-dev 3.1.9 and kettle-family 1.3.7 releases to be
+    # finished manually after `gem push`: the tag, checksum and GitHub Release
+    # steps all run through a release-mode dependency update, and that cannot
+    # resolve while cross-family unreleased pins are present.
+    #
+    # The blocker set comes from calling PublishedVersionCheck directly on each
+    # selected member and reading its structured diagnostics, NOT from running the
+    # blocked command and parsing its report. A dry-run release cannot surface
+    # them: workflow.rb:2522-2526 replaces the member result with a synthetic
+    # "release readiness requires lockfile normalization" entry before
+    # append_release_internal_checks runs, so published_version_check never
+    # appears and every diagnostics array is empty. The findings are computed
+    # inside release_lockfile_readiness_would_fail? (workflow.rb:5785-5794) and
+    # then discarded in favour of a boolean. Running with --execute to obtain them
+    # would run the release, which is what we are trying to unblock.
+    #
+    # PublishedVersionCheck is read-only, so this is safe to run without
+    # --execute; only the uninstall itself is gated.
+    class BlockerCleanup
+      PHASE = "clean_blockers"
+      BLOCKER_KIND = "unpublished_lockfile_pin"
+      NO_BLOCKERS_MESSAGE = "no unpublished lockfile pins found"
+      # A member in local-gem mode resolves its family siblings through PATH
+      # remotes, so its lockfile has no GEM-section specs to check. Reporting
+      # "no blockers" for it would claim a clean bill of health that was never
+      # established, so it is reported separately.
+      NOT_INSPECTABLE_MESSAGE = "lockfile has no registry-resolved pins; nothing inspectable"
+      NOT_REMOVABLE_PREFIX = "blockers pinned but not installed in a gem home (source checkout, not removable): "
+
+      include GemUninstallSupport
+
+      def initialize(members:, execute: false, runner: nil)
+        @members = members
+        @execute = execute
+        @runner = runner || CommandRunner.new(execute: execute)
+      end
+
+      # @return [Array<CommandResult>]
+      def results
+        findings = members.map { |member| member_blockers(member) }
+        removable = removable_candidates(findings)
+        annotated = annotate_contributors(findings, removable)
+        informational = informational_results(annotated)
+        return informational if removable.empty?
+
+        informational + batched_cleanup_results(annotated, removable)
+      end
+
+      private
+
+      attr_reader :members, :execute, :runner
+
+      def uninstall_phase
+        PHASE
+      end
+
+      # One member's blockers, from the check's structured diagnostics.
+      #
+      # @return [Hash] member, blockers (deduped [name, version, remote]),
+      #   inspectable (whether the lockfile had registry pins at all)
+      def member_blockers(member)
+        lockfile = File.join(member.root, "Gemfile.lock")
+        return {member: member, blockers: [], inspectable: false} unless File.file?(lockfile)
+
+        pins = registry_pins(lockfile)
+        result = PublishedVersionCheck.call(member: member)
+        blockers = result.diagnostics
+          .select { |diagnostic| diagnostic["kind"] == BLOCKER_KIND }
+          .map { |diagnostic| [diagnostic["gem"], diagnostic["version"], diagnostic["remote"]] }
+          .uniq
+
+        {member: member, blockers: blockers, inspectable: !pins.empty?}
+      end
+
+      def registry_pins(lockfile)
+        Kettle::Dev::LockfileReset.registry_gem_specs_from_source(File.read(lockfile))
+      rescue
+        []
+      end
+
+      # Blockers that are actually installed in a gem home and can therefore be
+      # removed, deduplicated across members by [name, version].
+      #
+      # A blocker that is not installed in a gem home is a PATH or git source
+      # checkout: `gem uninstall` cannot remove it, and including one would abort
+      # the whole batch. Those are reported rather than attempted.
+      #
+      # The version is normalized by stripping any platform suffix, because a
+      # lockfile pins `nokogiri (1.19.4-x86_64-linux-gnu)` while gem homes store
+      # the spec as `nokogiri-1.19.4-x86_64-linux-gnu.gemspec` and
+      # #installed_versions records it as 1.19.4.
+      def removable_candidates(findings)
+        findings.flat_map { |finding| normalized_blockers(finding) }
+          .uniq
+          .select { |name, version| installed_versions(name).include?(version) }
+      end
+
+      # A finding's blockers as [name, Gem::Version] pairs, minus any whose version
+      # cannot be parsed. Shared by #removable_candidates and #annotate_contributors
+      # so both see identical pairs and cannot drift apart.
+      def normalized_blockers(finding)
+        finding.fetch(:blockers).filter_map do |name, version, _remote|
+          normalized = normalize_version(version)
+          [name, normalized] unless normalized.nil?
+        end
+      end
+
+      # Strips any platform suffix and parses, rejecting blanks.
+      #
+      # The blank guard matters: `Gem::Version.new("")` returns version "0" rather
+      # than raising, so an empty version from a malformed diagnostic would become
+      # a bogus `name:0` uninstall argument instead of being skipped.
+      #
+      # @return [Gem::Version, nil]
+      def normalize_version(version)
+        text = version.to_s.split("-", 2).first.to_s.strip
+        return nil if text.empty?
+
+        parse_gem_version(text)
+      end
+
+      # Adds `:own` — the subset of the global removable set this member pinned.
+      #
+      # Computed once here rather than on demand: three call sites need it
+      # (host selection, contributing filter, per-member reporting), and each
+      # would otherwise re-run the same normalization and membership test.
+      def annotate_contributors(findings, removable)
+        findings.map do |finding|
+          own = normalized_blockers(finding).select { |candidate| removable.include?(candidate) }.uniq
+          finding.merge(own: own)
+        end
+      end
+
+      # Per-member reporting. Members that contributed removable blockers get the
+      # shared batch outcome; the rest get a plain informational result.
+      def informational_results(annotated)
+        annotated.filter_map do |finding|
+          next if finding.fetch(:own).any?
+
+          member = finding.fetch(:member)
+          message = if finding.fetch(:blockers).any?
+            unremovable_blockers_message(finding)
+          elsif finding.fetch(:inspectable)
+            NO_BLOCKERS_MESSAGE
+          else
+            NOT_INSPECTABLE_MESSAGE
+          end
+          informational_result(member: member, message: message)
+        end
+      end
+
+      def contributors(annotated)
+        annotated.select { |finding| finding.fetch(:own).any? }
+      end
+
+      # Names the blockers this member pinned that cannot be removed here, and
+      # why, so a cross-family offender is attributable rather than mysterious.
+      def unremovable_blockers_message(finding)
+        names = finding.fetch(:blockers).map { |name, version, _remote| "#{name} #{version}" }
+        "#{NOT_REMOVABLE_PREFIX}#{names.join(", ")}"
+      end
+
+      # Runs the batch once, then reports that one outcome against every member
+      # that contributed to it. See the class comment for why a single batched
+      # invocation is required rather than one per gem.
+      def batched_cleanup_results(annotated, removable)
+        contributing = contributors(annotated)
+        # Defensive: `removable` is derived from findings' own blockers, so a
+        # non-empty set always has at least one contributor. Guarded anyway
+        # because a nil host would raise NoMethodError inside the uninstall.
+        host = contributing.first&.fetch(:member)
+        return [] if host.nil?
+
+        command = batched_uninstall_command(removable)
+        # gem uninstall does not depend on the working directory, so the first
+        # contributing member provides a real directory to execute in.
+        outcome = if execute
+          verified_uninstall_outcome(candidates: removable, host: host, command: command)
+        else
+          dry_run_uninstall_outcome(command: command)
+        end
+
+        contributing.map { |finding| member_result(finding, outcome) }
+      end
+
+      # One member's view of the shared batch outcome, naming the gems that member
+      # pinned so a failure is attributable rather than mysterious.
+      #
+      # The member's own contribution comes from the annotated finding:
+      # PublishedVersionCheck hits the registry, so re-invoking it during
+      # reporting would add a network round-trip per member.
+      def member_result(finding, outcome)
+        member = finding.fetch(:member)
+        own = finding.fetch(:own)
+        own_reason = describe_gem_versions(own)
+        reason = if outcome.ok? || own.empty?
+          outcome.reason
+        else
+          "batched gem uninstall including #{own_reason} failed"
+        end
+        outcome.dup.tap do |copy|
+          copy.member_name = member.name
+          copy.workdir = member.root
+          copy.stdout = outcome.skipped ? "would uninstall #{own_reason}" : outcome.stdout
+          copy.reason = reason
+        end
+      end
+
+      def informational_result(member:, message:)
+        CommandResult.new(
+          member_name: member.name,
+          phase: PHASE,
+          command: ["internal", PHASE],
+          workdir: member.root,
+          status: 0,
+          success: true,
+          stdout: message,
+          stderr: "",
+          elapsed_seconds: 0.0,
+          skipped: false,
+          reason: nil
+        )
+      end
+    end
+  end
+end

data/lib/kettle/family/clean_installed.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Family
+    # Uninstalls exactly what `install` installs: each selected member's current
+    # source version, plus the cached .gem files.
+    #
+    # This is the deterministic inverse of `install`, and it exists because the
+    # other two cleanups cannot see this class of pollution:
+    #
+    # - +UnreleasedGemCleanup+ (`clean-unreleased`) removes installed versions
+    #   newer than the latest release, but it derives candidates per member from
+    #   release state and can miss versions it judges released.
+    # - +BlockerCleanup+ (`clean-blockers`) removes what members' lockfiles pin,
+    #   so an installed-but-unpinned gem is invisible to it. Observed live:
+    #   commonmarker-merge 7.1.10 survived a blocker cleanup (no release
+    #   lockfile pinned it), then broke gem activation family-wide with its
+    #   dangling exact pin on markdown-merge = 7.1.10 once the rest of the
+    #   series was removed.
+    #
+    # Candidates are the members `install` would act on -- the selected members
+    # plus any configured install local_dependencies -- restricted to those whose
+    # source version is unreleased (a member already at its released version has
+    # nothing to remove; uninstalling it would only churn the bundles that
+    # resolve it). Release state comes from the same ReleaseStateCheck
+    # +UnreleasedGemCleanup+ uses.
+    #
+    # The uninstall itself is the shared GemUninstallSupport batch: one
+    # invocation, a documented --ignore-dependencies retry when an out-of-batch
+    # dependent aborts it, cache removal, and post-uninstall re-enumeration.
+    #
+    # Note for the family running it: when this command is executed from an
+    # installed kettle-family, the batch includes kettle-family itself. The
+    # uninstall runs in a subprocess, so self-removal mid-run is safe; the
+    # executable falls back to the latest released install afterwards.
+    class CleanInstalled
+      PHASE = "clean_installed"
+      RELEASED_MESSAGE = "source version is released; nothing to uninstall"
+      NOT_INSTALLED_MESSAGE = "source version is not installed"
+      UNKNOWN_VERSION_MESSAGE = "source version is unknown; nothing to uninstall"
+      UNKNOWN_RELEASED_MESSAGE = "latest released version is unknown; no cleanup attempted"
+
+      include GemUninstallSupport
+      include MemberLoader
+
+      def initialize(config:, members:, execute: false, runner: nil)
+        @config = config
+        @members = members
+        @execute = execute
+        @runner = runner || CommandRunner.new(execute: execute)
+      end
+
+      # @return [Array<CommandResult>]
+      def results
+        findings = member_findings
+        removable = findings.filter_map { |finding| finding[:candidate] }.uniq
+        annotated = findings.map do |finding|
+          candidate = finding[:candidate]
+          own = (candidate && removable.include?(candidate)) ? [candidate] : []
+          finding.merge(own: own)
+        end
+        informational = annotated.filter_map { |finding| informational_for(finding) }
+        return informational if removable.empty?
+
+        informational + batched_cleanup_results(annotated.select { |finding| finding[:own].any? }, removable)
+      end
+
+      private
+
+      attr_reader :config, :members, :execute, :runner
+
+      def uninstall_phase
+        PHASE
+      end
+
+      # The members `install` would act on: selected members plus configured
+      # install local_dependencies, deduplicated by name.
+      def candidate_members
+        local = config.install_local_dependencies.map { |path| member_from_path(path) }
+        seen = {}
+        (local + members).each_with_object([]) do |member, memo|
+          next if seen.key?(member.name)
+
+          seen[member.name] = true
+          memo << member
+        end
+      end
+
+      def release_state_by_member
+        ReleaseStateCheck.new(config: config, members: candidate_members).results.each_with_object({}) do |result, memo|
+          memo[result.member_name] = result
+        end
+      end
+
+      # One member's candidate: its source version, when that version is
+      # unreleased and installed. [name, Gem::Version] or nil, plus the reason
+      # there is nothing to do.
+      def member_findings
+        states = release_state_by_member
+        candidate_members.map do |member|
+          state = states[member.name]
+          candidate, message = candidate_for(member, state)
+          {member: member, candidate: candidate, message: message, state: state}
+        end
+      end
+
+      def candidate_for(member, state)
+        return [nil, nil] unless state&.ok?
+
+        latest = latest_released_version(state.state)
+        return [nil, nil] unless latest
+
+        source = parse_gem_version(member.version.to_s)
+        return [nil, UNKNOWN_VERSION_MESSAGE] unless source
+        return [nil, RELEASED_MESSAGE] unless source > latest
+        return [[member.name, source], nil] if installed_versions(member.name).include?(source)
+
+        [nil, NOT_INSTALLED_MESSAGE]
+      end
+
+      def latest_released_version(state)
+        value = state.fetch("latest_released", nil).to_s
+        return nil if value.empty? || value == "unknown"
+
+        Gem::Version.new(value.delete_prefix("v"))
+      rescue ArgumentError
+        nil
+      end
+
+      # Per-member outcomes that are not part of the batch: unreadable release
+      # state (a failure naming its member), or nothing to do (informational).
+      def informational_for(finding)
+        member = finding.fetch(:member)
+        state = finding[:state]
+        return release_state_failure(member: member, release_state: state) unless state&.ok?
+
+        message = finding[:message]
+        return nil if message.nil? && finding[:own].any?
+        return informational_result(member: member, message: UNKNOWN_RELEASED_MESSAGE) if message.nil?
+
+        informational_result(member: member, message: message)
+      end
+
+      # Runs the batch once, then reports that one outcome against every member
+      # whose gem was in it, mirroring UnreleasedGemCleanup: the command and
+      # exit state are shared, but each member reports only its own gem so a
+      # failure stays attributable.
+      def batched_cleanup_results(contributors, removable)
+        host = contributors.first.fetch(:member)
+        command = batched_uninstall_command(removable)
+        outcome = if execute
+          verified_uninstall_outcome(candidates: removable, host: host, command: command)
+        else
+          dry_run_uninstall_outcome(command: command)
+        end
+
+        contributors.map do |finding|
+          member_result(finding.fetch(:member), outcome, finding.fetch(:own))
+        end
+      end
+
+      def member_result(member, outcome, own_candidates)
+        own = describe_gem_versions(own_candidates)
+        reason = if outcome.ok? || own_candidates.empty?
+          outcome.reason
+        else
+          "batched gem uninstall including #{own} failed"
+        end
+        outcome.dup.tap do |copy|
+          copy.member_name = member.name
+          copy.workdir = member.root
+          copy.stdout = outcome.skipped ? "would uninstall #{own}" : outcome.stdout
+          copy.reason = reason
+        end
+      end
+
+      def informational_result(member:, message:)
+        CommandResult.new(
+          member_name: member.name,
+          phase: PHASE,
+          command: ["internal", PHASE],
+          workdir: member.root,
+          status: 0,
+          success: true,
+          stdout: message,
+          stderr: "",
+          elapsed_seconds: 0.0,
+          skipped: false,
+          reason: nil
+        )
+      end
+
+      def release_state_failure(member:, release_state:)
+        CommandResult.new(
+          member_name: member.name,
+          phase: PHASE,
+          command: ["internal", PHASE],
+          workdir: member.root,
+          status: release_state&.status || 1,
+          success: false,
+          stdout: "",
+          stderr: release_state&.stderr.to_s,
+          elapsed_seconds: 0.0,
+          skipped: false,
+          reason: "release state unavailable"
+        )
+      end
+    end
+  end
+end

data/lib/kettle/family/cli.rb

@@ -11,7 +11,7 @@ module Kettle
     class CLI < CommandKit::Command
       include CommandKit::Commands
 
-      COMMANDS = %w[version mise-trust discover plan report metadata check clean-unreleased reconcile-releases reset test lint docs template gha-sha-pins bup bupb update-bundler bex install bump bump-version add-changelog release push pull sync up branch-lanes release-state state].freeze
+      COMMANDS = %w[version mise-trust discover plan report metadata check clean-blockers clean-installed clean-unreleased reconcile-releases reset test lint docs template gha-sha-pins bup bupb update-bundler bex install bump bump-version add-changelog release push pull sync up branch-lanes release-state state].freeze
       WORKFLOW_COMMANDS = %w[check reset test lint docs template gha-sha-pins bup bupb update-bundler bex release push pull sync up].freeze
 
       command_name "kettle-family"
@@ -353,6 +353,18 @@ module Kettle
         description "Uninstall locally installed family gem versions newer than the latest released version."
       end
 
+      class CleanBlockers < WorkflowCommand
+        command_name "clean-blockers"
+        usage "[options]"
+        description "Uninstall locally installed gems, from any family, whose unreleased versions are pinned by members' lockfiles."
+      end
+
+      class CleanInstalled < WorkflowCommand
+        command_name "clean-installed"
+        usage "[options]"
+        description "Uninstall the exact gem versions install installs: each member's current source version, when unreleased, including cached .gem files."
+      end
+
       class ReconcileReleases < BaseCommand
         include ExecutionOptions
 
@@ -657,6 +669,8 @@ module Kettle
       command "report", ReportCommand
       command Metadata
       command Check
+      command CleanBlockers
+      command CleanInstalled
       command CleanUnreleased
       command ReconcileReleases
       command Reset
@@ -870,6 +884,8 @@ module Kettle
         return bump_version_results(config: config, members: members, options: options, phase: command, release_state_results: release_state_results) if %w[bump bump-version].include?(command)
         return add_changelog_results(members: members, options: options) if command == "add-changelog"
         return clean_unreleased_results(config: config, members: members, options: options) if command == "clean-unreleased"
+        return clean_blockers_results(members: members, options: options) if command == "clean-blockers"
+        return clean_installed_results(config: config, members: members, options: options) if command == "clean-installed"
         return reconcile_release_results(config: config, members: members, options: options) if command == "reconcile-releases"
         return branch_lane_results(config: config, members: members) if command == "branch-lanes"
         return release_state_results(config: config, members: members, jobs: options[:jobs], event_handler: state_event_handler) if command == "release-state"
@@ -1361,6 +1377,14 @@ module Kettle
         UnreleasedGemCleanup.new(config: config, members: members, execute: options[:execute]).results
       end
 
+      def clean_blockers_results(members:, options:)
+        BlockerCleanup.new(members: members, execute: options[:execute]).results
+      end
+
+      def clean_installed_results(config:, members:, options:)
+        CleanInstalled.new(config: config, members: members, execute: options[:execute]).results
+      end
+
       def reconcile_release_results(config:, members:, options:)
         ReleaseReconciler.new(config: config, members: members, execute: options[:execute]).results
       end

data/lib/kettle/family/command_result.rb

@@ -18,7 +18,12 @@ module Kettle
       :output_streamed,
       :log_path,
       :resume_step,
-      :resume_command
+      :resume_command,
+      # Machine-readable findings, complete and unsummarized. See #diagnostics.
+      # Appended last because this Struct is positional: specs construct it with
+      # positional arguments, so inserting a member mid-list would silently shift
+      # every value after it.
+      :diagnostics
     ) do
       def to_h
         {
@@ -37,10 +42,37 @@ module Kettle
           "output_streamed" => output_streamed?,
           "log_path" => log_path,
           "resume_step" => resume_step,
-          "resume_command" => resume_command
+          "resume_command" => resume_command,
+          "diagnostics" => diagnostics
         }
       end
 
+      # Structured findings for machine consumers, complete and unsummarized.
+      #
+      # `stdout` is a human-facing summary and is deliberately truncated to its
+      # last 20 lines by #summarize, so it cannot carry a full finding set. A
+      # consumer that parsed the truncated `stdout` to decide what to act on
+      # would silently act on an incomplete set. That is not hypothetical:
+      # PublishedVersionCheck reported 28 unpublished lockfile pins for one
+      # member, and the JSON report carried only the last 20, losing 8 gems.
+      #
+      # The text report is unaffected — it prints `stdout` in full — which is why
+      # this only bites JSON consumers.
+      #
+      # Each entry is a Hash whose shape is defined by the producing check, plus
+      # a "message" string matching the human-readable line it summarizes. Always
+      # an Array, never nil, so consumers need no guard.
+      #
+      # Read through `self[:diagnostics]` rather than `super`: the block passed to
+      # `Struct.new` is class_eval'd onto the generated class, so this method
+      # REPLACES the generated accessor and has no superclass method to call.
+      # `Struct#[]` reads the slot directly and cannot recurse into this method.
+      #
+      # @return [Array<Hash>]
+      def diagnostics
+        Array(self[:diagnostics])
+      end
+
       def ok?
         success || skipped
       end