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/snapshot/snapshot.go

@@ -227,12 +227,39 @@ func (sm *SnapshotManager) ExportSnapshotMetadata(ctx context.Context, dbPath st
 		}
 	}()
 
+	// Steps 1-5: Copy, clean, vacuum, compress, and read the database
+	finalData, tempDBPath, err := sm.prepareExportDB(ctx, dbPath, snapshotID, tempDir)
+	if err != nil {
+		return err
+	}
+
+	// Step 6: Generate blob manifest (before closing temp DB)
+	blobManifest, err := sm.generateBlobManifest(ctx, tempDBPath, snapshotID)
+	if err != nil {
+		return fmt.Errorf("generating blob manifest: %w", err)
+	}
+
+	// Step 7: Upload to S3 in snapshot subdirectory
+	if err := sm.uploadSnapshotArtifacts(ctx, snapshotID, finalData, blobManifest); err != nil {
+		return err
+	}
+
+	log.Info("Uploaded snapshot metadata",
+		"snapshot_id", snapshotID,
+		"db_size", len(finalData),
+		"manifest_size", len(blobManifest))
+	return nil
+}
+
+// prepareExportDB copies, cleans, vacuums, and compresses the snapshot database for export.
+// Returns the compressed data and the path to the temporary database (needed for manifest generation).
+func (sm *SnapshotManager) prepareExportDB(ctx context.Context, dbPath, snapshotID, tempDir string) ([]byte, string, error) {
 	// Step 1: Copy database to temp file
 	// The main database should be closed at this point
 	tempDBPath := filepath.Join(tempDir, "snapshot.db")
 	log.Debug("Copying database to temporary location", "source", dbPath, "destination", tempDBPath)
 	if err := sm.copyFile(dbPath, tempDBPath); err != nil {
-		return fmt.Errorf("copying database: %w", err)
+		return nil, "", fmt.Errorf("copying database: %w", err)
 	}
 	log.Debug("Database copy complete", "size", sm.getFileSize(tempDBPath))
 
@@ -240,7 +267,7 @@ func (sm *SnapshotManager) ExportSnapshotMetadata(ctx context.Context, dbPath st
 	log.Debug("Cleaning temporary database", "snapshot_id", snapshotID)
 	stats, err := sm.cleanSnapshotDB(ctx, tempDBPath, snapshotID)
 	if err != nil {
-		return fmt.Errorf("cleaning snapshot database: %w", err)
+		return nil, "", fmt.Errorf("cleaning snapshot database: %w", err)
 	}
 	log.Info("Temporary database cleanup complete",
 		"db_path", tempDBPath,
@@ -255,14 +282,14 @@ func (sm *SnapshotManager) ExportSnapshotMetadata(ctx context.Context, dbPath st
 	// Step 3: VACUUM the database to remove deleted data and compact
 	// This is critical for security - ensures no stale/deleted data is uploaded
 	if err := sm.vacuumDatabase(tempDBPath); err != nil {
-		return fmt.Errorf("vacuuming database: %w", err)
+		return nil, "", fmt.Errorf("vacuuming database: %w", err)
 	}
 	log.Debug("Database vacuumed", "size", humanize.Bytes(uint64(sm.getFileSize(tempDBPath))))
 
 	// Step 4: Compress and encrypt the binary database file
 	compressedPath := filepath.Join(tempDir, "db.zst.age")
 	if err := sm.compressFile(tempDBPath, compressedPath); err != nil {
-		return fmt.Errorf("compressing database: %w", err)
+		return nil, "", fmt.Errorf("compressing database: %w", err)
 	}
 	log.Debug("Compression complete",
 		"original_size", humanize.Bytes(uint64(sm.getFileSize(tempDBPath))),
@@ -271,49 +298,43 @@ func (sm *SnapshotManager) ExportSnapshotMetadata(ctx context.Context, dbPath st
 	// Step 5: Read compressed and encrypted data for upload
 	finalData, err := afero.ReadFile(sm.fs, compressedPath)
 	if err != nil {
-		return fmt.Errorf("reading compressed dump: %w", err)
+		return nil, "", fmt.Errorf("reading compressed dump: %w", err)
 	}
 
-	// Step 6: Generate blob manifest (before closing temp DB)
-	blobManifest, err := sm.generateBlobManifest(ctx, tempDBPath, snapshotID)
-	if err != nil {
-		return fmt.Errorf("generating blob manifest: %w", err)
-	}
+	return finalData, tempDBPath, nil
+}
 
-	// Step 7: Upload to S3 in snapshot subdirectory
+// uploadSnapshotArtifacts uploads the database backup and blob manifest to S3
+func (sm *SnapshotManager) uploadSnapshotArtifacts(ctx context.Context, snapshotID string, dbData, manifestData []byte) error {
 	// Upload database backup (compressed and encrypted)
 	dbKey := fmt.Sprintf("metadata/%s/db.zst.age", snapshotID)
 
 	dbUploadStart := time.Now()
-	if err := sm.storage.Put(ctx, dbKey, bytes.NewReader(finalData)); err != nil {
+	if err := sm.storage.Put(ctx, dbKey, bytes.NewReader(dbData)); err != nil {
 		return fmt.Errorf("uploading snapshot database: %w", err)
 	}
 	dbUploadDuration := time.Since(dbUploadStart)
-	dbUploadSpeed := float64(len(finalData)) * 8 / dbUploadDuration.Seconds() // bits per second
+	dbUploadSpeed := float64(len(dbData)) * 8 / dbUploadDuration.Seconds() // bits per second
 	log.Info("Uploaded snapshot database",
 		"path", dbKey,
-		"size", humanize.Bytes(uint64(len(finalData))),
+		"size", humanize.Bytes(uint64(len(dbData))),
 		"duration", dbUploadDuration,
 		"speed", humanize.SI(dbUploadSpeed, "bps"))
 
 	// Upload blob manifest (compressed only, not encrypted)
 	manifestKey := fmt.Sprintf("metadata/%s/manifest.json.zst", snapshotID)
 	manifestUploadStart := time.Now()
-	if err := sm.storage.Put(ctx, manifestKey, bytes.NewReader(blobManifest)); err != nil {
+	if err := sm.storage.Put(ctx, manifestKey, bytes.NewReader(manifestData)); err != nil {
 		return fmt.Errorf("uploading blob manifest: %w", err)
 	}
 	manifestUploadDuration := time.Since(manifestUploadStart)
-	manifestUploadSpeed := float64(len(blobManifest)) * 8 / manifestUploadDuration.Seconds() // bits per second
+	manifestUploadSpeed := float64(len(manifestData)) * 8 / manifestUploadDuration.Seconds() // bits per second
 	log.Info("Uploaded blob manifest",
 		"path", manifestKey,
-		"size", humanize.Bytes(uint64(len(blobManifest))),
+		"size", humanize.Bytes(uint64(len(manifestData))),
 		"duration", manifestUploadDuration,
 		"speed", humanize.SI(manifestUploadSpeed, "bps"))
 
-	log.Info("Uploaded snapshot metadata",
-		"snapshot_id", snapshotID,
-		"db_size", len(finalData),
-		"manifest_size", len(blobManifest))
 	return nil
 }