ace-support-cli 0.6.2

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

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "errors"
+
+module Ace
+  module Support
+    module Cli
+      class Parser
+        def initialize(command_class, command_name: nil)
+          @command_class = command_class
+          @command_name = command_name
+        end
+
+        def parse(args)
+          options = build_defaults
+          remaining = args.dup
+
+          if help_requested?(remaining) && rich_help?
+            render_help(remaining)
+          end
+
+          parser = OptionParser.new
+          parser.banner = "Usage: #{File.basename($0)} #{command_label} [options]"
+
+          configure_options(parser, options)
+
+          parser.parse!(remaining)
+
+          apply_positionals(options, remaining)
+          validate_required_options!(options)
+
+          options
+        rescue OptionParser::ParseError => e
+          raise ParseError, parse_error_message(e)
+        rescue ArgumentError => e
+          raise ParseError, e.message
+        end
+
+        private
+
+        attr_reader :command_class
+
+        def help_requested?(args)
+          tokens = tokens_before_separator(args)
+          tokens.include?("--help") || tokens.include?("-h")
+        end
+
+        def rich_help?
+          has_desc = command_class.respond_to?(:description) && !command_class.description.nil?
+          has_examples = command_class.respond_to?(:examples) && !command_class.examples.empty?
+          has_desc || has_examples
+        end
+
+        def render_help(args)
+          name = resolved_command_name
+          output = Ace::Support::Cli::Help::TwoTierHelp.render(command_class, name, args: args)
+          raise HelpRendered.new(output)
+        end
+
+        def tokens_before_separator(args)
+          separator = args.index("--")
+          separator ? args.first(separator) : args
+        end
+
+        def resolved_command_name
+          return @command_name if @command_name && !@command_name.empty?
+
+          program = File.basename($PROGRAM_NAME)
+          label = command_label
+          (label == "command") ? program : "#{program} #{label}"
+        end
+
+        def build_defaults
+          command_class.options.each_with_object({}) do |option, hash|
+            hash[option.name] = duplicate_default(option.default)
+          end
+        end
+
+        def duplicate_default(value)
+          case value
+          when Array then value.dup
+          when Hash then value.dup
+          else value
+          end
+        end
+
+        def configure_options(parser, options)
+          command_class.options.each do |option|
+            desc = option.desc.to_s
+
+            case option.type
+            when :boolean
+              parser.on(*option.aliases, "--[no-]#{option.name.to_s.tr("_", "-")}", desc) do |value|
+                options[option.name] = value
+              end
+            when :integer
+              switches = value_switches(option, "N")
+              parser.on(*switches, Integer, desc) { |value| assign_option_value(options, option, value) }
+            when :float
+              switches = value_switches(option, "N")
+              parser.on(*switches, Float, desc) { |value| assign_option_value(options, option, value) }
+            when :array
+              switches = value_switches(option, "A,B")
+              parser.on(*switches, Array, desc) do |value|
+                current = Array(options[option.name])
+                parsed_values = value.nil? ? [] : Array(value)
+                options[option.name] = current + parsed_values
+              end
+            when :hash
+              switches = value_switches(option, "KEY=VALUE")
+              parser.on(*switches, String, desc) do |value|
+                key, parsed_value = parse_hash_pair(value, option)
+                current = options[option.name] || {}
+                options[option.name] = current.merge(key => parsed_value)
+              end
+            else
+              switches = value_switches(option, "VALUE")
+              parser.on(*switches, String, desc) { |value| assign_option_value(options, option, value) }
+            end
+          end
+        end
+
+        def assign_option_value(options, option, value)
+          if option.repeat
+            current = Array(options[option.name])
+            options[option.name] = current + [value]
+          else
+            options[option.name] = value
+          end
+        end
+
+        def value_switches(option, value_label)
+          (option.aliases + [option.long_switch]).map do |switch|
+            "#{switch} #{value_label}"
+          end
+        end
+
+        def parse_hash_pair(value, option)
+          parts = value.split(/[=:]/, 2)
+          raise ArgumentError, "Invalid value for #{option.long_switch}: expected key=value" if parts.length < 2
+
+          parts
+        end
+
+        def apply_positionals(options, remaining)
+          cursor = 0
+          command_class.arguments.each do |argument|
+            if argument.type == :array
+              values = remaining.drop(cursor)
+              if values.empty? && argument.required
+                raise ArgumentError, "Missing required argument: #{argument.name}"
+              end
+
+              options[argument.name] = values
+              cursor = remaining.length
+              break
+            end
+
+            raw_value = remaining[cursor]
+            if raw_value.nil?
+              raise ArgumentError, "Missing required argument: #{argument.name}" if argument.required
+              next
+            end
+
+            options[argument.name] = coerce_argument(raw_value, argument)
+            cursor += 1
+          end
+
+          return unless remaining.length > cursor
+          if accepts_args_keyword?
+            options[:args] = remaining.drop(cursor)
+            return
+          end
+
+          extra = remaining.drop(cursor).join(" ")
+          raise ArgumentError, "Unexpected arguments: #{extra}"
+        end
+
+        def accepts_args_keyword?
+          command_class.instance_method(:call).parameters.any? do |kind, name|
+            %i[key keyreq].include?(kind) && name == :args
+          end
+        rescue NameError
+          false
+        end
+
+        def coerce_argument(value, argument)
+          case argument.type
+          when :integer
+            Integer(value)
+          when :float
+            Float(value)
+          when :boolean
+            coerce_boolean(value)
+          else
+            value
+          end
+        rescue ArgumentError
+          raise ArgumentError, "Invalid value for argument #{argument.name}: expected #{argument.type}"
+        end
+
+        def coerce_boolean(value)
+          return true if value == true || value.to_s.casecmp("true").zero?
+          return false if value == false || value.to_s.casecmp("false").zero?
+
+          raise ArgumentError
+        end
+
+        def validate_required_options!(options)
+          missing = command_class.options.select do |option|
+            option.required && (options[option.name].nil? || options[option.name] == "")
+          end
+          return if missing.empty?
+
+          flags = missing.map(&:long_switch).join(", ")
+          raise ArgumentError, "Missing required options: #{flags}"
+        end
+
+        def command_label
+          raw = command_class.name.to_s
+          token = raw.empty? ? "command" : (raw.split("::").last || "command")
+          token.gsub(/([a-z])([A-Z])/, '\1-\2').downcase
+        end
+
+        def parse_error_message(error)
+          return "#{error.message}. Did you mean: #{suggest_for(error)}" if error.is_a?(OptionParser::InvalidOption)
+
+          error.message
+        end
+
+        def suggest_for(error)
+          token = error.args.first.to_s
+          return "(no suggestion)" if token.empty?
+
+          candidates = command_class.options.flat_map do |option|
+            option.aliases + [option.long_switch]
+          end
+
+          ranked = candidates.sort_by do |candidate|
+            levenshtein(token, candidate)
+          end
+
+          ranked.first || "(no suggestion)"
+        end
+
+        def levenshtein(source, target)
+          m = source.length
+          n = target.length
+          return n if m.zero?
+          return m if n.zero?
+
+          matrix = Array.new(m + 1) { |i| [i] + [0] * n }
+          (0..n).each { |j| matrix[0][j] = j }
+
+          (1..m).each do |i|
+            (1..n).each do |j|
+              cost = (source[i - 1] == target[j - 1]) ? 0 : 1
+              matrix[i][j] = [
+                matrix[i - 1][j] + 1,
+                matrix[i][j - 1] + 1,
+                matrix[i - 1][j - 1] + cost
+              ].min
+            end
+          end
+
+          matrix[m][n]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Ace
+  module Support
+    module Cli
+      class Registry
+        Node = Struct.new(:command, :children)
+
+        attr_reader :version
+
+        def initialize(version: nil)
+          @version = version
+          @root = Node.new(nil, {})
+        end
+
+        def register(name, command_class = nil)
+          node = ensure_path(name)
+          node.command = command_class if command_class
+          yield NestedRegistry.new(node) if block_given?
+          self
+        end
+
+        def resolve(args)
+          raise CommandNotFoundError, "No commands registered" if @root.children.empty?
+          raise CommandNotFoundError, "No command provided" if args.empty?
+
+          tokens = args.dup
+          node = @root
+          consumed = 0
+
+          tokens.each do |token|
+            child = node.children[token]
+            break unless child
+
+            node = child
+            consumed += 1
+          end
+
+          unless node.command
+            attempted = tokens.first(consumed + 1).join(" ")
+            raise CommandNotFoundError, "Command not found: #{attempted.strip}"
+          end
+
+          [node.command, tokens.drop(consumed)]
+        end
+
+        def commands
+          @root.children.each_with_object({}) do |(name, node), hash|
+            hash[name] = node.command || NestedRegistry.new(node)
+          end
+        end
+
+        private
+
+        def ensure_path(name)
+          parts = name.to_s.split(" ")
+          raise ArgumentError, "Command name cannot be empty" if parts.empty?
+
+          parts.reduce(@root) do |node, part|
+            node.children[part] ||= Node.new(nil, {})
+          end
+        end
+
+        class NestedRegistry
+          def initialize(node)
+            @node = node
+          end
+
+          def register(name, command_class = nil)
+            parts = name.to_s.split(" ")
+            raise ArgumentError, "Command name cannot be empty" if parts.empty?
+
+            node = parts.reduce(@node) do |current, part|
+              current.children[part] ||= Node.new(nil, {})
+            end
+            node.command = command_class if command_class
+            yield NestedRegistry.new(node) if block_given?
+            self
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+require_relative "error"
+
+module Ace
+  module Support
+    module Cli
+      # DSL adapter allowing CLI modules to keep `register` semantics
+      # while using Ace::Support::Cli::Registry under the hood.
+      module RegistryDsl
+        def self.extended(base)
+          base.instance_variable_set(:@registry, Ace::Support::Cli::Registry.new)
+        end
+
+        def register(name, command_class = nil, *_args, aliases: nil, **_kwargs)
+          registry.register(name, normalize_command(command_class))
+          Array(aliases).each do |aliaz|
+            registry.register(aliaz, normalize_command(command_class))
+          end
+          self
+        end
+
+        def resolve(args)
+          return registry.resolve(args) unless args.empty?
+
+          registry.resolve(["--help"])
+        rescue Ace::Support::Cli::CommandNotFoundError
+          raise Ace::Support::Cli::Error.new("unknown command", exit_code: 1)
+        end
+
+        private
+
+        def registry
+          @registry ||= Ace::Support::Cli::Registry.new
+        end
+
+        def normalize_command(command_class)
+          command_class
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+
+module Ace
+  module Support
+    module Cli
+      class Runner
+        def initialize(registry, parser_class: Parser)
+          @registry = registry
+          @parser_class = parser_class
+        end
+
+        def call(args: ARGV)
+          if root_help_request?(args)
+            puts Ace::Support::Cli::Help::Usage.new(@registry, program_name: resolve_program_name).render
+            return 0
+          end
+
+          command_target, remaining, command_name = resolve_target(args)
+          command_class = command_target.is_a?(Class) ? command_target : command_target.class
+          parsed = @parser_class.new(command_class, command_name: command_name).parse(remaining)
+          result = if command_target.is_a?(Class)
+            command_target.new.call(**parsed)
+          else
+            command_target.call(**parsed)
+          end
+          result.nil? ? 0 : result
+        rescue Ace::Support::Cli::HelpRendered => e
+          puts e.output
+          e.status
+        rescue Ace::Support::Cli::ParseError => e
+          raise Ace::Support::Cli::Error.new(e.message)
+        rescue Ace::Support::Cli::CommandNotFoundError => e
+          raise Ace::Support::Cli::Error.new(e.message)
+        end
+
+        private
+
+        def root_help_request?(args)
+          @registry.respond_to?(:resolve) && (%w[--help -h].include?(args.first) || args.empty?)
+        end
+
+        def resolve_target(args)
+          program = resolve_program_name
+          if @registry.respond_to?(:resolve)
+            command, remaining = @registry.resolve(args)
+            consumed = args.length - remaining.length
+            name = ([program] + args.first(consumed)).join(" ")
+            [command, remaining, name]
+          else
+            normalized = args.dup
+            token = @registry.name.to_s.split("::").last.gsub(/([a-z])([A-Z])/, '\1-\2').downcase
+            normalized.shift if !token.empty? && normalized.first == token
+            [@registry, normalized, program]
+          end
+        end
+
+        def resolve_program_name
+          if @registry.respond_to?(:const_defined?) && @registry.const_defined?(:PROGRAM_NAME)
+            @registry.const_get(:PROGRAM_NAME)
+          else
+            File.basename($PROGRAM_NAME)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      module StandardOptions
+        QUIET_DESC = "Suppress non-essential output"
+        VERBOSE_DESC = "Show verbose output"
+        DEBUG_DESC = "Show debug output"
+        HELP_DESC = "Show this help"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      VERSION = "0.6.2"
+    end
+  end
+end

data/lib/ace/support/cli.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "cli/version"
+require_relative "cli/errors"
+require_relative "cli/error"
+require_relative "cli/standard_options"
+require_relative "cli/base"
+require_relative "cli/registry_dsl"
+require_relative "cli/models/option"
+require_relative "cli/models/argument"
+require_relative "cli/command"
+require_relative "cli/parser"
+require_relative "cli/argv_coalescer"
+require_relative "cli/registry"
+require_relative "cli/runner"
+require_relative "cli/help/banner"
+require_relative "cli/help/usage"
+require_relative "cli/help/concise"
+require_relative "cli/help/help_command"
+require_relative "cli/help/version_command"
+require_relative "cli/help/two_tier_help"
+
+module Ace
+  module Support
+    module Cli
+      Banner = Help::Banner
+      HelpConcise = Help::Concise
+      HelpCommand = Help::HelpCommand
+      VersionCommand = Help::VersionCommand
+      TwoTierHelp = Help::TwoTierHelp
+
+      class Usage < Help::Usage
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: ace-support-cli
+version: !ruby/object:Gem::Version
+  version: 0.6.2
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Provides command DSL, option parsing, registry routing, and runner primitives
+  for ACE CLI tools.
+email:
+- mc@cs3b.com
+executables:
+- ace-support-cli
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- exe/ace-support-cli
+- lib/ace/support/cli.rb
+- lib/ace/support/cli/argv_coalescer.rb
+- lib/ace/support/cli/base.rb
+- lib/ace/support/cli/command.rb
+- lib/ace/support/cli/error.rb
+- lib/ace/support/cli/errors.rb
+- lib/ace/support/cli/help/banner.rb
+- lib/ace/support/cli/help/concise.rb
+- lib/ace/support/cli/help/help_command.rb
+- lib/ace/support/cli/help/two_tier_help.rb
+- lib/ace/support/cli/help/usage.rb
+- lib/ace/support/cli/help/version_command.rb
+- lib/ace/support/cli/models/argument.rb
+- lib/ace/support/cli/models/option.rb
+- lib/ace/support/cli/parser.rb
+- lib/ace/support/cli/registry.rb
+- lib/ace/support/cli/registry_dsl.rb
+- lib/ace/support/cli/runner.rb
+- lib/ace/support/cli/standard_options.rb
+- lib/ace/support/cli/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/cs3b/ace
+  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-support-cli/
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-support-cli/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: CLI command framework for ACE gems
+test_files: []