feat: add custom error types, structured logging, and --verbose flag

Introduce internal/errors package with ConfigError, ConnectionError,
and DockerError types carrying actionable suggestions. Add slog-based
structured logging with --verbose/-v flag for debug output. Update
config and ssh packages to use custom error types with user-friendly
hints.

Closes ISS-34

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: chuongld20

cmd/devbox/main.go

@@ -3,7 +3,9 @@ package main
 import (
 	"bufio"
 	"context"
+	"errors"
 	"fmt"
+	"log/slog"
 	"os"
 	"path/filepath"
 	"strings"
@@ -12,13 +14,17 @@ import (
 
 	"github.com/junixlabs/devbox/internal/config"
 	"github.com/junixlabs/devbox/internal/doctor"
+	devboxerr "github.com/junixlabs/devbox/internal/errors"
 	devboxssh "github.com/junixlabs/devbox/internal/ssh"
 	"github.com/junixlabs/devbox/internal/tailscale"
 	"github.com/junixlabs/devbox/internal/workspace"
 	"github.com/spf13/cobra"
 )
 
-var version = "0.1.0-dev"
+var (
+	version = "0.1.0-dev"
+	verbose bool
+)
 
 func main() {
 	wm := workspace.NewManager()
@@ -29,7 +35,15 @@ func main() {
 		Long:         "devbox turns any Linux machine into a ready-to-use dev environment in one command.\nNo cloud, no DevOps required.",
 		Version:      version,
 		SilenceUsage: true,
+		PersistentPreRun: func(cmd *cobra.Command, args []string) {
+			level := slog.LevelInfo
+			if verbose {
+				level = slog.LevelDebug
+			}
+			slog.SetDefault(slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: level})))
+		},
 	}
+	rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "Enable debug logging")
 
 	rootCmd.AddCommand(initCmd())
 	rootCmd.AddCommand(upCmd(wm))
@@ -40,10 +54,19 @@ func main() {
 	rootCmd.AddCommand(doctorCmd())
 
 	if err := rootCmd.Execute(); err != nil {
+		printError(err)
 		os.Exit(1)
 	}
 }
 
+// printError formats errors with suggestions when available.
+func printError(err error) {
+	var s devboxerr.Suggestible
+	if errors.As(err, &s) && s.GetSuggestion() != "" {
+		fmt.Fprintf(os.Stderr, "Hint: %s\n", s.GetSuggestion())
+	}
+}
+
 // remoteRunner returns a tailscale.CommandRunner that executes commands on a
 // remote server via SSH.
 func remoteRunner(sshExec devboxssh.Executor, server string) tailscale.CommandRunner {

internal/config/config.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 
+	devboxerr "github.com/junixlabs/devbox/internal/errors"
 	"gopkg.in/yaml.v3"
 )
 
@@ -25,20 +26,36 @@ const DefaultConfigFile = "devbox.yaml"
 func Load(path string) (*DevboxConfig, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {
-		return nil, fmt.Errorf("failed to read config file %s: %w", path, err)
+		return nil, devboxerr.NewConfigError(
+			fmt.Sprintf("failed to read config file %s", path),
+			"Run 'devbox init' to create a devbox.yaml",
+			err,
+		)
 	}
 
 	var cfg DevboxConfig
 	if err := yaml.Unmarshal(data, &cfg); err != nil {
-		return nil, fmt.Errorf("failed to parse config file %s: %w", path, err)
+		return nil, devboxerr.NewConfigError(
+			fmt.Sprintf("failed to parse config file %s", path),
+			"Check YAML syntax in devbox.yaml",
+			err,
+		)
 	}
 
 	if cfg.Name == "" {
-		return nil, fmt.Errorf("config file %s: 'name' is required", path)
+		return nil, devboxerr.NewConfigError(
+			fmt.Sprintf("config file %s: 'name' is required", path),
+			"Add 'name: your-project' to devbox.yaml",
+			nil,
+		)
 	}
 
 	if cfg.Server == "" {
-		return nil, fmt.Errorf("config file %s: 'server' is required", path)
+		return nil, devboxerr.NewConfigError(
+			fmt.Sprintf("config file %s: 'server' is required", path),
+			"Add 'server: your-server' to devbox.yaml",
+			nil,
+		)
 	}
 
 	return &cfg, nil

internal/errors/errors.go

@@ -0,0 +1,76 @@
+package errors
+
+import "fmt"
+
+// ConfigError represents a configuration-related error with an actionable suggestion.
+type ConfigError struct {
+	Message    string
+	Suggestion string
+	Err        error
+}
+
+func (e *ConfigError) Error() string {
+	if e.Err != nil {
+		return fmt.Sprintf("%s: %v", e.Message, e.Err)
+	}
+	return e.Message
+}
+
+func (e *ConfigError) Unwrap() error { return e.Err }
+
+// NewConfigError creates a ConfigError with a user-facing suggestion.
+func NewConfigError(message, suggestion string, err error) *ConfigError {
+	return &ConfigError{Message: message, Suggestion: suggestion, Err: err}
+}
+
+// ConnectionError represents an SSH or network connectivity error.
+type ConnectionError struct {
+	Message    string
+	Suggestion string
+	Err        error
+}
+
+func (e *ConnectionError) Error() string {
+	if e.Err != nil {
+		return fmt.Sprintf("%s: %v", e.Message, e.Err)
+	}
+	return e.Message
+}
+
+func (e *ConnectionError) Unwrap() error { return e.Err }
+
+// NewConnectionError creates a ConnectionError with a user-facing suggestion.
+func NewConnectionError(message, suggestion string, err error) *ConnectionError {
+	return &ConnectionError{Message: message, Suggestion: suggestion, Err: err}
+}
+
+// DockerError represents a Docker-related error.
+type DockerError struct {
+	Message    string
+	Suggestion string
+	Err        error
+}
+
+func (e *DockerError) Error() string {
+	if e.Err != nil {
+		return fmt.Sprintf("%s: %v", e.Message, e.Err)
+	}
+	return e.Message
+}
+
+func (e *DockerError) Unwrap() error { return e.Err }
+
+// NewDockerError creates a DockerError with a user-facing suggestion.
+func NewDockerError(message, suggestion string, err error) *DockerError {
+	return &DockerError{Message: message, Suggestion: suggestion, Err: err}
+}
+
+// Suggestible is implemented by errors that carry an actionable suggestion.
+type Suggestible interface {
+	error
+	GetSuggestion() string
+}
+
+func (e *ConfigError) GetSuggestion() string     { return e.Suggestion }
+func (e *ConnectionError) GetSuggestion() string  { return e.Suggestion }
+func (e *DockerError) GetSuggestion() string      { return e.Suggestion }

internal/errors/errors_test.go

@@ -0,0 +1,108 @@
+package errors_test
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	devboxerr "github.com/junixlabs/devbox/internal/errors"
+)
+
+func TestConfigError(t *testing.T) {
+	inner := fmt.Errorf("file not found")
+	err := devboxerr.NewConfigError("invalid config", "Run devbox init", inner)
+
+	if err.Error() != "invalid config: file not found" {
+		t.Errorf("unexpected message: %s", err.Error())
+	}
+
+	if !errors.Is(err, inner) {
+		t.Error("errors.Is should match inner error")
+	}
+
+	var ce *devboxerr.ConfigError
+	if !errors.As(err, &ce) {
+		t.Error("errors.As should match ConfigError")
+	}
+
+	if ce.GetSuggestion() != "Run devbox init" {
+		t.Errorf("unexpected suggestion: %s", ce.GetSuggestion())
+	}
+}
+
+func TestConfigErrorNoInner(t *testing.T) {
+	err := devboxerr.NewConfigError("missing name", "Add 'name' to devbox.yaml", nil)
+
+	if err.Error() != "missing name" {
+		t.Errorf("unexpected message: %s", err.Error())
+	}
+
+	if err.Unwrap() != nil {
+		t.Error("Unwrap should return nil")
+	}
+}
+
+func TestConnectionError(t *testing.T) {
+	inner := fmt.Errorf("connection refused")
+	err := devboxerr.NewConnectionError("ssh failed", "Check SSH connectivity", inner)
+
+	if err.Error() != "ssh failed: connection refused" {
+		t.Errorf("unexpected message: %s", err.Error())
+	}
+
+	var ce *devboxerr.ConnectionError
+	if !errors.As(err, &ce) {
+		t.Error("errors.As should match ConnectionError")
+	}
+
+	if ce.GetSuggestion() != "Check SSH connectivity" {
+		t.Errorf("unexpected suggestion: %s", ce.GetSuggestion())
+	}
+}
+
+func TestDockerError(t *testing.T) {
+	err := devboxerr.NewDockerError("container failed", "Run: docker ps", nil)
+
+	if err.Error() != "container failed" {
+		t.Errorf("unexpected message: %s", err.Error())
+	}
+
+	var de *devboxerr.DockerError
+	if !errors.As(err, &de) {
+		t.Error("errors.As should match DockerError")
+	}
+
+	if de.GetSuggestion() != "Run: docker ps" {
+		t.Errorf("unexpected suggestion: %s", de.GetSuggestion())
+	}
+}
+
+func TestSuggestibleInterface(t *testing.T) {
+	cases := []struct {
+		name string
+		err  devboxerr.Suggestible
+		want string
+	}{
+		{"ConfigError", devboxerr.NewConfigError("x", "fix config", nil), "fix config"},
+		{"ConnectionError", devboxerr.NewConnectionError("x", "fix conn", nil), "fix conn"},
+		{"DockerError", devboxerr.NewDockerError("x", "fix docker", nil), "fix docker"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if tc.err.GetSuggestion() != tc.want {
+				t.Errorf("got %q, want %q", tc.err.GetSuggestion(), tc.want)
+			}
+		})
+	}
+}
+
+func TestUnwrapChain(t *testing.T) {
+	root := fmt.Errorf("root cause")
+	wrapped := fmt.Errorf("middle: %w", root)
+	err := devboxerr.NewConnectionError("top level", "suggestion", wrapped)
+
+	if !errors.Is(err, root) {
+		t.Error("errors.Is should traverse the full chain to root")
+	}
+}