[Proposal] Option to output help as JSON

[thomassnielsen]

This has come up in #3699 and EmberTown/ember-hearth#66.

In short, it would be nice for tools that depend on Ember-CLI to be able to read the help output as JSON (for example ember g --help --json).

In our specific use case in Ember Hearth we would like to be able to render a dynamic GUI for some tasks, like generating blueprints. This way we cloud also include any blueprints added by addons. Like @stefanpenner mentioned, we should probably make the internal help-functions (like printBasicHelp and printDetailedHelp) use JSON internally, and parse to human readable before printing (unless --json is specified).

I'm not sure how the internals of this would/should work though. I'm imagining the json output would be something like this:

{
  "name":"generate",
  "description":"Generates new code from blueprints.",
  "aliases":["g"],
  "flags":[
    {
      "flag":"--verbose",
      "aliases":["-v"],
      "description":"Verbose output"
    }, {…}],
  "commands":[
    {
      "command":"template",
      "description":"Generates a template.",
      "arguments":["name"]
    },
    {
      "command":"model",
      "description":"Generate an ember-data model.",
      "arguments":[
        "name", 
        {
          "argument":"attr:type", 
          "description":"Add attributes to the model, e.g. 'name:String age:Number'", 
          "multiple":true
        }]
    }, {…}]
}

Note that this output contains a bit more info than the current --help, specifically in the attr:type argument for the model command. This is something I feel is currently missing (I did not understand the model generator command without consulting a colleague, for example), and would be nice to add while we're at it.

It should be pretty straight forward to generate a human readable output from this JSON. There are a few things missing: However: The generate help command specifically groups commands by addon. I'm not sure how this should be accomplished, and if this matches the other help outputs. Ideally, any tools reading the JSON should be able to rely on the format being the same for all commands. This would keep the internals cleaner as well, including the human readable parser.

[stefanpenner]

Yes I am absolutely down for this. This should likely be transitioned to an rfc so we can nail the details

[trabus]

@thomassnielsen let me know if I can be of any assistance on this.

[thomassnielsen]

Made an RFC with a bit more detail. ember-cli/rfcs#12

Closing this in favor of the RFC.

Regarding assistance, anything that can get this feature closer to implementation would help: Suggesting improvements or details to the idea, finding potential flaws in the JSON format, suggesting specific implementation details, etc. For the moment, that would mainly mean keeping the RFC conversation going.

I'm not very familiar with the ember-cli internals, so I wouldn't know what would be affected by changes to the help output, especially regarding addons. I've read through the code around printBasicHelp and friends, but that's about it.