search

fluidattacks / makes

A software supply chain framework powered by Nix.
https://makes.fluidattacks.tech/
MIT License
446 stars 43 forks source link

Integrate --help with CLI #740

Open kamadorueda opened 3 years ago

kamadorueda commented 3 years ago

Currently we handle help scripts like this:

You exec command --help:

image

then it runs and show:

image

Now that we have an excellent CLI, instead of having a markdown help that is invoked in the script itself, we can make it part of the CLI and render it once there is a full match for the output, in the bottom panel:

image

it would be faster, more dynamic, more accesible, auto-documented, and our CLI library already supports rendering markdown excellently

@blaggacao

kamadorueda commented 3 years ago

we can also introduce a 'help summary' displayed to the right of the command, and then it expands on full match or on-click

blaggacao commented 3 years ago

This sounds perfect! We should however maintain the --help contract for direct invocation.

blaggacao commented 3 years ago

The relevant contract here is that help is not null on any derivation:

https://github.com/fluidattacks/makes/blob/d4a5025ab4ae17a498f118bf26dece6b77867e35/src/args/make-derivation/default.nix#L20

kamadorueda commented 3 years ago

Yeah, I agree everything should have help, plus a flag for disabling adding such help to the CLI, as some apps may have their own --help already (for instance $ m f /skims --help comes from their source code and not from Makes injected help)

blaggacao commented 3 years ago

plus a flag for disabling adding such help to the CLI

m . /path/to/script -- --help

This is how the esacpe hatch is currently implemented. It was the best design I could come up with.

In the context of makes tasks, --help might still have a different focus. For example it might be a use case specific instruction whereas -- --help might just be the general command help.