Add app metadata to end of main execs for apps to use at runtime

The format I've settled on should be both forwards compatible and easy
to make backwards compatible extensions to. For now it's just some magic
bytes and a sized JSON string containing appIdentifier and appVersion
fields. The goal is for metadata parsers to always be able to at least
partially parse metadata produced by a newer Swift Bundler version than
they were designed for (the forwards compatibility I mentioned earlier).

Author: stackotter

Diff for: Sources/schema-gen/SchemaGenerator.swift

@@ -2,7 +2,7 @@ import Foundation
 import SwiftParser
 import SwiftSyntax
 
-extension FileHandle: TextOutputStream {
+extension FileHandle: Swift.TextOutputStream {
   public func write(_ string: String) {
     let data = Data(string.utf8)
     self.write(data)

Diff for: Sources/swift-bundler/Bundler/MetadataInserter.swift

@@ -0,0 +1,96 @@
+import Foundation
+
+/// Inserts metadata into executable files.
+///
+/// Swift Bundler inserts metadata at the end of your main executable file
+/// after compilation. The format is intended to be simple and portable to
+/// ensure that even if someone isn't using the Swift Bundler runtime they
+/// can easily parse the metadata at runtime. If the metadata format ever
+/// gets extended, it will be extended in such a way that current metadata
+/// remains valid, and future metadata is backwards compatible.
+enum MetadataInserter {
+  /// If an executable ends with this string, it probably contains Swift
+  /// Bundler metadata.
+  static let magicBytes: [UInt8] = Array("SBUNMETA".utf8)
+
+  /// Metadata appended to the end of executable files built with Swift
+  /// Bundler.
+  struct Metadata: Codable {
+    /// The app's identifier.
+    var appIdentifier: String
+    /// The app's version.
+    var appVersion: String
+  }
+
+  /// Generates an app's metadata from its configuration.
+  static func metadata(for configuration: AppConfiguration) -> Metadata {
+    Metadata(
+      appIdentifier: configuration.identifier,
+      appVersion: configuration.version
+    )
+  }
+
+  /// Inserts metadata at the end of the given executable file.
+  static func insert(
+    _ metadata: Metadata,
+    into executableFile: URL
+  ) -> Result<(), MetadataInserterError> {
+    Data.read(from: executableFile)
+      .mapError { error in
+        .failedToReadExecutableFile(executableFile, error)
+      }
+      .andThen { data in
+        JSONEncoder().encode(metadata)
+          .mapError { error in
+            .failedToEncodeMetadata(error)
+          }
+          .map { encodedMetadata in
+            var data = data
+
+            // A tag representing the type of the next metadata entry. For now
+            // it's just '0' meaning 'end'. This is purely to allow for the
+            // format to be extended in the future (e.g. to include resources).
+            // We could of course just keep adding more entries to the JSON,
+            // but certain types of data just don't work well with JSON (e.g.
+            // large amounts of binary data).
+            //
+            // For forwards compatibility, do NOT require this value to be one
+            // you support. Simply stop parsing if you don't understand it.
+            writeBigEndianUInt64(0, to: &data)
+
+            // The default JSON metadata entry. For now this is the only type
+            // of metadata entry. It would be suffixed with a tag type, however
+            // this is guaranteed to always be the first entry (for backwards
+            // compatibility), and I want to bake that into the format.
+            data.append(contentsOf: encodedMetadata)
+            // The data's length in bytes.
+            writeBigEndianUInt64(UInt64(encodedMetadata.count), to: &data)
+
+            // Magic bytes so that apps (and external tools) can know if they
+            // contain any Swift Bundler metadata. Since it's technically
+            // possible for false positives to occur, apps and tools should
+            // always fail safely if the metadata is malformed.
+            data.append(contentsOf: magicBytes)
+
+            return data
+          }
+      }
+      .andThen { (modifiedData: Data) in
+        modifiedData.write(to: executableFile)
+          .mapError { error in
+            .failedToWriteExecutableFile(executableFile, error)
+          }
+      }
+  }
+
+  /// Writes a single UInt64 value to the end of a data buffer (in big endian
+  /// order).
+  private static func writeBigEndianUInt64(_ value: UInt64, to data: inout Data) {
+    let count = MemoryLayout<UInt64>.size
+    withUnsafePointer(to: value.bigEndian) { pointer in
+      pointer.withMemoryRebound(to: UInt8.self, capacity: count) { pointer in
+        data.append(pointer, count: count)
+      }
+    }
+  }
+}

Diff for: Sources/swift-bundler/Bundler/MetadataInserterError.swift

@@ -0,0 +1,8 @@
+import Foundation
+
+/// An error returned by ``MetadataInserter``.
+enum MetadataInserterError: LocalizedError {
+  case failedToReadExecutableFile(URL, any Error)
+  case failedToEncodeMetadata(any Error)
+  case failedToWriteExecutableFile(URL, any Error)
+}

Diff for: Sources/swift-bundler/Commands/BundleCommand.swift

@@ -246,7 +246,6 @@ struct BundleCommand: AsyncCommand {
         try arguments.productsDirectory
         ?? SwiftPackageManager.getProductsDirectory(buildContext).unwrap()
 
-      // Create bundle job
       let bundlerContext = BundlerContext(
         appName: appName,
         packageName: manifest.displayName,
@@ -282,6 +281,14 @@ struct BundleCommand: AsyncCommand {
         try build().unwrap()
       }
 
+      // TODO: Insert when moving to the bundle directory, perhaps via a method
+      //   on some sort of BuildProducts struct. Otherwise we end up adding
+      //   metadata multiple times if the user uses `--skip-build`, which is
+      //   harmless, but janky.
+      let executable = productsDirectory.appendingPathComponent("\(appName)")
+      let metadata = MetadataInserter.metadata(for: appConfiguration)
+      try MetadataInserter.insert(metadata, into: executable).unwrap()
+
       try Self.removeExistingOutputs(outputDirectory: outputDirectory).unwrap()
       return try Self.bundle(
         with: arguments.bundler.bundler,

Diff for: Sources/swift-bundler/Extensions/JSONEncoder.swift

@@ -0,0 +1,10 @@
+import Foundation
+
+extension JSONEncoder {
+  /// Attempts to encode the given value as JSON, returning a result.
+  func encode<T: Encodable>(_ value: T) -> Result<Data, any Error> {
+    Result {
+      try encode(value)
+    }
+  }
+}