feat: Enhanced completion with caching for compartment IDs

[mgajda]

Enhanced Completion with Caching for OCI CLI

Summary

This PR adds an enhanced completion system with caching capabilities to the OCI CLI, significantly improving the performance of autocompletion for resource identifiers, particularly compartment IDs.

Problem

Currently, the OCI CLI's autocompletion for parameters like --compartment-id makes real-time API calls every time, which can be slow and impact user experience, especially in environments with high latency or when working with tenancies that have many compartments.

Solution

This PR introduces:

1. Caching Layer: A persistent cache for frequently used OCIDs, particularly compartments
2. Smart Completion: Enhanced completion that uses cached data when available
3. Cache Management: Commands to manage the cache (view status, clear, refresh)

Key Features

1. Compartment Caching

• Caches compartment listings from oci iam compartment list
• 24-hour TTL (Time To Live) by default
• Cache stored in ~/.oci/completion_cache/ directory
• Automatic cache invalidation after TTL expiry

2. Enhanced Completion Module

• CompartmentCompleter class for intelligent compartment completion
• OCIDCache class for generic OCID caching
• Seamless integration with existing interactive mode

3. Cache Management Commands

New commands added under oci setup:

# View cache status
oci setup completion-cache-status

# Clear cache (with options)
oci setup completion-cache-clear [--expired-only] [--force]

# Refresh compartment cache
oci setup completion-cache-refresh

Implementation Details

Files Added:

1. src/interactive/enhanced_completions.py - Core caching and completion logic
2. src/interactive/enable_enhanced_completions.py - Integration module
3. src/oci_cli/custom_types/cli_completion_cache.py - CLI commands for cache management

Files Modified:

1. src/interactive/cli_interactive.py - Enable enhanced completions on interactive mode start
2. src/oci_cli/cli_setup.py - Add cache management commands

Benefits

1. Performance: Dramatically faster compartment ID completion (near-instant vs. 1-3 seconds per lookup)
2. Offline Support: Can work with cached data when API is temporarily unavailable
3. Reduced API Calls: Fewer requests to OCI API, reducing load and potential rate limiting
4. User Control: Users can manage cache lifetime and manually refresh when needed

Testing

Manual Testing Steps:

1. Install the modified OCI CLI: pip install -e .
2. Enter interactive mode: oci -i
3. Type a command requiring compartment ID and test autocompletion
4. Verify cache is created: oci setup completion-cache-status
5. Test cache refresh: oci setup completion-cache-refresh
6. Test cache clearing: oci setup completion-cache-clear

Performance Comparison:

• Before: Each compartment ID completion takes 1-3 seconds
• After: First completion takes 1-3 seconds (to populate cache), subsequent completions are instant

Backward Compatibility

• Fully backward compatible
• Enhanced completions are opt-in and automatically enabled in interactive mode
• Falls back to original behavior if cache is unavailable
• No changes to existing CLI commands or parameters

Future Enhancements

Potential future improvements:

1. Extend caching to other resource types (VCNs, instances, etc.)
2. Configurable cache TTL per resource type
3. Background cache refresh
4. Cache sharing between profiles/regions

Checklist

• Code follows existing code style
• New features are documented
• Backward compatibility maintained
• Cache management commands added
• Error handling implemented
• Cache directory permissions handled correctly

Notes

This implementation focuses on compartment IDs as they are among the most frequently used parameters in OCI CLI. The architecture is designed to be extensible for other resource types in the future.

The cache is profile and region-aware, ensuring that cached data is properly isolated between different OCI configurations.

[oracle-contributor-agreement]

Thank you for your pull request and welcome to our community! To contribute, please sign the Oracle Contributor Agreement (OCA).
The following contributors of this PR have not signed the OCA:

• PR author: mgajda
• mjgajda@migamake.com (@mgajda)

To sign the OCA, please create an Oracle account and sign the OCA in Oracle's Contributor Agreement Application.

When signing the OCA, please provide your GitHub username. After signing the OCA and getting an OCA approval from Oracle, this PR will be automatically updated.

If you are an Oracle employee, please make sure that you are a member of the main Oracle GitHub organization, and your membership in this organization is public.

[mgajda]

Awaiting review and approval of my contributor agreement.