CLI new UI/UX implementation

[Amzani]

Problem

After #872 completion, we now have a visual direction of what needs to be implemented in the CLI.

Scope

• Implement new UI/UX foundations including a design system #1215
• Implement new UI/UX improvements in new command #1379
• Implement new UI/UX improvements in convert command #1381
• Implement new UI/UX improvements in generate command #1382
• Implement new UI/UX improvements in validate command #1385

[Shurtu-gal]

Great @Amzani, we can make some decisions in parallel too.

There was a great proposal by @fmvilas on clack

[Amzani]

Great @Shurtu-gal,
I don't know clack, does it replace oclif?
In case we need to change Oclif, this might help asyncapi/server-api#485 (comment)

[Shurtu-gal]

@Amzani I believe we can take it as a reference, and build our own design system to not face problems down the line.

Some reference https://codecryrepeat.hashnode.dev/learn-how-to-create-a-beautiful-cli-application-with-the-oclif-and-clackprompts

[Amzani]

@Shurtu-gal I see that we can just use @clack/prompts
https://codecryrepeat.hashnode.dev/learn-how-to-create-a-beautiful-cli-application-with-the-oclif-and-clackprompts
So you are not blocked by #1200

[aeworxet]

Bounty Issue's service comment

Text labels: bounty/2024-Q2, bounty/advanced, bounty/coding
First assignment to third-party contributors: 2024-03-22 00:00:00 UTC+12:00
End Of Life: 2024-08-31 23:59:59 UTC-12:00

@asyncapi/bounty_team

[Amzani]

@utnim2 @Shurtu-gal already started to work on the foundations, I think once he finish you can be part of it, as we need to implement DX in remaining commands.

[aeworxet]

@Amzani Please assign @Shurtu-gal and do not disperse the assignment, as unlike usual GitHub issues, the Bounty Issue can be worked on by only one person.

[Shurtu-gal]

@Amzani I was looking into this, and I am faced with some doubts:-
The current output looks something like:-

And the updated one is like given here

• How are we supposed to get the docs link for a specific error?
• How are we supposed to intelligently pass on next step for the user?

[Shurtu-gal]

Also clack/prompts is not required I suppose as similar things are there in oclif. Of course I will try it once and see if it provides any benefits and check things out.

[Amzani]

@Shurtu-gal

How are we supposed to get the docs link for a specific error?

The warning/errors that you mention are coming from spectral and our custom ruleset @smoya you confirm ?

How are we supposed to intelligently pass on next step for the user?

We can update the rulesets to inject the links, or do some magic with the parser, @smoya could have a better idea.

[smoya]

@Shurtu-gal

How are we supposed to get the docs link for a specific error?

The warning/errors that you mention are coming from spectral and our custom ruleset @smoya you confirm ?

Validation of v3 is done via some of the rules in https://github.com/asyncapi/parser-js/blob/58ae9387dd3d717af05debf8416deb1cac65bfd9/src/ruleset/ruleset.ts (those that are not filtered to apply exclusively to Spec v2) and https://github.com/asyncapi/parser-js/blob/58ae9387dd3d717af05debf8416deb1cac65bfd9/src/ruleset/v3/ruleset.ts, which are exclusive to Spec v3.

How are we supposed to intelligently pass on next step for the user?

We can update the rulesets to inject the links, or do some magic with the parser, @smoya could have a better idea.

Not trivial at all. We would need to either modify each of the functions that validate to understand the errors and match with some kind of dictionary of links/solutions, or rather parse the final output with some regex or similar and match with link/solutions. ATM, I can't think on a really easy to do stuff. For example, the rule that validates via JSON Schema is just one function, but under the hood uses a JSON Schema validator tool we don't control, so we only get an error message and a path to the error.

[aeworxet]

Bounty Issue's Timeline

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Advanced	2024-03-27	2024-04-01	2024-05-24	2024-04-19	2024-05-10	2024-05-24

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

Keep in mind the responsibility for violations of the Timeline.

[helios2003]

Hi @Amzani, I would like to work on the issues mentioned above. Can you please assign them to me? (If @Shurtu-gal is not working on them)

[helios2003]

I had an issue while testing the CLI, whenever I change any code in src/commands/new/file.ts for example build the project and run the asyncapi commands again, why isn't the new command displayed on the terminal? I checked and the correctly transpiled code is present in the ./lib directory as well. Should I do something else as well along with this command?

[aeworxet]

@helios2003, the above issues are atomic tasks of this Bounty Issue which is already assigned to @Shurtu-gal, and he IS working on them.

[helios2003]

Oh okay, since the issues were opened individually I thought they were open for other contributors as well. Thanks for the clarification @aeworxet

[peter-rr]

I had an issue while testing the CLI, whenever I change any code in src/commands/new/file.ts for example build the project and run the asyncapi commands again, why isn't the new command displayed on the terminal?

@helios2003 Could you be a bit more specific about this issue? Thanks :)

[helios2003]

Sure @peter-rr , so the issue I am experiencing is as follows:

When I make any changes in the files in the src directory (like making any changes to the prompts displayed to the user in the terminal) and run the command npm run build, the project builds and the modified transpiled code resides in the ./lib directory. After this when I try to run the required command, my custom prompts do not come appear the default prompts appear on the screen. So is there something I am missing or how do I make it work?

My general point is how do I view the changes I make in the CLI codebase myself?

[Shurtu-gal]

Hey @helios2003 are you using the ./bin/run to run it?

[helios2003]

Yes @Shurtu-gal

[Shurtu-gal]

Could you share the link to your branch where the changed code resides?

Would be easier to get to the root from there.

[helios2003]

Hey @Shurtu-gal, this is the link to the branch https://github.com/helios2003/cli/tree/check-error. I made a few trivial changes to the prompts (for demonstration purposes) and even after following the steps I mentioned above, the changed prompts weren't visible on screen. Can you please check if you can reproduce the same error on your side?

[Shurtu-gal]

Hey @Shurtu-gal, this is the link to the branch https://github.com/helios2003/cli/tree/check-error. I made a few trivial changes to the prompts (for demonstration purposes) and even after following the steps I mentioned above, the changed prompts weren't visible on screen. Can you please check if you can reproduce the same error on your side?

@helios2003, sadly I couldn't reproduce it. It's working perfectly fine as can be seen in the picture below.

Are you following the requisite steps?

• npm run build
• ./bin/run new file

[Shurtu-gal]

@Amzani all the commands have been migrated for which designs were provided.
I couldn't find designs for optimize, config and start command.

[helios2003]

@Shurtu-gal, I followed the required steps in my originally cloned repo, but the issue persisted. So, I decided to clone the project into a new path, and after setting it up, the problem disappeared, and it worked as expected. I suspect it may have been due to corruption along the particular path in my filesystem. Thanks a lot for the help, and my apologies for any inconvenience caused, as it turned out to be a local issue from my side.

[Shurtu-gal]

@Mayaleeeee could you please provide the designs for the rest of the commands as well.

[aeworxet]

@Shurtu-gal
If you have collected enough statistical information while doing PR #1302 and PR #1398 to understand in what direction the CLI commands' design goes, would you be able to do the rest of commands by yourself?
(new commands will be added over time anyway, so process for inheriting the design from the existing one needs to be developed in any case)

@Amzani
Would you agree with such an approach?

[Amzani]

@aeworxet yes, that was the initial idea to bootstrap the new DX direction and apply to the rest of commands.
We can even flag the remaining issues as first-time-issues

[aeworxet]

@Amzani
Decide, please, to what extent this issue should be completed so both

• this Bounty Issue could be considered completed
• Improve CLI UI and UX #872 could be closed

[Amzani]

Ok @aeworxet let's close it and consider it done.

[aeworxet]

Bounty Issue Completed 🎉

@Shurtu-gal, please go to the AsyncAPI page on Open Collective and submit an invoice for USD 400.00 with the expense title Bounty cli#1214, tag bounty, and full URL of this Bounty Issue in the description.