feat: add PackageUpgrader interface for targeted package upgrades

Add optional PackageUpgrader interface with UpgradePackages method
that upgrades specific installed packages (unlike Upgrade which
upgrades everything).

Each backend uses native upgrade commands:
- apt: apt-get install --only-upgrade
- dnf: dnf upgrade <pkg>
- pacman: pacman -S <pkg>
- apk: apk upgrade <pkg>
- pkg (FreeBSD): pkg upgrade <pkg>
- flatpak: flatpak update <pkg>
- snap: snap refresh <pkg>

Non-installed packages are filtered out and returned as Unchanged.

Closes #31

apk/apk.go

@@ -19,6 +19,7 @@ func New() *Apk {
 
 // compile-time check
 var _ snack.Manager = (*Apk)(nil)
+var _ snack.PackageUpgrader = (*Apk)(nil)
 
 // Name returns "apk".
 func (a *Apk) Name() string { return "apk" }
@@ -85,3 +86,10 @@ func (a *Apk) IsInstalled(ctx context.Context, pkg string) (bool, error) {
 func (a *Apk) Version(ctx context.Context, pkg string) (string, error) {
 	return version(ctx, pkg)
 }
+
+// UpgradePackages upgrades specific installed packages.
+func (a *Apk) UpgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	a.Lock()
+	defer a.Unlock()
+	return upgradePackages(ctx, pkgs, opts...)
+}

apk/apk_linux.go

@@ -216,3 +216,36 @@ func version(ctx context.Context, pkg string) (string, error) {
 	}
 	return ver, nil
 }
+
+func upgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	o := snack.ApplyOptions(opts...)
+	var toUpgrade []snack.Target
+	var unchanged []string
+	for _, t := range pkgs {
+		if o.DryRun {
+			toUpgrade = append(toUpgrade, t)
+			continue
+		}
+		ok, err := isInstalled(ctx, t.Name)
+		if err != nil {
+			return snack.InstallResult{}, err
+		}
+		if !ok {
+			unchanged = append(unchanged, t.Name)
+		} else {
+			toUpgrade = append(toUpgrade, t)
+		}
+	}
+	if len(toUpgrade) > 0 {
+		args := append([]string{"upgrade"}, formatTargets(toUpgrade)...)
+		if _, err := run(ctx, args, opts...); err != nil {
+			return snack.InstallResult{}, err
+		}
+	}
+	var upgraded []snack.Package
+	for _, t := range toUpgrade {
+		v, _ := version(ctx, t.Name)
+		upgraded = append(upgraded, snack.Package{Name: t.Name, Version: v, Installed: true})
+	}
+	return snack.InstallResult{Installed: upgraded, Unchanged: unchanged}, nil
+}

apk/apk_other.go

@@ -49,3 +49,7 @@ func isInstalled(_ context.Context, _ string) (bool, error) {
 func version(_ context.Context, _ string) (string, error) {
 	return "", snack.ErrUnsupportedPlatform
 }
+
+func upgradePackages(_ context.Context, _ []snack.Target, _ ...snack.Option) (snack.InstallResult, error) {
+	return snack.InstallResult{}, snack.ErrUnsupportedPlatform
+}

apt/apt.go

@@ -206,13 +206,21 @@ func (a *Apt) SupportsDryRun() bool { return true }
 
 // Compile-time interface checks.
 var (
-	_ snack.Manager        = (*Apt)(nil)
+	_ snack.Manager         = (*Apt)(nil)
-	_ snack.VersionQuerier = (*Apt)(nil)
+	_ snack.VersionQuerier  = (*Apt)(nil)
-	_ snack.Holder         = (*Apt)(nil)
+	_ snack.Holder          = (*Apt)(nil)
-	_ snack.Cleaner        = (*Apt)(nil)
+	_ snack.Cleaner         = (*Apt)(nil)
-	_ snack.FileOwner      = (*Apt)(nil)
+	_ snack.FileOwner       = (*Apt)(nil)
-	_ snack.RepoManager    = (*Apt)(nil)
+	_ snack.RepoManager     = (*Apt)(nil)
-	_ snack.KeyManager     = (*Apt)(nil)
+	_ snack.KeyManager      = (*Apt)(nil)
-	_ snack.NameNormalizer = (*Apt)(nil)
+	_ snack.NameNormalizer  = (*Apt)(nil)
-	_ snack.DryRunner      = (*Apt)(nil)
+	_ snack.DryRunner       = (*Apt)(nil)
+	_ snack.PackageUpgrader = (*Apt)(nil)
 )
+
+// UpgradePackages upgrades specific installed packages.
+func (a *Apt) UpgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	a.Lock()
+	defer a.Unlock()
+	return upgradePackages(ctx, pkgs, opts...)
+}

apt/apt_linux.go

@@ -211,3 +211,50 @@ func version(ctx context.Context, pkg string) (string, error) {
 	}
 	return v, nil
 }
+
+func upgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	o := snack.ApplyOptions(opts...)
+	var toUpgrade []snack.Target
+	var unchanged []string
+	for _, t := range pkgs {
+		if o.DryRun {
+			toUpgrade = append(toUpgrade, t)
+			continue
+		}
+		ok, err := isInstalled(ctx, t.Name)
+		if err != nil {
+			return snack.InstallResult{}, err
+		}
+		if !ok {
+			unchanged = append(unchanged, t.Name)
+		} else {
+			toUpgrade = append(toUpgrade, t)
+		}
+	}
+	if len(toUpgrade) > 0 {
+		// Use --only-upgrade to ensure we don't install new packages.
+		args := buildArgs("install", toUpgrade, opts...)
+		idx := -1
+		for i, a := range args {
+			if a == "install" {
+				idx = i
+				break
+			}
+		}
+		if idx >= 0 {
+			args = append(args[:idx+1], append([]string{"--only-upgrade"}, args[idx+1:]...)...)
+		}
+		cmd := exec.CommandContext(ctx, args[0], args[1:]...)
+		var stderr bytes.Buffer
+		cmd.Stderr = &stderr
+		if err := cmd.Run(); err != nil {
+			return snack.InstallResult{}, fmt.Errorf("apt-get install --only-upgrade: %w: %s", err, stderr.String())
+		}
+	}
+	var upgraded []snack.Package
+	for _, t := range toUpgrade {
+		v, _ := version(ctx, t.Name)
+		upgraded = append(upgraded, snack.Package{Name: t.Name, Version: v, Installed: true})
+	}
+	return snack.InstallResult{Installed: upgraded, Unchanged: unchanged}, nil
+}

apt/apt_other.go

@@ -49,3 +49,7 @@ func isInstalled(_ context.Context, _ string) (bool, error) {
 func version(_ context.Context, _ string) (string, error) {
 	return "", snack.ErrUnsupportedPlatform
 }
+
+func upgradePackages(_ context.Context, _ []snack.Target, _ ...snack.Option) (snack.InstallResult, error) {
+	return snack.InstallResult{}, snack.ErrUnsupportedPlatform
+}

dnf/dnf.go

@@ -93,3 +93,11 @@ func (d *DNF) Version(ctx context.Context, pkg string) (string, error) {
 
 // Verify interface compliance at compile time.
 var _ snack.Manager = (*DNF)(nil)
+var _ snack.PackageUpgrader = (*DNF)(nil)
+
+// UpgradePackages upgrades specific installed packages.
+func (d *DNF) UpgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	d.Lock()
+	defer d.Unlock()
+	return upgradePackages(ctx, d.v5, pkgs, opts...)
+}

dnf/dnf_linux.go

@@ -269,3 +269,37 @@ func version(ctx context.Context, pkg string, v5 bool) (string, error) {
 	}
 	return pkgs[0].Version, nil
 }
+
+func upgradePackages(ctx context.Context, v5 bool, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	o := snack.ApplyOptions(opts...)
+	var toUpgrade []snack.Target
+	var unchanged []string
+	for _, t := range pkgs {
+		if o.DryRun {
+			toUpgrade = append(toUpgrade, t)
+			continue
+		}
+		ok, err := isInstalled(ctx, t.Name, v5)
+		if err != nil {
+			return snack.InstallResult{}, err
+		}
+		if !ok {
+			unchanged = append(unchanged, t.Name)
+		} else {
+			toUpgrade = append(toUpgrade, t)
+		}
+	}
+	if len(toUpgrade) > 0 {
+		base := []string{"upgrade"}
+		args := append(base, formatTargets(toUpgrade)...)
+		if _, err := run(ctx, args, o); err != nil {
+			return snack.InstallResult{}, err
+		}
+	}
+	var upgraded []snack.Package
+	for _, t := range toUpgrade {
+		v, _ := version(ctx, t.Name, v5)
+		upgraded = append(upgraded, snack.Package{Name: t.Name, Version: v, Installed: true})
+	}
+	return snack.InstallResult{Installed: upgraded, Unchanged: unchanged}, nil
+}

dnf/dnf_other.go

@@ -47,3 +47,7 @@ func isInstalled(_ context.Context, _ string, _ bool) (bool, error) {
 func version(_ context.Context, _ string, _ bool) (string, error) {
 	return "", snack.ErrUnsupportedPlatform
 }
+
+func upgradePackages(_ context.Context, _ bool, _ []snack.Target, _ ...snack.Option) (snack.InstallResult, error) {
+	return snack.InstallResult{}, snack.ErrUnsupportedPlatform
+}

flatpak/flatpak.go

@@ -83,3 +83,11 @@ func (f *Flatpak) Version(ctx context.Context, pkg string) (string, error) {
 
 // Verify interface compliance at compile time.
 var _ snack.Manager = (*Flatpak)(nil)
+var _ snack.PackageUpgrader = (*Flatpak)(nil)
+
+// UpgradePackages upgrades specific installed packages.
+func (f *Flatpak) UpgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	f.Lock()
+	defer f.Unlock()
+	return upgradePackages(ctx, pkgs, opts...)
+}

flatpak/flatpak_linux.go

@@ -197,3 +197,41 @@ func removeRepo(ctx context.Context, id string) error {
 	_, err := run(ctx, []string{"remote-delete", id})
 	return err
 }
+
+func upgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	o := snack.ApplyOptions(opts...)
+	var toUpgrade []snack.Target
+	var unchanged []string
+	for _, t := range pkgs {
+		if o.DryRun {
+			toUpgrade = append(toUpgrade, t)
+			continue
+		}
+		ok, err := isInstalled(ctx, t.Name)
+		if err != nil {
+			return snack.InstallResult{}, err
+		}
+		if !ok {
+			unchanged = append(unchanged, t.Name)
+		} else {
+			toUpgrade = append(toUpgrade, t)
+		}
+	}
+	if len(toUpgrade) > 0 {
+		for _, t := range toUpgrade {
+			args := []string{"update", "-y", t.Name}
+			cmd := exec.CommandContext(ctx, "flatpak", args...)
+			var stderr bytes.Buffer
+			cmd.Stderr = &stderr
+			if err := cmd.Run(); err != nil {
+				return snack.InstallResult{}, fmt.Errorf("flatpak update %s: %w: %s", t.Name, err, stderr.String())
+			}
+		}
+	}
+	var upgraded []snack.Package
+	for _, t := range toUpgrade {
+		v, _ := version(ctx, t.Name)
+		upgraded = append(upgraded, snack.Package{Name: t.Name, Version: v, Installed: true})
+	}
+	return snack.InstallResult{Installed: upgraded, Unchanged: unchanged}, nil
+}

flatpak/flatpak_other.go

@@ -61,3 +61,7 @@ func addRepo(_ context.Context, _ snack.Repository) error {
 func removeRepo(_ context.Context, _ string) error {
 	return snack.ErrUnsupportedPlatform
 }
+
+func upgradePackages(_ context.Context, _ []snack.Target, _ ...snack.Option) (snack.InstallResult, error) {
+	return snack.InstallResult{}, snack.ErrUnsupportedPlatform
+}

pacman/pacman.go

@@ -85,3 +85,11 @@ func (p *Pacman) Version(ctx context.Context, pkg string) (string, error) {
 
 // Verify interface compliance at compile time.
 var _ snack.Manager = (*Pacman)(nil)
+var _ snack.PackageUpgrader = (*Pacman)(nil)
+
+// UpgradePackages upgrades specific installed packages.
+func (p *Pacman) UpgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	p.Lock()
+	defer p.Unlock()
+	return upgradePackages(ctx, pkgs, opts...)
+}

pacman/pacman_linux.go

@@ -219,3 +219,36 @@ func version(ctx context.Context, pkg string) (string, error) {
 	}
 	return parts[1], nil
 }
+
+func upgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	o := snack.ApplyOptions(opts...)
+	var toUpgrade []snack.Target
+	var unchanged []string
+	for _, t := range pkgs {
+		if o.DryRun {
+			toUpgrade = append(toUpgrade, t)
+			continue
+		}
+		ok, err := isInstalled(ctx, t.Name)
+		if err != nil {
+			return snack.InstallResult{}, err
+		}
+		if !ok {
+			unchanged = append(unchanged, t.Name)
+		} else {
+			toUpgrade = append(toUpgrade, t)
+		}
+	}
+	if len(toUpgrade) > 0 {
+		args := append([]string{"-S"}, formatTargets(toUpgrade)...)
+		if _, err := run(ctx, args, o); err != nil {
+			return snack.InstallResult{}, err
+		}
+	}
+	var upgraded []snack.Package
+	for _, t := range toUpgrade {
+		v, _ := version(ctx, t.Name)
+		upgraded = append(upgraded, snack.Package{Name: t.Name, Version: v, Installed: true})
+	}
+	return snack.InstallResult{Installed: upgraded, Unchanged: unchanged}, nil
+}

pacman/pacman_other.go

@@ -49,3 +49,7 @@ func isInstalled(_ context.Context, _ string) (bool, error) {
 func version(_ context.Context, _ string) (string, error) {
 	return "", snack.ErrUnsupportedPlatform
 }
+
+func upgradePackages(_ context.Context, _ []snack.Target, _ ...snack.Option) (snack.InstallResult, error) {
+	return snack.InstallResult{}, snack.ErrUnsupportedPlatform
+}

pkg/pkg.go

@@ -85,3 +85,11 @@ func (p *Pkg) Version(ctx context.Context, pkg string) (string, error) {
 
 // Verify interface compliance at compile time.
 var _ snack.Manager = (*Pkg)(nil)
+var _ snack.PackageUpgrader = (*Pkg)(nil)
+
+// UpgradePackages upgrades specific installed packages.
+func (p *Pkg) UpgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	p.Lock()
+	defer p.Unlock()
+	return upgradePackages(ctx, pkgs, opts...)
+}

pkg/pkg_freebsd.go

@@ -197,3 +197,36 @@ func version(ctx context.Context, pkg string) (string, error) {
 	}
 	return v, nil
 }
+
+func upgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	o := snack.ApplyOptions(opts...)
+	var toUpgrade []snack.Target
+	var unchanged []string
+	for _, t := range pkgs {
+		if o.DryRun {
+			toUpgrade = append(toUpgrade, t)
+			continue
+		}
+		ok, err := isInstalled(ctx, t.Name)
+		if err != nil {
+			return snack.InstallResult{}, err
+		}
+		if !ok {
+			unchanged = append(unchanged, t.Name)
+		} else {
+			toUpgrade = append(toUpgrade, t)
+		}
+	}
+	if len(toUpgrade) > 0 {
+		args := append([]string{"upgrade", "-y"}, snack.TargetNames(toUpgrade)...)
+		if _, err := run(ctx, args, o); err != nil {
+			return snack.InstallResult{}, err
+		}
+	}
+	var upgraded []snack.Package
+	for _, t := range toUpgrade {
+		v, _ := version(ctx, t.Name)
+		upgraded = append(upgraded, snack.Package{Name: t.Name, Version: v, Installed: true})
+	}
+	return snack.InstallResult{Installed: upgraded, Unchanged: unchanged}, nil
+}

pkg/pkg_other.go

@@ -49,3 +49,7 @@ func isInstalled(_ context.Context, _ string) (bool, error) {
 func version(_ context.Context, _ string) (string, error) {
 	return "", snack.ErrUnsupportedPlatform
 }
+
+func upgradePackages(_ context.Context, _ []snack.Target, _ ...snack.Option) (snack.InstallResult, error) {
+	return snack.InstallResult{}, snack.ErrUnsupportedPlatform
+}

snack.go

@@ -220,3 +220,15 @@ type DryRunner interface {
 	// SupportsDryRun reports whether this backend honors [WithDryRun].
 	SupportsDryRun() bool
 }
+
+// PackageUpgrader provides targeted package upgrades (as opposed to Upgrade
+// which upgrades everything). Backends that implement this use native upgrade
+// commands that only act on already-installed packages.
+//
+// Supported by: apt, dnf, pacman, apk, pkg (FreeBSD), flatpak, snap.
+type PackageUpgrader interface {
+	// UpgradePackages upgrades specific installed packages to their latest
+	// versions. Packages that are not installed are skipped (not installed).
+	// Returns an InstallResult describing what changed.
+	UpgradePackages(ctx context.Context, pkgs []Target, opts ...Option) (InstallResult, error)
+}

snap/snap.go

@@ -83,3 +83,11 @@ func (s *Snap) Version(ctx context.Context, pkg string) (string, error) {
 
 // Verify interface compliance at compile time.
 var _ snack.Manager = (*Snap)(nil)
+var _ snack.PackageUpgrader = (*Snap)(nil)
+
+// UpgradePackages upgrades specific installed packages.
+func (s *Snap) UpgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	s.Lock()
+	defer s.Unlock()
+	return upgradePackages(ctx, pkgs, opts...)
+}

snap/snap_linux.go

@@ -231,3 +231,40 @@ func upgradeAvailable(ctx context.Context, pkg string) (bool, error) {
 func versionCmp(_ context.Context, ver1, ver2 string) (int, error) {
 	return semverCmp(ver1, ver2), nil
 }
+
+func upgradePackages(ctx context.Context, pkgs []snack.Target, opts ...snack.Option) (snack.InstallResult, error) {
+	o := snack.ApplyOptions(opts...)
+	var toUpgrade []snack.Target
+	var unchanged []string
+	for _, t := range pkgs {
+		if o.DryRun {
+			toUpgrade = append(toUpgrade, t)
+			continue
+		}
+		ok, err := isInstalled(ctx, t.Name)
+		if err != nil {
+			return snack.InstallResult{}, err
+		}
+		if !ok {
+			unchanged = append(unchanged, t.Name)
+		} else {
+			toUpgrade = append(toUpgrade, t)
+		}
+	}
+	if len(toUpgrade) > 0 {
+		for _, t := range toUpgrade {
+			cmd := exec.CommandContext(ctx, "snap", "refresh", t.Name)
+			var stderr bytes.Buffer
+			cmd.Stderr = &stderr
+			if err := cmd.Run(); err != nil {
+				return snack.InstallResult{}, fmt.Errorf("snap refresh %s: %w: %s", t.Name, err, stderr.String())
+			}
+		}
+	}
+	var upgraded []snack.Package
+	for _, t := range toUpgrade {
+		v, _ := version(ctx, t.Name)
+		upgraded = append(upgraded, snack.Package{Name: t.Name, Version: v, Installed: true})
+	}
+	return snack.InstallResult{Installed: upgraded, Unchanged: unchanged}, nil
+}

snap/snap_other.go

@@ -65,3 +65,7 @@ func upgradeAvailable(_ context.Context, _ string) (bool, error) {
 func versionCmp(_ context.Context, _, _ string) (int, error) {
 	return 0, snack.ErrUnsupportedPlatform
 }
+
+func upgradePackages(_ context.Context, _ []snack.Target, _ ...snack.Option) (snack.InstallResult, error) {
+	return snack.InstallResult{}, snack.ErrUnsupportedPlatform
+}