Merge pull request #70 from datum-cloud/feat/user-friendly-error-messaging

feat: user-friendly error messaging

Author: scotwells

internal/authutil/credentials.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 	"sync"
 
+	customerrors "go.datum.net/datumctl/internal/errors"
 	"go.datum.net/datumctl/internal/keyring"
 	"golang.org/x/oauth2"
 )
@@ -24,7 +25,10 @@ const ActiveUserKey = "active_user"
 const KnownUsersKey = "known_users"
 
 // ErrNoActiveUser indicates that no active user is set in the keyring.
-var ErrNoActiveUser = errors.New("no active user set. Please login first")
+var ErrNoActiveUser = customerrors.NewUserErrorWithHint(
+	"No active user found.",
+	"Please login first using: `datumctl auth login`",
+)
 
 // StoredCredentials holds all necessary information for a single authenticated session.
 type StoredCredentials struct {
@@ -113,7 +117,11 @@ func (p *persistingTokenSource) Token() (*oauth2.Token, error) {
 		var retrieveErr *oauth2.RetrieveError
 		if errors.As(err, &retrieveErr) {
 			if retrieveErr.ErrorCode == "invalid_grant" || retrieveErr.ErrorCode == "invalid_request" {
-				return nil, fmt.Errorf("Authentication session has expired or refresh token is no longer valid. Please re-authenticate using: `datumctl auth login`")
+				return nil, customerrors.WrapUserErrorWithHint(
+					"Authentication session has expired or refresh token is no longer valid.",
+					"Please re-authenticate using: `datumctl auth login`",
+					err,
+				)
 			}
 		}
 		return nil, err

internal/errors/errors.go

@@ -0,0 +1,85 @@
+// Package errors provides custom error types for user-friendly error messaging.
+//
+// This package distinguishes between user-facing errors and technical errors,
+// allowing the CLI to display clean messages while preserving technical details
+// for debugging with verbose flags.
+package errors
+
+import (
+	"errors"
+	"fmt"
+)
+
+// UserError represents an error with a user-friendly message.
+//
+// UserError separates user-facing messages from technical implementation details,
+// making CLI output cleaner while preserving debugging information for verbose mode.
+type UserError struct {
+	// Message is the user-friendly error message displayed to users.
+	Message string
+
+	// Err is the underlying technical error, preserved for debugging
+	// but hidden from normal output.
+	Err error
+
+	// Hint provides actionable guidance to help users resolve the issue.
+	Hint string
+}
+
+// Error implements the error interface and returns the user-friendly message.
+//
+// If a hint is set, it appends the hint to the message on a new line.
+func (e *UserError) Error() string {
+	if e.Hint != "" {
+		return fmt.Sprintf("%s\n%s", e.Message, e.Hint)
+	}
+	return e.Message
+}
+
+// Unwrap returns the underlying technical error for error chain inspection.
+func (e *UserError) Unwrap() error {
+	return e.Err
+}
+
+// IsUserError checks whether an error chain contains a UserError.
+//
+// It uses errors.As to walk the error chain and returns the first UserError found.
+// The second return value indicates whether a UserError was found.
+func IsUserError(err error) (*UserError, bool) {
+	var userErr *UserError
+	if errors.As(err, &userErr) {
+		return userErr, true
+	}
+	return nil, false
+}
+
+// NewUserError creates a user-facing error with a message.
+//
+// Use this for simple errors that don't need hints or wrapped technical errors.
+func NewUserError(message string) *UserError {
+	return &UserError{Message: message}
+}
+
+// NewUserErrorWithHint creates a user-facing error with a message and actionable hint.
+//
+// The hint should provide specific instructions to help users resolve the issue,
+// such as command examples or documentation links.
+func NewUserErrorWithHint(message, hint string) *UserError {
+	return &UserError{Message: message, Hint: hint}
+}
+
+// WrapUserError wraps a technical error with a user-friendly message.
+//
+// The technical error is preserved for debugging with verbose flags but hidden
+// from normal output.
+func WrapUserError(message string, err error) *UserError {
+	return &UserError{Message: message, Err: err}
+}
+
+// WrapUserErrorWithHint wraps a technical error with a user-friendly message and hint.
+//
+// This combines a clean user message, actionable guidance, and technical details
+// for debugging.
+func WrapUserErrorWithHint(message, hint string, err error) *UserError {
+	return &UserError{Message: message, Hint: hint, Err: err}
+}

main.go

@@ -1,9 +1,12 @@
 package main
 
 import (
+	"fmt"
 	"os"
+	"strconv"
 
 	"go.datum.net/datumctl/internal/cmd"
+	customerrors "go.datum.net/datumctl/internal/errors"
 	"k8s.io/component-base/cli"
 	"k8s.io/component-base/logs"
 	kubectlcmd "k8s.io/kubectl/pkg/cmd"
@@ -14,6 +17,22 @@ func main() {
 	logs.GlogSetter(kubectlcmd.GetLogVerbosity(os.Args))
 	cmd := cmd.RootCmd()
 	if err := cli.RunNoErrOutput(cmd); err != nil {
+		// Check if this is a user-facing error
+		if userErr, ok := customerrors.IsUserError(err); ok {
+			// Print clean user-friendly error message
+			fmt.Fprintf(os.Stderr, "error: %s\n", userErr.Error())
+
+			// Show technical details in verbose mode (v >= 4)
+			verbosityStr := kubectlcmd.GetLogVerbosity(os.Args)
+			verbosity, _ := strconv.Atoi(verbosityStr)
+			if verbosity >= 4 && userErr.Err != nil {
+				fmt.Fprintf(os.Stderr, "\nDetails:\n%v\n", userErr.Err)
+			}
+
+			os.Exit(1)
+		}
+
+		// Fall back to standard kubectl error handling for technical errors
 		util.CheckErr(err)
 	}
 }