Enhancement: More robustly handle help requests in Truffle #5706

lsqproduction · 2022-11-15T17:39:25Z

PR description

This addresses #5662.
Currently, We have help as a truffle command. And since our truffle commands were built using Yargs, we also have yargs default help info display via truffle <cmd> help or truffle <cmd> --help.
Truffle's help command uses the command's meta.help object and Yargs help uses the command's meta.builder object. It's often the info in these two objects are miss matching causing the help outputs to be different.

Should we update the documentation to let users know about the other syntax for getting help?

For this, I explored two options and decided to go with option 1.

Turn off yargs's default for help. Use our own displayCommandHelp when --help is used anywhere in the command line.

Here are the reasons why I chose this option.
At this point, the info in the Help objects is more complete than in the Build object.
The output can be more customized.

Modify the inputStrings if they have --help in the command line before running through the command utils. As well as truffle --help <cmd>
I would love to know if there's a better way to handle this.
Added scenario testing of Help. Let me know if I'm missing any cases.
Do note, I did not include any fixes in this PR for getting help in truffle console or truffle develop.

Keep the current yargs default, and edit our Help command's run.js to use yargs's default showHelp() for the particular command.

There are still some limitations to using Yargs for this.
Need to inject the command's options as well as global options.
Not enough control over how the format of the output will look.

Testing instructions

truffle help <cmd> & truffle <cmd> --help & truffle --help <cmd> should have the same output.
run the help scenario test.

Documentation

I thought about documentation and added the doc-change-required label to this PR if documentation updates are required.

Breaking changes and new features

I have added any needed breaking-change and new-feature labels for the appropriate packages.

cds-amal

Thanks, @lsqproduction. It looks good, though I have a request to make the help system more inclusive to different invocations.

packages/core/cli.js

gnidan · 2022-11-15T21:41:21Z

Thanks for taking this on!

dongmingh

I ran the following test:
truffle help db
truffle --help db
truffle db help
truffle db --help
and they all give the same result:

  Usage:        truffle db <sub-command> [options]
  Available sub-commands: 
                serve 	Start the GraphQL server 
  Description:  Database interface commands

And
truffle help
truffle --help
also give the same results:

Truffle v5.6.5 - a development framework for Ethereum

Usage: truffle <command> [options]

Commands:
  cli.js build      Execute build pipeline (if configuration present)
  cli.js compile    Compile contract source files
  cli.js config     Set user-level configuration options
  cli.js console    Run a console with contract abstractions and commands
                    available
  cli.js create     Helper to create new contracts, migrations and tests
  cli.js dashboard  Start Truffle Dashboard to sign development transactions
                    using browser wallet
  cli.js db         Database interface commands
  cli.js debug      Interactively debug any transaction on the blockchain
  cli.js deploy     (alias for migrate)
  cli.js develop    Open a console with a local development blockchain
  cli.js exec       Execute a JS module within this Truffle environment
  cli.js help       List all commands or provide information about a specific
                    command
  cli.js init       Initialize new and empty Ethereum project
  cli.js migrate    Run migrations to deploy contracts
  cli.js networks   Show addresses for deployed contracts on each network
  cli.js obtain     Fetch and cache a specified compiler
  cli.js opcode     Print the compiled opcodes for a given contract
  cli.js preserve   Save data to decentralized storage platforms like IPFS and
                    Filecoin
  cli.js run        Run a third-party command
  cli.js test       Run JavaScript and Solidity tests
  cli.js unbox      Download a Truffle Box, a pre-built Truffle project
  cli.js version    Show version number and exit
  cli.js watch      Watch filesystem for changes and rebuild the project
                    automatically

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

Then I ran the same commands in truffle develop:

truffle(develop)> truffle db help
"ℹ️ : 'db' is not allowed within Truffle REPL"
truffle(develop)> truffle db --help
"ℹ️ : 'db' is not allowed within Truffle REPL"
truffle(develop)> truffle --help db
"ℹ️ : '--help' is not a valid Truffle command"

only truffle help db works properly:

truffle(develop)> truffle help db

  Usage:        truffle db <sub-command> [options]
  Available sub-commands: 
                serve 	Start the GraphQL server 
  Description:  Database interface commands

and truffle --help:

truffle(develop)> truffle --help
"ℹ️ : '--help' is not a valid Truffle command"

And, commands
truffle help
help
fail in truffle develop.

truffle(develop)> truffle help
TypeError: Cannot read properties of undefined (reading '#<Object>')
    at module.exports (/Users/dongminghwang/work/trufflesuite/truffle/packages/core/lib/commands/help/displayCommandHelp.js:9:46)
    at Object.module.exports [as run] (/Users/dongminghwang/work/trufflesuite/truffle/packages/core/lib/commands/help/run.js:5:11)
    at runCommand (/Users/dongminghwang/work/trufflesuite/truffle/packages/core/lib/command-utils.js:203:24)
truffle(develop)> help
TypeError: Cannot read properties of undefined (reading '#<Object>')
    at module.exports (/Users/dongminghwang/work/trufflesuite/truffle/packages/core/lib/commands/help/displayCommandHelp.js:9:46)
    at Object.module.exports [as run] (/Users/dongminghwang/work/trufflesuite/truffle/packages/core/lib/commands/help/run.js:5:11)
    at runCommand (/Users/dongminghwang/work/trufflesuite/truffle/packages/core/lib/command-utils.js:203:24)

Both truffle help help and help db work in truffle develop. If a subject, such as db, help, is required, we need to tell user about that.

lsqproduction · 2022-11-16T15:27:04Z

Thank you, @dongmingh for the review. You're right. Help in the truffle repls has been broken for a while too. I want to save that work for another PR if possible targeting #5312 and #2041.

cds-amal

Thanks, @lsqproduction. This PR should have tests to cover these new help cases. While manually testing, I noticed an error: Not enough non-option arguments: got 0, need at least 1.

test output

$ truffle db --help serve
cli.js db

Database interface commands

Commands:
  cli.js db serve  Start Truffle's GraphQL UI playground

Not enough non-option arguments: got 0, need at least 1

packages/core/cli.js

packages/core/lib/commands/db/meta.js

eggplantzzz · 2022-11-16T17:20:36Z

Note that we still need to maintain two versions of the options: the builder object and the options one.

Maybe it is worth rewriting the help so that all of the options are defined in terms of the information in the builder object? Does that make sense? Or rather maybe the help should get its information from the builder object instead of looking at options. If you are interested in something like this then ping me later and we can talk about it!

packages/core/lib/command-utils.js

packages/core/cli.js

packages/core/lib/command-utils.js

cds-amal

Hey @lsqproduction, It seems you merged develop into your branch. Can you rebase instead? I'm having a difficult time separating your commits while testing/reviewing.

This is what the commit log looks like

$ git log -40
Wed Dec 21 08:49:04 2022 -0500 32fa6b9f8 (HEAD -> betterHelp, origin/betterHelp) Merge branch 'develop' into betterHelp  [Liang Liang]
Sat Dec 17 18:52:45 2022 -0500 13280551b Merge pull request #5794 from trufflesuite/bump-w3  [tyler]
Fri Dec 16 15:37:55 2022 -0500 6a2316ec4 update expected message when connection to node fails for tests in provider  [eggplantzzz]
Fri Dec 16 14:40:43 2022 -0500 743259d65 fix some tests to deal with wonky type issues  [eggplantzzz]
Fri Dec 16 12:57:58 2022 -0500 1a8f1468c Merge branch 'develop' into betterHelp  [Liang Liang]
Fri Dec 16 12:01:34 2022 -0500 c1d71221c Merge pull request #5791 from trufflesuite/trufflemediate  [Harry Altman]
Fri Dec 16 11:25:47 2022 -0500 95c32972b bump web3 libs to 1.8.1  [eggplantzzz]
Thu Dec 15 18:40:34 2022 -0500 3d1c80d32 Update Ganache to 7.6.0  [Harry Altman]
Thu Dec 15 16:52:46 2022 -0500 c984fe37b (tag: v5.7.0, tag: [email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected], tag: @truffle/[email protected]) Publish  [eggplantzzz]
Thu Dec 15 16:31:47 2022 -0500 b278409c6 Merge pull request #5788 from trufflesuite/console-fix  [tyler]
Thu Dec 15 15:42:21 2022 -0500 7f833fd61 optimize logic  [eggplantzzz]
Thu Dec 15 13:31:50 2022 -0500 313164251 add condition checking for 1 source to determine whether to filter artifact  [eggplantzzz]
Thu Dec 15 12:24:46 2022 -0500 8ebc4668a don't load Truffle's console contract into the console environment  [eggplantzzz]
Thu Dec 15 10:18:01 2022 -0500 ac013dc46 Merge pull request #5785 from trufflesuite/fix-migrate  [tyler]
Wed Dec 14 23:14:02 2022 -0700 86b0e3d40 Merge pull request #5743 from trufflesuite/implement-1193-provider  [Sukanya Parashar]
Wed Dec 14 17:47:55 2022 -0500 f83cf2de7 core(console): add workaround for weird migration format  [cds-amal]
Wed Dec 14 15:11:11 2022 -0700 b50b9e5fa Use the word collision instead of race condition in the note  [Sukanya Parashar]
Wed Dec 14 15:12:47 2022 -0500 daa121c24 refactor logic to process help input  [liang liang]
Wed Dec 14 12:27:52 2022 -0700 9b2b9142d Add note for the requestId counter  [Sukanya Parashar]
Wed Nov 30 14:17:26 2022 -0500 28dcc7a72 add yarn.lock  [liang liang]
Wed Nov 30 14:07:27 2022 -0500 827964ea7 add missing deps to @core/package.json  [liang liang]
Wed Nov 30 12:14:58 2022 -0500 d3719e8df Move help inputStrings process to command-utils  [liang liang]
Wed Nov 30 11:07:42 2022 -0500 ea6b337b2 Add error handling when subCommand is invalid  [liang liang]
Wed Nov 30 11:02:57 2022 -0500 a7d674d9d Add handling when help cmd is in wrong place  [liang liang]
Wed Nov 30 11:00:34 2022 -0500 762744819 Add scenario test for Help cmd  [liang liang]
Tue Nov 29 14:14:37 2022 -0500 21002466d Add complete Help command usage info  [liang liang]
Tue Nov 29 10:06:10 2022 -0500 735b3be51 improve code comment readability  [liang liang]
Tue Nov 15 18:10:10 2022 -0500 2a30ac65a add handling for `truffle --help <cmd>`  [liang liang]
Tue Nov 15 10:56:19 2022 -0500 c90016be2 change inputStrings when help or --help is present  [liang liang]
Tue Nov 15 10:35:44 2022 -0500 891a309de turn off yargs default behavior for truffle cmd help  [liang liang]
Wed Dec 14 13:23:36 2022 -0500 3123c7b87 Implement console.log in Truffle (#5687)  [cds-amal]
Tue Dec 13 15:46:46 2022 -0500 bcbc02658 Merge pull request #5780 from trufflesuite/remove-invalidation  [tyler]
Tue Dec 13 14:52:49 2022 -0500 d9457529c Merge pull request #5782 from trufflesuite/fix/in-test-runnable  [g. nicholas d'andrea]
Tue Dec 13 13:25:02 2022 -0500 7899cad72 Merge pull request #5763 from trufflesuite/sneved  [Harry Altman]
Tue Dec 13 12:55:18 2022 -0500 077ca84d7 (fix/in-test-runnable) Slightly improve type  [g. nicholas d'andrea]
Mon Dec 12 20:05:46 2022 -0500 f93ca58d6 Switch Test's `mochaRunner` to be a Promise  [g. nicholas d'andrea]
Mon Dec 12 17:15:07 2022 -0500 85e682fe8 Simplify transfers of names  [Harry Altman]
Mon Dec 12 16:00:46 2022 -0500 d5b0970be add debug to config  [eggplantzzz]
Mon Dec 12 13:52:26 2022 -0500 972a5d91f move before setup into beforeEach for config test  [eggplantzzz]
Mon Dec 12 13:35:52 2022 -0500 0a818bab0 add some debug logging to config  [eggplantzzz]%

packages/core/cli.js

packages/core/lib/commands/help/meta.js

cds-amal

truffle db help could error better. See: https://github.com/trufflesuite/truffle/blob/develop/packages/core/lib/commands/db/run.js#L16

Maybe change it to Unknown truffle db command: ...

Changes were addressed.

packages/core/cli.js

packages/core/lib/commands/db/run.js

packages/core/lib/commands/help/meta.js

packages/dashboard/src/contexts/DashContext/state.ts

packages/dashboard/src/contexts/DashContext/types/Action.ts

packages/core/lib/commands/help/meta.js

packages/core/package.json

eggplantzzz

i like it!

sukanyaparashar · 2023-01-10T22:11:09Z

As mentioned in the testing instructions, should we have the same output for truffle <cmd> help and truffle help <cmd>? When I ran truffle help migrate, it shows the help for the "migrate" command but truffle migrate help doesn't show the help, instead it does the migration. Am I missing something here?
And this is the same result for "console" command too.

lsqproduction · 2023-01-10T22:31:51Z

testing instructions

Apologizes, @sukanyaparashar. I forgot to edit the test instructions.
We decided to change the requirement. Now, help as the commend will only work in the first position. for example:truffle help compile. User can use the flag --help anywhere to get help info.

sukanyaparashar · 2023-01-10T22:58:02Z

testing instructions

Apologizes, @sukanyaparashar. I forgot to edit the test instructions. We decided to change the requirement. Now, help as the commend will only work in the first position. for example:truffle help compile. User can use the flag --help anywhere to get help info.

Okay, that makes sense. Thanks @lsqproduction !

cds-amal

Looks good @lsqproduction. Nice work getting this one across the finish line.

cds-amal · 2023-01-10T23:55:36Z

packages/truffle/test/scenarios/commands/help.js

+    it("displays help for given command when `--help` is at final position of the command line", async function () {
+      await CommandRunner.run("compile --help", config);
+      const output = logger.contents();
+      assert(output.includes("Description:  Compile contract source files"));
+    }).timeout(20000);
+
+    it("displays help for given command when `--help` is at first position of the command line", async function () {
+      await CommandRunner.run("--help db serve", config);
+      const output = logger.contents();
+      assert(
+        output.includes("Description:  Start Truffle's GraphQL UI playground")
+      );
+    }).timeout(20000);
+
+    it("displays help for given command when `--help` is in the middle of the command line", async function () {
+      await CommandRunner.run("db --help serve", config);
+      const output = logger.contents();
+      assert(
+        output.includes("Description:  Start Truffle's GraphQL UI playground")
+      );
+    }).timeout(20000);


This isn't a change request. Just pointing out a unit test could validate the various --help positions, leaving only testing truffle help for integration tests.

I'm gonna come ask you about integration testing.

lsqproduction marked this pull request as ready for review November 15, 2022 19:16

lsqproduction requested review from eggplantzzz, cds-amal, sukanyaparashar and haltman-at November 15, 2022 19:16

cds-amal suggested changes Nov 15, 2022

View reviewed changes

packages/core/cli.js Outdated Show resolved Hide resolved

lsqproduction force-pushed the betterHelp branch from 5a861b8 to d97eb3f Compare November 15, 2022 23:11

lsqproduction requested a review from cds-amal November 15, 2022 23:14

cds-amal requested a review from dongmingh November 16, 2022 13:28

dongmingh reviewed Nov 16, 2022

View reviewed changes

cds-amal suggested changes Nov 16, 2022

View reviewed changes

packages/core/cli.js Outdated Show resolved Hide resolved

packages/core/cli.js Outdated Show resolved Hide resolved

eggplantzzz reviewed Nov 16, 2022

View reviewed changes

packages/core/lib/commands/db/meta.js Outdated Show resolved Hide resolved

lsqproduction force-pushed the betterHelp branch from d97eb3f to 3e18921 Compare November 30, 2022 17:30

lsqproduction requested review from eggplantzzz, cds-amal and dongmingh November 30, 2022 19:50

lsqproduction force-pushed the betterHelp branch 2 times, most recently from a4904a3 to d460f95 Compare December 13, 2022 19:13

eggplantzzz reviewed Dec 14, 2022

View reviewed changes

packages/core/lib/command-utils.js Outdated Show resolved Hide resolved

eggplantzzz reviewed Dec 14, 2022

View reviewed changes

packages/core/lib/command-utils.js Outdated Show resolved Hide resolved

eggplantzzz reviewed Dec 14, 2022

View reviewed changes

packages/core/cli.js Outdated Show resolved Hide resolved

eggplantzzz reviewed Dec 14, 2022

View reviewed changes

packages/core/lib/command-utils.js Outdated Show resolved Hide resolved

eggplantzzz reviewed Dec 14, 2022

View reviewed changes

packages/core/lib/command-utils.js Outdated Show resolved Hide resolved

lsqproduction force-pushed the betterHelp branch from d460f95 to daa121c Compare December 14, 2022 20:13

lsqproduction requested a review from eggplantzzz December 14, 2022 21:49

cds-amal reviewed Jan 3, 2023

View reviewed changes

packages/core/cli.js Outdated Show resolved Hide resolved

lsqproduction force-pushed the betterHelp branch from 32fa6b9 to e4fa898 Compare January 4, 2023 21:30

eggplantzzz reviewed Jan 9, 2023

View reviewed changes

packages/core/lib/commands/help/meta.js Outdated Show resolved Hide resolved

lsqproduction added 2 commits January 9, 2023 14:35

refactor processHelpInput

0265837

refact processHelpInput to inline check on cli.js

1ef1776

lsqproduction changed the title ~~Bug Fix: Produce same output fortruffle help <cmd> & truffle <cmd> help || --help~~ Bug Fix: Handle --help as the help command Jan 9, 2023

lsqproduction requested review from cds-amal and eggplantzzz January 9, 2023 22:11

cds-amal reviewed Jan 9, 2023

View reviewed changes

error better for unknown truffle db command

580324e

lsqproduction requested a review from cds-amal January 10, 2023 00:48

sukanyaparashar reviewed Jan 10, 2023

View reviewed changes

packages/core/cli.js Show resolved Hide resolved

cds-amal requested a review from sukanyaparashar January 10, 2023 20:44