Add cursor rules for development / testing

.cursor/rules/swift-development.mdc

@@ -0,0 +1,71 @@
+---
+description: Swift development workflow and language server workarounds
+globs: ["**/*.swift"]
+alwaysApply: true
+---
+
+# SWIFT DEVELOPMENT WORKFLOW
+
+## ⚠️ IMPORTANT: Language Server Issues
+
+**IGNORE ALL LANGUAGE SERVER ERRORS IN SWIFT FILES**
+- The language server reports errors erroneously while code compiles fine
+- Do NOT trust red squiggles or inline error messages
+- Always verify issues using the commands below instead
+
+## Verification Commands
+
+### Check your work systematically:
+1. **Lint & Format** → `dev lint` (or `dev style`) - Checks for linting and stylistic errors
+2. **Build Issues** → `dev build` - Checks for compilation issues
+3. **Test Issues** → `dev test` - Checks for failing tests 
+
+### Available dev commands:
+**See `dev.yml` in project root for complete list of commands and descriptions.**
+
+Key commands for verification:
+- `dev lint` (alias: `dev style`) - Check format & lint issues
+- `dev fix` - Auto-fix formatting and linting issues  
+- `dev build packages` - Build both packages
+- `dev test packages` - Run all tests
+
+## Concurrency Best Practices
+
+### DO: Use actors for thread-safe shared state
+```swift
+actor QueryCache {
+    private var cache: [String: Any] = [:]
+    private var inflightRequests: [String: Any] = [:]
+
+    func loadCached<T>(...) async throws -> T {
+        // Safe concurrent access to shared state
+    }
+}
+```
+
+## Workflow Best Practices
+
+### When you see errors:
+❌ DON'T: Trust language server errors in Xcode/editor
+✅ DO: Run the appropriate dev command to verify
+
+### After making changes:
+- ALWAYS run `dev fix && dev lint` to check your code is formatted and written in our style.
+
+## Example Workflow
+
+```bash
+# Make your Swift changes...
+
+# Fix any auto-fixable issues
+dev fix
+
+# Check for any remaining lint issues
+dev lint
+
+# Verify it compiles
+dev build
+
+# Run tests if needed
+dev test packages
+```

.cursor/rules/swift-test.mdc

@@ -0,0 +1,83 @@
+---
+description: Swift testing best practices and requirements
+globs: ["Tests/**/*.swift"]
+alwaysApply: true
+---
+
+# SWIFT TESTING RULES
+
+## Test Structure Requirements
+
+### DO:
+- Create separate test methods for each test case
+- Use `guard` statements with `XCTFail` for unwrapping optionals
+```swift
+func testSomething() {
+    guard let result = someOptionalValue else {
+        XCTFail("Expected non-nil value")
+        return
+    }
+    XCTAssertEqual(result, expectedValue)
+}
+```
+- Write focused tests that test one thing at a time
+- Use descriptive test method names in the format `test_<methodName>_<withCircumstances>_<shouldExpectation>`
+```
+    func test_canTransition_fromAppleSheetPresentedState_shouldAllowPaymentAuthorizationAndInterruptAndCompleted() 
+    func test_ensureCurrencyNotChanged_withNoInitialCurrency_shouldNotThrow() 
+```
+
+- If a function may throw multiple types of errors, write multiple tests to capture them in isolation
+```
+func throwingFunction() {
+    if someCondition {
+        throw Error.foo
+      } else 
+      throw Error.bar
+  }
+
+  func test_throwingFunction_whenSomeConditionTrue_shouldThrowFoo() {
+    do {
+        _ = try await storefront.createCart()
+        XCTFail("Expected error to be thrown")
+    } catch {
+      guard case let error = Error.foo else {
+        XCTFail("Expected .foo")
+      }
+    }
+  }
+  func test_throwingFunction_whenSomeConditionTrue_shouldThrowBar(){
+    do {
+        _ = try await storefront.createCart()
+        XCTFail("Expected error to be thrown")
+    } catch {
+      guard case let error = Error.foo else {
+        XCTFail("Expected .foo")
+      }
+    }
+  }
+```
+
+## Code Examples
+
+### ✅ CORRECT: Unwrapping optionals
+```swift
+func testSomething() {
+    guard let result = someOptionalValue else {
+        XCTFail("Expected non-nil value")
+        return
+    }
+    XCTAssertEqual(result, expectedValue)
+}
+```
+
+### DON'T:
+- Use typed catches when testing throwing expressions
+- Delete and recreate test files when debugging
+- Add boilerplate comments like "// Given", "// When", "// Then"
+
+## Comments
+
+- Use comments ONLY to explain non-obvious side effects or complex reasoning
+- Keep comments minimal and purposeful
+- Focus on WHY something is done, not WHAT is being done

dev.yml

@@ -30,29 +30,29 @@ check:
 commands:
   lint:
     aliases: [style]
-    desc: Check Format & Lint issues
+    desc: Check format and lint issues across all Swift files using SwiftLint and SwiftFormat
     run: scripts/lint
   fix:
-    desc: Autofix Format & Lint issues
+    desc: Automatically fix format and lint issues where possible
     run: scripts/lint fix
   build:
     subcommands:
       packages:
-        desc: Build the Package
+        desc: Build both ShopifyCheckoutSheetKit and ShopifyAcceleratedCheckouts packages
         run: |
           ./scripts/xcode_run build ShopifyCheckoutSheetKit
           ./scripts/xcode_run build ShopifyAcceleratedCheckouts
       samples:
-        desc: Build the Samples
+        desc: Build all sample applications to verify integration
         run: ./scripts/build_samples
   test:
     subcommands:
       packages:
-        desc: Test the Packages
+        desc: Run all unit and integration tests for the packages
         run: |
           ./scripts/xcode_run test ShopifyCheckoutSheetKit-Package
       samples:
-        desc: Test the Samples
+        desc: Run tests for sample applications
         run: ./scripts/test_samples
 
   apollo:
@@ -68,7 +68,7 @@ commands:
           rover graph introspect https://$DOMAIN/api/$API_VERSION/graphql --header="X-Shopify-Storefront-Access-Token: $TOKEN" --output schema.$API_VERSION.graphqls
 
       codegen:
-        desc: Generate Apollo Client
+        desc: Generate Apollo Client models and request functions for sample app
         run: |
           cd ./Samples/ShopifyAcceleratedCheckoutsApp/
           ./apollo-ios-cli generate