Add package design goals to CLI package documentation

Signed-off-by: Daniel Weiße <dw@edgeless.systems>

cli/internal/cloudcmd/cloudcmd.go

@@ -5,16 +5,17 @@ SPDX-License-Identifier: AGPL-3.0-only
 */
 
 /*
-Package cloudcmd provides executable command for the CLI.
+Package cloudcmd provides executable commands for the CLI.
 
 This package focuses on the interaction with the cloud provider.
 It separates the cloud provider specific code from the rest of the CLI, and
 provides a common interface for all cloud providers.
 
 Exported functions must not be cloud provider specific, but rather take a
-cloudprovider.Provider as an argument.
+cloudprovider.Provider as an argument, perform CSP specific logic, and return a universally usable result.
 
-User interaction happens in the cmd package, and should not happen or pass through
+It is used by the "cmd" to handle creation of cloud resources and other CSP specific interactions.
+User interaction happens in the "cmd" package, and should not happen or pass through
 this package.
 
 The backend to this package is currently provided by the terraform package.

cli/internal/clusterid/id.go

@@ -4,6 +4,8 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+// package clusterid defines the structure of the Constellation cluster ID file.
+// Logic in this package should be kept minimal.
 package clusterid
 
 import (

cli/internal/cmd/cmd.go

@@ -8,5 +8,15 @@ SPDX-License-Identifier: AGPL-3.0-only
 Package cmd provides the Constellation CLI.
 
 It is responsible for the interaction with the user.
+
+Logic should be kept to input/output parsing whenever possible.
+Any more complex code should usually be implemented in one of the other CLI packages.
+
+The code here should be kept as cloud provider agnostic as possible.
+Any CSP specific tasks should be handled by the "cloudcmd" package.
+
+All filepaths handled by the CLI code should originate from here.
+Common filepaths are defined as constants in the global "/internal/constants" package.
+To generate workspace correct filepaths for printing, use the functions from the "workspace" package.
 */
 package cmd

cli/internal/featureset/featureset.go

@@ -5,6 +5,7 @@ SPDX-License-Identifier: AGPL-3.0-only
 */
 
 // package featureset provides a way to check whether a feature is enabled in the current build.
+// This package should not implement any logic itself, but only define constants that are set at build time.
 package featureset
 
 // Edition is the edition of a build.

cli/internal/helm/helm.go

@@ -5,14 +5,26 @@ SPDX-License-Identifier: AGPL-3.0-only
 */
 
 /*
-Package helm provides a higher level interface to the Helm GO SDK.
+Package helm provides a higher level interface to the Helm Go SDK.
 
 It is used by the CLI to:
-- load embedded charts
-- install charts
-- update helm releases
-- get versions for installed helm releases
-- create local backups before running service upgrades
+
+  - load embedded charts
+  - install charts
+  - update helm releases
+  - get versions for installed helm releases
+  - create local backups before running service upgrades
+
+The charts themselves are embedded in the CLI binary, and values are dynamically updated depending on configuration.
+The charts can be found in “./charts/“.
+Values should be added in the chart's "values.yaml“ file if they are static i.e. don't depend on user input,
+otherwise they need to be dynamically created depending on a user's configuration.
+
+Helm logic should not be implemented outside this package.
+All values loading, parsing, installing, uninstalling, and updating of charts should be implemented here.
+As such, the helm package requires to implement some CSP specific logic.
+However, exported functions should be CSP agnostic and take a cloudprovider.Provider as argument.
+As such, the number of exported functions should be kept minimal.
 */
 package helm
 

cli/internal/kubernetes/kubernetes.go

@@ -5,9 +5,14 @@ SPDX-License-Identifier: AGPL-3.0-only
 */
 
 /*
-Package kubernetes provides functions to interact with a live cluster to the CLI.
+Package kubernetes provides functions to interact with a Kubernetes cluster to the CLI.
+The package should be used for:
 
-Currently it is used to implement the status and upgrade commands.
+  - Fetching status information about the cluster
+  - Creating, deleting, or migrating resources not managed by Helm
+
+The package should not be used for anything that doesn't just require the Kubernetes API.
+For example, Terraform and Helm actions should not be accessed by this package.
 */
 package kubernetes
 

cli/internal/libvirt/libvirt.go

@@ -4,7 +4,11 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
-// Package libvirt is used to start and stop containerized libvirt instances.
+/*
+Package libvirt is used to start and stop containerized libvirt instances.
+
+The code in this package should be kept minimal, and likely won't need to be changed unless we do a major refactoring of our QEMU/libvirt installation.
+*/
 package libvirt
 
 import (

cli/internal/terraform/terraform.go

@@ -5,12 +5,15 @@ SPDX-License-Identifier: AGPL-3.0-only
 */
 
 /*
-Package terraform handles creation/destruction of a Constellation cluster using Terraform.
+Package terraform handles creation/destruction of cloud and IAM resources required by Constellation using Terraform.
 
 Since Terraform does not provide a stable Go API, we use the `terraform-exec` package to interact with Terraform.
 
 The Terraform templates are located in the "terraform" subdirectory. The templates are embedded into the CLI binary using `go:embed`.
 On use the relevant template is extracted to the working directory and the user customized variables are written to a `terraform.tfvars` file.
+
+Functions in this package should be kept CSP agnostic (there should be no "CreateAzureCluster" function),
+as loading the correct values and calling the correct functions for a given CSP is handled by the `cloudcmd` package.
 */
 package terraform
 

cli/internal/upgrade/upgrade.go

@@ -5,6 +5,10 @@ SPDX-License-Identifier: AGPL-3.0-only
 */
 
 /*
-Package upgrade provides functionality to upgrade the cluster and it's resources
+Package upgrade provides functionality to upgrade the cluster and it's resources.
+
+TODO: Remove this package in favour of adding splitting its functionality onto the kubernetes, helm, and terraform packages.
+There should be no additions to this package at the current time.
+If you need to make larger changes to existing code, consider refactoring and moving relevant code to the kubernetes, helm, or terraform packages.
 */
 package upgrade