Improve cli project layout

[weikanglim]

As our codebase has involved with increasing complexity and functionality, we need a well-defined project layout that is able to organize things efficiently and with hopefully little confusion. I'd like the project layout to be opinionated as a result to avoid confusion.

Problem

The key problem that I've noticed is how to cleanly separate code for a given domain/subsystem such as auth, infra, environment. Taking a look at the environment package, we can see the desire for the following separation:

• The externals environment package that allows for reuse of core saving/loading of an azd environment
• The internals environment package for defining internal-only components of an azd environment
• The application-layer environment manager that is wired up in cmd

Proposal

After reviewing a few different examples, I've opted for the non-official standard project layout for Go: https://github.com/golang-standards/project-layout. The only caveat is instead of internal/app/azd, I'm opting for internal/azd to avoid the extra directory structure.

cmd/         // entrypoint for applications (CLIs/services) built in the repository
    azd/
        main.go
internal/
   azd/         // Application-layer logic for azd CLI. Only surfaced through wire by actions/commands
        auth/
        environment/
        cmd/         //  entry-point for all azd commands
   pkg/         // Internal library libraries to be consumed application wide.
        auth/         // Application shared library
        environment/
        azsdk/
        config/
pkg/         // Packages for external distribution. Unable to depend on internal packages
   cmdsubst/
   contracts/
   exec/    
   environment/ 
   osversion/
   password/
tools/
   azddocgen/
        main.go

Example

Let's say we're building a new subsystem for auth, that will be used in azd login and azd logout. We would do the following:

• For components that needs to be exposed to other application libraries, such as an azdCredential, it would go under internal/pkg/auth.
• For components that could be useful as a standalone package, such as a caching implementation, it can either go under pkg/auth or internal/pkg/auth depending on how separated it is from azd concepts.
• An authManager would go into internal/azd/auth. It would only be consumed by the cmd package.
• Finally, to create login and logout commands, we add the relevant code (command-design and action logic) into internal/azd/cmd.

We largely avoid package naming collision, since internal/azd/auth is only imported by cmd, whereas if internal/pkg/auth is imported by all other packages. The only time where collisions would happen is inside cmd, that could be reusing both the internal/azd/auth and internal/pkg/auth. In these case, we should aliasazd/authintoazdauth`.

[ellismg]

I love this idea.

One small note - to start with, I would prefer if we kept all our packages, with the exception of the "contracts" package inside of internal/pkg. The contracts package should be external because it's something we want to contractually guarantee about azd but I think the rest of the packages should remain internal. I don't think we want to give the impressions these are general purpose packages that are useful outside of the context of azd or that might be covered by anything that looks like the Go Compatibility Promise.