Add a default Help command

[thegedge]

Pretty much every command-line tool needs help, so perhaps we could provide a template command that can be incorporated into projects and provide a sane default set of help. My experience is that CLI tools often have both short-form and long-form descriptions.

The short-form description gets used generally when showing commands in a list (e.g., mytool help showing all commands and a short description). The long-form will be shown in help for just that command (e.g., mytool help mycommand).

Here's an incredibly rough sketch:

module CLI
  module Kit
    class Help < CLI::Kit::BaseCommand
      def call(args, _command_name)
        if args.empty?
          all_commands.each { |_command_name, command| puts CLI::UI.fmt(command.short_description) }
        else
          command = all_commands.find { |command_name, _command| command_name == args.first }
          puts CLI::UI.fmt(command.long_description) if command
          # else error message for unknown command
        end
      end

      # The subclassed help command will provide the list of all commands
      def all_commands
        raise NotImplementedError
      end
    end
  end
end

[burke]

Yeah, I would love to provide some sort of help facility. I started extracting dev's at one point, but I don't actually like it enough to drag into cli-kit.

It's tough to find a good paradigm for help when you rely on lazy-loading like we do.

[thegedge]

It's tough to find a good paradigm for help when you rely on lazy-loading like we do.

Do you think help is perhaps where we don't mind taking the hit of loading up all of the code? Or do you think separating help for commands from the commands themselves would be a more effective approach?

[burke]

I guess it's not a completely crazy idea to have dev help eager-load, as long as there aren't more common paths that trigger it. I wonder how long it would take, I don't think there's any path that eager-loads that much code right now.

[technicalpickles]

Looks like this happened at some point: https://github.com/Shopify/cli-kit/blob/master/gen/lib/gen/commands/help.rb