feat: ACNA-2785 - generate VS Code config for an App Builder Project

[shazron]

Description:

To debug, you will need to use Visual Studio Code, but you will not have the launch configuration yet in your project. Thus we need a new command to bootstrap your project: aio app dev init.

aio app dev debugging does not work without it being in a VS Code context, so we restrict it to that.

1. Introduces a new aio app dev init command - will install the .vscode/launch.json configuration so users can debug in Visual Studio Code (perhaps this can be run after aio app init?)
2. Modifies aio app dev so it can only run in the Visual Studio Code context, and not in the regular terminal

How Has This Been Tested?

• local link of the plugin
• debug in VS Code of an AB project after running aio app dev init
• run aio app dev in the Terminal (should error out)
• run aio app dev init in the Terminal (should install the .vscode launch config)
• unit tests are expected to fail since we haven't completed unit tests yet

Test Steps

1. Run the App Builder: debug actions configuration in the VS Code Debug tab. Modify any action code, put a breakpoint in it. Note that the breakpoint will not be "active" until the action is actually hit by calling the action url, only after it is called will the script be loaded, and the execution will stop at the breakpoint
2. Run the App Builder: debug full stack configuration in the VS Code Debug tab. Modify any static asset code (javascript):
   1. Under the VS Code Debug tab, find the Loaded Scripts section.
   2. Under that section, find the sub-section Browser Debug: <your app name>.
   3. In there, you will find __parcel_source_root
   4. In a sub-heading you will find the static asset source. You can put your breakpoints in the code there.

Dev Experience Improvements (Future?)

1. Ability to have active breakpoints in the action code
2. Ability to set breakpoints in the web-src code directly instead of the way outlined above

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• I have signed the Adobe Open Source CLA.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[moritzraho]

Why do we need aio app dev to error out if run from a terminal?
Users should be able to run a local environment even if they don't use the debugger, right?

Also, while I feel generating the config via an init command is better than during run or dev, I would still advocate for having an app builder vscode extension in the long run and make the CLI editor agnostic

[shazron]

Why do we need aio app dev to error out if run from a terminal? Users should be able to run a local environment even if they don't use the debugger, right?

This is true. I only had "IDE Debugging" on my mind, and excluded "console.log" debugging. I can remove the affected changes.

I also considered the "old" way of aio app run --local, where the user ran the command in the Terminal, and then would launch VS Code with their project open, then run Debug. This was a two step process. They can't do that anymore since for VS Code debugging to work it has to run in VS Code's node-terminal launch config, and the two will be separate instances.

Also, while I feel generating the config via an init command is better than during run or dev, I would still advocate for having an app builder vscode extension in the long run and make the CLI editor agnostic

It is editor agnostic, the restriction was based on not confusing users used to the old two-step process (the changes will be reverted). aio app dev does not have any VS Code specific code.

[MichaelGoberling]

while being able to run dev in other terminals makes sense, i still like the idea of only running certain things given the user's environment - i.e. maybe we check to see if the user is running aio app dev in vscode, and if they are then we run init, otherwise they may just be in the terminal or some other IDE and won't not need the vscode config?

[shazron]

while being able to run dev in other terminals makes sense, i still like the idea of only running certain things given the user's environment - i.e. maybe we check to see if the user is running aio app dev in vscode, and if they are then we run init, otherwise they may just be in the terminal or some other IDE and won't not need the vscode config?

good point. they will need to run it in a VS Code terminal for this to work. Still some friction, versus us perhaps just running it after a aio app init (so they get it no matter what)

Elaborating further to my reply to Moritz - you can run aio app dev in any terminal, then via a VS Code Launch configuration, attach to the node process (you pick the process from a list of node processes). But I think this is too much friction versus just running a specific launch config that does everything.

[moritzraho]

It is editor agnostic

The CLI generates vscode-specific configuration, we always did this, it's fine, just meant to open up for future discussion that we could provide the debugger configuration via an extension as well.

Elaborating further to my reply to Moritz - you can run aio app dev in any terminal, then via a VS Code Launch configuration, attach to the node process (you pick the process from a list of node processes). But I think this is too much friction versus just running a specific launch config that does everything.

interesting, would it be possible to do both? support run from terminal to have a local dev env and 1-step debugging (run from vscode)?

[shazron]

interesting, would it be possible to do both? support run from terminal to have a local dev env and 1-step debugging (run from vscode)?

I think it will be confusing and in my opinion not a good developer experience. Why would they run aio app dev in the Terminal, then attach to it via a launch configuration in VS Code? Why not just launch both via one button in VS Code? Is there be an actual use case for this scenario? Support to do so would be just by adding another launch config.

[moritzraho]

I think we are speaking about the same thing unless I am misunderstanding :D. I meant:

• be able to run from a terminal to run the local env (no debugging)
• be able to debug by pressing the debug button in vscode (without having to explicitly run aio app dev before)

[shazron]

I think we are speaking about the same thing unless I am misunderstanding :D. I meant:

• be able to run from a terminal to run the local env (no debugging)
• be able to debug by pressing the debug button in vscode (without having to explicitly run aio app dev before)

yes, both scenarios are possible with this, thus we are in agreement

[purplecabbage]

I am not sure the bundlePort vs serverPort logic belongs in this pr. This seems related to frontend hot reloading.

[shazron]

removed aio app dev init command - existing users can read an upgrade doc dc3f4d7

[shazron]

The original intent of this PR has changed. This has turned out to be just prep for #15 - and that PR has all of this PR's commits anyway. Closing.