ace-support-cli 0.6.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5f90e1991953f285459a32cb147c449db7e0e8156962690106734d1260fbee56
+  data.tar.gz: c974cdf497c7b6885a3a5cd29dce34cf531b0b4f257dd249012382e42c478e90
+SHA512:
+  metadata.gz: 192b5345131894c1c0bd44bbb53887411361eadba6d82d8306e3fb15cb1bc0b7b2df34433ea29dfb51f40963e9be7764c3ecec1a2827d35a91421b2701131a1c
+  data.tar.gz: 90954c90d0cdeb4984ba8bc9fc8a5ba047b2b01f9ab39bf295d5713b6f31c907f888629fe10bbd223b4dbdaa22164163bc7130b521e279b8760b5676fa174fad

data/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.6.2] - 2026-03-22
+
+### Technical
+- Removed trailing blank lines in README code fences for installation and basic usage examples.
+
+## [0.6.1] - 2026-03-22
+
+### Changed
+- Expanded the README with a clear package tagline, installation guidance, runnable basic usage example, API overview, and Part of ACE footer.
+
+## [0.6.0] - 2026-03-18
+
+### Added
+- Moved `Error`, `Base`, `StandardOptions`, and `RegistryDsl` classes from ace-support-core into ace-support-cli as their canonical home.
+- Added `.module(gem_name:, version:)` factory to `VersionCommand` for dynamic version display modules.
+- Added `argument :args` to `HelpCommand` for accepting trailing arguments.
+
+### Changed
+- Runner now raises `Ace::Support::Cli::Error` directly instead of bridging through `Ace::Core::CLI::Error`.
+
+## [0.5.1] - 2026-03-17
+
+### Fixed
+- Restored compatibility for repeated scalar options, `key=value` hash options, and `--` passthrough handling so migrated ACE CLIs preserve existing argument semantics.
+- Normalized help and command resolution behavior: top-level help now renders without raw command lookup failures, rich help no longer exits the process directly, and usage rendering supports real ACE registry metadata shapes.
+- Fixed the public `ArgvCoalescer` contract by loading it from the top-level entrypoint and aligning the canonical constant name with the file path while keeping the legacy alias available.
+
+## [0.5.0] - 2026-03-17
+
+### Added
+- Rich `--help` interception in Parser: commands with `desc` or `examples` metadata now render structured help (NAME, USAGE, DESCRIPTION, OPTIONS, EXAMPLES) via the existing Banner/Concise/TwoTierHelp formatters instead of OptionParser's bare-bones output.
+- Runner passes computed command name (e.g., `ace-task show`) to Parser for accurate help rendering.
+- `PROGRAM_NAME` constant lookup on registry modules for correct program name resolution.
+
+## [0.4.0] - 2026-03-15
+
+### Added
+- Runner improvements: enhanced command runner lifecycle with better error propagation and exit code handling
+- Registry DSL support: added declarative registry definition helpers for cleaner command registration
+- Parse error re-raising: parse errors now propagate with structured context for downstream error handling
+
+### Changed
+- Removed runtime dependency on `ace-support-core` to avoid circular dependency during support-core CLI migration.
+
+## [0.3.0] - 2026-03-14
+
+### Added
+- Added a native help subsystem with full banner rendering, concise `-h` rendering, registry usage rendering, and two-tier help dispatch helpers.
+- Added `HelpCommand` and `VersionCommand` factory modules in `Ace::Support::Cli`.
+- Added focused tests for help rendering and dispatch behavior.
+
+## [0.2.0] - 2026-03-13
+
+### Added
+- Initial `ace-support-cli` gem scaffold with core command/parsing/runtime classes.

data/LICENSE

@@ -0,0 +1 @@
+MIT License

data/README.md

@@ -0,0 +1,35 @@
+<div align="center">
+  <h1> ACE - Support CLI </h1>
+
+  Shared command primitives for consistent ACE CLI behavior.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-support-cli"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-support-cli.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+`ace-support-cli` is the foundation layer for ACE commands, providing metadata-driven command definitions, parser behavior, and execution orchestration. Packages like [ace-llm](../ace-llm), [ace-review](../ace-review), and [ace-search](../ace-search) build their CLI surfaces on top of these shared primitives.
+
+## How It Works
+
+1. Package commands extend shared `Command` base classes and define arguments/options declaratively.
+2. Parsers normalize argv into structured Ruby types and route to a command registry.
+3. Runners execute command objects with consistent help, error, and exit semantics.
+
+## Use Cases
+
+**Build a new ACE CLI tool quickly** - reuse shared conventions for command declaration, option parsing, and execution so new packages like [ace-retro](../ace-retro) or [ace-sim](../ace-sim) get consistent behavior from day one.
+
+**Standardize command behavior across packages** - enforce predictable option parsing, help text, and exit codes for both human and agent callers.
+
+**Keep agent invocations safe** - preserve a stable CLI contract so coding agents can call `ace-*` tools reliably in mixed human/agent workflows.
+
+---
+
+Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/exe/ace-support-cli

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+puts "ace-support-cli #{Ace::Support::Cli::VERSION}"

data/lib/ace/support/cli/argv_coalescer.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      module ArgvCoalescer
+        def self.call(argv, flags:, separator: ",")
+          normalized = normalize_flags(flags)
+          accum = normalized.values.to_h { |canonical| [canonical, []] }
+          passthrough = []
+
+          i = 0
+          while i < argv.length
+            token = argv[i]
+            flag = token.include?("=") ? token.split("=", 2)[0] : token
+            canonical = normalized[flag]
+
+            if canonical
+              value = extract_value(token, argv, i)
+              accum[canonical] << value unless value.to_s.empty?
+              i = next_index(token, argv, i)
+            else
+              passthrough << token
+              i += 1
+            end
+          end
+
+          result = passthrough.dup
+          accum.each do |canonical, values|
+            next if values.empty?
+
+            result << canonical
+            result << values.join(separator)
+          end
+          result
+        end
+
+        def self.normalize_flags(flags)
+          flags.each_with_object({}) do |(canonical, aliases), memo|
+            memo[canonical] = canonical
+            aliases.each { |entry| memo[entry] = canonical }
+          end
+        end
+        private_class_method :normalize_flags
+
+        def self.extract_value(token, argv, index)
+          return token.split("=", 2)[1] if token.include?("=")
+          return argv[index + 1] if index + 1 < argv.length && !argv[index + 1].start_with?("-")
+
+          ""
+        end
+        private_class_method :extract_value
+
+        def self.next_index(token, argv, index)
+          return index + 1 if token.include?("=")
+          return index + 2 if index + 1 < argv.length && !argv[index + 1].start_with?("-")
+
+          index + 1
+        end
+        private_class_method :next_index
+      end
+
+      ArgvCollector = ArgvCoalescer
+    end
+  end
+end

data/lib/ace/support/cli/base.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "standard_options"
+
+module Ace
+  module Support
+    module Cli
+      # Shared CLI helper methods and option constants used across ACE commands.
+      module Base
+        STANDARD_OPTIONS = %i[quiet verbose debug].freeze
+        RESERVED_FLAGS = %i[h v q d o].freeze
+
+        def verbose?(options)
+          options[:verbose] == true
+        end
+
+        def quiet?(options)
+          options[:quiet] == true
+        end
+
+        def debug?(options)
+          options[:debug] == true
+        end
+
+        def help?(options)
+          options[:help] == true || options[:h] == true
+        end
+
+        def debug_log(message, options)
+          warn "DEBUG: #{message}" if debug?(options)
+        end
+
+        def raise_cli_error(message, exit_code: 1)
+          raise Ace::Support::Cli::Error.new(message, exit_code: exit_code)
+        end
+
+        def validate_required!(options, *required)
+          missing = required - options.keys.select { |key| !options[key].nil? }
+          return if missing.empty?
+
+          raise ArgumentError, "Missing required options: #{missing.join(", ")}"
+        end
+
+        def format_pairs(hash)
+          hash.map { |key, value| "#{key}=#{value}" }.join(" ")
+        end
+
+        # Type coercion for CLI option values.
+        def coerce_types(options, conversions)
+          conversions.each do |key, type|
+            next if options[key].nil?
+
+            case type
+            when :integer
+              begin
+                options[key] = Integer(options[key])
+              rescue ArgumentError, TypeError
+                raise ArgumentError, "Invalid value for --#{key.to_s.tr("_", "-")}: " \
+                                     "'#{options[key]}' is not a valid integer"
+              end
+            when :float
+              begin
+                options[key] = Float(options[key])
+              rescue ArgumentError, TypeError
+                raise ArgumentError, "Invalid value for --#{key.to_s.tr("_", "-")}: " \
+                                     "'#{options[key]}' is not a valid number"
+              end
+            end
+          end
+          options
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/cli/command.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "models/option"
+require_relative "models/argument"
+
+module Ace
+  module Support
+    module Cli
+      class Command
+        class << self
+          attr_reader :description
+
+          def inherited(subclass)
+            super
+            subclass.instance_variable_set(:@description, description)
+            subclass.instance_variable_set(:@options, options.dup)
+            subclass.instance_variable_set(:@arguments, arguments.dup)
+            subclass.instance_variable_set(:@examples, examples.dup)
+          end
+
+          def desc(text)
+            @description = text
+          end
+
+          def option(name, type: :string, default: nil, desc: "", aliases: [], values: nil, required: false, repeat: false, **_extra)
+            @options ||= []
+            @options << Models::Option.new(
+              name: name,
+              type: type,
+              default: default,
+              desc: desc,
+              aliases: aliases,
+              values: values,
+              required: required,
+              repeat: repeat
+            )
+          end
+
+          def argument(name, type: :string, required: true, desc: "")
+            @arguments ||= []
+            @arguments << Models::Argument.new(name: name, type: type, required: required, desc: desc)
+          end
+
+          def example(lines)
+            @examples ||= []
+            @examples.concat(Array(lines).map(&:to_s))
+          end
+
+          def options
+            @options ||= []
+          end
+
+          def arguments
+            @arguments ||= []
+          end
+
+          def examples
+            @examples ||= []
+          end
+        end
+
+        def call(**_params)
+          raise NotImplementedError, "#{self.class} must implement #call"
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/cli/error.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      # Exception raised to signal non-zero exit code from CLI commands.
+      #
+      # This exception is used in the exception-based exit code pattern
+      # defined in ADR-023. Commands raise this error on failure, and
+      # the exe wrapper catches it and exits with the specified code.
+      #
+      # @example Raising from a command
+      #   def call(file:, **options)
+      #     raise Error.new("file required") if file.nil?
+      #
+      #     result = do_work(file)
+      #
+      #     if result[:success]
+      #       puts result[:message]
+      #       # Success - no exception, exits 0
+      #     else
+      #       raise Error.new(result[:error])
+      #     end
+      #   end
+      #
+      # @example Catching in exe wrapper
+      #   # exe/ace-gem
+      #   begin
+      #     Ace::Gem::CLI.start(ARGV)
+      #   rescue Ace::Support::Cli::Error => e
+      #     warn e.message
+      #     exit(e.exit_code)
+      #   end
+      #
+      # @see ADR-023 CLI framework conventions
+      class Error < StandardError
+        # Exit code to return when this exception is caught
+        # @return [Integer]
+        attr_reader :exit_code
+
+        # Original error message without prefix
+        # @return [String]
+        attr_reader :original_message
+
+        # Initialize a new CLI error
+        #
+        # @param message [String] Error message to display
+        # @param exit_code [Integer] Exit code (default: 1)
+        def initialize(message, exit_code: 1)
+          @original_message = message
+          super(message)
+          @exit_code = exit_code
+        end
+
+        # Return the original message without prefix.
+        # This ensures .message returns what was passed to the constructor.
+        # @return [String] Original message
+        def message
+          @original_message
+        end
+
+        # Prepend "Error: " to message for consistent user-facing output.
+        # exe wrappers use warn e.to_s which calls this method.
+        # @return [String] Message with "Error: " prefix
+        def to_s
+          "Error: #{@original_message}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/cli/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      class ParseError < StandardError; end
+      class CommandNotFoundError < StandardError; end
+
+      class HelpRendered < StandardError
+        attr_reader :output, :status
+
+        def initialize(output, status: 0)
+          @output = output
+          @status = status
+          super("Help rendered")
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/cli/help/banner.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      module Help
+        module Banner
+          COLUMN_WIDTH = 34
+
+          def self.call(command, name)
+            [
+              section_name(command, name),
+              section_usage(command, name),
+              section_description(command),
+              section_subcommands(command),
+              section_arguments(command),
+              section_options(command),
+              section_examples(command, name)
+            ].compact.join("\n\n")
+          end
+
+          def self.section_name(command, name)
+            summary = first_line(description(command))
+            line = summary ? "#{name} - #{summary}" : name.to_s
+            "NAME\n  #{line}"
+          end
+
+          def self.section_usage(command, name)
+            usage = "#{name}#{arguments_synopsis(command)}"
+            usage += " [OPTIONS]" if options(command).any?
+            usage += " | #{name} SUBCOMMAND" if subcommands(command).any?
+            "USAGE\n  #{usage}"
+          end
+
+          def self.section_description(command)
+            text = description(command)
+            return nil if text.nil?
+
+            lines = text.to_s.strip.split("\n")
+            return nil if lines.size <= 1
+
+            rest = lines.drop(1).drop_while { |line| line.strip.empty? }
+            return nil if rest.empty?
+
+            "DESCRIPTION\n#{rest.map { |line| "  #{line.strip}" }.join("\n")}"
+          end
+
+          def self.section_subcommands(command)
+            entries = subcommands(command)
+            return nil if entries.empty?
+
+            lines = entries.filter_map do |name, subcommand|
+              next if hidden?(subcommand)
+
+              desc = description(subcommand)
+              "  #{name.to_s.ljust(COLUMN_WIDTH)}#{first_line(desc)}"
+            end
+            return nil if lines.empty?
+
+            "SUBCOMMANDS\n#{lines.join("\n")}"
+          end
+
+          def self.section_arguments(command)
+            args = arguments(command)
+            return nil if args.empty?
+
+            lines = args.map do |arg|
+              label = arg.name.to_s.upcase
+              label = "[#{label}]" unless argument_required?(arg)
+              details = []
+              details << argument_desc(arg) unless argument_desc(arg).to_s.empty?
+              details << "(required)" if argument_required?(arg)
+              "  #{label.ljust(COLUMN_WIDTH)}#{details.join(" ")}"
+            end
+            "ARGUMENTS\n#{lines.join("\n")}"
+          end
+
+          def self.section_options(command)
+            lines = options(command).map { |option| format_option(option) }
+            lines << "  #{"--help, -h".ljust(COLUMN_WIDTH)}Show this help"
+            "OPTIONS\n#{lines.join("\n")}"
+          end
+
+          def self.section_examples(command, name)
+            items = examples(command)
+            return nil if items.empty?
+
+            lines = items.map do |item|
+              cleaned = item.to_s.sub(/\A#{Regexp.escape(name)}\s*/, "")
+              "  $ #{name} #{cleaned}".rstrip
+            end
+            "EXAMPLES\n#{lines.join("\n")}"
+          end
+
+          def self.format_option(option)
+            rendered = option_name(option)
+            rendered = "#{rendered}, #{option_aliases(option).join(", ")}" if option_aliases(option).any?
+            label = "  --#{rendered}"
+
+            details = []
+            desc = option_desc(option)
+            details << desc unless desc.to_s.empty?
+            values = option_values(option)
+            details << "(values: #{Array(values).join(", ")})" if values && !Array(values).empty?
+            default = option_default(option)
+            details << "(default: #{default.inspect})" unless default.nil?
+            details << "(required)" if option_required?(option)
+
+            return label if details.empty?
+
+            "#{label.ljust(COLUMN_WIDTH + 2)}#{details.join(" ")}"
+          end
+
+          def self.option_name(option)
+            name = dasherize(option_name_raw(option))
+            if option_boolean?(option)
+              "[no-]#{name}"
+            elsif option_array?(option)
+              "#{name}=VALUE1,VALUE2,.."
+            elsif option_flag?(option)
+              name
+            else
+              "#{name}=VALUE"
+            end
+          end
+
+          def self.arguments_synopsis(command)
+            required = arguments(command).select { |arg| argument_required?(arg) }.map { |arg| arg.name.to_s.upcase }
+            optional = arguments(command).reject { |arg| argument_required?(arg) }.map { |arg| "[#{arg.name.to_s.upcase}]" }
+            values = required + optional
+            values.empty? ? "" : " #{values.join(" ")}"
+          end
+
+          def self.description(command)
+            command.respond_to?(:description) ? command.description : nil
+          end
+
+          def self.subcommands(command)
+            return [] unless command.respond_to?(:subcommands)
+
+            value = command.subcommands
+            return value.to_a if value.respond_to?(:to_a)
+
+            []
+          end
+
+          def self.hidden?(command)
+            command.respond_to?(:hidden) && command.hidden
+          end
+
+          def self.arguments(command)
+            return command.arguments if command.respond_to?(:arguments)
+            return [] unless command.respond_to?(:required_arguments) && command.respond_to?(:optional_arguments)
+
+            command.required_arguments + command.optional_arguments
+          end
+
+          def self.argument_required?(argument)
+            argument.respond_to?(:required?) ? argument.required? : !!argument.required
+          end
+
+          def self.argument_desc(argument)
+            argument.respond_to?(:desc) ? argument.desc : nil
+          end
+
+          def self.options(command)
+            command.respond_to?(:options) ? command.options : []
+          end
+
+          def self.examples(command)
+            command.respond_to?(:examples) ? command.examples : []
+          end
+
+          def self.option_name_raw(option)
+            return option.name if option.respond_to?(:name)
+            return option.option_name if option.respond_to?(:option_name)
+
+            "option"
+          end
+
+          def self.option_aliases(option)
+            return option.alias_names if option.respond_to?(:alias_names)
+            return option.aliases if option.respond_to?(:aliases)
+
+            []
+          end
+
+          def self.option_desc(option)
+            option.respond_to?(:desc) ? option.desc : nil
+          end
+
+          def self.option_default(option)
+            option.respond_to?(:default) ? option.default : nil
+          end
+
+          def self.option_values(option)
+            option.respond_to?(:values) ? option.values : nil
+          end
+
+          def self.option_required?(option)
+            return option.required if option.respond_to?(:required)
+            return option.required? if option.respond_to?(:required?)
+
+            false
+          end
+
+          def self.option_boolean?(option)
+            return option.boolean? if option.respond_to?(:boolean?)
+
+            option.respond_to?(:type) && option.type.to_sym == :boolean
+          end
+
+          def self.option_array?(option)
+            return option.array? if option.respond_to?(:array?)
+
+            option.respond_to?(:type) && option.type.to_sym == :array
+          end
+
+          def self.option_flag?(option)
+            return option.flag? if option.respond_to?(:flag?)
+
+            false
+          end
+
+          def self.first_line(text)
+            return nil if text.nil?
+
+            text.to_s.strip.split("\n").first&.strip
+          end
+
+          def self.dasherize(value)
+            value.to_s.tr("_", "-")
+          end
+        end
+      end
+    end
+  end
+end