internal/hint: add structured hint mechanism for user-facing errors

Adds a small internal package that attaches actionable user guidance
to errors, separated from the error message itself. The hint is
exposed via the Hinter interface and is read out of the error chain
by the top-level renderer (a follow-up commit wires this up).

Keeping the hint out of err.Error() means substring-based test
assertions stay stable as hints are added or reworded, and gives the
CLI control over rendering (formatting, prefixing, future i18n) at a
single point instead of having every call site embed it inline.

Internal-only for now; can be promoted to a public API later if other
plugins (buildx, compose) want to share the convention.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

Author: dvdksn

internal/hint/hint.go

@@ -0,0 +1,51 @@
+// Package hint attaches actionable user guidance to errors.
+//
+// A hint describes what the user can do about a failure ("Run
+// 'docker rm foo' to remove it.") and is rendered separately from the
+// error's message by the top-level error handler. It is not part of
+// [error.Error], so substring matching on the error message stays
+// stable as hints are added or reworded.
+//
+// Use [Wrap] to attach a hint at the call site, and [Of] (or
+// [errors.As] against [Hinter]) to extract it for rendering.
+package hint
+
+import "errors"
+
+// Hinter is implemented by errors that carry actionable user guidance.
+type Hinter interface {
+	Hint() string
+}
+
+type errWithHint struct {
+	error
+	hint string
+}
+
+func (e *errWithHint) Hint() string  { return e.hint }
+func (e *errWithHint) Unwrap() error { return e.error }
+
+// Wrap attaches actionable guidance to err. It returns nil if err is
+// nil. The hint does not appear in the wrapped error's [error.Error]
+// output; it is read out of the chain by the top-level renderer via
+// [Of] (or [errors.As] against [Hinter]).
+func Wrap(err error, hint string) error {
+	if err == nil {
+		return nil
+	}
+	return &errWithHint{error: err, hint: hint}
+}
+
+// Of returns the first non-empty hint in the error chain, or "" if
+// none of the wrapped errors implement [Hinter].
+func Of(err error) string {
+	for err != nil {
+		if h, ok := err.(Hinter); ok {
+			if msg := h.Hint(); msg != "" {
+				return msg
+			}
+		}
+		err = errors.Unwrap(err)
+	}
+	return ""
+}

internal/hint/hint_test.go

@@ -0,0 +1,52 @@
+package hint
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"gotest.tools/v3/assert"
+)
+
+func TestWrap_NilError(t *testing.T) {
+	assert.Assert(t, Wrap(nil, "irrelevant") == nil)
+}
+
+func TestWrap_PreservesMessage(t *testing.T) {
+	err := Wrap(errors.New("bad input"), "Try --help.")
+	assert.Equal(t, err.Error(), "bad input")
+}
+
+func TestWrap_HintReadable(t *testing.T) {
+	err := Wrap(errors.New("bad input"), "Try --help.")
+
+	var h Hinter
+	assert.Assert(t, errors.As(err, &h))
+	assert.Equal(t, h.Hint(), "Try --help.")
+}
+
+func TestOf_FindsHint(t *testing.T) {
+	base := Wrap(errors.New("bad input"), "Try --help.")
+	wrapped := fmt.Errorf("context: %w", base)
+
+	assert.Equal(t, Of(wrapped), "Try --help.")
+}
+
+func TestOf_NoHint(t *testing.T) {
+	assert.Equal(t, Of(errors.New("plain")), "")
+	assert.Equal(t, Of(nil), "")
+}
+
+func TestOf_FirstNonEmpty(t *testing.T) {
+	// outer wrapper has empty hint; inner has content. Of should
+	// return the first non-empty hint.
+	inner := Wrap(errors.New("bad input"), "Try --help.")
+	outer := Wrap(inner, "")
+	assert.Equal(t, Of(outer), "Try --help.")
+}
+
+func TestUnwrap(t *testing.T) {
+	base := errors.New("bad input")
+	err := Wrap(base, "Try --help.")
+	assert.Assert(t, errors.Is(err, base))
+}