From 815bc97a28b2ce8e1f2392e815b6074376d097de Mon Sep 17 00:00:00 2001
From: Teodor Calin <teodor@vulturelabs.io>
Date: Tue, 16 Jun 2026 11:47:23 +0300
Subject: [PATCH] fix: smoke test product reference, platform floor, and
 runnable quickstart

The "SDK examples smoke test" workflow was red on main. Three genuine
issues, each of which would surface in sequence:

1. The generated smoke Package.swift referenced the dependency product
   as `dependencies: ["Pilot"]`. SwiftPM derives a path-dependency's
   identity from its directory name (`sdk-swift`), not its manifest
   name (`Pilot`), so it errored:
     product 'Pilot' required by package 'smoke' target 'smoke' not found.
   Fixed to `.product(name: "Pilot", package: "sdk-swift")`.

2. After that, SwiftPM refused to resolve because the smoke executable
   declared no platform floor while Pilot requires macOS 12. Added
   `platforms: [.macOS(.v12)]` to the generated manifest.

3. The README quickstart (which the workflow extracts and runs verbatim)
   used `FileManager`/`Data` without `import Foundation`, and called
   `handshake(peerID: 12345)` / `waitForTrust` against a non-existent
   peer, which fatals at runtime against the registry. Added the
   Foundation import and made the quickstart a self-contained loopback
   example (start -> identity -> health -> stop) that matches the
   workflow's documented intent, with the peer handshake/send/receive
   shown as commented copy-paste guidance.

Verified locally on macOS (Swift 6.3.2) by replaying the workflow's
extraction + package generation: `swift run smoke` now exits 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .github/workflows/sdk-examples-smoke-test.yml |  9 +++++-
 README.md                                     | 28 +++++++++++++------
 2 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/sdk-examples-smoke-test.yml b/.github/workflows/sdk-examples-smoke-test.yml
index 23d75f2..c893767 100644
--- a/.github/workflows/sdk-examples-smoke-test.yml
+++ b/.github/workflows/sdk-examples-smoke-test.yml
@@ -60,8 +60,15 @@ jobs:
           import PackageDescription
           let p = Package(
               name: "smoke",
+              // Pilot's library requires macOS 12; the consuming
+              // executable must declare at least the same floor or
+              // SwiftPM refuses to resolve the dependency.
+              platforms: [.macOS(.v12)],
               dependencies: [.package(path: "$GITHUB_WORKSPACE")],
-              targets: [.executableTarget(name: "smoke", dependencies: ["Pilot"])]
+              // The dependency package's identity is its directory name
+              // ("sdk-swift"), not its manifest name ("Pilot"), so the
+              // product must be referenced with an explicit package:.
+              targets: [.executableTarget(name: "smoke", dependencies: [.product(name: "Pilot", package: "sdk-swift")])]
           )
           PKG
           mkdir -p Sources/smoke
diff --git a/README.md b/README.md
index dbd1166..8eb313e 100644
--- a/README.md
+++ b/README.md
@@ -42,12 +42,14 @@ Requires iOS 14+ or macOS 12+, Swift 5.9+.
 ## Quick start
 
 ```swift
+import Foundation
 import Pilot
 
 let dataDir = FileManager.default
     .urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
     .appendingPathComponent("pilot")
 
+// Start the embedded daemon (no separate process needed).
 let pilot = try Pilot.start(.init(
     dataDir: dataDir,
     socketPath: "p.sock",
@@ -57,15 +59,23 @@ let pilot = try Pilot.start(.init(
 
 print("address=\(pilot.start.address) node_id=\(pilot.start.nodeID)")
 
-try pilot.handshake(peerID: 12345, justification: "hello")
-_ = try pilot.waitForTrust(peerID: 12345, timeoutMs: 30_000)
-try pilot.send(to: "0:0000.0000.AAAA", port: 7777, data: Data("hi".utf8))
-
-Task {
-    while let dg = try? pilot.receive() {
-        print("got \(dg.data.count) bytes from \(dg.srcAddr):\(dg.srcPort)")
-    }
-}
+// Confirm the node is up.
+let health = try pilot.health()
+print("status=\(health["status"] ?? "unknown")")
+
+// To talk to a peer, handshake first, then send once trusted:
+//
+//   try pilot.handshake(peerID: 12345, justification: "hello")
+//   _ = try pilot.waitForTrust(peerID: 12345, timeoutMs: 30_000)
+//   try pilot.send(to: "0:0000.0000.AAAA", port: 7777, data: Data("hi".utf8))
+//
+// And drain inbound datagrams on a background task:
+//
+//   Task {
+//       while let dg = try? pilot.receive() {
+//           print("got \(dg.data.count) bytes from \(dg.srcAddr):\(dg.srcPort)")
+//       }
+//   }
 
 // On shutdown
 try pilot.stop()