feat: Add a buildReason property to Saga

This allows you to only do certain work when certain files have changed. For example, only run SwiftTailwind when css or template files were changed.

Author: kevinrenskers

Sources/Saga/BuildReason.swift

@@ -0,0 +1,23 @@
+import SagaPathKit
+
+/// Describes why the current build was triggered.
+public enum BuildReason: Sendable {
+  /// First build when the process starts (cold start).
+  case initial
+
+  /// A non-Swift content/asset file changed during dev mode.
+  case fileChange(Path)
+
+  /// A Swift source file changed, triggering recompilation and relaunch.
+  case recompile(Path)
+
+  /// Returns the path of the file that triggered this build, if any.
+  public func changedFile() -> Path? {
+    switch self {
+    case .initial:
+      return nil
+    case .fileChange(let path), .recompile(let path):
+      return path
+    }
+  }
+}

Sources/Saga/Saga+Build.swift

@@ -82,6 +82,24 @@ extension Saga {
 
     fileIO.log("All done in \(elapsed(from: totalStart))")
   }
+  
+  var recompileReasonPath: Path {
+    rootPath + ".build/saga-recompile-reason"
+  }
+
+  /// Read `.build/saga-recompile-reason` to determine if this launch was triggered by a Swift file change.
+  /// If the file exists, sets ``buildReason`` to `.recompile` and deletes it.
+  func readRecompileReason() {
+    let path = recompileReasonPath
+    guard path.exists, let contents: String = try? path.read(), !contents.isEmpty else { return }
+    buildReason = .recompile(Path(contents))
+    try? path.delete()
+  }
+
+  /// Write `.build/saga-recompile-reason` so the next launch knows which Swift file triggered it.
+  func writeRecompileReason(_ changedPath: String) {
+    try? recompileReasonPath.write(changedPath)
+  }
 
   /// Watch for file changes and rebuild when content changes.
   /// Signals saga-cli via SIGUSR1 if Swift source files change (so it can recompile and relaunch).
@@ -90,15 +108,19 @@ extension Saga {
     let monitor = FolderMonitor(paths: watchPaths, ignoredPatterns: ignoredPatterns) { [weak self] changedPaths in
       guard let self else { return }
 
-      if changedPaths.contains(where: { $0.hasSuffix(".swift") }) {
-        // Swift source changed — signal saga-cli to recompile and relaunch
+      if let swiftFile = changedPaths.first(where: { $0.hasSuffix(".swift") }) {
+        // Swift source changed — write the reason file and signal saga-cli to recompile and relaunch
+        self.writeRecompileReason(swiftFile)
         self.signalParent(SIGUSR1)
         return
       }
 
       Task {
         do {
           try self.reset()
+          if let changedPath = changedPaths.first {
+            self.buildReason = .fileChange(Path(changedPath))
+          }
           try await self.build()
           self.signalParent(SIGUSR2)
         } catch {

Sources/Saga/Saga+Pipeline.swift

@@ -54,9 +54,9 @@ extension Saga {
       output: (try? outputPath.relativePath(from: rootPath))?.string ?? "deploy"
     )
 
-    let configPath = rootPath + ".build/saga-config.json"
     if let data = try? JSONEncoder().encode(config) {
-      try? data.write(to: URL(fileURLWithPath: configPath.string))
+      let configPath = rootPath + ".build/saga-config.json"
+      try? configPath.write(data)
     }
   }
 

Sources/Saga/Saga.swift

@@ -52,6 +52,9 @@ public class Saga: StepBuilder, @unchecked Sendable {
   /// Glob patterns to ignore during file watching in dev mode
   var ignoredPatterns: [String] = [".DS_Store"]
 
+  /// Why the current build was triggered.
+  public internal(set) var buildReason: BuildReason = .initial
+
   public init(input: Path, output: Path = "deploy", fileIO: FileIO = .diskAccess, originFilePath: StaticString = #filePath) throws {
     let originFile = Path("\(originFilePath)")
     let rootPath = try fileIO.resolveSwiftPackageFolder(originFile)
@@ -199,6 +202,9 @@ public class Saga: StepBuilder, @unchecked Sendable {
     // Write config file so saga-cli can detect output path for serving
     writeConfigFile()
 
+    // Check if this launch was triggered by a recompile
+    readRecompileReason()
+
     // Run the pipeline
     try await build()