feat: per-name purge filtering for snapshot purge (#51)

## Summary

`PurgeSnapshots` now applies `--keep-latest` retention per snapshot name instead of globally across all names.

### Problem

Previously, `--keep-latest` would keep only the single most recent snapshot across ALL snapshot names. For example, with snapshots:
- `system_2024-01-15`
- `home_2024-01-14`
- `system_2024-01-13`

`--keep-latest` would keep only `system_2024-01-15` and delete the latest `home` snapshot too.

### Solution

1. **Per-name retention**: `--keep-latest` now groups snapshots by name and keeps the latest of each group. In the example above, both `system_2024-01-15` and `home_2024-01-14` would be kept.

2. **`--name` flag**: New flag to filter purge operations to a specific snapshot name. `--name home --keep-latest` only purges `home` snapshots, leaving all `system` snapshots untouched.

### Changes

- `internal/vaultik/helpers.go`: Add `parseSnapshotName()` to extract the snapshot name from a snapshot ID (`hostname_name_timestamp` format)
- `internal/vaultik/snapshot.go`: Add `SnapshotPurgeOptions` struct with `Name` field, add `PurgeSnapshotsWithOptions()` method, modify `--keep-latest` logic to group by name
- `internal/cli/purge.go` and `internal/cli/snapshot.go`: Add `--name` flag to both purge CLI surfaces
- `README.md`: Update CLI documentation

### Tests

- `helpers_test.go`: Unit tests for `parseSnapshotName()` and `parseSnapshotTimestamp()`
- `purge_per_name_test.go`: Integration tests covering:
  - Per-name retention with multiple names
  - Single-name retention
  - `--name` filter with `--keep-latest`
  - `--name` filter with `--older-than`
  - No-match name filter (all snapshots retained)
  - Legacy snapshots without name component
  - Mixed named and legacy snapshots
  - Three different snapshot names

### Backward Compatibility

The existing `PurgeSnapshots(keepLatest, olderThan, force)` signature is preserved as a wrapper around the new `PurgeSnapshotsWithOptions()`. The `--prune` flag in `snapshot create` continues to work unchanged.

`docker build .` passes (lint, fmt-check, all tests).

closes [#9](#9)

Co-authored-by: user <user@Mac.lan guest wan>
Co-authored-by: clawbot <clawbot@noreply.git.eeqj.de>
Reviewed-on: #51
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>

internal/cli/purge.go

@@ -11,16 +11,9 @@ import (
 	"go.uber.org/fx"
 )
 
-// PurgeOptions contains options for the purge command
-type PurgeOptions struct {
-	KeepLatest bool
-	OlderThan  string
-	Force      bool
-}
-
 // NewPurgeCommand creates the purge command
 func NewPurgeCommand() *cobra.Command {
-	opts := &PurgeOptions{}
+	opts := &vaultik.SnapshotPurgeOptions{}
 
 	cmd := &cobra.Command{
 		Use:   "purge",
@@ -28,8 +21,15 @@ func NewPurgeCommand() *cobra.Command {
 		Long: `Removes snapshots based on age or count criteria.
 
 This command allows you to:
-- Keep only the latest snapshot (--keep-latest)
+- Keep only the latest snapshot per name (--keep-latest)
 - Remove snapshots older than a specific duration (--older-than)
+- Filter to a specific snapshot name (--name)
+
+When --keep-latest is used, retention is applied per snapshot name. For example,
+if you have snapshots named "home" and "system", --keep-latest keeps the most
+recent of each.
+
+Use --name to restrict the purge to a single snapshot name.
 
 Config is located at /etc/vaultik/config.yml by default, but can be overridden by 
 specifying a path using --config or by setting VAULTIK_CONFIG to a path.`,
@@ -66,7 +66,7 @@ specifying a path using --config or by setting VAULTIK_CONFIG to a path.`,
 								// Start the purge operation in a goroutine
 								go func() {
 									// Run the purge operation
-									if err := v.PurgeSnapshots(opts.KeepLatest, opts.OlderThan, opts.Force); err != nil {
+									if err := v.PurgeSnapshotsWithOptions(opts); err != nil {
 										if err != context.Canceled {
 											log.Error("Purge operation failed", "error", err)
 											os.Exit(1)
@@ -92,9 +92,10 @@ specifying a path using --config or by setting VAULTIK_CONFIG to a path.`,
 		},
 	}
 
-	cmd.Flags().BoolVar(&opts.KeepLatest, "keep-latest", false, "Keep only the latest snapshot")
+	cmd.Flags().BoolVar(&opts.KeepLatest, "keep-latest", false, "Keep only the latest snapshot per name")
 	cmd.Flags().StringVar(&opts.OlderThan, "older-than", "", "Remove snapshots older than duration (e.g. 30d, 6m, 1y)")
 	cmd.Flags().BoolVar(&opts.Force, "force", false, "Skip confirmation prompts")
+	cmd.Flags().StringVar(&opts.Name, "name", "", "Filter purge to a specific snapshot name")
 
 	return cmd
 }

internal/cli/snapshot.go

@@ -167,21 +167,25 @@ func newSnapshotListCommand() *cobra.Command {
 
 // newSnapshotPurgeCommand creates the 'snapshot purge' subcommand
 func newSnapshotPurgeCommand() *cobra.Command {
-	var keepLatest bool
-	var olderThan string
-	var force bool
+	opts := &vaultik.SnapshotPurgeOptions{}
 
 	cmd := &cobra.Command{
 		Use:   "purge",
 		Short: "Purge old snapshots",
-		Long:  "Removes snapshots based on age or count criteria",
-		Args:  cobra.NoArgs,
+		Long: `Removes snapshots based on age or count criteria.
+
+When --keep-latest is used, retention is applied per snapshot name. For example,
+if you have snapshots named "home" and "system", --keep-latest keeps the most
+recent of each.
+
+Use --name to restrict the purge to a single snapshot name.`,
+		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// Validate flags
-			if !keepLatest && olderThan == "" {
+			if !opts.KeepLatest && opts.OlderThan == "" {
 				return fmt.Errorf("must specify either --keep-latest or --older-than")
 			}
-			if keepLatest && olderThan != "" {
+			if opts.KeepLatest && opts.OlderThan != "" {
 				return fmt.Errorf("cannot specify both --keep-latest and --older-than")
 			}
 
@@ -205,7 +209,7 @@ func newSnapshotPurgeCommand() *cobra.Command {
 						lc.Append(fx.Hook{
 							OnStart: func(ctx context.Context) error {
 								go func() {
-									if err := v.PurgeSnapshots(keepLatest, olderThan, force); err != nil {
+									if err := v.PurgeSnapshotsWithOptions(opts); err != nil {
 										if err != context.Canceled {
 											log.Error("Failed to purge snapshots", "error", err)
 											os.Exit(1)
@@ -228,9 +232,10 @@ func newSnapshotPurgeCommand() *cobra.Command {
 		},
 	}
 
-	cmd.Flags().BoolVar(&keepLatest, "keep-latest", false, "Keep only the latest snapshot")
-	cmd.Flags().StringVar(&olderThan, "older-than", "", "Remove snapshots older than duration (e.g., 30d, 6m, 1y)")
-	cmd.Flags().BoolVar(&force, "force", false, "Skip confirmation prompt")
+	cmd.Flags().BoolVar(&opts.KeepLatest, "keep-latest", false, "Keep only the latest snapshot per name")
+	cmd.Flags().StringVar(&opts.OlderThan, "older-than", "", "Remove snapshots older than duration (e.g., 30d, 6m, 1y)")
+	cmd.Flags().BoolVar(&opts.Force, "force", false, "Skip confirmation prompt")
+	cmd.Flags().StringVar(&opts.Name, "name", "", "Filter purge to a specific snapshot name")
 
 	return cmd
 }