Feat: return usage as data instead of just a string

[tkjaergaard]

Describe the feature

We already have the feature of overriding the showUsage function on runMain, but the only way you cen compute the usage is as a string using the renderUsage function.

That means that if you wanted to enrich the usage output you have to recreate the renderUsage function locally and apply changes.

https://github.com/unjs/citty/blob/main/src/usage.ts#L18-L124

The downsides to this, is that it's fragile to new changes that may occur in commands and it's structure in the future.

I suggest that it should be considered to rethink the renderUsage method.

It could be great to either create some utils functions or class implementation for getting the usage as data that you can then manipulate.

The renderUsage method could then receive a implementation of a "render template" from which it can generate the string.

Use cases could be to group commands like:

⚡️ My Awesome CLI Experience (foo v1.0.0)                                                                                                                                                                                                                                               7:51:33 AM

USAGE awesome init|dev|test|build|info|deploy|start

COMMANDS

    Development 
           init    Create a new awesome file.                                          
            dev    Run awsome dev server
           test    Run tests                                                            

     Production           
          build    Build a awesome file
           info    Get information about your awesome bundle                                   

     Deployment
         deploy    Deploy your awesome file to your server
          start    Launches your awesome file

Use nuxi <command> --help for more information about a command.

Or what ever makes a good documented cli for different use case.

The main topic here is to add the opt-it feature of defining your own render usage "template".

What do you guys think? 🙂

Additional information

• Would you be willing to help implement this feature?