Add container system df command for disk usage reporting (#902)

- Closes #884. 

## Type of Change
- [ ] Bug fix
- [x] New feature  
- [ ] Breaking change
- [ ] Documentation update

## Motivation and Context
This PR implements the `container system df` command to display disk
usage statistics for images, containers, and volumes, along with their
total count, active count, size, and reclaimable space for each resource
type.

Active resources are determined by container mount references and
running state, while reclaimable space is calculated from inactive or
stopped resources.

Example output:
```
~/container ❯ container system df
TYPE           TOTAL  ACTIVE  SIZE      RECLAIMABLE
Images         4      3       4.42 GB   516.5 MB (11%)
Containers     4      2       2.69 GB   1.51 GB (56%)
Local Volumes  3      2       208.5 MB  66.2 MB (32%)
```

I'll have some follow-on PRs that will add `-v/--verbose` flag for
detailed per-resource information, `--filter` flag for filtering output
by resource type, and a `--debug` flag for debug statistics like block
usage, clone counts etc.

## Testing
- [x] Tested locally
- [x] Added/updated tests
- [ ] Added/updated docs

Author: realrajaryan

Sources/ContainerClient/Core/ClientDiskUsage.swift

@@ -0,0 +1,40 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 Apple Inc. and the container project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+import ContainerXPC
+import ContainerizationError
+import Foundation
+
+/// Client API for disk usage operations
+public struct ClientDiskUsage {
+    static let serviceIdentifier = "com.apple.container.apiserver"
+
+    /// Get disk usage statistics for all resource types
+    public static func get() async throws -> DiskUsageStats {
+        let client = XPCClient(service: serviceIdentifier)
+        let message = XPCMessage(route: .systemDiskUsage)
+        let reply = try await client.send(message)
+
+        guard let responseData = reply.dataNoCopy(key: .diskUsageStats) else {
+            throw ContainerizationError(
+                .internalError,
+                message: "Invalid response from server: missing disk usage data"
+            )
+        }
+
+        return try JSONDecoder().decode(DiskUsageStats.self, from: responseData)
+    }
+}

Sources/ContainerClient/Core/ClientImage.swift

@@ -289,10 +289,30 @@ extension ClientImage {
         let request = newRequest(.imagePrune)
         let response = try await client.send(request)
         let digests = try response.digests()
-        let size = response.uint64(key: .size)
+        let size = response.uint64(key: .imageSize)
         return (digests, size)
     }
 
+    /// Calculate disk usage for images
+    /// - Parameter activeReferences: Set of image references currently in use by containers
+    /// - Returns: Tuple of (total count, active count, total size, reclaimable size)
+    public static func calculateDiskUsage(activeReferences: Set<String>) async throws -> (totalCount: Int, activeCount: Int, totalSize: UInt64, reclaimableSize: UInt64) {
+        let client = newXPCClient()
+        let request = newRequest(.imageDiskUsage)
+
+        // Encode active references
+        let activeRefsData = try JSONEncoder().encode(activeReferences)
+        request.set(key: .activeImageReferences, value: activeRefsData)
+
+        let response = try await client.send(request)
+        let total = Int(response.int64(key: .totalCount))
+        let active = Int(response.int64(key: .activeCount))
+        let size = response.uint64(key: .imageSize)
+        let reclaimable = response.uint64(key: .reclaimableSize)
+
+        return (totalCount: total, activeCount: active, totalSize: size, reclaimableSize: reclaimable)
+    }
+
     public static func fetch(reference: String, platform: Platform? = nil, scheme: RequestScheme = .auto, progressUpdate: ProgressUpdateHandler? = nil) async throws -> ClientImage
     {
         do {

Sources/ContainerClient/Core/ClientVolume.swift

@@ -91,7 +91,7 @@ public struct ClientVolume {
         }
 
         let volumeNames = try JSONDecoder().decode([String].self, from: responseData)
-        let size = reply.uint64(key: .size)
+        let size = reply.uint64(key: .volumeSize)
         return (volumeNames, size)
     }
 

Sources/ContainerClient/Core/DiskUsage.swift

@@ -0,0 +1,57 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 Apple Inc. and the container project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+import Foundation
+
+/// Disk usage statistics for all resource types
+public struct DiskUsageStats: Sendable, Codable {
+    /// Disk usage for images
+    public var images: ResourceUsage
+
+    /// Disk usage for containers
+    public var containers: ResourceUsage
+
+    /// Disk usage for volumes
+    public var volumes: ResourceUsage
+
+    public init(images: ResourceUsage, containers: ResourceUsage, volumes: ResourceUsage) {
+        self.images = images
+        self.containers = containers
+        self.volumes = volumes
+    }
+}
+
+/// Disk usage statistics for a specific resource type
+public struct ResourceUsage: Sendable, Codable {
+    /// Total number of resources
+    public var total: Int
+
+    /// Number of active/running resources
+    public var active: Int
+
+    /// Total size in bytes
+    public var sizeInBytes: UInt64
+
+    /// Reclaimable size in bytes (from unused/inactive resources)
+    public var reclaimable: UInt64
+
+    public init(total: Int, active: Int, sizeInBytes: UInt64, reclaimable: UInt64) {
+        self.total = total
+        self.active = active
+        self.sizeInBytes = sizeInBytes
+        self.reclaimable = reclaimable
+    }
+}

Sources/ContainerClient/Core/XPC+.swift

@@ -118,6 +118,10 @@ public enum XPCKeys: String {
 
     /// Container statistics
     case statistics
+    case volumeSize
+
+    /// Disk usage
+    case diskUsageStats
 }
 
 public enum XPCRoute: String {
@@ -153,6 +157,8 @@ public enum XPCRoute: String {
     case volumeInspect
     case volumePrune
 
+    case systemDiskUsage
+
     case ping
 
     case installKernel

Sources/ContainerCommands/System/SystemCommand.swift

@@ -23,6 +23,7 @@ extension Application {
             commandName: "system",
             abstract: "Manage system components",
             subcommands: [
+                SystemDF.self,
                 SystemDNS.self,
                 SystemKernel.self,
                 SystemLogs.self,

Sources/ContainerCommands/System/SystemDF.swift

@@ -0,0 +1,115 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 Apple Inc. and the container project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+import ArgumentParser
+import ContainerClient
+import ContainerizationError
+import Foundation
+
+extension Application {
+    public struct SystemDF: AsyncParsableCommand {
+        public static let configuration = CommandConfiguration(
+            commandName: "df",
+            abstract: "Show disk usage for images, containers, and volumes"
+        )
+
+        @Option(name: .long, help: "Format of the output")
+        var format: ListFormat = .table
+
+        @OptionGroup
+        var global: Flags.Global
+
+        public init() {}
+
+        public func run() async throws {
+            let stats = try await ClientDiskUsage.get()
+
+            if format == .json {
+                let encoder = JSONEncoder()
+                encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+                let data = try encoder.encode(stats)
+                guard let jsonString = String(data: data, encoding: .utf8) else {
+                    throw ContainerizationError(
+                        .internalError,
+                        message: "Failed to encode JSON output"
+                    )
+                }
+                print(jsonString)
+                return
+            }
+
+            printTable(stats: stats)
+        }
+
+        private func printTable(stats: DiskUsageStats) {
+            var rows: [[String]] = []
+
+            // Header row
+            rows.append(["TYPE", "TOTAL", "ACTIVE", "SIZE", "RECLAIMABLE"])
+
+            // Images row
+            rows.append([
+                "Images",
+                "\(stats.images.total)",
+                "\(stats.images.active)",
+                formatSize(stats.images.sizeInBytes),
+                formatReclaimable(stats.images.reclaimable, total: stats.images.sizeInBytes),
+            ])
+
+            // Containers row
+            rows.append([
+                "Containers",
+                "\(stats.containers.total)",
+                "\(stats.containers.active)",
+                formatSize(stats.containers.sizeInBytes),
+                formatReclaimable(stats.containers.reclaimable, total: stats.containers.sizeInBytes),
+            ])
+
+            // Volumes row
+            rows.append([
+                "Local Volumes",
+                "\(stats.volumes.total)",
+                "\(stats.volumes.active)",
+                formatSize(stats.volumes.sizeInBytes),
+                formatReclaimable(stats.volumes.reclaimable, total: stats.volumes.sizeInBytes),
+            ])
+
+            let tableFormatter = TableOutput(rows: rows)
+            print(tableFormatter.format())
+        }
+
+        private func formatSize(_ bytes: UInt64) -> String {
+            if bytes == 0 {
+                return "0 B"
+            }
+            let formatter = ByteCountFormatter()
+            formatter.countStyle = .file
+            return formatter.string(fromByteCount: Int64(bytes))
+        }
+
+        private func formatReclaimable(_ reclaimable: UInt64, total: UInt64) -> String {
+            let sizeStr = formatSize(reclaimable)
+
+            if total == 0 {
+                return "\(sizeStr) (0%)"
+            }
+
+            // Cap at 100% in case reclaimable > total (shouldn't happen but be defensive)
+            let percentage = min(100, Int(round(Double(reclaimable) / Double(total) * 100.0)))
+            return "\(sizeStr) (\(percentage)%)"
+        }
+    }
+}

Sources/Helpers/APIServer/APIServer+Start.swift

@@ -67,7 +67,13 @@ extension APIServer {
                 )
                 initializeHealthCheckService(log: log, routes: &routes)
                 try initializeKernelService(log: log, routes: &routes)
-                try initializeVolumeService(containersService: containersService, log: log, routes: &routes)
+                let volumesService = try initializeVolumeService(containersService: containersService, log: log, routes: &routes)
+                try initializeDiskUsageService(
+                    containersService: containersService,
+                    volumesService: volumesService,
+                    log: log,
+                    routes: &routes
+                )
 
                 let server = XPCServer(
                     identifier: "com.apple.container.apiserver",
@@ -254,7 +260,7 @@ extension APIServer {
             containersService: ContainersService,
             log: Logger,
             routes: inout [XPCRoute: XPCServer.RouteHandler]
-        ) throws {
+        ) throws -> VolumesService {
             log.info("initializing volume service")
 
             let resourceRoot = appRoot.appendingPathComponent("volumes")
@@ -266,6 +272,26 @@ extension APIServer {
             routes[XPCRoute.volumeList] = harness.list
             routes[XPCRoute.volumeInspect] = harness.inspect
             routes[XPCRoute.volumePrune] = harness.prune
+
+            return service
+        }
+
+        private func initializeDiskUsageService(
+            containersService: ContainersService,
+            volumesService: VolumesService,
+            log: Logger,
+            routes: inout [XPCRoute: XPCServer.RouteHandler]
+        ) throws {
+            log.info("initializing disk usage service")
+
+            let service = DiskUsageService(
+                containersService: containersService,
+                volumesService: volumesService,
+                log: log
+            )
+            let harness = DiskUsageHarness(service: service, log: log)
+
+            routes[XPCRoute.systemDiskUsage] = harness.get
         }
     }
 }

Sources/Helpers/Images/ImagesHelper.swift

@@ -99,6 +99,7 @@ extension ImagesHelper {
             routes[ImagesServiceXPCRoute.imageLoad.rawValue] = harness.load
             routes[ImagesServiceXPCRoute.imageUnpack.rawValue] = harness.unpack
             routes[ImagesServiceXPCRoute.imagePrune.rawValue] = harness.prune
+            routes[ImagesServiceXPCRoute.imageDiskUsage.rawValue] = harness.calculateDiskUsage
             routes[ImagesServiceXPCRoute.snapshotDelete.rawValue] = harness.deleteSnapshot
             routes[ImagesServiceXPCRoute.snapshotGet.rawValue] = harness.getSnapshot
         }