[plugin] Refactor lambda-build packaging into a pluggable ArchiveBackend (ZIP today, OCI-ready) (#681)

### Summary

Introduces a pluggable **archive backend** abstraction for
`lambda-build`, mirroring
the existing build-backend design (#679). Packaging the built binaries
into a
deployable artifact was hard-coded to ZIP inside `Builder.swift`; it is
now behind
an `ArchiveBackend` protocol with one implementation today (ZIP, the
existing code
moved verbatim) and a stubbed seam for OCI images in the future.

Internal refactor: the default behaviour is unchanged (ZIP), no public
Swift API
changes, and the output ZIP layout / path is identical.

### What changed

- **`ArchiveBackend` protocol** (`ArchiveBackends/ArchiveBackend.swift`)
— owns *what
kind of artifact* is produced from the built binaries. It's the
packaging
counterpart to `BuildBackend` (which owns *how the binaries are built*);
`Builder`
  selects and sequences the two.
- **`ZipArchiveBackend`** (`ArchiveBackends/ZipArchiveBackend.swift`) —
the existing
`Builder.package(...)` body, moved unchanged, with `zipToolPath`
injected via init.
- **`ArchiveFormat` enum** (`ArchiveFormat.swift`) — the parsed
`--archive-format`
value (`zip` | `oci`), mirroring `CrossCompileMethod`: `parse(...)`
(defaults to
  `zip`, case-insensitive), `isSupported` (`oci` → false), and a new
  `BuilderErrors.unsupportedArchiveFormat` case.
- **`--archive-format zip|oci` flag** — parsed into
`BuilderConfiguration`, with a
`makeArchiveBackend()` factory (following the same on-configuration
factory
convention as `makeCrossCompileBackend()`). `oci` is recognised but
throws a
"not yet supported" error. Help text and the verbose config dump
updated.
- **`Builder.build(...)`** now ends with
`configuration.makeArchiveBackend().archive(...)`
  instead of the inline `package(...)` method (which is removed).
- **Directory rename**: `Backends/` → `BuildBackends/`, so the two
families read as
  parallel siblings: `BuildBackends/` and `ArchiveBackends/`.

### Adding OCI later

Add `OCIArchiveBackend: ArchiveBackend` under `ArchiveBackends/`, then
flip the `oci`
case in `ArchiveFormat.isSupported` and `makeArchiveBackend()`. No other
changes.

### Testing

- New `ArchiveBackendTests.swift`: `ArchiveFormat.parse`
(default/case-insensitive/
oci-unsupported/unknown), `makeArchiveBackend()` selection (zip →
`ZipArchiveBackend`),
and `ZipArchiveBackend.archive` run against a temp build dir asserting
the `.zip` and
  relocated `bootstrap` are produced.
- All `AWSLambdaPluginHelperTests` pass (90 tests); `swift build` and
  `swift format lint --strict` clean.
- End-to-end: `--archive-format oci` fails fast with the stub error;
zip/default
  produce a byte-for-byte identical artifact to before.

Author: sebsto

Sources/AWSLambdaPluginHelper/lambda-build/ArchiveBackends/ArchiveBackend.swift

@@ -0,0 +1,46 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright SwiftAWSLambdaRuntime project authors
+// Copyright (c) Amazon.com, Inc. or its affiliates.
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+#if canImport(FoundationEssentials)
+import FoundationEssentials
+#else
+import Foundation
+#endif
+
+/// A strategy for packaging built Lambda executables into a deployable artifact.
+///
+/// An archive backend owns *what kind of artifact* is produced from the built binaries — today a
+/// ZIP package suitable for upload to AWS Lambda, and in the future other formats such as an OCI
+/// image. It is the packaging counterpart to ``BuildBackend`` (which owns *how the binaries are
+/// built*); the two are selected and sequenced by ``Builder``.
+@available(LambdaSwift 2.0, *)
+protocol ArchiveBackend {
+    /// A human-readable name used in log output (e.g. "zip").
+    var name: String { get }
+
+    /// Package the built product executables into deployable artifacts.
+    ///
+    /// - Parameters:
+    ///   - products: A map of product name to the built executable's URL on the host, as returned
+    ///     by a ``BuildBackend``.
+    ///   - outputDirectory: The directory where the artifacts should be written.
+    ///   - verboseLogging: When `true`, emit verbose output for debugging.
+    /// - Returns: A map of product name to the produced artifact's URL.
+    func archive(
+        products: [String: URL],
+        outputDirectory: URL,
+        verboseLogging: Bool
+    ) throws -> [String: URL]
+}

Sources/AWSLambdaPluginHelper/lambda-build/ArchiveBackends/ZipArchiveBackend.swift

@@ -0,0 +1,124 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright SwiftAWSLambdaRuntime project authors
+// Copyright (c) Amazon.com, Inc. or its affiliates.
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+#if canImport(FoundationEssentials)
+import FoundationEssentials
+#else
+import Foundation
+#endif
+
+/// Packages built executables into ZIP archives suitable for upload to AWS Lambda.
+///
+/// Each product is laid out as a `bootstrap` executable (the name the Lambda runtime expects)
+/// alongside any `*.resources` bundles, then zipped via the `zip` tool.
+@available(LambdaSwift 2.0, *)
+struct ZipArchiveBackend: ArchiveBackend {
+    let name = "zip"
+
+    /// The resolved path to the `zip` tool.
+    let zipToolPath: URL
+
+    // TODO: explore using ziplib or similar instead of shelling out
+    func archive(
+        products: [String: URL],
+        outputDirectory: URL,
+        verboseLogging: Bool
+    ) throws -> [String: URL] {
+
+        var archives = [String: URL]()
+        for (product, artifactPath) in products {
+            print("-------------------------------------------------------------------------")
+            print("archiving \"\(product)\"")
+            print("-------------------------------------------------------------------------")
+
+            // prep zipfile location
+            let workingDirectory = outputDirectory.appending(path: product)
+            let zipfilePath = workingDirectory.appending(path: "\(product).zip")
+            if FileManager.default.fileExists(atPath: workingDirectory.path()) {
+                try FileManager.default.removeItem(atPath: workingDirectory.path())
+            }
+            try FileManager.default.createDirectory(atPath: workingDirectory.path(), withIntermediateDirectories: true)
+
+            // rename artifact to "bootstrap"
+            let relocatedArtifactPath = workingDirectory.appending(path: "bootstrap")
+            try FileManager.default.copyItem(atPath: artifactPath.path(), toPath: relocatedArtifactPath.path())
+
+            var arguments: [String] = []
+            #if os(macOS) || os(Linux)
+            arguments = [
+                "--recurse-paths",
+                "--symlinks",
+                zipfilePath.lastPathComponent,
+                relocatedArtifactPath.lastPathComponent,
+            ]
+            #else
+            throw BuilderErrors.unsupportedPlatform("can't or don't know how to create a zip file on this platform")
+            #endif
+
+            // add resources
+            var artifactPathComponents = artifactPath.pathComponents
+            _ = artifactPathComponents.removeFirst()  // Get rid of beginning "/"
+            _ = artifactPathComponents.removeLast()  // Get rid of the name of the package
+            let artifactDirectory = "/\(artifactPathComponents.joined(separator: "/"))"
+            for fileInArtifactDirectory in try FileManager.default.contentsOfDirectory(atPath: artifactDirectory) {
+                guard let artifactURL = URL(string: "\(artifactDirectory)/\(fileInArtifactDirectory)") else {
+                    continue
+                }
+
+                guard artifactURL.pathExtension == "resources" else {
+                    continue  // Not resources, so don't copy
+                }
+                let resourcesDirectoryName = artifactURL.lastPathComponent
+                let relocatedResourcesDirectory = workingDirectory.appending(path: resourcesDirectoryName)
+                if FileManager.default.fileExists(atPath: artifactURL.path()) {
+                    do {
+                        arguments.append(resourcesDirectoryName)
+                        try FileManager.default.copyItem(
+                            atPath: artifactURL.path(),
+                            toPath: relocatedResourcesDirectory.path()
+                        )
+                    } catch let error as CocoaError {
+
+                        // On Linux, when the build has been done with Docker,
+                        // the source file are owned by root
+                        // this causes a permission error **after** the files have been copied
+                        // see https://github.com/awslabs/swift-aws-lambda-runtime/issues/449
+                        // see https://forums.swift.org/t/filemanager-copyitem-on-linux-fails-after-copying-the-files/77282
+
+                        // because this error happens after the files have been copied, we can ignore it
+                        // this code checks if the destination file exists
+                        // if they do, just ignore error, otherwise throw it up to the caller.
+                        if !(error.code == CocoaError.Code.fileWriteNoPermission
+                            && FileManager.default.fileExists(atPath: relocatedResourcesDirectory.path()))
+                        {
+                            throw error
+                        }  // else just ignore it
+                    }
+                }
+            }
+
+            // run the zip tool
+            try Utils.execute(
+                executable: self.zipToolPath,
+                arguments: arguments,
+                customWorkingDirectory: workingDirectory,
+                logLevel: verboseLogging ? .debug : .silent
+            )
+
+            archives[product] = zipfilePath
+        }
+        return archives
+    }
+}

Sources/AWSLambdaPluginHelper/lambda-build/ArchiveFormat.swift

@@ -0,0 +1,61 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright SwiftAWSLambdaRuntime project authors
+// Copyright (c) Amazon.com, Inc. or its affiliates.
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+#if canImport(FoundationEssentials)
+import FoundationEssentials
+#else
+import Foundation
+#endif
+
+/// The packaging format requested via `--archive-format`.
+///
+/// This enum is purely the parsed user choice. The packaging flow lives in the ``ArchiveBackend``
+/// types, and backend construction lives on ``BuilderConfiguration/makeArchiveBackend()``.
+@available(LambdaSwift 2.0, *)
+enum ArchiveFormat: String, CustomStringConvertible {
+    /// A ZIP package suitable for upload to AWS Lambda.
+    case zip
+    /// An OCI image. Not yet supported.
+    case oci
+
+    var isSupported: Bool {
+        switch self {
+        case .zip: return true
+        case .oci: return false
+        }
+    }
+
+    static func parse(_ value: String?) throws -> Self {
+        guard let value else {
+            return .zip
+        }
+
+        guard let format = ArchiveFormat(rawValue: value.lowercased()) else {
+            throw BuilderErrors.invalidArgument(
+                "invalid archive format '\(value)'. Use 'zip' or 'oci'."
+            )
+        }
+
+        guard format.isSupported else {
+            throw BuilderErrors.unsupportedArchiveFormat(format)
+        }
+
+        return format
+    }
+
+    var description: String {
+        self.rawValue
+    }
+}