Add the declaration of the command capability for plugins (this is the first part of implementing command plugins, just laying the foundation)

- add the new enum case to PackageDescription
- add serialization of it in PackageDescriptionSerializer
- deserialize it in the ManifestJSONLoader
- add manifest source generation for it
- add ability to describe packages with command plugins
- adjust other parts of the code accordingly
- add a unit test to check loading a manifest with a command capability

Author: abertelrud

Sources/Commands/Describe.swift

@@ -144,13 +144,34 @@ struct DescribedPackage: Encodable {
     /// Represents a plugin capability for the sole purpose of generating a description.
     struct DescribedPluginCapability: Encodable {
         let type: String
+        let verb: String?
+        let description: String?
+        let permissions: [PluginPermission]?
 
         init(from capability: PluginCapability, in package: Package) {
             switch capability {
             case .buildTool:
                 self.type = "buildTool"
+                self.verb = nil
+                self.description = nil
+                self.permissions = nil
+            case .command(let verb, let description, let permissions):
+                self.type = "command"
+                self.verb = verb
+                self.description = description
+                self.permissions = permissions.map{
+                    switch $0 {
+                    case .packageWritability(let reason):
+                        return PluginPermission(type: "packageWritability", reason: reason)
+                    }
+                }
             }
         }
+        
+        struct PluginPermission: Encodable {
+            let type: String
+            let reason: String
+        }
     }
 
     /// Represents a target for the sole purpose of generating a description.

Sources/PackageDescription/PackageDescriptionSerialization.swift

@@ -224,18 +224,42 @@ extension SystemPackageProvider: Encodable {
 
 extension Target.PluginCapability: Encodable {
     private enum CodingKeys: CodingKey {
-        case type
+        case type, verb, description, permissions
     }
 
     private enum Capability: String, Encodable {
-        case buildTool
+        case buildTool, command
     }
 
     public func encode(to encoder: Encoder) throws {
         var container = encoder.container(keyedBy: CodingKeys.self)
         switch self {
         case ._buildTool:
             try container.encode(Capability.buildTool, forKey: .type)
+        case ._command(let verb, let description, let permissions):
+            try container.encode(Capability.command, forKey: .type)
+            try container.encode(verb, forKey: .verb)
+            try container.encode(description, forKey: .description)
+            try container.encode(permissions, forKey: .permissions)
+        }
+    }
+}
+
+extension PluginPermission: Encodable {
+    private enum CodingKeys: CodingKey {
+        case type, reason
+    }
+
+    private enum PermissionType: String, Encodable {
+        case packageWritability
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        switch self {
+        case .packageWritability(let reason):
+            try container.encode(PermissionType.packageWritability, forKey: .type)
+            try container.encode(reason, forKey: .reason)
         }
     }
 }

Sources/PackageDescription/Target.swift

@@ -127,10 +127,11 @@ public final class Target {
     private var _pluginCapability: PluginCapability?
 
     /// The different types of capability that a plugin can provide. In this
-    /// version of SwiftPM, only build tool plugins are supported; this enum
-    /// will be extended as new plugin capabilities are added.
+    /// version of SwiftPM, only build tool and command plugins are supported;
+    /// this enum will be extended as new plugin capabilities are added.
     public enum PluginCapability {
         case _buildTool
+        case _command(verb: String, description: String, permissions: [PluginPermission])
     }
 
     /// The target's C build settings.
@@ -1010,6 +1011,38 @@ extension Target.PluginCapability {
     public static func buildTool() -> Target.PluginCapability {
         return ._buildTool
     }
+
+    /// Specifies that the plugin provides a user command capability. It will
+    /// be available to invoke manually on one or more targets in a package.
+    /// The package can specify the verb that is used to invoke the command.
+    @available(_PackageDescription, introduced: 5.6)
+    /// Plugins that specify a `command` capability define commands that can be run
+    /// using the SwiftPM CLI (`swift package <verb>`), or in an IDE that supports
+    /// Swift Packages.
+    public static func command(
+        /// The `swift package` CLI verb through which the plugin can be invoked.
+        verb: String,
+        
+        /// A description of the functionality of the custom command, suitable for
+        /// showing in help text output.
+        description: String,
+        
+        /// Any permissions needed by the command plugin. This affects what the
+        /// sandbox in which the plugin is run allows. Some permissions may require
+        /// approval by the user.
+        permissions: [PluginPermission] = []
+    ) -> Target.PluginCapability {
+        return ._command(verb: verb, description: description, permissions: permissions)
+    }
+}
+
+public enum PluginPermission {
+    /// The custom command plugin requests permission to modify the files inside the
+    /// package directory. The `reason` string is shown to the user at the time of
+    /// request for approval, explaining why the plugin is requesting this access.
+    case packageWritability(reason: String)
+
+    /// Any future enum cases should use @available()
 }
 
 extension Target.PluginUsage {

Sources/PackageLoading/ManifestJSONParser.swift

@@ -596,6 +596,24 @@ extension TargetDescription.PluginCapability {
         switch type {
         case "buildTool":
             self = .buildTool
+        case "command":
+            let verb = try json.get(String.self, forKey: "verb")
+            let description = try json.get(String.self, forKey: "description")
+            let permissions = try json.getArray("permissions").map(TargetDescription.PluginPermission.init(v4:))
+            self = .command(verb: verb, description: description, permissions: permissions)
+        default:
+            throw InternalError("invalid type \(type)")
+        }
+    }
+}
+
+extension TargetDescription.PluginPermission {
+    fileprivate init(v4 json: JSON) throws {
+        let type = try json.get(String.self, forKey: "type")
+        switch type {
+        case "packageWritability":
+            let reason = try json.get(String.self, forKey: "reason")
+            self = .packageWritability(reason: reason)
         default:
             throw InternalError("invalid type \(type)")
         }
@@ -610,7 +628,6 @@ extension TargetDescription.PluginUsage {
             let name = try json.get(String.self, forKey: "name")
             let package = try? json.get(String.self, forKey: "package")
             self = .plugin(name: name, package: package)
-
         default:
             throw InternalError("invalid type \(type)")
         }

Sources/PackageLoading/PackageBuilder.swift

@@ -829,24 +829,18 @@ public final class PackageBuilder {
 
         // Deal with package plugin targets.
         if potentialModule.type == .plugin {
+            // Check that the target has a declared capability; we should not have come this far if not.
             guard let declaredCapability = manifestTarget.pluginCapability else {
                 throw ModuleError.pluginCapabilityNotDeclared(target: manifestTarget.name)
             }
 
-            // Translate the capability from the target description form coming in from the manifest
-            // to the package model form.
-            let capability: PluginCapability
-            switch declaredCapability {
-            case .buildTool:
-                capability = .buildTool
-            }
-
-            // Crate and return an PluginTarget configured with the information from the manifest.
+            // Create and return an PluginTarget configured with the information from the manifest.
             return PluginTarget(
                 name: potentialModule.name,
                 platforms: self.platforms(),  // FIXME: this should be host platform
                 sources: sources,
-                pluginCapability: capability,
+                apiVersion: self.manifest.toolsVersion,
+                pluginCapability: PluginCapability(from: declaredCapability),
                 dependencies: dependencies)
         }
 

Sources/PackageModel/Manifest/TargetDescription.swift

@@ -110,6 +110,11 @@ public struct TargetDescription: Equatable, Codable {
     /// Represents the declared capability of a package plugin.
     public enum PluginCapability: Equatable {
         case buildTool
+        case command(verb: String, description: String, permissions: [PluginPermission])
+    }
+    
+    public enum PluginPermission: Equatable, Codable {
+        case packageWritability(reason: String)
     }
 
     /// The target-specific build settings declared in this target.
@@ -259,14 +264,19 @@ extension TargetDescription.Dependency: ExpressibleByStringLiteral {
 
 extension TargetDescription.PluginCapability: Codable {
     private enum CodingKeys: CodingKey {
-        case buildTool
+        case buildTool, command
     }
 
     public func encode(to encoder: Encoder) throws {
         var container = encoder.container(keyedBy: CodingKeys.self)
         switch self {
         case .buildTool:
             try container.encodeNil(forKey: .buildTool)
+        case .command(let a1, let a2, let a3):
+            var unkeyedContainer = container.nestedUnkeyedContainer(forKey: .command)
+            try unkeyedContainer.encode(a1)
+            try unkeyedContainer.encode(a2)
+            try unkeyedContainer.encode(a3)
         }
     }
 
@@ -278,6 +288,12 @@ extension TargetDescription.PluginCapability: Codable {
         switch key {
         case .buildTool:
             self = .buildTool
+        case .command:
+            var unkeyedValues = try values.nestedUnkeyedContainer(forKey: key)
+            let a1 = try unkeyedValues.decode(String.self)
+            let a2 = try unkeyedValues.decode(String.self)
+            let a3 = try unkeyedValues.decode([TargetDescription.PluginPermission].self)
+            self = .command(verb: a1, description: a2, permissions: a3)
         }
     }
 }

Sources/PackageModel/ManifestSourceGeneration.swift

@@ -415,6 +415,23 @@ fileprivate extension SourceCodeFragment {
         switch capability {
         case .buildTool:
             self.init(enum: "buildTool", subnodes: [])
+        case .command(let verb, let description, let permissions):
+            var params: [SourceCodeFragment] = []
+            params.append(SourceCodeFragment(key: "verb", string: verb))
+            params.append(SourceCodeFragment(key: "description", string: description))
+            if !permissions.isEmpty {
+                params.append(SourceCodeFragment(key: "permissions", subnodes: permissions.map{ .init(from: $0) }))
+            }
+            self.init(enum: "command", subnodes: params)
+        }
+    }
+
+    /// Instantiates a SourceCodeFragment to represent a single plugin permission.
+    init(from permission: TargetDescription.PluginPermission) {
+        switch permission {
+        case .packageWritability(let reason):
+            let param = SourceCodeFragment(key: "reason", string: reason)
+            self.init(enum: "packageWritability", subnodes: [param])
         }
     }
 

Sources/PackageModel/Target.swift

@@ -614,16 +614,22 @@ public final class BinaryTarget: Target {
 
 public final class PluginTarget: Target {
 
+    /// Declared capability of the plugin.
     public let capability: PluginCapability
+    
+    /// API version to use for PackagePlugin API availability.
+    public let apiVersion: ToolsVersion
 
     public init(
         name: String,
         platforms: [SupportedPlatform] = [],
         sources: Sources,
+        apiVersion: ToolsVersion,
         pluginCapability: PluginCapability,
         dependencies: [Target.Dependency] = []
     ) {
         self.capability = pluginCapability
+        self.apiVersion = apiVersion
         super.init(
             name: name,
             defaultLocalization: nil,
@@ -638,33 +644,42 @@ public final class PluginTarget: Target {
 
     private enum CodingKeys: String, CodingKey {
         case capability
+        case apiVersion
     }
 
     public override func encode(to encoder: Encoder) throws {
         var container = encoder.container(keyedBy: CodingKeys.self)
         try container.encode(self.capability, forKey: .capability)
+        try container.encode(self.apiVersion, forKey: .apiVersion)
         try super.encode(to: encoder)
     }
 
     required public init(from decoder: Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
         self.capability = try container.decode(PluginCapability.self, forKey: .capability)
+        self.apiVersion = try container.decode(ToolsVersion.self, forKey: .apiVersion)
         try super.init(from: decoder)
     }
 }
 
-public enum PluginCapability: Equatable, Codable {
+public enum PluginCapability: Hashable, Codable {
     case buildTool
+    case command(verb: String, description: String, permissions: [PluginPermission])
 
     private enum CodingKeys: String, CodingKey {
-        case buildTool
+        case buildTool, command
     }
 
     public func encode(to encoder: Encoder) throws {
         var container = encoder.container(keyedBy: CodingKeys.self)
         switch self {
         case .buildTool:
             try container.encodeNil(forKey: .buildTool)
+        case .command(let a1, let a2, let a3):
+            var unkeyedContainer = container.nestedUnkeyedContainer(forKey: .command)
+            try unkeyedContainer.encode(a1)
+            try unkeyedContainer.encode(a2)
+            try unkeyedContainer.encode(a3)
         }
     }
 
@@ -676,6 +691,32 @@ public enum PluginCapability: Equatable, Codable {
         switch key {
         case .buildTool:
             self = .buildTool
+        case .command:
+            var unkeyedValues = try values.nestedUnkeyedContainer(forKey: key)
+            let a1 = try unkeyedValues.decode(String.self)
+            let a2 = try unkeyedValues.decode(String.self)
+            let a3 = try unkeyedValues.decode([PluginPermission].self)
+            self = .command(verb: a1, description: a2, permissions: a3)
+        }
+    }
+
+    public init(from desc: TargetDescription.PluginCapability) {
+        switch desc {
+        case .buildTool:
+            self = .buildTool
+        case .command(let verb, let description, let permissions):
+            self = .command(verb: verb, description: description, permissions: permissions.map{ .init(from: $0) })
+        }
+    }
+}
+
+public enum PluginPermission: Hashable, Codable {
+    case packageWritability(reason: String)
+
+    public init(from desc: TargetDescription.PluginPermission) {
+        switch desc {
+        case .packageWritability(let reason):
+            self = .packageWritability(reason: reason)
         }
     }
 }

Tests/PackageLoadingTests/PD_5_6_LoadingTests.swift

@@ -94,6 +94,32 @@ class PackageDescription5_6LoadingTests: PackageDescriptionLoadingTests {
         XCTAssertEqual(manifest.targets[0].pluginCapability, .buildTool)
     }
 
+    func testCommandPluginTarget() throws {
+        let content = """
+            import PackageDescription
+            let package = Package(
+               name: "Foo",
+               targets: [
+                   .plugin(
+                       name: "Foo",
+                       capability: .command(
+                           verb: "mycmd",
+                           description: "helpful description of mycmd",
+                           permissions: [ .packageWritability(reason: "YOLO") ]
+                       )
+                   )
+               ]
+            )
+            """
+
+        let observability = ObservabilitySystem.makeForTesting()
+        let manifest = try loadManifest(content, observabilityScope: observability.topScope)
+        XCTAssertNoDiagnostics(observability.diagnostics)
+
+        XCTAssertEqual(manifest.targets[0].type, .plugin)
+        XCTAssertEqual(manifest.targets[0].pluginCapability, .command(verb: "mycmd", description: "helpful description of mycmd", permissions: [.packageWritability(reason: "YOLO")]))
+    }
+
     func testPluginTargetCustomization() throws {
         let content = """
             import PackageDescription