Function execute 

pub async fn execute(args: CacheArgs) -> Result<()>

Execute cache management operations with comprehensive cleanup and validation.

This function provides the main interface for cache management operations, currently focusing on cache clearing functionality with plans for expanded cache inspection and maintenance capabilities. It ensures safe cache operations while preserving actual user data.

Cache Clear Process

1. Cache Location Discovery: Identify all cache directories and files
2. Validation: Verify cache files are SubX-generated and safe to remove
3. Backup Check: Ensure no critical data will be lost
4. Removal Execution: Systematically remove cache files and directories
5. Verification: Confirm successful removal and cleanup
6. Reporting: Provide user feedback on operations performed

Safety Guarantees

The cache management system provides strong safety guarantees:

• User Data Protection: Never removes actual subtitle or video files
• Configuration Safety: Preserves user configuration files
• Atomic Operations: Complete success or complete failure, no partial state
• Recovery Capability: All removed data can be regenerated automatically
• Validation: Extensive checks before any destructive operations

Cache Types Managed

AI Analysis Results

• File matching cache: Results from AI-powered file correlation
• Content analysis cache: Subtitle content analysis results
• API response cache: Cached responses from AI service providers
• Confidence data: Stored confidence scores and metadata

Processing Results

• Dry-run cache: Preview results for later application
• Operation cache: Planned file operations and metadata
• Backup references: Information about created backup files
• Progress state: Interrupted operation recovery data

System Cache

• Configuration cache: Processed and validated configuration
• Discovery cache: File system scan results
• Format cache: Subtitle format detection results
• Metadata cache: File metadata and characteristics

Error Handling

Comprehensive error handling covers various failure scenarios:

• Permission Issues: Clear guidance for access problems
• Disk Space: Graceful handling of disk space constraints
• Concurrent Access: Safe operation when multiple instances running
• Partial Failures: Detailed reporting of what succeeded/failed
• Recovery Instructions: Clear steps for manual cleanup if needed

Arguments

• args - Cache management arguments containing the specific operation to perform and any associated parameters for cache management tasks.

Returns

Returns Ok(()) on successful cache operation completion, or an error describing specific problems encountered during cache management:

• Configuration directory access issues
• File system permission problems
• Disk space or I/O errors during cleanup
• Cache corruption requiring manual intervention

Future Enhancements

Planned cache management features include:

• Cache Status: Detailed information about cache size and utilization
• Selective Clearing: Clear specific cache types or age ranges
• Cache Statistics: Usage metrics and efficiency analysis
• Automatic Maintenance: Scheduled cleanup and optimization
• Cache Import/Export: Backup and restore cache data

Examples

use subx_cli::cli::{CacheArgs, CacheAction};
use subx_cli::commands::cache_command;

// Basic cache clearing
let clear_all = CacheArgs {
    action: CacheAction::Clear,
};
cache_command::execute(clear_all).await?;

Use Cases

Development and Testing

• Clean State: Reset cache between test runs
• Debugging: Eliminate cache-related variables in troubleshooting
• Performance Testing: Measure operations without cache benefits
• Integration Testing: Ensure fresh state for automated tests

Maintenance and Troubleshooting

• Corruption Recovery: Clear potentially corrupted cache data
• Disk Space Management: Reclaim space used by cache files
• Configuration Changes: Clear cache after major configuration updates
• Version Upgrades: Clear cache when upgrading SubX versions

Privacy and Security

• Data Cleanup: Remove potentially sensitive cached content
• API Key Changes: Clear cache tied to previous credentials
• System Migration: Clean state before moving to new system
• Audit Compliance: Regular cache cleanup for compliance requirements