ace-support-cli 0.6.2

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      module Help
+        module Concise
+          def self.call(command, name)
+            [
+              header_line(command, name),
+              usage_line(command, name),
+              options_block(command),
+              examples_block(command, name),
+              footer_line(name)
+            ].compact.join("\n\n")
+          end
+
+          def self.header_line(command, name)
+            summary = first_line(command.respond_to?(:description) ? command.description : nil)
+            summary ? "#{name} - #{summary}" : name.to_s
+          end
+
+          def self.usage_line(command, name)
+            args = Banner.arguments_synopsis(command)
+            opts = Banner.options(command).any? ? " [OPTIONS]" : ""
+            "Usage: #{name}#{args}#{opts}"
+          end
+
+          def self.options_block(command)
+            lines = Banner.options(command).map { |option| format_option(option) }
+            lines << "  --help, -h            Show this help"
+            "Options:\n#{lines.join("\n")}"
+          end
+
+          def self.examples_block(command, name)
+            items = Banner.examples(command)
+            return nil if items.empty?
+
+            rendered = items.first(3).map do |item|
+              cleaned = item.to_s.sub(/\A#{Regexp.escape(name)}\s*/, "")
+              "  $ #{name} #{cleaned}".rstrip
+            end
+            "Examples:\n#{rendered.join("\n")}"
+          end
+
+          def self.footer_line(name)
+            "Run '#{name} --help' for full details."
+          end
+
+          def self.format_option(option)
+            name = Banner.option_name(option).sub("=VALUE1,VALUE2,..", " VALUES").sub("=VALUE", " VALUE")
+            aliases = Banner.option_aliases(option)
+            name = "#{name}, #{aliases.join(", ")}" if aliases.any?
+            "  --#{name}"
+          end
+
+          def self.first_line(text)
+            return nil if text.nil?
+
+            text.to_s.strip.split("\n").first&.strip
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      module Help
+        module HelpCommand
+          def self.build(program_name:, version:, commands:, examples: nil)
+            Class.new(Command) do
+              @program_name = program_name
+              @version = version
+              @commands = commands
+              @examples = examples
+
+              class << self
+                attr_reader :program_name, :version, :commands, :examples
+              end
+
+              desc "Show top-level help"
+              argument :args, type: :array, required: false
+
+              def call(**_params)
+                puts self.class.render
+                0
+              end
+
+              def self.render
+                sections = []
+                sections << "#{program_name} #{version}".strip
+                sections << render_commands
+                rendered_examples = render_examples
+                sections << rendered_examples if rendered_examples
+                sections << render_options
+                sections.join("\n\n")
+              end
+
+              def self.render_commands
+                lines = normalized_commands.map do |name, description|
+                  "#{"  #{name}".ljust(16)}# #{description}"
+                end
+                "Commands:\n#{lines.join("\n")}"
+              end
+
+              def self.render_examples
+                return nil if examples.nil? || examples.empty?
+
+                "Examples:\n#{examples.map { |item| "  #{item}" }.join("\n")}"
+              end
+
+              def self.render_options
+                <<~OPTIONS.chomp
+                  Options:
+                    --help, -h      # Print this help
+                    --version       # Print version
+                OPTIONS
+              end
+
+              def self.normalized_commands
+                commands.is_a?(Hash) ? commands.to_a : commands
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      module Help
+        module TwoTierHelp
+          def self.concise?(args)
+            values = Array(args)
+            values.include?("-h") && !values.include?("--help")
+          end
+
+          def self.render(command, name, args:)
+            if concise?(args)
+              Concise.call(command, name)
+            else
+              Banner.call(command, name)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      module Help
+        class Usage
+          COLUMN_WIDTH = 34
+
+          def initialize(registry, program_name: nil)
+            @registry = registry
+            @program_name = program_name
+          end
+
+          def render
+            commands = visible_commands
+            groups = command_groups
+            output = if groups && !groups.empty?
+              format_grouped(commands, groups)
+            else
+              format_flat(commands, header: "COMMANDS")
+            end
+
+            examples = help_examples
+            output += "\n\n#{format_examples(examples)}" if examples && !examples.empty?
+            output
+          end
+
+          def render_concise
+            output = format_flat(visible_commands, header: "Commands:")
+            output + "\n\nRun '#{resolved_program_name} --help' for more info. Each command has its own --help."
+          end
+
+          private
+
+          attr_reader :registry, :program_name
+
+          def visible_commands
+            all_commands.reject { |_name, value| value[:hidden] }
+          end
+
+          def all_commands
+            commands =
+              if registry.respond_to?(:commands)
+                convert_commands_hash(registry.commands)
+              elsif registry.is_a?(Hash)
+                convert_commands_hash(registry)
+              elsif registry.respond_to?(:to_h)
+                convert_commands_hash(registry.to_h)
+              elsif registry.respond_to?(:const_defined?) && registry.const_defined?(:REGISTERED_COMMANDS)
+                convert_registered_commands(registry.const_get(:REGISTERED_COMMANDS))
+              else
+                []
+              end
+
+            commands.sort_by { |name, _| name }
+          end
+
+          def convert_commands_hash(hash)
+            hash.map do |name, command|
+              [name.to_s, {description: first_line(description(command)), hidden: hidden?(command)}]
+            end
+          end
+
+          def convert_registered_commands(commands)
+            Array(commands).map do |entry|
+              if entry.is_a?(Array)
+                [entry[0].to_s, {description: first_line(entry[1]), hidden: false}]
+              else
+                [entry.to_s, {description: nil, hidden: false}]
+              end
+            end
+          end
+
+          def format_flat(commands, header:)
+            lines = commands.map do |name, meta|
+              banner = "  #{name}"
+              details = meta[:description] ? " # #{meta[:description]}" : nil
+              justify(banner, details)
+            end
+
+            ([header] + lines).join("\n")
+          end
+
+          def format_grouped(commands, groups)
+            index = commands.to_h
+            grouped_names = groups.values.flatten.map(&:to_s)
+            output = ["COMMANDS"]
+
+            groups.each do |group_name, names|
+              lines = names.filter_map do |name|
+                meta = index[name.to_s]
+                next unless meta
+
+                banner = "  #{name}"
+                details = meta[:description] ? " # #{meta[:description]}" : nil
+                justify(banner, details, indent: 2)
+              end
+              next if lines.empty?
+
+              output << ""
+              output << "  #{group_name}"
+              output.concat(lines)
+            end
+
+            ungrouped = commands.filter_map do |name, meta|
+              next if grouped_names.include?(name)
+
+              banner = "  #{name}"
+              details = meta[:description] ? " # #{meta[:description]}" : nil
+              justify(banner, details)
+            end
+
+            unless ungrouped.empty?
+              output << ""
+              output.concat(ungrouped)
+            end
+            output.join("\n")
+          end
+
+          def justify(banner, details, indent: 0)
+            return "#{" " * indent}#{banner}" if details.nil?
+
+            base = banner.ljust(COLUMN_WIDTH)
+            "#{" " * indent}#{base}#{details}"
+          end
+
+          def command_groups
+            return nil unless registry.respond_to?(:const_defined?)
+            return nil unless registry.const_defined?(:COMMAND_GROUPS)
+
+            registry.const_get(:COMMAND_GROUPS)
+          end
+
+          def help_examples
+            return nil unless registry.respond_to?(:const_defined?)
+            return nil unless registry.const_defined?(:HELP_EXAMPLES)
+
+            registry.const_get(:HELP_EXAMPLES)
+          end
+
+          def format_examples(examples)
+            lines = examples.map do |entry|
+              if entry.is_a?(Array)
+                desc, cmd = entry
+                "  $ #{cmd}  # #{desc}"
+              else
+                "  #{entry}"
+              end
+            end
+            "EXAMPLES\n#{lines.join("\n")}"
+          end
+
+          def resolved_program_name
+            return program_name unless program_name.nil? || program_name.empty?
+            return registry.const_get(:PROGRAM_NAME) if registry.respond_to?(:const_defined?) && registry.const_defined?(:PROGRAM_NAME)
+
+            $PROGRAM_NAME.split("/").last
+          end
+
+          def description(command)
+            command.respond_to?(:description) ? command.description : nil
+          end
+
+          def hidden?(command)
+            command.respond_to?(:hidden) && command.hidden
+          end
+
+          def first_line(text)
+            return nil if text.nil?
+
+            text.to_s.strip.split("\n").first&.strip
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      module Help
+        module VersionCommand
+          def self.build(gem_name:, version:)
+            Class.new(Command) do
+              @gem_name = gem_name
+              @version = version
+
+              class << self
+                attr_reader :gem_name, :version
+              end
+
+              desc "Show version information"
+
+              def call(**_params)
+                puts "#{self.class.gem_name} #{self.class.version}"
+                0
+              end
+            end
+          end
+
+          def self.module(gem_name:, version:)
+            Module.new do
+              define_method(:show_version) do
+                puts "#{gem_name} #{version.call}"
+                0
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/cli/models/argument.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      module Models
+        class Argument
+          VALID_TYPES = %i[string integer float boolean array].freeze
+
+          attr_reader :name, :type, :required, :desc
+
+          def initialize(name:, type: :string, required: true, desc: "")
+            @name = name.to_sym
+            @type = type.to_sym
+            @required = required
+            @desc = desc
+            validate!
+          end
+
+          private
+
+          def validate!
+            return if VALID_TYPES.include?(type)
+
+            raise ArgumentError, "Invalid argument type: #{type.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/cli/models/option.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Cli
+      module Models
+        class Option
+          VALID_TYPES = %i[string integer float boolean array hash].freeze
+
+          attr_reader :name, :type, :default, :desc, :aliases, :values, :required, :repeat
+
+          def initialize(name:, type: :string, default: nil, desc: "", aliases: [], values: nil, required: false, repeat: false)
+            @name = name.to_sym
+            @type = type.to_sym
+            @default = default
+            @desc = desc
+            @aliases = normalize_aliases(Array(aliases))
+            @values = values
+            @required = required
+            @repeat = repeat
+            validate!
+          end
+
+          def long_switch
+            "--#{name.to_s.tr("_", "-")}"
+          end
+
+          private
+
+          def validate!
+            return if VALID_TYPES.include?(type)
+
+            raise ArgumentError, "Invalid option type: #{type.inspect}"
+          end
+
+          def normalize_aliases(aliases)
+            aliases.map do |entry|
+              alias_name = entry.to_s
+              if alias_name.start_with?("-")
+                alias_name
+              elsif alias_name.length == 1
+                "-#{alias_name}"
+              else
+                "--#{alias_name.tr("_", "-")}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end