Add --preview and --port option for CLI to easily start a web server

Author: tothambrus11

Package.swift

@@ -37,6 +37,12 @@ let package = Package(
     .package(url: "https://github.com/pavel-trafimuk/Stencil", branch: "master"),
     .package(url: "https://github.com/tid-kijyun/Kanna.git", from: "5.2.2"),
 
+    // Web server for preview:
+    
+    // A server-side Swift web framework.
+    .package(url: "https://github.com/vapor/vapor.git", from: "4.99.3"),
+    // Non-blocking, event-driven networking for Swift. Used for custom executors
+    .package(url: "https://github.com/apple/swift-nio.git", from: "2.65.0"),
   ],
   targets: [
     // Targets are the basic building blocks of a package. A target can define a module or a test suite.
@@ -56,6 +62,9 @@ let package = Package(
         "HyloStandardLibrary",
         .product(name: "FrontEnd", package: "hylo"),
         .product(name: "ArgumentParser", package: "swift-argument-parser"),
+        .product(name: "Vapor", package: "vapor"),
+        .product(name: "NIOCore", package: "swift-nio"),
+        .product(name: "NIOPosix", package: "swift-nio"),
       ],
       path: "Sources/CLI",
       exclude: ["module.md"],

Sources/CLI/CLI.swift

@@ -6,6 +6,8 @@ import FrontEnd
 import HyloStandardLibrary
 import WebsiteGen
 
+// import Vapor
+
 extension DiagnosticSet {
   fileprivate var niceErrorMessage: String {
     return "Diagnostics: \n" + elements.map { " - " + $0.description + "\n" }.joined(by: "")
@@ -211,9 +213,15 @@ public struct CLI: ParsableCommand {
   @Option(name: .shortAndLong, help: "The output path for the HTML files. ")
   var outputPath: String = "./dist"
 
-  @Flag(name: .shortAndLong, help: "Document the standard library. ")
+  @Flag(name: .customShort("s"), help: "Document the standard library. ")
   var documentingStandardLibrary: Bool = false
 
+  @Flag(help: "Start a web server to preview the generated documentation. ")
+  var preview: Bool = false
+
+  @Option(name: .customShort("p"), help: "The port number for the web server. ")
+  var port: Int = 8080
+
   public init() {}
 
   public func run() throws {
@@ -230,5 +238,9 @@ public struct CLI: ParsableCommand {
     })
 
     print("Documentation successfully generated at \(outputPath) in \(duration).")
+
+    guard preview else { return }
+    print("Starting preview server... 🚀")
+    try startWebserverSync(port: port, publicDirectory: URL(fileURLWithPath: outputPath))
   }
 }

Sources/CLI/WebServer.swift

@@ -0,0 +1,48 @@
+import Logging
+import NIOCore
+import NIOPosix
+import Vapor
+
+/// Start a web server asynchronously to serve the files in the given directory.
+func startWebServer(port: Int = 8080, publicDirectory: URL) async throws {
+  var env = Environment(name: "development", arguments: ["vapor"])
+  try LoggingSystem.bootstrap(from: &env)
+
+  let app = try await Application.make(env)
+  app.http.server.configuration.port = port
+  defer { app.shutdown() }
+
+  app.middleware.use(
+    FileMiddleware(
+      publicDirectory: publicDirectory.absoluteURL.path,
+      defaultFile: "index.html"
+    )
+  )
+
+  try await app.execute()
+  try await app.asyncShutdown()
+}
+
+/// Start a web server synchronously to serve the files in the given directory.
+/// 
+/// This function will exit when the user sends a SIGINT signal (Ctrl+C).
+func startWebserverSync(port: Int, publicDirectory: URL) throws {
+  // Set up signal handler for SIGINT (Ctrl+C)
+  let signalSource = DispatchSource.makeSignalSource(signal: SIGINT, queue: .main)
+  signal(SIGINT, SIG_IGN)  // Ignore default handling
+  signalSource.setEventHandler {
+    print("Exiting...")
+    signalSource.cancel()
+    exit(0)
+  }
+  // Start monitoring the signal
+  signalSource.resume()
+
+  // Run the task asynchronously
+  Task {
+    try await startWebServer(port: port, publicDirectory: publicDirectory)
+  }
+
+  // Keep the run loop running
+  RunLoop.main.run()
+}