command: rework HCP-related error messages

The HCP error messages were sometimes a bit terse in terms of the
information it bubbles up to the user.
This made them useful for people who already knew what to look for, but
newcomers would almost certainly be lost because of the lack of
information in those.

To improve on this situation, we reword most of those error messages in
this commit.

command/build.go

@@ -108,8 +108,10 @@ func (c *BuildCommand) RunContext(buildCtx context.Context, cla *BuildArgs) int
 		if err := ArtifactMetadataPublisher.Initialize(buildCtx); err != nil {
 			diags := hcl.Diagnostics{
 				&hcl.Diagnostic{
-					Summary:  "HCP Packer Registry iteration initialization failed",
-					Detail:   fmt.Sprintf("Failed to initialize iteration for %q\n %s", ArtifactMetadataPublisher.Slug, err),
+					Summary: "Failed to get HCP Packer Registry iteration",
+					Detail: fmt.Sprintf("Packer could not create an iteration or "+
+						"link the build to an existing iteration. Contact HCP Packer "+
+						"support for further assistance.\nError: %s", err),
 					Severity: hcl.DiagError,
 				},
 			}
@@ -142,8 +144,10 @@ func (c *BuildCommand) RunContext(buildCtx context.Context, cla *BuildArgs) int
 		if err := ArtifactMetadataPublisher.PopulateIteration(buildCtx); err != nil {
 			diags := hcl.Diagnostics{
 				&hcl.Diagnostic{
-					Summary:  "HCP Packer Registry build initialization failed",
-					Detail:   fmt.Sprintf("Failed to initialize build for %q\n %s", ArtifactMetadataPublisher.Slug, err),
+					Summary: "Failed to register builds to the HCP Packer registry iteration",
+					Detail: fmt.Sprintf("Packer could not register builds within your "+
+						"configuration to the iteration. Contact HCP Packer support "+
+						"for further assistance.\nError: %s", err),
 					Severity: hcl.DiagError,
 				},
 			}

command/core_wrapper.go

@@ -1,6 +1,8 @@
 package command
 
 import (
+	"fmt"
+
 	"github.com/hashicorp/hcl/v2"
 	packerregistry "github.com/hashicorp/packer/internal/registry"
 	"github.com/hashicorp/packer/packer"
@@ -57,8 +59,10 @@ func (c *CoreWrapper) ConfiguredArtifactMetadataPublisher() (*packerregistry.Buc
 	if err != nil {
 		return nil, hcl.Diagnostics{
 			&hcl.Diagnostic{
-				Summary:  "Invalid HCP Packer Registry configuration",
-				Detail:   err.Error(),
+				Summary: "Invalid HCP Packer configuration",
+				Detail: fmt.Sprintf("Packer could not validate the provided "+
+					"HCP Packer registry configuration. Check the error message for details "+
+					"or contact HCP Packer support for further assistance.\nError: %s", err),
 				Severity: hcl.DiagError,
 			},
 		}

command/registry.go

@@ -193,8 +193,12 @@ func createConfiguredBucket(templateDir string, opts ...bucketConfigurationOpts)
 
 	if bucket.Slug == "" {
 		diags = append(diags, &hcl.Diagnostic{
-			Summary:  "bucket name cannot be empty",
-			Detail:   "empty bucket name, please set it with the HCP_PACKER_BUCKET_NAME environment variable, or in a `hcp_packer_registry` block",
+			Summary: "Image bucket name required",
+			Detail: "You must provide an image bucket name for HCP Packer builds. " +
+				"You can set the HCP_PACKER_BUCKET_NAME environment variable. " +
+				"For HCL2 templates, the registry either uses the name of your " +
+				"template's build block, or you can set the bucket_name argument " +
+				"in an hcp_packer_registry block.",
 			Severity: hcl.DiagError,
 		})
 	}
@@ -205,8 +209,9 @@ func createConfiguredBucket(templateDir string, opts ...bucketConfigurationOpts)
 
 	if err != nil {
 		diags = append(diags, &hcl.Diagnostic{
-			Summary:  "Iteration initialization failed",
-			Detail:   fmt.Sprintf("Initialization of the iteration failed with %s", err),
+			Summary: "Iteration initialization failed",
+			Detail: fmt.Sprintf("Initialization of the iteration failed with "+
+				"the following error message: %s", err),
 			Severity: hcl.DiagError,
 		})
 	}

hcl2template/registry.go

@@ -1,6 +1,8 @@
 package hcl2template
 
 import (
+	"fmt"
+
 	"github.com/hashicorp/hcl/v2"
 	packerregistry "github.com/hashicorp/packer/internal/registry"
 )
@@ -25,8 +27,10 @@ func (cfg *PackerConfig) ConfiguredArtifactMetadataPublisher() (*packerregistry.
 	if err != nil {
 		return nil, hcl.Diagnostics{
 			&hcl.Diagnostic{
-				Summary:  "Invalid HCP Packer Registry configuration",
-				Detail:   err.Error(),
+				Summary: "Invalid HCP Packer configuration",
+				Detail: fmt.Sprintf("Packer could not validate the provided "+
+					"HCP Packer registry configuration. Check the error message for details "+
+					"or contact HCP Packer support for further assistance.\nError: %s", err),
 				Severity: hcl.DiagError,
 			},
 		}

internal/registry/types.iterations.go

@@ -65,10 +65,10 @@ func GetGitFingerprint(opts IterationOptions) (string, error) {
 	})
 
 	if err != nil {
-		return "", fmt.Errorf("Packer was unable to load a git sha. "+
-			"If your Packer template is not in a git repo, please add a unique "+
-			"template fingerprint using the env var HCP_PACKER_BUILD_FINGERPRINT. "+
-			"Error: %s", err)
+		return "", fmt.Errorf("Packer could not read the fingerprint from git." +
+			"\n\nIf your Packer template is not within a git managed directory, " +
+			"you can set the HCP_PACKER_BUILD_FINGERPRINT environment variable. " +
+			"The fingerprint must be less than 32 characters and can contain letters and numbers.")
 	}
 
 	// The config can be used to retrieve user identity. for example,
@@ -81,9 +81,14 @@ func GetGitFingerprint(opts IterationOptions) (string, error) {
 	// }
 	ref, err := r.Head()
 	if err != nil {
-		return "", fmt.Errorf("Packer encountered an issue reading the git info for the path %q.\n"+
-			"If your Packer template is not in a git repo, please add a unique "+
-			"template fingerprint using the env var HCP_PACKER_BUILD_FINGERPRINT. "+
+		// If we get there, we're in a Git dir, but HEAD cannot be read.
+		//
+		// This may happen when there's no commit in the git dir.
+		return "", fmt.Errorf("Packer could not read a git SHA in directory %q.\n"+
+			"This may happen if your template is in a git repository without any "+
+			"commits. You can either add a commit in this directory, or set the "+
+			"HCP_PACKER_BUILD_FINGERPRINT environment variable. The fingerprint "+
+			"must be less than 32 characters and can contain letters and numbers.\n"+
 			"Error: %s", opts.TemplateBaseDir, err)
 	}