log formatted error (#44353)

### What does this PR do?
ensure `setup` subcommand prints human readable errors

### Motivation
https://datadoghq.atlassian.net/browse/WINA-2100
show error with formatting (line breaks), not just in JSON blob

MSI log error

before
<img width="1200" height="407" alt="image" src="https://github.com/user-attachments/assets/0899b0d3-5ba1-47b7-ba7b-f798fc540334" />

after
<img width="1200" height="546" alt="image" src="https://github.com/user-attachments/assets/a6925dcd-7897-4069-8af4-7da25e32d299" />

---

cobra command error
before
```
> .\datadog-installer-x86_64.exe setup --banana
{"error":"unknown flag: --banana","code":0}
```
after
```
> C:\installer.exe setup --banana
unknown flag: --banana
```

Co-authored-by: branden.clark <branden.clark@datadoghq.com>

Author: clarkb7

cmd/installer/command/command.go

@@ -14,6 +14,7 @@ import (
 	"github.com/spf13/cobra"
 
 	pkgconfigsetup "github.com/DataDog/datadog-agent/pkg/config/setup"
+	"github.com/DataDog/datadog-agent/pkg/fleet/installer/commands"
 )
 
 // common constants for all the updater subcommands.
@@ -111,6 +112,9 @@ Datadog Installer installs datadog-packages based on your commands.`,
 		// TODO: Specific to Windows for now, as Linux needs more testing/validation of
 		//       the additional migration cases, and the main setup entrypoint is
 		//       currently `install.sh` not the `installer` binary.
+		agentCmd.Annotations = map[string]string{
+			commands.AnnotationHumanReadableErrors: "true",
+		}
 		agentCmd.RunE = func(cmd *cobra.Command, args []string) error {
 			if len(args) == 0 {
 				cmd.SetArgs([]string{"setup", "--flavor", "default"})

cmd/installer/command/command_test.go

@@ -0,0 +1,29 @@
+// Unless explicitly stated otherwise all files in this repository are licensed
+// under the Apache License Version 2.0.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2016-present Datadog, Inc.
+
+package command
+
+import (
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/DataDog/datadog-agent/pkg/fleet/installer/commands"
+)
+
+func TestMakeCommandHasHumanReadableAnnotationOnWindows(t *testing.T) {
+	cmd := MakeCommand(nil)
+
+	if runtime.GOOS == "windows" {
+		// We expect the default command to redirect to the setup command, which
+		// should print human-readable errors
+		assert.Equal(t, "true", cmd.Annotations[commands.AnnotationHumanReadableErrors],
+			"root command should have human-readable-errors annotation on Windows")
+	} else {
+		assert.Empty(t, cmd.Annotations[commands.AnnotationHumanReadableErrors],
+			"root command should not have human-readable-errors annotation on non-Windows platforms")
+	}
+}

cmd/installer/main.go

@@ -15,23 +15,36 @@ import (
 	"github.com/spf13/cobra"
 	"go.uber.org/dig"
 
+	"github.com/DataDog/datadog-agent/pkg/fleet/installer/commands"
 	installerErrors "github.com/DataDog/datadog-agent/pkg/fleet/installer/errors"
 )
 
 func main() {
 	os.Exit(runCmd(command.MakeCommand(subcommands.InstallerSubcommands())))
 }
 
+// formatError returns the error formatted as human-readable text or JSON
+// based on the command's annotations.
+//
+// Most commands are internal and will use JSON errors to communicate result to the parent process.
+// The setup command is a special case and will print human-readable errors.
+func formatError(cmd *cobra.Command, err error) string {
+	if cmd != nil && cmd.Annotations[commands.AnnotationHumanReadableErrors] == "true" {
+		return err.Error()
+	}
+	return installerErrors.ToJSON(err)
+}
+
 func runCmd(cmd *cobra.Command) int {
 	// always silence errors, since they are handled here
 	cmd.SilenceErrors = true
 
-	err := cmd.Execute()
+	executedCmd, err := cmd.ExecuteC()
 	if err != nil {
 		if rootCauseErr := dig.RootCause(err); rootCauseErr != err {
-			fmt.Fprintln(cmd.ErrOrStderr(), installerErrors.ToJSON(rootCauseErr))
+			fmt.Fprintln(cmd.ErrOrStderr(), formatError(executedCmd, rootCauseErr))
 		} else {
-			fmt.Fprintln(cmd.ErrOrStderr(), installerErrors.ToJSON(err))
+			fmt.Fprintln(cmd.ErrOrStderr(), formatError(executedCmd, err))
 		}
 		return -1
 	}

cmd/installer/main_test.go

@@ -0,0 +1,56 @@
+// Unless explicitly stated otherwise all files in this repository are licensed
+// under the Apache License Version 2.0.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2023-present Datadog, Inc.
+
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+
+	"github.com/DataDog/datadog-agent/pkg/fleet/installer/commands"
+)
+
+func TestFormatError_HumanReadable(t *testing.T) {
+	cmd := &cobra.Command{
+		Annotations: map[string]string{commands.AnnotationHumanReadableErrors: "true"},
+	}
+	err := errors.New("something went wrong")
+
+	result := formatError(cmd, err)
+
+	assert.Equal(t, "something went wrong", result)
+	assert.NotContains(t, result, `"code"`)
+}
+
+func TestFormatError_JSON(t *testing.T) {
+	cmd := &cobra.Command{}
+	err := errors.New("something went wrong")
+
+	result := formatError(cmd, err)
+
+	var parsed map[string]interface{}
+	unmarshalErr := json.Unmarshal([]byte(result), &parsed)
+	assert.NoError(t, unmarshalErr, "result should be valid JSON")
+	assert.Contains(t, parsed, "error")
+	assert.Contains(t, parsed, "code")
+	assert.Equal(t, "something went wrong", parsed["error"])
+}
+
+func TestFormatError_NilCommand(t *testing.T) {
+	err := errors.New("something went wrong")
+
+	result := formatError(nil, err)
+
+	// Should fall back to JSON when command is nil
+	var parsed map[string]interface{}
+	unmarshalErr := json.Unmarshal([]byte(result), &parsed)
+	assert.NoError(t, unmarshalErr, "result should be valid JSON")
+	assert.Contains(t, parsed, "error")
+	assert.Equal(t, "something went wrong", parsed["error"])
+}

pkg/fleet/installer/commands/command.go

@@ -31,6 +31,14 @@ import (
 	"github.com/DataDog/datadog-agent/pkg/version"
 )
 
+const (
+	// AnnotationHumanReadableErrors is the annotation key for commands that should
+	// display errors in human-readable format instead of JSON.
+	//
+	// For example, `setup` is run by humans and its output should be human readable.
+	AnnotationHumanReadableErrors = "human-readable-errors"
+)
+
 type cmd struct {
 	t              *telemetry.Telemetry
 	span           *telemetry.Span
@@ -215,6 +223,9 @@ func setupCommand() *cobra.Command {
 		Use:     "setup",
 		Hidden:  true,
 		GroupID: "installer",
+		Annotations: map[string]string{
+			AnnotationHumanReadableErrors: "true",
+		},
 		RunE: func(_ *cobra.Command, _ []string) (err error) {
 			cmd := newCmd("setup")
 			defer func() { cmd.stop(err) }()

pkg/fleet/installer/commands/command_test.go

@@ -116,3 +116,9 @@ func TestConfigAndPackageStates(t *testing.T) {
 
 	assert.Equal(t, expected, res)
 }
+
+func TestSetupCommandHasHumanReadableAnnotation(t *testing.T) {
+	cmd := setupCommand()
+	assert.Equal(t, "true", cmd.Annotations[AnnotationHumanReadableErrors],
+		"setup command should have human-readable-errors annotation")
+}

releasenotes/notes/fleet-setup-human-err-b5529cd2b0313f41.yaml

@@ -0,0 +1,4 @@
+---
+enhancements:
+  - |
+    The datadog-installer `setup` command now prints human-readable errors instead of mixing JSON and text.