devex 0.3.5

data/lib/devex/cli.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+module Devex
+  # Main CLI class - entry point for CLI commands.
+  #
+  # Can be used with a Configuration for custom CLI applications,
+  # or with defaults for backward-compatible dx usage.
+  #
+  # @example Core usage
+  #   config = Devex::Core::Configuration.new(
+  #     executable_name: "mycli",
+  #     flag_prefix: "mycli"
+  #   )
+  #   cli = Devex::CLI.new(config: config)
+  #   cli.load_tools("/path/to/tools")
+  #   exit cli.run(ARGV)
+  #
+  class CLI
+    HELP_FLAGS = %w[-h -? --help].freeze
+    HELP_WORD  = "help"
+
+    # Universal flags available to all commands
+    UNIVERSAL_FLAGS = {
+      format:   ["-f", "--format=FORMAT"],
+      verbose:  ["-v", "--verbose"],
+      quiet:    ["-q", "--quiet"],
+      no_color: ["--no-color"],
+      color:    ["--color=MODE"]
+    }.freeze
+
+    attr_reader :root_tool, :executable_name, :project_root, :global_options, :config
+
+    # @param executable_name [String] name of the executable (for help text)
+    # @param config [Core::Configuration, nil] full configuration (overrides executable_name)
+    def initialize(executable_name: "dx", config: nil)
+      @config          = config
+      @executable_name = config&.executable_name || executable_name
+      @flag_prefix     = config&.flag_prefix || "dx"
+      @root_tool       = Tool.new(nil)
+      @builtin_root    = Tool.new(nil)
+      @mixins          = {}
+      @project_root    = nil
+      @global_options  = {
+        format:  nil,
+        verbose: 0,
+        quiet:   false
+      }
+    end
+
+    # Main entry point
+    def run(argv = ARGV)
+      argv = argv.dup
+
+      # Configure Context with our configuration (for env var prefix, etc.)
+      Context.configure(@config) if @config
+
+      # Extract and apply global flags first (before help or tool resolution)
+      argv, show_version = extract_global_flags(argv)
+
+      # --{prefix}-version shows gem version and exits
+      if show_version
+        output_gem_version
+        return 0
+      end
+
+      # Transform help anywhere in args to --help at the right place
+      argv, show_help = extract_help(argv)
+
+      # Find the tool to execute
+      tool, remaining_argv = resolve_tool(argv)
+
+      if show_help
+        show_help(tool)
+        return 0
+      end
+
+      if tool.nil?
+        show_help(@root_tool)
+        return 1
+      end
+
+      begin
+        # Track task invocation in context
+        task_name = tool.full_name.empty? ? "root" : tool.full_name
+        Context.with_task(task_name) do
+          tool.execute(remaining_argv, self)
+        end
+        0
+      rescue Error => e
+        Output.error(e.message)
+        1
+      rescue OptionParser::ParseError => e
+        Output.error(e.message)
+        1
+      end
+    end
+
+    # Load built-in tools from a directory
+    # @param dir [String, nil] directory path (uses gem builtins if nil)
+    def load_builtins(dir = nil)
+      builtin_dir = dir || File.join(__dir__, "builtins")
+      Loader.load_directory(builtin_dir, @builtin_root, @mixins)
+    end
+
+    # Load tools from a directory
+    # @param dir [String] directory path
+    def load_tools(dir)
+      Loader.load_directory(dir, @root_tool, @mixins) if dir && File.directory?(dir)
+    end
+
+    # Load project-specific tools
+    def load_project_tools(project_root)
+      @project_root = project_root
+
+      # Add project lib/ to load path so tools can `require` without `require_relative`
+      add_project_lib_to_load_path(project_root)
+
+      tools_dir = Devex.tools_dir(project_root)
+      Loader.load_directory(tools_dir, @root_tool, @mixins) if tools_dir
+    end
+
+    # Add project's lib/ directory to $LOAD_PATH if it exists.
+    def add_project_lib_to_load_path(project_root)
+      return unless project_root
+
+      lib_dir = File.join(project_root, "lib")
+      return unless File.directory?(lib_dir)
+      return if $LOAD_PATH.include?(lib_dir)
+
+      $LOAD_PATH.unshift(lib_dir)
+    end
+
+    # Merge builtin tools (project tools take precedence)
+    def merge_builtins
+      @builtin_root.subtools.each do |name, builtin_tool|
+        if @root_tool.subtools[name]
+          # Project overrides builtin - store reference for super-like behavior
+          @root_tool.subtools[name].builtin = builtin_tool
+        else
+          # No override - use builtin directly
+          @root_tool.add_subtool(builtin_tool)
+        end
+      end
+    end
+
+    # Display help for a tool
+    def show_help(tool)
+      help_text = tool.help_text(@executable_name)
+
+      # Append global options section if showing root help
+      help_text += global_options_help if tool == @root_tool
+
+      puts help_text
+    end
+
+    private
+
+    # Flag prefix for framework flags (--{prefix}-version, etc.)
+    def flag_prefix
+      @flag_prefix
+    end
+
+    # Extract global flags from argv, apply Context overrides
+    # Returns [remaining_argv, show_version]
+    def extract_global_flags(argv)
+      remaining    = []
+      show_version = false
+      prefix       = flag_prefix
+
+      # Build dynamic flag patterns
+      version_flag      = "--#{prefix}-version"
+      from_dir_flag     = "--#{prefix}-from-dir"
+      force_color_flag  = "--#{prefix}-force-color"
+      no_color_flag     = "--#{prefix}-no-color"
+      agent_mode_flag   = "--#{prefix}-agent-mode"
+      no_agent_flag     = "--#{prefix}-no-agent-mode"
+      interactive_flag  = "--#{prefix}-interactive"
+      no_interactive    = "--#{prefix}-no-interactive"
+      env_flag_pattern  = /^--#{Regexp.escape(prefix)}-env=(.+)$/
+      ci_flag           = "--#{prefix}-ci"
+      no_ci_flag        = "--#{prefix}-no-ci"
+      terminal_flag     = "--#{prefix}-terminal"
+      no_terminal_flag  = "--#{prefix}-no-terminal"
+
+      i = 0
+      while i < argv.length
+        arg      = argv[i]
+        consumed = false
+
+        # Check universal flags
+        case arg
+        when version_flag
+          show_version = true
+          consumed     = true
+        when "-f", "--format"
+          @global_options[:format] = argv[i + 1]
+          i        += 1
+          consumed = true
+        when /^--format=(.+)$/
+          @global_options[:format] = ::Regexp.last_match(1)
+          consumed = true
+        when "-v", "--verbose"
+          @global_options[:verbose] += 1
+          consumed = true
+        when "--no-verbose"
+          @global_options[:verbose] = 0
+          consumed = true
+        when "-q", "--quiet"
+          @global_options[:quiet] = true
+          consumed = true
+        when "--no-quiet"
+          @global_options[:quiet] = false
+          consumed = true
+        when "--no-color"
+          Context.set_override(:color, false)
+          consumed = true
+        when "--color=always"
+          Context.set_override(:color, true)
+          consumed = true
+        when "--color=never"
+          Context.set_override(:color, false)
+          consumed = true
+        when "--color=auto"
+          Context.clear_override(:color)
+          consumed = true
+        when /^--color=(.+)$/
+          consumed = true
+        end
+
+        # Check hidden debug flags (not in help)
+        unless consumed
+          case arg
+          when force_color_flag
+            Context.set_override(:color, true)
+            consumed = true
+          when no_color_flag
+            Context.set_override(:color, false)
+            consumed = true
+          when agent_mode_flag
+            Context.set_override(:agent_mode, true)
+            consumed = true
+          when no_agent_flag
+            Context.set_override(:agent_mode, false)
+            consumed = true
+          when interactive_flag
+            Context.set_override(:interactive, true)
+            consumed = true
+          when no_interactive
+            Context.set_override(:interactive, false)
+            consumed = true
+          when env_flag_pattern
+            Context.set_override(:env, ::Regexp.last_match(1))
+            consumed = true
+          when ci_flag
+            Context.set_override(:ci, true)
+            consumed = true
+          when no_ci_flag
+            Context.set_override(:ci, false)
+            consumed = true
+          when terminal_flag
+            Context.set_override(:terminal, true)
+            consumed = true
+          when no_terminal_flag
+            Context.set_override(:terminal, false)
+            consumed = true
+          end
+        end
+
+        remaining << arg unless consumed
+        i += 1
+      end
+
+      [remaining, show_version]
+    end
+
+    # Extract help indicators from argv, return [cleaned_argv, show_help]
+    def extract_help(argv)
+      show_help = false
+
+      HELP_FLAGS.each do |flag|
+        if argv.include?(flag)
+          argv.delete(flag)
+          show_help = true
+        end
+      end
+
+      if argv.include?(HELP_WORD)
+        argv.delete(HELP_WORD)
+        show_help = true
+      end
+
+      [argv, show_help]
+    end
+
+    # Resolve a tool from argv
+    def resolve_tool(argv)
+      tool      = @root_tool
+      remaining = argv.dup
+
+      while remaining.any?
+        candidate = remaining.first
+        break if candidate.start_with?("-")
+
+        subtool = tool.subtool(candidate)
+        break unless subtool
+
+        tool = subtool
+        remaining.shift
+      end
+
+      [tool, remaining]
+    end
+
+    # Generate help text for global options
+    def global_options_help
+      prefix = flag_prefix
+      <<~HELP
+
+        Global Options:
+          -f, --format=FORMAT      Output format (text, json, yaml)
+          -v, --verbose            Increase verbosity (can be repeated)
+          -q, --quiet              Suppress non-error output
+          --no-color               Disable colored output
+          --color=MODE             Color mode: auto, always, never
+          --#{prefix}-version#{' ' * (14 - prefix.length)}Show #{@executable_name} version
+          --#{prefix}-from-dir=PATH  Operate on project at PATH
+      HELP
+    end
+
+    # Output gem version (not project version)
+    def output_gem_version
+      if @global_options[:format] == "json"
+        require "json"
+        puts JSON.generate({ name: @executable_name, version: VERSION })
+      else
+        puts "#{@executable_name} #{VERSION}"
+      end
+    end
+  end
+end