feat: user-friendly error messaging

This change introduces a new errors library we can use to surface
user-friendly error messaging. When user errors are used, the internal
technical details of the error message are not shown to the user unless
they run the command with the verbose option.

What the command will return now:

```shell
$ datumctl activity query
error: Authentication session has expired or refresh token is no longer valid.
Please re-authenticate using: `datumctl auth login`
```

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)
 	}
 }