npm run list commands

[vjpr]

Part of the beauty of npm scripts is that you can run npm run and see a list of all the scripts and the commands they run. No digging to find what a command does.

Is there a way to get a similar list of commands like npm run?

[searls]

Aside from whatever shell commands one might use to peruse a directory of scripts, no. scripty isn't under active development, but I'd definitely be open to a PR accomplishing something along these lines!

[jasonkarns]

Two utilities I use that have something akin to what I think you're asking...

git-hooks

icefox's git-hooks is a git subcommand for managing git hooks at a system, global, user, and repo levels. If you run the git hooks subcommand without arguments, by default it will list the hooks currently applied to the repo and print the output of invoking each script with the --about flag.

rbenv, nodenv

Rbenv (and nodenv) both have a help subcommand that is capable of printing help/usage/summary for any rbenv/nodenv subcommand including plugins. It does this by assuming a conventional format for summary and usage documentation in the script itself. Therefore, when invoked rbenv help foo will find the foo subcommand's executable (whether core or 3rd party plugin), and parse/scrape the help and usage information directly from the executable itself. (Primarily by using sed and awk to parse out the text directly from the executable's opening contiguous comment block. Another example, is rbenv's shell completion support, which looks for a "magic" code comment in the plugin, which indicates support for the --complete flag.

So I think we have two options for how to approach this.

1. Invoke the scripts with a predefined flag, and blindly hope that the script accepts this flag and does the right thing. Downsides: brittle, and potentially dangerous, depending on what the script does if invoked in an unexpected way.
2. Parse the "head" of scripts and scrape out some summary information from the scripts' comment section. Downsides: brittle and potentially complex parsing. Relies on somewhat consistent code comment style. (Remember, scripty doesn't require the scripts be shell or even node. Anything executable is acceptable.)

So I would vote for a combined option 3:

Determine a predefined flag (e.g. --about) that will be passed to the script to generate a one-line summary of the script. Parse the head of a script for a predetermined magic comment (eg, scripty-summary) which indicates opt-in support for accepting the predefined flag. Invoke the script with the predefined flag and echo the first line or two of its output.

This avoids the danger of invoking non-conforming scripts in an unexpected way. It avoids the complexity of parsing comments out of a myriad scripting languages. With the downsides that it requires explicit opt-in support from the scripts, and wouldn't work for actual binaries (as they couldn't be parsed for the opt-in magic comment).

I would probably welcome such a PR with this approach. However, I'm hesitant as to the actual utility of this mechanism. Personally, I would expect that the one-line summary of most scripts would be a near re-iteration of the script name. (Anytime I wish for this feature in my own scripts, is because the script itself isn't named as well as it could be.) And secondly I would be skeptical that there would be much adoption of this feature, especially as it would require parsing and handling an argument (whereas many scripts likely just iterate over their args or pass them blindly through to subcommands instead of actually parsing out options). For both of these reasons, it feels like the cost outweighs the benefit. But I'm happy to be swayed if others feel strongly!