List scripts available in environments for `--help` of `hatch run` and `hatch env run`

[kunaltyagi]

Sometimes I forget the scripts provided by the environment. I can perform a hatch env show and check the scripts, but I'd love to have a similar functionality in hatch run --help and hatch env run --help

Usually, my muscle memory already has typed hatch run and then I hit a blank. Getting the list of env:<command> on adding -h would be awesome

Originally posted by @kunaltyagi in https://github.com/pypa/hatch/discussions/1071

[funkyfuture]

that functionality would have a relatively big impact on the help output generation that would also affact users that are just looking for the cli reference to look up the commands they didn't internalize yet.

[kunaltyagi]

Could we resolve the issue of new users by demarcating the help, eg:

===================
Commands available in this project based on `pyproject.toml`:
<command>
<env>:<command>

[funkyfuture]

sorry, i may have been too implicit with my remarks:

to include the information that hatch env show provides, the configuration files would have to be parsed which adds time for just showing the cli help. you must assume that most other users' don't need the feature, but will be affected by a less performant cli.

it's generally never a good idea to design interfaces with multiple ways to obtain the same information. if you find things unintuitive that can be hints to an improvable overall design or user documentation or a lack of interest in it.

[kunaltyagi]

I don't buy the argument of a performant cli for the following reasons:

• --help is not a hot-path so performance doesn't matter that much
• --help giving good output is the desired route, and --help being fast and bad at helping is not desired
• hatch env run --help gives hypothetical examples. If we give concrete commands, we are enhancing the help, not burdening the users. And ofc, performance doesn't matter as much

it's generally never a good idea to design interfaces with multiple ways to obtain the same information

I don't think along the same lines:

1. hatch env show lists much more information including dependencies, features, env variables, type of env, etc
2. hatch run --help literally says:

   Run commands within project environments. This is a convenience wrapper
     around the [`env run`](#hatch-env-run) command.
   

   Technically, this goes against your position of multiple ways to access the same info

[funkyfuture]

hints to an improvable overall design

what about this:

• hatch [env] run's error output is amended with a list of available scripts per env
  • that would make it impossible to define a default which someone may propose at some point
  • it would sooner or later probably evoke the desire to allow short descriptions per script (and env) that would be displayed along in the list

Technically, this goes against your position of multiple ways to access the same info

nah, that's just a positivist argument. and i actually think it is not the best design.

[kunaltyagi]

Please don't shift goalposts. Both of your arguments are out of scope for --help and independent of this discussion. These details would be defined as per the PEPs governing pyproject.toml

[kenden]

It would be nice to be able to autocomplete the script to run with hatch run. (But don't think it should be done in the --help).

Somewhat unrelated, but getting just the list of commands could be done by adding like this to pyproject.toml:

[tool.hatch.envs.default.scripts]
list = [
    "echo 'Scripts commands available for default env:'; hatch env show --json | jq --raw-output '.default.scripts | keys[]'"
]

And then just typing hatch run list