Cleans up build subcommand options. (apple#658)

jglogan · web-flow · commit 1f94a8340a88 · 2025-09-22T12:48:45.000-07:00
- Part of apple#515. - Order options alphabetically. - Use `container ls` options for `builder status`. ## Type of Change - [ ] Bug fix - [ ] New feature - [x] Breaking change - Change options and output of `builder status`. - [x] Documentation update ## Motivation and Context See apple#515. ## Testing - [x] Tested locally - [ ] Added/updated tests - [x] Added/updated docs
diff --git a/Sources/ContainerCommands/Builder/BuilderDelete.swift b/Sources/ContainerCommands/Builder/BuilderDelete.swift
@@ -21,22 +21,22 @@ import Foundation
 
 extension Application {
     public struct BuilderDelete: AsyncParsableCommand {
-        public init() {}
-
         public static var configuration: CommandConfiguration {
             var config = CommandConfiguration()
             config.commandName = "delete"
             config.aliases = ["rm"]
-            config._superCommandName = "builder"
-            config.abstract = "Delete builder"
-            config.usage = "\n\t builder delete [command options]"
-            config.helpNames = NameSpecification(arrayLiteral: .customShort("h"), .customLong("help"))
+            config.abstract = "Delete the builder container"
             return config
         }
 
-        @Flag(name: .shortAndLong, help: "Force delete builder even if it is running")
+        @Flag(name: .shortAndLong, help: "Delete the builder even if it is running")
         var force = false
 
+        @OptionGroup
+        var global: Flags.Global
+
+        public init() {}
+
         public func run() async throws {
             do {
                 let container = try await ClientContainer.get(id: "buildkit")
diff --git a/Sources/ContainerCommands/Builder/BuilderStart.swift b/Sources/ContainerCommands/Builder/BuilderStart.swift
@@ -28,28 +28,27 @@ import TerminalProgress
 
 extension Application {
     public struct BuilderStart: AsyncParsableCommand {
-        public init() {}
-
         public static var configuration: CommandConfiguration {
             var config = CommandConfiguration()
             config.commandName = "start"
-            config._superCommandName = "builder"
-            config.abstract = "Start builder"
-            config.usage = "\nbuilder start [command options]"
-            config.helpNames = NameSpecification(arrayLiteral: .customShort("h"), .customLong("help"))
+            config.abstract = "Start the builder container"
             return config
         }
 
-        @Option(name: [.customLong("cpus"), .customShort("c")], help: "Number of CPUs to allocate to the container")
+        @Option(name: .shortAndLong, help: "Number of CPUs to allocate to the builder container")
         var cpus: Int64 = 2
 
         @Option(
-            name: [.customLong("memory"), .customShort("m")],
-            help:
-                "Amount of memory in bytes, kilobytes (K), megabytes (M), or gigabytes (G) for the container, with MB granularity (for example, 1024K will result in 1MB being allocated for the container)"
+            name: .shortAndLong,
+            help: "Amount of builder container memory (1MiByte granularity), with optional K, M, G, T, or P suffix"
         )
         var memory: String = "2048MB"
 
+        @OptionGroup
+        var global: Flags.Global
+
+        public init() {}
+
         public func run() async throws {
             let progressConfig = try ProgressConfig(
                 showTasks: true,
diff --git a/Sources/ContainerCommands/Builder/BuilderStatus.swift b/Sources/ContainerCommands/Builder/BuilderStatus.swift
@@ -17,57 +17,86 @@
 import ArgumentParser
 import ContainerClient
 import ContainerizationError
+import ContainerizationExtras
 import Foundation
 
 extension Application {
     public struct BuilderStatus: AsyncParsableCommand {
-        public init() {}
-
         public static var configuration: CommandConfiguration {
             var config = CommandConfiguration()
             config.commandName = "status"
-            config._superCommandName = "builder"
-            config.abstract = "Print builder status"
-            config.usage = "\n\t builder status [command options]"
-            config.helpNames = NameSpecification(arrayLiteral: .customShort("h"), .customLong("help"))
+            config.abstract = "Display the builder container status"
             return config
         }
 
-        @Flag(name: .long, help: ArgumentHelp("Display detailed status in json format"))
-        var json: Bool = false
+        @Option(name: .long, help: "Format of the output")
+        var format: ListFormat = .table
 
-        public func run() async throws {
-            do {
-                let container = try await ClientContainer.get(id: "buildkit")
-                if json {
-                    let encoder = JSONEncoder()
-                    encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-                    let jsonData = try encoder.encode(container)
+        @Flag(name: .shortAndLong, help: "Only output the container ID")
+        var quiet = false
 
-                    guard let jsonString = String(data: jsonData, encoding: .utf8) else {
-                        throw ContainerizationError(.internalError, message: "failed to encode BuildKit container as json")
-                    }
-                    print(jsonString)
-                    return
-                }
+        @OptionGroup
+        var global: Flags.Global
 
-                let image = container.configuration.image.reference
-                let resources = container.configuration.resources
-                let cpus = resources.cpus
-                let memory = resources.memoryInBytes / (1024 * 1024)  // bytes to MB
-                let addr = ""
+        public init() {}
 
-                print("ID       IMAGE                           STATE   ADDR         CPUS MEMORY")
-                print("\(container.id) \(image) \(container.status.rawValue.uppercased()) \(addr) \(cpus)    \(memory) MB")
+        public func run() async throws {
+            do {
+                let container = try await ClientContainer.get(id: "buildkit")
+                try printContainers(containers: [container], format: format)
             } catch {
                 if error is ContainerizationError {
-                    if (error as? ContainerizationError)?.code == .notFound {
+                    if (error as? ContainerizationError)?.code == .notFound && !quiet {
                         print("builder is not running")
                         return
                     }
                 }
                 throw error
             }
         }
+
+        private func createHeader() -> [[String]] {
+            [["ID", "IMAGE", "STATE", "ADDR", "CPUS", "MEMORY"]]
+        }
+
+        private func printContainers(containers: [ClientContainer], format: ListFormat) throws {
+            if format == .json {
+                let printables = containers.map {
+                    PrintableContainer($0)
+                }
+                let data = try JSONEncoder().encode(printables)
+                print(String(data: data, encoding: .utf8)!)
+
+                return
+            }
+
+            if self.quiet {
+                containers
+                    .filter { $0.status == .running }
+                    .forEach { print($0.id) }
+                return
+            }
+
+            var rows = createHeader()
+            for container in containers {
+                rows.append(container.asRow)
+            }
+
+            let formatter = TableOutput(rows: rows)
+            print(formatter.format())
+        }
+    }
+}
+
+extension ClientContainer {
+    fileprivate var asRow: [String] {
+        [
+            self.id,
+            self.configuration.image.reference,
+            self.status.rawValue,
+            self.networks.compactMap { try? CIDRAddress($0.address).address.description }.joined(separator: ","),
+            "\(self.configuration.resources.cpus)",
+            "\(self.configuration.resources.memoryInBytes / (1024 * 1024)) MB",
+        ]
     }
 }
diff --git a/Sources/ContainerCommands/Builder/BuilderStop.swift b/Sources/ContainerCommands/Builder/BuilderStop.swift
@@ -21,18 +21,18 @@ import Foundation
 
 extension Application {
     public struct BuilderStop: AsyncParsableCommand {
-        public init() {}
-
         public static var configuration: CommandConfiguration {
             var config = CommandConfiguration()
             config.commandName = "stop"
-            config._superCommandName = "builder"
-            config.abstract = "Stop builder"
-            config.usage = "\n\t builder stop"
-            config.helpNames = NameSpecification(arrayLiteral: .customShort("h"), .customLong("help"))
+            config.abstract = "Stop the builder container"
             return config
         }
 
+        @OptionGroup
+        var global: Flags.Global
+
+        public init() {}
+
         public func run() async throws {
             do {
                 let container = try await ClientContainer.get(id: "buildkit")
diff --git a/Sources/ContainerCommands/Container/ContainerDelete.swift b/Sources/ContainerCommands/Container/ContainerDelete.swift
@@ -28,7 +28,7 @@ extension Application {
             abstract: "Delete one or more containers",
             aliases: ["rm"])
 
-        @Flag(name: .shortAndLong, help: "Force the removal of one or more running containers")
+        @Flag(name: .shortAndLong, help: "Delete containers even if they are running")
         var force = false
 
         @Flag(name: .shortAndLong, help: "Remove all containers")
diff --git a/Sources/ContainerCommands/Container/ContainerList.swift b/Sources/ContainerCommands/Container/ContainerList.swift
@@ -23,32 +23,32 @@ import SwiftProtobuf
 
 extension Application {
     public struct ContainerList: AsyncParsableCommand {
-        public init() {}
-
         public static let configuration = CommandConfiguration(
             commandName: "list",
             abstract: "List containers",
             aliases: ["ls"])
 
-        @Flag(name: .shortAndLong, help: "Show stopped containers as well")
+        @Flag(name: .shortAndLong, help: "Include containers that are not running")
         var all = false
 
-        @Flag(name: .shortAndLong, help: "Only output the container ID")
-        var quiet = false
-
         @Option(name: .long, help: "Format of the output")
         var format: ListFormat = .table
 
+        @Flag(name: .shortAndLong, help: "Only output the container ID")
+        var quiet = false
+
         @OptionGroup
         var global: Flags.Global
 
+        public init() {}
+
         public func run() async throws {
             let containers = try await ClientContainer.list()
             try printContainers(containers: containers, format: format)
         }
 
         private func createHeader() -> [[String]] {
-            [["ID", "IMAGE", "OS", "ARCH", "STATE", "ADDR"]]
+            [["ID", "IMAGE", "OS", "ARCH", "STATE", "ADDR", "CPUS", "MEMORY"]]
         }
 
         private func printContainers(containers: [ClientContainer], format: ListFormat) throws {
@@ -87,14 +87,16 @@ extension Application {
 }
 
 extension ClientContainer {
-    var asRow: [String] {
+    fileprivate var asRow: [String] {
         [
             self.id,
             self.configuration.image.reference,
             self.configuration.platform.os,
             self.configuration.platform.architecture,
             self.status.rawValue,
             self.networks.compactMap { try? CIDRAddress($0.address).address.description }.joined(separator: ","),
+            "\(self.configuration.resources.cpus)",
+            "\(self.configuration.resources.memoryInBytes / (1024 * 1024)) MB",
         ]
     }
 }
