cli: fix help message

[paul-marechal]

The CLI parsing logic is broken in @theia/cli. The help doesn't show
the right information.

The issue comes from using yargs at the script level in some places,
leading to corrupt global yargs state.

This commit refactors code around so that --help works as expected.

Fixes #1902

How to test

• Run yarn
• Run cd examples\browser
• yarn theia --help or npx theia --help should display a lot of commands, not just a few parameters.
• yarn theia <command> --help should display help for that command.
• yarn theia patate should fail with "unknown command" (code 1).

Review checklist

• as an author, I have thoroughly tested my changes and carefully followed the review guidelines

Reminder for reviewers

• as a reviewer, I agree to behave in accordance with the review guidelines

[msujew]

I can confirm that the help message is fixed by this change:

• theia --help displays all commands as well as general arguments (--help, --version, --app-target) ✔️
• theia generate --help shows the command parameters for generate (--mode and --split-frontend) ✔️
• theia <command> --help shows a general description of every command ✔️
• The message for running an unknown command was improved from non-existing or no command specified to Unknown command: <command> ✔️
• Every command still runs as expected (as far as I can tell) ✔️

Code LGTM as well, except for one exception, see below.

[vince-fugnitto]

I confirmed that the cli now displays the proper information:

gitpod /workspace/theia/examples/browser $ yarn theia --help
yarn run v1.22.10
$ /workspace/theia/node_modules/.bin/theia --help
theia <command>

Commands:
  theia start             Start the browser backend
  theia clean             Clean for the browser target
  theia copy              Copy various files from `src-gen` to `lib`
  theia generate          Generate various files for the browser target
  theia build             Generate and bundle the browser frontend using webpack
  theia rebuild           rebuild native node modules for the browser
  theia rebuild:browser   rebuild native node modules for the browser
  theia rebuild:electron  rebuild native node modules for the electron
  theia check:hoisted     Check that all dependencies are hoisted
  theia download:plugins  Download defined external plugins

Options:
  --help        Show help                                              [boolean]
  --version     Show version number                                    [boolean]
  --app-target  The target application type. Overrides `theia.target` in the
                application's package.json      [choices: "browser", "electron"]
Done in 0.54s.

gitpod /workspace/theia/examples/browser $ yarn theia start --help
yarn run v1.22.10
$ /workspace/theia/node_modules/.bin/theia start --help
theia start

Start the browser backend

Options:
  --help        Show help                                              [boolean]
  --version     Show version number                                    [boolean]
  --app-target  The target application type. Overrides `theia.target` in the
                application's package.json      [choices: "browser", "electron"]
Done in 0.88s.

I confirmed it works in electron as well:

gitpod /workspace/theia/examples/electron $ yarn theia --help
yarn run v1.22.10
$ /workspace/theia/node_modules/.bin/theia --help
theia <command>

Commands:
  theia start             Start the electron backend
  theia clean             Clean for the electron target
  theia copy              Copy various files from `src-gen` to `lib`
  theia generate          Generate various files for the electron target
  theia build             Generate and bundle the electron frontend using
                          webpack
  theia rebuild           rebuild native node modules for the electron
  theia rebuild:browser   rebuild native node modules for the browser
  theia rebuild:electron  rebuild native node modules for the electron
  theia check:hoisted     Check that all dependencies are hoisted
  theia download:plugins  Download defined external plugins

Options:
  --help        Show help                                              [boolean]
  --version     Show version number                                    [boolean]
  --app-target  The target application type. Overrides `theia.target` in the
                application's package.json      [choices: "browser", "electron"]
Done in 0.45s.

---

Did you mean to fail it for an unknown command? (it does fail without the --help flag)

gitpod /workspace/theia/examples/browser $ yarn theia vince --help
yarn run v1.22.10
$ /workspace/theia/node_modules/.bin/theia vince --help
theia <command>

Commands:
  theia start             Start the browser backend
  theia clean             Clean for the browser target
  theia copy              Copy various files from `src-gen` to `lib`
  theia generate          Generate various files for the browser target
  theia build             Generate and bundle the browser frontend using webpack
  theia rebuild           rebuild native node modules for the browser
  theia rebuild:browser   rebuild native node modules for the browser
  theia rebuild:electron  rebuild native node modules for the electron
  theia check:hoisted     Check that all dependencies are hoisted
  theia download:plugins  Download defined external plugins

Options:
  --help        Show help                                              [boolean]
  --version     Show version number                                    [boolean]
  --app-target  The target application type. Overrides `theia.target` in the
                application's package.json      [choices: "browser", "electron"]
Done in 0.63s.

A similar yarn command does:

gitpod /workspace/theia/examples/electron $ yarn vince --help
yarn run v1.22.10
error Command "vince" not found.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

[paul-marechal]

@vince-fugnitto I tried addressing your suggestion about invalid commands followed by --help but couldn't figure out something nice, not without fighting yargs itself. Although it allowed me to notice there's a strictCommand API that essentially does the check we were manually doing before for unknown commands, so I used that.

[paul-marechal]

I just polished the async queue a bit and fixed CI, turns out the --mode parameter was used both by Theia and Webpack, and I was not passing it to Webpack.

[vince-fugnitto]

I confirmed under different conditions that the --help displays correctly 👍
I believe it fixes the long standing issue #1902.

[paul-marechal]

#1902 wasn't fixed, but I just pushed a commit that fixes it.

The issue is that doing theia start --help doesn't show Theia's help but theia-cli's help. With this PR it will show Theia's help.