fix: wrap all bare error returns with context (#107)

* refactor: replace interface{} with typed CaptureResults in snapshot capture

* fix: wrap all bare error returns with context

Wrap ~80 bare `return err` and `return nil, err` statements across 24
production files with `fmt.Errorf("context: %w", err)` to satisfy the
project convention of never returning unwrapped errors.

Four intentional exceptions remain:
- dotfiles.go:301 — filepath.WalkDir callback convention
- install.go:150 — installer.Run already wraps thoroughly
- installer.go:226 — Apply already wraps thoroughly
- auth/login.go:154 — pollOnce returns user-facing messages

Also reverted wrapping in listBackupsSorted since callers check
os.IsNotExist (which does not traverse %w chains).

Author: fullstackjam

internal/auth/login.go

@@ -55,7 +55,7 @@ type cliPollResponse struct {
 func LoginInteractive(ctx context.Context, apiBase string) (*StoredAuth, error) {
 	codeID, code, err := startAuthSession(apiBase)
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("start auth session: %w", err)
 	}
 
 	fmt.Fprintf(os.Stderr, "\n")
@@ -72,7 +72,7 @@ func LoginInteractive(ctx context.Context, apiBase string) (*StoredAuth, error)
 
 	result, err := pollForApproval(ctx, apiBase, codeID)
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("poll for approval: %w", err)
 	}
 
 	expiresAt, err := time.Parse(time.RFC3339, result.ExpiresAt)

internal/brew/brew.go

@@ -87,7 +87,7 @@ func ListOutdated() ([]OutdatedPackage, error) {
 	}
 
 	if err := json.Unmarshal(output, &result); err != nil {
-		return nil, err
+		return nil, fmt.Errorf("parse brew outdated: %w", err)
 	}
 
 	var outdated []OutdatedPackage
@@ -246,10 +246,10 @@ func CheckDiskSpace() (float64, error) {
 	var stat syscall.Statfs_t
 	home, err := system.HomeDir()
 	if err != nil {
-		return 0, err
+		return 0, fmt.Errorf("check disk space: %w", err)
 	}
 	if err := syscall.Statfs(home, &stat); err != nil {
-		return 0, err
+		return 0, fmt.Errorf("statfs: %w", err)
 	}
 	// stat.Bsize is uint32 on darwin and int64 on linux; the kernel always
 	// reports a non-negative block size so the conversion is safe.

internal/cli/install.go

@@ -104,7 +104,7 @@ func runInstallCmd(cmd *cobra.Command, args []string) error {
 	if installCfg.RemoteConfig == nil {
 		src, err := resolveInstallSource(cmd, args)
 		if err != nil {
-			return err
+			return fmt.Errorf("resolve install source: %w", err)
 		}
 
 		if src.kind == sourceSyncSource {
@@ -113,7 +113,7 @@ func runInstallCmd(cmd *cobra.Command, args []string) error {
 		}
 
 		if err := applyInstallSource(src); err != nil {
-			return err
+			return fmt.Errorf("apply install source: %w", err)
 		}
 	}
 
@@ -128,7 +128,7 @@ func runInstallCmd(cmd *cobra.Command, args []string) error {
 		} else if !installCfg.Silent && (!installCfg.DryRun || system.HasTTY()) {
 			rc, proceed, err := promptCustomizeAndApply(installCfg.RemoteConfig)
 			if err != nil {
-				return err
+				return fmt.Errorf("customize config: %w", err)
 			}
 			if !proceed {
 				ui.Info("Cancelled.")

internal/cli/snapshot.go

@@ -79,7 +79,7 @@ func runSnapshot(cmd *cobra.Command) error {
 	if localFlag || publishFlag {
 		snap, err := captureEnvironment()
 		if err != nil {
-			return err
+			return fmt.Errorf("capture environment: %w", err)
 		}
 		if dryRunFlag {
 			showSnapshotPreview(snap)
@@ -97,7 +97,7 @@ func runSnapshot(cmd *cobra.Command) error {
 		}
 		if publishFlag {
 			if err := publishSnapshot(cmd.Context(), snap, slugFlag); err != nil {
-				return err
+				return fmt.Errorf("publish snapshot: %w", err)
 			}
 		}
 		return nil
@@ -110,7 +110,7 @@ func runSnapshot(cmd *cobra.Command) error {
 
 	snap, err := captureEnvironment()
 	if err != nil {
-		return err
+		return fmt.Errorf("capture environment: %w", err)
 	}
 
 	if dryRunFlag {
@@ -123,7 +123,7 @@ func runSnapshot(cmd *cobra.Command) error {
 
 	edited, confirmed, err := reviewSnapshot(snap)
 	if err != nil {
-		return err
+		return fmt.Errorf("review snapshot: %w", err)
 	}
 	if !confirmed {
 		return nil
@@ -153,7 +153,7 @@ func interactiveSaveOrPublish(ctx context.Context, snap *snapshot.Snapshot) erro
 	}
 	choice, err := ui.SelectOption("What to do with this snapshot?", options)
 	if err != nil {
-		return err
+		return fmt.Errorf("select snapshot action: %w", err)
 	}
 
 	switch choice {
@@ -260,7 +260,7 @@ func captureJSONSnapshot() error {
 func captureEnvironment() (*snapshot.Snapshot, error) {
 	snap, err := captureWithUI()
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("capture with ui: %w", err)
 	}
 	catalogMatch := snapshot.MatchPackages(snap)
 	snap.CatalogMatch = *catalogMatch
@@ -298,7 +298,7 @@ func captureWithUI() (*snapshot.Snapshot, error) {
 func reviewSnapshot(snap *snapshot.Snapshot) (*snapshot.Snapshot, bool, error) {
 	edited, confirmed, err := ui.RunSnapshotEditor(snap)
 	if err != nil {
-		return nil, false, err
+		return nil, false, fmt.Errorf("snapshot editor: %w", err)
 	}
 	if !confirmed {
 		fmt.Fprintln(os.Stderr)

internal/cli/snapshot_import.go

@@ -17,7 +17,7 @@ import (
 func runSnapshotImport(importPath string, dryRun bool) error {
 	snap, err := loadSnapshot(importPath)
 	if err != nil {
-		return err
+		return fmt.Errorf("load snapshot: %w", err)
 	}
 
 	if snap.Health.Partial {
@@ -29,7 +29,7 @@ func runSnapshotImport(importPath string, dryRun bool) error {
 		fmt.Fprintln(os.Stderr)
 		proceed, err := ui.Confirm("Continue with partial snapshot?", false)
 		if err != nil {
-			return err
+			return fmt.Errorf("confirm partial snapshot: %w", err)
 		}
 		if !proceed {
 			fmt.Fprintln(os.Stderr)
@@ -43,7 +43,7 @@ func runSnapshotImport(importPath string, dryRun bool) error {
 
 	edited, confirmed, err := ui.RunSnapshotEditor(snap)
 	if err != nil {
-		return err
+		return fmt.Errorf("snapshot editor: %w", err)
 	}
 	if !confirmed {
 		fmt.Fprintln(os.Stderr)
@@ -54,7 +54,7 @@ func runSnapshotImport(importPath string, dryRun bool) error {
 
 	ok, err := confirmInstallation(edited, dryRun)
 	if err != nil {
-		return err
+		return fmt.Errorf("confirm installation: %w", err)
 	}
 	if !ok {
 		fmt.Fprintln(os.Stderr)
@@ -96,17 +96,17 @@ func loadSnapshot(importPath string) (*snapshot.Snapshot, error) {
 		fmt.Fprintf(os.Stderr, "  Downloading snapshot from %s...\n", importPath)
 		data, err := downloadSnapshotBytes(importPath, &http.Client{Timeout: apiRequestTimeout})
 		if err != nil {
-			return nil, err
+			return nil, fmt.Errorf("download snapshot: %w", err)
 		}
 		s, err := snapshot.ParseBytes(data)
 		if err != nil {
-			return nil, err
+			return nil, fmt.Errorf("parse snapshot: %w", err)
 		}
 		snap = s
 	default:
 		s, err := snapshot.LoadFile(importPath)
 		if err != nil {
-			return nil, err
+			return nil, fmt.Errorf("load snapshot file: %w", err)
 		}
 		snap = s
 	}

internal/cli/snapshot_publish.go

@@ -65,13 +65,13 @@ func publishSnapshot(ctx context.Context, snap *snapshot.Snapshot, explicitSlug
 		fmt.Fprintln(os.Stderr, "  Publishing as a new config on openboot.dev")
 		configName, configDesc, visibility, err = promptPushDetails("")
 		if err != nil {
-			return err
+			return fmt.Errorf("prompt publish details: %w", err)
 		}
 	}
 
 	resultSlug, err := postSnapshotToAPI(snap, configName, configDesc, visibility, stored.Token, apiBase, targetSlug)
 	if err != nil {
-		return err
+		return fmt.Errorf("publish snapshot: %w", err)
 	}
 
 	recordPublishResult(stored.Username, resultSlug, targetSlug, visibility, apiBase)

internal/cli/update.go

@@ -133,7 +133,7 @@ func runRollback() error {
 
 func runPinnedUpgrade(v string) error {
 	if err := updater.ValidateSemver(v); err != nil {
-		return err
+		return fmt.Errorf("validate version: %w", err)
 	}
 	if updateIsHomebrewInstall() {
 		ui.Warn("OpenBoot is managed by Homebrew — --version is not supported.")

internal/config/packages_remote.go

@@ -67,7 +67,7 @@ func loadRemotePackages(dryRun bool) ([]remotePackage, error) {
 	// Fetch from server.
 	pkgs, err := fetchRemotePackages()
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("load remote packages: %w", err)
 	}
 
 	// Write cache (best-effort) — skip during dry-run to avoid disk side effects.
@@ -121,12 +121,12 @@ var cacheDir = func() string {
 func readPackagesCache() ([]remotePackage, error) {
 	data, err := os.ReadFile(filepath.Join(cacheDir(), packagesCacheFile))
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("read packages cache: %w", err)
 	}
 
 	var entry packagesCacheEntry
 	if err := json.Unmarshal(data, &entry); err != nil {
-		return nil, err
+		return nil, fmt.Errorf("parse packages cache: %w", err)
 	}
 
 	if time.Since(entry.FetchedAt) > packagesCacheTTL {
@@ -139,7 +139,7 @@ func readPackagesCache() ([]remotePackage, error) {
 func writePackagesCache(pkgs []remotePackage) error {
 	dir := cacheDir()
 	if err := os.MkdirAll(dir, 0700); err != nil {
-		return err
+		return fmt.Errorf("mkdir packages cache: %w", err)
 	}
 
 	entry := packagesCacheEntry{
@@ -148,7 +148,7 @@ func writePackagesCache(pkgs []remotePackage) error {
 	}
 	data, err := json.Marshal(entry)
 	if err != nil {
-		return err
+		return fmt.Errorf("marshal packages cache: %w", err)
 	}
 
 	return os.WriteFile(filepath.Join(dir, packagesCacheFile), data, 0600)

internal/config/remote.go

@@ -264,7 +264,7 @@ func fetchConfigByAlias(apiBase, alias, token string) (*RemoteConfig, error) {
 func decodeRemoteConfig(r io.Reader) (*RemoteConfig, error) {
 	data, err := io.ReadAll(io.LimitReader(r, 1<<20))
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("read remote config: %w", err)
 	}
 	return UnmarshalRemoteConfigFlexible(data)
 }
@@ -284,7 +284,7 @@ func UnmarshalRemoteConfigFlexible(data []byte) (*RemoteConfig, error) {
 	// Extract packages as typed objects and convert to flat arrays.
 	var raw map[string]json.RawMessage
 	if err := json.Unmarshal(data, &raw); err != nil {
-		return nil, err
+		return nil, fmt.Errorf("parse remote config: %w", err)
 	}
 
 	pkgData, ok := raw["packages"]
@@ -341,7 +341,7 @@ func UnmarshalRemoteConfigFlexible(data []byte) (*RemoteConfig, error) {
 
 	var result RemoteConfig
 	if err := json.Unmarshal(normalised, &result); err != nil {
-		return nil, err
+		return nil, fmt.Errorf("unmarshal normalised config: %w", err)
 	}
 	normalizeRemoteConfig(&result)
 	backfillMacOSPrefsFromSnapshot(&result, data)

internal/config/validate.go

@@ -65,13 +65,13 @@ func ValidateDotfilesURL(rawURL string) error {
 
 func (rc *RemoteConfig) Validate() error {
 	if err := validatePackageLists(rc); err != nil {
-		return err
+		return fmt.Errorf("validate packages: %w", err)
 	}
 	if err := ValidateDotfilesURL(rc.DotfilesRepo); err != nil {
 		return fmt.Errorf("invalid dotfiles_repo: %w", err)
 	}
 	if err := validateMacOSPrefs(rc); err != nil {
-		return err
+		return fmt.Errorf("validate macos prefs: %w", err)
 	}
 	return validatePostInstall(rc)
 }