subx_cli/commands/

cache_command.rs

//! Cache management command implementation with comprehensive cleanup capabilities.
//!
//! This module provides sophisticated cache management functionality through
//! the `cache` subcommand, enabling users to inspect, maintain, and clean up
//! various types of cached data that SubX accumulates during operation. The
//! cache system is crucial for performance optimization and API cost reduction.
//!
//! # Cache System Overview
//!
//! SubX maintains multiple types of caches to optimize performance:
//!
//! ## AI Analysis Cache
//! - **Purpose**: Store results from expensive AI API calls
//! - **Content**: File analysis results, matching decisions, confidence scores
//! - **Benefits**: Reduce API costs, improve response times, enable offline review
//! - **Location**: `~/.config/subx/ai_cache/`
//! - **Format**: JSON files with content hashes as keys
//!
//! ## Dry-run Results Cache
//! - **Purpose**: Preserve preview results for later application
//! - **Content**: Planned file operations, rename proposals, backup locations
//! - **Benefits**: Review before apply, batch operations, undo planning
//! - **Location**: `~/.config/subx/match_cache.json`
//! - **Format**: Structured JSON with operation metadata
//!
//! ## Audio Analysis Cache
//! - **Purpose**: Store computationally expensive audio processing results
//! - **Content**: Speech detection patterns, timing analysis, correlation data
//! - **Benefits**: Faster re-synchronization, batch processing optimization
//! - **Location**: `~/.config/subx/audio_cache/`
//! - **Format**: Binary files with audio fingerprints
//!
//! ## Configuration Cache
//! - **Purpose**: Processed and validated configuration data
//! - **Content**: Merged configuration, validation results, computed settings
//! - **Benefits**: Faster application startup, consistency validation
//! - **Location**: `~/.config/subx/config_cache/`
//! - **Format**: Serialized configuration structures
//!
//! # Cache Management Operations
//!
//! ## Clear Operation
//! - **Scope**: Remove all cached data across all cache types
//! - **Safety**: Non-destructive to actual subtitle and video files
//! - **Impact**: Next operations will require fresh computation/API calls
//! - **Recovery**: All cached data can be regenerated through normal usage
//!
//! ## Status Operation (Future Enhancement)
//! - **Information**: Cache size, age, hit rates, storage usage
//! - **Analysis**: Identify stale or corrupted cache entries
//! - **Optimization**: Suggest cache maintenance actions
//! - **Reporting**: Usage statistics and efficiency metrics
//!
//! ## Selective Clear (Future Enhancement)
//! - **Type-specific**: Clear only AI, audio, or configuration cache
//! - **Age-based**: Remove cache entries older than specified time
//! - **Size-based**: Remove least recently used entries to reduce disk usage
//! - **Pattern-based**: Clear cache entries matching specific criteria
//!
//! # Performance Impact
//!
//! ## After Cache Clear
//! - **AI Operations**: Will require fresh API calls (increased time/cost)
//! - **Audio Processing**: Re-analysis required for sync operations
//! - **Configuration**: Slight startup delay for configuration processing
//! - **File Operations**: No impact on actual file processing capabilities
//!
//! ## Cache Regeneration
//! - **Automatic**: Caches rebuild naturally during normal operations
//! - **Intelligent**: Only necessary computations are performed
//! - **Progressive**: Cache rebuilds incrementally as features are used
//! - **Optimized**: New cache generation benefits from previous optimizations
//!
//! # Examples
//!
//! ```rust,ignore
//! use subx_cli::cli::{CacheArgs, CacheAction};
//! use subx_cli::commands::cache_command;
//!
//! // Clear all cache data
//! let clear_args = CacheArgs {
//!     action: CacheAction::Clear,
//! };
//! cache_command::execute(clear_args).await?;
//! ```

use crate::Result;
use crate::cli::CacheArgs;
use crate::config::ConfigService;
use crate::error::SubXError;
use dirs;

/// 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
///
/// ```rust,ignore
/// 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
pub async fn execute(args: CacheArgs) -> Result<()> {
    match args.action {
        crate::cli::CacheAction::Clear => {
            // Determine the appropriate cache directory using standard conventions
            let dir = dirs::config_dir()
                .ok_or_else(|| SubXError::config("Unable to determine cache directory"))?;
            let path = dir.join("subx").join("match_cache.json");

            if path.exists() {
                // Remove the cache file with proper error handling
                std::fs::remove_file(&path)?;
                println!("Cache file cleared: {}", path.display());
            } else {
                println!("No cache file found");
            }
        }
    }
    Ok(())
}

/// Execute cache management command with injected configuration service.
///
/// This function provides the new dependency injection interface for the cache command,
/// accepting a configuration service instead of loading configuration globally.
///
/// # Arguments
///
/// * `args` - Cache command arguments
/// * `config_service` - Configuration service providing access to cache settings
///
/// # Returns
///
/// Returns `Ok(())` on successful completion, or an error if the operation fails.
pub async fn execute_with_config(
    args: CacheArgs,
    _config_service: std::sync::Arc<dyn ConfigService>,
) -> Result<()> {
    // Cache command doesn't need complex configuration, delegate to original implementation
    execute(args).await
}