Fix SPM dependency linking and Xcode multi-scheme selection (#69, #70)

SPM: After swift build, archive each dependency target's .o files into
lib<Dep>.a and pass -L <binPath> -l<Dep> so the bridge dylib can link
against sibling targets and cross-package dependencies. SPM doesn't
create static archives or emit autolink hints for library targets, so
the build system has to stage them explicitly.

Xcode: Add optional `scheme` parameter threaded from MCP tool schemas
and CLI options through BuildSystemDetector into XcodeBuildSystem.
When set, pickScheme() validates it against the project's scheme list.
When unset, existing heuristics apply (single scheme auto-pick, then
path-component matching). Ambiguous-target error now names the `scheme`
parameter instead of suggesting `projectRoot`.

Adds ToDoExtras (sibling target) and LocalDep (cross-package path dep)
to the SPM example. The existing Tier 2 test now exercises dependency
linking as a regression guard.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: obj-p

Sources/PreviewsCLI/BuildHelpers.swift

@@ -10,11 +10,12 @@ func detectAndBuild(
     for fileURL: URL,
     projectRoot projectRootURL: URL?,
     platform: PreviewPlatform,
+    scheme: String? = nil,
     logPrefix: String = ""
 ) async throws -> BuildContext? {
     guard
         let buildSystem = try await BuildSystemDetector.detect(
-            for: fileURL, projectRoot: projectRootURL
+            for: fileURL, projectRoot: projectRootURL, scheme: scheme
         )
     else {
         return nil

Sources/PreviewsCLI/MCPServer.swift

@@ -136,6 +136,12 @@ func configureMCPServer() async throws -> (Server, Compiler) {
                                 "Project root path (auto-detected if omitted). Enables importing project types from SPM packages, Bazel swift_library targets, or Xcode projects (.xcodeproj / .xcworkspace)."
                             ),
                         ]),
+                        "scheme": .object([
+                            "type": .string("string"),
+                            "description": .string(
+                                "Xcode scheme name (only used for .xcodeproj / .xcworkspace projects). Required when the project contains more than one scheme and none of them match the source file's directory."
+                            ),
+                        ]),
                         "colorScheme": .object([
                             "type": .string("string"),
                             "enum": .array([.string("light"), .string("dark")]),
@@ -723,7 +729,14 @@ private func detectBuildContext(
     platform: PreviewPlatform
 ) async throws -> BuildContext? {
     let projectRootURL = extractOptionalString("projectPath", from: params).map { URL(fileURLWithPath: $0) }
-    return try await detectAndBuild(for: fileURL, projectRoot: projectRootURL, platform: platform, logPrefix: "MCP:")
+    let scheme = extractOptionalString("scheme", from: params)
+    return try await detectAndBuild(
+        for: fileURL,
+        projectRoot: projectRootURL,
+        platform: platform,
+        scheme: scheme,
+        logPrefix: "MCP:"
+    )
 }
 
 private func handleSimulatorList() async throws -> CallTool.Result {

Sources/PreviewsCLI/RunCommand.swift

@@ -27,6 +27,12 @@ struct RunCommand: ParsableCommand {
     @Option(name: .long, help: "Project root path (auto-detected if omitted)")
     var project: String?
 
+    @Option(
+        name: .long,
+        help: "Xcode scheme name (only for .xcodeproj / .xcworkspace projects with multiple schemes)"
+    )
+    var scheme: String?
+
     @Option(name: .long, help: "Simulator device UDID (for ios; auto-selects if omitted)")
     var device: String?
 
@@ -64,13 +70,17 @@ struct RunCommand: ParsableCommand {
         let windowWidth = width
         let windowHeight = height
         let projectPath = project
+        let schemeName = scheme
         let traits = PreviewTraits(colorScheme: colorScheme, dynamicTypeSize: dynamicTypeSize)
 
         Task {
             do {
                 let projectRootURL = projectPath.map { URL(fileURLWithPath: $0) }
                 let buildContext = try await detectAndBuild(
-                    for: fileURL, projectRoot: projectRootURL, platform: .macOS)
+                    for: fileURL,
+                    projectRoot: projectRootURL,
+                    platform: .macOS,
+                    scheme: schemeName)
 
                 try await launchMacOSPreview(
                     fileURL: fileURL,
@@ -92,14 +102,18 @@ struct RunCommand: ParsableCommand {
         let previewIndex = preview
         let deviceUDID = device
         let projectPath = project
+        let schemeName = scheme
         let traits = PreviewTraits(colorScheme: colorScheme, dynamicTypeSize: dynamicTypeSize)
         let isHeadless = headless
 
         Task {
             do {
                 let projectRootURL = projectPath.map { URL(fileURLWithPath: $0) }
                 let buildContext = try await detectAndBuild(
-                    for: fileURL, projectRoot: projectRootURL, platform: .iOS)
+                    for: fileURL,
+                    projectRoot: projectRootURL,
+                    platform: .iOS,
+                    scheme: schemeName)
 
                 try await launchIOSPreview(
                     fileURL: fileURL,

Sources/PreviewsCLI/SnapshotCommand.swift

@@ -32,6 +32,12 @@ struct SnapshotCommand: ParsableCommand {
     @Option(name: .long, help: "Project root path (auto-detected if omitted)")
     var project: String?
 
+    @Option(
+        name: .long,
+        help: "Xcode scheme name (only for .xcodeproj / .xcworkspace projects with multiple schemes)"
+    )
+    var scheme: String?
+
     @Option(name: .long, help: "Simulator device UDID (for ios; auto-selects if omitted)")
     var device: String?
 
@@ -67,6 +73,7 @@ struct SnapshotCommand: ParsableCommand {
         let windowHeight = height
         let outputURL = URL(fileURLWithPath: output)
         let projectPath = project
+        let schemeName = scheme
         let traits = PreviewTraits(colorScheme: colorScheme, dynamicTypeSize: dynamicTypeSize)
 
         Task {
@@ -75,7 +82,11 @@ struct SnapshotCommand: ParsableCommand {
 
                 // Detect build system
                 let projectRootURL = projectPath.map { URL(fileURLWithPath: $0) }
-                let buildContext = try await detectAndBuild(for: fileURL, projectRoot: projectRootURL, platform: .macOS)
+                let buildContext = try await detectAndBuild(
+                    for: fileURL,
+                    projectRoot: projectRootURL,
+                    platform: .macOS,
+                    scheme: schemeName)
 
                 let session = PreviewSession(
                     sourceFile: fileURL,
@@ -134,6 +145,7 @@ struct SnapshotCommand: ParsableCommand {
         let outputURL = URL(fileURLWithPath: output)
         let deviceUDID = device
         let projectPath = project
+        let schemeName = scheme
         let traits = PreviewTraits(colorScheme: colorScheme, dynamicTypeSize: dynamicTypeSize)
 
         Task {
@@ -148,7 +160,10 @@ struct SnapshotCommand: ParsableCommand {
                 // Detect build system
                 let projectRootURL = projectPath.map { URL(fileURLWithPath: $0) }
                 let buildContext = try await detectAndBuild(
-                    for: fileURL, projectRoot: projectRootURL, platform: .iOS)
+                    for: fileURL,
+                    projectRoot: projectRootURL,
+                    platform: .iOS,
+                    scheme: schemeName)
 
                 let session = IOSPreviewSession(
                     sourceFile: fileURL,

Sources/PreviewsCore/BuildSystem.swift

@@ -20,7 +20,13 @@ public enum BuildSystemDetector {
     /// - Parameters:
     ///   - sourceFile: The Swift source file to detect the build system for.
     ///   - projectRoot: If provided, use this as the project root instead of auto-detecting.
-    public static func detect(for sourceFile: URL, projectRoot: URL? = nil) async throws -> (any BuildSystem)? {
+    ///   - scheme: Optional Xcode scheme name. Only used when the detected build
+    ///     system is `XcodeBuildSystem`; ignored for SPM and Bazel.
+    public static func detect(
+        for sourceFile: URL,
+        projectRoot: URL? = nil,
+        scheme: String? = nil
+    ) async throws -> (any BuildSystem)? {
         // If an explicit project root is provided, detect which build system applies there
         if let projectRoot = projectRoot {
             let fm = FileManager.default
@@ -43,7 +49,10 @@ public enum BuildSystemDetector {
             // Xcode: enumerate directory for *.xcworkspace / *.xcodeproj (name varies)
             if let projectFile = XcodeBuildSystem.findXcodeProject(in: projectRoot) {
                 return XcodeBuildSystem(
-                    projectRoot: projectRoot, sourceFile: sourceFile, projectFile: projectFile)
+                    projectRoot: projectRoot,
+                    sourceFile: sourceFile,
+                    projectFile: projectFile,
+                    requestedScheme: scheme)
             }
             return nil
         }
@@ -56,7 +65,7 @@ public enum BuildSystemDetector {
             return bazel
         }
         // Xcode (.xcworkspace / .xcodeproj)
-        if let xcode = try await XcodeBuildSystem.detect(for: sourceFile) {
+        if let xcode = try await XcodeBuildSystem.detect(for: sourceFile, scheme: scheme) {
             return xcode
         }
         return nil
@@ -69,6 +78,7 @@ public enum BuildSystemError: Error, LocalizedError {
     case targetNotFound(sourceFile: String, project: String)
     case missingArtifacts(String)
     case ambiguousTarget(sourceFile: String, candidates: [String])
+    case unknownScheme(requested: String, candidates: [String])
 
     public var errorDescription: String? {
         switch self {
@@ -80,7 +90,10 @@ public enum BuildSystemError: Error, LocalizedError {
             return "Build artifacts not found: \(msg)"
         case .ambiguousTarget(let file, let candidates):
             return
-                "Multiple schemes found for \(file). Use projectRoot to disambiguate. Available schemes: \(candidates.joined(separator: ", "))"
+                "Multiple schemes found for \(file) and none matched the source file's directory. Pass the `scheme` parameter to pick one. Available schemes: \(candidates.joined(separator: ", "))"
+        case .unknownScheme(let requested, let candidates):
+            return
+                "Scheme '\(requested)' not found in project. Available schemes: \(candidates.joined(separator: ", "))"
         }
     }
 }

Sources/PreviewsCore/SPMBuildSystem.swift

@@ -61,10 +61,30 @@ public actor SPMBuildSystem: BuildSystem {
             )
         }
 
-        // 6. Build compiler flags
+        // 6. Archive dependency targets into libDep.a files.
+        //    SPM leaves library targets as loose .o files under <Dep>.build/ instead
+        //    of creating .a archives, and .swiftmodule files don't carry autolink
+        //    hints (no -module-link-name), so we have to make the archives ourselves
+        //    and pass -l<Dep> explicitly below.
+        let dependencyLibs = try await archiveDependencyTargets(
+            binPath: binPath,
+            consumerTargetName: targetName
+        )
+
+        // 7. Build compiler flags
+        //    -I <Modules>   resolves dependency .swiftmodule files at compile time
+        //    -L <binPath>   library search path for the archives created above
+        //    -l<Dep>        per-dependency archive (lazy archive linking means only
+        //                   object files actually referenced get pulled in)
         var flags: [String] = [
             "-I", modulesDir.path,
         ]
+        if !dependencyLibs.isEmpty {
+            flags += ["-L", binPath.path]
+            for dep in dependencyLibs {
+                flags += ["-l\(dep)"]
+            }
+        }
 
         // Add C module include paths for targets with C shims
         let targetBuildDir = binPath.appendingPathComponent("\(targetName).build")
@@ -73,7 +93,7 @@ public actor SPMBuildSystem: BuildSystem {
             flags += ["-I", includeDir.path]
         }
 
-        // 7. Collect Tier 2 data: other source files in the target
+        // 8. Collect Tier 2 data: other source files in the target
         let otherSourceFiles = try collectSourceFiles(
             targetName: targetName,
             in: description
@@ -157,6 +177,104 @@ public actor SPMBuildSystem: BuildSystem {
         return URL(fileURLWithPath: output)
     }
 
+    // MARK: - Private: Dependency Archives
+
+    /// Archive every non-consumer target's `.o` files into `<binPath>/lib<Target>.a`
+    /// and return the list of target names (for use with `-l<Target>`).
+    ///
+    /// SPM's `swift build` produces loose object files under `<binPath>/<Target>.build/`
+    /// for each library target without creating a static archive, and doesn't emit
+    /// autolink hints for them either. So the bridge compile can't discover or link
+    /// dependency symbols on its own — we have to stage the archives ourselves.
+    ///
+    /// Consumer target `.build/` is skipped because Tier 2 already recompiles its
+    /// sources directly. All other sibling targets (and transitively-built external
+    /// packages, which land in the same bin path) are archived.
+    private func archiveDependencyTargets(
+        binPath: URL,
+        consumerTargetName: String
+    ) async throws -> [String] {
+        let fm = FileManager.default
+        guard
+            let entries = try? fm.contentsOfDirectory(
+                at: binPath,
+                includingPropertiesForKeys: [.isDirectoryKey],
+                options: [.skipsHiddenFiles]
+            )
+        else {
+            return []
+        }
+
+        let arPath = try await Self.resolvedArPath()
+        var libs: [String] = []
+
+        for entry in entries {
+            // We want `<binPath>/<Target>.build/` directories.
+            let name = entry.lastPathComponent
+            guard name.hasSuffix(".build") else { continue }
+            var isDir: ObjCBool = false
+            guard fm.fileExists(atPath: entry.path, isDirectory: &isDir), isDir.boolValue else {
+                continue
+            }
+
+            let targetName = String(name.dropLast(".build".count))
+            // Skip the consumer target — Tier 2 compiles its sources directly, and
+            // archiving them here would cause duplicate-symbol errors at link time.
+            if targetName == consumerTargetName { continue }
+            // Skip SPM's own plugin/support bundles if any.
+            if targetName.hasPrefix("_") { continue }
+
+            // Collect .o files produced for this target.
+            let objectFiles = collectObjectFiles(in: entry)
+            guard !objectFiles.isEmpty else { continue }
+
+            let archivePath = binPath.appendingPathComponent("lib\(targetName).a")
+            // `ar rcs` replaces any existing archive, so rebuilds stay consistent.
+            try? fm.removeItem(at: archivePath)
+
+            var arArgs = ["rcs", archivePath.path]
+            arArgs.append(contentsOf: objectFiles.map(\.path))
+            let result = try await runAsync(arPath, arguments: arArgs)
+            guard result.exitCode == 0 else {
+                throw BuildSystemError.buildFailed(
+                    stderr: "ar failed for \(targetName): \(result.stderr)",
+                    exitCode: result.exitCode
+                )
+            }
+            libs.append(targetName)
+        }
+
+        return libs
+    }
+
+    /// Recursively collect `.o` files under a target's build directory, including
+    /// files named `Foo.swift.o` that swift build emits for Swift sources.
+    private func collectObjectFiles(in directory: URL) -> [URL] {
+        guard
+            let enumerator = FileManager.default.enumerator(
+                at: directory,
+                includingPropertiesForKeys: nil,
+                options: [.skipsHiddenFiles]
+            )
+        else {
+            return []
+        }
+        var files: [URL] = []
+        for case let url as URL in enumerator where url.pathExtension == "o" {
+            files.append(url)
+        }
+        return files
+    }
+
+    private static func resolvedArPath() async throws -> String {
+        let output = try await runAsync(
+            "/usr/bin/xcrun", arguments: ["--find", "ar"], discardStderr: true)
+        guard output.exitCode == 0 else {
+            throw BuildSystemError.missingArtifacts("Could not locate `ar` via xcrun")
+        }
+        return output.stdout
+    }
+
     // MARK: - Private: Source Files (Tier 2)
 
     /// Collect all .swift source files in the target EXCEPT the preview file.