feat: Add stats command with session-level caching (v5.1.0)

New Features:
- Add 'deltaglider stats' CLI command for bucket compression metrics
- Session-level bucket statistics caching for performance
- Enhanced list_buckets() with cached stats metadata

Technical Changes:
- Automatic cache invalidation on bucket mutations
- Intelligent cache reuse (detailed → quick fallback)
- Comprehensive test coverage (106+ new test lines)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

tests/integration/test_bucket_management.py

@@ -1,11 +1,13 @@
 """Tests for bucket management APIs."""
 
+from typing import Any
 from unittest.mock import Mock
 
 import pytest
 
 from deltaglider.app.cli.main import create_service
 from deltaglider.client import DeltaGliderClient
+from deltaglider.client_models import BucketStats
 
 
 class TestBucketManagement:
@@ -123,6 +125,47 @@ class TestBucketManagement:
         assert response["Buckets"] == []
         assert response["ResponseMetadata"]["HTTPStatusCode"] == 200
 
+    def test_list_buckets_includes_cached_stats(self):
+        """Bucket list should merge cached stats when available."""
+        service = create_service()
+        mock_storage = Mock()
+        service.storage = mock_storage
+
+        mock_boto3_client = Mock()
+        mock_boto3_client.list_buckets.return_value = {
+            "Buckets": [
+                {"Name": "bucket1", "CreationDate": "2025-01-01T00:00:00Z"},
+                {"Name": "bucket2", "CreationDate": "2025-01-02T00:00:00Z"},
+            ],
+            "Owner": {"DisplayName": "test-user", "ID": "12345"},
+        }
+        mock_storage.client = mock_boto3_client
+
+        client = DeltaGliderClient(service)
+
+        cached_stats = BucketStats(
+            bucket="bucket1",
+            object_count=10,
+            total_size=1000,
+            compressed_size=600,
+            space_saved=400,
+            average_compression_ratio=0.4,
+            delta_objects=6,
+            direct_objects=4,
+        )
+        client._store_bucket_stats_cache("bucket1", detailed_stats=True, stats=cached_stats)
+
+        response = client.list_buckets()
+
+        bucket1 = next(bucket for bucket in response["Buckets"] if bucket["Name"] == "bucket1")
+        assert bucket1["DeltaGliderStats"]["Cached"] is True
+        assert bucket1["DeltaGliderStats"]["Detailed"] is True
+        assert bucket1["DeltaGliderStats"]["ObjectCount"] == cached_stats.object_count
+        assert bucket1["DeltaGliderStats"]["TotalSize"] == cached_stats.total_size
+
+        bucket2 = next(bucket for bucket in response["Buckets"] if bucket["Name"] == "bucket2")
+        assert "DeltaGliderStats" not in bucket2
+
     def test_delete_bucket_success(self):
         """Test deleting a bucket successfully."""
         service = create_service()
@@ -178,6 +221,69 @@ class TestBucketManagement:
         with pytest.raises(RuntimeError, match="Failed to delete bucket"):
             client.delete_bucket(Bucket="full-bucket")
 
+    def test_get_bucket_stats_caches_per_session(self, monkeypatch):
+        """Verify bucket stats are cached within the client session."""
+        service = create_service()
+        mock_storage = Mock()
+        service.storage = mock_storage
+
+        mock_storage.client = Mock()
+
+        client = DeltaGliderClient(service)
+
+        quick_stats = BucketStats(
+            bucket="bucket1",
+            object_count=5,
+            total_size=500,
+            compressed_size=300,
+            space_saved=200,
+            average_compression_ratio=0.4,
+            delta_objects=3,
+            direct_objects=2,
+        )
+        detailed_stats = BucketStats(
+            bucket="bucket1",
+            object_count=5,
+            total_size=520,
+            compressed_size=300,
+            space_saved=220,
+            average_compression_ratio=0.423,
+            delta_objects=3,
+            direct_objects=2,
+        )
+
+        call_count = {"value": 0}
+
+        def fake_get_bucket_stats(_: Any, bucket: str, detailed_stats_flag: bool) -> BucketStats:
+            call_count["value"] += 1
+            assert bucket == "bucket1"
+            return detailed_stats if detailed_stats_flag else quick_stats
+
+        monkeypatch.setattr("deltaglider.client._get_bucket_stats", fake_get_bucket_stats)
+
+        # First call should invoke underlying function
+        result_quick = client.get_bucket_stats("bucket1")
+        assert result_quick is quick_stats
+        assert call_count["value"] == 1
+
+        # Second quick call should hit cache
+        assert client.get_bucket_stats("bucket1") is quick_stats
+        assert call_count["value"] == 1
+
+        # Detailed call triggers new computation
+        result_detailed = client.get_bucket_stats("bucket1", detailed_stats=True)
+        assert result_detailed is detailed_stats
+        assert call_count["value"] == 2
+
+        # Quick call after detailed uses detailed cached value (more accurate)
+        assert client.get_bucket_stats("bucket1") is detailed_stats
+        assert call_count["value"] == 2
+
+        # Clearing the cache should force recomputation
+        client.clear_cache()
+        assert client.get_bucket_stats("bucket1") is quick_stats
+        assert call_count["value"] == 3
+
     def test_bucket_methods_without_boto3_client(self):
         """Test that bucket methods raise NotImplementedError when storage doesn't support it."""
         service = create_service()

tests/integration/test_stats_command.py

@@ -0,0 +1,206 @@
+"""Integration tests for stats CLI command."""
+
+import json
+from unittest.mock import Mock, patch
+
+from click.testing import CliRunner
+
+from deltaglider.app.cli.main import cli
+from deltaglider.client_models import BucketStats
+
+
+class TestStatsCommand:
+    """Test stats CLI command."""
+
+    def test_stats_json_output(self):
+        """Test stats command with JSON output."""
+        # Create mock bucket stats
+        mock_stats = BucketStats(
+            bucket="test-bucket",
+            object_count=10,
+            total_size=1000000,
+            compressed_size=500000,
+            space_saved=500000,
+            average_compression_ratio=0.5,
+            delta_objects=7,
+            direct_objects=3,
+        )
+
+        with patch("deltaglider.client.DeltaGliderClient") as mock_client_class:
+            # Setup mock client
+            mock_client = Mock()
+            mock_client.get_bucket_stats.return_value = mock_stats
+            mock_client_class.return_value = mock_client
+
+            # Run command
+            runner = CliRunner()
+            result = runner.invoke(cli, ["stats", "test-bucket", "--json"])
+
+            # Verify
+            assert result.exit_code == 0
+            output = json.loads(result.output)
+            assert output["bucket"] == "test-bucket"
+            assert output["object_count"] == 10
+            assert output["total_size"] == 1000000
+            assert output["compressed_size"] == 500000
+            assert output["space_saved"] == 500000
+            assert output["average_compression_ratio"] == 0.5
+            assert output["delta_objects"] == 7
+            assert output["direct_objects"] == 3
+
+            # Verify client was called correctly
+            mock_client.get_bucket_stats.assert_called_once_with("test-bucket", detailed_stats=False)
+
+    def test_stats_json_output_detailed(self):
+        """Test stats command with detailed JSON output."""
+        mock_stats = BucketStats(
+            bucket="test-bucket",
+            object_count=5,
+            total_size=2000000,
+            compressed_size=100000,
+            space_saved=1900000,
+            average_compression_ratio=0.95,
+            delta_objects=5,
+            direct_objects=0,
+        )
+
+        with patch("deltaglider.client.DeltaGliderClient") as mock_client_class:
+            mock_client = Mock()
+            mock_client.get_bucket_stats.return_value = mock_stats
+            mock_client_class.return_value = mock_client
+
+            runner = CliRunner()
+            result = runner.invoke(cli, ["stats", "test-bucket", "--detailed", "--json"])
+
+            assert result.exit_code == 0
+            output = json.loads(result.output)
+            assert output["average_compression_ratio"] == 0.95
+
+            # Verify detailed flag was passed
+            mock_client.get_bucket_stats.assert_called_once_with("test-bucket", detailed_stats=True)
+
+    def test_stats_human_readable_output(self):
+        """Test stats command with human-readable output."""
+        mock_stats = BucketStats(
+            bucket="test-bucket",
+            object_count=10,
+            total_size=1500000,  # ~1.43 MB
+            compressed_size=300000,  # ~293 KB
+            space_saved=1200000,  # ~1.14 MB
+            average_compression_ratio=0.8,
+            delta_objects=7,
+            direct_objects=3,
+        )
+
+        with patch("deltaglider.client.DeltaGliderClient") as mock_client_class:
+            mock_client = Mock()
+            mock_client.get_bucket_stats.return_value = mock_stats
+            mock_client_class.return_value = mock_client
+
+            runner = CliRunner()
+            result = runner.invoke(cli, ["stats", "test-bucket"])
+
+            assert result.exit_code == 0
+            output = result.output
+
+            # Verify human-readable format
+            assert "Bucket Statistics: test-bucket" in output
+            assert "Total Objects:" in output
+            assert "10" in output
+            assert "Delta Objects:" in output
+            assert "7" in output
+            assert "Direct Objects:" in output
+            assert "3" in output
+            assert "Original Size:" in output
+            assert "Compressed Size:" in output
+            assert "Space Saved:" in output
+            assert "Compression Ratio:" in output
+            assert "80.0%" in output  # 0.8 = 80%
+
+    def test_stats_error_handling(self):
+        """Test stats command error handling."""
+        with patch("deltaglider.client.DeltaGliderClient") as mock_client_class:
+            mock_client = Mock()
+            mock_client.get_bucket_stats.side_effect = Exception("Bucket not found")
+            mock_client_class.return_value = mock_client
+
+            runner = CliRunner()
+            result = runner.invoke(cli, ["stats", "nonexistent-bucket"])
+
+            assert result.exit_code == 1
+            assert "Error: Bucket not found" in result.output
+
+    def test_stats_with_s3_url(self):
+        """Test stats command with s3:// URL format."""
+        mock_stats = BucketStats(
+            bucket="test-bucket",
+            object_count=5,
+            total_size=1000000,
+            compressed_size=500000,
+            space_saved=500000,
+            average_compression_ratio=0.5,
+            delta_objects=3,
+            direct_objects=2,
+        )
+
+        with patch("deltaglider.client.DeltaGliderClient") as mock_client_class:
+            mock_client = Mock()
+            mock_client.get_bucket_stats.return_value = mock_stats
+            mock_client_class.return_value = mock_client
+
+            runner = CliRunner()
+            result = runner.invoke(cli, ["stats", "s3://test-bucket", "--json"])
+
+            assert result.exit_code == 0
+            # Verify bucket name was parsed correctly from S3 URL
+            mock_client.get_bucket_stats.assert_called_once_with("test-bucket", detailed_stats=False)
+
+    def test_stats_with_s3_url_trailing_slash(self):
+        """Test stats command with s3:// URL format with trailing slash."""
+        mock_stats = BucketStats(
+            bucket="test-bucket",
+            object_count=5,
+            total_size=1000000,
+            compressed_size=500000,
+            space_saved=500000,
+            average_compression_ratio=0.5,
+            delta_objects=3,
+            direct_objects=2,
+        )
+
+        with patch("deltaglider.client.DeltaGliderClient") as mock_client_class:
+            mock_client = Mock()
+            mock_client.get_bucket_stats.return_value = mock_stats
+            mock_client_class.return_value = mock_client
+
+            runner = CliRunner()
+            result = runner.invoke(cli, ["stats", "s3://test-bucket/", "--json"])
+
+            assert result.exit_code == 0
+            # Verify bucket name was parsed correctly from S3 URL with trailing slash
+            mock_client.get_bucket_stats.assert_called_once_with("test-bucket", detailed_stats=False)
+
+    def test_stats_with_s3_url_with_prefix(self):
+        """Test stats command with s3:// URL format with prefix (should ignore prefix)."""
+        mock_stats = BucketStats(
+            bucket="test-bucket",
+            object_count=5,
+            total_size=1000000,
+            compressed_size=500000,
+            space_saved=500000,
+            average_compression_ratio=0.5,
+            delta_objects=3,
+            direct_objects=2,
+        )
+
+        with patch("deltaglider.client.DeltaGliderClient") as mock_client_class:
+            mock_client = Mock()
+            mock_client.get_bucket_stats.return_value = mock_stats
+            mock_client_class.return_value = mock_client
+
+            runner = CliRunner()
+            result = runner.invoke(cli, ["stats", "s3://test-bucket/some/prefix/", "--json"])
+
+            assert result.exit_code == 0
+            # Verify only bucket name was extracted, prefix ignored
+            mock_client.get_bucket_stats.assert_called_once_with("test-bucket", detailed_stats=False)