agentic-team-templates 0.13.1 → 0.14.0

package/templates/swift-expert/.cursorrules/swiftui.md

@@ -0,0 +1,260 @@
+# SwiftUI
+
+Declarative UI with composable views, state management, and the observation framework.
+
+## View Fundamentals
+
+```swift
+struct UserProfileView: View {
+    let user: User
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 12) {
+            AsyncImage(url: user.avatarURL) { image in
+                image.resizable().scaledToFill()
+            } placeholder: {
+                ProgressView()
+            }
+            .frame(width: 80, height: 80)
+            .clipShape(Circle())
+
+            Text(user.name)
+                .font(.title2)
+                .fontWeight(.bold)
+
+            Text(user.bio)
+                .font(.body)
+                .foregroundStyle(.secondary)
+        }
+        .padding()
+    }
+}
+```
+
+## State Management
+
+```swift
+// @State — view-local mutable state (value types)
+struct CounterView: View {
+    @State private var count = 0
+
+    var body: some View {
+        Button("Count: \(count)") { count += 1 }
+    }
+}
+
+// @Binding — two-way connection to parent's state
+struct ToggleRow: View {
+    let title: String
+    @Binding var isOn: Bool
+
+    var body: some View {
+        Toggle(title, isOn: $isOn)
+    }
+}
+
+// @StateObject — owned reference type (create once)
+struct UserListView: View {
+    @StateObject private var viewModel = UserListViewModel()
+
+    var body: some View {
+        List(viewModel.users) { user in
+            UserRow(user: user)
+        }
+        .task { await viewModel.loadUsers() }
+    }
+}
+
+// @ObservedObject — non-owned reference type (passed in)
+struct UserDetailView: View {
+    @ObservedObject var viewModel: UserDetailViewModel
+    // ...
+}
+
+// @EnvironmentObject — shared dependency via environment
+struct SettingsView: View {
+    @EnvironmentObject var theme: ThemeManager
+    // ...
+}
+```
+
+## Observation Framework (iOS 17+)
+
+```swift
+// @Observable replaces ObservableObject
+@Observable
+class UserViewModel {
+    var users: [User] = []
+    var isLoading = false
+    var error: AppError?
+
+    func loadUsers() async {
+        isLoading = true
+        defer { isLoading = false }
+        do {
+            users = try await userService.fetchAll()
+        } catch {
+            self.error = AppError(error)
+        }
+    }
+}
+
+// No @Published needed. SwiftUI tracks property access automatically
+struct UserListView: View {
+    var viewModel = UserViewModel()
+
+    var body: some View {
+        List(viewModel.users) { user in
+            Text(user.name)
+        }
+        .overlay { if viewModel.isLoading { ProgressView() } }
+        .task { await viewModel.loadUsers() }
+    }
+}
+```
+
+## Navigation
+
+```swift
+// NavigationStack with type-safe routing
+enum Route: Hashable {
+    case userDetail(User)
+    case settings
+    case editProfile
+}
+
+struct ContentView: View {
+    @State private var path = NavigationPath()
+
+    var body: some View {
+        NavigationStack(path: $path) {
+            HomeView()
+                .navigationDestination(for: Route.self) { route in
+                    switch route {
+                    case .userDetail(let user):
+                        UserDetailView(user: user)
+                    case .settings:
+                        SettingsView()
+                    case .editProfile:
+                        EditProfileView()
+                    }
+                }
+        }
+    }
+}
+```
+
+## Composition Patterns
+
+```swift
+// Small, composable views
+struct AvatarView: View {
+    let url: URL?
+    var size: CGFloat = 40
+
+    var body: some View {
+        AsyncImage(url: url) { image in
+            image.resizable().scaledToFill()
+        } placeholder: {
+            Image(systemName: "person.circle.fill")
+                .foregroundStyle(.secondary)
+        }
+        .frame(width: size, height: size)
+        .clipShape(Circle())
+    }
+}
+
+// ViewModifier for reusable styling
+struct CardModifier: ViewModifier {
+    func body(content: Content) -> some View {
+        content
+            .padding()
+            .background(.background)
+            .clipShape(RoundedRectangle(cornerRadius: 12))
+            .shadow(radius: 2)
+    }
+}
+
+extension View {
+    func cardStyle() -> some View {
+        modifier(CardModifier())
+    }
+}
+
+// Usage: Text("Hello").cardStyle()
+```
+
+## Lists and Performance
+
+```swift
+// Lazy loading
+struct UserListView: View {
+    let users: [User]
+
+    var body: some View {
+        List {
+            ForEach(users) { user in
+                UserRow(user: user)
+            }
+        }
+        .listStyle(.plain)
+    }
+}
+
+// LazyVStack for custom layouts
+ScrollView {
+    LazyVStack(spacing: 8) {
+        ForEach(items) { item in
+            ItemView(item: item) // Only created when visible
+        }
+    }
+}
+```
+
+## Previews
+
+```swift
+#Preview("User Profile") {
+    UserProfileView(user: .preview)
+        .padding()
+}
+
+#Preview("Loading State") {
+    UserProfileView(user: .preview)
+        .redacted(reason: .placeholder)
+}
+
+// Preview data
+extension User {
+    static var preview: User {
+        User(id: UUID(), name: "Jane Doe", email: "jane@example.com")
+    }
+}
+```
+
+## Anti-Patterns
+
+```swift
+// Never: massive body properties
+var body: some View {
+    // 200 lines of nested views
+}
+// Use: extract subviews as separate structs or computed properties
+
+// Never: business logic in views
+var body: some View {
+    Button("Submit") {
+        let valid = email.contains("@") && password.count >= 8
+        if valid { /* ... */ }
+    }
+}
+// Use: view model with dedicated validation
+
+// Never: @ObservedObject for view-created objects
+@ObservedObject var vm = MyViewModel() // Recreated on every view update!
+// Use: @StateObject for view-owned objects
+
+// Never: ignoring .task lifecycle
+.onAppear { Task { await load() } } // No automatic cancellation
+// Use: .task { await load() } — cancelled when view disappears
+```

package/templates/swift-expert/.cursorrules/testing.md

@@ -0,0 +1,286 @@
+# Swift Testing
+
+XCTest, Swift Testing framework, and UI testing. Test behavior with expressive assertions.
+
+## Framework Stack
+
+| Tool | Purpose |
+|------|---------|
+| Swift Testing | Modern test framework (Swift 5.10+) |
+| XCTest | Traditional test framework |
+| ViewInspector | SwiftUI view testing |
+| XCUITest | UI automation testing |
+| swift-snapshot-testing | Snapshot/screenshot testing |
+| OHHTTPStubs / URLProtocol | Network mocking |
+
+## Swift Testing Framework
+
+```swift
+import Testing
+
+@Suite("UserService")
+struct UserServiceTests {
+    let sut: UserService
+    let mockRepo: MockUserRepository
+
+    init() {
+        mockRepo = MockUserRepository()
+        sut = UserService(repository: mockRepo)
+    }
+
+    @Test("creates user with valid input")
+    func createUserValid() async throws {
+        let request = CreateUserRequest(name: "Alice", email: "alice@test.com")
+
+        let user = try await sut.create(request)
+
+        #expect(user.name == "Alice")
+        #expect(user.email == "alice@test.com")
+        #expect(user.id != UUID())
+    }
+
+    @Test("rejects duplicate email")
+    func rejectsDuplicateEmail() async {
+        mockRepo.existingEmails = ["alice@test.com"]
+        let request = CreateUserRequest(name: "Alice", email: "alice@test.com")
+
+        await #expect(throws: ValidationError.duplicateEmail) {
+            try await sut.create(request)
+        }
+    }
+
+    @Test("validates email format", arguments: [
+        "invalid",
+        "@missing.local",
+        "no-at-sign",
+        "",
+    ])
+    func invalidEmails(email: String) async {
+        let request = CreateUserRequest(name: "Test", email: email)
+
+        await #expect(throws: ValidationError.invalidEmail) {
+            try await sut.create(request)
+        }
+    }
+}
+```
+
+## XCTest (Traditional)
+
+```swift
+final class OrderServiceTests: XCTestCase {
+    private var sut: OrderService!
+    private var mockInventory: MockInventoryClient!
+
+    override func setUp() {
+        super.setUp()
+        mockInventory = MockInventoryClient()
+        sut = OrderService(inventory: mockInventory)
+    }
+
+    override func tearDown() {
+        sut = nil
+        mockInventory = nil
+        super.tearDown()
+    }
+
+    func test_createOrder_withValidItems_succeeds() async throws {
+        // Arrange
+        mockInventory.availableStock = ["SKU-001": 10]
+        let request = CreateOrderRequest(items: [.init(sku: "SKU-001", quantity: 2)])
+
+        // Act
+        let order = try await sut.create(request)
+
+        // Assert
+        XCTAssertEqual(order.items.count, 1)
+        XCTAssertEqual(order.status, .pending)
+        XCTAssertEqual(mockInventory.reserveCalls.count, 1)
+    }
+
+    func test_createOrder_withInsufficientStock_throws() async {
+        mockInventory.availableStock = ["SKU-001": 0]
+        let request = CreateOrderRequest(items: [.init(sku: "SKU-001", quantity: 5)])
+
+        do {
+            _ = try await sut.create(request)
+            XCTFail("Expected OrderError.insufficientStock")
+        } catch let error as OrderError {
+            XCTAssertEqual(error, .insufficientStock("SKU-001"))
+        } catch {
+            XCTFail("Unexpected error: \(error)")
+        }
+    }
+}
+```
+
+## Async Testing
+
+```swift
+// Swift Testing — async is native
+@Test func fetchUsers() async throws {
+    let users = try await sut.fetchAll()
+    #expect(users.count == 3)
+}
+
+// XCTest — async/await support
+func test_fetchUsers() async throws {
+    let users = try await sut.fetchAll()
+    XCTAssertEqual(users.count, 3)
+}
+
+// Testing with timeouts (XCTest)
+func test_longRunningOperation() async throws {
+    let expectation = expectation(description: "completes")
+
+    Task {
+        _ = try await sut.processLargeDataset()
+        expectation.fulfill()
+    }
+
+    await fulfillment(of: [expectation], timeout: 10)
+}
+```
+
+## Mocking with Protocols
+
+```swift
+// Protocol-based dependency
+protocol UserRepository {
+    func findById(_ id: UUID) async throws -> User?
+    func save(_ user: User) async throws -> User
+    func delete(_ id: UUID) async throws
+}
+
+// Mock implementation
+final class MockUserRepository: UserRepository {
+    var users: [UUID: User] = [:]
+    var saveCalls: [User] = []
+    var deleteCalls: [UUID] = []
+    var findByIdError: Error?
+
+    func findById(_ id: UUID) async throws -> User? {
+        if let error = findByIdError { throw error }
+        return users[id]
+    }
+
+    func save(_ user: User) async throws -> User {
+        saveCalls.append(user)
+        users[user.id] = user
+        return user
+    }
+
+    func delete(_ id: UUID) async throws {
+        deleteCalls.append(id)
+        users.removeValue(forKey: id)
+    }
+}
+```
+
+## Network Mocking
+
+```swift
+// URLProtocol-based mock
+class MockURLProtocol: URLProtocol {
+    static var requestHandler: ((URLRequest) throws -> (HTTPURLResponse, Data))?
+
+    override class func canInit(with request: URLRequest) -> Bool { true }
+    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }
+
+    override func startLoading() {
+        guard let handler = Self.requestHandler else {
+            fatalError("requestHandler not set")
+        }
+        do {
+            let (response, data) = try handler(request)
+            client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
+            client?.urlProtocol(self, didLoad: data)
+            client?.urlProtocolDidFinishLoading(self)
+        } catch {
+            client?.urlProtocol(self, didFailWithError: error)
+        }
+    }
+
+    override func stopLoading() {}
+}
+
+// Usage in tests
+func test_fetchUser_decodesResponse() async throws {
+    let userData = try JSONEncoder().encode(User.preview)
+    MockURLProtocol.requestHandler = { request in
+        let response = HTTPURLResponse(url: request.url!, statusCode: 200, httpVersion: nil, headerFields: nil)!
+        return (response, userData)
+    }
+
+    let config = URLSessionConfiguration.ephemeral
+    config.protocolClasses = [MockURLProtocol.self]
+    let session = URLSession(configuration: config)
+    let client = APIClient(session: session)
+
+    let user = try await client.fetchUser(id: UUID())
+    XCTAssertEqual(user.name, "Jane Doe")
+}
+```
+
+## UI Testing
+
+```swift
+final class LoginUITests: XCTestCase {
+    let app = XCUIApplication()
+
+    override func setUp() {
+        super.setUp()
+        continueAfterFailure = false
+        app.launchArguments = ["--uitesting"]
+        app.launch()
+    }
+
+    func test_loginFlow_withValidCredentials() {
+        let emailField = app.textFields["email-field"]
+        emailField.tap()
+        emailField.typeText("user@test.com")
+
+        let passwordField = app.secureTextFields["password-field"]
+        passwordField.tap()
+        passwordField.typeText("password123")
+
+        app.buttons["login-button"].tap()
+
+        XCTAssertTrue(app.staticTexts["welcome-label"].waitForExistence(timeout: 5))
+    }
+}
+```
+
+## Test Naming
+
+```swift
+// XCTest: test_[method]_[condition]_[expected]
+func test_validate_emptyEmail_throwsValidationError()
+func test_create_validRequest_returnsNewUser()
+func test_delete_nonexistentUser_throwsNotFound()
+
+// Swift Testing: descriptive strings
+@Test("validates email format rejects empty string")
+@Test("creates user with all required fields")
+@Test("deletes existing user successfully")
+```
+
+## Anti-Patterns
+
+```swift
+// Never: testing implementation details
+XCTAssertEqual(viewModel.fetchCallCount, 1) // Fragile
+// Test the observable outcome instead
+
+// Never: shared mutable state between tests
+static var sharedDatabase = Database() // Tests affect each other
+// Use: setUp/tearDown for fresh state
+
+// Never: testing with real network calls
+let user = try await realAPIClient.fetchUser(id: uuid) // Flaky
+// Use: protocol mocking or URLProtocol
+
+// Never: sleeping in tests
+try await Task.sleep(for: .seconds(2)) // Slow and flaky
+// Use: expectations with timeouts, or test schedulers
+```