feat(cli): Add user hints to help fix errors (#95)

Author: dmcilvaney

internal/app/azldev/app.go

@@ -273,10 +273,12 @@ func (a *App) Execute(args []string) int {
 	// usage information, query the tool's version, etc. If the user attempts to run a command that
 	// requires configuration, then execution will stop just before running the command.
 	if err = a.initializeProjectConfig(envOptions, earlyTempDirPath); err != nil {
-		// Present an error, but move on.
+		// Present an error, but move on.  Store the error so we can set a fix suggestion
+		// on env once it's constructed.
 		slog.Error("Error loading configuration, execution may fail later;", "err", err)
 	}
 
+	configLoadErr := err
 	if err = a.reInitLoggingWithLogFile(envOptions); err != nil {
 		slog.Error("Error initializing file logging.", "err", err)
 
@@ -305,6 +307,12 @@ func (a *App) Execute(args []string) int {
 	env.SetVerbose(a.verbose)
 	env.SetQuiet(a.quiet)
 	env.SetColorMode(a.colorMode)
+
+	// If config loading failed, set a fix suggestion on env so it can be shown
+	// after any command error that requires config.
+	if configLoadErr != nil {
+		env.AddFixSuggestion(fmt.Sprintf("fix the configuration error: %v", configLoadErr))
+	}
 	//
 	// If we managed to find a project + configuration, then we can let anyone who was
 	// interested have an opportunity to add subcommands (or do whatever they need to
@@ -635,6 +643,8 @@ func (a *App) dispatchToCommand(env *Env, args []string) int {
 	if err != nil {
 		slog.Error("Error: " + err.Error())
 
+		env.PrintFixSuggestions()
+
 		return 1
 	}
 

internal/app/azldev/command.go

@@ -7,7 +7,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"log/slog"
 	"os"
 
 	"github.com/charmbracelet/x/term"
@@ -105,16 +104,15 @@ func runFuncInternal(innerFunc CmdWithExtraArgsFuncType, requireConfig bool) cob
 		}
 
 		if requireConfig && (env.Config() == nil || env.ProjectDir() == "") {
-			slog.Warn(
-				"!!! Unable to find and load valid Azure Linux project configuration.\n\n" +
-					"Please either use the -C option to specify a path to the root directory " +
+			env.AddFixSuggestion(
+				"Please either use the -C option to specify a path to the root directory " +
 					"of your Azure Linux project/repo, or else run this tool from within a directory " +
-					"tree that contains an 'azldev.toml' file at its root.\n\n" +
-					"Most commands will not function correctly without a valid configuration.\n\n" +
-					"------------------------------------------------------------------\n",
+					"tree that contains an 'azldev.toml' file at its root. " +
+					"Most commands will not function correctly without a valid configuration.",
 			)
 
-			return errors.New("a valid project and configuration are required to execute this command")
+			return errors.New(
+				"a valid project and configuration are required to execute this command")
 		}
 
 		results, err := innerFunc(env, args)

internal/app/azldev/env.go

@@ -8,13 +8,16 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"log/slog"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"runtime"
+	"strings"
 	"time"
 
 	"github.com/charmbracelet/gum/confirm"
+	"github.com/charmbracelet/x/term"
 	"github.com/mattn/go-isatty"
 	"github.com/microsoft/azure-linux-dev-tools/internal/global/opctx"
 	"github.com/microsoft/azure-linux-dev-tools/internal/projectconfig"
@@ -85,6 +88,10 @@ type Env struct {
 
 	// Start time: used for consistent timestamping of artifacts.
 	constructionTime time.Time
+
+	// Fix suggestion: a list of human readable hints that will be printed after an error to help the user
+	// resolve the issue. Printed in FIFO order.
+	fixSuggestions []string
 }
 
 // Constructs a new [Env] using specified options.
@@ -136,6 +143,9 @@ func NewEnv(ctx context.Context, options EnvOptions) *Env {
 
 		// Start time.
 		constructionTime: time.Now(),
+
+		// No fix suggestions to start.
+		fixSuggestions: []string{},
 	}
 }
 
@@ -279,6 +289,51 @@ func (env *Env) OutputDir() string {
 	return env.outputDir
 }
 
+// AddFixSuggestion records a human-readable hint that will be printed after an
+// error to help the user resolve the issue. Suggestions are printed in FIFO order.
+func (env *Env) AddFixSuggestion(suggestion string) {
+	env.fixSuggestions = append(env.fixSuggestions, suggestion)
+}
+
+// PrintFixSuggestions prints the current fix suggestions, if any.
+func (env *Env) PrintFixSuggestions() {
+	if len(env.fixSuggestions) == 0 {
+		return
+	}
+
+	// Use term.GetSize to guess at the width, defaulting to 80 if it fails.
+	// Subtract 15 to account for the slog head.
+	const slogHeadWidth = 15
+
+	consoleWidth, _, err := term.GetSize(os.Stderr.Fd())
+	if err != nil {
+		consoleWidth = 80
+	}
+
+	consoleWidth -= slogHeadWidth
+
+	padding := "    "
+	paddingSize := len(padding)
+
+	maxMsgLength := 0
+	for _, suggestion := range env.fixSuggestions {
+		if len(suggestion) > maxMsgLength {
+			maxMsgLength = len(suggestion)
+		}
+	}
+
+	boxWidth := max(0, min(consoleWidth, paddingSize+maxMsgLength+paddingSize))
+	boxEdgeString := strings.Repeat("=", boxWidth)
+
+	slog.Warn(boxEdgeString)
+
+	for _, suggestion := range env.fixSuggestions {
+		slog.Warn(padding + suggestion)
+	}
+
+	slog.Warn(boxEdgeString)
+}
+
 // CPUBoundConcurrency returns the recommended concurrency limit for CPU-bound tasks.
 // Returns [runtime.NumCPU], minimum 1.
 func (env *Env) CPUBoundConcurrency() int {

internal/app/azldev/env_test.go

@@ -132,3 +132,40 @@ func TestEnvWithCancel(t *testing.T) {
 	require.Error(t, child.Err())
 	assert.NoError(t, original.Err())
 }
+
+func TestFixSuggestions(t *testing.T) {
+	t.Run("no suggestions does not panic", func(t *testing.T) {
+		testEnv := testutils.NewTestEnv(t)
+		// Should not panic when no suggestions are present.
+		assert.NotPanics(t, func() {
+			testEnv.Env.PrintFixSuggestions()
+		})
+	})
+
+	t.Run("single suggestion does not panic", func(t *testing.T) {
+		testEnv := testutils.NewTestEnv(t)
+		testEnv.Env.AddFixSuggestion("run 'azldev component update -a'")
+		assert.NotPanics(t, func() {
+			testEnv.Env.PrintFixSuggestions()
+		})
+	})
+
+	t.Run("multiple suggestions does not panic", func(t *testing.T) {
+		testEnv := testutils.NewTestEnv(t)
+		testEnv.Env.AddFixSuggestion("first suggestion")
+		testEnv.Env.AddFixSuggestion("second suggestion")
+		testEnv.Env.AddFixSuggestion("third suggestion")
+		// Should not panic with multiple suggestions.
+		assert.NotPanics(t, func() {
+			testEnv.Env.PrintFixSuggestions()
+		})
+	})
+
+	t.Run("empty string suggestion does not panic", func(t *testing.T) {
+		testEnv := testutils.NewTestEnv(t)
+		testEnv.Env.AddFixSuggestion("")
+		assert.NotPanics(t, func() {
+			testEnv.Env.PrintFixSuggestions()
+		})
+	})
+}

scenario/__snapshots__/TestAzlDevWithInvalidConfig_stderr_1.snap

@@ -3,12 +3,11 @@ Parse error: /workdir/azldev.toml
  |        ~ expected character =
 
 ##:##:## ERR Error loading configuration, execution may fail later; err="error loading project configuration:\nfailed to load project configuration:\nproject config file \"/workdir/azldev.toml\" contains invalid data:\ntoml: expected character ="
-##:##:## WRN !!! Unable to find and load valid Azure Linux project configuration.
-
-Please either use the -C option to specify a path to the root directory of your Azure Linux project/repo, or else run this tool from within a directory tree that contains an 'azldev.toml' file at its root.
-
-Most commands will not function correctly without a valid configuration.
-
-------------------------------------------------------------------
-
 ##:##:## ERR Error: a valid project and configuration are required to execute this command
+##:##:## WRN =================================================================
+##:##:## WRN     fix the configuration error: error loading project configuration:
+failed to load project configuration:
+project config file "/workdir/azldev.toml" contains invalid data:
+toml: expected character =
+##:##:## WRN     Please either use the -C option to specify a path to the root directory of your Azure Linux project/repo, or else run this tool from within a directory tree that contains an 'azldev.toml' file at its root. Most commands will not function correctly without a valid configuration.
+##:##:## WRN =================================================================

scenario/__snapshots__/TestSnapshots_no-config_fix_hint_1.snap.json

@@ -0,0 +1,3 @@
+{
+ "ExitCode": 1
+}

scenario/__snapshots__/TestSnapshots_no-config_fix_hint_stderr_1.snap

@@ -0,0 +1,5 @@
+##:##:## INF No Azure Linux project found; some commands will not be available.
+##:##:## ERR Error: a valid project and configuration are required to execute this command
+##:##:## WRN =================================================================
+##:##:## WRN     Please either use the -C option to specify a path to the root directory of your Azure Linux project/repo, or else run this tool from within a directory tree that contains an 'azldev.toml' file at its root. Most commands will not function correctly without a valid configuration.
+##:##:## WRN =================================================================

scenario/__snapshots__/TestSnapshots_no-config_fix_hint_stdout_1.snap

@@ -31,6 +31,7 @@ func TestSnapshots(t *testing.T) {
 		"--help":                 cmdtest.NewScenarioTest("--help").Locally(),
 		"--help with color":      cmdtest.NewScenarioTest("--help", "--color=always").Locally(),
 		"--bogus-flag":           cmdtest.NewScenarioTest("--bogus-flag").Locally(),
+		"no-config fix hint":     cmdtest.NewScenarioTest("component", "list", "--all-components").Locally(),
 	}
 
 	for name, test := range tests {