kettle-family 0.1.31 → 0.1.32

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04edf8e4e21650602cc2162d54c6231a9c3ee61c9f3864cdd21ef7ac4ae127e7
-  data.tar.gz: 51ccd928cf357a0a405c593226b239d41fad32ccf18f190ecf355168576de9d7
+  metadata.gz: ab7db3c6a2cfe0e5c9456e14e0d7b643ee341da154f591c5de6b81d09a423a65
+  data.tar.gz: 9b1b9ecbc828efccfc1d51327a9a4efe7b69b2726500cabdca5943c6ca742f4e
 SHA512:
-  metadata.gz: 741ee2a5e4af039d3a44915ca6a93036ca265f59fa8f8a1d9cd011e888bf5e7acc7a637d4e99f12ec555915233f9096bddbca905f167fff28ff6e5ae5dc56a1f
-  data.tar.gz: d3b4434516b929156187e73ee4b65afa4f153818ee958cbf0221924ad2c20adc9da28df6887ff57aabd265f68d07157e8381d1c554575fe842b432150fe9eb5d
+  metadata.gz: 4e95a38962f4f0f4dada8de8adf59e9c2910ef9c7984df519f474fda1167e86523a6bb54d87382da9dd7e231bbd44df08955fed36e916aeb28acf078354cfc28
+  data.tar.gz: 28c0f4e0592ef36165f5a4bfe62a82fb8c13c8ee2ff5a22ad28dddad84a4b5003a84d5272f84eeb936d920f2fc2a135d426e54ca8d0b48a84203b6e2cefc33d9

data/CHANGELOG.md

@@ -30,6 +30,31 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.1.32] - 2026-07-01
+
+- TAG: [v0.1.32][0.1.32t]
+- COVERAGE: 95.46% -- 2227/2333 lines in 21 files
+- BRANCH COVERAGE: 75.96% -- 714/940 branches in 21 files
+- 29.82% documented
+
+### Added
+
+- `kettle-family` now supports `--exclude` anywhere member selection is
+  available, selecting all members except the comma-separated exclusions.
+- `kettle-family` now uses command-specific option parsing and help powered by
+  `command_kit`, keeping naked help focused on global options.
+
+### Fixed
+
+- `kettle-family` reports a final summary for every command, including selected
+  release members left pending when parallel release execution stops after a
+  failure.
+
+- `kettle-family release --execute` runs release members sequentially on
+  TruffleRuby to avoid a TruffleRuby 24.2 internal `ENV.replace` crash from
+  `Bundler.with_unbundled_env` inside parallel release threads
+  ([truffleruby/truffleruby#4352](https://github.com/truffleruby/truffleruby/issues/4352)).
+
 ## [0.1.31] - 2026-06-30
 
 - TAG: [v0.1.31][0.1.31t]
@@ -547,7 +572,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/v0.1.31...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v0.1.32...HEAD
+[0.1.32]: https://github.com/kettle-dev/kettle-family/compare/v0.1.31...v0.1.32
+[0.1.32t]: https://github.com/kettle-dev/kettle-family/releases/tag/v0.1.32
 [0.1.31]: https://github.com/kettle-dev/kettle-family/compare/v0.1.30...v0.1.31
 [0.1.31t]: https://github.com/kettle-dev/kettle-family/releases/tag/v0.1.31
 [0.1.30]: https://github.com/kettle-dev/kettle-family/compare/v0.1.29...v0.1.30

data/README.md

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

@@ -1,192 +1,498 @@
 # frozen_string_literal: true
 
+require "command_kit"
+require "command_kit/commands"
 require "fileutils"
 require "optparse"
 
 module Kettle
   module Family
-    class CLI
+    class CLI < CommandKit::Command
+      include CommandKit::Commands
+
       COMMANDS = %w[discover plan report metadata check test lint docs template gha-sha-pins bup bupb bex install bump-version add-changelog release push pull up branch-lanes release-state].freeze
       WORKFLOW_COMMANDS = %w[check test lint docs template gha-sha-pins bup bupb bex release push pull up].freeze
 
+      command_name "kettle-family"
+      usage "[options] COMMAND [ARGS...]"
+      description "Coordinate related Ruby gems as one family."
+
+      option :root, value: {type: String, usage: "PATH"}, desc: "Workspace or family root"
+      option :config, value: {type: String, usage: "PATH"}, desc: "Family config path"
+      option :json, desc: "Print JSON report to stdout"
+      option :report, value: {type: String, usage: "PATH"}, desc: "Write JSON report to PATH"
+
       def self.call(argv, out: $stdout, err: $stderr)
-        new(argv, out: out, err: err).call
+        main(argv, stdout: out, stderr: err)
+      end
+
+      module SharedOptions
+        def self.included(base)
+          base.option :root, value: {type: String, usage: "PATH"}, desc: "Workspace or family root"
+          base.option :config, value: {type: String, usage: "PATH"}, desc: "Family config path"
+          base.option :json, desc: "Print JSON report to stdout"
+          base.option :report, value: {type: String, usage: "PATH"}, desc: "Write JSON report to PATH"
+        end
+      end
+
+      module SelectionOptions
+        def self.included(base)
+          base.option :only, value: {type: String, usage: "MEMBERS"}, desc: "Select comma-separated members"
+          base.option :exclude, value: {type: String, usage: "MEMBERS"}, desc: "Exclude comma-separated members"
+          base.option :start_at, long: "--start-at", value: {type: String, usage: "MEMBER[@BRANCH]"}, desc: "Select from member through the end of order"
+        end
+      end
+
+      module ExecutionOptions
+        def self.included(base)
+          base.option :execute, desc: "Execute external workflow commands"
+          base.option :dry_run, long: "--dry-run", desc: "Plan external workflow commands without running them" do
+            options[:execute] = false
+          end
+        end
+      end
+
+      module CommitOptions
+        def self.included(base)
+          base.option :commit, desc: "Allow workflow commands that change files to commit"
+          base.option :no_commit, long: "--no-commit", desc: "Skip automatic commits after mutating workflow commands" do
+            options[:commit] = false
+          end
+          base.option :allow_dirty, long: "--allow-dirty", desc: "Reserved for compatibility; member repos manage their own commit safety"
+        end
+      end
+
+      module WorkflowOptions
+        def self.included(base)
+          base.option :debug, desc: "Preserve debug environment for workflow commands"
+          base.option :jobs, value: {type: Integer, usage: "N"}, desc: "Parallel jobs for supported executed workflows"
+          base.option :env, value: {type: String, usage: "KEY=VALUE"}, desc: "Override an environment variable for each member workflow command" do |value|
+            parse_env_override(value, workflow_env)
+          end
+        end
+      end
+
+      module ReturningMain
+        def main(argv = [])
+          args = parse_options(argv)
+          return 1 unless valid_argument_count?(args)
+
+          run(*args)
+        rescue SystemExit => error
+          error.status
+        rescue Error, OptionParser::ParseError => error
+          stderr.puts("kettle-family: #{error.message}")
+          1
+        end
+
+        private
+
+        def valid_argument_count?(args)
+          required_args = self.class.arguments.each_value.count(&:required?)
+          optional_args = self.class.arguments.each_value.count(&:optional?)
+          has_repeats_arg = self.class.arguments.each_value.any?(&:repeats?)
+          return true if args.length >= required_args && (has_repeats_arg || args.length <= (required_args + optional_args))
+
+          message = if args.length < required_args
+            "insufficient number of arguments"
+          else
+            "unexpected argument(s): #{args[(required_args + optional_args)..].join(" ")}"
+          end
+          stderr.puts("kettle-family: #{message}")
+          help_usage
+          false
+        end
+
+        def on_parse_error(error)
+          raise error
+        end
+      end
+
+      class BaseCommand < CommandKit::Command
+        prepend ReturningMain
+
+        include SharedOptions
+        include SelectionOptions
+
+        def initialize(**kwargs)
+          super
+          @workflow_env = {}
+        end
+
+        private
+
+        attr_reader :workflow_env
+
+        def family_options(overrides = {})
+          {
+            root: options[:root] || Dir.pwd,
+            config: options[:config],
+            only: options[:only],
+            exclude: options[:exclude],
+            start_at: options[:start_at],
+            json: truthy_option?(:json),
+            report: options[:report],
+            execute: truthy_option?(:execute),
+            debug: truthy_option?(:debug),
+            jobs: options[:jobs],
+            workflow_env: workflow_env,
+            changelog_section: nil,
+            changelog_entry: nil,
+            check: truthy_option?(:check),
+            from_version: nil,
+            gha_sha_pins_upgrade: "patch",
+            publish: false,
+            release_start_step: nil,
+            release_skip_steps: nil,
+            release_local_ci: false,
+            release_continue_ci_failures: false,
+            accept: true,
+            tag: false,
+            push: false,
+            commit: !options.key?(:commit) || options[:commit],
+            allow_dirty: truthy_option?(:allow_dirty),
+            target_version: nil,
+            bup_args: [],
+            bex_args: []
+          }.merge(overrides)
+        end
+
+        def run_family(command, overrides = {})
+          Kettle::Family::CLI.new(stdout: stdout, stderr: stderr).run_command(command, family_options(overrides))
+        end
+
+        def truthy_option?(name)
+          options.key?(name) && !!options[name]
+        end
+
+        def parse_env_override(value, env)
+          key, env_value = value.split("=", 2)
+          raise OptionParser::InvalidArgument, "--env requires KEY=VALUE" if key.to_s.empty? || env_value.nil?
+          raise OptionParser::InvalidArgument, "invalid environment variable name #{key.inspect}" unless key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+
+          env[key] = env_value
+        end
+
+        def parse_gha_sha_pins_upgrade(value)
+          normalized = value.to_s.downcase
+          return normalized if %w[major minor patch].include?(normalized)
+
+          raise OptionParser::InvalidArgument, "--upgrade must be one of: major, minor, patch"
+        end
+
+        def unexpected_arguments!(args)
+          raise OptionParser::InvalidArgument, "unexpected argument(s): #{args.join(" ")}" unless args.empty?
+        end
+      end
+
+      class Discover < BaseCommand
+        command_name "discover"
+        usage "[options]"
+        description "Discover family members and print selected order."
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family("discover")
+        end
+      end
+
+      class Plan < Discover
+        command_name "plan"
+        description "Alias for discover while execution workflows are built."
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family("plan")
+        end
+      end
+
+      class ReportCommand < Discover
+        command_name "report"
+        description "Print family discovery and configuration report."
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family("report")
+        end
+      end
+
+      class Metadata < BaseCommand
+        command_name "metadata"
+        usage "[options]"
+        description "Print version, Ruby floor, license, and author metadata."
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family("metadata")
+        end
+      end
+
+      class BranchLanes < BaseCommand
+        command_name "branch-lanes"
+        usage "[options]"
+        description "Audit configured branch lanes."
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family("branch-lanes")
+        end
+      end
+
+      class ReleaseState < BaseCommand
+        command_name "release-state"
+        usage "[options]"
+        description "Report changelog release state for family members."
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family("release-state")
+        end
+      end
+
+      class WorkflowCommand < BaseCommand
+        include ExecutionOptions
+        include WorkflowOptions
+        include CommitOptions
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family(self.class.command_name)
+        end
+      end
+
+      class Check < WorkflowCommand
+        command_name "check"
+        usage "[options]"
+        description "Run internal read-only readiness checks."
+      end
+
+      class Test < WorkflowCommand
+        command_name "test"
+        usage "[options]"
+        description "Plan or execute configured test command per member."
+      end
+
+      class Lint < WorkflowCommand
+        command_name "lint"
+        usage "[options]"
+        description "Plan or execute configured lint command per member."
+      end
+
+      class Docs < WorkflowCommand
+        command_name "docs"
+        usage "[options]"
+        description "Plan or execute configured docs command per member."
+      end
+
+      class Template < WorkflowCommand
+        command_name "template"
+        usage "[options]"
+        description "Plan or execute kettle-jem templating per member."
+      end
+
+      class GhaShaPins < WorkflowCommand
+        command_name "gha-sha-pins"
+        usage "[options]"
+        description "Plan or execute kettle-gha-sha-pins per member."
+
+        option :check, desc: "Check whether SHA pins would need edits"
+        option :upgrade, value: {type: String, usage: "LEVEL"}, desc: "SHA pin upgrade strategy: major, minor, patch" do |value|
+          options[:upgrade] = parse_gha_sha_pins_upgrade(value)
+        end
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family("gha-sha-pins", gha_sha_pins_upgrade: options[:upgrade] || "patch")
+        end
+      end
+
+      class Bup < WorkflowCommand
+        command_name "bup"
+        usage "[options] [GEM]"
+        description "Plan or execute bundle update --all, or bundle update GEM."
+        argument :gems, required: false, repeats: true, usage: "GEM", desc: "Gem name(s) to update"
+
+        def run(*bup_args)
+          run_family("bup", bup_args: bup_args)
+        end
+      end
+
+      class Bupb < WorkflowCommand
+        command_name "bupb"
+        usage "[options]"
+        description "Plan or execute bundle update --bundler."
+      end
+
+      class Bex < WorkflowCommand
+        command_name "bex"
+        usage "[options] -- COMMAND [ARGS...]"
+        description "Plan or execute bundle exec COMMAND per member."
+        argument :command, required: false, repeats: true, usage: "COMMAND [ARGS...]", desc: "Command and arguments to run through bundle exec"
+
+        def run(*bex_args)
+          raise Error, "bex requires COMMAND [ARGS]" if bex_args.empty?
+
+          run_family("bex", bex_args: bex_args)
+        end
+      end
+
+      class Install < BaseCommand
+        include ExecutionOptions
+
+        command_name "install"
+        usage "[options]"
+        description "Build and install selected local family gems."
+
+        option :jobs, value: {type: Integer, usage: "N"}, desc: "Parallel jobs for executed installs"
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family("install")
+        end
+      end
+
+      class BumpVersion < BaseCommand
+        include ExecutionOptions
+        include CommitOptions
+
+        command_name "bump-version"
+        usage "[options] VERSION|major|minor|patch|pre"
+        description "Check, plan, or execute family version alignment."
+        argument :target_version, required: false, usage: "VERSION|major|minor|patch|pre", desc: "Version or bump target"
+
+        option :check, desc: "Check whether version bumps would need edits"
+        option :from, value: {type: String, usage: "VERSION"}, desc: "Require selected members to currently match VERSION"
+
+        def run(target_version = nil)
+          raise Error, "bump-version requires VERSION, major, minor, patch, or pre" unless target_version
+
+          run_family("bump-version", target_version: target_version, from_version: options[:from])
+        end
       end
 
-      def initialize(argv, out:, err:)
-        @argv = argv.dup
-        @out = out
-        @err = err
+      class AddChangelog < BaseCommand
+        include ExecutionOptions
+
+        command_name "add-changelog"
+        usage "[options]"
+        description "Add an entry to an existing Unreleased changelog section."
+
+        option :section, value: {type: String, usage: "NAME"}, desc: "Changelog section"
+        option :entry, value: {type: String, usage: "TEXT"}, desc: "Changelog entry"
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family("add-changelog", changelog_section: options[:section], changelog_entry: options[:entry])
+        end
       end
 
-      def call
-        command = argv.shift || "help"
-        return help if command == "help" || command == "--help" || command == "-h"
+      class Release < BaseCommand
+        include ExecutionOptions
+        include WorkflowOptions
+        include CommitOptions
 
-        raise Error, "unknown command #{command.inspect}" unless COMMANDS.include?(command)
+        command_name "release"
+        usage "[options]"
+        description "Plan or execute release build/publish phases."
 
-        target_version = argv.shift if command == "bump-version"
-        raise Error, "bump-version requires VERSION, major, minor, patch, or pre" if command == "bump-version" && !target_version
-        bup_args = parse_bup_args(command)
-        bex_args = parse_bex_args_with_separator(command)
+        option :publish, desc: "Use publish release command instead of build command"
+        option :build_only, long: "--build-only", desc: "Use build release command" do
+          options[:publish] = false
+        end
+        option :start_step, long: "--start-step", value: {type: Integer, usage: "N"}, desc: "Pass start_step=N through to kettle-release commands"
+        option :skip_steps, long: "--skip-steps", value: {type: String, usage: "LIST"}, desc: "Pass skip_steps=LIST through to kettle-release commands"
+        option :local_ci, long: "--local-ci", desc: "Pass --local-ci through to kettle-release commands"
+        option :continue_ci_failures, long: "--continue-ci-failures", desc: "Set K_RELEASE_CI_CONTINUE=true for release commands"
+        option :accept, desc: "Answer yes to confirmation prompts in interactive commands"
+        option :no_accept, long: "--no-accept", desc: "Wait for user input at confirmation prompts" do
+          options[:accept] = false
+        end
+        option :tag, desc: "Add release tag phase"
+        option :push, desc: "Add release push phase"
+
+        def run(*args)
+          unexpected_arguments!(args)
+          run_family(
+            "release",
+            publish: truthy_option?(:publish),
+            release_start_step: options[:start_step],
+            release_skip_steps: options[:skip_steps],
+            release_local_ci: truthy_option?(:local_ci),
+            release_continue_ci_failures: truthy_option?(:continue_ci_failures),
+            accept: !options.key?(:accept) || options[:accept],
+            tag: truthy_option?(:tag),
+            push: truthy_option?(:push)
+          )
+        end
+      end
 
-        options = parse_options(allow_remainder: command == "bex" && bex_args.empty?)
-        bex_args = argv.shift(argv.length) if command == "bex" && bex_args.empty?
-        raise Error, "bex requires COMMAND [ARGS]" if command == "bex" && bex_args.empty?
+      class Push < WorkflowCommand
+        command_name "push"
+        usage "[options]"
+        description "Plan or execute git push per member."
+      end
+
+      class Pull < WorkflowCommand
+        command_name "pull"
+        usage "[options]"
+        description "Plan or execute git pull --rebase per member."
+      end
+
+      class Up < WorkflowCommand
+        command_name "up"
+        usage "[options]"
+        description "Plan or execute git pull --rebase then git push per member."
+      end
+
+      command Discover
+      command Plan
+      command "report", ReportCommand
+      command Metadata
+      command Check
+      command Test
+      command Lint
+      command Docs
+      command Template
+      command GhaShaPins
+      command Bup
+      command Bupb
+      command Bex
+      command Install
+      command BumpVersion
+      command AddChangelog
+      command Release
+      command Push
+      command Pull
+      command Up
+      command BranchLanes
+      command ReleaseState
+
+      prepend ReturningMain
+
+      def run(command = nil, *argv)
+        return invoke(command, *argv) if command
+
+        help
+        0
+      end
 
-        options[:target_version] = target_version
-        options[:bup_args] = bup_args
-        options[:bex_args] = bex_args
-        return help if options.delete(:help)
+      def on_unknown_command(name, _argv = [])
+        stderr.puts("kettle-family: unknown command #{name.inspect}")
+        1
+      end
 
+      def run_command(command, options)
         report = build_report(command, options)
         write_report(report, options)
-        out.puts(options[:json] ? report.to_json : report.to_text)
+        stdout.puts(options[:json] ? report.to_json : report.to_text)
         report.success? ? 0 : 1
       rescue Error, OptionParser::ParseError => error
-        err.puts("kettle-family: #{error.message}")
+        stderr.puts("kettle-family: #{error.message}")
         1
       end
 
       private
 
-      attr_reader :argv, :out, :err
-
-      def help
-        out.puts(<<~HELP)
-          kettle-family: #{Kettle::Family::VERSION}
-
-          Usage: kettle-family COMMAND [options]
-                 kettle-family bump-version VERSION|major|minor|patch|pre [options]
-                 kettle-family bup [GEM] [options]
-                 kettle-family bex [options] -- COMMAND [ARGS]
-
-          Commands:
-              discover        Discover family members and print selected order
-              plan            Alias for discover while execution workflows are built
-              report          Print family discovery and configuration report
-              metadata        Print version, Ruby floor, license, and author metadata
-              check           Run internal read-only readiness checks
-              test            Plan or execute configured test command per member
-              lint            Plan or execute configured lint command per member
-              docs            Plan or execute configured docs command per member
-              template        Plan or execute kettle-jem templating per member
-              gha-sha-pins    Plan or execute kettle-gha-sha-pins per member
-              bup             Plan or execute bundle update --all, or bundle update GEM
-              bupb            Plan or execute bundle update --bundler
-              bex             Plan or execute bundle exec COMMAND per member
-              install         Build and install selected local family gems
-              bump-version    Check, plan, or execute family version alignment
-              add-changelog   Add an entry to an existing Unreleased changelog section
-              release         Plan or execute release build/publish phases
-              push            Plan or execute git push per member
-              pull            Plan or execute git pull --rebase per member
-              up              Plan or execute git pull --rebase then git push per member
-              release-state   Report changelog release state for family members
-
-          Options:
-              --root PATH      Workspace or family root (default: current directory)
-              --config PATH    Family config path
-              --only MEMBERS   Select comma-separated members
-              --start-at NAME  Select from member through the end of order; use MEMBER@BRANCH for branch stacks
-              --json           Print JSON report to stdout
-              --report PATH    Write JSON report to PATH
-              --execute        Execute external workflow commands
-              --dry-run        Plan external workflow commands without running them (default)
-              --debug          Preserve debug environment for workflow commands
-              --jobs N         Parallel jobs for executed family templating, release, or install
-              --env KEY=VALUE  Override an environment variable for each member workflow command
-              --section NAME   Changelog section for add-changelog
-              --entry TEXT     Changelog entry for add-changelog
-              --check          Check whether bump-version or gha-sha-pins would need edits
-              --from VERSION   Require selected members to currently match VERSION
-              --upgrade LEVEL  GitHub Actions SHA pin upgrade strategy: major, minor, patch
-              --publish        Use publish release command instead of build command
-              --build-only      Use build release command (default)
-              --start-step N    Pass start_step=N through to kettle-release commands
-              --skip-steps LIST Pass skip_steps=LIST through to kettle-release commands
-              --local-ci        Pass --local-ci through to kettle-release commands
-              --continue-ci-failures
-                               Set K_RELEASE_CI_CONTINUE=true for release commands
-              --accept         Answer yes to confirmation prompts in interactive commands (default)
-              --no-accept      Wait for user input at confirmation prompts
-              --tag            Add release tag phase
-              --push           Add release push phase
-              --commit         Allow workflow commands that change files to commit (default)
-              --no-commit      Skip automatic commits after mutating workflow commands
-              --allow-dirty    Reserved for compatibility; member repos manage their own commit safety
-              --help           Print this help
-        HELP
-        0
-      end
-
-      def parse_options(allow_remainder: false)
-        options = {
-          root: Dir.pwd,
-          config: nil,
-          only: nil,
-          start_at: nil,
-          json: false,
-          report: nil,
-          execute: false,
-          debug: false,
-          jobs: nil,
-          workflow_env: {},
-          changelog_section: nil,
-          changelog_entry: nil,
-          check: false,
-          from_version: nil,
-          gha_sha_pins_upgrade: "patch",
-          publish: false,
-          release_start_step: nil,
-          release_skip_steps: nil,
-          release_local_ci: false,
-          release_continue_ci_failures: false,
-          accept: true,
-          tag: false,
-          push: false,
-          commit: true,
-          allow_dirty: false
-        }
-        OptionParser.new do |parser|
-          parser.on("--root PATH") { |value| options[:root] = value }
-          parser.on("--config PATH") { |value| options[:config] = value }
-          parser.on("--only MEMBER") { |value| options[:only] = value }
-          parser.on("--start-at MEMBER[@BRANCH]") { |value| options[:start_at] = value }
-          parser.on("--json") { options[:json] = true }
-          parser.on("--report PATH") { |value| options[:report] = value }
-          parser.on("--execute") { options[:execute] = true }
-          parser.on("--dry-run") { options[:execute] = false }
-          parser.on("--debug") { options[:debug] = true }
-          parser.on("--jobs N", Integer) { |value| options[:jobs] = value }
-          parser.on("--env KEY=VALUE") { |value| parse_env_override(value, options[:workflow_env]) }
-          parser.on("--section NAME") { |value| options[:changelog_section] = value }
-          parser.on("--entry TEXT") { |value| options[:changelog_entry] = value }
-          parser.on("--check") { options[:check] = true }
-          parser.on("--from VERSION") { |value| options[:from_version] = value }
-          parser.on("--upgrade LEVEL") { |value| options[:gha_sha_pins_upgrade] = parse_gha_sha_pins_upgrade(value) }
-          parser.on("--publish") { options[:publish] = true }
-          parser.on("--build-only") { options[:publish] = false }
-          parser.on("--start-step N", Integer) { |value| options[:release_start_step] = value }
-          parser.on("--skip-steps LIST") { |value| options[:release_skip_steps] = value }
-          parser.on("--local-ci") { options[:release_local_ci] = true }
-          parser.on("--continue-ci-failures") { options[:release_continue_ci_failures] = true }
-          parser.on("--accept") { options[:accept] = true }
-          parser.on("--no-accept") { options[:accept] = false }
-          parser.on("--tag") { options[:tag] = true }
-          parser.on("--push") { options[:push] = true }
-          parser.on("--commit") { options[:commit] = true }
-          parser.on("--no-commit") { options[:commit] = false }
-          parser.on("--allow-dirty") { options[:allow_dirty] = true }
-          parser.on("--help") { options[:help] = true }
-        end.parse!(argv)
-        return options if allow_remainder
-
-        raise OptionParser::InvalidArgument, "unexpected argument(s): #{argv.join(" ")}" unless argv.empty?
-
-        options
-      end
-
       def build_report(command, options)
         config = Config.load(root: options[:root], path: options[:config])
         start_at = parse_start_at(options[:start_at])
@@ -198,12 +504,8 @@ module Kettle
         else
           Orderer.new(members: members, mode: config.order_mode, hints: config.order_hints).ordered
         end
-        selected = Selection.new(members: ordered).apply(only: options[:only], start_at: start_at.member)
-        result_members = if command == "branch-lanes"
-          ordered
-        else
-          selected
-        end
+        selected = Selection.new(members: ordered).apply(only: options[:only], exclude: options[:exclude], start_at: start_at.member)
+        result_members = selected
         results = command_results(command: command, config: config, members: result_members, options: options, start_at: start_at)
         Report.new(
           family_name: config.family_name,
@@ -266,31 +568,12 @@ module Kettle
         ).results
       end
 
-      def parse_bup_args(command)
-        return [] unless command == "bup"
-
-        args = []
-        args << argv.shift while argv.first && !argv.first.start_with?("-")
-        args
-      end
-
-      def parse_bex_args_with_separator(command)
-        return [] unless command == "bex"
-
-        separator_index = argv.index("--")
-        return [] unless separator_index
-
-        args = argv[(separator_index + 1)..] || []
-        argv.slice!(separator_index..)
-        args
-      end
-
       def progress_io(command, options)
         return nil unless command == "template"
         return nil unless options[:execute]
         return nil if options[:json]
 
-        out
+        stdout
       end
 
       def branch_target_command?(command, config)
@@ -380,21 +663,6 @@ module Kettle
         )
       end
 
-      def parse_env_override(value, env)
-        key, env_value = value.split("=", 2)
-        raise OptionParser::InvalidArgument, "--env requires KEY=VALUE" if key.to_s.empty? || env_value.nil?
-        raise OptionParser::InvalidArgument, "invalid environment variable name #{key.inspect}" unless key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
-
-        env[key] = env_value
-      end
-
-      def parse_gha_sha_pins_upgrade(value)
-        normalized = value.to_s.downcase
-        return normalized if %w[major minor patch].include?(normalized)
-
-        raise OptionParser::InvalidArgument, "--upgrade must be one of: major, minor, patch"
-      end
-
       def parse_start_at(value)
         return StartAt.new(nil, nil) unless value
 

data/lib/kettle/family/report.rb

@@ -5,6 +5,26 @@ require "json"
 module Kettle
   module Family
     class Report
+      MEMBER_RESULT_COMMANDS = %w[
+        add-changelog
+        bex
+        bump-version
+        bup
+        bupb
+        check
+        docs
+        gha-sha-pins
+        install
+        lint
+        pull
+        push
+        release
+        release-state
+        template
+        test
+        up
+      ].freeze
+
       attr_reader :family_name, :family_mode, :order_mode, :members, :selected_members, :config_path, :command, :results, :branch_lanes, :release_target_branches, :member_release_target_branches, :release_mode
 
       def initialize(family_name:, order_mode:, members:, selected_members:, config_path:, family_mode: nil, branch_lanes: {}, release_target_branches: [], member_release_target_branches: {}, release_mode: nil, command: nil, results: [])
@@ -36,6 +56,7 @@ module Kettle
           "release_mode" => release_mode,
           "command" => command,
           "results" => results.map(&:to_h),
+          "summary" => summary,
           "resume_hint" => resume_hint
         }
       end
@@ -61,11 +82,12 @@ module Kettle
         end
         append_release_waves(lines)
         append_results(lines)
+        append_summary(lines)
         lines.join("\n")
       end
 
       def success?
-        results.all?(&:ok?)
+        results.all?(&:ok?) && summary_pending.empty?
       end
 
       private
@@ -88,6 +110,32 @@ module Kettle
         append_template_summary(lines) if command == "template"
       end
 
+      def append_summary(lines)
+        data = summary
+        lines << "summary:"
+        lines << "  outcome: #{data.fetch("outcome")}"
+        lines << "  selected: #{data.fetch("selected_count")}"
+        lines << "  results: #{data.fetch("result_count")}"
+        lines << "  succeeded: #{summary_list(data.fetch("succeeded"))}"
+        lines << "  skipped: #{summary_list(data.fetch("skipped"))}"
+        lines << "  failed: #{summary_list(data.fetch("failed").map { |entry| summary_entry(entry) })}"
+        lines << "  pending: #{summary_list(data.fetch("pending").map { |entry| summary_entry(entry) })}"
+        lines << "  resume: #{data.fetch("resume_hint")}" if data.fetch("resume_hint")
+      end
+
+      def summary
+        {
+          "outcome" => success? ? "success" : "failure",
+          "selected_count" => selected_members.length,
+          "result_count" => visible_results.length,
+          "succeeded" => summary_succeeded,
+          "skipped" => summary_skipped,
+          "failed" => summary_failed,
+          "pending" => summary_pending,
+          "resume_hint" => resume_hint
+        }
+      end
+
       def append_release_waves(lines)
         wave_results = results.select { |result| release_wave_result?(result) }
         return if wave_results.empty?
@@ -102,6 +150,10 @@ module Kettle
         result.phase == "release_wave"
       end
 
+      def visible_results
+        results.reject { |result| release_wave_result?(result) }
+      end
+
       def append_indented_output(lines, output)
         output.to_s.each_line(chomp: true) { |line| lines << "    #{line}" }
       end
@@ -146,6 +198,85 @@ module Kettle
         "failed"
       end
 
+      def member_result_command?
+        MEMBER_RESULT_COMMANDS.include?(command)
+      end
+
+      def selected_names
+        selected_members.map(&:name)
+      end
+
+      def selected_member_results
+        return {} unless member_result_command?
+
+        visible_results.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |result, memo|
+          next unless selected_names.include?(result.member_name)
+
+          memo[result.member_name] << result
+        end
+      end
+
+      def summary_succeeded
+        selected_member_results.filter_map do |member_name, member_results|
+          next if member_results.empty?
+          next if member_results.any? { |result| !result.ok? }
+          next if member_results.all?(&:skipped)
+
+          member_name
+        end
+      end
+
+      def summary_skipped
+        selected_member_results.filter_map do |member_name, member_results|
+          next if member_results.empty?
+          next unless member_results.all?(&:skipped)
+
+          member_name
+        end
+      end
+
+      def summary_failed
+        visible_results.reject(&:ok?).map do |result|
+          {
+            "member" => result.member_name,
+            "phase" => result.phase,
+            "reason" => result.reason || "command failed"
+          }
+        end
+      end
+
+      def summary_pending
+        return [] unless member_result_command?
+        return [] if visible_results.empty?
+
+        ran = selected_member_results.keys
+        reason = pending_reason
+        (selected_names - ran).map do |member_name|
+          {
+            "member" => member_name,
+            "phase" => command,
+            "reason" => reason
+          }
+        end
+      end
+
+      def pending_reason
+        if visible_results.any? { |result| !result.ok? }
+          "not run after earlier failure"
+        else
+          "no command result recorded"
+        end
+      end
+
+      def summary_list(values)
+        values.empty? ? "none" : values.join(", ")
+      end
+
+      def summary_entry(entry)
+        reason = entry.fetch("reason")
+        "#{entry.fetch("member")} #{entry.fetch("phase")} (#{reason})"
+      end
+
       def append_metadata_results(lines)
         lines << "metadata:"
         rows = [["gem", "version", "ruby", "licenses", "authors"]]

data/lib/kettle/family/selection.rb

@@ -7,9 +7,10 @@ module Kettle
         @members = members
       end
 
-      def apply(only: nil, start_at: nil)
+      def apply(only: nil, exclude: nil, start_at: nil)
         selected = members
         selected = select_only(selected, only) if only
+        selected = select_exclude(selected, exclude) if exclude
         selected = select_start_at(selected, start_at) if start_at
         raise Error, "selection is empty" if selected.empty?
 
@@ -30,6 +31,16 @@ module Kettle
         selected.select { |candidate| names.include?(candidate.name) }
       end
 
+      def select_exclude(selected, exclude)
+        names = exclude.split(",").map(&:strip).reject(&:empty?)
+        raise Error, "--exclude requires at least one member" if names.empty?
+
+        unknown = names - members.map(&:name)
+        raise Error, "unknown member(s): #{unknown.join(", ")}" unless unknown.empty?
+
+        selected.reject { |candidate| names.include?(candidate.name) }
+      end
+
       def select_start_at(selected, start_at)
         index = selected.index { |candidate| candidate.name == start_at }
         raise Error, "unknown member #{start_at.inspect}" unless index

data/lib/kettle/family/version.rb

@@ -3,7 +3,7 @@
 module Kettle
   module Family
     module Version
-      VERSION = "0.1.31"
+      VERSION = "0.1.32"
     end
     VERSION = Version::VERSION # Traditional Constant Location
   end

data/lib/kettle/family/workflow.rb

@@ -394,11 +394,18 @@ module Kettle
       end
 
       def release_jobs(release_members)
+        # TruffleRuby issue: https://github.com/truffleruby/truffleruby/issues/4352
+        return 1 if truffleruby?
+
         requested = jobs || config.release_jobs
         count = requested ? requested.to_i : [Etc.nprocessors, 4].min
         count.clamp(1, release_members.length)
       end
 
+      def truffleruby?
+        RUBY_ENGINE == "truffleruby"
+      end
+
       def release_waves(release_members)
         by_name = release_members.to_h { |member| [member.name, member] }
         pending = by_name.keys

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-family
 version: !ruby/object:Gem::Version
-  version: 0.1.31
+  version: 0.1.32
 platform: ruby
 authors:
 - Peter H. Boling
@@ -37,6 +37,34 @@ cert_chain:
   -----END CERTIFICATE-----
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: command_kit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: command_kit-completion
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: tsort
   requirement: !ruby/object:Gem::Requirement
@@ -311,10 +339,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/v0.1.31
-  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v0.1.31/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v0.1.32
+  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v0.1.32/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-family/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-family/0.1.31
+  documentation_uri: https://www.rubydoc.info/gems/kettle-family/0.1.32
   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