Consider adding plugin cmds to kn --help

[duglin]

In what area(s)?

Classifications:
/kind good-first-issue
/kind feature
/kind proposal

Describe the feature:

Once we have #249 merged, we should consider making kn --help show the list of available plugins. I still think having the plugin command is good, but from a UX perspective one of the points of the plugin model is that the user is (for the most part) unaware that they're using a plugin vs a built-in command. So, if we can make kn --help show the list of plugins under some kind of misc section I think that would be really helpful. Even if the help text for each one just said see kn foo for more details, the name of the command should at least provide a hint as to what it does. Often times people know there's a certain command they want to run but can't remember the name (get vs describe vs inspect vs ... ) so kn --help showing the full list of cmds will help them find what they're looking for.

[maximilien]

/assign @maximilien

[maximilien]

The simplest (MVP) addition is to list the discovered plugins under the set of available commands, so essentially the following, assuming two plugins kn-hi and kn-bye are installed:

Option 1:

➜  client git:(master) ✗ ./kn -h
Manage your Knative building blocks:

* Serving: Manage your services and release new software to them.
* Eventing: Manage event subscriptions and channels. Connect up event sources.

Usage:
  kn [command]

Available Commands:
  help        Help about any command
  revision    Revision command group
  route       Route command group
  service     Service command group
  version     Prints the client version

Available Plugins:
   hi, bye

Flags:
      --config string       config file (default is $HOME/.kn/config.yaml)
  -h, --help                help for kn
      --kubeconfig string   kubectl config file (default is $HOME/.kube/config)

Use "kn [command] --help" for more information about a command.

OR for a different, more verbose, formatting:

Option 2:

➜  client git:(master) ✗ ./kn -h
Manage your Knative building blocks:

* Serving: Manage your services and release new software to them.
* Eventing: Manage event subscriptions and channels. Connect up event sources.

Usage:
  kn [command]

Available Commands:
  help        Help about any command
  revision    Revision command group
  route       Route command group
  service     Service command group
  version     Prints the client version

Available Plugins:
   hi    /usr/local/bin/kn-hi
   bye   /usr/local/bin/kn-bye

Flags:
      --config string       config file (default is $HOME/.kn/config.yaml)
  -h, --help                help for kn
      --kubeconfig string   kubectl config file (default is $HOME/.kube/config)

Use "kn [command] --help" for more information about a command.

Assuming plugins are installed in /usr/local/bin.

Eventually we could force a simple contract on plugins, e.g., respond to --metadata with a formatted JSON output or YAML that would have various information, e.g., Short and Long description, Usage, and Flags information. This would allow a more detailed formatting of help on behalf of plugins (when needed).

In the spirit of staying agile and getting small things done first to test with customers ASAP. I would rather do option 1 or 2 for now and as we start getting users of plugins and creators of plugins we can explore more complicated implementations.

Of course, if we add more contract requirements to plugins, we would need to do so before v1.0 so that plugins don't have to be forced to a contract after first release and be invalid soon after.

[duglin]

Even though I don't see much value in showing the path for each plugin, I think showing each one on their own line is easier to read. And +1 to doing the --metadata stuff eventually.

[rhuss]

Eventually we could force a simple contract on plugins, e.g., respond to --metadata with a formatted JSON output or YAML that would have various information, e.g., Short and Long description, Usage, and Flags information. This would allow a more detailed formatting of help on behalf of plugins (when needed).

This kind of 'contract' is also suggested in https://docs.google.com/document/d/1T51o_sLUxjSKJq49zvTNQ0u8HlWwmK7fKnxPEnOZ2WI/edit#bookmark=id.s0wen9pac7lp

Tbh, its this kind of Plugin API which make it to a "Plugin". What we are discussing here is more like a "Delegate". But your mileage may vary ;-)

I really would love to see something like

kn help

Available commands:
    service - ....
    revision - ....
    ...
....
Plugins: 
    hi          -  Prints out hi
    bye       -  Say goodbye
.....

and then

kn hi help

Print out 'hi' 

Options:
      --name   who to greet 
      ....

i.e. to enforce that each plugin provides a help message and a short description to be used in the help message. E.g. a kn-hi manifest would be required and this command then returns

name: hi
description: Print out hi
commands:
    - name: hello
       description: alternate welcome message
       commands: 
       - name: world
          description: deeper commands
      ....
options:
    - name: name
       description: who to greet

This would allow for a streamline help message which has the same structure for every plugin and leads to a seamless UI without media break. The simpler alternative to letting every plugin write out its own help message is easier to implement, but very likely will lead to divergent user experience.

[maximilien]

Yup, I already implemented this. Just waiting to add after we get the core thing in. I think we need to discuss it since the one could argue that a more relax delegate is better and that the help for a plug-in should come from sending the help command to the plugin — the current implementation will do fine.

[rhuss]

@maximilien is it then also already that for a plugin kn-service-inspect it would appear in kn service help ? (I mean multilevel plugins should only appear when their n-1 level's help is called)

[maximilien]

Actually only top level. But I have no tests for this. So after #249 I'll look into implementing this fully and test it. I think also that with a --metadata contract that returns info about plugins this will make crafting help sections for plugins relatively easy.