feat: new command asyncapi start preview implemented.

[neoandmatrix]

Description

This PR introduces the changes to implement the new command asyncapi start preview to open the studio in a minimal readOnly mode along with bundling the ref files internally. An argument to file needs to be passed that is to be opened.

Approach :-

• First after the path to file is passed it is first validated that the file exist. After the validation is complete then using the function findPathsToWatchFromSchemaRef the path to ref files are extracted.
• This function uses a stack data structure based approach instead of recursion based as in the later one in case of very large schemas memory consumption will be too much and may cause overflow issues. This makes it not optimal to be implemented hence using stack based approach to get all the path to ref files from schema and then adding them to be watched for changes
• After the files are added to be watched then the server starts and websocket connection starts which before anything sends a verification message preview:connected to the frontend so that frontend of studio can confirm and set the readOnly mode in studio.
• Then rest of the bundled contents of the file are sent and upon changes to any of the file the modified file is again bundled and message is sent to update the frontend.
• Also the websocket connection is also validated that the request to establish a websocket connection is coming from localhost and specified port only to further establish that the readOnly is being set through this command only.

Related issue(s)
Resolves #1627

[changeset-bot]

🦋 Changeset detected

Latest commit: 1e879a8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@asyncapi/cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[neoandmatrix]

Below is a attached demo of the same using the latest studio package and a file having ref. As seen from below the when file is updated or changed the changes sync correctly through the websocket.

Screen.Recording.2025-04-03.075657.mp4

If no file is passed studio doesn't start.

Also if there is an error while bundling the file like incorrect ref then also studio doesn't start.

[neoandmatrix]

Hey @Shurtu-gal done with all the changes for the preview command with the approach mentioned as above :-

Approach :- #1753 (comment)

Demo of working with the latest studio :- #1753 (comment).

Just before marking this PR ready for review wanted to confirm one thing that as we are bundling the files should we also allow to use the flags of the bundle command like --base=<value> , --baseDir=<value> .

Please take a look at the approach and the implemented checks form cli side. After confirmation will mark this ready for review and also will add corresponding docs and changeset.

[Shurtu-gal]

Let me play around with it a bit will let you know.

[neoandmatrix]

Let me play around with it a bit will let you know.

Yeah , sure.

[Shurtu-gal]

There still some problems.

1. Reloading the site makes it go away from readOnly and opens a full studio.
2. The tour guide modal still appears, need to disable that.
3. Maybe just me but logos not working 🤔

[Shurtu-gal]

Just before marking this PR ready for review wanted to confirm one thing that as we are bundling the files should we also allow to use the flags of the bundle command like --base=<value> , --baseDir=<value>

Yes, we should. The description should be verbose though to explain this.

[neoandmatrix]

There still some problems.

1. Reloading the site makes it go away from readOnly and opens a full studio.
2. The tour guide modal still appears, need to disable that.
3. Maybe just me but logos not working 🤔

1. Yes, it happens but the connection to server is then not there and even the file is not sent but the old one just stored in local storage of browser is used.

I didn't modify this behaviour as the command is preview so i thought refreshing studio is not expected as the changes will already be synchronised through websockets and any way editing a file with ref is not supported either in studio.

2. In my testing i never faced tour guide even once.

3. The logos of 🌐 , GitHub as and slack are working for me.

[neoandmatrix]

Just before marking this PR ready for review wanted to confirm one thing that as we are bundling the files should we also allow to use the flags of the bundle command like --base=<value> , --baseDir=<value>

Yes, we should. The description should be verbose though to explain this.

Okay will do. So should i add all the flags of bundle or just these mentioned two?

[Shurtu-gal]

Okay will do. So, should I add all the flags of bundle or just these mentioned two?

help and output not needed only thing left is xOrigin you can add that as well.

[neoandmatrix]

Okay will do. So, should I add all the flags of bundle or just these mentioned two?

help and output not needed only thing left is xOrigin you can add that as well.

Okay. Will do.

[neoandmatrix]

There still some problems.

1. Reloading the site makes it go away from readOnly and opens a full studio.
2. The tour guide modal still appears, need to disable that.
3. Maybe just me but logos not working 🤔

1. Yes, it happens but the connection to server is then not there and even the file is not sent but the old one just stored in local storage of browser is used.

I didn't modify this behaviour as the command is preview so i thought refreshing studio is not expected as the changes will already be synchronised through websockets and any way editing a file with ref is not supported either in studio.

2. In my testing i never faced tour guide even once.
3. The logos of 🌐 , GitHub as and slack are working for me.

Also anything on these, are modifications required or will work?

For first maybe we can add that refresh is not allowed in this mode.

[Shurtu-gal]

Yep, its fine then. Will try once more.

[neoandmatrix]

Yep, its fine then. Will try once more.

Sure, let me know if anything else is also expected but i missed. When all good will mark this ready for review and will add docs.

[Shurtu-gal]

Just some final things:

• Below comment
• Please run prettier and linter once.
• Solve the Sonarcloud issues: https://sonarcloud.io/project/issues?id=asyncapi_cli&pullRequest=1753&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true

[Shurtu-gal]

After resolving the above just add docs and mark it ready for review 🚀

[neoandmatrix]

Usage documentation added.

[neoandmatrix]

Everything done @Shurtu-gal . Please review. The failing test as known will only be solved after the merge of #1748.

[Shurtu-gal]

Awesome job! LGTM 🚀

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[aeworxet]

@asyncapi/bounty_team