chore: Standardise Error Codes (#286)

* fix: Misc error handling fixes

* fix: Sandbox error translation

cmd/cloud/login.go

@@ -3,9 +3,9 @@ package cloud
 import (
 	"github.com/safedep/dry/cloud"
 	"github.com/safedep/dry/log"
-	"github.com/safedep/pmg/internal/ui"
 	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/errcodes"
+	"github.com/safedep/pmg/internal/ui"
 	"github.com/spf13/cobra"
 )
 

cmd/cloud/logout.go

@@ -3,9 +3,9 @@ package cloud
 import (
 	"github.com/safedep/dry/cloud"
 	"github.com/safedep/dry/log"
-	"github.com/safedep/pmg/internal/ui"
 	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/errcodes"
+	"github.com/safedep/pmg/internal/ui"
 	"github.com/spf13/cobra"
 )
 

cmd/cloud/sync.go

@@ -5,12 +5,12 @@ import (
 	"time"
 
 	"github.com/safedep/dry/log"
+	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/config"
+	"github.com/safedep/pmg/errcodes"
 	"github.com/safedep/pmg/internal/analytics"
 	"github.com/safedep/pmg/internal/audit"
 	"github.com/safedep/pmg/internal/ui"
-	"github.com/safedep/dry/usefulerror"
-	"github.com/safedep/pmg/errcodes"
 	"github.com/spf13/cobra"
 )
 

cmd/sandbox/doctor_test.go

@@ -10,10 +10,10 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	pmgsandbox "github.com/safedep/pmg/sandbox"
-	"github.com/safedep/pmg/sandbox/platform"
 	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/errcodes"
+	pmgsandbox "github.com/safedep/pmg/sandbox"
+	"github.com/safedep/pmg/sandbox/platform"
 )
 
 // stubProbe is a minimal probe used by tests.

cmd/sandbox/explain.go

@@ -8,11 +8,11 @@ import (
 	"strings"
 	"time"
 
+	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/config"
+	"github.com/safedep/pmg/errcodes"
 	"github.com/safedep/pmg/internal/ui"
 	pmgsandbox "github.com/safedep/pmg/sandbox"
-	"github.com/safedep/dry/usefulerror"
-	"github.com/safedep/pmg/errcodes"
 	"github.com/spf13/cobra"
 )
 

cmd/sandbox/explain_test.go

@@ -12,9 +12,9 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/errcodes"
+	pmgsandbox "github.com/safedep/pmg/sandbox"
 )
 
 func sampleReport() *pmgsandbox.ViolationReport {

cmd/sandbox/helpers.go

@@ -9,10 +9,10 @@ import (
 	"regexp"
 	"strings"
 
-	"github.com/safedep/pmg/internal/ui"
-	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/errcodes"
+	"github.com/safedep/pmg/internal/ui"
+	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/spf13/cobra"
 )
 
@@ -70,7 +70,7 @@ func wrapUseful(err error, code, help string) error {
 	if err == nil {
 		return nil
 	}
-	if _, ok := usefulerror.AsUsefulError(err); ok {
+	if hasUsefulError(err) {
 		return err
 	}
 	return usefulerror.NewUsefulError().
@@ -84,7 +84,7 @@ func profileLoadError(err error) error {
 	if err == nil {
 		return nil
 	}
-	if _, ok := usefulerror.AsUsefulError(err); ok {
+	if hasUsefulError(err) {
 		return err
 	}
 	switch {
@@ -99,6 +99,14 @@ func profileLoadError(err error) error {
 		"Failed to load the sandbox profile. Run with --verbose for the underlying cause.")
 }
 
+func hasUsefulError(err error) bool {
+	// AsUsefulError also runs global converters for plain errors like
+	// fs.ErrPermission. Contextual wrappers must only skip errors that already
+	// carry UsefulError details, otherwise generic converters hide command help.
+	var usefulErr usefulerror.UsefulError
+	return errors.As(err, &usefulErr)
+}
+
 func registryInitError(err error) error {
 	return wrapUseful(err, ioErrorCode(err, errcodes.Unknown),
 		"Failed to initialise the sandbox profile registry. Run with --verbose for details.")

cmd/sandbox/helpers_test.go

@@ -0,0 +1,44 @@
+package sandbox
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"testing"
+
+	"github.com/safedep/dry/usefulerror"
+	"github.com/safedep/pmg/errcodes"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestWrapUsefulPreservesContextForConvertibleErrors(t *testing.T) {
+	help := "Could not create the user profile directory. Check filesystem permissions for /var/root/pmg-repro/sandbox/profiles."
+	err := wrapUseful(
+		fmt.Errorf("failed to create user profile directory /var/root/pmg-repro/sandbox/profiles: %w", fs.ErrPermission),
+		errcodes.PermissionDenied,
+		help,
+	)
+
+	usefulErr, ok := usefulerror.AsUsefulError(err)
+	require.True(t, ok)
+	assert.Equal(t, errcodes.PermissionDenied, usefulErr.Code())
+	assert.Equal(t, help, usefulErr.Help())
+	assert.Contains(t, usefulErr.HumanError(), "failed to create user profile directory")
+}
+
+func TestWrapUsefulLeavesExistingUsefulErrorsUnchanged(t *testing.T) {
+	original := usefulerror.NewUsefulError().
+		WithCode(errcodes.InvalidArgument).
+		WithHumanError("already classified").
+		WithHelp("existing help").
+		Wrap(errors.New("root"))
+
+	err := wrapUseful(original, errcodes.PermissionDenied, "new help")
+
+	assert.Same(t, original, err)
+	usefulErr, ok := usefulerror.AsUsefulError(err)
+	require.True(t, ok)
+	assert.Equal(t, errcodes.InvalidArgument, usefulErr.Code())
+	assert.Equal(t, "existing help", usefulErr.Help())
+}

cmd/sandbox/profile_diff.go

@@ -7,9 +7,9 @@ import (
 	"strings"
 
 	"github.com/pmezard/go-difflib/difflib"
+	"github.com/safedep/pmg/errcodes"
 	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/safedep/pmg/sandbox/platform"
-	"github.com/safedep/pmg/errcodes"
 	"github.com/spf13/cobra"
 	"gopkg.in/yaml.v3"
 )

cmd/sandbox/profile_init_test.go

@@ -7,9 +7,9 @@ import (
 	"strings"
 	"testing"
 
-	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/errcodes"
+	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"

cmd/sandbox/profile_lint_test.go

@@ -10,9 +10,9 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/errcodes"
+	pmgsandbox "github.com/safedep/pmg/sandbox"
 )
 
 func writeUserProfileLint(t *testing.T, dir, name, body string) string {

cmd/sandbox/profile_list.go

@@ -5,9 +5,9 @@ import (
 	"io"
 	"strings"
 
+	"github.com/safedep/pmg/errcodes"
 	"github.com/safedep/pmg/internal/ui"
 	pmgsandbox "github.com/safedep/pmg/sandbox"
-	"github.com/safedep/pmg/errcodes"
 	"github.com/spf13/cobra"
 )
 

cmd/sandbox/profile_list_test.go

@@ -13,9 +13,9 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/errcodes"
+	pmgsandbox "github.com/safedep/pmg/sandbox"
 )
 
 func newTestRegistry(t *testing.T, userDir string) registryFactory {

cmd/sandbox/profile_show.go

@@ -6,9 +6,9 @@ import (
 	"os"
 
 	"github.com/safedep/dry/log"
+	"github.com/safedep/pmg/errcodes"
 	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/safedep/pmg/sandbox/platform"
-	"github.com/safedep/pmg/errcodes"
 	"github.com/spf13/cobra"
 	"gopkg.in/yaml.v3"
 )

cmd/sandbox/violations_list.go

@@ -6,10 +6,10 @@ import (
 	"io"
 	"time"
 
-	"github.com/safedep/pmg/internal/ui"
-	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/errcodes"
+	"github.com/safedep/pmg/internal/ui"
+	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/spf13/cobra"
 )
 

cmd/sandbox/violations_list_test.go

@@ -6,9 +6,9 @@ import (
 	"strings"
 	"testing"
 
-	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/errcodes"
+	pmgsandbox "github.com/safedep/pmg/sandbox"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )

config/config.go

@@ -12,8 +12,8 @@ import (
 
 	packagev1 "buf.build/gen/go/safedep/api/protocolbuffers/go/safedep/messages/package/v1"
 	"github.com/safedep/dry/log"
-	"github.com/safedep/dry/utils"
 	"github.com/safedep/dry/usefulerror"
+	"github.com/safedep/dry/utils"
 	"github.com/safedep/pmg/errcodes"
 	"github.com/spf13/viper"
 )
@@ -337,8 +337,8 @@ func DefaultConfig() RuntimeConfig {
 				},
 			},
 			Proxy: ProxyConfig{
-				Enabled:     true,
-				InstallOnly: false,
+				Enabled:      true,
+				InstallOnly:  false,
 				SkipCommands: map[string][]string{},
 			},
 		},

errcodes/codes.go

@@ -7,10 +7,19 @@ const (
 	Timeout                       = "Timeout"
 	Canceled                      = "Canceled"
 	UnexpectedEOF                 = "UnexpectedEOF"
-	Unknown                       = "Unknown"
 	Lifecycle                     = "Lifecycle"
 	Network                       = "Network"
-	SandboxViolation              = "SandboxViolation"
 	PackageManagerExecutionFailed = "PackageManagerExecutionFailed"
-	BubblewrapNotFound            = "bubblewrap_not_found"
+	BubblewrapNotFound            = "BubblewrapNotFound"
+
+	// Package manager error codes.
+	DependencyResolutionFailed = "DependencyResolutionFailed"
+	PackageParseFailed         = "PackageParseFailed"
+	PackageAuthorNotFound      = "PackageAuthorNotFound"
+	GitHubRateLimitExceeded    = "GitHubRateLimitExceeded"
+
+	// Unknown mirrors the default code that dry/usefulerror returns for errors
+	// created without an explicit code, so unset and explicitly-unknown errors
+	// classify identically (e.g. the bug-report hint in ui.ErrorExit).
+	Unknown = "unknown"
 )

go.mod

@@ -94,4 +94,4 @@ require (
 	modernc.org/memory v1.11.0 // indirect
 	modernc.org/sqlite v1.48.1 // indirect
 	sigs.k8s.io/yaml v1.4.0 // indirect
-)
+)

internal/runner/execute.go

@@ -10,12 +10,13 @@ import (
 	"sync"
 
 	"github.com/safedep/dry/log"
+	"github.com/safedep/dry/usefulerror"
+	"github.com/safedep/pmg/errcodes"
 	"github.com/safedep/pmg/internal/pty"
 	"github.com/safedep/pmg/internal/shim"
 	"github.com/safedep/pmg/packagemanager"
 	"github.com/safedep/pmg/sandbox"
 	"github.com/safedep/pmg/sandbox/executor"
-	"github.com/safedep/dry/usefulerror"
 )
 
 type ExecutionMode int
@@ -141,6 +142,7 @@ func runPTY(
 	if !result.ShouldRun() {
 		return usefulerror.NewUsefulError().
 			Wrap(fmt.Errorf("sandbox not supported for PTY sessions")).
+			WithCode(errcodes.InvalidArgument).
 			WithHumanError("Sandbox executed command cannot be used with PTY session. Please use non-interactive TTY mode instead.")
 	}
 

internal/ui/error_convert_test.go

@@ -76,7 +76,7 @@ func Test_ErrorConverters(t *testing.T) {
 			inputError: fmt.Errorf("more context: %w",
 				fmt.Errorf("outer context: %w",
 					errors.New("root cause error"))),
-			wantNil:    true,
+			wantNil: true,
 		},
 		{
 			name:       "Nil",
@@ -114,6 +114,65 @@ func Test_ErrorConverters(t *testing.T) {
 	}
 }
 
+func Test_convertToUsefulError(t *testing.T) {
+	tests := []struct {
+		name           string
+		inputError     error
+		wantCode       string
+		wantHumanError string
+		wantNil        bool
+	}{
+		{
+			name:       "Nil",
+			inputError: nil,
+			wantNil:    true,
+		},
+		{
+			name: "AlreadyUseful",
+			inputError: usefulerror.NewUsefulError().
+				WithCode("CUSTOM").
+				WithHumanError("Already useful"),
+			wantCode:       "CUSTOM",
+			wantHumanError: "Already useful",
+		},
+		{
+			name:           "Converted",
+			inputError:     &fs.PathError{Op: "open", Path: "/nonexistent/file.txt", Err: os.ErrNotExist},
+			wantCode:       errcodes.NotFound,
+			wantHumanError: "File or directory not found: /nonexistent/file.txt",
+		},
+		{
+			name:           "UnknownFallsBackToRootCause",
+			inputError:     errors.New("some unknown error"),
+			wantCode:       errcodes.Unknown,
+			wantHumanError: "some unknown error",
+		},
+		{
+			name: "UnknownWrappedExtractsRootCause",
+			inputError: fmt.Errorf("more context: %w",
+				fmt.Errorf("outer context: %w",
+					errors.New("root cause error"))),
+			wantCode:       errcodes.Unknown,
+			wantHumanError: "root cause error",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := convertToUsefulError(tt.inputError)
+
+			if tt.wantNil {
+				assert.Nil(t, result)
+				return
+			}
+
+			assert.NotNil(t, result)
+			assert.Equal(t, tt.wantCode, result.Code())
+			assert.Equal(t, tt.wantHumanError, result.HumanError())
+		})
+	}
+}
+
 func TestExtractPathFromError(t *testing.T) {
 	tests := []struct {
 		name     string

packagemanager/errors.go

@@ -5,13 +5,6 @@ import (
 	"github.com/safedep/pmg/errcodes"
 )
 
-const (
-	errDependencyResolutionFailed = "DependencyResolutionFailed"
-	errPackageParseFailed         = "PackageParseFailed"
-	errPackageAuthorNotFound      = "PackageAuthorNotFound"
-	errGitHubRateLimitExceeded    = "GitHubRateLimitExceeded"
-)
-
 var (
 	ErrPackageNotFound = usefulerror.NewUsefulError().
 				WithCode(errcodes.NotFound).
@@ -31,25 +24,25 @@ var (
 					WithMsg("failed to resolve package version")
 
 	ErrFailedToResolveDependencies = usefulerror.NewUsefulError().
-					WithCode(errDependencyResolutionFailed).
+					WithCode(errcodes.DependencyResolutionFailed).
 					WithHumanError("Failed to resolve dependencies.").
 					WithHelp("Check your network connection and try again.").
 					WithMsg("failed to resolve dependencies")
 
 	ErrFailedToParsePackage = usefulerror.NewUsefulError().
-				WithCode(errPackageParseFailed).
+				WithCode(errcodes.PackageParseFailed).
 				WithHumanError("The package data could not be processed.").
 				WithHelp("The package may be corrupted or in an unsupported format.").
 				WithMsg("failed to parse package")
 
 	ErrAuthorNotFound = usefulerror.NewUsefulError().
-				WithCode(errPackageAuthorNotFound).
+				WithCode(errcodes.PackageAuthorNotFound).
 				WithHumanError("The package author information could not be found.").
 				WithHelp("This may be due to incomplete package metadata or network issues.").
 				WithMsg("author not found")
 
 	ErrGitHubRateLimitExceeded = usefulerror.NewUsefulError().
-					WithCode(errGitHubRateLimitExceeded).
+					WithCode(errcodes.GitHubRateLimitExceeded).
 					WithHumanError("GitHub API rate limit has been exceeded.").
 					WithHelp("Wait for the rate limit to reset or configure authentication to increase your rate limit.").
 					WithMsg("github api rate limit exceeded")

sandbox/executor/apply.go

@@ -7,13 +7,13 @@ import (
 	"path/filepath"
 
 	"github.com/safedep/dry/log"
+	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/dry/utils"
 	"github.com/safedep/pmg/config"
+	"github.com/safedep/pmg/errcodes"
 	"github.com/safedep/pmg/internal/audit"
 	"github.com/safedep/pmg/sandbox"
 	"github.com/safedep/pmg/sandbox/platform"
-	"github.com/safedep/dry/usefulerror"
-	"github.com/safedep/pmg/errcodes"
 )
 
 type applySandboxConfig struct {

sandbox/executor/diagnostics.go

@@ -4,10 +4,10 @@ import (
 	"fmt"
 
 	"github.com/safedep/dry/log"
-	"github.com/safedep/pmg/config"
-	"github.com/safedep/pmg/sandbox"
 	"github.com/safedep/dry/usefulerror"
+	"github.com/safedep/pmg/config"
 	"github.com/safedep/pmg/errcodes"
+	"github.com/safedep/pmg/sandbox"
 )
 
 // WrapCommandExecutionError converts a package manager execution error into a

sandbox/executor/diagnostics_test.go

@@ -6,9 +6,9 @@ import (
 	"os/exec"
 	"testing"
 
-	"github.com/safedep/pmg/sandbox"
 	"github.com/safedep/dry/usefulerror"
 	"github.com/safedep/pmg/errcodes"
+	"github.com/safedep/pmg/sandbox"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )