Add brew debugger command

.vscode/launch.json

@@ -0,0 +1,14 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "rdbg",
+      "name": "Attach with rdbg",
+      "request": "attach",
+      "rdbgPath": "${workspaceFolder}/Library/Homebrew/vendor/portable-ruby/current/lib/ruby/gems/3.3.0/gems/debug-1.9.1/exe/rdbg",
+      "env": {
+        "TMPDIR": "/private/tmp/",
+      }
+    }
+  ]
+}

Library/Homebrew/abstract_command.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "cli/parser"
+require "shell_command"
 
 module Homebrew
   # Subclass this to implement a `brew` command. This is preferred to declaring a named function in the `Homebrew`
@@ -41,6 +42,9 @@ module Homebrew
       sig { returns(T::Boolean) }
       def dev_cmd? = T.must(name).start_with?("Homebrew::DevCmd")
 
+      sig { returns(T::Boolean) }
+      def ruby_cmd? = !include?(Homebrew::ShellCommand)
+
       sig { returns(CLI::Parser) }
       def parser = CLI::Parser.new(self, &@parser_block)
 

Library/Homebrew/commands.rb

@@ -41,6 +41,15 @@ module Commands
     require?(HOMEBREW_DEV_CMD_PATH/cmd)
   end
 
+  def self.valid_ruby_cmd?(cmd)
+    if (valid_internal_cmd?(cmd) || valid_internal_dev_cmd?(cmd) || external_ruby_v2_cmd_path(cmd)) &&
+       (command = Homebrew::AbstractCommand.command(cmd))
+      command.ruby_cmd?
+    else
+      false
+    end
+  end
+
   def self.method_name(cmd)
     cmd.to_s
        .tr("-", "_")

Library/Homebrew/dev-cmd/debugger.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Homebrew
+  module DevCmd
+    class Debugger < AbstractCommand
+      cmd_args do
+        description <<~EOS
+          Run the specified Homebrew command in debug mode.
+
+          To pass flags to the command, use `--` to separate them from the `brew` flags.
+          For example: `brew debugger -- list --formula`.
+        EOS
+        switch "-n", "--nonstop",
+               description: "Do not stop at the beginning of the script."
+        switch "-O", "--open",
+               description: "Start remote debugging over a Unix socket."
+
+        named_args :command, min: 1
+      end
+
+      sig { override.void }
+      def run
+        unless Commands.valid_ruby_cmd?(args.named.first)
+          raise UsageError, "`#{args.named.first}` is not a valid Ruby command!"
+        end
+
+        brew_rb = (HOMEBREW_LIBRARY_PATH/"brew.rb").resolved_path
+        nonstop = "1" if args.nonstop?
+        debugger_method = if args.open?
+          "open"
+        else
+          "start"
+        end
+
+        with_env RUBY_DEBUG_NONSTOP: nonstop, RUBY_DEBUG_FORK_MODE: "parent" do
+          system(*HOMEBREW_RUBY_EXEC_ARGS,
+                 "-I", $LOAD_PATH.join(File::PATH_SEPARATOR),
+                 "-rdebug/#{debugger_method}",
+                 brew_rb, *args.named)
+        end
+      end
+    end
+  end
+end

Library/Homebrew/sorbet/rbi/dsl/homebrew/dev_cmd/debugger.rbi

@@ -0,0 +1,25 @@
+# typed: true
+
+# DO NOT EDIT MANUALLY
+# This is an autogenerated file for dynamic methods in `Homebrew::DevCmd::Debugger`.
+# Please instead update this file by running `bin/tapioca dsl Homebrew::DevCmd::Debugger`.
+
+
+class Homebrew::DevCmd::Debugger
+  sig { returns(Homebrew::DevCmd::Debugger::Args) }
+  def args; end
+end
+
+class Homebrew::DevCmd::Debugger::Args < Homebrew::CLI::Args
+  sig { returns(T::Boolean) }
+  def O?; end
+
+  sig { returns(T::Boolean) }
+  def n?; end
+
+  sig { returns(T::Boolean) }
+  def nonstop?; end
+
+  sig { returns(T::Boolean) }
+  def open?; end
+end