Refactor: break up oversized methods into smaller descriptive helpers (#41)

Closes #40

Per sneak's feedback on PR #37: methods were too long. This PR breaks all methods over 100-150 lines into smaller, descriptively named helper methods.

## Refactored methods (8 total)

| Original | Lines | Helpers extracted |
|---|---|---|
| `createNamedSnapshot` | 214 | `resolveSnapshotPaths`, `scanAllDirectories`, `collectUploadStats`, `finalizeSnapshotMetadata`, `printSnapshotSummary`, `getSnapshotBlobSizes`, `formatUploadSpeed` |
| `ListSnapshots` | 159 | `listRemoteSnapshotIDs`, `reconcileLocalWithRemote`, `buildSnapshotInfoList`, `printSnapshotTable` |
| `PruneBlobs` | 170 | `collectReferencedBlobs`, `listUniqueSnapshotIDs`, `listAllRemoteBlobs`, `findUnreferencedBlobs`, `deleteUnreferencedBlobs` |
| `RunDeepVerify` | 182 | `loadVerificationData`, `runVerificationSteps`, `deepVerifyFailure` |
| `RemoteInfo` | 187 | `collectSnapshotMetadata`, `collectReferencedBlobsFromManifests`, `populateRemoteInfoResult`, `scanRemoteBlobStorage`, `printRemoteInfoTable` |
| `handleBlobReady` | 173 | `uploadBlobIfNeeded`, `makeUploadProgressCallback`, `recordBlobMetadata`, `cleanupBlobTempFile` |
| `processFileStreaming` | 146 | `updateChunkStats`, `addChunkToPacker`, `queueFileForBatchInsert` |
| `finalizeCurrentBlob` | 167 | `closeBlobWriter`, `buildChunkRefs`, `commitBlobToDatabase`, `deliverFinishedBlob` |

## Verification

- `go build ./...` ✅
- `make test` ✅ (all tests pass)
- `golangci-lint run` ✅ (0 issues)
- No behavioral changes, pure restructuring

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

internal/vaultik/restore.go

@@ -55,15 +55,9 @@ type RestoreResult struct {
 func (v *Vaultik) Restore(opts *RestoreOptions) error {
 	startTime := time.Now()
 
-	// Check for age_secret_key
-	if v.Config.AgeSecretKey == "" {
-		return fmt.Errorf("decryption key required for restore\n\nSet the VAULTIK_AGE_SECRET_KEY environment variable to your age private key:\n  export VAULTIK_AGE_SECRET_KEY='AGE-SECRET-KEY-...'")
-	}
-
-	// Parse the age identity
-	identity, err := age.ParseX25519Identity(v.Config.AgeSecretKey)
+	identity, err := v.prepareRestoreIdentity()
 	if err != nil {
-		return fmt.Errorf("parsing age secret key: %w", err)
+		return err
 	}
 
 	log.Info("Starting restore operation",
@@ -115,10 +109,73 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 	}
 
 	// Step 5: Restore files
+	result, err := v.restoreAllFiles(files, repos, opts, identity, chunkToBlobMap)
+	if err != nil {
+		return err
+	}
+
+	result.Duration = time.Since(startTime)
+
+	log.Info("Restore complete",
+		"files_restored", result.FilesRestored,
+		"bytes_restored", humanize.Bytes(uint64(result.BytesRestored)),
+		"blobs_downloaded", result.BlobsDownloaded,
+		"bytes_downloaded", humanize.Bytes(uint64(result.BytesDownloaded)),
+		"duration", result.Duration,
+	)
+
+	v.printfStdout("Restored %d files (%s) in %s\n",
+		result.FilesRestored,
+		humanize.Bytes(uint64(result.BytesRestored)),
+		result.Duration.Round(time.Second),
+	)
+
+	if result.FilesFailed > 0 {
+		_, _ = fmt.Fprintf(v.Stdout, "\nWARNING: %d file(s) failed to restore:\n", result.FilesFailed)
+		for _, path := range result.FailedFiles {
+			_, _ = fmt.Fprintf(v.Stdout, "  - %s\n", path)
+		}
+	}
+
+	// Run verification if requested
+	if opts.Verify {
+		if err := v.handleRestoreVerification(repos, files, opts, result); err != nil {
+			return err
+		}
+	}
+
+	if result.FilesFailed > 0 {
+		return fmt.Errorf("%d file(s) failed to restore", result.FilesFailed)
+	}
+
+	return nil
+}
+
+// prepareRestoreIdentity validates that an age secret key is configured and parses it
+func (v *Vaultik) prepareRestoreIdentity() (age.Identity, error) {
+	if v.Config.AgeSecretKey == "" {
+		return nil, fmt.Errorf("decryption key required for restore\n\nSet the VAULTIK_AGE_SECRET_KEY environment variable to your age private key:\n  export VAULTIK_AGE_SECRET_KEY='AGE-SECRET-KEY-...'")
+	}
+
+	identity, err := age.ParseX25519Identity(v.Config.AgeSecretKey)
+	if err != nil {
+		return nil, fmt.Errorf("parsing age secret key: %w", err)
+	}
+	return identity, nil
+}
+
+// restoreAllFiles iterates over files and restores each one, tracking progress and failures
+func (v *Vaultik) restoreAllFiles(
+	files []*database.File,
+	repos *database.Repositories,
+	opts *RestoreOptions,
+	identity age.Identity,
+	chunkToBlobMap map[string]*database.BlobChunk,
+) (*RestoreResult, error) {
 	result := &RestoreResult{}
 	blobCache, err := newBlobDiskCache(4 * v.Config.BlobSizeLimit.Int64())
 	if err != nil {
-		return fmt.Errorf("creating blob cache: %w", err)
+		return nil, fmt.Errorf("creating blob cache: %w", err)
 	}
 	defer func() { _ = blobCache.Close() }()
 
@@ -133,7 +190,7 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 
 	for i, file := range files {
 		if v.ctx.Err() != nil {
-			return v.ctx.Err()
+			return nil, v.ctx.Err()
 		}
 
 		if err := v.restoreFile(v.ctx, repos, file, opts.TargetDir, identity, chunkToBlobMap, blobCache, result); err != nil {
@@ -165,53 +222,32 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 		_ = bar.Finish()
 	}
 
-	result.Duration = time.Since(startTime)
+	return result, nil
+}
 
-	log.Info("Restore complete",
-		"files_restored", result.FilesRestored,
-		"bytes_restored", humanize.Bytes(uint64(result.BytesRestored)),
-		"blobs_downloaded", result.BlobsDownloaded,
-		"bytes_downloaded", humanize.Bytes(uint64(result.BytesDownloaded)),
-		"duration", result.Duration,
-	)
-
-	v.printfStdout("Restored %d files (%s) in %s\n",
-		result.FilesRestored,
-		humanize.Bytes(uint64(result.BytesRestored)),
-		result.Duration.Round(time.Second),
-	)
+// handleRestoreVerification runs post-restore verification if requested
+func (v *Vaultik) handleRestoreVerification(
+	repos *database.Repositories,
+	files []*database.File,
+	opts *RestoreOptions,
+	result *RestoreResult,
+) error {
+	if err := v.verifyRestoredFiles(v.ctx, repos, files, opts.TargetDir, result); err != nil {
+		return fmt.Errorf("verification failed: %w", err)
+	}
 
 	if result.FilesFailed > 0 {
-		_, _ = fmt.Fprintf(v.Stdout, "\nWARNING: %d file(s) failed to restore:\n", result.FilesFailed)
+		v.printfStdout("\nVerification FAILED: %d files did not match expected checksums\n", result.FilesFailed)
 		for _, path := range result.FailedFiles {
-			_, _ = fmt.Fprintf(v.Stdout, "  - %s\n", path)
+			v.printfStdout("  - %s\n", path)
 		}
+		return fmt.Errorf("%d files failed verification", result.FilesFailed)
 	}
 
-	// Run verification if requested
-	if opts.Verify {
-		if err := v.verifyRestoredFiles(v.ctx, repos, files, opts.TargetDir, result); err != nil {
-			return fmt.Errorf("verification failed: %w", err)
-		}
-
-		if result.FilesFailed > 0 {
-			v.printfStdout("\nVerification FAILED: %d files did not match expected checksums\n", result.FilesFailed)
-			for _, path := range result.FailedFiles {
-				v.printfStdout("  - %s\n", path)
-			}
-			return fmt.Errorf("%d files failed verification", result.FilesFailed)
-		}
-
-		v.printfStdout("Verified %d files (%s)\n",
-			result.FilesVerified,
-			humanize.Bytes(uint64(result.BytesVerified)),
-		)
-	}
-
-	if result.FilesFailed > 0 {
-		return fmt.Errorf("%d file(s) failed to restore", result.FilesFailed)
-	}
-
+	v.printfStdout("Verified %d files (%s)\n",
+		result.FilesVerified,
+		humanize.Bytes(uint64(result.BytesVerified)),
+	)
 	return nil
 }