CLI Specification

[jotamusik]

WIP
Setting up a context
The user will be able to set a specification file once and all actions after setting it, will be related to that specification file

Validation

Setup an option to be able to watch a specification file and reload the output when the file change

Generation

New Specification File

Some examples (from @derberg):

asyncapi set context ./asyncapi.yml
asyncapi validate --context=./asyncapi.yml
asyncapi validate #in case context was set
asyncapi create --context=./asyncapi.yml 
asyncapi get channels --context=./asyncapi.yml
asyncapi add channel
asyncapi new #new is not really a verb nor action but makes more sense than create I think

asyncapi generate --template=@asyncapi/html-template --context=./asyncapi.yml --output=./folder
asyncapi generate --model=java --context=./asyncapi.yml --output=./folder
asyncapi generate --model=java --context=./asyncapi.yml#/components/schemas/userCreate --output=./folder
asyncapi generate --model=java --context=(asyncapi get schema userCreate) --output=./folder

[fmvilas]

Love it so far. Simple and clean. For asyncapi validate, I think we could just use the existing Generator syntax. It would be like the following:

Usage: asyncapi generate [options] <asyncapi> <template>

- <asyncapi>: Local path or URL pointing to AsyncAPI specification file
- <template>: Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template

Options:
  -V, --version                  output the version number
  -d, --disable-hook [hooks...]  disable a specific hook type or hooks from given hook type
  --debug                        enable more specific errors in the console
  -i, --install                  installs the template and its dependencies (defaults to false)
  -n, --no-overwrite <glob>      glob or path of the file(s) to skip when regenerating
  -o, --output <outputDir>       directory where to put the generated files (defaults to current directory)
  -p, --param <name=value>       additional param to pass to templates
  --force-write                  force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir (defaults to false)
  --watch-template               watches the template directory and the AsyncAPI document, and re-generate the files when changes occur. Ignores the output directory. This flag should be used only for template development.
  -h, --help                     display help for command

[derberg]

That was fast man, thank you for taking a lead here!

If the input is a local file, there will be an option to automatictly detect file changes and auto reload the output

you mean like a --watch flag that keeps the cli running and watching for changes and reacting?

output file (maybe JSON)

what would be the content of this file?

---

in general I think we need to focus more on the CLI (interesting presentation here btw). Like try to imagine as many possible options we could see in the future and set some foundation for it now (like basic assumptions) so later on, adding another command doesn't feel like the CLI is actually composed of a number of different CLIs. I hope you know what I mean.

So basically when to use verbs and when nouns and be consistent. With kubectl it is

kubectl <action/verb> <noun/resource name>

kubectl get pod
kubectl delete pod

but with my beloved GitHub CLI (yes I like it a lot) it is:

gh <noun/resource name> <action/verb>

gh pr checkout
gh issue create

now how would it look like with asyncapi? I think best would be trying to list as many possible commands as you can imagine and then spot some pattern, like maybe:

asyncapi  <asyncapi-ref> <action/verb> <resource>

asyncapi ./asyncapi.yml validate
asyncapi ./asyncapi.yml create
asyncapi ./asyncapi.yml get channels
asyncapi ./asyncapi.yml get channel "/test/channel"
asyncapi ./asyncapi.yml edit channel "/test/channel"
asyncapi ./asyncapi.yml generate @asyncapi/html-template
asyncapi ./asyncapi.yml generate @asyncapi/html-template 

am I getting crazy here 😅 ? It is Friday afternoon, so you know 😄
of course, I don't mean all have to be implemented immediately, just set a basic UX for commands

[fmvilas]

Just some comment on what @derberg said. I'd make it like this:

asyncapi  <action/verb> <resource>

Because the AsyncAPI file might not be needed. For instance, to create a new AsyncAPI file with the default name, it could be asyncapi new. Each subcommand might take a different number of arguments. E.g., asyncapi new file --filename=my-asyncapi.yaml or asyncapi generate ./asyncapi.yml @asyncapi/html-template.

In any case, I think having both verb and resource "reserved" would make it easier to evolve. So for instance, asyncapi new could be sort for asyncapi new file. Just in case we want to add other "new" things, like a schema file (e.g., asyncapi new schema) or if we create a framework (wink wink) (e.g., asyncapi new project).

Does it make sense?

[derberg]

I like asyncapi <asyncapi-ref> as it puts asyncapi document in a center. I also get it might be confusing, especially that I would immediately like to have a feature where you set context for a given file just once, and then you do not need to refer to given document over and over. We could even have default, that if you do not provide file reference we read asyncapi.yml or asyncapi.json from cwd. This is how GH CLI works, where you do not have to specify repo name with each command.

asyncapi  <action/verb> <resource>

☝🏼 sounds best imho

asyncapi set context ./asyncapi.yml
asyncapi validate --context=./asyncapi.yml
asyncapi validate #in case context was set
asyncapi create --context=./asyncapi.yml 
asyncapi get channels --context=./asyncapi.yml
asyncapi add channel
asyncapi new #new is not really a verb nor action but makes more sense than create I think

# getting crazy here, just a bit, but just to break our thinking about current generator CLI, as we might think about generating more than just generating using the generator
asyncapi generate --template=@asyncapi/html-template --context=./asyncapi.yml --output=./folder
asyncapi generate --model=java --context=./asyncapi.yml --output=./folder
asyncapi generate --model=java --context=./asyncapi.yml#/components/schemas/userCreate --output=./folder
asyncapi generate --model=java --context=(asyncapi get schema userCreate) --output=./folder

[magicmatatjahu]

Maybe than new it should be init -> asyncapi init (file | schema | template | project)

[derberg]

@magicmatatjahu you sure? I have an impression that npm init is super not intuitive, I always have to look it up 😅

[magicmatatjahu]

@derberg The problem with new (as you mentioned) is that it's not a verb :) It's just a proposition. In general, I like the idea similar to k8s edit get etc.

[jotamusik]

you mean like a --watch flag that keeps the cli running and watching for changes and reacting?

Yeap! That's the idea, like nodemon when you are on development

what would be the content of this file?

I thought that in case you use the cli on a CI environment it could be useful to output the errors on this file.

---

I agree with @fmvilas that in terms of future it will be easier having the cli like asyncapi <action/verb> <resource> but I also like the way @derberg mentioned that we can 'set a context'. I think that this two concepts are compatible so I think that it would be great if we combine them

[jotamusik]

For those who know all the specification, what types of action would you like to be able to use with the CLI?
I'm asking because I know the specification since weeks ago so I don't have that general point of view 😅

For now, the things that I have in mind are:

• validating
• generating
• creating new specification file

But I have read in the comment above:

• editing already created channels
• getting channels

So I would like to know if this mean to edit through the command line or open an specific editor to edit the file 🤷🏻‍♂️

[derberg]

For the editing, it is the vision of the future how it works. For sure it needs to be supported on the same level of granularity as getting information. I mean, if I can do asyncapi get channel test/signup then I should also be able to do `asyncapi edit channel test/sig

nup` so I do not get editor with entire document but just given channel.

Some inspiration can be found in GitHub CLI and the issue creation process and usage of nano terminal editor.

1

2

3

but yeah, implementation details. As we agreed, let's start easy, and easiest is to do validation first, and a foundation for the project, so we know how the next commands should look like, and most important - how to test features

[jotamusik]

Today I'm going to start playing with Ink and try to make a TDD approach so the features' tests will be covered!

[KhudaDad414]

Hi, I'm Khudadad Nomani from Herat University, Herat, Afghanistan. I'm a fourth-year computer science student. I would love to work on this project as a GSoC student. Actually, I'm a little confused. I went through the guidelines and they mentioned starting working on an issue. since this project will start from zero, which other repositories would you recommend that I start working on so it helps me with this project? (@fmvilas saw your presentation here, learned a lot from it. thanks.)

[derberg]

@KhudaDad414 best would be if you could join our slack https://www.asyncapi.com/slack-invite/ and the #gsoc channel where we organize the work, where all students and mentors are

[Souvikns]

@derberg while validating will we give support to older spec versions.

[derberg]

@Souvikns our vision was always that it is better to invest in converters rather than maintain the old version. So I would say, we definitely need an option to run conversion, we forgot about it, thanks for pointing this out

[Souvikns]

would like to discuss the bootstrap parameters. How will the spec document be bootstrapped, will the CLI just create an empty yml or json file with the fixed fields or create the spec file by parsing some code.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[magicmatatjahu]

@Souvikns as the next task you can look at #7 I mean loading the spec from remote source. For that we can rename the --file flag to the --spec flag which will fetch spec if it will be remote source or use the local file.

[Souvikns]

On it 👍🏻.

[Souvikns]

@magicmatatjahu can you reopen #7 as this is a major feature. I think if we add --spec to load from url, we should also support contexts store URL strings. That means the contextService will have to be updated as well.

[magicmatatjahu]

@Souvikns Please describe the possible solution in the reopen issue :)

[fmvilas]

Have we considered adhering to these principles? https://clig.dev/#arguments-and-flags They seem reasonable and it's the "standard" way CLIs work.

[magicmatatjahu]

Insights on the use of flags - #7 (comment)

[derberg]

@fmvilas

Have we considered adhering to these principles? https://clig.dev/#arguments-and-flags They seem reasonable and it's the "standard" way CLIs work.

You mean there is something wrong? we do follow this approach in options like -f --file and others. What do you mean?

[fmvilas]

Nothing specific. I just wanted to raise awareness of https://clig.dev.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[derberg]

this was a kick-off issue, works continues in issues dedicated to specific command so closing this one